backstep 0.0.0-stage → 0.1.0

package/dist/proxy.js

@@ -0,0 +1,285 @@
+// The proxy: speaks MCP to the agent on stdio, runs the real server as a child
+// process, and decides per call whether to snapshot or just pass through.
+import { rmSync } from "node:fs";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, ToolListChangedNotificationSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { planCall } from "./classify.js";
+import { snapshotPaths } from "./adapters/fs.js";
+import { discardSnapshots, planSql } from "./adapters/postgres.js";
+import { firebasePlan, ReadFailed } from "./firebase.js";
+import { buildInverse, findRule } from "./rules.js";
+import { CONNECT_HINT, isSupabaseSql, refFromArgs, supabasePlanOptions, supabaseUrl } from "./supabase.js";
+import { snapshotDir, Store } from "./store.js";
+const CALL_TIMEOUT_MS = 10 * 60 * 1000;
+const UNDO_POLL_MS = 500;
+function summarize(result) {
+    const text = (result.content ?? [])
+        .map((c) => (c.type === "text" ? c.text : `[${c.type}]`))
+        .join("\n");
+    return text.length > 2000 ? `${text.slice(0, 2000)}…` : text;
+}
+function textResult(text, isError = false) {
+    return { content: [{ type: "text", text }], isError };
+}
+export async function runProxy(opts) {
+    const store = new Store();
+    const target = opts.url ?? [opts.command, ...opts.args].join(" ");
+    const run = store.createRun(opts.name, target, opts.pgUrl);
+    const log = (msg) => process.stderr.write(`[backstep:${opts.name}] ${msg}\n`);
+    const upstream = await connectUpstream(opts);
+    const caps = upstream.getServerCapabilities() ?? {};
+    const info = upstream.getServerVersion();
+    const server = new Server({ name: `backstep:${info?.name ?? opts.name}`, version: info?.version ?? "0.0.0" }, {
+        capabilities: {
+            tools: { listChanged: true },
+            ...(caps.resources ? { resources: {} } : {}),
+            ...(caps.prompts ? { prompts: {} } : {}),
+        },
+        instructions: upstream.getInstructions(),
+    });
+    const tools = new Map();
+    const refreshTools = async () => {
+        tools.clear();
+        let cursor;
+        do {
+            const page = await upstream.listTools(cursor ? { cursor } : {});
+            for (const t of page.tools)
+                tools.set(t.name, t);
+            cursor = page.nextCursor;
+        } while (cursor);
+    };
+    await refreshTools();
+    upstream.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+        await refreshTools();
+        await server.sendToolListChanged();
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [...tools.values()] }));
+    if (caps.resources) {
+        server.setRequestHandler(ListResourcesRequestSchema, (req) => upstream.listResources(req.params));
+        server.setRequestHandler(ListResourceTemplatesRequestSchema, (req) => upstream.listResourceTemplates(req.params));
+        server.setRequestHandler(ReadResourceRequestSchema, (req) => upstream.readResource(req.params));
+    }
+    if (caps.prompts) {
+        server.setRequestHandler(ListPromptsRequestSchema, (req) => upstream.listPrompts(req.params));
+        server.setRequestHandler(GetPromptRequestSchema, (req) => upstream.getPrompt(req.params));
+    }
+    const forward = async (name, args) => (await upstream.callTool({ name, arguments: args }, undefined, {
+        timeout: CALL_TIMEOUT_MS,
+        resetTimeoutOnProgress: true,
+    }));
+    const record = (tool, args, kind, reason) => store.addAction({
+        run_id: run.id,
+        tool,
+        args: JSON.stringify(args),
+        kind,
+        status: "running",
+        reason,
+        undo: null,
+        result: null,
+        error: null,
+        release_at: null,
+    });
+    const finish = async (a, undo, call) => {
+        try {
+            const result = await call();
+            store.updateAction(a.id, {
+                status: result.isError ? "error" : "ok",
+                undo: undo ? JSON.stringify(undo) : null,
+                result: summarize(result),
+            });
+            return result;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            // Keep undo data on failure: the call may have changed things before it threw.
+            store.updateAction(a.id, { status: "error", undo: undo ? JSON.stringify(undo) : null, error: msg });
+            throw err;
+        }
+    };
+    // Runs a call Backstep can't take back, recording why.
+    const unguarded = (a, name, args, kind, reason) => {
+        store.updateAction(a.id, { kind, reason });
+        return finish(a, null, () => forward(name, args));
+    };
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const name = req.params.name;
+        const args = (req.params.arguments ?? {});
+        if (!tools.has(name))
+            await refreshTools();
+        const rule = findRule(opts.rules, opts.name, name);
+        if (rule) {
+            const a = record(name, args, "reversible", null);
+            const result = await finish(a, null, () => forward(name, args));
+            if (!result.isError) {
+                const built = buildInverse(rule, opts.name, args, result);
+                if ("undo" in built)
+                    store.updateAction(a.id, { undo: JSON.stringify(built.undo) });
+                else
+                    store.updateAction(a.id, { kind: "write", reason: `undo rule needs "${built.missing}", which wasn't there` });
+            }
+            return result;
+        }
+        // Firebase: read what's there through the server first, then keep the call that puts it back.
+        const fb = firebasePlan(name, args);
+        if (fb) {
+            const a = record(name, args, "reversible", null);
+            const before = fb.read ? await forward(fb.read.tool, fb.read.args).catch(() => null) : null;
+            const result = await finish(a, null, () => forward(name, args));
+            if (result.isError)
+                return result;
+            try {
+                const inv = fb.undo(before, result);
+                if (inv)
+                    store.updateAction(a.id, { undo: JSON.stringify({ adapter: "inverse", server: opts.name, ...inv }) });
+                else
+                    store.updateAction(a.id, { reason: "nothing changed" });
+            }
+            catch (err) {
+                if (!(err instanceof ReadFailed))
+                    throw err;
+                store.updateAction(a.id, { kind: "write", reason: err.message });
+            }
+            return result;
+        }
+        const plan = planCall(tools.get(name), name, args);
+        switch (plan.kind) {
+            case "read": {
+                const a = record(name, args, "read", null);
+                return finish(a, null, () => forward(name, args));
+            }
+            case "write": {
+                const a = record(name, args, "write", "Backstep has no way to snapshot what this tool changes");
+                return finish(a, null, () => forward(name, args));
+            }
+            case "irreversible": {
+                const a = record(name, args, "irreversible", plan.reason);
+                return finish(a, null, () => forward(name, args));
+            }
+            case "paths": {
+                const a = record(name, args, "reversible", null);
+                const undo = snapshotPaths(a.id, plan.paths, process.cwd());
+                if (!undo) {
+                    rmSync(snapshotDir(a.id), { recursive: true, force: true });
+                    return unguarded(a, name, args, "write", "the files are too large to snapshot");
+                }
+                return finish(a, undo, () => forward(name, args));
+            }
+            case "sql": {
+                const a = record(name, args, "reversible", null);
+                const supabase = isSupabaseSql(opts.name, name, target);
+                const pgUrl = opts.pgUrl ?? (supabase ? await supabaseUrl(refFromArgs(args, opts.args)) : null);
+                if (!pgUrl)
+                    return unguarded(a, name, args, "write", supabase ? CONNECT_HINT : "database writes can't be undone without --pg");
+                let p;
+                try {
+                    p = await planSql(pgUrl, a.id, plan.sql, supabase ? supabasePlanOptions(name) : {});
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    store.updateAction(a.id, { status: "error", error: msg });
+                    return textResult(`Backstep could not run this SQL: ${msg}`, true);
+                }
+                if (p.mode === "irreversible")
+                    return unguarded(a, name, args, "irreversible", p.reason);
+                if (p.mode === "self") {
+                    return finish(a, p.undo, async () => textResult(`${p.summary}\n\n(Backstep kept a restorable copy of any dropped table.)`));
+                }
+                const undo = { ...p.undo, ...(pgUrl !== opts.pgUrl ? { url: pgUrl } : {}) };
+                const sent = p.mode === "rewrite" ? { ...args, [plan.argKey]: p.sql } : args;
+                const result = await finish(a, undo, () => forward(name, sent));
+                // Postgres runs a multi-statement string as one implicit transaction, so a
+                // failed call changed nothing and the snapshots are dead weight.
+                if (result.isError) {
+                    await discardSnapshots(pgUrl, undo).catch(() => { });
+                    store.updateAction(a.id, { undo: null });
+                }
+                return result;
+            }
+        }
+    });
+    // Undo by inverse tool call has to go through a live connection to the server,
+    // so the dashboard queues the request and whichever proxy serves that server
+    // name runs it, including requests left over from earlier sessions.
+    let undoing = false;
+    const undoTimer = setInterval(async () => {
+        if (undoing)
+            return;
+        undoing = true;
+        try {
+            const pending = store.db
+                .prepare(`SELECT a.* FROM actions a JOIN runs r ON r.id = a.run_id
+           WHERE a.status = 'undo_requested' AND r.server = ? ORDER BY a.created_at DESC`)
+                .all(opts.name);
+            for (const a of pending) {
+                if (!store.transition(a.id, "undo_requested", "undoing"))
+                    continue;
+                const inv = JSON.parse(a.undo);
+                try {
+                    const r = await forward(inv.tool, inv.args);
+                    if (r.isError)
+                        store.updateAction(a.id, { status: "undo_failed", error: summarize(r) });
+                    else
+                        store.updateAction(a.id, { status: "undone", undone_at: Date.now(), result: summarize(r) });
+                }
+                catch (err) {
+                    store.updateAction(a.id, { status: "undo_failed", error: err instanceof Error ? err.message : String(err) });
+                }
+            }
+        }
+        finally {
+            undoing = false;
+        }
+    }, UNDO_POLL_MS);
+    let closed = false;
+    const shutdown = async () => {
+        if (closed)
+            return;
+        closed = true;
+        clearInterval(undoTimer);
+        store.endRun(run.id);
+        await upstream.close().catch(() => { });
+        store.close();
+    };
+    server.onclose = () => void shutdown();
+    // The stdio transport doesn't notice the agent hanging up, so watch stdin
+    // ourselves; otherwise the wrapped server outlives every session.
+    process.stdin.on("end", () => void shutdown().then(() => process.exit(0)));
+    process.on("SIGINT", () => void shutdown().then(() => process.exit(0)));
+    process.on("SIGTERM", () => void shutdown().then(() => process.exit(0)));
+    await server.connect(new StdioServerTransport());
+    log(`run ${run.id} started, wrapping: ${run.command}`);
+}
+async function connectUpstream(opts) {
+    const make = () => new Client({ name: "backstep", version: "0.1.0" });
+    if (opts.url) {
+        const url = new URL(opts.url);
+        const requestInit = { headers: opts.headers };
+        const client = make();
+        try {
+            await client.connect(new StreamableHTTPClientTransport(url, { requestInit }));
+            return client;
+        }
+        catch {
+            // Older servers only speak the SSE transport.
+            const legacy = make();
+            await legacy.connect(new SSEClientTransport(url, { requestInit }));
+            return legacy;
+        }
+    }
+    if (!opts.command)
+        throw new Error("nothing to wrap: give a command or --url");
+    const client = make();
+    await client.connect(new StdioClientTransport({
+        command: opts.command,
+        args: opts.args,
+        env: process.env,
+        cwd: process.cwd(),
+        stderr: "inherit",
+    }));
+    return client;
+}

package/dist/push.js

@@ -0,0 +1,108 @@
+// Taking back code Claude pushed. Undo rewinds the local repository; this puts
+// the same undo on the remote (GitHub, GitLab, …) as one new commit, pushed
+// the ordinary way: no force push, no rewritten history, so it works on
+// protected branches and for anyone who already pulled. It uses the project's
+// own git and its sign-in, so if Claude could push, so can this.
+//
+// The commit is made in a temporary worktree, so the person's own folder is
+// never touched. Anything that would clash (newer commits that conflict, a
+// branch someone rewrote or added to) stops it and says why.
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const TIMEOUT_MS = 120_000;
+// The person's own git: their name on the commit, their hooks, their sign-in.
+function git(cwd, args, input) {
+    return execFileSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        timeout: TIMEOUT_MS,
+        maxBuffer: 64 * 1024 * 1024,
+        input,
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+        stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+}
+function tryGit(cwd, args) {
+    try {
+        return git(cwd, args);
+    }
+    catch {
+        return null;
+    }
+}
+const why = (err) => {
+    const e = err;
+    return (e.stderr || e.message || String(err)).trim().split("\n").filter(Boolean).at(-1) ?? "git failed";
+};
+export function revertPush(root, p) {
+    const where = `${p.remote}/${p.branch}`;
+    const ref = `refs/remotes/${p.remote}/${p.branch}`;
+    try {
+        git(root, ["fetch", "--quiet", p.remote, `+refs/heads/${p.branch}:${ref}`]);
+    }
+    catch (err) {
+        if (p.before === null && /couldn't find remote ref/i.test(why(err)))
+            return { ok: true, detail: `${p.branch} is already gone from ${p.host}` };
+        return { ok: false, detail: `couldn't reach ${p.host}: ${why(err)}` };
+    }
+    const head = tryGit(root, ["rev-parse", "-q", "--verify", ref]);
+    if (!head)
+        return { ok: false, detail: `${where} is gone from ${p.host}` };
+    // A branch the push made: taking it back means deleting it, but only while nobody has added to it.
+    if (p.before === null) {
+        if (head !== p.after)
+            return { ok: false, detail: `left ${p.branch} on ${p.host}: commits were added to it after Claude pushed it` };
+        try {
+            git(root, ["push", "--quiet", p.remote, "--delete", p.branch]);
+        }
+        catch (err) {
+            return { ok: false, detail: `couldn't delete ${p.branch} on ${p.host}: ${why(err)}` };
+        }
+        return { ok: true, detail: `deleted the branch ${p.branch} Claude pushed to ${p.host}` };
+    }
+    if (tryGit(root, ["merge-base", "--is-ancestor", p.after, head]) === null) {
+        return { ok: false, detail: `left ${where} alone: its history was rewritten after Claude pushed` };
+    }
+    const dir = mkdtempSync(join(tmpdir(), "backstep-push-"));
+    const patch = join(dir, "undo.patch");
+    const tree = join(dir, "tree");
+    try {
+        git(root, ["worktree", "add", "--quiet", "--detach", tree, head]);
+        // What turns Claude's commits back, applied on top of whatever is there now.
+        writeFileSync(patch, git(root, ["diff", "--binary", p.after, p.before]) + "\n");
+        if (git(root, ["diff", "--stat", p.after, p.before]) === "")
+            return { ok: true, detail: `Claude's commits on ${where} changed no files` };
+        try {
+            git(tree, ["apply", "--3way", "--index", patch]);
+        }
+        catch {
+            return { ok: false, detail: `left ${where} alone: newer commits there clash with undoing Claude's` };
+        }
+        const n = p.commits === 1 ? "1 commit" : `${p.commits} commits`;
+        git(tree, ["commit", "--quiet", "-m", "Undo Claude's changes", "-m", `Reverts ${p.before.slice(0, 7)}..${p.after.slice(0, 7)} (${n}), undone with Backstep.`]);
+        const undo = git(tree, ["rev-parse", "HEAD"]);
+        try {
+            git(tree, ["push", "--quiet", p.remote, `HEAD:refs/heads/${p.branch}`]);
+        }
+        catch (err) {
+            return { ok: false, detail: `couldn't push the undo to ${where}: ${why(err)}` };
+        }
+        // The local branch is where undo left it, with the same files as the undo
+        // commit: move it up so the next pull has nothing to fight.
+        const local = `refs/heads/${p.branch}`;
+        const sameFiles = tryGit(root, ["rev-parse", `${undo}^{tree}`]) === tryGit(root, ["rev-parse", `${p.before}^{tree}`]);
+        if (sameFiles && tryGit(root, ["rev-parse", "-q", "--verify", local]) === p.before) {
+            tryGit(root, ["update-ref", local, undo, p.before]);
+        }
+        return { ok: true, detail: `pushed a commit to ${where} that undoes Claude's ${n}` };
+    }
+    catch (err) {
+        return { ok: false, detail: `couldn't undo the push to ${where}: ${why(err)}` };
+    }
+    finally {
+        tryGit(root, ["worktree", "remove", "--force", tree]);
+        rmSync(dir, { recursive: true, force: true });
+    }
+}

package/dist/rules.js

@@ -0,0 +1,86 @@
+// Undo rules: for tools Backstep can't snapshot, undo by calling the server's
+// own opposite tool. A rule maps a tool to its inverse, filling the inverse's
+// arguments from the original call and its result:
+//
+//   { "tool": "create_issue",
+//     "inverse": { "tool": "update_issue",
+//                  "args": { "owner": "{{args.owner}}", "repo": "{{args.repo}}",
+//                            "issue_number": "{{result.number}}", "state": "closed" } } }
+import { readFileSync } from "node:fs";
+export function loadRules(file) {
+    if (!file)
+        return [];
+    const raw = JSON.parse(readFileSync(file, "utf8"));
+    const rules = Array.isArray(raw) ? raw : raw.rules;
+    if (!Array.isArray(rules))
+        throw new Error(`${file}: expected a list of rules`);
+    for (const r of rules) {
+        if (typeof r?.tool !== "string" || typeof r?.inverse?.tool !== "string") {
+            throw new Error(`${file}: every rule needs "tool" and "inverse.tool"`);
+        }
+    }
+    return rules;
+}
+export function findRule(rules, server, tool) {
+    return rules.find((r) => r.tool === tool && (r.server === undefined || r.server === server));
+}
+// Tools return JSON as text more often than as structuredContent, so try both.
+export function resultData(result) {
+    if (result.structuredContent)
+        return result.structuredContent;
+    const first = result.content?.find((c) => c.type === "text");
+    if (!first || first.type !== "text")
+        return undefined;
+    try {
+        return JSON.parse(first.text);
+    }
+    catch {
+        return first.text;
+    }
+}
+function lookup(scope, path) {
+    let cur = scope;
+    for (const part of path.split(".")) {
+        if (cur === null || typeof cur !== "object")
+            return undefined;
+        cur = cur[part];
+    }
+    return cur;
+}
+class Missing extends Error {
+}
+function render(value, scope) {
+    if (typeof value === "string") {
+        // A lone placeholder keeps the original type, so numbers stay numbers.
+        const whole = value.match(/^\{\{\s*([\w.]+)\s*\}\}$/);
+        if (whole) {
+            const v = lookup(scope, whole[1]);
+            if (v === undefined)
+                throw new Missing(whole[1]);
+            return v;
+        }
+        return value.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, path) => {
+            const v = lookup(scope, path);
+            if (v === undefined)
+                throw new Missing(path);
+            return typeof v === "string" ? v : JSON.stringify(v);
+        });
+    }
+    if (Array.isArray(value))
+        return value.map((v) => render(v, scope));
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, render(v, scope)]));
+    }
+    return value;
+}
+export function buildInverse(rule, server, args, result) {
+    try {
+        const inverseArgs = render(rule.inverse.args ?? {}, { args, result: resultData(result) });
+        return { undo: { adapter: "inverse", server, tool: rule.inverse.tool, args: inverseArgs } };
+    }
+    catch (err) {
+        if (err instanceof Missing)
+            return { missing: err.message };
+        throw err;
+    }
+}