docks-kit 0.16.11 → 0.16.13

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/README.md

@@ -79,7 +79,7 @@ into core, and the standalone platform package was unused here.
 | `--claude-plugin=<name>` | Sticky opt-in plugin (supabase, n8n) |
 | `--codex-model=<m>` | Deploy-time modifier: deployed Codex model |
 | `--skip-bubblewrap` | Skip optional bubblewrap bootstrap (Codex Linux sandbox) |
-| `--skip-plugin-refresh` | Install missing plugins but skip refresh-only updates (used automatically by `docks-kit update`) |
+| `--skip-plugin-refresh` | Install missing plugins but skip refresh-only updates |
 
 **Deploy-time modifiers** change deployed config only — the SoT is untouched
 and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`

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,21 @@ 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. Verified on Bun 1.4.2.
+
 ## No-Bun recovery
 
 No Bun or constrained sandbox: download the platform release binary from GitHub

package/cli/src/engine-native/claudePlugins.ts

@@ -168,9 +168,9 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     if (separator > 0) kitMarketplaces.add(pluginId.slice(separator + 1))
   }
 
-  // Pass 3 — refresh the kit-owned marketplaces unless the update command
-  // selected its install-missing-only fast path. Pass 2 already refreshed the
-  // source marketplace of every plugin it installed, so skip those: a second
+  // Pass 3 — refresh the kit-owned marketplaces unless the caller passed
+  // --skip-plugin-refresh by hand. Pass 2 already refreshed the source
+  // marketplace of every plugin it installed, so skip those: a second
   // fetch seconds later cannot resolve a newer snapshot, and re-running it
   // would duplicate one failure in the ledger and in the failed-operation count.
   if (!ctx.skipPluginRefresh) {

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.11"
+export const GENERATED_PACKAGE_VERSION = "0.16.13"
 
 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.11",
+  "version": "0.16.13",
   "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"
   },