@andrian.yablonskyy/thub-coordinator 1.1.13 → 1.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-coordinator",
-  "version": "1.1.13",
+  "version": "1.1.14",
   "description": "TestHub Coordinator — job queue, resource registry, scheduler, heartbeat monitor, log/artifact store and web dashboard",
   "main": "src/server.js",
   "engines": {
@@ -19,7 +19,7 @@
     "lint:fix": "eslint . --fix"
   },
   "dependencies": {
-    "@andrian.yablonskyy/thub-common": "^1.1.3",
+    "@andrian.yablonskyy/thub-common": "^1.1.4",
     "better-sqlite3": "^12.4.1",
     "express": "^5.1.0",
     "express-session": "^1.18.2",

package/views/help/_agent-cli.pug

@@ -25,7 +25,7 @@
       { title: 'What to run', rows: [
         ['--command <string>', 'Required. Run with sh -c in the work directory. Exit code 0 = PASSED. It clones repositories and runs containers itself (see Using git / Using Docker).', "--command './ci/test.sh'"],
         ['--arg <value>', 'Argument for the command, as "$@" (repeatable).', '--arg --junit --arg -v'],
-        ['--suite <name>', 'Passed as THUB_SUITE (default: default).', '--suite smoke'],
+        ['--suite <name>', 'Passed as JOB_SUITE (default: default).', '--suite smoke'],
         ['--download-file <url>', 'File downloaded before the command (repeatable, http(s), no credentials). THUB_DOWNLOAD_1…', '--download-file https://…/app.bin'],
         ['--env <vars>', 'NAME=value[,NAME=value] for the command (repeatable): how data and secrets reach the job (git tokens, registry passwords). --env NAME takes the value from your shell. Masked, dropped at job end.', '--env TARGET=staging --env API_TOKEN']
       ] },
@@ -70,12 +70,12 @@
     thub run --type hw --label board:nucleo-f401re \
       --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.bin \
       --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 --timeout 45m --wait
   +code('Reproduce a failure on the exact bench (the job carries your username)').
     thub run --type hw --label board:nucleo-f401re --client lab-hw-01 \
-      --download-file "$IMAGE_URL" --env GH_TOKEN --command 'git clone --depth 1 "https://x-access-token:$GH_TOKEN@$TESTS_REPO" . && ./ci/test.sh'
+      --download-file "$IMAGE_URL" --env GH_TOKEN --command 'git clone --depth 1 "https://x-access-token:$GH_TOKEN@$TESTS_REPO" src && cd src && ./ci/test.sh'
     # Ctrl-C detaches; the job keeps running. Re-attach:
     thub status M-00126
   +code('Verify a download before using it').

package/views/help/_ci.pug

@@ -34,8 +34,8 @@
                 --type hw --label board:nucleo-f401re \
                 --download-file "${{ needs.build.outputs.image_url }}" \
                 --env GH_TOKEN="${{ secrets.TESTS_READ_TOKEN }}",SHA="$GITHUB_SHA",REPO="$GITHUB_REPOSITORY" \
-                --command 'git init -q . && git fetch -q --depth 1 "https://x-access-token:$GH_TOKEN@github.com/$REPO.git" "$SHA" && git checkout -q FETCH_HEAD &&
-                           st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/hw-tests.sh' \
+                --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 &&
+                           st-flash --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/hw-tests.sh' \
                 --suite smoke --timeout 30m --wait \
                 --meta runUrl="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
   ul.small.mb-0

package/views/help/_client-machines.pug

@@ -53,8 +53,8 @@
     thub run --type hw --label board:nucleo-f401re \
       --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.bin \
       --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' \
       --wait
 
   +note('warning').
@@ -74,10 +74,9 @@
   +code('A typical SW job').
     thub run --type sw \
       --env GH_TOKEN --env DOCKER_PASSWORD \
-      --command 'git clone --depth 1 "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" . &&
-                 export DOCKER_CONFIG="$THUB_WORK_DIR/.docker" &&
+      --command 'git clone --depth 1 "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" src && cd src &&
                  echo "$DOCKER_PASSWORD" | docker login registry.lab.local:5000 -u ci --password-stdin &&
-                 docker run --rm -v "$PWD:/work" -w /work registry.lab.local:5000/dut-emulator:2026.08 make test' --wait
+                 docker run --rm --user "$(id -u):$(id -g)" -v "$THUB_WORK_DIR/src:/work" -w /work registry.lab.local:5000/dut-emulator:2026.08 make test' --wait
 
   h3.h6 Checklist for any Client machine
   ul.small.mb-0

package/views/help/_client-setup.pug

@@ -106,8 +106,8 @@
     change it hasn't applied yet. #[strong USB devices → Import to config] fills them from the host's #[code lsusb].
     The card's #[strong Export] and #[strong Import] icons download a Client's config file (never its
     #[code joinKey]) and apply one to it. An older HW Client takes only the file's #[code hw-devices].
-    There's no ST-Link serial field: the job's #[code --command] picks the probe
-    (#[code $THUB_DUT_STLINK_<n>]), and the Client reads each serial from its udev symlink.
+    There's no ST-Link serial field: the job's #[code --command] picks the probe (#[code st-flash] alone uses the
+    only one; with several, #[code st-flash --serial] with a serial from #[code st-info --probe]).
 
   h3.h6 Several DUT slots on one machine
   +code('One instance per slot').

package/views/help/_docker.pug

@@ -13,11 +13,10 @@
     thub run --type sw \
       --env DOCKER_REGISTRY=registry.lab.local:5000,DOCKER_USER=ci --env DOCKER_PASSWORD \
       --env TARGET=staging \
-      --command 'export DOCKER_CONFIG="$THUB_WORK_DIR/.docker" &&
-                 echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" -u "$DOCKER_USER" --password-stdin &&
-                 docker run --rm \
-                   -v "$THUB_WORK_DIR:/work" -w /work --user "$(id -u):$(id -g)" \
-                   -e TARGET -e THUB_SUITE -e THUB_JOB_ID \
+      --command 'echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" -u "$DOCKER_USER" --password-stdin &&
+                 docker run --rm --user "$(id -u):$(id -g)" \
+                   -v "$THUB_WORK_DIR/src:/work" -w /work \
+                   -e TARGET -e JOB_SUITE -e THUB_JOB_ID \
                    "$DOCKER_REGISTRY/team/test-runner:1.4" ./run-tests.sh --junit results/junit.xml' \
       --wait
   table.table.table-sm.small
@@ -30,8 +29,8 @@
         td: code --rm
         td Removes the container when the tests end.
       tr
-        td: code -v "$THUB_WORK_DIR:/work" -w /work
-        td The work directory, where the Client reads JUnit XML under #[code results/] and #[code artifacts/] for the test counts.
+        td: code -v "$THUB_WORK_DIR/src:/work" -w /work
+        td Only the clone (#[code src/]), not the job directory, which holds the registry login in #[code .docker/]. The Client reads JUnit XML from #[code src/results/] or #[code src/artifacts/] for the test counts.
       tr
         td: code -e NAME
         td Passes a job variable (#[code --env], #[code THUB_*], #[code JOB_*]) into the container.
@@ -40,7 +39,37 @@
         td Files written to #[code /work] stay owned by the Client user, so the workspace can be cleaned up.
       tr
         td: code --device /dev/thub/dut1-uart
-        td HW: gives the container the DUT's UART (#[code "$THUB_DUT_UART"]). Use #[code --privileged] only if you must.
+        td HW: gives the container the DUT's UART (#[code /dev/thub/dut1-uart]). Use #[code --privileged] only if you must.
+
+  h3.h6 Clone and test inside a container, with a deploy key and a registry login from the job
+  p.small.
+    Everything comes from the Agent as #[code --env]: the registry and its credentials, and the private key the
+    container clones with. Nothing is set up on the Client host beforehand.
+  +code('Reference example').
+    # 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: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
+  ul.small
+    li Plain values go as #[code --env NAME=value]. Secrets go as #[code --env NAME] alone: the Agent takes the value from its own environment, so it never appears on the command line, in shell history or in CI logs. A multi-line value, such as the key, arrives intact.
+    li The Client sets #[code DOCKER_CONFIG=$THUB_WORK_DIR/.docker]: the registry login lands in the job's directory, deleted with the job. Only #[code src/] is mounted into the container, so the login isn't visible in it.
+    li #[code -e GIT_KEY] hands the key to the container. #[code --entrypoint sh] is needed because #[code alpine/git]'s own entrypoint is #[code git]. #[code --user "$(id -u):$(id -g)"] (with #[code HOME=/tmp]) keeps the clone owned by the Client user, so it can be deleted with the job; #[code mkdir -p] first so Docker doesn't create #[code src/] as root.
+    li In the inner script, #[code \$] is escaped, so the #[strong container] expands the variables, not the Client's shell. #[code ssh-agent] holds the key in memory: it's never written to a file. #[code accept-new] trusts the git server's host key on first use.
+    li #[code alpine/git] comes from Docker Hub. The #[code docker login] is for private images such as #[code $DOCKER_REGISTRY/team/test-runner:1.4].
+    li Never #[code echo] a secret: the command's output is the job log, which is stored and visible.
 
   h3.h6 An emulator as the DUT
   p.small.
@@ -49,8 +78,7 @@
     thub run --type sw \
       --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.elf \
       --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" -u "$DOCKER_USER" --password-stdin &&
+      --command 'echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" -u "$DOCKER_USER" --password-stdin &&
                  dut="thub-$THUB_JOB_ID" && trap "docker rm -f $dut >/dev/null" EXIT &&
                  docker run -d --name "$dut" -p 127.0.0.1:5555:5555 -v "$THUB_DOWNLOADS_DIR:/downloads:ro" \
                    "$DOCKER_REGISTRY/dut-emulator:2026.08" &&

package/views/help/_env.pug

@@ -10,14 +10,11 @@
     const thubVars = [
       ['THUB_JOB_ID', 'The job id, e.g. M-00125'],
       ['THUB_ARTIFACTS_FILE', 'Where the command may list the artifacts it published elsewhere: a JSON array of {"name", "size", "link", "timestamp"}, shown on the job page'],
-      ['THUB_WORK_DIR', 'The directory the command runs in, empty at the start (clone into it if you need a repository). JUnit XML in results/ or artifacts/ gives the test counts; deleted when the job ends'],
-      ['THUB_SUITE', '--suite (default: default)'],
+      ['THUB_WORK_DIR', 'The job\'s directory (<client workDir>/<jobId>), where the command starts. Holds downloads/, the artifacts list and .docker/ (the job\'s DOCKER_CONFIG); clone into a folder of your own, e.g. src/. JUnit XML in results/ or artifacts/ gives the test counts; deleted when the job ends'],
+      ['DOCKER_CONFIG', '$THUB_WORK_DIR/.docker — so a docker login stays with the job and is deleted with it (unless --env sets DOCKER_CONFIG)'],
       ['THUB_DOWNLOADS_DIR', 'Where the --download-file files are'],
       ['THUB_DOWNLOADS / THUB_DOWNLOAD_<n>', 'Local paths of the downloads: all, one per line / each one'],
       ['THUB_META_<KEY>', '--meta values; camelCase keys become SNAKE_CASE (ciJobId → THUB_META_CI_JOB_ID)'],
-      ['THUB_DUT_STLINK / _<n>', 'HW: ST-Link serials (device path if the serial couldn\'t be read); unsuffixed = the first'],
-      ['THUB_DUT_UART / _<n>', 'HW: UART device paths (/dev/thub/dut<N>-uart); unsuffixed = the first'],
-      ['THUB_DUT_USB / _<n>', 'HW: DUT USB device paths']
     ]
   .table-responsive
     table.table.table-sm.small
@@ -80,7 +77,7 @@
   +code('ci/test.sh (shell)').
     #!/bin/sh
     set -eu
-    echo "Job $THUB_JOB_ID on $(hostname), suite ${THUB_SUITE}"
+    echo "Job $THUB_JOB_ID on $(hostname), suite ${JOB_SUITE}"
 
     # optional parameters with defaults
     TARGET="${TARGET:-staging}"
@@ -90,21 +87,21 @@
     printf '%s\n' "$THUB_DOWNLOADS" | while read -r f; do echo "downloaded: $f"; done
 
     # HW: flash through the first ST-Link, talk to the second UART
-    st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000
-    python3 -m pytest tests/ --uart "${THUB_DUT_UART_2:-$THUB_DUT_UART}" --junitxml=results/junit.xml
+    st-flash --reset write "$THUB_DOWNLOAD_1" 0x08000000
+    python3 -m pytest tests/ --uart "/dev/thub/dut2-uart" --junitxml=results/junit.xml
 
     # CI metadata passed with --meta ciJobId=… / --meta sha=…
     echo "CI run ${THUB_META_CI_JOB_ID:-local}, sha ${THUB_META_SHA:-unknown}"
   +code('conftest.py (Python)').
-    import os
+    import glob, os
 
-    UARTS     = [v for k, v in sorted(os.environ.items()) if k.startswith("THUB_DUT_UART_")]
+    UARTS     = sorted(glob.glob("/dev/thub/dut*-uart"))                # this Client's UARTs, by udev path
     FIRMWARE  = os.environ.get("THUB_DOWNLOAD_1")
-    RESULTS   = os.path.join(os.environ.get("THUB_WORK_DIR", "."), "results")
+    RESULTS   = "results"                                            # in the clone (src/results), where the tests run
     API_TOKEN = os.environ["API_TOKEN"]                              # from --env API_TOKEN
   +code('Into a container: -e NAME copies a variable from the job').
-    docker run --rm -v "$THUB_WORK_DIR:/work" -w /work \
-      -e THUB_JOB_ID -e THUB_SUITE -e TARGET -e API_TOKEN \
+    docker run --rm --user "$(id -u):$(id -g)" -v "$THUB_WORK_DIR/src:/work" -w /work \
+      -e THUB_JOB_ID -e JOB_SUITE -e TARGET -e API_TOKEN \
       python:3.14 ./run-tests.sh
   +code('Submitting the job that feeds these').
     export API_TOKEN=…
@@ -113,7 +110,7 @@
       --env TARGET=production,BRANCH=main --env API_TOKEN --env GH_TOKEN \
       --meta ciJobId="$GITHUB_RUN_ID" --meta sha="$GITHUB_SHA" \
       --suite smoke \
-      --command 'git clone --depth 1 --branch "$BRANCH" "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" . &&
+      --command 'git clone --depth 1 --branch "$BRANCH" "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" src && cd src &&
                  ./ci/test.sh' --wait
   p.small.text-body-secondary.mb-0.
     Tip: #[code thub run … --dry-run] lists every variable the command would get on the chosen Client, with #[code --env] values as #[code ***].

package/views/help/_git.pug

@@ -11,7 +11,7 @@
     export GH_TOKEN=…      # GitHub: a fine-grained PAT with read access; GitLab: oauth2 token; Bitbucket: x-token-auth
     thub run --type sw \
       --env GH_TOKEN \
-      --command 'git clone --depth 1 --branch main "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" . &&
+      --command 'git clone --depth 1 --branch main "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" src && cd src &&
                  ./ci/test.sh' \
       --wait
   p.small.
@@ -23,19 +23,23 @@
     export DEPLOY_KEY_B64="$(base64 < ~/.ssh/thub_deploy | tr -d '\n')"
     thub run --type hw --label board:nucleo-f401re \
       --env DEPLOY_KEY_B64 \
-      --command 'umask 077 && echo "$DEPLOY_KEY_B64" | base64 -d > "$THUB_WORK_DIR/../key" &&
-                 GIT_SSH_COMMAND="ssh -i $THUB_WORK_DIR/../key -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new" \
-                   git clone --depth 1 git@github.com:yourorg/firmware-tests.git . &&
+      --command 'umask 077 && echo "$DEPLOY_KEY_B64" | base64 -d > "$THUB_WORK_DIR/key" &&
+                 GIT_SSH_COMMAND="ssh -i $THUB_WORK_DIR/key -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new" \
+                   git clone --depth 1 git@github.com:yourorg/firmware-tests.git src && cd src &&
                  ./ci/test.sh' \
       --wait
   p.small.
     The job directory, key included, is deleted when the job ends. Add the public key as a read-only deploy key: GitHub,
     Repository → Settings → Deploy keys; GitLab, Settings → Repository → Deploy keys; Bitbucket, Repository settings → Access keys.
 
+  p.small.
+    To clone #[em inside a container] with a key passed the same way (held by #[code ssh-agent], never written to disk), see
+    #[a(href="#docker") Using Docker → Clone and test inside a container].
+
   h3.h6 Branch, tag, commit, submodules, LFS
   +code('All in the command').
-    git clone --depth 1 --branch v1.4.0 "$REPO" .                            # a branch or tag
-    git init -q . && git remote add origin "$REPO" && git fetch -q --depth 1 origin a1b2c3d && git checkout -q FETCH_HEAD   # a commit
+    git clone --depth 1 --branch v1.4.0 "$REPO" src                            # a branch or tag
+    git init -q src && cd src && git remote add origin "$REPO" && git fetch -q --depth 1 origin a1b2c3d && git checkout -q FETCH_HEAD   # a commit
     git submodule update --init --recursive --depth 1 && git lfs pull        # submodules / LFS
   p.small.
     Pass the repository and ref as #[code --env REPO=…,REF=…] (or #[code --meta]) so the same command works for every branch.

package/views/mixins/client-config.pug

@@ -249,7 +249,7 @@ mixin configPanes(r, returnTo, groupsById)
         +configPane(p, 'stlinks')
           +capabilitiesStatus(r)
           +deviceTable('stlinks', 'ST-Link probes', current.stlinks || [], ['Device', 'udev devpath'])
-          .form-text Device: a udev index 1–8 (→ /dev/thub/dut<N>-stlink) or a /dev path. Which probe a job uses is up to its #[code --command] (#[code $THUB_DUT_STLINK_<n>]).
+          .form-text Device: a udev index 1–8 (→ /dev/thub/dut<N>-stlink) or a /dev path. Which probe a job uses is up to its #[code --command] (st-flash, by serial with several probes).
           +saveCapabilities(canEdit)
         +configPane(p, 'uarts')
           +capabilitiesStatus(r)