checkpointer 0.1.1 → 0.2.0

package/README.md

@@ -52,18 +52,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 +107,65 @@ 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 **JSDoc/comment description**, kind (function/method/constructor),
+  async flag, parameters, and `file:line`, with recursion and cycles flagged inline.
+
+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.