@andrian.yablonskyy/thub-coordinator 1.1.4 → 1.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-coordinator",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "TestHub Coordinator — job queue, resource registry, scheduler, heartbeat monitor, log/artifact store and web dashboard",
   "main": "src/server.js",
   "engines": {

package/public/js/usb-import.js

@@ -144,8 +144,10 @@
     close.focus();
   }
 
-  document.querySelectorAll('[data-usb-import]').forEach((button) => {
-    button.addEventListener('click', () => {
+  // At the document: the button is swapped by live updates (public/js/live.js).
+  document.addEventListener('click', (e) => {
+    const button = e.target.closest('[data-usb-import]');
+    if (button && !button.disabled){
       const pane = button.closest('[data-usb-scan]'),
         modal = button.closest('.modal'),
         form = modal.querySelector('form[data-client-config="hw"]');
@@ -164,6 +166,6 @@
         bootstrap.Tab.getOrCreateInstance(root.querySelector(`[data-config-tab="${changed}"]`)).show();
       }
       overlay(modal, { total, skipped, changes });
-    });
+    }
   });
 })();

package/public/js/usb-scan.js

@@ -18,82 +18,107 @@
   const POLL_MS = 2000,
     // The Client answers on its next heartbeat (10 s by default); no answer
     // by then means it's too old to know scan-usb, or went away.
-    GIVE_UP_MS = 60_000;
+    GIVE_UP_MS = 60_000,
+    REFRESH_TIP = 'Run lsusb -tvv on the Client now — it answers on its next heartbeat',
+    WAITING_TIP = 'Waiting for the Client to run lsusb -tvv (its next heartbeat)',
+    // The buttons are swapped by live updates (public/js/live.js), so
+    // they're looked up when needed and clicks are handled at the document.
+    timers = new WeakMap(),
+    refreshButton = (pane) => pane.querySelector('[data-usb-refresh-wrap] button');
 
-  document.querySelectorAll('[data-usb-scan]').forEach((pane) => {
-    const url = pane.dataset.usbScan,
-      button = pane.querySelector('[data-usb-refresh]'),
-      status = pane.querySelector('[data-usb-status]'),
-      errorBox = pane.querySelector('[data-usb-error]'),
-      output = pane.querySelector('[data-usb-output]');
-    let timer = null;
-
-    function show(view){
-      if (view.scan){
-        status.textContent = `lsusb -tvv at ${view.scan.atText}`;
-        errorBox.textContent = view.scan.error || '';
-        errorBox.classList.toggle('d-none', !view.scan.error);
-        output.textContent = view.scan.output || '';
-        output.classList.toggle('d-none', !view.scan.output);
-        const importButton = pane.querySelector('[data-usb-import]');
-        if (importButton){
-          importButton.disabled = !view.scan.output;
-        }
-      }
+  // Enable or disable a button in its tooltip wrapper (which says why it's
+  // disabled, or what it does).
+  function setEnabled(wrap, on, tip){
+    const button = wrap?.querySelector('button');
+    if (!button){
+      return;
+    }
+    button.disabled = !on;
+    button.style.pointerEvents = on ? '' : 'none';
+    wrap.tabIndex = on ? -1 : 0;
+    if (tip && wrap.dataset.bsTitle !== tip){
+      bootstrap.Tooltip.getInstance(wrap)?.dispose();
+      wrap.dataset.bsTitle = tip;
     }
+  }
 
-    function waiting(on){
-      if (button){
-        button.disabled = on;
-        button.querySelector('i').className = on ? 'spinner-border spinner-border-sm me-1' : 'bi bi-arrow-clockwise me-1';
-      }
-      if (on){
-        status.textContent = 'Waiting for the Client to run lsusb -tvv (its next heartbeat)…';
-      }
+  function show(pane, view){
+    if (!view.scan){
+      return;
     }
+    const status = pane.querySelector('[data-usb-status]'),
+      errorBox = pane.querySelector('[data-usb-error]'),
+      output = pane.querySelector('[data-usb-output]'),
+      importWrap = pane.querySelector('[data-usb-import-wrap]');
+    status.textContent = `lsusb -tvv at ${view.scan.atText}`;
+    errorBox.textContent = view.scan.error || '';
+    errorBox.classList.toggle('d-none', !view.scan.error);
+    output.textContent = view.scan.output || '';
+    output.classList.toggle('d-none', !view.scan.output);
+    if (importWrap?.dataset.tipEnabled){ // an HW Client that reports its config
+      setEnabled(importWrap, Boolean(view.scan.output), view.scan.output ? importWrap.dataset.tipEnabled : null);
+    }
+  }
 
-    function poll(requestedAt){
-      clearTimeout(timer);
-      timer = setTimeout(async () => {
-        try {
-          const view = await (await fetch(url, { cache: 'no-store', headers: { Accept: 'application/json' } })).json();
-          if (!view.pending && view.scan && view.scan.at >= requestedAt){
-            waiting(false);
-            return show(view);
-          }
-        }
-        catch {
-          // network blip: keep polling
-        }
-        if (Date.now() - Date.parse(requestedAt) > GIVE_UP_MS){
-          waiting(false);
-          status.textContent = 'No answer from the Client — it may be too old to scan USB devices, or offline. Try again later.';
-          return;
-        }
-        poll(requestedAt);
-      }, POLL_MS);
+  function waiting(pane, on){
+    const button = refreshButton(pane);
+    if (button){
+      setEnabled(button.parentElement, !on, on ? WAITING_TIP : REFRESH_TIP);
+      button.querySelector('i').className = on ? 'spinner-border spinner-border-sm me-1' : 'bi bi-arrow-clockwise me-1';
+    }
+    if (on){
+      pane.querySelector('[data-usb-status]').textContent = `${WAITING_TIP}…`;
     }
+  }
 
-    button?.addEventListener('click', async () => {
-      waiting(true);
+  function poll(pane, requestedAt){
+    clearTimeout(timers.get(pane));
+    timers.set(pane, setTimeout(async () => {
       try {
-        const res = await fetch(url, { method: 'POST', headers: { Accept: 'application/json' } }),
-          view = await res.json();
-        if (!res.ok){
-          throw new Error(view.error || `HTTP ${res.status}`);
+        const view = await (await fetch(pane.dataset.usbScan, { cache: 'no-store', headers: { Accept: 'application/json' } })).json();
+        if (!view.pending && view.scan && view.scan.at >= requestedAt){
+          waiting(pane, false);
+          return show(pane, view);
         }
-        poll(view.requestedAt);
       }
-      catch (err){
-        waiting(false);
-        status.textContent = `Couldn't ask the Client: ${err.message}`;
+      catch {
+        // network blip: keep polling
       }
-    });
+      if (Date.now() - Date.parse(requestedAt) > GIVE_UP_MS){
+        waiting(pane, false);
+        pane.querySelector('[data-usb-status]').textContent = 'No answer from the Client — it may be too old to scan USB devices, or offline. Try again later.';
+        return;
+      }
+      poll(pane, requestedAt);
+    }, POLL_MS));
+  }
 
-    // A request still pending when the page loaded (e.g. after a reload).
+  document.addEventListener('click', async (e) => {
+    const button = e.target.closest('[data-usb-refresh]'),
+      pane = button?.closest('[data-usb-scan]');
+    if (!pane || button.disabled){
+      return;
+    }
+    waiting(pane, true);
+    try {
+      const res = await fetch(pane.dataset.usbScan, { method: 'POST', headers: { Accept: 'application/json' } }),
+        view = await res.json();
+      if (!res.ok){
+        throw new Error(view.error || `HTTP ${res.status}`);
+      }
+      poll(pane, view.requestedAt);
+    }
+    catch (err){
+      waiting(pane, false);
+      pane.querySelector('[data-usb-status]').textContent = `Couldn't ask the Client: ${err.message}`;
+    }
+  });
+
+  // A request still pending when the page loaded (e.g. after a reload).
+  document.querySelectorAll('[data-usb-scan]').forEach((pane) => {
     if (pane.dataset.pending && pane.dataset.requestedAt){
-      waiting(true);
-      poll(pane.dataset.requestedAt);
+      waiting(pane, true);
+      poll(pane, pane.dataset.requestedAt);
     }
   });
 })();

package/src/api/resource.js

@@ -87,6 +87,18 @@ function createResourceRouter({ services, config }){
     res.status(stored ? 204 : 409).end();
   });
 
+  // A Client that doesn't re-register on start (no joinKey) reports its
+  // config here instead, so Export, Import and the config tabs work for it.
+  router.post('/resources/:id/config-report', auth, requireOwnResource, (req, res, next) => {
+    try {
+      services.registry.reportClientConfig(req.params.id, { config: req.body?.config, configFile: req.body?.configFile });
+      res.status(204).end();
+    }
+    catch (err){
+      next(err);
+    }
+  });
+
   router.post('/resources/:id/heartbeat', auth, requireOwnResource, (req, res, next) => {
     try {
       const { state, activeJobId, localLock, metrics, addresses, hostUptimeSec, activity, rebootSchedule, configRevision, configError } = req.body;

package/src/db/migrations/027_scrub_config_file_secrets.sql

@@ -0,0 +1,4 @@
+-- A Client's reported config file is kept for Export (README §10), but
+-- never its credentials: drop the joinKey copies stored before that.
+UPDATE resources SET client_config_file = json_remove(client_config_file, '$.joinKey')
+  WHERE client_config_file IS NOT NULL AND json_extract(client_config_file, '$.joinKey') IS NOT NULL;

package/src/services/registry.js

@@ -18,11 +18,36 @@ const { v4: uuid } = require('uuid'),
     shareableClientConfigFile, HW_DEVICES_SECTION } = require('@andrian.yablonskyy/thub-common'),
   { generateToken, hashToken } = require('./tokens');
 
+// Never kept from or put in a Client's config file: its credentials.
+const CONFIG_FILE_SECRETS = ['joinKey'],
+  // The first Client that applies a whole config file (an Import's other
+  // fields, the Groups tab), not only its hw-devices section.
+  CONFIG_FILE_CLIENT = '1.0.30';
+
+function withoutSecrets(file){
+  const out = shareableClientConfigFile(file);
+  for (const key of CONFIG_FILE_SECRETS){
+    delete out[key];
+  }
+  return out;
+}
+
+// What a Client can take from the dashboard's Import: 'file' — a whole
+// config file (it reports its file, or is new enough to apply one even if
+// it never has, e.g. without a joinKey it doesn't re-register on start);
+// 'section' — an older HW Client's devices only; null — nothing.
+function configSupport(r){
+  if (r.client_config_file || (r.client_version && compareVersions(r.client_version, CONFIG_FILE_CLIENT) >= 0)){
+    return 'file';
+  }
+  return r.type === 'hw' && (r.client_config || r.config_desired) ? 'section' : null;
+}
+
 function rowToResource(row){
   if (!row){
     return row;
   }
-  return {
+  const r = {
     ...row,
     labels: JSON.parse(row.labels || '[]'),
     group_ids: JSON.parse(row.group_ids || '[]'),
@@ -35,6 +60,8 @@ function rowToResource(row){
     usb_scan: row.usb_scan ? JSON.parse(row.usb_scan) : null,
     activity: row.activity ? JSON.parse(row.activity) : null
   };
+  r.config_support = configSupport(r);
+  return r;
 }
 
 // host_info.addresses comes straight from the Client, so keep only
@@ -198,19 +225,36 @@ function createRegistryService(db, { bus, events }){
     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)){
+    storeConfigReport(result.resourceId, { config, configFile });
+    return result;
+  }
+
+  // The Client's config as it runs it: its hw-devices section (`config`)
+  // and its whole file (`configFile`, credentials dropped). Sent with every
+  // registration, and on start by a Client that doesn't re-register (no
+  // joinKey) — POST /resources/:id/config-report.
+  function storeConfigReport(resourceId, { config, configFile }){
+    const isObject = (v) => v && typeof v === 'object' && !Array.isArray(v);
+    if (isObject(config)){
       const json = JSON.stringify(config);
       if (json.length <= 64 * 1024){
-        db.prepare('UPDATE resources SET client_config = ? WHERE id = ?').run(json, result.resourceId);
+        db.prepare('UPDATE resources SET client_config = ? WHERE id = ?').run(json, resourceId);
       }
     }
-    if (configFile && typeof configFile === 'object' && !Array.isArray(configFile)){
-      const json = JSON.stringify(shareableClientConfigFile(configFile));
+    if (isObject(configFile)){
+      const json = JSON.stringify(withoutSecrets(configFile));
       if (json.length <= 64 * 1024){
-        db.prepare('UPDATE resources SET client_config_file = ? WHERE id = ?').run(json, result.resourceId);
+        db.prepare('UPDATE resources SET client_config_file = ? WHERE id = ?').run(json, resourceId);
       }
     }
-    return result;
+  }
+
+  function reportClientConfig(resourceId, report){
+    if (!get(resourceId)){
+      throw Object.assign(new Error('Unknown resource'), { status: 404 });
+    }
+    storeConfigReport(resourceId, report || {});
+    return get(resourceId);
   }
 
   function registerAutoInner({ clientId, name, type, labels = [], groups = [], hostInfo, capabilities, remoteAddr, clientVersion = null }){
@@ -691,18 +735,30 @@ function createRegistryService(db, { bus, events }){
     if (!r){
       throw Object.assign(new Error('Unknown resource'), { status: 404 });
     }
-    const { valid, errors, section, fields, ignored } = importClientConfigFile(r.type, file);
+    if (!r.config_support){
+      throw Object.assign(new Error(`Can't import a config into ${r.name}: its Client is too old to apply one — update it first`), { status: 409 });
+    }
+    const { valid, errors, section, fields: fileFields, ignored } = importClientConfigFile(r.type, file);
     if (!valid){
       throw Object.assign(new Error(`Can't import this config into ${r.name}: ${errors.join('; ')}`), { status: 400 });
     }
+    // An older HW Client applies its devices only: the rest is listed as
+    // ignored rather than sent to be dropped.
+    let fields = fileFields;
+    if (r.config_support === 'section'){
+      ignored.push(...Object.keys(fileFields).map((k) => `${k} (this Client applies only its devices — update it for the rest)`));
+      fields = {};
+    }
     const desired = section || currentSection(r);
     if (!desired){
       throw Object.assign(new Error(`Can't import this config into ${r.name}: it has no "${HW_DEVICES_SECTION}" section, and the Client hasn't reported one`),
         { status: 400 });
     }
-    const revision = r.config_revision + 1;
+    const revision = r.config_revision + 1,
+      // An older Client gets no `file` at all: it wouldn't apply one.
+      importJson = r.config_support === 'file' ? JSON.stringify({ revision, fields }) : null;
     db.prepare(`UPDATE resources SET config_desired = ?, config_revision = ?, config_error = NULL, config_import = ?
-                WHERE id = ?`).run(JSON.stringify(desired), revision, JSON.stringify({ revision, fields }), resourceId);
+                WHERE id = ?`).run(JSON.stringify(desired), revision, importJson, resourceId);
     events.record('resource', resourceId, 'resource.config_imported', { by, revision, fields: Object.keys(fields), ignored });
     return { resource: get(resourceId), ignored };
   }
@@ -726,7 +782,7 @@ function createRegistryService(db, { bus, events }){
     // Writing top-level fields needs a Client that reports its config file
     // (the same that Import needs); an older one would drop them.
     const desired = currentSection(r);
-    if (!desired || !r.client_config_file){
+    if (!desired || r.config_support !== 'file'){
       throw Object.assign(new Error(`${r.name} is too old to take its groups from the dashboard — update its Client first`), { status: 409 });
     }
     const revision = r.config_revision + 1,
@@ -750,7 +806,7 @@ function createRegistryService(db, { bus, events }){
       throw Object.assign(new Error('Unknown resource'), { status: 404 });
     }
     // Re-shared: a file stored from an older Client may still say hw / sw.
-    const base = shareableClientConfigFile(r.client_config_file || { name: r.reported_name || r.name, type: r.type, labels: r.labels }),
+    const base = withoutSecrets(r.client_config_file || { name: r.reported_name || r.name, type: r.type, labels: r.labels, groups: r.group_ids }),
       section = r.type === 'hw' ? currentSection(r) : null;
     return { ...base, ...(pendingImport(r) || {}), type: r.type, ...(section ? { [HW_DEVICES_SECTION]: section } : {}) };
   }
@@ -821,6 +877,7 @@ function createRegistryService(db, { bus, events }){
 
   return {
     get,
+    reportClientConfig,
     getByName,
     getByClientId,
     getByTokenHash,

package/src/web/routes.js

@@ -205,6 +205,9 @@ function createWebRouter({ services, config }){
     // dd/mm/yyyy HH:MM:SS, 24-hour (thub-common formatDateTime) — the one
     // format for every date/time label.
     res.locals.fmtDate = (iso, fallback = '—') => formatDateTime(iso, { timeZone: tz, fallback });
+    // Why a Client's config can't be edited or imported on its card
+    // (registry.js configSupport, README §10).
+    res.locals.noConfigReport = 'this Client is too old to report or apply its config from the dashboard — update it.';
     res.locals.userTimeZone = tz;
 
     // Idle timeout (§10.1): re-applied on every request (not just login)

package/test/groups-tab.test.js

@@ -140,3 +140,61 @@ test('ST-Link tab has no Serial field; a serial set in the config file is kept o
   // Rides along in data-extra, which public/js/client-config.js spreads back into the row.
   assert.match(table, /data-extra="\{"serial":"066DFF48"\}"/);
 });
+
+test('resource card: USB actions update live and every disabled button says why', async (t) => {
+  const { base, services, admin } = await start(t),
+    reg = services.registry.registerAuto({
+      clientId: 'hw3', name: 'lab-hw-03', type: 'hw', labels: [], config: { stlinks: [{ index: 1 }] }, configFile: { name: 'lab-hw-03', type: 'hw' }
+    }),
+    card = async () => {
+      const html = await (await fetch(`${base}/resources`, { headers: { cookie: admin } })).text();
+      return html.slice(html.indexOf(`id="resource-card-${reg.resourceId}"`));
+    };
+  let html = await card();
+  // A live region, so a Client coming back online gets Refresh back without a reload.
+  assert.match(html, new RegExp(`data-live="rc-usb-actions-${reg.resourceId}"`));
+  assert.match(html, /"Offline — a Client can only be scanned while it(&#39;|.)s connected" data-usb-refresh-wrap(="[^"]*")?><button[^>]*disabled/);
+  assert.match(html, /data-bs-title="Nothing to import yet — press Refresh to scan the Client first"[^>]*><button[^>]*disabled/);
+
+  services.registry.heartbeat(reg.resourceId, { state: 'IDLE' });
+  html = await card();
+  assert.match(html, /data-bs-title="Run lsusb -tvv on the Client now[^"]*" data-usb-refresh-wrap(="[^"]*")?><button [^>]*data-usb-refresh="">/);
+  assert.doesNotMatch(html, /data-usb-refresh-wrap(="[^"]*")?><button[^>]*disabled/);
+  // Every disabled button in the card sits in a tooltip wrapper that says why.
+  const disabled = [...html.matchAll(/(<span[^>]*data-bs-title="([^"]*)"[^>]*>)?<button[^>]*\sdisabled[^>]*>/g)];
+  assert.ok(disabled.every((m) => m[2]), disabled.filter((m) => !m[2]).map((m) => m[0]).join('\n'));
+});
+
+test('Import and Export work for a Client that doesn\'t re-register (no joinKey): it reports its config on start', async (t) => {
+  const { base, services, admin } = await start(t),
+    { resourceId, resourceToken } = services.registry.registerAuto({ clientId: 'hw4', name: 'lab-hw-04', type: 'hw', labels: [] }),
+    card = async () => {
+      const html = await (await fetch(`${base}/resources`, { headers: { cookie: admin } })).text();
+      return html.slice(html.indexOf(`id="resource-card-${resourceId}"`));
+    };
+  assert.match(await card(), /Import unavailable: this Client is too old/); // nothing reported, no version known
+
+  const res = await fetch(`${base}/api/v1/resources/${resourceId}/config-report`, {
+    method: 'POST',
+    headers: { authorization: `Bearer ${resourceToken}`, 'content-type': 'application/json', 'x-thub-client-version': '1.1.1' },
+    body: JSON.stringify({
+      config: { stlinks: [{ index: 1, devpath: '1.1' }] },
+      configFile: {
+        coordinatorUrl: 'https://c', name: 'lab-hw-04', type: 'hw', joinKey: 'secret', labels: [], 'hw-devices': { stlinks: [{ index: 1, devpath: '1.1' }] }
+      }
+    })
+  });
+  assert.equal(res.status, 204);
+  const html = await card();
+  assert.match(html, /data-config-import-pick/); // Import enabled
+  assert.doesNotMatch(html, /Import unavailable/);
+  const exported = await (await fetch(`${base}/resources/${resourceId}/config/export`, { headers: { cookie: admin } })).json();
+  assert.equal(exported.joinKey, undefined);
+  assert.deepEqual(exported['hw-devices'], { stlinks: [{ index: 1, devpath: '1.1' }] });
+
+  // Another resource's token can't report for it.
+  const other = services.registry.registerAuto({ clientId: 'hw5', name: 'lab-hw-05', type: 'hw', labels: [] });
+  assert.equal((await fetch(`${base}/api/v1/resources/${resourceId}/config-report`, {
+    method: 'POST', headers: { authorization: `Bearer ${other.resourceToken}`, 'content-type': 'application/json' }, body: '{}'
+  })).status, 403);
+});

package/test/scheduler.test.js

@@ -680,8 +680,8 @@ test('config export/import: exported from the reported file (+ what\'s pending);
       configFile: { coordinatorUrl: 'https://c', name: 'dut1', joinKey: 'k', type: 'hw', labels: [], hw: { uarts: [{ index: 1 }] },
         sw: { image: 'emu:1', registryAuth: { password: 'x' } }, artifactory: { token: 'secret', allowedArtifactPrefixes: [] } }
     });
-  assert.deepEqual(registry.exportClientConfig(resourceId), {
-    coordinatorUrl: 'https://c', name: 'dut1', joinKey: 'k', type: 'hw', labels: [], 'hw-devices': { uarts: [{ index: 1 }] }
+  assert.deepEqual(registry.exportClientConfig(resourceId), { // never the joinKey
+    coordinatorUrl: 'https://c', name: 'dut1', type: 'hw', labels: [], 'hw-devices': { uarts: [{ index: 1 }] }
   });
 
   const { resource, ignored } = registry.importClientConfig(resourceId, {
@@ -797,3 +797,41 @@ test('deleting a group strips it from every resource that listed it, without tou
   assert.equal(groups.get(g1.id), undefined);
   assert.ok(groups.get(g2.id));
 });
+
+test('config import: what each Client can take — a whole file, an older HW Client\'s devices only, or nothing', () => {
+  const { registry } = buildTestServices(),
+    reg = (clientId, type, clientVersion, extra = {}) =>
+      registry.registerAuto({ clientId, name: clientId, type, labels: [], clientVersion, ...extra }).resourceId,
+    // Never reported its file (no joinKey: it doesn't re-register), but new enough to apply one.
+    fresh = reg('fresh', 'hw', '1.1.1', { config: { uarts: [{ index: 1 }] } }),
+    oldHw = reg('old-hw', 'hw', '1.0.20', { config: { uarts: [{ index: 1 }] } }),
+    oldSw = reg('old-sw', 'sw', '1.0.20');
+  assert.deepEqual([fresh, oldHw, oldSw].map((id) => registry.get(id).config_support), ['file', 'section', null]);
+
+  const file = { type: 'hw', labels: ['board:b'], heartbeatIntervalSec: 20, 'hw-devices': { usbs: [{ index: 2 }] } };
+  assert.deepEqual(registry.importClientConfig(fresh, file, { by: 'a' }).ignored, []);
+  assert.deepEqual(registry.pendingConfig(fresh).file, { labels: ['board:b'], heartbeatIntervalSec: 20 });
+
+  const { ignored } = registry.importClientConfig(oldHw, file, { by: 'a' }),
+    why = '(this Client applies only its devices — update it for the rest)';
+  assert.deepEqual(ignored, [`labels ${why}`, `heartbeatIntervalSec ${why}`]);
+  assert.deepEqual(registry.pendingConfig(oldHw), { revision: 1, type: 'hw', config: { usbs: [{ index: 2 }] } }); // no `file` for it
+  assert.throws(() => registry.importClientConfig(oldSw, { type: 'sw' }, { by: 'a' }), /too old to apply one/);
+
+  // Reported later (POST /resources/:id/config-report): kept without the joinKey.
+  registry.reportClientConfig(oldSw, { configFile: { coordinatorUrl: 'https://c', name: 'old-sw', type: 'sw', joinKey: 'secret', labels: [] } });
+  assert.equal(registry.get(oldSw).client_config_file.joinKey, undefined);
+  assert.equal(registry.get(oldSw).config_support, 'file');
+  assert.equal(registry.exportClientConfig(oldSw).joinKey, undefined);
+});
+
+test('migration 027 drops joinKey copies from stored config files', () => {
+  const Database = require('better-sqlite3'),
+    db = new Database(':memory:');
+  db.exec('CREATE TABLE resources (id TEXT, client_config_file TEXT)');
+  db.prepare('INSERT INTO resources VALUES (?, ?)').run('a', JSON.stringify({ name: 'a', joinKey: 'k', labels: [] }));
+  db.prepare('INSERT INTO resources VALUES (?, ?)').run('b', null);
+  db.exec(require('node:fs').readFileSync(require('node:path').join(__dirname, '../src/db/migrations/027_scrub_config_file_secrets.sql'), 'utf8'));
+  assert.deepEqual(JSON.parse(db.prepare('SELECT client_config_file FROM resources WHERE id = ?').get('a').client_config_file), { name: 'a', labels: [] });
+  assert.equal(db.prepare('SELECT client_config_file FROM resources WHERE id = ?').get('b').client_config_file, null);
+});

package/views/help/_client-setup.pug

@@ -105,6 +105,8 @@
     Admins can also edit an HW Client's devices from its resource card (#[strong ST-Link | UART | DUT USB]
     tabs). The tabs show the config the Client runs, as it reported it at its last start, or a saved
     change it hasn't applied yet. #[strong Connected USB devices → Import to config] fills them from the host's #[code lsusb].
+    The card's #[strong Export] and #[strong Import] icons download a Client's config file (never its
+    #[code joinKey]) and apply one to it. An older HW Client takes only the file's #[code hw-devices].
     There's no ST-Link serial field: the job's #[code --command] picks the probe
     (#[code $THUB_DUT_STLINK_<n>]), and the Client reads each serial from its udev symlink.
 

package/views/mixins/client-config.pug

@@ -16,13 +16,13 @@ mixin deviceRow(kind, d)
       td: input.form-control.form-control-sm(data-f="baudRate" type="number" min="50" value=d && d.baudRate || '' placeholder="115200")
     td: input.form-control.form-control-sm.font-monospace(data-f="devpath" value=d && d.devpath || '' placeholder="3.3.4.1")
     td.text-end
-      button.btn.btn-sm.btn-outline-secondary(type="button" data-remove-row aria-label="Remove row")
+      button.btn.btn-sm.btn-outline-secondary(type="button" data-remove-row aria-label="Remove row" data-bs-toggle="tooltip" data-bs-title="Remove this device (saved with Save capabilities)")
         i.bi.bi-x-lg
 
 mixin deviceTable(kind, title, rows, columns)
   .d-flex.justify-content-between.align-items-center.mb-1
     strong.small= title
-    button.btn.btn-sm.btn-outline-primary(type="button" data-add-row=kind)
+    button.btn.btn-sm.btn-outline-primary(type="button" data-add-row=kind data-bs-toggle="tooltip" data-bs-title="Add a device row (saved with Save capabilities)")
       i.bi.bi-plus-lg.me-1
       | Add
   table.table.table-sm.align-middle.mb-0(data-table=kind)
@@ -69,7 +69,7 @@ mixin configPane(p, key)
 mixin saveCapabilities(canEdit)
   if canEdit
     .d-flex.justify-content-end.mt-3
-      button.btn.btn-sm.btn-primary(type="submit") Save capabilities
+      button.btn.btn-sm.btn-primary(type="submit" data-bs-toggle="tooltip" data-bs-title="Save the ST-Link, UART and DUT USB tabs — the Client applies them on its next heartbeat and restarts once idle") Save capabilities
 
 //- Where the saved capabilities stand, at the top of each capability tab.
 mixin capabilitiesStatus(r)
@@ -119,8 +119,8 @@ mixin groupsPane(r, returnTo, groupsById)
           ) not written to the Client yet
         if r.config_error
           span.badge.text-bg-danger(data-bs-toggle="tooltip" data-bs-title=r.config_error) refused by the Client
-    if !r.client_config_file
-      p.small.text-body-secondary This Client is too old to take its groups from the dashboard — update it, or set #[code groups] in its config file.
+    if r.config_support !== 'file'
+      p.small.text-body-secondary Groups can't be set here: #{noConfigReport} Or set #[code groups] in its config file.
     if !all.length && !unknown.length
       p.small.text-body-secondary.mb-0
         | No groups exist yet.
@@ -136,7 +136,7 @@ mixin groupsPane(r, returnTo, groupsById)
         data-confirm-tone="primary"
       )
         input(type="hidden" name="returnTo" value=returnTo)
-        fieldset(disabled=!canEdit || !r.client_config_file)
+        fieldset(disabled=!canEdit || r.config_support !== 'file')
           .list-group.mb-2
             each g in all
               label.list-group-item.d-flex.gap-2.align-items-start
@@ -155,9 +155,9 @@ mixin groupsPane(r, returnTo, groupsById)
                   br
                   code.small.text-body-secondary= id
           .form-text A job run with #[code thub run --group <id>] is scheduled only on Clients in that group; one that asks for no group can run on any Client.
-          if canEdit && r.client_config_file
+          if canEdit && r.config_support === 'file'
             .d-flex.justify-content-end.mt-3
-              button.btn.btn-sm.btn-primary(type="submit") Save groups
+              button.btn.btn-sm.btn-primary(type="submit" data-bs-toggle="tooltip" data-bs-title="Save the groups — in effect at once; the Client writes them to its config file") Save groups
 
 mixin configPanes(r, returnTo, groupsById)
   - const p = `cfg-${r.id}`
@@ -174,7 +174,7 @@ mixin configPanes(r, returnTo, groupsById)
   else if !current
     each t in [['stlinks', 'ST-Link'], ['uarts', 'UART'], ['usbs', 'DUT USB']]
       +configPane(p, t[0])
-        p.small.text-body-secondary.mb-0 This Client is too old to report its config — update it to edit its devices here.
+        p.small.text-body-secondary.mb-0 Devices can't be edited here: #{noConfigReport}
   else
     form(
       method="post"

package/views/mixins/resource.pug

@@ -246,12 +246,12 @@ mixin rebootScheduleRow(r, returnTo)
           aria-label=`Reboot schedule for ${r.name} (cron)`
           required
         )
-        button.btn.btn-sm.btn-outline-primary(type="submit") Save
+        button.btn.btn-sm.btn-outline-primary(type="submit" data-bs-toggle="tooltip" data-bs-title="Save this schedule — the Client applies it on its next heartbeat") Save
       if r.reboot_schedule
         form.d-inline(method="post" action=`/resources/${r.id}/reboot-schedule`)
           input(type="hidden" name="returnTo" value=returnTo)
           input(type="hidden" name="clear" value="1")
-          button.btn.btn-sm.btn-link.p-0.small(type="submit") Clear schedule
+          button.btn.btn-sm.btn-link.p-0.small(type="submit" data-bs-toggle="tooltip" data-bs-title="Remove the schedule — the host isn't rebooted on a schedule any more") Clear schedule
       .form-text
         | cron: minute hour day month weekday, in the host's local time#{tz ? ` (${tz})` : ''} — e.g.
         |
@@ -337,33 +337,27 @@ mixin usbScanPane(r)
   - const scan = r.usb_scan
   //- Import to config (public/js/usb-import.js): HW Clients that report
   //- their config only; enabled once there's a scan to import from.
-  - const importWhy = r.type !== 'hw' ? 'Only HW Clients have USB device lists to import into' : !(r.config_desired || r.client_config) ? 'This Client is too old to report its config — update it first' : null
+  - const importWhy = r.type !== 'hw' ? 'Only HW Clients have USB device lists to import into' : !(r.config_desired || r.client_config) ? noConfigReport[0].toUpperCase() + noConfigReport.slice(1) : null
   div(data-usb-scan=`/resources/${r.id}/usb-scan` data-pending=r.usb_scan_request_id ? '1' : null data-requested-at=r.usb_scan_requested_at)
     .d-flex.align-items-center.gap-2.mb-2
       if can.operate
-        if offline
-          span.d-inline-block(tabindex="0" data-bs-toggle="tooltip" data-bs-title="Offline — a Client can only be scanned while it's connected")
-            button.btn.btn-sm.btn-outline-primary(type="button" disabled style="pointer-events: none;")
-              i.bi.bi-arrow-clockwise.me-1
+        //- Live (public/js/live.js): a Client that comes back online gets its
+        //- Refresh back without a reload. Each button sits in a tooltip
+        //- wrapper, so a disabled one still says why (usb-scan.js and
+        //- usb-import.js handle clicks at the document, as these get replaced).
+        - const pending = Boolean(r.usb_scan_request_id)
+        - const refreshWhy = pending ? 'Waiting for the Client to run lsusb -tvv (its next heartbeat)' : offline ? 'Offline — a Client can only be scanned while it\'s connected' : null
+        - const importTip = 'Fill the ST-Link, UART and DUT USB tabs from this scan, for you to review and save'
+        - const importOff = importWhy || (!(scan && scan.output) ? 'Nothing to import yet — press Refresh to scan the Client first' : null)
+        span.d-inline-flex.gap-2(data-live=`rc-usb-actions-${r.id}`)
+          span.d-inline-block(tabindex=refreshWhy ? '0' : null data-bs-toggle="tooltip" data-bs-title=refreshWhy || 'Run lsusb -tvv on the Client now — it answers on its next heartbeat' data-usb-refresh-wrap)
+            button.btn.btn-sm.btn-outline-primary(type="button" data-usb-refresh=offline ? null : '' disabled=Boolean(refreshWhy) style=refreshWhy ? 'pointer-events: none;' : null)
+              i.me-1(class=pending ? 'spinner-border spinner-border-sm' : 'bi bi-arrow-clockwise')
               | Refresh
-        else
-          button.btn.btn-sm.btn-outline-primary(type="button" data-usb-refresh)
-            i.bi.bi-arrow-clockwise.me-1
-            | Refresh
-        if importWhy
-          span.d-inline-block(tabindex="0" data-bs-toggle="tooltip" data-bs-title=importWhy)
-            button.btn.btn-sm.btn-outline-secondary(type="button" disabled style="pointer-events: none;")
+          span.d-inline-block(tabindex=importOff ? '0' : null data-bs-toggle="tooltip" data-bs-title=importOff || importTip data-usb-import-wrap data-tip-enabled=importWhy ? null : importTip)
+            button.btn.btn-sm.btn-outline-secondary(type="button" data-usb-import=importWhy ? null : '' disabled=Boolean(importOff) style=importOff ? 'pointer-events: none;' : null)
               i.bi.bi-box-arrow-in-down.me-1
               | Import to config
-        else
-          button.btn.btn-sm.btn-outline-secondary(
-            type="button"
-            data-usb-import
-            disabled=!(scan && scan.output)
-            title="Fill the ST-Link, UART and DUT USB tabs from this scan, for you to review and save"
-          )
-            i.bi.bi-box-arrow-in-down.me-1
-            | Import to config
       span.small.text-body-secondary(data-usb-status)
         if scan
           = `lsusb -tvv at ${fmtDate(scan.at)}`
@@ -406,8 +400,8 @@ mixin rebootButton(r, returnTo)
 //- Export / Import the Client's config file as JSON (card's Actions row,
 //- icons only). Import: public/js/config-import.js reads the chosen file
 //- into the form and submits it (confirmed first); the Client applies it on
-//- its next heartbeat. A Client that doesn't report its config file is too
-//- old to apply more than the hw/sw section — Import is off for it.
+//- its next heartbeat. What it can apply: r.config_support (registry.js) —
+//- a whole file, or an older HW Client's devices only.
 mixin configTransferButtons(r, returnTo)
   a.btn.btn-sm.btn-outline-secondary.ms-1(
     href=`/resources/${r.id}/config/export`
@@ -417,8 +411,8 @@ mixin configTransferButtons(r, returnTo)
     data-bs-title="Export the Client's config file (JSON; its secrets left out)"
   )
     i.bi.bi-download
-  if !r.client_config_file
-    span.d-inline-block.ms-1(tabindex="0" data-bs-toggle="tooltip" data-bs-title="Import unavailable: this Client is too old to report its config file — update it")
+  if !r.config_support
+    span.d-inline-block.ms-1(tabindex="0" data-bs-toggle="tooltip" data-bs-title="Import unavailable: this Client is too old to apply a config from the dashboard — update it")
       button.btn.btn-sm.btn-outline-secondary(type="button" disabled style="pointer-events: none;" aria-label="Import config")
         i.bi.bi-upload
   else
@@ -440,7 +434,7 @@ mixin configTransferButtons(r, returnTo)
         aria-label=`Import a config into ${r.name}`
         data-config-import-pick
         data-bs-toggle="tooltip"
-        data-bs-title="Import a config file (JSON) — joinKey, coordinatorUrl and name in it are ignored"
+        data-bs-title=r.config_support === 'file' ? 'Import a config file (JSON) — joinKey, coordinatorUrl and name in it are ignored' : 'Import a config file (JSON) — this Client is older: only its hw-devices are applied (update it for the rest)'
       )
         i.bi.bi-upload
 
@@ -476,7 +470,7 @@ mixin resourceDetails(r, groupsById, returnTo, local, external)
               placeholder=r.reported_name || ''
               aria-label=`New name for ${r.name}`
             )
-            button.btn.btn-sm.btn-primary(type="submit") Rename
+            button.btn.btn-sm.btn-primary(type="submit" data-bs-toggle="tooltip" data-bs-title="Save the new name — kept across the Client's restarts") Rename
           .form-text Kept across the Client's restarts. Empty = back to the Client's own name#{r.reported_name ? ` (${r.reported_name})` : ''}.
     dt.col-sm-4 Type
     dd.col-sm-8.text-uppercase= r.type