# Custom Plugins

Drop your custom vSEAL plugins into this directory. Each plugin is a self-contained
folder with a `plugin.toml` manifest and a `plugin.ps1` script.

vSEAL scans each subdirectory of `plugins-custom/` for a `plugin.toml` file. If found,
the plugin is registered and available for execution.

For real-world examples, see `module/vSEAL/Plugins/`.

## Quick Start

### 1. Create a plugin folder

```
plugins-custom/
  my-plugin/
    plugin.toml
    plugin.ps1
```

### 2. Define the manifest (`plugin.toml`)

```toml
[plugin]
name = "my-plugin"              # Unique identifier (must match folder name)
version = "1.0.0"               # SemVer version
category = "custom"             # Grouping label (e.g. edr, agents, system)
phases = ["seal", "engage"]     # Which phases this plugin runs in
priority = 500                  # Execution order (lower = earlier, 1-999)
description = "Short summary of what this plugin does"
```

**Field reference:**

| Field         | Required | Description                                      |
|---------------|----------|--------------------------------------------------|
| `name`        | Yes      | Unique plugin identifier, must match folder name  |
| `version`     | Yes      | SemVer version string                             |
| `category`    | Yes      | Logical grouping for display and filtering        |
| `phases`      | Yes      | Array of phases: `"seal"`, `"engage"`, or both    |
| `priority`    | Yes      | Execution order within a phase (1-999)            |
| `description` | Yes      | One-line summary shown in `vseal plugins`         |

### 3. Write the plugin script (`plugin.ps1`)

```powershell
#Requires -Version 7.4

function Invoke-Seal {
    param($Config, $Globals)

    Write-vSEALLog "Sealing: $($Config.message ?? 'default action')"
    # Your seal-phase logic here
}

function Invoke-Engage {
    param($Config, $Globals)

    Write-vSEALLog "Engaging: $($Config.message ?? 'default action')"
    # Your engage-phase logic here
}
```

**Parameters:**

- `$Config` -- Plugin-specific configuration from the TOML config file
- `$Globals` -- Shared execution context (OS info, analyze mode, paths)

**Available functions:** All public vSEAL module functions are available inside
plugin scripts, including `Write-vSEALLog`, `Get-vSEALPlugin`, `Set-vSEALStatus`, etc.

### 4. Configure in your vseal config

Add a section for your plugin in your `.toml` config file:

```toml
[plugins.my-plugin]
enabled = true
message = "Hello from my custom plugin"
```

### 5. Verify discovery

Run `vseal plugins` to confirm your plugin appears in the list:

```
vseal plugins
```

Your plugin should appear with its name, version, category, and phase information.
