@andrian.yablonskyy/thub-coordinator 1.1.17 → 1.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-coordinator",
-  "version": "1.1.17",
+  "version": "1.1.18",
   "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.4",
+    "@andrian.yablonskyy/thub-common": "^1.1.5",
     "better-sqlite3": "^12.4.1",
     "express": "^5.1.0",
     "express-session": "^1.18.2",

package/public/js/client-config.js

@@ -40,9 +40,18 @@
     });
   }
 
-  // An HW Client's hw-devices section (the only Clients with a form).
+  // An HW Client's hw-devices section (the only Clients with a form), with
+  // what its tabs don't edit (data-keep: usbPower) as it was loaded.
   function sectionFrom(form){
+    let keep = {};
+    try {
+      keep = JSON.parse(form.dataset.keep || '{}');
+    }
+    catch {
+      keep = {};
+    }
     return {
+      ...keep,
       stlinks: rows(form, 'stlinks'),
       uarts: rows(form, 'uarts'),
       usbs: rows(form, 'usbs')

package/src/api/agent.js

@@ -1,6 +1,6 @@
 /**
  * @file        packages/coordinator/src/api/agent.js
- * @description Agent API routes: job submission, status, cancel, log streaming (README §6.1)
+ * @description Agent API routes: job submission, status, cancel, USB power, log streaming (README §6.1)
  *
  * @author      Andrian Yablonskyy
  * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
@@ -88,6 +88,20 @@ function createAgentRouter({ services, config }){
     }
   });
 
+  // `thub power on|off|reset <jobId>` (README §8.7): the job's owner
+  // switches the USB power of the Client running it.
+  router.post('/jobs/:id/power', auth, visibleJob, (req, res, next) => {
+    try {
+      const { action, delaySec, port } = req.body || {};
+      res.status(202).json(services.jobs.requestPower(req.params.id, {
+        agentId: req.agent.id, action, delaySec, port, by: req.user?.username || req.agent.name
+      }));
+    }
+    catch (err){
+      next(err);
+    }
+  });
+
   router.get('/jobs/:id/logs', auth, visibleJob, (req, res) => {
     const after = Number(req.query.after || 0),
       limit = req.query.limit ? Number(req.query.limit) : undefined;

package/src/api/resource.js

@@ -148,6 +148,46 @@ function createResourceRouter({ services, config }){
     }
   });
 
+  // While a job runs, the Client long-polls here for commands (README §8.7),
+  // so its owner's power reset — or a cancel — doesn't wait for the next
+  // heartbeat. Answers as soon as there's one (heartbeats still drain
+  // them too: whichever asks first gets them), else after `wait` seconds.
+  router.get('/resources/:id/commands', auth, requireOwnResource, (req, res) => {
+    const waitSec = Math.min(Math.max(Number(req.query.wait) || 0, 0), 60),
+      id = req.params.id,
+      queued = services.commands.drain(id);
+    if (queued.length || waitSec === 0){
+      return res.json({ commands: queued });
+    }
+    let timer = null;
+    const done = () => {
+        clearTimeout(timer);
+        services.bus.off('command', onCommand);
+        res.off('close', onClose);
+      },
+      // After the commands service queued it (setImmediate): taken off the
+      // queue only if the Client is still there to get it.
+      onCommand = (evt) => {
+        if (evt.resourceId === id){
+          setImmediate(() => {
+            if (res.writableEnded || res.destroyed){
+              return;
+            }
+            done();
+            res.json({ commands: services.commands.drain(id) });
+          });
+        }
+      },
+      onClose = () => done();
+    timer = setTimeout(() => {
+      done();
+      res.json({ commands: [] });
+    }, waitSec * 1000);
+    services.bus.on('command', onCommand);
+    // The Client gave up (or shut down): stop waiting.
+    res.on('close', onClose);
+  });
+
   router.post('/resources/:id/status', auth, requireOwnResource, (req, res, next) => {
     try {
       const { busy, source, reason } = req.body;

package/src/services/jobs.js

@@ -13,7 +13,9 @@
 
 'use strict';
 
-const { validateJobSpec, maskEnv, JOB_STATES, ACTIVE_JOB_STATES, TERMINAL_JOB_STATES, RESOURCE_STATES } = require('@andrian.yablonskyy/thub-common'),
+const {
+    validateJobSpec, maskEnv, powerRequestErrors, DEFAULT_RESET_DELAY_SEC, JOB_STATES, ACTIVE_JOB_STATES, TERMINAL_JOB_STATES, RESOURCE_STATES
+  } = require('@andrian.yablonskyy/thub-common'),
   { LABEL_RE, LABEL_RULE } = require('./registry'),
   { paginate } = require('./list-prefs'),
   { parseTerms, likeClause } = require('./search'),
@@ -326,6 +328,46 @@ function createJobsService(db, { bus, events, registry, config }){
     return setState(id, JOB_STATES.CANCELED, reason ? { message: reason } : {});
   }
 
+  // Agent: POST /jobs/:id/power (`thub power`, README §8.7) — switch the USB
+  // power of the Client running the job, now. The job's owner only (not
+  // even an admin: it's their bench for as long as the job runs), and only
+  // while a Client has it. Delivered right away to a Client long-polling
+  // for commands, else with its next heartbeat; the Client logs it in the job.
+  function requestPower(id, { agentId, action, delaySec, port, by }){
+    const job = get(id);
+    if (!job){
+      throw Object.assign(new Error('Unknown job'), { status: 404 });
+    }
+    if (job.agent_id !== agentId){
+      throw Object.assign(new Error('Only the job\'s owner can switch its Client\'s USB power'), { status: 403 });
+    }
+    const errors = powerRequestErrors({ action, delaySec, port });
+    if (errors.length){
+      throw Object.assign(new Error(errors.join('; ')), { status: 400 });
+    }
+    // Not ASSIGNED: the Client may not have picked it up yet, and would
+    // drop a command for a job it doesn't know.
+    if (![JOB_STATES.PREPARING, JOB_STATES.RUNNING].includes(job.state) || !job.resource_id){
+      throw Object.assign(new Error(`Job ${id} is ${job.state} — USB power can only be switched while a Client is running it`), { status: 409 });
+    }
+    const r = registry.get(job.resource_id),
+      usbPower = r?.capabilities?.hw?.usbPower;
+    if (!usbPower?.ports?.length){
+      throw Object.assign(new Error(`${r?.name || 'The Client'} has no USB power ports (hw-devices.usbPower in its config), ` +
+        'or its thub-client is older than USB power'), { status: 409 });
+    }
+    if (!usbPower.available){
+      throw Object.assign(new Error(`${r.name} can't switch USB power: ${usbPower.reason || 'uhubctl is unavailable'}`), { status: 409 });
+    }
+    if (port && port > usbPower.ports.length){
+      throw Object.assign(new Error(`port ${port}: ${r.name} has ${usbPower.ports.length} USB power port(s)`), { status: 400 });
+    }
+    const request = { action, ...(action === 'reset' ? { delaySec: delaySec ?? DEFAULT_RESET_DELAY_SEC } : {}), ...(port ? { port } : {}) };
+    bus.emit('command', { resourceId: r.id, command: 'power', jobId: id, ...request, by });
+    events.record('job', id, 'job.power_requested', { ...request, by });
+    return { jobId: id, resource: { id: r.id, name: r.name }, ...request };
+  }
+
   // Admin "Reboot" on a Client (resource card): its running job is canceled
   // first (the host is going down anyway), then a `reboot` command goes out
   // with its next heartbeat — the Client reboots the host through its root
@@ -589,6 +631,7 @@ function createJobsService(db, { bus, events, registry, config }){
     setState,
     cancel,
     cancelPinnedTo,
+    requestPower,
     requestReboot,
     removeResource,
     completeRemoval,

package/src/services/registry.js

@@ -139,13 +139,27 @@ function sanitizeTypedCapabilities(caps){
       hw: {
         stlinks: capList(hw.stlinks).map(device),
         uarts: capList(hw.uarts).map(device),
-        usbs: capList(hw.usbs).map(device)
+        usbs: capList(hw.usbs).map(device),
+        usbPower: usbPowerCapability(hw.usbPower)
       }
     };
   }
   return null;
 }
 
+// The Client's uhubctl ports (README §8.7) and whether uhubctl is installed
+// there: null when it has none (or is older than USB power).
+function usbPowerCapability(p){
+  if (!p || typeof p !== 'object'){
+    return null;
+  }
+  return {
+    ports: capList(p.ports).map((x) => ({ hub: str(x?.hub, 64), port: num(x?.port) })),
+    available: p.available === true,
+    ...(p.available === true ? { version: str(p.version, 64) } : { reason: str(p.reason, 300) })
+  };
+}
+
 // Heartbeat durations (README §10) arrive as seconds relative to "now" on
 // the Client and are anchored to the Coordinator's clock here. Anything
 // negative, non-numeric or over ~10 years is ignored.

package/test/scheduler.test.js

@@ -726,13 +726,13 @@ test('config export/import: exported from the reported file (+ what\'s pending);
   assert.deepEqual(registry.exportClientConfig(sw), { name: 'sw1', type: 'sw', labels: ['x'] });
 });
 
-test('HW capabilities: no power control — reported relays/power dropped, and refused on Save', () => {
+test('HW capabilities: no older power control — reported relays/power dropped, and refused on Save', () => {
   const { registry } = buildTestServices(),
     { resourceId } = registry.registerAuto({
       clientId: 'c-hw', name: 'hw1', type: 'hw', labels: [],
       capabilities: { hw: { stlinks: [], uarts: [], usbs: [], relays: [{ channel: 0 }], power: { method: 'uhubctl', hub: '1-1', port: 2 } } }
     });
-  assert.deepEqual(registry.get(resourceId).capabilities.hw, { stlinks: [], uarts: [], usbs: [] });
+  assert.deepEqual(registry.get(resourceId).capabilities.hw, { stlinks: [], uarts: [], usbs: [], usbPower: null }); // usbPower: none configured
   assert.throws(() => registry.setClientConfig(resourceId, { relays: [{ channel: 0 }] }), /must NOT have additional properties/);
   assert.throws(() => registry.setClientConfig(resourceId, { power: null }), /must NOT have additional properties/);
 });

package/test/usb-power.test.js

@@ -0,0 +1,129 @@
+/**
+ * @file        packages/coordinator/test/usb-power.test.js
+ * @description Tests: `thub power` — the job owner switches its Client's USB power; the command reaches a Client
+ *              long-polling for commands at once
+ *
+ * @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'),
+  fs = require('node:fs'),
+  os = require('node:os'),
+  path = require('node:path'),
+  { loadConfig } = require('../src/config'),
+  { buildServices, createApp } = require('../src/server');
+
+const USB_POWER = { ports: [{ hub: '1-1.4', port: 2 }, { hub: '1-1.4', port: 3 }], available: true, version: '2.6.0' };
+
+async function start(t){
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'thub-power-')),
+    file = path.join(dir, 'coordinator.json');
+  fs.writeFileSync(file, JSON.stringify({ dataDir: path.join(dir, 'data'), updates: { checkIntervalMin: 0 } }));
+  const config = loadConfig(file),
+    services = buildServices(config),
+    server = createApp(config, services).listen(0, '127.0.0.1');
+  t.after(() => new Promise((r) => {
+    server.closeAllConnections?.();
+    server.close(r);
+  }));
+  await new Promise((r) => server.on('listening', r));
+  const base = `http://127.0.0.1:${server.address().port}/api/v1`,
+    call = async (token, method, url, body) => {
+      const res = await fetch(`${base}${url}`, {
+        method,
+        headers: { authorization: `Bearer ${token}`, ...(body ? { 'content-type': 'application/json' } : {}) },
+        body: body ? JSON.stringify(body) : undefined
+      });
+      return { status: res.status, body: res.headers.get('content-type')?.includes('json') ? await res.json() : await res.text() };
+    };
+  return { services, call };
+}
+
+// A Client with `usbPower` capabilities (a job is only accepted when one
+// could run it), and then running job `jobId` (PREPARING).
+function client(services, { name, usbPower }){
+  return services.registry.registerAuto({ clientId: `id-${name}`, name, type: 'hw', labels: [], capabilities: { hw: { usbPower } } });
+}
+
+function runOn(services, { resourceId }, jobId){
+  services.registry.heartbeat(resourceId, { state: 'idle' });
+  services.scheduler.runPass();
+  assert.equal(services.jobs.get(jobId).resource_id, resourceId);
+  services.jobs.setState(jobId, 'PREPARING');
+}
+
+test('power: only the job\'s owner, only while a Client runs it; the Client gets it as a command', async (t) => {
+  const { services, call } = await start(t),
+    alice = services.agents.create({ name: 'alice', kind: 'cli' }).token,
+    ci = services.agents.create({ name: 'pipeline', kind: 'ci' }).token,
+    { resourceId, resourceToken } = client(services, { name: 'lab-hw-01', usbPower: USB_POWER }),
+    jobId = (await call(alice, 'POST', '/jobs', { target: { type: 'hw', client: 'lab-hw-01' }, command: './t.sh' })).body.jobId;
+
+  // Queued: no Client to switch yet.
+  assert.match((await call(alice, 'POST', `/jobs/${jobId}/power`, { action: 'reset' })).body.error,
+    /QUEUED — USB power can only be switched while a Client is running it/);
+
+  runOn(services, { resourceId }, jobId);
+
+  // A CI token sees the job, but it isn't its owner.
+  assert.equal((await call(ci, 'POST', `/jobs/${jobId}/power`, { action: 'reset' })).status, 403);
+  // Bad requests.
+  assert.match((await call(alice, 'POST', `/jobs/${jobId}/power`, { action: 'cycle' })).body.error, /action must be one of on, off, reset/);
+  assert.match((await call(alice, 'POST', `/jobs/${jobId}/power`, { action: 'off', delaySec: 2 })).body.error, /reset only/);
+  assert.match((await call(alice, 'POST', `/jobs/${jobId}/power`, { action: 'on', port: 3 })).body.error, /port 3: lab-hw-01 has 2 USB power port/);
+  services.commands.drain(resourceId); // the assignment's own, if any
+
+  const ok = await call(alice, 'POST', `/jobs/${jobId}/power`, { action: 'reset' });
+  assert.equal(ok.status, 202);
+  assert.deepEqual(ok.body, { jobId, resource: { id: resourceId, name: 'lab-hw-01' }, action: 'reset', delaySec: 1 }); // 1 s by default
+  const { body } = await call(resourceToken, 'GET', `/resources/${resourceId}/commands?wait=0`);
+  assert.deepEqual(body.commands, [{ command: 'power', jobId, action: 'reset', delaySec: 1, by: 'alice' }]);
+
+  // Not any more once it's over.
+  services.jobs.cancel(jobId, { agentId: null, isAdmin: true });
+  assert.equal((await call(alice, 'POST', `/jobs/${jobId}/power`, { action: 'on' })).status, 409);
+});
+
+test('power: refused for a Client without USB power ports, or without uhubctl', async (t) => {
+  const { services, call } = await start(t),
+    alice = services.agents.create({ name: 'alice', kind: 'cli' }).token,
+    old = client(services, { name: 'old-client' }),
+    noUhubctl = client(services, { name: 'no-uhubctl', usbPower: { ports: USB_POWER.ports, available: false, reason: 'uhubctl isn\'t installed' } }),
+    submit = async (on) => (await call(alice, 'POST', '/jobs', { target: { type: 'hw', client: on }, command: './t.sh' })).body.jobId,
+    first = await submit('old-client');
+  runOn(services, old, first);
+  assert.match((await call(alice, 'POST', `/jobs/${first}/power`, { action: 'on' })).body.error, /old-client has no USB power ports/);
+  services.jobs.cancel(first, { isAdmin: true });
+
+  const second = await submit('no-uhubctl');
+  runOn(services, noUhubctl, second);
+  assert.match((await call(alice, 'POST', `/jobs/${second}/power`, { action: 'on' })).body.error, /no-uhubctl can't switch USB power: uhubctl isn't installed/);
+});
+
+test('commands long-poll: answers as soon as a command is queued, else empty after `wait`', async (t) => {
+  const { services, call } = await start(t),
+    { resourceId, resourceToken } = services.registry.registerAuto({ clientId: 'c1', name: 'lab-hw-01', type: 'hw', labels: [] }),
+    listeners = services.bus.listenerCount('command'),
+    started = Date.now(),
+    polling = call(resourceToken, 'GET', `/resources/${resourceId}/commands?wait=10`);
+  await new Promise((r) => setTimeout(r, 100));
+  services.commands.push(resourceId, { command: 'cancel-job', jobId: 'M-00001' });
+  const { status, body } = await polling;
+  assert.equal(status, 200);
+  assert.deepEqual(body.commands, [{ command: 'cancel-job', jobId: 'M-00001' }]);
+  assert.ok(Date.now() - started < 2000);
+  assert.deepEqual(services.commands.drain(resourceId), []); // delivered once
+
+  assert.deepEqual((await call(resourceToken, 'GET', `/resources/${resourceId}/commands?wait=1`)).body, { commands: [] });
+  assert.equal(services.bus.listenerCount('command'), listeners); // none left behind
+  assert.equal((await call(resourceToken, 'GET', '/resources/someone-else/commands')).status, 403);
+});

package/test/views.test.js

@@ -53,7 +53,7 @@ test('help page renders every section with this Coordinator\'s URL', () => {
     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']){
+    'client-machines', 'usb-power', 'lab-devices', 'docker', 'git', 'agent-cli', 'env', 'storage', 'ci', 'troubleshooting']){
     assert.match(html, new RegExp(`<section[^>]* id="${id}"`), `section #${id}`);
     assert.match(html, new RegExp(`href="#${id}"`), `TOC entry for #${id}`);
   }
@@ -62,6 +62,30 @@ test('help page renders every section with this Coordinator\'s URL', () => {
   // 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>/);
+  // USB port power (uhubctl): its setup, the Agent options and the FAQ.
+  assert.match(html, /sudo uhubctl -l 1-1\.4 -p 2 -a off/);
+  assert.match(html, /thub power off M-00131 && thub power on M-00131/);
+  assert.match(html, /<code class="text-nowrap">--power-on-start &lt;action&gt;<\/code>/);
+  assert.match(html, /<span>USB power: <code>No compatible devices detected!<\/code><\/span>/);
+  // Smart sockets and PDUs: driven by the job's own command or script.
+  assert.match(html, /curl -fsS --digest -u "admin:\$SHELLY_PASSWORD" "\$S&on=false"/);
+  assert.match(html, /# ci\/power.sh on\|off\|reset \[off-seconds\]/);
+  assert.match(html, /older AP79xx: sPDUOutletCtl …1\.4\.4\.2\.1\.3\.&lt;outlet&gt;\)/);
+  assert.match(html, /cd src &amp;&amp; exec ci\/run.sh|cd src && exec ci\/run.sh/);
+  // CI/CD for GitHub, GitLab, Bitbucket and Jenkins, all pointed at this Coordinator; artifact storage.
+  for (const file of ['.github/workflows/firmware.yml', '.gitlab-ci.yml', 'bitbucket-pipelines.yml', 'Jenkinsfile']){
+    assert.match(html, new RegExp(`<figcaption class="thub-code-caption">${file.replace(/\./g, '\\.')}</figcaption>`), file);
+  }
+  assert.match(html, /THUB_URL {12}= 'https:\/\/thub\.example\.test'/);
+  assert.match(html, /aws s3 presign "s3:\/\/fw-builds\/app\/\$SHA\/app\.bin" --expires-in 3600/);
+  assert.match(html, /size=\$\(wc -c &lt; "\$file"/); // < escaped in code blocks
+  // Certificates, SSH host-key pinning, per-registry docker login, Artifactory service auth.
+  assert.match(html, /Environment=NODE_EXTRA_CA_CERTS=\/usr\/local\/share\/ca-certificates\/lab-ca\.crt/);
+  assert.match(html, /curl -fsSL --cert "\$THUB_WORK_DIR\/c\.pem" --key "\$THUB_WORK_DIR\/k\.pem"/);
+  assert.match(html, /StrictHostKeyChecking=yes/);
+  assert.match(html, /<td><code>oauth2accesstoken<\/code><\/td>/);
+  assert.match(html, /-d scope=applied-permissions\/user -d expires_in=3600/);
+  assert.match(html, /<span>`?Download failed … \(SELF_SIGNED_CERT_IN_CHAIN\)|<span><code>Download failed … \(SELF_SIGNED_CERT_IN_CHAIN\)<\/code>/);
   // Code placeholders are escaped, never parsed as tags.
   assert.doesNotMatch(html, /<(url|jobId|groupId|resourceId|work|ref)>/);
 });

package/views/help/_agent-cli.pug

@@ -4,6 +4,7 @@
     thub run      [options]                 Submit a job and follow its log
     thub status   <jobId> [--json]          Status; follow the log if running, verdict and test counts 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
     thub resources [--json]                 Clients and their status
     thub jobs     [--mine] [--state <s>] [--json]   Recent jobs (a cli token: only its own)
     thub config   set <url|key|group|user> <value>
@@ -35,6 +36,11 @@
         ['--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: 'USB power (HW, see USB port power)', rows: [
+        ['--power-on-start <action>', 'on, off or reset the Client\'s USB power ports before the command runs. A failure ends the job ERROR.', '--power-on-start reset'],
+        ['--power-on-end <action>', 'on, off or reset them when the job ends, whatever its verdict.', '--power-on-end off'],
+        ['--power-reset-delay <sec>', 'How long a reset keeps the power off: 0–60 s, default 1.', '--power-reset-delay 2']
+      ] },
       { 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'],
@@ -93,6 +99,13 @@
     JOB=$(thub run --type sw --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('Power-cycle the board at the start; your job hung? reset it without canceling').
+    thub run --type hw --label board:nucleo-f401re --command ./ci/test.sh \
+      --power-on-start reset --power-reset-delay 2 --power-on-end off --detach
+    thub power reset M-00131 --delay 3          # owner only, while it runs
+  +code('Power-cycle a board on a smart socket from the test repository (see Smart sockets, PDUs, devices)').
+    thub run --type hw --label board:nucleo-f401re --env GH_TOKEN --env POWER_PASSWORD \
+      --command 'git clone --depth 1 "https://x-access-token:$GH_TOKEN@$TESTS_REPO" src && cd src && exec ci/run.sh' --wait
   +code('Lists').
     thub resources
     thub jobs --mine --state FAILED

package/views/help/_ci.pug

@@ -1,8 +1,34 @@
-+section('ci', 'CI/CD integration (GitHub Actions)', 'github')
++section('ci', 'CI/CD integration (GitHub, GitLab, Bitbucket, Jenkins)', 'diagram-3')
   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 token] on #[a(href="/admin/agents") CI tokens] (admins and maintainers) and store it as the repository secret
-    #[code THUB_CI_TOKEN].
+    Any CI system can run TestHub tests. A pipeline step installs the Agent and runs #[code thub run … --wait]. The step's
+    exit code is the verdict, so the pipeline fails exactly when the tests do.
+
+  h3.h6 What every pipeline needs
+  ul.small
+    li
+      | #[strong A CI token]: create one on #[a(href="/admin/agents") CI tokens] (admins and maintainers). Store it as a masked or
+      | secret variable #[code THUB_KEY], and set #[code THUB_URL] to #[code #{coordinatorUrl}]. Its jobs get #[code A-] ids and the token's group.
+    li
+      | #[strong Node.js 24+ and outbound HTTPS to the Coordinator] on the CI runner. It needs no access to the lab. Use
+      | #[code npx -y @andrian.yablonskyy/thub-agent …] (pin a version, e.g. #[code @1.1.5], for reproducible pipelines) and set
+      | #[code THUB_NO_SELF_UPDATE=1] on short-lived runners.
+    li
+      | #[strong Exit codes] (#[code --wait]): #[code 0] PASSED, #[code 1] FAILED, #[code 2] ERROR/TIMEOUT/LOST, #[code 3] CANCELED,
+      | #[code 4] usage, auth or connection error.
+    li
+      | #[strong Canceling the pipeline cancels the job.] With #[code --wait], #[code SIGINT] and #[code SIGTERM] (how GitHub,
+      | GitLab and Jenkins stop a step) make the Agent cancel the TestHub job before exiting. If the runner kills it outright
+      | (#[code SIGKILL]), the job runs until its #[code --timeout], so keep that tight, or use #[code thub cancel].
+    li #[strong Timeouts]: make the CI step's timeout longer than the queue wait plus #[code --timeout].
+    li #[strong Secrets] go to the job with #[code --env NAME] (the value comes from the step's environment). The CI token never reaches the Client.
+    li #[strong Traceability]: #[code --meta] attaches the pipeline URL and commit to the job.
+    li
+      | #[strong Test reports]: the Coordinator keeps only the JUnit counts. For the CI system's own report view, have the command
+      | publish its JUnit XML to #[a(href="#storage") artifact storage], then download it in the CI step (examples below).
+
+  h3.h6 GitHub Actions
+  p.small.
+    Store the CI token as the repository secret #[code THUB_CI_TOKEN]. The test job runs on an ordinary hosted runner.
   +code('.github/workflows/firmware.yml').
     name: firmware
     on: [push, pull_request]
@@ -38,8 +64,171 @@
                            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
-    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_KEY] and run #[code thub run … --wait].
+  p.small.
+    If the workflow is canceled, the runner sends #[code SIGINT] and the Agent cancels the job.
+
+  h3.h6 GitLab CI/CD
+  p.small.
+    Add #[code THUB_KEY] (masked; protected if only protected branches should reach hardware) and #[code ART_TOKEN] under
+    #[strong Settings → CI/CD → Variables]. The tests are cloned with the job's own #[code CI_JOB_TOKEN]; allow it under
+    #[strong Settings → CI/CD → Job token permissions]. The build hands the image URL to the test job as a #[code dotenv] report,
+    and the JUnit XML comes back through storage for GitLab's test report.
+  +code('.gitlab-ci.yml').
+    # .gitlab-ci.yml
+    stages: [build, test]
+
+    variables:
+      THUB_URL: #{coordinatorUrl}
+      THUB_NO_SELF_UPDATE: "1"
+      ART_BASE: https://artifactory.example.com/fw-local/app
+
+    build:
+      stage: build
+      image: registry.example.com/toolchains/arm-gcc:13
+      script:
+        - cmake -B build -G Ninja && cmake --build build
+        - URL="$ART_BASE/$CI_COMMIT_SHORT_SHA-$CI_PIPELINE_IID/app.bin"
+        - 'curl -fsS -H "Authorization: Bearer $ART_TOKEN" -T build/app.bin "$URL"'
+        - echo "IMAGE_URL=$URL" > build.env
+      artifacts:
+        reports:
+          dotenv: build.env
+
+    test-hw:
+      stage: test
+      image: node:24
+      needs: [build]
+      timeout: 1h                 # > queue wait + --timeout
+      script:
+        - npm i -g @andrian.yablonskyy/thub-agent
+        - |
+          thub 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 --env CI_JOB_ID --env ART_TOKEN \
+            --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 &&
+                       st-flash --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/hw-tests.sh; rc=$?
+                       for f in results/*.xml; do
+                         curl -fsS -H "Authorization: Bearer $ART_TOKEN" -T "$f" "https://artifactory.example.com/qa/gitlab/$CI_JOB_ID/$(basename "$f")"
+                       done
+                       exit $rc' \
+            --timeout 30m --wait \
+            --meta pipelineUrl="$CI_PIPELINE_URL" --meta commit="$CI_COMMIT_SHA" || rc=$?
+          mkdir -p test-results
+          curl -fsS -H "Authorization: Bearer $ART_TOKEN" -o test-results/junit.xml \
+            "https://artifactory.example.com/qa/gitlab/$CI_JOB_ID/junit.xml" || true
+          exit ${rc:-0}
+      artifacts:
+        when: always
+        reports:
+          junit: test-results/*.xml
+
+  h3.h6 Bitbucket Pipelines
+  p.small.
+    Add #[code THUB_URL], #[code THUB_KEY] (secured), #[code ART_TOKEN] (secured) and #[code TESTS_TOKEN] under
+    #[strong Repository settings → Repository variables]. #[code TESTS_TOKEN] is a repository access token with read
+    access, used as the password of the user #[code x-token-auth]. #[code >-] folds the command into one line, so separate its
+    script with #[code ;] and #[code &&]. #[code after-script] collects the JUnit XML into #[code test-results/], which
+    Bitbucket reads automatically.
+  +code('bitbucket-pipelines.yml').
+    # bitbucket-pipelines.yml
+    image: node:24
+
+    definitions:
+      steps:
+        - step: &build
+            name: Build
+            image: registry.example.com/toolchains/arm-gcc:13
+            script:
+              - cmake -B build -G Ninja && cmake --build build
+              - URL="https://artifactory.example.com/fw-local/app/${BITBUCKET_COMMIT:0:7}-$BITBUCKET_BUILD_NUMBER/app.bin"
+              - 'curl -fsS -H "Authorization: Bearer $ART_TOKEN" -T build/app.bin "$URL"'
+              - echo "$URL" > image_url.txt
+            artifacts: [image_url.txt]
+        - step: &test-hw
+            name: HW tests
+            max-time: 60            # minutes; > queue wait + --timeout
+            script:
+              - export THUB_NO_SELF_UPDATE=1 IMAGE_URL="$(cat image_url.txt)"
+              - npm i -g @andrian.yablonskyy/thub-agent
+              - >-
+                thub run --type hw --label board:nucleo-f401re
+                --download-file "$IMAGE_URL"
+                --env TESTS_TOKEN --env BITBUCKET_REPO_FULL_NAME --env BITBUCKET_COMMIT --env BITBUCKET_BUILD_NUMBER --env ART_TOKEN
+                --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 &&
+                st-flash --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/hw-tests.sh; rc=$?;
+                curl -fsS -H "Authorization: Bearer $ART_TOKEN" -T results/junit.xml
+                "https://artifactory.example.com/qa/bitbucket/$BITBUCKET_BUILD_NUMBER/junit.xml"; exit $rc'
+                --timeout 30m --wait
+                --meta buildUrl="$BITBUCKET_GIT_HTTP_ORIGIN/pipelines/results/$BITBUCKET_BUILD_NUMBER"
+            after-script:
+              - mkdir -p test-results
+              - 'curl -fsS -H "Authorization: Bearer $ART_TOKEN" -o test-results/junit.xml "https://artifactory.example.com/qa/bitbucket/$BITBUCKET_BUILD_NUMBER/junit.xml" || true'
+
+    pipelines:
+      default:
+        - step: *build
+        - step: *test-hw
+
+  h3.h6 Jenkins
+  p.small.
+    Add the CI token as a #[strong Secret text] credential (#[code thub-ci-token]), plus #[code artifactory-token] and a
+    username/password for the tests repository (#[code tests-repo]). Run the stage in #[code node:24], or install Node.js with the
+    NodeJS plugin. #[code sh '''…'''] (single quotes) leaves every #[code $] to the shell, so no secret is interpolated by
+    Groovy. Aborting the build sends #[code SIGTERM], and the Agent cancels the job. In a freestyle job, put the same
+    #[code npx … run … --wait] line in an #[em Execute shell] step.
+  +code('Jenkinsfile').
+    // Jenkinsfile (declarative)
+    pipeline {
+      agent none
+      options { timeout(time: 1, unit: 'HOURS') }        // > queue wait + --timeout
+      environment {
+        THUB_URL            = '#{coordinatorUrl}'
+        THUB_NO_SELF_UPDATE = '1'
+      }
+      stages {
+        stage('Build') {
+          agent { label 'fw-build' }
+          environment { ART_TOKEN = credentials('artifactory-token') }
+          steps {
+            sh 'cmake -B build -G Ninja && cmake --build build'
+            script {
+              env.IMAGE_URL = "https://artifactory.example.com/fw-local/app/${env.GIT_COMMIT.take(7)}-${env.BUILD_NUMBER}/app.bin"
+            }
+            sh 'curl -fsS -H "Authorization: Bearer $ART_TOKEN" -T build/app.bin "$IMAGE_URL"'
+          }
+        }
+        stage('HW tests') {
+          agent { docker { image 'node:24' } }
+          environment {
+            THUB_KEY         = credentials('thub-ci-token')
+            ART_TOKEN        = credentials('artifactory-token')
+            NPM_CONFIG_CACHE = "${env.WORKSPACE}/.npm"
+          }
+          steps {
+            withCredentials([usernamePassword(credentialsId: 'tests-repo', usernameVariable: 'GIT_USER', passwordVariable: 'GIT_PASS')]) {
+              sh '''
+                npx -y @andrian.yablonskyy/thub-agent@1.1.5 run --type hw --label board:nucleo-f401re \
+                  --download-file "$IMAGE_URL" \
+                  --env GIT_USER --env GIT_PASS --env TESTS_COMMIT="$GIT_COMMIT" --env BUILD_TAG --env ART_TOKEN \
+                  --command 'git clone -q "https://$GIT_USER:$GIT_PASS@git.example.com/fw/firmware-tests.git" src && cd src &&
+                             git checkout -q "$TESTS_COMMIT" &&
+                             st-flash --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/hw-tests.sh; rc=$?
+                             curl -fsS -H "Authorization: Bearer $ART_TOKEN" -T results/junit.xml "https://artifactory.example.com/qa/jenkins/$BUILD_TAG/junit.xml"
+                             exit $rc' \
+                  --timeout 30m --wait --meta buildUrl="$BUILD_URL"
+              '''
+            }
+          }
+          post {
+            always {
+              sh 'mkdir -p test-results && curl -fsS -H "Authorization: Bearer $ART_TOKEN" -o test-results/junit.xml "https://artifactory.example.com/qa/jenkins/$BUILD_TAG/junit.xml" || true'
+              junit allowEmptyResults: true, testResults: 'test-results/*.xml'
+            }
+          }
+        }
+      }
+    }