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.

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.

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.

2.7 KiB Raw Blame History