checkpointer 0.1.1 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # checkpointer
 
-> Git-isolated checkpoints that humans and AI agents share — save working states, revert anytime, ship a range as one clean commit.
+> Git-isolated checkpoints that humans and AI agents share — save working states, revert anytime, ship a range as one clean commit, and map your code's call graph in the browser.
 
 When you (or an AI agent) work through a long task, you want save points: a way to
 mark "this works", roll back when something breaks, and at the end turn all that
@@ -11,6 +11,7 @@ repo kept outside your project — so your real `git log` stays clean until you
 - **Isolated from your repo** — checkpoints live in `~/.checkpointer`, never in your project's `.git`. Nothing shows up in `git log` until you `ship`.
 - **Captures everything** — unlike editor undo, it snapshots the whole working tree, including files changed by scripts, formatters, and codemods.
 - **Ships to one commit** — bundle a range of checkpoints into a single commit on your branch, then push when you're ready.
+- **Maps your code** — `checkpointer graph` opens an interactive, searchable function call-graph of your TypeScript/JavaScript project in the browser, so you can see how functions reach each other before you change them. Fully offline.
 
 ## Install
 
@@ -52,18 +53,45 @@ git push                                        # ship never pushes — you do
 | `save [name]` | Snapshot the working tree (auto-names `cp-N` if no name) |
 | `list` (`ls`) | List all checkpoints |
 | `status` | Show how many checkpoints are waiting to be shipped |
+| `changed [id]` | Probe whether the working tree differs from a checkpoint (exit `100` if not) |
 | `show <id>` | Show a checkpoint's details and tracked files |
 | `diff <a> [b]` | Diff two checkpoints, or one checkpoint vs current files |
 | `restore <id>` | Reset the working tree to a checkpoint (auto-saves first) |
 | `tag <id> <status>` | Mark a checkpoint `working`, `wip`, or `broken` |
 | `ship` | Bundle unshipped checkpoints into one commit on your repo |
+| `graph` | Visualize the project's functions and call graph in your browser |
 | `info` | Show where checkpoints are stored and which paths are excluded |
 | `skill install` | Install the Claude Code skill so agents know how to use this |
 
 Reference any checkpoint by **name** (`login`), **sequence** (`#4`), or **short sha**.
-Add `--json` to any command for machine-readable output; on failure it prints
-`{"error": "...", "code": "..."}` to stdout and exits non-zero. Run `checkpointer
-<command> --help` for full options and examples.
+Run `checkpointer <command> --help` for full options and examples.
+
+### Machine-readable output (`--json`)
+
+Add `--json` to any command for a stable, versioned envelope on stdout:
+
+```jsonc
+// success
+{ "schema": "checkpointer/v1", "ok": true,  "data": { /* command payload */ } }
+// failure (also exits non-zero)
+{ "schema": "checkpointer/v1", "ok": false, "error": { "message": "...", "code": "..." } }
+```
+
+Branch on `ok` (and on the exit code) rather than parsing prose. Fields inside
+`data` are additive; `schema` only changes on a breaking envelope change.
+
+### Exit codes
+
+Commands exit `0` on success. On failure the exit code is stable and tells you
+*why*, so scripts and agents can react without parsing the message:
+
+| Code | Meaning | Examples |
+| --- | --- | --- |
+| `1` | generic / unexpected | a git plumbing failure |
+| `3` | environment not ready | not initialized, not a git repo, lock held, corrupt metadata |
+| `4` | bad input | no such checkpoint, duplicate name, invalid status, missing message |
+| `5` | safety refusal — a human decision is needed | shipping a `broken` checkpoint without `--force`; shipping onto a detached HEAD; shipping a checkpoint a restore set aside |
+| `6` | benign no-op — nothing to do | nothing unshipped, repo already matches the checkpoint |
 
 ### Key options
 
@@ -80,15 +108,70 @@ checkpointer ship --force -m "..."                     # include broken checkpoi
 
 - **Restore can't lose work.** Every `restore` first auto-saves your current state, so
   you can always restore that to undo. These auto checkpoints are marked and don't
-  count toward what gets shipped.
+  count toward what gets shipped. Restoring an earlier checkpoint never deletes the
+  later ones — they stay in `list` so you can jump straight back to them; they are only
+  "set aside" (marked under a divider) so a later `ship` won't bundle the line of work
+  you rolled away from.
+- **Ship follows the live line of work.** `ship` defaults to the latest checkpoint a
+  restore hasn't set aside, and refuses an explicit `--upto` on a set-aside one — so
+  after a rollback it always commits the tree you're actually on, never a stale or
+  abandoned snapshot. To ship set-aside content, `restore` it (or `save` your current
+  state) first, which makes it live again.
 - **Ship only adds a commit.** `ship` builds the commit from a checkpoint's snapshot
   using git plumbing — it never resets your working tree, so uncommitted edits and
   untracked files are left exactly as they were.
 - **Secrets stay put.** `.env`, `*.pem`, `*.key`, `secrets.*`, `node_modules`, and your
   `.git` are never snapshotted — so a restore never overwrites them. See `checkpointer
   info` for the full list; add your own patterns in the shown `ignore` file.
+- **Saving is idempotent.** A plain `save` with nothing changed reuses the latest
+  checkpoint instead of creating an empty duplicate, so saving often is cheap. Pass
+  `--allow-empty` (or a name/message/status) to force a checkpoint anyway.
+- **Nested git repos are skipped, not silently broken.** A submodule or accidental inner
+  repo can't be snapshotted faithfully, so checkpointer warns and skips it (listing it in
+  `nestedRepos` under `--json`) rather than recording a dangling pointer. The directory is
+  left on disk untouched; a restore simply won't recreate it.
 - **Nothing leaves your machine.** No telemetry. Checkpoints are local git objects.
 
+## Visualizing your code (`graph`)
+
+Debugging an unfamiliar codebase is easier when you can *see* how functions call
+each other. `checkpointer graph` parses your TypeScript/JavaScript project with the
+TypeScript compiler (so calls resolve accurately — methods, `this.`, and imports,
+not just name matches) and opens an interactive map in your browser:
+
+```bash
+checkpointer graph                  # analyze + serve on localhost + open the browser
+checkpointer graph --no-open        # just print the localhost URL
+checkpointer graph --out graph.html # write a standalone, shareable HTML file
+checkpointer graph --json           # emit the raw graph (nodes, edges, roots)
+checkpointer graph --root ../other  # analyze a different project
+```
+
+In the viewer you can:
+
+- **Read top-down** from each entrypoint (a "root" — a function nothing in the
+  project calls) and **click any function to expand what it calls**, drilling as deep
+  as you like.
+- **Search** any function by name or file; jump straight to it.
+- **Focus a function** to see its **ancestors** (everyone who reaches it, up to the
+  entrypoints) beside its **descendants** (everything it calls) — both expandable.
+- See each function's **full signature** with type-checker-resolved parameter and
+  return types — so you learn what it takes and returns even when there's no comment —
+  alongside its description, a **per-parameter table** (name, type, optional, JSDoc
+  `@param` prose when present), kind (function/method/constructor), async flag, and
+  `file:line`, with recursion and cycles flagged inline.
+- Hit **"view code"** on any function to read its source inline, embedded in the page —
+  nothing is fetched.
+
+The page is fully self-contained and offline — no CDN, no telemetry, the graph data is
+embedded inline. `--out` produces a single file you can commit or share. Analysis is
+read-only and never creates a checkpoint.
+
+Today `graph` analyzes **TypeScript/JavaScript** (`.ts`/`.tsx`/`.js`/`.jsx`/`.mjs`/`.cjs`),
+since the accurate call resolution comes from the TypeScript compiler; support for more
+languages is planned. In a project with no TS/JS sources it says so cleanly — the other
+commands (`save`/`restore`/`ship`) work in any repository regardless of language.
+
 ## Using it with AI agents
 
 `checkpointer` is just a CLI, so any agent that can run shell commands can use it.