@phuetz/code-buddy 0.1.18 → 0.1.19

package/dist/hooks/advanced-hooks.js

@@ -0,0 +1,256 @@
+/**
+ * Advanced Hook System
+ *
+ * Extends the basic hook system with Claude Code-like capabilities:
+ * - Command hooks: run shell commands, parse JSON stdout for decisions
+ * - Prompt hooks: LLM-evaluated hooks (stub - returns allow with stored prompt)
+ * - Agent hooks: spawns subagent evaluation (stub - returns allow)
+ *
+ * Supports event matching with regex matchers, async fire-and-forget,
+ * one-shot hooks, and a registry for CRUD operations.
+ */
+import { spawn } from 'child_process';
+import { logger } from '../utils/logger.js';
+export var HookEvent;
+(function (HookEvent) {
+    HookEvent["PreToolUse"] = "PreToolUse";
+    HookEvent["PostToolUse"] = "PostToolUse";
+    HookEvent["PreBash"] = "PreBash";
+    HookEvent["PostBash"] = "PostBash";
+    HookEvent["PreEdit"] = "PreEdit";
+    HookEvent["PostEdit"] = "PostEdit";
+    HookEvent["SessionStart"] = "SessionStart";
+    HookEvent["SessionEnd"] = "SessionEnd";
+    HookEvent["PreCompact"] = "PreCompact";
+    HookEvent["Notification"] = "Notification";
+    HookEvent["SubagentStart"] = "SubagentStart";
+    HookEvent["SubagentStop"] = "SubagentStop";
+    HookEvent["PermissionRequest"] = "PermissionRequest";
+    HookEvent["TaskCompleted"] = "TaskCompleted";
+})(HookEvent || (HookEvent = {}));
+// ============================================================================
+// AdvancedHookRunner
+// ============================================================================
+export class AdvancedHookRunner {
+    workingDirectory;
+    timeout;
+    constructor(workingDirectory = process.cwd(), timeout = 30000) {
+        this.workingDirectory = workingDirectory;
+        this.timeout = timeout;
+    }
+    /**
+     * Run a hook and return a decision
+     */
+    async runHook(hook, context) {
+        switch (hook.type) {
+            case 'command':
+                return this.runCommandHook(hook, context);
+            case 'prompt':
+                return this.runPromptHook(hook, context);
+            case 'agent':
+                return this.runAgentHook(hook, context);
+            default:
+                logger.warn(`Unknown hook type: ${hook.type}`, { source: 'AdvancedHookRunner' });
+                return { action: 'allow' };
+        }
+    }
+    /**
+     * Fire-and-forget async hook execution
+     */
+    async runHookAsync(hook, context) {
+        this.runHook(hook, context).catch((error) => {
+            logger.warn(`Async hook "${hook.name}" failed: ${error}`, { source: 'AdvancedHookRunner' });
+        });
+    }
+    /**
+     * Check if a hook matches a given event and optional tool name
+     */
+    matchesEvent(hook, event, toolName) {
+        if (hook.event !== event) {
+            return false;
+        }
+        if (hook.matcher && toolName) {
+            return hook.matcher.test(toolName);
+        }
+        // If no matcher, match all tools for that event
+        if (!hook.matcher) {
+            return true;
+        }
+        // Has matcher but no toolName provided - no match
+        return false;
+    }
+    async runCommandHook(hook, context) {
+        if (!hook.command) {
+            logger.warn(`Command hook "${hook.name}" has no command`, { source: 'AdvancedHookRunner' });
+            return { action: 'allow' };
+        }
+        return new Promise((resolve) => {
+            let timedOut = false;
+            const child = spawn(hook.command, [], {
+                cwd: this.workingDirectory,
+                shell: true,
+                env: {
+                    ...process.env,
+                    HOOK_EVENT: context.event,
+                    HOOK_TOOL: context.toolName || '',
+                    HOOK_INPUT: JSON.stringify(context.input || {}),
+                },
+            });
+            let stdout = '';
+            let stderr = '';
+            const timeoutId = setTimeout(() => {
+                timedOut = true;
+                child.kill('SIGTERM');
+            }, this.timeout);
+            child.stdout?.on('data', (data) => {
+                stdout += data.toString();
+            });
+            child.stderr?.on('data', (data) => {
+                stderr += data.toString();
+            });
+            child.on('close', (code) => {
+                clearTimeout(timeoutId);
+                if (timedOut) {
+                    logger.warn(`Command hook "${hook.name}" timed out`, { source: 'AdvancedHookRunner' });
+                    resolve({ action: 'allow' });
+                    return;
+                }
+                if (code !== 0) {
+                    logger.warn(`Command hook "${hook.name}" exited with code ${code}: ${stderr}`, { source: 'AdvancedHookRunner' });
+                    resolve({ action: 'allow' });
+                    return;
+                }
+                try {
+                    const decision = JSON.parse(stdout.trim());
+                    if (decision.action && ['allow', 'deny', 'ask'].includes(decision.action)) {
+                        resolve(decision);
+                    }
+                    else {
+                        logger.warn(`Command hook "${hook.name}" returned invalid action`, { source: 'AdvancedHookRunner' });
+                        resolve({ action: 'allow' });
+                    }
+                }
+                catch {
+                    // Non-JSON output: if exit code 0, allow; non-zero handled above
+                    resolve({ action: 'allow' });
+                }
+            });
+            child.on('error', (error) => {
+                clearTimeout(timeoutId);
+                logger.warn(`Command hook "${hook.name}" failed: ${error.message}`, { source: 'AdvancedHookRunner' });
+                resolve({ action: 'allow' });
+            });
+        });
+    }
+    async runPromptHook(hook, _context) {
+        // Stub: returns allow with the prompt text stored as additional context
+        logger.debug(`Prompt hook "${hook.name}" evaluated (stub)`, { source: 'AdvancedHookRunner' });
+        return {
+            action: 'allow',
+            additionalContext: hook.prompt || undefined,
+        };
+    }
+    async runAgentHook(hook, _context) {
+        // Stub: returns allow
+        logger.debug(`Agent hook "${hook.name}" evaluated (stub)`, { source: 'AdvancedHookRunner' });
+        return { action: 'allow' };
+    }
+}
+// ============================================================================
+// HookRegistry
+// ============================================================================
+export class HookRegistry {
+    hooks = new Map();
+    firedOnceHooks = new Set();
+    /**
+     * Add a hook to the registry
+     */
+    addHook(hook) {
+        this.hooks.set(hook.name, hook);
+        logger.debug(`Hook "${hook.name}" registered for event ${hook.event}`, { source: 'HookRegistry' });
+    }
+    /**
+     * Remove a hook by name
+     */
+    removeHook(name) {
+        const deleted = this.hooks.delete(name);
+        this.firedOnceHooks.delete(name);
+        if (deleted) {
+            logger.debug(`Hook "${name}" removed`, { source: 'HookRegistry' });
+        }
+        return deleted;
+    }
+    /**
+     * Get all hooks that match a given event, filtering out already-fired once hooks
+     */
+    getHooksForEvent(event, toolName) {
+        const runner = new AdvancedHookRunner();
+        const matching = [];
+        for (const hook of this.hooks.values()) {
+            // Skip once hooks that already fired
+            if (hook.once && this.firedOnceHooks.has(hook.name)) {
+                continue;
+            }
+            if (runner.matchesEvent(hook, event, toolName)) {
+                matching.push(hook);
+            }
+        }
+        return matching;
+    }
+    /**
+     * Mark a once hook as fired
+     */
+    markFired(hookName) {
+        const hook = this.hooks.get(hookName);
+        if (hook?.once) {
+            this.firedOnceHooks.add(hookName);
+        }
+    }
+    /**
+     * List all registered hooks
+     */
+    listHooks() {
+        return Array.from(this.hooks.values());
+    }
+    /**
+     * Get a hook by name
+     */
+    getHook(name) {
+        return this.hooks.get(name);
+    }
+    /**
+     * Clear all hooks
+     */
+    clear() {
+        this.hooks.clear();
+        this.firedOnceHooks.clear();
+    }
+    /**
+     * Get the number of registered hooks
+     */
+    get size() {
+        return this.hooks.size;
+    }
+}
+// ============================================================================
+// Singleton
+// ============================================================================
+let registryInstance = null;
+let runnerInstance = null;
+export function getHookRegistry() {
+    if (!registryInstance) {
+        registryInstance = new HookRegistry();
+    }
+    return registryInstance;
+}
+export function getAdvancedHookRunner(workingDirectory) {
+    if (!runnerInstance || workingDirectory) {
+        runnerInstance = new AdvancedHookRunner(workingDirectory);
+    }
+    return runnerInstance;
+}
+export function resetAdvancedHooks() {
+    registryInstance = null;
+    runnerInstance = null;
+}
+//# sourceMappingURL=advanced-hooks.js.map

package/dist/hooks/advanced-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced-hooks.js","sourceRoot":"","sources":["../../src/hooks/advanced-hooks.ts"],"names":[],"mappings":"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"}

package/dist/hooks/async-hooks.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Async Hook Manager
+ *
+ * Manages asynchronous hook execution with concurrency control,
+ * job tracking, and result collection. Completed hook results
+ * can be injected as system messages into the next conversation turn.
+ */
+import type { SmartHookConfig, SmartHookResult } from './smart-hooks.js';
+export type AsyncHookStatus = 'running' | 'completed' | 'failed' | 'timeout' | 'cancelled';
+export interface AsyncHookJob {
+    /** Unique job ID */
+    id: string;
+    /** Hook configuration */
+    hookConfig: SmartHookConfig;
+    /** Input data */
+    input: Record<string, any>;
+    /** Start timestamp */
+    startTime: number;
+    /** Current status */
+    status: AsyncHookStatus;
+    /** Result (when completed) */
+    result?: SmartHookResult;
+    /** Error message (when failed) */
+    error?: string;
+}
+export declare class AsyncHookManager {
+    private jobs;
+    private maxConcurrent;
+    private runner;
+    private completedSinceLastCheck;
+    private cancelTokens;
+    constructor(maxConcurrent?: number);
+    /**
+     * Submit an async hook for execution
+     */
+    submit(hook: SmartHookConfig, input: Record<string, any>): string;
+    /**
+     * Execute a job asynchronously
+     */
+    private executeJob;
+    /**
+     * Get a job by ID
+     */
+    getJob(jobId: string): AsyncHookJob | null;
+    /**
+     * Get all jobs completed since the last call to this method
+     */
+    getCompletedJobs(): AsyncHookJob[];
+    /**
+     * Get results formatted as system messages for the next conversation turn
+     */
+    getSystemMessages(): string[];
+    /**
+     * Clear all completed/failed jobs
+     */
+    clearCompleted(): void;
+    /**
+     * Cancel a running job
+     */
+    cancel(jobId: string): boolean;
+    /**
+     * Get the number of currently running jobs
+     */
+    getRunningCount(): number;
+    /**
+     * Get the total number of tracked jobs
+     */
+    getTotalCount(): number;
+    /**
+     * Dispose of all jobs and clean up
+     */
+    dispose(): void;
+}

package/dist/hooks/async-hooks.js

@@ -0,0 +1,213 @@
+/**
+ * Async Hook Manager
+ *
+ * Manages asynchronous hook execution with concurrency control,
+ * job tracking, and result collection. Completed hook results
+ * can be injected as system messages into the next conversation turn.
+ */
+import { randomUUID } from 'crypto';
+import { logger } from '../utils/logger.js';
+import { SmartHookRunner } from './smart-hooks.js';
+// ============================================================================
+// AsyncHookManager
+// ============================================================================
+export class AsyncHookManager {
+    jobs = new Map();
+    maxConcurrent;
+    runner;
+    completedSinceLastCheck = [];
+    cancelTokens = new Map();
+    constructor(maxConcurrent) {
+        this.maxConcurrent = maxConcurrent ?? 10;
+        this.runner = new SmartHookRunner();
+        logger.debug(`AsyncHookManager initialized with max ${this.maxConcurrent} concurrent`, { source: 'AsyncHookManager' });
+    }
+    /**
+     * Submit an async hook for execution
+     */
+    submit(hook, input) {
+        // Check concurrency limit
+        const runningCount = this.getRunningCount();
+        if (runningCount >= this.maxConcurrent) {
+            logger.warn(`Max concurrent hooks reached (${this.maxConcurrent}), rejecting`, { source: 'AsyncHookManager' });
+            const jobId = randomUUID();
+            const job = {
+                id: jobId,
+                hookConfig: hook,
+                input,
+                startTime: Date.now(),
+                status: 'failed',
+                error: 'Max concurrent hooks reached',
+            };
+            this.jobs.set(jobId, job);
+            this.completedSinceLastCheck.push(jobId);
+            return jobId;
+        }
+        const jobId = randomUUID();
+        const job = {
+            id: jobId,
+            hookConfig: hook,
+            input,
+            startTime: Date.now(),
+            status: 'running',
+        };
+        this.jobs.set(jobId, job);
+        this.cancelTokens.set(jobId, false);
+        // Execute in background
+        this.executeJob(jobId, hook, input);
+        return jobId;
+    }
+    /**
+     * Execute a job asynchronously
+     */
+    async executeJob(jobId, hook, input) {
+        const timeout = hook.timeout ?? 30000;
+        try {
+            // Create a timeout race
+            const resultPromise = this.runner.runHook(hook, input);
+            const timeoutPromise = new Promise((_, reject) => {
+                setTimeout(() => reject(new Error('Hook execution timed out')), timeout);
+            });
+            const result = await Promise.race([resultPromise, timeoutPromise]);
+            const job = this.jobs.get(jobId);
+            if (!job)
+                return;
+            // Check if cancelled
+            if (this.cancelTokens.get(jobId)) {
+                job.status = 'cancelled';
+                job.error = 'Job was cancelled';
+                this.completedSinceLastCheck.push(jobId);
+                this.cancelTokens.delete(jobId);
+                return;
+            }
+            job.status = 'completed';
+            job.result = result;
+            this.completedSinceLastCheck.push(jobId);
+            this.cancelTokens.delete(jobId);
+            logger.debug(`Async hook ${jobId} completed`, { source: 'AsyncHookManager' });
+        }
+        catch (error) {
+            const job = this.jobs.get(jobId);
+            if (!job)
+                return;
+            const message = error instanceof Error ? error.message : String(error);
+            if (message.includes('timed out')) {
+                job.status = 'timeout';
+                job.error = 'Hook execution timed out';
+            }
+            else {
+                job.status = 'failed';
+                job.error = message;
+            }
+            this.completedSinceLastCheck.push(jobId);
+            this.cancelTokens.delete(jobId);
+            logger.warn(`Async hook ${jobId} failed: ${message}`, { source: 'AsyncHookManager' });
+        }
+    }
+    /**
+     * Get a job by ID
+     */
+    getJob(jobId) {
+        return this.jobs.get(jobId) ?? null;
+    }
+    /**
+     * Get all jobs completed since the last call to this method
+     */
+    getCompletedJobs() {
+        const completed = [];
+        for (const jobId of this.completedSinceLastCheck) {
+            const job = this.jobs.get(jobId);
+            if (job && job.status !== 'running') {
+                completed.push({ ...job });
+            }
+        }
+        this.completedSinceLastCheck = [];
+        return completed;
+    }
+    /**
+     * Get results formatted as system messages for the next conversation turn
+     */
+    getSystemMessages() {
+        const completed = this.getCompletedJobs();
+        const messages = [];
+        for (const job of completed) {
+            if (job.status === 'completed' && job.result) {
+                const prefix = `[Async Hook: ${job.hookConfig.event}]`;
+                if (job.result.ok) {
+                    messages.push(`${prefix} Success: ${job.result.output ?? 'No output'}`);
+                }
+                else {
+                    messages.push(`${prefix} Failed: ${job.result.reason ?? 'Unknown error'}`);
+                }
+            }
+            else if (job.status === 'failed' || job.status === 'timeout') {
+                messages.push(`[Async Hook: ${job.hookConfig.event}] Error: ${job.error ?? 'Unknown error'}`);
+            }
+            else if (job.status === 'cancelled') {
+                messages.push(`[Async Hook: ${job.hookConfig.event}] Cancelled`);
+            }
+        }
+        return messages;
+    }
+    /**
+     * Clear all completed/failed jobs
+     */
+    clearCompleted() {
+        const toRemove = [];
+        this.jobs.forEach((job, id) => {
+            if (job.status !== 'running') {
+                toRemove.push(id);
+            }
+        });
+        for (const id of toRemove) {
+            this.jobs.delete(id);
+            this.cancelTokens.delete(id);
+        }
+        logger.debug(`Cleared ${toRemove.length} completed jobs`, { source: 'AsyncHookManager' });
+    }
+    /**
+     * Cancel a running job
+     */
+    cancel(jobId) {
+        const job = this.jobs.get(jobId);
+        if (!job || job.status !== 'running') {
+            return false;
+        }
+        this.cancelTokens.set(jobId, true);
+        return true;
+    }
+    /**
+     * Get the number of currently running jobs
+     */
+    getRunningCount() {
+        let count = 0;
+        this.jobs.forEach((job) => {
+            if (job.status === 'running') {
+                count++;
+            }
+        });
+        return count;
+    }
+    /**
+     * Get the total number of tracked jobs
+     */
+    getTotalCount() {
+        return this.jobs.size;
+    }
+    /**
+     * Dispose of all jobs and clean up
+     */
+    dispose() {
+        // Mark all running as cancelled
+        this.jobs.forEach((job, id) => {
+            if (job.status === 'running') {
+                this.cancelTokens.set(id, true);
+            }
+        });
+        this.jobs.clear();
+        this.cancelTokens.clear();
+        this.completedSinceLastCheck = [];
+        logger.debug('AsyncHookManager disposed', { source: 'AsyncHookManager' });
+    }
+}
+//# sourceMappingURL=async-hooks.js.map

package/dist/hooks/async-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-hooks.js","sourceRoot":"","sources":["../../src/hooks/async-hooks.ts"],"names":[],"mappings":"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"}

package/dist/hooks/env-persistence.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Environment Persistence
+ *
+ * Persists environment variables across sessions via env files.
+ * Supports setup hooks that modify env and captures changes for replay.
+ *
+ * Format: standard shell-compatible `export VAR=value` lines.
+ */
+export declare class EnvPersistence {
+    private envFilePath;
+    private sessionEnv;
+    private sessionId;
+    constructor(sessionId?: string);
+    /**
+     * Get the path to the env persistence file
+     */
+    getEnvFilePath(): string;
+    /**
+     * Get the session ID
+     */
+    getSessionId(): string;
+    /**
+     * Set an environment variable and persist it
+     */
+    setVar(name: string, value: string): void;
+    /**
+     * Remove an environment variable
+     */
+    unsetVar(name: string): void;
+    /**
+     * Load all persisted environment variables from the env file
+     */
+    loadEnv(): Record<string, string>;
+    /**
+     * Apply all persisted env vars to process.env
+     */
+    applyToProcess(): void;
+    /**
+     * Parse an env file with `export VAR=value` format
+     */
+    parseEnvFile(content: string): Record<string, string>;
+    /**
+     * Serialize env vars to file content
+     */
+    serializeEnv(env: Record<string, string>): string;
+    /**
+     * Capture environment changes between before and after snapshots
+     */
+    captureEnvChanges(beforeEnv: Record<string, string>, afterEnv: Record<string, string>): Record<string, string>;
+    /**
+     * Clean up the env file
+     */
+    cleanup(): void;
+    /**
+     * Write current env state to file
+     */
+    private flush;
+}