# The tools, from app to package — Mercury LMS

> MX5. `mx test` runs a module's tests in a headless Chromium mx starts itself, with mx's own runtime answering `vitest` imports. `mx lsap` starts `hyperscript-lsap` from beside mx. `mx run` runs a package.json script as a cached task, or builds a host and becomes a command.

## Read this when

Create an app, check code, run browser tests, set up the language server, cache a script or prepare a package. New commands here are grounded in source build 0e08e7af420e92b1d7a5f44681dcac3366bfbda0 (reports mx 0.1.1); public publication is pending.

## Start an app

- Unix first fill: `MXNOSUMDB='registry.npmjs.org/fiberfx/*' mx mod cache`. This one-run setting accepts the initial Mercury package bytes without a signed checksum database; later installs verify recorded checksums. Plain unconfigured first fill refuses.
- Read module and TypeScript compiler cache results separately; compiler download failure does not necessarily fail the module fill.
- `mx new hello` uses cached Hyperscript/UI versions, writes package.json, mx.mod, mx.sum, index.html and src/main.tsx, then installs from cache. `cd hello`, `mx dev`.
- Missing cache or nonempty target: exit 1; existing files preserved. Missing name: 2. This build generates mx.mod with mx 0.1.1. No tsconfig is generated.

## Quality commands

- `mx lint`: Oxc, .oxlintrc.json; default correctness warnings. Errors fail; warnings alone do not.
- `mx lint --fix`: safe fixes, then recheck; unresolved errors remain exit 1. `--fix-unsafe` permits behavior-changing fixes.
- `mx fmt --check`: read-only, exit 1 when changes are needed. `mx fmt` writes; second pass stable.
- `mx typecheck [--root <dir>] [--json] [<tsconfig>…]`: root tsconfig.json by default; pass config paths, not source paths.
- Exercise: separate dependency-free project. package.json `{"name":"course-typecheck","type":"module"}`; mx.mod `module registry.npmjs.org/course-typecheck` and `mx 0.1.1`; tsconfig target ES2022, module ESNext, moduleResolution Bundler, strict true, skipLibCheck true, include ["src"]; src/main.ts `export const value: number = 1;`. Measured typecheck 0 errors/1 file, exit 0; quality all stages pass. Add src/type-error.ts with `export const x: number = "s";` → TS2322, exit 1. Remove the plant afterward. This is separate from the new-app exercise.
- Generated-app exercise: return to the `hello` app from `mx new hello`. Create root tsconfig.json with target ES2022, module ESNext, moduleResolution Bundler, jsx react-jsx, jsxImportSource @fiberfx/hyperscript, strict true, skipLibCheck true, include ["src"]. With the measured Hyperscript/UI 4.1.1 cache, `mx typecheck` returns 0 errors/1 file, exit 0. Add src/planted.ts containing `export const x: number = "s";`: TS2322 at 1:14, exit 1. Remove that exercise file to restore 0. No project writes from typechecking; absent offline compiler remains unavailable/3.
- This build uses native TypeScript 7.0.2 as a SHA-256-pinned sidecar in MXCACHE/tools. mod cache or a network-enabled first check fetches it. MXPROXY=off needs it cached; unavailable/refused compiler: 3. Uses scratch config, mx resolver and test-runtime types; no project writes or node_modules resolution.
- `mx quality` runs typecheck, lint, fmt --check even after failure; worst exit wins. `--fix` fixes lint and formats.
- Exit: 0 passed, 1 findings, 2 usage, 3 unavailable/could not run. Single quality verb --json: stage object; quality --json: list. Fields: stage/outcome/detail/files/fixed/findings; findings include path/line/column/rule/severity/message/fixable.

## mx test

- `usage: mx test [<path>...] [--root <dir>] [--timeout <seconds>] [--filter <words>]`
- Files: `*.test.*` / `*.spec.*` with `js mjs jsx ts mts tsx`; never in `node_modules`, `dist`, `target`, `coverage`.
- Browser: `MX_BROWSER`, else the newest Playwright Chromium, then headless shell (`PLAYWRIGHT_BROWSERS_PATH`, `~/Library/Caches/ms-playwright`, `~/.cache/ms-playwright`).
- `--timeout` = whole run (default 120 s). Per test 5 s, per hook 10 s. A page silent 30 s past those is a stall.
- `--filter` = substring of `<file> > <name>`.
- Exit: 0 all passed · 1 failed / none ran / broke · 2 usage · 3 no browser (never a pass).
- Output: `ok    <file> > <name>`, `skip  …`, `FAIL  <file> > <name>: <message>`, `mx test: P passed, F failed, of T`.

## The vitest runtime (mx's own)

`describe`, `it`, `test`, `beforeAll`, `afterAll`, `beforeEach`, `afterEach`, `expect`, `vi` (`fn`, `spyOn`, `stubGlobal`, fake timers, `setSystemTime`), `expectTypeOf`, `assertType` (no-ops at run time), `visit`. No `vi.mock`: it throws.

`visit(url, { width, height, scale, mobile, scheme, ready })` → `{ id, evaluate(fn, ...args), close() }`; `ready` is a CSS selector; `scheme` sets `prefers-color-scheme`.

## mx lsap

- `usage: mx lsap [--mcp] | mx lsap --version`
- A release ships `hyperscript-lsap-<target>` beside `mx-<target>`; install it beside mx as `hyperscript-lsap`. Not on Windows: a Windows release ships mx alone, and `mx lsap` refuses with "The language server isn't built for Windows in this release".
- Starts `hyperscript-lsap` from mx's own directory only; sets `HYPERSCRIPT_LSAP_MX`; exits with the server's code. `--version` → `mx 0.1.1` / `hyperscript-lsap 0.1.0` in the verified archive.
- Missing server: `Error: mx lsap found no language server beside mx.` (exit 1).

## mx run

- Task (package.json has the script): `mx run [--no-cache] [--verify] [-r | --filter <member>]... [-j <n>] <name> [-- args]`. Hit: `hit <key>, restored N files`. Miss: `miss (<why>)`. Task cache: `MXRUN_CACHE`, else `$XDG_CACHE_HOME/mx/run`, else `~/.cache/mx/run`. `MXCACHE` separately names the module cache (normally `~/.mercury/modules`). Env in the key: `NODE_ENV` + `MXRUN_ENV`. Only exit 0 stored. `mx test` scripts are never cached.
- Host (anything else): build, then exec the command (`mx run mix phx.server`).
- Refusals: `a script name is required`, `-r and --filter need an mx.work at or above <dir>`, `-j 0 is not a count`, `a command is required` (exit 2).

## npm-compatible package

`mx pack --npm [<package dir>…]` writes .mx/pack/*.tgz using the package file list and publishConfig exports; deterministic bytes/integrity. It checks an outside-workspace consumer, peers, export imports and declaration imports. Missing/stale output refuses; failed consumer proof removes the archive. Build first. It never publishes. With script "pack": "mx pack --npm", `mx run pack` restores the archive on a hit and repeats the proof.

## Never emit

`npx vitest`, `vitest run`, `jest`, `vi.mock(...)`, `playwright test` for a Mercury module, or a different language server in place of `mx lsap`.

## Next

- Back to the course: /mx
- This companion: /mx/tools/llms.txt

## Navigation

- [Read this page in the browser](/mx/tools)
- [Agent index](/llms.txt)
- [All English companions](/llms-full.txt)
- [Sitemap](/sitemap.xml)
- [Course companion](/mx/llms.txt)