@andrian.yablonskyy/thub-agent 1.1.5 → 1.1.7

package/LICENSE.md

@@ -0,0 +1,26 @@
+Custom License
+
+Copyright (c) 2026 Andrian Yablonskyy
+
+Permission is granted to use this software as-is, subject to the following
+conditions:
+
+1. No Modification. This software may not be modified, adapted, or used to
+   create derivative works.
+
+2. No Redistribution. This software may not be republished, redistributed,
+   or repackaged, in whole or in part, under this or any other name.
+
+3. Public Use Notification. Any public use of this software (including in a
+   publicly accessible product, service, or project) requires prior
+   notification to the author at andrian.yablonskyy@gmail.com.
+
+4. Commercial Use. Any commercial use of this software requires the
+   author's prior written agreement.
+
+THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -32,6 +32,8 @@ 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 report   <jobId> [--post gitlab|bitbucket|github] [--commit-status]   The job's report, or a sticky MR/PR comment
 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 +60,10 @@ 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) |
+| `--id-file <path>` | Write the job id to this file as soon as it's queued, for a later `thub report`. | — (Agent only) |
+| `--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 +83,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 +282,74 @@ 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
+
+The TestHub action does it in one step: the job's log in the step, a Job Summary with every test, a pull-request comment (verdict, board, time, log link; updated in place on re-runs) and an optional commit status:
+
+```yaml
+- uses: andrianyablonskyy/thub-action@v1
+  with:
+    url: https://thub.example.com
+    key: ${{ secrets.THUB_CI_TOKEN }}
+    type: hw
+    labels: board:nucleo-f401re
+    download-files: ${{ needs.build.outputs.image_url }}
+    command: st-flash --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/hw-tests.sh
+```
+
+The PR comment it leaves:
+
+```
+### ❌ TestHub HW smoke: FAILED
+| Job      | A-00042                                   |
+| Result   | FAILED (exit code 1)                      |
+| Board    | nucleo-f401re on lab-hw-01                |
+| Tests    | 42 total · 40 passed · 2 failed · 0 skipped |
+| Duration | 3m 12s (queued 20s)                       |
+| Commit   | abcdef1                                   |
+| Links    | Job page and full log · Workflow run      |
+▸ Failed tests (2)
+```
+
+Use its outputs in later steps:
+
+```yaml
+      - id: thub
+        uses: andrianyablonskyy/thub-action@v1
+        with:
+          url: https://thub.example.com
+          key: ${{ secrets.THUB_CI_TOKEN }}
+          type: hw
+          labels: board:nucleo-f401re
+          command: ./ci/hw-tests.sh
+      - if: always() && steps.thub.outputs.job-id
+        run: |
+          echo "TestHub ${{ steps.thub.outputs.job-id }} on ${{ steps.thub.outputs.client }}: ${{ steps.thub.outputs.state }}"
+          echo "${{ steps.thub.outputs.passed }}/${{ steps.thub.outputs.total }} tests passed in ${{ steps.thub.outputs.duration-sec }} s"
+          echo "Log: ${{ steps.thub.outputs.job-url }}"
+```
+
+Report only, quietly, with the verdict as a commit status:
+
+```yaml
+      - uses: andrianyablonskyy/thub-action@v1
+        with:
+          url: https://thub.example.com
+          key: ${{ secrets.THUB_CI_TOKEN }}
+          type: sw
+          command: ./ci/sw-tests.sh
+          fail: false
+          comment: on-failure
+          commit-status: true
+```
+
+Complete workflows, every input, and how the PR comment and test table work are in `packages/action/README.md` and the main README §11.1.
+
+With the Agent directly:
 
 ```yaml
 test-sw:
@@ -255,7 +367,140 @@ 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.
+
+### Merge/pull-request comments: GitLab, Bitbucket, Jenkins
+
+`thub report <jobId>` renders the same report the GitHub Action leaves: verdict, board, Client, duration, tests, failed tests, and links to the job's log and the pipeline. `--post gitlab|bitbucket|github` keeps it as one comment on the merge/pull request, updated by every later run, and `--commit-status` sets the commit's status, linking to the job. Save the id with `thub run --id-file`, and report in the step that runs whatever the result.
+
+GitLab, with a project access token (`api` scope, Reporter) in the masked variable `GITLAB_TOKEN`:
+
+```yaml
+# .gitlab-ci.yml
+test-hw:
+  stage: test
+  image: node:24
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"     # CI_MERGE_REQUEST_IID: the MR to comment on
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH            # status only (a branch pipeline's open MR, if any, is found by commit)
+  variables:
+    THUB_URL: https://thub.example.com                       # THUB_KEY, GITLAB_TOKEN: masked CI/CD variables
+    THUB_NO_SELF_UPDATE: "1"
+  before_script:
+    - npm i -g @andrian.yablonskyy/thub-agent
+  script:
+    - thub run --type hw --label board:nucleo-f401re --download-file "$IMAGE_URL"
+        --command './ci/hw-tests.sh' --suite smoke --timeout 30m --wait --id-file .thub-job
+        --meta pipelineUrl="$CI_PIPELINE_URL"
+  after_script:                                              # runs after failures and cancels too
+    - '[ -s .thub-job ] && thub report "$(cat .thub-job)" --post gitlab --commit-status --title "HW smoke"'
+```
+
+Bitbucket Cloud, with a repository access token (Pull requests: Write) in the secured variable `BITBUCKET_TOKEN`:
+
+```yaml
+# bitbucket-pipelines.yml
+image: node:24
+pipelines:
+  pull-requests:
+    '**':
+      - step:
+          name: HW tests
+          max-time: 60
+          script:                                            # THUB_URL, THUB_KEY, BITBUCKET_TOKEN: repository variables
+            - export THUB_NO_SELF_UPDATE=1
+            - npm i -g @andrian.yablonskyy/thub-agent
+            - thub run --type hw --label board:nucleo-f401re --command './ci/hw-tests.sh' --suite smoke --timeout 30m --wait --id-file .thub-job
+          after-script:                                      # runs whether the step passed or failed
+            - '[ -s .thub-job ] && thub report "$(cat .thub-job)" --post bitbucket --commit-status --title "HW smoke"'
+```
+
+Jenkins, Bitbucket Data Center, every `thub report` option, and which CI variables each code host reads: main README, §11.5.
+
+## Test frameworks and the PR comment
+
+The verdict is the command's exit code. Test counts come from JUnit XML the command writes to `results/` (or `artifacts/`, either one folder down too):
+
+```bash
+--command '… ./build/uart_tests --gtest_output=xml:results/ …'                          # GoogleTest
+--command '… ctest --test-dir build --output-junit "$PWD/results/ctest.xml" …'          # CTest (absolute path)
+--command '… pytest tests/ --junitxml=results/pytest.xml -o junit_family=xunit2 …'      # pytest
+--command '… mvn -B test; rc=$?; mkdir -p results && cp target/surefire-reports/TEST-*.xml results/; exit $rc'   # JUnit / Maven
+```
+
+To have **every test case** in the PR/MR comment, have the command publish the XML and list it as an artifact (`ci/publish-junit.sh`). The GitHub Action or `thub report --artifact-header …` then fetches it. Full examples, including hardware-in-the-loop with pytest: main README §7.6.
+
+## 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
 
@@ -266,4 +511,4 @@ npm run lint
 
 ## License
 
-Proprietary — see the header comment in each source file.
+See [LICENSE.md](./LICENSE.md).

package/RELEASE.md

@@ -0,0 +1,25 @@
+# Release notes — @andrian.yablonskyy/thub-agent
+
+What changed in each release, newest first. `## Unreleased` collects the changes since the version on npm; `bin/publish` turns that heading into the version and date it releases.
+
+## 1.1.7 — 2026-10-08
+
+Changes since 1.1.6.
+
+### Added
+
+- **`thub report <jobId>`**: a job's report as Markdown — verdict, board and Client, duration, test counts, the failed tests, links to the job's log and the CI run — or, with `--post gitlab|bitbucket|github`, **one sticky comment on the merge/pull request** of the pipeline, updated in place by every later run of the same CI job. `--commit-status` also sets a GitLab commit status, Bitbucket build status or GitHub status that links to the TestHub job. The project, merge/pull request, commit and pipeline come from the CI's own variables; it needs only the code host's token (`GITLAB_TOKEN`, `BITBUCKET_TOKEN`, `GITHUB_TOKEN`). Every test case is listed when the job published its JUnit XML as an artifact (fetched with `--artifact-header`). Also `--title`, `--key`, `--pr`, `--commit`, `--run-url`, `--summary`, `--output`, `--exit-code`.
+- **`thub run --id-file <path>`**: writes the job id to a file as soon as the job is queued, for a later `thub report` in the step that runs whatever the result.
+
+### Changed
+
+- With `--wait`, **`SIGTERM` cancels the job** like `SIGINT` (Ctrl-C) always did. GitLab CI, Jenkins and most CI runners stop a canceled step with `SIGTERM`, which used to end the Agent and leave the job holding the bench until its timeout. Without `--wait`, `SIGTERM` still just ends the Agent.
+
+### Requires
+
+- `@andrian.yablonskyy/thub-common` with `report-markdown` (the release after 1.1.5).
+
+### Docs
+
+- README: CI/CD for GitHub Actions (with the TestHub action), GitLab, Bitbucket and Jenkins; merge/pull-request comments; test frameworks (GoogleTest, CTest, pytest, JUnit) and their results in the PR comment; artifact storage and authentication (Artifactory, S3, Google Drive, SFTP, certificates); the license is now `LICENSE.md` (`"license"` and `"author"` set in `package.json`).
+- These release notes (`RELEASE.md`) are now part of the package.

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "@andrian.yablonskyy/thub-agent",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "TestHub Agent CLI — the single entry point CI/CD and developers use to submit and follow test jobs",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "author": "Andrian Yablonskyy <andrian.yablonskyy@gmail.com>",
   "bin": {
     "thub": "./src/cli.js"
   },
   "main": "src/cli.js",
   "scripts": {
+    "test": "node --test test/*.test.js",
     "postinstall": "node scripts/install-default-config.js",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix"
   },
   "dependencies": {
-    "@andrian.yablonskyy/thub-common": "^1.1.4",
+    "@andrian.yablonskyy/thub-common": "^1.1.6",
     "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/report/resources/jobs/config commands (README §7)
  *
  * @author      Andrian Yablonskyy
  * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
@@ -18,12 +18,14 @@
 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'),
   { followJob } = require('./streaming'),
-  { applyRequestedUpdate, installAgent, version } = require('./self-update');
+  { applyRequestedUpdate, installAgent, version } = require('./self-update'),
+  { report } = require('./report'),
+  fs = require('node:fs');
 
 const program = new Command();
 program
@@ -81,6 +83,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 +200,14 @@ 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('--id-file <path>', 'Write the job id to this file as soon as it\'s queued (for a later `thub report`, §11.5)')
+  .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,10 +219,14 @@ 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);
+      if (opts.idFile){
+        fs.writeFileSync(opts.idFile, `${result.jobId}\n`);
+      }
       if (opts.json){
         console.log(JSON.stringify(result));
       }
@@ -267,6 +306,69 @@ 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);
+    }
+  });
+
+// §11.5: the job as Markdown, or posted where its code is reviewed — the
+// same report the GitHub Action leaves, from any CI.
+program
+  .command('report')
+  .description('A job\'s report as Markdown, or a sticky comment on a GitLab merge request / Bitbucket or GitHub pull request')
+  .argument('<jobId>', 'The job, e.g. A-00042 (thub run --id-file saves it)')
+  .option('--post <platform>', 'Comment on the merge/pull request of this pipeline: gitlab, bitbucket or github (from the CI\'s own variables)')
+  .option('--commit-status', 'With --post: also set a commit status (GitLab) / build status (Bitbucket) / status (GitHub) linking to the job', false)
+  .option('--title <text>', 'A title in the heading, e.g. "HW smoke (nucleo-f401re)"')
+  .option('--key <text>', 'What identifies the comment, so the next run updates it (default: the CI job name and --title)')
+  .option('--pr <number>', 'The merge/pull request, when the pipeline doesn\'t say (a branch pipeline)')
+  .option('--commit <sha>', 'The commit to report on and set the status of (default: the pipeline\'s)')
+  .option('--run-url <url>', 'A link back to the CI run (default: the pipeline\'s)')
+  .option('--run-label <text>', 'Its label (default: Pipeline / Workflow run)')
+  .option('--flavor <platform>', 'Without --post: Markdown for github (default), gitlab or bitbucket (no HTML)')
+  .option('--summary', 'The full report (every test, artifacts) instead of the comment', false)
+  .option('--artifact-header <header>', 'A "Name: value" header for fetching the JUnit XML the job listed as artifacts (repeatable)', collectRepeatable, [])
+  .option('--no-junit', 'Don\'t fetch the JUnit XML artifacts (counts only)')
+  .option('--output <file>', 'Write the Markdown to this file (default: print it, unless --post)')
+  .option('--exit-code', 'Exit with the job\'s verdict code (0 PASSED, 1 FAILED, …) instead of 0', false)
+  .action(async (jobId, opts) => {
+    try {
+      const { url } = resolveConnection(program.opts()),
+        { job } = await report(client(), url, jobId, opts);
+      if (opts.exitCode){
+        process.exit(ACTIVE_JOB_STATES.has(job.state) ? EXIT_CODES.ACTIVE : exitCodeForJobState(job.state));
+      }
+    }
+    catch (err){
+      fail(err);
+    }
+  });
+
 program
   .command('resources')
   .description('List resources and their status')

package/src/report.js

@@ -0,0 +1,306 @@
+/**
+ * @file        packages/agent/src/report.js
+ * @description thub report: a finished job as Markdown, posted as a sticky comment on a GitLab merge request, a
+ *              Bitbucket pull request or a GitHub pull request, with an optional commit/build status (README §11.5)
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+const fs = require('node:fs'),
+  crypto = require('node:crypto'),
+  { parseJUnit, renderComment, renderSummary, commentMarker, statusFor, countsFromCases } = require('@andrian.yablonskyy/thub-common');
+
+const JUNIT_MAX_FILES = 10,
+  JUNIT_MAX_BYTES = 5 * 1024 * 1024;
+
+function fail(message, status = 1){
+  return Object.assign(new Error(message), { status });
+}
+
+async function http(method, url, { headers = {}, body } = {}){
+  const res = await fetch(url, {
+      method,
+      headers: { Accept: 'application/json', 'User-Agent': 'thub-agent', ...(body ? { 'Content-Type': 'application/json' } : {}), ...headers },
+      body: body ? JSON.stringify(body) : undefined
+    }),
+    data = res.status === 204 ? null : await res.json().catch(() => null);
+  if (!res.ok){
+    const why = data?.message || data?.error?.message || data?.error || '';
+    throw fail(`${method} ${url.replace(/\?.*/, '')}: HTTP ${res.status}${why ? ` ${typeof why === 'string' ? why : JSON.stringify(why)}` : ''}`);
+  }
+  return data;
+}
+
+// ---- Where the report goes ------------------------------------------------
+// Each platform: what it reads from its own CI's environment, how it finds
+// and updates its comment, and how it sets a commit status.
+
+const PLATFORMS = {
+  // GitLab merge requests. GITLAB_TOKEN: a project (or group) access token
+  // with the api scope, Reporter or above; CI_JOB_TOKEN can't write notes.
+  gitlab: {
+    detect(env, opts){
+      const api = (env.CI_API_V4_URL || '').replace(/\/+$/, ''),
+        project = env.CI_PROJECT_ID,
+        token = env.GITLAB_TOKEN;
+      if (!api || !project){
+        throw fail('--post gitlab: CI_API_V4_URL and CI_PROJECT_ID are not set — run it in a GitLab CI job', 4);
+      }
+      if (!token){
+        throw fail('--post gitlab: set GITLAB_TOKEN (a project access token with the api scope) as a masked CI/CD variable', 4);
+      }
+      return {
+        api,
+        base: `${api}/projects/${encodeURIComponent(project)}`,
+        headers: { 'PRIVATE-TOKEN': token },
+        target: opts.pr || env.CI_MERGE_REQUEST_IID || null,
+        sha: opts.commit || env.CI_MERGE_REQUEST_SOURCE_BRANCH_SHA || env.CI_COMMIT_SHA || null,
+        runUrl: env.CI_PIPELINE_URL || null,
+        runLabel: 'Pipeline',
+        key: env.CI_JOB_NAME || null
+      };
+    },
+    // A branch pipeline has no CI_MERGE_REQUEST_IID: the open MR for the commit.
+    async findTarget(p){
+      if (p.target || !p.sha){
+        return p.target;
+      }
+      const mrs = await http('GET', `${p.base}/repository/commits/${p.sha}/merge_requests`, { headers: p.headers });
+      return mrs.find((mr) => mr.state === 'opened')?.iid || null;
+    },
+    async upsert(p, mr, marker, body){
+      const notes = `${p.base}/merge_requests/${mr}/notes`;
+      for (let page = 1; page <= 20; page++){
+        const list = await http('GET', `${notes}?per_page=100&page=${page}&sort=asc`, { headers: p.headers }),
+          own = list.find((n) => n.body?.startsWith(marker));
+        if (own){
+          await http('PUT', `${notes}/${own.id}`, { headers: p.headers, body: { body } });
+          return 'updated';
+        }
+        if (list.length < 100){
+          break;
+        }
+      }
+      await http('POST', notes, { headers: p.headers, body: { body } });
+      return 'created';
+    },
+    status(p, { state, context, description, url }){
+      return http('POST', `${p.base}/statuses/${p.sha}`, {
+        headers: p.headers, body: { state, name: context, description: description.slice(0, 255), target_url: url }
+      });
+    },
+    targetName: (mr) => `merge request !${mr}`
+  },
+
+  // Bitbucket Cloud pull requests. BITBUCKET_TOKEN: a repository access token
+  // with Pull requests: Write (and Repositories: Write for the build status);
+  // or BITBUCKET_AUTH=user:app-password / email:API-token, as basic auth.
+  bitbucket: {
+    detect(env, opts){
+      const ws = env.BITBUCKET_WORKSPACE,
+        repo = env.BITBUCKET_REPO_SLUG,
+        api = (env.BITBUCKET_API_URL || 'https://api.bitbucket.org/2.0').replace(/\/+$/, '');
+      if (!ws || !repo){
+        throw fail('--post bitbucket: BITBUCKET_WORKSPACE and BITBUCKET_REPO_SLUG are not set — run it in a Bitbucket Pipelines step', 4);
+      }
+      const auth = env.BITBUCKET_TOKEN
+        ? `Bearer ${env.BITBUCKET_TOKEN}`
+        : env.BITBUCKET_AUTH ? `Basic ${Buffer.from(env.BITBUCKET_AUTH).toString('base64')}` : null;
+      if (!auth){
+        throw fail('--post bitbucket: set BITBUCKET_TOKEN (a repository access token) or BITBUCKET_AUTH=user:password as a secured variable', 4);
+      }
+      return {
+        base: `${api}/repositories/${ws}/${repo}`,
+        headers: { Authorization: auth },
+        target: opts.pr || env.BITBUCKET_PR_ID || null,
+        sha: opts.commit || env.BITBUCKET_COMMIT || null,
+        runUrl: env.BITBUCKET_GIT_HTTP_ORIGIN && env.BITBUCKET_BUILD_NUMBER
+          ? `${env.BITBUCKET_GIT_HTTP_ORIGIN}/pipelines/results/${env.BITBUCKET_BUILD_NUMBER}` : null,
+        runLabel: 'Pipeline',
+        key: null
+      };
+    },
+    // Only pull-request pipelines (pull-requests:) carry BITBUCKET_PR_ID.
+    findTarget: async (p) => p.target,
+    async upsert(p, pr, marker, body){
+      let url = `${p.base}/pullrequests/${pr}/comments?pagelen=100`;
+      for (let page = 0; url && page < 20; page++){
+        const list = await http('GET', url, { headers: p.headers }),
+          own = (list.values || []).find((c) => !c.deleted && c.content?.raw?.startsWith(marker));
+        if (own){
+          await http('PUT', `${p.base}/pullrequests/${pr}/comments/${own.id}`, { headers: p.headers, body: { content: { raw: body } } });
+          return 'updated';
+        }
+        url = list.next;
+      }
+      await http('POST', `${p.base}/pullrequests/${pr}/comments`, { headers: p.headers, body: { content: { raw: body } } });
+      return 'created';
+    },
+    // A build status key is at most 40 characters: a hash of ours.
+    status(p, { state, context, description, url }){
+      return http('POST', `${p.base}/commit/${p.sha}/statuses/build`, {
+        headers: p.headers,
+        body: {
+          key: `thub-${crypto.createHash('sha1').update(context).digest('hex').slice(0, 34)}`,
+          state, name: context, description: description.slice(0, 255), url
+        }
+      });
+    },
+    targetName: (pr) => `pull request #${pr}`
+  },
+
+  // GitHub pull requests from any CI (Jenkins, …); in GitHub Actions the
+  // TestHub action does this too. GITHUB_TOKEN: pull-requests (and statuses) write.
+  github: {
+    detect(env, opts){
+      const repo = env.GITHUB_REPOSITORY,
+        token = env.GITHUB_TOKEN;
+      if (!repo){
+        throw fail('--post github: set GITHUB_REPOSITORY (owner/name)', 4);
+      }
+      if (!token){
+        throw fail('--post github: set GITHUB_TOKEN (pull-requests: write, and statuses: write for --commit-status)', 4);
+      }
+      let event = {};
+      try {
+        event = env.GITHUB_EVENT_PATH ? JSON.parse(fs.readFileSync(env.GITHUB_EVENT_PATH, 'utf8')) : {};
+      }
+      catch { /* not in Actions */ }
+      const server = env.GITHUB_SERVER_URL || 'https://github.com';
+      return {
+        base: `${(env.GITHUB_API_URL || 'https://api.github.com').replace(/\/+$/, '')}/repos/${repo}`,
+        headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28' },
+        target: opts.pr || event.pull_request?.number || null,
+        sha: opts.commit || event.pull_request?.head?.sha || env.GITHUB_SHA || null,
+        runUrl: env.GITHUB_RUN_ID ? `${server}/${repo}/actions/runs/${env.GITHUB_RUN_ID}` : null,
+        runLabel: 'Workflow run',
+        key: [env.GITHUB_WORKFLOW, env.GITHUB_JOB].filter(Boolean).join(' / ') || null
+      };
+    },
+    findTarget: async (p) => p.target,
+    async upsert(p, pr, marker, body){
+      for (let page = 1; page <= 20; page++){
+        const list = await http('GET', `${p.base}/issues/${pr}/comments?per_page=100&page=${page}`, { headers: p.headers }),
+          own = list.find((c) => c.body?.startsWith(marker));
+        if (own){
+          await http('PATCH', `${p.base}/issues/comments/${own.id}`, { headers: p.headers, body: { body } });
+          return 'updated';
+        }
+        if (list.length < 100){
+          break;
+        }
+      }
+      await http('POST', `${p.base}/issues/${pr}/comments`, { headers: p.headers, body: { body } });
+      return 'created';
+    },
+    status(p, { state, context, description, url }){
+      return http('POST', `${p.base}/statuses/${p.sha}`, {
+        headers: p.headers, body: { state, context, description: description.slice(0, 140), target_url: url }
+      });
+    },
+    targetName: (pr) => `pull request #${pr}`
+  }
+};
+
+// Test cases from the JUnit XML the job listed in $THUB_ARTIFACTS_FILE.
+async function junitCases(job, headerLines, warn){
+  const headers = Object.fromEntries(headerLines.map((h) => [h.slice(0, h.indexOf(':')).trim(), h.slice(h.indexOf(':') + 1).trim()])),
+    files = (job.artifacts || []).filter((a) => /\.xml(\?|$)/i.test(a.name || '') || /\.xml(\?|$)/i.test(a.link || '')).slice(0, JUNIT_MAX_FILES),
+    cases = [];
+  for (const a of files){
+    try {
+      const res = await fetch(a.link, { headers });
+      if (!res.ok){
+        throw new Error(`HTTP ${res.status}`);
+      }
+      const text = await res.text();
+      if (text.length > JUNIT_MAX_BYTES){
+        throw new Error('larger than 5 MB');
+      }
+      cases.push(...parseJUnit(text));
+    }
+    catch (err){
+      warn(`Couldn't read test results from ${a.name}: ${err.message} (--artifact-header, if the storage needs credentials)`);
+    }
+  }
+  return cases;
+}
+
+// `thub report <jobId>`. `api`: the Agent's ApiClient; `baseUrl`: the
+// Coordinator, for the job page's link. Returns { markdown, posted, status }.
+async function report(api, baseUrl, jobId, opts, { env = process.env, out = console.log, warn = console.error } = {}){
+  for (const h of opts.artifactHeader || []){
+    if (!/^[A-Za-z0-9-]+:\s*\S/.test(h)){
+      throw fail(`--artifact-header ${h}: expected "Name: value"`, 4);
+    }
+  }
+  if (opts.post && !PLATFORMS[opts.post]){
+    throw fail(`--post ${opts.post}: must be gitlab, bitbucket or github`, 4);
+  }
+  if (opts.commitStatus && !opts.post){
+    throw fail('--commit-status needs --post gitlab|bitbucket|github (where to set it)', 4);
+  }
+  const job = await api.get(`/jobs/${encodeURIComponent(jobId)}`),
+    cases = opts.junit === false ? [] : await junitCases(job, opts.artifactHeader || [], warn);
+  if (cases.length && !(job.summary?.total > 0)){
+    job.summary = { ...job.summary, ...countsFromCases(cases) };
+  }
+  const platform = opts.post ? PLATFORMS[opts.post] : null,
+    where = platform ? platform.detect(env, opts) : {},
+    flavor = opts.flavor || opts.post || 'github',
+    key = opts.key || [where.key, opts.title].filter(Boolean).join(' / ') || 'TestHub',
+    ctx = {
+      key,
+      title: opts.title,
+      flavor,
+      jobUrl: `${baseUrl.replace(/\/+$/, '')}/jobs/${job.id}`,
+      runUrl: opts.runUrl || where.runUrl || null,
+      runLabel: opts.runLabel || where.runLabel || 'CI run',
+      sha: opts.commit || where.sha || null
+    },
+    markdown = opts.summary ? renderSummary(job, ctx, cases) : renderComment(job, ctx, cases),
+    result = { job, markdown, posted: null, status: null };
+
+  if (opts.output){
+    fs.writeFileSync(opts.output, markdown + '\n');
+  }
+  if (!platform){
+    if (!opts.output){
+      out(markdown);
+    }
+    return result;
+  }
+
+  const target = await platform.findTarget(where);
+  if (target){
+    const action = await platform.upsert(where, target, commentMarker(key, flavor), renderComment(job, ctx, cases));
+    result.posted = { target, action };
+    out(`${platform.targetName(target)}: TestHub comment ${action}`);
+  }
+  else {
+    const what = opts.post === 'gitlab' ? 'merge request' : 'pull request';
+    warn(`No ${what} for this pipeline — nothing commented (use a ${what} pipeline, or --pr <number>)`);
+  }
+  if (opts.commitStatus){
+    if (!where.sha){
+      throw fail('--commit-status: no commit (set --commit <sha>)', 4);
+    }
+    const state = statusFor(job.state, opts.post),
+      description = `${job.state}${job.summary?.total ? ` — ${job.summary.passed}/${job.summary.total} tests passed` : ''}` +
+        `${job.resource?.name ? ` on ${job.resource.name}` : ''}`;
+    await platform.status(where, { state, context: `TestHub / ${key}`, description, url: ctx.jobUrl });
+    result.status = state;
+    out(`commit ${where.sha.slice(0, 7)}: status ${state}`);
+  }
+  return result;
+}
+
+module.exports = { report, PLATFORMS };

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();
   }
 }

package/test/report.test.js

@@ -0,0 +1,150 @@
+/**
+ * @file        packages/agent/test/report.test.js
+ * @description Tests: thub report — the Markdown, and the sticky comment and commit/build status on GitLab, Bitbucket
+ *              and GitHub (fake APIs)
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+const test = require('node:test'),
+  assert = require('node:assert/strict'),
+  http = require('node:http'),
+  { ApiClient } = require('@andrian.yablonskyy/thub-common'),
+  { report } = require('../src/report');
+
+const JUNIT = '<testsuite name="s"><testcase classname="uart" name="echo"/>' +
+  '<testcase classname="uart" name="flow"><failure message="no CTS"/></testcase></testsuite>';
+
+// The Coordinator (/api/v1/jobs/…), the JUnit artifact (/art/…) and the code
+// host's API, on one server. `comments`: what the code host already has.
+async function fake(t, { comments = [], state = 'FAILED' } = {}){
+  const seen = [],
+    server = http.createServer((req, res) => {
+      let body = '';
+      req.on('data', (c) => (body += c));
+      req.on('end', () => {
+        seen.push({ method: req.method, url: req.url, headers: req.headers, body: body ? JSON.parse(body) : null });
+        const json = (code, data) => res.writeHead(code, { 'content-type': 'application/json' }).end(JSON.stringify(data)),
+          u = req.url.replace(/\?.*/, '');
+        if (u === '/api/v1/jobs/A-00042'){
+          return json(200, {
+            id: 'A-00042', state, exit_code: state === 'PASSED' ? 0 : 1, duration_sec: 75,
+            created_at: '2026-10-08T10:00:00Z', started_at: '2026-10-08T10:00:30Z',
+            resource: { name: 'lab-hw-01' }, spec: { suite: 'smoke', target: { labels: ['board:nucleo-f401re'] } },
+            summary: { total: 0, passed: 0, failed: 0, skipped: 0 }, artifacts: [{ name: 'junit.xml', link: `${base}/art/junit.xml` }]
+          });
+        }
+        if (u === '/art/junit.xml'){
+          return res.end(JUNIT);
+        }
+        if (req.method === 'GET' && u.endsWith('/merge_requests') && u.includes('/repository/commits/')){
+          return json(200, [{ iid: 3, state: 'merged' }, { iid: 7, state: 'opened' }]);
+        }
+        if (req.method === 'GET'){
+          return json(200, u.includes('/2.0/') ? { values: comments } : comments);
+        }
+        json(201, { id: 99 });
+      });
+    });
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  t.after(() => server.close());
+  const api = new ApiClient({ baseUrl: base, token: 'agt_x' }),
+    out = [],
+    run = (opts, env) => report(api, 'https://thub.example.com', 'A-00042', opts, { env, out: (l) => out.push(l), warn: (l) => out.push(l) });
+  return { base, seen, api, run, out };
+}
+
+test('without --post: the comment as Markdown, test counts from the JUnit artifact', async (t) => {
+  const f = await fake(t),
+    { markdown } = await f.run({ title: 'HW smoke' }, {});
+  assert.match(markdown, /^<!-- thub-report:HW smoke -->\n### ❌ TestHub HW smoke: \*\*FAILED\*\*/);
+  assert.match(markdown, /\| Board \| `nucleo-f401re` on lab-hw-01 \|/);
+  assert.match(markdown, /\| Tests \| 2 total · 1 passed · 1 failed · 0 skipped \|/);
+  assert.match(markdown, /\| Duration \| 1m 15s \(queued 30s\) \|/);
+  assert.match(markdown, /\[A-00042\]\(https:\/\/thub\.example\.com\/jobs\/A-00042\)/);
+  assert.match(markdown, /\| ❌ \| uart\.flow \| — \| no CTS \|/);
+  assert.equal(f.out[0], markdown);
+});
+
+test('GitLab: finds the open MR of a branch pipeline, creates the note, sets the commit status', async (t) => {
+  const f = await fake(t),
+    env = {
+      CI_API_V4_URL: `${f.base}/api/v4`, CI_PROJECT_ID: '12', GITLAB_TOKEN: 'glpat-x',
+      CI_COMMIT_SHA: 'abc1234567', CI_PIPELINE_URL: 'https://gitlab.example.com/fw/-/pipelines/5', CI_JOB_NAME: 'test-hw'
+    },
+    { posted, status } = await f.run({ post: 'gitlab', commitStatus: true }, env);
+  assert.deepEqual(posted, { target: 7, action: 'created' });
+  const note = f.seen.find((r) => r.method === 'POST' && r.url === '/api/v4/projects/12/merge_requests/7/notes');
+  assert.ok(note.body.body.startsWith('<!-- thub-report:test-hw -->'));
+  assert.match(note.body.body, /\[Pipeline\]\(https:\/\/gitlab\.example\.com\/fw\/-\/pipelines\/5\)/);
+  assert.match(note.body.body, /<details open><summary>Failed tests \(1\)<\/summary>/); // GitLab renders HTML
+  assert.equal(note.headers['private-token'], 'glpat-x');
+  const st = f.seen.find((r) => r.url === '/api/v4/projects/12/statuses/abc1234567');
+  assert.deepEqual([st.body.state, st.body.name, st.body.target_url], ['failed', 'TestHub / test-hw', 'https://thub.example.com/jobs/A-00042']);
+  assert.equal(status, 'failed');
+});
+
+test('GitLab: a merge-request pipeline updates its own note, leaving others alone', async (t) => {
+  const f = await fake(t, { state: 'PASSED', comments: [{ id: 1, body: 'LGTM' }, { id: 2, body: '<!-- thub-report:test-hw -->\nold' }] }),
+    env = { CI_API_V4_URL: 'x', CI_PROJECT_ID: '12', GITLAB_TOKEN: 't', CI_MERGE_REQUEST_IID: '4', CI_JOB_NAME: 'test-hw' };
+  env.CI_API_V4_URL = `${f.base}/api/v4`;
+  const { posted } = await f.run({ post: 'gitlab' }, env);
+  assert.deepEqual(posted, { target: '4', action: 'updated' });
+  const put = f.seen.find((r) => r.method === 'PUT');
+  assert.equal(put.url, '/api/v4/projects/12/merge_requests/4/notes/2');
+  assert.match(put.body.body, /✅ TestHub \*\*PASSED\*\*/);
+});
+
+test('Bitbucket: no HTML, a link-definition marker, the build status keyed under 40 characters', async (t) => {
+  const f = await fake(t, { comments: [{ id: 5, content: { raw: '[//]: # (thub-report:HW smoke)\nold' } }] }),
+    env = {
+      BITBUCKET_API_URL: `${f.base}/2.0`, BITBUCKET_WORKSPACE: 'acme', BITBUCKET_REPO_SLUG: 'fw', BITBUCKET_PR_ID: '11',
+      BITBUCKET_COMMIT: 'def4567890', BITBUCKET_TOKEN: 'bbtok', BITBUCKET_GIT_HTTP_ORIGIN: 'https://bitbucket.org/acme/fw', BITBUCKET_BUILD_NUMBER: '88'
+    },
+    { posted } = await f.run({ post: 'bitbucket', commitStatus: true, title: 'HW smoke' }, env);
+  assert.deepEqual(posted, { target: '11', action: 'updated' });
+  const put = f.seen.find((r) => r.method === 'PUT'),
+    raw = put.body.content.raw;
+  assert.equal(put.url, '/2.0/repositories/acme/fw/pullrequests/11/comments/5');
+  assert.equal(put.headers.authorization, 'Bearer bbtok');
+  assert.ok(raw.startsWith('[//]: # (thub-report:HW smoke)\n'));
+  assert.doesNotMatch(raw, /<details|<sub>|<!--/);
+  assert.match(raw, /\*\*Failed tests \(1\)\*\*/);
+  assert.match(raw, /\[Pipeline\]\(https:\/\/bitbucket\.org\/acme\/fw\/pipelines\/results\/88\)/);
+  const st = f.seen.find((r) => r.url === '/2.0/repositories/acme/fw/commit/def4567890/statuses/build');
+  assert.equal(st.body.state, 'FAILED');
+  assert.ok(st.body.key.length <= 40 && st.body.key.startsWith('thub-'));
+  assert.equal(st.body.url, 'https://thub.example.com/jobs/A-00042');
+});
+
+test('GitHub from another CI (Jenkins): --pr and GITHUB_TOKEN', async (t) => {
+  const f = await fake(t),
+    env = { GITHUB_API_URL: f.base, GITHUB_REPOSITORY: 'o/r', GITHUB_TOKEN: 'ghp_x' },
+    opts = { post: 'github', pr: '9', commit: 'aaa1111', commitStatus: true, runUrl: 'https://ci.lab/job/fw/12/', runLabel: 'Jenkins build' },
+    { posted } = await f.run(opts, env);
+  assert.deepEqual(posted, { target: '9', action: 'created' });
+  const post = f.seen.find((r) => r.method === 'POST' && r.url === '/repos/o/r/issues/9/comments');
+  assert.match(post.body.body, /\[Jenkins build\]\(https:\/\/ci\.lab\/job\/fw\/12\/\)/);
+  assert.equal(f.seen.find((r) => r.url === '/repos/o/r/statuses/aaa1111').body.state, 'failure');
+});
+
+test('what\'s missing is said plainly', async (t) => {
+  const f = await fake(t);
+  await assert.rejects(f.run({ post: 'gitlab' }, { CI_API_V4_URL: 'x', CI_PROJECT_ID: '1' }), /set GITLAB_TOKEN/);
+  await assert.rejects(f.run({ post: 'bitbucket' }, {}), /BITBUCKET_WORKSPACE and BITBUCKET_REPO_SLUG are not set/);
+  await assert.rejects(f.run({ post: 'gerrit' }, {}), /must be gitlab, bitbucket or github/);
+  await assert.rejects(f.run({ commitStatus: true }, {}), /--commit-status needs --post/);
+  // A Bitbucket branch pipeline: no PR to comment on, said so, not an error.
+  f.out.length = 0;
+  await f.run({ post: 'bitbucket' }, { BITBUCKET_API_URL: `${f.base}/2.0`, BITBUCKET_WORKSPACE: 'a', BITBUCKET_REPO_SLUG: 'b', BITBUCKET_TOKEN: 't' });
+  assert.match(f.out.join('\n'), /No pull request for this pipeline/);
+});