@apex-actions/cli 0.74.0 → 0.75.0

package/dist/src/domain/credentials.js

@@ -51,9 +51,18 @@ export const parseSavedCredential = (raw) => {
     return { token: r['token'], login: r['login'], apiUrl: r['apiUrl'], expiresAt: r['expiresAt'] };
 };
 /**
- * The consent page `apex login` and `apex token create` open (RFC 8252
- * loopback, RFC 7636 S256). A token request adds `purpose=token` and what the
- * person is approving, so the page can show it and the code carries it.
+ * The consent page `apex login`, `apex token create` and a widening `apex token
+ * edit` open (RFC 8252 loopback, RFC 7636 S256). The query is the contract with
+ * the web app's `/cli/authorize` page:
+ *
+ * - `port`, `state`, `code_challenge`, `name` — always;
+ * - `purpose` — `token` or `edit` (absent for a login);
+ * - `days`, `repos` (comma-separated `owner/repo`) — a token's lifetime and scope; for an edit, `repos` absent
+ *   keeps the token's own repositories;
+ * - `all_repos=1` — an edit that widens to every repository (never sent with `repos`);
+ * - `permission` — repeated, once per grant (`actions:read`, `secrets:write`, …);
+ * - `account` — the Account id, for a login or a token;
+ * - `token` — the token id an edit widens.
  */
 export const authorizeUrl = (webBase, request) => {
     const query = new URLSearchParams({
@@ -62,27 +71,55 @@ export const authorizeUrl = (webBase, request) => {
         code_challenge: request.codeChallenge,
         name: request.name,
     });
-    if (request.token !== undefined) {
-        query.set('purpose', 'token');
-        if (request.token.days !== undefined)
-            query.set('days', String(request.token.days));
-        if (request.token.repos !== undefined && request.token.repos.length > 0)
-            query.set('repos', request.token.repos.join(','));
+    const t = request.token;
+    if (t !== undefined) {
+        query.set('purpose', t.purpose ?? 'token');
+        if (t.days !== undefined)
+            query.set('days', String(t.days));
+        if (t.allRepos === true)
+            query.set('all_repos', '1');
+        else if (t.repos !== undefined && t.repos.length > 0)
+            query.set('repos', t.repos.join(','));
+        for (const p of t.permissions ?? [])
+            query.append('permission', p);
+        if (t.accountId !== undefined)
+            query.set('account', t.accountId);
+        if (t.tokenId !== undefined)
+            query.set('token', t.tokenId);
+    }
+    else if (request.accountId !== undefined) {
+        query.set('account', request.accountId);
     }
     return `${normaliseUrl(webBase)}/cli/authorize?${query.toString()}`;
 };
+/**
+ * Where the loopback callback sends the browser once the code is redeemed (control-plane ADR-0075): the
+ * web app's bare `/cli/done`, so the tab ends on our domain rather than on this process's `127.0.0.1`.
+ * The page is copy only and confirms nothing server-side, so it carries only the outcome and the purpose
+ * — never the code, the state or anything else the callback held.
+ */
+export const doneUrl = (webBase, outcome, purpose) => `${normaliseUrl(webBase)}/cli/done?${new URLSearchParams({ outcome, purpose }).toString()}`;
 /** A token's lifetime bounds (control-plane ADR-0064): every token expires, 90 days at most. */
 export const MAX_TOKEN_DAYS = 90;
 /** Repositories one token may be held to. */
 export const MAX_TOKEN_REPOS = 100;
 const REPO = /^[A-Za-z0-9-]+\/[A-Za-z0-9._-]+$/;
-/** `apex token create`'s flags, checked before a browser opens — the control plane checks them again. */
-export const tokenRequestProblem = (name, days, repos) => {
-    if (name.trim() === '' || name.trim().length > 100)
-        return 'a token needs a name of 1 to 100 characters';
-    if (days !== undefined && !(Number.isInteger(days) && days >= 1 && days <= MAX_TOKEN_DAYS)) {
-        return `--expires-in-days must be a whole number from 1 to ${MAX_TOKEN_DAYS}`;
-    }
+/**
+ * What a token may be granted (context ADR-0038): `resource:read|write`, write implying read. The control plane's
+ * `RepoPermission`, in the order a person reads them.
+ */
+export const TOKEN_RESOURCES = ['actions', 'approvals', 'deployments', 'secrets', 'variables', 'environments', 'notifications', 'administration'];
+export const TOKEN_PERMISSIONS = TOKEN_RESOURCES.flatMap((r) => [`${r}:read`, `${r}:write`]);
+/** `--permission`'s values: at least one when `required`, each one a known grant. */
+export const permissionsProblem = (permissions, required) => {
+    if (required && permissions.length === 0)
+        return 'a token needs at least one --permission, e.g. --permission actions:read';
+    const bad = permissions.filter((p) => !TOKEN_PERMISSIONS.includes(p));
+    if (bad.length > 0)
+        return `not a permission: ${bad.join(', ')} — each is resource:read or resource:write, resource one of ${TOKEN_RESOURCES.join(', ')}`;
+    return undefined;
+};
+const reposProblem = (repos) => {
     if (repos.length > MAX_TOKEN_REPOS)
         return `a token may name at most ${MAX_TOKEN_REPOS} repositories`;
     const bad = repos.filter((r) => !REPO.test(r));
@@ -90,6 +127,68 @@ export const tokenRequestProblem = (name, days, repos) => {
         return `not owner/repo: ${bad.join(', ')}`;
     return undefined;
 };
+/**
+ * `apex token create`'s flags, checked before a browser opens — the control plane checks them again. `permissions`,
+ * when given, must name at least one grant.
+ */
+export const tokenRequestProblem = (name, days, repos, permissions) => {
+    if (name.trim() === '' || name.trim().length > 100)
+        return 'a token needs a name of 1 to 100 characters';
+    if (days !== undefined && !(Number.isInteger(days) && days >= 1 && days <= MAX_TOKEN_DAYS)) {
+        return `--expires-in-days must be a whole number from 1 to ${MAX_TOKEN_DAYS}`;
+    }
+    return reposProblem(repos) ?? (permissions === undefined ? undefined : permissionsProblem(permissions, true));
+};
+/** `apex token edit`'s flags: something to change, and each change well-formed. */
+export const tokenEditProblem = (edit) => {
+    if (edit.permissions === undefined && edit.add.length === 0 && edit.remove.length === 0 && edit.repos === undefined) {
+        return 'nothing to change: pass --permission, --add-permission, --remove-permission, --repo or --all-repos';
+    }
+    if (edit.permissions !== undefined && (edit.add.length > 0 || edit.remove.length > 0))
+        return 'pass --permission for the whole set, or --add-permission/--remove-permission, not both';
+    return ((edit.permissions === undefined ? undefined : permissionsProblem(edit.permissions, true)) ??
+        permissionsProblem([...edit.add, ...edit.remove], false) ??
+        (edit.repos === undefined || edit.repos === 'all' ? undefined : reposProblem(edit.repos)));
+};
+/** Whether `current` already grants `asked` — itself, or its write when a read is asked (write implies read). */
+export const covers = (current, asked) => {
+    if (current.includes(asked))
+        return true;
+    const [resource, level] = asked.split(':');
+    return level === 'read' && current.includes(`${resource ?? ''}:write`);
+};
+/**
+ * The grants an edit asks for: the whole new set, or the current set with additions (skipping any already covered)
+ * and removals. Removing a write keeps nothing of it — ask for the read to keep reading.
+ */
+export const editedPermissions = (current, edit) => {
+    if (edit.permissions !== undefined)
+        return [...new Set(edit.permissions)];
+    const out = current.filter((p) => !edit.remove.includes(p));
+    for (const p of edit.add)
+        if (!covers(out, p))
+            out.push(p);
+    return out;
+};
+/** A grant set as one short phrase: `every permission` for all of them, otherwise the grants as given. */
+export const describeGrants = (permissions) => {
+    if (permissions === undefined || permissions.length === 0)
+        return 'none';
+    if (TOKEN_RESOURCES.every((r) => permissions.includes(`${r}:write`)))
+        return 'every permission';
+    return [...permissions].sort((a, b) => TOKEN_PERMISSIONS.indexOf(a) - TOKEN_PERMISSIONS.indexOf(b)).join(', ');
+};
+const NEEDS = /^this token needs ([a-z]+:(?:read|write))$/;
+/**
+ * The control plane refuses a token a route its grants do not cover with `this token needs <permission>`. Say how to
+ * get it — an edit that adds the grant, which a browser approves — naming the token when the CLI knows which it is.
+ */
+export const withPermissionHint = (message, tokenId) => {
+    const m = NEEDS.exec(message);
+    if (m === null)
+        return message;
+    return `${message} — add it with: apex token edit ${tokenId ?? '<id>'} --add-permission ${m[1] ?? ''}${tokenId === undefined ? ' (apex token list shows the id)' : ''}`;
+};
 /**
  * Judge what arrived at the loopback callback.
  *

package/dist/src/infrastructure/control-plane-http.js

@@ -2,6 +2,7 @@
 import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
+import { withPermissionHint } from '../domain/credentials.js';
 import { NotConfiguredError, apiUrlFrom, resolveCredential } from './credentials.js';
 export { NotConfiguredError } from './credentials.js';
 /** The API refused, with its status, so a use case can tell a 403 from a 500. */
@@ -16,12 +17,15 @@ export class HttpError extends Error {
 /**
  * Adapter: the control-plane REST API over the platform's `fetch`.
  *
- * The credential is resolved in control-plane ADR-0064's order (see
- * `credentials.ts`): a customer's `APEX_TOKEN`, then the token `apex login`
- * saved, then the operator's `APEX_ADMIN_TOKEN` — the machine principal, which
- * keeps scripts and boot paths working when GitHub is unreachable (ADR-0006).
- * A customer token reaches only the secrets and variables routes and `/me`;
- * every other command answers with the server's 403, which says so.
+ * The credential is resolved in control-plane ADR-0064's order as this repo's
+ * ADR-0005 amends it (see `credentials.ts`): a customer's `APEX_TOKEN`, then
+ * the operator's `APEX_ADMIN_TOKEN` — the machine principal, which keeps
+ * scripts and boot paths working when GitHub is unreachable (ADR-0006) — then
+ * the token `apex login` saved. The environment outranks the file.
+ * A customer token reaches the repository routes its permissions cover, in its
+ * Account (control-plane ADR-0071); a route it lacks the grant for answers 403
+ * `this token needs <permission>`, which this client extends with the edit
+ * that would add it.
  *
  * The token goes in the `authorization` header and nowhere else: not in a
  * URL, not in an error, not in anything this class returns.
@@ -32,6 +36,8 @@ export class HttpControlPlane {
     #fetch;
     /** Where the credential came from — for `apex whoami`, which never shows the credential. */
     credentialSource;
+    /** Credentials that were present and lost to `credentialSource` — sources only, never values. */
+    credentialsAlsoPresent;
     constructor(config = {}) {
         if (config.token !== undefined) {
             if (config.token === '')
@@ -39,12 +45,14 @@ export class HttpControlPlane {
             this.#token = config.token;
             this.#baseUrl = (config.baseUrl ?? apiUrlFrom()).replace(/\/$/, '');
             this.credentialSource = 'env';
+            this.credentialsAlsoPresent = [];
         }
         else {
             const resolved = resolveCredential();
             this.#token = resolved.token;
             this.#baseUrl = (config.baseUrl ?? resolved.apiUrl).replace(/\/$/, '');
             this.credentialSource = resolved.source;
+            this.credentialsAlsoPresent = resolved.alsoPresent ?? [];
         }
         this.#fetch = config.fetchImpl ?? fetch;
     }
@@ -57,7 +65,10 @@ export class HttpControlPlane {
     }
     // ── the person's tokens: read and revoke, never mint (ADR-0064, amended 2026-09-27) ──
     async listTokens() {
-        return (await this.#json('GET', '/api/v1/me/tokens')).tokens;
+        const body = await this.#json('GET', '/api/v1/me/tokens');
+        if (!Array.isArray(body.tokens))
+            throw new HttpError('the control plane answered the token list without a list', 502);
+        return body.tokens;
     }
     async revokeToken(id) {
         const response = await this.#request('DELETE', `/api/v1/me/tokens/${encodeURIComponent(id)}`);
@@ -70,6 +81,14 @@ export class HttpControlPlane {
     async revokeAllTokens() {
         return (await this.#json('DELETE', '/api/v1/me/tokens')).revoked;
     }
+    async editToken(id, change) {
+        const response = await this.#request('PATCH', `/api/v1/me/tokens/${encodeURIComponent(id)}`, change);
+        if (response.status === 404)
+            return { kind: 'not-found' };
+        if (!response.ok)
+            return { kind: 'refused', status: response.status, detail: await this.#errorMessage(response) };
+        return { kind: 'edited', token: (await this.#decodeOk(response)) };
+    }
     // ── secrets and variables (values are write-only) ──
     async listSecrets(target) {
         const body = await this.#json('GET', `${this.#scopePath(target)}/secrets`);
@@ -145,38 +164,43 @@ export class HttpControlPlane {
         const response = await this.#request('GET', `/api/v1/runs/${encodeURIComponent(id)}`);
         if (response.status === 404)
             return undefined;
-        return (await this.#decode(response));
+        const body = (await this.#decodeOk(response));
+        // A success that is not a run is not iterated as one: say so, rather than crash on `jobs`.
+        if (body === null || typeof body !== 'object' || typeof body.run !== 'object' || body.run === null || !Array.isArray(body.jobs)) {
+            throw new HttpError(`the control plane's answer for run ${id} is not a run`, response.status);
+        }
+        return body;
     }
     async explainRun(runId) {
         const response = await this.#request('GET', `/api/v1/runs/${encodeURIComponent(runId)}/explain`);
         if (response.status === 404)
             return undefined;
-        return (await this.#decode(response));
+        return (await this.#decodeOk(response));
     }
     async explainDelivery(deliveryId) {
         const response = await this.#request('GET', `/api/v1/deliveries/${encodeURIComponent(deliveryId)}/explain`);
         if (response.status === 404)
             return undefined;
-        return (await this.#decode(response));
+        return (await this.#decodeOk(response));
     }
     async reproduction(runId, job) {
         const query = job === undefined ? '' : `?job=${encodeURIComponent(job)}`;
         const response = await this.#request('GET', `/api/v1/runs/${encodeURIComponent(runId)}/reproduction${query}`);
         if (response.status === 404)
             return undefined;
-        return (await this.#decode(response));
+        return (await this.#decodeOk(response));
     }
     async runTiming(runId) {
         const response = await this.#request('GET', `/api/v1/runs/${encodeURIComponent(runId)}/timing`);
         if (response.status === 404)
             return undefined;
-        return (await this.#decode(response));
+        return (await this.#decodeOk(response));
     }
     async runTests(runId) {
         const response = await this.#request('GET', `/api/v1/runs/${encodeURIComponent(runId)}/tests`);
         if (response.status === 404)
             return undefined;
-        return (await this.#decode(response));
+        return (await this.#decodeOk(response));
     }
     async flakyTests(owner, repo) {
         const body = await this.#json('GET', `/api/v1/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/flaky-tests`);
@@ -471,18 +495,51 @@ export class HttpControlPlane {
     async #decode(response) {
         return await response.json();
     }
-    /** The API's own message, so a refusal explains itself. */
+    /**
+     * Decode a response that must be a success. Every read that answers
+     * `undefined` for a 404 used to decode whatever else came back — so a 403
+     * scope refusal became the value, and `apex logs <run-id>` crashed on
+     * `jobs is not iterable` instead of saying why (BUG-0189). The refusal is
+     * now thrown in the server's words, like every `#json` call.
+     */
+    async #decodeOk(response) {
+        if (!response.ok)
+            throw new HttpError(await this.#errorMessage(response), response.status);
+        try {
+            return await response.json();
+        }
+        catch {
+            throw new HttpError(`the control plane answered ${response.status} with a body that is not JSON`, response.status);
+        }
+    }
+    /** The API's own message, so a refusal explains itself — and a missing grant, how to add it. */
     async #errorMessage(response) {
         try {
             const problem = (await response.json());
-            if (typeof problem.error === 'string')
-                return problem.error;
+            if (typeof problem.error === 'string') {
+                // Only a missing grant costs another call; every other refusal is answered as it came.
+                return response.status === 403 && withPermissionHint(problem.error) !== problem.error ? await this.#hinted(problem.error) : problem.error;
+            }
         }
         catch {
             // a non-JSON body leaves the status
         }
         return `request failed with ${response.status}`;
     }
+    /**
+     * `this token needs <permission>`, with the `apex token edit` that adds it. Which token is asked of the server
+     * (`current` on the list), because the CLI holds the token and not its id; failing that, the hint says `<id>`.
+     */
+    async #hinted(message) {
+        const hinted = withPermissionHint(message);
+        try {
+            const current = (await this.listTokens()).find((t) => t.current === true)?.id;
+            return withPermissionHint(message, current);
+        }
+        catch {
+            return hinted;
+        }
+    }
 }
 /** Adapter: real time, injected so following a run is testable without it. */
 export class RealSleeper {

package/dist/src/infrastructure/credentials.js

@@ -99,30 +99,52 @@ export class FileCredentialStore {
     }
 }
 /**
- * Which credential the CLI uses, in ADR-0064's order:
+ * Which credential the CLI uses (control-plane ADR-0064's order, amended by
+ * this repo's ADR-0005 — the environment outranks the file):
  *
  * 1. `APEX_TOKEN` — a dashboard token, for CI and scripts;
- * 2. the token `apex login` saved — refused outright if the file is readable
+ * 2. `APEX_ADMIN_TOKEN` — the operator's. An explicitly exported variable is
+ *    the more deliberate choice than a file somebody saved once, as `GH_TOKEN`
+ *    outranks `gh`'s stored login; the old order let an operator shell act as
+ *    whichever customer last ran `apex login` on the machine (BUG-0189);
+ * 3. the token `apex login` saved — refused outright if the file is readable
  *    by others, skipped if it has expired or was minted by a different
  *    control plane than the one `APEX_API_URL` names (a token is only ever
  *    sent to the server that issued it);
- * 3. `APEX_ADMIN_TOKEN` — the operator's, unchanged;
  * 4. nothing: `NotConfiguredError`, naming `APEX_TOKEN` and `apex login`.
  */
 export const resolveCredential = (env = process.env, store = new FileCredentialStore(credentialsPath(env)), now = new Date()) => {
     const explicitUrl = set(env[URL_ENV]) ? normaliseUrl(env[URL_ENV]) : undefined;
     const token = env[TOKEN_ENV];
-    if (set(token))
-        return { token, apiUrl: explicitUrl ?? DEFAULT_API_URL, source: 'env' };
+    const admin = env[ADMIN_TOKEN_ENV];
+    /** A saved login this control plane would accept, read only to report it — an unreadable file is simply not one. */
+    const usableSaved = () => {
+        try {
+            const s = store.read();
+            return s !== undefined && !hasExpired(s, now) && (explicitUrl === undefined || explicitUrl === normaliseUrl(s.apiUrl));
+        }
+        catch {
+            return false;
+        }
+    };
+    const withOthers = (resolved, others) => others.length === 0 ? resolved : { ...resolved, alsoPresent: others };
+    if (set(token)) {
+        const others = [];
+        if (set(admin))
+            others.push('operator');
+        if (usableSaved())
+            others.push('login');
+        return withOthers({ token, apiUrl: explicitUrl ?? DEFAULT_API_URL, source: 'env' }, others);
+    }
+    if (set(admin)) {
+        return withOthers({ token: admin, apiUrl: explicitUrl ?? DEFAULT_API_URL, source: 'operator' }, usableSaved() ? ['login'] : []);
+    }
     const saved = store.read();
     if (saved !== undefined && !hasExpired(saved, now)) {
         const mintedBy = normaliseUrl(saved.apiUrl);
         if (explicitUrl === undefined || explicitUrl === mintedBy)
             return { token: saved.token, apiUrl: mintedBy, source: 'login' };
     }
-    const admin = env[ADMIN_TOKEN_ENV];
-    if (set(admin))
-        return { token: admin, apiUrl: explicitUrl ?? DEFAULT_API_URL, source: 'operator' };
     if (saved !== undefined && hasExpired(saved, now)) {
         throw new NotConfiguredError(`the token \`apex login\` saved expired at ${saved.expiresAt}: run \`apex login\` again, or set ${TOKEN_ENV}`);
     }

package/dist/src/infrastructure/loopback-login.js

@@ -41,6 +41,8 @@ export const listenForCallback = async (expectedState, timeoutMs = LOGIN_TIMEOUT
         settle = resolve;
     });
     let done = false;
+    /** The browser's response for a `code` or `denied` callback, held until `conclude` says where it goes. */
+    let held;
     const finish = (result) => {
         if (done)
             return;
@@ -56,10 +58,9 @@ export const listenForCallback = async (expectedState, timeoutMs = LOGIN_TIMEOUT
         const verdict = judgeCallback(url.searchParams, expectedState);
         switch (verdict.kind) {
             case 'code':
-                answer(res, 200, page('Approved', 'The <code>apex</code> CLI has what you approved. You can close this tab.'));
-                break;
             case 'denied':
-                answer(res, 200, page('Declined', 'The request was declined. You can close this tab.'));
+                // Answered by `conclude` once the code is redeemed — a 303 to the web app's bare done page.
+                held = res;
                 break;
             case 'state-mismatch':
                 answer(res, 400, page('Not signed in', 'This callback does not belong to the login waiting in your terminal, so it was refused.'));
@@ -79,8 +80,24 @@ export const listenForCallback = async (expectedState, timeoutMs = LOGIN_TIMEOUT
     return {
         port: server.address().port,
         wait: async () => await settled,
+        conclude: async (location) => {
+            const res = held;
+            held = undefined;
+            if (res === undefined)
+                return;
+            await new Promise((resolve) => {
+                res.once('close', () => resolve());
+                res.writeHead(303, { location, 'cache-control': 'no-store', 'referrer-policy': 'no-referrer', connection: 'close' });
+                res.end(() => resolve());
+            });
+        },
         close: async () => {
             clearTimeout(timer);
+            // A held response nobody concluded (a caller that threw) still gets an answer rather than a hung tab.
+            if (held !== undefined) {
+                answer(held, 200, page('Finished', 'Return to your terminal to see how the <code>apex</code> command ended. You can close this tab.'));
+                held = undefined;
+            }
             finish({ kind: 'timeout' });
             server.closeAllConnections();
             await new Promise((resolve) => server.close(() => resolve()));
@@ -127,17 +144,32 @@ export class HttpLoginExchange {
         }
         const body = (await response.json().catch(() => ({})));
         if (!response.ok)
-            throw new Error(typeof body.error === 'string' ? body.error : `the code exchange failed with ${response.status}`);
-        if (typeof body.token !== 'string' || typeof body.login !== 'string' || typeof body.expiresAt !== 'string') {
+            throw new Error(typeof body['error'] === 'string' ? body['error'] : `the code exchange failed with ${response.status}`);
+        if (typeof body['login'] !== 'string' || typeof body['expiresAt'] !== 'string') {
             throw new Error('the control plane answered the code exchange without a token');
         }
+        const str = (k) => {
+            const v = body[k];
+            return typeof v === 'string' ? { [k]: v } : {};
+        };
+        const list = (k) => {
+            const v = body[k];
+            return Array.isArray(v) ? { [k]: v.filter((r) => typeof r === 'string') } : {};
+        };
+        const source = body['source'];
         return {
-            token: body.token,
-            login: body.login,
-            expiresAt: body.expiresAt,
-            ...(typeof body.id === 'string' ? { id: body.id } : {}),
-            ...(typeof body.name === 'string' ? { name: body.name } : {}),
-            ...(Array.isArray(body.repos) ? { repos: body.repos.filter((r) => typeof r === 'string') } : {}),
+            login: body['login'],
+            expiresAt: body['expiresAt'],
+            // An edit's answer carries no token: it changed one and minted nothing. The caller that needs one says so.
+            ...str('token'),
+            ...str('id'),
+            ...str('name'),
+            ...str('accountId'),
+            ...str('last4'),
+            ...str('createdAt'),
+            ...list('repos'),
+            ...list('permissions'),
+            ...(source === 'dashboard' || source === 'login' || source === 'cli' ? { source } : {}),
         };
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-actions/cli",
-  "version": "0.74.0",
+  "version": "0.75.0",
   "license": "SEE LICENSE IN LICENSE",
   "//files": "Without this npm ships src, test and the CI config alongside the binary a user installs.",
   "files": [