@andrian.yablonskyy/thub-agent 1.0.27 → 1.0.29

package/README.md

@@ -52,11 +52,11 @@ Key options for `thub run`:
 | `--user <name>` | Free-text job owner — a label, not an identity. Falls back to `THUB_USER` / `thub config set user <name>`. |
 | `--command <string>` | **Required.** The task's entry point: a shell command the Client runs (`sh -c`) in the task's work directory — the `--git-repo` checkout, else an empty directory — after preparing its inputs. Its exit code is the verdict. On HW it flashes the board itself (the Client doesn't); it gets `THUB_DUT_STLINK`/`_UART`/`_USB`/`_HOST`/`_CONTAINER`, `THUB_DOWNLOAD_<n>`, `THUB_DOWNLOADS_DIR`, `THUB_GIT_COMMIT`, `THUB_SUITE`, `THUB_META_*`. |
 | `--download-file <url>` | A file the Client downloads before running the command (repeatable, `http(s)`), into the job's `downloads/` directory. |
-| `--docker-image <name>` | SW only: a Docker image the Client runs as the DUT instead of its own `sw.image` (the Client must allow it: `sw.allowJobImages`). |
+| `--docker-image <name>` | SW only: a Docker image the Client runs as the **DUT** (an emulator the tests talk to, at `$THUB_DUT_HOST` / `$THUB_DUT_CONTAINER`) — any SW Client runs it; without one, an SW job has no DUT container. It's not where `--command` runs: to run the tests in an image, see [Docker](#docker). |
 | `--git-repo <url> [<branch>\|<tag>\|<commit>]` | A git repository the Client clones (default ref: the default branch); the command runs in the checkout. |
 | `--depth <n>` | With `--git-repo`: commits to fetch, default `1`; `0` = full history. |
 | `--git-options <string>` | With `--git-repo`: extra git options placed between `git` and its subcommand on the Client, e.g. `'-c core.sshCommand="ssh -i ~/.ssh/lab_key -p 2222"'`. Shell-quoted (no shell run). Stored with the job, so reference key files rather than inlining secrets. |
-| `--env <vars>` | Environment variables for every command the Client runs for the job (git, docker login, `--command`): `NAME=value[,NAME=value]`, repeatable; `--env NAME` alone takes the value from your shell. `DOCKER_REGISTRY` + `DOCKER_USERNAME` + `DOCKER_PASSWORD`: the Client logs in to that registry first (`docker login … --password-stdin`). Values reach only the Client running the job; the Coordinator masks them and drops them when the job ends. |
+| `--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_*`, `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. |
 | `--suite <name>` | Passed to the command as `THUB_SUITE`. |
 | `--arg <value>` | Extra argument for the command, as `"$@"` (repeatable). |
 | `--timeout <dur>` | e.g. `30m`, default `30m`. |
@@ -68,7 +68,7 @@ Key options for `thub run`:
 | `--json` | Machine-readable output. |
 
 - `thub run` prints the **job ID**, then streams logs until Ctrl-C. Ctrl-C detaches; the job keeps running on the Client.
-- `thub status <jobId>` prints the current state; if active it keeps streaming, if done it prints the verdict and artifact download links.
+- `thub status <jobId>` prints the current state; if active it keeps streaming, if done it prints the verdict and artifact download links. `--json` prints the job once and never follows it (see [Job status and PASS/FAIL](#job-status-and-passfail)).
 
 Exit codes make the Agent usable as a CI step:
 
@@ -79,6 +79,7 @@ Exit codes make the Agent usable as a CI step:
 | `2` | `ERROR`, `TIMEOUT`, or `LOST` |
 | `3` | `CANCELED` |
 | `4` | Usage, auth or connection error |
+| `5` | `thub status <jobId> --json`: the job is still queued or running |
 | `130` | Detached with Ctrl-C (job still running) |
 
 ## Examples
@@ -93,12 +94,12 @@ thub run --type hw --board nucleo-f401re \
   --arg --junit --wait
 ```
 
-**SW task in a Docker image of your own:**
+**SW task against a DUT emulator image of your own** (the command runs on the Client host and talks to the emulator):
 
 ```bash
-thub run --type sw --docker-image alpine:3.20 \
+thub run --type sw --docker-image registry.lab.local:5000/dut-emulator:2026.08 \
   --git-repo git@github.com:yourorg/firmware-tests.git main --depth 20 \
-  --command 'make test' --wait
+  --command 'make test DUT="$THUB_DUT_HOST"' --wait
 ```
 
 **Associate a CI/CD job id with the internal job id:**
@@ -132,6 +133,99 @@ thub run --type hw --board nucleo-f401re \
   --git-repo "$TESTS_REPO" --command ./ci/test.sh --user "Your Name" --wait
 ```
 
+## Environment variables and secrets
+
+`--env NAME=value[,NAME=value]` (repeatable) sets variables for every command the Client runs for the job: git and `--command`. The names are yours; none means anything to the Agent or the Client. `--env NAME` alone takes the value from your own environment, so a secret stays off the command line and out of CI logs:
+
+```bash
+export API_TOKEN=…
+thub run --type sw --git-repo "$TESTS_REPO" \
+  --env TARGET=staging --env API_TOKEN \
+  --command './run-tests.sh --target "$TARGET"' --wait
+```
+
+**How the values are kept secret:**
+
+- They reach **only the Client that runs the job**.
+- The Agent API shows every value as `***`: `thub status --json`, `thub jobs --json`, even for your own job. The dashboard lists the names only.
+- The Coordinator replaces the values with `***` once the job ends.
+- A `--dry-run` shows every value as `***`, whatever its name.
+
+Your command's output is the job's log, so don't print secrets. Everything else — `--command`, `--arg`, `--meta`, `--git-options` — is stored as is and visible, so never put secrets there.
+
+## Docker
+
+**Log in to a custom registry:** in `--command`, with credentials passed as `--env` under any names. Point `DOCKER_CONFIG` at the job's work directory first, so the login is deleted with the job rather than left in the Client user's `~/.docker` for later jobs:
+
+```bash
+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 &&
+             docker pull "$DOCKER_REGISTRY/team/test-runner:1.4"' \
+  --wait
+```
+
+**Pull an image as the DUT:** `--docker-image` is pulled by the Client before the command runs, as its service user. For a private registry, log in once on the Client host as that user: `sudo -u thub docker login registry.lab.local:5000`.
+
+```bash
+thub run --type sw --docker-image registry.lab.local:5000/dut-emulator:2026.08 \
+  --git-repo "$TESTS_REPO" --command './ci/test.sh --dut "$THUB_DUT_HOST"' --wait
+```
+
+**Run the command inside a container:** `--command` starts on the Client host in the work directory (`$THUB_WORK_DIR`, the `--git-repo` checkout). Start the container from it, mounting that directory:
+
+```bash
+thub run --type sw \
+  --env DOCKER_REGISTRY=registry.lab.local:5000,DOCKER_USER=ci --env DOCKER_PASSWORD \
+  --git-repo git@bitbucket.org:yourorg/web-ui-tests.git main \
+  --git-options '-c core.sshCommand="ssh -i /home/thub/.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 -v "$THUB_WORK_DIR:/work" -w /work "$DOCKER_REGISTRY/python:3.14" ./run-tests.sh' \
+  --wait
+```
+
+**Clone the repository inside the image, with parameters from `--env`:**
+
+```bash
+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"' \
+  --wait
+```
+
+The Client host needs Docker and the Client's user in the `docker` group; SW Clients have both. 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.
+
+## Job status and PASS/FAIL
+
+The verdict is `--command`'s exit code: `0` → **PASSED**, anything else → **FAILED**. ERROR, TIMEOUT, LOST and CANCELED mean the job didn't run to a verdict. JUnit XML written to `results/` or `artifacts/` in the work directory is uploaded and summed into the job's `summary`.
+
+**In CI:** `thub run … --wait` exits with the verdict code (table above): `0` PASSED, `1` FAILED, `2` infrastructure, `3` canceled.
+
+**Check a job:**
+
+```bash
+thub status M-00125          # state; follows the log while active; then "Verdict: …" and artifact links; exit = verdict
+thub jobs --mine --state FAILED
+```
+
+**From a script:** `thub status <jobId> --json` prints the job once, with `state`, `exit_code`, `summary`, `message` and `resource.name`. It exits with the verdict code, or `5` while the job is still queued or running:
+
+```bash
+JOB=$(thub run --type sw --git-repo "$TESTS_REPO" --command ./ci/test.sh --detach --json | jq -r .jobId)
+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
 
 ```yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-agent",
-  "version": "1.0.27",
+  "version": "1.0.29",
   "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.0.27",
+    "@andrian.yablonskyy/thub-common": "^1.0.29",
     "commander": "^13.1.0"
   },
   "devDependencies": {

package/src/cli.js

@@ -168,8 +168,8 @@ program
   )
   .option(
     '--docker-image <name>',
-    'SW jobs only: a Docker image the Client runs as the DUT (e.g. alpine, alpine:3.20, registry.lab:5000/emu:1), ' +
-      'instead of its own sw.image; pulled from its registry or Docker Hub. The Client must allow it (sw.allowJobImages)'
+    'SW jobs only: a Docker image the Client runs as the job\'s DUT container, next to --command (e.g. registry.lab:5000/emu:1); ' +
+      'pulled from the registry it names, else Docker Hub. Without it, an SW job has no DUT container'
   )
   .option(
     '--git-repo <url...>',
@@ -184,9 +184,9 @@ program
   )
   .option(
     '--env <vars>',
-    'Environment variables for every command the Client runs for the job (git, docker login, --command): ' +
+    'Environment variables for every command the Client runs for the job (git, --command): ' +
       'NAME=value[,NAME=value] (repeatable; a value may contain commas); --env NAME alone takes its value from this shell. ' +
-      'With DOCKER_REGISTRY, DOCKER_USERNAME and DOCKER_PASSWORD the Client first logs in to that registry. ' +
+      'Any names (except THUB_*, GIT_TERMINAL_PROMPT, GIT_ALLOW_PROTOCOL). ' +
       'Values reach only the Client running the job; the Coordinator masks them and drops them when the job ends',
     collectRepeatable,
     []
@@ -254,14 +254,16 @@ program
   .command('status')
   .description('Show status; follow log if running, show artifacts if done')
   .argument('<jobId>')
-  .option('--json', 'Machine-readable output', false)
+  .option('--json', 'Print the job as JSON once, without following it; exit code: its verdict, or 5 while it\'s still active', false)
   .action(async (jobId, opts) => {
     try {
       const c = client(),
         job = await c.get(`/jobs/${jobId}`);
-      if (opts.json && !ACTIVE_JOB_STATES.has(job.state)){
+      // --json never follows: a script polls it, and tells "still running"
+      // (exit 5) from a verdict.
+      if (opts.json){
         console.log(JSON.stringify(job));
-        return process.exit(exitCodeForJobState(job.state));
+        return process.exit(ACTIVE_JOB_STATES.has(job.state) ? EXIT_CODES.ACTIVE : exitCodeForJobState(job.state));
       }
 
       console.log(`Job ${job.id} — ${job.state}${job.resource ? ' on ' + job.resource.name : ''}`);