@neat.is/core 0.3.4 → 0.3.6

package/dist/cli.cjs

@@ -805,11 +805,16 @@ init_cjs_shims();
 var import_types = require("@neat.is/types");
 var ROOT_CAUSE_MAX_DEPTH = 5;
 var BLAST_RADIUS_DEFAULT_DEPTH = 10;
+function isFrontierNode(graph, nodeId) {
+  if (!graph.hasNode(nodeId)) return false;
+  const attrs = graph.getNodeAttributes(nodeId);
+  return attrs.type === import_types.NodeType.FrontierNode;
+}
 function bestEdgeBySource(graph, edgeIds) {
   const best = /* @__PURE__ */ new Map();
   for (const id of edgeIds) {
     const e = graph.getEdgeAttributes(id);
-    if (e.provenance === import_types.Provenance.FRONTIER) continue;
+    if (isFrontierNode(graph, e.source)) continue;
     const cur = best.get(e.source);
     if (!cur || import_types.PROV_RANK[e.provenance] > import_types.PROV_RANK[cur.provenance]) {
       best.set(e.source, e);
@@ -821,7 +826,7 @@ function bestEdgeByTarget(graph, edgeIds) {
   const best = /* @__PURE__ */ new Map();
   for (const id of edgeIds) {
     const e = graph.getEdgeAttributes(id);
-    if (e.provenance === import_types.Provenance.FRONTIER) continue;
+    if (isFrontierNode(graph, e.target)) continue;
     const cur = best.get(e.target);
     if (!cur || import_types.PROV_RANK[e.provenance] > import_types.PROV_RANK[cur.provenance]) {
       best.set(e.target, e);
@@ -833,8 +838,7 @@ var PROVENANCE_CEILING = {
   OBSERVED: 1,
   INFERRED: 0.7,
   EXTRACTED: 0.5,
-  STALE: 0.3,
-  FRONTIER: 0.3
+  STALE: 0.3
 };
 function volumeWeight(spanCount) {
   if (!spanCount || spanCount <= 0) return 0.5;
@@ -1118,8 +1122,8 @@ var evaluateStructural = ({
     for (const edgeId of graph.outboundEdges(id)) {
       const e = graph.getEdgeAttributes(edgeId);
       if (e.type !== rule.edgeType) continue;
-      if (e.provenance === import_types2.Provenance.FRONTIER) continue;
       const target = graph.getNodeAttributes(e.target);
+      if (target.type === import_types2.NodeType.FrontierNode) continue;
       if (target.type === rule.toNodeType) {
         satisfied = true;
         break;
@@ -1238,8 +1242,8 @@ var evaluateCompatibility = ({
       for (const edgeId of graph.outboundEdges(svcId)) {
         const e = graph.getEdgeAttributes(edgeId);
         if (e.type !== import_types2.EdgeType.CONNECTS_TO) continue;
-        if (e.provenance === import_types2.Provenance.FRONTIER) continue;
         const dbAttrs = graph.getNodeAttributes(e.target);
+        if (dbAttrs.type === import_types2.NodeType.FrontierNode) continue;
         if (dbAttrs.type !== import_types2.NodeType.DatabaseNode) continue;
         const db = dbAttrs;
         for (const pair of compatPairs()) {
@@ -1556,31 +1560,6 @@ function ensureFrontierNode(graph, host, ts) {
   graph.addNode(id, node);
   return id;
 }
-function upsertFrontierEdge(graph, type, source, target, ts) {
-  const id = (0, import_types3.frontierEdgeId)(source, target, type);
-  if (graph.hasEdge(id)) {
-    const existing = graph.getEdgeAttributes(id);
-    const updated = {
-      ...existing,
-      provenance: import_types3.Provenance.FRONTIER,
-      lastObserved: ts,
-      callCount: (existing.callCount ?? 0) + 1
-    };
-    graph.replaceEdgeAttributes(id, updated);
-    return;
-  }
-  const edge = {
-    id,
-    source,
-    target,
-    type,
-    provenance: import_types3.Provenance.FRONTIER,
-    confidence: 1,
-    lastObserved: ts,
-    callCount: 1
-  };
-  graph.addEdgeWithKey(id, source, target, edge);
-}
 function upsertObservedEdge(graph, type, source, target, ts, isError = false) {
   if (!graph.hasNode(source) || !graph.hasNode(target)) return null;
   const id = makeObservedEdgeId(type, source, target);
@@ -1666,18 +1645,28 @@ async function appendErrorEvent(ctx, ev) {
   await import_node_fs3.promises.mkdir(import_node_path3.default.dirname(ctx.errorsPath), { recursive: true });
   await import_node_fs3.promises.appendFile(ctx.errorsPath, JSON.stringify(ev) + "\n", "utf8");
 }
+function sanitizeAttributes(attrs) {
+  const out = {};
+  for (const [k, v] of Object.entries(attrs)) {
+    if (typeof v === "bigint") out[k] = v.toString();
+    else out[k] = v;
+  }
+  return out;
+}
 function buildErrorEventForReceiver(span) {
   if (span.statusCode !== 2) return null;
   const ts = span.startTimeIso ?? (/* @__PURE__ */ new Date()).toISOString();
+  const attrs = sanitizeAttributes(span.attributes);
   return {
     id: `${span.traceId}:${span.spanId}`,
     timestamp: ts,
     service: span.service,
     traceId: span.traceId,
     spanId: span.spanId,
-    errorMessage: span.exception?.message ?? span.errorMessage ?? span.name ?? "unknown error",
+    errorMessage: span.exception?.message ?? "unknown error",
     ...span.exception?.type ? { exceptionType: span.exception.type } : {},
     ...span.exception?.stacktrace ? { exceptionStacktrace: span.exception.stacktrace } : {},
+    ...Object.keys(attrs).length > 0 ? { attributes: attrs } : {},
     affectedNode: (0, import_types3.serviceId)(span.service)
   };
 }
@@ -1728,11 +1717,16 @@ async function handleSpan(ctx, span) {
         affectedNode = targetId;
         resolvedViaAddress = true;
       } else if (!targetId) {
-        const frontierId2 = ensureFrontierNode(ctx.graph, host, ts);
-        if (ctx.graph.hasNode(sourceId)) {
-          upsertFrontierEdge(ctx.graph, import_types3.EdgeType.CALLS, sourceId, frontierId2, ts);
-        }
-        affectedNode = frontierId2;
+        const frontierNodeId = ensureFrontierNode(ctx.graph, host, ts);
+        upsertObservedEdge(
+          ctx.graph,
+          import_types3.EdgeType.CALLS,
+          sourceId,
+          frontierNodeId,
+          ts,
+          isError
+        );
+        affectedNode = frontierNodeId;
         resolvedViaAddress = true;
       }
     }
@@ -1754,15 +1748,17 @@ async function handleSpan(ctx, span) {
   if (span.statusCode === 2) {
     stitchTrace(ctx.graph, sourceId, ts);
     if (ctx.writeErrorEventInline !== false) {
+      const attrs = sanitizeAttributes(span.attributes);
       const ev = {
         id: `${span.traceId}:${span.spanId}`,
         timestamp: ts,
         service: span.service,
         traceId: span.traceId,
         spanId: span.spanId,
-        errorMessage: span.exception?.message ?? span.errorMessage ?? span.name ?? "unknown error",
+        errorMessage: span.exception?.message ?? "unknown error",
         ...span.exception?.type ? { exceptionType: span.exception.type } : {},
         ...span.exception?.stacktrace ? { exceptionStacktrace: span.exception.stacktrace } : {},
+        ...Object.keys(attrs).length > 0 ? { attributes: attrs } : {},
         affectedNode
       };
       await appendErrorEvent(ctx, ev);
@@ -1818,8 +1814,7 @@ function rewireFrontierEdges(graph, frontierId2, serviceId3) {
 }
 function rebuildEdge(graph, edge, newSource, newTarget, oldEdgeId) {
   graph.dropEdge(oldEdgeId);
-  const promotedProvenance = edge.provenance === import_types3.Provenance.FRONTIER ? import_types3.Provenance.OBSERVED : edge.provenance;
-  const newId = promotedProvenance === import_types3.Provenance.OBSERVED ? (0, import_types3.observedEdgeId)(newSource, newTarget, edge.type) : promotedProvenance === import_types3.Provenance.INFERRED ? (0, import_types3.inferredEdgeId)(newSource, newTarget, edge.type) : promotedProvenance === import_types3.Provenance.EXTRACTED ? (0, import_types3.extractedEdgeId)(newSource, newTarget, edge.type) : (0, import_types3.frontierEdgeId)(newSource, newTarget, edge.type);
+  const newId = edge.provenance === import_types3.Provenance.OBSERVED ? (0, import_types3.observedEdgeId)(newSource, newTarget, edge.type) : edge.provenance === import_types3.Provenance.INFERRED ? (0, import_types3.inferredEdgeId)(newSource, newTarget, edge.type) : (0, import_types3.extractedEdgeId)(newSource, newTarget, edge.type);
   if (graph.hasEdge(newId)) {
     const existing = graph.getEdgeAttributes(newId);
     const merged = {
@@ -1834,8 +1829,7 @@ function rebuildEdge(graph, edge, newSource, newTarget, oldEdgeId) {
     ...edge,
     id: newId,
     source: newSource,
-    target: newTarget,
-    provenance: promotedProvenance
+    target: newTarget
   };
   graph.addEdgeWithKey(newId, newSource, newTarget, rebuilt);
 }
@@ -4156,7 +4150,8 @@ async function extractFromDirectory(graph, scanPath, opts = {}) {
 init_cjs_shims();
 var import_node_fs18 = require("fs");
 var import_node_path31 = __toESM(require("path"), 1);
-var SCHEMA_VERSION = 2;
+var import_types19 = require("@neat.is/types");
+var SCHEMA_VERSION = 3;
 function migrateV1ToV2(payload) {
   const nodes = payload.graph.nodes;
   if (Array.isArray(nodes)) {
@@ -4168,6 +4163,25 @@ function migrateV1ToV2(payload) {
   }
   return { ...payload, schemaVersion: 2 };
 }
+function migrateV2ToV3(payload) {
+  const edges = payload.graph.edges;
+  if (Array.isArray(edges)) {
+    for (const edge of edges) {
+      const attrs = edge.attributes;
+      if (!attrs || attrs.provenance !== "FRONTIER") continue;
+      attrs.provenance = import_types19.Provenance.OBSERVED;
+      const type = typeof attrs.type === "string" ? attrs.type : void 0;
+      const source = typeof attrs.source === "string" ? attrs.source : void 0;
+      const target = typeof attrs.target === "string" ? attrs.target : void 0;
+      if (type && source && target) {
+        const newId = (0, import_types19.observedEdgeId)(source, target, type);
+        attrs.id = newId;
+        if (edge.key) edge.key = newId;
+      }
+    }
+  }
+  return { ...payload, schemaVersion: 3 };
+}
 async function ensureDir(filePath) {
   await import_node_fs18.promises.mkdir(import_node_path31.default.dirname(filePath), { recursive: true });
 }
@@ -4194,6 +4208,9 @@ async function loadGraphFromDisk(graph, outPath) {
   if (payload.schemaVersion === 1) {
     payload = migrateV1ToV2(payload);
   }
+  if (payload.schemaVersion === 2) {
+    payload = migrateV2ToV3(payload);
+  }
   if (payload.schemaVersion !== SCHEMA_VERSION) {
     throw new Error(
       `persist: unsupported snapshot schemaVersion ${payload.schemaVersion} (expected ${SCHEMA_VERSION})`
@@ -4246,11 +4263,11 @@ var import_chokidar = __toESM(require("chokidar"), 1);
 init_cjs_shims();
 var import_fastify = __toESM(require("fastify"), 1);
 var import_cors = __toESM(require("@fastify/cors"), 1);
-var import_types21 = require("@neat.is/types");
+var import_types22 = require("@neat.is/types");
 
 // src/divergences.ts
 init_cjs_shims();
-var import_types19 = require("@neat.is/types");
+var import_types20 = require("@neat.is/types");
 function bucketKey(source, target, type) {
   return `${type}|${source}|${target}`;
 }
@@ -4258,25 +4275,22 @@ function bucketEdges(graph) {
   const buckets = /* @__PURE__ */ new Map();
   graph.forEachEdge((id, attrs) => {
     const e = attrs;
-    const parsed = (0, import_types19.parseEdgeId)(id);
+    const parsed = (0, import_types20.parseEdgeId)(id);
     const provenance = parsed?.provenance ?? e.provenance;
     const key = bucketKey(e.source, e.target, e.type);
     const cur = buckets.get(key) ?? { source: e.source, target: e.target, type: e.type };
     switch (provenance) {
-      case import_types19.Provenance.EXTRACTED:
+      case import_types20.Provenance.EXTRACTED:
         cur.extracted = e;
         break;
-      case import_types19.Provenance.OBSERVED:
+      case import_types20.Provenance.OBSERVED:
         cur.observed = e;
         break;
-      case import_types19.Provenance.INFERRED:
+      case import_types20.Provenance.INFERRED:
         cur.inferred = e;
         break;
-      case import_types19.Provenance.FRONTIER:
-        cur.frontier = e;
-        break;
       default:
-        if (e.provenance === import_types19.Provenance.STALE) cur.stale = e;
+        if (e.provenance === import_types20.Provenance.STALE) cur.stale = e;
     }
     buckets.set(key, cur);
   });
@@ -4285,7 +4299,7 @@ function bucketEdges(graph) {
 function nodeIsFrontier(graph, nodeId) {
   if (!graph.hasNode(nodeId)) return false;
   const attrs = graph.getNodeAttributes(nodeId);
-  return attrs.type === import_types19.NodeType.FrontierNode;
+  return attrs.type === import_types20.NodeType.FrontierNode;
 }
 function clampConfidence(n) {
   if (!Number.isFinite(n)) return 0;
@@ -4346,7 +4360,7 @@ function declaredHostFor(svc) {
 function hasExtractedConfiguredBy(graph, svcId) {
   for (const edgeId of graph.outboundEdges(svcId)) {
     const e = graph.getEdgeAttributes(edgeId);
-    if (e.type === import_types19.EdgeType.CONFIGURED_BY && e.provenance === import_types19.Provenance.EXTRACTED) {
+    if (e.type === import_types20.EdgeType.CONFIGURED_BY && e.provenance === import_types20.Provenance.EXTRACTED) {
       return true;
     }
   }
@@ -4359,10 +4373,10 @@ function detectHostMismatch(graph, svcId, svc) {
   const out = [];
   for (const edgeId of graph.outboundEdges(svcId)) {
     const edge = graph.getEdgeAttributes(edgeId);
-    if (edge.type !== import_types19.EdgeType.CONNECTS_TO) continue;
-    if (edge.provenance !== import_types19.Provenance.OBSERVED) continue;
+    if (edge.type !== import_types20.EdgeType.CONNECTS_TO) continue;
+    if (edge.provenance !== import_types20.Provenance.OBSERVED) continue;
     const target = graph.getNodeAttributes(edge.target);
-    if (target.type !== import_types19.NodeType.DatabaseNode) continue;
+    if (target.type !== import_types20.NodeType.DatabaseNode) continue;
     const observedHost = target.host?.trim();
     if (!observedHost) continue;
     if (observedHost === declaredHost) continue;
@@ -4384,10 +4398,10 @@ function detectCompatDivergences(graph, svcId, svc) {
   const deps = svc.dependencies ?? {};
   for (const edgeId of graph.outboundEdges(svcId)) {
     const edge = graph.getEdgeAttributes(edgeId);
-    if (edge.type !== import_types19.EdgeType.CONNECTS_TO) continue;
-    if (edge.provenance !== import_types19.Provenance.OBSERVED) continue;
+    if (edge.type !== import_types20.EdgeType.CONNECTS_TO) continue;
+    if (edge.provenance !== import_types20.Provenance.OBSERVED) continue;
     const target = graph.getNodeAttributes(edge.target);
-    if (target.type !== import_types19.NodeType.DatabaseNode) continue;
+    if (target.type !== import_types20.NodeType.DatabaseNode) continue;
     for (const pair of compatPairs()) {
       if (pair.engine !== target.engine) continue;
       const declared = deps[pair.driver];
@@ -4448,7 +4462,7 @@ function computeDivergences(graph, opts = {}) {
   }
   graph.forEachNode((nodeId, attrs) => {
     const n = attrs;
-    if (n.type !== import_types19.NodeType.ServiceNode) return;
+    if (n.type !== import_types20.NodeType.ServiceNode) return;
     const svc = n;
     for (const d of detectHostMismatch(graph, nodeId, svc)) all.push(d);
     for (const d of detectCompatDivergences(graph, nodeId, svc)) all.push(d);
@@ -4481,7 +4495,7 @@ function computeDivergences(graph, opts = {}) {
     if (a.source !== b.source) return a.source.localeCompare(b.source);
     return a.target.localeCompare(b.target);
   });
-  return import_types19.DivergenceResultSchema.parse({
+  return import_types20.DivergenceResultSchema.parse({
     divergences: filtered,
     totalAffected: filtered.length,
     computedAt: (/* @__PURE__ */ new Date()).toISOString()
@@ -4622,7 +4636,7 @@ init_cjs_shims();
 var import_node_fs20 = require("fs");
 var import_node_os2 = __toESM(require("os"), 1);
 var import_node_path33 = __toESM(require("path"), 1);
-var import_types20 = require("@neat.is/types");
+var import_types21 = require("@neat.is/types");
 var LOCK_TIMEOUT_MS = 5e3;
 var LOCK_RETRY_MS = 50;
 function neatHome() {
@@ -4701,10 +4715,10 @@ async function readRegistry() {
     throw err;
   }
   const parsed = JSON.parse(raw);
-  return import_types20.RegistryFileSchema.parse(parsed);
+  return import_types21.RegistryFileSchema.parse(parsed);
 }
 async function writeRegistry(reg) {
-  const validated = import_types20.RegistryFileSchema.parse(reg);
+  const validated = import_types21.RegistryFileSchema.parse(reg);
   await writeAtomically(registryPath(), JSON.stringify(validated, null, 2) + "\n");
 }
 var ProjectNameCollisionError = class extends Error {
@@ -4955,11 +4969,11 @@ function registerRoutes(scope, ctx) {
       const candidates = req.query.type.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
       const parsed = [];
       for (const c of candidates) {
-        const r = import_types21.DivergenceTypeSchema.safeParse(c);
+        const r = import_types22.DivergenceTypeSchema.safeParse(c);
         if (!r.success) {
           return reply.code(400).send({
             error: `unknown divergence type "${c}"`,
-            allowed: import_types21.DivergenceTypeSchema.options
+            allowed: import_types22.DivergenceTypeSchema.options
           });
         }
         parsed.push(r.data);
@@ -5143,7 +5157,7 @@ function registerRoutes(scope, ctx) {
     const log = new PolicyViolationsLog(proj.paths.policyViolationsPath);
     let violations = await log.readAll();
     if (req.query.severity) {
-      const sev = import_types21.PolicySeveritySchema.safeParse(req.query.severity);
+      const sev = import_types22.PolicySeveritySchema.safeParse(req.query.severity);
       if (!sev.success) {
         return reply.code(400).send({
           error: "invalid severity",
@@ -5160,7 +5174,7 @@ function registerRoutes(scope, ctx) {
   scope.post("/policies/check", async (req, reply) => {
     const proj = resolveProject(registry, req, reply);
     if (!proj) return;
-    const parsed = import_types21.PoliciesCheckBodySchema.safeParse(req.body ?? {});
+    const parsed = import_types22.PoliciesCheckBodySchema.safeParse(req.body ?? {});
     if (!parsed.success) {
       return reply.code(400).send({
         error: "invalid /policies/check body",
@@ -5897,15 +5911,69 @@ init_cjs_shims();
 init_cjs_shims();
 var import_node_fs23 = require("fs");
 var import_node_path38 = __toESM(require("path"), 1);
+
+// src/installers/templates.ts
+init_cjs_shims();
+var OTEL_INIT_HEADER = "// Generated by `neat init --apply` (ADR-069). OpenTelemetry auto-instrumentation hook.";
+var OTEL_INIT_CJS = `${OTEL_INIT_HEADER}
+// Loads .env.neat (OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT) before
+// the auto-instrumentation hook attaches. Configure via the env file.
+const path = require('node:path')
+try {
+  require('dotenv').config({ path: path.join(__dirname, '.env.neat') })
+} catch (err) {
+  // dotenv unavailable \u2014 fall through to process.env.
+}
+require('@opentelemetry/auto-instrumentations-node/register')
+`;
+var OTEL_INIT_ESM = `${OTEL_INIT_HEADER}
+// Loads .env.neat (OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT) before
+// the auto-instrumentation hook attaches. Configure via the env file.
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+import dotenv from 'dotenv'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+dotenv.config({ path: path.join(here, '.env.neat') })
+
+await import('@opentelemetry/auto-instrumentations-node/register')
+`;
+var OTEL_INIT_TS = `${OTEL_INIT_HEADER}
+// Loads .env.neat (OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT) before
+// the auto-instrumentation hook attaches. Configure via the env file.
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+import dotenv from 'dotenv'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+dotenv.config({ path: path.join(here, '.env.neat') })
+
+await import('@opentelemetry/auto-instrumentations-node/register')
+`;
+function renderEnvNeat(serviceName) {
+  return [
+    "# Generated by `neat init --apply` (ADR-069).",
+    `OTEL_SERVICE_NAME=${serviceName}`,
+    "OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318",
+    ""
+  ].join("\n");
+}
+
+// src/installers/javascript.ts
 var SDK_PACKAGES = [
   { name: "@opentelemetry/api", version: "^1.9.0" },
   { name: "@opentelemetry/sdk-node", version: "^0.57.0" },
-  { name: "@opentelemetry/auto-instrumentations-node", version: "^0.55.0" }
+  { name: "@opentelemetry/auto-instrumentations-node", version: "^0.55.0" },
+  // ADR-069 §5 — dotenv is the fourth dep. The generated otel-init loads
+  // .env.neat through it so OTEL_SERVICE_NAME and the endpoint are in scope
+  // before the auto-instrumentation hook attaches.
+  { name: "dotenv", version: "^16.4.5" }
 ];
-var AUTO_INSTRUMENT_REQUIRE = "--require @opentelemetry/auto-instrumentations-node/register";
 var OTEL_ENV = {
-  // null target — NEAT does not write `.env` itself; the user sets the env
-  // var in their orchestration layer.
+  // ADR-069 §4 — endpoint moves into the per-package .env.neat (written
+  // by the apply phase). The envEdits surface stays for the dry-run
+  // patch render: it documents the key/value the user can inspect in the
+  // generated .env.neat.
   file: null,
   key: "OTEL_EXPORTER_OTLP_ENDPOINT",
   value: "http://localhost:4318"
@@ -5918,16 +5986,75 @@ async function readPackageJson(serviceDir) {
     return null;
   }
 }
+async function exists2(p) {
+  try {
+    await import_node_fs23.promises.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function detect(serviceDir) {
   const pkg = await readPackageJson(serviceDir);
   return pkg !== null && typeof pkg.name === "string";
 }
-function rewriteStartScript(start) {
-  if (start.includes(AUTO_INSTRUMENT_REQUIRE)) return start;
-  if (/^\s*node\b/.test(start)) {
-    return start.replace(/^\s*node\b\s*/, `node ${AUTO_INSTRUMENT_REQUIRE} `);
+var INDEX_CANDIDATES = ["index.ts", "index.tsx", "index.js", "index.mjs", "index.cjs"];
+async function resolveEntry(serviceDir, pkg) {
+  if (typeof pkg.main === "string" && pkg.main.length > 0) {
+    const candidate = import_node_path38.default.resolve(serviceDir, pkg.main);
+    if (await exists2(candidate)) return candidate;
+  }
+  if (pkg.bin) {
+    let binEntry;
+    if (typeof pkg.bin === "string") {
+      binEntry = pkg.bin;
+    } else if (pkg.name && typeof pkg.bin[pkg.name] === "string") {
+      binEntry = pkg.bin[pkg.name];
+    } else {
+      const first = Object.values(pkg.bin)[0];
+      if (typeof first === "string") binEntry = first;
+    }
+    if (binEntry) {
+      const candidate = import_node_path38.default.resolve(serviceDir, binEntry);
+      if (await exists2(candidate)) return candidate;
+    }
   }
-  return `node ${AUTO_INSTRUMENT_REQUIRE} -- ${start}`;
+  for (const name of INDEX_CANDIDATES) {
+    const candidate = import_node_path38.default.join(serviceDir, name);
+    if (await exists2(candidate)) return candidate;
+  }
+  return null;
+}
+function dispatchEntry(entryFile, pkg) {
+  const ext = import_node_path38.default.extname(entryFile).toLowerCase();
+  if (ext === ".ts" || ext === ".tsx") return "ts";
+  if (ext === ".mjs") return "esm";
+  if (ext === ".cjs") return "cjs";
+  return pkg.type === "module" ? "esm" : "cjs";
+}
+function otelInitFilename(flavor) {
+  if (flavor === "ts") return "otel-init.ts";
+  if (flavor === "esm") return "otel-init.mjs";
+  return "otel-init.cjs";
+}
+function otelInitContents(flavor) {
+  if (flavor === "ts") return OTEL_INIT_TS;
+  if (flavor === "esm") return OTEL_INIT_ESM;
+  return OTEL_INIT_CJS;
+}
+function injectionLine(flavor, entryFile, otelInitFile) {
+  let rel = import_node_path38.default.relative(import_node_path38.default.dirname(entryFile), otelInitFile);
+  if (!rel.startsWith(".")) rel = `./${rel}`;
+  rel = rel.split(import_node_path38.default.sep).join("/");
+  if (flavor === "cjs") return `require('${rel}')`;
+  if (flavor === "esm") return `import '${rel}'`;
+  const tsRel = rel.replace(/\.ts$/, "");
+  return `import '${tsRel}'`;
+}
+function lineIsOtelInjection(line) {
+  const trimmed = line.trim();
+  if (trimmed.length === 0) return false;
+  return /(?:require\(|import\s+)['"]\.\/otel-init[^'"]*['"]/.test(trimmed);
 }
 async function plan(serviceDir) {
   const pkg = await readPackageJson(serviceDir);
@@ -5937,9 +6064,17 @@ async function plan(serviceDir) {
     serviceDir,
     dependencyEdits: [],
     entrypointEdits: [],
-    envEdits: []
+    envEdits: [],
+    generatedFiles: []
   };
   if (!pkg) return empty;
+  const entryFile = await resolveEntry(serviceDir, pkg);
+  if (!entryFile) {
+    return { ...empty, libOnly: true };
+  }
+  const flavor = dispatchEntry(entryFile, pkg);
+  const otelInitFile = import_node_path38.default.join(import_node_path38.default.dirname(entryFile), otelInitFilename(flavor));
+  const envNeatFile = import_node_path38.default.join(serviceDir, ".env.neat");
   const existingDeps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
   const dependencyEdits = [];
   for (const sdk of SDK_PACKAGES) {
@@ -5952,14 +6087,37 @@ async function plan(serviceDir) {
     });
   }
   const entrypointEdits = [];
-  const startScript = pkg.scripts?.start;
-  if (typeof startScript === "string" && startScript.trim().length > 0) {
-    const rewritten = rewriteStartScript(startScript);
-    if (rewritten !== startScript) {
-      entrypointEdits.push({ file: manifestPath, before: startScript, after: rewritten });
+  try {
+    const raw = await import_node_fs23.promises.readFile(entryFile, "utf8");
+    const lines = raw.split(/\r?\n/);
+    const firstReal = lines[0]?.startsWith("#!") ? lines[1] ?? "" : lines[0] ?? "";
+    if (!lineIsOtelInjection(firstReal)) {
+      const inject = injectionLine(flavor, entryFile, otelInitFile);
+      entrypointEdits.push({
+        file: entryFile,
+        before: firstReal,
+        after: inject
+      });
     }
+  } catch {
+    return { ...empty, libOnly: true };
+  }
+  const generatedFiles = [];
+  if (!await exists2(otelInitFile)) {
+    generatedFiles.push({
+      file: otelInitFile,
+      contents: otelInitContents(flavor),
+      skipIfExists: true
+    });
   }
-  if (dependencyEdits.length === 0 && entrypointEdits.length === 0) {
+  if (!await exists2(envNeatFile)) {
+    generatedFiles.push({
+      file: envNeatFile,
+      contents: renderEnvNeat(pkg.name ?? import_node_path38.default.basename(serviceDir)),
+      skipIfExists: true
+    });
+  }
+  if (dependencyEdits.length === 0 && entrypointEdits.length === 0 && generatedFiles.length === 0) {
     return empty;
   }
   return {
@@ -5967,53 +6125,129 @@ async function plan(serviceDir) {
     serviceDir,
     dependencyEdits,
     entrypointEdits,
-    envEdits: [OTEL_ENV]
+    envEdits: [OTEL_ENV],
+    generatedFiles,
+    entryFile,
+    libOnly: false
   };
 }
+function isAllowedWritePath(serviceDir, target) {
+  const rel = import_node_path38.default.relative(serviceDir, target);
+  if (rel.startsWith("..")) return false;
+  const base = import_node_path38.default.basename(target);
+  if (base === "package.json") return true;
+  if (base === ".env.neat") return true;
+  if (/^otel-init\.(?:js|cjs|mjs|ts)$/.test(base)) return true;
+  return false;
+}
+async function writeAtomic(file, contents) {
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  await import_node_fs23.promises.writeFile(tmp, contents, "utf8");
+  await import_node_fs23.promises.rename(tmp, file);
+}
 async function apply(installPlan) {
-  const touched = /* @__PURE__ */ new Set();
-  for (const e of installPlan.dependencyEdits) touched.add(e.file);
-  for (const e of installPlan.entrypointEdits) touched.add(e.file);
-  if (touched.size === 0) return;
+  const { serviceDir } = installPlan;
+  if (installPlan.libOnly) {
+    return {
+      serviceDir,
+      outcome: "lib-only",
+      reason: "no resolvable entry point",
+      writtenFiles: []
+    };
+  }
+  if (installPlan.dependencyEdits.length === 0 && installPlan.entrypointEdits.length === 0 && (installPlan.generatedFiles?.length ?? 0) === 0) {
+    return {
+      serviceDir,
+      outcome: "already-instrumented",
+      writtenFiles: []
+    };
+  }
+  const allTargets = /* @__PURE__ */ new Set();
+  for (const d of installPlan.dependencyEdits) allTargets.add(d.file);
+  for (const e of installPlan.entrypointEdits) allTargets.add(e.file);
+  for (const g of installPlan.generatedFiles ?? []) allTargets.add(g.file);
+  for (const target of allTargets) {
+    const isEntryEdit = installPlan.entrypointEdits.some((e) => e.file === target);
+    if (isEntryEdit) continue;
+    if (!isAllowedWritePath(serviceDir, target)) {
+      throw new Error(
+        `javascript installer: refusing to write outside the allowed path set (ADR-069 \xA77): ${target}`
+      );
+    }
+  }
   const originals = /* @__PURE__ */ new Map();
-  for (const file of touched) {
-    try {
-      originals.set(file, await import_node_fs23.promises.readFile(file, "utf8"));
-    } catch {
+  const createdFiles = [];
+  for (const target of allTargets) {
+    if (await exists2(target)) {
+      try {
+        originals.set(target, await import_node_fs23.promises.readFile(target, "utf8"));
+      } catch {
+      }
     }
   }
+  const writtenFiles = [];
   try {
-    for (const file of touched) {
-      const raw = originals.get(file) ?? "";
+    const manifestTargets = installPlan.dependencyEdits.reduce((acc, e) => {
+      acc.add(e.file);
+      return acc;
+    }, /* @__PURE__ */ new Set());
+    for (const file of manifestTargets) {
+      const raw = originals.get(file);
+      if (raw === void 0) {
+        throw new Error(`javascript installer: cannot read ${file} during apply`);
+      }
       const pkg = JSON.parse(raw);
       pkg.dependencies = pkg.dependencies ?? {};
       for (const dep of installPlan.dependencyEdits) {
         if (dep.file !== file) continue;
         if (dep.kind === "add") {
-          pkg.dependencies[dep.name] = dep.version;
+          if (!(dep.name in (pkg.dependencies ?? {}))) {
+            pkg.dependencies[dep.name] = dep.version;
+          }
         } else {
           delete pkg.dependencies[dep.name];
         }
       }
-      for (const ep of installPlan.entrypointEdits) {
-        if (ep.file !== file) continue;
-        pkg.scripts = pkg.scripts ?? {};
-        if (pkg.scripts.start === ep.before) {
-          pkg.scripts.start = ep.after;
-        }
-      }
       const newRaw = JSON.stringify(pkg, null, 2) + "\n";
-      const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
-      await import_node_fs23.promises.writeFile(tmp, newRaw, "utf8");
-      await import_node_fs23.promises.rename(tmp, file);
+      await writeAtomic(file, newRaw);
+      writtenFiles.push(file);
+    }
+    for (const gen of installPlan.generatedFiles ?? []) {
+      if (gen.skipIfExists && await exists2(gen.file)) {
+        continue;
+      }
+      await writeAtomic(gen.file, gen.contents);
+      if (!originals.has(gen.file)) createdFiles.push(gen.file);
+      writtenFiles.push(gen.file);
+    }
+    for (const ep of installPlan.entrypointEdits) {
+      const raw = originals.get(ep.file);
+      if (raw === void 0) {
+        throw new Error(`javascript installer: cannot read entry ${ep.file} during apply`);
+      }
+      const lines = raw.split(/\r?\n/);
+      const hasShebang = lines[0]?.startsWith("#!") ?? false;
+      const insertAt = hasShebang ? 1 : 0;
+      const firstReal = lines[insertAt] ?? "";
+      if (lineIsOtelInjection(firstReal)) continue;
+      lines.splice(insertAt, 0, ep.after);
+      const newRaw = lines.join("\n");
+      await writeAtomic(ep.file, newRaw);
+      writtenFiles.push(ep.file);
     }
   } catch (err) {
-    await rollback(installPlan, originals);
+    await rollback(installPlan, originals, createdFiles);
     throw err;
   }
+  return {
+    serviceDir,
+    outcome: "instrumented",
+    writtenFiles
+  };
 }
-async function rollback(installPlan, originals) {
+async function rollback(installPlan, originals, createdFiles) {
   const restored = [];
+  const removed = [];
   for (const [file, raw] of originals.entries()) {
     try {
       await import_node_fs23.promises.writeFile(file, raw, "utf8");
@@ -6021,6 +6255,13 @@ async function rollback(installPlan, originals) {
     } catch {
     }
   }
+  for (const file of createdFiles) {
+    try {
+      await import_node_fs23.promises.unlink(file);
+      removed.push(file);
+    } catch {
+    }
+  }
   const lines = [
     "# neat-rollback.patch",
     "",
@@ -6028,6 +6269,7 @@ async function rollback(installPlan, originals) {
     "# Files listed below were restored to their pre-apply contents.",
     "",
     ...restored.map((f) => `restored: ${f}`),
+    ...removed.map((f) => `removed:  ${f}`),
     ""
   ];
   const rollbackPath = import_node_path38.default.join(installPlan.serviceDir, "neat-rollback.patch");
@@ -6053,7 +6295,7 @@ var OTEL_ENV2 = {
   key: "OTEL_EXPORTER_OTLP_ENDPOINT",
   value: "http://localhost:4318"
 };
-async function exists2(p) {
+async function exists3(p) {
   try {
     await import_node_fs24.promises.stat(p);
     return true;
@@ -6064,7 +6306,7 @@ async function exists2(p) {
 async function detect2(serviceDir) {
   const markers = ["requirements.txt", "pyproject.toml", "setup.py"];
   for (const m of markers) {
-    if (await exists2(import_node_path39.default.join(serviceDir, m))) return true;
+    if (await exists3(import_node_path39.default.join(serviceDir, m))) return true;
   }
   return false;
 }
@@ -6075,7 +6317,7 @@ function reqPackageName(line) {
 }
 async function planRequirementsTxtEdits(serviceDir) {
   const file = import_node_path39.default.join(serviceDir, "requirements.txt");
-  if (!await exists2(file)) return null;
+  if (!await exists3(file)) return null;
   const raw = await import_node_fs24.promises.readFile(file, "utf8");
   const presentNames = new Set(
     raw.split(/\r?\n/).map(reqPackageName).filter((n) => n.length > 0)
@@ -6085,7 +6327,7 @@ async function planRequirementsTxtEdits(serviceDir) {
 }
 async function planProcfileEdits(serviceDir) {
   const procfile = import_node_path39.default.join(serviceDir, "Procfile");
-  if (!await exists2(procfile)) return [];
+  if (!await exists3(procfile)) return [];
   const raw = await import_node_fs24.promises.readFile(procfile, "utf8");
   const edits = [];
   for (const line of raw.split(/\r?\n/)) {
@@ -6152,10 +6394,13 @@ async function applyProcfile(procfile, edits, original) {
   await import_node_fs24.promises.rename(tmp, procfile);
 }
 async function apply2(installPlan) {
+  const { serviceDir } = installPlan;
   const touched = /* @__PURE__ */ new Set();
   for (const e of installPlan.dependencyEdits) touched.add(e.file);
   for (const e of installPlan.entrypointEdits) touched.add(e.file);
-  if (touched.size === 0) return;
+  if (touched.size === 0) {
+    return { serviceDir, outcome: "already-instrumented", writtenFiles: [] };
+  }
   const originals = /* @__PURE__ */ new Map();
   for (const file of touched) {
     try {
@@ -6163,6 +6408,7 @@ async function apply2(installPlan) {
     } catch {
     }
   }
+  const writtenFiles = [];
   try {
     for (const file of touched) {
       const raw = originals.get(file);
@@ -6172,16 +6418,23 @@ async function apply2(installPlan) {
       const base = import_node_path39.default.basename(file);
       if (base === "requirements.txt") {
         const edits = installPlan.dependencyEdits.filter((e) => e.file === file);
-        if (edits.length > 0) await applyRequirementsTxt(file, edits, raw);
+        if (edits.length > 0) {
+          await applyRequirementsTxt(file, edits, raw);
+          writtenFiles.push(file);
+        }
       } else if (base === "Procfile") {
         const edits = installPlan.entrypointEdits.filter((e) => e.file === file);
-        if (edits.length > 0) await applyProcfile(file, edits, raw);
+        if (edits.length > 0) {
+          await applyProcfile(file, edits, raw);
+          writtenFiles.push(file);
+        }
       }
     }
   } catch (err) {
     await rollback2(installPlan, originals);
     throw err;
   }
+  return { serviceDir, outcome: "instrumented", writtenFiles };
 }
 async function rollback2(installPlan, originals) {
   const restored = [];
@@ -6214,7 +6467,7 @@ var pythonInstaller = {
 // src/installers/shared.ts
 init_cjs_shims();
 function isEmptyPlan(plan3) {
-  return plan3.dependencyEdits.length === 0 && plan3.entrypointEdits.length === 0 && plan3.envEdits.length === 0;
+  return plan3.dependencyEdits.length === 0 && plan3.entrypointEdits.length === 0 && plan3.envEdits.length === 0 && (plan3.generatedFiles?.length ?? 0) === 0;
 }
 
 // src/installers/index.ts
@@ -6256,8 +6509,18 @@ function renderPatch(sections) {
     const { installer, plan: plan3 } = section;
     lines.push(`## ${installer} (${plan3.language}) \u2014 ${plan3.serviceDir}`);
     lines.push("");
+    if (plan3.libOnly) {
+      lines.push("### skipped \u2014 no resolvable entry point (lib-only)");
+      lines.push("");
+      continue;
+    }
+    if (plan3.entryFile) {
+      lines.push(`entry: ${plan3.entryFile}`);
+      lines.push("");
+    }
     if (plan3.dependencyEdits.length > 0) {
       lines.push("### dependencies");
+      const byFile = /* @__PURE__ */ new Map();
       for (const dep of plan3.dependencyEdits) {
         const base = dep.file.split(/[\\/]/).pop() ?? dep.file;
         if (FORBIDDEN_LOCKFILES.has(base)) {
@@ -6265,24 +6528,41 @@ function renderPatch(sections) {
             `installer "${installer}" produced a dependency edit against a lockfile (${dep.file}); lockfiles must never be touched (ADR-047).`
           );
         }
-        lines.push(`- ${dep.kind} ${dep.name}@${dep.version} in ${dep.file}`);
+        const existing = byFile.get(dep.file) ?? [];
+        existing.push(dep);
+        byFile.set(dep.file, existing);
+      }
+      for (const [file, deps] of byFile) {
+        lines.push(`--- ${file}`);
+        for (const dep of deps) {
+          lines.push(`+ "${dep.name}": "${dep.version}"`);
+        }
+      }
+      lines.push("");
+    }
+    if (plan3.generatedFiles && plan3.generatedFiles.length > 0) {
+      lines.push("### generated files");
+      for (const gen of plan3.generatedFiles) {
+        lines.push(`--- (new file) ${gen.file}`);
+        for (const ln of gen.contents.split(/\r?\n/)) {
+          lines.push(`+ ${ln}`);
+        }
       }
       lines.push("");
     }
     if (plan3.entrypointEdits.length > 0) {
-      lines.push("### entrypoint");
+      lines.push("### entry-point injection");
       for (const e of plan3.entrypointEdits) {
-        lines.push(`- ${e.file}`);
-        lines.push(`    - before: ${e.before}`);
-        lines.push(`    - after:  ${e.after}`);
+        lines.push(`--- ${e.file}`);
+        lines.push(`+ ${e.after}`);
+        lines.push(`  ${e.before}`);
       }
       lines.push("");
     }
     if (plan3.envEdits.length > 0) {
-      lines.push("### env");
+      lines.push("### env (written to <package-dir>/.env.neat)");
       for (const env of plan3.envEdits) {
-        const target = env.file ?? "(set in your orchestration layer)";
-        lines.push(`- ${env.key}=${env.value} \u2192 ${target}`);
+        lines.push(`- ${env.key}=${env.value}`);
       }
       lines.push("");
     }
@@ -6291,11 +6571,11 @@ function renderPatch(sections) {
 }
 
 // src/cli.ts
-var import_types23 = require("@neat.is/types");
+var import_types24 = require("@neat.is/types");
 
 // src/cli-client.ts
 init_cjs_shims();
-var import_types22 = require("@neat.is/types");
+var import_types23 = require("@neat.is/types");
 var HttpError = class extends Error {
   constructor(status2, message, responseBody = "") {
     super(message);
@@ -6430,7 +6710,7 @@ async function runBlastRadius(client, input) {
   }
 }
 function formatBlastEntry(n) {
-  const tag = n.edgeProvenance === import_types22.Provenance.STALE ? " [STALE \u2014 last seen too long ago]" : "";
+  const tag = n.edgeProvenance === import_types23.Provenance.STALE ? " [STALE \u2014 last seen too long ago]" : "";
   return `  \u2022 ${n.nodeId} (distance ${n.distance}, ${n.edgeProvenance})${tag}`;
 }
 async function runDependencies(client, input) {
@@ -6476,9 +6756,9 @@ async function runObservedDependencies(client, input) {
     const edges = await client.get(
       projectPath(input.project, `/graph/edges/${encodeURIComponent(input.nodeId)}`)
     );
-    const observed = edges.outbound.filter((e) => e.provenance === import_types22.Provenance.OBSERVED);
+    const observed = edges.outbound.filter((e) => e.provenance === import_types23.Provenance.OBSERVED);
     if (observed.length === 0) {
-      const hasExtracted = edges.outbound.some((e) => e.provenance === import_types22.Provenance.EXTRACTED);
+      const hasExtracted = edges.outbound.some((e) => e.provenance === import_types23.Provenance.EXTRACTED);
       const note = hasExtracted ? " Static (EXTRACTED) dependencies exist but no runtime traffic has been seen \u2014 is OTel running?" : "";
       return { summary: `No OBSERVED dependencies for ${input.nodeId}.${note}` };
     }
@@ -6486,7 +6766,7 @@ async function runObservedDependencies(client, input) {
     return {
       summary: `${input.nodeId} has ${observed.length} runtime dependenc${observed.length === 1 ? "y" : "ies"} confirmed by OTel.`,
       block: blockLines.join("\n"),
-      provenance: import_types22.Provenance.OBSERVED
+      provenance: import_types23.Provenance.OBSERVED
     };
   } catch (err) {
     if (err instanceof HttpError && err.status === 404) {
@@ -6540,7 +6820,7 @@ async function runIncidents(client, input) {
     return {
       summary: `${target} has ${body.total} recorded incident${body.total === 1 ? "" : "s"}; showing the ${ordered.length} most recent.`,
       block: blockLines.join("\n"),
-      provenance: import_types22.Provenance.OBSERVED
+      provenance: import_types23.Provenance.OBSERVED
     };
   } catch (err) {
     if (err instanceof HttpError && err.status === 404) {
@@ -6649,7 +6929,7 @@ async function runStaleEdges(client, input) {
   return {
     summary: `${events.length} stale-edge transition${events.length === 1 ? "" : "s"} recorded${input.edgeType ? ` for ${input.edgeType}` : ""}.`,
     block: blockLines.join("\n"),
-    provenance: import_types22.Provenance.STALE
+    provenance: import_types23.Provenance.STALE
   };
 }
 async function runPolicies(client, input) {
@@ -7031,7 +7311,7 @@ async function buildPatchSections(services) {
     const installer = await pickInstaller(svc.dir);
     if (!installer) continue;
     const plan3 = await installer.plan(svc.dir);
-    if (isEmptyPlan(plan3)) continue;
+    if (isEmptyPlan(plan3) && !plan3.libOnly) continue;
     sections.push({ installer: installer.name, plan: plan3 });
   }
   return sections;
@@ -7084,14 +7364,28 @@ async function runInit(opts) {
   }
   if (!opts.noInstall) {
     if (opts.apply) {
+      let instrumented = 0;
+      let alreadyInstrumented = 0;
+      let libOnly = 0;
       for (const section of sections) {
         const installer = INSTALLERS.find((i) => i.name === section.installer);
         if (!installer) continue;
-        await installer.apply(section.plan);
+        const outcome = await installer.apply(section.plan);
+        if (outcome.outcome === "instrumented") {
+          instrumented++;
+          for (const f of outcome.writtenFiles) written.push(f);
+        } else if (outcome.outcome === "already-instrumented") {
+          alreadyInstrumented++;
+        } else if (outcome.outcome === "lib-only") {
+          libOnly++;
+        }
       }
       if (sections.length > 0) {
         console.log("");
-        console.log("patch applied. Run `npm install` (or your language equivalent) to refresh lockfiles.");
+        console.log(
+          `apply: instrumented ${instrumented}, already-instrumented ${alreadyInstrumented}, lib-only ${libOnly}`
+        );
+        console.log("Run `npm install` (or your language equivalent) to refresh lockfiles.");
       }
     } else {
       await import_node_fs25.promises.writeFile(patchPath, patch, "utf8");
@@ -7483,10 +7777,10 @@ async function runQueryVerb(cmd, parsed) {
         const parts = parsed.type.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
         const out = [];
         for (const p of parts) {
-          const r = import_types23.DivergenceTypeSchema.safeParse(p);
+          const r = import_types24.DivergenceTypeSchema.safeParse(p);
           if (!r.success) {
             console.error(
-              `neat divergences: unknown --type "${p}". allowed: ${import_types23.DivergenceTypeSchema.options.join(", ")}`
+              `neat divergences: unknown --type "${p}". allowed: ${import_types24.DivergenceTypeSchema.options.join(", ")}`
             );
             return 2;
           }