erosolar-cli 1.2.6 → 1.3.0

package/README.md

@@ -2,127 +2,478 @@
 
 A unified AI agent framework for the command line. Multi-provider support with schema-driven tools, code intelligence, and transparent reasoning.
 
+[![npm version](https://img.shields.io/npm/v/erosolar-cli.svg)](https://www.npmjs.com/package/erosolar-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/erosolar-cli.svg)](https://nodejs.org)
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Supported Providers](#supported-providers)
+- [Core Concepts](#core-concepts)
+- [Usage Guide](#usage-guide)
+- [Commands Reference](#commands-reference)
+- [Tool Capabilities](#tool-capabilities)
+- [Schema Architecture](#schema-architecture)
+- [Configuration](#configuration)
+- [Development](#development)
+
+---
+
 ## Installation
 
 ```bash
 npm install -g erosolar-cli
 ```
 
-Requires Node.js 20+
+**Requirements:** Node.js 20+
+
+**Verify installation:**
+
+```bash
+erosolar-cli --version
+```
+
+---
 
 ## Quick Start
 
 ```bash
+# Start interactive session
 erosolar-cli
+
+# Or use the short alias
+erosolar
 ```
 
-On first run, you'll be prompted to select a provider and configure your API key.
+On first run, you'll see available providers based on your configured API keys:
 
-## Supported Providers
+```
+✓ Providers: anthropic (claude-sonnet-4-5) | openai (gpt-4o) | deepseek (deepseek-reasoner)
+ℹ Add: google: set GOOGLE_API_KEY, xai: set XAI_API_KEY
+```
+
+### Basic Workflow
+
+1. **Ask a question or give a task** in natural language
+2. **Watch the agent work** - see tool calls, reasoning, and results in real-time
+3. **Iterate** - refine your request based on results
+
+```
+> find all TODO comments in the codebase
+
+⏺ I'll search for TODO comments across the codebase.
+
+⏺ Grep(pattern: "TODO", output_mode: "content")
+⎿ Found 23 matches in 8 files
+
+Here are the TODO comments I found:
+- src/api/handler.ts:45 - TODO: Add rate limiting
+- src/utils/cache.ts:12 - TODO: Implement TTL expiration
+...
+```
+
+---
 
-- **Anthropic** (Claude models)
-- **OpenAI** (GPT-4, GPT-4o)
-- **Google** (Gemini)
-- **DeepSeek** (deepseek-reasoner, deepseek-chat)
-- **xAI** (Grok)
-- **Ollama** (local models)
+## Supported Providers
 
-Set your API key via environment variable:
+| Provider | Models | Environment Variable |
+|----------|--------|---------------------|
+| **Anthropic** | Claude Opus, Sonnet, Haiku | `ANTHROPIC_API_KEY` |
+| **OpenAI** | GPT-4o, GPT-4, o1, o1-mini | `OPENAI_API_KEY` |
+| **Google** | Gemini 2.0 Flash, 1.5 Pro | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |
+| **DeepSeek** | deepseek-reasoner, deepseek-chat | `DEEPSEEK_API_KEY` |
+| **xAI** | Grok-2, Grok-beta | `XAI_API_KEY` |
+| **Ollama** | Llama, Qwen, Mistral (local) | `OLLAMA_BASE_URL` (optional) |
+| **Mistral** | Mistral Large, Codestral | `MISTRAL_API_KEY` |
+| **Groq** | Llama 3.1, Mixtral (fast) | `GROQ_API_KEY` |
+| **Together** | Various open models | `TOGETHER_API_KEY` |
+| **Fireworks** | Various open models | `FIREWORKS_API_KEY` |
+
+### Setting Up API Keys
 
 ```bash
-export ANTHROPIC_API_KEY=your-key
-export OPENAI_API_KEY=your-key
-export GOOGLE_API_KEY=your-key
-export DEEPSEEK_API_KEY=your-key
-export XAI_API_KEY=your-key
+# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
+export ANTHROPIC_API_KEY="sk-ant-..."
+export OPENAI_API_KEY="sk-..."
+export DEEPSEEK_API_KEY="sk-..."
 ```
 
-## Features
+### Switching Providers
+
+```bash
+# In the CLI
+/provider anthropic     # Switch to Anthropic
+/provider deepseek      # Switch to DeepSeek
+/providers              # List all configured providers
+```
 
-### Multi-Provider Architecture
+---
 
-Switch between AI providers seamlessly. Each provider uses a unified schema so tools work identically regardless of backend.
+## Core Concepts
 
 ### Transparent Reasoning
 
-See the agent's thought process in real-time:
+Every action is visible. The agent narrates its thought process and shows tool execution in real-time:
+
+```
+⏺ I'll analyze the authentication module for security issues.
+
+⏺ Read(src/auth/login.ts)
+⎿ Read 156 lines
+
+⏺ Grep(pattern: "password.*=", type: "ts")
+⎿ Found 3 matches
 
+Based on my analysis, I found a potential issue at line 42...
 ```
-⏺ I'll analyze the codebase to find the bug.
 
-⏺ Read(src/api/handler.ts)
-⎿ Read 340 lines
+### Schema-Driven Tools
 
-⏺ Grep(pattern: "validateInput", output_mode: "content")
-⎿ Found 8 lines
+All tools are defined in JSON schemas, making them:
+- **Provider-agnostic**: Same tools work across all LLM providers
+- **Self-documenting**: Schemas describe parameters and types
+- **Extensible**: Add custom tools via plugins or MCP servers
 
-Based on my analysis, the issue is...
+### Context Management
+
+The CLI tracks token usage and manages context efficiently:
+
+```
+• Context 45% used (52.3k tokens) • Ready for prompts
+```
+
+- **Green** (<70%): Plenty of room
+- **Yellow** (70-90%): Getting full
+- **Red** (>90%): Approaching limit, consider `/clear`
+
+### Session Persistence
+
+Sessions auto-save and restore. Use `/sessions` to manage:
+
+```bash
+/sessions list          # Show saved sessions
+/sessions load <name>   # Load a session
+/sessions save <name>   # Save current session
 ```
 
-### Built-in Tools
+---
+
+## Usage Guide
 
-**Filesystem**: `read_file`, `write_file`, `list_files`, `search_files`
+### Natural Language Tasks
 
-**Search**: `grep_search`, `find_definition`, glob patterns
+Just describe what you want:
 
-**Bash**: Execute commands in a sandboxed environment
+```
+> refactor the UserService class to use dependency injection
+> write tests for the authentication module
+> find and fix the memory leak in the event handler
+> explain how the caching system works
+```
+
+### File Operations
 
-**Code Analysis**: Structure analysis, dependency mapping, complexity metrics
+```
+> read src/config.ts
+> create a new utility file for date formatting
+> rename all instances of 'userId' to 'accountId' in the api folder
+```
 
-**Code Quality**: Lint checks, quality inspection, refactoring hotspots
+### Code Analysis
 
-**Testing**: Test generation, coverage analysis, test runners
+```
+> analyze the complexity of this codebase
+> find all functions with more than 50 lines
+> show the dependency graph for the auth module
+```
 
-**Web**: Fetch URLs, web search (requires API key)
+### Git Operations
 
-**MCP**: Model Context Protocol server integration
+```
+> show recent commits
+> create a commit with a descriptive message
+> what changed in the last PR?
+```
 
-### Context Tracking
+### Multi-Step Tasks
 
-Monitor token usage with color-coded indicators:
+For complex tasks, the agent uses a todo list to track progress:
 
 ```
-• Context 12% used (15.3k tokens) • Ready for prompts (3s)
+> implement user authentication with JWT, tests, and documentation
+
+⏺ Creating task list...
+
+[1. [in_progress] Design JWT authentication flow
+2. [pending] Implement login endpoint
+3. [pending] Implement token refresh
+4. [pending] Add middleware for protected routes
+5. [pending] Write unit tests
+6. [pending] Add API documentation]
 ```
 
-- Green: <70% (plenty of room)
-- Yellow: 70-90% (getting full)
-- Red: >90% (approaching limit)
+---
+
+## Commands Reference
+
+### Provider & Model Commands
+
+| Command | Description |
+|---------|-------------|
+| `/provider <name>` | Switch to a provider (openai, anthropic, etc.) |
+| `/providers` | List all configured providers |
+| `/model` | Interactive model selection menu |
+| `/discover` | Auto-discover models from provider APIs |
+
+### Session Commands
 
-### Streaming Output
+| Command | Description |
+|---------|-------------|
+| `/sessions list` | Show saved sessions |
+| `/sessions save <name>` | Save current session |
+| `/sessions load <name>` | Load a saved session |
+| `/clear` | Clear conversation history |
 
-Responses stream character-by-character for a responsive feel.
+### Tool Commands
 
-### Session Management
+| Command | Description |
+|---------|-------------|
+| `/tools` | Manage enabled tool suites |
+| `/doctor` | Diagnose environment and credentials |
+| `/checks` | Run repo validation (test/build/lint) |
 
-Sessions auto-save and restore. Pick up where you left off.
+### Display Commands
+
+| Command | Description |
+|---------|-------------|
+| `/shortcuts` or `/keys` | Show keyboard shortcuts |
+| `/thinking [mode]` | Set thinking display (concise/balanced/extended) |
+| `/changes` | Show file modifications this session |
+| `/metrics` | Show performance metrics |
+
+### Other Commands
+
+| Command | Description |
+|---------|-------------|
+| `/context` | Refresh workspace context |
+| `/agents` | Switch agent profiles |
+| `/skills` | Load skill bundles |
+| `/local` | Manage local LLM providers |
 
 ### Keyboard Shortcuts
 
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+C` | Cancel current operation |
+| `Ctrl+D` | Exit (when input empty) |
+| `Ctrl+G` | Compose multi-line message |
+| `Ctrl+O` | Expand collapsed output |
+| `Up/Down` | Navigate command history |
+
+---
+
+## Tool Capabilities
+
+### Core Tools
+
+| Tool Suite | Tools | Description |
+|------------|-------|-------------|
+| **Filesystem** | `read_file`, `write_file`, `list_files` | File I/O operations |
+| **Edit** | `edit_file` | Surgical string replacement |
+| **Search** | `grep_search`, `find_definition` | Code and text search |
+| **Glob** | `glob_files` | Pattern-based file matching |
+| **Bash** | `execute_command` | Sandboxed shell execution |
+
+### Analysis Tools
+
+| Tool Suite | Tools | Description |
+|------------|-------|-------------|
+| **Code Analysis** | `analyze_structure`, `dependency_graph` | AST and dependency analysis |
+| **Code Quality** | `lint_check`, `complexity_metrics` | Quality inspection |
+| **Refactoring** | `find_hotspots`, `impact_analysis` | Refactoring assistance |
+| **Testing** | `run_tests`, `coverage_report` | Test execution |
+
+### Integration Tools
+
+| Tool Suite | Tools | Description |
+|------------|-------|-------------|
+| **Web** | `fetch_url`, `web_search` | HTTP and search |
+| **Git** | `git_status`, `git_diff`, `git_commit` | Version control |
+| **MCP** | Dynamic | Model Context Protocol servers |
+| **Agent Spawning** | `spawn_agent` | Sub-agent delegation |
+
+### Task Management
+
+| Tool Suite | Tools | Description |
+|------------|-------|-------------|
+| **Todo** | `todo_write`, `todo_read` | Task tracking |
+| **Planning** | `create_plan`, `update_plan` | Multi-step planning |
+| **Interaction** | `ask_user` | User clarification |
+
+---
+
+## Schema Architecture
+
+Erosolar CLI uses a **unified schema architecture** for configuration, providers, tools, and agent behavior. All schemas are JSON-based and version-controlled.
+
+### Schema Hierarchy
+
 ```
-/shortcuts    Show all keyboard shortcuts
-/keys         Alias for /shortcuts
-ctrl+c        Cancel current operation
-ctrl+d        Exit
-ctrl+g        Compose multi-line messages
-ctrl+o        Expand tool output
+contracts/
+├── unified-schema.json      # Master schema - single source of truth
+├── agent-schemas.json       # Agent and model configurations
+├── tools.schema.json        # Tool capability definitions
+├── agent-profiles.schema.json
+└── schemas/
+    ├── agent.schema.json
+    ├── agent-profile.schema.json
+    ├── agent-rules.schema.json
+    ├── agent-schemas.schema.json
+    └── tool-selection.schema.json
+```
+
+### Unified Schema (unified-schema.json)
+
+The master schema defines all providers, models, and capabilities:
+
+```json
+{
+  "contractVersion": "2.0.0",
+  "providers": [
+    {
+      "id": "anthropic",
+      "label": "Anthropic",
+      "baseUrl": "https://api.anthropic.com",
+      "envVars": { "apiKey": "ANTHROPIC_API_KEY" },
+      "capabilities": ["chat", "reasoning", "tools", "streaming", "vision"],
+      "models": ["claude-opus-4-5-20251101", "claude-sonnet-4-5-20250929"],
+      "defaultModel": "claude-sonnet-4-5-20250929"
+    }
+  ]
+}
 ```
 
+### Provider Schema
+
+Each provider defines:
+
+| Field | Description |
+|-------|-------------|
+| `id` | Unique identifier (e.g., "anthropic") |
+| `baseUrl` | API endpoint |
+| `envVars` | Required environment variables |
+| `capabilities` | Supported features (chat, tools, streaming, vision) |
+| `models` | Available model IDs |
+| `openaiCompatible` | If true, uses OpenAI-compatible API |
+
+### Tool Schema (tools.schema.json)
+
+Tools are organized into capability suites:
+
+```json
+{
+  "options": [
+    {
+      "id": "filesystem",
+      "label": "File operations",
+      "defaultEnabled": true,
+      "category": "core",
+      "scopes": ["filesystem:read", "filesystem:write"],
+      "pluginIds": ["tool.filesystem.local"]
+    }
+  ]
+}
+```
+
+### Agent Rules (agents/*.rules.json)
+
+Agent behavior is controlled by rules:
+
+```json
+{
+  "profile": "erosolar-code",
+  "globalPrinciples": [
+    {
+      "id": "guardrail.snapshot_lock",
+      "summary": "Require workspace snapshot before editing",
+      "severity": "critical"
+    },
+    {
+      "id": "guardrail.tool_transparency",
+      "summary": "Narrate intent before running tools",
+      "severity": "required"
+    }
+  ]
+}
+```
+
+### Type System (src/core/types.ts)
+
+TypeScript types mirror the JSON schemas:
+
+```typescript
+export interface LLMProvider {
+  readonly id: ProviderId;
+  readonly model: string;
+  generate(messages: ConversationMessage[], tools: ProviderToolDefinition[]): Promise<ProviderResponse>;
+  generateStream?(messages: ConversationMessage[], tools: ProviderToolDefinition[]): AsyncIterableIterator<StreamChunk>;
+}
+
+export interface ProviderToolDefinition {
+  name: string;
+  description: string;
+  parameters?: JSONSchemaObject;
+}
+```
+
+### Model Discovery
+
+Models can be statically defined or auto-discovered:
+
+```typescript
+// Discover models from provider APIs
+const result = await discoverAllModels();
+// Returns models from OpenAI, Anthropic, Google, etc.
+
+// Get best model for a provider
+const best = getBestModel('anthropic', models);
+// Returns highest-priority model based on rankings
+```
+
+---
+
 ## Configuration
 
 ### Agent Profiles
 
-Profiles define provider, model, and behavior rules. Default profile uses your selected provider with coding-optimized settings.
+Profiles define provider, model, and behavior. Located in `agents/`:
+
+```json
+{
+  "profile": "erosolar-code",
+  "label": "Erosolar Code",
+  "defaultProvider": "openai",
+  "defaultModel": "gpt-4o",
+  "systemPrompt": "You are an expert coding assistant..."
+}
+```
 
 ### MCP Servers
 
-Add `.mcp.json` or `.erosolar/mcp.json` to your workspace:
+Add Model Context Protocol servers via `.mcp.json` or `.erosolar/mcp.json`:
 
 ```json
 {
   "filesystem": {
     "command": "npx",
     "args": ["-y", "@modelcontextprotocol/server-filesystem", "${WORKSPACE_ROOT}"]
+  },
+  "github": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-github"],
+    "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
   }
 }
 ```
@@ -131,45 +482,172 @@ Add `.mcp.json` or `.erosolar/mcp.json` to your workspace:
 
 Load reusable knowledge bundles from `SKILL.md` files:
 
+```markdown
+<!-- SKILL.md -->
+# React Component Development
+
+## Principles
+- Use functional components with hooks
+- Implement proper error boundaries
+- Follow accessibility guidelines
+
+## Patterns
+```typescript
+const Component: FC<Props> = ({ data }) => {
+  const [state, setState] = useState(initial);
+  // ...
+};
 ```
-/skill plugin-dev:skill-development
 ```
 
-## Headless Mode
+Load with `/skill <name>` or reference in prompts.
 
-Run non-interactively with JSON output:
+### Tool Settings
 
-```bash
-erosolar-cli --json
+Configure which tools are enabled via `/tools` command or `~/.erosolar/tools.json`:
+
+```json
+{
+  "enabled": ["filesystem", "search", "bash", "edit"],
+  "disabled": ["web"]
+}
 ```
 
+---
+
 ## Development
 
+### Setup
+
 ```bash
 git clone https://github.com/ErosolarAI/erosolar-by-bo.git
 cd erosolar-by-bo
 npm install
 npm run build
-npm run dev
 ```
 
-### Scripts
+### Development Mode
+
+```bash
+npm run dev          # Run with ts-node
+npm run build        # Compile TypeScript
+npm run type-check   # Check types only
+```
+
+### Testing
 
 ```bash
-npm run build         # Compile TypeScript
-npm run dev           # Run in development mode
-npm test              # Run tests
-npm run lint          # Run ESLint
-npm run type-check    # TypeScript type checking
-npm run health-check  # Validate core components
-npm run quality-gate  # Run all quality checks
+npm test             # Run test suite
+npm run lint         # Run ESLint
+npm run health-check # Validate core components
+npm run quality-gate # All quality checks
+```
+
+### Project Structure
+
+```
+src/
+├── bin/              # CLI entry point
+├── core/             # Core types, agent, context management
+│   ├── agent.ts
+│   ├── types.ts
+│   ├── modelDiscovery.ts
+│   └── unified/      # Unified schema runtime
+├── providers/        # LLM provider implementations
+│   ├── anthropicProvider.ts
+│   ├── openaiResponsesProvider.ts
+│   └── googleProvider.ts
+├── capabilities/     # Tool implementations
+│   ├── filesystemCapability.ts
+│   ├── searchCapability.ts
+│   └── bashCapability.ts
+├── shell/            # Interactive shell
+│   ├── shellApp.ts
+│   └── interactiveShell.ts
+├── ui/               # Display and theming
+├── plugins/          # Plugin system
+├── contracts/        # JSON schemas
+└── mcp/              # MCP client
+```
+
+### Adding a Provider
+
+1. Create provider in `src/providers/`:
+
+```typescript
+export class CustomProvider implements LLMProvider {
+  readonly id = 'custom';
+  readonly model: string;
+
+  async generate(messages, tools) {
+    // Implementation
+  }
+
+  async *generateStream(messages, tools) {
+    // Streaming implementation
+  }
+}
 ```
 
+2. Register in `src/plugins/providers/`:
+
+```typescript
+registerProvider('custom', (config) => new CustomProvider(config));
+```
+
+3. Add to `unified-schema.json`:
+
+```json
+{
+  "id": "custom",
+  "label": "Custom Provider",
+  "envVars": { "apiKey": "CUSTOM_API_KEY" },
+  "capabilities": ["chat", "tools", "streaming"]
+}
+```
+
+### Adding a Tool
+
+1. Create capability in `src/capabilities/`:
+
+```typescript
+export function createCustomTools(): ProviderToolDefinition[] {
+  return [{
+    name: 'custom_tool',
+    description: 'Does something useful',
+    parameters: {
+      type: 'object',
+      properties: {
+        input: { type: 'string', description: 'Input value' }
+      },
+      required: ['input']
+    }
+  }];
+}
+
+export async function executeCustomTool(args: { input: string }) {
+  // Implementation
+  return { result: 'success' };
+}
+```
+
+2. Register in tool registry
+
+3. Add to `tools.schema.json`
+
+---
+
 ## License
 
 MIT
 
 ## Links
 
+- [npm Package](https://www.npmjs.com/package/erosolar-cli)
 - [GitHub Repository](https://github.com/ErosolarAI/erosolar-by-bo)
 - [Issues](https://github.com/ErosolarAI/erosolar-by-bo/issues)
+
+## Support
+
+- Email: support@ero.solar
+- GitHub Issues for bug reports and feature requests