@andrian.yablonskyy/thub-coordinator 1.0.29 → 1.0.31

package/src/db/migrations/020_add_usb_scan.sql

@@ -0,0 +1,8 @@
+-- "Connected USB devices" (resource card tab, README §10): the Client runs
+-- `lsusb` only when an admin presses Refresh — a scan-usb command with its
+-- next heartbeat — and posts the output back. `usb_scan` is the last result
+-- (JSON {output, error, at}); `usb_scan_requested_at`/`_request_id` the
+-- pending request, so the tab can tell a fresh result from an old one.
+ALTER TABLE resources ADD COLUMN usb_scan TEXT;
+ALTER TABLE resources ADD COLUMN usb_scan_requested_at TEXT;
+ALTER TABLE resources ADD COLUMN usb_scan_request_id TEXT;

package/src/dev/virtual.js

@@ -66,6 +66,27 @@ const DEV_AGENT_NAME = 'virtual-agent',
     [0.4, 'ci', 'sw', 'PASSED', 201, null],
     [0.1, 'cli', 'sw', 'PASSED', 73, 'alice']
   ],
+  // What `lsusb -tvv` prints on a lab host with a DUT slot plugged in.
+  VIRTUAL_LSUSB = [
+    '/:  Bus 001.Port 001: Dev 001, Class=root_hub, Driver=xhci_hcd/12p, 480M',
+    '    ID 1d6b:0002 Linux Foundation 2.0 root hub',
+    '    /sys/bus/usb/devices/usb1  /dev/bus/usb/001/001',
+    '    |__ Port 003: Dev 002, If 0, Class=Hub, Driver=hub/4p, 480M',
+    '        ID 05e3:0610 Genesys Logic, Inc. Hub',
+    '        /sys/bus/usb/devices/1-3  /dev/bus/usb/001/002',
+    '        |__ Port 001: Dev 004, If 0, Class=Vendor Specific Class, Driver=, 12M',
+    '            ID 0483:3748 STMicroelectronics ST-LINK/V2',
+    '            /sys/bus/usb/devices/1-3.1  /dev/bus/usb/001/004',
+    '        |__ Port 002: Dev 005, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 12M',
+    '            ID 0403:6001 Future Technology Devices International, Ltd FT232 Serial (UART) IC',
+    '            /sys/bus/usb/devices/1-3.2  /dev/bus/usb/001/005',
+    '        |__ Port 003: Dev 006, If 0, Class=Communications, Driver=cdc_acm, 12M',
+    '            ID 0483:5740 STMicroelectronics Virtual COM Port',
+    '            /sys/bus/usb/devices/1-3.3  /dev/bus/usb/001/006',
+    '/:  Bus 002.Port 001: Dev 001, Class=root_hub, Driver=xhci_hcd/4p, 5000M',
+    '    ID 1d6b:0003 Linux Foundation 3.0 root hub',
+    '    /sys/bus/usb/devices/usb2  /dev/bus/usb/002/001'
+  ].join('\n'),
   LOG_SCRIPT = [
     ['runner', 'downloading app.bin (virtual)'],
     ['runner', 'cloning yourorg/firmware-tests at main (virtual)'],
@@ -167,6 +188,22 @@ function startVirtualClients(services, config){
       labels: def.labels,
       hostInfo: { hostname: `${def.name}.virtual`, platform: 'linux', addresses: [{ iface: 'eth0', address: def.address, family: 'IPv4' }], timeZone: 'UTC' },
       capabilities: { ...def.capabilities, rebootSupported: false },
+      // Its "config file": the hw/sw section, as a real Client reports it.
+      config: def.type === 'sw'
+        ? {
+          image: def.capabilities.sw.image,
+          allowDockerHub: def.capabilities.sw.allowDockerHub,
+          allowJobImages: def.capabilities.sw.allowJobImages,
+          cpus: def.capabilities.sw.cpus,
+          memory: def.capabilities.sw.memory
+        }
+        : {
+          stlinks: [{ index: 1, serial: '066DFF485457725187092834', devpath: '3.3.4.3.1' }],
+          uarts: [{ index: 1, baudRate: 115200, devpath: '3.3.3.2' }],
+          usbs: [{ index: 1 }],
+          relays: [{ channel: 0, baseUrl: 'http://localhost:3000' }],
+          power: { method: 'relay' }
+        },
       remoteAddr: '127.0.0.1',
       clientVersion: version
     });
@@ -186,9 +223,14 @@ function startVirtualClients(services, config){
       clientVersion: version,
       hostUptimeSec: Math.round((Date.now() - bootedAt) / 1000),
       activity: { state: c.activity.state, jobId: c.activity.jobId, durationSec: Math.round((Date.now() - c.activity.since) / 1000) },
-      rebootSchedule: registry.get(resourceId)?.reboot_schedule || null // "applies" whatever is saved
+      rebootSchedule: registry.get(resourceId)?.reboot_schedule || null, // "applies" whatever is saved
+      configRevision: registry.get(resourceId)?.config_revision || 0 // ...and any saved config
     });
-    services.commands.drain(resourceId); // nothing real to act on
+    for (const command of services.commands.drain(resourceId)){
+      if (command.command === 'scan-usb'){ // a plausible lsusb for the dashboard
+        registry.storeUsbScan(resourceId, { requestId: command.requestId, output: VIRTUAL_LSUSB, error: null });
+      }
+    }
   }
 
   const beat = () => {

package/src/server.js

@@ -90,6 +90,14 @@ function buildServices(config){
   };
 }
 
+function commonPath(){
+  return path.dirname(require.resolve('@andrian.yablonskyy/thub-common/package.json'));
+}
+
+function commonVersion(){
+  return require('@andrian.yablonskyy/thub-common/package.json').version;
+}
+
 function createApp(config, services){
   const app = express();
   app.set('view engine', 'pug');
@@ -98,6 +106,10 @@ function createApp(config, services){
   app.locals.services = services;
   // Shown in every dashboard page's footer (layout.pug).
   app.locals.coordinatorVersion = require('../package.json').version;
+  // The thub-common this process actually loaded (it validates job specs):
+  // installs keep the one they got, so it can lag behind — shown on the
+  // dashboard and logged at startup to make that visible.
+  app.locals.commonVersion = commonVersion();
 
   app.use(express.json({ limit: '2mb' }));
   app.use(express.urlencoded({ extended: true }));
@@ -162,6 +174,7 @@ function start(configPath){
   const server = app.listen(config.port, config.host, () => {
     console.log(`Config: ${config.configPath || '(built-in defaults)'}; data: ${config.dataDir}`);
     console.log(`TestHub Coordinator listening on http://${config.host}:${config.port}`);
+    console.log(`Coordinator v${require('../package.json').version}, thub-common v${commonVersion()} (${commonPath()})`);
   });
 
   return { app, server, services, config };

package/src/services/jobs.js

@@ -14,7 +14,11 @@
 'use strict';
 
 const { validateJobSpec, JOB_STATES, ACTIVE_JOB_STATES, TERMINAL_JOB_STATES, RESOURCE_STATES } = require('@andrian.yablonskyy/thub-common'),
-  { paginate } = require('./list-prefs');
+  { paginate } = require('./list-prefs'),
+  // Named in spec errors: a field the Agent sends but this thub-common
+  // doesn't know means the Coordinator needs an update.
+  VERSIONS = `Coordinator v${require('../../package.json').version}, ` +
+    `thub-common v${require('@andrian.yablonskyy/thub-common/package.json').version}`;
 
 function rowToJob(row){
   if (!row){
@@ -131,7 +135,7 @@ function createJobsService(db, { bus, events, registry, artifacts, config }){
       rawSpec?.priority === undefined ? { ...rawSpec, priority: DEFAULT_PRIORITY[source] } : rawSpec
     );
     if (!valid){
-      throw Object.assign(new Error(`Invalid job spec: ${errors.join('; ')}`), { status: 400 });
+      throw Object.assign(new Error(`Invalid job spec (${VERSIONS}): ${errors.join('; ')}`), { status: 400 });
     }
     spec.source = source;
 

package/src/services/registry.js

@@ -14,7 +14,7 @@
 'use strict';
 
 const { v4: uuid } = require('uuid'),
-  { RESOURCE_STATES, BUSY_SOURCES, ACTIVE_JOB_STATES, compareVersions, parseCron } = require('@andrian.yablonskyy/thub-common'),
+  { RESOURCE_STATES, BUSY_SOURCES, ACTIVE_JOB_STATES, compareVersions, parseCron, validateClientConfig } = require('@andrian.yablonskyy/thub-common'),
   { generateToken, hashToken } = require('./tokens');
 
 function rowToResource(row){
@@ -27,6 +27,9 @@ function rowToResource(row){
     group_ids: JSON.parse(row.group_ids || '[]'),
     host_info: row.host_info ? JSON.parse(row.host_info) : null,
     capabilities: row.capabilities ? JSON.parse(row.capabilities) : null,
+    client_config: row.client_config ? JSON.parse(row.client_config) : null,
+    config_desired: row.config_desired ? JSON.parse(row.config_desired) : null,
+    usb_scan: row.usb_scan ? JSON.parse(row.usb_scan) : null,
     activity: row.activity ? JSON.parse(row.activity) : null
   };
 }
@@ -187,7 +190,25 @@ function createRegistryService(db, { bus, events }){
   // this registration is allowed to reclaim it. Anything else (IDLE, BUSY,
   // MAINTENANCE, REGISTERED-but-just-created) means a process might still
   // be actively using that identity, so it stays a hard conflict.
-  function registerAuto({ clientId, name, type, labels = [], groups = [], hostInfo, capabilities, remoteAddr, clientVersion = null }){
+  // Plus `config`: the editable part of the Client's config (its hw or sw
+  // section, secrets excluded) — the starting point for the resource card's
+  // Config tab. Stored as reported, if it's a plain object of sane size.
+  // A dashboard rename (name_override) wins over the name the Client
+  // presents; that one is kept as reported_name.
+  function registerAuto({ config, ...registration }){
+    const known = registration.clientId ? getByClientId(registration.clientId) : null,
+      result = registerAutoInner({ ...registration, name: known?.name_override || registration.name });
+    db.prepare('UPDATE resources SET reported_name = ? WHERE id = ?').run(registration.name, result.resourceId);
+    if (config && typeof config === 'object' && !Array.isArray(config)){
+      const json = JSON.stringify(config);
+      if (json.length <= 64 * 1024){
+        db.prepare('UPDATE resources SET client_config = ? WHERE id = ?').run(json, result.resourceId);
+      }
+    }
+    return result;
+  }
+
+  function registerAutoInner({ clientId, name, type, labels = [], groups = [], hostInfo, capabilities, remoteAddr, clientVersion = null }){
     const resourceToken = generateToken('res'),
       remote = normalizeRemoteAddr(remoteAddr);
     hostInfo = {
@@ -307,7 +328,10 @@ function createRegistryService(db, { bus, events }){
   // Reconcile status from a heartbeat's self-reported state (§5.1).
   function heartbeat(
     resourceId,
-    { state, activeJobId, localLock, metrics, addresses, remoteAddr, clientVersion = null, hostUptimeSec, activity, rebootSchedule } = {}
+    {
+      state, activeJobId, localLock, metrics, addresses, remoteAddr, clientVersion = null, hostUptimeSec, activity, rebootSchedule,
+      configRevision, configError
+    } = {}
   ){
     const resource = get(resourceId);
     if (!resource){
@@ -340,6 +364,16 @@ function createRegistryService(db, { bus, events }){
       busyReason = null;
     }
 
+    // The dashboard config revision the Client has applied, and why it last
+    // refused one — older Clients report neither.
+    if (Number.isInteger(configRevision)){
+      db.prepare('UPDATE resources SET config_applied_revision = ?, config_error = ? WHERE id = ?').run(
+        configRevision,
+        typeof configError === 'string' && configError ? configError.slice(0, 1000) : null,
+        resourceId
+      );
+    }
+
     // The reboot schedule the Client applies (null: none); older Clients
     // don't report one at all — then leave what's stored.
     if (rebootSchedule !== undefined){
@@ -539,6 +573,95 @@ function createRegistryService(db, { bus, events }){
     return db.prepare('SELECT * FROM resources WHERE remove_requested_at IS NOT NULL').all().map(rowToResource);
   }
 
+  // "Connected USB devices" tab: Refresh asks the Client to run `lsusb` on
+  // its next heartbeat (a scan-usb command, delivered by the caller's bus
+  // via commands). Only while it's connected — it would otherwise run
+  // whenever it next reconnects.
+  function requestUsbScan(resourceId, { by } = {}){
+    const r = get(resourceId);
+    if (!r){
+      throw Object.assign(new Error('Unknown resource'), { status: 404 });
+    }
+    if (r.status === RESOURCE_STATES.OUT_OF_SERVICE || !r.last_heartbeat_at){
+      throw Object.assign(new Error(`${r.name} is offline — it can only be scanned while it's connected`), { status: 409 });
+    }
+    const requestId = uuid(),
+      requestedAt = new Date().toISOString();
+    db.prepare('UPDATE resources SET usb_scan_requested_at = ?, usb_scan_request_id = ? WHERE id = ?').run(requestedAt, requestId, resourceId);
+    bus.emit('command', { resourceId, command: 'scan-usb', requestId });
+    events.record('resource', resourceId, 'resource.usb_scan_requested', { by });
+    return { requestId, requestedAt };
+  }
+
+  // The Client's answer (POST /resources/:id/usb-scan): kept only for the
+  // request still pending, capped in size.
+  function storeUsbScan(resourceId, { requestId, output, error }){
+    const r = get(resourceId);
+    if (!r || !requestId || requestId !== r.usb_scan_request_id){
+      return false;
+    }
+    const scan = {
+      output: typeof output === 'string' ? output.slice(0, 64 * 1024) : '',
+      error: typeof error === 'string' && error ? error.slice(0, 1000) : null,
+      at: new Date().toISOString()
+    };
+    db.prepare('UPDATE resources SET usb_scan = ?, usb_scan_request_id = NULL WHERE id = ?').run(JSON.stringify(scan), resourceId);
+    return true;
+  }
+
+  // Rename from the dashboard (resource card). The new name must be free;
+  // it's kept across the Client's re-registrations (name_override). An
+  // empty name — or the Client's own — goes back to the Client's own name.
+  // Jobs reference the resource id, so their history follows the rename.
+  function rename(resourceId, newName, { by } = {}){
+    const r = get(resourceId);
+    if (!r){
+      throw Object.assign(new Error('Unknown resource'), { status: 404 });
+    }
+    const wanted = typeof newName === 'string' ? newName.trim() : '',
+      name = wanted || r.reported_name || r.name;
+    if (!/^[A-Za-z0-9._@+-]{1,64}$/.test(name)){
+      throw Object.assign(new Error('A Client name is 1-64 letters, digits or . _ @ + - (no spaces)'), { status: 400 });
+    }
+    const owner = getByName(name);
+    if (owner && owner.id !== resourceId){
+      throw Object.assign(new Error(`The name "${name}" is already used by another Client (${owner.status})`), { status: 409 });
+    }
+    const override = name === r.reported_name ? null : name;
+    db.prepare('UPDATE resources SET name = ?, name_override = ? WHERE id = ?').run(name, override, resourceId);
+    if (name !== r.name){
+      events.record('resource', resourceId, 'resource.renamed', { from: r.name, to: name, by });
+    }
+    return get(resourceId);
+  }
+
+  // Client capabilities edited on the resource card's Config tab: validated
+  // like the Client itself will, stored at the next revision, and delivered
+  // with its next heartbeat (pendingConfig).
+  function setClientConfig(resourceId, config, { by } = {}){
+    const r = get(resourceId);
+    if (!r){
+      throw Object.assign(new Error('Unknown resource'), { status: 404 });
+    }
+    const { valid, errors } = validateClientConfig(r.type, config);
+    if (!valid){
+      throw Object.assign(new Error(`Invalid ${r.type.toUpperCase()} config: ${errors.join('; ')}`), { status: 400 });
+    }
+    db.prepare('UPDATE resources SET config_desired = ?, config_revision = config_revision + 1, config_error = NULL WHERE id = ?')
+      .run(JSON.stringify(config), resourceId);
+    events.record('resource', resourceId, 'resource.config_saved', { by, revision: get(resourceId).config_revision });
+    return get(resourceId);
+  }
+
+  // { revision, type, config } while the Client hasn't applied the saved one.
+  function pendingConfig(resourceId){
+    const r = get(resourceId);
+    if (!r || !r.config_desired || r.config_applied_revision >= r.config_revision){
+      return null;
+    }
+    return { revision: r.config_revision, type: r.type, config: r.config_desired };
+  }
+
   // Scheduled host reboot (resource card): a cron expression, validated
   // here; '' or null clears it. Delivered on the Client's next heartbeat.
   function setRebootSchedule(resourceId, cron, { by } = {}){
@@ -603,6 +726,11 @@ function createRegistryService(db, { bus, events }){
     remove,
     setRebootSchedule,
     pendingRebootSchedule,
+    setClientConfig,
+    pendingConfig,
+    rename,
+    requestUsbScan,
+    storeUsbScan,
     requestRemoval,
     pendingRemovals,
     findIdleCandidates,

package/src/web/routes.js

@@ -425,6 +425,74 @@ function createWebRouter({ services, config }){
     res.redirect(returnTo(req, '/resources'));
   });
 
+  // "Connected USB devices" tab (public/js/usb-scan.js): Refresh queues a
+  // scan-usb for the Client's next heartbeat; the tab then polls the GET
+  // until the answer is in. JSON both ways — the modal stays open.
+  function usbScanView(req, r){
+    const tz = req.session.user.timezone || 'UTC',
+      scan = r.usb_scan;
+    return {
+      pending: Boolean(r.usb_scan_request_id),
+      requestedAt: r.usb_scan_requested_at,
+      scan: scan ? { ...scan, atText: formatDateTime(scan.at, { timeZone: tz }) } : null
+    };
+  }
+
+  router.post('/resources/:id/usb-scan', requireAdminRole, (req, res) => {
+    try {
+      services.registry.requestUsbScan(req.params.id, { by: req.session.user.username });
+      res.json(usbScanView(req, services.registry.get(req.params.id)));
+    }
+    catch (err){
+      res.status(err.status || 500).json({ error: err.message });
+    }
+  });
+
+  router.get('/resources/:id/usb-scan', (req, res) => {
+    const r = services.registry.get(req.params.id);
+    if (!r){
+      return res.status(404).json({ error: 'Unknown resource' });
+    }
+    res.set('Cache-Control', 'no-store').json(usbScanView(req, r));
+  });
+
+  // Rename (resource card, Name row); empty = back to the Client's own name.
+  router.post('/resources/:id/rename', requireAdminRole, (req, res) => {
+    try {
+      const before = services.registry.get(req.params.id)?.name,
+        r = services.registry.rename(req.params.id, req.body.name, { by: req.session.user.username });
+      if (r.name !== before){
+        flash(req, 'success', `Renamed "${before}" to "${r.name}".` + (r.name_override ? '' : '\nThat\'s the Client\'s own name again.'));
+      }
+    }
+    catch (err){
+      flash(req, 'danger', err.message);
+    }
+    res.redirect(returnTo(req, '/resources'));
+  });
+
+  // Capabilities (resource card, Config tab): public/js/client-config.js
+  // sends the edited hw/sw section as JSON in `config`. Applied by the Client
+  // on its next heartbeat, then it restarts once idle.
+  router.post('/resources/:id/config', requireAdminRole, (req, res) => {
+    try {
+      let config;
+      try {
+        config = JSON.parse(req.body.config || '');
+      }
+      catch {
+        throw Object.assign(new Error('The config form sent no valid JSON — reload the page and try again'), { status: 400 });
+      }
+      const r = services.registry.setClientConfig(req.params.id, config, { by: req.session.user.username });
+      flash(req, 'success', `Capabilities of ${r.name} saved (revision ${r.config_revision}).\n` +
+        'The Client applies them on its next heartbeat, then restarts once it has no job running.');
+    }
+    catch (err){
+      flash(req, 'danger', err.message);
+    }
+    res.redirect(returnTo(req, '/resources'));
+  });
+
   // Scheduled host reboot (resource card): save a cron expression, or clear
   // it; the Client applies it on its next heartbeat.
   router.post('/resources/:id/reboot-schedule', requireAdminRole, (req, res) => {

package/test/scheduler.test.js

@@ -618,6 +618,70 @@ test('reboot now: refused offline or without a helper; cancels a running job fir
   assert.equal(after.message, 'Canceled: user reboot request');
 });
 
+test('capabilities from the dashboard: reported config stored, saved at a new revision, resent until applied', () => {
+  const { registry } = buildTestServices(),
+    { resourceId } = registry.registerAuto({
+      clientId: 'c-cfg', name: 'lab-cfg', type: 'sw', labels: [], capabilities: { sw: { image: 'emu' } },
+      config: { image: 'emu:1', cpus: 2, memory: '2g' }
+    });
+  assert.deepEqual(registry.get(resourceId).client_config, { image: 'emu:1', cpus: 2, memory: '2g' });
+  assert.equal(registry.pendingConfig(resourceId), null);
+
+  assert.throws(() => registry.setClientConfig(resourceId, { memory: 'lots' }), /Invalid SW config: sw\.memory/);
+  const saved = registry.setClientConfig(resourceId, { image: 'emu:2', cpus: 1, memory: '1g', allowJobImages: true });
+  assert.equal(saved.config_revision, 1);
+  assert.deepEqual(registry.pendingConfig(resourceId), { revision: 1, type: 'sw', config: { image: 'emu:2', cpus: 1, memory: '1g', allowJobImages: true } });
+
+  registry.heartbeat(resourceId, { state: 'idle' }); // an older Client: reports nothing
+  assert.equal(registry.pendingConfig(resourceId).revision, 1);
+  registry.heartbeat(resourceId, { state: 'idle', configRevision: 1 });
+  assert.equal(registry.pendingConfig(resourceId), null);
+
+  registry.setClientConfig(resourceId, { image: 'emu:3' });
+  registry.heartbeat(resourceId, { state: 'idle', configRevision: 2, configError: 'Config revision 2 refused: bad' });
+  assert.equal(registry.pendingConfig(resourceId), null); // refused ones aren't resent
+  assert.match(registry.get(resourceId).config_error, /refused: bad/);
+});
+
+test('rename from the dashboard: kept across re-registration, unique, and resettable to the Client\'s own name', () => {
+  const { registry } = buildTestServices(),
+    reg = (name) => registry.get(registry.registerAuto({ clientId: 'c-ren', name, type: 'sw', labels: [] }).resourceId),
+    r = reg('dut1');
+  registerResource(registry, { name: 'taken', type: 'sw' });
+
+  assert.equal(registry.rename(r.id, ' bench-7 ').name, 'bench-7');
+  assert.equal(reg('dut1').name, 'bench-7'); // the Client restarts, still presenting "dut1"
+  assert.equal(registry.get(r.id).reported_name, 'dut1');
+
+  assert.throws(() => registry.rename(r.id, 'taken'), /already used by another Client/);
+  assert.throws(() => registry.rename(r.id, 'has space'), /1-64 letters/);
+
+  const reset = registry.rename(r.id, '');
+  assert.deepEqual([reset.name, reset.name_override], ['dut1', null]);
+  assert.equal(reg('dut2').name, 'dut2'); // no override: the Client's own name again
+});
+
+test('USB scan: only while connected; the answer is kept for the pending request only', () => {
+  const { bus, registry } = buildTestServices(),
+    commands = [],
+    offline = registerResource(registry, { name: 'usb-off', type: 'hw' }),
+    r = registerResource(registry, { name: 'usb-on', type: 'hw' });
+  registry.heartbeat(r.id, { state: 'idle' });
+  bus.on('command', (c) => commands.push(c));
+
+  assert.throws(() => registry.requestUsbScan(offline.id), /offline/);
+  const { requestId } = registry.requestUsbScan(r.id, { by: 'admin' });
+  assert.deepEqual(commands, [{ resourceId: r.id, command: 'scan-usb', requestId }]);
+
+  assert.equal(registry.storeUsbScan(r.id, { requestId: 'stale', output: 'x' }), false);
+  assert.equal(registry.get(r.id).usb_scan, null);
+  assert.equal(registry.storeUsbScan(r.id, { requestId, output: 'Bus 001 Device 004: ID 0483:3748 ST-LINK/V2', error: null }), true);
+  const stored = registry.get(r.id);
+  assert.match(stored.usb_scan.output, /ST-LINK/);
+  assert.equal(stored.usb_scan_request_id, null); // no longer pending
+  assert.equal(registry.storeUsbScan(r.id, { requestId, output: 'again' }), false); // answered once
+});
+
 test('a resource can belong to several groups at once', () => {
   const { registry, groups } = buildTestServices(),
     g1 = groups.create({ name: 'g1' }),

package/test/usb-parse.test.js

@@ -0,0 +1,73 @@
+/**
+ * @file        packages/coordinator/test/usb-parse.test.js
+ * @description Tests: parsing `lsusb -tvv` and sorting devices into a HW Client's config lists ("Import to config")
+ *
+ * @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'),
+  { parseLsusbTree, classifyDevices } = require('../public/js/usb-parse');
+
+const LSUSB = `/:  Bus 001.Port 001: Dev 001, Class=root_hub, Driver=xhci_hcd/12p, 480M
+    ID 1d6b:0002 Linux Foundation 2.0 root hub
+    /sys/bus/usb/devices/usb1  /dev/bus/usb/001/001
+    |__ Port 003: Dev 002, If 0, Class=Hub, Driver=hub/4p, 480M
+        ID 05e3:0610 Genesys Logic, Inc. Hub
+        /sys/bus/usb/devices/1-3  /dev/bus/usb/001/002
+        |__ Port 010: Dev 009, If 0, Class=Vendor Specific Class, Driver=, 12M
+            ID 0483:3748 STMicroelectronics ST-LINK/V2
+            /sys/bus/usb/devices/1-3.10  /dev/bus/usb/001/009
+        |__ Port 002: Dev 005, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 12M
+            ID 0403:6001 Future Technology Devices International, Ltd FT232 Serial (UART) IC
+            /sys/bus/usb/devices/1-3.2  /dev/bus/usb/001/005
+        |__ Port 001: Dev 004, If 0, Class=Vendor Specific Class, Driver=, 12M
+            ID 0483:374b STMicroelectronics ST-LINK/V2.1
+            /sys/bus/usb/devices/1-3.1  /dev/bus/usb/001/004
+        |__ Port 001: Dev 004, If 1, Class=Mass Storage, Driver=usb-storage, 12M
+            ID 0483:374b STMicroelectronics ST-LINK/V2.1
+            /sys/bus/usb/devices/1-3.1  /dev/bus/usb/001/004
+        |__ Port 004: Dev 007, If 0, Class=Vendor Specific Class, Driver=ch341, 12M
+            ID 1a86:7523 QinHeng Electronics CH340 serial converter
+            /sys/bus/usb/devices/1-3.4  /dev/bus/usb/001/007
+    |__ Port 005: Dev 003, If 0, Class=Communications, Driver=cdc_acm, 12M
+        ID 0483:5740 STMicroelectronics Virtual COM Port
+        /sys/bus/usb/devices/1-5  /dev/bus/usb/001/003
+    |__ Port 006: Dev 008, If 0, Class=Human Interface Device, Driver=usbhid, 1.5M
+        ID 046d:c077 Logitech, Inc. Mouse
+        /sys/bus/usb/devices/1-6  /dev/bus/usb/001/008`;
+
+test('parses every device once, with its ids, name, driver and udev devpath', () => {
+  const devices = parseLsusbTree(LSUSB);
+  assert.equal(devices.length, 8); // the ST-Link/V2-1's two interfaces are one device
+  const ftdi = devices.find((d) => d.id === '0403:6001');
+  assert.deepEqual([ftdi.devpath, ftdi.driver, ftdi.sysPath], ['3.2', 'ftdi_sio', '1-3.2']);
+  assert.equal(devices.find((d) => d.sysPath === 'usb1').devpath, null);
+  assert.deepEqual(parseLsusbTree(''), []);
+});
+
+test('sorts devices into the Client\'s lists in port order, with ids only when not the default', () => {
+  const { lists, skipped } = classifyDevices(parseLsusbTree(LSUSB));
+  assert.deepEqual(lists.stlinks.map((d) => [d.devpath, d.vendorId, d.productId]), [['3.1', '0483', '374b'], ['3.10', undefined, undefined]]);
+  assert.deepEqual(lists.uarts.map((d) => [d.devpath, d.id, d.vendorId]), [['3.2', '0403:6001', undefined], ['3.4', '1a86:7523', '1a86']]);
+  assert.deepEqual(lists.usbs.map((d) => d.devpath), ['5']);
+  assert.deepEqual(skipped.map((d) => [d.id, d.reason]), [
+    ['1d6b:0002', 'root hub'], ['05e3:0610', 'hub'], ['046d:c077', 'not a device the Client uses']
+  ]);
+});
+
+test('at most 8 per list; the rest are skipped', () => {
+  const ftdi = { id: '0403:6001', vendorId: '0403', productId: '6001', name: 'FT232', driver: 'ftdi_sio' },
+    many = Array.from({ length: 10 }, (_, i) => ({ ...ftdi, devpath: `2.${i + 1}` })),
+    { lists, skipped } = classifyDevices(many);
+  assert.equal(lists.uarts.length, 8);
+  assert.deepEqual(skipped.map((d) => d.reason), ['more than 8 uarts', 'more than 8 uarts']);
+});

package/test/views.test.js

@@ -0,0 +1,35 @@
+/**
+ * @file        packages/coordinator/test/views.test.js
+ * @description Tests: every dashboard Pug template compiles (catches syntax the Pug parser doesn't support, e.g. ??)
+ *
+ * @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'),
+  path = require('node:path'),
+  pug = require('pug');
+
+const VIEWS = path.join(__dirname, '..', 'views');
+
+function pugFiles(dir){
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
+    e.isDirectory() ? pugFiles(path.join(dir, e.name)) : e.name.endsWith('.pug') ? [path.join(dir, e.name)] : []);
+}
+
+test('every view compiles', () => {
+  const files = pugFiles(VIEWS);
+  assert.ok(files.length > 10);
+  for (const file of files){
+    assert.doesNotThrow(() => pug.compileFile(file), `${path.relative(VIEWS, file)}`);
+  }
+});

package/views/index.pug

@@ -47,3 +47,7 @@ block content
 block scripts
   script(src="/js/resource-card.js")
   script(src="/js/remove-resource.js")
+  script(src="/js/client-config.js")
+  script(src="/js/usb-scan.js")
+  script(src="/js/usb-parse.js")
+  script(src="/js/usb-import.js")

package/views/layout.pug

@@ -12,7 +12,12 @@ html(lang="en" data-bs-theme=(user && user.theme) || "auto")
       .container-fluid
         a.navbar-brand.d-flex.flex-column.lh-1.py-1(href="/")
           span TestHub
-          small.text-body-secondary.fw-normal.mt-1(style="font-size: .7rem;")
+          small.text-body-secondary.fw-normal.mt-1(
+            style="font-size: .7rem;"
+            data-bs-toggle="tooltip"
+            data-bs-placement="bottom"
+            data-bs-title=`Coordinator v${coordinatorVersion} · thub-common v${commonVersion} (validates job specs)`
+          )
             | ver. #{coordinatorVersion}
             if user && user.role !== 'admin' && updates.coordinatorUpdate
               span.badge.text-bg-warning.ms-1(