clearctx 3.0.0

package/src/snapshot-engine.js

@@ -0,0 +1,490 @@
+/**
+ * Snapshot & Replay Engine - Layer 3 Time-Travel System
+ *
+ * This module provides the ability to capture, rollback, and replay the entire
+ * coordination state of a team. Think of it as "git for your multi-session workflow."
+ *
+ * Features:
+ * - Capture complete snapshots of contracts, artifacts, and pipelines
+ * - Rollback to any previous snapshot
+ * - Replay with modifications (override inputs to test different scenarios)
+ * - Preserve artifact versions on disk (immutability)
+ * - Atomic operations with proper locking
+ *
+ * Use cases:
+ * - Before risky operations: "Save a snapshot, then try the change"
+ * - After major milestones: "Schema design complete, snapshot it"
+ * - Debugging: "Rollback to before the bug, replay with different inputs"
+ * - Testing: "Replay from checkpoint with modified parameters"
+ *
+ * @class SnapshotEngine
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Import Layer 1 utilities for atomic operations and locking
+const { atomicWriteJson, readJsonSafe } = require('./atomic-io');
+const { acquireLock, releaseLock } = require('./file-lock');
+
+/**
+ * SnapshotEngine class - manages snapshots and replay of team state
+ */
+class SnapshotEngine {
+  /**
+   * Creates a new SnapshotEngine instance
+   *
+   * @param {string} [teamName='default'] - Name of the team
+   */
+  constructor(teamName = 'default') {
+    // Store the team name
+    this.teamName = teamName;
+
+    // Set up the base directory: ~/.clearctx
+    const baseDir = path.join(os.homedir(), '.clearctx');
+    const teamDir = path.join(baseDir, 'team', teamName);
+
+    // Define paths for snapshots directory
+    this.snapshotsDir = path.join(teamDir, 'snapshots');
+
+    // Define paths to the index files we need to snapshot
+    this.contractsIndexPath = path.join(teamDir, 'contracts', 'index.json');
+    this.artifactsIndexPath = path.join(teamDir, 'artifacts', 'index.json');
+    this.pipelinesIndexPath = path.join(teamDir, 'pipelines', 'index.json');
+
+    // Define path to artifacts data directory (for version manifest)
+    this.artifactsDataDir = path.join(teamDir, 'artifacts', 'data');
+
+    // Define locks directory
+    this.locksDir = path.join(teamDir, 'locks');
+
+    // Create the snapshots directory if it doesn't exist
+    if (!fs.existsSync(this.snapshotsDir)) {
+      fs.mkdirSync(this.snapshotsDir, { recursive: true });
+    }
+  }
+
+  /**
+   * Create a snapshot of the current team state
+   *
+   * This method:
+   * 1. Locks all three index files (contracts, artifacts, pipelines)
+   * 2. Reads their current state
+   * 3. Scans artifact version files to build a version manifest
+   * 4. Creates a snapshot file with deep copies of all state
+   * 5. Releases all locks
+   *
+   * @param {string} snapshotId - Unique identifier for this snapshot
+   * @param {Object} [options={}] - Snapshot options
+   * @param {string} [options.label=''] - Short label for this snapshot
+   * @param {string} [options.description=''] - Longer description
+   * @returns {Object} Snapshot summary with id, label, timestamp, counts
+   */
+  createSnapshot(snapshotId, { label = '', description = '' } = {}) {
+    // Step 1: Acquire all three locks in a consistent order to prevent deadlocks
+    // Always lock in the same order: contracts → artifacts → pipelines
+    acquireLock(this.locksDir, 'contracts-index');
+    acquireLock(this.locksDir, 'artifacts-index');
+    acquireLock(this.locksDir, 'pipelines-index');
+
+    try {
+      // Step 2: Read all three index files
+      // Use readJsonSafe to get empty object if file doesn't exist
+      const contractsIndex = readJsonSafe(this.contractsIndexPath, {});
+      const artifactsIndex = readJsonSafe(this.artifactsIndexPath, {});
+      const pipelinesIndex = readJsonSafe(this.pipelinesIndexPath, {});
+
+      // Step 3: Build artifact version manifest
+      // This tells us which version files existed at snapshot time
+      const artifactVersionManifest = this._scanVersionManifest();
+
+      // Step 4: Create the snapshot object
+      const snapshot = {
+        snapshotId,
+        label,
+        description,
+        createdAt: new Date().toISOString(),
+        state: {
+          // Deep copy all indexes to prevent mutation
+          contracts: this._deepCopy(contractsIndex),
+          artifacts: this._deepCopy(artifactsIndex),
+          pipelines: this._deepCopy(pipelinesIndex),
+          // Include the version manifest so we know what existed
+          artifactVersionManifest
+        }
+      };
+
+      // Step 5: Write snapshot to file using atomic write
+      const snapshotPath = path.join(this.snapshotsDir, `snap_${snapshotId}.json`);
+      atomicWriteJson(snapshotPath, snapshot);
+
+      // Step 6: Release all locks in reverse order
+      releaseLock(this.locksDir, 'pipelines-index');
+      releaseLock(this.locksDir, 'artifacts-index');
+      releaseLock(this.locksDir, 'contracts-index');
+
+      // Step 7: Return summary information
+      return {
+        snapshotId,
+        label,
+        createdAt: snapshot.createdAt,
+        contractCount: Object.keys(contractsIndex).length,
+        artifactCount: Object.keys(artifactsIndex).length,
+        pipelineCount: Object.keys(pipelinesIndex).length
+      };
+    } catch (err) {
+      // Always release locks on error (reverse order)
+      releaseLock(this.locksDir, 'pipelines-index');
+      releaseLock(this.locksDir, 'artifacts-index');
+      releaseLock(this.locksDir, 'contracts-index');
+      throw err;
+    }
+  }
+
+  /**
+   * List all snapshots with summary information
+   *
+   * @returns {Array} Array of snapshot summaries, sorted newest first
+   */
+  listSnapshots() {
+    // Read all files in the snapshots directory
+    if (!fs.existsSync(this.snapshotsDir)) {
+      return []; // No snapshots exist yet
+    }
+
+    const files = fs.readdirSync(this.snapshotsDir);
+
+    // Filter for snapshot files (snap_*.json)
+    const snapshotFiles = files.filter(f => f.startsWith('snap_') && f.endsWith('.json'));
+
+    // Read each snapshot and extract summary information
+    const summaries = [];
+    for (const file of snapshotFiles) {
+      const filePath = path.join(this.snapshotsDir, file);
+
+      try {
+        const snapshot = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+
+        // Create a summary object
+        summaries.push({
+          snapshotId: snapshot.snapshotId,
+          label: snapshot.label,
+          description: snapshot.description,
+          createdAt: snapshot.createdAt,
+          contractCount: Object.keys(snapshot.state.contracts || {}).length,
+          artifactCount: Object.keys(snapshot.state.artifacts || {}).length,
+          pipelineCount: Object.keys(snapshot.state.pipelines || {}).length
+        });
+      } catch (err) {
+        // Skip corrupted snapshot files
+        continue;
+      }
+    }
+
+    // Sort by createdAt descending (newest first)
+    summaries.sort((a, b) => {
+      const dateA = new Date(a.createdAt);
+      const dateB = new Date(b.createdAt);
+      return dateB - dateA; // Newest first
+    });
+
+    return summaries;
+  }
+
+  /**
+   * Get the full snapshot data by ID
+   *
+   * @param {string} snapshotId - The snapshot to retrieve
+   * @returns {Object|null} The full snapshot object, or null if not found
+   */
+  getSnapshot(snapshotId) {
+    const snapshotPath = path.join(this.snapshotsDir, `snap_${snapshotId}.json`);
+
+    // Check if the snapshot exists
+    if (!fs.existsSync(snapshotPath)) {
+      return null;
+    }
+
+    try {
+      const snapshot = JSON.parse(fs.readFileSync(snapshotPath, 'utf-8'));
+      return snapshot;
+    } catch (err) {
+      // File is corrupted or invalid
+      return null;
+    }
+  }
+
+  /**
+   * Rollback to a previous snapshot
+   *
+   * This method:
+   * 1. Reads the snapshot file
+   * 2. Locks all three index files
+   * 3. Overwrites contracts and pipelines indexes completely
+   * 4. For artifacts: either marks newer ones as rolled back, or overwrites completely
+   * 5. Releases all locks
+   *
+   * Important: This DOES NOT delete artifact version files on disk (they're immutable)
+   *
+   * @param {string} snapshotId - The snapshot to rollback to
+   * @param {Object} [options={}] - Rollback options
+   * @param {boolean} [options.preserveArtifacts=true] - Keep newer artifacts but mark them
+   * @returns {Object} Summary of rollback operation
+   * @throws {Error} If snapshot not found
+   */
+  rollback(snapshotId, { preserveArtifacts = true } = {}) {
+    // Step 1: Read the snapshot
+    const snapshot = this.getSnapshot(snapshotId);
+
+    if (!snapshot) {
+      throw new Error(`Snapshot "${snapshotId}" not found`);
+    }
+
+    // Step 2: Acquire all three locks (same order as createSnapshot)
+    acquireLock(this.locksDir, 'contracts-index');
+    acquireLock(this.locksDir, 'artifacts-index');
+    acquireLock(this.locksDir, 'pipelines-index');
+
+    try {
+      // Step 3: Restore CONTRACTS - complete overwrite
+      // This resets all contract statuses to what they were at snapshot time
+      atomicWriteJson(this.contractsIndexPath, snapshot.state.contracts);
+      const contractsRestored = Object.keys(snapshot.state.contracts).length;
+
+      // Step 4: Restore PIPELINES - complete overwrite
+      atomicWriteJson(this.pipelinesIndexPath, snapshot.state.pipelines);
+
+      // Step 5: Restore ARTIFACTS
+      let artifactsMarked = 0;
+
+      if (preserveArtifacts) {
+        // Read current artifacts index
+        const currentArtifacts = readJsonSafe(this.artifactsIndexPath, {});
+        const snapshotArtifacts = snapshot.state.artifacts;
+
+        // For each artifact in the current index
+        for (const [artifactId, currentEntry] of Object.entries(currentArtifacts)) {
+          const snapshotEntry = snapshotArtifacts[artifactId];
+
+          // Check if this artifact didn't exist in the snapshot
+          // OR if it has a higher version number now
+          if (!snapshotEntry || currentEntry.latestVersion > snapshotEntry.latestVersion) {
+            // Mark it as rolled back (but keep it in the index)
+            currentEntry.rolledBack = true;
+            artifactsMarked++;
+          }
+        }
+
+        // Merge: start with snapshot artifacts, then overlay current marked ones
+        const mergedArtifacts = { ...snapshotArtifacts };
+        for (const [artifactId, entry] of Object.entries(currentArtifacts)) {
+          if (entry.rolledBack) {
+            mergedArtifacts[artifactId] = entry;
+          }
+        }
+
+        // Write the merged index
+        atomicWriteJson(this.artifactsIndexPath, mergedArtifacts);
+      } else {
+        // Complete overwrite - don't preserve newer artifacts
+        atomicWriteJson(this.artifactsIndexPath, snapshot.state.artifacts);
+        artifactsMarked = 0;
+      }
+
+      // Step 6: Release all locks in reverse order
+      releaseLock(this.locksDir, 'pipelines-index');
+      releaseLock(this.locksDir, 'artifacts-index');
+      releaseLock(this.locksDir, 'contracts-index');
+
+      // Step 7: Return summary
+      return {
+        rolledBackTo: snapshotId,
+        contractsRestored,
+        artifactsMarked,
+        message: preserveArtifacts
+          ? `Rolled back to ${snapshotId}. Newer artifacts marked as rolledBack.`
+          : `Rolled back to ${snapshotId}. Artifacts overwritten.`
+      };
+    } catch (err) {
+      // Always release locks on error (reverse order)
+      releaseLock(this.locksDir, 'pipelines-index');
+      releaseLock(this.locksDir, 'artifacts-index');
+      releaseLock(this.locksDir, 'contracts-index');
+      throw err;
+    }
+  }
+
+  /**
+   * Replay from a snapshot with optional input overrides
+   *
+   * This method:
+   * 1. Calls rollback() to restore the snapshot state
+   * 2. Applies overrides to contract inputs (for testing different scenarios)
+   * 3. Returns a message telling the caller to run the dependency resolver
+   *
+   * Note: This does NOT directly call the dependency resolver (to avoid circular imports)
+   * The MCP server handler should call resolver.resolve() after replay returns.
+   *
+   * @param {string} snapshotId - The snapshot to replay from
+   * @param {Object} [options={}] - Replay options
+   * @param {Object} [options.overrides={}] - Contract ID → override data map
+   * @returns {Object} Summary of replay operation
+   * @throws {Error} If snapshot not found
+   *
+   * @example
+   * // Replay with modified context for a specific contract
+   * replay('snap_001', {
+   *   overrides: {
+   *     'schema-design': {
+   *       inputs: {
+   *         context: 'Use PostgreSQL instead of MongoDB',
+   *         parameters: { database: 'postgres' }
+   *       }
+   *     }
+   *   }
+   * });
+   */
+  replay(snapshotId, { overrides = {} } = {}) {
+    // Step 1: Rollback to the snapshot first
+    const rollbackResult = this.rollback(snapshotId);
+
+    // Step 2: Apply overrides to contract inputs
+    if (Object.keys(overrides).length > 0) {
+      // Acquire lock on contracts index
+      acquireLock(this.locksDir, 'contracts-index');
+
+      try {
+        // Read the restored contracts index
+        const contractsIndex = readJsonSafe(this.contractsIndexPath, {});
+
+        // Apply overrides for each specified contract
+        for (const [contractId, override] of Object.entries(overrides)) {
+          const contract = contractsIndex[contractId];
+
+          if (!contract) {
+            // Contract doesn't exist - skip this override
+            continue;
+          }
+
+          // Merge override inputs into the contract
+          if (override.inputs) {
+            // If override has context, replace it completely
+            if (override.inputs.context !== undefined) {
+              contract.inputs.context = override.inputs.context;
+            }
+
+            // If override has artifacts, replace the array
+            if (override.inputs.artifacts !== undefined) {
+              contract.inputs.artifacts = override.inputs.artifacts;
+            }
+
+            // If override has parameters, deep merge them
+            if (override.inputs.parameters !== undefined) {
+              contract.inputs.parameters = {
+                ...contract.inputs.parameters,
+                ...override.inputs.parameters
+              };
+            }
+          }
+
+          // Update the contract's timestamp
+          contract.updatedAt = new Date().toISOString();
+        }
+
+        // Save the updated contracts index
+        atomicWriteJson(this.contractsIndexPath, contractsIndex);
+
+        // Release lock
+        releaseLock(this.locksDir, 'contracts-index');
+      } catch (err) {
+        // Always release lock on error
+        releaseLock(this.locksDir, 'contracts-index');
+        throw err;
+      }
+    }
+
+    // Step 3: Return summary
+    return {
+      replayedFrom: snapshotId,
+      overridesApplied: Object.keys(overrides),
+      contractsRestored: rollbackResult.contractsRestored,
+      message: 'Replayed from snapshot with overrides. Run dependency resolver to continue execution.'
+    };
+  }
+
+  /**
+   * Scan the artifacts/data directory to build a version manifest
+   *
+   * This tells us which version files existed at snapshot time.
+   * We scan each artifact's directory and collect version numbers.
+   *
+   * @private
+   * @returns {Object} Map of artifactId → [version numbers]
+   *
+   * @example
+   * {
+   *   "schema-user-model": [1],
+   *   "api-contract-auth": [1, 2, 3]
+   * }
+   */
+  _scanVersionManifest() {
+    const manifest = {};
+
+    // Check if artifacts data directory exists
+    if (!fs.existsSync(this.artifactsDataDir)) {
+      return manifest; // No artifacts yet
+    }
+
+    // Read all subdirectories (each is an artifact)
+    const artifactDirs = fs.readdirSync(this.artifactsDataDir);
+
+    for (const artifactId of artifactDirs) {
+      const artifactPath = path.join(this.artifactsDataDir, artifactId);
+
+      // Skip if not a directory
+      if (!fs.statSync(artifactPath).isDirectory()) {
+        continue;
+      }
+
+      // Read all files in this artifact directory
+      const files = fs.readdirSync(artifactPath);
+
+      // Filter for version files (v1.json, v2.json, etc.)
+      const versionFiles = files.filter(f => /^v\d+\.json$/.test(f));
+
+      // Extract version numbers
+      const versions = versionFiles.map(f => {
+        const match = f.match(/^v(\d+)\.json$/);
+        return match ? parseInt(match[1], 10) : null;
+      }).filter(v => v !== null); // Remove any nulls
+
+      // Sort versions numerically
+      versions.sort((a, b) => a - b);
+
+      // Add to manifest
+      if (versions.length > 0) {
+        manifest[artifactId] = versions;
+      }
+    }
+
+    return manifest;
+  }
+
+  /**
+   * Deep copy an object using JSON serialization
+   *
+   * This is a simple way to clone objects. It works for plain objects
+   * but won't preserve functions, dates, or circular references.
+   *
+   * @private
+   * @param {*} obj - Object to deep copy
+   * @returns {*} Deep copy of the object
+   */
+  _deepCopy(obj) {
+    return JSON.parse(JSON.stringify(obj));
+  }
+}
+
+// Export the SnapshotEngine class
+module.exports = SnapshotEngine;

package/src/stale-detector.js

@@ -0,0 +1,169 @@
+/**
+ * StaleDetector - Session Continuity Engine (Layer 0)
+ *
+ * Detects when the codebase has changed significantly since the last session,
+ * helping identify when previous context might be outdated or incorrect.
+ *
+ * This class checks for various staleness indicators:
+ * - Files you were working on were modified by someone else
+ * - Git branch has changed
+ * - Many commits happened since last session
+ * - Long time gap since last session
+ * - Files you were using were deleted
+ */
+
+const DiffEngine = require('./diff-engine');
+const SessionSnapshot = require('./session-snapshot');
+
+/**
+ * StaleDetector class
+ * Analyzes differences between current state and last session to detect stale context
+ */
+class StaleDetector {
+  /**
+   * Create a StaleDetector instance
+   * @param {string} projectPath - Absolute path to the project directory
+   */
+  constructor(projectPath) {
+    // Store the project path for reference
+    this.projectPath = projectPath;
+
+    // Create DiffEngine to compute differences from last snapshot
+    this.diff = new DiffEngine(projectPath);
+
+    // Create SessionSnapshot to load the last saved session state
+    this.snapshot = new SessionSnapshot(projectPath);
+  }
+
+  /**
+   * Check for stale context indicators
+   *
+   * This is the main method that analyzes the current state versus the last session.
+   * It returns a comprehensive report of all staleness warnings.
+   *
+   * @returns {Object} Stale context report with the following structure:
+   *   - isStale: boolean - true if any warnings were found
+   *   - noSnapshot: boolean - true if there's no previous session to compare against
+   *   - message: string - human-readable summary message
+   *   - lastSnapshotAge: string - how long ago the last session was (e.g., "3 days ago")
+   *   - lastSnapshotId: string - identifier of the last snapshot
+   *   - changedActiveFiles: string[] - list of files you were working on that changed
+   *   - totalFileChanges: number - total count of all file changes (added + modified + deleted)
+   *   - newCommits: number - number of commits since last session
+   *   - warnings: Array<Object> - detailed list of all warnings, each with:
+   *       - type: string - category of warning
+   *       - message: string - human-readable description
+   *       - (additional fields depending on warning type)
+   */
+  check() {
+    // Step 1: Get the latest snapshot (the most recent saved session state)
+    const snapshot = this.snapshot.getLatest();
+
+    // Step 2: If there's no previous snapshot, we can't detect staleness
+    // This happens on the very first session in a project
+    if (!snapshot) {
+      return {
+        isStale: false,
+        noSnapshot: true,
+        message: 'No previous session to compare against.',
+        warnings: []
+      };
+    }
+
+    // Step 3: Get the diff (differences) between now and the last snapshot
+    const diff = this.diff.diffFromLatest();
+
+    // Step 4: If diff computation failed (also means no snapshot), return non-stale
+    if (diff.noSnapshot) {
+      return {
+        isStale: false,
+        noSnapshot: true,
+        message: 'No previous session to compare against.',
+        warnings: []
+      };
+    }
+
+    // Step 5: Build an array of warnings by checking different staleness indicators
+    const warnings = [];
+
+    // WARNING TYPE 1: Active files modified
+    // These are files you were actively working on in your last session
+    // If they changed, your mental model might be outdated
+    if (diff.contextImpact && diff.contextImpact.activeFilesModified) {
+      for (const file of diff.contextImpact.activeFilesModified) {
+        warnings.push({
+          type: 'active_file_modified',
+          file,
+          message: `${file} was modified since your last session. Re-read before assuming previous context.`
+        });
+      }
+    }
+
+    // WARNING TYPE 2: Branch changed
+    // If you switched branches, you're in a completely different code context
+    if (diff.gitChanges && diff.gitChanges.branchChanged) {
+      warnings.push({
+        type: 'branch_changed',
+        oldBranch: diff.gitChanges.oldBranch,
+        newBranch: diff.gitChanges.newBranch,
+        message: `Branch changed from ${diff.gitChanges.oldBranch} to ${diff.gitChanges.newBranch} since your last session.`
+      });
+    }
+
+    // WARNING TYPE 3: Many commits since last session
+    // If lots of commits happened, the codebase might be significantly different
+    if (diff.gitChanges && diff.gitChanges.newCommitCount > 5) {
+      warnings.push({
+        type: 'many_commits',
+        count: diff.gitChanges.newCommitCount,
+        message: `${diff.gitChanges.newCommitCount} commits have been made since your last session. Significant changes may have occurred.`
+      });
+    }
+
+    // WARNING TYPE 4: Long time gap since last session
+    // If it's been more than 24 hours (86400000 milliseconds), context is likely stale
+    if (diff.timeDelta > 86400000) {
+      warnings.push({
+        type: 'long_gap',
+        timeDelta: diff.timeDeltaHuman,
+        message: `Last session was ${diff.timeDeltaHuman}. Codebase may have changed significantly.`
+      });
+    }
+
+    // WARNING TYPE 5: Active files deleted
+    // If files you were working on no longer exist, that's critical information
+    if (diff.fileChanges && diff.fileChanges.deleted && snapshot.activeFiles) {
+      for (const file of diff.fileChanges.deleted) {
+        // Only warn if this deleted file was one you were actively using
+        if (snapshot.activeFiles.includes(file)) {
+          warnings.push({
+            type: 'active_file_deleted',
+            file,
+            message: `${file} was deleted since your last session.`
+          });
+        }
+      }
+    }
+
+    // Step 6: Determine overall staleness
+    // If we found any warnings, the context is considered stale
+    const isStale = warnings.length > 0;
+
+    // Step 7 & 8: Return comprehensive staleness report
+    return {
+      isStale,
+      lastSnapshotAge: diff.timeDeltaHuman,
+      lastSnapshotId: snapshot.snapshotId,
+      changedActiveFiles: diff.contextImpact ? diff.contextImpact.activeFilesModified : [],
+      totalFileChanges: (diff.fileChanges.added.length +
+                        diff.fileChanges.modified.length +
+                        diff.fileChanges.deleted.length),
+      newCommits: diff.gitChanges ? diff.gitChanges.newCommitCount : 0,
+      warnings
+    };
+  }
+}
+
+// Export the class so other modules can use it
+// Usage: const StaleDetector = require('./stale-detector');
+module.exports = StaleDetector;