Duolith docs

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> --json and read the schemas in spec/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.runTests with the project and test file or duolith.preview with 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.
  • VS Code:
    • Commands, duolith tasks with a $duolith problem matcher, and a test explorer that runs duolith 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 as duolith-module.json or duolith-module.yaml.
  • Debuggers. Every editor starts duolith-debug-adapter from the PATH, 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.
  • Tool server. New tools: run_tests, lint_project, scan_packages, check_project, upgrade_project, build_native, build_report, lookup_effect and lookup_theme_token. screenshot_route gains steps (tap, type, navigate, wait) and returns the console log.
    • A tool that writes works only inside the workspace.
    • upgrade_project is a dry run unless asked.

Alternatives considered

OptionWhy not
Each editor parses test files and runs Playwright itselfIt duplicates the runner, and breaks on every change to @duolith/testing.
A server-side workspace/executeCommand for lensesThe language server would then start browsers and dev servers. Editors already run processes and show their output better.
A JetBrains plugin class registering the adapterThe 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 manifestNo file name existed. This one says what it is and sorts beside duolith.yaml.

Consequences

  • Editors without the duolith.runTests and duolith.preview commands show the lenses but cannot run them. The VS Code extension has both.
  • editors/others/test/headless/debuggers.test.ts starts each editor's configured adapter command and launches it for a copy of examples/minimal. Zed and the JetBrains IDEs are not run, so their own project-folder substitution is not covered.