@andrian.yablonskyy/thub-agent 1.0.21 → 1.0.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-agent",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "description": "TestHub Agent CLI — the single entry point CI/CD and developers use to submit and follow test jobs",
   "bin": {
     "thub": "./src/cli.js"

package/src/cli.js

@@ -54,6 +54,61 @@ function client(){
   return new ApiClient({ baseUrl: url, token, userAgent: `thub-agent/${version}` });
 }
 
+// `--image`: an http(s) URL is a firmware file to download; anything else
+// is taken as a Docker image reference, which only an SW job can run. Caught
+// here so `--type hw --image alpine` explains itself instead of failing
+// the Coordinator's schema check.
+function firmwareFromImage(opts){
+  if (/^https?:\/\//i.test(opts.image)){
+    return { url: opts.image, ...(opts.sha256 ? { sha256: opts.sha256 } : {}) };
+  }
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(opts.image)){
+    throw usageError(`--image ${opts.image}: only http(s) URLs can be downloaded as firmware`);
+  }
+  if (opts.type !== 'sw'){
+    throw usageError(
+      `--image ${opts.image} looks like a Docker image, which only an SW job can run (--type sw). ` +
+        'An HW job flashes a firmware file: pass its http(s) URL.'
+    );
+  }
+  if (opts.sha256){
+    throw usageError('--sha256 applies to a firmware URL only; pin a Docker image by digest instead (image@sha256:...)');
+  }
+  return { image: opts.image };
+}
+
+// --tests (archive URL) or --tests-git (+ at most one of branch/tag/commit).
+function testsFromOptions(opts){
+  const refs = ['branch', 'tag', 'commit'].filter((k) => opts[`tests${k[0].toUpperCase()}${k.slice(1)}`]);
+  if (opts.tests && opts.testsGit){
+    throw usageError('give either --tests (an archive URL) or --tests-git (a repository), not both');
+  }
+  if (!opts.tests && !opts.testsGit){
+    throw usageError('missing test sources: --tests <archive-url> or --tests-git <repo> [--tests-branch|--tests-tag|--tests-commit]');
+  }
+  if (opts.tests){
+    if (refs.length){
+      throw usageError(`--tests-${refs[0]} only applies to --tests-git`);
+    }
+    return { url: opts.tests };
+  }
+  if (refs.length > 1){
+    throw usageError(`give at most one of --tests-branch, --tests-tag, --tests-commit (got ${refs.map((r) => `--tests-${r}`).join(', ')})`);
+  }
+  return {
+    git: {
+      url: opts.testsGit,
+      ...(opts.testsBranch ? { branch: opts.testsBranch } : {}),
+      ...(opts.testsTag ? { tag: opts.testsTag } : {}),
+      ...(opts.testsCommit ? { commit: opts.testsCommit } : {})
+    }
+  };
+}
+
+function usageError(message){
+  return Object.assign(new Error(message), { status: EXIT_CODES.USAGE });
+}
+
 function fail(err){
   console.error(`Error: ${err.message}`);
   process.exit(err.status && Number.isInteger(err.status) && err.status < 100 ? err.status : EXIT_CODES.USAGE);
@@ -80,11 +135,29 @@ program
     'Free-text job owner, shown on the Client and the dashboard to tell whose job is whose ' +
       '— purely a label, not an identity. Overrides THUB_USER / config file.'
   )
-  .requiredOption('--image <url>', 'Firmware/build image URL (Artifactory or a Docker registry blob) fetched by the Client')
-  .option('--sha256 <hex>', 'Expected sha256 of --image; the Client verifies it before flashing/running')
-  .requiredOption('--tests <url>', 'Test package URL in Artifactory')
+  .requiredOption(
+    '--image <url|docker-image>',
+    'What the DUT runs: a firmware file URL (http/https, e.g. Artifactory) the Client downloads — HW and SW jobs — ' +
+      'or, for --type sw only, a Docker image to run as the DUT (e.g. alpine, alpine:3.20, registry.lab:5000/emu:1), ' +
+      'pulled from the Client\'s registry or Docker Hub; the Client must allow it (sw.allowJobImages)'
+  )
+  .option('--sha256 <hex>', 'Expected sha256 of a firmware --image URL; the Client verifies it before flashing/running')
+  .option(
+    '--tests <url>',
+    'Test sources as an archive URL (tar, tar.gz/.tgz/.bz2/.xz, or zip) the Client downloads and unpacks. ' +
+      'Give this or --tests-git'
+  )
+  .option('--tests-git <repo>', 'Test sources as a git repository (https://, ssh://, git:// or user@host:path) the Client fetches')
+  .option('--tests-branch <name>', 'With --tests-git: the branch to check out (default: the repository\'s default branch)')
+  .option('--tests-tag <name>', 'With --tests-git: the tag to check out')
+  .option('--tests-commit <sha>', 'With --tests-git: the commit to check out (7-40 hex digits)')
+  .option(
+    '--run <command>',
+    'Shell command that starts the tests, run in the test sources on the Client (--arg values arrive as "$@"). ' +
+      'Default: the sources\' own run-tests.sh. The Client must allow it (allowJobCommands)'
+  )
   .option('--suite <name>', 'Test suite name', 'default')
-  .option('--arg <value>', 'Extra argument passed through to run-tests.sh on the Client (repeatable)', collectRepeatable, [])
+  .option('--arg <value>', 'Extra argument passed through to run-tests.sh / --run on the Client (repeatable)', collectRepeatable, [])
   .option('--timeout <duration>', 'e.g. 30m, 1h', '30m')
   .option('--priority <n>', 'Priority 0-100', (v) => Number(v))
   .option('--wait', 'Do not detach on job end; exit with the verdict code (used in CI)', false)
@@ -105,7 +178,9 @@ program
   )
   .action(async (opts) => {
     try {
-      const c = client(),
+      const firmware = firmwareFromImage(opts),
+        testSources = testsFromOptions(opts),
+        c = client(),
         labels = [...(opts.board ? [`board:${opts.board}`] : []), ...opts.label],
         meta = Object.fromEntries(opts.meta.map((kv) => kv.split(/=(.*)/s).slice(0, 2))),
         group = resolveGroup({ group: opts.group }),
@@ -113,8 +188,8 @@ program
 
         spec = {
           target: { type: opts.type, labels, ...(group ? { group } : {}), ...(opts.client ? { client: opts.client } : {}) },
-          firmware: { url: opts.image, ...(opts.sha256 ? { sha256: opts.sha256 } : {}) },
-          tests: { url: opts.tests, suite: opts.suite, args: opts.arg },
+          firmware,
+          tests: { ...testSources, ...(opts.run ? { command: opts.run } : {}), suite: opts.suite, args: opts.arg },
           timeoutSec: parseDurationSec(opts.timeout),
           ...(opts.priority !== undefined ? { priority: opts.priority } : {}),
           ...(user ? { user } : {}),