@documentation-robotics/cli 0.1.13 → 0.3.0

package/dist/mcp/tools/model-validate.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { getAllLayerIds, isValidLayer } from "../../generated/layer-registry.js";
+import { CLIError, ErrorCategory, findSimilar, formatValidOptions } from "../../utils/errors.js";
+import { ValidationFormatter } from "../../validators/validation-formatter.js";
+import { Validator } from "../../validators/validator.js";
+import { jsonResult, loadModel, rootPathSchema, runTool } from "./shared.js";
+const inputSchema = {
+  layers: z.array(z.string()).optional().describe("Restrict validation to these layers. Omit to validate the whole model."),
+  strict: z.boolean().optional().describe("Also flag elements with no description as warnings."),
+  orphans: z.boolean().optional().describe("Return only the orphaned-elements report instead of running full validation."),
+  rootPath: rootPathSchema
+};
+async function modelValidateHandler(args) {
+  return runTool(async () => {
+    const model = await loadModel(args.rootPath), activeChangesetId = model.getActiveChangesetId();
+    let modelToValidate = activeChangesetId ? { ...await model.getVirtualProjectionEngine().projectModel(model, activeChangesetId), rootPath: model.rootPath } : model;
+    if (args.layers && args.layers.length > 0) {
+      const unknownLayers = args.layers.filter((name) => !isValidLayer(name));
+      if (unknownLayers.length > 0) {
+        const validLayers = getAllLayerIds(), suggestions = [`Use a valid layer name: ${formatValidOptions(validLayers)}`];
+        for (const unknown of unknownLayers) {
+          const similar = findSimilar(unknown, validLayers, 3);
+          similar.length > 0 && suggestions.unshift(`Did you mean "${similar.join(" or ")}" instead of "${unknown}"?`);
+        }
+        throw new CLIError(`Unknown layer(s): ${unknownLayers.join(", ")}`, ErrorCategory.USER, suggestions);
+      }
+      const requestedLayers = new Set(args.layers);
+      modelToValidate = {
+        ...modelToValidate,
+        layers: new Map(Array.from(modelToValidate.layers.entries()).filter(([name]) => requestedLayers.has(name)))
+      };
+    }
+    if (args.orphans) {
+      const stats2 = ValidationFormatter.calculateStats(modelToValidate);
+      return jsonResult({
+        orphanCount: stats2.orphanedElements.length,
+        orphanedElements: stats2.orphanedElements
+      });
+    }
+    const result = await new Validator().validateModel(modelToValidate), stats = ValidationFormatter.calculateStats(modelToValidate);
+    for (const orphanId of stats.orphanedElements)
+      result.addWarning({
+        message: `Element '${orphanId}' is orphaned (no cross-layer references or intra-layer relationships)`,
+        layer: orphanId.split(".")[0] ?? "",
+        elementId: orphanId,
+        category: "orphan",
+        fixSuggestion: "Add cross-layer references or relationships to connect this element to the rest of the model"
+      });
+    for (const [layerName, layer] of modelToValidate.layers)
+      for (const element of layer.listElements()) {
+        const elementId = element.path || element.id;
+        element.source_reference || result.addWarning({
+          message: `Element '${elementId}' has no source reference`,
+          layer: layerName,
+          elementId,
+          fixSuggestion: "Add a source_reference with provenance to link this element to its implementation"
+        }), args.strict && (!element.description || element.description.trim() === "") && result.addWarning({
+          message: `Element '${elementId}' has no description`,
+          layer: layerName,
+          elementId,
+          fixSuggestion: "Add a description to document what this element represents"
+        });
+      }
+    const formatted = ValidationFormatter.toJSON(result, modelToValidate), valid = result.isValid() && !(args.strict && result.warnings.length > 0);
+    return jsonResult({ ...formatted, valid });
+  });
+}
+const modelValidateTool = {
+  name: "model_validate",
+  description: "Run the full schema/naming/reference/semantic/relationship validation pipeline against the model.",
+  inputSchema,
+  handler: modelValidateHandler
+};
+export {
+  modelValidateHandler,
+  modelValidateTool
+};
+//# sourceMappingURL=model-validate.js.map

package/dist/mcp/tools/model-validate.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/mcp/tools/model-validate.ts"],
+  "sourcesContent": ["/**\n * model_validate \u2014 run the 5-stage validation pipeline against the model.\n * Mirrors `dr validate`, reusing the shared Validator and ValidationFormatter.\n */\n\nimport { z } from \"zod\";\nimport type { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\";\nimport type { Model } from \"../../core/model.js\";\nimport { getAllLayerIds, isValidLayer } from \"../../generated/layer-registry.js\";\nimport { CLIError, ErrorCategory, findSimilar, formatValidOptions } from \"../../utils/errors.js\";\nimport { ValidationFormatter } from \"../../validators/validation-formatter.js\";\nimport { Validator } from \"../../validators/validator.js\";\nimport { jsonResult, loadModel, rootPathSchema, runTool, type McpToolDefinition } from \"./shared.js\";\n\nconst inputSchema = {\n  layers: z.array(z.string()).optional().describe(\"Restrict validation to these layers. Omit to validate the whole model.\"),\n  strict: z.boolean().optional().describe(\"Also flag elements with no description as warnings.\"),\n  orphans: z\n    .boolean()\n    .optional()\n    .describe(\"Return only the orphaned-elements report instead of running full validation.\"),\n  rootPath: rootPathSchema,\n};\n\nexport type ModelValidateArgs = z.infer<z.ZodObject<typeof inputSchema>>;\n\nexport async function modelValidateHandler(args: ModelValidateArgs): Promise<CallToolResult> {\n  return runTool(async () => {\n    const model = await loadModel(args.rootPath);\n\n    // `Validator` is typed to accept `Model`, but a projected changeset is a\n    // `ProjectedModel` (manifest/layers/relationships only, no `rootPath` or the\n    // mutation methods `Model` exposes). The validation pipeline only reads\n    // `rootPath` for telemetry (validator.ts), so it's carried over explicitly\n    // rather than left undefined. This mirrors the identical cast in\n    // `cli/src/commands/validate.ts`; a proper fix would give `Validator` a\n    // narrower \"validatable model\" interface shared by both types.\n    const activeChangesetId = model.getActiveChangesetId();\n    let modelToValidate = (\n      activeChangesetId\n        ? { ...(await model.getVirtualProjectionEngine().projectModel(model, activeChangesetId)), rootPath: model.rootPath }\n        : model\n    ) as unknown as Model;\n\n    // `loadModel()` returns the full cached model (all layers), so a `layers` scope\n    // is applied here rather than at load time. Copies the layers Map onto a new\n    // object instead of mutating `model.layers` directly, since that Map is the\n    // shared cached instance other tool calls read from.\n    if (args.layers && args.layers.length > 0) {\n      const unknownLayers = args.layers.filter((name) => !isValidLayer(name));\n      if (unknownLayers.length > 0) {\n        const validLayers = getAllLayerIds();\n        const suggestions: string[] = [`Use a valid layer name: ${formatValidOptions(validLayers)}`];\n        for (const unknown of unknownLayers) {\n          const similar = findSimilar(unknown, validLayers, 3);\n          if (similar.length > 0) suggestions.unshift(`Did you mean \"${similar.join(\" or \")}\" instead of \"${unknown}\"?`);\n        }\n        throw new CLIError(`Unknown layer(s): ${unknownLayers.join(\", \")}`, ErrorCategory.USER, suggestions);\n      }\n\n      const requestedLayers = new Set(args.layers);\n      modelToValidate = {\n        ...modelToValidate,\n        layers: new Map(\n          Array.from(modelToValidate.layers.entries()).filter(([name]) => requestedLayers.has(name))\n        ),\n      } as unknown as Model;\n    }\n\n    if (args.orphans) {\n      const stats = ValidationFormatter.calculateStats(modelToValidate);\n      return jsonResult({\n        orphanCount: stats.orphanedElements.length,\n        orphanedElements: stats.orphanedElements,\n      });\n    }\n\n    const validator = new Validator();\n    const result = await validator.validateModel(modelToValidate);\n\n    const stats = ValidationFormatter.calculateStats(modelToValidate);\n    for (const orphanId of stats.orphanedElements) {\n      result.addWarning({\n        message: `Element '${orphanId}' is orphaned (no cross-layer references or intra-layer relationships)`,\n        layer: orphanId.split(\".\")[0] ?? \"\",\n        elementId: orphanId,\n        category: \"orphan\",\n        fixSuggestion: \"Add cross-layer references or relationships to connect this element to the rest of the model\",\n      });\n    }\n\n    for (const [layerName, layer] of modelToValidate.layers) {\n      for (const element of layer.listElements()) {\n        const elementId = element.path || element.id;\n        if (!element.source_reference) {\n          result.addWarning({\n            message: `Element '${elementId}' has no source reference`,\n            layer: layerName,\n            elementId,\n            fixSuggestion: \"Add a source_reference with provenance to link this element to its implementation\",\n          });\n        }\n        if (args.strict && (!element.description || element.description.trim() === \"\")) {\n          result.addWarning({\n            message: `Element '${elementId}' has no description`,\n            layer: layerName,\n            elementId,\n            fixSuggestion: \"Add a description to document what this element represents\",\n          });\n        }\n      }\n    }\n\n    const formatted = ValidationFormatter.toJSON(result, modelToValidate);\n    const valid = result.isValid() && !(args.strict && result.warnings.length > 0);\n\n    return jsonResult({ ...formatted, valid });\n  });\n}\n\nexport const modelValidateTool: McpToolDefinition<typeof inputSchema> = {\n  name: \"model_validate\",\n  description: \"Run the full schema/naming/reference/semantic/relationship validation pipeline against the model.\",\n  inputSchema,\n  handler: modelValidateHandler,\n};\n"],
+  "mappings": "AAKA,SAAS,SAAS;AAGlB,SAAS,gBAAgB,oBAAoB;AAC7C,SAAS,UAAU,eAAe,aAAa,0BAA0B;AACzE,SAAS,2BAA2B;AACpC,SAAS,iBAAiB;AAC1B,SAAS,YAAY,WAAW,gBAAgB,eAAuC;AAEvF,MAAM,cAAc;EAClB,QAAQ,EAAE,MAAM,EAAE,OAAM,CAAE,EAAE,SAAQ,EAAG,SAAS,wEAAwE;EACxH,QAAQ,EAAE,QAAO,EAAG,SAAQ,EAAG,SAAS,qDAAqD;EAC7F,SAAS,EACN,QAAO,EACP,SAAQ,EACR,SAAS,8EAA8E;EAC1F,UAAU;;AAKZ,eAAsB,qBAAqB,MAAuB;AAChE,SAAO,QAAQ,YAAW;AACxB,UAAM,QAAQ,MAAM,UAAU,KAAK,QAAQ,GASrC,oBAAoB,MAAM,qBAAoB;AACpD,QAAI,kBACF,oBACI,EAAE,GAAI,MAAM,MAAM,2BAA0B,EAAG,aAAa,OAAO,iBAAiB,GAAI,UAAU,MAAM,SAAQ,IAChH;AAON,QAAI,KAAK,UAAU,KAAK,OAAO,SAAS,GAAG;AACzC,YAAM,gBAAgB,KAAK,OAAO,OAAO,CAAC,SAAS,CAAC,aAAa,IAAI,CAAC;AACtE,UAAI,cAAc,SAAS,GAAG;AAC5B,cAAM,cAAc,eAAc,GAC5B,cAAwB,CAAC,2BAA2B,mBAAmB,WAAW,CAAC,EAAE;AAC3F,mBAAW,WAAW,eAAe;AACnC,gBAAM,UAAU,YAAY,SAAS,aAAa,CAAC;AACnD,UAAI,QAAQ,SAAS,KAAG,YAAY,QAAQ,iBAAiB,QAAQ,KAAK,MAAM,CAAC,iBAAiB,OAAO,IAAI;QAC/G;AACA,cAAM,IAAI,SAAS,qBAAqB,cAAc,KAAK,IAAI,CAAC,IAAI,cAAc,MAAM,WAAW;MACrG;AAEA,YAAM,kBAAkB,IAAI,IAAI,KAAK,MAAM;AAC3C,wBAAkB;QAChB,GAAG;QACH,QAAQ,IAAI,IACV,MAAM,KAAK,gBAAgB,OAAO,QAAO,CAAE,EAAE,OAAO,CAAC,CAAC,IAAI,MAAM,gBAAgB,IAAI,IAAI,CAAC,CAAC;;IAGhG;AAEA,QAAI,KAAK,SAAS;AAChB,YAAMA,SAAQ,oBAAoB,eAAe,eAAe;AAChE,aAAO,WAAW;QAChB,aAAaA,OAAM,iBAAiB;QACpC,kBAAkBA,OAAM;OACzB;IACH;AAGA,UAAM,SAAS,MADG,IAAI,UAAS,EACA,cAAc,eAAe,GAEtD,QAAQ,oBAAoB,eAAe,eAAe;AAChE,eAAW,YAAY,MAAM;AAC3B,aAAO,WAAW;QAChB,SAAS,YAAY,QAAQ;QAC7B,OAAO,SAAS,MAAM,GAAG,EAAE,CAAC,KAAK;QACjC,WAAW;QACX,UAAU;QACV,eAAe;OAChB;AAGH,eAAW,CAAC,WAAW,KAAK,KAAK,gBAAgB;AAC/C,iBAAW,WAAW,MAAM,aAAY,GAAI;AAC1C,cAAM,YAAY,QAAQ,QAAQ,QAAQ;AAC1C,QAAK,QAAQ,oBACX,OAAO,WAAW;UAChB,SAAS,YAAY,SAAS;UAC9B,OAAO;UACP;UACA,eAAe;SAChB,GAEC,KAAK,WAAW,CAAC,QAAQ,eAAe,QAAQ,YAAY,KAAI,MAAO,OACzE,OAAO,WAAW;UAChB,SAAS,YAAY,SAAS;UAC9B,OAAO;UACP;UACA,eAAe;SAChB;MAEL;AAGF,UAAM,YAAY,oBAAoB,OAAO,QAAQ,eAAe,GAC9D,QAAQ,OAAO,QAAO,KAAM,EAAE,KAAK,UAAU,OAAO,SAAS,SAAS;AAE5E,WAAO,WAAW,EAAE,GAAG,WAAW,MAAK,CAAE;EAC3C,CAAC;AACH;AAEO,MAAM,oBAA2D;EACtE,MAAM;EACN,aAAa;EACb;EACA,SAAS;;",
+  "names": ["stats"]
+}

package/dist/mcp/tools/relationship-tools.js

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { ChangesetGraph } from "../../core/changeset-graph.js";
+import { Element } from "../../core/element.js";
+import { StagingAreaManager } from "../../core/staging-area.js";
+import { liveRelationshipsBetween, stageRelationshipDeletes } from "../../core/relationship-staging.js";
+import { addRelationship, deleteRelationshipHandler } from "../../commands/relationship.js";
+import { CLIError, ErrorCategory } from "../../utils/errors.js";
+import { jsonResult, loadModel, reloadModel, rootPathSchema, runTool } from "./shared.js";
+import { activeStagedChangeset } from "./changeset-shared.js";
+const addInputSchema = {
+  source: z.string().describe("Source element ID (layer.type.name)."),
+  predicate: z.string().describe("Relationship predicate, e.g. 'realizes', 'serves', 'accesses'. Use spec_type to see what the catalog allows."),
+  target: z.string().describe("Target element ID (layer.type.name)."),
+  properties: z.record(z.string(), z.unknown()).optional().describe("Optional relationship properties."),
+  rootPath: rootPathSchema
+};
+async function relationshipAddHandler(args) {
+  return runTool(async () => {
+    const model = await loadModel(args.rootPath), manager = new StagingAreaManager(model.rootPath, model), active = await activeStagedChangeset(manager);
+    if (!active) {
+      const outcome2 = await addRelationship(model, args.source, args.target, args.predicate, args.properties);
+      return jsonResult({
+        status: outcome2,
+        source: args.source,
+        predicate: args.predicate,
+        target: args.target
+      });
+    }
+    const graph = await ChangesetGraph.build(model, active), sourceElement = liveElement(graph, args.source, "Source"), targetElement = liveElement(graph, args.target, "Target"), source = sourceElement.id, target = targetElement.id, triple = { source, predicate: args.predicate, target }, outcome = await addRelationship(model, source, target, args.predicate, args.properties, {
+      source: preResolved(sourceElement),
+      target: preResolved(targetElement)
+    });
+    return outcome !== "duplicate" && await reloadModel(args.rootPath), jsonResult({ status: outcome, changeset: active.name, ...triple });
+  });
+}
+const relationshipAddTool = {
+  name: "relationship_add",
+  description: "Add a relationship between two elements, validated against the relationship catalog. Stages it in the active changeset when there is one (including between elements the changeset itself adds), else writes the model. Status: 'staged' or 'added'; 'duplicate' when the model or the changeset already has it (nothing staged); 'restored' when the changeset had staged its deletion (that deletion is unstaged).",
+  inputSchema: addInputSchema,
+  handler: relationshipAddHandler
+}, deleteInputSchema = {
+  source: z.string().describe("Source element ID."),
+  target: z.string().describe("Target element ID."),
+  predicate: z.string().optional().describe("Only this predicate. Omit to remove every relationship from source to target."),
+  rootPath: rootPathSchema
+};
+async function relationshipDeleteHandler(args) {
+  return runTool(async () => {
+    const model = await loadModel(args.rootPath), manager = new StagingAreaManager(model.rootPath, model), active = await activeStagedChangeset(manager);
+    if (!active) {
+      const { deletedCount } = await deleteRelationshipHandler(model, args.source, args.target, args.predicate, void 0, "mcp");
+      return jsonResult({ status: "deleted", deletedCount, source: args.source, target: args.target });
+    }
+    const graph = await ChangesetGraph.build(model, active), source = graph.resolve(args.source), target = graph.resolve(args.target), matches = liveRelationshipsBetween(graph, source, target, args.predicate);
+    if (matches.length === 0)
+      throw new CLIError("No matching relationships found", ErrorCategory.USER, [
+        `Use "model_show" on ${args.source} to see its relationships`,
+        'Use "changeset_brief" to see what this changeset already stages'
+      ]);
+    const results = await stageRelationshipDeletes(manager, graph, active, matches);
+    return await reloadModel(args.rootPath), jsonResult({ changeset: active.name, source, target, relationships: results });
+  });
+}
+const relationshipDeleteTool = {
+  name: "relationship_delete",
+  description: "Remove relationships from source to target. In an active changeset, stages the removal, or unstages the relationship if this changeset added it; else writes the model.",
+  inputSchema: deleteInputSchema,
+  handler: relationshipDeleteHandler
+};
+function liveElement(graph, id, role) {
+  const element = graph.getElement(id);
+  if (!element || element.status === "deleted")
+    throw new CLIError(`${role} element ${id} not found${element ? " (this changeset deletes it)" : ""}`, ErrorCategory.USER, ['Use "model_search" to find elements, or "changeset_brief" to see what this changeset adds']);
+  return element;
+}
+function preResolved(element) {
+  return {
+    layerName: element.layer,
+    element: new Element({
+      id: element.uuid ?? element.id,
+      path: element.id,
+      spec_node_id: `${element.layer}.${element.type}`,
+      layer_id: element.layer,
+      type: element.type,
+      name: element.name,
+      description: element.description,
+      attributes: element.attributes,
+      layer: element.layer
+    })
+  };
+}
+export {
+  relationshipAddHandler,
+  relationshipAddTool,
+  relationshipDeleteHandler,
+  relationshipDeleteTool
+};
+//# sourceMappingURL=relationship-tools.js.map

package/dist/mcp/tools/relationship-tools.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/mcp/tools/relationship-tools.ts"],
+  "sourcesContent": ["/**\n * relationship_add, relationship_delete \u2014 stage (or write) relationships. Mirror\n * `dr relationship add|delete`, validated against the relationship catalog.\n *\n * Inside an active changeset both tools read the changeset's projected graph, so they work between\n * elements that exist only in the changeset, report a repeated add as a duplicate rather than\n * staging it twice, and undo instead of stacking: deleting a relationship this changeset added\n * unstages the add, and re-adding one it deleted unstages the delete. The projected-graph logic is\n * shared with the CLI (`cli/src/core/relationship-staging.ts`).\n */\n\nimport { z } from \"zod\";\nimport type { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\";\nimport { ChangesetGraph, type GraphElement } from \"../../core/changeset-graph.js\";\nimport { Element } from \"../../core/element.js\";\nimport { StagingAreaManager } from \"../../core/staging-area.js\";\nimport { liveRelationshipsBetween, stageRelationshipDeletes } from \"../../core/relationship-staging.js\";\nimport { addRelationship, deleteRelationshipHandler } from \"../../commands/relationship.js\";\nimport { CLIError, ErrorCategory } from \"../../utils/errors.js\";\nimport { jsonResult, loadModel, reloadModel, rootPathSchema, runTool, type McpToolDefinition } from \"./shared.js\";\nimport { activeStagedChangeset } from \"./changeset-shared.js\";\n\n// ---------------------------------------------------------------------------\n// relationship_add\n// ---------------------------------------------------------------------------\n\nconst addInputSchema = {\n  source: z.string().describe(\"Source element ID (layer.type.name).\"),\n  predicate: z\n    .string()\n    .describe(\"Relationship predicate, e.g. 'realizes', 'serves', 'accesses'. Use spec_type to see what the catalog allows.\"),\n  target: z.string().describe(\"Target element ID (layer.type.name).\"),\n  properties: z.record(z.string(), z.unknown()).optional().describe(\"Optional relationship properties.\"),\n  rootPath: rootPathSchema,\n};\n\nexport type RelationshipAddArgs = z.infer<z.ZodObject<typeof addInputSchema>>;\n\nexport async function relationshipAddHandler(args: RelationshipAddArgs): Promise<CallToolResult> {\n  return runTool(async () => {\n    const model = await loadModel(args.rootPath);\n    const manager = new StagingAreaManager(model.rootPath, model);\n    const active = await activeStagedChangeset(manager);\n\n    if (!active) {\n      const outcome = await addRelationship(model, args.source, args.target, args.predicate, args.properties);\n      return jsonResult({\n        status: outcome,\n        source: args.source,\n        predicate: args.predicate,\n        target: args.target,\n      });\n    }\n\n    // Resolve the ends in the projection first, for a clear error when the changeset deletes one.\n    const graph = await ChangesetGraph.build(model, active);\n    const sourceElement = liveElement(graph, args.source, \"Source\");\n    const targetElement = liveElement(graph, args.target, \"Target\");\n    const source = sourceElement.id;\n    const target = targetElement.id;\n    const triple = { source, predicate: args.predicate, target };\n\n    // Hand addRelationship the projection's resolution: its own lookup reads the cached model's\n    // layers, which need not know a layer only this changeset adds elements to.\n    const outcome = await addRelationship(model, source, target, args.predicate, args.properties, {\n      source: preResolved(sourceElement),\n      target: preResolved(targetElement),\n    });\n    // Model.load merges the active changeset's relationships into model.relationships, and other tools\n    // (model_validate, model_export, model_delete's cascade) read that merged view: reload after any staging.\n    if (outcome !== \"duplicate\") {\n      await reloadModel(args.rootPath);\n    }\n    return jsonResult({ status: outcome, changeset: active.name, ...triple });\n  });\n}\n\nexport const relationshipAddTool: McpToolDefinition<typeof addInputSchema> = {\n  name: \"relationship_add\",\n  description:\n    \"Add a relationship between two elements, validated against the relationship catalog. Stages it in the \" +\n    \"active changeset when there is one (including between elements the changeset itself adds), else writes the model. \" +\n    \"Status: 'staged' or 'added'; 'duplicate' when the model or the changeset already has it (nothing staged); \" +\n    \"'restored' when the changeset had staged its deletion (that deletion is unstaged).\",\n  inputSchema: addInputSchema,\n  handler: relationshipAddHandler,\n};\n\n// ---------------------------------------------------------------------------\n// relationship_delete\n// ---------------------------------------------------------------------------\n\nconst deleteInputSchema = {\n  source: z.string().describe(\"Source element ID.\"),\n  target: z.string().describe(\"Target element ID.\"),\n  predicate: z.string().optional().describe(\"Only this predicate. Omit to remove every relationship from source to target.\"),\n  rootPath: rootPathSchema,\n};\n\nexport type RelationshipDeleteArgs = z.infer<z.ZodObject<typeof deleteInputSchema>>;\n\nexport async function relationshipDeleteHandler(args: RelationshipDeleteArgs): Promise<CallToolResult> {\n  return runTool(async () => {\n    const model = await loadModel(args.rootPath);\n    const manager = new StagingAreaManager(model.rootPath, model);\n    const active = await activeStagedChangeset(manager);\n\n    if (!active) {\n      const { deletedCount } = await deleteRelationshipHandler(\n        model,\n        args.source,\n        args.target,\n        args.predicate,\n        undefined,\n        \"mcp\"\n      );\n      return jsonResult({ status: \"deleted\", deletedCount, source: args.source, target: args.target });\n    }\n\n    const graph = await ChangesetGraph.build(model, active);\n    const source = graph.resolve(args.source);\n    const target = graph.resolve(args.target);\n    const matches = liveRelationshipsBetween(graph, source, target, args.predicate);\n\n    if (matches.length === 0) {\n      throw new CLIError(\"No matching relationships found\", ErrorCategory.USER, [\n        `Use \"model_show\" on ${args.source} to see its relationships`,\n        'Use \"changeset_brief\" to see what this changeset already stages',\n      ]);\n    }\n\n    const results = await stageRelationshipDeletes(manager, graph, active, matches);\n    // Staged or unstaged, the cached model's merged relationships are now stale.\n    await reloadModel(args.rootPath);\n    return jsonResult({ changeset: active.name, source, target, relationships: results });\n  });\n}\n\nexport const relationshipDeleteTool: McpToolDefinition<typeof deleteInputSchema> = {\n  name: \"relationship_delete\",\n  description:\n    \"Remove relationships from source to target. In an active changeset, stages the removal, or unstages the \" +\n    \"relationship if this changeset added it; else writes the model.\",\n  inputSchema: deleteInputSchema,\n  handler: relationshipDeleteHandler,\n};\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\nfunction liveElement(graph: ChangesetGraph, id: string, role: \"Source\" | \"Target\"): GraphElement {\n  const element = graph.getElement(id);\n  if (!element || element.status === \"deleted\") {\n    throw new CLIError(\n      `${role} element ${id} not found${element ? \" (this changeset deletes it)\" : \"\"}`,\n      ErrorCategory.USER,\n      ['Use \"model_search\" to find elements, or \"changeset_brief\" to see what this changeset adds']\n    );\n  }\n  return element;\n}\n\n/** A projected element in the shape addRelationship's catalog check reads. */\nfunction preResolved(element: GraphElement): { element: Element; layerName: string } {\n  return {\n    layerName: element.layer,\n    element: new Element({\n      id: element.uuid ?? element.id,\n      path: element.id,\n      spec_node_id: `${element.layer}.${element.type}`,\n      layer_id: element.layer,\n      type: element.type,\n      name: element.name,\n      description: element.description,\n      attributes: element.attributes,\n      layer: element.layer,\n    }),\n  };\n}\n"],
+  "mappings": "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",
+  "names": ["outcome"]
+}

package/dist/mcp/tools/shared.js

@@ -0,0 +1,126 @@
+import { z } from "zod";
+import { Model } from "../../core/model.js";
+import { CLIError, ModelNotFoundError, getErrorMessage } from "../../utils/errors.js";
+import { ChangesetOnlyError } from "../../core/changeset-only-guard.js";
+import { changesetOnlyError } from "../changeset-only.js";
+const rootPathSchema = z.string().optional().describe("Absolute path to the project root containing documentation-robotics/. Defaults to the MCP server's working directory."), modelCache = /* @__PURE__ */ new Map();
+function modelCacheKey(rootPath) {
+  return rootPath ?? "";
+}
+function clearModelCache() {
+  modelCache.clear();
+}
+async function readModelFromDisk(rootPath) {
+  try {
+    return await Model.load(rootPath, { lazyLoad: !1 });
+  } catch (error) {
+    if (error instanceof CLIError)
+      throw error;
+    const message = getErrorMessage(error).toLowerCase();
+    throw message.includes("no dr project") || message.includes("model not found") || message.includes("no model found") ? new ModelNotFoundError(rootPath) : error;
+  }
+}
+async function loadModel(rootPath) {
+  const key = modelCacheKey(rootPath), cached = modelCache.get(key);
+  if (cached)
+    return cached;
+  const promise = readModelFromDisk(rootPath);
+  return modelCache.set(key, promise), evictOnFailure(key, promise), promise;
+}
+async function reloadModel(rootPath) {
+  const key = modelCacheKey(rootPath), promise = readModelFromDisk(rootPath);
+  return modelCache.set(key, promise), evictOnFailure(key, promise), promise;
+}
+function evictOnFailure(key, promise) {
+  promise.catch(() => {
+    modelCache.get(key) === promise && modelCache.delete(key);
+  });
+}
+function jsonResult(data, options) {
+  return {
+    content: [{ type: "text", text: options?.compact ? compactJson(data) : JSON.stringify(data, null, 2) }],
+    ...options?.isError ? { isError: !0 } : {}
+  };
+}
+const COMPACT_LINE = 140;
+function compactJson(data) {
+  const write = (raw, indent) => {
+    const value = raw !== null && typeof raw == "object" && typeof raw.toJSON == "function" ? raw.toJSON() : raw, inline = JSON.stringify(value);
+    if (inline === void 0 || value === null || typeof value != "object" || inline.length + indent.length <= COMPACT_LINE)
+      return inline;
+    const inner = indent + "  ";
+    return Array.isArray(value) ? `[
+${value.map((item) => inner + (write(item, inner) ?? "null")).join(`,
+`)}
+${indent}]` : `{
+${Object.entries(value).map(([key, item]) => {
+      const text = write(item, inner);
+      return text === void 0 ? void 0 : `${inner}${JSON.stringify(key)}: ${text}`;
+    }).filter((line) => line !== void 0).join(`,
+`)}
+${indent}}`;
+  };
+  return write(data, "") ?? "null";
+}
+function errorResult(error) {
+  if (error instanceof CLIError) {
+    const context = error.context;
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: error.message,
+            category: errorCategoryName(error.exitCode),
+            suggestions: error.suggestions ?? [],
+            ...context?.operation ? { operation: context.operation } : {},
+            ...context?.relatedElements ? { relatedElements: context.relatedElements } : {},
+            ...context?.partialProgress ? { partialProgress: context.partialProgress } : {}
+          }, null, 2)
+        }
+      ],
+      isError: !0
+    };
+  }
+  return {
+    content: [{ type: "text", text: JSON.stringify({ error: getErrorMessage(error) }, null, 2) }],
+    isError: !0
+  };
+}
+function errorCategoryName(exitCode) {
+  switch (exitCode) {
+    case 1:
+      return "user";
+    case 2:
+      return "not_found";
+    case 3:
+      return "system";
+    case 4:
+      return "validation";
+    case 5:
+      return "breaking_change";
+    default:
+      return "unknown";
+  }
+}
+async function runTool(fn) {
+  try {
+    return await fn();
+  } catch (error) {
+    return logToolError(error), error instanceof ChangesetOnlyError ? (clearModelCache(), errorResult(changesetOnlyError())) : errorResult(error);
+  }
+}
+function logToolError(error) {
+  error instanceof CLIError ? console.error(`[mcp] tool error: ${error.message}`) : error instanceof Error ? console.error(`[mcp] tool error: ${error.stack ?? error.message}`) : console.error(`[mcp] tool error: ${getErrorMessage(error)}`);
+}
+export {
+  clearModelCache,
+  compactJson,
+  errorResult,
+  jsonResult,
+  loadModel,
+  reloadModel,
+  rootPathSchema,
+  runTool
+};
+//# sourceMappingURL=shared.js.map

package/dist/mcp/tools/shared.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/mcp/tools/shared.ts"],
+  "sourcesContent": ["/**\n * Shared helpers for MCP model tool handlers.\n *\n * Centralizes model loading and the CLIError -> structured error content\n * translation so individual tool handlers stay focused on their own domain\n * logic.\n */\n\nimport { z, type ZodRawShape } from \"zod\";\nimport type { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\";\nimport { Model } from \"../../core/model.js\";\nimport {\n  CLIError,\n  ModelNotFoundError,\n  getErrorMessage,\n  type ErrorContext,\n} from \"../../utils/errors.js\";\nimport { ChangesetOnlyError } from \"../../core/changeset-only-guard.js\";\nimport { changesetOnlyError } from \"../changeset-only.js\";\n\n/** Shared input field: lets a client point at a model outside the server's cwd. */\nexport const rootPathSchema = z\n  .string()\n  .optional()\n  .describe(\n    \"Absolute path to the project root containing documentation-robotics/. Defaults to the MCP server's working directory.\"\n  );\n\nexport interface McpToolDefinition<Shape extends ZodRawShape = ZodRawShape> {\n  name: string;\n  description: string;\n  inputSchema: Shape;\n  // Method-shorthand (not an arrow-typed property) so tool definitions with\n  // differently-shaped Args can share the heterogeneous MODEL_TOOLS array in\n  // tool-registry.ts without a manual cast back to `any` at the storage site.\n  handler(args: z.infer<z.ZodObject<Shape>>): Promise<CallToolResult>;\n}\n\n/**\n * Per-rootPath cache of the loaded architecture model, held for the lifetime of the\n * MCP server process: the Model is loaded once and reused across tool calls rather\n * than reread from disk on every invocation. Keyed by the raw `rootPath` argument\n * (`\"\"` for the server's default cwd), matching how MCP clients address a model\n * across calls.\n */\nconst modelCache = new Map<string, Promise<Model>>();\n\nfunction modelCacheKey(rootPath?: string): string {\n  return rootPath ?? \"\";\n}\n\n/** Test-only escape hatch: clears the module-private model cache between test cases. */\nexport function clearModelCache(): void {\n  modelCache.clear();\n}\n\n/** Reads the model fresh from disk, translating \"no model found\" into a CLIError consistently. */\nasync function readModelFromDisk(rootPath?: string): Promise<Model> {\n  try {\n    // Always a full, non-lazy load: the cached instance must be able to answer any\n    // tool call regardless of which layers/options the first caller happened to need.\n    return await Model.load(rootPath, { lazyLoad: false });\n  } catch (error) {\n    if (error instanceof CLIError) {\n      throw error;\n    }\n    const message = getErrorMessage(error).toLowerCase();\n    if (\n      message.includes(\"no dr project\") ||\n      message.includes(\"model not found\") ||\n      message.includes(\"no model found\")\n    ) {\n      throw new ModelNotFoundError(rootPath);\n    }\n    throw error;\n  }\n}\n\n/** Returns the cached model for this rootPath, loading it from disk on first use. */\nexport async function loadModel(rootPath?: string): Promise<Model> {\n  const key = modelCacheKey(rootPath);\n  const cached = modelCache.get(key);\n  if (cached) {\n    return cached;\n  }\n\n  const promise = readModelFromDisk(rootPath);\n  modelCache.set(key, promise);\n  evictOnFailure(key, promise);\n  return promise;\n}\n\n/** Forces a fresh read from disk, replacing any cached instance for this rootPath. */\nexport async function reloadModel(rootPath?: string): Promise<Model> {\n  const key = modelCacheKey(rootPath);\n  const promise = readModelFromDisk(rootPath);\n  modelCache.set(key, promise);\n  evictOnFailure(key, promise);\n  return promise;\n}\n\n/**\n * Don't let a failed load poison the cache for subsequent (possibly-fixed) calls.\n * Guarded by identity: if a newer promise has since replaced this one for `key`\n * (e.g. a concurrent reloadModel()), a stale rejection must not evict it.\n */\nfunction evictOnFailure(key: string, promise: Promise<Model>): void {\n  promise.catch(() => {\n    if (modelCache.get(key) === promise) {\n      modelCache.delete(key);\n    }\n  });\n}\n\n/**\n * Wraps structured data as the tool's JSON text content. `compact` keeps the indentation of the\n * outer structure but writes any object or array that fits on a line on one line (the same JSON,\n * a fraction of the lines), for large results such as the brief.\n */\nexport function jsonResult(data: unknown, options?: { isError?: boolean; compact?: boolean }): CallToolResult {\n  return {\n    content: [{ type: \"text\", text: options?.compact ? compactJson(data) : JSON.stringify(data, null, 2) }],\n    ...(options?.isError ? { isError: true } : {}),\n  };\n}\n\nconst COMPACT_LINE = 140;\n\n/** JSON indented by two spaces, with every object or array whose one-line form is short kept on one line. */\nexport function compactJson(data: unknown): string {\n  const write = (raw: unknown, indent: string): string | undefined => {\n    const value =\n      raw !== null && typeof raw === \"object\" && typeof (raw as { toJSON?: unknown }).toJSON === \"function\"\n        ? (raw as { toJSON: () => unknown }).toJSON()\n        : raw;\n    const inline = JSON.stringify(value);\n    if (inline === undefined || value === null || typeof value !== \"object\") return inline;\n    if (inline.length + indent.length <= COMPACT_LINE) return inline;\n    const inner = indent + \"  \";\n    if (Array.isArray(value)) {\n      const items = value.map((item) => inner + (write(item, inner) ?? \"null\"));\n      return `[\\n${items.join(\",\\n\")}\\n${indent}]`;\n    }\n    const fields = Object.entries(value as Record<string, unknown>)\n      .map(([key, item]) => {\n        const text = write(item, inner);\n        return text === undefined ? undefined : `${inner}${JSON.stringify(key)}: ${text}`;\n      })\n      .filter((line): line is string => line !== undefined);\n    return `{\\n${fields.join(\",\\n\")}\\n${indent}}`;\n  };\n  return write(data, \"\") ?? \"null\";\n}\n\n/** Converts a thrown error into a structured, non-throwing tool error result. */\nexport function errorResult(error: unknown): CallToolResult {\n  if (error instanceof CLIError) {\n    const context: ErrorContext | undefined = error.context;\n    return {\n      content: [\n        {\n          type: \"text\",\n          text: JSON.stringify(\n            {\n              error: error.message,\n              category: errorCategoryName(error.exitCode),\n              suggestions: error.suggestions ?? [],\n              ...(context?.operation ? { operation: context.operation } : {}),\n              ...(context?.relatedElements ? { relatedElements: context.relatedElements } : {}),\n              ...(context?.partialProgress ? { partialProgress: context.partialProgress } : {}),\n            },\n            null,\n            2\n          ),\n        },\n      ],\n      isError: true,\n    };\n  }\n\n  return {\n    content: [{ type: \"text\", text: JSON.stringify({ error: getErrorMessage(error) }, null, 2) }],\n    isError: true,\n  };\n}\n\nfunction errorCategoryName(exitCode: number): string {\n  switch (exitCode) {\n    case 1:\n      return \"user\";\n    case 2:\n      return \"not_found\";\n    case 3:\n      return \"system\";\n    case 4:\n      return \"validation\";\n    case 5:\n      return \"breaking_change\";\n    default:\n      return \"unknown\";\n  }\n}\n\n/** Runs a tool handler body, catching any error into a structured tool result instead of throwing. */\nexport async function runTool(fn: () => Promise<CallToolResult>): Promise<CallToolResult> {\n  try {\n    return await fn();\n  } catch (error) {\n    logToolError(error);\n    if (error instanceof ChangesetOnlyError) {\n      // A base-model save was refused (DR_CHANGESET_ONLY) after the handler may already have\n      // edited the cached model in memory: drop the cache so the next call rereads disk, and\n      // answer in MCP terms (changeset_create) rather than CLI ones.\n      clearModelCache();\n      return errorResult(changesetOnlyError());\n    }\n    return errorResult(error);\n  }\n}\n\n/**\n * Logs a tool failure to stderr unconditionally (independent of telemetry\n * settings, which are off by default) so server operators have visibility\n * into failures. Non-CLIError exceptions include their stack trace, since\n * that's otherwise discarded once errorResult() reduces them to a message.\n */\nfunction logToolError(error: unknown): void {\n  if (error instanceof CLIError) {\n    console.error(`[mcp] tool error: ${error.message}`);\n  } else if (error instanceof Error) {\n    console.error(`[mcp] tool error: ${error.stack ?? error.message}`);\n  } else {\n    console.error(`[mcp] tool error: ${getErrorMessage(error)}`);\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/mcp/tools/spec-type.js

@@ -0,0 +1,90 @@
+import { z } from "zod";
+import { SpecDataLoader } from "../../core/spec-loader.js";
+import { getAllLayerIds, isValidLayer } from "../../generated/layer-registry.js";
+import { getNodeType, getNodeTypesForLayer, isValidNodeType, normalizeNodeType } from "../../generated/node-types.js";
+import { RELATIONSHIPS_BY_DESTINATION, RELATIONSHIPS_BY_SOURCE } from "../../generated/relationship-index.js";
+import { CLIError, ErrorCategory, findSimilar, formatValidOptions } from "../../utils/errors.js";
+import { jsonResult, runTool } from "./shared.js";
+const inputSchema = {
+  layer: z.string().describe("Canonical layer name, e.g. 'api', 'data-model'."),
+  type: z.string().optional().describe("Node type within the layer, e.g. 'operation'. Omit to list the layer's types."),
+  predicate: z.string().optional().describe("Only list relationships with this predicate."),
+  otherLayer: z.string().optional().describe("Only list relationships whose other end is in this layer.")
+};
+let loaderPromise = null;
+function specLoader() {
+  if (!loaderPromise) {
+    const loader = new SpecDataLoader();
+    loaderPromise = loader.load().then(() => loader), loaderPromise.catch(() => {
+      loaderPromise = null;
+    });
+  }
+  return loaderPromise;
+}
+async function specTypeHandler(args) {
+  return runTool(async () => {
+    if (!isValidLayer(args.layer)) {
+      const layers = getAllLayerIds(), similar = findSimilar(args.layer, layers, 3);
+      throw new CLIError(`Unknown layer "${args.layer}"`, ErrorCategory.USER, [
+        ...similar.length > 0 ? [`Did you mean: ${similar.join(" or ")}?`] : [],
+        `Valid layers: ${formatValidOptions(layers)}`
+      ]);
+    }
+    const loader = await specLoader();
+    if (!args.type) {
+      const layer = loader.getLayer(args.layer);
+      return jsonResult({
+        layer: args.layer,
+        description: layer?.description,
+        types: getNodeTypesForLayer(args.layer).map((t) => ({
+          type: t.type,
+          title: t.title,
+          definition: firstSentence(loader.getNodeType(t.specNodeId)?.description),
+          requiredAttributes: t.requiredAttributes
+        }))
+      });
+    }
+    if (!isValidNodeType(args.layer, args.type)) {
+      const names = getNodeTypesForLayer(args.layer).map((t) => t.type), similar = findSimilar(args.type, names, 3);
+      throw new CLIError(`Invalid type "${args.type}" for layer "${args.layer}"`, ErrorCategory.USER, [
+        ...similar.length > 0 ? [`Did you mean: ${similar.join(" or ")}?`] : [],
+        `Valid types for ${args.layer}: ${formatValidOptions(names)}`
+      ]);
+    }
+    const specNodeId = `${args.layer}.${normalizeNodeType(args.layer, args.type)}`, info = getNodeType(specNodeId), spec = loader.getNodeType(specNodeId), keep = (rel, otherEnd) => (!args.predicate || rel.predicate === args.predicate) && (!args.otherLayer || otherEnd.startsWith(`${args.otherLayer}.`)), outgoing = (RELATIONSHIPS_BY_SOURCE.get(specNodeId) ?? []).filter((r) => keep(r, r.destinationSpecNodeId)).map((r) => ({ predicate: r.predicate, target: r.destinationSpecNodeId, ...r.required ? { required: !0 } : {} })), incoming = (RELATIONSHIPS_BY_DESTINATION.get(specNodeId) ?? []).filter((r) => keep(r, r.sourceSpecNodeId)).map((r) => ({ source: r.sourceSpecNodeId, predicate: r.predicate, ...r.required ? { required: !0 } : {} })), attributes = Object.entries(info.attributeConstraints).map(([name, constraint]) => {
+      const c = constraint;
+      return {
+        name,
+        required: info.requiredAttributes.includes(name),
+        ...c.type ? { type: c.type } : {},
+        ...c.enum ? { enum: c.enum } : {},
+        ...c.description ? { description: c.description } : {}
+      };
+    });
+    return jsonResult({
+      specNodeId,
+      title: info.title,
+      definition: spec?.description,
+      attributes,
+      outgoing,
+      incoming
+    });
+  });
+}
+const specTypeTool = {
+  name: "spec_type",
+  description: "Look up a node type in the spec: its definition, attributes (required ones, enum values) and the relationships the catalog allows from and to it. Omit 'type' to list a layer's types. Use before model_add and relationship_add.",
+  inputSchema,
+  handler: specTypeHandler
+};
+function firstSentence(text) {
+  if (!text)
+    return;
+  const match = text.match(/^.*?[.!?](\s|$)/);
+  return (match ? match[0] : text).trim();
+}
+export {
+  specTypeHandler,
+  specTypeTool
+};
+//# sourceMappingURL=spec-type.js.map

package/dist/mcp/tools/spec-type.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/mcp/tools/spec-type.ts"],
+  "sourcesContent": ["/**\n * spec_type \u2014 what the spec says about one node type: its definition, its attributes (required,\n * enums), and every relationship the catalog allows from it and to it.\n *\n * This is the lookup a planner needs before staging an element: model_add fails on a missing\n * required attribute, and relationship_add fails on a triple the catalog does not list.\n */\n\nimport { z } from \"zod\";\nimport type { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\";\nimport { SpecDataLoader } from \"../../core/spec-loader.js\";\nimport { getAllLayerIds, isValidLayer } from \"../../generated/layer-registry.js\";\nimport {\n  getNodeType,\n  getNodeTypesForLayer,\n  isValidNodeType,\n  normalizeNodeType,\n  type SpecNodeId,\n} from \"../../generated/node-types.js\";\nimport { RELATIONSHIPS_BY_DESTINATION, RELATIONSHIPS_BY_SOURCE, type RelationshipSpec } from \"../../generated/relationship-index.js\";\nimport { CLIError, ErrorCategory, findSimilar, formatValidOptions } from \"../../utils/errors.js\";\nimport { jsonResult, runTool, type McpToolDefinition } from \"./shared.js\";\n\nconst inputSchema = {\n  layer: z.string().describe(\"Canonical layer name, e.g. 'api', 'data-model'.\"),\n  type: z\n    .string()\n    .optional()\n    .describe(\"Node type within the layer, e.g. 'operation'. Omit to list the layer's types.\"),\n  predicate: z.string().optional().describe(\"Only list relationships with this predicate.\"),\n  otherLayer: z.string().optional().describe(\"Only list relationships whose other end is in this layer.\"),\n};\n\nexport type SpecTypeArgs = z.infer<z.ZodObject<typeof inputSchema>>;\n\nlet loaderPromise: Promise<SpecDataLoader> | null = null;\nfunction specLoader(): Promise<SpecDataLoader> {\n  if (!loaderPromise) {\n    const loader = new SpecDataLoader();\n    loaderPromise = loader.load().then(() => loader);\n    loaderPromise.catch(() => {\n      loaderPromise = null;\n    });\n  }\n  return loaderPromise;\n}\n\nexport async function specTypeHandler(args: SpecTypeArgs): Promise<CallToolResult> {\n  return runTool(async () => {\n    if (!isValidLayer(args.layer)) {\n      const layers = getAllLayerIds();\n      const similar = findSimilar(args.layer, layers, 3);\n      throw new CLIError(`Unknown layer \"${args.layer}\"`, ErrorCategory.USER, [\n        ...(similar.length > 0 ? [`Did you mean: ${similar.join(\" or \")}?`] : []),\n        `Valid layers: ${formatValidOptions(layers)}`,\n      ]);\n    }\n\n    const loader = await specLoader();\n\n    if (!args.type) {\n      const layer = loader.getLayer(args.layer);\n      return jsonResult({\n        layer: args.layer,\n        description: layer?.description,\n        types: getNodeTypesForLayer(args.layer).map((t) => ({\n          type: t.type,\n          title: t.title,\n          definition: firstSentence(loader.getNodeType(t.specNodeId)?.description),\n          requiredAttributes: t.requiredAttributes,\n        })),\n      });\n    }\n\n    if (!isValidNodeType(args.layer, args.type)) {\n      const names = getNodeTypesForLayer(args.layer).map((t) => t.type);\n      const similar = findSimilar(args.type, names, 3);\n      throw new CLIError(`Invalid type \"${args.type}\" for layer \"${args.layer}\"`, ErrorCategory.USER, [\n        ...(similar.length > 0 ? [`Did you mean: ${similar.join(\" or \")}?`] : []),\n        `Valid types for ${args.layer}: ${formatValidOptions(names)}`,\n      ]);\n    }\n\n    const specNodeId = `${args.layer}.${normalizeNodeType(args.layer, args.type)}` as SpecNodeId;\n    const info = getNodeType(specNodeId)!;\n    const spec = loader.getNodeType(specNodeId);\n\n    const keep = (rel: RelationshipSpec, otherEnd: string) =>\n      (!args.predicate || rel.predicate === args.predicate) &&\n      (!args.otherLayer || otherEnd.startsWith(`${args.otherLayer}.`));\n\n    const outgoing = (RELATIONSHIPS_BY_SOURCE.get(specNodeId) ?? [])\n      .filter((r) => keep(r, r.destinationSpecNodeId))\n      .map((r) => ({ predicate: r.predicate, target: r.destinationSpecNodeId, ...(r.required ? { required: true } : {}) }));\n    const incoming = (RELATIONSHIPS_BY_DESTINATION.get(specNodeId) ?? [])\n      .filter((r) => keep(r, r.sourceSpecNodeId))\n      .map((r) => ({ source: r.sourceSpecNodeId, predicate: r.predicate, ...(r.required ? { required: true } : {}) }));\n\n    const attributes = Object.entries(info.attributeConstraints).map(([name, constraint]) => {\n      const c = constraint as Record<string, unknown>;\n      return {\n        name,\n        required: info.requiredAttributes.includes(name),\n        ...(c.type ? { type: c.type } : {}),\n        ...(c.enum ? { enum: c.enum } : {}),\n        ...(c.description ? { description: c.description } : {}),\n      };\n    });\n\n    return jsonResult({\n      specNodeId,\n      title: info.title,\n      definition: spec?.description,\n      attributes,\n      outgoing,\n      incoming,\n    });\n  });\n}\n\nexport const specTypeTool: McpToolDefinition<typeof inputSchema> = {\n  name: \"spec_type\",\n  description:\n    \"Look up a node type in the spec: its definition, attributes (required ones, enum values) and the relationships \" +\n    \"the catalog allows from and to it. Omit 'type' to list a layer's types. Use before model_add and relationship_add.\",\n  inputSchema,\n  handler: specTypeHandler,\n};\n\nfunction firstSentence(text: string | undefined): string | undefined {\n  if (!text) return undefined;\n  const match = text.match(/^.*?[.!?](\\s|$)/);\n  return (match ? match[0] : text).trim();\n}\n"],
+  "mappings": "AAQA,SAAS,SAAS;AAElB,SAAS,sBAAsB;AAC/B,SAAS,gBAAgB,oBAAoB;AAC7C,SACE,aACA,sBACA,iBACA,yBAEK;AACP,SAAS,8BAA8B,+BAAsD;AAC7F,SAAS,UAAU,eAAe,aAAa,0BAA0B;AACzE,SAAS,YAAY,eAAuC;AAE5D,MAAM,cAAc;EAClB,OAAO,EAAE,OAAM,EAAG,SAAS,iDAAiD;EAC5E,MAAM,EACH,OAAM,EACN,SAAQ,EACR,SAAS,+EAA+E;EAC3F,WAAW,EAAE,OAAM,EAAG,SAAQ,EAAG,SAAS,8CAA8C;EACxF,YAAY,EAAE,OAAM,EAAG,SAAQ,EAAG,SAAS,2DAA2D;;AAKxG,IAAI,gBAAgD;AACpD,SAAS,aAAU;AACjB,MAAI,CAAC,eAAe;AAClB,UAAM,SAAS,IAAI,eAAc;AACjC,oBAAgB,OAAO,KAAI,EAAG,KAAK,MAAM,MAAM,GAC/C,cAAc,MAAM,MAAK;AACvB,sBAAgB;IAClB,CAAC;EACH;AACA,SAAO;AACT;AAEA,eAAsB,gBAAgB,MAAkB;AACtD,SAAO,QAAQ,YAAW;AACxB,QAAI,CAAC,aAAa,KAAK,KAAK,GAAG;AAC7B,YAAM,SAAS,eAAc,GACvB,UAAU,YAAY,KAAK,OAAO,QAAQ,CAAC;AACjD,YAAM,IAAI,SAAS,kBAAkB,KAAK,KAAK,KAAK,cAAc,MAAM;QACtE,GAAI,QAAQ,SAAS,IAAI,CAAC,iBAAiB,QAAQ,KAAK,MAAM,CAAC,GAAG,IAAI,CAAA;QACtE,iBAAiB,mBAAmB,MAAM,CAAC;OAC5C;IACH;AAEA,UAAM,SAAS,MAAM,WAAU;AAE/B,QAAI,CAAC,KAAK,MAAM;AACd,YAAM,QAAQ,OAAO,SAAS,KAAK,KAAK;AACxC,aAAO,WAAW;QAChB,OAAO,KAAK;QACZ,aAAa,OAAO;QACpB,OAAO,qBAAqB,KAAK,KAAK,EAAE,IAAI,CAAC,OAAO;UAClD,MAAM,EAAE;UACR,OAAO,EAAE;UACT,YAAY,cAAc,OAAO,YAAY,EAAE,UAAU,GAAG,WAAW;UACvE,oBAAoB,EAAE;UACtB;OACH;IACH;AAEA,QAAI,CAAC,gBAAgB,KAAK,OAAO,KAAK,IAAI,GAAG;AAC3C,YAAM,QAAQ,qBAAqB,KAAK,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,GAC1D,UAAU,YAAY,KAAK,MAAM,OAAO,CAAC;AAC/C,YAAM,IAAI,SAAS,iBAAiB,KAAK,IAAI,gBAAgB,KAAK,KAAK,KAAK,cAAc,MAAM;QAC9F,GAAI,QAAQ,SAAS,IAAI,CAAC,iBAAiB,QAAQ,KAAK,MAAM,CAAC,GAAG,IAAI,CAAA;QACtE,mBAAmB,KAAK,KAAK,KAAK,mBAAmB,KAAK,CAAC;OAC5D;IACH;AAEA,UAAM,aAAa,GAAG,KAAK,KAAK,IAAI,kBAAkB,KAAK,OAAO,KAAK,IAAI,CAAC,IACtE,OAAO,YAAY,UAAU,GAC7B,OAAO,OAAO,YAAY,UAAU,GAEpC,OAAO,CAAC,KAAuB,cAClC,CAAC,KAAK,aAAa,IAAI,cAAc,KAAK,eAC1C,CAAC,KAAK,cAAc,SAAS,WAAW,GAAG,KAAK,UAAU,GAAG,IAE1D,YAAY,wBAAwB,IAAI,UAAU,KAAK,CAAA,GAC1D,OAAO,CAAC,MAAM,KAAK,GAAG,EAAE,qBAAqB,CAAC,EAC9C,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,WAAW,QAAQ,EAAE,uBAAuB,GAAI,EAAE,WAAW,EAAE,UAAU,GAAI,IAAK,CAAA,EAAG,EAAG,GAChH,YAAY,6BAA6B,IAAI,UAAU,KAAK,CAAA,GAC/D,OAAO,CAAC,MAAM,KAAK,GAAG,EAAE,gBAAgB,CAAC,EACzC,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,kBAAkB,WAAW,EAAE,WAAW,GAAI,EAAE,WAAW,EAAE,UAAU,GAAI,IAAK,CAAA,EAAG,EAAG,GAE3G,aAAa,OAAO,QAAQ,KAAK,oBAAoB,EAAE,IAAI,CAAC,CAAC,MAAM,UAAU,MAAK;AACtF,YAAM,IAAI;AACV,aAAO;QACL;QACA,UAAU,KAAK,mBAAmB,SAAS,IAAI;QAC/C,GAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAI,IAAK,CAAA;QAChC,GAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAI,IAAK,CAAA;QAChC,GAAI,EAAE,cAAc,EAAE,aAAa,EAAE,YAAW,IAAK,CAAA;;IAEzD,CAAC;AAED,WAAO,WAAW;MAChB;MACA,OAAO,KAAK;MACZ,YAAY,MAAM;MAClB;MACA;MACA;KACD;EACH,CAAC;AACH;AAEO,MAAM,eAAsD;EACjE,MAAM;EACN,aACE;EAEF;EACA,SAAS;;AAGX,SAAS,cAAc,MAAwB;AAC7C,MAAI,CAAC;AAAM;AACX,QAAM,QAAQ,KAAK,MAAM,iBAAiB;AAC1C,UAAQ,QAAQ,MAAM,CAAC,IAAI,MAAM,KAAI;AACvC;",
+  "names": []
+}

package/dist/reports/model-layer-report-generator.js

@@ -5,6 +5,7 @@ import { createAnchor } from "../utils/markdown-anchor.js";
 import { escapeMarkdown, getLayerDescription, valueToMarkdown } from "../export/markdown-utils.js";
 import { getLayerOrder, CANONICAL_LAYER_NAMES } from "../core/layers.js";
 import { getValidRelationships } from "../generated/relationship-index.js";
+import { getLayerReportFileName } from "./model-report-utils.js";
 class ModelLayerReportGenerator {
   modelVersion;
   generatedAt;
@@ -22,6 +23,8 @@ class ModelLayerReportGenerator {
     const lines = [];
     return lines.push(`# ${formatLayerName(data.layerName)}
 `), lines.push(`
+`), lines.push(`[\u2190 Back to README](../README.md)
+`), lines.push(`
 `), lines.push(`${getLayerDescription(data.layerName)}
 `), lines.push(`
 `), lines.join("");
@@ -245,10 +248,9 @@ class ModelLayerReportGenerator {
    * Create a markdown link to a layer report
    */
   createLayerLink(layerName) {
-    const layerNumber = getLayerOrder(layerName);
-    if (layerNumber === -1)
+    if (getLayerOrder(layerName) === -1)
       return layerName;
-    const filename = `./${String(layerNumber).padStart(2, "0")}-${layerName}-layer-report.md`;
+    const filename = `./${getLayerReportFileName(layerName)}`;
     return `[${formatLayerName(layerName)}](${filename})`;
   }
   /**