@compilr-dev/cli 0.4.0

package/README.md

@@ -0,0 +1,110 @@
+# @compilr-dev/cli
+
+> AI-powered CLI assistant using @compilr-dev/agents
+
+## Overview
+
+An AI coding assistant for the terminal, built with the `@compilr-dev/agents` library. Supports multiple LLM providers (Claude, OpenAI, Gemini, Ollama) with streaming output, tool execution, and context management.
+
+## Features
+
+- **Multi-LLM Support** - Claude, OpenAI, Gemini, Ollama
+- **Streaming Output** - Real-time response display with cursor positioning
+- **Tool Execution** - File operations, git, code search, project detection
+- **Context Management** - Auto-compaction, LLM summarization, token tracking
+- **Persistent Footer** - Todo list and input prompt always visible
+- **Input Queueing** - Commands queued during agent execution (FIFO)
+- **Permissions** - Interactive approval for dangerous operations
+- **Esc to Cancel** - Immediately abort running agent
+
+## Installation
+
+```bash
+npm install -g @compilr-dev/cli
+```
+
+## Usage
+
+```bash
+# Start with default provider (Claude)
+compilr
+
+# Use a specific provider
+compilr --provider openai --model gpt-4o
+compilr --provider gemini --model gemini-1.5-pro
+compilr --provider ollama --model llama3.1:8b
+
+# Verbose mode (show tool filtering)
+compilr --verbose
+```
+
+## Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show available commands |
+| `/exit` | Exit the CLI |
+| `/clear` | Clear conversation history |
+| `/compact` | Compress context using LLM summarization |
+| `/tools` | List available tools |
+| `/tokens` | Show token usage |
+| `/context` | Show context statistics |
+
+## Requirements
+
+- Node.js 18 or higher
+- API key for your chosen provider:
+  - `ANTHROPIC_API_KEY` for Claude
+  - `OPENAI_API_KEY` for OpenAI
+  - `GOOGLE_API_KEY` for Gemini
+  - Ollama running locally (no API key needed)
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/scozzola/compilr-dev-cli.git
+cd compilr-dev-cli
+
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Build for production
+npm run build
+```
+
+## Architecture
+
+- **Runtime:** Node.js 18+
+- **Language:** TypeScript
+- **Agent Framework:** @compilr-dev/agents
+- **Coding Tools:** @compilr-dev/agents-coding
+- **UI:** Custom terminal zones (scrolling + persistent footer)
+
+## Documentation
+
+Specs in `/workspace/project-docs/00-requirements/compilr-dev-cli/`:
+- `poc-objectives.md` - Original validation objectives
+- `poc-scope.md` - Feature scope
+- `poc-architecture.md` - Technical design
+- `streaming-output-plan.md` - Streaming implementation
+- `theme-system-spec.md` - Theme configuration
+- `config-overlay-spec.md` - Settings system
+
+## License
+
+MIT
+
+## Links
+
+- [compilr.dev](https://compilr.dev) - Main website
+- [@compilr-dev/agents](https://www.npmjs.com/package/@compilr-dev/agents) - Agent library
+- [@compilr-dev/agents-coding](https://www.npmjs.com/package/@compilr-dev/agents-coding) - Coding tools
+- [GitHub](https://github.com/scozzola/compilr-dev-cli) - Source code
+
+---
+
+**Built with @compilr-dev/agents**

package/dist/agent.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Agent Configuration
+ *
+ * Creates and configures the Agent instance with
+ * ClaudeProvider, OllamaProvider, OpenAIProvider, or GeminiProvider
+ * and available tools.
+ */
+import { Agent } from '@compilr-dev/agents';
+import type { AgentEvent, PermissionHandler } from '@compilr-dev/agents';
+/**
+ * Supported providers
+ */
+export type ProviderType = 'claude' | 'ollama' | 'openai' | 'gemini';
+/**
+ * Context passed to onIterationLimitReached callback
+ */
+export interface IterationLimitContext {
+    iteration: number;
+    maxIterations: number;
+    toolCallCount: number;
+}
+export interface AgentOptions {
+    /** Use minimal tools (for basic testing) */
+    minimal?: boolean;
+    /** Maximum iterations per request */
+    maxIterations?: number;
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /** Provider to use: 'claude' (default), 'ollama', 'openai', or 'gemini' */
+    provider?: ProviderType;
+    /** Model to use (provider-specific) */
+    model?: string;
+    /** Permission handler for tool approval prompts */
+    onPermissionRequest?: PermissionHandler;
+    /** Callback for suggested next actions */
+    onSuggest?: (event: Extract<AgentEvent, {
+        type: 'suggest';
+    }>) => void;
+    /**
+     * Callback invoked when the agent reaches its iteration limit.
+     * Return a number to extend the limit by that many iterations,
+     * or false to stop execution.
+     */
+    onIterationLimitReached?: (context: IterationLimitContext) => Promise<number | false>;
+    /**
+     * Project context from COMPILR.md or CLAUDE.md.
+     * This is appended to the system prompt to give the agent project-specific knowledge.
+     */
+    projectContext?: string;
+}
+/**
+ * Get permission info for a tool by name.
+ * Returns undefined if the tool doesn't require special permission (always allowed).
+ */
+export declare function getToolPermissionInfo(toolName: string): {
+    level: 'once' | 'always' | 'session';
+    description: string;
+} | undefined;
+/**
+ * Creates an Agent instance configured with all tools.
+ */
+export declare function createAgent(options?: AgentOptions): Agent;

package/dist/agent.js

@@ -0,0 +1,317 @@
+/**
+ * Agent Configuration
+ *
+ * Creates and configures the Agent instance with
+ * ClaudeProvider, OllamaProvider, OpenAIProvider, or GeminiProvider
+ * and available tools.
+ */
+import { Agent, ClaudeProvider, OllamaProvider, OpenAIProvider, GeminiProvider, ContextManager, DEFAULT_CONTEXT_CONFIG, createTaskTool, createSuggestTool, defaultAgentTypes, TOOL_SETS, } from '@compilr-dev/agents';
+import { isAutoCompactEnabled } from './settings/index.js';
+import { getApiKey } from './utils/credentials.js';
+import { createToolRegistry, createMinimalToolRegistry } from './tools.js';
+import { getAgentRegistry } from './agents/registry.js';
+const SYSTEM_PROMPT = `You are a helpful coding assistant running in a terminal.
+
+AVAILABLE TOOLS (use these exact names - lowercase with underscores):
+
+File Operations:
+- read_file: Read contents of a file (parameter: path)
+- write_file: Create or overwrite a file (parameters: path, content)
+- edit: Replace text in a file (parameters: path, old_text, new_text)
+- glob: Find files matching a pattern (parameters: pattern, path)
+- grep: Search file contents with regex (parameters: pattern, path)
+
+Shell:
+- bash: Run shell commands (parameter: command)
+  For long-running commands (dev servers, watch modes), use run_in_background=true
+- bash_output: Get output from a background shell (parameter: shell_id)
+- kill_shell: Terminate a background shell (parameter: shell_id)
+
+BACKGROUND PROCESSES:
+When running commands that don't exit (like npm run dev, npm start, watch commands):
+1. Use bash with run_in_background=true to start the process
+2. The tool returns a shell_id you can use to monitor or kill the process
+3. Use bash_output with the shell_id to check output/status
+4. Use kill_shell with the shell_id to stop the process when done
+
+Example: Starting a dev server
+  bash(command="npm run dev", run_in_background=true) → returns shell_id
+  bash_output(shell_id="...") → check if server started
+  kill_shell(shell_id="...") → stop when done
+
+Git:
+- git_status: Show working tree status
+- git_diff: Show file differences
+- git_log: Show commit history (parameter: limit)
+- git_commit: Create a commit (parameters: message, files)
+- git_branch: List or manage branches
+
+Project Analysis:
+- detect_project: Detect project type and framework
+- find_project_root: Find the root directory of the project
+- run_tests: Run project test suite
+- run_lint: Run project linter
+
+Task Management:
+- todo_write: Add/update todo items (parameters: todos array)
+- todo_read: View current todo list
+
+Next Action Suggestions:
+- suggest: Suggest a next action to the user (parameters: action, reason)
+  The suggestion appears as ghost text in the input prompt (user presses Tab to accept).
+
+  IMPORTANT: Always use 'suggest' after completing a task or answering a question.
+  This is a mandatory part of your response workflow, not optional.
+
+  When to suggest:
+    - After ANY tool-based task → suggest verifying, testing, or next logical step
+    - After answering a question → suggest a follow-up to explore
+    - After explaining something → suggest trying it out or diving deeper
+    - When your reply ends with a question → suggest an answer option
+
+  Good suggestions are short commands or actions: "run npm test", "commit the changes",
+  "show me the API endpoints", "explain the error in more detail"
+
+Sub-agents (via task tool):
+- task: Spawn a specialized sub-agent for complex, multi-step tasks
+  Parameters: description (3-5 words), prompt (detailed task), subagent_type
+  Built-in types:
+    - explore: Fast codebase search and navigation
+    - code-review: Review code for bugs and best practices
+    - plan: Break down complex tasks into steps
+    - debug: Investigate and fix issues
+    - test-runner: Run and analyze tests
+    - refactor: Safe code refactoring
+    - security-audit: Scan for vulnerabilities
+    - doc-lookup: Search documentation
+    - general: General-purpose multi-step tasks
+  Custom agents may also be available (check /agents command).
+
+IMPORTANT RULES:
+1. Tool names are lowercase with underscores - use them exactly as shown
+2. If unsure which tool to use, pick the closest match from the list
+3. For simple questions (math, facts), answer directly without tools
+4. After calling a tool, you MUST respond with the result to the user - never end silently
+5. Use the task tool to delegate complex tasks to specialized sub-agents
+
+Current working directory: ${process.cwd()}`;
+/**
+ * Default permission rules for potentially dangerous operations
+ * Note: Tool names are lowercase (bash, write_file, edit, git_commit)
+ */
+const DEFAULT_PERMISSION_RULES = [
+    // File writes need approval each time (user can see diff before approving)
+    { toolName: 'write_file', level: 'once', description: 'Write/create files' },
+    { toolName: 'edit', level: 'once', description: 'Edit file contents' },
+    // Git operations that modify state
+    { toolName: 'git_commit', level: 'once', description: 'Create git commit' },
+    { toolName: 'git_branch', level: 'once', description: 'Create/delete git branches' },
+    // Shell commands need approval each time
+    { toolName: 'bash', level: 'once', description: 'Execute shell command' },
+    // Project runners (can have side effects)
+    { toolName: 'run_tests', level: 'once', description: 'Run test suite' },
+    { toolName: 'run_lint', level: 'once', description: 'Run linter (may auto-fix)' },
+    // Local file modifications
+    { toolName: 'backlog_write', level: 'once', description: 'Modify backlog file' },
+];
+/**
+ * Get permission info for a tool by name.
+ * Returns undefined if the tool doesn't require special permission (always allowed).
+ */
+export function getToolPermissionInfo(toolName) {
+    const rule = DEFAULT_PERMISSION_RULES.find(r => r.toolName === toolName);
+    if (rule) {
+        return {
+            level: rule.level,
+            description: rule.description ?? 'Requires approval',
+        };
+    }
+    return undefined;
+}
+/**
+ * Merges built-in agent types with custom agents from registry.
+ * Custom agents get safe read-only tools by default.
+ */
+function getMergedAgentTypes() {
+    const registry = getAgentRegistry();
+    const customAgents = registry.getCustomAgents();
+    // Start with default agent types (library now has correct tool names)
+    const mergedTypes = { ...defaultAgentTypes };
+    // Add custom agents from registry
+    for (const agent of customAgents) {
+        mergedTypes[agent.name] = {
+            description: agent.description,
+            systemPrompt: agent.systemPrompt,
+            defaultModel: agent.model === 'inherit' ? undefined : agent.model,
+            // Safe read-only tools for custom agents (using library's TOOL_SETS)
+            // Type assertion needed because TOOL_SETS typing might not be exported correctly
+            allowedTools: Array.isArray(TOOL_SETS.READ_ONLY) ? [...(TOOL_SETS.READ_ONLY)] : [],
+            maxIterations: 10,
+            contextMode: 'inherit-summary',
+        };
+    }
+    return mergedTypes;
+}
+/**
+ * Creates the appropriate LLM provider based on configuration.
+ */
+function createProvider(options) {
+    const providerType = options.provider ?? 'claude';
+    switch (providerType) {
+        case 'ollama': {
+            const model = options.model ?? 'llama3.1';
+            console.log(`Using Ollama provider with model: ${model}`);
+            const provider = new OllamaProvider({
+                model,
+                baseUrl: process.env.OLLAMA_BASE_URL ?? 'http://localhost:11434',
+            });
+            return provider;
+        }
+        case 'openai': {
+            const apiKey = getApiKey('openai');
+            if (!apiKey) {
+                throw new Error('OpenAI API key not found.\n' +
+                    'Run /keys to set it, or: export OPENAI_API_KEY=sk-...');
+            }
+            const model = options.model ?? 'gpt-4o';
+            console.log(`Using OpenAI provider with model: ${model}`);
+            const provider = new OpenAIProvider({ apiKey, model });
+            return provider;
+        }
+        case 'gemini': {
+            const apiKey = getApiKey('google');
+            if (!apiKey) {
+                throw new Error('Google AI API key not found.\n' +
+                    'Run /keys to set it, or: export GOOGLE_API_KEY=AI...');
+            }
+            const model = options.model ?? 'gemini-2.0-flash';
+            console.log(`Using Gemini provider with model: ${model}`);
+            const provider = new GeminiProvider({ apiKey, model });
+            return provider;
+        }
+        case 'claude':
+        default: {
+            const apiKey = getApiKey('anthropic');
+            if (!apiKey) {
+                throw new Error('Anthropic API key not found.\n' +
+                    'Run /keys to set it, or: export ANTHROPIC_API_KEY=sk-ant-...\n' +
+                    'Or use --provider ollama for local models.');
+            }
+            const model = options.model ?? 'claude-sonnet-4-20250514';
+            console.log(`Using Claude provider with model: ${model}`);
+            return new ClaudeProvider({ apiKey, model });
+        }
+    }
+}
+/**
+ * Returns the context window limit for each provider.
+ */
+function getProviderContextLimit(provider) {
+    switch (provider) {
+        case 'gemini':
+            return 1000000; // 1M tokens
+        case 'claude':
+            return 200000; // 200K tokens
+        case 'openai':
+            return 128000; // 128K tokens
+        case 'ollama':
+            return 32000; // Conservative default for local models
+        default:
+            return 200000;
+    }
+}
+/**
+ * Creates an Agent instance configured with all tools.
+ */
+export function createAgent(options = {}) {
+    const provider = createProvider(options);
+    // Create context manager with provider-appropriate limits
+    // Uses library defaults: compact at 50%, summarize at 90%, emergency at 95%
+    // Auto-compact can be disabled via settings (requires restart)
+    const autoCompact = isAutoCompactEnabled();
+    const contextManager = new ContextManager({
+        provider,
+        config: {
+            maxContextTokens: getProviderContextLimit(options.provider),
+            // If auto-compact disabled, set threshold to 100% (never triggers)
+            compaction: autoCompact
+                ? DEFAULT_CONTEXT_CONFIG.compaction
+                : {
+                    ...DEFAULT_CONTEXT_CONFIG.compaction,
+                    triggerThreshold: 1.0, // Never auto-trigger
+                    triggerInterval: Number.MAX_SAFE_INTEGER, // Never interval-trigger
+                },
+        },
+    });
+    // Create event handler for verbose mode
+    const onEvent = options.verbose
+        ? (event) => {
+            if (event.type === 'tool_start') {
+                console.log(`\n[Tool: ${event.name}] Starting...`);
+            }
+            else if (event.type === 'tool_end') {
+                console.log(`[Tool: ${event.name}] Done`);
+            }
+        }
+        : undefined;
+    // Build system prompt with optional project context
+    const systemPrompt = options.projectContext
+        ? `${SYSTEM_PROMPT}\n\n---\n\n## Project Context\n\nThe following is project-specific context loaded from COMPILR.md:\n\n${options.projectContext}`
+        : SYSTEM_PROMPT;
+    const agent = new Agent({
+        provider,
+        systemPrompt,
+        maxIterations: options.maxIterations ?? 50,
+        onEvent,
+        contextManager,
+        // Set tool timeout to 2 minutes (default is 30s which is too short for complex operations)
+        // Sub-agents inherit this timeout from the parent agent
+        toolTimeoutMs: 120000,
+        // Enable file tracking for context restoration hints
+        enableFileTracking: true,
+        // Enable permissions if handler is provided
+        permissions: options.onPermissionRequest
+            ? {
+                enabled: true,
+                defaultLevel: 'always', // Allow tools by default, unless specified in rules
+                rules: DEFAULT_PERMISSION_RULES,
+                onPermissionRequest: options.onPermissionRequest,
+            }
+            : undefined,
+        // Iteration limit handler - asks user if they want to continue
+        onIterationLimitReached: options.onIterationLimitReached,
+    });
+    // Register tools using registerTools method
+    const tools = options.minimal
+        ? createMinimalToolRegistry()
+        : createToolRegistry();
+    // Type assertion needed for tool registry compatibility
+    agent.registerTools(tools);
+    // Register Task tool for sub-agent spawning (only in full mode)
+    if (!options.minimal) {
+        const taskTool = createTaskTool({
+            parentAgent: agent,
+            agentTypes: getMergedAgentTypes(),
+            enableEventStreaming: true,
+            defaultTimeout: 120000, // 2 minutes for subagent operations
+            onSpawn: (agentType, description) => {
+                if (options.verbose) {
+                    console.log(`\n[Sub-agent] Spawning ${agentType}: ${description}`);
+                }
+            },
+            onComplete: (agentType, result) => {
+                if (options.verbose) {
+                    console.log(`[Sub-agent] ${agentType} completed (${String(result.iterations)} iterations)`);
+                }
+            },
+        });
+        // Type assertion needed for task tool compatibility
+        agent.registerTool(taskTool);
+        // Register Suggest tool for next action suggestions
+        const suggestTool = createSuggestTool({
+            onSuggest: options.onSuggest,
+        });
+        agent.registerTool(suggestTool);
+    }
+    return agent;
+}

package/dist/agents/registry.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Agent Registry
+ *
+ * Handles loading, saving, and managing agent definitions.
+ * Loads from both project (.compilr-dev/agents/) and user (~/.compilr-dev/agents/) directories.
+ */
+import { AgentDefinition, AgentModel } from './types.js';
+export declare class AgentRegistry {
+    private readonly projectDir;
+    private readonly userDir;
+    private customAgents;
+    constructor(projectRoot?: string);
+    /**
+     * Load all custom agents from project and user directories
+     */
+    load(): void;
+    /**
+     * Get all built-in agents
+     */
+    getBuiltinAgents(): AgentDefinition[];
+    /**
+     * Get all custom agents
+     */
+    getCustomAgents(): AgentDefinition[];
+    /**
+     * Get all agents (built-in + custom)
+     */
+    getAllAgents(): AgentDefinition[];
+    /**
+     * Get an agent by name
+     */
+    getAgent(name: string): AgentDefinition | undefined;
+    /**
+     * Check if an agent name exists
+     */
+    hasAgent(name: string): boolean;
+    /**
+     * Save a new custom agent
+     */
+    saveAgent(agent: {
+        name: string;
+        description: string;
+        model: AgentModel;
+        systemPrompt: string;
+    }, location: 'project' | 'personal'): string;
+    /**
+     * Delete a custom agent
+     */
+    deleteAgent(name: string): boolean;
+    /**
+     * Get the project agents directory
+     */
+    getProjectDir(): string;
+    /**
+     * Get the user agents directory
+     */
+    getUserDir(): string;
+}
+/**
+ * Get the global agent registry instance
+ */
+export declare function getAgentRegistry(): AgentRegistry;
+/**
+ * Reset the registry (for testing)
+ */
+export declare function resetAgentRegistry(): void;