Skip to main content
← Back to list
01Issue
FeatureClosedSwamp CLI
AssigneesNone

#385 Add swamp extension prune to clean up stale catalog entries

Opened by stack72 · 5/20/2026

Problem

When using SWAMP_REPO_DIR with --extensions-dir to run swamp from git worktrees, the extension catalog at .swamp/_extension_catalog.db accumulates entries keyed by absolute source file paths. Each worktree produces entries like:

  • /repo/trees/wt1/extensions/models/example.ts
  • /repo/trees/wt2/extensions/models/example.ts

When a worktree is deleted (git worktree remove), its catalog rows and cached bundles (under .swamp/bundles/<namespace>/) remain orphaned. They don't affect correctness — the loader scans the current extensions directory, not the catalog — but they waste disk and clutter the catalog over time.

Currently, stale entries self-heal during the next reconcile scan from the appropriate directory, but there's no way to explicitly clean up entries for directories that no longer exist.

Proposed Solution

Add swamp extension prune that:

  1. Scans all entries in _extension_catalog.db
  2. Checks if each entry's source file still exists on disk
  3. Removes catalog entries whose source files are missing
  4. Deletes the corresponding cached bundles under .swamp/bundles/<namespace>/
  5. Reports what was removed (count of entries pruned, disk space reclaimed)

Should support both --json and log output modes. A --dry-run flag would let users preview what would be cleaned up.

Alternatives

  • Do nothing — stale entries are harmless and self-heal on next scan from the right directory. Acceptable for small-scale use but becomes noisy in pipelines that create many short-lived worktrees.
  • Automatic pruning during reconcile — the reconcile scan could check all catalog entries (not just those in the current scan scope) for missing source files. This risks removing entries that are valid in a different worktree context.
  • TTL-based expiry — add a last-accessed timestamp to catalog entries and prune entries older than a threshold. More complex, may prune entries that are still valid but infrequently used.

Context

This came up during triage of swamp-club#381 (worktree support via --extensions-dir). The --extensions-dir flag separates the code plane (extensions/) from the data plane (.swamp/), enabling git worktree workflows. The prune command completes the lifecycle by providing explicit cleanup for ephemeral worktrees.

02Bog Flow
OPENTRIAGEDIN PROGRESSCLOSED

Closed

5/20/2026, 7:45:35 AM

No activity in this phase yet.

03Sludge Pulse
Editable. Press Enter to edit.

stack72 commented 5/20/2026, 7:45:49 AM

We already have swamp doctor extensions --repair which can do this!

Sign in to post a ripple.