@defai.digital/ax-cli 3.12.1 → 3.12.5

package/dist/hooks/manager.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Hooks Manager
+ *
+ * Manages loading, registration, and execution of hooks.
+ *
+ * @packageDocumentation
+ */
+import type { AnyHookConfig, HookEventType, HookInput, HookExecutionResult } from "./types.js";
+/**
+ * Hooks Manager
+ *
+ * Singleton that manages hook registration and execution.
+ */
+export declare class HooksManager {
+    private static instance;
+    private hooks;
+    private projectDir;
+    private userDir;
+    private initialized;
+    private constructor();
+    /**
+     * Get the singleton instance
+     */
+    static getInstance(): HooksManager;
+    /**
+     * Reset the singleton (for testing)
+     */
+    static reset(): void;
+    /**
+     * Register a hook programmatically
+     */
+    registerHook(hook: AnyHookConfig): void;
+    /**
+     * Ensure hooks are initialized (lazy init)
+     */
+    private ensureInitialized;
+    /**
+     * Get all hooks for a specific event type
+     */
+    getHooksForEvent(event: HookEventType, toolName?: string): AnyHookConfig[];
+    /**
+     * Match a tool name against a glob pattern
+     */
+    private matchToolPattern;
+    /**
+     * Execute hooks for an event
+     */
+    executeHooks(event: HookEventType, input: HookInput): Promise<HookExecutionResult[]>;
+    /**
+     * Execute a single hook
+     */
+    private executeHook;
+    /**
+     * Execute a command hook
+     */
+    private executeCommandHook;
+    /**
+     * Check if any PreToolUse hook blocks the tool execution
+     */
+    shouldBlockTool(toolName: string, toolArgs: Record<string, unknown>, toolId: string): Promise<{
+        blocked: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Process user input through UserPromptSubmit hooks
+     */
+    processUserInput(userInput: string): Promise<string>;
+    /**
+     * Execute PostToolUse hooks (fire-and-forget)
+     */
+    executePostToolHooks(toolName: string, toolArgs: Record<string, unknown>, toolId: string, toolResult: import("../types/index.js").ToolResult): Promise<void>;
+    /**
+     * Get the list of registered hooks
+     */
+    getHooks(): AnyHookConfig[];
+    /**
+     * Clear all hooks
+     */
+    clearHooks(): void;
+}
+/**
+ * Get the singleton hooks manager instance
+ */
+export declare function getHooksManager(): HooksManager;

package/dist/hooks/manager.js

@@ -0,0 +1,344 @@
+/**
+ * Hooks Manager
+ *
+ * Manages loading, registration, and execution of hooks.
+ *
+ * @packageDocumentation
+ */
+import { spawn } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { extractErrorMessage } from "../utils/error-handler.js";
+/** Default hook timeout in milliseconds */
+const DEFAULT_HOOK_TIMEOUT = 60000;
+/** Config file names to check */
+const CONFIG_FILE_NAMES = ["hooks.json", "hooks.yaml", "hooks.yml"];
+/**
+ * Hooks Manager
+ *
+ * Singleton that manages hook registration and execution.
+ */
+export class HooksManager {
+    static instance = null;
+    hooks = [];
+    projectDir;
+    userDir;
+    initialized = false;
+    constructor() {
+        this.projectDir = process.cwd();
+        this.userDir = path.join(os.homedir(), ".ax-cli");
+    }
+    /**
+     * Get the singleton instance
+     */
+    static getInstance() {
+        if (!HooksManager.instance) {
+            HooksManager.instance = new HooksManager();
+        }
+        return HooksManager.instance;
+    }
+    /**
+     * Reset the singleton (for testing)
+     */
+    static reset() {
+        HooksManager.instance = null;
+    }
+    /**
+     * Register a hook programmatically
+     */
+    registerHook(hook) {
+        this.hooks.push(hook);
+    }
+    /**
+     * Ensure hooks are initialized (lazy init)
+     */
+    ensureInitialized() {
+        if (this.initialized)
+            return;
+        this.hooks = [];
+        // Load hooks from project directory (.ax-cli/hooks.json)
+        const projectHooksDir = path.join(this.projectDir, ".ax-cli");
+        for (const fileName of CONFIG_FILE_NAMES) {
+            const filePath = path.join(projectHooksDir, fileName);
+            if (fs.existsSync(filePath)) {
+                try {
+                    const content = fs.readFileSync(filePath, "utf-8");
+                    const config = JSON.parse(content);
+                    this.hooks.push(...(config.hooks || []));
+                    break;
+                }
+                catch (error) {
+                    console.warn(`Failed to load hooks from ${filePath}:`, extractErrorMessage(error));
+                }
+            }
+        }
+        // Load hooks from user directory (~/.ax-cli/hooks.json)
+        for (const fileName of CONFIG_FILE_NAMES) {
+            const filePath = path.join(this.userDir, fileName);
+            if (fs.existsSync(filePath)) {
+                try {
+                    const content = fs.readFileSync(filePath, "utf-8");
+                    const config = JSON.parse(content);
+                    this.hooks.push(...(config.hooks || []));
+                    break;
+                }
+                catch (error) {
+                    console.warn(`Failed to load hooks from ${filePath}:`, extractErrorMessage(error));
+                }
+            }
+        }
+        this.initialized = true;
+    }
+    /**
+     * Get all hooks for a specific event type
+     */
+    getHooksForEvent(event, toolName) {
+        this.ensureInitialized();
+        return this.hooks.filter((hook) => {
+            if (hook.event !== event)
+                return false;
+            if (hook.enabled === false)
+                return false;
+            // For tool-related events, check tool pattern
+            if ((event === "PreToolUse" || event === "PostToolUse") && toolName) {
+                if (hook.toolPattern) {
+                    return this.matchToolPattern(toolName, hook.toolPattern);
+                }
+            }
+            return true;
+        });
+    }
+    /**
+     * Match a tool name against a glob pattern
+     */
+    matchToolPattern(toolName, pattern) {
+        // Simple glob matching: * matches any characters
+        const regexPattern = pattern
+            .replace(/[.+?^${}()|[\]\\]/g, "\\$&") // Escape regex special chars
+            .replace(/\*/g, ".*"); // Convert * to .*
+        const regex = new RegExp(`^${regexPattern}$`);
+        return regex.test(toolName);
+    }
+    /**
+     * Execute hooks for an event
+     */
+    async executeHooks(event, input) {
+        const toolName = input.toolCall?.name;
+        const hooks = this.getHooksForEvent(event, toolName);
+        if (hooks.length === 0) {
+            return [];
+        }
+        // Execute all matching hooks in parallel
+        const results = await Promise.all(hooks.map((hook) => this.executeHook(hook, input)));
+        return results;
+    }
+    /**
+     * Execute a single hook
+     */
+    async executeHook(hook, input) {
+        const startTime = Date.now();
+        try {
+            if (hook.type === "command") {
+                return await this.executeCommandHook(hook, input);
+            }
+            else {
+                // Prompt hooks would require LLM integration
+                // For now, return a placeholder
+                return {
+                    success: false,
+                    error: "Prompt hooks not yet implemented",
+                    durationMs: Date.now() - startTime,
+                };
+            }
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: extractErrorMessage(error),
+                durationMs: Date.now() - startTime,
+            };
+        }
+    }
+    /**
+     * Execute a command hook
+     */
+    async executeCommandHook(hook, input) {
+        const startTime = Date.now();
+        const timeout = hook.timeout || DEFAULT_HOOK_TIMEOUT;
+        return new Promise((resolve) => {
+            const env = {
+                ...process.env,
+                ...hook.env,
+                AXCLI_PROJECT_DIR: input.projectDir,
+                AXCLI_EVENT: input.event,
+                AXCLI_HOOK_INPUT: JSON.stringify(input),
+            };
+            const child = spawn(hook.command, [], {
+                shell: true,
+                cwd: hook.cwd || input.projectDir,
+                env,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            let stdout = "";
+            let stderr = "";
+            let timedOut = false;
+            // Send input as JSON to stdin
+            child.stdin.write(JSON.stringify(input));
+            child.stdin.end();
+            child.stdout.on("data", (data) => {
+                stdout += data.toString();
+            });
+            child.stderr.on("data", (data) => {
+                stderr += data.toString();
+            });
+            const timeoutId = setTimeout(() => {
+                timedOut = true;
+                child.kill("SIGTERM");
+            }, timeout);
+            child.on("close", (code) => {
+                clearTimeout(timeoutId);
+                if (timedOut) {
+                    resolve({
+                        success: false,
+                        error: `Hook timed out after ${timeout}ms`,
+                        durationMs: Date.now() - startTime,
+                    });
+                    return;
+                }
+                // Parse output for special fields
+                let output = {
+                    exitCode: code || 0,
+                    stdout: stdout.trim(),
+                    stderr: stderr.trim(),
+                };
+                // Try to parse JSON output for structured response
+                try {
+                    if (stdout.trim().startsWith("{")) {
+                        const parsed = JSON.parse(stdout.trim());
+                        if (parsed.permissionDecision) {
+                            output.permissionDecision = parsed.permissionDecision;
+                        }
+                        if (parsed.updatedInput) {
+                            output.updatedInput = parsed.updatedInput;
+                        }
+                    }
+                }
+                catch {
+                    // Not JSON, use raw output
+                }
+                resolve({
+                    success: code === 0,
+                    output,
+                    durationMs: Date.now() - startTime,
+                });
+            });
+            child.on("error", (error) => {
+                clearTimeout(timeoutId);
+                resolve({
+                    success: false,
+                    error: extractErrorMessage(error),
+                    durationMs: Date.now() - startTime,
+                });
+            });
+        });
+    }
+    /**
+     * Check if any PreToolUse hook blocks the tool execution
+     */
+    async shouldBlockTool(toolName, toolArgs, toolId) {
+        const input = {
+            event: "PreToolUse",
+            projectDir: this.projectDir,
+            timestamp: new Date().toISOString(),
+            toolCall: {
+                name: toolName,
+                arguments: toolArgs,
+                id: toolId,
+            },
+        };
+        const results = await this.executeHooks("PreToolUse", input);
+        for (const result of results) {
+            if (!result.success) {
+                // Hook execution failed - treat as non-blocking but log
+                console.warn(`PreToolUse hook failed: ${result.error}`);
+                continue;
+            }
+            // Check for explicit denial
+            if (result.output?.permissionDecision === "deny") {
+                return {
+                    blocked: true,
+                    reason: result.output.stderr || result.output.stdout || "Blocked by hook",
+                };
+            }
+            // Exit code 2 means blocking error
+            if (result.output?.exitCode === 2) {
+                return {
+                    blocked: true,
+                    reason: result.output.stderr || result.output.stdout || "Blocked by hook",
+                };
+            }
+        }
+        return { blocked: false };
+    }
+    /**
+     * Process user input through UserPromptSubmit hooks
+     */
+    async processUserInput(userInput) {
+        const input = {
+            event: "UserPromptSubmit",
+            projectDir: this.projectDir,
+            timestamp: new Date().toISOString(),
+            userInput,
+        };
+        const results = await this.executeHooks("UserPromptSubmit", input);
+        // Check for modified input from any hook
+        for (const result of results) {
+            if (result.success && result.output?.updatedInput) {
+                return result.output.updatedInput;
+            }
+        }
+        return userInput;
+    }
+    /**
+     * Execute PostToolUse hooks (fire-and-forget)
+     */
+    async executePostToolHooks(toolName, toolArgs, toolId, toolResult) {
+        const input = {
+            event: "PostToolUse",
+            projectDir: this.projectDir,
+            timestamp: new Date().toISOString(),
+            toolCall: {
+                name: toolName,
+                arguments: toolArgs,
+                id: toolId,
+            },
+            toolResult,
+        };
+        // Execute hooks but don't wait for them
+        this.executeHooks("PostToolUse", input).catch((error) => {
+            console.warn("PostToolUse hook error:", extractErrorMessage(error));
+        });
+    }
+    /**
+     * Get the list of registered hooks
+     */
+    getHooks() {
+        this.ensureInitialized();
+        return [...this.hooks];
+    }
+    /**
+     * Clear all hooks
+     */
+    clearHooks() {
+        this.hooks = [];
+        this.initialized = false;
+    }
+}
+/**
+ * Get the singleton hooks manager instance
+ */
+export function getHooksManager() {
+    return HooksManager.getInstance();
+}
+//# sourceMappingURL=manager.js.map

package/dist/hooks/manager.js.map

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

package/dist/hooks/types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Hooks System Types
+ *
+ * Event-driven hooks for customizing tool execution and user interaction.
+ *
+ * @packageDocumentation
+ */
+import type { ToolResult } from "../types/index.js";
+/**
+ * Hook event types
+ */
+export type HookEventType = "PreToolUse" | "PostToolUse" | "UserPromptSubmit" | "Notification" | "Stop";
+/**
+ * Hook type - shell command or prompt-based
+ */
+export type HookType = "command" | "prompt";
+/**
+ * Hook decision for PreToolUse hooks
+ */
+export interface HookDecision {
+    /** Whether to allow the tool execution */
+    allow: boolean;
+    /** Optional reason for blocking */
+    reason?: string;
+    /** Optional modified input (for UserPromptSubmit) */
+    modifiedInput?: string;
+}
+/**
+ * Base hook configuration
+ */
+export interface HookConfig {
+    /** Unique identifier for this hook */
+    id?: string;
+    /** Event type that triggers this hook */
+    event: HookEventType;
+    /** Hook type: command (shell) or prompt (LLM evaluation) */
+    type: HookType;
+    /** Glob pattern to match tool names (for PreToolUse/PostToolUse) */
+    toolPattern?: string;
+    /** Whether this hook is enabled */
+    enabled?: boolean;
+    /** Timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+/**
+ * Shell command hook configuration
+ */
+export interface CommandHookConfig extends HookConfig {
+    type: "command";
+    /** Shell command to execute */
+    command: string;
+    /** Working directory for the command */
+    cwd?: string;
+    /** Environment variables to set */
+    env?: Record<string, string>;
+}
+/**
+ * Prompt-based hook configuration (uses Claude Haiku for evaluation)
+ */
+export interface PromptHookConfig extends HookConfig {
+    type: "prompt";
+    /** Prompt template for LLM evaluation */
+    prompt: string;
+    /** Model to use (default: haiku for speed) */
+    model?: string;
+}
+/**
+ * Union type for all hook configurations
+ */
+export type AnyHookConfig = CommandHookConfig | PromptHookConfig;
+/**
+ * Hook input data passed to hook execution
+ */
+export interface HookInput {
+    /** The event type */
+    event: HookEventType;
+    /** Session ID */
+    sessionId?: string;
+    /** Project directory */
+    projectDir: string;
+    /** Timestamp */
+    timestamp: string;
+    /** Tool call information (for PreToolUse/PostToolUse) */
+    toolCall?: {
+        name: string;
+        arguments: Record<string, unknown>;
+        id: string;
+    };
+    /** Tool result (for PostToolUse) */
+    toolResult?: ToolResult;
+    /** User input (for UserPromptSubmit) */
+    userInput?: string;
+    /** Notification message (for Notification) */
+    message?: string;
+}
+/**
+ * Hook output data returned from hook execution
+ */
+export interface HookOutput {
+    /** Exit code (0 = success, 2 = blocking error) */
+    exitCode: number;
+    /** Standard output */
+    stdout?: string;
+    /** Standard error */
+    stderr?: string;
+    /** Permission decision (for PreToolUse) */
+    permissionDecision?: "allow" | "deny";
+    /** Updated input (for UserPromptSubmit) */
+    updatedInput?: string;
+    /** Error message */
+    error?: string;
+}
+/**
+ * Hooks configuration file structure
+ */
+export interface HooksConfig {
+    /** Version of the hooks config schema */
+    version?: string;
+    /** Array of hook configurations */
+    hooks: AnyHookConfig[];
+}
+/**
+ * Hook execution result
+ */
+export interface HookExecutionResult {
+    /** Whether the hook executed successfully */
+    success: boolean;
+    /** Hook output */
+    output?: HookOutput;
+    /** Error if execution failed */
+    error?: string;
+    /** Execution duration in milliseconds */
+    durationMs?: number;
+}

package/dist/hooks/types.js

@@ -0,0 +1,9 @@
+/**
+ * Hooks System Types
+ *
+ * Event-driven hooks for customizing tool execution and user interaction.
+ *
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/hooks/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/hooks/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/llm/tools.js

@@ -369,6 +369,59 @@ const BASE_LLM_TOOLS = [
             },
         },
     },
+    {
+        type: "function",
+        function: {
+            name: "ask_user",
+            description: "Ask the user questions to gather preferences, clarify requirements, or get decisions on implementation choices. Use this when you need user input before proceeding. Supports multiple choice questions with 2-4 options per question.",
+            parameters: {
+                type: "object",
+                properties: {
+                    questions: {
+                        type: "array",
+                        description: "Questions to ask the user (1-4 questions)",
+                        items: {
+                            type: "object",
+                            properties: {
+                                question: {
+                                    type: "string",
+                                    description: "The complete question to ask the user. Should be clear and specific.",
+                                },
+                                header: {
+                                    type: "string",
+                                    description: "Short label for the question (max 12 chars). E.g., 'Auth method', 'Library'.",
+                                },
+                                options: {
+                                    type: "array",
+                                    description: "Available choices (2-4 options). 'Other' is added automatically.",
+                                    items: {
+                                        type: "object",
+                                        properties: {
+                                            label: {
+                                                type: "string",
+                                                description: "Display text for this option (1-5 words).",
+                                            },
+                                            description: {
+                                                type: "string",
+                                                description: "Explanation of what this option means.",
+                                            },
+                                        },
+                                        required: ["label", "description"],
+                                    },
+                                },
+                                multiSelect: {
+                                    type: "boolean",
+                                    description: "Allow multiple selections (default: false).",
+                                },
+                            },
+                            required: ["question", "options"],
+                        },
+                    },
+                },
+                required: ["questions"],
+            },
+        },
+    },
 ];
 /**
  * Exported tool definitions