@andrian.yablonskyy/thub-common 1.1.3 → 1.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-common",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Shared job-spec schema, state enums and a thin API client used by the Agent and Client",
   "main": "src/index.js",
   "files": [

package/src/client-config.js

@@ -16,7 +16,8 @@
 'use strict';
 
 const Ajv = require('ajv'),
-  addFormats = require('ajv-formats');
+  addFormats = require('ajv-formats'),
+  { MAX_POWER_PORTS } = require('./power');
 
 // The config file's key for an HW Client's devices. Older files call it
 // `hw`, still read (and rewritten as `hw-devices` on the next save).
@@ -46,7 +47,29 @@ const HW_DEVICES = 'hw-devices',
     properties: {
       stlinks: list(device({ serial: { type: 'string', pattern: '^[A-Za-z0-9]{1,64}$' } })),
       uarts: list(device({ baudRate: { type: 'integer', minimum: 50, maximum: 4000000 } })),
-      usbs: list(device())
+      usbs: list(device()),
+      // USB port power switched with uhubctl (README §8.7): each port by its
+      // hub's location and port number, as `uhubctl` lists them
+      // ("Current status for hub 1-1.4" … "Port 2").
+      usbPower: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ports: {
+            type: 'array',
+            maxItems: MAX_POWER_PORTS,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              required: ['hub', 'port'],
+              properties: {
+                hub: { type: 'string', pattern: '^[0-9]+(-[0-9]+(\\.[0-9]+)*)?$', maxLength: 64 },
+                port: { type: 'integer', minimum: 1, maximum: 255 }
+              }
+            }
+          }
+        }
+      }
     }
   },
   // An SW Client has no settings of its own: its editable section is empty.
@@ -62,8 +85,8 @@ function hwDevicesOf(file){
   return file?.[HW_DEVICES] !== undefined ? file[HW_DEVICES] : file?.hw;
 }
 
-// An hw-devices section without the power control Clients no longer have
-// (relays, power — relay boards and uhubctl), so a config file that still
+// An hw-devices section without the older power control Clients no longer
+// have (relays, power — relay boards, and uhubctl before usbPower), so a config file that still
 // has them reports, saves and imports without them. Returns
 // { section, dropped } (dropped: the names left out).
 function withoutPowerControl(hw){

package/src/index.js

@@ -22,5 +22,6 @@ module.exports = {
   ...require('./client-config'),
   ...require('./split-args'),
   ...require('./env-list'),
+  ...require('./power'),
   ApiClient: require('./api-client').ApiClient
 };

package/src/job-spec.schema.js

@@ -13,6 +13,8 @@
 
 'use strict';
 
+const { POWER_ACTIONS, MAX_RESET_DELAY_SEC } = require('./power');
+
 // An environment variable name a job may set (`--env NAME=value`).
 const ENV_NAME_PATTERN = '^[A-Za-z_][A-Za-z0-9_]*$',
 
@@ -56,7 +58,7 @@ const ENV_NAME_PATTERN = '^[A-Za-z_][A-Za-z0-9_]*$',
       // Client runs with `sh -c`, `args` as "$@" (`--arg`, repeatable).
       command: { type: 'string', minLength: 1, maxLength: 4096 },
       args: { type: 'array', items: { type: 'string' }, default: [] },
-      // Passed to the command as THUB_SUITE (`--suite`).
+      // Passed to the command as JOB_SUITE (`--suite`).
       suite: { type: 'string', default: 'default' },
       // Files the Client downloads into the task's work directory before
       // running the command (`--download-file`, repeatable).
@@ -92,6 +94,19 @@ const ENV_NAME_PATTERN = '^[A-Za-z_][A-Za-z0-9_]*$',
       // not an identity: nothing authenticates or enforces it.
       user: { type: 'string', minLength: 1 },
       meta: { type: 'object' },
+      // USB port power on the Client (uhubctl, README §8.7) at the job's
+      // start (before the DUT is prepared) and end (whatever the verdict):
+      // `--power-on-start` / `--power-on-end` on|off|reset, and the reset's
+      // off time `--power-reset-delay` (seconds; 1 when not given). HW only.
+      power: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          onStart: { enum: POWER_ACTIONS },
+          onEnd: { enum: POWER_ACTIONS },
+          resetDelaySec: { type: 'number', minimum: 0, maximum: MAX_RESET_DELAY_SEC }
+        }
+      },
       // Exercises the full pipeline (schedule, accept, state transitions,
       // logs, artifact, result) without flashing/running anything for real —
       // see README §7.1 "Dry-run the pipeline".

package/src/power.js

@@ -0,0 +1,46 @@
+/**
+ * @file        packages/shared/src/power.js
+ * @description USB port power (uhubctl on the Client): the actions, the reset delay and the checks on a power
+ *              request — shared by the Agent, the Coordinator and the Client (README §8.7)
+ *
+ * @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';
+
+// `reset`: off, wait the reset delay, on.
+const POWER_ACTIONS = Object.freeze(['on', 'off', 'reset']),
+  DEFAULT_RESET_DELAY_SEC = 1,
+  MAX_RESET_DELAY_SEC = 60,
+  // A Client's hw-devices.usbPower.ports holds at most this many.
+  MAX_POWER_PORTS = 8;
+
+// Errors (strings) for a request to switch a Client's ports: `action` one of
+// POWER_ACTIONS, `delaySec` (reset only, optional) 0..MAX_RESET_DELAY_SEC,
+// `port` (optional) a 1-based position in the Client's usbPower.ports.
+function powerRequestErrors({ action, delaySec, port } = {}){
+  const errors = [];
+  if (!POWER_ACTIONS.includes(action)){
+    errors.push(`action must be one of ${POWER_ACTIONS.join(', ')}`);
+  }
+  if (delaySec !== undefined && delaySec !== null){
+    if (typeof delaySec !== 'number' || !Number.isFinite(delaySec) || delaySec < 0 || delaySec > MAX_RESET_DELAY_SEC){
+      errors.push(`the reset delay (delaySec) must be a number of seconds, 0-${MAX_RESET_DELAY_SEC}`);
+    }
+    else if (action !== 'reset'){
+      errors.push('the reset delay (delaySec) applies to reset only');
+    }
+  }
+  if (port !== undefined && port !== null && (!Number.isInteger(port) || port < 1 || port > MAX_POWER_PORTS)){
+    errors.push(`port must be a usbPower port number, 1-${MAX_POWER_PORTS}`);
+  }
+  return errors;
+}
+
+module.exports = { POWER_ACTIONS, DEFAULT_RESET_DELAY_SEC, MAX_RESET_DELAY_SEC, MAX_POWER_PORTS, powerRequestErrors };

package/src/validate-job-spec.js

@@ -69,6 +69,10 @@ function crossFieldErrors(spec){
   if (reserved.length){
     errors.push(`/env ${reserved.join(', ')}: set by the Client itself (THUB_*, JOB_*) — use other names`);
   }
+  // USB power is an HW Client's (its hw-devices.usbPower ports).
+  if (spec.power && spec.target?.type !== 'hw'){
+    errors.push('/power USB port power is for HW jobs only (--type hw)');
+  }
   return errors;
 }