wave-agent-sdk 0.0.1

package/dist/hooks/executor.js

@@ -0,0 +1,312 @@
+/**
+ * Hook Command Executor
+ *
+ * Handles the execution of hook commands in isolated processes with proper
+ * timeout handling, environment variable injection, and cross-platform support.
+ */
+import { spawn } from "child_process";
+import { getSessionFilePath, } from "./types.js";
+/**
+ * Build JSON input data for hook stdin
+ */
+function buildHookJsonInput(context) {
+    const jsonInput = {
+        session_id: context.sessionId || "unknown",
+        transcript_path: context.transcriptPath ||
+            (context.sessionId ? getSessionFilePath(context.sessionId) : ""),
+        cwd: context.cwd || context.projectDir,
+        hook_event_name: context.event,
+    };
+    // Add optional fields based on event type
+    if (context.event === "PreToolUse" || context.event === "PostToolUse") {
+        if (context.toolName) {
+            jsonInput.tool_name = context.toolName;
+        }
+        if (context.toolInput !== undefined) {
+            jsonInput.tool_input = context.toolInput;
+        }
+    }
+    if (context.event === "PostToolUse" && context.toolResponse !== undefined) {
+        jsonInput.tool_response = context.toolResponse;
+    }
+    if (context.event === "UserPromptSubmit" &&
+        context.userPrompt !== undefined) {
+        jsonInput.user_prompt = context.userPrompt;
+    }
+    return jsonInput;
+}
+export class HookExecutor {
+    constructor(logger, options) {
+        this.defaultTimeout = 10000; // 10 seconds
+        this.maxTimeout = 300000; // 5 minutes
+        this.logger = logger;
+        // Skip execution in test environment unless we're specifically testing the executor
+        this.skipExecution =
+            options?.skipExecution ??
+                ((process.env.NODE_ENV === "test" || process.env.VITEST === "true") &&
+                    !process.env.WAVE_TEST_HOOKS_EXECUTION);
+    }
+    /**
+     * Execute a single hook command in an isolated process
+     */
+    async executeCommand(command, context, options = {}) {
+        const startTime = Date.now();
+        const timeout = Math.min(options.timeout ?? this.defaultTimeout, this.maxTimeout);
+        const cwd = options.cwd ?? context.projectDir;
+        // Skip command execution in test environment (unless specifically testing hooks)
+        if (this.skipExecution) {
+            this.logger?.debug(`[Hook] Skipping command execution: ${command}`);
+            return {
+                success: true,
+                exitCode: 0,
+                stdout: "Test environment: command execution skipped",
+                duration: Date.now() - startTime,
+                timedOut: false,
+            };
+        }
+        // Log hook execution start
+        this.logger?.debug(`[Hook] Executing ${context.event} hook: ${command}`);
+        this.logger?.debug(`[Hook] Context: event=${context.event}, tool=${context.toolName || "N/A"}, cwd=${cwd}`);
+        // Validate command safety
+        if (!this.isCommandSafe(command)) {
+            const error = "Command contains potentially unsafe characters";
+            this.logger?.warn(`[Hook] Command safety validation failed: ${error}`);
+            return {
+                success: false,
+                exitCode: -1,
+                stderr: error,
+                duration: Date.now() - startTime,
+                timedOut: false,
+            };
+        }
+        // Prepare environment variables
+        const env = this.buildEnvironment(context);
+        // Resolve command with environment variables
+        const resolvedCommand = this.resolveEnvironmentVariables(command, env);
+        // Prepare JSON input for stdin (if extended context is provided)
+        const isExtendedContext = "sessionId" in context ||
+            "toolInput" in context ||
+            "toolResponse" in context ||
+            "userPrompt" in context;
+        const jsonInput = isExtendedContext
+            ? buildHookJsonInput(context)
+            : null;
+        this.logger?.debug(`[Hook] Resolved command: ${resolvedCommand}`);
+        if (jsonInput) {
+            this.logger?.debug(`[Hook] JSON input: ${JSON.stringify(jsonInput)}`);
+        }
+        return new Promise((resolve) => {
+            let stdout = "";
+            let stderr = "";
+            let timedOut = false;
+            let childProcess;
+            // Setup timeout
+            const timeoutId = setTimeout(() => {
+                timedOut = true;
+                this.logger?.warn(`[Hook] Command timed out after ${timeout}ms: ${resolvedCommand}`);
+                if (childProcess && !childProcess.killed) {
+                    childProcess.kill("SIGTERM");
+                    // Force kill after 5 seconds if SIGTERM doesn't work
+                    setTimeout(() => {
+                        if (childProcess && !childProcess.killed) {
+                            this.logger?.warn(`[Hook] Force killing process: ${resolvedCommand}`);
+                            childProcess.kill("SIGKILL");
+                        }
+                    }, 5000);
+                }
+            }, timeout);
+            try {
+                // Execute command using shell for cross-platform compatibility
+                const shell = process.platform === "win32" ? "cmd.exe" : "/bin/sh";
+                const shellArgs = process.platform === "win32" ? ["/c"] : ["-c"];
+                childProcess = spawn(shell, [...shellArgs, resolvedCommand], {
+                    cwd,
+                    env,
+                    stdio: "pipe",
+                    windowsHide: true, // Hide console window on Windows
+                });
+                this.logger?.debug(`[Hook] Process started (PID: ${childProcess.pid})`);
+                // Write JSON input to stdin if available
+                if (jsonInput && childProcess.stdin) {
+                    try {
+                        const jsonString = JSON.stringify(jsonInput, null, 2);
+                        childProcess.stdin.write(jsonString);
+                        childProcess.stdin.end();
+                        this.logger?.debug(`[Hook] JSON input written to stdin`);
+                    }
+                    catch (error) {
+                        this.logger?.warn(`[Hook] Failed to write JSON to stdin: ${error}`);
+                    }
+                }
+                // Collect stdout
+                childProcess.stdout?.on("data", (data) => {
+                    stdout += data.toString();
+                });
+                // Collect stderr
+                childProcess.stderr?.on("data", (data) => {
+                    stderr += data.toString();
+                });
+                // Handle process completion
+                childProcess.on("close", (exitCode) => {
+                    clearTimeout(timeoutId);
+                    const duration = Date.now() - startTime;
+                    const success = !timedOut && exitCode === 0;
+                    // Log execution result
+                    if (success) {
+                        this.logger?.debug(`[Hook] Command completed successfully in ${duration}ms (exit code: ${exitCode})`);
+                    }
+                    else {
+                        this.logger?.warn(`[Hook] Command failed in ${duration}ms (exit code: ${exitCode}, timed out: ${timedOut})`);
+                        if (stderr) {
+                            this.logger?.warn(`[Hook] stderr: ${stderr.trim()}`);
+                        }
+                    }
+                    if (stdout && stdout.trim()) {
+                        this.logger?.debug(`[Hook] stdout: ${stdout.trim()}`);
+                    }
+                    resolve({
+                        success,
+                        exitCode: exitCode ?? undefined,
+                        stdout: stdout.trim() || undefined,
+                        stderr: stderr.trim() || undefined,
+                        duration,
+                        timedOut,
+                    });
+                });
+                // Handle process errors
+                childProcess.on("error", (error) => {
+                    clearTimeout(timeoutId);
+                    const duration = Date.now() - startTime;
+                    this.logger?.error(`[Hook] Process error in ${duration}ms: ${error.message}`);
+                    resolve({
+                        success: false,
+                        stderr: error.message,
+                        duration,
+                        timedOut,
+                    });
+                });
+            }
+            catch (error) {
+                clearTimeout(timeoutId);
+                const duration = Date.now() - startTime;
+                const errorMessage = error instanceof Error ? error.message : "Unknown execution error";
+                this.logger?.error(`[Hook] Execution error in ${duration}ms: ${errorMessage}`);
+                resolve({
+                    success: false,
+                    stderr: errorMessage,
+                    duration,
+                    timedOut,
+                });
+            }
+        });
+    }
+    /**
+     * Execute multiple commands in sequence
+     * Stops on first failure unless configured otherwise
+     */
+    async executeCommands(commands, context, options = {}) {
+        const results = [];
+        this.logger?.debug(`[Hook] Executing ${commands.length} commands in sequence for ${context.event} event`);
+        for (let i = 0; i < commands.length; i++) {
+            const command = commands[i];
+            this.logger?.debug(`[Hook] Command ${i + 1}/${commands.length}: ${command}`);
+            try {
+                const result = await this.executeCommand(command, context, options);
+                results.push(result);
+                // Stop on first failure to prevent cascading issues
+                if (!result.success) {
+                    this.logger?.warn(`[Hook] Stopping sequence at command ${i + 1} due to failure`);
+                    break;
+                }
+            }
+            catch (error) {
+                // This shouldn't happen as executeCommand handles all errors,
+                // but include defensive handling
+                const errorMessage = error instanceof Error ? error.message : "Unknown error";
+                this.logger?.error(`[Hook] Unexpected error in command ${i + 1}: ${errorMessage}`);
+                results.push({
+                    success: false,
+                    stderr: errorMessage,
+                    duration: 0,
+                    timedOut: false,
+                });
+                break;
+            }
+        }
+        const successCount = results.filter((r) => r.success).length;
+        this.logger?.debug(`[Hook] Completed sequence: ${successCount}/${results.length} commands succeeded`);
+        return results;
+    }
+    /**
+     * Validate command safety to prevent injection attacks
+     */
+    isCommandSafe(command) {
+        if (!command || typeof command !== "string")
+            return false;
+        // Command cannot be empty
+        const trimmed = command.trim();
+        if (trimmed.length === 0)
+            return false;
+        // Basic safety checks - these could be expanded based on security requirements
+        const dangerousPatterns = [
+            /\b(rm\s+-rf\s+\/|rm\s+-rf\s+~|rm\s+-rf\s+\*)/i, // Dangerous rm commands
+            /\bdd\s+if=/i, // dd commands that could be destructive
+            /:\(\)\{.*\}/, // Fork bomb patterns
+            /\beval\s*[(\s]/i, // Code evaluation
+            /\bexec\s+/i, // Process execution in shells
+        ];
+        // Check for obviously dangerous patterns
+        if (dangerousPatterns.some((pattern) => pattern.test(trimmed))) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Build environment variables for hook execution
+     */
+    buildEnvironment(context) {
+        return {
+            ...process.env, // Inherit parent environment
+            WAVE_PROJECT_DIR: context.projectDir,
+        };
+    }
+    /**
+     * Resolve environment variables in command string
+     */
+    resolveEnvironmentVariables(command, env) {
+        let resolved = command;
+        // Replace $VAR and ${VAR} patterns
+        Object.entries(env).forEach(([key, value]) => {
+            if (value !== undefined) {
+                // Handle both $VAR and ${VAR} syntax
+                const dollarPattern = new RegExp(`\\$${key}\\b`, "g");
+                const bracesPattern = new RegExp(`\\$\\{${key}\\}`, "g");
+                resolved = resolved.replace(dollarPattern, value);
+                resolved = resolved.replace(bracesPattern, value);
+            }
+        });
+        return resolved;
+    }
+    /**
+     * Get process statistics for monitoring
+     */
+    getExecutionStats() {
+        return {
+            platform: process.platform,
+            defaultTimeout: this.defaultTimeout,
+            maxTimeout: this.maxTimeout,
+        };
+    }
+    /**
+     * Test if the executor can run commands on this platform
+     */
+    isSupported() {
+        try {
+            // Try to detect shell availability - basic check could be enhanced with actual shell testing
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/hooks/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Hooks System Entry Point
+ *
+ * Exports all public APIs for the Wave Code hooks system.
+ * This module provides a clean interface for integrating hooks
+ * into AI workflows and CLI applications.
+ */
+export type { HookEvent, HookCommand, HookEventConfig, HookConfiguration, HookExecutionContext, HookExecutionResult, HookExecutionOptions, ValidationResult, HookEnvironment, } from "./types.js";
+export { isValidHookEvent, isValidHookCommand, isValidHookEventConfig, HookExecutionError, HookConfigurationError, } from "./types.js";
+export type { IHookMatcher } from "./matcher.js";
+export { HookMatcher } from "./matcher.js";
+export type { IHookExecutor } from "./executor.js";
+export { HookExecutor } from "./executor.js";
+export type { IHookManager } from "./manager.js";
+export { HookManager } from "./manager.js";
+export { getUserHooksConfigPath, getProjectHooksConfigPath, loadUserHooksConfig, loadProjectHooksConfig, loadMergedHooksConfig, hasHooksConfiguration, getHooksConfigurationInfo, } from "./settings.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,YAAY,EACV,SAAS,EACT,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG7C,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,eAAe,CAAC"}

package/dist/hooks/index.js

@@ -0,0 +1,14 @@
+/**
+ * Hooks System Entry Point
+ *
+ * Exports all public APIs for the Wave Code hooks system.
+ * This module provides a clean interface for integrating hooks
+ * into AI workflows and CLI applications.
+ */
+// Type guards and utility functions
+export { isValidHookEvent, isValidHookCommand, isValidHookEventConfig, HookExecutionError, HookConfigurationError, } from "./types.js";
+export { HookMatcher } from "./matcher.js";
+export { HookExecutor } from "./executor.js";
+export { HookManager } from "./manager.js";
+// Settings and configuration loading
+export { getUserHooksConfigPath, getProjectHooksConfigPath, loadUserHooksConfig, loadProjectHooksConfig, loadMergedHooksConfig, hasHooksConfiguration, getHooksConfigurationInfo, } from "./settings.js";

package/dist/hooks/manager.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Hook Manager
+ *
+ * Central orchestrator for the hooks system. Handles configuration loading,
+ * validation, and hook execution across all supported events.
+ */
+import { type HookEvent, type HookConfiguration, type PartialHookConfiguration, type HookExecutionContext, type ExtendedHookExecutionContext, type HookExecutionResult, type ValidationResult } from "./types.js";
+import { type IHookMatcher } from "./matcher.js";
+import { type IHookExecutor } from "./executor.js";
+import type { Logger } from "../types.js";
+export interface IHookManager {
+    loadConfiguration(userHooks?: PartialHookConfiguration, projectHooks?: PartialHookConfiguration): void;
+    loadConfigurationFromSettings(): void;
+    executeHooks(event: HookEvent, context: HookExecutionContext | ExtendedHookExecutionContext): Promise<HookExecutionResult[]>;
+    hasHooks(event: HookEvent, toolName?: string): boolean;
+    validateConfiguration(config: HookConfiguration): ValidationResult;
+    getConfiguration(): PartialHookConfiguration | undefined;
+}
+export declare class HookManager implements IHookManager {
+    private configuration;
+    private readonly matcher;
+    private readonly executor;
+    private readonly logger?;
+    private readonly workdir;
+    constructor(workdir: string, matcher?: IHookMatcher, executor?: IHookExecutor, logger?: Logger);
+    /**
+     * Load and merge hook configurations from user and project settings
+     * Project settings take precedence over user settings
+     */
+    loadConfiguration(userHooks?: PartialHookConfiguration, projectHooks?: PartialHookConfiguration): void;
+    /**
+     * Load configuration from filesystem settings
+     * Automatically loads and merges user and project hooks configuration
+     */
+    loadConfigurationFromSettings(): void;
+    /**
+     * Execute hooks for a specific event
+     */
+    executeHooks(event: HookEvent, context: HookExecutionContext | ExtendedHookExecutionContext): Promise<HookExecutionResult[]>;
+    /**
+     * Check if hooks are configured for an event/tool combination
+     */
+    hasHooks(event: HookEvent, toolName?: string): boolean;
+    /**
+     * Validate hook configuration structure and content
+     */
+    validateConfiguration(config: HookConfiguration): ValidationResult;
+    /**
+     * Validate partial hook configuration structure and content
+     */
+    private validatePartialConfiguration;
+    /**
+     * Get current configuration
+     */
+    getConfiguration(): PartialHookConfiguration | undefined;
+    /**
+     * Clear current configuration
+     */
+    clearConfiguration(): void;
+    /**
+     * Validate execution context for a specific event
+     */
+    private validateExecutionContext;
+    /**
+     * Generate a summary of hook execution results
+     */
+    private generateExecutionSummary;
+    /**
+     * Merge hook configurations, with the second taking precedence
+     */
+    private mergeHooksConfiguration;
+    /**
+     * Check if a hook configuration applies to the current context
+     */
+    private configApplies;
+    /**
+     * Validate a single event configuration
+     */
+    private validateEventConfig;
+    /**
+     * Get statistics about current configuration
+     */
+    getConfigurationStats(): {
+        totalEvents: number;
+        totalConfigs: number;
+        totalCommands: number;
+        eventBreakdown: Record<HookEvent, number>;
+    };
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/hooks/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/hooks/manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,KAAK,SAAS,EAEd,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,4BAA4B,EACjC,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EAItB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,YAAY,EAAe,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,KAAK,aAAa,EAAgB,MAAM,eAAe,CAAC;AAEjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,WAAW,YAAY;IAE3B,iBAAiB,CACf,SAAS,CAAC,EAAE,wBAAwB,EACpC,YAAY,CAAC,EAAE,wBAAwB,GACtC,IAAI,CAAC;IAGR,6BAA6B,IAAI,IAAI,CAAC;IAGtC,YAAY,CACV,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,oBAAoB,GAAG,4BAA4B,GAC3D,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAGlC,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAGvD,qBAAqB,CAAC,MAAM,EAAE,iBAAiB,GAAG,gBAAgB,CAAC;IAGnE,gBAAgB,IAAI,wBAAwB,GAAG,SAAS,CAAC;CAC1D;AAED,qBAAa,WAAY,YAAW,YAAY;IAC9C,OAAO,CAAC,aAAa,CAAuC;IAC5D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAG/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,YAAgC,EACzC,QAAQ,CAAC,EAAE,aAAa,EACxB,MAAM,CAAC,EAAE,MAAM;IAWjB;;;OAGG;IACH,iBAAiB,CACf,SAAS,CAAC,EAAE,wBAAwB,EACpC,YAAY,CAAC,EAAE,wBAAwB,GACtC,IAAI;IAyBP;;;OAGG;IACH,6BAA6B,IAAI,IAAI;IAmCrC;;OAEG;IACG,YAAY,CAChB,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,oBAAoB,GAAG,4BAA4B,GAC3D,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAsHjC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO;IAWtD;;OAEG;IACH,qBAAqB,CAAC,MAAM,EAAE,iBAAiB,GAAG,gBAAgB;IA8ClE;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAyCpC;;OAEG;IACH,gBAAgB,IAAI,wBAAwB,GAAG,SAAS;IAOxD;;OAEG;IACH,kBAAkB,IAAI,IAAI;IAI1B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAmDhC;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA8BhC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAa/B;;OAEG;IACH,OAAO,CAAC,aAAa;IA4BrB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAqC3B;;OAEG;IACH,qBAAqB,IAAI;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;KAC3C;CA2CF"}