backstep 0.0.0-stage → 0.1.1

package/mod/hooks/register.tsx

@@ -0,0 +1,529 @@
+// Backstep for Claude Code: snapshot every file Claude is about to change,
+// and the whole project before each shell command, and rewind its whole last
+// turn with one key (ctrl+z) and a short animation above the prompt. Database
+// and tool changes made through servers wrapped by `backstep wrap`, and
+// Supabase changes over a connected database, rewind with it, by the turn's
+// time window.
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface, Register } from 'claude-code'
+
+import type { Rewind, RewindItem, Turn } from '../types'
+
+const turns = atom({ plugin: 'backstep', key: 'turns' } as const, [] as Turn[])
+const rewind = atom({ plugin: 'backstep', key: 'rewind' } as const, null as Rewind | null)
+const note = atom({ plugin: 'backstep', key: 'note' } as const, null as string | null)
+
+// The engine has no keybinding actions of its own for plugins yet, so the undo
+// button borrows one that only the diff panel handles; ~/.claude/keybindings.json
+// binds ctrl+z to it everywhere else.
+const UNDO_ACTION = 'app:cycleDiffBase'
+const EDIT_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit'])
+const KEEP_TURNS = 30
+const BAR = 26
+
+const hasWork = (t: Turn) => !t.undone && t.edits + t.mcp + (t.shell ?? 0) > 0
+const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? '' : 's'}`
+
+function summary(t: Turn): string {
+  const parts: string[] = []
+  if (t.edits) parts.push(`${plural(t.edits, 'edit')} to ${plural(t.files.length, 'file')}`)
+  if (t.shell) parts.push(plural(t.shell, 'shell command'))
+  if (t.mcp) parts.push(plural(t.mcp, 'tool action'))
+  return parts.join(', ')
+}
+
+// A rewind bar: a run of arrows sliding right to left, like tape winding back.
+function bar(frame: number): string {
+  const head = BAR - 1 - (frame % (BAR + 4))
+  return Array.from({ length: BAR }, (_, i) => (i >= head && i < head + 4 ? '◂' : '─')).join('')
+}
+
+type Pushed = { remote: string; branch: string; before: string | null; after: string; commits: number; host: string }
+type Outcome = {
+  id: string
+  tool: string
+  ok: boolean
+  detail: string
+  run?: { server: string; tool: string; args: Record<string, unknown> }
+  pushed?: { root: string; pushes: Pushed[] }
+}
+const PUSH = /\bgit\b[^;&|]*\bpush\b/
+
+const PUSH_ASK = { yes: 'Push the undo', no: 'Leave it as it is' }
+
+// Undo rewound the code here; this asks before taking it back on GitHub too,
+// as a new commit that undoes Claude's (never a force push).
+async function offerPushUndo($: EngineInterface, outcomes: Outcome[]) {
+  for (const o of outcomes) {
+    if (!o.ok || !o.pushed) continue
+    for (const p of o.pushed.pushes) {
+      const what =
+        p.before === null
+          ? `Claude pushed a new branch, ${p.branch}, to ${p.host}. Delete it there too?`
+          : `Claude pushed ${p.commits === 1 ? '1 commit' : `${p.commits} commits`} to ${p.branch} on ${p.host}. Undo ${p.commits === 1 ? 'it' : 'them'} there too?`
+      const answer = await $.ui.ask(what, { header: 'Backstep', options: [p.before === null ? 'Delete the branch' : PUSH_ASK.yes, PUSH_ASK.no] }).catch(() => null)
+      if (!answer || answer === PUSH_ASK.no) continue
+      const ran = await $.process
+        .run(backstep(['revert-push', '--root', o.pushed.root]), { stdin: JSON.stringify(p), timeoutMs: 180_000 })
+        .catch((err: unknown) => ({ exitCode: 1, stdout: '', stderr: err instanceof Error ? err.message : String(err) }))
+      let r: { ok: boolean; detail: string } = { ok: false, detail: (ran.stderr || 'it failed').trim().split('\n').at(-1) ?? 'it failed' }
+      try {
+        r = JSON.parse(ran.stdout) as typeof r
+      } catch {
+        // keep the error above
+      }
+      $.ui.toast(r.ok ? `Backstep ${r.detail}.` : `Backstep ${r.detail}. Nothing was changed on ${p.host}.`)
+      await update($, note, (n) =>
+        n ? `${n}\n${r.ok ? `On ${p.host}: ${r.detail}.` : `${p.host} was left as it was: ${r.detail}.`}` : n,
+      )
+    }
+  }
+}
+
+async function undoLastTurn($: EngineInterface) {
+  if (await read($, rewind)) return
+  const target = (await read($, turns)).findLast(hasWork)
+  if (!target) return
+
+  await update($, rewind, (): Rewind => ({ phase: 'running', frame: 0, shown: 0, items: [], message: '' }))
+  const ticker = $.clock.every(55, () => {
+    void update($, rewind, (r) => (r && r.phase === 'running' ? { ...r, frame: r.frame + 1 } : r))
+  })
+
+  const cwd = await $.session.cwd()
+  const short = (p: string) => (p.startsWith(cwd + '/') ? p.slice(cwd.length + 1) : p)
+  const [ran] = await Promise.all([
+    $.process.run(backstep(['undo', '--since', String(target.startedAt), '--json', '--via-claude-code'])).catch((err: unknown) => ({
+      exitCode: 1,
+      stdout: '',
+      stderr: err instanceof Error ? err.message : String(err),
+    })),
+    // Long enough to read as a rewind, short enough to never feel slow.
+    $.clock.sleep(700),
+  ])
+  ticker.cancel()
+
+  let outcomes: Outcome[] = []
+  try {
+    outcomes = JSON.parse(ran.stdout || '[]') as Outcome[]
+  } catch {
+    outcomes = [{ id: '', tool: 'backstep', ok: false, detail: (ran.stderr || ran.stdout).trim().split('\n')[0] ?? 'failed' }]
+  }
+  if (ran.exitCode !== 0 && outcomes.length === 0) {
+    outcomes = [{ id: '', tool: 'backstep', ok: false, detail: ran.stderr.trim().split('\n').at(-1) ?? 'failed' }]
+  }
+
+  // Opposite calls on servers only Claude Code is connected to run here, newest first.
+  for (const o of outcomes) {
+    if (!o.ok || !o.run) continue
+    const done = await $.mcp.call(o.run.server, o.run.tool, o.run.args).catch((err: unknown) => ({
+      isError: true,
+      content: [{ type: 'text' as const, text: err instanceof Error ? err.message : String(err) }],
+    }))
+    if (done.isError) {
+      const why = done.content.map((c) => (c.type === 'text' ? c.text : '')).join(' ').trim().split('\n')[0] || 'failed'
+      o.ok = false
+      o.detail = `${o.run.tool} failed: ${why}`
+      await $.process.run(backstep(['settle', o.id, '--failed', why])).catch(() => null)
+      break
+    }
+    o.detail = `ran ${o.run.tool}`
+    await $.process.run(backstep(['settle', o.id])).catch(() => null)
+  }
+  // Stop the list at the first failure, as the CLI does.
+  const cut = outcomes.findIndex((o) => !o.ok)
+  if (cut !== -1) outcomes = outcomes.slice(0, cut + 1)
+
+  const items: RewindItem[] = outcomes.map((o) => {
+    const first = o.detail.split('\n')[0] ?? ''
+    const what = first.replace(/^(restored|removed) (.*)$/, (_, verb: string, p: string) => `${short(p)} ${verb}`)
+    return { label: o.ok ? what || o.tool : `${o.tool}: ${first}`, ok: o.ok }
+  })
+  const done = items.filter((i) => i.ok).length
+  const failed = items.some((i) => !i.ok)
+  // A push counted as lost when it ran, but undo can now offer to take it back there.
+  const offered = outcomes.filter((o) => o.ok && o.pushed).length
+  const lost = Math.max(0, (target.lost ?? 0) - offered)
+  const shell = lost ? ` ${plural(lost, 'action')} that reached outside couldn't be undone.` : ''
+
+  await update($, rewind, (): Rewind => ({
+    phase: failed ? 'failed' : items.length ? 'done' : 'empty',
+    frame: 0,
+    shown: 0,
+    items,
+    message: failed
+      ? `Stopped after ${plural(done, 'change')}: the next one couldn't be undone.`
+      : items.length
+        ? `Rewound ${plural(done, 'change')} from the last turn.${shell}`
+        : `Nothing in the last turn could be undone.${shell}`,
+  }))
+  await bump($, target.id, (t) => ({ ...t, undone: !failed }))
+
+  if (done) {
+    const list = items.filter((i) => i.ok).map((i) => `- ${i.label}`).join('\n')
+    await update($, note, () =>
+      `[Backstep] The user pressed undo (ctrl+z) on your previous turn. These changes were reverted:\n${list}\n` +
+        (lost ? `${plural(lost, 'action')} from that turn couldn't be undone (they reached outside this machine with no way back, or the project was too big to snapshot).\n` : '') +
+        `Treat them as not having happened, re-read files before editing them, and don't redo them unless asked.`,
+    )
+  }
+
+  // Asked once the band shows what came back.
+  void offerPushUndo($, outcomes)
+
+  // Reveal the restored items one by one, then fold the band away.
+  const reveal = $.clock.every(90, () => {
+    void update($, rewind, (r) => (r && r.shown < r.items.length ? { ...r, shown: r.shown + 1 } : r))
+  })
+  $.clock.after(failed ? 9000 : 4200, () => {
+    reveal.cancel()
+    void update($, rewind, () => null)
+  })
+}
+
+type Next = (e: Record<string, unknown>) => Promise<{ deny?: string; isError?: true; result?: unknown; text?: string }>
+type WatchPlan = {
+  kind: 'wrapped' | 'read' | 'irreversible' | 'write' | 'reversible'
+  id?: string
+  reason?: string
+  args?: Record<string, unknown>
+  hint?: 'supabase'
+}
+
+// Said once a session: a Supabase change went through that could have been undoable.
+let hinted = false
+
+function hint($: EngineInterface, plan: WatchPlan | null) {
+  if (plan?.hint !== 'supabase' || hinted) return
+  hinted = true
+  $.ui.toast("Backstep can't undo Supabase changes until it's connected to the database. Ask Claude to connect Backstep to Supabase.")
+}
+
+// The keys a tool.call carries that aren't the tool's own arguments.
+const RESERVED = new Set(['tool', 'tool_use_id', 'consent', 'agentId', 'requestMeta'])
+
+// An MCP call. Servers behind Backstep's proxy record themselves; for the rest
+// (claude.ai connectors, servers Claude Code signs in to) Backstep records the
+// call here and keeps an opposite call when an undo rule matches, which undo
+// runs through Claude Code's own connection. Supabase SQL is snapshotted
+// first, and a DROP comes back rewritten as a move to Backstep's trash.
+async function watchMcp($: EngineInterface, e: Record<string, unknown>, next: Next) {
+  const tool = String(e.tool)
+  const t = await current($)
+  const args = Object.fromEntries(Object.entries(e).filter(([k]) => !RESERVED.has(k)))
+  const cwd = await $.session.cwd()
+  const sid = await $.session.id()
+  const started = await $.process
+    .run(backstep(['watch-start', '--session', sid, '--cwd', cwd, '--', tool]), { stdin: JSON.stringify(args) })
+    .catch(() => null)
+  let plan: WatchPlan | null = null
+  try {
+    plan = JSON.parse(started?.stdout || 'null') as WatchPlan | null
+  } catch {
+    plan = null
+  }
+  hint($, plan)
+  // Behind Backstep, or Backstep couldn't be reached: count it as before.
+  if (!plan || plan.kind === 'wrapped' || !plan.id) {
+    if (plan?.kind !== 'read') await bump($, t.id, (x) => ({ ...x, mcp: x.mcp + 1 }))
+    return next(e)
+  }
+  const r = await next(plan.args ? { ...e, ...plan.args } : e)
+  if (r.deny) {
+    await $.process.run(backstep(['cancel', plan.id])).catch(() => null)
+    return r
+  }
+  const ended = await $.process
+    .run(backstep(['watch-end', plan.id]), { stdin: JSON.stringify({ isError: r.isError ?? false, result: r.result, text: r.text }) })
+    .catch(() => null)
+  let undoable = false
+  try {
+    undoable = (JSON.parse(ended?.stdout || '{}') as { undoable?: boolean }).undoable === true
+  } catch {
+    undoable = false
+  }
+  if (!r.isError) await bump($, t.id, (x) => (undoable ? { ...x, mcp: x.mcp + 1 } : { ...x, lost: (x.lost ?? 0) + 1 }))
+  return r
+}
+
+type ShellPlan = { kind: 'read' | 'write' | 'outbound'; reason?: string; id?: string; undoable: boolean }
+
+// Set from the plugin's options each time the module registers.
+let cli = 'backstep'
+
+function backstep(args: string[]): string[] {
+  return cli === 'backstep' ? ['backstep', ...args] : ['node', '--disable-warning=ExperimentalWarning', cli, ...args]
+}
+
+function newTurn(startedAt: number): Turn {
+  return { id: `t${startedAt}`, startedAt, edits: 0, files: [], mcp: 0, shell: 0, lost: 0, undone: false }
+}
+
+// The turn tool calls belong to; one opens if none is (a call before any prompt).
+async function current($: EngineInterface): Promise<Turn> {
+  const last = (await read($, turns)).at(-1)
+  if (last && !last.undone) return last
+  const t = newTurn(await $.clock.now())
+  await update($, turns, (l) => [...(l ?? []), t].slice(-KEEP_TURNS))
+  return t
+}
+
+async function bump($: EngineInterface, id: string, fn: (t: Turn) => Turn): Promise<void> {
+  await update($, turns, (l) => (l ?? []).map((t) => (t.id === id ? fn(t) : t)))
+}
+
+// MCP servers added since setup go behind Backstep too. Claude Code has already
+// started this session's servers, so the change takes effect from the next one.
+async function wrapNewServers($: EngineInterface, cwd: string) {
+  const ran = await $.process.run(backstep(['wrap-servers', '--project', cwd, '--json']), { timeoutMs: 120_000 }).catch(() => null)
+  let changes: { name: string; done: boolean }[] = []
+  try {
+    changes = JSON.parse(ran?.stdout || '[]') as typeof changes
+  } catch {
+    return
+  }
+  const names = changes.filter((c) => c.done).map((c) => c.name)
+  if (names.length === 0) return
+  $.ui.toast(
+    `Backstep: ${names.join(', ')} ${names.length === 1 ? 'is' : 'are'} now behind Backstep, so ${names.length === 1 ? 'its' : 'their'} changes can be undone. Restart Claude Code to start using that.`,
+  )
+}
+
+// As a session starts: connects what the project's own settings allow, then
+// says what Claude reaches that Backstep could undo once connected, so nobody
+// presses ctrl+z expecting it to come back.
+async function checkCoverage($: EngineInterface, cwd: string) {
+  // Supabase is only ever noticed here, never connected: that's the person's
+  // call. Firebase is added once someone is signed in to it.
+  const found = await $.process.run(backstep(['connect', '--dir', cwd, '--json', '--auto']), { timeoutMs: 120_000 }).catch(() => null)
+  try {
+    for (const c of JSON.parse(found?.stdout || '[]') as Connected[]) {
+      if (c.service === 'supabase' && c.state === 'ask') void askSupabase($, cwd)
+      if (c.state === 'added') $.ui.toast('Backstep added Firebase for this project, so Claude can reach it and its changes can be undone. Restart Claude Code to use it.')
+    }
+  } catch {
+    // Backstep couldn't be reached: nothing to say.
+  }
+  const ran = await $.process.run(backstep(['status', '--quick', '--json', '--dir', cwd])).catch(() => null)
+  let items: { name: string; level: string; detail: string }[] = []
+  try {
+    items = (JSON.parse(ran?.stdout || '{}') as { items?: typeof items }).items ?? []
+  } catch {
+    return
+  }
+  // Supabase has its own question above, asked only where a project uses it.
+  const missing = [...new Set(items.filter((i) => i.level === 'connect' && !/supabase/i.test(i.name)).map((i) => i.name))]
+  if (missing.length === 0) return
+  $.ui.toast(`Backstep can't undo Claude's changes to ${missing.join(', ')} yet. They become undoable from the next Claude Code session.`)
+}
+
+const ASK = {
+  connect: 'Connect',
+  later: 'Not now',
+  never: "Don't ask for this project",
+}
+
+// Asked when Claude Code opens a project that uses Supabase and Backstep isn't
+// connected to it; the answer is the only thing that connects it.
+async function askSupabase($: EngineInterface, cwd: string) {
+  const answer = await $.ui
+    .ask("This project uses Supabase, but Backstep isn't connected to it, so Claude's changes to its database can't be undone. Connect it?", {
+      header: 'Backstep',
+      options: [ASK.connect, ASK.later, ASK.never],
+    })
+    .catch(() => null)
+  if (answer === ASK.never) {
+    await $.process.run(backstep(['connect', 'supabase', '--dir', cwd, '--dismiss'])).catch(() => null)
+    return
+  }
+  if (answer !== ASK.connect) return
+  const ran = await $.process.run(backstep(['connect', 'supabase', '--dir', cwd, '--json']), { timeoutMs: 120_000 }).catch(() => null)
+  let s: Connected | undefined
+  try {
+    s = (JSON.parse(ran?.stdout || '[]') as Connected[])[0]
+  } catch {
+    s = undefined
+  }
+  if (s?.state === 'connected' || s?.state === 'covered') {
+    $.ui.toast(`Backstep ${s.detail}. Claude's changes to its database can now be undone.`)
+    return
+  }
+  // Nothing in the project to connect with: a sign-in is needed, and Claude walks the person through it.
+  $.ui.toast('Backstep needs a Supabase sign-in for this. Ask Claude to "connect Backstep to Supabase" and it will walk you through it.')
+}
+
+const CONNECT = 'mcp__backstep__connect'
+
+const CONNECT_TOOL = {
+  name: 'connect',
+  description:
+    "Connect Backstep (the undo for this session's changes) to the services the project uses, so changes Claude makes to them can be undone with ctrl+z. " +
+    'Use it when the user asks to connect Backstep, or to make their database or Firebase undoable. ' +
+    "Supabase: finds the database's connection string in the project's .env files or its local `supabase start` database. " +
+    'When it reports it needs a sign-in, tell the user how to make an access token (it says where), ask them to paste it, then call this again with connection_string. ' +
+    'Never repeat a token or connection string back: they are secrets. ' +
+    "Firebase: adds Firebase's MCP server to the project when Claude can't reach Firebase yet; nothing else is needed.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      service: { type: 'string', enum: ['all', 'supabase', 'firebase'], description: 'what to connect; all when the user names nothing' },
+      connection_string: {
+        type: 'string',
+        description: 'what the user gave to connect Supabase: an access token (sbp_…, connects every project) or a database connection string (postgresql://…)',
+      },
+      project_ref: { type: 'string', description: 'the Supabase project ref to save it under, when the connection string has none' },
+    },
+  },
+}
+
+type Connected = { service: string; state: string; detail: string }
+
+async function connectServices($: EngineInterface, input: { service?: string; connection_string?: string; project_ref?: string }) {
+  const cwd = await $.session.cwd()
+  const service = input.service === 'supabase' || input.service === 'firebase' ? [input.service] : []
+  const ref = input.project_ref ? ['--project', input.project_ref] : []
+  // The connection string goes on stdin, never in an argv other processes can read.
+  const ran = await $.process
+    .run(backstep(['connect', ...service, ...ref, '--dir', cwd, '--json', '--stdin']), { stdin: input.connection_string ?? '', timeoutMs: 180_000 })
+    .catch((err: unknown) => ({ exitCode: 1, stdout: '', stderr: err instanceof Error ? err.message : String(err) }))
+  let out: Connected[] = []
+  try {
+    out = JSON.parse(ran.stdout || '[]') as Connected[]
+  } catch {
+    out = []
+  }
+  if (out.length === 0) return `Backstep couldn't connect: ${(ran.stderr || ran.stdout).trim().split('\n').at(-1) || 'it failed'}`
+  if (out.some((s) => s.state === 'connected' || s.state === 'added')) $.ui.toast('Backstep: connected. Changes Claude makes there can now be undone.')
+  return out.map((s) => `${s.service === 'supabase' ? 'Supabase' : 'Firebase'} (${s.state}): ${s.detail}`).join('\n')
+}
+
+export const register: Register = (on, options) => {
+  cli = String(options.cli ?? 'backstep')
+
+  on('session.start', async ($, e, next) => {
+    await $.tool.register(CONNECT_TOOL)
+    const r = await next(e)
+    // In the background: a session never waits on either.
+    void wrapNewServers($, e.cwd)
+    void checkCoverage($, e.cwd)
+    void $.process.run(backstep(['ping'])).catch(() => null)
+    return r
+  })
+
+  // Each prompt of the person's starts a turn; a pending undo note rides along
+  // as context only the model reads, so Claude knows its work was taken back.
+  on('prompt.submit', async ($, e, next) => {
+    if (e.command || e.isMeta || (e.origin.kind !== 'composer' && e.origin.kind !== 'bridge')) return next(e)
+    const startedAt = await $.clock.now()
+    await update($, turns, (l) => [...(l ?? []), newTurn(startedAt)].slice(-KEEP_TURNS))
+    const pending = await read($, note)
+    if (!pending) return next(e)
+    await update($, note, () => null)
+    return next({ ...e, context: [...(e.context ?? []), pending] })
+  })
+
+  on('tool.call', { tool: CONNECT }, async ($, e) => ({ result: await connectServices($, e as { service?: string; connection_string?: string; project_ref?: string }) }))
+
+  on('tool.call', async ($, e, next) => {
+    const tool = String(e.tool)
+    if (tool === CONNECT) return next(e)
+    if (EDIT_TOOLS.has(tool)) {
+      const input = e as { file_path?: string; notebook_path?: string }
+      const path = input.file_path ?? input.notebook_path
+      if (path) {
+        const t = await current($)
+        const cwd = await $.session.cwd()
+        const sid = await $.session.id()
+        // A failed snapshot never blocks the edit; it just won't be undoable.
+        const snap = await $.process
+          .run(backstep(['snap', '--session', sid, '--tool', tool, '--cwd', cwd, '--', path]))
+          .catch(() => null)
+        if (snap?.exitCode === 0) {
+          await bump($, t.id, (x) => ({ ...x, edits: x.edits + 1, files: x.files.includes(path) ? x.files : [...x.files, path] }))
+        }
+      }
+    } else if (tool === 'Bash') {
+      const command = String((e as { command?: unknown }).command ?? '')
+      const t = await current($)
+      const cwd = await $.session.cwd()
+      const sid = await $.session.id()
+      // Never blocks the command: if Backstep can't be reached it just won't be undoable.
+      const ran = await $.process
+        .run(backstep(['shell', '--session', sid, '--cwd', cwd, '--', command]), { timeoutMs: 60_000 })
+        .catch(() => null)
+      let plan: ShellPlan | null = null
+      try {
+        plan = JSON.parse(ran?.stdout || 'null') as ShellPlan | null
+      } catch {
+        plan = null
+      }
+      if (plan?.kind === 'outbound') {
+        // What it changed here comes back with the project snapshot; what it sent out doesn't (a push is offered back after undo).
+        await bump($, t.id, (x) => ({ ...x, shell: (x.shell ?? 0) + (plan.undoable ? 1 : 0), lost: (x.lost ?? 0) + 1 }))
+      } else if (plan?.kind === 'write') {
+        await bump($, t.id, (x) => (plan.undoable ? { ...x, shell: (x.shell ?? 0) + 1 } : { ...x, lost: (x.lost ?? 0) + 1 }))
+      }
+      // A push: once it's run, note what it sent, so undo can offer to take it back there.
+      if (plan?.id && PUSH.test(command)) {
+        const r = await next(e)
+        await $.process.run(backstep(['shell-end', plan.id])).catch(() => null)
+        return r
+      }
+    } else if (tool.startsWith('mcp__')) {
+      return watchMcp($, e as unknown as Record<string, unknown>, next as unknown as Next)
+    }
+    return next(e)
+  })
+
+  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
+    if (e.props.hasSurvey) return next(e)
+    const { Box, Button, Text } = $.ui.resolve(e)
+    const r = await read($, rewind)
+
+    if (r?.phase === 'running') {
+      return (
+        <Box>
+          <Text color="success" bold>↺ Rewinding </Text>
+          <Text color="success">{bar(r.frame)}</Text>
+          <Text dimColor> undoing the last turn…</Text>
+        </Box>
+      )
+    }
+
+    if (r) {
+      const tone = r.phase === 'failed' ? 'error' : r.phase === 'empty' ? 'warning' : 'success'
+      const glyph = r.phase === 'failed' ? '✗' : r.phase === 'empty' ? '!' : '✓'
+      const visible = r.items.slice(0, Math.min(r.shown, 6))
+      const more = r.items.length - 6
+      return (
+        <Box flexDirection="column">
+          <Text color={tone} bold>
+            {glyph} {r.message}
+          </Text>
+          {visible.map((i, n) => (
+            <Text key={`i${n}`} color={i.ok ? undefined : 'error'} dimColor={i.ok}>
+              {'  '}
+              {i.ok ? '↺ ' : '✗ '}
+              {i.label}
+            </Text>
+          ))}
+          {r.shown >= 6 && more > 0 ? <Text dimColor>{`  and ${more} more`}</Text> : null}
+        </Box>
+      )
+    }
+
+    // Idle: a quiet line naming what one press would take back. The button
+    // has to be on screen for the chord to reach it.
+    const target = (await read($, turns)).findLast(hasWork)
+    if (!target) return next(e)
+    return (
+      <Box>
+        <Text color="success">↺ </Text>
+        <Text dimColor>Last turn: {summary(target)}  </Text>
+        <Button key="undo" action={UNDO_ACTION} plain dimColor onPress={() => void undoLastTurn($)}>
+          ctrl+z to undo
+        </Button>
+      </Box>
+    )
+  })
+}

package/mod/types/index.d.ts

@@ -0,0 +1,30 @@
+// One turn: everything Claude did between two of the person's prompts.
+export type Turn = {
+  id: string
+  startedAt: number
+  edits: number
+  files: string[]
+  mcp: number
+  // Shell commands snapshotted before they ran, so undo takes them back.
+  shell: number
+  // Shell commands and tool calls whose effects can't be taken back: they reached outside the machine with no undo rule, or the project was too big to snapshot.
+  lost: number
+  undone: boolean
+}
+
+export type RewindItem = { label: string; ok: boolean }
+
+// The animation above the prompt while a turn is being rewound.
+export type Rewind = {
+  phase: 'running' | 'done' | 'failed' | 'empty'
+  frame: number
+  shown: number
+  items: RewindItem[]
+  message: string
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    backstep: { turns: Turn[]; rewind: Rewind | null; note: string | null }
+  }
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "backstep",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Undo for everything your agents touch: an MCP proxy that makes agent actions reversible.",
+  "scripts": {
+    "dev": "node src/cli.ts",
+    "ui": "node --disable-warning=ExperimentalWarning src/cli.ts ui",
+    "demo": "node --disable-warning=ExperimentalWarning examples/demo-db.ts",
+    "build": "tsc -p tsconfig.json && cp src/ui/index.html dist/ui/index.html && chmod +x dist/cli.js",
+    "test": "node --disable-warning=ExperimentalWarning --test test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "license": "UNLICENSED",
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "pg": "^8.23.1",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.5.12",
+    "@electric-sql/pglite-socket": "^0.2.15",
+    "@modelcontextprotocol/server-filesystem": "^2.0.1",
+    "@types/node": "^26.6.5",
+    "@types/pg": "^8.23.1",
+    "typescript": "^7.0.2"
+  },
+  "bin": {
+    "backstep": "dist/cli.js"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "files": [
+    "dist",
+    "mod",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "undo",
+    "claude-code",
+    "agents",
+    "rollback"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bzells11/backstep.git"
+  }
+}