@compozy/skeeper 0.2.0 → 0.3.0

package/README.md

@@ -29,9 +29,11 @@ It mirrors `SPEC.md`, ADRs, RFCs, and AI plan files into a sidecar Git repositor
 - **Specs stay local to their code.** Edit `SPEC.md`, `docs/specs/**`, `.claude/plans/**`, ADRs, RFCs, or custom globs where they naturally belong.
 - **Shared sidecars without collisions.** Namespaces isolate stored paths and sidecar branches inside one sidecar remote.
 - **Branch-aware history.** Namespace branches use `<namespace>/__branches__/<source-branch>`.
-- **Fresh-clone hydration.** `skeeper hydrate` restores files from the locked sidecar commits, not a best-effort latest branch.
-- **Agent-friendly commands.** `status`, `sync`, `verify`, `fsck`, `hooks check`, `repair status`, `pattern`, `adopt`, and `untrack` all support deterministic output where needed.
-- **Skill for AI agents.** A bundled skill at [`.agents/skills/skeeper/SKILL.md`](.agents/skills/skeeper/SKILL.md) teaches coding agents the strict-sync workflow, namespaces, and recovery commands.
+- **Git-like spec sync.** `skeeper pull` brings remote docs in, `skeeper push` publishes local docs, and `skeeper sync` runs pull then push.
+- **Safe by default.** Manual push does not delete remote-only docs just because this clone does not have them; destructive pruning requires `--prune`.
+- **Fresh-clone restore.** `skeeper restore --all` restores files from the exact sidecar commits recorded in `skeeper.lock`.
+- **Small command surface.** Daily use is `status`, `pull`, `push`, `sync`, `restore`, `track`, `untrack`, `repair`, `log`, and `version`; Git hook plumbing lives behind hidden `skeeper internal` commands.
+- **Skill for AI agents.** A bundled skill at [`skills/skeeper/SKILL.md`](skills/skeeper/SKILL.md) teaches coding agents the strict-sync workflow, namespaces, and recovery commands.
 
 ## 🎯 Who Is This For
 
@@ -41,16 +43,51 @@ It mirrors `SPEC.md`, ADRs, RFCs, and AI plan files into a sidecar Git repositor
 
 ## 📦 Installation
 
+#### Homebrew
+
+```bash
+brew tap compozy/compozy
+brew install --cask skeeper
+```
+
+#### NPM
+
+```bash
+npm install -g @compozy/skeeper
+```
+
+#### Go
+
 ```bash
 go install github.com/compozy/skeeper/cmd/skeeper@latest
 ```
 
-Other release channels are available through GitHub Releases, Homebrew, NPM, and the distroless Docker image.
+#### GitHub Releases
+
+Download the archive for your OS and architecture from [GitHub Releases](https://github.com/compozy/skeeper/releases), then place the `skeeper` binary on your `PATH`.
+
+#### From Source
+
+```bash
+git clone git@github.com:compozy/skeeper.git
+cd skeeper
+make verify
+go build -o bin/skeeper ./cmd/skeeper
+```
+
+#### Docker
+
+```bash
+git clone git@github.com:compozy/skeeper.git
+cd skeeper
+make docker-build
+docker run --rm -v "$PWD:/workspace" -w /workspace skeeper:dev status
+```
 
 Prerequisites:
 
 - `git` on `PATH`
-- `gh` only when `skeeper init` creates a new GitHub sidecar repo
+- `gh` only when `skeeper init` creates a new GitHub sidecar repo; existing sidecars can be reused with `--sidecar`
 
 ## 🔄 How It Works
 
@@ -73,8 +110,8 @@ flowchart TD
 
     Block --> Commit[✅ Main commit proceeds]:::ok
     Commit --> Push([🚀 git push]):::user
-    Push --> Verify[🔍 Skeeper pre-push verify]:::skeeper
-    Verify --> Done([🎉 Sidecar verified]):::ok
+    Push --> Verify[🔍 Skeeper pre-push status check]:::skeeper
+    Verify --> Done([🎉 Sidecar checked]):::ok
 
     classDef user fill:#dbeafe,stroke:#1d4ed8,color:#0c1e3e
     classDef skeeper fill:#fef3c7,stroke:#b45309,color:#3b2c00
@@ -82,7 +119,7 @@ flowchart TD
     class S1,S2,S3,S4,S5 skeeper
 ```
 
-If sync fails, the commit fails. This is intentional: a committed main change should not silently drift from the sidecar. The audited bypass is `SKEEPER_SKIP=1`; it records `.git/skeeper/bypass.json`, prints a warning, and `pre-push`, `status`, `fsck`, and `verify` continue to surface stale-lock diagnostics until `skeeper sync` repairs the state. `git commit --no-verify` is unsupported because Git skips all hook code and cannot record an audit trail.
+If sync fails, the commit fails. This is intentional: a committed main change should not silently drift from the sidecar. The audited bypass is `SKEEPER_SKIP=1`; it records `.git/skeeper/bypass.json`, prints a warning, and `status --check`, `repair`, and the managed `pre-push` hook continue to surface stale-lock diagnostics until `skeeper sync` or `skeeper repair` repairs the state. `git commit --no-verify` is unsupported because Git skips all hook code and cannot record an audit trail.
 
 ## ⚙️ Configuration
 
@@ -100,8 +137,6 @@ namespaces:
       - "**/*.spec.md"
     exclude:
       - "docs/specs/private/**"
-
-bootstrap: brew tap compozy/compozy && brew install --cask skeeper
 ```
 
 Advanced operational defaults are optional:
@@ -136,6 +171,8 @@ Local-only state lives under `.git/skeeper/`:
 | ------------------ | ---------------------------------------------- |
 | `transaction.json` | Current resumable mutating operation and phase |
 | `bypass.json`      | Latest audited strict-hook bypass              |
+| `hydration.json`   | Last locked sidecar blobs hydrated locally     |
+| `rescue/`          | Local files moved aside before prune/overwrite |
 
 ## 🚀 Quick Start
 
@@ -150,8 +187,8 @@ skeeper init \
   --sidecar-name myproject-specs \
   --visibility private \
   --namespace project \
-  --patterns "**/SPEC.md" \
-  --patterns "docs/specs/**"
+  --track "**/SPEC.md" \
+  --track "docs/specs/**"
 ```
 
 Use an existing shared sidecar:
@@ -160,7 +197,7 @@ Use an existing shared sidecar:
 skeeper init \
   --sidecar git@github.com:user/shared-specs.git \
   --namespace project \
-  --patterns "**/SPEC.md"
+  --track "**/SPEC.md"
 ```
 
 Then edit specs and commit normally:
@@ -175,66 +212,140 @@ The `pre-commit` and `pre-merge-commit` hooks mirror specs and stage `skeeper.lo
 
 ## 🛟 Failed Sync Recovery
 
-Inspect local repair state:
+Start with status. It prints the health summary and the next action:
 
 ```bash
-skeeper repair status
+skeeper status --paths
 ```
 
-Resume the recorded operation when network/auth/sidecar contention has been fixed:
+Use repair as the single recovery door for broken local state, stale bypasses, hook drift, missing sidecar objects, and interrupted transactions:
 
 ```bash
-skeeper repair resume
+skeeper repair
+skeeper status --check
 ```
 
-Abort only before the main index has been mutated:
+When two clones have different docs and both sides should be preserved, use the union workflow:
 
 ```bash
-skeeper repair abort
+skeeper sync
+git add skeeper.lock
+git commit -m "skeeper: sync docs"
+git push
 ```
 
-Run a fresh repair sync when a bypass or stale lock is reported:
+## 📖 CLI Reference
+
+The public surface is intentionally small. `status` tells you what is wrong and what to run next; `repair` is the only public recovery door; Git hook and merge-driver plumbing runs through hidden `skeeper internal` commands.
+
+<details>
+<summary><code>skeeper init</code> — Create or connect a sidecar repository</summary>
 
 ```bash
-skeeper sync
-skeeper verify
+skeeper init [flags]
 ```
 
-## 📖 CLI Reference
+Run `init` once per main repository. Without flags in an interactive terminal, it opens the guided setup. With flags, it can create a GitHub sidecar or connect an existing remote. `init` installs hooks and merge-driver wiring.
+
+| Flag             | Default   | Description                                       |
+| ---------------- | --------- | ------------------------------------------------- |
+| `--sidecar`      |           | Existing sidecar repository URL                   |
+| `--sidecar-name` |           | GitHub sidecar repository name or `OWNER/REPO`    |
+| `--visibility`   | `private` | GitHub repository visibility                      |
+| `--namespace`    |           | Sidecar namespace for this project                |
+| `--track`        |           | Managed spec glob; repeat for multiple globs      |
+| `--patterns`     |           | Compatibility spelling for managed spec globs     |
+| `--bootstrap`    |           | Optional install command stored in `.skeeper.yml` |
+
+</details>
+
+<details>
+<summary><code>skeeper status</code> — Inspect sync health and next action</summary>
 
 ```bash
-skeeper init [flags]
-skeeper sync [--dry-run] [--json] [--commit --message <msg>] [--force]
-skeeper adopt <path-or-glob>... [--dry-run] [--json] [--force] [--commit --message <msg>]
+skeeper status [--json] [--check] [--paths]
+```
+
+Use `status` before guessing. It reports sidecar URL, current branch, lock state, hook health, namespace drift counts, bypass state, active transactions, diagnostics, and a next-action line. `--check` exits non-zero when Skeeper needs action, making it the CI health check. `--paths` includes per-path drift classes such as `local_only`, `missing_local`, `local_modified`, and `both_modified_conflict`.
+
+</details>
+
+<details>
+<summary><code>skeeper pull</code>, <code>push</code>, and <code>sync</code> — Git-like spec convergence</summary>
+
+```bash
+skeeper pull [--json] [--no-git]
+skeeper push [--dry-run] [--json] [--commit --message <msg>] [--force] [--prune]
+skeeper sync [--dry-run] [--json] [--commit --message <msg>] [--force] [--prune]
+```
+
+Use `pull` to fetch sidecar refs and materialize remote docs into the working tree while preserving local docs. It fast-forwards the main repo unless `--no-git` is set.
+
+Use `push` to publish local managed docs, write `skeeper.lock`, and stage the lockfile. By default `push` is non-destructive: remote-only docs stay in the sidecar.
+
+Use `sync` for the common two-clone flow. It runs a sidecar pull, then a push, so disjoint docs from two clones converge to the union.
+
+`--prune` is explicit and destructive: it deletes remote-only sidecar files that are absent locally.
+
+</details>
+
+<details>
+<summary><code>skeeper restore</code> — Restore local files from locked sidecar state</summary>
+
+```bash
+skeeper restore <path...> [--dry-run] [--json]
+skeeper restore --all [--dry-run] [--json]
+```
+
+Use `restore <path>` to overwrite selected local files with the content pinned by `skeeper.lock`. Existing local content is moved into rescue storage before overwrite. Use `restore --all` after a fresh clone, bisect, or checkout when you need every locked managed file materialized locally. Use `pull` when you want the latest remote sidecar tip instead of the locked state.
+
+</details>
+
+<details>
+<summary><code>skeeper track</code> and <code>untrack</code> — Change managed coverage</summary>
+
+```bash
+skeeper track <glob> [--namespace <name>] [--exclude <glob>]... [--sync] [--dry-run] [--json] [--force] [--commit --message <msg>]
 skeeper untrack <path-or-glob>... [--dry-run] [--json] [--force] [--commit --message <msg>]
-skeeper pattern test <glob> [--namespace <name>] [--json]
-skeeper pattern add <glob> [--namespace <name>] [--exclude <glob>]... [--adopt-existing] [--dry-run] [--json] [--force] [--commit --message <msg>]
-skeeper hydrate
-skeeper status [--json]
-skeeper log <path> [--latest]
-skeeper fsck [--json] [--source-branch <branch>]
-skeeper verify [--json] [--source-branch <branch>]
-skeeper hooks install [--json]
-skeeper hooks check [--json]
-skeeper merge-driver [--json]
-skeeper repair status|resume|abort [--json]
+```
+
+Use `track` to add a managed glob to `.skeeper.yml` and the managed `.gitignore` block. Add `--sync` when matching files already exist and should be published into the sidecar immediately.
+
+Use `untrack` when a managed path should stop being tracked in the main repository after the sidecar has the content.
+
+</details>
+
+<details>
+<summary><code>skeeper repair</code> — Diagnose and repair local Skeeper state</summary>
+
+```bash
+skeeper repair [--check] [--json]
+```
+
+`repair` handles hook drift, strict-hook bypasses, interrupted transactions, missing local sidecar objects, and rescue reporting. It applies safe repairs automatically and stops on ambiguous overwrite/delete decisions. Use `repair --check` for read-only diagnosis.
+
+</details>
+
+<details>
+<summary><code>skeeper log</code>, <code>version</code>, and <code>completion</code> — Utility commands</summary>
+
+```bash
+skeeper log <path> [--latest] [--source-branch <branch>]
 skeeper version
+skeeper completion <bash|fish|powershell|zsh>
 ```
 
-Command notes:
+`log` shows sidecar history for one managed spec path. By default it reads the locked commit; use `--latest` to fetch and inspect the latest namespace branch instead.
 
-- `sync` uses working-tree content and stages `skeeper.lock`. Hook mode uses staged index content.
-- `adopt` and `untrack` push sidecar coverage before removing main-index tracking.
-- `pattern add --adopt-existing` updates `.skeeper.yml`, updates the managed `.gitignore` block, then runs the same adoption transaction.
-- `verify` checks `skeeper.lock` against the sidecar remote and does not require hooks.
-- `fsck` compares current working-tree specs against locked sidecar content and does not mutate files or refs.
-- `hydrate` restores from locked sidecar commits by default.
-- `log --latest` fetches the namespace branch and reads its latest history instead of the locked commit.
-- `hooks install` removes legacy Skeeper post-commit blocks, installs strict pre-commit/pre-merge-commit/pre-push blocks, writes `.gitattributes`, and configures the `skeeper.lock` merge driver.
+`version` prints build version, commit, and build date.
+
+`completion` is provided by Cobra and generates shell completion scripts.
+
+</details>
 
 ## 🤖 CI Action
 
-Use the same-repository Action to verify `skeeper.lock` in CI:
+Use the same-repository Action to check Skeeper health in CI:
 
 ```yaml
 name: skeeper
@@ -245,16 +356,17 @@ on:
     branches: [main]
 
 jobs:
-  verify:
+  check:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: compozy/skeeper@v0.1.1
+      - uses: compozy/skeeper@v0.2.1
         with:
           args: |
-            verify
+            status
+            --check
             --json
           ssh-private-key: ${{ secrets.SKEEPER_SSH_PRIVATE_KEY }}
 ```
@@ -265,25 +377,29 @@ Credential precedence:
 2. `token` configures HTTPS GitHub credentials.
 3. Existing runner Git/SSH credentials are used when neither input is provided.
 
-Secrets are masked before configuration. The wrapper downloads the released Skeeper binary for the action ref/tag and delegates verification to the CLI.
+Secrets are masked before configuration. The wrapper downloads the released Skeeper binary for the action ref/tag and delegates the status check to the CLI.
 
 ## 🩺 Troubleshooting
 
 **`SKEEPER_SKIP=1` was used**
 
-Run `skeeper status`, then `skeeper sync`, then `skeeper verify`. The bypass journal remains visible until sync clears it.
+Run `skeeper status`, then `skeeper sync`, then `skeeper status --check`. The bypass journal remains visible until sync clears it.
 
 **Sidecar push was rejected**
 
-Run `skeeper repair status`. If the failure happened before main-index mutation, fix network/auth or sidecar contention and run `skeeper repair resume`. If the main index was already mutated, inspect the listed files manually.
+Run `skeeper repair --check`. If the failure is safe to repair automatically, run `skeeper repair` after fixing network/auth or sidecar contention. If the report names an ambiguous overwrite/delete decision, inspect the listed files manually and use `skeeper sync` after resolving it.
 
 **`skeeper.lock` conflicts during merge**
 
-Run `skeeper hooks install` to ensure the merge driver is configured, then rerun the merge. Manual editing of scalar sidecar SHAs is unsupported; regenerate the lock through `skeeper merge-driver` or `skeeper sync`.
+Run `skeeper repair` to ensure hooks and merge-driver wiring are configured, then rerun the merge. Manual editing of scalar sidecar SHAs is unsupported; regenerate the lock through `skeeper sync`.
+
+**`skeeper pull` or `skeeper restore` is blocked by local managed files**
+
+Run `skeeper status --paths` to inspect exact paths. Use `skeeper sync` when local-only docs should be merged with remote docs. Use `skeeper push --prune` only when the local set is intentionally authoritative and remote-only docs should be pruned.
 
-**`verify` reports a lock mismatch**
+**`status --check` reports a lock mismatch**
 
-The main commit and sidecar remote disagree. Run `skeeper sync`, include the updated `skeeper.lock`, and rerun `skeeper verify`.
+The main commit and sidecar remote disagree. Run `skeeper sync`, include the updated `skeeper.lock`, and rerun `skeeper status --check`.
 
 **A namespace overlaps another namespace**
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@compozy/skeeper",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Sidecar Git versioning for spec artifacts",
   "scripts": {
     "postinstall": "node install.js",
@@ -27,63 +27,63 @@
   },
   "archives": {
     "darwin-arm64": {
-      "name": "skeeper_0.2.0_darwin_arm64.tar.gz",
-      "url": "https://github.com/compozy/skeeper/releases/download/v0.2.0/skeeper_0.2.0_darwin_arm64.tar.gz",
+      "name": "skeeper_0.3.0_darwin_arm64.tar.gz",
+      "url": "https://github.com/compozy/skeeper/releases/download/v0.3.0/skeeper_0.3.0_darwin_arm64.tar.gz",
       "bins": [
         "skeeper"
       ],
       "format": "tar.gz",
       "checksum": {
         "algorithm": "sha256",
-        "digest": "0b989d71f5cf6dc929bcf18d9f86fbe827ba74231b38b98fe268a299ba56d7da"
+        "digest": "3aa2e55272c6de252f6064cd35fbf4ce328715f6835c3810b6b18be2ba23cd84"
       }
     },
     "darwin-x64": {
-      "name": "skeeper_0.2.0_darwin_x86_64.tar.gz",
-      "url": "https://github.com/compozy/skeeper/releases/download/v0.2.0/skeeper_0.2.0_darwin_x86_64.tar.gz",
+      "name": "skeeper_0.3.0_darwin_x86_64.tar.gz",
+      "url": "https://github.com/compozy/skeeper/releases/download/v0.3.0/skeeper_0.3.0_darwin_x86_64.tar.gz",
       "bins": [
         "skeeper"
       ],
       "format": "tar.gz",
       "checksum": {
         "algorithm": "sha256",
-        "digest": "fced98b16ffae5f72d843dfe532b989ee4f4c6df59973167f38a8e68fde1385c"
+        "digest": "d56c7ab028576cc50f6e9f3dd4b7c84909ef4baee6dfa9dcb9e98e32d77b0319"
       }
     },
     "linux-arm64": {
-      "name": "skeeper_0.2.0_linux_arm64.tar.gz",
-      "url": "https://github.com/compozy/skeeper/releases/download/v0.2.0/skeeper_0.2.0_linux_arm64.tar.gz",
+      "name": "skeeper_0.3.0_linux_arm64.tar.gz",
+      "url": "https://github.com/compozy/skeeper/releases/download/v0.3.0/skeeper_0.3.0_linux_arm64.tar.gz",
       "bins": [
         "skeeper"
       ],
       "format": "tar.gz",
       "checksum": {
         "algorithm": "sha256",
-        "digest": "04ab4382e4a01cb7a9165c055b8cf3b9675d03fbebe056ff67e2b04450c02a54"
+        "digest": "457f1b62137886afa56cdbf48b902b01fc81abc10e4431619ca1a8bbca5b73e1"
       }
     },
     "linux-x64": {
-      "name": "skeeper_0.2.0_linux_x86_64.tar.gz",
-      "url": "https://github.com/compozy/skeeper/releases/download/v0.2.0/skeeper_0.2.0_linux_x86_64.tar.gz",
+      "name": "skeeper_0.3.0_linux_x86_64.tar.gz",
+      "url": "https://github.com/compozy/skeeper/releases/download/v0.3.0/skeeper_0.3.0_linux_x86_64.tar.gz",
       "bins": [
         "skeeper"
       ],
       "format": "tar.gz",
       "checksum": {
         "algorithm": "sha256",
-        "digest": "f1e0426e926fc654fccf23a6744cebc9313bf43cd5cc14576adef6cdf5612583"
+        "digest": "58697a19879045eb0c6f5d92711697f58f78926dc87e772608e8cf99bc614525"
       }
     },
     "win32-x64": {
-      "name": "skeeper_0.2.0_windows_x86_64.zip",
-      "url": "https://github.com/compozy/skeeper/releases/download/v0.2.0/skeeper_0.2.0_windows_x86_64.zip",
+      "name": "skeeper_0.3.0_windows_x86_64.zip",
+      "url": "https://github.com/compozy/skeeper/releases/download/v0.3.0/skeeper_0.3.0_windows_x86_64.zip",
       "bins": [
         "skeeper.exe"
       ],
       "format": "zip",
       "checksum": {
         "algorithm": "sha256",
-        "digest": "7dc1569a187eecaccc5e79e5f69be4da95acf050a6b58816bb790a38303e8733"
+        "digest": "630c98e8f22fb91777602c704a4e21a70532dfada3bb604477a1997d95951768"
       }
     }
   }