Add site checkpoints: whole-site (files + database) save points with rollback

[shaunandrews]

Related issues

• None yet — this is an exploratory proof of concept for whole-site checkpoints (files + database). A companion issue write-up can follow if the direction holds.

How AI was used in this PR

Built end-to-end with Claude Code from a reviewed plan: research passes over the codebase and prior art (Cline, Replit, DDEV, Jetpack Backup), an adversarial design review, four validation spikes run against real sites before any implementation, then implementation with unit tests and a scripted Playwright pass over the packaged app for light/dark visual verification. All code was verified by running it: full create → mutate → diff → restore round trips on live sites of both runtimes.

Proposed Changes

When the agent (or you) makes big changes to a site, there's currently no way back. This adds checkpoints: capture the entire state of a site — every file and the SQLite database — at "known good" moments, and roll back to any of them later. This closes the gap that desktop AI coding tools document as a limitation: Cursor/Claude Code/Cline checkpoint only the files their own edit tools touch; Studio owns the whole site directory and its database, so it can checkpoint everything, including wp-cli side effects and uploads.

How it behaves:

• Users get a Checkpoints tab in site settings: create with a label ("mark as good"), see a timeline (manual / agent / auto / safety), restore, delete. Restore always captures a safety checkpoint of the current state first, so a restore can itself be undone — rollback is never one-way.
• The agent gets checkpoint_create/list/restore/diff tools, and destructive tools (wp_cli, imports, pulls, scaffolding, data liberation) automatically capture a checkpoint before running (debounced to one per 2 minutes). Checkpoint chips render in the chat transcript with a restore affordance.
• The CLI gets studio checkpoint create|list|restore|delete|diff. The diff answers "what changed since things last worked": files added/modified/deleted plus per-table row-count deltas and changed wp_options names.

Storage is a content-addressed store per site under ~/.studio/checkpoints/ — git-like dedupe without a git dependency (Studio ships to machines without git). Unchanged files cost nothing after the first checkpoint: measured on a ~96 MB site, the first checkpoint stored 30 MB compressed in 3.5 s, the next one 58 KB in 0.8 s. Restores are transactional about the database: while a site runs, capture executes VACUUM INTO inside the site's own PHP runtime, and every artifact is integrity-verified host-side with retries (the validation spike reproduced a torn read on the Playground runtime under concurrent writes — the daemon runs wp-cli in parallel WASM instances whose SQLite locks don't coordinate — so verification is load-bearing, not paranoia).

Trade-offs and deliberate v1 boundaries, so reviewers know what they're evaluating: restore is always files+database together (files-only invites plugin/DB mismatches); reprint-pulled sites are refused with a clear message; retention is fixed policy (manual/agent kept forever, last 10 auto, last 5 safety) with no settings UI yet; create/restore progress in the desktop UI is pending/complete rather than granular; a crash-interrupted restore is recoverable via the journal from the CLI but has no desktop dialog yet.

This spans a new architectural boundary (CLI engine + agent tool decorator + local-server routes + desktop IPC + UI), which is why it's a draft PoC rather than a merge-ready change.

Testing Instructions

1. npm install && npm run cli:build
2. CLI round trip: node apps/cli/dist/cli/main.mjs checkpoint create --path ~/Studio/<site> --label "known good", change something (studio wp option update blogname broken, add/delete a plugin file), then checkpoint diff <id> and checkpoint restore <id> — the site should come back exactly, running or stopped, with an undo hint pointing at the safety checkpoint.
3. Desktop: npm start, open a site → Settings → Checkpoints. Create, restore (note the confirm dialog copy), delete.
4. Agent: ask the agent to run a destructive wp_cli command and watch the auto-checkpoint chip appear in the transcript; try checkpoint_diff ("what changed since the last checkpoint?").
5. Unit tests: npm test -- apps/cli/lib/checkpoints apps/cli/ai/tools/auto-checkpoint.

UI was visually verified in light and dark via a scripted run of the packaged app; a second pair of human eyes on the timeline, dialogs, and chips is still welcome.

Pre-merge Checklist

• Typecheck, lint, and unit tests pass (npm run typecheck, npx eslint, npm test)
• New/changed UI verified in light and dark color schemes
• e2e suite run
• Team alignment on architecture (this is a draft PoC)

🤖 Generated with Claude Code