@agiflowai/hooks-adapter 0.0.0

package/dist/index.mjs

@@ -0,0 +1,480 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import * as crypto from "node:crypto";
+import { CLAUDE_CODE } from "@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 = path.join(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 fs.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 fs.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 fs.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 fs.readFile(filePath, "utf-8");
+			const checksum = crypto.createHash("md5").update(content).digest("hex");
+			return {
+				mtime: (await fs.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 CLAUDE_CODE:
+				if (hookType === POST_TOOL_USE) return new ClaudeCodePostToolUseAdapter();
+				return new ClaudeCodeAdapter();
+			default: throw new Error(`Unknown agent: ${agentName}. Supported: ${CLAUDE_CODE}`);
+		}
+	}
+};
+
+//#endregion
+export { AdapterProxyService, BaseAdapter, ClaudeCodeAdapter, ClaudeCodePostToolUseAdapter, ExecutionLogService, POST_TOOL_USE, PRE_TOOL_USE };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@agiflowai/hooks-adapter",
+  "description": "Hook adapters for normalizing AI agent hook formats (Claude Code, Gemini, etc.)",
+  "version": "0.0.0",
+  "license": "AGPL-3.0",
+  "author": "AgiflowIO",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AgiFlow/aicode-toolkit.git",
+    "directory": "packages/hooks-adapter"
+  },
+  "homepage": "https://github.com/AgiFlow/aicode-toolkit#readme",
+  "bugs": {
+    "url": "https://github.com/AgiFlow/aicode-toolkit/issues"
+  },
+  "keywords": [
+    "typescript",
+    "library"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@agiflowai/coding-agent-bridge": "1.0.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "tsdown": "^0.16.4",
+    "typescript": "5.9.3",
+    "vitest": "^3.0.0"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest --run",
+    "typecheck": "tsc --noEmit"
+  }
+}