@gcunharodrigues/wrxn 0.3.0 → 0.5.0

package/bin/wrxn.cjs

@@ -11,6 +11,7 @@ const worktree = require('../lib/worktree.cjs');
 const executor = require('../lib/executor.cjs');
 const onboard = require('../lib/onboard.cjs');
 const connect = require('../lib/connect.cjs');
+const brain = require('../lib/brain.cjs');
 const statusline = require('../lib/statusline.cjs');
 const { convert } = require('../lib/convert.cjs');
 const { ingest } = require('../lib/ingest.cjs');
@@ -58,6 +59,10 @@ function parseArgs(argv) {
       args.flags.probe = argv[++i];
     } else if (a === '--distillation') {
       args.flags.distillation = argv[++i];
+    } else if (a === '--limit') {
+      args.flags.limit = argv[++i];
+    } else if (a === '--type') {
+      args.flags.type = argv[++i];
     } else if (a === '--check-report') {
       args.flags['check-report'] = true;
     } else if (a.startsWith('--')) {
@@ -109,6 +114,17 @@ Usage:
       list                       print all registered connections (agent-readable JSON)
       get <name>                 print one connection by name
 
+  wrxn brain query "<q>" [--json] [--limit <n>] [--type <prose|code|NodeType>] [--neighbors] [--root <dir>]
+                                 ask the warm Brain (recon-wrxn's code+prose graph) from the terminal.
+                                 WHOLE-BRAIN by default. Discovers the live serve door via
+                                 .recon-wrxn/serve-endpoint.json and POSTs the query; prints ranked
+                                 hits (name · type · file:line). If the Brain is not warm (no live
+                                 serve), prints a clear error and exits non-zero — no cold load.
+                                 --json emits the structured hits · --limit asks the door for top n ·
+                                 --type post-filters (prose=Page/Section, code=the rest, or an exact
+                                 NodeType) · --neighbors expands each hit to its 1-hop graph neighbors
+                                 (callers/callees/relationships via recon_explain).
+
   wrxn statusline [--inject [--path <script>]]
                                  SYNAPSE live-window writer. With no flag: report whether a statusline
                                  is configured (~/.claude/settings.json) + print the marker-bounded
@@ -408,6 +424,32 @@ async function main(argv) {
     }
   }
 
+  if (cmd === 'brain') {
+    const sub = args._[1];
+    if (sub !== 'query') {
+      process.stderr.write(`wrxn: unknown brain subcommand "${sub || ''}" (expected: query)\n\n${USAGE}\n`);
+      return 2;
+    }
+    const q = args._[2];
+    if (!q) { process.stderr.write('wrxn: brain query requires "<query>"\n'); return 2; }
+    const opts = { json: !!args.flags.json, neighbors: !!args.flags.neighbors };
+    if (args.flags.limit != null) {
+      const n = parseInt(args.flags.limit, 10);
+      if (!Number.isInteger(n) || n <= 0) { process.stderr.write('wrxn: --limit requires a positive integer\n'); return 2; }
+      opts.limit = n;
+    }
+    if (args.flags.type) opts.type = String(args.flags.type);
+    const root = path.resolve(args.flags.root || process.cwd());
+    try {
+      const res = await brain.query(q, opts, { root });
+      process.stdout.write(brain.formatHits(res.hits, opts) + '\n');
+      return 0;
+    } catch (err) {
+      process.stderr.write(`wrxn: ${err.message}\n`);
+      return 2;
+    }
+  }
+
   if (cmd === 'statusline') {
     const home = process.env.HOME || os.homedir();
     const detection = statusline.detectStatusLine(home);

package/lib/brain.cjs

@@ -0,0 +1,295 @@
+'use strict';
+
+// WRXN brain query (recon-brain-recall-03) — interrogate the warm Brain from the terminal.
+//
+// The Brain is recon-wrxn's unified code+prose knowledge graph, loaded WARM inside the `recon serve`
+// process Claude Code boots for a session. This command reaches it over the loopback find door that
+// serve announces via a discovery file — it is WHOLE-BRAIN (code AND prose, no scope filter by
+// default), the operator's on-demand counterpart to the prose-only proactive Recall hook.
+//
+// Endpoint-first (v1): if no warm door is discoverable, we raise a clear, actionable error and the CLI
+// exits non-zero — there is NO cold one-shot load (that would pay the index + embedder cost the warm
+// serve already absorbs).
+//
+// The query path takes an INJECTED transport + endpoint reader (deps) so its behavior is unit-testable
+// with no live serve — mirrors the injected-invoker seam in lib/connect.cjs and the recall hook's
+// httpTransport. lib/brain.cjs is PACKAGE code (invoked via bin/wrxn.cjs), NOT payload — no manifest
+// entry, consistent with lib/connect.cjs / lib/executor.cjs / lib/onboard.cjs.
+//
+// The discovery contract (serve-endpoint.json {pid,port}, pid-liveness) is duplicated here from the
+// payload recall-surface hook ON PURPOSE: that hook must be node-stdlib-only and self-contained (it
+// ships into installs without the kernel lib), so package code cannot import it. The contract is ~20
+// stable lines — duplicating it across the install boundary is the same self-containment trade the
+// payload hooks make for findInstallRoot.
+
+const fs = require('fs');
+const http = require('http');
+const path = require('path');
+
+const ENDPOINT_REL = path.join('.recon-wrxn', 'serve-endpoint.json');
+const FIND_PATH = '/api/tools/recon_find';
+const EXPLAIN_PATH = '/api/tools/recon_explain';
+const TIMEOUT_MS = 5000; // generous: an interactive CLI, not the per-prompt 150ms recall budget
+const MAX_RESPONSE_BYTES = 256 * 1024; // hard cap on an accumulated door response body (anti-flood)
+const PROSE_TYPES = new Set(['Page', 'Section']);
+const WALK_UP_LIMIT = 12;
+
+// ── discovery (the cross-repo warm-door contract) ────────────────────────────────────
+
+// A pid is alive unless process.kill(pid,0) throws. ESRCH = gone; EPERM = owned by another user but
+// alive. Mirrors the cross-repo discovery contract (and the recall hook).
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return !!e && e.code === 'EPERM';
+  }
+}
+
+// Refuse a discovery file another user could have planted, or that is group/world-writable — trusting
+// it would let a hostile workspace point the door host/port at an exfil/injection sink. lstat (not
+// stat) so a symlink's OWN ownership/mode is judged, not its target's. A platform without getuid (no
+// POSIX ownership) skips the uid check but still enforces the mode check. Any fault → not trusted.
+function endpointTrusted(file) {
+  let st;
+  try {
+    st = fs.lstatSync(file);
+  } catch {
+    return false;
+  }
+  if (typeof process.getuid === 'function' && st.uid !== process.getuid()) return false; // foreign owner
+  if ((st.mode & 0o022) !== 0) return false; // group/world-writable
+  return true;
+}
+
+// Walk up from startDir to the first directory carrying .recon-wrxn/serve-endpoint.json; read and
+// validate {pid,port}; trust it only when it is well-owned (not planted), well-formed, and the pid is
+// alive. Returns {pid,port,root} or null (the Brain is not warm: absent, untrusted, malformed, missing
+// fields, or a dead process).
+function discoverEndpoint(startDir) {
+  let dir = startDir || process.cwd();
+  for (let i = 0; i < WALK_UP_LIMIT; i++) {
+    const file = path.join(dir, ENDPOINT_REL);
+    if (fs.existsSync(file)) {
+      if (!endpointTrusted(file)) return null; // foreign-owned or loose perms → not warm
+      let obj;
+      try {
+        obj = JSON.parse(fs.readFileSync(file, 'utf8'));
+      } catch {
+        return null; // malformed → not warm
+      }
+      const pid = Number(obj && obj.pid);
+      const port = Number(obj && obj.port);
+      if (!Number.isInteger(pid) || pid <= 0) return null;
+      if (!Number.isInteger(port) || port <= 0) return null;
+      if (!pidAlive(pid)) return null; // dead process → not warm
+      return { pid, port, root: dir };
+    }
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+// ── transport (injectable; default = real loopback POST) ─────────────────────────────
+
+// Default transport: a real loopback POST with a hard timeout. Injectable so unit tests never touch
+// the network (mirrors lib/connect.cjs's invoke seam). Resolves {statusCode, body}; rejects on socket
+// error or timeout.
+function httpTransport({ port, path: reqPath, body, timeoutMs }) {
+  return new Promise((resolve, reject) => {
+    const payload = Buffer.from(JSON.stringify(body));
+    const deadline = timeoutMs || TIMEOUT_MS;
+    let settled = false;
+    let wall = null;
+    const done = (fn, arg) => {
+      if (settled) return;
+      settled = true;
+      if (wall) clearTimeout(wall);
+      fn(arg);
+    };
+    const req = http.request(
+      {
+        host: '127.0.0.1',
+        port,
+        path: reqPath,
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': payload.length },
+      },
+      (res) => {
+        const chunks = [];
+        let total = 0;
+        res.on('data', (c) => {
+          total += c.length;
+          if (total > MAX_RESPONSE_BYTES) { req.destroy(new Error('brain door response too large')); return; }
+          chunks.push(c);
+        });
+        res.on('end', () => done(resolve, { statusCode: res.statusCode, body: Buffer.concat(chunks).toString('utf8') }));
+        res.on('error', (e) => done(reject, e));
+      }
+    );
+    req.on('error', (e) => done(reject, e));
+    // Idle timeout (no bytes for `deadline`) AND an independent wall-clock — the latter bounds a trickle
+    // attacker that dribbles bytes to keep the idle timer from ever firing.
+    req.setTimeout(deadline, () => req.destroy(new Error('brain door timeout')));
+    wall = setTimeout(() => req.destroy(new Error('brain door wall-clock timeout')), deadline);
+    req.write(payload);
+    req.end();
+  });
+}
+
+// POST a door tool and return the parsed JSON body. Raises a clean error (never a crash) on a transport
+// fault, a non-200 status, or a non-JSON body.
+async function postTool(transport, port, reqPath, body, timeoutMs) {
+  let resp;
+  try {
+    resp = await transport({ port, path: reqPath, body, timeoutMs: timeoutMs || TIMEOUT_MS });
+  } catch (err) {
+    throw new Error(`Brain door request to ${reqPath} failed: ${err.message}`);
+  }
+  if (!resp || resp.statusCode !== 200) {
+    throw new Error(`Brain door returned HTTP ${resp ? resp.statusCode : 'no-response'} for ${reqPath}`);
+  }
+  try {
+    return JSON.parse(resp.body);
+  } catch {
+    throw new Error(`Brain door returned a malformed (non-JSON) response for ${reqPath}`);
+  }
+}
+
+// ── pure helpers ─────────────────────────────────────────────────────────────────────
+
+function isProse(hit) {
+  return !!hit && PROSE_TYPES.has(hit.type);
+}
+
+// Post-filter hits by --type (the find request can't carry a type ARRAY, so prose=Page+Section is
+// always a post-filter): 'prose' → Page/Section, 'code' → everything else, else an exact NodeType.
+function filterByType(hits, type) {
+  if (!type) return hits;
+  if (type === 'prose') return hits.filter(isProse);
+  if (type === 'code') return hits.filter((h) => !isProse(h));
+  const t = String(type).toLowerCase();
+  return hits.filter((h) => String(h && h.type).toLowerCase() === t);
+}
+
+// Extract a hit's 1-hop neighbors from the door's structured recon_explain response:
+//   { result, neighbors: NeighborHit[] }, NeighborHit = { name, type, file, line, relationship }
+//   relationship ∈ caller | callee | import | importedBy | method | implementedBy | usedBy | testRef
+// Strictly 1-hop. Consumes that real shape directly — no relationship-bucket guesswork. A missing or
+// non-array `neighbors` (e.g. a degraded/empty explain) yields [] so the hit simply has no neighbors.
+function extractNeighbors(resp) {
+  if (!resp || typeof resp !== 'object' || !Array.isArray(resp.neighbors)) return [];
+  return resp.neighbors.map((n) => {
+    const r = n || {};
+    const out = { name: r.name, type: r.type, file: r.file };
+    if (r.line != null) out.line = r.line;
+    if (r.relationship) out.relationship = r.relationship;
+    return out;
+  });
+}
+
+// ── formatting (pure) ────────────────────────────────────────────────────────────────
+
+function hitLine(h) {
+  const name = h.name || '(unnamed)';
+  const type = h.type || '?';
+  const loc = h.file ? `${h.file}${h.line != null ? ':' + h.line : ''}` : '';
+  return loc ? `${name} · ${type} · ${loc}` : `${name} · ${type}`;
+}
+
+function neighborLine(n) {
+  const rel = n.relationship ? ` [${n.relationship}]` : '';
+  return `    - ${hitLine(n)}${rel}`;
+}
+
+// Render results: --json re-emits the structured hits; default is a human text list. With --neighbors,
+// each hit's 1-hop neighbors are listed indented beneath it.
+function formatHits(hits, opts = {}) {
+  const list = Array.isArray(hits) ? hits : [];
+  if (opts.json) return JSON.stringify(list, null, 2);
+  if (!list.length) return 'no results';
+  const lines = [];
+  for (const h of list) {
+    lines.push(hitLine(h));
+    if (opts.neighbors) {
+      const ns = Array.isArray(h.neighbors) ? h.neighbors : [];
+      if (ns.length) for (const n of ns) lines.push(neighborLine(n));
+      else lines.push('    (no 1-hop neighbors)');
+    }
+  }
+  return lines.join('\n');
+}
+
+// ── the query (IO shell over the injected seam) ──────────────────────────────────────
+
+const NOT_WARM =
+  'Brain is not warm — no live recon serve door found (.recon-wrxn/serve-endpoint.json is absent, ' +
+  'malformed, or its process is dead). Open a Claude Code session (which boots recon serve), or run ' +
+  '`recon serve` with the find door enabled, then retry.';
+
+/**
+ * Query the warm Brain. Whole-brain (code+prose) by default.
+ * @param {string} q          the query string
+ * @param {object} opts       { json?, limit?, type?, neighbors? }
+ * @param {object} deps       { root?, discover?, transport?, timeoutMs? } — injected seam for tests
+ * @returns {Promise<{hits: object[]}>}
+ * @throws  a clear error when the Brain is not warm, or on a malformed/non-200 door response.
+ */
+async function query(q, opts = {}, deps = {}) {
+  const term = String(q == null ? '' : q).trim();
+  if (!term) throw new Error('wrxn brain query requires a non-empty query string');
+
+  const startDir = deps.root || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const discover = deps.discover || discoverEndpoint;
+  const transport = deps.transport || httpTransport;
+  const timeoutMs = deps.timeoutMs || TIMEOUT_MS;
+
+  const door = discover(startDir);
+  if (!door) throw new Error(NOT_WARM);
+
+  const findBody = { query: term };
+  if (Number.isInteger(opts.limit) && opts.limit > 0) findBody.limit = opts.limit;
+
+  const found = await postTool(transport, door.port, FIND_PATH, findBody, timeoutMs);
+  if (!Array.isArray(found.hits)) {
+    throw new Error(
+      'Brain door returned an unexpected response shape (no structured `hits` array) — the recon-wrxn ' +
+      'serve door may predate the structured find response.'
+    );
+  }
+
+  let hits = filterByType(found.hits, opts.type);
+
+  // --neighbors: 1-hop expansion per hit via recon_explain — the ONLY place 1-hop lives. A per-hit
+  // explain failure degrades to empty neighbors (the find already succeeded); it never crashes.
+  if (opts.neighbors) {
+    for (const h of hits) {
+      const explainBody = { name: h.name };
+      if (h.file) explainBody.file = h.file;
+      try {
+        h.neighbors = extractNeighbors(await postTool(transport, door.port, EXPLAIN_PATH, explainBody, timeoutMs));
+      } catch {
+        h.neighbors = [];
+      }
+    }
+  }
+
+  return { hits };
+}
+
+module.exports = {
+  query,
+  formatHits,
+  discoverEndpoint,
+  pidAlive,
+  httpTransport,
+  filterByType,
+  extractNeighbors,
+  isProse,
+  FIND_PATH,
+  EXPLAIN_PATH,
+  PROSE_TYPES,
+};

package/manifest.json

@@ -98,6 +98,11 @@
       "class": "managed",
       "profile": "project"
     },
+    {
+      "path": ".claude/skills/dream/SKILL.md",
+      "class": "managed",
+      "profile": "project"
+    },
     {
       "path": ".claude/skills/grill-me/SKILL.md",
       "class": "managed",
@@ -408,6 +413,16 @@
       "class": "state",
       "profile": "project"
     },
+    {
+      "path": ".wrxn/dream.cjs",
+      "class": "managed",
+      "profile": "project"
+    },
+    {
+      "path": ".wrxn/dream/.gitkeep",
+      "class": "state",
+      "profile": "project"
+    },
     {
       "path": ".wrxn/wiki.cjs",
       "class": "managed",
@@ -438,6 +453,16 @@
       "class": "state",
       "profile": "project"
     },
+    {
+      "path": ".wrxn/wiki/_rules/.gitkeep",
+      "class": "state",
+      "profile": "project"
+    },
+    {
+      "path": ".wrxn/wiki/_slots/.gitkeep",
+      "class": "state",
+      "profile": "project"
+    },
     {
       "path": "docs/agents/domain.md",
       "class": "seeded",

package/migrations/003-serve-http-door.cjs

@@ -0,0 +1,44 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * 003 — open the warm-brain HTTP find door on existing installs (recon-brain-recall-05).
+ *
+ * The door is the concurrent, read-only, loopback HTTP transport `recon serve` runs alongside its
+ * stdio MCP transport when `.recon-wrxn.json` carries `serveHttp:true` (recon-wrxn ADR 0003) — the one
+ * warm index the per-prompt Recall hook and `wrxn brain query` reach. A fresh install gets the door
+ * from the updated seed, but `.recon-wrxn.json` is SEEDED (operator-owned), so `wrxn update` never
+ * overwrites it — an install created before this release would keep the door shut forever unless a
+ * migration flips it.
+ *
+ * up() sets `serveHttp:true` in place, PRESERVING every existing operator field (projects, ignore,
+ * watch, …) — it touches only the door bit, it does not retrofit the rest of the new template.
+ * Defensive like 002/001: a missing config is a no-op (a non-recon install has nothing to migrate), an
+ * already-open door is an idempotent no-op, and a corrupt/unparseable (or non-object) config is left
+ * untouched — never clobber a hand-edited file. `version` is a frozen 0.4.0: it runs via `wrxn update`
+ * once the install reaches the release that carries the door (the same release that bumps the recon-wrxn
+ * pin to the wrxn.3 build whose serve actually honors serveHttp).
+ */
+module.exports = {
+  id: '003',
+  version: '0.4.0',
+  up(ctx) {
+    const cfgPath = path.join(ctx.target, '.recon-wrxn.json');
+    if (!fs.existsSync(cfgPath)) return; // no recon config → nothing to migrate
+
+    let cfg;
+    try {
+      cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+    } catch {
+      return; // malformed operator config → leave it untouched, never clobber
+    }
+    if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) return; // not a config object → leave it
+
+    if (cfg.serveHttp === true) return; // door already open → idempotent no-op
+
+    cfg.serveHttp = true; // open the door; every other operator field is preserved
+    fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcunharodrigues/wrxn",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "WRXN Kernel — installable AI operating system. Two profiles (project | workspace), pull-based updates, managed/seeded/state file classes.",
   "bin": {
     "wrxn": "bin/wrxn.cjs"
@@ -16,7 +16,7 @@
     "test": "node --test"
   },
   "dependencies": {
-    "recon-wrxn": "6.0.0-wrxn.2"
+    "recon-wrxn": "6.0.0-wrxn.3"
   },
   "engines": {
     "node": ">=20"