wicked-brain 0.15.2 → 0.15.3

package/README.md

@@ -159,8 +159,50 @@ The viewer has no auth. It's localhost-only, same-machine trust.
 | `wicked-brain:retag` | Backfill synonym-expanded tags across all chunks for better search recall |
 | `wicked-brain:update` | Check npm for updates and reinstall skills across all detected CLIs |
 | `wicked-brain:lsp` | Universal code intelligence via LSP — hover, go-to-definition, diagnostics, completions |
+| `wicked-brain:graph` | Code-relationship graph — blast radius, callers, lineage — backed by a static code graph |
 | `wicked-brain:ui` | Open the read-only browser viewer — Material-styled Search + Wiki tabs over `http://localhost:<port>/` |
 
+## Code Graph (offline / air-gapped)
+
+`wicked-brain:graph` (blast radius, callers, lineage) is backed by the
+[`@colbymchenry/codegraph`](https://www.npmjs.com/package/@colbymchenry/codegraph)
+CLI. By **default** the brain resolves that CLI by shelling out to
+`npx @colbymchenry/codegraph` — which **fetches from the npm registry and will
+not work air-gapped**. On an offline/air-gapped machine, point the brain at a
+pre-installed binary with the **`WICKED_CODEGRAPH_BIN`** environment variable.
+
+`WICKED_CODEGRAPH_BIN` sits at the **top** of the resolution ladder:
+
+```
+WICKED_CODEGRAPH_BIN  →  brain _meta/codegraph.json {bin}  →  PATH  →  source node_modules/.bin/codegraph  →  npx (last resort, network)
+```
+
+**Offline install path:**
+
+```bash
+# 1. On a connected machine, install codegraph globally (or vendor it):
+npm install -g @colbymchenry/codegraph        # provides a `codegraph` on PATH
+#    …or install it into the project: npm install @colbymchenry/codegraph
+
+# 2. On the air-gapped machine, point the brain at the binary:
+export WICKED_CODEGRAPH_BIN=/usr/local/bin/codegraph     # macOS/Linux
+#    A .mjs/.js path is run via node; any other path is executed directly.
+```
+
+```powershell
+# Windows (PowerShell)
+$env:WICKED_CODEGRAPH_BIN = "C:\tools\codegraph\codegraph.cmd"
+```
+
+Notes:
+- Setting `WICKED_CODEGRAPH_BIN` to an **empty string** is a deliberate **kill
+  switch** — graph queries return `engine: "unavailable"` instead of falling
+  through to the network `npx` path.
+- A per-brain alternative to the env var is `_meta/codegraph.json` with
+  `{ "bin": "/path/to/codegraph" }`.
+- If nothing resolves, graph queries degrade gracefully to
+  `engine: "unavailable"` rather than returning a misleading empty graph.
+
 ## Multi-Brain Federation
 
 Brains can link to other brains. A personal research brain can reference a team standards brain. A client brain can inherit from a company knowledge base.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain",
-  "version": "0.15.2",
+  "version": "0.15.3",
   "type": "module",
   "description": "Digital brain as skills for AI coding CLIs — no vector DB, no embeddings, no infrastructure",
   "keywords": [

package/server/bin/wicked-brain-call.mjs

@@ -106,6 +106,20 @@ function readMetaConfig(brainPath) {
   }
 }
 
+// The brain the caller EXPECTS to be on this port. The server derives its
+// brain_id from brain.json's `id` field (see wicked-brain-server.mjs), so we
+// read the same source here. Fall back to the per-project basename convention
+// when brain.json is absent — that's the id a freshly-init'd brain will carry.
+function readExpectedBrainId(brainPath) {
+  try {
+    const cfg = JSON.parse(readFileSync(join(brainPath, "brain.json"), "utf-8"));
+    if (cfg && typeof cfg.id === "string" && cfg.id) return cfg.id;
+  } catch {
+    // brain.json missing/unreadable — fall through to the basename convention.
+  }
+  return basename(brainPath);
+}
+
 // ---------- HTTP ----------
 
 async function callApi(port, action, params, { timeoutMs = 30000, auditFile } = {}) {
@@ -135,6 +149,18 @@ async function healthCheck(port, { timeoutMs = 800 } = {}) {
   }
 }
 
+// Like healthCheck, but returns the full health body (which carries brain_id)
+// so callers can confirm WHICH brain is answering the port — not just that
+// SOMETHING is. Returns null when nothing responds healthily.
+async function healthInfo(port, { timeoutMs = 800 } = {}) {
+  try {
+    const r = await callApi(port, "health", {}, { timeoutMs });
+    return r && r.status === "ok" ? r : null;
+  } catch {
+    return null;
+  }
+}
+
 // ---------- spawn lock ----------
 // Cross-platform exclusive-create lock via { flag: "wx" }. Stale entries
 // (older than STALE_LOCK_MS) are reaped on contention so a crashed CLI
@@ -495,15 +521,44 @@ Examples:
   if (args.flags.status) {
     const meta = readMetaConfig(brainPath);
     const port = args.flags.port || meta.server_port || 4242;
-    const running = await healthCheck(port);
+    const expectedBrainId = readExpectedBrainId(brainPath);
+    // Ask the responding server WHICH brain it is rather than trusting that the
+    // persisted port still belongs to us. A different brain's server can have
+    // claimed this port (probe-up on EADDRINUSE, stale config, manual restart),
+    // and a blind `running:true` would point an operator at the wrong process.
+    const health = await healthInfo(port);
     let pid = null;
     try { pid = parseInt(readFileSync(join(brainPath, "_meta", "server.pid"), "utf-8").trim(), 10); } catch {}
-    const payload = {
-      brain_path: brainPath,
-      port,
-      running,
-      pid: running && pidAlive(pid) ? pid : null,
-    };
+
+    let payload;
+    if (!health) {
+      payload = {
+        brain_path: brainPath,
+        brain_id: expectedBrainId,
+        port,
+        running: false,
+        pid: null,
+      };
+    } else if (health.brain_id !== expectedBrainId) {
+      // Port is occupied — but by a DIFFERENT brain than the one we resolved.
+      payload = {
+        brain_path: brainPath,
+        brain_id: expectedBrainId,
+        port,
+        running: false,
+        port_conflict: true,
+        actual_brain_id: health.brain_id ?? null,
+        pid: null,
+      };
+    } else {
+      payload = {
+        brain_path: brainPath,
+        brain_id: expectedBrainId,
+        port,
+        running: true,
+        pid: pidAlive(pid) ? pid : null,
+      };
+    }
     process.stdout.write(
       (args.flags.pretty ? JSON.stringify(payload, null, 2) : JSON.stringify(payload)) + "\n",
     );
@@ -514,9 +569,32 @@ Examples:
   if (args.flags.stop) {
     const meta = readMetaConfig(brainPath);
     const port = args.flags.port || meta.server_port || 4242;
+    const expectedBrainId = readExpectedBrainId(brainPath);
     const pidPath = join(brainPath, "_meta", "server.pid");
     let pid = null;
     try { pid = parseInt(readFileSync(pidPath, "utf-8").trim(), 10); } catch {}
+
+    // Reconcile the port's actual occupant before signalling anything. If a
+    // DIFFERENT brain answers this port, refuse — killing our persisted PID
+    // (or, worse, mistaking the port owner for ours) would take down an
+    // unrelated process. The operator must target the right brain or port.
+    const health = await healthInfo(port);
+    if (health && health.brain_id !== expectedBrainId) {
+      const payload = {
+        stopped: false,
+        reason: "port_conflict",
+        port,
+        brain_id: expectedBrainId,
+        actual_brain_id: health.brain_id ?? null,
+      };
+      process.stdout.write(
+        (args.flags.pretty ? JSON.stringify(payload, null, 2) : JSON.stringify(payload)) + "\n",
+      );
+      // Refused on purpose — surface a non-zero exit so scripted callers notice.
+      process.exitCode = 1;
+      return;
+    }
+
     if (!pid || !pidAlive(pid)) {
       process.stdout.write(JSON.stringify({ stopped: false, reason: "not running", port }) + "\n");
       return;

package/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain-server",
-  "version": "0.15.2",
+  "version": "0.15.3",
   "type": "module",
   "description": "SQLite FTS5 search server for wicked-brain digital knowledge bases",
   "keywords": [
@@ -40,6 +40,6 @@
     "wicked-bus": "^2.0.0"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   }
 }

package/skills/wicked-brain-graph/SKILL.md

@@ -52,3 +52,28 @@ empty graph.
 Backed by the `@colbymchenry/codegraph` CLI (resolved at runtime via
 `WICKED_CODEGRAPH_BIN` → brain config → PATH → `npx`). The brain reads codegraph's
 SQLite graph directly; it shells the CLI only to (re)build.
+
+### Offline / air-gapped install
+
+By **default** the engine is resolved by shelling out to
+`npx @colbymchenry/codegraph`, which **downloads from the npm registry and will
+not work on an air-gapped machine**. To run offline, install the CLI ahead of
+time and point the brain at the binary with **`WICKED_CODEGRAPH_BIN`** — the
+**highest-priority** entry in the resolution ladder:
+
+```
+WICKED_CODEGRAPH_BIN  →  _meta/codegraph.json {bin}  →  PATH  →  source node_modules/.bin/codegraph  →  npx (network, last resort)
+```
+
+```bash
+# Pre-install on a connected machine, then on the air-gapped host:
+export WICKED_CODEGRAPH_BIN=/usr/local/bin/codegraph     # macOS/Linux
+```
+```powershell
+$env:WICKED_CODEGRAPH_BIN = "C:\tools\codegraph\codegraph.cmd"   # Windows
+```
+
+- A `.mjs`/`.js` target is invoked via `node`; any other path is executed directly.
+- An **empty** `WICKED_CODEGRAPH_BIN` is a **kill switch** — queries return
+  `engine: "unavailable"` rather than reaching for the network `npx` path.
+- Per-brain alternative: write `_meta/codegraph.json` with `{ "bin": "/path/to/codegraph" }`.