wave-agent-sdk 0.0.8 → 0.0.10

package/src/services/hook.ts

@@ -1,37 +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 {
-  getUserConfigPath,
-  getProjectConfigPath,
-  getUserConfigPaths,
-  getProjectConfigPaths,
-  hasAnyConfig,
-  getConfigurationInfo,
-} from "../utils/configPaths.js";
 import {
   type HookExecutionContext,
   type HookExecutionResult,
   type HookExecutionOptions,
   type ExtendedHookExecutionContext,
   type HookJsonInput,
-  type WaveConfiguration,
-  type PartialHookConfiguration,
-  getSessionFilePath,
-  isValidHookEvent,
 } from "../types/hooks.js";
-import {
-  type EnvironmentValidationResult,
-  type MergedEnvironmentContext,
-  type EnvironmentMergeOptions,
-  isValidEnvironmentVars,
-} from "../types/environment.js";
+import { generateSessionFilePath } from "./session.js";
 
 // =============================================================================
 // Hook Execution Functions
@@ -40,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,
   };
 
@@ -78,6 +73,16 @@ function buildHookJsonInput(
     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;
 }
 
@@ -88,7 +93,6 @@ export async function executeCommand(
   command: string,
   context: HookExecutionContext | ExtendedHookExecutionContext,
   options?: HookExecutionOptions,
-  additionalEnvVars?: Record<string, string>,
 ): Promise<HookExecutionResult> {
   const defaultTimeout = 10000; // 10 seconds
   const maxTimeout = 300000; // 5 minutes
@@ -111,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 = "";
@@ -125,8 +140,8 @@ export async function executeCommand(
       stdio: ["pipe", "pipe", "pipe"],
       cwd: context.projectDir,
       env: {
-        ...process.env,
-        ...additionalEnvVars, // Merge additional environment variables from Wave configuration
+        ...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,
@@ -160,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
@@ -212,17 +226,11 @@ export async function executeCommands(
   commands: string[],
   context: HookExecutionContext | ExtendedHookExecutionContext,
   options?: HookExecutionOptions,
-  additionalEnvVars?: Record<string, string>,
 ): Promise<HookExecutionResult[]> {
   const results: HookExecutionResult[] = [];
 
   for (const command of commands) {
-    const result = await executeCommand(
-      command,
-      context,
-      options,
-      additionalEnvVars,
-    );
+    const result = await executeCommand(command, context, options);
     results.push(result);
 
     // Stop on first failure unless continueOnFailure is set
@@ -260,592 +268,3 @@ export function isCommandSafe(command: string): boolean {
     pattern.test(trimmed.toLowerCase()),
   );
 }
-
-// =============================================================================
-// Environment Variable Functions
-// =============================================================================
-
-/**
- * Validate environment variable configuration
- */
-export function validateEnvironmentConfig(
-  env: unknown,
-  configPath?: string,
-): EnvironmentValidationResult {
-  const result: EnvironmentValidationResult = {
-    isValid: true,
-    errors: [],
-    warnings: [],
-  };
-
-  // Check if env is defined
-  if (env === undefined || env === null) {
-    return result; // undefined/null env is valid (means no env vars)
-  }
-
-  // Validate that env is a Record<string, string>
-  if (!isValidEnvironmentVars(env)) {
-    result.isValid = false;
-    result.errors.push(
-      `Invalid env field format${configPath ? ` in ${configPath}` : ""}. Environment variables must be a Record<string, string>.`,
-    );
-    return result;
-  }
-
-  // Additional validation for environment variable names
-  const envVars = env as Record<string, string>;
-  for (const [key, value] of Object.entries(envVars)) {
-    // Check for valid environment variable naming convention
-    if (!/^[A-Z_][A-Z0-9_]*$/i.test(key)) {
-      result.warnings.push(
-        `Environment variable '${key}' does not follow standard naming convention (alphanumeric and underscores only).`,
-      );
-    }
-
-    // Check for empty values
-    if (value === "") {
-      result.warnings.push(`Environment variable '${key}' has an empty value.`);
-    }
-
-    // Check for reserved variable names that might cause conflicts
-    const reservedNames = [
-      "PATH",
-      "HOME",
-      "USER",
-      "PWD",
-      "SHELL",
-      "TERM",
-      "NODE_ENV",
-    ];
-    if (reservedNames.includes(key.toUpperCase())) {
-      result.warnings.push(
-        `Environment variable '${key}' overrides a system variable, which may cause unexpected behavior.`,
-      );
-    }
-  }
-
-  return result;
-}
-
-/**
- * Merge environment configurations with project taking precedence over user
- */
-export function mergeEnvironmentConfig(
-  userEnv: Record<string, string> | undefined,
-  projectEnv: Record<string, string> | undefined,
-  options: EnvironmentMergeOptions = {},
-): MergedEnvironmentContext {
-  const userVars = userEnv || {};
-  const projectVars = projectEnv || {};
-  const mergedVars: Record<string, string> = {};
-  const conflicts: MergedEnvironmentContext["conflicts"] = [];
-
-  // Start with user environment variables
-  Object.assign(mergedVars, userVars);
-
-  // Override with project environment variables and track conflicts
-  for (const [key, projectValue] of Object.entries(projectVars)) {
-    const userValue = userVars[key];
-
-    if (
-      userValue !== undefined &&
-      userValue !== projectValue &&
-      options.includeConflictWarnings !== false
-    ) {
-      // Conflict detected - project value takes precedence
-      conflicts.push({
-        key,
-        userValue,
-        projectValue,
-        resolvedValue: projectValue,
-      });
-    }
-
-    mergedVars[key] = projectValue;
-  }
-
-  return {
-    userVars,
-    projectVars,
-    mergedVars,
-    conflicts,
-  };
-}
-
-// =============================================================================
-// Hook Settings Functions (using centralized config path utilities)
-// =============================================================================
-
-/**
- * Get the user-specific hooks configuration file path (legacy function)
- * @deprecated Use getUserConfigPaths() from configPaths.ts for better priority support
- */
-export function getUserHooksConfigPath(): string {
-  return getUserConfigPath();
-}
-
-/**
- * Get the project-specific hooks configuration file path (legacy function)
- * @deprecated Use getProjectConfigPaths() from configPaths.ts for better priority support
- */
-export function getProjectHooksConfigPath(workdir: string): string {
-  return getProjectConfigPath(workdir);
-}
-
-/**
- * Get the user-specific hooks configuration file paths in priority order
- * @deprecated Use getUserConfigPaths() from configPaths.ts directly
- */
-export function getUserHooksConfigPaths(): string[] {
-  return getUserConfigPaths();
-}
-
-/**
- * Get the project-specific hooks configuration file paths in priority order
- * @deprecated Use getProjectConfigPaths() from configPaths.ts directly
- */
-export function getProjectHooksConfigPaths(workdir: string): string[] {
-  return getProjectConfigPaths(workdir);
-}
-
-/**
- * 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 function loadWaveConfigFromFileWithFallback(
-  filePath: string,
-  previousValidConfig?: WaveConfiguration | null,
-): { config: WaveConfiguration | null; error?: string; usedFallback: boolean } {
-  if (!existsSync(filePath)) {
-    return { config: null, usedFallback: false };
-  }
-
-  try {
-    const content = readFileSync(filePath, "utf-8");
-    const config = JSON.parse(content) as WaveConfiguration;
-
-    // Validate basic structure
-    if (!config || typeof config !== "object") {
-      const error = `Invalid configuration structure in ${filePath}`;
-      return {
-        config: previousValidConfig || null,
-        error,
-        usedFallback: !!previousValidConfig,
-      };
-    }
-
-    // Validate environment variables if present
-    if (config.env !== undefined) {
-      const envValidation = validateEnvironmentConfig(config.env, filePath);
-
-      if (!envValidation.isValid) {
-        const error = `Environment variable validation failed in ${filePath}: ${envValidation.errors.join(", ")}`;
-        return {
-          config: previousValidConfig || null,
-          error,
-          usedFallback: !!previousValidConfig,
-        };
-      }
-
-      // Log warnings if any
-      if (envValidation.warnings.length > 0) {
-        console.warn(
-          `Environment variable warnings in ${filePath}:\n- ${envValidation.warnings.join("\n- ")}`,
-        );
-      }
-    }
-
-    // Return valid configuration
-    return {
-      config: {
-        hooks: config.hooks || undefined,
-        env: config.env || undefined,
-      },
-      usedFallback: false,
-    };
-  } catch (error) {
-    let errorMessage: string;
-
-    if (error instanceof SyntaxError) {
-      errorMessage = `Invalid JSON syntax in ${filePath}: ${error.message}`;
-    } else {
-      errorMessage = `Error loading configuration from ${filePath}: ${(error as Error).message}`;
-    }
-
-    return {
-      config: previousValidConfig || null,
-      error: errorMessage,
-      usedFallback: !!previousValidConfig,
-    };
-  }
-}
-
-/**
- * Load Wave configuration from multiple file paths in priority order
- * Returns the first valid configuration found, or null if none exist
- */
-export function loadWaveConfigFromFiles(
-  filePaths: string[],
-): WaveConfiguration | null {
-  for (const filePath of filePaths) {
-    const config = loadWaveConfigFromFile(filePath);
-    if (config !== null) {
-      return config;
-    }
-  }
-  return null;
-}
-
-/**
- * Load Wave configuration from multiple file paths with graceful fallback
- * Returns the first valid configuration found with fallback support
- */
-export function loadWaveConfigFromFilesWithFallback(
-  filePaths: string[],
-  previousValidConfig?: WaveConfiguration | null,
-): {
-  config: WaveConfiguration | null;
-  error?: string;
-  usedFallback: boolean;
-  usedPath?: string;
-} {
-  let lastError: string | undefined;
-
-  for (const filePath of filePaths) {
-    const result = loadWaveConfigFromFileWithFallback(
-      filePath,
-      previousValidConfig,
-    );
-
-    if (result.config !== null && !result.usedFallback) {
-      // Found a valid config at this path
-      return {
-        config: result.config,
-        error: result.error,
-        usedFallback: result.usedFallback,
-        usedPath: filePath,
-      };
-    }
-
-    if (result.error) {
-      lastError = result.error;
-    }
-  }
-
-  // No valid config found in any path
-  return {
-    config: previousValidConfig || null,
-    error: lastError,
-    usedFallback: !!previousValidConfig,
-  };
-}
-
-/**
- * Load and merge Wave configuration with graceful fallback for live reload
- * Provides error recovery by falling back to previous valid configuration
- */
-export function loadMergedWaveConfigWithFallback(
-  workdir: string,
-  previousValidConfig?: WaveConfiguration | null,
-): {
-  config: WaveConfiguration | null;
-  errors: string[];
-  usedFallback: boolean;
-} {
-  const errors: string[] = [];
-  let usedFallback = false;
-
-  // Load user config with fallback (check .local.json first, then .json)
-  const userResult = loadWaveConfigFromFilesWithFallback(
-    getUserHooksConfigPaths(),
-    previousValidConfig,
-  );
-  if (userResult.error) {
-    errors.push(`User config: ${userResult.error}`);
-  }
-  if (userResult.usedFallback) {
-    usedFallback = true;
-  }
-
-  // Load project config with fallback (check .local.json first, then .json)
-  const projectResult = loadWaveConfigFromFilesWithFallback(
-    getProjectHooksConfigPaths(workdir),
-    previousValidConfig,
-  );
-  if (projectResult.error) {
-    errors.push(`Project config: ${projectResult.error}`);
-  }
-  if (projectResult.usedFallback) {
-    usedFallback = true;
-  }
-
-  const userConfig = userResult.config;
-  const projectConfig = projectResult.config;
-
-  // If both configs failed and no fallback available
-  if (!userConfig && !projectConfig && errors.length > 0) {
-    return {
-      config: previousValidConfig || null,
-      errors,
-      usedFallback: !!previousValidConfig,
-    };
-  }
-
-  // No configuration found at all
-  if (!userConfig && !projectConfig) {
-    return { config: null, errors, usedFallback };
-  }
-
-  // Only one configuration found
-  if (!userConfig) return { config: projectConfig, errors, usedFallback };
-  if (!projectConfig) return { config: userConfig, errors, usedFallback };
-
-  // Merge configurations (project overrides user)
-  try {
-    const mergedHooks: PartialHookConfiguration = {};
-
-    // Merge environment variables using the new mergeEnvironmentConfig function
-    const environmentContext = mergeEnvironmentConfig(
-      userConfig.env,
-      projectConfig.env,
-      { includeConflictWarnings: true },
-    );
-
-    // Merge hooks (combine arrays, project configs come after user configs)
-    const allEvents = new Set([
-      ...Object.keys(userConfig.hooks || {}),
-      ...Object.keys(projectConfig.hooks || {}),
-    ]);
-
-    for (const event of allEvents) {
-      if (!isValidHookEvent(event)) continue;
-
-      const userEventConfigs = userConfig.hooks?.[event] || [];
-      const projectEventConfigs = projectConfig.hooks?.[event] || [];
-
-      // Project configurations take precedence
-      mergedHooks[event] = [...userEventConfigs, ...projectEventConfigs];
-    }
-
-    const mergedConfig = {
-      hooks: Object.keys(mergedHooks).length > 0 ? mergedHooks : undefined,
-      env:
-        Object.keys(environmentContext.mergedVars).length > 0
-          ? environmentContext.mergedVars
-          : undefined,
-    };
-
-    return { config: mergedConfig, errors, usedFallback };
-  } catch (error) {
-    errors.push(`Merge error: ${(error as Error).message}`);
-    return {
-      config: previousValidConfig || null,
-      errors,
-      usedFallback: !!previousValidConfig,
-    };
-  }
-}
-
-/**
- * Load Wave configuration from a JSON file
- * Supports both hooks and environment variables with proper validation
- */
-export function loadWaveConfigFromFile(
-  filePath: string,
-): WaveConfiguration | null {
-  if (!existsSync(filePath)) {
-    return null;
-  }
-
-  try {
-    const content = readFileSync(filePath, "utf-8");
-    const config = JSON.parse(content) as WaveConfiguration;
-
-    // Validate basic structure
-    if (!config || typeof config !== "object") {
-      throw new Error(`Invalid configuration structure in ${filePath}`);
-    }
-
-    // Validate environment variables if present
-    if (config.env !== undefined) {
-      const envValidation = validateEnvironmentConfig(config.env, filePath);
-
-      if (!envValidation.isValid) {
-        throw new Error(
-          `Environment variable validation failed in ${filePath}: ${envValidation.errors.join(", ")}`,
-        );
-      }
-
-      // Log warnings if any
-      if (envValidation.warnings.length > 0) {
-        console.warn(
-          `Environment variable warnings in ${filePath}:\n- ${envValidation.warnings.join("\n- ")}`,
-        );
-      }
-    }
-
-    return {
-      hooks: config.hooks || undefined,
-      env: config.env || undefined,
-    };
-  } catch (error) {
-    if (error instanceof SyntaxError) {
-      throw new Error(`Invalid JSON syntax in ${filePath}: ${error.message}`);
-    }
-
-    // Re-throw validation errors and other errors as-is
-    throw error;
-  }
-}
-
-/**
- * Load hooks configuration from a JSON file (legacy function)
- */
-export function loadHooksConfigFromFile(
-  filePath: string,
-): PartialHookConfiguration | null {
-  const waveConfig = loadWaveConfigFromFile(filePath);
-  if (!waveConfig) {
-    return null;
-  }
-
-  return waveConfig.hooks || null;
-}
-
-/**
- * Load user-specific Wave configuration
- * Checks .local.json first, then falls back to .json
- */
-export function loadUserWaveConfig(): WaveConfiguration | null {
-  return loadWaveConfigFromFiles(getUserHooksConfigPaths());
-}
-
-/**
- * Load project-specific Wave configuration
- * Checks .local.json first, then falls back to .json
- */
-export function loadProjectWaveConfig(
-  workdir: string,
-): WaveConfiguration | null {
-  return loadWaveConfigFromFiles(getProjectHooksConfigPaths(workdir));
-}
-
-/**
- * Load user-specific hooks configuration (legacy function)
- */
-export function loadUserHooksConfig(): PartialHookConfiguration | null {
-  const waveConfig = loadUserWaveConfig();
-  return waveConfig?.hooks || null;
-}
-
-/**
- * Load project-specific hooks configuration (legacy function)
- */
-export function loadProjectHooksConfig(
-  workdir: string,
-): PartialHookConfiguration | null {
-  const waveConfig = loadProjectWaveConfig(workdir);
-  return waveConfig?.hooks || null;
-}
-
-/**
- * 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 function loadMergedWaveConfig(
-  workdir: string,
-): WaveConfiguration | null {
-  const userConfig = loadUserWaveConfig();
-  const projectConfig = loadProjectWaveConfig(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 mergedHooks: PartialHookConfiguration = {};
-
-  // Merge environment variables using the new mergeEnvironmentConfig function
-  const environmentContext = mergeEnvironmentConfig(
-    userConfig.env,
-    projectConfig.env,
-    { includeConflictWarnings: true },
-  );
-
-  // Log environment variable conflicts if any
-  if (environmentContext.conflicts.length > 0) {
-    console.warn(
-      `Environment variable conflicts detected (project values take precedence):\n${environmentContext.conflicts
-        .map(
-          (conflict) =>
-            `- ${conflict.key}: "${conflict.userValue}" → "${conflict.projectValue}"`,
-        )
-        .join("\n")}`,
-    );
-  }
-
-  // Merge hooks (combine arrays, project configs come after user configs)
-  const allEvents = new Set([
-    ...Object.keys(userConfig.hooks || {}),
-    ...Object.keys(projectConfig.hooks || {}),
-  ]);
-
-  for (const event of allEvents) {
-    if (!isValidHookEvent(event)) continue;
-
-    const userEventConfigs = userConfig.hooks?.[event] || [];
-    const projectEventConfigs = projectConfig.hooks?.[event] || [];
-
-    // Project configurations take precedence
-    mergedHooks[event] = [...userEventConfigs, ...projectEventConfigs];
-  }
-
-  return {
-    hooks: Object.keys(mergedHooks).length > 0 ? mergedHooks : undefined,
-    env:
-      Object.keys(environmentContext.mergedVars).length > 0
-        ? environmentContext.mergedVars
-        : undefined,
-  };
-}
-
-/**
- * Load and merge hooks configuration from both user and project sources (legacy function)
- */
-export function loadMergedHooksConfig(
-  workdir: string,
-): PartialHookConfiguration | null {
-  const waveConfig = loadMergedWaveConfig(workdir);
-  return waveConfig?.hooks || 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 function hasHooksConfiguration(workdir: string): boolean {
-  return hasAnyConfig(workdir);
-}
-
-/**
- * Get hooks configuration information for debugging
- * Includes both .local.json and .json variants
- * @deprecated Use getConfigurationInfo() from configPaths.ts for better functionality
- */
-export function getHooksConfigurationInfo(workdir: string): {
-  hasUser: boolean;
-  hasProject: boolean;
-  paths: string[];
-  userPaths: string[];
-  projectPaths: string[];
-  existingPaths: string[];
-} {
-  return getConfigurationInfo(workdir);
-}