checkpointer 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "checkpointer",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Git-isolated checkpoints that humans and AI agents share — save working states, revert anytime, ship a range as one clean commit.",
   "keywords": [
     "checkpoint",
@@ -32,19 +32,21 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
+    "pretest": "tsup",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
+    "smoke": "node scripts/smoke.mjs",
+    "prepublishOnly": "npm run build && npm run smoke"
   },
   "dependencies": {
     "commander": "^12.1.0",
-    "picocolors": "^1.1.1"
+    "picocolors": "^1.1.1",
+    "typescript": "^5.7.2"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "tsup": "^8.3.5",
-    "typescript": "^5.7.2",
     "vitest": "^2.1.8"
   }
 }

package/skills/checkpointer/SKILL.md

@@ -28,6 +28,10 @@ If `checkpointer` is not installed, run it through `npx checkpointer <command>`.
    ```bash
    checkpointer save --intent "why you are about to make this change"
    ```
+   To avoid piling up identical checkpoints, gate the save on a real change:
+   ```bash
+   checkpointer changed && checkpointer save --intent "..."   # exits 100 if nothing changed
+   ```
 2. **After reaching a known-good state** — tests pass, feature works:
    ```bash
    checkpointer save working-login --status working -m "login flow works end to end"
@@ -53,7 +57,15 @@ If `checkpointer` is not installed, run it through `npx checkpointer <command>`.
 
 ## Rules
 
+- A plain `save` with no changes is a no-op — it reuses the latest checkpoint instead of
+  piling up duplicates (the `--json` payload has `"noop": true`). Pass `--allow-empty`, or a
+  name/message/status, to force a new one. So saving proactively is cheap and safe.
 - Restoring is always safe: it auto-saves the current state first, so a restore can be undone.
+  It never deletes later checkpoints — they stay in `list` (under a "set aside" divider) and you
+  can `restore` straight back to them. Restoring only rewinds the working tree.
+- After a rollback, `ship` follows the live line of work: it targets the latest checkpoint a
+  restore hasn't set aside, and refuses (`abandoned_target`, exit 5) an explicit `--upto` on a
+  set-aside one. To ship set-aside content, `restore` it (or re-`save` the current state) first.
 - `ship` only adds a commit — it never overwrites the user's uncommitted or untracked work.
 - Never run `ship` without showing `status` or `--dry-run` output to the user first.
 - Don't `--force` past a `broken` checkpoint without telling the user why.
@@ -68,12 +80,33 @@ If `checkpointer` is not installed, run it through `npx checkpointer <command>`.
 | `checkpointer save [name]` | Snapshot the working tree |
 | `checkpointer list` | List checkpoints |
 | `checkpointer status` | Show how many checkpoints are unshipped |
+| `checkpointer changed [id]` | Is there anything new to save? (exit 0 = yes, 100 = no) |
 | `checkpointer show <id>` | Details + files in a checkpoint |
 | `checkpointer diff <a> [b]` | Diff two checkpoints, or one vs the working tree |
 | `checkpointer restore <id>` | Reset working tree to a checkpoint (auto-saves first) |
 | `checkpointer tag <id> <status>` | Mark working / wip / broken |
 | `checkpointer ship -m "msg"` | Bundle unshipped checkpoints into one commit |
+| `checkpointer graph --json` | Function call graph of the project (nodes/edges/roots) for understanding code |
 | `checkpointer info` | Show storage location and excluded paths (e.g. .env, *.key) |
 
-Add `--json` to any command for structured output. On failure with `--json`, the
-command prints `{"error": "...", "code": "..."}` to stdout and exits non-zero.
+To understand an unfamiliar codebase or trace how a function is reached before
+editing it, `checkpointer graph --json` returns the project's call graph: `nodes`
+(functions/methods with `file`, `line`, `description`, params) and `edges`
+(`{from, to}` by node id), plus `roots` (entrypoints). Resolved via the TypeScript
+compiler, so method and import calls are accurate. For a human, `checkpointer graph`
+opens an interactive, searchable tree in the browser.
+
+Add `--json` to any command for a stable, versioned envelope on stdout:
+
+- success — `{"schema":"checkpointer/v1","ok":true,"data":{...}}`
+- failure — `{"schema":"checkpointer/v1","ok":false,"error":{"message":"...","code":"..."}}` (exits non-zero)
+
+Branch on the `ok` field, not on output text. Fields inside `data` are additive.
+
+Exit codes are stable, so you can react without parsing the message:
+
+- `0` success · `1` generic/unexpected
+- `3` environment not ready (not initialized, not a 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 (e.g. a `broken` checkpoint, a detached HEAD, or a set-aside checkpoint blocks ship)
+- `6` benign no-op — nothing to do (nothing unshipped; repo already matches)