backstep 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# Backstep
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Undo for everything your agents touch. Backstep sits between your agent (Claude Code, Cursor, any MCP client) and the MCP servers it uses. Before a tool changes something, Backstep saves a way back. When an agent goes wrong, you undo the action, or the whole run, from a dashboard.
+
+- **Files:** every path a tool is about to touch is copied first. Writes, edits, deletes, creates and moves all roll back.
+- **Postgres:** `INSERT`/`UPDATE`/`DELETE`/`TRUNCATE` snapshot the table first. `DROP TABLE` never really drops: the table is moved to a `backstep_trash` schema with its indexes, constraints and sequences, so undo brings it back exactly. `CREATE TABLE` is undone by dropping the new table.
+- **Shell commands Claude runs:** before each one, the project folder is saved into a hidden git history under `~/.backstep/trees`, along with the project's own branches, HEAD and staged files. `rm`, `git reset --hard`, scripts that rewrite files and new branches all roll back. Commands that only read are skipped.
+- **Supabase:** `execute_sql` and `apply_migration` snapshot the tables they change, over a connection to the project's database. Backstep never connects it on its own: when Claude Code opens a project that uses Supabase and isn't connected, it asks (Connect, Not now, or Don't ask for this project). Connect uses a connection string in the project's `.env` files, the local `supabase start` database, or a Supabase sign-in (`supabase login`, `SUPABASE_ACCESS_TOKEN`, or an access token you give Backstep once), with which the project gets a temporary database login that Backstep renews as it runs out. You can also ask Claude to "connect Backstep to Supabase" any time. Deleted rows, dropped tables and migrations, including the migration's history row, all come back. Works for the claude.ai Supabase connector and a local Supabase MCP server alike.
+- **Firebase:** before a change, Backstep reads what's there through the Firebase MCP server itself, and undoes through it too, so there's nothing to set up. Firestore documents updated, deleted or added; Realtime Database writes; Remote Config publishes (rolled back to the version before); and users enabled or disabled.
+- **claude.ai connectors and servers Claude Code signs in to:** Backstep can't sit in front of these, so the Claude Code mod watches their calls instead. Calls with an undo rule are undone through Claude Code's own connection.
+- **Code Claude pushed:** ctrl+z rewinds the commits locally, then asks whether to undo them on GitHub (or any remote) too. Yes pushes one new commit that undoes Claude's, made in a temporary worktree: no force push, no rewritten history, so it works on protected branches and for teammates who already pulled. Newer commits that clash, or a rewritten branch, stop it. A branch Claude created is deleted instead, if nobody has added to it. It uses the project's own git sign-in, so there's nothing to connect.
+- **Things that can't be undone** (sending email, payments, deploys, `ALTER TABLE`…) run as normal and are marked in the journal, so you know what an undo didn't cover.
+- **Anything else, by rule:** a rules file maps a tool to its opposite (`create_issue` → close the issue, `send_message` → retract it), filled in from the call and its result. See [Undo rules](#undo-rules).
+- **Conflicts:** undoing an action first undoes any later action that touched the same file or table, so nothing gets silently thrown away.
+
+## Install
+
+```sh
+npx backstep setup
+```
+
+This installs Backstep, adds its Claude Code mod, binds **ctrl+z** to undo everything Claude did in its last turn, and puts the MCP servers you've already added to Claude Code behind Backstep, so their changes can be undone too. If you use Supabase, it asks for your database's connection string (Enter skips; you can ask Claude to connect it later). Restart Claude Code afterwards. Needs Node 22.13+ and Claude Code.
+
+Servers in a repo's shared `.mcp.json` that you've approved get a wrapped copy for that project only; the repo's file is never edited. Remote servers that Claude Code signs in to stay as they are, and the mod watches their calls instead. Servers you add later are wrapped the next time Claude Code starts. `backstep unwrap` puts every server back the way it was and stops new ones being wrapped.
+
+## Try it
+
+```sh
+npm install
+npm run demo     # throwaway Postgres on :5544 with a customers table; prints the claude mcp add line
+npm run ui       # dashboard at http://localhost:4747
+```
+
+Then ask Claude to drop the customers table, and press **Undo** in the dashboard.
+
+## Wrap any MCP server
+
+```sh
+backstep wrap --name files -- npx -y @modelcontextprotocol/server-filesystem ~/project
+backstep wrap --name db --pg "$DATABASE_URL" -- npx -y some-postgres-mcp-server
+backstep wrap --name github --url https://api.githubcopilot.com/mcp/ \
+  --header 'Authorization: Bearer ${GITHUB_TOKEN}' --rules examples/rules.json
+```
+
+With Claude Code: `claude mcp add files -- backstep wrap --name files -- <the server command>`.
+
+| Option | |
+|---|---|
+| `--name` | label in the dashboard |
+| `--url <url>` | wrap a remote MCP server (Streamable HTTP, falls back to SSE) |
+| `--header "K: V"` | header for the remote server, repeatable. `${VAR}` is read from the environment so tokens stay out of config files |
+| `--rules <file>` | undo rules (or set `BACKSTEP_RULES`) |
+| `--pg <url>` | the Postgres database the wrapped server writes to. Enables database undo. Without it, SQL writes are recorded but can't be undone. |
+
+Other commands: `backstep ui`, `backstep log`, `backstep undo <action-id>`, `backstep undo --run <run-id>`, `backstep connect [supabase|firebase]` (connects what the project uses, the same as asking Claude), `backstep disconnect supabase <ref>`.
+
+In Claude Code you can just ask: "connect Backstep to everything I use". Supabase is connected from the project's settings (or the connection string you paste), and when the project uses Firebase but Claude can't reach it yet, Firebase's MCP server is added behind Backstep.
+
+During development, run `node src/cli.ts …` (Node 24 runs the TypeScript directly). `npm run build` compiles to `dist/`.
+
+## Undo rules
+
+For tools Backstep can't snapshot, a rule names the tool that undoes them. `{{args.x}}` comes from the original call; `{{result.x}}` comes from its result (structured content, or the text parsed as JSON).
+
+```json
+{ "rules": [
+  { "server": "github", "tool": "create_issue",
+    "inverse": { "tool": "update_issue",
+                 "args": { "owner": "{{args.owner}}", "repo": "{{args.repo}}",
+                           "issue_number": "{{result.number}}", "state": "closed" } } }
+] }
+```
+
+`server` is optional and matches `--name`. For claude.ai connectors and servers Claude Code signs in to, put rules in `~/.backstep/rules.json`; `server` is the name as it appears in tool names (`claude_ai_Notion`), and pressing ctrl+z runs the opposite call through Claude Code. A rule overrides the built-in guess, so a `send_message` with a retract rule is undoable. The undo runs through a live `backstep wrap` of that server; if none is running, the dashboard tells you to start it, and any running copy with the same `--name` picks up the request. `examples/rules.json` has GitHub rules as a starting point. Check the tool and argument names against your server's version.
+
+## How it decides
+
+Each call is classified before it runs (`src/classify.ts`):
+
+0. **Undo rules** match first, then **Firebase** tools.
+1. **SQL** (an argument like `sql`/`query` that reads like SQL): judged by the statements, not the tool name. Reads pass through.
+2. **Reads:** `readOnlyHint`, or names like `get_*`, `list_*`, `read_*`, `search_*`.
+3. **Irreversible:** names like `send_*`, `pay`, `deploy`, `execute_command`, or `destructiveHint`/`openWorldHint` with nothing to snapshot. These run and are marked, not undone.
+4. **Paths:** arguments named `path`, `source`, `destination`… get file snapshots.
+5. Anything else is recorded as a write with no undo.
+
+Everything is journaled to `~/.backstep/journal.db` (SQLite, mode 0600; override with `BACKSTEP_HOME`). File snapshots live in `~/.backstep/snapshots/`, Postgres snapshots in the `backstep` schema of your database.
+
+## Known limits (MVP)
+
+- `ALTER TABLE`, writing CTEs, `TRUNCATE … CASCADE`, functions and other DDL run but aren't undone.
+- Table snapshots are full copies, capped at ~1M rows; changes to bigger tables aren't undoable. Files are capped at 50 MB per call.
+- Supabase changes need the database connected. Without it they run as normal and the Claude Code mod says once to ask Claude to connect it. The connection string is kept in `~/.backstep/connections.json` (mode 0600).
+- Firebase undo needs the Firebase server running behind Backstep (it is after setup). Custom claims on users, Storage, Cloud Messaging and deploys aren't undone. Firestore undo puts the whole document back, so a change someone else made to it in between is lost too.
+- Google's own Firestore MCP server, connected with sign-in, is watched rather than wrapped, so its changes aren't undone yet.
+- Undoing a table restore runs `DELETE` and then re-inserts rows, so foreign keys from other tables pointing at deleted rows can block it. The undo then fails cleanly inside a transaction.
+- `--pg` must point at the same database the wrapped server uses.
+- The dashboard only accepts requests from this machine. The journal stores the `--pg` URL so undo works later.
+- Remote servers that need an OAuth login can't be wrapped; they're watched from Claude Code instead, so their undo works with ctrl+z but not from the dashboard.
+- Shell snapshots cover the project folder (the git repository, or the folder Claude Code runs in). Files outside it, and ignored folders like `node_modules`, aren't saved: undo restores `package.json` and the lockfile, and you re-run the install.
+- Shell commands are judged before they run by what they look like, so a script that pushes or deploys from inside is snapshotted, not held.
+
+## Telemetry
+
+`backstep setup` sends one anonymous `install` event, and Claude Code with the Backstep mod sends one `active` event a day. Each carries a random id made on your machine (`~/.backstep/install-id`), the Backstep version, your OS and CPU type, and the Node major version. Nothing else: no paths, commands, server names, IP-based location, or anything from the journal. The code is `src/telemetry.ts`.
+
+Turn it off with `BACKSTEP_TELEMETRY=0`, or the standard `DO_NOT_TRACK=1`.
+
+## Tests
+
+```sh
+npm test
+```
+
+Runs the official filesystem MCP server and a SQL MCP server on PGlite through the real proxy, plus a remote HTTP server that requires an API key. Then it checks undo, conflict chains, undo rules and dashboard request checks. Supabase is checked against a real Postgres (PGlite), through both the connector path and the proxy, and Firebase against a stand-in server with the real tool names.
+
+## Landing page
+
+`site/index.html` is a static page with no build step. Open it directly, or deploy the folder with `vercel deploy site`. Set `ACCESS_EMAIL` at the top of its script before it goes live; until then the early-access form says access opens soon.

package/dist/adapters/fs.js

@@ -0,0 +1,66 @@
+// File undo: copy every path a tool is about to touch, then put it all back.
+// Restoring "the state each path was in" handles writes, edits, deletes,
+// creates and moves with one rule.
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { snapshotDir } from "../store.js";
+const MAX_BYTES = 50 * 1024 * 1024;
+export function resolvePath(p, cwd) {
+    if (p === "~" || p.startsWith("~/"))
+        return join(homedir(), p.slice(1));
+    return resolve(cwd, p);
+}
+function sizeOf(p, budget) {
+    const st = lstatSync(p);
+    if (!st.isDirectory())
+        return st.size;
+    let total = 0;
+    for (const name of readdirSync(p)) {
+        total += sizeOf(join(p, name), budget - total);
+        if (total > budget)
+            return total;
+    }
+    return total;
+}
+// Returns null when a path is too large to copy; the caller then can't promise undo.
+export function snapshotPaths(actionId, paths, cwd) {
+    const dir = snapshotDir(actionId);
+    const seen = new Set();
+    const entries = [];
+    let budget = MAX_BYTES;
+    for (const raw of paths) {
+        const path = resolvePath(raw, cwd);
+        if (seen.has(path))
+            continue;
+        seen.add(path);
+        if (!existsSync(path)) {
+            entries.push({ path, existed: false, snapshot: null });
+            continue;
+        }
+        const size = sizeOf(path, budget);
+        if (size > budget)
+            return null;
+        budget -= size;
+        const snapshot = join(dir, String(entries.length));
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        cpSync(path, snapshot, { recursive: true, preserveTimestamps: true, verbatimSymlinks: true });
+        entries.push({ path, existed: true, snapshot });
+    }
+    return { adapter: "fs", entries };
+}
+export function undoPaths(undo) {
+    const restored = [];
+    for (const e of undo.entries) {
+        rmSync(e.path, { recursive: true, force: true });
+        if (e.existed && e.snapshot) {
+            mkdirSync(dirname(e.path), { recursive: true });
+            cpSync(e.snapshot, e.path, { recursive: true, preserveTimestamps: true, verbatimSymlinks: true });
+            restored.push(`restored ${e.path}`);
+        }
+        else {
+            restored.push(`removed ${e.path}`);
+        }
+    }
+    return restored.join("\n");
+}

package/dist/adapters/postgres.js

@@ -0,0 +1,220 @@
+// Postgres undo.
+//  - INSERT / UPDATE / DELETE / TRUNCATE: copy the table into the `backstep`
+//    schema first; undo puts the rows back.
+//  - DROP TABLE: never actually dropped. Backstep runs the call itself and moves
+//    the table (with its indexes, constraints and sequences) into `backstep_trash`.
+//  - CREATE TABLE: undo drops the new table.
+//    Where Backstep can't run SQL in place of the server (Supabase runs it
+//    through its own API), the DROP is rewritten into that move instead.
+// Anything else (ALTER, CTE writes, TRUNCATE ... CASCADE, functions) is reported
+// as irreversible instead of pretending.
+import pg from "pg";
+import { parseSql } from "../sql.js";
+const MAX_ROWS = 1_000_000;
+const SNAP_SCHEMA = "backstep";
+const TRASH_SCHEMA = "backstep_trash";
+export function q(ident) {
+    return `"${ident.replaceAll('"', '""')}"`;
+}
+async function withClient(url, fn) {
+    const client = new pg.Client({ connectionString: url });
+    await client.connect();
+    try {
+        return await fn(client);
+    }
+    finally {
+        await client.end();
+    }
+}
+async function resolveTable(c, name) {
+    const r = await c.query(`SELECT n.nspname AS schema, c.relname AS name, c.reltuples::bigint AS rows
+     FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+     WHERE c.oid = to_regclass($1) AND c.relkind IN ('r', 'p')`, [name]);
+    if (r.rowCount === 0)
+        return null;
+    return { schema: r.rows[0].schema, name: r.rows[0].name, rows: Number(r.rows[0].rows) };
+}
+function key(t) {
+    return `${t.schema}.${t.name}`;
+}
+const UNSUPPORTED = {
+    alter: "ALTER TABLE changes structure, which Backstep can't snapshot yet",
+    unknown: "it contains a statement Backstep can't snapshot",
+};
+export async function planSql(url, actionId, sql, opts = {}) {
+    const statements = parseSql(sql);
+    for (const s of statements) {
+        const why = UNSUPPORTED[s.op];
+        if (why)
+            return { mode: "irreversible", reason: `${why}: ${s.text.slice(0, 80)}` };
+    }
+    const hasDrop = statements.some((s) => s.op === "drop");
+    return withClient(url, async (c) => {
+        const undo = { adapter: "pg", snapshots: [], trashed: [], created: [] };
+        const snapped = new Set();
+        const createdHere = new Set();
+        const snapshot = async (raw) => {
+            const t = await resolveTable(c, raw);
+            if (!t || snapped.has(key(t)) || createdHere.has(key(t)))
+                return;
+            if (t.rows > MAX_ROWS)
+                throw new TooBig(`${key(t)} has about ${t.rows} rows, over the ${MAX_ROWS} snapshot limit`);
+            const snap = `${actionId}_${undo.snapshots.length}`;
+            await c.query(`CREATE SCHEMA IF NOT EXISTS ${q(SNAP_SCHEMA)}`);
+            await c.query(`CREATE TABLE ${q(SNAP_SCHEMA)}.${q(snap)} AS TABLE ${q(t.schema)}.${q(t.name)}`);
+            snapped.add(key(t));
+            undo.snapshots.push({ schema: t.schema, name: t.name, snapshot: snap });
+        };
+        const noteCreate = async (raw) => {
+            const exists = await resolveTable(c, raw);
+            if (exists)
+                return;
+            // The table doesn't exist yet, so resolve its future name by hand.
+            const parts = raw.split(".").map((p) => p.replace(/^"|"$/g, ""));
+            const [schema, name] = parts.length === 2 ? parts : [(await c.query("SELECT current_schema() AS s")).rows[0].s, parts[0]];
+            const n = /^".*"$/.test(raw.split(".").at(-1)) ? name : name.toLowerCase();
+            createdHere.add(`${schema}.${n}`);
+            undo.created.push({ schema, name: n });
+        };
+        try {
+            for (const t of opts.alsoSnapshot ?? [])
+                await snapshot(t);
+            if (!hasDrop) {
+                for (const s of statements) {
+                    if (s.op === "create")
+                        await Promise.all(s.tables.map(noteCreate));
+                    else if (s.op !== "read")
+                        for (const t of s.tables)
+                            await snapshot(t);
+                }
+                return { mode: "forward", undo };
+            }
+            if (opts.rewrite) {
+                // The server runs the call as one transaction, so the moves only stick if it all does.
+                const out = [];
+                for (const s of statements) {
+                    if (s.op !== "drop") {
+                        if (s.op === "create")
+                            for (const t of s.tables)
+                                await noteCreate(t);
+                        else if (s.op !== "read")
+                            for (const t of s.tables)
+                                await snapshot(t);
+                        out.push(s.text);
+                        continue;
+                    }
+                    for (const raw of s.tables) {
+                        const t = await resolveTable(c, raw);
+                        // Missing: let the server say so. Made in this same call: nothing to keep.
+                        if (!t || createdHere.has(key(t))) {
+                            out.push(`DROP TABLE ${s.ifExists ? "IF EXISTS " : ""}${raw}`);
+                            continue;
+                        }
+                        const trash = `${actionId}_${undo.trashed.length}_${t.name}`.slice(0, 63);
+                        out.push(`CREATE SCHEMA IF NOT EXISTS ${q(TRASH_SCHEMA)}`, `ALTER TABLE ${q(t.schema)}.${q(t.name)} RENAME TO ${q(trash)}`, `ALTER TABLE ${q(t.schema)}.${q(trash)} SET SCHEMA ${q(TRASH_SCHEMA)}`);
+                        undo.trashed.push({ schema: t.schema, name: t.name, trash });
+                    }
+                }
+                return { mode: "rewrite", undo, sql: out.join(";\n") + ";" };
+            }
+            // A DROP is in there, so run the whole call here inside one transaction.
+            const done = [];
+            await c.query("BEGIN");
+            try {
+                for (const s of statements) {
+                    if (s.op === "drop") {
+                        for (const raw of s.tables) {
+                            const t = await resolveTable(c, raw);
+                            if (!t) {
+                                if (s.ifExists)
+                                    continue;
+                                throw new Error(`table "${raw}" does not exist`);
+                            }
+                            if (createdHere.has(key(t))) {
+                                await c.query(`DROP TABLE ${q(t.schema)}.${q(t.name)}`);
+                                continue;
+                            }
+                            const trash = `${actionId}_${undo.trashed.length}_${t.name}`.slice(0, 63);
+                            await c.query(`CREATE SCHEMA IF NOT EXISTS ${q(TRASH_SCHEMA)}`);
+                            await c.query(`ALTER TABLE ${q(t.schema)}.${q(t.name)} RENAME TO ${q(trash)}`);
+                            await c.query(`ALTER TABLE ${q(t.schema)}.${q(trash)} SET SCHEMA ${q(TRASH_SCHEMA)}`);
+                            undo.trashed.push({ schema: t.schema, name: t.name, trash });
+                        }
+                        done.push(`DROP TABLE (moved to ${TRASH_SCHEMA})`);
+                        continue;
+                    }
+                    if (s.op === "create")
+                        for (const t of s.tables)
+                            await noteCreate(t);
+                    else if (s.op !== "read")
+                        for (const t of s.tables)
+                            await snapshot(t);
+                    const r = await c.query(s.text);
+                    done.push(`${r.command ?? s.op.toUpperCase()}${r.rowCount != null ? ` ${r.rowCount}` : ""}`);
+                }
+                await c.query("COMMIT");
+            }
+            catch (err) {
+                await c.query("ROLLBACK");
+                throw err;
+            }
+            return { mode: "self", undo, summary: done.join("\n") };
+        }
+        catch (err) {
+            if (err instanceof TooBig)
+                return { mode: "irreversible", reason: err.message };
+            throw err;
+        }
+    });
+}
+class TooBig extends Error {
+}
+async function insertableColumns(c, schema, name) {
+    const r = await c.query(`SELECT a.attname FROM pg_attribute a
+     WHERE a.attrelid = to_regclass($1) AND a.attnum > 0 AND NOT a.attisdropped AND a.attgenerated = ''
+     ORDER BY a.attnum`, [`${q(schema)}.${q(name)}`]);
+    return r.rows.map((row) => row.attname);
+}
+export async function undoSql(url, undo) {
+    return withClient(url, async (c) => {
+        const log = [];
+        await c.query("BEGIN");
+        try {
+            for (const t of [...undo.created].reverse()) {
+                await c.query(`DROP TABLE IF EXISTS ${q(t.schema)}.${q(t.name)}`);
+                log.push(`dropped new table ${t.schema}.${t.name}`);
+            }
+            for (const t of [...undo.trashed].reverse()) {
+                if (await resolveTable(c, `${q(t.schema)}.${q(t.name)}`)) {
+                    throw new Error(`can't bring back ${t.schema}.${t.name}: a table with that name exists again`);
+                }
+                await c.query(`ALTER TABLE ${q(TRASH_SCHEMA)}.${q(t.trash)} SET SCHEMA ${q(t.schema)}`);
+                await c.query(`ALTER TABLE ${q(t.schema)}.${q(t.trash)} RENAME TO ${q(t.name)}`);
+                log.push(`restored dropped table ${t.schema}.${t.name}`);
+            }
+            for (const s of undo.snapshots) {
+                const cols = (await insertableColumns(c, s.schema, s.name)).map(q).join(", ");
+                const target = `${q(s.schema)}.${q(s.name)}`;
+                await c.query(`DELETE FROM ${target}`);
+                const r = await c.query(`INSERT INTO ${target} (${cols}) OVERRIDING SYSTEM VALUE SELECT ${cols} FROM ${q(SNAP_SCHEMA)}.${q(s.snapshot)}`);
+                log.push(`restored ${r.rowCount} rows in ${s.schema}.${s.name}`);
+            }
+            await c.query("COMMIT");
+        }
+        catch (err) {
+            await c.query("ROLLBACK");
+            throw err;
+        }
+        for (const s of undo.snapshots)
+            await c.query(`DROP TABLE IF EXISTS ${q(SNAP_SCHEMA)}.${q(s.snapshot)}`);
+        return log.join("\n");
+    });
+}
+export async function discardSnapshots(url, undo) {
+    if (undo.snapshots.length === 0)
+        return;
+    await withClient(url, async (c) => {
+        for (const s of undo.snapshots)
+            await c.query(`DROP TABLE IF EXISTS ${q(SNAP_SCHEMA)}.${q(s.snapshot)}`);
+    });
+}

package/dist/adapters/tree.js

@@ -0,0 +1,171 @@
+// Project undo for shell commands: before a command runs, the whole project
+// folder is committed into a hidden git repository Backstep keeps for it under
+// ~/.backstep/trees, and the project's own git state (branches, HEAD, index)
+// is noted. Git stores only what changed, so this stays fast on big projects.
+// Undo puts the folder and the git state back the way they were.
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+import { homeDir, snapshotDir } from "../store.js";
+const TIMEOUT_MS = 20_000;
+// Too big to copy and rebuilt by a command anyway. A project's own .gitignore is honoured too.
+const EXCLUDE = ["node_modules/", ".venv/", "venv/", "__pycache__/", ".next/", ".nuxt/", ".turbo/", ".cache/", ".DS_Store"];
+const ENV = {
+    ...process.env,
+    GIT_AUTHOR_NAME: "backstep",
+    GIT_AUTHOR_EMAIL: "backstep@localhost",
+    GIT_COMMITTER_NAME: "backstep",
+    GIT_COMMITTER_EMAIL: "backstep@localhost",
+    GIT_TERMINAL_PROMPT: "0",
+};
+function git(args, opts = {}) {
+    const pre = ["-c", "core.autocrlf=false", "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null"];
+    if (opts.gitDir)
+        pre.push("--git-dir", opts.gitDir);
+    if (opts.workTree)
+        pre.push("--work-tree", opts.workTree);
+    return execFileSync("git", [...pre, ...args], {
+        cwd: opts.cwd ?? opts.workTree,
+        env: ENV,
+        encoding: "utf8",
+        timeout: TIMEOUT_MS,
+        maxBuffer: 64 * 1024 * 1024,
+        stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+}
+function tryGit(args, cwd) {
+    try {
+        return git(args, { cwd });
+    }
+    catch {
+        return null;
+    }
+}
+// The project a command runs in: its git repository, or the folder itself.
+export function projectRoot(cwd) {
+    return tryGit(["rev-parse", "--show-toplevel"], cwd) ?? resolve(cwd);
+}
+function shadowFor(root) {
+    const gitDir = join(homeDir(), "trees", createHash("sha256").update(root).digest("hex").slice(0, 16) + ".git");
+    if (!existsSync(join(gitDir, "HEAD"))) {
+        mkdirSync(gitDir, { recursive: true, mode: 0o700 });
+        git(["init", "--bare", "--quiet", gitDir], { cwd: root });
+        mkdirSync(join(gitDir, "info"), { recursive: true });
+        writeFileSync(join(gitDir, "info", "exclude"), EXCLUDE.join("\n") + "\n");
+        writeFileSync(join(gitDir, "description"), `Backstep snapshots of ${root}\n`);
+    }
+    return gitDir;
+}
+// Stages the folder as it is now in the hidden repository's index and returns its tree.
+function stage(gitDir, root) {
+    git(["add", "--all", "--ignore-errors", "."], { gitDir, workTree: root });
+    return git(["write-tree"], { gitDir, workTree: root });
+}
+function refsUnder(root, prefix) {
+    const refs = {};
+    for (const line of (tryGit(["for-each-ref", "--format=%(refname) %(objectname)", prefix], root) ?? "").split("\n")) {
+        const [name, sha] = line.split(" ");
+        if (name && sha && !name.endsWith("/HEAD"))
+            refs[name] = sha;
+    }
+    return refs;
+}
+function projectGit(root, actionId, pushes) {
+    const dotGit = tryGit(["rev-parse", "--absolute-git-dir"], root);
+    if (!dotGit)
+        return null;
+    const head = tryGit(["symbolic-ref", "-q", "HEAD"], root) ?? tryGit(["rev-parse", "HEAD"], root) ?? "";
+    const refs = {};
+    for (const line of (tryGit(["for-each-ref", "--format=%(refname) %(objectname)", "refs/heads", "refs/tags"], root) ?? "").split("\n")) {
+        const [name, sha] = line.split(" ");
+        if (name && sha)
+            refs[name] = sha;
+    }
+    let index = null;
+    if (existsSync(join(dotGit, "index"))) {
+        const dir = snapshotDir(actionId);
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        index = join(dir, "index");
+        copyFileSync(join(dotGit, "index"), index);
+    }
+    return { head, refs, index, ...(pushes ? { remotes: refsUnder(root, "refs/remotes") } : {}) };
+}
+// Returns null when the folder can't be snapshotted: the home folder or the
+// whole disk, or a folder too big to stage in time.
+export function snapshotTree(actionId, cwd, opts = {}) {
+    const root = projectRoot(cwd);
+    if (root === "/" || root === homedir() || root === resolve(homeDir()))
+        return null;
+    try {
+        const gitDir = shadowFor(root);
+        const tree = stage(gitDir, root);
+        const commit = git(["commit-tree", tree, "-m", actionId], { gitDir, workTree: root });
+        // A ref per snapshot keeps it from being garbage collected until it's undone.
+        git(["update-ref", `refs/backstep/${actionId}`, commit], { gitDir, workTree: root });
+        return { adapter: "tree", root, gitDir, commit, git: projectGit(root, actionId, opts.pushes === true) };
+    }
+    catch {
+        return null;
+    }
+}
+// After a command that pushes: each remote branch that moved, and how far.
+export function notePushed(u) {
+    const before = u.git?.remotes;
+    if (!before)
+        return [];
+    const out = [];
+    for (const [ref, after] of Object.entries(refsUnder(u.root, "refs/remotes"))) {
+        const was = before[ref] ?? null;
+        if (was === after)
+            continue;
+        const [remote, ...rest] = ref.replace(/^refs\/remotes\//, "").split("/");
+        const commits = was ? Number(tryGit(["rev-list", "--count", `${was}..${after}`], u.root) ?? "0") : Number(tryGit(["rev-list", "--count", after], u.root) ?? "0");
+        out.push({ remote, branch: rest.join("/"), before: was, after, commits, host: remoteHost(u.root, remote) });
+    }
+    return out;
+}
+function remoteHost(root, remote) {
+    const url = tryGit(["remote", "get-url", remote], root) ?? "";
+    const host = url.match(/^(?:[a-z+]+:\/\/)?(?:[^@/]+@)?([^/:]+)/i)?.[1] ?? "";
+    return /github\.com$/i.test(host) ? "GitHub" : /gitlab/i.test(host) ? "GitLab" : /bitbucket/i.test(host) ? "Bitbucket" : remote;
+}
+export function undoTree(u, actionId) {
+    const { root, gitDir } = u;
+    // Stage what's there now, then move the index and the folder to the snapshot:
+    // changed and deleted files come back, files made since are removed, and
+    // ignored files are left alone.
+    stage(gitDir, root);
+    const before = git(["diff", "--cached", "--name-status", u.commit], { gitDir, workTree: root });
+    git(["read-tree", "--reset", "-u", u.commit], { gitDir, workTree: root });
+    git(["update-ref", "-d", `refs/backstep/${actionId}`], { gitDir, workTree: root });
+    const lines = [];
+    for (const row of before.split("\n").filter(Boolean)) {
+        const [status, path] = row.split("\t");
+        // The diff reads from the snapshot to now: A was made since, so it's removed.
+        lines.push(`${status === "A" ? "removed" : "restored"} ${join(root, path)}`);
+    }
+    if (u.git) {
+        const now = tryGit(["for-each-ref", "--format=%(refname)", "refs/heads", "refs/tags"], root) ?? "";
+        for (const name of now.split("\n").filter(Boolean)) {
+            if (!(name in u.git.refs)) {
+                git(["update-ref", "-d", name], { cwd: root });
+                lines.push(`removed ${name.replace(/^refs\/(heads|tags)\//, "")}`);
+            }
+        }
+        for (const [name, sha] of Object.entries(u.git.refs)) {
+            if (tryGit(["rev-parse", "-q", "--verify", name], root) !== sha) {
+                git(["update-ref", name, sha], { cwd: root });
+                lines.push(`restored ${name.replace(/^refs\/(heads|tags)\//, "")}`);
+            }
+        }
+        if (u.git.head.startsWith("refs/"))
+            git(["symbolic-ref", "HEAD", u.git.head], { cwd: root });
+        else if (u.git.head)
+            git(["update-ref", "--no-deref", "HEAD", u.git.head], { cwd: root });
+        if (u.git.index)
+            copyFileSync(u.git.index, join(git(["rev-parse", "--absolute-git-dir"], { cwd: root }), "index"));
+    }
+    return lines.length ? lines.join("\n") : `nothing had changed in ${root}`;
+}