@ngockhoale/ukit 2.2.5 → 2.2.7

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 All notable changes to UKit are documented here.
 
+## 2.2.7 - 2026-08-28
+
+Follow-up to 2.2.6: that release only made the wrong-runtime failure message *explain* the
+`UKIT_NODE_PATH` workaround better, but a user still had to diagnose the error and export the
+variable by hand. This release removes the manual step for the common case.
+
+### Fixed
+
+- **The omp bridge now auto-detects a working Node.js binary instead of requiring
+  `UKIT_NODE_PATH` to be set by hand.** [`ukit-bridge.js`](.omp/hooks/pre/ukit-bridge.js) probes
+  `process.execPath` with `--version` before trusting it; if that fails (e.g. a Bun-hosted or
+  self-compiled omp reporting its own binary as `process.execPath`), it falls back to the bare
+  `node` command name and lets normal OS `PATH` resolution find a real Node.js binary — this
+  works the same way on macOS, Linux, and Windows, since Node's `child_process` spawn does `PATH`
+  lookup for bare executable names on all three. An explicit `UKIT_NODE_PATH` still always wins
+  and skips the probe. The probe result is cached for the life of the omp process, so it only
+  runs once, not on every tool call. The transport-failure message's `UKIT_NODE_PATH` hint now
+  only appears when both the probe and the `node` PATH fallback have failed.
+
+### Added
+
+- **1 regression test** in `tests/hooks/ompHookBridge.test.js` — with `UKIT_NODE_PATH` unset and
+  `process.execPath` mocked to fail the `--version` probe, the bridge falls back to invoking the
+  bare `node` command instead of blocking the tool call.
+
+## 2.2.6 - 2026-08-27
+
+Follow-up to a real-world report: a user on a Bun-hosted/self-compiled omp build kept getting
+every Edit/Write blocked with `UKit OMP hook runner failed before producing a valid result
+(killed=true, ..., runtime=/Users/.../bin/omp)`. The diagnostic added in 2.2.4 was already
+honest about the failure, but it did not say *why* — `runtime=` pointed straight at omp's own
+binary (proof that `process.execPath` inside that omp build resolves to omp itself, not a real
+Node.js binary), yet the message never told the user the fix was to set `UKIT_NODE_PATH`.
+
+### Fixed
+
+- **The omp bridge's transport-failure message named the wrong-runtime symptom but never the
+  fix.** [`ukit-bridge.js`](.omp/hooks/pre/ukit-bridge.js) already resolved
+  `process.env.UKIT_NODE_PATH || process.execPath` and reported the resolved `runtime` on failure
+  (2.2.4), but a user seeing `runtime=/Users/lenk/.local/bin/omp` had no way to know that string
+  meant "wrong binary" or what to do about it. When `UKIT_NODE_PATH` is unset, the failure
+  message now appends: the reported runtime may not be a real Node.js binary, and the exact fix —
+  `export UKIT_NODE_PATH="$(command -v node)"`. No behavior change when `UKIT_NODE_PATH` is
+  already set.
+
+### Added
+
+- **2 regression tests** in `tests/hooks/ompHookBridge.test.js` (case 13) — the wrong-runtime
+  hint appears when `UKIT_NODE_PATH` is unset, and is omitted when it is already set.
+
 ## 2.2.5 - 2026-08-27
 
 Follow-up to the user's report that UKit had become too heavy-handed: too many hook scripts firing per tool call, too much blocking, and a concrete false-positive in the destructive-command gate itself. This wave trims default hook wiring and fixes the false positive, while explicitly preserving `rm`/destructive-command protection as instructed.

package/package.json

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

package/templates/.omp/hooks/pre/ukit-bridge.js

@@ -8,6 +8,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
 import {
   evaluateCompletion,
   incrementContinuation,
@@ -181,6 +182,30 @@ function recordHookErrorDiagnostic(projectRoot, sessionId, diagnostic) {
   }
 }
 
+// Cached across the omp process lifetime: resolution below spawns a probe process, and every
+// tool call would otherwise pay that cost again.
+let cachedNodeExecutable = null;
+
+function isRealNodeBinary(candidate) {
+  try {
+    const probe = spawnSync(candidate, ['--version'], { timeout: 2000, encoding: 'utf8' });
+    return !probe.error && typeof probe.stdout === 'string' && /^v\d+\.\d+\.\d+/.test(probe.stdout.trim());
+  } catch {
+    return false;
+  }
+}
+
+// Do not blindly trust process.execPath: under a Bun-hosted or self-compiled omp, it can report
+// omp's own binary path instead of a real Node.js one. Probe it first; if it fails, fall back to
+// the bare "node" command name so PATH resolution (cross-platform: macOS/Linux/Windows) finds a
+// real Node.js binary automatically, without requiring a manual UKIT_NODE_PATH export.
+function resolveNodeExecutable() {
+  if (process.env.UKIT_NODE_PATH) return process.env.UKIT_NODE_PATH;
+  if (cachedNodeExecutable) return cachedNodeExecutable;
+  cachedNodeExecutable = isRealNodeBinary(process.execPath) ? process.execPath : 'node';
+  return cachedNodeExecutable;
+}
+
 export async function runScriptChain(
   pi,
   scripts,
@@ -195,8 +220,7 @@ export async function runScriptChain(
 
   const runnerPath = path.join(projectRoot, '.claude', 'ukit', 'runtime', 'hook-chain-runner.mjs');
   const scriptPaths = scripts.map((scriptName) => path.join(projectRoot, '.claude', 'hooks', scriptName));
-  // Do not blindly trust process.execPath: under a Bun-hosted omp, it points at bun, not node.
-  const nodeExecutable = process.env.UKIT_NODE_PATH || process.execPath;
+  const nodeExecutable = resolveNodeExecutable();
   const startedAt = Date.now();
   let execResult;
   try {
@@ -241,10 +265,15 @@ export async function runScriptChain(
       wrapperError: chainResult?.wrapperError || null,
     };
     recordHookErrorDiagnostic(projectRoot, payload.session_id, diagnostic);
+    const nodePathHint = process.env.UKIT_NODE_PATH
+      ? ''
+      : ` UKit already tried process.execPath and a "node" PATH lookup; neither resolved to a `
+        + `working Node.js binary (runtime="${diagnostic.nodeExecutable}"). Set UKIT_NODE_PATH to `
+        + `an explicit Node.js binary path to override, e.g.: export UKIT_NODE_PATH="$(command -v node)".`;
     const reason = `UKit OMP hook runner failed before producing a valid result `
       + `(killed=${diagnostic.killed}, code=${diagnostic.code}, elapsedMs=${diagnostic.elapsedMs}, `
       + `runtime=${diagnostic.nodeExecutable}). No safety-gate verdict was available for [${scripts.join(', ')}]. `
-      + `See .ukit/storage/cache/hook-errors/.`;
+      + `See .ukit/storage/cache/hook-errors/.${nodePathHint}`;
     if (failClosedOnTransportError) {
       return { block: true, reason, context, invoked };
     }