@apex-actions/cli 0.74.0 → 0.76.0

package/dist/src/domain/grants.js

@@ -0,0 +1,111 @@
+// domain layer — see ../../../../docs/conventions.md §1
+/**
+ * Complimentary access from the terminal (control-plane ADR-0056 as amended by
+ * ADR-0079, TASK-0199): the grant and installation shapes the admin API
+ * answers with, the checks `apex grant` makes before a round trip — the
+ * control plane makes them again — and how each reads as a line.
+ */
+/** The admin API's limits on a grant (control-plane `domain/grant.ts`). */
+export const MAX_GRANT_MINUTES = 120_000;
+export const MAX_GRANT_CONCURRENCY = 50;
+export const MAX_GRANT_REASON = 500;
+const whole = (raw, min, max) => {
+    if (raw === undefined || !/^[0-9]+$/.test(raw.trim()))
+        return undefined;
+    const n = Number(raw.trim());
+    return Number.isSafeInteger(n) && n >= min && n <= max ? n : undefined;
+};
+/**
+ * `--until YYYY-MM-DD`: the grant ends at the end of that UTC day, as the Console's form has it — so the
+ * instant sent is the next day's midnight. A day that is not a real date, or not after `now`, is refused.
+ */
+export const endOfDay = (day, now) => {
+    const value = day.trim();
+    const start = /^\d{4}-\d{2}-\d{2}$/.test(value) ? new Date(`${value}T00:00:00.000Z`) : new Date(Number.NaN);
+    if (Number.isNaN(start.getTime()) || start.toISOString().slice(0, 10) !== value)
+        return { ok: false, problem: `--until must be a date, YYYY-MM-DD, got ${JSON.stringify(day)}` };
+    const end = new Date(start.getTime() + 86_400_000);
+    if (end.getTime() <= now.getTime())
+        return { ok: false, problem: '--until must be today or later — the grant ends at the end of that UTC day' };
+    return { ok: true, value: end.toISOString() };
+};
+const minutesProblem = `--minutes must be a whole number from 1 to ${MAX_GRANT_MINUTES.toLocaleString('en-US')}`;
+const concurrencyProblem = `--concurrency must be a whole number from 1 to ${MAX_GRANT_CONCURRENCY}`;
+/** `apex grant create`'s arguments, checked. */
+export const createGrantBody = (installation, flags, now) => {
+    const installationId = whole(installation, 1, Number.MAX_SAFE_INTEGER);
+    if (installationId === undefined)
+        return { ok: false, problem: `expected a positive installation id, got ${JSON.stringify(installation)}` };
+    const minutesPerMonth = whole(flags.minutes, 1, MAX_GRANT_MINUTES);
+    if (minutesPerMonth === undefined)
+        return { ok: false, problem: minutesProblem };
+    const concurrency = whole(flags.concurrency, 1, MAX_GRANT_CONCURRENCY);
+    if (concurrency === undefined)
+        return { ok: false, problem: concurrencyProblem };
+    const reason = flags.reason?.trim() ?? '';
+    if (reason === '' || reason.length > MAX_GRANT_REASON)
+        return { ok: false, problem: `--reason is required, up to ${MAX_GRANT_REASON} characters — who this is for, and why they run free` };
+    if (flags.until === undefined)
+        return { ok: true, value: { installationId, minutesPerMonth, concurrency, reason } };
+    const until = endOfDay(flags.until, now);
+    return until.ok ? { ok: true, value: { installationId, minutesPerMonth, concurrency, reason, expiresAt: until.value } } : until;
+};
+/** `apex grant update`'s flags, checked: at least one change, each well-formed, and not both an end date and none. */
+export const updateGrantBody = (flags, now) => {
+    const body = {};
+    if (flags.minutes !== undefined) {
+        const n = whole(flags.minutes, 1, MAX_GRANT_MINUTES);
+        if (n === undefined)
+            return { ok: false, problem: minutesProblem };
+        body.minutesPerMonth = n;
+    }
+    if (flags.concurrency !== undefined) {
+        const n = whole(flags.concurrency, 1, MAX_GRANT_CONCURRENCY);
+        if (n === undefined)
+            return { ok: false, problem: concurrencyProblem };
+        body.concurrency = n;
+    }
+    if (flags.until !== undefined && flags.noEnd === true)
+        return { ok: false, problem: 'pass --until or --no-end, not both' };
+    if (flags.noEnd === true)
+        body.expiresAt = null;
+    if (flags.until !== undefined) {
+        const until = endOfDay(flags.until, now);
+        if (!until.ok)
+            return until;
+        body.expiresAt = until.value;
+    }
+    if (Object.keys(body).length === 0)
+        return { ok: false, problem: 'nothing to change: pass --minutes, --concurrency, --until or --no-end' };
+    return { ok: true, value: body };
+};
+const day = (iso) => iso?.slice(0, 10);
+/** One grant as a line: whose, how it stands, the month so far, and who granted it and why. */
+export const grantLine = (g) => {
+    const used = g.usedMinutes === undefined ? '' : `${Math.floor(g.usedMinutes).toLocaleString('en-US')} of `;
+    const state = g.state === 'ended' ? `ended ${day(g.endedAt ?? g.revokedAt) ?? ''}${g.revokedBy === undefined ? '' : ` by ${g.revokedBy}`}`.trim() : g.dormant ? `${g.state}, dormant — they pay for a plan` : g.state;
+    const until = g.expiresAt === undefined ? '' : `, until ${day(g.expiresAt) ?? ''}`;
+    return `${g.id}  ${g.owner} (installation ${g.installationId}) — ${state}; ${used}${g.minutesPerMonth.toLocaleString('en-US')} minutes a month, ${g.concurrency} at once${until}; granted by ${g.grantedBy}: ${g.reason}`;
+};
+/** What a create means, in the Console's words: open, a replacement, or dormant behind a subscription. */
+export const createdLine = (c) => c.dormant
+    ? `Granted to ${c.grant.owner}. They pay for a plan, so the grant is dormant until they stop.`
+    : `Granted to ${c.grant.owner}.${c.superseded === undefined ? '' : ' It replaces the grant they held.'}`;
+export const revokedLine = (r) => `Revoked the grant for ${r.grant.owner}.${r.cancelledJobs > 0 ? ` ${r.cancelledJobs} queued job${r.cancelledJobs === 1 ? ' was' : 's were'} cancelled.` : ''}`;
+/** One installation as a line: whose, and what Apex knows of it — or that it is new. */
+export const installationLine = (i) => {
+    const known = [
+        i.accountId === undefined ? 'no Account' : `Account ${i.accountId}`,
+        ...(i.subscription === undefined ? [] : [`subscription ${i.subscription}`]),
+        ...(i.grant === undefined ? [] : [`grant ${i.grant}`]),
+        ...(i.recentUsage ? ['ran in the last 30 days'] : []),
+    ];
+    return `${i.installationId}  ${i.account.login} (${i.account.type === 'User' ? 'personal account' : 'organization'})${i.listedAsTenant ? '' : ' — new'} · ${known.join(', ')}`;
+};
+/**
+ * The control plane refuses a grant write made with the machine token, and every operator route to an Account
+ * token. Either way the remedy is the operator token: say so.
+ */
+export const withOperatorHint = (message) => /machine token|no token reaches|operator’s|only the grant routes|not signed in/.test(message)
+    ? `${message} — sign in as an operator with: apex login --console`
+    : message;

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

@@ -2,7 +2,8 @@
 import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
-import { NotConfiguredError, apiUrlFrom, resolveCredential } from './credentials.js';
+import { withPermissionHint } from '../domain/credentials.js';
+import { NotConfiguredError, apiUrlFrom, resolveCredential, resolveOperatorCredential } 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. */
 export class HttpError extends Error {
@@ -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();
+            const resolved = config.operator === true ? resolveOperatorCredential() : 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`);
@@ -223,6 +247,22 @@ export class HttpControlPlane {
     async accountsBackfill(input, apply) {
         return await this.#json('POST', `/api/v1/admin/accounts/backfill${apply ? '?apply=true' : ''}`, input);
     }
+    // ── complimentary access (control-plane ADR-0056, ADR-0079): the admin API's shapes, unchanged ──
+    async listGrants() {
+        return (await this.#json('GET', '/api/v1/admin/grants')).grants;
+    }
+    async createGrant(body) {
+        return await this.#json('POST', '/api/v1/admin/grants', body);
+    }
+    async updateGrant(id, body) {
+        return (await this.#json('PATCH', `/api/v1/admin/grants/${encodeURIComponent(id)}`, body)).grant;
+    }
+    async revokeGrant(id) {
+        return await this.#json('DELETE', `/api/v1/admin/grants/${encodeURIComponent(id)}`);
+    }
+    async listInstallations() {
+        return (await this.#json('GET', '/api/v1/admin/installations')).installations;
+    }
     async accountsUnconnected() {
         return (await this.#json('GET', '/api/v1/admin/accounts/unconnected')).installations;
     }
@@ -471,18 +511,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

@@ -9,6 +9,7 @@ export const URL_ENV = 'APEX_API_URL';
 export const WEB_URL_ENV = 'APEX_WEB_URL';
 export const TOKEN_ENV = 'APEX_TOKEN';
 export const ADMIN_TOKEN_ENV = 'APEX_ADMIN_TOKEN';
+export const CONSOLE_URL_ENV = 'APEX_CONSOLE_URL';
 const set = (value) => value !== undefined && value !== '';
 /** The control plane: `APEX_API_URL`, or the hosted service. */
 export const apiUrlFrom = (env = process.env) => normaliseUrl(set(env[URL_ENV]) ? env[URL_ENV] : DEFAULT_API_URL);
@@ -35,6 +36,11 @@ export class InsecureCredentialsError extends NotConfiguredError {
 }
 /** `$XDG_CONFIG_HOME/apex/credentials`, defaulting to `~/.config`. */
 export const credentialsPath = (env = process.env) => join(set(env['XDG_CONFIG_HOME']) ? env['XDG_CONFIG_HOME'] : join(homedir(), '.config'), 'apex', 'credentials');
+/**
+ * `$XDG_CONFIG_HOME/apex/console-credentials`: where `apex login --console` keeps the operator token
+ * (control-plane ADR-0079) — beside the Account login, never in place of it.
+ */
+export const consoleCredentialsPath = (env = process.env) => join(dirname(credentialsPath(env)), 'console-credentials');
 /**
  * Adapter: the credentials file `apex login` writes.
  *
@@ -99,30 +105,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}`);
     }
@@ -132,3 +160,20 @@ export const resolveCredential = (env = process.env, store = new FileCredentialS
     }
     throw new NotConfiguredError();
 };
+/**
+ * Which credential an operator command — `apex grant`, `apex tenant installations` — uses (control-plane
+ * ADR-0079): the operator token `apex login --console` saved, when it is private, unexpired and was minted by
+ * the control plane `APEX_API_URL` names; otherwise the ordinary order ({@link resolveCredential}), in which
+ * the machine token can read grants and is refused every write. An expired operator token is skipped, and
+ * the refusal that follows says to sign in again.
+ */
+export const resolveOperatorCredential = (env = process.env, consoleStore = new FileCredentialStore(consoleCredentialsPath(env)), fallback = () => resolveCredential(env), now = new Date()) => {
+    const explicitUrl = set(env[URL_ENV]) ? normaliseUrl(env[URL_ENV]) : undefined;
+    const saved = consoleStore.read();
+    if (saved !== undefined && !hasExpired(saved, now)) {
+        const mintedBy = normaliseUrl(saved.apiUrl);
+        if (explicitUrl === undefined || explicitUrl === mintedBy)
+            return { token: saved.token, apiUrl: mintedBy, source: 'console' };
+    }
+    return fallback();
+};

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

@@ -0,0 +1,82 @@
+// infrastructure layer — see ../../../../docs/conventions.md §1
+import { existsSync } from 'node:fs';
+import { hostname, platform, release, type } from 'node:os';
+import { headlessReason, isDevicePollError, normaliseUrl } from '../domain/credentials.js';
+import { redeemedFrom } from './loopback-login.js';
+/**
+ * The device flow's adapters (control-plane ADR-0075): the two calls, what this machine says about
+ * itself, and whether a browser can open here at all.
+ */
+/** Why no browser can open here, read from this process's environment; `undefined` when one can. */
+export const detectHeadless = () => headlessReason({ env: process.env, platform: process.platform, dockerenv: existsSync('/.dockerenv') });
+/** What the approval page shows as "reported by the terminal": this machine's name and system. */
+export const machineReport = () => ({
+    hostname: hostname().slice(0, 100),
+    os: `${type()} ${release()} (${platform()})`.slice(0, 100),
+});
+export const sleep = async (ms) => await new Promise((resolve) => setTimeout(resolve, ms));
+/** Adapter: `POST /api/v1/cli/device` and the `{ deviceCode }` poll of `POST /api/v1/cli/token`. No credential either way. */
+export class HttpDeviceExchange {
+    #baseUrl;
+    #fetch;
+    constructor(baseUrl, fetchImpl = fetch) {
+        this.#baseUrl = normaliseUrl(baseUrl);
+        this.#fetch = fetchImpl;
+    }
+    async start(request) {
+        const body = await this.#post('/api/v1/cli/device', {
+            name: request.name,
+            purpose: request.purpose,
+            ...(request.days === undefined ? {} : { expiresInDays: request.days }),
+            ...(request.repos === undefined ? {} : { repos: request.repos }),
+            ...(request.permissions === undefined ? {} : { permissions: request.permissions }),
+            ...(request.accountId === undefined ? {} : { accountId: request.accountId }),
+            ...(request.tokenId === undefined ? {} : { tokenId: request.tokenId }),
+            ...(request.allRepositories === true ? { allRepositories: true } : {}),
+            ...(request.os === undefined ? {} : { os: request.os }),
+            ...(request.hostname === undefined ? {} : { hostname: request.hostname }),
+        });
+        if (!body.ok) {
+            if (body.status === 429)
+                throw new Error('too many device logins from this address this hour — wait, or approve in a browser on this machine with --browser');
+            throw new Error(typeof body.json['error'] === 'string' ? body.json['error'] : `starting the device login failed with ${body.status}`);
+        }
+        const j = body.json;
+        if (typeof j['deviceCode'] !== 'string' || typeof j['userCode'] !== 'string' || typeof j['verificationUri'] !== 'string') {
+            throw new Error('the control plane answered the device login without a code — is it older than this CLI?');
+        }
+        return {
+            deviceCode: j['deviceCode'],
+            userCode: j['userCode'],
+            verificationUri: j['verificationUri'],
+            expiresIn: typeof j['expiresIn'] === 'number' ? j['expiresIn'] : 600,
+            interval: typeof j['interval'] === 'number' ? j['interval'] : 5,
+        };
+    }
+    async poll(deviceCode) {
+        const body = await this.#post('/api/v1/cli/token', { deviceCode });
+        if (body.ok)
+            return { kind: 'minted', minted: redeemedFrom(body.json) };
+        const error = body.json['error'];
+        const interval = body.json['interval'];
+        if (body.status === 400 && isDevicePollError(error))
+            return { kind: error, ...(typeof interval === 'number' ? { interval } : {}) };
+        throw new Error(typeof error === 'string' ? error : `polling the device login failed with ${body.status}`);
+    }
+    async #post(path, payload) {
+        let response;
+        try {
+            response = await this.#fetch(`${this.#baseUrl}${path}`, {
+                method: 'POST',
+                headers: { accept: 'application/json', 'content-type': 'application/json' },
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(30_000),
+            });
+        }
+        catch (err) {
+            throw new Error(`${this.#baseUrl} is unreachable: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+        }
+        const json = (await response.json().catch(() => ({})));
+        return { ok: response.ok, status: response.status, json };
+    }
+}

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,39 @@ 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('the control plane answered the code exchange without a token');
-        }
-        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') } : {}),
-        };
+            throw new Error(typeof body['error'] === 'string' ? body['error'] : `the code exchange failed with ${response.status}`);
+        return redeemedFrom(body);
     }
 }
+/**
+ * What `POST /api/v1/cli/token` minted, from its answer — shared by the loopback's redemption and the
+ * device flow's poll, which end in the same token. Throws when the answer names nobody.
+ */
+export const redeemedFrom = (body) => {
+    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 {
+        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.76.0",
   "license": "SEE LICENSE IN LICENSE",
   "//files": "Without this npm ships src, test and the CI config alongside the binary a user installs.",
   "files": [