@ricky-stevens/context-guardian 2.1.0

package/lib/compact-output.mjs

@@ -0,0 +1,350 @@
+/**
+ * Post-processing optimisations for compacted checkpoint output.
+ *
+ * Applies information density improvements after extraction:
+ * - Strips phatic assistant filler (R4)
+ * - Strips operational noise like stats boxes (R3)
+ * - Groups consecutive tool notes into single lines (R2)
+ * - Detects and strips project root from paths (R1)
+ * - Merges bare tool result lines into previous message
+ *
+ * @module compact-output
+ */
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Assistant messages that are ONLY collapsible tool notes. */
+const COLLAPSIBLE_NOTE_RE =
+	/^(?:\*\*Assistant:\*\* )?→ (?:Read |Grep |Glob |Ran |Write |Serena: (?:find |get |search |list ))/;
+
+/** Phatic assistant filler — trivial responses that add no recall value. */
+const PHATIC_RE =
+	/^\*\*Assistant:\*\* (?:Confirmed[. —!]|Ready[. —!]|Starting all |Memories checked|Looking at the |Moving on to |Done[.!]|Got it[.!]|File (?:created|edited)[.!])/;
+
+/** Meta-tool invocations that are infrastructure, not session content. */
+const META_TOOL_RE =
+	/^→ (?:Tool: `?ToolSearch|Serena: list.memor|Serena: check.onboard)/;
+
+// ---------------------------------------------------------------------------
+// Noise detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Operational content that becomes meaningless after checkpoint restore.
+ */
+function isOperationalNoise(msg) {
+	const isAsst = msg.startsWith("**Assistant:**");
+	if (!isAsst && !msg.startsWith("→") && !msg.startsWith("←")) return false;
+
+	const text = msg.replace("**Assistant:** ", "");
+
+	// CG stats boxes
+	if (text.includes("Context Guardian Stats") && text.includes("┌"))
+		return true;
+	if (text.includes('"success":true') && text.includes("statsBlock"))
+		return true;
+	if (text.includes("Checkpoint saved") && text.includes("NOT applied"))
+		return true;
+	// CG operational tool calls
+	if (text.startsWith("→ Ran `date +%s`")) return true;
+	if (/^→ Read .*state-.*\.json/.test(text)) return true;
+	// Meta-tool invocations (ToolSearch, memory checks)
+	if (META_TOOL_RE.test(text)) return true;
+	if (META_TOOL_RE.test(msg)) return true;
+	// Diagnostics JSON output
+	if (/^\{?"checks"/.test(text) || /diagnostics\.mjs/.test(text)) return true;
+	if (/← \{"checks"/.test(msg)) return true;
+	// Bare diagnostics run
+	if (/^→ Ran.*diagnostics/.test(text)) return true;
+	return false;
+}
+
+// ---------------------------------------------------------------------------
+// Phase helpers (extracted for cognitive complexity)
+// ---------------------------------------------------------------------------
+
+/**
+ * Phase 1: Strip noise and meta-tool content.
+ * @param {string[]} messages
+ * @returns {string[]}
+ */
+function filterNoise(messages) {
+	return messages.filter((msg) => {
+		if (PHATIC_RE.test(msg) && msg.length < 200) return false;
+		if (isOperationalNoise(msg)) return false;
+		return true;
+	});
+}
+
+/**
+ * Classify an assistant message body as trivial (should be skipped).
+ * @param {string} body - The text after "**Assistant:** "
+ * @returns {boolean}
+ */
+function isTrivialAssistantBody(body) {
+	return (
+		!body || /^(?:Done\.?|Got it\.?|File (?:created|edited)\.?)$/i.test(body)
+	);
+}
+
+/**
+ * Decide whether an assistant line should merge without re-prefixing.
+ * @param {string} lastLine - Previous line in the exchange
+ * @returns {boolean}
+ */
+function shouldMergeAssistant(lastLine) {
+	return (
+		lastLine.startsWith("**Assistant:**") ||
+		/^[→←]/.test(lastLine) ||
+		/^[→←]/.test(lastLine.trim())
+	);
+}
+
+/**
+ * Handle a single assistant message within an exchange.
+ * Merges or prefixes based on previous line context.
+ * @param {string} msg - The raw message
+ * @param {object} current - The current exchange { lines: string[] }
+ * @returns {void}
+ */
+function handleAssistantLine(msg, current) {
+	const body = msg.slice(14).trim();
+	if (isTrivialAssistantBody(body)) return;
+
+	const lastLine = current.lines.at(-1);
+	if (shouldMergeAssistant(lastLine)) {
+		current.lines.push(body);
+	} else {
+		current.lines.push(`**Assistant:** ${body}`);
+	}
+}
+
+/**
+ * Handle a pre-first-user message (startup noise).
+ * @param {string} msg
+ * @param {object[]} exchanges
+ */
+function handlePreUserMessage(msg, exchanges) {
+	if (msg.length > 50 && !isOperationalNoise(msg)) {
+		if (!exchanges.length) exchanges.push({ lines: [] });
+		exchanges[0].lines.push(msg);
+	}
+}
+
+/**
+ * Phase 2: Group filtered messages into exchanges.
+ * An exchange = one User message + all following Asst/tool messages until next User.
+ * @param {string[]} filtered
+ * @returns {object[]}
+ */
+function groupIntoExchanges(filtered) {
+	const exchanges = [];
+	let current = null;
+
+	for (const msg of filtered) {
+		if (msg.startsWith("**User:**")) {
+			if (current) exchanges.push(current);
+			current = { lines: [msg] };
+		} else if (current) {
+			if (msg.startsWith("**Assistant:**")) {
+				handleAssistantLine(msg, current);
+			} else {
+				current.lines.push(msg);
+			}
+		} else {
+			handlePreUserMessage(msg, exchanges);
+		}
+	}
+	if (current) exchanges.push(current);
+	return exchanges;
+}
+
+/**
+ * Flush accumulated collapsible tool lines into the collapsed array.
+ * @param {string[]} toolBatch - Accumulated tool lines
+ * @param {string[]} collapsed - Output array
+ */
+function flushTools(toolBatch, collapsed) {
+	if (toolBatch.length === 0) return;
+	if (toolBatch.length === 1) {
+		collapsed.push(toolBatch[0]);
+	} else {
+		const items = toolBatch.map((t) =>
+			t.replace(/^→ /, "").replaceAll("`", "").trim(),
+		);
+		collapsed.push(`→ ${items.join("; ")}`);
+	}
+}
+
+/**
+ * Collapse consecutive collapsible tool lines in an exchange.
+ * @param {string[]} lines - Exchange lines
+ * @returns {string[]}
+ */
+function collapseToolLines(lines) {
+	const collapsed = [];
+	const toolBatch = [];
+
+	for (const line of lines) {
+		if (isCollapsibleToolLine(line)) {
+			toolBatch.push(extractToolLine(line));
+			continue;
+		}
+		flushTools(toolBatch, collapsed);
+		toolBatch.length = 0;
+		collapsed.push(line);
+	}
+	flushTools(toolBatch, collapsed);
+	return collapsed;
+}
+
+/**
+ * Check if a line is a collapsible single-line tool note.
+ * @param {string} line
+ * @returns {boolean}
+ */
+function isCollapsibleToolLine(line) {
+	if (
+		!COLLAPSIBLE_NOTE_RE.test(line) &&
+		!COLLAPSIBLE_NOTE_RE.test(`Asst: ${line}`)
+	) {
+		return false;
+	}
+	const toolLine = extractToolLine(line);
+	return toolLine.startsWith("→") && toolLine.split("\n").length <= 2;
+}
+
+/**
+ * Extract the tool portion of a line, stripping "Asst:" prefix if present.
+ * @param {string} line
+ * @returns {string}
+ */
+function extractToolLine(line) {
+	return line.startsWith("Asst:") ? line.slice(5).trim() : line;
+}
+
+/**
+ * Phase 4: Build output with [N] anchors and collapsed tool lines.
+ * @param {object[]} exchanges
+ * @returns {string[]}
+ */
+function buildAnchoredOutput(exchanges) {
+	const result = [];
+	let exchangeNum = 0;
+
+	for (const ex of exchanges) {
+		const hasUser = ex.lines.some((l) => l.startsWith("**User:**"));
+		if (hasUser) exchangeNum++;
+
+		const collapsed = collapseToolLines(ex.lines);
+		if (collapsed.length === 0) continue;
+
+		const anchor = hasUser ? `[${exchangeNum}] ` : "";
+		const firstLine = collapsed[0];
+		const rest = collapsed.slice(1);
+
+		const block = [`${anchor}${firstLine}`, ...rest].join("\n");
+		result.push(block);
+	}
+
+	return result;
+}
+
+// ---------------------------------------------------------------------------
+// Message compaction
+// ---------------------------------------------------------------------------
+
+/**
+ * Post-process messages for maximum information density.
+ * Groups messages into exchanges, strips noise, shortens prefixes,
+ * and adds [N] anchors for cross-reference with the Conversation Index.
+ *
+ * @param {string[]} messages - The formatted message strings
+ * @returns {string[]} Optimised exchange blocks (one entry per exchange)
+ */
+export function compactMessages(messages) {
+	if (messages.length === 0) return messages;
+
+	const filtered = filterNoise(messages);
+	const exchanges = groupIntoExchanges(filtered);
+	return buildAnchoredOutput(exchanges);
+}
+
+// ---------------------------------------------------------------------------
+// Project root detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Collect file paths from tool_use blocks in assistant messages.
+ * @param {string[]} lines - Raw JSONL lines
+ * @param {number} startIdx - First line to scan
+ * @returns {string[]}
+ */
+function collectToolPaths(lines, startIdx) {
+	const paths = [];
+	for (let i = startIdx; i < lines.length; i++) {
+		try {
+			const obj = JSON.parse(lines[i]);
+			if (obj.type !== "assistant" || !Array.isArray(obj.message?.content))
+				continue;
+			for (const b of obj.message.content) {
+				if (b.type !== "tool_use") continue;
+				const fp =
+					b.input?.file_path || b.input?.path || b.input?.relative_path || "";
+				if (fp.startsWith("/") && fp.split("/").filter(Boolean).length >= 3) {
+					paths.push(fp);
+				}
+			}
+		} catch {}
+	}
+	return paths;
+}
+
+/**
+ * Build a map of directory prefix → occurrence count from a list of paths.
+ * @param {string[]} paths
+ * @returns {Map<string, number>}
+ */
+function buildPrefixCounts(paths) {
+	const counts = new Map();
+	for (const p of paths) {
+		const parts = p.split("/");
+		for (let len = 3; len < parts.length; len++) {
+			const prefix = `${parts.slice(0, len).join("/")}/`;
+			counts.set(prefix, (counts.get(prefix) || 0) + 1);
+		}
+	}
+	return counts;
+}
+
+/**
+ * Select the longest prefix covering at least 70% of paths.
+ * @param {Map<string, number>} counts
+ * @returns {string}
+ */
+function selectBestPrefix(counts) {
+	const maxCount = Math.max(...counts.values());
+	const threshold = Math.floor(maxCount * 0.7);
+	let best = "";
+	for (const [prefix, count] of counts) {
+		if (count >= threshold && prefix.length > best.length) {
+			best = prefix;
+		}
+	}
+	return best && counts.get(best) >= 3 ? best : "";
+}
+
+/**
+ * Detect the project root directory from tool_use file paths in the transcript.
+ * Scans for Read/Edit/Write/Grep tool inputs and finds the most common
+ * directory prefix. Returns it with trailing slash, or empty string.
+ */
+export function detectProjectRoot(lines, startIdx) {
+	const paths = collectToolPaths(lines, startIdx);
+	if (paths.length < 3) return "";
+
+	const counts = buildPrefixCounts(paths);
+	return selectBestPrefix(counts);
+}

package/lib/config.mjs

@@ -0,0 +1,40 @@
+import fs from "node:fs";
+import { CONFIG_FILE } from "./paths.mjs";
+
+const DEFAULT_CONFIG = {
+	threshold: 0.35,
+	max_tokens: 200000,
+};
+
+// ---------------------------------------------------------------------------
+// Load / Save
+// ---------------------------------------------------------------------------
+
+let _cachedConfig = null;
+
+export function loadConfig() {
+	if (_cachedConfig) return _cachedConfig;
+	try {
+		_cachedConfig = {
+			...DEFAULT_CONFIG,
+			...JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8")),
+		};
+	} catch {
+		_cachedConfig = { ...DEFAULT_CONFIG };
+	}
+	return _cachedConfig;
+}
+
+// ---------------------------------------------------------------------------
+// Resolve max_tokens.
+//   1. Explicit max_tokens in config (covers most cases)
+//   2. Safe default (200K)
+//
+// The submit hook detects max_tokens from the model name in the transcript
+// (getTokenUsage in tokens.mjs). This config value is the initial fallback
+// before any assistant response provides real model info.
+// ---------------------------------------------------------------------------
+export function resolveMaxTokens() {
+	const cfg = loadConfig();
+	return cfg.max_tokens ?? 200000;
+}

package/lib/content.mjs

@@ -0,0 +1,33 @@
+/**
+ * Extract the first text string from a Claude message content field.
+ * Handles string, array-of-blocks, and null/undefined.
+ */
+export function flattenContent(content) {
+	if (!content) return "";
+	if (typeof content === "string") return content;
+	if (Array.isArray(content))
+		return content
+			.filter((b) => b.type === "text")
+			.map((b) => b.text)
+			.join("\n");
+	return "";
+}
+
+/**
+ * Count the byte size of message content (text + tool input).
+ * Used for token estimation when real counts are unavailable.
+ */
+export function contentBytesOf(content) {
+	if (!content) return 0;
+	if (typeof content === "string") return Buffer.byteLength(content, "utf8");
+	if (Array.isArray(content)) {
+		let sum = 0;
+		for (const b of content) {
+			if (b.text) sum += Buffer.byteLength(b.text, "utf8");
+			if (b.input) sum += Buffer.byteLength(JSON.stringify(b.input), "utf8");
+			if (b.content) sum += contentBytesOf(b.content);
+		}
+		return sum;
+	}
+	return 0;
+}

package/lib/diagnostics.mjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveDataDir } from "./paths.mjs";
+
+// ---------------------------------------------------------------------------
+// Diagnostics — lightweight health checks for /cg:stats.
+// Outputs JSON to stdout: { checks: [{name, ok, detail}...] }
+// Always exits 0 so it never breaks the skill.
+// ---------------------------------------------------------------------------
+
+// CLI args override env vars (skills run via Bash without plugin env).
+// But Claude often drops the args, so we auto-discover as much as possible.
+const argSessionId = process.argv[2] || process.env.CLAUDE_SESSION_ID || "";
+const argPluginRoot = process.argv[3] || process.env.CLAUDE_PLUGIN_ROOT || "";
+const argPluginData = process.argv[4] || process.env.CLAUDE_PLUGIN_DATA || "";
+
+// Plugin root: infer from this file's location (lib/diagnostics.mjs → parent dir)
+const pluginRoot = argPluginRoot || path.resolve(import.meta.dirname, "..");
+
+// Data dir: try CLI arg, env var, then discover any cg* dirs.
+// Scans both global (~/.claude/plugins/data/) and project-local (.claude/plugins/data/)
+// to handle all install scopes: user, project, local/inline.
+function discoverDataDirs() {
+	const dirs = [argPluginData, resolveDataDir()].filter(Boolean);
+	const scanRoots = [
+		path.join(os.homedir(), ".claude", "plugins", "data"),
+		path.join(process.cwd(), ".claude", "plugins", "data"),
+	];
+	for (const root of scanRoots) {
+		try {
+			for (const d of fs.readdirSync(root)) {
+				if (d.startsWith("cg")) {
+					dirs.push(path.join(root, d));
+				}
+			}
+		} catch {}
+	}
+	return [...new Set(dirs)];
+}
+const KNOWN_DATA_DIRS = discoverDataDirs();
+
+// Find the most recent state file across all known data dirs
+function findRecentState() {
+	let best = null;
+	for (const dir of KNOWN_DATA_DIRS) {
+		try {
+			for (const f of fs
+				.readdirSync(dir)
+				.filter((f) => f.startsWith("state-") && f.endsWith(".json"))) {
+				const fp = path.join(dir, f);
+				const stat = fs.statSync(fp);
+				if (!best || stat.mtimeMs > best.mtimeMs) {
+					best = {
+						path: fp,
+						mtimeMs: stat.mtimeMs,
+						dir,
+						sessionId: f.replace("state-", "").replace(".json", ""),
+					};
+				}
+			}
+		} catch {}
+	}
+	return best;
+}
+
+const recentState = findRecentState();
+const DATA_DIR = recentState?.dir || argPluginData || resolveDataDir();
+const sessionId = argSessionId || recentState?.sessionId || "unknown";
+const stateFile = (sid) =>
+	path.join(DATA_DIR, `state-${sid || "unknown"}.json`);
+
+const checks = [];
+
+function check(name, ok, detail) {
+	checks.push({ name, ok, detail });
+}
+
+// 1. Data directory writable
+try {
+	const tmp = path.join(DATA_DIR, `.diag-${Date.now()}`);
+	fs.writeFileSync(tmp, "ok");
+	fs.unlinkSync(tmp);
+	check("data_dir", true, DATA_DIR);
+} catch (e) {
+	check("data_dir", false, `Not writable: ${e.message}`);
+}
+
+// 2. State file present
+try {
+	const sf = stateFile(sessionId);
+	if (fs.existsSync(sf)) {
+		check("state_file", true, "Present");
+	} else {
+		check(
+			"state_file",
+			false,
+			"Missing — send a message first so hooks can write token counts",
+		);
+	}
+} catch (e) {
+	check("state_file", false, e.message);
+}
+
+// 3. Transcript readable
+try {
+	const sf = stateFile(sessionId);
+	if (fs.existsSync(sf)) {
+		const state = JSON.parse(fs.readFileSync(sf, "utf8"));
+		if (state.transcript_path && fs.existsSync(state.transcript_path)) {
+			check("transcript", true, "Readable");
+		} else if (state.transcript_path) {
+			check("transcript", false, `Not found: ${state.transcript_path}`);
+		} else {
+			check("transcript", false, "No transcript_path in state file");
+		}
+	} else {
+		check("transcript", false, "Skipped — no state file");
+	}
+} catch (e) {
+	check("transcript", false, e.message);
+}
+
+// 4. Plugin root exists
+if (fs.existsSync(pluginRoot)) {
+	check("plugin_root", true, pluginRoot);
+} else {
+	check("plugin_root", false, `Directory missing: ${pluginRoot}`);
+}
+
+// 5. Hook files present
+const hookFiles = [
+	"hooks/submit.mjs",
+	"hooks/stop.mjs",
+	"hooks/session-start.mjs",
+	"hooks/precompact.mjs",
+];
+const root = pluginRoot;
+const missingHooks = hookFiles.filter(
+	(h) => !fs.existsSync(path.join(root, h)),
+);
+if (missingHooks.length === 0) {
+	check("hooks", true, "All 4 hook files present");
+} else {
+	check("hooks", false, `Missing: ${missingHooks.join(", ")}`);
+}
+
+// 6. Marketplace directory exists
+try {
+	const knownPath = path.join(
+		os.homedir(),
+		".claude",
+		"plugins",
+		"known_marketplaces.json",
+	);
+	if (fs.existsSync(knownPath)) {
+		const known = JSON.parse(fs.readFileSync(knownPath, "utf8"));
+		const entry = known["context-guardian"];
+		if (entry) {
+			const mktDir = entry.installLocation;
+			if (fs.existsSync(mktDir)) {
+				check("marketplace", true, "Repository cache present");
+			} else {
+				check(
+					"marketplace",
+					false,
+					`Missing: ${mktDir} — run: /plugin marketplace add https://github.com/Ricky-Stevens/context-guardian`,
+				);
+			}
+		} else {
+			check(
+				"marketplace",
+				true,
+				"Not marketplace-installed (OK for local dev)",
+			);
+		}
+	} else {
+		check("marketplace", true, "No marketplace registry (OK for local dev)");
+	}
+} catch (e) {
+	check(
+		"marketplace",
+		false,
+		`Error reading marketplace registry: ${e.message}`,
+	);
+}
+
+// 7. Statusline configured — critical for CG since the statusline is the
+// sole UX for context pressure alerts (no blocking or menus).
+try {
+	const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
+	if (fs.existsSync(settingsPath)) {
+		const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+		if (settings.statusLine?.command?.includes("statusline.mjs")) {
+			check("statusline", true, "Configured");
+		} else if (settings.statusLine) {
+			check(
+				"statusline",
+				false,
+				"Another statusline is active — CG cannot display context warnings. Session-start will reclaim it on next restart.",
+			);
+		} else {
+			check(
+				"statusline",
+				false,
+				"Not configured — will be auto-configured on next session start",
+			);
+		}
+	} else {
+		check(
+			"statusline",
+			false,
+			"No settings.json found — will be auto-configured on next session start",
+		);
+	}
+} catch (e) {
+	check("statusline", false, e.message);
+}
+
+process.stdout.write(JSON.stringify({ checks }));