04 — Integration & tooling

Sub-plan of trap-sandbox-gateway-spec. Build last (M4): requires both the TS gateway (M1) and the Lua client (M2) to exist. References the spec's Protocol/Handshake for assertions.

Scope

Host tooling (just/npm.just recipes, sandbox-serve, docs) and the cross-side tests: TS integration (real craftos ↔ real gateway) plus the full-boot e2e.

Task checklist

just/npm.just: extend install/build/check/test/test-integration/ci to cover tools/trap-sandbox alongside mcp-bridge; ensure just install/just ci include it.
just/opencode.just (or new recipe): add just sandbox-serve mirroring opencode-serve.
docs/public-ports.md: add a 4444 row.
TS integration harness + cases (tools/trap-sandbox/test-integration/).
Full-boot e2e.
Gate: npm run test:integration green; just ci covers both tools.

Tooling

just/npm.just: extend recipes (install/build/check/test/test-integration/ci) to cover tools/trap-sandbox alongside mcp-bridge; ensure just install/just ci include it.
just/opencode.just (or a new recipe): add just sandbox-serve mirroring opencode-serve (source .env, export OPENCODE_SERVER_PASSWORD, default OPENCODE_URL/SANDBOX_PORT, run npm run dev --prefix tools/trap-sandbox).
docs/public-ports.md: add a 4444 row (note it sits outside the 4242–4244 range; 4244 reserved).

Test layout

test-integration/   # harness.ts (app on :0, startCraftos, fake-opencode http server) + lua/ + *.test.ts

TS integration (`tools/trap-sandbox/test-integration`, real craftos ↔ real gateway, serialized)

Self-contained gateway-client.lua for the health round-trip (opencodeOk true/false via the fake-opencode server), reverse ping via registry.request, duplicate (newest-wins), and the auth canary — wrong secret asserts in-band hello ok:false code:"unauthorized", correct secret asserts hello ok:true.

Full-boot e2e (TS integration)

craftos --exec replicates boot (set sandbox.url, _G.bootEventLoop, run real servers/sandbox, then under parallel wait for trapos_sandbox_connected and run sandbox health); assert stdout contains sandboxOk: true. Bounded by generous timeouts.

Verification gate (also the project-level acceptance)

npm test, npm run test:integration, npm run lint/check clean in tools/trap-sandbox.
just _craftos-test runs tests/sandbox.lua; just ci covers both tools.
Manual: just sandbox-serve; in-game set sandbox.url ws://<host>:4444/gateway (+ set sandbox.password <secret> if SANDBOX_PASSWORD set), reboot, sandbox health → sandboxOk: true / opencodeOk: ….

2.7 KiB Raw Blame History Unescape Escape