@neat.is/core 0.7.1 → 0.7.2

package/dist/cli.d.cts

@@ -80,5 +80,6 @@ declare class ProjectResolutionError extends Error {
 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>;
+declare function runMonitorVerb(parsed: ParsedArgs): Promise<number>;
 
-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 };
+export { CLAUDE_SKILL_CONFIG, type InitOptions, type InitResult, ProjectResolutionError, QUERY_VERBS, type SkillOptions, commandPrefix, isNpxInvocation, main, parseArgs, printBanner, readPackageVersion, resolveDaemonUrl, resolveProjectForVerb, runInit, runMonitorVerb, runQueryVerb, runSkill, usage };

package/dist/cli.d.ts

@@ -80,5 +80,6 @@ declare class ProjectResolutionError extends Error {
 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>;
+declare function runMonitorVerb(parsed: ParsedArgs): Promise<number>;
 
-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 };
+export { CLAUDE_SKILL_CONFIG, type InitOptions, type InitResult, ProjectResolutionError, QUERY_VERBS, type SkillOptions, commandPrefix, isNpxInvocation, main, parseArgs, printBanner, readPackageVersion, resolveDaemonUrl, resolveProjectForVerb, runInit, runMonitorVerb, runQueryVerb, runSkill, usage };

package/dist/cli.js

@@ -3590,8 +3590,8 @@ async function healthIsForProject(restPort, project) {
   }
   return false;
 }
-function daemonLogPath(projectPath2) {
-  return path8.join(projectPath2, "neat-out", "daemon.log");
+function daemonLogPath(projectPath3) {
+  return path8.join(projectPath3, "neat-out", "daemon.log");
 }
 function spawnDaemonDetached(spec) {
   const here = path8.dirname(fileURLToPath2(import.meta.url));
@@ -4455,8 +4455,8 @@ async function runHooksCommand(args) {
   }
 }
 
-// src/cli-verbs.ts
-import path10 from "path";
+// src/monitor.ts
+import { EdgeType, parseEdgeId, Provenance as Provenance3 } from "@neat.is/types";
 
 // src/cli-client.ts
 import { Provenance as Provenance2 } from "@neat.is/types";
@@ -4988,7 +4988,310 @@ async function pushSnapshotToRemote(input) {
   );
 }
 
+// src/monitor.ts
+var OBSERVED_DEP_EDGE_TYPES = /* @__PURE__ */ new Set([
+  EdgeType.CALLS,
+  EdgeType.CONNECTS_TO,
+  EdgeType.PUBLISHES_TO,
+  EdgeType.CONSUMES_FROM
+]);
+function divergenceKey(d) {
+  const column = "column" in d && d.column ? d.column : "";
+  const edgeType = "edgeType" in d && d.edgeType ? d.edgeType : "";
+  let extra = "";
+  switch (d.type) {
+    case "version-mismatch":
+      extra = `${d.extractedVersion}->${d.observedVersion}`;
+      break;
+    case "host-mismatch":
+      extra = `${d.extractedHost}->${d.observedHost}`;
+      break;
+    case "compat-violation":
+      extra = `${d.rule.kind}:${d.rule.package ?? ""}`;
+      break;
+    default:
+      extra = "";
+  }
+  return `div|${d.type}|${d.source}|${d.target}|${edgeType}|${column}|${extra}`;
+}
+function tableLabel(d) {
+  return "table" in d && d.table ? d.table : d.source;
+}
+function formatDivergenceLine2(d) {
+  switch (d.type) {
+    case "missing-observed":
+      if (d.column) {
+        return `\u26A0 divergence [missing-observed] ${tableLabel(d)}.${d.column} declared, never observed in production`;
+      }
+      return `\u26A0 divergence [missing-observed] ${d.source} \u2192 ${d.target} declared, never observed in production`;
+    case "missing-extracted":
+      if (d.column) {
+        return `\u26A0 divergence [missing-extracted] production writes ${tableLabel(d)}.${d.column} \u2014 not declared in code`;
+      }
+      return `\u26A0 divergence [missing-extracted] production ${d.source} \u2192 ${d.target} \u2014 not declared in code`;
+    case "version-mismatch":
+      return `\u26A0 divergence [version-mismatch] ${d.source} \u2192 ${d.target} declared ${d.extractedVersion}, observed ${d.observedVersion} (${d.compatibility})`;
+    case "host-mismatch":
+      return `\u26A0 divergence [host-mismatch] ${d.source} \u2192 ${d.target} declared host ${d.extractedHost}, observed host ${d.observedHost}`;
+    case "compat-violation":
+      return `\u26A0 divergence [compat-violation] ${d.source} \u2192 ${d.target} \u2014 ${d.rule.kind}${d.rule.package ? ` (${d.rule.package})` : ""}`;
+  }
+}
+function formatStaleLine(edgeId) {
+  const parsed = parseEdgeId(edgeId);
+  if (parsed) {
+    return `\u22EF stale  ${parsed.source} \u2192 ${parsed.target}  (observed edge went quiet)`;
+  }
+  return `\u22EF stale  ${edgeId}  (observed edge went quiet)`;
+}
+function formatObservedEdgeLine(edge) {
+  return `+ observed  ${edge.source} \u2192 ${edge.target}  (new runtime dependency)`;
+}
+function divergenceJson(d) {
+  return JSON.stringify({ kind: "divergence", ...d });
+}
+function staleJson(edgeId) {
+  const parsed = parseEdgeId(edgeId);
+  return JSON.stringify({
+    kind: "stale",
+    edgeId,
+    ...parsed ? { source: parsed.source, target: parsed.target, edgeType: parsed.type } : {}
+  });
+}
+function observedEdgeJson(edge) {
+  return JSON.stringify({
+    kind: "observed",
+    id: edge.id,
+    source: edge.source,
+    target: edge.target,
+    edgeType: edge.type,
+    provenance: edge.provenance
+  });
+}
+var MonitorEmitter = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  seen = /* @__PURE__ */ new Set();
+  out(line) {
+    this.opts.write(line + "\n");
+  }
+  // Emit every not-yet-seen divergence in a fresh result. Returns the count
+  // newly emitted (0 → nothing printed, the silent path). Idempotent across
+  // re-reads: the seen-set keys off divergenceKey.
+  emitDivergences(result) {
+    let emitted = 0;
+    for (const d of result.divergences) {
+      const key = divergenceKey(d);
+      if (this.seen.has(key)) continue;
+      this.seen.add(key);
+      this.out(this.opts.json ? divergenceJson(d) : formatDivergenceLine2(d));
+      emitted++;
+    }
+    return emitted;
+  }
+  // Emit a stale-transition once, keyed on the edge id.
+  emitStale(edgeId) {
+    const key = `stale|${edgeId}`;
+    if (this.seen.has(key)) return false;
+    this.seen.add(key);
+    this.out(this.opts.json ? staleJson(edgeId) : formatStaleLine(edgeId));
+    return true;
+  }
+  // Emit a new OBSERVED runtime dependency once, keyed on the edge id. Silently
+  // ignores non-OBSERVED edges and non-dependency edge types (structural
+  // ownership), so only real runtime dependencies reach stdout.
+  emitObservedEdge(edge) {
+    if (edge.provenance !== Provenance3.OBSERVED) return false;
+    if (!OBSERVED_DEP_EDGE_TYPES.has(edge.type)) return false;
+    const key = `edge|${edge.id}`;
+    if (this.seen.has(key)) return false;
+    this.seen.add(key);
+    this.out(this.opts.json ? observedEdgeJson(edge) : formatObservedEdgeLine(edge));
+    return true;
+  }
+};
+function parseFrame(raw) {
+  let event = "message";
+  const dataLines = [];
+  for (const line of raw.split("\n")) {
+    if (line.length === 0 || line.startsWith(":")) continue;
+    if (line.startsWith("event:")) {
+      event = line.slice("event:".length).trim();
+    } else if (line.startsWith("data:")) {
+      dataLines.push(line.slice("data:".length).replace(/^ /, ""));
+    }
+  }
+  if (dataLines.length === 0) return null;
+  return { event, data: dataLines.join("\n") };
+}
+async function drainSse(body, onFrame) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      buf = buf.replace(/\r\n/g, "\n");
+      let idx;
+      while ((idx = buf.indexOf("\n\n")) !== -1) {
+        const rawFrame = buf.slice(0, idx);
+        buf = buf.slice(idx + 2);
+        const frame = parseFrame(rawFrame);
+        if (frame) onFrame(frame);
+      }
+    }
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+    }
+  }
+}
+function safeParse(data) {
+  try {
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
+function projectPath2(project, suffix) {
+  if (!project) return suffix;
+  return `/projects/${encodeURIComponent(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;
+      return;
+    }
+    reading = true;
+    try {
+      const result = await client.get(divergencesPath);
+      emitter.emitDivergences(result);
+    } catch {
+    } finally {
+      reading = false;
+      if (readPending) {
+        readPending = false;
+        scheduleRead();
+      }
+    }
+  };
+  const scheduleRead = () => {
+    if (readTimer) clearTimeout(readTimer);
+    readTimer = setTimeout(() => {
+      readTimer = null;
+      void doRead();
+    }, debounceMs);
+    if (typeof readTimer.unref === "function") readTimer.unref();
+  };
+  const onFrame = (frame) => {
+    switch (frame.event) {
+      case "extraction-complete":
+        scheduleRead();
+        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();
+        break;
+      }
+      case "edge-added": {
+        const payload = safeParse(frame.data);
+        const edge = payload?.edge;
+        if (edge && edge.provenance === Provenance3.OBSERVED) {
+          emitter.emitObservedEdge(edge);
+          scheduleRead();
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  };
+  const headers = { accept: "text/event-stream" };
+  if (opts.authToken && opts.authToken.length > 0) {
+    headers.authorization = `Bearer ${opts.authToken}`;
+  }
+  let connectedOnce = false;
+  let firstConnect = true;
+  for (let attempt = 0; ; attempt++) {
+    if (opts.signal?.aborted) break;
+    let res;
+    try {
+      res = await fetch(eventsUrl, { headers, signal: 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 (!connectedOnce || attempt >= maxReconnects) break;
+      await sleep(backoffDelay(attempt, backoffCapMs), opts.signal);
+      continue;
+    }
+    connectedOnce = true;
+    attempt = 0;
+    if (firstConnect) {
+      firstConnect = false;
+      await doRead();
+    } else {
+      scheduleRead();
+    }
+    try {
+      await drainSse(res.body, onFrame);
+    } catch {
+    }
+    if (opts.signal?.aborted) break;
+    if (attempt >= maxReconnects) break;
+    await sleep(backoffDelay(attempt, backoffCapMs), opts.signal);
+  }
+  if (readTimer) clearTimeout(readTimer);
+  return 0;
+}
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    if (typeof timer.unref === "function") timer.unref();
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
 // src/cli-verbs.ts
+import path10 from "path";
 async function resolveProjectEntry(opts) {
   const entries = await listProjects();
   if (opts.project) {
@@ -5182,6 +5485,14 @@ function usage2() {
   console.log("  watch <path>   Start neat-core, watch <path>, re-extract on changes.");
   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("                 Flags:");
+  console.log("                   --project <name>   watch a registered project by name");
+  console.log("                   --json             emit one JSON object per line");
   console.log("  list           Report the daemons running on this machine (alias: ps).");
   console.log("                 Reads ~/.neat/daemons/ and folds in any registered");
   console.log("                 project no daemon has self-described yet.");
@@ -5841,14 +6152,14 @@ async function main() {
       console.error(`neat uninstall: no project named "${name}"`);
       process.exit(1);
     }
-    const projectPath2 = daemon?.record.projectPath ?? removed?.path ?? "(unknown path)";
+    const projectPath3 = daemon?.record.projectPath ?? removed?.path ?? "(unknown path)";
     if (daemon) {
       if (daemon.live && signalDaemonStop(daemon.record.pid)) {
         console.log(`uninstall: ${name} \u2014 stopped daemon pid ${daemon.record.pid}`);
       }
       await removeDaemonRecord(daemon.source);
     }
-    console.log(`unregistered: ${name} (${projectPath2})`);
+    console.log(`unregistered: ${name} (${projectPath3})`);
     console.log("note: neat-out/, policy.json, and other files at the project path were left in place.");
     return;
   }
@@ -5903,6 +6214,11 @@ async function main() {
     if (result.exitCode !== 0) process.exit(result.exitCode);
     return;
   }
+  if (cmd === "monitor") {
+    const code = await runMonitorVerb(parsed);
+    if (code !== 0) process.exit(code);
+    return;
+  }
   if (QUERY_VERBS.has(cmd)) {
     const code = await runQueryVerb(cmd, parsed);
     if (code !== 0) process.exit(code);
@@ -6156,6 +6472,37 @@ async function runQueryVerb(cmd, parsed) {
     return exitCodeForError(err);
   }
 }
+async function runMonitorVerb(parsed) {
+  const requestedProject = resolveProjectFlag(parsed);
+  const baseUrl = await resolveDaemonUrl(requestedProject);
+  const token = resolveAuthToken();
+  const client = createHttpClient(baseUrl, token);
+  let project;
+  try {
+    project = await resolveProjectForVerb(client, parsed);
+  } catch (err) {
+    if (err instanceof ProjectResolutionError) {
+      console.error(`neat monitor: ${err.message}`);
+    }
+    return 0;
+  }
+  const controller = new AbortController();
+  const onSignal = () => controller.abort();
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
+  try {
+    return await runMonitor({
+      baseUrl,
+      project,
+      json: parsed.json,
+      authToken: token,
+      signal: controller.signal
+    });
+  } finally {
+    process.off("SIGINT", onSignal);
+    process.off("SIGTERM", onSignal);
+  }
+}
 var entry = process.argv[1] ?? "";
 if (/[\\/](?:cli\.(?:cjs|js)|cli|neat|neat\.is)$/.test(entry)) {
   main().catch((err) => {
@@ -6176,6 +6523,7 @@ export {
   resolveDaemonUrl,
   resolveProjectForVerb,
   runInit,
+  runMonitorVerb,
   runQueryVerb,
   runSkill,
   usage2 as usage