flowsprite 0.1.0 → 0.1.3

package/dist/cli.js

@@ -3,12 +3,13 @@ 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 { deviceCodeLogin, ghCliLogin } 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 { printable, redact } from "./redact.js";
+import { asArray, asObject, planBindArgs, planNextStep, rungConnectionIds, runLinkStep, waitForRepository, } from "./setup.js";
+import { doorRefusalSentence, FROM_SF_CLI_EXCLUSIVE, parseSfOrgDisplay, projectDoorResult, scrubForceUrls, SF_ALIAS_RE, SF_ALIAS_RULE, sfLoginLine, sfRelogin, sfRemedy, } from "./sfCli.js";
 import { renderStatus } from "./status.js";
 import { USAGE } from "./usage.js";
 /**
@@ -31,8 +32,11 @@ const OPTIONS = {
     token: { type: "string" },
     save: { type: "boolean" },
     "no-open": { type: "boolean" },
+    workspace: { type: "string" },
+    "no-gh": { type: "boolean" },
     sandbox: { type: "boolean" },
     "my-domain": { type: "string" },
+    "from-sf-cli": { type: "string" },
     connection: { type: "string" },
     installation: { type: "string" },
     repo: { type: "string" },
@@ -73,6 +77,12 @@ export async function main(argv, deps) {
     if (!COMMANDS.has(command)) {
         return usageError(deps.writer, `Unknown command '${command}'.`);
     }
+    // `--from-sf-cli` is accepted by exactly one command. Refused elsewhere
+    // rather than ignored: FLO-514 found that a flag `setup` accepts and
+    // silently drops is how a person's intent goes missing.
+    if (typeof values["from-sf-cli"] === "string" && !(command === "connect" && positionals[1] === "salesforce")) {
+        return usageError(deps.writer, "--from-sf-cli belongs to `connect salesforce`: flowsprite connect salesforce --from-sf-cli <alias>.");
+    }
     const endpoint = parseEndpoint({
         flag: typeof values.endpoint === "string" ? values.endpoint : undefined,
         env: deps.env.FLOWSPRITE_ENDPOINT,
@@ -131,6 +141,13 @@ function clientFor(deps, origin, values) {
 }
 // ------------------------------------------------------------------- commands
 async function cmdLogin(deps, origin, values) {
+    // `--workspace` is the one value the gh road sends that a person typed.
+    // Refused empty HERE, before any spawn or request, rather than sent for the
+    // door to refuse: the door's `invalid_argument` costs a round trip to say so.
+    const workspaceFlag = typeof values.workspace === "string" ? values.workspace.trim() : null;
+    if (workspaceFlag !== null && workspaceFlag.length === 0) {
+        return usageError(deps.writer, "--workspace needs a name: flowsprite login --workspace <name>.");
+    }
     // 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.
@@ -149,14 +166,29 @@ async function cmdLogin(deps, origin, values) {
         }
         return EXIT_OK;
     }
-    const result = await deviceCodeLogin({
+    // ONE deps object for both roads, so the 409 road's browser tail inherits
+    // `--no-open` (and an absent opener) exactly as the device-code road does.
+    const loginDeps = {
         origin,
         fetch: deps.fetch,
         sleep: deps.sleep,
         writer: deps.writer,
         version: deps.version,
         ...(values["no-open"] === true || deps.openUrl === undefined ? {} : { openUrl: deps.openUrl }),
-    });
+        ...(deps.progress === undefined ? {} : { progress: deps.progress }),
+    };
+    // FLO-517: the gh road first, unless opted out. Null means it fell to the
+    // browser login at its own start, having said why in one line.
+    const viaGh = values["no-gh"] === true
+        ? null
+        : await ghCliLogin({
+            ...loginDeps,
+            isOnPath: deps.isOnPath,
+            spawn: deps.spawn,
+            ...(deps.ask === undefined ? {} : { ask: deps.ask }),
+            workspaceName: workspaceFlag,
+        });
+    const result = viaGh ?? (await deviceCodeLogin(loginDeps));
     if (!result.ok) {
         deps.writer.err(result.message);
         return EXIT_FAILED;
@@ -276,36 +308,186 @@ async function cmdConnect(deps, origin, values, which) {
     if (which !== "salesforce" && which !== "github") {
         return usageError(deps.writer, "connect takes 'salesforce' or 'github'.");
     }
+    // The `sf`-CLI door (FLO-515): a branch chosen BEFORE the link is minted,
+    // not a change to the link step. The alias was already routed here by `main`.
+    if (which === "salesforce" && typeof values["from-sf-cli"] === "string") {
+        return await connectFromSfCli(deps, origin, values, values["from-sf-cli"]);
+    }
     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"] } : {}),
+    // ponytail: the GitHub alternative door is absent here and plugs in at THIS
+    // call, as a branch chosen before the link is minted — the gh-token door
+    // (card A3, blocked), which would use a token the person already holds
+    // instead of an app install. The Salesforce one is `connectFromSfCli` above.
+    const args = which === "salesforce" ? salesforceLinkArgs(values) : {};
+    // No pre-mint snapshot is passed: the link step reads one itself, so `done`
+    // means a NEW connection or installation, never "the ladder is elsewhere".
+    const outcome = await runLinkStep(setupDeps(deps, built.client), tool, args, which);
+    return reportLinkOutcome(deps.writer, outcome, which);
+}
+/**
+ * `flowsprite connect salesforce --from-sf-cli <alias>` (FLO-515): read the
+ * Salesforce CLI's own login for that alias and hand it to the server door
+ * `setup_connect_salesforce_cli`, so the credential crosses inside THIS process
+ * — spawn stdout → parser → tools/call arguments — and never enters a chat, a
+ * transcript or this CLI's output. Why that matters: an agent harness redacted
+ * `result.sfdxAuthUrl` before its model could relay it (measured 2026-09-17,
+ * Claude Code), and the writer's redactor covers `fp_` tokens only, so the URL
+ * is scoped to the spawn-to-call span below and appears in NO string. Every
+ * printed text that did not originate in this CLI's constants goes through
+ * `scrubForceUrls` as defence in depth. The acceptance oracle censuses this
+ * function's source for `fs` / `console` identifiers: the writer and the
+ * tools/call body are its only sinks.
+ *
+ * Refusals BEFORE the network, in this order: the flag exclusivity (DM5), the
+ * alias rule (DM4), `sf` on PATH (DM3: install lines, never an auto-install),
+ * the stored credential, then the spawn's own failure and the envelope's shape
+ * (DM2: a JWT or empty-client login is refused here with the alias-bearing
+ * remedy rather than round-tripped to a server that would refuse it anyway).
+ */
+async function connectFromSfCli(deps, origin, values, alias) {
+    if (values.sandbox === true || typeof values["my-domain"] === "string") {
+        return usageError(deps.writer, FROM_SF_CLI_EXCLUSIVE);
+    }
+    if (!SF_ALIAS_RE.test(alias))
+        return usageError(deps.writer, SF_ALIAS_RULE);
+    // On Windows the npm install of sf is a `sf.cmd` shim, which node refuses to
+    // spawn without a shell (>= 20.12), so `isOnPath("sf")` reads FALSE for a
+    // person who has it (reasoned from Node's documented .cmd refusal, FLO-515
+    // fix round 1 — no Windows run exists in this repo's harness). There the
+    // PATH probe is skipped and the spawn itself is the probe.
+    const win32 = deps.platform === "win32";
+    if (!win32 && !deps.isOnPath("sf")) {
+        for (const line of sfRemedy(alias, deps.platform))
+            deps.writer.err(line);
+        return EXIT_USAGE;
+    }
+    const built = clientFor(deps, origin, values);
+    if (!built.ok)
+        return EXIT_FAILED;
+    // sf's stdout and stderr are NEVER printed: either can quote the URL.
+    // UNVERIFIED: the win32 arm — no Windows machine in this repo's harness. It
+    // runs sf through cmd.exe as ONE command string; that string is safe by
+    // construction because SF_ALIAS_RE (checked above) admits no quote, space or
+    // shell metacharacter, so the alias cannot end the command or start another.
+    const run = win32
+        ? await deps.spawn("cmd.exe", ["/d", "/s", "/c", "sf org display --verbose --json --target-org " + alias])
+        : await deps.spawn("sf", ["org", "display", "--verbose", "--json", "--target-org", alias]);
+    const spawnError = run.error !== undefined && run.error !== null;
+    // On win32 "sf is not installed" arrives two ways, both the install remedy
+    // the PATH probe gives elsewhere: cmd.exe itself could not start (a spawn
+    // `error`), or cmd.exe started and reported the command not recognized —
+    // its documented command-not-found ERRORLEVEL is 9009, so that STATUS is
+    // read as "no sf", never as "that org is not logged in". Reasoned from
+    // Windows' documented behaviour; UNVERIFIED on a real box like the rest of
+    // this branch.
+    if (win32 && (spawnError || run.status === 9009)) {
+        for (const line of sfRemedy(alias, "win32"))
+            deps.writer.err(line);
+        return EXIT_USAGE;
+    }
+    if (spawnError) {
+        deps.writer.err(`sf org display could not be run for '${alias}'. Is that org logged in? ${sfLoginLine(alias)}`);
+        return EXIT_FAILED;
+    }
+    const parsed = parseSfOrgDisplay(run.stdout ?? "");
+    if (run.status !== 0) {
+        // sf's JSON error envelope names an error CLASS (`NamedOrgNotFoundError`
+        // for a logged-out alias, exit 2); that identifier is printed, its free
+        // text and stderr never are.
+        const named = !parsed.ok && parsed.reason === "status" && parsed.message !== "";
+        const what = named ? `reported ${parsed.message}` : `failed for '${alias}'`;
+        deps.writer.err(`sf org display ${what} (exit ${run.status ?? "by signal"}). Is that org logged in? ${sfLoginLine(alias)}`);
+        return EXIT_FAILED;
+    }
+    if (!parsed.ok) {
+        switch (parsed.reason) {
+            case "not_json":
+                deps.writer.err(`sf org display did not return its JSON. ${sfLoginLine(alias)}`);
+                break;
+            case "status":
+                deps.writer.err(`sf org display reported ${parsed.message || "an error"}. ${sfLoginLine(alias)}`);
+                break;
+            default:
+                // `no_url` (a JWT login, or an older auth file with an empty client id)
+                // and `client` (another connected app): the server would refuse both.
+                deps.writer.err("That sf login cannot be handed over: only the Salesforce CLI's default connected app (PlatformCLI) " +
+                    `with a web login works. ${sfRelogin(alias)}`);
         }
-        : {};
-    const outcome = await runLinkStep(setupDeps(deps, built.client), tool, args, stepKind);
-    return reportLinkOutcome(deps.writer, outcome);
+        return EXIT_FAILED;
+    }
+    // The ONE place the URL leaves this process: exactly this key, nothing else.
+    const res = await built.client.callTool("setup_connect_salesforce_cli", { sfdxAuthUrl: parsed.sfdxAuthUrl });
+    if (!res.ok) {
+        switch (res.kind) {
+            case "tool_error":
+                // The door's own refusal sentence (or whatever the server said), scrubbed.
+                deps.writer.err(scrubForceUrls(res.message));
+                break;
+            case "rpc_error":
+                // A JSON-RPC error's message is the server's text: only its code is printed.
+                deps.writer.err(`Flowsprite's endpoint rejected the call${res.code === undefined ? "" : ` (JSON-RPC error ${res.code})`}. Run \`flowsprite doctor\`.`);
+                break;
+            default:
+                // `unauthorized` / `transport`: the client builds these sentences from
+                // its own URL, the HTTP status and an error NAME — no server text.
+                deps.writer.err(scrubForceUrls(res.message));
+        }
+        return EXIT_FAILED;
+    }
+    const doc = projectDoorResult(toolJson(res));
+    if (doc === null) {
+        deps.writer.err("Unexpected reply from setup_connect_salesforce_cli.");
+        return EXIT_FAILED;
+    }
+    if (values.json === true)
+        deps.writer.out(JSON.stringify(doc, null, 2));
+    if (!doc.ok) {
+        deps.writer.err(doorRefusalSentence(doc.code, alias));
+        return EXIT_FAILED;
+    }
+    if (values.json !== true) {
+        deps.writer.out(`Connected ${doc.orgName ?? doc.username} (${doc.envType}).`);
+        if (doc.reconnected)
+            deps.writer.out("That org was already connected to this workspace; its login was refreshed.");
+        deps.writer.out("Done.");
+    }
+    return EXIT_OK;
+}
+/**
+ * The `setup_connect_salesforce` arguments the flags ask for — ONE home, used by
+ * `connect salesforce` and by `setup`'s Salesforce rung, so a flag `setup`
+ * accepts cannot be one it silently ignores (FLO-514: `--my-domain` was).
+ */
+function salesforceLinkArgs(values) {
+    return {
+        ...(values.sandbox === true ? { env: "sandbox" } : {}),
+        ...(typeof values["my-domain"] === "string" ? { myDomain: values["my-domain"] } : {}),
+    };
 }
-function reportLinkOutcome(writer, outcome) {
+function reportLinkOutcome(writer, outcome, provider) {
+    const noun = provider === "github" ? "GitHub installation" : "Salesforce org";
     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`.");
+            if (outcome.used) {
+                // The link was opened but no new id arrived: re-authorizing an org (or
+                // re-installing on an account) that is already connected refreshes the
+                // existing row and mints nothing new, so "expired" would misdescribe it.
+                writer.err(`The link was used, but no new ${noun} appeared in this workspace. ` +
+                    "If you signed in to one that was already connected, it was refreshed — run `flowsprite status`.");
+            }
+            else if (outcome.kind === "expired") {
+                writer.err("That setup link expired before it was used. Run the command again for a fresh one.");
+            }
+            else {
+                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);
@@ -352,13 +534,13 @@ 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);
+    return await runBind(deps, origin, 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);
+async function runBind(deps, origin, values, client, rung) {
+    const filled = await fillBindInput(deps, origin, client, values, rung);
+    if (!filled.ok)
+        return filled.rc;
+    const plan = planBindArgs(filled.input);
     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
@@ -379,8 +561,45 @@ async function runBind(deps, values, client, rung) {
         for (const line of textOf(result.content))
             deps.writer.out(line);
     }
+    // Only `setup` waits: its NEXT rung is the first sync, which refuses a
+    // repository that is still being created. The wait sits inside the bind step,
+    // before the ladder's next read, so FIX-F1's identity guard compares the
+    // payload AFTER the repository settled.
+    // ponytail: a bare `flowsprite bind` does not wait — it has no next step to
+    // protect; `flowsprite status` shows "(creating)". Wait there too if people
+    // chain `bind && sync` in scripts.
+    if (rung !== null && asObject(toolJson(result))?.bootstrapState === "creating") {
+        return await reportRepositoryWait(deps, values, client, String(filled.input.connection));
+    }
     return EXIT_OK;
 }
+async function reportRepositoryWait(deps, values, client, connectionId) {
+    // Progress is prose, so under --json it goes to stderr and stdout stays parseable.
+    const say = (line) => (values.json === true ? deps.writer.err(line) : deps.writer.out(line));
+    say("Waiting for GitHub to create the repository...");
+    const outcome = await waitForRepository(setupDeps(deps, client), connectionId);
+    switch (outcome.kind) {
+        case "ready":
+            say("Repository ready.");
+            return EXIT_OK;
+        case "gone":
+            return EXIT_OK;
+        case "failed":
+            // Scrubbed HERE as well as at the writer: the writer keeps newlines (a
+            // multi-line refusal or a --json document is meant to stay lines), but a
+            // stored error INTERPOLATED into one sentence must not forge a second line
+            // (FLO-511 F3 pins it).
+            deps.writer.err(`Creating the repository failed: ${printable(outcome.error)}`);
+            deps.writer.err("Run `flowsprite setup` again to choose another name, or pick an existing repository.");
+            return EXIT_FAILED;
+        case "timeout":
+            deps.writer.err("The repository is still being created. Run `flowsprite setup` again in a minute.");
+            return EXIT_FAILED;
+        default:
+            deps.writer.err(outcome.message);
+            return EXIT_FAILED;
+    }
+}
 /**
  * Fill in `--connection`, `--installation` and the repository when the workspace
  * leaves no choice, and ask when it does.
@@ -391,14 +610,16 @@ async function runBind(deps, values, client, rung) {
  * 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.
+ * THE REPOSITORY DEFAULTS TO A NEW PRIVATE ONE (FLO-511, Noah 2026-09-17). A
+ * fresh GitHub installation has no repository list Flowsprite can show, so
+ * picking cannot be the default. Creating writes to the person's GitHub account,
+ * and the tool treats create + private as a consent decision, so it happens only
+ * after a yes at a prompt (or an explicit `--create`); without a prompt the
+ * command refuses and names the flag. Picking an existing repository is the "no"
+ * branch, and `--repo` is its non-interactive form.
  */
-async function fillBindInput(deps, client, values, rung) {
+async function fillBindInput(deps, origin, client, values, rung) {
+    const refuse = { ok: false, rc: EXIT_USAGE };
     const input = {
         connection: typeof values.connection === "string" ? values.connection : undefined,
         installation: typeof values.installation === "string" ? values.installation : undefined,
@@ -410,7 +631,7 @@ async function fillBindInput(deps, client, values, rung) {
         return status.ok ? status.payload : undefined;
     })();
     if (payload === undefined)
-        return null;
+        return refuse;
     const root = asObject(payload);
     const connections = asArray(root?.connections);
     const installations = asArray(root?.installations);
@@ -428,7 +649,7 @@ async function fillBindInput(deps, client, values, rung) {
     if (typeof input.connection === "string") {
         if (rung !== null && !rung.connectionIds.includes(input.connection)) {
             deps.writer.err(outOfRungRefusal(input.connection, rung));
-            return null;
+            return refuse;
         }
     }
     else {
@@ -437,7 +658,7 @@ async function fillBindInput(deps, client, values, rung) {
             `${String(c.displayName ?? "?")} [${String(c.envType ?? "?")}]`,
         ]));
         if (picked === null)
-            return null;
+            return refuse;
         input.connection = picked;
     }
     // ---- which GitHub installation ------------------------------------------
@@ -447,30 +668,70 @@ async function fillBindInput(deps, client, values, rung) {
             `@${String(i.accountLogin ?? "?")} [${String(i.accountType ?? "?")}]`,
         ]));
         if (picked === null)
-            return null;
+            return refuse;
         input.installation = picked;
     }
-    // ---- which repository ----------------------------------------------------
+    // ---- create a new repository, or pick an existing one -------------------
     if (typeof input.repo !== "string" && typeof input.create !== "string") {
-        const chosen = installations.find((i) => String(i.installationId ?? "") === String(input.installation));
+        const installationId = String(input.installation);
+        const chosen = installations.find((i) => String(i.installationId ?? "") === installationId);
+        const target = connections.find((c) => String(c.id ?? "") === String(input.connection));
+        const suggested = typeof target?.suggestedRepoName === "string" && target.suggestedRepoName.length > 0
+            ? target.suggestedRepoName
+            : null;
+        // Decided from setup_status BEFORE any call: a refusal's `kind` never
+        // reaches this client over HTTP, only its sentence.
+        if (chosen?.needsUserAuth === true) {
+            deps.writer.err(`GitHub needs a one-time sign-in before Flowsprite can create a repository on @${String(chosen.accountLogin ?? "?")}. ` +
+                `Open ${origin}/api/auth/github/user/start?installation_id=${installationId} in the browser where this workspace is open, ` +
+                "then run `flowsprite setup` again.");
+            deps.writer.err("To use a repository that already exists instead, pass --repo owner/name.");
+            return { ok: false, rc: EXIT_FAILED };
+        }
+        if (deps.ask === undefined) {
+            deps.writer.err("Flowsprite creates a new private repository here by default, and that needs a yes. " +
+                `Run \`flowsprite setup\` at a terminal, or pass --create ${suggested ?? "<name>"} ` +
+                "(or --repo owner/name to use an existing repository).");
+            return refuse;
+        }
+        const answer = (await deps.ask(`Create a new private GitHub repository for ${String(target?.displayName ?? input.connection)}? [Y/n] `)).trim().toLowerCase();
+        if (answer !== "" && answer !== "y" && answer !== "yes" && answer !== "n" && answer !== "no") {
+            // A typo is neither answer: reading it as "no" would bind an existing
+            // repository (silently, when exactly one is listed).
+            deps.writer.err("Answer y or n.");
+            return refuse;
+        }
+        if (answer === "" || answer === "y" || answer === "yes") {
+            const typed = (await deps.ask(`Repository name [${suggested ?? ""}]: `)).trim();
+            const name = typed.length > 0 ? typed : suggested;
+            if (name === null) {
+                deps.writer.err("The new repository needs a name. Run `flowsprite setup` again and type one, or pass --create <name>.");
+                return refuse;
+            }
+            // Not validated here: the server's own rule refuses a bad name, and its
+            // sentence is what the person sees.
+            input.create = name;
+            return { ok: true, input };
+        }
         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;
+            // repositories, not that the installation has none. The web's repository
+            // dropdown on Salesforce Orgs is the only thing that lists them.
+            deps.writer.err(`Flowsprite has not listed any repositories for installation ${installationId} yet. ` +
+                "Open this connection's repository list on the Salesforce Orgs page in the app and press Refresh, " +
+                "then run `flowsprite setup` again — or answer yes to create a new private one.");
+            return refuse;
         }
         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;
+            return refuse;
         input.repo = picked;
     }
-    return input;
+    return { ok: true, input };
 }
 /**
  * One of a list, or nothing.
@@ -640,9 +901,16 @@ async function cmdSetup(deps, origin, values) {
             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 (step.kind === "connect_salesforce" && deps.isOnPath("sf")) {
+                    deps.writer.out("Already logged in to that org with the Salesforce CLI? `flowsprite connect salesforce --from-sf-cli <alias>` connects it without a browser.");
+                }
+                const provider = step.kind === "connect_salesforce" ? "salesforce" : "github";
+                const tool = provider === "salesforce" ? "setup_connect_salesforce" : "setup_connect_github";
+                const args = provider === "salesforce" ? salesforceLinkArgs(values) : {};
+                // The payload just read IS the pre-mint snapshot: the rung is done when a
+                // NEW connection / installation appears in it, and the identity check at
+                // the top of the loop then sees the ladder move on that same new row.
+                const rc = reportLinkOutcome(deps.writer, await runLinkStep(sdeps, tool, args, provider, status.payload), provider);
                 if (rc !== EXIT_OK)
                     return rc;
                 previousTool = tool;
@@ -660,9 +928,23 @@ async function cmdSetup(deps, origin, values) {
                     return EXIT_FAILED;
                 }
                 deps.writer.out(step.text);
+                if (step.kind === "first_sync") {
+                    // A repository still being CREATED already counts as bound, so a re-run
+                    // of `setup` (or a wait that ended "gone") can land here while
+                    // `sfdc_trigger_sync` would refuse it. Wait for each one first, then
+                    // re-read the ladder rather than syncing off this stale payload.
+                    const creating = asArray(asObject(status.payload)?.connections).filter((c) => connectionIds.includes(String(c.id)) && c.bootstrapState === "creating");
+                    for (const c of creating) {
+                        const rc = await reportRepositoryWait(deps, values, built.client, String(c.id));
+                        if (rc !== EXIT_OK)
+                            return rc;
+                    }
+                    if (creating.length > 0)
+                        continue;
+                }
                 const rung = { kind: step.kind, connectionIds, status: status.payload };
                 const rc = step.kind === "bind_repo"
-                    ? await runBind(deps, values, built.client, rung)
+                    ? await runBind(deps, origin, values, built.client, rung)
                     : await runSync(deps, values, built.client, rung);
                 if (rc !== EXIT_OK)
                     return rc;
@@ -715,12 +997,44 @@ 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;
+    const clients = flag !== undefined ? [flag] : [...CLIENTS];
+    const ctxLite = pathContext(deps);
+    /** Every stdout line of this invocation, with `placeholder` where the bearer goes. */
+    const render = (placeholder) => {
+        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 }),
+            };
+        });
+        // ONE client asked for, one object; no client asked for, the array. Nothing
+        // else on stdout either way — that is what makes this parseable.
+        if (values.json === true)
+            return [JSON.stringify(flag !== undefined ? rows[0] : rows, null, 2)];
+        return rows.flatMap((row, n) => [...(n > 0 ? [""] : []), `# ${row.client}`, row.snippet]);
+    };
     if (values.reveal === true) {
-        if (deps.isTTY !== true) {
+        if (deps.reveal === undefined) {
             // 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.
+            // the person watching can decide to clear. The sink exists iff stdout is a
+            // terminal (wiring.ts), so its absence IS the pipe.
             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;
@@ -734,44 +1048,16 @@ function mcpPrint(deps, origin, values, flag) {
             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));
+        // THE ONE CALL SITE OF THE UNREDACTED SINK (FLO-513 AC3). Every stdout line
+        // of a --reveal run — the `# client` headers, the snippet, or the --json
+        // document — goes through it, because the writer would redact the token
+        // back out. The real token enters `render` only on this path.
+        for (const line of render(token.token))
+            deps.reveal(line);
         return EXIT_OK;
     }
-    rows.forEach((row, n) => {
-        if (n > 0)
-            deps.writer.out("");
-        deps.writer.out(`# ${row.client}`);
-        deps.writer.out(row.snippet);
-    });
+    for (const line of render(TOKEN_PLACEHOLDER))
+        deps.writer.out(line);
     return EXIT_OK;
 }
 async function mcpInstall(deps, origin, values, flag) {