backstep 0.0.0-stage → 0.1.0

package/dist/undo.js

@@ -0,0 +1,176 @@
+// Undoing actions, shared by the CLI and the dashboard.
+import { rmSync } from "node:fs";
+import { undoPaths } from "./adapters/fs.js";
+import { undoSql } from "./adapters/postgres.js";
+import { undoTree } from "./adapters/tree.js";
+import { snapshotDir } from "./store.js";
+import { dbKey, freshUrl } from "./supabase.js";
+const INVERSE_TIMEOUT_MS = 20_000;
+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.
+    if (u.adapter === "tree")
+        return new Set([`fs:${u.root}`]);
+    // An opposite tool call doesn't rewind shared state, so it never conflicts.
+    if (u.adapter === "inverse" || u.adapter === "engine")
+        return new Set();
+    // Keyed by database, not run, so two agents on the same database still conflict.
+    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));
+}
+// Same resource, or a file inside a folder that's rewound whole.
+function overlaps(a, b) {
+    if (a === b)
+        return true;
+    if (!a.startsWith("fs:") || !b.startsWith("fs:"))
+        return false;
+    return a.startsWith(b + "/") || b.startsWith(a + "/");
+}
+// Failed calls stay undoable: a tool can change things before it errors out.
+function undoable(a) {
+    return (a.status === "ok" || a.status === "error") && a.undo !== null;
+}
+// Undoing an action rewinds what it touched to how it was before, which would
+// silently throw away later changes to the same files or tables. So those later
+// actions are undone first, newest to oldest.
+export function undoChain(store, target) {
+    const later = store.db
+        .prepare("SELECT * FROM actions WHERE created_at >= ? AND id != ? AND status IN ('ok', 'error') AND undo IS NOT NULL ORDER BY created_at DESC, seq DESC")
+        .all(target.created_at, target.id);
+    const touched = resources(store, target);
+    const chain = [];
+    // Walk oldest-first so a conflict found later still pulls in its own dependents.
+    for (const a of [...later].reverse()) {
+        const r = resources(store, a);
+        if ([...r].some((x) => [...touched].some((t) => overlaps(x, t)))) {
+            chain.push(a);
+            for (const x of r)
+                touched.add(x);
+        }
+    }
+    return [...chain.reverse(), target];
+}
+// Inverse calls run inside the proxy that holds the connection to the server,
+// so queue the request and wait for it to report back.
+async function undoInverse(store, a, u) {
+    const live = store.db.prepare("SELECT 1 FROM runs WHERE server = ? AND ended_at IS NULL LIMIT 1").get(u.server);
+    if (!live) {
+        return { id: a.id, tool: a.tool, ok: false, detail: `start "${u.server}" again through Backstep to undo this (it runs ${u.tool})` };
+    }
+    const before = a.status;
+    if (!store.transition(a.id, before, "undo_requested")) {
+        return { id: a.id, tool: a.tool, ok: false, detail: "this action changed while undoing; try again" };
+    }
+    const deadline = Date.now() + INVERSE_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        const cur = store.getAction(a.id);
+        if (cur.status === "undone")
+            return { id: a.id, tool: a.tool, ok: true, detail: `ran ${u.tool}` };
+        if (cur.status === "undo_failed")
+            return { id: a.id, tool: a.tool, ok: false, detail: `${u.tool} failed: ${cur.error}` };
+        await new Promise((r) => setTimeout(r, 200));
+    }
+    if (store.transition(a.id, "undo_requested", before)) {
+        return { id: a.id, tool: a.tool, ok: false, detail: `no running "${u.server}" picked this up; is it still connected?` };
+    }
+    return { id: a.id, tool: a.tool, ok: false, detail: `${u.tool} is still running; check back in a moment` };
+}
+// Claude Code reports back how the call went with `backstep settle`.
+function undoEngine(store, a, u, opts) {
+    if (!opts.viaClaudeCode) {
+        return { id: a.id, tool: a.tool, ok: false, detail: `undo this with ctrl+z in Claude Code: only it is connected to ${u.server}` };
+    }
+    if (!store.transition(a.id, a.status, "undo_requested")) {
+        return { id: a.id, tool: a.tool, ok: false, detail: "this action changed while undoing; try again" };
+    }
+    return { id: a.id, tool: a.tool, ok: true, detail: `runs ${u.tool}`, run: { server: u.server, tool: u.tool, args: u.args } };
+}
+async function undoOne(store, a, opts = {}) {
+    const u = JSON.parse(a.undo);
+    if (u.adapter === "inverse")
+        return undoInverse(store, a, u);
+    if (u.adapter === "engine")
+        return undoEngine(store, a, u, opts);
+    try {
+        let detail;
+        if (u.adapter === "fs") {
+            detail = undoPaths(u);
+        }
+        else if (u.adapter === "tree") {
+            detail = undoTree(u, a.id);
+        }
+        else {
+            const url = u.url ?? store.getRun(a.run_id)?.pg_url;
+            if (!url)
+                throw new Error("this run has no database connection recorded");
+            // A temporary Supabase login may have run out since the snapshot.
+            detail = await undoSql(await freshUrl(url), u);
+        }
+        store.updateAction(a.id, { status: "undone", undone_at: Date.now() });
+        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 } : {}) };
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        store.updateAction(a.id, { status: "undo_failed", error: detail });
+        return { id: a.id, tool: a.tool, ok: false, detail };
+    }
+}
+async function runChain(store, chain, opts = {}) {
+    const out = [];
+    for (const a of chain) {
+        const r = await undoOne(store, a, opts);
+        out.push(r);
+        // Stop at the first failure: undoing older actions on top of a half-undone
+        // newer one would leave things in a state nobody asked for.
+        if (!r.ok)
+            break;
+    }
+    return out;
+}
+export async function undoAction(store, id) {
+    const a = store.getAction(id);
+    if (!a)
+        throw new Error(`no action ${id}`);
+    if (!undoable(a))
+        throw new Error(`action ${id} can't be undone (status: ${a.status}, ${a.undo ? "has" : "no"} undo data)`);
+    return runChain(store, undoChain(store, a));
+}
+export async function undoRun(store, runId) {
+    if (!store.getRun(runId))
+        throw new Error(`no run ${runId}`);
+    return undoAll(store, store.listActions(runId).filter(undoable));
+}
+// Everything any agent did in a window of time: what one turn of a chat did,
+// across Claude's own edits and every server wrapped by Backstep.
+export async function undoSince(store, since, until = Date.now(), opts = {}) {
+    const inWindow = store.db
+        .prepare("SELECT * FROM actions WHERE created_at >= ? AND created_at <= ? ORDER BY created_at, seq")
+        .all(since, until);
+    return undoAll(store, inWindow.filter(undoable), opts);
+}
+async function undoAll(store, actions, opts = {}) {
+    if (actions.length === 0)
+        return [];
+    // Start from the oldest, which pulls in every later conflict across runs too.
+    const chain = [];
+    const seen = new Set();
+    for (const a of [...actions].reverse()) {
+        for (const c of undoChain(store, a)) {
+            if (!seen.has(c.id)) {
+                seen.add(c.id);
+                chain.push(c);
+            }
+        }
+    }
+    chain.sort((x, y) => y.created_at - x.created_at || y.seq - x.seq);
+    return runChain(store, chain, opts);
+}

package/dist/watch.js

@@ -0,0 +1,138 @@
+// Tool calls to MCP servers Backstep can't sit in front of: claude.ai
+// connectors, and remote servers Claude Code signs in to. The Claude Code mod
+// reports each call before and after it runs. Backstep records it, and where
+// an undo rule matches, keeps the opposite call, which the mod runs through
+// Claude Code's own connection. Supabase SQL is snapshotted over the
+// database connection from `backstep connect supabase`.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { discardSnapshots, planSql } from "./adapters/postgres.js";
+import { planCall } from "./classify.js";
+import { buildInverse, findRule, loadRules } from "./rules.js";
+import { isWrappedServer } from "./servers.js";
+import { homeDir } from "./store.js";
+import { CONNECT_HINT, isSupabaseSql, supabaseDb, supabasePlanOptions, supabaseUrl } from "./supabase.js";
+const DELETES = /(^|_|-)(delete|remove|trash|destroy|drop|purge|erase|archive)(_|-|$)/i;
+const MAX_RESULT = 20_000;
+// The engine spells MCP tools mcp__<server>__<tool>.
+export function splitTool(name) {
+    if (!name.startsWith("mcp__"))
+        return null;
+    const rest = name.slice(5);
+    const i = rest.indexOf("__");
+    return i > 0 ? { server: rest.slice(0, i), tool: rest.slice(i + 2) } : null;
+}
+// Rules from BACKSTEP_RULES, else ~/.backstep/rules.json when there is one.
+export function watchRules() {
+    const file = process.env.BACKSTEP_RULES ?? join(homeDir(), "rules.json");
+    return existsSync(file) ? loadRules(file) : [];
+}
+// A Supabase SQL write with no database connected to snapshot it.
+function unconnected(server, tool, args) {
+    if (!isSupabaseSql(server, tool))
+        return false;
+    const plan = planCall(undefined, tool, args);
+    return plan.kind === "sql" && !supabaseDb(typeof args.project_id === "string" ? args.project_id : undefined);
+}
+export async function watchStart(store, session, cwd, name, args) {
+    const t = splitTool(name);
+    if (!t)
+        return { kind: "read" };
+    // Its own Backstep proxy records it.
+    if (isWrappedServer(t.server, cwd))
+        return unconnected(t.server, t.tool, args) ? { kind: "wrapped", hint: "supabase" } : { kind: "wrapped" };
+    const record = (kind, reason) => store.addAction({
+        run_id: store.sessionRun(t.server, `session:${session}`).id,
+        tool: t.tool,
+        args: JSON.stringify(args),
+        kind,
+        status: "running",
+        reason,
+        undo: null,
+        result: null,
+        error: null,
+        release_at: null,
+    });
+    const rule = findRule(watchRules(), t.server, t.tool);
+    const plan = rule ? null : planCall(undefined, t.tool, args);
+    if (plan?.kind === "read")
+        return { kind: "read" };
+    if (plan?.kind === "sql" && isSupabaseSql(t.server, t.tool)) {
+        const url = await supabaseUrl(typeof args.project_id === "string" ? args.project_id : undefined);
+        if (!url)
+            return { kind: "write", id: record("write", CONNECT_HINT).id, reason: CONNECT_HINT, hint: "supabase" };
+        const a = record("reversible", null);
+        try {
+            const p = await planSql(url, a.id, plan.sql, supabasePlanOptions(t.tool));
+            if (p.mode === "irreversible") {
+                store.updateAction(a.id, { kind: "irreversible", reason: p.reason });
+                return { kind: "irreversible", id: a.id, reason: p.reason };
+            }
+            // Kept now, so watchEnd can drop the snapshots if the call fails.
+            const undo = { ...p.undo, url };
+            store.updateAction(a.id, { undo: JSON.stringify(undo) });
+            return p.mode === "rewrite" ? { kind: "reversible", id: a.id, args: { [plan.argKey]: p.sql } } : { kind: "reversible", id: a.id };
+        }
+        catch (err) {
+            // Never block the call: it just won't be undoable.
+            const reason = `couldn't snapshot first: ${err instanceof Error ? err.message : String(err)}`;
+            store.updateAction(a.id, { kind: "write", reason });
+            return { kind: "write", id: a.id, reason };
+        }
+    }
+    let kind = "write";
+    let reason;
+    if (rule)
+        kind = "reversible";
+    else if (plan?.kind === "irreversible")
+        [kind, reason] = ["irreversible", `${plan.reason.replace(/ acts outside.*/, "")} can't be taken back`];
+    else if (DELETES.test(t.tool))
+        [kind, reason] = ["irreversible", "deletes something Backstep can't bring back"];
+    else
+        reason = "no undo rule for this tool";
+    return { kind, id: record(kind, reason ?? null).id, reason };
+}
+// The engine hands the mod the tool's record and the text the model read.
+function asResult(r) {
+    const rec = r.result;
+    if (rec && typeof rec === "object" && rec.structuredContent)
+        return rec;
+    if (rec && typeof rec === "object" && Array.isArray(rec.content))
+        return rec;
+    return { content: [{ type: "text", text: r.text ?? (typeof rec === "string" ? rec : JSON.stringify(rec ?? "")) }] };
+}
+export async function watchEnd(store, id, r) {
+    const a = store.getAction(id);
+    if (!a)
+        throw new Error(`no action ${id}`);
+    const result = asResult(r);
+    const text = (r.text ?? "").slice(0, MAX_RESULT);
+    const server = store.getRun(a.run_id).server;
+    const args = JSON.parse(a.args);
+    const kept = a.undo ? JSON.parse(a.undo) : null;
+    if (kept?.adapter === "pg") {
+        // Postgres runs the string as one transaction, so a failed call changed nothing.
+        if (r.isError) {
+            await discardSnapshots(kept.url, kept).catch(() => { });
+            store.updateAction(id, { status: "error", error: text, undo: null });
+            return { undoable: false };
+        }
+        store.updateAction(id, { status: "ok", result: text });
+        return { undoable: true };
+    }
+    if (r.isError) {
+        store.updateAction(id, { status: "error", error: text });
+        return { undoable: false };
+    }
+    let undo = null;
+    const rule = a.kind === "reversible" ? findRule(watchRules(), server, a.tool) : undefined;
+    if (rule) {
+        const built = buildInverse(rule, server, args, result);
+        if ("undo" in built)
+            undo = { adapter: "engine", server, tool: built.undo.tool, args: built.undo.args };
+        else
+            store.updateAction(id, { kind: "write", reason: `the result had no ${built.missing} for the undo rule` });
+    }
+    store.updateAction(id, { status: "ok", result: text, undo: undo ? JSON.stringify(undo) : null });
+    return { undoable: undo !== null };
+}

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

@@ -0,0 +1,5 @@
+{
+  "name": "backstep",
+  "owner": { "name": "Backstep" },
+  "plugins": [{ "name": "backstep", "source": "./" }]
+}

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

@@ -0,0 +1,14 @@
+{
+  "name": "backstep",
+  "version": "0.1.0",
+  "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": {
+    "cli": {
+      "type": "string",
+      "title": "Backstep CLI",
+      "description": "Path to Backstep's cli.js (run with node), or \"backstep\" if it is on your PATH. backstep setup fills this in.",
+      "default": "backstep"
+    }
+  }
+}

package/mod/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }