backstep 0.0.0-stage → 0.1.1

package/dist/servers.js

@@ -0,0 +1,226 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { homeDir } from "./store.js";
+const TAG = "BACKSTEP_WRAPPED";
+const PG = /^postgres(ql)?:\/\//;
+export function claudeConfigFile() {
+    const dir = process.env.CLAUDE_CONFIG_DIR;
+    return dir ? join(dir, ".claude.json") : join(homedir(), ".claude.json");
+}
+const savedFile = () => join(homeDir(), "wrapped.json");
+const settingsFile = () => join(homeDir(), "settings.json");
+// Claude Code may store an entry's keys in another order than they were given.
+const canonical = (v) => Array.isArray(v) ? v.map(canonical) : v && typeof v === "object" ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b)).map(([k, x]) => [k, canonical(x)])) : v;
+const same = (a, b) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+const key = (s) => `${s.scope}\0${s.dir ?? ""}\0${s.name}`;
+function readJson(file, fallback) {
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return fallback;
+    }
+}
+function writeJson(file, value) {
+    mkdirSync(homeDir(), { recursive: true });
+    const tmp = `${file}.backstep-tmp`;
+    writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 });
+    renameSync(tmp, file);
+}
+// `backstep unwrap` turns this off so a new session doesn't wrap everything again; setup turns it back on.
+export function autoWrap(on) {
+    const s = readJson(settingsFile(), {});
+    if (on === undefined)
+        return s.autoWrap !== false;
+    writeJson(settingsFile(), { ...s, autoWrap: on });
+    return on;
+}
+// Tagged by us, or wrapped by hand: `backstep wrap …`, `node …/cli.js wrap …`.
+function isWrapped(e) {
+    if (e.env?.[TAG])
+        return true;
+    const words = [e.command ?? "", ...(e.args ?? [])];
+    return words.some((w, i) => /(^|\/)(backstep|cli\.[jt]s)$/.test(w) && words[i + 1] === "wrap");
+}
+// Whether calls to a server, by the name its tools carry, go through Backstep's
+// proxy. Claude Code spells a server's name in tool names with _ for anything
+// but letters, digits, _ and -.
+export function isWrappedServer(toolServer, cwd) {
+    const config = readJson(claudeConfigFile(), {});
+    const spell = (n) => n.replace(/[^a-zA-Z0-9_-]/g, "_");
+    const project = Object.entries(config.projects ?? {}).find(([dir]) => resolve(dir) === resolve(cwd))?.[1];
+    const shared = readJson(join(cwd, ".mcp.json"), {}).mcpServers ?? {};
+    // A project's own server shadows a shared one, which shadows the person's.
+    for (const servers of [project?.mcpServers ?? {}, shared, config.mcpServers ?? {}]) {
+        const hit = Object.entries(servers).find(([n]) => spell(n) === toolServer);
+        if (hit)
+            return isWrapped(hit[1]);
+    }
+    return false;
+}
+export function wrapEntry(name, e, cli) {
+    if (isWrapped(e))
+        return { skip: "already behind Backstep" };
+    const base = ["--disable-warning=ExperimentalWarning", cli, "wrap", "--name", name];
+    const env = { [TAG]: "1" };
+    if (e.command && (e.type ?? "stdio") === "stdio") {
+        const args = e.args ?? [];
+        const pg = [...Object.values(e.env ?? {}), ...args].find((v) => PG.test(v));
+        if (pg)
+            env.BACKSTEP_PG_URL = pg;
+        return {
+            entry: { ...e, type: "stdio", command: "node", args: [...base, "--", e.command, ...args], env: { ...e.env, ...env } },
+            note: pg ? "file and database changes can be undone" : "changes can be undone",
+        };
+    }
+    if (e.url && (e.type === "http" || e.type === "sse")) {
+        // No headers usually means Claude Code signs in for it, and we can't borrow that sign-in.
+        const headers = Object.entries(e.headers ?? {});
+        if (headers.length === 0 || e.headersHelper || e.oauth)
+            return { skip: "uses sign-in, so Backstep watches its calls from inside Claude Code instead" };
+        // Header values travel in env, not args, so tokens don't show up in the process list.
+        headers.forEach(([k, v], i) => (env[`BACKSTEP_HEADER_${i}`] = `${k}: ${v}`));
+        const { url, headers: _, ...rest } = e;
+        return { entry: { ...rest, type: "stdio", command: "node", args: [...base, "--url", url], env }, note: "changes can be undone" };
+    }
+    return { skip: `${e.type ?? "this"} servers aren't supported yet` };
+}
+// Approved in Claude Code's prompt, or every server of the project allowed in its settings.
+function approved(dir, p, name) {
+    if (p.disabledMcpjsonServers?.includes(name))
+        return false;
+    if (p.enabledMcpjsonServers?.includes(name))
+        return true;
+    for (const f of ["settings.local.json", "settings.json"]) {
+        const s = readJson(join(dir, ".claude", f), {});
+        if (s.enableAllProjectMcpServers || s.enabledMcpjsonServers?.includes(name))
+            return true;
+    }
+    return false;
+}
+// Every server Claude Code would start, with what it would start for each. A
+// project's own server shadows a shared one of the same name, so that's the one
+// listed, unless it's the wrapped copy Backstep made of the shared one.
+function findServers(config, saved, onlyDir) {
+    const found = [];
+    for (const [name, entry] of Object.entries(config.mcpServers ?? {}))
+        found.push({ scope: "user", name, entry });
+    for (const [dir, p] of Object.entries(config.projects ?? {})) {
+        if (onlyDir && resolve(dir) !== resolve(onlyDir))
+            continue;
+        const own = p.mcpServers ?? {};
+        const shared = readJson(join(dir, ".mcp.json"), {}).mcpServers ?? {};
+        const copied = (name) => saved.some((s) => s.scope === "shared" && s.dir === dir && s.name === name);
+        for (const [name, entry] of Object.entries(own)) {
+            if (!(copied(name) && name in shared))
+                found.push({ scope: "local", dir, name, entry });
+        }
+        for (const [name, entry] of Object.entries(shared)) {
+            if ((!(name in own) || copied(name)) && approved(dir, p, name))
+                found.push({ scope: "shared", dir, name, entry });
+        }
+    }
+    return found;
+}
+function claude(args, dir) {
+    const r = spawnSync("claude", args, { cwd: dir && existsSync(dir) ? dir : homedir(), encoding: "utf8", timeout: 30_000 });
+    return { ok: r.status === 0, out: `${r.stdout ?? ""}${r.stderr ?? ""}`.trim() };
+}
+// The scope Claude Code knows a server by. A shared server's wrapped copy lives in the project's own.
+const cliScope = (s) => (s === "user" ? "user" : "local");
+// Replaces a server's entry, putting the old one back if the new one is refused.
+function replace(scope, dir, name, next, prev) {
+    const s = cliScope(scope);
+    if (prev) {
+        const r = claude(["mcp", "remove", "-s", s, name], dir);
+        if (!r.ok)
+            return r.out.split("\n")[0] || "claude mcp remove failed";
+    }
+    if (!next)
+        return null;
+    const r = claude(["mcp", "add-json", "-s", s, name, JSON.stringify(next)], dir);
+    if (r.ok)
+        return null;
+    if (prev)
+        claude(["mcp", "add-json", "-s", s, name, JSON.stringify(prev)], dir);
+    return r.out.split("\n")[0] || "claude mcp add-json failed";
+}
+// Wraps every server not yet behind Backstep. With `onlyDir`, just the servers a
+// session in that folder would start: the person's own and that project's.
+export function wrapServers(cli, opts = {}) {
+    const file = claudeConfigFile();
+    if (!existsSync(file))
+        return [];
+    const config = readJson(file, {});
+    const saved = readJson(savedFile(), []);
+    const changes = [];
+    for (const f of findServers(config, saved, opts.onlyDir)) {
+        const where = { scope: f.scope, dir: f.dir, name: f.name };
+        if (f.dir && !existsSync(f.dir))
+            continue;
+        // Wrapped before: wrap the original again, so it points at this copy of Backstep,
+        // or at a shared server's new settings if the repo changed them.
+        const prev = saved.find((s) => key(s) === key(where));
+        const current = f.scope === "shared" ? config.projects?.[f.dir]?.mcpServers?.[f.name] ?? null : f.entry;
+        if (prev && current && !same(prev.wrapped, current))
+            continue; // changed by hand since; leave it
+        const original = f.scope === "shared" ? f.entry : prev?.original ?? f.entry;
+        const r = wrapEntry(f.name, original, cli);
+        if ("skip" in r) {
+            if (!prev)
+                changes.push({ ...where, done: false, note: r.skip });
+            continue;
+        }
+        if (prev && same(prev.wrapped, r.entry))
+            continue;
+        const err = replace(f.scope, f.dir, f.name, r.entry, f.scope === "shared" ? (prev ? current : null) : f.entry);
+        if (err) {
+            changes.push({ ...where, done: false, note: err });
+            continue;
+        }
+        if (prev)
+            Object.assign(prev, { original, wrapped: r.entry });
+        else
+            saved.push({ ...where, original, wrapped: r.entry });
+        changes.push({ ...where, done: true, note: f.scope === "shared" ? `${r.note} (the repo's .mcp.json is unchanged)` : r.note });
+        writeJson(savedFile(), saved);
+    }
+    return changes;
+}
+export function unwrapServers() {
+    const saved = readJson(savedFile(), []);
+    const config = readJson(claudeConfigFile(), {});
+    const changes = [];
+    const left = [];
+    for (const s of saved) {
+        const where = { scope: s.scope, dir: s.dir, name: s.name };
+        const current = s.scope === "user" ? config.mcpServers?.[s.name] : config.projects?.[s.dir]?.mcpServers?.[s.name];
+        if (!current) {
+            changes.push({ ...where, done: false, note: "removed since, nothing to put back" });
+            continue;
+        }
+        if (!same(current, s.wrapped)) {
+            changes.push({ ...where, done: false, note: "changed since setup, left as it is" });
+            continue;
+        }
+        // A shared server's copy is just removed, and the repo's own entry takes over again.
+        const err = replace(s.scope, s.dir, s.name, s.scope === "shared" ? null : s.original, current);
+        if (err) {
+            changes.push({ ...where, done: false, note: err });
+            left.push(s);
+        }
+        else {
+            changes.push({ ...where, done: true, note: "restored" });
+        }
+    }
+    writeJson(savedFile(), left);
+    return changes;
+}
+export function printChanges(changes) {
+    for (const c of changes) {
+        const where = c.dir ? `  (${c.dir.replace(homedir(), "~")})` : "";
+        console.log(`  ${c.done ? "✓" : "–"} ${c.name}: ${c.note}${where}`);
+    }
+}

package/dist/setup.js

@@ -0,0 +1,116 @@
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homeDir } from "./store.js";
+import { createInterface } from "node:readline/promises";
+import { autoWrap, wrapServers } from "./servers.js";
+import { check, printCheck } from "./check.js";
+import { dim, logo, pink, white, width, wrap } from "./look.js";
+import { sendInstall, telemetryOn } from "./telemetry.js";
+// Both src/ and dist/ sit one level below the package root, next to mod/.
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const UNDO_KEY = "ctrl+z";
+// The mod's undo button borrows this action; see mod/hooks/register.tsx.
+const UNDO_ACTION = "app:cycleDiffBase";
+function run(cmd, args) {
+    const r = spawnSync(cmd, args, { encoding: "utf8" });
+    return { ok: r.status === 0, out: `${r.stdout ?? ""}${r.stderr ?? ""}`.trim(), missing: r.error !== undefined };
+}
+// npx runs us from a cache that gets cleaned, so the mod needs a lasting copy.
+// A global install also puts `backstep` on the PATH; where npm's global folder
+// isn't writable (often root-owned on macOS), keep this npx copy under ~/.backstep.
+function keepCopy() {
+    const { version } = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"));
+    console.log(dim(`  Installing backstep@${version}…`));
+    if (run("npm", ["install", "-g", `backstep@${version}`]).ok) {
+        return { root: join(run("npm", ["root", "-g"]).out, "backstep"), onPath: true };
+    }
+    const modules = join(homeDir(), "app", "node_modules");
+    rmSync(modules, { recursive: true, force: true });
+    cpSync(dirname(ROOT), modules, { recursive: true });
+    return { root: join(modules, "backstep"), onPath: false };
+}
+function bindUndoKey() {
+    const dir = process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude");
+    const file = join(dir, "keybindings.json");
+    let config = {
+        $schema: "https://www.schemastore.org/claude-code-keybindings.json",
+        $docs: "https://code.claude.com/docs/en/keybindings",
+    };
+    if (existsSync(file)) {
+        try {
+            config = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch {
+            return `couldn't read ${file}, so ${UNDO_KEY} isn't bound. Add "${UNDO_KEY}": "${UNDO_ACTION}" under Global and Chat.`;
+        }
+    }
+    config.bindings ??= [];
+    for (const context of ["Global", "Chat"]) {
+        let block = config.bindings.find((b) => b.context === context);
+        if (!block)
+            config.bindings.push((block = { context, bindings: {} }));
+        const taken = block.bindings[UNDO_KEY];
+        if (taken && taken !== UNDO_ACTION)
+            return `${UNDO_KEY} is already bound to ${taken} in ${file}; left it alone.`;
+        block.bindings[UNDO_KEY] = UNDO_ACTION;
+    }
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(file, JSON.stringify(config, null, 2) + "\n");
+    return "";
+}
+const WHERE = `In Supabase, open your project, press Connect at the top, and copy the URI under
+"Direct connection" (or "Session pooler" if your network has no IPv6). Put your
+database password in place of [YOUR-PASSWORD].`;
+export async function askConnectionString() {
+    if (!process.stdin.isTTY)
+        throw new Error("give the connection string: backstep connect supabase <postgresql://…>");
+    console.log(`  ${wrap(WHERE.replaceAll("\n", " "), width() - 4, 2)}\n`);
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const url = (await rl.question("Connection string: ")).trim();
+        if (!url)
+            throw new Error("no connection string given");
+        return url;
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function setup() {
+    console.log(logo("undo for everything Claude does"));
+    console.log(dim("\n  Setting up…"));
+    if (run("claude", ["--version"]).missing) {
+        throw new Error("Claude Code isn't installed (no `claude` on PATH). Install it from https://claude.com/claude-code, then run this again.");
+    }
+    const { root, onPath } = ROOT.includes("/_npx/") ? keepCopy() : { root: ROOT, onPath: true };
+    const cli = join(root, "dist", "cli.js");
+    // Without `backstep` on the PATH, the commands printed below go through npx.
+    const bs = onPath ? "backstep" : "npx -y backstep";
+    const install = () => run("claude", ["plugin", "install", "backstep", "--marketplace", join(root, "mod"), "--config", `cli=${cli}`]);
+    let r = install();
+    // Installed before from another copy (the file a person was given, or ~/.backstep before npm worked):
+    // Claude Code keeps one source per name, so swap the old one for this.
+    if (!r.ok && /already added from a different source/i.test(r.out)) {
+        run("claude", ["plugin", "marketplace", "remove", "backstep"]);
+        r = install();
+    }
+    if (!r.ok)
+        throw new Error(`claude plugin install failed:\n${r.out}`);
+    // Only a problem is worth a line here; the summary below says the rest.
+    const bound = bindUndoKey();
+    if (bound)
+        console.log(`  ${white("!")} ${bound}`);
+    // Wrap last, so a failed install never leaves servers pointing at a Backstep that isn't there.
+    autoWrap(true);
+    wrapServers(cli);
+    // What's covered and what isn't, said once here and kept up to date by `backstep status`.
+    console.log(`\n  ${pink("✓")} ${white("Backstep is ready.")} Restart Claude Code, then press ${white(UNDO_KEY)} after any turn to undo it.`);
+    printCheck(check(process.cwd()), bs);
+    if (telemetryOn()) {
+        console.log(dim("  Sends an anonymous install count. Turn it off with BACKSTEP_TELEMETRY=0.\n"));
+        await sendInstall();
+    }
+}

package/dist/shell.js

@@ -0,0 +1,112 @@
+// Decides what a shell command Claude is about to run could do, before it runs.
+// Reads pass straight through; commands that reach outside the machine can't be
+// taken back, so they're held; everything else gets the project snapshotted.
+// Programs that only look. A pipeline or chain is a read only if every part is.
+const READ_PROGRAMS = new Set([
+    "ls", "ll", "la", "cat", "head", "tail", "less", "more", "grep", "egrep", "fgrep", "rg", "ag", "fd", "find", "tree",
+    "wc", "du", "df", "pwd", "echo", "printf", "which", "whereis", "type", "file", "stat", "diff", "cmp", "sort", "uniq",
+    "cut", "tr", "column", "jq", "yq", "date", "whoami", "id", "uname", "env", "printenv", "ps", "top", "uptime",
+    "basename", "dirname", "realpath", "readlink", "md5", "md5sum", "shasum", "sha256sum", "true", "false", "test", "[",
+    "sleep", "man", "tldr", "history", "lsof", "hostname", "cal", "nproc",
+]);
+const READ_GIT = new Set([
+    "status", "log", "diff", "show", "blame", "grep", "ls-files", "ls-tree", "rev-parse", "describe", "shortlog",
+    "reflog", "cat-file", "whatchanged", "count-objects", "check-ignore", "merge-base", "name-rev", "for-each-ref",
+]);
+// `git branch` and friends only read when they're just listing.
+const LISTING_GIT = new Set(["branch", "tag", "remote", "stash", "worktree", "config"]);
+const READ_VERSION = /^(-v|--version|-h|--help|version|help)$/;
+// Commands that act on something outside this machine.
+const OUTBOUND = [
+    [/^git (push|send-email|svn dcommit)\b/, "pushes to a remote"],
+    [/^(npm|pnpm|yarn|bun) (publish|unpublish|deprecate|dist-tag)\b/, "publishes a package"],
+    [/^(cargo|gem|twine|poetry|flit) (publish|push|upload)\b/, "publishes a package"],
+    [/^gh (pr (create|merge|close|comment|review|edit)|issue (create|close|comment|edit|delete)|release (create|delete|upload)|repo (create|delete|edit)|secret|workflow run|api)\b/, "changes GitHub"],
+    [/^(vercel|netlify|fly|flyctl|heroku|firebase|wrangler|railway|surge)\b(?!.*\s(--version|-v|--help|login|whoami|logs|ls|list)(\s|$))/, "deploys"],
+    [/^(kubectl (apply|delete|create|patch|replace|scale|rollout)|helm (install|upgrade|uninstall|rollback)|terraform (apply|destroy)|pulumi (up|destroy)|aws |gcloud |az )/, "changes cloud resources"],
+    [/^docker (push|login)\b/, "pushes an image"],
+    [/^(ssh|scp|sftp|rsync .*:\S)/, "runs on another machine"],
+    [/^(curl|wget|http|xh)\b.*(\s-X\s*(POST|PUT|PATCH|DELETE)|\s--request\s+(POST|PUT|PATCH|DELETE)|\s(-d|--data\S*|-F|--form|-T|--upload-file)\b|\s(POST|PUT|PATCH|DELETE)\s)/i, "sends a request"],
+    [/^(sendmail|mail|mutt)\b/, "sends email"],
+    [/^(psql|mysql|mongosh|redis-cli)\b/, "changes a database directly"],
+];
+// Splits on ; && || | and newlines, outside quotes. Good enough to judge each part.
+function parts(cmd) {
+    const out = [];
+    let cur = "";
+    let quote = null;
+    for (let i = 0; i < cmd.length; i++) {
+        const c = cmd[i];
+        if (quote) {
+            if (c === quote)
+                quote = null;
+            cur += c;
+        }
+        else if (c === "'" || c === '"') {
+            quote = c;
+            cur += c;
+        }
+        else if ((c === ";" || c === "\n" || c === "|" || c === "&") && !(c === "&" && (cmd[i - 1] === ">" || cmd[i + 1] === ">"))) {
+            out.push(cur);
+            cur = "";
+            if (cmd[i + 1] === c)
+                i++;
+        }
+        else {
+            cur += c;
+        }
+    }
+    out.push(cur);
+    return out.map((p) => p.trim()).filter(Boolean);
+}
+// Drops leading VAR=value assignments and wrappers like sudo, time, env.
+function strip(part) {
+    let p = part.replace(/^\(+/, "").trim();
+    for (;;) {
+        const next = p
+            .replace(/^[A-Za-z_][A-Za-z0-9_]*=("[^"]*"|'[^']*'|\S*)\s+/, "")
+            .replace(/^(sudo|time|nice|nohup|command|exec|env)\s+/, "")
+            .replace(/^npx\s+(-y\s+|--yes\s+)?/, "");
+        if (next === p)
+            return p;
+        p = next;
+    }
+}
+function isRead(part) {
+    // Writing to a file through redirection is a write, whatever the program.
+    if (/(^|[^0-9&])>{1,2}\s*(?!&|\/dev\/null)/.test(part.replace(/'[^']*'|"[^"]*"/g, "")))
+        return false;
+    const words = part.split(/\s+/);
+    const [prog, sub, ...rest] = words;
+    if (READ_PROGRAMS.has(prog)) {
+        if (prog === "find" && /\s-(delete|exec|execdir|ok|fprint)\b/.test(part))
+            return false;
+        if ((prog === "sort" || prog === "tree") && /\s-o\b/.test(part))
+            return false;
+        return true;
+    }
+    if (sub !== undefined && READ_VERSION.test(sub))
+        return true;
+    if (prog === "git" && sub !== undefined) {
+        if (READ_GIT.has(sub))
+            return true;
+        if (LISTING_GIT.has(sub)) {
+            const args = rest.filter((w) => w !== "-v" && w !== "-vv" && w !== "-a" && w !== "-r" && w !== "--list" && w !== "-l" && w !== "list" && w !== "--all");
+            return args.length === 0 || (sub === "config" && (args[0] === "--get" || args[0] === "--get-all"));
+        }
+    }
+    if ((prog === "npm" || prog === "pnpm" || prog === "yarn") && /^(ls|list|view|info|outdated|why|audit)$/.test(sub ?? ""))
+        return true;
+    return false;
+}
+export function classifyShell(command) {
+    const ps = parts(command).map(strip);
+    for (const p of ps) {
+        for (const [re, reason] of OUTBOUND)
+            if (re.test(p))
+                return { kind: "outbound", reason };
+    }
+    if (ps.length > 0 && ps.every(isRead))
+        return { kind: "read" };
+    return { kind: "write" };
+}

package/dist/sql.js

@@ -0,0 +1,88 @@
+// Just enough SQL understanding to know which tables a statement will change.
+// This is not a parser: anything it can't place is reported as "unknown" so
+// the caller treats it as irreversible instead of guessing.
+const IDENT = String.raw `(?:"[^"]+"|[A-Za-z_][\w$]*)(?:\s*\.\s*(?:"[^"]+"|[A-Za-z_][\w$]*))?`;
+const LIST = String.raw `${IDENT}(?:\s*,\s*${IDENT})*`;
+// Splits on semicolons outside quotes and comments.
+export function splitStatements(sql) {
+    const out = [];
+    let cur = "";
+    let quote = null;
+    for (let i = 0; i < sql.length; i++) {
+        const c = sql[i];
+        if (quote) {
+            cur += c;
+            if (c === quote)
+                quote = null;
+            continue;
+        }
+        if (c === "'" || c === '"') {
+            quote = c;
+            cur += c;
+        }
+        else if (c === "-" && sql[i + 1] === "-") {
+            const end = sql.indexOf("\n", i);
+            i = end === -1 ? sql.length : end;
+            cur += " ";
+        }
+        else if (c === "/" && sql[i + 1] === "*") {
+            const end = sql.indexOf("*/", i + 2);
+            i = end === -1 ? sql.length : end + 1;
+            cur += " ";
+        }
+        else if (c === ";") {
+            if (cur.trim())
+                out.push(cur.trim());
+            cur = "";
+        }
+        else {
+            cur += c;
+        }
+    }
+    if (cur.trim())
+        out.push(cur.trim());
+    return out;
+}
+function names(list) {
+    const re = new RegExp(IDENT, "g");
+    return [...list.matchAll(re)].map((m) => m[0].replace(/\s+/g, ""));
+}
+export function classifyStatement(text) {
+    const s = text.replace(/\s+/g, " ").trim();
+    const base = { text, tables: [], ifExists: false };
+    let m;
+    if (/^(select|show|explain|values|table)\b/i.test(s))
+        return { ...base, op: "read" };
+    if (/^with\b/i.test(s)) {
+        // A CTE that writes anywhere is too tangled to snapshot reliably.
+        return { ...base, op: /\b(insert|update|delete|merge)\b/i.test(s) ? "unknown" : "read" };
+    }
+    if ((m = s.match(new RegExp(String.raw `^insert\s+into\s+(${IDENT})`, "i")))) {
+        return { ...base, op: "insert", tables: names(m[1]) };
+    }
+    if ((m = s.match(new RegExp(String.raw `^update\s+(?:only\s+)?(${IDENT})`, "i")))) {
+        return { ...base, op: "update", tables: names(m[1]) };
+    }
+    if ((m = s.match(new RegExp(String.raw `^delete\s+from\s+(?:only\s+)?(${IDENT})`, "i")))) {
+        return { ...base, op: "delete", tables: names(m[1]) };
+    }
+    if ((m = s.match(new RegExp(String.raw `^truncate\s+(?:table\s+)?(?:only\s+)?(${LIST})`, "i")))) {
+        // CASCADE empties tables we can't see from here.
+        if (/\bcascade\b/i.test(s))
+            return { ...base, op: "unknown" };
+        return { ...base, op: "truncate", tables: names(m[1]) };
+    }
+    if ((m = s.match(new RegExp(String.raw `^drop\s+table\s+(if\s+exists\s+)?(${LIST})`, "i")))) {
+        return { ...base, op: "drop", tables: names(m[2]), ifExists: Boolean(m[1]) };
+    }
+    if ((m = s.match(new RegExp(String.raw `^alter\s+table\s+(?:if\s+exists\s+)?(?:only\s+)?(${IDENT})`, "i")))) {
+        return { ...base, op: "alter", tables: names(m[1]) };
+    }
+    if ((m = s.match(new RegExp(String.raw `^create\s+(?:unlogged\s+)?table\s+(?:if\s+not\s+exists\s+)?(${IDENT})`, "i")))) {
+        return { ...base, op: "create", tables: names(m[1]) };
+    }
+    return { ...base, op: "unknown" };
+}
+export function parseSql(sql) {
+    return splitStatements(sql).map(classifyStatement);
+}

package/dist/store.js

@@ -0,0 +1,132 @@
+// The journal: every run and every tool call an agent makes through Backstep.
+// SQLite in WAL mode so the proxy and the dashboard can share it across processes.
+import { DatabaseSync } from "node:sqlite";
+import { chmodSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+export function homeDir() {
+    return process.env.BACKSTEP_HOME ?? join(homedir(), ".backstep");
+}
+export function snapshotDir(actionId) {
+    return join(homeDir(), "snapshots", actionId);
+}
+export function shortId() {
+    return randomUUID().replaceAll("-", "").slice(0, 12);
+}
+export class Store {
+    db;
+    constructor(dir = homeDir()) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const file = join(dir, "journal.db");
+        this.db = new DatabaseSync(file);
+        // The journal can hold database URLs, so keep it private to this user.
+        chmodSync(file, 0o600);
+        this.db.exec(`
+      PRAGMA journal_mode = WAL;
+      PRAGMA busy_timeout = 5000;
+      CREATE TABLE IF NOT EXISTS runs (
+        id TEXT PRIMARY KEY,
+        server TEXT NOT NULL,
+        command TEXT NOT NULL,
+        pg_url TEXT,
+        started_at INTEGER NOT NULL,
+        ended_at INTEGER
+      );
+      CREATE TABLE IF NOT EXISTS actions (
+        id TEXT PRIMARY KEY,
+        run_id TEXT NOT NULL REFERENCES runs(id),
+        seq INTEGER NOT NULL,
+        tool TEXT NOT NULL,
+        args TEXT NOT NULL,
+        kind TEXT NOT NULL,
+        status TEXT NOT NULL,
+        reason TEXT,
+        undo TEXT,
+        result TEXT,
+        error TEXT,
+        created_at INTEGER NOT NULL,
+        release_at INTEGER,
+        undone_at INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS actions_run ON actions(run_id, seq);
+      CREATE INDEX IF NOT EXISTS actions_created ON actions(created_at);
+    `);
+    }
+    createRun(server, command, pgUrl) {
+        const run = {
+            id: shortId(),
+            server,
+            command,
+            pg_url: pgUrl,
+            started_at: Date.now(),
+            ended_at: null,
+        };
+        this.db
+            .prepare("INSERT INTO runs (id, server, command, pg_url, started_at) VALUES (?, ?, ?, ?, ?)")
+            .run(run.id, run.server, run.command, run.pg_url, run.started_at);
+        return run;
+    }
+    // Claude Code's own tool calls have no proxy to open a run, so each session
+    // gets one, found again by its command on every call.
+    sessionRun(server, command) {
+        const found = this.db
+            .prepare("SELECT * FROM runs WHERE server = ? AND command = ? ORDER BY started_at DESC LIMIT 1")
+            .get(server, command);
+        return found ?? this.createRun(server, command, null);
+    }
+    endRun(id) {
+        this.db.prepare("UPDATE runs SET ended_at = ? WHERE id = ?").run(Date.now(), id);
+    }
+    getRun(id) {
+        return this.db.prepare("SELECT * FROM runs WHERE id = ?").get(id);
+    }
+    listRuns(limit = 50) {
+        return this.db
+            .prepare(`SELECT r.*,
+           (SELECT COUNT(*) FROM actions a WHERE a.run_id = r.id) AS actions,
+           (SELECT COUNT(*) FROM actions a WHERE a.run_id = r.id AND a.undo IS NOT NULL AND a.status IN ('ok', 'error')) AS undoable
+         FROM runs r ORDER BY r.started_at DESC LIMIT ?`)
+            .all(limit);
+    }
+    addAction(a) {
+        const id = shortId();
+        const seq = (this.db.prepare("SELECT MAX(seq) AS m FROM actions WHERE run_id = ?").get(a.run_id)
+            .m ?? 0) + 1;
+        const created_at = Date.now();
+        this.db
+            .prepare(`INSERT INTO actions (id, run_id, seq, tool, args, kind, status, reason, undo, result, error, created_at, release_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, a.run_id, seq, a.tool, a.args, a.kind, a.status, a.reason, a.undo, a.result, a.error, created_at, a.release_at);
+        return { ...a, id, seq, created_at, undone_at: null };
+    }
+    updateAction(id, fields) {
+        const keys = Object.keys(fields);
+        if (keys.length === 0)
+            return;
+        const set = keys.map((k) => `${k} = ?`).join(", ");
+        const values = keys.map((k) => fields[k] ?? null);
+        this.db.prepare(`UPDATE actions SET ${set} WHERE id = ?`).run(...values, id);
+    }
+    // Moves an action between states only if it is still in the expected one,
+    // so the proxy releasing a hold and a user cancelling it can't both win.
+    transition(id, from, to) {
+        const r = this.db.prepare("UPDATE actions SET status = ? WHERE id = ? AND status = ?").run(to, id, from);
+        return r.changes === 1;
+    }
+    getAction(id) {
+        return this.db.prepare("SELECT * FROM actions WHERE id = ?").get(id);
+    }
+    listActions(runId) {
+        return this.db.prepare("SELECT * FROM actions WHERE run_id = ? ORDER BY seq").all(runId);
+    }
+    feed(limit = 200) {
+        return this.db
+            .prepare(`SELECT a.*, r.server FROM actions a JOIN runs r ON r.id = a.run_id
+         ORDER BY a.created_at DESC LIMIT ?`)
+            .all(limit);
+    }
+    close() {
+        this.db.close();
+    }
+}