@agiflowai/hooks-adapter 0.0.0

package/README.md

@@ -0,0 +1,123 @@
+# @agiflowai/hooks-adapter
+
+Hook adapters for normalizing AI agent hook formats (Claude Code, Gemini, etc.). This library provides a unified interface for handling hooks from different AI coding agents.
+
+## Installation
+
+```bash
+pnpm add @agiflowai/hooks-adapter
+```
+
+## Usage
+
+### Basic Hook Execution
+
+```typescript
+import { AdapterProxyService, PRE_TOOL_USE, POST_TOOL_USE } from '@agiflowai/hooks-adapter';
+import { CLAUDE_CODE } from '@agiflowai/coding-agent-bridge';
+
+// Define your hook callback
+const myPreToolUseHook = async (context) => {
+  console.log('Tool:', context.toolName);
+  console.log('File:', context.filePath);
+
+  return {
+    decision: 'allow',
+    message: 'Proceeding with operation',
+  };
+};
+
+// Execute the hook
+await AdapterProxyService.execute(CLAUDE_CODE, PRE_TOOL_USE, myPreToolUseHook);
+```
+
+### Hook Types
+
+The library exports two hook type constants:
+
+- `PRE_TOOL_USE` - Hook that runs before a tool is executed
+- `POST_TOOL_USE` - Hook that runs after a tool is executed
+
+### Hook Context
+
+The normalized `HookContext` passed to callbacks includes:
+
+```typescript
+interface HookContext {
+  toolName: string;        // Name of the tool (e.g., "Read", "Write", "Edit")
+  toolInput: Record<string, any>;  // Input parameters
+  filePath?: string;       // File path for file operations
+  operation?: 'read' | 'write' | 'edit';  // Operation type
+  cwd: string;             // Current working directory
+  sessionId: string;       // Unique session identifier
+  llmTool?: string;        // Optional LLM tool identifier
+}
+```
+
+### Hook Response
+
+Callbacks should return a `HookResponse`:
+
+```typescript
+interface HookResponse {
+  decision: 'allow' | 'deny' | 'ask' | 'skip';  // Permission decision
+  message: string;         // Message for the LLM
+  userMessage?: string;    // Optional message for the user only
+  updatedInput?: Record<string, any>;  // Optional updated input parameters
+}
+```
+
+### Decision Types
+
+- `allow` - Allow the operation to proceed
+- `deny` - Block the operation
+- `ask` - Ask the user for confirmation
+- `skip` - Skip the hook silently (no output)
+
+## Adapters
+
+### ClaudeCodeAdapter
+
+Adapter for Claude Code PreToolUse hooks. Parses Claude Code's JSON stdin format and formats responses accordingly.
+
+### ClaudeCodePostToolUseAdapter
+
+Adapter for Claude Code PostToolUse hooks. Handles post-execution hook format with tool response data.
+
+### BaseAdapter
+
+Abstract base class for creating custom adapters. Implements the Template Method pattern for hook execution flow.
+
+## Services
+
+### AdapterProxyService
+
+Routes hook execution to the appropriate adapter based on agent and hook type.
+
+```typescript
+AdapterProxyService.execute(agentName, hookType, callback);
+```
+
+### ExecutionLogService
+
+Tracks hook executions to prevent duplicate actions within a session.
+
+```typescript
+// Check if already executed
+const executed = await ExecutionLogService.hasExecuted(sessionId, filePath, decision);
+
+// Log an execution
+await ExecutionLogService.logExecution({
+  sessionId,
+  filePath,
+  operation: 'read',
+  decision: 'allow',
+});
+
+// Check if file has changed since last execution
+const changed = await ExecutionLogService.hasFileChanged(sessionId, filePath, decision);
+```
+
+## License
+
+AGPL-3.0

package/dist/index.cjs

@@ -0,0 +1,513 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let node_fs_promises = require("node:fs/promises");
+node_fs_promises = __toESM(node_fs_promises);
+let node_path = require("node:path");
+node_path = __toESM(node_path);
+let node_os = require("node:os");
+node_os = __toESM(node_os);
+let node_crypto = require("node:crypto");
+node_crypto = __toESM(node_crypto);
+let __agiflowai_coding_agent_bridge = require("@agiflowai/coding-agent-bridge");
+
+//#region src/constants/index.ts
+/**
+* @agiflowai/hooks-adapter - Constants
+*
+* DESIGN PATTERNS:
+* - Strongly-typed constant exports for compile-time safety
+* - Immutable by default (as const assertions)
+*
+* CODING STANDARDS:
+* - Primitive constants: UPPER_SNAKE_CASE
+* - Always include JSDoc with purpose and usage
+*
+* AVOID:
+* - Mutable exports (let, var)
+* - Magic strings without explanation
+*/
+/**
+* Hook type identifiers for different hook events
+*/
+const PRE_TOOL_USE = "PreToolUse";
+const POST_TOOL_USE = "PostToolUse";
+
+//#endregion
+//#region src/adapters/BaseAdapter.ts
+/**
+* Abstract base adapter for normalizing AI agent hook formats
+*/
+var BaseAdapter = class {
+	/**
+	* Execute hook callback with normalized context
+	* Template method that orchestrates the hook execution flow
+	*
+	* @param callback - Hook callback function to execute
+	*/
+	async execute(callback) {
+		try {
+			const stdin = await this.readStdin();
+			const response = await callback(this.parseInput(stdin));
+			if (response.decision === "skip") {
+				process.exit(0);
+				return;
+			}
+			const output = this.formatOutput(response);
+			console.log(output);
+			process.exit(0);
+		} catch (error) {
+			this.handleError(error);
+		}
+	}
+	/**
+	* Read stdin from AI agent
+	* @returns Promise resolving to stdin content
+	*/
+	readStdin() {
+		return new Promise((resolve, reject) => {
+			const chunks = [];
+			process.stdin.on("data", (chunk) => {
+				chunks.push(chunk);
+			});
+			process.stdin.on("end", () => {
+				resolve(Buffer.concat(chunks).toString("utf8"));
+			});
+			process.stdin.on("error", (error) => {
+				reject(error);
+			});
+		});
+	}
+	/**
+	* Handle errors with fail-open behavior
+	* Allows operation to proceed with warning message
+	*
+	* @param error - Error that occurred during hook execution
+	*/
+	handleError(error) {
+		const errorMessage = error instanceof Error ? error.message : String(error);
+		const output = this.formatOutput({
+			decision: "allow",
+			message: `⚠️ Hook error: ${errorMessage}`
+		});
+		console.log(output);
+		process.exit(0);
+	}
+};
+
+//#endregion
+//#region src/adapters/ClaudeCodeAdapter.ts
+/**
+* ClaudeCodeAdapter - Adapter for Claude Code hook format
+*
+* DESIGN PATTERNS:
+* - Adapter pattern: Converts Claude Code format to normalized format
+* - Parser pattern: Extracts file paths and operations from tool inputs
+*
+* CODING STANDARDS:
+* - Parse Claude Code JSON stdin format exactly as specified
+* - Format output to match Claude Code hook response schema
+* - Handle missing/optional fields gracefully
+*
+* AVOID:
+* - Assuming all fields are present
+* - Hardcoding tool names (use constants if needed)
+* - Mutating input objects
+*/
+/**
+* Adapter for Claude Code hook format
+*/
+var ClaudeCodeAdapter = class extends BaseAdapter {
+	/**
+	* Parse Claude Code stdin into normalized HookContext
+	*
+	* @param stdin - Raw JSON string from Claude Code
+	* @returns Normalized hook context
+	*/
+	parseInput(stdin) {
+		const input = JSON.parse(stdin);
+		return {
+			toolName: input.tool_name,
+			toolInput: input.tool_input,
+			filePath: this.extractFilePath(input.tool_name, input.tool_input),
+			operation: this.extractOperation(input.tool_name),
+			cwd: input.cwd,
+			sessionId: input.session_id,
+			llmTool: input.llm_tool
+		};
+	}
+	/**
+	* Format normalized HookResponse into Claude Code output
+	*
+	* @param response - Normalized hook response
+	* @returns JSON string for Claude Code
+	*/
+	formatOutput(response) {
+		if (response.decision === "skip") return JSON.stringify({}, null, 2);
+		const output = { hookSpecificOutput: {
+			hookEventName: "PreToolUse",
+			permissionDecision: response.decision,
+			permissionDecisionReason: response.message
+		} };
+		if (response.updatedInput) output.hookSpecificOutput.updatedInput = response.updatedInput;
+		return JSON.stringify(output, null, 2);
+	}
+	/**
+	* Extract file path from tool input
+	*
+	* @param toolName - Name of the tool
+	* @param toolInput - Tool input parameters
+	* @returns File path if this is a file operation
+	*/
+	extractFilePath(toolName, toolInput) {
+		if ([
+			"Read",
+			"Write",
+			"Edit"
+		].includes(toolName)) return toolInput.file_path;
+	}
+	/**
+	* Extract operation type from tool name
+	*
+	* @param toolName - Name of the tool
+	* @returns Operation type if this is a file operation
+	*/
+	extractOperation(toolName) {
+		return {
+			Read: "read",
+			Write: "write",
+			Edit: "edit"
+		}[toolName];
+	}
+};
+
+//#endregion
+//#region src/adapters/ClaudeCodePostToolUseAdapter.ts
+/**
+* ClaudeCodePostToolUseAdapter - Adapter for Claude Code PostToolUse hook format
+*
+* DESIGN PATTERNS:
+* - Adapter pattern: Converts Claude Code PostToolUse format to normalized format
+* - Parser pattern: Extracts file paths and operations from tool response
+*
+* CODING STANDARDS:
+* - Parse Claude Code JSON stdin format exactly as specified
+* - Format output to match Claude Code PostToolUse hook response schema
+* - Handle missing/optional fields gracefully
+*
+* AVOID:
+* - Assuming all fields are present
+* - Hardcoding tool names (use constants if needed)
+* - Mutating input objects
+*/
+/**
+* Adapter for Claude Code PostToolUse hook format
+*/
+var ClaudeCodePostToolUseAdapter = class extends BaseAdapter {
+	/**
+	* Parse Claude Code PostToolUse stdin into normalized HookContext
+	*
+	* @param stdin - Raw JSON string from Claude Code
+	* @returns Normalized hook context
+	*/
+	parseInput(stdin) {
+		const input = JSON.parse(stdin);
+		return {
+			toolName: input.tool_name,
+			toolInput: input.tool_input,
+			filePath: this.extractFilePath(input.tool_name, input.tool_input, input.tool_response),
+			operation: this.extractOperation(input.tool_name),
+			cwd: input.cwd,
+			sessionId: input.session_id,
+			llmTool: input.llm_tool
+		};
+	}
+	/**
+	* Format normalized HookResponse into Claude Code PostToolUse output
+	*
+	* @param response - Normalized hook response
+	* @returns JSON string for Claude Code
+	*/
+	formatOutput(response) {
+		const output = { hookSpecificOutput: { hookEventName: "PostToolUse" } };
+		if (response.decision === "deny") {
+			output.decision = "block";
+			output.reason = response.message;
+		}
+		if (response.decision === "allow" && response.message) output.hookSpecificOutput.additionalContext = response.message;
+		return JSON.stringify(output, null, 2);
+	}
+	/**
+	* Extract file path from tool input or response
+	*
+	* @param toolName - Name of the tool
+	* @param toolInput - Tool input parameters
+	* @param toolResponse - Tool response data
+	* @returns File path if this is a file operation
+	*/
+	extractFilePath(toolName, toolInput, toolResponse) {
+		if ([
+			"Read",
+			"Write",
+			"Edit"
+		].includes(toolName)) return toolInput.file_path || toolResponse.filePath;
+	}
+	/**
+	* Extract operation type from tool name
+	*
+	* @param toolName - Name of the tool
+	* @returns Operation type if this is a file operation
+	*/
+	extractOperation(toolName) {
+		return {
+			Read: "read",
+			Write: "write",
+			Edit: "edit"
+		}[toolName];
+	}
+};
+
+//#endregion
+//#region src/services/ExecutionLogService.ts
+/**
+* ExecutionLogService - Tracks hook executions to prevent duplicate actions
+*
+* DESIGN PATTERNS:
+* - Repository pattern: Abstracts data access to execution log
+* - Query pattern: Provides efficient lookups for hook execution history
+* - Singleton cache: In-memory cache for performance
+*
+* CODING STANDARDS:
+* - Use static methods for stateless operations
+* - Handle file system errors gracefully
+* - Optimize for performance with efficient data structures
+*
+* AVOID:
+* - Loading entire log file into memory
+* - Blocking I/O operations
+* - Complex parsing logic (keep it simple)
+*/
+/**
+* Service for tracking hook executions using an append-only log
+* Prevents duplicate hook actions (e.g., showing design patterns twice for same file)
+*/
+var ExecutionLogService = class ExecutionLogService {
+	/** Log file path - stored in system temp directory */
+	static LOG_FILE = node_path.join(node_os.tmpdir(), "hook-adapter-executions.jsonl");
+	/** In-memory cache of recent executions (last 1000 entries) */
+	static cache = null;
+	/** Max cache size to prevent memory bloat */
+	static MAX_CACHE_SIZE = 1e3;
+	/**
+	* Check if a specific action was already taken for this file in this session
+	*
+	* @param sessionId - Session identifier
+	* @param filePath - File path to check
+	* @param decision - Decision to check for (e.g., 'deny' means we already showed patterns)
+	* @returns true if the action was already taken
+	*/
+	static async hasExecuted(sessionId, filePath, decision) {
+		const entries = await ExecutionLogService.loadLog();
+		for (let i = entries.length - 1; i >= 0; i--) {
+			const entry = entries[i];
+			if (entry.sessionId === sessionId && entry.filePath === filePath && entry.decision === decision) return true;
+		}
+		return false;
+	}
+	/**
+	* Log a hook execution
+	*
+	* @param params - Log execution parameters
+	*/
+	static async logExecution(params) {
+		const entry = {
+			timestamp: Date.now(),
+			sessionId: params.sessionId,
+			filePath: params.filePath,
+			operation: params.operation,
+			decision: params.decision,
+			filePattern: params.filePattern,
+			fileMtime: params.fileMtime,
+			fileChecksum: params.fileChecksum
+		};
+		try {
+			await node_fs_promises.appendFile(ExecutionLogService.LOG_FILE, `${JSON.stringify(entry)}\n`, "utf-8");
+			if (ExecutionLogService.cache) {
+				ExecutionLogService.cache.push(entry);
+				if (ExecutionLogService.cache.length > ExecutionLogService.MAX_CACHE_SIZE) ExecutionLogService.cache = ExecutionLogService.cache.slice(-ExecutionLogService.MAX_CACHE_SIZE);
+			}
+		} catch (error) {
+			console.error("Failed to log hook execution:", error);
+		}
+	}
+	/**
+	* Load execution log from file
+	* Uses in-memory cache for performance
+	*/
+	static async loadLog() {
+		if (ExecutionLogService.cache !== null) return ExecutionLogService.cache;
+		try {
+			const lines = (await node_fs_promises.readFile(ExecutionLogService.LOG_FILE, "utf-8")).trim().split("\n").filter(Boolean);
+			const entries = [];
+			for (const line of lines) try {
+				entries.push(JSON.parse(line));
+			} catch {}
+			ExecutionLogService.cache = entries.slice(-ExecutionLogService.MAX_CACHE_SIZE);
+			return ExecutionLogService.cache;
+		} catch (error) {
+			if (error.code === "ENOENT") {
+				ExecutionLogService.cache = [];
+				return ExecutionLogService.cache;
+			}
+			console.error("Failed to load execution log:", error);
+			ExecutionLogService.cache = [];
+			return ExecutionLogService.cache;
+		}
+	}
+	/**
+	* Clear the execution log (for testing)
+	*/
+	static async clearLog() {
+		try {
+			await node_fs_promises.unlink(ExecutionLogService.LOG_FILE);
+			ExecutionLogService.cache = [];
+		} catch (error) {
+			if (error.code !== "ENOENT") throw error;
+		}
+	}
+	/**
+	* Get log statistics (for debugging)
+	*/
+	static async getStats() {
+		const entries = await ExecutionLogService.loadLog();
+		const sessions = new Set(entries.map((e) => e.sessionId));
+		const files = new Set(entries.map((e) => e.filePath));
+		return {
+			totalEntries: entries.length,
+			uniqueSessions: sessions.size,
+			uniqueFiles: files.size
+		};
+	}
+	/**
+	* Get file metadata (mtime and checksum) for a file
+	*
+	* @param filePath - Path to the file
+	* @returns File metadata or null if file doesn't exist
+	*/
+	static async getFileMetadata(filePath) {
+		try {
+			const content = await node_fs_promises.readFile(filePath, "utf-8");
+			const checksum = node_crypto.createHash("md5").update(content).digest("hex");
+			return {
+				mtime: (await node_fs_promises.stat(filePath)).mtimeMs,
+				checksum
+			};
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Check if a file has changed since the last execution for this session
+	* Returns true if the file should be reviewed (new file or content changed)
+	*
+	* @param sessionId - Session identifier
+	* @param filePath - File path to check
+	* @param decision - Decision type to check for
+	* @returns true if file has changed or no previous execution found
+	*/
+	static async hasFileChanged(sessionId, filePath, decision) {
+		const entries = await ExecutionLogService.loadLog();
+		let lastExecution = null;
+		for (let i = entries.length - 1; i >= 0; i--) {
+			const entry = entries[i];
+			if (entry.sessionId === sessionId && entry.filePath === filePath && entry.decision === decision) {
+				lastExecution = entry;
+				break;
+			}
+		}
+		if (!lastExecution || !lastExecution.fileChecksum) return true;
+		const currentMetadata = await ExecutionLogService.getFileMetadata(filePath);
+		if (!currentMetadata) return true;
+		return currentMetadata.checksum !== lastExecution.fileChecksum;
+	}
+};
+
+//#endregion
+//#region src/services/AdapterProxyService.ts
+/**
+* AdapterProxyService - Routes hook execution to appropriate adapter
+*
+* DESIGN PATTERNS:
+* - Proxy pattern: Routes requests to appropriate handlers
+* - Factory pattern: Creates adapter instances based on agent name
+*
+* CODING STANDARDS:
+* - Use static methods for stateless operations
+* - Provide clear error messages for invalid inputs
+* - Follow TitleCase naming convention for service classes
+*
+* AVOID:
+* - Creating adapter instances unnecessarily
+* - Silently falling back to defaults
+* - Complex conditional logic (use lookup tables)
+*/
+/**
+* Proxy service for routing hook execution
+* Eliminates duplication across commands by centralizing hook routing logic
+*/
+var AdapterProxyService = class AdapterProxyService {
+	/**
+	* Execute hook with the appropriate adapter for the agent
+	*
+	* @param agentName - Agent identifier (e.g., "claude-code")
+	* @param hookType - Type of hook ("PreToolUse" or "PostToolUse")
+	* @param callback - Hook callback function to execute
+	*/
+	static async execute(agentName, hookType, callback) {
+		await AdapterProxyService.getAdapter(agentName, hookType).execute(callback);
+	}
+	/**
+	* Get adapter instance for agent and hook type
+	*
+	* @param agentName - Name of the AI agent (e.g., "claude-code")
+	* @param hookType - Type of hook ("PreToolUse" or "PostToolUse")
+	* @returns Adapter instance
+	*/
+	static getAdapter(agentName, hookType) {
+		switch (agentName) {
+			case __agiflowai_coding_agent_bridge.CLAUDE_CODE:
+				if (hookType === POST_TOOL_USE) return new ClaudeCodePostToolUseAdapter();
+				return new ClaudeCodeAdapter();
+			default: throw new Error(`Unknown agent: ${agentName}. Supported: ${__agiflowai_coding_agent_bridge.CLAUDE_CODE}`);
+		}
+	}
+};
+
+//#endregion
+exports.AdapterProxyService = AdapterProxyService;
+exports.BaseAdapter = BaseAdapter;
+exports.ClaudeCodeAdapter = ClaudeCodeAdapter;
+exports.ClaudeCodePostToolUseAdapter = ClaudeCodePostToolUseAdapter;
+exports.ExecutionLogService = ExecutionLogService;
+exports.POST_TOOL_USE = POST_TOOL_USE;
+exports.PRE_TOOL_USE = PRE_TOOL_USE;