checkpointer 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,137 @@
+# checkpointer
+
+> Git-isolated checkpoints that humans and AI agents share — save working states, revert anytime, ship a range as one clean commit.
+
+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
+churn into **one clean commit**. `checkpointer` does exactly that, in a shadow git
+repo kept outside your project — so your real `git log` stays clean until you ship.
+
+- **Shared by humans and agents** — same commands, same checkpoints. Works with Claude Code, Cursor, or any tool that can run a shell command.
+- **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.
+
+## Install
+
+```bash
+npm install -g checkpointer      # then: checkpointer <command>
+npx checkpointer <command>       # or run without installing
+```
+
+Requires Node 18+ and git. Also available as `ckpt`.
+
+## Quick start
+
+```bash
+checkpointer init                              # set up checkpointing here
+checkpointer save before-refactor              # snapshot before risky work
+# ... make changes ...
+checkpointer save working --status working     # mark a known-good state
+checkpointer restore before-refactor           # something broke? roll back
+checkpointer ship -m "Refactor auth module"    # bundle it all into one commit
+git push                                        # ship never pushes — you do
+```
+
+## Concepts
+
+- **Checkpoint** — a full snapshot of your working tree at a moment in time, with a
+  name, a status, and (optionally) who made it and why.
+- **Status** — `working` (verified good), `wip` (in progress, the default), or
+  `broken` (known bad). `ship` refuses to include `broken` checkpoints unless forced.
+- **Shipping** — replaying the state of a chosen checkpoint onto your real repo as a
+  single commit. Everything since the last ship is bundled together.
+- **Shadow repo** — a hidden git repository per project under `~/.checkpointer`. It is
+  how snapshots are stored cheaply; it never touches your project's `.git`.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `init` | Initialize checkpointing for the current project |
+| `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 |
+| `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 |
+| `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.
+
+### Key options
+
+```bash
+checkpointer save v1 --status working -m "first working version"
+checkpointer save --intent "extracting the parser"     # record why (for agents)
+
+checkpointer ship --dry-run                            # preview what will commit
+checkpointer ship --upto v1 -m "Ship first version"    # ship up to a checkpoint
+checkpointer ship --force -m "..."                     # include broken checkpoints
+```
+
+## Safety
+
+- **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.
+- **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.
+- **Nothing leaves your machine.** No telemetry. Checkpoints are local git objects.
+
+## Using it with AI agents
+
+`checkpointer` is just a CLI, so any agent that can run shell commands can use it.
+Agents identify themselves with environment variables so their checkpoints are
+attributed:
+
+```bash
+export CHECKPOINTER_AGENT=claude-code
+export CHECKPOINTER_SESSION="<session-id>"
+export CHECKPOINTER_AUTHOR="<name>"   # optional: override the attributed author
+```
+
+Then a `checkpointer save` records the agent and session automatically.
+
+### Claude Code
+
+Install the bundled skill once and Claude Code will know when and how to checkpoint:
+
+```bash
+checkpointer skill install
+```
+
+This copies a skill into `~/.claude/skills/checkpointer`. Claude will then save
+checkpoints before risky changes, roll back on failure, and offer to ship when you're
+done.
+
+### Cursor and other agents
+
+Point the agent at the command reference above, or copy the skill's guidance into your
+agent rules (`checkpointer skill path` prints the bundled skill directory; read
+`SKILL.md` inside it). The same env-var protocol applies.
+
+## How it works
+
+For each project, `checkpointer` keeps a bare git repo at
+`~/.checkpointer/projects/<id>/repo.git`. Every checkpoint is a commit there, made with
+`git --git-dir=<shadow> --work-tree=<project>` so your project's `.git` is never read or
+written. `ship` transfers the chosen checkpoint's objects into your real repo and builds
+one ordinary commit from its tree — without resetting your working tree, so your
+uncommitted work is untouched. It never pushes.
+
+Set `CHECKPOINTER_HOME` to store checkpoints somewhere other than `~/.checkpointer`.
+
+## License
+
+Apache-2.0

package/dist/cli.js

@@ -0,0 +1,875 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+import pc3 from "picocolors";
+
+// src/actions.ts
+import pc2 from "picocolors";
+
+// src/core/store.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync3 } from "fs";
+
+// src/core/exec.ts
+import { spawnSync } from "child_process";
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd,
+    input: options.input,
+    env: options.env ?? process.env,
+    encoding: "utf8",
+    maxBuffer: 256 * 1024 * 1024
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? ""
+  };
+}
+
+// src/core/errors.ts
+var CheckpointerError = class extends Error {
+  code;
+  constructor(message, code = "error") {
+    super(message);
+    this.name = "CheckpointerError";
+    this.code = code;
+  }
+};
+function fail(message, code) {
+  throw new CheckpointerError(message, code);
+}
+
+// src/core/git.ts
+var IDENTITY = [
+  "-c",
+  "user.name=checkpointer",
+  "-c",
+  "user.email=checkpointer@local",
+  "-c",
+  "commit.gpgsign=false"
+];
+var ShadowGit = class {
+  constructor(gitDir, workTree) {
+    this.gitDir = gitDir;
+    this.workTree = workTree;
+  }
+  gitDir;
+  workTree;
+  base() {
+    return [`--git-dir=${this.gitDir}`, `--work-tree=${this.workTree}`];
+  }
+  run(args, input) {
+    return run("git", [...this.base(), ...args], { input });
+  }
+  capture(args, context) {
+    const result = this.run(args);
+    if (result.status !== 0) {
+      fail(`git ${context} failed: ${result.stderr.trim() || result.stdout.trim()}`);
+    }
+    return result.stdout.trim();
+  }
+  init() {
+    this.capture(["init", "-q"], "init");
+    this.run(["symbolic-ref", "HEAD", "refs/heads/checkpoints"]);
+  }
+  hasCommits() {
+    return this.run(["rev-parse", "--verify", "-q", "refs/heads/checkpoints"]).status === 0;
+  }
+  stageAll() {
+    this.capture(["add", "-A"], "stage");
+  }
+  commit(message) {
+    const args = [...IDENTITY, "commit", "-q", "--allow-empty", "-m", message];
+    const result = this.run(args);
+    if (result.status !== 0) {
+      fail(`git commit failed: ${result.stderr.trim() || result.stdout.trim()}`);
+    }
+    return this.capture(["rev-parse", "HEAD"], "rev-parse");
+  }
+  resolve(ref) {
+    const result = this.run(["rev-parse", "--verify", "-q", `${ref}^{commit}`]);
+    return result.status === 0 ? result.stdout.trim() : null;
+  }
+  restoreTree(sha) {
+    this.capture(["read-tree", "--reset", "-u", sha], "read-tree");
+  }
+  diff(from, to, paths = []) {
+    const args = ["diff", from, to];
+    if (paths.length) args.push("--", ...paths);
+    return this.capture(args, "diff");
+  }
+  diffWorkTree(from) {
+    return this.capture(["diff", from], "diff");
+  }
+  listFiles(sha) {
+    const out = this.capture(["ls-tree", "-r", "--name-only", sha], "ls-tree");
+    return out ? out.split("\n") : [];
+  }
+  diffStat(from, to) {
+    return this.capture(["diff", "--stat", from, to], "diff");
+  }
+  treeOf(sha) {
+    return this.capture(["rev-parse", `${sha}^{tree}`], "rev-parse");
+  }
+  get path() {
+    return this.gitDir;
+  }
+};
+
+// src/core/metadata.ts
+import { existsSync, readFileSync, writeFileSync, renameSync } from "fs";
+var STATUSES = ["working", "wip", "broken"];
+function empty(root) {
+  return { version: 1, root, shippedSeq: 0, checkpoints: [] };
+}
+function read(file, root) {
+  if (!existsSync(file)) return empty(root);
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    fail(`checkpoint metadata at ${file} is corrupt (invalid JSON)`);
+  }
+  const data = parsed;
+  if (data?.version !== 1 || !Array.isArray(data.checkpoints) || typeof data.shippedSeq !== "number") {
+    fail(`checkpoint metadata at ${file} is invalid or from an unsupported version`);
+  }
+  return data;
+}
+var Metadata = class _Metadata {
+  constructor(file, data) {
+    this.file = file;
+    this.data = data;
+  }
+  file;
+  data;
+  static load(paths) {
+    return new _Metadata(paths.metaFile, read(paths.metaFile, paths.root));
+  }
+  // Re-read from disk; call under the lock before a read-modify-write so we
+  // never compute a sequence number from a stale in-memory snapshot.
+  reload() {
+    this.data = read(this.file, this.data.root);
+  }
+  save() {
+    const tmp = `${this.file}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(this.data, null, 2) + "\n");
+    renameSync(tmp, this.file);
+  }
+  all() {
+    return this.data.checkpoints;
+  }
+  shippedSeq() {
+    return this.data.shippedSeq;
+  }
+  nextSeq() {
+    return this.data.checkpoints.reduce((max, cp) => Math.max(max, cp.seq), 0) + 1;
+  }
+  nameTaken(name) {
+    return this.data.checkpoints.some((cp) => cp.name === name);
+  }
+  // Derive a name that does not collide with an existing checkpoint, suffixing
+  // -2, -3, … as needed. Used for auto/default names, which must never fail.
+  uniqueName(base) {
+    if (!this.nameTaken(base)) return base;
+    for (let n = 2; ; n++) {
+      const candidate = `${base}-${n}`;
+      if (!this.nameTaken(candidate)) return candidate;
+    }
+  }
+  add(checkpoint) {
+    this.data.checkpoints.push(checkpoint);
+    this.save();
+  }
+  setStatus(seq, status2) {
+    const cp = this.data.checkpoints.find((c) => c.seq === seq);
+    if (cp) {
+      cp.status = status2;
+      this.save();
+    }
+  }
+  markShipped(seq) {
+    this.data.shippedSeq = Math.max(this.data.shippedSeq, seq);
+    this.save();
+  }
+  find(ref) {
+    if (ref.startsWith("#") && /^\d+$/.test(ref.slice(1))) {
+      const seq = Number(ref.slice(1));
+      return this.data.checkpoints.find((cp) => cp.seq === seq) ?? null;
+    }
+    const byName = this.data.checkpoints.find((cp) => cp.name === ref);
+    if (byName) return byName;
+    if (/^\d+$/.test(ref)) {
+      const bySeq = this.data.checkpoints.find((cp) => cp.seq === Number(ref));
+      if (bySeq) return bySeq;
+    }
+    return this.data.checkpoints.find((cp) => cp.sha.startsWith(ref)) ?? null;
+  }
+  require(ref) {
+    const cp = this.find(ref);
+    if (!cp) fail(`no checkpoint matches '${ref}' (try 'checkpointer list')`, "no_match");
+    return cp;
+  }
+  latest() {
+    return this.data.checkpoints.at(-1) ?? null;
+  }
+  latestManual() {
+    return [...this.data.checkpoints].reverse().find((cp) => !cp.auto) ?? null;
+  }
+  unshipped() {
+    return this.data.checkpoints.filter((cp) => cp.seq > this.data.shippedSeq && !cp.auto);
+  }
+};
+
+// src/core/paths.ts
+import { homedir } from "os";
+import { createHash } from "crypto";
+import { join } from "path";
+function home() {
+  return process.env.CHECKPOINTER_HOME ?? join(homedir(), ".checkpointer");
+}
+function projectId(root) {
+  return createHash("sha256").update(root).digest("hex").slice(0, 12);
+}
+function projectPaths(root) {
+  const id = projectId(root);
+  const dir = join(home(), "projects", id);
+  return {
+    id,
+    root,
+    dir,
+    gitDir: join(dir, "repo.git"),
+    metaFile: join(dir, "meta.json"),
+    ignoreFile: join(dir, "ignore"),
+    lockFile: join(dir, "lock")
+  };
+}
+
+// src/core/ignore.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync } from "fs";
+import { join as join2 } from "path";
+var DEFAULT_EXCLUDES = [
+  ".git/",
+  "node_modules/",
+  ".env",
+  ".env.*",
+  "*.pem",
+  "*.key",
+  "secrets.*",
+  ".DS_Store"
+];
+function userPatterns(paths) {
+  if (!existsSync2(paths.ignoreFile)) return [];
+  return readFileSync2(paths.ignoreFile, "utf8").split("\n").map((line) => line.trim()).filter((line) => line && !line.startsWith("#"));
+}
+function effectivePatterns(paths) {
+  return [...DEFAULT_EXCLUDES, ...userPatterns(paths)];
+}
+function writeExcludes(paths) {
+  const infoDir = join2(paths.gitDir, "info");
+  mkdirSync(infoDir, { recursive: true });
+  const body = effectivePatterns(paths).join("\n") + "\n";
+  writeFileSync2(join2(infoDir, "exclude"), body);
+}
+
+// src/core/project.ts
+import { realpathSync } from "fs";
+function resolveRoot(cwd = process.cwd()) {
+  const result = run("git", ["rev-parse", "--show-toplevel"], { cwd });
+  const top = result.stdout.trim();
+  const base = result.status === 0 && top ? top : cwd;
+  return realpathSync(base);
+}
+function isGitRepo(root) {
+  return run("git", ["rev-parse", "--git-dir"], { cwd: root }).status === 0;
+}
+function requireGitRepo(root) {
+  if (!isGitRepo(root)) {
+    fail(`not a git repository: ${root}
+Run 'git init' first so checkpointer can ship to it.`, "not_a_repo");
+  }
+}
+
+// src/core/lock.ts
+import { writeFileSync as writeFileSync3, linkSync, unlinkSync, readFileSync as readFileSync3, statSync, mkdirSync as mkdirSync2 } from "fs";
+import { dirname } from "path";
+var RETRY_MS = 50;
+var TIMEOUT_MS = 1e4;
+var STALE_MS = 6e4;
+function sleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function liveHolder(file) {
+  let pid = 0;
+  try {
+    pid = Number(readFileSync3(file, "utf8").trim());
+  } catch {
+    return false;
+  }
+  if (Number.isInteger(pid) && pid > 0) {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (err) {
+      return err.code === "EPERM";
+    }
+  }
+  try {
+    return Date.now() - statSync(file).mtimeMs < STALE_MS;
+  } catch {
+    return false;
+  }
+}
+var held = /* @__PURE__ */ new Set();
+function withLock(file, fn) {
+  if (held.has(file)) return fn();
+  mkdirSync2(dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}`;
+  writeFileSync3(temp, String(process.pid));
+  const deadline = Date.now() + TIMEOUT_MS;
+  try {
+    for (; ; ) {
+      try {
+        linkSync(temp, file);
+        break;
+      } catch (err) {
+        if (err.code !== "EEXIST") throw err;
+        if (!liveHolder(file)) {
+          try {
+            unlinkSync(file);
+          } catch {
+          }
+          continue;
+        }
+        if (Date.now() > deadline) {
+          fail("another checkpointer operation is in progress \u2014 try again in a moment");
+        }
+        sleep(RETRY_MS);
+      }
+    }
+  } finally {
+    try {
+      unlinkSync(temp);
+    } catch {
+    }
+  }
+  held.add(file);
+  try {
+    return fn();
+  } finally {
+    held.delete(file);
+    try {
+      unlinkSync(file);
+    } catch {
+    }
+  }
+}
+
+// src/core/store.ts
+var Store = class _Store {
+  paths;
+  git;
+  meta;
+  constructor(paths) {
+    this.paths = paths;
+    this.git = new ShadowGit(paths.gitDir, paths.root);
+    this.meta = Metadata.load(paths);
+  }
+  static open(root = resolveRoot()) {
+    const paths = projectPaths(root);
+    if (!existsSync3(paths.gitDir)) {
+      fail("checkpointer is not initialized here \u2014 run 'checkpointer init' first", "not_initialized");
+    }
+    return new _Store(paths);
+  }
+  static init(root = resolveRoot()) {
+    const paths = projectPaths(root);
+    const fresh = !existsSync3(paths.gitDir);
+    mkdirSync3(paths.dir, { recursive: true });
+    const store = new _Store(paths);
+    if (fresh) store.git.init();
+    writeExcludes(paths);
+    return store;
+  }
+  static isInitialized(root) {
+    return existsSync3(projectPaths(root).gitDir);
+  }
+  save(input) {
+    return withLock(this.paths.lockFile, () => {
+      this.meta.reload();
+      writeExcludes(this.paths);
+      const seq = this.meta.nextSeq();
+      const auto = input.auto ?? false;
+      let name;
+      if (input.name === void 0) {
+        name = this.meta.uniqueName(`cp-${seq}`);
+      } else if (auto) {
+        name = this.meta.uniqueName(input.name);
+      } else {
+        if (this.meta.nameTaken(input.name)) {
+          fail(`a checkpoint named '${input.name}' already exists`, "name_taken");
+        }
+        name = input.name;
+      }
+      this.git.stageAll();
+      const message = input.message ?? name;
+      const sha = this.git.commit(`[${seq}] ${name}: ${message}`);
+      const checkpoint = {
+        seq,
+        name,
+        sha,
+        status: input.status,
+        message,
+        author: input.author,
+        agent: input.agent,
+        session: input.session,
+        intent: input.intent,
+        auto,
+        createdAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      this.meta.add(checkpoint);
+      return checkpoint;
+    });
+  }
+  setStatus(seq, status2) {
+    withLock(this.paths.lockFile, () => {
+      this.meta.reload();
+      this.meta.setStatus(seq, status2);
+    });
+  }
+  restore(target, safetyAuthor) {
+    return withLock(this.paths.lockFile, () => {
+      const safety = this.save({
+        name: `before-restore-${target.name}`,
+        message: `auto-saved before restoring ${target.name}`,
+        status: "wip",
+        author: safetyAuthor,
+        agent: null,
+        session: null,
+        intent: null,
+        auto: true
+      });
+      this.git.restoreTree(target.sha);
+      return safety;
+    });
+  }
+};
+
+// src/core/identity.ts
+function resolveIdentity(root, overrides = {}) {
+  const agent = overrides.agent ?? process.env.CHECKPOINTER_AGENT ?? null;
+  const session = overrides.session ?? process.env.CHECKPOINTER_SESSION ?? null;
+  const intent = overrides.intent ?? process.env.CHECKPOINTER_INTENT ?? null;
+  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;
+}
+
+// src/core/ship.ts
+function planShip(store, uptoRef) {
+  const upto = uptoRef ? store.meta.require(uptoRef) : latestOrFail(store);
+  if (upto.auto) {
+    fail(`'${upto.name}' is an auto safety checkpoint \u2014 ship to a manual checkpoint instead`, "auto_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);
+  return {
+    upto,
+    from,
+    included,
+    files: store.git.listFiles(upto.sha),
+    diffStat: from ? store.git.diffStat(from.sha, upto.sha) : "(everything \u2014 nothing shipped yet)"
+  };
+}
+function executeShip(store, plan, message, author) {
+  return withLock(store.paths.lockFile, () => {
+    store.meta.reload();
+    if (!plan.included.length) {
+      fail(`nothing to ship \u2014 no unshipped checkpoints up to ${plan.upto.name}`, "nothing_to_ship");
+    }
+    const root = store.paths.root;
+    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) {
+        fail(`nothing to commit \u2014 your repo already matches checkpoint ${plan.upto.name}`, "nothing_to_commit");
+      }
+    }
+    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 }
+    });
+    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 });
+    if (update.status !== 0) fail(`git update-ref failed: ${update.stderr.trim()}`);
+    run("git", ["reset", "-q", "--mixed", "HEAD"], { cwd: root });
+    store.meta.markShipped(plan.upto.seq);
+    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;
+}
+
+// src/ui/format.ts
+import pc from "picocolors";
+function statusBadge(status2) {
+  switch (status2) {
+    case "working":
+      return pc.green("\u25CF working");
+    case "wip":
+      return pc.yellow("\u25CF wip");
+    case "broken":
+      return pc.red("\u25CF broken");
+  }
+}
+function relativeTime(iso) {
+  const then = new Date(iso).getTime();
+  const seconds = Math.round((Date.now() - then) / 1e3);
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.round(hours / 24)}d ago`;
+}
+function who(cp) {
+  return cp.agent ? `${cp.author} via ${cp.agent}` : cp.author;
+}
+function checkpointLine(cp, shippedSeq) {
+  const marker = cp.seq <= shippedSeq ? pc.dim("\u2713") : cp.auto ? pc.dim("\xB7") : " ";
+  const id = pc.cyan(`#${cp.seq}`.padEnd(4));
+  const label = cp.auto ? pc.dim(cp.name.padEnd(22)) : pc.bold(cp.name.padEnd(22));
+  return `${marker} ${id} ${label} ${statusBadge(cp.status).padEnd(20)} ${pc.dim(relativeTime(cp.createdAt).padStart(8))}  ${cp.message}`;
+}
+function heading(text) {
+  return pc.bold(pc.underline(text));
+}
+var ok = (text) => pc.green(text);
+var dim = (text) => pc.dim(text);
+
+// src/actions.ts
+function parseStatus(value, fallback) {
+  if (!value) return fallback;
+  if (!STATUSES.includes(value)) {
+    fail(`invalid status '${value}' (expected: ${STATUSES.join(", ")})`, "invalid_status");
+  }
+  return value;
+}
+function emit(json2, data, render) {
+  if (json2) {
+    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+  } else {
+    render();
+  }
+}
+function init(opts = {}) {
+  const root = resolveRoot();
+  requireGitRepo(root);
+  const existed = Store.isInitialized(root);
+  const store = Store.init(root);
+  emit(opts.json ?? false, { initialized: true, alreadyExisted: existed, id: store.paths.id, dir: store.paths.dir }, () => {
+    console.log(existed ? dim("checkpointer already initialized") : ok("\u2713 checkpointer initialized"));
+    console.log(dim(`  checkpoints stored in ${store.paths.dir}`));
+    console.log(dim(`  your project's git history is never touched`));
+  });
+}
+function save(name, opts) {
+  const root = resolveRoot();
+  requireGitRepo(root);
+  const store = Store.isInitialized(root) ? Store.open(root) : Store.init(root);
+  const id = resolveIdentity(root, {
+    author: opts.author,
+    agent: opts.agent,
+    session: opts.session,
+    intent: opts.intent
+  });
+  const cp = store.save({
+    name,
+    message: opts.message,
+    status: parseStatus(opts.status, "wip"),
+    ...id
+  });
+  emit(opts.json ?? false, cp, () => {
+    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}`));
+  });
+}
+function list(opts = {}) {
+  const store = Store.open();
+  const checkpoints = store.meta.all();
+  emit(opts.json ?? false, { shippedSeq: store.meta.shippedSeq(), checkpoints }, () => {
+    if (!checkpoints.length) {
+      console.log(dim("no checkpoints yet \u2014 run 'checkpointer save'"));
+      return;
+    }
+    const shipped = store.meta.shippedSeq();
+    for (const cp of checkpoints) console.log(checkpointLine(cp, shipped));
+    const legend = [];
+    if (shipped > 0) legend.push("\u2713 shipped to git");
+    if (checkpoints.some((cp) => cp.auto)) legend.push("\xB7 auto safety checkpoint");
+    if (legend.length) console.log(dim(`
+${legend.join("   ")}`));
+  });
+}
+function show(ref, opts = {}) {
+  const store = Store.open();
+  const cp = store.meta.require(ref);
+  const files = store.git.listFiles(cp.sha);
+  emit(opts.json ?? false, { ...cp, files }, () => {
+    console.log(`${pc2.cyan(`#${cp.seq}`)} ${pc2.bold(cp.name)}  ${statusBadge(cp.status)}`);
+    console.log(`  message  ${cp.message}`);
+    console.log(`  by       ${who(cp)}`);
+    if (cp.session) console.log(`  session  ${cp.session}`);
+    if (cp.intent) console.log(`  intent   ${cp.intent}`);
+    console.log(`  created  ${cp.createdAt} (${relativeTime(cp.createdAt)})`);
+    console.log(`  commit   ${cp.sha.slice(0, 12)}`);
+    console.log(dim(`  ${files.length} file(s) tracked`));
+  });
+}
+function diff(refA, refB, opts = {}) {
+  const store = Store.open();
+  const a = store.meta.require(refA);
+  if (refB) {
+    const b = store.meta.require(refB);
+    const patch = store.git.diff(a.sha, b.sha);
+    emit(opts.json ?? false, { from: a.name, to: b.name, patch }, () => process.stdout.write(patch + "\n"));
+  } else {
+    store.git.stageAll();
+    const patch = store.git.diffWorkTree(a.sha);
+    emit(opts.json ?? false, { from: a.name, to: "working-tree", patch }, () => process.stdout.write(patch + "\n"));
+  }
+}
+function restore(ref, opts = {}) {
+  const store = Store.open();
+  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 }, () => {
+    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 tag(ref, status2, opts = {}) {
+  const store = Store.open();
+  const cp = store.meta.require(ref);
+  const next = parseStatus(status2, cp.status);
+  store.setStatus(cp.seq, next);
+  emit(opts.json ?? false, { seq: cp.seq, name: cp.name, status: next }, () => {
+    console.log(`${ok("\u2713 tagged")} ${pc2.bold(cp.name)} as ${statusBadge(next)}`);
+  });
+}
+function status(opts = {}) {
+  const root = resolveRoot();
+  if (!Store.isInitialized(root)) {
+    emit(
+      opts.json ?? false,
+      { initialized: false },
+      () => console.log(dim("checkpointer not initialized here \u2014 run 'checkpointer init'"))
+    );
+    return;
+  }
+  const store = Store.open(root);
+  const all = store.meta.all();
+  const shipped = store.meta.shippedSeq();
+  const pending = store.meta.unshipped();
+  const latest = store.meta.latestManual();
+  emit(
+    opts.json ?? false,
+    { initialized: true, root, total: all.length, pending: pending.length, shippedSeq: shipped, latest },
+    () => {
+      console.log(`${heading("checkpointer")}  ${dim(root)}`);
+      console.log(`  ${all.length} checkpoint(s), ${pending.length} unshipped`);
+      if (latest) console.log(`  latest: ${pc2.bold(latest.name)} ${statusBadge(latest.status)} ${dim(relativeTime(latest.createdAt))}`);
+      if (pending.length) console.log(dim(`  run 'checkpointer ship -m "..."' to bundle them into one commit`));
+    }
+  );
+}
+function ship(opts) {
+  const root = resolveRoot();
+  requireGitRepo(root);
+  const store = Store.open(root);
+  const plan = planShip(store, opts.upto);
+  const broken = plan.included.filter((cp) => cp.status === "broken");
+  if (broken.length && !opts.force) {
+    fail(
+      `refusing to ship: ${broken.map((c) => c.name).join(", ")} tagged 'broken'
+re-tag them or pass --force to ship anyway`,
+      "broken_refusal"
+    );
+  }
+  if (opts.dryRun) {
+    emit(opts.json ?? false, { dryRun: true, ...summarizePlan(plan) }, () => renderPlan(plan));
+    return;
+  }
+  if (!opts.message) fail('a commit message is required: checkpointer ship -m "your message"', "missing_message");
+  const id = resolveIdentity(root);
+  const result = executeShip(store, plan, opts.message, id.author);
+  emit(opts.json ?? false, { committed: result.commit, message: result.message, ...summarizePlan(plan) }, () => {
+    console.log(`${ok("\u2713 shipped")} ${plan.included.length} checkpoint(s) as one commit`);
+    console.log(`  ${pc2.yellow(result.commit.slice(0, 12))} ${result.message.split("\n")[0]}`);
+    console.log(dim(`  your uncommitted and untracked changes were left untouched`));
+    console.log(dim(`  push when ready:  git push`));
+  });
+}
+function summarizePlan(plan) {
+  return {
+    upto: plan.upto.name,
+    from: plan.from?.name ?? null,
+    included: plan.included.map((cp) => ({ seq: cp.seq, name: cp.name, status: cp.status })),
+    fileCount: plan.files.length
+  };
+}
+function renderPlan(plan) {
+  console.log(heading("ship plan (dry run)"));
+  console.log(`  base:  ${plan.from ? plan.from.name : "(empty \u2014 first ship)"}`);
+  console.log(`  upto:  ${pc2.bold(plan.upto.name)} ${pc2.cyan(`#${plan.upto.seq}`)}`);
+  console.log(`  bundles ${plan.included.length} checkpoint(s):`);
+  for (const cp of plan.included) console.log(`    ${pc2.cyan(`#${cp.seq}`)} ${cp.name} ${statusBadge(cp.status)}`);
+  console.log(dim("\n" + (plan.diffStat || "(no changes)")));
+  console.log(dim('\nrun without --dry-run and with -m "message" to commit'));
+}
+function info(opts = {}) {
+  const root = resolveRoot();
+  const store = Store.isInitialized(root) ? Store.open(root) : null;
+  const patterns = store ? effectivePatterns(store.paths) : [];
+  emit(
+    opts.json ?? false,
+    { root, initialized: !!store, dir: store?.paths.dir, ignoreFile: store?.paths.ignoreFile, excluded: patterns },
+    () => {
+      console.log(`${heading("checkpointer config")}`);
+      console.log(`  project root: ${root}`);
+      console.log(`  initialized:  ${store ? "yes" : "no"}`);
+      if (store) console.log(`  storage dir:  ${store.paths.dir}`);
+      console.log(`  excluded (never snapshotted or restored over):`);
+      for (const p of patterns) console.log(dim(`    ${p}`));
+      if (store) console.log(dim(`  add patterns by editing ${store.paths.ignoreFile}`));
+    }
+  );
+}
+
+// src/skill.ts
+import { cpSync, existsSync as existsSync4, mkdirSync as mkdirSync4, rmSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname2, join as join3 } 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")
+  ];
+  const found = candidates.find((dir) => existsSync4(join3(dir, "SKILL.md")));
+  if (!found) fail("bundled skill not found \u2014 reinstall the package");
+  return found;
+}
+function installSkill(opts = {}) {
+  const source = packagedSkillDir();
+  const target = opts.dir ?? join3(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");
+    return;
+  }
+  console.log(`${ok("\u2713 installed")} checkpointer skill to ${target}`);
+  console.log(dim("  Claude Code will pick it up next session. Cursor/other agents: see the README."));
+}
+function skillPath(opts = {}) {
+  const source = packagedSkillDir();
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ path: source }, null, 2) + "\n");
+    return;
+  }
+  console.log(source);
+}
+
+// src/cli.ts
+var VERSION = "0.1.0";
+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'."
+).version(VERSION, "-v, --version", "print version").showHelpAfterError("(run 'checkpointer --help' for usage)").configureHelp({ showGlobalOptions: true });
+program.addHelpText(
+  "after",
+  `
+${pc3.bold("Examples:")}
+  ${pc3.dim("$")} checkpointer init                       initialize checkpointing here
+  ${pc3.dim("$")} checkpointer save                       snapshot the working tree
+  ${pc3.dim("$")} checkpointer save login --status working -m "login works"
+  ${pc3.dim("$")} checkpointer list                       see all checkpoints
+  ${pc3.dim("$")} checkpointer restore login              roll back to a checkpoint
+  ${pc3.dim("$")} checkpointer ship -m "Add login flow"   bundle into one commit
+
+${pc3.bold("Identifying checkpoints:")} by name (login), sequence (#4), or short sha.
+
+${pc3.bold("For AI agents:")} set CHECKPOINTER_AGENT and CHECKPOINTER_SESSION env vars
+so saves are attributed. Run 'checkpointer skill install' to teach Claude Code.
+
+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(
+  "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("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",
+  "\nExamples:\n  $ checkpointer diff login          compare 'login' to current files\n  $ checkpointer diff login #6       compare two checkpoints"
+).action((a, b, opts) => diff(a, b, opts));
+program.command("restore <id>").description("reset the working tree to a checkpoint (auto-saves current state first)").option(...json).action((id, opts) => restore(id, opts));
+program.command("tag <id> <status>").description("mark a checkpoint working | wip | broken").option(...json).action((id, status2, opts) => tag(id, status2, opts));
+program.command("ship").description("bundle unshipped checkpoints into one commit on your real repo").option("-u, --upto <id>", "ship up to this checkpoint (default: latest)").option("-m, --message <text>", "commit message").option("--dry-run", "show what would be committed without committing").option("--force", "ship even if a checkpoint is tagged 'broken'").option(...json).addHelpText(
+  "after",
+  `
+Ship never pushes \u2014 run 'git push' yourself afterward.
+A safety checkpoint is auto-saved so a ship can be undone.
+
+Examples:
+  $ checkpointer ship --dry-run
+  $ checkpointer ship -m "Add login flow"
+  $ checkpointer ship --upto v1 -m "Ship first version"`
+).action((opts) => ship(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));
+skill.command("path").description("print the path to the bundled skill (for manual install)").option(...json).action((opts) => skillPath(opts));
+async function main() {
+  try {
+    await program.parseAsync(process.argv);
+  } catch (error) {
+    if (error instanceof CheckpointerError) {
+      if (process.argv.includes("--json")) {
+        process.stdout.write(JSON.stringify({ error: error.message, code: error.code }) + "\n");
+      } else {
+        process.stderr.write(pc3.red("error: ") + error.message + "\n");
+      }
+      process.exit(1);
+    }
+    throw error;
+  }
+}
+void main();

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "checkpointer",
+  "version": "0.1.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",
+    "git",
+    "ai",
+    "agent",
+    "claude",
+    "cursor",
+    "snapshot",
+    "undo",
+    "rollback",
+    "cli"
+  ],
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "checkpointer": "dist/cli.js",
+    "ckpt": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}

package/skills/checkpointer/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: checkpointer
+description: Save, restore, and ship git-isolated checkpoints during multi-step work. Use this skill when the user wants save points while you make changes, asks to undo/revert to an earlier state, or asks to bundle progress into a clean commit. Use it proactively — save a checkpoint before risky edits (large refactors, codemods, formatter runs, dependency upgrades) so the work can be rolled back.
+---
+
+# checkpointer
+
+`checkpointer` is a CLI that snapshots the working tree into a shadow git repo kept
+outside the project. It never touches the project's real `.git`, so checkpoints never
+appear in `git log`. At the end you bundle a range of checkpoints into one clean commit.
+
+## Setup
+
+At the start of a session, identify yourself so checkpoints are attributed to you:
+
+```bash
+export CHECKPOINTER_AGENT=claude-code
+export CHECKPOINTER_SESSION="<session-or-task-id>"
+```
+
+Optionally set `CHECKPOINTER_AUTHOR` to override the name attributed to checkpoints.
+If `checkpointer` is not installed, run it through `npx checkpointer <command>`.
+
+## When to act
+
+1. **Before risky changes** — large refactors, codemods, `prettier`/`eslint --fix`,
+   dependency upgrades, or anything you are unsure about:
+   ```bash
+   checkpointer save --intent "why you are about to make this change"
+   ```
+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"
+   ```
+3. **When something breaks** — tag it so it won't be shipped, then keep going or roll back:
+   ```bash
+   checkpointer tag <id> broken
+   checkpointer restore <id>      # roll the working tree back to a good checkpoint
+   ```
+4. **When the user says "ship it" / "commit this"** — review, then bundle into one commit:
+   ```bash
+   checkpointer status
+   checkpointer ship --dry-run            # show what will be committed
+   checkpointer ship -m "Add login flow"  # one clean commit on the current branch
+   ```
+   Tell the user to `git push` themselves — `ship` never pushes.
+
+## Status values
+
+- `working` — verified good state
+- `wip` — in progress (default)
+- `broken` — known bad; `ship` refuses to include these unless `--force`
+
+## Rules
+
+- Restoring is always safe: it auto-saves the current state first, so a restore can be undone.
+- `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.
+- To reassure the user that secrets are safe, run `checkpointer info` to show the exclusion list.
+- Reference checkpoints by name (`login-fix`), sequence (`#4`), or short sha.
+
+## Command reference
+
+| Command | Purpose |
+| --- | --- |
+| `checkpointer init` | Set up checkpointing here (save auto-inits; use to initialize deliberately) |
+| `checkpointer save [name]` | Snapshot the working tree |
+| `checkpointer list` | List checkpoints |
+| `checkpointer status` | Show how many checkpoints are unshipped |
+| `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 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.