@goodfoot/agent-hooks 1.0.0

package/dist/core/logger.js

@@ -0,0 +1,508 @@
+/**
+ * Logger system for agent hooks.
+ *
+ * Provides structured logging with event subscription and optional file output.
+ * The logger is **silent by default** to avoid interfering with hook protocol
+ * (stdout is reserved for JSON responses, stderr may conflict with the host
+ * CLI).
+ * @module
+ * @example
+ * ```typescript
+ * import { logger } from '@goodfoot/agent-hooks';
+ *
+ * // Subscribe to log events
+ * const unsubscribe = logger.on('error', (event) => {
+ *   console.error(`Error in ${event.hookType}: ${event.message}`);
+ * });
+ *
+ * // Later, clean up
+ * unsubscribe();
+ * ```
+ */
+import { closeSync, existsSync, mkdirSync, openSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+/**
+ * All log levels in order of severity (lowest to highest).
+ */
+export const LOG_LEVELS = ["debug", "info", "warn", "error"];
+// ============================================================================
+// Logger Class
+// ============================================================================
+/**
+ * Logger for agent hooks with event subscription and file output.
+ *
+ * ## Key Behaviors
+ *
+ * | Configuration | Behavior |
+ * |--------------|----------|
+ * | No config (default) | **Silent** - no output anywhere |
+ * | `AGENT_HOOKS_LOG_FILE` env var | Append JSON lines to file |
+ * | `.on(level, handler)` registered | Events delivered to handlers only |
+ * | Multiple destinations | All destinations receive events |
+ *
+ * ## Important Notes
+ *
+ * - **Never outputs to stdout** (reserved for JSON hook response)
+ * - **Never outputs to stderr** (may interfere with host CLI error handling)
+ * - File output uses JSON Lines format for easy parsing
+ * - `.on(level, handler)` returns an unsubscribe function
+ * @example
+ * ```typescript
+ * import { logger } from '@goodfoot/agent-hooks';
+ *
+ * // Subscribe to events at specific level
+ * logger.on('warn', (event) => {
+ *   sendAlert(event.message);
+ * });
+ *
+ * // Log within a hook handler
+ * export default preToolUseHook({ matcher: 'Bash' }, async (input, { logger }) => {
+ *   logger.warn('About to validate Bash command');
+ *   return preToolUseOutput({ allow: true });
+ * });
+ * ```
+ */
+export class Logger {
+    /**
+     * Registered event handlers by log level.
+     */
+    handlers = new Map();
+    /**
+     * File descriptor for log file output.
+     * Lazily initialized on first write.
+     */
+    logFileFd = null;
+    /**
+     * Path to the log file, if configured.
+     */
+    logFilePath = null;
+    /**
+     * Whether file initialization has been attempted.
+     */
+    fileInitialized = false;
+    /**
+     * Current hook context for enriching log events.
+     */
+    currentHookType;
+    /**
+     * Current hook input for enriching log events.
+     */
+    currentInput;
+    /**
+     * Creates a new Logger instance.
+     *
+     * Typically you should use the exported `logger` singleton rather than
+     * creating new instances.
+     * @param config - Optional configuration
+     * @example
+     * ```typescript
+     * // Use singleton (recommended)
+     * import { logger } from '@goodfoot/agent-hooks';
+     *
+     * // Or create custom instance
+     * const customLogger = new Logger({ logFilePath: '/var/log/hooks.log' });
+     * ```
+     */
+    constructor(config = {}) {
+        // Initialize handlers map for each level
+        for (const level of LOG_LEVELS) {
+            this.handlers.set(level, new Set());
+        }
+        // Set log file path from explicit config, or by reading the configured env var
+        this.logFilePath = config.logFilePath ?? (config.logEnvVar ? process.env[config.logEnvVar] : undefined) ?? null;
+    }
+    /**
+     * Logs a debug message.
+     *
+     * Use for detailed debugging information that is typically only useful
+     * during development or troubleshooting.
+     * @param message - The debug message
+     * @param context - Optional additional context
+     * @example
+     * ```typescript
+     * logger.debug('Processing tool input', { toolName: 'Bash', inputSize: 256 });
+     * ```
+     */
+    debug(message, context) {
+        this.emit("debug", message, context);
+    }
+    /**
+     * Logs an info message.
+     *
+     * Use for general operational events like hook invocations, successful
+     * completions, or state changes.
+     * @param message - The info message
+     * @param context - Optional additional context
+     * @example
+     * ```typescript
+     * logger.info('Session started', { source: 'startup', sessionId: 'abc123' });
+     * ```
+     */
+    info(message, context) {
+        this.emit("info", message, context);
+    }
+    /**
+     * Logs a warning message.
+     *
+     * Use for conditions that may indicate issues but don't prevent
+     * operation, such as deprecated patterns or performance concerns.
+     * @param message - The warning message
+     * @param context - Optional additional context
+     * @example
+     * ```typescript
+     * logger.warn('Deprecated hook pattern detected', { pattern: 'legacyMatcher' });
+     * ```
+     */
+    warn(message, context) {
+        this.emit("warn", message, context);
+    }
+    /**
+     * Logs an error message.
+     *
+     * Use for error conditions that require attention but were handled
+     * gracefully. For exceptions, prefer {@link logError}.
+     * @param message - The error message
+     * @param context - Optional additional context
+     * @example
+     * ```typescript
+     * logger.error('Failed to validate tool input', { toolName: 'Bash', reason: 'empty command' });
+     * ```
+     */
+    error(message, context) {
+        this.emit("error", message, context);
+    }
+    /**
+     * Logs a structured error with full error details.
+     *
+     * Use this method when logging caught exceptions to capture the full
+     * error context including name, message, stack trace, and cause chain.
+     * @param error - The error to log
+     * @param message - Human-readable description of what failed
+     * @param context - Optional additional context
+     * @example
+     * ```typescript
+     * try {
+     *   await dangerousOperation();
+     * } catch (err) {
+     *   logger.logError(err, 'Failed to execute dangerous operation', {
+     *     operation: 'delete',
+     *     target: '/important/file.txt'
+     *   });
+     * }
+     * ```
+     */
+    logError(error, message, context) {
+        const errorInfo = this.extractErrorInfo(error);
+        const event = {
+            timestamp: new Date().toISOString(),
+            level: "error",
+            hookType: this.currentHookType,
+            message,
+            input: this.currentInput,
+            error: errorInfo,
+            context,
+        };
+        this.deliverEvent(event);
+    }
+    /**
+     * Subscribes a handler to log events at the specified level.
+     *
+     * The handler will be called for every log event at the specified level.
+     * Returns an unsubscribe function that should be called when the handler
+     * is no longer needed.
+     * @param level - The log level to subscribe to
+     * @param handler - The handler function to call for each event
+     * @returns A function to unsubscribe the handler
+     * @example
+     * ```typescript
+     * // Subscribe to error events
+     * const unsubscribe = logger.on('error', (event) => {
+     *   console.error(`[${event.hookType}] ${event.message}`);
+     *   if (event.error) {
+     *     console.error(event.error.stack);
+     *   }
+     * });
+     *
+     * // Later, clean up
+     * unsubscribe();
+     * ```
+     * @example
+     * ```typescript
+     * // Forward to external logging library
+     * import pino from 'pino';
+     * const pinoLogger = pino();
+     *
+     * logger.on('info', (event) => pinoLogger.info(event, event.message));
+     * logger.on('warn', (event) => pinoLogger.warn(event, event.message));
+     * logger.on('error', (event) => pinoLogger.error(event, event.message));
+     * ```
+     */
+    on(level, handler) {
+        const levelHandlers = this.handlers.get(level);
+        if (levelHandlers) {
+            levelHandlers.add(handler);
+        }
+        return () => {
+            levelHandlers?.delete(handler);
+        };
+    }
+    /**
+     * Sets the current hook context for enriching log events.
+     *
+     * This is called internally by the runtime before invoking hook handlers.
+     * You typically don't need to call this directly.
+     * @param hookType - The agent event name being executed
+     * @param input - The hook input data
+     * @internal
+     */
+    setContext(hookType, input) {
+        this.currentHookType = hookType;
+        this.currentInput = input;
+    }
+    /**
+     * Clears the current hook context.
+     *
+     * Called internally by the runtime after hook execution completes.
+     * @internal
+     */
+    clearContext() {
+        this.currentHookType = undefined;
+        this.currentInput = undefined;
+    }
+    /**
+     * Configures the log file path at runtime.
+     *
+     * Call this to enable or change file logging. Setting to `null` disables
+     * file logging (but doesn't close existing file handle immediately).
+     * @param filePath - Path to the log file, or null to disable
+     * @example
+     * ```typescript
+     * // Enable file logging at runtime
+     * logger.setLogFile('/var/log/agent-hooks.log');
+     *
+     * // Disable file logging
+     * logger.setLogFile(null);
+     * ```
+     */
+    setLogFile(filePath) {
+        // Close existing file if open
+        if (this.logFileFd !== null) {
+            try {
+                closeSync(this.logFileFd);
+            }
+            catch (closeError) {
+                process.stderr.write(`[agent-hooks] Failed to close log file: ${String(closeError)}\n`);
+            }
+            this.logFileFd = null;
+        }
+        this.logFilePath = filePath;
+        this.fileInitialized = false;
+    }
+    /**
+     * Closes all resources held by the logger.
+     *
+     * Call this during graceful shutdown to ensure all log data is flushed.
+     * @example
+     * ```typescript
+     * process.on('exit', () => {
+     *   logger.close();
+     * });
+     * ```
+     */
+    close() {
+        if (this.logFileFd !== null) {
+            try {
+                closeSync(this.logFileFd);
+            }
+            catch (closeError) {
+                process.stderr.write(`[agent-hooks] Failed to close log file: ${String(closeError)}\n`);
+            }
+            this.logFileFd = null;
+        }
+        this.fileInitialized = false;
+    }
+    /**
+     * Checks if there are any active handlers or destinations.
+     *
+     * Returns true if any handlers are registered or file logging is enabled.
+     * @returns Whether the logger has any active output destinations
+     */
+    hasDestinations() {
+        for (const handlers of this.handlers.values()) {
+            if (handlers.size > 0)
+                return true;
+        }
+        return this.logFilePath !== null;
+    }
+    // ============================================================================
+    // Private Methods
+    // ============================================================================
+    /**
+     * Emits a log event.
+     * @param level - The severity level of the event
+     * @param message - The log message
+     * @param context - Optional additional context data
+     */
+    emit(level, message, context) {
+        const event = {
+            timestamp: new Date().toISOString(),
+            level,
+            hookType: this.currentHookType,
+            message,
+            input: this.currentInput,
+            context,
+        };
+        this.deliverEvent(event);
+    }
+    /**
+     * Delivers an event to all registered destinations.
+     * @param event - The log event to deliver
+     */
+    deliverEvent(event) {
+        // Deliver to event handlers
+        const levelHandlers = this.handlers.get(event.level);
+        if (levelHandlers) {
+            for (const handler of levelHandlers) {
+                try {
+                    handler(event);
+                }
+                catch (handlerError) {
+                    process.stderr.write(`[agent-hooks] Log handler error: ${String(handlerError)}\n`);
+                }
+            }
+        }
+        // Write to file if configured
+        this.writeToFile(event);
+    }
+    /**
+     * Writes an event to the log file.
+     * @param event - The log event to write
+     */
+    writeToFile(event) {
+        if (!this.logFilePath)
+            return;
+        // Lazy initialization of file handle
+        if (!this.fileInitialized) {
+            this.initializeFile();
+        }
+        if (this.logFileFd === null)
+            return;
+        try {
+            const line = `${JSON.stringify(event)}\n`;
+            writeSync(this.logFileFd, line);
+        }
+        catch (writeError) {
+            // Disable file logging after a write failure to avoid repeated errors
+            this.logFileFd = null;
+            this.fileInitialized = false;
+            process.stderr.write(`[agent-hooks] Log file write failed: ${String(writeError)}\n`);
+        }
+    }
+    /**
+     * Initializes the log file for writing.
+     */
+    initializeFile() {
+        this.fileInitialized = true;
+        if (!this.logFilePath)
+            return;
+        try {
+            // Ensure directory exists
+            const dir = dirname(this.logFilePath);
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+            // Open file for appending
+            this.logFileFd = openSync(this.logFilePath, "a");
+        }
+        catch {
+            // Silently ignore file initialization errors
+            this.logFileFd = null;
+        }
+    }
+    /**
+     * Extracts structured error information from an unknown error.
+     * @param error - The error to extract information from
+     * @returns Structured error information
+     */
+    extractErrorInfo(error) {
+        if (error instanceof Error) {
+            const info = {
+                name: error.name,
+                message: error.message,
+                stack: error.stack,
+            };
+            // Extract cause chain if present
+            if (error.cause !== undefined) {
+                info.cause = this.extractErrorInfo(error.cause);
+            }
+            return info;
+        }
+        // Handle non-Error values
+        return {
+            name: "UnknownError",
+            message: String(error),
+        };
+    }
+}
+// ============================================================================
+// Singleton Export
+// ============================================================================
+/**
+ * Global logger instance for agent hooks.
+ *
+ * Use this singleton for all logging within hooks. The logger is configured
+ * via environment variables and supports event subscription for custom
+ * destinations.
+ *
+ * ## Configuration
+ *
+ * | Environment Variable | Description |
+ * |---------------------|-------------|
+ * | `AGENT_HOOKS_LOG_FILE` | Path to log file (JSON Lines format) |
+ *
+ * ## Usage in Hooks
+ *
+ * The logger is passed to hook handlers via context for convenience:
+ *
+ * ```typescript
+ * export default preToolUseHook({ matcher: 'Bash' }, async (input, { logger }) => {
+ *   logger.warn('Validating Bash command');
+ *   return preToolUseOutput({ allow: true });
+ * });
+ * ```
+ *
+ * ## External Integration
+ *
+ * Subscribe to events to forward logs to external systems:
+ *
+ * ```typescript
+ * import { logger } from '@goodfoot/agent-hooks';
+ * import pino from 'pino';
+ *
+ * const pinoLogger = pino({ level: 'debug' });
+ *
+ * logger.on('debug', (event) => pinoLogger.debug(event, event.message));
+ * logger.on('info', (event) => pinoLogger.info(event, event.message));
+ * logger.on('warn', (event) => pinoLogger.warn(event, event.message));
+ * logger.on('error', (event) => pinoLogger.error(event, event.message));
+ * ```
+ * @example
+ * ```typescript
+ * // Direct usage
+ * import { logger } from '@goodfoot/agent-hooks';
+ *
+ * logger.info('Starting operation');
+ * logger.warn('Resource limit approaching', { usage: 0.9 });
+ *
+ * try {
+ *   await riskyOperation();
+ * } catch (err) {
+ *   logger.logError(err, 'Risky operation failed');
+ * }
+ * ```
+ */
+// AGENT_HOOKS_LOG_ENV_VAR is set unconditionally by the --log-env-var banner
+// before this module initialises. If absent, fall back to the default env var name.
+export const logger = new Logger({
+    logEnvVar: process.env.AGENT_HOOKS_LOG_ENV_VAR ?? "AGENT_HOOKS_LOG_FILE",
+});

package/dist/core/stdin.js

@@ -0,0 +1,38 @@
+/**
+ * Stdin acquisition and JSON parsing for agent hooks.
+ *
+ * Both source runtimes (`claude-code-hooks`, `codex-hooks`) read stdin and
+ * parse JSON identically; this module is that shared logic. Wire rules for
+ * what a parse failure *means* belong to each agent's transport — core only
+ * classifies the outcome.
+ * @module
+ */
+/**
+ * Reads all data from stdin.
+ * @returns Promise resolving to the complete stdin content
+ */
+export async function readStdin() {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        // Set encoding first to ensure data events receive strings
+        process.stdin.setEncoding("utf-8");
+        process.stdin.on("data", (chunk) => {
+            chunks.push(chunk);
+        });
+        process.stdin.on("end", () => {
+            resolve(chunks.join(""));
+        });
+        process.stdin.on("error", (error) => {
+            reject(error);
+        });
+    });
+}
+/**
+ * Parses stdin JSON input.
+ * @param stdinContent - Raw stdin content
+ * @returns Parsed input in the host CLI's wire format
+ * @throws SyntaxError if JSON is malformed
+ */
+export function parseStdinJson(stdinContent) {
+    return JSON.parse(stdinContent);
+}