@compozy/skeeper 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +19 -6
  2. package/package.json +16 -16
package/README.md CHANGED
@@ -30,7 +30,8 @@ It mirrors `SPEC.md`, ADRs, RFCs, and AI plan files into a sidecar Git repositor
30
30
  - **Shared sidecars without collisions.** Namespaces isolate stored paths and sidecar branches inside one sidecar remote.
31
31
  - **Branch-aware history.** Namespace branches use `<namespace>/__branches__/<source-branch>`.
32
32
  - **Fresh-clone hydration.** `skeeper hydrate` restores files from the locked sidecar commits, not a best-effort latest branch.
33
- - **Agent-friendly commands.** `status`, `sync`, `verify`, `fsck`, `hooks check`, `repair status`, `pattern`, `adopt`, and `untrack` all support deterministic output where needed.
33
+ - **Safe reconciliation.** `hydrate`, `fsck`, `diff`, and `reconcile` classify per-path drift before any local managed document is overwritten or moved.
34
+ - **Agent-friendly commands.** `status`, `sync`, `verify`, `fsck`, `diff`, `reconcile`, `update`, `hooks check`, `repair status`, `rescue`, `pattern`, `adopt`, and `untrack` all support deterministic output where needed.
34
35
  - **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.
35
36
 
36
37
  ## 🎯 Who Is This For
@@ -100,8 +101,6 @@ namespaces:
100
101
  - "**/*.spec.md"
101
102
  exclude:
102
103
  - "docs/specs/private/**"
103
-
104
- bootstrap: brew tap compozy/compozy && brew install --cask skeeper
105
104
  ```
106
105
 
107
106
  Advanced operational defaults are optional:
@@ -136,6 +135,8 @@ Local-only state lives under `.git/skeeper/`:
136
135
  | ------------------ | ---------------------------------------------- |
137
136
  | `transaction.json` | Current resumable mutating operation and phase |
138
137
  | `bypass.json` | Latest audited strict-hook bypass |
138
+ | `hydration.json` | Last locked sidecar blobs hydrated locally |
139
+ | `rescue/` | Local files moved aside before prune/overwrite |
139
140
 
140
141
  ## 🚀 Quick Start
141
142
 
@@ -209,7 +210,12 @@ skeeper adopt <path-or-glob>... [--dry-run] [--json] [--force] [--commit --messa
209
210
  skeeper untrack <path-or-glob>... [--dry-run] [--json] [--force] [--commit --message <msg>]
210
211
  skeeper pattern test <glob> [--namespace <name>] [--json]
211
212
  skeeper pattern add <glob> [--namespace <name>] [--exclude <glob>]... [--adopt-existing] [--dry-run] [--json] [--force] [--commit --message <msg>]
212
- skeeper hydrate
213
+ skeeper hydrate [--dry-run] [--json] [--keep-local|--adopt-local|--prune-local|--merge] [--ours|--theirs]
214
+ skeeper reconcile [--dry-run] [--json] [--adopt-local|--prune-local|--merge] [--ours|--theirs]
215
+ skeeper diff [--json] [--namespace <name>] [--class <class>] [--extra] [--missing] [--modified]
216
+ skeeper rescue list [--json]
217
+ skeeper rescue restore <id> [path...] [--json] [--overwrite]
218
+ skeeper update [--json] [--no-git] [--reconcile <report|keep-local|adopt-local|prune-local|merge>] [--ours|--theirs]
213
219
  skeeper status [--json]
214
220
  skeeper log <path> [--latest]
215
221
  skeeper fsck [--json] [--source-branch <branch>]
@@ -227,8 +233,11 @@ Command notes:
227
233
  - `adopt` and `untrack` push sidecar coverage before removing main-index tracking.
228
234
  - `pattern add --adopt-existing` updates `.skeeper.yml`, updates the managed `.gitignore` block, then runs the same adoption transaction.
229
235
  - `verify` checks `skeeper.lock` against the sidecar remote and does not require hooks.
230
- - `fsck` compares current working-tree specs against locked sidecar content and does not mutate files or refs.
231
- - `hydrate` restores from locked sidecar commits by default.
236
+ - `fsck` compares current working-tree specs against locked sidecar content, reports exact drift paths, and does not mutate files or refs.
237
+ - `hydrate` restores from locked sidecar commits by default, but fails closed if local managed files would be overwritten or orphaned.
238
+ - `reconcile` is the explicit status/add/merge equivalent for managed documents. Use `--adopt-local` to publish local-only files, or `--prune-local` to move them to `.git/skeeper/rescue/<id>/` before restoring.
239
+ - `diff` lists per-path drift classes such as `local_only`, `missing_local`, `local_modified`, and `both_modified_conflict`.
240
+ - `update` is the high-level clone workflow for agents: safe fast-forward, verify, hydrate, fsck, and hook validation.
232
241
  - `log --latest` fetches the namespace branch and reads its latest history instead of the locked commit.
233
242
  - `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.
234
243
 
@@ -281,6 +290,10 @@ Run `skeeper repair status`. If the failure happened before main-index mutation,
281
290
 
282
291
  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`.
283
292
 
293
+ **`skeeper hydrate` is blocked by local managed files**
294
+
295
+ Run `skeeper diff` to inspect exact paths. Use `skeeper reconcile --adopt-local` when the local files should be published into the sidecar, or `skeeper reconcile --prune-local` when they should be moved to rescue before restoring the locked content. Use `skeeper rescue list` and `skeeper rescue restore <id>` to recover pruned files.
296
+
284
297
  **`verify` reports a lock mismatch**
285
298
 
286
299
  The main commit and sidecar remote disagree. Run `skeeper sync`, include the updated `skeeper.lock`, and rerun `skeeper verify`.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@compozy/skeeper",
3
3
  "type": "module",
4
- "version": "0.2.0",
4
+ "version": "0.2.1",
5
5
  "description": "Sidecar Git versioning for spec artifacts",
6
6
  "scripts": {
7
7
  "postinstall": "node install.js",
@@ -27,63 +27,63 @@
27
27
  },
28
28
  "archives": {
29
29
  "darwin-arm64": {
30
- "name": "skeeper_0.2.0_darwin_arm64.tar.gz",
31
- "url": "https://github.com/compozy/skeeper/releases/download/v0.2.0/skeeper_0.2.0_darwin_arm64.tar.gz",
30
+ "name": "skeeper_0.2.1_darwin_arm64.tar.gz",
31
+ "url": "https://github.com/compozy/skeeper/releases/download/v0.2.1/skeeper_0.2.1_darwin_arm64.tar.gz",
32
32
  "bins": [
33
33
  "skeeper"
34
34
  ],
35
35
  "format": "tar.gz",
36
36
  "checksum": {
37
37
  "algorithm": "sha256",
38
- "digest": "0b989d71f5cf6dc929bcf18d9f86fbe827ba74231b38b98fe268a299ba56d7da"
38
+ "digest": "0ce0b122891566136533442e176b05decc990bbe4e17bf01b290065276104392"
39
39
  }
40
40
  },
41
41
  "darwin-x64": {
42
- "name": "skeeper_0.2.0_darwin_x86_64.tar.gz",
43
- "url": "https://github.com/compozy/skeeper/releases/download/v0.2.0/skeeper_0.2.0_darwin_x86_64.tar.gz",
42
+ "name": "skeeper_0.2.1_darwin_x86_64.tar.gz",
43
+ "url": "https://github.com/compozy/skeeper/releases/download/v0.2.1/skeeper_0.2.1_darwin_x86_64.tar.gz",
44
44
  "bins": [
45
45
  "skeeper"
46
46
  ],
47
47
  "format": "tar.gz",
48
48
  "checksum": {
49
49
  "algorithm": "sha256",
50
- "digest": "fced98b16ffae5f72d843dfe532b989ee4f4c6df59973167f38a8e68fde1385c"
50
+ "digest": "5f7f2cf4ba83c3ed2f69eb388f04dce42b5e9f49009e307ede9b5200dcdc6621"
51
51
  }
52
52
  },
53
53
  "linux-arm64": {
54
- "name": "skeeper_0.2.0_linux_arm64.tar.gz",
55
- "url": "https://github.com/compozy/skeeper/releases/download/v0.2.0/skeeper_0.2.0_linux_arm64.tar.gz",
54
+ "name": "skeeper_0.2.1_linux_arm64.tar.gz",
55
+ "url": "https://github.com/compozy/skeeper/releases/download/v0.2.1/skeeper_0.2.1_linux_arm64.tar.gz",
56
56
  "bins": [
57
57
  "skeeper"
58
58
  ],
59
59
  "format": "tar.gz",
60
60
  "checksum": {
61
61
  "algorithm": "sha256",
62
- "digest": "04ab4382e4a01cb7a9165c055b8cf3b9675d03fbebe056ff67e2b04450c02a54"
62
+ "digest": "b10431032496f3091e2227ca2dd3fa660425f6224f1526b6086cb00a2f006396"
63
63
  }
64
64
  },
65
65
  "linux-x64": {
66
- "name": "skeeper_0.2.0_linux_x86_64.tar.gz",
67
- "url": "https://github.com/compozy/skeeper/releases/download/v0.2.0/skeeper_0.2.0_linux_x86_64.tar.gz",
66
+ "name": "skeeper_0.2.1_linux_x86_64.tar.gz",
67
+ "url": "https://github.com/compozy/skeeper/releases/download/v0.2.1/skeeper_0.2.1_linux_x86_64.tar.gz",
68
68
  "bins": [
69
69
  "skeeper"
70
70
  ],
71
71
  "format": "tar.gz",
72
72
  "checksum": {
73
73
  "algorithm": "sha256",
74
- "digest": "f1e0426e926fc654fccf23a6744cebc9313bf43cd5cc14576adef6cdf5612583"
74
+ "digest": "b913b1e145d0cb81f32c3b968e429810942237df0e3f93af2ebd10714409437d"
75
75
  }
76
76
  },
77
77
  "win32-x64": {
78
- "name": "skeeper_0.2.0_windows_x86_64.zip",
79
- "url": "https://github.com/compozy/skeeper/releases/download/v0.2.0/skeeper_0.2.0_windows_x86_64.zip",
78
+ "name": "skeeper_0.2.1_windows_x86_64.zip",
79
+ "url": "https://github.com/compozy/skeeper/releases/download/v0.2.1/skeeper_0.2.1_windows_x86_64.zip",
80
80
  "bins": [
81
81
  "skeeper.exe"
82
82
  ],
83
83
  "format": "zip",
84
84
  "checksum": {
85
85
  "algorithm": "sha256",
86
- "digest": "7dc1569a187eecaccc5e79e5f69be4da95acf050a6b58816bb790a38303e8733"
86
+ "digest": "0dc47392a8427bf29242ee92e72971cb8b4020ee78c03e6477ee0467523f8dd3"
87
87
  }
88
88
  }
89
89
  }