@documentation-robotics/cli 0.1.13 → 0.3.0

package/dist/server-entry.js

@@ -1,7 +1,7 @@
 import { Model } from "./core/model.js";
 import { VisualizationServer } from "./server/server.js";
 import { getErrorMessage } from "./utils/errors.js";
-const port = parseInt(process.env.DR_VISUALIZE_PORT || "8080", 10), projectPath = process.env.DR_PROJECT_PATH || process.cwd(), authEnabled = process.env.DR_AUTH_ENABLED !== "false", authToken = process.env.DR_AUTH_TOKEN && process.env.DR_AUTH_TOKEN.length > 0 ? process.env.DR_AUTH_TOKEN : void 0, withDanger = process.env.DR_WITH_DANGER === "true", viewerPath = process.env.DR_VIEWER_PATH, isTelemetryEnabled = !1;
+const port = parseInt(process.env.DR_VISUALIZE_PORT || "8080", 10), projectPath = process.env.DR_PROJECT_PATH || process.cwd(), authEnabled = process.env.DR_AUTH_ENABLED !== "false", authToken = process.env.DR_AUTH_TOKEN && process.env.DR_AUTH_TOKEN.length > 0 ? process.env.DR_AUTH_TOKEN : void 0, withDanger = process.env.DR_WITH_DANGER === "true", withChangesets = process.env.DR_WITH_CHANGESETS === "true", viewerPath = process.env.DR_VIEWER_PATH, isTelemetryEnabled = !1;
 let serverInstance = null, isShuttingDown = !1;
 async function main() {
   try {
@@ -23,6 +23,7 @@ async function main() {
       authEnabled,
       authToken,
       withDanger,
+      withChangesets,
       viewerPath
     });
     serverInstance = server, await server.start(port), authEnabled && console.log(`TOKEN:${server.getAuthToken()}`), setupShutdownHandlers();

package/dist/server-entry.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/server-entry.ts"],
-  "sourcesContent": ["/**\n * Visualization Server Entry Point\n * This is spawned as a subprocess by `dr visualize` (see cli/src/commands/visualize.ts),\n * using whichever runtime (Node.js or Bun) is already running the parent CLI process.\n * It receives configuration via environment variables and starts the server.\n */\n\nimport { Model } from \"./core/model.js\";\nimport { VisualizationServer } from \"./server/server.js\";\nimport { getErrorMessage } from \"./utils/errors.js\";\n\n// Get configuration from environment variables\nconst port = parseInt(process.env.DR_VISUALIZE_PORT || \"8080\", 10);\nconst projectPath = process.env.DR_PROJECT_PATH || process.cwd();\nconst authEnabled = process.env.DR_AUTH_ENABLED !== \"false\";\n// Only pass authToken if it's a non-empty string, otherwise let server generate one\nconst authToken =\n  process.env.DR_AUTH_TOKEN && process.env.DR_AUTH_TOKEN.length > 0\n    ? process.env.DR_AUTH_TOKEN\n    : undefined;\nconst withDanger = process.env.DR_WITH_DANGER === \"true\";\nconst viewerPath = process.env.DR_VIEWER_PATH;\n\n// Conditional telemetry import based on compile-time flag\ndeclare const TELEMETRY_ENABLED: boolean | undefined;\nconst isTelemetryEnabled = typeof TELEMETRY_ENABLED !== \"undefined\" ? TELEMETRY_ENABLED : false;\n\nlet serverInstance: VisualizationServer | null = null;\nlet isShuttingDown = false;\n\nasync function main() {\n  try {\n    // CRITICAL: Initialize telemetry SDK in subprocess\n    // Without this, no spans will be created or exported even though TELEMETRY_ENABLED=true\n    if (isTelemetryEnabled) {\n      try {\n        const { initTelemetry } = await import(\"./telemetry/index.js\");\n        await initTelemetry();\n\n        // Load and display actual OTLP configuration\n        const { loadOTLPConfig } = await import(\"./telemetry/config.js\");\n        const otlpConfig = await loadOTLPConfig();\n\n        if (process.env.DEBUG || process.env.VERBOSE) {\n          console.log(`[Telemetry] SDK initialized in server subprocess`);\n          console.log(`[Telemetry] OTLP traces endpoint: ${otlpConfig.endpoint}`);\n          console.log(`[Telemetry] OTLP logs endpoint: ${otlpConfig.logsEndpoint}`);\n          console.log(`[Telemetry] Service name: ${otlpConfig.serviceName}`);\n\n          // Runtime detection and compatibility info\n          const isBun = typeof (globalThis as any).Bun !== \"undefined\";\n          if (isBun) {\n            console.log(`[Telemetry] Runtime: Bun (using fetch-based OTLP exporter)`);\n          } else {\n            console.log(`[Telemetry] Runtime: Node.js (using http-based OTLP exporter)`);\n          }\n        }\n      } catch (error) {\n        // Log telemetry initialization errors but don't fail the server\n        console.error(\"[Telemetry] Failed to initialize telemetry:\", error);\n        console.error(\"[Telemetry] Server will continue without telemetry\");\n      }\n    } else if (process.env.DEBUG || process.env.VERBOSE) {\n      console.log(`[Telemetry] TELEMETRY_ENABLED is false - telemetry disabled`);\n    }\n\n    // Load model with full content\n    const model = await Model.load(projectPath, { lazyLoad: false });\n\n    // Create and start server\n    const server = new VisualizationServer(model, {\n      authEnabled,\n      authToken,\n      withDanger,\n      viewerPath,\n    });\n    serverInstance = server; // Store for signal handlers\n    await server.start(port);\n\n    // Output token for parent process to read\n    if (authEnabled) {\n      console.log(`TOKEN:${server.getAuthToken()}`);\n    }\n\n    // Setup graceful shutdown handlers\n    setupShutdownHandlers();\n  } catch (error) {\n    const message = getErrorMessage(error);\n    console.error(`Error: ${message}`);\n    if (error instanceof Error) {\n      console.error(`Stack: ${error.stack}`);\n    }\n    await gracefulShutdown(1);\n  }\n}\n\n/**\n * Gracefully shutdown the server and flush telemetry\n */\nasync function gracefulShutdown(exitCode: number = 0): Promise<void> {\n  if (isShuttingDown) {\n    return; // Prevent multiple shutdown attempts\n  }\n  isShuttingDown = true;\n\n  try {\n    // Stop the visualization server\n    if (serverInstance) {\n      serverInstance.stop();\n      serverInstance = null;\n    }\n\n    // Flush telemetry spans before exit\n    if (isTelemetryEnabled) {\n      console.log(\"[Telemetry] Shutting down telemetry and flushing spans...\");\n      const { shutdownTelemetry } = await import(\"./telemetry/index.js\");\n      await shutdownTelemetry();\n      console.log(\"[Telemetry] Telemetry shutdown complete\");\n    } else {\n      if (process.env.DEBUG) {\n        console.log(\"[Telemetry] Telemetry is disabled (TELEMETRY_ENABLED=false at build time)\");\n      }\n    }\n  } catch (error) {\n    // Don't block shutdown on errors\n    if (process.env.DEBUG) {\n      console.error(\"Error during shutdown:\", error);\n    }\n  } finally {\n    process.exit(exitCode);\n  }\n}\n\n/**\n * Setup handlers for graceful shutdown on signals\n */\nfunction setupShutdownHandlers(): void {\n  // Handle Ctrl-C (SIGINT)\n  process.on(\"SIGINT\", async () => {\n    console.log(\"\\n[SIGINT] Shutting down visualization server...\");\n    await gracefulShutdown(0);\n  });\n\n  // Handle termination signal (SIGTERM)\n  process.on(\"SIGTERM\", async () => {\n    console.log(\"\\n[SIGTERM] Shutting down visualization server...\");\n    await gracefulShutdown(0);\n  });\n\n  // Handle uncaught exceptions\n  process.on(\"uncaughtException\", async (error) => {\n    console.error(\"Uncaught exception:\", error);\n    await gracefulShutdown(1);\n  });\n\n  // Handle unhandled promise rejections\n  process.on(\"unhandledRejection\", async (reason) => {\n    console.error(\"Unhandled rejection:\", reason);\n    await gracefulShutdown(1);\n  });\n}\n\nmain();\n"],
-  "mappings": "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",
+  "sourcesContent": ["/**\n * Visualization Server Entry Point\n * This is spawned as a subprocess by `dr visualize` (see cli/src/commands/visualize.ts),\n * using whichever runtime (Node.js or Bun) is already running the parent CLI process.\n * It receives configuration via environment variables and starts the server.\n */\n\nimport { Model } from \"./core/model.js\";\nimport { VisualizationServer } from \"./server/server.js\";\nimport { getErrorMessage } from \"./utils/errors.js\";\n\n// Get configuration from environment variables\nconst port = parseInt(process.env.DR_VISUALIZE_PORT || \"8080\", 10);\nconst projectPath = process.env.DR_PROJECT_PATH || process.cwd();\nconst authEnabled = process.env.DR_AUTH_ENABLED !== \"false\";\n// Only pass authToken if it's a non-empty string, otherwise let server generate one\nconst authToken =\n  process.env.DR_AUTH_TOKEN && process.env.DR_AUTH_TOKEN.length > 0\n    ? process.env.DR_AUTH_TOKEN\n    : undefined;\nconst withDanger = process.env.DR_WITH_DANGER === \"true\";\nconst withChangesets = process.env.DR_WITH_CHANGESETS === \"true\";\nconst viewerPath = process.env.DR_VIEWER_PATH;\n\n// Conditional telemetry import based on compile-time flag\ndeclare const TELEMETRY_ENABLED: boolean | undefined;\nconst isTelemetryEnabled = typeof TELEMETRY_ENABLED !== \"undefined\" ? TELEMETRY_ENABLED : false;\n\nlet serverInstance: VisualizationServer | null = null;\nlet isShuttingDown = false;\n\nasync function main() {\n  try {\n    // CRITICAL: Initialize telemetry SDK in subprocess\n    // Without this, no spans will be created or exported even though TELEMETRY_ENABLED=true\n    if (isTelemetryEnabled) {\n      try {\n        const { initTelemetry } = await import(\"./telemetry/index.js\");\n        await initTelemetry();\n\n        // Load and display actual OTLP configuration\n        const { loadOTLPConfig } = await import(\"./telemetry/config.js\");\n        const otlpConfig = await loadOTLPConfig();\n\n        if (process.env.DEBUG || process.env.VERBOSE) {\n          console.log(`[Telemetry] SDK initialized in server subprocess`);\n          console.log(`[Telemetry] OTLP traces endpoint: ${otlpConfig.endpoint}`);\n          console.log(`[Telemetry] OTLP logs endpoint: ${otlpConfig.logsEndpoint}`);\n          console.log(`[Telemetry] Service name: ${otlpConfig.serviceName}`);\n\n          // Runtime detection and compatibility info\n          const isBun = typeof (globalThis as any).Bun !== \"undefined\";\n          if (isBun) {\n            console.log(`[Telemetry] Runtime: Bun (using fetch-based OTLP exporter)`);\n          } else {\n            console.log(`[Telemetry] Runtime: Node.js (using http-based OTLP exporter)`);\n          }\n        }\n      } catch (error) {\n        // Log telemetry initialization errors but don't fail the server\n        console.error(\"[Telemetry] Failed to initialize telemetry:\", error);\n        console.error(\"[Telemetry] Server will continue without telemetry\");\n      }\n    } else if (process.env.DEBUG || process.env.VERBOSE) {\n      console.log(`[Telemetry] TELEMETRY_ENABLED is false - telemetry disabled`);\n    }\n\n    // Load model with full content\n    const model = await Model.load(projectPath, { lazyLoad: false });\n\n    // Create and start server\n    const server = new VisualizationServer(model, {\n      authEnabled,\n      authToken,\n      withDanger,\n      withChangesets,\n      viewerPath,\n    });\n    serverInstance = server; // Store for signal handlers\n    await server.start(port);\n\n    // Output token for parent process to read\n    if (authEnabled) {\n      console.log(`TOKEN:${server.getAuthToken()}`);\n    }\n\n    // Setup graceful shutdown handlers\n    setupShutdownHandlers();\n  } catch (error) {\n    const message = getErrorMessage(error);\n    console.error(`Error: ${message}`);\n    if (error instanceof Error) {\n      console.error(`Stack: ${error.stack}`);\n    }\n    await gracefulShutdown(1);\n  }\n}\n\n/**\n * Gracefully shutdown the server and flush telemetry\n */\nasync function gracefulShutdown(exitCode: number = 0): Promise<void> {\n  if (isShuttingDown) {\n    return; // Prevent multiple shutdown attempts\n  }\n  isShuttingDown = true;\n\n  try {\n    // Stop the visualization server\n    if (serverInstance) {\n      serverInstance.stop();\n      serverInstance = null;\n    }\n\n    // Flush telemetry spans before exit\n    if (isTelemetryEnabled) {\n      console.log(\"[Telemetry] Shutting down telemetry and flushing spans...\");\n      const { shutdownTelemetry } = await import(\"./telemetry/index.js\");\n      await shutdownTelemetry();\n      console.log(\"[Telemetry] Telemetry shutdown complete\");\n    } else {\n      if (process.env.DEBUG) {\n        console.log(\"[Telemetry] Telemetry is disabled (TELEMETRY_ENABLED=false at build time)\");\n      }\n    }\n  } catch (error) {\n    // Don't block shutdown on errors\n    if (process.env.DEBUG) {\n      console.error(\"Error during shutdown:\", error);\n    }\n  } finally {\n    process.exit(exitCode);\n  }\n}\n\n/**\n * Setup handlers for graceful shutdown on signals\n */\nfunction setupShutdownHandlers(): void {\n  // Handle Ctrl-C (SIGINT)\n  process.on(\"SIGINT\", async () => {\n    console.log(\"\\n[SIGINT] Shutting down visualization server...\");\n    await gracefulShutdown(0);\n  });\n\n  // Handle termination signal (SIGTERM)\n  process.on(\"SIGTERM\", async () => {\n    console.log(\"\\n[SIGTERM] Shutting down visualization server...\");\n    await gracefulShutdown(0);\n  });\n\n  // Handle uncaught exceptions\n  process.on(\"uncaughtException\", async (error) => {\n    console.error(\"Uncaught exception:\", error);\n    await gracefulShutdown(1);\n  });\n\n  // Handle unhandled promise rejections\n  process.on(\"unhandledRejection\", async (reason) => {\n    console.error(\"Unhandled rejection:\", reason);\n    await gracefulShutdown(1);\n  });\n}\n\nmain();\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/telemetry/config.js

@@ -1,49 +1,11 @@
-import { homedir } from "node:os";
-import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { parse } from "yaml";
-import { join } from "node:path";
-const CONFIG_FILENAME = ".dr-config.yaml";
+import { loadDRConfig } from "../config.js";
 async function loadOTLPConfig() {
   const defaults = {
     endpoint: "http://localhost:4318/v1/traces",
     logsEndpoint: "http://localhost:4318/v1/logs",
     serviceName: "dr-cli",
     isExplicitlyConfigured: !1
-  };
-  let fileConfig = {};
-  const configPath = process.env.DR_CONFIG_PATH ?? join(homedir(), CONFIG_FILENAME);
-  if (existsSync(configPath))
-    try {
-      const content = await readFile(configPath, "utf-8");
-      fileConfig = parse(content);
-    } catch (error) {
-      if (error instanceof Error) {
-        const errorMsg = error.message;
-        errorMsg.includes("EACCES") || errorMsg.includes("permission denied") ? (process.stderr.write(`Error: Cannot read config file ${configPath} - permission denied
-`), process.stderr.write(`Suggestions:
-`), process.stderr.write(`  \u2022 Check file permissions with: ls -l ${configPath}
-`), process.stderr.write(`  \u2022 Ensure you have read access to the file
-`), process.stderr.write(`  \u2022 Try: chmod 644 ${configPath}
-`)) : errorMsg.includes("YAMLException") || error.name === "YAMLException" || errorMsg.includes("bad indentation") || errorMsg.includes("unexpected") ? (process.stderr.write(`Error: Invalid YAML syntax in ${configPath}
-`), process.stderr.write(`Details: ${errorMsg}
-`), process.stderr.write(`Suggestions:
-`), process.stderr.write(`  \u2022 Validate your YAML syntax at https://www.yamllint.com/
-`), process.stderr.write(`  \u2022 Check for proper indentation (use spaces, not tabs)
-`), process.stderr.write(`  \u2022 Verify colons have spaces after them
-`)) : (process.stderr.write(`Error: Failed to load config file ${configPath}
-`), process.stderr.write(`Details: ${errorMsg}
-`), process.stderr.write(`Suggestions:
-`), process.stderr.write(`  \u2022 Verify the file is valid UTF-8 encoded text
-`), process.stderr.write(`  \u2022 Check if the file system is accessible
-`), process.stderr.write(`  \u2022 Try recreating the file if it may be corrupted
-`)), process.stderr.write(`Using default OTLP configuration due to config file error
-`);
-      } else
-        process.stderr.write(`Warning: Failed to parse ${configPath}, using defaults
-`);
-    }
-  const otlp = fileConfig?.telemetry?.otlp, getEnvVar = (value) => value !== void 0 && value.trim().length > 0 ? value : void 0, getValidUrl = (url, fieldName = "URL") => {
+  }, otlp = (await loadDRConfig())?.telemetry?.otlp, getEnvVar = (value) => value !== void 0 && value.trim().length > 0 ? value : void 0, getValidUrl = (url, fieldName = "URL") => {
     if (!url)
       return;
     const trimmed = url.trim();

package/dist/telemetry/config.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/telemetry/config.ts"],
-  "sourcesContent": ["/**\n * OTLP Configuration Loader\n *\n * Loads and merges OTLP configuration from multiple sources with the following precedence:\n * 1. DR-specific env vars: DR_OTLP_ENDPOINT, DR_OTLP_LOGS_ENDPOINT, DR_OTLP_SERVICE_NAME (highest)\n * 2. ~/.dr-config.yaml file configuration\n * 3. Standard OTEL env vars: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT,\n *    OTEL_SERVICE_NAME \u2014 treated as a low-priority fallback so that ambient OTEL env vars set\n *    by a parent process (e.g. Claude Code) do not silently override the DR config file.\n * 4. Hard-coded defaults (lowest priority)\n *\n * Why DR-specific env vars are highest: the standard OTEL_* vars are commonly set in developer\n * environments by other OTEL-instrumented tools (IDEs, shell profiles, CI). When dr runs as a\n * subprocess it inherits those vars and would silently misdirect spans. DR_OTLP_* vars are\n * unambiguously for dr and always win.\n *\n * Configuration file format (~/.dr-config.yaml):\n * ```yaml\n * telemetry:\n *   otlp:\n *     endpoint: 'http://localhost:4318/v1/traces'\n *     logs_endpoint: 'http://localhost:4318/v1/logs'\n *     service_name: 'dr-cli'\n * ```\n */\n\nimport { homedir } from \"node:os\";\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { parse } from \"yaml\";\nimport { join } from \"node:path\";\n\n/**\n * Configuration structure parsed from ~/.dr-config.yaml\n */\ninterface DRConfig {\n  telemetry?: {\n    otlp?: {\n      endpoint?: string;\n      logs_endpoint?: string;\n      service_name?: string;\n    };\n  };\n}\n\n/**\n * Resolved OTLP configuration with all required fields\n */\nexport interface OTLPConfig {\n  endpoint: string;\n  logsEndpoint: string;\n  serviceName: string;\n  /** True only when an endpoint was explicitly set via env var or config file. */\n  isExplicitlyConfigured: boolean;\n}\n\nconst CONFIG_FILENAME = \".dr-config.yaml\";\n\n/**\n * Load OTLP configuration from multiple sources.\n *\n * Configuration precedence (each field resolved independently):\n * 1. Environment variables (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, OTEL_SERVICE_NAME)\n * 2. File configuration (~/.dr-config.yaml)\n * 3. Hard-coded defaults\n *\n * All endpoint URLs are validated. Invalid URLs are treated as not set and fall back to next priority.\n *\n * @returns Resolved OTLP configuration with all required fields\n *\n * @example\n * ```typescript\n * const config = await loadOTLPConfig();\n * console.log(config.endpoint); // 'http://localhost:4318/v1/traces' (or from env/file)\n * ```\n */\nexport async function loadOTLPConfig(): Promise<OTLPConfig> {\n  // Hard-coded defaults (Priority 3)\n  const defaults: OTLPConfig = {\n    endpoint: \"http://localhost:4318/v1/traces\",\n    logsEndpoint: \"http://localhost:4318/v1/logs\",\n    serviceName: \"dr-cli\",\n    isExplicitlyConfigured: false,\n  };\n\n  // Load file configuration (Priority 2)\n  let fileConfig: DRConfig = {};\n  // Support DR_CONFIG_PATH override for testing; default to ~/.dr-config.yaml\n  const configPath = process.env.DR_CONFIG_PATH ?? join(homedir(), CONFIG_FILENAME);\n\n  if (existsSync(configPath)) {\n    try {\n      const content = await readFile(configPath, \"utf-8\");\n      fileConfig = parse(content) as DRConfig;\n    } catch (error) {\n      // Provide specific error messages based on error type\n      if (error instanceof Error) {\n        const errorMsg = error.message;\n\n        // File permission errors\n        if (errorMsg.includes(\"EACCES\") || errorMsg.includes(\"permission denied\")) {\n          process.stderr.write(\n            `Error: Cannot read config file ${configPath} - permission denied\\n`\n          );\n          process.stderr.write(\"Suggestions:\\n\");\n          process.stderr.write(`  \u2022 Check file permissions with: ls -l ${configPath}\\n`);\n          process.stderr.write(\"  \u2022 Ensure you have read access to the file\\n\");\n          process.stderr.write(`  \u2022 Try: chmod 644 ${configPath}\\n`);\n        }\n        // YAML parse errors\n        else if (\n          errorMsg.includes(\"YAMLException\") ||\n          error.name === \"YAMLException\" ||\n          errorMsg.includes(\"bad indentation\") ||\n          errorMsg.includes(\"unexpected\")\n        ) {\n          process.stderr.write(`Error: Invalid YAML syntax in ${configPath}\\n`);\n          process.stderr.write(`Details: ${errorMsg}\\n`);\n          process.stderr.write(\"Suggestions:\\n\");\n          process.stderr.write(\"  \u2022 Validate your YAML syntax at https://www.yamllint.com/\\n\");\n          process.stderr.write(\"  \u2022 Check for proper indentation (use spaces, not tabs)\\n\");\n          process.stderr.write(\"  \u2022 Verify colons have spaces after them\\n\");\n        }\n        // File encoding or other I/O errors\n        else {\n          process.stderr.write(`Error: Failed to load config file ${configPath}\\n`);\n          process.stderr.write(`Details: ${errorMsg}\\n`);\n          process.stderr.write(\"Suggestions:\\n\");\n          process.stderr.write(\"  \u2022 Verify the file is valid UTF-8 encoded text\\n\");\n          process.stderr.write(\"  \u2022 Check if the file system is accessible\\n\");\n          process.stderr.write(\"  \u2022 Try recreating the file if it may be corrupted\\n\");\n        }\n        process.stderr.write(`Using default OTLP configuration due to config file error\\n`);\n      } else {\n        process.stderr.write(`Warning: Failed to parse ${configPath}, using defaults\\n`);\n      }\n    }\n  }\n\n  const otlp = fileConfig?.telemetry?.otlp;\n\n  // Helper to check if env var is effectively set (not empty after trim)\n  const getEnvVar = (value: string | undefined) => {\n    return value !== undefined && value.trim().length > 0 ? value : undefined;\n  };\n\n  // Helper to validate URL and return if valid, undefined if invalid\n  const getValidUrl = (url: string | undefined, fieldName: string = \"URL\") => {\n    if (!url) return undefined;\n    const trimmed = url.trim();\n    if (trimmed.length === 0) return undefined;\n\n    try {\n      const parsedUrl = new URL(trimmed);\n\n      // Only accept http and https protocols\n      if (parsedUrl.protocol !== \"http:\" && parsedUrl.protocol !== \"https:\") {\n        const protocolMsg =\n          parsedUrl.protocol === \"\" || parsedUrl.protocol === \":\"\n            ? \"URL must include http:// or https:// scheme\"\n            : `Invalid protocol \"${parsedUrl.protocol}\" (expected http or https)`;\n        process.stderr.write(`Error: ${protocolMsg} in ${fieldName}\\n`);\n        process.stderr.write(`  Provided: ${trimmed}\\n`);\n        process.stderr.write(`  Expected: URL must start with http:// or https://\\n`);\n        process.stderr.write(`  Using fallback configuration for this field\\n`);\n        return undefined;\n      }\n\n      return trimmed;\n    } catch (error) {\n      process.stderr.write(`Error: Invalid URL in ${fieldName}: \"${trimmed}\"\\n`);\n      if (error instanceof Error) {\n        process.stderr.write(`  Reason: ${error.message}\\n`);\n      }\n      process.stderr.write(\"Suggestions:\\n\");\n      process.stderr.write(\"  \u2022 Ensure URL starts with http:// or https://\\n\");\n      process.stderr.write(\"  \u2022 Check for typos in hostname\\n\");\n      process.stderr.write(\"  \u2022 Verify port number if specified (e.g., :4318)\\n\");\n      process.stderr.write(\"  \u2022 Example: http://localhost:4318/v1/traces\\n\");\n      process.stderr.write(`  Using fallback configuration for this field\\n`);\n      return undefined;\n    }\n  };\n\n  // Resolve each field using the 4-level precedence chain:\n  //   1. DR-specific env vars  (unambiguously for dr, never set by other tools)\n  //   2. ~/.dr-config.yaml     (explicit user config for dr)\n  //   3. Standard OTEL env vars (low-priority fallback; may be set by parent processes)\n  //   4. Hard-coded defaults\n  //\n  // Standard OTEL env vars are intentionally below the config file. When dr runs as a\n  // subprocess of another OTEL-instrumented tool (e.g. Claude Code), it inherits those\n  // env vars and would otherwise silently redirect spans to the wrong collector.\n  const explicitEndpoint =\n    getValidUrl(getEnvVar(process.env.DR_OTLP_ENDPOINT), \"DR_OTLP_ENDPOINT\") ??\n    getValidUrl(otlp?.endpoint, \"telemetry.otlp.endpoint\") ??\n    getValidUrl(getEnvVar(process.env.OTEL_EXPORTER_OTLP_ENDPOINT), \"OTEL_EXPORTER_OTLP_ENDPOINT\");\n\n  const explicitLogsEndpoint =\n    getValidUrl(getEnvVar(process.env.DR_OTLP_LOGS_ENDPOINT), \"DR_OTLP_LOGS_ENDPOINT\") ??\n    getValidUrl(otlp?.logs_endpoint, \"telemetry.otlp.logs_endpoint\") ??\n    getValidUrl(getEnvVar(process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT), \"OTEL_EXPORTER_OTLP_LOGS_ENDPOINT\");\n\n  return {\n    endpoint: explicitEndpoint ?? defaults.endpoint,\n    logsEndpoint: explicitLogsEndpoint ?? defaults.logsEndpoint,\n    serviceName:\n      getEnvVar(process.env.DR_OTLP_SERVICE_NAME) ??\n      otlp?.service_name ??\n      getEnvVar(process.env.OTEL_SERVICE_NAME) ??\n      defaults.serviceName,\n    // True only when at least one endpoint was explicitly provided. Without this,\n    // TELEMETRY_ENABLED=true (build-time) would try to connect to localhost:4318\n    // even when no collector is running, causing a hang at shutdown.\n    isExplicitlyConfigured: !!(explicitEndpoint || explicitLogsEndpoint),\n  };\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["/**\n * OTLP Configuration Loader\n *\n * Loads and merges OTLP configuration from multiple sources with the following precedence:\n * 1. DR-specific env vars: DR_OTLP_ENDPOINT, DR_OTLP_LOGS_ENDPOINT, DR_OTLP_SERVICE_NAME (highest)\n * 2. ~/.dr-config.yaml file configuration\n * 3. Standard OTEL env vars: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT,\n *    OTEL_SERVICE_NAME \u2014 treated as a low-priority fallback so that ambient OTEL env vars set\n *    by a parent process (e.g. Claude Code) do not silently override the DR config file.\n * 4. Hard-coded defaults (lowest priority)\n *\n * Why DR-specific env vars are highest: the standard OTEL_* vars are commonly set in developer\n * environments by other OTEL-instrumented tools (IDEs, shell profiles, CI). When dr runs as a\n * subprocess it inherits those vars and would silently misdirect spans. DR_OTLP_* vars are\n * unambiguously for dr and always win.\n *\n * Configuration file format (~/.dr-config.yaml):\n * ```yaml\n * telemetry:\n *   otlp:\n *     endpoint: 'http://localhost:4318/v1/traces'\n *     logs_endpoint: 'http://localhost:4318/v1/logs'\n *     service_name: 'dr-cli'\n * ```\n */\n\nimport { loadDRConfig } from \"../config.js\";\n\n/**\n * Resolved OTLP configuration with all required fields\n */\nexport interface OTLPConfig {\n  endpoint: string;\n  logsEndpoint: string;\n  serviceName: string;\n  /** True only when an endpoint was explicitly set via env var or config file. */\n  isExplicitlyConfigured: boolean;\n}\n\n/**\n * Load OTLP configuration from multiple sources.\n *\n * Configuration precedence (each field resolved independently):\n * 1. Environment variables (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, OTEL_SERVICE_NAME)\n * 2. File configuration (~/.dr-config.yaml)\n * 3. Hard-coded defaults\n *\n * All endpoint URLs are validated. Invalid URLs are treated as not set and fall back to next priority.\n *\n * @returns Resolved OTLP configuration with all required fields\n *\n * @example\n * ```typescript\n * const config = await loadOTLPConfig();\n * console.log(config.endpoint); // 'http://localhost:4318/v1/traces' (or from env/file)\n * ```\n */\nexport async function loadOTLPConfig(): Promise<OTLPConfig> {\n  // Hard-coded defaults (Priority 3)\n  const defaults: OTLPConfig = {\n    endpoint: \"http://localhost:4318/v1/traces\",\n    logsEndpoint: \"http://localhost:4318/v1/logs\",\n    serviceName: \"dr-cli\",\n    isExplicitlyConfigured: false,\n  };\n\n  // Load file configuration (Priority 2) via the shared DR config loader.\n  // Malformed/unreadable config files are reported to stderr there and\n  // resolve to an empty object here, matching prior loadOTLPConfig() behavior.\n  const fileConfig = await loadDRConfig();\n  const otlp = fileConfig?.telemetry?.otlp;\n\n  // Helper to check if env var is effectively set (not empty after trim)\n  const getEnvVar = (value: string | undefined) => {\n    return value !== undefined && value.trim().length > 0 ? value : undefined;\n  };\n\n  // Helper to validate URL and return if valid, undefined if invalid\n  const getValidUrl = (url: string | undefined, fieldName: string = \"URL\") => {\n    if (!url) return undefined;\n    const trimmed = url.trim();\n    if (trimmed.length === 0) return undefined;\n\n    try {\n      const parsedUrl = new URL(trimmed);\n\n      // Only accept http and https protocols\n      if (parsedUrl.protocol !== \"http:\" && parsedUrl.protocol !== \"https:\") {\n        const protocolMsg =\n          parsedUrl.protocol === \"\" || parsedUrl.protocol === \":\"\n            ? \"URL must include http:// or https:// scheme\"\n            : `Invalid protocol \"${parsedUrl.protocol}\" (expected http or https)`;\n        process.stderr.write(`Error: ${protocolMsg} in ${fieldName}\\n`);\n        process.stderr.write(`  Provided: ${trimmed}\\n`);\n        process.stderr.write(`  Expected: URL must start with http:// or https://\\n`);\n        process.stderr.write(`  Using fallback configuration for this field\\n`);\n        return undefined;\n      }\n\n      return trimmed;\n    } catch (error) {\n      process.stderr.write(`Error: Invalid URL in ${fieldName}: \"${trimmed}\"\\n`);\n      if (error instanceof Error) {\n        process.stderr.write(`  Reason: ${error.message}\\n`);\n      }\n      process.stderr.write(\"Suggestions:\\n\");\n      process.stderr.write(\"  \u2022 Ensure URL starts with http:// or https://\\n\");\n      process.stderr.write(\"  \u2022 Check for typos in hostname\\n\");\n      process.stderr.write(\"  \u2022 Verify port number if specified (e.g., :4318)\\n\");\n      process.stderr.write(\"  \u2022 Example: http://localhost:4318/v1/traces\\n\");\n      process.stderr.write(`  Using fallback configuration for this field\\n`);\n      return undefined;\n    }\n  };\n\n  // Resolve each field using the 4-level precedence chain:\n  //   1. DR-specific env vars  (unambiguously for dr, never set by other tools)\n  //   2. ~/.dr-config.yaml     (explicit user config for dr)\n  //   3. Standard OTEL env vars (low-priority fallback; may be set by parent processes)\n  //   4. Hard-coded defaults\n  //\n  // Standard OTEL env vars are intentionally below the config file. When dr runs as a\n  // subprocess of another OTEL-instrumented tool (e.g. Claude Code), it inherits those\n  // env vars and would otherwise silently redirect spans to the wrong collector.\n  const explicitEndpoint =\n    getValidUrl(getEnvVar(process.env.DR_OTLP_ENDPOINT), \"DR_OTLP_ENDPOINT\") ??\n    getValidUrl(otlp?.endpoint, \"telemetry.otlp.endpoint\") ??\n    getValidUrl(getEnvVar(process.env.OTEL_EXPORTER_OTLP_ENDPOINT), \"OTEL_EXPORTER_OTLP_ENDPOINT\");\n\n  const explicitLogsEndpoint =\n    getValidUrl(getEnvVar(process.env.DR_OTLP_LOGS_ENDPOINT), \"DR_OTLP_LOGS_ENDPOINT\") ??\n    getValidUrl(otlp?.logs_endpoint, \"telemetry.otlp.logs_endpoint\") ??\n    getValidUrl(getEnvVar(process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT), \"OTEL_EXPORTER_OTLP_LOGS_ENDPOINT\");\n\n  return {\n    endpoint: explicitEndpoint ?? defaults.endpoint,\n    logsEndpoint: explicitLogsEndpoint ?? defaults.logsEndpoint,\n    serviceName:\n      getEnvVar(process.env.DR_OTLP_SERVICE_NAME) ??\n      otlp?.service_name ??\n      getEnvVar(process.env.OTEL_SERVICE_NAME) ??\n      defaults.serviceName,\n    // True only when at least one endpoint was explicitly provided. Without this,\n    // TELEMETRY_ENABLED=true (build-time) would try to connect to localhost:4318\n    // even when no collector is running, causing a hang at shutdown.\n    isExplicitlyConfigured: !!(explicitEndpoint || explicitLogsEndpoint),\n  };\n}\n"],
+  "mappings": "AA0BA,SAAS,oBAAoB;AA+B7B,eAAsB,iBAAc;AAElC,QAAM,WAAuB;IAC3B,UAAU;IACV,cAAc;IACd,aAAa;IACb,wBAAwB;KAOpB,QADa,MAAM,aAAY,IACZ,WAAW,MAG9B,YAAY,CAAC,UACV,UAAU,UAAa,MAAM,KAAI,EAAG,SAAS,IAAI,QAAQ,QAI5D,cAAc,CAAC,KAAyB,YAAoB,UAAS;AACzE,QAAI,CAAC;AAAK;AACV,UAAM,UAAU,IAAI,KAAI;AACxB,QAAI,QAAQ,WAAW;AAEvB,UAAI;AACF,cAAM,YAAY,IAAI,IAAI,OAAO;AAGjC,YAAI,UAAU,aAAa,WAAW,UAAU,aAAa,UAAU;AACrE,gBAAM,cACJ,UAAU,aAAa,MAAM,UAAU,aAAa,MAChD,gDACA,qBAAqB,UAAU,QAAQ;AAC7C,kBAAQ,OAAO,MAAM,UAAU,WAAW,OAAO,SAAS;CAAI,GAC9D,QAAQ,OAAO,MAAM,eAAe,OAAO;CAAI,GAC/C,QAAQ,OAAO,MAAM;CAAuD,GAC5E,QAAQ,OAAO,MAAM;CAAiD;AACtE;QACF;AAEA,eAAO;MACT,SAAS,OAAO;AACd,gBAAQ,OAAO,MAAM,yBAAyB,SAAS,MAAM,OAAO;CAAK,GACrE,iBAAiB,SACnB,QAAQ,OAAO,MAAM,aAAa,MAAM,OAAO;CAAI,GAErD,QAAQ,OAAO,MAAM;CAAgB,GACrC,QAAQ,OAAO,MAAM;CAAkD,GACvE,QAAQ,OAAO,MAAM;CAAmC,GACxD,QAAQ,OAAO,MAAM;CAAqD,GAC1E,QAAQ,OAAO,MAAM;CAAgD,GACrE,QAAQ,OAAO,MAAM;CAAiD;AACtE;MACF;EACF,GAWM,mBACJ,YAAY,UAAU,QAAQ,IAAI,gBAAgB,GAAG,kBAAkB,KACvE,YAAY,MAAM,UAAU,yBAAyB,KACrD,YAAY,UAAU,QAAQ,IAAI,2BAA2B,GAAG,6BAA6B,GAEzF,uBACJ,YAAY,UAAU,QAAQ,IAAI,qBAAqB,GAAG,uBAAuB,KACjF,YAAY,MAAM,eAAe,8BAA8B,KAC/D,YAAY,UAAU,QAAQ,IAAI,gCAAgC,GAAG,kCAAkC;AAEzG,SAAO;IACL,UAAU,oBAAoB,SAAS;IACvC,cAAc,wBAAwB,SAAS;IAC/C,aACE,UAAU,QAAQ,IAAI,oBAAoB,KAC1C,MAAM,gBACN,UAAU,QAAQ,IAAI,iBAAiB,KACvC,SAAS;;;;IAIX,wBAAwB,CAAC,EAAE,oBAAoB;;AAEnD;",
   "names": []
 }

package/dist/telemetry/index.js

@@ -21,7 +21,7 @@ async function initTelemetry() {
 `), process.stderr.write(`  - Logs endpoint: ${otlpConfig.logsEndpoint}
 `), process.stderr.write(`  - Service name: ${otlpConfig.serviceName}
 `));
-    const cliVersion = "0.1.13";
+    const cliVersion = "0.3.0";
     let projectName = "unknown";
     try {
       const [{ readFileSync, existsSync }, { parse }] = await Promise.all([

package/dist/types/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/types/index.ts"],
-  "sourcesContent": ["/**\n * Core type definitions for Documentation Robotics CLI\n */\n\n// Import source reference types for use in Element interface\nimport type { SourceReference } from \"./source-reference.js\";\n\n// Export source reference types\nexport type {\n  ProvenanceType,\n  SourceLocation,\n  RepositoryContext,\n  SourceReference,\n} from \"./source-reference.js\";\n\n/**\n * Reference across layers\n */\nexport interface Reference {\n  source: string; // Element ID\n  target: string; // Element ID\n  type: string; // Reference type\n  description?: string;\n}\n\n/**\n * Intra-layer or cross-layer relationship\n */\nexport interface Relationship {\n  source: string;\n  target: string;\n  predicate: string; // e.g., \"depends-on\", \"implements\"\n  layer?: string; // Source element's layer ID\n  targetLayer?: string; // Destination element's layer ID; present only for cross-layer relationships\n  properties?: Record<string, unknown>;\n  category?: \"structural\" | \"behavioral\"; // Relationship classification\n}\n\n/**\n * Element metadata for lifecycle and version tracking\n *\n * Note: created_at and updated_at should be treated as immutable after element initialization.\n * For safe external access with immutability guarantees, use Element.getMetadata() which\n * returns a defensive copy protecting against external mutations.\n */\nexport interface ElementMetadata {\n  created_at?: string; // ISO 8601 timestamp (immutable after initialization)\n  updated_at?: string; // ISO 8601 timestamp (immutable after initialization)\n  created_by?: string;\n  version?: number;\n}\n\n/**\n * Element representation\n *\n * Aligned with spec-node.schema.json structure for direct validation\n */\nexport interface Element {\n  // Spec-node aligned fields (required in new format)\n  id?: string; // UUIDv4 (e.g., \"550e8400-e29b-41d4-a716-446655440000\")\n  path?: string; // Human-readable path: {layer}.{type}.{kebab-name} (e.g., \"motivation.goal.increase-revenue\")\n  spec_node_id: string; // Reference to spec node type (e.g., \"motivation.goal\")\n  type: string; // Denormalized node type (e.g., \"goal\", \"endpoint\")\n  layer_id: string; // Denormalized layer ID (e.g., \"motivation\", \"api\")\n  name: string;\n\n  // Spec-node aligned optional fields\n  description?: string;\n  attributes?: Record<string, unknown>; // Type-specific properties\n  source_reference?: SourceReference; // Provenance tracking\n  metadata?: ElementMetadata; // Lifecycle tracking\n\n  // Relationship tracking\n  references?: Reference[];\n  relationships?: Relationship[];\n\n  // Internal tracking (unchanged)\n  layer?: string;\n  filePath?: string;\n  rawData?: any;\n}\n\n/**\n * Layer container\n */\nexport interface LayerData {\n  elements: Element[];\n  metadata?: {\n    layer: string;\n    version: string;\n  };\n}\n\n/**\n * Changeset application history entry\n * Records when changesets were committed or discarded in the model\n */\nexport interface ChangesetHistoryEntry {\n  /** Name of the changeset that was committed or discarded */\n  name: string;\n  /** ISO 8601 timestamp when the action occurred */\n  committed_at: string;\n  /** Type of action performed */\n  action: \"committed\" | \"discarded\";\n}\n\n/**\n * Manifest metadata\n */\nexport interface ManifestData {\n  name: string;\n  version: string;\n  description?: string;\n  author?: string;\n  created?: string;\n  modified?: string;\n  specVersion?: string;\n  /** Changeset history for the model */\n  changeset_history?: ChangesetHistoryEntry[];\n}\n\n/**\n * Model options for customization\n */\nexport interface ModelOptions {\n  enableCache?: boolean;\n  lazyLoad?: boolean;\n  referenceRegistry?: unknown; // Will be properly typed when implemented\n  layers?: string[]; // If set, only these layers are loaded (selective loading)\n}\n\n/**\n * JSON Schema property definition\n * Represents a single property in a JSON Schema object\n */\nexport interface JsonSchemaProperty {\n  type?: string | string[];\n  description?: string;\n  enum?: unknown[];\n  default?: unknown;\n  items?: JsonSchemaProperty;\n  properties?: Record<string, JsonSchemaProperty>;\n  required?: string[];\n  [key: string]: unknown;\n}\n\n/**\n * Tool parameter definition for Claude AI tools\n * Describes a single input parameter for a tool\n */\nexport interface ToolParameter {\n  type: string;\n  description: string;\n  enum?: string[];\n  items?: { type: string };\n  [key: string]: unknown;\n}\n\n/**\n * Tool input schema definition\n * Defines the structure of inputs for a Claude AI tool\n */\nexport interface ToolInputSchema {\n  type: \"object\";\n  properties: Record<string, ToolParameter>;\n  required: string[];\n}\n\n/**\n * Tool definition for Claude AI integration\n * Represents a single tool that Claude can call\n */\nexport interface ToolDefinition {\n  name: string;\n  description: string;\n  input_schema: ToolInputSchema;\n}\n\n/**\n * Result of executing a tool\n * All tool results are returned as JSON-serializable objects\n */\nexport interface ToolExecutionResult {\n  [key: string]: unknown;\n  error?: string;\n}\n\n/**\n * SHA256 hash branded type for compile-time safety\n * Prevents accidental misuse of arbitrary strings as cryptographic checksums\n */\nexport type Sha256Hash = string & { readonly __brand: \"Sha256Hash\" };\n\n/**\n * Create a Sha256Hash from a hex string\n * This is the only valid way to construct a Sha256Hash value\n *\n * @param hash - The hex string representation of a SHA256 hash\n * @returns A branded Sha256Hash type\n * @throws Error if the hash is not a valid 64-character hex string\n */\nexport function createSha256Hash(hash: string): Sha256Hash {\n  if (!/^[a-f0-9]{64}$/.test(hash)) {\n    throw new Error(`Invalid SHA256 hash format. Expected 64-character hex string, got: ${hash}`);\n  }\n  return hash as Sha256Hash;\n}\n\n/**\n * Backup manifest entry for a single file\n * All properties are readonly to enforce immutability of backup records\n */\nexport interface BackupManifestFile {\n  readonly path: string; // Relative path to the file in the backup directory\n  readonly checksum: Sha256Hash; // SHA256 hash of the file contents (branded type)\n  readonly size: number; // File size in bytes\n}\n\n/**\n * Backup manifest tracking files and creation timestamp\n * Used for backup integrity validation and recovery\n * All properties are readonly to enforce immutability of backup records\n */\nexport interface BackupManifest {\n  readonly files: ReadonlyArray<BackupManifestFile>; // Array of backed up files with metadata\n  readonly timestamp: string; // ISO 8601 timestamp when backup was created\n}\n\n/**\n * Create and validate a BackupManifest from raw data\n * Validates structure and transforms string checksums to Sha256Hash branded type\n *\n * @param data - Unknown data to validate (typically from JSON parsing)\n * @returns Validated and typed BackupManifest object\n * @throws Error if data doesn't match expected structure or contains invalid checksums\n */\nexport function createBackupManifest(data: unknown): BackupManifest {\n  if (!data || typeof data !== \"object\") {\n    throw new Error(\"Backup manifest must be an object\");\n  }\n\n  const obj = data as Record<string, unknown>;\n\n  if (!obj.files || !Array.isArray(obj.files)) {\n    throw new Error(\"Backup manifest must have a files array\");\n  }\n\n  if (obj.timestamp && typeof obj.timestamp !== \"string\") {\n    throw new Error(\"Backup manifest timestamp must be a string if provided\");\n  }\n\n  // Validate ISO 8601 timestamp if provided\n  let timestamp: string;\n  if (obj.timestamp) {\n    const timestampDate = new Date(obj.timestamp as string);\n    if (isNaN(timestampDate.getTime())) {\n      throw new Error(`Invalid timestamp format: ${obj.timestamp}. Expected ISO 8601 string.`);\n    }\n    timestamp = obj.timestamp as string;\n  } else {\n    timestamp = new Date().toISOString();\n  }\n\n  // Validate and transform each file entry\n  const files: readonly BackupManifestFile[] = obj.files.map((file: unknown, index: number) => {\n    if (!file || typeof file !== \"object\") {\n      throw new Error(`Backup manifest file entry ${index} must be an object`);\n    }\n\n    const fileObj = file as Record<string, unknown>;\n\n    if (typeof fileObj.path !== \"string\" || !fileObj.path) {\n      throw new Error(`Backup manifest file entry ${index} must have a non-empty path string`);\n    }\n\n    if (typeof fileObj.checksum !== \"string\") {\n      throw new Error(`Backup manifest file entry ${index} must have a checksum string`);\n    }\n\n    if (typeof fileObj.size !== \"number\" || fileObj.size < 0) {\n      throw new Error(`Backup manifest file entry ${index} must have a non-negative size number`);\n    }\n\n    return {\n      path: fileObj.path,\n      checksum: createSha256Hash(fileObj.checksum),\n      size: fileObj.size,\n    };\n  });\n\n  return {\n    files,\n    timestamp,\n  };\n}\n\n/**\n * Verify backup manifest against actual file checksums\n * Checks that all files in the manifest exist and have matching checksums\n *\n * @param manifest - The backup manifest to verify\n * @param readFile - Function to read file contents by path\n * @param fileExists - Function to check if a file exists by path\n * @param backupDir - Base directory path for resolving relative file paths\n * @returns Promise resolving to verification result with detailed error information\n */\nexport async function verifyBackupIntegrity(\n  manifest: BackupManifest,\n  readFile: (path: string) => Promise<string>,\n  fileExists: (path: string) => Promise<boolean>,\n  backupDir: string\n): Promise<{\n  isValid: boolean;\n  filesChecked: number;\n  errors: string[];\n}> {\n  const { createHash } = await import(\"crypto\");\n  const path = await import(\"path\");\n\n  const errors: string[] = [];\n  let filesChecked = 0;\n\n  try {\n    // Verify each file in the manifest\n    for (const file of manifest.files) {\n      filesChecked++;\n      const backupFilePath = path.join(backupDir, file.path);\n\n      // Check file exists\n      if (!(await fileExists(backupFilePath))) {\n        errors.push(`Missing: ${file.path}`);\n        continue;\n      }\n\n      try {\n        // Read file and verify checksum\n        const content = await readFile(backupFilePath);\n        const checksum = createHash(\"sha256\").update(content).digest(\"hex\") as Sha256Hash;\n\n        if (checksum !== file.checksum) {\n          errors.push(\n            `Checksum mismatch: ${file.path} (expected ${file.checksum}, got ${checksum})`\n          );\n          continue;\n        }\n\n        // Verify size matches\n        if (content.length !== file.size) {\n          errors.push(`Size mismatch: ${file.path} (expected ${file.size}, got ${content.length})`);\n        }\n      } catch (err) {\n        errors.push(\n          `Failed to verify: ${file.path} (${err instanceof Error ? err.message : String(err)})`\n        );\n      }\n    }\n\n    return {\n      isValid: errors.length === 0,\n      filesChecked,\n      errors,\n    };\n  } catch (err) {\n    return {\n      isValid: false,\n      filesChecked,\n      errors: [\n        ...errors,\n        `Integrity verification failed: ${err instanceof Error ? err.message : String(err)}`,\n      ],\n    };\n  }\n}\n"],
-  "mappings": "AAyMM,SAAU,iBAAiB,MAAY;AAC3C,MAAI,CAAC,iBAAiB,KAAK,IAAI;AAC7B,UAAM,IAAI,MAAM,sEAAsE,IAAI,EAAE;AAE9F,SAAO;AACT;AA8BM,SAAU,qBAAqB,MAAa;AAChD,MAAI,CAAC,QAAQ,OAAO,QAAS;AAC3B,UAAM,IAAI,MAAM,mCAAmC;AAGrD,QAAM,MAAM;AAEZ,MAAI,CAAC,IAAI,SAAS,CAAC,MAAM,QAAQ,IAAI,KAAK;AACxC,UAAM,IAAI,MAAM,yCAAyC;AAG3D,MAAI,IAAI,aAAa,OAAO,IAAI,aAAc;AAC5C,UAAM,IAAI,MAAM,wDAAwD;AAI1E,MAAI;AACJ,MAAI,IAAI,WAAW;AACjB,UAAM,gBAAgB,IAAI,KAAK,IAAI,SAAmB;AACtD,QAAI,MAAM,cAAc,QAAO,CAAE;AAC/B,YAAM,IAAI,MAAM,6BAA6B,IAAI,SAAS,6BAA6B;AAEzF,gBAAY,IAAI;EAClB;AACE,iBAAY,oBAAI,KAAI,GAAG,YAAW;AA8BpC,SAAO;IACL,OA3B2C,IAAI,MAAM,IAAI,CAAC,MAAe,UAAiB;AAC1F,UAAI,CAAC,QAAQ,OAAO,QAAS;AAC3B,cAAM,IAAI,MAAM,8BAA8B,KAAK,oBAAoB;AAGzE,YAAM,UAAU;AAEhB,UAAI,OAAO,QAAQ,QAAS,YAAY,CAAC,QAAQ;AAC/C,cAAM,IAAI,MAAM,8BAA8B,KAAK,oCAAoC;AAGzF,UAAI,OAAO,QAAQ,YAAa;AAC9B,cAAM,IAAI,MAAM,8BAA8B,KAAK,8BAA8B;AAGnF,UAAI,OAAO,QAAQ,QAAS,YAAY,QAAQ,OAAO;AACrD,cAAM,IAAI,MAAM,8BAA8B,KAAK,uCAAuC;AAG5F,aAAO;QACL,MAAM,QAAQ;QACd,UAAU,iBAAiB,QAAQ,QAAQ;QAC3C,MAAM,QAAQ;;IAElB,CAAC;IAIC;;AAEJ;AAYA,eAAsB,sBACpB,UACA,UACA,YACA,WAAiB;AAMjB,QAAM,EAAE,WAAU,IAAK,MAAM,OAAO,QAAQ,GACtC,OAAO,MAAM,OAAO,MAAM,GAE1B,SAAmB,CAAA;AACzB,MAAI,eAAe;AAEnB,MAAI;AAEF,eAAW,QAAQ,SAAS,OAAO;AACjC;AACA,YAAM,iBAAiB,KAAK,KAAK,WAAW,KAAK,IAAI;AAGrD,UAAI,CAAE,MAAM,WAAW,cAAc,GAAI;AACvC,eAAO,KAAK,YAAY,KAAK,IAAI,EAAE;AACnC;MACF;AAEA,UAAI;AAEF,cAAM,UAAU,MAAM,SAAS,cAAc,GACvC,WAAW,WAAW,QAAQ,EAAE,OAAO,OAAO,EAAE,OAAO,KAAK;AAElE,YAAI,aAAa,KAAK,UAAU;AAC9B,iBAAO,KACL,sBAAsB,KAAK,IAAI,cAAc,KAAK,QAAQ,SAAS,QAAQ,GAAG;AAEhF;QACF;AAGA,QAAI,QAAQ,WAAW,KAAK,QAC1B,OAAO,KAAK,kBAAkB,KAAK,IAAI,cAAc,KAAK,IAAI,SAAS,QAAQ,MAAM,GAAG;MAE5F,SAAS,KAAK;AACZ,eAAO,KACL,qBAAqB,KAAK,IAAI,KAAK,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC,GAAG;MAE1F;IACF;AAEA,WAAO;MACL,SAAS,OAAO,WAAW;MAC3B;MACA;;EAEJ,SAAS,KAAK;AACZ,WAAO;MACL,SAAS;MACT;MACA,QAAQ;QACN,GAAG;QACH,kCAAkC,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;;;EAGxF;AACF;",
+  "sourcesContent": ["/**\n * Core type definitions for Documentation Robotics CLI\n */\n\n// Import source reference types for use in Element interface\nimport type { SourceReference } from \"./source-reference.js\";\n\n// Export source reference types\nexport type {\n  ProvenanceType,\n  SourceLocation,\n  RepositoryContext,\n  SourceReference,\n} from \"./source-reference.js\";\n\n// Export farm-related types\nexport type {\n  FarmProject,\n  FarmManifestData,\n} from \"../core/farm-manifest.js\";\n\n/**\n * Reference across layers\n */\nexport interface Reference {\n  source: string; // Element ID\n  target: string; // Element ID\n  type: string; // Reference type\n  description?: string;\n}\n\n/**\n * Intra-layer or cross-layer relationship\n */\nexport interface Relationship {\n  source: string;\n  target: string;\n  predicate: string; // e.g., \"depends-on\", \"implements\"\n  layer?: string; // Source element's layer ID\n  targetLayer?: string; // Destination element's layer ID; present only for cross-layer relationships\n  properties?: Record<string, unknown>;\n  category?: \"structural\" | \"behavioral\"; // Relationship classification\n}\n\n/**\n * Element metadata for lifecycle and version tracking\n *\n * Note: created_at and updated_at should be treated as immutable after element initialization.\n * For safe external access with immutability guarantees, use Element.getMetadata() which\n * returns a defensive copy protecting against external mutations.\n */\nexport interface ElementMetadata {\n  created_at?: string; // ISO 8601 timestamp (immutable after initialization)\n  updated_at?: string; // ISO 8601 timestamp (immutable after initialization)\n  created_by?: string;\n  version?: number;\n}\n\n/**\n * Element representation\n *\n * Aligned with spec-node.schema.json structure for direct validation\n */\nexport interface Element {\n  // Spec-node aligned fields (required in new format)\n  id?: string; // UUIDv4 (e.g., \"550e8400-e29b-41d4-a716-446655440000\")\n  path?: string; // Human-readable path: {layer}.{type}.{kebab-name} (e.g., \"motivation.goal.increase-revenue\")\n  spec_node_id: string; // Reference to spec node type (e.g., \"motivation.goal\")\n  type: string; // Denormalized node type (e.g., \"goal\", \"endpoint\")\n  layer_id: string; // Denormalized layer ID (e.g., \"motivation\", \"api\")\n  name: string;\n\n  // Spec-node aligned optional fields\n  description?: string;\n  attributes?: Record<string, unknown>; // Type-specific properties\n  source_reference?: SourceReference; // Provenance tracking\n  metadata?: ElementMetadata; // Lifecycle tracking\n\n  // Relationship tracking\n  references?: Reference[];\n  relationships?: Relationship[];\n\n  // Internal tracking (unchanged)\n  layer?: string;\n  filePath?: string;\n  rawData?: any;\n}\n\n/**\n * Layer container\n */\nexport interface LayerData {\n  elements: Element[];\n  metadata?: {\n    layer: string;\n    version: string;\n  };\n}\n\n/**\n * Changeset application history entry\n * Records when changesets were committed or discarded in the model\n */\nexport interface ChangesetHistoryEntry {\n  /** Name of the changeset that was committed or discarded */\n  name: string;\n  /** ISO 8601 timestamp when the action occurred */\n  committed_at: string;\n  /** Type of action performed */\n  action: \"committed\" | \"discarded\";\n}\n\n/**\n * External model declaration in manifest\n * Declares a model that this model may reference via qualified paths (e.g., @model-name/...)\n */\nexport interface ExternalModelDeclaration {\n  /** Optional git repository URL for documentation */\n  url?: string;\n  /** Optional informational role (e.g., \"shared\") - not interpreted by CLI */\n  role?: string;\n}\n\n/**\n * Manifest metadata\n */\nexport interface ManifestData {\n  name: string;\n  version: string;\n  description?: string;\n  author?: string;\n  created?: string;\n  modified?: string;\n  cliVersion?: string;\n  specVersion?: string;\n  /** Changeset history for the model */\n  changeset_history?: ChangesetHistoryEntry[];\n  /** External model declarations: model name to declaration metadata */\n  models?: Record<string, ExternalModelDeclaration>;\n  /** Relative path to the codebase root (for detached models). Resolved relative to model root. */\n  codebase_path?: string;\n}\n\n/**\n * Model options for customization\n */\nexport interface ModelOptions {\n  enableCache?: boolean;\n  lazyLoad?: boolean;\n  referenceRegistry?: unknown; // Will be properly typed when implemented\n  layers?: string[]; // If set, only these layers are loaded (selective loading)\n  codebaseRoot?: string; // If set, points to the codebase directory (for detached models)\n}\n\n/**\n * JSON Schema property definition\n * Represents a single property in a JSON Schema object\n */\nexport interface JsonSchemaProperty {\n  type?: string | string[];\n  description?: string;\n  enum?: unknown[];\n  default?: unknown;\n  items?: JsonSchemaProperty;\n  properties?: Record<string, JsonSchemaProperty>;\n  required?: string[];\n  [key: string]: unknown;\n}\n\n/**\n * Tool parameter definition for Claude AI tools\n * Describes a single input parameter for a tool\n */\nexport interface ToolParameter {\n  type: string;\n  description: string;\n  enum?: string[];\n  items?: { type: string };\n  [key: string]: unknown;\n}\n\n/**\n * Tool input schema definition\n * Defines the structure of inputs for a Claude AI tool\n */\nexport interface ToolInputSchema {\n  type: \"object\";\n  properties: Record<string, ToolParameter>;\n  required: string[];\n}\n\n/**\n * Tool definition for Claude AI integration\n * Represents a single tool that Claude can call\n */\nexport interface ToolDefinition {\n  name: string;\n  description: string;\n  input_schema: ToolInputSchema;\n}\n\n/**\n * Result of executing a tool\n * All tool results are returned as JSON-serializable objects\n */\nexport interface ToolExecutionResult {\n  [key: string]: unknown;\n  error?: string;\n}\n\n/**\n * SHA256 hash branded type for compile-time safety\n * Prevents accidental misuse of arbitrary strings as cryptographic checksums\n */\nexport type Sha256Hash = string & { readonly __brand: \"Sha256Hash\" };\n\n/**\n * Create a Sha256Hash from a hex string\n * This is the only valid way to construct a Sha256Hash value\n *\n * @param hash - The hex string representation of a SHA256 hash\n * @returns A branded Sha256Hash type\n * @throws Error if the hash is not a valid 64-character hex string\n */\nexport function createSha256Hash(hash: string): Sha256Hash {\n  if (!/^[a-f0-9]{64}$/.test(hash)) {\n    throw new Error(`Invalid SHA256 hash format. Expected 64-character hex string, got: ${hash}`);\n  }\n  return hash as Sha256Hash;\n}\n\n/**\n * Backup manifest entry for a single file\n * All properties are readonly to enforce immutability of backup records\n */\nexport interface BackupManifestFile {\n  readonly path: string; // Relative path to the file in the backup directory\n  readonly checksum: Sha256Hash; // SHA256 hash of the file contents (branded type)\n  readonly size: number; // File size in bytes\n}\n\n/**\n * Backup manifest tracking files and creation timestamp\n * Used for backup integrity validation and recovery\n * All properties are readonly to enforce immutability of backup records\n */\nexport interface BackupManifest {\n  readonly files: ReadonlyArray<BackupManifestFile>; // Array of backed up files with metadata\n  readonly timestamp: string; // ISO 8601 timestamp when backup was created\n}\n\n/**\n * Create and validate a BackupManifest from raw data\n * Validates structure and transforms string checksums to Sha256Hash branded type\n *\n * @param data - Unknown data to validate (typically from JSON parsing)\n * @returns Validated and typed BackupManifest object\n * @throws Error if data doesn't match expected structure or contains invalid checksums\n */\nexport function createBackupManifest(data: unknown): BackupManifest {\n  if (!data || typeof data !== \"object\") {\n    throw new Error(\"Backup manifest must be an object\");\n  }\n\n  const obj = data as Record<string, unknown>;\n\n  if (!obj.files || !Array.isArray(obj.files)) {\n    throw new Error(\"Backup manifest must have a files array\");\n  }\n\n  if (obj.timestamp && typeof obj.timestamp !== \"string\") {\n    throw new Error(\"Backup manifest timestamp must be a string if provided\");\n  }\n\n  // Validate ISO 8601 timestamp if provided\n  let timestamp: string;\n  if (obj.timestamp) {\n    const timestampDate = new Date(obj.timestamp as string);\n    if (isNaN(timestampDate.getTime())) {\n      throw new Error(`Invalid timestamp format: ${obj.timestamp}. Expected ISO 8601 string.`);\n    }\n    timestamp = obj.timestamp as string;\n  } else {\n    timestamp = new Date().toISOString();\n  }\n\n  // Validate and transform each file entry\n  const files: readonly BackupManifestFile[] = obj.files.map((file: unknown, index: number) => {\n    if (!file || typeof file !== \"object\") {\n      throw new Error(`Backup manifest file entry ${index} must be an object`);\n    }\n\n    const fileObj = file as Record<string, unknown>;\n\n    if (typeof fileObj.path !== \"string\" || !fileObj.path) {\n      throw new Error(`Backup manifest file entry ${index} must have a non-empty path string`);\n    }\n\n    if (typeof fileObj.checksum !== \"string\") {\n      throw new Error(`Backup manifest file entry ${index} must have a checksum string`);\n    }\n\n    if (typeof fileObj.size !== \"number\" || fileObj.size < 0) {\n      throw new Error(`Backup manifest file entry ${index} must have a non-negative size number`);\n    }\n\n    return {\n      path: fileObj.path,\n      checksum: createSha256Hash(fileObj.checksum),\n      size: fileObj.size,\n    };\n  });\n\n  return {\n    files,\n    timestamp,\n  };\n}\n\n/**\n * Verify backup manifest against actual file checksums\n * Checks that all files in the manifest exist and have matching checksums\n *\n * @param manifest - The backup manifest to verify\n * @param readFile - Function to read file contents by path\n * @param fileExists - Function to check if a file exists by path\n * @param backupDir - Base directory path for resolving relative file paths\n * @returns Promise resolving to verification result with detailed error information\n */\nexport async function verifyBackupIntegrity(\n  manifest: BackupManifest,\n  readFile: (path: string) => Promise<string>,\n  fileExists: (path: string) => Promise<boolean>,\n  backupDir: string\n): Promise<{\n  isValid: boolean;\n  filesChecked: number;\n  errors: string[];\n}> {\n  const { createHash } = await import(\"crypto\");\n  const path = await import(\"path\");\n\n  const errors: string[] = [];\n  let filesChecked = 0;\n\n  try {\n    // Verify each file in the manifest\n    for (const file of manifest.files) {\n      filesChecked++;\n      const backupFilePath = path.join(backupDir, file.path);\n\n      // Check file exists\n      if (!(await fileExists(backupFilePath))) {\n        errors.push(`Missing: ${file.path}`);\n        continue;\n      }\n\n      try {\n        // Read file and verify checksum\n        const content = await readFile(backupFilePath);\n        const checksum = createHash(\"sha256\").update(content).digest(\"hex\") as Sha256Hash;\n\n        if (checksum !== file.checksum) {\n          errors.push(\n            `Checksum mismatch: ${file.path} (expected ${file.checksum}, got ${checksum})`\n          );\n          continue;\n        }\n\n        // Verify size matches\n        if (content.length !== file.size) {\n          errors.push(`Size mismatch: ${file.path} (expected ${file.size}, got ${content.length})`);\n        }\n      } catch (err) {\n        errors.push(\n          `Failed to verify: ${file.path} (${err instanceof Error ? err.message : String(err)})`\n        );\n      }\n    }\n\n    return {\n      isValid: errors.length === 0,\n      filesChecked,\n      errors,\n    };\n  } catch (err) {\n    return {\n      isValid: false,\n      filesChecked,\n      errors: [\n        ...errors,\n        `Integrity verification failed: ${err instanceof Error ? err.message : String(err)}`,\n      ],\n    };\n  }\n}\n"],
+  "mappings": "AAgOM,SAAU,iBAAiB,MAAY;AAC3C,MAAI,CAAC,iBAAiB,KAAK,IAAI;AAC7B,UAAM,IAAI,MAAM,sEAAsE,IAAI,EAAE;AAE9F,SAAO;AACT;AA8BM,SAAU,qBAAqB,MAAa;AAChD,MAAI,CAAC,QAAQ,OAAO,QAAS;AAC3B,UAAM,IAAI,MAAM,mCAAmC;AAGrD,QAAM,MAAM;AAEZ,MAAI,CAAC,IAAI,SAAS,CAAC,MAAM,QAAQ,IAAI,KAAK;AACxC,UAAM,IAAI,MAAM,yCAAyC;AAG3D,MAAI,IAAI,aAAa,OAAO,IAAI,aAAc;AAC5C,UAAM,IAAI,MAAM,wDAAwD;AAI1E,MAAI;AACJ,MAAI,IAAI,WAAW;AACjB,UAAM,gBAAgB,IAAI,KAAK,IAAI,SAAmB;AACtD,QAAI,MAAM,cAAc,QAAO,CAAE;AAC/B,YAAM,IAAI,MAAM,6BAA6B,IAAI,SAAS,6BAA6B;AAEzF,gBAAY,IAAI;EAClB;AACE,iBAAY,oBAAI,KAAI,GAAG,YAAW;AA8BpC,SAAO;IACL,OA3B2C,IAAI,MAAM,IAAI,CAAC,MAAe,UAAiB;AAC1F,UAAI,CAAC,QAAQ,OAAO,QAAS;AAC3B,cAAM,IAAI,MAAM,8BAA8B,KAAK,oBAAoB;AAGzE,YAAM,UAAU;AAEhB,UAAI,OAAO,QAAQ,QAAS,YAAY,CAAC,QAAQ;AAC/C,cAAM,IAAI,MAAM,8BAA8B,KAAK,oCAAoC;AAGzF,UAAI,OAAO,QAAQ,YAAa;AAC9B,cAAM,IAAI,MAAM,8BAA8B,KAAK,8BAA8B;AAGnF,UAAI,OAAO,QAAQ,QAAS,YAAY,QAAQ,OAAO;AACrD,cAAM,IAAI,MAAM,8BAA8B,KAAK,uCAAuC;AAG5F,aAAO;QACL,MAAM,QAAQ;QACd,UAAU,iBAAiB,QAAQ,QAAQ;QAC3C,MAAM,QAAQ;;IAElB,CAAC;IAIC;;AAEJ;AAYA,eAAsB,sBACpB,UACA,UACA,YACA,WAAiB;AAMjB,QAAM,EAAE,WAAU,IAAK,MAAM,OAAO,QAAQ,GACtC,OAAO,MAAM,OAAO,MAAM,GAE1B,SAAmB,CAAA;AACzB,MAAI,eAAe;AAEnB,MAAI;AAEF,eAAW,QAAQ,SAAS,OAAO;AACjC;AACA,YAAM,iBAAiB,KAAK,KAAK,WAAW,KAAK,IAAI;AAGrD,UAAI,CAAE,MAAM,WAAW,cAAc,GAAI;AACvC,eAAO,KAAK,YAAY,KAAK,IAAI,EAAE;AACnC;MACF;AAEA,UAAI;AAEF,cAAM,UAAU,MAAM,SAAS,cAAc,GACvC,WAAW,WAAW,QAAQ,EAAE,OAAO,OAAO,EAAE,OAAO,KAAK;AAElE,YAAI,aAAa,KAAK,UAAU;AAC9B,iBAAO,KACL,sBAAsB,KAAK,IAAI,cAAc,KAAK,QAAQ,SAAS,QAAQ,GAAG;AAEhF;QACF;AAGA,QAAI,QAAQ,WAAW,KAAK,QAC1B,OAAO,KAAK,kBAAkB,KAAK,IAAI,cAAc,KAAK,IAAI,SAAS,QAAQ,MAAM,GAAG;MAE5F,SAAS,KAAK;AACZ,eAAO,KACL,qBAAqB,KAAK,IAAI,KAAK,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC,GAAG;MAE1F;IACF;AAEA,WAAO;MACL,SAAS,OAAO,WAAW;MAC3B;MACA;;EAEJ,SAAS,KAAK;AACZ,WAAO;MACL,SAAS;MACT;MACA,QAAQ;QACN,GAAG;QACH,kCAAkC,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;;;EAGxF;AACF;",
   "names": []
 }

package/dist/utils/ansi-suppressor.js

@@ -0,0 +1,23 @@
+function stripAnsi(text) {
+  return text.replace(/\x1b\[[0-9;]*m/g, "");
+}
+function installAnsiSuppressor() {
+  const originalLog = console.log, originalError = console.error, originalWarn = console.warn, originalInfo = console.info;
+  process.stdout.isTTY !== !0 && (console.log = function(...args) {
+    const stripped = args.map((arg) => typeof arg == "string" ? stripAnsi(arg) : arg);
+    return originalLog.apply(console, stripped);
+  }, console.info = function(...args) {
+    const stripped = args.map((arg) => typeof arg == "string" ? stripAnsi(arg) : arg);
+    return originalInfo.apply(console, stripped);
+  }), process.stderr.isTTY !== !0 && (console.error = function(...args) {
+    const stripped = args.map((arg) => typeof arg == "string" ? stripAnsi(arg) : arg);
+    return originalError.apply(console, stripped);
+  }, console.warn = function(...args) {
+    const stripped = args.map((arg) => typeof arg == "string" ? stripAnsi(arg) : arg);
+    return originalWarn.apply(console, stripped);
+  });
+}
+export {
+  installAnsiSuppressor
+};
+//# sourceMappingURL=ansi-suppressor.js.map

package/dist/utils/ansi-suppressor.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/ansi-suppressor.ts"],
+  "sourcesContent": ["/**\n * Global ANSI code suppression for non-TTY output\n * Intercepts console output and strips ANSI escape sequences when the target stream is not a TTY\n * Handles stdout (log/info) and stderr (error/warn) independently based on their respective TTY status\n */\n\nfunction stripAnsi(text: string): string {\n  // eslint-disable-next-line no-control-regex\n  return text.replace(/\\x1b\\[[0-9;]*m/g, \"\");\n}\n\nexport function installAnsiSuppressor(): void {\n  const originalLog = console.log;\n  const originalError = console.error;\n  const originalWarn = console.warn;\n  const originalInfo = console.info;\n\n  // Suppress ANSI codes from stdout (log/info) if stdout is not a TTY\n  const shouldSuppressStdout = process.stdout.isTTY !== true;\n  if (shouldSuppressStdout) {\n    console.log = function (...args: any[]) {\n      const stripped = args.map((arg) => {\n        if (typeof arg === \"string\") {\n          return stripAnsi(arg);\n        }\n        return arg;\n      });\n      return originalLog.apply(console, stripped);\n    };\n\n    console.info = function (...args: any[]) {\n      const stripped = args.map((arg) => {\n        if (typeof arg === \"string\") {\n          return stripAnsi(arg);\n        }\n        return arg;\n      });\n      return originalInfo.apply(console, stripped);\n    };\n  }\n\n  // Suppress ANSI codes from stderr (error/warn) if stderr is not a TTY\n  const shouldSuppressStderr = process.stderr.isTTY !== true;\n  if (shouldSuppressStderr) {\n    console.error = function (...args: any[]) {\n      const stripped = args.map((arg) => {\n        if (typeof arg === \"string\") {\n          return stripAnsi(arg);\n        }\n        return arg;\n      });\n      return originalError.apply(console, stripped);\n    };\n\n    console.warn = function (...args: any[]) {\n      const stripped = args.map((arg) => {\n        if (typeof arg === \"string\") {\n          return stripAnsi(arg);\n        }\n        return arg;\n      });\n      return originalWarn.apply(console, stripped);\n    };\n  }\n}\n"],
+  "mappings": "AAMA,SAAS,UAAU,MAAY;AAE7B,SAAO,KAAK,QAAQ,mBAAmB,EAAE;AAC3C;AAEM,SAAU,wBAAqB;AACnC,QAAM,cAAc,QAAQ,KACtB,gBAAgB,QAAQ,OACxB,eAAe,QAAQ,MACvB,eAAe,QAAQ;AAI7B,EAD6B,QAAQ,OAAO,UAAU,OAEpD,QAAQ,MAAM,YAAa,MAAW;AACpC,UAAM,WAAW,KAAK,IAAI,CAAC,QACrB,OAAO,OAAQ,WACV,UAAU,GAAG,IAEf,GACR;AACD,WAAO,YAAY,MAAM,SAAS,QAAQ;EAC5C,GAEA,QAAQ,OAAO,YAAa,MAAW;AACrC,UAAM,WAAW,KAAK,IAAI,CAAC,QACrB,OAAO,OAAQ,WACV,UAAU,GAAG,IAEf,GACR;AACD,WAAO,aAAa,MAAM,SAAS,QAAQ;EAC7C,IAI2B,QAAQ,OAAO,UAAU,OAEpD,QAAQ,QAAQ,YAAa,MAAW;AACtC,UAAM,WAAW,KAAK,IAAI,CAAC,QACrB,OAAO,OAAQ,WACV,UAAU,GAAG,IAEf,GACR;AACD,WAAO,cAAc,MAAM,SAAS,QAAQ;EAC9C,GAEA,QAAQ,OAAO,YAAa,MAAW;AACrC,UAAM,WAAW,KAAK,IAAI,CAAC,QACrB,OAAO,OAAQ,WACV,UAAU,GAAG,IAEf,GACR;AACD,WAAO,aAAa,MAAM,SAAS,QAAQ;EAC7C;AAEJ;",
+  "names": []
+}

package/dist/utils/attribute-patch.js

@@ -0,0 +1,41 @@
+import { CLIError, ErrorCategory } from "./errors.js";
+function isPlainObject(value) {
+  return !!value && typeof value == "object" && !Array.isArray(value);
+}
+function applyAttributePatch(current, patch) {
+  const merged = { ...current ?? {} };
+  for (const [key, value] of Object.entries(patch))
+    value === null ? delete merged[key] : value !== void 0 && (merged[key] = value);
+  return merged;
+}
+function effectiveAttributePatch(patch) {
+  return patch !== void 0 && Object.keys(patch).length > 0 ? patch : void 0;
+}
+function resolveAttributeUpdate(current, update, flags = { attributes: "attributes", attributePatch: "attributePatch" }) {
+  if (update.attributes !== void 0 && update.attributePatch !== void 0)
+    throw new CLIError(`Cannot use ${flags.attributes} and ${flags.attributePatch} together`, ErrorCategory.USER, [
+      `Use ${flags.attributes} to replace all attributes, or ${flags.attributePatch} to change only the keys it names`
+    ]);
+  if (update.attributes !== void 0)
+    return update.attributes;
+  if (update.attributePatch !== void 0)
+    return applyAttributePatch(current, update.attributePatch);
+}
+function parseJsonObjectOption(raw, flag) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new CLIError(`Invalid JSON in ${flag}`, ErrorCategory.USER, ["Ensure your JSON is valid and properly formatted"]);
+  }
+  if (!isPlainObject(parsed))
+    throw new CLIError(`${flag} must be a JSON object`, ErrorCategory.USER, [`Example: ${flag} '{"summary":"New summary"}'`]);
+  return parsed;
+}
+export {
+  applyAttributePatch,
+  effectiveAttributePatch,
+  parseJsonObjectOption,
+  resolveAttributeUpdate
+};
+//# sourceMappingURL=attribute-patch.js.map

package/dist/utils/attribute-patch.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/attribute-patch.ts"],
+  "sourcesContent": ["/**\n * Attribute updates for `dr update` and the MCP `model_update` tool.\n *\n * `attributes` replaces an element's attributes; `attributePatch` merges into them, so changing one\n * attribute does not mean repeating every required one. A `null` value in a patch removes that key.\n * Both callers resolve the new attributes here so they behave the same; schema validation then runs\n * on the result.\n */\n\nimport { CLIError, ErrorCategory } from \"./errors.js\";\n\nexport type AttributePatch = Record<string, unknown>;\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  return !!value && typeof value === \"object\" && !Array.isArray(value);\n}\n\n/**\n * Merges `patch` over `current` (shallow: a patched key's value replaces the old one), removing keys\n * whose patch value is `null`. Returns a new object; `current` is not modified (staged `before`\n * snapshots share the element's attributes object).\n */\nexport function applyAttributePatch(\n  current: Record<string, unknown> | undefined,\n  patch: AttributePatch\n): Record<string, unknown> {\n  const merged: Record<string, unknown> = { ...(current ?? {}) };\n  for (const [key, value] of Object.entries(patch)) {\n    if (value === null) {\n      delete merged[key];\n    } else if (value !== undefined) {\n      merged[key] = value;\n    }\n  }\n  return merged;\n}\n\n/**\n * The patch as an update: an empty patch names no key, so it changes nothing and is not an update\n * (callers then report \"No fields specified\" and stage nothing).\n */\nexport function effectiveAttributePatch(patch: AttributePatch | undefined): AttributePatch | undefined {\n  return patch !== undefined && Object.keys(patch).length > 0 ? patch : undefined;\n}\n\n/**\n * The attributes an update asks for: `attributes` as given (replace), or `attributePatch` merged\n * over `current`, or undefined when the update leaves attributes alone. Passing both is an error.\n *\n * @param flags how the two options are spelled to the caller, for the error message\n */\nexport function resolveAttributeUpdate(\n  current: Record<string, unknown> | undefined,\n  update: { attributes?: Record<string, unknown>; attributePatch?: AttributePatch },\n  flags: { attributes: string; attributePatch: string } = { attributes: \"attributes\", attributePatch: \"attributePatch\" }\n): Record<string, unknown> | undefined {\n  if (update.attributes !== undefined && update.attributePatch !== undefined) {\n    throw new CLIError(`Cannot use ${flags.attributes} and ${flags.attributePatch} together`, ErrorCategory.USER, [\n      `Use ${flags.attributes} to replace all attributes, or ${flags.attributePatch} to change only the keys it names`,\n    ]);\n  }\n  if (update.attributes !== undefined) return update.attributes;\n  if (update.attributePatch !== undefined) return applyAttributePatch(current, update.attributePatch);\n  return undefined;\n}\n\n/** Parses a CLI JSON option that must be an object (`--attributes`, `--attribute-patch`). */\nexport function parseJsonObjectOption(raw: string, flag: string): Record<string, unknown> {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw);\n  } catch {\n    throw new CLIError(`Invalid JSON in ${flag}`, ErrorCategory.USER, [\"Ensure your JSON is valid and properly formatted\"]);\n  }\n  if (!isPlainObject(parsed)) {\n    throw new CLIError(`${flag} must be a JSON object`, ErrorCategory.USER, [`Example: ${flag} '{\"summary\":\"New summary\"}'`]);\n  }\n  return parsed;\n}\n"],
+  "mappings": "AASA,SAAS,UAAU,qBAAqB;AAIxC,SAAS,cAAc,OAAc;AACnC,SAAO,CAAC,CAAC,SAAS,OAAO,SAAU,YAAY,CAAC,MAAM,QAAQ,KAAK;AACrE;AAOM,SAAU,oBACd,SACA,OAAqB;AAErB,QAAM,SAAkC,EAAE,GAAI,WAAW,CAAA,EAAG;AAC5D,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK;AAC7C,IAAI,UAAU,OACZ,OAAO,OAAO,GAAG,IACR,UAAU,WACnB,OAAO,GAAG,IAAI;AAGlB,SAAO;AACT;AAMM,SAAU,wBAAwB,OAAiC;AACvE,SAAO,UAAU,UAAa,OAAO,KAAK,KAAK,EAAE,SAAS,IAAI,QAAQ;AACxE;AAQM,SAAU,uBACd,SACA,QACA,QAAwD,EAAE,YAAY,cAAc,gBAAgB,iBAAgB,GAAE;AAEtH,MAAI,OAAO,eAAe,UAAa,OAAO,mBAAmB;AAC/D,UAAM,IAAI,SAAS,cAAc,MAAM,UAAU,QAAQ,MAAM,cAAc,aAAa,cAAc,MAAM;MAC5G,OAAO,MAAM,UAAU,kCAAkC,MAAM,cAAc;KAC9E;AAEH,MAAI,OAAO,eAAe;AAAW,WAAO,OAAO;AACnD,MAAI,OAAO,mBAAmB;AAAW,WAAO,oBAAoB,SAAS,OAAO,cAAc;AAEpG;AAGM,SAAU,sBAAsB,KAAa,MAAY;AAC7D,MAAI;AACJ,MAAI;AACF,aAAS,KAAK,MAAM,GAAG;EACzB,QAAQ;AACN,UAAM,IAAI,SAAS,mBAAmB,IAAI,IAAI,cAAc,MAAM,CAAC,kDAAkD,CAAC;EACxH;AACA,MAAI,CAAC,cAAc,MAAM;AACvB,UAAM,IAAI,SAAS,GAAG,IAAI,0BAA0B,cAAc,MAAM,CAAC,YAAY,IAAI,8BAA8B,CAAC;AAE1H,SAAO;AACT;",
+  "names": []
+}

package/dist/utils/color-utils.js

@@ -0,0 +1,34 @@
+import ansis from "ansis";
+function shouldUseColors() {
+  return process.stdout.isTTY === !0;
+}
+const colors = {
+  red: (str) => shouldUseColors() ? ansis.red(str) : str,
+  green: (str) => shouldUseColors() ? ansis.green(str) : str,
+  yellow: (str) => shouldUseColors() ? ansis.yellow(str) : str,
+  blue: (str) => shouldUseColors() ? ansis.blue(str) : str,
+  gray: (str) => shouldUseColors() ? ansis.gray(str) : str,
+  dim: (str) => shouldUseColors() ? ansis.dim(str) : str,
+  bold: (str) => shouldUseColors() ? ansis.bold(str) : str,
+  cyan: (str) => shouldUseColors() ? ansis.cyan(str) : str,
+  get red_bold() {
+    return (str) => shouldUseColors() ? ansis.red.bold(str) : str;
+  },
+  get bold_yellow() {
+    return (str) => shouldUseColors() ? ansis.bold.yellow(str) : str;
+  },
+  get bold_blue() {
+    return (str) => shouldUseColors() ? ansis.bold.blue(str) : str;
+  },
+  get bold_green() {
+    return (str) => shouldUseColors() ? ansis.bold.green(str) : str;
+  }
+};
+function isColorSupported() {
+  return shouldUseColors();
+}
+export {
+  colors,
+  isColorSupported
+};
+//# sourceMappingURL=color-utils.js.map

package/dist/utils/color-utils.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/color-utils.ts"],
+  "sourcesContent": ["import ansis from \"ansis\";\n\nfunction shouldUseColors(): boolean {\n  return process.stdout.isTTY === true;\n}\n\nexport const colors = {\n  red: (str: string): string => (shouldUseColors() ? ansis.red(str) : str),\n  green: (str: string): string => (shouldUseColors() ? ansis.green(str) : str),\n  yellow: (str: string): string => (shouldUseColors() ? ansis.yellow(str) : str),\n  blue: (str: string): string => (shouldUseColors() ? ansis.blue(str) : str),\n  gray: (str: string): string => (shouldUseColors() ? ansis.gray(str) : str),\n  dim: (str: string): string => (shouldUseColors() ? ansis.dim(str) : str),\n  bold: (str: string): string => (shouldUseColors() ? ansis.bold(str) : str),\n  cyan: (str: string): string => (shouldUseColors() ? ansis.cyan(str) : str),\n\n  get red_bold() {\n    return (str: string): string => (shouldUseColors() ? ansis.red.bold(str) : str);\n  },\n  get bold_yellow() {\n    return (str: string): string => (shouldUseColors() ? ansis.bold.yellow(str) : str);\n  },\n  get bold_blue() {\n    return (str: string): string => (shouldUseColors() ? ansis.bold.blue(str) : str);\n  },\n  get bold_green() {\n    return (str: string): string => (shouldUseColors() ? ansis.bold.green(str) : str);\n  },\n};\n\nexport function isColorSupported(): boolean {\n  return shouldUseColors();\n}\n"],
+  "mappings": "AAAA,OAAO,WAAW;AAElB,SAAS,kBAAe;AACtB,SAAO,QAAQ,OAAO,UAAU;AAClC;AAEO,MAAM,SAAS;EACpB,KAAK,CAAC,QAAyB,gBAAe,IAAK,MAAM,IAAI,GAAG,IAAI;EACpE,OAAO,CAAC,QAAyB,gBAAe,IAAK,MAAM,MAAM,GAAG,IAAI;EACxE,QAAQ,CAAC,QAAyB,gBAAe,IAAK,MAAM,OAAO,GAAG,IAAI;EAC1E,MAAM,CAAC,QAAyB,gBAAe,IAAK,MAAM,KAAK,GAAG,IAAI;EACtE,MAAM,CAAC,QAAyB,gBAAe,IAAK,MAAM,KAAK,GAAG,IAAI;EACtE,KAAK,CAAC,QAAyB,gBAAe,IAAK,MAAM,IAAI,GAAG,IAAI;EACpE,MAAM,CAAC,QAAyB,gBAAe,IAAK,MAAM,KAAK,GAAG,IAAI;EACtE,MAAM,CAAC,QAAyB,gBAAe,IAAK,MAAM,KAAK,GAAG,IAAI;EAEtE,IAAI,WAAQ;AACV,WAAO,CAAC,QAAyB,gBAAe,IAAK,MAAM,IAAI,KAAK,GAAG,IAAI;EAC7E;EACA,IAAI,cAAW;AACb,WAAO,CAAC,QAAyB,gBAAe,IAAK,MAAM,KAAK,OAAO,GAAG,IAAI;EAChF;EACA,IAAI,YAAS;AACX,WAAO,CAAC,QAAyB,gBAAe,IAAK,MAAM,KAAK,KAAK,GAAG,IAAI;EAC9E;EACA,IAAI,aAAU;AACZ,WAAO,CAAC,QAAyB,gBAAe,IAAK,MAAM,KAAK,MAAM,GAAG,IAAI;EAC/E;;AAGI,SAAU,mBAAgB;AAC9B,SAAO,gBAAe;AACxB;",
+  "names": []
+}

package/dist/utils/element-reference-shape.js

@@ -1,8 +1,22 @@
 import { getAllLayerIds } from "../generated/layer-registry.js";
-const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i, KNOWN_LAYERS = new Set(getAllLayerIds());
+import { UUID_PATTERN, QUALIFIED_PREFIX_PATTERN, parseReferencePath, ReferencePathParseError } from "./reference-path-parser.js";
+const KNOWN_LAYERS = new Set(getAllLayerIds());
 function looksLikeElementReference(value) {
   if (UUID_PATTERN.test(value))
     return !0;
+  if (QUALIFIED_PREFIX_PATTERN.test(value))
+    try {
+      const parsed = parseReferencePath(value), dotIndex2 = parsed.segment.indexOf(".");
+      if (dotIndex2 > 0) {
+        const layer = parsed.segment.slice(0, dotIndex2);
+        return KNOWN_LAYERS.has(layer);
+      }
+      return !1;
+    } catch (error) {
+      if (error instanceof ReferencePathParseError)
+        return !1;
+      throw error;
+    }
   const dotIndex = value.indexOf(".");
   return dotIndex <= 0 ? !1 : KNOWN_LAYERS.has(value.slice(0, dotIndex));
 }

package/dist/utils/element-reference-shape.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/utils/element-reference-shape.ts"],
-  "sourcesContent": ["/**\n * Shape check for \"does this string plausibly identify a DR model element\" \u2014 a UUIDv4\n * (element.id) or a dot-separated `{layer}.{type}.{slug}` id whose first segment is a real,\n * known DR layer (matching the id scheme `NamingValidator` enforces on every element).\n *\n * Used by `ReferenceRegistry` to gate its `*Ref`/`*Reference` attribute-name heuristic: an\n * attribute NAME matching that convention is not, by itself, reliable evidence that its VALUE\n * is an element reference \u2014 `api.link.operationRef` is a schema-declared OpenAPI URL fragment\n * (e.g. \"#/paths/~1users/get\"), not an element id, and matches the naming convention purely by\n * coincidence. Checking the value's shape catches that case (and any future one like it)\n * without needing per-attribute schema annotations that don't exist today.\n *\n * Deliberately a shape check, not an existence check: a value that looks like an element id but\n * doesn't resolve to one is exactly what `ReferenceRegistry.findBrokenReferences()` is supposed\n * to catch, so this must not filter those out too.\n */\nimport { getAllLayerIds } from \"../generated/layer-registry.js\";\n\nconst UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\nconst KNOWN_LAYERS = new Set(getAllLayerIds());\n\nexport function looksLikeElementReference(value: string): boolean {\n  if (UUID_PATTERN.test(value)) return true;\n\n  const dotIndex = value.indexOf(\".\");\n  if (dotIndex <= 0) return false;\n\n  return KNOWN_LAYERS.has(value.slice(0, dotIndex));\n}\n"],
-  "mappings": "AAgBA,SAAS,sBAAsB;AAE/B,MAAM,eAAe,mEACf,eAAe,IAAI,IAAI,eAAc,CAAE;AAEvC,SAAU,0BAA0B,OAAa;AACrD,MAAI,aAAa,KAAK,KAAK;AAAG,WAAO;AAErC,QAAM,WAAW,MAAM,QAAQ,GAAG;AAClC,SAAI,YAAY,IAAU,KAEnB,aAAa,IAAI,MAAM,MAAM,GAAG,QAAQ,CAAC;AAClD;",
-  "names": []
+  "sourcesContent": ["/**\n * Shape check for \"does this string plausibly identify a DR model element\" \u2014 a UUIDv4\n * (element.id), a dot-separated `{layer}.{type}.{slug}` id whose first segment is a real,\n * known DR layer (matching the id scheme `NamingValidator` enforces on every element), or\n * a qualified cross-model reference in the format `@{model-name}/{layer}.{type}.{slug}`.\n *\n * Used by `ReferenceRegistry` to gate its `*Ref`/`*Reference` attribute-name heuristic: an\n * attribute NAME matching that convention is not, by itself, reliable evidence that its VALUE\n * is an element reference \u2014 `api.link.operationRef` is a schema-declared OpenAPI URL fragment\n * (e.g. \"#/paths/~1users/get\"), not an element id, and matches the naming convention purely by\n * coincidence. Checking the value's shape catches that case (and any future one like it)\n * without needing per-attribute schema annotations that don't exist today.\n *\n * Deliberately a shape check, not an existence check: a value that looks like an element id but\n * doesn't resolve to one is exactly what `ReferenceRegistry.findBrokenReferences()` is supposed\n * to catch, so this must not filter those out too.\n */\nimport { getAllLayerIds } from \"../generated/layer-registry.js\";\nimport {\n  UUID_PATTERN,\n  QUALIFIED_PREFIX_PATTERN,\n  parseReferencePath,\n  ReferencePathParseError,\n} from \"./reference-path-parser.js\";\n\nconst KNOWN_LAYERS = new Set(getAllLayerIds());\n\nexport function looksLikeElementReference(value: string): boolean {\n  if (UUID_PATTERN.test(value)) return true;\n\n  // Check for qualified reference: must match without whitespace\n  if (QUALIFIED_PREFIX_PATTERN.test(value)) {\n    try {\n      const parsed = parseReferencePath(value);\n      // Extract layer name from segment (first dot-separated component)\n      const dotIndex = parsed.segment.indexOf(\".\");\n      if (dotIndex > 0) {\n        const layer = parsed.segment.slice(0, dotIndex);\n        return KNOWN_LAYERS.has(layer);\n      }\n      return false;\n    } catch (error) {\n      // Malformed qualified reference\n      if (error instanceof ReferencePathParseError) {\n        return false;\n      }\n      throw error;\n    }\n  }\n\n  // Check for unqualified reference: {layer}.{type}.{slug}\n  const dotIndex = value.indexOf(\".\");\n  if (dotIndex <= 0) return false;\n\n  return KNOWN_LAYERS.has(value.slice(0, dotIndex));\n}\n"],
+  "mappings": "AAiBA,SAAS,sBAAsB;AAC/B,SACE,cACA,0BACA,oBACA,+BACK;AAEP,MAAM,eAAe,IAAI,IAAI,eAAc,CAAE;AAEvC,SAAU,0BAA0B,OAAa;AACrD,MAAI,aAAa,KAAK,KAAK;AAAG,WAAO;AAGrC,MAAI,yBAAyB,KAAK,KAAK;AACrC,QAAI;AACF,YAAM,SAAS,mBAAmB,KAAK,GAEjCA,YAAW,OAAO,QAAQ,QAAQ,GAAG;AAC3C,UAAIA,YAAW,GAAG;AAChB,cAAM,QAAQ,OAAO,QAAQ,MAAM,GAAGA,SAAQ;AAC9C,eAAO,aAAa,IAAI,KAAK;MAC/B;AACA,aAAO;IACT,SAAS,OAAO;AAEd,UAAI,iBAAiB;AACnB,eAAO;AAET,YAAM;IACR;AAIF,QAAM,WAAW,MAAM,QAAQ,GAAG;AAClC,SAAI,YAAY,IAAU,KAEnB,aAAa,IAAI,MAAM,MAAM,GAAG,QAAQ,CAAC;AAClD;",
+  "names": ["dotIndex"]
 }

package/dist/utils/error-hints.js

@@ -0,0 +1,29 @@
+const CLI_FLAGS = {
+  sourceFile: "--source-file",
+  sourceSymbol: "--source-symbol",
+  sourceProvenance: "--source-provenance",
+  sourceRepoRemote: "--source-repo-remote",
+  sourceRepoCommit: "--source-repo-commit",
+  clearSourceReference: "--clear-source-reference"
+};
+function optionName(surface, option) {
+  return surface === "mcp" ? option : CLI_FLAGS[option];
+}
+function optionExample(surface, option, value) {
+  return surface === "mcp" ? `${option}: "${value}"` : `${CLI_FLAGS[option]} "${value}"`;
+}
+function schemaLookupHint(surface, layer, type) {
+  return surface === "mcp" ? `Call "spec_type" with layer "${layer}" and type "${type}" to see the required attributes` : `Run "dr schema node ${layer}.${type}" to see the required attributes`;
+}
+function undefinedTypeWarning(surface, layer, elementId, type, replacements) {
+  const message = `Element '${elementId}' has type '${type}', which the spec does not define for the ${layer} layer, so its attributes were not checked against a type schema`, replacement = replacements[0];
+  let hint;
+  return surface === "mcp" ? hint = replacement ? `Pass type "${replacement}" to model_update to move the element to a type the spec defines` : `Call "spec_type" with layer "${layer}" and no type to list the layer's types, then pass one as type to model_update` : hint = replacement ? `Run "dr update ${elementId} --type ${replacement}" to move the element to a type the spec defines` : `Run "dr schema types ${layer}" to list the layer's types, then "dr update ${elementId} --type <type>"`, { message, hint };
+}
+export {
+  optionExample,
+  optionName,
+  schemaLookupHint,
+  undefinedTypeWarning
+};
+//# sourceMappingURL=error-hints.js.map

package/dist/utils/error-hints.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/error-hints.ts"],
+  "sourcesContent": ["/**\n * Surface-aware error hints.\n *\n * The CLI and the MCP server share validation code, but a user at the terminal passes\n * `--source-provenance` and runs `dr schema`, while an agent over MCP passes the\n * `sourceProvenance` parameter and calls the `spec_type` tool. Errors built from shared code\n * take a surface and name things the way that caller can act on them.\n */\n\nexport type HintSurface = \"cli\" | \"mcp\";\n\n/** Option keys that shared validators name in their messages. */\nexport type HintOption =\n  | \"sourceFile\"\n  | \"sourceSymbol\"\n  | \"sourceProvenance\"\n  | \"sourceRepoRemote\"\n  | \"sourceRepoCommit\"\n  | \"clearSourceReference\";\n\nconst CLI_FLAGS: Record<HintOption, string> = {\n  sourceFile: \"--source-file\",\n  sourceSymbol: \"--source-symbol\",\n  sourceProvenance: \"--source-provenance\",\n  sourceRepoRemote: \"--source-repo-remote\",\n  sourceRepoCommit: \"--source-repo-commit\",\n  clearSourceReference: \"--clear-source-reference\",\n};\n\n/** How the caller names an option: `--source-file` on the CLI, `sourceFile` over MCP. */\nexport function optionName(surface: HintSurface, option: HintOption): string {\n  return surface === \"mcp\" ? option : CLI_FLAGS[option];\n}\n\n/** How the caller passes an option with a value, for examples in hints. */\nexport function optionExample(surface: HintSurface, option: HintOption, value: string): string {\n  return surface === \"mcp\" ? `${option}: \"${value}\"` : `${CLI_FLAGS[option]} \"${value}\"`;\n}\n\n/** Where to look up a type's required attributes: `dr schema` on the CLI, `spec_type` over MCP. */\nexport function schemaLookupHint(surface: HintSurface, layer: string, type: string): string {\n  return surface === \"mcp\"\n    ? `Call \"spec_type\" with layer \"${layer}\" and type \"${type}\" to see the required attributes`\n    : `Run \"dr schema node ${layer}.${type}\" to see the required attributes`;\n}\n\n/**\n * Warning for an update to an element whose current type the spec does not define (an obsolete\n * `product.capability`). With no type schema there is nothing to check its attributes against, so\n * the update goes through; the hint names the type change that fixes it, because looking up the\n * obsolete type with `spec_type` or `dr schema node` cannot work.\n */\nexport function undefinedTypeWarning(\n  surface: HintSurface,\n  layer: string,\n  elementId: string,\n  type: string,\n  replacements: string[]\n): { message: string; hint: string } {\n  const message =\n    `Element '${elementId}' has type '${type}', which the spec does not define for the ${layer} layer, ` +\n    `so its attributes were not checked against a type schema`;\n  const replacement = replacements[0];\n  let hint: string;\n  if (surface === \"mcp\") {\n    hint = replacement\n      ? `Pass type \"${replacement}\" to model_update to move the element to a type the spec defines`\n      : `Call \"spec_type\" with layer \"${layer}\" and no type to list the layer's types, then pass one as type to model_update`;\n  } else {\n    hint = replacement\n      ? `Run \"dr update ${elementId} --type ${replacement}\" to move the element to a type the spec defines`\n      : `Run \"dr schema types ${layer}\" to list the layer's types, then \"dr update ${elementId} --type <type>\"`;\n  }\n  return { message, hint };\n}\n"],
+  "mappings": "AAoBA,MAAM,YAAwC;EAC5C,YAAY;EACZ,cAAc;EACd,kBAAkB;EAClB,kBAAkB;EAClB,kBAAkB;EAClB,sBAAsB;;AAIlB,SAAU,WAAW,SAAsB,QAAkB;AACjE,SAAO,YAAY,QAAQ,SAAS,UAAU,MAAM;AACtD;AAGM,SAAU,cAAc,SAAsB,QAAoB,OAAa;AACnF,SAAO,YAAY,QAAQ,GAAG,MAAM,MAAM,KAAK,MAAM,GAAG,UAAU,MAAM,CAAC,KAAK,KAAK;AACrF;AAGM,SAAU,iBAAiB,SAAsB,OAAe,MAAY;AAChF,SAAO,YAAY,QACf,gCAAgC,KAAK,eAAe,IAAI,qCACxD,uBAAuB,KAAK,IAAI,IAAI;AAC1C;AAQM,SAAU,qBACd,SACA,OACA,WACA,MACA,cAAsB;AAEtB,QAAM,UACJ,YAAY,SAAS,eAAe,IAAI,6CAA6C,KAAK,oEAEtF,cAAc,aAAa,CAAC;AAClC,MAAI;AACJ,SAAI,YAAY,QACd,OAAO,cACH,cAAc,WAAW,qEACzB,gCAAgC,KAAK,mFAEzC,OAAO,cACH,kBAAkB,SAAS,WAAW,WAAW,qDACjD,wBAAwB,KAAK,gDAAgD,SAAS,mBAErF,EAAE,SAAS,KAAI;AACxB;",
+  "names": []
+}

package/dist/utils/errors.js

@@ -1,4 +1,5 @@
 import ansis from "ansis";
+import { isJson } from "./globals.js";
 const MAX_SUGGESTIONS = 5;
 var ErrorCategory;
 (function(ErrorCategory2) {
@@ -105,20 +106,83 @@ class InvalidJSONError extends CLIError {
   }
 }
 function handleError(error) {
-  throw error instanceof CLIError ? (console.error(error.format()), error) : error instanceof Error ? (console.error(ansis.red(`Error: ${error.message}`)), process.env.DEBUG && console.error(ansis.dim(error.stack)), error) : (console.error(ansis.red("An unexpected error occurred")), process.env.DEBUG && console.error(ansis.dim(String(error))), new Error(String(error)));
+  if (error instanceof CLIError) {
+    if (isJson()) {
+      const output = {
+        status: "error",
+        code: error.exitCode,
+        message: error.message
+      };
+      error.suggestions && error.suggestions.length > 0 && (output.suggestions = error.suggestions), error.context && (error.context.operation && (output.operation = error.context.operation), error.context.relatedElements && error.context.relatedElements.length > 0 && (output.relatedElements = error.context.relatedElements), error.context.partialProgress && (output.partialProgress = error.context.partialProgress)), console.log(JSON.stringify(output));
+    } else
+      console.error(error.format());
+    throw error;
+  } else if (error instanceof Error) {
+    if (isJson()) {
+      const output = {
+        status: "error",
+        code: ErrorCategory.USER,
+        message: error.message
+      };
+      process.env.DEBUG && error.stack && (output.stack = error.stack), console.log(JSON.stringify(output));
+    } else
+      console.error(ansis.red(`Error: ${error.message}`)), process.env.DEBUG && console.error(ansis.dim(error.stack));
+    throw error;
+  } else {
+    if (isJson()) {
+      const output = {
+        status: "error",
+        code: ErrorCategory.USER,
+        message: "An unexpected error occurred"
+      };
+      process.env.DEBUG && (output.details = String(error)), console.log(JSON.stringify(output));
+    } else
+      console.error(ansis.red("An unexpected error occurred")), process.env.DEBUG && console.error(ansis.dim(String(error)));
+    throw new Error(String(error));
+  }
 }
 function handleWarning(message, suggestions) {
-  const lines = [];
-  if (lines.push(ansis.yellow(`Warning: ${message}`)), suggestions && suggestions.length > 0) {
-    lines.push(""), lines.push(ansis.dim("Suggestions:"));
-    for (const suggestion of suggestions)
-      lines.push(ansis.dim(`  \u2022 ${suggestion}`));
-  }
-  console.warn(lines.join(`
+  if (isJson()) {
+    const output = {
+      level: "warning",
+      message
+    };
+    suggestions && suggestions.length > 0 && (output.suggestions = suggestions), console.error(JSON.stringify(output));
+  } else {
+    const lines = [];
+    if (lines.push(ansis.yellow(`Warning: ${message}`)), suggestions && suggestions.length > 0) {
+      lines.push(""), lines.push(ansis.dim("Suggestions:"));
+      for (const suggestion of suggestions)
+        lines.push(ansis.dim(`  \u2022 ${suggestion}`));
+    }
+    console.warn(lines.join(`
 `));
+  }
+}
+function handleSuccess(message, details, options) {
+  if (isJson()) {
+    const output = {
+      ...details,
+      status: "ok"
+    };
+    console.log(JSON.stringify(output));
+  } else if (console.log(ansis.green(`\u2713 ${message}`)), details && (options?.verbose || details.changesetStatus))
+    for (const [key, value] of Object.entries(details)) {
+      const displayKey = keyToDisplayName(key);
+      console.log(ansis.dim(`  ${displayKey}: ${value}`));
+    }
+}
+function keyToDisplayName(key) {
+  return key.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/_/g, " ").split(" ").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 }
-function handleSuccess(message, details) {
-  if (console.log(ansis.green(`\u2713 ${message}`)), details)
+function handleInfo(message, details) {
+  if (isJson()) {
+    const output = {
+      level: "info",
+      message
+    };
+    details && (output.details = details), console.error(JSON.stringify(output));
+  } else if (console.log(message), details)
     for (const [key, value] of Object.entries(details))
       console.log(ansis.dim(`  ${key}: ${value}`));
 }
@@ -172,6 +236,7 @@ export {
   formatValidOptions,
   getErrorMessage,
   handleError,
+  handleInfo,
   handleSuccess,
   handleWarning
 };