@documentation-robotics/cli 0.2.0 → 0.4.0

package/dist/commands/mcp.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/commands/mcp.ts"],
-  "sourcesContent": ["/**\n * MCP server command - Starts an MCP server for AI assistant integration\n *\n * Supports two transport modes:\n * - stdio (default): In-process over stdio; stdout carries the MCP JSON-RPC protocol\n * - http: HTTP server with Express, exposing MCP at /mcp endpoint with bearer token auth\n *\n * All non-protocol output goes to stderr.\n */\n\nimport { isCancel, text } from \"@clack/prompts\";\nimport { ApiKeyManager, type ApiKeyStoragePrompt } from \"../mcp/api-key-manager.js\";\nimport { type HttpTransportApp } from \"../mcp/http-transport.js\";\nimport { McpResourceRegistry } from \"../mcp/resource-registry.js\";\nimport { McpToolRegistry } from \"../mcp/tool-registry.js\";\nimport { loadModel } from \"../mcp/tools/shared.js\";\nimport { startActiveSpan } from \"../telemetry/index.js\";\nimport { CLIError, getErrorMessage } from \"../utils/errors.js\";\nimport { getCliVersion } from \"../utils/spec-version.js\";\n\nconst cliVersion = getCliVersion();\n\n/**\n * Prompt the user (via stdout/stdin) for where to store a newly generated API key.\n * Only invoked when stdin is a TTY \u2014 non-interactive launches (e.g. an MCP client\n * spawning `dr mcp`) fall back to the default path without prompting.\n */\nconst promptForKeyPath: ApiKeyStoragePrompt = async (defaultPath) => {\n  const result = await text({\n    message: \"Where should the MCP API key be stored?\",\n    placeholder: defaultPath,\n    defaultValue: defaultPath,\n  });\n\n  if (isCancel(result) || typeof result !== \"string\" || result.trim().length === 0) {\n    return defaultPath;\n  }\n  return result.trim();\n};\n\nasync function createConfiguredServer() {\n  const { McpServer } = await import(\"@modelcontextprotocol/sdk/server/mcp.js\");\n\n  const server = new McpServer({\n    name: \"documentation-robotics\",\n    version: cliVersion,\n  });\n\n  // Register the model tool surface and spec/model manifest resources.\n  new McpToolRegistry().registerAll(server);\n  await new McpResourceRegistry().registerAll(server);\n\n  // Warm the model cache at startup so it's loaded once and held in memory\n  // for the session, rather than waiting for the first tool call. Best-effort:\n  // a server started outside a DR project still starts up cleanly \u2014 the first\n  // tool call that supplies a valid rootPath will load and cache it.\n  try {\n    await loadModel();\n  } catch (error) {\n    process.stderr.write(`[mcp] model warmup skipped: ${getErrorMessage(error)}\\n`);\n  }\n\n  return server;\n}\n\nexport interface McpCommandOptions {\n  /** Force-generate a new API key, overwrite it at the configured storage path, and exit. */\n  regenerateKey?: boolean;\n  /** Transport type: \"stdio\" or \"http\" (default: \"stdio\") */\n  transport?: \"stdio\" | \"http\";\n  /** Port for HTTP transport (default: 3100, only meaningful with --transport http) */\n  port?: number;\n  /** Host address for HTTP transport (default: \"127.0.0.1\", only meaningful with --transport http) */\n  host?: string;\n}\n\nexport async function mcpCommand(options: McpCommandOptions = {}): Promise<void> {\n  const keyManager = new ApiKeyManager();\n\n  try {\n    if (options.regenerateKey) {\n      await startActiveSpan(\"mcp.key.rotate\", async (span) => {\n        const isInteractive = process.stdin.isTTY === true;\n        const { key, path } = await keyManager.rotate(\n          isInteractive ? promptForKeyPath : undefined\n        );\n        span.setAttribute(\"mcp.key.path\", path);\n        process.stderr.write(`Generated new MCP API key, stored at ${path}\\n`);\n        process.stderr.write(`MCP API key: ${key}\\n`);\n      });\n      return;\n    }\n\n    const isInteractive = process.stdin.isTTY === true;\n    const { key, path, isNew } = await keyManager.ensureKey(\n      isInteractive ? promptForKeyPath : undefined\n    );\n\n    if (isNew) {\n      process.stderr.write(`Generated new MCP API key, stored at ${path}\\n`);\n    }\n    // Required every launch: print the API key to stderr (never stdout, which\n    // carries the MCP protocol).\n    process.stderr.write(`MCP API key: ${key}\\n`);\n\n    if (options.transport === \"http\") {\n      // HTTP transport implementation\n      const { createMcpHttpApp, startHttpServer, closeHttpServer } = await import(\n        \"../mcp/http-transport.js\"\n      );\n\n      const host = options.host || \"127.0.0.1\";\n      const port = options.port || 3100;\n\n      let httpApp: HttpTransportApp;\n      const httpServer = await startActiveSpan(\n        \"mcp.server.start\",\n        async (span) => {\n          httpApp = await createMcpHttpApp(keyManager, key, createConfiguredServer, host);\n          const server = await startHttpServer(httpApp, host, port);\n\n          span.setAttribute(\"mcp.server.name\", \"documentation-robotics\");\n          span.setAttribute(\"mcp.server.version\", cliVersion);\n          span.setAttribute(\"mcp.server.transport\", \"http\");\n          span.setAttribute(\"mcp.server.host\", host);\n          span.setAttribute(\"mcp.server.port\", port);\n\n          return server;\n        }\n      );\n\n      // Warn if bound to 0.0.0.0\n      if (host === \"0.0.0.0\") {\n        process.stderr.write(\n          \"Warning: Server bound to 0.0.0.0. DNS rebinding protection is not automatic; ensure your MCP client validates the Host header.\\n\"\n        );\n      }\n\n      process.stderr.write(`Documentation Robotics MCP server ready (http://${host}:${port}/mcp)\\n`);\n\n      // Set up graceful shutdown on SIGINT/SIGTERM\n      let resolveKeepAlive: () => void;\n      const keepAlive = new Promise<void>((resolve) => {\n        resolveKeepAlive = resolve;\n      });\n\n      let isShuttingDown = false;\n      const shutdown = async () => {\n        if (isShuttingDown) {\n          return;\n        }\n        isShuttingDown = true;\n\n        try {\n          process.stderr.write(\"\\nShutting down HTTP server...\\n\");\n          await closeHttpServer(httpServer, httpApp);\n        } catch (error) {\n          const errorMsg = error instanceof Error ? error.message : \"unknown error\";\n          process.stderr.write(`[mcp] Error closing server: ${errorMsg}\\n`);\n        } finally {\n          resolveKeepAlive!();\n        }\n      };\n\n      process.on(\"SIGINT\", shutdown);\n      process.on(\"SIGTERM\", shutdown);\n\n      // Keep the process alive until explicitly terminated\n      await keepAlive;\n    } else {\n      // Stdio transport (default)\n      // Validate that the environment has the correct API key configured\n      if (!keyManager.validate(process.env.DR_MCP_API_KEY, key)) {\n        process.stderr.write(\n          \"Error: DR_MCP_API_KEY environment variable is missing or does not match the stored API key.\\n\"\n        );\n        process.stderr.write(\n          \"Set DR_MCP_API_KEY to the key above when configuring the MCP client, e.g.:\\n\"\n        );\n        process.stderr.write(\n          '  { \"command\": \"dr\", \"args\": [\"mcp\"], \"env\": { \"DR_MCP_API_KEY\": \"<key>\" } }\\n'\n        );\n        throw new CLIError(\"MCP authentication failed: invalid or missing DR_MCP_API_KEY\", 1);\n      }\n\n      const transport = await startActiveSpan(\n        \"mcp.server.start\",\n        async (span) => {\n          const { StdioServerTransport } = await import(\"@modelcontextprotocol/sdk/server/stdio.js\");\n\n          const server = await createConfiguredServer();\n\n          span.setAttribute(\"mcp.server.name\", \"documentation-robotics\");\n          span.setAttribute(\"mcp.server.version\", cliVersion);\n          span.setAttribute(\"mcp.server.transport\", \"stdio\");\n\n          const serverTransport = new StdioServerTransport();\n          await server.connect(serverTransport);\n          return serverTransport;\n        }\n      );\n\n      process.stderr.write(\"Documentation Robotics MCP server ready (stdio)\\n\");\n\n      // Keep the process alive for the lifetime of the stdio session; the\n      // transport closes (and the process exits) when stdin closes. Shutdown\n      // is implicit in the `mcp.server.start` span's end, so no separate\n      // zero-duration \"stop\" span is recorded here.\n      await new Promise<void>((resolve) => {\n        transport.onclose = () => resolve();\n      });\n    }\n  } catch (error) {\n    if (error instanceof CLIError) {\n      throw error;\n    }\n\n    let message = getErrorMessage(error);\n\n    // Handle port-in-use errors with actionable message\n    if (error instanceof Error && (error as NodeJS.ErrnoException).code === \"EADDRINUSE\") {\n      const port = options.port || 3100;\n      message = `Port ${port} is already in use. Try a different port with --port or kill the process using that port.`;\n    }\n\n    process.stderr.write(`Error: ${message}\\n`);\n    throw new CLIError(message, 1);\n  }\n}\n"],
-  "mappings": "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",
-  "names": ["isInteractive", "key", "path"]
+  "sourcesContent": ["/**\n * MCP server command - Starts an MCP server for AI assistant integration\n *\n * Supports two transport modes:\n * - stdio (default): In-process over stdio; stdout carries the MCP JSON-RPC protocol. The client\n *   spawns the server as the same user, so there is no API key: anything that can start\n *   `dr mcp` can already read the model files.\n * - http: HTTP server with Express, exposing MCP at /mcp endpoint with bearer token auth\n *\n * All non-protocol output goes to stderr.\n */\n\nimport { isCancel, text } from \"@clack/prompts\";\nimport type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { RootsListChangedNotificationSchema } from \"@modelcontextprotocol/sdk/types.js\";\nimport { ApiKeyManager, type ApiKeyStoragePrompt } from \"../mcp/api-key-manager.js\";\nimport { type HttpTransportApp } from \"../mcp/http-transport.js\";\nimport { followClientRoots, markEnvProjectRoot } from \"../mcp/project-root.js\";\nimport { McpResourceRegistry } from \"../mcp/resource-registry.js\";\nimport { SERVER_INSTRUCTIONS } from \"../mcp/server-instructions.js\";\nimport { McpToolRegistry } from \"../mcp/tool-registry.js\";\nimport { clearModelCache, loadModel } from \"../mcp/tools/shared.js\";\nimport { startActiveSpan } from \"../telemetry/index.js\";\nimport { CLIError, getErrorMessage } from \"../utils/errors.js\";\nimport { getCliVersion } from \"../utils/spec-version.js\";\n\nconst cliVersion = getCliVersion();\n\n/**\n * Prompt the user (via stdout/stdin) for where to store a newly generated API key.\n * Only invoked when stdin is a TTY \u2014 non-interactive launches (e.g. an MCP client\n * spawning `dr mcp`) fall back to the default path without prompting.\n */\nconst promptForKeyPath: ApiKeyStoragePrompt = async (defaultPath) => {\n  const result = await text({\n    message: \"Where should the MCP API key be stored?\",\n    placeholder: defaultPath,\n    defaultValue: defaultPath,\n  });\n\n  if (isCancel(result) || typeof result !== \"string\" || result.trim().length === 0) {\n    return defaultPath;\n  }\n  return result.trim();\n};\n\nasync function createConfiguredServer(): Promise<McpServer> {\n  const { McpServer } = await import(\"@modelcontextprotocol/sdk/server/mcp.js\");\n\n  const server = new McpServer(\n    { name: \"documentation-robotics\", version: cliVersion },\n    { instructions: SERVER_INSTRUCTIONS }\n  );\n\n  // Register the model tool surface and spec/model manifest resources.\n  new McpToolRegistry().registerAll(server);\n  await new McpResourceRegistry().registerAll(server);\n  return server;\n}\n\n/**\n * Loads the default project's model into the cache so the first tool call doesn't wait for it.\n * Best-effort: a server started outside a DR project still starts cleanly, and the first tool\n * call that supplies a valid rootPath loads and caches that model.\n */\nasync function warmModel(): Promise<void> {\n  try {\n    await loadModel();\n  } catch (error) {\n    process.stderr.write(`[mcp] model warmup skipped: ${getErrorMessage(error)}\\n`);\n  }\n}\n\n/**\n * Serve the project the client has open: once the client has initialized, ask for its roots\n * (mcp/project-root.ts), and ask again whenever it says they changed. A client without roots\n * leaves the server in its working directory.\n */\nfunction serveClientRoots(server: McpServer): void {\n  const inner = server.server;\n  const follow = () =>\n    followClientRoots(() => inner.listRoots(), { onChange: () => clearModelCache() }).then(warmModel);\n\n  inner.setNotificationHandler(RootsListChangedNotificationSchema, async () => {\n    await follow();\n  });\n  inner.oninitialized = () => {\n    if (inner.getClientCapabilities()?.roots) {\n      void follow();\n    } else {\n      void warmModel();\n    }\n  };\n}\n\n/**\n * DR_MCP_ROOT_PATH lets a launcher (DrBot under `dr visualize`) point the server at a model\n * without relying on the cwd its MCP client spawns it in: tools default to this directory, and\n * the client's roots are not consulted. A bad path is reported and the server keeps its own cwd.\n * Returns whether the server now serves from DR_MCP_ROOT_PATH.\n */\nexport function serveFromRootPathEnv(env: NodeJS.ProcessEnv = process.env): boolean {\n  const rootPath = env.DR_MCP_ROOT_PATH;\n  if (!rootPath) return false;\n  try {\n    process.chdir(rootPath);\n  } catch (error) {\n    process.stderr.write(\n      `[mcp] DR_MCP_ROOT_PATH=${rootPath} is not usable (${getErrorMessage(error)}); serving from ${process.cwd()}\\n`\n    );\n    return false;\n  }\n  markEnvProjectRoot(process.cwd());\n  return true;\n}\n\nexport interface McpCommandOptions {\n  /** Force-generate a new API key, overwrite it at the configured storage path, and exit. */\n  regenerateKey?: boolean;\n  /** Transport type: \"stdio\" or \"http\" (default: \"stdio\") */\n  transport?: \"stdio\" | \"http\";\n  /** Port for HTTP transport (default: 3100, only meaningful with --transport http) */\n  port?: number;\n  /** Host address for HTTP transport (default: \"127.0.0.1\", only meaningful with --transport http) */\n  host?: string;\n}\n\nexport async function mcpCommand(options: McpCommandOptions = {}): Promise<void> {\n  const keyManager = new ApiKeyManager();\n\n  try {\n    if (options.regenerateKey) {\n      await startActiveSpan(\"mcp.key.rotate\", async (span) => {\n        const isInteractive = process.stdin.isTTY === true;\n        const { key, path } = await keyManager.rotate(\n          isInteractive ? promptForKeyPath : undefined\n        );\n        span.setAttribute(\"mcp.key.path\", path);\n        process.stderr.write(`Generated new MCP API key, stored at ${path}\\n`);\n        process.stderr.write(`MCP API key: ${key}\\n`);\n      });\n      return;\n    }\n\n    const servesEnvRoot = serveFromRootPathEnv();\n\n    if (options.transport === \"http\") {\n      // HTTP clients authenticate with the API key as a bearer token.\n      const isInteractive = process.stdin.isTTY === true;\n      const { key, path, isNew } = await keyManager.ensureKey(\n        isInteractive ? promptForKeyPath : undefined\n      );\n      if (isNew) {\n        process.stderr.write(`Generated new MCP API key, stored at ${path}\\n`);\n      }\n      // Print the key to stderr so a user can configure a client. DR_MCP_QUIET_KEY keeps it out\n      // of logs for a launcher that already has it.\n      if (!/^(1|true|yes|on)$/i.test(process.env.DR_MCP_QUIET_KEY ?? \"\")) {\n        process.stderr.write(`MCP API key: ${key}\\n`);\n      }\n\n      // One server for every HTTP session, so the project is the env root or the cwd (client\n      // roots are per session and can't move a shared working directory).\n      await warmModel();\n      const { createMcpHttpApp, startHttpServer, closeHttpServer } = await import(\n        \"../mcp/http-transport.js\"\n      );\n\n      const host = options.host || \"127.0.0.1\";\n      const port = options.port || 3100;\n\n      let httpApp: HttpTransportApp;\n      const httpServer = await startActiveSpan(\n        \"mcp.server.start\",\n        async (span) => {\n          httpApp = await createMcpHttpApp(keyManager, key, createConfiguredServer, host);\n          const server = await startHttpServer(httpApp, host, port);\n\n          span.setAttribute(\"mcp.server.name\", \"documentation-robotics\");\n          span.setAttribute(\"mcp.server.version\", cliVersion);\n          span.setAttribute(\"mcp.server.transport\", \"http\");\n          span.setAttribute(\"mcp.server.host\", host);\n          span.setAttribute(\"mcp.server.port\", port);\n\n          return server;\n        }\n      );\n\n      // Warn if bound to 0.0.0.0\n      if (host === \"0.0.0.0\") {\n        process.stderr.write(\n          \"Warning: Server bound to 0.0.0.0. DNS rebinding protection is not automatic; ensure your MCP client validates the Host header.\\n\"\n        );\n      }\n\n      process.stderr.write(`Documentation Robotics MCP server ready (http://${host}:${port}/mcp)\\n`);\n\n      // Set up graceful shutdown on SIGINT/SIGTERM\n      let resolveKeepAlive: () => void;\n      const keepAlive = new Promise<void>((resolve) => {\n        resolveKeepAlive = resolve;\n      });\n\n      let isShuttingDown = false;\n      const shutdown = async () => {\n        if (isShuttingDown) {\n          return;\n        }\n        isShuttingDown = true;\n\n        try {\n          process.stderr.write(\"\\nShutting down HTTP server...\\n\");\n          await closeHttpServer(httpServer, httpApp);\n        } catch (error) {\n          const errorMsg = error instanceof Error ? error.message : \"unknown error\";\n          process.stderr.write(`[mcp] Error closing server: ${errorMsg}\\n`);\n        } finally {\n          resolveKeepAlive!();\n        }\n      };\n\n      process.on(\"SIGINT\", shutdown);\n      process.on(\"SIGTERM\", shutdown);\n\n      // Keep the process alive until explicitly terminated\n      await keepAlive;\n    } else {\n      // Stdio transport (default). No API key: the client spawns this process as its own user.\n      const transport = await startActiveSpan(\n        \"mcp.server.start\",\n        async (span) => {\n          const { StdioServerTransport } = await import(\"@modelcontextprotocol/sdk/server/stdio.js\");\n\n          const server = await createConfiguredServer();\n          if (servesEnvRoot) {\n            await warmModel();\n          } else {\n            serveClientRoots(server);\n          }\n\n          span.setAttribute(\"mcp.server.name\", \"documentation-robotics\");\n          span.setAttribute(\"mcp.server.version\", cliVersion);\n          span.setAttribute(\"mcp.server.transport\", \"stdio\");\n\n          const serverTransport = new StdioServerTransport();\n          await server.connect(serverTransport);\n          return serverTransport;\n        }\n      );\n\n      process.stderr.write(\"Documentation Robotics MCP server ready (stdio)\\n\");\n\n      // Keep the process alive for the lifetime of the stdio session; the\n      // transport closes (and the process exits) when stdin closes. Shutdown\n      // is implicit in the `mcp.server.start` span's end, so no separate\n      // zero-duration \"stop\" span is recorded here.\n      await new Promise<void>((resolve) => {\n        transport.onclose = () => resolve();\n      });\n    }\n  } catch (error) {\n    if (error instanceof CLIError) {\n      throw error;\n    }\n\n    let message = getErrorMessage(error);\n\n    // Handle port-in-use errors with actionable message\n    if (error instanceof Error && (error as NodeJS.ErrnoException).code === \"EADDRINUSE\") {\n      const port = options.port || 3100;\n      message = `Port ${port} is already in use. Try a different port with --port or kill the process using that port.`;\n    }\n\n    process.stderr.write(`Error: ${message}\\n`);\n    throw new CLIError(message, 1);\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
 }

package/dist/commands/relationship.js

@@ -4,11 +4,16 @@ import { StagingAreaManager } from "../core/staging-area.js";
 import { findElementLayer } from "../utils/element-utils.js";
 import { isValidLayerName } from "../core/layers.js";
 import { CLIError, ErrorCategory, handleError, handleSuccess, handleInfo, getErrorMessage } from "../utils/errors.js";
-import { getValidRelationships, getValidPredicatesForSource, getValidDestinationsForSourceAndPredicate } from "../generated/relationship-index.js";
+import { getValidRelationships } from "../generated/relationship-index.js";
 import { normalizeNodeType } from "../generated/node-types.js";
 import { ModelReportOrchestrator } from "../reports/model-report-orchestrator.js";
 import { emitLog, SeverityNumber } from "../telemetry/index.js";
+import { elementIdentifiers } from "../core/relationships.js";
 import { RelationshipCatalog } from "../core/relationship-catalog.js";
+import { collectKnownIdentifiers, findDanglingRelationships } from "../core/relationship-prune.js";
+import { isJson } from "../utils/globals.js";
+import { ChangesetGraph } from "../core/changeset-graph.js";
+import { liveRelationshipsBetween, planRelationshipAdd, stageRelationshipDeletes, validateRelationshipCombination } from "../core/relationship-staging.js";
 function constructSpecNodeId(element, elementId) {
   const layerId = element.layer_id, type = element.type;
   if (typeof layerId != "string" || !layerId)
@@ -18,16 +23,6 @@ function constructSpecNodeId(element, elementId) {
   const normalizedType = normalizeNodeType(layerId, type);
   return `${layerId}.${normalizedType}`;
 }
-function validateRelationshipCombination(sourceSpecNodeId, predicate, destSpecNodeId) {
-  if (getValidRelationships(sourceSpecNodeId, predicate, destSpecNodeId).length > 0)
-    return { valid: !0 };
-  const suggestions = [], validPredicates = getValidPredicatesForSource(sourceSpecNodeId);
-  if (validPredicates.length > 0 ? suggestions.push(`Valid predicates for ${sourceSpecNodeId}: ${validPredicates.join(", ")}`) : suggestions.push(`No valid relationships defined for ${sourceSpecNodeId}`), predicate) {
-    const validDests = getValidDestinationsForSourceAndPredicate(sourceSpecNodeId, predicate);
-    validDests.length > 0 ? suggestions.push(`Valid destinations for --[${predicate}]-->: ${validDests.join(", ")}`) : suggestions.push(`No valid destinations for ${sourceSpecNodeId} --[${predicate}]-->`);
-  }
-  return { valid: !1, suggestions };
-}
 function getRelationshipConstraints(sourceSpecNodeId, predicate, destSpecNodeId) {
   const rels = getValidRelationships(sourceSpecNodeId, predicate, destSpecNodeId);
   if (rels.length === 0)
@@ -39,6 +34,13 @@ function getRelationshipConstraints(sourceSpecNodeId, predicate, destSpecNodeId)
   };
 }
 async function addRelationshipHandler(model, source, target, predicate, properties, preResolved) {
+  return await addRelationship(model, source, target, predicate, properties, preResolved) !== "duplicate";
+}
+async function activeStagedChangeset(manager) {
+  const active = await manager.getActive();
+  return active && active.status === "staged" ? active : null;
+}
+async function addRelationship(model, source, target, predicate, properties, preResolved) {
   let resolvedSourceLayerName = preResolved?.source?.layerName, resolvedSourceElement = preResolved?.source?.element, resolvedTargetLayerName = preResolved?.target?.layerName, resolvedTargetElement = preResolved?.target?.element;
   if (!resolvedSourceLayerName && (resolvedSourceLayerName = await findElementLayer(model, source), !resolvedSourceLayerName))
     throw new CLIError(`Source element ${source} not found`, ErrorCategory.USER);
@@ -68,9 +70,19 @@ async function addRelationshipHandler(model, source, target, predicate, properti
     if (relType && !relType.semantics.reflexivity && source === target)
       throw new CLIError(`Invalid relationship: predicate "${predicate}" does not allow reflexive relationships (${source})`, ErrorCategory.USER);
   }
-  if (model.relationships.find(source, target, predicate).length > 0)
-    return !1;
-  const stagingManager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await stagingManager.getActiveId(), relData = {
+  const stagingManager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await stagingManager.getActiveId(), activeChangeset = activeChangesetId ? await activeStagedChangeset(stagingManager) : null;
+  if (activeChangeset) {
+    const graph = await ChangesetGraph.build(model, activeChangeset), plan = planRelationshipAdd(graph, activeChangeset, { source, predicate, target });
+    if (plan.action === "duplicate")
+      return "duplicate";
+    if (plan.action === "restore") {
+      for (const key of plan.keys)
+        await stagingManager.unstage(activeChangeset.id, key);
+      return "restored";
+    }
+  } else if (model.relationships.find(source, target, predicate).length > 0)
+    return "duplicate";
+  const relData = {
     source,
     target,
     predicate,
@@ -109,15 +121,35 @@ async function addRelationshipHandler(model, source, target, predicate, properti
       });
     }
   }
-  return !0;
+  return activeChangesetId ? "staged" : "added";
 }
-async function deleteRelationshipHandler(model, source, target, predicate, preResolved) {
+async function findRelationshipsByEndpoints(model, source, target, predicate) {
+  const sourceIds = new Set(elementIdentifiers(model.getElementById(source) ?? {}, source)), targetIds = new Set(elementIdentifiers(model.getElementById(target) ?? {}, target));
+  return model.relationships.getAll().filter((rel) => sourceIds.has(rel.source) && targetIds.has(rel.target) && (!predicate || rel.predicate === predicate));
+}
+function noMatchingRelationshipHints(surface, source, inChangeset) {
+  return surface === "mcp" ? [
+    `Use "model_show" on ${source} to see its relationships`,
+    inChangeset ? 'Use "changeset_brief" to see what this changeset already stages' : 'Use "model_search" to check the source and target element IDs'
+  ] : [
+    `Use "dr relationship list ${source}" to see the relationships recorded for ${source}`,
+    inChangeset ? 'Use "dr changeset staged" to see what the active changeset already stages' : 'Use "dr relationship prune --dry-run" to list rows whose endpoints no longer resolve'
+  ];
+}
+async function deleteRelationshipHandler(model, source, target, predicate, preResolved, surface = "cli") {
+  const changesetManager = new StagingAreaManager(model.rootPath, model), changeset = await changesetManager.getActiveId() ? await activeStagedChangeset(changesetManager) : null;
+  if (changeset) {
+    const graph = await ChangesetGraph.build(model, changeset), matches = liveRelationshipsBetween(graph, source, target, predicate);
+    if (matches.length === 0)
+      throw new CLIError("No matching relationships found", ErrorCategory.USER, noMatchingRelationshipHints(surface, source, !0));
+    const staged = await stageRelationshipDeletes(changesetManager, graph, changeset, matches);
+    return { deletedCount: staged.length, staged };
+  }
   let resolvedSourceLayerName = preResolved?.sourceLayerName;
-  if (!resolvedSourceLayerName && (resolvedSourceLayerName = await findElementLayer(model, source), !resolvedSourceLayerName))
-    throw new CLIError(`Source element ${source} not found`, ErrorCategory.USER);
+  resolvedSourceLayerName || (resolvedSourceLayerName = await findElementLayer(model, source));
   let resolvedToDelete = preResolved?.toDelete;
-  if (resolvedToDelete || (resolvedToDelete = model.relationships.find(source, target, predicate)), resolvedToDelete.length === 0)
-    throw new CLIError("No matching relationships found", ErrorCategory.USER);
+  if (resolvedToDelete || (resolvedToDelete = await findRelationshipsByEndpoints(model, source, target, predicate)), resolvedToDelete.length === 0)
+    throw new CLIError("No matching relationships found", ErrorCategory.USER, noMatchingRelationshipHints(surface, source, !1));
   const stagingManager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await stagingManager.getActiveId();
   if (activeChangesetId)
     for (const rel of resolvedToDelete) {
@@ -137,7 +169,9 @@ async function deleteRelationshipHandler(model, source, target, predicate, preRe
       });
     }
   else {
-    model.relationships.delete(source, target, predicate), await model.saveRelationships(), await model.saveManifest();
+    for (const rel of resolvedToDelete)
+      model.relationships.delete(rel.source, rel.target, rel.predicate);
+    await model.saveRelationships(), await model.saveManifest();
     try {
       const orchestrator = new ModelReportOrchestrator(model, model.rootPath), affectedLayers = /* @__PURE__ */ new Set();
       for (const rel of resolvedToDelete) {
@@ -161,6 +195,106 @@ async function deleteRelationshipHandler(model, source, target, predicate, preRe
   }
   return { deletedCount: resolvedToDelete.length };
 }
+async function pruneRelationshipsCommand(options) {
+  const format = options.format ?? "text";
+  if (format !== "text" && format !== "json")
+    throw new CLIError(`Invalid format: ${format}`, ErrorCategory.USER, [
+      "Use --format text or --format json"
+    ]);
+  const jsonOutput = format === "json" || isJson(), layers = options.layers?.length ? options.layers : void 0;
+  if (layers) {
+    const invalid = layers.filter((l) => !isValidLayerName(l));
+    if (invalid.length > 0)
+      throw new CLIError(`Invalid layer name(s): ${invalid.join(", ")}`, ErrorCategory.USER, ['Use canonical layer names, e.g. "api", "data-model", "data-store"']);
+  }
+  const model = await Model.load(options.model || process.cwd()), elements = [];
+  for (const layerName of model.getLayerNames()) {
+    const layer = await model.getLayer(layerName);
+    layer && elements.push(...layer.listElements());
+  }
+  const known = collectKnownIdentifiers(elements), analysis = findDanglingRelationships(model.relationships.getAll(), known, { layers }), stagingManager = new StagingAreaManager(model.rootPath, model), activeChangeset = await stagingManager.getActive(), staging = !!activeChangeset && activeChangeset.status === "staged", result = {
+    scanned: analysis.scanned,
+    dangling: analysis.dangling.length,
+    removed: 0,
+    dryRun: !!options.dryRun,
+    staged: !1,
+    ...staging ? { changeset: activeChangeset.name } : {},
+    ...layers ? { layers } : {},
+    relationships: analysis.dangling.map(({ relationship: rel, unresolved }) => ({
+      source: rel.source,
+      predicate: rel.predicate,
+      target: rel.target,
+      layer: rel.layer,
+      ...rel.targetLayer ? { targetLayer: rel.targetLayer } : {},
+      unresolved
+    }))
+  };
+  if (!options.dryRun && analysis.dangling.length > 0) {
+    if (staging) {
+      for (const { relationship: rel } of analysis.dangling)
+        await stagingManager.stage(activeChangeset.id, {
+          type: "relationship-delete",
+          elementId: `${rel.source}::${rel.predicate}::${rel.target}`,
+          layerName: rel.layer,
+          before: {
+            source: rel.source,
+            target: rel.target,
+            predicate: rel.predicate,
+            layer: rel.layer,
+            ...rel.targetLayer ? { targetLayer: rel.targetLayer } : {},
+            ...rel.properties ? { properties: rel.properties } : {}
+          }
+        });
+      result.staged = !0;
+    } else {
+      const danglingRows = new Set(analysis.dangling.map((d) => d.relationship));
+      model.relationships.retain((rel) => !danglingRows.has(rel)), await model.saveRelationships({ preserveHeader: !0 }), await model.saveManifest();
+      try {
+        const orchestrator = new ModelReportOrchestrator(model, model.rootPath), affectedLayers = /* @__PURE__ */ new Set();
+        for (const { relationship: rel } of analysis.dangling)
+          for (const name of [rel.layer, rel.targetLayer])
+            if (name && isValidLayerName(name))
+              for (const affected of orchestrator.computeAffectedLayers(name))
+                affectedLayers.add(affected);
+        await orchestrator.regenerate(affectedLayers);
+      } catch (error) {
+        emitLog(SeverityNumber.WARN, "Failed to regenerate layer reports after relationship prune", {
+          "relationship.pruned": analysis.dangling.length,
+          "error.message": getErrorMessage(error)
+        });
+      }
+    }
+    result.removed = analysis.dangling.length;
+  }
+  if (jsonOutput)
+    return console.log(JSON.stringify({ status: "ok", ...result }, null, 2)), result;
+  const scope = layers ? ` in layer(s) ${layers.join(", ")}` : "";
+  handleInfo(`Scanned ${result.scanned} relationship(s)${scope}: ${result.dangling} dangling`);
+  for (const row of result.relationships) {
+    const side = row.unresolved === "both" ? "source and target not found" : `${row.unresolved} not found`;
+    handleInfo(`  - ${ansis.yellow(row.source)} --[${ansis.magenta(row.predicate)}]--> ${ansis.yellow(row.target)} ${ansis.dim(`(${side})`)}`);
+  }
+  return result.dangling === 0 ? handleSuccess("No dangling relationships found", {
+    scanned: result.scanned,
+    dangling: 0,
+    removed: 0
+  }) : result.dryRun ? handleSuccess(`Dry run: would remove ${result.dangling} dangling relationship(s)`, {
+    scanned: result.scanned,
+    dangling: result.dangling,
+    removed: 0,
+    dryRun: !0
+  }) : result.staged ? handleSuccess(`Staged removal of ${result.removed} dangling relationship(s) to ${ansis.bold(result.changeset)}`, {
+    scanned: result.scanned,
+    dangling: result.dangling,
+    removed: result.removed,
+    changesetStatus: "staged",
+    changeset: result.changeset
+  }) : handleSuccess(`Removed ${result.removed} dangling relationship(s)`, {
+    scanned: result.scanned,
+    dangling: result.dangling,
+    removed: result.removed
+  }), result;
+}
 function relationshipCommands(program, rootProgram) {
   program.command("add <source> <target>").description("Add a relationship between elements (intra-layer or cross-layer)").option("--model <path>", "Path to model root (contains model/manifest.yaml)").requiredOption("--predicate <predicate>", "Relationship predicate (e.g., depends-on, realizes, exposes)").option("--properties <json>", "Relationship properties (JSON)").addHelpText("after", `
 Examples:
@@ -169,7 +303,7 @@ Examples:
   $ dr relationship add business.businessprocess.checkout application.applicationprocess.checkout --predicate aggregates
   $ dr relationship add element-1 element-2 --predicate realizes --properties '{"strength":"high"}'`).action(async (source, target, options) => {
     try {
-      const model = await Model.load(options.model || process.cwd()), sourceLayerName = await findElementLayer(model, source);
+      const model = await Model.load(options.model), sourceLayerName = await findElementLayer(model, source);
       if (!sourceLayerName)
         throw new CLIError(`Source element ${source} not found`, ErrorCategory.USER);
       const sourceLayer = await model.getLayer(sourceLayerName);
@@ -195,17 +329,29 @@ Examples:
         } catch {
           throw new CLIError("Invalid JSON in --properties", ErrorCategory.USER);
         }
-      const activeChangesetId = await new StagingAreaManager(model.rootPath, model).getActiveId();
-      if (!await addRelationshipHandler(model, source, target, options.predicate, properties, {
+      const activeChangesetId = await new StagingAreaManager(model.rootPath, model).getActiveId(), outcome = await addRelationship(model, source, target, options.predicate, properties, {
         source: { element: sourceElement, layerName: sourceLayerName },
         target: { element: targetElement, layerName: targetLayerName }
-      })) {
-        handleSuccess(`Relationship ${source} --[${options.predicate}]--> ${target} already exists`, {
+      });
+      if (outcome === "duplicate") {
+        handleSuccess(`Relationship ${source} --[${options.predicate}]--> ${target} already exists` + (activeChangesetId ? " (in the model or the active changeset); nothing staged" : ""), {
+          source,
+          target,
+          predicate: options.predicate,
+          layer: sourceLayerName,
+          duplicate: !0,
+          ...activeChangesetId ? { changesetStatus: "unchanged" } : {}
+        }, { verbose: options.verbose });
+        return;
+      }
+      if (outcome === "restored") {
+        handleSuccess(`Restored relationship: ${ansis.bold(source)} ${options.predicate} ${ansis.bold(target)}` + ansis.dim(" [the active changeset's staged deletion of it was unstaged]"), {
           source,
           target,
           predicate: options.predicate,
           layer: sourceLayerName,
-          duplicate: !0
+          restored: !0,
+          changesetStatus: "unstaged"
         }, { verbose: options.verbose });
         return;
       }
@@ -225,13 +371,13 @@ Examples:
   $ dr relationship delete element-1 element-2 --predicate depends-on
   $ dr relationship delete element-1 element-2 --force`).action(async (source, target, options) => {
     try {
-      const model = await Model.load(options.model || process.cwd()), sourceLayerName = await findElementLayer(model, source);
-      if (!sourceLayerName)
-        throw new CLIError(`Source element ${source} not found`, ErrorCategory.USER);
-      const toDelete = model.relationships.find(source, target, options.predicate);
+      const model = await Model.load(options.model), activeForDelete = await activeStagedChangeset(new StagingAreaManager(model.rootPath, model)), toDelete = activeForDelete ? liveRelationshipsBetween(await ChangesetGraph.build(model, activeForDelete), source, target, options.predicate) : await findRelationshipsByEndpoints(model, source, target, options.predicate);
       if (toDelete.length === 0)
-        throw new CLIError("No matching relationships found", ErrorCategory.USER);
-      const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+        throw new CLIError("No matching relationships found", ErrorCategory.USER, [
+          `Use "dr relationship list ${source}" to see the relationships recorded for ${source}`,
+          'Use "dr relationship prune --dry-run" to list rows whose endpoints no longer resolve'
+        ]);
+      const sourceLayerName = await findElementLayer(model, source) ?? toDelete[0].layer, isInteractive = process.stdin.isTTY && process.stdout.isTTY;
       if (!options.force && isInteractive) {
         const { confirm } = await import("@clack/prompts");
         if (!await confirm({
@@ -248,24 +394,46 @@ Examples:
       }
       const activeChangesetId = await new StagingAreaManager(model.rootPath, model).getActiveId(), result = await deleteRelationshipHandler(model, source, target, options.predicate, {
         sourceLayerName,
-        toDelete
+        // In a changeset the handler re-reads the projected graph itself.
+        toDelete: activeForDelete ? void 0 : toDelete
       }), stagedSuffix = activeChangesetId ? " [staged]" : "", deleteDetails = {
         source,
         target,
         layer: sourceLayerName,
-        deletedCount: result.deletedCount
+        deletedCount: result.deletedCount,
+        ...result.staged ? { relationships: result.staged } : {}
       };
       options.predicate && (deleteDetails.predicate = options.predicate), activeChangesetId && (deleteDetails.changesetStatus = "staged"), handleSuccess(`Deleted ${result.deletedCount} relationship(s) from ${ansis.bold(source)} to ${ansis.bold(target)}${stagedSuffix}`, deleteDetails, { verbose: options.verbose });
     } catch (error) {
       handleError(error);
     }
+  }), program.command("prune").description("Remove relationship rows whose source or target no longer resolves to an element").option("--model <path>", "Path to model root (contains model/manifest.yaml)").option("--dry-run", "List the rows that would be removed without writing").option("--layers <layers...>", "Only scan rows whose source or target layer is one of these canonical layer names").option("--format <format>", "Output format: text, json", "text").addHelpText("after", `
+A row is dangling when its source or target matches neither the UUID id nor the
+dotted path of any current element. Kept rows keep their order and the file's
+header comment is preserved. Inside an active changeset the removals are staged
+as relationship deletions instead of being written to relationships.yaml.
+
+Examples:
+  $ dr relationship prune --dry-run
+  $ dr relationship prune
+  $ dr relationship prune --layers api application --format json`).action(async (options) => {
+    try {
+      await pruneRelationshipsCommand({
+        model: options.model,
+        dryRun: !!options.dryRun,
+        layers: options.layers,
+        format: options.format
+      });
+    } catch (error) {
+      handleError(error);
+    }
   }), program.command("list <id>").description("List relationships for an element").option("--model <path>", "Path to model root (contains model/manifest.yaml)").option("--direction <dir>", "Filter by direction (incoming/outgoing/all)", "all").option("--json", "Output as JSON").addHelpText("after", `
 Examples:
   $ dr relationship list api-endpoint-create-customer
   $ dr relationship list business-service-order --direction outgoing
   $ dr relationship list element-1 --json`).action(async (id, options) => {
     try {
-      const model = await Model.load(options.model || process.cwd());
+      const model = await Model.load(options.model);
       if (!await findElementLayer(model, id))
         throw new CLIError(`Element ${id} not found`, ErrorCategory.USER);
       const { outgoing, incoming } = model.relationships.getForElement(id);
@@ -295,7 +463,7 @@ Examples:
   $ dr relationship show api-endpoint-create-customer business-service-customer-mgmt
   $ dr relationship show application-component-api motivation-goal-sales-efficiency`).action(async (source, target, options) => {
     try {
-      const model = await Model.load(options.model || process.cwd());
+      const model = await Model.load(options.model);
       if (!await findElementLayer(model, source))
         throw new CLIError(`Source element ${source} not found`, ErrorCategory.USER);
       const relationships = model.relationships.find(source, target);
@@ -320,9 +488,12 @@ Examples:
   });
 }
 export {
+  addRelationship,
   addRelationshipHandler,
   deleteRelationshipHandler,
+  findRelationshipsByEndpoints,
   getRelationshipConstraints,
+  pruneRelationshipsCommand,
   relationshipCommands,
   validateRelationshipCombination
 };