codebridge-cli 0.6.0-alpha

# CodeBridge CLI

A powerful local server that enables LLM-driven code automation with intelligent build detection, git operations, and script execution capabilities.

## 🚀 New Features

### ✨ Smart Build Detection
Automatically detects your project type and uses the appropriate build command:
- **Rust** (Cargo.toml) → `cargo check`
- **Node.js** (package.json) → `npm run build`
- **Python** (requirements.txt) → `python -m py_compile`
- **Documentation** (mostly .md files) → No build needed
- **Unknown** → No build attempted

No more "could not find Cargo.toml" errors on documentation projects!

### 🔧 Git Repository Initialization
New `GitInit` action allows the LLM to initialize git repositories on-demand. No more manual setup required.

### 🎯 Script Execution (Experimental)
Execute custom scripts in multiple languages for complex automation:
- **Deno**: TypeScript/JavaScript with secure defaults
- **Python**: General-purpose scripting
- **Bash**: Shell automation
- **Rust**: Compiled scripts (coming soon)

**Security Features**:
- Sandboxed execution (filesystem restricted to project)
- Timeout enforcement (30s default)
- No network access by default
- Resource limits

---

## 📦 Installation

### Prerequisites
- Rust 1.70+ (for building)
- Git 2.0+ (for git operations)
- Deno 1.30+ (optional, for script execution)
- Python 3.8+ (optional, for script execution)

### Build from Source
```bash
cargo build --release
```

### Run
```bash
./target/release/codebridge-cli \
  --port 3000 \
  --workspace ./workspace \
  --build-command auto \
  --enable-script-execution \
  --script-languages deno,python
```

---

## 🔧 Configuration

### CLI Options

| Flag | Default | Description |
|------|---------|-------------|
| `--port` | `3000` | HTTP server port |
| `--workspace` | `../codebridge-workspace` | Root directory for projects |
| `--build-command` | `auto` | Build command (use `auto` for detection, `none` to disable) |
| `--allowed-commands` | `npm,cargo,python` | Comma-separated list of allowed shell commands |
| `--enable-script-execution` | `false` | Enable LLM script execution |
| `--script-languages` | `deno,python` | Allowed script languages |
| `--script-timeout` | `30` | Script execution timeout (seconds) |

### Examples

**Rust-only environment**:
```bash
codebridge-cli --build-command "cargo check" --allowed-commands cargo
```

**Documentation project**:
```bash
codebridge-cli --build-command none
```

**Full automation mode** (with script execution):
```bash
codebridge-cli \
  --enable-script-execution \
  --script-languages deno,python,bash \
  --script-timeout 60
```

---

## 📡 API Reference

### Endpoints

#### `POST /execute`
Execute a series of actions and optionally run a build.

**Request**:
```json
{
  "projectId": "my-project",
  "actions": [
    { "type": "writeFile", "params": { "path": "src/main.rs", "content": "fn main() {}" } },
    { "type": "gitInit" },
    { "type": "gitAdd", "params": { "files": ["src/main.rs"] } },
    { "type": "gitCommit", "params": { "message": "Initial commit" } }
  ]
}
```

**Response**:
```json
{
  "actionResults": [
    { "success": true, "content": null, "error": null },
    { "success": true, "content": "Git repository initialized", "error": null },
    { "success": true, "content": null, "error": null },
    { "success": true, "content": "Committed: abc123...", "error": null }
  ],
  "buildOutput": {
    "success": true,
    "errors": [],
    "warnings": [],
    "rawOutput": "..."
  },
  "continueLoop": false
}
```

---

## 🎬 Action Types

### File Operations

#### `readFile`
```json
{ "type": "readFile", "params": { "path": "README.md" } }
```

#### `writeFile`
```json
{ 
  "type": "writeFile", 
  "params": { 
    "path": "src/lib.rs", 
    "content": "pub fn hello() { println!(\"Hello\"); }" 
  } 
}
```

#### `deleteFile`
```json
{ "type": "deleteFile", "params": { "path": "old-file.txt" } }
```

#### `createDirectory`
```json
{ "type": "createDirectory", "params": { "path": "src/components" } }
```

#### `listDirectory`
```json
{ "type": "listDirectory", "params": { "path": "src" } }
```

---

### Git Operations

#### `gitInit` 🆕
Initialize a git repository.
```json
{ "type": "gitInit" }
```

#### `gitStatus`
```json
{ "type": "gitStatus" }
```

#### `gitAdd`
```json
{ "type": "gitAdd", "params": { "files": ["src/main.rs", "Cargo.toml"] } }
```

#### `gitCommit`
```json
{ "type": "gitCommit", "params": { "message": "feat: Add new feature" } }
```

#### `gitPush`
```json
{ 
  "type": "gitPush", 
  "params": { 
    "remote": "origin",  // optional
    "branch": "main"      // optional
  } 
}
```

#### `gitDiff`
```json
{ 
  "type": "gitDiff", 
  "params": { 
    "target": "staged"  // "staged" or omit for unstaged
  } 
}
```

---

### Script Execution 🆕

#### `runScript`
Execute custom scripts in supported languages.

**Deno Example** (TypeScript):
```json
{
  "type": "runScript",
  "params": {
    "language": "deno",
    "code": "import { walk } from 'https://deno.land/std/fs/mod.ts';\n\nfor await (const entry of walk('.', { exts: ['.rs'] })) {\n  logger.log(entry.path);\n}",
    "args": [],
    "timeout": 30
  }
}
```

**Python Example**:
```json
{
  "type": "runScript",
  "params": {
    "language": "python",
    "code": "import os\nfor root, dirs, files in os.walk('.'):\n    for f in files:\n        if f.endswith('.py'):\n            print(os.path.join(root, f))",
    "args": [],
    "timeout": 30
  }
}
```

**Bash Example**:
```json
{
  "type": "runScript",
  "params": {
    "language": "bash",
    "code": "#!/bin/bash\nfind . -name '*.log' -type f -delete\necho 'Cleaned up log files'",
    "args": []
  }
}
```

**Response**:
```json
{
  "success": true,
  "content": "STDOUT:\n./src/main.rs\n./src/lib.rs\nSTDERR:\n",
  "error": null
}
```

---

## 🔒 Security

### Filesystem Isolation
All file operations are restricted to the project directory. Path traversal attempts (`../../../etc/passwd`) are blocked.

### Script Sandboxing
Scripts executed via `runScript`:
- **Cannot access files outside the project directory**
- **Cannot make network requests** (unless `--enable-network` flag is set)
- **Have a timeout** (default 30 seconds)
- **Run with limited privileges** (no sudo/root)

### Git Operations
Git push requires SSH key authentication configured on the host system.

---

## 🧪 Testing

### Run Tests
```bash
cargo test
```

### Manual Testing

**Test 1: Smart Build Detection**
```bash
# Create a docs-only project
mkdir -p workspace/docs-test
echo "# Documentation" > workspace/docs-test/README.md

# Send execute request (should skip build)
curl -X POST http://localhost:3000/execute \
  -H "Content-Type: application/json" \
  -d '{"projectId":"docs-test","actions":[]}'

# Expected: buildOutput should be null
```

**Test 2: Git Initialization**
```bash
curl -X POST http://localhost:3000/execute \
  -H "Content-Type: application/json" \
  -d '{"projectId":"new-project","actions":[{"type":"gitInit"}]}'

# Expected: success with "Git repository initialized"
```

**Test 3: Script Execution**
```bash
curl -X POST http://localhost:3000/execute \
  -H "Content-Type: application/json" \
  -d '{
    "projectId":"test-project",
    "actions":[{
      "type":"runScript",
      "params":{
        "language":"python",
        "code":"print(\"Hello from Python!\")",
        "args":[]
      }
    }]
  }'

# Expected: success with stdout containing "Hello from Python!"
```

---

## 🐛 Troubleshooting

### Issue: "Not a git repository" error

**Solution**: Use the `GitInit` action before other git operations.

```json
{ "type": "gitInit" }
```

---

### Issue: "could not find Cargo.toml" on docs project

**Solution**: Set `--build-command none` or use `auto` (default). The system should automatically detect documentation projects and skip builds.

---

### Issue: Script execution timeout

**Solutions**:
1. Optimize your script to run faster
2. Increase timeout: `--script-timeout 60`
3. Break script into smaller chunks

---

### Issue: Script cannot access files

**Check**:
- File paths are relative to project root
- File exists in the project directory
- No path traversal (`../`) attempts

---

## 📊 Logging

Set log level via environment variable:
```bash
RUST_LOG=codebridge_cli=debug ./codebridge-cli
```

Log levels: `error`, `warn`, `info`, `debug`, `trace`

Log output includes:
- Request IDs for tracking
- Action execution details
- Build command detection
- Script execution logs
- Error details with context

---

## 🗺️ Roadmap

### Phase 1 (Current)
- [x] Smart build detection
- [x] Git initialization action
- [x] Script execution (Deno, Python, Bash)

### Phase 2 (Next)
- [ ] Rust script support
- [ ] Docker sandboxing
- [ ] Script library with pre-approved scripts
- [ ] User approval UI for script execution

### Phase 3 (Future)
- [ ] Heartbeat mechanism for multi-task coordination
- [ ] Dependency installation actions
- [ ] Network access controls
- [ ] Resource monitoring and limits

---

## 🤝 Contributing

Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Submit a pull request

### Development Setup
```bash
git clone <repo>
cd codebridge-cli
cargo build
cargo test
```

---

## 📄 License

MIT License - see LICENSE file for details

---

## 🙏 Acknowledgments

Built with:
- [axum](https://github.com/tokio-rs/axum) - Web framework
- [git2](https://github.com/rust-lang/git2-rs) - Git operations
- [tokio](https://tokio.rs/) - Async runtime
- [tracing](https://github.com/tokio-rs/tracing) - Logging

---

## 📞 Support

For issues and questions:
- GitHub Issues: [link]
- Documentation: [link]
- Discord: [link]