ros/automaker
1
0
Fork 0
mirror of https://github.com/AutoMaker-Org/automaker.git synced 2026-02-04 09:13:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Add Cursor CLI Integration Analysis document

Browse Source 
- Created a comprehensive analysis document detailing the existing Claude CLI integration architecture and the planned Cursor CLI implementation.
- Document includes sections on current architecture, service integration, UI components, and a thorough examination of Cursor CLI behavior.
- Outlined integration strategy, including types to add, provider implementation, setup flow changes, and UI updates.
- Marked the completion of Phase 0 analysis and documentation tasks.
This commit is contained in:
Shirone
2025-12-28 00:27:43 +01:00
parent 81f35ad6aa
commit 525c4c303f
2 changed files with 410 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

392
docs/cursor-integration-analysis.md Normal file
View File

@@ -0,0 +1,392 @@
# Cursor CLI Integration Analysis
> Phase 0 Analysis Document for AutoMaker Cursor Integration
> Generated: 2025-12-28
## Executive Summary
This document analyzes the existing Claude CLI integration architecture in AutoMaker and documents the Cursor CLI (cursor-agent) behavior to plan a parallel provider implementation.
## 1. Current Architecture Analysis
### 1.1 Provider System (`apps/server/src/providers/`)
#### BaseProvider (`base-provider.ts`)
- Abstract class with core interface for all providers
- Key methods:
- `execute(options)` - Runs the CLI process
- `buildCommand(options)` - Constructs CLI command
- `parseOutput(output)` - Parses CLI response
- `buildSystemPrompt(options)` - Constructs system prompts
- Uses `@automaker/platform.spawnJSONLProcess()` for CLI execution
- Handles abort signals for cancellation
#### ClaudeProvider (`claude-provider.ts`)
- Extends BaseProvider for Claude CLI
- Uses Claude Agent SDK via `@anthropic-ai/claude-code` package
- Key features:
- Thinking levels (none, low, medium, high, ultrathink)
- Model selection (haiku, sonnet, opus)
- System prompt injection
- Session/conversation management
- MCP server support
- SDK options built via `buildSdkOptions()` in `sdk-options.ts`
#### ProviderFactory (`provider-factory.ts`)
- Creates provider instances based on type
- Currently only supports 'claude' provider
- Extension point for adding new providers
#### Types (`types.ts`)
- `ProviderType`: Currently `'claude'`
- `ProviderConfig`: Configuration for providers
- `ExecuteResult`: Standardized result format
### 1.2 Service Integration
#### AgentService (`agent-service.ts`)
- Manages chat agent sessions
- Uses ClaudeProvider for execution
- Handles streaming output to clients
- Session persistence and history
#### AutoModeService (`auto-mode-service.ts`)
- Orchestrates feature generation workflow
- Manages concurrent feature execution
- Uses provider for each feature task
- Handles planning, execution, verification phases
#### SDK Options (`sdk-options.ts`)
- Builds Claude SDK options from settings
- Handles thinking level configuration
- Maps model aliases to full model IDs
- Configures MCP servers
### 1.3 UI Components
#### LogParser (`log-parser.ts`)
- Parses agent output into structured entries
- Detects entry types: tool_call, tool_result, phase, error, success, etc.
- Extracts metadata: tool name, file path, summary
- Claude-specific patterns (🔧 Tool:, etc.)
#### LogViewer (`log-viewer.tsx`)
- Renders parsed log entries
- Collapsible sections
- Filtering by type/category
- Tool-specific icons and colors
### 1.4 Setup Flow
#### Claude Status Detection (`get-claude-status.ts`)
- Checks CLI installation via `which`/`where`
- Searches common installation paths
- Detects authentication via:
- `~/.claude/stats-cache.json` (activity)
- `~/.claude/.credentials.json` (OAuth)
- Environment variables (`ANTHROPIC_API_KEY`)
- Stored API keys in AutoMaker
#### Setup View (`setup-view.tsx`)
- Multi-step wizard: welcome → theme → claude → github → complete
- `ClaudeSetupStep` handles CLI detection and auth
- Skip option for users without Claude
#### HTTP API Client (`http-api-client.ts`)
- Client-side API wrapper
- `setup.getClaudeStatus()` - Get Claude CLI status
- `setup.installClaude()` - Trigger installation
- `setup.authClaude()` - Trigger authentication
### 1.5 Types Package (`@automaker/types`)
#### Model Types (`model.ts`)
```typescript
CLAUDE_MODEL_MAP = {
haiku: 'claude-haiku-4-5-20251001',
sonnet: 'claude-sonnet-4-5-20250929',
opus: 'claude-opus-4-5-20251101',
};
```
#### Settings Types (`settings.ts`)
- `ModelProvider`: Currently `'claude'` only
- `AIProfile`: Provider field for profiles
- `ThinkingLevel`: Reasoning intensity levels
#### Model Display (`model-display.ts`)
- `CLAUDE_MODELS`: UI metadata for model selection
- `getModelDisplayName()`: Human-readable names
## 2. Cursor CLI Behavior Analysis
### 2.1 Installation & Location
- **Binary**: `cursor-agent`
- **Installed at**: `~/.local/bin/cursor-agent`
- **Version tested**: `2025.12.17-996666f`
- **Config directory**: `~/.cursor/`
- **Config file**: `~/.cursor/cli-config.json`
### 2.2 Authentication
```bash
# Login command
cursor-agent login
# Status check
cursor-agent status # or `cursor-agent whoami`
# Logout
cursor-agent logout
```
Authentication is browser-based (OAuth) by default. Status output:
```
✓ Logged in as user@example.com
```
### 2.3 CLI Options
| Option | Description |
| -------------------------- | ------------------------------------------- |
| `--print` | Non-interactive mode, outputs to stdout |
| `--output-format <format>` | `text`, `json`, or `stream-json` |
| `--model <model>` | Model selection (e.g., `gpt-5`, `sonnet-4`) |
| `--workspace <path>` | Working directory |
| `--resume [chatId]` | Resume previous session |
| `--api-key <key>` | API key (or `CURSOR_API_KEY` env) |
| `--force` | Auto-approve tool calls |
| `--approve-mcps` | Auto-approve MCP servers |
### 2.4 Output Formats
#### JSON Format (`--output-format json`)
Single JSON object on completion:
```json
{
"type": "result",
"subtype": "success",
"is_error": false,
"duration_ms": 2691,
"result": "Response text here",
"session_id": "uuid",
"request_id": "uuid"
}
```
#### Stream-JSON Format (`--output-format stream-json`)
JSONL (one JSON per line) during execution:
1. **Init event**:
```json
{
"type": "system",
"subtype": "init",
"apiKeySource": "login",
"cwd": "/path",
"session_id": "uuid",
"model": "Composer 1"
}
```
2. **User message**:
```json
{
"type": "user",
"message": { "role": "user", "content": [{ "type": "text", "text": "prompt" }] },
"session_id": "uuid"
}
```
3. **Thinking events**:
```json
{"type":"thinking","subtype":"delta","text":"","session_id":"uuid","timestamp_ms":123}
{"type":"thinking","subtype":"completed","session_id":"uuid","timestamp_ms":123}
```
4. **Assistant response**:
```json
{
"type": "assistant",
"message": { "role": "assistant", "content": [{ "type": "text", "text": "response" }] },
"session_id": "uuid"
}
```
5. **Result**:
```json
{
"type": "result",
"subtype": "success",
"duration_ms": 1825,
"is_error": false,
"result": "response",
"session_id": "uuid"
}
```
### 2.5 Config File Structure
`~/.cursor/cli-config.json`:
```json
{
"permissions": {
"allow": ["Shell(ls)"],
"deny": []
},
"version": 1,
"model": {
"modelId": "composer-1",
"displayModelId": "composer-1",
"displayName": "Composer 1"
},
"approvalMode": "allowlist",
"sandbox": {
"mode": "disabled",
"networkAccess": "allowlist"
}
}
```
### 2.6 Available Models
From `--help`:
- `gpt-5`
- `sonnet-4`
- `sonnet-4-thinking`
- `composer-1` (default)
### 2.7 MCP Support
```bash
cursor-agent mcp list # List configured servers
cursor-agent mcp login <id> # Authenticate with server
cursor-agent mcp list-tools <id> # List tools for server
cursor-agent mcp disable <id> # Remove from approved list
```
## 3. Integration Strategy
### 3.1 Types to Add (`@automaker/types`)
```typescript
// settings.ts
export type ModelProvider = 'claude' | 'cursor';
// model.ts (new: cursor-models.ts)
export type CursorModelId = 'composer-1' | 'gpt-5' | 'sonnet-4' | 'sonnet-4-thinking';
export const CURSOR_MODEL_MAP: Record<string, CursorModelId> = {
composer: 'composer-1',
gpt5: 'gpt-5',
sonnet: 'sonnet-4',
'sonnet-thinking': 'sonnet-4-thinking',
};
```
### 3.2 Provider Implementation
New `CursorProvider` class extending `BaseProvider`:
- Override `buildCommand()` for cursor-agent CLI
- Override `parseOutput()` for Cursor's JSONL format
- Handle stream-json output parsing
- Map thinking events to existing log format
### 3.3 Setup Flow Changes
1. Add `CursorSetupStep` component
2. Add `get-cursor-status.ts` route handler
3. Update setup wizard to detect/choose providers
4. Add Cursor authentication flow
### 3.4 UI Updates
1. Extend `LogParser` for Cursor event types
2. Add Cursor icon (Terminal from lucide-react)
3. Update model selectors for Cursor models
4. Provider toggle in settings
## 4. Key Differences: Claude vs Cursor
| Aspect | Claude CLI | Cursor CLI |
| ---------- | --------------------------- | ----------------------- |
| Binary | `claude` | `cursor-agent` |
| SDK | `@anthropic-ai/claude-code` | Direct CLI spawn |
| Config dir | `~/.claude/` | `~/.cursor/` |
| Auth file | `.credentials.json` | `cli-config.json` |
| Output | SDK events | JSONL stream |
| Thinking | Extended thinking API | `thinking` events |
| Models | haiku/sonnet/opus | composer/gpt-5/sonnet-4 |
| Session | Conversation system | `session_id` in output |
## 5. Files to Create/Modify
### Phase 1: Types
- [ ] `libs/types/src/cursor-models.ts` - Cursor model definitions
- [ ] `libs/types/src/settings.ts` - Update ModelProvider type
- [ ] `libs/types/src/index.ts` - Export new types
### Phase 2: Provider
- [ ] `apps/server/src/providers/cursor-provider.ts` - New provider
- [ ] `apps/server/src/providers/provider-factory.ts` - Add cursor
- [ ] `apps/server/src/providers/types.ts` - Update ProviderType
### Phase 3: Setup
- [ ] `apps/server/src/routes/setup/get-cursor-status.ts` - Detection
- [ ] `apps/server/src/routes/setup/routes/cursor-status.ts` - Route
- [ ] `apps/server/src/routes/setup/index.ts` - Register route
### Phase 4: UI
- [ ] `apps/ui/src/components/views/setup-view/steps/CursorSetupStep.tsx`
- [ ] `apps/ui/src/lib/log-parser.ts` - Cursor event parsing
- [ ] `apps/ui/src/lib/http-api-client.ts` - Add cursor endpoints
## 6. Verification Checklist
- [x] Read all core provider files
- [x] Read service integration files
- [x] Read UI streaming/logging files
- [x] Read setup flow files
- [x] Read types package files
- [x] Document Cursor CLI behavior
- [x] Create this analysis document
## 7. Next Steps
Proceed to **Phase 1: Types & Interfaces** to:
1. Add Cursor model types to `@automaker/types`
2. Update `ModelProvider` type
3. Create cursor model display constants

36
plan/cursor-cli-integration/phases/phase-0-analysis.md
View File

@@ -1,6 +1,6 @@
# Phase 0: Analysis & Documentation # Phase 0: Analysis & Documentation
**Status:** `pending` **Status:** `complete`
**Dependencies:** None **Dependencies:** None
**Estimated Effort:** Research only (no code changes) **Estimated Effort:** Research only (no code changes)
@@ -16,7 +16,7 @@ Understand existing AutoMaker architecture patterns before writing any code. Doc
### Task 0.1: Read Core Provider Files ### Task 0.1: Read Core Provider Files
**Status:** `pending` **Status:** `complete`
Read and understand these files: Read and understand these files:
@@ -37,7 +37,7 @@ cat apps/server/src/providers/claude-provider.ts | head -100
### Task 0.2: Read Service Integration ### Task 0.2: Read Service Integration
**Status:** `pending` **Status:** `complete`
Understand how providers are consumed: Understand how providers are consumed:
@@ -49,7 +49,7 @@ Understand how providers are consumed:
### Task 0.3: Read UI Streaming/Logging ### Task 0.3: Read UI Streaming/Logging
**Status:** `pending` **Status:** `complete`
Understand log parsing and display: Understand log parsing and display:
@@ -60,7 +60,7 @@ Understand log parsing and display:
### Task 0.4: Read Setup Flow ### Task 0.4: Read Setup Flow
**Status:** `pending` **Status:** `complete`
Understand setup wizard patterns: Understand setup wizard patterns:
@@ -72,7 +72,7 @@ Understand setup wizard patterns:
### Task 0.5: Read Types Package ### Task 0.5: Read Types Package
**Status:** `pending` **Status:** `complete`
Understand type definitions: Understand type definitions:
@@ -85,7 +85,7 @@ Understand type definitions:
### Task 0.6: Document Cursor CLI Behavior ### Task 0.6: Document Cursor CLI Behavior
**Status:** `pending` **Status:** `complete`
Test and document Cursor CLI behavior: Test and document Cursor CLI behavior:
@@ -102,10 +102,10 @@ echo "Test prompt" | cursor-agent -p --output-format stream-json --model auto 2>
Document: Document:
- [ ] Exact event sequence for simple prompt - [x] Exact event sequence for simple prompt
- [ ] Error message formats - [x] Error message formats
- [ ] Exit codes for different failure modes - [x] Exit codes for different failure modes
- [ ] How tool calls appear in stream - [x] How tool calls appear in stream
--- ---
@@ -176,13 +176,13 @@ Create `docs/cursor-integration-analysis.md` with findings:
Before marking this phase complete: Before marking this phase complete:
- [ ] All provider files read and understood - [x] All provider files read and understood
- [ ] Service integration patterns documented - [x] Service integration patterns documented
- [ ] Log parser patterns understood - [x] Log parser patterns understood
- [ ] Setup wizard flow mapped - [x] Setup wizard flow mapped
- [ ] Types package structure documented - [x] Types package structure documented
- [ ] Cursor CLI behavior tested (if installed) - [x] Cursor CLI behavior tested (if installed)
- [ ] Analysis document created in `docs/` - [x] Analysis document created in `docs/`
--- ---