From 88e4370572333975613fa071c16e6f28414f1731 Mon Sep 17 00:00:00 2001
From: Markus Staab <markus.staab@redaxo.de>
Date: Thu, 21 May 2026 10:55:16 +0200
Subject: [PATCH] ENV vars and secrets have scalar values, and a string name

---
 docs/api.md             | 8 ++++----
 src/Ssh/RunParams.php   | 7 +++++++
 src/Support/helpers.php | 4 ++++
 src/functions.php       | 8 ++++----
 4 files changed, 19 insertions(+), 8 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index f8816877a..b2abb3101 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -382,8 +382,8 @@ run('echo \{{not_replaced}}'); // outputs: {{not_replaced}}
 | `$cwd` | `string` or `null` | Working directory for this run. Defaults to `{{working_path}}` (set by `cd()`). |
 | `$timeout` | `int` or `null` | Max runtime in seconds (default: `{{default_timeout}}`, 300; `null` disables). |
 | `$idleTimeout` | `int` or `null` | Max seconds without output before aborting. |
-| `$secrets` | `array` or `null` | Map of `%name%` placeholders to redacted values. |
-| `$env` | `array` or `null` | Environment variables: `run('echo $KEY', env: ['KEY' => 'value']);` |
+| `$secrets` | `array<string, scalar>` or `null` | Map of `%name%` placeholders to redacted values. |
+| `$env` | `array<string, scalar>` or `null` | Environment variables: `run('echo $KEY', env: ['KEY' => 'value']);` |
 | `$forceOutput` | `bool` or `null` | Print command output in real time. |
 | `$nothrow` | `bool` or `null` | Return output instead of throwing on non-zero exit. |
 
@@ -420,8 +420,8 @@ runLocally('npm run build', timeout: 600);
 | `$cwd` | `string` or `null` | Working directory for this run. Defaults to `{{working_path}}`. |
 | `$timeout` | `int` or `null` | Max runtime in seconds (default 300, `null` disables). |
 | `$idleTimeout` | `int` or `null` | Max seconds without output before aborting. |
-| `$secrets` | `array` or `null` | Map of `%name%` placeholders to redacted values. |
-| `$env` | `array` or `null` | Environment variables: `runLocally('echo $KEY', env: ['KEY' => 'value']);` |
+| `$secrets` | `array<string, scalar>` or `null` | Map of `%name%` placeholders to redacted values. |
+| `$env` | `array<string, scalar>` or `null` | Environment variables: `runLocally('echo $KEY', env: ['KEY' => 'value']);` |
 | `$forceOutput` | `bool` or `null` | Print command output in real time. |
 | `$nothrow` | `bool` or `null` | Return output instead of throwing on non-zero exit. |
 | `$shell` | `string` or `null` | Shell to run in. Default `bash -s`. |
diff --git a/src/Ssh/RunParams.php b/src/Ssh/RunParams.php
index a3d2af3bb..1cd2602f9 100644
--- a/src/Ssh/RunParams.php
+++ b/src/Ssh/RunParams.php
@@ -4,6 +4,10 @@
 
 class RunParams
 {
+    /**
+     * @param array<string, scalar>|null $env
+     * @param array<string, scalar>|null $secrets
+     */
     public function __construct(
         public ?string  $shell = null,
         public ?string $cwd = null,
@@ -18,6 +22,9 @@ public function __construct(
         public ?array  $secrets = null,
     ) {}
 
+    /**
+     * @param array<string, scalar>|null $secrets
+     */
     public function with(
         #[\SensitiveParameter]
         ?array $secrets = null,
diff --git a/src/Support/helpers.php b/src/Support/helpers.php
index 52adf88a6..9ee3c5c73 100644
--- a/src/Support/helpers.php
+++ b/src/Support/helpers.php
@@ -67,6 +67,10 @@ function ($key, $value) {
     ));
 }
 
+/**
+ * @param array<string, scalar>|null $secrets
+ * @return string
+ */
 function replace_secrets(string $command, ?array $secrets): string
 {
     if (!empty($secrets)) {
diff --git a/src/functions.php b/src/functions.php
index d7be42887..22f69fd30 100644
--- a/src/functions.php
+++ b/src/functions.php
@@ -495,8 +495,8 @@ function within(string $path, callable $callback): mixed
  * @param string|null $cwd Working directory for this run. Defaults to `{{working_path}}` (set by `cd()`).
  * @param int|null $timeout Max runtime in seconds (default: `{{default_timeout}}`, 300; `null` disables).
  * @param int|null $idleTimeout Max seconds without output before aborting.
- * @param array|null $secrets Map of `%name%` placeholders to redacted values.
- * @param array|null $env Environment variables: `run('echo $KEY', env: ['KEY' => 'value']);`
+ * @param array<string, scalar>|null $secrets Map of `%name%` placeholders to redacted values.
+ * @param array<string, scalar>|null $env Environment variables: `run('echo $KEY', env: ['KEY' => 'value']);`
  * @param bool|null $forceOutput Print command output in real time.
  * @param bool|null $nothrow Return output instead of throwing on non-zero exit.
  * @throws RunException
@@ -581,8 +581,8 @@ function run(
  * @param string|null $cwd Working directory for this run. Defaults to `{{working_path}}`.
  * @param int|null $timeout Max runtime in seconds (default 300, `null` disables).
  * @param int|null $idleTimeout Max seconds without output before aborting.
- * @param array|null $secrets Map of `%name%` placeholders to redacted values.
- * @param array|null $env Environment variables: `runLocally('echo $KEY', env: ['KEY' => 'value']);`
+ * @param array<string, scalar>|null $secrets Map of `%name%` placeholders to redacted values.
+ * @param array<string, scalar>|null $env Environment variables: `runLocally('echo $KEY', env: ['KEY' => 'value']);`
  * @param bool|null $forceOutput Print command output in real time.
  * @param bool|null $nothrow Return output instead of throwing on non-zero exit.
  * @param string|null $shell Shell to run in. Default `bash -s`.