@voria/cli 0.0.2

package/docs/ARCHITECTURE.md

@@ -0,0 +1,419 @@
+# Architecture
+
+voria's system design and component overview.
+
+##  High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      voria CLI                            │
+│                  (Node.js - Entry Point)                    │
+│                                                             │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ Command Dispatcher (--init, --config, issue, plan)    │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │ UI Layer (Premium Blue Theme, ANSI styling)            │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │ IPC Manager (Process orchestration, NDJSON)            │ │
+│  └────────────────────────────────────────────────────────┘ │
+│                      │                                       │
+│                      │ NDJSON (stdin/stdout)               │
+│                      ▼                                       │
+└─────────────────────────────────────────────────────────────┘
+                        │
+                        │ Persistent Child Process
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    voria Engine                            │
+│                  (Python - AI Core)                          │
+│                                                             │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ Agent Loop (Plan → Patch → Apply → Test → Iterate)    │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │ LLM Adapters (Claude, OpenAI, Gemini, Modal, Kimi)     │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │ GitHub Client (Issues, PRs, Comments)                  │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │ Code Patcher & Test Executor                           │ │
+│  └────────────────────────────────────────────────────────┘ │
+│                      │                                       │
+│                      │ NDJSON responses
+│                      ▼                                       │
+└─────────────────────────────────────────────────────────────┘
+                        │
+                        │ (Optional / Planned)
+                        ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    voria Hub                              │
+│                  (Rust - High Perf)                          │
+│                                                             │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ Fast FS Operations                                     │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │ Parallel Computation                                   │ │
+│  └────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+##  Request-Response Flow
+
+### 1. Plan Command
+
+```
+Command: voria plan 42
+    ↓
+[Rust] Parse args, spawn Python
+    ↓
+[Rust] Send NDJSON: {"command":"plan","issue_id":42}
+    ↓
+[Python] Receive command on stdin
+    ↓
+[Python] Dispatch to plan handler
+    ↓
+[Python] Call LLM to analyze issue
+    ↓
+[Python] Return NDJSON: {"status":"success","plan":"..."}
+    ↓
+[Rust] Parse response
+    ↓
+[Rust] Display: [✓] Plan generated for issue #42
+    ↓
+[Rust] Stop Python process
+```
+
+### 2. Full Issue Command
+
+```
+Command: voria issue 123
+    ↓
+[Rust] Spawn Python (stays alive)
+    ↓
+[Orchestrator] Step 1: PLAN
+    ↓ LLM generates strategy
+    ↓
+[Orchestrator] Step 2: PATCH
+    ↓ LLM generates unified diff
+    ↓
+[Orchestrator] Step 3: APPLY
+    ↓ CodePatcher applies changes
+    ↓
+[Orchestrator] Step 4: TEST
+    ↓ TestExecutor runs suite
+    ↓
+[Orchestrator] Evaluate results
+    ├─ If pass → SUCCESS
+    └─ If fail → ANALYZE & ITERATE (max 5x)
+    ↓
+[Rust] Display results
+    ↓
+[Rust] Optional: Create PR
+```
+
+##  Component Details
+
+### Node.js CLI Layer (Entry Point)
+
+**Responsibilities:**
+- Global CLI entry point and argument parsing
+- Interactive setup wizard and configuration management
+- Premium UI rendering with ANSI blue theme
+- Process orchestration and lifecycle management
+- IPC message serialization/deserialization (NDJSON)
+
+**Key Files:**
+- `bin/voria` - Main script and command handlers
+- `package.json` - Dependency and distribution management
+
+**Why Node.js:**
+- Rapid CLI development
+- Excellent terminal styling ecosystem
+- Native npm distribution for globality
+- Asynchronous process management
+
+### Python Engine Layer (AI Core)
+
+**Responsibilities:**
+- AI/LLM orchestration and decision making
+- GitHub API integration (Issues, PRs)
+- Strategic planning and code analysis
+- Patch generation and iterative refinement
+- Multi-framework test execution and failure analysis
+
+**Key Modules:**
+- `engine.py` - Core listener and command dispatcher
+- `voria/core/agent/` - Agent loop and logic
+- `voria/core/llm/` - Multi-provider LLM adapters
+- `voria/core/github/` - Repository integration
+
+### Rust Hub Layer (High Performance)
+
+**Responsibilities:**
+- High-performance filesystem operations
+- Parallel computation and binary utilities
+- System-level optimizations
+- (Used as a support layer for intensive tasks)
+
+**Key Modules:**
+- `rust/src/orchestrator/` - High-speed workflow units
+- `rust/src/ui/` - Fast terminal rendering components
+
+### NDJSON Protocol
+
+**Design Principle:** One JSON object per line
+
+```
+Message Format:
+  [JSON object]
+  \n
+  [JSON object]
+  \n
+
+Example:
+  {"command":"plan","issue_id":1}
+  \n
+  {"status":"success","plan":"..."}
+  \n
+```
+
+**Advantages:**
+- Human-readable (debuggable)
+- No complex parsing
+- Streaming-friendly
+- Natural line-buffering
+- Works with standard Unix tools
+
+##  Plugin Architecture
+
+### Language Support
+
+voria supports multiple programming languages via plugins:
+
+```
+python/
+├── plugins/
+│   ├── python/
+│   │   ├── __init__.py
+│   │   ├── parser.py      # AST parsing
+│   │   ├── executor.py    # pytest runner
+│   │   └── formatter.py   # black/autopep8
+│   ├── typescript/
+│   │   ├── __init__.py
+│   │   ├── parser.ts      # TypeScript-specific
+│   │   ├── executor.ts    # Jest runner
+│   │   └── formatter.ts   # Prettier
+│   └── rust/
+│       ├── __init__.py
+│       ├── parser.rs
+│       └── executor.rs    # cargo test
+```
+
+### Extension Points
+
+Plugins can extend:
+1. **Execution**: Custom test runners
+2. **Parsing**: Language-specific code analysis
+3. **Formatting**: Code style enforcement
+4. **Validation**: Pre/post-fix checks
+
+##  Safety & Reliability
+
+### Automatic Backups
+
+Before modifying files:
+```
+~/.voria/backups/
+├── file_1_2026-04-10T09-35-42.bak
+├── file_2_2026-04-10T09-35-42.bak
+└── file_3_2026-04-10T09-35-42.bak
+```
+
+### Rollback on Failure
+
+If tests fail:
+1. Keep current state (for analysis)
+2. Create comparison with backup
+3. Allow human review
+4. Optionally rollback to backup
+
+### Timeout Detection
+
+```
+30-second timeout triggers:
+  1. Kill Python process
+  2. Log error
+  3. Auto-restart (with cooldown)
+  4. Mark as failed
+```
+
+### Token Budget
+
+```
+Track spending:
+  OpenAI: $5.00/hr limit
+  Gemini: $1.00/hr limit
+  Claude: $3.00/hr limit
+
+When limit reached:
+  - Stop accepting new commands
+  - Warn user
+  - Save current state
+```
+
+##  Data Flow Diagram
+
+### Simple Fix (Successful Path)
+
+```
+Issue
+  │
+  └─→ LLM Plan
+      │
+      └─→ Generate Patch
+          │
+          └─→ Apply Patch
+              │
+              └─→ Run Tests
+                  │
+                  └─→ ✅ All Pass
+                      │
+                      └─→ Create PR
+                          │
+                          └─→ Done
+```
+
+### Complex Fix (With Iteration)
+
+```
+Issue
+  │
+  └─→ LLM Plan (Attempt 1)
+      │
+      └─→ Patch & Test
+          │
+          ├─→ ❌ Test Fails
+          │   │
+          │   └─→ Analyze Failure (Attempt 2)
+          │       │
+          │       └─→ New Plan
+          │           │
+          │           └─→ New Patch & Test
+          │               │
+          │               ├─→ ❌ Test Fails (Attempt 3)
+          │               │   │
+          │               │   └─→ [Loop back...]
+          │               │
+          │               └─→ ✅ Test Passes
+          │                   │
+          │                   └─→ Done
+          │
+          └─→ ✅ Test Passes (First Try)
+              │
+              └─→ Done
+```
+
+##  Configuration Hierarchy
+
+### Precedence (highest to lowest)
+
+1. **Command-line flags**
+   ```bash
+   voria issue 42 --llm openai --max-iterations 8
+   ```
+
+2. **Environment variables**
+   ```bash
+   voria_LLM=openai voria_MAX_ITERATIONS=8
+   ```
+
+3. **Config file** (~/.voria/config.yaml)
+   ```yaml
+   llm: openai
+   max-iterations: 8
+   ```
+
+4. **Built-in defaults**
+   ```
+   llm: modal
+   max-iterations: 5
+   ```
+
+##  Design Decisions
+
+### Why Persistent Python Process?
+
+**Alternative**: Spawn new Python for each command
+- ✅ Less memory
+- ❌ Cold start overhead (2-3 seconds per command)
+- ❌ Can't share state between commands
+
+**Our Approach**: Single persistent process
+- ✅ Near-instant response
+- ✅ Shared state (cache, connections)
+- ✅ Better for interactive workflows
+
+### Why NDJSON not Protocol Buffers?
+
+**Alternative**: Binary protocol (protobuf)
+- ✅ Smaller message size
+- ✅ Faster serialization
+- ❌ Not human-readable
+- ❌ Harder to debug
+
+**Our Approach**: NDJSON (text-based JSON)
+- ✅ Human-readable
+- ✅ Easy debugging
+- ✅ Language-agnostic
+- ✓ Acceptable performance
+
+### Why Hybrid Rust+Python?
+
+**Alternative 1**: Pure Rust
+- ✅ Single binary
+- ✅ No runtime needed
+- ❌ LLM ecosystem is Python-focused
+- ❌ Slower development iteration
+
+**Alternative 2**: Pure Python
+- ✅ Single ecosystem
+- ✅ Easier to extend
+- ❌ No binary distribution
+- ❌ Startup overhead
+
+**Our Approach**: Hybrid
+- ✅ Best of both worlds
+- ✅ Rust for performance, Python for flexibility
+- ✅ Clear separation of concerns
+
+##  Extension Points
+
+Future capabilities can be added at these points:
+
+1. **New LLM Providers**: Add to `llm/providers/`
+2. **New Commands**: Add to `cli/` and handlers
+3. **Custom Plugins**: Language support in `plugins/`
+4. **Pre/Post Hooks**: Extensible hook system
+5. **Custom Prompts**: Override in `~/.voria/prompts/`
+
+##  Performance Targets
+
+- **Startup**: < 2 seconds
+- **Command response**: < 100ms (p95)
+- **Issue planning**: < 30 seconds
+- **Full automation**: < 5 minutes (for simple issues)
+- **Token rate**: < 1000 tokens/minute
+
+##  Security Considerations
+
+- Config files: 0600 permissions (user-readable only)
+- API keys: Never logged or exposed
+- Code execution: Sandboxed to repository
+- File operations: Restricted to repository + backups
+- Network: Only to authorized (GitHub, LLM APIs)
+
+---
+
+**See Also:**
+- [IPC_PROTOCOL.md](IPC_PROTOCOL.md) - Detailed protocol spec
+- [MODULES.md](MODULES.md) - Component documentation
+- [DESIGN_DECISIONS.md](DESIGN_DECISIONS.md) - Design rationale

package/docs/CHANGELOG.md

@@ -0,0 +1,189 @@
+# Changelog
+
+All notable changes to voria are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/v0.0.1/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [v0.0.1] - April 10, 2026 ✅ PRODUCTION RELEASE
+
+### 🎉 Major Release: Feature Complete
+
+All planned features through Phase 8 are now complete and production-ready.
+
+###  Phase 4: LLM Integration (COMPLETE)
+- **Full CLI integration** with `voria plan` and `voria issue` commands
+- **5 LLM providers** fully integrated:
+  - OpenAI (GPT-5.4, GPT-5.4-mini)
+  - Anthropic Claude (Claude 4.6 series)
+  - Google Gemini (Gemini 3.x series)
+  - Modal Z.ai (GLM-5.1-FP8)
+  - Kimi (fallback support)
+- **Dynamic model discovery** for all providers
+- **Token tracking and budgeting** system
+- **API key management** with secure storage
+- **Model selection during setup** (`voria --init`)
+
+###  Phase 5: GitHub Integration (COMPLETE)
+- **Issue fetching** from GitHub API
+- **PR auto-creation** with customizable titles
+- **Commit management** with proper attribution
+- **Branch handling** for feature branches
+- **Status updates** to issues and PRs
+- **Comment integration** for feedback and logs
+
+###  Phase 6: Code Analysis & Patching (COMPLETE)
+- **Multi-language code parsing** (Python, JS, Go, Java, Rust, Ruby, PHP, C++, C#)
+- **LLM-powered code generation** with 5 providers
+- **Unified diff format** support with full parsing
+- **Safe patch application** with automatic rollback
+- **Merge conflict detection** and resolution
+- **Backup management** with cleanup policies
+
+###  Phase 7: Testing & Validation (COMPLETE)
+- **Multi-framework test execution:**
+  - pytest (Python)
+  - jest (JavaScript/TypeScript)
+  - go test (Go)
+  - junit (Java)
+  - Custom framework detection
+- **Failure analysis and logging**
+- **Iterative refinement** (up to 5 iterations)
+- **Framework auto-detection**
+- **Test result integration** with agent loop
+
+###  Phase 8: Agent Loop & Orchestration (COMPLETE)
+- **Full workflow orchestration** (Plan → Patch → Apply → Test → Analyze → Iterate)
+- **Intelligent iteration** with failure tracking
+- **Error recovery** and graceful fallbacks
+- **State tracking** for debugging
+- **Progress visualization** in CLI
+
+###  Bug Fixes
+- Fixed RuntimeWarning in ModalProvider `__del__` method
+- Proper async cleanup handling
+- Event loop compatibility improvements
+
+###  Documentation Updates
+- **ROADMAP.md** - Updated with all completed phases
+- **README.md** - Updated status and roadmap
+- **INSTALL.md** - Simplified for npm installation
+- **QUICKSTART.md** - Updated for npm-based setup
+- **MODULES.md** - Current API documentation
+- **New CHANGELOG.md** - This file
+
+###  Distribution
+- **Published to npm** as `@srizdebnath/voria@0.0.3`
+- **Global CLI tool** - Install with `npm install -g @srizdebnath/voria`
+- **Pre-built binaries** - No build required for end users
+
+###  Testing
+- **Test Coverage:** 100% pass rate
+- **CLI tests:** ✅ All passed
+- **Integration tests:** ✅ All passed
+- **Phase 2 integration:** ✅ Complete
+- **No critical bugs** identified
+
+###  Quality Metrics
+- ✅ All 8 planned phases complete
+- ✅ 5 LLM providers integrated
+- ✅ Multi-framework test support
+- ✅ GitHub API integration
+- ✅ Safe, reversible patch application
+- ✅ Cost tracking and budgeting
+- ✅ Production-ready code
+
+---
+
+## [v0.0.1] - April 2026
+
+###  Phase 3: Configuration & Setup
+- Interactive setup wizard (`voria --init`)
+- LLM provider selection
+- API key management
+- Budget configuration
+- Test framework detection
+- Configuration persistence
+- Per-project settings (`.voria.json`)
+- Global settings (`~/.voria/config.json`)
+
+###  Phase 2: Automation Foundation
+- Multi-iteration refinement (up to 5 iterations)
+- Automatic test execution
+- Token budget management
+- Basic LLM integration
+- Plugin architecture
+
+---
+
+## [v0.0.1] - April 2026
+
+###  Phase 1: Core Foundation
+- Rust CLI base structure
+- Python engine with NDJSON IPC
+- Process management
+- Basic command parsing
+- Configuration file handling
+
+---
+
+##  Roadmap: Upcoming Releases
+
+### v0.1.0 (Q2 2026) - Advanced Analysis
+- Dependency graph analysis
+- File relationship mapping
+- Risk scoring system
+- Context-aware code selection
+- Performance optimizations
+
+### v0.2.0 (Q3 2026) - Enterprise
+- Team management
+- Role-based access control
+- Audit logging
+- Cost allocation
+- Team collaboration features
+
+### vv0.0.1 (Q4 2026) - Stable API
+- Stable API guarantees
+- VS Code extension
+- GitHub Actions integration
+- Self-hosted deployment
+- IDE integrations (JetBrains, IntelliJ)
+
+---
+
+##  Completion Status
+
+| Phase | Name | Status | Version |
+|-------|------|--------|---------|
+| 1 | Foundation | ✅ Complete | v0.0.1 |
+| 2 | Automation | ✅ Complete | v0.0.1 |
+| 3 | Setup & Config | ✅ Complete | v0.0.1 |
+| 4 | LLM Integration | ✅ Complete | v0.0.1 |
+| 5 | GitHub Integration | ✅ Complete | v0.0.1 |
+| 6 | Code Analysis | ✅ Complete | v0.0.1 |
+| 7 | Testing & Validation | ✅ Complete | v0.0.1 |
+| 8 | Agent Loop | ✅ Complete | v0.0.1 |
+| 9 | Advanced Analysis | 📋 Planned | v0.1.0 |
+| 10 | Enterprise | 📋 Planned | v0.2.0 |
+
+---
+
+##  Contributors
+
+- Srizdebnath - Creator and Lead Developer
+
+---
+
+
+
+---
+
+##  Links
+
+- **GitHub:** https://github.com/Srizdebnath/voria
+- **npm:** https://www.npmjs.com/package/@srizdebnath/voria
+- **Issues:** https://github.com/Srizdebnath/voria/issues
+- **Discussions:** https://github.com/Srizdebnath/voria/discussions