recoder-code/.devcontainer/README.md

🚀 Recoder Code - AI-powered CLI for developers. Chat with 40+ models (Claude, GPT-4, DeepSeek, Gemini, Qwen3) with tool calling support. Build projects, automate workflows. Free agentic models included! Features interactive mode, file operations, and opt

# 🐳 Recoder Code DevContainer

This devcontainer provides a complete, preconfigured development environment for Recoder Code with all dependencies, tools, and services ready to use.

## 🚀 Quick Start

### Option 1: VS Code + Dev Containers Extension
1. Install [VS Code](https://code.visualstudio.com/) and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
2. Clone the repository: `git clone https://github.com/caelum0x/recoder-code.git`
3. Open in VS Code and click "Reopen in Container" when prompted
4. Wait for the container to build and initialize (first time takes ~5-10 minutes)

### Option 2: Docker Command Line
```bash
# Clone the repository
git clone https://github.com/caelum0x/recoder-code.git
cd recoder-code

# Build and run the devcontainer
docker build -t recoder-dev .devcontainer
docker run -it -v $(pwd):/workspace recoder-dev zsh
```

### Option 3: Codespaces (if available)
Click "Create codespace" from the GitHub repository page.

## 🔧 What's Included

### ✅ Pre-installed Software
- **Node.js 20** with npm and global package management
- **Published recoder-code package** (latest NPM version)
- **Development tools**: git, docker, zsh with Oh My Zsh
- **Utilities**: fzf, jq, nano, vim, curl, wget
- **GitHub CLI** for repository management

### ✅ Development Environment
- **Workspace**: `/workspace` (your local project directory)
- **Config**: `/home/node/.recoder-code` (persistent across rebuilds)
- **Shell**: zsh with helpful aliases and shortcuts
- **Node**: Global NPM packages and development linking

### ✅ VS Code Extensions
- ESLint, Prettier for code quality
- GitLens for Git integration
- Docker extension for container management
- JSON, YAML, TypeScript support
- Terminal enhancements and utilities

### ✅ Environment Variables
```bash
RECODER_CONFIG_DIR=/home/node/.recoder-code
OPENROUTER_SITE_NAME=Recoder-Code-DevContainer  
OPENROUTER_SITE_URL=https://recoder.xyz
RECODER_DEBUG=true
NODE_OPTIONS=--max-old-space-size=4096
```

## 🎯 Quick Commands

The devcontainer comes with helpful aliases for common operations:

### Basic Commands
```bash
rc --help          # Show recoder-code help
rcs                # Run setup  
rcp                # Check progress
rcm                # List models
rcv                # Show version
rci                # System information
```

### Development Commands  
```bash
rcd                # Run with debug mode
rcl                # Run in lite mode
rcf                # Run with streaming
rchello            # Quick test command
rctest             # Create test file
```

### Services Management
```bash
rcsrv              # Services commands
rcstart            # Start services
rcstop             # Stop services  
rcstatus           # Check service status
```

### Project Management
```bash
rcinit             # Initialize project
rclist             # List sessions
rcresume           # Resume session
```

## 🧪 Testing Your Setup

Run the integration test to validate everything is working:

```bash
/workspace/.devcontainer/test-integration.sh
```

This will check:
- ✅ Published package installation
- ✅ Development workspace setup
- ✅ Configuration and environment
- ✅ Shell aliases and shortcuts
- ✅ Docker and Node.js versions
- ✅ File permissions and mounts

## 📁 Directory Structure

```
/workspace/                     # Your project (mounted from local)
├── cli/                       # CLI source code
├── .devcontainer/             # DevContainer configuration
│   ├── devcontainer.json     # Main container config
│   ├── Dockerfile            # Container image definition
│   ├── recoder-init.sh       # Initialization script
│   ├── test-integration.sh   # Validation tests
│   └── README.md             # This file
└── package.json              # Project configuration

/home/node/.recoder-code/      # Persistent configuration (volume)
├── config.json               # Main configuration
├── .env                      # Environment variables
├── logs/                     # Application logs
└── sessions/                 # Saved sessions
```

## 🔐 API Key Setup

### Method 1: Environment Variable (Recommended)
Set the `OPENROUTER_API_KEY` environment variable on your host machine:

**macOS/Linux:**
```bash
export OPENROUTER_API_KEY=your_key_here
```

**Windows:**
```powershell
$env:OPENROUTER_API_KEY="your_key_here"
```

### Method 2: Configuration File
Edit `/home/node/.recoder-code/.env` in the container:
```bash
OPENROUTER_API_KEY=your_key_here
```

### Method 3: CLI Command
```bash
rc --setup  # Interactive setup wizard
```

## 🛠️ Development Workflow

### 1. Working with Published Package
The devcontainer automatically installs the latest published version:
```bash
which recoder-code    # Shows: /usr/local/bin/recoder-code
rc --version          # Published version
```

### 2. Working with Development Version
Your local code is linked for development:
```bash
npm link              # Link development version
node cli/run.js       # Run development version directly
```

### 3. Testing Changes
```bash
npm run lint          # Check code quality
npm run test          # Run tests
npm run build         # Build project
```

### 4. Package Development
```bash
npm pack              # Create package tarball
npm version patch     # Bump version
npm publish           # Publish to NPM (requires auth)
```

## 🐳 Docker Services

The devcontainer supports running Recoder Code's microservices:

```bash
# Check Docker availability
docker --version

# Generate docker-compose file
rc services compose

# Start services (requires docker-compose.services.yml)
rc services start

# Check service status
rc services status
```

## 🔧 Customization

### Adding VS Code Extensions
Edit `.devcontainer/devcontainer.json`:
```json
"extensions": [
  "your.extension.id"
]
```

### Adding System Packages
Edit `.devcontainer/Dockerfile`:
```dockerfile
RUN apt-get update && apt-get install -y your-package
```

### Modifying Environment
Edit `.devcontainer/devcontainer.json`:
```json
"containerEnv": {
  "YOUR_VAR": "your_value"
}
```

## 🐛 Troubleshooting

### Container Won't Start
1. Check Docker is running on your host machine
2. Ensure you have enough disk space (>2GB needed)
3. Try rebuilding: Command Palette → "Dev Containers: Rebuild Container"

### NPM Global Packages Issues
```bash
npm config list        # Check NPM configuration
npm prefix -g          # Should show /usr/local/share/npm-global
```

### Permission Issues
```bash
sudo chown -R node:node /home/node/.recoder-code
```

### Network Issues
```bash
curl -v https://api.openrouter.com/api/v1/models  # Test API access
ping google.com                                   # Test internet
```

### Development Version Not Working
```bash
cd /workspace
npm install     # Reinstall dependencies
npm link        # Relink global command
```

## 📚 Additional Resources

- **Recoder Website**: https://recoder.xyz
- **NPM Package**: https://www.npmjs.com/package/recoder-code  
- **Documentation**: Check `/workspace/README.md`
- **VS Code Dev Containers**: https://code.visualstudio.com/docs/devcontainers/containers

## 🤝 Contributing

When working in the devcontainer:

1. Make your changes in `/workspace`
2. Test with `npm run test` and integration tests
3. Use development version: `node cli/run.js your-command`
4. Compare with published version: `rc your-command` 
5. Submit PR to `https://github.com/caelum0x/recoder-code`

---

**Happy coding with Recoder Code! 🚀**