@holmes-lab/holmes-kit 0.19.0 → 0.19.3

package/docs/install-guide.md

@@ -91,19 +91,63 @@ Your npm metadata cache predates the release — measured minutes after publishi
 registry already listed the version while a default-cache install still refused it. Add
 `--prefer-online`, or retry in a few minutes.
 
+### npm 12: `better-sqlite3` has no binary and nothing failed
+
+npm 12 (and npm ≥ 11.19) **blocks dependency install scripts by default** and skips them
+silently: `npm ci` exits 0, `better-sqlite3` never runs `prebuild-install`, and the first
+`require` dies with "Could not locate the bindings file". Measured 2026-09-09 (Windows 11,
+npm 12.0.1, Node 24.19.0). `npx holmes-kit doctor` names this cause as `scripts-blocked` and prints
+the commands below; do not reinstall — a reinstall reproduces the same state.
+
+Only **one** package needs its script: `better-sqlite3`. The 8 tree-sitter packages are also
+listed as blocked, but they load from their shipped `prebuilds/` without the script (measured on
+all 8), so they are deliberately NOT approved. This repository's `package.json` therefore carries
+
+```json
+"allowScripts": { "better-sqlite3@12.11.1": true }
+```
+
+pinned to the lockfile version, so a dependency bump forces a fresh review (a test fails until the
+pin is updated). Recovery, by how you installed — on Windows use the `.cmd` spellings (see below):
+
+| Layout | Commands |
+|---|---|
+| A project that depends on holmes-kit | `npm install-scripts approve better-sqlite3@12.11.1` then `npm rebuild better-sqlite3 --foreground-scripts` (from the project root; this writes the pin into YOUR package.json) |
+| This repository checkout | already approved — `npm rebuild better-sqlite3 --foreground-scripts` if the binary is missing |
+| Global (`npm install -g`) | `npm rebuild -g better-sqlite3 --foreground-scripts --allow-scripts=better-sqlite3` — a per-command flag scoped to one package; no npm config is changed. Target the dependency: `rebuild -g @holmes-lab/holmes-kit` re-links the bin and dies `EEXIST` under npm 12 (measured). If this fails `EPERM` under `C:\Program Files\nodejs`, your prefix is protected — see "Before `npm install -g`" above |
+| Bare `npx` | not repairable in place — do a local install and use the first row |
+
+Never use `--dangerously-allow-all-scripts` or a global `allow-scripts` config: the point of the
+policy is that only the reviewed package runs code at install time. Older npm 11 (measured 11.6.2)
+ignores the `allowScripts` field and runs scripts as before; npm 11.19 honours it exactly like 12.
+
+### Windows: `npm`/`npx` are blocked by the PowerShell execution policy
+
+`npm`, `npx` and `holmes-kit` resolve to `.ps1` shims first, and a `Restricted`/`AllSigned`
+policy refuses them (PSSecurityException). The `.cmd` shims always run: `npm.cmd`, `npx.cmd`.
+doctor emits `.cmd` commands on Windows and appends the policy note when it can observe a
+blocking policy. Do not change the execution policy to fix this.
+
 ### `better-sqlite3` fails to build
 
 The one dependency that may need a toolchain. The 8 tree-sitter grammars ship prebuilt binaries
 (`darwin-arm64`, `darwin-x64`, `linux-x64`, `win32-x64`) and compile nothing; `better-sqlite3`
 downloads a prebuild at install time and **falls back to compiling** when none matches your
-platform and Node ABI. If it compiles, you need:
+platform and Node ABI. doctor reports this as `build-failed` — with the approval in place, the
+script ran and left no binary — and names what it can observe on Windows (Python on PATH, Visual
+Studio C++ Build Tools, a space in the install path). It cannot observe a failed prebuild
+download; rerun with `--foreground-scripts` to see the script's own output. If it compiles, you
+need:
 
 | Platform | Toolchain |
 |---|---|
-| Windows | Visual Studio Build Tools (C++ workload) |
+| Windows | Visual Studio Build Tools (C++ workload) + Python 3 on PATH; prefer an install path without spaces |
 | macOS | Xcode Command Line Tools (`xcode-select --install`) |
 | Alpine | `apk add --no-cache python3 make g++` |
 
+A binary that exists but fails with `NODE_MODULE_VERSION` was built for another Node — doctor
+calls that `abi-mismatch`; rebuild against the Node you run.
+
 ### `spawn sh ENOENT` during a git-URL install
 
 `npm i -g git+ssh://…` is not a supported path: npm 11 clones the repository into its cache and
@@ -117,15 +161,20 @@ npx holmes-kit doctor        # local install
 holmes-kit doctor            # global install
 ```
 
-Expect `10 pass, 1 warn, 0 fail` on a healthy install. The lines that matter most:
+Expect `0 fail` on a healthy install (a few `warn` lines are normal — measured `12 pass, 4 warn,
+0 fail` on a Windows source checkout). The lines that matter most:
 
 - `global prefix` — whether `-g` would work on this machine, and the remedy if not
-- `tree-sitter grammars` / `better-sqlite3` — whether the native modules actually load
+- `tree-sitter grammars` — every grammar actually PARSES in a fresh process (`8 grammars parse`)
+- `better-sqlite3` — loads and runs a `:memory:` query; on FAIL the detail names the cause
+  (`scripts-blocked`, `abi-mismatch`, `build-failed`, or `unknown` with the raw error) and the fix
+  is the exact command for your install layout
 
 ## What we deliberately do NOT do
 
 | Idea | Why not |
 |---|---|
-| A `postinstall` script that prints guidance | Triggers npm 11's `allow-scripts` warning and forfeits this package's current property of running no install scripts at all |
+| A `postinstall` script that prints guidance | Under npm 12 it would be blocked like any other install script, and it forfeits this package's property of running no install scripts of its own |
+| Approving the tree-sitter grammars in `allowScripts` | Measured unnecessary — they load from shipped prebuilds — and every extra approval is code that runs at install time |
 | Recommending `npx @holmes-lab/holmes-kit init` with no install | `init` writes wiring with absolute paths; under bare `npx` those point into the npx cache and break when it is pruned |
 | Fixing your npm prefix from inside the package | A package rewriting your npm configuration is exactly the supply-chain behaviour this guide warns about |

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.19.0",
+  "version": "0.19.3",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",
@@ -85,5 +85,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "allowScripts": {
+    "better-sqlite3@12.11.1": true
   }
 }