nodedex 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodedex",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "mcpName": "io.github.NodeDex/nodedex",
   "description": "NodeDex — persistent knowledge-graph memory (MCP server) for AI agents: decisions with their why, dead-ends, and causal chains, built automatically from your agent's conversations",
   "license": "AGPL-3.0-or-later",

package/scripts/nodedex-entry.mjs

@@ -12,12 +12,20 @@
  * In the repo, build first with `npm run build` in server/ (this loads ../dist/server.js);
  * the published npm package ships dist/ + the compiled TUI (tui-dist/) ready to run.
  */
-import { spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { spawn, execSync } from "node:child_process";
+import { existsSync, readFileSync, mkdirSync, writeFileSync, unlinkSync, readdirSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { dirname, resolve, join } from "node:path";
 import { homedir } from "node:os";
 
+// Fail CLEARLY on old Node — the entry + server use global fetch / AbortSignal.timeout
+// (Node ≥ 18); without this guard an old runtime dies with a cryptic ReferenceError.
+const nodeMajor = Number(process.versions.node.split(".")[0]);
+if (nodeMajor < 18) {
+  console.error(`[nodedex] Node ${process.versions.node} is too old — NodeDex needs Node >= 18. Upgrade at https://nodejs.org`);
+  process.exit(1);
+}
+
 const here = dirname(fileURLToPath(import.meta.url));
 const args = process.argv.slice(2);
 const cmd = (args[0] || "").toLowerCase();
@@ -35,6 +43,10 @@ Usage:
     --provider openrouter --key sk-or-...   [--model google/gemini-2.5-flash-lite]
     --provider local --base-url http://localhost:11434/v1 --model <id>
     [--port 3001] [--db <name>] [--capture hermes,claude-code | none] [--dry-run]
+  nodedex stop      Stop running NodeDex servers: \`stop\` = the ones it knows
+                    (pidfiles + config port), \`stop 3002\` = that port,
+                    \`stop --all\` = sweep the whole discovery range. Only kills
+                    a process after confirming a NodeDex answers on the port.
   nodedex uninstall Remove ALL local data + config (~/.nodedex) — asks first;
                     --yes skips the prompt (scripts). Does not remove the package.
   nodedex help      Show this message
@@ -95,12 +107,103 @@ function startServer() {
     );
     process.exit(1);
   }
+  writePidFile();
   // On Windows a bare absolute path ("C:\\...") is rejected by the ESM loader;
   // it must be a file:// URL.
   import(pathToFileURL(distServer).href);
   startEnabledWatchers();
 }
 
+// ─── pidfiles + `nodedex stop` ─────────────────────────────────────────────────
+// The server runs IN-PROCESS of this entry (import above), so this pid IS the
+// server pid. `nodedex stop [port…|--all]` reads these first; for servers it
+// didn't start (TUI-launched, bare node) it falls back to a port→PID lookup.
+function runDir() { return join(homedir(), ".nodedex", "run"); }
+function pidFileFor(port) { return join(runDir(), `server-${port}.pid`); }
+
+function writePidFile() {
+  try {
+    const port = Number(process.env.PORT) || 3001;
+    mkdirSync(runDir(), { recursive: true });
+    writeFileSync(pidFileFor(port), String(process.pid));
+    process.on("exit", () => { try { unlinkSync(pidFileFor(port)); } catch { /* */ } });
+  } catch { /* best-effort — stop falls back to port lookup */ }
+}
+
+/** PID listening on a local port — Windows netstat / unix lsof. Null if none. */
+function pidOnPort(port) {
+  try {
+    if (process.platform === "win32") {
+      const out = execSync("netstat -ano -p tcp", { encoding: "utf8" });
+      for (const line of out.split(/\r?\n/)) {
+        const m = line.trim().match(/^TCP\s+\S+:(\d+)\s+\S+\s+LISTENING\s+(\d+)$/i);
+        if (m && Number(m[1]) === port) return Number(m[2]);
+      }
+      return null;
+    }
+    const out = execSync(`lsof -ti tcp:${port} -sTCP:LISTEN`, { encoding: "utf8" });
+    const pid = Number(out.trim().split(/\s+/)[0]);
+    return Number.isInteger(pid) ? pid : null;
+  } catch { return null; }
+}
+
+function killPid(pid) {
+  try {
+    if (process.platform === "win32") execSync(`taskkill /PID ${pid} /T /F`, { stdio: "ignore" });
+    else process.kill(pid, "SIGTERM");
+    return true;
+  } catch { return false; }
+}
+
+/** `nodedex stop [port…] | --all` — stop NodeDex servers by port. Only kills a
+ *  process after confirming a NodeDex answers on that port (never blind-kills). */
+async function stopServers() {
+  const wantAll = args.includes("--all");
+  const explicit = args.slice(1).map(Number).filter((n) => Number.isInteger(n) && n > 0);
+
+  // Candidate ports: explicit args, or (for --all / bare stop) pidfiles + config
+  // port + the discovery range.
+  let ports = explicit;
+  if (ports.length === 0) {
+    const set = new Set();
+    try {
+      for (const f of readdirSync(runDir())) {
+        const m = f.match(/^server-(\d+)\.pid$/);
+        if (m) set.add(Number(m[1]));
+      }
+    } catch { /* no run dir */ }
+    try {
+      const c = JSON.parse(readFileSync(join(homedir(), ".nodedex", "config.json"), "utf8"));
+      if (Number.isInteger(c.port)) set.add(c.port);
+    } catch { /* */ }
+    if (wantAll) for (const p of [3001, 3002, 3003, 3004, 3005, 3006, 3007, 3008, 3009, 3099]) set.add(p);
+    ports = [...set];
+  }
+  if (ports.length === 0) { console.log("[nodedex stop] no known servers (no pidfiles, no config port). Pass a port: nodedex stop 3001"); return; }
+
+  let stopped = 0;
+  for (const port of ports.sort((a, b) => a - b)) {
+    // Confirm it's a NodeDex before killing anything on the port.
+    let isNodedex = false;
+    try {
+      const r = await fetch(`http://127.0.0.1:${port}/api/health`, { signal: AbortSignal.timeout(1200) });
+      isNodedex = r.ok;
+    } catch { /* not up */ }
+    if (!isNodedex) {
+      if (explicit.length) console.log(`  :${port} — no NodeDex answering, skipped`);
+      continue;
+    }
+    let pid = null;
+    try { pid = Number(readFileSync(pidFileFor(port), "utf8").trim()) || null; } catch { /* no pidfile */ }
+    if (!pid) pid = pidOnPort(port);
+    if (!pid) { console.log(`  :${port} — NodeDex is up but its PID couldn't be resolved (kill it by hand)`); continue; }
+    const ok = killPid(pid);
+    console.log(`  :${port} — ${ok ? `stopped (pid ${pid})` : `failed to kill pid ${pid}`}`);
+    if (ok) { stopped++; try { unlinkSync(pidFileFor(port)); } catch { /* */ } }
+  }
+  console.log(`[nodedex stop] ${stopped} server(s) stopped.`);
+}
+
 // Headless path parity with the TUI: `nodedex run` also brings up whichever capture
 // watchers the config enables (the TUI spawns its own when it runs; this covers
 // server-only / agent-driven installs where no TUI is ever opened).
@@ -371,6 +474,9 @@ switch (cmd) {
   case "doctor":
     void connectCard();
     break;
+  case "stop":
+    void stopServers();
+    break;
   case "uninstall":
     void uninstall();
     break;

package/tui-dist/api.js

@@ -9,9 +9,20 @@
 export function prefer127(url) {
     return url.replace(/\/\/localhost(?=[:/]|$)/i, "//127.0.0.1");
 }
+import { loadConfig } from "./config.js";
 // The active server. Mutable so the Servers pane can switch which graph the
 // TUI reads at runtime (was a const — multi-server switching needs it live).
-let currentBase = prefer127((process.env.NODEDEX_TUI_API || "http://localhost:3001").replace(/\/$/, ""));
+// Default base honors the CONFIG port — `nodedex run` starts the server on
+// config.json's port, so the TUI must aim there by default, not a hardcoded 3001
+// (the "ran nodedex, then nodedex tui, can't connect" bug).
+const configPort = (() => { try {
+    const p = loadConfig().port;
+    return Number.isInteger(p) && p > 0 ? p : null;
+}
+catch {
+    return null;
+} })();
+let currentBase = prefer127((process.env.NODEDEX_TUI_API || `http://localhost:${configPort || 3001}`).replace(/\/$/, ""));
 // Per-server API tokens. A server launched with NODEDEX_API_TOKEN gates its WHOLE REST API,
 // so the TUI must send the token to read it. Keyed by normalized base url; setBase picks the
 // active one up automatically, so every connect path authenticates without extra plumbing.

package/tui-dist/onboarding.js

@@ -16,7 +16,7 @@ import { Box, Text, useApp, useInput } from "ink";
 import { Logo } from "./components.js";
 import { theme } from "./theme.js";
 import { saveConfig, DEFAULT_PORT, DEFAULT_LOCAL_BASE_URL, RECOMMENDED_MODELS, isTrainsOnPrompts, validateOpenRouterKey, listDbs, dbPathForName, scanLocalModels, scanCaptureHosts, setHermesCapture, setClaudeCapture, } from "./config.js";
-import { launchServer, genToken, launchWatcher, stopWatcher } from "./servers.js";
+import { launchServer, genToken, launchWatcher, stopWatcher, scanFreePorts } from "./servers.js";
 import { probeServer, setBase } from "./api.js";
 import { writeConnectSnippets } from "./connect-snippets.js";
 const README_URL = "https://github.com/NodeDex/NodeDex-v0.1#connect-your-agent";
@@ -106,22 +106,16 @@ export function Onboarding({ onDone }) {
         });
         return () => { cancelled = true; };
     }, [step, localScanNonce]);
-    // Detect free ports when entering the port step (reuse probeServer: a port with no
-    // Nodedex responding is free enough to claim; launch fails loudly otherwise).
+    // Detect free ports when entering the port step. scanFreePorts checks actual
+    // BINDABILITY (momentary bind + close), not just "no NodeDex answering" — a port
+    // held by any other app must never be offered, or the launch hangs and fails.
     useEffect(() => {
         if (step !== "port" || freePorts.length > 0)
             return;
         let cancelled = false;
         (async () => {
             setStatus("Scanning for free ports…");
-            const found = [];
-            for (const p of [3001, 3002, 3003, 3004, 3005, 3006, 3007, 3008]) {
-                const probe = await probeServer(`http://localhost:${p}`);
-                if (!probe.up)
-                    found.push(p);
-                if (found.length >= 5)
-                    break;
-            }
+            const found = await scanFreePorts(undefined, 5);
             if (cancelled)
                 return;
             setStatus("");
@@ -144,7 +138,9 @@ export function Onboarding({ onDone }) {
             return;
         }
         const url = `http://localhost:${port}`;
-        const deadline = Date.now() + 30000;
+        // 60s: a first boot on a slow disk / AV-scanned Windows can take a while to
+        // import 400+ files; the embedder download is background and doesn't block listen.
+        const deadline = Date.now() + 60000;
         while (Date.now() < deadline) {
             const probe = await probeServer(url);
             if (probe.up) {

package/tui-dist/servers.js

@@ -23,7 +23,7 @@ import { dirname, resolve } from "path";
 import { homedir } from "os";
 import { mkdirSync, createWriteStream, readFileSync, writeFileSync, existsSync, readdirSync, statSync, renameSync, rmSync } from "fs";
 import { probeServer, prefer127, registerToken } from "./api.js";
-import { providerEnv } from "./config.js";
+import { providerEnv, loadConfig } from "./config.js";
 import { randomBytes } from "node:crypto";
 // Server dir — two layouts:
 //   repo/dev:  <repo>/tui/src/servers.ts  → ../../server   (runs src via tsx)
@@ -64,7 +64,16 @@ const SESSION_FILE = resolve(NODEDEX_HOME, "tui-session.json");
 const LOG_DIR = resolve(NODEDEX_HOME, "tui-logs");
 // ports probed during discovery (plus any pinned urls). 127.0.0.1, not localhost —
 // the IPv4 host skips Windows's ::1-first penalty (see prefer127 in api.ts).
-const CANDIDATE_PORTS = [3001, 3002, 3003, 3004, 3005, 3099];
+// The CONFIG port comes first: it's where `nodedex run` puts the server, and the
+// wizard's picker offers up to 3009 — both must be discoverable.
+const CONFIG_PORT = (() => { try {
+    const p = loadConfig().port;
+    return Number.isInteger(p) && p > 0 ? p : null;
+}
+catch {
+    return null;
+} })();
+const CANDIDATE_PORTS = [...new Set([...(CONFIG_PORT ? [CONFIG_PORT] : []), 3001, 3002, 3003, 3004, 3005, 3006, 3007, 3008, 3009, 3099])];
 const candidateUrl = (p) => `http://127.0.0.1:${p}`;
 // ─── available DB files (for the launch/swap picker) ────────────────────────
 // A port is just an access point; the DB is the content. Let the user pick the
@@ -260,8 +269,14 @@ export async function restoreSession() {
     // must NOT strand the TUI on a dead url, so fall back to a live MANAGED server and adopt it
     // as the focus so the next restart is clean.
     const connected = s.connected?.url ?? null;
-    if (!connected && s.managed.length === 0)
+    // No TUI session at all — but `nodedex run` (headless) starts the server on the
+    // CONFIG port and never writes tui-session.json. The config is the shared source
+    // of truth, so probe it before concluding there's nothing to connect to.
+    if (!connected && s.managed.length === 0) {
+        if (CONFIG_PORT && (await probeServer(candidateUrl(CONFIG_PORT))).up)
+            return candidateUrl(CONFIG_PORT);
         return null;
+    }
     const deadline = Date.now() + 12000;
     while (Date.now() < deadline) {
         if (connected && (await probeServer(connected)).up)
@@ -274,6 +289,10 @@ export async function restoreSession() {
                 return url;
             }
         }
+        // Session servers all down — a CLI-launched server on the config port still wins
+        // over waiting out the deadline on dead entries.
+        if (CONFIG_PORT && (await probeServer(candidateUrl(CONFIG_PORT))).up)
+            return candidateUrl(CONFIG_PORT);
         await new Promise((res) => setTimeout(res, 300));
     }
     return connected ?? (s.managed[0] ? candidateUrl(s.managed[0].port) : null); // hand back; poll shows state