swamp-extension

name

swamp-extension

description

Create, test, and develop swamp extensions — models, vaults, drivers, datastores, and reports. Covers Zod schemas, smoke testing, manifest.yaml, and the quality scorecard. Do NOT use for running existing models (swamp-model), using vaults (swamp-vault), workflows (swamp-workflow), debugging (swamp-troubleshooting), or publishing (swamp-extension-publish). Triggers on "create model", "custom model", "extension model", "zod schema", "build integration", "extensions/models", "implement model", "smoke test extension", "test extension", "manifest.yaml", "custom vault", "VaultProvider", "extensions/vaults", "custom driver", "ExecutionDriver", "extensions/drivers", "custom datastore", "DatastoreProvider", "extensions/datastores", "create report extension", "extensions/reports", "quality score", "scorecard", "improve my extension", "extension quality", "rubric", "fast-check", "extension grade", "symbols-docs".

Swamp Extension

Create TypeScript extensions that swamp loads at startup. Five extension types share the same workflow: implement an interface, register in a manifest, publish via swamp-extension-publish.

Determine Extension Type

User intent	Type	Export	Location
New data source, API integration, automation	Model	export const model	extensions/models/*.ts
Custom secret backend (HashiCorp Vault, 1P, …)	Vault	export const vault	extensions/vaults/*/mod.ts
Control where/how model methods execute	Driver	export const driver	extensions/drivers/*/mod.ts
Custom storage backend (GCS, DB, …)	Datastore	export const datastore	extensions/datastores/*/mod.ts
Repeatable analysis of model/workflow output	Report	export const report	extensions/reports/*.ts

Before Creating an Extension

1. swamp extension search <query> — does a community extension already cover it? Prefer @swamp/* official extensions first. Install with swamp extension pull <package> and use it. Stop.
2. swamp model type search <query> — check built-in/installed local types.
3. Extend an existing type (including @swamp extensions) if it covers the domain but lacks the method you need.
4. For local or private extensions, use swamp extension source add <path>.
5. Only create a new extension if nothing fits.

Trusted collectives auto-resolve on first use. Only @swamp/* is trusted by default; trust others explicitly with swamp extension trust add <collective> (swamp extension trust list shows which).

Never use command/shell to wrap service integrations — build a dedicated model.

Choosing a Collective Name

Run swamp auth whoami --json to see available collectives. If multiple are returned, always ask the user which one to use. Use @collective/name from the start — placeholder prefixes like @local/ are rejected during push.

Quick Reference

Task	Command/Action
Search community	swamp extension search <query> --json
Verify registration	swamp model type search --json
Verify it loads	swamp doctor extensions --json
Inspect catalog	swamp doctor extensions --verbose
Repair stale state	swamp doctor extensions --repair
Next version	swamp extension version --manifest m.yaml -j
Create manifest	Create manifest.yaml with extension entries
Format extension	swamp extension fmt manifest.yaml --json
Check formatting	swamp extension fmt manifest.yaml --check -j
Quality score	swamp extension quality manifest.yaml --json
Dry-run push	swamp extension push manifest.yaml --dry-run
Push extension	swamp extension push manifest.yaml --json

Quick Starts

Model

/**
 * Processes input messages and stores the result.
 *
 * @module
 */
// extensions/models/my_model.ts
import { z } from "npm:zod@4";

const GlobalArgsSchema = z.object({
  message: z.string(),
});

const OutputSchema = z.object({
  id: z.uuid(),
  message: z.string(),
  timestamp: z.iso.datetime(),
});

/** Model definition for processing input messages. */
export const model = {
  type: "@myorg/my-model",
  version: "2026.02.09.1",
  globalArguments: GlobalArgsSchema,
  resources: {
    "result": {
      description: "Model output data",
      schema: OutputSchema,
      lifetime: "infinite",
      garbageCollection: 10,
    },
  },
  methods: {
    run: {
      description: "Process the input message",
      arguments: z.object({}),
      execute: async (args, context) => {
        const handle = await context.writeResource("result", "main", {
          id: crypto.randomUUID(),
          message: context.globalArgs.message.toUpperCase(),
          timestamp: new Date().toISOString(),
        });
        return { dataHandles: [handle] };
      },
    },
  },
};

Vault

/**
 * Custom vault provider for retrieving secrets from a backend.
 *
 * @module
 */
// extensions/vaults/my-vault/mod.ts
import { z } from "npm:zod@4";

const ConfigSchema = z.object({
  endpoint: z.string().url(),
  token: z.string(),
});

/** Vault provider definition. */
export const vault = {
  type: "@myorg/my-vault",
  name: "My Custom Vault",
  description: "Retrieves secrets from a custom backend",
  configSchema: ConfigSchema,
  createProvider: (name: string, config: Record<string, unknown>) => {
    const parsed = ConfigSchema.parse(config);
    return {
      get: async (key: string) => {
        /* fetch from backend */ return "";
      },
      put: async (key: string, value: string) => {/* store */},
      list: async () => {
        /* list keys */ return [];
      },
      getName: () => name,
    };
  },
};

Driver

/**
 * Custom execution driver for running methods on a remote host.
 *
 * @module
 */
// extensions/drivers/my-driver/mod.ts
import { z } from "npm:zod@4";

const ConfigSchema = z.object({
  host: z.string(),
  port: z.number().default(22),
});

/** Execution driver definition. */
export const driver = {
  type: "@myorg/my-driver",
  name: "My Custom Driver",
  description: "Executes methods on a remote host",
  configSchema: ConfigSchema,
  createDriver: (config: Record<string, unknown>) => {
    const parsed = ConfigSchema.parse(config);
    return {
      type: "@myorg/my-driver",
      execute: async (request, callbacks?) => {
        callbacks?.onLog?.(`Executing ${request.methodName} on ${parsed.host}`);
        const output = new TextEncoder().encode(
          JSON.stringify({ result: "ok" }),
        );
        return {
          status: "success" as const,
          outputs: [{
            kind: "pending" as const,
            specName: request.methodName,
            name: request.methodName,
            type: "resource" as const,
            content: output,
          }],
          logs: [],
          durationMs: 0,
        };
      },
    };
  },
};

Datastore

/**
 * Custom datastore provider for storing runtime data in a backend.
 *
 * @module
 */
// extensions/datastores/my-store/mod.ts
import { z } from "npm:zod@4";

const ConfigSchema = z.object({
  endpoint: z.string().url(),
  bucket: z.string(),
});

/** Datastore provider definition. */
export const datastore = {
  type: "@myorg/my-store",
  name: "My Custom Store",
  description: "Stores runtime data in a custom backend",
  configSchema: ConfigSchema,
  createProvider: (config: Record<string, unknown>) => {
    const parsed = ConfigSchema.parse(config);
    return {
      createLock: (path, opts?) => ({
        acquire: async () => {},
        release: async () => {},
        withLock: async <T>(fn: () => Promise<T>) => fn(),
        inspect: async () => null,
        forceRelease: async (_nonce: string) => false,
      }),
      createVerifier: () => ({
        verify: async () => ({
          healthy: true,
          message: "OK",
          latencyMs: 1,
          datastoreType: "@myorg/my-store",
        }),
      }),
      resolveDatastorePath: (repoDir: string) => `${repoDir}/.my-store`,
    };
  },
};

Shared Development Workflow

All extension types follow the same lifecycle:

1. Confirm nothing covers it — search built-in and community first.
2. Author the extension file — use the Quick Start above; deno check.
3. Verify registration — swamp model type search --json (models/drivers) or swamp vault status --json / swamp datastore status --json.
4. Adversarial review — see Adversarial Review Gate below.
5. Smoke test (models) — see references/model/smoke_testing.md.
6. Unit tests — colocate *_test.ts; deno test passes.
7. Version + manifest — swamp extension version, swamp extension fmt manifest.yaml --check.
8. Quality check (optional) — swamp extension quality manifest.yaml.
9. Publish — use the swamp-extension-publish skill.

Adversarial Review Gate

swamp extension push checks for this.

swamp extension push warns and prompts for confirmation unless a complete, content-hash-bound review report exists for the exact code being pushed. The prompt is the gate — do not answer it blindly or pass --yes to dodge the review. Editing any source (or bumping the version) changes the content hash and asks for a fresh report.

After authoring or significantly modifying extension code, and BEFORE running smoke tests or unit tests:

1. Read references/adversarial-review.md. Execute the Mandatory Mechanical Verification checks first — these catch schema/write mismatches that dimensional review misses. Fix any failures before proceeding.
2. Review against every applicable dimension.
3. Run swamp extension push manifest.yaml --dry-run. When no report exists, it prints the exact report path (a content-hash-bound file under the temp directory) and a JSON skeleton listing every applicable dimension.
4. Write that skeleton to the printed path, setting each dimension's verdict to pass, issue, or na (with a note for anything not pass). Set reviewedAt to the current ISO-8601 timestamp.
5. Present the findings to the user, then re-run the push. A missing, stale, or incomplete report (or any issue verdict) surfaces as a warning to confirm.

Key Rules (All Types)

1. Import: import { z } from "npm:zod@4"; — always required
2. Static imports only: Dynamic import() is rejected during push
3. Pin npm versions: Always pin — inline, via deno.json, or package.json
4. Reserved collectives: Cannot use swamp or si in the type
5. Type pattern: @collective/name (lowercase, alphanumeric, hyphens, underscores)

Discovery & Loading

Type	Location	Export name	Bundle cache
Model	extensions/models/**/*.ts	export const model	(bundled inline)
Vault	extensions/vaults/**/*.ts	export const vault	.swamp/vault-bundles/
Driver	extensions/drivers/**/*.ts	export const driver	.swamp/driver-bundles/
Datastore	extensions/datastores/**/*.ts	export const datastore	.swamp/datastore-bundles/
Report	extensions/reports/*.ts	export const report	(bundled inline)

Files ending in _test.ts are excluded. Files without the correct export are silently skipped. When a file fails to load, swamp emits swamp-warning: on stderr.

If an extension doesn't appear after creation, delete stale bundles (rm -rf .swamp/<type>-bundles/) and retry.

Quality Scorecard

Swamp Club scores published extensions against a 12-factor rubric. Maximum third-party score: 14/15 = 93% (Grade A).

Key factors: README in additionalFiles:, LICENSE file, JSDoc coverage ≥80%, explicit return types, manifest description:, repository: URL on allowlisted host, dependency trust (no deprecated or vulnerable npm deps).

Run swamp extension quality manifest.yaml --json for a local self-check. Dependency trust is evaluated automatically — npm dependencies are audited against OSV.dev advisories and trust signals (downloads, license, recency, maintainer count). HIGH/CRITICAL vulnerabilities block push.

See references/quality/rubric.md for the full rubric and references/quality/templates.md for manifest/README skeletons.

Model-Specific

Models have the richest API surface. For model-specific guidance:

• Model structure (fields, resources, files, methods, checks, upgrades): detailed in references/model/api.md
• Pre-flight checks: references/model/checks.md
• Execute function (context.writeResource, readResource, createFileWriter, dataRepository, extensionFile): references/model/api.md
• Factory models: multiple outputs from one spec — references/model/scenarios.md
• CRUD lifecycle: create/update/delete/sync patterns — references/model/examples.md
• Extending existing types: export const extension — references/model/api.md
• Version upgrades: references/model/upgrades.md
• Smoke testing: references/model/smoke_testing.md
• Docker execution: references/model/docker-execution.md
• Typing: references/model/typing.md
• Bundling skills: references/model/skills.md
• Examples: references/model/examples.md
• Scenarios: references/model/scenarios.md
• Troubleshooting: references/model/troubleshooting.md

Vault-Specific

• VaultProvider interface (get, put, list, getName): references/vault/api.md
• Configuration in .swamp.yaml: references/vault/api.md
• Examples: references/vault/examples.md
• Testing: references/vault/testing.md
• Troubleshooting: references/vault/troubleshooting.md

Note: createProvider takes two args: (name: string, config) — the first is the vault instance name, the second is the parsed config.

Driver-Specific

• ExecutionDriver interface (execute, initialize, shutdown): references/driver/api.md
• Resolution priority: step > job > workflow > definition > "raw" (default)
• Examples: references/driver/examples.md
• Testing: references/driver/testing.md
• Troubleshooting: references/driver/troubleshooting.md

Datastore-Specific

• DatastoreProvider interface (createLock, createVerifier, resolveDatastorePath, optional createSyncService): references/datastore/api.md
• Configuration in .swamp.yaml or SWAMP_DATASTORE env var
• Examples: references/datastore/examples.md
• Testing: references/datastore/testing.md
• Troubleshooting: references/datastore/troubleshooting.md

Report-Specific

For creating report extensions, see references/report/api.md.

Manifest Path Resolution

All extension types support the optional paths.base manifest field. Default behavior is unchanged — omit it and paths resolve relative to the configured extensions/<type>/ directory. Set paths.base: manifest for per-extension-subdir layouts. See swamp-extension-publish references/publishing.md.

CalVer Versioning

Use swamp extension version --manifest manifest.yaml --json to get the correct next version. See publishing reference.

When to Use Other Skills

Need	Use Skill
Use existing models	swamp-model
Use existing vaults	swamp-vault
Create/run workflows	swamp-workflow
Manage model data	swamp-data
Repository setup	swamp-repo
Run/configure reports	swamp-report
Publish extensions	swamp-extension-publish
Debug runtime errors	swamp-troubleshooting
Understand swamp internals	swamp-troubleshooting