clearctx 3.0.0

package/src/atomic-io.js

@@ -0,0 +1,99 @@
+/**
+ * Atomic I/O utilities for safe file operations.
+ *
+ * These functions ensure data integrity during concurrent access:
+ * - atomicWriteJson: Write-then-rename prevents partial reads
+ * - writeImmutable: Exclusive create prevents overwrites
+ * - readJsonSafe: Never throws, returns fallback on error
+ * - appendJsonl: Append-only log format for event streams
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+/**
+ * Write JSON data atomically using write-then-rename.
+ * Prevents other processes from reading partial/corrupt data.
+ *
+ * @param {string} filePath - Target file path
+ * @param {any} data - Data to serialize as JSON
+ */
+function atomicWriteJson(filePath, data) {
+  // Ensure parent directory exists
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // Write to temp file in same directory (ensures same filesystem for atomic rename)
+  const tempSuffix = crypto.randomBytes(8).toString('hex');
+  const tempPath = `${filePath}.tmp.${tempSuffix}`;
+
+  fs.writeFileSync(tempPath, JSON.stringify(data, null, 2), 'utf-8');
+
+  // Atomic rename — replaces target file in a single filesystem operation
+  fs.renameSync(tempPath, filePath);
+}
+
+/**
+ * Write JSON data with exclusive create (fails if file exists).
+ * Used for immutable artifacts like versioned snapshots.
+ *
+ * @param {string} filePath - Target file path
+ * @param {any} data - Data to serialize as JSON
+ * @throws {Error} Throws EEXIST if file already exists
+ */
+function writeImmutable(filePath, data) {
+  // Ensure parent directory exists
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // 'wx' flag = exclusive create — atomic check-and-create operation
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), { flag: 'wx' });
+}
+
+/**
+ * Read and parse JSON file safely, never throws.
+ * Returns fallback value if file doesn't exist or parse fails.
+ *
+ * @param {string} filePath - File to read
+ * @param {any} [fallback={}] - Value to return on error
+ * @returns {any} Parsed JSON or fallback
+ */
+function readJsonSafe(filePath, fallback = {}) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(content);
+  } catch (err) {
+    // File doesn't exist, permission denied, invalid JSON, etc.
+    return fallback;
+  }
+}
+
+/**
+ * Append a JSON object to a JSONL (JSON Lines) file.
+ * Each line is a complete JSON object for append-only event logs.
+ *
+ * @param {string} filePath - JSONL file path
+ * @param {any} obj - Object to append (serialized as one line)
+ */
+function appendJsonl(filePath, obj) {
+  // Ensure parent directory exists
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // Append as single line (no pretty printing)
+  fs.appendFileSync(filePath, JSON.stringify(obj) + '\n', 'utf-8');
+}
+
+module.exports = {
+  atomicWriteJson,
+  writeImmutable,
+  readJsonSafe,
+  appendJsonl
+};

package/src/briefing-generator.js

@@ -0,0 +1,451 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+const DiffEngine = require('./diff-engine');
+const SessionSnapshot = require('./session-snapshot');
+const DecisionJournal = require('./decision-journal');
+const PatternRegistry = require('./pattern-registry');
+
+/**
+ * BriefingGenerator
+ *
+ * Generates markdown briefings for session continuity. This module creates
+ * comprehensive summaries of what happened since the last session, including
+ * git changes, file modifications, decisions made, and active patterns.
+ *
+ * Part of the Session Continuity Engine (Layer 0).
+ */
+class BriefingGenerator {
+  /**
+   * Creates a new BriefingGenerator instance
+   * @param {string} projectPath - Absolute path to the project root directory
+   */
+  constructor(projectPath) {
+    // Initialize all the engines we need to generate a briefing
+    this.diff = new DiffEngine(projectPath);
+    this.snapshot = new SessionSnapshot(projectPath);
+    this.journal = new DecisionJournal(projectPath);
+    this.patterns = new PatternRegistry(projectPath);
+    this.projectPath = projectPath;
+
+    // Create a unique hash for this project to store briefings
+    // Uses the same hash and path as SessionSnapshot and other modules:
+    //   ~/.clearctx/continuity/{projectHash}/briefings/
+    const hash = crypto.createHash('sha256').update(projectPath).digest('hex').slice(0, 16);
+    const storageDir = path.join(os.homedir(), '.clearctx', 'continuity', hash);
+    this.briefingsDir = path.join(storageDir, 'briefings');
+
+    // Make sure the briefings directory exists
+    if (!fs.existsSync(this.briefingsDir)) {
+      fs.mkdirSync(this.briefingsDir, { recursive: true });
+    }
+  }
+
+  /**
+   * Generates a complete markdown briefing from the latest snapshot and current diff
+   * @param {Object} options - Configuration options
+   * @param {number} options.maxTokens - Approximate max character length (default: 4000)
+   * @param {boolean} options.includeDecisions - Include recent decisions (default: true)
+   * @param {boolean} options.includePatterns - Include pattern rules (default: true)
+   * @param {number} options.decisionLimit - How many recent decisions (default: 10)
+   * @returns {Object} Contains markdown, briefingId, savedTo, and sections
+   */
+  generate(options = {}) {
+    // Set up default options
+    const maxTokens = options.maxTokens || 4000;
+    const includeDecisions = options.includeDecisions !== false;
+    const includePatterns = options.includePatterns !== false;
+    const decisionLimit = options.decisionLimit || 10;
+
+    // Get the latest snapshot to compare against
+    const latestSnapshot = this.snapshot.getLatest();
+
+    // If no snapshot exists, this is the first session
+    if (!latestSnapshot) {
+      return this._generateFirstSessionBriefing(includePatterns);
+    }
+
+    // Get the diff from the latest snapshot to now
+    const diff = this.diff.diffFromLatest();
+
+    // If diff has no git state, use safe defaults
+    const gitChanges = diff.gitChanges || { newCommitCount: 0, commits: [], branchChanged: false, oldBranch: 'unknown', newBranch: 'unknown' };
+    const fileChanges = diff.fileChanges || { added: [], modified: [], deleted: [], renamed: [] };
+
+    // Build all the sections of the briefing
+    const sections = {
+      header: this._formatHeader(latestSnapshot, diff),
+      timeSummary: this._formatTimeSummary(diff, gitChanges, fileChanges),
+      gitSection: this._formatGitSection(gitChanges),
+      fileSection: this._formatFileSection(fileChanges, (latestSnapshot.workingContext && latestSnapshot.workingContext.activeFiles) || []),
+      contextSection: this._formatContextSection(latestSnapshot),
+      decisionsSection: includeDecisions ? this._formatDecisions(decisionLimit) : '',
+      patternsSection: includePatterns ? this._formatPatterns() : '',
+      staleSection: this._formatStaleWarnings(fileChanges, (latestSnapshot.workingContext && latestSnapshot.workingContext.activeFiles) || [])
+    };
+
+    // Combine all sections into one markdown document
+    let markdown = [
+      sections.header,
+      sections.timeSummary,
+      sections.gitSection,
+      sections.fileSection,
+      sections.contextSection,
+      sections.decisionsSection,
+      sections.patternsSection,
+      sections.staleSection
+    ].filter(s => s).join('\n\n'); // Filter out empty sections
+
+    // Trim if we exceed maxTokens (rough approximation: 1 token ≈ 1 character)
+    if (markdown.length > maxTokens) {
+      markdown = this._trimToTokenLimit(sections, maxTokens);
+    }
+
+    // Save the briefing to disk
+    const timestamp = Date.now();
+    const briefingId = `brief_${timestamp}`;
+    const savedTo = path.join(this.briefingsDir, `${briefingId}.md`);
+    fs.writeFileSync(savedTo, markdown, 'utf8');
+
+    return {
+      markdown,
+      briefingId,
+      savedTo,
+      sections
+    };
+  }
+
+  /**
+   * Generates a briefing for the very first session
+   * @param {boolean} includePatterns - Whether to include patterns
+   * @returns {Object} Briefing object
+   * @private
+   */
+  _generateFirstSessionBriefing(includePatterns) {
+    let markdown = '## Session Briefing\n\n';
+    markdown += 'This is the first tracked session for this project. No previous context available.\n';
+
+    // Include patterns if requested
+    if (includePatterns) {
+      const patternsSection = this._formatPatterns();
+      if (patternsSection) {
+        markdown += '\n' + patternsSection;
+      }
+    }
+
+    // Save the briefing
+    const timestamp = Date.now();
+    const briefingId = `brief_${timestamp}`;
+    const savedTo = path.join(this.briefingsDir, `${briefingId}.md`);
+    fs.writeFileSync(savedTo, markdown, 'utf8');
+
+    return {
+      markdown,
+      briefingId,
+      savedTo,
+      sections: { header: markdown }
+    };
+  }
+
+  /**
+   * Formats the header section with date and time
+   * @param {Object} snapshot - The latest snapshot
+   * @param {Object} diff - The diff object
+   * @returns {string} Formatted header
+   * @private
+   */
+  _formatHeader(snapshot, diff) {
+    const now = new Date();
+    const dateStr = now.toLocaleDateString('en-US', {
+      month: 'short',
+      day: 'numeric',
+      year: 'numeric'
+    });
+    const timeStr = now.toLocaleTimeString('en-US', {
+      hour: 'numeric',
+      minute: '2-digit',
+      hour12: true
+    });
+    return `## Session Briefing — ${dateStr}, ${timeStr}`;
+  }
+
+  /**
+   * Formats the time summary section
+   * @param {Object} diff - The diff object
+   * @param {Object} gitChanges - Safe git changes object
+   * @param {Object} fileChanges - Safe file changes object
+   * @returns {string} Formatted time summary
+   * @private
+   */
+  _formatTimeSummary(diff, gitChanges, fileChanges) {
+    const timeDelta = this._formatTimeDelta(diff.timeDelta || diff.timeDeltaMs || 0);
+    const commitCount = gitChanges.commits ? gitChanges.commits.length : gitChanges.newCommitCount || 0;
+    const addedCount = fileChanges.added.length;
+    const modifiedCount = fileChanges.modified.length;
+    const deletedCount = fileChanges.deleted.length;
+
+    let summary = `### Since your last session (${timeDelta}):\n`;
+    summary += `- **${commitCount} new commit${commitCount !== 1 ? 's' : ''}** on \`${gitChanges.newBranch || 'unknown'}\`\n`;
+    summary += `- **${addedCount} file${addedCount !== 1 ? 's' : ''} added**, **${modifiedCount} modified**, **${deletedCount} deleted**`;
+
+    return summary;
+  }
+
+  /**
+   * Formats a time delta in milliseconds to human-readable format
+   * @param {number} ms - Milliseconds
+   * @returns {string} Human-readable time delta
+   * @private
+   */
+  _formatTimeDelta(ms) {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+
+    if (days > 0) return `${days} day${days !== 1 ? 's' : ''} ago`;
+    if (hours > 0) return `${hours} hour${hours !== 1 ? 's' : ''} ago`;
+    if (minutes > 0) return `${minutes} minute${minutes !== 1 ? 's' : ''} ago`;
+    return 'just now';
+  }
+
+  /**
+   * Formats the git changes section
+   * @param {Object} gitChanges - Git changes from diff
+   * @returns {string} Formatted git section
+   * @private
+   */
+  _formatGitSection(gitChanges) {
+    const commits = gitChanges.commits || [];
+    if (!commits.length && !gitChanges.branchChanged) {
+      return ''; // No git changes to report
+    }
+
+    let section = '### Git Changes:\n';
+
+    // List new commits
+    if (commits.length > 0) {
+      commits.forEach(commit => {
+        section += `- \`${commit.hash}\` ${commit.message}\n`;
+      });
+    }
+
+    // Report branch changes
+    if (gitChanges.branchChanged) {
+      section += `- Branch changed from \`${gitChanges.oldBranch || 'unknown'}\` to \`${gitChanges.newBranch || 'unknown'}\``;
+    }
+
+    return section.trim();
+  }
+
+  /**
+   * Formats the file changes section
+   * @param {Object} fileChanges - File changes from diff
+   * @param {Array} activeFiles - Files that were actively being worked on
+   * @returns {string} Formatted file section
+   * @private
+   */
+  _formatFileSection(fileChanges, activeFiles) {
+    let section = '### File Changes:\n';
+
+    // Added files
+    section += '**Added:**\n';
+    if (fileChanges.added.length > 0) {
+      fileChanges.added.forEach(file => {
+        section += `- \`${file}\`\n`;
+      });
+    } else {
+      section += '- (none)\n';
+    }
+
+    section += '\n**Modified:**\n';
+    if (fileChanges.modified.length > 0) {
+      fileChanges.modified.forEach(file => {
+        // Mark files that were being actively worked on
+        const isActive = activeFiles.includes(file);
+        section += `- \`${file}\`${isActive ? ' ⚠️ (you were working on this!)' : ''}\n`;
+      });
+    } else {
+      section += '- (none)\n';
+    }
+
+    section += '\n**Deleted:**\n';
+    if (fileChanges.deleted.length > 0) {
+      fileChanges.deleted.forEach(file => {
+        section += `- \`${file}\`\n`;
+      });
+    } else {
+      section += '- (none)\n';
+    }
+
+    return section.trim();
+  }
+
+  /**
+   * Formats the previous context section
+   * @param {Object} snapshot - The latest snapshot
+   * @returns {string} Formatted context section
+   * @private
+   */
+  _formatContextSection(snapshot) {
+    // The snapshot stores working context in snapshot.workingContext
+    const ctx = snapshot.workingContext;
+    if (!ctx) {
+      return '';
+    }
+
+    let section = '### Your Previous Context:\n';
+
+    // What were we working on?
+    if (ctx.taskSummary) {
+      section += `- **Working on:** ${ctx.taskSummary}\n`;
+    }
+
+    // Any open questions?
+    if (ctx.openQuestions && ctx.openQuestions.length > 0) {
+      section += '- **Open questions:**\n';
+      ctx.openQuestions.forEach(q => {
+        section += `  - ${q}\n`;
+      });
+    }
+
+    return section.trim();
+  }
+
+  /**
+   * Formats the decisions section
+   * @param {number} limit - Maximum number of decisions to include
+   * @returns {string} Formatted decisions section
+   * @private
+   */
+  _formatDecisions(limit) {
+    const decisions = this.journal.list({ limit });
+    if (decisions.length === 0) {
+      return '';
+    }
+
+    let section = '### Recent Decisions:\n';
+    decisions.forEach((decision, index) => {
+      const date = new Date(decision.createdAt).toLocaleDateString('en-US', {
+        month: 'short',
+        day: 'numeric'
+      });
+      section += `${index + 1}. **${decision.decision}** — ${decision.reason} _(${date})_\n`;
+    });
+
+    return section.trim();
+  }
+
+  /**
+   * Formats the patterns section
+   * @returns {string} Formatted patterns section
+   * @private
+   */
+  _formatPatterns() {
+    const patterns = this.patterns.list();
+    if (patterns.length === 0) {
+      return '';
+    }
+
+    let section = '### Patterns to Follow:\n';
+    patterns.forEach(pattern => {
+      const contextStr = pattern.context ? ` _(context: ${pattern.context})_` : '';
+      section += `- ${pattern.rule}${contextStr}\n`;
+    });
+
+    return section.trim();
+  }
+
+  /**
+   * Formats the stale warnings section
+   * @param {Object} fileChanges - File changes from diff
+   * @param {Array} activeFiles - Files that were actively being worked on
+   * @returns {string} Formatted stale warnings section
+   * @private
+   */
+  _formatStaleWarnings(fileChanges, activeFiles) {
+    // Files that were active and have been modified are stale
+    const staleFiles = fileChanges.modified.filter(file => activeFiles.includes(file));
+
+    if (staleFiles.length === 0) {
+      return '';
+    }
+
+    let section = '### ⚠ Stale Context Warnings:\n';
+    staleFiles.forEach(file => {
+      section += `- \`${file}\` was modified since your last session. Re-read before assuming previous context is correct.\n`;
+    });
+
+    return section.trim();
+  }
+
+  /**
+   * Trims the briefing to fit within token limit
+   * @param {Object} sections - All sections of the briefing
+   * @param {number} maxTokens - Maximum allowed characters
+   * @returns {string} Trimmed markdown
+   * @private
+   */
+  _trimToTokenLimit(sections, maxTokens) {
+    // Priority order: header > timeSummary > gitSection > fileSection > contextSection > decisionsSection > patternsSection > staleSection
+    // We trim from least important to most important
+    const priorityOrder = [
+      'patternsSection',
+      'decisionsSection',
+      'staleSection',
+      'fileSection',
+      'gitSection',
+      'contextSection',
+      'timeSummary',
+      'header'
+    ];
+
+    let result = '';
+    let currentLength = 0;
+
+    // Start from most important and add sections until we hit the limit
+    for (let i = priorityOrder.length - 1; i >= 0; i--) {
+      const sectionName = priorityOrder[i];
+      const sectionContent = sections[sectionName];
+
+      if (!sectionContent) continue;
+
+      const sectionLength = sectionContent.length + 2; // +2 for the newlines
+      if (currentLength + sectionLength > maxTokens) {
+        break; // Can't fit any more sections
+      }
+
+      result = result ? sectionContent + '\n\n' + result : sectionContent;
+      currentLength += sectionLength;
+    }
+
+    return result.trim();
+  }
+
+  /**
+   * Gets the most recently generated briefing markdown
+   * @returns {string|null} The briefing markdown, or null if none exist
+   */
+  getLatestBriefing() {
+    // Read all briefing files in the directory
+    if (!fs.existsSync(this.briefingsDir)) {
+      return null;
+    }
+
+    const files = fs.readdirSync(this.briefingsDir)
+      .filter(f => f.startsWith('brief_') && f.endsWith('.md'))
+      .sort()
+      .reverse(); // Most recent first
+
+    if (files.length === 0) {
+      return null;
+    }
+
+    // Read and return the most recent briefing
+    const latestFile = path.join(this.briefingsDir, files[0]);
+    return fs.readFileSync(latestFile, 'utf8');
+  }
+}
+
+module.exports = BriefingGenerator;