@ricky-stevens/context-guardian 2.1.0

package/lib/checkpoint.mjs

@@ -0,0 +1,258 @@
+/**
+ * Checkpoint creation and validation utilities.
+ *
+ * Provides the shared compaction pipeline: extract → cap → validate → save
+ * checkpoint file → compute stats. Used by the compact and prune skills
+ * (/cg:compact, /cg:prune) via compact-cli.mjs.
+ *
+ * @module checkpoint
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { loadConfig, resolveMaxTokens } from "./config.mjs";
+import { log } from "./logger.mjs";
+import {
+	CHECKPOINTS_DIR,
+	ensureDataDir,
+	rotateCheckpoints,
+	stateFile,
+} from "./paths.mjs";
+import { formatCompactionStats } from "./stats.mjs";
+import { estimateOverhead, estimateTokens, getTokenUsage } from "./tokens.mjs";
+import { extractConversation, extractRecent } from "./transcript.mjs";
+
+// ---------------------------------------------------------------------------
+// Content validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if extracted content has actual conversation data, not just
+ * headers, empty strings, or placeholder text.
+ *
+ * @param {string} text - Extracted checkpoint content
+ * @returns {boolean} True if the content contains real conversation
+ */
+export function hasExtractedContent(text) {
+	return (
+		text &&
+		text !== "(no transcript available)" &&
+		text.length > 50 &&
+		(text.includes("User:") || text.includes("Assistant:"))
+	);
+}
+
+// ---------------------------------------------------------------------------
+// Checkpoint size cap
+// ---------------------------------------------------------------------------
+
+/**
+ * Cap checkpoint content to prevent oversized additionalContext injections.
+ * Uses start+end trim: keeps the first half and last half, trims the middle.
+ *
+ * @param {string} content - The checkpoint text
+ * @param {number} maxTokens - The model's max token limit
+ * @returns {string} The original or trimmed content
+ */
+export function capCheckpointContent(content, maxTokens) {
+	// ~3.5 chars per token for English. Using 3x as conservative multiplier.
+	const maxChars = Math.max(50000, (maxTokens || 200000) * 3);
+	if (content.length <= maxChars) return content;
+	const half = Math.floor(maxChars / 2);
+	const trimmed = content.length - maxChars;
+	log(
+		`checkpoint-trimmed original=${content.length} kept=${maxChars} trimmed=${trimmed}`,
+	);
+	return (
+		content.slice(0, half) +
+		`\n\n> [${trimmed} chars trimmed from middle to fit context window]\n\n` +
+		content.slice(-half)
+	);
+}
+
+// ---------------------------------------------------------------------------
+// State file writer
+// ---------------------------------------------------------------------------
+
+/**
+ * Write a state file with post-compaction token estimates so
+ * /cg:stats works immediately after compaction.
+ *
+ * @param {string} sessionId - Current session ID
+ * @param {string} transcriptPath - Path to the transcript
+ * @param {number} tokens - Estimated token count
+ * @param {number} max - Max tokens for the model
+ * @param {string} rec - Recommendation text
+ */
+export function writeCompactionState(
+	sessionId,
+	transcriptPath,
+	tokens,
+	max,
+	rec,
+	{ payloadBytes = 0 } = {},
+) {
+	try {
+		const c = loadConfig();
+		const th = c.threshold ?? 0.35;
+		const p = tokens / max;
+
+		// Carry forward baseline_overhead from existing state
+		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 {}
+
+		ensureDataDir();
+		fs.writeFileSync(
+			stateFile(sessionId),
+			JSON.stringify({
+				current_tokens: tokens,
+				max_tokens: max,
+				pct: p,
+				pct_display: (p * 100).toFixed(1),
+				threshold: th,
+				threshold_display: Math.round(th * 100),
+				remaining_to_alert: Math.max(
+					0,
+					Math.round(
+						Math.round(th * 100) - Number.parseFloat((p * 100).toFixed(1)),
+					),
+				),
+				headroom: Math.max(0, Math.round(max * th - tokens)),
+				recommendation: rec,
+				source: "estimated",
+				model: "unknown",
+				smart_estimate_pct: 0,
+				recent_estimate_pct: 0,
+				baseline_overhead: baselineOverhead,
+				payload_bytes: payloadBytes,
+				session_id: sessionId,
+				transcript_path: transcriptPath,
+				ts: Date.now(),
+			}),
+		);
+	} catch (e) {
+		log(`writeCompactionState-error: ${e.message}`);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Shared compaction pipeline
+// ---------------------------------------------------------------------------
+
+/**
+ * Perform the full compaction pipeline: extract → cap → validate → save
+ * checkpoint → compute stats.
+ *
+ * Returns the stats block for display, or null if extraction produced
+ * no meaningful content (caller should handle the empty case).
+ *
+ * @param {object} opts
+ * @param {string} opts.mode - "smart" or "recent"
+ * @param {string} opts.transcriptPath - Path to the JSONL transcript
+ * @param {string} opts.sessionId - Current session ID
+ * @param {object} [opts.preStats] - Pre-compaction token counts { currentTokens, maxTokens }
+ * @returns {{ statsBlock: string, stats: object, checkpointPath: string } | null}
+ */
+export function performCompaction(opts) {
+	const { mode, transcriptPath, sessionId, preStats } = opts;
+	const label = mode === "smart" ? "Smart Compact" : "Keep Recent 10";
+
+	ensureDataDir();
+	fs.mkdirSync(CHECKPOINTS_DIR, { recursive: true });
+
+	// Generate checkpoint filename
+	const stamp = new Date().toISOString().replaceAll(/[:.]/g, "-").slice(0, 19);
+	const checkpointPath = path.join(
+		CHECKPOINTS_DIR,
+		`session-${stamp}-${sessionId.slice(0, 8)}.md`,
+	);
+
+	// Extract and cap content
+	const usage = getTokenUsage(transcriptPath);
+	const capMax = usage?.max_tokens || resolveMaxTokens() || 200000;
+	let content =
+		mode === "smart"
+			? extractConversation(transcriptPath)
+			: extractRecent(transcriptPath, 10);
+	content = capCheckpointContent(content, capMax);
+
+	if (!hasExtractedContent(content)) return null;
+
+	// Save checkpoint file
+	const fullCheckpoint = `# Context Checkpoint (${label})\n> Created: ${new Date().toISOString()}\n\n${content}`;
+	fs.writeFileSync(checkpointPath, fullCheckpoint);
+
+	// Also copy to .context-guardian/ for user visibility
+	try {
+		const cgDir = path.join(process.cwd(), ".context-guardian");
+		fs.mkdirSync(cgDir, { recursive: true });
+		const cgCheckpointPath = path.join(
+			cgDir,
+			`cg-checkpoint-${stamp}-${sessionId.slice(0, 8)}.md`,
+		);
+		fs.writeFileSync(cgCheckpointPath, fullCheckpoint);
+		// Rotate — keep last 5 checkpoint copies
+		const cpFiles = fs
+			.readdirSync(cgDir)
+			.filter((f) => f.startsWith("cg-checkpoint-") && f.endsWith(".md"))
+			.sort()
+			.reverse();
+		for (const f of cpFiles.slice(5)) {
+			try {
+				fs.unlinkSync(path.join(cgDir, f));
+			} catch {}
+		}
+	} catch (e) {
+		log(`checkpoint-copy-error: ${e.message}`);
+	}
+
+	// Compute stats
+	const preTokens =
+		preStats?.currentTokens ||
+		usage?.current_tokens ||
+		estimateTokens(transcriptPath);
+	const preMax = preStats?.maxTokens || usage?.max_tokens || resolveMaxTokens();
+
+	// Read baseline overhead from state file if available
+	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,
+	);
+
+	// Measure transcript file size for payload reporting
+	let prePayloadBytes = 0;
+	try {
+		prePayloadBytes = fs.statSync(transcriptPath).size;
+	} catch {}
+
+	const { stats, block: statsBlock } = formatCompactionStats(
+		preTokens,
+		preMax,
+		fullCheckpoint,
+		{ overhead, prePayloadBytes },
+	);
+
+	rotateCheckpoints();
+
+	log(
+		`checkpoint-saved mode=${mode} file=${checkpointPath} pre=${preTokens} post=${stats.postTokens} saved=${stats.saved}`,
+	);
+
+	return { statsBlock, stats, checkpointPath };
+}

package/lib/compact-cli.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for manual compaction via skills.
+ * Skills don't fire UserPromptSubmit, so this provides a direct path.
+ *
+ * Usage: node compact-cli.mjs <smart|recent|handoff> <session_id> <data_dir> [label]
+ * Output: single JSON line { success, statsBlock?, error? }
+ */
+
+// Set CLAUDE_PLUGIN_DATA before any module reads it (paths.mjs uses it at import time)
+const [mode, sessionId, dataDir, ...labelParts] = process.argv.slice(2);
+const label = labelParts.join(" ").trim() || "";
+if (dataDir) process.env.CLAUDE_PLUGIN_DATA = dataDir;
+
+const crypto = await import("node:crypto");
+const fs = await import("node:fs");
+const { performCompaction } = await import("./checkpoint.mjs");
+const { log } = await import("./logger.mjs");
+const { stateFile } = await import("./paths.mjs");
+
+function out(obj) {
+	process.stdout.write(JSON.stringify(obj));
+}
+
+if (mode !== "smart" && mode !== "recent" && mode !== "handoff") {
+	out({
+		success: false,
+		error: "Invalid mode. Use smart, recent, or handoff.",
+	});
+	process.exit(0);
+}
+
+let transcriptPath;
+try {
+	transcriptPath = JSON.parse(
+		fs.readFileSync(stateFile(sessionId), "utf8"),
+	).transcript_path;
+} catch {
+	out({ success: false, error: "No session data yet. Send a message first." });
+	process.exit(0);
+}
+
+if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+	out({ success: false, error: "Transcript not found." });
+	process.exit(0);
+}
+
+log(`compact-cli mode=${mode} session=${sessionId}`);
+
+// ---------------------------------------------------------------------------
+// Handoff mode — extract conversation and write to project dir for cross-
+// session continuity. Does not need /clear — handoff files persist across sessions.
+// ---------------------------------------------------------------------------
+if (mode === "handoff") {
+	const { performHandoff } = await import("./handoff.mjs");
+	const result = performHandoff({ transcriptPath, sessionId, label });
+	if (!result) {
+		out({
+			success: false,
+			error: "No extractable content. Try sending a few messages first.",
+		});
+		process.exit(0);
+	}
+	// Write synthetic JSONL for /resume cg:{label}
+	let handoffLabel;
+	try {
+		const { writeSyntheticSession } = await import("./synthetic-session.mjs");
+		handoffLabel =
+			label || new Date().toISOString().replaceAll(/[:.]/g, "-").slice(0, 19);
+		const { sessionUuid } = writeSyntheticSession({
+			checkpointContent: fs.readFileSync(result.handoffPath, "utf8"),
+			title: `cg:${handoffLabel}`,
+			type: "handoff",
+			projectCwd: process.cwd(),
+		});
+		log(`synthetic-session handoff uuid=${sessionUuid} label=${handoffLabel}`);
+	} catch (e) {
+		log(`synthetic-session-error: ${e.message}`);
+	}
+	const resumeTitle = `cg:${handoffLabel || "handoff"}`;
+	out({
+		success: true,
+		statsBlock: result.statsBlock,
+		resumeInstruction: `**To restore in a future session, type \`/resume ${resumeTitle}\`, or \`/resume\` to browse all sessions.**`,
+	});
+	process.exit(0);
+}
+
+const result = performCompaction({
+	mode,
+	transcriptPath,
+	sessionId,
+});
+
+if (!result) {
+	const alt = mode === "smart" ? "/cg:prune" : "/cg:compact";
+	out({ success: false, error: `No extractable content. Try ${alt} instead.` });
+	process.exit(0);
+}
+
+// Write synthetic JSONL for /resume cg:{hash}
+let resumeTitle = "cg";
+try {
+	const { writeSyntheticSession } = await import("./synthetic-session.mjs");
+	const shortHash = crypto.randomUUID().replaceAll("-", "").slice(0, 4);
+	resumeTitle = `cg:${shortHash}`;
+	const { sessionUuid } = writeSyntheticSession({
+		checkpointContent: fs.readFileSync(result.checkpointPath, "utf8"),
+		title: resumeTitle,
+		type: "compact",
+		projectCwd: process.cwd(),
+	});
+	log(`synthetic-session compact uuid=${sessionUuid}`);
+} catch (e) {
+	log(`synthetic-session-error: ${e.message}`);
+}
+
+// The resume instruction is a separate pre-formatted field so the SKILL.md
+// can display it in bold after the box — no template interpolation by Claude.
+out({
+	success: true,
+	statsBlock: result.statsBlock,
+	resumeInstruction: `**Type \`/resume ${resumeTitle}\` to restore the compacted session.**`,
+});