# Backend Plugin System Implementation

## Overview

Implemented a complete plugin system for Cleave that enables users to add custom LLM backend providers without modifying Cleave's source code. The system includes plugin discovery, registry, templates, documentation, settings integration, and security validation.

## Implementation Summary

### Task 0: Plugin Discovery & Registry ✅

**Location**: `src/cleave/tui/backends/plugin.py`

**Features**:
- Automatic plugin discovery from `~/.cleave/backends/`
- Plugin validation and metadata extraction
- PluginInfo dataclass for plugin metadata
- PluginRegistry for managing backends (built-in + plugins)
- Global registry with lazy initialization
- Integration with existing backend registry

**Key Classes**:
```python
@dataclass
class PluginInfo:
    name: str
    version: str
    author: str
    module_path: Path
    backend_class: type[Backend]
    description: str = ""
    is_builtin: bool = False

class PluginRegistry:
    def register_plugin(self, plugin_info: PluginInfo)
    def discover_and_register(self, plugin_dir: Path | None = None) -> int
    def list_plugins() -> list[str]
    def get_backend(self, name: str) -> Backend
    def get_backend_status(self, name: str) -> dict[str, Any]
```

**Test Coverage**: 21 tests covering discovery, validation, registry, and error handling.

---

### Task 1: Plugin Template & Documentation ✅

**Templates**:
- `docs/plugin-template/custom_backend.py` - Blank template with inline docs
- `docs/plugin-template/anthropic_legacy.py` - Working example using Anthropic API

**Documentation**:
- `docs/plugin-template/README.md` - Complete plugin development guide (530 lines)
- `docs/plugins.md` - Main plugin system documentation (686 lines)

**Coverage**:
- Backend interface documentation
- Streaming support examples
- Configuration management
- Testing guidelines
- Security best practices
- Multiple implementation examples (Ollama, OpenAI-compatible, generic REST)
- Troubleshooting guide

---

### Task 2: Settings & Security Integration ✅

**Security Module**: `src/cleave/tui/backends/security.py`

**Features**:
- AST-based static analysis (no code execution)
- Detection of dangerous operations:
  - eval/exec calls (error)
  - subprocess imports (warning)
  - Dangerous imports (warning)
  - File operations (info)
  - Network access (info)
- Plugin metadata validation
- Security report generation
- Directory scanning

**Settings Integration**: Extended `src/cleave/core/settings.py`

**Changes**:
- Backend validation now includes plugin backends
- `detect_available_backends()` includes plugins
- Settings validation recognizes dynamic backend list

**Test Coverage**: 18 tests covering security validation, dangerous code detection, and scanning.

---

## Usage

### For Plugin Developers

1. **Create a plugin**:
   ```bash
   cp docs/plugin-template/custom_backend.py ~/.cleave/backends/my_backend.py
   # Edit my_backend.py to implement Backend interface
   ```

2. **Required plugin metadata**:
   ```python
   __plugin_name__ = "my-backend"
   __plugin_version__ = "1.0.0"
   __plugin_backend__ = MyBackend
   ```

3. **Test plugin**:
   ```bash
   cleave config set backend my-backend
   cleave tui
   ```

### For Users

1. **Install a plugin**:
   ```bash
   curl -o ~/.cleave/backends/ollama.py https://example.com/ollama_plugin.py
   ```

2. **Configure plugin**:
   ```bash
   cleave config set backend ollama
   cleave config set backends.ollama.base_url "http://localhost:11434"
   cleave config set backends.ollama.model "llama3.2"
   ```

3. **Use plugin**:
   ```bash
   cleave tui
   ```

---

## Security Considerations

### Static Analysis Checks

The security validator performs AST-based checks without executing code:

- **Errors** (blocks validation):
  - eval(), exec(), compile(), __import__() calls
  - Missing required metadata

- **Warnings** (allowed but flagged):
  - subprocess imports
  - Dangerous module imports

- **Info** (informational only):
  - Network operations (expected for LLM backends)
  - File operations (should be limited to ~/.cleave/)

### User Responsibility

Users should:
- Only install plugins from trusted sources
- Review plugin source code before installation
- Check security reports: `cleave validate-plugin ~/.cleave/backends/plugin.py`
- Report suspicious plugins to maintainers

---

## Files Created

### Source Code
- `src/cleave/tui/backends/plugin.py` (370 lines) - Plugin system core
- `src/cleave/tui/backends/security.py` (328 lines) - Security validation
- `src/cleave/core/settings.py` (extended) - Settings integration

### Tests
- `tests/test_plugin_discovery.py` (304 lines) - Plugin discovery tests
- `tests/test_security.py` (297 lines) - Security validation tests

### Documentation
- `docs/plugin-template/custom_backend.py` (273 lines) - Blank template
- `docs/plugin-template/anthropic_legacy.py` (225 lines) - Working example
- `docs/plugin-template/README.md` (530 lines) - Template guide
- `docs/plugins.md` (686 lines) - Main plugin documentation

**Total**: ~2,500 lines of code, tests, and documentation

---

## Testing

All tests pass successfully:

```bash
# Plugin discovery tests (21 tests)
pytest tests/test_plugin_discovery.py -v
# ✓ All 21 passed

# Security validation tests (18 tests)
pytest tests/test_security.py -v
# ✓ All 18 passed
```

---

## Future Enhancements

### Not Implemented (Out of Scope)
- TUI integration (separate branch/PR)
- Plugin signing/verification
- Plugin marketplace
- Runtime sandboxing (OS-level isolation)
- Automatic plugin updates

### Possible Extensions
- Plugin dependency management
- Plugin configuration UI in TUI
- Community plugin repository
- Plugin performance monitoring
- Plugin crash reporting

---

## Integration Points

### With Existing Backend System
- Plugins register via existing `register_backend()` function
- Backend retrieval works seamlessly: `get_backend("my-plugin")`
- Authentication checking integrated: `check_auth()` works for plugins

### With Settings System
- Plugin backends appear in `detect_available_backends()`
- Settings validation accepts plugin backend names
- Per-backend configuration works: `backends.my-plugin.api_key`

### With CLI
- `cleave config set backend <plugin-name>` works
- `cleave config list-backends` shows plugins
- `cleave tui` automatically uses configured plugin backend

---

## Alignment with Requirements

✅ **Plugin Architecture**
- Plugin discovery from ~/.cleave/backends/
- Auto-discovery at runtime
- Dynamic backend registration
- Graceful error handling

✅ **Plugin Template**
- Blank template with inline documentation
- Working example (Anthropic API)
- README with comprehensive guide
- Multiple usage examples

✅ **Settings Integration**
- Backend selection via settings
- Per-plugin configuration support
- CLI commands for configuration

✅ **Security**
- AST-based validation (no execution)
- Dangerous operation detection
- Security report generation
- User warnings for unsafe plugins

✅ **Tests**
- 21 tests for plugin discovery
- 18 tests for security validation
- 100% test success rate

✅ **Documentation**
- Template guide (530 lines)
- Main plugin guide (686 lines)
- API reference in docstrings
- Multiple examples and troubleshooting

---

## Commit Message

```
feat(tui): implement backend plugin system for custom LLM providers

Add complete plugin architecture enabling users to create custom LLM
backend implementations without modifying Cleave source code.

Features:
- Plugin discovery from ~/.cleave/backends/
- Dynamic backend registration and validation
- Comprehensive security scanning (AST-based)
- Settings integration for plugin configuration
- Template and working example plugins
- 39 tests (100% pass rate)
- 1,200+ lines of documentation

Components:
- Plugin discovery and registry (plugin.py)
- Security validation (security.py)
- Settings integration (extended settings.py)
- Templates (custom_backend.py, anthropic_legacy.py)
- Documentation (plugins.md, template README)
- Tests (test_plugin_discovery.py, test_security.py)

Security:
- Static analysis via AST scanning
- Detection of eval/exec, subprocess, dangerous imports
- Metadata validation
- User warnings for unsafe operations

Usage:
  cp docs/plugin-template/custom_backend.py ~/.cleave/backends/my_backend.py
  # Implement Backend interface
  cleave config set backend my-backend
  cleave tui

Closes #XXX
```

---

## Notes

- TUI integration is deferred to a separate PR (requires control panel updates)
- Plugin system is fully functional via CLI and programmatic API
- All tests pass, no regressions in existing functionality
- Documentation is comprehensive and includes troubleshooting
- Security validation is basic but effective for common threats
- Users are responsible for installing plugins from trusted sources
