backstep 0.1.26 → 0.1.28

package/README.md

@@ -67,6 +67,8 @@ With Claude Code: `claude mcp add files -- backstep wrap --name files -- <the se
 
 The undo key is ctrl+u (not ctrl+z: Claude Code suspends itself on ctrl+z in a terminal before anything else sees the key, so it can't be used). The first press asks "Undo Claude's last turn?" above the prompt and a second press within 5 seconds undoes, so a stray press does nothing. Change the key whenever you like: ask Claude ("change my Backstep undo key to ctrl+q"), or run `backstep key ctrl+q`. The line above the prompt is always there, even with nothing to undo, because the key only reaches Backstep while it's on screen; otherwise a press would do nothing.
 
+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).
 
 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>`.
@@ -119,7 +121,7 @@ Everything is journaled to `~/.backstep/journal.db` (SQLite, mode 0600; override
 
 ## Telemetry
 
-`backstep setup` sends one anonymous `install` event, Claude Code with the Backstep mod sends one `active` event a day, and `backstep uninstall` sends one `uninstall` event. 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`.
+`backstep setup` sends one anonymous `install` event the first time on a computer (and an `update` event each time after, as updates run setup again), Claude Code with the Backstep mod sends one `active` event a day, and `backstep uninstall` sends one `uninstall` event. 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`.
 

package/dist/setup.js

@@ -86,6 +86,10 @@ export async function setup() {
     }
     if (!r.ok)
         throw new Error(`claude plugin install failed:\n${r.out}`);
+    // Already installed, install keeps Claude Code's cached copy of the mod as it
+    // was; re-reading the folder and updating brings the mod up to this version.
+    run("claude", ["plugin", "marketplace", "update", "backstep"]);
+    run("claude", ["plugin", "update", "backstep@backstep"]);
     // Only a problem is worth a line here; the summary below says the rest.
     const bound = ensureUndoKey();
     if (bound)

package/dist/telemetry.js

@@ -1,4 +1,4 @@
-// An anonymous count of installs and of installs still in use, so we know how
+// An anonymous count of installs, updates and 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.
@@ -62,7 +62,10 @@ async function send(event) {
         // Offline, blocked, or slow: skip it.
     }
 }
-export const sendInstall = () => send("install");
+// Setup runs on a first install and again on every update. Only the first, on a
+// computer that has never sent anything (no install-id yet), counts as an
+// install; every later setup is an update, so installs stay new installs.
+export const sendInstall = () => send(existsSync(join(homeDir(), "install-id")) ? "update" : "install");
 export const sendUninstall = () => send("uninstall");
 // At most once a day, as Claude Code starts with Backstep's mod.
 export async function sendActive() {

package/dist/update.js

@@ -5,6 +5,7 @@
 import { spawnSync } from "./spawn.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { tmpdir } from "node:os";
 import { homeDir } from "./store.js";
 import { version } from "./telemetry.js";
 const REGISTRY = process.env.BACKSTEP_REGISTRY ?? "https://registry.npmjs.org";
@@ -68,6 +69,9 @@ const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0,
 // at it and re-wraps servers, exactly as a fresh install would. npm is asked
 // online, never from its cache, which can be older than a version just
 // published; and asked again for a while if it still hasn't heard of it.
+// It runs from a neutral folder: inside a project that is itself named
+// backstep (or depends on it), npx runs that copy instead of fetching the one
+// asked for, and the "update" reinstalls the old version.
 export function runUpdate(v, tries = 4) {
     let out = "";
     for (let i = 0; i < tries; i++) {
@@ -78,10 +82,15 @@ export function runUpdate(v, tries = 4) {
             timeout: 5 * 60 * 1000,
             env: { ...process.env, NO_COLOR: "1", BACKSTEP_TELEMETRY: "0" },
             stdio: ["ignore", "pipe", "pipe"],
+            cwd: tmpdir(),
         });
-        if (r.status === 0)
-            return { ok: true, detail: `updated to ${v}` };
         out = `${r.stderr ?? ""}\n${r.stdout ?? ""}`;
+        // Setup says which version it put in place; anything else means npx ran some other copy.
+        if (r.status === 0) {
+            if (out.includes(`backstep@${v}`))
+                return { ok: true, detail: `updated to ${v}` };
+            return { ok: false, detail: `npx ran a different copy of Backstep instead of ${v}. Run this from your home folder: npx backstep@${v} setup` };
+        }
         if (!/ETARGET|notarget|No matching version/i.test(out))
             break;
     }

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

@@ -1,6 +1,6 @@
 {
   "name": "backstep",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "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

@@ -1129,3 +1129,50 @@ test('when signing in is required and nobody is, ctrl+u says how to sign in inst
   expect(toasts.at(-1)).toContain('npx backstep login')
   await ui.unmount()
 })
+
+test('in the desktop app the band says Undo (a click), since ctrl+u never reaches it there', { options: { cli: CLI } }, async ($, on) => {
+  mock.clock(on, { now: 5000 })
+  engine(on, { exitCode: 0, stdout: '[]' })
+  await $.prompt.submit({ text: 'fix it', wait: false, origin: { kind: 'composer' } })
+  await $.tool.call({ tool: 'Edit', file_path: '/repo/src/a.ts', old_string: 'a', new_string: 'b' })
+
+  const desk = await $.ui.mount({ ...BAND, surface: 'desktop' })
+  expect((await desk.find({ type: 'Button', key: 'undo' }))?.text).toBe('◀ Undo last turn')
+  expect(JSON.stringify(await desk.find({ type: 'Box', text: /Undo last turn/ }))).not.toContain('ctrl')
+  await desk.press({ key: 'undo' })
+  expect(await desk.find({ type: 'Text', text: /Undo Claude's last turn\?/ })).toBeTruthy()
+  expect((await desk.find({ type: 'Button', key: 'undo' }))?.text).toBe('Yes, undo it')
+  expect((await desk.find({ type: 'Button', key: 'cancel' }))?.text).toBe('Cancel')
+  await desk.unmount()
+
+  const term = await $.ui.mount({ ...BAND, surface: 'terminal' })
+  expect((await term.find({ type: 'Button', key: 'undo' }))?.text).toContain('again to undo')
+  await term.unmount()
+})
+
+test('/backstep-undo undoes the last turn straight away, and says when there is nothing to undo', { options: { cli: CLI } }, async ($, on) => {
+  const clock = mock.clock(on, { now: 5000 })
+  const { runs } = engine(on, { exitCode: 0, stdout: JSON.stringify([{ id: 'c1', tool: 'Edit', ok: true, detail: 'restored /repo/src/a.ts' }]) })
+
+  expect(JSON.stringify(await $.command.run({ command: 'backstep-undo' } as never))).toContain('Nothing to undo yet')
+
+  await $.prompt.submit({ text: 'fix it', wait: false, origin: { kind: 'composer' } })
+  await $.tool.call({ tool: 'Edit', file_path: '/repo/src/a.ts', old_string: 'a', new_string: 'b' })
+  const ran = $.command.run({ command: 'backstep-undo' } as never)
+  await clock.advance(1000)
+  const r = await ran
+  expect(runs.some((a) => a[3] === 'undo')).toBe(true)
+  expect(JSON.stringify(r)).toContain('Rewound 1 change from the last turn.')
+})
+
+test('in the desktop app, the update is offered the same way and says not to close Claude Code', { options: { cli: CLI } }, async ($, on) => {
+  const { asked, logs, statuses } = updates(on, 'Update')
+  await $.session.start({ cwd: '/repo', surface: 'desktop', hasPerson: true } as never)
+  await settle()
+  expect(asked).toEqual(['Backstep 0.2.0 is out (you have 0.1.2). Update now?'])
+  const said = logs.join('\n')
+  expect(said).toContain('type /backstep-undo')
+  expect(said).toContain("Don't close Claude Code until it says it's done")
+  expect(statuses[0]).toContain("don't close Claude Code")
+  expect(said).not.toContain('terminal')
+})

package/mod/hooks/register.tsx

@@ -281,6 +281,18 @@ async function pressUndo($: EngineInterface) {
   })
 }
 
+// /backstep-undo: the command is the confirmation, so it undoes straight away.
+async function undoByCommand($: EngineInterface): Promise<string> {
+  if (await read($, rewind)) return 'Backstep is already undoing a turn.'
+  const off = await read($, blocked)
+  if (off) return `${MARK_TEXT} ${off}`
+  if (!(await read($, turns)).some(hasWork)) return "Nothing to undo yet: Claude hasn't changed anything Backstep can take back."
+  await update($, armed, () => null)
+  const { before } = await undoTargets($)
+  await undoLastTurn($, before ? 2 : 1)
+  return (await read($, rewind))?.message ?? 'Done.'
+}
+
 // Undoes the last `count` turns that changed something, newest first.
 async function undoLastTurn($: EngineInterface, count = 1) {
   if (await read($, rewind)) return
@@ -396,7 +408,7 @@ async function undoLastTurn($: EngineInterface, count = 1) {
 
   if (done) {
     const list = items.filter((i) => i.ok).map((i) => `- ${i.label}`).join('\n')
-    const key = await keysLabel($)
+    const key = surface === 'terminal' ? await keysLabel($) : 'the Undo button or /backstep-undo'
     await update($, note, () =>
       `[Backstep] The user pressed undo (${key}) on your ${taken.length > 1 ? `last ${taken.length} turns` : '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` : '') +
@@ -686,7 +698,7 @@ async function checkAccess($: EngineInterface): Promise<boolean> {
     // the minimum, then
   }
   const answer = await $.ui
-    .ask(`This version of Backstep (${a.current}) is no longer supported, so ${await keysLabel($)} is off until it updates. Update to ${latest} now?`, {
+    .ask(`This version of Backstep (${a.current}) is no longer supported, so ${surface === 'terminal' ? await keysLabel($) : 'undo'} is off until it updates. Update to ${latest} now?`, {
       header: 'Backstep',
       options: ['Update now', 'Not now'],
     })
@@ -721,9 +733,10 @@ async function installUpdate($: EngineInterface, current: string | undefined, la
   const u = { current, latest }
   // Said where it stays (the conversation) and where it's seen while it runs (the status line).
   const from = u.current ? ` from ${u.current}` : ''
-  $.ui.log(`${MARK_TEXT} Updating Backstep${from} to ${u.latest}… Don't close this terminal until it says it's done (about a minute).`)
-  $.ui.toast(`Updating Backstep to ${u.latest}. Don't close this terminal until it's done.`, { timeoutMs: 15_000 })
-  $.ui.status(`◀◀ Updating Backstep to ${u.latest}… don't close this terminal`)
+  const win = surface === 'terminal' ? 'this terminal' : 'Claude Code'
+  $.ui.log(`${MARK_TEXT} Updating Backstep${from} to ${u.latest}… Don't close ${win} until it says it's done (about a minute).`)
+  $.ui.toast(`Updating Backstep to ${u.latest}. Don't close ${win} until it's done.`, { timeoutMs: 15_000 })
+  $.ui.status(`◀◀ Updating Backstep to ${u.latest}… don't close ${win}`)
   const done = await $.process
     .run(backstep(['update', '--version', u.latest, '--json']), { timeoutMs: 600_000 })
     .catch((err: unknown) => ({ exitCode: 1, stdout: '', stderr: err instanceof Error ? err.message : String(err) }))
@@ -735,7 +748,7 @@ async function installUpdate($: EngineInterface, current: string | undefined, la
   }
   $.ui.status(undefined)
   if (r.ok) {
-    $.ui.log(`${MARK_TEXT} Backstep is updated to ${u.latest}${u.current ? ` (you had ${u.current})` : ''}. It's safe to close the terminal now. Restart Claude Code to start using ${u.latest}.`)
+    $.ui.log(`${MARK_TEXT} Backstep is updated to ${u.latest}${u.current ? ` (you had ${u.current})` : ''}. It's safe to close ${win} now. Restart Claude Code to start using ${u.latest}.`)
     $.ui.toast(`Backstep is updated to ${u.latest}. Restart Claude Code to use it.`)
     return true
   } else {
@@ -866,15 +879,21 @@ async function uninstallBackstep($: EngineInterface): Promise<string> {
   return `Backstep is removed. Restart Claude Code to finish.\n${lines}`
 }
 
+// Where this session is drawn: the terminal, or an app (the desktop app, VS Code) where there's no terminal to mention.
+let surface = 'terminal'
+
 export const register: Register = (on, options) => {
   cli = String(options.cli ?? 'backstep')
 
   on('session.start', async ($, e, next) => {
+    surface = e.surface ?? 'terminal'
     await $.tool.register(CONNECT_TOOL)
     await $.tool.register(KEY_TOOL)
     await $.tool.register(UNINSTALL_TOOL)
     // A command that can't be added never holds up the session: asking Claude still uninstalls.
     await $.command.register({ name: 'uninstall-backstep', description: 'Remove Backstep and everything it set up from this computer' }).catch(() => null)
+    // Undo by command too: the desktop app has no way for ctrl+u to reach Backstep yet.
+    await $.command.register({ name: 'backstep-undo', description: "Undo Claude's last turn with Backstep" }).catch(() => null)
     const r = await next(e)
     const boundOut = await $.process.run(backstep(['key', '--json'])).catch(() => null)
     try {
@@ -884,7 +903,11 @@ export const register: Register = (on, options) => {
       // keep the default
     }
     // Said first thing, so nobody has to wonder whether it's running.
-    $.ui.log(`✓ Backstep connected · press ${await keysLabel($)} to undo Claude's last turn`)
+    $.ui.log(
+      e.surface === 'terminal'
+        ? `✓ Backstep connected · press ${await keysLabel($)} to undo Claude's last turn`
+        : "✓ Backstep connected · click Undo last turn above the message box, or type /backstep-undo, to undo Claude's last turn",
+    )
     // In the background: a session never waits on either.
     void wrapNewServers($, e.cwd)
     // One question at a time: Supabase first, then whether this version may run, then any update.
@@ -917,6 +940,7 @@ export const register: Register = (on, options) => {
   on('tool.call', { tool: UNINSTALL }, async ($) => ({ result: await uninstallBackstep($) }))
 
   on('command.run', { command: 'uninstall-backstep' }, async ($) => ({ text: await uninstallBackstep($) }))
+  on('command.run', { command: 'backstep-undo' }, async ($) => ({ text: await undoByCommand($) }))
 
   on('tool.call', async ($, e, next) => {
     const tool = String(e.tool)
@@ -1066,6 +1090,57 @@ export const register: Register = (on, options) => {
 
     const { target, before } = await undoTargets($)
     const label = (await read($, keys)).map(keyLabel).join(' / ')
+
+    // The desktop app (and any app that isn't the terminal): ctrl+u never reaches
+    // Backstep there, so it's real buttons to click and no key is mentioned.
+    const appBand = async (target: Turn | undefined, before: Turn | undefined) => {
+      const cancel = (
+        <Button key="cancel" variant="secondary" onPress={() => void update($, armed, () => null)}>
+          Cancel
+        </Button>
+      )
+      if (target && (await read($, armed)) !== null) {
+        return (
+          <Box flexDirection="column">
+            <Box>
+              {mark()}
+              <Text color="warning" bold>{before ? 'That turn only saved and pushed to git.' : "Undo Claude's last turn?"}</Text>
+            </Box>
+            <Text dimColor>{before ? `   Undo it and the turn before it${quoted(before, 50)}?` : `   ${quoted(target, 50).trim() || 'That turn'} · ${summary(target)}`}</Text>
+            <Box marginTop={1}>
+              <Text>{'   '}</Text>
+              <Button key="undo" variant="primary" onPress={() => void pressUndo($)}>
+                {before ? 'Yes, undo both' : 'Yes, undo it'}
+              </Button>
+              <Text>{'  '}</Text>
+              {before ? (
+                <Button key="just" variant="secondary" onPress={() => void update($, armed, () => null).then(() => undoLastTurn($, 1))}>
+                  Just the push
+                </Button>
+              ) : null}
+              {before ? <Text>{'  '}</Text> : null}
+              {cancel}
+            </Box>
+          </Box>
+        )
+      }
+      return (
+        <Box>
+          {mark()}
+          <Box flexShrink={1} minWidth={0}>
+            <Text dimColor wrap="truncate-end">{target ? `Last turn:${quoted(target, 28)} · ${summary(target)}` : 'Backstep is running · nothing to undo yet'}</Text>
+          </Box>
+          <Box flexShrink={0} marginLeft={2}>
+            <Button key="undo" variant="primary" onPress={() => void pressUndo($)}>
+              ◀ Undo last turn
+            </Button>
+          </Box>
+        </Box>
+      )
+    }
+    // Only the terminal hands ctrl+u to the button; anywhere else (the desktop app) it's a click.
+    const keyed = e.surface === 'terminal'
+    if (!keyed) return appBand(target, before)
     if (target && (await read($, armed)) !== null) {
       // Laid out a line at a time, so nothing gets squeezed into columns on a narrow terminal.
       const cancel = (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backstep",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "description": "Undo for everything your agents touch: an MCP proxy that makes agent actions reversible.",
   "homepage": "https://getbackstep.com",
   "scripts": {