apt-dnf-bridge-workspace/README.md

# APT-DNF Bridge

A DNF-like bridge around APT for apt-ostree integration. This workspace provides a transaction-based API that makes APT work like DNF.

## 🎯 **Two-Crate Approach**

This workspace implements the refined two-crate approach with feature flags:

- **`apt-dnf-bridge-core`** - Minimal shell-out implementation
- **`apt-dnf-bridge`** - Main crate that re-exports core + optional advanced features
- **`apt-dnf-bridge-advanced`** - Pluggable backends, caching, and enhanced features

## 🚀 **Quick Start**

### Core (Minimal)
```toml
[dependencies]
apt-dnf-bridge = "0.1"
```

### Advanced Features
```toml
[dependencies]
apt-dnf-bridge = { version = "0.1", features = ["advanced"] }
```

## 📁 **Workspace Structure**

```
apt-dnf-bridge-workspace/
├── Cargo.toml                    # Workspace root
├── apt-dnf-bridge-core/          # Minimal implementation
│   ├── Cargo.toml
│   └── src/
│       ├── lib.rs
│       ├── command.rs
│       ├── error.rs
│       ├── package.rs
│       ├── repository.rs
│       └── transaction.rs
├── apt-dnf-bridge/               # Main public crate
│   ├── Cargo.toml
│   └── src/
│       └── lib.rs
├── apt-dnf-bridge-advanced/      # Advanced features
│   ├── Cargo.toml
│   └── src/
│       ├── lib.rs
│       ├── backend.rs
│       ├── package_v2.rs
│       ├── transaction_v2.rs
│       └── backend/
│           ├── shell_backend.rs
│           ├── mock_backend.rs
│           └── libapt_backend.rs
└── examples/                     # Shared examples
    ├── basic_usage.rs
    ├── package_query.rs
    ├── atomicity_notes.rs
    └── backend_selection.rs
```

## 🔧 **Usage Examples**

### Basic Usage (Core Only)
```rust
use apt_dnf_bridge::{Transaction, Package, Repository};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a transaction
    let mut tx = Transaction::new();
    
    // Add packages to install
    let vim = Package::new("vim", "2:8.1.2269-1ubuntu5.14", "amd64");
    tx.add_install(vim).await?;
    
    // Resolve dependencies (APT handles automatically)
    tx.resolve().await?;
    
    // Commit the transaction
    tx.commit().await?;
    
    Ok(())
}
```

### Advanced Usage (With Backends)
```rust
use apt_dnf_bridge::{TransactionV2, PackageDatabaseV2, BackendFactory};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create transaction with auto-detected backend
    let mut tx = TransactionV2::new().await?;
    
    // Add packages
    let vim = Package::new("vim", "2:8.1.2269-1ubuntu5.14", "amd64");
    tx.add_install(vim).await?;
    
    // Resolve and commit
    tx.resolve().await?;
    tx.commit().await?;
    
    Ok(())
}
```

## 🏗️ **Building and Testing**

### Build All Crates
```bash
cargo build
```

### Test Core Features
```bash
cargo test -p apt-dnf-bridge-core
```

### Test Advanced Features
```bash
cargo test -p apt-dnf-bridge-advanced
```

### Run Examples
```bash
# Core examples
cargo run --example basic_usage
cargo run --example package_query

# Advanced examples (requires advanced feature)
cargo run --example backend_selection --features advanced
```

## 🎯 **Feature Flags**

### Core Features (Default)
- Shell-out APT commands
- Basic transaction model
- Package querying
- Repository management
- Error handling

### Advanced Features (`advanced` feature)
- Pluggable backends (shell, mock, libapt)
- Caching system
- Enhanced error handling
- Backend statistics
- Mock backend for testing

## 🔄 **Migration Guide**

### From Single Crate to Workspace
1. **Core users**: No changes needed - same API
2. **Advanced users**: Add `features = ["advanced"]` to Cargo.toml
3. **New users**: Start with core, add advanced when needed

### API Compatibility
- Core API remains unchanged
- Advanced API available via feature flag
- Gradual adoption path supported

## 📚 **Documentation**

- **Core API**: Focus on simplicity and reliability
- **Advanced API**: Focus on power and flexibility
- **Examples**: Demonstrate both core and advanced usage
- **Migration**: Guide for moving between feature levels

## 🚀 **Benefits of This Approach**

1. **Single Crate** - No confusion about which to use
2. **Feature Flags** - Users choose complexity level
3. **Workspace** - Easy version coordination
4. **Re-exports** - Clean API surface
5. **Gradual Adoption** - Start simple, add complexity when needed
6. **Clear Documentation** - One README with feature explanations

This approach gives us all the benefits of the two-crate strategy with much better UX and maintenance.