# vSEAL

**Scripted Enterprise Automation Layer** -- Automated golden image sealing for VDI environments.

## Overview

vSEAL replaces manual sealing scripts (like BIS-F) with a declarative, plugin-based framework for preparing and personalizing Windows golden images. The Go CLI (`vseal`) is the sole user-facing interface. A PowerShell 7.4+ module handles all business logic underneath.

**Status:** 0.1.19 pre-release. Not yet production-ready.

## Requirements

| Requirement | Minimum |
|-------------|---------|
| Windows | 11 / Server 2022+ |
| PowerShell | 7.4+ (`pwsh`, not Windows PowerShell 5.1) |
| PSToml | 0.4.0+ (bundled in portable distribution) |

## Quick Start

```bash
# Check environment health
vseal doctor

# Preview what seal would do (dry run)
vseal seal --config path/to/vseal.toml --analyze

# Seal the master image
vseal seal --config path/to/vseal.toml

# Personalize a clone after deployment
vseal engage

# List available plugins
vseal plugins --detail
```

A skeleton configuration ships at `examples/vseal.skeleton.toml`. Generate one with `vseal config init`.

## CLI Reference

All commands support `--json` for machine-readable output.

| Command | Description |
|---------|-------------|
| `vseal seal` | Prepare golden image for deployment (`--analyze` for dry run) |
| `vseal engage` | Activate clone after deployment (`--analyze` for dry run) |
| `vseal status` | Show last run status |
| `vseal doctor` | Environment health check |
| `vseal plugins` | List available plugins (`--detail` for full info) |
| `vseal baselines` | Manage rollback baselines (list, show, delete) |
| `vseal baselines cleanup` | Batch delete baselines by age, validity, or count |
| `vseal rollback` | Restore system to a baseline state |
| `vseal config` | Configuration management (init, validate) |
| `vseal version` | Show CLI version information |

## Plugins

vSEAL uses a folder-based plugin architecture. Each plugin is a self-contained directory with a `plugin.toml` manifest and one or more TOML template files. Three categories are supported:

| Category | Description |
|----------|-------------|
| **Declarative** | Pure TOML templates -- no PowerShell code required |
| **Imperative** | Full PowerShell implementation with direct executor calls |
| **Hybrid** | TOML templates for standard phases, PowerShell for custom logic |

12 built-in plugins ship with the distribution. To create a custom plugin, add a folder under `plugins-custom/` containing a `plugin.toml` and at least one template file. See the built-in `example-*` plugins for reference implementations of each category.

Per-plugin configuration uses `[plugins.{id}]` sections in the TOML config file:

```toml
[plugins.bloatware]
enabled = true

[plugins.example-defender]
enabled = true
scan_before_seal = true
timeout = 600
```

## Documentation

- [Architecture Overview](docs/architecture.md) -- System design, data flow, and component interactions
- [Configuration Reference](docs/configuration.md) -- Complete TOML configuration guide
- [API Reference](docs/api-reference.md) -- All 39 exported PowerShell functions
- [Plugin Authoring Guide](docs/plugin-authoring.md) -- How to create custom plugins
- [Lab Evaluation Guide](docs/quickstart-uat.md) -- 1-hour walkthrough with 3 hands-on scenarios
- [CLI-PowerShell Protocol](docs/cli-ps-protocol.md) -- Technical specification for CLI/module communication

For inline help: `vseal --help` or `vseal <command> --help`.

## CI/CD Integration

Every command accepts `--json` for structured output suitable for pipelines:

```bash
# Check seal status in a pipeline
vseal status --json | jq '.phase'

# List enabled plugins
vseal plugins --json | jq '.[].Name'

# Validate configuration before deployment
vseal config validate --config vseal.toml --json
```

## Development

The project uses [`just`](https://github.com/casey/just) as its build system:

```bash
just setup    # Configure environment after clone
just test     # Run all tests (2,300+ across Pester and Go)
just build    # Build module to dist/
just doctor   # Check development environment health
just smoke    # End-to-end smoke test
```

See [CHANGELOG.md](CHANGELOG.md) for version history.

| Metric | Value |
|--------|-------|
| Milestones shipped | 17 |
| Total tests | 2,300+ |
| Public functions | 39 |
| Built-in plugins | 12 |
| Lines of code | ~21,000 |

## License

[MIT](LICENSE)
