Repository navigation
CLI help keeps its placeholders: ferro migrate --help prints <name>, <migration>:<step> and the rest #702
Description
Parent
What to build
ferro migrate rerecord --help prints "The step whose edit to accept: :, as 0007:01." because help text is rendered as Markdown and <migration>:<step> is swallowed as an HTML tag. Seven help strings lose their placeholders (new, squash, rerecord and others).
Help renders as plain text on both the root app and the migrate app, so every placeholder prints as written. A test pins it.
Acceptance criteria
-
ferro migrate rerecord --helpprints<migration>:<step>. -
ferro migrate new --helpandferro migrate squash --helpprintNN_<name>.up.sql-style placeholders intact. - Every
<...>placeholder written in any command's help source appears verbatim in that command's--helpoutput (pinned by the new test). - No other help text changes rendering (headings, option tables, defaults render as before).
Files owned
- Create:
tests/test_cli_help.py - Modify:
src/ferro/cli/__init__.py,src/ferro/cli/migrate.py
Interfaces
- Consumes: nothing from other tickets
- Produces:
tests/test_cli_help.py: one parametrized test over everyferrocommand asserting each<placeholder>in the help source appears in--helpoutput. The migrations-API docstring ticket (Docstrings: the migrations API, PassReport and the CLI commands #721) keeps it green when it rewrites help text.
Test scenarios
- Happy path:
ferro migrate rerecord --helpoutput contains<migration>:<step>. - Edge case: a help string with two placeholders on one line keeps both.
- Error path: switching the help format back to Markdown makes the test fail for
rerecord,newandsquash.
Verify
uv run --no-sync pytest tests/test_cli_help.py -q --no-cov -p no:cacheprovider
uv run --no-sync ferro migrate rerecord --help | grep -F '<migration>:<step>'Blocked by
None (can start immediately)
Audit findings
Rows from the docs audit this ticket covers (file, line, rule, fix)
src/ferro/cli/ — main, render_refusal, Global, and ferro migrate <verb> --help
- Kind: reference (help text)
- Verdict: the verb summaries are the most consistent prose in scope: all infinitive, one line, and exit codes stated (
check0/3,status0/3/4,drift0/4). One rendering defect wipes out the placeholder in seven help strings. C (B once the H is fixed)
| Sev | Line | Rule | Finding | Suggested fix |
|---|---|---|---|---|
| H | migrate.py 170, 179, 198, 210, 222, 270, 280, 289, 308, 690 | 8, 22 | cyclopts renders help as Markdown, which drops <name>, <model>, <table>.<column>, <migration>:<step> as HTML tags. The real output reads "writes NNNN_/", "SQL step NN_.up.sql", "data step NN_backfill_.py", "this column (., repeatable)", and for rerecord: "The step whose edit to accept: :, as 0007:01." |
Set help_format="plaintext" (or "rich") on both Apps, or wrap placeholders in backticks. Add a test that asserts <name> survives in --help. |
| M | migrate.py 210–213 | 15 | --replace help ends "…carrying its data steps and hand-written SQL steps across: two branches that each generated the same number." The use case comes after the colon as a fragment. |
Put the condition first: "When two branches generated the same number, regenerate this migration…". |
| L | status --help |
22 | --steps --no-steps and --json --no-json show negative flags, while every other boolean sets negative="" (--verbose, --data-only, --all). |
negative="" on both. |
| L | new/squash --help |
— | An extra blank line after the summary, and a blank line after --no-backfill STR... and rerecord's TARGET. Both are side effects of the same Markdown parsing. |
Fixed by the plaintext format. |
| L | cli/init.py 1–20, 42, 53 | 22 | Module/Global/render_refusal docstrings use :func:/:data:/:class: roles and "(ADR-0036: …)". No API page renders them, so this is low impact. |
Convert if they are ever rendered. |
| L | ferro --help |
22 | "ferro's command line: schema migrations for ferro models." starts lowercase. Docstrings elsewhere say "Ferro" in prose (33×) and "ferro" (≈400× incl. code). | Pick one prose capitalisation for the product name. |
Activity
0x054 commentedon Oct 19, 2026
Status: verify-passed
Worker: sdd worker
Branch:
sdd/702-cli-help-placeholdersPR: #726
Verify: passed 57ea0c6
Review: spec PASS, quality PASS. One Minor:
squashhelp prints literal backticks aroundnewunder plaintext. Trial merge not run (base unchanged).fix(cli): keep <placeholders> in --help (#702) (#726)
0x054 commentedon Oct 19, 2026
Merged in #726 into
feat/docs-rewritedocs(api): migrations, pass report and CLI docstrings as Google-style…
docs: every page one kind, every block runs, the SQL beside every que…