backstep 0.1.31 → 0.1.33

package/CHANGES.json

@@ -0,0 +1,41 @@
+[
+  {
+    "version": "0.1.33",
+    "notes": [
+      "After an update, Backstep shows what's new, like this."
+    ]
+  },
+  {
+    "version": "0.1.32",
+    "notes": [
+      "Undoing a Notion change in auto mode now finishes properly when Claude makes the last step.",
+      "Opening a page, file or app is no longer listed as something that couldn't be undone.",
+      "When something can't be undone, Backstep says why in plain words."
+    ]
+  },
+  {
+    "version": "0.1.31",
+    "notes": [
+      "In auto mode, Notion undos are finished by Claude straight away, with no extra question and no red error."
+    ]
+  },
+  {
+    "version": "0.1.30",
+    "notes": [
+      "Updates now say when they're done and it's safe to close the terminal.",
+      "Notion undos work in auto mode."
+    ]
+  },
+  {
+    "version": "0.1.29",
+    "notes": [
+      "If you edited a file after Claude's turn, undo asks before taking your changes along. Keep my changes undoes only Claude's."
+    ]
+  },
+  {
+    "version": "0.1.28",
+    "notes": [
+      "Updates install the new version even when Claude Code is open in a project named backstep."
+    ]
+  }
+]

package/README.md

@@ -70,7 +70,7 @@ The undo key is ctrl+u (not ctrl+z: Claude Code suspends itself on ctrl+z in a t
 
 In the Claude Code desktop app, keys don't reach Backstep, so the line above the message box has an **Undo last turn** button to click instead (it asks once, then undoes). Typing `/backstep-undo` works everywhere and undoes straight away.
 
-Backstep checks npm for a newer version as each Claude Code session starts and asks before updating (Update, Not now, or Skip this version; `backstep update` does it by hand, `BACKSTEP_UPDATE_CHECK=0` turns the check off).
+Backstep checks npm for a newer version as each Claude Code session starts and asks before updating (Update, Not now, or Skip this version; `backstep update` does it by hand, `BACKSTEP_UPDATE_CHECK=0` turns the check off). Once an update is in place, Backstep says what's new, from `CHANGES.json`.
 
 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>`.
 

package/dist/adapters/tree.js

@@ -195,6 +195,7 @@ function projectGit(root, actionId, pushes) {
 // 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 = {}) {
+    lastTreeError = null;
     const root = projectRoot(cwd);
     if (isDiskRoot(root) || root === homedir() || root === resolve(homeDir()))
         return null;
@@ -206,10 +207,13 @@ export function snapshotTree(actionId, cwd, opts = {}) {
         git(["update-ref", `refs/backstep/${actionId}`, commit], { gitDir, workTree: root });
         return { adapter: "tree", root, gitDir, commit, git: projectGit(root, actionId, opts.pushes === true) };
     }
-    catch {
+    catch (err) {
+        lastTreeError = (err instanceof Error ? err.stderr || err.message : String(err)).trim().split("\n").find(Boolean) ?? null;
         return null;
     }
 }
+// Why the last snapshot couldn't be made, in git's words: null when it was too big or the folder is off limits.
+export let lastTreeError = null;
 // Once the command has run: the folder as it left it, kept like the snapshot before it.
 export function recordTreeAfter(u, actionId) {
     const tree = stage(u.gitDir, u.root);

package/dist/cli.js

@@ -6,7 +6,7 @@ import { startUi } from "./ui/server.js";
 import { Store, snapshotDir } from "./store.js";
 import { pendingManual, pruneDatabaseCopies, undoAction, undoRun, undoSince } from "./undo.js";
 import { insideDir, recordAfter, snapshotPaths } from "./adapters/fs.js";
-import { notePushed, recordTreeAfter, snapshotSqlite, snapshotTree } from "./adapters/tree.js";
+import { lastTreeError, notePushed, recordTreeAfter, snapshotSqlite, snapshotTree } from "./adapters/tree.js";
 import { revertPush } from "./push.js";
 import { ghMade, grantScope, openPage, undoGh } from "./github.js";
 import { accessNow, accessOnline, currentNote, login, logout, requireAccess } from "./account.js";
@@ -57,7 +57,7 @@ import { connect } from "./connect.js";
 import { check, printCheck } from "./check.js";
 import { logo } from "./look.js";
 import { keyLabel, setUndoKey, undoKeys } from "./keys.js";
-import { checkUpdate, runUpdate, skipVersion } from "./update.js";
+import { changesSince, checkUpdate, runUpdate, skipVersion } from "./update.js";
 import { askConnectionString } from "./setup.js";
 // Header values can name env vars, so tokens don't have to sit in agent config files.
 function parseHeaders(list) {
@@ -124,6 +124,8 @@ const HELP = `backstep: undo for everything your agents touch
   backstep undo --since <ms> [--until <ms>] [--json] [--via-claude-code] [--manual ask|undo|keep]
                                undo everything any agent did in that window; files changed since
                                (often by hand) are undone too, kept, or named first with ask
+  backstep changes --since <version> [--json]
+                               what's new since that version
   backstep after <action-id>   note how a tool left the files, once it ran (used by the Claude Code mod)
   backstep snap --session <id> --tool <name> [--cwd <dir>] -- <paths...>
                                save paths before Claude Code's own tools change them (used by the Claude Code mod)
@@ -340,6 +342,19 @@ async function main() {
         return;
     }
     // `backstep update` installs the newest version; --skip <v> stops asking about that one.
+    // What's new since a version, for the mod to show once an update is in place.
+    if (cmd === "changes") {
+        const { values } = parseArgs({ args: rest, options: { since: { type: "string" }, json: { type: "boolean", default: false } } });
+        if (!values.since)
+            throw new Error("usage: backstep changes --since <version> [--json]");
+        const list = changesSince(values.since);
+        if (values.json)
+            console.log(JSON.stringify(list));
+        else
+            for (const c of list)
+                console.log(`${c.version}\n${c.notes.map((n) => `  - ${n}`).join("\n")}`);
+        return;
+    }
     if (cmd === "update") {
         const { values } = parseArgs({ args: rest, options: { skip: { type: "string" }, version: { type: "string" }, json: { type: "boolean", default: false } } });
         if (values.skip) {
@@ -520,13 +535,14 @@ async function main() {
         const kind = plan.kind === "outbound" && saved && /database|request/.test(plan.reason ?? "") ? "write" : plan.kind;
         if (kind !== plan.kind)
             store.updateAction(a.id, { kind: "reversible", reason: null });
+        const unsaved = lastTreeError ? `Backstep couldn't save a copy first (${lastTreeError})` : "Backstep couldn't save a copy first (the folder is too big, or it's your whole home folder)";
         if (!undo && kind !== "outbound")
-            store.updateAction(a.id, { kind: "write", reason: "project too large to snapshot" });
+            store.updateAction(a.id, { kind: "write", reason: unsaved });
         if (missed.length)
             store.updateAction(a.id, { reason: `couldn't save the database first: ${missed[0]}` });
         if (dbs.length)
             await pruneDatabaseCopies(store).catch(() => { });
-        console.log(JSON.stringify({ kind, reason: kind === plan.kind ? plan.reason : undefined, id: a.id, undoable: undo !== null, db: saved }));
+        console.log(JSON.stringify({ kind, reason: !undo && kind !== "outbound" ? unsaved : kind === plan.kind ? plan.reason : undefined, id: a.id, undoable: undo !== null, db: saved }));
         return;
     }
     // Before a shell command, from the Claude Code mod: does it reach a Supabase project Backstep

package/dist/shell.js

@@ -10,6 +10,8 @@ const READ_PROGRAMS = new Set([
     "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",
+    // Opening a page, a file or an app in it changes nothing here by itself.
+    "open", "xdg-open",
 ]);
 const READ_GIT = new Set([
     "status", "log", "diff", "show", "blame", "grep", "ls-files", "ls-tree", "rev-parse", "describe", "shortlog",

package/dist/update.js

@@ -4,7 +4,8 @@
 // Off with BACKSTEP_UPDATE_CHECK=0.
 import { spawnSync } from "./spawn.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { tmpdir } from "node:os";
 import { homeDir } from "./store.js";
 import { version } from "./telemetry.js";
@@ -48,6 +49,15 @@ export async function checkUpdate() {
     const available = latest !== null && newer(latest, current) && settings().skipVersion !== latest;
     return { current, latest, available };
 }
+export function changesSince(from, upTo = version()) {
+    try {
+        const all = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "CHANGES.json"), "utf8"));
+        return all.filter((c) => newer(c.version, from) && !newer(c.version, upTo)).sort((a, b) => (newer(a.version, b.version) ? -1 : 1));
+    }
+    catch {
+        return [];
+    }
+}
 export function skipVersion(v) {
     mkdirSync(homeDir(), { recursive: true });
     writeFileSync(file(), JSON.stringify({ ...settings(), skipVersion: v }, null, 2) + "\n");

package/mod/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "backstep",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "description": "Press ctrl+z to rewind everything Claude did in its last turn: file edits, shell commands, and database and tool changes.",
   "types": "./types/index.d.ts",
   "userConfig": {

package/mod/hooks/register.test.tsx

@@ -373,9 +373,14 @@ test('a Notion move: the pages are read first, and undo runs every opposite call
   await ui.unmount()
 })
 
-test('when the opposite call fails, the rewind says so', { options: { cli: CLI } }, async ($, on) => {
+test('when the opposite call fails, the rewind says so, plainly', { options: { cli: CLI } }, async ($, on) => {
   const clock = mock.clock(on, { now: 5000 })
-  const { runs } = connector(on, { start: { kind: 'reversible', id: 'w1' }, undoable: true, mcpFails: true })
+  const { runs } = connector(on, {
+    start: { kind: 'reversible', id: 'w1' },
+    undoable: true,
+    mcpFails: true,
+    undo: { id: 'w1', tool: 'notion-create-pages', ok: true, detail: 'runs notion-delete-pages', run: { server: 'claude_ai_Notion', tool: 'notion-delete-pages', args: { page_ids: ['p1'] }, label: 'Notion: moved the pages Claude made to Trash' } },
+  })
 
   await $.prompt.submit({ text: 'make a page', wait: false, origin: { kind: 'composer' } })
   await $.tool.call({ tool: 'mcp__claude_ai_Notion__create-page', title: 'Plan' } as never)
@@ -385,7 +390,8 @@ test('when the opposite call fails, the rewind says so', { options: { cli: CLI }
   await clock.advance(1000)
   await pressed
   expect(runs.at(-1)?.argv.slice(3)).toEqual(['settle', 'w1', '--failed', 'no such page'])
-  expect((await ui.find({ type: 'Text', text: /no such page/ }))).toBeTruthy()
+  expect((await ui.find({ type: 'Text', text: /no such page/ }))?.text).toContain(`Couldn't move the pages Claude made to Trash: Notion said "no such page"`)
+  expect(await ui.find({ type: 'Text', text: /notion-delete-pages failed/ })).toBeFalsy()
   await ui.unmount()
 })
 
@@ -1271,6 +1277,8 @@ test('an update that reloads the mod partway is finished by the reloaded mod: it
     }
     const stdout = argv.includes('update-check')
       ? JSON.stringify({ current: started ? '0.2.0' : '0.1.2', latest: '0.2.0', available: !started })
+      : argv.includes('changes')
+        ? JSON.stringify(argv.includes('0.1.2') ? [{ version: '0.2.0', notes: ['Undo is faster.', 'Notion undos finish in auto mode.'] }] : [])
       : argv.includes('status')
         ? JSON.stringify({ items: [], suggest: [] })
         : '[]'
@@ -1314,6 +1322,8 @@ test('an update that reloads the mod partway is finished by the reloaded mod: it
   }
   expect(statuses.at(-1)).toBeUndefined()
   expect(logs.join('\n')).toContain('Backstep is updated to 0.2.0 (you had 0.1.2). It\'s safe to close this terminal now.')
+  // Then what changed, from the new version's own notes.
+  expect(logs.join('\n')).toContain("What's new in 0.2.0:\n  • Undo is faster.\n  • Notion undos finish in auto mode.")
   await ui.unmount()
 })
 
@@ -1355,7 +1365,8 @@ test("when auto mode won't let Backstep undo a Notion change, Claude is asked to
   // Claude makes the call: it isn't recorded as a change of its own, and the change is marked undone.
   const before = ran.length
   const watched = runs.filter((r) => r.argv.includes('watch-start')).length
-  await $.tool.call({ tool: 'mcp__claude_ai_Notion__notion-delete-pages', page_ids: ['p1'], user_confirmed: true, tool_use_id: 'tu2' } as never)
+  // Claude adds an argument of its own (Notion's telemetry): still the same call.
+  await $.tool.call({ tool: 'mcp__claude_ai_Notion__notion-delete-pages', page_ids: ['p1'], user_confirmed: true, telemetry: { intent: 'undo' }, tool_use_id: 'tu2' } as never)
   expect(ran.length).toBe(before + 1)
   expect(runs.filter((r) => r.argv.includes('watch-start')).length).toBe(watched)
   expect(runs.at(-1)?.argv.slice(3)).toEqual(['settle', 'w1'])

package/mod/hooks/register.tsx

@@ -395,7 +395,7 @@ async function undoLastTurn($: EngineInterface, count = 1) {
     }
     if (failed) {
       o.ok = false
-      o.detail = `${failed.tool} failed: ${failed.why}`
+      o.detail = couldnt(run.label, failed.why, `undo ${o.tool}`)
       await $.process.run(backstep(['settle', o.id, '--failed', failed.why])).catch(() => null)
       break
     }
@@ -415,7 +415,7 @@ async function undoLastTurn($: EngineInterface, count = 1) {
         .filter(Boolean)
         .map((line): RewindItem => (o.pending ? { label: undoneLabel(line, short), ok: true, pending: true, action: o.id } : { label: undoneLabel(line, short), ok: true })),
     )
-  const stopped = outcomes.filter((o) => !o.ok).map((o) => ({ label: `${o.tool}: ${o.detail.split('\n')[0] ?? 'failed'}`, ok: false }))
+  const stopped = outcomes.filter((o) => !o.ok).map((o) => { const line = o.detail.split('\n')[0] ?? 'failed'; return { label: line.startsWith("Couldn't ") ? line : `${o.tool}: ${line}`, ok: false } })
   // A push, or something made on GitHub, is offered back below, so it isn't listed as lost.
   const offered = outcomes.some((o) => o.ok && o.pushed)
   const offeredGh = outcomes.some((o) => o.ok && o.github?.length)
@@ -599,13 +599,31 @@ function undoneLabel(line: string, short: (p: string) => string): string {
   return `${p} ${m[1]}`
 }
 
-// Opposite calls handed to Claude to make, after the person said yes: the call,
-// by tool and arguments, to the action it undoes. Not recorded as Claude's own,
-// and once all of an action's have run, it counts as undone.
-const handedOver = new Map<string, string>()
+// Opposite calls handed to Claude to make after the person pressed undo: the call
+// and the action it undoes. Not recorded as Claude's own, and once all of an
+// action's have run, it counts as undone.
+type Handed = { tool: string; args: Record<string, unknown>; action: string }
+const handedOver: Handed[] = []
+
+// Claude's call is the one handed over when it's the same tool with the same
+// values for every argument Backstep gave; Claude adds its own (Notion's telemetry, say).
+function handedCall(tool: string, args: Record<string, unknown>): Handed | undefined {
+  return handedOver.find((h) => h.tool === tool && Object.entries(h.args).every(([k, v]) => undoCallKey('', v) === undoCallKey('', args[k])))
+}
 
 type Handoff = { id: string; server: string; calls: { tool: string; args: Record<string, unknown> }[]; label: string }
 
+// A change that didn't come back, said plainly: "Notion: moved the pages Claude made to Trash"
+// that failed reads "Couldn't move the pages Claude made to Trash: Notion said "no such page"".
+const INFINITIVE: Record<string, string> = { moved: 'move', restored: 'restore', put: 'put', archived: 'archive', deleted: 'delete', removed: 'remove', ran: 'run', closed: 'close', reopened: 'reopen', set: 'set' }
+function couldnt(label: string | undefined, why: string, fallback: string): string {
+  const reason = why.replace(/^(backstep|error):\s*/i, '').split(/(?<=\.)\s/)[0].slice(0, 140)
+  const m = label?.match(/^(?:([A-Z][\w.]*(?: [A-Z][\w.]*)*): )?(\w+)\s(.*)$/)
+  const verb = m ? INFINITIVE[m[2]] : undefined
+  const what = m && verb ? `${verb} ${m[3]}` : fallback
+  return m?.[1] ? `Couldn't ${what}: ${m[1]} said "${reason}"` : `Couldn't ${what}: ${reason}`
+}
+
 // Said after "Rewound …" while Claude still has some of it to finish.
 function finishing(items: RewindItem[]): string {
   const n = items.filter((i) => i.pending).length
@@ -620,7 +638,7 @@ async function handOff($: EngineInterface, list: Handoff[]) {
   for (const h of list) {
     const server = toolServer(h.server)
     for (const c of h.calls) {
-      handedOver.set(undoCallKey(`mcp__${server}__${c.tool}`, c.args), h.id)
+      handedOver.push({ tool: `mcp__${server}__${c.tool}`, args: c.args, action: h.id })
       steps.push(`- mcp__${server}__${c.tool} with ${JSON.stringify(c.args)}`)
     }
   }
@@ -638,7 +656,7 @@ async function handOff($: EngineInterface, list: Handoff[]) {
 async function handedBack($: EngineInterface, action: string, ok: boolean, why?: string) {
   await update($, rewind, (r) => {
     if (!r) return r
-    const items = r.items.map((i) => (i.pending && i.action === action ? (ok ? { ...i, pending: false } : { label: `${i.label}: Claude couldn't (${why ?? 'it failed'})`, ok: false }) : i))
+    const items = r.items.map((i) => (i.pending && i.action === action ? (ok ? { ...i, pending: false } : { label: couldnt(i.label, why ?? 'it failed', 'finish undoing it'), ok: false }) : i))
     const undone = items.filter((i) => i.ok)
     // "Rewound 2 changes from the last turn. Claude is finishing it." loses its last sentence once Claude has.
     const [rewound, ...rest] = r.message.replace(/ Claude is finishing [^.]*\./, '').split(/(?<=\.) /)
@@ -887,9 +905,26 @@ async function offerUpdate($: EngineInterface) {
   await installUpdate($, u.current, u.latest)
 }
 
-function updated($: EngineInterface, u: Updating) {
+async function updated($: EngineInterface, u: Updating) {
   $.ui.log(`${MARK_TEXT} Backstep is updated to ${u.to}${u.from ? ` (you had ${u.from})` : ''}. It's safe to close ${u.win} now. Restart Claude Code to start using ${u.to}.`)
   $.ui.toast(`Backstep is updated to ${u.to}. Restart Claude Code to use it.`)
+  if (u.from) await whatsNew($, u.from)
+}
+
+// What changed since the version before, from the new version's own notes.
+async function whatsNew($: EngineInterface, from: string) {
+  const ran = await $.process.run(backstep(['changes', '--since', from, '--json']), { timeoutMs: 15_000 }).catch(() => null)
+  let list: { version: string; notes: string[] }[] = []
+  try {
+    list = JSON.parse(ran?.stdout || '[]') as typeof list
+  } catch {
+    return
+  }
+  list = list.filter((c) => c.notes?.length)
+  if (!list.length) return
+  const one = list.length === 1
+  const lines = one ? list[0].notes.map((n) => `  • ${n}`) : list.flatMap((c) => [`  ${c.version}`, ...c.notes.map((n) => `    • ${n}`)])
+  $.ui.log([`${MARK_TEXT} What's new${one ? ` in ${list[0].version}` : ` since ${from}`}:`, ...lines].join('\n'))
 }
 
 // After a reload in the middle of an update: once the new version is in place,
@@ -911,7 +946,7 @@ async function finishUpdate($: EngineInterface) {
       await $.clock.sleep(5000)
       $.ui.status(undefined)
       await update($, updating, () => null)
-      updated($, u)
+      await updated($, u)
       return
     }
     await $.clock.sleep(5000)
@@ -943,7 +978,7 @@ async function installUpdate($: EngineInterface, current: string | undefined, la
   $.ui.status(undefined)
   await update($, updating, () => null)
   if (r.ok) {
-    updated($, { ...(u.current ? { from: u.current } : {}), to: latest, win })
+    await updated($, { ...(u.current ? { from: u.current } : {}), to: latest, win })
     return true
   } else {
     $.ui.log(`${MARK_TEXT} Backstep couldn't update to ${u.latest}: ${r.detail}. You're still on ${u.current ?? 'the version you had'}${forced ? '' : ', which keeps working'}. To try again, run: npx backstep@latest setup`)
@@ -1139,19 +1174,22 @@ export const register: Register = (on, options) => {
   on('tool.call', async ($, e, next) => {
     const tool = String(e.tool)
     // An opposite call Claude is making for undo, as the person asked: not recorded as a change of its own.
-    const handed = handedOver.size ? undoCallKey(tool, Object.fromEntries(Object.entries(e).filter(([k]) => !RESERVED.has(k)))) : ''
-    const forAction = handed ? handedOver.get(handed) : undefined
-    if (forAction) {
+    const handed = handedOver.length ? handedCall(tool, Object.fromEntries(Object.entries(e).filter(([k]) => !RESERVED.has(k)))) : undefined
+    if (handed) {
+      const forAction = handed.action
       const r = (await next(e)) as { deny?: string; isError?: boolean; text?: string }
+      const drop = (which: (h: Handed) => boolean) => {
+        for (let i = handedOver.length - 1; i >= 0; i--) if (which(handedOver[i])) handedOver.splice(i, 1)
+      }
       if (!r.deny && !r.isError) {
-        handedOver.delete(handed)
-        if (![...handedOver.values()].includes(forAction)) {
+        drop((h) => h === handed)
+        if (!handedOver.some((h) => h.action === forAction)) {
           await $.process.run(backstep(['settle', forAction])).catch(() => null)
           await handedBack($, forAction, true)
         }
       } else {
         const why = (r.deny ?? r.text ?? 'it failed').trim().split('\n')[0]
-        for (const [k, a] of handedOver) if (a === forAction) handedOver.delete(k)
+        drop((h) => h.action === forAction)
         await $.process.run(backstep(['settle', forAction, '--failed', why])).catch(() => null)
         await handedBack($, forAction, false, why)
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backstep",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "description": "Undo for everything your agents touch: an MCP proxy that makes agent actions reversible.",
   "homepage": "https://getbackstep.com",
   "scripts": {
@@ -37,7 +37,8 @@
   "files": [
     "dist",
     "mod",
-    "README.md"
+    "README.md",
+    "CHANGES.json"
   ],
   "keywords": [
     "mcp",