@documentation-robotics/cli 0.1.0 → 0.1.5

package/dist/core/staged-changeset-storage.js

@@ -0,0 +1,282 @@
+import { readFile, writeFile, readdir, rm } from "fs/promises";
+import { fileExists, ensureDir } from "../utils/file-io.js";
+import { FileLock } from "../utils/file-lock.js";
+import path from "path";
+import yaml from "yaml";
+import ansis from "ansis";
+import { Changeset } from "./changeset.js";
+import { getErrorMessage } from "../utils/errors.js";
+class StagedChangesetStorage {
+  changesetsDir;
+  constructor(rootPath) {
+    this.changesetsDir = path.join(rootPath, "documentation-robotics", "changesets");
+  }
+  /**
+   * Create a new staged changeset directory structure
+   */
+  async create(id, name, description, baseSnapshot) {
+    const now = (/* @__PURE__ */ new Date()).toISOString(), sanitizedId = this.sanitizeId(id), changesetPath = path.join(this.changesetsDir, sanitizedId);
+    await ensureDir(changesetPath);
+    const metadata = {
+      id: sanitizedId,
+      name,
+      description,
+      created: now,
+      modified: now,
+      status: "staged",
+      baseSnapshot,
+      stats: {
+        additions: 0,
+        modifications: 0,
+        deletions: 0
+      }
+    };
+    return await writeFile(path.join(changesetPath, "metadata.yaml"), yaml.stringify(metadata), "utf-8"), await writeFile(path.join(changesetPath, "changes.yaml"), yaml.stringify([]), "utf-8"), new Changeset({
+      id: sanitizedId,
+      name,
+      description,
+      created: now,
+      modified: now,
+      status: "staged",
+      baseSnapshot,
+      changes: [],
+      stats: metadata.stats
+    });
+  }
+  /**
+   * Load a staged changeset from YAML files
+   */
+  async load(id) {
+    const sanitizedId = this.sanitizeId(id), changesetPath = path.join(this.changesetsDir, sanitizedId), metadataPath = path.join(changesetPath, "metadata.yaml"), changesPath = path.join(changesetPath, "changes.yaml");
+    if (!await fileExists(changesetPath))
+      return null;
+    const metadataExists = await fileExists(metadataPath), changesExists = await fileExists(changesPath);
+    if (!metadataExists || !changesExists)
+      throw new Error(`Changeset '${id}' is corrupted (missing ${metadataExists ? "changes.yaml" : "metadata.yaml"}). Location: ${changesetPath}
+This may indicate disk failure or incomplete write. Check disk health and restore from backup if available.`);
+    try {
+      const metadataContent = await readFile(metadataPath, "utf-8"), metadata = yaml.parse(metadataContent), changesContent = await readFile(changesPath, "utf-8"), changes = yaml.parse(changesContent) || [], data = {
+        id: metadata.id,
+        name: metadata.name,
+        description: metadata.description,
+        created: metadata.created,
+        modified: metadata.modified,
+        status: metadata.status,
+        baseSnapshot: metadata.baseSnapshot,
+        changes,
+        stats: metadata.stats || { additions: 0, modifications: 0, deletions: 0 }
+      };
+      return Changeset.fromJSON(data);
+    } catch (error) {
+      throw new Error(`Failed to load changeset '${id}': YAML parsing failed.
+Error: ${getErrorMessage(error)}
+Location: ${metadataPath}
+This indicates file corruption. Try:
+  1. Validate YAML syntax with: yamllint ${metadataPath}
+  2. Restore from backup if available
+  3. Manually edit to fix syntax errors`);
+    }
+  }
+  /**
+   * Save a staged changeset to YAML files
+   */
+  async save(changeset) {
+    if (!changeset.id)
+      throw new Error("Changeset must have an id to be saved in YAML format");
+    const sanitizedId = this.sanitizeId(changeset.id), changesetPath = path.join(this.changesetsDir, sanitizedId);
+    await ensureDir(changesetPath);
+    const metadata = {
+      id: changeset.id,
+      name: changeset.name,
+      description: changeset.description,
+      created: changeset.created,
+      modified: changeset.modified,
+      status: changeset.status,
+      baseSnapshot: changeset.baseSnapshot,
+      stats: changeset.stats || { additions: 0, modifications: 0, deletions: 0 }
+    };
+    await writeFile(path.join(changesetPath, "metadata.yaml"), yaml.stringify(metadata), "utf-8"), await writeFile(path.join(changesetPath, "changes.yaml"), yaml.stringify(changeset.changes), "utf-8");
+  }
+  /**
+   * List all staged changesets
+   */
+  async list() {
+    if (!await fileExists(this.changesetsDir))
+      return [];
+    try {
+      const entries = await readdir(this.changesetsDir, { withFileTypes: !0 }), changesets = [];
+      let skippedCount = 0;
+      for (const entry of entries)
+        if (entry.isDirectory())
+          try {
+            const changeset = await this.load(entry.name);
+            changeset ? changesets.push(changeset) : (console.warn(ansis.yellow(`\u26A0 Warning: Changeset directory '${entry.name}' exists but could not be loaded (may be corrupted)`)), skippedCount++);
+          } catch (loadError) {
+            console.warn(ansis.yellow(`\u26A0 Warning: Failed to load changeset '${entry.name}': ${loadError instanceof Error ? loadError.message : String(loadError)}`)), skippedCount++;
+          }
+      return skippedCount > 0 && console.warn(ansis.yellow(`
+\u26A0 ${skippedCount} changeset(s) could not be loaded and were skipped.`) + ansis.dim(`
+Run 'dr changeset validate' to check for corruption and repair options.`)), changesets;
+    } catch (error) {
+      throw new Error(`Failed to list changesets: ${getErrorMessage(error)}`);
+    }
+  }
+  /**
+   * Delete a staged changeset
+   */
+  async delete(id) {
+    const sanitizedId = this.sanitizeId(id), changesetPath = path.join(this.changesetsDir, sanitizedId);
+    if (!await fileExists(changesetPath)) {
+      const availableIds = (await this.list()).map((cs) => cs.id).join(", ");
+      throw new Error(`Changeset '${id}' not found.
+Available changesets: ${availableIds || "(none)"}
+Run 'dr changeset list' to see all changesets.`);
+    }
+    try {
+      await rm(changesetPath, { recursive: !0, force: !0 });
+    } catch (error) {
+      throw new Error(`Failed to delete changeset '${id}': ${getErrorMessage(error)}`);
+    }
+  }
+  /**
+   * Add or update a change in the changeset's changes.yaml
+   *
+   * Uses file locking to prevent concurrent modification race conditions
+   * Assigns sequence number atomically inside the lock to prevent duplicates
+   *
+   * @returns The assigned sequence number for the change
+   * @throws {Error} If lock acquisition, changeset load, save, or lock release fails
+   */
+  async addChange(id, change) {
+    const changesetPath = this.getChangesetPath(id), lock = new FileLock(changesetPath);
+    try {
+      return await lock.withLock(async () => {
+        const changeset = await this.load(id);
+        if (!changeset)
+          throw new Error(`Changeset '${id}' not found`);
+        const sequenceNumber = changeset.changes.length, stagedChange = {
+          ...change,
+          sequenceNumber
+        };
+        return changeset.changes.push(stagedChange), changeset.updateModified(), await this.save(changeset), sequenceNumber;
+      });
+    } catch (error) {
+      const errorMessage = getErrorMessage(error);
+      if (errorMessage.includes("lock") || errorMessage.includes("timeout")) {
+        const lockFilePath = path.join(changesetPath, ".lock");
+        throw new Error(`Failed to add change to changeset '${id}': Lock acquisition failed.
+Error: ${errorMessage}
+
+This usually means another dr process is modifying this changeset.
+If no other processes are running, a stale lock file may exist.
+
+To resolve:
+  1. Wait for other operations to complete
+  2. Check for running dr processes: ps aux | grep dr
+  3. If no processes found, remove stale lock: rm "${lockFilePath}"
+  4. Retry the operation`);
+      }
+      throw new Error(`Failed to add change to changeset '${id}': ${errorMessage}
+Changeset path: ${changesetPath}`);
+    }
+  }
+  /**
+   * Remove a change by element ID
+   *
+   * Uses file locking to prevent concurrent modification race conditions
+   *
+   * @throws {Error} If lock acquisition, changeset load, save, or lock release fails
+   */
+  async removeChange(id, elementId) {
+    const changesetPath = this.getChangesetPath(id), lock = new FileLock(changesetPath);
+    try {
+      await lock.withLock(async () => {
+        const changeset = await this.load(id);
+        if (!changeset)
+          throw new Error(`Changeset '${id}' not found`);
+        const filtered = changeset.changes.filter((c) => c.elementId !== elementId);
+        changeset.changes = filtered.map((c, idx) => ({
+          ...c,
+          sequenceNumber: idx
+        })), changeset.updateModified(), await this.save(changeset);
+      });
+    } catch (error) {
+      const errorMessage = getErrorMessage(error);
+      if (errorMessage.includes("lock") || errorMessage.includes("timeout")) {
+        const lockFilePath = path.join(changesetPath, ".lock");
+        throw new Error(`Failed to remove change from changeset '${id}': Lock acquisition failed.
+Error: ${errorMessage}
+
+This usually means another dr process is modifying this changeset.
+If no other processes are running, a stale lock file may exist.
+
+To resolve:
+  1. Wait for other operations to complete
+  2. Check for running dr processes: ps aux | grep dr
+  3. If no processes found, remove stale lock: rm "${lockFilePath}"
+  4. Retry the operation`);
+      }
+      throw new Error(`Failed to remove change from changeset '${id}': ${errorMessage}
+Changeset path: ${changesetPath}`);
+    }
+  }
+  /**
+   * Update an existing change in-place within the changeset's changes.yaml
+   *
+   * Atomically replaces the change for the given elementId under a single file lock,
+   * preventing data loss if the process is interrupted between a remove and add.
+   * The original sequence number is preserved so commit-ordering is unaffected.
+   *
+   * @throws {Error} If changeset not found, elementId not found in changes, or I/O error
+   */
+  async updateChange(id, elementId, updated) {
+    const changesetPath = this.getChangesetPath(id), lock = new FileLock(changesetPath);
+    try {
+      await lock.withLock(async () => {
+        const changeset = await this.load(id);
+        if (!changeset)
+          throw new Error(`Changeset '${id}' not found`);
+        const index = changeset.changes.findIndex((c) => c.elementId === elementId);
+        if (index === -1)
+          throw new Error(`No change for element '${elementId}' in changeset '${id}'`);
+        const existing = changeset.changes[index];
+        changeset.changes[index] = {
+          ...existing,
+          ...updated,
+          sequenceNumber: existing.sequenceNumber ?? index
+        }, changeset.updateModified(), await this.save(changeset);
+      });
+    } catch (error) {
+      const errorMessage = getErrorMessage(error);
+      throw new Error(`Failed to update change in changeset '${id}': ${errorMessage}
+Changeset path: ${changesetPath}`);
+    }
+  }
+  /**
+   * Get the storage path for a changeset
+   */
+  getChangesetPath(id) {
+    const sanitizedId = this.sanitizeId(id);
+    return path.join(this.changesetsDir, sanitizedId);
+  }
+  /**
+   * Get the root changesets directory
+   */
+  getChangesetsDir() {
+    return this.changesetsDir;
+  }
+  /**
+   * Sanitize changeset ID for safe use in file paths
+   * Prevents path traversal by removing special characters and path separators
+   */
+  sanitizeId(id) {
+    const sanitized = id.replace(/\.\./g, "").replace(/^\/+/, "").replace(/^[A-Z]:\\/g, "").toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "");
+    if (!sanitized)
+      throw new Error(`Invalid changeset ID '${id}': results in empty string after sanitization. ID must contain at least one alphanumeric character.`);
+    return sanitized;
+  }
+}
+export {
+  StagedChangesetStorage
+};
+//# sourceMappingURL=staged-changeset-storage.js.map

package/dist/core/staged-changeset-storage.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/core/staged-changeset-storage.ts"],
+  "sourcesContent": ["/**\n * StagedChangesetStorage - Handles YAML-based storage for staged changesets\n *\n * Manages the new storage structure:\n * documentation-robotics/changesets/{changeset-id}/\n * \u251C\u2500\u2500 metadata.yaml       # Name, description, dates, status, base snapshot\n * \u2514\u2500\u2500 changes.yaml        # Delta-only change records\n */\n\nimport { readFile, writeFile, readdir, rm } from \"fs/promises\";\nimport { fileExists, ensureDir } from \"../utils/file-io.js\";\nimport { FileLock } from \"../utils/file-lock.js\";\nimport path from \"path\";\nimport yaml from \"yaml\";\nimport ansis from \"ansis\";\nimport type { StagedChangesetData, StagedChange } from \"./changeset.js\";\nimport { Changeset } from \"./changeset.js\";\nimport { getErrorMessage } from \"../utils/errors.js\";\n\n/**\n * Storage manager for staged changesets using YAML format\n */\nexport class StagedChangesetStorage {\n  private changesetsDir: string;\n\n  constructor(rootPath: string) {\n    // Store changesets in documentation-robotics/changesets/ directory\n    this.changesetsDir = path.join(rootPath, \"documentation-robotics\", \"changesets\");\n  }\n\n  /**\n   * Create a new staged changeset directory structure\n   */\n  async create(\n    id: string,\n    name: string,\n    description: string | undefined,\n    baseSnapshot: string\n  ): Promise<Changeset> {\n    const now = new Date().toISOString();\n    const sanitizedId = this.sanitizeId(id);\n    const changesetPath = path.join(this.changesetsDir, sanitizedId);\n\n    // Create directory structure\n    await ensureDir(changesetPath);\n\n    // Create metadata\n    const metadata: Omit<StagedChangesetData, \"changes\"> = {\n      id: sanitizedId,\n      name,\n      description,\n      created: now,\n      modified: now,\n      status: \"staged\",\n      baseSnapshot,\n      stats: {\n        additions: 0,\n        modifications: 0,\n        deletions: 0,\n      },\n    };\n\n    // Write metadata.yaml\n    await writeFile(path.join(changesetPath, \"metadata.yaml\"), yaml.stringify(metadata), \"utf-8\");\n\n    // Write empty changes.yaml\n    await writeFile(path.join(changesetPath, \"changes.yaml\"), yaml.stringify([]), \"utf-8\");\n\n    // Return constructed changeset object\n    return new Changeset({\n      id: sanitizedId,\n      name,\n      description,\n      created: now,\n      modified: now,\n      status: \"staged\",\n      baseSnapshot,\n      changes: [],\n      stats: metadata.stats,\n    });\n  }\n\n  /**\n   * Load a staged changeset from YAML files\n   */\n  async load(id: string): Promise<Changeset | null> {\n    const sanitizedId = this.sanitizeId(id);\n    const changesetPath = path.join(this.changesetsDir, sanitizedId);\n    const metadataPath = path.join(changesetPath, \"metadata.yaml\");\n    const changesPath = path.join(changesetPath, \"changes.yaml\");\n\n    // Check if changeset directory exists\n    if (!(await fileExists(changesetPath))) {\n      return null; // Changeset doesn't exist - this is OK\n    }\n\n    // Changeset directory exists - files SHOULD be present\n    const metadataExists = await fileExists(metadataPath);\n    const changesExists = await fileExists(changesPath);\n\n    if (!metadataExists || !changesExists) {\n      // Changeset directory exists but required files are missing - this is corruption\n      throw new Error(\n        `Changeset '${id}' is corrupted (missing ${!metadataExists ? \"metadata.yaml\" : \"changes.yaml\"}). ` +\n          `Location: ${changesetPath}\\n` +\n          `This may indicate disk failure or incomplete write. Check disk health and restore from backup if available.`\n      );\n    }\n\n    try {\n      // Load metadata\n      const metadataContent = await readFile(metadataPath, \"utf-8\");\n      const metadata = yaml.parse(metadataContent);\n\n      // Load changes\n      const changesContent = await readFile(changesPath, \"utf-8\");\n      const changes = yaml.parse(changesContent) || [];\n\n      // Construct changeset object\n      const data: StagedChangesetData = {\n        id: metadata.id,\n        name: metadata.name,\n        description: metadata.description,\n        created: metadata.created,\n        modified: metadata.modified,\n        status: metadata.status,\n        baseSnapshot: metadata.baseSnapshot,\n        changes: changes as StagedChange[],\n        stats: metadata.stats || { additions: 0, modifications: 0, deletions: 0 },\n      };\n\n      return Changeset.fromJSON(data);\n    } catch (error) {\n      // YAML parsing or file read error - provide detailed guidance\n      throw new Error(\n        `Failed to load changeset '${id}': YAML parsing failed.\\n` +\n          `Error: ${getErrorMessage(error)}\\n` +\n          `Location: ${metadataPath}\\n` +\n          `This indicates file corruption. Try:\\n` +\n          `  1. Validate YAML syntax with: yamllint ${metadataPath}\\n` +\n          `  2. Restore from backup if available\\n` +\n          `  3. Manually edit to fix syntax errors`\n      );\n    }\n  }\n\n  /**\n   * Save a staged changeset to YAML files\n   */\n  async save(changeset: Changeset): Promise<void> {\n    if (!changeset.id) {\n      throw new Error(\"Changeset must have an id to be saved in YAML format\");\n    }\n\n    const sanitizedId = this.sanitizeId(changeset.id);\n    const changesetPath = path.join(this.changesetsDir, sanitizedId);\n    await ensureDir(changesetPath);\n\n    // Prepare metadata (all fields except changes)\n    const metadata = {\n      id: changeset.id,\n      name: changeset.name,\n      description: changeset.description,\n      created: changeset.created,\n      modified: changeset.modified,\n      status: changeset.status,\n      baseSnapshot: changeset.baseSnapshot,\n      stats: changeset.stats || { additions: 0, modifications: 0, deletions: 0 },\n    };\n\n    // Write metadata.yaml\n    await writeFile(path.join(changesetPath, \"metadata.yaml\"), yaml.stringify(metadata), \"utf-8\");\n\n    // Write changes.yaml\n    await writeFile(\n      path.join(changesetPath, \"changes.yaml\"),\n      yaml.stringify(changeset.changes),\n      \"utf-8\"\n    );\n  }\n\n  /**\n   * List all staged changesets\n   */\n  async list(): Promise<Changeset[]> {\n    if (!(await fileExists(this.changesetsDir))) {\n      return [];\n    }\n\n    try {\n      const entries = await readdir(this.changesetsDir, { withFileTypes: true });\n      const changesets: Changeset[] = [];\n      let skippedCount = 0;\n\n      for (const entry of entries) {\n        if (entry.isDirectory()) {\n          try {\n            const changeset = await this.load(entry.name);\n            if (changeset) {\n              changesets.push(changeset);\n            } else {\n              // load() returned null - directory exists but no valid changeset\n              console.warn(\n                ansis.yellow(\n                  `\u26A0 Warning: Changeset directory '${entry.name}' exists but could not be loaded (may be corrupted)`\n                )\n              );\n              skippedCount++;\n            }\n          } catch (loadError) {\n            // load() threw an error - this is a corrupted changeset\n            console.warn(\n              ansis.yellow(\n                `\u26A0 Warning: Failed to load changeset '${entry.name}': ${loadError instanceof Error ? loadError.message : String(loadError)}`\n              )\n            );\n            skippedCount++;\n          }\n        }\n      }\n\n      // Show summary if any were skipped\n      if (skippedCount > 0) {\n        console.warn(\n          ansis.yellow(`\\n\u26A0 ${skippedCount} changeset(s) could not be loaded and were skipped.`) +\n            ansis.dim(`\\nRun 'dr changeset validate' to check for corruption and repair options.`)\n        );\n      }\n\n      return changesets;\n    } catch (error) {\n      throw new Error(\n        `Failed to list changesets: ${getErrorMessage(error)}`\n      );\n    }\n  }\n\n  /**\n   * Delete a staged changeset\n   */\n  async delete(id: string): Promise<void> {\n    const sanitizedId = this.sanitizeId(id);\n    const changesetPath = path.join(this.changesetsDir, sanitizedId);\n\n    if (!(await fileExists(changesetPath))) {\n      // List available changesets to help user\n      const available = await this.list();\n      const availableIds = available.map((cs) => cs.id).join(\", \");\n\n      throw new Error(\n        `Changeset '${id}' not found.\\n` +\n          `Available changesets: ${availableIds || \"(none)\"}\\n` +\n          `Run 'dr changeset list' to see all changesets.`\n      );\n    }\n\n    try {\n      await rm(changesetPath, { recursive: true, force: true });\n    } catch (error) {\n      throw new Error(\n        `Failed to delete changeset '${id}': ${getErrorMessage(error)}`\n      );\n    }\n  }\n\n  /**\n   * Add or update a change in the changeset's changes.yaml\n   *\n   * Uses file locking to prevent concurrent modification race conditions\n   * Assigns sequence number atomically inside the lock to prevent duplicates\n   *\n   * @returns The assigned sequence number for the change\n   * @throws {Error} If lock acquisition, changeset load, save, or lock release fails\n   */\n  async addChange(id: string, change: Omit<StagedChange, \"sequenceNumber\">): Promise<number> {\n    const changesetPath = this.getChangesetPath(id);\n    const lock = new FileLock(changesetPath);\n\n    try {\n      return await lock.withLock(async () => {\n        const changeset = await this.load(id);\n        if (!changeset) {\n          throw new Error(`Changeset '${id}' not found`);\n        }\n\n        // Assign sequence number atomically inside the lock\n        // This prevents race conditions when multiple concurrent operations\n        // try to add changes at the same time\n        const sequenceNumber = changeset.changes.length;\n        const stagedChange: StagedChange = {\n          ...change,\n          sequenceNumber,\n        };\n\n        changeset.changes.push(stagedChange);\n        changeset.updateModified();\n\n        await this.save(changeset);\n\n        return sequenceNumber;\n      });\n    } catch (error) {\n      const errorMessage = getErrorMessage(error);\n\n      // Detect lock-specific errors\n      if (errorMessage.includes(\"lock\") || errorMessage.includes(\"timeout\")) {\n        const lockFilePath = path.join(changesetPath, \".lock\");\n\n        throw new Error(\n          `Failed to add change to changeset '${id}': Lock acquisition failed.\\n` +\n            `Error: ${errorMessage}\\n\\n` +\n            `This usually means another dr process is modifying this changeset.\\n` +\n            `If no other processes are running, a stale lock file may exist.\\n\\n` +\n            `To resolve:\\n` +\n            `  1. Wait for other operations to complete\\n` +\n            `  2. Check for running dr processes: ps aux | grep dr\\n` +\n            `  3. If no processes found, remove stale lock: rm \"${lockFilePath}\"\\n` +\n            `  4. Retry the operation`\n        );\n      }\n\n      // Generic error with context\n      throw new Error(\n        `Failed to add change to changeset '${id}': ${errorMessage}\\n` +\n          `Changeset path: ${changesetPath}`\n      );\n    }\n  }\n\n  /**\n   * Remove a change by element ID\n   *\n   * Uses file locking to prevent concurrent modification race conditions\n   *\n   * @throws {Error} If lock acquisition, changeset load, save, or lock release fails\n   */\n  async removeChange(id: string, elementId: string): Promise<void> {\n    const changesetPath = this.getChangesetPath(id);\n    const lock = new FileLock(changesetPath);\n\n    try {\n      await lock.withLock(async () => {\n        const changeset = await this.load(id);\n        if (!changeset) {\n          throw new Error(`Changeset '${id}' not found`);\n        }\n\n        // Filter out changes for this element\n        const filtered = changeset.changes.filter((c) => c.elementId !== elementId);\n\n        // Reconstruct changes with updated sequence numbers\n        changeset.changes = filtered.map((c, idx) => ({\n          ...c,\n          sequenceNumber: idx,\n        }));\n\n        changeset.updateModified();\n\n        await this.save(changeset);\n      });\n    } catch (error) {\n      const errorMessage = getErrorMessage(error);\n\n      // Detect lock-specific errors\n      if (errorMessage.includes(\"lock\") || errorMessage.includes(\"timeout\")) {\n        const lockFilePath = path.join(changesetPath, \".lock\");\n\n        throw new Error(\n          `Failed to remove change from changeset '${id}': Lock acquisition failed.\\n` +\n            `Error: ${errorMessage}\\n\\n` +\n            `This usually means another dr process is modifying this changeset.\\n` +\n            `If no other processes are running, a stale lock file may exist.\\n\\n` +\n            `To resolve:\\n` +\n            `  1. Wait for other operations to complete\\n` +\n            `  2. Check for running dr processes: ps aux | grep dr\\n` +\n            `  3. If no processes found, remove stale lock: rm \"${lockFilePath}\"\\n` +\n            `  4. Retry the operation`\n        );\n      }\n\n      // Generic error with context\n      throw new Error(\n        `Failed to remove change from changeset '${id}': ${errorMessage}\\n` +\n          `Changeset path: ${changesetPath}`\n      );\n    }\n  }\n\n  /**\n   * Update an existing change in-place within the changeset's changes.yaml\n   *\n   * Atomically replaces the change for the given elementId under a single file lock,\n   * preventing data loss if the process is interrupted between a remove and add.\n   * The original sequence number is preserved so commit-ordering is unaffected.\n   *\n   * @throws {Error} If changeset not found, elementId not found in changes, or I/O error\n   */\n  async updateChange(\n    id: string,\n    elementId: string,\n    updated: Omit<StagedChange, \"sequenceNumber\">\n  ): Promise<void> {\n    const changesetPath = this.getChangesetPath(id);\n    const lock = new FileLock(changesetPath);\n\n    try {\n      await lock.withLock(async () => {\n        const changeset = await this.load(id);\n        if (!changeset) {\n          throw new Error(`Changeset '${id}' not found`);\n        }\n\n        const index = changeset.changes.findIndex((c) => c.elementId === elementId);\n        if (index === -1) {\n          throw new Error(`No change for element '${elementId}' in changeset '${id}'`);\n        }\n\n        // Spread existing entry first so runtime fields like sequenceNumber and timestamp\n        // are preserved. Then apply the updated fields. Since `updated` is\n        // Omit<StagedChange, \"sequenceNumber\">, it will not overwrite sequenceNumber.\n        const existing = changeset.changes[index] as any;\n        changeset.changes[index] = {\n          ...existing,\n          ...updated,\n          sequenceNumber: existing.sequenceNumber ?? index,\n        } as any;\n\n        changeset.updateModified();\n        await this.save(changeset);\n      });\n    } catch (error) {\n      const errorMessage = getErrorMessage(error);\n      throw new Error(\n        `Failed to update change in changeset '${id}': ${errorMessage}\\n` +\n          `Changeset path: ${changesetPath}`\n      );\n    }\n  }\n\n  /**\n   * Get the storage path for a changeset\n   */\n  getChangesetPath(id: string): string {\n    const sanitizedId = this.sanitizeId(id);\n    return path.join(this.changesetsDir, sanitizedId);\n  }\n\n  /**\n   * Get the root changesets directory\n   */\n  getChangesetsDir(): string {\n    return this.changesetsDir;\n  }\n\n  /**\n   * Sanitize changeset ID for safe use in file paths\n   * Prevents path traversal by removing special characters and path separators\n   */\n  private sanitizeId(id: string): string {\n    const sanitized = id\n      .replace(/\\.\\./g, \"\") // Remove .. (parent directory)\n      .replace(/^\\/+/, \"\") // Remove leading slashes\n      .replace(/^[A-Z]:\\\\/g, \"\") // Remove Windows drive letters\n      .toLowerCase()\n      .replace(/\\s+/g, \"-\") // Replace spaces with hyphens\n      .replace(/[^a-z0-9-]/g, \"\"); // Keep only alphanumeric and hyphens\n\n    if (!sanitized) {\n      throw new Error(\n        `Invalid changeset ID '${id}': results in empty string after sanitization. ` +\n          `ID must contain at least one alphanumeric character.`\n      );\n    }\n\n    return sanitized;\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}