@aisa-one/cli 0.3.0 → 0.5.1

package/dist/commands/mcp.js

@@ -2,27 +2,58 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import chalk from "chalk";
 import { success, error, info, hint } from "../utils/display.js";
 import { expandHome, ensureDir } from "../utils/file.js";
-import { MCP_CONFIGS, MCP_MANIFEST_URL, DOCS_MCP_URL, MCP_DEFAULT_SLUGS } from "../constants.js";
+import { MCP_CONFIGS, MCP_MANIFEST_URL, MCP_CATALOG_URL, DOCS_MCP_URL, MCP_DEFAULT_SLUGS } from "../constants.js";
+import { httpFetch, MAX_ATTEMPTS } from "../utils/http.js";
 import { getApiKey } from "../config.js";
+import { detectClients } from "./connect.js";
 import { join } from "node:path";
-const stripped = (name) => name.replace(/^AIsa\s+/i, "");
-async function fetchLiveServers() {
-    const res = await fetch(MCP_MANIFEST_URL, { signal: AbortSignal.timeout(15_000) });
-    if (!res.ok)
-        throw new Error(`manifest answered HTTP ${res.status}`);
-    const manifest = (await res.json());
-    const live = (manifest.servers ?? [])
+export const stripped = (name) => name.replace(/^AIsa\s+/i, "");
+function toLive(servers) {
+    return servers
         .filter((s) => s.status === "live" && s.slug && s.transport?.endpoint)
         .map((s) => ({
         slug: s.slug,
         name: s.name ?? s.slug,
         endpoint: s.transport.endpoint,
-        toolCount: s.tools?.length ?? 0,
+        toolCount: s.toolCount ?? s.tools?.length ?? 0,
+        description: s.description ?? "",
+        category: s.category ?? "Other",
     }));
+}
+async function readSource(url, attempts) {
+    const res = await httpFetch(url, { idempotent: true, maxAttempts: attempts, timeoutMs: 15_000 });
+    if (!res.ok)
+        throw new Error(`${url} answered HTTP ${res.status}`);
+    const doc = (await res.json());
+    const live = toLive(doc.servers ?? []);
     if (live.length === 0)
-        throw new Error("manifest lists no live servers");
+        throw new Error(`${url} lists no live servers`);
     return live;
 }
+/**
+ * Which servers exist, asked of the host that runs them.
+ *
+ * The index is preferred and the manifest is the fallback, in that order for
+ * one reason: the manifest is a snapshot committed by hand, and on 2026-08-25
+ * it was three servers and 72 tools behind what the host was actually serving.
+ * Anything derived from a running process cannot drift that way.
+ *
+ * The fallback is not defensive padding — the index is newer than some
+ * deployments, and a self-hosted gateway configured through `baseUrl` may
+ * never grow one. A user in either case should still get a working setup from
+ * a slightly stale list rather than an error.
+ */
+export async function fetchLiveServers() {
+    try {
+        // One attempt only: there is somewhere else to go, so spending a retry
+        // budget here just delays the fallback. The manifest is the last resort
+        // and gets the full three.
+        return await readSource(MCP_CATALOG_URL, 1);
+    }
+    catch {
+        return await readSource(MCP_MANIFEST_URL, MAX_ATTEMPTS);
+    }
+}
 /** One config entry in the shape the client actually executes. */
 export function buildEntry(shape, endpoint, key) {
     if (shape === "url") {
@@ -40,14 +71,72 @@ export function buildEntry(shape, endpoint, key) {
 }
 /** The dead entry every pre-v0.3 setup wrote. Remove it on sight. */
 const DEAD_URL = "https://docs.aisa.one/mcp";
+/**
+ * Write the chosen servers (plus the docs server) into one client's config
+ * file. Shared by `aisa mcp setup` and `aisa connect` so the two entry points
+ * cannot drift in how they treat existing files: unparseable JSON is refused,
+ * never replaced, and only the known-dead legacy entry is cleaned up.
+ */
+export function writeClientConfig(agent, chosen, key) {
+    const config = MCP_CONFIGS[agent];
+    if (!config)
+        return { ok: false, reason: `unknown client "${agent}"` };
+    const filePath = expandHome(config.path);
+    let existing = {};
+    if (existsSync(filePath)) {
+        try {
+            existing = JSON.parse(readFileSync(filePath, "utf-8"));
+        }
+        catch {
+            // A file we cannot parse is a file we do not own. Refuse instead of
+            // wiping a user's hand-edited config.
+            return { ok: false, reason: `${config.path} exists but is not valid JSON` };
+        }
+    }
+    else {
+        ensureDir(join(filePath, ".."));
+    }
+    const entries = existing[config.key] || {};
+    // Clean up the dead entry earlier releases wrote, and only that one: an
+    // "aisa" entry the user pointed somewhere else on purpose stays.
+    const stale = entries["aisa"];
+    if (stale?.url === DEAD_URL)
+        delete entries["aisa"];
+    for (const s of chosen) {
+        entries[`aisa-${s.slug}`] = buildEntry(config.shape, s.endpoint, key);
+    }
+    // The docs-search MCP is tiny, unauthenticated, and answers "how do I call
+    // this" questions — always included.
+    entries["aisa-docs"] = buildEntry(config.shape, DOCS_MCP_URL, undefined);
+    existing[config.key] = entries;
+    writeFileSync(filePath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
+    return { ok: true, written: chosen.length + 1 };
+}
 export async function mcpSetupAction(options) {
-    const targets = options.agent && options.agent !== "all" ? [options.agent] : Object.keys(MCP_CONFIGS);
-    for (const agent of targets) {
+    const requested = options.agent && options.agent !== "all" ? [options.agent] : Object.keys(MCP_CONFIGS);
+    for (const agent of requested) {
         if (!MCP_CONFIGS[agent]) {
             error(`Unknown agent: ${agent}. Valid: ${Object.keys(MCP_CONFIGS).join(", ")}, all`);
             return;
         }
     }
+    // Write only where the client actually lives. Until 2026-08-25 `--agent all`
+    // (the default) wrote to every entry in MCP_CONFIGS whether or not it was
+    // installed, which on a machine without Windsurf created ~/.codeium/ and
+    // made the next `aisa connect` offer a card for an editor that was never
+    // there — this command's output became that command's input.
+    const installed = new Set(detectClients().filter((c) => c.detected).map((c) => c.id));
+    const targets = requested.filter((a) => installed.has(a));
+    const absent = requested.filter((a) => !installed.has(a));
+    for (const a of absent) {
+        console.log(`  ${chalk.gray("○")} ${a}: not installed — skipped`);
+    }
+    if (targets.length === 0) {
+        error("None of the requested clients are installed on this machine.");
+        hint("`aisa connect` detects what is here and walks you through it.");
+        process.exitCode = 1;
+        return;
+    }
     // Fetch before touching any file: a setup that cannot see the manifest has
     // nothing true to write.
     let servers;
@@ -72,41 +161,30 @@ export async function mcpSetupAction(options) {
         info("No API key configured — entries are written without credentials, and the");
         info("server's OAuth flow will open in your browser on first use.");
     }
-    for (const agent of targets) {
-        const config = MCP_CONFIGS[agent];
-        const filePath = expandHome(config.path);
-        let existing = {};
-        if (existsSync(filePath)) {
-            try {
-                existing = JSON.parse(readFileSync(filePath, "utf-8"));
-            }
-            catch {
-                // A file we cannot parse is a file we do not own. The old command
-                // replaced it with {} — a user's hand-edited config (comments,
-                // trailing commas) was wiped by a "setup". Refuse instead.
-                error(`${agent}: ${config.path} exists but is not valid JSON — refusing to overwrite it.`);
-                hint("Fix or remove the file, then re-run setup.");
-                continue;
-            }
+    // Nothing is written without saying so first. This command used to change
+    // three config files the moment it was typed, with no preview and no way to
+    // ask what it would do — the opposite of `connect`, which shows the plan and
+    // waits. --yes is how a script opts back in to writing straight away.
+    if (!options.yes) {
+        info("This would write:");
+        for (const agent of targets) {
+            console.log(`  ${chalk.cyan(MCP_CONFIGS[agent].path)}  (${agent}, ${MCP_CONFIGS[agent].shape})`);
         }
-        else {
-            ensureDir(join(filePath, ".."));
-        }
-        const entries = existing[config.key] || {};
-        // Clean up the dead entry earlier releases wrote, and only that one:
-        // an "aisa" entry the user pointed somewhere else on purpose stays.
-        const stale = entries["aisa"];
-        if (stale?.url === DEAD_URL)
-            delete entries["aisa"];
         for (const s of chosen) {
-            entries[`aisa-${s.slug}`] = buildEntry(config.shape, s.endpoint, key);
+            console.log(`    ${chalk.gray(`aisa-${s.slug}`)}  ${stripped(s.name)} (${s.toolCount} tools)`);
+        }
+        hint("Nothing was written. Re-run with --yes to apply, or use `aisa connect` to choose interactively.");
+        return;
+    }
+    for (const agent of targets) {
+        const config = MCP_CONFIGS[agent];
+        const result = writeClientConfig(agent, chosen, key);
+        if (!result.ok) {
+            error(`${agent}: ${result.reason} — refusing to overwrite it.`);
+            hint("Fix or remove the file, then re-run setup.");
+            continue;
         }
-        // The docs-search MCP is tiny, unauthenticated, and answers "how do I call
-        // this" questions — always included.
-        entries["aisa-docs"] = buildEntry(config.shape, DOCS_MCP_URL, undefined);
-        existing[config.key] = entries;
-        writeFileSync(filePath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
-        console.log(`  ${chalk.green("✓")} ${agent}: ${chosen.length + 1} servers (${config.shape}) → ${config.path}`);
+        console.log(`  ${chalk.green("✓")} ${agent}: ${result.written} servers (${config.shape}) → ${config.path}`);
     }
     success(`Configured ${chosen.length} live servers plus docs search for ${targets.length} client(s)`);
     for (const s of chosen) {

package/dist/commands/oauth-login.d.ts

@@ -0,0 +1,33 @@
+import { type Lang } from "./flow.js";
+/**
+ * The whole sign-in, as a function other commands can embed: browser (or
+ * paste-back) OAuth, then the mint. Stores the key and returns it; throws on
+ * any failure. `aisa login` wraps this with CLI messaging; `aisa connect`
+ * runs it as its "Sign in to AIsa" step.
+ */
+/**
+ * Somewhere for the browser to land.
+ *
+ * `aisa login` on its own takes a random loopback port and serves one page on
+ * it. Inside `connect` that is the wrong shape: the sign-in opens in a second
+ * tab, and a random port has nothing to do with the run — the tab finishes on
+ * a page that knows nothing about the setup in progress and leaves the user
+ * to find their way back to the first tab themselves. Handing the run's own
+ * server in means the approval comes home to the address the setup already
+ * lives at, and the tab can return the reader to it.
+ */
+export interface OAuthCatcher {
+    /** Registered with the authorization server before the browser opens. */
+    redirectUri: string;
+    /** Resolves with the authorization code, or rejects with why it will not. */
+    wait(expectedState: string): Promise<string>;
+}
+export declare function mintCliKey(options?: {
+    open?: boolean;
+    lang?: Lang;
+    catcher?: OAuthCatcher;
+}): Promise<string>;
+export declare function oauthLogin(options?: {
+    open?: boolean;
+    lang?: Lang;
+}): Promise<void>;

package/dist/commands/oauth-login.js

@@ -0,0 +1,333 @@
+import chalk from "chalk";
+import { run } from "../utils/exec.js";
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { createInterface } from "node:readline/promises";
+import { error, hint, info, success } from "../utils/display.js";
+import { setApiKey } from "../config.js";
+import { maskKey } from "../config.js";
+import { httpFetch } from "../utils/http.js";
+import { canOpenBrowser } from "../utils/browser.js";
+import { SIGNIN, t } from "./flow.js";
+import { renderSignInPage } from "./signin-page.js";
+import { handOverSignInPage, SIGNIN_PAGE_TTL_MS } from "./serve-signin.js";
+/**
+ * `aisa login` without a key: sign in once in a browser, come back with the
+ * CLI's long-lived key.
+ *
+ * The flow is the standard one every CLI converges on (gh, flyctl, claude):
+ *
+ *   1. register a public OAuth client (Clerk supports dynamic registration)
+ *   2. authorization-code + PKCE, redirecting to a loopback port
+ *   3. exchange the code for an access token
+ *   4. trade that token for the durable "aisa cli" key at /v1/keys/mint,
+ *      and store the key — the token itself is then dropped. One secret on
+ *      disk, and it is the one that does not expire in a day.
+ *
+ * A machine with no browser of its own takes the paste-back variant, and it
+ * is chosen for the user rather than asked for: the URL is printed, the user
+ * authorizes wherever they are sitting, the redirect to 127.0.0.1 fails to
+ * load there — and that is fine, because the code is in the URL, which they
+ * paste back here. PKCE needs the verifier, not a reachable callback, and
+ * the verifier never left this machine. What travels through the clipboard
+ * is a one-time code, not a key.
+ */
+const AUTH_SERVER = "https://clerk.aisa.one";
+/**
+ * Where the sign-in lands when the browser is on a different machine.
+ *
+ * A page that does one thing: show the one-time code so it can be carried
+ * back by hand. The loopback redirect below is better whenever it can be
+ * used — the CLI catches the code itself and nobody copies anything — but it
+ * only works when the browser and this process share a machine.
+ *
+ * This address is a published contract. Every released CLI that names it
+ * keeps sending users there, so it is not to be changed; a new one would
+ * have to be added alongside.
+ */
+const HOSTED_REDIRECT = "https://aisa.one/cli/auth";
+const MINT_URL = "https://api.aisa.one/v1/keys/mint";
+const b64url = (buf) => buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+async function registerClient(redirectUri) {
+    const res = await httpFetch(`${AUTH_SERVER}/oauth/register`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            client_name: "AIsa CLI",
+            redirect_uris: [redirectUri],
+            grant_types: ["authorization_code"],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+            scope: "openid profile email",
+        }),
+        signal: AbortSignal.timeout(15_000),
+    });
+    const body = (await res.json());
+    if (!body.client_id)
+        throw new Error(`client registration failed (HTTP ${res.status})`);
+    return body.client_id;
+}
+/** Wait for the authorization code on the loopback port. */
+/**
+ * How long to hold a loopback callback open before giving up on it.
+ *
+ * Five minutes looked generous until a sign-in took longer than that and the
+ * approval landed on a closed port: the browser said it could not connect,
+ * which reads as "I broke something" rather than "that took too long". A
+ * person who is signing in normally is done inside a minute; the ones who are
+ * not are switching machines, reading the consent screen properly, or being
+ * interrupted. Fifteen minutes costs nothing and covers all of them.
+ */
+const CALLBACK_TIMEOUT_MS = 15 * 60 * 1000;
+/**
+ * And once it does expire, keep answering for a little longer.
+ *
+ * The wait is over and the terminal has said so, but the socket costs nothing
+ * to hold and an approval arriving late deserves a sentence rather than a
+ * connection error. It stops the process from lingering more than this.
+ */
+const AFTER_TIMEOUT_GRACE_MS = 90 * 1000;
+function waitForCallback(port, expectedState, lang) {
+    let expired = false;
+    return new Promise((resolve, reject) => {
+        // A browser we opened may never come back — it was never opened at all,
+        // the tab was closed, the machine has no screen. Waiting for that with
+        // no deadline is a hang, and a hang is the one failure that tells the
+        // user nothing.
+        const giveUp = setTimeout(() => {
+            // Deliberately not closing the server: an approval that arrives now has
+            // to land somewhere that can explain itself. It closes on its own a
+            // little later, and the process does not outlive it.
+            expired = true;
+            const close = setTimeout(() => {
+                srv.close();
+                process.exit(1);
+            }, AFTER_TIMEOUT_GRACE_MS);
+            close.unref?.();
+            reject(new Error(`no response from the browser after ${CALLBACK_TIMEOUT_MS / 60_000} minutes — run 'aisa login' again`));
+        }, CALLBACK_TIMEOUT_MS);
+        giveUp.unref?.();
+        const srv = createServer((req, res) => {
+            clearTimeout(giveUp);
+            const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
+            if (url.pathname !== "/callback") {
+                res.writeHead(404).end();
+                return;
+            }
+            if (expired) {
+                // They approved it; we had already stopped listening for an answer.
+                // Saying so is the difference between "that took too long" and the
+                // browser's own "could not connect", which reads like a broken tool.
+                res
+                    .writeHead(408, { "content-type": "text/html; charset=utf-8" })
+                    .end(renderSignInPage("expired"));
+                return;
+            }
+            const code = url.searchParams.get("code");
+            const state = url.searchParams.get("state");
+            if (!code || state !== expectedState) {
+                res
+                    .writeHead(400, { "content-type": "text/html; charset=utf-8" })
+                    .end(renderSignInPage("failed"));
+                srv.close();
+                reject(new Error("authorization was denied or the response was malformed"));
+                return;
+            }
+            // charset matters more than it looks: without it a browser in a Chinese
+            // locale decodes this as GBK and the em dash arrives as mojibake, which
+            // is what the last version of this line actually did.
+            res
+                .writeHead(200, { "content-type": "text/html; charset=utf-8" })
+                .end(renderSignInPage("ok", Date.now() + SIGNIN_PAGE_TTL_MS));
+            // Not srv.close(): a page that cannot survive a refresh is a page that
+            // says "this site can't be reached" to someone checking their sign-in
+            // really worked. The port goes to a detached copy that serves this one
+            // document for a few minutes, and the terminal comes back now.
+            res.on("finish", () => {
+                clearTimeout(giveUp);
+                handOverSignInPage(port, () => srv.close());
+            });
+            resolve(code);
+        });
+        srv.listen(port, "127.0.0.1");
+        srv.on("error", (e) => {
+            clearTimeout(giveUp);
+            reject(e);
+        });
+    });
+}
+/** The paste-back path: read the redirect URL (or bare code) from stdin. */
+/**
+ * Read the redirect back from whoever has the browser.
+ *
+ * Takes the whole address, which is what a person copying from an address
+ * bar actually has — but also takes a bare code, because someone who reads
+ * the query string will pull out the interesting part instead, and refusing
+ * that would be pedantry.
+ */
+/**
+ * Read the pasted redirect, and give the reader more than one go at it.
+ *
+ * It used to ask once and reject on anything it could not parse. Pasting a
+ * long code into a terminal is exactly where people fumble — the clipboard
+ * did not take, enter went in early, the wrong window was in front — and one
+ * fumble failed the whole sign-in. In `aisa login` that costs the command and
+ * the authorize URL together: the page they just opened is stale, so they
+ * start over from the beginning for a mistyped paste.
+ *
+ * Three tries, each saying what was wrong with the last one. An empty line is
+ * not a mistake, it is "stop asking" — the same meaning it has in every other
+ * prompt in this flow.
+ */
+const PASTE_TRIES = 3;
+function parsePaste(raw) {
+    const text = raw.trim().replace(/^["']|["']$/g, "");
+    try {
+        const url = new URL(text);
+        return { code: url.searchParams.get("code"), state: url.searchParams.get("state") };
+    }
+    catch {
+        // Not a URL. A query fragment, or the code on its own.
+        const params = new URLSearchParams(text.replace(/^\?/, ""));
+        return {
+            code: params.get("code") ?? (/^[A-Za-z0-9._~-]{8,}$/.test(text) ? text : null),
+            state: params.get("state"),
+        };
+    }
+}
+async function waitForPaste(expectedState, lang) {
+    for (let attempt = 1; attempt <= PASTE_TRIES; attempt++) {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await rl.question(t(SIGNIN.prompt, lang));
+        rl.close();
+        if (answer.trim() === "") {
+            throw new Error("sign-in cancelled — run it again when you have the code");
+        }
+        const { code, state } = parsePaste(answer);
+        let wrong;
+        if (!code)
+            wrong = t(SIGNIN.badPaste, lang);
+        // A pasted bare code carries no state to check; a pasted URL does, and a
+        // mismatched one is an older sign-in that would fail confusingly at the
+        // token endpoint instead of here.
+        else if (state !== null && state !== expectedState) {
+            wrong = "that is from an older sign-in — paste the address from the page you just opened";
+        }
+        if (!wrong)
+            return code;
+        if (attempt === PASTE_TRIES)
+            throw new Error(wrong);
+        console.log(`  ${chalk.yellow(wrong)}`);
+        console.log(`  ${chalk.gray(`try again — ${PASTE_TRIES - attempt} left, or press enter to stop`)}\n`);
+    }
+    /* c8 ignore next */
+    throw new Error(t(SIGNIN.badPaste, lang));
+}
+function openBrowser(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    void run(cmd, [url], { timeout: 30_000 }).catch(() => { });
+}
+export async function mintCliKey(options = {}) {
+    const lang = options.lang ?? "en";
+    // Unset means "work it out": a server has no browser to open and waiting
+    // for a click on a machine with no screen is the worst way to find out.
+    // A caller that brought its own catcher has already decided.
+    const useBrowser = options.catcher ? true : (options.open ?? canOpenBrowser());
+    // The redirect has to be registered before the browser opens, and Clerk
+    // matches it exactly — so which of the three it is has to be settled here,
+    // before anything else happens. A loopback port is only worth taking when
+    // this process is the one that will catch the redirect.
+    const port = useBrowser && !options.catcher ? 10000 + Math.floor(Math.random() * 50_000) : 0;
+    const redirectUri = options.catcher
+        ? options.catcher.redirectUri
+        : useBrowser
+            ? `http://127.0.0.1:${port}/callback`
+            : HOSTED_REDIRECT;
+    info(t(SIGNIN.start, lang));
+    const clientId = await registerClient(redirectUri);
+    const verifier = b64url(randomBytes(32));
+    const challenge = b64url(createHash("sha256").update(verifier).digest());
+    const state = b64url(randomBytes(16));
+    const authUrl = new URL(`${AUTH_SERVER}/oauth/authorize`);
+    authUrl.search = new URLSearchParams({
+        response_type: "code",
+        client_id: clientId,
+        redirect_uri: redirectUri,
+        scope: "openid profile email",
+        state,
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+    }).toString();
+    let code;
+    if (options.catcher) {
+        // The run's own server is already listening; nothing to start here.
+        info(t(SIGNIN.willOpen, lang));
+        console.log(`  ${t(SIGNIN.ifNot, lang)}\n  ${authUrl.toString()}\n`);
+        openBrowser(authUrl.toString());
+        code = await options.catcher.wait(state);
+    }
+    else if (useBrowser) {
+        info(t(SIGNIN.willOpen, lang));
+        console.log(`  ${t(SIGNIN.ifNot, lang)}\n  ${authUrl.toString()}\n`);
+        openBrowser(authUrl.toString());
+        code = await waitForCallback(port, state, lang);
+    }
+    else {
+        if (!process.stdin.isTTY) {
+            // Nothing to open and nowhere to paste. Say so now rather than sitting
+            // on a callback that cannot arrive.
+            throw new Error(`no browser here and no terminal to paste into — sign in on a machine that has one, or run: aisa login --key <key>\n  ${authUrl.toString()}`);
+        }
+        console.log(`  ${t(SIGNIN.here, lang)}\n`);
+        console.log(`  ${t(SIGNIN.step1, lang)}\n     ${authUrl.toString()}\n`);
+        console.log(`  ${t(SIGNIN.step2, lang)}\n`);
+        console.log(`  ${t(SIGNIN.step3, lang)}\n`);
+        code = await waitForPaste(state, lang);
+    }
+    const tokenRes = await httpFetch(`${AUTH_SERVER}/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: redirectUri,
+            client_id: clientId,
+            code_verifier: verifier,
+        }),
+        signal: AbortSignal.timeout(20_000),
+    });
+    const tokens = (await tokenRes.json());
+    if (!tokens.access_token) {
+        throw new Error(`token exchange failed: ${tokens.error_description ?? tokens.error ?? tokenRes.status}`);
+    }
+    // The token is a day-long credential; the key is the durable one. Trade up
+    // and keep only the key.
+    const mintRes = await httpFetch(MINT_URL, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${tokens.access_token}` },
+        signal: AbortSignal.timeout(20_000),
+    });
+    if (mintRes.status === 404) {
+        // A deployment without the mint endpoint. The sign-in still proved the
+        // account works; the key just has to travel by hand once.
+        throw new Error("this deployment cannot issue CLI keys — copy one from https://console.aisa.one/api-keys and run: aisa login --key <key>");
+    }
+    const minted = (await mintRes.json());
+    if (!mintRes.ok || !minted.key) {
+        throw new Error(`could not issue a key: ${minted.error ?? `HTTP ${mintRes.status}`}`);
+    }
+    setApiKey(minted.key);
+    return minted.key;
+}
+export async function oauthLogin(options = {}) {
+    if (options.open === false && !process.stdin.isTTY) {
+        error("--no-browser needs an interactive terminal to paste the redirect URL into.");
+        hint("In scripts, use: aisa login --key <key>");
+        process.exitCode = 1;
+        return;
+    }
+    const key = await mintCliKey(options);
+    // The balance follows from the caller, so no "try aisa balance" here: being
+    // told to go and check is worse than being shown.
+    success(`Signed in — CLI key ${maskKey(key)} stored`);
+}

package/dist/commands/prompt.d.ts

@@ -0,0 +1,96 @@
+/** Put the terminal back the way a shell expects it. Safe to call twice. */
+export declare function restoreTerminal(): void;
+/**
+ * Let a child process own the keyboard.
+ *
+ * leaveRaw resumes stdin, which is right when this process is about to read
+ * it again and wrong when something else is. A resumed stream with no `data`
+ * listener still pulls bytes off the file descriptor and drops them — so with
+ * stdio inherited, every keystroke was a race between this process and the
+ * agent it had just started. The user saw it as characters going missing and
+ * lines submitting themselves: enter is the keystroke where losing the race
+ * has consequences.
+ *
+ * Paused, this process reads nothing and the child gets all of it. Anything
+ * here that wants stdin back takes it — the pickers call enterRaw and the
+ * prompts build a fresh readline, and both resume.
+ */
+export declare function handOffStdin(): void;
+/** Can this terminal deliver arrow keys? */
+export declare function interactive(): boolean;
+export interface Choice {
+    /**
+     * A short label on the right, said once where a run of rows begins.
+     *
+     * Eight areas over twenty-five servers, and five of the areas hold exactly
+     * one server — so heading rows produced "heading, row, heading, row", which
+     * is not a grouping, it is a hat on every line. Sorting by area and naming
+     * it only where it changes says the same thing in no extra rows at all: the
+     * rows below inherit it from the blank space, which is what a run is.
+     *
+     * Set it on every row; this decides where to print it. Naming only the
+     * first row of a run put the name off-screen for most of a long one — the
+     * twelve SEO servers do not fit a window, so scrolling into them lost the
+     * word that said what they were. It is printed where the run changes and
+     * again at the top of the window, which is the other place a run can begin
+     * as far as the reader is concerned.
+     */
+    tag?: string;
+    /** Left column, already coloured. */
+    label: string;
+    /** Right column, dimmed. Cut before it can wrap. */
+    meta?: string;
+    /** Extra lines under the cursor's row only. */
+    detail?: string;
+}
+/**
+ * Watch for a change made somewhere else while the picker is open.
+ *
+ * Given a signal that fires the moment the picker is done, because a watcher
+ * that outlives it never stops: each step left one behind, polling every 900ms
+ * for the life of the process — three steps, three pollers, still running long
+ * after the run had finished.
+ */
+export type Interrupt<T> = (signal: AbortSignal, 
+/**
+ * Repaint with a selection made elsewhere, without ending the picker.
+ *
+ * A checklist is not answered by its first tick. Treating every change in
+ * the page as the answer closed this picker on the first box ticked over
+ * there and moved the run on; a person ticking their way down twenty-five
+ * servers should see the ✓ marks arrive here and keep going.
+ */
+apply: (indexes: number[]) => void) => Promise<T | undefined>;
+export interface PickResult<T> {
+    /** Indexes chosen here, or undefined when something else answered. */
+    picked?: number[];
+    /** Whatever the interrupt resolved with. */
+    interrupted?: T;
+    aborted?: boolean;
+    /** Escape: the question was left rather than answered. */
+    escaped?: boolean;
+}
+/**
+ * Draw a picker until the user commits, or `watch` resolves.
+ *
+ * `multi` decides whether space toggles and enter confirms a set, or the
+ * cursor itself is the answer.
+ */
+export declare function pick<T>(opts: {
+    title: string;
+    choices: Choice[];
+    multi: boolean;
+    initial?: number[];
+    cursor?: number;
+    hint: string;
+    watch?: Interrupt<T>;
+    /**
+     * Called whenever the local selection changes, so the other side can follow.
+     *
+     * On a checklist that is a tick; on a single choice it is the cursor
+     * itself, which is the only way this terminal has of saying "this one" —
+     * it is painted as chosen, so treating the move as a hover left the page
+     * showing nothing while the terminal plainly showed something.
+     */
+    onToggle?: (indexes: number[]) => void;
+}): Promise<PickResult<T>>;