@andrian.yablonskyy/thub-agent 1.0.34 → 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
 ```
@@ -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.34",
+  "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.33",
+    "@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
@@ -374,16 +375,79 @@ function formatBytes(bytes){
 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