backstep 0.0.0-stage → 0.1.1

package/dist/check.js

@@ -0,0 +1,117 @@
+// What Backstep can undo for each service Claude Code is connected to, and
+// what to connect next. Setup prints it, `backstep status` prints it, and the
+// Claude Code mod checks it as a session starts, so nobody assumes a service
+// is covered when it isn't.
+import { spawnSync } from "node:child_process";
+import { configServers, projectUses } from "./connect.js";
+import { supabaseProjects } from "./supabase.js";
+import { watchRules } from "./watch.js";
+import { dim, pink, white, width, wrap } from "./look.js";
+const WRAPPED = /(^|[/\s])(backstep|cli\.[jt]s) wrap\b/;
+const SUPABASE = /supabase/i;
+const FIREBASE = /firebase|firestore/i;
+// `claude mcp list` sees everything a session would, plugins and claude.ai
+// connectors included, and whether each works; it prints "name: target - ✔ Connected".
+function listed(dir) {
+    const r = spawnSync("claude", ["mcp", "list"], { cwd: dir, encoding: "utf8", timeout: 90_000 });
+    if (r.status !== 0 || !r.stdout)
+        return null;
+    const out = [];
+    for (const line of r.stdout.split("\n")) {
+        const m = line.match(/^(.+?): (.*) - ([✔!✘]) /);
+        if (m)
+            out.push({ name: m[1], target: m[2], health: m[3] === "✔" ? "ok" : m[3] === "!" ? "auth" : "failed" });
+    }
+    return out;
+}
+// "claude.ai Notion" → "Notion", "plugin:vercel:vercel" → "vercel".
+const label = (name) => name.replace(/^claude\.ai /, "").replace(/^plugin:(?:[^:]+:)?/, "");
+function classify(s, supabaseConnected, ruled) {
+    const what = `${s.name} ${s.target}`;
+    const name = label(s.name);
+    const wrapped = WRAPPED.test(s.target);
+    // Wrapped at the next session start: servers in Claude Code's config, not plugins or claude.ai connectors.
+    const wrappable = !wrapped && s.target !== "" && !s.name.startsWith("plugin:") && !s.name.startsWith("claude.ai ");
+    const signIn = s.health === "auth" || undefined;
+    if (s.health === "failed")
+        return { name, level: "off", detail: "check it with /mcp in Claude Code" };
+    if (SUPABASE.test(what)) {
+        return supabaseConnected
+            ? { name, level: "undoable", detail: "rows, tables and migrations", signIn }
+            : { name, level: "connect", detail: "rows, tables and migrations, once it's connected", signIn };
+    }
+    if (FIREBASE.test(what)) {
+        if (wrapped)
+            return { name, level: "undoable", detail: "Firestore, Realtime Database, Remote Config", signIn };
+        if (wrappable)
+            return { name, level: "connect", detail: "undoable from the next Claude Code session", signIn };
+    }
+    if (ruled.has(s.name.replace(/[^a-zA-Z0-9_-]/g, "_")))
+        return { name, level: "undoable", detail: "the tools your undo rules cover", signIn };
+    if (wrapped)
+        return { name, level: "recorded", detail: "except file and database changes, which undo", signIn };
+    if (wrappable)
+        return { name, level: "recorded", detail: "goes behind Backstep from the next Claude Code session", signIn };
+    // Recorded only: printed as one line for all of them.
+    return { name, level: "recorded", detail: "", signIn };
+}
+// `quick` reads Claude Code's config instead of asking `claude mcp list`,
+// which starts every server: for a check as a session starts.
+export function check(dir, opts = {}) {
+    const found = (opts.quick ? null : listed(dir)) ?? configServers(dir);
+    const connected = supabaseProjects().length > 0;
+    const ruled = new Set(watchRules().map((r) => r.server ?? "").filter(Boolean));
+    const items = found.map((s) => classify(s, connected, ruled));
+    const uses = projectUses(dir);
+    const suggest = [];
+    const supabaseHere = items.some((i) => SUPABASE.test(i.name)) || uses.supabase;
+    if (!connected && supabaseHere) {
+        suggest.push({ title: "Connect Supabase", why: "so Claude's database changes can be undone", how: 'Ask Claude: "connect Backstep to Supabase"' });
+    }
+    if (uses.firebase && !items.some((i) => FIREBASE.test(i.name))) {
+        suggest.push({ title: "Add Firebase", why: "so Claude can reach it and its changes can be undone", how: 'Ask Claude: "connect Backstep to Firebase"' });
+    }
+    return { items, suggest };
+}
+// Short and friendly: what undoes, the one thing worth connecting, and a
+// single line for everything else. Claude's other tools that have nothing to
+// do with undo (ones that are broken, or need signing in) aren't Backstep's to list.
+export function printCheck(c, bs = "backstep") {
+    const cols = width() - 6;
+    const undoable = [...new Set(c.items.filter((i) => i.level === "undoable").map((i) => i.name))];
+    const soon = [...new Set(c.items.filter((i) => i.level === "connect" && FIREBASE.test(i.name)).map((i) => i.name))];
+    const supabase = c.items.find((i) => SUPABASE.test(i.name));
+    const supabaseLeft = supabase?.level === "connect" || c.suggest.some((s) => s.title === "Connect Supabase");
+    const other = [...new Set(c.items.filter((i) => i.level === "recorded").map((i) => i.name))];
+    console.log(`\n  ${white("What ctrl+z can undo")}`);
+    console.log(`    ${pink("✓")} Files Claude edits and commands it runs`);
+    console.log(`    ${pink("✓")} Code Claude pushes to GitHub ${dim("(automatic, nothing to connect)")}`);
+    for (const n of undoable)
+        console.log(`    ${pink("✓")} ${n}`);
+    for (const n of soon)
+        console.log(`    ${pink("✓")} ${n} ${dim("(from your next Claude Code session)")}`);
+    console.log("");
+    if (supabaseLeft) {
+        console.log(`  ${white("Connect Supabase to undo database changes too")}`);
+        console.log(`    ${pink("→")} ${wrap("Open your project in Claude Code. Backstep checks it for Supabase and asks if you want to connect.", cols, 6)}`);
+        console.log(`    ${pink("→")} Or just ask Claude: ${white('"connect Backstep to Supabase"')}`);
+        console.log("");
+    }
+    else if (!supabase || supabase.level !== "undoable") {
+        console.log(`  ${dim(wrap("Use Supabase? Open your project in Claude Code and Backstep will check for it and offer to connect.", cols, 2))}`);
+        console.log("");
+    }
+    if (c.suggest.some((s) => s.title === "Add Firebase")) {
+        console.log(`  ${white("Your project uses Firebase")}`);
+        console.log(`    ${pink("→")} Ask Claude: ${white('"connect Backstep to Firebase"')}`);
+        console.log("");
+    }
+    if (other.length) {
+        const names = other.length > 3 ? `${other.slice(0, 2).join(", ")} and ${other.length - 2} more` : other.join(", ");
+        console.log(`  ${dim(wrap(`Changes in your other tools (${names}) show up in Backstep's history, but can't be undone.`, cols, 2))}`);
+        console.log("");
+    }
+    console.log(`  ${pink(`${bs} status`)}  ${dim("see this again")}`);
+    console.log(`  ${pink(`${bs} ui`.padEnd(bs.length + 7))}  ${dim("see everything Claude changed")}`);
+    console.log("");
+}

package/dist/classify.js

@@ -0,0 +1,53 @@
+import { parseSql } from "./sql.js";
+const READ_VERB = /^(get|list|read|search|query|fetch|describe|find|show|view|lookup|check|count|inspect|browse|stat|head|preview|directory_tree|tree)(_|$|[A-Z])/i;
+const READ_ANYWHERE = /(^|_)(get|list|read|search|find|describe)(_|$)/i;
+const IRREVERSIBLE = /(^|_|-)(send|email|mail|sms|message|reply|post|publish|tweet|pay|charge|transfer|refund|payout|invoice|deploy|release|merge|notify|call|dial|purchase|buy|order|checkout|book|sign|submit|broadcast|exec|execute|run|shell|command)(_|-|$)/i;
+const PATH_KEY = /^(path|paths|file|files|filename|filepath|file_path|source|destination|src|dest|target|dir|directory)$/i;
+const SQL_KEY = /^(sql|query|statement|statements)$/i;
+const LOOKS_SQL = /^\s*(?:--[^\n]*\n\s*)*(select|insert|update|delete|truncate|drop|alter|create|with|show|explain|values|table|grant|revoke|begin|commit|copy|vacuum|comment|merge)\b/i;
+function findSql(args) {
+    for (const [k, v] of Object.entries(args)) {
+        // "query" is also what search tools call their search box, so require it to read like SQL.
+        if (SQL_KEY.test(k) && typeof v === "string" && LOOKS_SQL.test(v))
+            return { key: k, sql: v };
+    }
+    return null;
+}
+function findPaths(args) {
+    const out = [];
+    for (const [k, v] of Object.entries(args)) {
+        if (!PATH_KEY.test(k))
+            continue;
+        if (typeof v === "string")
+            out.push(v);
+        else if (Array.isArray(v))
+            out.push(...v.filter((x) => typeof x === "string"));
+    }
+    return out;
+}
+export function planCall(tool, name, args) {
+    const ann = tool?.annotations;
+    const sql = findSql(args);
+    // SQL tools are judged by the statement, not the tool name: "query" can drop a table.
+    if (sql) {
+        const statements = parseSql(sql.sql);
+        if (statements.length > 0 && statements.every((s) => s.op === "read"))
+            return { kind: "read" };
+        return { kind: "sql", sql: sql.sql, argKey: sql.key };
+    }
+    if (ann?.readOnlyHint === true)
+        return { kind: "read" };
+    const looksRead = READ_VERB.test(name) || (READ_ANYWHERE.test(name) && !IRREVERSIBLE.test(name));
+    if (looksRead && ann?.destructiveHint !== true)
+        return { kind: "read" };
+    if (IRREVERSIBLE.test(name))
+        return { kind: "irreversible", reason: `"${name}" acts outside anything Backstep can snapshot` };
+    const paths = findPaths(args);
+    if (paths.length > 0)
+        return { kind: "paths", paths };
+    if (ann?.destructiveHint === true)
+        return { kind: "irreversible", reason: "the server marks this tool destructive" };
+    if (ann?.openWorldHint === true)
+        return { kind: "irreversible", reason: "the server marks this tool as reaching the outside world" };
+    return { kind: "write" };
+}

package/dist/cli.js

@@ -0,0 +1,408 @@
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
+import { parseArgs } from "node:util";
+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 { snapshotPaths } from "./adapters/fs.js";
+import { notePushed, snapshotTree } from "./adapters/tree.js";
+import { revertPush } from "./push.js";
+const PUSH = /\bgit\b[^;&|]*\bpush\b/;
+import { classifyShell } from "./shell.js";
+import { watchEnd, watchStart } from "./watch.js";
+import { sendActive } from "./telemetry.js";
+import { readFileSync, rmSync } from "node:fs";
+import { loadRules } from "./rules.js";
+import { setup } from "./setup.js";
+import { autoWrap, printChanges, unwrapServers, wrapServers } from "./servers.js";
+import { disconnectSupabase, dismissSupabase } from "./supabase.js";
+import { connect } from "./connect.js";
+import { check, printCheck } from "./check.js";
+import { logo } from "./look.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) {
+    const out = {};
+    for (const h of list) {
+        const i = h.indexOf(":");
+        if (i < 1)
+            throw new Error(`--header must look like "Name: value", got "${h}"`);
+        out[h.slice(0, i).trim()] = h
+            .slice(i + 1)
+            .trim()
+            .replace(/\$\{(\w+)\}/g, (_, v) => {
+            const val = process.env[v];
+            if (val === undefined)
+                throw new Error(`--header uses \${${v}}, which isn't set`);
+            return val;
+        });
+    }
+    return out;
+}
+// Setup passes the headers of a wrapped remote server as BACKSTEP_HEADER_0, _1, … (see servers.ts).
+function envHeaders() {
+    return Object.keys(process.env)
+        .filter((k) => /^BACKSTEP_HEADER_\d+$/.test(k))
+        .sort((a, b) => Number(a.slice(16)) - Number(b.slice(16)))
+        .map((k) => process.env[k]);
+}
+const HELP = `backstep: undo for everything your agents touch
+
+  backstep setup               install the Claude Code mod, bind ctrl+z to undo Claude's last turn,
+                               and put your MCP servers behind Backstep
+  backstep unwrap              take your MCP servers back out from behind Backstep
+  backstep connect [supabase|firebase] [<access-token>|<connection-string>] [--project <ref>] [--dir <folder>] [--json]
+                               connect what the project uses, so Claude's changes to it can be undone:
+                               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 status [--json]     what Backstep can and can't undo for each service Claude Code reaches,
+                               and what to connect next
+  backstep disconnect supabase <ref>
+  backstep wrap-servers [--project <dir>] [--json]
+                               put MCP servers added since setup behind Backstep (the Claude Code mod runs this)
+
+  backstep wrap [options] -- <command> [args...]
+  backstep wrap [options] --url <https://server/mcp>
+      Run an MCP server behind Backstep. Point your agent at this instead.
+        --name <name>          label shown in the dashboard (default: the command)
+        --url <url>            wrap a remote MCP server (Streamable HTTP, falling back to SSE)
+        --header "K: V"        send a header to the remote server; \${VAR} reads an env var (repeatable)
+        --rules <file>         undo rules: which tool undoes which (see examples/rules.json)
+        --pg <url>             Postgres URL the wrapped server writes to; enables database undo
+
+  backstep ui [--port 4747]    open the dashboard
+  backstep log [--limit 30]    print recent actions
+  backstep undo <action-id>    undo one action (and later ones that touched the same things)
+  backstep undo --run <run-id> undo everything a run did
+  backstep undo --since <ms> [--until <ms>] [--json] [--via-claude-code]
+                               undo everything any agent did in that window
+  backstep snap --session <id> --tool <name> [--cwd <dir>] -- <paths...>
+                               save paths before Claude Code's own tools change them (used by the Claude Code mod)
+  backstep revert-push --root <repo>
+                               undo code Claude pushed, on the remote, with a new commit (the push as JSON on stdin;
+                               the Claude Code mod runs this after asking)
+  backstep shell --session <id> [--cwd <dir>] -- <command>
+                               snapshot the project before Claude Code runs a shell command (used by the Claude Code mod)
+
+Example (Claude Code):
+  claude mcp add files -- backstep wrap --name files -- npx -y @modelcontextprotocol/server-filesystem ~/project
+`;
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    if (cmd === "wrap") {
+        const sep = rest.indexOf("--");
+        const { values } = parseArgs({
+            args: sep === -1 ? rest : rest.slice(0, sep),
+            options: {
+                name: { type: "string" },
+                url: { type: "string" },
+                header: { type: "string", multiple: true, default: [] },
+                rules: { type: "string" },
+                pg: { type: "string" },
+            },
+        });
+        const [command, ...args] = sep === -1 ? [] : rest.slice(sep + 1);
+        if (!command && !values.url)
+            throw new Error("usage: backstep wrap [options] -- <command> [args...]  or  --url <url>");
+        if (command && values.url)
+            throw new Error("give either a command or --url, not both");
+        await runProxy({
+            name: values.name ?? command ?? new URL(values.url).host,
+            command,
+            args,
+            url: values.url,
+            headers: parseHeaders([...values.header, ...envHeaders()]),
+            rules: loadRules(values.rules ?? process.env.BACKSTEP_RULES),
+            pgUrl: values.pg ?? process.env.BACKSTEP_PG_URL ?? null,
+        });
+        return;
+    }
+    if (cmd === "setup") {
+        await setup();
+        return;
+    }
+    // The mod runs this as Claude Code starts; it counts at most once a day.
+    if (cmd === "ping") {
+        await sendActive();
+        return;
+    }
+    if (cmd === "unwrap") {
+        autoWrap(false);
+        const changes = unwrapServers();
+        if (changes.length === 0)
+            console.log("No MCP servers are behind Backstep.");
+        printChanges(changes);
+        if (changes.some((c) => c.done))
+            console.log("\nRestart Claude Code to use them directly again.");
+        console.log("New MCP servers won't be put behind Backstep either, until you run backstep setup again.");
+        return;
+    }
+    // Run by the Claude Code mod as a session starts: wraps servers added since setup.
+    if (cmd === "wrap-servers") {
+        const { values } = parseArgs({ args: rest, options: { project: { type: "string" }, json: { type: "boolean", default: false } } });
+        const changes = autoWrap() ? wrapServers(fileURLToPath(import.meta.url), { onlyDir: values.project }) : [];
+        if (values.json)
+            console.log(JSON.stringify(changes));
+        else
+            printChanges(changes);
+        return;
+    }
+    // Connects whatever the project uses; the Claude Code mod runs this when the
+    // person asks Claude to, passing a connection string they gave on stdin.
+    if (cmd === "connect") {
+        const { values, positionals } = parseArgs({
+            args: rest,
+            allowPositionals: true,
+            options: {
+                project: { type: "string" },
+                dir: { type: "string" },
+                json: { type: "boolean", default: false },
+                stdin: { type: "boolean", default: false },
+                auto: { type: "boolean", default: false },
+                dismiss: { type: "boolean", default: false },
+            },
+        });
+        const [service, given] = positionals;
+        if (service && service !== "supabase" && service !== "firebase")
+            throw new Error(`can't connect "${service}": Backstep connects supabase and firebase`);
+        // "Don't ask for this project", from the question the Claude Code mod asks.
+        if (values.dismiss) {
+            dismissSupabase(values.dir ?? process.cwd());
+            return;
+        }
+        const opts = {
+            dir: values.dir ?? process.cwd(),
+            cli: fileURLToPath(import.meta.url),
+            only: service,
+            url: given ?? (values.stdin ? readFileSync(0, "utf8").trim() || undefined : undefined),
+            ref: values.project,
+            auto: values.auto,
+            interactive: !values.json && process.stdin.isTTY === true,
+        };
+        let out = await connect(opts);
+        // In a terminal, ask for what couldn't be found.
+        if (!values.json && !opts.url && service === "supabase" && out[0].state === "needs" && process.stdin.isTTY) {
+            out = await connect({ ...opts, url: await askConnectionString() });
+        }
+        if (values.json) {
+            console.log(JSON.stringify(out));
+            return;
+        }
+        for (const s of out)
+            console.log(`${s.service === "supabase" ? "Supabase" : "Firebase"}: ${s.detail}`);
+        if (out.some((s) => s.state === "needs" && s.service === "supabase"))
+            console.log("Then run: backstep connect supabase <connection-string>");
+        return;
+    }
+    // What each service Claude Code reaches can and can't undo, and what to connect.
+    if (cmd === "status") {
+        const { values } = parseArgs({ args: rest, options: { dir: { type: "string" }, json: { type: "boolean", default: false }, quick: { type: "boolean", default: false } } });
+        const c = check(values.dir ?? process.cwd(), { quick: values.quick });
+        if (values.json)
+            console.log(JSON.stringify(c));
+        else {
+            console.log(logo("what Claude's changes can be undone"));
+            printCheck(c);
+        }
+        return;
+    }
+    if (cmd === "disconnect") {
+        const [service, ref] = rest;
+        if (service !== "supabase" || !ref)
+            throw new Error("usage: backstep disconnect supabase <ref>");
+        console.log(disconnectSupabase(ref) ? `Disconnected ${ref}.` : `${ref} wasn't connected.`);
+        return;
+    }
+    if (cmd === "ui") {
+        const { values } = parseArgs({ args: rest, options: { port: { type: "string", default: "4747" } } });
+        await startUi(Number(values.port));
+        return;
+    }
+    if (cmd === "log") {
+        const { values } = parseArgs({ args: rest, options: { limit: { type: "string", default: "30" } } });
+        const store = new Store();
+        for (const a of store.feed(Number(values.limit)).reverse()) {
+            const when = new Date(a.created_at).toLocaleTimeString();
+            const undo = a.undo && (a.status === "ok" || a.status === "error") ? "  [undoable]" : "";
+            console.log(`${when}  ${a.id}  ${a.server}/${a.tool}  ${a.kind}  ${a.status}${undo}`);
+        }
+        return;
+    }
+    if (cmd === "snap") {
+        const sep = rest.indexOf("--");
+        const { values } = parseArgs({
+            args: sep === -1 ? rest : rest.slice(0, sep),
+            options: { session: { type: "string" }, tool: { type: "string" }, cwd: { type: "string" } },
+        });
+        const paths = sep === -1 ? [] : rest.slice(sep + 1);
+        if (!values.session || !values.tool || paths.length === 0) {
+            throw new Error("usage: backstep snap --session <id> --tool <name> [--cwd <dir>] -- <paths...>");
+        }
+        const store = new Store();
+        const run = store.sessionRun("claude-code", `session:${values.session}`);
+        const a = store.addAction({
+            run_id: run.id,
+            tool: values.tool,
+            args: JSON.stringify({ paths }),
+            kind: "reversible",
+            status: "ok",
+            reason: null,
+            undo: null,
+            result: null,
+            error: null,
+            release_at: null,
+        });
+        const undo = snapshotPaths(a.id, paths, values.cwd ?? process.cwd());
+        if (undo)
+            store.updateAction(a.id, { undo: JSON.stringify(undo) });
+        else
+            store.updateAction(a.id, { kind: "write", reason: "too large to snapshot" });
+        console.log(JSON.stringify({ id: a.id, undoable: undo !== null }));
+        return;
+    }
+    // Prints {kind, reason?, id?, undoable}: "read" is let through untouched, "outbound"
+    // is recorded but can't be undone, and anything else gets the project snapshotted.
+    if (cmd === "shell") {
+        const sep = rest.indexOf("--");
+        const { values } = parseArgs({
+            args: sep === -1 ? rest : rest.slice(0, sep),
+            options: { session: { type: "string" }, cwd: { type: "string" } },
+        });
+        const command = sep === -1 ? "" : rest.slice(sep + 1).join(" ");
+        if (!values.session || !command)
+            throw new Error("usage: backstep shell --session <id> [--cwd <dir>] -- <command>");
+        const plan = classifyShell(command);
+        if (plan.kind === "read") {
+            console.log(JSON.stringify({ kind: "read", undoable: false }));
+            return;
+        }
+        const store = new Store();
+        const run = store.sessionRun("claude-code", `session:${values.session}`);
+        const a = store.addAction({
+            run_id: run.id,
+            tool: "Bash",
+            args: JSON.stringify({ command }),
+            kind: plan.kind === "outbound" ? "irreversible" : "reversible",
+            status: "ok",
+            reason: plan.reason ?? null,
+            undo: null,
+            result: null,
+            error: null,
+            release_at: null,
+        });
+        // 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) });
+        if (undo)
+            store.updateAction(a.id, { undo: JSON.stringify(undo) });
+        else if (plan.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 }));
+        return;
+    }
+    // After a shell command that pushed: notes what it sent (run by the Claude Code mod).
+    if (cmd === "shell-end") {
+        const store = new Store();
+        const a = store.getAction(rest[0] ?? "");
+        const u = a?.undo ? JSON.parse(a.undo) : null;
+        if (a && u?.adapter === "tree" && u.git?.remotes) {
+            const pushed = notePushed(u);
+            if (pushed.length)
+                store.updateAction(a.id, { undo: JSON.stringify({ ...u, pushed }) });
+        }
+        return;
+    }
+    // Puts an undo of code Claude pushed on the remote, as a new commit. The push, as undo reported it, comes on stdin.
+    if (cmd === "revert-push") {
+        const { values } = parseArgs({ args: rest, options: { root: { type: "string" } } });
+        if (!values.root)
+            throw new Error("usage: backstep revert-push --root <repo>  (the push as JSON on stdin)");
+        const out = revertPush(values.root, JSON.parse(readFileSync(0, "utf8")));
+        console.log(JSON.stringify(out));
+        if (!out.ok)
+            process.exitCode = 1;
+        return;
+    }
+    // The mod reports MCP calls to servers Backstep isn't in front of. The call's
+    // arguments, and later its result, come as JSON on stdin.
+    if (cmd === "watch-start") {
+        const sep = rest.indexOf("--");
+        const { values } = parseArgs({ args: sep === -1 ? rest : rest.slice(0, sep), options: { session: { type: "string" }, cwd: { type: "string" } } });
+        const tool = sep === -1 ? "" : rest[sep + 1];
+        if (!values.session || !tool)
+            throw new Error("usage: backstep watch-start --session <id> [--cwd <dir>] -- <mcp__server__tool>  (arguments as JSON on stdin)");
+        const input = readFileSync(0, "utf8").trim();
+        console.log(JSON.stringify(await watchStart(new Store(), values.session, values.cwd ?? process.cwd(), tool, input ? JSON.parse(input) : {})));
+        return;
+    }
+    if (cmd === "watch-end") {
+        const input = readFileSync(0, "utf8").trim();
+        console.log(JSON.stringify(await watchEnd(new Store(), rest[0] ?? "", input ? JSON.parse(input) : {})));
+        return;
+    }
+    // Claude Code ran an opposite call `undo --via-claude-code` handed it.
+    if (cmd === "settle") {
+        const { values, positionals } = parseArgs({ args: rest, allowPositionals: true, options: { failed: { type: "string" } } });
+        const store = new Store();
+        const id = positionals[0] ?? "";
+        if (!store.getAction(id))
+            throw new Error(`no action ${id}`);
+        if (values.failed !== undefined)
+            store.updateAction(id, { status: "undo_failed", error: values.failed });
+        else
+            store.updateAction(id, { status: "undone", undone_at: Date.now() });
+        return;
+    }
+    // A call the mod reported was refused before it ran.
+    if (cmd === "cancel") {
+        const store = new Store();
+        const id = rest[0] ?? "";
+        const a = store.getAction(id);
+        if (!a)
+            throw new Error(`no action ${id}`);
+        store.updateAction(id, { status: "cancelled", undo: null });
+        rmSync(snapshotDir(id), { recursive: true, force: true });
+        return;
+    }
+    if (cmd === "undo") {
+        const { values, positionals } = parseArgs({
+            args: rest,
+            allowPositionals: true,
+            options: {
+                run: { type: "string" },
+                since: { type: "string" },
+                until: { type: "string" },
+                json: { type: "boolean", default: false },
+                "via-claude-code": { type: "boolean", default: false },
+            },
+        });
+        const store = new Store();
+        const outcomes = values.since
+            ? await undoSince(store, Number(values.since), values.until ? Number(values.until) : undefined, { viaClaudeCode: values["via-claude-code"] })
+            : values.run
+                ? await undoRun(store, values.run)
+                : await undoAction(store, positionals[0] ?? "");
+        if (values.json) {
+            console.log(JSON.stringify(outcomes));
+            if (outcomes.some((o) => !o.ok))
+                process.exitCode = 1;
+            return;
+        }
+        if (outcomes.length === 0)
+            console.log("Nothing to undo.");
+        for (const o of outcomes)
+            console.log(`${o.ok ? "undone" : "FAILED"}  ${o.tool} (${o.id})\n  ${o.detail.replaceAll("\n", "\n  ")}`);
+        if (outcomes.some((o) => !o.ok))
+            process.exitCode = 1;
+        return;
+    }
+    process.stdout.write(HELP);
+    if (cmd && cmd !== "help" && cmd !== "--help" && cmd !== "-h")
+        process.exitCode = 1;
+}
+main().catch((err) => {
+    process.stderr.write(`backstep: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});