@andrian.yablonskyy/thub-common 1.0.24 → 1.0.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-common",
-  "version": "1.0.24",
+  "version": "1.0.26",
   "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,7 @@ module.exports = {
   ...require('./updates'),
   ...require('./datetime'),
   ...require('./cron'),
+  ...require('./client-config'),
+  ...require('./split-args'),
   ApiClient: require('./api-client').ApiClient
 };

package/src/job-spec.schema.js

@@ -89,7 +89,13 @@ const DOCKER_IMAGE_PATTERN =
         properties: {
           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 }
+          depth: { type: 'integer', minimum: 0, maximum: 100000, default: 1 },
+          // Extra git options (`--git-options`), shell-quoted, inserted
+          // between `git` and its subcommand on the Client — e.g.
+          // -c core.sshCommand="ssh -i ~/.ssh/lab_key -p 2222". Stored with
+          // the job and visible like the rest of it: reference key files on
+          // the Client rather than putting secrets here.
+          options: { type: 'string', minLength: 1, maxLength: 1024 }
         }
       },
       timeoutSec: { type: 'integer', minimum: 1, default: 1800 },

package/src/split-args.js

@@ -0,0 +1,88 @@
+/**
+ * @file        packages/shared/src/split-args.js
+ * @description Splits a command-line options string into arguments the way a POSIX shell would quote them —
+ *              without running a shell (for `thub run --git-options`)
+ *
+ * @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';
+
+// Whitespace separates arguments; '...' is literal; "..." keeps spaces, with
+// \" \\ \$ \` escaped; a backslash outside quotes escapes the next
+// character. No expansion of any kind ($VAR, ~, globs) — the result goes
+// straight to execFile. Throws on an unterminated quote or trailing "\".
+function splitArgs(text){
+  const args = [],
+    s = String(text ?? '');
+  let current = null,
+    i = 0;
+  const push = (ch) => {
+    current = (current ?? '') + ch;
+  };
+  while (i < s.length){
+    const ch = s[i];
+    if (/\s/.test(ch)){
+      if (current !== null){
+        args.push(current);
+        current = null;
+      }
+      i++;
+    }
+    else if (ch === '\''){
+      const end = s.indexOf('\'', i + 1);
+      if (end < 0){
+        throw new Error('unterminated \' quote');
+      }
+      push(s.slice(i + 1, end));
+      i = end + 1;
+    }
+    else if (ch === '"'){
+      let j = i + 1,
+        closed = false;
+      push('');
+      while (j < s.length){
+        if (s[j] === '\\' && /["\\$`]/.test(s[j + 1] || '')){
+          push(s[j + 1]);
+          j += 2;
+        }
+        else if (s[j] === '"'){
+          closed = true;
+          j++;
+          break;
+        }
+        else {
+          push(s[j]);
+          j++;
+        }
+      }
+      if (!closed){
+        throw new Error('unterminated " quote');
+      }
+      i = j;
+    }
+    else if (ch === '\\'){
+      if (i + 1 >= s.length){
+        throw new Error('trailing \\');
+      }
+      push(s[i + 1]);
+      i += 2;
+    }
+    else {
+      push(ch);
+      i++;
+    }
+  }
+  if (current !== null){
+    args.push(current);
+  }
+  return args;
+}
+
+module.exports = { splitArgs };

package/src/validate-job-spec.js

@@ -15,7 +15,8 @@
 
 const Ajv = require('ajv'),
   addFormats = require('ajv-formats'),
-  { jobSpecSchema } = require('./job-spec.schema');
+  { jobSpecSchema } = require('./job-spec.schema'),
+  { splitArgs } = require('./split-args');
 
 const ajv = new Ajv({ useDefaults: true, allErrors: true, strict: false });
 addFormats(ajv);
@@ -63,6 +64,14 @@ function crossFieldErrors(spec){
   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');
   }
+  if (spec.git?.options){
+    try {
+      splitArgs(spec.git.options);
+    }
+    catch (err){
+      errors.push(`/git/options can't be split into arguments: ${err.message}`);
+    }
+  }
   return errors;
 }