docs: generate README's command table from the schema (PRD 0006 R13) - #260
Merged
Conversation
The README described the CLI from memory. Nothing connected its command
listings to the table the dispatcher actually reads, so a renamed verb
stayed documented and a new one stayed invisible — the same drift that had
already happened inside `moshcode help` itself.
Generated rather than checked, which R13 offers as the alternative and is
the better half of it: a checker tells you the README is wrong, a generator
makes it right. `moshcode help --markdown` emits the table, and it goes
between markers in README.md exactly like the PRD index this repo already
maintains, so the convention is one people here already know.
Three tests, in both directions:
- the table is regenerated and compared, so adding a verb without
regenerating fails with the command that fixes it;
- every command named in the table resolves in the schema;
- every `moshcode <verb>` invoked in a fenced code block anywhere in the
README is a real command, engine or tool. Scoped to fenced blocks
because the prose also contains sentences like "moshcode warns you",
and a grep that cannot tell those apart is a test nobody trusts.
Verified the guard bites: adding a command to the schema without
regenerating fails the suite, and the failure names `moshcode help
--markdown` as the fix.
1089 tests, 877 pass, 0 fail.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
vu1nz Security ReviewNOT RUN — Add |
ThreatCrush Security Scan87 finding(s) HIGH/CRITICAL: 50 | MEDIUM: 37
…and 37 more. Full results in the Security tab. Snippets are redacted; ThreatCrush never prints matched credential material. |
#263) The tail of PRD 0006 — R14, R15, R16. R14. `moshcode help ask` answered "no help for ask". `ask()` is as much part of the interface as `moshcode prd`, but the vocabulary lives in a registry help had never been introduced to. Verbs now carry an optional `usage` — `ai(prompt, { engine })`, `ask(...prompt)` — and help renders it with the summary and a note that this one is called from a .mosh file, not a shell. `usage` stays optional, so a verb registered by a host that has not declared one still renders as `name(…)`. cliVerb() derives its own signature rather than repeating it twenty times: every CLI verb forwards its arguments to `moshcode <name>`, so adding a line to the vocabulary documents it. R15 turned out to be already true and is now nailed down. src/ui.mjs gates colour on `NO_COLOR == null && process.stdout.isTTY`, so both the CLI and the pit already emit plain text to a pipe. Three tests keep it that way, including one for the pit — which needs spawnSync rather than the execFile helper the rest of the file uses, because the pit reads stdin and execFile has no way to supply it. Nothing paginates. R16. `moshcode help <tab>` now completes topics, in all four shells. The list is what help itself accepts — commands, engines, tools and moshscript verbs — so tab-completion and help cannot disagree about what is answerable. A test asserts exactly that: every offered topic resolves. 1099 tests, 887 pass, 0 fail. That closes PRD 0006. R1–R16 are implemented across #257, #258, #260 and this. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follows #257 (CLI help) and #258 (the pit's
/help). Same drift problem, third surface.The problem
The README described the CLI from memory. Nothing connected its command listings to the table the dispatcher actually reads, so a renamed verb stayed documented and a new one stayed invisible — exactly the drift that had already happened inside
moshcode helpitself.Generated, not checked
R13 offers either "checked against the schema by a test" or "generated from it via
moshcode help --markdown". I did the generator, because a checker tells you the README is wrong and a generator makes it right.The table lives between
<!-- COMMANDS:START -->/<!-- COMMANDS:END -->markers — the same convention this repo already uses for the PRD index, so it's one people here already know.Three tests, both directions
moshcode <verb>invoked in a fenced code block anywhere in the README is a real command, engine or tool — this is the one that catches a rename, since the examples are scattered across 480 lines.Test 3 is scoped to fenced blocks deliberately: the prose contains sentences like "moshcode warns you" and "moshcode doesn't reinvent the agent", and a grep that can't tell those from invocations is a test nobody trusts and everyone eventually deletes.
Verified the guard bites
I added a fake
brandnewverbto the schema without regenerating, and confirmed the suite fails:Then restored the schema — the only change to
cli-schema.mjsin this PR is documenting the new--markdownflag.Tests
4 new (32 in
test/help.test.mjs). Full suite: 1089 tests, 877 pass, 0 fail.Remaining from PRD 0006, all P2: R14 (moshscript verb help —
moshcode help ai), R15 (NO_COLOR), R16 (completing help topics).🤖 Generated with Claude Code