rush-ai 0.3.0 → 0.4.0

package/README.md

@@ -1,135 +1,230 @@
+<div align="center">
+
 # rush-ai
 
-Rush CLI — Command-line interface for the Rush AI platform.
+**Command-line interface for the Rush AI platform**
+
+*Create tasks, manage agents, stream results, and integrate IDE plugins — all from the terminal*
+
+[![npm version](https://img.shields.io/npm/v/rush-ai.svg)](https://www.npmjs.com/package/rush-ai)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+</div>
+
+---
 
 ## Quick Start
 
 ```bash
-pnpm --filter rush-ai build
-pnpm --filter rush-ai test
+npm install -g rush-ai
+
+rush-ai auth login
+rush-ai agent list
+rush-ai task create -a <agent> -p "Build a landing page"
+rush-ai task watch <task-id>
 ```
 
-## Testing Strategy
+## Features
+
+- **Task lifecycle** — Create, watch (SSE streaming), cancel, and download artifacts
+- **Agent management** — Browse agents, inspect skills and MCP servers
+- **MCP integration** — Discover MCP servers, list tools, run as MCP stdio server
+- **IDE plugins** — Install, update, diagnose plugins for Claude Code and Cursor
+- **Multi-profile** — Switch between environments (test, production, custom)
+- **Shell completion** — Bash, Zsh, and Fish auto-completion
+- **CI-friendly** — `--json` output, `--ci` mode, non-zero exit codes on failure
 
-rush-ai 采用三层测试策略，在不同阶段用最合适的方式验证代码正确性。
+## Installation
 
-### L1: 单元测试（本地，秒级反馈）
+**Requirements:** Node.js >= 18.0.0
 
-验证 CLI 自身逻辑，完全不依赖外部服务。
+```bash
+npm install -g rush-ai       # Global install
+npx rush-ai <command>        # Or use npx directly
+```
 
-**覆盖范围：**
+## Commands
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `auth login` | - | Log in via browser (PKCE) or API key |
+| `auth status` | - | Show current authentication status |
+| `auth logout` | - | Log out and clear credentials |
+| `agent list` | `agent ls` | List available agents |
+| `agent info <name>` | - | Show agent details, skills, and MCP servers |
+| `task create` | - | Create a task for an agent |
+| `task send <id>` | - | Send a follow-up message to a task |
+| `task status <id>` | - | Check task status |
+| `task result <id>` | - | Get task result and file summary |
+| `task files <id>` | - | List and download task artifacts |
+| `task list` | `task ls` | List tasks |
+| `task watch <id>` | - | Stream task execution in real-time (SSE) |
+| `task cancel <id>` | - | Cancel a running task |
+| `mcp serve` | - | Start MCP stdio server |
+| `mcp list` | `mcp ls` | List available MCP servers |
+| `mcp list-tools <id>` | - | List tools provided by an MCP server |
+| `plugin install <name>` | - | Install an IDE plugin |
+| `plugin update <name>` | - | Update an installed plugin |
+| `plugin uninstall <name>` | - | Remove a plugin |
+| `plugin list` | `plugin ls` | List available and installed plugins |
+| `plugin status <name>` | - | Show plugin installation status |
+| `plugin doctor [name]` | - | Diagnose plugin issues |
+| `config show` | - | Show current configuration |
+| `config set <key> <value>` | - | Set a config value (`api`, `collectMetrics`, `currentTeam`) |
+| `config use <profile>` | - | Switch active profile |
+| `config create <profile>` | - | Create a new profile |
+| `config delete <profile>` | - | Delete a profile |
+| `config list` | `config ls` | List all profiles |
+| `completion install` | - | Auto-install shell completion |
+| `completion bash\|zsh\|fish` | - | Print completion script |
+| `doctor` | - | Run environment, auth, and connectivity diagnostics |
+
+### Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output as JSON (machine-readable) |
+| `--ci` | CI mode: JSON output, no interactive prompts, strict exit codes |
+| `--verbose` | Show detailed output including HTTP requests |
+| `--debug` | Debug-level output (implies `--verbose`) |
+| `--no-color` | Disable color output |
+| `-f, --format <type>` | Output format: `table`, `json`, `csv` |
 
-- 命令解析（commander 参数、flag、子命令路由）
-- 输出格式化（table / `--json` / `--stream`）
-- 配置管理（`~/.rush/` 读写、token 存取）
-- 错误处理（未认证提示、网络错误、API 错误码映射）
-- stdin 管道输入解析
+## Usage
 
-**技术方案：** vitest，mock HTTP 层（`lib/client.ts`），不启动任何服务。
+### Authentication
 
 ```bash
-pnpm --filter rush-ai test
+# Browser login (PKCE flow — opens browser)
+rush-ai auth login
+
+# API key login
+rush-ai auth login --api-key <key>
+
+# Check status
+rush-ai auth status --verify
 ```
 
-### L2: 本地联调测试（本地，秒级反馈）
+### Working with Tasks
 
-CLI 对本地运行的 Agent 服务做真实调用，验证请求/响应链路。
+```bash
+# Create a task
+rush-ai task create -a rush -p "Add a contact form to the homepage"
 
-**前置条件：**
+# Stream output in real-time
+rush-ai task watch <task-id>
 
-- `pnpm dev:agent` 运行在 `localhost:4000`（需 `.env.local` 配好凭证）
-- 或 `pnpm dev` 同时启动 web + agent
+# Get result and download files
+rush-ai task result <task-id>
+rush-ai task files <task-id> --download-all -o ./output
 
-**覆盖范围：**
+# Send follow-up message
+rush-ai task send <task-id> -p "Change the button color to blue"
 
-- auth 认证流程
-- `agent list` / `agent info` 真实返回
-- `task create` + `task status` + `task result` 异步链路
-- SSE 流式输出（`task watch`）
+# Pipe prompt from stdin
+echo "Refactor the auth module" | rush-ai task create -a rush
 
-**技术方案：** vitest e2e 配置，测试前检查 `localhost` health，不可用则 skip。
+# List recent tasks
+rush-ai task list -l 10 -s completed
+```
+
+### Discovering Agents and MCP Servers
 
 ```bash
-# 需要先启动 agent
-pnpm dev:agent &
+# Browse agents
+rush-ai agent list
+rush-ai agent info rush
 
-pnpm --filter rush-ai test:e2e
+# Browse MCP servers and their tools
+rush-ai mcp list --search "database"
+rush-ai mcp list-tools <server-id>
 ```
 
-### L3: 冒烟测试（CI / 手动，分钟级）
-
-对真实环境做最终确认，验证完整 CLI 链路：`auth → agent list → task create → task result → task files → task list`。
+### IDE Plugin Management
 
-**触发时机：**
+```bash
+# Install plugin for Claude Code
+rush-ai plugin install claude-code
 
-- PR 合入后，CI 构建部署完成
-- 手动触发，指定目标环境
+# Check plugin health
+rush-ai plugin doctor claude-code
 
-**覆盖范围：**
+# Update plugin
+rush-ai plugin update claude-code --force
+```
 
-- 核心 happy path 全链路验证
-- 网络 / 鉴权 / 代理等环境相关的集成验证
-- production build 模式下的 API 行为
+### Multi-Profile Configuration
 
 ```bash
-RUSH_API_BASE_URL=https://rush-test.zhenguanyu.com \
-RUSH_AUTH_TOKEN=$CI_TEST_TOKEN \
-pnpm --filter rush-ai test:smoke
+# Create profiles for different environments
+rush-ai config create production --api https://rush.example.com
+rush-ai config create staging --api https://rush-test.example.com
+
+# Switch between profiles
+rush-ai config use production
+rush-ai config list
 ```
 
-## Scripts
+### CI/CD Integration
 
-| Script | Description |
-|--------|-------------|
-| `test` | L1 单元测试 |
-| `test:e2e` | L2 本地联调测试 |
-| `test:smoke` | L3 冒烟测试 |
-| `test:all` | L1 + L2 |
-| `test:watch` | 单元测试 watch 模式 |
-| `typecheck` | TypeScript 类型检查 |
-| `build` | 构建 |
+```bash
+# Non-interactive auth via API key
+RUSH_API_KEY=$KEY rush-ai task create -a rush -p "Run tests" --ci
+
+# Script-friendly JSON output
+rush-ai task status <id> --json | jq '.status'
+
+# Pipe results
+rush-ai task result <id> --json | jq -r '.result'
+```
 
 ## Environment Variables
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `RUSH_API_BASE_URL` | API 目标地址 | `http://localhost:3000` |
-| `RUSH_AUTH_TOKEN` | 认证 token（跳过 CAS 交互登录） | — |
-| `RUSH_TEST_AGENT` | E2E 测试用的 Agent 名称 | `rush` |
+| `RUSH_API_KEY` | API key for non-interactive auth (skips browser login) | - |
+| `RUSH_API_URL` | API base URL override | `https://rush.zhenguanyu.com` |
+| `RUSH_PROFILE` | Override active profile | - |
+| `NO_COLOR` | Disable colored output | - |
+| `DEBUG` | Enable debug logging | - |
 
-## Development Verification Flow
+## Configuration
 
-每完成一个命令实现：
+Config files are stored in `~/.rush/`:
 
-```bash
-pnpm --filter rush-ai typecheck     # 类型检查
-pnpm --filter rush-ai test           # L1 单元测试
-pnpm --filter rush-ai build          # 确保能构建
+```
+~/.rush/
+├── auth.json             # Credentials (token, refresh token, expiry)
+├── config.json           # Global settings (profiles, metrics, team)
+└── plugins/
+    └── installed.json    # Plugin manifest
 ```
 
-涉及 API 交互改动时（需先启动 dev:agent）：
+## Development
 
 ```bash
-pnpm --filter rush-ai test:e2e       # L2 本地联调
-```
+# Install dependencies
+pnpm install
 
-PR 合入后（CI 自动或手动）：
+# Build
+pnpm --filter rush-ai build
 
-```bash
-pnpm --filter rush-ai test:smoke     # L3 部署冒烟
-```
+# Type check
+pnpm --filter rush-ai typecheck
 
-## Project Structure
+# Run unit tests
+pnpm --filter rush-ai test
 
+# Run E2E tests (requires web + agent: pnpm dev)
+pnpm dev &
+pnpm --filter rush-ai test:e2e
+
+# Run smoke tests (against deployed environment)
+RUSH_API_BASE_URL=https://rush-test.zhenguanyu.com \
+RUSH_AUTH_TOKEN=$TOKEN \
+pnpm --filter rush-ai test:smoke
 ```
-packages/rush-ai/
-├── src/
-│   ├── commands/          # CLI commands (agent, auth, mcp, plugin, task)
-│   ├── e2e/               # E2E & smoke test files
-│   ├── output/            # Output formatting (table, json, stream)
-│   └── util/              # Shared utilities (client, config, auth, errors)
-├── vitest.config.ts       # L1 unit test config
-├── vitest.e2e.config.ts   # L2 e2e test config
-├── vitest.smoke.config.ts # L3 smoke test config
-└── package.json
-```
+
+## License
+
+MIT