guillaumearm/cc-libs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
c7ba641e2d
cc-libs/CLAUDE.md
Guillaume ARM c7ba641e2d test(craftos): add suite runner
2026-06-08 05:10:31 +02:00

3.3 KiB
Raw Blame History

CLAUDE.md

Concise guidance for agents working in this repository.

Project

ComputerCraft / CC:Tweaked Lua APIs, servers, and programs for Minecraft 1.21. Code runs in the ComputerCraft sandbox, not standard Lua.

Use docs/README.md as the entrypoint for CC:Tweaked, CraftOS-PC, Advanced Peripherals, and Create integration documentation links. Use docs/adrs/README.md for repository architecture decisions.

Constraints

  • Do not add a standalone Lua test harness unless asked. Local execution happens through the CraftOS-PC harness (see docs/install-craftos-pc.md, docs/craftos_pc_glossary.md, and ADR-0005); code otherwise executes in-game.
  • Do not run just repl as an LLM agent; it is a human-only interactive CraftOS-PC wrapper. Use just craftos --headless ... for automated probes.
  • 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.
  • 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')().
  • Most API modules return factories; call the required module once before use.

Architecture

  • apis/eventloop.lua is the single-threaded event loop around os.pullEventRaw; consider using it everywhere async behavior is needed. A handler that returns api.STOP auto-unregisters.
  • apis/libtest.lua is the lightweight test helper used by scripts under tests/; /programs/runtest.lua discovers tests, renders suite output, and owns the __TRAPOS_TEST_OK__ success marker.
  • apis/net.lua builds modem packet messaging, routing, and request/response RPC on the event loop. sendRequest returns ok, result, packet and defaults to a 0.5s timeout.
  • A router (/programs/router.lua) must be running somewhere on the network; without it, packets lack routerId, isPacketOk rejects them, and cross-machine messaging silently fails.
  • servers/ listen for requests and start loops; programs/ are clients that send requests and exit.
  • Well-known channels: 9 ping, 10 router/default routing. Keep duplicated constants in sync.

Boot And Install

  • startup/servers.lua starts /programs, the shell, and configured servers via parallel.waitForAll.
  • Preserve periphemu guards used for CraftOS-PC emulation; see docs/craftos_pc_glossary.md for upstream emulator references.
  • install.lua downloads files listed in LIST_FILES from master by default, or from next with --beta; add shipped files there.
  • Add new servers to startup/servers.lua as needed.

Conventions

  • Bump local _VERSION = '...' when changing module behavior.
  • Programs support -version/--version and -help/--help; router also supports -silent/--silent.
  • French or English comments are fine; match surrounding code.
  • Commit messages use lightweight conventional style: topic(scope): description or topic: description.

See DEVELOPMENT.md for local setup.