ff-cli 0.1.0

# Plugin Development Guide

## Overview

ff-cli supports multiple plugin architectures. This guide covers the recommended approaches for extending ff-cli with custom commands.

## Recommended Plugin Approaches (Ranked)

### 1. ⭐ Compile-time Plugins (Recommended for v0.1.0)

**Best for:** Initial release, stable plugins, type-safety

**How it works:**
- Create a separate Rust crate that depends on `ff-cli`
- Implement the `Command` trait
- Users add your plugin as a dependency in their `Cargo.toml`
- Register commands at startup

**Example:**

```toml
# my-plugin/Cargo.toml
[dependencies]
ff-cli = "0.1"
anyhow = "1.0"
```

```rust
// my-plugin/src/lib.rs
use ff_cli::Command;
use anyhow::Result;

pub struct MyCommand;

impl Command for MyCommand {
    fn name(&self) -> &str {
        "mycmd"
    }

    fn description(&self) -> &str {
        "My custom command"
    }

    fn execute(&self, args: &[String]) -> Result<()> {
        println!("Running with: {:?}", args);
        Ok(())
    }
}
```

**Pros:**
- ✅ Type-safe
- ✅ Fast (no runtime overhead)
- ✅ Easy to distribute via crates.io
- ✅ No security concerns
- ✅ Simple to implement

**Cons:**
- ❌ Requires recompilation to add plugins
- ❌ Users need Rust toolchain

---

### 2. 🔧 Cargo Workspace Plugins

**Best for:** Monorepo setups, related plugins

**How it works:**
- Create a workspace with multiple plugin crates
- Share common code between plugins
- Build all plugins together

**Example structure:**
```
ff-cli-workspace/
├── Cargo.toml          # workspace root
├── ff-cli/             # core CLI
├── ff-plugin-git/      # git plugin
├── ff-plugin-docker/   # docker plugin
└── ff-plugin-k8s/      # kubernetes plugin
```

**Pros:**
- ✅ Easy code sharing
- ✅ Unified versioning
- ✅ All compile-time benefits

**Cons:**
- ❌ Monorepo complexity
- ❌ All-or-nothing builds

---

### 3. 🔌 Dynamic Loading (libloading)

**Best for:** Runtime plugin discovery, third-party plugins

**How it works:**
- Plugins compiled as dynamic libraries (.so/.dylib/.dll)
- Load at runtime from plugin directory
- FFI-safe interface required

**Enable with:**
```toml
[dependencies]
ff-cli = { version = "0.1", features = ["dynamic-plugins"] }
```

**Pros:**
- ✅ No recompilation needed
- ✅ Hot-reload possible
- ✅ Plugin discovery at runtime

**Cons:**
- ❌ Complex API stability
- ❌ FFI safety concerns
- ❌ Platform-specific issues
- ❌ Harder to debug

---

### 4. 🌐 WebAssembly Plugins

**Best for:** Sandboxed execution, untrusted plugins

**How it works:**
- Plugins compiled to WASM
- Run in sandboxed environment
- Use wasmtime or wasmer runtime

**Pros:**
- ✅ Cross-platform
- ✅ Sandboxed (secure)
- ✅ Language-agnostic

**Cons:**
- ❌ Higher complexity
- ❌ Performance overhead
- ❌ Limited host access

---

### 5. 🔀 Process-based Plugins (Git-style)

**Best for:** Language-agnostic, maximum isolation

**How it works:**
- Plugins as separate executables
- Named `ff-cli-<plugin>` (e.g., `ff-cli-git`)
- Discovered via PATH

**Example:**
```bash
# User runs:
ff-cli git status

# ff-cli executes:
ff-cli-git status
```

**Pros:**
- ✅ Language-agnostic
- ✅ Maximum isolation
- ✅ Easy distribution
- ✅ No API coupling

**Cons:**
- ❌ IPC overhead
- ❌ Harder to share state
- ❌ More disk space

---

## Implementation Roadmap

### Phase 1: v0.1.0 - v0.2.0 (Current)
- ✅ Core plugin trait
- ✅ Compile-time plugin support
- ✅ Example plugins
- ✅ Documentation

### Phase 2: v0.3.0 - v0.5.0
- ⬜ Process-based plugin discovery
- ⬜ Plugin configuration system
- ⬜ Plugin registry/marketplace

### Phase 3: v0.6.0+
- ⬜ Dynamic loading support
- ⬜ WASM plugin runtime
- ⬜ Hot-reload capabilities

## Best Practices

1. **Start Simple**: Use compile-time plugins for v0.1.0
2. **Stable API**: Define clear trait boundaries
3. **Versioning**: Use semver for plugin compatibility
4. **Documentation**: Document plugin API changes
5. **Examples**: Provide working plugin examples
6. **Testing**: Test plugin integration

## Plugin Distribution

### Via crates.io
```bash
cargo install ff-cli
cargo install ff-plugin-mycommand
```

### Via Git
```toml
[dependencies]
ff-plugin-custom = { git = "https://github.com/user/plugin" }
```

### Binary Distribution
- Build standalone binaries
- Use process-based approach
- Distribute via package managers

## Security Considerations

- **Compile-time**: Fully trusted code
- **Dynamic**: Verify plugin signatures
- **Process-based**: Run with limited permissions
- **WASM**: Sandboxed by default

## Questions?

Open an issue at: https://github.com/yourusername/ff-cli/issues