cc-libs/AGENTS.md

AGENTS / 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 trapos-exec '<lua>' for automated probes against the TrapOS dev environment, or just craftos-exec '<lua>' for probes against vanilla CraftOS (no TrapOS mounts). These wrappers shut down the machine and include a host watchdog. Headless probes are the recommended way to verify hypotheses about CC:Tweaked behavior; see ADR-0005.
• 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 3s (--timeout <s> / --no-timeout to override); never commit a hanging test to tests/. Slow harness fixtures go in tests/harness/ behind dedicated recipes. See ADR-0007.
• 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 ADR-0011.
• After editing Lua or Markdown, run just check and fix all luacheck warnings and lychee broken-link reports (markdown link validation is offline-only via just lint-markdown).
• 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.
• startup/servers.lua creates a single boot eventloop at _G.bootEventLoop and runs it alongside the shell via parallel.waitForAny. Servers register handlers on it and return; programs call services via os.pullEvent without touching the loop. See ADR-0002.
• 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 is a service-name bus on a single channel (10). net.serve(name, handler) registers a server handler; net.call(name, payload, { destId, timeout }) and net.send(name, payload, { destId }) are the client surface. require('/apis/net')() returns a singleton bound to _G.bootEventLoop when present, otherwise an ephemeral instance.
• A router (/programs/router.lua) must be running somewhere on the network; it registers a modem_message handler that stamps routerId, resolves label-addressed packets via a TTL map populated by servers/net-registrar.lua, and rebroadcasts. Without it, packets stay unrouted and consumers ignore them.
• servers/ register handlers on the boot eventloop and return; programs/ are clients that exit.
• Single well-known channel: 10 (the bus). Service multiplexing happens inside the packet body.

Boot And Install

• startup/servers.lua creates the boot eventloop, runs autostart server files (which register handlers and return), then runs the shell and the eventloop in parallel via parallel.waitForAny.
• Preserve periphemu guards used for CraftOS-PC emulation; see docs/craftos_pc_glossary.md for upstream emulator references.
• TrapOS ships as packages, each described by packages/<name>/ccpm.json (name, version, dependencies, files, autostart); packages/index.json lists them. Source files stay in place — descriptors only reference them. To ship a new file, add it to the right package's files (and autostart if it is a server). packages/trapos/ccpm.json is the full OS meta-package. See ADR-0010.
• install-ccpm.lua is the one-time wget bootstrap. It installs only trapos-core/ccpm, seeds the default guillaumearm/cc-libs registry as a gitea registry on git.trapcloud.fr tracking master (or next with --beta), and tells users to run ccpm update then ccpm install trapos. The legacy github registry type still resolves but is deprecated.
• ccpm (in trapos-core) is the package manager: apis/libccpm.lua is the testable core (factory with injectable http/stateDir/installRoot), programs/ccpm.lua the CLI. State: /trapos/ccpm.json (registries), /trapos/ccpm.lock.json (installed packages), and /trapos/ccpm.cache.json (available packages from ccpm update). Never use the word "manifest" in ccpm — it is reserved for the OS manifest.
• Add new servers to startup/servers.lua as needed.

Conventions

• Bump the owning packages/<name>/ccpm.json version (and mirror it in packages/index.json) when changing module behavior; programs report it at runtime via require('/apis/libversion')().forSelf(). install-ccpm.lua is the only file that still carries its own _VERSION because it is the wget bootstrap and lives outside the package system.
• 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.
• Reference other .md files (and ADR-####) with [text](path) link syntax so just lint-markdown (lychee) can validate them. See ADR-0011.

See DEVELOPMENT.md for local setup.