flowsprite 0.1.0 → 0.1.4

package/dist/sfCli.js

@@ -0,0 +1,179 @@
+/**
+ * The pure half of `flowsprite connect salesforce --from-sf-cli <alias>`
+ * (FLO-515): the alias rule, the `sf org auth show-sfdx-auth-url --json`
+ * envelope parser, the remedies, and the allow-list projection of the door's
+ * reply.
+ *
+ * The command changed on 2026-09-20 (card 263cefa5). FLO-515 read the login
+ * from `sf org display --verbose --json`; sf 2.147.0 (published 2026-07-31,
+ * `npm view @salesforce/cli time`) bundles @salesforce/plugin-org 6.0.x, which
+ * writes a `[REDACTED] Use 'sf org auth show-sfdx-auth-url' to view`
+ * placeholder into that command's `sfdxAuthUrl` unless a documented-temporary
+ * env var is set, so on a current sf the old parser answered `no_url` for a
+ * perfectly good web login (measured on sf 2.150.6, 2026-09-20). The stable
+ * command this module now parses ships in the same plugin version and needs no
+ * env var. Its `--json` stdout is `{status, result:{sfdxAuthUrl}, warnings}` —
+ * no accessToken, no password, no clientId; the command's own warning text
+ * lands both in that `warnings` array and on stderr (sf-plugins-core
+ * `toSuccessJson`/`warn`, measured against 12.2.6), and this CLI prints
+ * neither.
+ *
+ * NOTHING HERE PRINTS. The `sfdxAuthUrl` this module extracts is a reusable
+ * Salesforce credential that the CLI's own redactor cannot see (`redact.ts`
+ * covers `fp_user_`/`fp_live_` runs only), so the value's only sinks are the
+ * spawn stdout it came from and the `tools/call` arguments — the caller in
+ * `cli.ts` (`connectFromSfCli`) holds it in one scope and hands it to exactly
+ * one place. The acceptance oracle censuses both files for `fs` / `console`
+ * identifiers, which is why this module imports nothing.
+ */
+/**
+ * An sf alias or username: letters, digits, `. _ @ + -`, not starting with `-`
+ * (flag-shaped for the downstream CLI), at most 80 characters. `@` and `+`
+ * because `--target-org` takes usernames, which are emails and can be
+ * plus-addressed. The value is spawned as ONE argv element (never a shell), so
+ * the rule exists for the printed remedies and for the third-party CLI's own
+ * parser, not for a shell.
+ */
+export const SF_ALIAS_RE = /^(?!-)[A-Za-z0-9._@+-]{1,80}$/;
+export const SF_ALIAS_RULE = "--from-sf-cli wants an sf alias or username: letters, digits, . _ @ + -, not starting with -, at most 80 characters.";
+export const FROM_SF_CLI_EXCLUSIVE = "--from-sf-cli takes the org from the sf CLI; --sandbox and --my-domain belong to the browser link.";
+/**
+ * Every `force://` run up to the next whitespace becomes a marker that carries
+ * NO scheme, so a scrubbed line can never itself read as an auth URL. Applied
+ * to every string this command prints that did not originate in this CLI's own
+ * constants — a tool's refusal text, an org's display name.
+ */
+export function scrubForceUrls(text) {
+    return text.replace(/force:\/\/\S*/g, "[sf auth url removed]");
+}
+const SF_URL_PREFIX = "force://PlatformCLI::";
+const ERROR_NAME_RE = /^[A-Za-z0-9_]{1,64}$/;
+/**
+ * The sentence for an `sf` that predates the command (card 263cefa5 DM4). It
+ * names no alias: a missing subcommand is a property of the INSTALL, not of
+ * the org, so the login line and the logout-then-login remedy are both wrong
+ * here — logging in again does not add a subcommand. It also stays true if sf
+ * ever removes the command, which is why it ends at the browser road.
+ */
+export const SF_TOO_OLD_REMEDY = "Your Salesforce CLI does not have `sf org auth show-sfdx-auth-url` (added in sf 2.147.0, July 2026), " +
+    "which this command reads the login from. Update it — sf update, or npm install -g @salesforce/cli — " +
+    "then run this again; if it persists on a current sf, connect this org from the browser: flowsprite connect salesforce.";
+/**
+ * Read the `sf org auth show-sfdx-auth-url --target-org <alias> --json`
+ * envelope: `{status, result:{sfdxAuthUrl}, warnings}`, parsed from the first
+ * `{` because a CLI notice can precede the JSON (the setup skill body already
+ * parses from the first `{` for the other configurations). Only
+ * `result.sfdxAuthUrl` is read: `warnings` carries the command's own "this
+ * exposes an SFDX Auth URL" text, which also goes to stderr, and neither is
+ * returned or printed.
+ *
+ * A non-zero envelope `status` reports the envelope's `name` — an error-class
+ * identifier such as `NamedOrgNotFoundError` (a logged-out or mistyped alias)
+ * or `NoRefreshTokenError` (a JWT / access-token login) — and NEVER its
+ * free-text `message`: that text is third-party and can quote the URL
+ * (spec-gate codex C2), so it is not even returned.
+ *
+ * There is no `clientId` in this envelope and no `client` reason: the url's own
+ * `force://PlatformCLI::` prefix IS the client check here, and the server door
+ * re-checks it. An auth file written before the CLI stored its client id
+ * yields `force://:<token>@host` (empty client id), which fails that prefix and
+ * is `no_url` like an absent or non-string url.
+ */
+export function parseSfAuthUrl(stdout) {
+    const start = stdout.indexOf("{");
+    if (start < 0)
+        return { ok: false, reason: "not_json" };
+    let doc;
+    try {
+        doc = JSON.parse(stdout.slice(start));
+    }
+    catch {
+        return { ok: false, reason: "not_json" };
+    }
+    if (typeof doc !== "object" || doc === null || Array.isArray(doc))
+        return { ok: false, reason: "not_json" };
+    const envelope = doc;
+    if (envelope.status !== 0) {
+        const name = typeof envelope.name === "string" && ERROR_NAME_RE.test(envelope.name) ? envelope.name : "";
+        return { ok: false, reason: "status", message: name };
+    }
+    const result = typeof envelope.result === "object" && envelope.result !== null && !Array.isArray(envelope.result)
+        ? envelope.result
+        : {};
+    const url = result.sfdxAuthUrl;
+    if (typeof url !== "string" || !url.startsWith(SF_URL_PREFIX))
+        return { ok: false, reason: "no_url" };
+    return { ok: true, sfdxAuthUrl: url };
+}
+/** The `sf org login web` line for this alias — sandbox users need the host. */
+export function sfLoginLine(alias) {
+    return (`sf org login web --alias ${alias} --instance-url <your sandbox My Domain, ` +
+        "for example https://acme--uat.sandbox.my.salesforce.com, or https://test.salesforce.com; " +
+        "leave --instance-url off for a production or Developer Edition org (sf's default login host)>");
+}
+/** The logout-then-login remedy for a login this door cannot take over. */
+export function sfRelogin(alias) {
+    return `Run: sf org logout --target-org ${alias}, then ${sfLoginLine(alias)}`;
+}
+/**
+ * What to print when `sf` is not on PATH: the install line(s) for the platform,
+ * the PATH note for a fresh npm install the shell cannot see yet, then the
+ * login line. No auto-install (DM3): a global install is the person's decision.
+ */
+export function sfRemedy(alias, platform) {
+    const lines = ["The Salesforce CLI (sf) is not on PATH, so there is no login to hand over. Install it:", "  npm install -g @salesforce/cli"];
+    if (platform === "darwin")
+        lines.push("  brew install --cask salesforce-cli");
+    if (platform === "win32")
+        lines.push("  or the Windows installer: https://developer.salesforce.com/tools/salesforcecli");
+    if (platform !== "win32") {
+        lines.push('If you installed it with npm and this shell still cannot find it: export PATH="$(npm prefix -g)/bin:$PATH"');
+    }
+    lines.push("Then log in to the org and run this command again:", `  ${sfLoginLine(alias)}`);
+    return lines;
+}
+const DOOR_CODES = new Set(["sf_cli_refresh_failed", "sf_cli_identity_failed", "sf_cli_env_unresolved", "sf_cli_save_failed"]);
+const ENV_TYPES = new Set(["production", "sandbox", "developer"]);
+/**
+ * Rebuild the door's reply from an ALLOW-LIST — exactly {ok, username, orgName,
+ * envType, reconnected} or {ok, code} — so a reply is never serialized
+ * wholesale and an extra key (the URL echoed back, anything) is dropped rather
+ * than printed. The org-reported strings are scrubbed here, before any sink.
+ * `null` is "not the door's shape", which the caller reports as unexpected.
+ */
+export function projectDoorResult(doc) {
+    if (typeof doc !== "object" || doc === null || Array.isArray(doc))
+        return null;
+    const d = doc;
+    if (d.ok === true) {
+        if (typeof d.username !== "string" || typeof d.envType !== "string" || !ENV_TYPES.has(d.envType))
+            return null;
+        if (typeof d.reconnected !== "boolean")
+            return null;
+        if (d.orgName !== undefined && typeof d.orgName !== "string")
+            return null;
+        return {
+            ok: true,
+            username: scrubForceUrls(d.username),
+            ...(d.orgName === undefined ? {} : { orgName: scrubForceUrls(d.orgName) }),
+            envType: d.envType,
+            reconnected: d.reconnected,
+        };
+    }
+    if (d.ok === false && typeof d.code === "string" && DOOR_CODES.has(d.code))
+        return { ok: false, code: d.code };
+    return null;
+}
+/** One sentence per refusal code the door can answer with. */
+export function doorRefusalSentence(code, alias) {
+    switch (code) {
+        case "sf_cli_refresh_failed":
+            return `Salesforce refused that login's token. Log in again: ${sfLoginLine(alias)}`;
+        case "sf_cli_identity_failed":
+            return "Salesforce accepted the token but its identity could not be read. Try again in a minute; if it persists, connect this org from the browser.";
+        case "sf_cli_env_unresolved":
+            return "Flowsprite could not read whether that org is a sandbox and does not guess production versus sandbox. Try again; if it persists, connect it from the browser.";
+        default:
+            return "Flowsprite could not save the connection. Run `flowsprite status` and try again.";
+    }
+}

package/dist/status.js

@@ -1,3 +1,4 @@
+import { printable } from "./redact.js";
 import { asArray, asObject, planNextStep } from "./setup.js";
 /**
  * Render a `setup_status` payload as plain text.
@@ -37,6 +38,15 @@ function expiryText(value) {
     }
     return new Date(value).toISOString();
 }
+/** A connection's repository, with its creation state when it is not ready yet (FLO-511 DM5). */
+function repoText(c) {
+    const repo = str(c.repo, "none");
+    if (c.bootstrapState === "creating")
+        return `${repo} (creating)`;
+    if (c.bootstrapState === "failed")
+        return `${repo} (failed: ${printable(str(c.bootstrapError, "no reason given"))})`;
+    return repo;
+}
 export function renderStatus(payload) {
     const root = obj(payload);
     if (root === null) {
@@ -64,7 +74,7 @@ export function renderStatus(payload) {
     if (connections.length === 0)
         lines.push("  none");
     for (const c of connections) {
-        lines.push(`  ${str(c.id)}  ${str(c.displayName)}  [${str(c.envType)}]  repo: ${str(c.repo, "none")}  synced: ${yesNo(c.hasSyncJob)}`);
+        lines.push(`  ${str(c.id)}  ${str(c.displayName)}  [${str(c.envType)}]  repo: ${repoText(c)}  synced: ${yesNo(c.hasSyncJob)}`);
     }
     const installations = arr(root.installations);
     lines.push("", `GitHub installations (${installations.length})`);

package/dist/usage.js

@@ -1,44 +1,84 @@
-/** The usage text, as data, so `--help` and every exit-2 refusal print the same thing. */
+/**
+ * The usage text, as data, so `--help` and every exit-2 refusal print the same thing.
+ *
+ * Card eecc9d6f N5/N6/N13: what Flowsprite is first, then examples, then each
+ * command WITH ITS OWN OPTIONS under it. Every flag `cli.ts` parses appears here
+ * (pinned in usage.test.ts against the parser's own option table). `--sandbox`
+ * names the generic hosts the server picks (`lib/salesforceOAuthExchange.ts`
+ * GENERIC_OAUTH_HOST: sandbox -> test.salesforce.com, prod -> login.salesforce.com).
+ */
 export const USAGE = `flowsprite — set up and drive a Flowsprite workspace from a terminal.
 
+Flowsprite mirrors a Salesforce org's metadata into a PRIVATE GitHub repository.
+\`flowsprite setup\` takes three steps: log this terminal in, connect Salesforce,
+then connect GitHub and create the private repository.
+
 Usage: flowsprite [command] [options]
 
-Commands:
-  setup                     Run the whole setup ladder (the default).
-  login                     Log this terminal in with a device code.
+Examples:
+  flowsprite setup                  Log in and set the workspace up, step by step.
+  flowsprite setup --sandbox        The same, connecting a Salesforce sandbox org.
+  flowsprite mcp install --client claude-code
+                                    Point Claude Code at this workspace.
+
+Commands, each with its own options:
+  setup                     Run the whole setup (the default command). Steps
+                            that are already done are skipped.
+    --sandbox               Connect a Salesforce sandbox org (sign-in at
+                            test.salesforce.com). Without it the sign-in is at
+                            login.salesforce.com, the production login host.
+    --my-domain <host>      Sign in to Salesforce at this My Domain host instead.
+    --no-open               Do not try to open a browser for the login step.
+  login [--workspace <name>] [--no-gh]
+                            Log this terminal in. Uses the GitHub CLI's login
+                            (gh) when it has one, else a device code in the
+                            browser.
+    --workspace <name>      The name for the workspace the GitHub CLI login
+                            creates. Omitted, login asks at a terminal; through
+                            a pipe it uses the browser instead.
+    --no-gh                 Skip the GitHub CLI and use the browser.
+    --no-open               Do not try to open a browser.
+    --token <token>         Use this token instead of logging in.
+    --save                  With --token: also store it for this endpoint.
   logout                    Forget the stored credential for this endpoint.
   status                    Show the setup checklist, connections and installations.
   connect salesforce        Get a one-time link to connect a Salesforce org.
+                            Takes --sandbox and --my-domain, as setup does.
+  connect salesforce --from-sf-cli <alias>
+                            Connect an org the Salesforce CLI is already logged
+                            in to (no browser). Needs sf on PATH and a web
+                            login (not JWT).
   connect github            Get a one-time link to install the GitHub app.
-  bind                      Bind a GitHub repo to a Salesforce connection. With no
-                            --repo/--create it offers the repos setup_status lists.
+  bind                      Give a Salesforce connection a GitHub repo. With no
+                            --repo/--create it offers to create a new private
+                            one with a suggested name, or pick an existing one.
+    --connection <id>       The Salesforce connection id (also for sync).
+    --installation <number> The GitHub installation id.
+    --repo <owner/name>     Use a repository that already exists.
+    --create <name>         Create a new repository with this name, without
+                            asking. Always PRIVATE — Flowsprite only mirrors
+                            into private repos.
   sync                      Start a metadata sync and show the recent sync log.
+                            Takes --connection, as bind does.
   doctor                    Check node, the endpoint, the credential, and sf/gh.
+                            Exits 1 when a check FAILs.
   mcp install               Point an AI client at this workspace's MCP endpoint.
+    --client <name>         claude-code, codex, claude-desktop or cursor.
+                            Omitted, mcp install offers the ones it detects and
+                            mcp print shows every one.
+    --print                 Show what it would do, change nothing.
+    --force                 Replace an existing flowsprite entry.
+    --token-env <NAME>      codex reads the bearer from this variable;
+                            claude-code uses its CURRENT value.
   mcp print                 Show the config snippet for a client, token hidden.
+                            Takes --client, as mcp install does.
+    --reveal                Print the real token instead of <YOUR_TOKEN>. Only
+                            at a terminal, never through a pipe.
 
-Options:
+Options for every command:
   --endpoint <origin>       Flowsprite origin (default https://app.flowsprite.com).
   --json                    Machine-readable output where a command has one.
   --token <token>           Use this token instead of the stored credential.
-  --save                    With --token: also store it for this endpoint.
-  --no-open                 Do not try to open a browser during login.
-  --sandbox                 connect salesforce: use the sandbox login host.
-  --my-domain <host>        connect salesforce: use this My Domain login host.
-  --connection <id>         bind / sync: the Salesforce connection id.
-  --installation <number>   bind: the GitHub installation id.
-  --repo <owner/name>       bind: a repository that already exists.
-  --create <name>           bind: create a new repository instead. Always PRIVATE —
-                            Flowsprite only mirrors into private repos.
-  --client <name>           mcp: claude-code, codex, claude-desktop or cursor.
-                            Omitted, mcp install offers the ones it detects and
-                            mcp print shows every one.
-  --print                   mcp install: show what it would do, change nothing.
-  --force                   mcp install: replace an existing flowsprite entry.
-  --reveal                  mcp print: print the real token instead of
-                            <YOUR_TOKEN>. Only at a terminal, never through a pipe.
-  --token-env <NAME>        mcp install: codex reads the bearer from this
-                            variable; claude-code uses its CURRENT value.
   -h, --help                Show this help and exit 0.
   -v, --version             Show the version and exit 0.
 

package/dist/version.js

@@ -7,4 +7,4 @@
  * manifest are pinned EQUAL by cli/src/packaging.test.ts, which reads both, so
  * they cannot disagree without a red test.
  */
-export const VERSION = "0.1.0";
+export const VERSION = "0.1.4";

package/dist/wiring.js

@@ -0,0 +1,96 @@
+import { createStatusLine, createWriter } from "./output.js";
+import { printable, redact } from "./redact.js";
+/**
+ * THE WRITER, THE STATUS LINE AND THE REVEAL SINK ARE BUILT HERE; the readline
+ * prompt (`ask`, built in bin.ts) only passes through, redacted and scrubbed, and the bin's
+ * last-line-of-defence catch is its own exit (see the exit list in output.ts).
+ * Two conditions govern what exists:
+ *
+ * - the writer (`log`/`error`, both redacting) — unconditional;
+ * - the status line and the ONE unredacted sink, `reveal` — only when
+ *   `stdout.isTTY === true`. Strictly `=== true`: a real pipe carries
+ *   `isTTY === undefined`, so `!== false` would reveal into a pipe. The sink
+ *   writes through the SAME `stdout` object whose `isTTY` authorised it, never
+ *   through `log` (a separate function a caller could point anywhere). Its only
+ *   reader is `mcpPrint` in `cli.ts`.
+ *
+ * The prompt needs BOTH stdout and stdin to be terminals (`interactive`); the
+ * secret needs only stdout: stdin may be a here-doc while the person is still
+ * watching the terminal the secret lands in. The browser opener needs NEITHER —
+ * it is decided by `shouldOpenBrowser` (card eecc9d6f C1).
+ */
+export function wireDeps(io) {
+    const stdoutIsTTY = io.stdout.isTTY === true;
+    const interactive = stdoutIsTTY && io.stdin.isTTY === true;
+    // FLO-509: the in-place login countdown exists only when stdout is a terminal
+    // (the login lines go to stdout). On a pipe a redrawn line is just noise in a log.
+    const statusLine = stdoutIsTTY ? createStatusLine((text) => io.stdout.write(text)) : null;
+    const writer = createWriter({
+        out: (line) => {
+            statusLine?.settle();
+            io.log(line);
+        },
+        err: (line) => {
+            statusLine?.settle();
+            io.error(line);
+        },
+    });
+    const deps = {
+        env: io.env,
+        writer,
+        fetch: io.fetch,
+        sleep: io.sleep,
+        now: io.now,
+        nodeVersion: io.nodeVersion,
+        isOnPath: io.isOnPath,
+        version: io.version,
+        spawn: io.spawn,
+        fileExists: io.fileExists,
+        home: io.home,
+        platform: io.platform,
+        ...(statusLine === null ? {} : { progress: statusLine.progress }),
+        // `mcp print --reveal` is the ONE command allowed to put a token on stdout,
+        // and this is the fact it is allowed on. The sink settles a dangling
+        // countdown first so the secret never lands glued to a status line.
+        ...(stdoutIsTTY
+            ? {
+                reveal: (line) => {
+                    statusLine?.settle();
+                    io.stdout.write(line + "\n");
+                },
+            }
+            : {}),
+        // The browser opener is NOT gated on a terminal any more (card eecc9d6f C1).
+        // History: FLO-500 gated it on stdin+stdout TTYs after a piped probe popped
+        // a tab; that also starved every agent shell (Claude Code runs commands with
+        // no TTY on a person's own desktop), which is exactly where `login` is now
+        // run most. The rule is `shouldOpenBrowser`: `--no-open` (cli.ts), a CI
+        // environment, or a Linux box with no display keeps the browser shut.
+        ...(shouldOpenBrowser(io.env, io.platform) ? { openUrl: io.openUrl } : {}),
+        // The prompt stays gated on there being a terminal on BOTH ends.
+        // The question is redacted AND scrubbed HERE because readline writes it to
+        // stdout raw, around the writer — the prompt text is CLI-built (a path, a
+        // display name), but the guarantee should not depend on every future caller
+        // remembering. `printable`, not the writer's per-line scrub: a question is
+        // ONE line by construction, so a newline in a spliced display name is a
+        // forged line, not structure.
+        ...(interactive ? { ask: (question) => io.ask(printable(redact(question))) } : {}),
+    };
+    return { deps, statusLine };
+}
+/**
+ * C1 — may `login` open a browser on this machine? Yes, unless a CI job (`CI`
+ * set to anything non-empty — the convention GitHub Actions, GitLab and most
+ * runners follow) or Linux with neither `DISPLAY` nor `WAYLAND_DISPLAY` (an SSH
+ * session or a container: `xdg-open` there has no screen, or picks a text
+ * browser that takes over the terminal). `--no-open` is the person's override,
+ * applied in `cli.ts`. PURE, so the whole cross product is pinned in wiring.test.ts.
+ */
+export function shouldOpenBrowser(env, platform) {
+    const set = (name) => typeof env[name] === "string" && env[name].length > 0;
+    if (set("CI"))
+        return false;
+    if (platform === "linux" && !set("DISPLAY") && !set("WAYLAND_DISPLAY"))
+        return false;
+    return true;
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "flowsprite",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "type": "module",
   "description": "The Flowsprite CLI: log a terminal in to Flowsprite and drive workspace setup over the MCP endpoint. Zero runtime dependencies, node builtins only.",
   "license": "UNLICENSED",
   "homepage": "https://app.flowsprite.com/setup",
   "bin": {
-    "flowsprite": "./dist/bin.js"
+    "flowsprite": "dist/bin.js"
   },
   "engines": {
     "node": ">=20"