# Development

Requirements:
- `just`
- `jq`
- `luacheck`
- [CraftOS-PC](docs/install-craftos-pc.md) ≥ v2.8.3 — local harness for the CC:Tweaked sandbox; see [`docs/craftos_pc_glossary.md`](docs/craftos_pc_glossary.md) for CLI flags, mounting, `periphemu`, save data, and troubleshooting references.

After cloning the repository, run:

```sh
just install
```

This creates `.env` from `.env.sample` when needed and installs the local Git hooks, including a pre-commit hook that runs `just ci`.

`just ci` is the local verification entry point. Today it verifies that `craftos --version` reports v2.8.3 or newer, runs `just check` for `luacheck`, and runs `just test` for CraftOS-PC headless tests. Use `just craftos` to launch CraftOS-PC with repo-local save data under `.craftos` and read-only mounts for `/trapos`, `/apis`, `/programs`, `/servers`, and `/startup`. `just repl` opens the same environment with `--cli` for human interactive use only; LLM agents must not run it. Use the CraftOS-PC glossary when adjusting `--headless`, `--exec`, `--script`, `--rom`, or `--mount-*` usage.

Tests live under `tests/` and run inside CraftOS-PC through `just test`. API-level tests should use `require('/apis/libtest')({ ... })`, register cases with `testlib.test(name, fn)`, and call `testlib.run()` at the end. `libtest` prints `__TRAPOS_TEST_OK__` only when every case passes, which is the contract consumed by the shell harness. Pass `--verbose` to `just test` to list each test script; `libtest` also accepts `--verbose` and prints each case when script stdout is inspected.

Each CraftOS-PC test process is killed if it does not finish within `TRAP_CCLIBS_TEST_TIMEOUT_SECONDS`, defaulting to `3`. Override this in `.env` for slower local probes.