flowsprite 0.1.0

package/dist/credentials.js

@@ -0,0 +1,195 @@
+import { randomUUID } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const CREDENTIALS_FILE = "credentials.json";
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+/**
+ * Where the store lives, in precedence order: an explicit
+ * `FLOWSPRITE_CONFIG_DIR`, else `$XDG_CONFIG_HOME/flowsprite`, else
+ * `~/.config/flowsprite`. `env` is injected so a test never touches a real home
+ * directory.
+ */
+export function credentialsDir(env, home = homedir()) {
+    const explicit = env.FLOWSPRITE_CONFIG_DIR;
+    if (typeof explicit === "string" && explicit.length > 0)
+        return explicit;
+    const xdg = env.XDG_CONFIG_HOME;
+    if (typeof xdg === "string" && xdg.length > 0)
+        return join(xdg, "flowsprite");
+    return join(home, ".config", "flowsprite");
+}
+export function credentialsPath(env, home) {
+    return join(credentialsDir(env, home), CREDENTIALS_FILE);
+}
+/**
+ * TOLERANT BY CONTRACT: a missing file, an unreadable one, invalid JSON, or a
+ * JSON value that is not an object all read as "no credentials". A CLI whose
+ * first act is to crash on a file the person cannot see is a CLI they cannot
+ * recover from — and the recovery (`flowsprite login`) overwrites the file
+ * anyway. Entries that are not well-shaped credentials are dropped rather than
+ * returned, so no caller has to re-check a token's type.
+ */
+export function readCredentials(env, home) {
+    let raw;
+    try {
+        raw = readFileSync(credentialsPath(env, home), "utf8");
+    }
+    catch {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return {};
+    const store = {};
+    for (const [origin, value] of Object.entries(parsed)) {
+        // SHAPE FIRST, then field types: a non-object entry would otherwise reach a
+        // template as "[object Object]" or throw on a property read.
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            continue;
+        const v = value;
+        if (typeof v.token !== "string" || v.token.length === 0)
+            continue;
+        if (typeof v.orgId !== "string" || typeof v.userId !== "string")
+            continue;
+        if (typeof v.mcpEndpoint !== "string")
+            continue;
+        store[origin] = {
+            token: v.token,
+            orgId: v.orgId,
+            userId: v.userId,
+            mcpEndpoint: v.mcpEndpoint,
+            savedAt: typeof v.savedAt === "number" ? v.savedAt : 0,
+        };
+    }
+    return store;
+}
+/**
+ * ATOMIC, EXCLUSIVE, AND 0600 — in that order of importance.
+ *
+ * THE TEMP FILE IS CREATED WITH `flag: "wx"`, AND THAT IS THE SECURITY PROPERTY,
+ * not the mode. `wx` is `O_CREAT | O_EXCL | O_WRONLY`, which the kernel refuses
+ * (EEXIST) on anything already at that path INCLUDING A SYMLINK — it never
+ * follows one. Measured at fd0f434, before this flag existed: a `credentials.json.tmp`
+ * planted as a symlink to a 0644 file elsewhere took the write, so the token
+ * landed in the attacker's file, that file was chmod'd to 0600, and
+ * `credentials.json` then BECAME the symlink. `O_EXCL` is what closes that; a
+ * mode argument never could, because the mode applies to a file being created
+ * and the old write was not creating one.
+ *
+ * THE NAME IS UNIQUE PER WRITE (`pid` + a random uuid). A fixed `.tmp` is both
+ * the thing an attacker plants and the thing two concurrent `flowsprite` runs
+ * collide on; with `wx` a fixed name would turn that collision into a hard
+ * failure rather than a silent overwrite, which is worse than not colliding.
+ *
+ * The suffix is a PARAMETER with a random default, for one reason: the two
+ * defences above are independent, and with a random name a test can never reach
+ * the `wx` one — the planted path is simply never used, so dropping `flag: "wx"`
+ * stays green. Passing a known suffix lets a test pre-create the EXACT path the
+ * write will use and assert the refusal. Nothing in this package passes it.
+ *
+ * THE MODE IS RIGHT FROM THE FIRST BYTE, and now really is. `writeFileSync`'s
+ * `mode` applies at creation, and because `wx` guarantees this call is the
+ * creator, there is no pre-existing-file case left in which it does not apply —
+ * that was the hole the old fixed-name version had (a pre-existing 0644 `.tmp`
+ * kept 0644 until the final chmod, so the docstring's "never world-readable even
+ * for an instant" was false of exactly the file it was describing).
+ *
+ * `renameSync` is the atomic swap (same directory, so same filesystem). The
+ * `chmodSync` AFTER it is for a DIFFERENT case the create mode cannot reach: a
+ * `credentials.json` that already existed with a wider mode, which rename does
+ * not change. The two are not redundant — see the all-terms bite recorded for
+ * this function in EVIDENCE-FLO-500.md.
+ *
+ * The directory is created 0700 — a 0600 file in a 0755 directory still leaks
+ * its existence and its size to every local account. `mkdirSync`'s `mode` is
+ * masked by the process umask, so it is asserted with an explicit `chmodSync`
+ * rather than trusted from the create.
+ */
+/**
+ * The temp path a write will use, given the target and a unique suffix.
+ * Exported so a test can pre-create it; see `writeStore`'s docstring.
+ */
+export function tempPathFor(target, unique) {
+    return `${target}.${unique}.tmp`;
+}
+/** A suffix no other process and no attacker can predict. */
+function freshSuffix() {
+    return `${process.pid}.${randomUUID()}`;
+}
+/**
+ * The write itself, as the ONE primitive — everything the docstring above argues
+ * about `wx`, the unique name, the create mode and the post-rename `chmod` lives
+ * here and nowhere else.
+ *
+ * It is exported because `mcpConfig.ts` writes a second kind of token-bearing
+ * file (a client's MCP config) and a second copy of this sequence is how one of
+ * them loses `wx` in a later edit. The caller supplies the mode, because a
+ * client config may legitimately be stricter than 0600 and the credential store
+ * never is.
+ */
+export function writeFileAtomic(path, contents, mode, unique = freshSuffix()) {
+    const tmp = tempPathFor(path, unique);
+    writeFileSync(tmp, contents, { flag: "wx", mode });
+    try {
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        // Leave nothing half-written behind: a surviving temp file holds a live
+        // token at a path nothing will ever clean up.
+        rmSync(tmp, { force: true });
+        throw err;
+    }
+    chmodSync(path, mode);
+}
+function writeStore(env, store, home, unique = freshSuffix()) {
+    const dir = credentialsDir(env, home);
+    mkdirSync(dir, { recursive: true, mode: DIR_MODE });
+    chmodSync(dir, DIR_MODE);
+    writeFileAtomic(credentialsPath(env, home), `${JSON.stringify(store, null, 2)}\n`, FILE_MODE, unique);
+}
+export function writeCredential(env, origin, cred, home, 
+/** Test seam only — see `writeStore`. Every caller in this package omits it. */
+unique) {
+    const store = readCredentials(env, home);
+    store[origin] = cred;
+    writeStore(env, store, home, unique ?? freshSuffix());
+}
+/**
+ * Remove ONE origin's entry. Returns whether there was one, so `logout` can say
+ * "you were not logged in there" instead of claiming a removal it did not make.
+ * Other origins' entries survive: this is the whole reason the file is keyed.
+ */
+export function deleteCredential(env, origin, home) {
+    const store = readCredentials(env, home);
+    if (!Object.prototype.hasOwnProperty.call(store, origin))
+        return false;
+    delete store[origin];
+    writeStore(env, store, home);
+    return true;
+}
+/**
+ * Which token this invocation uses: an explicit `--token`, else
+ * `FLOWSPRITE_TOKEN`, else the credential stored for this origin. The stored one
+ * is LAST so that a one-off token on the command line never has to fight a stale
+ * login, and so CI can set an env var without writing to a home directory.
+ */
+export function resolveToken(input) {
+    if (typeof input.flag === "string" && input.flag.length > 0) {
+        return { token: input.flag, source: "--token" };
+    }
+    if (typeof input.env === "string" && input.env.length > 0) {
+        return { token: input.env, source: "FLOWSPRITE_TOKEN" };
+    }
+    if (typeof input.stored === "string" && input.stored.length > 0) {
+        return { token: input.stored, source: "stored" };
+    }
+    return null;
+}

package/dist/doctor.js

@@ -0,0 +1,39 @@
+import { spawnSync } from "node:child_process";
+/**
+ * `flowsprite doctor` — what is wrong before anything else is tried.
+ *
+ * THE PROBE IS INJECTED so the formatter is testable without a network, a PATH
+ * or a child process; `realProbe` below is the one place any of those are
+ * touched.
+ */
+/** The major this package declares in `engines` — one authority, read by both halves. */
+export const MIN_NODE_MAJOR = 20;
+export function nodeMajor(version) {
+    const m = /^v?(\d+)\./.exec(version);
+    return m ? Number(m[1]) : 0;
+}
+export function formatDoctor(report) {
+    const mark = (ok) => (ok ? "ok  " : "FAIL");
+    return [
+        `${mark(report.nodeOk)} node ${report.nodeVersion} (needs >= ${MIN_NODE_MAJOR})`,
+        `${mark(report.endpointReachable)} endpoint ${report.endpoint} — ${report.endpointDetail}`,
+        `${mark(report.hasCredential)} credential for ${report.endpoint} ${report.hasCredential ? "found" : "not found — run `flowsprite login`"} (${report.credentialsPath})`,
+        `${report.sfOnPath ? "ok  " : "note"} sf on PATH: ${report.sfOnPath ? "yes" : "no (only needed for Salesforce CLI work)"}`,
+        `${report.ghOnPath ? "ok  " : "note"} gh on PATH: ${report.ghOnPath ? "yes" : "no (only needed for GitHub CLI work)"}`,
+    ];
+}
+/**
+ * Is `name` an executable this shell could run?
+ *
+ * NEVER `command -v` THROUGH A SHELL. `spawnSync(name, ["--version"])` with the
+ * default `shell: false` passes the name as argv[0] to execvp — there is no
+ * string for a crafted value to break out of. ENOENT is the absence signal; a
+ * non-zero exit is NOT (a binary that exists and dislikes `--version` is still
+ * on PATH).
+ */
+export function isOnPath(name) {
+    const res = spawnSync(name, ["--version"], { shell: false, stdio: "ignore" });
+    if (res.error && res.error.code === "ENOENT")
+        return false;
+    return res.error === undefined || res.error === null;
+}

package/dist/endpoint.js

@@ -0,0 +1,72 @@
+/**
+ * Which Flowsprite deployment this invocation talks to.
+ *
+ * THE BARE-ORIGIN RULE IS RE-STATED HERE, NOT IMPORTED. The repo's authority for
+ * it is `requireAppOrigin` in `convex/mcpSetup.ts` — unexported code inside the
+ * Convex isolate, which a zero-dependency node package cannot reach. This is a
+ * deliberate textual mirror of that paragraph, for the same reason it gives: the
+ * value is CONCATENATED with a path (`/api/mcp`, `/api/cli/auth/start`), so an
+ * origin carrying a path, a query or a fragment produces a URL that looks right
+ * and cannot work, and one carrying userinfo hands credentials to whatever reads
+ * the terminal. A trailing slash is accepted because `new URL("https://x/")`
+ * has pathname `"/"` — that IS the canonical origin, not a path.
+ *
+ * ONE RULE THIS CLI ADDS ON TOP: `http:` is accepted ONLY for loopback. Every
+ * request built from this origin carries an `fp_user_` bearer, and plaintext
+ * http to anything off this machine puts that bearer on the wire for whoever is
+ * on the path. `http://localhost:3000` is the dev server and is the whole reason
+ * `http:` is allowed at all, so the exception is an ALLOW-LIST of the three
+ * spellings of this machine — a deny-list would default every new host into the
+ * plaintext case, which is the wrong direction for a credential.
+ */
+export const DEFAULT_ENDPOINT = "https://app.flowsprite.com";
+/** The three spellings of this machine, the only hosts `http:` is allowed for. */
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/**
+ * THE REFUSAL NEVER ECHOES THE VALUE — not the userinfo, not the host, not a
+ * "cleaned" version of it. Written as a structural rule rather than a filter for
+ * credential-looking parts: a filter is an enumeration of what looks like a
+ * secret, and the one it forgets is the one that reaches the screen (and a
+ * terminal scrollback, and a pasted bug report). The source name plus the rule
+ * is everything the person needs to fix it, and they can already see their own
+ * input.
+ */
+export function parseEndpoint(input) {
+    const chosen = typeof input.flag === "string" && input.flag.length > 0
+        ? { raw: input.flag, source: "--endpoint" }
+        : typeof input.env === "string" && input.env.length > 0
+            ? { raw: input.env, source: "FLOWSPRITE_ENDPOINT" }
+            : { raw: DEFAULT_ENDPOINT, source: "default" };
+    let url = null;
+    try {
+        url = new URL(chosen.raw);
+    }
+    catch {
+        url = null;
+    }
+    // `URL.hostname` is already lower-cased and, for IPv6, already bracketed —
+    // measured: `http://LOCALHOST:3000` -> "localhost", `http://[::1]:3000` -> "[::1]".
+    const loopback = url !== null && LOOPBACK_HOSTS.has(url.hostname);
+    // The NEGATION of the rule in the docstring, so TS narrows `url` past it.
+    if (url === null ||
+        (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) ||
+        url.username !== "" ||
+        url.password !== "" ||
+        url.pathname !== "/" ||
+        url.search !== "" ||
+        url.hash !== "") {
+        return {
+            ok: false,
+            source: chosen.source,
+            message: `The endpoint from ${chosen.source} is not a usable Flowsprite origin. ` +
+                "It must be https:// with a host and nothing else — no username or password, " +
+                "no path, no query string and no #fragment. A single trailing slash is fine. " +
+                "Plain http:// is accepted only for localhost, 127.0.0.1 and [::1], because every " +
+                "request carries an access token. " +
+                `Example: ${DEFAULT_ENDPOINT}`,
+        };
+    }
+    // `url.origin`, never the raw string: lower-cased host, default port dropped,
+    // and no trailing slash for the `${origin}/api/mcp` concatenations to double.
+    return { ok: true, origin: url.origin, source: chosen.source };
+}

package/dist/login.js

@@ -0,0 +1,154 @@
+import { isLoginFailureKind, LOGIN_REMEDIES, POLL_CONTINUE_KINDS } from "./messages.js";
+/**
+ * RFC 8628 device-code login against `/api/cli/auth/{start,poll}`.
+ *
+ * WHAT THE PERSON SEES: the user code and `verification_uri_complete`. NOT the
+ * device code — that value IS the credential the poll exchanges, so printing it
+ * would put a bearer-equivalent in a terminal scrollback for no gain (the
+ * browser never needs it). NOT the token either, on the way out.
+ *
+ * SLEEP CONVENTION — THE LOOP SLEEPS BEFORE EACH POLL, including the first.
+ * The clause ("polls every interval seconds") does not settle before-vs-between,
+ * and both are conforming; this one is chosen because the first poll is
+ * otherwise guaranteed to answer `authorization_pending` (nobody can have
+ * approved in the microseconds since `start` returned), and because the server
+ * treats a too-fast poll as `slow_down`, which lengthens the client's own next
+ * window.
+ *
+ * ponytail: no `sf`-CLI door on this ladder — card B4 is Blocked, so there is no
+ * "reuse the Salesforce CLI's browser session" rung here. When it lands it is
+ * one more branch BEFORE `start` is called, not a second login function.
+ */
+/** Seconds added to the poll interval each time the server says `slow_down`. */
+const SLOW_DOWN_STEP_SECONDS = 5;
+/** The device-code TTL the endpoint documents (`expires_in: 900`) — and the ceiling. */
+const MAX_EXPIRES_IN_SECONDS = 900;
+function failure(kind) {
+    return { ok: false, kind, message: LOGIN_REMEDIES[kind] };
+}
+/** One POST of a JSON body, answering with the status and the parsed body. */
+async function postJson(deps, url, body) {
+    let res;
+    try {
+        res = await deps.fetch(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json",
+                "user-agent": `flowsprite-cli/${deps.version}`,
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    catch {
+        // The error object is DISCARDED, not formatted: a transport error's message
+        // is written by the runtime around the request we just built, and the one
+        // caller of this function has a fixed sentence for the whole class.
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = await res.json();
+    }
+    catch {
+        parsed = null;
+    }
+    const obj = typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+        ? parsed
+        : {};
+    return { status: res.status, body: obj };
+}
+/** The `{error: <kind>}` a refusal carries, mapped onto a kind we have a remedy for. */
+function refusalKind(body) {
+    return isLoginFailureKind(body.error) ? body.error : "server_error";
+}
+export async function deviceCodeLogin(deps) {
+    const start = await postJson(deps, `${deps.origin}/api/cli/auth/start`, {
+        client_name: "flowsprite-cli",
+        cli_version: deps.version,
+    });
+    if (start === null)
+        return failure("transport");
+    if (start.status !== 200) {
+        // `rate_limited` (429), `invalid_argument`/`invalid_request` (400),
+        // `server_misconfigured`/`server_error` (500) — the route's own vocabulary,
+        // read off the body rather than guessed from the status.
+        return failure(refusalKind(start.body));
+    }
+    const deviceCode = start.body.device_code;
+    const userCode = start.body.user_code;
+    const completeUri = start.body.verification_uri_complete;
+    const fallbackUri = start.body.verification_uri;
+    if (typeof deviceCode !== "string" || typeof userCode !== "string") {
+        return failure("server_error");
+    }
+    const openTarget = typeof completeUri === "string"
+        ? completeUri
+        : typeof fallbackUri === "string"
+            ? fallbackUri
+            : null;
+    if (openTarget === null)
+        return failure("server_error");
+    deps.writer.out(`Open ${openTarget} and confirm the code ${userCode}`);
+    deps.writer.out("Waiting for you to approve this login...");
+    if (deps.openUrl) {
+        try {
+            deps.openUrl(openTarget);
+        }
+        catch {
+            // Deliberately silent: see LoginDeps.openUrl. The URL is already printed.
+        }
+    }
+    const intervalFromServer = start.body.interval;
+    let intervalSeconds = typeof intervalFromServer === "number" && intervalFromServer > 0 ? intervalFromServer : 5;
+    // The device code's own lifetime bounds the loop, so a server that answers
+    // `authorization_pending` forever still ends — with the same sentence a real
+    // `expired_token` gets, because the window really has passed.
+    //
+    // CLAMPED TO THE REAL TTL. `expires_in` is a number this CLI reads off a
+    // response, and the loop's termination is the only thing standing between a
+    // bad value and a terminal that polls for a year. The server's own TTL is 15
+    // minutes (`docs/mcp.md`, `expires_in: 900`), so anything larger is either a
+    // mistake or a hostile endpoint, and anything non-positive would end the loop
+    // before a single poll. Both fold to the documented value.
+    const claimed = start.body.expires_in;
+    const expiresIn = typeof claimed === "number" && Number.isFinite(claimed) && claimed > 0
+        ? Math.min(claimed, MAX_EXPIRES_IN_SECONDS)
+        : MAX_EXPIRES_IN_SECONDS;
+    let waitedSeconds = 0;
+    for (;;) {
+        if (waitedSeconds >= expiresIn)
+            return failure("expired_token");
+        await deps.sleep(intervalSeconds * 1000);
+        waitedSeconds += intervalSeconds;
+        const poll = await postJson(deps, `${deps.origin}/api/cli/auth/poll`, {
+            device_code: deviceCode,
+        });
+        if (poll === null)
+            return failure("transport");
+        if (poll.status === 200) {
+            const token = poll.body.token;
+            const orgId = poll.body.org_id;
+            const userId = poll.body.user_id;
+            const mcpEndpoint = poll.body.mcp_endpoint;
+            if (typeof token !== "string" ||
+                typeof orgId !== "string" ||
+                typeof userId !== "string" ||
+                typeof mcpEndpoint !== "string") {
+                return failure("server_error");
+            }
+            return { ok: true, token, orgId, userId, mcpEndpoint };
+        }
+        const kind = poll.body.error;
+        if (typeof kind === "string" && POLL_CONTINUE_KINDS.has(kind)) {
+            if (kind === "slow_down") {
+                // The server has ALREADY raised its own required interval by this much;
+                // raising ours to match is what stops the next poll earning another one.
+                // It persists for the rest of the loop rather than applying to one poll.
+                intervalSeconds += SLOW_DOWN_STEP_SECONDS;
+            }
+            continue;
+        }
+        return failure(refusalKind(poll.body));
+    }
+}

package/dist/mcpClient.js

@@ -0,0 +1,109 @@
+import { redact } from "./redact.js";
+/**
+ * EVERY message this module produces goes through `redact` before it is
+ * returned. The bearer lives only in a header, so no message SHOULD carry it —
+ * but "should" is the part that fails: a vendor error string can quote the
+ * request it was building, and the caller has no way to tell which strings came
+ * from us. Redacting at the one place messages are constructed makes the
+ * guarantee a property of this file rather than of every future edit to it.
+ */
+function fail(kind, message, code) {
+    const safe = redact(message);
+    return code === undefined ? { ok: false, kind, message: safe } : { ok: false, kind, message: safe, code };
+}
+export function createMcpClient(deps) {
+    const url = `${deps.origin}/api/mcp`;
+    let nextId = 0;
+    async function rpc(method, params) {
+        let res;
+        try {
+            res = await deps.fetch(url, {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${deps.token}`,
+                    "content-type": "application/json",
+                    accept: "application/json",
+                    "user-agent": `flowsprite-cli/${deps.version}`,
+                },
+                body: JSON.stringify({ jsonrpc: "2.0", id: ++nextId, method, params }),
+            });
+        }
+        catch (err) {
+            // Transport death, never reaching the app. Classified by the error's NAME,
+            // never by parsing its message text, which varies by runtime and libc.
+            const name = err instanceof Error ? err.name : "unknown";
+            return fail("transport", `Could not reach ${url} (${name}).`);
+        }
+        // 401 IS READ OFF THE STATUS, before the body. The body also carries
+        // `error.code -32001`, but a status is what the auth layer actually sets.
+        if (res.status === 401) {
+            return fail("unauthorized", `${url} refused the token (HTTP 401). Run \`flowsprite login\` to get a new one.`);
+        }
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            return fail("transport", `${url} answered HTTP ${res.status} with a body that is not JSON.`);
+        }
+        if (typeof body !== "object" || body === null || Array.isArray(body)) {
+            return fail("transport", `${url} answered HTTP ${res.status} with a body that is not a JSON-RPC object.`);
+        }
+        const envelope = body;
+        const rpcError = envelope.error;
+        if (typeof rpcError === "object" && rpcError !== null && !Array.isArray(rpcError)) {
+            const e = rpcError;
+            const code = typeof e.code === "number" ? e.code : undefined;
+            const message = typeof e.message === "string" ? e.message : "unknown JSON-RPC error";
+            return fail("rpc_error", message, code);
+        }
+        const result = envelope.result;
+        if (typeof result !== "object" || result === null || Array.isArray(result)) {
+            return fail("transport", `${url} answered HTTP ${res.status} with neither a result nor an error.`);
+        }
+        const r = result;
+        const content = Array.isArray(r.content) ? r.content : [];
+        if (r.isError === true) {
+            // The tool's own refusal text is the whole value of this branch — an
+            // `isError` result with no text would otherwise be an empty message.
+            const text = content.find((c) => typeof c.text === "string")?.text;
+            return fail("tool_error", text ?? `${method} failed and said nothing about why.`);
+        }
+        return r.structuredContent === undefined
+            ? { ok: true, content }
+            : { ok: true, content, structured: r.structuredContent };
+    }
+    return {
+        url,
+        callTool: (name, args) => rpc("tools/call", { name, arguments: args }),
+        initialize: () => rpc("initialize", {
+            protocolVersion: "2025-06-18",
+            capabilities: {},
+            clientInfo: { name: "flowsprite-cli", version: deps.version },
+        }),
+    };
+}
+/**
+ * The JSON payload every `setup_*` / `sfdc_*` tool puts in `content[0].text`.
+ *
+ * It lives here rather than in the caller because the SHAPE is a property of
+ * this endpoint, not of setup: the tools answer with a JSON string, not with a
+ * structured field. A body that is not parseable JSON is a `null` rather than a
+ * throw — the caller already has to handle "the tool refused", and a second
+ * failure channel for the same call is how one of them stops being handled.
+ */
+export function toolJson(result) {
+    if (!result.ok)
+        return null;
+    if (result.structured !== undefined)
+        return result.structured;
+    const text = result.content.find((c) => typeof c.text === "string")?.text;
+    if (typeof text !== "string")
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}