@voria/cli 0.0.2

package/docs/INSTALL.md

@@ -0,0 +1,335 @@
+# Installation Guide
+
+Complete instructions for installing and using voria.
+
+##  Prerequisites
+
+### For Global CLI Tool (Recommended)
+- **Node.js 16+** - Get from [https://nodejs.org](https://nodejs.org)
+- **npm 8+** - Comes with Node.js
+- **Git** - For version control
+
+### For Development/Contributing
+- **Rust 1.70+** - Get from [https://rustup.rs](https://rustup.rs)
+- **Python 3.9+** - Get from [https://python.org](https://python.org)
+- **10+ GB disk space** - For dependencies and build artifacts
+
+### Optional (for specific features)
+- **pytest** - For Python test execution support
+- **Docker** - For sandboxed test runs
+- **GraphQL client** - For GitHub Enterprise
+
+##  Quick Install (Recommended)
+
+### Using npm (Easiest)
+
+```bash
+# Install globally
+npm install -g @srizdebnath/voria
+
+# Verify installation
+voria --version  # Should show v0.0.1
+
+# Initialize in your project
+cd your-project
+voria --init
+```
+
+**That's it!** voria is now ready to use.
+
+## 🔧 Alternative: Manual Installation from Source
+
+### Step 1: Clone Repository
+
+```bash
+git clone https://github.com/Srizdebnath/voria.git
+cd voria
+```
+
+### Step 2: Create Python Virtual Environment
+
+```bash
+# Create virtual environment
+python3 -m venv venv
+source venv/bin/activate
+
+# On Windows: venv\Scripts\activate
+```
+
+### Step 3: Install Python Package
+
+```bash
+cd python
+pip install -e ".[dev]"
+cd ..
+```
+
+**What gets installed:**
+- httpx 0.24.0 - Async HTTP client
+- aiofiles 23.0 - Async file operations
+- pydantic 2.0+ - Data validation
+- pytest 7.4+ - Testing framework (optional)
+- black - Code formatter (optional)
+- mypy - Type checker (optional)
+
+### Step 4: Verify Installation
+
+```bash
+# Test the installation
+voria --help
+
+# Setup your LLM provider
+voria setup-modal
+
+# Setup GitHub access  
+voria set-github-token
+
+# List issues from a repository
+voria list-issues owner/repo
+```
+
+Expected output:
+```
+⚡ voria - AI-Powered Bug Fixing
+
+Usage: voria [OPTIONS] <COMMAND>
+
+Commands:
+  setup-modal       Setup Modal API configuration
+  set-github-token  Set GitHub Personal Access Token
+  list-issues       List issues from a GitHub repository
+  fix               Fix a specific GitHub issue
+  plan              Plan how to fix an issue
+  issue             Run full agent loop on an issue
+  apply             Apply an existing plan
+  help              Print this message or the help of the given subcommand(s)
+
+Options:
+  -v, --verbose          Verbose logging
+  -c, --config <CONFIG>  Configuration file path
+  -h, --help             Print help
+  -V, --version          Print version
+```
+
+##  Configure LLM Providers
+
+voria requires at least one LLM provider. Set up using `voria setup-modal`:
+
+### Interactive Setup (Recommended)
+
+```bash
+# In your project directory
+voria --init
+```
+
+This will guide you through:
+1. ✅ Choose LLM provider (Modal, OpenAI, Gemini, Claude)
+2. ✅ Enter API key
+3. ✅ Set daily budget
+4. ✅ Select test framework
+5. ✅ Save configuration to `.voria.json`
+
+### Manual Configuration
+
+Edit `~/.voria/config.json` (created after `voria --init`):
+
+```json
+{
+  "provider": "openai",
+      "api_key": "sk-...",
+      "model": "gpt-5.4"
+    },
+    "modal": {
+      "api_key": "token-...",
+      "model": "zai-org/GLM-5.1-FP8"
+    }
+  }
+}
+```
+
+### Option C: Environment Variables
+
+```bash
+# OpenAI
+export OPENAI_API_KEY="sk-..."
+
+# Modal
+export MODAL_API_KEY="token-..."
+
+# Google Gemini
+export GOOGLE_API_KEY="..."
+
+# Anthropic Claude
+export ANTHROPIC_API_KEY="..."
+```
+
+##  System-Wide Installation
+
+### Install to PATH
+
+```bash
+# Copy binary to system path
+sudo cp target/release/voria /usr/local/bin/
+
+# Now run from anywhere
+voria --version
+```
+
+### Create Shell Alias
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+alias voria="~/path/to/voria/target/release/voria"
+
+# Reload shell
+source ~/.bashrc
+```
+
+## 🐳 Docker Installation
+
+```dockerfile
+FROM rust:1.70 as builder
+WORKDIR /app
+COPY . .
+RUN cd rust && cargo build --release
+
+FROM python:3.11
+COPY --from=builder /app/target/release/voria /usr/local/bin/
+COPY python /app/python
+WORKDIR /app
+RUN pip install -e python/
+ENTRYPOINT ["voria"]
+```
+
+Build and run:
+
+```bash
+docker build -t voria .
+docker run -it voria --version
+```
+
+##  Post-Installation Verification
+
+### Check All Components
+
+```bash
+# ✅ Check Rust CLI
+./target/release/voria --version
+./target/release/voria --help
+
+# ✅ Check Python engine
+python3 -c "import voria; print('Python OK')"
+
+# ✅ Check NDJSON protocol
+echo '{"command":"plan","issue_id":1}' | python3 -m voria.engine | head -1
+
+# ✅ Check end-to-end
+./target/release/voria plan 1
+```
+
+### Run Test Suite
+
+```bash
+# Python tests
+cd python
+pytest -v
+
+# Rust tests
+cd ../rust
+cargo test
+
+# Full integration
+cd ..
+python3 test_voria_cli.py
+```
+
+##  Development Installation
+
+If you plan to contribute:
+
+```bash
+# Install with dev dependencies
+cd python
+pip install -e ".[dev]"
+
+# Install development tools
+pip install black pyright pytest-cov
+
+# Format code
+black .
+
+# Type check
+pyright .
+
+# Run all tests
+pytest -v
+```
+
+##  Troubleshooting Installation
+
+### "cargo not found"
+
+```bash
+# Install Rust
+curl --proto '=https' --tlsvv0.0.1 -sSf https://sh.rustup.rs | sh
+source $HOME/.cargo/env
+```
+
+### "Python version too old"
+
+```bash
+# Check version
+python3 --version
+
+# Update with your package manager
+brew install python3  # macOS
+apt install python3.11  # Ubuntu
+```
+
+### "Port already in use"
+
+voria uses stdin/stdout, not network ports, so this shouldn't occur. If you see it:
+
+```bash
+# Kill any hanging Python processes
+pkill -f "python.*voria"
+```
+
+### "NDJSON protocol error"
+
+```bash
+# Clear any cached state
+rm -rf ~/.voria/
+
+# Reinstall
+cd python && pip install -e . --force-reinstall
+```
+
+##  Installation Checklist
+
+- [ ] Rust compiled successfully
+- [ ] Python virtual environment created
+- [ ] Python dependencies installed
+- [ ] `voria --version` works
+- [ ] `voria plan 1` works
+- [ ] LLM provider configured
+- [ ] All tests passing
+- [ ] Configuration file created
+
+##  Next Steps
+
+1. Read [QUICKSTART.md](QUICKSTART.md) to run your first command
+2. Check [USER_GUIDE.md](USER_GUIDE.md) for detailed usage
+3. See [EXAMPLES.md](EXAMPLES.md) for real-world scenarios
+4. Join the community on GitHub
+
+##  Need Help?
+
+- Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
+- Read [DEVELOPMENT.md](DEVELOPMENT.md)
+- Search [GitHub Issues](https://github.com/Srizdebnath/voria/issues)
+- Open a new issue
+
+---
+
+**Installation Complete!** Continue with [QUICKSTART.md](QUICKSTART.md) 🚀

package/docs/IPC_PROTOCOL.md

@@ -0,0 +1,310 @@
+# IPC Protocol Specification
+
+Complete specification of voria's NDJSON-based inter-process communication protocol.
+
+##  Protocol Overview
+
+voria uses **NDJSON** (Newline-Delimited JSON) for communication between Rust CLI and Python engine.
+
+## Format Rules (MANDATORY)
+
+1. **One JSON object per line** - no line wrapping
+2. **Newline terminator** - exactly `\n` after each JSON object
+3. **No multi-line JSON** - protocol messages must fit on single line
+4. **Flush after write** - must call `flush()` immediately after writing
+5. **Line-by-line reading** - read one complete line at a time
+
+### Example
+
+```
+{"command":"plan","issue_id":1}\n
+{"status":"success","action":"stop","message":"Done"}\n
+```
+
+NOT acceptable:
+```
+{"command":"plan",
+"issue_id":1}
+```
+
+## Stdout/Stderr Discipline
+
+### Python Side
+
+**stdout** (ONLY protocol messages):
+```python
+response = {"status": "success", "action": "stop", "message": "Done"}
+print(json.dumps(response))  # Automatic \n added
+sys.stdout.flush()           # CRITICAL!
+```
+
+**stderr** (logs and debug info):
+```python
+logger.info("Processing issue...")        # Goes to stderr
+logger.debug("Token count: 1000")          # Goes to stderr
+print(f"Debug: {value}", file=sys.stderr) # Goes to stderr
+```
+
+### Rust Side
+
+**Reads**: Only from stdout (line-by-line JSON parsing)
+**Pipes**: stderr directly to user console
+
+## Message Types
+
+### Request (Rust → Python)
+
+Sent by Rust CLI to invoke Python processing.
+
+```json
+{
+  "command": "plan|issue|apply|graph|test_results",
+  "issue_id": 123,
+  "repo_path": "/path/to/repo",
+  "iteration": 1,
+  "extra_field": "optional"
+}
+```
+
+**Fields**:
+- `command` (required): The action to perform
+- `issue_id` (optional): GitHub issue number
+- `repo_path` (optional): Local repository path
+- `iteration` (optional): Loop iteration count (1-5)
+
+**Command Types**:
+- `plan`: Analyze issue without code changes
+- `issue`: Start full agent loop
+- `apply`: Execute a previously generated plan
+- `graph`: Generate dependency graph
+- `test_results`: Callback with test results
+
+### Response (Python → Rust)
+
+Sent by Python engine to Rust CLI after processing.
+
+```json
+{
+  "status": "success|pending|error",
+  "action": "apply_patch|run_tests|continue|stop",
+  "message": "Human-readable status message",
+  "patch": "... unified diff format ...",
+  "logs": "... multi-line debug output ...",
+  "token_usage": {
+    "used": 1000,
+    "max": 4000,
+    "cost": 0.05
+  }
+}
+```
+
+**Fields**:
+- `status` (required): Success, pending work, or error
+- `action` (required): What Rust should do next
+- `message` (required): Human-readable message
+- `patch` (optional): Unified diff format patch
+- `logs` (optional): Multi-line debug logs
+- `token_usage` (optional): LLM token accounting
+
+**Status Values**:
+- `success`: Action completed successfully
+- `pending`: Action in progress, expect more messages
+- `error`: Action failed with error
+
+**Action Values**:
+- `apply_patch`: Apply the patch to filesystem
+- `run_tests`: Execute test suite
+- `continue`: Continue to next iteration
+- `stop`: Stop processing, issue is done
+
+### Callback (Rust → Python)
+
+Sent by Rust to inform Python of execution results.
+
+```json
+{
+  "command": "test_results",
+  "test_status": "passed|failed",
+  "test_logs": "... test output ...",
+  "error": "... error message if failed ..."
+}
+```
+
+**Fields**:
+- `command` (required): `test_results`
+- `test_status` (required): passed or failed
+- `test_logs` (optional): Test suite output
+- `error` (optional): Error message if failed
+
+## Protocol Flow Examples
+
+### Example 1: Simple Plan Request
+
+```
+RUST → PYTHON:
+{"command":"plan","issue_id":1,"iteration":1}
+
+PYTHON → RUST:
+{"status":"success","action":"stop","message":"Plan generated for issue #1"}
+```
+
+### Example 2: Full Agent Loop
+
+```
+RUST → PYTHON:
+{"command":"issue","issue_id":123,"repo_path":"/home/user/repo"}
+
+PYTHON → RUST:
+{"status":"pending","action":"apply_patch","message":"Generated patch","patch":"--- a/src/main.py\n+++ b/src/main.py\n@@ -1,3 +1,3 @@\n..."}
+
+RUST applies patch, runs tests
+
+RUST → PYTHON:
+{"command":"test_results","test_status":"failed","test_logs":"..."}
+
+PYTHON → RUST:
+{"status":"pending","action":"continue","message":"Tests failed, refining..."}
+
+... (iterations) ...
+
+PYTHON → RUST:
+{"status":"success","action":"stop","message":"Issue resolved!"}
+```
+
+### Example 3: Error Handling
+
+```
+RUST → PYTHON:
+{"command":"plan","issue_id":1}
+
+PYTHON → RUST:
+{"status":"error","action":"stop","message":"Failed to fetch issue: API key missing","logs":"...traceback..."}
+
+RUST displays error and exits
+```
+
+## Encoding
+
+- **Character Encoding**: UTF-8
+- **JSON Spec**: RFC 7159
+- **Line Terminator**: LF (`\n`) on Unix/Linux/macOS, CRLF (`\r\n`) OK but LF preferred
+
+## Timeout Behavior
+
+### Rust Timeout Detection
+
+If no response received for 30 seconds:
+
+1. Log timeout message
+2. Kill Python subprocess
+3. Restart Python engine
+4. Retry last request once
+5. If still no response after 30s → exit with error
+
+### Python Timeout Prevention
+
+Python should send a response within reasonable time (< 5s for most operations).
+
+For long operations:
+- Send periodic `pending` messages
+- Or implement streaming (future enhancement)
+
+## Error Handling
+
+### Python Errors
+
+If Python encounters an error processing a request:
+
+```json
+{
+  "status": "error",
+  "action": "stop",
+  "message": "Description of what failed",
+  "logs": "... traceback to stderr ..."
+}
+```
+
+### Rust Errors
+
+If Rust encounters an error:
+
+1. Log the error
+2. Skip to next command
+3. Or restart Python if critical
+
+### JSON Parse Errors
+
+If either side receives invalid JSON:
+
+1. Log the error to stderr
+2. Send error response if possible
+3. Or abort current operation
+
+## Performance Guidelines
+
+- **Parse Speed**: NDJSON parsing should be < 1ms per message
+- **Flush Timing**: Flush within 100ms of write
+- **Message Size**: Keep messages < 1MB (practical limit)
+- **Latency**: Aim for < 100ms roundtrip for simple operations
+
+## Versioning
+
+Current protocol version: **1.0**
+
+Protocol changes require coordination between Rust and Python versions.
+
+## Testing
+
+### Manual Test (Python Engine)
+
+```bash
+echo '{"command":"plan","issue_id":1}' | python3 -m voria.engine
+```
+
+Expected output:
+```
+{"status":"success","action":"stop","message":"Plan generated for issue #1"}
+```
+
+### Manual Test (Full CLI)
+
+```bash
+./target/debug/voria -v plan 1
+```
+
+Expected behavior:
+- [i] Planning fix for issue #1
+- [✓] Plan generated for issue #1
+- Process exits cleanly
+
+## Debugging
+
+Enable verbose logging:
+
+```bash
+RUST_LOG=debug ./target/debug/voria plan 1
+```
+
+This shows:
+- JSON being sent to Python
+- JSON being received from Python
+- Timing information
+- Process lifecycle events
+
+View Python logs:
+
+```bash
+./target/debug/voria -v plan 1 2>&1 | grep -E "\[DEBUG\]|\[INFO\]"
+```
+
+## Backward Compatibility
+
+Currently no versioning mechanism. Once protocol is stable, add version field:
+
+```json
+{
+  "version": "1.0",
+  "command": "...",
+  ...
+}
+```