flowsprite 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+# flowsprite — the Flowsprite CLI
+
+Log a terminal in to Flowsprite and drive workspace setup from the command line.
+Zero runtime dependencies: node builtins only.
+
+## Install
+
+Node 20 or newer. Nothing to install — `npx` fetches it:
+
+    npx flowsprite --help
+    npx flowsprite            # runs `setup`, the default command
+
+Or install it once: `npm i -g flowsprite`, then `flowsprite …`. The package is
+`flowsprite` on npm (unscoped, UNLICENSED — proprietary; the source lives in the
+Flowsprite repo). To run an unreleased change from a checkout of this repo:
+
+    pnpm exec tsc -p cli/tsconfig.json
+    node cli/dist/bin.js --help
+
+## Commands
+
+| command | what it does |
+| --- | --- |
+| `setup` (default) | Runs the whole ladder: log in if needed, then connect Salesforce, connect GitHub, bind a repo and start the first sync, in the order the server asks for them. It needs **no flags** — where the workspace leaves a choice (which connection, which installation, which repository) it asks at a terminal and, through a pipe, lists the options and stops rather than guessing. |
+| `login` | Device-code login. Prints a code and a URL; approve it in a browser. `--token <t>` skips the loop and uses that token instead (add `--save` to store it). |
+| `logout` | Removes this endpoint's entry from the credentials file. Other endpoints keep theirs. |
+| `status` | The setup checklist, the Salesforce connections, the GitHub installations and the next step. `--json` prints the tool's payload unmodified. |
+| `connect salesforce` | Mints a one-time browser link (`--sandbox`, `--my-domain <host>`), prints it, and watches until the connection lands. |
+| `connect github` | The same for installing the GitHub app. |
+| `bind` | Binds a repo to a Salesforce connection. With no flags it offers the connections, installations and repositories `setup_status` already lists; `--connection <id>`, `--installation <n>`, `--repo owner/name` and `--create <name>` pin any of those for a non-interactive run. `--create` always makes a **private** repo — Flowsprite refuses to mirror into a public one. |
+| `sync` | `sfdc_trigger_sync` then `sfdc_sync_logs` for `--connection <id>`. |
+| `doctor` | node version, endpoint reachability, whether a credential exists for this endpoint (never its value), and whether `sf` and `gh` are on PATH. |
+| `mcp install` | Points an AI client at this workspace's MCP endpoint. `--client claude-code\|codex\|claude-desktop\|cursor`; with no `--client` it offers the clients it detects and names the rest as print-only. Runs the client's own registration command where there is one (`claude mcp add`, `codex mcp add`), and otherwise writes the client's config file — backed up once, one entry changed, `0600`. `--print` shows what it would do and changes nothing; `--force` replaces an existing `flowsprite` entry (at a terminal it asks instead); `--token-env NAME` tells codex which variable holds the bearer. |
+| `mcp print` | The config snippet for a client, with `<YOUR_TOKEN>` where the bearer goes — no credential needed. `--client <name>` for one, nothing for all four, `--json` for `{client, kind, path, command, snippet}`. `--reveal` substitutes the real token and runs **only at a terminal**. |
+
+`--help` and `--version` exit 0. An unknown command or an unknown flag — single- or
+double-dash — prints the usage and exits **2**. A command that ran and was refused
+exits **1**.
+
+## Environment
+
+| variable | meaning |
+| --- | --- |
+| `FLOWSPRITE_ENDPOINT` | The Flowsprite origin. Same as `--endpoint`. Default `https://app.flowsprite.com`. Must be a bare origin: scheme + host, no userinfo, path, query or fragment. Plain `http://` is accepted **only** for `localhost`, `127.0.0.1` and `[::1]` — every request carries an access token, so anything else must be `https://`. |
+| `FLOWSPRITE_TOKEN` | A token to use instead of the stored credential. Same as `--token`. |
+| `FLOWSPRITE_CONFIG_DIR` | Where `credentials.json` lives. Otherwise `$XDG_CONFIG_HOME/flowsprite`, otherwise `~/.config/flowsprite`. |
+
+Precedence is flag > environment > stored credential, for both the endpoint and the token.
+
+## Where the credential lives
+
+One `fp_user_` token per endpoint, in `credentials.json` inside the config
+directory above: the file is written `0600` (temp file + rename, never a partial
+read) inside a `0700` directory. A missing or malformed file reads as "no
+credentials" rather than a crash.
+
+`setup` stops rather than repeating itself: Flowsprite's setup steps are
+list-wide ("some connection has no repo"), so if a step reports success and the
+checklist does not move, the CLI says which step and stops instead of running it
+again.
+
+**One command prints a token, and only at a terminal: `mcp print --reveal`.**
+Everything else — every success line, every refusal, a failing client command's
+own stderr — carries `<YOUR_TOKEN>` or nothing, and no line ever carries a command
+line. Every line leaves this process through one writer that rewrites any
+`fp_user_`/`fp_live_` value to its prefix plus the last four characters, so a
+token cannot reach a scrollback even from an error string that quoted one.
+
+## What `mcp install` touches
+
+| client | route | file |
+| --- | --- | --- |
+| `claude-code` | `claude mcp add --transport http … --scope user` when `claude` is on PATH, else the file | `$CLAUDE_CONFIG_DIR/.claude.json`, else `~/.claude.json` |
+| `codex` | `codex mcp add --url … --bearer-token-env-var NAME` when `codex` is on PATH, else a printed TOML snippet (this CLI does not edit TOML) | `$CODEX_HOME/config.toml`, else `~/.codex/config.toml` |
+| `claude-desktop` | the file, always — it takes a stdio command, so the entry runs `npx -y mcp-remote@<pinned>` | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), `%APPDATA%/Claude/…`, `~/.config/Claude/…` |
+| `cursor` | the file, but only when it already exists; otherwise a printed snippet | `~/.cursor/mcp.json` |
+
+A file write **refuses rather than replaces** anything it cannot preserve: a
+symlinked config, a file that is not valid JSON, or a root that is not a JSON
+object. It backs the file up once — `<config>.flowsprite-backup-<epoch>`, kept
+forever, never overwritten — and changes only `mcpServers.flowsprite`.
+
+**Where the token goes.** Into the config file (`0600`), or into the client's own
+command. `codex` is told an environment-variable **name**, never the value. The
+`claude` command is the one exception: the bearer is one of its arguments, so it
+is briefly visible to a local `ps` on your own machine — that is the cost of
+letting the client own its file format instead of editing 348 KB of someone
+else's live state.
+
+## Testing it by hand
+
+`docs/E2E-TESTING-CLI-FLOW.md` is the one-sitting pass of the whole terminal door — every
+command above, in journey order, with the exact lines to expect and the results table.

package/dist/bin.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline/promises";
+import { main } from "./cli.js";
+import { isOnPath } from "./doctor.js";
+import { createWriter } from "./output.js";
+import { redact } from "./redact.js";
+import { VERSION } from "./version.js";
+/**
+ * THE ONLY FILE THAT NAMES A REAL EFFECT. Everything under it takes its fetch,
+ * clock, sleep, environment, writer, PATH probe and prompt as arguments, so the
+ * whole CLI is drivable in a test without a network, a home directory or a TTY.
+ */
+/**
+ * Best effort, and deliberately fire-and-forget.
+ *
+ * ARGV ARRAY, `shell: false` (the default), and a FIXED command name — the URL
+ * is an argument, never part of a command string, so a crafted URL has no shell
+ * to reach. `detached` + `unref` so an opener that outlives the login does not
+ * hold this process open, and `ignore` for stdio so a GUI launcher's chatter
+ * never lands in the middle of the login output.
+ */
+function openUrl(url) {
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer" : "xdg-open";
+    try {
+        const child = spawn(command, [url], { shell: false, stdio: "ignore", detached: true });
+        // An opener that is not installed raises `error` asynchronously; without a
+        // listener node turns that into an unhandled exception and kills the login.
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // Same reason: a browser that will not open is a convenience lost, never a
+        // login lost. The URL is already on screen.
+    }
+}
+const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true;
+/**
+ * Run a client's own registration command.
+ *
+ * ARGV ARRAY AND `shell: false` — the same rule `openUrl` follows above, and it
+ * matters more here: one of these arguments is `Authorization: Bearer <token>`.
+ * With a shell there would be quoting to get wrong; without one there is nothing
+ * to quote. `stdio` is piped rather than inherited so the child's stderr comes
+ * back as a value this CLI can redact before printing, instead of going straight
+ * to the terminal around the writer.
+ */
+function runCommand(command, args) {
+    const result = spawnSync(command, args, {
+        shell: false,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return {
+        status: result.status,
+        signal: result.signal,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        error: result.error,
+    };
+}
+const writer = createWriter({
+    out: (line) => console.log(line),
+    err: (line) => console.error(line),
+});
+/**
+ * THE LAST LINE OF DEFENCE: no unexpected throw reaches a person as a stack
+ * trace.
+ *
+ * A stack trace is a bad answer twice over. It is unreadable advice — the
+ * measured case was a credential write to an unwritable directory, which
+ * surfaced as `Error: ENOENT: no such file or directory, mkdir '/proc/…'` with no
+ * exit code set at all — and it is an uncontrolled OUTPUT PATH: node prints it
+ * itself, around the writer, so every redaction this CLI does is bypassed by the
+ * one message nobody wrote on purpose. So the message is redacted explicitly
+ * here, the frames are dropped, and the exit code is 1.
+ *
+ * Commands do NOT rely on this: every expected failure is a typed result with its
+ * own sentence and exit code. This catches what nobody predicted.
+ */
+let rc;
+try {
+    rc = await main(process.argv.slice(2), {
+        env: process.env,
+        writer,
+        fetch: globalThis.fetch,
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        now: () => Date.now(),
+        nodeVersion: process.version,
+        isOnPath,
+        version: VERSION,
+        spawn: runCommand,
+        fileExists: existsSync,
+        // `mcp print --reveal` is the ONE command allowed to put a token on stdout,
+        // and this is the fact it is allowed on. stdout only: stdin may be a here-doc
+        // while the person is still watching the terminal the secret would land in.
+        isTTY: process.stdout.isTTY === true,
+        home: homedir(),
+        platform: process.platform,
+        // The browser opener and the prompt are BOTH gated on there being a terminal.
+        // Measured 2026-09-15: 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.
+        ...(interactive
+            ? {
+                openUrl,
+                ask: async (question) => {
+                    const rl = createInterface({ input: process.stdin, output: process.stdout });
+                    try {
+                        return await rl.question(question);
+                    }
+                    finally {
+                        rl.close();
+                    }
+                },
+            }
+            : {}),
+    });
+}
+catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`flowsprite: ${redact(message.split("\n")[0] ?? "unexpected error")}`);
+    rc = 1;
+}
+process.exitCode = rc;