@documentation-robotics/cli 0.1.13 → 0.3.0

package/dist/utils/errors.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/utils/errors.ts"],
-  "sourcesContent": ["/**\n * Error handling utilities with formatted output\n * Matches Python CLI error message formatting\n *\n * Error Categories:\n * - User Error (exit code 1): Invalid input, wrong format, element exists\n * - Not Found (exit code 2): File/element/model not found\n * - System Error (exit code 3): Permission denied, I/O failure\n * - Validation Error (exit code 4): Schema/reference/semantic validation failed\n * - Breaking Change (exit code 5): Version migration required\n */\n\nimport ansis from \"ansis\";\n\nconst MAX_SUGGESTIONS = 5;\n\nexport enum ErrorCategory {\n  USER = 1,\n  NOT_FOUND = 2,\n  SYSTEM = 3,\n  VALIDATION = 4,\n  BREAKING_CHANGE = 5,\n}\n\nexport interface ErrorContext {\n  operation?: string;\n  context?: string;\n  relatedElements?: string[];\n  partialProgress?: { completed: number; total: number };\n}\n\nexport class CLIError extends Error {\n  constructor(\n    message: string,\n    public exitCode: number = ErrorCategory.USER,\n    public suggestions?: string[],\n    public context?: ErrorContext\n  ) {\n    super(message);\n    this.name = \"CLIError\";\n  }\n\n  format(): string {\n    const lines: string[] = [];\n\n    lines.push(ansis.red(`Error: ${this.message}`));\n\n    if (this.context?.operation) {\n      lines.push(ansis.dim(`During: ${this.context.operation}`));\n    }\n\n    if (this.context?.partialProgress) {\n      const { completed, total } = this.context.partialProgress;\n      lines.push(\n        ansis.yellow(`\u26A0 Partial progress: ${completed}/${total} completed (operation rolled back)`)\n      );\n    }\n\n    if (this.context?.relatedElements && this.context.relatedElements.length > 0) {\n      lines.push(ansis.dim(\"Related elements:\"));\n      for (const elem of this.context.relatedElements.slice(0, MAX_SUGGESTIONS)) {\n        lines.push(ansis.dim(`  \u2022 ${elem}`));\n      }\n      if (this.context.relatedElements.length > MAX_SUGGESTIONS) {\n        lines.push(\n          ansis.dim(`  ... and ${this.context.relatedElements.length - MAX_SUGGESTIONS} more`)\n        );\n      }\n    }\n\n    if (this.suggestions && this.suggestions.length > 0) {\n      lines.push(\"\");\n      lines.push(ansis.dim(\"Suggestions:\"));\n      for (const suggestion of this.suggestions) {\n        lines.push(ansis.dim(`  \u2022 ${suggestion}`));\n      }\n    }\n\n    return lines.join(\"\\n\");\n  }\n}\n\nexport class ValidationError extends CLIError {\n  constructor(\n    message: string,\n    public errors: Array<{ layer?: string; elementId?: string; message: string }> = [],\n    suggestions?: string[],\n    context?: ErrorContext\n  ) {\n    super(message, ErrorCategory.VALIDATION, suggestions, context);\n    this.name = \"ValidationError\";\n  }\n\n  format(): string {\n    const lines: string[] = [];\n\n    lines.push(ansis.red(`Error: ${this.message}`));\n\n    if (this.errors.length > 0) {\n      // Show error count and grouping\n      const errorsByLayer: Record<string, Array<{ elementId?: string; message: string }>> = {};\n      for (const error of this.errors) {\n        const layer = error.layer || \"general\";\n        if (!errorsByLayer[layer]) {\n          errorsByLayer[layer] = [];\n        }\n        errorsByLayer[layer].push({ elementId: error.elementId, message: error.message });\n      }\n\n      lines.push(\"\");\n      lines.push(ansis.dim(`Validation errors: ${this.errors.length} found`));\n      lines.push(\"\");\n\n      const layerNames = Object.keys(errorsByLayer).sort();\n\n      for (const layer of layerNames) {\n        const layerErrors = errorsByLayer[layer];\n        lines.push(ansis.dim(`  [${layer}] ${layerErrors.length} error(s):`));\n\n        for (let i = 0; i < Math.min(layerErrors.length, MAX_SUGGESTIONS); i++) {\n          const error = layerErrors[i];\n          let detail = \"\";\n          if (error.elementId) {\n            detail = `    ${error.elementId}: ${error.message}`;\n          } else {\n            detail = `    ${error.message}`;\n          }\n          lines.push(ansis.dim(detail));\n        }\n\n        if (layerErrors.length > MAX_SUGGESTIONS) {\n          lines.push(\n            ansis.dim(`    ... and ${layerErrors.length - MAX_SUGGESTIONS} more in this layer`)\n          );\n        }\n      }\n    }\n\n    if (this.suggestions && this.suggestions.length > 0) {\n      lines.push(\"\");\n      lines.push(ansis.dim(\"Suggestions:\"));\n      for (const suggestion of this.suggestions) {\n        lines.push(ansis.dim(`  \u2022 ${suggestion}`));\n      }\n    }\n\n    return lines.join(\"\\n\");\n  }\n}\n\nexport class FileNotFoundError extends CLIError {\n  constructor(path: string, context?: string) {\n    const message = context ? `${context}: ${path}` : `File not found: ${path}`;\n    super(message, ErrorCategory.NOT_FOUND, [\n      `Check that the path is correct: ${path}`,\n      'Use \"dr init\" to create a new model',\n      'Use \"dr list <layer>\" to see available elements',\n    ]);\n    this.name = \"FileNotFoundError\";\n  }\n}\n\nexport class ElementNotFoundError extends CLIError {\n  constructor(elementId: string) {\n    super(`Element not found: ${elementId}`, ErrorCategory.NOT_FOUND, [\n      `Use \"dr search ${elementId}\" to find similar elements`,\n      'Use \"dr list <layer>\" to list all elements in a layer',\n      \"Check the element ID format: {layer}.{type}.{kebab-case-name}\",\n    ]);\n    this.name = \"ElementNotFoundError\";\n  }\n}\n\nexport class ModelNotFoundError extends CLIError {\n  constructor(rootPath: string = \".\") {\n    super(`No model found at ${rootPath}`, ErrorCategory.NOT_FOUND, [\n      `Run \"dr init\" to initialize a new model`,\n      \"Check that you are in the correct directory\",\n    ]);\n    this.name = \"ModelNotFoundError\";\n  }\n}\n\nexport class InvalidJSONError extends CLIError {\n  constructor(input: string, context?: string) {\n    const message = context ? `Invalid JSON in ${context}` : \"Invalid JSON format\";\n    super(message, ErrorCategory.USER, [\n      `Check your JSON syntax: ${input}`,\n      'Use single quotes to wrap JSON: --attributes \\'{\"key\":\"value\"}\\'',\n      \"Escape special characters properly\",\n    ]);\n    this.name = \"InvalidJSONError\";\n  }\n}\n\nexport function handleError(error: unknown): never {\n  if (error instanceof CLIError) {\n    console.error(error.format());\n    // Don't call process.exit() - rethrow so CLI wrapper can handle telemetry shutdown\n    throw error;\n  } else if (error instanceof Error) {\n    console.error(ansis.red(`Error: ${error.message}`));\n    if (process.env.DEBUG) {\n      console.error(ansis.dim(error.stack));\n    }\n    // Rethrow to allow CLI wrapper to handle shutdown\n    throw error;\n  } else {\n    console.error(ansis.red(\"An unexpected error occurred\"));\n    if (process.env.DEBUG) {\n      console.error(ansis.dim(String(error)));\n    }\n    // Create proper error to throw\n    throw new Error(String(error));\n  }\n}\n\nexport function handleWarning(message: string, suggestions?: string[]): void {\n  const lines: string[] = [];\n  lines.push(ansis.yellow(`Warning: ${message}`));\n  if (suggestions && suggestions.length > 0) {\n    lines.push(\"\");\n    lines.push(ansis.dim(\"Suggestions:\"));\n    for (const suggestion of suggestions) {\n      lines.push(ansis.dim(`  \u2022 ${suggestion}`));\n    }\n  }\n  console.warn(lines.join(\"\\n\"));\n}\n\nexport function handleSuccess(message: string, details?: Record<string, string>): void {\n  console.log(ansis.green(`\u2713 ${message}`));\n  if (details) {\n    for (const [key, value] of Object.entries(details)) {\n      console.log(ansis.dim(`  ${key}: ${value}`));\n    }\n  }\n}\n\n/**\n * Utility to extract common valid options for better error suggestions\n */\nexport function formatValidOptions(options: string[], heading: string = \"Valid options\"): string {\n  if (options.length === 0) return \"\";\n  if (options.length === 1) return `${heading}: ${options[0]}`;\n  return `${heading}: ${options.slice(0, -1).join(\", \")} or ${options[options.length - 1]}`;\n}\n\n/**\n * Categorize errors based on type, using stable error.code for system errors\n * Returns the appropriate ErrorCategory for a given error\n */\nexport function categorizeError(error: unknown): ErrorCategory {\n  if (error instanceof CLIError) {\n    return error.exitCode;\n  }\n\n  // Check for system errors using stable error.code\n  if (error instanceof Error && \"code\" in error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (typeof code === \"string\") {\n      // File not found errors should map to NOT_FOUND category\n      if (code === \"ENOENT\") {\n        return ErrorCategory.NOT_FOUND;\n      }\n      // Other system-level errors\n      const SYSTEM_ERROR_CODES = new Set([\"EACCES\", \"ENOSPC\", \"EIO\", \"EROFS\", \"EPERM\"]);\n      if (SYSTEM_ERROR_CODES.has(code)) {\n        return ErrorCategory.SYSTEM;\n      }\n    }\n  }\n\n  // Default to USER for other errors\n  return ErrorCategory.USER;\n}\n\n/**\n * Extract error message from any error type\n * Handles Error instances, strings, and unknown types consistently\n */\nexport function getErrorMessage(error: unknown): string {\n  if (error instanceof Error) {\n    return error.message;\n  }\n  return String(error);\n}\n\n/**\n * Simple fuzzy match to find similar strings (for typo suggestions)\n */\nexport function findSimilar(input: string, options: string[], maxDistance: number = 2): string[] {\n  return options\n    .map((option) => ({\n      option,\n      distance: levenshteinDistance(input.toLowerCase(), option.toLowerCase()),\n    }))\n    .filter(({ distance }) => distance <= maxDistance)\n    .sort((a, b) => a.distance - b.distance)\n    .slice(0, 3)\n    .map(({ option }) => option);\n}\n\n/**\n * Calculate Levenshtein distance for typo detection\n */\nfunction levenshteinDistance(a: string, b: string): number {\n  const matrix: number[][] = [];\n\n  for (let i = 0; i <= b.length; i++) {\n    matrix[i] = [i];\n  }\n\n  for (let j = 0; j <= a.length; j++) {\n    matrix[0][j] = j;\n  }\n\n  for (let i = 1; i <= b.length; i++) {\n    for (let j = 1; j <= a.length; j++) {\n      if (b.charAt(i - 1) === a.charAt(j - 1)) {\n        matrix[i][j] = matrix[i - 1][j - 1];\n      } else {\n        matrix[i][j] = Math.min(\n          matrix[i - 1][j - 1] + 1,\n          matrix[i][j - 1] + 1,\n          matrix[i - 1][j] + 1\n        );\n      }\n    }\n  }\n\n  return matrix[b.length][a.length];\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["/**\n * Error handling utilities with formatted output\n * Matches Python CLI error message formatting\n *\n * Error Categories:\n * - User Error (exit code 1): Invalid input, wrong format, element exists\n * - Not Found (exit code 2): File/element/model not found\n * - System Error (exit code 3): Permission denied, I/O failure\n * - Validation Error (exit code 4): Schema/reference/semantic validation failed\n * - Breaking Change (exit code 5): Version migration required\n */\n\nimport ansis from \"ansis\";\nimport { isJson } from \"./globals.js\";\n\nconst MAX_SUGGESTIONS = 5;\n\nexport enum ErrorCategory {\n  USER = 1,\n  NOT_FOUND = 2,\n  SYSTEM = 3,\n  VALIDATION = 4,\n  BREAKING_CHANGE = 5,\n}\n\nexport interface ErrorContext {\n  operation?: string;\n  context?: string;\n  relatedElements?: string[];\n  partialProgress?: { completed: number; total: number };\n}\n\nexport class CLIError extends Error {\n  constructor(\n    message: string,\n    public exitCode: number = ErrorCategory.USER,\n    public suggestions?: string[],\n    public context?: ErrorContext\n  ) {\n    super(message);\n    this.name = \"CLIError\";\n  }\n\n  format(): string {\n    const lines: string[] = [];\n\n    lines.push(ansis.red(`Error: ${this.message}`));\n\n    if (this.context?.operation) {\n      lines.push(ansis.dim(`During: ${this.context.operation}`));\n    }\n\n    if (this.context?.partialProgress) {\n      const { completed, total } = this.context.partialProgress;\n      lines.push(\n        ansis.yellow(`\u26A0 Partial progress: ${completed}/${total} completed (operation rolled back)`)\n      );\n    }\n\n    if (this.context?.relatedElements && this.context.relatedElements.length > 0) {\n      lines.push(ansis.dim(\"Related elements:\"));\n      for (const elem of this.context.relatedElements.slice(0, MAX_SUGGESTIONS)) {\n        lines.push(ansis.dim(`  \u2022 ${elem}`));\n      }\n      if (this.context.relatedElements.length > MAX_SUGGESTIONS) {\n        lines.push(\n          ansis.dim(`  ... and ${this.context.relatedElements.length - MAX_SUGGESTIONS} more`)\n        );\n      }\n    }\n\n    if (this.suggestions && this.suggestions.length > 0) {\n      lines.push(\"\");\n      lines.push(ansis.dim(\"Suggestions:\"));\n      for (const suggestion of this.suggestions) {\n        lines.push(ansis.dim(`  \u2022 ${suggestion}`));\n      }\n    }\n\n    return lines.join(\"\\n\");\n  }\n}\n\nexport class ValidationError extends CLIError {\n  constructor(\n    message: string,\n    public errors: Array<{ layer?: string; elementId?: string; message: string }> = [],\n    suggestions?: string[],\n    context?: ErrorContext\n  ) {\n    super(message, ErrorCategory.VALIDATION, suggestions, context);\n    this.name = \"ValidationError\";\n  }\n\n  format(): string {\n    const lines: string[] = [];\n\n    lines.push(ansis.red(`Error: ${this.message}`));\n\n    if (this.errors.length > 0) {\n      // Show error count and grouping\n      const errorsByLayer: Record<string, Array<{ elementId?: string; message: string }>> = {};\n      for (const error of this.errors) {\n        const layer = error.layer || \"general\";\n        if (!errorsByLayer[layer]) {\n          errorsByLayer[layer] = [];\n        }\n        errorsByLayer[layer].push({ elementId: error.elementId, message: error.message });\n      }\n\n      lines.push(\"\");\n      lines.push(ansis.dim(`Validation errors: ${this.errors.length} found`));\n      lines.push(\"\");\n\n      const layerNames = Object.keys(errorsByLayer).sort();\n\n      for (const layer of layerNames) {\n        const layerErrors = errorsByLayer[layer];\n        lines.push(ansis.dim(`  [${layer}] ${layerErrors.length} error(s):`));\n\n        for (let i = 0; i < Math.min(layerErrors.length, MAX_SUGGESTIONS); i++) {\n          const error = layerErrors[i];\n          let detail = \"\";\n          if (error.elementId) {\n            detail = `    ${error.elementId}: ${error.message}`;\n          } else {\n            detail = `    ${error.message}`;\n          }\n          lines.push(ansis.dim(detail));\n        }\n\n        if (layerErrors.length > MAX_SUGGESTIONS) {\n          lines.push(\n            ansis.dim(`    ... and ${layerErrors.length - MAX_SUGGESTIONS} more in this layer`)\n          );\n        }\n      }\n    }\n\n    if (this.suggestions && this.suggestions.length > 0) {\n      lines.push(\"\");\n      lines.push(ansis.dim(\"Suggestions:\"));\n      for (const suggestion of this.suggestions) {\n        lines.push(ansis.dim(`  \u2022 ${suggestion}`));\n      }\n    }\n\n    return lines.join(\"\\n\");\n  }\n}\n\nexport class FileNotFoundError extends CLIError {\n  constructor(path: string, context?: string) {\n    const message = context ? `${context}: ${path}` : `File not found: ${path}`;\n    super(message, ErrorCategory.NOT_FOUND, [\n      `Check that the path is correct: ${path}`,\n      'Use \"dr init\" to create a new model',\n      'Use \"dr list <layer>\" to see available elements',\n    ]);\n    this.name = \"FileNotFoundError\";\n  }\n}\n\nexport class ElementNotFoundError extends CLIError {\n  constructor(elementId: string) {\n    super(`Element not found: ${elementId}`, ErrorCategory.NOT_FOUND, [\n      `Use \"dr search ${elementId}\" to find similar elements`,\n      'Use \"dr list <layer>\" to list all elements in a layer',\n      \"Check the element ID format: {layer}.{type}.{kebab-case-name}\",\n    ]);\n    this.name = \"ElementNotFoundError\";\n  }\n}\n\nexport class ModelNotFoundError extends CLIError {\n  constructor(rootPath: string = \".\") {\n    super(`No model found at ${rootPath}`, ErrorCategory.NOT_FOUND, [\n      `Run \"dr init\" to initialize a new model`,\n      \"Check that you are in the correct directory\",\n    ]);\n    this.name = \"ModelNotFoundError\";\n  }\n}\n\nexport class InvalidJSONError extends CLIError {\n  constructor(input: string, context?: string) {\n    const message = context ? `Invalid JSON in ${context}` : \"Invalid JSON format\";\n    super(message, ErrorCategory.USER, [\n      `Check your JSON syntax: ${input}`,\n      'Use single quotes to wrap JSON: --attributes \\'{\"key\":\"value\"}\\'',\n      \"Escape special characters properly\",\n    ]);\n    this.name = \"InvalidJSONError\";\n  }\n}\n\nexport function handleError(error: unknown): never {\n  if (error instanceof CLIError) {\n    if (isJson()) {\n      const output: Record<string, unknown> = {\n        status: \"error\",\n        code: error.exitCode,\n        message: error.message,\n      };\n      if (error.suggestions && error.suggestions.length > 0) {\n        output.suggestions = error.suggestions;\n      }\n      if (error.context) {\n        if (error.context.operation) output.operation = error.context.operation;\n        if (error.context.relatedElements && error.context.relatedElements.length > 0) {\n          output.relatedElements = error.context.relatedElements;\n        }\n        if (error.context.partialProgress) {\n          output.partialProgress = error.context.partialProgress;\n        }\n      }\n      console.log(JSON.stringify(output));\n    } else {\n      console.error(error.format());\n    }\n    // Don't call process.exit() - rethrow so CLI wrapper can handle telemetry shutdown\n    throw error;\n  } else if (error instanceof Error) {\n    if (isJson()) {\n      const output: Record<string, unknown> = {\n        status: \"error\",\n        code: ErrorCategory.USER,\n        message: error.message,\n      };\n      if (process.env.DEBUG && error.stack) {\n        output.stack = error.stack;\n      }\n      console.log(JSON.stringify(output));\n    } else {\n      console.error(ansis.red(`Error: ${error.message}`));\n      if (process.env.DEBUG) {\n        console.error(ansis.dim(error.stack));\n      }\n    }\n    // Rethrow to allow CLI wrapper to handle shutdown\n    throw error;\n  } else {\n    if (isJson()) {\n      const output: Record<string, unknown> = {\n        status: \"error\",\n        code: ErrorCategory.USER,\n        message: \"An unexpected error occurred\",\n      };\n      if (process.env.DEBUG) {\n        output.details = String(error);\n      }\n      console.log(JSON.stringify(output));\n    } else {\n      console.error(ansis.red(\"An unexpected error occurred\"));\n      if (process.env.DEBUG) {\n        console.error(ansis.dim(String(error)));\n      }\n    }\n    // Create proper error to throw\n    throw new Error(String(error));\n  }\n}\n\nexport function handleWarning(message: string, suggestions?: string[]): void {\n  if (isJson()) {\n    // In JSON mode, emit warnings to stderr as structured JSON\n    const output: Record<string, unknown> = {\n      level: \"warning\",\n      message,\n    };\n    if (suggestions && suggestions.length > 0) {\n      output.suggestions = suggestions;\n    }\n    console.error(JSON.stringify(output));\n  } else {\n    const lines: string[] = [];\n    lines.push(ansis.yellow(`Warning: ${message}`));\n    if (suggestions && suggestions.length > 0) {\n      lines.push(\"\");\n      lines.push(ansis.dim(\"Suggestions:\"));\n      for (const suggestion of suggestions) {\n        lines.push(ansis.dim(`  \u2022 ${suggestion}`));\n      }\n    }\n    console.warn(lines.join(\"\\n\"));\n  }\n}\n\nexport function handleSuccess(message: string, details?: Record<string, unknown>, options?: { verbose?: boolean }): void {\n  if (isJson()) {\n    const output: Record<string, unknown> = {\n      ...details,\n      status: \"ok\",\n    };\n    console.log(JSON.stringify(output));\n  } else {\n    console.log(ansis.green(`\u2713 ${message}`));\n    // Only show details in non-JSON mode if verbose flag is set or details include changesetStatus/status\n    if (details && (options?.verbose || details.changesetStatus)) {\n      // Convert camelCase keys to PascalCase for display\n      for (const [key, value] of Object.entries(details)) {\n        const displayKey = keyToDisplayName(key);\n        console.log(ansis.dim(`  ${displayKey}: ${value}`));\n      }\n    }\n  }\n}\n\nfunction keyToDisplayName(key: string): string {\n  // Convert camelCase and snake_case to PascalCase/Title Case\n  return key\n    .replace(/([a-z])([A-Z])/g, '$1 $2') // camelCase to words\n    .replace(/_/g, ' ') // snake_case to words\n    .split(' ')\n    .map(word => word.charAt(0).toUpperCase() + word.slice(1))\n    .join(' ');\n}\n\nexport function handleInfo(message: string, details?: Record<string, string>): void {\n  if (isJson()) {\n    const output: Record<string, unknown> = {\n      level: \"info\",\n      message,\n    };\n    if (details) {\n      output.details = details;\n    }\n    console.error(JSON.stringify(output));\n  } else {\n    console.log(message);\n    if (details) {\n      for (const [key, value] of Object.entries(details)) {\n        console.log(ansis.dim(`  ${key}: ${value}`));\n      }\n    }\n  }\n}\n\n/**\n * Utility to extract common valid options for better error suggestions\n */\nexport function formatValidOptions(options: string[], heading: string = \"Valid options\"): string {\n  if (options.length === 0) return \"\";\n  if (options.length === 1) return `${heading}: ${options[0]}`;\n  return `${heading}: ${options.slice(0, -1).join(\", \")} or ${options[options.length - 1]}`;\n}\n\n/**\n * Categorize errors based on type, using stable error.code for system errors\n * Returns the appropriate ErrorCategory for a given error\n */\nexport function categorizeError(error: unknown): ErrorCategory {\n  if (error instanceof CLIError) {\n    return error.exitCode;\n  }\n\n  // Check for system errors using stable error.code\n  if (error instanceof Error && \"code\" in error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (typeof code === \"string\") {\n      // File not found errors should map to NOT_FOUND category\n      if (code === \"ENOENT\") {\n        return ErrorCategory.NOT_FOUND;\n      }\n      // Other system-level errors\n      const SYSTEM_ERROR_CODES = new Set([\"EACCES\", \"ENOSPC\", \"EIO\", \"EROFS\", \"EPERM\"]);\n      if (SYSTEM_ERROR_CODES.has(code)) {\n        return ErrorCategory.SYSTEM;\n      }\n    }\n  }\n\n  // Default to USER for other errors\n  return ErrorCategory.USER;\n}\n\n/**\n * Extract error message from any error type\n * Handles Error instances, strings, and unknown types consistently\n */\nexport function getErrorMessage(error: unknown): string {\n  if (error instanceof Error) {\n    return error.message;\n  }\n  return String(error);\n}\n\n/**\n * Simple fuzzy match to find similar strings (for typo suggestions)\n */\nexport function findSimilar(input: string, options: string[], maxDistance: number = 2): string[] {\n  return options\n    .map((option) => ({\n      option,\n      distance: levenshteinDistance(input.toLowerCase(), option.toLowerCase()),\n    }))\n    .filter(({ distance }) => distance <= maxDistance)\n    .sort((a, b) => a.distance - b.distance)\n    .slice(0, 3)\n    .map(({ option }) => option);\n}\n\n/**\n * Calculate Levenshtein distance for typo detection\n */\nfunction levenshteinDistance(a: string, b: string): number {\n  const matrix: number[][] = [];\n\n  for (let i = 0; i <= b.length; i++) {\n    matrix[i] = [i];\n  }\n\n  for (let j = 0; j <= a.length; j++) {\n    matrix[0][j] = j;\n  }\n\n  for (let i = 1; i <= b.length; i++) {\n    for (let j = 1; j <= a.length; j++) {\n      if (b.charAt(i - 1) === a.charAt(j - 1)) {\n        matrix[i][j] = matrix[i - 1][j - 1];\n      } else {\n        matrix[i][j] = Math.min(\n          matrix[i - 1][j - 1] + 1,\n          matrix[i][j - 1] + 1,\n          matrix[i - 1][j] + 1\n        );\n      }\n    }\n  }\n\n  return matrix[b.length][a.length];\n}\n"],
+  "mappings": "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",
   "names": ["ErrorCategory"]
 }

package/dist/utils/globals.js

@@ -2,6 +2,9 @@ let globalOptions = {};
 function setGlobalOptions(options) {
   globalOptions = { ...globalOptions, ...options };
 }
+function resetGlobalOptions() {
+  globalOptions = {};
+}
 function getGlobalOptions() {
   return { ...globalOptions };
 }
@@ -11,18 +14,31 @@ function isVerbose() {
 function isDebug() {
   return globalOptions.debug === !0;
 }
+function isJson() {
+  return globalOptions.json === !0;
+}
 function logVerbose(message) {
   isVerbose() && console.log(message);
 }
 function logDebug(message) {
   isDebug() && console.debug(`[DEBUG] ${message}`);
 }
+function setJsonMode(json) {
+  globalOptions.json = json;
+}
+function getCodebasePath() {
+  return globalOptions.codebasePath;
+}
 export {
+  getCodebasePath,
   getGlobalOptions,
   isDebug,
+  isJson,
   isVerbose,
   logDebug,
   logVerbose,
-  setGlobalOptions
+  resetGlobalOptions,
+  setGlobalOptions,
+  setJsonMode
 };
 //# sourceMappingURL=globals.js.map

package/dist/utils/globals.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/utils/globals.ts"],
-  "sourcesContent": ["/**\n * Global CLI option management\n */\n\nexport interface GlobalOptions {\n  verbose?: boolean;\n  debug?: boolean;\n}\n\n// Global state for CLI options\nlet globalOptions: GlobalOptions = {};\n\n/**\n * Set global CLI options\n */\nexport function setGlobalOptions(options: GlobalOptions): void {\n  globalOptions = { ...globalOptions, ...options };\n}\n\n/**\n * Get current global options\n */\nexport function getGlobalOptions(): GlobalOptions {\n  return { ...globalOptions };\n}\n\n/**\n * Check if verbose mode is enabled\n */\nexport function isVerbose(): boolean {\n  return globalOptions.verbose === true;\n}\n\n/**\n * Check if debug mode is enabled\n */\nexport function isDebug(): boolean {\n  return globalOptions.debug === true;\n}\n\n/**\n * Log verbose messages\n */\nexport function logVerbose(message: string): void {\n  if (isVerbose()) {\n    console.log(message);\n  }\n}\n\n/**\n * Log debug messages\n */\nexport function logDebug(message: string): void {\n  if (isDebug()) {\n    console.debug(`[DEBUG] ${message}`);\n  }\n}\n"],
-  "mappings": "AAUA,IAAI,gBAA+B,CAAA;AAK7B,SAAU,iBAAiB,SAAsB;AACrD,kBAAgB,EAAE,GAAG,eAAe,GAAG,QAAO;AAChD;AAKM,SAAU,mBAAgB;AAC9B,SAAO,EAAE,GAAG,cAAa;AAC3B;AAKM,SAAU,YAAS;AACvB,SAAO,cAAc,YAAY;AACnC;AAKM,SAAU,UAAO;AACrB,SAAO,cAAc,UAAU;AACjC;AAKM,SAAU,WAAW,SAAe;AACxC,EAAI,UAAS,KACX,QAAQ,IAAI,OAAO;AAEvB;AAKM,SAAU,SAAS,SAAe;AACtC,EAAI,QAAO,KACT,QAAQ,MAAM,WAAW,OAAO,EAAE;AAEtC;",
+  "sourcesContent": ["/**\n * Global CLI option management\n */\n\nexport interface GlobalOptions {\n  verbose?: boolean;\n  debug?: boolean;\n  json?: boolean;\n  codebasePath?: string;\n}\n\n// Global state for CLI options\nlet globalOptions: GlobalOptions = {};\n\n/**\n * Set global CLI options\n */\nexport function setGlobalOptions(options: GlobalOptions): void {\n  globalOptions = { ...globalOptions, ...options };\n}\n\n/**\n * Reset global CLI options to empty state\n */\nexport function resetGlobalOptions(): void {\n  globalOptions = {};\n}\n\n/**\n * Get current global options\n */\nexport function getGlobalOptions(): GlobalOptions {\n  return { ...globalOptions };\n}\n\n/**\n * Check if verbose mode is enabled\n */\nexport function isVerbose(): boolean {\n  return globalOptions.verbose === true;\n}\n\n/**\n * Check if debug mode is enabled\n */\nexport function isDebug(): boolean {\n  return globalOptions.debug === true;\n}\n\n/**\n * Check if JSON mode is enabled\n */\nexport function isJson(): boolean {\n  return globalOptions.json === true;\n}\n\n/**\n * Log verbose messages\n */\nexport function logVerbose(message: string): void {\n  if (isVerbose()) {\n    console.log(message);\n  }\n}\n\n/**\n * Log debug messages\n */\nexport function logDebug(message: string): void {\n  if (isDebug()) {\n    console.debug(`[DEBUG] ${message}`);\n  }\n}\n\n/**\n * Set JSON mode\n */\nexport function setJsonMode(json: boolean): void {\n  globalOptions.json = json;\n}\n\n/**\n * Get codebase path from global options\n */\nexport function getCodebasePath(): string | undefined {\n  return globalOptions.codebasePath;\n}\n"],
+  "mappings": "AAYA,IAAI,gBAA+B,CAAA;AAK7B,SAAU,iBAAiB,SAAsB;AACrD,kBAAgB,EAAE,GAAG,eAAe,GAAG,QAAO;AAChD;AAKM,SAAU,qBAAkB;AAChC,kBAAgB,CAAA;AAClB;AAKM,SAAU,mBAAgB;AAC9B,SAAO,EAAE,GAAG,cAAa;AAC3B;AAKM,SAAU,YAAS;AACvB,SAAO,cAAc,YAAY;AACnC;AAKM,SAAU,UAAO;AACrB,SAAO,cAAc,UAAU;AACjC;AAKM,SAAU,SAAM;AACpB,SAAO,cAAc,SAAS;AAChC;AAKM,SAAU,WAAW,SAAe;AACxC,EAAI,UAAS,KACX,QAAQ,IAAI,OAAO;AAEvB;AAKM,SAAU,SAAS,SAAe;AACtC,EAAI,QAAO,KACT,QAAQ,MAAM,WAAW,OAAO,EAAE;AAEtC;AAKM,SAAU,YAAY,MAAa;AACvC,gBAAc,OAAO;AACvB;AAKM,SAAU,kBAAe;AAC7B,SAAO,cAAc;AACvB;",
   "names": []
 }

package/dist/utils/project-paths.js

@@ -1,6 +1,7 @@
 import { fileExists } from "./file-io.js";
-import { join, dirname } from "path";
-const MAX_SEARCH_DEPTH = 5, PROJECT_FOLDER_NAME = "documentation-robotics", SPEC_FOLDER_NAME = ".dr";
+import { join, dirname, resolve } from "path";
+import { stat } from "fs/promises";
+const MAX_SEARCH_DEPTH = 5, PROJECT_FOLDER_NAME = "documentation-robotics", SPEC_FOLDER_NAME = ".dr", FARM_FILE_NAME = "farm.yaml";
 async function findProjectRoot(startPath) {
   let currentPath = startPath || process.cwd();
   for (let depth = 0; depth < MAX_SEARCH_DEPTH; depth++) {
@@ -35,11 +36,57 @@ async function getSpecReferencePath(startPath) {
 async function isInDRProject(startPath) {
   return await findProjectRoot(startPath) !== null;
 }
+async function findFarmRoot(startPath) {
+  if (process.env.DR_FARM_PATH) {
+    const envPath = resolve(process.env.DR_FARM_PATH), farmFilePath = join(envPath, FARM_FILE_NAME);
+    if (await fileExists(farmFilePath))
+      return envPath;
+    throw new Error(`Invalid DR_FARM_PATH: ${process.env.DR_FARM_PATH}
+Expected farm.yaml at: ${farmFilePath}
+Ensure DR_FARM_PATH points to a directory containing a farm.yaml file.`);
+  }
+  let currentPath = startPath || process.cwd();
+  for (let depth = 0; depth < MAX_SEARCH_DEPTH; depth++) {
+    const farmFilePath = join(currentPath, FARM_FILE_NAME);
+    if (await fileExists(farmFilePath))
+      return currentPath;
+    const parentPath = dirname(currentPath);
+    if (parentPath === currentPath)
+      break;
+    currentPath = parentPath;
+  }
+  return null;
+}
+const MODEL_LAYOUT_CANDIDATES = [
+  { layout: "standard", segments: [PROJECT_FOLDER_NAME, "model"] },
+  { layout: "legacy", segments: ["model"] },
+  { layout: "detached", segments: [] }
+];
+async function resolveModelDirectory(basePath, options = {}) {
+  const resolvedBase = resolve(basePath);
+  for (const candidate of MODEL_LAYOUT_CANDIDATES) {
+    const modelDir = join(resolvedBase, ...candidate.segments), stats = await statIfExists(modelDir);
+    if (stats && !(options.requireManifest && (!stats.isDirectory() || !await statIfExists(join(modelDir, "manifest.yaml")))))
+      return { modelDir, layout: candidate.layout, isDirectory: stats.isDirectory() };
+  }
+  return null;
+}
+async function statIfExists(target) {
+  try {
+    return await stat(target);
+  } catch (err) {
+    if (err?.code === "ENOENT")
+      return;
+    throw err;
+  }
+}
 export {
+  findFarmRoot,
   findProjectRoot,
   getDocumentationRobotsPath,
   getModelPath,
   getSpecReferencePath,
-  isInDRProject
+  isInDRProject,
+  resolveModelDirectory
 };
 //# sourceMappingURL=project-paths.js.map

package/dist/utils/project-paths.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/utils/project-paths.ts"],
-  "sourcesContent": ["/**\n * Project Path Utilities\n *\n * Handles finding project root and related paths in the DR project structure:\n *\n * my-project/\n * \u251C\u2500\u2500 .dr/                           # Reference spec (ephemeral, git-ignored)\n * \u2502   \u251C\u2500\u2500 manifest.json              # Installed spec version\n * \u2502   \u2514\u2500\u2500 schemas/\n * \u2514\u2500\u2500 documentation-robotics/        # Project model (permanent, git-committed)\n *     \u251C\u2500\u2500 model/\n *     \u2502   \u251C\u2500\u2500 manifest.yaml       # Model spec version\n *     \u2502   \u2514\u2500\u2500 layers/\n *     \u251C\u2500\u2500 annotations/\n *     \u2514\u2500\u2500 changesets/\n */\n\nimport { fileExists } from \"./file-io.js\";\nimport { join, dirname } from \"path\";\n\nconst MAX_SEARCH_DEPTH = 5;\nconst PROJECT_FOLDER_NAME = \"documentation-robotics\";\nconst SPEC_FOLDER_NAME = \".dr\";\n\n/**\n * Find the project root by searching for the documentation-robotics/ folder\n *\n * Searches upward from the current working directory up to MAX_SEARCH_DEPTH levels.\n * Returns the directory containing the documentation_robotics/ folder.\n *\n * @param startPath - Optional starting path (defaults to process.cwd())\n * @returns Path to project root, or null if not found\n *\n * @example\n * // From /home/user/my-project/documentation-robotics/model/01_motivation\n * // Returns: /home/user/my-project\n * const root = await findProjectRoot();\n */\nexport async function findProjectRoot(startPath?: string): Promise<string | null> {\n  let currentPath = startPath || process.cwd();\n\n  for (let depth = 0; depth < MAX_SEARCH_DEPTH; depth++) {\n    const projectPath = join(currentPath, PROJECT_FOLDER_NAME);\n\n    if (await fileExists(projectPath)) {\n      return currentPath;\n    }\n\n    // Move up one directory\n    const parentPath = dirname(currentPath);\n\n    // Check if we've reached the root\n    if (parentPath === currentPath) {\n      break;\n    }\n\n    currentPath = parentPath;\n  }\n\n  return null;\n}\n\n/**\n * Get the path to the documentation-robotics/ folder\n *\n * @param startPath - Optional starting path (defaults to process.cwd())\n * @returns Path to documentation-robotics/ folder, or null if not found\n */\nexport async function getDocumentationRobotsPath(startPath?: string): Promise<string | null> {\n  const root = await findProjectRoot(startPath);\n  return root ? join(root, PROJECT_FOLDER_NAME) : null;\n}\n\n/**\n * Get the path to the model directory (documentation-robotics/model/)\n *\n * @param startPath - Optional starting path (defaults to process.cwd())\n * @returns Path to model directory, or null if not found\n */\nexport async function getModelPath(startPath?: string): Promise<string | null> {\n  const drPath = await getDocumentationRobotsPath(startPath);\n  if (!drPath) return null;\n\n  const modelPath = join(drPath, \"model\");\n  return (await fileExists(modelPath)) ? modelPath : null;\n}\n\n/**\n * Get the path to the .dr/ folder (spec reference directory)\n *\n * @param startPath - Optional starting path (defaults to process.cwd())\n * @returns Path to .dr/ folder, or null if not found\n */\nexport async function getSpecReferencePath(startPath?: string): Promise<string | null> {\n  const root = await findProjectRoot(startPath);\n  if (!root) return null;\n\n  const specPath = join(root, SPEC_FOLDER_NAME);\n  return (await fileExists(specPath)) ? specPath : null;\n}\n\n/**\n * Check if currently in a DR project\n *\n * @param startPath - Optional starting path (defaults to process.cwd())\n * @returns True if documentation-robotics/ folder exists in hierarchy\n */\nexport async function isInDRProject(startPath?: string): Promise<boolean> {\n  return (await findProjectRoot(startPath)) !== null;\n}\n"],
-  "mappings": "AAiBA,SAAS,kBAAkB;AAC3B,SAAS,MAAM,eAAe;AAE9B,MAAM,mBAAmB,GACnB,sBAAsB,0BACtB,mBAAmB;AAgBzB,eAAsB,gBAAgB,WAAkB;AACtD,MAAI,cAAc,aAAa,QAAQ,IAAG;AAE1C,WAAS,QAAQ,GAAG,QAAQ,kBAAkB,SAAS;AACrD,UAAM,cAAc,KAAK,aAAa,mBAAmB;AAEzD,QAAI,MAAM,WAAW,WAAW;AAC9B,aAAO;AAIT,UAAM,aAAa,QAAQ,WAAW;AAGtC,QAAI,eAAe;AACjB;AAGF,kBAAc;EAChB;AAEA,SAAO;AACT;AAQA,eAAsB,2BAA2B,WAAkB;AACjE,QAAM,OAAO,MAAM,gBAAgB,SAAS;AAC5C,SAAO,OAAO,KAAK,MAAM,mBAAmB,IAAI;AAClD;AAQA,eAAsB,aAAa,WAAkB;AACnD,QAAM,SAAS,MAAM,2BAA2B,SAAS;AACzD,MAAI,CAAC;AAAQ,WAAO;AAEpB,QAAM,YAAY,KAAK,QAAQ,OAAO;AACtC,SAAQ,MAAM,WAAW,SAAS,IAAK,YAAY;AACrD;AAQA,eAAsB,qBAAqB,WAAkB;AAC3D,QAAM,OAAO,MAAM,gBAAgB,SAAS;AAC5C,MAAI,CAAC;AAAM,WAAO;AAElB,QAAM,WAAW,KAAK,MAAM,gBAAgB;AAC5C,SAAQ,MAAM,WAAW,QAAQ,IAAK,WAAW;AACnD;AAQA,eAAsB,cAAc,WAAkB;AACpD,SAAQ,MAAM,gBAAgB,SAAS,MAAO;AAChD;",
+  "sourcesContent": ["/**\n * Project Path Utilities\n *\n * Handles finding project root and related paths in the DR project structure:\n *\n * my-project/\n * \u251C\u2500\u2500 .dr/                           # Reference spec (ephemeral, git-ignored)\n * \u2502   \u251C\u2500\u2500 manifest.json              # Installed spec version\n * \u2502   \u2514\u2500\u2500 schemas/\n * \u2514\u2500\u2500 documentation-robotics/        # Project model (permanent, git-committed)\n *     \u251C\u2500\u2500 model/\n *     \u2502   \u251C\u2500\u2500 manifest.yaml       # Model spec version\n *     \u2502   \u2514\u2500\u2500 layers/\n *     \u251C\u2500\u2500 annotations/\n *     \u2514\u2500\u2500 changesets/\n */\n\nimport { fileExists } from \"./file-io.js\";\nimport { join, dirname, resolve } from \"path\";\nimport { stat } from \"fs/promises\";\nimport type { Stats } from \"fs\";\n\nconst MAX_SEARCH_DEPTH = 5;\nconst PROJECT_FOLDER_NAME = \"documentation-robotics\";\nconst SPEC_FOLDER_NAME = \".dr\";\nconst FARM_FILE_NAME = \"farm.yaml\";\n\n/**\n * Find the project root by searching for the documentation-robotics/ folder\n *\n * Searches upward from the current working directory up to MAX_SEARCH_DEPTH levels.\n * Returns the directory containing the documentation_robotics/ folder.\n *\n * @param startPath - Optional starting path (defaults to process.cwd())\n * @returns Path to project root, or null if not found\n *\n * @example\n * // From /home/user/my-project/documentation-robotics/model/01_motivation\n * // Returns: /home/user/my-project\n * const root = await findProjectRoot();\n */\nexport async function findProjectRoot(startPath?: string): Promise<string | null> {\n  let currentPath = startPath || process.cwd();\n\n  for (let depth = 0; depth < MAX_SEARCH_DEPTH; depth++) {\n    const projectPath = join(currentPath, PROJECT_FOLDER_NAME);\n\n    if (await fileExists(projectPath)) {\n      return currentPath;\n    }\n\n    // Move up one directory\n    const parentPath = dirname(currentPath);\n\n    // Check if we've reached the root\n    if (parentPath === currentPath) {\n      break;\n    }\n\n    currentPath = parentPath;\n  }\n\n  return null;\n}\n\n/**\n * Get the path to the documentation-robotics/ folder\n *\n * @param startPath - Optional starting path (defaults to process.cwd())\n * @returns Path to documentation-robotics/ folder, or null if not found\n */\nexport async function getDocumentationRobotsPath(startPath?: string): Promise<string | null> {\n  const root = await findProjectRoot(startPath);\n  return root ? join(root, PROJECT_FOLDER_NAME) : null;\n}\n\n/**\n * Get the path to the model directory (documentation-robotics/model/)\n *\n * @param startPath - Optional starting path (defaults to process.cwd())\n * @returns Path to model directory, or null if not found\n */\nexport async function getModelPath(startPath?: string): Promise<string | null> {\n  const drPath = await getDocumentationRobotsPath(startPath);\n  if (!drPath) return null;\n\n  const modelPath = join(drPath, \"model\");\n  return (await fileExists(modelPath)) ? modelPath : null;\n}\n\n/**\n * Get the path to the .dr/ folder (spec reference directory)\n *\n * @param startPath - Optional starting path (defaults to process.cwd())\n * @returns Path to .dr/ folder, or null if not found\n */\nexport async function getSpecReferencePath(startPath?: string): Promise<string | null> {\n  const root = await findProjectRoot(startPath);\n  if (!root) return null;\n\n  const specPath = join(root, SPEC_FOLDER_NAME);\n  return (await fileExists(specPath)) ? specPath : null;\n}\n\n/**\n * Check if currently in a DR project\n *\n * @param startPath - Optional starting path (defaults to process.cwd())\n * @returns True if documentation-robotics/ folder exists in hierarchy\n */\nexport async function isInDRProject(startPath?: string): Promise<boolean> {\n  return (await findProjectRoot(startPath)) !== null;\n}\n\n/**\n * Find the farm root by searching for the farm.yaml file\n *\n * Resolution order:\n * 1. DR_FARM_PATH environment variable (if set, must point to a directory with farm.yaml)\n * 2. Directory walk upward from startPath (default: process.cwd()) up to MAX_SEARCH_DEPTH levels\n *\n * @param startPath - Optional starting path (defaults to process.cwd())\n * @returns Path to farm root, or null if not found\n *\n * @example\n * // From /home/user/architecture-farm/service-a-model/documentation-robotics/model\n * // Returns: /home/user/architecture-farm (if farm.yaml exists there)\n * const farmRoot = await findFarmRoot();\n *\n * @example\n * // With DR_FARM_PATH environment variable set\n * // Returns: /path/specified/in/env (if farm.yaml exists there)\n * const farmRoot = await findFarmRoot();\n */\nexport async function findFarmRoot(startPath?: string): Promise<string | null> {\n  // Check DR_FARM_PATH environment variable first\n  if (process.env.DR_FARM_PATH) {\n    const envPath = resolve(process.env.DR_FARM_PATH);\n    const farmFilePath = join(envPath, FARM_FILE_NAME);\n    if (await fileExists(farmFilePath)) {\n      return envPath;\n    }\n    // If DR_FARM_PATH is set but invalid, throw a clear error rather than silently returning null\n    throw new Error(\n      `Invalid DR_FARM_PATH: ${process.env.DR_FARM_PATH}\\n` +\n      `Expected farm.yaml at: ${farmFilePath}\\n` +\n      `Ensure DR_FARM_PATH points to a directory containing a farm.yaml file.`\n    );\n  }\n\n  let currentPath = startPath || process.cwd();\n\n  for (let depth = 0; depth < MAX_SEARCH_DEPTH; depth++) {\n    const farmFilePath = join(currentPath, FARM_FILE_NAME);\n\n    if (await fileExists(farmFilePath)) {\n      return currentPath;\n    }\n\n    // Move up one directory\n    const parentPath = dirname(currentPath);\n\n    // Check if we've reached the root\n    if (parentPath === currentPath) {\n      break;\n    }\n\n    currentPath = parentPath;\n  }\n\n  return null;\n}\n\n/**\n * Layouts under which a model directory can be found below a base path.\n * - `standard`: `{base}/documentation-robotics/model/` (a project that self-hosts its model)\n * - `legacy`: `{base}/model/`\n * - `detached`: `{base}` itself holds `manifest.yaml` and the layer folders\n */\nexport type ModelLayout = \"standard\" | \"legacy\" | \"detached\";\n\nexport interface ResolvedModelDirectory {\n  /** Absolute path of the directory that holds the model (manifest.yaml and layer folders) */\n  modelDir: string;\n  layout: ModelLayout;\n  /** False when something that is not a directory sits at the resolved path */\n  isDirectory: boolean;\n}\n\nconst MODEL_LAYOUT_CANDIDATES: ReadonlyArray<{ layout: ModelLayout; segments: string[] }> = [\n  { layout: \"standard\", segments: [PROJECT_FOLDER_NAME, \"model\"] },\n  { layout: \"legacy\", segments: [\"model\"] },\n  { layout: \"detached\", segments: [] },\n];\n\n/**\n * Locate a model directory under `basePath`, trying the standard, legacy and detached\n * layouts in that order. Shared by the composed reference validator (resolving external\n * models) and `dr farm add` (adopting a codebase's self-hosted model).\n *\n * Only a missing path moves the search on to the next candidate; permission and I/O\n * errors propagate so callers never mistake them for \"no model here\".\n *\n * @param basePath - Project root, model folder or any path to probe\n * @param options.requireManifest - When true, a candidate counts only if it is a directory\n *   that contains `manifest.yaml`; otherwise the first existing path wins (even a file, so\n *   the caller can report it)\n * @returns The resolved directory, or null when none of the candidates exists\n */\nexport async function resolveModelDirectory(\n  basePath: string,\n  options: { requireManifest?: boolean } = {}\n): Promise<ResolvedModelDirectory | null> {\n  const resolvedBase = resolve(basePath);\n\n  for (const candidate of MODEL_LAYOUT_CANDIDATES) {\n    const modelDir = join(resolvedBase, ...candidate.segments);\n    const stats = await statIfExists(modelDir);\n    if (!stats) {\n      continue;\n    }\n\n    if (options.requireManifest) {\n      if (!stats.isDirectory() || !(await statIfExists(join(modelDir, \"manifest.yaml\")))) {\n        continue;\n      }\n    }\n\n    return { modelDir, layout: candidate.layout, isDirectory: stats.isDirectory() };\n  }\n\n  return null;\n}\n\nasync function statIfExists(target: string): Promise<Stats | undefined> {\n  try {\n    return await stat(target);\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException)?.code === \"ENOENT\") {\n      return undefined;\n    }\n    throw err;\n  }\n}\n"],
+  "mappings": "AAiBA,SAAS,kBAAkB;AAC3B,SAAS,MAAM,SAAS,eAAe;AACvC,SAAS,YAAY;AAGrB,MAAM,mBAAmB,GACnB,sBAAsB,0BACtB,mBAAmB,OACnB,iBAAiB;AAgBvB,eAAsB,gBAAgB,WAAkB;AACtD,MAAI,cAAc,aAAa,QAAQ,IAAG;AAE1C,WAAS,QAAQ,GAAG,QAAQ,kBAAkB,SAAS;AACrD,UAAM,cAAc,KAAK,aAAa,mBAAmB;AAEzD,QAAI,MAAM,WAAW,WAAW;AAC9B,aAAO;AAIT,UAAM,aAAa,QAAQ,WAAW;AAGtC,QAAI,eAAe;AACjB;AAGF,kBAAc;EAChB;AAEA,SAAO;AACT;AAQA,eAAsB,2BAA2B,WAAkB;AACjE,QAAM,OAAO,MAAM,gBAAgB,SAAS;AAC5C,SAAO,OAAO,KAAK,MAAM,mBAAmB,IAAI;AAClD;AAQA,eAAsB,aAAa,WAAkB;AACnD,QAAM,SAAS,MAAM,2BAA2B,SAAS;AACzD,MAAI,CAAC;AAAQ,WAAO;AAEpB,QAAM,YAAY,KAAK,QAAQ,OAAO;AACtC,SAAQ,MAAM,WAAW,SAAS,IAAK,YAAY;AACrD;AAQA,eAAsB,qBAAqB,WAAkB;AAC3D,QAAM,OAAO,MAAM,gBAAgB,SAAS;AAC5C,MAAI,CAAC;AAAM,WAAO;AAElB,QAAM,WAAW,KAAK,MAAM,gBAAgB;AAC5C,SAAQ,MAAM,WAAW,QAAQ,IAAK,WAAW;AACnD;AAQA,eAAsB,cAAc,WAAkB;AACpD,SAAQ,MAAM,gBAAgB,SAAS,MAAO;AAChD;AAsBA,eAAsB,aAAa,WAAkB;AAEnD,MAAI,QAAQ,IAAI,cAAc;AAC5B,UAAM,UAAU,QAAQ,QAAQ,IAAI,YAAY,GAC1C,eAAe,KAAK,SAAS,cAAc;AACjD,QAAI,MAAM,WAAW,YAAY;AAC/B,aAAO;AAGT,UAAM,IAAI,MACR,yBAAyB,QAAQ,IAAI,YAAY;yBACvB,YAAY;uEACkC;EAE5E;AAEA,MAAI,cAAc,aAAa,QAAQ,IAAG;AAE1C,WAAS,QAAQ,GAAG,QAAQ,kBAAkB,SAAS;AACrD,UAAM,eAAe,KAAK,aAAa,cAAc;AAErD,QAAI,MAAM,WAAW,YAAY;AAC/B,aAAO;AAIT,UAAM,aAAa,QAAQ,WAAW;AAGtC,QAAI,eAAe;AACjB;AAGF,kBAAc;EAChB;AAEA,SAAO;AACT;AAkBA,MAAM,0BAAsF;EAC1F,EAAE,QAAQ,YAAY,UAAU,CAAC,qBAAqB,OAAO,EAAC;EAC9D,EAAE,QAAQ,UAAU,UAAU,CAAC,OAAO,EAAC;EACvC,EAAE,QAAQ,YAAY,UAAU,CAAA,EAAE;;AAiBpC,eAAsB,sBACpB,UACA,UAAyC,CAAA,GAAE;AAE3C,QAAM,eAAe,QAAQ,QAAQ;AAErC,aAAW,aAAa,yBAAyB;AAC/C,UAAM,WAAW,KAAK,cAAc,GAAG,UAAU,QAAQ,GACnD,QAAQ,MAAM,aAAa,QAAQ;AACzC,QAAK,SAID,UAAQ,oBACN,CAAC,MAAM,YAAW,KAAM,CAAE,MAAM,aAAa,KAAK,UAAU,eAAe,CAAC;AAKlF,aAAO,EAAE,UAAU,QAAQ,UAAU,QAAQ,aAAa,MAAM,YAAW,EAAE;EAC/E;AAEA,SAAO;AACT;AAEA,eAAe,aAAa,QAAc;AACxC,MAAI;AACF,WAAO,MAAM,KAAK,MAAM;EAC1B,SAAS,KAAK;AACZ,QAAK,KAA+B,SAAS;AAC3C;AAEF,UAAM;EACR;AACF;",
   "names": []
 }

package/dist/utils/reference-path-parser.js

@@ -0,0 +1,49 @@
+class ReferencePathParseError extends Error {
+  kind = "malformed-qualified-path";
+  constructor(message) {
+    super(message), this.name = "ReferencePathParseError", Object.setPrototypeOf(this, ReferencePathParseError.prototype);
+  }
+}
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i, QUALIFIED_PREFIX_PATTERN = /^@([a-z0-9][a-z0-9_-]*)\//i, ELEMENT_PATH_PATTERN = /^[a-z_][a-z0-9_-]*(\.[a-z_][a-z0-9_-]*)+$/;
+function parseReferencePath(path) {
+  if (!path || typeof path != "string" || path.trim() === "")
+    throw createParseError("Empty reference path");
+  const trimmedPath = path.trim(), qualifiedMatch = trimmedPath.match(QUALIFIED_PREFIX_PATTERN);
+  if (qualifiedMatch) {
+    const modelName = qualifiedMatch[1].toLowerCase(), segment = trimmedPath.substring(qualifiedMatch[0].length);
+    if (!segment || segment.trim() === "")
+      throw createParseError("Qualified reference missing segment after '@{model-name}/'");
+    if (UUID_PATTERN.test(segment))
+      throw createParseError("Qualified references cannot reference UUIDs; use '@{model-name}/{layer}.{type}.{name}' format");
+    if (!ELEMENT_PATH_PATTERN.test(segment))
+      throw createParseError(`Qualified reference has invalid element path: '${segment}'. Use format '@{model-name}/{layer}.{type}.{name}'`);
+    return {
+      modelName,
+      segment,
+      isQualified: !0
+    };
+  }
+  if (UUID_PATTERN.test(trimmedPath))
+    return {
+      modelName: void 0,
+      segment: trimmedPath,
+      isQualified: !1
+    };
+  if (ELEMENT_PATH_PATTERN.test(trimmedPath))
+    return {
+      modelName: void 0,
+      segment: trimmedPath,
+      isQualified: !1
+    };
+  throw createParseError(`Invalid reference path format: '${trimmedPath}'. Use one of: '{layer}.{type}.{name}', UUID, or '@{model-name}/{layer}.{type}.{name}'`);
+}
+function createParseError(message) {
+  return new ReferencePathParseError(message);
+}
+export {
+  QUALIFIED_PREFIX_PATTERN,
+  ReferencePathParseError,
+  UUID_PATTERN,
+  parseReferencePath
+};
+//# sourceMappingURL=reference-path-parser.js.map

package/dist/utils/reference-path-parser.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/reference-path-parser.ts"],
+  "sourcesContent": ["/**\n * Reference path parser for qualified and unqualified element references.\n *\n * Supports parsing reference targets in the following formats:\n * - Unqualified: {layer}.{type}.{name} (e.g., motivation.goal.increase-revenue)\n * - Unqualified UUID: UUIDv4 format\n * - Qualified: @{model-name}/{layer}.{type}.{name} (e.g., @auth-service/api.operation.authenticate)\n *\n * The parser distinguishes between parse-level errors (malformed qualified paths)\n * and reference resolution errors (unknown model or broken reference).\n */\n\nexport interface ParsedReferencePath {\n  /** Model qualifier if present (without @ or /) */\n  modelName?: string;\n  /** The underlying {layer}.{type}.{name} segment or UUID */\n  segment: string;\n  /** Whether this is a qualified reference */\n  isQualified: boolean;\n}\n\nexport class ReferencePathParseError extends Error {\n  readonly kind = \"malformed-qualified-path\" as const;\n\n  constructor(message: string) {\n    super(message);\n    this.name = \"ReferencePathParseError\";\n    Object.setPrototypeOf(this, ReferencePathParseError.prototype);\n  }\n}\n\nexport const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\nexport const QUALIFIED_PREFIX_PATTERN = /^@([a-z0-9][a-z0-9_-]*)\\//i;\nconst ELEMENT_PATH_PATTERN = /^[a-z_][a-z0-9_-]*(\\.[a-z_][a-z0-9_-]*)+$/;\n\n/**\n * Parse a reference path, extracting model qualifier and underlying segment.\n *\n * @param path The reference path string to parse\n * @returns Parsed reference information on success\n * @throws ReferencePathParseError if the path is malformed\n *\n * @example\n * // Unqualified path\n * parseReferencePath(\"motivation.goal.increase-revenue\")\n * // => { modelName: undefined, segment: \"motivation.goal.increase-revenue\", isQualified: false }\n *\n * // Qualified path\n * parseReferencePath(\"@auth-service/api.operation.authenticate\")\n * // => { modelName: \"auth-service\", segment: \"api.operation.authenticate\", isQualified: true }\n *\n * // UUID\n * parseReferencePath(\"550e8400-e29b-41d4-a716-446655440000\")\n * // => { modelName: undefined, segment: \"550e8400-e29b-41d4-a716-446655440000\", isQualified: false }\n *\n * // Qualified UUID (not yet supported, will throw)\n * parseReferencePath(\"@model/550e8400-e29b-41d4-a716-446655440000\")\n * // => throws ReferencePathParseError\n */\nexport function parseReferencePath(path: string): ParsedReferencePath {\n  if (!path || typeof path !== \"string\" || path.trim() === \"\") {\n    throw createParseError(\"Empty reference path\");\n  }\n\n  const trimmedPath = path.trim();\n\n  // Check for qualified prefix (@model-name/)\n  const qualifiedMatch = trimmedPath.match(QUALIFIED_PREFIX_PATTERN);\n\n  if (qualifiedMatch) {\n    const modelName = qualifiedMatch[1].toLowerCase();\n    const segment = trimmedPath.substring(qualifiedMatch[0].length);\n\n    // Validate segment format\n    if (!segment || segment.trim() === \"\") {\n      throw createParseError(\n        \"Qualified reference missing segment after '@{model-name}/'\"\n      );\n    }\n\n    // Qualified paths must use dot-separated format, not UUIDs\n    if (UUID_PATTERN.test(segment)) {\n      throw createParseError(\n        \"Qualified references cannot reference UUIDs; use '@{model-name}/{layer}.{type}.{name}' format\"\n      );\n    }\n\n    // Validate segment is a valid element path\n    if (!ELEMENT_PATH_PATTERN.test(segment)) {\n      throw createParseError(\n        `Qualified reference has invalid element path: '${segment}'. Use format '@{model-name}/{layer}.{type}.{name}'`\n      );\n    }\n\n    return {\n      modelName,\n      segment,\n      isQualified: true,\n    };\n  }\n\n  // Unqualified reference\n  // Accept either UUID or dot-separated element path\n  if (UUID_PATTERN.test(trimmedPath)) {\n    return {\n      modelName: undefined,\n      segment: trimmedPath,\n      isQualified: false,\n    };\n  }\n\n  if (ELEMENT_PATH_PATTERN.test(trimmedPath)) {\n    return {\n      modelName: undefined,\n      segment: trimmedPath,\n      isQualified: false,\n    };\n  }\n\n  // Invalid format\n  throw createParseError(\n    `Invalid reference path format: '${trimmedPath}'. ` +\n      \"Use one of: '{layer}.{type}.{name}', UUID, or '@{model-name}/{layer}.{type}.{name}'\"\n  );\n}\n\n\nfunction createParseError(message: string): ReferencePathParseError {\n  return new ReferencePathParseError(message);\n}\n"],
+  "mappings": "AAqBM,MAAO,gCAAgC,MAAK;EACvC,OAAO;EAEhB,YAAY,SAAe;AACzB,UAAM,OAAO,GACb,KAAK,OAAO,2BACZ,OAAO,eAAe,MAAM,wBAAwB,SAAS;EAC/D;;AAGK,MAAM,eAAe,mEACf,2BAA2B,8BAClC,uBAAuB;AA0BvB,SAAU,mBAAmB,MAAY;AAC7C,MAAI,CAAC,QAAQ,OAAO,QAAS,YAAY,KAAK,KAAI,MAAO;AACvD,UAAM,iBAAiB,sBAAsB;AAG/C,QAAM,cAAc,KAAK,KAAI,GAGvB,iBAAiB,YAAY,MAAM,wBAAwB;AAEjE,MAAI,gBAAgB;AAClB,UAAM,YAAY,eAAe,CAAC,EAAE,YAAW,GACzC,UAAU,YAAY,UAAU,eAAe,CAAC,EAAE,MAAM;AAG9D,QAAI,CAAC,WAAW,QAAQ,KAAI,MAAO;AACjC,YAAM,iBACJ,4DAA4D;AAKhE,QAAI,aAAa,KAAK,OAAO;AAC3B,YAAM,iBACJ,+FAA+F;AAKnG,QAAI,CAAC,qBAAqB,KAAK,OAAO;AACpC,YAAM,iBACJ,kDAAkD,OAAO,qDAAqD;AAIlH,WAAO;MACL;MACA;MACA,aAAa;;EAEjB;AAIA,MAAI,aAAa,KAAK,WAAW;AAC/B,WAAO;MACL,WAAW;MACX,SAAS;MACT,aAAa;;AAIjB,MAAI,qBAAqB,KAAK,WAAW;AACvC,WAAO;MACL,WAAW;MACX,SAAS;MACT,aAAa;;AAKjB,QAAM,iBACJ,mCAAmC,WAAW,wFACyC;AAE3F;AAGA,SAAS,iBAAiB,SAAe;AACvC,SAAO,IAAI,wBAAwB,OAAO;AAC5C;",
+  "names": []
+}

package/dist/utils/source-reference.js

@@ -1,33 +1,40 @@
 import { CLIError } from "./errors.js";
-function validateSourceReferenceOptions(options) {
+import { optionExample, optionName } from "./error-hints.js";
+function validateSourceReferenceOptions(options, surface = "cli") {
+  const name = (option) => optionName(surface, option), example = (option, value) => optionExample(surface, option, value);
   if (!(options.sourceFile || options.sourceSymbol || options.sourceProvenance || options.sourceRepoRemote || options.sourceRepoCommit)) {
-    process.stderr.isTTY && console.warn("Warning: no source provenance specified. Add --source-file and --source-provenance to maintain traceability for drift detection and /dr-sync workflows.");
+    process.stderr.isTTY && console.warn(`Warning: no source provenance specified. Add ${name("sourceFile")} and ${name("sourceProvenance")} to maintain traceability for drift detection and /dr-sync workflows.`);
     return;
   }
+  if (options.sourceSymbol && !options.sourceFile)
+    throw new CLIError(`${name("sourceSymbol")} requires ${name("sourceFile")}`, 1, [
+      "Provide the source file that contains the symbol",
+      `Example: ${example("sourceFile", "src/auth.ts")} ${example("sourceSymbol", "validateToken")}`
+    ]);
   if (!options.sourceProvenance)
-    throw new CLIError("--source-provenance is required when specifying source reference", 1, [
+    throw new CLIError(`${name("sourceProvenance")} is required when specifying source reference`, 1, [
       "Specify provenance type: extracted, manual, inferred, or generated"
     ]);
   const fileOptionalProvenances = ["inferred", "generated"];
   if (!options.sourceFile && !fileOptionalProvenances.includes(options.sourceProvenance))
-    throw new CLIError("--source-file is required when specifying source reference", 1, [
+    throw new CLIError(`${name("sourceFile")} is required when specifying source reference`, 1, [
       "Provide source file path relative to repository root",
-      'Example: --source-file "src/services/auth.ts"',
-      "Note: --source-file is optional when --source-provenance is 'inferred' or 'generated'"
+      `Example: ${example("sourceFile", "src/services/auth.ts")}`,
+      `Note: ${name("sourceFile")} is optional when ${name("sourceProvenance")} is 'inferred' or 'generated'`
     ]);
   const validProvenance = ["extracted", "manual", "inferred", "generated"];
   if (!validProvenance.includes(options.sourceProvenance))
-    throw new CLIError(`Invalid --source-provenance value: "${options.sourceProvenance}"`, 1, [
+    throw new CLIError(`Invalid ${name("sourceProvenance")} value: "${options.sourceProvenance}"`, 1, [
       `Must be one of: ${validProvenance.join(", ")}`
     ]);
   if (options.sourceRepoCommit && !/^[0-9a-f]{40}$/.test(options.sourceRepoCommit))
-    throw new CLIError(`Invalid --source-repo-commit value: "${options.sourceRepoCommit}"`, 1, [
+    throw new CLIError(`Invalid ${name("sourceRepoCommit")} value: "${options.sourceRepoCommit}"`, 1, [
       "Must be exactly 40 hexadecimal characters (full Git commit SHA)"
     ]);
   if (options.sourceRepoRemote && !options.sourceRepoCommit)
-    throw new CLIError("--source-repo-commit is required when --source-repo-remote is provided", 1, ["Provide both remote URL and commit SHA for repository context"]);
+    throw new CLIError(`${name("sourceRepoCommit")} is required when ${name("sourceRepoRemote")} is provided`, 1, ["Provide both remote URL and commit SHA for repository context"]);
   if (options.sourceRepoCommit && !options.sourceRepoRemote)
-    throw new CLIError("--source-repo-remote is required when --source-repo-commit is provided", 1, ["Provide both remote URL and commit SHA for repository context"]);
+    throw new CLIError(`${name("sourceRepoRemote")} is required when ${name("sourceRepoCommit")} is provided`, 1, ["Provide both remote URL and commit SHA for repository context"]);
 }
 function buildSourceReference(options) {
   if (!options.sourceProvenance)

package/dist/utils/source-reference.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/utils/source-reference.ts"],
-  "sourcesContent": ["/**\n * Source Reference Utilities\n * Shared validation and builder functions for source reference options\n */\n\nimport type { SourceReference, ProvenanceType } from \"../types/index.js\";\nimport { CLIError } from \"./errors.js\";\n\nexport interface SourceReferenceOptions {\n  sourceFile?: string;\n  sourceSymbol?: string;\n  sourceProvenance?: string;\n  sourceRepoRemote?: string;\n  sourceRepoCommit?: string;\n}\n\n/**\n * Validate source reference options\n */\nexport function validateSourceReferenceOptions(options: SourceReferenceOptions): void {\n  const hasSourceOptions =\n    options.sourceFile ||\n    options.sourceSymbol ||\n    options.sourceProvenance ||\n    options.sourceRepoRemote ||\n    options.sourceRepoCommit;\n\n  if (!hasSourceOptions) {\n    if (process.stderr.isTTY) {\n      console.warn(\n        \"Warning: no source provenance specified. Add --source-file and --source-provenance to maintain traceability for drift detection and /dr-sync workflows.\"\n      );\n    }\n    return;\n  }\n\n  // Require provenance first so we can use it to determine file requirements\n  if (!options.sourceProvenance) {\n    throw new CLIError(\"--source-provenance is required when specifying source reference\", 1, [\n      \"Specify provenance type: extracted, manual, inferred, or generated\",\n    ]);\n  }\n\n  // For inferred and generated provenance, source file is optional (no code exists yet)\n  const fileOptionalProvenances = [\"inferred\", \"generated\"];\n  if (!options.sourceFile && !fileOptionalProvenances.includes(options.sourceProvenance)) {\n    throw new CLIError(\"--source-file is required when specifying source reference\", 1, [\n      \"Provide source file path relative to repository root\",\n      'Example: --source-file \"src/services/auth.ts\"',\n      \"Note: --source-file is optional when --source-provenance is 'inferred' or 'generated'\",\n    ]);\n  }\n\n  // Validate provenance enum\n  const validProvenance = [\"extracted\", \"manual\", \"inferred\", \"generated\"];\n  if (!validProvenance.includes(options.sourceProvenance)) {\n    throw new CLIError(`Invalid --source-provenance value: \"${options.sourceProvenance}\"`, 1, [\n      `Must be one of: ${validProvenance.join(\", \")}`,\n    ]);\n  }\n\n  // Validate commit SHA format if provided\n  if (options.sourceRepoCommit && !/^[0-9a-f]{40}$/.test(options.sourceRepoCommit)) {\n    throw new CLIError(`Invalid --source-repo-commit value: \"${options.sourceRepoCommit}\"`, 1, [\n      \"Must be exactly 40 hexadecimal characters (full Git commit SHA)\",\n    ]);\n  }\n\n  // Require both or neither repo context fields\n  if (options.sourceRepoRemote && !options.sourceRepoCommit) {\n    throw new CLIError(\n      \"--source-repo-commit is required when --source-repo-remote is provided\",\n      1,\n      [\"Provide both remote URL and commit SHA for repository context\"]\n    );\n  }\n\n  if (options.sourceRepoCommit && !options.sourceRepoRemote) {\n    throw new CLIError(\n      \"--source-repo-remote is required when --source-repo-commit is provided\",\n      1,\n      [\"Provide both remote URL and commit SHA for repository context\"]\n    );\n  }\n}\n\n/**\n * Build SourceReference object from options\n */\nexport function buildSourceReference(options: SourceReferenceOptions): SourceReference | undefined {\n  if (!options.sourceProvenance) {\n    return undefined;\n  }\n\n  const reference: SourceReference = {\n    provenance: options.sourceProvenance as ProvenanceType,\n  };\n\n  if (options.sourceFile) {\n    reference.locations = [\n      {\n        file: options.sourceFile,\n        ...(options.sourceSymbol && { symbol: options.sourceSymbol }),\n      },\n    ];\n  }\n\n  if (options.sourceRepoRemote && options.sourceRepoCommit) {\n    reference.repository = {\n      url: options.sourceRepoRemote,\n      commit: options.sourceRepoCommit,\n    };\n  }\n\n  return reference;\n}\n"],
-  "mappings": "AAMA,SAAS,gBAAgB;AAanB,SAAU,+BAA+B,SAA+B;AAQ5E,MAAI,EANF,QAAQ,cACR,QAAQ,gBACR,QAAQ,oBACR,QAAQ,oBACR,QAAQ,mBAEa;AACrB,IAAI,QAAQ,OAAO,SACjB,QAAQ,KACN,yJAAyJ;AAG7J;EACF;AAGA,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI,SAAS,oEAAoE,GAAG;MACxF;KACD;AAIH,QAAM,0BAA0B,CAAC,YAAY,WAAW;AACxD,MAAI,CAAC,QAAQ,cAAc,CAAC,wBAAwB,SAAS,QAAQ,gBAAgB;AACnF,UAAM,IAAI,SAAS,8DAA8D,GAAG;MAClF;MACA;MACA;KACD;AAIH,QAAM,kBAAkB,CAAC,aAAa,UAAU,YAAY,WAAW;AACvE,MAAI,CAAC,gBAAgB,SAAS,QAAQ,gBAAgB;AACpD,UAAM,IAAI,SAAS,uCAAuC,QAAQ,gBAAgB,KAAK,GAAG;MACxF,mBAAmB,gBAAgB,KAAK,IAAI,CAAC;KAC9C;AAIH,MAAI,QAAQ,oBAAoB,CAAC,iBAAiB,KAAK,QAAQ,gBAAgB;AAC7E,UAAM,IAAI,SAAS,wCAAwC,QAAQ,gBAAgB,KAAK,GAAG;MACzF;KACD;AAIH,MAAI,QAAQ,oBAAoB,CAAC,QAAQ;AACvC,UAAM,IAAI,SACR,0EACA,GACA,CAAC,+DAA+D,CAAC;AAIrE,MAAI,QAAQ,oBAAoB,CAAC,QAAQ;AACvC,UAAM,IAAI,SACR,0EACA,GACA,CAAC,+DAA+D,CAAC;AAGvE;AAKM,SAAU,qBAAqB,SAA+B;AAClE,MAAI,CAAC,QAAQ;AACX;AAGF,QAAM,YAA6B;IACjC,YAAY,QAAQ;;AAGtB,SAAI,QAAQ,eACV,UAAU,YAAY;IACpB;MACE,MAAM,QAAQ;MACd,GAAI,QAAQ,gBAAgB,EAAE,QAAQ,QAAQ,aAAY;;MAK5D,QAAQ,oBAAoB,QAAQ,qBACtC,UAAU,aAAa;IACrB,KAAK,QAAQ;IACb,QAAQ,QAAQ;MAIb;AACT;",
+  "sourcesContent": ["/**\n * Source Reference Utilities\n * Shared validation and builder functions for source reference options\n */\n\nimport type { SourceReference, ProvenanceType } from \"../types/index.js\";\nimport { CLIError } from \"./errors.js\";\nimport { optionExample, optionName, type HintOption, type HintSurface } from \"./error-hints.js\";\n\nexport interface SourceReferenceOptions {\n  sourceFile?: string;\n  sourceSymbol?: string;\n  sourceProvenance?: string;\n  sourceRepoRemote?: string;\n  sourceRepoCommit?: string;\n}\n\n/**\n * Validate source reference options\n */\nexport function validateSourceReferenceOptions(\n  options: SourceReferenceOptions,\n  surface: HintSurface = \"cli\"\n): void {\n  const name = (option: HintOption) => optionName(surface, option);\n  const example = (option: HintOption, value: string) => optionExample(surface, option, value);\n  const hasSourceOptions =\n    options.sourceFile ||\n    options.sourceSymbol ||\n    options.sourceProvenance ||\n    options.sourceRepoRemote ||\n    options.sourceRepoCommit;\n\n  if (!hasSourceOptions) {\n    if (process.stderr.isTTY) {\n      console.warn(\n        `Warning: no source provenance specified. Add ${name(\"sourceFile\")} and ${name(\"sourceProvenance\")} to maintain traceability for drift detection and /dr-sync workflows.`\n      );\n    }\n    return;\n  }\n\n  // Require source-symbol to have source-file (both or neither is not acceptable here)\n  if (options.sourceSymbol && !options.sourceFile) {\n    throw new CLIError(`${name(\"sourceSymbol\")} requires ${name(\"sourceFile\")}`, 1, [\n      \"Provide the source file that contains the symbol\",\n      `Example: ${example(\"sourceFile\", \"src/auth.ts\")} ${example(\"sourceSymbol\", \"validateToken\")}`,\n    ]);\n  }\n\n  // Require provenance first so we can use it to determine file requirements\n  if (!options.sourceProvenance) {\n    throw new CLIError(`${name(\"sourceProvenance\")} is required when specifying source reference`, 1, [\n      \"Specify provenance type: extracted, manual, inferred, or generated\",\n    ]);\n  }\n\n  // For inferred and generated provenance, source file is optional (no code exists yet)\n  const fileOptionalProvenances = [\"inferred\", \"generated\"];\n  if (!options.sourceFile && !fileOptionalProvenances.includes(options.sourceProvenance)) {\n    throw new CLIError(`${name(\"sourceFile\")} is required when specifying source reference`, 1, [\n      \"Provide source file path relative to repository root\",\n      `Example: ${example(\"sourceFile\", \"src/services/auth.ts\")}`,\n      `Note: ${name(\"sourceFile\")} is optional when ${name(\"sourceProvenance\")} is 'inferred' or 'generated'`,\n    ]);\n  }\n\n  // Validate provenance enum\n  const validProvenance = [\"extracted\", \"manual\", \"inferred\", \"generated\"];\n  if (!validProvenance.includes(options.sourceProvenance)) {\n    throw new CLIError(`Invalid ${name(\"sourceProvenance\")} value: \"${options.sourceProvenance}\"`, 1, [\n      `Must be one of: ${validProvenance.join(\", \")}`,\n    ]);\n  }\n\n  // Validate commit SHA format if provided\n  if (options.sourceRepoCommit && !/^[0-9a-f]{40}$/.test(options.sourceRepoCommit)) {\n    throw new CLIError(`Invalid ${name(\"sourceRepoCommit\")} value: \"${options.sourceRepoCommit}\"`, 1, [\n      \"Must be exactly 40 hexadecimal characters (full Git commit SHA)\",\n    ]);\n  }\n\n  // Require both or neither repo context fields\n  if (options.sourceRepoRemote && !options.sourceRepoCommit) {\n    throw new CLIError(\n      `${name(\"sourceRepoCommit\")} is required when ${name(\"sourceRepoRemote\")} is provided`,\n      1,\n      [\"Provide both remote URL and commit SHA for repository context\"]\n    );\n  }\n\n  if (options.sourceRepoCommit && !options.sourceRepoRemote) {\n    throw new CLIError(\n      `${name(\"sourceRepoRemote\")} is required when ${name(\"sourceRepoCommit\")} is provided`,\n      1,\n      [\"Provide both remote URL and commit SHA for repository context\"]\n    );\n  }\n}\n\n/**\n * Build SourceReference object from options\n */\nexport function buildSourceReference(options: SourceReferenceOptions): SourceReference | undefined {\n  if (!options.sourceProvenance) {\n    return undefined;\n  }\n\n  const reference: SourceReference = {\n    provenance: options.sourceProvenance as ProvenanceType,\n  };\n\n  if (options.sourceFile) {\n    reference.locations = [\n      {\n        file: options.sourceFile,\n        ...(options.sourceSymbol && { symbol: options.sourceSymbol }),\n      },\n    ];\n  }\n\n  if (options.sourceRepoRemote && options.sourceRepoCommit) {\n    reference.repository = {\n      url: options.sourceRepoRemote,\n      commit: options.sourceRepoCommit,\n    };\n  }\n\n  return reference;\n}\n"],
+  "mappings": "AAMA,SAAS,gBAAgB;AACzB,SAAS,eAAe,kBAAqD;AAavE,SAAU,+BACd,SACA,UAAuB,OAAK;AAE5B,QAAM,OAAO,CAAC,WAAuB,WAAW,SAAS,MAAM,GACzD,UAAU,CAAC,QAAoB,UAAkB,cAAc,SAAS,QAAQ,KAAK;AAQ3F,MAAI,EANF,QAAQ,cACR,QAAQ,gBACR,QAAQ,oBACR,QAAQ,oBACR,QAAQ,mBAEa;AACrB,IAAI,QAAQ,OAAO,SACjB,QAAQ,KACN,gDAAgD,KAAK,YAAY,CAAC,QAAQ,KAAK,kBAAkB,CAAC,uEAAuE;AAG7K;EACF;AAGA,MAAI,QAAQ,gBAAgB,CAAC,QAAQ;AACnC,UAAM,IAAI,SAAS,GAAG,KAAK,cAAc,CAAC,aAAa,KAAK,YAAY,CAAC,IAAI,GAAG;MAC9E;MACA,YAAY,QAAQ,cAAc,aAAa,CAAC,IAAI,QAAQ,gBAAgB,eAAe,CAAC;KAC7F;AAIH,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI,SAAS,GAAG,KAAK,kBAAkB,CAAC,iDAAiD,GAAG;MAChG;KACD;AAIH,QAAM,0BAA0B,CAAC,YAAY,WAAW;AACxD,MAAI,CAAC,QAAQ,cAAc,CAAC,wBAAwB,SAAS,QAAQ,gBAAgB;AACnF,UAAM,IAAI,SAAS,GAAG,KAAK,YAAY,CAAC,iDAAiD,GAAG;MAC1F;MACA,YAAY,QAAQ,cAAc,sBAAsB,CAAC;MACzD,SAAS,KAAK,YAAY,CAAC,qBAAqB,KAAK,kBAAkB,CAAC;KACzE;AAIH,QAAM,kBAAkB,CAAC,aAAa,UAAU,YAAY,WAAW;AACvE,MAAI,CAAC,gBAAgB,SAAS,QAAQ,gBAAgB;AACpD,UAAM,IAAI,SAAS,WAAW,KAAK,kBAAkB,CAAC,YAAY,QAAQ,gBAAgB,KAAK,GAAG;MAChG,mBAAmB,gBAAgB,KAAK,IAAI,CAAC;KAC9C;AAIH,MAAI,QAAQ,oBAAoB,CAAC,iBAAiB,KAAK,QAAQ,gBAAgB;AAC7E,UAAM,IAAI,SAAS,WAAW,KAAK,kBAAkB,CAAC,YAAY,QAAQ,gBAAgB,KAAK,GAAG;MAChG;KACD;AAIH,MAAI,QAAQ,oBAAoB,CAAC,QAAQ;AACvC,UAAM,IAAI,SACR,GAAG,KAAK,kBAAkB,CAAC,qBAAqB,KAAK,kBAAkB,CAAC,gBACxE,GACA,CAAC,+DAA+D,CAAC;AAIrE,MAAI,QAAQ,oBAAoB,CAAC,QAAQ;AACvC,UAAM,IAAI,SACR,GAAG,KAAK,kBAAkB,CAAC,qBAAqB,KAAK,kBAAkB,CAAC,gBACxE,GACA,CAAC,+DAA+D,CAAC;AAGvE;AAKM,SAAU,qBAAqB,SAA+B;AAClE,MAAI,CAAC,QAAQ;AACX;AAGF,QAAM,YAA6B;IACjC,YAAY,QAAQ;;AAGtB,SAAI,QAAQ,eACV,UAAU,YAAY;IACpB;MACE,MAAM,QAAQ;MACd,GAAI,QAAQ,gBAAgB,EAAE,QAAQ,QAAQ,aAAY;;MAK5D,QAAQ,oBAAoB,QAAQ,qBACtC,UAAU,aAAa;IACrB,KAAK,QAAQ;IACb,QAAQ,QAAQ;MAIb;AACT;",
   "names": []
 }

package/dist/utils/spec-version.js

@@ -1,8 +1,16 @@
 import { readJSON, fileExists } from "./file-io.js";
 import { join } from "path";
-const CLI_VERSION = "0.1.12", BUNDLED_SPEC_VERSION = "0.9.0";
+import { createRequire } from "node:module";
+const BUNDLED_SPEC_VERSION = "0.11.0";
+function resolveDevVersion() {
+  try {
+    return createRequire(import.meta.url)("../../package.json").version ?? "0.0.0";
+  } catch (error) {
+    return console.error(`Failed to resolve dev-mode CLI version from package.json, falling back to "0.0.0": ${error instanceof Error ? error.message : String(error)}`), "0.0.0";
+  }
+}
 function getCliVersion() {
-  return CLI_VERSION;
+  return "0.3.0";
 }
 function getCliBundledSpecVersion() {
   return BUNDLED_SPEC_VERSION;

package/dist/utils/spec-version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/utils/spec-version.ts"],
-  "sourcesContent": ["/**\n * Spec Version Utilities\n *\n * Manages spec version information for the CLI\n */\n\nimport { readJSON, fileExists } from \"./file-io.js\";\nimport { join } from \"path\";\n\n/**\n * CLI version\n * This should match the version in ../package.json\n * Updated during release process\n */\nconst CLI_VERSION = \"0.1.12\";\n\n/**\n * Bundled spec version\n * This should match the version in ../../../spec/VERSION\n * Updated during build process\n */\nconst BUNDLED_SPEC_VERSION = \"0.9.0\";\n\n/**\n * Get the CLI version\n *\n * @returns CLI version string\n */\nexport function getCliVersion(): string {\n  return CLI_VERSION;\n}\n\n/**\n * Get the CLI's bundled spec version\n *\n * This is the version of the DR specification that is bundled with this CLI.\n * It represents what version of the spec this CLI supports.\n *\n * @returns Bundled spec version string\n */\nexport function getCliBundledSpecVersion(): string {\n  return BUNDLED_SPEC_VERSION;\n}\n\n/**\n * Read spec version from .dr/manifest.json (installed spec reference)\n *\n * @param drPath - Path to .dr/ directory\n * @returns Spec version from .dr/manifest.json, or null if not found\n */\nexport async function getInstalledSpecVersion(drPath: string): Promise<string | null> {\n  const manifestPath = join(drPath, \"manifest.json\");\n\n  if (!(await fileExists(manifestPath))) {\n    return null;\n  }\n\n  try {\n    const manifest = await readJSON<{ specVersion?: string }>(manifestPath);\n    return manifest.specVersion || null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Read spec version from documentation_robotics/model/manifest.yaml\n *\n * @param modelPath - Path to model directory\n * @returns Spec version from model manifest, or null if not found\n */\nexport async function getModelSpecVersion(modelPath: string): Promise<string | null> {\n  const manifestPath = join(modelPath, \"manifest.yaml\");\n\n  if (!(await fileExists(manifestPath))) {\n    return null;\n  }\n\n  try {\n    // Use YAML parser\n    const yaml = await import(\"yaml\");\n    const fs = await import(\"fs/promises\");\n    const content = await fs.readFile(manifestPath, \"utf-8\");\n    const manifest = yaml.parse(content) as { spec_version?: string; specVersion?: string };\n    // Check snake_case first (Python CLI format), then camelCase (legacy)\n    return manifest.spec_version || manifest.specVersion || null;\n  } catch {\n    return null;\n  }\n}\n"],
-  "mappings": "AAMA,SAAS,UAAU,kBAAkB;AACrC,SAAS,YAAY;AAOrB,MAAM,cAAc,UAOd,uBAAuB;AAOvB,SAAU,gBAAa;AAC3B,SAAO;AACT;AAUM,SAAU,2BAAwB;AACtC,SAAO;AACT;AAQA,eAAsB,wBAAwB,QAAc;AAC1D,QAAM,eAAe,KAAK,QAAQ,eAAe;AAEjD,MAAI,CAAE,MAAM,WAAW,YAAY;AACjC,WAAO;AAGT,MAAI;AAEF,YADiB,MAAM,SAAmC,YAAY,GACtD,eAAe;EACjC,QAAQ;AACN,WAAO;EACT;AACF;AAQA,eAAsB,oBAAoB,WAAiB;AACzD,QAAM,eAAe,KAAK,WAAW,eAAe;AAEpD,MAAI,CAAE,MAAM,WAAW,YAAY;AACjC,WAAO;AAGT,MAAI;AAEF,UAAM,OAAO,MAAM,OAAO,MAAM,GAE1B,UAAU,OADL,MAAM,OAAO,aAAa,GACZ,SAAS,cAAc,OAAO,GACjD,WAAW,KAAK,MAAM,OAAO;AAEnC,WAAO,SAAS,gBAAgB,SAAS,eAAe;EAC1D,QAAQ;AACN,WAAO;EACT;AACF;",
+  "sourcesContent": ["/**\n * Spec Version Utilities\n *\n * Manages spec version information for the CLI\n */\n\nimport { readJSON, fileExists } from \"./file-io.js\";\nimport { join } from \"path\";\nimport { createRequire } from \"node:module\";\n\n// Declare build-time constant (substituted by esbuild)\ndeclare const CLI_VERSION: string;\n\n/**\n * Bundled spec version\n * This should match the version in ../../../spec/VERSION\n * Updated during build process\n */\nconst BUNDLED_SPEC_VERSION = \"0.11.0\";\n\n// Dev-mode fallback (e.g. `tsx src/cli.ts`) that reads package.json directly, so it can't drift.\nfunction resolveDevVersion(): string {\n  try {\n    const require = createRequire(import.meta.url);\n    const pkg = require(\"../../package.json\") as { version?: string };\n    return pkg.version ?? \"0.0.0\";\n  } catch (error) {\n    console.error(\n      `Failed to resolve dev-mode CLI version from package.json, falling back to \"0.0.0\": ${\n        error instanceof Error ? error.message : String(error)\n      }`\n    );\n    return \"0.0.0\";\n  }\n}\n\n/**\n * Get the CLI version\n *\n * @returns CLI version string\n */\nexport function getCliVersion(): string {\n  return typeof CLI_VERSION !== \"undefined\" ? CLI_VERSION : resolveDevVersion();\n}\n\n/**\n * Get the CLI's bundled spec version\n *\n * This is the version of the DR specification that is bundled with this CLI.\n * It represents what version of the spec this CLI supports.\n *\n * @returns Bundled spec version string\n */\nexport function getCliBundledSpecVersion(): string {\n  return BUNDLED_SPEC_VERSION;\n}\n\n/**\n * Read spec version from .dr/manifest.json (installed spec reference)\n *\n * @param drPath - Path to .dr/ directory\n * @returns Spec version from .dr/manifest.json, or null if not found\n */\nexport async function getInstalledSpecVersion(drPath: string): Promise<string | null> {\n  const manifestPath = join(drPath, \"manifest.json\");\n\n  if (!(await fileExists(manifestPath))) {\n    return null;\n  }\n\n  try {\n    const manifest = await readJSON<{ specVersion?: string }>(manifestPath);\n    return manifest.specVersion || null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Read spec version from documentation_robotics/model/manifest.yaml\n *\n * @param modelPath - Path to model directory\n * @returns Spec version from model manifest, or null if not found\n */\nexport async function getModelSpecVersion(modelPath: string): Promise<string | null> {\n  const manifestPath = join(modelPath, \"manifest.yaml\");\n\n  if (!(await fileExists(manifestPath))) {\n    return null;\n  }\n\n  try {\n    // Use YAML parser\n    const yaml = await import(\"yaml\");\n    const fs = await import(\"fs/promises\");\n    const content = await fs.readFile(manifestPath, \"utf-8\");\n    const manifest = yaml.parse(content) as { spec_version?: string; specVersion?: string };\n    // Check snake_case first (Python CLI format), then camelCase (legacy)\n    return manifest.spec_version || manifest.specVersion || null;\n  } catch {\n    return null;\n  }\n}\n"],
+  "mappings": "AAMA,SAAS,UAAU,kBAAkB;AACrC,SAAS,YAAY;AACrB,SAAS,qBAAqB;AAU9B,MAAM,uBAAuB;AAG7B,SAAS,oBAAiB;AACxB,MAAI;AAGF,WAFgB,cAAc,YAAY,GAAG,EACzB,oBAAoB,EAC7B,WAAW;EACxB,SAAS,OAAO;AACd,mBAAQ,MACN,sFACE,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,CACvD,EAAE,GAEG;EACT;AACF;AAOM,SAAU,gBAAa;AAC3B,SAA4C;AAC9C;AAUM,SAAU,2BAAwB;AACtC,SAAO;AACT;AAQA,eAAsB,wBAAwB,QAAc;AAC1D,QAAM,eAAe,KAAK,QAAQ,eAAe;AAEjD,MAAI,CAAE,MAAM,WAAW,YAAY;AACjC,WAAO;AAGT,MAAI;AAEF,YADiB,MAAM,SAAmC,YAAY,GACtD,eAAe;EACjC,QAAQ;AACN,WAAO;EACT;AACF;AAQA,eAAsB,oBAAoB,WAAiB;AACzD,QAAM,eAAe,KAAK,WAAW,eAAe;AAEpD,MAAI,CAAE,MAAM,WAAW,YAAY;AACjC,WAAO;AAGT,MAAI;AAEF,UAAM,OAAO,MAAM,OAAO,MAAM,GAE1B,UAAU,OADL,MAAM,OAAO,aAAa,GACZ,SAAS,cAAc,OAAO,GACjD,WAAW,KAAK,MAAM,OAAO;AAEnC,WAAO,SAAS,gBAAgB,SAAS,eAAe;EAC1D,QAAQ;AACN,WAAO;EACT;AACF;",
   "names": []
 }