flowsprite 0.1.0 → 0.1.4

package/dist/login.js

@@ -1,4 +1,6 @@
-import { isLoginFailureKind, LOGIN_REMEDIES, POLL_CONTINUE_KINDS } from "./messages.js";
+import { approvePageHref, clampExpiresIn, classifyBootstrapAnswer, intervalSeconds, readGhToken, USER_CODE_RE, } from "./ghLogin.js";
+import { APPROVER_BLOCKED_NOTE, clock, CODE_ENDING_KINDS, GH_DOOR_REMEDIES, GH_ROAD, inProgressRemedy, isLoginFailureKind, LOGIN_REMEDIES, OPEN_TARGET_REFUSED, POLL_CONTINUE_KINDS, RESUMING_LINE, SEED_RESUME_HINT, stillWaitingLine, timeLeftLine, waitHintLine, } from "./messages.js";
+import { printable } from "./redact.js";
 /**
  * RFC 8628 device-code login against `/api/cli/auth/{start,poll}`.
  *
@@ -15,19 +17,59 @@ 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;
+/** How often, in SLEPT seconds, a run with no status line re-prints the link (C2). */
+const REPRINT_EVERY_SECONDS = 60;
+/** The longest server-supplied display string the success line takes (an email's RFC 5321 cap). */
+const DISPLAY_MAX = 254;
+/**
+ * C4 — a display string from the poll answer, or undefined (the id is shown
+ * instead). It is SERVER text spliced into a CLI sentence, so it is scrubbed of
+ * every control character here (a newline in it would forge a line) — the
+ * writer's per-line scrub keeps newlines, so it is not enough on its own.
+ *
+ * eecc9d6f G4/H5 — THE RULE, not a list: every code point Unicode marks
+ * `Default_Ignorable_Code_Point` (renders as nothing: ZWSP/ZWJ, bidi marks, all
+ * variation selectors incl. Mongolian FVS, tag characters, the soft hyphen, the
+ * combining grapheme joiner…), every format character (`\p{Cf}`), and the line
+ * and paragraph separators U+2028/2029 are REMOVED, before the writer redacts.
+ * Removed, not spaced: a token split by an invisible character would otherwise
+ * reach the writer as two halves its redactor (`redact.ts`, a run of the token
+ * alphabet) matches only the first of; joined, the writer redacts it whole.
+ * Visible combining marks (`\p{Mn}` outside that property — accents in real
+ * names) are kept.
+ */
+const INVISIBLE = /[\p{Default_Ignorable_Code_Point}\p{Cf}\u2028\u2029]/gu;
+function displayText(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const text = printable(value.replace(INVISIBLE, "")).trim();
+    return text.length > 0 && text.length <= DISPLAY_MAX ? text : undefined;
+}
+/** A pending-port call that must never fail the login (C3). */
+function quietly(call) {
+    try {
+        call();
+    }
+    catch {
+        // Persistence is a convenience: an unwritable config dir costs the resume, not the login.
+    }
+}
 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 +78,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 +105,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,
@@ -79,48 +123,60 @@ export async function deviceCodeLogin(deps) {
     const userCode = start.body.user_code;
     const completeUri = start.body.verification_uri_complete;
     const fallbackUri = start.body.verification_uri;
-    if (typeof deviceCode !== "string" || typeof userCode !== "string") {
+    if (typeof deviceCode !== "string" || typeof userCode !== "string" || !USER_CODE_RE.test(userCode)) {
         return failure("server_error");
     }
-    const openTarget = typeof completeUri === "string"
-        ? completeUri
-        : typeof fallbackUri === "string"
-            ? fallbackUri
-            : null;
+    // eecc9d6f G1: the ONE string this CLI prints and hands to `openUrl` is held to
+    // the gh road's rule (`approvePageHref`): exactly this origin's `/cli/auth`,
+    // optionally `?code=<this user code>`, normalised. A foreign host, `file:`,
+    // `javascript:`, userinfo, or an option-shaped `-a…` (macOS `open` reads a
+    // `-a`/`-b` option out of a single argv element) never reaches a sink.
+    const openTarget = approvePageHref(completeUri ?? fallbackUri, deps.origin, userCode);
     if (openTarget === null)
-        return failure("server_error");
-    deps.writer.out(`Open ${openTarget} and confirm the code ${userCode}`);
+        return { ok: false, kind: "server_error", message: OPEN_TARGET_REFUSED };
+    // 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, expiresIn);
+    return { deviceCode, userCode, openTarget, expiresIn, interval };
+}
+/**
+ * The lines a person acts on, plus the best-effort browser open. A RESUMED login
+ * is announced again but not re-opened (`open: false`): the browser was opened
+ * by the run that started it, and the approval may already be done.
+ */
+function announceBrowser(deps, payload, open = true) {
+    // printable(): defence in depth — both values were already held to a grammar.
+    deps.writer.out(`Open ${printable(payload.openTarget)} and confirm the code ${printable(payload.userCode)}`);
     deps.writer.out("Waiting for you to approve this login...");
-    if (deps.openUrl) {
+    deps.writer.out(timeLeftLine(payload.expiresIn));
+    deps.writer.out(waitHintLine(payload.expiresIn));
+    if (open && 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, openTarget }) {
+    let intervalSeconds = interval;
     let waitedSeconds = 0;
+    let approverNotePrinted = false;
+    let reprintAt = REPRINT_EVERY_SECONDS;
     for (;;) {
         if (waitedSeconds >= expiresIn)
             return failure("expired_token");
-        await deps.sleep(intervalSeconds * 1000);
-        waitedSeconds += intervalSeconds;
+        // G3: never sleep past the code's end — the last nap is cut to the time left,
+        // so the slept total is at most `expiresIn` whatever `slow_down` added.
+        const nap = Math.min(intervalSeconds, expiresIn - waitedSeconds);
+        await deps.sleep(nap * 1000);
+        waitedSeconds += nap;
         const poll = await postJson(deps, `${deps.origin}/api/cli/auth/poll`, {
             device_code: deviceCode,
         });
@@ -137,10 +193,42 @@ export async function deviceCodeLogin(deps) {
                 typeof mcpEndpoint !== "string") {
                 return failure("server_error");
             }
-            return { ok: true, token, orgId, userId, mcpEndpoint };
+            const userEmail = displayText(poll.body.user_email);
+            const orgName = displayText(poll.body.org_name);
+            return {
+                ok: true,
+                token,
+                orgId,
+                userId,
+                mcpEndpoint,
+                ...(userEmail === undefined ? {} : { userEmail }),
+                ...(orgName === undefined ? {} : { orgName }),
+            };
         }
         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.
+            if (deps.progress) {
+                deps.progress(`Still waiting — ${clock(expiresIn - waitedSeconds)} left`);
+            }
+            else if (waitedSeconds >= reprintAt) {
+                // C2: no status line (a pipe, an agent shell) — one line per minute of
+                // waiting, carrying the link, so it never scrolls out of reach.
+                deps.writer.out(stillWaitingLine(expiresIn - waitedSeconds, openTarget));
+                reprintAt = (Math.floor(waitedSeconds / REPRINT_EVERY_SECONDS) + 1) * REPRINT_EVERY_SECONDS;
+            }
             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 +240,168 @@ export async function deviceCodeLogin(deps) {
         return failure(refusalKind(poll.body));
     }
 }
+/**
+ * C3 — poll, then settle the saved pending login. Success and every answer in
+ * `CODE_ENDING_KINDS` clear it (G10); a transient answer keeps it for the next
+ * `flowsprite login`. The clear names THIS run's device code (G2), so a stale
+ * run never deletes the entry a newer run saved.
+ */
+async function pollAndSettle(deps, pending) {
+    const result = await pollLoop(deps, pending);
+    if (result.ok || CODE_ENDING_KINDS.has(result.kind))
+        quietly(() => deps.pending?.clear(pending.deviceCode));
+    return result;
+}
+function savePending(deps, pending) {
+    quietly(() => deps.pending?.save(pending));
+}
+/**
+ * C3 — resume an unexpired login an earlier run announced, or null when none is
+ * saved (or the port fails). A resumed login calls NEITHER `/api/cli/auth/start`
+ * NOR the gh door. The saved numbers are re-clamped by the SAME rules the wire
+ * values get (G3): the wait is at most the seconds left (itself at most 900),
+ * and the interval is 1 s to that — so the slept total of a resumed login never
+ * exceeds the time the file says is left, capped at the code's 900 s TTL.
+ */
+async function resumePending(deps) {
+    let saved;
+    try {
+        saved = deps.pending?.load() ?? null;
+    }
+    catch {
+        return null;
+    }
+    if (saved === null)
+        return null;
+    const pending = {
+        ...saved,
+        expiresIn: clampExpiresIn(saved.expiresIn),
+        interval: intervalSeconds(saved.interval, clampExpiresIn(saved.expiresIn)),
+    };
+    deps.writer.out(RESUMING_LINE);
+    if (pending.userCode !== undefined && pending.openTarget !== undefined) {
+        announceBrowser(deps, { userCode: pending.userCode, openTarget: pending.openTarget, expiresIn: pending.expiresIn }, false);
+    }
+    else {
+        // G9b: the gh road's 202 — the workspace is being set up; nothing to approve.
+        deps.writer.out(GH_ROAD.seedPending);
+        deps.writer.out(SEED_RESUME_HINT);
+    }
+    return pollAndSettle(deps, pending);
+}
+export async function deviceCodeLogin(deps) {
+    const resumed = await resumePending(deps);
+    if (resumed !== null)
+        return resumed;
+    const started = await startDeviceCode(deps);
+    if ("ok" in started)
+        return started;
+    savePending(deps, started);
+    announceBrowser(deps, started);
+    return pollAndSettle(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) {
+    // C3: a login an earlier run left waiting is finished first — before gh is
+    // spawned or the door is asked, either of which would start a second one.
+    const resumed = await resumePending(deps);
+    if (resumed !== null)
+        return resumed;
+    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":
+            savePending(deps, answer);
+            deps.writer.out(GH_ROAD.seedPending);
+            return pollAndSettle(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);
+            }
+            savePending(deps, answer);
+            announceBrowser(deps, answer);
+            return pollAndSettle(deps, answer);
+        default:
+            return stop(answer);
+    }
+}

package/dist/mcpClient.js

@@ -1,4 +1,24 @@
 import { redact } from "./redact.js";
+/**
+ * The closed set of `structuredContent.error.code` values the endpoint can send on a refused
+ * `tools/call` (server side: `lib/mcpErrorEnvelope.ts`, `MCP_ERROR_CODES`). Duplicated here because
+ * this package builds standalone from `src/` and cannot import `lib/`; a root-tsc-checked test
+ * pins the two lists equal.
+ */
+export const TOOL_ERROR_CODES = [
+    "not_found",
+    "unauthorized",
+    "forbidden",
+    "invalid_argument",
+    "quota_exceeded",
+    "conflict",
+    "expired",
+    "not_ready",
+    "storage_failed",
+    "vendor_failed",
+    "cancelled",
+    "internal",
+];
 /**
  * EVERY message this module produces goes through `redact` before it is
  * returned. The bearer lives only in a header, so no message SHOULD carry it —
@@ -6,11 +26,27 @@ 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);
     return code === undefined ? { ok: false, kind, message: safe } : { ok: false, kind, message: safe, code };
 }
+/** The envelope's code + retryable, or undefined unless BOTH are well-formed (never a partial read). */
+function readToolError(structured) {
+    if (typeof structured !== "object" || structured === null || Array.isArray(structured))
+        return undefined;
+    const error = structured.error;
+    if (typeof error !== "object" || error === null || Array.isArray(error))
+        return undefined;
+    const { code, retryable } = error;
+    if (typeof retryable !== "boolean")
+        return undefined;
+    const known = TOOL_ERROR_CODES.find((c) => c === code);
+    return known === undefined ? undefined : { code: known, retryable };
+}
 export function createMcpClient(deps) {
     const url = `${deps.origin}/api/mcp`;
     let nextId = 0;
@@ -67,7 +103,9 @@ export function createMcpClient(deps) {
             // The tool's own refusal text is the whole value of this branch — an
             // `isError` result with no text would otherwise be an empty message.
             const text = content.find((c) => typeof c.text === "string")?.text;
-            return fail("tool_error", text ?? `${method} failed and said nothing about why.`);
+            const failure = fail("tool_error", text ?? `${method} failed and said nothing about why.`);
+            const toolError = readToolError(r.structuredContent);
+            return toolError === undefined ? failure : { ...failure, toolError };
         }
         return r.structuredContent === undefined
             ? { ok: true, content }

package/dist/messages.js

@@ -13,8 +13,92 @@ 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) {
+    return `This code is good for ${minutesSpan(seconds)}. Press Ctrl-C to stop waiting.`;
+}
+/** Whole minutes, rounded DOWN (see `timeLeftLine`), or "less than a minute". */
+export function minutesSpan(seconds) {
+    const minutes = Math.floor(seconds / 60);
+    return minutes < 1 ? "less than a minute" : `${minutes} ${minutes === 1 ? "minute" : "minutes"}`;
+}
+/** `m:ss`, for a countdown. Negative and fractional seconds fold to whole, non-negative ones. */
+export function clock(seconds) {
+    const whole = Math.max(0, Math.floor(seconds));
+    return `${Math.floor(whole / 60)}:${String(whole % 60).padStart(2, "0")}`;
+}
+/**
+ * Card eecc9d6f C2 — printed once after the link is announced. An agent shell
+ * (measured: Claude Code backgrounds a command at 120 s) can stop this process
+ * long before the code expires; the device code is kept on disk
+ * (`pending-login.json`) so the next `flowsprite login` resumes it instead of
+ * starting over.
+ */
+export function waitHintLine(seconds) {
+    return `This waits up to ${minutesSpan(seconds)} for you to approve in the browser. If your terminal or tool stops it sooner, run \`flowsprite login\` again — it picks up the same login.`;
+}
+/**
+ * C2 — re-printed every 60 s of waiting when there is no terminal status line
+ * (a pipe, an agent shell), so the link never scrolls out of reach. `openTarget`
+ * is absent on the gh road's 202, which has no page to open.
+ */
+export function stillWaitingLine(secondsLeft, openTarget) {
+    return `Still waiting — ${clock(secondsLeft)} left.${openTarget === undefined ? "" : ` Open ${openTarget}`}`;
+}
+/**
+ * eecc9d6f G1 — `/api/cli/auth/start` answered with a page that is not THIS
+ * endpoint's approve page (another host, another scheme, a malformed or
+ * option-shaped string). Nothing is printed, opened or saved; the commonest
+ * honest cause is the same host spelled two ways (127.0.0.1 vs localhost).
+ */
+export const OPEN_TARGET_REFUSED = "Flowsprite answered with a sign-in link for a different host than the endpoint this terminal is using, so it was not opened or printed. If you passed --endpoint, use the exact host the server uses (127.0.0.1 and localhost count as different hosts), then run `flowsprite login` again.";
+/**
+ * eecc9d6f G9b — printed when a login is resumed on the gh road's 202 (the
+ * workspace was being set up): nothing waits on a browser there.
+ */
+export const SEED_RESUME_HINT = "If your terminal or tool stops this sooner, run `flowsprite login` again — it picks up the same login.";
+/** C3 — printed when `flowsprite login` picks up a login an earlier run started. */
+export const RESUMING_LINE = "Picking up the login this terminal started earlier.";
+/** C5 — printed after the success line: the setup links are bound to the account AND the workspace. */
+export const SAME_ACCOUNT_NOTE = "Setup links this terminal prints open only in a browser signed in to Flowsprite as this same account, in this same workspace.";
+/**
+ * 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"]);
+/**
+ * eecc9d6f G10/H1 — the poll answers that END a device code, and so clear its
+ * saved pending login. The rule: the server said THIS code can no longer be
+ * approved or exchanged — including `invalid_request`/`invalid_argument`, the
+ * wire's two `invalid_*` kinds (`WIRE_KINDS` below), which say the code itself
+ * is unusable. Only the four transient answers keep it: `transport`,
+ * `rate_limited`, `server_error`, `server_misconfigured` — and an entry is never
+ * live past its write + 900 s (`readPendingLogin`).
+ */
+export const CODE_ENDING_KINDS = new Set([
+    "expired_token",
+    "access_denied",
+    "no_grant",
+    "not_member",
+    "suspended",
+    "revoked",
+    "ambiguous_grant",
+    "invalid_request",
+    "invalid_argument",
+]);
 /**
  * The kinds that can arrive FROM THE WIRE — a strict subset of the remedy table.
  *
@@ -45,3 +129,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,
+};