@compass-ai/nova 1.0.73 → 1.0.74

package/dist/services/hook-service.js

@@ -0,0 +1,705 @@
+/**
+ * Hook service for discovering, parsing, and executing hooks.
+ * Hooks are shell commands that execute in response to events like tool calls.
+ *
+ * Claude Code style hooks support:
+ * - PreToolUse: Execute before a tool runs, can block execution
+ * - PostToolUse: Execute after a tool runs
+ * - UserPromptSubmit: Execute when user submits a prompt
+ * - Notification: Execute for notifications
+ * - Stop: Execute when the session ends
+ *
+ * Hooks are defined in:
+ * - .compass/hooks/ (project-specific)
+ * - ~/.compass/hooks/ (personal/global)
+ *
+ * Hook files can be:
+ * - <event>.yaml or <event>.md (single hook per event)
+ * - <event>/<name>.yaml or <event>/<name>.md (multiple hooks per event)
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { glob } from 'glob';
+import { execa } from 'execa';
+import { getGlobalCompassDir, getProjectCompassDir } from '../utils/path.js';
+import { HOOKS_DIR } from '../constants/defaults.js';
+import { logger } from '../utils/logger.js';
+import { isValidHookEvent, HOOK_SOURCE_PRIORITY, } from '../types/hook.js';
+// =============================================================================
+// Module State
+// =============================================================================
+/** Cache for discovered hooks */
+let cachedHooks = null;
+let cacheTimestamp = 0;
+const CACHE_TTL_MS = 5000; // 5 seconds
+/** Current project root for hook discovery */
+let currentProjectRoot = process.cwd();
+/** Whether hooks are enabled globally */
+let hooksEnabled = true;
+/** Default timeout for hook execution */
+const DEFAULT_HOOK_TIMEOUT_MS = 30000;
+// =============================================================================
+// Path Utilities
+// =============================================================================
+/**
+ * Gets the project hooks directory path.
+ */
+export function getProjectHooksDir() {
+    return path.join(getProjectCompassDir(currentProjectRoot), HOOKS_DIR);
+}
+/**
+ * Gets the personal (user) hooks directory path.
+ */
+export function getPersonalHooksDir() {
+    return path.join(getGlobalCompassDir(), HOOKS_DIR);
+}
+/**
+ * Sets the project root for hook discovery.
+ * Call this when --cwd is used to ensure hooks are discovered from the correct location.
+ */
+export function setHooksProjectRoot(projectRoot) {
+    if (currentProjectRoot !== projectRoot) {
+        currentProjectRoot = projectRoot;
+        invalidateHookCache();
+    }
+}
+/**
+ * Gets the current project root.
+ */
+export function getHooksProjectRoot() {
+    return currentProjectRoot;
+}
+/**
+ * Enables or disables hooks globally.
+ */
+export function setHooksEnabled(enabled) {
+    hooksEnabled = enabled;
+    logger.debug(`Hooks ${enabled ? 'enabled' : 'disabled'}`);
+}
+/**
+ * Checks if hooks are enabled.
+ */
+export function areHooksEnabled() {
+    return hooksEnabled;
+}
+// =============================================================================
+// Frontmatter Parsing
+// =============================================================================
+/**
+ * Parses YAML frontmatter from hook file content.
+ * Uses a simple regex-based approach for portability.
+ *
+ * @param content - The file content
+ * @returns Object containing parsed frontmatter and script body
+ */
+export function parseHookFrontmatter(content) {
+    const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+    const match = content.match(frontmatterRegex);
+    if (!match) {
+        return { frontmatter: {}, script: content };
+    }
+    const [, yamlContent, script] = match;
+    const frontmatter = {};
+    // Parse YAML key-value pairs and arrays
+    const lines = yamlContent.split(/\r?\n/);
+    let currentKey = null;
+    let currentArray = null;
+    for (const line of lines) {
+        // Skip empty lines and comments
+        if (!line.trim() || line.trim().startsWith('#')) {
+            continue;
+        }
+        // Check for array item
+        if (line.match(/^\s+-\s+/)) {
+            if (currentKey && currentArray !== null) {
+                const value = line.replace(/^\s+-\s+/, '').trim();
+                // Remove quotes if present
+                const unquoted = value.replace(/^["']|["']$/g, '');
+                currentArray.push(unquoted);
+            }
+            continue;
+        }
+        // Check for key-value pair
+        const kvMatch = line.match(/^([a-zA-Z-]+):\s*(.*)$/);
+        if (kvMatch) {
+            // Save previous array if any
+            if (currentKey && currentArray !== null) {
+                frontmatter[currentKey] = currentArray;
+            }
+            const [, key, value] = kvMatch;
+            currentKey = key;
+            if (value.trim() === '') {
+                // Start of array
+                currentArray = [];
+            }
+            else {
+                // Simple value
+                currentArray = null;
+                let parsedValue = value.trim();
+                // Remove quotes if present
+                parsedValue = parsedValue.replace(/^["']|["']$/g, '');
+                // Parse booleans
+                if (parsedValue === 'true')
+                    parsedValue = true;
+                if (parsedValue === 'false')
+                    parsedValue = false;
+                // Parse numbers for timeout
+                if (key === 'timeout' && !isNaN(Number(parsedValue))) {
+                    parsedValue = Number(parsedValue);
+                }
+                frontmatter[key] = parsedValue;
+            }
+        }
+    }
+    // Save last array if any
+    if (currentKey && currentArray !== null) {
+        frontmatter[currentKey] = currentArray;
+    }
+    return { frontmatter, script: script.trim() };
+}
+// =============================================================================
+// Hook Parsing
+// =============================================================================
+/**
+ * Extracts description from frontmatter or first comment line.
+ */
+function extractDescription(frontmatter, script) {
+    if (frontmatter.description) {
+        return frontmatter.description;
+    }
+    // Try to extract from first comment line
+    const lines = script.split(/\r?\n/);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('#!')) {
+            continue; // Skip shebang
+        }
+        if (trimmed.startsWith('#')) {
+            return trimmed.slice(1).trim();
+        }
+        if (trimmed) {
+            break; // Stop at first non-comment line
+        }
+    }
+    return 'Custom hook';
+}
+/**
+ * Determines the event type from file path.
+ */
+function getEventFromPath(filePath, baseDir) {
+    const relativePath = path.relative(baseDir, filePath);
+    const parts = relativePath.split(path.sep);
+    // Check if first directory or filename (without extension) is a valid event
+    const firstPart = parts[0].replace(/\.(yaml|yml|md)$/i, '');
+    if (isValidHookEvent(firstPart)) {
+        return firstPart;
+    }
+    // Check second level for event/<name>.yaml pattern
+    if (parts.length >= 2 && isValidHookEvent(parts[0])) {
+        return parts[0];
+    }
+    return null;
+}
+/**
+ * Parses a hook file and creates a HookDefinition.
+ *
+ * @param filePath - Absolute path to the hook file
+ * @param source - Where this hook was found
+ * @param baseDir - The base hooks directory
+ * @returns Parsed hook definition or null if invalid
+ */
+export async function parseHookFile(filePath, source, baseDir) {
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const { frontmatter, script } = parseHookFrontmatter(content);
+        // Determine event from file path
+        const event = getEventFromPath(filePath, baseDir);
+        if (!event) {
+            logger.warn(`Could not determine event type for hook: ${filePath}`);
+            return null;
+        }
+        // Get hook name from filename (without extension)
+        const filename = path.basename(filePath);
+        const name = filename.replace(/\.(yaml|yml|md)$/i, '');
+        // If name equals event, it's the only hook for that event
+        const hookName = name === event ? 'default' : name;
+        const description = extractDescription(frontmatter, script);
+        return {
+            id: `${source}-${event}-${hookName}`,
+            name: hookName,
+            event,
+            filePath,
+            source,
+            frontmatter,
+            script,
+            description,
+            isActive: true, // Will be updated during priority resolution
+        };
+    }
+    catch (error) {
+        logger.warn(`Failed to parse hook file: ${filePath}`, error);
+        return null;
+    }
+}
+// =============================================================================
+// Hook Discovery
+// =============================================================================
+/**
+ * Discovers hooks from a specific directory.
+ *
+ * @param directory - Directory to search
+ * @param source - Source type for discovered hooks
+ * @returns Array of discovered hooks
+ */
+async function discoverHooksInDirectory(directory, source) {
+    const hooks = [];
+    if (!(await fs.pathExists(directory))) {
+        return hooks;
+    }
+    try {
+        // Find all hook files (yaml, yml, md)
+        const hookFiles = await glob('**/*.{yaml,yml,md}', {
+            cwd: directory,
+            nodir: true,
+            absolute: true,
+        });
+        for (const filePath of hookFiles) {
+            const hook = await parseHookFile(filePath, source, directory);
+            if (hook) {
+                hooks.push(hook);
+                logger.debug(`Discovered ${source} hook: ${hook.event}/${hook.name}`, {
+                    path: filePath,
+                });
+            }
+        }
+    }
+    catch (error) {
+        logger.warn(`Failed to discover hooks in ${directory}`, error);
+    }
+    return hooks;
+}
+/**
+ * Resolves hook priorities and marks inactive hooks.
+ *
+ * @param hooks - All discovered hooks
+ * @returns Discovery result with priority resolution
+ */
+function resolveHookPriorities(hooks) {
+    const bySource = {
+        personal: [],
+        project: [],
+    };
+    const byEvent = {
+        PreToolUse: [],
+        PostToolUse: [],
+        UserPromptSubmit: [],
+        Notification: [],
+        Stop: [],
+    };
+    // Group by source
+    for (const hook of hooks) {
+        bySource[hook.source].push(hook);
+    }
+    // Build active hooks map (higher priority wins for same event+name)
+    const activeByKey = new Map();
+    // Process in priority order (lowest first, so higher overwrites)
+    for (const source of HOOK_SOURCE_PRIORITY) {
+        for (const hook of bySource[source]) {
+            const key = `${hook.event}-${hook.name}`;
+            activeByKey.set(key, hook);
+        }
+    }
+    // Mark active status and group by event
+    const active = [];
+    for (const hook of hooks) {
+        const key = `${hook.event}-${hook.name}`;
+        const isActive = activeByKey.get(key)?.id === hook.id;
+        hook.isActive = isActive;
+        if (isActive) {
+            active.push(hook);
+            byEvent[hook.event].push(hook);
+        }
+    }
+    return {
+        all: hooks,
+        active,
+        byEvent,
+        bySource,
+    };
+}
+/**
+ * Discovers all hooks from personal and project directories.
+ * Project hooks take precedence over personal hooks with the same name.
+ *
+ * @param forceRefresh - Force refresh the cache
+ * @returns Discovery result with all hooks
+ */
+export async function discoverHooks(forceRefresh = false) {
+    // Check cache
+    if (!forceRefresh && cachedHooks && Date.now() - cacheTimestamp < CACHE_TTL_MS) {
+        return cachedHooks;
+    }
+    const allHooks = [];
+    // 1. Personal hooks (lower priority)
+    const personalHooks = await discoverHooksInDirectory(getPersonalHooksDir(), 'personal');
+    allHooks.push(...personalHooks);
+    // 2. Project hooks (higher priority)
+    const projectHooks = await discoverHooksInDirectory(getProjectHooksDir(), 'project');
+    allHooks.push(...projectHooks);
+    // Resolve priorities
+    const result = resolveHookPriorities(allHooks);
+    // Update cache
+    cachedHooks = result;
+    cacheTimestamp = Date.now();
+    logger.info(`Discovered ${result.active.length} active hooks (${result.all.length} total)`);
+    return result;
+}
+/**
+ * Invalidates the hook cache.
+ */
+export function invalidateHookCache() {
+    cachedHooks = null;
+    cacheTimestamp = 0;
+}
+// =============================================================================
+// Pattern Matching
+// =============================================================================
+/**
+ * Simple glob pattern matching.
+ */
+function matchGlob(pattern, value) {
+    // Convert glob to regex
+    const regexPattern = pattern
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&') // Escape special regex chars
+        .replace(/\*/g, '.*') // * matches anything
+        .replace(/\?/g, '.'); // ? matches single char
+    const regex = new RegExp(`^${regexPattern}$`, 'i');
+    return regex.test(value);
+}
+/**
+ * Checks if a hook matches the given tool context.
+ */
+function hookMatchesTool(hook, toolName, toolInput) {
+    const { frontmatter } = hook;
+    // If no tools specified, matches all tools
+    if (!frontmatter.tools || frontmatter.tools.length === 0) {
+        return true;
+    }
+    // Check if tool name matches any pattern
+    const toolMatches = frontmatter.tools.some((pattern) => matchGlob(pattern, toolName));
+    if (!toolMatches) {
+        return false;
+    }
+    // If no match patterns specified, tool name match is sufficient
+    if (!frontmatter.match || Object.keys(frontmatter.match).length === 0) {
+        return true;
+    }
+    // Check input pattern matching
+    for (const [field, pattern] of Object.entries(frontmatter.match)) {
+        const inputValue = toolInput[field];
+        if (inputValue === undefined) {
+            return false;
+        }
+        if (!matchGlob(pattern, String(inputValue))) {
+            return false;
+        }
+    }
+    return true;
+}
+// =============================================================================
+// Hook Execution
+// =============================================================================
+/**
+ * Builds environment variables for hook execution.
+ */
+function buildHookEnvironment(hook, context) {
+    const env = {
+        HOOK_EVENT: context.event,
+        HOOK_NAME: hook.name,
+        HOOK_CWD: context.projectRoot,
+        HOOK_SESSION_ID: context.sessionId,
+    };
+    // Add tool-specific variables
+    if (context.tool) {
+        env.TOOL_NAME = context.tool.name;
+        env.TOOL_CALL_ID = context.tool.callId;
+        env.TOOL_INPUT = JSON.stringify(context.tool.input);
+        // Add individual input fields as TOOL_INPUT_<FIELD_NAME>
+        for (const [key, value] of Object.entries(context.tool.input)) {
+            const envKey = `TOOL_INPUT_${key.toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
+            env[envKey] = String(value);
+        }
+        // PostToolUse specific
+        if (context.event === 'PostToolUse') {
+            env.TOOL_OUTPUT = JSON.stringify(context.tool.output);
+            env.TOOL_SUCCESS = String(context.tool.success ?? true);
+            if (context.tool.error) {
+                env.TOOL_ERROR = context.tool.error;
+            }
+        }
+    }
+    // UserPromptSubmit specific
+    if (context.userPrompt !== undefined) {
+        env.USER_PROMPT = context.userPrompt;
+    }
+    return env;
+}
+/**
+ * Executes a single hook.
+ */
+async function executeHook(hook, context) {
+    const startTime = Date.now();
+    // Check if hook is enabled
+    if (hook.frontmatter.enabled === false) {
+        return {
+            hookId: hook.id,
+            success: true,
+            exitCode: 0,
+            stdout: '',
+            stderr: '',
+            duration: 0,
+            skipped: true,
+            skipReason: 'Hook is disabled',
+        };
+    }
+    // For tool events, check if hook matches the tool
+    if ((context.event === 'PreToolUse' || context.event === 'PostToolUse') && context.tool) {
+        if (!hookMatchesTool(hook, context.tool.name, context.tool.input)) {
+            return {
+                hookId: hook.id,
+                success: true,
+                exitCode: 0,
+                stdout: '',
+                stderr: '',
+                duration: 0,
+                skipped: true,
+                skipReason: 'Hook does not match tool',
+            };
+        }
+    }
+    // Build environment
+    const env = buildHookEnvironment(hook, context);
+    // Determine shell based on platform
+    const isWindows = process.platform === 'win32';
+    const shell = isWindows ? 'cmd.exe' : '/bin/bash';
+    const shellArgs = isWindows ? ['/c'] : ['-c'];
+    try {
+        logger.debug(`Executing hook: ${hook.id}`, { event: context.event });
+        const timeout = hook.frontmatter.timeout ?? DEFAULT_HOOK_TIMEOUT_MS;
+        const result = await execa(shell, [...shellArgs, hook.script], {
+            cwd: context.projectRoot,
+            env: { ...process.env, ...env },
+            timeout,
+            reject: false,
+            shell: false,
+        });
+        const duration = Date.now() - startTime;
+        return {
+            hookId: hook.id,
+            success: result.exitCode === 0,
+            exitCode: result.exitCode ?? 1,
+            stdout: result.stdout || '',
+            stderr: result.stderr || '',
+            duration,
+            skipped: false,
+        };
+    }
+    catch (error) {
+        const duration = Date.now() - startTime;
+        const errorMsg = error instanceof Error ? error.message : 'Hook execution failed';
+        logger.error(`Hook execution failed: ${hook.id}`, error);
+        return {
+            hookId: hook.id,
+            success: false,
+            exitCode: 1,
+            stdout: '',
+            stderr: '',
+            duration,
+            skipped: false,
+            error: errorMsg,
+        };
+    }
+}
+// =============================================================================
+// Event Execution
+// =============================================================================
+/**
+ * Executes all hooks for a given event.
+ *
+ * @param event - The event type
+ * @param context - Execution context
+ * @returns Combined result from all hooks
+ */
+export async function executeHooks(event, context) {
+    const startTime = Date.now();
+    // Check if hooks are enabled
+    if (!hooksEnabled) {
+        return {
+            event,
+            allowed: true,
+            results: [],
+            totalDuration: 0,
+        };
+    }
+    const fullContext = { ...context, event };
+    const discovery = await discoverHooks();
+    const hooks = discovery.byEvent[event];
+    if (hooks.length === 0) {
+        return {
+            event,
+            allowed: true,
+            results: [],
+            totalDuration: 0,
+        };
+    }
+    const results = [];
+    let blocked = false;
+    let blockMessage;
+    for (const hook of hooks) {
+        const result = await executeHook(hook, fullContext);
+        results.push(result);
+        // For PreToolUse, check if hook blocked execution
+        if (event === 'PreToolUse' && !result.success && !result.skipped) {
+            blocked = true;
+            // Use stderr or stdout as block message
+            blockMessage = result.stderr.trim() || result.stdout.trim() || `Blocked by hook: ${hook.name}`;
+            logger.info(`Tool blocked by hook ${hook.id}: ${blockMessage}`);
+            break; // Stop processing more hooks
+        }
+    }
+    const totalDuration = Date.now() - startTime;
+    return {
+        event,
+        allowed: !blocked,
+        blockMessage,
+        results,
+        totalDuration,
+    };
+}
+// =============================================================================
+// Convenience Functions
+// =============================================================================
+/**
+ * Executes PreToolUse hooks for a tool call.
+ * Returns whether the tool should proceed (allowed) and any block message.
+ */
+export async function executePreToolUseHooks(toolName, toolCallId, toolInput, projectRoot, sessionId) {
+    const result = await executeHooks('PreToolUse', {
+        projectRoot,
+        sessionId,
+        tool: {
+            name: toolName,
+            callId: toolCallId,
+            input: toolInput,
+        },
+    });
+    return {
+        allowed: result.allowed,
+        blockMessage: result.blockMessage,
+    };
+}
+/**
+ * Executes PostToolUse hooks for a tool call.
+ */
+export async function executePostToolUseHooks(toolName, toolCallId, toolInput, toolOutput, success, error, projectRoot, sessionId) {
+    await executeHooks('PostToolUse', {
+        projectRoot,
+        sessionId,
+        tool: {
+            name: toolName,
+            callId: toolCallId,
+            input: toolInput,
+            output: toolOutput,
+            success,
+            error,
+        },
+    });
+}
+/**
+ * Executes UserPromptSubmit hooks.
+ * Returns whether the prompt should proceed (allowed) and any block message.
+ */
+export async function executeUserPromptSubmitHooks(userPrompt, projectRoot, sessionId) {
+    const result = await executeHooks('UserPromptSubmit', {
+        projectRoot,
+        sessionId,
+        userPrompt,
+    });
+    return {
+        allowed: result.allowed,
+        blockMessage: result.blockMessage,
+    };
+}
+/**
+ * Executes Notification hooks.
+ */
+export async function executeNotificationHooks(notification, projectRoot, sessionId) {
+    await executeHooks('Notification', {
+        projectRoot,
+        sessionId,
+        notification,
+    });
+}
+/**
+ * Executes Stop hooks.
+ */
+export async function executeStopHooks(projectRoot, sessionId) {
+    await executeHooks('Stop', {
+        projectRoot,
+        sessionId,
+    });
+}
+// =============================================================================
+// Hook Lookup
+// =============================================================================
+/**
+ * Gets all active hooks.
+ */
+export async function getActiveHooks() {
+    const result = await discoverHooks();
+    return result.active;
+}
+/**
+ * Gets all hooks for a specific event.
+ */
+export async function getHooksForEvent(event) {
+    const result = await discoverHooks();
+    return result.byEvent[event];
+}
+/**
+ * Checks if any hooks are defined for an event.
+ */
+export async function hasHooksForEvent(event) {
+    const hooks = await getHooksForEvent(event);
+    return hooks.length > 0;
+}
+// =============================================================================
+// Export Default
+// =============================================================================
+export default {
+    // Path utilities
+    getProjectHooksDir,
+    getPersonalHooksDir,
+    setHooksProjectRoot,
+    getHooksProjectRoot,
+    setHooksEnabled,
+    areHooksEnabled,
+    // Discovery
+    discoverHooks,
+    invalidateHookCache,
+    // Parsing
+    parseHookFrontmatter,
+    parseHookFile,
+    // Execution
+    executeHooks,
+    executePreToolUseHooks,
+    executePostToolUseHooks,
+    executeUserPromptSubmitHooks,
+    executeNotificationHooks,
+    executeStopHooks,
+    // Lookup
+    getActiveHooks,
+    getHooksForEvent,
+    hasHooksForEvent,
+};
+//# sourceMappingURL=hook-service.js.map