flowsprite 0.1.0

package/dist/mcpConfig.js

@@ -0,0 +1,266 @@
+import { lstatSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { writeFileAtomic } from "./credentials.js";
+/**
+ * MUTATE ONE ENTRY IN SOMEONE ELSE'S FILE, OR REFUSE.
+ *
+ * The files this writes are not Flowsprite's. `~/.claude.json` on this machine is
+ * 348 KB of live state — projects, history, onboarding flags — and a client's MCP
+ * config is the only copy the person has. So the contract is preservation first:
+ * parse, set exactly `mcpServers.flowsprite`, write the whole object back, and
+ * REFUSE anything that cannot be parsed back out (an unparsable file, a non-object
+ * root, a symlink) rather than replacing it with a file this CLI understands.
+ * A refusal leaves a person with a config they can fix; an overwrite does not.
+ *
+ * The write goes through `writeFileAtomic` from `credentials.ts` — the same
+ * unique-name + `O_EXCL` + rename + chmod sequence that file argues for at length.
+ * It is imported rather than restated so the two writers cannot drift.
+ */
+/** The server name this CLI owns in every client's config. */
+export const SERVER_NAME = "flowsprite";
+const FILE_MODE = 0o600;
+/** The suffix a backup's name carries, between the config name and the epoch. */
+export const BACKUP_MARKER = ".flowsprite-backup-";
+export class McpConfigError extends Error {
+    code;
+    path;
+    constructor(code, path, message) {
+        super(message);
+        this.name = "McpConfigError";
+        this.code = code;
+        this.path = path;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Read a config for mutation, or throw the typed refusal.
+ *
+ * Returns `null` for a file that is simply not there — the one tolerated absence,
+ * because creating a client's first config is the normal case.
+ */
+function readForMutation(path) {
+    let stat;
+    try {
+        // `lstatSync`, never `statSync`: the question is what is AT this path, and a
+        // `statSync` on a symlink answers about its target.
+        stat = lstatSync(path);
+    }
+    catch {
+        return null;
+    }
+    if (stat.isSymbolicLink()) {
+        // THE LEAF ONLY. A symlinked DIRECTORY on the way here is FOLLOWED, by design:
+        // a dotfiles setup that symlinks `~/.cursor` or the whole Application Support
+        // folder is an ordinary arrangement, and refusing it would make this CLI
+        // unusable for the people most likely to have four AI clients configured. What
+        // is refused is a symlinked CONFIG FILE, where writing through the link would
+        // put a bearer token into a file the person did not name.
+        throw new McpConfigError("symlink", path, `${path} is a symbolic link; refusing to write through it.`);
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        // A config that `lstat` can see but this process cannot READ. Without this the
+        // EACCES escapes as a raw node error to `bin.ts`'s last-resort handler, which
+        // prints one redacted line with no remedy in it. The person needs to be told
+        // WHICH file and that the problem is permission, not content.
+        throw new McpConfigError("unreadable", path, `${path} could not be read (${err.code ?? "read failed"}); refusing to replace a file this CLI cannot preserve.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new McpConfigError("unparsable", path, `${path} is not valid JSON; refusing to overwrite it.`);
+    }
+    if (!isPlainObject(parsed)) {
+        throw new McpConfigError("not_object", path, `${path} is not a JSON object; refusing to overwrite it.`);
+    }
+    // A `mcpServers` that is not an object is the same problem one level down: the
+    // only way to add an entry would be to discard whatever is there.
+    if (parsed.mcpServers !== undefined && !isPlainObject(parsed.mcpServers)) {
+        throw new McpConfigError("not_object", path, `${path} has an mcpServers value that is not an object; refusing to overwrite it.`);
+    }
+    return { raw, root: parsed };
+}
+/**
+ * Every `<name>.flowsprite-backup-*` already sitting beside `path` that is a
+ * REGULAR FILE.
+ *
+ * `.isFile()` is the load-bearing half. A directory or a symlink wearing a backup
+ * name is not a backup — nothing can be restored from it — and counting it would
+ * make this function answer "already backed up" for a path where no backup exists,
+ * which is how a config gets mutated with nothing saved. It also keeps this
+ * agreeing with the exclusive create below, which refuses the same things: the two
+ * must have one answer, or the fast path waves through exactly what the slow path
+ * would have caught.
+ */
+function existingBackups(path) {
+    const base = basename(path);
+    const dir = dirname(path);
+    try {
+        return readdirSync(dir).filter((n) => {
+            if (!n.startsWith(`${base}${BACKUP_MARKER}`))
+                return false;
+            try {
+                return lstatSync(join(dir, n)).isFile();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The mode the config comes out with: 0600, unless what is there is already
+ * STRICTER, in which case it is kept.
+ *
+ * The direction matters. A config that holds a bearer token must not stay 0644
+ * because it happened to be 0644 before; but a person who has locked their config
+ * down to 0400 has made a decision this CLI has no business widening. "Stricter"
+ * is "no bits outside owner read/write".
+ *
+ * (An earlier version also excluded a mode of 0, reasoning that preserving it
+ * would leave a file nothing can read back. That branch was UNREACHABLE: a 0-mode
+ * config fails `readForMutation`'s read first and is refused as `unreadable`
+ * before this function is ever called. It is deleted rather than kept as a
+ * comforting no-op.)
+ */
+function modeFor(path) {
+    let current;
+    try {
+        current = statSync(path).mode & 0o777;
+    }
+    catch {
+        return FILE_MODE;
+    }
+    return (current & ~FILE_MODE) === 0 ? current : FILE_MODE;
+}
+/**
+ * Set `mcpServers.flowsprite` in a JSON client config, preserving everything else.
+ *
+ * ONE BACKUP PER PATH, FOREVER (brief DM2 / ASSUME-2). The first write beside a
+ * file that has no `.flowsprite-backup-*` takes one; every later write leaves it
+ * alone. The point of the backup is the state BEFORE this CLI ever touched the
+ * file, and a rolling backup overwrites exactly that with a copy of our own work.
+ * There is no restore command in v1: the file is named in the output and a person
+ * (or an agent) moves it back.
+ *
+ * THE BACKUP IS WRITTEN WITH A DIRECT `wx`, NOT THROUGH `writeFileAtomic`, and
+ * that is the whole difference between a backup and a lie. `writeFileAtomic` puts
+ * `O_EXCL` on its TEMP file and then RENAMES over the destination — rename
+ * replaces whatever is there, so two writes aiming at one backup name (two
+ * installs inside the same second, for two different clients' configs that share
+ * a directory, or two `flowsprite` processes) would leave a "backup" that is a
+ * copy of the ALREADY-MUTATED file. A direct `O_EXCL` create cannot: the second
+ * one gets EEXIST, which is read here as "a backup already exists", the same
+ * answer the readdir check gives. The check is the fast path; this is the one
+ * that is actually a guarantee.
+ */
+export function upsertJsonConfig(input) {
+    const { path, entry } = input;
+    const existing = readForMutation(path);
+    const root = existing?.root ?? {};
+    const servers = isPlainObject(root.mcpServers) ? root.mcpServers : {};
+    const replaced = Object.prototype.hasOwnProperty.call(servers, SERVER_NAME);
+    let backup;
+    if (existing !== null && existingBackups(path).length === 0) {
+        const stamp = Math.floor((input.now ?? Date.now()) / 1000);
+        const candidate = join(dirname(path), `${basename(path)}${BACKUP_MARKER}${stamp}`);
+        try {
+            // 0600 whatever the original was: the copy may hold a bearer token, and a
+            // backup nobody can read is a smaller problem than one everybody can.
+            writeFileSync(candidate, existing.raw, { flag: "wx", mode: FILE_MODE });
+            backup = candidate;
+        }
+        catch (err) {
+            // EEXIST IS NOT BY ITSELF "ALREADY BACKED UP". `O_EXCL` fails with EEXIST for
+            // anything at that path — a regular file, a directory, and a DANGLING SYMLINK
+            // too. Read as a bare success, a dangling symlink wearing the backup name
+            // would mean: nothing saved, no error, and the config mutated anyway. So the
+            // success case is narrowed to what can actually be restored from, and
+            // everything else is a refusal taken BEFORE the write, leaving the config
+            // exactly as it was.
+            //
+            // Anything that is not EEXIST (a read-only directory, ENOSPC) stops the write
+            // for the same reason: losing the only copy of someone's config is the
+            // failure this whole file exists to avoid.
+            if (err.code !== "EEXIST")
+                throw err;
+            let isFile = false;
+            try {
+                isFile = lstatSync(candidate).isFile();
+            }
+            catch {
+                isFile = false;
+            }
+            if (!isFile) {
+                throw new McpConfigError("backup_blocked", path, `${candidate} is in the way of this config's backup and is not a regular file; ` +
+                    "refusing to change the config without one.");
+            }
+            // A real backup is already there: the pre-Flowsprite state is saved, so this
+            // is a success and `backup` stays undefined because THIS call did not take one.
+        }
+    }
+    servers[SERVER_NAME] = entry;
+    root.mcpServers = servers;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileAtomic(path, `${JSON.stringify(root, null, 2)}\n`, modeFor(path), input.unique);
+    return { wrote: true, replaced, ...(backup === undefined ? {} : { backup }) };
+}
+/**
+ * Is `name` already registered in this JSON config?
+ *
+ * FALSE FOR EVERYTHING IT CANNOT READ, deliberately: this answers "must I ask
+ * before replacing?", and a file that is missing, unreadable or malformed has no
+ * entry to protect. It is not a substitute for the refusals above — the write
+ * still goes through `upsertJsonConfig`, which throws on exactly those files.
+ */
+export function jsonConfigHasServer(path, name = SERVER_NAME) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (!isPlainObject(parsed) || !isPlainObject(parsed.mcpServers))
+            return false;
+        return Object.prototype.hasOwnProperty.call(parsed.mcpServers, name);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Is `name` already a `[mcp_servers.<name>]` section in a codex `config.toml`?
+ *
+ * A TEXT SCAN, NOT A TOML PARSE — this repo has no TOML library and card FLO-501
+ * adds no dependency (NC-1). It matches the section-header form `codex mcp add`
+ * itself writes, MEASURED 2026-09-15 on a throwaway `CODEX_HOME`:
+ *
+ *     [mcp_servers.probe]
+ *     url = "https://example.invalid/mcp"
+ *     bearer_token_env_var = "X"
+ *
+ * CEILING, stated because the next reader will assume more: an entry written by
+ * hand as a quoted key (`["mcp_servers"."flowsprite"]`) or as an inline table
+ * under a single `mcp_servers = { … }` is NOT seen by this, so the answer is
+ * "no conflict" and `codex mcp add` then overwrites that entry — which is what it
+ * does anyway (measured: a second `codex mcp add` with the same name replaces the
+ * section and exits 0). ponytail: a real TOML reader is the upgrade path, and it
+ * costs a dependency this package does not have.
+ */
+export function tomlConfigHasServer(path, name = SERVER_NAME) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`^[ \\t]*\\[mcp_servers\\.${escaped}\\][ \\t]*$`, "m").test(text);
+}

package/dist/mcpInstall.js

@@ -0,0 +1,225 @@
+import { join } from "node:path";
+import { SERVER_NAME } from "./mcpConfig.js";
+/** Every client this CLI can install, in the order they are offered. */
+export const CLIENTS = ["claude-code", "codex", "claude-desktop", "cursor"];
+export function isClientId(value) {
+    return CLIENTS.includes(value);
+}
+/** The env var codex is told to read the bearer from, unless `--token-env` names another. */
+export const TOKEN_ENV_DEFAULT = "FLOWSPRITE_MCP_TOKEN";
+/** What `mcp print` puts where the bearer goes, unless `--reveal` is given on a TTY. */
+export const TOKEN_PLACEHOLDER = "<YOUR_TOKEN>";
+/**
+ * The `mcp-remote` version Claude Desktop is pointed at.
+ *
+ * MEASURED, not guessed: `npm view mcp-remote version` -> 0.14.2 on 2026-09-15.
+ * It is PINNED because the entry this CLI writes is `npx -y mcp-remote@<version>`
+ * and an unpinned `npx -y mcp-remote` re-resolves to whatever is newest every time
+ * Claude Desktop starts the server — a supply-chain surface on a process that
+ * holds a live Flowsprite bearer. Bump it deliberately, in a card, with the
+ * measurement re-run.
+ */
+export const MCP_REMOTE_VERSION = "0.14.2";
+function nonEmpty(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/**
+ * THE ONE DERIVATION OF EVERY CLIENT'S CONFIG PATH.
+ *
+ * Both the fallback writer and the "is flowsprite already registered?" check read
+ * it from here, so they cannot aim at different files — which is the shape of the
+ * bug where a conflict check passes over a file the write then clobbers.
+ *
+ * Paths, and where each came from:
+ *  - claude-code: `$CLAUDE_CONFIG_DIR/.claude.json`, else `~/.claude.json`. MEASURED
+ *    2026-09-15: `claude mcp add --transport http … --scope user` wrote exactly that
+ *    file, with a top-level `mcpServers` entry `{type:"http", url, headers}`.
+ *  - codex: `$CODEX_HOME/config.toml`, else `~/.codex/config.toml`. MEASURED: a
+ *    throwaway `CODEX_HOME` got a `config.toml` holding `[mcp_servers.<name>]`.
+ *  - claude-desktop: the platform's application-support path. The darwin one is
+ *    MEASURED on this machine (its live flowsprite entry is the `npx mcp-remote`
+ *    shape this file writes); win32 and linux are from Claude Desktop's own
+ *    documented locations and are UNVERIFIED here — no install of either to read.
+ *  - cursor: `~/.cursor/mcp.json` (ASSUME-1; no Cursor install on this machine,
+ *    which is why that client is only WRITTEN when the file is already there).
+ */
+export function configPathFor(client, ctx) {
+    const { home, platform, env } = ctx;
+    switch (client) {
+        case "claude-code":
+            return { path: join(nonEmpty(env.CLAUDE_CONFIG_DIR) ?? home, ".claude.json"), format: "json" };
+        case "codex":
+            return { path: join(nonEmpty(env.CODEX_HOME) ?? join(home, ".codex"), "config.toml"), format: "toml" };
+        case "claude-desktop": {
+            if (platform === "darwin") {
+                return {
+                    path: join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json"),
+                    format: "json",
+                };
+            }
+            if (platform === "win32") {
+                const appData = nonEmpty(env.APPDATA) ?? join(home, "AppData", "Roaming");
+                return { path: join(appData, "Claude", "claude_desktop_config.json"), format: "json" };
+            }
+            return { path: join(home, ".config", "Claude", "claude_desktop_config.json"), format: "json" };
+        }
+        default:
+            return { path: join(home, ".cursor", "mcp.json"), format: "json" };
+    }
+}
+/** The command each client registers through, or null where it has none. */
+export function commandFor(client) {
+    if (client === "claude-code")
+        return "claude";
+    if (client === "codex")
+        return "codex";
+    return null;
+}
+function bearer(token) {
+    return `Bearer ${token}`;
+}
+/**
+ * The plan for one client. Pure — every fact comes from `ctx`.
+ *
+ * The `--token-env` rules are NOT here: `cli.ts` resolves that flag before
+ * building the context, because for claude-code it means "read the CURRENT value
+ * of that variable and use it as the bearer" (a resolution that can fail) while
+ * for codex it means "pass the NAME through", and for the two write clients it is
+ * refused outright — their configs hold literal values, so a variable name in one
+ * is a config that silently does not authenticate.
+ */
+export function planInstall(client, ctx) {
+    const url = ctx.mcpEndpoint;
+    const { path } = configPathFor(client, ctx);
+    switch (client) {
+        case "claude-code": {
+            if (ctx.onPath("claude")) {
+                return {
+                    kind: "exec",
+                    argv: [
+                        "claude",
+                        "mcp",
+                        "add",
+                        "--transport",
+                        "http",
+                        SERVER_NAME,
+                        url,
+                        "--header",
+                        `Authorization: ${bearer(ctx.token)}`,
+                        "--scope",
+                        "user",
+                    ],
+                    describe: "Claude Code, through its own `claude` command",
+                };
+            }
+            return {
+                kind: "write",
+                path,
+                entry: { type: "http", url, headers: { Authorization: bearer(ctx.token) } },
+                describe: "Claude Code (the `claude` command is not on PATH, so its config was written directly)",
+            };
+        }
+        case "codex": {
+            const envName = nonEmpty(ctx.tokenEnv) ?? TOKEN_ENV_DEFAULT;
+            if (ctx.onPath("codex")) {
+                return {
+                    kind: "exec",
+                    argv: ["codex", "mcp", "add", SERVER_NAME, "--url", url, "--bearer-token-env-var", envName],
+                    describe: "Codex, through its own `codex` command",
+                };
+            }
+            // NO TOML WRITER (NC-1): this package has zero dependencies and a
+            // hand-rolled TOML mutation of someone's `config.toml` is exactly the
+            // "overwrite what you cannot preserve" this card refuses elsewhere.
+            return {
+                kind: "print",
+                snippet: renderSnippet("codex", { url, placeholder: TOKEN_PLACEHOLDER, tokenEnv: envName }),
+                reason: `the \`codex\` command is not on PATH, and this CLI does not edit ${path} itself`,
+            };
+        }
+        case "claude-desktop": {
+            // STDIO ONLY: Claude Desktop takes a command and arguments, not a URL with
+            // headers (measured on this machine — every server in its live config is
+            // `command`/`args`), so the bridge is `mcp-remote`.
+            return {
+                kind: "write",
+                path,
+                entry: {
+                    command: "npx",
+                    args: ["-y", `mcp-remote@${MCP_REMOTE_VERSION}`, url, "--header", `Authorization: ${bearer(ctx.token)}`],
+                },
+                describe: "Claude Desktop (restart it to pick the server up)",
+            };
+        }
+        default: {
+            if (ctx.fileExists(path)) {
+                return {
+                    kind: "write",
+                    path,
+                    entry: { url, headers: { Authorization: bearer(ctx.token) } },
+                    describe: "Cursor",
+                };
+            }
+            // ASSUME-1 is unverified here, so a file that does not exist is not
+            // created: a wrong guess at the shape would be a config Cursor ignores,
+            // and a person who has never configured Cursor has nothing to compare it
+            // against. An existing file proves the location at least.
+            return {
+                kind: "print",
+                snippet: renderSnippet("cursor", { url, placeholder: TOKEN_PLACEHOLDER }),
+                reason: `${path} does not exist yet, so there is no Cursor config to add an entry to`,
+            };
+        }
+    }
+}
+/**
+ * The hand-edit snippet for a client: what a person pastes when the automated
+ * route is not available, and what `mcp print` shows.
+ *
+ * It is the SAME shape the writer produces, rendered from the same values, so the
+ * printed instructions and the automated write cannot describe different configs.
+ */
+export function renderSnippet(client, input) {
+    const { url, placeholder } = input;
+    const auth = `Bearer ${placeholder}`;
+    if (client === "codex") {
+        const envName = nonEmpty(input.tokenEnv) ?? TOKEN_ENV_DEFAULT;
+        return [
+            `# ~/.codex/config.toml (or $CODEX_HOME/config.toml)`,
+            `[mcp_servers.${SERVER_NAME}]`,
+            `url = "${url}"`,
+            `bearer_token_env_var = "${envName}"`,
+            ``,
+            `# and in the shell that starts codex:`,
+            `export ${envName}=${placeholder}`,
+        ].join("\n");
+    }
+    if (client === "claude-desktop") {
+        return [
+            `// claude_desktop_config.json`,
+            JSON.stringify({
+                mcpServers: {
+                    [SERVER_NAME]: {
+                        command: "npx",
+                        args: ["-y", `mcp-remote@${MCP_REMOTE_VERSION}`, url, "--header", `Authorization: ${auth}`],
+                    },
+                },
+            }, null, 2),
+        ].join("\n");
+    }
+    if (client === "cursor") {
+        return [
+            `// ~/.cursor/mcp.json`,
+            JSON.stringify({ mcpServers: { [SERVER_NAME]: { url, headers: { Authorization: auth } } } }, null, 2),
+        ].join("\n");
+    }
+    // claude-code: the one-liner first, because it is what most people will use,
+    // and the file shape under it for anyone who would rather edit than run.
+    return [
+        `claude mcp add --transport http ${SERVER_NAME} ${url} \\`,
+        `  --header "Authorization: ${auth}" --scope user`,
+        ``,
+        `// or, in ~/.claude.json ($CLAUDE_CONFIG_DIR/.claude.json when that is set)`,
+        JSON.stringify({ mcpServers: { [SERVER_NAME]: { type: "http", url, headers: { Authorization: auth } } } }, null, 2),
+    ].join("\n");
+}

package/dist/messages.js

@@ -0,0 +1,47 @@
+export const LOGIN_REMEDIES = {
+    expired_token: "This login code has expired. Codes last 15 minutes — run `flowsprite login` again to start a new one.",
+    access_denied: "The login was denied in the browser. If that was not you, run `flowsprite login` again and approve only a code you started yourself.",
+    no_grant: "Your Flowsprite account has no MCP access in this workspace yet. Ask a workspace owner or admin to grant you MCP access in Settings, then run `flowsprite login` again.",
+    not_member: "You are not an active member of that workspace any more. Ask an owner or admin to re-invite you, then run `flowsprite login` again.",
+    suspended: "That workspace is suspended, so no new access tokens can be issued. An owner needs to resolve the suspension in billing before a terminal can log in.",
+    revoked: "Your MCP access in that workspace has been revoked. Ask a workspace owner or admin to grant it again, then run `flowsprite login` again.",
+    ambiguous_grant: "You hold more than one live MCP grant in that workspace, so Flowsprite cannot tell which one this terminal should use. Ask an owner or admin to revoke the extra grants, then run `flowsprite login` again.",
+    rate_limited: "Too many logins have been started from this network in the last few minutes. Wait ten minutes and run `flowsprite login` again.",
+    invalid_request: "Flowsprite rejected the login request as malformed. This is a bug in this CLI version — upgrade it, and report it if a newer version does the same.",
+    invalid_argument: "Flowsprite rejected one of the values this CLI sent when starting the login. This is a bug in this CLI version — upgrade it, and report it if a newer version does the same.",
+    server_misconfigured: "That Flowsprite deployment is not configured for command-line login. Whoever operates it needs to set its MCP service secret.",
+    server_error: "Flowsprite hit an unexpected error while logging this terminal in. Try again in a minute; if it keeps happening, that is an operator problem, not something you can fix here.",
+    transport: "Could not reach that Flowsprite deployment. Check the endpoint and your network, then run `flowsprite login` again.",
+};
+/** The wire values that mean "keep polling", kept apart from the terminal ones above. */
+export const POLL_CONTINUE_KINDS = new Set(["authorization_pending", "slow_down"]);
+/**
+ * The kinds that can arrive FROM THE WIRE — a strict subset of the remedy table.
+ *
+ * ⚠️ `transport` IS NOT IN IT, and that is the point of this set existing. It is a
+ * real `LoginFailureKind` with a real remedy ("could not reach that deployment"),
+ * but it is a conclusion this CLI draws when `fetch` THROWS — never something a
+ * server says. Keying the wire lookup on the remedy table instead meant a
+ * response body of `{"error":"transport"}` was read as "unreachable", which is a
+ * lie about a deployment that plainly answered, and it points the person at their
+ * network instead of at the workspace. Anything not in this set folds to
+ * `server_error` and is never echoed: an unrecognised error string is still a
+ * server string.
+ */
+const WIRE_KINDS = new Set([
+    "expired_token",
+    "access_denied",
+    "no_grant",
+    "not_member",
+    "suspended",
+    "revoked",
+    "ambiguous_grant",
+    "rate_limited",
+    "invalid_request",
+    "invalid_argument",
+    "server_misconfigured",
+    "server_error",
+]);
+export function isLoginFailureKind(value) {
+    return typeof value === "string" && WIRE_KINDS.has(value);
+}

package/dist/output.js

@@ -0,0 +1,21 @@
+import { redact } from "./redact.js";
+/**
+ * `sinks` is injected so a test can record every line without a process.
+ * The bin wires `console.log` / `console.error`.
+ */
+export function createWriter(sinks) {
+    return {
+        out: (line) => sinks.out(redact(line)),
+        err: (line) => sinks.err(redact(line)),
+    };
+}
+/** A writer that records, for tests and for the doctor's dry runs. */
+export function createRecordingWriter() {
+    const lines = [];
+    const errors = [];
+    const w = createWriter({
+        out: (line) => lines.push(line),
+        err: (line) => errors.push(line),
+    });
+    return { ...w, lines, errors };
+}

package/dist/redact.js

@@ -0,0 +1,47 @@
+/**
+ * Rewrite every Flowsprite bearer token in a string to a stub.
+ *
+ * NO IMPORTABLE REDACTOR EXISTS IN THIS REPO (measured at f301c49: `fp_user_`
+ * appears in lib/ and scripts/ only as comments and a type guard), so this is
+ * the CLI's own, re-stated rather than shared.
+ *
+ * THE TOKEN GRAMMAR IS TAKEN FROM THE MINTER, not guessed: `generateRawToken`
+ * in `convex/lib/mcpCrypto.ts` emits `fp_live_` or `fp_user_` followed by 32
+ * characters drawn from `[A-Za-z0-9-_]`. The suffix alphabet CONTAINS `_`, so
+ * the match is greedy over that class — stopping at the first underscore would
+ * leave most of the secret on the screen.
+ *
+ * THE SET THIS COVERS IS EXACTLY `fp_user_` AND `fp_live_`, and nothing else —
+ * stated so the next reader does not assume it is a general secret scrubber.
+ * Those are the only two prefixes `generateRawToken` can emit and the only
+ * credentials this CLI ever holds. The OTHER value worth never printing, the
+ * device code, is not covered here and does not need to be: it is 64 hex
+ * characters with no marker to match on, and it is kept off the screen BY
+ * CONSTRUCTION instead — `cli/src/login.ts` prints `user_code` and
+ * `verification_uri_complete` and never passes `device_code` to the writer, which
+ * the AC3 acceptance oracle pins (`printedTheDeviceCode: false`). A setup-link
+ * token is the same shape and the same story, except that one is DELIBERATELY
+ * shown: it is the thing the person has to open.
+ *
+ * Applied by the shared writer (`cli/src/output.ts`), so the redaction is a
+ * property of the ONE place lines leave this process, not of each caller
+ * remembering. A caller that bypassed the writer would bypass this.
+ */
+const TOKEN = /fp_(?:user|live)_[A-Za-z0-9_-]+/g;
+/** How many trailing characters survive, so a person can tell two tokens apart. */
+const KEEP_LAST = 4;
+export function redact(text) {
+    return text.replace(TOKEN, (match) => {
+        // `fp_user_` / `fp_live_` — a fixed 8 characters, so this is a slice, not a
+        // search: the prefix is the part the grammar above already pinned.
+        const prefix = match.slice(0, "fp_user_".length);
+        const suffix = match.slice("fp_user_".length);
+        // A suffix at or under the keep length would be echoed whole. It cannot be a
+        // real token (the minter always emits 32), and truncating to nothing would
+        // be indistinguishable from an empty value — so the stub says "..." and
+        // keeps nothing.
+        if (suffix.length <= KEEP_LAST)
+            return `${prefix}...`;
+        return `${prefix}...${suffix.slice(-KEEP_LAST)}`;
+    });
+}