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

#195 Skill/prompt guidance: prefer the bundled deno when no system deno is on PATH

Opened by bixu · 5/1/2026

Problem

When working on swamp extension models, agents (and humans) reach for deno test ... to run the extension's TypeScript test suite. On a machine without a system-wide deno install, that fails with command not found: deno even though swamp itself ships a bundled deno at ~/.swamp/deno/deno and uses it for everything internally.

The bundled binary is right there, but it's not discoverable from the agent's perspective unless someone (a) already knows it exists, or (b) goes hunting for it. Today's swamp-extension-model / swamp-troubleshooting skills don't mention it, so the agent's first attempt at deno test fails and the agent has to figure out the workaround on its own.

Proposed solution

Add explicit guidance to the relevant swamp skills (at minimum swamp-extension-model and swamp-troubleshooting) that says, in effect: "To run extension tests or any deno command, prefer the bundled deno at ~/.swamp/deno/deno (or $(swamp --deno-path) if such a flag exists/can be added). If no system deno is on PATH, the bundled one is the only viable option — don't ask the user to install deno just to run extension tests."

A stronger variant: have the skill prefer the bundled deno unconditionally, since that guarantees the same deno version swamp itself uses for bundling, eliminating subtle bundler-vs-tester drift.

Either way, the skill should also surface a discoverable command — e.g. swamp doctor deno or swamp deno test ... — so agents have an obvious entry point that doesn't depend on knowing the on-disk path.

Alternatives considered

  1. Document it only in CLAUDE.md / project READMEs. Each repo would have to remember to add it; agents reading the swamp skills wouldn't pick it up by default.
  2. Symlink the bundled deno into PATH at install time. Polluting the user's PATH from a CLI install is intrusive and clashes with users who prefer to manage their own deno toolchain.

Impact

Concrete example from this session: while writing a regression test for hivemq/swamp-extensions issue #53, the natural deno test ... invocation failed because the agent's machine had no system deno. The agent eventually located ~/.swamp/deno/deno and used it, but only after a round-trip with the user. Skill-level guidance would make this a one-shot path.

02Bog Flow
OPENTRIAGEDIN PROGRESSCLOSED+ 1 MOREASSIGNED+ 2 MOREREVIEW

Closed

5/1/2026, 10:42:23 PM

No activity in this phase yet.

03Sludge Pulse
stack72 assigned stack725/1/2026, 10:02:29 PM
Editable. Press Enter to edit.

stack72 commented 5/1/2026, 10:42:19 PM

Hey @bixu

Closing this as won't-fix. The reasoning is architectural and worth recording.

The proposed solution — point agents at ~/.swamp/deno/deno (or expose it via swamp doctor deno / swamp deno test) — would commit swamp to a contract we would be worried about keeping: that the bundled runtime is Deno, that the binary lives at a specific path, and that Deno's CLI surface (flags, output formats, test-runner semantics) is part of swamp's public API. Once external workflows depend on those facts, every Deno major version, every flag rename, and any future swap to a different runtime becomes a user-visible break.

The bundled deno is intentionally an implementation detail. swamp uses it internally for bundling, type-checking, formatting, linting, and quality scoring (e.g. swamp extension fmt, the checks inside swamp extension push). Those surfaces work because they expose operations that happen to use Deno today — not Deno itself. The issue's framing inverts that: it asks for the implementation to be the surface.

The original incident (an agent on a no-system-deno machine couldn't run deno test) is real, but the right fix is a different shape:

  • Add an extension-lifecycle primitive — e.g. swamp extension verify — that runs check + lint + fmt + tests internally, owns the runtime invocation, and exposes no Deno-shaped flags.
  • Update the swamp-extension-model and swamp-troubleshooting skills to point agents at that primitive instead of at deno test directly.
  • Leave ~/.swamp/deno/deno undocumented and unsupported as a path.

We are going to investigate a swamp extension verify - this would effectively lint, check, fmt and test for extension internal code. More to come on this

bixu commented 5/2/2026, 12:45:24 PM

I'd be happy with swamp extension verify. This is even better IMO.

Sign in to post a ripple.