wave-agent-sdk 0.0.7 → 0.0.10

package/src/services/fileWatcher.ts

@@ -0,0 +1,300 @@
+/**
+ * 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 type { Logger } from "../types/index.js";
+
+export interface FileWatchEvent {
+  type: "change" | "create" | "delete" | "rename";
+  path: string;
+  timestamp: number;
+  size?: number;
+}
+
+export interface FileWatcherConfig {
+  stabilityThreshold: number; // Chokidar awaitWriteFinish delay (ms)
+  pollInterval: number; // Chokidar polling interval (ms)
+  maxRetries: number; // Default: 3
+  fallbackPolling: boolean; // Default: false
+  ignoreTempFiles: boolean; // Default: true
+}
+
+export interface FileWatcherStatus {
+  isActive: boolean;
+  path: string;
+  method: "native" | "polling" | "failed";
+  errorCount: number;
+  lastError?: string;
+  lastEvent?: FileWatchEvent;
+}
+
+interface FileWatcherEntry {
+  path: string;
+  watcher: chokidar.FSWatcher | null;
+  isActive: boolean;
+  lastEvent: number;
+  errorCount: number;
+  lastError?: string;
+  callbacks: Set<(event: FileWatchEvent) => void>;
+  config: FileWatcherConfig;
+}
+
+export class FileWatcherService extends EventEmitter {
+  private watchers: Map<string, FileWatcherEntry> = new Map();
+  private globalWatcher: chokidar.FSWatcher | null = null;
+  private defaultConfig: FileWatcherConfig;
+  private logger?: Logger;
+
+  constructor(logger?: Logger, config?: Partial<FileWatcherConfig>) {
+    super();
+    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: string,
+    callback: (event: FileWatchEvent) => void,
+  ): Promise<void> {
+    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: FileWatcherEntry = {
+        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 as Error).message}`,
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Stop watching a file
+   * Resource cleanup
+   */
+  async unwatchFile(path: string): Promise<void> {
+    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 as Error).message}`,
+      );
+    }
+  }
+
+  /**
+   * Get watcher status
+   * Maps to FR-012: Handle watcher initialization failures
+   */
+  getWatcherStatus(path: string): FileWatcherStatus | null {
+    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: "change",
+              path: entry.path,
+              timestamp: entry.lastEvent,
+            }
+          : undefined,
+    };
+  }
+
+  /**
+   * Get all watcher statuses
+   * For monitoring and debugging
+   */
+  getAllWatcherStatuses(): FileWatcherStatus[] {
+    return Array.from(this.watchers.keys())
+      .map((path) => this.getWatcherStatus(path))
+      .filter((status): status is FileWatcherStatus => status !== null);
+  }
+
+  /**
+   * Configure watcher behavior
+   * Runtime configuration updates
+   */
+  updateConfig(config: Partial<FileWatcherConfig>): void {
+    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(): Promise<void> {
+    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;
+    }
+  }
+
+  private async initializeWatcher(entry: FileWatcherEntry): Promise<void> {
+    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 as Error).message;
+
+      this.logger?.error(
+        `Live Config: Failed to initialize watcher for ${entry.path}: ${(error as 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;
+      }
+    }
+  }
+
+  private setupGlobalWatcherEvents(): void {
+    if (!this.globalWatcher) return;
+
+    this.globalWatcher.on(
+      "change",
+      (filePath: string, stats?: { size?: number }) => {
+        this.handleFileEvent("change", filePath, stats);
+      },
+    );
+
+    this.globalWatcher.on(
+      "add",
+      (filePath: string, stats?: { size?: number }) => {
+        this.handleFileEvent("create", filePath, stats);
+      },
+    );
+
+    this.globalWatcher.on("unlink", (filePath: string) => {
+      this.handleFileEvent("delete", filePath);
+    });
+
+    this.globalWatcher.on("error", (err: unknown) => {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.logger?.error(`Live Config: File watcher error: ${error.message}`);
+      this.emit("watcherError", error);
+    });
+  }
+
+  private handleFileEvent(
+    type: FileWatchEvent["type"],
+    filePath: string,
+    stats?: { size?: number },
+  ): void {
+    const entry = this.watchers.get(filePath);
+    if (!entry) return;
+
+    const event: FileWatchEvent = {
+      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 as Error).message}`,
+        );
+      }
+    }
+
+    this.logger?.debug(`Live Config: File ${type} event for ${filePath}`);
+  }
+}

package/src/services/hook.ts

@@ -1,25 +1,20 @@
 /**
- * Hook Services
+ * Hook Execution Services
  *
- * Consolidated hook services providing both execution and configuration functionality.
- * Combines hook command execution and settings management into a single module.
+ * Provides hook command execution functionality and hook-specific configuration loading.
+ * This module focuses on hook execution while delegating general Wave configuration
+ * management to ConfigurationService.
  */
 
 import { spawn, type ChildProcess } from "child_process";
-import { existsSync, readFileSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
 import {
   type HookExecutionContext,
   type HookExecutionResult,
   type HookExecutionOptions,
   type ExtendedHookExecutionContext,
   type HookJsonInput,
-  type HookConfiguration,
-  type PartialHookConfiguration,
-  getSessionFilePath,
-  isValidHookEvent,
 } from "../types/hooks.js";
+import { generateSessionFilePath } from "./session.js";
 
 // =============================================================================
 // Hook Execution Functions
@@ -28,15 +23,27 @@ import {
 /**
  * Build JSON input data for hook stdin
  */
-function buildHookJsonInput(
+async function buildHookJsonInput(
   context: ExtendedHookExecutionContext,
-): HookJsonInput {
+): Promise<HookJsonInput> {
+  const workdir = context.cwd || context.projectDir || process.cwd();
+
+  let transcriptPath = context.transcriptPath;
+  if (!transcriptPath && context.sessionId) {
+    try {
+      transcriptPath = await generateSessionFilePath(
+        context.sessionId,
+        workdir,
+      );
+    } catch {
+      transcriptPath = "";
+    }
+  }
+
   const jsonInput: HookJsonInput = {
     session_id: context.sessionId || "unknown",
-    transcript_path:
-      context.transcriptPath ||
-      (context.sessionId ? getSessionFilePath(context.sessionId) : ""),
-    cwd: context.cwd || context.projectDir,
+    transcript_path: transcriptPath || "",
+    cwd: workdir,
     hook_event_name: context.event,
   };
 
@@ -61,6 +68,21 @@ function buildHookJsonInput(
     jsonInput.user_prompt = context.userPrompt;
   }
 
+  // Add subagent_type if present
+  if (context.subagentType !== undefined) {
+    jsonInput.subagent_type = context.subagentType;
+  }
+
+  // Add notification fields for Notification events
+  if (context.event === "Notification") {
+    if (context.message !== undefined) {
+      jsonInput.message = context.message;
+    }
+    if (context.notificationType !== undefined) {
+      jsonInput.notification_type = context.notificationType;
+    }
+  }
+
   return jsonInput;
 }
 
@@ -93,6 +115,17 @@ export async function executeCommand(
     };
   }
 
+  // Prepare JSON input for hooks that need it
+  let jsonInput: string | null = null;
+  if ("sessionId" in context) {
+    try {
+      const hookJsonInput = await buildHookJsonInput(context);
+      jsonInput = JSON.stringify(hookJsonInput, null, 2);
+    } catch {
+      // Continue execution even if JSON input preparation fails
+    }
+  }
+
   return new Promise((resolve) => {
     let stdout = "";
     let stderr = "";
@@ -107,7 +140,8 @@ export async function executeCommand(
       stdio: ["pipe", "pipe", "pipe"],
       cwd: context.projectDir,
       env: {
-        ...process.env,
+        ...process.env, // Environment variables from process.env
+        ...("env" in context ? context.env || {} : {}), // Additional environment variables from configuration (if ExtendedHookExecutionContext)
         HOOK_EVENT: context.event,
         HOOK_TOOL_NAME: context.toolName || "",
         HOOK_PROJECT_DIR: context.projectDir,
@@ -141,11 +175,10 @@ export async function executeCommand(
       });
     }
 
-    // Send JSON input to stdin if we have extended context
-    if (childProcess.stdin && "sessionId" in context) {
+    // Send JSON input to stdin if we have prepared it
+    if (childProcess.stdin && jsonInput) {
       try {
-        const jsonInput = buildHookJsonInput(context);
-        childProcess.stdin.write(JSON.stringify(jsonInput, null, 2));
+        childProcess.stdin.write(jsonInput);
         childProcess.stdin.end();
       } catch {
         // Continue execution even if JSON input fails
@@ -235,126 +268,3 @@ export function isCommandSafe(command: string): boolean {
     pattern.test(trimmed.toLowerCase()),
   );
 }
-
-// =============================================================================
-// Hook Settings Functions
-// =============================================================================
-
-/**
- * Get the user-specific hooks configuration file path
- */
-export function getUserHooksConfigPath(): string {
-  return join(homedir(), ".wave", "settings.json");
-}
-
-/**
- * Get the project-specific hooks configuration file path
- */
-export function getProjectHooksConfigPath(workdir: string): string {
-  return join(workdir, ".wave", "settings.json");
-}
-
-/**
- * Load hooks configuration from a JSON file
- */
-export function loadHooksConfigFromFile(
-  filePath: string,
-): PartialHookConfiguration | null {
-  if (!existsSync(filePath)) {
-    return null;
-  }
-
-  const content = readFileSync(filePath, "utf-8");
-  const config = JSON.parse(content) as HookConfiguration;
-
-  // Validate basic structure
-  if (!config || typeof config !== "object" || !config.hooks) {
-    throw new Error(`Invalid hooks configuration structure in ${filePath}`);
-  }
-
-  return config.hooks;
-}
-
-/**
- * Load user-specific hooks configuration
- */
-export function loadUserHooksConfig(): PartialHookConfiguration | null {
-  return loadHooksConfigFromFile(getUserHooksConfigPath());
-}
-
-/**
- * Load project-specific hooks configuration
- */
-export function loadProjectHooksConfig(
-  workdir: string,
-): PartialHookConfiguration | null {
-  return loadHooksConfigFromFile(getProjectHooksConfigPath(workdir));
-}
-
-/**
- * Load and merge hooks configuration from both user and project sources
- */
-export function loadMergedHooksConfig(
-  workdir: string,
-): PartialHookConfiguration | null {
-  const userConfig = loadUserHooksConfig();
-  const projectConfig = loadProjectHooksConfig(workdir);
-
-  // No configuration found
-  if (!userConfig && !projectConfig) {
-    return null;
-  }
-
-  // Only one configuration found
-  if (!userConfig) return projectConfig;
-  if (!projectConfig) return userConfig;
-
-  // Merge configurations (project overrides user)
-  const merged: PartialHookConfiguration = {};
-
-  // Combine all hook events
-  const allEvents = new Set([
-    ...Object.keys(userConfig),
-    ...Object.keys(projectConfig),
-  ]);
-
-  for (const event of allEvents) {
-    if (!isValidHookEvent(event)) continue;
-
-    const userEventConfigs = userConfig[event] || [];
-    const projectEventConfigs = projectConfig[event] || [];
-
-    // Project configurations take precedence
-    merged[event] = [...userEventConfigs, ...projectEventConfigs];
-  }
-
-  return merged;
-}
-
-/**
- * Check if hooks configuration exists (user or project)
- */
-export function hasHooksConfiguration(workdir: string): boolean {
-  return (
-    existsSync(getUserHooksConfigPath()) ||
-    existsSync(getProjectHooksConfigPath(workdir))
-  );
-}
-
-/**
- * Get hooks configuration information for debugging
- */
-export function getHooksConfigurationInfo(workdir: string): {
-  hasUser: boolean;
-  hasProject: boolean;
-  paths: string[];
-} {
-  const userPath = getUserHooksConfigPath();
-  const projectPath = getProjectHooksConfigPath(workdir);
-
-  return {
-    hasUser: existsSync(userPath),
-    hasProject: existsSync(projectPath),
-    paths: [userPath, projectPath],
-  };
-}