Skip to content

Releases: systeminit/swamp

swamp 20260302.211941.0-sha.9cb888e5

02 Mar 21:20
Immutable release. Only release title and notes can be modified.
9cb888e

Choose a tag to compare

What's Changed

  • feat: send repository URL to registry during extension push (#566)

Summary

  • Add optional repository field to PushMetadata interface in the extension API client
  • Wire manifest.repository through to the push metadata in the extension push command

Why this is correct

The swamp-club registry backend already accepts an optional repository field in both push API endpoints, but the CLI was never sending it — even though the manifest parser already reads the field. This change closes that gap with two minimal additions:

  1. PushMetadata interface (extension_api_client.ts): Adding repository?: string makes the type reflect what the API accepts. The field is optional, so all existing callers remain valid without changes.

  2. Push metadata construction (extension_push.ts): manifest.repository || undefined uses logical-OR coercion so that empty strings ("") become undefined, which JSON.stringify omits entirely. The registry receives either a real URL or no field at all — never a blank string.

User impact

Extension authors who set repository in their extension.yaml manifest will now have that URL visible on the registry after pushing. Authors who don't set it (or leave it empty) see no change — the field is simply absent from the API payload.

Test plan

  • deno check — type-checks pass
  • deno lint — no lint issues
  • deno fmt — formatting clean
  • deno run test — all 2488 tests pass

🤖 Generated with Claude Code


Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.211941.0-sha.9cb888e5/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.211941.0-sha.9cb888e5/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.211941.0-sha.9cb888e5/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.211941.0-sha.9cb888e5/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

swamp 20260302.205621.0-sha.ea0fde08

02 Mar 20:57
Immutable release. Only release title and notes can be modified.
ea0fde0

Choose a tag to compare

What's Changed

  • fix: add spinner progress feedback to swamp update (#564)

Summary

  • Add spinner to swamp update so it no longer appears to hang during download/install
  • Shows "Checking for updates..." for --check and "Updating swamp..." for full update
  • Follows the same Spinner pattern already used in auth login, with try/finally for cleanup
  • Spinner is skipped in --json mode

Test plan

  • deno check passes
  • deno lint passes
  • deno fmt passes
  • New tests in update_test.ts pass (5 tests covering start/stop, error cleanup, and JSON-mode skip)

Fixes #561

🤖 Generated with Claude Code


Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.205621.0-sha.ea0fde08/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.205621.0-sha.ea0fde08/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.205621.0-sha.ea0fde08/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.205621.0-sha.ea0fde08/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

swamp 20260302.205225.0-sha.018ec6d8

02 Mar 20:53
Immutable release. Only release title and notes can be modified.
018ec6d

Choose a tag to compare

What's Changed

  • fix: extract core install logic from pullExtension for clean extension updates (#563)

Summary

Extracts the core install pipeline (download → verify → extract → copy → track)
from pullExtension() into a new installExtension() function that returns
structured data instead of rendering output as a side effect. This fixes several
problems with extension update:

  • Broken JSON outputpullExtension emitted its own JSON objects mid-flow,
    so update output was multiple JSON fragments instead of one valid document
  • Double API calls — update called getExtension() to check versions, then
    pullExtension called it again internally to resolve the version
  • Noisy output — pull-specific messages (resolved, integrity, file list) were
    interleaved with update messages
  • Wrong error types — pull failures were recorded as not_found regardless of
    actual cause (could be safety error, integrity failure, etc.)

Design

installExtension as the shared boundary. Every caller (pull, update,
search) needs the same download→verify→extract→copy→track sequence. They differ
only in what they show the user. The I/O is the shared concern; rendering is
per-caller. installExtension returns an InstallResult with all the data
callers need to render their own way.

Throws on conflicts instead of prompting. The interactive prompt is a UX
decision that belongs to the command layer. Update always forces (overwriting is
the point of an update). Pull wants to ask. By throwing a ConflictError, each
caller handles conflicts its way.

New failed status distinct from not_found. not_found means "extension
doesn't exist in registry" (permanent, from the check phase). failed means
"install blew up" (could be transient network error, safety rejection, integrity
failure). Users and JSON consumers need to distinguish these cases.

Changes

src/cli/commands/extension_pull.ts

  • New InstallResult type — structured return with name, version, files,
    integrity status, safety warnings, conflicts, dependency results
  • New InstallContext type — like PullContext without outputMode
  • New ConflictError — thrown when conflicts exist and !force
  • New installExtension() — pure I/O, no rendering, returns InstallResult
  • Rewrote pullExtension() as thin wrapper: calls installExtension, renders
    result, handles ConflictError with interactive prompt + retry

src/domain/extensions/extension_update_service.ts

  • Added FailedStatus interface (status: "failed")
  • Added to ExtensionUpdateStatus union
  • buildUpdateResult counts "failed" in the failed bucket

src/cli/commands/extension_update.ts

  • Uses installExtension directly instead of pullExtension
  • Passes explicit version: s.latestVersion — no redundant API call
  • Always force: true — updates should overwrite
  • Errors recorded as "failed" (not "not_found") with actual error message

src/presentation/output/extension_update_output.ts

  • Added "failed" case to both renderExtensionUpdateCheck and
    renderExtensionUpdateResult

Test files

  • 11 new tests across service, CLI, and output layers for the failed variant

User Impact

  • swamp extension update now produces clean, non-interleaved output
  • swamp extension update --json returns a single valid JSON document
  • Update errors show the actual failure reason (e.g., "safety error",
    "integrity check failed") instead of misleadingly saying "not found"
  • swamp extension pull behavior is unchanged — same interactive prompts,
    same rendering

Test Plan

  • deno check — all types pass
  • deno lint — clean
  • deno fmt — formatted
  • deno run test — 2488 tests pass, 0 failures
  • deno run compile — binary compiles
  • Manual: installed @stack72/system-extensions@2026.02.26.2, ran
    extension update → upgraded to 2026.02.28.1, ran again → "up to date"
  • Manual: extension update --json produces single valid JSON document

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.6 noreply@anthropic.com


Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.205225.0-sha.018ec6d8/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.205225.0-sha.018ec6d8/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.205225.0-sha.018ec6d8/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.205225.0-sha.018ec6d8/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

swamp 20260302.203912.0-sha.b250bb5e

02 Mar 20:40
Immutable release. Only release title and notes can be modified.
b250bb5

Choose a tag to compare

What's Changed

  • feat: check community extensions before building custom models (#562)

Summary

Closes #546

When AI agents are asked to create models for services (e.g., "I need a model
for Tailscale"), they immediately build custom extension models from scratch.
The swamp extension search command already exists (PR #555) but isn't wired
into the model creation workflow — agents and users have no guidance to check
community extensions first.

This PR closes the gap at two levels:

1. Agent guidance updates

  • CLAUDE.md: Adds step 3 to the "Building Automation with Swamp" workflow
    swamp extension search <query> — between local type search and building
    from scratch.
  • swamp-extension-model skill (SKILL.md): Updates the "When to Create a
    Custom Model" decision flow to check community extensions before creating a
    model. Adds a "Search community" row to the Quick Reference table.
  • swamp-extension-model scenarios (references/scenarios.md): Updates all
    4 scenario decision trees to start with checking local types and community
    extensions.

2. User-facing hint in model type search

When model type search returns zero results and the user typed a query, a tip
is shown suggesting swamp extension search <query>:

  • Interactive UI: Displays the hint below "No matching types found" (only
    when a query is present, not when the list is simply empty).
  • JSON output: Adds an optional hint field to TypeSearchData when no
    results match.

Why this is the correct fix

The agent workflow previously was:

local type search → not found → build from scratch

Now it's:

local type search → community extension search → install or build

The guidance changes fix the agent workflow (the primary consumer of skills
and CLAUDE.md). The hint fixes the human workflow — a user who runs
swamp model type search tailscale, gets zero results, and doesn't know what
to do next. Both close the same gap: the missing link between "no local type
found" and "check the community registry."

User impact

  • Agents will now check community extensions before building custom models,
    avoiding duplicate work when a community extension already exists.
  • Users running model type search with no results will see a helpful tip
    pointing them to extension search.
  • No breaking changes — the hint field is optional in TypeSearchData,
    and the interactive hint only appears conditionally.

Test Plan

  • 5 new tests covering hint behavior in both interactive and JSON modes
  • All 2454 existing tests pass
  • deno check, deno lint, deno fmt all pass
  • Binary recompiled successfully

🤖 Generated with Claude Code


Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.203912.0-sha.b250bb5e/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.203912.0-sha.b250bb5e/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.203912.0-sha.b250bb5e/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.203912.0-sha.b250bb5e/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

swamp 20260302.203007.0-sha.8142ddfc

02 Mar 20:31
Immutable release. Only release title and notes can be modified.
8142ddf

Choose a tag to compare

What's Changed

  • feat: show data retrieval commands after workflow run completes (#560)

Summary

  • After a successful workflow run, the log output now shows copy-pasteable swamp data list and swamp data get commands for each unique data artifact produced
  • Skipped entirely for failed runs (no useful data) and when no data artifacts exist
  • Only affects log mode output (onWorkflowComplete in the log progress callback); JSON mode is unchanged

Fixes #559

Test plan

  • Unit test: helper commands appear for successful runs with data artifacts
  • Unit test: no helper commands for failed runs
  • Unit test: no helper commands when no data artifacts exist
  • deno check — type checking passes
  • deno lint — linting passes
  • deno fmt — formatting passes
  • deno run test — all 2452 tests pass

🤖 Generated with Claude Code


Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.203007.0-sha.8142ddfc/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.203007.0-sha.8142ddfc/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.203007.0-sha.8142ddfc/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.203007.0-sha.8142ddfc/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

swamp 20260302.191852.0-sha.061f496c

02 Mar 19:19
Immutable release. Only release title and notes can be modified.
061f496

Choose a tag to compare

What's Changed

  • fix: omit empty platforms and labels from extension search JSON output (#557)

Summary

  • Omit empty platforms and labels arrays from JSON output of extension search
  • Non-empty arrays are still included as before
  • Adds tests verifying both empty-omission and non-empty-retention behavior

Test plan

  • deno run test src/presentation/output/extension_search_output_test.tsx — all 14 tests pass
  • Manual: swamp extension search --json — verify empty platforms/labels are absent

🤖 Generated with Claude Code


Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.191852.0-sha.061f496c/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.191852.0-sha.061f496c/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.191852.0-sha.061f496c/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.191852.0-sha.061f496c/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

swamp 20260302.184040.0-sha.b0814490

02 Mar 18:41
Immutable release. Only release title and notes can be modified.
b081449

Choose a tag to compare

What's Changed

  • feat: proactive update notification after every command (#556)

Closes #493

Problem

Users currently have no way to know that a new version of swamp is available unless they manually run swamp update --check. This means users can run outdated versions for weeks or months without realizing an update exists.

Solution

Adds a zero-latency background update check that caches results and displays a one-line banner on the next invocation when an update exists. The approach is modeled after Deno's own update notification system.

How it works

  1. Command runs normally — no latency impact whatsoever
  2. After the command completes, read the cached notification and display if applicable
  3. Fire off a background HTTP HEAD check (rate-limited to once per 24h) to the stable artifact URL
  4. Cache the result in ~/.swamp/last-update-check.json for the next invocation

Two notification types

When a newer version is found in the cache:

$ swamp version
20260206.200442.0-sha.abc123

A new version of swamp is available. Run `swamp update` to upgrade.

When the installed version is >30 days old (zero-network, uses CalVer date):

$ swamp version
20260106.200442.0-sha.abc123

Your swamp version is 55 days old. Run `swamp update` to upgrade.

Guards — notification is suppressed for:

  • Dev builds — developers running from source don't need update prompts
  • SWAMP_NO_UPDATE_CHECK=1 — environment variable for CI/scripting contexts
  • --json mode — never corrupt structured output
  • update command itself — avoid redundant messaging

Architecture

Follows the existing DDD layered architecture:

Layer File Purpose
Domain version_staleness.ts Pure functions for CalVer date extraction and staleness detection
Domain update_check_cache.ts Cache data type, repository port, and isCacheStale()
Domain update_notification_service.ts Core service: getNotification() (local I/O only) + backgroundCheck() (fire-and-forget)
Infrastructure update_check_cache_file_repository.ts File-based cache at ~/.swamp/last-update-check.json with atomic writes
Presentation update_notification_output.ts Renders yellow banner to stderr
CLI mod.ts Post-command hook + isUpdateCheckDisabledByEnv()

Test plan

  • deno check — type checking passes
  • deno lint — linting passes
  • deno fmt — formatting passes
  • deno run test — all 2428 tests pass (82 new)
  • deno run compile — binary compiles
  • Manual: run any command, verify no notification on first run (no cache yet)
  • Manual: run again after cache exists with a different version — verify banner
  • Manual: SWAMP_NO_UPDATE_CHECK=1 swamp version — verify no notification
  • Manual: swamp version --json — verify no notification in JSON output

🤖 Generated with Claude Code


Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.184040.0-sha.b0814490/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.184040.0-sha.b0814490/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.184040.0-sha.b0814490/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.184040.0-sha.b0814490/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

swamp 20260302.181545.0-sha.842b020c

02 Mar 18:16
Immutable release. Only release title and notes can be modified.
842b020

Choose a tag to compare

What's Changed

  • feat: add extension search command with install from detail view (#555)

Summary

Adds a new swamp extension search subcommand and an inline install action from the search detail view.

  • New extension search command — queries the swamp extension registry with support for --namespace, --platform, --label, --sort, --page, and --per-page options. Renders an interactive fuzzy-filter UI (Ink + fzf) in log mode, or structured JSON in --json mode.
  • Install from detail view — when viewing an extension's details, pressing i pulls the extension directly into the current repo, removing the need for a separate swamp extension pull step. Pressing Enter still returns the selection without installing. Esc goes back to the list.
  • Exports pullExtension / PullContext — the core pull logic in extension_pull.ts is now exported so the search command (and future commands) can reuse it without duplicating code.

Why this approach

The extension search → install flow is the most common user journey: find an extension, then install it. Previously this required two separate commands (swamp extension search to discover, then swamp extension pull @ns/name to install). Adding i as a key command in the detail view makes this a single-step operation while keeping the existing Enter to select behavior unchanged.

The implementation follows the existing patterns in the codebase:

  • Discriminated result type (ExtensionSearchResult with action: "select" | "install") — matches the WorkflowActionSelectUI pattern already used elsewhere
  • Lazy repo resolution — the repo context is only resolved when install is actually requested, so searching works without an initialized repo
  • Reuse of pullExtension — avoids duplicating the pull logic (integrity verification, safety analysis, conflict detection, dependency resolution)

Example commands

# Search all extensions (interactive fuzzy filter)
swamp extension search

# Search with a query
swamp extension search aws

# Filter by namespace and platform
swamp extension search --namespace stack72 --platform aws

# Sort by newest, 10 per page
swamp extension search --sort new --per-page 10

# JSON output mode (for scripting)
swamp extension search aws --json

# Interactive flow:
# 1. Run: swamp extension search
# 2. Type to filter, arrow keys to navigate
# 3. Press Enter to view extension details
# 4. Press "i" to install into current repo
#    — or Enter to select, Esc to go back

Test plan

  • deno check — type checking passes
  • deno lint — no lint errors
  • deno fmt — formatting clean
  • deno run test — all 15 tests pass (12 UI + 3 command validation)
  • Manual: swamp extension search → select → press i → installs into repo
  • Manual: swamp extension search → select → press Enter → returns item (no install)
  • Manual: swamp extension search → select → press i with no repo → clear error

🤖 Generated with Claude Code


Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.181545.0-sha.842b020c/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.181545.0-sha.842b020c/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.181545.0-sha.842b020c/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.181545.0-sha.842b020c/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

swamp 20260302.135703.0-sha.7f1c73cc

02 Mar 13:58
Immutable release. Only release title and notes can be modified.
7f1c73c

Choose a tag to compare

What's Changed

  • docs: add model method describe to design/models.md (#553)

Summary

Follow-up to #552 — documents the new model method describe CLI command in the design doc.

  • Adds a ### model method describe <model_id_or_name> <method_name> section to design/models.md
  • Describes both log and JSON output modes
  • Placed before the existing model method run section

Test plan

  • Documentation-only change, no code affected

🤖 Generated with Claude Code


Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.135703.0-sha.7f1c73cc/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.135703.0-sha.7f1c73cc/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.135703.0-sha.7f1c73cc/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.135703.0-sha.7f1c73cc/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

swamp 20260302.135354.0-sha.1329659a

02 Mar 13:54
Immutable release. Only release title and notes can be modified.
1329659

Choose a tag to compare

What's Changed

  • feat: add model method describe subcommand (#552)

Summary

Closes #550

  • Adds swamp model method describe <model> <method> subcommand that surfaces method-specific documentation (description, typed arguments, data output specs) from model definitions
  • Supports both builtin and extension models, in log and JSON output modes
  • Reuses existing toMethodDescribeData() and formatSchemaAttributes() from the type_describe module — no new domain logic needed

Why this approach

Issue #550 reports that swamp model method run <model> <method> --help shows generic Cliffy help instead of method-specific argument documentation. All the metadata needed already exists in model definitions (method descriptions, Zod argument schemas with .describe()).

Rather than intercepting --help on the run command (which would mix concerns between execution and introspection), this adds a dedicated describe subcommand following the existing model type describe pattern. This is consistent with the CLI's architecture where inspection commands are separate from execution commands.

What changed

New files

File Purpose
src/cli/commands/model_method_describe.ts CLI command — resolves model, validates method, renders output
src/presentation/output/model_method_describe_output.ts Output rendering with ModelMethodDescribeData interface
src/cli/commands/model_method_describe_test.ts Command registration tests (3 tests)
src/presentation/output/model_method_describe_output_test.ts Output rendering tests for log + JSON modes (4 tests)

Modified files

File Change
src/cli/commands/model_method_run.ts Register describe subcommand on modelMethodCommand
integration/ddd_layer_rules_test.ts Bump presentation→infrastructure ratchet 31→32 (new output file follows existing writeOutput pattern)

Testing

Automated

  • 7 new unit tests (all pass)
  • Full test suite: 2383 passed, 0 failed
  • deno check / deno lint / deno fmt — clean
  • deno run compile — binary compiles

Manual (compiled binary, fresh swamp repo init)

Builtin model (command/shell) — log mode:

$ swamp model method describe my-shell-cmd execute
Model: my-shell-cmd
Type: command/shell
Version: 2026.02.09.1

Method: execute - Execute the shell command and capture stdout, stderr, and exit code

Arguments:
  run (string) *required
  workingDir (string)
  timeout (integer)
  env (object)

Data Outputs:
  result [resource] - Shell command execution result (exit code, timing, command) (infinite)
  log [file] - Shell command output (stdout and stderr) (text/plain, infinite)

Extension model (@test/echo) — JSON mode:

{
  "modelName": "my-echo",
  "modelType": "@test/echo",
  "version": "2026.03.02.1",
  "method": {
    "name": "run",
    "description": "Echo the message with a timestamp",
    "arguments": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "prefix": {
          "description": "Optional prefix for the message",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "dataOutputSpecs": [
      {
        "specName": "data",
        "kind": "resource",
        "description": "Echo output",
        "lifetime": "infinite",
        "garbageCollection": 10
      }
    ]
  }
}

Error cases:

$ swamp model method describe my-shell-cmd nonexistent
Error: "Unknown method 'nonexistent' for type 'command/shell'. Available methods: execute"

$ swamp model method describe nonexistent-model execute
Error: "Model not found: nonexistent-model"

Help listing:

$ swamp model method --help
Commands:
  run       <model_id_or_name> <method_name>  - Execute a method on a model
  describe  <model_id_or_name> <method_name>  - Describe a method on a model with argument details
  history                                     - Model method run history commands

Test plan

  • deno check passes
  • deno lint passes
  • deno fmt passes
  • deno run test — all tests pass
  • deno run compile — binary compiles
  • Manual: builtin model describe works (log + JSON)
  • Manual: extension model describe works (log + JSON)
  • Manual: error on invalid method name
  • Manual: error on invalid model name
  • Manual: model method --help lists describe

🤖 Generated with Claude Code


Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.135354.0-sha.1329659a/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.135354.0-sha.1329659a/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.135354.0-sha.1329659a/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.135354.0-sha.1329659a/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/