@agiflowai/hooks-adapter 0.0.0 → 0.0.2

package/dist/index.d.cts

@@ -1,13 +1,13 @@
-//#region src/constants/index.d.ts
+//#region src/constants/hookTypes.d.ts
 /**
- * @agiflowai/hooks-adapter - Constants
+ * Hook Types Constants
  *
  * DESIGN PATTERNS:
  * - Strongly-typed constant exports for compile-time safety
  * - Immutable by default (as const assertions)
  *
  * CODING STANDARDS:
- * - Primitive constants: UPPER_SNAKE_CASE
+ * - Primitive constants: UPPER_SNAKE_CASE or PascalCase for event names
  * - Always include JSDoc with purpose and usage
  *
  * AVOID:
@@ -15,14 +15,19 @@
  * - Magic strings without explanation
  */
 /**
- * Hook type identifiers for different hook events
+ * Hook type identifiers for Claude Code hook events
  */
 declare const PRE_TOOL_USE = "PreToolUse";
 declare const POST_TOOL_USE = "PostToolUse";
+/**
+ * Hook type identifiers for Gemini CLI hook events
+ */
+declare const BEFORE_TOOL_USE = "BeforeTool";
+declare const AFTER_TOOL_USE = "AfterTool";
 /**
  * Union type of all supported hook types
  */
-type HookType = typeof PRE_TOOL_USE | typeof POST_TOOL_USE;
+type HookType = typeof PRE_TOOL_USE | typeof POST_TOOL_USE | typeof BEFORE_TOOL_USE | typeof AFTER_TOOL_USE;
 //#endregion
 //#region src/types/index.d.ts
 /**
@@ -45,55 +50,134 @@ type HookType = typeof PRE_TOOL_USE | typeof POST_TOOL_USE;
  * - Coupling types to implementation details
  */
 /**
- * Normalized context passed to hook callback function
+ * Decision types for hook responses
+ */
+type Decision = 'allow' | 'deny' | 'ask' | 'skip';
+/**
+ * Normalized hook context passed to hook callbacks
+ * Provides a common interface for hooks regardless of the underlying AI agent format
  */
 interface HookContext {
-  /** Name of the tool being invoked (e.g., "Read", "Write", "Edit") */
+  /** Name of the tool being executed (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 */
+  /** Input parameters for the tool */
+  toolInput: Record<string, unknown>;
+  /** File path for file operations (extracted from tool input if applicable) */
   filePath?: string;
-  /** Type of file operation */
+  /** Operation type for file operations */
   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") */
+  /** Optional LLM tool identifier (e.g., 'claude-code') */
   llmTool?: string;
 }
 /**
- * Normalized response from hook callback function
+ * Response from hook callback function
  */
 interface HookResponse {
   /** Permission decision for the tool execution */
-  decision: 'allow' | 'deny' | 'ask' | 'skip';
+  decision: Decision;
   /** 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>;
+  updatedInput?: Record<string, unknown>;
+}
+/**
+ * Content item in tool result from Claude Code
+ */
+interface ToolResultContentItem {
+  /** Content type (e.g., 'text', 'image') */
+  readonly type: string;
+  /** Text content if type is 'text' */
+  readonly text?: string;
+}
+/**
+ * Tool result structure from Claude Code PostToolUse hook
+ */
+interface ToolResult {
+  /** Array of content items returned by the tool */
+  readonly content?: readonly ToolResultContentItem[];
+}
+/**
+ * Scaffold execution data from execution log
+ */
+interface ScaffoldExecution {
+  /** Unique scaffold execution ID */
+  readonly scaffoldId: string;
+  /** List of files generated by the scaffold */
+  readonly generatedFiles: readonly string[];
+  /** Name of the scaffold feature/method */
+  readonly featureName?: string;
+}
+/**
+ * Log entry structure from ExecutionLogService
+ */
+interface LogEntry {
+  /** Timestamp of the log entry */
+  readonly timestamp?: number;
+  /** Session ID */
+  readonly sessionId?: string;
+  /** Operation type */
+  readonly operation: string;
+  /** Scaffold execution ID */
+  readonly scaffoldId?: string;
+  /** Files generated by scaffold */
+  readonly generatedFiles?: readonly string[];
+  /** Scaffold feature name */
+  readonly featureName?: string;
+  /** File path */
+  readonly filePath: string;
+  /** Decision made */
+  readonly decision?: string;
+  /** File pattern matched */
+  readonly filePattern?: string;
+  /** File modification timestamp */
+  readonly fileMtime?: number;
+  /** File content checksum */
+  readonly fileChecksum?: string;
+  /** Project path */
+  readonly projectPath?: string;
+}
+/**
+ * Pending scaffold log entry for temp file storage
+ */
+interface PendingScaffoldLogEntry {
+  /** Unique scaffold execution ID */
+  readonly scaffoldId: string;
+  /** List of files generated */
+  readonly generatedFiles: readonly string[];
+  /** Project path where scaffold was executed */
+  readonly projectPath: string;
+  /** Scaffold feature name */
+  readonly featureName?: string;
 }
+//#endregion
+//#region src/constants/decisions.d.ts
 /**
- * Hook callback function signature
- * Takes normalized context and returns normalized response
+ * Normalized hook decision types used across all adapters
+ * Adapters convert platform-specific formats to these normalized values
  */
-type HookCallback = (context: HookContext) => Promise<HookResponse>;
+declare const DECISION_ALLOW: Decision;
+declare const DECISION_DENY: Decision;
+declare const DECISION_SKIP: Decision;
+declare const DECISION_ASK: Decision;
 //#endregion
 //#region src/adapters/BaseAdapter.d.ts
-
 /**
- * Abstract base adapter for normalizing AI agent hook formats
+ * Abstract base adapter for AI agent hook formats
+ * @template TContext - The adapter-specific input context type
  */
-declare abstract class BaseAdapter {
+declare abstract class BaseAdapter<TContext = any> {
   /**
-   * Parse stdin from AI agent into normalized HookContext
+   * Parse stdin from AI agent into context (specific to each adapter)
    * @param stdin - Raw stdin string from AI agent
-   * @returns Normalized hook context
+   * @returns Context object (can be adapter-specific or normalized)
    */
-  abstract parseInput(stdin: string): HookContext;
+  abstract parseInput(stdin: string): TContext;
   /**
    * Format normalized HookResponse into AI agent-specific output
    * @param response - Normalized hook response
@@ -101,12 +185,18 @@ declare abstract class BaseAdapter {
    */
   abstract formatOutput(response: HookResponse): string;
   /**
-   * Execute hook callback with normalized context
+   * Execute hook callback with context
    * Template method that orchestrates the hook execution flow
    *
    * @param callback - Hook callback function to execute
    */
-  execute(callback: HookCallback): Promise<void>;
+  execute(callback: (context: TContext) => Promise<HookResponse>): Promise<void>;
+  /**
+   * Execute multiple hooks with shared stdin (read once, execute all)
+   * This is useful when multiple hooks need to process the same input
+   * @param callbacks - Array of callback functions to execute
+   */
+  executeMultiple(callbacks: Array<(context: TContext) => Promise<HookResponse>>): Promise<void>;
   /**
    * Read stdin from AI agent
    * @returns Promise resolving to stdin content
@@ -123,96 +213,108 @@ declare abstract class BaseAdapter {
 //#endregion
 //#region src/adapters/ClaudeCodeAdapter.d.ts
 /**
- * Adapter for Claude Code hook format
+ * Claude Code hook input format (PreToolUse)
  */
-declare class ClaudeCodeAdapter extends BaseAdapter {
+interface ClaudeCodePreToolUseInput {
+  tool_name: string;
+  tool_input: Record<string, any>;
+  cwd: string;
+  session_id: string;
+  hook_event_name: 'PreToolUse';
+  tool_use_id: string;
+  transcript_path: string;
+  permission_mode: string;
+  llm_tool?: string;
+}
+/**
+ * Claude Code hook input format (PostToolUse)
+ */
+interface ClaudeCodePostToolUseInput {
+  tool_name: string;
+  tool_input: Record<string, any>;
+  tool_response: Record<string, any>;
+  cwd: string;
+  session_id: string;
+  hook_event_name: 'PostToolUse';
+  tool_use_id: string;
+  transcript_path: string;
+  permission_mode: string;
+  llm_tool?: string;
+}
+/**
+ * Union type for both hook input formats
+ */
+type ClaudeCodeHookInput = ClaudeCodePreToolUseInput | ClaudeCodePostToolUseInput;
+/**
+ * Unified adapter for Claude Code hook format (PreToolUse & PostToolUse)
+ */
+declare class ClaudeCodeAdapter extends BaseAdapter<ClaudeCodeHookInput> {
+  private hookEventName;
   /**
-   * Parse Claude Code stdin into normalized HookContext
+   * Parse Claude Code stdin into ClaudeCodeHookInput
    *
    * @param stdin - Raw JSON string from Claude Code
-   * @returns Normalized hook context
+   * @returns ClaudeCodeHookInput
    */
-  parseInput(stdin: string): HookContext;
+  parseInput(stdin: string): ClaudeCodeHookInput;
   /**
    * Format normalized HookResponse into Claude Code output
+   * Morphs output based on hook event type (PreToolUse vs PostToolUse)
    *
    * @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
+   * Format PreToolUse output
    */
-  private extractFilePath;
+  private formatPreToolUseOutput;
   /**
-   * Extract operation type from tool name
-   *
-   * @param toolName - Name of the tool
-   * @returns Operation type if this is a file operation
+   * Format PostToolUse output
    */
-  private extractOperation;
+  private formatPostToolUseOutput;
 }
 //#endregion
-//#region src/adapters/ClaudeCodePostToolUseAdapter.d.ts
+//#region src/adapters/GeminiCliAdapter.d.ts
 /**
- * Adapter for Claude Code PostToolUse hook format
+ * Gemini CLI hook input format (BeforeTool/AfterTool)
  */
-declare class ClaudeCodePostToolUseAdapter extends BaseAdapter {
+interface GeminiCliHookInput {
+  tool_name: string;
+  tool_input: Record<string, any>;
+  cwd: string;
+  session_id: string;
+  event: 'BeforeTool' | 'AfterTool' | 'BeforeModel' | 'AfterModel';
+  llm_tool?: string;
+}
+/**
+ * Adapter for Gemini CLI hook format
+ */
+declare class GeminiCliAdapter extends BaseAdapter<GeminiCliHookInput> {
   /**
-   * Parse Claude Code PostToolUse stdin into normalized HookContext
+   * Parse Gemini CLI stdin into full hook input (preserves all fields)
    *
-   * @param stdin - Raw JSON string from Claude Code
-   * @returns Normalized hook context
+   * @param stdin - Raw JSON string from Gemini CLI
+   * @returns Full Gemini CLI hook input
    */
-  parseInput(stdin: string): HookContext;
+  parseInput(stdin: string): GeminiCliHookInput;
   /**
-   * Format normalized HookResponse into Claude Code PostToolUse output
+   * Format normalized HookResponse into Gemini CLI output
    *
    * @param response - Normalized hook response
-   * @returns JSON string for Claude Code
+   * @returns JSON string for Gemini CLI
    */
   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)
+ * Log statistics returned by getStats method
  */
+interface LogStats {
+  totalEntries: number;
+  uniqueFiles: number;
+}
 /**
  * Input parameters for logging a hook execution
  */
@@ -226,57 +328,99 @@ interface LogExecutionParams {
   fileMtime?: number;
   /** MD5 checksum of file content at time of execution */
   fileChecksum?: string;
+  /** List of files generated by scaffold method execution */
+  generatedFiles?: readonly string[] | string[];
+  /** Unique scaffold execution ID (for tracking specific scaffold operations) */
+  scaffoldId?: string;
+  /** Project path where scaffold was executed */
+  projectPath?: string;
+  /** Name of the scaffold feature/method that was used */
+  featureName?: string;
+}
+/**
+ * Input parameters for checking if a hook execution has occurred
+ */
+interface HasExecutedParams {
+  /** File path to check */
+  filePath: string;
+  /** Decision to check for (e.g., 'deny' means we already showed patterns) */
+  decision: string;
+  /** Optional file pattern to match */
+  filePattern?: string;
+  /** Optional project path to distinguish same patterns in different projects */
+  projectPath?: string;
 }
 /**
  * Service for tracking hook executions using an append-only log
  * Prevents duplicate hook actions (e.g., showing design patterns twice for same file)
+ * Each session has its own log file for isolation
  */
 declare class ExecutionLogService {
-  /** Log file path - stored in system temp directory */
-  private static readonly LOG_FILE;
+  /** Log file path for this session - stored in system temp directory */
+  private readonly logFile;
   /** In-memory cache of recent executions (last 1000 entries) */
-  private static cache;
+  private cache;
   /** Max cache size to prevent memory bloat */
   private static readonly MAX_CACHE_SIZE;
+  /** Session ID for this service instance */
+  private readonly sessionId;
+  /**
+   * Create a new ExecutionLogService instance for a specific session
+   * @param sessionId - Unique session identifier
+   */
+  constructor(sessionId: string);
   /**
    * 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
+   * NOTE: Uses fail-open strategy - on error, returns false to allow action.
+   * This ensures hooks can still provide guidance even if log access fails.
+   *
+   * @param params - Parameters for checking execution
+   * @returns true if the action was already taken, false on error (fail-open)
    */
-  static hasExecuted(sessionId: string, filePath: string, decision: string): Promise<boolean>;
+  hasExecuted(params: HasExecutedParams): Promise<boolean>;
   /**
    * Log a hook execution
    *
-   * @param params - Log execution parameters
+   * NOTE: This method uses fail-silent strategy. Logging failures should never
+   * break hook execution since the hook's primary purpose is to provide guidance,
+   * not to persist data. The log is used for optimization (preventing duplicate
+   * guidance) rather than critical functionality.
+   *
+   * @param params - Log execution parameters (sessionId will be set automatically)
    */
-  static logExecution(params: LogExecutionParams): Promise<void>;
+  logExecution(params: Omit<LogExecutionParams, 'sessionId'>): Promise<void>;
   /**
    * Load execution log from file
    * Uses in-memory cache for performance
+   *
+   * NOTE: Uses fail-silent strategy for non-ENOENT errors. The log is used for
+   * optimization (deduplication) rather than critical functionality. If the log
+   * cannot be read, returning empty allows hooks to continue with potentially
+   * duplicate guidance rather than failing entirely.
    */
-  private static loadLog;
+  loadLog(): Promise<LogEntry[]>;
   /**
    * Clear the execution log (for testing)
+   * @throws Error if deletion fails for reasons other than file not existing
    */
-  static clearLog(): Promise<void>;
+  clearLog(): Promise<void>;
   /**
    * Get log statistics (for debugging)
+   *
+   * NOTE: Uses fail-open strategy - on error, returns zero counts.
+   * This is acceptable for debugging statistics which are non-critical.
+   *
+   * @returns Log statistics, or zeros on error (fail-open)
    */
-  static getStats(): Promise<{
-    totalEntries: number;
-    uniqueSessions: number;
-    uniqueFiles: number;
-  }>;
+  getStats(): Promise<LogStats>;
   /**
    * 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<{
+  getFileMetadata(filePath: string): Promise<{
     mtime: number;
     checksum: string;
   } | null>;
@@ -284,36 +428,85 @@ declare class ExecutionLogService {
    * 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
+   * NOTE: Uses fail-open strategy - on error, returns true to allow review.
+   * This ensures hooks can still provide value even if log access fails.
+   *
    * @param filePath - File path to check
    * @param decision - Decision type to check for
-   * @returns true if file has changed or no previous execution found
+   * @returns true if file has changed or no previous execution found, true on error (fail-open)
    */
-  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 {
+  hasFileChanged(filePath: string, decision: string): Promise<boolean>;
   /**
-   * Execute hook with the appropriate adapter for the agent
+   * Check if file was recently reviewed (within debounce window)
+   * Prevents noisy feedback during rapid successive edits
    *
-   * @param agentName - Agent identifier (e.g., "claude-code")
-   * @param hookType - Type of hook ("PreToolUse" or "PostToolUse")
-   * @param callback - Hook callback function to execute
+   * NOTE: Uses fail-open strategy - on error, returns false to allow review.
+   * This ensures hooks can still provide value even if log access fails.
+   *
+   * @param filePath - File path to check
+   * @param debounceMs - Debounce window in milliseconds (default: 3000ms = 3 seconds)
+   * @returns true if file was reviewed within debounce window, false on error (fail-open)
    */
-  static execute(agentName: string, hookType: HookType, callback: HookCallback): Promise<void>;
+  wasRecentlyReviewed(filePath: string, debounceMs?: number): Promise<boolean>;
   /**
-   * Get adapter instance for agent and hook type
+   * Check if a file was generated by a scaffold method
+   * Useful for hooks to avoid suggesting scaffold for files already created by scaffold
+   *
+   * NOTE: Uses fail-open strategy - on error, returns false to allow scaffold suggestion.
+   * Worst case: user sees scaffold suggestion for an already-scaffolded file.
    *
-   * @param agentName - Name of the AI agent (e.g., "claude-code")
-   * @param hookType - Type of hook ("PreToolUse" or "PostToolUse")
-   * @returns Adapter instance
+   * @param filePath - File path to check
+   * @returns true if file was generated by scaffold in this session, false on error (fail-open)
    */
-  private static getAdapter;
+  wasGeneratedByScaffold(filePath: string): Promise<boolean>;
 }
 //#endregion
-export { AdapterProxyService, BaseAdapter, ClaudeCodeAdapter, ClaudeCodePostToolUseAdapter, ExecutionLogService, HookCallback, HookContext, HookResponse, HookType, LogExecutionParams, POST_TOOL_USE, PRE_TOOL_USE };
+//#region src/utils/parseHookType.d.ts
+/**
+ * parseHookType Utilities
+ *
+ * DESIGN PATTERNS:
+ * - Pure function pattern: No side effects, deterministic output
+ * - Single domain focus: All functions related to hook type parsing
+ * - Early validation with descriptive error messages
+ *
+ * CODING STANDARDS:
+ * - Function names use camelCase with descriptive verbs (validate, format, parse, transform)
+ * - All functions should be pure (same input = same output, no side effects)
+ * - Use explicit return types
+ * - Document complex logic with JSDoc comments
+ * - Keep functions small and focused on single responsibility
+ *
+ * AVOID:
+ * - Side effects (mutations, I/O, random values, Date.now(), etc.)
+ * - Stateful behavior or closures with mutable state
+ * - Dependencies on external services or global variables
+ * - Classes (use pure functions instead)
+ */
+/**
+ * Parsed hook type result containing agent and hook method
+ */
+interface ParsedHookType {
+  /** Agent identifier (e.g., 'claude-code', 'gemini-cli') */
+  agent: string;
+  /** Hook method name (e.g., 'preToolUse', 'afterTool') */
+  hookMethod: string;
+}
+/**
+ * Parse hook type option in format: agent.hookMethod
+ *
+ * @param hookType - Hook type string in format '<agent>.<hookMethod>'
+ * @returns Parsed hook type with agent and hookMethod
+ * @throws Error if hook type format is invalid
+ *
+ * @example
+ * parseHookType('claude-code.preToolUse')
+ * // Returns: { agent: 'claude-code', hookMethod: 'preToolUse' }
+ *
+ * @example
+ * parseHookType('gemini-cli.afterTool')
+ * // Returns: { agent: 'gemini-cli', hookMethod: 'afterTool' }
+ */
+declare function parseHookType(hookType: string): ParsedHookType;
+//#endregion
+export { AFTER_TOOL_USE, BEFORE_TOOL_USE, BaseAdapter, ClaudeCodeAdapter, ClaudeCodeHookInput, ClaudeCodePostToolUseInput, ClaudeCodePreToolUseInput, DECISION_ALLOW, DECISION_ASK, DECISION_DENY, DECISION_SKIP, Decision, ExecutionLogService, GeminiCliAdapter, GeminiCliHookInput, HasExecutedParams, HookContext, HookResponse, HookType, LogEntry, LogExecutionParams, LogStats, POST_TOOL_USE, PRE_TOOL_USE, ParsedHookType, PendingScaffoldLogEntry, ScaffoldExecution, ToolResult, ToolResultContentItem, parseHookType };