@documentation-robotics/cli 0.1.0 → 0.1.5

package/dist/core/staging-area.js

@@ -0,0 +1,1002 @@
+import path from "path";
+import ansis from "ansis";
+import { StagedChangesetStorage } from "./staged-changeset-storage.js";
+import { BaseSnapshotManager } from "./base-snapshot-manager.js";
+import { ChangesetValidator } from "./changeset-validator.js";
+import { fileExists } from "../utils/file-io.js";
+import { createSha256Hash } from "../types/index.js";
+import { getErrorMessage } from "../utils/errors.js";
+import { Layer } from "./layer.js";
+import { isValidLayerName } from "./layers.js";
+import { isTelemetryEnabled, startSpan, startActiveSpan, endSpan, emitLog, SeverityNumber } from "../telemetry/index.js";
+import { ModelReportOrchestrator } from "../reports/model-report-orchestrator.js";
+class StagingAreaManager {
+  storage;
+  snapshotManager;
+  validator;
+  projectionEngine = null;
+  rootPath;
+  model = null;
+  constructor(rootPath, model) {
+    this.rootPath = rootPath, this.model = model || null, this.storage = new StagedChangesetStorage(rootPath), this.snapshotManager = new BaseSnapshotManager(), this.validator = new ChangesetValidator(rootPath), this.projectionEngine = null;
+  }
+  /**
+   * Validate changeset ID format and content
+   * Ensures ID is safe and provides early validation before file operations
+   *
+   * Validation rules:
+   * - Must be a non-empty string
+   * - Cannot contain path separators (.., /, \)
+   * - Cannot contain special characters (<>:"|?*)
+   * - During storage, the ID will be normalized: lowercase, spaces→hyphens, non-alphanumeric→stripped
+   *
+   * @param changesetId - The changeset ID to validate
+   * @throws Error if ID contains invalid characters or structure
+   */
+  validateChangesetId(changesetId) {
+    if (!changesetId || typeof changesetId != "string")
+      throw new Error("Changeset ID must be a non-empty string");
+    if (changesetId.trim() === "")
+      throw new Error("Changeset ID cannot be empty or whitespace-only");
+    if (changesetId.includes("..") || changesetId.includes("/") || changesetId.includes("\\"))
+      throw new Error("Changeset ID cannot contain path separators or traversal sequences (..)");
+    if (/[<>:"|?*]/.test(changesetId))
+      throw new Error('Changeset ID contains invalid special characters (<>:"|?*). Only alphanumeric characters and hyphens are preserved. Spaces are converted to hyphens, and other characters are removed during storage.');
+  }
+  /**
+   * Get or create projection engine instance (lazy initialization).
+   * Deferred initialization avoids circular dependency issues at module load time.
+   * @returns VirtualProjectionEngine instance for computing merged model views
+   */
+  async getProjectionEngine() {
+    if (!this.projectionEngine) {
+      const { VirtualProjectionEngine } = await import("./virtual-projection.js");
+      this.projectionEngine = new VirtualProjectionEngine(this.rootPath);
+    }
+    return this.projectionEngine;
+  }
+  /**
+   * Create a new staged changeset
+   */
+  async create(name, description) {
+    if (!this.model)
+      throw new Error("Model required for creating changesets");
+    const id = this.generateChangesetId(), baseSnapshotId = await this.snapshotManager.captureSnapshot(this.model), changeset = await this.storage.create(id, name, description, baseSnapshotId);
+    return changeset.id = id, changeset.markStaged(), await this.storage.save(changeset), changeset;
+  }
+  /**
+   * Load a changeset by name or ID
+   */
+  async load(name) {
+    let changeset = await this.storage.load(name);
+    return changeset || (await this.storage.list()).find((cs) => cs.name === name) || null;
+  }
+  /**
+   * List all staged changesets
+   */
+  async list() {
+    return this.storage.list();
+  }
+  /**
+   * Delete a changeset
+   * If the changeset being deleted is the currently active changeset,
+   * this method will also clear the active changeset marker.
+   */
+  async delete(name) {
+    const changeset = await this.load(name);
+    if (!changeset)
+      throw new Error(`Changeset '${name}' not found`);
+    if (!changeset.id)
+      throw new Error(`Changeset '${name}' has no ID and cannot be deleted`);
+    const activeChangeset = await this.getActive();
+    activeChangeset && activeChangeset.id === changeset.id && await this.clearActive(), await this.storage.delete(changeset.id);
+  }
+  /**
+   * Stage a change in the changeset.
+   * Records the change in the staging area without applying to the base model.
+   * The changeset must be in 'staged' status to accept new changes.
+   *
+   * @param changesetId - ID of the changeset to stage the change in
+   * @param change - The change to stage (type, elementId, layerName, before/after snapshots)
+   * @throws Error if changeset ID is invalid, changeset not found, or not in 'staged' status
+   */
+  async stage(changesetId, change) {
+    this.validateChangesetId(changesetId);
+    const changeset = await this.load(changesetId);
+    if (!changeset)
+      throw new Error(`Changeset '${changesetId}' not found`);
+    if (changeset.status !== "staged")
+      throw new Error(`Cannot stage changes on changeset with status '${changeset.status}'. Changeset must have status 'staged' to accept new changes.`);
+    const stagedChange = {
+      ...change,
+      timestamp: change.timestamp || (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await this.storage.addChange(changesetId, stagedChange), (await this.getProjectionEngine()).invalidateOnStage(changesetId, change.layerName);
+  }
+  /**
+   * Unstage a specific element from the changeset.
+   * Removes all changes associated with the element.
+   * The changeset must be in 'staged' status.
+   *
+   * @param changesetId - ID of the changeset to unstage from
+   * @param elementId - ID of the element to remove all changes for
+   * @throws Error if changeset ID is invalid, changeset not found, or not in 'staged' status
+   */
+  async unstage(changesetId, elementId) {
+    this.validateChangesetId(changesetId);
+    const changeset = await this.load(changesetId);
+    if (!changeset)
+      throw new Error(`Changeset '${changesetId}' not found`);
+    if (changeset.status !== "staged")
+      throw new Error(`Cannot unstage changes on changeset with status '${changeset.status}'. Changeset must have status 'staged'.`);
+    await this.storage.removeChange(changesetId, elementId), await (await this.getProjectionEngine()).invalidateOnUnstage(changesetId, elementId);
+  }
+  /**
+   * Discard all changes in the changeset.
+   * Clears all staged changes and marks the changeset as 'discarded'.
+   * This operation is irreversible for the changeset but does not affect the base model.
+   *
+   * @param changesetId - ID of the changeset to discard
+   * @throws Error if changeset ID is invalid or changeset not found
+   */
+  async discard(changesetId) {
+    this.validateChangesetId(changesetId);
+    const changeset = await this.load(changesetId);
+    if (!changeset)
+      throw new Error(`Changeset '${changesetId}' not found`);
+    changeset.changes = [], changeset.status = "discarded", changeset.updateModified(), await this.storage.save(changeset), (await this.getProjectionEngine()).invalidateOnDiscard(changesetId);
+  }
+  /**
+   * Capture a base snapshot of the current model state for drift detection.
+   * Stores a hash of the model that can be compared later to detect changes.
+   *
+   * @param changesetId - ID of the changeset to capture snapshot for
+   * @returns SHA256 hash of the current model state
+   * @throws Error if changeset not found or model not available
+   */
+  async captureBaseSnapshot(changesetId) {
+    if (this.validateChangesetId(changesetId), !this.model)
+      throw new Error("Model required for capturing base snapshot");
+    const changeset = await this.load(changesetId);
+    if (!changeset)
+      throw new Error(`Changeset '${changesetId}' not found`);
+    const snapshotId = await this.snapshotManager.captureSnapshot(this.model);
+    return changeset.baseSnapshot = snapshotId, changeset.updateModified(), await this.storage.save(changeset), snapshotId;
+  }
+  /**
+   * Detect drift by comparing base snapshot hash to current model state.
+   * Identifies whether the base model has changed since the changeset was created.
+   *
+   * @param changesetId - ID of the changeset to check for drift
+   * @returns DriftReport with isDrifted flag, snapshot hashes, and warnings
+   * @throws Error if changeset ID is invalid, changeset not found, or model not available
+   *
+   * @remarks
+   * Drift detection uses hash-based comparison of the entire model snapshot.
+   * Element-level change tracking is not implemented - only the isDrifted flag
+   * indicates if the model has changed. Detailed diff detection would require
+   * storing complete snapshot data, not just hashes.
+   * Returns isDrifted=false and warnings if no base snapshot was captured.
+   */
+  async detectDrift(changesetId) {
+    if (this.validateChangesetId(changesetId), !this.model)
+      throw new Error("Model required for drift detection");
+    const changeset = await this.load(changesetId);
+    if (!changeset)
+      throw new Error(`Changeset '${changesetId}' not found`);
+    if (!changeset.baseSnapshot)
+      return {
+        isDrifted: !1,
+        baseSnapshotId: "unknown",
+        currentSnapshotId: "unknown",
+        warnings: ["No base snapshot available for drift detection"]
+      };
+    const currentSnapshotId = await this.snapshotManager.captureSnapshot(this.model), isDrifted = changeset.baseSnapshot !== currentSnapshotId, warnings = [];
+    return isDrifted && warnings.push("Model has drifted since changeset creation (base snapshot hash differs from current)"), {
+      isDrifted,
+      baseSnapshotId: changeset.baseSnapshot,
+      currentSnapshotId,
+      warnings
+    };
+  }
+  /**
+   * Commit a changeset to the base model with atomic guarantee.
+   * Applies all staged changes and persists them to the base model.
+   *
+   * Implements atomic commit with the following steps:
+   * 1. Detect drift in base model (fail unless force=true)
+   * 2. Validate projected model (schema, references, semantics)
+   * 3. Create backup of current model state
+   * 4. Apply all changes in sequence order
+   * 5. Save all modified layers to disk
+   * 6. Update changeset status and manifest history
+   * 7. Cleanup backup on success, restore on failure
+   *
+   * @param model - The model to commit changes to
+   * @param changesetId - ID of the changeset to commit
+   * @param options - Commit options (force, validate, dryRun)
+   * @returns CommitResult with count of committed/failed changes and validation status
+   * @throws Error if validation fails, drift detected without --force, or commit fails
+   *
+   * @remarks
+   * Validation errors always block commit (force flag does not override).
+   * Drift warnings can be bypassed with --force flag.
+   * Dry-run mode performs all checks but does not persist changes.
+   * On commit failure, model state is restored from backup; rollback failure triggers CRITICAL error.
+   */
+  async commit(model, changesetId, options = {}) {
+    return startActiveSpan("staging.commit", async (span) => {
+      this.validateChangesetId(changesetId);
+      const changeset = await this.load(changesetId);
+      if (!changeset)
+        throw new Error(`Changeset '${changesetId}' not found`);
+      span.setAttribute("changeset.name", changeset.name), span.setAttribute("changeset.changeCount", changeset.changes.length);
+      const isDryRun = options.dryRun === !0, shouldValidate = options.validate !== !1, driftSpan = isTelemetryEnabled ? startSpan("staging.detectDrift") : null, drift = await this.detectDrift(changesetId);
+      if (isTelemetryEnabled && driftSpan && (driftSpan.setAttribute("drift.detected", drift.isDrifted), driftSpan.setAttribute("drift.baseSnapshotId", drift.baseSnapshotId), driftSpan.setAttribute("drift.currentSnapshotId", drift.currentSnapshotId), driftSpan.setStatus({ code: 0 })), endSpan(driftSpan), drift.isDrifted)
+        if (span.setAttribute("commit.driftDetected", !0), options.force)
+          emitLog(SeverityNumber.WARN, "Drift detected but overridden with --force", {
+            "drift.baseSnapshot": drift.baseSnapshotId,
+            "drift.currentSnapshot": drift.currentSnapshotId
+          });
+        else
+          throw emitLog(SeverityNumber.ERROR, "Drift detected, commit blocked", {
+            "drift.baseSnapshot": drift.baseSnapshotId,
+            "drift.currentSnapshot": drift.currentSnapshotId
+          }), new Error("Base model has drifted since changeset creation. Use --force to commit anyway.");
+      const result = {
+        changeset: changeset.name,
+        committed: 0,
+        skipped: 0,
+        skippedDetails: [],
+        failed: 0,
+        validation: {
+          passed: !0,
+          errors: []
+        }
+      };
+      if (shouldValidate && await startActiveSpan("staging.validate", async (validationSpan) => {
+        const validation = await this.validator.validateChangeset(model, changesetId);
+        if (validationSpan.setAttribute("validation.passed", validation.isValid()), validationSpan.setAttribute("validation.errorCount", validation.errors.length), validationSpan.setStatus({ code: 0 }), !validation.isValid())
+          throw result.validation.passed = !1, result.validation.errors = validation.errors.map((e) => e.message), emitLog(SeverityNumber.ERROR, "Validation failed", {
+            "validation.errorCount": result.validation.errors.length,
+            "validation.errors": result.validation.errors.slice(0, 10)
+            // First 10 errors
+          }), new Error(`Validation failed with ${result.validation.errors.length} error(s):
+` + result.validation.errors.map((e) => `  - ${e}`).join(`
+`) + `
+
+Fix these validation errors before committing.`);
+      }), isDryRun)
+        return result.committed = changeset.changes.length, drift.isDrifted && (result.driftWarning = drift), result;
+      let backup;
+      try {
+        backup = await this.backupModel(model);
+      } catch (backupError) {
+        throw new Error(`Failed to create backup before commit. No changes have been applied. ${backupError instanceof Error ? backupError.message : String(backupError)}`);
+      }
+      const sortedChanges = [...changeset.changes].sort((a, b) => a.sequenceNumber - b.sequenceNumber);
+      try {
+        const applySpan = isTelemetryEnabled ? startSpan("staging.apply", {
+          "apply.changeCount": changeset.changes.length
+        }) : null;
+        try {
+          for (const change of sortedChanges)
+            try {
+              let layer = await model.getBaseLayer(change.layerName);
+              if (layer || (layer = new Layer(change.layerName), model.addLayer(layer)), change.type === "relationship-add" && change.after) {
+                const rel = change.after;
+                model.relationships.find(rel.source, rel.target, rel.predicate).length === 0 && model.relationships.add({
+                  source: rel.source,
+                  target: rel.target,
+                  predicate: rel.predicate,
+                  layer: rel.layer,
+                  ...rel.targetLayer ? { targetLayer: rel.targetLayer } : {},
+                  category: rel.category ?? "structural",
+                  ...rel.properties ? { properties: rel.properties } : {}
+                }), result.committed++;
+                continue;
+              }
+              if (change.type === "relationship-delete" && change.before) {
+                const rel = change.before;
+                model.relationships.delete(rel.source, rel.target, rel.predicate), result.committed++;
+                continue;
+              }
+              if (change.type === "add" && change.after) {
+                const { Element } = await import("./element.js"), elementData = change.after, elementId = elementData.id;
+                if (layer.listElements().some((e) => e.id === elementId))
+                  result.skipped = (result.skipped ?? 0) + 1, result.skippedDetails = result.skippedDetails ?? [], result.skippedDetails.push(`'${elementId}' in '${change.layerName}' already exists \u2014 deduplicated`), emitLog(SeverityNumber.WARN, "Element deduplicated during commit", {
+                    "change.elementId": change.elementId,
+                    "change.layer": change.layerName
+                  });
+                else {
+                  const element = new Element(elementData);
+                  layer.addElement(element), result.committed++;
+                }
+              } else if (change.type === "update" && change.after) {
+                const element = layer.getElement(change.elementId);
+                if (element) {
+                  const elementData = change.after;
+                  Object.assign(element, elementData), layer.updateElement(element), result.committed++;
+                } else
+                  result.failed++, result.validation.passed = !1, result.validation.errors.push(`Cannot update '${change.elementId}' in '${change.layerName}': element not found in base model`);
+              } else if (change.type === "delete") {
+                const element = layer.getElement(change.elementId);
+                element ? (layer.deleteElement(element.path || element.id), result.committed++) : (result.skipped = (result.skipped ?? 0) + 1, result.skippedDetails = result.skippedDetails ?? [], result.skippedDetails.push(`'${change.elementId}' in '${change.layerName}' not found \u2014 already deleted`));
+              } else
+                result.failed++, result.validation.passed = !1, result.validation.errors.push(`Cannot apply change '${change.type}' for '${change.elementId}': missing payload or unrecognised type`);
+            } catch (error) {
+              throw result.failed++, result.validation.passed = !1, result.validation.errors.push(`Failed to apply change to ${change.elementId}: ${getErrorMessage(error)}`), emitLog(SeverityNumber.ERROR, "Failed to apply change", {
+                "change.elementId": change.elementId,
+                "change.type": change.type,
+                "change.layer": change.layerName,
+                "error.message": getErrorMessage(error)
+              }), new Error(`Atomic commit failed at change ${sortedChanges.indexOf(change) + 1}/${sortedChanges.length}: ${getErrorMessage(error)}`);
+            }
+          isTelemetryEnabled && applySpan && (applySpan.setAttribute("apply.committed", result.committed), applySpan.setAttribute("apply.failed", result.failed), applySpan.setStatus({ code: 0 }));
+        } finally {
+          endSpan(applySpan);
+        }
+        const modifiedLayers = /* @__PURE__ */ new Set();
+        let hasRelationshipChanges = !1;
+        for (const change of sortedChanges)
+          change.type === "relationship-add" || change.type === "relationship-delete" ? hasRelationshipChanges = !0 : modifiedLayers.add(change.layerName);
+        for (const layerName of modifiedLayers)
+          try {
+            await model.saveLayer(layerName);
+          } catch (error) {
+            throw new Error(`Failed to save layer '${layerName}': ${getErrorMessage(error)}`);
+          }
+        if (hasRelationshipChanges)
+          try {
+            await model.saveRelationships();
+          } catch (error) {
+            throw new Error(`Failed to save relationships after commit: ${getErrorMessage(error)}`);
+          }
+        changeset.status = "committed", changeset.updateModified();
+        try {
+          await this.storage.save(changeset);
+        } catch (error) {
+          throw new Error(`Failed to save changeset status after commit: ${getErrorMessage(error)}. This is a critical error that requires rollback to maintain consistency between model state and changeset metadata.`);
+        }
+        model.manifest.changeset_history || (model.manifest.changeset_history = []), model.manifest.changeset_history.push({
+          name: changeset.name,
+          committed_at: (/* @__PURE__ */ new Date()).toISOString(),
+          action: "committed"
+        });
+        try {
+          await model.saveManifest();
+        } catch (manifestError) {
+          throw new Error(`Failed to save manifest with changeset history: ${manifestError instanceof Error ? manifestError.message : String(manifestError)}. Model will be rolled back to maintain consistency.`);
+        }
+        try {
+          const orchestrator = new ModelReportOrchestrator(model, model.rootPath), affectedLayers = /* @__PURE__ */ new Set();
+          for (const change of sortedChanges)
+            if (isValidLayerName(change.layerName))
+              for (const layer of orchestrator.computeAffectedLayers(change.layerName))
+                affectedLayers.add(layer);
+          await orchestrator.regenerate(affectedLayers);
+        } catch (error) {
+          emitLog(SeverityNumber.WARN, "Failed to regenerate layer reports after changeset commit", {
+            "changeset.id": changesetId,
+            "changeset.name": changeset.name,
+            "changeset.changeCount": sortedChanges.length,
+            "error.message": getErrorMessage(error)
+          });
+        }
+        return await this.cleanupBackup(backup), span.setAttribute("commit.success", !0), span.setAttribute("commit.committed", result.committed), drift.isDrifted && span.setAttribute("commit.driftOverridden", !0), span.setStatus({ code: 0 }), result;
+      } catch (commitError) {
+        let rollbackSucceeded = !1, rollbackError = null;
+        const rollbackSpan = isTelemetryEnabled ? startSpan("staging.rollback") : null;
+        try {
+          emitLog(SeverityNumber.WARN, "Commit failed, attempting rollback", {
+            "commit.error": commitError instanceof Error ? commitError.message : String(commitError)
+          }), await this.restoreModel(model, backup), rollbackSucceeded = !0, isTelemetryEnabled && rollbackSpan && (rollbackSpan.setAttribute("rollback.success", !0), rollbackSpan.setStatus({ code: 0 })), emitLog(SeverityNumber.INFO, "Rollback succeeded, model restored", {
+            "backup.path": backup
+          });
+        } catch (err) {
+          rollbackError = err instanceof Error ? err : new Error(String(err)), isTelemetryEnabled && rollbackSpan && (rollbackSpan.setAttribute("rollback.success", !1), rollbackSpan.recordException(rollbackError), rollbackSpan.setStatus({ code: 2, message: rollbackError.message })), emitLog(SeverityNumber.ERROR, "Rollback failed, model may be corrupted", {
+            "rollback.error": rollbackError.message,
+            "backup.path": backup
+          });
+        } finally {
+          endSpan(rollbackSpan);
+        }
+        let backupHealth, backupValidationError = null, validationProcessFailed = !1;
+        try {
+          backupHealth = await this.validateBackupIntegrity(backup);
+        } catch (validationErr) {
+          validationProcessFailed = !0, backupValidationError = validationErr instanceof Error ? validationErr.message : String(validationErr), backupHealth = {
+            isValid: !1,
+            filesChecked: 0,
+            errors: [
+              `Validation process failed: ${backupValidationError}`,
+              "This indicates a critical issue with the backup infrastructure, not the backup content.",
+              "Contact support before attempting manual restoration."
+            ]
+          };
+        }
+        let compositeMessage;
+        const suggestions = [];
+        if (rollbackSucceeded)
+          throw compositeMessage = `Commit failed but rollback succeeded. Model restored to pre-commit state.
+
+`, compositeMessage += `Error during commit:
+`, compositeMessage += `  ${commitError instanceof Error ? commitError.message : String(commitError)}
+
+`, compositeMessage += `Backup location (for reference): ${backup}`, await this.cleanupBackup(backup), span.setAttribute("commit.success", !1), span.setAttribute("commit.rollbackSuccess", !0), span.recordException(commitError), span.setStatus({
+            code: 2,
+            message: commitError instanceof Error ? commitError.message : String(commitError)
+          }), new Error(compositeMessage);
+        {
+          if (compositeMessage = `Commit failed AND rollback failed. Model may be in corrupted state.
+
+Original commit error:
+  ${commitError instanceof Error ? commitError.message : String(commitError)}
+
+Rollback error:
+  ${rollbackError ? rollbackError.message : "Unknown error"}
+
+Backup location: ${backup}
+`, compositeMessage += `Backup integrity check:
+`, validationProcessFailed)
+            compositeMessage += `  \u2717 Backup integrity issues found:
+`, compositeMessage += `    - Validation process failed: ${backupValidationError}
+`, compositeMessage += `
+\u26A0 CRITICAL: Backup validation process crashed.
+`, compositeMessage += `This indicates a system-level issue (filesystem, memory, permissions).
+`, compositeMessage += `DO NOT attempt manual restoration until this is resolved.
+`;
+          else if (backupHealth.isValid)
+            compositeMessage += `  \u2713 Backup is valid (${backupHealth.filesChecked} files checked)
+`;
+          else {
+            compositeMessage += `  \u2717 Backup integrity issues found:
+`;
+            for (const error of backupHealth.errors)
+              compositeMessage += `    - ${error}
+`;
+          }
+          compositeMessage += `
+`, backupHealth.isValid ? suggestions.push(`Backup is valid. Manually restore from backup: ${backup}`, `Copy manifest.json/manifest.yaml from backup to ${path.join(model.rootPath, "documentation-robotics")}`, `Copy layer files from ${path.join(backup, "layers")} to ${path.join(model.rootPath, "documentation-robotics", "layers")}`, "Run 'dr validate' after manual restoration", "Contact support if issue persists") : suggestions.push("\u26A0 Backup integrity is compromised. Do NOT use this backup for recovery.", `Check if backup files exist at: ${backup}`, "Verify disk space and file permissions", "Contact support immediately - manual data recovery may be required", "Do not attempt manual restoration with a corrupted backup"), compositeMessage += "Manual recovery may be required.", span.setAttribute("commit.success", !1), span.setAttribute("commit.rollbackSuccess", !1), span.recordException(commitError), span.setStatus({ code: 2, message: "Commit and rollback both failed" });
+          const { CLIError } = await import("../utils/errors.js");
+          throw new CLIError(compositeMessage, 1, suggestions);
+        }
+      }
+    }, {
+      "changeset.id": changesetId,
+      "commit.validate": options.validate !== !1,
+      "commit.force": options.force === !0,
+      "commit.dryRun": options.dryRun === !0
+    });
+  }
+  /**
+   * Check if a changeset is currently active.
+   * Active changesets intercept mutations to stage changes instead of applying to base model.
+   *
+   * @param changesetId - ID of the changeset to check
+   * @returns true if changeset is marked as active, false otherwise
+   * @throws Error if changeset ID is invalid
+   */
+  async isActive(changesetId) {
+    this.validateChangesetId(changesetId);
+    const activePath = path.join(this.rootPath, "documentation-robotics", "changesets", ".active");
+    if (!await fileExists(activePath))
+      return !1;
+    const { readFile } = await import("../utils/file-io.js");
+    return (await readFile(activePath)).trim() === changesetId;
+  }
+  /**
+   * Activate a changeset to intercept model mutations.
+   * Marks the changeset as active and transitions status to 'staged'.
+   * Only one changeset can be active at a time.
+   *
+   * @param changesetId - ID of the changeset to activate
+   * @throws Error if changeset ID is invalid or changeset not found
+   *
+   * @remarks
+   * When a changeset is active, add/update/delete commands will stage changes
+   * instead of applying them directly to the base model.
+   */
+  async setActive(changesetId) {
+    this.validateChangesetId(changesetId);
+    const changeset = await this.load(changesetId);
+    if (!changeset)
+      throw new Error(`Changeset '${changesetId}' not found`);
+    changeset.status !== "staged" && (changeset.markStaged(), await this.storage.save(changeset));
+    const { writeFile, ensureDir } = await import("../utils/file-io.js"), changesetDir = path.join(this.rootPath, "documentation-robotics", "changesets");
+    await ensureDir(changesetDir);
+    const activePath = path.join(changesetDir, ".active");
+    if (!changeset.id)
+      throw new Error("Changeset has no ID, cannot activate");
+    await writeFile(activePath, changeset.id);
+  }
+  /**
+   * Clear the active changeset marker.
+   * Allows a new changeset to be activated or model mutations to proceed normally.
+   */
+  async clearActive() {
+    const { writeFile } = await import("../utils/file-io.js"), activePath = path.join(this.rootPath, "documentation-robotics", "changesets", ".active");
+    await fileExists(activePath) && await writeFile(activePath, "");
+  }
+  /**
+   * Get the currently active changeset.
+   * Returns null if no changeset is active.
+   *
+   * @returns The active changeset or null if none is active
+   */
+  async getActive() {
+    const activePath = path.join(this.rootPath, "documentation-robotics", "changesets", ".active");
+    if (!await fileExists(activePath))
+      return null;
+    const { readFile } = await import("../utils/file-io.js"), id = (await readFile(activePath)).trim();
+    return id ? this.storage.load(id) : null;
+  }
+  /**
+   * Get the ID of the active changeset without loading the full changeset object.
+   * Useful for status display and quick active changeset checks.
+   *
+   * @returns The active changeset ID or null if no active changeset exists
+   */
+  async getActiveId() {
+    const activePath = path.join(this.rootPath, "documentation-robotics", "changesets", ".active");
+    if (!await fileExists(activePath))
+      return null;
+    const { readFile } = await import("../utils/file-io.js");
+    return (await readFile(activePath)).trim() || null;
+  }
+  /**
+   * Apply a changeset to the base model.
+   * Alias for commit() to match legacy command terminology.
+   *
+   * @param model - The model to apply changes to
+   * @param changesetId - ID of the changeset to apply
+   * @param options - Commit options (force, validate, dryRun)
+   * @returns CommitResult with count of applied changes and validation status
+   * @throws Error if validation fails, drift detected without --force, or apply fails
+   *
+   * @remarks
+   * This method provides backward compatibility with changeset commands that use
+   * "apply" instead of "commit" terminology. All logic is delegated to commit().
+   */
+  async apply(model, changesetId, options = {}) {
+    return this.commit(model, changesetId, options);
+  }
+  /**
+   * Revert a changeset without applying changes.
+   * Alias for discard() to match legacy command terminology.
+   *
+   * @param changesetId - ID of the changeset to revert
+   * @throws Error if changeset ID is invalid or changeset not found
+   *
+   * @remarks
+   * This method provides backward compatibility with changeset commands that use
+   * "revert" instead of "discard" terminology. All logic is delegated to discard().
+   */
+  async revert(changesetId) {
+    return this.discard(changesetId);
+  }
+  /**
+   * Backup the current model state for atomic rollback on commit failure.
+   * Creates a temporary backup directory with copies of all layer files and manifest.
+   * Validates backup completeness and calculates checksums for integrity verification.
+   *
+   * @param model - The model to backup
+   * @returns Path to the backup directory
+   * @throws Error if backup creation or validation fails
+   *
+   * @remarks
+   * Backup includes:
+   * - manifest.yaml or manifest.json
+   * - All layer YAML files
+   * - Backup manifest with checksums and metadata
+   * Backup is removed after successful commit; retained if commit fails for recovery.
+   */
+  async backupModel(model) {
+    const backupDir = path.join(this.rootPath, "documentation-robotics", ".backups", `backup-${Date.now()}`), { ensureDir, readFile, atomicWrite } = await import("../utils/file-io.js"), { createHash } = await import("crypto");
+    await ensureDir(backupDir);
+    const backupFiles = [], timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    try {
+      let manifestPath = path.join(model.rootPath, "documentation-robotics", "model", "manifest.yaml");
+      if (await fileExists(manifestPath) || (manifestPath = path.join(model.rootPath, "documentation-robotics", "manifest.json")), !await fileExists(manifestPath))
+        throw new Error("Manifest file not found in expected locations");
+      const manifestContent = await readFile(manifestPath), manifestChecksum = createSha256Hash(createHash("sha256").update(manifestContent).digest("hex")), manifestFilename = path.basename(manifestPath);
+      await atomicWrite(path.join(backupDir, manifestFilename), manifestContent), backupFiles.push({
+        path: manifestFilename,
+        checksum: manifestChecksum,
+        size: manifestContent.length
+      });
+      const layersDir = path.join(backupDir, "layers");
+      await ensureDir(layersDir);
+      const fs = await import("fs/promises");
+      for (const layer of model.layers.values()) {
+        const layerBackupDir = path.join(layersDir, layer.name);
+        await ensureDir(layerBackupDir);
+        const layerDirPath = await this.findLayerDirectory(model.rootPath, layer.name);
+        if (!layerDirPath)
+          continue;
+        const files = await fs.readdir(layerDirPath);
+        for (const file of files)
+          if (file.endsWith(".yaml") || file.endsWith(".yml")) {
+            const filePath = path.join(layerDirPath, file), fileContent = await readFile(filePath), fileChecksum = createSha256Hash(createHash("sha256").update(fileContent).digest("hex"));
+            await atomicWrite(path.join(layerBackupDir, file), fileContent), backupFiles.push({
+              path: `layers/${layer.name}/${file}`,
+              checksum: fileChecksum,
+              size: fileContent.length
+            });
+          }
+      }
+      const backupManifest = {
+        files: backupFiles,
+        timestamp
+      };
+      return await atomicWrite(path.join(backupDir, ".backup-manifest.json"), JSON.stringify(backupManifest, null, 2)), await this.validateBackup(backupDir, backupManifest), backupDir;
+    } catch (error) {
+      const cleanupError = await this.forceRemoveBackupDir(backupDir);
+      throw cleanupError ? new Error(`Backup creation failed AND cleanup failed.
+Original error: ${getErrorMessage(error)}
+Cleanup error: ${cleanupError}
+
+Orphaned backup directory: ${backupDir}
+This directory will accumulate and consume disk space.
+
+REQUIRED ACTIONS:
+  1. Manually remove: rm -rf "${backupDir}"
+  2. Check disk space: df -h
+  3. Check permissions: ls -la "${path.dirname(backupDir)}"
+
+Cannot proceed with commit until this is resolved.`) : new Error(`Failed to create backup: ${getErrorMessage(error)}`);
+    }
+  }
+  /**
+   * Validate backup completeness and file integrity.
+   * Verifies that all files in the manifest exist in the backup directory
+   * with matching checksums and sizes.
+   *
+   * @param backupDir - Path to the backup directory
+   * @param manifest - Backup manifest with file list and checksums
+   * @throws Error if any file is missing, checksum mismatches, or size differs
+   */
+  async validateBackup(backupDir, manifest) {
+    const { readFile, fileExists: fileExists2 } = await import("../utils/file-io.js"), { createHash } = await import("crypto");
+    for (const file of manifest.files) {
+      const backupFilePath = path.join(backupDir, file.path);
+      if (!await fileExists2(backupFilePath))
+        throw new Error(`Backup validation failed: ${file.path} not found in backup`);
+      const content = await readFile(backupFilePath), checksum = createHash("sha256").update(content).digest("hex");
+      if (checksum !== file.checksum)
+        throw new Error(`Backup validation failed: ${file.path} checksum mismatch (expected ${file.checksum}, got ${checksum})`);
+      if (content.length !== file.size)
+        throw new Error(`Backup validation failed: ${file.path} size mismatch (expected ${file.size}, got ${content.length})`);
+    }
+  }
+  /**
+   * Validate backup integrity by checking manifest and file checksums.
+   * This is called before suggesting manual restoration to ensure the backup is usable.
+   * @param backupDir - Path to the backup directory
+   * @returns Promise resolving to backup health status or throwing error with details
+   * @throws Error with details about any integrity issues found
+   */
+  async validateBackupIntegrity(backupDir) {
+    const { readFile, fileExists: fileExists2 } = await import("../utils/file-io.js"), { createHash } = await import("crypto"), errors = [];
+    let filesChecked = 0;
+    try {
+      if (!await fileExists2(backupDir))
+        throw new Error(`Backup directory not found: ${backupDir}`);
+      const manifestPath = path.join(backupDir, ".backup-manifest.json");
+      if (!await fileExists2(manifestPath))
+        throw new Error(`Backup manifest not found at ${manifestPath}`);
+      let rawManifest;
+      try {
+        const manifestContent = await readFile(manifestPath);
+        if (!manifestContent || manifestContent.length === 0)
+          throw new Error("Backup manifest is empty");
+        rawManifest = JSON.parse(manifestContent.toString());
+      } catch (err) {
+        throw new Error(`Failed to read backup manifest: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      if (!rawManifest || typeof rawManifest != "object")
+        throw new Error("Backup manifest must be an object");
+      if (!rawManifest.files || !Array.isArray(rawManifest.files))
+        throw new Error("Backup manifest must have a files array");
+      for (let index = 0; index < rawManifest.files.length; index++) {
+        const file = rawManifest.files[index];
+        if (filesChecked++, !file || typeof file != "object") {
+          errors.push(`Backup manifest file entry ${index} must be an object`);
+          continue;
+        }
+        if (typeof file.path != "string" || !file.path) {
+          errors.push(`Backup manifest file entry ${index} must have a non-empty path string`);
+          continue;
+        }
+        if (typeof file.checksum != "string") {
+          errors.push(`Backup manifest file entry ${index} must have a checksum string`);
+          continue;
+        }
+        if (typeof file.size != "number" || file.size < 0) {
+          errors.push(`Backup manifest file entry ${index} must have a non-negative size number`);
+          continue;
+        }
+        const backupFilePath = path.join(backupDir, file.path);
+        if (!await fileExists2(backupFilePath)) {
+          errors.push(`Missing: ${file.path}`);
+          continue;
+        }
+        try {
+          const content = await readFile(backupFilePath), checksum = createHash("sha256").update(content).digest("hex");
+          if (checksum !== file.checksum) {
+            errors.push(`Checksum mismatch: ${file.path} (expected ${file.checksum}, got ${checksum})`);
+            continue;
+          }
+          content.length !== file.size && errors.push(`Size mismatch: ${file.path} (expected ${file.size}, got ${content.length})`);
+        } catch (err) {
+          errors.push(`Failed to validate: ${file.path} (${err instanceof Error ? err.message : String(err)})`);
+        }
+      }
+      return {
+        isValid: errors.length === 0,
+        filesChecked,
+        errors
+      };
+    } catch (err) {
+      throw new Error(`Backup integrity check failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  /**
+   * Clean up a backup directory after successful commit.
+   * Removes the backup directory and all its contents to prevent disk space accumulation.
+   *
+   * @param backupDir - Path to the backup directory to remove
+   *
+   * @remarks
+   * Failures during cleanup are logged with ERROR severity but do not throw.
+   * Successful commits should not fail due to cleanup errors, but users need to
+   * know about cleanup failures to avoid disk space accumulation.
+   * Includes actionable guidance for common failure scenarios.
+   */
+  async cleanupBackup(backupDir) {
+    try {
+      const { rm } = await import("node:fs/promises");
+      await rm(backupDir, { recursive: !0, force: !0 });
+    } catch (error) {
+      const errorMsg = getErrorMessage(error), errorCode = error?.code;
+      let suggestions = "";
+      if (errorCode === "ENOENT")
+        return;
+      if (errorCode === "ENOSPC")
+        throw new Error(`Backup cleanup failed due to disk full.
+Original error: ${errorMsg}
+
+Orphaned backup directory: ${backupDir}
+This directory will accumulate and consume disk space.
+
+REQUIRED ACTIONS:
+  1. Manually remove: rm -rf "${backupDir}"
+  2. Free up disk space: df -h
+  3. Check disk usage: du -sh ${path.dirname(backupDir)}/*
+
+Cannot proceed with future commits until disk space is freed.`);
+      errorCode === "EACCES" ? suggestions = `
+
+[PERMISSION ERROR] Cannot delete backup directory.
+Directory: ${backupDir}
+Check file permissions or try manual cleanup:
+sudo rm -rf "${backupDir}"` : suggestions = `
+
+[ACTION REQUIRED] Backup cleanup failed due to file system error.
+Directory: ${backupDir}
+Manual cleanup: rm -rf "${backupDir}"
+Note: Backup directories accumulate over time and can fill disk space.`, console.error(`[ERROR] Failed to clean up backup directory after commit: ${errorMsg}` + suggestions);
+    }
+  }
+  /**
+   * Force remove a backup directory with enhanced error handling.
+   * Attempts multiple strategies to ensure removal even with permission issues.
+   *
+   * @param backupDir - Path to the backup directory to remove
+   * @returns Error message if removal failed, null if successful
+   *
+   * @remarks
+   * This is used during backup creation failures to ensure cleanup of partial state.
+   * Returns error details instead of throwing so caller can log and continue.
+   */
+  async forceRemoveBackupDir(backupDir) {
+    const fs = await import("fs/promises");
+    try {
+      return await fs.rm(backupDir, { recursive: !0, force: !0 }), null;
+    } catch {
+      try {
+        const removalFailures = [], entries = await fs.readdir(backupDir, { withFileTypes: !0 });
+        for (const entry of entries) {
+          const fullPath = path.join(backupDir, entry.name);
+          try {
+            entry.isDirectory() ? await fs.rm(fullPath, { recursive: !0, force: !0 }) : await fs.unlink(fullPath);
+          } catch (itemError) {
+            removalFailures.push({
+              path: fullPath,
+              error: itemError instanceof Error ? itemError.message : String(itemError)
+            });
+          }
+        }
+        try {
+          return await fs.rmdir(backupDir), null;
+        } catch {
+          if (removalFailures.length > 0) {
+            const failureDetails = removalFailures.map((f) => `  - ${f.path}: ${f.error}`).join(`
+`);
+            return `Could not remove ${removalFailures.length} items from backup directory:
+` + failureDetails + `
+
+Manual cleanup required: rm -rf "${backupDir}"`;
+          }
+          return `Could not remove directory ${backupDir} - may contain leftover files`;
+        }
+      } catch (aggressiveError) {
+        return `Backup cleanup failed: ${aggressiveError instanceof Error ? aggressiveError.message : String(aggressiveError)}`;
+      }
+    }
+  }
+  /**
+   * Restore model state from backup after failed commit.
+   * Restores manifest first (critical), then all layer files with defensive error handling.
+   * Provides detailed reporting of restoration progress and failures.
+   *
+   * @param model - The model to restore
+   * @param backupDir - Path to the backup directory
+   * @throws Error with detailed restoration summary if restoration fails
+   *
+   * @remarks
+   * Restoration strategy:
+   * 1. Restore manifest first (critical for model integrity)
+   * 2. Restore all layer files with per-file error handling
+   * 3. Continue restoring remaining files even if some fail
+   * 4. Throw detailed error if critical files fail to restore
+   * Both manifest and layer restoration failures are critical and will throw errors.
+   */
+  async restoreModel(model, backupDir) {
+    const { readFile, fileExists: fileExists2, atomicWrite } = await import("../utils/file-io.js"), restoredFiles = [], failedFiles = [], criticalLayers = /* @__PURE__ */ new Set();
+    try {
+      let backupManifestFile = path.join(backupDir, "manifest.yaml"), manifestDestPath = path.join(model.rootPath, "documentation-robotics", "model", "manifest.yaml");
+      await fileExists2(backupManifestFile) || (backupManifestFile = path.join(backupDir, "manifest.json"), manifestDestPath = path.join(model.rootPath, "documentation-robotics", "manifest.json"));
+      try {
+        if (!await fileExists2(backupManifestFile))
+          throw new Error("Backup manifest file not found (tried .yaml and .json)");
+        const manifestContent = await readFile(backupManifestFile);
+        await atomicWrite(manifestDestPath, manifestContent), restoredFiles.push(path.basename(backupManifestFile));
+      } catch (error) {
+        throw failedFiles.push({
+          path: path.basename(backupManifestFile),
+          error: getErrorMessage(error),
+          isCritical: !0
+        }), new Error(`Failed to restore ${path.basename(backupManifestFile)}: ${getErrorMessage(error)}`);
+      }
+      const backupLayersDir = path.join(backupDir, "layers"), fs = await import("fs/promises");
+      for (const layer of model.layers.values()) {
+        const backupLayerDir = path.join(backupLayersDir, layer.name);
+        try {
+          if (!await fileExists2(backupLayerDir)) {
+            const errorMsg = `Layer '${layer.name}' not found in backup (backup incomplete or corrupted)`;
+            failedFiles.push({
+              path: `layers/${layer.name}`,
+              error: errorMsg,
+              isCritical: !0
+            }), criticalLayers.add(layer.name);
+            continue;
+          }
+          const layerDirPath = await this.findLayerDirectory(model.rootPath, layer.name);
+          if (!layerDirPath) {
+            const errorMsg = `Destination directory not found for layer '${layer.name}' (permissions issue or directory structure changed)`;
+            failedFiles.push({
+              path: `layers/${layer.name}`,
+              error: errorMsg,
+              isCritical: !0
+            }), criticalLayers.add(layer.name);
+            continue;
+          }
+          const backupFiles = await fs.readdir(backupLayerDir);
+          let filesRestoredInLayer = 0;
+          for (const file of backupFiles)
+            if (file.endsWith(".yaml") || file.endsWith(".yml")) {
+              const backupFilePath = path.join(backupLayerDir, file), destFilePath = path.join(layerDirPath, file);
+              try {
+                const fileContent = await readFile(backupFilePath);
+                await atomicWrite(destFilePath, fileContent), restoredFiles.push(`layers/${layer.name}/${file}`), filesRestoredInLayer++;
+              } catch (fileError) {
+                const errorMsg = fileError instanceof Error ? fileError.message : String(fileError);
+                console.error(ansis.red(`\u2717 Failed to restore ${layer.name}/${file}: ${errorMsg}`)), failedFiles.push({
+                  path: `layers/${layer.name}/${file}`,
+                  error: errorMsg,
+                  isCritical: !0
+                }), criticalLayers.add(layer.name);
+              }
+            }
+        } catch (error) {
+          const errorMessage = getErrorMessage(error);
+          failedFiles.push({
+            path: `layers/${layer.name}`,
+            error: errorMessage,
+            isCritical: !0
+          }), criticalLayers.add(layer.name);
+        }
+      }
+      if (model.layers.clear(), criticalLayers.size > 0) {
+        const failedLayersList = Array.from(criticalLayers).join(", "), detailedErrors = failedFiles.map((f) => `  - ${f.path}: ${f.error}`).join(`
+`), errorSummary = `Model restoration FAILED - ${failedFiles.length} critical layer(s) could not be restored:
+  Failed layers: ${failedLayersList}
+
+Detailed errors:
+${detailedErrors}
+
+Successfully restored: ${restoredFiles.length} files
+Failed to restore: ${failedFiles.length} files
+
+Possible causes:
+  1. Backup directory corrupted or incomplete
+  2. Insufficient permissions to write to model directory
+  3. Disk full during restoration
+  4. Layer directory structure changed since backup
+
+Backup location: ${backupDir}
+
+ACTION REQUIRED: Manually restore from backup or contact support.`;
+        throw new Error(errorSummary);
+      }
+    } catch (error) {
+      const summary = `Model restoration failed: ${getErrorMessage(error)}
+
+Restoration progress:
+  Successfully restored: ${restoredFiles.length} files
+  Failed to restore: ${failedFiles.length} files (all critical)
+
+Restored files:
+${restoredFiles.map((f) => `  \u2713 ${f}`).join(`
+`)}
+
+Failed files:
+${failedFiles.map((f) => `  ${f.isCritical ? "\u2717 [CRITICAL]" : "\u26A0 [WARNING]"} ${f.path}: ${f.error}`).join(`
+`)}
+
+Backup location: ${backupDir}`;
+      throw new Error(summary);
+    }
+  }
+  /**
+   * Find the directory path for a layer in the model.
+   * Uses same discovery logic as Model.loadLayer to locate layer directories.
+   * Handles naming convention: `{PREFIX}_{layerName}` where PREFIX is numeric (01_motivation, etc).
+   *
+   * @param rootPath - Root path of the model
+   * @param layerName - Name of the layer to find
+   * @returns Path to the layer directory or null if not found
+   */
+  async findLayerDirectory(rootPath, layerName) {
+    const fs = await import("fs/promises"), modelDir = path.join(rootPath, "documentation-robotics", "model");
+    try {
+      const layerDir = (await fs.readdir(modelDir, { withFileTypes: !0 })).find((e) => e.isDirectory() && e.name.match(/^\d{2}_/) && e.name.replace(/^\d{2}_/, "") === layerName);
+      return layerDir ? path.join(modelDir, layerDir.name) : null;
+    } catch (error) {
+      const errorCode = error?.code;
+      if (errorCode === "ENOENT")
+        return null;
+      throw new Error(`Cannot access model directory for layer '${layerName}': ${getErrorMessage(error)}
+Location: ${modelDir}
+Error code: ${errorCode}
+This indicates a filesystem or permissions issue. Check:
+  1. Directory permissions: ls -la ${path.dirname(modelDir)}
+  2. Disk health: df -h
+  3. Filesystem errors: dmesg | tail`);
+    }
+  }
+  /**
+   * Generate a unique changeset ID.
+   * Combines timestamp and random suffix to ensure uniqueness across concurrent operations.
+   *
+   * @returns A unique changeset ID in format `changeset-{timestamp}-{random}`
+   */
+  generateChangesetId() {
+    return `changeset-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+}
+export {
+  StagingAreaManager
+};
+//# sourceMappingURL=staging-area.js.map