flowsprite 0.1.0

package/dist/setup.js

@@ -0,0 +1,216 @@
+import { toolJson } from "./mcpClient.js";
+/**
+ * The setup plane, driven from a terminal.
+ *
+ * THE ORDERING IS NOT RE-DERIVED HERE. `convex/mcpSetup.ts nextSetupAction` is
+ * the one home for "what is the next step", and `setup_status` returns its
+ * answer as `nextAction`. This module TRANSLATES that answer into a step this
+ * CLI can take; a second ladder computed from `workspace.salesforce.connected`
+ * and friends is exactly how the two start disagreeing.
+ */
+/** How often the link steps re-read `setup_status`, and for how long (AC5). */
+export const LINK_POLL_INTERVAL_MS = 5_000;
+export const LINK_POLL_MAX_MS = 10 * 60 * 1000;
+/** `nextAction.tool` -> the step this CLI knows how to take. */
+const TOOL_TO_STEP = {
+    setup_connect_salesforce: "connect_salesforce",
+    setup_connect_github: "connect_github",
+    setup_bind_repo: "bind_repo",
+    sfdc_trigger_sync: "first_sync",
+};
+/**
+ * The two shape readers every module that touches a tool payload needs.
+ *
+ * ONE HOME, exported, because `status.ts` and `cli.ts` each grew their own and
+ * two copies of "is this an object" is how one of them starts disagreeing about
+ * an array.
+ */
+export function asObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** The objects in an array field, dropping anything that is not one. */
+export function asArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const v of value) {
+        const o = asObject(v);
+        if (o !== null)
+            out.push(o);
+    }
+    return out;
+}
+/**
+ * PURE. Given whatever `setup_status` returned, name the next step.
+ *
+ * FAIL-CLOSED DIRECTION IS `web_only`, NOT `done`. A payload this function
+ * cannot read — the tool's `null` (suspended tenant, or a session whose subject
+ * is no longer an active member), a `nextAction` naming a tool no version of
+ * this CLI drives, or `available: false` — must never be reported as "nothing
+ * left to do". Sending someone to /getting-started when setup is in fact
+ * finished costs them a page load; telling them setup is finished when it is not
+ * costs them the rest of the session.
+ */
+export function planNextStep(status) {
+    const obj = asObject(status);
+    const fallback = "Finish setting this workspace up in the browser, at /getting-started.";
+    if (obj === null)
+        return { kind: "web_only", text: fallback };
+    // `nextAction: null` is the server saying the ladder is EXHAUSTED — the one
+    // shape that legitimately means done. It is distinguished from an absent key,
+    // which means this payload is not a setup_status at all.
+    if (obj.nextAction === null)
+        return { kind: "done", text: "Setup is complete." };
+    const next = asObject(obj.nextAction);
+    if (next === null)
+        return { kind: "web_only", text: fallback };
+    const text = typeof next.text === "string" && next.text.length > 0 ? next.text : fallback;
+    // `available: false` means the step has no tool on this endpoint; the server
+    // already appended where to do it instead, so its text is the whole answer.
+    if (next.available !== true)
+        return { kind: "web_only", text };
+    const tool = typeof next.tool === "string" ? next.tool : "";
+    const kind = Object.prototype.hasOwnProperty.call(TOOL_TO_STEP, tool)
+        ? TOOL_TO_STEP[tool]
+        : undefined;
+    if (kind === undefined)
+        return { kind: "web_only", text };
+    return { kind, text };
+}
+/**
+ * The connections the SERVER'S CURRENT RUNG is unsatisfied about.
+ *
+ * ⚠️ THE LADDER'S RUNGS ARE LIST-WIDE AND THIS CLI'S ACTIONS ARE PER-CONNECTION.
+ * `nextSetupAction` (`convex/mcpSetup.ts`) returns `setup_bind_repo` while
+ * `connections.some((c) => !c.hasBinding)` and `sfdc_trigger_sync` while
+ * `connections.some((c) => !c.hasSyncJob)` — deliberately, so an org with one
+ * bound and one unbound connection stays on the rung until EVERY connection is
+ * done. A caller that binds ONE connection and re-reads therefore gets the SAME
+ * rung back, which is not a failure and is not progress either.
+ *
+ * MEASURED at fd0f434: `setup` against a two-connection workspace made 201
+ * `setup_status` + 200 `setup_bind_repo` calls before an external cap stopped it,
+ * every one of those binds SUPERSEDING the binding it had just made and clearing
+ * that connection's data-export consent. So the rung's SUBJECT has to be derived
+ * here, and the loop in `cli.ts` has to prove the ladder moved.
+ *
+ * Returns the ids in payload order; an empty array means the payload does not
+ * explain the rung, which the caller treats as "cannot act", never as "any
+ * connection will do".
+ */
+export function rungConnectionIds(status, kind) {
+    const root = asObject(status);
+    if (root === null)
+        return [];
+    const term = kind === "bind_repo"
+        ? (c) => c.hasBinding !== true
+        : kind === "first_sync"
+            ? (c) => c.hasSyncJob !== true
+            : null;
+    if (term === null)
+        return [];
+    const out = [];
+    for (const c of asArray(root.connections)) {
+        if (term(c) && typeof c.id === "string" && c.id.length > 0)
+            out.push(c.id);
+    }
+    return out;
+}
+/**
+ * Map the bind flags onto `setup_bind_repo`'s schema (`convex/mcpRegistry.ts`).
+ *
+ * `create` ALWAYS sends `isPrivate: true`, and there is no way to ask for a
+ * public one. That is not this CLI being opinionated: the tool "is refused" for
+ * anything else, because a public repo's GitHub Actions logs are world-readable.
+ * A flag that can only hold one value is not a choice to offer, so there is no
+ * `--private`; `--create` says it, and the usage text says so.
+ */
+export function planBindArgs(input) {
+    const connection = typeof input.connection === "string" ? input.connection.trim() : "";
+    if (connection.length === 0) {
+        return { ok: false, message: "bind needs --connection <salesforce connection id>. `flowsprite status` lists them." };
+    }
+    const rawInstallation = input.installation;
+    const installationId = typeof rawInstallation === "number"
+        ? rawInstallation
+        : typeof rawInstallation === "string" && /^[0-9]+$/.test(rawInstallation.trim())
+            ? Number(rawInstallation.trim())
+            : null;
+    if (installationId === null) {
+        return {
+            ok: false,
+            message: "bind needs --installation <number>, the numeric GitHub installation id. `flowsprite status` lists them.",
+        };
+    }
+    const wantsRepo = typeof input.repo === "string" && input.repo.length > 0;
+    const wantsCreate = typeof input.create === "string" && input.create.length > 0;
+    if (wantsRepo === wantsCreate) {
+        return {
+            ok: false,
+            message: wantsRepo
+                ? "bind takes either --repo owner/name or --create name, not both."
+                : "bind needs either --repo owner/name (bind a repo that exists) or --create name (make a new private one).",
+        };
+    }
+    if (wantsCreate) {
+        return {
+            ok: true,
+            args: { sandboxId: connection, installationId, repoName: input.create, create: true, isPrivate: true },
+        };
+    }
+    // `owner/name`, split on the FIRST slash only — a GitHub repo name cannot
+    // contain one, so anything after a second slash is a typo, not a path.
+    const parts = input.repo.split("/");
+    if (parts.length !== 2 || parts[0].length === 0 || parts[1].length === 0) {
+        return { ok: false, message: "--repo wants owner/name, for example acme/salesforce-metadata." };
+    }
+    return {
+        ok: true,
+        args: { sandboxId: connection, installationId, repoOwner: parts[0], repoName: parts[1] },
+    };
+}
+/**
+ * Run one browser-leg step: mint the link, show it, then watch `setup_status`
+ * until the step is no longer the next one.
+ *
+ * THE STOP CONDITIONS ARE THREE AND THEY ARE DIFFERENT. The link's own
+ * `expiresAt` passing means the person must be handed a fresh link (this returns
+ * `expired` and says so); the overall budget running out means the CLI stops
+ * waiting but the link may still be good (`timeout`); and the step completing is
+ * read from the PLANNER moving on, not from a field this module interprets
+ * itself.
+ */
+export async function runLinkStep(deps, tool, args, stepKind) {
+    const minted = await deps.client.callTool(tool, args);
+    if (!minted.ok)
+        return { kind: "failed", message: minted.message };
+    const payload = asObject(toolJson(minted));
+    if (payload === null || typeof payload.url !== "string") {
+        return { kind: "failed", message: `${tool} did not return a link.` };
+    }
+    const url = payload.url;
+    const expiresAt = typeof payload.expiresAt === "number" ? payload.expiresAt : null;
+    deps.writer.out(`Open this link in a browser where you are signed in to Flowsprite:`);
+    deps.writer.out(`  ${url}`);
+    if (typeof payload.instructions === "string")
+        deps.writer.out(payload.instructions);
+    deps.writer.out("Waiting for you to finish in the browser...");
+    const deadline = deps.now() + LINK_POLL_MAX_MS;
+    for (;;) {
+        await deps.sleep(LINK_POLL_INTERVAL_MS);
+        const status = await deps.client.callTool("setup_status", {});
+        if (!status.ok)
+            return { kind: "failed", message: status.message };
+        if (planNextStep(toolJson(status)).kind !== stepKind)
+            return { kind: "done" };
+        // The link check comes AFTER the status read, so a link that expired in the
+        // same tick as the step completing is reported as the completion it was.
+        const now = deps.now();
+        if (expiresAt !== null && now >= expiresAt)
+            return { kind: "expired" };
+        if (now >= deadline)
+            return { kind: "timeout" };
+    }
+}

package/dist/status.js

@@ -0,0 +1,92 @@
+import { asArray, asObject, planNextStep } from "./setup.js";
+/**
+ * Render a `setup_status` payload as plain text.
+ *
+ * READ DEFENSIVELY, FIELD BY FIELD. The payload is the tool's, not this
+ * module's: a missing section prints as "not reported" rather than throwing, so
+ * a server that gains or loses a field cannot turn `flowsprite status` into a
+ * stack trace. `--json` does not come through here at all — the machine form is
+ * the payload itself, unmodified, so a consumer is never reading this file's
+ * idea of it.
+ */
+const obj = asObject;
+const arr = asArray;
+function str(value, fallback = "?") {
+    return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+function yesNo(value) {
+    return value === true ? "yes" : value === false ? "no" : "not reported";
+}
+/**
+ * A `pendingLinks` expiry, as text.
+ *
+ * `expiresAt` was the ONE field this renderer read without a helper, and
+ * `new Date(Number(x)).toISOString()` THROWS `RangeError: Invalid time value` on
+ * anything that is not a finite epoch — measured: `undefined`, an ISO string, and
+ * `Infinity` each crashed `flowsprite status` outright. Everything else here
+ * degrades to "not reported" when the payload surprises it, and so does this: a
+ * status command that cannot survive one odd field is not a status command.
+ * `Number.isFinite` is the whole rule (it is false for NaN and both infinities),
+ * plus a range check, because a finite number outside the Date epoch range
+ * (|t| > 8.64e15) throws exactly the same way.
+ */
+const MAX_EPOCH_MS = 8.64e15;
+function expiryText(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || Math.abs(value) > MAX_EPOCH_MS) {
+        return "not reported";
+    }
+    return new Date(value).toISOString();
+}
+export function renderStatus(payload) {
+    const root = obj(payload);
+    if (root === null) {
+        return [
+            "Flowsprite could not read this workspace's setup.",
+            "That is what it answers when the workspace is suspended, or when your membership is no longer active.",
+        ];
+    }
+    const lines = [];
+    const workspace = obj(root.workspace);
+    const salesforce = obj(workspace?.salesforce);
+    const github = obj(workspace?.github);
+    const personal = obj(obj(root.personal)?.mcp);
+    const progress = obj(root.progress);
+    lines.push("Checklist");
+    lines.push(`  Salesforce connected: ${yesNo(salesforce?.connected)}${salesforce?.summary ? ` (${str(salesforce.summary)})` : ""}`);
+    lines.push(`  GitHub connected:     ${yesNo(github?.connected)}${github?.summary ? ` (${str(github.summary)})` : ""}`);
+    lines.push(`  Your MCP access:      ${str(personal?.state, "not reported")}`);
+    if (progress && typeof progress.done === "number" && typeof progress.total === "number") {
+        lines.push(`  Progress:             ${progress.done}/${progress.total}`);
+    }
+    lines.push(`  Complete:             ${yesNo(root.complete)}`);
+    const connections = arr(root.connections);
+    lines.push("", `Salesforce connections (${connections.length})`);
+    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)}`);
+    }
+    const installations = arr(root.installations);
+    lines.push("", `GitHub installations (${installations.length})`);
+    if (installations.length === 0)
+        lines.push("  none");
+    for (const i of installations) {
+        const repos = arr(i.repos).map((r) => str(r.fullName));
+        lines.push(`  ${String(i.installationId ?? "?")}  @${str(i.accountLogin)}  [${str(i.accountType)}]  repos listed: ${repos.length}`);
+        // The bind step needs these names, and a truncated list would make a repo
+        // that IS bindable read as absent — so every one is printed, one per line.
+        for (const name of repos)
+            lines.push(`      ${name}`);
+    }
+    const pending = arr(root.pendingLinks);
+    if (pending.length > 0) {
+        lines.push("", `Setup links still open (${pending.length})`);
+        for (const p of pending) {
+            lines.push(`  ${str(p.purpose)} — expires ${expiryText(p.expiresAt)}`);
+        }
+    }
+    const step = planNextStep(root);
+    lines.push("", "Next step");
+    lines.push(`  ${step.text}`);
+    return lines;
+}

package/dist/usage.js

@@ -0,0 +1,54 @@
+/** The usage text, as data, so `--help` and every exit-2 refusal print the same thing. */
+export const USAGE = `flowsprite — set up and drive a Flowsprite workspace from a terminal.
+
+Usage: flowsprite [command] [options]
+
+Commands:
+  setup                     Run the whole setup ladder (the default).
+  login                     Log this terminal in with a device code.
+  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.
+  bind                      Bind a GitHub repo to a Salesforce connection. With no
+                            --repo/--create it offers the repos setup_status lists.
+  sync                      Start a metadata sync and show the recent sync log.
+  doctor                    Check node, the endpoint, the credential, and sf/gh.
+  mcp install               Point an AI client at this workspace's MCP endpoint.
+  mcp print                 Show the config snippet for a client, token hidden.
+
+Options:
+  --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.
+
+Environment:
+  FLOWSPRITE_ENDPOINT       Same as --endpoint.
+  FLOWSPRITE_TOKEN          Same as --token.
+  FLOWSPRITE_CONFIG_DIR     Where credentials.json lives (default
+                            $XDG_CONFIG_HOME/flowsprite or ~/.config/flowsprite).
+
+The credential file holds one token per endpoint, mode 0600 in a 0700 directory.
+mcp install backs a client config up once before its first write and changes
+only the flowsprite entry. The ONLY command that prints a token is
+mcp print --reveal, and only at a terminal.`;

package/dist/version.js

@@ -0,0 +1,10 @@
+/**
+ * The CLI's version, as one exported constant.
+ *
+ * NOT read from package.json at runtime: `dist/bin.js` sits one directory below
+ * the manifest, and an installed package's layout is npm's business, not ours —
+ * a path walk is a second authority that can drift. The constant and the
+ * 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";

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "flowsprite",
+  "version": "0.1.0",
+  "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"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  }
+}