backstep 0.1.1 → 0.1.2

package/README.md

@@ -52,6 +52,8 @@ With Claude Code: `claude mcp add files -- backstep wrap --name files -- <the se
 | `--rules <file>` | undo rules (or set `BACKSTEP_RULES`) |
 | `--pg <url>` | the Postgres database the wrapped server writes to. Enables database undo. Without it, SQL writes are recorded but can't be undone. |
 
+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>`.
 
 In Claude Code you can just ask: "connect Backstep to everything I use". Supabase is connected from the project's settings (or the connection string you paste), and when the project uses Firebase but Claude can't reach it yet, Firebase's MCP server is added behind Backstep.

package/dist/cli.js

@@ -20,6 +20,7 @@ import { disconnectSupabase, dismissSupabase } from "./supabase.js";
 import { connect } from "./connect.js";
 import { check, printCheck } from "./check.js";
 import { logo } from "./look.js";
+import { 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) {
@@ -57,6 +58,7 @@ const HELP = `backstep: undo for everything your agents touch
                                Supabase from the project's .env files or local database (or the
                                connection string you give), Firebase by adding its MCP server.
                                In Claude Code you can just ask: "connect Backstep to my Supabase"
+  backstep update               install the newest version (Claude Code offers this as a session starts)
   backstep status [--json]     what Backstep can and can't undo for each service Claude Code reaches,
                                and what to connect next
   backstep disconnect supabase <ref>
@@ -208,6 +210,27 @@ async function main() {
         }
         return;
     }
+    // Run by the Claude Code mod as a session starts: is there a newer Backstep?
+    if (cmd === "update-check") {
+        console.log(JSON.stringify(await checkUpdate()));
+        return;
+    }
+    // `backstep update` installs the newest version; --skip <v> stops asking about that one.
+    if (cmd === "update") {
+        const { values } = parseArgs({ args: rest, options: { skip: { type: "string" }, version: { type: "string" }, json: { type: "boolean", default: false } } });
+        if (values.skip) {
+            skipVersion(values.skip);
+            return;
+        }
+        const target = values.version ?? (await checkUpdate()).latest;
+        if (!target)
+            throw new Error("couldn't reach npm to find the newest version");
+        const out = runUpdate(target);
+        console.log(values.json ? JSON.stringify(out) : out.ok ? `Backstep ${out.detail}. Restart Claude Code to use it.` : `Update failed: ${out.detail}`);
+        if (!out.ok)
+            process.exitCode = 1;
+        return;
+    }
     if (cmd === "disconnect") {
         const [service, ref] = rest;
         if (service !== "supabase" || !ref)

package/dist/telemetry.js

@@ -29,7 +29,7 @@ function installId() {
     writeFileSync(file, id + "\n", { mode: 0o600 });
     return id;
 }
-function version() {
+export function version() {
     const pkg = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
     return JSON.parse(readFileSync(pkg, "utf8")).version;
 }

package/dist/update.js

@@ -0,0 +1,67 @@
+// Keeping Backstep current. As each Claude Code session starts, the mod asks
+// whether npm has a newer version; if so it asks the person, and an update
+// runs the new version's own setup, the same command a first install runs.
+// Off with BACKSTEP_UPDATE_CHECK=0.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homeDir } from "./store.js";
+import { version } from "./telemetry.js";
+const REGISTRY = process.env.BACKSTEP_REGISTRY ?? "https://registry.npmjs.org";
+const file = () => join(homeDir(), "settings.json");
+function settings() {
+    try {
+        return existsSync(file()) ? JSON.parse(readFileSync(file(), "utf8")) : {};
+    }
+    catch {
+        return {};
+    }
+}
+// 1.2.10 > 1.2.9; anything after a dash (a pre-release) counts as older than without.
+export function newer(a, b) {
+    const parse = (v) => {
+        const [main, pre] = v.split("-", 2);
+        return { nums: main.split(".").map((n) => Number(n) || 0), pre: pre ?? null };
+    };
+    const x = parse(a);
+    const y = parse(b);
+    for (let i = 0; i < 3; i++)
+        if ((x.nums[i] ?? 0) !== (y.nums[i] ?? 0))
+            return (x.nums[i] ?? 0) > (y.nums[i] ?? 0);
+    return x.pre === null && y.pre !== null;
+}
+// Never slow: a session doesn't wait more than a few seconds on npm.
+export async function checkUpdate() {
+    const current = version();
+    if (/^(0|false|off|no)$/i.test(process.env.BACKSTEP_UPDATE_CHECK ?? ""))
+        return { current, latest: null, available: false };
+    let latest = null;
+    try {
+        const r = await fetch(`${REGISTRY}/backstep/latest`, { signal: AbortSignal.timeout(4000) });
+        if (r.ok)
+            latest = (await r.json()).version ?? null;
+    }
+    catch {
+        // offline: nothing to offer
+    }
+    const available = latest !== null && newer(latest, current) && settings().skipVersion !== latest;
+    return { current, latest, available };
+}
+export function skipVersion(v) {
+    mkdirSync(homeDir(), { recursive: true });
+    writeFileSync(file(), JSON.stringify({ ...settings(), skipVersion: v }, null, 2) + "\n");
+}
+// The new version's setup puts its own copy in place, points Claude Code's mod
+// at it and re-wraps servers, exactly as a fresh install would.
+export function runUpdate(v) {
+    const r = spawnSync("npx", ["-y", `backstep@${v}`, "setup"], {
+        encoding: "utf8",
+        timeout: 5 * 60 * 1000,
+        env: { ...process.env, NO_COLOR: "1", BACKSTEP_TELEMETRY: "0" },
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (r.status === 0)
+        return { ok: true, detail: `updated to ${v}` };
+    const why = `${r.stderr ?? ""}${r.stdout ?? ""}`.trim().split("\n").filter(Boolean).at(-1) ?? "npx failed";
+    return { ok: false, detail: why.replace(/^backstep: /, "") };
+}

package/mod/hooks/register.test.tsx

@@ -172,16 +172,23 @@ test('servers added since setup are wrapped as a session starts', { options: { c
     tools.push(e.name)
     return { value: { tool: `mcp__backstep__${e.name}` } }
   })
+  const logs: string[] = []
+  on('ui.log', (_, e) => {
+    logs.push(e.text)
+    return { value: undefined }
+  })
   on('session.start', (_, e) => ({ cwd: e.cwd }))
 
   await $.session.start({ cwd: '/repo', surface: 'terminal', hasPerson: true } as never)
   await new Promise((r) => setTimeout(r, 10))
   expect(tools).toEqual(['connect'])
+  expect(logs[0]).toContain('Backstep connected')
   expect(runs).toEqual([
     ['node', '--disable-warning=ExperimentalWarning', CLI, 'wrap-servers', '--project', '/repo', '--json'],
     ['node', '--disable-warning=ExperimentalWarning', CLI, 'connect', '--dir', '/repo', '--json', '--auto'],
     ['node', '--disable-warning=ExperimentalWarning', CLI, 'ping'],
     ['node', '--disable-warning=ExperimentalWarning', CLI, 'status', '--quick', '--json', '--dir', '/repo'],
+    ['node', '--disable-warning=ExperimentalWarning', CLI, 'update-check'],
   ])
   expect(toasts.find((t) => t.includes('linear is now behind Backstep'))).toBeTruthy()
   // Supabase gets its own question, and only in a project that uses it.
@@ -430,3 +437,50 @@ test('after undoing a turn that pushed, Backstep asks and pushes the undo', { op
   expect((await ui.find({ type: 'Text', text: /Rewound/ }))?.text).not.toContain("couldn't be undone")
   await ui.unmount()
 })
+
+function updates(on: On, answer: string) {
+  const runs: string[][] = []
+  const toasts: string[] = []
+  const asked: string[] = []
+  on('process.run', (_, e) => {
+    runs.push([...e.argv])
+    const stdout = e.argv.includes('update-check')
+      ? JSON.stringify({ current: '0.1.2', latest: '0.2.0', available: true })
+      : e.argv.includes('update') && e.argv.includes('--json')
+        ? JSON.stringify({ ok: true, detail: 'updated to 0.2.0' })
+        : e.argv.includes('status')
+          ? JSON.stringify({ items: [], suggest: [] })
+          : '[]'
+    return { value: { exitCode: 0, stdout, stderr: '', isStdoutTruncated: false, isStderrTruncated: false } }
+  })
+  on('ui.toast', (_, e) => {
+    toasts.push(e.text)
+    return { value: undefined }
+  })
+  on('ui.log', () => ({ value: undefined }))
+  on('tool.register', (_, e) => ({ value: { tool: `mcp__backstep__${e.name}` } }))
+  on('tool.call', { tool: 'AskUserQuestion' }, (_, e) => {
+    const questions = (e as unknown as { questions: { question: string }[] }).questions
+    asked.push(questions[0].question)
+    return { result: { questions, answers: { [questions[0].question]: answer } } }
+  })
+  on('session.start', (_, e) => ({ cwd: e.cwd }))
+  return { runs, toasts, asked }
+}
+
+test('a newer version is offered as a session starts, and Update installs it', { options: { cli: CLI } }, async ($, on) => {
+  const { runs, toasts, asked } = updates(on, 'Update')
+  await $.session.start({ cwd: '/repo', surface: 'terminal', hasPerson: true } as never)
+  await settle()
+  expect(asked).toEqual(['Backstep 0.2.0 is out (you have 0.1.2). Update now?'])
+  expect(runs.some((r) => r.slice(3).join(' ') === 'update --version 0.2.0 --json')).toBe(true)
+  expect(toasts.at(-1)).toBe('Backstep updated to 0.2.0. Restart Claude Code to use it.')
+})
+
+test('Skip this version stops asking about it, and Not now changes nothing', { options: { cli: CLI } }, async ($, on) => {
+  const { runs } = updates(on, 'Skip this version')
+  await $.session.start({ cwd: '/repo', surface: 'terminal', hasPerson: true } as never)
+  await settle()
+  expect(runs.some((r) => r.slice(3).join(' ') === 'update --skip 0.2.0')).toBe(true)
+  expect(runs.some((r) => r.includes('--version'))).toBe(false)
+})

package/mod/hooks/register.tsx

@@ -298,7 +298,7 @@ async function checkCoverage($: EngineInterface, cwd: string) {
   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.service === 'supabase' && c.state === 'ask') await 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 {
@@ -352,6 +352,39 @@ async function askSupabase($: EngineInterface, cwd: string) {
   $.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 UPDATE = { yes: 'Update', later: 'Not now', skip: 'Skip this version' }
+
+// A newer Backstep on npm: asked as a session starts, installed only on a yes.
+async function offerUpdate($: EngineInterface) {
+  const ran = await $.process.run(backstep(['update-check']), { timeoutMs: 15_000 }).catch(() => null)
+  let u: { current?: string; latest?: string | null; available?: boolean } = {}
+  try {
+    u = JSON.parse(ran?.stdout || '{}') as typeof u
+  } catch {
+    return
+  }
+  if (!u.available || !u.latest) return
+  const answer = await $.ui
+    .ask(`Backstep ${u.latest} is out (you have ${u.current}). Update now?`, { header: 'Backstep', options: [UPDATE.yes, UPDATE.later, UPDATE.skip] })
+    .catch(() => null)
+  if (answer === UPDATE.skip) {
+    await $.process.run(backstep(['update', '--skip', u.latest])).catch(() => null)
+    return
+  }
+  if (answer !== UPDATE.yes) return
+  $.ui.toast(`Updating Backstep to ${u.latest}…`)
+  const done = await $.process
+    .run(backstep(['update', '--version', u.latest, '--json']), { timeoutMs: 300_000 })
+    .catch((err: unknown) => ({ exitCode: 1, stdout: '', stderr: err instanceof Error ? err.message : String(err) }))
+  let r: { ok: boolean; detail: string } = { ok: false, detail: (done.stderr || 'it failed').trim().split('\n').at(-1) ?? 'it failed' }
+  try {
+    r = JSON.parse(done.stdout) as typeof r
+  } catch {
+    // keep the error above
+  }
+  $.ui.toast(r.ok ? `Backstep ${r.detail}. Restart Claude Code to use it.` : `Backstep couldn't update: ${r.detail}. Try: npx backstep@latest setup`)
+}
+
 const CONNECT = 'mcp__backstep__connect'
 
 const CONNECT_TOOL = {
@@ -403,9 +436,12 @@ export const register: Register = (on, options) => {
   on('session.start', async ($, e, next) => {
     await $.tool.register(CONNECT_TOOL)
     const r = await next(e)
+    // Said first thing, so nobody has to wonder whether it's running.
+    $.ui.log("✓ Backstep connected · press ctrl+z to undo Claude's last turn")
     // In the background: a session never waits on either.
     void wrapNewServers($, e.cwd)
-    void checkCoverage($, e.cwd)
+    // One question at a time: Supabase first, then any update.
+    void checkCoverage($, e.cwd).then(() => offerUpdate($))
     void $.process.run(backstep(['ping'])).catch(() => null)
     return r
   })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backstep",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Undo for everything your agents touch: an MCP proxy that makes agent actions reversible.",
   "scripts": {
     "dev": "node src/cli.ts",