@compass-ai/nova 1.0.74 → 1.0.76

package/dist/services/hook-service.js

@@ -1,705 +0,0 @@
-/**
- * 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