clearctx 3.0.0

package/src/continuity-hooks.js

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Continuity Hooks — Handler functions for Claude Code lifecycle hooks.
+ *
+ * This module exports 4 handler functions, one for each hook event:
+ *   - handleSessionStart  — Injects a diff-aware briefing at session start
+ *   - handleStop          — Lightweight background checkpoint after each response
+ *   - handlePreCompact    — Critical save before context compaction
+ *   - handleSessionEnd    — Final snapshot on exit (Ctrl+C, /exit, error)
+ *
+ * Each handler receives the parsed hook input JSON from Claude Code.
+ * Handlers for SessionStart and PreCompact can return { additionalContext }
+ * which gets injected into Claude's conversation.
+ *
+ * Part of the Session Continuity Engine (Layer 0).
+ */
+
+const SessionSnapshot = require('./session-snapshot');
+const BriefingGenerator = require('./briefing-generator');
+const DecisionJournal = require('./decision-journal');
+const PatternRegistry = require('./pattern-registry');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * handleSessionStart — Fires when a Claude Code session begins.
+ *
+ * This is the most important handler. It checks if continuity data exists
+ * for the project, and if so, generates a diff-aware briefing that gets
+ * injected into the conversation automatically.
+ *
+ * @param {Object} input - The parsed hook JSON from Claude Code
+ * @param {string} input.working_directory - Absolute path to the project root
+ * @param {string} input.session_id - Unique session identifier
+ * @returns {Object} { additionalContext: string } or {} if no briefing needed
+ */
+function handleSessionStart(input) {
+  // Extract the project root directory from the hook input
+  const workDir = input.working_directory;
+  if (!workDir) return {};
+
+  // Check if we have any previous snapshot data for this project
+  const snap = new SessionSnapshot(workDir);
+  const latest = snap.getLatest();
+
+  // If no previous snapshot exists, this is a new project — nothing to brief
+  if (!latest) return {};
+
+  // Generate a diff-aware briefing comparing last snapshot to current state
+  // Budget: 500 tokens (characters) to keep session start fast
+  const gen = new BriefingGenerator(workDir);
+  const result = gen.generate({
+    maxTokens: 500,
+    includeDecisions: true,
+    includePatterns: true
+  });
+
+  // If we got a briefing, inject it into the conversation
+  if (result && result.markdown) {
+    return { additionalContext: result.markdown };
+  }
+
+  return {};
+}
+
+/**
+ * handleStop — Fires after every Claude response (async, runs in background).
+ *
+ * This is a lightweight handler. It only captures a new snapshot if the
+ * last one is more than 30 minutes old, to avoid excessive I/O.
+ *
+ * Since this hook is async, it cannot return additionalContext.
+ *
+ * @param {Object} input - The parsed hook JSON from Claude Code
+ * @param {string} input.working_directory - Absolute path to the project root
+ * @param {string} input.session_id - Unique session identifier
+ * @returns {Object} Always returns {} (async hook, no context injection)
+ */
+function handleStop(input) {
+  const workDir = input.working_directory;
+  const sessionId = input.session_id || 'auto-stop';
+  if (!workDir) return {};
+
+  // Check if continuity data exists — don't auto-create on Stop events
+  const snap = new SessionSnapshot(workDir);
+  const latest = snap.getLatest();
+  if (!latest) return {};
+
+  // Only snapshot if the last one is more than 30 minutes old
+  // This keeps the Stop hook fast and non-disruptive
+  const THIRTY_MINUTES = 30 * 60 * 1000; // 30 minutes in milliseconds
+  const lastCapturedAt = new Date(latest.capturedAt).getTime();
+  const timeSinceLast = Date.now() - lastCapturedAt;
+
+  if (timeSinceLast > THIRTY_MINUTES) {
+    // Capture a safety-net snapshot
+    snap.capture(sessionId, {
+      taskSummary: 'Auto-checkpoint (30min interval)',
+      activeFiles: []
+    });
+  }
+
+  return {};
+}
+
+/**
+ * handlePreCompact — Fires right before context compaction.
+ *
+ * This is the CRITICAL save moment. Context is about to be destroyed by
+ * compaction, so we capture a full snapshot and generate a compact briefing
+ * that gets re-injected after compaction. This preserves essential context
+ * that would otherwise be lost.
+ *
+ * @param {Object} input - The parsed hook JSON from Claude Code
+ * @param {string} input.working_directory - Absolute path to the project root
+ * @param {string} input.session_id - Unique session identifier
+ * @returns {Object} { additionalContext: string } with preserved context
+ */
+function handlePreCompact(input) {
+  const workDir = input.working_directory;
+  const sessionId = input.session_id || 'pre-compact';
+  if (!workDir) return {};
+
+  // Step 1: Generate a compact briefing BEFORE capturing a new snapshot.
+  // This way the diff compares the PREVIOUS snapshot to current state,
+  // giving a meaningful summary of what changed during this session.
+  // (If we captured first, the diff would always be empty.)
+  const gen = new BriefingGenerator(workDir);
+  const briefing = gen.generate({
+    maxTokens: 300,
+    includeDecisions: true,
+    includePatterns: true
+  });
+
+  // Step 2: NOW capture a full snapshot so future sessions can diff against it
+  const snap = new SessionSnapshot(workDir);
+  snap.capture(sessionId, {
+    taskSummary: 'Auto-saved before context compaction',
+    activeFiles: []
+  });
+
+  // Step 3: Get recent decisions to reinforce after compaction
+  const journal = new DecisionJournal(workDir);
+  const recentDecisions = journal.list({ limit: 5 });
+
+  // Step 4: Get patterns to reinforce after compaction
+  const registry = new PatternRegistry(workDir);
+  const patterns = registry.list({});
+
+  // Step 5: Build the additionalContext string
+  let context = '=== Context Preserved by Session Continuity Engine ===\n';
+  context += 'Your session context was just compacted. Here\'s what you need to remember:\n\n';
+
+  // Add the briefing markdown
+  if (briefing && briefing.markdown) {
+    context += briefing.markdown + '\n\n';
+  }
+
+  // Add recent decisions
+  if (recentDecisions.length > 0) {
+    context += 'Key decisions this session:\n';
+    for (const d of recentDecisions) {
+      context += `- ${d.decision}`;
+      if (d.reason) context += ` (${d.reason})`;
+      context += '\n';
+    }
+    context += '\n';
+  }
+
+  // Add patterns
+  if (patterns.length > 0) {
+    context += 'Code patterns for this project:\n';
+    for (const p of patterns) {
+      context += `- ${p.rule}`;
+      if (p.context) context += ` [${p.context}]`;
+      context += '\n';
+    }
+    context += '\n';
+  }
+
+  context += '=== End Preserved Context ===';
+
+  return { additionalContext: context };
+}
+
+/**
+ * handleSessionEnd — Fires on Ctrl+C, /exit, error, or terminal close.
+ *
+ * Captures a final snapshot and prunes old snapshots (keeps last 20).
+ * This hook is async — it runs in the background and the session may
+ * terminate before it completes. The snapshot write is the priority;
+ * pruning is best-effort.
+ *
+ * @param {Object} input - The parsed hook JSON from Claude Code
+ * @param {string} input.working_directory - Absolute path to the project root
+ * @param {string} input.session_id - Unique session identifier
+ * @returns {Object} Always returns {} (async hook, no context injection)
+ */
+function handleSessionEnd(input) {
+  const workDir = input.working_directory;
+  const sessionId = input.session_id || 'session-end';
+  if (!workDir) return {};
+
+  // Step 1: Capture a full snapshot on exit
+  const snap = new SessionSnapshot(workDir);
+  snap.capture(sessionId, {
+    taskSummary: 'Auto-saved on session exit',
+    activeFiles: []
+  });
+
+  // Step 2: Prune old snapshots — keep the 20 most recent
+  // This is best-effort; if the process terminates before we finish, that's OK
+  try {
+    const MAX_SNAPSHOTS = 20;
+    const snapshotsDir = path.join(snap.getProjectDir(), 'snapshots');
+
+    if (fs.existsSync(snapshotsDir)) {
+      // Read all snapshot files
+      const files = fs.readdirSync(snapshotsDir)
+        .filter(f => f.startsWith('snap_') && f.endsWith('.json'));
+
+      // If we have more than MAX_SNAPSHOTS, delete the oldest ones
+      if (files.length > MAX_SNAPSHOTS) {
+        // Sort by filename (contains timestamp) ascending — oldest first
+        files.sort();
+
+        // Delete oldest files, keeping the most recent MAX_SNAPSHOTS
+        const toDelete = files.slice(0, files.length - MAX_SNAPSHOTS);
+        for (const file of toDelete) {
+          try {
+            fs.unlinkSync(path.join(snapshotsDir, file));
+          } catch (e) {
+            // Ignore delete errors — best-effort pruning
+          }
+        }
+      }
+    }
+  } catch (e) {
+    // Pruning failed — that's OK, the snapshot was already saved
+  }
+
+  return {};
+}
+
+// Export all handler functions
+module.exports = {
+  handleSessionStart,
+  handleStop,
+  handlePreCompact,
+  handleSessionEnd
+};