main
2 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
| f41ff92c67 |
docs(book): the four chapters — Phase 5 slice 2
The book, written out of the tree slice 1 proved. Four chapters in the order the
work happens: the first module in twenty minutes, the website module, the sidecar,
and the game-side plugin.
Shape, settled with the org lead:
* template/README.md stays the REFERENCE — it travels with a copied template and
CI holds it against the tree — and chapter 1 is the narration: what you should
see after each step, the state your module lands in, and the four ways it fails.
The chapter links to the checklist rather than restating it.
* chapters 3 and 4 cite link/ and servuo-plugins/ by FILE AND IDENTIFIER, never by
line. Those repositories move for their own reasons and checkLinks already
forbids commit permalinks, so a line number in this book is wrong the moment
they do. The template stays the only code quoted verbatim.
* one PR: the outline's status table and the link check are only coherent when the
whole set lands.
scripts/checkChapterPaths.js is the anti-rot half a machine can answer: every path
a chapter names in backticks must exist. None of those mentions is a markdown link,
so checkLinks never looked at them, and none is code, so nothing else did either —
renaming one template file would have left four chapters quietly pointing at
nothing. Its anchor list is STATED rather than derived from the tree, for the reason
the template's own build guard states it: a list derived from what exists cannot
fail when what exists changes, and an anchor that stops matching is a check that has
silently stopped checking. So each anchor must exist or the check fails. Eleven
tests, every "must not catch" case a span that really appears in the book.
stripFences moved to scripts/lib/markdown.js and both checks use it — shared code,
not a shared description.
CHAPTER 1 WAS RUN, NOT REASONED ABOUT. The template was copied into a real core on
edge, booted against the dev database, and every claim in "what you should see"
checked: the five log lines, /examplegame/status with its injected
<script type="module" src="/modules/examplegame/entry.js">, the chunk served
no-cache while module.json 404s, /api/v1/public/world/status, the capabilities in
/api/v1/public/modules, and the route in the merged /api/docs.json. Then the three
failures the chapter tells a reader to cause on purpose, because a chapter that
predicts the wrong debugging heuristic is worse than one that predicts none:
* an undeclared prefix -> stage `register`, "declared public/extra but never
registered it", routes 404 and absent from /public/modules;
* a table without the id prefix -> stage `schema`, at LOAD time, before mounting;
* a throwing onBoot -> after mounting, so the same route answers 503 "Module
unavailable" rather than vanishing.
All three came out exactly as written, and the messages in the chapter are that
core's own. Two small corrections fell out of the run: the log sample now shows the
real interleaving of core's three lines with the module's two, and the section on
failure adds that a module disappears from /api/v1/public/modules in every failure
case — a check that needs no login.
MODULE_SYSTEM.md 2.11.1 slice 2. Docs half: docs#146.
Co-Authored-By: Claude <noreply@anthropic.com>
|
|||
| cffd525bdf |
docs: scaffold the Integration Kit — front page, outline, and the checks
Phase 5 slice 0 (MODULE_SYSTEM.md §2.11.1). The repo's governance, the front page, the book's outline, and the CI that keeps the whole thing from rotting. README.md What the reader is building, all three parts, and the draft banner: the kit is finished when someone outside this project builds a working module by following it alone, and that has not happened. Says the sidecar rule plainly (MODULE_API.md §2.7) rather than leaving it to chapter 3, because a reader who skims the front page and starts coding should still get that one right. book/README.md The outline of four chapters, landed before the prose so the shape can be argued with. Chapters are named but NOT linked — a link to a file that does not exist is what the link check is for, and an outline should not be the first thing to fail it. CONTRIBUTING.md The rule that governs every change here: the kit never re-specifies a contract. Also the prose conventions, and why the pinned ref points at core's `edge` rather than `main`. SECURITY.md Scoped for a repo that runs nothing: the two things that ARE reportable are a template that teaches an insecure pattern (it is meant to be copied) and a chapter that teaches something dangerous. scripts/checkLinks.js Relative links resolve; anchors match a real heading; no link pins a reader to a commit snapshot of a moving document. Nothing is fetched — a self-hosted Gitea would fail on a credential-less runner and teach us to ignore red. Fences and code spans are stripped by a line walk, not a regexp. Its first run found a real one: a PR template's relative links resolve from the REPO ROOT, because that is where their text ends up when Gitea inlines them into a pull request body. Encoded, with the reason. scripts/checkCoreApi.js The anti-rot check. Asserts template/module.json's `coreApi` EQUALS the pinned core's MODULE_API_VERSION — equality, not "satisfies", because a range check stays green across a contract bump and green would then mean "the template still loads" instead of "someone has re-read the book". Both failure branches and the pass were exercised against a real core checkout. ci/core-ref.json The pin, same convention as Module-uo's. Points at `edge`: core's `main` has no server/src/modules/ until the cutover, and that pin is one of the things the cutover has to revisit. .gitea/workflows/pr-checks.yml Two jobs. `links` always runs; `template` is conditional on template/module.json existing, so the repo is gated now and the job arms itself when slice 1 lands, with no edit to the workflow. Same guard Module-uo used through its planning phase. Co-Authored-By: Claude <noreply@anthropic.com> |
