@andrian.yablonskyy/thub-agent 1.1.4 → 1.1.6

package/README.md

@@ -32,6 +32,7 @@ thub key rotate                   # a new key; the old one stops at once (saved
 thub run      [options]        Submit a test job and follow its log
 thub status   <jobId>          Show status; follow log if running, verdict, test counts and artifacts if done
 thub cancel   <jobId>          Cancel a job
+thub power    on|off|reset <jobId> [--delay <sec>] [--port <n>]   Switch the USB power of the Client running your job (owner only)
 thub resources                 List resources and their status
 thub jobs     [--mine] [--state <s>]   List recent jobs (a cli token: only its own; a ci token: all, or its own with --mine)
 thub config   set <key> <value>        Save coordinator URL / key / default user locally
@@ -52,12 +53,15 @@ Key options for `thub run`. **On the Client** names the environment variable the
 | `--command <string>` | **Required.** The task's entry point: a shell command the Client runs (`sh -c`) in the job's work directory, after the downloads. It clones repositories and runs containers itself (see Git and Docker below), with credentials from `--env`. Exit code 0 = PASSED. | `JOB_COMMAND` | `JOB_COMMAND` |
 | `--download-file <url>` | A file the Client downloads before running the command (repeatable, `http(s)`), into the job's `downloads/` directory. | `JOB_DOWNLOAD_FILE`, `JOB_DOWNLOAD_FILE_<n>` (URLs); `THUB_DOWNLOAD_<n>` (local paths) |
 | `--env <vars>` | Environment variables for every command the Client runs for the job (git and `--command`): `NAME=value[,NAME=value]`, repeatable; `--env NAME` alone takes the value from your shell. Any names — none means anything to the Agent or the Client (only `THUB_*`, `JOB_*`, `GIT_TERMINAL_PROMPT`, `GIT_ALLOW_PROTOCOL` are refused). Every value is a secret: it reaches only the Client running the job; the Coordinator masks it and drops it when the job ends. | each `NAME` itself |
-| `--suite <name>` | Passed to the command as `THUB_SUITE`. | `JOB_SUITE` (also `THUB_SUITE`) |
+| `--suite <name>` | Test suite name for the command. | `JOB_SUITE` |
 | `--arg <value>` | Extra argument for the command, as `"$@"` (repeatable). | `JOB_ARG`, `JOB_ARG_<n>` (and `"$@"`) |
 | `--timeout <dur>` | e.g. `30m`, default `30m`. | `JOB_TIMEOUT` (seconds) |
 | `--priority <n>` | 0–100; CI defaults to 50, CLI to 60 so a developer is not starved by a busy pipeline. | `JOB_PRIORITY` |
 | `--meta <key=value>` | Arbitrary metadata stored on the job (repeatable) — CI job ids, git coordinates, anything else worth attaching to the run. | `JOB_META_<KEY>` (also `THUB_META_<KEY>`) |
 | `--dry-run` | Exercise the full pipeline without the Client executing anything for real. | — (the command doesn't run) |
+| `--power-on-start on\|off\|reset` | HW only: switch the Client's USB power ports (uhubctl) before the DUT is prepared; a failure ends the job in `ERROR`. | `JOB_POWER_ON_START` |
+| `--power-on-end on\|off\|reset` | HW only: switch them when the job ends, whatever its verdict. | `JOB_POWER_ON_END` |
+| `--power-reset-delay <sec>` | How long a `reset` keeps the power off, 0–60 s; default `1`. | `JOB_POWER_RESET_DELAY` |
 | `--wait` | Do not detach on job end; exit with the job's verdict code (used in CI). | — (Agent only) |
 | `--detach` | Print the job id and exit immediately. | — (Agent only) |
 | `--json` | Machine-readable output. | — (Agent only) |
@@ -77,6 +81,45 @@ Exit codes make the Agent usable as a CI step:
 | `5` | `thub status <jobId> --json`: the job is still queued or running |
 | `130` | Detached with Ctrl-C (job still running) |
 
+### USB port power (HW)
+
+On a Client with USB power ports (uhubctl, see the main README §8.7), a job can cold-boot its board and switch it off at the end. Its owner can also power-cycle it while it runs, without canceling the job:
+
+```bash
+thub run --type hw --label board:nucleo-f401re \
+  --download-file "$IMAGE_URL" --command './ci/flash-and-test.sh' \
+  --power-on-start reset --power-reset-delay 2 --power-on-end off --wait
+
+thub power reset M-00131                      # every port, 1 s off (the default delay)
+thub power reset M-00131 --port 2 --delay 3   # the Client's second port, 3 s off
+thub power off M-00131
+```
+
+`thub power` works only for your own job, while it's `PREPARING` or `RUNNING`; otherwise the Coordinator says why it refused. The job's log shows each action:
+
+```
+[runner] USB power reset (port 2) requested by alice (thub power)
+[runner] USB power reset: 1-1.4:3 (off 3 s)
+```
+
+### Smart sockets, PDUs and other lab devices
+
+Boards on a smart socket (Shelly, Tasmota, Kasa, Home Assistant) or a PDU outlet are switched by the job itself. Its `--command`, or a script from the repository it clones, calls the device with `curl`, `snmpset` or the device's own CLI, with credentials passed as `--env`. Each Client instance names its bench's device in its environment (e.g. `BENCH_POWER=shelly:10.0.20.11`, set with a systemd drop-in):
+
+```bash
+# inline: Shelly Gen2 off, 2 s, on, then the tests
+thub run --type hw --label board:nucleo-f401re --env SHELLY_PASSWORD \
+  --command 'S="http://$BENCH_IP/rpc/Switch.Set?id=0"
+             curl -fsS --digest -u "admin:$SHELLY_PASSWORD" "$S&on=false" && sleep 2 &&
+             curl -fsS --digest -u "admin:$SHELLY_PASSWORD" "$S&on=true" && ./ci/test.sh' --wait
+
+# from the test repository: ci/run.sh resets the bench's socket or PDU outlet, tests, and always powers it off
+thub run --type hw --env GH_TOKEN --env POWER_PASSWORD \
+  --command 'git clone --depth 1 "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" src && cd src && exec ci/run.sh' --wait
+```
+
+Use `exec` so a canceled job's `SIGTERM` reaches the script's trap. The full `ci/power.sh` and `ci/run.sh` examples (Shelly, Tasmota, Home Assistant, Kasa, APC PDU over SNMP) are in the main README, §8.8, and in the dashboard's Help.
+
 ## Examples
 
 **Run a task** — download the firmware, clone the tests at a tag, flash and test (HW):
@@ -85,8 +128,8 @@ Exit codes make the Agent usable as a CI step:
 export GH_TOKEN=…   # read access to the tests repository
 thub run --type hw --label board:nucleo-f401re \
   --download-file "$IMAGE_URL" --env GH_TOKEN \
-  --command 'git clone --depth 1 --branch v1.4.0 "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" . &&
-             st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/test.sh "$@"' \
+  --command 'git clone --depth 1 --branch v1.4.0 "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" src && cd src &&
+             st-flash --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/test.sh "$@"' \
   --arg --junit --wait
 ```
 
@@ -147,7 +190,7 @@ The Client doesn't clone anything (and doesn't need git itself): the command doe
 ```bash
 export GH_TOKEN=…
 thub run --type sw --env GH_TOKEN,REF=main \
-  --command 'git clone --depth 1 --branch "$REF" "https://x-access-token:$GH_TOKEN@github.com/yourorg/tests.git" . && ./ci/test.sh' --wait
+  --command 'git clone --depth 1 --branch "$REF" "https://x-access-token:$GH_TOKEN@github.com/yourorg/tests.git" src && cd src && ./ci/test.sh' --wait
 ```
 
 For SSH, pass the private key itself as `--env` (base64) and use it via `GIT_SSH_COMMAND` from a file in the job directory, which is deleted with the job (main README, §7.2).
@@ -162,48 +205,53 @@ The Client doesn't pull images or start containers (and doesn't need Docker itse
 export DOCKER_PASSWORD=…
 thub run --type hw \
   --env DOCKER_REGISTRY=registry.lab.local:5000,DOCKER_USER=ci --env DOCKER_PASSWORD \
-  --command 'export DOCKER_CONFIG="$THUB_WORK_DIR/.docker" &&
-             echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" --username "$DOCKER_USER" --password-stdin &&
+  --command 'echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" --username "$DOCKER_USER" --password-stdin &&
              docker pull "$DOCKER_REGISTRY/team/test-runner:1.4"' \
   --wait
 ```
 
-**Run the command inside a container:** `--command` starts on the Client host in the work directory (`$THUB_WORK_DIR`). Clone into it, then start the container mounting it:
+**Run the command inside a container:** `--command` starts on the Client host in the job's directory (`$THUB_WORK_DIR`). Clone into `src/`, then start the container mounting only `src/` (the directory also holds `.docker/`, the job's registry login):
 
 ```bash
 thub run --type sw \
   --env DOCKER_REGISTRY=registry.lab.local:5000,DOCKER_USER=ci --env DOCKER_PASSWORD --env GH_TOKEN \
-  --command 'git clone --depth 1 "https://x-access-token:$GH_TOKEN@github.com/yourorg/web-ui-tests.git" . &&
-             export DOCKER_CONFIG="$THUB_WORK_DIR/.docker" &&
+  --command 'git clone --depth 1 "https://x-access-token:$GH_TOKEN@github.com/yourorg/web-ui-tests.git" src && cd src &&
              echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" --username "$DOCKER_USER" --password-stdin &&
-             docker run --rm -v "$THUB_WORK_DIR:/work" -w /work "$DOCKER_REGISTRY/python:3.14" ./run-tests.sh' \
+             docker run --rm --user "$(id -u):$(id -g)" -v "$THUB_WORK_DIR/src:/work" -w /work "$DOCKER_REGISTRY/python:3.14" ./run-tests.sh' \
   --wait
 ```
 
-**Clone the repository inside the image, with parameters from `--env`:**
+**Clone and test inside a container, with a deploy key and a registry login from `--env`** (the reference example for passing data and secrets to a job):
 
 ```bash
+# In CI, from its secret store — never typed on the command line:
+export THUB_KEY=…                              # a CI token (dashboard → CI tokens)
+export DOCKER_PASSWORD=…                       # the registry password
+export GIT_KEY="$(cat ~/.ssh/thub_deploy)"     # a private deploy key with read access to the repository
+
 thub run --type sw \
-  --env DOCKER_REGISTRY=registry.lab.local:5000,DOCKER_USER=ci --env DOCKER_PASSWORD \
-  --env TEST_IMAGE=registry.lab.local:5000/team/test-runner:1.4 \
-  --env REPO_URL=git@bitbucket.org:yourorg/web-ui-tests.git,REPO_REF=main \
-  --env 'GIT_SSH_COMMAND=ssh -i /root/.ssh/id_ed25519 -o StrictHostKeyChecking=accept-new' \
-  --command 'export DOCKER_CONFIG="$THUB_WORK_DIR/.docker" &&
-             echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" --username "$DOCKER_USER" --password-stdin &&
-             docker run --rm -e REPO_URL -e REPO_REF -e GIT_SSH_COMMAND \
-               -v "$HOME/.ssh:/root/.ssh:ro" -v "$THUB_WORK_DIR/results:/results" \
-               "$TEST_IMAGE" sh -c "git clone --depth 1 --branch \"\$REPO_REF\" \"\$REPO_URL\" /src && cd /src && ./run-tests.sh --junit /results"' \
+  --env DOCKER_REGISTRY=registry.lab:5000,DOCKER_USERNAME=ci-reader \
+  --env DOCKER_PASSWORD --env GIT_KEY \
+  --command 'echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" --username "$DOCKER_USERNAME" --password-stdin &&
+             mkdir -p "$THUB_WORK_DIR/src" &&
+             docker run --rm -e GIT_KEY -e HOME=/tmp --user "$(id -u):$(id -g)" \
+               -v "$THUB_WORK_DIR/src:/work" -w /work --entrypoint sh alpine/git -c "
+               eval \$(ssh-agent -s) > /dev/null &&
+               printf \"%s\n\" \"\$GIT_KEY\" | ssh-add - &&
+               GIT_SSH_COMMAND=\"ssh -o StrictHostKeyChecking=accept-new\" git clone --depth 1 git@bitbucket.org:yourorg/web-ui-tests.git . &&
+               ./run-tests.sh"' \
   --wait
 ```
 
+Plain values go as `--env NAME=value`, secrets as `--env NAME` (taken from your environment, so never on the command line; multi-line values arrive intact). The inner script's `\$` is expanded in the container; `ssh-agent` keeps the key in memory only; `--entrypoint sh` because `alpine/git`'s entrypoint is `git`; `--user` keeps the clone deletable by the Client. Only `src/` is mounted, so the registry login (the Client's `DOCKER_CONFIG`, `$THUB_WORK_DIR/.docker`) stays out of the container. More in the main README, §7.2.
+
 The Client host needs Docker and the Client's user in the `docker` group for these (install Docker before the Client). Add `--dry-run` to see every command a job would run on the Client (every `--env` value shown as `***`) without running any. More in the main README, §7.2.
 
 ## Client environment variables
 
 On the Client, the job's `--command` gets every option above as a `JOB_<NAME>` variable (the **On the Client** column). A variable whose option wasn't given is unset. A repeatable option gives `<NAME>` with all values plus `<NAME>_<n>` for each one. It also gets:
 - its `--env` variables, under their own names;
-- `THUB_JOB_ID`, `THUB_WORK_DIR` (where it runs), `THUB_DOWNLOADS_DIR`, `THUB_DOWNLOADS`, `THUB_DOWNLOAD_<n>` (local paths), `THUB_SUITE` and `THUB_META_<KEY>`;
-- the DUT's `THUB_DUT_UART[_<n>]`, `THUB_DUT_USB[_<n>]`, `THUB_DUT_STLINK[_<n>]` (HW).
+- `THUB_JOB_ID`, `THUB_WORK_DIR` (where it runs), `THUB_DOWNLOADS_DIR`, `THUB_DOWNLOADS`, `THUB_DOWNLOAD_<n>` (local paths) and `THUB_META_<KEY>`. HW devices are used by their `/dev/thub/dut<N>-uart|usb|stlink` paths; no device variables are passed.
 
 `THUB_*` and `JOB_*` names can't be set with `--env`. The full list is in the main README, §7.4.
 
@@ -232,7 +280,11 @@ while thub status "$JOB" --json > job.json; [ $? -eq 5 ]; do sleep 10; done
 jq -r '"\(.state) exit=\(.exit_code) failed=\(.summary.failed // 0)"' job.json   # PASSED exit=0 failed=0
 ```
 
-## GitHub Actions
+## CI/CD: GitHub Actions, GitLab, Bitbucket, Jenkins
+
+Every CI system works the same way: store a CI token (dashboard → CI tokens) as the secret `THUB_KEY`, set `THUB_URL`, and run `thub run … --wait` on a runner with Node.js 24. The step's exit code is the verdict. Set `THUB_NO_SELF_UPDATE=1` on short-lived runners.
+
+### GitHub Actions
 
 ```yaml
 test-sw:
@@ -246,11 +298,83 @@ test-sw:
         npx -y @andrian.yablonskyy/thub-agent run --type sw \
           --download-file "${{ needs.build.outputs.image_url }}" \
           --env GH_TOKEN="${{ secrets.TESTS_READ_TOKEN }}",REPO="$GITHUB_REPOSITORY",SHA="$GITHUB_SHA" \
-          --command 'git init -q . && git fetch -q --depth 1 "https://x-access-token:$GH_TOKEN@github.com/$REPO.git" "$SHA" &&
+          --command 'git init -q src && cd src && git fetch -q --depth 1 "https://x-access-token:$GH_TOKEN@github.com/$REPO.git" "$SHA" &&
                      git checkout -q FETCH_HEAD && ./ci/sw-tests.sh' --suite full --wait
 ```
 
-If the GitHub job is canceled, the runner sends `SIGINT` to the Agent. In `--wait` mode (CI), that's treated as a cancel request (`POST /jobs/:id/cancel`) before exiting, so abandoned CI jobs don't hold hardware. In interactive mode, Ctrl-C only detaches.
+In `--wait` mode, `SIGINT` and `SIGTERM` (how GitHub, GitLab and Jenkins stop a canceled step) make the Agent cancel the job (`POST /jobs/:id/cancel`) before exiting, so abandoned CI jobs don't hold hardware. In interactive mode, Ctrl-C only detaches.
+
+### GitLab CI/CD
+
+```yaml
+test-hw:
+  image: node:24
+  variables: { THUB_URL: https://thub.example.com, THUB_NO_SELF_UPDATE: "1" }   # THUB_KEY: a masked CI/CD variable
+  script:
+    - |
+      npx -y @andrian.yablonskyy/thub-agent run --type hw --label board:nucleo-f401re --download-file "$IMAGE_URL" \
+        --env CI_JOB_TOKEN --env CI_SERVER_HOST --env CI_PROJECT_PATH --env CI_COMMIT_SHA \
+        --command 'git init -q src && cd src &&
+                   git fetch -q --depth 1 "https://gitlab-ci-token:$CI_JOB_TOKEN@$CI_SERVER_HOST/$CI_PROJECT_PATH.git" "$CI_COMMIT_SHA" &&
+                   git checkout -q FETCH_HEAD && ./ci/hw-tests.sh' \
+        --wait --meta pipelineUrl="$CI_PIPELINE_URL"
+```
+
+### Bitbucket Pipelines
+
+```yaml
+- step:
+    name: HW tests
+    image: node:24
+    script:   # repository variables: THUB_URL, THUB_KEY (secured), TESTS_TOKEN (a repository access token)
+      - >-
+        npx -y @andrian.yablonskyy/thub-agent run --type hw --download-file "$IMAGE_URL"
+        --env TESTS_TOKEN --env BITBUCKET_REPO_FULL_NAME --env BITBUCKET_COMMIT
+        --command 'git init -q src && cd src &&
+        git fetch -q --depth 1 "https://x-token-auth:$TESTS_TOKEN@bitbucket.org/$BITBUCKET_REPO_FULL_NAME.git" "$BITBUCKET_COMMIT" &&
+        git checkout -q FETCH_HEAD && ./ci/hw-tests.sh' --wait
+```
+
+### Jenkins
+
+```groovy
+stage('HW tests') {
+  agent { docker { image 'node:24' } }
+  environment {
+    THUB_URL = 'https://thub.example.com'
+    THUB_KEY = credentials('thub-ci-token')          // Secret text
+    NPM_CONFIG_CACHE = "${env.WORKSPACE}/.npm"
+  }
+  steps {
+    sh '''
+      npx -y @andrian.yablonskyy/thub-agent run --type hw --download-file "$IMAGE_URL" \
+        --command './ci/hw-tests.sh' --wait --meta buildUrl="$BUILD_URL"
+    '''
+  }
+}
+```
+
+Full pipelines — build, test, and bringing the JUnit report back into GitLab, Bitbucket or Jenkins — are in the main README, §11, and in the dashboard's Help.
+
+## Artifact storage
+
+`--download-file` is a plain, anonymous GET. For private storage, either pass a short-lived signed URL (`aws s3 presign …`), or fetch the file in `--command` with credentials passed as `--env`. Outputs are uploaded by the command and listed in `$THUB_ARTIFACTS_FILE`:
+
+```bash
+thub run --type sw --env ART_TOKEN \
+  --command './ci/test.sh; rc=$?
+             curl -fsS -H "Authorization: Bearer $ART_TOKEN" -T results/junit.xml "https://artifactory.example.com/qa/$THUB_JOB_ID/junit.xml"
+             exit $rc' --wait
+```
+
+The main README, §7.5, and the dashboard's Help have examples for Artifactory, AWS S3, Google Drive (rclone), FTP/FTPS/SFTP, and custom HTTP authentication (bearer, API key, basic, `.netrc`, mutual TLS, OAuth2).
+
+More authentication how-tos, in the main README and the dashboard's Help:
+
+- **Downloads over HTTPS:** a private CA (`NODE_EXTRA_CA_CERTS` on the Client), and client certificates (`curl --cert` in `--command`; `--download-file` can't present one). See §7.5.
+- **Artifactory:** scoped, short-lived access tokens minted per CI run, the JFrog CLI, and signed URLs. See §7.5.
+- **git over SSH:** a deploy key plus a pinned `known_hosts`, both passed with `--env`. See §7.2.
+- **`docker login`:** your own registry, Artifactory, ghcr, GitLab, Docker Hub, ECR, Google Artifact Registry and ACR. See §7.2.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-agent",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "TestHub Agent CLI — the single entry point CI/CD and developers use to submit and follow test jobs",
   "bin": {
     "thub": "./src/cli.js"
@@ -12,7 +12,7 @@
     "lint:fix": "eslint . --fix"
   },
   "dependencies": {
-    "@andrian.yablonskyy/thub-common": "^1.1.3",
+    "@andrian.yablonskyy/thub-common": "^1.1.5",
     "commander": "^13.1.0"
   },
   "devDependencies": {

package/src/cli.js

@@ -2,7 +2,7 @@
 
 /**
  * @file        packages/agent/src/cli.js
- * @description thub CLI entry point: run/status/cancel/resources/jobs/config commands (README §7)
+ * @description thub CLI entry point: run/status/cancel/power/resources/jobs/config commands (README §7)
  *
  * @author      Andrian Yablonskyy
  * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
@@ -18,7 +18,7 @@
 const { Command, Option } = require('commander'),
   {
     ApiClient, EXIT_CODES, ACTIVE_JOB_STATES, exitCodeForJobState, PACKAGES, fetchLatestVersion, isNewer, isValidVersion, formatDateTime,
-    parseEnvList
+    parseEnvList, POWER_ACTIONS, DEFAULT_RESET_DELAY_SEC, MAX_RESET_DELAY_SEC, powerRequestErrors
   } = require('@andrian.yablonskyy/thub-common'),
   { resolveConnection, writeConfigFile, readConfigFile, CONFIG_PATH } = require('./config'),
   { parseDurationSec } = require('./duration'),
@@ -81,6 +81,34 @@ function taskFromOptions(opts){
   return task;
 }
 
+// --power-on-start / --power-on-end / --power-reset-delay -> the job spec's
+// `power` (README §8.7), checked here so a typo fails before it's sent.
+function powerFromOptions(opts){
+  const power = {};
+  for (const [option, key]of [['powerOnStart', 'onStart'], ['powerOnEnd', 'onEnd']]){
+    if (opts[option] !== undefined){
+      if (!POWER_ACTIONS.includes(opts[option])){
+        throw usageError(`--${option.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)} ${opts[option]}: must be one of ${POWER_ACTIONS.join(', ')}`);
+      }
+      power[key] = opts[option];
+    }
+  }
+  if (opts.powerResetDelay !== undefined){
+    const errors = powerRequestErrors({ action: 'reset', delaySec: opts.powerResetDelay });
+    if (errors.length){
+      throw usageError(`--power-reset-delay: ${errors.join('; ')}`);
+    }
+    if (power.onStart !== 'reset' && power.onEnd !== 'reset'){
+      throw usageError('--power-reset-delay needs --power-on-start reset or --power-on-end reset');
+    }
+    power.resetDelaySec = opts.powerResetDelay;
+  }
+  if (Object.keys(power).length && opts.type !== 'hw'){
+    throw usageError('--power-on-start / --power-on-end are for HW jobs only (--type hw)');
+  }
+  return Object.keys(power).length ? power : null;
+}
+
 function usageError(message){
   return Object.assign(new Error(message), { status: EXIT_CODES.USAGE });
 }
@@ -131,7 +159,7 @@ program
     '--command <string>',
     'The task\'s entry point: a shell command the Client runs (sh -c) in the job\'s work directory, after downloading ' +
       '--download-file files. --arg values arrive as "$@". Anything else the job needs it does itself — e.g. ' +
-      '`git clone "https://x-access-token:$GH_TOKEN@github.com/org/tests.git" . && ./ci/test.sh` or ' +
+      '`git clone "https://x-access-token:$GH_TOKEN@github.com/org/tests.git" src && cd src && ./ci/test.sh` or ' +
       '`docker run --rm "$IMAGE" ./run.sh` — with credentials passed by --env'
   )
   .option(
@@ -150,7 +178,7 @@ program
     collectRepeatable,
     []
   )
-  .option('--suite <name>', 'Test suite name, passed to --command as THUB_SUITE', 'default')
+  .option('--suite <name>', 'Test suite name, passed to --command as JOB_SUITE', 'default')
   .option('--arg <value>', 'Extra argument for --command, as "$@" (repeatable)', collectRepeatable, [])
   .option('--timeout <duration>', 'e.g. 30m, 1h', '30m')
   .option('--priority <n>', 'Priority 0-100', (v) => Number(v))
@@ -170,9 +198,13 @@ program
       'without the Client flashing/running anything for real',
     false
   )
+  .option('--power-on-start <action>', `USB power on the Client (uhubctl) before the DUT is prepared: ${POWER_ACTIONS.join(' | ')} (HW only)`)
+  .option('--power-on-end <action>', `USB power on the Client when the job ends, whatever its verdict: ${POWER_ACTIONS.join(' | ')} (HW only)`)
+  .option('--power-reset-delay <sec>', `Seconds a reset keeps the power off (default ${DEFAULT_RESET_DELAY_SEC}, max ${MAX_RESET_DELAY_SEC})`, (v) => Number(v))
   .action(async (opts) => {
     try {
       const task = taskFromOptions(opts),
+        power = powerFromOptions(opts),
         c = client(),
         labels = requiredLabels(opts),
         meta = Object.fromEntries(opts.meta.map((kv) => kv.split(/=(.*)/s).slice(0, 2))),
@@ -184,7 +216,8 @@ program
           timeoutSec: parseDurationSec(opts.timeout),
           ...(opts.priority !== undefined ? { priority: opts.priority } : {}),
           ...(Object.keys(meta).length ? { meta } : {}),
-          ...(opts.dryRun ? { dryRun: true } : {})
+          ...(opts.dryRun ? { dryRun: true } : {}),
+          ...(power ? { power } : {})
         },
 
         result = await c.post('/jobs', spec);
@@ -267,6 +300,36 @@ program
     }
   });
 
+// README §8.7: the owner of a running job switches its Client's USB power
+// right away — no need to wait for the job to end or to cancel it.
+program
+  .command('power')
+  .description('Switch the USB power of the Client running your job (uhubctl): on, off or reset — while it runs')
+  .argument('<action>', POWER_ACTIONS.join(' | '))
+  .argument('<jobId>')
+  .option('--delay <sec>', `reset: seconds the power stays off (default ${DEFAULT_RESET_DELAY_SEC}, max ${MAX_RESET_DELAY_SEC})`, (v) => Number(v))
+  .option('--port <n>', 'Only this port of the Client: its number in the Client\'s hw-devices.usbPower.ports (default: all of them)', (v) => Number(v))
+  .option('--json', 'Machine-readable output', false)
+  .action(async (action, jobId, opts) => {
+    try {
+      const errors = powerRequestErrors({ action, delaySec: opts.delay, port: opts.port });
+      if (errors.length){
+        throw usageError(errors.join('; ').replace('the reset delay (delaySec)', '--delay').replace(/^port/, '--port'));
+      }
+      const res = await client().post(`/jobs/${jobId}/power`, {
+        action, ...(opts.delay !== undefined ? { delaySec: opts.delay } : {}), ...(opts.port !== undefined ? { port: opts.port } : {})
+      });
+      if (opts.json){
+        return console.log(JSON.stringify(res));
+      }
+      const what = `USB power ${res.action}${res.port ? ` (port ${res.port})` : ''}${res.action === 'reset' ? `, ${res.delaySec} s off` : ''}`;
+      console.log(`${what} sent to ${res.resource.name} for job ${res.jobId} — the job's log shows when it's done.`);
+    }
+    catch (err){
+      fail(err);
+    }
+  });
+
 program
   .command('resources')
   .description('List resources and their status')

package/src/streaming.js

@@ -21,7 +21,9 @@ const { exitCodeForJobState, EXIT_CODES } = require('@andrian.yablonskyy/thub-co
  * last seen `seq` on network drops (§7).
  *
  * In --wait mode (used by CI, §11) Ctrl-C/SIGINT is treated as a cancel
- * request; otherwise it only detaches and the job keeps running.
+ * request — and so is SIGTERM, which is how GitLab CI, Jenkins and most CI
+ * runners stop a canceled step; otherwise it only detaches and the job
+ * keeps running (SIGTERM then just ends the Agent, as before).
  */
 async function followJob(client, jobId, { fromSeq = 0, waitMode = false, print = console.log } = {}){
   let lastEventId = fromSeq,
@@ -60,6 +62,9 @@ async function followJob(client, jobId, { fromSeq = 0, waitMode = false, print =
   });
 
   process.on('SIGINT', onSigint);
+  if (waitMode){
+    process.on('SIGTERM', onSigint);
+  }
 
   (async () => {
     while (!finished){
@@ -107,6 +112,7 @@ async function followJob(client, jobId, { fromSeq = 0, waitMode = false, print =
   }
   finally {
     process.off('SIGINT', onSigint);
+    process.off('SIGTERM', onSigint);
     controller.abort();
   }
 }