backstep 0.1.9 → 0.1.13

package/dist/connect.js

@@ -8,11 +8,13 @@
 //    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, readdirSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import pg from "pg";
+import { accessToken, loadCreds } from "./adapters/firestore.js";
 import { claudeConfigFile, wrapServers } from "./servers.js";
-import { connectSupabase, hasSavedToken, LOCAL, mintSupabase, projectRef, saveSupabaseToken, supabaseDb, restKey, saveRest, supabaseDismissed, supabaseProjects, supabaseToken, supabaseUrl, } from "./supabase.js";
+import { connectSupabase, hasSavedToken, LOCAL, mintSupabase, projectRef, saveSupabaseToken, supabaseDb, restKey, firebaseConn, postgresUrl, saveFirebase, savePostgres, saveRest, supabaseDismissed, supabaseProjects, supabaseToken, supabaseUrl, } 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"];
@@ -71,14 +73,82 @@ const servers = (dir) => configServers(dir).map((s) => `${s.name} ${s.target}`);
 export function projectUses(dir) {
     const d = deps(dir);
     return {
+        postgres: postgresUrls(dir).length > 0,
         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"),
     };
 }
+// Postgres databases in the project's .env that aren't Supabase's: Neon, Railway, Render, AWS, a local one.
+export function postgresUrls(dir) {
+    const supa = existsSync(join(dir, "supabase", "config.toml")) || deps(dir).some((x) => x.startsWith("@supabase/"));
+    return [
+        ...new Set(envVars(dir)
+            .filter(([, v]) => PG.test(v) && !v.includes("[YOUR-PASSWORD]"))
+            .map(([, v]) => v)
+            .filter((v) => !projectRef(v) && !/supabase\.(co|com)\b/.test(v) && !(supa && /@(127\.0\.0\.1|localhost):5432[0-9]\b/.test(v)))),
+    ];
+}
+// The Firebase project a folder uses, from .firebaserc or its settings.
+export function firebaseProject(dir) {
+    try {
+        const rc = JSON.parse(read(join(dir, ".firebaserc")));
+        if (rc.projects?.default)
+            return rc.projects.default;
+    }
+    catch {
+        // no .firebaserc
+    }
+    return envVars(dir).find(([k]) => /FIREBASE_PROJECT_ID$|GCLOUD_PROJECT$|GOOGLE_CLOUD_PROJECT$/.test(k))?.[1];
+}
+// Credentials that can read and write the project's Firestore: a service account
+// key in the project or named by GOOGLE_APPLICATION_CREDENTIALS, one pasted into
+// an env var, or gcloud's application default login.
+export function firebaseCreds(dir) {
+    const vars = envVars(dir);
+    const named = vars.find(([k]) => k === "GOOGLE_APPLICATION_CREDENTIALS")?.[1] ?? process.env.GOOGLE_APPLICATION_CREDENTIALS;
+    if (named) {
+        const f = named.startsWith("/") ? named : join(dir, named);
+        if (existsSync(f))
+            return f;
+    }
+    for (const sub of [dir, join(dir, "config"), join(dir, "secrets")]) {
+        let names = [];
+        try {
+            names = readdirSync(sub);
+        }
+        catch {
+            continue;
+        }
+        const key = names.find((n) => /^(service-?account.*|.*firebase-adminsdk.*)\.json$/i.test(n) || /^serviceAccountKey\.json$/i.test(n));
+        if (key)
+            return join(sub, key);
+    }
+    // A key pasted whole into an env var: kept in Backstep's own folder, readable only by the person.
+    const inline = vars.find(([k, v]) => /FIREBASE.*(SERVICE_ACCOUNT|ADMIN).*|GOOGLE_CREDENTIALS/.test(k) && v.trim().startsWith("{"))?.[1];
+    if (inline) {
+        const f = join(homedir(), ".backstep", `firebase-${firebaseProject(dir) ?? "project"}.json`);
+        mkdirSync(dirname(f), { recursive: true, mode: 0o700 });
+        writeFileSync(f, inline, { mode: 0o600 });
+        return f;
+    }
+    const adc = join(homedir(), ".config", "gcloud", "application_default_credentials.json");
+    return existsSync(adc) ? adc : null;
+}
+const rtdbUrl = (dir) => envVars(dir).find(([k, v]) => /DATABASE_URL$/.test(k) && /firebaseio\.com|firebasedatabase\.app/.test(v))?.[1];
 // Folders a session in `dir` works in that use Supabase: the folder itself, or
 // its projects a level or two down (Claude Code opened in a parent folder).
 export function supabaseDirs(dir) {
-    if (projectUses(dir).supabase)
+    return projectDirs(dir, (d) => projectUses(d).supabase);
+}
+// Folders that use any database Backstep connects: Supabase, other Postgres, Firebase.
+export function dbDirs(dir) {
+    return projectDirs(dir, (d) => {
+        const u = projectUses(d);
+        return u.supabase || u.postgres || u.firebase;
+    });
+}
+export function projectDirs(dir, uses) {
+    if (uses(dir))
         return [dir];
     const out = [];
     const walk = (d, depth) => {
@@ -93,7 +163,7 @@ export function supabaseDirs(dir) {
         }
         for (const n of names) {
             const child = join(d, n);
-            if (projectUses(child).supabase)
+            if (uses(child))
                 out.push(child);
             else
                 walk(child, depth - 1);
@@ -171,6 +241,20 @@ async function signedIn(dir, token, ref, isNew) {
     }
     return isNew ? { service: "supabase", state: "connected", detail: "signed in to Supabase, so each project connects itself as Claude uses it" } : null;
 }
+// Whether one of a folder's databases is connected to Backstep.
+export function connectedFor(dir, service) {
+    if (service === "supabase")
+        return projectConnected(dir);
+    if (service === "postgres")
+        return postgresUrls(dir).every((u) => postgresUrl(u) !== null);
+    const project = firebaseProject(dir);
+    return project !== undefined && firebaseConn(project) !== null;
+}
+// A folder's databases that aren't connected yet, and that the person hasn't said not to ask about.
+export function unconnected(dir) {
+    const u = projectUses(dir);
+    return ["supabase", "postgres", "firebase"].filter((s) => u[s] && !connectedFor(dir, s) && !supabaseDismissed(dir, s));
+}
 // Whether the project this folder uses is connected: its database, or its API through the project's keys.
 export function projectConnected(dir) {
     const rest = restKeys(dir);
@@ -304,11 +388,85 @@ function firebase(dir, cli, auto = false) {
 }
 // `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).
+async function postgres(dir, given, auto = false) {
+    if (auto) {
+        const d = dbDirs(dir).find((x) => unconnected(x).includes("postgres"));
+        return d
+            ? { service: "postgres", state: "ask", detail: "this project uses a Postgres database, but Backstep isn't connected to it", dir: d }
+            : { service: "postgres", state: dbDirs(dir).some((x) => projectUses(x).postgres) ? "covered" : "unused", detail: "nothing to ask" };
+    }
+    if (!projectUses(dir).postgres && !given)
+        dir = projectDirs(dir, (d) => projectUses(d).postgres)[0] ?? dir;
+    const urls = given ? [given] : postgresUrls(dir);
+    if (urls.length === 0)
+        return { service: "postgres", state: "unused", detail: "this project has no Postgres database in its settings" };
+    const errors = [];
+    for (const url of urls) {
+        const client = new pg.Client({ connectionString: url, connectionTimeoutMillis: 10_000 });
+        try {
+            await client.connect();
+            await client.query("SELECT 1");
+            savePostgres(url);
+        }
+        catch (err) {
+            errors.push(err instanceof Error ? err.message : String(err));
+        }
+        finally {
+            await client.end().catch(() => { });
+        }
+    }
+    if (errors.length === urls.length)
+        return { service: "postgres", state: "needs", detail: `couldn't reach the database in the project's settings: ${errors[0]}` };
+    const host = (u) => {
+        try {
+            return new URL(u).hostname;
+        }
+        catch {
+            return "the database";
+        }
+    };
+    return { service: "postgres", state: "connected", detail: `connected ${urls.map(host).join(", ")}, from the project's settings` };
+}
+const SERVICE_KEY_HOW = "Firebase console → your project → ⚙ Project settings → Service accounts → Generate new private key, then save the file in the project as serviceAccountKey.json (and keep it out of git)";
+// Firebase's data (Firestore, Realtime Database), signed in with the project's
+// service account or gcloud's login. Separate from its MCP server, which the
+// firebase() step above adds.
+async function firebaseData(dir, auto = false) {
+    if (auto) {
+        const d = dbDirs(dir).find((x) => unconnected(x).includes("firebase"));
+        return d ? { service: "firebase", state: "ask", detail: "this project uses Firebase, but Backstep isn't connected to its data", dir: d } : { service: "firebase", state: "unused", detail: "nothing to ask" };
+    }
+    if (!projectUses(dir).firebase)
+        dir = projectDirs(dir, (d) => projectUses(d).firebase)[0] ?? dir;
+    const credsFile = firebaseCreds(dir);
+    let project = firebaseProject(dir);
+    if (!credsFile)
+        return { service: "firebase", state: "needs", detail: `needs the project's service account key: ${SERVICE_KEY_HOW}` };
+    try {
+        const creds = loadCreds(credsFile);
+        if (!project && creds.type === "service_account")
+            project = creds.project_id;
+        if (!project)
+            return { service: "firebase", state: "needs", detail: "couldn't tell which Firebase project this is: add a .firebaserc (run: npx firebase-tools use --add)" };
+        await accessToken(creds);
+        saveFirebase({ project, credsFile, ...(rtdbUrl(dir) ? { rtdb: rtdbUrl(dir) } : {}) });
+        return { service: "firebase", state: "connected", detail: `connected Firebase project ${project}: Firestore${rtdbUrl(dir) ? " and the Realtime Database" : ""} can be undone` };
+    }
+    catch (err) {
+        return { service: "firebase", state: "needs", detail: `the Firebase sign-in didn't work (${err instanceof Error ? err.message : String(err)}). ${SERVICE_KEY_HOW}` };
+    }
+}
 export async function connect(opts) {
     const out = [];
-    if (opts.only !== "firebase")
+    const want = (s) => !opts.only || opts.only === s;
+    if (want("supabase"))
         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));
+    if (want("postgres"))
+        out.push(await postgres(opts.dir, opts.only === "postgres" ? opts.url : undefined, opts.auto));
+    if (want("firebase")) {
+        const data = await firebaseData(opts.dir, opts.auto);
+        // Asked about its data first; its MCP server is added as before once that's settled.
+        out.push(data.state === "ask" ? data : firebase(opts.dir, opts.cli, opts.auto), ...(data.state === "ask" || data.state === "unused" ? [] : [data]));
+    }
     return out;
 }

package/dist/github.js

@@ -0,0 +1,111 @@
+// Things Claude makes on GitHub with the gh command line (a repository, an
+// issue, a pull request, a release), noted from what gh printed, so undo can
+// offer to take them away again with gh itself, signed in as the person.
+import { spawn, spawnSync } from "node:child_process";
+const CREATES = /\bgh\s+(repo|issue|pr|release)\s+create\b/g;
+const URL = /https:\/\/github\.com\/([\w.-]+\/[\w.-]+?)(?:\.git)?(?:\/(issues|pull)\/(\d+)|\/releases\/tag\/([^\s)]+))?(?=[\s)'"]|$)/g;
+// What a gh command made, from the command and what it printed.
+export function ghMade(command, output) {
+    const kinds = new Set([...command.matchAll(CREATES)].map((m) => m[1]));
+    if (kinds.size === 0)
+        return [];
+    const out = [];
+    for (const m of output.matchAll(URL)) {
+        const [url, repo, part, num, tag] = m;
+        if (part === "issues" && kinds.has("issue"))
+            out.push({ kind: "issue", repo, number: Number(num), url });
+        else if (part === "pull" && kinds.has("pr"))
+            out.push({ kind: "pr", repo, number: Number(num), url });
+        else if (tag && kinds.has("release"))
+            out.push({ kind: "release", repo, tag, url });
+        else if (!part && !tag && kinds.has("repo"))
+            out.push({ kind: "repo", repo, url });
+    }
+    // `gh repo create` also says "Created repository owner/name on GitHub".
+    for (const m of output.matchAll(/Created repository ([\w.-]+\/[\w.-]+)/g))
+        out.push({ kind: "repo", repo: m[1], url: `https://github.com/${m[1]}` });
+    const seen = new Set();
+    return out.filter((g) => {
+        const k = `${g.kind}:${g.repo}:${g.number ?? g.tag ?? ""}`;
+        return seen.has(k) ? false : (seen.add(k), true);
+    });
+}
+export const describeGh = (g) => g.kind === "repo" ? `the repository ${g.repo}` : g.kind === "release" ? `the release ${g.tag} in ${g.repo}` : `${g.kind === "pr" ? "pull request" : "issue"} #${g.number} in ${g.repo}`;
+function gh(args) {
+    const r = spawnSync("gh", args, { encoding: "utf8", timeout: 60_000, env: { ...process.env, GH_PROMPT_DISABLED: "1", NO_COLOR: "1" } });
+    return { ok: r.status === 0, out: `${r.stdout ?? ""}${r.stderr ?? ""}`.trim() };
+}
+export function undoGh(g) {
+    const what = describeGh(g);
+    let r;
+    if (g.kind === "repo") {
+        r = gh(["repo", "delete", g.repo, "--yes"]);
+        // gh's sign-in can't delete repositories until the person allows it: the mod gets that OK and tries again.
+        if (!r.ok && /delete_repo/.test(r.out))
+            return { ok: false, needs: "delete_repo", detail: `GitHub needs your OK before ${g.repo} can be deleted` };
+    }
+    else if (g.kind === "issue") {
+        // Deleting needs admin rights; closing is the fallback anyone can do.
+        r = gh(["issue", "delete", String(g.number), "-R", g.repo, "--yes"]);
+        if (!r.ok) {
+            r = gh(["issue", "close", String(g.number), "-R", g.repo, "-c", "Undone with Backstep."]);
+            if (r.ok)
+                return { ok: true, detail: `closed ${what} (deleting it needs admin rights)` };
+        }
+    }
+    else if (g.kind === "pr") {
+        r = gh(["pr", "close", String(g.number), "-R", g.repo, "--delete-branch", "-c", "Undone with Backstep."]);
+        if (r.ok)
+            return { ok: true, detail: `closed ${what} and deleted its branch` };
+    }
+    else {
+        r = gh(["release", "delete", g.tag, "-R", g.repo, "--yes", "--cleanup-tag"]);
+    }
+    if (r.ok)
+        return { ok: true, detail: `deleted ${what}` };
+    return { ok: false, detail: `couldn't undo ${what}: ${r.out.split("\n").filter(Boolean).at(-1) ?? "gh failed"}` };
+}
+const DEVICE = "https://github.com/login/device";
+function copy(text) {
+    const tries = process.platform === "darwin" ? [["pbcopy", []]] : process.platform === "win32" ? [["clip", []]] : [["wl-copy", []], ["xclip", ["-selection", "clipboard"]], ["xsel", ["-b", "-i"]]];
+    for (const [cmd, args] of tries)
+        if (spawnSync(cmd, args, { input: text }).status === 0)
+            return true;
+    return false;
+}
+function openPage(url) {
+    const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+    spawnSync(cmd, args, { stdio: "ignore" });
+}
+// Gives gh's sign-in another permission (like delete_repo) with GitHub's own
+// approval page: the one-time code is put on the clipboard and the page opened,
+// so the person only pastes it and approves. Resolves once GitHub says yes,
+// or no, or nine minutes pass (Claude Code gives a command ten).
+export function grantScope(scope) {
+    return new Promise((resolve) => {
+        // gh would open the page too; Backstep already does, so gh's browser is told to do nothing.
+        const env = { ...process.env, NO_COLOR: "1", GH_BROWSER: process.platform === "win32" ? "cmd /c exit" : "true" };
+        const child = spawn("gh", ["auth", "refresh", "-h", "github.com", "-s", scope], { env, stdio: ["pipe", "pipe", "pipe"] });
+        let out = "";
+        let shown = false;
+        const timer = setTimeout(() => child.kill(), 9 * 60 * 1000);
+        const read = (chunk) => {
+            out += chunk.toString();
+            const code = out.match(/\b([A-Z0-9]{4}-[A-Z0-9]{4})\b/)?.[1];
+            if (code && !shown) {
+                shown = true;
+                copy(code);
+                openPage(DEVICE);
+                // gh waits for Enter before it would open the page itself; it's already open.
+                child.stdin.write("\n");
+            }
+        };
+        child.stdout.on("data", read);
+        child.stderr.on("data", read);
+        child.on("error", () => resolve({ ok: false, detail: "gh isn't installed" }));
+        child.on("close", (status) => {
+            clearTimeout(timer);
+            resolve(status === 0 ? { ok: true, detail: "GitHub approved it" } : { ok: false, detail: out.split("\n").filter(Boolean).at(-1) ?? "GitHub didn't approve it" });
+        });
+    });
+}

package/dist/shell.js

@@ -141,3 +141,12 @@ export function commandDir(command, cwd) {
         return cwd;
     return to.startsWith("/") ? to : to.startsWith("~") ? to.replace(/^~/, process.env.HOME ?? "~") : `${cwd.replace(/\/$/, "")}/${to}`;
 }
+// Commands that change Firebase's data some other way than its MCP server.
+const FIREBASE_DATA = /\bfirebase(-tools)?\s+(firestore:|database:)|firestore\.googleapis\.com|firebaseio\.com|firebasedatabase\.app/;
+export function touchesFirebase(command, projectUsesFirebase) {
+    return FIREBASE_DATA.test(command) || (projectUsesFirebase && SCRIPT.test(command));
+}
+// A command that could change a SQLite file in the project.
+export function touchesSqlite(command) {
+    return DATABASE.test(command) || SCRIPT.test(command) || /\bsqlite3?\b|\.(db|sqlite3?|db3)\b/.test(command);
+}

package/dist/supabase.js

@@ -165,12 +165,26 @@ export function saveRest(url, key) {
     save(c);
 }
 export const restKey = (url) => load().rest?.[url.replace(/\/$/, "")] ?? null;
-export function dismissSupabase(dir) {
+export function savePostgres(url) {
     const c = load();
-    c.dismissed = [...new Set([...(c.dismissed ?? []), dir])];
+    c.postgres = { ...c.postgres, [dbKey(url)]: url };
     save(c);
 }
-export const supabaseDismissed = (dir) => (load().dismissed ?? []).includes(dir);
+export const postgresUrl = (url) => load().postgres?.[dbKey(url)] ?? null;
+export function saveFirebase(conn) {
+    const c = load();
+    c.firebase = { ...c.firebase, [conn.project]: conn };
+    save(c);
+}
+export const firebaseConn = (project) => load().firebase?.[project] ?? null;
+// "Don't ask for this project": Supabase keeps its old key (the folder), other databases add theirs.
+const dismissKey = (dir, service = "supabase") => (service === "supabase" ? dir : `${service}:${dir}`);
+export function dismissSupabase(dir, service = "supabase") {
+    const c = load();
+    c.dismissed = [...new Set([...(c.dismissed ?? []), dismissKey(dir, service)])];
+    save(c);
+}
+export const supabaseDismissed = (dir, service = "supabase") => (load().dismissed ?? []).includes(dismissKey(dir, service));
 // Checks the token works before keeping it.
 export async function saveSupabaseToken(token) {
     const projects = await api(token, "GET", "/v1/projects");

package/dist/undo.js

@@ -5,7 +5,8 @@ import { undoSql } from "./adapters/postgres.js";
 import { undoTree } from "./adapters/tree.js";
 import { discardDb, undoDb } from "./adapters/dbsnap.js";
 import { snapshotDir } from "./store.js";
-import { dbKey, freshUrl, restKey } from "./supabase.js";
+import { dbKey, firebaseConn, freshUrl, restKey } from "./supabase.js";
+import { undoFirebase } from "./adapters/firestore.js";
 import { undoRest } from "./adapters/rest.js";
 const INVERSE_TIMEOUT_MS = 20_000;
 // Database copies sit in the person's own database, so only the newest few per
@@ -39,11 +40,11 @@ function resources(store, a) {
         return new Set(u.entries.map((e) => `fs:${e.path}`));
     // A project snapshot rewinds every file under its folder, and any whole database saved with it.
     const whole = (dbs = []) => dbs.map((d) => `pgdb:${dbKey(d.url)}`);
-    const apis = (rests = []) => rests.map((r) => `pgdb:${r.url}`);
+    const apis = (rests = [], fbs = []) => [...rests.map((r) => `pgdb:${r.url}`), ...fbs.map((f) => `firebase:${f.project}`)];
     if (u.adapter === "tree")
-        return new Set([`fs:${u.root}`, ...whole(u.dbs), ...apis(u.rests)]);
+        return new Set([`fs:${u.root}`, ...whole(u.dbs), ...apis(u.rests, u.fbs)]);
     if (u.adapter === "dbs")
-        return new Set([...whole(u.dbs), ...apis(u.rests)]);
+        return new Set([...whole(u.dbs), ...apis(u.rests, u.fbs)]);
     // An opposite tool call doesn't rewind shared state, so it never conflicts.
     if (u.adapter === "inverse" || u.adapter === "engine")
         return new Set();
@@ -142,6 +143,12 @@ async function undoOne(store, a, opts = {}) {
                     throw new Error(`Backstep isn't connected to ${r.url} any more`);
                 lines.push(await undoRest(r, key));
             }
+            for (const f of u.fbs ?? []) {
+                const conn = firebaseConn(f.project);
+                if (!conn)
+                    throw new Error(`Backstep isn't connected to the Firebase project ${f.project} any more`);
+                lines.push(await undoFirebase(f, conn.credsFile));
+            }
             if (u.adapter === "tree")
                 lines.unshift(undoTree(u, a.id));
             detail = lines.filter((l) => !/^nothing had changed/.test(l)).join("\n") || lines[0];
@@ -157,7 +164,8 @@ async function undoOne(store, a, opts = {}) {
         if (u.adapter === "fs" || u.adapter === "tree")
             rmSync(snapshotDir(a.id), { recursive: true, force: true });
         const pushed = u.adapter === "tree" && u.pushed?.length ? { root: u.root, pushes: u.pushed } : undefined;
-        return { id: a.id, tool: a.tool, ok: true, detail, ...(pushed ? { pushed } : {}) };
+        const github = u.adapter === "tree" && u.github?.length ? u.github : undefined;
+        return { id: a.id, tool: a.tool, ok: true, detail, ...(pushed ? { pushed } : {}), ...(github ? { github } : {}) };
     }
     catch (err) {
         const detail = err instanceof Error ? err.message : String(err);

package/mod/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "backstep",
-  "version": "0.1.9",
+  "version": "0.1.13",
   "description": "Press ctrl+z to rewind everything Claude did in its last turn: file edits, shell commands, and database and tool changes.",
   "types": "./types/index.d.ts",
   "userConfig": {