@andrian.yablonskyy/thub-coordinator 1.0.36 → 1.0.38

package/test/search.test.js

@@ -0,0 +1,97 @@
+/**
+ * @file        packages/coordinator/test/search.test.js
+ * @description Tests: dashboard list search (?q=) — query parsing, in-memory matching and the Jobs page's SQL search
+ *
+ * @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'),
+  { EventEmitter } = require('node:events'),
+  { openDb } = require('../src/db'),
+  { createEventsService } = require('../src/services/events'),
+  { createRegistryService } = require('../src/services/registry'),
+  { createAgentsService } = require('../src/services/agents'),
+  { createJobsService } = require('../src/services/jobs'),
+  { parseTerms, normalizeQuery, matches, likeClause, MAX_QUERY } = require('../src/services/search');
+
+test('parseTerms splits into lower-case, unique words, capped', () => {
+  assert.deepEqual(parseTerms('  Lab-HW   nucleo lab-hw '), ['lab-hw', 'nucleo']);
+  assert.deepEqual(parseTerms(''), []);
+  assert.deepEqual(parseTerms(undefined), []);
+  assert.deepEqual(parseTerms(['a']), []); // ?q=a&q=b arrives as an array: ignored
+  assert.equal(parseTerms(Array.from({ length: 30 }, (_, i) => `w${i}`).join(' ')).length, 10);
+  assert.equal(normalizeQuery(`  ${'x'.repeat(500)}`).length, MAX_QUERY - 2);
+});
+
+test('matches needs every word somewhere in the fields', () => {
+  const fields = ['lab-hw-01', 'IDLE', ['board:nucleo-f401re', 'uart'], null, [['10.0.0.7']]];
+  assert.ok(matches(fields, []));
+  assert.ok(matches(fields, parseTerms('NUCLEO idle')));
+  assert.ok(matches(fields, parseTerms('10.0.0')));
+  assert.ok(!matches(fields, parseTerms('nucleo busy')));
+});
+
+test('likeClause ANDs the words, ORs the columns and matches % and _ literally', () => {
+  const { sql, params } = likeClause(['a', 'b'], ['x', '50%_off']);
+  assert.equal(sql, '(COALESCE(a, \'\') LIKE ? ESCAPE \'\\\' OR COALESCE(b, \'\') LIKE ? ESCAPE \'\\\') AND ' +
+    '(COALESCE(a, \'\') LIKE ? ESCAPE \'\\\' OR COALESCE(b, \'\') LIKE ? ESCAPE \'\\\')');
+  assert.deepEqual(params, ['%x%', '%x%', '%50\\%\\_off%', '%50\\%\\_off%']);
+  assert.deepEqual(likeClause(['a'], []), { sql: '', params: [] });
+});
+
+test('jobs.page searches ids, users, resources, agents and spec fields — never --env values', () => {
+  const db = openDb(':memory:'),
+    bus = new EventEmitter(),
+    events = createEventsService(db),
+    registry = createRegistryService(db, { bus, events }),
+    agents = createAgentsService(db, { events }),
+    ci = agents.create({ name: 'ci-firmware', kind: 'ci' }).agent,
+    dev = agents.create({ name: 'alice-laptop', kind: 'cli' }).agent,
+    config = { scheduler: { maxQueuedPerAgent: 100 }, jobs: { defaultTimeoutSec: 60, maxTimeoutSec: 60 } },
+    jobs = createJobsService(db, { bus, events, registry, artifacts: {}, config });
+  registry.registerAuto({ clientId: 'c', name: 'lab-sw-01', type: 'sw', labels: [] });
+
+  const a = jobs.create({
+      agentId: ci.id,
+      source: 'ci',
+      spec: {
+        target: { type: 'sw' },
+        command: './ci/smoke.sh',
+        git: { url: 'git@github.com:yourorg/firmware-tests.git', ref: 'release/1.4' },
+        meta: { ciJobId: '9165432107' },
+        env: { API_TOKEN: 'hunter2-secret' }
+      }
+    }).id,
+    m = jobs.create({
+      agentId: dev.id,
+      source: 'cli',
+      spec: { target: { type: 'sw' }, command: 'make test', user: 'Alice Smith', suite: 'regression_50%' }
+    }).id,
+    ids = (q, extra = {}) => jobs.page({ q, size: 'all', ...extra }).rows.map((j) => j.id).sort();
+
+  assert.deepEqual(ids(''), [a, m].sort());
+  assert.deepEqual(ids(a.toLowerCase()), [a]); // job id, any case
+  assert.deepEqual(ids('alice'), [m]); // user and agent name
+  assert.deepEqual(ids('ci-firmware'), [a]); // agent name
+  assert.deepEqual(ids('firmware-tests release/1.4'), [a]); // git url + ref, both words
+  assert.deepEqual(ids('9165432107'), [a]); // meta
+  assert.deepEqual(ids('smoke alice'), []); // words must all match the same job
+  assert.deepEqual(ids('regression_50%'), [m]); // % and _ are literal…
+  assert.deepEqual(ids('regression_5%'), []); // …not wildcards
+  assert.deepEqual(ids('queued', { source: 'cli' }), [m]); // combines with filters
+  assert.equal(jobs.page({ q: 'make', size: 'all' }).pagination.total, 1);
+
+  // --env values are secrets (README §7.2): searching them must find nothing,
+  // or the search box would be an oracle for them.
+  assert.deepEqual(ids('hunter2'), []);
+  assert.deepEqual(ids('API_TOKEN'), []);
+});

package/test/views.test.js

@@ -33,3 +33,33 @@ test('every view compiles', () => {
     assert.doesNotThrow(() => pug.compileFile(file), `${path.relative(VIEWS, file)}`);
   }
 });
+
+// The help page is mostly static text split over partials sharing mixins
+// (views/help/_mixins.pug): compiling each file alone doesn't catch a missing
+// mixin or a broken include, so render the whole page.
+test('help page renders every section with this Coordinator\'s URL', () => {
+  const html = pug.renderFile(path.join(VIEWS, 'help', 'index.pug'), {
+    user: { username: 'viewer', role: 'viewer', theme: 'auto' },
+    updates: {},
+    messages: [],
+    currentPath: '/help',
+    active: 'help',
+    title: 'Help',
+    coordinatorVersion: '1.2.3',
+    commonVersion: '1.0.0',
+    fmtDate: () => '',
+    coordinatorUrl: 'https://thub.example.test'
+  });
+  for (const id of ['overview', 'use-cases', 'quick-start', 'coordinator', 'agent-setup', 'client-setup',
+    'client-machines', 'docker', 'git', 'agent-cli', 'env', 'ci', 'troubleshooting']){
+    assert.match(html, new RegExp(`<section[^>]* id="${id}"`), `section #${id}`);
+    assert.match(html, new RegExp(`href="#${id}"`), `TOC entry for #${id}`);
+  }
+  assert.match(html, /thub config set url {3}https:\/\/thub\.example\.test/);
+  assert.match(html, /<a class="nav-link d-flex align-items-center active" href="\/help" aria-current="page"/);
+  // Troubleshooting: commands and parameters are <code>, placeholders escaped.
+  assert.match(html, /<code>journalctl -u thub-client@&lt;instance&gt; -f<\/code>/);
+  assert.match(html, /<span>The job is rejected with <code>422<\/code><\/span>/);
+  // Code placeholders are escaped, never parsed as tags.
+  assert.doesNotMatch(html, /<(url|jobId|groupId|resourceId|work|ref)>/);
+});

package/views/admin/agents.pug

@@ -1,12 +1,17 @@
 extends ../layout
 include ../mixins/updates
+include ../mixins/list-controls
 
 block content
   .d-flex.justify-content-between.align-items-center.mb-3
     h1.h4.mb-0 Agents (CI / developers)
     button.btn.btn-primary.btn-sm(type="button" data-bs-toggle="modal" data-bs-target="#addAgentModal") Register agent
-  .mb-3
-    +updatesToolbar('agent', 'agents', '/admin/agents')
+  .d-flex.flex-wrap.align-items-center.gap-2.mb-3
+    +updatesToolbar('agent', 'agents', list.pageUrl())
+  .d-flex.flex-wrap.align-items-center.gap-2.mb-3
+    +searchForm(q, 'Search agents: name, kind, version, status', list.urlFor({ q: '' }))
+    .ms-auto
+      +pageSizePicker(list)
 
   if newToken
     .alert.alert-warning
@@ -14,23 +19,26 @@ block content
       |
       code= newToken
 
+  div(data-live="list-toolbar")
+    +listToolbar(list, 'agents')
+
   table.table.table-hover.align-middle
     thead
       tr
-        th Name
-        th Kind
-        th Version
-        th Created
-        th Last used
-        th Status
+        +sortHeader(list, 'name', 'Name')
+        +sortHeader(list, 'kind', 'Kind')
+        +sortHeader(list, 'version', 'Version', 'desc')
+        +sortHeader(list, 'created', 'Created', 'desc')
+        +sortHeader(list, 'used', 'Last used', 'desc')
+        +sortHeader(list, 'status', 'Status')
         th
-    tbody
+    tbody(data-live="rows")
       each a in agents
         tr(class=a.revoked_at ? 'opacity-50' : '')
           td= a.name
           td.text-uppercase= a.kind
           //- A revoked token can't pick an update up: no button.
-          td: +versionWithUpdate(a.version, updates.latest.agent, a.update_to, `/admin/agents/${a.id}/update`, '/admin/agents', !a.revoked_at)
+          td: +versionWithUpdate(a.version, updates.latest.agent, a.update_to, `/admin/agents/${a.id}/update`, list.pageUrl(), !a.revoked_at)
           td= fmtDate(a.created_at)
           td= fmtDate(a.last_used_at, 'never')
           td= a.revoked_at ? 'revoked' : 'active'
@@ -50,12 +58,14 @@ block content
                   data-confirm-title="Revoke agent token?"
                   data-confirm-ok="Revoke"
                 )
+                  input(type="hidden" name="returnTo" value=list.pageUrl())
                   button.btn.btn-sm.btn-outline-danger(type="submit") Revoke
 
             .modal(tabindex="-1" id=`editAgentModal-${a.id}` aria-labelledby=`editAgentTitle-${a.id}`)
               .modal-dialog
                 .modal-content
                   form(method="post" action=`/admin/agents/${a.id}/rename`)
+                    input(type="hidden" name="returnTo" value=list.pageUrl())
                     .modal-header
                       h5.modal-title(id=`editAgentTitle-${a.id}`) Edit agent
                       button.btn-close(type="button" data-bs-dismiss="modal" aria-label="Close")
@@ -66,6 +76,14 @@ block content
                     .modal-footer
                       button.btn.btn-secondary(type="button" data-bs-dismiss="modal") Cancel
                       button.btn.btn-primary(type="submit") Save
+      else
+        tr
+          td.text-body-secondary(colspan="7")
+            if q
+              | No agent matches “#{q}”. 
+              a(href=list.urlFor({ q: '' })) Show all agents
+            else
+              | No agents yet.
 
   .modal(tabindex="-1" id="addAgentModal")
     .modal-dialog

package/views/groups/list.pug

@@ -1,4 +1,5 @@
 extends ../layout
+include ../mixins/list-controls
 
 block content
   .d-flex.justify-content-between.align-items-center.mb-3
@@ -6,10 +7,18 @@ block content
     if canManage
       button.btn.btn-primary.btn-sm(type="button" data-bs-toggle="modal" data-bs-target="#addGroupModal") Add group
 
-  p.text-body-secondary.small.
+  p.text-body-secondary.small: i.
     A job can be constrained to run only on resources in a group with `thub run --group <id>` (§13.1).
     A resource joins a group by listing its id under `groups` in the Client's own config — membership isn't set here.
 
+  if totalCount
+    .d-flex.flex-wrap.align-items-center.gap-2.mb-2
+      +searchForm(q, 'Search groups: name, id, comment', '/groups')
+      if q
+        span.small.text-body-secondary
+          | #{groups.length} of #{totalCount} groups
+          +searchNote(q)
+
   if groups.length
     table.table.table-hover.align-middle
       thead
@@ -77,6 +86,10 @@ block content
                             i.bi.bi-clipboard
                       .modal-footer
                         button.btn.btn-primary(type="submit") Save
+  else if q
+    p.text-body-secondary
+      | No group matches “#{q}”. 
+      a(href="/groups") Show all groups
   else
     p.text-body-secondary No groups yet.
 

package/views/help/_agent-cli.pug

@@ -0,0 +1,103 @@
++section('agent-cli', 'Agent CLI reference', 'code-square')
+  h3.h6 Commands
+  +code('thub --help').
+    thub run      [options]                 Submit a job and follow its log
+    thub status   <jobId> [--json]          Status; follow the log if running, artifact links if done
+    thub cancel   <jobId>                   Cancel a job
+    thub resources [--json]                 Clients and their status
+    thub jobs     [--mine] [--state <s>] [--json]   Recent jobs
+    thub config   set <url|token|group|user> <value>
+    thub check-update                       Compare with the latest published Agent
+    thub self-update [--to <x.y.z>]         Update with npm i -g
+    thub --version
+    Global: --url <url>  --token <token>   (override THUB_URL / THUB_TOKEN / config file)
+
+  h3.h6 #[code thub run] options
+  -
+    const groups = [
+      { title: 'Where to run', rows: [
+        ['--type hw|sw', 'Required. Resource type.', '--type hw'],
+        ['--board <name>', 'Shorthand for --label board:<name>.', '--board nucleo-f401re'],
+        ['--label <l>', 'Required label (repeatable). The Client must have all of them.', '--label uart --label stlink'],
+        ['--group <id>', 'Only Clients in this group. Default: THUB_GROUP / config.', '--group 548ae4ae-…'],
+        ['--client <name|id>', 'Only this Client; waits for it even if others are idle.', '--client lab-hw-01']
+      ] },
+      { title: 'What to run', rows: [
+        ['--command <string>', 'Required. Run with sh -c in the work directory. Exit code 0 = PASSED.', "--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'],
+        ['--download-file <url>', 'File downloaded before the command (repeatable, http(s), no credentials). THUB_DOWNLOAD_1…', '--download-file https://…/app.bin'],
+        ['--git-repo <url> [ref]', 'Repository cloned first; the command runs in it.', '--git-repo git@github.com:org/tests.git v1.4.0'],
+        ['--depth <n>', 'Commits to fetch with --git-repo (default 1, 0 = full).', '--depth 0'],
+        ['--git-options <string>', 'Extra git options between git and its subcommand. Stored with the job.', '--git-options \'-c core.sshCommand="ssh -i ~/.ssh/k"\''],
+        ['--docker-image <ref>', 'SW only: DUT container image, pulled with the Client host’s Docker login.', '--docker-image registry.lab:5000/emu:1'],
+        ['--env <vars>', 'NAME=value[,NAME=value] for git and the command (repeatable). --env NAME takes the value from your shell. Masked, dropped at job end.', '--env TARGET=staging --env API_TOKEN']
+      ] },
+      { title: 'Job settings', rows: [
+        ['--timeout <dur>', 'e.g. 30m, 1h (default 30m, capped by the Coordinator).', '--timeout 1h'],
+        ['--priority <n>', '0–100. Defaults: ci 50, cli 60.', '--priority 80'],
+        ['--user <name>', 'Free-text owner label. Default: THUB_USER / config.', '--user alice'],
+        ['--meta <key=value>', 'Metadata stored on the job (repeatable). The command sees THUB_META_<KEY>.', '--meta ciJobId=$GITHUB_RUN_ID'],
+        ['--dry-run', 'Schedule for real, but only log what the Client would run.', '--dry-run']
+      ] },
+      { title: 'Agent behavior', rows: [
+        ['--wait', 'Follow to the end and exit with the verdict code (CI). Ctrl-C/SIGINT cancels the job.', '--wait'],
+        ['--detach', 'Print the job id and exit.', '--detach --json'],
+        ['--json', 'Machine-readable output.', '--json']
+      ] }
+    ]
+  each g in groups
+    h4.h6.text-body-secondary.mt-3= g.title
+    .table-responsive
+      table.table.table-sm.small.align-middle
+        thead
+          tr
+            th(style="width: 22%") Option
+            th Description
+            th(style="width: 32%") Example
+        tbody
+          each r in g.rows
+            tr
+              td: code.text-nowrap= r[0]
+              td= r[1]
+              td: code= r[2]
+
+  h3.h6 Exit codes
+  table.table.table-sm.small.w-auto
+    tbody
+      each e in [['0', 'PASSED'], ['1', 'FAILED'], ['2', 'ERROR, TIMEOUT or LOST'], ['3', 'CANCELED'], ['4', 'Usage, auth or connection error'], ['5', 'thub status --json: still queued or running'], ['130', 'Detached with Ctrl-C (job keeps running)']]
+        tr
+          td: code= e[0]
+          td= e[1]
+
+  h3.h6 Examples
+  +code('Flash and test a board, fail CI on failure').
+    thub run --type hw --board nucleo-f401re \
+      --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.bin \
+      --git-repo https://github.com/yourorg/firmware-tests.git v1.4.0 \
+      --command 'st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/test.sh "$@"' \
+      --arg --junit --timeout 45m --wait
+  +code('Reproduce a failure on the exact bench, labeled with your name').
+    thub run --type hw --board nucleo-f401re --client lab-hw-01 --user "$USER" \
+      --download-file "$IMAGE_URL" --git-repo "$TESTS_REPO" --command ./ci/test.sh
+    # Ctrl-C detaches; the job keeps running. Re-attach:
+    thub status M-00126
+  +code('Verify a download before using it').
+    thub run --type hw --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.bin \
+      --command 'echo "8f15bf27…  $THUB_DOWNLOAD_1" | sha256sum -c && ./flash.sh "$THUB_DOWNLOAD_1"' --wait
+  +code('Secrets and parameters').
+    export API_TOKEN=…
+    thub run --type sw --git-repo "$TESTS_REPO" \
+      --env TARGET=staging,LOG_LEVEL=debug --env API_TOKEN \
+      --command './run-tests.sh --target "$TARGET"' --suite regression --wait
+  +code('Preview exactly what would run (nothing is executed)').
+    thub run --type sw --docker-image alpine --git-repo https://example.invalid/tests.git main \
+      --command ./ci/test.sh --dry-run --wait
+  +code('Scripting: submit, poll, read the result').
+    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) tests=\(.summary.total // 0) failed=\(.summary.failed // 0)"' job.json
+  +code('Lists').
+    thub resources
+    thub jobs --mine --state FAILED
+    thub cancel M-00126

package/views/help/_agent-setup.pug

@@ -0,0 +1,72 @@
++section('agent-setup', 'Agent setup', 'terminal')
+  p.
+    The Agent (#[code thub]) is a stateless Node.js CLI. Install it wherever jobs are submitted from:
+    a developer machine (macOS, Linux or Windows with Node.js 20+) or a CI runner.
+
+  h3.h6 Install
+  +code('Developer machine').
+    npm i -g @andrian.yablonskyy/thub-agent
+    thub --version
+  p.small.
+    In CI you don't need a global install: #[code npx -y @andrian.yablonskyy/thub-agent run …].
+
+  h3.h6 Get a token
+  p.small.
+    An admin registers an agent on #[a(href="/admin/agents") Agents] (or with #[code thub-admin agent add]) and passes you
+    its token, which is shown only once. The agent's #[strong kind] decides the job id prefix and the default priority:
+  table.table.table-sm.small.w-auto
+    thead
+      tr
+        th Kind
+        th For
+        th Job ids
+        th Default priority
+    tbody
+      tr
+        td: code ci
+        td Pipelines
+        td: code A-00001…
+        td 50
+      tr
+        td: code cli
+        td Developers
+        td: code M-00001…
+        td 60 (so a busy pipeline doesn't starve them)
+
+  h3.h6 Configure
+  +code('Save the settings once').
+    thub config set url   #{coordinatorUrl}
+    thub config set token agt_…
+    thub config set user  "Your Name"      # optional: job owner label
+    thub config set group <groupId>       # optional: default --group
+  p.small.
+    These are saved in #[code ~/.config/thub/agent.json]. Order of precedence: flags (#[code --url], #[code --token]) →
+    environment → config file.
+  table.table.table-sm.small
+    thead
+      tr
+        th Variable
+        th Meaning
+    tbody
+      tr
+        td: code THUB_URL
+        td Coordinator URL, e.g. #[code #{coordinatorUrl}]
+      tr
+        td: code THUB_TOKEN
+        td Agent token. Keep it in your CI's secret store.
+      tr
+        td: code THUB_GROUP
+        td Default #[code --group]
+      tr
+        td: code THUB_USER
+        td Default #[code --user]
+      tr
+        td: code THUB_NO_SELF_UPDATE=1
+        td Don't install admin-requested Agent updates on this machine
+  +code('Check the connection').
+    thub resources          # lists the Clients and their status
+    thub jobs --mine        # your recent jobs
+  p.small.mb-0.
+    When an admin requests an Agent update, the next #[code thub] command installs it and then runs on
+    the new version. If it can't install (e.g. no permission in CI), it prints the manual command and
+    carries on with the current version.

package/views/help/_ci.pug

@@ -0,0 +1,44 @@
++section('ci', 'CI/CD integration (GitHub Actions)', 'github')
+  p.
+    The test job only needs the Agent and HTTPS access to the Coordinator, so it runs on an ordinary hosted runner.
+    Create a #[strong ci]-kind agent on #[a(href="/admin/agents") Agents] and store its token as the repository secret
+    #[code THUB_AGENT_TOKEN].
+  +code('.github/workflows/firmware.yml').
+    name: firmware
+    on: [push, pull_request]
+
+    jobs:
+      build:
+        runs-on: [self-hosted, fw-build]
+        outputs:
+          image_url: ${{ steps.upload.outputs.image_url }}
+        steps:
+          - uses: actions/checkout@v4
+          - run: cmake -B build -G Ninja && cmake --build build
+          - id: upload
+            env: { ART_TOKEN: "${{ secrets.ARTIFACTORY_TOKEN }}" }
+            run: |
+              URL="https://artifactory.example.com/fw-local/app/${GITHUB_SHA::7}-${GITHUB_RUN_NUMBER}/app.bin"
+              curl -fsS -H "Authorization: Bearer $ART_TOKEN" -T build/app.bin "$URL"
+              echo "image_url=$URL" >> "$GITHUB_OUTPUT"
+
+      test-hw:
+        needs: build
+        runs-on: ubuntu-latest
+        env:
+          THUB_URL: #{coordinatorUrl}
+          THUB_TOKEN: ${{ secrets.THUB_AGENT_TOKEN }}
+        steps:
+          - run: |
+              npx -y @andrian.yablonskyy/thub-agent run \
+                --type hw --board nucleo-f401re \
+                --download-file "${{ needs.build.outputs.image_url }}" \
+                --git-repo "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY.git" "$GITHUB_SHA" \
+                --command 'st-flash --serial "$THUB_DUT_STLINK" --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
+    li The step's exit code is the verdict (#[a(href="#agent-cli") exit codes]), so the workflow fails exactly when the tests do.
+    li If the workflow is canceled, the Agent (in #[code --wait] mode) cancels the TestHub job, so abandoned runs don't hold hardware.
+    li Downloads carry no credentials. Publish the image to a URL the Client can read, or fetch it in #[code --command] with a token passed as #[code --env].
+    li Other CI systems (GitLab CI, Jenkins, Azure Pipelines) work the same way: install Node.js, set #[code THUB_URL]/#[code THUB_TOKEN] and run #[code thub run … --wait].

package/views/help/_client-machines.pug

@@ -0,0 +1,87 @@
++section('client-machines', 'Client machines: HW and SW', 'pc')
+  p.
+    Which machine you need depends on what the jobs run against. Clients are supported on
+    #[strong Ubuntu 26.04]; other systemd-based Linux distributions work the same way in practice.
+    Every Client machine needs outbound HTTPS to the Coordinator (and to wherever jobs download from:
+    Artifactory, git servers, Docker registries). Nothing inbound.
+
+  .row.g-3.mb-3
+    .col-md-6
+      .card.h-100.border-primary-subtle
+        .card-header
+          i.bi.bi-cpu.me-1
+          strong HW Client: real machine with a physical DUT
+        .card-body.small
+          ul.mb-0
+            li A physical machine (a mini-PC, NUC or Raspberry-class ARM64 board) next to the bench.
+            li USB for the DUT's debugger (ST-Link), USB-serial adapters (UART) and DUT USB. A #[strong powered USB hub] is recommended.
+            li #[code stlink-tools] and/or #[code openocd], #[code usbutils] (for the dashboard's USB scan).
+            li Docker only if jobs run containers in their #[code --command].
+            li One Client instance per board. One machine can drive several boards (up to 8 ST-Links, UARTs and USB devices per instance).
+    .col-md-6
+      .card.h-100.border-success-subtle
+        .card-header
+          i.bi.bi-pc-display.me-1
+          strong SW Client: real or virtual machine, software-only jobs
+        .card-body.small
+          ul.mb-0
+            li Any Linux host: bare metal, a VM (Proxmox, VMware, Hyper-V, KVM) or a cloud instance.
+            li Docker Engine (#[code docker.io]), with the Client's service user in the #[code docker] group (the installer arranges this).
+            li Each job's DUT container is limited to 2 CPUs and 2 GB RAM. Size the VM for one job plus your test tools: 4 vCPU, 8 GB RAM and 40 GB+ disk for images and workspaces is a good start.
+            li For KVM-accelerated emulators (QEMU) inside a VM, turn on #[strong nested virtualization].
+            li No USB or udev setup.
+
+  h3.h6 Preparing an HW machine
+  ol.small
+    li Install the OS and the Client (#[a(href="#client-setup") Client setup]), then plug in the board's ST-Link, UART adapter and DUT USB.
+    li
+      | Find each device's USB #[strong port path] (#[code devpath]). It's stable across replugs as long as the device stays in the same port:
+      +code('HW machine').
+        lsusb -t                                      # USB tree
+        udevadm info -a -n /dev/ttyUSB0 | grep -m1 'ATTRS{devpath}'
+        st-info --probe                               # ST-Link serials
+      | Or open the resource card → #[strong Connected USB devices] → #[strong Refresh], then #[strong Import to config].
+    li
+      | Put the devpaths into #[code hw-devices] and restart. On every start the Client writes
+      | #[code /etc/udev/rules.d/99-thub-<instance>.rules], so the devices appear as #[code /dev/thub/dut<N>-stlink|uart|usb]:
+      +code('HW machine').
+        sudo systemctl restart thub-client@client
+        ls -l /dev/thub/
+    li Check the resource card's #[strong Capabilities]: each configured device must be present (a missing one is flagged).
+    li Your job's #[code --command] flashes the board. The Client never flashes by itself; it passes the ST-Link serials and the downloaded files in the environment (#[a(href="#env") Environment variables]).
+  +code('A typical HW job').
+    thub run --type hw --board nucleo-f401re \
+      --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.bin \
+      --git-repo https://github.com/yourorg/firmware-tests.git v1.4.0 \
+      --command 'st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/test.sh' \
+      --wait
+
+  +note('warning').
+    #[strong HW in a VM?] USB passthrough works, but the #[code devpath] then reflects the #[em virtual] USB topology and
+    can change when the hypervisor reassigns devices. Serial timing-sensitive tests may also suffer. Use a physical machine for HW Clients.
+
+  h3.h6 Preparing an SW machine (real or virtual)
+  +code('SW machine / VM').
+    sudo apt install -y nodejs npm docker.io
+    sudo npm i -g @andrian.yablonskyy/thub-client
+    nano ~/.config/thub/client.json        # "type": "sw", coordinatorUrl, joinKey
+    sudo systemctl enable --now thub-client@client
+    # a private registry for DUT images? log in once, as the Client's user:
+    docker login registry.lab.local:5000
+  p.small.
+    To scale out, clone the VM template. In the clone, #[strong before its first start], run
+    #[code rm -f ~/var/lib/thub/client/*/.client-id ~/var/lib/thub/client/*.token] and give it its own #[code name].
+    Otherwise both VMs register as the same resource.
+  +code('A typical SW job').
+    thub run --type sw \
+      --docker-image registry.lab.local:5000/dut-emulator:2026.08 \
+      --git-repo git@github.com:yourorg/firmware-tests.git main \
+      --command 'make test DUT="$THUB_DUT_HOST"' --wait
+
+  h3.h6 Checklist for any Client machine
+  ul.small.mb-0
+    li Correct time (NTP). Timestamps are anchored to the Coordinator's clock, but TLS needs a sane clock.
+    li Outbound HTTPS to the Coordinator; test it with #[code curl -sI #{coordinatorUrl}/login].
+    li The Client's service user has SSH keys and git credentials for private repos (#[a(href="#git") Git repositories]) and Docker logins for private registries (#[a(href="#docker") Docker registry]).
+    li Under systemd, the service can only write to its state directory. Jobs write to #[code $THUB_WORK_DIR], not to #[code ~].
+    li Optional: a nightly reboot from the resource card's #[strong Reboot] tab (cron, host-local time). It waits for running jobs.