wave-agent-sdk 0.0.7 → 0.0.8

package/dist/services/fileWatcher.js

@@ -0,0 +1,213 @@
+/**
+ * File Watcher Service
+ *
+ * Provides robust cross-platform file watching using Chokidar library.
+ * Handles file watching with debouncing, error recovery, and graceful fallbacks.
+ */
+import * as chokidar from "chokidar";
+import { EventEmitter } from "events";
+import { FILE_WATCHER_EVENTS } from "../constants/events.js";
+export class FileWatcherService extends EventEmitter {
+    constructor(logger, config) {
+        super();
+        this.watchers = new Map();
+        this.globalWatcher = null;
+        this.logger = logger;
+        this.defaultConfig = {
+            stabilityThreshold: 300,
+            pollInterval: 100,
+            maxRetries: 3,
+            fallbackPolling: false,
+            ignoreTempFiles: true,
+            ...config,
+        };
+    }
+    /**
+     * Start watching a file
+     * Maps to FR-010: Handle file deletion, creation, and modification
+     */
+    async watchFile(path, callback) {
+        try {
+            if (this.watchers.has(path)) {
+                // Add callback to existing watcher
+                const entry = this.watchers.get(path);
+                entry.callbacks.add(callback);
+                return;
+            }
+            // Create new watcher entry
+            const entry = {
+                path,
+                watcher: null,
+                isActive: false,
+                lastEvent: Date.now(),
+                errorCount: 0,
+                lastError: undefined,
+                callbacks: new Set([callback]),
+                config: { ...this.defaultConfig },
+            };
+            this.watchers.set(path, entry);
+            await this.initializeWatcher(entry);
+        }
+        catch (error) {
+            this.logger?.error(`Live Config: Failed to watch file ${path}: ${error.message}`);
+            throw error;
+        }
+    }
+    /**
+     * Stop watching a file
+     * Resource cleanup
+     */
+    async unwatchFile(path) {
+        const entry = this.watchers.get(path);
+        if (!entry)
+            return;
+        try {
+            if (entry.watcher) {
+                entry.watcher.unwatch(path);
+            }
+            this.watchers.delete(path);
+            this.logger?.info(`Live Config: Stopped watching file: ${path}`);
+        }
+        catch (error) {
+            this.logger?.warn(`Live Config: Error unwatching file ${path}: ${error.message}`);
+        }
+    }
+    /**
+     * Get watcher status
+     * Maps to FR-012: Handle watcher initialization failures
+     */
+    getWatcherStatus(path) {
+        const entry = this.watchers.get(path);
+        if (!entry)
+            return null;
+        return {
+            isActive: entry.isActive,
+            path: entry.path,
+            method: entry.errorCount > 0
+                ? "failed"
+                : entry.config.fallbackPolling
+                    ? "polling"
+                    : "native",
+            errorCount: entry.errorCount,
+            lastError: entry.lastError,
+            lastEvent: entry.lastEvent > 0
+                ? {
+                    type: FILE_WATCHER_EVENTS.CHANGE,
+                    path: entry.path,
+                    timestamp: entry.lastEvent,
+                }
+                : undefined,
+        };
+    }
+    /**
+     * Get all watcher statuses
+     * For monitoring and debugging
+     */
+    getAllWatcherStatuses() {
+        return Array.from(this.watchers.keys())
+            .map((path) => this.getWatcherStatus(path))
+            .filter((status) => status !== null);
+    }
+    /**
+     * Configure watcher behavior
+     * Runtime configuration updates
+     */
+    updateConfig(config) {
+        this.defaultConfig = { ...this.defaultConfig, ...config };
+        // Update existing watchers with new config
+        for (const entry of this.watchers.values()) {
+            entry.config = { ...entry.config, ...config };
+        }
+    }
+    /**
+     * Cleanup all watchers
+     */
+    async cleanup() {
+        const paths = Array.from(this.watchers.keys());
+        await Promise.all(paths.map((path) => this.unwatchFile(path)));
+        if (this.globalWatcher) {
+            await this.globalWatcher.close();
+            this.globalWatcher = null;
+        }
+    }
+    async initializeWatcher(entry) {
+        try {
+            // Initialize global watcher if needed
+            if (!this.globalWatcher) {
+                this.globalWatcher = chokidar.watch([], {
+                    persistent: true,
+                    ignoreInitial: true,
+                    awaitWriteFinish: {
+                        stabilityThreshold: entry.config.stabilityThreshold,
+                        pollInterval: entry.config.pollInterval,
+                    },
+                    usePolling: entry.config.fallbackPolling,
+                    interval: entry.config.pollInterval,
+                });
+                this.setupGlobalWatcherEvents();
+            }
+            // Add path to global watcher
+            this.globalWatcher.add(entry.path);
+            entry.watcher = this.globalWatcher;
+            entry.isActive = true;
+            entry.errorCount = 0;
+            this.logger?.info(`Live Config: Started watching file: ${entry.path}`);
+        }
+        catch (error) {
+            entry.errorCount++;
+            entry.isActive = false;
+            entry.lastError = error.message;
+            this.logger?.error(`Live Config: Failed to initialize watcher for ${entry.path}: ${error.message}`);
+            // Try fallback polling if not already using it
+            if (!entry.config.fallbackPolling &&
+                entry.errorCount < entry.config.maxRetries) {
+                this.logger?.info(`Live Config: Attempting polling fallback for ${entry.path}`);
+                entry.config.fallbackPolling = true;
+                await this.initializeWatcher(entry);
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    setupGlobalWatcherEvents() {
+        if (!this.globalWatcher)
+            return;
+        this.globalWatcher.on(FILE_WATCHER_EVENTS.CHANGE, (filePath, stats) => {
+            this.handleFileEvent(FILE_WATCHER_EVENTS.CHANGE, filePath, stats);
+        });
+        this.globalWatcher.on("add", (filePath, stats) => {
+            this.handleFileEvent(FILE_WATCHER_EVENTS.CREATE, filePath, stats);
+        });
+        this.globalWatcher.on("unlink", (filePath) => {
+            this.handleFileEvent(FILE_WATCHER_EVENTS.DELETE, filePath);
+        });
+        this.globalWatcher.on("error", (err) => {
+            const error = err instanceof Error ? err : new Error(String(err));
+            this.logger?.error(`Live Config: File watcher error: ${error.message}`);
+            this.emit("watcherError", error);
+        });
+    }
+    handleFileEvent(type, filePath, stats) {
+        const entry = this.watchers.get(filePath);
+        if (!entry)
+            return;
+        const event = {
+            type,
+            path: filePath,
+            timestamp: Date.now(),
+            size: stats?.size,
+        };
+        entry.lastEvent = event.timestamp;
+        // Notify all callbacks for this file
+        for (const callback of entry.callbacks) {
+            try {
+                callback(event);
+            }
+            catch (error) {
+                this.logger?.error(`Live Config: Error in file watch callback for ${filePath}: ${error.message}`);
+            }
+        }
+        this.logger?.debug(`Live Config: File ${type} event for ${filePath}`);
+    }
+}

package/dist/services/hook.d.ts

@@ -4,53 +4,135 @@
  * Consolidated hook services providing both execution and configuration functionality.
  * Combines hook command execution and settings management into a single module.
  */
-import { type HookExecutionContext, type HookExecutionResult, type HookExecutionOptions, type ExtendedHookExecutionContext, type PartialHookConfiguration } from "../types/hooks.js";
+import { type HookExecutionContext, type HookExecutionResult, type HookExecutionOptions, type ExtendedHookExecutionContext, type WaveConfiguration, type PartialHookConfiguration } from "../types/hooks.js";
+import { type EnvironmentValidationResult, type MergedEnvironmentContext, type EnvironmentMergeOptions } from "../types/environment.js";
 /**
  * Execute a single hook command
  */
-export declare function executeCommand(command: string, context: HookExecutionContext | ExtendedHookExecutionContext, options?: HookExecutionOptions): Promise<HookExecutionResult>;
+export declare function executeCommand(command: string, context: HookExecutionContext | ExtendedHookExecutionContext, options?: HookExecutionOptions, additionalEnvVars?: Record<string, string>): Promise<HookExecutionResult>;
 /**
  * Execute multiple commands in sequence
  */
-export declare function executeCommands(commands: string[], context: HookExecutionContext | ExtendedHookExecutionContext, options?: HookExecutionOptions): Promise<HookExecutionResult[]>;
+export declare function executeCommands(commands: string[], context: HookExecutionContext | ExtendedHookExecutionContext, options?: HookExecutionOptions, additionalEnvVars?: Record<string, string>): Promise<HookExecutionResult[]>;
 /**
  * Validate command safety (basic checks)
  */
 export declare function isCommandSafe(command: string): boolean;
 /**
- * Get the user-specific hooks configuration file path
+ * Validate environment variable configuration
+ */
+export declare function validateEnvironmentConfig(env: unknown, configPath?: string): EnvironmentValidationResult;
+/**
+ * Merge environment configurations with project taking precedence over user
+ */
+export declare function mergeEnvironmentConfig(userEnv: Record<string, string> | undefined, projectEnv: Record<string, string> | undefined, options?: EnvironmentMergeOptions): MergedEnvironmentContext;
+/**
+ * Get the user-specific hooks configuration file path (legacy function)
+ * @deprecated Use getUserConfigPaths() from configPaths.ts for better priority support
  */
 export declare function getUserHooksConfigPath(): string;
 /**
- * Get the project-specific hooks configuration file path
+ * Get the project-specific hooks configuration file path (legacy function)
+ * @deprecated Use getProjectConfigPaths() from configPaths.ts for better priority support
  */
 export declare function getProjectHooksConfigPath(workdir: string): string;
 /**
- * Load hooks configuration from a JSON file
+ * Get the user-specific hooks configuration file paths in priority order
+ * @deprecated Use getUserConfigPaths() from configPaths.ts directly
+ */
+export declare function getUserHooksConfigPaths(): string[];
+/**
+ * Get the project-specific hooks configuration file paths in priority order
+ * @deprecated Use getProjectConfigPaths() from configPaths.ts directly
+ */
+export declare function getProjectHooksConfigPaths(workdir: string): string[];
+/**
+ * Load Wave configuration from a JSON file with graceful fallback
+ * This version is optimized for live reload scenarios where invalid config should not crash the system
+ */
+export declare function loadWaveConfigFromFileWithFallback(filePath: string, previousValidConfig?: WaveConfiguration | null): {
+    config: WaveConfiguration | null;
+    error?: string;
+    usedFallback: boolean;
+};
+/**
+ * Load Wave configuration from multiple file paths in priority order
+ * Returns the first valid configuration found, or null if none exist
+ */
+export declare function loadWaveConfigFromFiles(filePaths: string[]): WaveConfiguration | null;
+/**
+ * Load Wave configuration from multiple file paths with graceful fallback
+ * Returns the first valid configuration found with fallback support
+ */
+export declare function loadWaveConfigFromFilesWithFallback(filePaths: string[], previousValidConfig?: WaveConfiguration | null): {
+    config: WaveConfiguration | null;
+    error?: string;
+    usedFallback: boolean;
+    usedPath?: string;
+};
+/**
+ * Load and merge Wave configuration with graceful fallback for live reload
+ * Provides error recovery by falling back to previous valid configuration
+ */
+export declare function loadMergedWaveConfigWithFallback(workdir: string, previousValidConfig?: WaveConfiguration | null): {
+    config: WaveConfiguration | null;
+    errors: string[];
+    usedFallback: boolean;
+};
+/**
+ * Load Wave configuration from a JSON file
+ * Supports both hooks and environment variables with proper validation
+ */
+export declare function loadWaveConfigFromFile(filePath: string): WaveConfiguration | null;
+/**
+ * Load hooks configuration from a JSON file (legacy function)
  */
 export declare function loadHooksConfigFromFile(filePath: string): PartialHookConfiguration | null;
 /**
- * Load user-specific hooks configuration
+ * Load user-specific Wave configuration
+ * Checks .local.json first, then falls back to .json
+ */
+export declare function loadUserWaveConfig(): WaveConfiguration | null;
+/**
+ * Load project-specific Wave configuration
+ * Checks .local.json first, then falls back to .json
+ */
+export declare function loadProjectWaveConfig(workdir: string): WaveConfiguration | null;
+/**
+ * Load user-specific hooks configuration (legacy function)
  */
 export declare function loadUserHooksConfig(): PartialHookConfiguration | null;
 /**
- * Load project-specific hooks configuration
+ * Load project-specific hooks configuration (legacy function)
  */
 export declare function loadProjectHooksConfig(workdir: string): PartialHookConfiguration | null;
 /**
- * Load and merge hooks configuration from both user and project sources
+ * Load and merge Wave configuration from both user and project sources
+ * Project configuration takes precedence over user configuration
+ * Checks .local.json files first, then falls back to .json files
+ */
+export declare function loadMergedWaveConfig(workdir: string): WaveConfiguration | null;
+/**
+ * Load and merge hooks configuration from both user and project sources (legacy function)
  */
 export declare function loadMergedHooksConfig(workdir: string): PartialHookConfiguration | null;
 /**
  * Check if hooks configuration exists (user or project)
+ * Checks both .local.json and .json variants
+ * @deprecated Use hasAnyConfig() from configPaths.ts for better functionality
  */
 export declare function hasHooksConfiguration(workdir: string): boolean;
 /**
  * Get hooks configuration information for debugging
+ * Includes both .local.json and .json variants
+ * @deprecated Use getConfigurationInfo() from configPaths.ts for better functionality
  */
 export declare function getHooksConfigurationInfo(workdir: string): {
     hasUser: boolean;
     hasProject: boolean;
     paths: string[];
+    userPaths: string[];
+    projectPaths: string[];
+    existingPaths: string[];
 };
 //# sourceMappingURL=hook.d.ts.map

package/dist/services/hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../src/services/hook.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,4BAA4B,EAGjC,KAAK,wBAAwB,EAG9B,MAAM,mBAAmB,CAAC;AA6C3B;;GAEG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,oBAAoB,GAAG,4BAA4B,EAC5D,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,CAiH9B;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,EAAE,oBAAoB,GAAG,4BAA4B,EAC5D,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAchC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAsBtD;AAMD;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,GACf,wBAAwB,GAAG,IAAI,CAcjC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,wBAAwB,GAAG,IAAI,CAErE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,GACd,wBAAwB,GAAG,IAAI,CAEjC;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,GACd,wBAAwB,GAAG,IAAI,CAiCjC;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAK9D;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CASA"}
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../src/services/hook.ts"],"names":[],"mappings":"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"}