@ngockhoale/ukit 3.4.34 → 3.4.35

package/CHANGELOG.md

@@ -9,6 +9,13 @@ All notable changes to UKit are documented here.
 - New `/ukit:ci-check` command + `ci-check.mjs` helper (core pack): prechecks, fail-closed budget guard, local preflight, at most one dispatch per invocation, write-ahead run-id state, `status` (never dispatches), `--ref`, `--dry-run`, per-OS report. Never pushes, merges or publishes.
 - Default-branch bootstrap stub documented in `docs/design/CI-CROSS-PLATFORM-MATRIX.md` (requires separate approval).
 
+## 3.4.35 - 2026-10-12
+
+**Windows: `ukit update` no longer fails preflight with `npm is not runnable (spawnSync npm ENOENT)`.**
+- Root cause: `update.js` (`npm root -g`, `npm install -g`) and `updateSafety.js` (`npm --version` preflight) called `spawnSync('npm', …)`. On Windows npm is `npm.cmd`, so a bare name fails with ENOENT even though npm works in PowerShell (and spawning a `.cmd` directly fails with EINVAL on Node >= 18.20/20.12/22, including 24).
+- Fix: new `src/core/npmCommand.js` — on win32 npm runs through `%ComSpec% /d /s /c` (PATH/PATHEXT resolution, custom locations, paths with spaces); POSIX behavior is unchanged (direct spawn, no shell). Arguments are allowlisted so nothing cmd.exe treats specially can reach the command line. The preflight message now includes npm's first stderr line.
+- Validation limit: no real Windows host was available; the cmd.exe path is covered by exact-invocation tests plus a POSIX stand-in for cmd.exe, which proves the spawn/exit-code/timeout/PATH plumbing, not real Windows behavior.
+
 ## 3.4.34 - 2026-10-12
 
 **Hook interference fixes (P1): task intent, operation evidence, heredoc data, containment reporting.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.34",
+  "version": "3.4.35",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/src/core/npmCommand.js

@@ -0,0 +1,31 @@
+import { spawnSync as defaultSpawnSync } from 'node:child_process';
+
+// On Windows npm is `npm.cmd` (+ `npm.ps1`), not an executable. `spawnSync('npm', …)` therefore
+// fails with ENOENT (CreateProcess does not apply PATHEXT to a bare name), and since the
+// CVE-2024-27980 hardening (Node 18.20 / 20.12 / 21.7 / 22+, so Node 24 too) spawning a
+// `.cmd`/`.bat` file directly fails with EINVAL. The supported route is cmd.exe: it resolves
+// `npm` through PATH + PATHEXT (custom locations, directories with spaces) exactly like the
+// user's shell. POSIX is untouched: `npm` is spawned directly, no shell.
+//
+// No shell string is ever built from free-form input: every npm argument must match a strict
+// allowlist (package names, versions, flags), so nothing cmd.exe treats specially can pass.
+const SAFE_NPM_ARG = /^[A-Za-z0-9@._/:=+~^-]+$/;
+
+export function npmInvocation(args, { platform = process.platform, env = process.env } = {}) {
+  for (const arg of args) {
+    if (typeof arg !== 'string' || !SAFE_NPM_ARG.test(arg)) {
+      throw new Error(`Refusing unsafe npm argument: ${JSON.stringify(arg)}`);
+    }
+  }
+  if (platform !== 'win32') return { command: 'npm', args: [...args], options: {} };
+  return {
+    command: env.ComSpec || env.COMSPEC || 'cmd.exe',
+    args: ['/d', '/s', '/c', ['npm', ...args].join(' ')],
+    options: { windowsVerbatimArguments: true, windowsHide: true },
+  };
+}
+
+export function spawnNpm(args, options = {}, { spawnSync = defaultSpawnSync, platform = process.platform, env = process.env } = {}) {
+  const inv = npmInvocation(args, { platform, env });
+  return spawnSync(inv.command, inv.args, { ...options, ...inv.options });
+}

package/src/core/update.js

@@ -1,6 +1,7 @@
 import { spawnSync as defaultSpawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { spawnNpm } from './npmCommand.js';
 
 export const UKIT_PACKAGE_NAME = '@ngockhoale/ukit';
 
@@ -50,11 +51,11 @@ export function resolveGlobalUkitBin({ spawnSync = defaultSpawnSync } = {}) {
 // a timeout as actionable ("npm query timed out — is the network/proxy wedged?")
 // instead of misattributing it to a missing file.
 function resolveGlobalUkitBinDetailed({ spawnSync = defaultSpawnSync } = {}) {
-  const result = spawnSync('npm', ['root', '-g'], {
+  const result = spawnNpm(['root', '-g'], {
     encoding: 'utf8',
     timeout: NPM_QUERY_TIMEOUT_MS,
     killSignal: KILL_ON_TIMEOUT,
-  });
+  }, { spawnSync });
   if (result.error || result.status !== 0 || typeof result.stdout !== 'string') {
     return { binPath: null, timedOut: result.error?.code === 'ETIMEDOUT' };
   }
@@ -113,11 +114,11 @@ export function runInstallAfterUpdate({
 }
 
 export function updateUkit({ spawnSync = defaultSpawnSync } = {}) {
-  const result = spawnSync('npm', ['install', '-g', UKIT_PACKAGE_NAME], {
+  const result = spawnNpm(['install', '-g', UKIT_PACKAGE_NAME], {
     stdio: 'inherit',
     timeout: NPM_INSTALL_TIMEOUT_MS,
     killSignal: KILL_ON_TIMEOUT,
-  });
+  }, { spawnSync });
 
   if (result.error) {
     throw new Error(`Failed to run npm install -g ${UKIT_PACKAGE_NAME}: ${result.error.message}`);

package/src/core/updateSafety.js

@@ -3,6 +3,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { spawnSync as defaultSpawnSync } from 'node:child_process';
 import { readInstallMetadata } from './metadata.js';
+import { spawnNpm } from './npmCommand.js';
 import { writeFileAtomic } from './fileOps.js';
 
 // F5: safety net around `ukit update`.
@@ -42,8 +43,9 @@ function insideProject(projectRoot, rel) {
 export async function preflightUpdate({ projectRoot, spawnSync = defaultSpawnSync, checkNpm = true } = {}) {
   const problems = [];
   if (checkNpm) {
-    const r = spawnSync('npm', ['--version'], { encoding: 'utf8', timeout: 15_000, killSignal: 'SIGKILL' });
-    if (r.error || r.status !== 0) problems.push(`npm is not runnable (${r.error?.message ?? `exit ${r.status}`})`);
+    const r = spawnNpm(['--version'], { encoding: 'utf8', timeout: 15_000, killSignal: 'SIGKILL' }, { spawnSync });
+    const detail = typeof r.stderr === 'string' ? r.stderr.trim().split(/\r?\n/)[0] : '';
+    if (r.error || r.status !== 0) problems.push(`npm is not runnable (${r.error?.message ?? `exit ${r.status}`}${detail ? `: ${detail}` : ''})`);
   }
   try {
     await readInstallMetadata(path.join(projectRoot, INSTALL_META_REL));