@andrian.yablonskyy/thub-common 1.0.23 → 1.0.25

package/README.md

@@ -21,12 +21,13 @@ const { validateJobSpec } = require('@andrian.yablonskyy/thub-common');
 
 const { valid, spec, errors } = validateJobSpec({
   target: { type: 'hw', labels: ['board:nucleo-f401re'] },
-  firmware: { url: 'https://artifactory.example.com/app.bin' },
-  tests: { url: 'https://artifactory.example.com/tests.tar.gz' }
+  command: './ci/test.sh',
+  downloads: [{ url: 'https://artifactory.example.com/app.bin' }],
+  git: { url: 'https://github.com/yourorg/firmware-tests.git', ref: 'v1.4.0' }
 });
 ```
 
-The schema deliberately has no field for shell commands — a job only ever names a firmware image and a test package; the Client runs a fixed entry point (`run-tests.sh`) from that package, never arbitrary code from the spec itself. Top-level fields: `target` (`type`, `labels`, optional `group`), `firmware` (`url`, optional `sha256`/`flashAddress`), `tests` (`url`, `suite`, `args`), `timeoutSec`, `priority`, `source` (`ci`/`cli`), `user` (a free-text job-owner label), `meta` (arbitrary key/value metadata), and `dryRun`.
+A job is a task: `command` (required — the shell command the Client runs as its entry point, `args` as `"$@"`), with optional inputs `downloads` (`[{ url }]`), `git` (`url`, optional `ref` — branch, tag or commit — and `depth`, default 1) and, for SW jobs, `image` (a Docker image to run as the DUT). Other top-level fields: `target` (`type`, `labels`, optional `group`/`client`), `suite`, `timeoutSec`, `priority`, `source` (`ci`/`cli`), `user` (a free-text job-owner label), `meta` (arbitrary key/value metadata), and `dryRun`. A spec in the old shape (`firmware`/`tests`, from an Agent older than `--command`) is refused with a message to update the Agent.
 
 ### State enums and exit codes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-common",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "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

@@ -0,0 +1,117 @@
+/**
+ * @file        packages/shared/src/client-config.js
+ * @description Schema and validation for the part of a Client's config that can be edited from the dashboard
+ *              (its capabilities: the `hw` or `sw` section) — used by the Coordinator on Save and by the Client
+ *              before applying it
+ *
+ * @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 Ajv = require('ajv'),
+  addFormats = require('ajv-formats'),
+  { DOCKER_IMAGE_PATTERN } = require('./job-spec.schema');
+
+const MAX_DEVICES = 8,
+  device = (extra = {}) => ({
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      // udev index N -> /dev/thub/dut<N>-<kind>, or an explicit path.
+      index: { type: 'integer', minimum: 1, maximum: MAX_DEVICES },
+      path: { type: 'string', pattern: '^/dev/[A-Za-z0-9._/+-]+$', maxLength: 128 },
+      // udev rule for the symlink (README §8.2): the USB port path, plus
+      // optional id/subsystem overrides.
+      devpath: { type: 'string', pattern: '^[A-Za-z0-9.:+/-]+$', maxLength: 64 },
+      vendorId: { type: 'string', pattern: '^[0-9a-fA-F]{4}$' },
+      productId: { type: 'string', pattern: '^[0-9a-fA-F]{4}$' },
+      subsystem: { enum: ['usb', 'tty'] },
+      ...extra
+    },
+    anyOf: [{ required: ['index'] }, { required: ['path'] }, ...(extra.serial ? [{ required: ['serial'] }] : [])]
+  }),
+  list = (item) => ({ type: 'array', maxItems: MAX_DEVICES, items: item }),
+  hwSchema = {
+    type: 'object',
+    additionalProperties: false,
+    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()),
+      relays: list({
+        type: 'object',
+        additionalProperties: false,
+        required: ['channel'],
+        properties: {
+          channel: { type: 'integer', minimum: 0, maximum: 7 },
+          baseUrl: { type: 'string', format: 'uri', pattern: '^https?://' }
+        }
+      }),
+      power: {
+        type: ['object', 'null'],
+        additionalProperties: false,
+        properties: {
+          method: { enum: ['uhubctl', 'relay'] },
+          hub: { type: 'string', pattern: '^[A-Za-z0-9.:-]{1,32}$' },
+          port: { type: 'integer', minimum: 1, maximum: 64 },
+          baseUrl: { type: 'string', format: 'uri', pattern: '^https?://' }
+        }
+      }
+    }
+  },
+  swSchema = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      image: { type: 'string', maxLength: 255, pattern: DOCKER_IMAGE_PATTERN },
+      registry: { type: 'string', pattern: '^(https?://)?[A-Za-z0-9.-]+(:[0-9]+)?/?$', maxLength: 255 },
+      allowDockerHub: { type: 'boolean' },
+      allowJobImages: { type: 'boolean' },
+      cpus: { type: 'number', exclusiveMinimum: 0, maximum: 256 },
+      memory: { type: 'string', pattern: '^[0-9]+[kmgKMG]?$' },
+      cmd: { type: 'array', maxItems: 32, items: { type: 'string', maxLength: 1024 } }
+    }
+  },
+  ajv = new Ajv({ allErrors: true, strict: false }),
+  validators = { hw: null, sw: null };
+addFormats(ajv);
+validators.hw = ajv.compile(hwSchema);
+validators.sw = ajv.compile(swSchema);
+
+// Fields of a section that never leave the Client (secrets) — kept on the
+// Client when a dashboard edit is applied, never reported or accepted.
+const PRIVATE_FIELDS = { hw: [], sw: ['registryAuth'] };
+
+// { valid, errors } for a Client's `type` ('hw' | 'sw') config section.
+function validateClientConfig(type, section){
+  const validate = validators[type];
+  if (!validate){
+    return { valid: false, errors: [`unknown Client type "${type}"`] };
+  }
+  if (!section || typeof section !== 'object' || Array.isArray(section)){
+    return { valid: false, errors: [`the ${type} section must be an object`] };
+  }
+  const valid = validate(section);
+  return {
+    valid,
+    errors: valid ? [] : validate.errors.map((e) => `${type}${e.instancePath.replace(/\//g, '.')} ${e.message}`)
+  };
+}
+
+// The editable view of a section: without its private fields.
+function publicClientConfig(type, section){
+  const out = { ...(section || {}) };
+  for (const key of PRIVATE_FIELDS[type] || []){
+    delete out[key];
+  }
+  return out;
+}
+
+module.exports = { validateClientConfig, publicClientConfig, CLIENT_CONFIG_PRIVATE_FIELDS: PRIVATE_FIELDS };

package/src/index.js

@@ -19,5 +19,6 @@ module.exports = {
   ...require('./updates'),
   ...require('./datetime'),
   ...require('./cron'),
+  ...require('./client-config'),
   ApiClient: require('./api-client').ApiClient
 };

package/src/job-spec.schema.js

@@ -18,19 +18,20 @@
 const DOCKER_IMAGE_PATTERN =
     '^[A-Za-z0-9][A-Za-z0-9.-]*(:[0-9]+)?(/[a-z0-9]+((\\.|_|__|-+)[a-z0-9]+)*)*(:[A-Za-z0-9_][A-Za-z0-9_.-]{0,127})?(@sha256:[a-f0-9]{64})?$',
 
-  // A git branch or tag name: no leading "-" or "/", no "..", no spaces or
-  // the characters git forbids (~^:?*[\), not ending in "/", ".lock" or ".".
+  // A git ref to check out — a branch, a tag or a commit (hex) — as git
+  // allows them: no leading "-" (never taken for an option) or "/", no "..",
+  // no spaces or the characters git forbids, not ending in "/", ".lock", ".".
   GIT_REF_PATTERN = '^(?![-/])(?!.*\\.\\.)(?!.*//)(?!.*(/|\\.lock|\\.)$)[A-Za-z0-9._/+@-]+$',
 
-  // Matches the job spec shape documented in README.md §4.3.
-  // Deliberately has no field for shell commands: the Client only ever
-  // runs the fixed entry point from the downloaded test package — the
-  // one exception is firmware.image, which a Client must opt in to.
+  // Matches the job spec shape documented in README.md §4.3. A task is:
+  // optionally files to download and/or a git checkout, optionally (SW only)
+  // a Docker image to run as the DUT, and — always — the shell command that
+  // is its entry point, run on the Client in the checkout / work directory.
   jobSpecSchema = {
     $id: 'https://thub.example.com/schemas/job-spec.json',
     type: 'object',
     additionalProperties: false,
-    required: ['target', 'tests'],
+    required: ['target', 'command'],
     properties: {
       target: {
         type: 'object',
@@ -56,47 +57,39 @@ const DOCKER_IMAGE_PATTERN =
           client: { type: 'string', minLength: 1 }
         }
       },
-      // Exactly one of `url` (a firmware file the Client downloads — HW and
-      // SW) or `image` (a Docker image an SW Client runs instead of its own
-      // sw.image, if it allows that: sw.allowJobImages). The combinations are
-      // checked in validate-job-spec.js, for readable errors.
-      firmware: {
-        type: 'object',
-        additionalProperties: false,
-        properties: {
-          url: { type: 'string', format: 'uri' },
-          image: { type: 'string', maxLength: 255, pattern: DOCKER_IMAGE_PATTERN },
-          sha256: { type: 'string', pattern: '^[a-f0-9]{64}$' },
-          flashAddress: { type: 'string' }
-        }
+      // The task's entry point (`thub run --command`): a shell command the
+      // 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`).
+      suite: { type: 'string', default: 'default' },
+      // Files the Client downloads into the task's work directory before
+      // running the command (`--download-file`, repeatable).
+      downloads: {
+        type: 'array',
+        maxItems: 32,
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['url'],
+          properties: { url: { type: 'string', format: 'uri' } }
+        },
+        default: []
       },
-      // Where the tests come from — exactly one of `url` (an archive: tar in
-      // any compression, or zip) or `git` (a repository at a branch, tag or
-      // commit; default: its default branch) — and how they start: `command`
-      // (a shell command run in the sources, if the Client allows it:
-      // allowJobCommands), else the package's own run-tests.sh. Combinations
-      // are checked in validate-job-spec.js.
-      tests: {
+      // A Docker image an SW Client runs as the DUT instead of its own
+      // sw.image, if it allows that (sw.allowJobImages) — `--docker-image`.
+      image: { type: 'string', maxLength: 255, pattern: DOCKER_IMAGE_PATTERN },
+      // A repository the Client clones before running the command — at `ref`
+      // (branch, tag or commit; default: the default branch), `depth` commits
+      // deep (0 = full history). `--git-repo <url> [ref] [--depth <n>]`.
+      git: {
         type: 'object',
         additionalProperties: false,
+        required: ['url'],
         properties: {
-          url: { type: 'string', format: 'uri' },
-          git: {
-            type: 'object',
-            additionalProperties: false,
-            required: ['url'],
-            properties: {
-              url: { type: 'string', minLength: 1, maxLength: 2048 },
-              // Ref names as git allows them — never starting with "-",
-              // so none can be taken for a git option.
-              branch: { type: 'string', maxLength: 255, pattern: GIT_REF_PATTERN },
-              tag: { type: 'string', maxLength: 255, pattern: GIT_REF_PATTERN },
-              commit: { type: 'string', pattern: '^[0-9a-fA-F]{7,40}$' }
-            }
-          },
-          command: { type: 'string', minLength: 1, maxLength: 4096 },
-          suite: { type: 'string', default: 'default' },
-          args: { type: 'array', items: { type: 'string' }, default: [] }
+          url: { type: 'string', minLength: 1, maxLength: 2048 },
+          ref: { type: 'string', maxLength: 255, pattern: GIT_REF_PATTERN },
+          depth: { type: 'integer', minimum: 0, maximum: 100000, default: 1 }
         }
       },
       timeoutSec: { type: 'integer', minimum: 1, default: 1800 },

package/src/validate-job-spec.js

@@ -26,62 +26,44 @@ const validateFn = ajv.compile(jobSpecSchema);
  * Returns { valid, spec, errors }.
  */
 function validateJobSpec(spec){
+  const legacy = legacyShapeError(spec);
+  if (legacy){
+    return { valid: false, spec: JSON.parse(JSON.stringify(spec ?? {})), errors: [legacy] };
+  }
   const clone = JSON.parse(JSON.stringify(spec ?? {})),
     schemaValid = validateFn(clone),
     errors = schemaValid ? [] : (validateFn.errors || []).map((e) => `${e.instancePath || '/'} ${e.message}`);
-  errors.push(...firmwareErrors(clone), ...testsErrors(clone));
+  errors.push(...crossFieldErrors(clone));
   return { valid: errors.length === 0, spec: clone, errors };
 }
 
-// Git transports a Client may fetch test sources over. Never `ext::` (runs
-// a command), `file://` or a local path: the Client also sets
-// GIT_ALLOW_PROTOCOL to the same list (downloader.js).
-const GIT_URL = /^(?:(?:https?|ssh|git):\/\/[^\s]+|[A-Za-z0-9._-]+@[A-Za-z0-9.-]+:[^\s]+)$/;
-
-// tests.url (archive) vs tests.git (repo + at most one of branch/tag/commit).
-function testsErrors(spec){
-  const tests = spec.tests;
-  if (!tests || typeof tests !== 'object'){
-    return [];
-  }
-  if (tests.url && tests.git){
-    return ['/tests give either url (an archive) or git (a repository), not both'];
-  }
-  if (!tests.url && !tests.git){
-    return ['/tests needs url (an archive: tar/tar.gz/zip) or git (a repository)'];
-  }
-  if (tests.git){
-    if (!GIT_URL.test(tests.git.url || '')){
-      return ['/tests/git/url must be an https://, http://, ssh:// or git:// URL, or user@host:path'];
-    }
-    const refs = ['branch', 'tag', 'commit'].filter((k) => tests.git[k]);
-    if (refs.length > 1){
-      return [`/tests/git give at most one of branch, tag or commit (got ${refs.join(', ')})`];
-    }
+// Specs from an Agent older than --command (firmware/tests fields) can't be
+// translated faithfully (they relied on the Client flashing and on
+// run-tests.sh) — say what to do instead of listing unknown fields.
+function legacyShapeError(spec){
+  if (spec && typeof spec === 'object' && ('firmware' in spec || 'tests' in spec) && !('command' in spec)){
+    return '/ this job spec is from an older Agent (firmware/tests fields) — update the Agent (thub self-update) ' +
+      'and use --command, --download-file, --docker-image and --git-repo';
   }
-  return [];
+  return null;
 }
 
-// firmware.url vs firmware.image — spelled out here rather than as schema
-// oneOf/if-then, whose errors ("must match exactly one schema") say little.
-function firmwareErrors(spec){
-  const fw = spec.firmware;
-  if (!fw || typeof fw !== 'object'){
-    return ['/firmware is required'];
-  }
-  if (fw.url && fw.image){
-    return ['/firmware give either url (a firmware file) or image (a Docker image), not both'];
-  }
-  if (!fw.url && !fw.image){
-    return ['/firmware needs url (a firmware file) or image (a Docker image, SW jobs only)'];
-  }
-  if (fw.image && spec.target?.type === 'hw'){
-    return ['/firmware/image a Docker image only works for SW jobs (target.type "sw") — an HW job flashes a firmware file: use firmware.url'];
+// Git transports a Client may fetch sources over. Never `ext::` (runs a
+// command), `file://` or a local path: the Client also sets
+// GIT_ALLOW_PROTOCOL to the same list (downloader.js).
+const GIT_URL = /^(?:(?:https?|ssh|git):\/\/[^\s]+|[A-Za-z0-9._-]+@[A-Za-z0-9.-]+:[^\s]+)$/;
+
+// Rules across fields, spelled out here rather than as schema if/then,
+// whose errors ("must match a schema in then") say little.
+function crossFieldErrors(spec){
+  const errors = [];
+  if (spec.image && spec.target?.type === 'hw'){
+    errors.push('/image a Docker image only works for SW jobs (target.type "sw")');
   }
-  if (fw.image && fw.sha256){
-    return ['/firmware/sha256 applies to a firmware file (url) only — pin a Docker image by digest instead (image@sha256:...)'];
+  if (spec.git && !GIT_URL.test(spec.git.url || '')){
+    errors.push('/git/url must be an https://, http://, ssh:// or git:// URL, or user@host:path');
   }
-  return [];
+  return errors;
 }
 
 module.exports = { validateJobSpec };