@neat.is/core 0.4.20-dev.20260629 → 0.4.22

package/dist/cli.d.cts

@@ -78,6 +78,7 @@ declare class ProjectResolutionError extends Error {
     constructor(message: string, exitCode?: number);
 }
 declare function resolveProjectForVerb(client: HttpClient, parsed: ParsedArgs): Promise<string | undefined>;
+declare function resolveDaemonUrl(project?: string): Promise<string>;
 declare function runQueryVerb(cmd: string, parsed: ParsedArgs): Promise<number>;
 
-export { CLAUDE_SKILL_CONFIG, type InitOptions, type InitResult, ProjectResolutionError, QUERY_VERBS, type SkillOptions, commandPrefix, isNpxInvocation, main, parseArgs, printBanner, readPackageVersion, resolveProjectForVerb, runInit, runQueryVerb, runSkill, usage };
+export { CLAUDE_SKILL_CONFIG, type InitOptions, type InitResult, ProjectResolutionError, QUERY_VERBS, type SkillOptions, commandPrefix, isNpxInvocation, main, parseArgs, printBanner, readPackageVersion, resolveDaemonUrl, resolveProjectForVerb, runInit, runQueryVerb, runSkill, usage };

package/dist/cli.d.ts

@@ -78,6 +78,7 @@ declare class ProjectResolutionError extends Error {
     constructor(message: string, exitCode?: number);
 }
 declare function resolveProjectForVerb(client: HttpClient, parsed: ParsedArgs): Promise<string | undefined>;
+declare function resolveDaemonUrl(project?: string): Promise<string>;
 declare function runQueryVerb(cmd: string, parsed: ParsedArgs): Promise<number>;
 
-export { CLAUDE_SKILL_CONFIG, type InitOptions, type InitResult, ProjectResolutionError, QUERY_VERBS, type SkillOptions, commandPrefix, isNpxInvocation, main, parseArgs, printBanner, readPackageVersion, resolveProjectForVerb, runInit, runQueryVerb, runSkill, usage };
+export { CLAUDE_SKILL_CONFIG, type InitOptions, type InitResult, ProjectResolutionError, QUERY_VERBS, type SkillOptions, commandPrefix, isNpxInvocation, main, parseArgs, printBanner, readPackageVersion, resolveDaemonUrl, resolveProjectForVerb, runInit, runQueryVerb, runSkill, usage };

package/dist/cli.js

@@ -1,7 +1,12 @@
 #!/usr/bin/env node
 import {
-  readDaemonRecord
-} from "./chunk-62ELQVIP.js";
+  clearDaemonRecord,
+  portFromListenAddress,
+  readDaemonRecord,
+  resolveHost,
+  resolveNeatVersion,
+  writeDaemonRecord
+} from "./chunk-XRE4OQWJ.js";
 import {
   buildSearchIndex
 } from "./chunk-XOOCA5T7.js";
@@ -14,6 +19,7 @@ import {
   addCallEdges,
   addConfigNodes,
   addDatabasesAndCompat,
+  addFiles,
   addImports,
   addInfra,
   addProject,
@@ -53,17 +59,18 @@ import {
   signalDaemonStop,
   startPersistLoop,
   startStalenessLoop
-} from "./chunk-GNAX2CBF.js";
+} from "./chunk-OQ7CHOY2.js";
 import {
   startOtelGrpcReceiver
-} from "./chunk-MTXF77TN.js";
+} from "./chunk-GAFTW2OX.js";
 import {
   __dirname,
   __require,
   assertBindAuthority,
   buildOtelReceiver,
+  listenSteppingOtlp,
   readAuthEnv
-} from "./chunk-BGPWBRLU.js";
+} from "./chunk-ZX7PCMGZ.js";
 
 // src/cli.ts
 import path9 from "path";
@@ -241,6 +248,7 @@ import chokidar from "chokidar";
 var ALL_PHASES = [
   "services",
   "aliases",
+  "files",
   "imports",
   "databases",
   "configs",
@@ -265,6 +273,7 @@ function classifyChange(relPath) {
     phases.add("aliases");
   }
   if (/\.(?:js|jsx|mjs|cjs|ts|tsx|py)$/.test(base)) {
+    phases.add("files");
     phases.add("imports");
     phases.add("calls");
   }
@@ -287,6 +296,11 @@ async function runExtractPhases(graph, scanPath, phases, project = DEFAULT_PROJE
   if (phases.has("aliases")) {
     await addServiceAliases(graph, scanPath, services);
   }
+  if (phases.has("files")) {
+    const r = await addFiles(graph, services);
+    nodesAdded += r.nodesAdded;
+    edgesAdded += r.edgesAdded;
+  }
   if (phases.has("imports")) {
     const r = await addImports(graph, services);
     nodesAdded += r.nodesAdded;
@@ -321,6 +335,7 @@ async function runExtractPhases(graph, scanPath, phases, project = DEFAULT_PROJE
     durationMs: Date.now() - started
   };
 }
+var DEFAULT_WATCH_WEB_PORT = 6328;
 var IGNORED_WATCH_GLOBS = [
   "**/node_modules/**",
   "**/.git/**",
@@ -469,7 +484,7 @@ async function startWatch(graph, opts) {
     searchIndex
   });
   const api = await buildApi({ projects: registry });
-  await api.listen({ port, host });
+  const restAddress = await api.listen({ port, host });
   console.log(`neat-core listening on http://${host}:${port}`);
   console.log(`  scan path:     ${opts.scanPath} (watching for changes)`);
   console.log(`  snapshot path: ${opts.outPath}`);
@@ -482,10 +497,41 @@ async function startWatch(graph, opts) {
     writeErrorEventInline: false,
     onPolicyTrigger
   });
-  const onErrorSpanSync = makeErrorSpanWriter(opts.errorsPath);
+  const onErrorSpanSync = makeErrorSpanWriter(opts.errorsPath, graph, opts.scanPath);
   const otelHttp = await buildOtelReceiver({ onSpan, onErrorSpanSync });
-  await otelHttp.listen({ port: otelPort, host });
-  console.log(`neat-core OTLP receiver on http://${host}:${otelPort}/v1/traces`);
+  const otelAddress = await listenSteppingOtlp(otelHttp, otelPort, host);
+  const boundOtelPort = portFromListenAddress(otelAddress, otelPort);
+  console.log(`neat-core OTLP receiver on ${otelAddress}/v1/traces`);
+  const boundRestPort = portFromListenAddress(restAddress, port);
+  const daemonRecord = {
+    project: projectName,
+    projectPath: opts.scanPath,
+    pid: process.pid,
+    status: "running",
+    ports: {
+      rest: boundRestPort,
+      otlp: boundOtelPort,
+      // watch serves no dashboard of its own; record the canonical web port so
+      // the record shape is valid. Only ports.otlp is load-bearing here.
+      web: DEFAULT_WATCH_WEB_PORT
+    },
+    startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    neatVersion: resolveNeatVersion()
+  };
+  try {
+    await writeDaemonRecord(daemonRecord);
+    console.log(
+      `neat watch: wrote daemon.json (REST ${boundRestPort} / OTLP ${boundOtelPort})`
+    );
+  } catch (err) {
+    await api.close().catch(() => {
+    });
+    await otelHttp.close().catch(() => {
+    });
+    throw new Error(
+      `neat watch: failed to write daemon.json \u2014 ${err.message}`
+    );
+  }
   let grpcReceiver = null;
   if (opts.otelGrpc) {
     const grpcPort = opts.otelGrpcPort ?? 4317;
@@ -598,6 +644,8 @@ async function startWatch(graph, opts) {
     await api.close();
     await otelHttp.close();
     if (grpcReceiver) await grpcReceiver.stop();
+    await clearDaemonRecord(daemonRecord).catch(() => {
+    });
   };
   return { api, stop };
 }
@@ -1448,9 +1496,23 @@ var WEB_FRAMEWORK_DEPS = [
   "polka",
   "micro"
 ];
-function looksLikeWebApp(pkg) {
+var WORKER_FRAMEWORK_DEPS = [
+  "bullmq",
+  "bull",
+  "bee-queue",
+  "agenda",
+  "kafkajs",
+  "amqplib",
+  "amqp-connection-manager",
+  "nats",
+  "node-resque",
+  "pg-boss",
+  "graphile-worker"
+];
+var APP_FRAMEWORK_DEPS = [...WEB_FRAMEWORK_DEPS, ...WORKER_FRAMEWORK_DEPS];
+function appFrameworkDependencies(pkg) {
   const deps = allDeps(pkg);
-  return WEB_FRAMEWORK_DEPS.some((name) => name in deps);
+  return APP_FRAMEWORK_DEPS.filter((name) => name in deps);
 }
 function uninstrumentedLibraries(pkg) {
   const deps = allDeps(pkg);
@@ -1537,10 +1599,10 @@ async function isTypeScriptProject(serviceDir) {
 var INDEX_EXTENSIONS = [".ts", ".tsx", ".js", ".mjs", ".cjs"];
 var INDEX_CANDIDATES = INDEX_EXTENSIONS.map((ext) => `index${ext}`);
 var SRC_INDEX_CANDIDATES = INDEX_EXTENSIONS.map((ext) => `src/index${ext}`);
-var SRC_NAMED_CANDIDATES = ["server", "main", "app"].flatMap(
+var SRC_NAMED_CANDIDATES = ["server", "main", "app", "worker"].flatMap(
   (name) => INDEX_EXTENSIONS.map((ext) => `src/${name}${ext}`)
 );
-var ROOT_NAMED_CANDIDATES = ["server", "app", "main"].flatMap(
+var ROOT_NAMED_CANDIDATES = ["server", "app", "main", "worker"].flatMap(
   (name) => INDEX_EXTENSIONS.map((ext) => `${name}${ext}`)
 );
 var SCRIPT_LAUNCHERS = /* @__PURE__ */ new Set([
@@ -2797,11 +2859,13 @@ async function applyInstallersOver(services, project, options = {}) {
     } else if (outcome.outcome === "already-instrumented") already++;
     else if (outcome.outcome === "lib-only") {
       libOnly++;
-      if (svc.pkg && looksLikeWebApp(svc.pkg)) {
+      const appDeps = svc.pkg ? appFrameworkDependencies(svc.pkg) : [];
+      if (appDeps.length > 0) {
         const svcName = path7.basename(svc.dir);
+        const list = appDeps.join(", ");
         console.warn(
           `neat: runtime layer won't engage for ${svcName}: no entry point found.
-  ${svc.dir} depends on a web framework but neat couldn't resolve an entry to instrument.
+  ${svc.dir} depends on ${list} \u2014 a runnable app \u2014 but neat couldn't resolve an entry to instrument.
   Add a "start" script to package.json, or point neat at the entry file directly.`
         );
       }
@@ -2869,10 +2933,11 @@ async function applyInstallersOver(services, project, options = {}) {
       if (gaps.length > 0) {
         const svcName = path7.basename(svc.dir);
         const list = gaps.join(", ");
-        const verb = gaps.length === 1 ? "this library" : "these libraries";
+        const subject = gaps.length === 1 ? "this library" : "these libraries";
+        const aux = gaps.length === 1 ? "isn't" : "aren't";
         console.warn(
           `neat: calls to ${list} won't be observed by default in ${svcName}.
-  ${verb} aren't in the default instrumentation set, so they produce no OBSERVED edges.
+  ${subject} ${aux} in the default instrumentation set, so they produce no OBSERVED edges.
   Run \`neat list-uninstrumented\` to review them, then \`neat extend\` to capture them.`
         );
       }
@@ -2966,29 +3031,22 @@ async function probeProjectHealth(restPort, name) {
     });
   });
 }
-async function snapshotProjectStatus(restPort, body) {
+async function snapshotProjectStatus(restPort, project, body) {
   if (body.projects && body.projects.length > 0) {
-    return body.projects.map((p) => ({
-      name: p.name,
-      status: p.status ?? "active"
-    }));
-  }
-  const entries = await listProjects().catch(() => []);
-  if (entries.length === 0) return [];
-  return Promise.all(
-    entries.map(async (entry2) => ({
-      name: entry2.name,
-      status: await probeProjectHealth(restPort, entry2.name)
-    }))
-  );
+    const mine = body.projects.filter((p) => p.name === project);
+    if (mine.length > 0) {
+      return mine.map((p) => ({ name: p.name, status: p.status ?? "active" }));
+    }
+  }
+  return [{ name: project, status: await probeProjectHealth(restPort, project) }];
 }
-async function waitForDaemonReady(restPort, timeoutMs) {
+async function waitForDaemonReady(restPort, project, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   let lastBootstrapping = [];
   while (Date.now() < deadline) {
     const body = await fetchDaemonHealth(restPort);
     if (body !== null) {
-      const projects2 = await snapshotProjectStatus(restPort, body);
+      const projects2 = await snapshotProjectStatus(restPort, project, body);
       const bootstrapping = projects2.filter((p) => p.status === "bootstrapping").map((p) => p.name);
       const broken = projects2.filter((p) => p.status === "broken").map((p) => p.name);
       if (bootstrapping.length === 0) {
@@ -3007,7 +3065,7 @@ async function waitForDaemonReady(restPort, timeoutMs) {
     await new Promise((r) => setTimeout(r, PROBE_INTERVAL_MS));
   }
   const final = await fetchDaemonHealth(restPort);
-  const projects = final ? await snapshotProjectStatus(restPort, final) : [];
+  const projects = final ? await snapshotProjectStatus(restPort, project, final) : [];
   return {
     ready: false,
     brokenProjects: projects.filter((p) => p.status === "broken").map((p) => p.name),
@@ -3015,14 +3073,37 @@ async function waitForDaemonReady(restPort, timeoutMs) {
   };
 }
 var NEAT_PORTS = [8080, 4318, 6328];
-async function isPortFree(port) {
+function probeBind(port, host) {
   return new Promise((resolve) => {
     const server = net.createServer();
-    server.once("error", () => resolve(false));
-    server.once("listening", () => server.close(() => resolve(true)));
-    server.listen(port, "127.0.0.1");
+    server.once("error", (err) => {
+      resolve(err.code === "EADDRINUSE" ? "in-use" : "unavailable");
+    });
+    server.once("listening", () => server.close(() => resolve("free")));
+    server.listen(port, host);
   });
 }
+function crossFamilyHost(host) {
+  switch (host) {
+    case "127.0.0.1":
+    case "localhost":
+      return "::1";
+    case "::1":
+      return "127.0.0.1";
+    case "0.0.0.0":
+      return "::";
+    case "::":
+      return "0.0.0.0";
+    default:
+      return null;
+  }
+}
+async function isPortFree(port, host = "127.0.0.1") {
+  if (await probeBind(port, host) !== "free") return false;
+  const sibling = crossFamilyHost(host);
+  if (sibling && await probeBind(port, sibling) === "in-use") return false;
+  return true;
+}
 function formatPortCollisionMessage(port) {
   return [
     `neat: port ${port} is in use; the NEAT daemon needs it.`,
@@ -3032,13 +3113,13 @@ function formatPortCollisionMessage(port) {
 }
 var PORT_ALLOCATION_ATTEMPTS = 8;
 var PORT_STRIDE = 1;
-async function tripleFree(ports) {
+async function tripleFree(ports, host = "127.0.0.1") {
   for (const p of [ports.rest, ports.otlp, ports.web]) {
-    if (!await isPortFree(p)) return false;
+    if (!await isPortFree(p, host)) return false;
   }
   return true;
 }
-async function allocatePorts() {
+async function allocatePorts(host = "127.0.0.1") {
   const [baseRest, baseOtlp, baseWeb] = NEAT_PORTS;
   for (let i = 0; i < PORT_ALLOCATION_ATTEMPTS; i++) {
     const candidate = {
@@ -3046,7 +3127,7 @@ async function allocatePorts() {
       otlp: baseOtlp + i * PORT_STRIDE,
       web: baseWeb + i * PORT_STRIDE
     };
-    if (await tripleFree(candidate)) return candidate;
+    if (await tripleFree(candidate, host)) return candidate;
   }
   return null;
 }
@@ -3252,16 +3333,20 @@ async function runOrchestrator(opts) {
     }
   }
   const timeoutMs = opts.daemonReadyTimeoutMs ?? DEFAULT_DAEMON_READY_TIMEOUT_MS;
+  const bindHost = resolveHost(
+    {},
+    typeof process.env.NEAT_AUTH_TOKEN === "string" && process.env.NEAT_AUTH_TOKEN.length > 0
+  );
   const persistedPorts = await persistedPortsFor(opts.scanPath);
   let allocated = null;
   if (persistedPorts && await healthIsForProject(persistedPorts.rest, currentProjectName)) {
     result.steps.daemon = "already-running";
     allocated = persistedPorts;
   } else {
-    if (persistedPorts && await isPortFree(persistedPorts.rest) && await tripleFree(persistedPorts)) {
+    if (persistedPorts && await isPortFree(persistedPorts.rest, bindHost) && await tripleFree(persistedPorts, bindHost)) {
       allocated = persistedPorts;
     } else {
-      allocated = await allocatePorts();
+      allocated = await allocatePorts(bindHost);
     }
     if (!allocated) {
       for (const line of formatPortCollisionMessage(NEAT_PORTS[0])) {
@@ -3290,7 +3375,7 @@ async function runOrchestrator(opts) {
             projectPath: opts.scanPath,
             ports: allocated
           });
-          const ready = await waitForDaemonReady(allocated.rest, timeoutMs);
+          const ready = await waitForDaemonReady(allocated.rest, currentProjectName, timeoutMs);
           result.steps.daemon = ready.ready ? "spawned" : "timed-out";
           if (!ready.ready) {
             console.error(`neat: daemon did not become ready within ${timeoutMs}ms`);
@@ -3472,7 +3557,7 @@ async function runBlastRadius(client, input) {
     const result = await client.get(path10);
     if (result.totalAffected === 0) {
       return {
-        summary: `${result.origin} has no downstream dependencies. Nothing else would break if it failed.`
+        summary: `${result.origin} has no dependents. Nothing else would break if it failed.`
       };
     }
     const sorted = [...result.affectedNodes].sort(
@@ -3485,7 +3570,7 @@ async function runBlastRadius(client, input) {
     );
     const provenances = [...new Set(sorted.map((n) => n.edgeProvenance))];
     return {
-      summary: `Blast radius for ${result.origin}: ${result.totalAffected} affected node${result.totalAffected === 1 ? "" : "s"} reachable downstream.`,
+      summary: `Blast radius for ${result.origin}: ${result.totalAffected} dependent node${result.totalAffected === 1 ? "" : "s"} would break if it changed.`,
       block: blockLines.join("\n"),
       confidence: Number.isFinite(minConfidence) ? minConfidence : void 0,
       provenance: provenances.length ? provenances : void 0
@@ -3539,20 +3624,31 @@ async function runDependencies(client, input) {
     throw err;
   }
 }
+function observedDepLine(nodeId, e) {
+  const via = e.source !== nodeId ? ` (via ${e.source})` : "";
+  return `  \u2022 ${e.target} \u2014 ${e.type}${via}${edgeMeta(e)}`;
+}
 async function runObservedDependencies(client, input) {
   try {
-    const edges = await client.get(
-      projectPath(input.project, `/graph/edges/${encodeURIComponent(input.nodeId)}`)
+    const result = await client.get(
+      projectPath(
+        input.project,
+        `/graph/observed-dependencies/${encodeURIComponent(input.nodeId)}`
+      )
     );
-    const observed = edges.outbound.filter((e) => e.provenance === Provenance2.OBSERVED);
-    if (observed.length === 0) {
-      const hasExtracted = edges.outbound.some((e) => e.provenance === Provenance2.EXTRACTED);
-      const note = hasExtracted ? " Static (EXTRACTED) dependencies exist but no runtime traffic has been seen \u2014 is OTel running?" : "";
+    if (result.dependencies.length === 0) {
+      if (result.observed) {
+        return {
+          summary: `${input.nodeId} makes no outbound runtime calls, but OTel has observed it receiving traffic on ${result.inboundObservedCount} inbound call path${result.inboundObservedCount === 1 ? "" : "s"} \u2014 it's a pure receiver.`,
+          provenance: Provenance2.OBSERVED
+        };
+      }
+      const note = result.hasExtractedOutbound ? " Static (EXTRACTED) dependencies exist but no runtime traffic has been seen \u2014 is OTel running?" : "";
       return { summary: `No OBSERVED dependencies for ${input.nodeId}.${note}` };
     }
-    const blockLines = observed.map((e) => `  \u2022 ${e.target} \u2014 ${e.type}${edgeMeta(e)}`);
+    const blockLines = result.dependencies.map((e) => observedDepLine(input.nodeId, e));
     return {
-      summary: `${input.nodeId} has ${observed.length} runtime dependenc${observed.length === 1 ? "y" : "ies"} confirmed by OTel.`,
+      summary: `${input.nodeId} has ${result.dependencies.length} runtime dependenc${result.dependencies.length === 1 ? "y" : "ies"} confirmed by OTel.`,
       block: blockLines.join("\n"),
       provenance: Provenance2.OBSERVED
     };
@@ -4099,7 +4195,7 @@ function usage() {
   console.log("query commands (mirror the MCP tools, ADR-050):");
   console.log("  root-cause <node-id>             Walk inbound edges to find what broke first.");
   console.log(`                                   example: ${neat} root-cause service:<name>`);
-  console.log("  blast-radius <node-id>           BFS outbound \u2014 what would break if this dies.");
+  console.log("  blast-radius <node-id>           BFS inbound \u2014 the dependents that break if this dies.");
   console.log(`                                   example: ${neat} blast-radius database:<host>`);
   console.log("  dependencies <node-id>           Transitive outbound dependencies.");
   console.log("                                   Flags: --depth N (default 3, max 10)");
@@ -4826,11 +4922,18 @@ Pass --project <name> to choose:
 ${names}`
   );
 }
-function resolveDaemonUrl() {
-  return process.env.NEAT_API_URL ?? process.env.NEAT_CORE_URL ?? "http://localhost:8080";
+async function resolveDaemonUrl(project) {
+  const explicit = process.env.NEAT_API_URL ?? process.env.NEAT_CORE_URL;
+  if (explicit) return explicit;
+  if (project) {
+    const daemon = await findDaemonByProject(project);
+    if (daemon) return `http://localhost:${daemon.record.ports.rest}`;
+  }
+  return "http://localhost:8080";
 }
 async function runQueryVerb(cmd, parsed) {
-  const baseUrl = resolveDaemonUrl();
+  const requestedProject = resolveProjectFlag(parsed);
+  const baseUrl = await resolveDaemonUrl(requestedProject);
   const client = createHttpClient(baseUrl, resolveAuthToken());
   const positional = parsed.positional;
   let makeWork;
@@ -4986,7 +5089,7 @@ async function runQueryVerb(cmd, parsed) {
       const detail = err.responseBody.length > 0 ? err.responseBody : err.message;
       console.error(`neat ${cmd}: ${detail.trim()}`);
     } else if (err instanceof TransportError) {
-      console.error(`neat ${cmd}: ${err.message}. Is the daemon running? (NEAT_API_URL=${resolveDaemonUrl()})`);
+      console.error(`neat ${cmd}: ${err.message}. Is the daemon running? (endpoint=${baseUrl})`);
     } else {
       console.error(`neat ${cmd}: ${err.message}`);
     }
@@ -5010,6 +5113,7 @@ export {
   parseArgs,
   printBanner,
   readPackageVersion,
+  resolveDaemonUrl,
   resolveProjectForVerb,
   runInit,
   runQueryVerb,