# Example Hybrid Plugin

This plugin demonstrates the **hybrid pattern** combining TOML templates with custom PowerShell logic.

## Pattern Overview

| Phase / Mode | Implementation                                |
|--------------|-----------------------------------------------|
| Seal         | TOML template via `Invoke-vSEALActionGroup`   |
| Engage       | TOML template (minimal custom logic)          |
| `--analyze`  | Handled by the orchestrator (no custom `Invoke-Analyze` needed) |
| `--rollback` | Custom PowerShell invoked via `--rollback` switch |

## When to Use Hybrid Pattern

Use the hybrid pattern when:

- **Seal/Engage** actions are standard (registry, service, command) and fit TOML
- **`--rollback` mode** needs validation before execution (safety checks, filtering)
- You want template simplicity for common actions plus custom flexibility

**Comparison to other patterns:**

| Pattern     | Seal/Engage | `--analyze` | `--rollback` | Best For |
|-------------|-------------|-------------|--------------|----------|
| Declarative | TOML only   | Auto        | Auto         | Simple configuration |
| **Hybrid**  | TOML        | Auto        | Custom       | Custom rollback validation |
| Imperative  | PowerShell  | Custom      | Custom       | API integration |

## Files

- `plugin.toml` - Plugin metadata (name, version, category, phases, priority)
- `plugin.ps1` - PowerShell plugin with custom Rollback
- `hybrid.toml` - TOML template for Seal phase actions
- `README.md` - This documentation

## How It Works

### 1. Seal Phase (TOML Template)

The `Invoke-Seal` function loads the TOML template and processes groups:

```powershell
$template = Import-vSEALTemplate -Path 'hybrid.toml'
foreach ($group in $template.Groups) {
    Invoke-vSEALActionGroup -Group $group -Phase 'Seal' -PluginId 'example-hybrid'
}
```

The template handles:
- Condition evaluation (skip groups that don't apply)
- Action dispatch to appropriate executors
- Baseline capture for successful actions
- Error handling per `on_error` strategy

### 2. Analyze Mode (`--analyze` switch)

Hybrid plugins do not need a custom `Invoke-Analyze` function. The orchestrator handles analyze mode automatically by calling `Get-PlannedActions` and inspecting the TOML template. The helper functions `Get-CurrentSecuritySettings` and `Get-AnalysisSummary` in `plugin.ps1` are available for use by other contract functions if needed.

### 3. Rollback Mode (`--rollback` switch)

The `Invoke-Rollback` function adds validation before core rollback:

```powershell
function Invoke-Rollback {
    param($Entries, $PluginId)

    # Validate each entry
    $safeEntries = @()
    foreach ($entry in $Entries) {
        if (Test-SafeToRollback -Entry $entry) {
            $safeEntries += $entry
        } else {
            Write-vSEALLog "Skipping unsafe: $($entry.Target)" -Level WARNING
        }
    }

    # Delegate safe entries to core rollback
    return Invoke-vSEALCoreRollback -Entries $safeEntries -PluginId $PluginId
}
```

**Validation benefits:**
- Filter out entries that shouldn't be rolled back
- Check dependencies before restoring
- Add custom logging or audit trail
- Handle special cases core rollback can't

## Key Integration Points

### Template Loading

```powershell
$pluginDir = Split-Path -Parent $PSCommandPath
$templatePath = Join-Path $pluginDir 'hybrid.toml'
$template = Import-vSEALTemplate -Path $templatePath
```

### Core Rollback Delegation

```powershell
# Invoke-vSEALCoreRollback handles:
#   - LIFO order (last applied = first rolled back)
#   - Type-specific rollback (registry, service, task, command)
#   - Best-effort semantics (continue on individual failures)
Invoke-vSEALCoreRollback -Entries $safeEntries -PluginId $PluginId
```

## Domain: Security Configuration

This example uses mock security settings:

| Setting | Registry Path | Purpose |
|---------|---------------|---------|
| TelemetryEnabled | `HKLM:\SOFTWARE\vSEAL\Mock\Security` | Mock telemetry toggle |
| FirewallProfile | `HKLM:\SOFTWARE\vSEAL\Mock\Security` | Mock firewall config |
| AuditLevel | `HKLM:\SOFTWARE\vSEAL\Mock\Security` | Mock audit level |

The helper function `Get-CurrentSecuritySettings` compares current values to expected values and can be used for drift detection by other contract functions.

## Testing

```powershell
# Check plugin discovery
Import-Module ./src/vSEAL/vSEAL.psd1 -Force
Get-vSEALPlugin -Name 'Example Hybrid'

# Verify phases
$plugin = Get-vSEALPlugin -Name 'Example Hybrid'
$plugin.Phases  # Should show: Seal, Engage (Analyze and Rollback are modes, not phases)

# Validate template
$result = Import-vSEALTemplate -Path './src/vSEAL/Plugins/example-hybrid/hybrid.toml' -ValidateOnly
$result.IsValid  # Should be True
$result.Groups.Count  # Should be 3
```

## Key Points

1. **Template handles repetitive Seal actions** - No need to write PowerShell for standard registry/service changes
2. **Analyze mode handled by the orchestrator** - No custom `Invoke-Analyze` needed; the orchestrator uses `Get-PlannedActions` and template inspection
3. **Custom `--rollback` mode adds safety validation** - Filter unsafe entries, validate before restoring
4. **Best of both worlds** - Template simplicity for common actions, custom power for complex logic

---

*Part of vSEAL example plugin collection for learning and testing plugin patterns.*
