@bluehawks/cli 1.0.0

package/src/core/tools/definitions/shell.ts

@@ -0,0 +1,228 @@
+/**
+ * Bluehawks CLI - Shell Command Tool
+ * Execute shell commands with safety controls
+ */
+
+import { spawn } from 'node:child_process';
+import { toolRegistry, type ToolHandler } from '../registry.js';
+import { COMMAND_TIMEOUT_MS, MAX_OUTPUT_LENGTH } from '../../../config/constants.js';
+
+// Dangerous command patterns
+const DANGEROUS_PATTERNS = [
+    /\brm\s+-rf?\s+[\/~]/i,
+    /\bsudo\b/i,
+    /\bchmod\s+777\b/i,
+    /\bchown\b/i,
+    /\bmkfs\b/i,
+    /\bdd\s+if=/i,
+    />\s*\/dev\//i,
+    /\bshutdown\b/i,
+    /\breboot\b/i,
+    /\bhalt\b/i,
+    /\bpoweroff\b/i,
+];
+
+function isDangerousCommand(command: string): { dangerous: boolean; reason?: string } {
+    for (const pattern of DANGEROUS_PATTERNS) {
+        if (pattern.test(command)) {
+            return {
+                dangerous: true,
+                reason: `Command matches dangerous pattern: ${pattern.source}`,
+            };
+        }
+    }
+    return { dangerous: false };
+}
+
+interface CommandResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    signal: string | null;
+}
+
+async function executeCommand(
+    command: string,
+    cwd: string,
+    timeout: number
+): Promise<CommandResult> {
+    return new Promise((resolve, reject) => {
+        // Determine shell based on platform
+        const shell = process.platform === 'win32' ? 'cmd.exe' : '/bin/bash';
+        const shellArgs = process.platform === 'win32' ? ['/c', command] : ['-c', command];
+
+        const child = spawn(shell, shellArgs, {
+            cwd,
+            env: { ...process.env, TERM: 'dumb' },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+
+        let stdout = '';
+        let stderr = '';
+        let killed = false;
+
+        const timeoutId = setTimeout(() => {
+            killed = true;
+            child.kill('SIGTERM');
+            // Force kill after 5 seconds if still running
+            setTimeout(() => child.kill('SIGKILL'), 5000);
+        }, timeout);
+
+        child.stdout?.on('data', (data) => {
+            stdout += data.toString();
+            // Truncate if too long
+            if (stdout.length > MAX_OUTPUT_LENGTH) {
+                stdout = stdout.substring(0, MAX_OUTPUT_LENGTH) + '\n... (output truncated)';
+                child.kill('SIGTERM');
+            }
+        });
+
+        child.stderr?.on('data', (data) => {
+            stderr += data.toString();
+            if (stderr.length > MAX_OUTPUT_LENGTH) {
+                stderr = stderr.substring(0, MAX_OUTPUT_LENGTH) + '\n... (output truncated)';
+            }
+        });
+
+        child.on('close', (code, signal) => {
+            clearTimeout(timeoutId);
+            if (killed && !signal) {
+                reject(new Error('Command timed out'));
+            } else {
+                resolve({
+                    stdout: stdout.trim(),
+                    stderr: stderr.trim(),
+                    exitCode: code,
+                    signal: signal,
+                });
+            }
+        });
+
+        child.on('error', (error) => {
+            clearTimeout(timeoutId);
+            reject(error);
+        });
+    });
+}
+
+const runCommandTool: ToolHandler = {
+    name: 'run_command',
+    safeToAutoRun: false,
+    definition: {
+        type: 'function',
+        function: {
+            name: 'run_command',
+            description:
+                'Execute a shell command. Use this for running tests, building projects, git commands, and other shell operations.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    command: {
+                        type: 'string',
+                        description: 'The shell command to execute.',
+                    },
+                    cwd: {
+                        type: 'string',
+                        description:
+                            'The working directory for the command. Defaults to the current directory.',
+                    },
+                    timeout: {
+                        type: 'number',
+                        description: `Timeout in milliseconds. Default is ${COMMAND_TIMEOUT_MS}ms.`,
+                    },
+                },
+                required: ['command'],
+            },
+        },
+    },
+    async execute(args) {
+        const command = args.command as string;
+        const cwd = (args.cwd as string) || process.cwd();
+        const timeout = (args.timeout as number) || COMMAND_TIMEOUT_MS;
+
+        // Check for dangerous commands
+        const dangerCheck = isDangerousCommand(command);
+        if (dangerCheck.dangerous) {
+            throw new Error(`Dangerous command detected: ${dangerCheck.reason}`);
+        }
+
+        const result = await executeCommand(command, cwd, timeout);
+
+        // Format output
+        let output = '';
+
+        if (result.stdout) {
+            output += result.stdout;
+        }
+
+        if (result.stderr) {
+            if (output) output += '\n\n';
+            output += `STDERR:\n${result.stderr}`;
+        }
+
+        if (result.exitCode !== 0) {
+            output += `\n\nExit code: ${result.exitCode}`;
+        }
+
+        if (result.signal) {
+            output += `\n\nTerminated by signal: ${result.signal}`;
+        }
+
+        return output || '(no output)';
+    },
+};
+
+// Background command tool (for long-running processes)
+const runBackgroundCommandTool: ToolHandler = {
+    name: 'run_background_command',
+    safeToAutoRun: false,
+    definition: {
+        type: 'function',
+        function: {
+            name: 'run_background_command',
+            description:
+                'Start a background process like a dev server. The command will run in the background.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    command: {
+                        type: 'string',
+                        description: 'The shell command to run in the background.',
+                    },
+                    cwd: {
+                        type: 'string',
+                        description: 'The working directory for the command.',
+                    },
+                },
+                required: ['command'],
+            },
+        },
+    },
+    async execute(args) {
+        const command = args.command as string;
+        const cwd = (args.cwd as string) || process.cwd();
+
+        const dangerCheck = isDangerousCommand(command);
+        if (dangerCheck.dangerous) {
+            throw new Error(`Dangerous command detected: ${dangerCheck.reason}`);
+        }
+
+        const shell = process.platform === 'win32' ? 'cmd.exe' : '/bin/bash';
+        const shellArgs = process.platform === 'win32' ? ['/c', command] : ['-c', command];
+
+        const child = spawn(shell, shellArgs, {
+            cwd,
+            detached: true,
+            stdio: 'ignore',
+        });
+
+        child.unref();
+
+        return `Started background process with PID: ${child.pid}\nCommand: ${command}`;
+    },
+};
+
+export function registerShellTools(): void {
+    toolRegistry.register(runCommandTool);
+    toolRegistry.register(runBackgroundCommandTool);
+}

package/src/core/tools/definitions/web.ts

@@ -0,0 +1,113 @@
+/**
+ * Bluehawks CLI - Web Tools
+ * Tools for fetching web content
+ */
+
+import { toolRegistry, type ToolHandler } from '../registry.js';
+import { DEFAULT_TIMEOUT_MS } from '../../../config/constants.js';
+
+const fetchUrlTool: ToolHandler = {
+    name: 'fetch_url',
+    safeToAutoRun: true,
+    definition: {
+        type: 'function',
+        function: {
+            name: 'fetch_url',
+            description:
+                'Fetch content from a URL. Useful for reading documentation, API responses, or web pages.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    url: {
+                        type: 'string',
+                        description: 'The URL to fetch.',
+                    },
+                    method: {
+                        type: 'string',
+                        enum: ['GET', 'POST', 'PUT', 'DELETE'],
+                        description: 'HTTP method. Default is GET.',
+                    },
+                    headers: {
+                        type: 'object',
+                        description: 'Optional HTTP headers as key-value pairs.',
+                    },
+                    body: {
+                        type: 'string',
+                        description: 'Optional request body for POST/PUT.',
+                    },
+                    timeout: {
+                        type: 'number',
+                        description: 'Timeout in milliseconds.',
+                    },
+                },
+                required: ['url'],
+            },
+        },
+    },
+    async execute(args) {
+        const url = args.url as string;
+        const method = (args.method as string) || 'GET';
+        const headers = (args.headers as Record<string, string>) || {};
+        const body = args.body as string | undefined;
+        const timeout = (args.timeout as number) || DEFAULT_TIMEOUT_MS;
+
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+        try {
+            const response = await fetch(url, {
+                method,
+                headers: {
+                    'User-Agent': 'Bluehawks-CLI/1.0',
+                    ...headers,
+                },
+                body: body && ['POST', 'PUT'].includes(method) ? body : undefined,
+                signal: controller.signal,
+            });
+
+            clearTimeout(timeoutId);
+
+            const contentType = response.headers.get('content-type') || '';
+            let content: string;
+
+            if (contentType.includes('application/json')) {
+                const json = await response.json();
+                content = JSON.stringify(json, null, 2);
+            } else {
+                content = await response.text();
+
+                // Simple HTML to text conversion
+                if (contentType.includes('text/html')) {
+                    content = content
+                        .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '')
+                        .replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, '')
+                        .replace(/<[^>]+>/g, '\n')
+                        .replace(/&nbsp;/g, ' ')
+                        .replace(/&lt;/g, '<')
+                        .replace(/&gt;/g, '>')
+                        .replace(/&amp;/g, '&')
+                        .replace(/\n\s*\n/g, '\n\n')
+                        .trim();
+                }
+            }
+
+            // Truncate if too long
+            const maxLength = 50000;
+            if (content.length > maxLength) {
+                content = content.substring(0, maxLength) + '\n... (content truncated)';
+            }
+
+            return `Status: ${response.status} ${response.statusText}\n\n${content}`;
+        } catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new Error('Request timed out');
+            }
+            throw error;
+        }
+    },
+};
+
+export function registerWebTools(): void {
+    toolRegistry.register(fetchUrlTool);
+}

package/src/core/tools/executor.ts

@@ -0,0 +1,145 @@
+/**
+ * Bluehawks CLI - Tool Executor
+ * Executes tools with safety controls and output handling
+ */
+
+import { toolRegistry, type ToolHandler } from './registry.js';
+import type { ToolCall, ToolResult } from '../api/types.js';
+import { MAX_OUTPUT_LENGTH } from '../../config/constants.js';
+
+export type ApprovalMode = 'always' | 'never' | 'unsafe-only';
+
+export interface ExecutorOptions {
+    approvalMode: ApprovalMode;
+    onApprovalRequest?: (toolName: string, args: Record<string, unknown>) => Promise<boolean>;
+    onToolStart?: (toolName: string, args: Record<string, unknown>) => void;
+    onToolEnd?: (toolName: string, result: string, isError: boolean) => void;
+}
+
+export class ToolExecutor {
+    private options: ExecutorOptions;
+
+    constructor(options: Partial<ExecutorOptions> = {}) {
+        this.options = {
+            approvalMode: options.approvalMode || 'unsafe-only',
+            onApprovalRequest: options.onApprovalRequest,
+            onToolStart: options.onToolStart,
+            onToolEnd: options.onToolEnd,
+        };
+    }
+
+    async executeToolCalls(toolCalls: ToolCall[]): Promise<ToolResult[]> {
+        const results: ToolResult[] = [];
+
+        for (const toolCall of toolCalls) {
+            const result = await this.executeToolCall(toolCall);
+            results.push(result);
+        }
+
+        return results;
+    }
+
+    async executeToolCall(toolCall: ToolCall): Promise<ToolResult> {
+        const { id, function: fn } = toolCall;
+        const { name, arguments: argsString } = fn;
+
+        let args: Record<string, unknown>;
+        try {
+            args = JSON.parse(argsString);
+        } catch {
+            return {
+                tool_call_id: id,
+                content: `Error: Failed to parse tool arguments: ${argsString}`,
+                isError: true,
+            };
+        }
+
+        const handler = toolRegistry.get(name);
+        if (!handler) {
+            return {
+                tool_call_id: id,
+                content: `Error: Unknown tool: ${name}`,
+                isError: true,
+            };
+        }
+
+        // Check if approval is needed
+        const needsApproval = await this.needsApproval(handler);
+        if (needsApproval) {
+            const approved = await this.requestApproval(name, args);
+            if (!approved) {
+                return {
+                    tool_call_id: id,
+                    content: 'Tool execution was denied by the user.',
+                    isError: true,
+                };
+            }
+        }
+
+        // Execute the tool
+        this.options.onToolStart?.(name, args);
+
+        try {
+            let result = await handler.execute(args);
+
+            // Truncate output if too long
+            if (result.length > MAX_OUTPUT_LENGTH) {
+                result = result.substring(0, MAX_OUTPUT_LENGTH) + '\n... (output truncated)';
+            }
+
+            this.options.onToolEnd?.(name, result, false);
+
+            return {
+                tool_call_id: id,
+                content: result,
+                isError: false,
+            };
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.options.onToolEnd?.(name, errorMessage, true);
+
+            return {
+                tool_call_id: id,
+                content: `Error: ${errorMessage}`,
+                isError: true,
+            };
+        }
+    }
+
+    private async needsApproval(handler: ToolHandler): Promise<boolean> {
+        switch (this.options.approvalMode) {
+            case 'never':
+                return false;
+            case 'always':
+                return true;
+            case 'unsafe-only':
+                return !handler.safeToAutoRun;
+            default:
+                return !handler.safeToAutoRun;
+        }
+    }
+
+    private async requestApproval(
+        toolName: string,
+        args: Record<string, unknown>
+    ): Promise<boolean> {
+        if (!this.options.onApprovalRequest) {
+            // If no approval handler, deny by default
+            return false;
+        }
+
+        return this.options.onApprovalRequest(toolName, args);
+    }
+
+    setApprovalMode(mode: ApprovalMode): void {
+        this.options.approvalMode = mode;
+    }
+
+    setApprovalHandler(
+        handler: (toolName: string, args: Record<string, unknown>) => Promise<boolean>
+    ): void {
+        this.options.onApprovalRequest = handler;
+    }
+}
+
+export const toolExecutor = new ToolExecutor();

package/src/core/tools/index.ts

@@ -0,0 +1,3 @@
+export * from './registry.js';
+export * from './executor.js';
+export * from './definitions/index.js';

package/src/core/tools/registry.ts

@@ -0,0 +1,44 @@
+/**
+ * Bluehawks CLI - Tool Registry
+ * Central registry for all available tools
+ */
+
+import type { ToolDefinition } from '../api/types.js';
+
+export interface ToolHandler {
+    name: string;
+    definition: ToolDefinition;
+    execute: (args: Record<string, unknown>) => Promise<string>;
+    safeToAutoRun: boolean;
+}
+
+class ToolRegistry {
+    private tools: Map<string, ToolHandler> = new Map();
+
+    register(handler: ToolHandler): void {
+        this.tools.set(handler.name, handler);
+    }
+
+    get(name: string): ToolHandler | undefined {
+        return this.tools.get(name);
+    }
+
+    getAll(): ToolHandler[] {
+        return Array.from(this.tools.values());
+    }
+
+    getDefinitions(): ToolDefinition[] {
+        return this.getAll().map((handler) => handler.definition);
+    }
+
+    has(name: string): boolean {
+        return this.tools.has(name);
+    }
+
+    isSafeToAutoRun(name: string): boolean {
+        const handler = this.tools.get(name);
+        return handler?.safeToAutoRun ?? false;
+    }
+}
+
+export const toolRegistry = new ToolRegistry();