feat(tui): the pit's /help renders from the schema too (PRD 0006 R12) - #258
Merged
Conversation
The pit had the CLI's problem in a second copy. `printHelp()` typed out
`/railway /gh /supabase /doppler /doctl /turso /tailscale` by hand,
immediately below a `printTools()` whose own comment explains why
hardcoding the roster goes stale — and it had already gone stale in three
ways at once:
- `/logout` has been dispatched since it was added and appeared nowhere
in `/help`.
- the moshscript verb list missed `ai()` and `shell()`, both in the
vocabulary the pit itself injects.
- nothing said that `/dns`, `/console`, `/completion` and `/uninstall`
do not exist here at all, so their absence read as an oversight rather
than a fact about the pit.
Now: PIT_COMMANDS in the schema, rendered by src/help.mjs, with the tool
and engine rosters and the moshscript vocabulary all derived. A drift test
scrapes `cmd === "…"` out of the pit's own loop and fails when a
dispatched verb has no help — the same guard the CLI got, pointed at the
other dispatcher.
`/help <command>` and `/<command> --help` both work, and per-command detail
delegates to the CLI block so flags and examples are written once. That
also closes the pit's copy of the sharp edge: `/prd --help` prints usage
instead of publishing a PRD.
Absent commands are named rather than silently missing. R12 lists
`/uninstall` among the omissions to add, but the pit does not dispatch it
— so it goes in the "not in the pit" line, which is what the same
requirement asks for two sentences later.
Rosters wrap at 80 columns on the bare strings, before colour: measuring a
string that already carries ANSI escapes counts the escapes as width and
wraps far too early.
1085 tests, 873 pass, 0 fail.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
vu1nz Security ReviewNOT RUN — Add |
ThreatCrush Security Scan0 finding(s) No findings. |
This was referenced Aug 3, 2026
Merged
ralyodio
added a commit
that referenced
this pull request
Aug 3, 2026
#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>
ralyodio
added a commit
that referenced
this pull request
Aug 3, 2026
…260) * docs: generate README's command table from the schema (PRD 0006 R13) 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> * feat(help): moshscript verbs, terminal manners, and completable topics (#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> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
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.
The last hardcoded roster. Follows #257, which did R1–R11 for the CLI.
What was stale
printHelp()insrc/tui.mjstyped out/railway /gh /supabase /doppler /doctl /turso /tailscaleby hand — immediately below aprintTools()whose own comment explains why hardcoding the roster goes stale. It had already gone stale in three ways at once:/logouthas been dispatched since it was added and appeared nowhere in/help.ai()andshell(), both in the vocabulary the pit itself injects./dns,/console,/completionand/uninstalldon't exist here at all, so their absence read as an oversight rather than a fact about the pit.What changed
PIT_COMMANDSin the schema, rendered bysrc/help.mjs, with the engine roster, tool roster and moshscript vocabulary all derived. A drift test scrapescmd === "…"out of the pit's own loop and fails when a dispatched verb has no help — the same guard the CLI got in #257, pointed at the other dispatcher./help <command>and/<command> --helpboth work now. Per-command detail delegates to the CLI block, so flags and examples are written once and can't diverge between the two surfaces. That also closes the pit's copy of the sharp edge:/prd --helpprints usage instead of publishing a PRD.One place I read R12 against its own example
R12 lists
/uninstallamong the omissions to add to/help— but the pit doesn't dispatch it. Adding it to the command list would imply it exists, which the same requirement forbids two sentences later ("where a CLI command has no pit equivalent,/helpMUST say so rather than imply it exists"). So it's in the "not in the pit" line. There's a test asserting nothing can appear in both lists.Detail worth flagging
Rosters wrap at 80 columns measured on the bare strings, before colour. Measuring a string that already carries ANSI escapes counts the escapes as width and wraps far too early — the reason the wrap helper takes the items rather than the rendered line.
Tests
6 new (28 total in
test/help.test.mjs). Full suite: 1085 tests, 873 pass, 0 fail.Remaining from the PRD after this: R13 (README drift test), R14–R16 (moshscript verb help,
NO_COLOR, help-topic completion) — all P1/P2.🤖 Generated with Claude Code