@andrian.yablonskyy/thub-agent 1.0.33 → 1.1.0

package/README.md

@@ -14,13 +14,16 @@ npx -y @andrian.yablonskyy/thub-agent run --type sw --download-file "$IMAGE_URL"
 
 ## Configuration
 
-Read from flags, then environment (`THUB_URL`, `THUB_TOKEN`, `THUB_GROUP`, `THUB_USER`), 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_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.
 
 `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`:
 
 ```bash
 thub config set url https://thub.example.com
-thub config set token agt_...
+thub config set key thk_...       # your access key: from an admin (Users), or your dashboard profile
+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
 ```
@@ -29,10 +32,10 @@ thub config set user "Your Name"     # optional default --user
 
 ```
 thub run      [options]        Submit a test job and follow its log
-thub status   <jobId>          Show status; follow log if running, verdict and test counts if done
+thub status   <jobId>          Show status; follow log if running, verdict, test counts and artifacts if done
 thub cancel   <jobId>          Cancel a job
 thub resources                 List resources and their status
-thub jobs     [--mine] [--state <s>]   List recent jobs
+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 check-update                      Compare this Agent with the latest published version
 thub self-update [--to <x.y.z>]        Update this Agent with npm i -g
@@ -249,7 +252,7 @@ test-sw:
   runs-on: ubuntu-latest
   env:
     THUB_URL: https://thub.example.com
-    THUB_TOKEN: ${{ secrets.THUB_AGENT_TOKEN }}
+    THUB_KEY: ${{ secrets.THUB_CI_TOKEN }}   # a CI token (dashboard → CI tokens)
   steps:
     - run: |
         npx -y @andrian.yablonskyy/thub-agent run --type sw \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-agent",
-  "version": "1.0.33",
+  "version": "1.1.0",
   "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.0.32",
+    "@andrian.yablonskyy/thub-common": "^1.1.0",
     "commander": "^13.1.0"
   },
   "devDependencies": {

package/src/cli.js

@@ -15,13 +15,13 @@
 
 'use strict';
 
-const { Command } = require('commander'),
+const { Command, Option } = require('commander'),
   {
     ApiClient, EXIT_CODES, ACTIVE_JOB_STATES, exitCodeForJobState, PACKAGES, fetchLatestVersion, isNewer, isValidVersion, formatDateTime,
     splitArgs,
     parseEnvList
   } = require('@andrian.yablonskyy/thub-common'),
-  { resolveConnection, resolveGroup, resolveUser, writeConfigFile, readConfigFile } = require('./config'),
+  { resolveConnection, resolveGroup, resolveUser, writeConfigFile, readConfigFile, CONFIG_PATH } = require('./config'),
   { parseDurationSec } = require('./duration'),
   { followJob } = require('./streaming'),
   { applyRequestedUpdate, installAgent, version } = require('./self-update');
@@ -31,7 +31,8 @@ program
   .name('thub')
   .description('TestHub Agent — submit test jobs and follow them, from CI or your laptop')
   .option('--url <url>', 'Coordinator URL (overrides THUB_URL / config file)')
-  .option('--token <token>', 'Agent token (overrides THUB_TOKEN / config file)')
+  .option('--key <key>', 'Your access key (overrides THUB_KEY / config file)')
+  .addOption(new Option('--token <token>', 'Old name of --key').hideHelp())
   .version(version);
 
 // An admin-requested self-update (README §10.2) is applied at the start of
@@ -252,7 +253,7 @@ program
 
 program
   .command('status')
-  .description('Show status; follow log if running, verdict and test counts if done')
+  .description('Show status; follow log if running, verdict, test counts and artifacts if done')
   .argument('<jobId>')
   .option('--json', 'Print the job as JSON once, without following it; exit code: its verdict, or 5 while it\'s still active', false)
   .action(async (jobId, opts) => {
@@ -282,6 +283,13 @@ program
       if (job.message){
         console.log(`Message: ${job.message}`);
       }
+      // What the job published elsewhere and reported (links, not files).
+      if (job.artifacts?.length){
+        console.log('Artifacts:');
+        for (const a of job.artifacts){
+          console.log(`  ${a.name}  ${a.size != null ? formatBytes(a.size) : '—'}  ${a.link}`);
+        }
+      }
       process.exit(exitCodeForJobState(job.state));
     }
     catch (err){
@@ -330,7 +338,7 @@ program
 program
   .command('jobs')
   .description('List recent jobs')
-  .option('--mine', 'Only jobs submitted by this agent token', false)
+  .option('--mine', 'Only jobs submitted by this agent token (always so for a cli token, which sees only its own)', false)
   .option('--state <state>', 'Filter by state')
   .option('--json', 'Machine-readable output', false)
   .action(async (opts) => {
@@ -352,19 +360,94 @@ program
     }
   });
 
+// 1233 -> "1.2 KB" (1024-based), for artifact sizes.
+function formatBytes(bytes){
+  const units = ['B', 'KB', 'MB', 'GB', 'TB', 'PB'];
+  let value = bytes,
+    unit = 0;
+  while (value >= 1024 && unit < units.length - 1){
+    value /= 1024;
+    unit += 1;
+  }
+  return unit === 0 ? `${value} B` : `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`;
+}
+
 const config = program.command('config').description('Manage local Agent configuration');
 config
   .command('set')
-  .argument('<key>', 'url | token | group | user')
+  .argument('<name>', 'url | key | group | user')
   .argument('<value>')
-  .action((key, value) => {
-    if (!['url', 'token', 'group', 'user'].includes(key)){
-      console.error('Error: key must be "url", "token", "group", or "user"');
+  .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"');
       process.exit(EXIT_CODES.USAGE);
     }
-    const current = readConfigFile();
-    writeConfigFile({ ...current, [key]: value });
-    console.log(`Saved ${key} to config`);
+    const { token: _old, ...current } = readConfigFile();
+    writeConfigFile({ ...(setting === 'key' ? current : { ...current, ...(_old ? { token: _old } : {}) }), [setting]: value });
+    console.log(`Saved ${setting} to 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}"`;
+}
+
+program
+  .command('whoami')
+  .description('Show whose access key this Agent uses')
+  .action(async () => {
+    try {
+      console.log(describeMe(await client().get('/me')));
+    }
+    catch (err){
+      fail(err);
+    }
+  });
+
+const keyCommand = program.command('key').description('Your access key');
+keyCommand
+  .command('show')
+  .description('Show your access key\'s details (never the key itself — only its last characters)')
+  .action(async () => {
+    try {
+      const me = await client().get('/me'),
+        { keySource } = resolveConnection(program.opts());
+      console.log(`User:      ${describeMe(me)}`);
+      if (me.key){
+        console.log(`Key:       …${me.key.hint || '????'} (from ${keySource === 'file' ? CONFIG_PATH : keySource === 'flag' ? '--key' : keySource})`);
+        console.log(`Created:   ${formatDateTime(me.key.createdAt)}`);
+        console.log(`Last used: ${me.key.lastUsedAt ? formatDateTime(me.key.lastUsedAt) : 'never'}`);
+      }
+    }
+    catch (err){
+      fail(err);
+    }
+  });
+keyCommand
+  .command('rotate')
+  .description('Replace your access key: the current one stops working at once')
+  .action(async () => {
+    try {
+      const { keySource } = resolveConnection(program.opts()),
+        { key, username } = await client().post('/me/key/rotate');
+      if (keySource === 'file'){
+        const { token: _old, ...current } = readConfigFile();
+        writeConfigFile({ ...current, key });
+        console.log(`New access key for ${username} saved to ${CONFIG_PATH} — the old one has stopped working.`);
+      }
+      else {
+        console.log(`New access key for ${username} — the old one has stopped working. Shown only now:\n\n  ${key}\n`);
+        console.log(keySource === 'flag'
+          ? 'Use it with --key from now on (or save it: thub config set key <key>).'
+          : `Update ${keySource} (e.g. your CI secret) with it, or save it: thub config set key <key>.`);
+      }
+    }
+    catch (err){
+      fail(err);
+    }
   });
 
 program

package/src/config.js

@@ -18,7 +18,8 @@ const fs = require('node:fs'),
   path = require('node:path');
 
 // §7: "Configuration is read from flags, then environment (THUB_URL,
-// THUB_TOKEN), then ~/.config/thub/agent.json."
+// THUB_KEY), then ~/.config/thub/agent.json." The access key (§10.3) used to
+// be called a token: --token, THUB_TOKEN and a saved `token` still work.
 const CONFIG_PATH = path.join(os.homedir(), '.config', 'thub', 'agent.json'),
 
   // Bundled with the package as a last-resort default, below the user's own
@@ -44,19 +45,24 @@ function writeConfigFile(config){
   fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
 }
 
+// `keySource` says where the key came from — `thub key rotate` saves the
+// new one only where it can (the config file), and says what to update
+// otherwise.
 function resolveConnection(flags = {}){
   const file = { ...readJsonFile(PACKAGE_DEFAULT_CONFIG_PATH), ...readConfigFile() },
     url = flags.url || process.env.THUB_URL || file.url,
-    token = flags.token || process.env.THUB_TOKEN || file.token;
+    [token, keySource] = flags.key || flags.token ? [flags.key || flags.token, 'flag']
+      : process.env.THUB_KEY || process.env.THUB_TOKEN ? [process.env.THUB_KEY || process.env.THUB_TOKEN, process.env.THUB_KEY ? 'THUB_KEY' : 'THUB_TOKEN']
+        : file.key || file.token ? [file.key || file.token, 'file'] : [null, null];
   if (!url || !token){
     const err = new Error(
-      'Missing coordinator URL or token. Set with `thub config set url <url>` / `thub config set token <token>`, ' +
-        'or THUB_URL / THUB_TOKEN, or --url / --token.'
+      'Missing Coordinator URL or access key. Set them with `thub config set url <url>` and `thub config set key <key>`, ' +
+        'or THUB_URL / THUB_KEY, or --url / --key. An admin gives you your key (Users), or create it on your dashboard profile.'
     );
     err.status = 4;
     throw err;
   }
-  return { url, token };
+  return { url, token, keySource };
 }
 
 // Optional default for `--group` (§4.3/§7.1) — same flags > env > file