flowsprite 0.1.0 → 0.1.3

package/dist/ghLogin.js

@@ -0,0 +1,173 @@
+/**
+ * FLO-517 — the pure half of `flowsprite login`'s gh road: what `gh auth token`
+ * printed is read BY SHAPE, and what `POST /api/cli/bootstrap/github` answered is
+ * classified BY SHAPE, before either value reaches a sink. This module imports
+ * nothing, so the classification can be pinned without a harness.
+ *
+ * THE INVARIANTS. Every field of the door's answer that this CLI will STORE,
+ * PRINT or OPEN is held to the grammar of whoever mints it, and anything else is
+ * `stop server_error`: a 200's token is the minter's `fp_` grammar (a door that
+ * echoed the gh bearer back would otherwise be stored as a credential), its ids
+ * are Clerk's `org_`/`user_` grammars and its endpoint is exactly this origin's
+ * `/api/mcp`; a 409's open target is exactly this origin's approve page
+ * (`/cli/auth`, no userinfo, no hash, at most `?code=<the payload's user_code>`)
+ * so a bearer cannot fit into a URL the CLI prints or hands to `openUrl`; the
+ * server's `remediation` is never carried — every sentence the CLI prints is a
+ * fixed local string.
+ */
+/**
+ * A GitHub token in running text: gh's own prefixes at a WORD BOUNDARY with a
+ * minimum suffix, so `highs_score` and a bare `ghs_` never match (spec gate C7 —
+ * an unanchored `ghs_[A-Za-z0-9_]+` matched inside `highs_score`). Real tokens
+ * are 40+ characters; the minimums are floors, not the grammar.
+ */
+export const GH_TOKEN_RE = /\b(?:(?:gho|ghp|ghu|ghs|ghr)_[A-Za-z0-9_]{16,}|github_pat_[A-Za-z0-9_]{20,})/;
+/** The bearer grammar the door itself enforces (`lib/cliBootstrapGithub.ts`, 401 outside it). */
+const GH_BEARER_RE = /^[A-Za-z0-9_]{20,255}$/;
+/**
+ * The token `gh auth token` printed, or null when there is no usable one: the
+ * command must have exited 0 and printed EXACTLY ONE line of bearer shape.
+ *
+ * A `ghs_` prefix is refused HERE, locally: `gh auth token` returns
+ * `GH_TOKEN`/`GITHUB_TOKEN` from the environment ahead of any stored login
+ * (measured gh 2.99.0), so in GitHub Actions it yields the job's installation
+ * token, which is not a user and cannot answer `GET /user` (UNVERIFIED: GitHub
+ * answers 403 for it, which the door reports as 502 `github_unavailable`, not
+ * a 401). Whatever the door would say, refusing it locally keeps CI on the
+ * browser road it had, at no request.
+ */
+export function readGhToken(outcome) {
+    if (outcome.status !== 0)
+        return null;
+    const text = (outcome.stdout ?? "").trim();
+    if (text.length === 0 || /[\r\n]/.test(text))
+        return null;
+    if (!GH_BEARER_RE.test(text) || text.startsWith("ghs_"))
+        return null;
+    return text;
+}
+/** A Flowsprite token as the minter emits it (`generateRawToken`, `convex/lib/mcpCrypto.ts`): the prefix and EXACTLY 32 suffix characters. */
+const FLOWSPRITE_TOKEN_RE = /^fp_(?:user|live)_[A-Za-z0-9_-]{32}$/;
+/** Clerk's id grammars — the door copies `org_id`/`user_id` from Clerk. */
+const ORG_ID_RE = /^org_[A-Za-z0-9]+$/;
+const USER_ID_RE = /^user_[A-Za-z0-9]+$/;
+const DEVICE_CODE_RE = /^[0-9a-f]{64}$/;
+const USER_CODE_RE = /^[A-Z]{4}-[A-Z]{4}$/;
+/** The approve page's path on the endpoint; the only thing a 409 may ask the CLI to open. */
+const APPROVE_PATH = "/cli/auth";
+/** The device-code TTL the endpoint documents (`expires_in: 900`) — and the ceiling. */
+export const MAX_EXPIRES_IN_SECONDS = 900;
+/**
+ * `expires_in` as the loop may trust it: a number this CLI reads off a response,
+ * and the loop's termination is the only thing between a bad value and a
+ * terminal that polls for a year. Anything larger than the documented TTL is a
+ * mistake or a hostile endpoint, and anything non-positive would end the loop
+ * before a single poll — both fold to the documented value. ONE rule for both
+ * roads: `/api/cli/auth/start` (`login.ts`) and the bootstrap door (below).
+ */
+export function clampExpiresIn(claimed) {
+    return typeof claimed === "number" && Number.isFinite(claimed) && claimed > 0
+        ? Math.min(MAX_EXPIRES_IN_SECONDS, Math.max(1, claimed))
+        : MAX_EXPIRES_IN_SECONDS;
+}
+/** The poll interval as the loop may trust it: a positive number, else the documented 5. ONE rule for both roads. */
+export function intervalSeconds(claimed) {
+    return typeof claimed === "number" && claimed > 0 ? claimed : 5;
+}
+const STOP_CODES = new Set([
+    "in_progress",
+    "rate_limited",
+    "github_token_invalid",
+    "no_verified_email",
+    "noreply_email",
+    "invalid_request",
+    "invalid_argument",
+    "suspended",
+    "revoked",
+    "ambiguous_grant",
+    "github_unavailable",
+    "clerk_unavailable",
+    "server_misconfigured",
+    "server_error",
+]);
+const STOP_SERVER_ERROR = { kind: "stop", code: "server_error" };
+/**
+ * The approve page this endpoint's 409 may ask the CLI to open, as the ONE string
+ * the CLI will print and hand to `openUrl` — or null. The raw server string is
+ * parsed, held field by field (the ORIGIN is exactly `origin`, host-anchored,
+ * never a prefix test; no userinfo; the path is `/cli/auth`; no fragment; the
+ * query is empty or exactly one `code` equal to the payload's own `userCode`),
+ * and then what is RETURNED is the NORMALISED `href`, never the raw string: the
+ * WHATWG parser removes dot segments, so `<origin>/gho_<token>/../cli/auth`
+ * parses to a pathname of `/cli/auth` while the raw string still carries the
+ * bearer (fix round 2 F6). The href is asserted to be one of the two exact
+ * forms, so nothing else can ever reach a sink.
+ */
+function approvePageHref(target, origin, userCode) {
+    if (typeof target !== "string")
+        return null;
+    let url;
+    try {
+        url = new URL(target);
+    }
+    catch {
+        return null;
+    }
+    if (url.origin !== origin || url.username !== "" || url.password !== "")
+        return null;
+    if (url.pathname !== APPROVE_PATH || url.hash !== "")
+        return null;
+    const params = [...url.searchParams.entries()];
+    if (params.length !== 0 && !(params.length === 1 && params[0][0] === "code" && params[0][1] === userCode))
+        return null;
+    const plain = `${origin}${APPROVE_PATH}`;
+    const withCode = `${plain}?code=${userCode}`;
+    return url.href === plain || url.href === withCode ? url.href : null;
+}
+/**
+ * One of four kinds for the door's answer. `origin` is the endpoint the request
+ * went to, so a 409's open target can be held to it.
+ */
+export function classifyBootstrapAnswer(status, body, origin) {
+    if (status === 200) {
+        const { token, org_id: orgId, user_id: userId, mcp_endpoint: mcpEndpoint } = body;
+        if (typeof token !== "string" ||
+            !FLOWSPRITE_TOKEN_RE.test(token) ||
+            typeof orgId !== "string" ||
+            !ORG_ID_RE.test(orgId) ||
+            typeof userId !== "string" ||
+            !USER_ID_RE.test(userId) ||
+            mcpEndpoint !== `${origin}/api/mcp`) {
+            return STOP_SERVER_ERROR;
+        }
+        return { kind: "token", token, orgId, userId, mcpEndpoint };
+    }
+    const deviceCode = body.device_code;
+    const expiresIn = clampExpiresIn(body.expires_in);
+    const interval = intervalSeconds(body.interval);
+    if (status === 202) {
+        if (typeof deviceCode !== "string" || !DEVICE_CODE_RE.test(deviceCode))
+            return STOP_SERVER_ERROR;
+        return { kind: "poll", deviceCode, expiresIn, interval };
+    }
+    if (status === 409 && (body.error === "browser_required" || body.error === "github_scope_missing")) {
+        const userCode = body.user_code;
+        if (typeof deviceCode !== "string" ||
+            !DEVICE_CODE_RE.test(deviceCode) ||
+            typeof userCode !== "string" ||
+            !USER_CODE_RE.test(userCode)) {
+            return STOP_SERVER_ERROR;
+        }
+        const openTarget = approvePageHref(body.verification_uri_complete ?? body.verification_uri, origin, userCode);
+        if (openTarget === null)
+            return STOP_SERVER_ERROR;
+        return { kind: "browser", reason: body.error, deviceCode, userCode, openTarget, expiresIn, interval };
+    }
+    const code = body.error;
+    if (typeof code !== "string" || !STOP_CODES.has(code))
+        return STOP_SERVER_ERROR;
+    const retryAfter = body.retry_after;
+    return code === "in_progress" && typeof retryAfter === "number" && retryAfter > 0
+        ? { kind: "stop", code, retryAfter }
+        : { kind: "stop", code: code };
+}

package/dist/login.js

@@ -1,4 +1,5 @@
-import { isLoginFailureKind, LOGIN_REMEDIES, POLL_CONTINUE_KINDS } from "./messages.js";
+import { clampExpiresIn, classifyBootstrapAnswer, intervalSeconds, readGhToken, } from "./ghLogin.js";
+import { APPROVER_BLOCKED_NOTE, GH_DOOR_REMEDIES, GH_ROAD, inProgressRemedy, isLoginFailureKind, LOGIN_REMEDIES, POLL_CONTINUE_KINDS, timeLeftLine, } from "./messages.js";
 /**
  * RFC 8628 device-code login against `/api/cli/auth/{start,poll}`.
  *
@@ -15,19 +16,27 @@ import { isLoginFailureKind, LOGIN_REMEDIES, POLL_CONTINUE_KINDS } from "./messa
  * treats a too-fast poll as `slow_down`, which lengthens the client's own next
  * window.
  *
- * ponytail: no `sf`-CLI door on this ladder — card B4 is Blocked, so there is no
- * "reuse the Salesforce CLI's browser session" rung here. When it lands it is
- * one more branch BEFORE `start` is called, not a second login function.
+ * THE GH ROAD (FLO-517, `ghCliLogin` below) is the one shortcut rung, and it
+ * sits BEFORE `start` is called: a terminal already signed in to `gh` sends that
+ * bearer to `/api/cli/bootstrap/github` and either gets the credential in one
+ * round trip, or is handed a device code whose browser/poll tail is THIS
+ * ladder's own `announceBrowser` + `pollLoop` — split out of `deviceCodeLogin`
+ * so the 409 and 202 roads reuse it instead of duplicating it. The Salesforce
+ * CLI's login is a different credential, consumed by `connect salesforce
+ * --from-sf-cli` (cli/src/cli.ts `connectFromSfCli`, FLO-515), not here.
  */
 /** Seconds added to the poll interval each time the server says `slow_down`. */
 const SLOW_DOWN_STEP_SECONDS = 5;
-/** The device-code TTL the endpoint documents (`expires_in: 900`) — and the ceiling. */
-const MAX_EXPIRES_IN_SECONDS = 900;
+/** `m:ss`, for the countdown. */
+function clock(seconds) {
+    const whole = Math.max(0, Math.floor(seconds));
+    return `${Math.floor(whole / 60)}:${String(whole % 60).padStart(2, "0")}`;
+}
 function failure(kind) {
     return { ok: false, kind, message: LOGIN_REMEDIES[kind] };
 }
 /** One POST of a JSON body, answering with the status and the parsed body. */
-async function postJson(deps, url, body) {
+async function postJson(deps, url, body, headers = {}) {
     let res;
     try {
         res = await deps.fetch(url, {
@@ -36,6 +45,7 @@ async function postJson(deps, url, body) {
                 "content-type": "application/json",
                 accept: "application/json",
                 "user-agent": `flowsprite-cli/${deps.version}`,
+                ...headers,
             },
             body: JSON.stringify(body),
         });
@@ -62,7 +72,8 @@ async function postJson(deps, url, body) {
 function refusalKind(body) {
     return isLoginFailureKind(body.error) ? body.error : "server_error";
 }
-export async function deviceCodeLogin(deps) {
+/** The POST to `/api/cli/auth/start`, parsed into the payload shape — or the failure. */
+async function startDeviceCode(deps) {
     const start = await postJson(deps, `${deps.origin}/api/cli/auth/start`, {
         client_name: "flowsprite-cli",
         cli_version: deps.version,
@@ -89,33 +100,34 @@ export async function deviceCodeLogin(deps) {
             : null;
     if (openTarget === null)
         return failure("server_error");
-    deps.writer.out(`Open ${openTarget} and confirm the code ${userCode}`);
+    // The device code's own lifetime bounds the loop, so a server that answers
+    // `authorization_pending` forever still ends — with the same sentence a real
+    // `expired_token` gets, because the window really has passed. CLAMPED TO THE
+    // REAL TTL (`clampExpiresIn`): a number this CLI reads off a response is what
+    // stands between a bad value and a terminal that polls for a year.
+    const expiresIn = clampExpiresIn(start.body.expires_in);
+    const interval = intervalSeconds(start.body.interval);
+    return { deviceCode, userCode, openTarget, expiresIn, interval };
+}
+/** The three lines a person acts on, plus the best-effort browser open. */
+function announceBrowser(deps, payload) {
+    deps.writer.out(`Open ${payload.openTarget} and confirm the code ${payload.userCode}`);
     deps.writer.out("Waiting for you to approve this login...");
+    deps.writer.out(timeLeftLine(payload.expiresIn));
     if (deps.openUrl) {
         try {
-            deps.openUrl(openTarget);
+            deps.openUrl(payload.openTarget);
         }
         catch {
             // Deliberately silent: see LoginDeps.openUrl. The URL is already printed.
         }
     }
-    const intervalFromServer = start.body.interval;
-    let intervalSeconds = typeof intervalFromServer === "number" && intervalFromServer > 0 ? intervalFromServer : 5;
-    // The device code's own lifetime bounds the loop, so a server that answers
-    // `authorization_pending` forever still ends — with the same sentence a real
-    // `expired_token` gets, because the window really has passed.
-    //
-    // CLAMPED TO THE REAL TTL. `expires_in` is a number this CLI reads off a
-    // response, and the loop's termination is the only thing standing between a
-    // bad value and a terminal that polls for a year. The server's own TTL is 15
-    // minutes (`docs/mcp.md`, `expires_in: 900`), so anything larger is either a
-    // mistake or a hostile endpoint, and anything non-positive would end the loop
-    // before a single poll. Both fold to the documented value.
-    const claimed = start.body.expires_in;
-    const expiresIn = typeof claimed === "number" && Number.isFinite(claimed) && claimed > 0
-        ? Math.min(claimed, MAX_EXPIRES_IN_SECONDS)
-        : MAX_EXPIRES_IN_SECONDS;
+}
+/** Poll `/api/cli/auth/poll` until the code is approved and minted, refused, or expired. */
+async function pollLoop(deps, { deviceCode, expiresIn, interval }) {
+    let intervalSeconds = interval;
     let waitedSeconds = 0;
+    let approverNotePrinted = false;
     for (;;) {
         if (waitedSeconds >= expiresIn)
             return failure("expired_token");
@@ -141,6 +153,20 @@ export async function deviceCodeLogin(deps) {
         }
         const kind = poll.body.error;
         if (typeof kind === "string" && POLL_CONTINUE_KINDS.has(kind)) {
+            // FLO-509: an informational bit on the pending answer. Strictly `true`:
+            // anything else a server sends here is ignored, never coerced. Printed once
+            // per login, and it never ends the wait — the refusal can be fixed inside
+            // the window, and a different person may still approve the same code.
+            if (kind === "authorization_pending" &&
+                poll.body.approver_blocked === true &&
+                !approverNotePrinted) {
+                approverNotePrinted = true;
+                deps.writer.out(APPROVER_BLOCKED_NOTE);
+            }
+            // ponytail: time left is expires_in minus the SUM OF SLEEPS, so fetch latency
+            // and a suspended laptop are not counted and it can overstate; thread `now`
+            // into LoginDeps for a wall-clock countdown if that ever reads wrong.
+            deps.progress?.(`Still waiting — ${clock(expiresIn - waitedSeconds)} left`);
             if (kind === "slow_down") {
                 // The server has ALREADY raised its own required interval by this much;
                 // raising ours to match is what stops the next poll earning another one.
@@ -152,3 +178,108 @@ export async function deviceCodeLogin(deps) {
         return failure(refusalKind(poll.body));
     }
 }
+export async function deviceCodeLogin(deps) {
+    const started = await startDeviceCode(deps);
+    if ("ok" in started)
+        return started;
+    announceBrowser(deps, started);
+    return pollLoop(deps, started);
+}
+/**
+ * `gh auth token`, read by shape. Null on every way it can fail — a non-zero
+ * exit, a throw, a REJECTING promise, or stdout that is not one token line.
+ * The error object is DISCARDED, never formatted (spec gate C4): a rejection's
+ * message can carry gh's stderr, and gh's stderr can carry the token.
+ */
+async function ghToken(deps) {
+    let outcome;
+    try {
+        outcome = await deps.spawn("gh", ["auth", "token"]);
+    }
+    catch {
+        return null;
+    }
+    if (typeof outcome !== "object" || outcome === null)
+        return null;
+    const { status, stdout } = outcome;
+    return readGhToken({
+        status: typeof status === "number" ? status : null,
+        ...(typeof stdout === "string" ? { stdout } : {}),
+    });
+}
+/**
+ * The workspace name the door is asked to create: `--workspace`, else one
+ * prompt when there is a terminal (an empty answer takes the default), else
+ * NULL — a pipe with no `--workspace` never creates a workspace silently (the
+ * caller says so in one sentence and takes the browser road, which a script
+ * had before this road existed). Asked AFTER the gh token was read — a
+ * logged-out gh never prompts — and BEFORE the door is asked.
+ */
+async function workspaceName(deps) {
+    if (deps.workspaceName !== null)
+        return deps.workspaceName;
+    if (deps.ask === undefined)
+        return null;
+    deps.writer.out(GH_ROAD.context);
+    const answer = (await deps.ask(GH_ROAD.question)).trim();
+    return answer.length > 0 ? answer : GH_ROAD.defaultWorkspace;
+}
+function stop(answer) {
+    const message = answer.code === "in_progress" && answer.retryAfter !== undefined
+        ? inProgressRemedy(answer.retryAfter)
+        : GH_DOOR_REMEDIES[answer.code];
+    return { ok: false, kind: answer.code, message };
+}
+/**
+ * FLO-517 — `flowsprite login` through the gh CLI's token. Returns null when the
+ * road falls to the browser login at its OWN start (gh absent, not logged in, or
+ * a pipe with no `--workspace`: one sentence, then the caller runs
+ * `deviceCodeLogin`); otherwise the result,
+ * which on a 409 or 202 is the SAME browser/poll tail with the door's payload —
+ * never a second `/api/cli/auth/start`.
+ *
+ * THE TOKEN'S SINKS are exactly two: the spawn's stdout (read once) and the
+ * request's `authorization` header. It is in no message (every sentence is a
+ * fixed local string), never logged, never stored; the writer's redactor
+ * (`redact.ts`) is the second net, not the first.
+ */
+export async function ghCliLogin(deps) {
+    if (!deps.isOnPath("gh")) {
+        deps.writer.out(GH_ROAD.notFound);
+        return null;
+    }
+    const token = await ghToken(deps);
+    if (token === null) {
+        deps.writer.out(GH_ROAD.notLoggedIn);
+        return null;
+    }
+    const companyName = await workspaceName(deps);
+    if (companyName === null) {
+        deps.writer.out(GH_ROAD.noTerminal);
+        return null;
+    }
+    deps.writer.out(GH_ROAD.using);
+    const posted = await postJson(deps, `${deps.origin}/api/cli/bootstrap/github`, { company_name: companyName, cli_version: deps.version }, { authorization: `Bearer ${token}` });
+    if (posted === null)
+        return failure("transport");
+    const answer = classifyBootstrapAnswer(posted.status, posted.body, deps.origin);
+    switch (answer.kind) {
+        case "token":
+            return { ok: true, token: answer.token, orgId: answer.orgId, userId: answer.userId, mcpEndpoint: answer.mcpEndpoint };
+        case "poll":
+            deps.writer.out(GH_ROAD.seedPending);
+            return pollLoop(deps, answer);
+        case "browser":
+            if (answer.reason === "github_scope_missing") {
+                deps.writer.out(GH_ROAD.scopeMissing);
+                deps.writer.out(GH_ROAD.scopeRemediation);
+            }
+            else {
+                deps.writer.out(GH_ROAD.browserRequired);
+            }
+            announceBrowser(deps, answer);
+            return pollLoop(deps, answer);
+        default:
+            return stop(answer);
+    }
+}

package/dist/mcpClient.js

@@ -6,6 +6,9 @@ import { redact } from "./redact.js";
  * request it was building, and the caller has no way to tell which strings came
  * from us. Redacting at the one place messages are constructed makes the
  * guarantee a property of this file rather than of every future edit to it.
+ * (Control characters are NOT scrubbed here: that is the writer's job,
+ * `cli/src/output.ts`, because tool text also reaches the terminal through
+ * parsed `toolJson` fields that never pass this constructor.)
  */
 function fail(kind, message, code) {
     const safe = redact(message);

package/dist/messages.js

@@ -13,6 +13,28 @@ export const LOGIN_REMEDIES = {
     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.",
 };
+/**
+ * FLO-509 — printed once, right after "Waiting for you to approve this login...".
+ * `seconds` is the CLAMPED `expires_in`. Whole minutes are rounded DOWN, so the
+ * line never promises more time than the loop will actually wait (61 s is "1
+ * minute", not 2), and anything under a minute says so rather than "0 minutes".
+ */
+export function timeLeftLine(seconds) {
+    const minutes = Math.floor(seconds / 60);
+    const span = minutes < 1 ? "less than a minute" : `${minutes} ${minutes === 1 ? "minute" : "minutes"}`;
+    return `This code is good for ${span}. Press Ctrl-C to stop waiting.`;
+}
+/**
+ * FLO-509 — printed once per login when a pending poll carries
+ * `approver_blocked: true`.
+ *
+ * PAST TENSE, because the server's marker is SET-ONLY: it says someone WAS
+ * refused, never that the code is still unapprovable (an admin may have fixed it,
+ * or a different person may approve it). It names no reason, person or
+ * workspace: the terminal is not told those, and the browser already showed that
+ * person the specific remedy.
+ */
+export const APPROVER_BLOCKED_NOTE = "Someone who opened this code in the browser could not approve it; that page says why and what to do. This terminal keeps waiting and logs in as soon as the code is approved.";
 /** 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"]);
 /**
@@ -45,3 +67,66 @@ const WIRE_KINDS = new Set([
 export function isLoginFailureKind(value) {
     return typeof value === "string" && WIRE_KINDS.has(value);
 }
+// ------------------------------------------------------------ the gh road (FLO-517)
+/**
+ * The lines `flowsprite login` prints on its gh road, before the device-code
+ * road takes over or the door answers. EVERY sentence here is a fixed local
+ * string: the door's `remediation` field is a server string, and a message is a
+ * sink the GitHub token must never reach (spec gate C2) — so the scope remedy is
+ * this CLI's own line, not the server's.
+ */
+/** The workspace name an empty prompt answer takes; the prompt shows it in brackets. */
+const DEFAULT_WORKSPACE = "My workspace";
+export const GH_ROAD = {
+    /** `gh` is not on PATH: one line, then the browser login it always was. */
+    notFound: "The GitHub CLI (gh) is not on PATH — using the browser to log in.",
+    /** `gh auth token` exited non-zero, threw, or printed anything but one token line. */
+    notLoggedIn: "gh is not logged in — using the browser to log in.",
+    /** Printed once before the workspace-name prompt, only when there is a terminal to prompt at. */
+    context: "Setting up Flowsprite from your GitHub CLI login.",
+    defaultWorkspace: DEFAULT_WORKSPACE,
+    question: `Name for your new Flowsprite workspace [${DEFAULT_WORKSPACE}]: `,
+    /** A pipe with no `--workspace`: a workspace is never created on a default nobody typed. */
+    noTerminal: "No terminal to ask for a workspace name — pass `--workspace <name>` to set up from your GitHub CLI login. Using the browser to log in.",
+    /** The road taken, named right before the door is asked. */
+    using: "Using your GitHub CLI login to set up Flowsprite...",
+    /** A 202: the poll loop finishes it — no code, no browser. */
+    seedPending: "Your workspace is being set up — this takes a few seconds.",
+    /**
+     * A 409 `browser_required`. It claims NOTHING about an existing account: the
+     * server's code is deliberately generic and also covers an email collision, a
+     * Clerk 422 and a consumed op.
+     */
+    browserRequired: "Flowsprite needs the browser to finish this login.",
+    scopeMissing: "Your gh login lacks the user:email scope, so the browser will finish this login. To skip the browser next time, run:",
+    scopeRemediation: "gh auth refresh -h github.com -s user:email",
+};
+/** The `in_progress` sentence, with the seconds the door's `retry_after` named. */
+export function inProgressRemedy(seconds) {
+    return `Another login for this GitHub account is in progress. Wait ${seconds} seconds and run \`flowsprite login\` again.`;
+}
+/**
+ * One sentence per way the door can STOP the login (exit 1, no browser). The
+ * codes shared with the device-code road keep that road's remedy — except
+ * `invalid_argument`, which on this door means the typed workspace name (the
+ * only value the door validates), so "a bug in this CLI" would be wrong.
+ * `in_progress` names the wait; see `inProgressRemedy`.
+ */
+export const GH_DOOR_REMEDIES = {
+    in_progress: inProgressRemedy(60),
+    rate_limited: LOGIN_REMEDIES.rate_limited,
+    github_token_invalid: "GitHub rejected the token gh holds. Run `gh auth login`, then `flowsprite login` again.",
+    no_verified_email: "GitHub has no verified primary email for this account. Verify an email address on GitHub and make it your primary address (https://github.com/settings/emails), then run `flowsprite login` again.",
+    noreply_email: "Your GitHub primary email is a noreply address. Set a real verified email as your primary on GitHub, then run `flowsprite login` again.",
+    invalid_request: LOGIN_REMEDIES.invalid_request,
+    invalid_argument: "Flowsprite rejected that workspace name. Run `flowsprite login --workspace <name>` with a different name.",
+    suspended: LOGIN_REMEDIES.suspended,
+    revoked: LOGIN_REMEDIES.revoked,
+    ambiguous_grant: LOGIN_REMEDIES.ambiguous_grant,
+    // "could not be completed", never "did not answer": these codes also cover a
+    // malformed answer from GitHub or Clerk (spec gate C6).
+    github_unavailable: "The GitHub check could not be completed. Try again in a minute, or run `flowsprite login --no-gh` to use the browser.",
+    clerk_unavailable: "Flowsprite's account service could not complete the request. Try again in a minute.",
+    server_misconfigured: LOGIN_REMEDIES.server_misconfigured,
+    server_error: LOGIN_REMEDIES.server_error,
+};

package/dist/output.js

@@ -1,12 +1,64 @@
-import { redact } from "./redact.js";
+import { printable, 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)),
+        out: (line) => sinks.out(scrubLines(redact(line))),
+        err: (line) => sinks.err(scrubLines(redact(line))),
+    };
+}
+/** `printable` per line, keeping the newlines that separate them. */
+function scrubLines(text) {
+    return text.split("\n").map(printable).join("\n");
+}
+/**
+ * FLO-509 — a status line redrawn IN PLACE on a terminal: carriage return, the
+ * redacted text, erase-to-end-of-line, and NO newline. `settle()` ends a line
+ * left dangling; `wireDeps` settles it before every writer and reveal line, and
+ * the bin settles it in its catch and SIGINT paths, so a later result or error
+ * never lands glued to the end of a countdown.
+ *
+ * Redacted and scrubbed like `out`/`err`, BEFORE this function adds its own
+ * carriage return and erase sequence: this is exit 2 of the five listed above,
+ * so it gets the same guarantee rather than relying on callers.
+ */
+export function createStatusLine(write) {
+    let dangling = false;
+    return {
+        progress: (line) => {
+            write(`\r${scrubLines(redact(line))}\x1b[K`);
+            dangling = true;
+        },
+        settle: () => {
+            if (!dangling)
+                return;
+            dangling = false;
+            write("\n");
+        },
+    };
+}
+/**
+ * FLO-509 — the Ctrl-C handler for a terminal with a status line: end the
+ * dangling countdown line, then RE-RAISE the signal. Without the settle, node dies
+ * mid-line and the next prompt lands glued to "Still waiting — 14:55 left" in
+ * shells that do not add a newline.
+ *
+ * RE-RAISE, NOT EXIT: the listener is process-wide, so every command run at a
+ * terminal (`setup`, `mcp`, `doctor`) reaches it. The bin installs it with
+ * `process.once`, so by the time `reraise` runs the listener is gone and the
+ * re-sent SIGINT meets node's default action — on POSIX the process dies BY THE
+ * SIGNAL, as it did before this handler existed (measured in a pty on node
+ * v26.8.1, macOS, FLO-509), rather than with an ordinary exit status.
+ * UNVERIFIED on Windows: node emulates `process.kill(pid, "SIGINT")` as a forced
+ * termination and console writes there can be asynchronous, so the settling
+ * newline may not land before the process ends (no worse than before FLO-509).
+ */
+export function settleThenReraise(status, reraise) {
+    return () => {
+        status.settle();
+        reraise();
     };
 }
 /** A writer that records, for tests and for the doctor's dry runs. */