flowsprite 0.1.0

package/dist/cli.js

@@ -0,0 +1,974 @@
+import { homedir } from "node:os";
+import { parseArgs } from "node:util";
+import { credentialsPath, deleteCredential, readCredentials, resolveToken, writeCredential, } from "./credentials.js";
+import { formatDoctor, MIN_NODE_MAJOR, nodeMajor } from "./doctor.js";
+import { parseEndpoint } from "./endpoint.js";
+import { deviceCodeLogin } from "./login.js";
+import { createMcpClient, toolJson } from "./mcpClient.js";
+import { jsonConfigHasServer, McpConfigError, SERVER_NAME, tomlConfigHasServer, upsertJsonConfig, } from "./mcpConfig.js";
+import { CLIENTS, commandFor, configPathFor, isClientId, planInstall, renderSnippet, TOKEN_PLACEHOLDER, } from "./mcpInstall.js";
+import { redact } from "./redact.js";
+import { asArray, asObject, planBindArgs, planNextStep, rungConnectionIds, runLinkStep, } from "./setup.js";
+import { renderStatus } from "./status.js";
+import { USAGE } from "./usage.js";
+/**
+ * The argv router. EXIT CODES ARE THE CONTRACT: 0 success, 1 the command ran and
+ * the answer was bad, 2 the command line itself was wrong (unknown command,
+ * unknown flag, missing required flag). A script can tell "you asked wrong" from
+ * "Flowsprite said no" without parsing prose.
+ *
+ * EVERY EFFECT IS INJECTED (DM3): fetch, sleep, the clock, the environment, the
+ * writer, the PATH probe and the optional prompt. `bin.ts` is the only file that
+ * names a real one, so every command below is drivable in a test without a
+ * network, a home directory or a TTY.
+ */
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+export const EXIT_USAGE = 2;
+const OPTIONS = {
+    endpoint: { type: "string" },
+    json: { type: "boolean" },
+    token: { type: "string" },
+    save: { type: "boolean" },
+    "no-open": { type: "boolean" },
+    sandbox: { type: "boolean" },
+    "my-domain": { type: "string" },
+    connection: { type: "string" },
+    installation: { type: "string" },
+    repo: { type: "string" },
+    create: { type: "string" },
+    client: { type: "string" },
+    print: { type: "boolean" },
+    force: { type: "boolean" },
+    reveal: { type: "boolean" },
+    "token-env": { type: "string" },
+    help: { type: "boolean", short: "h" },
+    version: { type: "boolean", short: "v" },
+};
+const COMMANDS = new Set(["setup", "login", "logout", "status", "connect", "bind", "sync", "doctor", "mcp"]);
+export async function main(argv, deps) {
+    let values;
+    let positionals;
+    try {
+        // `strict: true` is what makes an unknown flag an error at all, and it
+        // covers SINGLE-dash too: measured on node 22, `-x` throws
+        // ERR_PARSE_ARGS_UNKNOWN_OPTION exactly as `--nope` does, and a clustered
+        // `-xyz` reports the first unknown short. There is no second check to write.
+        const parsed = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true });
+        values = parsed.values;
+        positionals = parsed.positionals;
+    }
+    catch (err) {
+        return usageError(deps.writer, err instanceof Error ? err.message : "could not parse the command line");
+    }
+    if (values.help === true) {
+        deps.writer.out(USAGE);
+        return EXIT_OK;
+    }
+    if (values.version === true) {
+        deps.writer.out(deps.version);
+        return EXIT_OK;
+    }
+    const command = positionals[0] ?? "setup";
+    if (!COMMANDS.has(command)) {
+        return usageError(deps.writer, `Unknown command '${command}'.`);
+    }
+    const endpoint = parseEndpoint({
+        flag: typeof values.endpoint === "string" ? values.endpoint : undefined,
+        env: deps.env.FLOWSPRITE_ENDPOINT,
+    });
+    if (!endpoint.ok)
+        return usageError(deps.writer, endpoint.message);
+    const origin = endpoint.origin;
+    switch (command) {
+        case "login":
+            return await cmdLogin(deps, origin, values);
+        case "logout":
+            return cmdLogout(deps, origin);
+        case "doctor":
+            return await cmdDoctor(deps, origin, values);
+        case "status":
+            return await cmdStatus(deps, origin, values);
+        case "connect":
+            return await cmdConnect(deps, origin, values, positionals[1]);
+        case "mcp":
+            return await cmdMcp(deps, origin, values, positionals[1]);
+        case "bind":
+            return await cmdBind(deps, origin, values);
+        case "sync":
+            return await cmdSync(deps, origin, values);
+        default:
+            return await cmdSetup(deps, origin, values);
+    }
+}
+function usageError(writer, message) {
+    writer.err(message);
+    writer.err("");
+    writer.err(USAGE);
+    return EXIT_USAGE;
+}
+// ------------------------------------------------------------------ the client
+/**
+ * Resolve the token for this origin and build a client, or explain what is
+ * missing. `--token` beats `FLOWSPRITE_TOKEN` beats the stored credential —
+ * precedence lives in `resolveToken`, this only supplies the three candidates.
+ */
+function clientFor(deps, origin, values) {
+    const stored = readCredentials(deps.env, deps.home)[origin];
+    const token = resolveToken({
+        flag: typeof values.token === "string" ? values.token : undefined,
+        env: deps.env.FLOWSPRITE_TOKEN,
+        stored: stored?.token,
+    });
+    if (token === null) {
+        deps.writer.err(`Not logged in to ${origin}. Run \`flowsprite login\`, or pass --token.`);
+        return { ok: false };
+    }
+    return {
+        ok: true,
+        client: createMcpClient({ origin, token: token.token, fetch: deps.fetch, version: deps.version }),
+    };
+}
+// ------------------------------------------------------------------- commands
+async function cmdLogin(deps, origin, values) {
+    // A token handed in on the command line or the environment SKIPS the device
+    // loop entirely — there is nothing to approve. It is not stored unless --save
+    // is given, so a one-off token in a CI job leaves nothing behind.
+    const direct = typeof values.token === "string" && values.token.length > 0
+        ? values.token
+        : typeof deps.env.FLOWSPRITE_TOKEN === "string" && deps.env.FLOWSPRITE_TOKEN.length > 0
+            ? deps.env.FLOWSPRITE_TOKEN
+            : null;
+    if (direct !== null) {
+        if (values.save === true) {
+            writeCredential(deps.env, origin, { token: direct, orgId: "", userId: "", mcpEndpoint: `${origin}/api/mcp`, savedAt: deps.now() }, deps.home);
+            deps.writer.out(`Saved a token for ${origin}.`);
+        }
+        else {
+            deps.writer.out(`Using the token you supplied for ${origin}. Pass --save to store it.`);
+        }
+        return EXIT_OK;
+    }
+    const result = await deviceCodeLogin({
+        origin,
+        fetch: deps.fetch,
+        sleep: deps.sleep,
+        writer: deps.writer,
+        version: deps.version,
+        ...(values["no-open"] === true || deps.openUrl === undefined ? {} : { openUrl: deps.openUrl }),
+    });
+    if (!result.ok) {
+        deps.writer.err(result.message);
+        return EXIT_FAILED;
+    }
+    const cred = {
+        token: result.token,
+        orgId: result.orgId,
+        userId: result.userId,
+        mcpEndpoint: result.mcpEndpoint,
+        savedAt: deps.now(),
+    };
+    // The token is NOT in this sentence, and the writer would redact it anyway.
+    const who = `Logged in to ${origin} as ${result.userId} in workspace ${result.orgId}`;
+    try {
+        writeCredential(deps.env, origin, cred, deps.home);
+    }
+    catch (err) {
+        // THE LOGIN ALREADY SUCCEEDED AND THE DEVICE ROW IS ALREADY CONSUMED, so a
+        // failed write is not "the login failed": the token was issued, it exists,
+        // and this process is the only thing that will ever hold it. Saying so —
+        // and saying how to use it for this session — is the difference between one
+        // lost token and a person logging in again and again. A second login mints a
+        // SECOND token on the same grant, which is how a workspace ends up with
+        // several live grants and every later login answers `ambiguous_grant`.
+        //
+        // The token itself is never printed (the writer redacts, and it is not in
+        // any of these strings). `err.message` is not printed either: it is a node
+        // string about a path, and the path is already named here.
+        deps.writer.out(who);
+        deps.writer.err(`Your token was issued, but it could not be saved to ${credentialsPath(deps.env, deps.home)} ` +
+            `(${err.code ?? "write failed"}). ` +
+            "Fix that path, or set FLOWSPRITE_TOKEN / pass --token to use this session's token without storing it.");
+        return EXIT_FAILED;
+    }
+    deps.writer.out(who);
+    return EXIT_OK;
+}
+function cmdLogout(deps, origin) {
+    const removed = deleteCredential(deps.env, origin, deps.home);
+    deps.writer.out(removed ? `Logged out of ${origin}.` : `There was no stored credential for ${origin}.`);
+    return EXIT_OK;
+}
+async function cmdDoctor(deps, origin, values) {
+    const stored = readCredentials(deps.env, deps.home)[origin];
+    let reachable = false;
+    let detail = "no credential, so reachability was not tested";
+    const built = clientForQuiet(deps, origin, values, stored?.token);
+    if (built !== null) {
+        const probe = await built.initialize();
+        reachable = probe.ok;
+        // `initialize` is the reachability probe (DM2). An `unauthorized` answer
+        // still proves the endpoint is THERE — it is reported as its own line rather
+        // than folded into "unreachable", which would send someone to check DNS.
+        detail = probe.ok ? "reachable" : `${probe.kind}: ${probe.message}`;
+    }
+    const report = {
+        nodeVersion: deps.nodeVersion,
+        nodeOk: nodeMajor(deps.nodeVersion) >= MIN_NODE_MAJOR,
+        endpoint: origin,
+        endpointReachable: reachable,
+        endpointDetail: detail,
+        hasCredential: stored !== undefined,
+        credentialsPath: credentialsPath(deps.env, deps.home),
+        sfOnPath: deps.isOnPath("sf"),
+        ghOnPath: deps.isOnPath("gh"),
+    };
+    if (values.json === true) {
+        deps.writer.out(JSON.stringify(report, null, 2));
+    }
+    else {
+        for (const line of formatDoctor(report))
+            deps.writer.out(line);
+    }
+    return report.nodeOk ? EXIT_OK : EXIT_FAILED;
+}
+/** Like `clientFor` but silent and optional — doctor reports absence, it does not refuse. */
+function clientForQuiet(deps, origin, values, storedToken) {
+    const token = resolveToken({
+        flag: typeof values.token === "string" ? values.token : undefined,
+        env: deps.env.FLOWSPRITE_TOKEN,
+        stored: storedToken,
+    });
+    if (token === null)
+        return null;
+    return createMcpClient({ origin, token: token.token, fetch: deps.fetch, version: deps.version });
+}
+async function fetchStatus(deps, client) {
+    const result = await client.callTool("setup_status", {});
+    if (!result.ok) {
+        deps.writer.err(result.message);
+        return { ok: false };
+    }
+    return { ok: true, payload: toolJson(result) };
+}
+async function cmdStatus(deps, origin, values) {
+    const built = clientFor(deps, origin, values);
+    if (!built.ok)
+        return EXIT_FAILED;
+    const status = await fetchStatus(deps, built.client);
+    if (!status.ok)
+        return EXIT_FAILED;
+    if (values.json === true) {
+        // The payload, byte for byte as the tool sent it — a machine consumer must
+        // never be reading this CLI's idea of the shape.
+        deps.writer.out(JSON.stringify(status.payload, null, 2));
+    }
+    else {
+        for (const line of renderStatus(status.payload))
+            deps.writer.out(line);
+    }
+    return EXIT_OK;
+}
+function setupDeps(deps, client) {
+    return { client, writer: deps.writer, sleep: deps.sleep, now: deps.now };
+}
+async function cmdConnect(deps, origin, values, which) {
+    if (which !== "salesforce" && which !== "github") {
+        return usageError(deps.writer, "connect takes 'salesforce' or 'github'.");
+    }
+    const built = clientFor(deps, origin, values);
+    if (!built.ok)
+        return EXIT_FAILED;
+    const tool = which === "salesforce" ? "setup_connect_salesforce" : "setup_connect_github";
+    const stepKind = which === "salesforce" ? "connect_salesforce" : "connect_github";
+    // ponytail: both alternative doors are absent here, and both plug in at THIS
+    // call, as a branch chosen before the link is minted — not as a change to the
+    // link step itself. Salesforce: the `sf`-CLI handoff (card B4, Blocked), which
+    // would reuse a `sf org login` session instead of a browser link. GitHub: the
+    // gh-token door (card A3, blocked), which would use a token the person already
+    // holds instead of an app install.
+    const args = which === "salesforce"
+        ? {
+            ...(values.sandbox === true ? { env: "sandbox" } : {}),
+            ...(typeof values["my-domain"] === "string" ? { myDomain: values["my-domain"] } : {}),
+        }
+        : {};
+    const outcome = await runLinkStep(setupDeps(deps, built.client), tool, args, stepKind);
+    return reportLinkOutcome(deps.writer, outcome);
+}
+function reportLinkOutcome(writer, outcome) {
+    switch (outcome.kind) {
+        case "done":
+            writer.out("Done.");
+            return EXIT_OK;
+        case "expired":
+            writer.err("That setup link expired before it was used. Run the command again for a fresh one.");
+            return EXIT_FAILED;
+        case "timeout":
+            writer.err("Gave up waiting after 10 minutes. The link may still work — finish it in the browser, then run `flowsprite status`.");
+            return EXIT_FAILED;
+        default:
+            writer.err(outcome.message);
+            return EXIT_FAILED;
+    }
+}
+/**
+ * What the CURRENT rung of the server's ladder is about, when a rung is being
+ * driven by `setup` rather than by a bare `bind` / `sync`.
+ *
+ * It exists because the rungs are LIST-WIDE (see `rungConnectionIds`): "bind a
+ * repo" means "some connection has none", not "this connection has none". An
+ * explicit `--connection` naming a connection the rung is NOT about would
+ * re-do work on the wrong row and leave the rung exactly where it was.
+ */
+const CONNECTION = { singular: "Salesforce connection", plural: "Salesforce connections", flag: "--connection" };
+const INSTALLATION = { singular: "GitHub installation", plural: "GitHub installations", flag: "--installation" };
+const REPOSITORY = { singular: "repository", plural: "repositories", flag: "--repo" };
+/**
+ * Why an explicit `--connection` is refused under a rung.
+ *
+ * ⚠️ THE REASON IS BRANCHED, BECAUSE "NOT IN THE RUNG'S SET" HAS TWO CAUSES AND
+ * ONLY ONE OF THEM IS "you already did this one". An id that is not a connection
+ * in this workspace at all — a typo, a stale id copied from another workspace —
+ * is also not in the set, and telling that person their connection "is already
+ * bound" is a false statement about a row that does not exist, pointing them at
+ * the wrong fix. Membership in `connections` is what distinguishes the two, so it
+ * is read rather than assumed.
+ *
+ * ONE HOME for both rungs: `bind` and `sync` had the same sentence with the same
+ * defect, differing only in two words. Two copies is how one of them gets fixed.
+ */
+function outOfRungRefusal(flagValue, rung) {
+    const known = asArray(asObject(rung.status)?.connections).some((c) => String(c.id ?? "") === flagValue);
+    const binding = rung.kind === "bind_repo";
+    const reason = known
+        ? `--connection ${flagValue} is already ${binding ? "bound" : "synced"}`
+        : `--connection ${flagValue} is not a connection in this workspace`;
+    return (`${reason}, and the workspace still has ${rung.connectionIds.length} connection(s) that ` +
+        `${binding ? "are not bound" : "have not synced"}: ${rung.connectionIds.join(", ")}. ` +
+        `Re-run ${binding ? "bind" : "sync"} for one of those, or drop --connection and let setup ask.`);
+}
+async function cmdBind(deps, origin, values) {
+    const built = clientFor(deps, origin, values);
+    if (!built.ok)
+        return EXIT_FAILED;
+    return await runBind(deps, values, built.client, null);
+}
+async function runBind(deps, values, client, rung) {
+    const filled = await fillBindInput(deps, client, values, rung);
+    if (filled === null)
+        return EXIT_USAGE;
+    const plan = planBindArgs(filled);
+    if (!plan.ok) {
+        // A ONE-LINE REMEDY, not the whole usage text. By the time we are here the
+        // command line parsed fine and the workspace was read; dumping 39 lines of
+        // usage buries the sentence that says what to do.
+        deps.writer.err(plan.message);
+        return EXIT_USAGE;
+    }
+    const result = await client.callTool("setup_bind_repo", plan.args);
+    if (!result.ok) {
+        deps.writer.err(result.message);
+        return EXIT_FAILED;
+    }
+    if (values.json === true) {
+        deps.writer.out(JSON.stringify(toolJson(result), null, 2));
+    }
+    else {
+        deps.writer.out("Bound.");
+        for (const line of textOf(result.content))
+            deps.writer.out(line);
+    }
+    return EXIT_OK;
+}
+/**
+ * Fill in `--connection`, `--installation` and the repository when the workspace
+ * leaves no choice, and ask when it does.
+ *
+ * ONE candidate is not a choice, so it is taken silently. SEVERAL is a decision
+ * that belongs to the person: with a prompt available it is asked, and without
+ * one (a pipe, a CI job) the candidates are LISTED ON STDERR and the command
+ * refuses — never guessed, because binding SUPERSEDES whatever that connection
+ * was bound to before and switches off its data export.
+ *
+ * THE REPOSITORY IS PICKED THE SAME WAY, and that is what makes a bare
+ * `flowsprite setup` able to pass this rung at all: `setup_status` already
+ * carries each installation's repositories (FLO-496 AC6), so the ladder does not
+ * have to ask the person for a flag it never told them they needed. `--create`
+ * stays the non-interactive alternative for a workspace whose repos Flowsprite
+ * has not listed.
+ */
+async function fillBindInput(deps, client, values, rung) {
+    const input = {
+        connection: typeof values.connection === "string" ? values.connection : undefined,
+        installation: typeof values.installation === "string" ? values.installation : undefined,
+        repo: typeof values.repo === "string" ? values.repo : undefined,
+        create: typeof values.create === "string" ? values.create : undefined,
+    };
+    const payload = rung !== null ? rung.status : await (async () => {
+        const status = await fetchStatus(deps, client);
+        return status.ok ? status.payload : undefined;
+    })();
+    if (payload === undefined)
+        return null;
+    const root = asObject(payload);
+    const connections = asArray(root?.connections);
+    const installations = asArray(root?.installations);
+    // ---- which connection ----------------------------------------------------
+    // Under a rung, the CANDIDATES are the connections that rung is unsatisfied
+    // about — not every connection — and an explicit --connection outside that set
+    // is refused rather than silently re-bound (it would leave the rung unmoved,
+    // which is the unbounded-loop defect one level down).
+    const eligible = rung !== null
+        ? connections.filter((c) => rung.connectionIds.includes(String(c.id)))
+        : (() => {
+            const unbound = connections.filter((c) => c.hasBinding !== true);
+            return unbound.length > 0 ? unbound : connections;
+        })();
+    if (typeof input.connection === "string") {
+        if (rung !== null && !rung.connectionIds.includes(input.connection)) {
+            deps.writer.err(outOfRungRefusal(input.connection, rung));
+            return null;
+        }
+    }
+    else {
+        const picked = await pickOne(deps, CONNECTION, eligible.map((c) => [
+            String(c.id ?? ""),
+            `${String(c.displayName ?? "?")} [${String(c.envType ?? "?")}]`,
+        ]));
+        if (picked === null)
+            return null;
+        input.connection = picked;
+    }
+    // ---- which GitHub installation ------------------------------------------
+    if (typeof input.installation !== "string") {
+        const picked = await pickOne(deps, INSTALLATION, installations.map((i) => [
+            String(i.installationId ?? ""),
+            `@${String(i.accountLogin ?? "?")} [${String(i.accountType ?? "?")}]`,
+        ]));
+        if (picked === null)
+            return null;
+        input.installation = picked;
+    }
+    // ---- which repository ----------------------------------------------------
+    if (typeof input.repo !== "string" && typeof input.create !== "string") {
+        const chosen = installations.find((i) => String(i.installationId ?? "") === String(input.installation));
+        const repos = asArray(chosen?.repos);
+        if (repos.length === 0) {
+            // An EMPTY list means Flowsprite has not listed that installation's
+            // repositories, not that the installation has none — the distinction the
+            // setup_bind_repo description draws, and the remedy differs.
+            deps.writer.err(`Flowsprite has not listed any repositories for installation ${String(input.installation)}. ` +
+                "Refresh Sync Accounts in the app, then try again — or pass --create <name> to make a new private one.");
+            return null;
+        }
+        const picked = await pickOne(deps, REPOSITORY, repos.map((r) => [
+            String(r.fullName ?? ""),
+            `${r.private === true ? "private" : "PUBLIC — will be refused"}, default branch ${String(r.defaultBranch ?? "?")}`,
+        ]));
+        if (picked === null)
+            return null;
+        input.repo = picked;
+    }
+    return input;
+}
+/**
+ * One of a list, or nothing.
+ *
+ * The listing goes to STDERR, not stdout: it is diagnostic, and `--json` callers
+ * must be able to parse stdout whatever route the command took.
+ */
+async function pickOne(deps, noun, rows) {
+    const options = rows.filter(([id]) => id.length > 0);
+    if (options.length === 0) {
+        deps.writer.err(`This workspace has no ${noun.singular} to use here. Run \`flowsprite status\` to see what it has.`);
+        return null;
+    }
+    if (options.length === 1)
+        return options[0][0];
+    deps.writer.err(`Several ${noun.plural}:`);
+    options.forEach(([id, desc], n) => deps.writer.err(`  ${n + 1}) ${id}  ${desc}`));
+    if (deps.ask === undefined) {
+        deps.writer.err(`Re-run with the one you want, for example ${noun.flag} ${options[0][0]}.`);
+        return null;
+    }
+    const answer = (await deps.ask(`Which ${noun.singular}? [1-${options.length}] `)).trim();
+    const n = Number(answer);
+    if (!Number.isInteger(n) || n < 1 || n > options.length) {
+        deps.writer.err(`'${answer}' is not one of 1-${options.length}.`);
+        return null;
+    }
+    return options[n - 1][0];
+}
+async function cmdSync(deps, origin, values) {
+    const built = clientFor(deps, origin, values);
+    if (!built.ok)
+        return EXIT_FAILED;
+    return await runSync(deps, values, built.client, null);
+}
+async function runSync(deps, values, client, rung) {
+    let connection = typeof values.connection === "string" ? values.connection : "";
+    if (rung !== null && connection.length > 0 && !rung.connectionIds.includes(connection)) {
+        deps.writer.err(outOfRungRefusal(connection, rung));
+        return EXIT_USAGE;
+    }
+    if (connection.length === 0) {
+        let pool;
+        if (rung !== null) {
+            const ids = rung.connectionIds;
+            pool = asArray(asObject(rung.status)?.connections).filter((c) => ids.includes(String(c.id)));
+        }
+        else {
+            const status = await fetchStatus(deps, client);
+            if (!status.ok)
+                return EXIT_FAILED;
+            const all = asArray(asObject(status.payload)?.connections);
+            // The SAME narrowing `fillBindInput` does for the bind rung: a connection
+            // that has already synced is not a candidate for "start the first sync",
+            // and offering it is how `setup` re-triggers a sync that changes nothing.
+            const unsynced = all.filter((c) => c.hasSyncJob !== true);
+            pool = unsynced.length > 0 ? unsynced : all;
+        }
+        const picked = await pickOne(deps, CONNECTION, pool.map((c) => [
+            String(c.id ?? ""),
+            `${String(c.displayName ?? "?")} [${String(c.envType ?? "?")}]`,
+        ]));
+        if (picked === null)
+            return EXIT_USAGE;
+        connection = picked;
+    }
+    const started = await client.callTool("sfdc_trigger_sync", { sandboxId: connection });
+    if (!started.ok) {
+        deps.writer.err(started.message);
+        return EXIT_FAILED;
+    }
+    // Under --json the ONLY thing on stdout is the JSON below: the trigger's prose
+    // would make the stream unparseable for the caller who asked for machine output.
+    if (values.json !== true) {
+        for (const line of textOf(started.content))
+            deps.writer.out(line);
+    }
+    const logs = await client.callTool("sfdc_sync_logs", { sandboxId: connection });
+    if (!logs.ok) {
+        deps.writer.err(logs.message);
+        return EXIT_FAILED;
+    }
+    if (values.json === true) {
+        deps.writer.out(JSON.stringify(toolJson(logs), null, 2));
+    }
+    else {
+        for (const line of textOf(logs.content))
+            deps.writer.out(line);
+    }
+    return EXIT_OK;
+}
+/**
+ * A HARD CEILING on how many rungs one `setup` may take.
+ *
+ * The identity check below is the precise diagnosis — "that tool said OK and the
+ * ladder did not move" — but it is not a BOUND on its own: one volatile field in
+ * the payload (a `pendingLinks` expiry ticking down) makes two reads differ
+ * without the ladder having moved, and the loop runs again. This is the term that
+ * makes termination structural. The ladder has four rungs and a workspace can
+ * legitimately need several passes of the list-wide ones, so this is generous;
+ * it is a backstop, not a budget.
+ */
+const MAX_SETUP_RUNGS = 24;
+async function cmdSetup(deps, origin, values) {
+    // Doctor-lite: the two things that make every later step fail confusingly.
+    if (nodeMajor(deps.nodeVersion) < MIN_NODE_MAJOR) {
+        deps.writer.err(`flowsprite needs node ${MIN_NODE_MAJOR} or newer; this is ${deps.nodeVersion}.`);
+        return EXIT_FAILED;
+    }
+    if (readCredentials(deps.env, deps.home)[origin] === undefined && resolveToken({
+        flag: typeof values.token === "string" ? values.token : undefined,
+        env: deps.env.FLOWSPRITE_TOKEN,
+    }) === null) {
+        deps.writer.out(`Not logged in to ${origin} yet.`);
+        const rc = await cmdLogin(deps, origin, values);
+        if (rc !== EXIT_OK)
+            return rc;
+    }
+    const built = clientFor(deps, origin, values);
+    if (!built.ok)
+        return EXIT_FAILED;
+    const sdeps = setupDeps(deps, built.client);
+    /**
+     * THE LOOP MUST PROVE THE LADDER MOVED, and this is why.
+     *
+     * The ladder is the SERVER'S and its rungs are LIST-WIDE
+     * (`connections.some(...)` in `nextSetupAction`), while every action this CLI
+     * takes is per-connection. So a rung CAN succeed and leave the next answer
+     * identical — and at fd0f434 that produced 200 consecutive `setup_bind_repo`
+     * calls against the same connection, each superseding the binding the last one
+     * made and clearing that connection's data-export consent. (The comment that
+     * used to sit here, "every rung that succeeds changes the answer", was simply
+     * false; it is deleted rather than softened.)
+     *
+     * Two terms, and they answer different questions: the identity check says WHICH
+     * tool stopped making progress, and `MAX_SETUP_RUNGS` guarantees termination
+     * even when a volatile field makes two payloads differ.
+     */
+    let previousStatus = null;
+    let previousTool = null;
+    for (let rungs = 0;; rungs++) {
+        const status = await fetchStatus(deps, built.client);
+        if (!status.ok)
+            return EXIT_FAILED;
+        const serialized = JSON.stringify(status.payload) ?? "";
+        if (previousTool !== null && serialized === previousStatus) {
+            deps.writer.err(`\`${previousTool}\` reported success, but this workspace's setup status did not change. ` +
+                "Stopping rather than repeating it: the setup steps are list-wide, so a step that does not " +
+                "move the checklist would repeat forever. Run `flowsprite status` to see what is left.");
+            return EXIT_FAILED;
+        }
+        if (rungs >= MAX_SETUP_RUNGS) {
+            deps.writer.err(`Stopped after ${MAX_SETUP_RUNGS} setup steps without finishing. Run \`flowsprite status\` to see what is left.`);
+            return EXIT_FAILED;
+        }
+        previousStatus = serialized;
+        const step = planNextStep(status.payload);
+        switch (step.kind) {
+            case "done":
+                deps.writer.out("Setup is complete.");
+                for (const line of renderStatus(status.payload))
+                    deps.writer.out(line);
+                return EXIT_OK;
+            case "web_only":
+                deps.writer.out(step.text);
+                return EXIT_OK;
+            case "connect_salesforce":
+            case "connect_github": {
+                deps.writer.out(step.text);
+                const tool = step.kind === "connect_salesforce" ? "setup_connect_salesforce" : "setup_connect_github";
+                const args = step.kind === "connect_salesforce" && values.sandbox === true ? { env: "sandbox" } : {};
+                const rc = reportLinkOutcome(deps.writer, await runLinkStep(sdeps, tool, args, step.kind));
+                if (rc !== EXIT_OK)
+                    return rc;
+                previousTool = tool;
+                break;
+            }
+            default: {
+                // The two per-connection rungs. `rungConnectionIds` derives WHICH
+                // connections the list-wide rung is unsatisfied about; an empty answer
+                // means the payload does not explain its own rung, which is a stop, not
+                // a licence to act on an arbitrary connection.
+                const connectionIds = rungConnectionIds(status.payload, step.kind);
+                if (connectionIds.length === 0) {
+                    deps.writer.err(`Flowsprite says the next step is ${step.kind === "bind_repo" ? "binding a repository" : "the first sync"}, ` +
+                        "but its status does not say which connection needs it. Run `flowsprite status`.");
+                    return EXIT_FAILED;
+                }
+                deps.writer.out(step.text);
+                const rung = { kind: step.kind, connectionIds, status: status.payload };
+                const rc = step.kind === "bind_repo"
+                    ? await runBind(deps, values, built.client, rung)
+                    : await runSync(deps, values, built.client, rung);
+                if (rc !== EXIT_OK)
+                    return rc;
+                previousTool = step.kind === "bind_repo" ? "setup_bind_repo" : "sfdc_trigger_sync";
+                break;
+            }
+        }
+    }
+}
+/** The human-readable text an MCP tool result carries, one line per content entry. */
+function textOf(content) {
+    return content.flatMap((c) => (typeof c.text === "string" ? [c.text] : []));
+}
+// ------------------------------------------------------------- mcp install/print
+const MCP_CLIENT = { singular: "AI client", plural: "AI clients", flag: "--client" };
+/**
+ * `mcp install` and `mcp print`: point an AI client at this workspace's MCP
+ * endpoint, or show the person what to paste.
+ *
+ * THE TOKEN RULE, in one place because it is the reason this command exists
+ * (AC3 / DM3): the stored bearer reaches a config file or a client's own
+ * registration command, and reaches STDOUT only through `mcp print --reveal` at a
+ * terminal. Every other route — the success lines, the refusals, a failing
+ * command's stderr, an install-time fallback snippet — carries the placeholder or
+ * nothing at all, and no line ever carries an argv.
+ */
+async function cmdMcp(deps, origin, values, sub) {
+    if (sub !== "install" && sub !== "print") {
+        return usageError(deps.writer, "mcp takes 'install' or 'print'.");
+    }
+    const flag = typeof values.client === "string" ? values.client : undefined;
+    if (flag !== undefined && !isClientId(flag)) {
+        // An unknown --client is a COMMAND-LINE error (exit 2), not a refusal: the
+        // list of clients is closed and the usage text names it.
+        return usageError(deps.writer, `Unknown --client '${flag}'. Known clients: ${CLIENTS.join(", ")}.`);
+    }
+    return sub === "print"
+        ? mcpPrint(deps, origin, values, flag)
+        : await mcpInstall(deps, origin, values, flag);
+}
+/** The facts every client path is derived from — `home`, `platform`, `env`, and nothing else. */
+function pathContext(deps) {
+    return {
+        home: deps.home ?? homedir(),
+        platform: deps.platform ?? process.platform,
+        env: deps.env,
+    };
+}
+function mcpPrint(deps, origin, values, flag) {
+    const stored = readCredentials(deps.env, deps.home)[origin];
+    const mcpEndpoint = stored?.mcpEndpoint ?? `${origin}/api/mcp`;
+    const tokenEnv = typeof values["token-env"] === "string" ? values["token-env"] : undefined;
+    let placeholder = TOKEN_PLACEHOLDER;
+    if (values.reveal === true) {
+        if (deps.isTTY !== true) {
+            // A SECRET GOES TO A TERMINAL OR NOWHERE. Through a pipe the destination is
+            // a file, a log or another process's buffer, and none of those is something
+            // the person watching can decide to clear.
+            deps.writer.err("--reveal prints the real token, so it only runs at a terminal and stdout here is not one. " +
+                "Re-run it at a terminal, or drop --reveal for a snippet with a placeholder.");
+            return EXIT_USAGE;
+        }
+        const token = resolveToken({
+            flag: typeof values.token === "string" ? values.token : undefined,
+            env: deps.env.FLOWSPRITE_TOKEN,
+            stored: stored?.token,
+        });
+        if (token === null) {
+            deps.writer.err(`Not logged in to ${origin}, so there is no token to reveal. Run \`flowsprite login\`.`);
+            return EXIT_FAILED;
+        }
+        placeholder = token.token;
+    }
+    const clients = flag !== undefined ? [flag] : [...CLIENTS];
+    const ctxLite = pathContext(deps);
+    const rows = clients.map((client) => {
+        const cfg = configPathFor(client, ctxLite);
+        const command = commandFor(client);
+        return {
+            client,
+            // What `mcp install` WOULD do for this client, on this machine, right now —
+            // derived from the same planner, so `print --json` cannot describe a route
+            // `install` does not take.
+            kind: planInstall(client, {
+                ...ctxLite,
+                origin,
+                mcpEndpoint,
+                token: TOKEN_PLACEHOLDER,
+                tokenEnv,
+                onPath: deps.isOnPath,
+                fileExists: deps.fileExists,
+            }).kind,
+            path: cfg.path,
+            ...(command === null ? {} : { command }),
+            snippet: renderSnippet(client, { url: mcpEndpoint, placeholder, tokenEnv }),
+        };
+    });
+    if (values.json === true) {
+        // ONE client asked for, one object; no client asked for, the array. Nothing
+        // else on stdout either way — that is what makes this parseable.
+        deps.writer.out(JSON.stringify(flag !== undefined ? rows[0] : rows, null, 2));
+        return EXIT_OK;
+    }
+    rows.forEach((row, n) => {
+        if (n > 0)
+            deps.writer.out("");
+        deps.writer.out(`# ${row.client}`);
+        deps.writer.out(row.snippet);
+    });
+    return EXIT_OK;
+}
+async function mcpInstall(deps, origin, values, flag) {
+    const stored = readCredentials(deps.env, deps.home)[origin];
+    const resolved = resolveToken({
+        flag: typeof values.token === "string" ? values.token : undefined,
+        env: deps.env.FLOWSPRITE_TOKEN,
+        stored: stored?.token,
+    });
+    if (resolved === null) {
+        deps.writer.err(`Not logged in to ${origin}, so there is no token to install. Run \`flowsprite login\` first, ` +
+            "or run `flowsprite mcp print` for a snippet to fill in by hand.");
+        return EXIT_FAILED;
+    }
+    const ctxLite = pathContext(deps);
+    const client = flag ?? (await chooseClient(deps, ctxLite));
+    if (client === null)
+        return EXIT_USAGE;
+    // ---- --token-env, resolved before the plan -------------------------------
+    const tokenEnv = typeof values["token-env"] === "string" ? values["token-env"] : undefined;
+    let token = resolved.token;
+    if (tokenEnv !== undefined) {
+        if (client === "claude-desktop" || client === "cursor") {
+            deps.writer.err(`--token-env is not something ${client} can use: its config holds the literal header value, ` +
+                "so a variable name there is a config that never authenticates. Drop --token-env for this client.");
+            return EXIT_USAGE;
+        }
+        if (client === "claude-code") {
+            // claude-code has no indirection either — it stores the header. So the flag
+            // means "use what that variable holds RIGHT NOW", and an unset variable is a
+            // command line that cannot be carried out, not an empty header to write.
+            const value = deps.env[tokenEnv];
+            if (typeof value !== "string" || value.length === 0) {
+                deps.writer.err(`--token-env ${tokenEnv} was given, but ${tokenEnv} is not set in this environment. ` +
+                    "claude-code stores the header value itself, so there is nothing to read.");
+                return EXIT_USAGE;
+            }
+            token = value;
+        }
+    }
+    const mcpEndpoint = stored?.mcpEndpoint ?? `${origin}/api/mcp`;
+    const plan = planInstall(client, {
+        ...ctxLite,
+        origin,
+        mcpEndpoint,
+        token,
+        tokenEnv,
+        onPath: deps.isOnPath,
+        fileExists: deps.fileExists,
+    });
+    const fallback = () => {
+        deps.writer.out(renderSnippet(client, { url: mcpEndpoint, placeholder: TOKEN_PLACEHOLDER, tokenEnv }));
+    };
+    // ---- --print: say what would happen, change nothing ----------------------
+    if (values.print === true) {
+        deps.writer.out(`# ${client} — ${plan.kind === "write" ? `would write ${plan.path}` : plan.kind === "exec" ? `would run \`${plan.argv[0]}\`` : "has no automated route"}`);
+        fallback();
+        return EXIT_OK;
+    }
+    // ---- already registered? -------------------------------------------------
+    const cfg = configPathFor(client, ctxLite);
+    const already = cfg.format === "toml" ? tomlConfigHasServer(cfg.path) : jsonConfigHasServer(cfg.path);
+    if (already && values.force !== true) {
+        const line = `${SERVER_NAME} is already registered in ${cfg.path}.`;
+        if (deps.ask === undefined) {
+            deps.writer.err(`${line} Re-run with --force to replace it.`);
+            return EXIT_USAGE;
+        }
+        const answer = (await deps.ask(`${line} Replace it? [y/N] `)).trim().toLowerCase();
+        if (answer !== "y" && answer !== "yes") {
+            deps.writer.out("Left the existing entry alone.");
+            return EXIT_OK;
+        }
+    }
+    switch (plan.kind) {
+        case "print":
+            deps.writer.out(`Nothing to run for ${client}: ${plan.reason}.`);
+            deps.writer.out("Paste this instead, with your own token:");
+            deps.writer.out(plan.snippet);
+            return EXIT_OK;
+        case "write": {
+            let result;
+            try {
+                result = upsertJsonConfig({ path: plan.path, entry: plan.entry });
+            }
+            catch (err) {
+                if (err instanceof McpConfigError) {
+                    deps.writer.err(err.message);
+                    deps.writer.err("Nothing was written. Fix that file, or add the entry by hand:");
+                    fallback();
+                    return EXIT_FAILED;
+                }
+                throw err;
+            }
+            deps.writer.out(`Registered ${SERVER_NAME} with ${plan.describe}.`);
+            // THE PATH, NEVER THE CONTENTS: the entry that was just written holds the
+            // bearer, and this line is the one a person copies into a chat.
+            deps.writer.out(`Wrote ${plan.path}${result.backup === undefined ? "" : ` (backup: ${result.backup})`}`);
+            return EXIT_OK;
+        }
+        default: {
+            const [command, ...args] = plan.argv;
+            if (command === undefined)
+                throw new Error("an exec plan with no command");
+            // `already` here means "there was an entry AND replacing it was authorized",
+            // because the only way past the block above with `already` true is --force or
+            // a yes at the prompt. Keying this on `--force` alone was a real defect: an
+            // interactive yes then reached the add below, which REFUSES a duplicate
+            // (exit 1, see the measurement), so the person who said yes was told the
+            // command could not register it.
+            if (already && client === "claude-code") {
+                // MEASURED 2026-09-15 (unpiped — the first reading of this was `| head`'s
+                // exit code, not the command's): a second `claude mcp add` with a name
+                // already in the config prints "MCP server <name> already exists in user
+                // config", leaves the entry untouched, and EXITS 1. So without this remove
+                // a `--force` install would simply FAIL — the person asked to replace the
+                // entry and would be told the command could not register it. The remove is
+                // what makes --force do what it says.
+                //
+                // Its own rc is ignored deliberately: removing a name that is not there is
+                // REFUSED with rc 1 and its own message ("No MCP server named … in user
+                // scope", measured unpiped 2026-09-15), which is not a problem worth
+                // reporting here — the add below is the real check either way.
+                await deps.spawn(command, ["mcp", "remove", SERVER_NAME, "--scope", "user"]);
+            }
+            const outcome = await deps.spawn(command, args);
+            if (outcome.error !== undefined || outcome.status !== 0) {
+                // THE COMMAND NAME AND ITS OWN STDERR, never the argv — the argv is where
+                // the bearer is on this path. `redact` runs here as well as in the writer
+                // because a vendor error string is the likeliest place a token comes back.
+                // THREE SOURCES, IN THE ORDER THAT SAYS SOMETHING. A command that RAN and
+                // refused explains itself on stderr. A command that could not START at all
+                // has no stderr — `spawnSync` reports that as `error` and leaves `status`
+                // null, so reading only stderr printed the useless "(exit null)" for the
+                // commonest case of all, a binary that is not really there. Both are
+                // redacted here as well as in the writer: a vendor error string is the
+                // likeliest place a token comes back.
+                const fromStderr = redact(String(outcome.stderr ?? "").trim().split("\n")[0] ?? "");
+                const fromError = outcome.error === undefined
+                    ? ""
+                    : redact((outcome.error instanceof Error ? outcome.error.message : String(outcome.error))
+                        .split("\n")[0] ?? "");
+                const detail = fromStderr.length > 0 ? fromStderr : fromError;
+                deps.writer.err(`\`${command}\` could not register ${SERVER_NAME}` +
+                    (detail.length > 0 ? `: ${detail}` : ` (exit ${String(outcome.status)})`));
+                deps.writer.err("Add it by hand instead:");
+                fallback();
+                return EXIT_FAILED;
+            }
+            deps.writer.out(`Registered ${SERVER_NAME} with ${plan.describe}.`);
+            if (client === "codex") {
+                const envName = tokenEnv ?? "FLOWSPRITE_MCP_TOKEN";
+                deps.writer.out(`Set ${envName} in the shell that starts codex — the config holds the variable NAME, not the token. ` +
+                    `\`flowsprite mcp print --client codex --reveal\` prints the export line at a terminal.`);
+            }
+            return EXIT_OK;
+        }
+    }
+}
+/**
+ * Which client to install into when `--client` was not given.
+ *
+ * DETECTED means "this machine has something to install into": the client's own
+ * command is on PATH, or its config file is already there. Everything else is
+ * listed as print-only rather than offered — offering a client that is not
+ * installed produces a config file nothing reads, which is indistinguishable from
+ * a successful install until the person wonders why their assistant cannot see
+ * the workspace.
+ */
+async function chooseClient(deps, ctxLite) {
+    const detected = [];
+    const rest = [];
+    for (const client of CLIENTS) {
+        const command = commandFor(client);
+        const present = (command !== null && deps.isOnPath(command)) || deps.fileExists(configPathFor(client, ctxLite).path);
+        (present ? detected : rest).push(client);
+    }
+    if (rest.length > 0) {
+        deps.writer.err(`Not detected here (use \`flowsprite mcp print --client <name>\` for a snippet): ${rest.join(", ")}.`);
+    }
+    if (detected.length === 0) {
+        deps.writer.err(`No supported AI client was detected. Name one anyway with --client (${CLIENTS.join(", ")}), ` +
+            "or run `flowsprite mcp print` and paste the snippet.");
+        return null;
+    }
+    // `pickOne` takes one silently, prompts at a terminal and refuses through a
+    // pipe with the flag to re-run with — the same three behaviours `bind` gets.
+    const picked = await pickOne(deps, MCP_CLIENT, detected.map((client) => {
+        const command = commandFor(client);
+        return [
+            client,
+            command !== null && deps.isOnPath(command)
+                ? `\`${command}\` is on PATH`
+                : `${configPathFor(client, ctxLite).path} exists`,
+        ];
+    }));
+    // Every id in `detected` came from CLIENTS, so whatever `pickOne` returns is one
+    // of them; `isClientId` proves that to the type system rather than asserting it.
+    return picked !== null && isClientId(picked) ? picked : null;
+}