@nuvin/nuvin-cli 2.0.0-rc.14 → 2.0.0-rc.16

package/README.md

@@ -1,186 +1,244 @@
 # @nuvin/nuvin-cli
 
-Interactive AI coding assistant for the terminal.
-Your terminal, your choice of model, your rules—nothing hidden.
+A full-featured terminal UI (TUI) coding assistant built with **React** and **Ink**. It provides an interactive, streaming chat interface in your terminal that connects to LLM providers (Anthropic, OpenAI-compatible) and gives the assistant a suite of workspace tools — file reading/writing, search, shell execution, and more — with a human-in-the-loop approval system for safety-critical operations.
 
-## Features
-
-**Provider Freedom** — Use any LLM provider without lock-in. Supports OpenRouter, Anthropic, GitHub Models, DeepInfra, ZAI, Moonshot, Kimi, MiniMax out of the box. Switch models mid-conversation.
+---
 
-**Multi-Agent Delegation** — Spawn specialist agents for focused tasks like security audits or code investigation. Each agent runs in isolated context with session resumption support.
+## Features
 
-**Native Code Intelligence** — Built-in LSP integration for go-to-definition, find references, hover information, and real-time diagnostics. Understand your codebase, not just pattern match.
+- **Interactive Terminal UI** — Full-screen TUI with virtualized message list, scrolling, keyboard navigation, and alt-screen buffer support.
+- **Streaming Responses** — Real-time streaming of assistant text, reasoning, and tool output as they arrive.
+- **Workspace Tools** — Built-in tools for file inspection (`FileRead`, `Ls`, `Glob`, `Grep`), file editing (`FileEdit`, `FileNew`), and shell execution (`Bash`).
+- **Human-in-the-Loop Approvals** — Tool calls that modify state (e.g., `Bash`, `FileEdit`, `FileNew`) require explicit user approval before execution. Read-only tools (`FileRead`, `Ls`, `Glob`, `Grep`) are auto-approved.
+- **Delegated Agents** — Pluggable agent delegation system (`AssignTask`) for spawning specialist sub-agents (code review, debugging, planning, etc.) with nested message rendering.
+- **Rich Markdown Rendering** — Terminal-optimized markdown with syntax highlighting, table rendering, emoji support, and configurable text reflow.
+- **Theming Engine** — Adaptive light/dark theme with automatic terminal color-depth detection, background fills, dim variants for modals, and full customization via config/env variables.
+- **Diff View** — Inline file-diff rendering for `FileEdit` tool calls showing additions, removals, and context lines with color-coded highlighting.
+- **Customizable Chat Model** — Configurable LLM provider with support for Anthropic Messages API, OpenAI-compatible endpoints, bearer/API-key auth schemes, and reasoning effort settings.
 
-**Modern TUI** — React/Ink-based terminal interface with vim mode, virtualized rendering for large outputs, and session statistics.
+---
 
-**Configuration Profiles** — Maintain separate configurations for different projects, teams, or workflows. Layer global, workspace, and CLI settings.
+## Architecture
 
-**MCP Extensibility** — Extend capabilities with Model Context Protocol servers. Add custom tools without modifying core code.
+```
+src/
+├── index.ts                          # Entry point — boots the app
+├── root.tsx                          # Main bootstrap: config, model, agent, render
+├── app.tsx                           # Root React component — state, events, approvals
+├── components/
+│   ├── Header.tsx                    # Top bar: brand, cwd, model name, approval mode
+│   ├── Composer.tsx                  # User input field with busy/idle states
+│   ├── MessageList.tsx               # Virtualized scrollable message list
+│   ├── MessageRow.tsx                # Renders a single message (text or tool)
+│   ├── ToolMessageRow.tsx            # Tool-specific message rendering
+│   ├── ApprovalModal.tsx             # Modal for approving/denying tool calls
+│   ├── StatusFooter.tsx              # Footer with hints + live memory usage
+│   ├── Modal.tsx                     # Generic modal overlay component
+│   ├── ChildMessagesContext.tsx       # Context for nested delegation messages
+│   └── tool-renders/                 # Per-tool renderers
+│       ├── BashToolRender.tsx
+│       ├── FileReadToolRender.tsx
+│       ├── FileEditToolRender.tsx
+│       ├── FileNewToolRender.tsx
+│       ├── FileDiffView.tsx          # Inline diff display
+│       ├── GlobToolRender.tsx
+│       ├── GrepToolRender.tsx
+│       ├── LsToolRender.tsx
+│       ├── AssignTaskToolRender.tsx
+│       ├── UnknownToolRender.tsx
+│       └── ...
+└── lib/
+    ├── agent-channel.ts              # Event bridge between Agent and React UI
+    ├── approvals/
+    │   └── queue.ts                  # Approval queue with FIFO processing
+    ├── chat/
+    │   └── model.ts                  # Chat model factory (provider config, auth)
+    ├── diagnostics/
+    │   └── memory.ts                 # Memory tracking & diagnostics
+    ├── markdown/                     # Markdown → terminal rendering pipeline
+    │   ├── cache.ts
+    │   ├── provider.ts               # Cached Marked instance management
+    │   ├── render.ts
+    │   └── renderers/
+    │       ├── terminal-renderer.ts
+    │       ├── code-highlighter.ts
+    │       ├── table-renderer.ts
+    │       ├── list-renderer.ts
+    │       ├── text-reflow.ts
+    │       ├── emoji-processor.ts
+    │       └── text-utils.ts
+    ├── messages/
+    │   └── state.ts                  # Immutable message state machine
+    ├── theme/
+    │   ├── runtime.ts                # Theme resolution (light/dark, color depth)
+    │   └── store.ts                  # Zustand theme store with dim support
+    └── tools/
+        └── argsRenderer.ts           # Tool argument formatting for approval UI
+```
 
-**Session Persistence** — Resume previous conversations with full context. Export, browse, and manage conversation history.
+### Key Design Patterns
 
-**Controlled Execution** — Optional sudo mode for manual tool approval. Review and approve file edits, bash commands, and web requests before execution.
+| Pattern | Description |
+|---------|-------------|
+| **Agent Channel** | Decouples the imperative `Agent` (constructed before React mounts) from the UI via an `EventEmitter`-based channel. The agent publishes events and requests tool decisions; `<App />` subscribes and resolves approvals. |
+| **Immutable State** | All message and approval state transitions use pure functions that return new state objects, composed inside React's `setState`. |
+| **Virtualized List** | Only visible messages are rendered (with overscan), using `@nuvin/ink-virtualized-list` for efficient scrolling through long conversations. |
+| **Singleton Theme Store** | A Zustand store (not React Context) holds the resolved theme, enabling both React hook access (`useTheme()`) and vanilla JS snapshots (`getTheme()`). |
+| **Cached Markdown Provider** | `Marked` instances are cached by config key (width, tokens, reflow) to avoid re-creating the parser pipeline on every render frame. |
 
-## Installation
+---
 
-```bash
-# Install globally
-npm install --global @nuvin/nuvin-cli
+## Getting Started
 
-# Use with npx (no installation required)
-npx @nuvin/nuvin-cli
+### Prerequisites
 
-# Install in project as dependency
-npm install @nuvin/nuvin-cli
+- **Node.js** ≥ 22
+- **npm**, **pnpm**, or **yarn** (monorepo workspace setup with `pnpm` recommended)
 
-# Or with pnpm
-pnpm add @nuvin/nuvin-cli
+### Install Dependencies
 
-# Or with yarn
-yarn add @nuvin/nuvin-cli
+```bash
+pnpm install
 ```
 
-## Quick Start
+### Development
 
 ```bash
-# Start with default provider
-nuvin
+# Run in dev mode with hot reload
+pnpm dev
 
-# Use OpenRouter with a free model
-nuvin --provider openrouter --model minimax/minimax-m2:free
+# Run with file watcher
+pnpm dev:watch
+```
 
-# Use Anthropic Claude (requires API key)
-nuvin --provider anthropic --model claude-sonnet-4-5
+### Build
 
-# Use GitHub Models (requires GitHub token)
-nuvin --provider github --model claude-sonnet-4.5
+```bash
+pnpm build
+```
 
-# Use configuration file for persistent settings
-nuvin --config ./my-config.yaml
+Output is written to `dist/`. The CLI entry point is `dist/index.js`.
 
-# List available commands
-nuvin --help
+### Run Tests
 
-# Check version
-nuvin --version
-```
+```bash
+# Run all tests once
+pnpm test
 
-## CLI Usage
+# Run tests in watch mode
+pnpm test:watch
+```
 
-### Basic Commands
+Test files are co-located alongside source files using the `.test.ts` / `.test.tsx` convention, run via [Vitest](https://vitest.dev/).
 
-```bash
-# Start interactive mode with default provider
-nuvin
+---
 
-# Use specific provider and model
-nuvin --provider openrouter --model openai/gpt-4o
+## Configuration
 
-# Use Anthropic Claude
-nuvin --provider anthropic --model claude-sonnet-4-5
+### Config File
 
-# Use GitHub Models
-nuvin --provider github --model claude-sonnet-4.5
+The CLI loads configuration from a `config.yaml` (or the path resolved by `@nuvin/config`). Example:
 
-# Use Echo mode for testing
-nuvin --provider echo --model echo
+```yaml
+database:
+  host: localhost
+  port: 5432
+  name: myapp_db
 
-# Load configuration from file
-nuvin --config ./my-config.yaml
+server:
+  port: 9000
+  timeout: 60
+  debug: true
+  ssl_enabled: true
 
-# Show help and all options
-nuvin --help
+features:
+  - login
+  - signup
+  - profile
+  - dashboard
+  - api_integration
 ```
 
-### Advanced Usage
+### Environment Variables
 
-```bash
-# Combine multiple options
-nuvin --provider openrouter --model openai/gpt-4o --config ./config.yaml
+| Variable | Description |
+|----------|-------------|
+| `API_KEY` | LLM provider API key (fallback if not in config) |
+| `NUVIN_THEME_MODE` | Force `"dark"` or `"light"` theme |
+| `NUVIN_THEME_BACKGROUNDS` | Background fills: `"on"`, `"off"`, or `"auto"` |
+| `NUVIN_MESSAGE_STYLE` | Message styling: `"plain"` or `"tinted"` |
+| `FORCE_COLOR` | Force color level (`0`=none, `1`=16-color, `2`=256-color, `3`=truecolor) |
+| `NO_COLOR` | Disable all colors |
+| `COLORFGBG` | Auto-detect light/dark terminal background |
 
-# Use ZAI provider
-nuvin --provider zai --model glm-4.7
-```
+---
 
-### ACP Server Mode
+## Approval System
 
-Run Nuvin as an ACP server over stdio:
+Tool calls fall into two categories:
 
-```bash
-nuvin --acp
-```
+| Category | Tools | Behavior |
+|----------|-------|----------|
+| **Auto-approved** | `FileRead`, `Ls`, `Glob`, `Grep` | Execute immediately without prompting |
+| **Requires approval** | `Bash`, `FileEdit`, `FileNew`, `AssignTask` | Pauses for user decision |
 
-Notes: Uses the same config resolution as the CLI. File system and terminal actions use local Nuvin tools (no ACP fs/terminal proxy in the initial implementation).
+When a tool requires approval, the **Approval Modal** appears with:
 
-## Environment Variables
+- **Tool name & parameters** — scrollable argument display
+- **Yes** (1) — approve this call
+- **No** (2) — deny this call
+- **Yes, for this session** (3) — auto-approve this tool for the rest of the session
+- **Comment input** (4) — submit a change request / denial reason
 
-Set up authentication via environment variables:
+Navigate with `Tab`, confirm with `Enter`, dismiss with `Escape`.
 
-```bash
-# AI Provider Authentication
-export OPENROUTER_API_KEY=sk-or-xxxxxxxx
-export ANTHROPIC_API_KEY=sk-ant-xxxxxxxx
-export GITHUB_ACCESS_TOKEN=ghp_xxxxxxxxxxxx
-
-# Optional Tool Configuration
-export GOOGLE_CSE_KEY=your_google_cse_key
-export GOOGLE_CSE_CX=your_search_engine_id
-```
+---
+
+## Theming
 
-## What You Can Do
+The theme system automatically adapts to your terminal:
 
-### Development & Code Analysis
-- "Analyze my project structure and provide optimization recommendations"
-- "Review the recent git commits and summarize changes"
-- "Find all TODO comments in my codebase"
-- "Set up automated testing for my codebase"
-- "Refactor this function to follow SOLID principles"
+1. **Mode** — Detects light vs. dark background via `COLORFGBG` or `NUVIN_THEME_MODE`
+2. **Color Level** — Reads `FORCE_COLOR` / `NO_COLOR` or probes `stdout.getColorDepth()`
+3. **Backgrounds** — Enables colored surface fills only when truecolor/256-color is available (off by default in light mode)
+4. **Dim Variant** — When a modal opens, all background colors blend toward a neutral target so the overlay stands out
 
-### Multi-Agent Delegation
-- "Delegate code review to the specialist agent"
-- "Create a comprehensive test suite for this module"
-- "Research documentation for this API and create usage examples"
-- "Organize my git changes into conventional commits"
-- "Have the architect review this design and suggest improvements"
+The theme is accessible via `useTheme()` in React components or `getTheme()` in vanilla code.
 
-## Documentation
+---
 
-- **[Configuration Guide](docs/configuration.md)** - Detailed configuration system documentation
-- **[Commands Reference](docs/commands.md)** - Built-in commands and usage examples
-- **[MCP Integration](docs/mcp-integration.md)** - Model Context Protocol setup and usage
-- **[Specialist Agents](docs/agents.md)** - Multi-agent system and delegation guide
-- **[Development Guide](docs/development.md)** - Contributing and development workflow
-- **[Tool Approval Renderers](docs/tool-approval-renderers.md)** - Tool approval system and custom renderers
+## Delegated Agents
 
-## Troubleshooting
+The CLI supports a pluggable agent delegation system. Agent definitions are discovered from configured directories and can be enabled/disabled per profile. When enabled, the coordinator agent can delegate subtasks to specialists:
 
-### Common Issues
+- **Code Reviewer** — Reviews code for quality, bugs, and best practices
+- **React Senior Dev** — Expert React/TypeScript/CSS implementation
+- **News Collector** — Gathers current news and updates
+- **GSD Agents** — Planning, execution, verification, debugging workflows
 
-**Installation problems**
-- Ensure Node.js 18+ is installed: `node --version`
-- Clear npm cache: `npm cache clean --force`
-- Use specific version: `npm install -g @nuvin/nuvin-cli@latest`
+Delegated agents run with their own tool set and publish events back through the `AgentChannel`, rendered as nested messages under the parent `AssignTask` tool call.
 
-**Provider authentication issues**
-- Check API keys are set correctly as environment variables
-- Verify keys have proper permissions for the provider
-- Test with free models first before upgrading
+---
 
-**Configuration file issues**
-- Validate YAML syntax (use online validator)
-- Check file paths are correct
-- Use absolute paths if relative paths fail
+## Key Dependencies
 
-**Performance issues**
-- Close other memory-intensive applications
-- Increase Node.js memory limit: `node --max-old-space-size=4096`
-- Use lighter models for faster responses
+| Package | Purpose |
+|---------|---------|
+| `@nuvin/nuvin-core` | Agent runtime, tool definitions, chat model abstractions |
+| `@nuvin/config` | Configuration management, profiles, env loading |
+| `@nuvin/ink` | React-based terminal rendering (fork of Ink) |
+| `@nuvin/ink-input` | Keyboard input handling |
+| `@nuvin/ink-text-input` | Text input component |
+| `@nuvin/ink-virtualized-list` | Virtualized scrolling list |
+| `react` / `react-dom` | UI framework |
+| `zustand` | Lightweight state management (theme store) |
+| `marked` | Markdown parsing |
+| `chalk` | Terminal color utilities |
+| `cli-highlight` | Syntax highlighting |
+| `vitest` | Test framework |
 
-**Getting help**
-- Run `nuvin --help` for command options
-- Check [GitHub Issues](https://github.com/marschhuynh/nuvin-cli/issues) for known problems
-- Enable debug mode (if available) for detailed logs
+---
 
 ## License
 
-Apache-2.0 © Marsch Huynh
+Private — All rights reserved.