@andrian.yablonskyy/thub-common 1.0.25 → 1.0.27

package/package.json

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

@@ -0,0 +1,40 @@
+/**
+ * @file        packages/shared/src/env-list.js
+ * @description Parses the Agent's `--env NAME=value[,NAME=value]` values into a job's env
+ *
+ * @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';
+
+// ['A=1,B=2', 'C'] -> { A: '1', B: '2', C: <C from environ> }. A comma only
+// starts a new variable when NAME= follows it, so values may contain commas
+// (`P=a,b` is P="a,b"). A bare NAME — a whole --env of its own — takes its
+// value from `environ`: keeps secrets like DOCKER_PASSWORD off the command
+// line and out of shell history. Throws on a malformed item or a bare NAME
+// that isn't set.
+function parseEnvList(values = [], environ = process.env){
+  const env = {};
+  for (const value of values){
+    for (const item of String(value).split(/,(?=[A-Za-z_][A-Za-z0-9_]*=)/)){
+      const m = /^([A-Za-z_][A-Za-z0-9_]*)(?:=(.*))?$/s.exec(item);
+      if (!m){
+        throw new Error(`--env ${item}: expected NAME=value or NAME (NAME: letters, digits and _, not starting with a digit)`);
+      }
+      const [, name, val] = m;
+      if (val === undefined && environ[name] === undefined){
+        throw new Error(`--env ${name}: not set in this shell — give it as ${name}=value or export it first`);
+      }
+      env[name] = val === undefined ? environ[name] : val;
+    }
+  }
+  return env;
+}
+
+module.exports = { parseEnvList };

package/src/index.js

@@ -20,5 +20,7 @@ module.exports = {
   ...require('./datetime'),
   ...require('./cron'),
   ...require('./client-config'),
+  ...require('./split-args'),
+  ...require('./env-list'),
   ApiClient: require('./api-client').ApiClient
 };

package/src/job-spec.schema.js

@@ -23,6 +23,9 @@ const DOCKER_IMAGE_PATTERN =
   // no spaces or the characters git forbids, not ending in "/", ".lock", ".".
   GIT_REF_PATTERN = '^(?![-/])(?!.*\\.\\.)(?!.*//)(?!.*(/|\\.lock|\\.)$)[A-Za-z0-9._/+@-]+$',
 
+  // An environment variable name a job may set (`--env NAME=value`).
+  ENV_NAME_PATTERN = '^[A-Za-z_][A-Za-z0-9_]*$',
+
   // 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
@@ -89,9 +92,27 @@ 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 }
         }
       },
+      // Environment variables (`--env NAME=value`) the Client sets for every
+      // command it runs for the job — git, docker login, the job's command.
+      // DOCKER_REGISTRY + DOCKER_USERNAME + DOCKER_PASSWORD: the Client logs in
+      // to that registry first (README §8.1). Values are secrets as far as
+      // the Coordinator is concerned: masked in the Agent API and dropped
+      // from its database once the job ends.
+      env: {
+        type: 'object',
+        maxProperties: 64,
+        propertyNames: { pattern: ENV_NAME_PATTERN, maxLength: 128 },
+        additionalProperties: { type: 'string', maxLength: 8192 }
+      },
       timeoutSec: { type: 'integer', minimum: 1, default: 1800 },
       priority: { type: 'integer', minimum: 0, maximum: 100, default: 50 },
       // Set by the Coordinator from the agent token's kind; any value an
@@ -107,6 +128,9 @@ const DOCKER_IMAGE_PATTERN =
       // see README §7.1 "Dry-run the pipeline".
       dryRun: { type: 'boolean', default: false }
     }
-  };
+  },
+
+  // The job env variables the Client logs in to a Docker registry with.
+  DOCKER_LOGIN_ENV = ['DOCKER_REGISTRY', 'DOCKER_USERNAME', 'DOCKER_PASSWORD'];
 
-module.exports = { jobSpecSchema, DOCKER_IMAGE_PATTERN };
+module.exports = { jobSpecSchema, DOCKER_IMAGE_PATTERN, ENV_NAME_PATTERN, DOCKER_LOGIN_ENV };

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, DOCKER_LOGIN_ENV } = require('./job-spec.schema'),
+  { splitArgs } = require('./split-args');
 
 const ajv = new Ajv({ useDefaults: true, allErrors: true, strict: false });
 addFormats(ajv);
@@ -51,7 +52,11 @@ function legacyShapeError(spec){
 // 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]+)$/;
+const GIT_URL = /^(?:(?:https?|ssh|git):\/\/[^\s]+|[A-Za-z0-9._-]+@[A-Za-z0-9.-]+:[^\s]+)$/,
+
+  // Job env names the Client sets itself for a job's commands (besides
+  // THUB_*): git's safety settings, and the job's own Docker config dir.
+  RESERVED_ENV = ['GIT_TERMINAL_PROMPT', 'GIT_ALLOW_PROTOCOL', 'DOCKER_CONFIG'];
 
 // Rules across fields, spelled out here rather than as schema if/then,
 // whose errors ("must match a schema in then") say little.
@@ -63,7 +68,33 @@ 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');
   }
+  const envNames = Object.keys(spec.env && typeof spec.env === 'object' ? spec.env : {}),
+    reserved = envNames.filter((n) => /^THUB_/.test(n) || RESERVED_ENV.includes(n)),
+    login = DOCKER_LOGIN_ENV.filter((n) => envNames.includes(n));
+  if (reserved.length){
+    errors.push(`/env ${reserved.join(', ')}: set by the Client itself (THUB_*, ${RESERVED_ENV.join(', ')}) — use other names`);
+  }
+  if (login.length && login.length < DOCKER_LOGIN_ENV.length){
+    errors.push(`/env a Docker registry login needs all of ${DOCKER_LOGIN_ENV.join(', ')} — missing ` +
+      DOCKER_LOGIN_ENV.filter((n) => !login.includes(n)).join(', '));
+  }
+  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;
 }
 
-module.exports = { validateJobSpec };
+// A job's `env` with its values hidden — for anything but the Client that
+// runs the job (Agent API, logs, dry-run output).
+function maskEnv(env){
+  return env && typeof env === 'object' ? Object.fromEntries(Object.keys(env).map((k) => [k, MASKED])) : env;
+}
+
+const MASKED = '***';
+
+module.exports = { validateJobSpec, maskEnv, DOCKER_LOGIN_ENV, JOB_ENV_MASK: MASKED };