docks-kit 0.16.15 → 0.16.16

package/AGENTS.md

@@ -80,7 +80,7 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the m
 - **Idempotent operations.** Every EngineNative sync step must be safe to re-run. Settings merges, plugin installs, and marketplace adds are all idempotent — re-running with no SoT changes is a no-op.
 - **Failed harness-CLI operations fail the sync.** A kit-managed marketplace or plugin command that exits non-zero is recorded through `failures.ts recordFailure` — it still warns in place, and `index.ts engineSync, failure ledger` lists every entry under `--- Failures ---` after the summary, then returns exit 1. A skip is not a failure: a missing harness CLI, missing git, a missing `SoT/toolchain.json` pin, and an unavailable plugin inventory stay warn-only with exit 0, and `ompSync.ts syncMarketplace, probe guard` returns before spawning so a host without omp never records one. Aggregate roll-up warnings (`N plugin operation(s) failed`) stay warns, because each counted site already records itself.
 - **Removed bash engine.** The bash engine was removed after the `bash-engine-final` tag. `DOCKS_KIT_ENGINE=bash` must fail with the removed-engine message; engine bugs are fixed forward in EngineNative.
-- **Effect 4 CLI stack.** The CLI pins `effect@4.0.0-rc.109` (including `effect/unstable/cli`), `@effect/platform-bun@4.0.0-rc.109` (`BunServices.layer`, `BunRuntime.runMain`), `@effect/vitest@4.0.0-rc.109`, and `vitest@4.1.11` (inside the `@effect/vitest` peer range `>=4.1.0 <5.0.0`; 4.1.11 fixes GHSA-82fw-gwwq-j7x9). `@effect/cli` and `@effect/platform` are removed and must not be reintroduced.
+- **Effect 4 CLI stack.** The CLI pins `effect@4.0.0-rc.115` (including `effect/unstable/cli`), `@effect/platform-bun@4.0.0-rc.115` (`BunServices.layer`, `BunRuntime.runMain`), `@effect/vitest@4.0.0-rc.115`, and `vitest@5.0.0` (inside the `@effect/vitest` peer range `>=5.0.0 <6.0.0`; 5.0.0 is past the 5.x patch point for GHSA-82fw-gwwq-j7x9, fixed in 5.0.0-rc.2). `@effect/cli` and `@effect/platform` are removed and must not be reintroduced.
 - **Effect skill routing.** Effect work in this checkout must verify migration and API call shapes against the installed declarations under `node_modules/effect/dist/unstable/cli/`, never from memory or a mutable dist-tag. The `effect-ts-setup`, `effect-ts-port`, and `effect-ts-specialist` skills target Effect 3.x and do not apply.
 - **Targeted syncs.** `./docks-kit sync` accepts positional targets: `claude`, `codex`, `agents`, and `omp`. Use the narrowest target that matches the SoT change (for example, `./docks-kit sync omp` for omp-only config edits); targets can be combined with `--dry-run`, `--skip-bubblewrap` (skip optional bubblewrap bootstrap for the Codex Linux sandbox), `--skip-plugin-refresh` (install missing plugins without refreshing existing caches), `--reconcile`, `--prune`, and the deploy-time modifiers `--claude-compact-window=<tokens>` / `--claude-permissive` / `--claude-model=<m>` / `--claude-effort=<level>` / `--claude-advisor=<on|off|default>` / `--codex-model=<m>` / `--codex-effort=<level>` (see `CLAUDE.md` § Deploy-time modifiers).
 - **Per-machine harness selection.** `~/.docks-kit/state.json` drives a flag-less sync. A missing file selects `claude`, `codex`, and `agents`; it never selects `omp` implicitly. `sync` never prompts and never writes the selection file. `docks-kit harnesses` is the only command that writes the selection.

package/README.md

@@ -59,10 +59,10 @@ docks-kit docs [topic]                          self-documentation (10 topics)
 The CLI is a typed Effect 4 RC front-end on Bun; all mutation runs through
 EngineNative in `cli/src/engine-native/`, with golden-regression coverage for
 dry-run output, mutation snapshots, and argv logs. Its dependency graph is
-`effect@4.0.0-rc.109` (including `effect/unstable/cli`),
-`@effect/platform-bun@4.0.0-rc.109` (`BunServices.layer` and
-`BunRuntime.runMain`), `@effect/vitest@4.0.0-rc.109`, and `vitest@4.1.11`
-(inside the `@effect/vitest` peer range `>=4.1.0 <5.0.0`). `@effect/cli` and
+`effect@4.0.0-rc.115` (including `effect/unstable/cli`),
+`@effect/platform-bun@4.0.0-rc.115` (`BunServices.layer` and
+`BunRuntime.runMain`), `@effect/vitest@4.0.0-rc.115`, and `vitest@5.0.0`
+(inside the `@effect/vitest` peer range `>=5.0.0 <6.0.0`). `@effect/cli` and
 `@effect/platform` are removed: neither has a 4.x release, the CLI API moved
 into core, and the standalone platform package was unused here.
 

package/cli/docs/install.md

@@ -40,9 +40,9 @@ one package with an `install` script, `msgpackr-extract` by way of
 `effect > msgpackr`, and Bun raises no trust prompt for it.
 
 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
+`@effect/platform-node-shared` at `4.0.0-rc.115`, 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
+each and the transitive peer range `effect@^4.0.0-rc.115` 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`.

package/cli/docs/toolchain.md

@@ -34,9 +34,10 @@ an installer. An already-present Bun skips that download on every host.
 from `typescript-language-server` 6's `engines` field. The kit installs that
 server as an npm global for the `typescript-lsp` plugin, so an older Node runs
 a server its own manifest rejects. `docks-kit toolchain check` prints
-`below-floor` for a Node older than 22.22.2 and changes nothing else. No sync
-pass, install, or launcher consults the Node floor. A host below the floor
-still runs every kit operation.
+`below-floor` for a Node older than 22.22.2. The sync pass reads the same
+floor: it skips the `typescript-language-server` install on such a host, warns
+with the host Node version, and installs the other language servers. Nothing
+else consults the floor, so a host below it still runs every kit operation.
 
 ## Language-server upgrades
 
@@ -46,7 +47,7 @@ that is already present. A `verified` bump therefore reaches a fresh host
 immediately and leaves an existing install alone.
 
 A lagging server shows as `below-floor` in `docks-kit toolchain check`. To move
-it, install the pinned version by hand:
+it, upgrade Node to 22.22.2 or newer, then install the pinned version by hand:
 
 ```bash
 npm install -g typescript-language-server@6.0.0

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

@@ -8,7 +8,7 @@ import { p, spawnProcess } from "./exec"
 import { recordFailure } from "./failures"
 import type { Ctx } from "./index"
 import { compareCodepoints, deepMerge, isObject, jqStringify, parseJson, readJsonFile, type Json } from "./jq"
-import { field } from "./toolchain"
+import { belowFloor, field, installedVersion } from "./toolchain"
 import { payloadText } from "../payload"
 
 async function cli(args: Array<string>): Promise<{ ok: boolean; out: string; detail: string }> {
@@ -389,6 +389,19 @@ function lspPkg(ctx: Ctx, tool: string, pkg: string): string | undefined {
   return undefined
 }
 
+/**
+ * npm treats a package's `engines` field as advisory unless the host opted
+ * into engine-strict, so installing typescript-language-server 6 on an older
+ * Node succeeds and then fails at every startup. Report the host Node version
+ * when it is too old, and the empty string when the install is safe.
+ */
+async function nodeBelowServerFloor(ctx: Ctx): Promise<string> {
+  const floor = field("node", "floor")
+  if (floor === "") return ""
+  const installed = await installedVersion(ctx, "node")
+  return belowFloor(installed, floor) ? installed : ""
+}
+
 export async function syncLspServers(ctx: Ctx): Promise<void> {
   const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger
   const sot = parseJson(payloadText("SoT/.claude/settings.json"))
@@ -402,9 +415,17 @@ export async function syncLspServers(ctx: Ctx): Promise<void> {
   const tsServerMissing = hasTs && ctx.services.deps.probe("typescript-language-server").state === "missing"
   const tscMissing = hasTs && ctx.services.deps.probe("tsc").state === "missing"
   const missingToolCount = Number(phpMissing) + Number(tsServerMissing) + Number(tscMissing)
+  const blockingNode = tsServerMissing ? await nodeBelowServerFloor(ctx) : ""
+  if (blockingNode !== "") {
+    warn(
+      `Skipping typescript-language-server install: Node ${blockingNode} is older than the ${field("node", "floor")} that version requires. Upgrade Node, then re-run sync.`
+    )
+  }
   const missing = [
     phpMissing ? lspPkg(ctx, "intelephense", "intelephense") : undefined,
-    tsServerMissing ? lspPkg(ctx, "typescript-language-server", "typescript-language-server") : undefined,
+    tsServerMissing && blockingNode === ""
+      ? lspPkg(ctx, "typescript-language-server", "typescript-language-server")
+      : undefined,
     tscMissing ? lspPkg(ctx, "tsc", "typescript") : undefined
   ].filter((spec): spec is string => spec !== undefined)
 

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

@@ -34,6 +34,15 @@ function isNewer(a: string, b: string): boolean {
   return compareCodepoints(a, b) > 0
 }
 
+/**
+ * A readable installed version strictly older than the manifest floor. The
+ * doctor row and the LSP install gate must agree on that judgement, so both
+ * ask here rather than re-deriving it.
+ */
+export function belowFloor(installed: string, floor: string): boolean {
+  return installed !== "" && floor !== "" && isNewer(floor, installed)
+}
+
 export function present(ctx: Ctx, tool: ToolId): boolean {
   return ctx.services.deps.probe(tool).state === "present"
 }
@@ -103,7 +112,7 @@ export async function report(ctx: Ctx): Promise<void> {
     if (present(ctx, toolId)) {
       installed = await installedVersion(ctx, toolId)
       status = installed === "" ? "unknown" : "ok"
-      if (floor !== "" && installed !== "" && isNewer(floor, installed)) {
+      if (belowFloor(installed, floor)) {
         status = "below-floor"
       } else if (verified !== "" && installed !== "" && isNewer(installed, verified)) {
         status = "above-verified"

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.15"
+export const GENERATED_PACKAGE_VERSION = "0.16.16"
 
 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.15",
+  "version": "0.16.16",
   "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Claude Code, Codex, and universal agent skills",
   "type": "module",
   "license": "MIT",