wave-agent-sdk 0.0.1

package/src/hooks/matcher.ts

@@ -0,0 +1,187 @@
+/**
+ * Hook Pattern Matcher
+ *
+ * Provides pattern matching functionality for hook tool name matching.
+ * Supports exact matching, wildcard patterns, and pipe-separated alternatives.
+ */
+
+import { minimatch } from "minimatch";
+
+export interface IHookMatcher {
+  // Test if pattern matches tool name
+  matches(pattern: string, toolName: string): boolean;
+
+  // Validate pattern syntax
+  isValidPattern(pattern: string): boolean;
+
+  // Get pattern type for optimization
+  getPatternType(pattern: string): "exact" | "glob" | "regex" | "alternatives";
+}
+
+export class HookMatcher implements IHookMatcher {
+  /**
+   * Test if pattern matches tool name
+   * Supports multiple matching strategies:
+   * - Exact matching: "Edit" matches "Edit"
+   * - Pipe alternatives: "Edit|Write" matches "Edit" or "Write"
+   * - Glob patterns: "Edit*" matches "EditFile", "EditText", etc.
+   * - Case insensitive matching
+   */
+  matches(pattern: string, toolName: string): boolean {
+    if (!pattern || !toolName) return false;
+
+    // Handle pipe-separated alternatives (e.g., "Edit|Write|Delete")
+    if (pattern.includes("|")) {
+      const alternatives = pattern.split("|").map((alt) => alt.trim());
+      return alternatives.some((alt) => this.matchesSingle(alt, toolName));
+    }
+
+    return this.matchesSingle(pattern, toolName);
+  }
+
+  /**
+   * Match a single pattern against tool name
+   */
+  private matchesSingle(pattern: string, toolName: string): boolean {
+    // Exact match (case insensitive)
+    if (pattern.toLowerCase() === toolName.toLowerCase()) {
+      return true;
+    }
+
+    // Glob pattern matching using minimatch
+    try {
+      return minimatch(toolName, pattern, {
+        nocase: true, // Case insensitive
+        noglobstar: false, // Allow ** patterns
+        nonegate: true, // Disable negation for security
+      });
+    } catch {
+      // Invalid pattern, fall back to exact match
+      return false;
+    }
+  }
+
+  /**
+   * Validate pattern syntax
+   */
+  isValidPattern(pattern: string): boolean {
+    if (!pattern || typeof pattern !== "string") return false;
+
+    // Empty pattern is invalid
+    if (pattern.trim().length === 0) return false;
+
+    // Handle pipe-separated alternatives
+    if (pattern.includes("|")) {
+      const alternatives = pattern.split("|").map((alt) => alt.trim());
+      return (
+        alternatives.length > 0 &&
+        alternatives.every(
+          (alt) => alt.length > 0 && this.isValidSinglePattern(alt),
+        )
+      );
+    }
+
+    return this.isValidSinglePattern(pattern);
+  }
+
+  /**
+   * Validate single pattern syntax
+   */
+  private isValidSinglePattern(pattern: string): boolean {
+    // Basic validation - non-empty string
+    if (!pattern || pattern.trim().length === 0) return false;
+
+    // Check for dangerous characters that could be used for command injection
+    // Note: [ ] are allowed for glob patterns
+    const dangerousChars = /[;&|`$(){}><]/;
+    if (dangerousChars.test(pattern)) return false;
+
+    // Validate glob pattern syntax using minimatch
+    try {
+      // Test with a dummy string to validate pattern
+      minimatch("test", pattern, { nocase: true });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get pattern type for optimization
+   */
+  getPatternType(pattern: string): "exact" | "glob" | "regex" | "alternatives" {
+    if (!pattern) return "exact";
+
+    // Check for pipe alternatives first
+    if (pattern.includes("|")) {
+      return "alternatives";
+    }
+
+    // Check for regex patterns first (before glob check)
+    if (
+      pattern.startsWith("/") &&
+      pattern.endsWith("/") &&
+      pattern.length > 2
+    ) {
+      return "regex";
+    }
+
+    // Check for glob patterns
+    if (
+      pattern.includes("*") ||
+      pattern.includes("?") ||
+      pattern.includes("[")
+    ) {
+      return "glob";
+    }
+
+    return "exact";
+  }
+
+  /**
+   * Get all tool names that would match this pattern from a given list
+   * Useful for testing and validation
+   */
+  getMatches(pattern: string, toolNames: string[]): string[] {
+    return toolNames.filter((toolName) => this.matches(pattern, toolName));
+  }
+
+  /**
+   * Optimize pattern for repeated matching
+   * Returns a compiled matcher function for performance
+   */
+  compile(pattern: string): (toolName: string) => boolean {
+    if (!this.isValidPattern(pattern)) {
+      return () => false;
+    }
+
+    const patternType = this.getPatternType(pattern);
+
+    switch (patternType) {
+      case "exact": {
+        const lowerPattern = pattern.toLowerCase();
+        return (toolName: string) => toolName.toLowerCase() === lowerPattern;
+      }
+
+      case "alternatives": {
+        const alternatives = pattern
+          .split("|")
+          .map((alt) => alt.trim().toLowerCase());
+        return (toolName: string) => {
+          const lowerTool = toolName.toLowerCase();
+          return alternatives.some(
+            (alt) =>
+              lowerTool === alt || minimatch(toolName, alt, { nocase: true }),
+          );
+        };
+      }
+
+      case "glob":
+        return (toolName: string) =>
+          minimatch(toolName, pattern, { nocase: true });
+
+      default:
+        return (toolName: string) => this.matches(pattern, toolName);
+    }
+  }
+}

package/src/hooks/settings.ts

@@ -0,0 +1,129 @@
+/**
+ * Hook Settings Management
+ *
+ * Handles loading and merging of hook configurations from:
+ * - User settings: ~/.wave/hooks.json
+ * - Project settings: ./.wave/hooks.json
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import type { HookConfiguration, PartialHookConfiguration } from "./types.js";
+import { isValidHookEvent } from "./types.js";
+
+/**
+ * Get the user-specific hooks configuration file path
+ */
+export function getUserHooksConfigPath(): string {
+  return join(homedir(), ".wave", "hooks.json");
+}
+
+/**
+ * Get the project-specific hooks configuration file path
+ */
+export function getProjectHooksConfigPath(workdir: string): string {
+  return join(workdir, ".wave", "hooks.json");
+}
+
+/**
+ * Load hooks configuration from a JSON file
+ */
+export function loadHooksConfigFromFile(
+  filePath: string,
+): PartialHookConfiguration | null {
+  try {
+    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) {
+      console.warn(`Invalid hooks configuration structure in ${filePath}`);
+      return null;
+    }
+
+    return config.hooks;
+  } catch (error) {
+    console.warn(`Failed to load hooks configuration from ${filePath}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Load user hooks configuration
+ */
+export function loadUserHooksConfig(): PartialHookConfiguration | null {
+  return loadHooksConfigFromFile(getUserHooksConfigPath());
+}
+
+/**
+ * Load project hooks configuration
+ */
+export function loadProjectHooksConfig(
+  workdir: string,
+): PartialHookConfiguration | null {
+  return loadHooksConfigFromFile(getProjectHooksConfigPath(workdir));
+}
+
+/**
+ * Load and merge hooks configuration with project settings taking precedence
+ */
+export function loadMergedHooksConfig(
+  workdir: string,
+): PartialHookConfiguration {
+  const userConfig = loadUserHooksConfig();
+  const projectConfig = loadProjectHooksConfig(workdir);
+
+  const merged: PartialHookConfiguration = {};
+
+  // Start with user configuration
+  if (userConfig) {
+    Object.entries(userConfig).forEach(([event, configs]) => {
+      if (isValidHookEvent(event)) {
+        merged[event] = [...configs];
+      }
+    });
+  }
+
+  // Override with project configuration (project takes precedence)
+  if (projectConfig) {
+    Object.entries(projectConfig).forEach(([event, configs]) => {
+      if (isValidHookEvent(event)) {
+        merged[event] = [...configs];
+      }
+    });
+  }
+
+  return merged;
+}
+
+/**
+ * Check if any hooks configuration files exist
+ */
+export function hasHooksConfiguration(workdir: string): boolean {
+  return (
+    existsSync(getUserHooksConfigPath()) ||
+    existsSync(getProjectHooksConfigPath(workdir))
+  );
+}
+
+/**
+ * Get information about available hooks configuration files
+ */
+export function getHooksConfigurationInfo(workdir: string): {
+  userConfigExists: boolean;
+  projectConfigExists: boolean;
+  userConfigPath: string;
+  projectConfigPath: string;
+} {
+  return {
+    userConfigExists: existsSync(getUserHooksConfigPath()),
+    projectConfigExists: existsSync(getProjectHooksConfigPath(workdir)),
+    userConfigPath: getUserHooksConfigPath(),
+    projectConfigPath: getProjectHooksConfigPath(workdir),
+  };
+}

package/src/hooks/types.ts

@@ -0,0 +1,169 @@
+/**
+ * Hooks System Type Definitions
+ *
+ * Provides comprehensive TypeScript types for the Wave Code hooks system,
+ * enabling automated actions at specific workflow points.
+ */
+
+import { join } from "path";
+import { homedir } from "os";
+
+// Session path utility (from session.ts)
+export function getSessionFilePath(sessionId: string): string {
+  const shortId = sessionId.split("_")[2] || sessionId.slice(-8);
+  return join(homedir(), ".wave", "sessions", `session_${shortId}.json`);
+}
+
+// Hook event types - trigger points in the AI workflow
+export type HookEvent =
+  | "PreToolUse"
+  | "PostToolUse"
+  | "UserPromptSubmit"
+  | "Stop";
+
+// Individual hook command configuration
+export interface HookCommand {
+  type: "command";
+  command: string;
+}
+
+// Hook event configuration with optional pattern matching
+export interface HookEventConfig {
+  matcher?: string; // Required for PreToolUse/PostToolUse, omitted for others
+  hooks: HookCommand[];
+}
+
+// Root configuration structure for all hook definitions
+export interface HookConfiguration {
+  hooks: Partial<Record<HookEvent, HookEventConfig[]>>;
+}
+
+// Partial hook configuration for loading/merging scenarios
+export type PartialHookConfiguration = Partial<
+  Record<HookEvent, HookEventConfig[]>
+>;
+
+// Direct hook configuration record (for test convenience)
+export type HookConfigurationRecord = Record<HookEvent, HookEventConfig[]>;
+
+// Context passed to hook during execution
+export interface HookExecutionContext {
+  event: HookEvent;
+  toolName?: string; // Present for PreToolUse/PostToolUse events
+  projectDir: string; // Absolute path for $WAVE_PROJECT_DIR
+  timestamp: Date;
+}
+
+// Result of hook execution
+export interface HookExecutionResult {
+  success: boolean;
+  exitCode?: number;
+  stdout?: string;
+  stderr?: string;
+  duration: number; // milliseconds
+  timedOut: boolean;
+}
+
+// Hook execution options
+export interface HookExecutionOptions {
+  timeout?: number; // milliseconds, default 10000
+  cwd?: string; // working directory, defaults to projectDir
+}
+
+// Validation result for hook configuration
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+// Hook execution errors (non-blocking)
+export class HookExecutionError extends Error {
+  constructor(
+    public readonly hookCommand: string,
+    public readonly originalError: Error,
+    public readonly context: HookExecutionContext,
+  ) {
+    super(`Hook execution failed: ${hookCommand} - ${originalError.message}`);
+    this.name = "HookExecutionError";
+  }
+}
+
+// Configuration validation errors (blocking)
+export class HookConfigurationError extends Error {
+  constructor(
+    public readonly configPath: string,
+    public readonly validationErrors: string[],
+  ) {
+    super(
+      `Hook configuration error in ${configPath}: ${validationErrors.join(", ")}`,
+    );
+    this.name = "HookConfigurationError";
+  }
+}
+
+// Type guards for runtime validation
+export function isValidHookEvent(event: string): event is HookEvent {
+  return ["PreToolUse", "PostToolUse", "UserPromptSubmit", "Stop"].includes(
+    event,
+  );
+}
+
+export function isValidHookCommand(cmd: unknown): cmd is HookCommand {
+  return (
+    typeof cmd === "object" &&
+    cmd !== null &&
+    "type" in cmd &&
+    cmd.type === "command" &&
+    "command" in cmd &&
+    typeof cmd.command === "string" &&
+    cmd.command.length > 0
+  );
+}
+
+export function isValidHookEventConfig(
+  config: unknown,
+): config is HookEventConfig {
+  if (typeof config !== "object" || config === null) return false;
+
+  const cfg = config as Record<string, unknown>;
+
+  // Validate hooks array
+  if (!Array.isArray(cfg.hooks) || cfg.hooks.length === 0) return false;
+  if (!cfg.hooks.every(isValidHookCommand)) return false;
+
+  // Validate optional matcher
+  if ("matcher" in cfg && typeof cfg.matcher !== "string") return false;
+
+  return true;
+}
+
+// JSON structure passed to hooks via stdin
+export interface HookJsonInput {
+  // Required fields for all events
+  session_id: string; // Format: "wave_session_{uuid}_{shortId}"
+  transcript_path: string; // Format: "~/.wave/sessions/session_{shortId}.json"
+  cwd: string; // Absolute path to current working directory
+  hook_event_name: HookEvent; // "PreToolUse" | "PostToolUse" | "UserPromptSubmit" | "Stop"
+
+  // Optional fields based on event type
+  tool_name?: string; // Present for PreToolUse, PostToolUse
+  tool_input?: unknown; // Present for PreToolUse, PostToolUse
+  tool_response?: unknown; // Present for PostToolUse only
+  user_prompt?: string; // Present for UserPromptSubmit only
+}
+
+// Extended context interface for passing additional data to hook executor
+export interface ExtendedHookExecutionContext extends HookExecutionContext {
+  sessionId?: string; // Session identifier for JSON construction
+  transcriptPath?: string; // Path to session transcript file
+  cwd?: string; // Current working directory
+  toolInput?: unknown; // Tool input parameters (PreToolUse/PostToolUse)
+  toolResponse?: unknown; // Tool execution result (PostToolUse only)
+  userPrompt?: string; // User prompt text (UserPromptSubmit only)
+}
+
+// Environment variables injected into hook processes
+export interface HookEnvironment {
+  WAVE_PROJECT_DIR: string; // Absolute path to project root
+  [key: string]: string; // Inherit all parent process environment variables
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+// Export all services
+export * from "./services/aiService.js";
+export * from "./services/memory.js";
+export * from "./services/session.js";
+
+// Export main agent
+export * from "./agent.js";
+
+// Export all utilities
+export * from "./utils/bashHistory.js";
+export * from "./utils/convertMessagesForAPI.js";
+export * from "./utils/fileFilter.js";
+export * from "./utils/mcpUtils.js";
+export * from "./utils/messageOperations.js";
+export * from "./utils/path.js";
+export * from "./utils/stringUtils.js";
+export * from "./utils/markdownParser.js";
+export * from "./utils/customCommands.js";
+
+// Export hooks system
+export * from "./hooks/index.js";
+
+// Export types
+export * from "./types.js";