npm - @kaddo/cli - Versions diffs - 3.77.0 → 3.78.0 - Mend

@kaddo/cli 3.77.0 → 3.78.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/dist/admin-dist/assets/{index-D0l52rub.js → index-Y7S2WW1U.js} +2 -2
package/dist/admin-dist/index.html +1 -1
package/dist/admin-server/index.js +26 -2
package/dist/core.js +211 -2
package/package.json +1 -1

package/dist/admin-dist/index.html CHANGED Viewed

@@ -5,7 +5,7 @@
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>admin</title>
-    <script type="module" crossorigin src="/assets/index-D0l52rub.js"></script>
+    <script type="module" crossorigin src="/assets/index-Y7S2WW1U.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-BPQdYfAp.css">
   </head>
   <body>

package/dist/admin-server/index.js CHANGED Viewed

@@ -69,6 +69,7 @@ import {
   getWorkItemCaptureDefinition as coreGetCaptureDefinition,
   buildRefinementHandoff as coreBuildRefinementHandoff,
   getSystemMapProjection as coreGetSystemMapProjection,
+  buildTopologyEnrichmentHandoff as coreBuildTopologyHandoff,
   WorkItemWriteError,
   exists,
   join,
@@ -139,6 +140,11 @@ function getCaptureDefinition() {
 function getSystemMap(dir) {
   return coreGetSystemMapProjection(dir);
 }
+function getTopologyHandoff(dir) {
+  const config = loadConfig(dir);
+  if (!config) throw new CoreError("PROJECT_NOT_FOUND", "No Kaddo project was found.");
+  return coreBuildTopologyHandoff(dir, config.project.name ?? "this project");
+}
 function getRefinementHandoff(dir, workItemId) {
   assertValidWorkItemId(workItemId);
   try {
@@ -590,7 +596,12 @@ var SystemMapNodeSchema = z.object({
   path: z.string().optional(),
   workItemRef: z.string().optional(),
   knowledgeRef: z.object({ id: z.string(), layer: z.string() }).optional(),
-  moduleId: z.string().optional()
+  moduleId: z.string().optional(),
+  purpose: z.string().optional(),
+  implementationRefs: z.array(z.string()).optional(),
+  knowledgeRefs: z.array(z.object({ id: z.string(), layer: z.string() })).optional(),
+  provenance: z.string().optional(),
+  evidence: z.array(z.string()).optional()
 });
 var SystemMapRelationshipSchema = z.object({
   id: z.string(),
@@ -618,9 +629,20 @@ var SystemMapProjectionSchema = z.object({
     coverage: z.enum(["good", "partial", "sparse", "empty"]),
     available: z.boolean(),
     dimensions: z.object({ system: z.number(), knowledge: z.number(), delivery: z.number(), implementation: z.number(), unknown: z.number() }),
-    topologyAvailable: z.boolean()
+    topologyAvailable: z.boolean(),
+    topologyStatus: z.enum(["unavailable", "partial", "available"]),
+    semanticEntityCount: z.number(),
+    technicalRelationshipCount: z.number(),
+    topologyFindings: z.array(z.object({ level: z.enum(["blocking", "warning"]), message: z.string() }))
   })
 });
+var TopologyEnrichmentHandoffSchema = z.object({
+  projectName: z.string(),
+  recommendedAgent: z.string(),
+  recommendedSkill: z.string(),
+  targetFile: z.string(),
+  text: z.string()
+});
 var ErrorResponseSchema = z.object({
   error: z.object({
     code: z.string(),
@@ -782,6 +804,7 @@ async function createAdminServer(opts) {
   app.get("/api/v1/admin/route", coreRoute(getProjectRoute));
   app.get("/api/v1/admin/findings", coreRoute(getFindings));
   app.get("/api/v1/admin/system", coreRoute(getSystemMap));
+  app.get("/api/v1/admin/system/topology-handoff", coreRoute(getTopologyHandoff));
   app.get("/api/v1/admin/knowledge/inventory", coreRoute(getKnowledgeInventory));
   app.get("/api/v1/admin/knowledge/artifact/:artifactId", async (request) => {
     try {
@@ -940,6 +963,7 @@ export {
   SystemMapNodeSchema,
   SystemMapProjectionSchema,
   SystemMapRelationshipSchema,
+  TopologyEnrichmentHandoffSchema,
   ValidationResultSchema,
   WorkItemCreateSchema,
   WorkItemCreateWithAnswersSchema,

package/dist/core.js CHANGED Viewed

@@ -8712,6 +8712,159 @@ function buildRefinementHandoff(dir, workItemId) {
   };
 }
+// src/core/system-topology.ts
+import { parse as parseYaml8 } from "yaml";
+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 path3 = join(dir, TOPOLOGY_FILE);
+  if (!exists(path3)) return { entities: [], relationships: [], findings: [], declared: false };
+  let parsed;
+  try {
+    parsed = parseYaml8(readFile(path3)) ?? {};
+  } catch {
+    return { entities: [], relationships: [], findings: [{ level: "blocking", message: "system-topology.yml could not be parsed." }], declared: true };
+  }
+  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;
+    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 implementation = strList(e.implementation).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;
+    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),
+      ...provenance ? { provenance } : {},
+      evidence: strList(e.evidence).filter(isRelative)
+    });
+  }
+  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 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;
+    }
+    relationships.push({ from, to, type, evidence: strList(r.evidence).filter(isRelative) });
+  }
+  return { entities, relationships, findings, declared: true };
+}
+function validateSystemTopology(dir) {
+  return loadSystemTopology(dir).findings;
+}
+function buildTopologyEnrichmentHandoff(dir, projectName) {
+  const mappedModules = loadMappedModules(dir).map((m) => m.id);
+  const lines = [
+    `Enrich the semantic system topology for the Kaddo project "${projectName}".`,
+    "",
+    "Use the canonical architecture-agent and graph-metadata-review skill (via Kaddo MCP or skills).",
+    "Inspect the actual repository and relevant mapped modules \u2014 do not infer architecture from",
+    "filenames or directory names."
+  ];
+  if (mappedModules.length > 0) {
+    lines.push("", `This is a multirepo project. Inspect the relevant mapped modules (${mappedModules.join(", ")}) before finalizing the topology.`);
+  }
+  lines.push(
+    "",
+    `Write the result to ${TOPOLOGY_FILE} as declared entities and relationships. 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.",
+    "",
+    "Capture evidence-backed technical relationships: contains, calls, depends-on, reads-from,",
+    "writes-to, integrates-with, runs-on. Preserve unknowns when evidence is insufficient.",
+    "",
+    "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 {
+    projectName,
+    recommendedAgent: "architecture-agent",
+    recommendedSkill: "graph-metadata-review",
+    targetFile: TOPOLOGY_FILE,
+    text: lines.join("\n")
+  };
+}
 // src/core/system-map.ts
 function dimensionOf(type) {
   switch (type) {
@@ -8770,7 +8923,20 @@ function emptyProjection(name, structure) {
     nodes: [],
     relationships: [],
     groups: [],
-    metadata: { projectName: name, structure, nodeCount: 0, relationshipCount: 0, coverage: "empty", available: false, dimensions: emptyDimensions(), topologyAvailable: false }
+    metadata: {
+      projectName: name,
+      structure,
+      nodeCount: 0,
+      relationshipCount: 0,
+      coverage: "empty",
+      available: false,
+      dimensions: emptyDimensions(),
+      topologyAvailable: false,
+      topologyStatus: "unavailable",
+      semanticEntityCount: 0,
+      technicalRelationshipCount: 0,
+      topologyFindings: []
+    }
   };
 }
 function getSystemMapProjection(dir) {
@@ -8796,6 +8962,38 @@ function getSystemMapProjection(dir) {
     type: e.type,
     label: EDGE_LABELS[e.type] ?? e.type.replace(/_/g, " ")
   }));
+  const knowledgeById = /* @__PURE__ */ new Map();
+  for (const ref of knowledgeByPath.values()) knowledgeById.set(ref.id, ref);
+  const topology = loadSystemTopology(dir);
+  const existingIds = new Set(nodes.map((n) => n.id));
+  for (const e of topology.entities) {
+    const nodeId = `sys:${e.id}`;
+    const node = {
+      id: nodeId,
+      type: e.kind,
+      label: e.label,
+      dimension: "system",
+      implementationRefs: e.implementationRefs,
+      knowledgeRefs: e.knowledgeRefs.map((k) => knowledgeById.get(k)).filter(Boolean),
+      evidence: e.evidence
+    };
+    if (e.purpose) node.purpose = e.purpose;
+    if (e.moduleId) node.moduleId = e.moduleId;
+    if (e.provenance) node.provenance = e.provenance;
+    nodes.push(node);
+    existingIds.add(nodeId);
+    for (const ref of e.implementationRefs) {
+      const fileId = `file:${ref}`;
+      if (!existingIds.has(fileId)) {
+        nodes.push({ id: fileId, type: "file", label: ref.split("/").pop() || ref, dimension: "implementation", path: ref });
+        existingIds.add(fileId);
+      }
+      relationships.push({ id: `${nodeId}~implemented-by~${fileId}`, source: nodeId, target: fileId, type: "implemented-by", label: "implemented by" });
+    }
+  }
+  for (const r of topology.relationships) {
+    relationships.push({ id: `sys:${r.from}~${r.type}~sys:${r.to}`, source: `sys:${r.from}`, target: `sys:${r.to}`, type: r.type, label: r.type.replace(/-/g, " ") });
+  }
   const usedGroups = new Set(nodes.map((n) => n.moduleId).filter(Boolean));
   const allGroups = [
     { id: "core", label: "core", repositoryId: "core", available: true },
@@ -8805,6 +9003,9 @@ function getSystemMapProjection(dir) {
   const groups = allGroups.filter((g) => usedGroups.has(g.id) || g.available === false);
   const dimensions = emptyDimensions();
   for (const n of nodes) dimensions[n.dimension]++;
+  const semanticEntityCount = topology.entities.length;
+  const technicalRelationshipCount = relationships.filter((r) => TECHNICAL_RELATIONSHIP_TYPES.has(r.type)).length;
+  const topologyStatus = semanticEntityCount === 0 ? "unavailable" : topology.relationships.length > 0 ? "available" : "partial";
   return {
     system: { name: config.project.name },
     nodes,
@@ -8818,7 +9019,11 @@ function getSystemMapProjection(dir) {
       coverage: hints.quality,
       available: nodes.length > 0,
       dimensions,
-      topologyAvailable: dimensions.system > 0
+      topologyAvailable: dimensions.system > 0,
+      topologyStatus,
+      semanticEntityCount,
+      technicalRelationshipCount,
+      topologyFindings: topology.findings
     }
   };
 }
@@ -8858,6 +9063,7 @@ function toNode(n, knowledgeByPath, wiModules, groupIds) {
   return node;
 }
 export {
+  TOPOLOGY_FILE,
   WorkItemNotFoundError,
   WorkItemWriteError,
   analyzeCrossRepoEvidence,
@@ -8866,6 +9072,7 @@ export {
   buildProjectRoute,
   buildReadinessReport,
   buildRefinementHandoff,
+  buildTopologyEnrichmentHandoff,
   computeRefinementStatus,
   createWorkItem,
   cwd,
@@ -8887,8 +9094,10 @@ export {
   lifecycleStateOf,
   loadConfig,
   loadMappedModules,
+  loadSystemTopology,
   readFile,
   transitionWorkItem,
   updateWorkItem,
+  validateSystemTopology,
   validateWorkItem
 };

package/package.json CHANGED Viewed

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