@kaddo/cli 3.78.0 → 3.79.0

package/dist/core.js

@@ -116,8 +116,8 @@ function loadConfig(dir) {
   const parsed = configSchema.safeParse(raw ?? {});
   if (!parsed.success) {
     const issues = parsed.error.issues.map((i) => {
-      const path3 = i.path.join(".");
-      return path3 ? `  - ${path3}: ${i.message}` : `  - ${i.message}`;
+      const path4 = i.path.join(".");
+      return path4 ? `  - ${path4}: ${i.message}` : `  - ${i.message}`;
     }).join("\n");
     throw new ConfigError(`Invalid .kaddo/config.yml:
 ${issues}`);
@@ -352,11 +352,11 @@ function moduleArtifactCoverage(dir, id) {
   };
 }
 function loadMappedModules(dir) {
-  const path3 = join(dir, DESCRIPTOR_PATH);
-  if (!exists(path3)) return [];
+  const path4 = join(dir, DESCRIPTOR_PATH);
+  if (!exists(path4)) return [];
   let parsed;
   try {
-    parsed = parseYaml3(readFile(path3));
+    parsed = parseYaml3(readFile(path4));
   } catch {
     return [];
   }
@@ -1590,7 +1590,7 @@ function sectionParagraph(md, title) {
   }
   return "";
 }
-function parseCapsule(id, path3, md) {
+function parseCapsule(id, path4, md) {
   const { data } = matter2(md);
   const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
   let ageDays = null;
@@ -1600,7 +1600,7 @@ function parseCapsule(id, path3, md) {
   }
   return {
     id,
-    path: path3,
+    path: path4,
     system: data.system ? String(data.system) : id,
     owner: data.owner ? String(data.owner) : void 0,
     updatedAt,
@@ -1662,9 +1662,9 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   ];
   const presentLayers = [];
   for (const layer of layerDocs) {
-    const path3 = layer.files.map((f) => `${KNOWLEDGE2}/${f}`).find((rel) => exists(join(dir, rel)));
-    if (path3) {
-      addNode({ id: layer.id, type: layer.type, label: layer.label, path: path3 });
+    const path4 = layer.files.map((f) => `${KNOWLEDGE2}/${f}`).find((rel) => exists(join(dir, rel)));
+    if (path4) {
+      addNode({ id: layer.id, type: layer.type, label: layer.label, path: path4 });
       presentLayers.push(layer.id);
     }
   }
@@ -3060,10 +3060,10 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   const q = (rel) => analyzeKnowledgeArtifact(dir, rel);
   const resolveAgent = (agent) => {
     const file = agent.endsWith(".md") ? agent : `${agent}.md`;
-    const path3 = agentInstallPath(file);
-    const installed = isFile(join(dir, path3));
+    const path4 = agentInstallPath(file);
+    const installed = isFile(join(dir, path4));
     const group = agentGroupOf(file);
-    return { agentPath: path3, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
+    return { agentPath: path4, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
   };
   const moduleRepo = isModule(config);
   const coreRepo = isCore(config);
@@ -8713,7 +8713,10 @@ function buildRefinementHandoff(dir, workItemId) {
 }
 
 // src/core/system-topology.ts
-import { parse as parseYaml8 } from "yaml";
+import { parse as parseYaml8, stringify as stringifyYaml4 } from "yaml";
+import fs3 from "fs";
+import path3 from "path";
+import crypto2 from "crypto";
 var TOPOLOGY_FILE = "knowledge/tech/system-topology.yml";
 var SYSTEM_ENTITY_KINDS = /* @__PURE__ */ new Set([
   "system",
@@ -8749,22 +8752,27 @@ function strList(v) {
   return Array.isArray(v) ? v.map((x) => typeof x === "string" ? x.trim() : "").filter(Boolean) : [];
 }
 function loadSystemTopology(dir) {
-  const path3 = join(dir, TOPOLOGY_FILE);
-  if (!exists(path3)) return { entities: [], relationships: [], findings: [], declared: false };
+  const filePath = join(dir, TOPOLOGY_FILE);
+  if (!exists(filePath)) return { entities: [], relationships: [], findings: [], declared: false };
+  const parsed = parseTopologyContent(readFile(filePath), dir);
+  return { ...parsed, declared: true };
+}
+function parseTopologyContent(raw, dir) {
   let parsed;
   try {
-    parsed = parseYaml8(readFile(path3)) ?? {};
+    parsed = parseYaml8(raw) ?? {};
   } catch {
-    return { entities: [], relationships: [], findings: [{ level: "blocking", message: "system-topology.yml could not be parsed." }], declared: true };
+    return { entities: [], relationships: [], findings: [{ level: "blocking", message: "The topology could not be parsed." }] };
   }
+  const sourceRevision = typeof parsed.source_revision === "string" ? parsed.source_revision : void 0;
   const findings = [];
   const validModules = /* @__PURE__ */ new Set(["core", ...loadMappedModules(dir).map((m) => m.id)]);
   const rawEntities = Array.isArray(parsed.entities) ? parsed.entities : [];
   const entities = [];
   const seenIds = /* @__PURE__ */ new Set();
-  for (const raw of rawEntities) {
-    if (!raw || typeof raw !== "object") continue;
-    const e = raw;
+  for (const raw2 of rawEntities) {
+    if (!raw2 || typeof raw2 !== "object") continue;
+    const e = raw2;
     const id = typeof e.id === "string" ? e.id.trim() : "";
     if (!id) {
       findings.push({ level: "warning", message: "A topology entity is missing an id and was skipped." });
@@ -8780,12 +8788,16 @@ function loadSystemTopology(dir) {
     }
     const moduleRaw = typeof e.module === "string" ? e.module.trim() : void 0;
     if (moduleRaw && !validModules.has(moduleRaw)) findings.push({ level: "warning", message: `Entity "${id}" references unregistered module "${moduleRaw}".` });
-    const implementation = strList(e.implementation).filter((p2) => {
+    const rawImpl = e.implementation ?? e.implementation_refs;
+    const implementation = strList(rawImpl).filter((p2) => {
       if (isRelative(p2)) return true;
       findings.push({ level: "warning", message: `Entity "${id}" implementation ref "${p2}" is not a safe relative path and was dropped.` });
       return false;
     });
-    const provenance = typeof e.provenance === "string" && PROVENANCE.has(e.provenance) ? e.provenance : void 0;
+    const prov = e.provenance;
+    const provOrigin = typeof prov === "string" ? prov : prov && typeof prov === "object" && typeof prov.origin === "string" ? String(prov.origin) : void 0;
+    const provenance = provOrigin && PROVENANCE.has(provOrigin) ? provOrigin : void 0;
+    const evidence = strList(e.evidence ?? (prov && typeof prov === "object" ? prov.evidence_refs : void 0)).filter(isRelative);
     seenIds.add(id);
     entities.push({
       id,
@@ -8794,19 +8806,20 @@ function loadSystemTopology(dir) {
       ...typeof e.purpose === "string" && e.purpose.trim() ? { purpose: e.purpose.trim() } : {},
       ...moduleRaw && validModules.has(moduleRaw) ? { moduleId: moduleRaw } : {},
       implementationRefs: implementation,
-      knowledgeRefs: strList(e.knowledge),
+      knowledgeRefs: strList(e.knowledge ?? e.knowledge_refs),
       ...provenance ? { provenance } : {},
-      evidence: strList(e.evidence).filter(isRelative)
+      evidence
     });
   }
   const entityIds = new Set(entities.map((e) => e.id));
   const rawRels = Array.isArray(parsed.relationships) ? parsed.relationships : [];
   const relationships = [];
-  for (const raw of rawRels) {
-    if (!raw || typeof raw !== "object") continue;
-    const r = raw;
-    const from = typeof r.from === "string" ? r.from.trim() : "";
-    const to = typeof r.to === "string" ? r.to.trim() : "";
+  const seenRels = /* @__PURE__ */ new Set();
+  for (const raw2 of rawRels) {
+    if (!raw2 || typeof raw2 !== "object") continue;
+    const r = raw2;
+    const from = typeof r.from === "string" ? r.from.trim() : typeof r.source === "string" ? r.source.trim() : "";
+    const to = typeof r.to === "string" ? r.to.trim() : typeof r.target === "string" ? r.target.trim() : "";
     const type = typeof r.type === "string" ? r.type.trim() : "";
     if (!from || !to || !type) {
       findings.push({ level: "warning", message: "A topology relationship is missing from/to/type and was skipped." });
@@ -8820,13 +8833,101 @@ function loadSystemTopology(dir) {
       findings.push({ level: "blocking", message: `Relationship ${from} \u2192 ${to} references an unknown entity endpoint.` });
       continue;
     }
-    relationships.push({ from, to, type, evidence: strList(r.evidence).filter(isRelative) });
+    const key = `${from}~${type}~${to}`;
+    if (seenRels.has(key)) {
+      findings.push({ level: "warning", message: `Duplicate relationship ${from} ${type} ${to} was skipped.` });
+      continue;
+    }
+    seenRels.add(key);
+    const prov = r.provenance;
+    relationships.push({ from, to, type, evidence: strList(r.evidence ?? prov?.evidence_refs).filter(isRelative) });
   }
-  return { entities, relationships, findings, declared: true };
+  return { entities, relationships, findings, ...sourceRevision ? { sourceRevision } : {} };
 }
 function validateSystemTopology(dir) {
   return loadSystemTopology(dir).findings;
 }
+var TopologyWriteError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "TopologyWriteError";
+    this.code = code;
+  }
+};
+function topologyRevision(dir) {
+  const filePath = join(dir, TOPOLOGY_FILE);
+  const raw = exists(filePath) ? readFile(filePath) : "";
+  return crypto2.createHash("sha256").update(raw, "utf-8").digest("hex");
+}
+function validateTopologyProposal(dir, proposalYaml) {
+  const { entities, relationships, findings } = parseTopologyContent(proposalYaml, dir);
+  const blocking = findings.filter((f) => f.level === "blocking").length;
+  const warning = findings.filter((f) => f.level === "warning").length;
+  return { findings, blocking, warning, canApply: blocking === 0, entityCount: entities.length, relationshipCount: relationships.length };
+}
+function serializeTopology(entities, relationships) {
+  const doc = {
+    entities: entities.map((e) => ({
+      id: e.id,
+      kind: e.kind,
+      label: e.label,
+      ...e.purpose ? { purpose: e.purpose } : {},
+      ...e.moduleId ? { module: e.moduleId } : {},
+      ...e.implementationRefs.length ? { implementation: e.implementationRefs } : {},
+      ...e.knowledgeRefs.length ? { knowledge: e.knowledgeRefs } : {},
+      ...e.provenance ? { provenance: e.provenance } : {},
+      ...e.evidence.length ? { evidence: e.evidence } : {}
+    })),
+    relationships: relationships.map((r) => ({ from: r.from, to: r.to, type: r.type, ...r.evidence.length ? { evidence: r.evidence } : {} }))
+  };
+  return stringifyYaml4(doc);
+}
+function atomicWrite2(filePath, content) {
+  fs3.mkdirSync(path3.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs3.writeFileSync(tmp, content, "utf-8");
+  try {
+    fs3.renameSync(tmp, filePath);
+  } catch (err) {
+    try {
+      fs3.rmSync(tmp, { force: true });
+    } catch {
+    }
+    throw err;
+  }
+}
+function applyTopologyProposal(dir, proposalYaml, expectedRevision) {
+  const validation = validateTopologyProposal(dir, proposalYaml);
+  if (!validation.canApply) throw new TopologyWriteError("TOPOLOGY_INVALID", "The topology proposal has blocking findings and cannot be applied.");
+  const current = topologyRevision(dir);
+  if (expectedRevision != null && expectedRevision !== current) {
+    throw new TopologyWriteError("TOPOLOGY_CONFLICT", "The topology changed after this proposal was created. Refresh and validate the proposal again.");
+  }
+  const proposal = parseTopologyContent(proposalYaml, dir);
+  const existing = loadSystemTopology(dir);
+  const entityMap = /* @__PURE__ */ new Map();
+  for (const e of existing.entities) entityMap.set(e.id, e);
+  let entitiesNew = 0, entitiesUpdated = 0;
+  for (const e of proposal.entities) {
+    if (entityMap.has(e.id)) entitiesUpdated++;
+    else entitiesNew++;
+    entityMap.set(e.id, e);
+  }
+  const relKey = (r) => `${r.from}~${r.type}~${r.to}`;
+  const relMap = /* @__PURE__ */ new Map();
+  for (const r of existing.relationships) relMap.set(relKey(r), r);
+  let relationshipsNew = 0;
+  for (const r of proposal.relationships) {
+    if (!relMap.has(relKey(r))) relationshipsNew++;
+    relMap.set(relKey(r), r);
+  }
+  const raw = serializeTopology([...entityMap.values()], [...relMap.values()]);
+  const finalCheck = validateTopologyProposal(dir, raw);
+  if (!finalCheck.canApply) throw new TopologyWriteError("TOPOLOGY_INVALID", "The merged topology is invalid; no changes were written.");
+  atomicWrite2(join(dir, TOPOLOGY_FILE), raw);
+  return { revision: topologyRevision(dir), entitiesNew, entitiesUpdated, relationshipsNew };
+}
 function buildTopologyEnrichmentHandoff(dir, projectName) {
   const mappedModules = loadMappedModules(dir).map((m) => m.id);
   const lines = [
@@ -8841,19 +8942,22 @@ function buildTopologyEnrichmentHandoff(dir, projectName) {
   }
   lines.push(
     "",
-    `Write the result to ${TOPOLOGY_FILE} as declared entities and relationships. For each entity`,
+    "Build a topology PROPOSAL first \u2014 do not write canonical metadata directly. For each entity",
     "capture, only when supported by evidence:",
     "- a stable id and semantic kind (application/service/component/api/interface/datastore/queue/job/external-system);",
     "- a responsibility/purpose (what it does, not how);",
     "- the owning module/repository;",
     "- implementation references (relative paths);",
-    "- relevant Knowledge references (capability/ADR ids), not Kaddo operational assets.",
+    "- relevant Knowledge references (capability/ADR ids), not Kaddo operational assets;",
+    "- provenance/evidence.",
     "",
     "Capture evidence-backed technical relationships: contains, calls, depends-on, reads-from,",
-    "writes-to, integrates-with, runs-on. Preserve unknowns when evidence is insufficient.",
+    "writes-to, integrates-with, runs-on. Preserve Unknown when evidence is insufficient.",
+    "",
+    "Validate the proposal through Kaddo before applying it. Do not write canonical topology metadata",
+    `unless (1) Kaddo validation succeeds and (2) the human explicitly confirms the write. The canonical`,
+    `artifact is ${TOPOLOGY_FILE}; Core validates and applies it \u2014 do not hand-edit it.`,
     "",
-    "Review the proposed graph metadata (duplicate ids, dangling relationships, unknown modules,",
-    "invalid references) before writing.",
     "Do not implement application changes. Do not run mutating Git operations."
   );
   return {
@@ -9064,10 +9168,12 @@ function toNode(n, knowledgeByPath, wiModules, groupIds) {
 }
 export {
   TOPOLOGY_FILE,
+  TopologyWriteError,
   WorkItemNotFoundError,
   WorkItemWriteError,
   analyzeCrossRepoEvidence,
   analyzeScopeCoverage,
+  applyTopologyProposal,
   buildProjectExplanation,
   buildProjectRoute,
   buildReadinessReport,
@@ -9096,8 +9202,10 @@ export {
   loadMappedModules,
   loadSystemTopology,
   readFile,
+  topologyRevision,
   transitionWorkItem,
   updateWorkItem,
   validateSystemTopology,
+  validateTopologyProposal,
   validateWorkItem
 };