@holmes-lab/holmes-kit 0.1.10 → 0.1.11

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+<!-- @implements A-SPEC-209 -->
+## [0.1.11] - 2026-08-23
+
+### Added
+- **`doctor` diagnoses the global npm prefix (REQ-243)**: after a Windows adopter hit `EPERM` on
+  `npm install -g` twice — once elevated — `doctor` now reads the npm global prefix, computes where
+  a global install would land (win32: `<prefix>\\node_modules`; POSIX: `<prefix>/lib/node_modules`),
+  and checks writability on the deepest existing ancestor, which is what decides the real mkdir's
+  fate. An unwritable prefix is a **WARN** naming the exact directory the install would die in, with
+  a user-space prefix prescription — never elevation, which npm's own error text suggests and which
+  would run better-sqlite3's install script with system privileges. An unreadable probe is a WARN
+  carrying the reason, never a silent pass. The check cannot FAIL: a red doctor would tell a user
+  with a healthy local install that the install is broken.
+
+### Unchanged
+- The `-g` EPERM itself is not fixable by any package: it occurs while npm creates the scope
+  directory, before a single package file is transferred. The supported regular-account path remains
+  the local install (`npm install --save-dev`), which touches no protected directory.
+
 <!-- @implements A-SPEC-209 -->
 ## [0.1.10] - 2026-08-23
 

package/dist/.build-id

@@ -1 +1 @@
-a400784-mt568ove
+c3422e5-mt570gca

package/dist/holmes/cli/doctor.d.ts

@@ -28,6 +28,45 @@ export interface DoctorOptions {
  * real key-related failure.
  */
 export declare const STRIPPED_FOR_PROBE: readonly ["HOLMES_APPROVAL", "HOLMES_SPECS"];
+/**
+ * Where a global install actually lands for a given prefix.
+ *
+ * @implements A-SPEC-243
+ * The shapes differ, not just the separators: win32 puts global modules directly under the prefix,
+ * POSIX puts them under `lib/`. The win32 result is the exact directory the reported EPERM died in
+ * — npm mkdir-ing `@holmes-lab` inside `C:\Program Files\nodejs\node_modules`, before a single
+ * package file was transferred. That is why no package content can fix that failure, and why the
+ * only lever left is naming the condition here.
+ */
+export declare function globalInstallDir(prefix: string, platform: string): string;
+/** What the global-prefix probe saw. `unreadable` carries WHY npm could not be consulted. */
+export interface PrefixProbe {
+    prefix?: unknown;
+    dir?: string;
+    writable?: boolean;
+    platform?: string;
+    unreadable?: string;
+}
+/**
+ * Judge the global prefix. Pure — the probing lives with the caller.
+ *
+ * @implements A-SPEC-243
+ * Never FAIL: the `-g` path is optional, and a red doctor tells a user with a healthy local
+ * install that the install is broken — a false signal that comes back as distrust of the check.
+ *
+ * Never elevation: npm's own EPERM text ends with "try running the command again as
+ * root/Administrator", and pointing the opposite way is this check's reason to exist — elevation
+ * runs better-sqlite3's install script (`prebuild-install || node-gyp rebuild`) with system
+ * privileges. The prescription is a user-space prefix, per platform.
+ *
+ * An unreadable probe is a WARN carrying the reason, not a silent pass: a silent pass reads as
+ * "checked, no problem", which translates what was not seen into a verdict.
+ */
+export declare function prefixVerdict(input: PrefixProbe): {
+    level: Level;
+    detail: string;
+    fix?: string;
+};
 /** The parent environment minus the variables that legitimately change a gate decision. Pure. */
 export declare function probeEnv(parent: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /** Seam for the gate probe's child process. Default is a real `spawnSync`; tests inject a fake. */

package/dist/holmes/cli/doctor.js

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.STRIPPED_FOR_PROBE = void 0;
+exports.globalInstallDir = globalInstallDir;
+exports.prefixVerdict = prefixVerdict;
 exports.probeEnv = probeEnv;
 exports.runDoctor = runDoctor;
 exports.formatChecks = formatChecks;
@@ -63,6 +65,56 @@ const GRAMMARS = [
  * real key-related failure.
  */
 exports.STRIPPED_FOR_PROBE = ['HOLMES_APPROVAL', 'HOLMES_SPECS'];
+/**
+ * Where a global install actually lands for a given prefix.
+ *
+ * @implements A-SPEC-243
+ * The shapes differ, not just the separators: win32 puts global modules directly under the prefix,
+ * POSIX puts them under `lib/`. The win32 result is the exact directory the reported EPERM died in
+ * — npm mkdir-ing `@holmes-lab` inside `C:\Program Files\nodejs\node_modules`, before a single
+ * package file was transferred. That is why no package content can fix that failure, and why the
+ * only lever left is naming the condition here.
+ */
+function globalInstallDir(prefix, platform) {
+    return platform === 'win32'
+        ? `${prefix.replace(/[\\/]+$/, '')}\\node_modules`
+        : `${prefix.replace(/\/+$/, '')}/lib/node_modules`;
+}
+/**
+ * Judge the global prefix. Pure — the probing lives with the caller.
+ *
+ * @implements A-SPEC-243
+ * Never FAIL: the `-g` path is optional, and a red doctor tells a user with a healthy local
+ * install that the install is broken — a false signal that comes back as distrust of the check.
+ *
+ * Never elevation: npm's own EPERM text ends with "try running the command again as
+ * root/Administrator", and pointing the opposite way is this check's reason to exist — elevation
+ * runs better-sqlite3's install script (`prebuild-install || node-gyp rebuild`) with system
+ * privileges. The prescription is a user-space prefix, per platform.
+ *
+ * An unreadable probe is a WARN carrying the reason, not a silent pass: a silent pass reads as
+ * "checked, no problem", which translates what was not seen into a verdict.
+ */
+function prefixVerdict(input) {
+    const reason = input.unreadable ?? (typeof input.prefix !== 'string' || input.prefix === ''
+        ? `npm 이 돌려준 prefix 를 해석할 수 없습니다 (${String(input.prefix)})`
+        : undefined);
+    if (reason !== undefined) {
+        return { level: 'WARN', detail: `전역 prefix 를 판독하지 못했습니다 — ${reason}. 로컬 설치(--save-dev)는 이 판정과 무관하게 동작합니다.` };
+    }
+    const prefix = input.prefix;
+    if (input.writable) {
+        return { level: 'PASS', detail: `전역 prefix(${prefix})가 현재 계정으로 쓰기 가능합니다 — npm install -g 가 권한 문제 없이 동작합니다.` };
+    }
+    const fix = input.platform === 'win32'
+        ? 'npm config set prefix "%APPDATA%\\npm" 실행 후 %APPDATA%\\npm 을 PATH 에 추가하고 터미널을 다시 여세요. 로컬 설치(npm install --save-dev)는 이 설정 없이도 동작합니다.'
+        : 'npm config set prefix "$HOME/.npm-global" 실행 후 $HOME/.npm-global/bin 을 PATH 에 추가하세요. 로컬 설치(npm install --save-dev)는 이 설정 없이도 동작합니다.';
+    return {
+        level: 'WARN',
+        detail: `전역 prefix(${prefix})가 현재 계정으로 쓰기 불가입니다 — npm install -g 는 ${input.dir ?? ''} 에 디렉터리를 만들다 EPERM 으로 죽습니다. 패키지가 도착하기 전 단계라 어떤 패키지도 이를 고칠 수 없습니다.`,
+        fix,
+    };
+}
 /** The parent environment minus the variables that legitimately change a gate decision. Pure. */
 function probeEnv(parent) {
     const out = { ...parent };
@@ -451,6 +503,33 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
         catch { /* an unreadable settings file is `target wiring`'s business, not this check's */ }
     }
     add('gate blind spots', 'PASS', (0, blind_spots_1.blindSpotSummary)());
+    // @implements A-SPEC-243 — the writability of the deepest EXISTING ancestor is what decides the
+    // real mkdir's fate, since the scope directory being created does not exist yet.
+    {
+        let verdict;
+        try {
+            const prefix = (0, node_child_process_1.execFileSync)('npm', ['config', 'get', 'prefix'], { encoding: 'utf8' }).trim();
+            const dir = globalInstallDir(prefix, process.platform);
+            let probe = dir;
+            while (!fs.existsSync(probe)) {
+                const parent = path.dirname(probe);
+                if (parent === probe)
+                    break;
+                probe = parent;
+            }
+            let writable = false;
+            try {
+                fs.accessSync(probe, fs.constants.W_OK);
+                writable = true;
+            }
+            catch { /* not writable */ }
+            verdict = prefixVerdict({ prefix, dir, writable, platform: process.platform });
+        }
+        catch (e) {
+            verdict = prefixVerdict({ unreadable: e instanceof Error ? e.message.split('\n')[0] : String(e) });
+        }
+        add('global prefix', verdict.level, verdict.detail, verdict.fix);
+    }
     add('environment', 'PASS', present);
     if (extraChecks) {
         checks.push(...extraChecks);

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "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",