52 lines
2.8 KiB
Markdown
52 lines
2.8 KiB
Markdown
# 04 — Integration & tooling
|
||
|
||
> Sub-plan of [trap-sandbox-gateway-spec](./trap-sandbox-gateway-spec.md). **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
|
||
- [x] `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.
|
||
(Symmetric per-tool recipes; `npm-trap-sandbox-ci` removed.)
|
||
- [x] **`just sandbox-serve`** added in new `just/sandbox.just` (warn-only on missing secret).
|
||
- [x] `docs/public-ports.md`: added a `4444` row.
|
||
- [x] TS integration harness + cases (`tools/trap-sandbox/test-integration/`).
|
||
- [x] Full-boot e2e.
|
||
- [x] 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` (origin only —
|
||
libsandbox appends `/gateway`) (+
|
||
`set sandbox.password <secret>` if `SANDBOX_PASSWORD` set), reboot, `sandbox health` →
|
||
`sandboxOk: true` / `opencodeOk: …`.
|