@agiflowai/hooks-adapter 0.0.0

package/dist/index.d.cts

@@ -0,0 +1,319 @@
+//#region src/constants/index.d.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
+ */
+declare const PRE_TOOL_USE = "PreToolUse";
+declare const POST_TOOL_USE = "PostToolUse";
+/**
+ * Union type of all supported hook types
+ */
+type HookType = typeof PRE_TOOL_USE | typeof POST_TOOL_USE;
+//#endregion
+//#region src/types/index.d.ts
+/**
+ * @agiflowai/hooks-adapter - Type Definitions
+ *
+ * DESIGN PATTERNS:
+ * - Interface segregation: Keep interfaces focused and minimal
+ * - Type composition: Build complex types from simple primitives
+ * - Generics: Use type parameters for reusable, type-safe abstractions
+ *
+ * CODING STANDARDS:
+ * - Use PascalCase for type/interface names
+ * - Prefix interfaces with 'I' only for abstract contracts
+ * - Document complex types with JSDoc comments
+ * - Export all public types
+ *
+ * AVOID:
+ * - Any type unless absolutely necessary
+ * - Overly complex type gymnastics
+ * - Coupling types to implementation details
+ */
+/**
+ * Normalized context passed to hook callback function
+ */
+interface HookContext {
+  /** Name of the tool being invoked (e.g., "Read", "Write", "Edit") */
+  toolName: string;
+  /** Input parameters passed to the tool */
+  toolInput: Record<string, any>;
+  /** File path if this is a file operation */
+  filePath?: string;
+  /** Type of file operation */
+  operation?: 'read' | 'write' | 'edit';
+  /** Current working directory */
+  cwd: string;
+  /** Unique session identifier */
+  sessionId: string;
+  /** Optional LLM tool to use for processing (e.g., "claude-code", "gemini") */
+  llmTool?: string;
+}
+/**
+ * Normalized response from hook callback function
+ */
+interface HookResponse {
+  /** Permission decision for the tool execution */
+  decision: 'allow' | 'deny' | 'ask' | 'skip';
+  /** Message shown to the LLM (e.g., design patterns, warnings) */
+  message: string;
+  /** Optional message shown only to the user (not the LLM) */
+  userMessage?: string;
+  /** Optional updated input parameters for the tool */
+  updatedInput?: Record<string, any>;
+}
+/**
+ * Hook callback function signature
+ * Takes normalized context and returns normalized response
+ */
+type HookCallback = (context: HookContext) => Promise<HookResponse>;
+//#endregion
+//#region src/adapters/BaseAdapter.d.ts
+
+/**
+ * Abstract base adapter for normalizing AI agent hook formats
+ */
+declare abstract class BaseAdapter {
+  /**
+   * Parse stdin from AI agent into normalized HookContext
+   * @param stdin - Raw stdin string from AI agent
+   * @returns Normalized hook context
+   */
+  abstract parseInput(stdin: string): HookContext;
+  /**
+   * Format normalized HookResponse into AI agent-specific output
+   * @param response - Normalized hook response
+   * @returns Formatted output string for AI agent
+   */
+  abstract formatOutput(response: HookResponse): string;
+  /**
+   * Execute hook callback with normalized context
+   * Template method that orchestrates the hook execution flow
+   *
+   * @param callback - Hook callback function to execute
+   */
+  execute(callback: HookCallback): Promise<void>;
+  /**
+   * Read stdin from AI agent
+   * @returns Promise resolving to stdin content
+   */
+  private readStdin;
+  /**
+   * Handle errors with fail-open behavior
+   * Allows operation to proceed with warning message
+   *
+   * @param error - Error that occurred during hook execution
+   */
+  private handleError;
+}
+//#endregion
+//#region src/adapters/ClaudeCodeAdapter.d.ts
+/**
+ * Adapter for Claude Code hook format
+ */
+declare class ClaudeCodeAdapter extends BaseAdapter {
+  /**
+   * Parse Claude Code stdin into normalized HookContext
+   *
+   * @param stdin - Raw JSON string from Claude Code
+   * @returns Normalized hook context
+   */
+  parseInput(stdin: string): HookContext;
+  /**
+   * Format normalized HookResponse into Claude Code output
+   *
+   * @param response - Normalized hook response
+   * @returns JSON string for Claude Code
+   */
+  formatOutput(response: HookResponse): string;
+  /**
+   * 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
+   */
+  private extractFilePath;
+  /**
+   * Extract operation type from tool name
+   *
+   * @param toolName - Name of the tool
+   * @returns Operation type if this is a file operation
+   */
+  private extractOperation;
+}
+//#endregion
+//#region src/adapters/ClaudeCodePostToolUseAdapter.d.ts
+/**
+ * Adapter for Claude Code PostToolUse hook format
+ */
+declare class ClaudeCodePostToolUseAdapter extends BaseAdapter {
+  /**
+   * Parse Claude Code PostToolUse stdin into normalized HookContext
+   *
+   * @param stdin - Raw JSON string from Claude Code
+   * @returns Normalized hook context
+   */
+  parseInput(stdin: string): HookContext;
+  /**
+   * Format normalized HookResponse into Claude Code PostToolUse output
+   *
+   * @param response - Normalized hook response
+   * @returns JSON string for Claude Code
+   */
+  formatOutput(response: HookResponse): string;
+  /**
+   * 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
+   */
+  private extractFilePath;
+  /**
+   * Extract operation type from tool name
+   *
+   * @param toolName - Name of the tool
+   * @returns Operation type if this is a file operation
+   */
+  private extractOperation;
+}
+//#endregion
+//#region src/services/ExecutionLogService.d.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)
+ */
+/**
+ * Input parameters for logging a hook execution
+ */
+interface LogExecutionParams {
+  sessionId: string;
+  filePath: string;
+  operation: string;
+  decision: string;
+  filePattern?: string;
+  /** File modification timestamp (mtime) at time of execution */
+  fileMtime?: number;
+  /** MD5 checksum of file content at time of execution */
+  fileChecksum?: string;
+}
+/**
+ * Service for tracking hook executions using an append-only log
+ * Prevents duplicate hook actions (e.g., showing design patterns twice for same file)
+ */
+declare class ExecutionLogService {
+  /** Log file path - stored in system temp directory */
+  private static readonly LOG_FILE;
+  /** In-memory cache of recent executions (last 1000 entries) */
+  private static cache;
+  /** Max cache size to prevent memory bloat */
+  private static readonly MAX_CACHE_SIZE;
+  /**
+   * 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 hasExecuted(sessionId: string, filePath: string, decision: string): Promise<boolean>;
+  /**
+   * Log a hook execution
+   *
+   * @param params - Log execution parameters
+   */
+  static logExecution(params: LogExecutionParams): Promise<void>;
+  /**
+   * Load execution log from file
+   * Uses in-memory cache for performance
+   */
+  private static loadLog;
+  /**
+   * Clear the execution log (for testing)
+   */
+  static clearLog(): Promise<void>;
+  /**
+   * Get log statistics (for debugging)
+   */
+  static getStats(): Promise<{
+    totalEntries: number;
+    uniqueSessions: number;
+    uniqueFiles: number;
+  }>;
+  /**
+   * 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 getFileMetadata(filePath: string): Promise<{
+    mtime: number;
+    checksum: string;
+  } | 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 hasFileChanged(sessionId: string, filePath: string, decision: string): Promise<boolean>;
+}
+//#endregion
+//#region src/services/AdapterProxyService.d.ts
+/**
+ * Proxy service for routing hook execution
+ * Eliminates duplication across commands by centralizing hook routing logic
+ */
+declare 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 execute(agentName: string, hookType: HookType, callback: HookCallback): Promise<void>;
+  /**
+   * 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
+   */
+  private static getAdapter;
+}
+//#endregion
+export { AdapterProxyService, BaseAdapter, ClaudeCodeAdapter, ClaudeCodePostToolUseAdapter, ExecutionLogService, HookCallback, HookContext, HookResponse, HookType, LogExecutionParams, POST_TOOL_USE, PRE_TOOL_USE };

package/dist/index.d.mts

@@ -0,0 +1,319 @@
+//#region src/constants/index.d.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
+ */
+declare const PRE_TOOL_USE = "PreToolUse";
+declare const POST_TOOL_USE = "PostToolUse";
+/**
+ * Union type of all supported hook types
+ */
+type HookType = typeof PRE_TOOL_USE | typeof POST_TOOL_USE;
+//#endregion
+//#region src/types/index.d.ts
+/**
+ * @agiflowai/hooks-adapter - Type Definitions
+ *
+ * DESIGN PATTERNS:
+ * - Interface segregation: Keep interfaces focused and minimal
+ * - Type composition: Build complex types from simple primitives
+ * - Generics: Use type parameters for reusable, type-safe abstractions
+ *
+ * CODING STANDARDS:
+ * - Use PascalCase for type/interface names
+ * - Prefix interfaces with 'I' only for abstract contracts
+ * - Document complex types with JSDoc comments
+ * - Export all public types
+ *
+ * AVOID:
+ * - Any type unless absolutely necessary
+ * - Overly complex type gymnastics
+ * - Coupling types to implementation details
+ */
+/**
+ * Normalized context passed to hook callback function
+ */
+interface HookContext {
+  /** Name of the tool being invoked (e.g., "Read", "Write", "Edit") */
+  toolName: string;
+  /** Input parameters passed to the tool */
+  toolInput: Record<string, any>;
+  /** File path if this is a file operation */
+  filePath?: string;
+  /** Type of file operation */
+  operation?: 'read' | 'write' | 'edit';
+  /** Current working directory */
+  cwd: string;
+  /** Unique session identifier */
+  sessionId: string;
+  /** Optional LLM tool to use for processing (e.g., "claude-code", "gemini") */
+  llmTool?: string;
+}
+/**
+ * Normalized response from hook callback function
+ */
+interface HookResponse {
+  /** Permission decision for the tool execution */
+  decision: 'allow' | 'deny' | 'ask' | 'skip';
+  /** Message shown to the LLM (e.g., design patterns, warnings) */
+  message: string;
+  /** Optional message shown only to the user (not the LLM) */
+  userMessage?: string;
+  /** Optional updated input parameters for the tool */
+  updatedInput?: Record<string, any>;
+}
+/**
+ * Hook callback function signature
+ * Takes normalized context and returns normalized response
+ */
+type HookCallback = (context: HookContext) => Promise<HookResponse>;
+//#endregion
+//#region src/adapters/BaseAdapter.d.ts
+
+/**
+ * Abstract base adapter for normalizing AI agent hook formats
+ */
+declare abstract class BaseAdapter {
+  /**
+   * Parse stdin from AI agent into normalized HookContext
+   * @param stdin - Raw stdin string from AI agent
+   * @returns Normalized hook context
+   */
+  abstract parseInput(stdin: string): HookContext;
+  /**
+   * Format normalized HookResponse into AI agent-specific output
+   * @param response - Normalized hook response
+   * @returns Formatted output string for AI agent
+   */
+  abstract formatOutput(response: HookResponse): string;
+  /**
+   * Execute hook callback with normalized context
+   * Template method that orchestrates the hook execution flow
+   *
+   * @param callback - Hook callback function to execute
+   */
+  execute(callback: HookCallback): Promise<void>;
+  /**
+   * Read stdin from AI agent
+   * @returns Promise resolving to stdin content
+   */
+  private readStdin;
+  /**
+   * Handle errors with fail-open behavior
+   * Allows operation to proceed with warning message
+   *
+   * @param error - Error that occurred during hook execution
+   */
+  private handleError;
+}
+//#endregion
+//#region src/adapters/ClaudeCodeAdapter.d.ts
+/**
+ * Adapter for Claude Code hook format
+ */
+declare class ClaudeCodeAdapter extends BaseAdapter {
+  /**
+   * Parse Claude Code stdin into normalized HookContext
+   *
+   * @param stdin - Raw JSON string from Claude Code
+   * @returns Normalized hook context
+   */
+  parseInput(stdin: string): HookContext;
+  /**
+   * Format normalized HookResponse into Claude Code output
+   *
+   * @param response - Normalized hook response
+   * @returns JSON string for Claude Code
+   */
+  formatOutput(response: HookResponse): string;
+  /**
+   * 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
+   */
+  private extractFilePath;
+  /**
+   * Extract operation type from tool name
+   *
+   * @param toolName - Name of the tool
+   * @returns Operation type if this is a file operation
+   */
+  private extractOperation;
+}
+//#endregion
+//#region src/adapters/ClaudeCodePostToolUseAdapter.d.ts
+/**
+ * Adapter for Claude Code PostToolUse hook format
+ */
+declare class ClaudeCodePostToolUseAdapter extends BaseAdapter {
+  /**
+   * Parse Claude Code PostToolUse stdin into normalized HookContext
+   *
+   * @param stdin - Raw JSON string from Claude Code
+   * @returns Normalized hook context
+   */
+  parseInput(stdin: string): HookContext;
+  /**
+   * Format normalized HookResponse into Claude Code PostToolUse output
+   *
+   * @param response - Normalized hook response
+   * @returns JSON string for Claude Code
+   */
+  formatOutput(response: HookResponse): string;
+  /**
+   * 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
+   */
+  private extractFilePath;
+  /**
+   * Extract operation type from tool name
+   *
+   * @param toolName - Name of the tool
+   * @returns Operation type if this is a file operation
+   */
+  private extractOperation;
+}
+//#endregion
+//#region src/services/ExecutionLogService.d.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)
+ */
+/**
+ * Input parameters for logging a hook execution
+ */
+interface LogExecutionParams {
+  sessionId: string;
+  filePath: string;
+  operation: string;
+  decision: string;
+  filePattern?: string;
+  /** File modification timestamp (mtime) at time of execution */
+  fileMtime?: number;
+  /** MD5 checksum of file content at time of execution */
+  fileChecksum?: string;
+}
+/**
+ * Service for tracking hook executions using an append-only log
+ * Prevents duplicate hook actions (e.g., showing design patterns twice for same file)
+ */
+declare class ExecutionLogService {
+  /** Log file path - stored in system temp directory */
+  private static readonly LOG_FILE;
+  /** In-memory cache of recent executions (last 1000 entries) */
+  private static cache;
+  /** Max cache size to prevent memory bloat */
+  private static readonly MAX_CACHE_SIZE;
+  /**
+   * 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 hasExecuted(sessionId: string, filePath: string, decision: string): Promise<boolean>;
+  /**
+   * Log a hook execution
+   *
+   * @param params - Log execution parameters
+   */
+  static logExecution(params: LogExecutionParams): Promise<void>;
+  /**
+   * Load execution log from file
+   * Uses in-memory cache for performance
+   */
+  private static loadLog;
+  /**
+   * Clear the execution log (for testing)
+   */
+  static clearLog(): Promise<void>;
+  /**
+   * Get log statistics (for debugging)
+   */
+  static getStats(): Promise<{
+    totalEntries: number;
+    uniqueSessions: number;
+    uniqueFiles: number;
+  }>;
+  /**
+   * 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 getFileMetadata(filePath: string): Promise<{
+    mtime: number;
+    checksum: string;
+  } | 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 hasFileChanged(sessionId: string, filePath: string, decision: string): Promise<boolean>;
+}
+//#endregion
+//#region src/services/AdapterProxyService.d.ts
+/**
+ * Proxy service for routing hook execution
+ * Eliminates duplication across commands by centralizing hook routing logic
+ */
+declare 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 execute(agentName: string, hookType: HookType, callback: HookCallback): Promise<void>;
+  /**
+   * 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
+   */
+  private static getAdapter;
+}
+//#endregion
+export { AdapterProxyService, BaseAdapter, ClaudeCodeAdapter, ClaudeCodePostToolUseAdapter, ExecutionLogService, HookCallback, HookContext, HookResponse, HookType, LogExecutionParams, POST_TOOL_USE, PRE_TOOL_USE };