EXTENSIONS
Extensions package reusable automation into installable units. Each extension contains one or more content types — behaviors, workflows, vaults, datastores, and reports — declared in a manifest.
Content Types
| Type | Purpose | Export | File location |
|---|---|---|---|
| Behavior | Resource lifecycle automation | behavior |
extensions/behaviors/ |
| Workflow | Multi-step orchestration | YAML | extensions/workflows/ |
| Vault | Secret storage backend | vault |
extensions/vaults/ |
| Datastore | Data persistence backend | datastore |
extensions/datastores/ |
| Report | Post-execution analysis | report |
extensions/reports/ |
| Webhook | Incoming webhook verification | webhook |
extensions/webhooks/ |
TypeScript content types (behavior, vault, datastore, report) export a named object that Swamp loads at runtime. The export shape and provider interface for each type is documented in the pages below. Behaviors also accept a compatibility spelling; see Behavior § Compatibility.
By default, Swamp discovers local extensions relative to the repository root. To
scan a different directory (e.g. a git worktree), use --extensions-dir or
SWAMP_EXTENSIONS_DIR. See
Extensions Directory
for details.
Release Channels
Every extension version belongs to one of three fixed channels:
| Channel | Purpose | Default |
|---|---|---|
| stable | Production-ready versions | Yes |
| rc | Release candidates awaiting validation | No |
| beta | Early versions for integration testing | No |
Versions promote forward through the ladder: beta to rc to stable. A beta version can skip rc and promote directly to stable. Promotion is a metadata-only operation — the archive content does not change. A yanked version, or any version of a yanked extension, cannot be promoted.
Version numbers are globally unique per extension regardless of channel. The same CalVer version string cannot exist on two different channels simultaneously. Channels are orthogonal metadata on versions — the CalVer format is unchanged.
When --channel is omitted, every command defaults to stable. Auto-resolve and
dependency resolution only consider stable versions. The lockfile records the
installed channel, and update checks stay within that channel.
In This Section
- Manifest — YAML schema for
manifest.yaml - Management — CLI commands for installing, updating, and searching extensions
- Publishing Commands —
fmt,quality, andpush, with gate behavior and blocking errors - Registry Publication API — upload flow, optional private visibility, and confirmation responses
- Scorecard Rubric — quality scoring factors and grade thresholds
- Vault Provider — interface for custom secret storage backends
- Datastore Provider — interface for custom data persistence backends
- Behavior — interface for resource automation behaviors
- Report — interface for post-execution analysis