#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
- 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.
- 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.
Closed
No activity in this phase yet.
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 testdirectly. - Leave
~/.swamp/deno/denoundocumented 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.