EXTENSION MANIFEST

The extension manifest is a YAML file named manifest.yaml that declares the contents and metadata of a swamp extension. It is the input to swamp extension push, which packages and publishes the extension to the registry.

manifestVersion: 1
name: "@myorg/deploy-tools"
version: "2026.04.07.1"
description: "Deployment automation models and workflows"
models:
  - ec2_instance.ts
  - security_group.ts
workflows:
  - deploy_stack.yaml
reports:
  - cost_summary.ts
additionalFiles:
  - README.md
platforms:
  - darwin-aarch64
  - linux-x86_64
labels:
  - aws
  - deployment
dependencies:
  - "@myorg/aws-core"
releaseNotes: "Added security group model"

Required Fields

manifestVersion

Schema version for the manifest format.

The only supported value is 1. A manifest missing this field or using an unsupported version is rejected.

name

Scoped extension name.

The name has two parts separated by /:

• Collective — the @-prefixed namespace (e.g., @myorg). Must match the authenticated user's collective when pushing.
• Name — one or more /-separated segments (e.g., deploy, aws/ec2, aws/accessanalyzer/analyzer).

All segments must be lowercase and may contain letters, digits, hyphens, and underscores.

The collectives @swamp and @si are reserved for built-in extensions.

All content types within the extension (model types, vault types, workflow names, driver types, datastore types, report names) must use the same collective prefix as the extension name. This is enforced during push.

version

Extension version in CalVer format.

The date components must represent a valid calendar date (month 01-12, day valid for the given month and year including leap years). The micro counter is a non-negative integer that allows multiple versions per day and resets for each new date. In practice, swamp extension version starts the counter at 1.

The registry enforces unique name+version tuples. Use swamp extension version --manifest manifest.yaml to query the latest published version and compute the next CalVer version.

Content Arrays (at least one required)

The manifest must include at least one of models, workflows, vaults, drivers, datastores, or reports with at least one entry. A manifest with none of these is rejected.

Content Fields

All content fields are arrays of relative file paths. Every path must be relative and downward-only — paths containing .. components or starting with / are rejected.

models

TypeScript model entry-point files.

models:
  - ec2_instance.ts
  - aws/s3/bucket.ts

Only list entry-point files. Local imports (e.g., ./helpers.ts) are auto-resolved recursively and included in the archive. Each entry point is bundled into a standalone JavaScript file for the registry.

workflows

YAML workflow files.

workflows:
  - deploy_stack.yaml
  - namespace-debug/workflow.yaml

Workflow files are resolved by checking the indexer symlinks directory (workflows/) first, then the extension workflows directory. Models referenced by workflows are auto-resolved and included in the archive.

vaults

TypeScript vault entry-point files.

drivers

TypeScript driver entry-point files.

datastores

TypeScript datastore entry-point files.

reports

TypeScript report entry-point files.

For vaults, drivers, datastores, and reports, the same rules as models apply: only list entry-point files, local imports are auto-resolved, and each entry point is bundled.

Optional Metadata Fields

description

Human-readable description of the extension.

repository

URL of the extension's source repository.

repository: "https://github.com/myorg/swamp-deploy-tools"

Must be a valid URL. Invalid URLs are rejected during validation.

releaseNotes

Per-version release notes.

Can also be provided via the --release-notes flag on swamp extension push, which overrides the manifest value.

platforms

Platform identifiers the extension supports.

platforms:
  - darwin-aarch64
  - linux-x86_64

Informational only — displayed during pull. Not enforced at install time.

labels

Categorization labels for registry search and filtering.

labels:
  - aws
  - kubernetes
  - security

dependencies

Other extensions this extension depends on.

dependencies:
  - "@myorg/aws-core"
  - "@myorg/network"

Dependencies are pulled automatically when the extension is installed. Maximum dependency resolution depth is 10 to prevent circular loops.

Supplementary File Fields

skills

AI coding tool skill directories to include in the extension.

skills:
  - swamp-deploy

Each entry is a skill directory name, resolved from the project-local skill directory first, then the global skill directory. Each skill directory must contain a SKILL.md file with YAML frontmatter declaring name and description.

Skill file limits:

include

TypeScript files to include alongside models without bundling.

include:
  - helpers/scan_ports.ts

Include files are copied to the archive's models/ directory but are not bundled or quality-checked. They are intended for helper scripts executed via Deno.Command subprocess rather than imported directly. At runtime, the loader skips files that do not declare the expected named export.

additionalFiles

Non-code files to include in the extension.

additionalFiles:
  - README.md
  - templates/config.txt

Additional files are stored under files/ in the archive, preserving their relative paths. Extracted to the models directory on pull.

Path Safety

All file paths in content, supplementary, and include fields are validated:

• Must be relative (must not start with /)
• Must not contain .. components (e.g., ../../workflows/file.yaml)
• Must not contain backslash traversal (e.g., ..\file.ts)

Paths that fail these checks are rejected during both schema validation and file resolution.

Push Checks

Extensions are analyzed for safety and quality before push. All checks run in a single pass.

Safety Checks (hard errors — block push)

Safety Warnings (prompt user)

Quality Checks (hard errors — block push)

Quality checks use the project's deno.json configuration when present, otherwise default rules.

Validation Summary

Complete Example

A manifest using all available fields:

manifestVersion: 1
name: "@myorg/deploy-suite"
version: "2026.04.07.1"
description: "Full deployment automation with models, workflows, and reporting"
repository: "https://github.com/myorg/swamp-deploy-suite"
models:
  - ec2_instance.ts
  - security_group.ts
  - aws/s3/bucket.ts
workflows:
  - deploy_stack.yaml
vaults:
  - secrets_manager.ts
drivers:
  - docker_driver.ts
datastores:
  - s3_datastore.ts
reports:
  - cost_summary.ts
skills:
  - swamp-deploy
include:
  - helpers/scan_ports.ts
additionalFiles:
  - README.md
  - templates/config.txt
platforms:
  - darwin-aarch64
  - linux-x86_64
labels:
  - aws
  - deployment
  - security
dependencies:
  - "@myorg/aws-core"
  - "@myorg/network"
releaseNotes: "Added S3 bucket model and cost reporting"

Archive Structure

When pushed, the extension is packaged as a gzipped tar archive:

extension/
  manifest.yaml
  models/
    ec2_instance.ts
    security_group.ts
    aws/s3/bucket.ts
    helpers/scan_ports.ts     # from include
  bundles/
    ec2_instance.js
    security_group.js
    aws/s3/bucket.js
  workflows/
    deploy_stack.yaml
  vaults/
    secrets_manager.ts
  vault-bundles/
    secrets_manager.js
  drivers/
    docker_driver.ts
  driver-bundles/
    docker_driver.js
  datastores/
    s3_datastore.ts
  datastore-bundles/
    s3_datastore.js
  reports/
    cost_summary.ts
  report-bundles/
    cost_summary.js
  files/
    README.md
    templates/config.txt

Source TypeScript files preserve their relative directory structure. Local imports are resolved recursively and included alongside entry points. Each entry point is compiled into a JavaScript bundle with zod externalized.

Related

• Model Definitions — YAML schema for model definitions referenced by extensions
• Workflows — YAML schema for workflow files included in extensions
• Vaults — vault types and configuration
• Repository Configuration — directory overrides (modelsDir, workflowsDir, etc.) and trust settings that affect extension resolution