@andrian.yablonskyy/thub-agent 1.1.5 → 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
@@ -58,6 +59,9 @@ Key options for `thub run`. **On the Client** names the environment variable the
 | `--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):
@@ -237,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:
@@ -255,7 +302,79 @@ test-sw:
                      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.5",
+  "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.4",
+    "@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 });
 }
@@ -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();
   }
 }