@andrian.yablonskyy/thub-common 1.0.26 → 1.0.27

package/package.json

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

@@ -21,5 +21,6 @@ module.exports = {
   ...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
@@ -98,6 +101,18 @@ const DOCKER_IMAGE_PATTERN =
           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
@@ -113,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/validate-job-spec.js

@@ -15,7 +15,7 @@
 
 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 });
@@ -52,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.
@@ -64,6 +68,16 @@ 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);
@@ -75,4 +89,12 @@ function crossFieldErrors(spec){
   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 };