@andrian.yablonskyy/thub-agent 1.1.1 → 1.1.3

package/README.md

@@ -14,7 +14,7 @@ npx -y @andrian.yablonskyy/thub-agent run --type sw --download-file "$IMAGE_URL"
 
 ## Configuration
 
-Read from flags (`--url`, `--key`), then environment (`THUB_URL`, `THUB_KEY`, `THUB_GROUP`, `THUB_USER`; the old names `--token`/`THUB_TOKEN` still work), then `~/.config/thub/agent.json`, then a bundled default. `url`/`token` are required by the time a command actually talks to the Coordinator; `group`/`user` are optional everywhere.
+Read from flags (`--url`, `--key`), then environment (`THUB_URL`, `THUB_KEY`, `THUB_USER`; the old names `--token`/`THUB_TOKEN` still work), then `~/.config/thub/agent.json`, then a bundled default. `url`/`token` are required by the time a command actually talks to the Coordinator; `group`/`user` are optional everywhere.
 
 `npm install -g` creates `~/.config/thub/agent.json` for you (blank `url`/`token`, so nothing works until you set them) if it doesn't already exist — a re-install never overwrites it. Fill it in with `thub config set`:
 
@@ -24,7 +24,6 @@ thub config set key thk_...       # your access key: from an admin (Users), or y
 thub whoami                       # jane (user) <jane@example.com>
 thub key show                     # its last characters, created, last used
 thub key rotate                   # a new key; the old one stops at once (saved here if it came from here)
-thub config set group 548ae4ae-...   # optional default --group
 thub config set user "Your Name"     # optional default --user
 ```
 
@@ -36,7 +35,7 @@ thub status   <jobId>          Show status; follow log if running, verdict, test
 thub cancel   <jobId>          Cancel a job
 thub resources                 List resources and their status
 thub jobs     [--mine] [--state <s>]   List recent jobs (a cli token: only its own; a ci token: all, or its own with --mine)
-thub config   set <key> <value>        Save coordinator URL / token / default group / default user locally
+thub config   set <key> <value>        Save coordinator URL / key / default user locally
 thub check-update                      Compare this Agent with the latest published version
 thub self-update [--to <x.y.z>]        Update this Agent with npm i -g
 thub --version
@@ -49,8 +48,7 @@ Key options for `thub run`. **On the Client** names the environment variable the
 | Option | Description | On the Client |
 |---|---|---|
 | `--type hw\|sw` | Required resource type. | `JOB_TYPE` |
-| `--board <name>` / `--label <l>` | Required labels (repeatable). | `JOB_BOARD`; `JOB_LABEL`, `JOB_LABEL_<n>` |
-| `--group <groupId>` | Restrict scheduling to resources that are members of this group. Falls back to `THUB_GROUP` / `thub config set group <id>`. | `JOB_GROUP` |
+| `--label <l>` | Required labels (repeatable; a board is `--label board:<name>`): the job runs only on a runner that has all of them. Each 1–64 characters, no whitespace, commas or semicolons. | `JOB_LABEL`, `JOB_LABEL_<n>` |
 | `--client <name\|id>` | Run on this specific Client (resource name or id) only; the job waits in that Client's queue even if other matching resources are idle. | `JOB_CLIENT` |
 | `--user <name>` | Free-text job owner — a label, not an identity. Falls back to `THUB_USER` / `thub config set user <name>`. | `JOB_USER` |
 | `--command <string>` | **Required.** The task's entry point: a shell command the Client runs (`sh -c`) in the task's work directory — the `--git-repo` checkout, else an empty directory — after preparing its inputs. Its exit code is the verdict. On HW it flashes the board itself (the Client doesn't); it gets `THUB_DUT_STLINK`/`_UART`/`_USB`/`_HOST`/`_CONTAINER`, `THUB_DOWNLOAD_<n>`, `THUB_DOWNLOADS_DIR`, `THUB_GIT_COMMIT`, `THUB_SUITE`, `THUB_META_*`. | `JOB_COMMAND` |
@@ -90,7 +88,7 @@ Exit codes make the Agent usable as a CI step:
 **Run a task** — download the firmware, check out the tests at a tag, flash and test (HW):
 
 ```bash
-thub run --type hw --board nucleo-f401re \
+thub run --type hw --label board:nucleo-f401re \
   --download-file "$IMAGE_URL" \
   --git-repo https://github.com/yourorg/firmware-tests.git v1.4.0 \
   --command 'st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/test.sh "$@"' \
@@ -122,17 +120,12 @@ thub run --type sw --download-file https://does-not-exist.invalid/app.bin \
   --command ./ci/test.sh --dry-run --wait
 ```
 
-**Run on a specific resource group only:**
-
-```bash
-thub run --type sw --git-repo "$TESTS_REPO" --command ./ci/test.sh \
-  --group 548ae4ae-ac5b-401f-acaa-24bbe790e62d --wait
-```
+**Run in a resource group:** there's no `--group` option. An admin or maintainer gives your user (or a CI token) one group on the dashboard, and every job it submits runs only on that group's resources; `thub whoami` shows it.
 
 **Label a job with its owner** — purely informational, shows up on the dashboard, in `thub jobs`, and on the Client's own console:
 
 ```bash
-thub run --type hw --board nucleo-f401re \
+thub run --type hw --label board:nucleo-f401re \
   --git-repo "$TESTS_REPO" --command ./ci/test.sh --user "Your Name" --wait
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-agent",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "TestHub Agent CLI — the single entry point CI/CD and developers use to submit and follow test jobs",
   "bin": {
     "thub": "./src/cli.js"
@@ -12,7 +12,7 @@
     "lint:fix": "eslint . --fix"
   },
   "dependencies": {
-    "@andrian.yablonskyy/thub-common": "^1.1.1",
+    "@andrian.yablonskyy/thub-common": "^1.1.2",
     "commander": "^13.1.0"
   },
   "devDependencies": {

package/src/cli.js

@@ -21,7 +21,7 @@ const { Command, Option } = require('commander'),
     splitArgs,
     parseEnvList
   } = require('@andrian.yablonskyy/thub-common'),
-  { resolveConnection, resolveGroup, resolveUser, writeConfigFile, readConfigFile, CONFIG_PATH } = require('./config'),
+  { resolveConnection, resolveUser, writeConfigFile, readConfigFile, CONFIG_PATH } = require('./config'),
   { parseDurationSec } = require('./duration'),
   { followJob } = require('./streaming'),
   { applyRequestedUpdate, installAgent, version } = require('./self-update');
@@ -134,17 +134,27 @@ function fail(err){
   process.exit(err.status && Number.isInteger(err.status) && err.status < 100 ? err.status : EXIT_CODES.USAGE);
 }
 
+// --label: the labels a runner must all have for the job (§7.1).
+// Checked here against the Coordinator's rule, so a typo fails before the
+// job is sent.
+const LABEL_RE = /^[^\s,;]{1,64}$/;
+function requiredLabels(opts){
+  const labels = opts.label,
+    bad = labels.filter((l) => !LABEL_RE.test(l));
+  if (bad.length){
+    const err = new Error(`Invalid label: ${bad.join(', ')} — 1–64 characters, no spaces, commas or semicolons`);
+    err.status = EXIT_CODES.USAGE;
+    throw err;
+  }
+  return [...new Set(labels)];
+}
+
 program
   .command('run')
   .description('Submit a test job and follow its log')
   .requiredOption('--type <hw|sw>', 'Required resource type')
-  .option('--board <name>', 'Shorthand for --label board:<name>')
-  .option('--label <label>', 'Required label the resource must have (repeatable)', collectRepeatable, [])
-  .option(
-    '--group <groupId>',
-    'Restrict scheduling to resources that are members of this group (§13.1). ' +
-      'Overrides THUB_GROUP / config file; leave unset for an unconstrained run.'
-  )
+  .option('--label <label>', 'A label the runner must have (repeatable; the job runs only on a runner with all of them). ' +
+    '1–64 characters, no spaces, commas or semicolons', collectRepeatable, [])
   .option(
     '--client <nameOrId>',
     'Run on this specific Client (resource name or id) only; the job waits in that Client\'s queue ' +
@@ -216,13 +226,13 @@ program
     try {
       const task = taskFromOptions(opts),
         c = client(),
-        labels = [...(opts.board ? [`board:${opts.board}`] : []), ...opts.label],
+        labels = requiredLabels(opts),
         meta = Object.fromEntries(opts.meta.map((kv) => kv.split(/=(.*)/s).slice(0, 2))),
-        group = resolveGroup({ group: opts.group }),
         user = resolveUser({ user: opts.user }),
 
         spec = {
-          target: { type: opts.type, labels, ...(group ? { group } : {}), ...(opts.client ? { client: opts.client } : {}) },
+          // No group: the Coordinator uses this key's, set on the dashboard (§13.1).
+          target: { type: opts.type, labels, ...(opts.client ? { client: opts.client } : {}) },
           ...task,
           timeoutSec: parseDurationSec(opts.timeout),
           ...(opts.priority !== undefined ? { priority: opts.priority } : {}),
@@ -375,13 +385,15 @@ function formatBytes(bytes){
 const config = program.command('config').description('Manage local Agent configuration');
 config
   .command('set')
-  .argument('<name>', 'url | key | group | user')
+  .argument('<name>', 'url | key | user')
   .argument('<value>')
   .action((name, value) => {
     // `token` is the old name of `key`.
     const setting = name === 'token' ? 'key' : name;
-    if (!['url', 'key', 'group', 'user'].includes(setting)){
-      console.error('Error: the setting must be "url", "key", "group", or "user"');
+    if (!['url', 'key', 'user'].includes(setting)){
+      console.error(setting === 'group'
+        ? 'Error: a job\'s group is set on the dashboard now (Users / CI tokens), not in the Agent'
+        : 'Error: the setting must be "url", "key", or "user"');
       process.exit(EXIT_CODES.USAGE);
     }
     const { token: _old, ...current } = readConfigFile();
@@ -391,8 +403,10 @@ config
 
 // Who this access key belongs to (§10.3).
 function describeMe(me){
-  const role = me.user?.role ? me.user.role.charAt(0).toUpperCase() + me.user.role.slice(1) : '';
-  return me.user ? `${me.user.username} (${role})${me.user.email ? ` <${me.user.email}>` : ''}` : `CI token "${me.name}"`;
+  const role = me.user?.role ? me.user.role.charAt(0).toUpperCase() + me.user.role.slice(1) : '',
+    who = me.user ? `${me.user.username} (${role})${me.user.email ? ` <${me.user.email}>` : ''}` : `CI token "${me.name}"`;
+  // Older Coordinators don't say: then nothing about groups.
+  return me.group === undefined ? who : `${who}\nJobs run in: ${me.group ? `group ${me.group}` : 'any resource (no group)'}`;
 }
 
 program

package/src/config.js

@@ -1,6 +1,6 @@
 /**
  * @file        packages/agent/src/config.js
- * @description Agent config resolution: flags > env > config file > bundled default (url/token/group/user)
+ * @description Agent config resolution: flags > env > config file > bundled default (url/token/user)
  *
  * @author      Andrian Yablonskyy
  * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
@@ -65,16 +65,8 @@ function resolveConnection(flags = {}){
   return { url, token, keySource };
 }
 
-// Optional default for `--group` (§4.3/§7.1) — same flags > env > file
-// precedence as url/token, but unset is fine: a job just runs unconstrained
-// by group, same as if `groups` had never been used at all.
-function resolveGroup(flags = {}){
-  const file = { ...readJsonFile(PACKAGE_DEFAULT_CONFIG_PATH), ...readConfigFile() };
-  return flags.group || process.env.THUB_GROUP || file.group || undefined;
-}
-
-// Optional default for `--user` (§4.3/§7.1) — same flags > env > file
-// precedence as group. Purely a label (who submitted this job), not an
+// Optional default for `--user` (§4.3/§7.1) — flags > env > file, like
+// url/token. Purely a label (who submitted this job), not an
 // identity: unset is fine, and nothing on the Coordinator side enforces
 // or authenticates it.
 function resolveUser(flags = {}){
@@ -82,4 +74,4 @@ function resolveUser(flags = {}){
   return flags.user || process.env.THUB_USER || file.user || undefined;
 }
 
-module.exports = { CONFIG_PATH, readConfigFile, writeConfigFile, resolveConnection, resolveGroup, resolveUser };
+module.exports = { CONFIG_PATH, readConfigFile, writeConfigFile, resolveConnection, resolveUser };