0145. An installed Duolith carries its Node companions, and the templates carry tests
- Status: Accepted (Mik, 16 Nov 2026)
- Date: 2026-11-14
- Decided by: wave 5 developer tools agent (domain F), pending Mik
- Planning item: v1 gap audit, developer tools: "an installed CLI works outside the repository"
Context
duolith check, duolith test and duolith create each run a Node program: the type checker (packages/checker), the test runner (packages/testing) and the scaffolder (packages/create). Until now the CLI found them only in the repository (packages/<name>/src). A duolith copied anywhere else could build, but could not check types, test or make an app.
Decision
- Where the CLI finds a companion (
crates/cli/src/companions.rs), first match wins: When none is found, the error names every folder it looked in (E0351 for the checker).- The environment variable
DUOLITH_CHECKER,DUOLITH_TESTINGorDUOLITH_CREATE. - The project's
node_modules/@duolith/<name>, in the project or a folder above it. <prefix>/lib/duolith/<name>beside an installed<prefix>/bin/duolith, orlib/duolith/<name>in the binary's own folder.- The repository's
packages/<name>, only when the binary or the project is inside the repository, and always from source, so a stale bundle never answers there.
- The environment variable
- Each companion ships as a bundle.
scripts/bundle.tswritesdist/bundle/:crates/cli/install/stage.ts --binary <duolith> --out <prefix>lays out an install:bin/duolithandlib/duolith/{checker,testing,create}.- the checker: one ESM file, TypeScript's library files, and the declarations it checks against;
- the testing runner: the package transpiled file by file, with Playwright and
spec/effects/effects.yaml; - the scaffolder:
main.mjs, its templates, and beside them the files every app gets (skills/app,llms.txt,llms/; since decision 0160 the skills are Duolith's packs, carried by the compiler, andskills/appis no longer shipped), laid out as the npm package lays them out.
- The create templates:
- Existing:
blank,tabsanddata. - New:
tabs-auth,effects,native(with a commentedapp:manifest stub in duolith.yaml),themedandtested. - Every new template carries
theme.yaml,duolith.yamland at least one*.test.ts. - Tests check that each one builds, lints clean with
--deny-warnings, is formatted, and passes its own tests;nativealso builds for native.
- Existing:
- **The testing origin is
https://duolith.test.** Sign-in and secure storage need WebCrypto, which only a secure context has.
Alternatives considered
| Option | Why not |
|---|---|
| Compile the companions into the binary (embedded JavaScript) | Still needs Node to run them. The binary grows by the TypeScript compiler and Playwright, and updating one means a new binary. |
Require npm install @duolith/checker @duolith/testing in every project | It would be one resolution step among several, as it is now (2), but making it the only one breaks duolith create and a first duolith check on a fresh machine. |
| Look only beside the binary | It ignores a project that pins its own companion versions. |
Consequences
crates/cli/tests/installed_cli.rsstages an install in a temporary folder outside the repository. It makes an app from a template, checks, builds and tests it, then builds and tests a copy ofexamples/control-flow. It reports E0340 in a copy oftyped-errors, and E0351 once the checker is removed.- The release (domain G) must run each package's
bundlescript and stage the layout above into every CLI archive.@duolith/checker,@duolith/testingand@duolith/createare publishable from theirdist/bundle/, but are stillprivate: true. - Node 22 or later is required on the machine for check, test and create, as before.