@neat.is/core 0.4.4 → 0.4.6

package/dist/cli.cjs

@@ -49,9 +49,9 @@ function mountBearerAuth(app, opts) {
   const suffixes = [...DEFAULT_UNAUTH_SUFFIXES, ...opts.extraUnauthenticatedSuffixes ?? []];
   const publicRead = opts.publicRead === true;
   app.addHook("preHandler", (req, reply, done) => {
-    const path45 = (req.url.split("?")[0] ?? "").replace(/\/+$/, "");
+    const path46 = (req.url.split("?")[0] ?? "").replace(/\/+$/, "");
     for (const suffix of suffixes) {
-      if (path45 === suffix || path45.endsWith(suffix)) {
+      if (path46 === suffix || path46.endsWith(suffix)) {
         done();
         return;
       }
@@ -301,12 +301,15 @@ function parseOtlpRequest(body) {
   const out = [];
   for (const rs of body.resourceSpans ?? []) {
     const resourceAttrs = attrsToRecord(rs.resource?.attributes);
-    const service = typeof resourceAttrs["service.name"] === "string" ? resourceAttrs["service.name"] : "unknown";
+    const rawServiceName = resourceAttrs["service.name"];
+    const resourceServiceNamePresent = typeof rawServiceName === "string" && rawServiceName.length > 0;
+    const service = resourceServiceNamePresent ? rawServiceName : "unidentified";
     for (const ss of rs.scopeSpans ?? []) {
       for (const span of ss.spans ?? []) {
         const attrs = attrsToRecord(span.attributes);
         const parsed = {
           service,
+          resourceServiceNamePresent,
           traceId: span.traceId ?? "",
           spanId: span.spanId ?? "",
           parentSpanId: span.parentSpanId || void 0,
@@ -559,8 +562,8 @@ __export(cli_exports, {
 });
 module.exports = __toCommonJS(cli_exports);
 init_cjs_shims();
-var import_node_path44 = __toESM(require("path"), 1);
-var import_node_fs28 = require("fs");
+var import_node_path45 = __toESM(require("path"), 1);
+var import_node_fs29 = require("fs");
 var import_node_url3 = require("url");
 
 // src/graph.ts
@@ -1071,19 +1074,19 @@ function confidenceFromMix(edges, now = Date.now()) {
 function longestIncomingWalk(graph, start, maxDepth) {
   let best = { path: [start], edges: [] };
   const visited = /* @__PURE__ */ new Set([start]);
-  function step(node, path45, edges) {
-    if (path45.length > best.path.length) {
-      best = { path: [...path45], edges: [...edges] };
+  function step(node, path46, edges) {
+    if (path46.length > best.path.length) {
+      best = { path: [...path46], edges: [...edges] };
     }
-    if (path45.length - 1 >= maxDepth) return;
+    if (path46.length - 1 >= maxDepth) return;
     const incoming = bestEdgeBySource(graph, graph.inboundEdges(node));
     for (const [srcId, edge] of incoming) {
       if (visited.has(srcId)) continue;
       visited.add(srcId);
-      path45.push(srcId);
+      path46.push(srcId);
       edges.push(edge);
-      step(srcId, path45, edges);
-      path45.pop();
+      step(srcId, path46, edges);
+      path46.pop();
       edges.pop();
       visited.delete(srcId);
     }
@@ -1620,6 +1623,14 @@ function thresholdForEdgeType(edgeType, overrides) {
 function nowIso(ctx) {
   return new Date(ctx.now ? ctx.now() : Date.now()).toISOString();
 }
+var unidentifiedWarnedProjects = /* @__PURE__ */ new Set();
+function warnUnidentifiedSpan(project) {
+  if (unidentifiedWarnedProjects.has(project)) return;
+  unidentifiedWarnedProjects.add(project);
+  console.warn(
+    `[neatd] span lacked service.name; routed to 'unidentified' in project ${project}; check your OTel SDK config.`
+  );
+}
 function pickAttr(span, ...keys) {
   for (const k of keys) {
     const v = span.attributes[k];
@@ -1874,6 +1885,9 @@ async function handleSpan(ctx, span) {
   const ts = span.startTimeIso ?? nowIso(ctx);
   const nowMs = ctx.now ? ctx.now() : Date.now();
   const env = span.env ?? "unknown";
+  if (span.resourceServiceNamePresent === false) {
+    warnUnidentifiedSpan(ctx.project ?? DEFAULT_PROJECT);
+  }
   const sourceId = ensureServiceNode(ctx.graph, span.service, env);
   const isError = span.statusCode === 2;
   cacheSpanService(span, nowMs);
@@ -6559,22 +6573,40 @@ var OTEL_INIT_CJS = `${OTEL_INIT_HEADER}
 process.env.OTEL_SERVICE_NAME ||= '__SERVICE_NAME__'
 process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ||= 'http://localhost:4318/projects/__PROJECT__/v1/traces'
 
-require('@opentelemetry/auto-instrumentations-node/register')
+const { NodeSDK } = require('@opentelemetry/sdk-node')
+const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node')
+
+const instrumentations = [getNodeAutoInstrumentations()]
+__INSTRUMENTATION_BLOCK__
+new NodeSDK({ instrumentations }).start()
 `;
 var OTEL_INIT_ESM = `${OTEL_INIT_HEADER}
 process.env.OTEL_SERVICE_NAME ||= '__SERVICE_NAME__'
 process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ||= 'http://localhost:4318/projects/__PROJECT__/v1/traces'
 
-await import('@opentelemetry/auto-instrumentations-node/register')
+import { NodeSDK } from '@opentelemetry/sdk-node'
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
+
+const instrumentations = [getNodeAutoInstrumentations()]
+__INSTRUMENTATION_BLOCK__
+new NodeSDK({ instrumentations }).start()
 `;
 var OTEL_INIT_TS = `${OTEL_INIT_HEADER}
 process.env.OTEL_SERVICE_NAME ||= '__SERVICE_NAME__'
 process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ||= 'http://localhost:4318/projects/__PROJECT__/v1/traces'
 
-await import('@opentelemetry/auto-instrumentations-node/register')
+import { NodeSDK } from '@opentelemetry/sdk-node'
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
+
+const instrumentations = [getNodeAutoInstrumentations()]
+__INSTRUMENTATION_BLOCK__
+new NodeSDK({ instrumentations }).start()
 `;
-function renderNodeOtelInit(template, serviceName, projectName) {
-  return template.replace(/__SERVICE_NAME__/g, serviceName).replace(/__PROJECT__/g, projectName);
+function renderNodeOtelInit(template, serviceName, projectName, registrations = []) {
+  const block = registrations.length === 0 ? "" : `
+${registrations.join("\n")}
+`;
+  return template.replace(/__SERVICE_NAME__/g, serviceName).replace(/__PROJECT__/g, projectName).replace(/__INSTRUMENTATION_BLOCK__\n?/g, block);
 }
 function renderEnvNeat(serviceName, projectName) {
   return [
@@ -6606,7 +6638,9 @@ process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ||= 'http://localhost:4318/projec
 import { NodeSDK } from '@opentelemetry/sdk-node'
 import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
 
-new NodeSDK({ instrumentations: [getNodeAutoInstrumentations()] }).start()
+const instrumentations = [getNodeAutoInstrumentations()]
+__INSTRUMENTATION_BLOCK__
+new NodeSDK({ instrumentations }).start()
 `;
 var NEXT_INSTRUMENTATION_NODE_JS = `${NEXT_INSTRUMENTATION_HEADER}
 process.env.OTEL_SERVICE_NAME ||= '__SERVICE_NAME__'
@@ -6615,10 +6649,15 @@ process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ||= 'http://localhost:4318/projec
 const { NodeSDK } = require('@opentelemetry/sdk-node')
 const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node')
 
-new NodeSDK({ instrumentations: [getNodeAutoInstrumentations()] }).start()
+const instrumentations = [getNodeAutoInstrumentations()]
+__INSTRUMENTATION_BLOCK__
+new NodeSDK({ instrumentations }).start()
 `;
-function renderNextInstrumentationNode(template, serviceName, projectName) {
-  return template.replace(/__SERVICE_NAME__/g, serviceName).replace(/__PROJECT__/g, projectName);
+function renderNextInstrumentationNode(template, serviceName, projectName, registrations = []) {
+  const block = registrations.length === 0 ? "" : `
+${registrations.join("\n")}
+`;
+  return template.replace(/__SERVICE_NAME__/g, serviceName).replace(/__PROJECT__/g, projectName).replace(/__INSTRUMENTATION_BLOCK__\n?/g, block);
 }
 var FRAMEWORK_OTEL_INIT_HEADER = "// Generated by `neat init --apply` (ADR-074). OpenTelemetry SDK hook.";
 var FRAMEWORK_OTEL_INIT_TS_BODY = `${FRAMEWORK_OTEL_INIT_HEADER}
@@ -6714,6 +6753,25 @@ var SDK_PACKAGES = [
   { name: "@opentelemetry/sdk-node", version: "^0.57.0" },
   { name: "@opentelemetry/auto-instrumentations-node", version: "^0.55.0" }
 ];
+function getMajor(versionRange) {
+  if (!versionRange) return 0;
+  const match = versionRange.match(/(\d+)/);
+  return match ? parseInt(match[1], 10) : 0;
+}
+function detectNonBundledInstrumentations(pkg) {
+  const deps = allDeps(pkg);
+  const out = [];
+  if ("@prisma/client" in deps) {
+    const prismaMajor = getMajor(deps["@prisma/client"]);
+    const prismaInstrVersion = prismaMajor >= 6 ? "^6.0.0" : "^5.0.0";
+    out.push({
+      pkg: "@prisma/instrumentation",
+      version: prismaInstrVersion,
+      registration: "instrumentations.push(new (require('@prisma/instrumentation').PrismaInstrumentation)())"
+    });
+  }
+  return out;
+}
 var OTEL_ENV = {
   // ADR-069 §4 — endpoint moves into the per-package .env.neat (written
   // by the apply phase). The envEdits surface stays for the dry-run
@@ -7004,8 +7062,19 @@ async function planNext(serviceDir, pkg, manifestPath, nextConfigPath, project)
       version: sdk.version
     });
   }
+  const nonBundled = detectNonBundledInstrumentations(pkg);
+  for (const inst of nonBundled) {
+    if (inst.pkg in existingDeps) continue;
+    dependencyEdits.push({
+      file: manifestPath,
+      kind: "add",
+      name: inst.pkg,
+      version: inst.version
+    });
+  }
   const svcName = serviceNodeName(pkg, serviceDir);
   const projectName = projectToken(pkg, serviceDir, project);
+  const registrations = nonBundled.map((i) => i.registration);
   const generatedFiles = [];
   if (!await exists2(instrumentationFile)) {
     generatedFiles.push({
@@ -7020,7 +7089,8 @@ async function planNext(serviceDir, pkg, manifestPath, nextConfigPath, project)
       contents: renderNextInstrumentationNode(
         useTs ? NEXT_INSTRUMENTATION_NODE_TS : NEXT_INSTRUMENTATION_NODE_JS,
         svcName,
-        projectName
+        projectName,
+        registrations
       ),
       skipIfExists: true
     });
@@ -7370,55 +7440,73 @@ async function planAstro(serviceDir, pkg, manifestPath, project) {
     framework: "astro"
   };
 }
-async function plan(serviceDir, opts) {
-  const pkg = await readPackageJson(serviceDir);
-  const manifestPath = import_node_path40.default.join(serviceDir, "package.json");
-  const project = opts?.project;
-  const empty = {
-    language: "javascript",
-    serviceDir,
-    dependencyEdits: [],
-    entrypointEdits: [],
-    envEdits: [],
-    generatedFiles: []
-  };
-  if (!pkg) return empty;
+async function findFrameworkDispatch(serviceDir, pkg, manifestPath, project) {
   if (hasNextDependency(pkg)) {
     const nextConfig = await findNextConfig(serviceDir);
     if (nextConfig) {
-      return planNext(serviceDir, pkg, manifestPath, nextConfig, project);
+      return () => planNext(serviceDir, pkg, manifestPath, nextConfig, project);
     }
   }
   if (hasRemixDependency(pkg)) {
     const remixEntry = await findRemixEntry(serviceDir);
     if (remixEntry) {
-      return planRemix(serviceDir, pkg, manifestPath, remixEntry, project);
+      return () => planRemix(serviceDir, pkg, manifestPath, remixEntry, project);
     }
   }
   if (hasSvelteKitDependency(pkg)) {
     const hooks = await findSvelteKitHooks(serviceDir);
     const config = await findSvelteKitConfig(serviceDir);
     if (hooks || config) {
-      return planSvelteKit(serviceDir, pkg, manifestPath, hooks, project);
+      return () => planSvelteKit(serviceDir, pkg, manifestPath, hooks, project);
     }
   }
   if (hasNuxtDependency(pkg)) {
     const nuxtConfig = await findNuxtConfig(serviceDir);
     if (nuxtConfig) {
-      return planNuxt(serviceDir, pkg, manifestPath, project);
+      return () => planNuxt(serviceDir, pkg, manifestPath, project);
     }
   }
   if (hasAstroDependency(pkg)) {
     const astroConfig = await findAstroConfig(serviceDir);
     if (astroConfig) {
-      return planAstro(serviceDir, pkg, manifestPath, project);
+      return () => planAstro(serviceDir, pkg, manifestPath, project);
+    }
+  }
+  return null;
+}
+async function plan(serviceDir, opts) {
+  const pkg = await readPackageJson(serviceDir);
+  const manifestPath = import_node_path40.default.join(serviceDir, "package.json");
+  const project = opts?.project;
+  const empty = {
+    language: "javascript",
+    serviceDir,
+    dependencyEdits: [],
+    entrypointEdits: [],
+    envEdits: [],
+    generatedFiles: []
+  };
+  if (!pkg) return empty;
+  const frameworkDispatch = await findFrameworkDispatch(
+    serviceDir,
+    pkg,
+    manifestPath,
+    project
+  );
+  let entryFile = null;
+  if (!frameworkDispatch) {
+    entryFile = await resolveEntry(serviceDir, pkg);
+    if (!entryFile) {
+      return { ...empty, libOnly: true };
     }
   }
+  if (frameworkDispatch) {
+    return frameworkDispatch();
+  }
   const runtimeKind = await detectRuntimeKind(serviceDir, pkg);
   if (runtimeKind !== "node") {
     return { ...empty, runtimeKind };
   }
-  const entryFile = await resolveEntry(serviceDir, pkg);
   if (!entryFile) {
     return { ...empty, libOnly: true };
   }
@@ -7436,6 +7524,16 @@ async function plan(serviceDir, opts) {
       version: sdk.version
     });
   }
+  const nonBundled = detectNonBundledInstrumentations(pkg);
+  for (const inst of nonBundled) {
+    if (inst.pkg in existingDeps) continue;
+    dependencyEdits.push({
+      file: manifestPath,
+      kind: "add",
+      name: inst.pkg,
+      version: inst.version
+    });
+  }
   const entrypointEdits = [];
   try {
     const raw = await import_node_fs25.promises.readFile(entryFile, "utf8");
@@ -7454,11 +7552,17 @@ async function plan(serviceDir, opts) {
   }
   const svcName = serviceNodeName(pkg, serviceDir);
   const projectName = projectToken(pkg, serviceDir, project);
+  const registrations = nonBundled.map((i) => i.registration);
   const generatedFiles = [];
   if (!await exists2(otelInitFile)) {
     generatedFiles.push({
       file: otelInitFile,
-      contents: renderNodeOtelInit(otelInitContents(flavor), svcName, projectName),
+      contents: renderNodeOtelInit(
+        otelInitContents(flavor),
+        svcName,
+        projectName,
+        registrations
+      ),
       skipIfExists: true
     });
   }
@@ -7991,18 +8095,100 @@ function renderPatch(sections) {
 
 // src/orchestrator.ts
 init_cjs_shims();
-var import_node_fs27 = require("fs");
+var import_node_fs28 = require("fs");
 var import_node_http = __toESM(require("http"), 1);
+var import_node_net = __toESM(require("net"), 1);
+var import_node_path43 = __toESM(require("path"), 1);
+var import_node_child_process3 = require("child_process");
+var import_node_readline = __toESM(require("readline"), 1);
+
+// src/installers/package-manager.ts
+init_cjs_shims();
+var import_node_fs27 = require("fs");
 var import_node_path42 = __toESM(require("path"), 1);
 var import_node_child_process2 = require("child_process");
-var import_node_readline = __toESM(require("readline"), 1);
+var LOCKFILE_PRIORITY = [
+  { lockfile: "bun.lockb", pm: "bun", args: ["install", "--no-summary"] },
+  { lockfile: "pnpm-lock.yaml", pm: "pnpm", args: ["install", "--no-summary"] },
+  { lockfile: "yarn.lock", pm: "yarn", args: ["install", "--silent"] },
+  {
+    lockfile: "package-lock.json",
+    pm: "npm",
+    args: ["install", "--no-audit", "--no-fund", "--prefer-offline"]
+  }
+];
+var NPM_FALLBACK_ARGS = ["install", "--no-audit", "--no-fund", "--prefer-offline"];
+async function exists4(p) {
+  try {
+    await import_node_fs27.promises.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function detectPackageManager(serviceDir) {
+  let dir = import_node_path42.default.resolve(serviceDir);
+  const stops = /* @__PURE__ */ new Set();
+  for (let i = 0; i < 64; i++) {
+    if (stops.has(dir)) break;
+    stops.add(dir);
+    for (const candidate of LOCKFILE_PRIORITY) {
+      const lockPath = import_node_path42.default.join(dir, candidate.lockfile);
+      if (await exists4(lockPath)) {
+        return { pm: candidate.pm, cwd: dir, args: [...candidate.args] };
+      }
+    }
+    const parent = import_node_path42.default.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return { pm: "npm", cwd: import_node_path42.default.resolve(serviceDir), args: [...NPM_FALLBACK_ARGS] };
+}
+async function runPackageManagerInstall(cmd) {
+  return new Promise((resolve) => {
+    const child = (0, import_node_child_process2.spawn)(cmd.pm, cmd.args, {
+      cwd: cmd.cwd,
+      // Inherit PATH + HOME so the user's installed managers resolve.
+      env: process.env,
+      // `false` keeps the parent in control of cleanup if the orchestrator
+      // exits before install finishes. Cross-platform-safe.
+      shell: false,
+      stdio: ["ignore", "ignore", "pipe"]
+    });
+    let stderr = "";
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString("utf8");
+    });
+    child.on("error", (err) => {
+      resolve({
+        pm: cmd.pm,
+        cwd: cmd.cwd,
+        args: cmd.args,
+        exitCode: 127,
+        stderr: stderr + `
+${err.message}`
+      });
+    });
+    child.on("close", (code) => {
+      resolve({
+        pm: cmd.pm,
+        cwd: cmd.cwd,
+        args: cmd.args,
+        exitCode: code ?? 1,
+        stderr: stderr.trim()
+      });
+    });
+  });
+}
+
+// src/orchestrator.ts
 async function extractAndPersist(opts) {
   const services = await discoverServices(opts.scanPath);
   const languages = [...new Set(services.map((s) => s.node.language))].sort();
   const graphKey = opts.projectExplicit ? opts.project : DEFAULT_PROJECT;
   resetGraph(graphKey);
   const graph = getGraph(graphKey);
-  const projectPaths = pathsForProject(graphKey, import_node_path42.default.join(opts.scanPath, "neat-out"));
+  const projectPaths = pathsForProject(graphKey, import_node_path43.default.join(opts.scanPath, "neat-out"));
   const extraction = await extractFromDirectory(graph, opts.scanPath, {
     errorsPath: projectPaths.errorsPath
   });
@@ -8020,12 +8206,15 @@ async function extractAndPersist(opts) {
     errorsPath: projectPaths.errorsPath
   };
 }
-async function applyInstallersOver(services, project) {
+async function applyInstallersOver(services, project, options = {}) {
+  const resolveManager = options.resolveManager ?? detectPackageManager;
+  const runInstall = options.runInstall ?? runPackageManagerInstall;
   let instrumented = 0;
   let already = 0;
   let libOnly = 0;
   let browserBundle = 0;
   let reactNative = 0;
+  const installPlans = /* @__PURE__ */ new Map();
   for (const svc of services) {
     const installer = await pickInstaller(svc.dir);
     if (!installer) continue;
@@ -8035,8 +8224,14 @@ async function applyInstallersOver(services, project) {
       continue;
     }
     const outcome = await installer.apply(plan3);
-    if (outcome.outcome === "instrumented") instrumented++;
-    else if (outcome.outcome === "already-instrumented") already++;
+    if (outcome.outcome === "instrumented") {
+      instrumented++;
+      if (plan3.dependencyEdits.length > 0) {
+        const cmd = await resolveManager(svc.dir);
+        const key = `${cmd.pm}:${cmd.cwd}`;
+        if (!installPlans.has(key)) installPlans.set(key, cmd);
+      }
+    } else if (outcome.outcome === "already-instrumented") already++;
     else if (outcome.outcome === "lib-only") libOnly++;
     else if (outcome.outcome === "browser-bundle") {
       browserBundle++;
@@ -8046,7 +8241,30 @@ async function applyInstallersOver(services, project) {
       console.log(`skipping ${svc.dir}: React Native target; browser-OTel support lands in a future release.`);
     }
   }
-  return { instrumented, alreadyInstrumented: already, libOnly, browserBundle, reactNative };
+  const packageManagerInstalls = [];
+  for (const cmd of installPlans.values()) {
+    console.log(`running \`${cmd.pm} ${cmd.args.join(" ")}\` in ${cmd.cwd}`);
+    const result = await runInstall(cmd);
+    packageManagerInstalls.push(result);
+    if (result.exitCode !== 0) {
+      console.error(
+        `neat: ${cmd.pm} install failed in ${cmd.cwd} (exit ${result.exitCode}); run it manually to surface the error.`
+      );
+      if (result.stderr.length > 0) {
+        for (const line of result.stderr.split(/\r?\n/).slice(0, 20)) {
+          console.error(`  ${line}`);
+        }
+      }
+    }
+  }
+  return {
+    instrumented,
+    alreadyInstrumented: already,
+    libOnly,
+    browserBundle,
+    reactNative,
+    packageManagerInstalls
+  };
 }
 async function promptYesNo(question) {
   const rl = import_node_readline.default.createInterface({ input: process.stdin, output: process.stdout });
@@ -8159,11 +8377,33 @@ async function waitForDaemonReady(restPort, timeoutMs) {
     stillBootstrapping: projects.filter((p) => p.status === "bootstrapping").map((p) => p.name)
   };
 }
+var NEAT_PORTS = [8080, 4318, 6328];
+async function isPortFree(port) {
+  return new Promise((resolve) => {
+    const server = import_node_net.default.createServer();
+    server.once("error", () => resolve(false));
+    server.once("listening", () => server.close(() => resolve(true)));
+    server.listen(port, "127.0.0.1");
+  });
+}
+async function probePortsFree() {
+  for (const port of NEAT_PORTS) {
+    if (!await isPortFree(port)) return { free: false, held: port };
+  }
+  return { free: true };
+}
+function formatPortCollisionMessage(port) {
+  return [
+    `neat: port ${port} is in use; the NEAT daemon needs it.`,
+    `      run \`neatd stop\` to release the previous daemon, or`,
+    `      \`lsof -i :${port}\` to find the holding process.`
+  ];
+}
 function spawnDaemonDetached() {
-  const here = import_node_path42.default.dirname(new URL(importMetaUrl).pathname);
+  const here = import_node_path43.default.dirname(new URL(importMetaUrl).pathname);
   const candidates = [
-    import_node_path42.default.join(here, "neatd.cjs"),
-    import_node_path42.default.join(here, "neatd.js")
+    import_node_path43.default.join(here, "neatd.cjs"),
+    import_node_path43.default.join(here, "neatd.js")
   ];
   let entry2 = null;
   const fsSync = require("fs");
@@ -8183,7 +8423,7 @@ function spawnDaemonDetached() {
   if (!hasToken && (!env.HOST || env.HOST.length === 0)) {
     env.HOST = "127.0.0.1";
   }
-  const child = (0, import_node_child_process2.spawn)(process.execPath, [entry2, "start"], {
+  const child = (0, import_node_child_process3.spawn)(process.execPath, [entry2, "start"], {
     detached: true,
     // stderr inherits the orchestrator's fd so the daemon's
     // `BindAuthorityError` message lands in front of the operator instead
@@ -8200,7 +8440,7 @@ function openBrowser(url) {
   const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
   const args = platform === "win32" ? ["/c", "start", "", url] : [url];
   try {
-    const child = (0, import_node_child_process2.spawn)(cmd, args, { detached: true, stdio: "ignore" });
+    const child = (0, import_node_child_process3.spawn)(cmd, args, { detached: true, stdio: "ignore" });
     child.on("error", () => {
     });
     child.unref();
@@ -8221,7 +8461,7 @@ async function runOrchestrator(opts) {
       browser: "skipped"
     }
   };
-  const stat = await import_node_fs27.promises.stat(opts.scanPath).catch(() => null);
+  const stat = await import_node_fs28.promises.stat(opts.scanPath).catch(() => null);
   if (!stat || !stat.isDirectory()) {
     console.error(`neat: ${opts.scanPath} is not a directory`);
     result.exitCode = 2;
@@ -8289,12 +8529,24 @@ async function runOrchestrator(opts) {
     console.log(
       `instrumented ${tally.instrumented}, already ${tally.alreadyInstrumented}, lib-only ${tally.libOnly}`
     );
+    const failedInstalls = tally.packageManagerInstalls.filter((i) => i.exitCode !== 0);
+    if (failedInstalls.length > 0) {
+      result.exitCode = 1;
+    }
   }
   const restPort = Number(process.env.PORT ?? 8080);
   const timeoutMs = opts.daemonReadyTimeoutMs ?? DEFAULT_DAEMON_READY_TIMEOUT_MS;
   if (await checkDaemonHealth(restPort)) {
     result.steps.daemon = "already-running";
   } else {
+    const probe = await probePortsFree();
+    if (!probe.free) {
+      for (const line of formatPortCollisionMessage(probe.held)) {
+        console.error(line);
+      }
+      result.exitCode = 3;
+      return result;
+    }
     try {
       spawnDaemonDetached();
     } catch (err) {
@@ -8352,7 +8604,7 @@ function printSummary(result, graph, dashboardUrl) {
 
 // src/cli-verbs.ts
 init_cjs_shims();
-var import_node_path43 = __toESM(require("path"), 1);
+var import_node_path44 = __toESM(require("path"), 1);
 
 // src/cli-client.ts
 init_cjs_shims();
@@ -8377,10 +8629,10 @@ function createHttpClient(baseUrl, bearerToken) {
   const root = baseUrl.replace(/\/$/, "");
   const authHeader = bearerToken && bearerToken.length > 0 ? { authorization: `Bearer ${bearerToken}` } : {};
   return {
-    async get(path45) {
+    async get(path46) {
       let res;
       try {
-        res = await fetch(`${root}${path45}`, {
+        res = await fetch(`${root}${path46}`, {
           headers: { ...authHeader }
         });
       } catch (err) {
@@ -8392,16 +8644,16 @@ function createHttpClient(baseUrl, bearerToken) {
         const body = await res.text().catch(() => "");
         throw new HttpError(
           res.status,
-          `${res.status} ${res.statusText} on GET ${path45}: ${body}`,
+          `${res.status} ${res.statusText} on GET ${path46}: ${body}`,
           body
         );
       }
       return await res.json();
     },
-    async post(path45, body) {
+    async post(path46, body) {
       let res;
       try {
-        res = await fetch(`${root}${path45}`, {
+        res = await fetch(`${root}${path46}`, {
           method: "POST",
           headers: { "content-type": "application/json", ...authHeader },
           body: JSON.stringify(body)
@@ -8415,7 +8667,7 @@ function createHttpClient(baseUrl, bearerToken) {
         const text = await res.text().catch(() => "");
         throw new HttpError(
           res.status,
-          `${res.status} ${res.statusText} on POST ${path45}: ${text}`,
+          `${res.status} ${res.statusText} on POST ${path46}: ${text}`,
           text
         );
       }
@@ -8429,12 +8681,12 @@ function projectPath(project, suffix) {
 }
 async function runRootCause(client, input) {
   const qs = input.errorId ? `?errorId=${encodeURIComponent(input.errorId)}` : "";
-  const path45 = projectPath(
+  const path46 = projectPath(
     input.project,
     `/graph/root-cause/${encodeURIComponent(input.errorNode)}${qs}`
   );
   try {
-    const result = await client.get(path45);
+    const result = await client.get(path46);
     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}.` : "");
@@ -8460,12 +8712,12 @@ async function runRootCause(client, input) {
 }
 async function runBlastRadius(client, input) {
   const qs = input.depth !== void 0 ? `?depth=${input.depth}` : "";
-  const path45 = projectPath(
+  const path46 = projectPath(
     input.project,
     `/graph/blast-radius/${encodeURIComponent(input.nodeId)}${qs}`
   );
   try {
-    const result = await client.get(path45);
+    const result = await client.get(path46);
     if (result.totalAffected === 0) {
       return {
         summary: `${result.origin} has no downstream dependencies. Nothing else would break if it failed.`
@@ -8499,12 +8751,12 @@ function formatBlastEntry(n) {
 }
 async function runDependencies(client, input) {
   const depth = input.depth ?? 3;
-  const path45 = projectPath(
+  const path46 = projectPath(
     input.project,
     `/graph/dependencies/${encodeURIComponent(input.nodeId)}?depth=${depth}`
   );
   try {
-    const result = await client.get(path45);
+    const result = await client.get(path46);
     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}).`
@@ -8585,9 +8837,9 @@ function formatDuration(ms) {
   return `${Math.round(h / 24)}d`;
 }
 async function runIncidents(client, input) {
-  const path45 = input.nodeId ? projectPath(input.project, `/incidents/${encodeURIComponent(input.nodeId)}`) : projectPath(input.project, "/incidents");
+  const path46 = input.nodeId ? projectPath(input.project, `/incidents/${encodeURIComponent(input.nodeId)}`) : projectPath(input.project, "/incidents");
   try {
-    const body = await client.get(path45);
+    const body = await client.get(path46);
     const events = body.events;
     if (events.length === 0) {
       return {
@@ -8877,7 +9129,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}${import_node_path43.default.sep}`)) {
+    if (resolvedCwd === entry2.path || resolvedCwd.startsWith(`${entry2.path}${import_node_path44.default.sep}`)) {
       return entry2;
     }
   }
@@ -9102,7 +9354,8 @@ function usage() {
   console.log("  0  success");
   console.log("  1  server error (4xx/5xx body printed to stderr)");
   console.log("  2  misuse (missing args, bad flags) \u2014 handled before any network call");
-  console.log("  3  daemon not reachable (connection refused / timeout)");
+  console.log("  3  environmental \u2014 daemon unreachable, or one of ports 8080 / 4318 / 6328");
+  console.log("     is held by another process when `neat <path>` tries to spawn the daemon");
   console.log("");
   console.log("environment:");
   console.log("  NEAT_API_URL    base URL for the core REST API (default http://localhost:8080)");
@@ -9236,14 +9489,14 @@ function assignFlag(out, field, value) {
   out[field] = value;
 }
 function readPackageVersion() {
-  const here = typeof __dirname !== "undefined" ? __dirname : import_node_path44.default.dirname((0, import_node_url3.fileURLToPath)(importMetaUrl));
+  const here = typeof __dirname !== "undefined" ? __dirname : import_node_path45.default.dirname((0, import_node_url3.fileURLToPath)(importMetaUrl));
   const candidates = [
-    import_node_path44.default.resolve(here, "../package.json"),
-    import_node_path44.default.resolve(here, "../../package.json")
+    import_node_path45.default.resolve(here, "../package.json"),
+    import_node_path45.default.resolve(here, "../../package.json")
   ];
   for (const candidate of candidates) {
     try {
-      const raw = (0, import_node_fs28.readFileSync)(candidate, "utf8");
+      const raw = (0, import_node_fs29.readFileSync)(candidate, "utf8");
       const parsed = JSON.parse(raw);
       if (parsed.name === "@neat.is/core" && typeof parsed.version === "string") {
         return parsed.version;
@@ -9307,7 +9560,7 @@ async function buildPatchSections(services, project) {
 }
 async function runInit(opts) {
   const written = [];
-  const stat = await import_node_fs28.promises.stat(opts.scanPath).catch(() => null);
+  const stat = await import_node_fs29.promises.stat(opts.scanPath).catch(() => null);
   if (!stat || !stat.isDirectory()) {
     console.error(`neat init: ${opts.scanPath} is not a directory`);
     return { exitCode: 2, writtenFiles: written };
@@ -9316,13 +9569,13 @@ async function runInit(opts) {
   printDiscoveryReport(opts, services);
   const sections = opts.noInstall ? [] : await buildPatchSections(services, opts.project);
   const patch = renderPatch(sections);
-  const patchPath = import_node_path44.default.join(opts.scanPath, "neat.patch");
+  const patchPath = import_node_path45.default.join(opts.scanPath, "neat.patch");
   if (opts.dryRun) {
-    await import_node_fs28.promises.writeFile(patchPath, patch, "utf8");
+    await import_node_fs29.promises.writeFile(patchPath, patch, "utf8");
     written.push(patchPath);
     console.log(`dry-run: patch written to ${patchPath}`);
-    const gitignorePath = import_node_path44.default.join(opts.scanPath, ".gitignore");
-    const gitignoreExists = await import_node_fs28.promises.stat(gitignorePath).then(() => true).catch(() => false);
+    const gitignorePath = import_node_path45.default.join(opts.scanPath, ".gitignore");
+    const gitignoreExists = await import_node_fs29.promises.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.");
@@ -9333,9 +9586,9 @@ async function runInit(opts) {
   const graph = getGraph(graphKey);
   const projectPaths = pathsForProject(
     graphKey,
-    import_node_path44.default.join(opts.scanPath, "neat-out")
+    import_node_path45.default.join(opts.scanPath, "neat-out")
   );
-  const errorsPath = import_node_path44.default.join(import_node_path44.default.dirname(opts.outPath), import_node_path44.default.basename(projectPaths.errorsPath));
+  const errorsPath = import_node_path45.default.join(import_node_path45.default.dirname(opts.outPath), import_node_path45.default.basename(projectPaths.errorsPath));
   const result = await extractFromDirectory(graph, opts.scanPath, { errorsPath });
   await saveGraphToDisk(graph, opts.outPath);
   written.push(opts.outPath);
@@ -9414,7 +9667,7 @@ async function runInit(opts) {
         console.log("Run `npm install` (or your language equivalent) to refresh lockfiles.");
       }
     } else {
-      await import_node_fs28.promises.writeFile(patchPath, patch, "utf8");
+      await import_node_fs29.promises.writeFile(patchPath, patch, "utf8");
       written.push(patchPath);
     }
   }
@@ -9454,9 +9707,9 @@ var CLAUDE_SKILL_CONFIG = {
 };
 function claudeConfigPath() {
   const override = process.env.NEAT_CLAUDE_CONFIG;
-  if (override && override.length > 0) return import_node_path44.default.resolve(override);
+  if (override && override.length > 0) return import_node_path45.default.resolve(override);
   const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
-  return import_node_path44.default.join(home, ".claude.json");
+  return import_node_path45.default.join(home, ".claude.json");
 }
 async function runSkill(opts) {
   const snippet2 = JSON.stringify(CLAUDE_SKILL_CONFIG, null, 2) + "\n";
@@ -9468,7 +9721,7 @@ async function runSkill(opts) {
     const target = claudeConfigPath();
     let existing = {};
     try {
-      existing = JSON.parse(await import_node_fs28.promises.readFile(target, "utf8"));
+      existing = JSON.parse(await import_node_fs29.promises.readFile(target, "utf8"));
     } catch (err) {
       if (err.code !== "ENOENT") {
         console.error(`neat skill: failed to read ${target} \u2014 ${err.message}`);
@@ -9480,8 +9733,8 @@ async function runSkill(opts) {
       ...existing,
       mcpServers: { ...mcp, neat: CLAUDE_SKILL_CONFIG.mcpServers.neat }
     };
-    await import_node_fs28.promises.mkdir(import_node_path44.default.dirname(target), { recursive: true });
-    await import_node_fs28.promises.writeFile(target, JSON.stringify(merged, null, 2) + "\n", "utf8");
+    await import_node_fs29.promises.mkdir(import_node_path45.default.dirname(target), { recursive: true });
+    await import_node_fs29.promises.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.");
     return { exitCode: 0 };
@@ -9519,12 +9772,12 @@ async function main() {
       console.error("neat init: --apply and --dry-run are mutually exclusive");
       process.exit(2);
     }
-    const scanPath = import_node_path44.default.resolve(target);
+    const scanPath = import_node_path45.default.resolve(target);
     const projectExplicit = parsed.project !== null;
-    const projectName = projectExplicit ? project : import_node_path44.default.basename(scanPath);
+    const projectName = projectExplicit ? project : import_node_path45.default.basename(scanPath);
     const projectKey = projectExplicit ? project : DEFAULT_PROJECT;
-    const fallback = pathsForProject(projectKey, import_node_path44.default.join(scanPath, "neat-out")).snapshotPath;
-    const outPath = import_node_path44.default.resolve(process.env.NEAT_OUT_PATH ?? fallback);
+    const fallback = pathsForProject(projectKey, import_node_path45.default.join(scanPath, "neat-out")).snapshotPath;
+    const outPath = import_node_path45.default.resolve(process.env.NEAT_OUT_PATH ?? fallback);
     const result = await runInit({
       scanPath,
       outPath,
@@ -9545,21 +9798,21 @@ async function main() {
       usage();
       process.exit(2);
     }
-    const scanPath = import_node_path44.default.resolve(target);
-    const stat = await import_node_fs28.promises.stat(scanPath).catch(() => null);
+    const scanPath = import_node_path45.default.resolve(target);
+    const stat = await import_node_fs29.promises.stat(scanPath).catch(() => null);
     if (!stat || !stat.isDirectory()) {
       console.error(`neat watch: ${scanPath} is not a directory`);
       process.exit(2);
     }
-    const projectPaths = pathsForProject(project, import_node_path44.default.join(scanPath, "neat-out"));
-    const outPath = import_node_path44.default.resolve(process.env.NEAT_OUT_PATH ?? projectPaths.snapshotPath);
-    const errorsPath = import_node_path44.default.resolve(
-      process.env.NEAT_ERRORS_PATH ?? import_node_path44.default.join(import_node_path44.default.dirname(outPath), import_node_path44.default.basename(projectPaths.errorsPath))
+    const projectPaths = pathsForProject(project, import_node_path45.default.join(scanPath, "neat-out"));
+    const outPath = import_node_path45.default.resolve(process.env.NEAT_OUT_PATH ?? projectPaths.snapshotPath);
+    const errorsPath = import_node_path45.default.resolve(
+      process.env.NEAT_ERRORS_PATH ?? import_node_path45.default.join(import_node_path45.default.dirname(outPath), import_node_path45.default.basename(projectPaths.errorsPath))
     );
-    const staleEventsPath = import_node_path44.default.resolve(
-      process.env.NEAT_STALE_EVENTS_PATH ?? import_node_path44.default.join(import_node_path44.default.dirname(outPath), import_node_path44.default.basename(projectPaths.staleEventsPath))
+    const staleEventsPath = import_node_path45.default.resolve(
+      process.env.NEAT_STALE_EVENTS_PATH ?? import_node_path45.default.join(import_node_path45.default.dirname(outPath), import_node_path45.default.basename(projectPaths.staleEventsPath))
     );
-    const embeddingsCachePath = process.env.NEAT_EMBEDDINGS_CACHE_PATH ? import_node_path44.default.resolve(process.env.NEAT_EMBEDDINGS_CACHE_PATH) : void 0;
+    const embeddingsCachePath = process.env.NEAT_EMBEDDINGS_CACHE_PATH ? import_node_path45.default.resolve(process.env.NEAT_EMBEDDINGS_CACHE_PATH) : void 0;
     const handle = await startWatch(getGraph(project), {
       scanPath,
       outPath,
@@ -9705,11 +9958,11 @@ async function main() {
   process.exit(1);
 }
 async function tryOrchestrator(cmd, parsed) {
-  const scanPath = import_node_path44.default.resolve(cmd);
-  const stat = await import_node_fs28.promises.stat(scanPath).catch(() => null);
+  const scanPath = import_node_path45.default.resolve(cmd);
+  const stat = await import_node_fs29.promises.stat(scanPath).catch(() => null);
   if (!stat || !stat.isDirectory()) return null;
   const projectExplicit = parsed.project !== null;
-  const projectName = projectExplicit ? parsed.project : import_node_path44.default.basename(scanPath);
+  const projectName = projectExplicit ? parsed.project : import_node_path45.default.basename(scanPath);
   const result = await runOrchestrator({
     scanPath,
     project: projectName,