flowsprite 0.1.3 → 0.1.4

package/dist/sfCli.js

@@ -1,7 +1,22 @@
 /**
  * The pure half of `flowsprite connect salesforce --from-sf-cli <alias>`
- * (FLO-515): the alias rule, the `sf org display --verbose --json` envelope
- * parser, the remedies, and the allow-list projection of the door's reply.
+ * (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`
@@ -31,24 +46,40 @@ export const FROM_SF_CLI_EXCLUSIVE = "--from-sf-cli takes the org from the sf CL
 export function scrubForceUrls(text) {
     return text.replace(/force:\/\/\S*/g, "[sf auth url removed]");
 }
-const SF_CLIENT_ID = "PlatformCLI";
 const SF_URL_PREFIX = "force://PlatformCLI::";
 const ERROR_NAME_RE = /^[A-Za-z0-9_]{1,64}$/;
 /**
- * Read the `sf org display --verbose --json` envelope: `{status, result:{…}}`,
- * parsed from the first `{` because a CLI notice can precede the JSON on
- * stdout (measured: the update notice goes to stderr on sf 2.127 / 2.150, but
- * the setup skill body already parses from the first `{` for the other
- * configurations).
+ * 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 `NoAuthInfoFound` — 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. An `sf org login jwt` org has no `sfdxAuthUrl`, and an
- * auth file written before the CLI stored its client id yields
- * `force://:<token>@host` (empty client id); both are `no_url`.
+ * 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 parseSfOrgDisplay(stdout) {
+export function parseSfAuthUrl(stdout) {
     const start = stdout.indexOf("{");
     if (start < 0)
         return { ok: false, reason: "not_json" };
@@ -72,9 +103,6 @@ export function parseSfOrgDisplay(stdout) {
     const url = result.sfdxAuthUrl;
     if (typeof url !== "string" || !url.startsWith(SF_URL_PREFIX))
         return { ok: false, reason: "no_url" };
-    const clientId = typeof result.clientId === "string" ? result.clientId : "";
-    if (clientId !== SF_CLIENT_ID)
-        return { ok: false, reason: "client", clientId };
     return { ok: true, sfdxAuthUrl: url };
 }
 /** The `sf org login web` line for this alias — sandbox users need the host. */

package/dist/usage.js

@@ -1,59 +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).
+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.
-  connect github            Get a one-time link to install the GitHub app.
+                            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).
+                            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                      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.
-  --workspace <name>        login: 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                   login: skip the GitHub CLI and use the browser.
-  --sandbox                 setup / connect salesforce: use the sandbox login host.
-  --my-domain <host>        setup / connect salesforce: use this My Domain login host.
-  --from-sf-cli <alias>     connect salesforce: hand over the sf CLI's login for
-                            that alias instead of a browser link. Needs sf on
-                            PATH and a web login (not JWT).
-  --connection <id>         bind / sync: the Salesforce connection id.
-  --installation <number>   bind: the GitHub installation id.
-  --repo <owner/name>       bind: use a repository that already exists.
-  --create <name>           bind: create a new repository with this name, without
-                            asking. 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.3";
+export const VERSION = "0.1.4";

package/dist/wiring.js

@@ -14,9 +14,10 @@ import { printable, redact } from "./redact.js";
  *   through `log` (a separate function a caller could point anywhere). Its only
  *   reader is `mcpPrint` in `cli.ts`.
  *
- * The browser opener and the prompt need 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 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;
@@ -59,19 +60,37 @@ export function wireDeps(io) {
                 },
             }
             : {}),
-        // The browser opener and the prompt are BOTH gated on there being a terminal.
-        // History (measured 2026-09-15 at bin.ts, before this wiring existed,
-        // FLO-500): a non-interactive `login` (stdout piped, as in a CI job or a
-        // probe script) still popped a browser tab on this machine, because the
-        // opener was wired unconditionally. A process nobody is watching must not
-        // take over the screen of whoever happens to be at the machine.
+        // 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 ? { openUrl: io.openUrl, ask: (question) => io.ask(printable(redact(question))) } : {}),
+        ...(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,6 +1,6 @@
 {
   "name": "flowsprite",
-  "version": "0.1.3",
+  "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",