checkpointer 0.1.1 → 0.2.1

package/dist/cli.js

@@ -5,6 +5,8 @@ import { Command } from "commander";
 import pc3 from "picocolors";
 
 // src/actions.ts
+import { writeFileSync as writeFileSync4 } from "fs";
+import { resolve } from "path";
 import pc2 from "picocolors";
 
 // src/core/store.ts
@@ -42,8 +44,37 @@ var CheckpointerError = class extends Error {
 function fail(message, code) {
   throw new CheckpointerError(message, code);
 }
+var GENERIC_EXIT = 1;
+var EXIT_CODES = {
+  // 3 — environment not ready
+  not_initialized: 3,
+  not_a_repo: 3,
+  lock_held: 3,
+  corrupt_metadata: 3,
+  unsupported_meta_version: 3,
+  skill_missing: 3,
+  // 4 — bad input
+  no_match: 4,
+  name_taken: 4,
+  invalid_status: 4,
+  missing_message: 4,
+  auto_target: 4,
+  bad_path: 4,
+  // 5 — safety refusal
+  broken_refusal: 5,
+  detached_head: 5,
+  abandoned_target: 5,
+  // 6 — benign no-op
+  nothing_to_ship: 6,
+  nothing_to_commit: 6,
+  no_sources: 6
+};
+function exitCodeFor(code) {
+  return EXIT_CODES[code] ?? GENERIC_EXIT;
+}
 
 // src/core/git.ts
+var EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 var IDENTITY = [
   "-c",
   "user.name=checkpointer",
@@ -82,6 +113,21 @@ var ShadowGit = class {
   stageAll() {
     this.capture(["add", "-A"], "stage");
   }
+  // Paths staged as git submodule links (mode 160000). `git add -A` records a
+  // gitlink for any nested repo, but the shadow store never holds that repo's
+  // objects — so a snapshot would be a dangling pointer and a restore would
+  // leave the directory empty. Callers detect these to warn and drop them.
+  stagedGitlinks() {
+    const out = this.capture(["ls-files", "-s"], "ls-files");
+    if (!out) return [];
+    return out.split("\n").filter((line) => line.startsWith("160000 ")).map((line) => line.split("	").slice(1).join("	")).filter(Boolean);
+  }
+  // Drop paths from the index without touching the working tree, so the
+  // recorded tree contains neither a populated copy nor a dangling gitlink.
+  unstage(paths) {
+    if (!paths.length) return;
+    this.capture(["rm", "--cached", "-f", "-q", "--ignore-unmatch", "--", ...paths], "rm");
+  }
   commit(message) {
     const args = [...IDENTITY, "commit", "-q", "--allow-empty", "-m", message];
     const result = this.run(args);
@@ -109,6 +155,18 @@ var ShadowGit = class {
     const out = this.capture(["ls-tree", "-r", "--name-only", sha], "ls-tree");
     return out ? out.split("\n") : [];
   }
+  // Paths whose staged content differs from the given commit/tree. Call after
+  // stageAll() so the index reflects the working tree (excludes already
+  // applied), then this never reports excluded files like .env.
+  changedFiles(sha) {
+    const out = this.capture(["diff-index", "--cached", "--name-only", sha], "diff-index");
+    return out ? out.split("\n") : [];
+  }
+  // The tree object the current index would commit to. Lets callers compare
+  // working-tree state to a checkpoint without making a commit.
+  writeTree() {
+    return this.capture(["write-tree"], "write-tree");
+  }
   diffStat(from, to) {
     return this.capture(["diff", "--stat", from, to], "diff");
   }
@@ -132,11 +190,17 @@ function read(file, root) {
   try {
     parsed = JSON.parse(readFileSync(file, "utf8"));
   } catch {
-    fail(`checkpoint metadata at ${file} is corrupt (invalid JSON)`);
+    fail(`checkpoint metadata at ${file} is corrupt (invalid JSON)`, "corrupt_metadata");
   }
   const data = parsed;
+  if (typeof data?.version === "number" && data.version > 1) {
+    fail(
+      `checkpoint metadata at ${file} was written by a newer checkpointer (schema v${data.version}) \u2014 upgrade checkpointer`,
+      "unsupported_meta_version"
+    );
+  }
   if (data?.version !== 1 || !Array.isArray(data.checkpoints) || typeof data.shippedSeq !== "number") {
-    fail(`checkpoint metadata at ${file} is invalid or from an unsupported version`);
+    fail(`checkpoint metadata at ${file} is invalid or unreadable`, "corrupt_metadata");
   }
   return data;
 }
@@ -362,7 +426,10 @@ function withLock(file, fn) {
           continue;
         }
         if (Date.now() > deadline) {
-          fail("another checkpointer operation is in progress \u2014 try again in a moment");
+          fail(
+            `another checkpointer operation is in progress (lock: ${file}) \u2014 try again in a moment`,
+            "lock_held"
+          );
         }
         sleep(RETRY_MS);
       }
@@ -418,8 +485,15 @@ var Store = class _Store {
     return withLock(this.paths.lockFile, () => {
       this.meta.reload();
       writeExcludes(this.paths);
-      const seq = this.meta.nextSeq();
+      this.git.stageAll();
+      const nestedRepos = this.git.stagedGitlinks();
+      if (nestedRepos.length) this.git.unstage(nestedRepos);
       const auto = input.auto ?? false;
+      const latest = this.meta.latest();
+      if (!auto && !input.allowEmpty && input.restoredToSeq === void 0 && input.name === void 0 && input.message === void 0 && input.intent === null && latest && !latest.auto && input.status === latest.status && this.git.writeTree() === this.git.treeOf(latest.sha)) {
+        return { ...latest, noop: true, ...nestedRepos.length ? { nestedRepos } : {} };
+      }
+      const seq = this.meta.nextSeq();
       let name;
       if (input.name === void 0) {
         name = this.meta.uniqueName(`cp-${seq}`);
@@ -431,7 +505,6 @@ var Store = class _Store {
         }
         name = input.name;
       }
-      this.git.stageAll();
       const message = input.message ?? name;
       const sha = this.git.commit(`[${seq}] ${name}: ${message}`);
       const checkpoint = {
@@ -449,9 +522,21 @@ var Store = class _Store {
         ...input.restoredToSeq !== void 0 ? { restoredToSeq: input.restoredToSeq } : {}
       };
       this.meta.add(checkpoint);
-      return checkpoint;
+      return nestedRepos.length ? { ...checkpoint, nestedRepos } : checkpoint;
     });
   }
+  // Whether the working tree differs from a checkpoint, without committing.
+  // Defaults to the latest checkpoint of any kind, so the answer predicts
+  // whether `save` would create a new checkpoint or be a no-op. Read-only:
+  // stages into the shadow index (applying excludes) but writes no commit.
+  changed(ref) {
+    const against = ref ? this.meta.require(ref) : this.meta.latest();
+    this.git.stageAll();
+    const nested = this.git.stagedGitlinks();
+    if (nested.length) this.git.unstage(nested);
+    const files = against ? this.git.changedFiles(against.sha) : this.git.changedFiles(EMPTY_TREE);
+    return { changed: files.length > 0, against, files };
+  }
   setStatus(seq, status2) {
     withLock(this.paths.lockFile, () => {
       this.meta.reload();
@@ -485,24 +570,41 @@ function resolveIdentity(root, overrides = {}) {
   const author = overrides.author ?? process.env.CHECKPOINTER_AUTHOR ?? gitUser(root) ?? (agent ? agent : "you");
   return { author, agent, session, intent };
 }
-function gitUser(root) {
-  const result = run("git", ["config", "user.name"], { cwd: root });
-  const name = result.stdout.trim();
-  return result.status === 0 && name ? name : null;
+function gitUserName(root) {
+  return gitConfig(root, "user.name");
+}
+function gitUserEmail(root) {
+  return gitConfig(root, "user.email");
 }
+function gitConfig(root, key) {
+  const result = run("git", ["config", key], { cwd: root });
+  const value = result.stdout.trim();
+  return result.status === 0 && value ? value : null;
+}
+var gitUser = gitUserName;
 
 // src/core/ship.ts
 function planShip(store, uptoRef) {
-  const upto = uptoRef ? store.meta.require(uptoRef) : latestOrFail(store);
+  const upto = uptoRef ? store.meta.require(uptoRef) : latestLiveOrFail(store);
   if (upto.auto) {
     fail(`'${upto.name}' is an auto safety checkpoint \u2014 ship to a manual checkpoint instead`, "auto_target");
   }
+  if (store.meta.isAbandoned(upto.seq)) {
+    fail(
+      `'${upto.name}' was set aside by a restore \u2014 it is not part of the current line of work.
+Restore it first if you want to ship it, or ship a live checkpoint instead.`,
+      "abandoned_target"
+    );
+  }
   const all = store.meta.all();
   const shippedSeq = store.meta.shippedSeq();
   const from = all.find((cp) => cp.seq === shippedSeq) ?? null;
   const included = all.filter(
     (cp) => cp.seq > shippedSeq && cp.seq <= upto.seq && !cp.auto && !store.meta.isAbandoned(cp.seq)
   );
+  if (!included.length) {
+    fail(`nothing to ship \u2014 no unshipped checkpoints up to ${upto.name}`, "nothing_to_ship");
+  }
   return {
     upto,
     from,
@@ -518,10 +620,19 @@ function executeShip(store, plan, message, author) {
       fail(`nothing to ship \u2014 no unshipped checkpoints up to ${plan.upto.name}`, "nothing_to_ship");
     }
     const root = store.paths.root;
+    const parent = run("git", ["rev-parse", "--verify", "-q", "HEAD"], { cwd: root }).stdout.trim();
+    if (parent) {
+      const onBranch = run("git", ["symbolic-ref", "-q", "HEAD"], { cwd: root }).status === 0;
+      if (!onBranch) {
+        fail(
+          "HEAD is detached \u2014 checkpointer won't ship here, the commit could be lost on checkout.\nCheck out a branch first (e.g. 'git switch -c my-feature'), then ship.",
+          "detached_head"
+        );
+      }
+    }
     const fetch = run("git", ["fetch", "--no-tags", "-q", store.git.path, "refs/heads/checkpoints"], { cwd: root });
     if (fetch.status !== 0) fail(`could not read checkpoints into the repo: ${fetch.stderr.trim()}`);
     const tree = store.git.treeOf(plan.upto.sha);
-    const parent = run("git", ["rev-parse", "--verify", "-q", "HEAD"], { cwd: root }).stdout.trim();
     if (parent) {
       const headTree = run("git", ["rev-parse", "HEAD^{tree}"], { cwd: root }).stdout.trim();
       if (headTree === tree) {
@@ -530,10 +641,17 @@ function executeShip(store, plan, message, author) {
     }
     const args = ["commit-tree", tree, "-m", message];
     if (parent) args.push("-p", parent);
-    const built = run("git", args, {
-      cwd: root,
-      env: { ...process.env, GIT_AUTHOR_NAME: author, GIT_COMMITTER_NAME: author }
-    });
+    const env = {
+      ...process.env,
+      GIT_AUTHOR_NAME: author,
+      GIT_COMMITTER_NAME: author
+    };
+    const isHuman = author === gitUserName(root) && gitUserEmail(root) !== null;
+    if (!isHuman) {
+      env.GIT_AUTHOR_EMAIL = "checkpointer@local";
+      env.GIT_COMMITTER_EMAIL = "checkpointer@local";
+    }
+    const built = run("git", args, { cwd: root, env });
     if (built.status !== 0) fail(`git commit-tree failed: ${built.stderr.trim()}`);
     const commit = built.stdout.trim();
     const update = run("git", ["update-ref", "HEAD", commit], { cwd: root });
@@ -543,10 +661,350 @@ function executeShip(store, plan, message, author) {
     return { commit, message };
   });
 }
-function latestOrFail(store) {
-  const latest = store.meta.latestManual();
-  if (!latest) fail("no checkpoints to ship \u2014 run 'checkpointer save' first", "nothing_to_ship");
-  return latest;
+function latestLiveOrFail(store) {
+  const live = [...store.meta.all()].reverse().find((cp) => !cp.auto && !store.meta.isAbandoned(cp.seq));
+  if (!live) fail("no checkpoints to ship \u2014 run 'checkpointer save' first", "nothing_to_ship");
+  return live;
+}
+
+// src/core/analyze.ts
+import { existsSync as existsSync4, readdirSync } from "fs";
+import { join as join3, relative, sep } from "path";
+import ts from "typescript";
+var SOURCE_EXTS = /* @__PURE__ */ new Set([".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"]);
+var SKIP_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  ".next",
+  ".nuxt",
+  ".cache",
+  "vendor"
+]);
+function scanSources(root) {
+  const found = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true, encoding: "utf8" });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = join3(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name) || entry.name.startsWith(".")) continue;
+        walk(full);
+      } else if (entry.isFile()) {
+        if (entry.name.endsWith(".d.ts")) continue;
+        const dot = entry.name.lastIndexOf(".");
+        if (dot >= 0 && SOURCE_EXTS.has(entry.name.slice(dot))) found.push(full);
+      }
+    }
+  };
+  walk(root);
+  return found;
+}
+function collectFiles(root) {
+  const configPath = join3(root, "tsconfig.json");
+  if (existsSync4(configPath)) {
+    const config = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (!config.error) {
+      const parsed = ts.parseJsonConfigFileContent(config.config, ts.sys, root);
+      if (parsed.fileNames.length) {
+        return { files: parsed.fileNames, options: { ...parsed.options, allowJs: true, noEmit: true } };
+      }
+    }
+  }
+  return {
+    files: scanSources(root),
+    options: { allowJs: true, noEmit: true, target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext }
+  };
+}
+function rel(root, file) {
+  return relative(root, file).split(sep).join("/");
+}
+function isFunctionLike(node) {
+  return ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node) || ts.isConstructorDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isGetAccessor(node) || ts.isSetAccessor(node);
+}
+function describeCallable(node) {
+  if (ts.isFunctionDeclaration(node)) {
+    return node.name ? { name: node.name.text, kind: "function", commentNode: node } : null;
+  }
+  if (ts.isConstructorDeclaration(node)) {
+    const cls = node.parent;
+    const clsName = ts.isClassLike(cls) && cls.name ? cls.name.text : "(anonymous class)";
+    return { name: `${clsName}.constructor`, kind: "constructor", commentNode: node };
+  }
+  if (ts.isMethodDeclaration(node) || ts.isGetAccessor(node) || ts.isSetAccessor(node)) {
+    const cls = node.parent;
+    const clsName = ts.isClassLike(cls) && cls.name ? cls.name.text : "";
+    const member = node.name.getText();
+    return { name: clsName ? `${clsName}.${member}` : member, kind: "method", commentNode: node };
+  }
+  const parent = node.parent;
+  if (ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)) {
+    const stmt = parent.parent.parent;
+    return { name: parent.name.text, kind: "function", commentNode: ts.isVariableStatement(stmt) ? stmt : node };
+  }
+  if ((ts.isPropertyAssignment(parent) || ts.isPropertyDeclaration(parent)) && (ts.isIdentifier(parent.name) || ts.isStringLiteral(parent.name))) {
+    const member = parent.name.text;
+    if (ts.isPropertyDeclaration(parent) && ts.isClassLike(parent.parent) && parent.parent.name) {
+      return { name: `${parent.parent.name.text}.${member}`, kind: "method", commentNode: parent };
+    }
+    return { name: member, kind: "function", commentNode: parent };
+  }
+  return null;
+}
+function extractDescription(commentNode, sf) {
+  const full = sf.getFullText();
+  const ranges = ts.getLeadingCommentRanges(full, commentNode.getFullStart());
+  if (!ranges?.length) return "";
+  const tail = full.slice(ranges[ranges.length - 1].end, commentNode.getStart());
+  if ((tail.match(/\n/g) ?? []).length > 1) return "";
+  const group = [ranges[ranges.length - 1]];
+  for (let i = ranges.length - 2; i >= 0; i--) {
+    const gap = full.slice(ranges[i].end, ranges[i + 1].pos);
+    if ((gap.match(/\n/g) ?? []).length > 1) break;
+    group.unshift(ranges[i]);
+  }
+  const raw = group.map((r) => full.slice(r.pos, r.end)).join("\n");
+  const cleaned = raw.split("\n").map(
+    (line) => line.replace(/^\s*\/\*\*?/, "").replace(/\*\/\s*$/, "").replace(/^\s*\*\s?/, "").replace(/^\s*\/\/\s?/, "").trimEnd()
+  ).join("\n").trim();
+  const summary = cleaned.split("\n").filter((line) => !line.trimStart().startsWith("@")).join(" ").replace(/\s+/g, " ").trim();
+  return summary.length > 280 ? summary.slice(0, 277) + "\u2026" : summary;
+}
+function jsdocTags(node) {
+  const params = /* @__PURE__ */ new Map();
+  let returns = "";
+  for (const tag2 of ts.getJSDocTags(node)) {
+    const text = typeof tag2.comment === "string" ? tag2.comment : ts.getTextOfJSDocComment(tag2.comment) ?? "";
+    if (ts.isJSDocParameterTag(tag2)) {
+      params.set(tag2.name.getText(), text.replace(/^[-–\s]+/, "").trim());
+    } else if (tag2.tagName.text === "returns" || tag2.tagName.text === "return") {
+      returns = text.replace(/^[-–\s]+/, "").trim();
+    }
+  }
+  return { params, returns };
+}
+function clampType(t) {
+  const flat = t.replace(/\s+/g, " ").trim();
+  return flat.length > 80 ? flat.slice(0, 77) + "\u2026" : flat;
+}
+function signatureOf(node, name, checker) {
+  const docs = jsdocTags(node);
+  const params = node.parameters.map((p) => {
+    const pname = p.name.getText();
+    let type = "";
+    if (p.type) {
+      type = p.type.getText();
+    } else {
+      try {
+        type = checker.typeToString(checker.getTypeAtLocation(p));
+      } catch {
+        type = "";
+      }
+    }
+    return {
+      name: pname,
+      type: clampType(type),
+      optional: !!p.questionToken || !!p.initializer || !!p.dotDotDotToken,
+      doc: docs.params.get(pname.replace(/[.{}[\]]/g, "").split(/[,:]/)[0].trim()) ?? docs.params.get(pname) ?? ""
+    };
+  });
+  let returns = "";
+  try {
+    const sig = checker.getSignatureFromDeclaration(node);
+    if (sig) returns = clampType(checker.typeToString(checker.getReturnTypeOfSignature(sig)));
+  } catch {
+    returns = "";
+  }
+  if (!returns && node.type) returns = clampType(node.type.getText());
+  const paramStr = params.map((p) => `${p.name}${p.optional ? "?" : ""}: ${p.type || "any"}`).join(", ");
+  const signature = `${name}(${paramStr})${returns ? `: ${returns}` : ""}`;
+  return { params, returns, signature };
+}
+function sourceOf(node, sf) {
+  const text = node.getText(sf);
+  const MAX = 8e3;
+  return text.length > MAX ? text.slice(0, MAX) + "\n/* \u2026 truncated \u2026 */" : text;
+}
+function resolveCallee(expr, checker, declToId) {
+  let symbol = checker.getSymbolAtLocation(expr.expression);
+  if (!symbol) return null;
+  if (symbol.flags & ts.SymbolFlags.Alias) {
+    try {
+      symbol = checker.getAliasedSymbol(symbol);
+    } catch {
+    }
+  }
+  for (const decl of symbol.declarations ?? []) {
+    const id = declToId.get(decl);
+    if (id) return id;
+  }
+  if (ts.isNewExpression(expr)) {
+    for (const decl of symbol.declarations ?? []) {
+      if (ts.isClassLike(decl)) {
+        for (const member of decl.members) {
+          if (ts.isConstructorDeclaration(member)) {
+            const id = declToId.get(member);
+            if (id) return id;
+          }
+        }
+      }
+    }
+  }
+  return null;
+}
+function analyzeProject(root) {
+  const { files, options } = collectFiles(root);
+  if (!files.length) {
+    fail(
+      `no TypeScript/JavaScript sources found under ${root} to graph. Today 'graph' analyzes TS/JS (it resolves calls via the TypeScript compiler); support for more languages is planned. Your other commands (save/restore/ship) work in any repo.`,
+      "no_sources"
+    );
+  }
+  const program2 = ts.createProgram(files, options);
+  const checker = program2.getTypeChecker();
+  const sources = program2.getSourceFiles().filter((sf) => !sf.isDeclarationFile && !sf.fileName.includes("node_modules"));
+  const nodes = /* @__PURE__ */ new Map();
+  const declToId = /* @__PURE__ */ new Map();
+  const moduleId = /* @__PURE__ */ new Map();
+  const makeId = (base) => {
+    if (!nodes.has(base)) return base;
+    for (let n = 2; ; n++) if (!nodes.has(`${base}~${n}`)) return `${base}~${n}`;
+  };
+  for (const sf of sources) {
+    const file = rel(root, sf.fileName);
+    moduleId.set(sf, `${file}::<module>`);
+    const discover = (node) => {
+      if (isFunctionLike(node)) {
+        const info2 = describeCallable(node);
+        if (info2) {
+          const { line } = sf.getLineAndCharacterOfPosition(node.getStart());
+          const id = makeId(`${file}#${info2.name}`);
+          const modifiers = ts.canHaveModifiers(node) ? ts.getCombinedModifierFlags(node) : ts.ModifierFlags.None;
+          const { params, returns, signature } = signatureOf(node, info2.name, checker);
+          nodes.set(id, {
+            id,
+            name: info2.name,
+            kind: info2.kind,
+            file,
+            line: line + 1,
+            description: extractDescription(info2.commentNode, sf),
+            signature,
+            exported: (modifiers & ts.ModifierFlags.Export) !== 0,
+            async: (modifiers & ts.ModifierFlags.Async) !== 0,
+            params,
+            returns,
+            returnDoc: jsdocTags(node).returns,
+            code: sourceOf(info2.commentNode, sf)
+          });
+          declToId.set(node, id);
+          if (ts.isVariableDeclaration(node.parent)) declToId.set(node.parent, id);
+          if (ts.isPropertyAssignment(node.parent) || ts.isPropertyDeclaration(node.parent)) {
+            declToId.set(node.parent, id);
+          }
+        }
+      }
+      ts.forEachChild(node, discover);
+    };
+    discover(sf);
+  }
+  const edgeSet = /* @__PURE__ */ new Set();
+  const edges = [];
+  const addEdge = (from, to) => {
+    if (from === to) return;
+    const key = `${from}\0${to}`;
+    if (edgeSet.has(key)) return;
+    edgeSet.add(key);
+    edges.push({ from, to });
+  };
+  for (const sf of sources) {
+    const visit = (node, scope) => {
+      if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+        const target = resolveCallee(node, checker, declToId);
+        if (target) addEdge(scope, target);
+      }
+      const nextScope = isFunctionLike(node) ? declToId.get(node) ?? scope : scope;
+      ts.forEachChild(node, (child) => visit(child, nextScope));
+    };
+    visit(sf, moduleId.get(sf));
+  }
+  const usedModules = new Set(edges.filter((e) => e.from.endsWith("::<module>")).map((e) => e.from));
+  for (const sf of sources) {
+    const id = moduleId.get(sf);
+    if (!usedModules.has(id)) continue;
+    const file = rel(root, sf.fileName);
+    nodes.set(id, {
+      id,
+      name: `${file} (top-level)`,
+      kind: "module",
+      file,
+      line: 1,
+      description: "Top-level module code \u2014 runs on import.",
+      signature: `${file} (top-level)`,
+      exported: false,
+      async: false,
+      params: [],
+      returns: "",
+      returnDoc: "",
+      code: ""
+    });
+  }
+  const liveEdges = edges.filter((e) => nodes.has(e.from) && nodes.has(e.to));
+  const hasIncoming = new Set(liveEdges.map((e) => e.to));
+  const roots = [...nodes.keys()].filter((id) => !hasIncoming.has(id)).sort();
+  return {
+    root,
+    fileCount: sources.length,
+    nodes: [...nodes.values()].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line),
+    edges: liveEdges,
+    roots
+  };
+}
+
+// src/core/graph-server.ts
+import { createServer } from "http";
+import { spawn } from "child_process";
+import { platform } from "os";
+function serveGraph(html, opts) {
+  return new Promise((resolve2, reject) => {
+    const server = createServer((req, res) => {
+      if (req.url === "/favicon.ico") {
+        res.writeHead(204).end();
+        return;
+      }
+      res.writeHead(200, {
+        "content-type": "text/html; charset=utf-8",
+        "cache-control": "no-store"
+      });
+      res.end(html);
+    });
+    server.on("error", reject);
+    server.listen(opts.port ?? 0, "127.0.0.1", () => {
+      const addr = server.address();
+      const port = typeof addr === "object" && addr ? addr.port : opts.port;
+      const url = `http://127.0.0.1:${port}/`;
+      if (opts.open !== false) openBrowser(url);
+      resolve2({ url, close: () => server.close() });
+    });
+  });
+}
+function openBrowser(url) {
+  const cmd = platform() === "darwin" ? "open" : platform() === "win32" ? "cmd" : "xdg-open";
+  const args = platform() === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
 }
 
 // src/ui/format.ts
@@ -587,8 +1045,319 @@ function heading(text) {
   return pc.bold(pc.underline(text));
 }
 var ok = (text) => pc.green(text);
+var warn = (text) => pc.yellow(text);
 var dim = (text) => pc.dim(text);
 
+// src/ui/graph-html.ts
+function renderGraphHtml(graph2, meta) {
+  const data = JSON.stringify(graph2).replace(/</g, "\\u003c").replace(/>/g, "\\u003e");
+  const projectName = graph2.root.split("/").filter(Boolean).at(-1) ?? "project";
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${escapeHtml(projectName)} \xB7 function graph</title>
+<style>${CSS}</style>
+</head>
+<body>
+<header>
+  <div class="title">
+    <span class="logo">\u2387</span>
+    <div>
+      <h1>${escapeHtml(projectName)}</h1>
+      <div class="sub"><span id="stat-fn">0</span> functions \xB7 <span id="stat-file">${graph2.fileCount}</span> files \xB7 <span id="stat-edge">0</span> calls \xB7 generated ${escapeHtml(meta.generatedAt)}</div>
+    </div>
+  </div>
+  <div class="search">
+    <input id="q" type="search" placeholder="Search a function\u2026  (\u2191\u2193 to move, \u21B5 to focus)" autocomplete="off" spellcheck="false" />
+    <div id="results"></div>
+  </div>
+</header>
+<main>
+  <section id="pane-tree" class="pane">
+    <div class="pane-head">
+      <h2>Call tree</h2>
+      <div class="pane-actions">
+        <button id="btn-expand">Expand all</button>
+        <button id="btn-collapse">Collapse</button>
+      </div>
+    </div>
+    <div class="hint">Top-down from entrypoints. Click a row to expand the functions it calls. \u25B8 has callees.</div>
+    <div id="tree" class="tree"></div>
+  </section>
+  <section id="pane-focus" class="pane hidden">
+    <div class="pane-head">
+      <h2 id="focus-title">Function</h2>
+      <button id="btn-back" title="Back to full tree">\u2715 close</button>
+    </div>
+    <div id="focus-meta" class="focus-meta"></div>
+    <div class="focus-cols">
+      <div class="focus-col">
+        <h3>Ancestors <span class="muted">\u2014 who reaches this (up to entrypoints)</span></h3>
+        <div id="ancestors" class="tree"></div>
+      </div>
+      <div class="focus-col">
+        <h3>Descendants <span class="muted">\u2014 what this calls</span></h3>
+        <div id="descendants" class="tree"></div>
+      </div>
+    </div>
+  </section>
+</main>
+<script id="graph-data" type="application/json">${data}</script>
+<script>${JS}</script>
+</body>
+</html>`;
+}
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+var CSS = `
+:root{
+  --bg:#0d1117;--panel:#161b22;--panel2:#1c2330;--line:#283040;--fg:#e6edf3;--muted:#8b949e;
+  --accent:#58a6ff;--green:#3fb950;--yellow:#d29922;--purple:#bc8cff;--row:#21262d;
+}
+*{box-sizing:border-box}
+body{margin:0;font:14px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;background:var(--bg);color:var(--fg)}
+header{position:sticky;top:0;z-index:5;background:linear-gradient(180deg,#0d1117,#0d1117f0);border-bottom:1px solid var(--line);padding:14px 20px;display:flex;gap:24px;align-items:flex-start;flex-wrap:wrap}
+.title{display:flex;gap:12px;align-items:center}
+.logo{font-size:26px;color:var(--accent)}
+h1{margin:0;font-size:17px;font-weight:600}
+.sub{color:var(--muted);font-size:12px}
+.search{position:relative;flex:1;min-width:280px;max-width:520px}
+#q{width:100%;padding:9px 12px;background:var(--panel2);border:1px solid var(--line);border-radius:8px;color:var(--fg);font:inherit;outline:none}
+#q:focus{border-color:var(--accent)}
+#results{position:absolute;top:42px;left:0;right:0;background:var(--panel);border:1px solid var(--line);border-radius:8px;max-height:340px;overflow:auto;display:none;box-shadow:0 12px 30px #0008;z-index:6}
+#results.open{display:block}
+.result{padding:7px 12px;cursor:pointer;border-bottom:1px solid var(--line);display:flex;justify-content:space-between;gap:10px}
+.result:last-child{border-bottom:none}
+.result.active,.result:hover{background:var(--row)}
+.result .nm{color:var(--accent)}
+.result .fl{color:var(--muted);font-size:11px;white-space:nowrap}
+main{padding:18px 20px;display:block}
+.pane{background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:14px 16px;margin-bottom:18px}
+.pane.hidden{display:none}
+.pane-head{display:flex;justify-content:space-between;align-items:center;margin-bottom:4px}
+.pane-head h2{margin:0;font-size:14px;font-weight:600}
+.pane-actions button,#btn-back{background:var(--panel2);border:1px solid var(--line);color:var(--fg);border-radius:6px;padding:5px 10px;cursor:pointer;font:inherit;font-size:12px}
+.pane-actions button:hover,#btn-back:hover{border-color:var(--accent)}
+.hint{color:var(--muted);font-size:12px;margin-bottom:10px}
+.tree{font-size:13px}
+.node{margin:0}
+.row{display:flex;align-items:baseline;gap:8px;padding:3px 6px;border-radius:6px;cursor:pointer;white-space:nowrap;overflow:hidden}
+.row:hover{background:var(--row)}
+.tw{width:14px;display:inline-block;color:var(--muted);flex:0 0 auto;text-align:center}
+.tw.leaf{color:transparent}
+.kind{font-size:10px;padding:1px 5px;border-radius:4px;flex:0 0 auto;text-transform:uppercase;letter-spacing:.04em}
+.kind.function{background:#1f6feb33;color:var(--accent)}
+.kind.method{background:#bc8cff22;color:var(--purple)}
+.kind.constructor{background:#d2992222;color:var(--yellow)}
+.kind.module{background:#8b949e22;color:var(--muted)}
+.nm{color:var(--fg);font-weight:500;flex:0 0 auto}
+.async{color:var(--yellow);font-size:11px;flex:0 0 auto}
+.desc{color:var(--muted);font-size:12px;overflow:hidden;text-overflow:ellipsis}
+.loc{color:#6e7681;font-size:11px;flex:0 0 auto;margin-left:auto;padding-left:12px}
+.children{margin-left:16px;border-left:1px solid var(--line);padding-left:4px}
+.children.collapsed{display:none}
+.cycle{color:var(--yellow);font-size:11px}
+.empty{color:var(--muted);font-style:italic;padding:6px}
+.focus-meta{background:var(--panel2);border:1px solid var(--line);border-radius:8px;padding:10px 12px;margin:8px 0 14px}
+.focus-meta .d{color:var(--muted);margin-top:6px}
+.fline{display:flex;align-items:center;gap:8px;flex-wrap:wrap}
+.sig{margin:8px 0 4px;padding:8px 10px;background:var(--bg);border:1px solid var(--line);border-radius:6px;color:var(--accent);font-size:12.5px;white-space:pre-wrap;word-break:break-word;overflow-x:auto}
+table.params{width:100%;border-collapse:collapse;margin:8px 0 4px;font-size:12px}
+table.params th{text-align:left;color:var(--muted);font-weight:500;padding:3px 8px;border-bottom:1px solid var(--line);text-transform:uppercase;letter-spacing:.04em;font-size:10px}
+table.params td{padding:3px 8px;border-bottom:1px solid var(--line);vertical-align:top}
+table.params tr:last-child td{border-bottom:none}
+.pn{color:var(--fg);white-space:nowrap}
+.pn .opt{color:var(--yellow)}
+.pt{color:var(--green);white-space:pre-wrap;word-break:break-word}
+.pd{color:var(--muted)}
+.ret{margin:6px 0 2px;font-size:12px}
+.ret .rk{color:var(--muted);text-transform:uppercase;letter-spacing:.04em;font-size:10px;margin-right:6px}
+.codewrap{margin-top:10px}
+.codebtn{background:var(--panel2);border:1px solid var(--line);color:var(--accent);border-radius:6px;padding:4px 10px;cursor:pointer;font:inherit;font-size:12px}
+.codebtn:hover{border-color:var(--accent)}
+.code{margin:8px 0 0;padding:10px 12px;background:var(--bg);border:1px solid var(--line);border-radius:6px;font-size:12px;line-height:1.45;overflow:auto;max-height:480px;white-space:pre;tab-size:2}
+.code.hidden{display:none}
+.focus-cols{display:grid;grid-template-columns:1fr 1fr;gap:16px}
+@media(max-width:820px){.focus-cols{grid-template-columns:1fr}}
+.focus-col h3{font-size:12px;font-weight:600;margin:0 0 8px;color:var(--fg)}
+.muted{color:var(--muted);font-weight:400}
+mark{background:#d2992255;color:#fff;border-radius:2px;padding:0 1px}
+`;
+var JS = String.raw`
+const GRAPH = JSON.parse(document.getElementById('graph-data').textContent);
+const byId = new Map(GRAPH.nodes.map(n => [n.id, n]));
+const callees = new Map(), callers = new Map();
+for (const n of GRAPH.nodes){ callees.set(n.id, []); callers.set(n.id, []); }
+for (const e of GRAPH.edges){
+  if (callees.has(e.from)) callees.get(e.from).push(e.to);
+  if (callers.has(e.to)) callers.get(e.to).push(e.from);
+}
+for (const m of [callees, callers]) for (const [k,v] of m) m.set(k, [...new Set(v)].sort((a,b)=>label(a).localeCompare(label(b))));
+
+document.getElementById('stat-fn').textContent = GRAPH.nodes.length;
+document.getElementById('stat-edge').textContent = GRAPH.edges.length;
+
+function label(id){ const n = byId.get(id); return n ? n.name : id; }
+function esc(s){ return s.replace(/[&<>"]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c])); }
+
+// Build one tree row. \`dir\` is 'down' (callees) or 'up' (callers). \`path\` is the
+// set of ancestor ids on the current branch, to detect and stop cycles.
+function makeNode(id, dir, path){
+  const n = byId.get(id);
+  const wrap = document.createElement('div'); wrap.className = 'node';
+  const row = document.createElement('div'); row.className = 'row';
+  const kids = (dir === 'down' ? callees : callers).get(id) || [];
+  const isCycle = path.has(id);
+  const hasKids = kids.length > 0 && !isCycle;
+
+  const tw = document.createElement('span');
+  tw.className = 'tw' + (hasKids ? '' : ' leaf');
+  tw.textContent = hasKids ? '▸' : '•';
+  row.appendChild(tw);
+
+  const kind = document.createElement('span'); kind.className = 'kind ' + n.kind; kind.textContent = n.kind; row.appendChild(kind);
+  const nm = document.createElement('span'); nm.className = 'nm'; nm.textContent = n.name; row.appendChild(nm);
+  if (n.async){ const a = document.createElement('span'); a.className='async'; a.textContent='async'; row.appendChild(a); }
+  if (isCycle){ const c=document.createElement('span'); c.className='cycle'; c.textContent='↻ cycle'; row.appendChild(c); }
+  if (n.description){ const d=document.createElement('span'); d.className='desc'; d.textContent='— '+n.description; row.appendChild(d); }
+  const loc=document.createElement('span'); loc.className='loc'; loc.textContent=n.file+':'+n.line; row.appendChild(loc);
+  wrap.appendChild(row);
+
+  const childBox = document.createElement('div'); childBox.className = 'children collapsed';
+  wrap.appendChild(childBox);
+  let built = false;
+  const toggle = () => {
+    if (!hasKids){ openFocus(id); return; }
+    if (!built){
+      const nextPath = new Set(path); nextPath.add(id);
+      for (const k of kids) childBox.appendChild(makeNode(k, dir, nextPath));
+      built = true;
+    }
+    const collapsed = childBox.classList.toggle('collapsed');
+    tw.textContent = collapsed ? '▸' : '▾';
+  };
+  row.addEventListener('click', (e) => { if (e.metaKey || e.ctrlKey){ openFocus(id); return; } toggle(); });
+  row._expand = () => { if (hasKids && childBox.classList.contains('collapsed')) toggle(); };
+  return wrap;
+}
+
+function renderTree(container, ids, dir){
+  container.innerHTML = '';
+  if (!ids.length){ container.innerHTML = '<div class="empty">none</div>'; return; }
+  for (const id of ids) container.appendChild(makeNode(id, dir, new Set()));
+}
+
+const treeEl = document.getElementById('tree');
+renderTree(treeEl, GRAPH.roots.length ? GRAPH.roots : GRAPH.nodes.map(n=>n.id), 'down');
+
+document.getElementById('btn-expand').onclick = () => {
+  // Expand a bounded number of levels to avoid runaway DOM on huge graphs.
+  for (let depth=0; depth<6; depth++){
+    treeEl.querySelectorAll('.row').forEach(r => r._expand && r._expand());
+  }
+};
+document.getElementById('btn-collapse').onclick = () => renderTree(treeEl, GRAPH.roots.length ? GRAPH.roots : GRAPH.nodes.map(n=>n.id), 'down');
+
+// ---- Focus view: ancestors + descendants of one function ----
+function openFocus(id){
+  const n = byId.get(id);
+  document.getElementById('pane-tree').classList.add('hidden');
+  const pane = document.getElementById('pane-focus'); pane.classList.remove('hidden');
+  document.getElementById('focus-title').textContent = n.name;
+  const m = document.getElementById('focus-meta');
+  const cers = (callers.get(id)||[]).length, cees = (callees.get(id)||[]).length;
+
+  let html = '<div class="fline"><span class="kind '+n.kind+'">'+n.kind+'</span>'
+    + (n.async?' <span class="async">async</span>':'')
+    + ' <span class="loc">'+esc(n.file)+':'+n.line+'</span>'
+    + ' · '+cers+' caller(s), '+cees+' callee(s)</div>';
+  if (n.signature) html += '<pre class="sig">'+esc(n.signature)+'</pre>';
+  html += n.description ? '<div class="d">'+esc(n.description)+'</div>'
+                        : '<div class="d muted">no written description — signature derived from types</div>';
+
+  // Parameter table: every param shows its resolved type; the doc column is
+  // filled from JSDoc @param when the author wrote one.
+  if (n.params && n.params.length){
+    html += '<table class="params"><thead><tr><th>param</th><th>type</th><th>notes</th></tr></thead><tbody>'
+      + n.params.map(p =>
+          '<tr><td class="pn">'+esc(p.name)+(p.optional?'<span class="opt">?</span>':'')+'</td>'
+          + '<td class="pt">'+esc(p.type||'any')+'</td>'
+          + '<td class="pd">'+(p.doc?esc(p.doc):'<span class="muted">—</span>')+'</td></tr>').join('')
+      + '</tbody></table>';
+  }
+  if (n.returns){
+    html += '<div class="ret"><span class="rk">returns</span> <span class="pt">'+esc(n.returns)+'</span>'
+      + (n.returnDoc?' <span class="pd">— '+esc(n.returnDoc)+'</span>':'')+'</div>';
+  }
+  // View-code toggle: reveals the function's own source, fetched from nothing —
+  // it's embedded in the graph data.
+  if (n.code){
+    html += '<div class="codewrap"><button id="btn-code" class="codebtn">▸ view code</button>'
+      + '<pre id="codeblock" class="code hidden"></pre></div>';
+  }
+  m.innerHTML = html;
+  if (n.code){
+    const btn = document.getElementById('btn-code'), block = document.getElementById('codeblock');
+    block.textContent = n.code;
+    btn.onclick = () => {
+      const hidden = block.classList.toggle('hidden');
+      btn.textContent = (hidden?'▸':'▾') + ' view code';
+    };
+  }
+  renderTree(document.getElementById('ancestors'), callers.get(id)||[], 'up');
+  renderTree(document.getElementById('descendants'), callees.get(id)||[], 'down');
+  window.scrollTo({top:0,behavior:'smooth'});
+}
+document.getElementById('btn-back').onclick = () => {
+  document.getElementById('pane-focus').classList.add('hidden');
+  document.getElementById('pane-tree').classList.remove('hidden');
+};
+
+// ---- Search ----
+const q = document.getElementById('q'), results = document.getElementById('results');
+let active = -1, hits = [];
+function search(term){
+  term = term.trim().toLowerCase();
+  if (!term){ results.classList.remove('open'); hits=[]; return; }
+  hits = GRAPH.nodes.filter(n => n.name.toLowerCase().includes(term) || n.file.toLowerCase().includes(term)).slice(0,50);
+  active = hits.length ? 0 : -1;
+  results.innerHTML = hits.map((n,i) =>
+    '<div class="result'+(i===active?' active':'')+'" data-id="'+esc(n.id)+'">'
+    + '<span class="nm">'+hl(n.name,term)+'</span><span class="fl">'+esc(n.file)+':'+n.line+'</span></div>').join('')
+    || '<div class="result"><span class="fl">no matches</span></div>';
+  results.classList.add('open');
+  results.querySelectorAll('.result[data-id]').forEach(el =>
+    el.onclick = () => { pick(el.getAttribute('data-id')); });
+}
+function hl(s,t){ const i=s.toLowerCase().indexOf(t); if(i<0)return esc(s); return esc(s.slice(0,i))+'<mark>'+esc(s.slice(i,i+t.length))+'</mark>'+esc(s.slice(i+t.length)); }
+function pick(id){ results.classList.remove('open'); q.value=''; openFocus(id); }
+q.addEventListener('input', () => search(q.value));
+q.addEventListener('keydown', (e) => {
+  if (!results.classList.contains('open')) return;
+  if (e.key==='ArrowDown'){ e.preventDefault(); active=Math.min(active+1,hits.length-1); search(q.value); }
+  else if (e.key==='ArrowUp'){ e.preventDefault(); active=Math.max(active-1,0); search(q.value); }
+  else if (e.key==='Enter'){ e.preventDefault(); if(hits[active]) pick(hits[active].id); }
+  else if (e.key==='Escape'){ results.classList.remove('open'); }
+});
+document.addEventListener('click', (e) => { if(!e.target.closest('.search')) results.classList.remove('open'); });
+document.addEventListener('keydown', (e) => { if(e.key==='/' && document.activeElement!==q){ e.preventDefault(); q.focus(); } });
+`;
+
+// src/ui/json.ts
+var SCHEMA = "checkpointer/v1";
+function okEnvelope(data) {
+  return { schema: SCHEMA, ok: true, data };
+}
+function errEnvelope(message, code) {
+  return { schema: SCHEMA, ok: false, error: { message, code } };
+}
+function writeJson(value) {
+  process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+}
+
 // src/actions.ts
 function parseStatus(value, fallback) {
   if (!value) return fallback;
@@ -599,11 +1368,18 @@ function parseStatus(value, fallback) {
 }
 function emit(json2, data, render) {
   if (json2) {
-    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+    writeJson(okEnvelope(data));
   } else {
     render();
   }
 }
+function warnNestedRepos(nested) {
+  if (!nested?.length) return;
+  process.stderr.write(
+    pc2.yellow(`warning: ${nested.length} nested git repo(s) cannot be checkpointed and were skipped:
+`) + nested.map((p) => `  - ${p}`).join("\n") + "\n" + pc2.dim("  their contents are left on disk untouched, but a restore will not recreate them\n")
+  );
+}
 function init(opts = {}) {
   const root = resolveRoot();
   requireGitRepo(root);
@@ -629,9 +1405,19 @@ function save(name, opts) {
     name,
     message: opts.message,
     status: parseStatus(opts.status, "wip"),
+    allowEmpty: opts.allowEmpty,
     ...id
   });
-  emit(opts.json ?? false, cp, () => {
+  const noop = cp.noop ?? false;
+  const nestedRepos = cp.nestedRepos ?? [];
+  warnNestedRepos(cp.nestedRepos);
+  emit(opts.json ?? false, { ...cp, noop, nestedRepos }, () => {
+    if (noop) {
+      console.log(
+        `${dim("\xB7 no change")} \u2014 reusing ${pc2.cyan(`#${cp.seq}`)} ${pc2.bold(cp.name)} ${dim("(pass --allow-empty to force)")}`
+      );
+      return;
+    }
     console.log(`${ok("\u2713 saved")} ${pc2.cyan(`#${cp.seq}`)} ${pc2.bold(cp.name)}  ${statusBadge(cp.status)}`);
     if (cp.intent) console.log(dim(`  intent: ${cp.intent}`));
   });
@@ -692,11 +1478,39 @@ function restore(ref, opts = {}) {
   const target = store.meta.require(ref);
   const id = resolveIdentity(store.paths.root);
   const safety = store.restore(target, id.author);
-  emit(opts.json ?? false, { restored: target.name, safety: safety.name }, () => {
+  warnNestedRepos(safety.nestedRepos);
+  emit(opts.json ?? false, { restored: target.name, safety: safety.name, nestedRepos: safety.nestedRepos ?? [] }, () => {
     console.log(`${ok("\u2713 restored")} working tree to ${pc2.bold(target.name)} ${pc2.cyan(`#${target.seq}`)}`);
     console.log(dim(`  current state was auto-saved as '${safety.name}' (#${safety.seq}) \u2014 restore it to undo`));
   });
 }
+function changed(ref, opts = {}) {
+  const root = resolveRoot();
+  requireGitRepo(root);
+  if (!Store.isInitialized(root)) {
+    emit(
+      opts.json ?? false,
+      { changed: true, against: null, fileCount: 0, files: [] },
+      () => console.log(`${warn("changed")} ${dim("(no checkpoints yet)")}`)
+    );
+    return;
+  }
+  const store = Store.open(root);
+  const { changed: changed2, against, files } = store.changed(ref);
+  emit(
+    opts.json ?? false,
+    { changed: changed2, against: against ? { seq: against.seq, name: against.name } : null, fileCount: files.length, files },
+    () => {
+      if (changed2) {
+        const since = against ? ` since ${pc2.bold(against.name)}` : "";
+        console.log(`${warn("changed")}${dim(since)} ${dim(`(${files.length} file(s))`)}`);
+      } else {
+        console.log(`${dim("unchanged")}${against ? dim(` since ${against.name}`) : ""}`);
+      }
+    }
+  );
+  if (!opts.json && !changed2) process.exitCode = 100;
+}
 function tag(ref, status2, opts = {}) {
   const store = Store.open();
   const cp = store.meta.require(ref);
@@ -776,6 +1590,33 @@ function renderPlan(plan) {
   console.log(dim("\n" + (plan.diffStat || "(no changes)")));
   console.log(dim('\nrun without --dry-run and with -m "message" to commit'));
 }
+async function graph(opts) {
+  const root = opts.root ? resolve(opts.root) : resolveRoot();
+  const g = analyzeProject(root);
+  if (opts.json) {
+    writeJson(okEnvelope(g));
+    return;
+  }
+  const html = renderGraphHtml(g, { generatedAt: (/* @__PURE__ */ new Date()).toISOString() });
+  if (opts.out) {
+    const file = resolve(opts.out);
+    writeFileSync4(file, html);
+    console.log(`${ok("\u2713 wrote graph")} ${pc2.bold(file)}`);
+    console.log(dim(`  ${g.nodes.length} function(s), ${g.edges.length} call edge(s) across ${g.fileCount} file(s)`));
+    console.log(dim(`  open it in any browser \u2014 it's fully self-contained`));
+    return;
+  }
+  const port = opts.port !== void 0 ? Number(opts.port) : void 0;
+  if (port !== void 0 && (!Number.isInteger(port) || port < 0 || port > 65535)) {
+    fail(`invalid --port '${opts.port}' (expected 0\u201365535)`, "bad_path");
+  }
+  const { url } = await serveGraph(html, { port, open: opts.open });
+  console.log(`${ok("\u2713 function graph")} for ${pc2.bold(root)}`);
+  console.log(`  ${g.nodes.length} function(s), ${g.edges.length} call edge(s) across ${g.fileCount} file(s)`);
+  console.log(`  serving at ${pc2.cyan(url)}`);
+  console.log(dim(opts.open === false ? "  open the URL in your browser" : "  opened in your browser"));
+  console.log(dim("  press Ctrl-C to stop"));
+}
 function info(opts = {}) {
   const root = resolveRoot();
   const store = Store.isInitialized(root) ? Store.open(root) : null;
@@ -796,28 +1637,28 @@ function info(opts = {}) {
 }
 
 // src/skill.ts
-import { cpSync, existsSync as existsSync4, mkdirSync as mkdirSync4, rmSync } from "fs";
+import { cpSync, existsSync as existsSync5, mkdirSync as mkdirSync4, rmSync } from "fs";
 import { homedir as homedir2 } from "os";
-import { dirname as dirname2, join as join3 } from "path";
+import { dirname as dirname2, join as join4 } from "path";
 import { fileURLToPath } from "url";
 function packagedSkillDir() {
   const here = dirname2(fileURLToPath(import.meta.url));
   const candidates = [
-    join3(here, "..", "skills", "checkpointer"),
-    join3(here, "..", "..", "skills", "checkpointer")
+    join4(here, "..", "skills", "checkpointer"),
+    join4(here, "..", "..", "skills", "checkpointer")
   ];
-  const found = candidates.find((dir) => existsSync4(join3(dir, "SKILL.md")));
-  if (!found) fail("bundled skill not found \u2014 reinstall the package");
+  const found = candidates.find((dir) => existsSync5(join4(dir, "SKILL.md")));
+  if (!found) fail("bundled skill not found \u2014 reinstall the package", "skill_missing");
   return found;
 }
 function installSkill(opts = {}) {
   const source = packagedSkillDir();
-  const target = opts.dir ?? join3(homedir2(), ".claude", "skills", "checkpointer");
+  const target = opts.dir ?? join4(homedir2(), ".claude", "skills", "checkpointer");
   mkdirSync4(dirname2(target), { recursive: true });
   rmSync(target, { recursive: true, force: true });
   cpSync(source, target, { recursive: true });
   if (opts.json) {
-    process.stdout.write(JSON.stringify({ installed: true, target }, null, 2) + "\n");
+    writeJson(okEnvelope({ installed: true, target }));
     return;
   }
   console.log(`${ok("\u2713 installed")} checkpointer skill to ${target}`);
@@ -826,14 +1667,14 @@ function installSkill(opts = {}) {
 function skillPath(opts = {}) {
   const source = packagedSkillDir();
   if (opts.json) {
-    process.stdout.write(JSON.stringify({ path: source }, null, 2) + "\n");
+    writeJson(okEnvelope({ path: source }));
     return;
   }
   console.log(source);
 }
 
 // src/cli.ts
-var VERSION = "0.1.0";
+var VERSION = true ? "0.2.1" : "0.0.0-dev";
 var program = new Command();
 program.name("checkpointer").description(
   "Git-isolated checkpoints that humans and AI agents share.\n\nSave working states during a long task, revert when something breaks,\nthen bundle a range of checkpoints into one clean commit on your repo.\nYour project's real git history is never touched until you 'ship'."
@@ -858,12 +1699,16 @@ Docs: https://github.com/checkpointer/checkpointer`
 );
 var json = ["--json", "output machine-readable JSON"];
 program.command("init").description("initialize checkpointing for this project").option(...json).action((opts) => init(opts));
-program.command("save [name]").description("snapshot the working tree as a checkpoint").option("-m, --message <text>", "describe what this checkpoint contains").option("-s, --status <status>", "working | wip | broken (default: wip)").option("--intent <text>", "why this checkpoint is being made (useful for agents)").option("--author <name>", "override the author").option("--agent <name>", "agent making the checkpoint (or set CHECKPOINTER_AGENT)").option("--session <id>", "agent session id (or set CHECKPOINTER_SESSION)").option(...json).addHelpText(
+program.command("save [name]").description("snapshot the working tree as a checkpoint").option("-m, --message <text>", "describe what this checkpoint contains").option("-s, --status <status>", "working | wip | broken (default: wip)").option("--intent <text>", "why this checkpoint is being made (useful for agents)").option("--allow-empty", "save even if nothing changed since the latest checkpoint").option("--author <name>", "override the author").option("--agent <name>", "agent making the checkpoint (or set CHECKPOINTER_AGENT)").option("--session <id>", "agent session id (or set CHECKPOINTER_SESSION)").option(...json).addHelpText(
   "after",
   '\nExamples:\n  $ checkpointer save\n  $ checkpointer save before-refactor --intent "extracting auth module"\n  $ checkpointer save v1 --status working -m "first working version"'
 ).action((name, opts) => save(name, opts));
 program.command("list").alias("ls").description("list all checkpoints").option(...json).action((opts) => list(opts));
 program.command("status").description("show how many checkpoints are unshipped").option(...json).action((opts) => status(opts));
+program.command("changed [id]").description("probe whether the working tree differs from a checkpoint (exit 100 if unchanged)").option(...json).addHelpText(
+  "after",
+  "\nExit codes: 0 = changed, 100 = unchanged. With --json it always exits 0;\nread the 'changed' field instead. Defaults to the latest checkpoint.\n\nExamples:\n  $ checkpointer changed && checkpointer save   # save only when something changed\n  $ checkpointer changed login --json"
+).action((id, opts) => changed(id, opts));
 program.command("show <id>").description("show details and tracked files of a checkpoint").option(...json).action((id, opts) => show(id, opts));
 program.command("diff <a> [b]").description("diff two checkpoints, or one checkpoint vs the working tree").option(...json).addHelpText(
   "after",
@@ -882,6 +1727,10 @@ Examples:
   $ checkpointer ship -m "Add login flow"
   $ checkpointer ship --upto v1 -m "Ship first version"`
 ).action((opts) => ship(opts));
+program.command("graph").description("visualize the project's functions and their call graph in a browser").option("--out <file>", "write a standalone HTML file instead of serving it").option("--port <n>", "port to serve on (default: a free ephemeral port)").option("--no-open", "don't auto-open the browser; just print the URL").option("--root <path>", "project to analyze (default: current git repo)").option(...json).addHelpText(
+  "after",
+  "\nBuilds a top-down call tree from a TypeScript/JavaScript project: click a\nfunction to expand what it calls, search any function, and view its\nancestors (callers up to entrypoints) and descendants.\n\nExamples:\n  $ checkpointer graph                  serve + open in browser\n  $ checkpointer graph --no-open        print the localhost URL only\n  $ checkpointer graph --out graph.html save a shareable file\n  $ checkpointer graph --json           emit the raw graph data"
+).action((opts) => graph(opts));
 program.command("info").description("show storage location and excluded paths").option(...json).action((opts) => info(opts));
 var skill = program.command("skill").description("manage the Claude / agent skill");
 skill.command("install").description("install the skill into ~/.claude/skills so Claude Code can use checkpointer").option("--dir <path>", "install to a custom directory").option(...json).action((opts) => installSkill(opts));
@@ -892,11 +1741,11 @@ async function main() {
   } catch (error) {
     if (error instanceof CheckpointerError) {
       if (process.argv.includes("--json")) {
-        process.stdout.write(JSON.stringify({ error: error.message, code: error.code }) + "\n");
+        writeJson(errEnvelope(error.message, error.code));
       } else {
         process.stderr.write(pc3.red("error: ") + error.message + "\n");
       }
-      process.exit(1);
+      process.exit(exitCodeFor(error.code));
     }
     throw error;
   }