docks-kit 0.16.12 → 0.16.14

package/AGENTS.md

@@ -101,7 +101,7 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the m
 
 - No secrets in SoT. The kit's SoT directories are committed; treat them as declarative config only.
 - Treat external plugin marketplaces and installer downloads as untrusted input. Prefer download-then-run over `curl … | bash` so a truncated stream cannot execute a partial script.
-- **Pin, never float.** Every kit-driven install of third-party software is pinned to a `SoT/toolchain.json` `verified` version — no `@latest` npm/bun installs (Shai-Hulud-class worm surface), no mutable action tags in workflows (commit SHAs only), installer scripts fetched from version tags where upstream supports it. New third-party install surface ⇒ manifest pin first. Details: the `toolchain-context` skill and `cli/docs/toolchain.md`.
+- **Pin, never float.** Every kit-driven install of third-party software is pinned to a `SoT/toolchain.json` `verified` version — no `@latest` npm/bun installs (Shai-Hulud-class worm surface), no mutable action tags in workflows (commit SHAs only), installer scripts fetched from version tags where upstream supports it. New third-party install surface ⇒ manifest pin first. The rule also covers a transitive dependency whose declared range is a caret or tilde over a prerelease: `^4.0.0-rc.109` admits every later prerelease of the same version tuple, and a published install resolves that range fresh because `bun.lock` is not packaged, so a runtime pinned in `package.json` meets a newer sibling and the process fails at startup. The fix is an exact root pin plus both guards: the offline `cli/test/unit/dependencyPins.test.ts` and the clean-room `bun run smoke:package`. Details: the `toolchain-context` skill and `cli/docs/toolchain.md`.
 - **One exemption: the kit's own package.** `install.sh` and `install.ps1` end with `bun add -g docks-kit@latest`, because a global installer that pinned itself would install a fixed old kit forever, and pinning it to `package.json` would request an unpublished version between the release-prep commit and the npm publish. The exemption covers `docks-kit` alone. Both installers still pin the Bun installer they download to the manifest's verified version, and `cli/test/unit/install.test.ts` asserts that pin in all four launcher and installer scripts.
 ## Testing
 

package/cli/docs/install.md

@@ -39,17 +39,13 @@ untrusted` reports zero untrusted dependencies with scripts. Neither
 one package with an `install` script, `msgpackr-extract` by way of
 `effect > msgpackr`, and Bun raises no trust prompt for it.
 
-The install does print one expected warning:
-
-```
-warn: incorrect peer dependency "effect@4.0.0-rc.109"
-```
-
-`@effect/platform-bun` resolves `@effect/platform-node-shared` through a caret
-range, which installs rc.111, and that release declares a peer requirement of
-`effect@^4.0.0-rc.111`. The kit pins `effect@4.0.0-rc.109` deliberately, so this
-newer transitive peer range cannot be satisfied. `docks-kit --version`, model
-catalogs, toolchain checks, and real sync are unaffected.
+The install prints no peer dependency warning. The root pins
+`@effect/platform-node-shared` at `4.0.0-rc.109`, the same release as the
+pinned `effect`, so a fresh registry resolution installs exactly one copy of
+each and the transitive peer range `effect@^4.0.0-rc.109` is satisfied. Without
+that root pin, `@effect/platform-bun` requests the shared package through a
+caret range over a prerelease and a fresh install can pair a newer shared
+package with the pinned `effect`.
 
 ## 3. curl installer (POSIX)
 
@@ -113,6 +109,40 @@ the launcher bypasses that now-stale binary and uses updated source until rebuil
 Every `docks-kit sync` also does a best-effort behind-upstream check and
 nudges when the checkout is stale (silent offline / detached / no git).
 
+## Recovering a broken global install
+
+A global install made before the `@effect/platform-node-shared` pin can fail at
+startup with `Cannot find module 'effect/ByteSize'` or another missing
+`effect/...` module. Repair it with a remove followed by a fresh add:
+
+```
+bun rm -g docks-kit && bun add -g docks-kit@latest
+```
+
+A plain reinstall over the broken tree is not enough. Bun keeps the previously
+resolved copy nested under
+`node_modules/@effect/platform-bun/node_modules/@effect/platform-node-shared`,
+and that stale copy still loads.
+
+If a plain reinstall was already attempted, the remove-then-add above no longer
+clears that nested copy either. Force a full re-resolve of the global tree:
+
+```
+bun rm -g docks-kit && bun add -g docks-kit@latest --force
+```
+
+`--force` without the remove does not repair it. Other global packages survive
+both sequences.
+
+An npm global install repairs itself with a plain upgrade, because npm rebuilds
+the tree it owns:
+
+```
+npm install -g docks-kit@latest
+```
+
+Verified on Bun 1.4.2 and npm 11, each in a clean HOME.
+
 ## No-Bun recovery
 
 No Bun or constrained sandbox: download the platform release binary from GitHub

package/cli/src/generated/sotPayload.ts

@@ -1,7 +1,7 @@
 // Generated by cli/scripts/generate-sot-payload.ts. DO NOT EDIT.
 // Edit SoT/, notification.mp3, or package.json, then run: bun cli/scripts/generate-sot-payload.ts
 
-export const GENERATED_PACKAGE_VERSION = "0.16.12"
+export const GENERATED_PACKAGE_VERSION = "0.16.14"
 
 export const GENERATED_PAYLOAD_TEXT = {
   "SoT/.agents/skills.txt": "# Universal AI-agent skill manifest intentionally empty.\n# Global skill discovery is opt-in: add one <owner>/<repo> slug per line.\n# EngineNative ignores comments and blank lines.\n",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docks-kit",
-  "version": "0.16.12",
+  "version": "0.16.14",
   "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Claude Code, Codex, and universal agent skills",
   "type": "module",
   "license": "MIT",
@@ -29,6 +29,7 @@
     "typecheck": "tsc --noEmit -p cli",
     "build:binaries": "bash cli/build-binaries.sh",
     "smoke:native": "bun cli/scripts/native-smoke.ts",
+    "smoke:package": "bun cli/scripts/package-smoke.ts",
     "check:generated": "bun cli/scripts/generate-sot-payload.ts --check",
     "prepack": "bun run check:generated",
     "golden:dryrun": "bun cli/test/golden-dryrun.ts",
@@ -40,6 +41,7 @@
   },
   "dependencies": {
     "@effect/platform-bun": "4.0.0-rc.109",
+    "@effect/platform-node-shared": "4.0.0-rc.109",
     "effect": "4.0.0-rc.109",
     "yaml": "2.9.0"
   },