@documentation-robotics/cli 0.2.0 → 0.3.0

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

@@ -1,7 +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\";\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/** Wraps structured data as the tool's JSON text content. */\nexport function jsonResult(data: unknown, options?: { isError?: boolean }): CallToolResult {\n  return {\n    content: [{ type: \"text\", text: JSON.stringify(data, null, 2) }],\n    ...(options?.isError ? { isError: true } : {}),\n  };\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    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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",
+  "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": "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",
+  "names": []
+}