0149. Editors run tests, previews and other project jobs through the Duolith command
- 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: language server, VS Code, debugger configurations, MCP tools
Context
The editors (decisions 0025, 0066, 0085) and the agent tool server (decision 0061) each needed more: running one page's tests, previews, tasks, a test explorer, debugging outside VS Code, and the project commands as agent tools. Each could grow its own logic, or reuse the CLI's.
Decision
- The CLI is the one engine. Editors and the tool server run
duolith <command> --jsonand read the schemas inspec/schemas/cli/.duolith test --file <path>runs one test file. - Language server:
- Code lenses. At the top of a page: Run tests in <file>, for the test file beside it and any test file that renders its route, and Open a preview of <route>. Each carries an editor command,
duolith.runTestswith the project and test file orduolith.previewwith the project and route, for the editor to run. - Colour swatches. A swatch shows the theme token's light colour. The picker keeps the token as written, because a page names colours by token.
- References and rename. Without a
tsconfig.json, every page of an open file's project is added to the TypeScript project, so they reach pages that are not open.
- Code lenses. At the top of a page: Run tests in <file>, for the test file beside it and any test file that renders its route, and Open a preview of <route>. Each carries an editor command,
- VS Code:
- Commands,
duolithtasks with a$duolithproblem matcher, and a test explorer that runsduolith test --file --json. - YAML schemas for
theme.yaml,duolith.yaml,permissions.yaml(made from the declarations in effects.yaml at build time), the kit's part files, and module manifests saved asduolith-module.jsonorduolith-module.yaml.
- Commands,
- Debuggers. Every editor starts
duolith-debug-adapterfrom thePATH, the bin of@duolith/debug-adapter:- nvim-dap:
require("duolith.dap").setup(); - Helix:
[language.debugger]; - Zed: the extension's
get_dap_binary; - JetBrains: an LSP4IJ debug adapter template the user adds. LSP4IJ's extension point for registering one is experimental.
- nvim-dap:
- Tool server. New tools:
run_tests,lint_project,scan_packages,check_project,upgrade_project,build_native,build_report,lookup_effectandlookup_theme_token.screenshot_routegains steps (tap, type, navigate, wait) and returns the console log.- A tool that writes works only inside the workspace.
upgrade_projectis a dry run unless asked.
Alternatives considered
| Option | Why not |
|---|---|
| Each editor parses test files and runs Playwright itself | It duplicates the runner, and breaks on every change to @duolith/testing. |
A server-side workspace/executeCommand for lenses | The language server would then start browsers and dev servers. Editors already run processes and show their output better. |
| A JetBrains plugin class registering the adapter | The LSP4IJ API for it is experimental in 0.12. The template works today, and the plugin can register the adapter once that API is stable. |
Names other than duolith-module.json for a saved manifest | No file name existed. This one says what it is and sorts beside duolith.yaml. |
Consequences
- Editors without the
duolith.runTestsandduolith.previewcommands show the lenses but cannot run them. The VS Code extension has both. editors/others/test/headless/debuggers.test.tsstarts each editor's configured adapter command and launches it for a copy ofexamples/minimal. Zed and the JetBrains IDEs are not run, so their own project-folder substitution is not covered.