@neat.is/core 0.7.3 → 0.7.5

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   resolveHost,
   resolveNeatVersion,
   writeDaemonRecord
-} from "./chunk-3SBEY67S.js";
+} from "./chunk-MYLUXVXE.js";
 import {
   buildSearchIndex
 } from "./chunk-BIY46Q6U.js";
@@ -23,8 +23,10 @@ import {
   addImports,
   addInfra,
   addProject,
+  addRoutes,
   addServiceAliases,
   addServiceNodes,
+  addSymbols,
   attachGraphToEventBus,
   autoSlugConnectorId,
   buildApi,
@@ -72,7 +74,7 @@ import {
   startStalenessLoop,
   upsertConnectorEntry,
   validateConnectorEntry
-} from "./chunk-BY6ZP5WA.js";
+} from "./chunk-KB4HRB6N.js";
 import {
   startOtelGrpcReceiver
 } from "./chunk-6H757ZNM.js";
@@ -86,9 +88,9 @@ import {
 } from "./chunk-P2ZEKJ35.js";
 
 // src/cli.ts
-import path11 from "path";
-import os2 from "os";
-import { promises as fs9 } from "fs";
+import path13 from "path";
+import os4 from "os";
+import { promises as fs11 } from "fs";
 
 // src/banner.ts
 import path from "path";
@@ -263,9 +265,11 @@ var ALL_PHASES = [
   "services",
   "aliases",
   "files",
+  "symbols",
   "imports",
   "databases",
   "configs",
+  "routes",
   "calls",
   "infra"
 ];
@@ -288,7 +292,9 @@ function classifyChange(relPath) {
   }
   if (/\.(?:js|jsx|mjs|cjs|ts|tsx|py)$/.test(base)) {
     phases.add("files");
+    phases.add("symbols");
     phases.add("imports");
+    phases.add("routes");
     phases.add("calls");
   }
   if (/\.ya?ml$/.test(base) && !/^docker-compose.*\.ya?ml$/.test(base)) {
@@ -315,6 +321,11 @@ async function runExtractPhases(graph, scanPath, phases, project = DEFAULT_PROJE
     nodesAdded += r.nodesAdded;
     edgesAdded += r.edgesAdded;
   }
+  if (phases.has("symbols")) {
+    const r = await addSymbols(graph, services);
+    nodesAdded += r.nodesAdded;
+    edgesAdded += r.edgesAdded;
+  }
   if (phases.has("imports")) {
     const r = await addImports(graph, services);
     nodesAdded += r.nodesAdded;
@@ -330,6 +341,11 @@ async function runExtractPhases(graph, scanPath, phases, project = DEFAULT_PROJE
     nodesAdded += r.nodesAdded;
     edgesAdded += r.edgesAdded;
   }
+  if (phases.has("routes")) {
+    const r = await addRoutes(graph, services);
+    nodesAdded += r.nodesAdded;
+    edgesAdded += r.edgesAdded;
+  }
   if (phases.has("calls")) {
     const r = await addCallEdges(graph, services);
     nodesAdded += r.nodesAdded;
@@ -4455,6 +4471,453 @@ async function runHooksCommand(args) {
   }
 }
 
+// src/codex-cli.ts
+import path10 from "path";
+import os2 from "os";
+import { promises as fs9 } from "fs";
+import { isDeepStrictEqual } from "util";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+var CODEX_MCP_SERVER = {
+  command: "npx",
+  args: ["-y", "@neat.is/mcp"],
+  env: { NEAT_CORE_URL: "http://localhost:8080" }
+};
+var CODEX_NEAT_BLOCK = [
+  "[mcp_servers.neat]",
+  'command = "npx"',
+  'args = ["-y", "@neat.is/mcp"]',
+  'env = { NEAT_CORE_URL = "http://localhost:8080" }'
+].join("\n");
+var NEAT_GRAPH_FIRST_START = "<!-- neat:graph-first -->";
+var NEAT_GRAPH_FIRST_END = "<!-- /neat:graph-first -->";
+function codexConfigPath() {
+  const override = process.env.NEAT_CODEX_CONFIG;
+  if (override && override.length > 0) return path10.resolve(override);
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? os2.homedir();
+  return path10.join(home, ".codex", "config.toml");
+}
+function agentsFilePath() {
+  const override = process.env.NEAT_CODEX_AGENTS;
+  if (override && override.length > 0) return path10.resolve(override);
+  return path10.join(process.cwd(), "AGENTS.md");
+}
+function isTableHeader(line) {
+  return /^\s*\[\[?[^\]]+\]\]?\s*$/.test(line);
+}
+function tableName(line) {
+  return line.trim().replace(/^\[\[?/, "").replace(/\]\]?$/, "").trim();
+}
+function isNeatHeader(line) {
+  return isTableHeader(line) && tableName(line) === "mcp_servers.neat";
+}
+function isNeatChildHeader(line) {
+  if (!isTableHeader(line)) return false;
+  const name = tableName(line);
+  return name === "mcp_servers.neat" || name.startsWith("mcp_servers.neat.");
+}
+function upsertCodexConfig(raw) {
+  const trimmed = raw.trim();
+  const parsed = trimmed.length > 0 ? parseToml(raw) : {};
+  const existingServers = parsed.mcp_servers ?? {};
+  const spliced = spliceNeatBlock(raw);
+  let text;
+  if (verifyPreserved(raw, spliced, parsed)) {
+    text = spliced;
+  } else {
+    const merged = {
+      ...parsed,
+      mcp_servers: { ...existingServers, neat: CODEX_MCP_SERVER }
+    };
+    text = stringifyToml(merged);
+    if (!text.endsWith("\n")) text += "\n";
+  }
+  return { text, changed: text !== raw };
+}
+function spliceNeatBlock(raw) {
+  const block = CODEX_NEAT_BLOCK;
+  const lines = raw.length > 0 ? raw.split("\n") : [];
+  const start = lines.findIndex(isNeatHeader);
+  if (start === -1) {
+    const base = raw.replace(/\n+$/, "");
+    return base.length > 0 ? `${base}
+
+${block}
+` : `${block}
+`;
+  }
+  let end = start + 1;
+  for (; ; ) {
+    while (end < lines.length && !isTableHeader(lines[end])) end++;
+    if (end < lines.length && isNeatChildHeader(lines[end])) {
+      end++;
+      continue;
+    }
+    break;
+  }
+  const before = lines.slice(0, start).join("\n").replace(/\n*$/, "");
+  const after = lines.slice(end).join("\n").replace(/^\n*/, "");
+  let text = "";
+  if (before.length > 0) text += `${before}
+
+`;
+  text += `${block}
+`;
+  if (after.length > 0) text += `
+${after}`;
+  return `${text.replace(/\n*$/, "")}
+`;
+}
+function verifyPreserved(raw, spliced, original) {
+  let next;
+  try {
+    next = parseToml(spliced);
+  } catch {
+    return false;
+  }
+  const origServers = original.mcp_servers ?? {};
+  const nextServers = next.mcp_servers ?? {};
+  if (!isDeepStrictEqual(nextServers.neat, CODEX_MCP_SERVER)) return false;
+  for (const name of Object.keys(origServers)) {
+    if (name === "neat") continue;
+    if (!isDeepStrictEqual(nextServers[name], origServers[name])) return false;
+  }
+  for (const name of Object.keys(nextServers)) {
+    if (name !== "neat" && !(name in origServers)) return false;
+  }
+  for (const key of Object.keys(original)) {
+    if (key === "mcp_servers") continue;
+    if (!isDeepStrictEqual(next[key], original[key])) return false;
+  }
+  for (const key of Object.keys(next)) {
+    if (key !== "mcp_servers" && !(key in original)) return false;
+  }
+  return true;
+}
+function agentsBlock(guide) {
+  return `${NEAT_GRAPH_FIRST_START}
+${guide.replace(/\s+$/, "")}
+${NEAT_GRAPH_FIRST_END}
+`;
+}
+function upsertAgents(raw, guide) {
+  const block = agentsBlock(guide);
+  if (raw.length === 0) return { text: block, changed: true };
+  const startIdx = raw.indexOf(NEAT_GRAPH_FIRST_START);
+  const endIdx = raw.indexOf(NEAT_GRAPH_FIRST_END);
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const before = raw.slice(0, startIdx);
+    const after = raw.slice(endIdx + NEAT_GRAPH_FIRST_END.length);
+    const text2 = `${before}${block.replace(/\n+$/, "")}${after}`;
+    return { text: text2, changed: text2 !== raw };
+  }
+  const base = raw.replace(/\n+$/, "");
+  const text = base.length > 0 ? `${base}
+
+${block}` : block;
+  return { text, changed: text !== raw };
+}
+async function readGuide() {
+  return readSkillAsset(GUIDE_FILENAME);
+}
+async function runCodex(opts) {
+  if (opts.printConfig) {
+    process.stdout.write(`${CODEX_NEAT_BLOCK}
+`);
+    return { exitCode: 0 };
+  }
+  if (opts.printGuide) {
+    process.stdout.write(agentsBlock(await readGuide()));
+    return { exitCode: 0 };
+  }
+  const configPath = codexConfigPath();
+  const agentsPath = agentsFilePath();
+  let configRaw = "";
+  try {
+    configRaw = await fs9.readFile(configPath, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      console.error(`neat codex: failed to read ${configPath} \u2014 ${err.message}`);
+      return { exitCode: 1 };
+    }
+  }
+  let agentsRaw = "";
+  try {
+    agentsRaw = await fs9.readFile(agentsPath, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      console.error(`neat codex: failed to read ${agentsPath} \u2014 ${err.message}`);
+      return { exitCode: 1 };
+    }
+  }
+  let config;
+  try {
+    config = upsertCodexConfig(configRaw);
+  } catch (err) {
+    console.error(
+      `neat codex: ${configPath} is not valid TOML \u2014 ${err.message}`
+    );
+    console.error("neat codex: fix the file and re-run; nothing was written.");
+    return { exitCode: 1 };
+  }
+  const guide = await readGuide();
+  const agents = upsertAgents(agentsRaw, guide);
+  if (!opts.apply) {
+    console.log("neat codex \u2014 plan (nothing written; re-run with --apply to write)");
+    console.log("");
+    console.log(`  Codex MCP config: ${configPath}`);
+    console.log(
+      config.changed ? `    ${configRaw ? "update" : "create"} the [mcp_servers.neat] table:` : "    already up to date \u2014 [mcp_servers.neat] matches"
+    );
+    if (config.changed) {
+      for (const line of CODEX_NEAT_BLOCK.split("\n")) console.log(`      ${line}`);
+    }
+    console.log("");
+    console.log(`  Project instructions: ${agentsPath}`);
+    console.log(
+      agents.changed ? `    ${agentsRaw ? "update" : "create"} the graph-first block (between ${NEAT_GRAPH_FIRST_START} markers)` : "    already up to date \u2014 graph-first block matches"
+    );
+    console.log("");
+    console.log("The MCP server reads NEAT_CORE_URL for the daemon URL \u2014 edit that value in");
+    console.log("the generated table to point Codex at a non-default daemon.");
+    return { exitCode: 0 };
+  }
+  if (config.changed) {
+    await fs9.mkdir(path10.dirname(configPath), { recursive: true });
+    await fs9.writeFile(configPath, config.text, "utf8");
+    console.log(`neat codex: wrote [mcp_servers.neat] to ${configPath}`);
+  } else {
+    console.log(`neat codex: ${configPath} already has NEAT's MCP server`);
+  }
+  if (agents.changed) {
+    await fs9.mkdir(path10.dirname(agentsPath), { recursive: true });
+    await fs9.writeFile(agentsPath, agents.text, "utf8");
+    console.log(`neat codex: wrote the graph-first block to ${agentsPath}`);
+  } else {
+    console.log(`neat codex: ${agentsPath} already has the graph-first block`);
+  }
+  console.log("");
+  console.log("restart Codex to pick up the new MCP server. NEAT_CORE_URL in the table");
+  console.log("points the server at the local daemon \u2014 edit it for a non-default one.");
+  return { exitCode: 0 };
+}
+function usage2() {
+  console.log("neat codex \u2014 install NEAT into the OpenAI Codex CLI (MCP server + AGENTS.md)");
+  console.log("");
+  console.log("  (no flag)        plan: print what would change, write nothing");
+  console.log("  --apply          add [mcp_servers.neat] to ~/.codex/config.toml and write");
+  console.log("                   the graph-first block into ./AGENTS.md, merging into both");
+  console.log("                   without touching your other servers or instructions");
+  console.log("  --print-config   print the [mcp_servers.neat] TOML block to stdout");
+  console.log("  --print-guide    print the AGENTS.md graph-first block to stdout");
+  console.log("");
+  console.log("Existing config is preserved and a re-run is a no-op. A malformed");
+  console.log("config.toml is a clear error with no partial write.");
+}
+async function runCodexCommand(args) {
+  const opts = { apply: false, printConfig: false, printGuide: false };
+  for (const arg of args) {
+    switch (arg) {
+      case "--apply":
+        opts.apply = true;
+        break;
+      case "--print-config":
+        opts.printConfig = true;
+        break;
+      case "--print-guide":
+        opts.printGuide = true;
+        break;
+      case "-h":
+      case "--help":
+        usage2();
+        return 0;
+      default:
+        console.error(`neat codex: unknown flag "${arg}"`);
+        usage2();
+        return 2;
+    }
+  }
+  try {
+    const { exitCode } = await runCodex(opts);
+    return exitCode;
+  } catch (err) {
+    console.error(err.message);
+    return 1;
+  }
+}
+
+// src/editors-cli.ts
+import path11 from "path";
+import os3 from "os";
+import { promises as fs10 } from "fs";
+var NEAT_MCP_SERVER = {
+  command: "npx",
+  args: ["-y", "@neat.is/mcp"]
+};
+var GRAPH_FIRST_MARKER_OPEN = "<!-- neat:graph-first -->";
+var GRAPH_FIRST_MARKER_CLOSE = "<!-- /neat:graph-first -->";
+function homeDir() {
+  return process.env.HOME ?? process.env.USERPROFILE ?? os3.homedir();
+}
+var CURSOR_CLIENT = {
+  id: "cursor",
+  label: "Cursor",
+  docsUrl: "https://docs.cursor.com/context/mcp",
+  mcpConfigPath: () => {
+    const override = process.env.NEAT_CURSOR_CONFIG;
+    if (override && override.length > 0) return path11.resolve(override);
+    return path11.join(homeDir(), ".cursor", "mcp.json");
+  },
+  // Cursor still reads a single `.cursorrules` at the project root (the modern
+  // `.cursor/rules/*.mdc` split is one-rule-per-file with frontmatter — a worse
+  // fit for a marker-fenced block). GRAPH_FIRST.md names this file directly.
+  rulesFileName: ".cursorrules"
+};
+var DEVIN_CLIENT = {
+  id: "devin",
+  label: "Devin Desktop (Cascade)",
+  docsUrl: "https://docs.devin.ai/desktop/cascade/mcp",
+  mcpConfigPath: () => {
+    const override = process.env.NEAT_DEVIN_CONFIG;
+    if (override && override.length > 0) return path11.resolve(override);
+    return path11.join(homeDir(), ".codeium", "windsurf", "mcp_config.json");
+  },
+  rulesFileName: ".windsurfrules"
+};
+function mergeMcpConfig(existing) {
+  const servers = existing.mcpServers ?? {};
+  const already = JSON.stringify(servers.neat) === JSON.stringify(NEAT_MCP_SERVER);
+  const merged = {
+    ...existing,
+    mcpServers: { ...servers, neat: NEAT_MCP_SERVER }
+  };
+  return { merged, changed: !already };
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function buildGuidanceBlock(guide) {
+  return `${GRAPH_FIRST_MARKER_OPEN}
+${guide.trim()}
+${GRAPH_FIRST_MARKER_CLOSE}
+`;
+}
+function mergeRulesFile(existing, block) {
+  const region = new RegExp(
+    `${escapeRegExp(GRAPH_FIRST_MARKER_OPEN)}[\\s\\S]*?${escapeRegExp(GRAPH_FIRST_MARKER_CLOSE)}\\n?`
+  );
+  if (region.test(existing)) return existing.replace(region, block);
+  if (existing.trim().length === 0) return block;
+  return `${existing.replace(/\s+$/, "")}
+
+${block}`;
+}
+async function runEditorInstall(client, opts) {
+  const mcpPath = client.mcpConfigPath();
+  const rulesPath = path11.join(opts.projectDir, client.rulesFileName);
+  let existingMcp = {};
+  try {
+    existingMcp = JSON.parse(await fs10.readFile(mcpPath, "utf8"));
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT") {
+      existingMcp = {};
+    } else if (err instanceof SyntaxError) {
+      console.error(
+        `neat ${client.id}: ${mcpPath} is not valid JSON \u2014 ${e.message}. Fix it (or move it aside) and re-run; nothing was written.`
+      );
+      return { exitCode: 1 };
+    } else {
+      console.error(`neat ${client.id}: failed to read ${mcpPath} \u2014 ${e.message}`);
+      return { exitCode: 1 };
+    }
+  }
+  let existingRules = "";
+  try {
+    existingRules = await fs10.readFile(rulesPath, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      console.error(`neat ${client.id}: failed to read ${rulesPath} \u2014 ${err.message}`);
+      return { exitCode: 1 };
+    }
+  }
+  const guide = await readSkillAsset(GUIDE_FILENAME);
+  const block = buildGuidanceBlock(guide);
+  const { merged, changed: mcpChanged } = mergeMcpConfig(existingMcp);
+  const mcpJson = JSON.stringify(merged, null, 2) + "\n";
+  const newRules = mergeRulesFile(existingRules, block);
+  const rulesChanged = newRules !== existingRules;
+  if (!opts.apply) {
+    console.log(`neat ${client.id} \u2014 wire NEAT into ${client.label} (plan; nothing written)`);
+    console.log("");
+    console.log(`MCP server \u2192 ${mcpPath}`);
+    console.log(
+      mcpChanged ? "  would add mcpServers.neat:" : "  mcpServers.neat already present and current \u2014 no change:"
+    );
+    console.log(indent(JSON.stringify({ neat: NEAT_MCP_SERVER }, null, 2)));
+    console.log("");
+    console.log(`Graph-first guidance \u2192 ${rulesPath}`);
+    console.log(
+      rulesChanged ? existingRules.includes(GRAPH_FIRST_MARKER_OPEN) ? "  would refresh the neat:graph-first block:" : "  would add the neat:graph-first block:" : "  neat:graph-first block already present and current \u2014 no change."
+    );
+    if (rulesChanged) console.log(indent(block.trimEnd()));
+    console.log("");
+    console.log(`Re-run with --apply to write both files. Existing servers and rules are kept.`);
+    return { exitCode: 0 };
+  }
+  await fs10.mkdir(path11.dirname(mcpPath), { recursive: true });
+  await fs10.writeFile(mcpPath, mcpJson, "utf8");
+  await fs10.mkdir(path11.dirname(rulesPath), { recursive: true });
+  await fs10.writeFile(rulesPath, newRules, "utf8");
+  console.log(`neat ${client.id}: wired NEAT into ${client.label}`);
+  console.log(`  MCP server: ${mcpPath} (mcpServers.neat \u2192 npx -y @neat.is/mcp)`);
+  console.log(`  guidance:   ${rulesPath} (neat:graph-first block)`);
+  console.log("");
+  console.log(`restart ${client.label} to pick up the MCP server. Point it at a non-default`);
+  console.log(`daemon by setting NEAT_CORE_URL in the neat server's env in that config.`);
+  return { exitCode: 0 };
+}
+function indent(text) {
+  return text.split("\n").map((line) => line.length > 0 ? `    ${line}` : line).join("\n");
+}
+function usage3(client) {
+  console.log(`neat ${client.id} \u2014 install NEAT's MCP server + graph-first guidance into ${client.label}`);
+  console.log("");
+  console.log("  --apply   write the MCP config and the rules file (default: plan only)");
+  console.log("");
+  console.log("Writes NEAT's stdio MCP server (npx -y @neat.is/mcp) into");
+  console.log(`  ${client.mcpConfigPath()}`);
+  console.log(`and the graph-first guidance block into ./${client.rulesFileName}, both`);
+  console.log("additively \u2014 existing servers and rules are preserved, a re-run is a no-op.");
+  console.log("");
+  console.log(`See ${client.docsUrl} for ${client.label}'s MCP config format.`);
+}
+async function runEditorCommand(clientId, args, projectDir = process.cwd()) {
+  const client = clientId === "cursor" ? CURSOR_CLIENT : DEVIN_CLIENT;
+  let apply4 = false;
+  for (const arg of args) {
+    switch (arg) {
+      case "--apply":
+        apply4 = true;
+        break;
+      case "-h":
+      case "--help":
+        usage3(client);
+        return 0;
+      default:
+        console.error(`neat ${client.id}: unknown flag "${arg}"`);
+        usage3(client);
+        return 2;
+    }
+  }
+  try {
+    const { exitCode } = await runEditorInstall(client, { apply: apply4, projectDir });
+    return exitCode;
+  } catch (err) {
+    console.error(err.message);
+    return 1;
+  }
+}
+
 // src/monitor.ts
 import { EdgeType, parseEdgeId, Provenance as Provenance3 } from "@neat.is/types";
 
@@ -4484,10 +4947,10 @@ function createHttpClient(baseUrl, bearerToken) {
   const root = baseUrl.replace(/\/$/, "");
   const authHeader = bearerToken && bearerToken.length > 0 ? { authorization: `Bearer ${bearerToken}` } : {};
   return {
-    async get(path12) {
+    async get(path14) {
       let res;
       try {
-        res = await fetch(`${root}${path12}`, {
+        res = await fetch(`${root}${path14}`, {
           headers: { ...authHeader }
         });
       } catch (err) {
@@ -4499,16 +4962,16 @@ function createHttpClient(baseUrl, bearerToken) {
         const body = await res.text().catch(() => "");
         throw new HttpError(
           res.status,
-          `${res.status} ${res.statusText} on GET ${path12}: ${body}`,
+          `${res.status} ${res.statusText} on GET ${path14}: ${body}`,
           body
         );
       }
       return await res.json();
     },
-    async post(path12, body) {
+    async post(path14, body) {
       let res;
       try {
-        res = await fetch(`${root}${path12}`, {
+        res = await fetch(`${root}${path14}`, {
           method: "POST",
           headers: { "content-type": "application/json", ...authHeader },
           body: JSON.stringify(body)
@@ -4522,7 +4985,7 @@ function createHttpClient(baseUrl, bearerToken) {
         const text = await res.text().catch(() => "");
         throw new HttpError(
           res.status,
-          `${res.status} ${res.statusText} on POST ${path12}: ${text}`,
+          `${res.status} ${res.statusText} on POST ${path14}: ${text}`,
           text
         );
       }
@@ -4536,12 +4999,12 @@ function projectPath(project, suffix) {
 }
 async function runRootCause(client, input) {
   const qs = input.errorId ? `?errorId=${encodeURIComponent(input.errorId)}` : "";
-  const path12 = projectPath(
+  const path14 = projectPath(
     input.project,
     `/graph/root-cause/${encodeURIComponent(input.errorNode)}${qs}`
   );
   try {
-    const result = await client.get(path12);
+    const result = await client.get(path14);
     const arrowPath = result.traversalPath.join(" \u2190 ");
     const provenances = result.edgeProvenances.length ? result.edgeProvenances.join(", ") : "(direct, no edges traversed)";
     const summary = `Root cause for ${input.errorNode} is ${result.rootCauseNode}. ` + result.rootCauseReason + (result.fixRecommendation ? ` Recommended fix: ${result.fixRecommendation}.` : "");
@@ -4567,12 +5030,12 @@ async function runRootCause(client, input) {
 }
 async function runBlastRadius(client, input) {
   const qs = input.depth !== void 0 ? `?depth=${input.depth}` : "";
-  const path12 = projectPath(
+  const path14 = projectPath(
     input.project,
     `/graph/blast-radius/${encodeURIComponent(input.nodeId)}${qs}`
   );
   try {
-    const result = await client.get(path12);
+    const result = await client.get(path14);
     if (result.totalAffected === 0) {
       return {
         summary: `${result.origin} has no dependents. Nothing else would break if it failed.`
@@ -4606,12 +5069,12 @@ function formatBlastEntry(n) {
 }
 async function runDependencies(client, input) {
   const depth = input.depth ?? 3;
-  const path12 = projectPath(
+  const path14 = projectPath(
     input.project,
     `/graph/dependencies/${encodeURIComponent(input.nodeId)}?depth=${depth}`
   );
   try {
-    const result = await client.get(path12);
+    const result = await client.get(path14);
     if (result.total === 0) {
       return {
         summary: depth === 1 ? `${input.nodeId} has no direct dependencies in the graph.` : `${input.nodeId} has no dependencies (BFS to depth ${depth}).`
@@ -4703,9 +5166,9 @@ function formatDuration(ms) {
   return `${Math.round(h / 24)}d`;
 }
 async function runIncidents(client, input) {
-  const path12 = input.nodeId ? projectPath(input.project, `/incidents/${encodeURIComponent(input.nodeId)}`) : projectPath(input.project, "/incidents");
+  const path14 = input.nodeId ? projectPath(input.project, `/incidents/${encodeURIComponent(input.nodeId)}`) : projectPath(input.project, "/incidents");
   try {
-    const body = await client.get(path12);
+    const body = await client.get(path14);
     const events = body.events;
     if (events.length === 0) {
       return {
@@ -5068,6 +5531,24 @@ function observedEdgeJson(edge) {
     provenance: edge.provenance
   });
 }
+function policyKey(v) {
+  return `policy|${v.id}`;
+}
+function policySubject(v) {
+  const s = v.subject;
+  if (s.nodeId) return s.nodeId;
+  if (s.edgeId) return s.edgeId;
+  if (s.path && s.path.length > 0) return s.path.join(" \u2192 ");
+  return "";
+}
+function formatPolicyLine(v) {
+  const subject = policySubject(v);
+  const where = subject ? `  (${subject})` : "";
+  return `\u26A0 policy [${v.severity}] ${v.policyName} \u2014 ${v.message}${where}`;
+}
+function policyJson(v) {
+  return JSON.stringify({ kind: "policy", ...v });
+}
 var MonitorEmitter = class {
   constructor(opts) {
     this.opts = opts;
@@ -5111,6 +5592,20 @@ var MonitorEmitter = class {
     this.out(this.opts.json ? observedEdgeJson(edge) : formatObservedEdgeLine(edge));
     return true;
   }
+  // Emit every not-yet-seen policy violation in a fresh /policies/violations
+  // read. Returns the count newly emitted (0 → nothing printed, the silent
+  // path). Idempotent across re-reads: the seen-set keys off the violation id.
+  emitPolicies(response) {
+    let emitted = 0;
+    for (const v of response.violations) {
+      const key = policyKey(v);
+      if (this.seen.has(key)) continue;
+      this.seen.add(key);
+      this.out(this.opts.json ? policyJson(v) : formatPolicyLine(v));
+      emitted++;
+    }
+    return emitted;
+  }
 };
 function parseFrame(raw) {
   let event = "message";
@@ -5165,54 +5660,83 @@ function projectPath2(project, suffix) {
 function backoffDelay(attempt, capMs) {
   return Math.min(capMs, 500 * 2 ** Math.min(attempt, 6));
 }
-async function runMonitor(opts) {
-  const write = opts.write ?? ((line) => process.stdout.write(line));
-  const debounceMs = opts.debounceMs ?? 400;
-  const backoffCapMs = opts.backoffCapMs ?? 1e4;
-  const maxReconnects = opts.maxReconnects ?? Number.POSITIVE_INFINITY;
-  const client = createHttpClient(opts.baseUrl, opts.authToken);
-  const emitter = new MonitorEmitter({ json: opts.json, write });
-  const divergencesPath = projectPath2(opts.project, "/graph/divergences");
-  const eventsUrl = `${opts.baseUrl.replace(/\/$/, "")}${projectPath2(opts.project, "/events")}`;
-  let readTimer = null;
-  let reading = false;
-  let readPending = false;
-  const doRead = async () => {
-    if (reading) {
-      readPending = true;
+var defaultOpenEvents = async (url, headers, signal) => {
+  const res = await fetch(url, { headers, signal });
+  return { ok: res.ok, status: res.status, body: res.body };
+};
+function makeDebouncedReader(read, debounceMs) {
+  let timer = null;
+  let running = false;
+  let pending = false;
+  const cancel = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  };
+  const run = async () => {
+    if (running) {
+      pending = true;
       return;
     }
-    reading = true;
+    running = true;
     try {
-      const result = await client.get(divergencesPath);
-      emitter.emitDivergences(result);
+      await read();
     } catch {
     } finally {
-      reading = false;
-      if (readPending) {
-        readPending = false;
-        scheduleRead();
+      running = false;
+      if (pending) {
+        pending = false;
+        schedule();
       }
     }
   };
-  const scheduleRead = () => {
-    if (readTimer) clearTimeout(readTimer);
-    readTimer = setTimeout(() => {
-      readTimer = null;
-      void doRead();
+  const schedule = () => {
+    cancel();
+    timer = setTimeout(() => {
+      timer = null;
+      void run();
     }, debounceMs);
-    if (typeof readTimer.unref === "function") readTimer.unref();
+    if (typeof timer.unref === "function") timer.unref();
   };
+  return {
+    schedule,
+    runNow: async () => {
+      cancel();
+      await run();
+    },
+    cancel
+  };
+}
+async function runMonitor(opts) {
+  const write = opts.write ?? ((line) => process.stdout.write(line));
+  const debounceMs = opts.debounceMs ?? 400;
+  const backoffCapMs = opts.backoffCapMs ?? 1e4;
+  const maxReconnects = opts.maxReconnects ?? Number.POSITIVE_INFINITY;
+  const client = opts.httpClient ?? createHttpClient(opts.baseUrl, opts.authToken);
+  const openEvents = opts.openEvents ?? defaultOpenEvents;
+  const emitter = new MonitorEmitter({ json: opts.json, write });
+  const divergencesPath = projectPath2(opts.project, "/graph/divergences");
+  const policiesPath = projectPath2(opts.project, "/policies/violations");
+  const eventsUrl = `${opts.baseUrl.replace(/\/$/, "")}${projectPath2(opts.project, "/events")}`;
+  const divergences = makeDebouncedReader(async () => {
+    const result = await client.get(divergencesPath);
+    emitter.emitDivergences(result);
+  }, debounceMs);
+  const policies = makeDebouncedReader(async () => {
+    const result = await client.get(policiesPath);
+    emitter.emitPolicies(result);
+  }, debounceMs);
   const onFrame = (frame) => {
     switch (frame.event) {
       case "extraction-complete":
-        scheduleRead();
+        divergences.schedule();
         break;
       case "stale-transition": {
         const payload = safeParse(frame.data);
         const edgeId = payload && typeof payload.edgeId === "string" ? payload.edgeId : void 0;
         if (edgeId) emitter.emitStale(edgeId);
-        scheduleRead();
+        divergences.schedule();
         break;
       }
       case "edge-added": {
@@ -5220,10 +5744,13 @@ async function runMonitor(opts) {
         const edge = payload?.edge;
         if (edge && edge.provenance === Provenance3.OBSERVED) {
           emitter.emitObservedEdge(edge);
-          scheduleRead();
+          divergences.schedule();
         }
         break;
       }
+      case "policy-violation":
+        policies.schedule();
+        break;
       default:
         break;
     }
@@ -5236,17 +5763,17 @@ async function runMonitor(opts) {
   let firstConnect = true;
   for (let attempt = 0; ; attempt++) {
     if (opts.signal?.aborted) break;
-    let res;
+    let conn;
     try {
-      res = await fetch(eventsUrl, { headers, signal: opts.signal });
+      conn = await openEvents(eventsUrl, headers, opts.signal);
     } catch (err) {
       if (err.name === "AbortError") break;
       if (!connectedOnce || attempt >= maxReconnects) break;
       await sleep(backoffDelay(attempt, backoffCapMs), opts.signal);
       continue;
     }
-    if (!res.ok || !res.body) {
-      await res.body?.cancel().catch(() => {
+    if (!conn.ok || !conn.body) {
+      await conn.body?.cancel().catch(() => {
       });
       if (!connectedOnce || attempt >= maxReconnects) break;
       await sleep(backoffDelay(attempt, backoffCapMs), opts.signal);
@@ -5256,19 +5783,22 @@ async function runMonitor(opts) {
     attempt = 0;
     if (firstConnect) {
       firstConnect = false;
-      await doRead();
+      await divergences.runNow();
+      await policies.runNow();
     } else {
-      scheduleRead();
+      divergences.schedule();
+      policies.schedule();
     }
     try {
-      await drainSse(res.body, onFrame);
+      await drainSse(conn.body, onFrame);
     } catch {
     }
     if (opts.signal?.aborted) break;
     if (attempt >= maxReconnects) break;
     await sleep(backoffDelay(attempt, backoffCapMs), opts.signal);
   }
-  if (readTimer) clearTimeout(readTimer);
+  divergences.cancel();
+  policies.cancel();
   return 0;
 }
 function sleep(ms, signal) {
@@ -5291,7 +5821,7 @@ function sleep(ms, signal) {
 }
 
 // src/cli-verbs.ts
-import path10 from "path";
+import path12 from "path";
 async function resolveProjectEntry(opts) {
   const entries = await listProjects();
   if (opts.project) {
@@ -5301,7 +5831,7 @@ async function resolveProjectEntry(opts) {
   const cwd = opts.cwd ?? process.cwd();
   const resolvedCwd = await normalizeProjectPath(cwd);
   for (const entry2 of entries) {
-    if (resolvedCwd === entry2.path || resolvedCwd.startsWith(`${entry2.path}${path10.sep}`)) {
+    if (resolvedCwd === entry2.path || resolvedCwd.startsWith(`${entry2.path}${path12.sep}`)) {
       return entry2;
     }
   }
@@ -5466,7 +5996,7 @@ function isNpxInvocation() {
 function commandPrefix() {
   return isNpxInvocation() ? "npx neat.is" : "neat";
 }
-function usage2() {
+function usage4() {
   const neat = commandPrefix();
   console.log("Installed via npx? Prefix commands with `npx neat.is`, or install once: `npm i -g neat.is`.");
   console.log("");
@@ -5486,10 +6016,12 @@ function usage2() {
   console.log("                 PORT (default 8080), OTEL_PORT (4318), HOST (0.0.0.0)");
   console.log("                 control listeners. NEAT_OTLP_GRPC=true also opens 4317.");
   console.log("  monitor        Stream live graph facts to stdout \u2014 one line per new");
-  console.log("                 fact \u2014 as the daemon learns them: fresh divergences,");
-  console.log("                 integrations that just went stale, and new observed");
-  console.log("                 runtime dependencies. Silent when nothing is new; exits");
-  console.log("                 clean with no output when no daemon is reachable.");
+  console.log("                 fact \u2014 as the daemon learns them: fresh divergences");
+  console.log("                 (down to the drifting column), integrations that just");
+  console.log("                 went stale, new observed runtime dependencies, and");
+  console.log("                 freshly-tripped policy violations. Silent when nothing");
+  console.log("                 is new; exits clean with no output when no daemon is");
+  console.log("                 reachable.");
   console.log("                 Flags:");
   console.log("                   --project <name>   watch a registered project by name");
   console.log("                   --json             emit one JSON object per line");
@@ -5519,6 +6051,22 @@ function usage2() {
   console.log("                   --print-hook     print the hook script");
   console.log("                   --print-guide    print the graph-first guidance");
   console.log("                   --print-settings print the settings.json block --apply adds");
+  console.log("  codex          Install NEAT into the OpenAI Codex CLI: add [mcp_servers.neat]");
+  console.log("                 to ~/.codex/config.toml and the graph-first block to ./AGENTS.md.");
+  console.log("                 Plan by default; --apply to write.");
+  console.log("                 Flags:");
+  console.log("                   --apply          add the MCP server + AGENTS.md block");
+  console.log("                   --print-config   print the config.toml table");
+  console.log("                   --print-guide    print the AGENTS.md block");
+  console.log("  cursor         Wire NEAT into Cursor: add the MCP server to ~/.cursor/mcp.json");
+  console.log("                 and the graph-first guidance to ./.cursorrules. Plan by default.");
+  console.log("                 Flags:");
+  console.log("                   --apply   write the MCP config + rules file (default: plan)");
+  console.log("  devin          Wire NEAT into Devin Desktop (Cascade): add the MCP server to");
+  console.log("                 ~/.codeium/windsurf/mcp_config.json and the graph-first guidance");
+  console.log("                 to ./.windsurfrules. Plan by default.");
+  console.log("                 Flags:");
+  console.log("                   --apply   write the MCP config + rules file (default: plan)");
   console.log("  deploy         Detect the deploy substrate, generate NEAT_AUTH_TOKEN,");
   console.log("                 emit a docker-compose / systemd / docker run artifact, and");
   console.log("                 print the OTel env-vars block to paste into your platform.");
@@ -5532,7 +6080,8 @@ function usage2() {
   console.log("                   --no-instrument    skip the SDK install apply step");
   console.log("                   --json             emit the delta summary as JSON");
   console.log("  connector      Configure OBSERVED connectors \u2014 pull (supabase, railway,");
-  console.log("                 firebase, cloudflare) and push (vercel, via a trace Drain).");
+  console.log("                 firebase, cloudflare, neon, cloud-run) and push (vercel,");
+  console.log("                 via a trace Drain).");
   console.log("                 Subcommands:");
   console.log("                   add <provider>   add a connector; validates the credential");
   console.log("                                    against the provider first (--skip-validate to skip)");
@@ -5764,7 +6313,7 @@ async function buildPatchSections(services, project) {
 }
 async function runInit(opts) {
   const written = [];
-  const stat = await fs9.stat(opts.scanPath).catch(() => null);
+  const stat = await fs11.stat(opts.scanPath).catch(() => null);
   if (!stat || !stat.isDirectory()) {
     console.error(`neat init: ${opts.scanPath} is not a directory`);
     return { exitCode: 2, writtenFiles: written };
@@ -5773,13 +6322,13 @@ async function runInit(opts) {
   printDiscoveryReport(opts, services);
   const sections = opts.noInstall ? [] : await buildPatchSections(services, opts.project);
   const patch = renderPatch(sections);
-  const patchPath = path11.join(opts.scanPath, "neat.patch");
+  const patchPath = path13.join(opts.scanPath, "neat.patch");
   if (opts.dryRun) {
-    await fs9.writeFile(patchPath, patch, "utf8");
+    await fs11.writeFile(patchPath, patch, "utf8");
     written.push(patchPath);
     console.log(`dry-run: patch written to ${patchPath}`);
-    const gitignorePath = path11.join(opts.scanPath, ".gitignore");
-    const gitignoreExists = await fs9.stat(gitignorePath).then(() => true).catch(() => false);
+    const gitignorePath = path13.join(opts.scanPath, ".gitignore");
+    const gitignoreExists = await fs11.stat(gitignorePath).then(() => true).catch(() => false);
     const verb = gitignoreExists ? "append" : "create";
     console.log(`dry-run: would ${verb} ${gitignorePath} (add neat-out/)`);
     console.log("rerun without --dry-run to register and snapshot.");
@@ -5790,9 +6339,9 @@ async function runInit(opts) {
   const graph = getGraph(graphKey);
   const projectPaths = pathsForProject(
     graphKey,
-    path11.join(opts.scanPath, "neat-out")
+    path13.join(opts.scanPath, "neat-out")
   );
-  const errorsPath = path11.join(path11.dirname(opts.outPath), path11.basename(projectPaths.errorsPath));
+  const errorsPath = path13.join(path13.dirname(opts.outPath), path13.basename(projectPaths.errorsPath));
   const result = await extractFromDirectory(graph, opts.scanPath, { errorsPath });
   await saveGraphToDisk(graph, opts.outPath);
   written.push(opts.outPath);
@@ -5871,7 +6420,7 @@ async function runInit(opts) {
         console.log("Run `npm install` (or your language equivalent) to refresh lockfiles.");
       }
     } else {
-      await fs9.writeFile(patchPath, patch, "utf8");
+      await fs11.writeFile(patchPath, patch, "utf8");
       written.push(patchPath);
     }
   }
@@ -5911,9 +6460,9 @@ var CLAUDE_SKILL_CONFIG = {
 };
 function claudeConfigPath() {
   const override = process.env.NEAT_CLAUDE_CONFIG;
-  if (override && override.length > 0) return path11.resolve(override);
+  if (override && override.length > 0) return path13.resolve(override);
   const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
-  return path11.join(home, ".claude.json");
+  return path13.join(home, ".claude.json");
 }
 async function runSkill(opts) {
   const snippet = JSON.stringify(CLAUDE_SKILL_CONFIG, null, 2) + "\n";
@@ -5925,7 +6474,7 @@ async function runSkill(opts) {
     const target = claudeConfigPath();
     let existing = {};
     try {
-      existing = JSON.parse(await fs9.readFile(target, "utf8"));
+      existing = JSON.parse(await fs11.readFile(target, "utf8"));
     } catch (err) {
       if (err.code !== "ENOENT") {
         console.error(`neat skill: failed to read ${target} \u2014 ${err.message}`);
@@ -5937,8 +6486,8 @@ async function runSkill(opts) {
       ...existing,
       mcpServers: { ...mcp, neat: CLAUDE_SKILL_CONFIG.mcpServers.neat }
     };
-    await fs9.mkdir(path11.dirname(target), { recursive: true });
-    await fs9.writeFile(target, JSON.stringify(merged, null, 2) + "\n", "utf8");
+    await fs11.mkdir(path13.dirname(target), { recursive: true });
+    await fs11.writeFile(target, JSON.stringify(merged, null, 2) + "\n", "utf8");
     console.log(`neat skill: wrote mcpServers.neat to ${target}`);
     console.log("restart Claude Code to pick up the new MCP server.");
     console.log("");
@@ -5965,7 +6514,7 @@ async function main() {
   const argv = process.argv.slice(2);
   const cmd0 = argv[0];
   if (cmd0 === "-h" || cmd0 === "--help") {
-    usage2();
+    usage4();
     process.exit(0);
   }
   if (cmd0 === "--version" || cmd0 === "-v" || cmd0 === "version") {
@@ -5982,6 +6531,16 @@ async function main() {
     if (code !== 0) process.exit(code);
     return;
   }
+  if (cmd0 === "codex") {
+    const code = await runCodexCommand(argv.slice(1));
+    if (code !== 0) process.exit(code);
+    return;
+  }
+  if (cmd0 === "cursor" || cmd0 === "devin") {
+    const code = await runEditorCommand(cmd0, argv.slice(1));
+    if (code !== 0) process.exit(code);
+    return;
+  }
   const argvParsed = parseArgs(argv);
   if (argvParsed.positional.length === 0) {
     const orchestratorCode2 = await tryOrchestrator(process.cwd(), argvParsed);
@@ -5996,19 +6555,19 @@ async function main() {
     const target = positional[0];
     if (!target) {
       console.error("neat init: missing <path>");
-      usage2();
+      usage4();
       process.exit(2);
     }
     if (apply4 && dryRun) {
       console.error("neat init: --apply and --dry-run are mutually exclusive");
       process.exit(2);
     }
-    const scanPath = path11.resolve(target);
+    const scanPath = path13.resolve(target);
     const projectExplicit = parsed.project !== null;
-    const projectName = projectExplicit ? project : path11.basename(scanPath);
+    const projectName = projectExplicit ? project : path13.basename(scanPath);
     const projectKey = projectExplicit ? project : DEFAULT_PROJECT;
-    const fallback = pathsForProject(projectKey, path11.join(scanPath, "neat-out")).snapshotPath;
-    const outPath = path11.resolve(process.env.NEAT_OUT_PATH ?? fallback);
+    const fallback = pathsForProject(projectKey, path13.join(scanPath, "neat-out")).snapshotPath;
+    const outPath = path13.resolve(process.env.NEAT_OUT_PATH ?? fallback);
     const result = await runInit({
       scanPath,
       outPath,
@@ -6026,24 +6585,24 @@ async function main() {
     const target = positional[0];
     if (!target) {
       console.error("neat watch: missing <path>");
-      usage2();
+      usage4();
       process.exit(2);
     }
-    const scanPath = path11.resolve(target);
-    const stat = await fs9.stat(scanPath).catch(() => null);
+    const scanPath = path13.resolve(target);
+    const stat = await fs11.stat(scanPath).catch(() => null);
     if (!stat || !stat.isDirectory()) {
       console.error(`neat watch: ${scanPath} is not a directory`);
       process.exit(2);
     }
-    const projectPaths = pathsForProject(project, path11.join(scanPath, "neat-out"));
-    const outPath = path11.resolve(process.env.NEAT_OUT_PATH ?? projectPaths.snapshotPath);
-    const errorsPath = path11.resolve(
-      process.env.NEAT_ERRORS_PATH ?? path11.join(path11.dirname(outPath), path11.basename(projectPaths.errorsPath))
+    const projectPaths = pathsForProject(project, path13.join(scanPath, "neat-out"));
+    const outPath = path13.resolve(process.env.NEAT_OUT_PATH ?? projectPaths.snapshotPath);
+    const errorsPath = path13.resolve(
+      process.env.NEAT_ERRORS_PATH ?? path13.join(path13.dirname(outPath), path13.basename(projectPaths.errorsPath))
     );
-    const staleEventsPath = path11.resolve(
-      process.env.NEAT_STALE_EVENTS_PATH ?? path11.join(path11.dirname(outPath), path11.basename(projectPaths.staleEventsPath))
+    const staleEventsPath = path13.resolve(
+      process.env.NEAT_STALE_EVENTS_PATH ?? path13.join(path13.dirname(outPath), path13.basename(projectPaths.staleEventsPath))
     );
-    const embeddingsCachePath = process.env.NEAT_EMBEDDINGS_CACHE_PATH ? path11.resolve(process.env.NEAT_EMBEDDINGS_CACHE_PATH) : void 0;
+    const embeddingsCachePath = process.env.NEAT_EMBEDDINGS_CACHE_PATH ? path13.resolve(process.env.NEAT_EMBEDDINGS_CACHE_PATH) : void 0;
     const handle = await startWatch(getGraph(project), {
       scanPath,
       outPath,
@@ -6052,7 +6611,7 @@ async function main() {
       project,
       // Resolve NEAT_HOME so a `neat watch` picks up connectors added to
       // ~/.neat/connectors.json (#871). Same resolution the rest of the CLI uses.
-      neatHome: process.env.NEAT_HOME ? path11.resolve(process.env.NEAT_HOME) : path11.join(os2.homedir(), ".neat"),
+      neatHome: process.env.NEAT_HOME ? path13.resolve(process.env.NEAT_HOME) : path13.join(os4.homedir(), ".neat"),
       ...embeddingsCachePath ? { embeddingsCachePath } : {},
       host: process.env.HOST ?? "0.0.0.0",
       port: Number(process.env.PORT ?? 8080),
@@ -6088,7 +6647,7 @@ async function main() {
     const name = positional[0];
     if (!name) {
       console.error("neat pause: missing <name>");
-      usage2();
+      usage4();
       process.exit(2);
     }
     const daemon = await findDaemonByProject(name);
@@ -6113,7 +6672,7 @@ async function main() {
     const name = positional[0];
     if (!name) {
       console.error("neat resume: missing <name>");
-      usage2();
+      usage4();
       process.exit(2);
     }
     const daemon = await findDaemonByProject(name);
@@ -6143,7 +6702,7 @@ async function main() {
     const name = positional[0];
     if (!name) {
       console.error("neat uninstall: missing <name>");
-      usage2();
+      usage4();
       process.exit(2);
     }
     const daemon = await findDaemonByProject(name);
@@ -6230,15 +6789,15 @@ async function main() {
     return;
   }
   console.error(`neat: unknown command "${cmd}"`);
-  usage2();
+  usage4();
   process.exit(1);
 }
 async function tryOrchestrator(cmd, parsed) {
-  const scanPath = path11.resolve(cmd);
-  const stat = await fs9.stat(scanPath).catch(() => null);
+  const scanPath = path13.resolve(cmd);
+  const stat = await fs11.stat(scanPath).catch(() => null);
   if (!stat || !stat.isDirectory()) return null;
   const projectExplicit = parsed.project !== null;
-  const projectName = projectExplicit ? parsed.project : path11.basename(scanPath);
+  const projectName = projectExplicit ? parsed.project : path13.basename(scanPath);
   const result = await runOrchestrator({
     scanPath,
     project: projectName,
@@ -6526,6 +7085,6 @@ export {
   runMonitorVerb,
   runQueryVerb,
   runSkill,
-  usage2 as usage
+  usage4 as usage
 };
 //# sourceMappingURL=cli.js.map