todo-enforcer 1.0.0

package/src/lib/hooks-manager.ts

@@ -0,0 +1,207 @@
+/**
+ * hooks-manager — Shared library for pi hook management
+ *
+ * Provides:
+ * - State persistence (global/local scope)
+ * - Hook registry (registerHook / isEnabled / getRegistry)
+ * - Toggle operations (addDisabled / removeDisabled)
+ */
+// @ts-nocheck
+
+// 
+
+// 
+
+// 
+
+
+import fs from "node:fs";
+import path from "node:path";
+import type { HookOrigin, HookRegistration, HookSource, HookState, Scope, StatePaths } from "./types";
+
+const STATE_FILE = "hooks-state.json";
+
+// ── Registry (in-memory, per-process, shared via globalThis) ────────────
+
+const GLOBAL_REGISTRY_KEY = "__PI_HOOKS_REGISTRY__" as const;
+const GLOBAL_DISABLED_KEY = "__PI_HOOKS_DISABLED__" as const;
+
+function getGlobalRegistry(): HookRegistration[] {
+  if (!(globalThis as any)[GLOBAL_REGISTRY_KEY]) {
+    (globalThis as any)[GLOBAL_REGISTRY_KEY] = [];
+  }
+  return (globalThis as any)[GLOBAL_REGISTRY_KEY];
+}
+
+function getGlobalDisabled(): Record<string, string[]> {
+  if (!(globalThis as any)[GLOBAL_DISABLED_KEY]) {
+    (globalThis as any)[GLOBAL_DISABLED_KEY] = {};
+  }
+  return (globalThis as any)[GLOBAL_DISABLED_KEY];
+}
+
+
+/** Register a hook's metadata. Called by each extension at load time. */
+export function registerHook(
+  extension: string,
+  event: string,
+  opts: { blocking?: boolean; source?: HookSource; origin?: HookOrigin } = {},
+): void {
+  // Avoid duplicates (extension + event combo)
+  const reg = getGlobalRegistry();
+  const exists = reg.some((r) => r.extension === extension && r.event === event);
+  if (!exists) {
+    reg.push({
+      extension,
+      event,
+      blocking: opts.blocking === true,
+      source: opts.source ?? "pi",
+      origin: opts.origin ?? "global",
+    });
+  }
+}
+
+/** Get all registered hooks. */
+export function getRegistry(): HookRegistration[] {
+  return [...getGlobalRegistry()];
+}
+
+/** Clear registry (for tests). */
+export function clearRegistry(): void {
+  getGlobalRegistry().length = 0;
+}
+
+/** Set the current disabled map. Called by pi-hooks-manager on state changes. */
+export function setCurrentDisabled(disabled: Record<string, string[]>): void {
+  (globalThis as any)[GLOBAL_DISABLED_KEY] = disabled;
+}
+
+/** Get the current disabled map (for tests/integration). */
+export function getCurrentDisabled(): Record<string, string[]> {
+  return getGlobalDisabled();
+}
+
+/** Check if a specific hook is enabled using the shared current disabled state. */
+export function isEnabled(extension: string, event: string): boolean {
+  const disabled = getGlobalDisabled();
+  const events = disabled[extension];
+  if (!events) return true;
+  return !events.includes(event);
+}
+
+/** Check if a specific hook is enabled given an explicit disabled map (for tests). */
+export function isEnabledWithState(extension: string, event: string, disabled: Record<string, string[]>): boolean {
+  const events = disabled[extension];
+  if (!events) return true;
+  return !events.includes(event);
+}
+
+// ── State Persistence ──────────────────────────────────────────────────
+
+function stateFilePath(dir: string): string {
+  return path.join(dir, STATE_FILE);
+}
+
+function readStateFile(dir: string): HookState | null {
+  const fp = stateFilePath(dir);
+  try {
+    if (!fs.existsSync(fp)) return null;
+    const raw = fs.readFileSync(fp, "utf-8");
+    const parsed = JSON.parse(raw);
+    return sanitizeState(parsed);
+  } catch {
+    return null;
+  }
+}
+
+function sanitizeState(raw: unknown): HookState {
+  if (!raw || typeof raw !== "object") return { scope: "global", disabled: {} };
+  const obj = raw as Record<string, unknown>;
+  const scope: Scope = obj.scope === "local" ? "local" : "global";
+  let disabled: Record<string, string[]>;
+  if (obj.disabled && typeof obj.disabled === "object" && !Array.isArray(obj.disabled)) {
+    disabled = {};
+    for (const [key, val] of Object.entries(obj.disabled as Record<string, unknown>)) {
+      if (Array.isArray(val) && val.every((v) => typeof v === "string")) {
+        disabled[key] = val;
+      }
+    }
+  } else {
+    disabled = {};
+  }
+  return { scope, disabled };
+}
+
+/** Load state from global and/or local files, merging as needed. */
+export function loadState(paths: StatePaths, scope: Scope): HookState {
+  const globalState = readStateFile(paths.globalDir);
+
+  if (scope === "global") {
+    return globalState ?? { scope: "global", disabled: {} };
+  }
+
+  // scope === "local": merge local over global
+  const localState = readStateFile(paths.localDir);
+
+  if (!globalState && !localState) {
+    return { scope: "local", disabled: {} };
+  }
+
+  if (!localState) {
+    return { ...globalState!, scope: "local" };
+  }
+
+  if (!globalState) {
+    return localState;
+  }
+
+  // Merge: local overrides global for same extension, global entries preserved if not in local
+  const merged: Record<string, string[]> = { ...globalState.disabled };
+  for (const [ext, events] of Object.entries(localState.disabled)) {
+    merged[ext] = events; // local takes precedence
+  }
+
+  return { scope: "local", disabled: merged };
+}
+
+/** Save state to the appropriate directory based on scope. */
+export function saveState(state: HookState, paths: StatePaths): void {
+  const dir = state.scope === "local" ? paths.localDir : paths.globalDir;
+  const fp = stateFilePath(dir);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(fp, JSON.stringify(state, null, 2), "utf-8");
+}
+
+/** Switch scope. Returns new state. Saves to new scope's file. */
+export function switchScope(current: HookState, newScope: Scope, paths: StatePaths): HookState {
+  if (current.scope === newScope) return current;
+
+  // Load the target scope's existing state
+  const targetState = loadState(paths, newScope);
+  saveState(targetState, paths);
+  return targetState;
+}
+
+// ── Toggle Operations ──────────────────────────────────────────────────
+
+/** Add an event to the disabled list for an extension. Idempotent. */
+export function addDisabled(state: HookState, extension: string, event: string): void {
+  if (!state.disabled[extension]) {
+    state.disabled[extension] = [];
+  }
+  if (!state.disabled[extension].includes(event)) {
+    state.disabled[extension].push(event);
+  }
+}
+
+/** Remove an event from the disabled list for an extension. Removes key if empty. */
+export function removeDisabled(state: HookState, extension: string, event: string): void {
+  const events = state.disabled[extension];
+  if (!events) return;
+  const idx = events.indexOf(event);
+  if (idx === -1) return;
+  events.splice(idx, 1);
+  if (events.length === 0) {
+    delete state.disabled[extension];
+  }
+}

package/src/lib/plugin-logger.ts

@@ -0,0 +1,155 @@
+// @ts-nocheck
+// 
+// 
+// 
+import {
+	appendFileSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+
+export type PluginLogLevel = "debug" | "info" | "warn" | "error";
+
+export interface PluginLoggerOptions {
+	baseDir?: string;
+	filePath?: string;
+	maxBytes?: number;
+	mirrorToConsole?: boolean;
+}
+
+export interface PluginLogger {
+	readonly name: string;
+	readonly filePath: string;
+	debug(message: string, details?: unknown): void;
+	info(message: string, details?: unknown): void;
+	warn(message: string, details?: unknown): void;
+	error(message: string, details?: unknown): void;
+}
+
+const DEFAULT_BASE_DIR = resolve(homedir(), ".pi", "logs", "extensions");
+const DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
+const TRIM_TARGET_RATIO = 0.8;
+
+function sanitizeFileName(name: string): string {
+	return (
+		name
+			.trim()
+			.toLowerCase()
+			.replace(/[^a-z0-9._-]+/g, "-")
+			.replace(/-{2,}/g, "-")
+			.replace(/^-+|-+$/g, "") || "plugin"
+	);
+}
+
+function normalizeDetails(details: unknown): string {
+	if (details === undefined) return "";
+	if (details instanceof Error) {
+		return JSON.stringify({
+			name: details.name,
+			message: details.message,
+			stack: details.stack,
+		});
+	}
+	if (typeof details === "string") return details;
+	try {
+		return JSON.stringify(details);
+	} catch (error) {
+		return String(details);
+	}
+}
+
+function buildLine(
+	name: string,
+	level: PluginLogLevel,
+	message: string,
+	details?: unknown,
+): string {
+	const suffix = normalizeDetails(details);
+	return `${new Date().toISOString()} [${name}] ${level.toUpperCase()} ${message}${suffix ? ` ${suffix}` : ""}\n`;
+}
+
+function trimFileToLimit(filePath: string, maxBytes: number): void {
+	if (!existsSync(filePath)) return;
+	const stats = statSync(filePath);
+	if (stats.size <= maxBytes) return;
+	const targetBytes = Math.max(1, Math.floor(maxBytes * TRIM_TARGET_RATIO));
+	const buffer = readFileSync(filePath);
+	const start = Math.max(0, buffer.length - targetBytes);
+	let trimmed = buffer.subarray(start);
+	const newlineIndex = trimmed.indexOf(0x0a);
+	if (newlineIndex >= 0 && newlineIndex < trimmed.length - 1) {
+		trimmed = trimmed.subarray(newlineIndex + 1);
+	}
+	writeFileSync(filePath, trimmed);
+}
+
+function appendLine(filePath: string, line: string, maxBytes: number): void {
+	mkdirSync(dirname(filePath), { recursive: true });
+	if (existsSync(filePath)) {
+		const currentSize = statSync(filePath).size;
+		const incomingSize = Buffer.byteLength(line);
+		if (currentSize + incomingSize > maxBytes) {
+			trimFileToLimit(filePath, Math.max(incomingSize, maxBytes));
+		}
+	}
+	appendFileSync(filePath, line, "utf8");
+	trimFileToLimit(filePath, maxBytes);
+}
+
+function mirror(level: PluginLogLevel, line: string): void {
+	const text = line.trimEnd();
+	if (level === "error") {
+		console.error(text);
+		return;
+	}
+	if (level === "warn") {
+		console.warn(text);
+		return;
+	}
+	console.log(text);
+}
+
+export function createPluginLogger(
+	name: string,
+	options: PluginLoggerOptions = {},
+): PluginLogger {
+	const filePath = options.filePath
+		? resolve(options.filePath)
+		: resolve(
+				options.baseDir ?? DEFAULT_BASE_DIR,
+				`${sanitizeFileName(name)}.log`,
+			);
+	const maxBytes = Math.max(1, options.maxBytes ?? DEFAULT_MAX_BYTES);
+	const mirrorToConsole = options.mirrorToConsole ?? false;
+
+	const write = (
+		level: PluginLogLevel,
+		message: string,
+		details?: unknown,
+	): void => {
+		const line = buildLine(name, level, message, details);
+		try {
+			appendLine(filePath, line, maxBytes);
+		} catch (error) {
+			const fallback = buildLine(name, "error", "log-write-failed", error);
+			console.error(fallback.trimEnd());
+		}
+		if (mirrorToConsole) {
+			mirror(level, line);
+		}
+	};
+
+	return {
+		name,
+		filePath,
+		debug: (message, details) => write("debug", message, details),
+		info: (message, details) => write("info", message, details),
+		warn: (message, details) => write("warn", message, details),
+		error: (message, details) => write("error", message, details),
+	};
+}

package/src/lib/types.ts

@@ -0,0 +1,59 @@
+/**
+ * pi-hooks-manager — Type definitions
+ */
+// @ts-nocheck
+
+// 
+
+// 
+
+// 
+
+
+/** Persistence scope for hook state */
+export type Scope = "global" | "local";
+
+/** Hook source — where the hook conceptually originates from */
+export type HookSource = "pi" | "claude";
+
+/** Hook origin — where the extension is loaded from */
+export type HookOrigin = "global" | "local" | "package";
+
+/** A registered hook's metadata */
+export interface HookRegistration {
+  /** Extension name (directory/file name) */
+  extension: string;
+  /** Pi event name (e.g., "tool_call", "session_start") */
+  event: string;
+  /** Whether this hook can block the main workflow */
+  blocking: boolean;
+  /** Where the hook conceptually originates: native pi or Claude Code adapter */
+  source: HookSource;
+  /** Where the extension is loaded from: global (~/.pi/agent/), local (.pi/), or package */
+  origin: HookOrigin;
+}
+
+/** Persisted state of disabled hooks */
+export interface HookState {
+  /** Current persistence scope */
+  scope: Scope;
+  /** Map of extension name → array of disabled event names */
+  disabled: Record<string, string[]>;
+}
+
+/** Options for state operations */
+export interface StatePaths {
+  /** Global state directory (e.g., ~/.pi/agent/) */
+  globalDir: string;
+  /** Local state directory (e.g., .pi/) */
+  localDir: string;
+}
+
+/** Parsed /hooks command */
+export type ParsedCommand =
+  | { action: "list" }
+  | { action: "enable"; extension: string; event?: string }
+  | { action: "disable"; extension: string; event?: string }
+  | { action: "status" }
+  | { action: "scope"; scope: Scope }
+  | { action: "unknown"; raw: string };

package/src/message-stall.ts

@@ -0,0 +1,188 @@
+/**
+ * message-stall — Reusable stall guard for todo-enforcer
+ *
+ * Prevents the enforcer from flooding the session with repeated or
+ * high-frequency messages. Two stall conditions:
+ *
+ * 1. **Repeated message guard**: If the same exact message is about to
+ *    be sent for the 3rd consecutive time, stall it.
+ *    - Reset when a DIFFERENT message arrives (new problem → fresh start).
+ *
+ * 2. **Rate limit**: If 5 messages have been sent within a 60-minute window,
+ *    stall additional messages until the window expires.
+ *
+ * Usage:
+ *   const { stalled, reason } = checkMessageStall(sessionId, message);
+ *   if (stalled) { log("stalled", reason); return; }
+ *   // ... proceed to deliver message ...
+ *
+ * Call resetStallState(sessionId) on session_start to clear tracking.
+ */
+// @ts-nocheck
+
+// 
+
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface StallState {
+	/** Last message content that was checked (not stalled). */
+	lastMessage: string | null;
+
+	/** How many consecutive times the same message has been seen. */
+	repeatCount: number;
+
+	/** Timestamps of all delivered (non-stalled) messages for rate-limit tracking. */
+	messageTimestamps: number[];
+}
+
+export interface StallResult {
+	/** Whether the message should be stalled (not sent). */
+	stalled: boolean;
+
+	/** Reason for stalling: "repeated_message" | "rate_limit" | null. */
+	reason: "repeated_message" | "rate_limit" | null;
+}
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+/** Consecutive identical messages before stalling. */
+const REPEAT_THRESHOLD = 3;
+
+/** Stall when this many messages have been delivered in the window. */
+const RATE_LIMIT_STALL_AT = 5;
+
+/** Rate-limit window duration in ms (60 minutes). */
+const RATE_LIMIT_WINDOW_MS = 60 * 60 * 1000;
+
+// ─── State store ─────────────────────────────────────────────────────────────
+
+const stallStates = new Map<string, StallState>();
+
+function getOrCreate(sessionId: string): StallState {
+	let state = stallStates.get(sessionId);
+	if (!state) {
+		state = {
+			lastMessage: null,
+			repeatCount: 0,
+			messageTimestamps: [],
+		};
+		stallStates.set(sessionId, state);
+	}
+	return state;
+}
+
+// ─── Time abstraction (testable) ─────────────────────────────────────────────
+
+let _getTime: () => number = () => Date.now();
+
+/**
+ * Override time source for testing. Returns the previous getter.
+ * Production code should NOT call this.
+ */
+export function stubGetTime(fn: () => number): () => number {
+	const prev = _getTime;
+	_getTime = fn;
+	return prev;
+}
+
+/** Reset time source to default. */
+export function resetGetTime(): void {
+	_getTime = () => Date.now();
+}
+
+// ─── Internal helpers ────────────────────────────────────────────────────────
+
+/**
+ * Prune timestamps outside the rate-limit window.
+ * Returns the pruned array (mutates in place).
+ */
+function pruneOldTimestamps(timestamps: number[], now: number): void {
+	const cutoff = now - RATE_LIMIT_WINDOW_MS;
+	while (timestamps.length > 0 && timestamps[0] < cutoff) {
+		timestamps.shift();
+	}
+}
+
+/**
+ * Fingerprint a message by its first non-empty line.
+ *
+ * Defense against the death-spiral: if {{latest_user_message}} in the prompt
+ * template echoes the previous injection, every successive message is longer
+ * than the last and exact-string equality never holds. The first line is the
+ * stable rule-determined prefix (e.g. "You have incomplete tasks. ..."), so
+ * fingerprinting on it lets the repeat-stall fire regardless of nested growth.
+ */
+function fingerprint(message: string): string {
+	for (const line of message.split("\n")) {
+		const trimmed = line.trim();
+		if (trimmed) return trimmed;
+	}
+	return "";
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Check if a message should be stalled.
+ *
+ * Call this BEFORE delivering the message. If stalled=true, do NOT send.
+ *
+ * If not stalled, this function records the message for future tracking.
+ */
+export function checkMessageStall(
+	sessionId: string,
+	message: string,
+): StallResult {
+	const state = getOrCreate(sessionId);
+	const now = _getTime();
+
+	// ── Check 1: Repeated message ─────────────────────────────────────
+	// Compare by first-line fingerprint so growing nested content (the
+	// enforcer's own injection echoed back via {{latest_user_message}}) is
+	// still caught as a repeat.
+	const fp = fingerprint(message);
+	const lastFp = state.lastMessage === null ? null : fingerprint(state.lastMessage);
+	if (lastFp !== null && lastFp === fp) {
+		state.repeatCount++;
+		// Keep lastMessage in sync with the most recent content so callers
+		// inspecting state see the actual last seen message.
+		state.lastMessage = message;
+		if (state.repeatCount >= REPEAT_THRESHOLD) {
+			return { stalled: true, reason: "repeated_message" };
+		}
+	} else {
+		// Different fingerprint → reset repeat counter
+		state.lastMessage = message;
+		state.repeatCount = 1;
+	}
+
+	// ── Check 2: Rate limit ───────────────────────────────────────────
+	pruneOldTimestamps(state.messageTimestamps, now);
+	// If we've already recorded RATE_LIMIT_MAX-1 messages, the next one is the Nth and should be stalled.
+	// (We record AFTER passing this check, so at the time of check, timestamps.length is the count of prior sends.)
+	if (state.messageTimestamps.length >= RATE_LIMIT_STALL_AT - 1) {
+		return { stalled: true, reason: "rate_limit" };
+	}
+
+	// ── Not stalled → record this message ─────────────────────────────
+	state.messageTimestamps.push(now);
+
+	return { stalled: false, reason: null };
+}
+
+/**
+ * Reset all stall state for a session.
+ * Call on session_start or manual reset.
+ */
+export function resetStallState(sessionId: string): void {
+	stallStates.delete(sessionId);
+}
+
+/**
+ * Reset all stall state for all sessions.
+ * Useful for testing.
+ */
+export function resetAllStallState(): void {
+	stallStates.clear();
+}