pi-knowledge 0.5.3 → 0.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.5.4] - 2026-07-23
4
+
5
+ ### Fixed
6
+ - Prevented missing Windows `node.exe` from surfacing as an uncaught `uv_spawn 'node'` failure by resolving Node before worker startup and wrapping synchronous spawn failures with model-worker diagnostics.
7
+ - Expanded Windows Node discovery to common Node, Volta, and NVM install locations, and stripped accidental surrounding quotes from `PI_KNOWLEDGE_NODE_PATH` paths with spaces.
8
+
9
+
3
10
  ## [0.5.3] - 2026-07-23
4
11
 
5
12
  ### Fixed
@@ -1,6 +1,6 @@
1
1
  import { execFileSync, fork, spawn } from "node:child_process";
2
2
  import { existsSync } from "node:fs";
3
- import { basename } from "node:path";
3
+ import { basename, delimiter, join } from "node:path";
4
4
  import { StringDecoder } from "node:string_decoder";
5
5
  import { fileURLToPath } from "node:url";
6
6
  let worker = null;
@@ -26,6 +26,9 @@ function parseNodeMajor(version) {
26
26
  const major = Number(match.groups.major);
27
27
  return Number.isInteger(major) ? major : null;
28
28
  }
29
+ function toError(error) {
30
+ return error instanceof Error ? error : new Error(String(error));
31
+ }
29
32
  function validateNodeExecPath(candidate) {
30
33
  const version = execFileSync(candidate, ["--version"], {
31
34
  encoding: "utf8",
@@ -39,13 +42,63 @@ function validateNodeExecPath(candidate) {
39
42
  }
40
43
  return candidate;
41
44
  }
45
+ function normalizeExecutableCandidate(value) {
46
+ const trimmed = value.trim();
47
+ if (trimmed.length >= 2 &&
48
+ ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'")))) {
49
+ return trimmed.slice(1, -1).trim();
50
+ }
51
+ return trimmed;
52
+ }
53
+ function pathEnvValue() {
54
+ return process.env.PATH ?? process.env.Path ?? process.env.path ?? "";
55
+ }
56
+ function appendIfPresent(candidates, value, suffix) {
57
+ const normalized = value ? normalizeExecutableCandidate(value) : "";
58
+ if (!normalized)
59
+ return;
60
+ candidates.push(suffix ? join(normalized, suffix) : normalized);
61
+ }
62
+ function getWindowsNodeCandidates() {
63
+ const candidates = [];
64
+ appendIfPresent(candidates, process.env.NVM_SYMLINK, "node.exe");
65
+ appendIfPresent(candidates, process.env.VOLTA_HOME, join("bin", "node.exe"));
66
+ appendIfPresent(candidates, process.env.ProgramFiles, join("nodejs", "node.exe"));
67
+ appendIfPresent(candidates, process.env["ProgramFiles(x86)"], join("nodejs", "node.exe"));
68
+ appendIfPresent(candidates, process.env.LOCALAPPDATA, join("Programs", "nodejs", "node.exe"));
69
+ for (const directory of pathEnvValue().split(delimiter)) {
70
+ appendIfPresent(candidates, directory, "node.exe");
71
+ }
72
+ return candidates;
73
+ }
74
+ function getNodeCandidates() {
75
+ const candidates = [];
76
+ appendIfPresent(candidates, process.env.NODE);
77
+ if (process.platform === "win32") {
78
+ candidates.push(...getWindowsNodeCandidates());
79
+ }
80
+ else {
81
+ for (const directory of pathEnvValue().split(delimiter)) {
82
+ appendIfPresent(candidates, directory, "node");
83
+ }
84
+ }
85
+ candidates.push("node");
86
+ return [...new Set(candidates)];
87
+ }
42
88
  function getNodeExecPath() {
43
89
  if (resolvedNodeExecPath)
44
90
  return resolvedNodeExecPath;
45
- const configured = process.env.PI_KNOWLEDGE_NODE_PATH?.trim();
91
+ const configured = process.env.PI_KNOWLEDGE_NODE_PATH
92
+ ? normalizeExecutableCandidate(process.env.PI_KNOWLEDGE_NODE_PATH)
93
+ : "";
46
94
  if (configured) {
47
- resolvedNodeExecPath = validateNodeExecPath(configured);
48
- return resolvedNodeExecPath;
95
+ try {
96
+ resolvedNodeExecPath = validateNodeExecPath(configured);
97
+ return resolvedNodeExecPath;
98
+ }
99
+ catch (error) {
100
+ throw new Error(`PI_KNOWLEDGE_NODE_PATH does not point to a usable Node ${MIN_NODE_MAJOR}+ executable: ${toError(error).message}`);
101
+ }
49
102
  }
50
103
  const execName = basename(process.execPath).toLowerCase();
51
104
  const currentProcessLooksLikeNode = execName === "node" || execName === "node.exe";
@@ -56,8 +109,7 @@ function getNodeExecPath() {
56
109
  return resolvedNodeExecPath;
57
110
  }
58
111
  }
59
- const envNode = process.env.NODE?.trim();
60
- for (const candidate of [envNode, "node"].filter((value) => Boolean(value))) {
112
+ for (const candidate of getNodeCandidates()) {
61
113
  try {
62
114
  resolvedNodeExecPath = validateNodeExecPath(candidate);
63
115
  return resolvedNodeExecPath;
@@ -66,7 +118,7 @@ function getNodeExecPath() {
66
118
  // Try the next candidate before surfacing a deterministic error below.
67
119
  }
68
120
  }
69
- throw new Error(`Node ${MIN_NODE_MAJOR}+ is required for local pi-knowledge embeddings. Set PI_KNOWLEDGE_NODE_PATH to a working node.exe path.`);
121
+ throw new Error(`Node ${MIN_NODE_MAJOR}+ is required for local pi-knowledge embeddings, but no usable node executable was found. Install Node ${MIN_NODE_MAJOR}+ or set PI_KNOWLEDGE_NODE_PATH to the full node.exe path.`);
70
122
  }
71
123
  function appendWorkerStderr(current, chunk) {
72
124
  const next = `${current}${chunk.toString("utf-8")}`;
@@ -96,7 +148,7 @@ class ModelWorkerTransport {
96
148
  pending = new Map();
97
149
  stderrTail = "";
98
150
  exited = false;
99
- spawnError = null;
151
+ terminalError = null;
100
152
  constructor(child) {
101
153
  this.child = child;
102
154
  child.stderr?.on("data", (chunk) => {
@@ -110,21 +162,21 @@ class ModelWorkerTransport {
110
162
  this.rejectPending(formatWorkerExitError(code, signal, this.stderrTail));
111
163
  });
112
164
  child.on("error", (error) => {
113
- this.spawnError = error;
165
+ this.terminalError = formatWorkerSpawnError(error, this.stderrTail);
114
166
  this.exited = true;
115
167
  if (worker === this)
116
168
  worker = null;
117
- this.rejectPending(formatWorkerSpawnError(error, this.stderrTail));
169
+ this.rejectPending(this.terminalError);
118
170
  });
119
171
  }
120
172
  isConnected() {
121
- return !this.exited && !this.child.killed && !this.spawnError && this.isTransportConnected();
173
+ return !this.exited && !this.child.killed && !this.terminalError && this.isTransportConnected();
122
174
  }
123
175
  request(message, signal) {
124
176
  if (signal?.aborted)
125
177
  throw new Error("Cancelled");
126
178
  if (!this.isConnected())
127
- throw new Error("Model worker is not connected");
179
+ throw this.terminalError ?? new Error("Model worker is not connected");
128
180
  const id = nextRequestId++;
129
181
  const { promise, resolve, reject } = Promise.withResolvers();
130
182
  let abortHandler;
@@ -196,11 +248,11 @@ class IpcModelWorkerTransport extends ModelWorkerTransport {
196
248
  this.ipcChild = ipcChild;
197
249
  ipcChild.on("message", (message) => this.handleWorkerResponse(message));
198
250
  }
199
- static create(workerPath) {
251
+ static create(workerPath, nodeExecPath) {
200
252
  let child;
201
253
  try {
202
254
  child = fork(workerPath, {
203
- execPath: getNodeExecPath(),
255
+ execPath: nodeExecPath,
204
256
  execArgv: getWorkerExecArgv(),
205
257
  stdio: ["ignore", "ignore", "pipe", "ipc"],
206
258
  env: process.env,
@@ -226,12 +278,18 @@ class IpcModelWorkerTransport extends ModelWorkerTransport {
226
278
  class StdioModelWorkerTransport extends ModelWorkerTransport {
227
279
  decoder = new StringDecoder("utf8");
228
280
  stdoutBuffer = "";
229
- constructor(workerPath) {
230
- const child = spawn(getNodeExecPath(), [...getWorkerExecArgv(), workerPath, "--stdio"], {
231
- stdio: ["pipe", "pipe", "pipe"],
232
- env: process.env,
233
- windowsHide: true,
234
- });
281
+ constructor(workerPath, nodeExecPath) {
282
+ let child;
283
+ try {
284
+ child = spawn(nodeExecPath, [...getWorkerExecArgv(), workerPath, "--stdio"], {
285
+ stdio: ["pipe", "pipe", "pipe"],
286
+ env: process.env,
287
+ windowsHide: true,
288
+ });
289
+ }
290
+ catch (error) {
291
+ throw formatWorkerSpawnError(toError(error), "");
292
+ }
235
293
  super(child);
236
294
  if (!child.stdin || !child.stdout) {
237
295
  if (!child.killed)
@@ -279,7 +337,9 @@ function getWorker() {
279
337
  if (worker?.isConnected())
280
338
  return worker;
281
339
  const workerPath = getWorkerPath();
282
- worker = IpcModelWorkerTransport.create(workerPath) ?? new StdioModelWorkerTransport(workerPath);
340
+ const nodeExecPath = getNodeExecPath();
341
+ worker =
342
+ IpcModelWorkerTransport.create(workerPath, nodeExecPath) ?? new StdioModelWorkerTransport(workerPath, nodeExecPath);
283
343
  return worker;
284
344
  }
285
345
  export async function embedInModelWorker(texts, prefix, signal) {
@@ -30,7 +30,7 @@ Default data storage is `~/.pi/knowledge` under Pi and `~/.omp/knowledge` under
30
30
  | `PI_KNOWLEDGE_EMBEDDING_IDLE_MS` | `30000` | Idle timer used only when native idle disposal coordination is enabled. Mainly for lifecycle stress tests. |
31
31
  | `PI_KNOWLEDGE_OFFLINE` | unset | Use with a pre-populated model cache for offline local model operation. See `docs/offline-mode.md`. |
32
32
 
33
- Local embeddings require a real Node 22+ executable for the isolated model worker. `pi-knowledge` first tries Node IPC and automatically falls back to a stdin/stdout JSONL worker transport when the host runtime does not expose `child_process.fork().send()`, which can happen in Windows OMP compatibility layers. If worker startup fails, set `PI_KNOWLEDGE_NODE_PATH` to the full `node.exe` path or use an OpenAI-compatible embedding provider.
33
+ Local embeddings require a real Node 22+ executable for the isolated model worker. `pi-knowledge` first tries Node IPC and automatically falls back to a stdin/stdout JSONL worker transport when the host runtime does not expose `child_process.fork().send()`, which can happen in Windows OMP compatibility layers. On Windows it searches common Node, Volta, NVM, and `PATH` locations before failing. If worker startup still fails, set `PI_KNOWLEDGE_NODE_PATH` to the full `node.exe` path such as `C:\Program Files\nodejs\node.exe`; accidental surrounding quotes are ignored. OpenAI-compatible embeddings avoid the local worker entirely.
34
34
 
35
35
  API embedding failures intentionally surface by default. Silent fallback can hide bad API keys, wrong base URLs, unsupported model names, or context-window errors and can produce a KB with a different embedding model than intended.
36
36
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-knowledge",
3
- "version": "0.5.3",
3
+ "version": "0.5.4",
4
4
  "description": "Local-first RAG knowledge base for Pi and OMP coding agents with hybrid code/doc search, reranking, diagnostics, and large-project indexing",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",