mirror of
https://github.com/AutoMaker-Org/automaker.git
synced 2026-01-31 06:42:03 +00:00
525c4c303f
- 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.
202 lines
6.1 KiB
Markdown
202 lines
6.1 KiB
Markdown
# Phase 0: Analysis & Documentation
|
|
|
|
**Status:** `complete`
|
|
**Dependencies:** None
|
|
**Estimated Effort:** Research only (no code changes)
|
|
|
|
---
|
|
|
|
## Objective
|
|
|
|
Understand existing AutoMaker architecture patterns before writing any code. Document findings to ensure consistent implementation.
|
|
|
|
---
|
|
|
|
## Tasks
|
|
|
|
### Task 0.1: Read Core Provider Files
|
|
|
|
**Status:** `complete`
|
|
|
|
Read and understand these files:
|
|
|
|
| File | Purpose | Key Patterns |
|
|
| ----------------------------------------------- | ------------------------ | --------------------------------------- |
|
|
| `apps/server/src/providers/base-provider.ts` | Abstract base class | `executeQuery()` AsyncGenerator pattern |
|
|
| `apps/server/src/providers/claude-provider.ts` | Reference implementation | SDK integration, streaming |
|
|
| `apps/server/src/providers/provider-factory.ts` | Model routing | `getProviderForModel()` pattern |
|
|
| `apps/server/src/providers/types.ts` | Type definitions | `ProviderMessage`, `ExecuteOptions` |
|
|
|
|
**Verification:**
|
|
|
|
```bash
|
|
# Files should exist and be readable
|
|
cat apps/server/src/providers/base-provider.ts | head -50
|
|
cat apps/server/src/providers/claude-provider.ts | head -100
|
|
```
|
|
|
|
### Task 0.2: Read Service Integration
|
|
|
|
**Status:** `complete`
|
|
|
|
Understand how providers are consumed:
|
|
|
|
| File | Purpose | Key Patterns |
|
|
| ----------------------------------------------- | --------------------- | ---------------------------------- |
|
|
| `apps/server/src/services/agent-service.ts` | Chat sessions | Provider streaming, event emission |
|
|
| `apps/server/src/services/auto-mode-service.ts` | Autonomous tasks | executeOptions, tool handling |
|
|
| `apps/server/src/lib/sdk-options.ts` | Configuration factory | Tool presets, max turns |
|
|
|
|
### Task 0.3: Read UI Streaming/Logging
|
|
|
|
**Status:** `complete`
|
|
|
|
Understand log parsing and display:
|
|
|
|
| File | Purpose | Key Patterns |
|
|
| ------------------------------------------ | ------------------ | ---------------------------- |
|
|
| `apps/ui/src/lib/log-parser.ts` | Parse agent output | Entry types, tool categories |
|
|
| `apps/ui/src/components/ui/log-viewer.tsx` | Display logs | Collapsible entries, search |
|
|
|
|
### Task 0.4: Read Setup Flow
|
|
|
|
**Status:** `complete`
|
|
|
|
Understand setup wizard patterns:
|
|
|
|
| File | Purpose | Key Patterns |
|
|
| --------------------------------------------------- | ------------------ | ------------------------ |
|
|
| `apps/server/src/routes/setup/index.ts` | Route registration | Handler patterns |
|
|
| `apps/server/src/routes/setup/get-claude-status.ts` | CLI detection | Installation check logic |
|
|
| `apps/ui/src/components/views/setup-view.tsx` | Wizard UI | Step components |
|
|
|
|
### Task 0.5: Read Types Package
|
|
|
|
**Status:** `complete`
|
|
|
|
Understand type definitions:
|
|
|
|
| File | Purpose | Key Patterns |
|
|
| --------------------------------- | -------------- | ---------------------------- |
|
|
| `libs/types/src/index.ts` | Re-exports | Export patterns |
|
|
| `libs/types/src/settings.ts` | Settings types | `AIProfile`, `ModelProvider` |
|
|
| `libs/types/src/model.ts` | Model aliases | `CLAUDE_MODEL_MAP` |
|
|
| `libs/types/src/model-display.ts` | UI metadata | Display info pattern |
|
|
|
|
### Task 0.6: Document Cursor CLI Behavior
|
|
|
|
**Status:** `complete`
|
|
|
|
Test and document Cursor CLI behavior:
|
|
|
|
```bash
|
|
# Check installation
|
|
cursor-agent --version
|
|
|
|
# Check auth status (if available)
|
|
cursor-agent status 2>&1 || echo "No status command"
|
|
|
|
# Test stream-json output (dry run)
|
|
echo "Test prompt" | cursor-agent -p --output-format stream-json --model auto 2>&1 | head -20
|
|
```
|
|
|
|
Document:
|
|
|
|
- [x] Exact event sequence for simple prompt
|
|
- [x] Error message formats
|
|
- [x] Exit codes for different failure modes
|
|
- [x] How tool calls appear in stream
|
|
|
|
---
|
|
|
|
## Deliverable: Analysis Document
|
|
|
|
Create `docs/cursor-integration-analysis.md` with findings:
|
|
|
|
```markdown
|
|
# Cursor CLI Integration Analysis
|
|
|
|
## Provider Pattern Summary
|
|
|
|
### BaseProvider Interface
|
|
|
|
- `executeQuery()` returns `AsyncGenerator<ProviderMessage>`
|
|
- Messages must match format: { type, message?, result?, error? }
|
|
- Session IDs propagated through all messages
|
|
|
|
### ClaudeProvider Patterns
|
|
|
|
- Uses Claude Agent SDK `query()` function
|
|
- Streaming handled natively by SDK
|
|
- Yields messages directly from SDK stream
|
|
|
|
### Key Interfaces
|
|
|
|
[Document: ProviderMessage, ExecuteOptions, InstallationStatus]
|
|
|
|
## Cursor CLI Behavior
|
|
|
|
### Stream Event Sequence
|
|
|
|
1. system/init - session start
|
|
2. user - input prompt
|
|
3. assistant - response text
|
|
4. tool_call/started - tool invocation
|
|
5. tool_call/completed - tool result
|
|
6. result/success - final output
|
|
|
|
### Event Format Differences
|
|
|
|
[Document any transformations needed]
|
|
|
|
### Error Scenarios
|
|
|
|
- Not authenticated: [error message/code]
|
|
- Rate limited: [error message/code]
|
|
- Network error: [error message/code]
|
|
|
|
## Integration Points
|
|
|
|
### Files to Create
|
|
|
|
[List with descriptions]
|
|
|
|
### Files to Modify
|
|
|
|
[List with specific changes needed]
|
|
|
|
## Open Questions
|
|
|
|
[Any unresolved issues]
|
|
```
|
|
|
|
---
|
|
|
|
## Verification Checklist
|
|
|
|
Before marking this phase complete:
|
|
|
|
- [x] All provider files read and understood
|
|
- [x] Service integration patterns documented
|
|
- [x] Log parser patterns understood
|
|
- [x] Setup wizard flow mapped
|
|
- [x] Types package structure documented
|
|
- [x] Cursor CLI behavior tested (if installed)
|
|
- [x] Analysis document created in `docs/`
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- This phase is **read-only** - no code changes
|
|
- Document anything unclear for later clarification
|
|
- Note any differences from the high-level plan provided
|
|
|
|
---
|
|
|
|
## References
|
|
|
|
- [Cursor CLI Output Format](https://cursor.com/docs/cli/reference/output-format)
|
|
- [Cursor CLI Usage](https://cursor.com/docs/cli/using)
|
|
- [Cursor CLI GitHub Actions](https://cursor.com/docs/cli/github-actions)
|