nova-terminal-assistant 0.1.0

package/README.md

@@ -0,0 +1,358 @@
+# Nova CLI
+
+> Next-generation CLI agent framework — more efficient, more multimodal, more intelligent.
+
+[![npm version](https://img.shields.io/npm/v/@nova-cli/cli.svg)](https://www.npmjs.com/package/@nova-cli/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Nova CLI is a production-grade terminal AI agent that combines the best ideas from Claude Code, iFlow CLI, and other tools into a unified, extensible framework. It provides a complete conversation loop with tool use, multi-provider LLM support, MCP integration, and a security-first architecture.
+
+## 快速安装
+
+### 1. 安装 Node.js
+
+访问 [https://nodejs.org/zh-cn/download](https://nodejs.org/zh-cn/download) 下载最新的 Node.js 安装程序。
+
+### 2. 运行安装程序
+
+按照安装向导完成 Node.js 的安装。
+
+### 3. 重启终端
+
+- **Windows**: CMD（按 `Win + R`，输入 `cmd`）或 PowerShell
+- **macOS/Linux**: 打开新的终端窗口
+
+### 4. 安装 Nova CLI
+
+```bash
+npm install -g @nova-cli/cli@latest
+```
+
+### 5. 启动 Nova CLI
+
+```bash
+nova
+```
+
+## 配置 API Key
+
+```bash
+# 配置 Anthropic Claude
+nova auth set anthropic
+
+# 配置 OpenAI
+nova auth set openai
+
+# 查看认证状态
+nova auth status
+```
+
+### 使用本地模型（Ollama）
+
+如果你安装了 Ollama，Nova CLI 会自动检测本地模型：
+
+```bash
+# 查看本地模型
+nova ollama list
+
+# 使用本地模型启动
+nova -m llama3.2
+```
+
+详细安装指南请参阅 [INSTALLATION.md](./INSTALLATION.md)。
+
+## Architecture Overview
+
+```
+nova-cli/
+├── packages/
+│   ├── core/                    # @nova-cli/core - Engine library
+│   │   └── src/
+│   │       ├── types/           # Branded types, session, tools, config, errors
+│   │       ├── tools/           # ToolRegistry, JSON schemas, 11 built-in tools
+│   │       ├── model/           # Unified LLM client + Anthropic/OpenAI providers
+│   │       ├── session/         # SessionManager + AgentLoop (execution engine)
+│   │       ├── context/         # MemoryDiscovery + ContextBuilder + compression
+│   │       ├── security/        # ApprovalManager + HookExecutor + FileFilter
+│   │       ├── mcp/             # Model Context Protocol server management
+│   │       ├── config/          # ConfigManager (YAML/JSON/env layered config)
+│   │       ├── auth/            # Credential management (file + env vars)
+│   │       ├── telemetry/       # Anonymous usage tracking
+│   │       └── utils/           # Logger, helpers (retry, format, debounce)
+│   └── cli/                     # @nova-cli/cli - Terminal interface
+│       └── src/
+│           ├── bin/nova.js      # Entry point
+│           └── startup/         # NovaApp, InteractiveRepl, CLI argument parser
+├── extensions/                  # Skills and agents
+├── __tests__/                   # Unit and integration tests
+└── scripts/                     # Build and utility scripts
+```
+
+## Key Features
+
+### Multi-Provider LLM Support
+- **Anthropic** — Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku (streaming, tools, vision)
+- **OpenAI** — GPT-4o, GPT-4o Mini, GPT-4 Turbo (streaming, function calling)
+- Unified `ModelClient` interface — swap providers without code changes
+- Automatic message format conversion between Anthropic and OpenAI formats
+
+### 11 Built-in Tools
+
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **File** | `read_file`, `write_file`, `edit_file`, `list_directory` | File operations with offset/limit, occurrence-safe editing, recursive listing |
+| **Search** | `search_file`, `search_content` | Glob-based file search, ripgrep-powered content search with context lines |
+| **Execution** | `execute_command` | Shell command execution with PowerShell/bash auto-detection, timeout, abort |
+| **Web** | `web_search`, `web_fetch` | Serper.dev API search, URL fetching with HTML-to-text conversion |
+| **Memory** | `memory_read`, `memory_write` | Key-value store with session/project/global scopes and TTL |
+
+### Agent Execution Loop
+The `AgentLoop` is the heart of Nova CLI — a multi-turn conversation loop that:
+1. Sends messages to the LLM with tool definitions
+2. Processes tool use responses from the model
+3. Executes tools through the `ToolRegistry` (with approval checks)
+4. Feeds tool results back to the model
+5. Repeats until the model stops calling tools or max turns reached
+
+Supports both **blocking** (`run()`) and **streaming** (`runStream()`) modes.
+
+### Approval System
+Five approval modes for different use cases:
+
+| Mode | Behavior |
+|------|----------|
+| `yolo` | Auto-approve everything (dangerous but fast) |
+| `default` | Ask for high/critical risk tools only |
+| `accepting_edits` | Auto-approve file edits, ask for the rest |
+| `plan` | Always ask before any tool execution |
+| `smart` | AI-assisted approval decisions |
+
+Custom approval rules with glob patterns and input field conditions.
+
+### MCP (Model Context Protocol) Integration
+- Connect to external MCP servers via stdio JSON-RPC
+- Automatically discover and register MCP tools
+- Each MCP server's tools become native Nova tools
+
+### Security
+- **FileFilter**: Path-based access control, ignore patterns, size limits
+- **HookExecutor**: Lifecycle hooks (PreToolUse, PostToolUse, SessionStart, etc.)
+- **ApprovalManager**: Risk-based approval workflow
+- Credential files stored with `chmod 600` permissions
+
+### Context & Memory System
+- **MemoryDiscovery**: Auto-discovers project context files (CLAUDE.md, .cursor/rules, ARCHITECTURE.md, etc.)
+- **ContextBuilder**: Builds optimized system prompts from discovered memory
+- **Context Compression**: Automatic conversation truncation when approaching token limits
+
+## Getting Started
+
+### Prerequisites
+- Node.js >= 18.0.0
+- npm (or pnpm >= 9.0.0)
+- An Anthropic or OpenAI API key
+
+### Installation
+
+```bash
+# Clone and install
+git clone <your-repo>
+cd nova-cli
+npm install --workspaces=false
+
+# Install core dependencies
+cd packages/core && npm install
+
+# Install CLI dependencies
+cd ../cli && npm install
+
+# Build core first
+cd ../core && npx tsc -p tsconfig.json
+
+# Build CLI (includes core source for local references)
+cd ../cli && npx tsc -p tsconfig.json
+
+# Or use the build script (requires pnpm)
+cd ../.. && pnpm install && pnpm build
+```
+
+### Configuration
+
+Set your API key:
+
+```bash
+# Via CLI
+nova auth set anthropic
+# Enter your API key when prompted
+
+# Or via environment variable
+export ANTHROPIC_API_KEY=sk-ant-...
+export OPENAI_API_KEY=sk-...
+```
+
+Create a config file at `~/.nova/config.yaml`:
+
+```yaml
+core:
+  defaultModel: claude-3-sonnet-20240229
+  defaultApprovalMode: default
+  maxTurns: 100
+  maxTokens: 4096
+  temperature: 0.7
+  logLevel: info
+```
+
+Project-level config at `.nova/config.yaml` overrides global settings.
+
+### Usage
+
+```bash
+# Start interactive session
+nova
+
+# Single prompt
+nova -p "Explain this codebase"
+
+# Use a specific model
+nova -m gpt-4o
+
+# YOLO mode (auto-approve all tools)
+nova --approval-mode yolo
+
+# Set working directory
+nova -d /path/to/project
+
+# Show current config
+nova config show
+```
+
+### Interactive Commands
+
+Inside the REPL:
+
+```
+/help              Show all commands
+/quit              Exit
+/clear             Clear conversation
+/model <name>      Switch model
+/approval <mode>   Change approval mode
+/tools             List available tools
+/sessions          Show session stats
+/compact           Compress context
+/reset             Start new session
+```
+
+## Development
+
+### Project Structure (Monorepo)
+
+```
+nova-cli/                 # pnpm workspace + Turborepo
+├── packages/core/        # @nova-cli/core — reusable engine library
+├── packages/cli/         # @nova-cli/cli — terminal application
+├── extensions/           # Pluggable skills and agents
+└── __tests__/            # Test suites
+```
+
+### Building
+
+```bash
+pnpm build           # Build all packages
+pnpm dev             # Watch mode
+pnpm test            # Run tests
+pnpm lint            # Lint
+pnpm typecheck       # Type check
+```
+
+### Adding a New Tool
+
+1. Create a JSON schema in `packages/core/src/tools/schemas/my-tool.ts`
+2. Export from `packages/core/src/tools/schemas/index.ts`
+3. Create a handler in `packages/core/src/tools/impl/MyTool.ts`
+4. Register in `NovaApp.ts`:
+
+```typescript
+this.toolRegistry.register({
+  name: 'my_tool',
+  description: 'What this tool does',
+  category: 'file',
+  inputSchema: myToolSchema,
+  requiresApproval: false,
+  riskLevel: 'low',
+}, myToolHandler);
+```
+
+### Adding a New Model Provider
+
+1. Create `packages/core/src/model/providers/MyProvider.ts`
+2. Implement the `ModelProvider` interface
+3. Add to `ModelClient.ts` constructor switch
+4. Register models in `ConfigManager.ts` default config
+
+### Type System
+
+Nova CLI uses **branded TypeScript types** for compile-time safety:
+
+```typescript
+type SessionId = string & { readonly __brand: 'SessionId' };
+type MessageId = string & { readonly __brand: 'MessageId' };
+type ToolCallId = string & { readonly __brand: 'ToolCallId' };
+```
+
+### Error Handling
+
+Hierarchical error classes:
+
+```
+NovaError (base)
+├── ConfigError
+├── ModelError
+│   └── RateLimitError (retryable)
+├── ToolError
+│   └── ToolValidationError
+├── SessionError
+├── ApprovalError
+├── HookError
+├── McpError
+├── SecurityError
+├── ContextOverflowError
+├── CancelledError
+├── TimeoutError
+└── AggregateError
+```
+
+## Design Decisions
+
+### Why Monorepo?
+Separation between `core` (library) and `cli` (application) allows:
+- Reusing the engine in other projects (IDE plugins, web UIs)
+- Independent versioning and testing
+- Clean dependency boundaries
+
+### Why Custom Tool System Instead of Raw MCP?
+- Built-in tools work without external server dependencies
+- Fine-grained approval control per tool
+- Consistent error handling and streaming
+- MCP tools are wrapped and exposed through the same registry
+
+### Why Both Blocking and Streaming?
+- Blocking mode (`run()`): simpler, good for scripts and testing
+- Streaming mode (`runStream()`): better UX for interactive sessions
+
+## Comparison with Alternatives
+
+| Feature | Nova CLI | Claude Code | iFlow CLI |
+|---------|----------|-------------|-----------|
+| Multi-provider | Anthropic + OpenAI | Anthropic only | Multiple |
+| Tool approval modes | 5 modes | 2 modes | 2 modes |
+| MCP integration | Yes | Yes | Yes |
+| Custom hooks | Shell-based | Limited | Limited |
+| Context compression | Auto | Auto | Auto |
+| Memory system | 3 scopes | Session only | File-based |
+| Streaming | Yes | Yes | Yes |
+| Extensible | Yes (extensions) | No | Limited |
+| Open source | Yes | No | Yes |
+
+## License
+
+MIT

package/bin/nova

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+// Nova CLI Entry Point - Cross-platform launcher
+// Automatically uses tsx if available, falls back to direct node if compiled
+
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const mainScript = join(__dirname, 'nova.js');
+
+// Check if running from compiled dist
+const isCompiled = !existsSync(join(__dirname, '../src'));
+
+if (isCompiled) {
+  // Running compiled version
+  import(mainScript).catch((err) => {
+    console.error('Fatal error:', err.message);
+    process.exit(1);
+  });
+} else {
+  // Running from source, need tsx
+  const tsxPath = join(__dirname, '../node_modules/.bin/tsx');
+  const tsxCmd = existsSync(tsxPath + '.cmd') ? tsxPath + '.cmd' : tsxPath;
+  
+  const child = spawn(tsxCmd, [mainScript, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+  });
+  
+  child.on('exit', (code) => {
+    process.exit(code ?? 0);
+  });
+}

package/bin/nova.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+// Nova CLI Entry Point
+// Uses tsx to run TypeScript directly (handles ESM + cross-package imports)
+
+import { NovaApp } from '../src/startup/NovaApp.ts';
+
+const app = new NovaApp();
+app.run().catch((err) => {
+  console.error('Fatal error:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "nova-terminal-assistant",
+  "version": "0.1.0",
+  "description": "Nova CLI - Next-generation AI-powered terminal assistant",
+  "type": "module",
+  "bin": {
+    "nova": "./bin/nova.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "keywords": [
+    "ai",
+    "cli",
+    "assistant",
+    "code",
+    "terminal",
+    "llm",
+    "anthropic",
+    "openai",
+    "ollama"
+  ],
+  "author": "Nova CLI Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nova-cli/nova-cli"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.25.0",
+    "@inquirer/prompts": "^5.3.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "diff": "^5.2.0",
+    "glob": "^10.3.0",
+    "ignore": "^5.3.0",
+    "ink": "^4.4.1",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^5.0.1",
+    "json-schema": "^0.4.0",
+    "mime-types": "^2.1.35",
+    "open": "^10.1.0",
+    "openai": "^4.28.0",
+    "p-limit": "^4.0.0",
+    "react": "^18.2.0",
+    "semver": "^7.6.0",
+    "uuid": "^9.0.0",
+    "yaml": "^2.4.0",
+    "yargs": "^17.7.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@types/react": "^18.2.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "tsx": ">=4.0.0"
+  }
+}