@kaddo/cli 3.78.0 → 3.79.0

package/dist/index.js

@@ -1361,8 +1361,8 @@ function loadConfig(dir) {
   const parsed = configSchema.safeParse(raw ?? {});
   if (!parsed.success) {
     const issues = parsed.error.issues.map((i) => {
-      const path9 = i.path.join(".");
-      return path9 ? `  - ${path9}: ${i.message}` : `  - ${i.message}`;
+      const path10 = i.path.join(".");
+      return path10 ? `  - ${path10}: ${i.message}` : `  - ${i.message}`;
     }).join("\n");
     throw new ConfigError(`Invalid .kaddo/config.yml:
 ${issues}`);
@@ -6732,10 +6732,10 @@ function analyzeGuard(touchedFiles, artifacts, silentWithoutOwnership) {
 import { parse as parseYaml4, stringify as stringifyYaml2 } from "yaml";
 var IGNORE_FILE = ".kaddo/ignores.yml";
 function loadIgnores(dir) {
-  const path9 = join(dir, IGNORE_FILE);
-  if (!exists(path9)) return [];
+  const path10 = join(dir, IGNORE_FILE);
+  if (!exists(path10)) return [];
   try {
-    const raw = readFile(path9);
+    const raw = readFile(path10);
     const parsed = parseYaml4(raw);
     return Array.isArray(parsed) ? parsed : [];
   } catch {
@@ -6743,7 +6743,7 @@ function loadIgnores(dir) {
   }
 }
 function saveIgnore(dir, entry) {
-  const path9 = join(dir, IGNORE_FILE);
+  const path10 = join(dir, IGNORE_FILE);
   const existing = loadIgnores(dir);
   const idx = existing.findIndex((e) => e.artifact_id === entry.artifact_id);
   if (idx >= 0) {
@@ -6751,17 +6751,17 @@ function saveIgnore(dir, entry) {
   } else {
     existing.push(entry);
   }
-  writeFile(path9, stringifyYaml2(existing));
+  writeFile(path10, stringifyYaml2(existing));
 }
 function isIgnored(ignores, artifactId) {
   return ignores.find((e) => e.artifact_id === artifactId);
 }
 function removeIgnore(dir, artifactId) {
-  const path9 = join(dir, IGNORE_FILE);
+  const path10 = join(dir, IGNORE_FILE);
   const existing = loadIgnores(dir);
   const filtered = existing.filter((e) => e.artifact_id !== artifactId);
   if (filtered.length === existing.length) return false;
-  writeFile(path9, stringifyYaml2(filtered));
+  writeFile(path10, stringifyYaml2(filtered));
   return true;
 }
 
@@ -6783,11 +6783,11 @@ function moduleArtifactCoverage(dir, id) {
   };
 }
 function loadMappedModules(dir) {
-  const path9 = join(dir, DESCRIPTOR_PATH);
-  if (!exists(path9)) return [];
+  const path10 = join(dir, DESCRIPTOR_PATH);
+  if (!exists(path10)) return [];
   let parsed;
   try {
-    parsed = parseYaml5(readFile(path9));
+    parsed = parseYaml5(readFile(path10));
   } catch {
     return [];
   }
@@ -7531,7 +7531,7 @@ function buildGuardHistory(dir) {
     const d = hotspotDir(t.code_path);
     hotspotMap.set(d, (hotspotMap.get(d) ?? 0) + 1);
   }
-  const hotspots = [...hotspotMap.entries()].map(([path9, warnings]) => ({ path: path9, warnings })).sort((a, b) => b.warnings - a.warnings);
+  const hotspots = [...hotspotMap.entries()].map(([path10, warnings]) => ({ path: path10, warnings })).sort((a, b) => b.warnings - a.warnings);
   return {
     available: true,
     total_runs: sorted.length,
@@ -10102,10 +10102,10 @@ function slugify2(name) {
   return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function readModulesDescriptor(dir) {
-  const path9 = join(dir, DESCRIPTOR_PATH2);
-  if (!exists(path9)) return { version: 1, modules: [] };
+  const path10 = join(dir, DESCRIPTOR_PATH2);
+  if (!exists(path10)) return { version: 1, modules: [] };
   try {
-    const parsed = parseYaml9(readFile(path9));
+    const parsed = parseYaml9(readFile(path10));
     return { version: parsed.version ?? 1, modules: parsed.modules ?? [] };
   } catch {
     return { version: 1, modules: [] };
@@ -10485,7 +10485,7 @@ function sectionParagraph(md, title) {
   }
   return "";
 }
-function parseCapsule(id, path9, md) {
+function parseCapsule(id, path10, md) {
   const { data } = matter3(md);
   const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
   let ageDays = null;
@@ -10495,7 +10495,7 @@ function parseCapsule(id, path9, md) {
   }
   return {
     id,
-    path: path9,
+    path: path10,
     system: data.system ? String(data.system) : id,
     owner: data.owner ? String(data.owner) : void 0,
     updatedAt,
@@ -10581,9 +10581,9 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   ];
   const presentLayers = [];
   for (const layer2 of layerDocs) {
-    const path9 = layer2.files.map((f) => `${KNOWLEDGE3}/${f}`).find((rel) => exists(join(dir, rel)));
-    if (path9) {
-      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path9 });
+    const path10 = layer2.files.map((f) => `${KNOWLEDGE3}/${f}`).find((rel) => exists(join(dir, rel)));
+    if (path10) {
+      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path10 });
       presentLayers.push(layer2.id);
     }
   }
@@ -12119,10 +12119,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 path9 = agentInstallPath(file);
-    const installed = isFile(join(dir, path9));
+    const path10 = agentInstallPath(file);
+    const installed = isFile(join(dir, path10));
     const group = agentGroupOf(file);
-    return { agentPath: path9, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
+    return { agentPath: path10, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
   };
   const moduleRepo = isModule(config);
   const coreRepo = isCore(config);
@@ -17097,6 +17097,287 @@ function runGraphExport(opts = {}) {
   outro2("Knowledge graph ready.");
 }
 
+// src/core/system-topology.ts
+import { parse as parseYaml16, stringify as stringifyYaml7 } from "yaml";
+import fs3 from "fs";
+import path7 from "path";
+import crypto from "crypto";
+var TOPOLOGY_FILE = "knowledge/tech/system-topology.yml";
+var SYSTEM_ENTITY_KINDS = /* @__PURE__ */ new Set([
+  "system",
+  "application",
+  "service",
+  "component",
+  "api",
+  "interface",
+  "datastore",
+  "queue",
+  "job",
+  "external-system",
+  "module",
+  "unknown"
+]);
+var TECHNICAL_RELATIONSHIP_TYPES = /* @__PURE__ */ new Set([
+  "contains",
+  "depends-on",
+  "calls",
+  "reads-from",
+  "writes-to",
+  "publishes-to",
+  "subscribes-to",
+  "integrates-with",
+  "runs-on",
+  "implemented-by"
+]);
+var PROVENANCE = /* @__PURE__ */ new Set(["declared", "derived", "agent-reviewed"]);
+function isRelative(p2) {
+  return typeof p2 === "string" && p2.trim() !== "" && !/^([a-zA-Z]:[\\/]|\/)/.test(p2) && !p2.includes("..");
+}
+function strList(v) {
+  return Array.isArray(v) ? v.map((x) => typeof x === "string" ? x.trim() : "").filter(Boolean) : [];
+}
+function loadSystemTopology(dir) {
+  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 = parseYaml16(raw) ?? {};
+  } catch {
+    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 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." });
+      continue;
+    }
+    if (seenIds.has(id)) {
+      findings.push({ level: "blocking", message: `Duplicate topology entity id "${id}".` });
+      continue;
+    }
+    const kind = typeof e.kind === "string" ? e.kind.trim() : "unknown";
+    if (!SYSTEM_ENTITY_KINDS.has(kind)) {
+      findings.push({ level: "warning", message: `Entity "${id}" has an unknown kind "${kind}"; treated as unknown.` });
+    }
+    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 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 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,
+      kind: SYSTEM_ENTITY_KINDS.has(kind) ? kind : "unknown",
+      label: typeof e.label === "string" && e.label.trim() ? e.label.trim() : id,
+      ...typeof e.purpose === "string" && e.purpose.trim() ? { purpose: e.purpose.trim() } : {},
+      ...moduleRaw && validModules.has(moduleRaw) ? { moduleId: moduleRaw } : {},
+      implementationRefs: implementation,
+      knowledgeRefs: strList(e.knowledge ?? e.knowledge_refs),
+      ...provenance ? { provenance } : {},
+      evidence
+    });
+  }
+  const entityIds = new Set(entities.map((e) => e.id));
+  const rawRels = Array.isArray(parsed.relationships) ? parsed.relationships : [];
+  const relationships = [];
+  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." });
+      continue;
+    }
+    if (!TECHNICAL_RELATIONSHIP_TYPES.has(type)) {
+      findings.push({ level: "warning", message: `Relationship type "${type}" is not recognized and was skipped.` });
+      continue;
+    }
+    if (!entityIds.has(from) || !entityIds.has(to)) {
+      findings.push({ level: "blocking", message: `Relationship ${from} \u2192 ${to} references an unknown entity endpoint.` });
+      continue;
+    }
+    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, ...sourceRevision ? { sourceRevision } : {} };
+}
+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 crypto.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 stringifyYaml7(doc);
+}
+function atomicWrite(filePath, content) {
+  fs3.mkdirSync(path7.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.");
+  atomicWrite(join(dir, TOPOLOGY_FILE), raw);
+  return { revision: topologyRevision(dir), entitiesNew, entitiesUpdated, relationshipsNew };
+}
+
+// src/commands/topology.ts
+function requireProject(dir) {
+  if (!loadConfig(dir)) {
+    log2.error("No Kaddo project was found in the current directory.");
+    process.exit(1);
+  }
+}
+function readProposal(dir, file) {
+  const abs = join(dir, file);
+  if (!exists(abs) && !exists(file)) {
+    log2.error(`Proposal file not found: ${file}`);
+    process.exit(1);
+  }
+  return readFile(exists(abs) ? abs : file);
+}
+function printFindings(v) {
+  log2.info(`${v.entityCount} entities \xB7 ${v.relationshipCount} relationships`);
+  log2.info(`${v.blocking} blocking \xB7 ${v.warning} warning`);
+  for (const f of v.findings) {
+    const line = `[${f.level}] ${f.message}`;
+    if (f.level === "blocking") log2.error(line);
+    else log2.warn(line);
+  }
+}
+async function runTopologyValidate(file) {
+  const dir = cwd();
+  requireProject(dir);
+  intro2("kaddo topology validate");
+  const proposal = readProposal(dir, file);
+  const v = validateTopologyProposal(dir, proposal);
+  printFindings(v);
+  if (v.canApply) outro2("Proposal is valid. Apply it with `kaddo topology apply`.");
+  else {
+    outro2("Proposal has blocking findings and cannot be applied.");
+    process.exit(1);
+  }
+}
+async function runTopologyApply(file, opts = {}) {
+  const dir = cwd();
+  requireProject(dir);
+  intro2("kaddo topology apply");
+  const proposal = readProposal(dir, file);
+  const v = validateTopologyProposal(dir, proposal);
+  printFindings(v);
+  if (!v.canApply) {
+    cancel2("Cannot apply: the proposal has blocking findings.");
+    process.exit(1);
+  }
+  if (!opts.yes) {
+    const ok = await confirm2({ message: `Apply this topology enrichment to ${join("", "knowledge/tech/system-topology.yml")}? (writes the project artifact; no Git commit is created)` });
+    if (!ok) {
+      cancel2("Apply cancelled.");
+      process.exit(0);
+    }
+  }
+  try {
+    const result = applyTopologyProposal(dir, proposal, topologyRevision(dir));
+    outro2(`Applied. ${result.entitiesNew} new / ${result.entitiesUpdated} updated entities, ${result.relationshipsNew} new relationships.`);
+  } catch (err) {
+    if (err instanceof TopologyWriteError) {
+      cancel2(err.message);
+      process.exit(1);
+    }
+    throw err;
+  }
+}
+
 // src/core/impact-report.ts
 import matter10 from "gray-matter";
 function isBroadGlob(glob) {
@@ -17544,7 +17825,7 @@ function runReportImpact(opts = {}) {
 }
 
 // src/core/savings.ts
-import { parse as parseYaml16 } from "yaml";
+import { parse as parseYaml17 } from "yaml";
 var DEFAULT_ASSUMPTIONS = {
   currency: "USD",
   hourly_cost: 40,
@@ -17562,7 +17843,7 @@ function loadAssumptions(dir) {
   const p2 = join(dir, SAVINGS_PATH);
   if (!exists(p2)) return { assumptions: { ...DEFAULT_ASSUMPTIONS }, source: "default" };
   try {
-    const raw = parseYaml16(readFile(p2));
+    const raw = parseYaml17(readFile(p2));
     const a = raw?.assumptions ?? {};
     const t = raw?.team ?? {};
     const num = (v, d) => typeof v === "number" && Number.isFinite(v) ? v : d;
@@ -18244,7 +18525,7 @@ function runAdr(opts = {}) {
 }
 
 // src/commands/tech.ts
-import fs3 from "fs";
+import fs4 from "fs";
 var DISCOVERY_FILES = ["architecture-notes.md", "decision-candidates.md"];
 var DISCOVERY_DIR = "knowledge/tech/discovery";
 function runTechOrganize(dir = cwd()) {
@@ -18261,7 +18542,7 @@ function runTechOrganize(dir = cwd()) {
       continue;
     }
     ensureDir(join(dir, DISCOVERY_DIR));
-    fs3.renameSync(from, to);
+    fs4.renameSync(from, to);
     moved.push(`knowledge/tech/${file} \u2192 ${DISCOVERY_DIR}/${file}`);
   }
   if (moved.length > 0) {
@@ -18343,8 +18624,8 @@ function runAssetsUpdate(kind, opts = {}) {
 }
 
 // src/commands/ready.ts
-import fs4 from "fs";
-import path7 from "path";
+import fs5 from "fs";
+import path8 from "path";
 import matter11 from "gray-matter";
 function validateReadiness(content, frontmatter) {
   const warnings = [];
@@ -18407,10 +18688,10 @@ function transitionToReady(filePath) {
   const posix = filePath.replace(/\\/g, "/");
   let newPath = filePath;
   if (posix.includes("/work-items/draft/")) {
-    const readyDir = path7.dirname(filePath).replace(/[/\\]draft$/, path7.sep + "ready");
+    const readyDir = path8.dirname(filePath).replace(/[/\\]draft$/, path8.sep + "ready");
     ensureDir(readyDir);
-    const fileName = path7.basename(filePath);
-    newPath = path7.join(readyDir, fileName);
+    const fileName = path8.basename(filePath);
+    newPath = path8.join(readyDir, fileName);
   }
   return { newPath, newContent };
 }
@@ -18478,11 +18759,11 @@ async function runReady(id, opts = {}) {
   const { newPath, newContent } = transitionToReady(wi.filePath);
   if (newPath !== wi.filePath) {
     writeFile(newPath, newContent);
-    fs4.unlinkSync(wi.filePath);
+    fs5.unlinkSync(wi.filePath);
     log2.success(`Updated status: ready`);
     log2.success(`Moved file:`);
-    log2.info(`  ${path7.relative(dir, wi.filePath)}`);
-    log2.info(`  \u2192 ${path7.relative(dir, newPath)}`);
+    log2.info(`  ${path8.relative(dir, wi.filePath)}`);
+    log2.info(`  \u2192 ${path8.relative(dir, newPath)}`);
   } else {
     writeFile(wi.filePath, newContent);
     log2.success(`Updated status: ready`);
@@ -18493,7 +18774,7 @@ async function runReady(id, opts = {}) {
 }
 
 // src/commands/admin.ts
-import path8 from "path";
+import path9 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import net from "net";
 function isPortAvailable(port, host) {
@@ -18508,13 +18789,13 @@ function isPortAvailable(port, host) {
   });
 }
 function resolveStaticDir() {
-  const __dirname = path8.dirname(fileURLToPath2(import.meta.url));
+  const __dirname = path9.dirname(fileURLToPath2(import.meta.url));
   const candidates = [
     // Bundled inside CLI dist (npm install)
-    path8.resolve(__dirname, "admin-dist"),
+    path9.resolve(__dirname, "admin-dist"),
     // Monorepo development
-    path8.resolve(__dirname, "..", "..", "admin", "dist"),
-    path8.resolve(__dirname, "..", "node_modules", "@kaddo", "admin", "dist")
+    path9.resolve(__dirname, "..", "..", "admin", "dist"),
+    path9.resolve(__dirname, "..", "node_modules", "@kaddo", "admin", "dist")
   ];
   for (const c of candidates) {
     if (exists(join(c, "index.html"))) return c;
@@ -18556,8 +18837,8 @@ async function runAdmin(opts = {}) {
   }
   let adminServer;
   try {
-    const __dirname = path8.dirname(fileURLToPath2(import.meta.url));
-    const bundled = path8.resolve(__dirname, "admin-server", "index.js");
+    const __dirname = path9.dirname(fileURLToPath2(import.meta.url));
+    const bundled = path9.resolve(__dirname, "admin-server", "index.js");
     if (exists(bundled)) {
       const { pathToFileURL } = await import("url");
       adminServer = await import(pathToFileURL(bundled).href);
@@ -18636,13 +18917,20 @@ var capsuleCmd = program.command("capsule").description("Export this project as
 capsuleCmd.command("export").description("Write a Knowledge Capsule about this project to .kaddo/exports/").option("--scope <scope>", 'Export scope: "system" includes all mapped modules').option("--module <id>", "Export a capsule for a specific mapped module").action((opts) => {
   runCapsuleExport(opts);
 });
-capsuleCmd.command("add <path>").description("Register an external Knowledge Capsule as project context (.kaddo/external.yml)").action((path9) => {
-  runCapsuleAdd(path9);
+capsuleCmd.command("add <path>").description("Register an external Knowledge Capsule as project context (.kaddo/external.yml)").action((path10) => {
+  runCapsuleAdd(path10);
 });
 var graphCmd = program.command("graph").description("Export the lightweight, file-based knowledge graph of the project");
 graphCmd.command("export").description("Write the knowledge graph to .kaddo/graph.json and .kaddo/graph.mmd").option("--scope <scope>", "Graph scope: active (default) or all").option("--format <format>", "Output format: json, mermaid (default: both)").action((opts) => {
   runGraphExport(opts);
 });
+var topologyCmd = program.command("topology").description("Validate and apply a semantic system topology proposal (agent proposes, human confirms, Core applies)");
+topologyCmd.command("validate <file>").description("Validate a topology proposal file deterministically (no write)").action((file) => {
+  runTopologyValidate(file);
+});
+topologyCmd.command("apply <file>").description("Apply a validated topology proposal to the canonical artifact after human confirmation").option("-y, --yes", "Skip the confirmation prompt (for already-approved automation)").action((file, opts) => {
+  runTopologyApply(file, opts);
+});
 var reportCmd = program.command("report").description("Generate Kaddo reports");
 reportCmd.command("impact").description("Knowledge Impact Report: knowledge health, coverage, traceability, readiness (deterministic, no LLM)").option("--json", "Output JSON instead of Markdown").option("--scope <scope>", "Scope: all (default \u2014 accumulated impact) or active").option("--output <path>", "Write the report to a file (e.g. .kaddo/reports/impact-report.md)").action((opts) => {
   runReportImpact(opts);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaddo/cli",
-  "version": "3.78.0",
+  "version": "3.79.0",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {