Subcommand --help registry + shared error helper (#89, #92)#118
Merged
Conversation
Closes #89, closes #92. - Adds `cli_help.py` registry mapping each subcommand path -> description, examples, and when-to-run. A post-pass in `build_parser` walks the subparser tree and applies the registry, so every `<cmd> --help` now shows what the command does, when to run it, and 1-3 worked examples. Hidden flat aliases inherit the canonical command's documentation. - Adds `errors.py` with `fail_with(cause, next_step, link=None)` and a matching `CliError` exception. The format is three lines: cause / next / see. Wiki `Errors-and-Recovery.md` documents the style and the recurring failure modes (no AGENTS.md, missing tool, untouched .env, eval-on-empty-repo, manifest version mismatch). - Tests assert every visible subcommand has a non-empty description and at least one example block, every registry entry has examples, and the error helper preserves the three-line shape.
…nd-errors-style # Conflicts: # docs/docs/wiki/_meta.json # src/coding_scaffold/cli.py
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.
Summary
cli_help.pyregistry mapping every subcommand path to a description, when-to-run line, and 1-3 worked examples. A post-pass inbuild_parserwalks the subparser tree and applies it —coding-scaffold setup run --help(and every other subcommand) now has a real description and examples instead of bare argparse.errors.pywithfail_with(cause, next_step, link=None)so every failure path prints the same three-line shape. New wiki pageErrors-and-Recovery.mddocuments the style + recurring failure modes.init,wizard,setup-tool, …) automatically inherit the canonical command's documentation.Closes #89, closes #92.
Test plan
uv run pytest -q— 360 tests pass.tests/test_subcommand_help.pyasserts every visible subcommand has a non-empty description and example block.python -m coding_scaffold setup run --help— shows description, when-to-run, examples, and the Glossary link.Errors-and-Recovery.mdenumerates the recurring failure paths and the three-line format.