diff --git a/CLAUDE.md b/CLAUDE.md index 469b7ae..53b84b9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,7 +15,7 @@ Use `docs/README.md` as the entrypoint for CC:Tweaked, CraftOS-PC, Advanced Peri - When changing behavior, add as many useful CraftOS-PC tests as practical. It is acceptable to skip tests that require human-only validation, such as complex turtle motion, in-game UX feel, or visual approval, but still add unit-style non-regression tests for deterministic parts when possible. - Use `/apis/libtest.lua` for test scripts under `tests/`; `/programs/runtest.lua` prints `__TRAPOS_TEST_OK__` only after the suite passes. - `libtest` cancels each case after `3`s (`--timeout ` / `--no-timeout` to override); never commit a hanging test to `tests/`. Slow harness fixtures go in `tests/harness/` behind dedicated recipes. See `docs/adrs/adr-0009-layered-test-timeouts.md`. -- Git hooks own commit/push verification: pre-commit runs `just test`, and pre-push runs `just ci`. When explicitly asked to commit and/or push, do not run `just test` manually first; rely on the hooks. See `docs/adrs/adr-0011-git-hooks-own-commit-push-verification.md`. +- Git hooks own commit/push verification: pre-commit runs `just check test`, and pre-push runs `just ci`. When explicitly asked to commit and/or push, do not run `just test` manually first; rely on the hooks. See `docs/adrs/adr-0011-git-hooks-own-commit-push-verification.md`. - After editing Lua, run `just check` and fix all `luacheck` warnings. - Use 2-space indent, semicolons, and `local function`. - `require` paths are absolute ComputerCraft paths, for example `require('/apis/net')()`. diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index d13a2f7..439f29e 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,28 +1,13 @@ # 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. +## Installation -After cloning the repository, run: +Install `just`, `jq`, `luacheck`, `openssl`, and [CraftOS-PC v2.8.3+](docs/install-craftos-pc.md), then run: ```sh -just install +just install trapos-install && echo ok ``` -This installs the local Git hooks: pre-commit runs `just test`, and pre-push runs `just ci`. +This installs local Git hooks, checks required tools, generates `.env`, and verifies a full TrapOS install on a fresh CraftOS-PC state. -`just ci` is the full local verification entry point. Today it verifies that `craftos --version` reports v2.8.3 or newer, runs `just check` for `luacheck`, runs `just test` for CraftOS-PC headless tests, and runs the harness timeout regression guard. Three launch recipes wrap CraftOS-PC: `just trapos` launches the TrapOS dev environment with repo-local save data under `.craftos` and read-only mounts for `/trapos`, `/apis`, `/programs`, `/servers`, and `/startup`; `just craftos` launches a vanilla CraftOS-PC under `.craftos-vanilla` with no mounts (useful when a probe should not see TrapOS files, or to confirm a behavior is upstream); and `just trapos-install` exercises the real ccpm bootstrap (`install-ccpm.lua` → `ccpm update` → `ccpm install trapos`) end-to-end on a fresh ephemeral state. `just repl` opens the TrapOS dev environment with `--cli` for human interactive use only; LLM agents must not run it. `--headless --exec '; os.shutdown()'` against either `just trapos` or `just craftos` is the canonical way to verify a hypothesis about CC:Tweaked behavior before writing code or tests — see [`docs/adrs/adr-0012-headless-craftos-pc-as-hypothesis-probe.md`](docs/adrs/adr-0012-headless-craftos-pc-as-hypothesis-probe.md). Use the CraftOS-PC glossary when adjusting `--headless`, `--exec`, `--script`, `--rom`, or `--mount-*` usage. - -When asking an agent to commit and/or push, rely on these hooks instead of duplicating `just test` manually before Git operations: pre-commit owns `just test`, and pre-push owns `just ci`. Manual `just test` and `just ci` remain appropriate when validating changes outside a commit/push workflow. - -Tests live under `tests/` and run inside CraftOS-PC through `just test`, which launches `/programs/runtest.lua`. API-level tests should use `require('/apis/libtest')({ ... })`, register cases with `testlib.test(name, fn)`, and call `testlib.run()` at the end. `libtest` tests remain normal ComputerCraft programs; the runner handles suite discovery, grouped output, and the `__TRAPOS_TEST_OK__` shell success contract. Pass `--pretty` to `just test` for grouped colored `[OK]`/`[KO]` statuses, or `--verbose` for additional runner/debug detail. - -Test timeouts run in two independent layers (see [`docs/adrs/adr-0009-layered-test-timeouts.md`](docs/adrs/adr-0009-layered-test-timeouts.md)): - -- **libtest per-case timeout (primary).** Each `libtest` case is cancelled after `3` seconds by default, failing with a distinct `libtest timeout` message. Override with `--timeout `, or disable with `--no-timeout` (both forwarded by `runtest` to each case). This catches a single hung case quickly without taking down the whole run. -- **Shell watchdog (backstop).** The whole CraftOS-PC process is killed if it does not finish within `TRAP_CCLIBS_TEST_TIMEOUT_SECONDS` (`.env.test` ships `3`; the recipe falls back to `3`). Keep it at or above the `3`s libtest default so libtest fires first; the watchdog only catches what Lua cannot interrupt. Override in your shell for slower local probes. - -`just test-timeout` is a self-asserting regression guard for these layers and runs automatically as part of `just ci`. It chains `just test-timeout-lua` (proves libtest cancels a slow case immediately with `--timeout 0`, before the shell backstop) and `just test-timeout-shell` (proves the `TRAP_CCLIBS_TEST_TIMEOUT_WATCHDOG_SECONDS` watchdog, default `1`, kills a slow case run with `--no-timeout`). Both drive the `tests/harness/slow-case.lua` fixture, which is never picked up by the normal `just test` suite (`runtest` skips `tests/` subdirectories). +See [`docs/README.md`](docs/README.md) for repository docs and [`docs/adrs/README.md`](docs/adrs/README.md) for architecture decisions. diff --git a/README.md b/README.md index a42cf32..ed7db27 100644 --- a/README.md +++ b/README.md @@ -84,4 +84,4 @@ Servers listed in `manifest.autostart` are launched at boot by `startup/servers. - `upgrade`: alias for `ccpm upgrade`. ## Development -See [DEVELOPMENT.md](./DEVELOPMENT.md) for development setup and workflow. +See [DEVELOPMENT.md](./DEVELOPMENT.md) for local development installation. diff --git a/docs/adrs/adr-0005-craftos-pc-harness.md b/docs/adrs/adr-0005-craftos-pc-harness.md index 8148a6e..3e4ebd2 100644 --- a/docs/adrs/adr-0005-craftos-pc-harness.md +++ b/docs/adrs/adr-0005-craftos-pc-harness.md @@ -26,10 +26,10 @@ Treat CraftOS-PC as a first-class local development dependency. - **Minimum version `v2.8.3`** — recent enough to have the current CC:Tweaked ROM, old enough that contributors already on a 2.8.x build will not be forced to upgrade again immediately. - **Documented install** in [`docs/install-craftos-pc.md`](../install-craftos-pc.md), with a SHA-256-verified macOS flow and pointers to the official Windows/Linux artifacts. - **Documented upstream navigation** in [`docs/craftos_pc_glossary.md`](../craftos_pc_glossary.md), covering CLI flags, mounts, `periphemu`, save data, and troubleshooting pages. -- **Verified by `just install`** via `check-install`, which checks `craftos`, `jq`, and `luacheck`. `check-craftos` runs `craftos --version` and requires v2.8.3 or newer. Failure prints a one-line pointer to the install guide instead of a long stack trace. +- **Verified by `just install`** via `check-install`, which checks `craftos`, `jq`, `luacheck`, and `openssl`. `check-craftos` runs `craftos --version` and requires v2.8.3 or newer. Failure prints a one-line pointer to the install guide instead of a long stack trace. - **Repository-local launch recipe.** `just trapos` runs CraftOS-PC with `--directory .craftos`, keeps the macOS `--rom /Applications/CraftOS-PC.app/Contents/Resources` workaround, mounts the repository root read-only at `/trapos`, and mounts each manifest top-level directory read-only at its ComputerCraft root path. (Originally `just craftos`; renamed when a separate vanilla-emulator recipe was added — see ADR-0012.) - **Vanilla launch recipe.** `just craftos` launches CraftOS-PC under `.craftos-vanilla/` with no mounts, for probes that should not see TrapOS files and for the `just trapos-install` end-to-end install verification. See ADR-0012. -- **`just ci` is the local verification entry point.** Today it runs `check-craftos`, `check`, and `test`. The installed pre-commit hook invokes `just ci` directly, and `just test` owns CraftOS-PC-driven integration tests. +- **`just ci` is the local verification entry point.** Today it runs `check-craftos`, `check`, and `test`. Local Git hooks are installed by `just install`; see [ADR-0011](adr-0011-git-hooks-own-commit-push-verification.md) for the current commit/push split. The existing `CLAUDE.md` constraint ("Do not run Lua locally or add a test harness unless asked") is reframed rather than removed: there is still no standalone Lua harness, and we are not adding a Busted-style test runner. The harness *is* CraftOS-PC, invoked deliberately. diff --git a/docs/adrs/adr-0012-headless-craftos-pc-as-hypothesis-probe.md b/docs/adrs/adr-0012-headless-craftos-pc-as-hypothesis-probe.md index e259b0d..a3f25c4 100644 --- a/docs/adrs/adr-0012-headless-craftos-pc-as-hypothesis-probe.md +++ b/docs/adrs/adr-0012-headless-craftos-pc-as-hypothesis-probe.md @@ -74,7 +74,7 @@ Conventions: - Faster convergence on correct fixes: agents stop committing speculative changes that pass `luacheck` but fail in-game. - A named pattern (`--headless --exec '; os.shutdown()'`) shows up in `CLAUDE.md` and - `DEVELOPMENT.md`, so contributors and agents reach for it without rediscovery. + `docs/install-craftos-pc.md`, so contributors and agents reach for it without rediscovery. - `.craftos-vanilla/` is added to `.gitignore` alongside `.craftos/`. - `just trapos-install` is *not* part of `just ci`: it is network-dependent and slower than `just test`. Run it manually when touching `install-ccpm.lua` or ccpm package diff --git a/docs/install-craftos-pc.md b/docs/install-craftos-pc.md index 50298ee..fded105 100644 --- a/docs/install-craftos-pc.md +++ b/docs/install-craftos-pc.md @@ -4,7 +4,7 @@ CraftOS-PC is the local harness used to run this repo's Lua outside of Minecraft CraftOS-PC is the emulator; `craftos` is the command-line executable it installs. For the broader upstream documentation index, see [`craftos_pc_glossary.md`](craftos_pc_glossary.md). -Minimum version: **v2.8.3**. `just install` runs `craftos --version` to verify it is on `$PATH` and recent enough; it also checks that `jq` and `luacheck` are installed. +Minimum version: **v2.8.3**. `just install` runs `craftos --version` to verify it is on `$PATH` and recent enough; it also checks that `jq`, `luacheck`, and `openssl` are installed. The upstream installation page is . The notes below pin the version we test against and add a SHA-256 verification step.