@neat.is/core 0.4.0 → 0.4.3

package/dist/cli.cjs

@@ -480,6 +480,7 @@ __export(cli_exports, {
   CLAUDE_SKILL_CONFIG: () => CLAUDE_SKILL_CONFIG,
   QUERY_VERBS: () => QUERY_VERBS,
   parseArgs: () => parseArgs,
+  readPackageVersion: () => readPackageVersion,
   runInit: () => runInit,
   runQueryVerb: () => runQueryVerb,
   runSkill: () => runSkill
@@ -488,6 +489,7 @@ 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_url3 = require("url");
 
 // src/graph.ts
 init_cjs_shims();
@@ -2093,8 +2095,36 @@ var IGNORED_DIRS = /* @__PURE__ */ new Set([
   ".turbo",
   "dist",
   "build",
-  ".next"
+  ".next",
+  // Python virtualenv shapes (issue #344). Walking into a venv pulls in the
+  // entire CPython stdlib + every installed package as if it were first-party
+  // service code — 20k+ files, none of which the user wrote. The shape names
+  // cover the three common venv tools (`venv` / `python -m venv`,
+  // `virtualenv`) and the tox + PEP 582 conventions.
+  ".venv",
+  "venv",
+  "__pypackages__",
+  ".tox",
+  // `site-packages` shows up nested inside venvs that don't carry one of the
+  // outer names (system Python on macOS, in-place pyenv layouts). Listing it
+  // here means we stop the walk at the boundary even when the wrapper dir
+  // wasn't recognisable.
+  "site-packages"
 ]);
+var PYVENV_MARKER_CACHE = /* @__PURE__ */ new Map();
+async function isPythonVenvDir(dir) {
+  const cached = PYVENV_MARKER_CACHE.get(dir);
+  if (cached !== void 0) return cached;
+  try {
+    const stat = await import_node_fs4.promises.stat(import_node_path4.default.join(dir, "pyvenv.cfg"));
+    const ok = stat.isFile();
+    PYVENV_MARKER_CACHE.set(dir, ok);
+    return ok;
+  } catch {
+    PYVENV_MARKER_CACHE.set(dir, false);
+    return false;
+  }
+}
 function isConfigFile(name) {
   const ext = import_node_path4.default.extname(name);
   if (CONFIG_FILE_EXTENSIONS.has(ext)) return { match: true, fileType: ext.slice(1) };
@@ -2443,6 +2473,7 @@ async function walkDirs(start, scanPath, options, visit) {
         const rel = import_node_path8.default.relative(scanPath, child).split(import_node_path8.default.sep).join("/");
         if (rel && options.ig.ignores(rel + "/")) continue;
       }
+      if (await isPythonVenvDir(child)) continue;
       await visit(child);
       await recurse(child, depth + 1);
     }
@@ -2721,7 +2752,9 @@ async function walkYamlFiles(start, depth = 0, max = 5) {
   for (const entry2 of entries) {
     if (entry2.isDirectory()) {
       if (IGNORED_DIRS.has(entry2.name)) continue;
-      out.push(...await walkYamlFiles(import_node_path9.default.join(start, entry2.name), depth + 1, max));
+      const child = import_node_path9.default.join(start, entry2.name);
+      if (await isPythonVenvDir(child)) continue;
+      out.push(...await walkYamlFiles(child, depth + 1, max));
     } else if (entry2.isFile() && CONFIG_FILE_EXTENSIONS.has(import_node_path9.default.extname(entry2.name))) {
       out.push(import_node_path9.default.join(start, entry2.name));
     }
@@ -3403,7 +3436,9 @@ async function walkConfigFiles(dir) {
     for (const entry2 of entries) {
       const full = import_node_path18.default.join(current, entry2.name);
       if (entry2.isDirectory()) {
-        if (!IGNORED_DIRS.has(entry2.name)) await walk(full);
+        if (IGNORED_DIRS.has(entry2.name)) continue;
+        if (await isPythonVenvDir(full)) continue;
+        await walk(full);
       } else if (entry2.isFile() && isConfigFile(entry2.name).match) {
         out.push(full);
       }
@@ -3471,7 +3506,9 @@ async function walkSourceFiles(dir) {
     for (const entry2 of entries) {
       const full = import_node_path19.default.join(current, entry2.name);
       if (entry2.isDirectory()) {
-        if (!IGNORED_DIRS.has(entry2.name)) await walk(full);
+        if (IGNORED_DIRS.has(entry2.name)) continue;
+        if (await isPythonVenvDir(full)) continue;
+        await walk(full);
       } else if (entry2.isFile() && SERVICE_FILE_EXTENSIONS.has(import_node_path19.default.extname(entry2.name))) {
         out.push(full);
       }
@@ -4107,7 +4144,9 @@ async function walkTfFiles(start, depth = 0, max = 5) {
   for (const entry2 of entries) {
     if (entry2.isDirectory()) {
       if (IGNORED_DIRS.has(entry2.name) || entry2.name === ".terraform") continue;
-      out.push(...await walkTfFiles(import_node_path27.default.join(start, entry2.name), depth + 1, max));
+      const child = import_node_path27.default.join(start, entry2.name);
+      if (await isPythonVenvDir(child)) continue;
+      out.push(...await walkTfFiles(child, depth + 1, max));
     } else if (entry2.isFile() && entry2.name.endsWith(".tf")) {
       out.push(import_node_path27.default.join(start, entry2.name));
     }
@@ -4155,7 +4194,9 @@ async function walkYamlFiles2(start, depth = 0, max = 5) {
   for (const entry2 of entries) {
     if (entry2.isDirectory()) {
       if (IGNORED_DIRS.has(entry2.name)) continue;
-      out.push(...await walkYamlFiles2(import_node_path28.default.join(start, entry2.name), depth + 1, max));
+      const child = import_node_path28.default.join(start, entry2.name);
+      if (await isPythonVenvDir(child)) continue;
+      out.push(...await walkYamlFiles2(child, depth + 1, max));
     } else if (entry2.isFile() && CONFIG_FILE_EXTENSIONS.has(import_node_path28.default.extname(entry2.name))) {
       out.push(import_node_path28.default.join(start, entry2.name));
     }
@@ -5155,10 +5196,19 @@ function projectFromReq(req) {
   const params = req.params;
   return params.project ?? DEFAULT_PROJECT;
 }
-function resolveProject(registry, req, reply) {
+function resolveProject(registry, req, reply, bootstrap) {
   const name = projectFromReq(req);
   const ctx = registry.get(name);
   if (!ctx) {
+    const phase = bootstrap?.status(name);
+    if (phase === "bootstrapping") {
+      void reply.code(503).send({ ready: false, project: name, status: "bootstrapping" });
+      return null;
+    }
+    if (phase === "broken") {
+      void reply.code(503).send({ ready: false, project: name, status: "broken" });
+      return null;
+    }
     void reply.code(404).send({ error: "project not found", project: name });
     return null;
   }
@@ -5188,36 +5238,38 @@ function buildLegacyRegistry(opts) {
 function registerRoutes(scope, ctx) {
   const { registry, startedAt, errorsPathFor, staleEventsPathFor } = ctx;
   scope.get("/events", (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     handleSse(req, reply, { project: proj.name });
   });
-  scope.get("/health", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
-    if (!proj) return;
-    const uptimeMs = Date.now() - startedAt;
-    return {
-      ok: true,
-      project: proj.name,
-      uptimeMs,
-      // Legacy fields kept additively. The web shell's StatusBar reads
-      // nodeCount / edgeCount; ADR-061's HealthResponseSchema validates
-      // the canonical triple and lets the extras pass through.
-      uptime: Math.floor(uptimeMs / 1e3),
-      nodeCount: proj.graph.order,
-      edgeCount: proj.graph.size,
-      lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
-    };
-  });
+  if (ctx.scope === "project") {
+    scope.get("/health", async (req, reply) => {
+      const proj = resolveProject(registry, req, reply, ctx.bootstrap);
+      if (!proj) return;
+      const uptimeMs = Date.now() - startedAt;
+      return {
+        ok: true,
+        project: proj.name,
+        uptimeMs,
+        // Legacy fields kept additively. The web shell's StatusBar reads
+        // nodeCount / edgeCount; ADR-061's HealthResponseSchema validates
+        // the canonical triple and lets the extras pass through.
+        uptime: Math.floor(uptimeMs / 1e3),
+        nodeCount: proj.graph.order,
+        edgeCount: proj.graph.size,
+        lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+      };
+    });
+  }
   scope.get("/graph", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     return serializeGraph(proj.graph);
   });
   scope.get(
     "/graph/node/:id",
     async (req, reply) => {
-      const proj = resolveProject(registry, req, reply);
+      const proj = resolveProject(registry, req, reply, ctx.bootstrap);
       if (!proj) return;
       const { id } = req.params;
       if (!proj.graph.hasNode(id)) {
@@ -5229,7 +5281,7 @@ function registerRoutes(scope, ctx) {
   scope.get(
     "/graph/edges/:id",
     async (req, reply) => {
-      const proj = resolveProject(registry, req, reply);
+      const proj = resolveProject(registry, req, reply, ctx.bootstrap);
       if (!proj) return;
       const { id } = req.params;
       if (!proj.graph.hasNode(id)) {
@@ -5241,7 +5293,7 @@ function registerRoutes(scope, ctx) {
     }
   );
   scope.get("/graph/dependencies/:nodeId", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     const { nodeId } = req.params;
     if (!proj.graph.hasNode(nodeId)) {
@@ -5256,7 +5308,7 @@ function registerRoutes(scope, ctx) {
     return getTransitiveDependencies(proj.graph, nodeId, depth);
   });
   scope.get("/graph/divergences", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     let typeFilter;
     if (req.query.type) {
@@ -5291,7 +5343,7 @@ function registerRoutes(scope, ctx) {
     });
   });
   scope.get("/incidents", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     const epath = errorsPathFor(proj);
     if (!epath) return { count: 0, total: 0, events: [] };
@@ -5303,7 +5355,7 @@ function registerRoutes(scope, ctx) {
     return { count: sliced.length, total, events: sliced };
   });
   scope.get("/stale-events", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     const spath = staleEventsPathFor(proj);
     if (!spath) return { count: 0, total: 0, events: [] };
@@ -5318,7 +5370,7 @@ function registerRoutes(scope, ctx) {
   scope.get(
     "/incidents/:nodeId",
     async (req, reply) => {
-      const proj = resolveProject(registry, req, reply);
+      const proj = resolveProject(registry, req, reply, ctx.bootstrap);
       if (!proj) return;
       const { nodeId } = req.params;
       if (!proj.graph.hasNode(nodeId)) {
@@ -5334,7 +5386,7 @@ function registerRoutes(scope, ctx) {
     }
   );
   scope.get("/graph/root-cause/:nodeId", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     const { nodeId } = req.params;
     if (!proj.graph.hasNode(nodeId)) {
@@ -5354,7 +5406,7 @@ function registerRoutes(scope, ctx) {
     return result;
   });
   scope.get("/graph/blast-radius/:nodeId", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     const { nodeId } = req.params;
     if (!proj.graph.hasNode(nodeId)) {
@@ -5367,7 +5419,7 @@ function registerRoutes(scope, ctx) {
     return getBlastRadius(proj.graph, nodeId, depth);
   });
   scope.get("/search", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     const raw = (req.query.q ?? "").trim();
     if (!raw) return reply.code(400).send({ error: "query parameter `q` is required" });
@@ -5398,7 +5450,7 @@ function registerRoutes(scope, ctx) {
   scope.get(
     "/graph/diff",
     async (req, reply) => {
-      const proj = resolveProject(registry, req, reply);
+      const proj = resolveProject(registry, req, reply, ctx.bootstrap);
       if (!proj) return;
       const against = req.query.against;
       if (!against) {
@@ -5413,7 +5465,7 @@ function registerRoutes(scope, ctx) {
     }
   );
   scope.post("/snapshot", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     const body = req.body;
     if (!body || typeof body !== "object" || !body.snapshot) {
@@ -5442,7 +5494,7 @@ function registerRoutes(scope, ctx) {
     }
   });
   scope.post("/graph/scan", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     if (!proj.scanPath) {
       return reply.code(409).send({ error: "scan path not configured for this project", project: proj.name });
@@ -5458,7 +5510,7 @@ function registerRoutes(scope, ctx) {
     };
   });
   scope.get("/policies", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     const policyPath = ctx.policyFilePathFor(proj);
     if (!policyPath) {
@@ -5475,7 +5527,7 @@ function registerRoutes(scope, ctx) {
     }
   });
   scope.get("/policies/violations", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     const log = new PolicyViolationsLog(proj.paths.policyViolationsPath);
     let violations = await log.readAll();
@@ -5495,7 +5547,7 @@ function registerRoutes(scope, ctx) {
     return { violations };
   });
   scope.post("/policies/check", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     const parsed = import_types23.PoliciesCheckBodySchema.safeParse(req.body ?? {});
     if (!parsed.success) {
@@ -5566,10 +5618,36 @@ async function buildApi(opts) {
   const routeCtx = {
     registry,
     startedAt,
+    scope: "root",
     errorsPathFor,
     staleEventsPathFor,
-    policyFilePathFor
+    policyFilePathFor,
+    bootstrap: opts.bootstrap
   };
+  app.get("/health", async () => {
+    const uptimeMs = Date.now() - startedAt;
+    const bootstrapList = opts.bootstrap?.list() ?? [];
+    const byName = new Map(bootstrapList.map((p) => [p.name, p]));
+    const names = /* @__PURE__ */ new Set([
+      ...registry.list(),
+      ...bootstrapList.map((p) => p.name)
+    ]);
+    const projects = [...names].sort().map((name) => {
+      const proj = registry.get(name);
+      const tracked = byName.get(name);
+      return {
+        name,
+        nodeCount: proj?.graph.order ?? 0,
+        edgeCount: proj?.graph.size ?? 0,
+        ...tracked ? { status: tracked.status, elapsedMs: tracked.elapsedMs } : {}
+      };
+    });
+    return {
+      ok: true,
+      uptimeMs,
+      projects
+    };
+  });
   app.get("/projects", async (_req, reply) => {
     try {
       return await listProjects();
@@ -5597,7 +5675,7 @@ async function buildApi(opts) {
   registerRoutes(app, routeCtx);
   await app.register(
     async (scope) => {
-      registerRoutes(scope, routeCtx);
+      registerRoutes(scope, { ...routeCtx, scope: "project" });
     },
     { prefix: "/projects/:project" }
   );
@@ -5980,6 +6058,14 @@ var IGNORED_WATCH_GLOBS = [
   "**/.turbo/**",
   "**/.next/**",
   "**/neat-out/**",
+  // Python venv shapes (issue #344). chokidar opens one watch handle per
+  // descended dir; a CPython venv carries 20k+ files and trivially blows
+  // through the macOS kqueue cap before extraction even runs.
+  "**/.venv/**",
+  "**/venv/**",
+  "**/__pypackages__/**",
+  "**/.tox/**",
+  "**/site-packages/**",
   "**/.DS_Store"
 ];
 var IGNORED_WATCH_PATHS = [
@@ -5990,6 +6076,11 @@ var IGNORED_WATCH_PATHS = [
   /(?:^|[\\/])\.turbo[\\/]/,
   /(?:^|[\\/])\.next[\\/]/,
   /(?:^|[\\/])neat-out[\\/]/,
+  /(?:^|[\\/])\.venv[\\/]/,
+  /(?:^|[\\/])venv[\\/]/,
+  /(?:^|[\\/])__pypackages__[\\/]/,
+  /(?:^|[\\/])\.tox[\\/]/,
+  /(?:^|[\\/])site-packages[\\/]/,
   /[\\/]?\.DS_Store$/
 ];
 function shouldIgnore(absPath) {
@@ -6427,10 +6518,10 @@ dotenv.config({ path: path.join(here, '.env.neat') })
 
 await import('@opentelemetry/auto-instrumentations-node/register')
 `;
-function renderEnvNeat(serviceName) {
+function renderEnvNeat(projectName) {
   return [
     "# Generated by `neat init --apply` (ADR-069).",
-    `OTEL_SERVICE_NAME=${serviceName}`,
+    `OTEL_SERVICE_NAME=${projectName}`,
     "OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318",
     ""
   ].join("\n");
@@ -6451,41 +6542,26 @@ export async function register() {
 }
 `;
 var NEXT_INSTRUMENTATION_NODE_TS = `${NEXT_INSTRUMENTATION_HEADER}
-// Loads .env.neat (OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT) before
-// the OTel SDK starts so the exporter target and service name are in scope.
-import { fileURLToPath } from 'node:url'
-import path from 'node:path'
-import dotenv from 'dotenv'
+process.env.OTEL_SERVICE_NAME ||= '__PROJECT_NAME__'
+process.env.OTEL_EXPORTER_OTLP_ENDPOINT ||= 'http://localhost:4318'
+
 import { NodeSDK } from '@opentelemetry/sdk-node'
 import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
 
-const here = path.dirname(fileURLToPath(import.meta.url))
-dotenv.config({ path: path.join(here, '.env.neat') })
-
-const sdk = new NodeSDK({
-  serviceName: process.env.OTEL_SERVICE_NAME,
-  instrumentations: [getNodeAutoInstrumentations()],
-})
-sdk.start()
+new NodeSDK({ instrumentations: [getNodeAutoInstrumentations()] }).start()
 `;
 var NEXT_INSTRUMENTATION_NODE_JS = `${NEXT_INSTRUMENTATION_HEADER}
-// Loads .env.neat (OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT) before
-// the OTel SDK starts so the exporter target and service name are in scope.
-import { fileURLToPath } from 'node:url'
-import path from 'node:path'
-import dotenv from 'dotenv'
-import { NodeSDK } from '@opentelemetry/sdk-node'
-import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
+process.env.OTEL_SERVICE_NAME ||= '__PROJECT_NAME__'
+process.env.OTEL_EXPORTER_OTLP_ENDPOINT ||= 'http://localhost:4318'
 
-const here = path.dirname(fileURLToPath(import.meta.url))
-dotenv.config({ path: path.join(here, '.env.neat') })
+const { NodeSDK } = require('@opentelemetry/sdk-node')
+const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node')
 
-const sdk = new NodeSDK({
-  serviceName: process.env.OTEL_SERVICE_NAME,
-  instrumentations: [getNodeAutoInstrumentations()],
-})
-sdk.start()
+new NodeSDK({ instrumentations: [getNodeAutoInstrumentations()] }).start()
 `;
+function renderNextInstrumentationNode(template, projectName) {
+  return template.replace(/__PROJECT_NAME__/g, projectName);
+}
 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}
 // Loads .env.neat (OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT) before
@@ -6600,6 +6676,10 @@ var OTEL_ENV = {
   key: "OTEL_EXPORTER_OTLP_ENDPOINT",
   value: "http://localhost:4318"
 };
+function envServiceName(pkg, serviceDir, project) {
+  if (project && project.length > 0) return project;
+  return pkg.name ?? import_node_path40.default.basename(serviceDir);
+}
 async function readPackageJson(serviceDir) {
   try {
     const raw = await import_node_fs25.promises.readFile(import_node_path40.default.join(serviceDir, "package.json"), "utf8");
@@ -6824,17 +6904,29 @@ function lineIsOtelInjection(line) {
   if (trimmed.length === 0) return false;
   return /(?:require\(|import\s+)['"]\.\/otel-init[^'"]*['"]/.test(trimmed);
 }
-async function planNext(serviceDir, pkg, manifestPath, nextConfigPath) {
+async function detectsSrcLayout(serviceDir) {
+  const [hasSrcApp, hasSrcPages, hasRootApp, hasRootPages] = await Promise.all([
+    exists2(import_node_path40.default.join(serviceDir, "src", "app")),
+    exists2(import_node_path40.default.join(serviceDir, "src", "pages")),
+    exists2(import_node_path40.default.join(serviceDir, "app")),
+    exists2(import_node_path40.default.join(serviceDir, "pages"))
+  ]);
+  return (hasSrcApp || hasSrcPages) && !hasRootApp && !hasRootPages;
+}
+async function planNext(serviceDir, pkg, manifestPath, nextConfigPath, project) {
   const useTs = await isTypeScriptProject(serviceDir);
-  const instrumentationFile = import_node_path40.default.join(serviceDir, useTs ? "instrumentation.ts" : "instrumentation.js");
+  const srcLayout = await detectsSrcLayout(serviceDir);
+  const baseDir = srcLayout ? import_node_path40.default.join(serviceDir, "src") : serviceDir;
+  const instrumentationFile = import_node_path40.default.join(baseDir, useTs ? "instrumentation.ts" : "instrumentation.js");
   const instrumentationNodeFile = import_node_path40.default.join(
-    serviceDir,
+    baseDir,
     useTs ? "instrumentation.node.ts" : "instrumentation.node.js"
   );
-  const envNeatFile = import_node_path40.default.join(serviceDir, ".env.neat");
+  const envNeatFile = import_node_path40.default.join(baseDir, ".env.neat");
   const existingDeps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
   const dependencyEdits = [];
   for (const sdk of SDK_PACKAGES) {
+    if (sdk.name === "dotenv") continue;
     if (sdk.name in existingDeps) continue;
     dependencyEdits.push({
       file: manifestPath,
@@ -6843,6 +6935,7 @@ async function planNext(serviceDir, pkg, manifestPath, nextConfigPath) {
       version: sdk.version
     });
   }
+  const projectName = envServiceName(pkg, serviceDir, project);
   const generatedFiles = [];
   if (!await exists2(instrumentationFile)) {
     generatedFiles.push({
@@ -6854,14 +6947,17 @@ async function planNext(serviceDir, pkg, manifestPath, nextConfigPath) {
   if (!await exists2(instrumentationNodeFile)) {
     generatedFiles.push({
       file: instrumentationNodeFile,
-      contents: useTs ? NEXT_INSTRUMENTATION_NODE_TS : NEXT_INSTRUMENTATION_NODE_JS,
+      contents: renderNextInstrumentationNode(
+        useTs ? NEXT_INSTRUMENTATION_NODE_TS : NEXT_INSTRUMENTATION_NODE_JS,
+        projectName
+      ),
       skipIfExists: true
     });
   }
   if (!await exists2(envNeatFile)) {
     generatedFiles.push({
       file: envNeatFile,
-      contents: renderEnvNeat(pkg.name ?? import_node_path40.default.basename(serviceDir)),
+      contents: renderEnvNeat(projectName),
       skipIfExists: true
     });
   }
@@ -6917,12 +7013,12 @@ function buildDependencyEdits(pkg, manifestPath) {
   }
   return edits;
 }
-async function queueEnvNeat(serviceDir, pkg, generatedFiles) {
+async function queueEnvNeat(serviceDir, pkg, project, generatedFiles) {
   const envNeatFile = import_node_path40.default.join(serviceDir, ".env.neat");
   if (!await exists2(envNeatFile)) {
     generatedFiles.push({
       file: envNeatFile,
-      contents: renderEnvNeat(pkg.name ?? import_node_path40.default.basename(serviceDir)),
+      contents: renderEnvNeat(envServiceName(pkg, serviceDir, project)),
       skipIfExists: true
     });
   }
@@ -6941,7 +7037,7 @@ function fileImportsOtelHook(raw, specifiers) {
   }
   return false;
 }
-async function planRemix(serviceDir, pkg, manifestPath, entryFile) {
+async function planRemix(serviceDir, pkg, manifestPath, entryFile, project) {
   const useTs = await isTypeScriptProject(serviceDir);
   const otelServerFile = import_node_path40.default.join(
     serviceDir,
@@ -6956,7 +7052,7 @@ async function planRemix(serviceDir, pkg, manifestPath, entryFile) {
       skipIfExists: true
     });
   }
-  await queueEnvNeat(serviceDir, pkg, generatedFiles);
+  await queueEnvNeat(serviceDir, pkg, project, generatedFiles);
   const entrypointEdits = [];
   try {
     const raw = await import_node_fs25.promises.readFile(entryFile, "utf8");
@@ -6993,7 +7089,7 @@ async function planRemix(serviceDir, pkg, manifestPath, entryFile) {
     framework: "remix"
   };
 }
-async function planSvelteKit(serviceDir, pkg, manifestPath, hooksFile) {
+async function planSvelteKit(serviceDir, pkg, manifestPath, hooksFile, project) {
   const useTs = await isTypeScriptProject(serviceDir);
   const otelInitFile = import_node_path40.default.join(
     serviceDir,
@@ -7010,7 +7106,7 @@ async function planSvelteKit(serviceDir, pkg, manifestPath, hooksFile) {
       skipIfExists: true
     });
   }
-  await queueEnvNeat(serviceDir, pkg, generatedFiles);
+  await queueEnvNeat(serviceDir, pkg, project, generatedFiles);
   if (hooksFile === null) {
     generatedFiles.push({
       file: resolvedHooksFile,
@@ -7054,7 +7150,7 @@ async function planSvelteKit(serviceDir, pkg, manifestPath, hooksFile) {
     framework: "sveltekit"
   };
 }
-async function planNuxt(serviceDir, pkg, manifestPath) {
+async function planNuxt(serviceDir, pkg, manifestPath, project) {
   const useTs = await isTypeScriptProject(serviceDir);
   const otelPluginFile = import_node_path40.default.join(
     serviceDir,
@@ -7080,7 +7176,7 @@ async function planNuxt(serviceDir, pkg, manifestPath) {
       skipIfExists: true
     });
   }
-  await queueEnvNeat(serviceDir, pkg, generatedFiles);
+  await queueEnvNeat(serviceDir, pkg, project, generatedFiles);
   const empty = dependencyEdits.length === 0 && generatedFiles.length === 0;
   if (empty) {
     return {
@@ -7111,7 +7207,7 @@ async function findAstroMiddleware(serviceDir) {
   }
   return null;
 }
-async function planAstro(serviceDir, pkg, manifestPath) {
+async function planAstro(serviceDir, pkg, manifestPath, project) {
   const useTs = await isTypeScriptProject(serviceDir);
   const otelInitFile = import_node_path40.default.join(
     serviceDir,
@@ -7129,7 +7225,7 @@ async function planAstro(serviceDir, pkg, manifestPath) {
       skipIfExists: true
     });
   }
-  await queueEnvNeat(serviceDir, pkg, generatedFiles);
+  await queueEnvNeat(serviceDir, pkg, project, generatedFiles);
   if (existingMiddleware === null) {
     generatedFiles.push({
       file: middlewareFile,
@@ -7173,9 +7269,10 @@ async function planAstro(serviceDir, pkg, manifestPath) {
     framework: "astro"
   };
 }
-async function plan(serviceDir) {
+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,
@@ -7188,32 +7285,32 @@ async function plan(serviceDir) {
   if (hasNextDependency(pkg)) {
     const nextConfig = await findNextConfig(serviceDir);
     if (nextConfig) {
-      return planNext(serviceDir, pkg, manifestPath, nextConfig);
+      return planNext(serviceDir, pkg, manifestPath, nextConfig, project);
     }
   }
   if (hasRemixDependency(pkg)) {
     const remixEntry = await findRemixEntry(serviceDir);
     if (remixEntry) {
-      return planRemix(serviceDir, pkg, manifestPath, remixEntry);
+      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);
+      return planSvelteKit(serviceDir, pkg, manifestPath, hooks, project);
     }
   }
   if (hasNuxtDependency(pkg)) {
     const nuxtConfig = await findNuxtConfig(serviceDir);
     if (nuxtConfig) {
-      return planNuxt(serviceDir, pkg, manifestPath);
+      return planNuxt(serviceDir, pkg, manifestPath, project);
     }
   }
   if (hasAstroDependency(pkg)) {
     const astroConfig = await findAstroConfig(serviceDir);
     if (astroConfig) {
-      return planAstro(serviceDir, pkg, manifestPath);
+      return planAstro(serviceDir, pkg, manifestPath, project);
     }
   }
   const entryFile = await resolveEntry(serviceDir, pkg);
@@ -7261,7 +7358,7 @@ async function plan(serviceDir) {
   if (!await exists2(envNeatFile)) {
     generatedFiles.push({
       file: envNeatFile,
-      contents: renderEnvNeat(pkg.name ?? import_node_path40.default.basename(serviceDir)),
+      contents: renderEnvNeat(envServiceName(pkg, serviceDir, project)),
       skipIfExists: true
     });
   }
@@ -7286,9 +7383,13 @@ function isAllowedWritePath(serviceDir, target) {
   if (base === "package.json") return true;
   if (base === ".env.neat") return true;
   if (/^otel-init\.(?:js|cjs|mjs|ts)$/.test(base)) return true;
-  if (/^instrumentation(?:\.node)?\.(?:js|cjs|mjs|ts)$/.test(base)) return true;
-  if (/^next\.config\.(?:js|mjs|ts)$/.test(base)) return true;
   const relPosix = rel.split(import_node_path40.default.sep).join("/");
+  if (/^instrumentation(?:\.node)?\.(?:js|cjs|mjs|ts)$/.test(base)) {
+    if (relPosix === base) return true;
+    if (relPosix === `src/${base}`) return true;
+    return false;
+  }
+  if (/^next\.config\.(?:js|mjs|ts)$/.test(base)) return true;
   if (relPosix === "app/otel.server.ts" || relPosix === "app/otel.server.js") return true;
   if (/^app\/entry\.server\.(?:tsx?|jsx?)$/.test(relPosix)) return true;
   if (relPosix === "src/otel-init.ts" || relPosix === "src/otel-init.js") return true;
@@ -7796,14 +7897,14 @@ async function extractAndPersist(opts) {
     errorsPath: projectPaths.errorsPath
   };
 }
-async function applyInstallersOver(services) {
+async function applyInstallersOver(services, project) {
   let instrumented = 0;
   let already = 0;
   let libOnly = 0;
   for (const svc of services) {
     const installer = await pickInstaller(svc.dir);
     if (!installer) continue;
-    const plan3 = await installer.plan(svc.dir);
+    const plan3 = await installer.plan(svc.dir, { project });
     if (isEmptyPlan(plan3) && !plan3.libOnly) {
       already++;
       continue;
@@ -7825,28 +7926,106 @@ async function promptYesNo(question) {
     });
   });
 }
-var DEFAULT_DAEMON_READY_TIMEOUT_MS = 15e3;
-async function checkDaemonHealth(restPort) {
+var DEFAULT_DAEMON_READY_TIMEOUT_MS = 6e4;
+var PROBE_INTERVAL_MS = 500;
+async function fetchDaemonHealth(restPort) {
   return new Promise((resolve) => {
     const req = import_node_http.default.get(`http://127.0.0.1:${restPort}/health`, (res) => {
       const ok = res.statusCode !== void 0 && res.statusCode >= 200 && res.statusCode < 300;
-      res.resume();
-      resolve(ok);
+      if (!ok) {
+        res.resume();
+        resolve(null);
+        return;
+      }
+      let body = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => {
+        body += chunk;
+      });
+      res.on("end", () => {
+        try {
+          resolve(JSON.parse(body));
+        } catch {
+          resolve({ ok: true });
+        }
+      });
     });
-    req.on("error", () => resolve(false));
+    req.on("error", () => resolve(null));
     req.setTimeout(1e3, () => {
       req.destroy();
-      resolve(false);
+      resolve(null);
+    });
+  });
+}
+async function checkDaemonHealth(restPort) {
+  const body = await fetchDaemonHealth(restPort);
+  return body !== null;
+}
+async function probeProjectHealth(restPort, name) {
+  return new Promise((resolve) => {
+    const req = import_node_http.default.get(
+      `http://127.0.0.1:${restPort}/projects/${encodeURIComponent(name)}/health`,
+      (res) => {
+        const code = res.statusCode ?? 0;
+        res.resume();
+        if (code >= 200 && code < 300) resolve("active");
+        else resolve("bootstrapping");
+      }
+    );
+    req.on("error", () => resolve("bootstrapping"));
+    req.setTimeout(1e3, () => {
+      req.destroy();
+      resolve("bootstrapping");
     });
   });
 }
+async function snapshotProjectStatus(restPort, 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)
+    }))
+  );
+}
 async function waitForDaemonReady(restPort, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
+  let lastBootstrapping = [];
   while (Date.now() < deadline) {
-    if (await checkDaemonHealth(restPort)) return true;
-    await new Promise((r) => setTimeout(r, 300));
+    const body = await fetchDaemonHealth(restPort);
+    if (body !== null) {
+      const projects2 = await snapshotProjectStatus(restPort, 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) {
+        return { ready: true, brokenProjects: broken, stillBootstrapping: [] };
+      }
+      const key = bootstrapping.slice().sort().join(",");
+      const prevKey = lastBootstrapping.slice().sort().join(",");
+      if (key !== prevKey) {
+        const plural = bootstrapping.length === 1 ? "" : "s";
+        console.log(
+          `neat: waiting on ${bootstrapping.length} project${plural}: ${bootstrapping.join(", ")}`
+        );
+        lastBootstrapping = bootstrapping;
+      }
+    }
+    await new Promise((r) => setTimeout(r, PROBE_INTERVAL_MS));
   }
-  return false;
+  const final = await fetchDaemonHealth(restPort);
+  const projects = final ? await snapshotProjectStatus(restPort, final) : [];
+  return {
+    ready: false,
+    brokenProjects: projects.filter((p) => p.status === "broken").map((p) => p.name),
+    stillBootstrapping: projects.filter((p) => p.status === "bootstrapping").map((p) => p.name)
+  };
 }
 function spawnDaemonDetached() {
   const here = import_node_path42.default.dirname(new URL(importMetaUrl).pathname);
@@ -7867,12 +8046,21 @@ function spawnDaemonDetached() {
   if (!entry2) {
     throw new Error(`orchestrator: cannot locate neatd entry in ${here}`);
   }
+  const env = { ...process.env };
+  const hasToken = typeof env.NEAT_AUTH_TOKEN === "string" && env.NEAT_AUTH_TOKEN.length > 0;
+  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"], {
     detached: true,
-    stdio: "ignore",
-    env: process.env
+    // stderr inherits the orchestrator's fd so the daemon's
+    // `BindAuthorityError` message lands in front of the operator instead
+    // of being swallowed (issue #341).
+    stdio: ["ignore", "ignore", "inherit"],
+    env
   });
   child.unref();
+  return child;
 }
 function openBrowser(url) {
   if (!process.stdout.isTTY) return "failed";
@@ -7948,7 +8136,7 @@ async function runOrchestrator(opts) {
     result.steps.apply.skipped = true;
     console.log("skipped instrumentation (--no-instrument)");
   } else {
-    const tally = await applyInstallersOver(services);
+    const tally = await applyInstallersOver(services, opts.project);
     result.steps.apply = { ...tally, skipped: false };
     console.log(
       `instrumented ${tally.instrumented}, already ${tally.alreadyInstrumented}, lib-only ${tally.libOnly}`
@@ -7967,12 +8155,25 @@ async function runOrchestrator(opts) {
       return result;
     }
     const ready = await waitForDaemonReady(restPort, timeoutMs);
-    result.steps.daemon = ready ? "spawned" : "timed-out";
-    if (!ready) {
+    result.steps.daemon = ready.ready ? "spawned" : "timed-out";
+    if (!ready.ready) {
       console.error(`neat: daemon did not become ready within ${timeoutMs}ms`);
+      if (ready.stillBootstrapping.length > 0) {
+        console.error(
+          `neat: still bootstrapping: ${ready.stillBootstrapping.join(", ")}`
+        );
+      }
+      if (ready.brokenProjects.length > 0) {
+        console.error(`neat: broken projects: ${ready.brokenProjects.join(", ")}`);
+      }
       result.exitCode = 1;
       return result;
     }
+    if (ready.brokenProjects.length > 0) {
+      console.warn(
+        `neat: ${ready.brokenProjects.length} project(s) reported broken: ${ready.brokenProjects.join(", ")}`
+      );
+    }
   }
   const dashboardUrl = opts.dashboardUrl ?? "http://localhost:6328";
   if (opts.noOpen || !process.stdout.isTTY) {
@@ -8603,7 +8804,7 @@ async function runSync(opts) {
     snapshotPath = target;
   }
   const skipApply = opts.dryRun || opts.noInstrument;
-  const applyTally = skipApply ? { instrumented: 0, alreadyInstrumented: 0, libOnly: 0 } : await applyInstallersOver(persisted.services);
+  const applyTally = skipApply ? { instrumented: 0, alreadyInstrumented: 0, libOnly: 0 } : await applyInstallersOver(persisted.services, entry2.name);
   const warnings = [];
   let daemonState = "skipped";
   let exitCode = 0;
@@ -8699,6 +8900,8 @@ function usage() {
   console.log("  uninstall <name>");
   console.log("                 Remove a project from the registry. Does not touch");
   console.log("                 neat-out/, policy.json, or any user file.");
+  console.log("  version        Print the installed @neat.is/core version and exit.");
+  console.log("                 Aliases: --version, -v.");
   console.log("  skill          Install or print the Claude Code MCP drop-in.");
   console.log("                 Flags:");
   console.log("                   --print-config   print the JSON snippet to stdout");
@@ -8825,7 +9028,7 @@ function parseArgs(rest) {
       out.yes = true;
       continue;
     }
-    if (arg === "--verbose" || arg === "-v") {
+    if (arg === "--verbose") {
       out.verbose = true;
       continue;
     }
@@ -8884,6 +9087,28 @@ 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 candidates = [
+    import_node_path44.default.resolve(here, "../package.json"),
+    import_node_path44.default.resolve(here, "../../package.json")
+  ];
+  for (const candidate of candidates) {
+    try {
+      const raw = (0, import_node_fs28.readFileSync)(candidate, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed.name === "@neat.is/core" && typeof parsed.version === "string") {
+        return parsed.version;
+      }
+    } catch {
+    }
+  }
+  return "unknown";
+}
+function printVersion() {
+  process.stdout.write(`${readPackageVersion()}
+`);
+}
 function printBanner() {
   console.log("\u2588\u2588\u2588\u2557   \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557");
   console.log("\u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u255A\u2550\u2550\u2588\u2588\u2554\u2550\u2550\u255D");
@@ -8893,7 +9118,7 @@ function printBanner() {
   console.log("\u255A\u2550\u255D  \u255A\u2550\u2550\u2550\u255D\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u255D  \u255A\u2550\u255D   \u255A\u2550\u255D   ");
   console.log("");
   console.log("  Network Expressive Architecting Tool");
-  console.log("  neat.is  \xB7  v0.2.5  \xB7  BSL 1.1");
+  console.log("  neat.is  \xB7  v0.4.0  \xB7  Apache 2.0");
   console.log("");
 }
 function printDiscoveryReport(opts, services) {
@@ -8921,12 +9146,12 @@ function printDiscoveryReport(opts, services) {
   }
   console.log("");
 }
-async function buildPatchSections(services) {
+async function buildPatchSections(services, project) {
   const sections = [];
   for (const svc of services) {
     const installer = await pickInstaller(svc.dir);
     if (!installer) continue;
-    const plan3 = await installer.plan(svc.dir);
+    const plan3 = await installer.plan(svc.dir, { project });
     if (isEmptyPlan(plan3) && !plan3.libOnly) continue;
     sections.push({ installer: installer.name, plan: plan3 });
   }
@@ -8941,7 +9166,7 @@ async function runInit(opts) {
   }
   const services = await discoverServices(opts.scanPath);
   printDiscoveryReport(opts, services);
-  const sections = opts.noInstall ? [] : await buildPatchSections(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");
   if (opts.dryRun) {
@@ -9099,6 +9324,10 @@ async function main() {
     usage();
     process.exit(0);
   }
+  if (cmd === "--version" || cmd === "-v" || cmd === "version") {
+    printVersion();
+    process.exit(0);
+  }
   const parsed = parseArgs(rest);
   const { positional, apply: apply3, dryRun, noInstall } = parsed;
   const project = parsed.project ?? DEFAULT_PROJECT;
@@ -9494,7 +9723,7 @@ async function runQueryVerb(cmd, parsed) {
   }
 }
 var entry = process.argv[1] ?? "";
-if (/[\\/]cli\.(?:cjs|js)$/.test(entry) || entry.endsWith("/cli") || entry.endsWith("/neat")) {
+if (/[\\/]cli\.(?:cjs|js)$/.test(entry) || entry.endsWith("/cli") || entry.endsWith("/neat") || entry.endsWith("/neat.is")) {
   main().catch((err) => {
     console.error(err);
     process.exit(1);
@@ -9505,6 +9734,7 @@ if (/[\\/]cli\.(?:cjs|js)$/.test(entry) || entry.endsWith("/cli") || entry.endsW
   CLAUDE_SKILL_CONFIG,
   QUERY_VERBS,
   parseArgs,
+  readPackageVersion,
   runInit,
   runQueryVerb,
   runSkill