@ricky-stevens/context-guardian 2.1.0

package/lib/handoff.mjs

@@ -0,0 +1,329 @@
+/**
+ * Session handoff — save extracted conversation to a project-local file
+ * so a future session can pick up where you left off.
+ *
+ * Writes to .context-guardian/ in the project root for visibility.
+ * Synthetic JSONL sessions are also created for `/resume cg:{label}` access.
+ *
+ * @module handoff
+ */
+
+import { Buffer } from "node:buffer";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveMaxTokens } from "./config.mjs";
+import { log } from "./logger.mjs";
+import { stateFile } from "./paths.mjs";
+import { estimateOverhead, getTokenUsage } from "./tokens.mjs";
+import { extractConversation } from "./transcript.mjs";
+
+/** Directory name for CG artifacts in the project root */
+export const CG_DIR_NAME = ".context-guardian";
+
+// ---------------------------------------------------------------------------
+// Perform handoff
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a handoff file from the current session transcript.
+ *
+ * @param {object} opts
+ * @param {string} opts.transcriptPath - Path to the JSONL transcript
+ * @param {string} opts.sessionId - Current session ID
+ * @param {string} [opts.label] - Optional user-provided name for the handoff
+ * @returns {{ statsBlock: string, handoffPath: string } | null}
+ */
+export function performHandoff({ transcriptPath, sessionId, label = "" }) {
+	if (!transcriptPath || !fs.existsSync(transcriptPath)) return null;
+
+	const content = extractConversation(transcriptPath);
+	if (
+		!content ||
+		content === "(no transcript available)" ||
+		content.includes("Messages preserved: 0")
+	) {
+		return null;
+	}
+
+	const projectDir = process.cwd();
+	const cgDir = path.join(projectDir, CG_DIR_NAME);
+	fs.mkdirSync(cgDir, { recursive: true });
+
+	const stamp = new Date().toISOString().replaceAll(/[:.]/g, "-").slice(0, 19);
+	// Slugify label for filename: lowercase, replace non-alphanumeric with dashes, trim
+	const slug = label
+		? `${label
+				.toLowerCase()
+				.replaceAll(/[^a-z0-9]+/g, "-")
+				.replaceAll(/^-|-$/g, "")
+				.slice(0, 50)}-`
+		: "";
+	const handoffPath = path.join(cgDir, `cg-handoff-${slug}${stamp}.md`);
+
+	const labelLine = label ? `\n> Label: ${label}` : "";
+	const fullContent = `# Session Handoff\n> Created: ${new Date().toISOString()}\n> Session: ${sessionId}${labelLine}\n\n${content}`;
+	fs.writeFileSync(handoffPath, fullContent);
+
+	// Rotate old handoff files (keep last 5)
+	rotateFiles(cgDir, "cg-handoff-", 5);
+
+	// Compute stats
+	const usage = getTokenUsage(transcriptPath);
+	const preTokens =
+		usage?.current_tokens || Math.round(Buffer.byteLength(content, "utf8") / 4);
+	const maxTokens = usage?.max_tokens || resolveMaxTokens() || 200000;
+	const postTokens = Math.round(Buffer.byteLength(fullContent, "utf8") / 4);
+
+	let baselineOverhead = 0;
+	try {
+		const sf = stateFile(sessionId);
+		if (fs.existsSync(sf)) {
+			const prev = JSON.parse(fs.readFileSync(sf, "utf8"));
+			baselineOverhead = prev.baseline_overhead ?? 0;
+		}
+	} catch {}
+
+	const overhead = estimateOverhead(
+		preTokens,
+		transcriptPath,
+		baselineOverhead,
+	);
+	const effectivePost = postTokens + overhead;
+	const saved = Math.max(0, preTokens - effectivePost);
+	const savedPct =
+		preTokens > 0 ? ((saved / preTokens) * 100).toFixed(1) : "0.0";
+	const prePct =
+		maxTokens > 0 ? ((preTokens / maxTokens) * 100).toFixed(1) : "?";
+	const postPct =
+		maxTokens > 0 ? ((effectivePost / maxTokens) * 100).toFixed(1) : "0.0";
+
+	// Measure transcript file size + system overhead for session size reporting
+	let prePayloadBytes = 0;
+	try {
+		prePayloadBytes = fs.statSync(transcriptPath).size;
+	} catch {}
+	const overheadBytes = overhead * 4;
+	const totalPreBytes = prePayloadBytes + overheadBytes;
+	const postPayloadBytes = Buffer.byteLength(fullContent, "utf8");
+
+	const lines = [
+		`┌──────────────────────────────────────────────────────────────────────────────────────────────────`,
+		`│  Session Handoff`,
+		`│`,
+		`│  Before:  ${preTokens.toLocaleString()} tokens (~${prePct}% of context)`,
+		`│  After:   ~${effectivePost.toLocaleString()} tokens (~${postPct}% of context)`,
+		`│  Saved:   ~${saved.toLocaleString()} tokens (${savedPct}% reduction)`,
+	];
+	if (totalPreBytes > 0) {
+		lines.push(
+			`│  Session: ${Math.max(0.1, totalPreBytes / (1024 * 1024)).toFixed(1)}MB → ${Math.max(0.1, postPayloadBytes / (1024 * 1024)).toFixed(1)}MB`,
+		);
+	}
+	lines.push(
+		`│`,
+		`│  Saved to: ${handoffPath}`,
+		`│`,
+		`└──────────────────────────────────────────────────────────────────────────────────────────────────`,
+	);
+	const statsBlock = lines.join("\n");
+
+	log(
+		`handoff-saved session=${sessionId} file=${handoffPath} pre=${preTokens} post=${effectivePost}`,
+	);
+
+	return { statsBlock, handoffPath };
+}
+
+// ---------------------------------------------------------------------------
+// List available restore files
+// ---------------------------------------------------------------------------
+
+/**
+ * Scan .context-guardian/ for handoff and checkpoint files.
+ * Returns them sorted newest-first with metadata parsed from headers.
+ *
+ * @param {string} projectDir - Project root directory
+ * @returns {Array<{ path: string, filename: string, type: string, created: string, goal: string, size: number }>}
+ */
+export function listRestoreFiles(
+	projectDir,
+	{ includeCheckpoints = false } = {},
+) {
+	const cgDir = path.join(projectDir, CG_DIR_NAME);
+	if (!fs.existsSync(cgDir)) return [];
+
+	const files = [];
+	for (const f of fs.readdirSync(cgDir)) {
+		let type = null;
+		if (f.startsWith("cg-handoff-") && f.endsWith(".md")) type = "handoff";
+		else if (
+			includeCheckpoints &&
+			f.startsWith("cg-checkpoint-") &&
+			f.endsWith(".md")
+		)
+			type = "checkpoint";
+		if (!type) continue;
+
+		const fullPath = path.join(cgDir, f);
+		try {
+			const stat = fs.statSync(fullPath);
+			const head = readFileHead(fullPath, 512);
+			const created = parseCreatedDate(head) || stat.mtime.toISOString();
+			const label = parseLabel(head);
+			const goal = parseGoal(head);
+			const sizeKB = Math.round(stat.size / 1024);
+
+			files.push({
+				path: fullPath,
+				filename: f,
+				type,
+				created,
+				label,
+				goal,
+				size: sizeKB,
+			});
+		} catch {
+			// Skip unreadable files
+		}
+	}
+
+	// Sort newest first
+	files.sort((a, b) => b.created.localeCompare(a.created));
+
+	// Limit: 10 per type
+	if (includeCheckpoints) {
+		const handoffs = files.filter((f) => f.type === "handoff").slice(0, 10);
+		const checkpoints = files
+			.filter((f) => f.type === "checkpoint")
+			.slice(0, 10);
+		return [...handoffs, ...checkpoints].sort((a, b) =>
+			b.created.localeCompare(a.created),
+		);
+	}
+	return files.slice(0, 10);
+}
+
+/**
+ * Format the restore menu for display.
+ *
+ * @param {Array} files - From listRestoreFiles()
+ * @returns {string} Formatted menu text
+ */
+export function formatRestoreMenu(files, { showType = false } = {}) {
+	if (files.length === 0) {
+		return [
+			`┌──────────────────────────────────────────────────────────────────────────`,
+			`│  No saved sessions found in .context-guardian/`,
+			`│  Run /cg:handoff [name] to save your current session.`,
+			`└──────────────────────────────────────────────────────────────────────────`,
+		].join("\n");
+	}
+
+	const lines = [
+		`┌──────────────────────────────────────────────────────────────────────────`,
+		`│  Previous Sessions`,
+		`├──────────────────────────────────────────────────────────────────────────`,
+	];
+
+	for (let i = 0; i < files.length; i++) {
+		const f = files[i];
+		const date = formatDate(f.created);
+		const goalDisplay = f.label || f.goal || "no description";
+		const typeLabel = f.type === "handoff" ? "HANDOFF" : "CHECKPOINT";
+		const typeSuffix = showType ? ` [${typeLabel}]` : "";
+		lines.push(
+			`│  [${i + 1}]  ${goalDisplay} (${date} · ${f.size}KB)${typeSuffix}`,
+		);
+	}
+
+	lines.push(
+		`│`,
+		`│  Reply with a number to restore, or continue to start a new session.`,
+		`└──────────────────────────────────────────────────────────────────────────`,
+	);
+
+	return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function readFileHead(filePath, bytes) {
+	const fd = fs.openSync(filePath, "r");
+	try {
+		const buf = Buffer.alloc(bytes);
+		const bytesRead = fs.readSync(fd, buf, 0, bytes, 0);
+		return buf.toString("utf8", 0, bytesRead);
+	} finally {
+		fs.closeSync(fd);
+	}
+}
+
+function parseCreatedDate(head) {
+	const m = head.match(/> Created: (.+)/);
+	return m ? m[1].trim() : null;
+}
+
+function parseLabel(head) {
+	const m = head.match(/> Label: (.+)/);
+	return m ? m[1].trim() : null;
+}
+
+function parseGoal(head) {
+	const m = head.match(/Goal: (.+)/);
+	if (!m) return null;
+	const goal = m[1].trim();
+	return goal === "[not available]" ? null : goal;
+}
+
+function formatDate(isoString) {
+	try {
+		const d = new Date(isoString);
+		const now = new Date();
+		const diffMs = now - d;
+		const diffM = Math.round(diffMs / (60 * 1000));
+		const diffH = Math.round(diffMs / (60 * 60 * 1000));
+
+		if (diffM < 1) return "just now";
+		if (diffM === 1) return "1 minute ago";
+		if (diffM < 60) return `${diffM} minutes ago`;
+		if (diffH === 1) return "1 hour ago";
+		if (diffH < 24) return `${diffH} hours ago`;
+		const diffD = Math.round(diffH / 24);
+		if (diffD === 1) return "yesterday";
+		return `${diffD} days ago`;
+	} catch {
+		return isoString;
+	}
+}
+
+/**
+ * Rotate files matching a prefix, keeping the most recent N.
+ */
+export function rotateFiles(dir, prefix, maxKeep) {
+	try {
+		const files = fs
+			.readdirSync(dir)
+			.filter((f) => f.startsWith(prefix) && f.endsWith(".md"));
+
+		// Sort by file mtime (newest first) — filename sort is unreliable
+		// when labels are prepended before the timestamp.
+		files.sort((a, b) => {
+			try {
+				return (
+					fs.statSync(path.join(dir, b)).mtimeMs -
+					fs.statSync(path.join(dir, a)).mtimeMs
+				);
+			} catch {
+				return 0;
+			}
+		});
+
+		for (const f of files.slice(maxKeep)) {
+			try {
+				fs.unlinkSync(path.join(dir, f));
+			} catch {}
+		}
+	} catch {}
+}

package/lib/logger.mjs

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+import { LOG_DIR, LOG_FILE } from "./paths.mjs";
+
+const MAX_LOG_SIZE = 5 * 1024 * 1024; // 5 MiB
+
+/**
+ * Append a timestamped line to the shared log file.
+ * Silently swallows errors — logging must never break the hook.
+ * Rotates the log file when it exceeds MAX_LOG_SIZE.
+ */
+let logDirReady = false;
+
+export function log(msg) {
+	try {
+		if (!logDirReady) {
+			fs.mkdirSync(LOG_DIR, { recursive: true });
+			logDirReady = true;
+		}
+		// Rotate if log exceeds size limit
+		try {
+			if (
+				fs.existsSync(LOG_FILE) &&
+				fs.statSync(LOG_FILE).size > MAX_LOG_SIZE
+			) {
+				const rotated = `${LOG_FILE}.1`;
+				try {
+					fs.unlinkSync(rotated);
+				} catch {}
+				fs.renameSync(LOG_FILE, rotated);
+			}
+		} catch {}
+		fs.appendFileSync(LOG_FILE, `[${new Date().toISOString()}] ${msg}\n`);
+	} catch {}
+}

package/lib/mcp-tools.mjs

@@ -0,0 +1,200 @@
+/**
+ * MCP tool summarisation rules for specific server integrations.
+ *
+ * Handles Serena, Sequential Thinking, Context-mode, Context7, and
+ * unknown MCP tools. Each server has tailored rules that preserve
+ * high-value content while removing re-obtainable noise.
+ *
+ * @module mcp-tools
+ */
+
+import { startEndTrim } from "./trim.mjs";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Maximum chars for sequential thinking thoughts before start+end trim. */
+const THOUGHT_LIMIT = 2000;
+/** Maximum chars for write content before start+end trim. */
+const WRITE_LIMIT = 3000;
+// ---------------------------------------------------------------------------
+// MCP tool use dispatch
+// ---------------------------------------------------------------------------
+
+/**
+ * Summarise an MCP tool_use block based on server and tool name.
+ *
+ * @param {string} name - Full MCP tool name (e.g. "mcp__serena__find_symbol")
+ * @param {object} input - The tool input object
+ * @param {function} indent - Indent helper function
+ * @param {function} summarizeUnknown - Fallback for unknown tools
+ * @returns {string|null} Formatted summary, or null to remove
+ */
+export function summarizeMcpToolUse(name, input, indent, summarizeUnknown) {
+	if (name.includes("__serena__"))
+		return summarizeSerenaTool(name, input, indent);
+	if (name.includes("__sequential-thinking__"))
+		return summarizeThinking(name, input);
+	if (name.includes("context-mode")) return summarizeContextMode(name, input);
+	if (name.includes("__context7__")) {
+		return `→ Docs: \`${input?.libraryName || input?.query || name}\``;
+	}
+	return summarizeUnknown(name, input);
+}
+
+// ---------------------------------------------------------------------------
+// Serena rules
+// ---------------------------------------------------------------------------
+
+/**
+ * Summarise a Serena MCP tool based on the specific operation.
+ * Write tools preserve code changes; read/query tools are note-only.
+ *
+ * @param {string} name - Full tool name
+ * @param {object} input - Tool input
+ * @param {function} indent - Indent helper
+ * @returns {string|null} Formatted summary, or null to remove
+ */
+function summarizeSerenaTool(name, input, indent) {
+	const toolName = name.split("__").pop();
+
+	// Write operations — preserve code changes like Edit/Write
+	if (toolName === "replace_symbol_body") {
+		const body = input?.new_body || "";
+		const sym = input?.name_path || input?.symbol_name || "unknown";
+		const file = input?.relative_path || "";
+		const trimmed = startEndTrim(body, WRITE_LIMIT);
+		return `→ Serena: replaced \`${sym}\` in \`${file}\`:\n${indent(trimmed, 4)}`;
+	}
+	if (
+		toolName === "insert_after_symbol" ||
+		toolName === "insert_before_symbol"
+	) {
+		const body = input?.code || input?.body || "";
+		const sym = input?.name_path || "";
+		const trimmed = startEndTrim(body, WRITE_LIMIT);
+		const dir = toolName.includes("after") ? "after" : "before";
+		return `→ Serena: inserted ${dir} \`${sym}\`:\n${indent(trimmed, 4)}`;
+	}
+	if (toolName === "rename_symbol") {
+		return `→ Serena: renamed \`${input?.old_name || ""}\` → \`${input?.new_name || ""}\``;
+	}
+
+	// Memory operations — externally persisted, note only
+	if (toolName === "write_memory" || toolName === "edit_memory") {
+		return `→ Serena: wrote memory \`${input?.name || input?.title || ""}\``;
+	}
+	if (
+		["read_memory", "list_memories", "rename_memory", "delete_memory"].includes(
+			toolName,
+		)
+	) {
+		return `→ Serena: ${toolName.replaceAll("_", " ")}`;
+	}
+
+	// Setup/onboarding — noise
+	if (
+		[
+			"onboarding",
+			"check_onboarding_performed",
+			"initial_instructions",
+		].includes(toolName)
+	) {
+		return null;
+	}
+
+	// Read/query operations — re-obtainable, note only
+	const query =
+		input?.name_path || input?.pattern || input?.relative_path || "";
+	const label = toolName.replaceAll("_", " ");
+	const querySuffix = query ? ` \`${query}\`` : "";
+	return `→ Serena: ${label}${querySuffix}`;
+}
+
+// ---------------------------------------------------------------------------
+// Sequential Thinking rules
+// ---------------------------------------------------------------------------
+
+/**
+ * Summarise a sequential thinking tool call.
+ * The thought field IS the reasoning chain — preserve it.
+ */
+function summarizeThinking(_name, input) {
+	const thought = input?.thought || "";
+	const step = input?.thoughtNumber || "?";
+	const total = input?.totalThoughts || "?";
+	const trimmed = startEndTrim(thought, THOUGHT_LIMIT);
+	return `→ Thinking (step ${step}/${total}): ${trimmed}`;
+}
+
+// ---------------------------------------------------------------------------
+// Context-mode rules
+// ---------------------------------------------------------------------------
+
+/**
+ * Summarise a context-mode tool call.
+ * Results are sandbox-internal — assistant text has the summary.
+ */
+function summarizeContextMode(name, input) {
+	if (name.includes("batch_execute")) {
+		const n = Array.isArray(input?.commands) ? input.commands.length : "?";
+		return `→ Context-mode: batch executed ${n} commands`;
+	}
+	if (name.includes("execute")) {
+		return `→ Context-mode: executed ${input?.language || "code"}`;
+	}
+	if (name.includes("search")) {
+		const queries = Array.isArray(input?.queries)
+			? input.queries.join(", ")
+			: "";
+		return `→ Context-mode: searched ${queries}`;
+	}
+	if (name.includes("fetch_and_index")) {
+		return `→ Context-mode: fetched \`${input?.url || ""}\``;
+	}
+	// index, stats — operational noise
+	return null;
+}
+
+// ---------------------------------------------------------------------------
+// Serena tool classification (used by tool_result handling)
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if a tool name is a Serena read/query operation.
+ * @param {string} name - Tool name
+ * @returns {boolean}
+ */
+export function isSerenaReadTool(name) {
+	if (!name?.includes("serena")) return false;
+	const tool = name.split("__").pop();
+	return [
+		"find_symbol",
+		"get_symbols_overview",
+		"search_for_pattern",
+		"list_dir",
+		"find_file",
+		"find_referencing_symbols",
+		"read_memory",
+		"list_memories",
+	].includes(tool);
+}
+
+/**
+ * Check if a tool name is a Serena write operation.
+ * @param {string} name - Tool name
+ * @returns {boolean}
+ */
+export function isSerenaWriteTool(name) {
+	if (!name?.includes("serena")) return false;
+	const tool = name.split("__").pop();
+	return [
+		"replace_symbol_body",
+		"insert_after_symbol",
+		"insert_before_symbol",
+		"rename_symbol",
+		"write_memory",
+		"edit_memory",
+	].includes(tool);
+}

package/lib/paths.mjs

@@ -0,0 +1,90 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// ---------------------------------------------------------------------------
+// Plugin data directory — persistent storage that survives plugin updates.
+// Falls back to ~/.claude/cg/ for standalone / local testing.
+// ---------------------------------------------------------------------------
+/** Resolve the data directory at call time, not import time.
+ * This allows tests to set CLAUDE_PLUGIN_DATA after paths.mjs is first imported. */
+export function resolveDataDir() {
+	return (
+		process.env.CLAUDE_PLUGIN_DATA || path.join(os.homedir(), ".claude", "cg")
+	);
+}
+
+/** @deprecated Use resolveDataDir() for call-time resolution. Kept for backwards compat. */
+export const DATA_DIR = resolveDataDir();
+
+// ---------------------------------------------------------------------------
+// Logging
+// ---------------------------------------------------------------------------
+export const LOG_DIR = path.join(os.homedir(), ".claude", "logs");
+export const LOG_FILE = path.join(LOG_DIR, "cg.log");
+
+// ---------------------------------------------------------------------------
+// Persistent state files (plugin-scoped, survive /clear)
+// ---------------------------------------------------------------------------
+export const CONFIG_FILE = path.join(resolveDataDir(), "config.json");
+export const CHECKPOINTS_DIR = path.join(resolveDataDir(), "checkpoints");
+
+// Session-scoped state file — each session writes its own token counts
+// so multiple concurrent sessions don't clobber each other.
+export function stateFile(sessionId) {
+	return path.join(resolveDataDir(), `state-${sessionId || "unknown"}.json`);
+}
+
+// Fixed fallback location for statusline reads. The statusline process doesn't
+// receive CLAUDE_PLUGIN_DATA, so it always reads from ~/.claude/cg/.
+// Hooks write here in addition to the primary data dir.
+export const STATUSLINE_STATE_DIR = path.join(os.homedir(), ".claude", "cg");
+
+export function statuslineStateFile(sessionId) {
+	return path.join(
+		STATUSLINE_STATE_DIR,
+		`state-${sessionId || "unknown"}.json`,
+	);
+}
+
+// ---------------------------------------------------------------------------
+// Ensure the data directory exists on first use.
+// ---------------------------------------------------------------------------
+export function ensureDataDir() {
+	fs.mkdirSync(resolveDataDir(), { recursive: true });
+}
+
+/**
+ * Atomic write — writes to a temp file then renames. Prevents partial/corrupt
+ * state files on crash, disk full, or concurrent access. Rename is atomic on
+ * POSIX systems when source and target are on the same filesystem.
+ *
+ * @param {string} filePath - Target file path
+ * @param {string} data - Content to write
+ */
+export function atomicWriteFileSync(filePath, data) {
+	const tmp = `${filePath}.${process.pid}.${Date.now()}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+	fs.writeFileSync(tmp, data);
+	fs.renameSync(tmp, filePath);
+}
+
+// ---------------------------------------------------------------------------
+// Rotate checkpoint files — keep only the most recent N.
+// Files are named session-YYYY-MM-DDTHH-MM-SS-<hash>.md, so alphabetical
+// sort gives chronological order.
+// ---------------------------------------------------------------------------
+export function rotateCheckpoints(maxKeep = 10) {
+	try {
+		const files = fs
+			.readdirSync(CHECKPOINTS_DIR)
+			.filter((f) => f.startsWith("session-") && f.endsWith(".md"))
+			.sort()
+			.reverse(); // newest first
+		for (const f of files.slice(maxKeep)) {
+			try {
+				fs.unlinkSync(path.join(CHECKPOINTS_DIR, f));
+			} catch {}
+		}
+	} catch {}
+}