diff --git a/CLAUDE.md b/CLAUDE.md index c5b4cbe..e686897 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,6 +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`. - 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 fc001bb..a551658 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -12,9 +12,11 @@ After cloning the repository, run: 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`. +This creates `.env` from `.env.sample` when needed and installs the local Git hooks: pre-commit runs `just test`, and pre-push 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. +`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. 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. + +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. diff --git a/Justfile b/Justfile index 2ba041f..68ee037 100644 --- a/Justfile +++ b/Justfile @@ -1,5 +1,5 @@ # Justfile for cc-libs -# Run `just ci` to verify local tooling and lint Lua code. +# Run `just ci` for full local verification. # List available recipes. default: @@ -18,9 +18,12 @@ init-env: # Install Git hooks for this repository. install-git-hooks: @mkdir -p .git/hooks - @printf '%s\n' '#!/bin/sh' '' 'just ci' > .git/hooks/pre-commit + @printf '%s\n' '#!/bin/sh' '' 'just test' > .git/hooks/pre-commit @chmod +x .git/hooks/pre-commit @printf '%s\n' 'Installed .git/hooks/pre-commit' + @printf '%s\n' '#!/bin/sh' '' 'just ci' > .git/hooks/pre-push + @chmod +x .git/hooks/pre-push + @printf '%s\n' 'Installed .git/hooks/pre-push' # Verify the CraftOS-PC harness is installed and recent enough. check-craftos: diff --git a/docs/adrs/README.md b/docs/adrs/README.md index 7a52098..1c946e7 100644 --- a/docs/adrs/README.md +++ b/docs/adrs/README.md @@ -18,3 +18,4 @@ Future ADRs can reuse the shape of the existing files when it is useful. - [`adr-0008-keep-tests-runnable-in-craftos-and-in-game.md`](adr-0008-keep-tests-runnable-in-craftos-and-in-game.md) - Keep tests runnable in CraftOS and in-game. - [`adr-0009-layered-test-timeouts.md`](adr-0009-layered-test-timeouts.md) - Layered test timeouts (libtest per-case + shell watchdog). - [`adr-0010-ccpm-package-manager.md`](adr-0010-ccpm-package-manager.md) - ccpm package manager (packages, registries, package-aware bootstrap). +- [`adr-0011-git-hooks-own-commit-push-verification.md`](adr-0011-git-hooks-own-commit-push-verification.md) - Git hooks own commit/push verification. diff --git a/docs/adrs/adr-0011-git-hooks-own-commit-push-verification.md b/docs/adrs/adr-0011-git-hooks-own-commit-push-verification.md new file mode 100644 index 0000000..cea038e --- /dev/null +++ b/docs/adrs/adr-0011-git-hooks-own-commit-push-verification.md @@ -0,0 +1,49 @@ +# ADR 0011: Git Hooks Own Commit/Push Verification + +## Status + +Accepted + +## Date + +2026-06-08 + +## Context + +The repository already has a CraftOS-PC harness (`just test`) and a fuller local CI path +(`just ci`) that adds tool checks, `luacheck`, and harness regression guards. Agents and +humans can also be asked to commit and push changes, which means verification can happen in +two places: manually before Git operations and automatically inside Git hooks. + +Running the same tests manually and then again in hooks makes commit/push workflows slower +without improving the success contract. It also risks divergent habits between human and +agent workflows if agents run one verification path and hooks run another. + +## Decision + +Install two local Git hooks through `just install` / `just install-git-hooks`: + +- `.git/hooks/pre-commit` runs `just test`. +- `.git/hooks/pre-push` runs `just ci`. + +When an agent is explicitly asked to commit and/or push, it should not run `just test` +manually before the Git operation. The hook is the source of truth for that workflow: +commit triggers `just test`, and push triggers `just ci`. + +Manual verification is still appropriate outside commit/push workflows. For example, run +`just test` while developing a behavior change, and run `just ci` when checking the full +local state without pushing. + +## Consequences + +- Commit and push verification is consistent for humans and agents. +- Commit workflows avoid duplicating the same CraftOS-PC test run before and during + `git commit`. +- Push workflows still get the full local CI gate before remote updates. +- The hooks are local files under `.git/hooks`, so developers should run `just install` + after cloning or after hook behavior changes. + +## Future Work + +- Revisit the split if `just test` becomes too slow for pre-commit or `just ci` gains + checks that should also block commits.