@documentation-robotics/cli 0.1.0 → 0.1.5

package/dist/utils/export-python-annotations.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import fs from "fs/promises";
+import path from "path";
+import { Command } from "commander";
+async function findAnnotationsDirectory(modelRoot) {
+  const drPath = path.join(modelRoot, ".dr", "annotations");
+  try {
+    return await fs.access(drPath), drPath;
+  } catch {
+    const drAltPath = path.join(modelRoot, "documentation-robotics", "annotations");
+    try {
+      return await fs.access(drAltPath), drAltPath;
+    } catch {
+      return null;
+    }
+  }
+}
+async function loadAnnotations(annotationsDir) {
+  const threads = [];
+  try {
+    const files = await fs.readdir(annotationsDir);
+    for (const file of files) {
+      if (!file.endsWith(".json"))
+        continue;
+      const filePath = path.join(annotationsDir, file), content = await fs.readFile(filePath, "utf-8"), data = JSON.parse(content), elementId = file.replace(".json", "");
+      threads.push({
+        elementId,
+        annotations: Array.isArray(data) ? data : [data]
+      });
+    }
+  } catch (error) {
+    console.error("Error loading annotations:", error);
+  }
+  return threads;
+}
+function exportToJSON(threads) {
+  return JSON.stringify(threads, null, 2);
+}
+function exportToMarkdown(threads) {
+  let markdown = `# Annotation Export
+
+`;
+  markdown += `**Exported:** ${(/* @__PURE__ */ new Date()).toISOString()}
+
+`, markdown += `**Total Threads:** ${threads.length}
+
+`, markdown += `---
+
+`;
+  for (const thread of threads) {
+    markdown += `## Element: ${thread.elementId}
+
+`;
+    for (const annotation of thread.annotations)
+      markdown += `### Annotation by ${annotation.author}
+
+`, markdown += `**Date:** ${annotation.timestamp}
+
+`, annotation.threadId && (markdown += `**Thread:** ${annotation.threadId}
+
+`), markdown += `${annotation.content}
+
+`, markdown += `---
+
+`;
+  }
+  return markdown;
+}
+async function main() {
+  const program = new Command();
+  program.name("export-python-annotations").description("Export annotations from Python CLI format").option("--model <path>", "Path to model root", process.cwd()).option("--output <file>", "Output file (required)").option("--format <format>", "Output format: json, markdown", "json").parse();
+  const options = program.opts();
+  options.output || (console.error("Error: --output is required"), process.exit(1)), console.log(`Searching for annotations in ${options.model}...`);
+  const annotationsDir = await findAnnotationsDirectory(options.model);
+  annotationsDir || (console.log("No annotations directory found."), console.log("This is normal if you never used the Python CLI annotation feature."), console.log(""), console.log("Annotation directories checked:"), console.log("  - .dr/annotations/"), console.log("  - documentation-robotics/annotations/"), process.exit(0)), console.log(`Found annotations directory: ${annotationsDir}`);
+  const threads = await loadAnnotations(annotationsDir);
+  threads.length === 0 && (console.log("No annotations found in directory."), process.exit(0)), console.log(`Loaded ${threads.length} annotation threads`);
+  let output;
+  options.format === "markdown" ? output = exportToMarkdown(threads) : output = exportToJSON(threads), await fs.writeFile(options.output, output, "utf-8"), console.log(`\u2713 Annotations exported to ${options.output}`), console.log(""), console.log("Next steps:"), console.log("1. Review the exported annotations"), console.log("2. Add important annotations to element descriptions:"), console.log('   dr update <element-id> --description "Annotation content"'), console.log("3. Consider using external tools for collaborative annotations:"), console.log("   - GitHub Issues"), console.log("   - Notion/Confluence"), console.log("   - Linear/Jira");
+}
+main().catch(console.error);
+//# sourceMappingURL=export-python-annotations.js.map

package/dist/utils/export-python-annotations.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/export-python-annotations.ts"],
+  "sourcesContent": ["#!/usr/bin/env node\n/**\n * Annotation Export Utility\n *\n * Exports annotations from Python CLI format to help users migrate.\n * Python CLI stores annotations in `.dr/annotations/` directory.\n * This tool exports them to JSON or Markdown for manual migration.\n *\n * Usage:\n *   bun run src/utils/export-python-annotations.ts --output annotations.json\n *   bun run src/utils/export-python-annotations.ts --format markdown --output annotations.md\n */\n\nimport fs from \"fs/promises\";\nimport path from \"path\";\nimport { Command } from \"commander\";\n\ninterface Annotation {\n  id: string;\n  elementId: string;\n  author: string;\n  timestamp: string;\n  content: string;\n  threadId?: string;\n  parentId?: string;\n}\n\ninterface AnnotationThread {\n  elementId: string;\n  annotations: Annotation[];\n}\n\nasync function findAnnotationsDirectory(modelRoot: string): Promise<string | null> {\n  // Try .dr/annotations/ first\n  const drPath = path.join(modelRoot, \".dr\", \"annotations\");\n  try {\n    await fs.access(drPath);\n    return drPath;\n  } catch {\n    // Try documentation-robotics/annotations/\n    const drAltPath = path.join(modelRoot, \"documentation-robotics\", \"annotations\");\n    try {\n      await fs.access(drAltPath);\n      return drAltPath;\n    } catch {\n      return null;\n    }\n  }\n}\n\nasync function loadAnnotations(annotationsDir: string): Promise<AnnotationThread[]> {\n  const threads: AnnotationThread[] = [];\n\n  try {\n    const files = await fs.readdir(annotationsDir);\n\n    for (const file of files) {\n      if (!file.endsWith(\".json\")) continue;\n\n      const filePath = path.join(annotationsDir, file);\n      const content = await fs.readFile(filePath, \"utf-8\");\n      const data = JSON.parse(content);\n\n      // Extract element ID from filename (format: element-id.json)\n      const elementId = file.replace(\".json\", \"\");\n\n      threads.push({\n        elementId,\n        annotations: Array.isArray(data) ? data : [data],\n      });\n    }\n  } catch (error) {\n    console.error(\"Error loading annotations:\", error);\n  }\n\n  return threads;\n}\n\nfunction exportToJSON(threads: AnnotationThread[]): string {\n  return JSON.stringify(threads, null, 2);\n}\n\nfunction exportToMarkdown(threads: AnnotationThread[]): string {\n  let markdown = \"# Annotation Export\\n\\n\";\n  markdown += `**Exported:** ${new Date().toISOString()}\\n\\n`;\n  markdown += `**Total Threads:** ${threads.length}\\n\\n`;\n  markdown += \"---\\n\\n\";\n\n  for (const thread of threads) {\n    markdown += `## Element: ${thread.elementId}\\n\\n`;\n\n    for (const annotation of thread.annotations) {\n      markdown += `### Annotation by ${annotation.author}\\n\\n`;\n      markdown += `**Date:** ${annotation.timestamp}\\n\\n`;\n      if (annotation.threadId) {\n        markdown += `**Thread:** ${annotation.threadId}\\n\\n`;\n      }\n      markdown += `${annotation.content}\\n\\n`;\n      markdown += \"---\\n\\n\";\n    }\n  }\n\n  return markdown;\n}\n\nasync function main() {\n  const program = new Command();\n\n  program\n    .name(\"export-python-annotations\")\n    .description(\"Export annotations from Python CLI format\")\n    .option(\"--model <path>\", \"Path to model root\", process.cwd())\n    .option(\"--output <file>\", \"Output file (required)\")\n    .option(\"--format <format>\", \"Output format: json, markdown\", \"json\")\n    .parse();\n\n  const options = program.opts();\n\n  if (!options.output) {\n    console.error(\"Error: --output is required\");\n    process.exit(1);\n  }\n\n  console.log(`Searching for annotations in ${options.model}...`);\n\n  const annotationsDir = await findAnnotationsDirectory(options.model);\n\n  if (!annotationsDir) {\n    console.log(\"No annotations directory found.\");\n    console.log(\"This is normal if you never used the Python CLI annotation feature.\");\n    console.log(\"\");\n    console.log(\"Annotation directories checked:\");\n    console.log(\"  - .dr/annotations/\");\n    console.log(\"  - documentation-robotics/annotations/\");\n    process.exit(0);\n  }\n\n  console.log(`Found annotations directory: ${annotationsDir}`);\n\n  const threads = await loadAnnotations(annotationsDir);\n\n  if (threads.length === 0) {\n    console.log(\"No annotations found in directory.\");\n    process.exit(0);\n  }\n\n  console.log(`Loaded ${threads.length} annotation threads`);\n\n  let output: string;\n\n  if (options.format === \"markdown\") {\n    output = exportToMarkdown(threads);\n  } else {\n    output = exportToJSON(threads);\n  }\n\n  await fs.writeFile(options.output, output, \"utf-8\");\n\n  console.log(`\u2713 Annotations exported to ${options.output}`);\n  console.log(\"\");\n  console.log(\"Next steps:\");\n  console.log(\"1. Review the exported annotations\");\n  console.log(\"2. Add important annotations to element descriptions:\");\n  console.log('   dr update <element-id> --description \"Annotation content\"');\n  console.log(\"3. Consider using external tools for collaborative annotations:\");\n  console.log(\"   - GitHub Issues\");\n  console.log(\"   - Notion/Confluence\");\n  console.log(\"   - Linear/Jira\");\n}\n\nmain().catch(console.error);\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/utils/file-io.js

@@ -1,5 +1,6 @@
 import { mkdir, rename, readFile as fsReadFile, writeFile as fsWriteFile, stat } from "node:fs/promises";
 import { existsSync as fsExistsSync } from "node:fs";
+import { dirname } from "node:path";
 import { startSpan, endSpan } from "../telemetry/index.js";
 const isTelemetryEnabled = !1;
 async function ensureDir(path) {
@@ -12,6 +13,8 @@ async function atomicWrite(path, content) {
     "file.created": !fileExists2
   });
   try {
+    const dir = dirname(path);
+    await mkdir(dir, { recursive: !0 });
     const tempPath = `${path}.tmp`;
     await fsWriteFile(tempPath, content, "utf-8"), await rename(tempPath, path);
   } finally {
@@ -44,7 +47,8 @@ async function writeFile(path, content) {
     "file.created": !fileExists2
   });
   try {
-    await fsWriteFile(path, content, "utf-8");
+    const dir = dirname(path);
+    await mkdir(dir, { recursive: !0 }), await fsWriteFile(path, content, "utf-8");
   } finally {
     endSpan(span);
   }
@@ -55,7 +59,8 @@ async function readJSON(path) {
 }
 async function writeJSON(path, data, pretty = !0) {
   const content = pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
-  await writeFile(path, content);
+  await atomicWrite(path, content + `
+`);
 }
 export {
   atomicWrite,

package/dist/utils/file-io.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/utils/file-io.ts"],
-  "sourcesContent": ["import { mkdir, rename, readFile as fsReadFile, writeFile as fsWriteFile, stat } from \"node:fs/promises\";\nimport { existsSync as fsExistsSync } from \"node:fs\";\nimport { startSpan, endSpan } from \"../telemetry/index.js\";\n\n// Fallback for runtime environments where TELEMETRY_ENABLED is not defined by esbuild\ndeclare const TELEMETRY_ENABLED: boolean | undefined;\nconst isTelemetryEnabled = typeof TELEMETRY_ENABLED !== 'undefined' ? TELEMETRY_ENABLED : false;\n\n/**\n * Ensure a directory exists, creating it if necessary\n */\nexport async function ensureDir(path: string): Promise<void> {\n  await mkdir(path, { recursive: true });\n}\n\n/**\n * Write content to a file atomically using a temporary file\n */\nexport async function atomicWrite(path: string, content: string): Promise<void> {\n  const fileExists = fsExistsSync(path);\n\n  const span = startSpan('file.write', {\n    'file.path': path,\n    'file.size': content.length,\n    'file.created': !fileExists,\n  });\n\n  try {\n    const tempPath = `${path}.tmp`;\n    await fsWriteFile(tempPath, content, 'utf-8');\n    // Rename temp file to target path (atomic operation)\n    await rename(tempPath, path);\n  } finally {\n    endSpan(span);\n  }\n}\n\n/**\n * Check if a file exists\n */\nexport async function fileExists(path: string): Promise<boolean> {\n  try {\n    await stat(path);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Read a file as text\n */\nexport async function readFile(path: string): Promise<string> {\n  const span = startSpan('file.read', {\n    'file.path': path,\n    'file.exists': fsExistsSync(path),\n  });\n\n  try {\n    const content = await fsReadFile(path, 'utf-8');\n\n    if (isTelemetryEnabled && span) {\n      span.setAttribute('file.size', content.length);\n    }\n\n    return content;\n  } finally {\n    endSpan(span);\n  }\n}\n\n/**\n * Write content to a file\n */\nexport async function writeFile(path: string, content: string): Promise<void> {\n  const fileExists = fsExistsSync(path);\n\n  const span = startSpan('file.write', {\n    'file.path': path,\n    'file.size': content.length,\n    'file.created': !fileExists,\n  });\n\n  try {\n    await fsWriteFile(path, content, 'utf-8');\n  } finally {\n    endSpan(span);\n  }\n}\n\n/**\n * Read a JSON file\n */\nexport async function readJSON<T>(path: string): Promise<T> {\n  const content = await readFile(path);\n  return JSON.parse(content) as T;\n}\n\n/**\n * Write a JSON object to a file\n */\nexport async function writeJSON<T>(path: string, data: T, pretty: boolean = true): Promise<void> {\n  const content = pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);\n  await writeFile(path, content);\n}\n"],
-  "mappings": "AAAA,SAAS,OAAO,QAAQ,YAAY,YAAY,aAAa,aAAa,YAAY;AACtF,SAAS,cAAc,oBAAoB;AAC3C,SAAS,WAAW,eAAe;AAInC,MAAM,qBAAgE;AAKtE,eAAsB,UAAU,MAAY;AAC1C,QAAM,MAAM,MAAM,EAAE,WAAW,GAAI,CAAE;AACvC;AAKA,eAAsB,YAAY,MAAc,SAAe;AAC7D,QAAMA,cAAa,aAAa,IAAI,GAE9B,OAAO,UAAU,cAAc;IACnC,aAAa;IACb,aAAa,QAAQ;IACrB,gBAAgB,CAACA;GAClB;AAED,MAAI;AACF,UAAM,WAAW,GAAG,IAAI;AACxB,UAAM,YAAY,UAAU,SAAS,OAAO,GAE5C,MAAM,OAAO,UAAU,IAAI;EAC7B;AACE,YAAQ,IAAI;EACd;AACF;AAKA,eAAsB,WAAW,MAAY;AAC3C,MAAI;AACF,iBAAM,KAAK,IAAI,GACR;EACT,QAAQ;AACN,WAAO;EACT;AACF;AAKA,eAAsB,SAAS,MAAY;AACzC,QAAM,OAAO,UAAU,aAAa;IAClC,aAAa;IACb,eAAe,aAAa,IAAI;GACjC;AAED,MAAI;AACF,UAAM,UAAU,MAAM,WAAW,MAAM,OAAO;AAE9C,WAAI,sBAAsB,QACxB,KAAK,aAAa,aAAa,QAAQ,MAAM,GAGxC;EACT;AACE,YAAQ,IAAI;EACd;AACF;AAKA,eAAsB,UAAU,MAAc,SAAe;AAC3D,QAAMA,cAAa,aAAa,IAAI,GAE9B,OAAO,UAAU,cAAc;IACnC,aAAa;IACb,aAAa,QAAQ;IACrB,gBAAgB,CAACA;GAClB;AAED,MAAI;AACF,UAAM,YAAY,MAAM,SAAS,OAAO;EAC1C;AACE,YAAQ,IAAI;EACd;AACF;AAKA,eAAsB,SAAY,MAAY;AAC5C,QAAM,UAAU,MAAM,SAAS,IAAI;AACnC,SAAO,KAAK,MAAM,OAAO;AAC3B;AAKA,eAAsB,UAAa,MAAc,MAAS,SAAkB,IAAI;AAC9E,QAAM,UAAU,SAAS,KAAK,UAAU,MAAM,MAAM,CAAC,IAAI,KAAK,UAAU,IAAI;AAC5E,QAAM,UAAU,MAAM,OAAO;AAC/B;",
+  "sourcesContent": ["import {\n  mkdir,\n  rename,\n  readFile as fsReadFile,\n  writeFile as fsWriteFile,\n  stat,\n} from \"node:fs/promises\";\nimport { existsSync as fsExistsSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport { startSpan, endSpan } from \"../telemetry/index.js\";\n\n// Fallback for runtime environments where TELEMETRY_ENABLED is not defined by esbuild\ndeclare const TELEMETRY_ENABLED: boolean | undefined;\nconst isTelemetryEnabled = typeof TELEMETRY_ENABLED !== \"undefined\" ? TELEMETRY_ENABLED : false;\n\n/**\n * Ensure a directory exists, creating it if necessary\n */\nexport async function ensureDir(path: string): Promise<void> {\n  await mkdir(path, { recursive: true });\n}\n\n/**\n * Write content to a file atomically using a temporary file\n */\nexport async function atomicWrite(path: string, content: string): Promise<void> {\n  const fileExists = fsExistsSync(path);\n\n  const span = startSpan(\"file.write\", {\n    \"file.path\": path,\n    \"file.size\": content.length,\n    \"file.created\": !fileExists,\n  });\n\n  try {\n    // Ensure parent directory exists\n    const dir = dirname(path);\n    await mkdir(dir, { recursive: true });\n\n    const tempPath = `${path}.tmp`;\n    await fsWriteFile(tempPath, content, \"utf-8\");\n    // Rename temp file to target path (atomic operation)\n    await rename(tempPath, path);\n  } finally {\n    endSpan(span);\n  }\n}\n\n/**\n * Check if a file exists\n */\nexport async function fileExists(path: string): Promise<boolean> {\n  try {\n    await stat(path);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Read a file as text\n */\nexport async function readFile(path: string): Promise<string> {\n  const span = startSpan(\"file.read\", {\n    \"file.path\": path,\n    \"file.exists\": fsExistsSync(path),\n  });\n\n  try {\n    const content = await fsReadFile(path, \"utf-8\");\n\n    if (isTelemetryEnabled && span) {\n      span.setAttribute(\"file.size\", content.length);\n    }\n\n    return content;\n  } finally {\n    endSpan(span);\n  }\n}\n\n/**\n * Write content to a file\n */\nexport async function writeFile(path: string, content: string): Promise<void> {\n  const fileExists = fsExistsSync(path);\n\n  const span = startSpan(\"file.write\", {\n    \"file.path\": path,\n    \"file.size\": content.length,\n    \"file.created\": !fileExists,\n  });\n\n  try {\n    // Ensure parent directory exists\n    const dir = dirname(path);\n    await mkdir(dir, { recursive: true });\n\n    await fsWriteFile(path, content, \"utf-8\");\n  } finally {\n    endSpan(span);\n  }\n}\n\n/**\n * Read a JSON file\n */\nexport async function readJSON<T>(path: string): Promise<T> {\n  const content = await readFile(path);\n  return JSON.parse(content) as T;\n}\n\n/**\n * Write a JSON object to a file\n * Uses atomic write to prevent corruption\n */\nexport async function writeJSON<T>(path: string, data: T, pretty: boolean = true): Promise<void> {\n  const content = pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);\n  await atomicWrite(path, content + \"\\n\");\n}\n"],
+  "mappings": "AAAA,SACE,OACA,QACA,YAAY,YACZ,aAAa,aACb,YACK;AACP,SAAS,cAAc,oBAAoB;AAC3C,SAAS,eAAe;AACxB,SAAS,WAAW,eAAe;AAInC,MAAM,qBAAgE;AAKtE,eAAsB,UAAU,MAAY;AAC1C,QAAM,MAAM,MAAM,EAAE,WAAW,GAAI,CAAE;AACvC;AAKA,eAAsB,YAAY,MAAc,SAAe;AAC7D,QAAMA,cAAa,aAAa,IAAI,GAE9B,OAAO,UAAU,cAAc;IACnC,aAAa;IACb,aAAa,QAAQ;IACrB,gBAAgB,CAACA;GAClB;AAED,MAAI;AAEF,UAAM,MAAM,QAAQ,IAAI;AACxB,UAAM,MAAM,KAAK,EAAE,WAAW,GAAI,CAAE;AAEpC,UAAM,WAAW,GAAG,IAAI;AACxB,UAAM,YAAY,UAAU,SAAS,OAAO,GAE5C,MAAM,OAAO,UAAU,IAAI;EAC7B;AACE,YAAQ,IAAI;EACd;AACF;AAKA,eAAsB,WAAW,MAAY;AAC3C,MAAI;AACF,iBAAM,KAAK,IAAI,GACR;EACT,QAAQ;AACN,WAAO;EACT;AACF;AAKA,eAAsB,SAAS,MAAY;AACzC,QAAM,OAAO,UAAU,aAAa;IAClC,aAAa;IACb,eAAe,aAAa,IAAI;GACjC;AAED,MAAI;AACF,UAAM,UAAU,MAAM,WAAW,MAAM,OAAO;AAE9C,WAAI,sBAAsB,QACxB,KAAK,aAAa,aAAa,QAAQ,MAAM,GAGxC;EACT;AACE,YAAQ,IAAI;EACd;AACF;AAKA,eAAsB,UAAU,MAAc,SAAe;AAC3D,QAAMA,cAAa,aAAa,IAAI,GAE9B,OAAO,UAAU,cAAc;IACnC,aAAa;IACb,aAAa,QAAQ;IACrB,gBAAgB,CAACA;GAClB;AAED,MAAI;AAEF,UAAM,MAAM,QAAQ,IAAI;AACxB,UAAM,MAAM,KAAK,EAAE,WAAW,GAAI,CAAE,GAEpC,MAAM,YAAY,MAAM,SAAS,OAAO;EAC1C;AACE,YAAQ,IAAI;EACd;AACF;AAKA,eAAsB,SAAY,MAAY;AAC5C,QAAM,UAAU,MAAM,SAAS,IAAI;AACnC,SAAO,KAAK,MAAM,OAAO;AAC3B;AAMA,eAAsB,UAAa,MAAc,MAAS,SAAkB,IAAI;AAC9E,QAAM,UAAU,SAAS,KAAK,UAAU,MAAM,MAAM,CAAC,IAAI,KAAK,UAAU,IAAI;AAC5E,QAAM,YAAY,MAAM,UAAU;CAAI;AACxC;",
   "names": ["fileExists"]
 }

package/dist/utils/file-lock.js

@@ -0,0 +1,156 @@
+import { mkdir, rm, stat } from "fs/promises";
+import { existsSync } from "fs";
+const DEFAULT_STALE_LOCK_THRESHOLD = 3e4;
+class FileLock {
+  lockPath;
+  acquired = !1;
+  constructor(resourcePath) {
+    this.lockPath = `${resourcePath}.lock`;
+  }
+  /**
+   * Acquire exclusive lock with timeout and retry
+   *
+   * Uses atomic directory creation (mkdir with recursive: false) to ensure
+   * only one process can acquire the lock at a time.
+   *
+   * Before attempting lock acquisition, automatically checks for stale locks
+   * (locks older than the configured threshold) and removes them if detected.
+   * This prevents the CLI from becoming unusable after process crashes.
+   */
+  async acquire(options = {}) {
+    const timeout = options.timeout || 5e3, retryInterval = options.retryInterval || 50, staleLockThreshold = options.staleLockThreshold || DEFAULT_STALE_LOCK_THRESHOLD;
+    if (options.detectStaleLocks !== !1)
+      try {
+        await FileLock.cleanupStaleLocks(this.lockPath.replace(/\.lock$/, ""), staleLockThreshold);
+      } catch {
+      }
+    const startTime = Date.now();
+    for (; ; )
+      try {
+        await mkdir(this.lockPath, { recursive: !1 }), this.acquired = !0;
+        return;
+      } catch (error) {
+        if (error.code === "EEXIST") {
+          if (Date.now() - startTime >= timeout)
+            throw new Error(`Failed to acquire lock on ${this.lockPath} within ${timeout}ms. Resource may be locked by another process or operation.`);
+          await this.sleep(retryInterval);
+        } else
+          throw new Error(`Failed to acquire lock on ${this.lockPath}: ${error.message}`);
+      }
+  }
+  /**
+   * Release the lock
+   *
+   * Removes the lock directory. Should always be called in a finally block.
+   * Throws errors on filesystem failures to propagate critical issues.
+   *
+   * @throws {Error} If lock removal fails (permission denied, disk full, etc)
+   */
+  async release() {
+    if (this.acquired)
+      try {
+        await rm(this.lockPath, { recursive: !0, force: !0 }), this.acquired = !1;
+      } catch (error) {
+        const errorMsg = `Failed to release lock on ${this.lockPath} (acquired: ${this.acquired}): ${error.message}`;
+        throw console.error(`ERROR: ${errorMsg}`), new Error(errorMsg);
+      }
+  }
+  /**
+   * Check if lock is currently held by this instance
+   */
+  isAcquired() {
+    return this.acquired;
+  }
+  /**
+   * Execute function with lock protection
+   *
+   * Acquires lock, executes function, and releases lock in finally block.
+   * Ensures lock is always released even if function throws.
+   *
+   * Propagates both function errors and lock release errors to the caller.
+   * If the function throws and lock release also fails, the lock release error
+   * is thrown (with original error logged).
+   *
+   * @throws {Error} If function throws or if lock release fails
+   */
+  async withLock(fn, options) {
+    await this.acquire(options);
+    let fnError;
+    try {
+      return await fn();
+    } catch (error) {
+      throw fnError = error, error;
+    } finally {
+      try {
+        await this.release();
+      } catch (releaseError) {
+        throw fnError && console.error(`Function error suppressed due to lock release failure. Function error: ${fnError instanceof Error ? fnError.message : String(fnError)}`), releaseError;
+      }
+    }
+  }
+  /**
+   * Check if a lock file exists (static utility)
+   */
+  static exists(resourcePath) {
+    return existsSync(`${resourcePath}.lock`);
+  }
+  /**
+   * Check if a lock is stale based on age
+   *
+   * A lock is considered stale if its modification time exceeds the threshold.
+   * This helps detect locks from crashed processes.
+   *
+   * @param resourcePath - Path to the locked resource
+   * @param threshold - Max age in ms before lock is considered stale (default: 30s)
+   * @returns true if lock exists and is stale, false otherwise
+   */
+  static async isLockStale(resourcePath, threshold = DEFAULT_STALE_LOCK_THRESHOLD) {
+    const lockPath = `${resourcePath}.lock`;
+    try {
+      if (!existsSync(lockPath))
+        return !1;
+      const stats = await stat(lockPath);
+      return Date.now() - stats.mtime.getTime() > threshold;
+    } catch {
+      return !1;
+    }
+  }
+  /**
+   * Cleanup stale locks automatically
+   *
+   * Removes lock directories that are older than the specified threshold.
+   * Logs the cleanup action for diagnostics. Safe to call repeatedly.
+   *
+   * @param resourcePath - Path to the locked resource
+   * @param threshold - Max age in ms before lock is considered stale (default: 30s)
+   */
+  static async cleanupStaleLocks(resourcePath, threshold = DEFAULT_STALE_LOCK_THRESHOLD) {
+    if (await this.isLockStale(resourcePath, threshold)) {
+      const lockPath = `${resourcePath}.lock`;
+      try {
+        const stats = await stat(lockPath), lockAge = Date.now() - stats.mtime.getTime();
+        await rm(lockPath, { recursive: !0, force: !0 }), console.log(`Cleaned up stale lock at ${lockPath} (age: ${lockAge}ms, threshold: ${threshold}ms)`);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Force remove a stale lock (static utility)
+   *
+   * Use with caution - only for cleaning up locks from crashed processes.
+   */
+  static async forceRemove(resourcePath) {
+    const lockPath = `${resourcePath}.lock`;
+    await rm(lockPath, { recursive: !0, force: !0 });
+  }
+  /**
+   * Sleep utility for retry delays
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+export {
+  FileLock
+};
+//# sourceMappingURL=file-lock.js.map

package/dist/utils/file-lock.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/file-lock.ts"],
+  "sourcesContent": ["/**\n * FileLock - Simple file-based locking mechanism for concurrent operations\n *\n * Uses atomic file creation to implement exclusive locks with timeout and retry.\n * Prevents race conditions in read-modify-write operations on changeset files.\n */\n\nimport { mkdir, rm, stat } from \"fs/promises\";\nimport { existsSync } from \"fs\";\n\nconst DEFAULT_STALE_LOCK_THRESHOLD = 30000; // 30 seconds\n\nexport interface LockOptions {\n  timeout?: number; // Max time to wait for lock (ms)\n  retryInterval?: number; // Time between retry attempts (ms)\n  staleLockThreshold?: number; // Threshold in ms for detecting stale locks (default: 30000ms)\n  detectStaleLocks?: boolean; // Whether to automatically detect and cleanup stale locks (default: true)\n}\n\n/**\n * FileLock provides exclusive access to a resource using lockfiles\n */\nexport class FileLock {\n  private lockPath: string;\n  private acquired: boolean = false;\n\n  constructor(resourcePath: string) {\n    // Create lock file path by appending .lock\n    this.lockPath = `${resourcePath}.lock`;\n  }\n\n  /**\n   * Acquire exclusive lock with timeout and retry\n   *\n   * Uses atomic directory creation (mkdir with recursive: false) to ensure\n   * only one process can acquire the lock at a time.\n   *\n   * Before attempting lock acquisition, automatically checks for stale locks\n   * (locks older than the configured threshold) and removes them if detected.\n   * This prevents the CLI from becoming unusable after process crashes.\n   */\n  async acquire(options: LockOptions = {}): Promise<void> {\n    const timeout = options.timeout || 5000; // 5 second default\n    const retryInterval = options.retryInterval || 50; // 50ms default\n    const staleLockThreshold = options.staleLockThreshold || DEFAULT_STALE_LOCK_THRESHOLD;\n    const detectStaleLocks = options.detectStaleLocks !== false; // true by default\n\n    // Attempt to clean up stale locks before acquiring\n    if (detectStaleLocks) {\n      try {\n        await FileLock.cleanupStaleLocks(this.lockPath.replace(/\\.lock$/, \"\"), staleLockThreshold);\n      } catch {\n        // Silently ignore cleanup errors - we'll still attempt to acquire the lock\n      }\n    }\n\n    const startTime = Date.now();\n\n    while (true) {\n      try {\n        // Atomic operation: mkdir fails if directory exists\n        await mkdir(this.lockPath, { recursive: false });\n        this.acquired = true;\n        return;\n      } catch (error: any) {\n        if (error.code === \"EEXIST\") {\n          // Lock is held by another process\n          if (Date.now() - startTime >= timeout) {\n            throw new Error(\n              `Failed to acquire lock on ${this.lockPath} within ${timeout}ms. ` +\n                `Resource may be locked by another process or operation.`\n            );\n          }\n\n          // Wait before retrying\n          await this.sleep(retryInterval);\n        } else {\n          // Unexpected error\n          throw new Error(`Failed to acquire lock on ${this.lockPath}: ${error.message}`);\n        }\n      }\n    }\n  }\n\n  /**\n   * Release the lock\n   *\n   * Removes the lock directory. Should always be called in a finally block.\n   * Throws errors on filesystem failures to propagate critical issues.\n   *\n   * @throws {Error} If lock removal fails (permission denied, disk full, etc)\n   */\n  async release(): Promise<void> {\n    if (!this.acquired) {\n      return;\n    }\n\n    try {\n      await rm(this.lockPath, { recursive: true, force: true });\n      this.acquired = false;\n    } catch (error: any) {\n      // Construct detailed error message with lock state\n      const errorMsg = `Failed to release lock on ${this.lockPath} (acquired: ${this.acquired}): ${error.message}`;\n\n      // Log the error for visibility\n      console.error(`ERROR: ${errorMsg}`);\n\n      // Throw to propagate to callers - they may attempt force removal\n      throw new Error(errorMsg);\n    }\n  }\n\n  /**\n   * Check if lock is currently held by this instance\n   */\n  isAcquired(): boolean {\n    return this.acquired;\n  }\n\n  /**\n   * Execute function with lock protection\n   *\n   * Acquires lock, executes function, and releases lock in finally block.\n   * Ensures lock is always released even if function throws.\n   *\n   * Propagates both function errors and lock release errors to the caller.\n   * If the function throws and lock release also fails, the lock release error\n   * is thrown (with original error logged).\n   *\n   * @throws {Error} If function throws or if lock release fails\n   */\n  async withLock<T>(fn: () => Promise<T>, options?: LockOptions): Promise<T> {\n    await this.acquire(options);\n    let fnError: unknown;\n\n    try {\n      return await fn();\n    } catch (error) {\n      // Capture function error to re-throw after attempting lock release\n      fnError = error;\n      throw error;\n    } finally {\n      try {\n        await this.release();\n      } catch (releaseError) {\n        // If function already threw, log both errors\n        // Release error takes precedence since it indicates filesystem corruption\n        if (fnError) {\n          console.error(\n            `Function error suppressed due to lock release failure. ` +\n              `Function error: ${fnError instanceof Error ? fnError.message : String(fnError)}`\n          );\n        }\n        throw releaseError;\n      }\n    }\n  }\n\n  /**\n   * Check if a lock file exists (static utility)\n   */\n  static exists(resourcePath: string): boolean {\n    return existsSync(`${resourcePath}.lock`);\n  }\n\n  /**\n   * Check if a lock is stale based on age\n   *\n   * A lock is considered stale if its modification time exceeds the threshold.\n   * This helps detect locks from crashed processes.\n   *\n   * @param resourcePath - Path to the locked resource\n   * @param threshold - Max age in ms before lock is considered stale (default: 30s)\n   * @returns true if lock exists and is stale, false otherwise\n   */\n  static async isLockStale(\n    resourcePath: string,\n    threshold: number = DEFAULT_STALE_LOCK_THRESHOLD\n  ): Promise<boolean> {\n    const lockPath = `${resourcePath}.lock`;\n\n    try {\n      if (!existsSync(lockPath)) {\n        return false;\n      }\n\n      const stats = await stat(lockPath);\n      const lockAge = Date.now() - stats.mtime.getTime();\n      return lockAge > threshold;\n    } catch {\n      // If we can't determine lock age, treat as valid (not stale)\n      // This ensures we don't accidentally remove locks we're unsure about\n      return false;\n    }\n  }\n\n  /**\n   * Cleanup stale locks automatically\n   *\n   * Removes lock directories that are older than the specified threshold.\n   * Logs the cleanup action for diagnostics. Safe to call repeatedly.\n   *\n   * @param resourcePath - Path to the locked resource\n   * @param threshold - Max age in ms before lock is considered stale (default: 30s)\n   */\n  static async cleanupStaleLocks(\n    resourcePath: string,\n    threshold: number = DEFAULT_STALE_LOCK_THRESHOLD\n  ): Promise<void> {\n    const isStale = await this.isLockStale(resourcePath, threshold);\n\n    if (isStale) {\n      const lockPath = `${resourcePath}.lock`;\n      try {\n        const stats = await stat(lockPath);\n        const lockAge = Date.now() - stats.mtime.getTime();\n        await rm(lockPath, { recursive: true, force: true });\n        console.log(\n          `Cleaned up stale lock at ${lockPath} (age: ${lockAge}ms, threshold: ${threshold}ms)`\n        );\n      } catch (error) {\n        // Silently ignore cleanup errors - lock may have been removed by another process\n        // or other temporary filesystem issues\n      }\n    }\n  }\n\n  /**\n   * Force remove a stale lock (static utility)\n   *\n   * Use with caution - only for cleaning up locks from crashed processes.\n   */\n  static async forceRemove(resourcePath: string): Promise<void> {\n    const lockPath = `${resourcePath}.lock`;\n    await rm(lockPath, { recursive: true, force: true });\n  }\n\n  /**\n   * Sleep utility for retry delays\n   */\n  private sleep(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n  }\n}\n"],
+  "mappings": "AAOA,SAAS,OAAO,IAAI,YAAY;AAChC,SAAS,kBAAkB;AAE3B,MAAM,+BAA+B;AAY/B,MAAO,SAAQ;EACX;EACA,WAAoB;EAE5B,YAAY,cAAoB;AAE9B,SAAK,WAAW,GAAG,YAAY;EACjC;;;;;;;;;;;EAYA,MAAM,QAAQ,UAAuB,CAAA,GAAE;AACrC,UAAM,UAAU,QAAQ,WAAW,KAC7B,gBAAgB,QAAQ,iBAAiB,IACzC,qBAAqB,QAAQ,sBAAsB;AAIzD,QAHyB,QAAQ,qBAAqB;AAIpD,UAAI;AACF,cAAM,SAAS,kBAAkB,KAAK,SAAS,QAAQ,WAAW,EAAE,GAAG,kBAAkB;MAC3F,QAAQ;MAER;AAGF,UAAM,YAAY,KAAK,IAAG;AAE1B;AACE,UAAI;AAEF,cAAM,MAAM,KAAK,UAAU,EAAE,WAAW,GAAK,CAAE,GAC/C,KAAK,WAAW;AAChB;MACF,SAAS,OAAY;AACnB,YAAI,MAAM,SAAS,UAAU;AAE3B,cAAI,KAAK,IAAG,IAAK,aAAa;AAC5B,kBAAM,IAAI,MACR,6BAA6B,KAAK,QAAQ,WAAW,OAAO,6DACD;AAK/D,gBAAM,KAAK,MAAM,aAAa;QAChC;AAEE,gBAAM,IAAI,MAAM,6BAA6B,KAAK,QAAQ,KAAK,MAAM,OAAO,EAAE;MAElF;EAEJ;;;;;;;;;EAUA,MAAM,UAAO;AACX,QAAK,KAAK;AAIV,UAAI;AACF,cAAM,GAAG,KAAK,UAAU,EAAE,WAAW,IAAM,OAAO,GAAI,CAAE,GACxD,KAAK,WAAW;MAClB,SAAS,OAAY;AAEnB,cAAM,WAAW,6BAA6B,KAAK,QAAQ,eAAe,KAAK,QAAQ,MAAM,MAAM,OAAO;AAG1G,sBAAQ,MAAM,UAAU,QAAQ,EAAE,GAG5B,IAAI,MAAM,QAAQ;MAC1B;EACF;;;;EAKA,aAAU;AACR,WAAO,KAAK;EACd;;;;;;;;;;;;;EAcA,MAAM,SAAY,IAAsB,SAAqB;AAC3D,UAAM,KAAK,QAAQ,OAAO;AAC1B,QAAI;AAEJ,QAAI;AACF,aAAO,MAAM,GAAE;IACjB,SAAS,OAAO;AAEd,sBAAU,OACJ;IACR;AACE,UAAI;AACF,cAAM,KAAK,QAAO;MACpB,SAAS,cAAc;AAGrB,cAAI,WACF,QAAQ,MACN,0EACqB,mBAAmB,QAAQ,QAAQ,UAAU,OAAO,OAAO,CAAC,EAAE,GAGjF;MACR;IACF;EACF;;;;EAKA,OAAO,OAAO,cAAoB;AAChC,WAAO,WAAW,GAAG,YAAY,OAAO;EAC1C;;;;;;;;;;;EAYA,aAAa,YACX,cACA,YAAoB,8BAA4B;AAEhD,UAAM,WAAW,GAAG,YAAY;AAEhC,QAAI;AACF,UAAI,CAAC,WAAW,QAAQ;AACtB,eAAO;AAGT,YAAM,QAAQ,MAAM,KAAK,QAAQ;AAEjC,aADgB,KAAK,IAAG,IAAK,MAAM,MAAM,QAAO,IAC/B;IACnB,QAAQ;AAGN,aAAO;IACT;EACF;;;;;;;;;;EAWA,aAAa,kBACX,cACA,YAAoB,8BAA4B;AAIhD,QAFgB,MAAM,KAAK,YAAY,cAAc,SAAS,GAEjD;AACX,YAAM,WAAW,GAAG,YAAY;AAChC,UAAI;AACF,cAAM,QAAQ,MAAM,KAAK,QAAQ,GAC3B,UAAU,KAAK,IAAG,IAAK,MAAM,MAAM,QAAO;AAChD,cAAM,GAAG,UAAU,EAAE,WAAW,IAAM,OAAO,GAAI,CAAE,GACnD,QAAQ,IACN,4BAA4B,QAAQ,UAAU,OAAO,kBAAkB,SAAS,KAAK;MAEzF,QAAgB;MAGhB;IACF;EACF;;;;;;EAOA,aAAa,YAAY,cAAoB;AAC3C,UAAM,WAAW,GAAG,YAAY;AAChC,UAAM,GAAG,UAAU,EAAE,WAAW,IAAM,OAAO,GAAI,CAAE;EACrD;;;;EAKQ,MAAM,IAAU;AACtB,WAAO,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,EAAE,CAAC;EACzD;;",
+  "names": []
+}

package/dist/utils/id-generator.js

@@ -0,0 +1,18 @@
+import crypto from "node:crypto";
+function toKebabCase(text) {
+  let result = text.replace(/[\s_]+/g, "-");
+  return result = result.replace(/([a-z])([A-Z])/g, "$1-$2"), result = result.toLowerCase(), result = result.replace(/\./g, ""), result = result.replace(/[^a-z0-9-]/g, ""), result = result.replace(/-+/g, "-"), result = result.replace(/^-+|-+$/g, ""), result;
+}
+function generateElementId(layer, elementType, name) {
+  const kebabName = toKebabCase(name);
+  return `${layer}.${elementType}.${kebabName}`;
+}
+function generateUUID() {
+  return crypto.randomUUID();
+}
+export {
+  generateElementId,
+  generateUUID,
+  toKebabCase
+};
+//# sourceMappingURL=id-generator.js.map

package/dist/utils/id-generator.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/id-generator.ts"],
+  "sourcesContent": ["/**\n * Element ID generation utilities matching Python CLI implementation.\n */\n\nimport crypto from \"node:crypto\";\n\n/**\n * Convert text to kebab-case.\n * Matches Python implementation in utils/id_generator.py\n *\n * @example\n * toKebabCase(\"Customer Management\") // \"customer-management\"\n * toKebabCase(\"CustomerManagement\")  // \"customer-management\"\n * toKebabCase(\"customer_management\") // \"customer-management\"\n */\nexport function toKebabCase(text: string): string {\n  // Replace spaces and underscores with hyphens\n  let result = text.replace(/[\\s_]+/g, \"-\");\n\n  // Insert hyphen before capital letters (for camelCase/PascalCase)\n  result = result.replace(/([a-z])([A-Z])/g, \"$1-$2\");\n\n  // Convert to lowercase\n  result = result.toLowerCase();\n\n  // Remove dots (e.g. \"Node.js\" \u2192 \"nodejs\") to prevent extra ID segments\n  result = result.replace(/\\./g, \"\");\n\n  // Remove any characters not valid in a slug (keeps only a-z, 0-9, hyphens)\n  result = result.replace(/[^a-z0-9-]/g, \"\");\n\n  // Remove multiple consecutive hyphens\n  result = result.replace(/-+/g, \"-\");\n\n  // Remove leading/trailing hyphens\n  result = result.replace(/^-+|-+$/g, \"\");\n\n  return result;\n}\n\n/**\n * Generate element ID following Python CLI convention: {layer}.{type}.{kebab-name}\n * Matches Python implementation in utils/id_generator.py\n *\n * @example\n * generateElementId(\"business\", \"service\", \"Customer Management\")\n * // \"business.service.customer-management\"\n */\nexport function generateElementId(layer: string, elementType: string, name: string): string {\n  const kebabName = toKebabCase(name);\n  return `${layer}.${elementType}.${kebabName}`;\n}\n\n/**\n * Generate a new UUIDv4 using the Node.js built-in crypto module.\n *\n * @example\n * generateUUID() // \"550e8400-e29b-41d4-a716-446655440000\"\n */\nexport function generateUUID(): string {\n  return crypto.randomUUID();\n}\n"],
+  "mappings": "AAIA,OAAO,YAAY;AAWb,SAAU,YAAY,MAAY;AAEtC,MAAI,SAAS,KAAK,QAAQ,WAAW,GAAG;AAGxC,kBAAS,OAAO,QAAQ,mBAAmB,OAAO,GAGlD,SAAS,OAAO,YAAW,GAG3B,SAAS,OAAO,QAAQ,OAAO,EAAE,GAGjC,SAAS,OAAO,QAAQ,eAAe,EAAE,GAGzC,SAAS,OAAO,QAAQ,OAAO,GAAG,GAGlC,SAAS,OAAO,QAAQ,YAAY,EAAE,GAE/B;AACT;AAUM,SAAU,kBAAkB,OAAe,aAAqB,MAAY;AAChF,QAAM,YAAY,YAAY,IAAI;AAClC,SAAO,GAAG,KAAK,IAAI,WAAW,IAAI,SAAS;AAC7C;AAQM,SAAU,eAAY;AAC1B,SAAO,OAAO,WAAU;AAC1B;",
+  "names": []
+}

package/dist/utils/layer-name-formatter.js

@@ -0,0 +1,16 @@
+function formatLayerName(layerName) {
+  const acronyms = {
+    api: "API",
+    ux: "UX",
+    apm: "APM"
+  };
+  return acronyms[layerName] ? acronyms[layerName] : layerName.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+function formatLayerNameWithSuffix(layerName) {
+  return `${formatLayerName(layerName)} layer`;
+}
+export {
+  formatLayerName,
+  formatLayerNameWithSuffix
+};
+//# sourceMappingURL=layer-name-formatter.js.map

package/dist/utils/layer-name-formatter.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/layer-name-formatter.ts"],
+  "sourcesContent": ["/**\n * Centralized layer name formatting\n * Ensures consistent layer name display across all CLI output\n */\n\n/**\n * Format layer name for display with title case\n * Examples: \"motivation\" \u2192 \"Motivation\", \"data-model\" \u2192 \"Data Model\"\n * Special cases: \"api\" \u2192 \"API\", \"ux\" \u2192 \"UX\", \"apm\" \u2192 \"APM\"\n */\nexport function formatLayerName(layerName: string): string {\n  // Handle special acronym cases\n  const acronyms: Record<string, string> = {\n    api: \"API\",\n    ux: \"UX\",\n    apm: \"APM\",\n  };\n\n  if (acronyms[layerName]) {\n    return acronyms[layerName];\n  }\n\n  return layerName\n    .split(\"-\")\n    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))\n    .join(\" \");\n}\n\n/**\n * Format layer name with \" layer\" suffix\n * Examples: \"motivation\" \u2192 \"Motivation layer\", \"data-model\" \u2192 \"Data Model layer\"\n */\nexport function formatLayerNameWithSuffix(layerName: string): string {\n  return `${formatLayerName(layerName)} layer`;\n}\n"],
+  "mappings": "AAUM,SAAU,gBAAgB,WAAiB;AAE/C,QAAM,WAAmC;IACvC,KAAK;IACL,IAAI;IACJ,KAAK;;AAGP,SAAI,SAAS,SAAS,IACb,SAAS,SAAS,IAGpB,UACJ,MAAM,GAAG,EACT,IAAI,CAAC,SAAS,KAAK,OAAO,CAAC,EAAE,YAAW,IAAK,KAAK,MAAM,CAAC,CAAC,EAC1D,KAAK,GAAG;AACb;AAMM,SAAU,0BAA0B,WAAiB;AACzD,SAAO,GAAG,gBAAgB,SAAS,CAAC;AACtC;",
+  "names": []
+}

package/dist/utils/markdown-anchor.js

@@ -0,0 +1,7 @@
+function createAnchor(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+export {
+  createAnchor
+};
+//# sourceMappingURL=markdown-anchor.js.map

package/dist/utils/markdown-anchor.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/markdown-anchor.ts"],
+  "sourcesContent": ["/**\n * Markdown anchor utilities for heading links\n */\n\n/**\n * Create a markdown anchor from text by converting to lowercase and replacing non-alphanumeric characters with hyphens\n * @param text The text to convert to an anchor\n * @returns Anchor string suitable for markdown heading links\n */\nexport function createAnchor(text: string): string {\n  return text\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, \"-\")\n    .replace(/^-|-$/g, \"\");\n}\n"],
+  "mappings": "AASM,SAAU,aAAa,MAAY;AACvC,SAAO,KACJ,YAAW,EACX,QAAQ,eAAe,GAAG,EAC1B,QAAQ,UAAU,EAAE;AACzB;",
+  "names": []
+}

package/dist/utils/markdown-link.js

@@ -0,0 +1,12 @@
+function formatNodeTypeName(type) {
+  return type.split(/(?=[A-Z])/).join(" ").replace(/^./, (c) => c.toUpperCase());
+}
+function createDescriptiveLinkText(type) {
+  const prohibited = ["click here", "here", "link", "more"], formatted = formatNodeTypeName(type);
+  return prohibited.includes(formatted.toLowerCase()) ? `${formatted} node` : formatted;
+}
+export {
+  createDescriptiveLinkText,
+  formatNodeTypeName
+};
+//# sourceMappingURL=markdown-link.js.map

package/dist/utils/markdown-link.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/markdown-link.ts"],
+  "sourcesContent": ["/**\n * Markdown link text utilities\n */\n\n/**\n * Format node type name for display by splitting on capital letters and title-casing\n * @param type The node type string (e.g., \"CustomEndpoint\")\n * @returns Formatted display name (e.g., \"Custom Endpoint\")\n */\nexport function formatNodeTypeName(type: string): string {\n  return type\n    .split(/(?=[A-Z])/)\n    .join(\" \")\n    .replace(/^./, (c) => c.toUpperCase());\n}\n\n/**\n * Create descriptive link text that avoids markdownlint MD059 prohibited texts\n * Prohibited texts: \"click here\", \"here\", \"link\", \"more\"\n * @param type The node type to create link text for\n * @returns Descriptive link text safe for markdownlint MD059\n */\nexport function createDescriptiveLinkText(type: string): string {\n  const prohibited = [\"click here\", \"here\", \"link\", \"more\"];\n  const formatted = formatNodeTypeName(type);\n\n  if (prohibited.includes(formatted.toLowerCase())) {\n    // Add \"node\" suffix to make it descriptive\n    return `${formatted} node`;\n  }\n\n  return formatted;\n}\n"],
+  "mappings": "AASM,SAAU,mBAAmB,MAAY;AAC7C,SAAO,KACJ,MAAM,WAAW,EACjB,KAAK,GAAG,EACR,QAAQ,MAAM,CAAC,MAAM,EAAE,YAAW,CAAE;AACzC;AAQM,SAAU,0BAA0B,MAAY;AACpD,QAAM,aAAa,CAAC,cAAc,QAAQ,QAAQ,MAAM,GAClD,YAAY,mBAAmB,IAAI;AAEzC,SAAI,WAAW,SAAS,UAAU,YAAW,CAAE,IAEtC,GAAG,SAAS,UAGd;AACT;",
+  "names": []
+}

package/dist/utils/markdown-table.js

@@ -0,0 +1,17 @@
+function formatMarkdownTable(headers, rows) {
+  const colWidths = headers.map((h, i) => {
+    let width = h.length;
+    for (const row of rows)
+      width = Math.max(width, (row[i] || "").length);
+    return width;
+  }), headerRow = headers.map((h, i) => h.padEnd(colWidths[i])).join(" | "), sepRow = colWidths.map((w) => "-".repeat(w)).join(" | "), dataRows = rows.map((row) => row.map((cell, i) => cell.padEnd(colWidths[i])).join(" | "));
+  return `| ${headerRow} |
+| ${sepRow} |
+${dataRows.map((r) => `| ${r} |`).join(`
+`)}
+`;
+}
+export {
+  formatMarkdownTable
+};
+//# sourceMappingURL=markdown-table.js.map

package/dist/utils/markdown-table.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/markdown-table.ts"],
+  "sourcesContent": ["/**\n * Markdown table formatting utilities\n */\n\n/**\n * Format a markdown table with proper column alignment and padding\n * @param headers Array of header strings\n * @param rows Array of row arrays (each row is an array of cell strings)\n * @returns Formatted markdown table string with pipe delimiters\n */\nexport function formatMarkdownTable(headers: string[], rows: string[][]): string {\n  // Calculate column widths based on content\n  const colWidths = headers.map((h, i) => {\n    let width = h.length;\n    for (const row of rows) {\n      width = Math.max(width, (row[i] || \"\").length);\n    }\n    return width;\n  });\n\n  // Build header row\n  const headerRow = headers\n    .map((h, i) => h.padEnd(colWidths[i]))\n    .join(\" | \");\n\n  // Build separator row\n  const sepRow = colWidths.map((w) => \"-\".repeat(w)).join(\" | \");\n\n  // Build data rows\n  const dataRows = rows.map((row) =>\n    row.map((cell, i) => cell.padEnd(colWidths[i])).join(\" | \")\n  );\n\n  return `| ${headerRow} |\\n| ${sepRow} |\\n${dataRows.map((r) => `| ${r} |`).join(\"\\n\")}\\n`;\n}\n"],
+  "mappings": "AAUM,SAAU,oBAAoB,SAAmB,MAAgB;AAErE,QAAM,YAAY,QAAQ,IAAI,CAAC,GAAG,MAAK;AACrC,QAAI,QAAQ,EAAE;AACd,eAAW,OAAO;AAChB,cAAQ,KAAK,IAAI,QAAQ,IAAI,CAAC,KAAK,IAAI,MAAM;AAE/C,WAAO;EACT,CAAC,GAGK,YAAY,QACf,IAAI,CAAC,GAAG,MAAM,EAAE,OAAO,UAAU,CAAC,CAAC,CAAC,EACpC,KAAK,KAAK,GAGP,SAAS,UAAU,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,EAAE,KAAK,KAAK,GAGvD,WAAW,KAAK,IAAI,CAAC,QACzB,IAAI,IAAI,CAAC,MAAM,MAAM,KAAK,OAAO,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,CAAC;AAG7D,SAAO,KAAK,SAAS;IAAS,MAAM;EAAO,SAAS,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,EAAE,KAAK;CAAI,CAAC;;AACvF;",
+  "names": []
+}

package/dist/utils/mermaid-utils.js

@@ -0,0 +1,11 @@
+function sanitizeMermaidId(text) {
+  return text.replace(/[^a-zA-Z0-9]/g, "_");
+}
+function escapeMermaidLabel(text) {
+  return text.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+export {
+  escapeMermaidLabel,
+  sanitizeMermaidId
+};
+//# sourceMappingURL=mermaid-utils.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/mermaid-utils.ts"],
+  "sourcesContent": ["/**\n * Mermaid diagram utilities\n */\n\n/**\n * Sanitize text for use as a Mermaid diagram node ID\n * Replaces all non-alphanumeric characters with underscores\n * @param text The text to sanitize\n * @returns Sanitized ID safe for use in Mermaid diagrams\n */\nexport function sanitizeMermaidId(text: string): string {\n  return text.replace(/[^a-zA-Z0-9]/g, \"_\");\n}\n\n/**\n * Escape special characters for use in Mermaid diagram labels\n *\n * Mermaid labels use double quotes as delimiters, so we escape:\n * - `\"` \u2192 `\\\"` (double quote: the label delimiter)\n * - `\\` \u2192 `\\\\` (backslash: prevents unintended escape sequences)\n *\n * Note: Unlike markdown, Mermaid renders special chars like |, *, [, ], {, } literally\n * (they don't need escaping), so we don't escape them. Using escapeMarkdown() on Mermaid\n * labels would produce visual artifacts like \\| and \\{ in the diagram.\n *\n * @param text The text to escape for use in a Mermaid label\n * @returns Escaped text safe for use in Mermaid diagram node/edge labels\n */\nexport function escapeMermaidLabel(text: string): string {\n  return text\n    .replace(/\\\\/g, \"\\\\\\\\\")  // Escape backslash first to avoid double-escaping\n    .replace(/\"/g, '\\\\\"');   // Escape double quotes (label delimiter)\n}\n"],
+  "mappings": "AAUM,SAAU,kBAAkB,MAAY;AAC5C,SAAO,KAAK,QAAQ,iBAAiB,GAAG;AAC1C;AAgBM,SAAU,mBAAmB,MAAY;AAC7C,SAAO,KACJ,QAAQ,OAAO,MAAM,EACrB,QAAQ,MAAM,KAAK;AACxB;",
+  "names": []
+}

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,SAAO,MAAM,WAAW,SAAS,IAAI,YAAY;AACnD;AAQA,eAAsB,qBAAqB,WAAkB;AAC3D,QAAM,OAAO,MAAM,gBAAgB,SAAS;AAC5C,MAAI,CAAC;AAAM,WAAO;AAElB,QAAM,WAAW,KAAK,MAAM,gBAAgB;AAC5C,SAAO,MAAM,WAAW,QAAQ,IAAI,WAAW;AACjD;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 } 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;",
   "names": []
 }

package/dist/utils/source-reference.js

@@ -0,0 +1,52 @@
+import { CLIError } from "./errors.js";
+function validateSourceReferenceOptions(options) {
+  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.");
+    return;
+  }
+  if (!options.sourceProvenance)
+    throw new CLIError("--source-provenance 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, [
+      "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'"
+    ]);
+  const validProvenance = ["extracted", "manual", "inferred", "generated"];
+  if (!validProvenance.includes(options.sourceProvenance))
+    throw new CLIError(`Invalid --source-provenance 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, [
+      "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"]);
+  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"]);
+}
+function buildSourceReference(options) {
+  if (!options.sourceProvenance)
+    return;
+  const reference = {
+    provenance: options.sourceProvenance
+  };
+  return options.sourceFile && (reference.locations = [
+    {
+      file: options.sourceFile,
+      ...options.sourceSymbol && { symbol: options.sourceSymbol }
+    }
+  ]), options.sourceRepoRemote && options.sourceRepoCommit && (reference.repository = {
+    url: options.sourceRepoRemote,
+    commit: options.sourceRepoCommit
+  }), reference;
+}
+export {
+  buildSourceReference,
+  validateSourceReferenceOptions
+};
+//# sourceMappingURL=source-reference.js.map

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

@@ -0,0 +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;",
+  "names": []
+}