backstep 0.1.1 → 0.1.3

package/README.md

@@ -8,6 +8,7 @@ Undo for everything your agents touch. Backstep sits between your agent (Claude
 - **Supabase:** `execute_sql` and `apply_migration` snapshot the tables they change, over a connection to the project's database. Backstep never connects it on its own: when Claude Code opens a project that uses Supabase and isn't connected, it asks (Connect, Not now, or Don't ask for this project). Connect uses a connection string in the project's `.env` files, the local `supabase start` database, or a Supabase sign-in (`supabase login`, `SUPABASE_ACCESS_TOKEN`, or an access token you give Backstep once), with which the project gets a temporary database login that Backstep renews as it runs out. You can also ask Claude to "connect Backstep to Supabase" any time. Deleted rows, dropped tables and migrations, including the migration's history row, all come back. Works for the claude.ai Supabase connector and a local Supabase MCP server alike.
 - **Firebase:** before a change, Backstep reads what's there through the Firebase MCP server itself, and undoes through it too, so there's nothing to set up. Firestore documents updated, deleted or added; Realtime Database writes; Remote Config publishes (rolled back to the version before); and users enabled or disabled.
 - **claude.ai connectors and servers Claude Code signs in to:** Backstep can't sit in front of these, so the Claude Code mod watches their calls instead. Calls with an undo rule are undone through Claude Code's own connection.
+- **Database commands Claude runs** (`supabase db push`, `supabase migration up`, `supabase db reset`, `psql`, `prisma migrate`, `drizzle-kit push`, seed scripts…): in a project whose Supabase database is connected, the whole database is noted before the command runs, and ctrl+z puts it back in one transaction: rows, new tables dropped, dropped or altered tables rebuilt with their constraints, indexes, foreign keys, row level security policies, triggers and grants, sequence counters, and the migration history. Copies sit in a `backstep` schema in the same database; the newest 10 per database are kept. On a very big database it keeps every table's structure and the migration history, and rows smallest-table-first up to a budget (`BACKSTEP_DB_SNAPSHOT_MB`, default 250); undo names any table whose rows it couldn't bring back. Functions, views, types and extensions aren't restored.
 - **Code Claude pushed:** ctrl+z rewinds the commits locally, then asks whether to undo them on GitHub (or any remote) too. Yes pushes one new commit that undoes Claude's, made in a temporary worktree: no force push, no rewritten history, so it works on protected branches and for teammates who already pulled. Newer commits that clash, or a rewritten branch, stop it. A branch Claude created is deleted instead, if nobody has added to it. It uses the project's own git sign-in, so there's nothing to connect.
 - **Things that can't be undone** (sending email, payments, deploys, `ALTER TABLE`…) run as normal and are marked in the journal, so you know what an undo didn't cover.
 - **Anything else, by rule:** a rules file maps a tool to its opposite (`create_issue` → close the issue, `send_message` → retract it), filled in from the call and its result. See [Undo rules](#undo-rules).
@@ -52,6 +53,8 @@ With Claude Code: `claude mcp add files -- backstep wrap --name files -- <the se
 | `--rules <file>` | undo rules (or set `BACKSTEP_RULES`) |
 | `--pg <url>` | the Postgres database the wrapped server writes to. Enables database undo. Without it, SQL writes are recorded but can't be undone. |
 
+Backstep checks npm for a newer version as each Claude Code session starts and asks before updating (Update, Not now, or Skip this version; `backstep update` does it by hand, `BACKSTEP_UPDATE_CHECK=0` turns the check off).
+
 Other commands: `backstep ui`, `backstep log`, `backstep undo <action-id>`, `backstep undo --run <run-id>`, `backstep connect [supabase|firebase]` (connects what the project uses, the same as asking Claude), `backstep disconnect supabase <ref>`.
 
 In Claude Code you can just ask: "connect Backstep to everything I use". Supabase is connected from the project's settings (or the connection string you paste), and when the project uses Firebase but Claude can't reach it yet, Firebase's MCP server is added behind Backstep.

package/dist/adapters/dbsnap.js

@@ -0,0 +1,265 @@
+// Database undo for shell commands (`supabase db push`, `supabase migration up`,
+// `psql`, `prisma migrate`, seed scripts…), which change a database Backstep
+// can't see into. Before the command runs, the whole database's own tables are
+// noted:
+//  - every table's structure: columns, constraints, indexes, foreign keys,
+//    row level security and its policies, triggers, grants, sequence counters;
+//  - every table's rows, copied into Backstep's own schema in the same
+//    database, smallest tables first, until a size budget is spent. A very big
+//    database keeps its structure, its migration history and as many tables'
+//    rows as fit; undo names the tables whose rows it couldn't bring back.
+// Undo, in one transaction: drops tables made since, rebuilds tables dropped
+// or reshaped, and puts back rows wherever they changed.
+import pg from "pg";
+import { q } from "./postgres.js";
+const SNAP_SCHEMA = "backstep";
+const budget = () => Number(process.env.BACKSTEP_DB_SNAPSHOT_MB ?? 250) * 1024 * 1024;
+// Supabase's and Postgres's own schemas: managed by them, not by the project's migrations.
+const SYSTEM = [
+    "information_schema", "auth", "storage", "realtime", "_realtime", "extensions", "graphql", "graphql_public", "pgsodium",
+    "pgsodium_masks", "vault", "net", "supabase_functions", "cron", "pgbouncer", "_analytics", "_supavisor", "pgtle", "topology",
+    "tiger", "tiger_data",
+];
+const MIGRATIONS = "supabase_migrations";
+async function withClient(url, fn) {
+    const client = new pg.Client({ connectionString: url, connectionTimeoutMillis: 10_000 });
+    await client.connect();
+    try {
+        return await fn(client);
+    }
+    finally {
+        await client.end();
+    }
+}
+async function tables(c) {
+    const r = await c.query(`SELECT c.oid::int AS oid, n.nspname AS schema, c.relname AS name, pg_total_relation_size(c.oid)::bigint AS bytes
+     FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+     WHERE c.relkind = 'r' AND NOT c.relispartition
+       AND n.nspname NOT LIKE 'pg\\_%' AND n.nspname NOT LIKE 'backstep%' AND n.nspname <> ALL($1::text[])
+     ORDER BY n.nspname, c.relname`, [SYSTEM]);
+    return r.rows.map((x) => ({ oid: Number(x.oid), schema: x.schema, name: x.name, bytes: Number(x.bytes) }));
+}
+const full = (t) => `${q(t.schema)}.${q(t.name)}`;
+async function shapeOf(c, oid) {
+    const r = await c.query(`SELECT string_agg(attname || ' ' || format_type(atttypid, atttypmod), ', ' ORDER BY attnum) AS s
+     FROM pg_attribute WHERE attrelid = $1 AND attnum > 0 AND NOT attisdropped`, [oid]);
+    return r.rows[0].s ?? "";
+}
+async function describe(c, t) {
+    const name = full(t);
+    const cols = await c.query(`SELECT a.attname, format_type(a.atttypid, a.atttypmod) AS type, a.attnotnull, a.attidentity, a.attgenerated,
+            pg_get_expr(d.adbin, d.adrelid) AS def
+     FROM pg_attribute a LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+     WHERE a.attrelid = $1 AND a.attnum > 0 AND NOT a.attisdropped ORDER BY a.attnum`, [t.oid]);
+    const seqs = await c.query(`SELECT s.oid::regclass::text AS name, a.attname
+     FROM pg_depend dep JOIN pg_class s ON s.oid = dep.objid AND s.relkind = 'S'
+     JOIN pg_attribute a ON a.attrelid = dep.refobjid AND a.attnum = dep.refobjsubid
+     WHERE dep.refobjid = $1 AND dep.deptype IN ('a', 'i')`, [t.oid]);
+    const seqValues = [];
+    const create = [];
+    // Serial columns' sequences go with their table; make them first so the defaults resolve.
+    const serial = seqs.rows.filter((s) => !cols.rows.find((col) => col.attname === s.attname)?.attidentity);
+    for (const s of serial)
+        create.push(`CREATE SEQUENCE IF NOT EXISTS ${s.name}`);
+    const defs = cols.rows.map((col) => {
+        let d = `${q(col.attname)} ${col.type}`;
+        if (col.attgenerated === "s")
+            d += ` GENERATED ALWAYS AS (${col.def}) STORED`;
+        else if (col.attidentity)
+            d += ` GENERATED ${col.attidentity === "a" ? "ALWAYS" : "BY DEFAULT"} AS IDENTITY`;
+        else if (col.def !== null)
+            d += ` DEFAULT ${col.def}`;
+        if (col.attnotnull)
+            d += " NOT NULL";
+        return d;
+    });
+    create.push(`CREATE TABLE ${name} (${defs.join(", ")})`);
+    for (const s of serial)
+        create.push(`ALTER SEQUENCE ${s.name} OWNED BY ${name}.${q(s.attname)}`);
+    for (const s of seqs.rows) {
+        const v = await c.query(`SELECT last_value::text AS v, is_called FROM ${s.name}`);
+        seqValues.push({ name: s.name, value: v.rows[0].v, called: v.rows[0].is_called });
+    }
+    const cons = await c.query(`SELECT conname, contype, pg_get_constraintdef(oid) AS def FROM pg_constraint
+     WHERE conrelid = $1 AND contype IN ('p', 'u', 'c', 'x', 'f') ORDER BY contype = 'p' DESC, conname`, [t.oid]);
+    const fks = [];
+    for (const k of cons.rows) {
+        const sql = `ALTER TABLE ${name} ADD CONSTRAINT ${q(k.conname)} ${k.def}`;
+        if (k.contype === "f")
+            fks.push({ name: k.conname, sql });
+        else
+            create.push(sql);
+    }
+    const idx = await c.query(`SELECT pg_get_indexdef(i.indexrelid) AS def FROM pg_index i
+     WHERE i.indrelid = $1 AND NOT EXISTS (SELECT 1 FROM pg_constraint k WHERE k.conindid = i.indexrelid)`, [t.oid]);
+    for (const i of idx.rows)
+        create.push(i.def);
+    const rls = await c.query(`SELECT relrowsecurity, relforcerowsecurity FROM pg_class WHERE oid = $1`, [t.oid]);
+    if (rls.rows[0].relrowsecurity)
+        create.push(`ALTER TABLE ${name} ENABLE ROW LEVEL SECURITY`);
+    if (rls.rows[0].relforcerowsecurity)
+        create.push(`ALTER TABLE ${name} FORCE ROW LEVEL SECURITY`);
+    const pols = await c.query(`SELECT policyname, permissive, cmd, roles::text[] AS roles, qual, with_check FROM pg_policies WHERE schemaname = $1 AND tablename = $2`, [t.schema, t.name]);
+    for (const p of pols.rows) {
+        const roles = p.roles.map((r) => (r === "public" ? "public" : q(r))).join(", ");
+        create.push(`CREATE POLICY ${q(p.policyname)} ON ${name} AS ${p.permissive} FOR ${p.cmd} TO ${roles}` +
+            (p.qual ? ` USING (${p.qual})` : "") +
+            (p.with_check ? ` WITH CHECK (${p.with_check})` : ""));
+    }
+    // Supabase's API reaches tables through grants to anon and authenticated.
+    const grants = await c.query(`SELECT CASE WHEN g.grantee = 0 THEN 'PUBLIC' ELSE quote_ident(pg_get_userbyid(g.grantee)) END AS who, g.privilege_type AS priv
+     FROM pg_class c, aclexplode(c.relacl) g WHERE c.oid = $1 AND g.grantee <> c.relowner`, [t.oid]);
+    for (const g of grants.rows)
+        create.push(`GRANT ${g.priv} ON ${name} TO ${g.who}`);
+    const trig = await c.query(`SELECT pg_get_triggerdef(oid) AS def FROM pg_trigger WHERE tgrelid = $1 AND NOT tgisinternal`, [t.oid]);
+    return { schema: t.schema, name: t.name, shape: await shapeOf(c, t.oid), create, triggers: trig.rows.map((x) => x.def), fks, seqs: seqValues };
+}
+// The same rows in any order give the same fingerprint.
+async function fingerprint(c, table) {
+    const r = await c.query(`SELECT md5(coalesce(string_agg(h, '' ORDER BY h), '')) AS s FROM (SELECT md5(t::text) AS h FROM ${table} t) x`);
+    return r.rows[0].s;
+}
+export async function snapshotDb(actionId, url) {
+    return withClient(url, async (c) => {
+        const all = await tables(c);
+        await c.query(`CREATE SCHEMA IF NOT EXISTS ${q(SNAP_SCHEMA)}`);
+        // The migration history first, then the smallest tables: the most tables for the budget.
+        const order = [...all].sort((a, b) => Number(b.schema === MIGRATIONS) - Number(a.schema === MIGRATIONS) || a.bytes - b.bytes);
+        let spent = 0;
+        const copied = new Map();
+        let k = 0;
+        for (const t of order) {
+            if (t.schema !== MIGRATIONS && spent + t.bytes > budget())
+                continue;
+            spent += t.bytes;
+            const copy = `${actionId}_db${k++}`;
+            await c.query(`CREATE TABLE ${q(SNAP_SCHEMA)}.${q(copy)} AS TABLE ${full(t)}`);
+            copied.set(t.oid, { copy, sum: await fingerprint(c, full(t)) });
+        }
+        const out = [];
+        for (const t of all)
+            out.push({ ...(await describe(c, t)), copy: copied.get(t.oid)?.copy ?? null, sum: copied.get(t.oid)?.sum ?? null });
+        return { adapter: "db", url, tables: out };
+    });
+}
+async function insertable(c, table) {
+    const r = await c.query(`SELECT string_agg(quote_ident(attname), ', ' ORDER BY attnum) AS cols FROM pg_attribute
+     WHERE attrelid = to_regclass($1) AND attnum > 0 AND NOT attisdropped AND attgenerated = ''`, [table]);
+    return r.rows[0].cols;
+}
+async function putRows(c, t) {
+    const cols = await insertable(c, full(t));
+    const r = await c.query(`INSERT INTO ${full(t)} (${cols}) OVERRIDING SYSTEM VALUE SELECT ${cols} FROM ${q(SNAP_SCHEMA)}.${q(t.copy)}`);
+    return r.rowCount ?? 0;
+}
+const label = (t) => (t.schema === "public" ? t.name : `${t.schema}.${t.name}`);
+export async function undoDb(url, u) {
+    return withClient(url, async (c) => {
+        const log = [];
+        await c.query("BEGIN");
+        try {
+            const now = new Map((await tables(c)).map((t) => [`${t.schema}.${t.name}`, t]));
+            const was = new Map(u.tables.map((t) => [`${t.schema}.${t.name}`, t]));
+            // Made since: gone again.
+            for (const [key, t] of now) {
+                if (was.has(key))
+                    continue;
+                await c.query(`DROP TABLE IF EXISTS ${full(t)} CASCADE`);
+                log.push(`removed new table ${label(t)}`);
+            }
+            // Dropped or reshaped since: rebuilt as it was, rows and all.
+            const rebuilt = [];
+            const changed = [];
+            for (const [key, t] of was) {
+                const cur = now.get(key);
+                if (cur && (await shapeOf(c, cur.oid)) === t.shape) {
+                    if (t.copy && (await fingerprint(c, full(t))) !== t.sum)
+                        changed.push(t);
+                    continue;
+                }
+                if (cur)
+                    await c.query(`DROP TABLE ${full(t)} CASCADE`);
+                for (const sql of t.create)
+                    await c.query(sql);
+                rebuilt.push(t);
+            }
+            for (const t of rebuilt) {
+                const rows = t.copy ? await putRows(c, t) : 0;
+                log.push(t.copy
+                    ? `restored table ${label(t)} (${rows} rows)`
+                    : `restored table ${label(t)}, but not its rows: it was too big to copy`);
+            }
+            // Rows changed in a table that's still there: put the old ones back. Tables
+            // whose rows point at these come along, so no foreign key is left dangling.
+            const set = new Map(changed.map((t) => [`${t.schema}.${t.name}`, t]));
+            for (let grew = true; grew;) {
+                grew = false;
+                const refs = await c.query(`SELECT DISTINCT cn.nspname || '.' || cl.relname AS child, pn.nspname || '.' || pl.relname AS parent
+           FROM pg_constraint k JOIN pg_class cl ON cl.oid = k.conrelid JOIN pg_namespace cn ON cn.oid = cl.relnamespace
+           JOIN pg_class pl ON pl.oid = k.confrelid JOIN pg_namespace pn ON pn.oid = pl.relnamespace WHERE k.contype = 'f'`);
+                for (const r of refs.rows) {
+                    if (!set.has(r.parent) || set.has(r.child) || r.child === r.parent)
+                        continue;
+                    const child = was.get(r.child);
+                    if (!child?.copy)
+                        throw new Error(`couldn't put back the rows of ${label(set.get(r.parent))}: ${r.child} points at them and was too big to copy`);
+                    set.set(r.child, child);
+                    grew = true;
+                }
+            }
+            if (set.size) {
+                const list = [...set.values()];
+                for (const t of list)
+                    await c.query(`ALTER TABLE ${full(t)} DISABLE TRIGGER USER`);
+                await c.query(`TRUNCATE ${list.map(full).join(", ")}`);
+                // Parents before the tables that point at them.
+                const left = new Set(set.keys());
+                const deps = await c.query(`SELECT cn.nspname || '.' || cl.relname AS child, pn.nspname || '.' || pl.relname AS parent
+           FROM pg_constraint k JOIN pg_class cl ON cl.oid = k.conrelid JOIN pg_namespace cn ON cn.oid = cl.relnamespace
+           JOIN pg_class pl ON pl.oid = k.confrelid JOIN pg_namespace pn ON pn.oid = pl.relnamespace WHERE k.contype = 'f'`);
+                while (left.size) {
+                    const ready = [...left].filter((k) => !deps.rows.some((d) => d.child === k && d.parent !== k && left.has(d.parent)));
+                    const batch = ready.length ? ready : [...left];
+                    for (const key of batch) {
+                        const t = set.get(key);
+                        log.push(`restored ${await putRows(c, t)} rows in ${label(t)}`);
+                        left.delete(key);
+                    }
+                }
+                for (const t of list)
+                    await c.query(`ALTER TABLE ${full(t)} ENABLE TRIGGER USER`);
+            }
+            // Triggers on rebuilt tables once their rows are in, then every foreign key a drop took with it.
+            for (const t of rebuilt)
+                for (const sql of t.triggers)
+                    await c.query(sql);
+            for (const t of u.tables) {
+                for (const fk of t.fks) {
+                    const has = await c.query(`SELECT 1 FROM pg_constraint WHERE conrelid = to_regclass($1) AND conname = $2`, [full(t), fk.name]);
+                    if (has.rowCount === 0)
+                        await c.query(fk.sql);
+                }
+            }
+            // Counters, so new rows don't collide with restored ones.
+            for (const t of [...rebuilt, ...set.values()]) {
+                for (const s of t.seqs)
+                    await c.query(`SELECT setval($1, $2::bigint, $3)`, [s.name, s.value, s.called]);
+            }
+            await c.query("COMMIT");
+        }
+        catch (err) {
+            await c.query("ROLLBACK");
+            throw err;
+        }
+        await dropCopies(c, u);
+        return log.length ? log.join("\n") : "nothing had changed in the database";
+    });
+}
+async function dropCopies(c, u) {
+    for (const t of u.tables)
+        if (t.copy)
+            await c.query(`DROP TABLE IF EXISTS ${q(SNAP_SCHEMA)}.${q(t.copy)}`);
+}
+export async function discardDb(u) {
+    await withClient(u.url, (c) => dropCopies(c, u)).catch(() => { });
+}

package/dist/cli.js

@@ -4,12 +4,14 @@ import { fileURLToPath } from "node:url";
 import { runProxy } from "./proxy.js";
 import { startUi } from "./ui/server.js";
 import { Store, snapshotDir } from "./store.js";
-import { undoAction, undoRun, undoSince } from "./undo.js";
+import { pruneDatabaseCopies, undoAction, undoRun, undoSince } from "./undo.js";
 import { snapshotPaths } from "./adapters/fs.js";
 import { notePushed, snapshotTree } from "./adapters/tree.js";
 import { revertPush } from "./push.js";
+import { snapshotDb } from "./adapters/dbsnap.js";
+import { projectDatabases } from "./connect.js";
 const PUSH = /\bgit\b[^;&|]*\bpush\b/;
-import { classifyShell } from "./shell.js";
+import { classifyShell, supabaseTarget, touchesDatabase } from "./shell.js";
 import { watchEnd, watchStart } from "./watch.js";
 import { sendActive } from "./telemetry.js";
 import { readFileSync, rmSync } from "node:fs";
@@ -20,6 +22,7 @@ import { disconnectSupabase, dismissSupabase } from "./supabase.js";
 import { connect } from "./connect.js";
 import { check, printCheck } from "./check.js";
 import { logo } from "./look.js";
+import { checkUpdate, runUpdate, skipVersion } from "./update.js";
 import { askConnectionString } from "./setup.js";
 // Header values can name env vars, so tokens don't have to sit in agent config files.
 function parseHeaders(list) {
@@ -57,6 +60,7 @@ const HELP = `backstep: undo for everything your agents touch
                                Supabase from the project's .env files or local database (or the
                                connection string you give), Firebase by adding its MCP server.
                                In Claude Code you can just ask: "connect Backstep to my Supabase"
+  backstep update               install the newest version (Claude Code offers this as a session starts)
   backstep status [--json]     what Backstep can and can't undo for each service Claude Code reaches,
                                and what to connect next
   backstep disconnect supabase <ref>
@@ -208,6 +212,27 @@ async function main() {
         }
         return;
     }
+    // Run by the Claude Code mod as a session starts: is there a newer Backstep?
+    if (cmd === "update-check") {
+        console.log(JSON.stringify(await checkUpdate()));
+        return;
+    }
+    // `backstep update` installs the newest version; --skip <v> stops asking about that one.
+    if (cmd === "update") {
+        const { values } = parseArgs({ args: rest, options: { skip: { type: "string" }, version: { type: "string" }, json: { type: "boolean", default: false } } });
+        if (values.skip) {
+            skipVersion(values.skip);
+            return;
+        }
+        const target = values.version ?? (await checkUpdate()).latest;
+        if (!target)
+            throw new Error("couldn't reach npm to find the newest version");
+        const out = runUpdate(target);
+        console.log(values.json ? JSON.stringify(out) : out.ok ? `Backstep ${out.detail}. Restart Claude Code to use it.` : `Update failed: ${out.detail}`);
+        if (!out.ok)
+            process.exitCode = 1;
+        return;
+    }
     if (cmd === "disconnect") {
         const [service, ref] = rest;
         if (service !== "supabase" || !ref)
@@ -294,12 +319,35 @@ async function main() {
         });
         // Outbound commands still get a snapshot: whatever they change locally can come back.
         // A push also notes where the remote branches stood, so undo can take it back there too.
-        const undo = snapshotTree(a.id, values.cwd ?? process.cwd(), { pushes: PUSH.test(command) });
+        const cwd = values.cwd ?? process.cwd();
+        const tree = snapshotTree(a.id, cwd, { pushes: PUSH.test(command) });
+        // A migration, reset, seed or raw SQL: the connected databases it could change are noted too.
+        const dbs = [];
+        const missed = [];
+        if (touchesDatabase(command)) {
+            for (const url of await projectDatabases(cwd, supabaseTarget(command))) {
+                try {
+                    dbs.push(await snapshotDb(a.id, url));
+                }
+                catch (err) {
+                    missed.push(err instanceof Error ? err.message : String(err));
+                }
+            }
+        }
+        const undo = tree ? { ...tree, ...(dbs.length ? { dbs } : {}) } : dbs.length ? { adapter: "dbs", dbs } : null;
         if (undo)
             store.updateAction(a.id, { undo: JSON.stringify(undo) });
-        else if (plan.kind !== "outbound")
+        // With its database saved, a command that reaches it is no longer lost to undo.
+        const kind = plan.kind === "outbound" && dbs.length && plan.reason === "changes a database directly" ? "write" : plan.kind;
+        if (kind !== plan.kind)
+            store.updateAction(a.id, { kind: "reversible", reason: null });
+        if (!undo && kind !== "outbound")
             store.updateAction(a.id, { kind: "write", reason: "project too large to snapshot" });
-        console.log(JSON.stringify({ kind: plan.kind, reason: plan.reason, id: a.id, undoable: undo !== null }));
+        if (missed.length)
+            store.updateAction(a.id, { reason: `couldn't save the database first: ${missed[0]}` });
+        if (dbs.length)
+            await pruneDatabaseCopies(store).catch(() => { });
+        console.log(JSON.stringify({ kind, reason: kind === plan.kind ? plan.reason : undefined, id: a.id, undoable: undo !== null, db: dbs.length }));
         return;
     }
     // After a shell command that pushed: notes what it sent (run by the Claude Code mod).

package/dist/connect.js

@@ -12,7 +12,7 @@ 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";
+import { connectSupabase, hasSavedToken, LOCAL, mintSupabase, projectRef, saveSupabaseToken, supabaseDb, 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"];
@@ -105,6 +105,23 @@ function linkedRef(dir) {
     }
     return undefined;
 }
+// The connected databases a command in this folder could change: only ones the
+// person connected, so a database is never touched without their say.
+export async function projectDatabases(dir, target) {
+    const out = [];
+    const ref = linkedRef(dir);
+    if (target !== "local" && ref && supabaseProjects().includes(ref)) {
+        const url = await supabaseUrl(ref);
+        if (url)
+            out.push(url);
+    }
+    if (target !== "hosted" && projectUses(dir).supabase) {
+        const local = supabaseDb(LOCAL);
+        if (local)
+            out.push(local);
+    }
+    return out;
+}
 // 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);

package/dist/shell.js

@@ -110,3 +110,18 @@ export function classifyShell(command) {
         return { kind: "read" };
     return { kind: "write" };
 }
+// Commands that change a database through its own tools rather than Claude's:
+// migrations, resets, seeds and raw SQL.
+const DATABASE = /(^|[\s;&|(])(npx\s+|pnpm\s+(dlx\s+)?|bunx\s+|yarn\s+)?(supabase\s+(db|migration|seed)\b|psql\b|pg_restore\b|prisma\s+(migrate|db)\b|drizzle-kit\s+(push|migrate)\b|knex\s+(migrate|seed)|sequelize(-cli)?\s+db:|typeorm\s+(migration|schema)|node-pg-migrate\b|dbmate\b|goose\b|sqlx\s+(migrate|database)\b|alembic\b|(rails|rake)\s+db:|python3?\s+manage\.py\s+(migrate|flush|loaddata)\b)/;
+export function touchesDatabase(command) {
+    return DATABASE.test(command);
+}
+// Which of a project's databases a Supabase command aims at: `db push` and
+// --linked mean the hosted project, the rest default to the local one.
+export function supabaseTarget(command) {
+    if (!/\bsupabase\s+(db|migration|seed)\b/.test(command))
+        return "both";
+    if (/--local\b/.test(command))
+        return "local";
+    return /--linked\b|--db-url\b|\bdb\s+push\b/.test(command) ? "hosted" : "local";
+}

package/dist/store.js

@@ -114,6 +114,12 @@ export class Store {
         const r = this.db.prepare("UPDATE actions SET status = ? WHERE id = ? AND status = ?").run(to, id, from);
         return r.changes === 1;
     }
+    // Actions still holding a copy of a database, newest first.
+    databaseCopies() {
+        return this.db
+            .prepare(`SELECT * FROM actions WHERE undo LIKE '%"adapter":"db"%' AND status IN ('ok', 'error') ORDER BY created_at DESC`)
+            .all();
+    }
     getAction(id) {
         return this.db.prepare("SELECT * FROM actions WHERE id = ?").get(id);
     }

package/dist/telemetry.js

@@ -29,7 +29,7 @@ function installId() {
     writeFileSync(file, id + "\n", { mode: 0o600 });
     return id;
 }
-function version() {
+export function version() {
     const pkg = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
     return JSON.parse(readFileSync(pkg, "utf8")).version;
 }

package/dist/undo.js

@@ -3,18 +3,45 @@ import { rmSync } from "node:fs";
 import { undoPaths } from "./adapters/fs.js";
 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 } from "./supabase.js";
 const INVERSE_TIMEOUT_MS = 20_000;
+// Database copies sit in the person's own database, so only the newest few per
+// database are kept; older commands keep their file undo but not their database undo.
+const KEEP_DB_COPIES = 10;
+export async function pruneDatabaseCopies(store) {
+    const seen = new Map();
+    for (const a of store.databaseCopies()) {
+        const u = JSON.parse(a.undo);
+        const keep = [];
+        for (const d of u.dbs ?? []) {
+            const k = dbKey(d.url);
+            const n = (seen.get(k) ?? 0) + 1;
+            seen.set(k, n);
+            if (n <= KEEP_DB_COPIES)
+                keep.push(d);
+            else
+                await discardDb({ ...d, url: await freshUrl(d.url) });
+        }
+        if (keep.length === (u.dbs ?? []).length)
+            continue;
+        const next = u.adapter === "dbs" ? (keep.length ? { ...u, dbs: keep } : null) : { ...u, dbs: keep.length ? keep : undefined };
+        store.updateAction(a.id, { undo: next ? JSON.stringify(next) : null, ...(next ? {} : { kind: "write", reason: "its database copy was cleared to save space" }) });
+    }
+}
 function resources(store, a) {
     const u = a.undo ? JSON.parse(a.undo) : null;
     if (!u)
         return new Set();
     if (u.adapter === "fs")
         return new Set(u.entries.map((e) => `fs:${e.path}`));
-    // A project snapshot rewinds every file under its folder.
+    // 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)}`);
     if (u.adapter === "tree")
-        return new Set([`fs:${u.root}`]);
+        return new Set([`fs:${u.root}`, ...whole(u.dbs)]);
+    if (u.adapter === "dbs")
+        return new Set(whole(u.dbs));
     // An opposite tool call doesn't rewind shared state, so it never conflicts.
     if (u.adapter === "inverse" || u.adapter === "engine")
         return new Set();
@@ -22,7 +49,7 @@ function resources(store, a) {
     const url = u.url ?? store.getRun(a.run_id)?.pg_url;
     const db = url ? dbKey(url) : a.run_id;
     const pgKey = (t) => `pg:${db}:${t.schema}.${t.name}`;
-    return new Set([...u.snapshots, ...u.trashed, ...u.created].map(pgKey));
+    return new Set([...u.snapshots, ...u.trashed, ...u.created].map(pgKey).concat(url ? [`pgdb:${dbKey(url)}`] : []));
 }
 // Same resource, or a file inside a folder that's rewound whole.
 function overlaps(a, b) {
@@ -102,8 +129,14 @@ async function undoOne(store, a, opts = {}) {
         if (u.adapter === "fs") {
             detail = undoPaths(u);
         }
-        else if (u.adapter === "tree") {
-            detail = undoTree(u, a.id);
+        else if (u.adapter === "tree" || u.adapter === "dbs") {
+            // The databases first: their undo is one transaction each, so a failure leaves everything as it was.
+            const lines = [];
+            for (const d of u.dbs ?? [])
+                lines.push(await undoDb(await freshUrl(d.url), d));
+            if (u.adapter === "tree")
+                lines.unshift(undoTree(u, a.id));
+            detail = lines.filter((l) => !/^nothing had changed/.test(l)).join("\n") || lines[0];
         }
         else {
             const url = u.url ?? store.getRun(a.run_id)?.pg_url;

package/dist/update.js

@@ -0,0 +1,67 @@
+// Keeping Backstep current. As each Claude Code session starts, the mod asks
+// whether npm has a newer version; if so it asks the person, and an update
+// runs the new version's own setup, the same command a first install runs.
+// Off with BACKSTEP_UPDATE_CHECK=0.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homeDir } from "./store.js";
+import { version } from "./telemetry.js";
+const REGISTRY = process.env.BACKSTEP_REGISTRY ?? "https://registry.npmjs.org";
+const file = () => join(homeDir(), "settings.json");
+function settings() {
+    try {
+        return existsSync(file()) ? JSON.parse(readFileSync(file(), "utf8")) : {};
+    }
+    catch {
+        return {};
+    }
+}
+// 1.2.10 > 1.2.9; anything after a dash (a pre-release) counts as older than without.
+export function newer(a, b) {
+    const parse = (v) => {
+        const [main, pre] = v.split("-", 2);
+        return { nums: main.split(".").map((n) => Number(n) || 0), pre: pre ?? null };
+    };
+    const x = parse(a);
+    const y = parse(b);
+    for (let i = 0; i < 3; i++)
+        if ((x.nums[i] ?? 0) !== (y.nums[i] ?? 0))
+            return (x.nums[i] ?? 0) > (y.nums[i] ?? 0);
+    return x.pre === null && y.pre !== null;
+}
+// Never slow: a session doesn't wait more than a few seconds on npm.
+export async function checkUpdate() {
+    const current = version();
+    if (/^(0|false|off|no)$/i.test(process.env.BACKSTEP_UPDATE_CHECK ?? ""))
+        return { current, latest: null, available: false };
+    let latest = null;
+    try {
+        const r = await fetch(`${REGISTRY}/backstep/latest`, { signal: AbortSignal.timeout(4000) });
+        if (r.ok)
+            latest = (await r.json()).version ?? null;
+    }
+    catch {
+        // offline: nothing to offer
+    }
+    const available = latest !== null && newer(latest, current) && settings().skipVersion !== latest;
+    return { current, latest, available };
+}
+export function skipVersion(v) {
+    mkdirSync(homeDir(), { recursive: true });
+    writeFileSync(file(), JSON.stringify({ ...settings(), skipVersion: v }, null, 2) + "\n");
+}
+// The new version's setup puts its own copy in place, points Claude Code's mod
+// at it and re-wraps servers, exactly as a fresh install would.
+export function runUpdate(v) {
+    const r = spawnSync("npx", ["-y", `backstep@${v}`, "setup"], {
+        encoding: "utf8",
+        timeout: 5 * 60 * 1000,
+        env: { ...process.env, NO_COLOR: "1", BACKSTEP_TELEMETRY: "0" },
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (r.status === 0)
+        return { ok: true, detail: `updated to ${v}` };
+    const why = `${r.stderr ?? ""}${r.stdout ?? ""}`.trim().split("\n").filter(Boolean).at(-1) ?? "npx failed";
+    return { ok: false, detail: why.replace(/^backstep: /, "") };
+}

package/mod/hooks/register.test.tsx

@@ -172,16 +172,23 @@ test('servers added since setup are wrapped as a session starts', { options: { c
     tools.push(e.name)
     return { value: { tool: `mcp__backstep__${e.name}` } }
   })
+  const logs: string[] = []
+  on('ui.log', (_, e) => {
+    logs.push(e.text)
+    return { value: undefined }
+  })
   on('session.start', (_, e) => ({ cwd: e.cwd }))
 
   await $.session.start({ cwd: '/repo', surface: 'terminal', hasPerson: true } as never)
   await new Promise((r) => setTimeout(r, 10))
   expect(tools).toEqual(['connect'])
+  expect(logs[0]).toContain('Backstep connected')
   expect(runs).toEqual([
     ['node', '--disable-warning=ExperimentalWarning', CLI, 'wrap-servers', '--project', '/repo', '--json'],
     ['node', '--disable-warning=ExperimentalWarning', CLI, 'connect', '--dir', '/repo', '--json', '--auto'],
     ['node', '--disable-warning=ExperimentalWarning', CLI, 'ping'],
     ['node', '--disable-warning=ExperimentalWarning', CLI, 'status', '--quick', '--json', '--dir', '/repo'],
+    ['node', '--disable-warning=ExperimentalWarning', CLI, 'update-check'],
   ])
   expect(toasts.find((t) => t.includes('linear is now behind Backstep'))).toBeTruthy()
   // Supabase gets its own question, and only in a project that uses it.
@@ -430,3 +437,50 @@ test('after undoing a turn that pushed, Backstep asks and pushes the undo', { op
   expect((await ui.find({ type: 'Text', text: /Rewound/ }))?.text).not.toContain("couldn't be undone")
   await ui.unmount()
 })
+
+function updates(on: On, answer: string) {
+  const runs: string[][] = []
+  const toasts: string[] = []
+  const asked: string[] = []
+  on('process.run', (_, e) => {
+    runs.push([...e.argv])
+    const stdout = e.argv.includes('update-check')
+      ? JSON.stringify({ current: '0.1.2', latest: '0.2.0', available: true })
+      : e.argv.includes('update') && e.argv.includes('--json')
+        ? JSON.stringify({ ok: true, detail: 'updated to 0.2.0' })
+        : e.argv.includes('status')
+          ? JSON.stringify({ items: [], suggest: [] })
+          : '[]'
+    return { value: { exitCode: 0, stdout, stderr: '', isStdoutTruncated: false, isStderrTruncated: false } }
+  })
+  on('ui.toast', (_, e) => {
+    toasts.push(e.text)
+    return { value: undefined }
+  })
+  on('ui.log', () => ({ value: undefined }))
+  on('tool.register', (_, e) => ({ value: { tool: `mcp__backstep__${e.name}` } }))
+  on('tool.call', { tool: 'AskUserQuestion' }, (_, e) => {
+    const questions = (e as unknown as { questions: { question: string }[] }).questions
+    asked.push(questions[0].question)
+    return { result: { questions, answers: { [questions[0].question]: answer } } }
+  })
+  on('session.start', (_, e) => ({ cwd: e.cwd }))
+  return { runs, toasts, asked }
+}
+
+test('a newer version is offered as a session starts, and Update installs it', { options: { cli: CLI } }, async ($, on) => {
+  const { runs, toasts, asked } = updates(on, 'Update')
+  await $.session.start({ cwd: '/repo', surface: 'terminal', hasPerson: true } as never)
+  await settle()
+  expect(asked).toEqual(['Backstep 0.2.0 is out (you have 0.1.2). Update now?'])
+  expect(runs.some((r) => r.slice(3).join(' ') === 'update --version 0.2.0 --json')).toBe(true)
+  expect(toasts.at(-1)).toBe('Backstep updated to 0.2.0. Restart Claude Code to use it.')
+})
+
+test('Skip this version stops asking about it, and Not now changes nothing', { options: { cli: CLI } }, async ($, on) => {
+  const { runs } = updates(on, 'Skip this version')
+  await $.session.start({ cwd: '/repo', surface: 'terminal', hasPerson: true } as never)
+  await settle()
+  expect(runs.some((r) => r.slice(3).join(' ') === 'update --skip 0.2.0')).toBe(true)
+  expect(runs.some((r) => r.includes('--version'))).toBe(false)
+})

package/mod/hooks/register.tsx

@@ -298,7 +298,7 @@ async function checkCoverage($: EngineInterface, cwd: string) {
   const found = await $.process.run(backstep(['connect', '--dir', cwd, '--json', '--auto']), { timeoutMs: 120_000 }).catch(() => null)
   try {
     for (const c of JSON.parse(found?.stdout || '[]') as Connected[]) {
-      if (c.service === 'supabase' && c.state === 'ask') void askSupabase($, cwd)
+      if (c.service === 'supabase' && c.state === 'ask') await askSupabase($, cwd)
       if (c.state === 'added') $.ui.toast('Backstep added Firebase for this project, so Claude can reach it and its changes can be undone. Restart Claude Code to use it.')
     }
   } catch {
@@ -352,6 +352,39 @@ async function askSupabase($: EngineInterface, cwd: string) {
   $.ui.toast('Backstep needs a Supabase sign-in for this. Ask Claude to "connect Backstep to Supabase" and it will walk you through it.')
 }
 
+const UPDATE = { yes: 'Update', later: 'Not now', skip: 'Skip this version' }
+
+// A newer Backstep on npm: asked as a session starts, installed only on a yes.
+async function offerUpdate($: EngineInterface) {
+  const ran = await $.process.run(backstep(['update-check']), { timeoutMs: 15_000 }).catch(() => null)
+  let u: { current?: string; latest?: string | null; available?: boolean } = {}
+  try {
+    u = JSON.parse(ran?.stdout || '{}') as typeof u
+  } catch {
+    return
+  }
+  if (!u.available || !u.latest) return
+  const answer = await $.ui
+    .ask(`Backstep ${u.latest} is out (you have ${u.current}). Update now?`, { header: 'Backstep', options: [UPDATE.yes, UPDATE.later, UPDATE.skip] })
+    .catch(() => null)
+  if (answer === UPDATE.skip) {
+    await $.process.run(backstep(['update', '--skip', u.latest])).catch(() => null)
+    return
+  }
+  if (answer !== UPDATE.yes) return
+  $.ui.toast(`Updating Backstep to ${u.latest}…`)
+  const done = await $.process
+    .run(backstep(['update', '--version', u.latest, '--json']), { timeoutMs: 300_000 })
+    .catch((err: unknown) => ({ exitCode: 1, stdout: '', stderr: err instanceof Error ? err.message : String(err) }))
+  let r: { ok: boolean; detail: string } = { ok: false, detail: (done.stderr || 'it failed').trim().split('\n').at(-1) ?? 'it failed' }
+  try {
+    r = JSON.parse(done.stdout) as typeof r
+  } catch {
+    // keep the error above
+  }
+  $.ui.toast(r.ok ? `Backstep ${r.detail}. Restart Claude Code to use it.` : `Backstep couldn't update: ${r.detail}. Try: npx backstep@latest setup`)
+}
+
 const CONNECT = 'mcp__backstep__connect'
 
 const CONNECT_TOOL = {
@@ -403,9 +436,12 @@ export const register: Register = (on, options) => {
   on('session.start', async ($, e, next) => {
     await $.tool.register(CONNECT_TOOL)
     const r = await next(e)
+    // Said first thing, so nobody has to wonder whether it's running.
+    $.ui.log("✓ Backstep connected · press ctrl+z to undo Claude's last turn")
     // In the background: a session never waits on either.
     void wrapNewServers($, e.cwd)
-    void checkCoverage($, e.cwd)
+    // One question at a time: Supabase first, then any update.
+    void checkCoverage($, e.cwd).then(() => offerUpdate($))
     void $.process.run(backstep(['ping'])).catch(() => null)
     return r
   })
@@ -449,7 +485,8 @@ export const register: Register = (on, options) => {
       const sid = await $.session.id()
       // Never blocks the command: if Backstep can't be reached it just won't be undoable.
       const ran = await $.process
-        .run(backstep(['shell', '--session', sid, '--cwd', cwd, '--', command]), { timeoutMs: 60_000 })
+        // A database command copies the database first, which takes longer on a big one.
+        .run(backstep(['shell', '--session', sid, '--cwd', cwd, '--', command]), { timeoutMs: 180_000 })
         .catch(() => null)
       let plan: ShellPlan | null = null
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backstep",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Undo for everything your agents touch: an MCP proxy that makes agent actions reversible.",
   "scripts": {
     "dev": "node src/cli.ts",