backstep 0.0.0-stage → 0.1.0

package/dist/connect.js

@@ -0,0 +1,237 @@
+// Connects Backstep to what a project uses, so undo covers it, without anyone
+// having to know what to connect or where its settings live. The person asks
+// Claude ("connect Backstep to my Supabase", "to everything I use") and the
+// Claude Code mod runs this; `backstep connect` in a terminal does the same.
+//  - Supabase: a connection string from the project's .env files, the local
+//    database `supabase start` runs, or one the person gives.
+//  - Firebase: undo runs through Firebase's own MCP server, so there's nothing
+//    to connect once Claude can reach Firebase. When the project uses Firebase
+//    and Claude can't, this adds that server (behind Backstep).
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { claudeConfigFile, wrapServers } from "./servers.js";
+import { connectSupabase, hasSavedToken, LOCAL, mintSupabase, projectRef, saveSupabaseToken, supabaseDismissed, supabaseProjects, supabaseToken } from "./supabase.js";
+const ENV_FILES = [".env", ".env.local", ".env.development", ".env.development.local"];
+const PG = /^postgres(ql)?:\/\//;
+const FIREBASE_SERVER = ["npx", "-y", "firebase-tools@latest", "mcp"];
+function read(file) {
+    try {
+        return readFileSync(file, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function envVars(dir) {
+    const out = [];
+    for (const f of ENV_FILES) {
+        for (const line of read(join(dir, f)).split("\n")) {
+            const m = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+            if (m)
+                out.push([m[1], m[2].replace(/^(['"])(.*)\1$/, "$2")]);
+        }
+    }
+    return out;
+}
+function deps(dir) {
+    try {
+        const pkg = JSON.parse(read(join(dir, "package.json")));
+        return [...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.devDependencies ?? {})];
+    }
+    catch {
+        return [];
+    }
+}
+// Every MCP server a session in `dir` can reach, from Claude Code's config:
+// the person's, the project's own, its .mcp.json, and the claude.ai
+// connectors that have been used.
+export function configServers(dir) {
+    let config = {};
+    try {
+        config = JSON.parse(read(claudeConfigFile()));
+    }
+    catch {
+        // no config yet
+    }
+    const project = Object.entries(config.projects ?? {}).find(([d]) => resolve(d) === resolve(dir))?.[1];
+    let shared = {};
+    try {
+        shared = JSON.parse(read(join(dir, ".mcp.json"))).mcpServers ?? {};
+    }
+    catch {
+        // no .mcp.json
+    }
+    const list = (all = {}) => Object.entries(all).map(([name, e]) => ({ name, target: [e.command ?? "", ...(e.args ?? []), e.url ?? ""].join(" ").trim() }));
+    const connectors = (config.claudeAiMcpEverConnected ?? []).map((name) => ({ name, target: "" }));
+    return [...list(project?.mcpServers), ...list(shared), ...list(config.mcpServers), ...connectors];
+}
+const servers = (dir) => configServers(dir).map((s) => `${s.name} ${s.target}`);
+export function projectUses(dir) {
+    const d = deps(dir);
+    return {
+        supabase: d.some((x) => x.startsWith("@supabase/")) || envVars(dir).some(([k]) => k.includes("SUPABASE")) || existsSync(join(dir, "supabase", "config.toml")),
+        firebase: existsSync(join(dir, "firebase.json")) || existsSync(join(dir, ".firebaserc")) || d.some((x) => x === "firebase" || x === "firebase-admin"),
+    };
+}
+// Connection strings worth trying, best first: the ones that say they're
+// direct, then any other Postgres URL in the project's env files.
+function candidates(dir) {
+    const urls = envVars(dir)
+        .filter(([, v]) => PG.test(v) && !v.includes("[YOUR-PASSWORD]"))
+        .sort(([a], [b]) => Number(/DIRECT|SUPABASE/.test(b)) - Number(/DIRECT|SUPABASE/.test(a)))
+        .map(([, v]) => v);
+    // `supabase start` runs a database with a fixed password on the port its config names.
+    const toml = read(join(dir, "supabase", "config.toml"));
+    if (toml) {
+        const port = toml.match(/^\[db\][^[]*?^port\s*=\s*(\d+)/m)?.[1] ?? "54322";
+        urls.push(`postgresql://postgres:postgres@127.0.0.1:${port}/postgres`);
+    }
+    return [...new Set(urls)];
+}
+const TOKENS = "https://supabase.com/dashboard/account/tokens";
+const WHERE = "Supabase → your project → Connect (top of the page) → Direct connection (or Session pooler) → copy the URI and put the database password in place of [YOUR-PASSWORD]";
+// The hosted project a folder belongs to: `supabase link` notes it, and the
+// app's own settings name it in its API URL.
+function linkedRef(dir) {
+    const linked = read(join(dir, "supabase", ".temp", "project-ref")).trim();
+    if (/^[a-z0-9]{20}$/.test(linked))
+        return linked;
+    for (const [, v] of envVars(dir)) {
+        const m = v.match(/^https:\/\/([a-z0-9]{20})\.supabase\.co/);
+        if (m)
+            return m[1];
+    }
+    return undefined;
+}
+// Signed in to Supabase: this folder's project connects now, the rest as Claude uses them.
+async function signedIn(dir, token, ref, isNew) {
+    const project = ref ?? linkedRef(dir);
+    if (project && !supabaseProjects().includes(project)) {
+        try {
+            await mintSupabase(project, token);
+            return { service: "supabase", state: "connected", detail: `connected project ${project} with your Supabase sign-in` };
+        }
+        catch (err) {
+            return { service: "supabase", state: "needs", detail: `signed in, but couldn't connect project ${project}: ${err instanceof Error ? err.message : String(err)}` };
+        }
+    }
+    return isNew ? { service: "supabase", state: "connected", detail: "signed in to Supabase, so each project connects itself as Claude uses it" } : null;
+}
+// Whether the project this folder uses already has its database connected.
+function projectConnected(dir) {
+    const ref = linkedRef(dir);
+    return ref ? supabaseProjects().includes(ref) : supabaseProjects().length > 0;
+}
+async function supabase(dir, given, ref, interactive = false, auto = false) {
+    const label = (r) => (r === LOCAL ? "the local database" : `project ${r}`);
+    // On its own, Backstep only notices: connecting is the person's call.
+    if (auto) {
+        if (!projectUses(dir).supabase || supabaseDismissed(dir))
+            return { service: "supabase", state: "unused", detail: "nothing to ask" };
+        if (projectConnected(dir))
+            return { service: "supabase", state: "covered", detail: "already connected" };
+        return { service: "supabase", state: "ask", detail: "this project uses Supabase, but Backstep isn't connected to it" };
+    }
+    // An access token (sbp_…) rather than a connection string: one sign-in for every project.
+    if (given?.startsWith("sbp_")) {
+        try {
+            await saveSupabaseToken(given);
+        }
+        catch (err) {
+            return { service: "supabase", state: "needs", detail: err instanceof Error ? err.message : String(err) };
+        }
+        return (await signedIn(dir, given, ref, true));
+    }
+    if (given) {
+        try {
+            return { service: "supabase", state: "connected", detail: `connected ${label(await connectSupabase(given, ref))}` };
+        }
+        catch (err) {
+            return { service: "supabase", state: "needs", detail: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    const had = supabaseProjects();
+    const errors = [];
+    for (const url of candidates(dir)) {
+        const r = ref ?? projectRef(url) ?? LOCAL;
+        if (had.includes(r))
+            continue;
+        // A Postgres URL that isn't Supabase's belongs to something else, and so
+        // does a local one in a project that doesn't use Supabase.
+        if (r === LOCAL && (!/@(127\.0\.0\.1|localhost)[:/]/.test(url) || !projectUses(dir).supabase))
+            continue;
+        try {
+            await connectSupabase(url, ref);
+            return { service: "supabase", state: "connected", detail: `connected ${label(r)}, found in the project's settings` };
+        }
+        catch (err) {
+            errors.push(err instanceof Error ? err.message : String(err));
+        }
+    }
+    // Already signed in to Supabase, here or through its own CLI: keep that sign-in.
+    const token = supabaseToken(interactive);
+    if (token) {
+        const isNew = !hasSavedToken();
+        if (isNew)
+            await saveSupabaseToken(token).catch(() => null);
+        const s = await signedIn(dir, token, ref, isNew);
+        if (s)
+            return s;
+        return { service: "supabase", state: "covered", detail: "signed in to Supabase, so each project connects itself as Claude uses it" };
+    }
+    if (had.length)
+        return { service: "supabase", state: "covered", detail: `already connected: ${had.map(label).join(", ")}` };
+    const used = /supabase/i.test(servers(dir).join("\n")) || projectUses(dir).supabase;
+    if (!used && errors.length === 0)
+        return { service: "supabase", state: "unused", detail: "this project doesn't use Supabase" };
+    return {
+        service: "supabase",
+        state: "needs",
+        detail: `needs a Supabase sign-in. Easiest: an access token, made once at ${TOKENS} ("Generate new token"), which connects every project. ` +
+            `Or the database's connection string (${WHERE})${errors.length ? `. Tried the one in the project's settings: ${errors[0]}` : ""}`,
+    };
+}
+// firebase-tools keeps its sign-in here once someone runs `firebase login`.
+function firebaseSignedIn() {
+    try {
+        const c = JSON.parse(read(join(homedir(), ".config", "configstore", "firebase-tools.json")));
+        return Boolean(c.tokens?.refresh_token);
+    }
+    catch {
+        return false;
+    }
+}
+// `auto`: on its own as a session starts, so a server is only added when it would work.
+function firebase(dir, cli, auto = false) {
+    if (servers(dir).some((s) => /firebase|firestore/i.test(s))) {
+        return { service: "firebase", state: "covered", detail: "Claude reaches Firebase through its MCP server, so its changes can be undone" };
+    }
+    if (!projectUses(dir).firebase)
+        return { service: "firebase", state: "unused", detail: "this project doesn't use Firebase" };
+    if (auto && !firebaseSignedIn()) {
+        return { service: "firebase", state: "needs", detail: "sign in to Firebase once (run: npx firebase-tools login), and Backstep connects it by itself" };
+    }
+    // For this project only, like `claude mcp add` without -s.
+    const r = spawnSync("claude", ["mcp", "add", "firebase", "--", ...FIREBASE_SERVER], { cwd: dir, encoding: "utf8" });
+    if (r.status !== 0) {
+        return { service: "firebase", state: "needs", detail: `couldn't add Firebase's MCP server: ${`${r.stderr ?? ""}${r.stdout ?? ""}`.trim().split("\n")[0] || "claude mcp add failed"}` };
+    }
+    wrapServers(cli, { onlyDir: dir });
+    return {
+        service: "firebase",
+        state: "added",
+        detail: "added Firebase's MCP server for this project, behind Backstep. Restart Claude Code to use it (and run `npx firebase-tools login` first if you've never signed in to Firebase)",
+    };
+}
+// `auto`: run by the Claude Code mod as a session starts, with nobody asked.
+// `interactive`: a person is at the terminal (macOS may ask them to share `supabase login`'s sign-in).
+export async function connect(opts) {
+    const out = [];
+    if (opts.only !== "firebase")
+        out.push(await supabase(opts.dir, opts.url, opts.ref, opts.interactive, opts.auto));
+    if (opts.only !== "supabase")
+        out.push(firebase(opts.dir, opts.cli, opts.auto));
+    return out;
+}

package/dist/firebase.js

@@ -0,0 +1,137 @@
+// Firestore names documents projects/<p>/databases/<d>/documents/<path>.
+const DOC_NAME = /^projects\/[^/]+\/databases\/[^/]+\/documents\/.+/;
+function text(r) {
+    return (r.content ?? []).map((c) => (c.type === "text" ? c.text : "")).join("");
+}
+function data(r) {
+    if (r.structuredContent)
+        return r.structuredContent;
+    try {
+        const v = JSON.parse(text(r));
+        return v && typeof v === "object" ? v : {};
+    }
+    catch {
+        return {};
+    }
+}
+const notFound = (r) => r.isError === true && /not[ _-]?found|404|no document/i.test(text(r));
+class ReadFailed extends Error {
+}
+function readOk(r, what) {
+    if (!r)
+        throw new ReadFailed(`couldn't read ${what} first`);
+    if (r.isError && !notFound(r))
+        throw new ReadFailed(`couldn't read ${what} first: ${text(r).slice(0, 200)}`);
+    return r;
+}
+// Splits "firestore_update_document" into its prefix and the base tool name.
+// Google's own Firestore server has no prefix.
+function split(tool, bases) {
+    for (const base of bases) {
+        if (tool === base)
+            return { prefix: "", base };
+        if (tool.endsWith(`_${base}`))
+            return { prefix: tool.slice(0, -base.length), base };
+    }
+    return null;
+}
+function firestore(tool, args) {
+    const t = split(tool, ["update_document", "delete_document", "add_document"]);
+    if (!t || (t.prefix !== "" && t.prefix !== "firestore_"))
+        return null;
+    const p = t.prefix;
+    const restore = (name, before) => notFound(before)
+        ? { tool: `${p}delete_document`, args: { name } }
+        : { tool: `${p}update_document`, args: { document: { name, fields: data(before).fields ?? {} } } };
+    if (t.base === "update_document") {
+        const name = args.document?.name;
+        if (typeof name !== "string" || !DOC_NAME.test(name))
+            return null;
+        return {
+            read: { tool: `${p}get_document`, args: { name } },
+            undo: (read) => restore(name, readOk(read, name)),
+        };
+    }
+    if (t.base === "delete_document") {
+        const name = args.name;
+        if (typeof name !== "string" || !DOC_NAME.test(name))
+            return null;
+        return {
+            read: { tool: `${p}get_document`, args: { name } },
+            undo: (read) => {
+                const before = readOk(read, name);
+                // Deleting a document that wasn't there changed nothing.
+                return notFound(before) ? null : restore(name, before);
+            },
+        };
+    }
+    if (typeof args.parent !== "string" || typeof args.collectionId !== "string")
+        return null;
+    return {
+        undo: (_, result) => {
+            const name = data(result).name;
+            if (typeof name !== "string")
+                throw new ReadFailed("the new document's name wasn't in the result");
+            return { tool: `${p}delete_document`, args: { name } };
+        },
+    };
+}
+function realtimeDatabase(tool, args) {
+    const t = split(tool, ["set_data"]);
+    if (!t || !/^(realtimedatabase|database)_$/.test(t.prefix) || typeof args.path !== "string")
+        return null;
+    const where = { path: args.path, ...(typeof args.databaseUrl === "string" ? { databaseUrl: args.databaseUrl } : {}) };
+    return {
+        read: { tool: `${t.prefix}get_data`, args: where },
+        undo: (read) => {
+            const before = text(readOk(read, args.path)).trim();
+            let value;
+            try {
+                value = JSON.parse(before || "null");
+            }
+            catch {
+                throw new ReadFailed(`couldn't read ${args.path} first: ${before.slice(0, 200)}`);
+            }
+            // The REST API answers a refused read with {"error": "..."}.
+            if (value && typeof value === "object" && Object.keys(value).length === 1 && "error" in value) {
+                throw new ReadFailed(`couldn't read ${args.path} first: ${value.error}`);
+            }
+            // Writing null deletes the path, which is right when nothing was there.
+            return { tool: `${t.prefix}set_data`, args: { ...where, data: JSON.stringify(value) } };
+        },
+    };
+}
+function remoteConfig(tool) {
+    if (tool !== "remoteconfig_update_template")
+        return null;
+    return {
+        read: { tool: "remoteconfig_get_template", args: {} },
+        undo: (read) => {
+            const r = readOk(read, "the Remote Config template");
+            const version = Number(data(r).version?.versionNumber);
+            // The first template has nothing before it to roll back to.
+            if (notFound(r) || !Number.isFinite(version) || version <= 0)
+                return null;
+            return { tool: "remoteconfig_update_template", args: { version_number: version } };
+        },
+    };
+}
+function auth(tool, args) {
+    // Custom claims can be set but not removed through the server, so only enable/disable is undoable.
+    if (tool !== "auth_update_user" || typeof args.uid !== "string" || typeof args.disabled !== "boolean")
+        return null;
+    const uid = args.uid;
+    return {
+        read: { tool: "auth_get_users", args: { uids: [uid] } },
+        undo: (read) => {
+            const users = data(readOk(read, `user ${uid}`)).users;
+            if (!users?.[0])
+                throw new ReadFailed(`couldn't find user ${uid} first`);
+            return { tool: "auth_update_user", args: { uid, disabled: users[0].disabled === true } };
+        },
+    };
+}
+export function firebasePlan(tool, args) {
+    return firestore(tool, args) ?? realtimeDatabase(tool, args) ?? remoteConfig(tool) ?? auth(tool, args);
+}
+export { ReadFailed };

package/dist/look.js

@@ -0,0 +1,34 @@
+// How Backstep looks in a terminal: the mark (two rewind triangles, white over
+// pink), pink for Backstep, white for what matters, dim for the rest. Plain
+// text where colour isn't wanted (NO_COLOR, piped output).
+const on = !process.env.NO_COLOR && (Boolean(process.env.FORCE_COLOR) || (process.stdout.isTTY === true && process.env.TERM !== "dumb"));
+const truecolor = /truecolor|24bit/i.test(process.env.COLORTERM ?? "");
+const paint = (code) => (s) => (on ? `\x1b[${code}m${s}\x1b[0m` : s);
+// The mark's pink, #ee7bb6, or the nearest of the 256 colours.
+export const pink = paint(truecolor ? "38;2;238;123;182" : "38;5;211");
+export const white = paint("1;97");
+export const dim = paint("2");
+export const width = () => Math.min(process.stdout.columns || 80, 92);
+// Words wrapped to `cols`, each line after the first indented by `indent`.
+export function wrap(text, cols, indent) {
+    const lines = [];
+    let line = "";
+    for (const word of text.split(" ")) {
+        if (line && line.length + 1 + word.length > cols) {
+            lines.push(line);
+            line = word;
+        }
+        else
+            line = line ? `${line} ${word}` : word;
+    }
+    if (line)
+        lines.push(line);
+    return lines.join(`\n${" ".repeat(indent)}`);
+}
+// The front triangle white, the one behind it pink, as on the logo.
+export function logo(tagline) {
+    const front = ["    ▄█", "  ▄███", "▄█████", "  ▀███", "    ▀█"];
+    const back = ["    ▄█", "  ▄███", "▄█████", "  ▀███", "    ▀█"];
+    const side = ["", white("Backstep"), dim(tagline), "", ""];
+    return "\n" + front.map((f, i) => `  ${white(f)}${pink(back[i])}   ${side[i]}`.trimEnd()).join("\n");
+}