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

cargo build --release

Run

./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:

codebridge-cli --build-command "cargo check" --allowed-commands cargo

Documentation project:

codebridge-cli --build-command none

Full automation mode (with script execution):

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:

{
  "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:

{
  "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

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

writeFile

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

deleteFile

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

createDirectory

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

listDirectory

{ "type": "listDirectory", "params": { "path": "src" } }

---

Git Operations

gitInit 🆕

Initialize a git repository.

{ "type": "gitInit" }

gitStatus

{ "type": "gitStatus" }

gitAdd

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

gitCommit

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

gitPush

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

gitDiff

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

---

Script Execution 🆕

runScript

Execute custom scripts in supported languages.

Deno Example (TypeScript):

{
  "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:

{
  "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:

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

Response:

{
  "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

cargo test

Manual Testing

Test 1: Smart Build Detection

# 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

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

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.

{ "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:

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)

• Smart build detection
• Git initialization action
• 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

git clone <repo>
cd codebridge-cli
cargo build
cargo test

---

📄 License

MIT License - see LICENSE file for details

---

🙏 Acknowledgments

Built with:

• axum - Web framework
• git2 - Git operations
• tokio - Async runtime
• tracing - Logging

---

📞 Support

For issues and questions:

• GitHub Issues: [link]
• Documentation: [link]
• Discord: [link]