46 lines
2.7 KiB
Markdown
46 lines
2.7 KiB
Markdown
# ADR 0016: JavaScript Tool Verification
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Date
|
|
|
|
2026-06-10
|
|
|
|
## Context
|
|
|
|
The repository now contains `tools/mcp-bridge`, a TypeScript Node.js tool that sits next to the ComputerCraft Lua code. It has a different build and test lifecycle than TrapOS packages, but it still participates in the same local developer workflow and Git hooks described by [ADR-0011](adr-0011-repo-conventions.md).
|
|
|
|
The bridge also needs future end-to-end coverage that spans both runtimes: a host Node process and a headless CraftOS-PC computer. That is broader and slower than normal unit tests, and it needs the same kind of timeout discipline as the Lua harness in [ADR-0007](adr-0007-test-framework.md).
|
|
|
|
## Decision
|
|
|
|
Keep the Node package scripts simple and one-purpose:
|
|
|
|
- `npm run build` emits TypeScript into `dist/`.
|
|
- `npm run test` runs only the already-built Node unit tests.
|
|
- `npm run check` runs ESLint. TypeScript compilation is covered by `npm run build` and `npm run ci` to avoid duplicate compiler runs in repository CI.
|
|
- `npm run ci` runs `npm run build && npm run test`.
|
|
- `npm run test-integration` is reserved for bridge-to-CraftOS integration coverage and currently prints an explicit TODO.
|
|
|
|
Expose matching repository recipes for the Node lifecycle:
|
|
|
|
- `just build` delegates to `npm run build` for the bridge.
|
|
- `just test` depends on `just build`, runs `npm run test`, then runs the existing CraftOS-PC test suite.
|
|
- `just check` includes `npm run check` alongside Lua and Markdown checks.
|
|
- `just ci` uses `npm run ci`, then runs CraftOS-PC tests and the broader integration/harness target.
|
|
- `just test-integration` runs the placeholder Node integration target and the Lua timeout harness checks.
|
|
|
|
## Consequences
|
|
|
|
- `npm run test` no longer hides a build step. Callers that need a fresh build must use `npm run ci` or `just test`.
|
|
- `just ci` avoids duplicating Node unit tests by calling `npm run ci` directly and then invoking only the CraftOS-side test body.
|
|
- ESLint failures are part of `just check`, so they are covered by the same pre-commit and pre-push hooks as Lua and Markdown checks. TypeScript compiler failures are covered by `just build`, `just test`, and `just ci`.
|
|
- Future bridge integration tests have a named home before they exist, reducing the chance that slow end-to-end behavior is mixed into fast unit tests.
|
|
|
|
## Future Work
|
|
|
|
- Replace the `npm run test-integration` placeholder with a harness that launches the bridge and CraftOS-PC headless, connects a websocket client from CraftOS, probes through the MCP surface, and tears down both processes reliably.
|
|
- Give the bridge integration harness host-level timeout handling and readable diagnostics modelled on the CraftOS-PC test recipes.
|