guillaumearm/cc-libs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
54ffe82786
cc-libs/CLAUDE.md

5.7 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 trapos --headless --exec '<lua>; os.shutdown()' for automated probes against the TrapOS dev environment, or just craftos --headless --exec '<lua>; os.shutdown()' for probes against vanilla CraftOS (no TrapOS mounts). Headless probes are the recommended way to verify hypotheses about CC:Tweaked behavior; see ADR-0012.
  • 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 docs/adrs/adr-0009-layered-test-timeouts.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 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.
  • 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.
  • 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 on master (or next with --beta), and tells users to run ccpm update then ccpm install trapos.
  • 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 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.
  • Reference other .md files (and ADR-####) with [text](path) link syntax so just lint-markdown (lychee) can validate them. See ADR-0013.

See DEVELOPMENT.md for local setup.