backstep 0.0.0-stage → 0.1.1

package/dist/supabase.js

@@ -0,0 +1,245 @@
+// Supabase: its MCP server (and the claude.ai connector) runs SQL through
+// Supabase's API, which gives Backstep nothing to snapshot with. So the person
+// connects the project's database once (`backstep connect supabase`), and from
+// then on Backstep snapshots tables over that connection before each
+// execute_sql or apply_migration, the same way it does for any Postgres.
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import pg from "pg";
+import { homeDir } from "./store.js";
+// The key for a database with no project ref in its URL, like `supabase start`'s local one.
+export const LOCAL = "local";
+const SQL_TOOLS = new Set(["execute_sql", "apply_migration"]);
+function file() {
+    return join(homeDir(), "connections.json");
+}
+function load() {
+    if (!existsSync(file()))
+        return { supabase: {} };
+    const c = JSON.parse(readFileSync(file(), "utf8"));
+    return { ...c, supabase: c.supabase ?? {} };
+}
+function save(c) {
+    mkdirSync(homeDir(), { recursive: true, mode: 0o700 });
+    // Connection strings carry the database password.
+    writeFileSync(file(), JSON.stringify(c, null, 2) + "\n", { mode: 0o600 });
+    chmodSync(file(), 0o600);
+}
+// The project ref is in the host of a direct connection (db.<ref>.supabase.co)
+// and in the user name of a pooler one (postgres.<ref>@…pooler.supabase.com).
+export function projectRef(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    const host = u.hostname.match(/^db\.([a-z0-9]{20})\.supabase\.co$/);
+    if (host)
+        return host[1];
+    const user = decodeURIComponent(u.username).match(/^[^.]+\.([a-z0-9]{20})$/);
+    if (user && u.hostname.endsWith(".supabase.com"))
+        return user[1];
+    return null;
+}
+// Checks the connection works before keeping it. Returns the ref it's saved under.
+export async function connectSupabase(url, ref) {
+    if (!/^postgres(ql)?:\/\//.test(url)) {
+        throw new Error("that isn't a Postgres connection string. In Supabase: Connect (top of the project page) → Direct, or Session pooler → copy the URI");
+    }
+    if (url.includes("[YOUR-PASSWORD]"))
+        throw new Error("put your database password in place of [YOUR-PASSWORD] first");
+    const key = ref ?? projectRef(url) ?? LOCAL;
+    const client = new pg.Client({ connectionString: url, connectionTimeoutMillis: 10_000 });
+    try {
+        await client.connect();
+        await client.query("SELECT 1");
+    }
+    catch (err) {
+        throw new Error(`couldn't connect to that database: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    finally {
+        await client.end().catch(() => { });
+    }
+    const c = load();
+    c.supabase[key] = url;
+    if (c.expires)
+        delete c.expires[key];
+    save(c);
+    return key;
+}
+export function disconnectSupabase(ref) {
+    const c = load();
+    if (!(ref in c.supabase))
+        return false;
+    delete c.supabase[ref];
+    if (c.expires)
+        delete c.expires[ref];
+    save(c);
+    return true;
+}
+export function supabaseProjects() {
+    return Object.keys(load().supabase);
+}
+// The database for a call. Hosted calls name their project, which has to match;
+// a call that names none (a local server) uses the only database connected.
+export function supabaseDb(ref) {
+    const all = load().supabase;
+    if (ref)
+        return all[ref] ?? null;
+    const urls = Object.values(all);
+    return all[LOCAL] ?? (urls.length === 1 ? urls[0] : null);
+}
+export function isSupabase(server, command = "") {
+    return /supabase/i.test(server) || /supabase/i.test(command);
+}
+export function isSupabaseSql(server, tool, command = "") {
+    return isSupabase(server, command) && SQL_TOOLS.has(tool);
+}
+// A local server started with --project-ref doesn't take project_id on each call.
+export function refFromArgs(callArgs, serverArgs = []) {
+    if (typeof callArgs.project_id === "string")
+        return callArgs.project_id;
+    for (let i = 0; i < serverArgs.length; i++) {
+        const m = serverArgs[i].match(/^--project-ref(?:=(.+))?$/);
+        if (m)
+            return m[1] ?? serverArgs[i + 1];
+    }
+    return undefined;
+}
+// Supabase runs the SQL itself, so a DROP is rewritten rather than run here.
+// apply_migration also records the migration, which undo takes back too.
+export function supabasePlanOptions(tool) {
+    return { rewrite: true, alsoSnapshot: tool === "apply_migration" ? ["supabase_migrations.schema_migrations"] : [] };
+}
+export const CONNECT_HINT = "connect the database to undo Supabase changes: run `backstep connect supabase`";
+// With an access token, a project connects in one step: Supabase hands out a
+// temporary database login (the one its own CLI uses), and Backstep makes a
+// new one whenever the last runs out. The token comes from `backstep connect
+// supabase --token`, SUPABASE_ACCESS_TOKEN, or `supabase login`.
+const API = process.env.BACKSTEP_SUPABASE_API ?? "https://api.supabase.com";
+// Renewed this long before it runs out, so a snapshot never starts on a login about to expire.
+const MARGIN_MS = 5 * 60 * 1000;
+// The session pooler's port; the API names the transaction pooler's, which can't hold a snapshot's transaction.
+const POOLER_PORT = process.env.BACKSTEP_SUPABASE_POOLER_PORT ?? "5432";
+// `interactive` may read the macOS keychain, where `supabase login` keeps its
+// token, which can ask the person for permission: never as a session starts.
+export function supabaseToken(interactive = false) {
+    const saved = load().token ?? process.env.SUPABASE_ACCESS_TOKEN;
+    if (saved)
+        return saved;
+    try {
+        const t = readFileSync(join(homedir(), ".supabase", "access-token"), "utf8").trim();
+        if (t)
+            return t;
+    }
+    catch {
+        // not logged in through the file
+    }
+    if (!interactive || process.platform !== "darwin")
+        return null;
+    const r = spawnSync("security", ["find-generic-password", "-s", "Supabase CLI", "-w"], { encoding: "utf8" });
+    const v = r.status === 0 ? r.stdout.trim() : "";
+    if (!v)
+        return null;
+    return v.startsWith("go-keyring-base64:") ? Buffer.from(v.slice(18), "base64").toString("utf8") : v;
+}
+async function api(token, method, path, body) {
+    const r = await fetch(`${API}${path}`, {
+        method,
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: AbortSignal.timeout(20_000),
+    });
+    if (!r.ok)
+        throw new Error(`Supabase said ${r.status}${r.status === 401 ? ": the access token isn't valid" : ""}`);
+    return (await r.json());
+}
+export const hasSavedToken = () => Boolean(load().token);
+export function dismissSupabase(dir) {
+    const c = load();
+    c.dismissed = [...new Set([...(c.dismissed ?? []), dir])];
+    save(c);
+}
+export const supabaseDismissed = (dir) => (load().dismissed ?? []).includes(dir);
+// Checks the token works before keeping it.
+export async function saveSupabaseToken(token) {
+    const projects = await api(token, "GET", "/v1/projects");
+    const c = load();
+    c.token = token;
+    save(c);
+    return projects.map((p) => p.ref ?? p.id ?? "").filter(Boolean);
+}
+async function tryUrl(url) {
+    const client = new pg.Client({ connectionString: url, connectionTimeoutMillis: 10_000 });
+    try {
+        await client.connect();
+        await client.query("SELECT 1");
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        await client.end().catch(() => { });
+    }
+}
+// A new temporary login for the project's database: direct where the network
+// reaches it, else through Supabase's session pooler.
+export async function mintSupabase(ref, token) {
+    const login = await api(token, "POST", `/v1/projects/${ref}/cli/login-role`, { read_only: false });
+    const pw = encodeURIComponent(login.password);
+    let url = `postgresql://${encodeURIComponent(login.role)}:${pw}@db.${ref}.supabase.co:5432/postgres`;
+    if (!(await tryUrl(url))) {
+        const poolers = await api(token, "GET", `/v1/projects/${ref}/config/database/pooler`);
+        const p = poolers.find((x) => x.database_type !== "READ_REPLICA" && x.db_host);
+        if (!p)
+            throw new Error(`couldn't reach project ${ref}'s database`);
+        url = `postgresql://${encodeURIComponent(`${login.role}.${ref}`)}:${pw}@${p.db_host}:${POOLER_PORT}/${p.db_name ?? "postgres"}`;
+        if (!(await tryUrl(url)))
+            throw new Error(`couldn't reach project ${ref}'s database`);
+    }
+    const c = load();
+    c.supabase[ref] = url;
+    c.expires = { ...c.expires, [ref]: Date.now() + login.ttl_seconds * 1000 };
+    save(c);
+    return url;
+}
+// The database for a call, renewed with the access token when Backstep made
+// it and it has run out. A project is only ever connected when the person says so.
+export async function supabaseUrl(ref) {
+    const saved = supabaseDb(ref);
+    const key = ref ?? (saved ? Object.entries(load().supabase).find(([, u]) => u === saved)?.[0] : undefined);
+    if (!key || key === LOCAL)
+        return saved;
+    const expires = load().expires?.[key];
+    if (saved === null || expires === undefined || expires - MARGIN_MS >= Date.now())
+        return saved;
+    const token = supabaseToken();
+    if (!token)
+        return saved;
+    try {
+        return await mintSupabase(key, token);
+    }
+    catch {
+        return saved;
+    }
+}
+// A saved database URL, renewed if Backstep made it and it has run out.
+export async function freshUrl(url) {
+    const ref = projectRef(url);
+    return ref && load().expires?.[ref] !== undefined ? ((await supabaseUrl(ref)) ?? url) : url;
+}
+// The same database whatever login reaches it: for telling two changes to it apart.
+export function dbKey(url) {
+    try {
+        const u = new URL(url);
+        return `${projectRef(url) ?? u.host}${u.pathname}`;
+    }
+    catch {
+        return url;
+    }
+}

package/dist/telemetry.js

@@ -0,0 +1,77 @@
+// An anonymous count of installs and of installs still in use, so we know how
+// many people use Backstep. Each event carries a random id made on this
+// machine, the Backstep version, the OS and the Node version. Never paths,
+// commands, server names or anything from the journal.
+//
+// Off with BACKSTEP_TELEMETRY=0 or DO_NOT_TRACK=1.
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homeDir } from "./store.js";
+// PostHog's project key only lets events be sent, never read, so it's safe to ship.
+const POSTHOG_KEY = "phc_kkZCQxYJhCSZwqNiYYKW8Yz4x3MwpKCiDX7SBQ29S7w7";
+const POSTHOG_URL = "https://us.i.posthog.com/i/v0/e/";
+const DAY_MS = 24 * 60 * 60 * 1000;
+export function telemetryOn() {
+    const off = (v) => v !== undefined && /^(0|false|off|no)$/i.test(v);
+    const on = (v) => v !== undefined && v !== "" && !off(v);
+    if (off(process.env.BACKSTEP_TELEMETRY) || on(process.env.DO_NOT_TRACK))
+        return false;
+    return Boolean(process.env.BACKSTEP_TELEMETRY_URL || POSTHOG_KEY);
+}
+function installId() {
+    const file = join(homeDir(), "install-id");
+    if (existsSync(file))
+        return readFileSync(file, "utf8").trim();
+    const id = randomUUID();
+    mkdirSync(homeDir(), { recursive: true });
+    writeFileSync(file, id + "\n", { mode: 0o600 });
+    return id;
+}
+function version() {
+    const pkg = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    return JSON.parse(readFileSync(pkg, "utf8")).version;
+}
+// Never throws and never waits long: a count is not worth slowing anyone down.
+async function send(event) {
+    if (!telemetryOn())
+        return;
+    try {
+        await fetch(process.env.BACKSTEP_TELEMETRY_URL ?? POSTHOG_URL, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                api_key: POSTHOG_KEY,
+                event,
+                distinct_id: installId(),
+                properties: {
+                    version: version(),
+                    os: process.platform,
+                    arch: process.arch,
+                    node: process.versions.node.split(".")[0],
+                    // No profile and no location: just the count.
+                    $process_person_profile: false,
+                    $geoip_disable: true,
+                },
+            }),
+            signal: AbortSignal.timeout(3000),
+        });
+    }
+    catch {
+        // Offline, blocked, or slow: skip it.
+    }
+}
+export const sendInstall = () => send("install");
+// At most once a day, as Claude Code starts with Backstep's mod.
+export async function sendActive() {
+    if (!telemetryOn())
+        return;
+    const stamp = join(homeDir(), "last-active-ping");
+    const last = existsSync(stamp) ? Number(readFileSync(stamp, "utf8")) : 0;
+    if (Date.now() - last < DAY_MS)
+        return;
+    mkdirSync(homeDir(), { recursive: true });
+    writeFileSync(stamp, String(Date.now()));
+    await send("active");
+}

package/dist/ui/index.html

@@ -0,0 +1,246 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Backstep</title>
+<style>
+  :root {
+    --bg: #f6f4ef;
+    --panel: #fffdf8;
+    --ink: #1d1b16;
+    --muted: #6f6a5f;
+    --line: #e4dfd3;
+    --soft: #efebe1;
+    --undo: #1f6f4a;
+    --undo-bg: #e3f1e8;
+    --hold: #a35a00;
+    --hold-bg: #fbeedb;
+    --bad: #a3302a;
+    --bad-bg: #f8e3e1;
+    --mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+    --sans: ui-sans-serif, -apple-system, "Segoe UI", system-ui, sans-serif;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #15140f;
+      --panel: #1d1c16;
+      --ink: #ece7da;
+      --muted: #9a9384;
+      --line: #2f2d24;
+      --soft: #26241d;
+      --undo: #6fcf9a;
+      --undo-bg: #1b2e23;
+      --hold: #f0a845;
+      --hold-bg: #33260f;
+      --bad: #f08a80;
+      --bad-bg: #3a1c19;
+    }
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--ink); font: 14px/1.45 var(--sans); }
+  header {
+    display: flex; align-items: baseline; gap: 14px; padding: 18px 28px;
+    border-bottom: 1px solid var(--line);
+  }
+  header h1 { margin: 0; font-size: 18px; letter-spacing: -0.01em; }
+  header h1 span { color: var(--undo); }
+  header p { margin: 0; color: var(--muted); }
+  header label { margin-left: auto; color: var(--muted); display: flex; gap: 6px; align-items: center; cursor: pointer; }
+  main { display: grid; grid-template-columns: 280px 1fr; min-height: calc(100vh - 60px); }
+  aside { border-right: 1px solid var(--line); padding: 18px 14px; }
+  aside h2, section h2 { font-size: 11px; text-transform: uppercase; letter-spacing: .08em; color: var(--muted); margin: 0 10px 10px; font-weight: 600; }
+  .run {
+    display: block; width: 100%; text-align: left; border: 0; background: none; color: inherit;
+    padding: 9px 10px; border-radius: 8px; cursor: pointer; font: inherit;
+  }
+  .run:hover { background: var(--soft); }
+  .run.sel { background: var(--panel); box-shadow: inset 0 0 0 1px var(--line); }
+  .run b { display: block; font-weight: 600; }
+  .run small { color: var(--muted); }
+  .live { display: inline-block; width: 7px; height: 7px; border-radius: 50%; background: var(--undo); margin-right: 6px; vertical-align: 1px; }
+  section { padding: 22px 28px 60px; max-width: 980px; }
+  .bar { display: flex; align-items: center; gap: 12px; margin-bottom: 18px; }
+  .bar h3 { margin: 0; font-size: 20px; letter-spacing: -0.01em; }
+  .bar .cmd { font: 12px var(--mono); color: var(--muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .bar .grow { flex: 1; min-width: 0; }
+  button.act {
+    font: 600 13px var(--sans); border-radius: 7px; padding: 6px 12px; cursor: pointer;
+    border: 1px solid var(--line); background: var(--panel); color: var(--ink); white-space: nowrap;
+  }
+  button.act:hover { border-color: var(--muted); }
+  button.act.undo { color: var(--undo); }
+  button.act.primary { background: var(--ink); color: var(--bg); border-color: var(--ink); }
+  button.act:disabled { opacity: .45; cursor: default; }
+  ol { list-style: none; margin: 0; padding: 0; border-left: 2px solid var(--line); margin-left: 7px; }
+  li.a { position: relative; padding: 10px 0 10px 22px; }
+  li.a::before {
+    content: ""; position: absolute; left: -7px; top: 16px; width: 12px; height: 12px; border-radius: 50%;
+    background: var(--panel); border: 2px solid var(--line);
+  }
+  li.a.reversible::before { border-color: var(--undo); }
+  li.a.irreversible::before { border-color: var(--hold); }
+  li.a.undone { opacity: .55; }
+  li.a.undone .tool { text-decoration: line-through; }
+  .row { display: flex; gap: 10px; align-items: center; }
+  .tool { font: 600 13px var(--mono); }
+  .chip { font-size: 11px; font-weight: 600; padding: 2px 8px; border-radius: 99px; background: var(--soft); color: var(--muted); }
+  .chip.reversible { background: var(--undo-bg); color: var(--undo); }
+  .chip.irreversible, .chip.held { background: var(--hold-bg); color: var(--hold); }
+  .chip.error, .chip.undo_failed, .chip.cancelled { background: var(--bad-bg); color: var(--bad); }
+  .time { color: var(--muted); font-size: 12px; margin-left: auto; }
+  .args { font: 12px/1.5 var(--mono); color: var(--muted); margin-top: 4px; white-space: pre-wrap; word-break: break-all; max-height: 4.5em; overflow: hidden; }
+  .note { font-size: 12px; color: var(--muted); margin-top: 3px; }
+  .note.bad { color: var(--bad); }
+  .confirm {
+    margin-top: 10px; background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: 12px 14px;
+  }
+  .confirm ul { margin: 6px 0 10px; padding-left: 18px; font: 12px var(--mono); }
+  .empty { color: var(--muted); padding: 60px 0; text-align: center; }
+  .empty code { font: 12px var(--mono); background: var(--soft); padding: 2px 6px; border-radius: 5px; }
+  .toast {
+    position: fixed; bottom: 20px; left: 50%; transform: translateX(-50%); background: var(--ink); color: var(--bg);
+    padding: 10px 16px; border-radius: 9px; font-size: 13px; max-width: 90vw; white-space: pre-wrap;
+  }
+  @media (max-width: 760px) {
+    main { grid-template-columns: 1fr; }
+    aside { border-right: 0; border-bottom: 1px solid var(--line); }
+    header, section { padding-left: 16px; padding-right: 16px; }
+  }
+</style>
+</head>
+<body>
+<header>
+  <h1>Back<span>step</span></h1>
+  <p>Every action your agents take, and the way back.</p>
+  <label><input type="checkbox" id="reads"> Show reads</label>
+</header>
+<main>
+  <aside><h2>Runs</h2><div id="runs"></div></aside>
+  <section id="main"></section>
+</main>
+<div id="toast" class="toast" hidden></div>
+<script>
+const state = { runs: [], actions: [], sel: null, confirm: null, busy: false };
+const $ = (s) => document.querySelector(s);
+const esc = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+const ago = (t) => {
+  const s = Math.round((Date.now() - t) / 1000);
+  if (s < 60) return s + "s ago";
+  if (s < 3600) return Math.round(s / 60) + "m ago";
+  if (s < 86400) return Math.round(s / 3600) + "h ago";
+  return new Date(t).toLocaleDateString();
+};
+try { $("#reads").checked = localStorage.getItem("tb-reads") === "1"; } catch {}
+$("#reads").onchange = (e) => { try { localStorage.setItem("tb-reads", e.target.checked ? "1" : "0"); } catch {} render(); };
+
+function toast(msg) {
+  const t = $("#toast"); t.textContent = msg; t.hidden = false;
+  clearTimeout(toast.t); toast.t = setTimeout(() => (t.hidden = true), 4500);
+}
+
+async function post(path) {
+  const r = await fetch(path, { method: "POST", headers: { "x-backstep": "1" } });
+  const body = await r.json();
+  if (!r.ok) throw new Error(body.error || "request failed");
+  return body;
+}
+
+async function load() {
+  try {
+    const r = await fetch("/api/feed");
+    const data = await r.json();
+    state.runs = data.runs; state.actions = data.actions;
+    if (!state.sel || !state.runs.some((x) => x.id === state.sel)) state.sel = state.runs[0]?.id ?? null;
+    if (!state.busy) render();
+  } catch {}
+}
+
+const KIND_LABEL = { read: "read", reversible: "undoable", irreversible: "can't undo", write: "no undo" };
+const STATUS_LABEL = { held: "held", cancelled: "cancelled", undone: "undone", undo_failed: "undo failed", error: "error", running: "running", undo_requested: "undoing…", undoing: "undoing…" };
+
+function actionHtml(a) {
+  const argText = Object.entries(a.args).map(([k, v]) => `${k}: ${typeof v === "string" ? v : JSON.stringify(v)}`).join("\n");
+  const status = STATUS_LABEL[a.status];
+  const confirming = state.confirm && state.confirm.id === a.id;
+  return `<li class="a ${a.kind} ${a.status}">
+    <div class="row">
+      <span class="tool">${esc(a.tool)}</span>
+      <span class="chip ${a.kind}">${KIND_LABEL[a.kind]}</span>
+      ${status ? `<span class="chip ${a.status}">${status}</span>` : ""}
+      <span class="time">${ago(a.created_at)}</span>
+      ${a.undoable ? `<button class="act undo" data-undo="${a.id}">Undo</button>` : ""}
+    </div>
+    ${argText ? `<div class="args">${esc(argText)}</div>` : ""}
+    ${a.reason && a.kind !== "read" ? `<div class="note">${esc(a.reason)}</div>` : ""}
+    ${a.error ? `<div class="note bad">${esc(a.error)}</div>` : ""}
+    ${confirming ? confirmHtml() : ""}
+  </li>`;
+}
+
+function confirmHtml() {
+  const c = state.confirm;
+  const extra = c.chain.filter((x) => x.id !== c.id);
+  return `<div class="confirm">
+    ${extra.length
+      ? `Later actions changed the same things, so they'll be undone first:<ul>${extra.map((x) => `<li>${esc(x.tool)}</li>`).join("")}</ul>`
+      : `<div style="margin-bottom:10px">Put everything this action touched back the way it was?</div>`}
+    <button class="act primary" data-go="${c.id}">Undo ${extra.length ? extra.length + 1 + " actions" : "it"}</button>
+    <button class="act" data-nevermind>Keep</button>
+  </div>`;
+}
+
+function render() {
+  $("#runs").innerHTML = state.runs.length
+    ? state.runs.map((r) => `<button class="run ${r.id === state.sel ? "sel" : ""}" data-run="${r.id}">
+        <b>${r.ended_at ? "" : '<span class="live"></span>'}${esc(r.server)}</b>
+        <small>${ago(r.started_at)} · ${r.actions} actions · ${r.undoable} undoable</small>
+      </button>`).join("")
+    : `<div class="note" style="padding:0 10px">No runs yet.</div>`;
+
+  const run = state.runs.find((r) => r.id === state.sel);
+  const main = $("#main");
+  if (!run) {
+    main.innerHTML = `<div class="empty">Wrap an MCP server to start recording.<br><br>
+      <code>backstep wrap --name files -- npx -y @modelcontextprotocol/server-filesystem .</code></div>`;
+    return;
+  }
+  const all = state.actions.filter((a) => a.run_id === run.id);
+  const shown = all.filter((a) => $("#reads").checked || a.kind !== "read");
+  main.innerHTML = `
+    <div class="bar">
+      <div class="grow"><h3>${esc(run.server)}</h3><div class="cmd">${esc(run.command)}</div></div>
+      <button class="act undo" data-undorun="${run.id}" ${run.undoable ? "" : "disabled"}>Undo entire run</button>
+    </div>
+    ${shown.length ? `<ol>${shown.map(actionHtml).join("")}</ol>` : `<div class="empty">Nothing recorded yet${$("#reads").checked ? "" : " (reads hidden)"}.</div>`}`;
+}
+
+document.addEventListener("click", async (e) => {
+  const el = e.target.closest("button");
+  if (!el) return;
+  const d = el.dataset;
+  try {
+    if (d.run) { state.sel = d.run; state.confirm = null; render(); }
+    else if (d.undo) {
+      const r = await fetch(`/api/actions/${d.undo}/chain`).then((x) => x.json());
+      state.confirm = { id: d.undo, chain: r.chain }; state.busy = true; render();
+    }
+    else if (d.nevermind !== undefined) { state.confirm = null; state.busy = false; render(); }
+    else if (d.go) { report(await post(`/api/actions/${d.go}/undo`)); state.confirm = null; state.busy = false; }
+    else if (d.undorun) { report(await post(`/api/runs/${d.undorun}/undo`)); }
+  } catch (err) { toast(err.message); state.busy = false; }
+  load();
+});
+
+function report(body) {
+  const o = body.outcomes || [];
+  if (!o.length) return toast("Nothing to undo.");
+  const failed = o.find((x) => !x.ok);
+  toast(failed ? `Undo stopped at ${failed.tool}: ${failed.detail}` : `Undid ${o.length} action${o.length > 1 ? "s" : ""}.\n${o.map((x) => x.detail).join("\n")}`);
+}
+
+load();
+setInterval(load, 1000);
+</script>
+</body>
+</html>

package/dist/ui/server.js

@@ -0,0 +1,70 @@
+// Local dashboard: a timeline of agent actions with undo.
+import { createServer } from "node:http";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { Store } from "../store.js";
+import { undoAction, undoChain, undoRun } from "../undo.js";
+const page = readFileSync(fileURLToPath(new URL("./index.html", import.meta.url)), "utf8");
+function json(res, status, body) {
+    res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
+    res.end(JSON.stringify(body));
+}
+// The journal can hold database URLs and every undo is destructive, so only
+// accept same-machine requests: a Host check stops DNS rebinding, and the
+// custom header on writes forces a CORS preflight that we never approve.
+function trusted(req, port) {
+    const host = req.headers.host ?? "";
+    return host === `127.0.0.1:${port}` || host === `localhost:${port}`;
+}
+function publicAction(a) {
+    const { undo, ...rest } = a;
+    return { ...rest, args: JSON.parse(a.args), undoable: undo !== null && (a.status === "ok" || a.status === "error") };
+}
+export function startUi(port) {
+    const store = new Store();
+    const server = createServer(async (req, res) => {
+        try {
+            if (!trusted(req, port))
+                return json(res, 403, { error: "forbidden" });
+            const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+            const parts = url.pathname.split("/").filter(Boolean);
+            if (req.method === "GET" && url.pathname === "/") {
+                res.writeHead(200, {
+                    "content-type": "text/html; charset=utf-8",
+                    "content-security-policy": "default-src 'self'; style-src 'unsafe-inline'; script-src 'unsafe-inline'",
+                });
+                return res.end(page);
+            }
+            if (req.method === "GET" && url.pathname === "/api/feed") {
+                const runs = store.listRuns(30).map(({ pg_url, ...r }) => ({ ...r, has_db: pg_url !== null }));
+                return json(res, 200, { runs, actions: store.feed(300).map(publicAction) });
+            }
+            if (req.method === "GET" && parts[0] === "api" && parts[1] === "actions" && parts[3] === "chain") {
+                const a = store.getAction(parts[2]);
+                if (!a)
+                    return json(res, 404, { error: "not found" });
+                return json(res, 200, { chain: undoChain(store, a).map((c) => ({ id: c.id, tool: c.tool })) });
+            }
+            if (req.method === "POST") {
+                if (req.headers["x-backstep"] !== "1")
+                    return json(res, 403, { error: "missing header" });
+                const [, kind, id, verb] = parts;
+                if (kind === "actions" && verb === "undo")
+                    return json(res, 200, { outcomes: await undoAction(store, id) });
+                if (kind === "runs" && verb === "undo")
+                    return json(res, 200, { outcomes: await undoRun(store, id) });
+            }
+            json(res, 404, { error: "not found" });
+        }
+        catch (err) {
+            json(res, 400, { error: err instanceof Error ? err.message : String(err) });
+        }
+    });
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, "127.0.0.1", () => {
+            console.log(`Backstep dashboard: http://localhost:${port}`);
+            resolve();
+        });
+    });
+}