#397 docs: audit and document every CLI exit code (closes #193)

[Anonymous]

Originally created by: Maqbool61

What

Closes [#193].

One file changed, no behaviour changed: docs/CLI.md gains an "Exit codes"
section.

Audit

grep -n "typer.Exit(code=" src/doberman/cli/main.py returns 42 call sites
(the issue body said 44; the count reflects the state at merge time — a couple
of sites were removed since the issue was written).

All 42 use code=1 or code=2. No collisions found:

• 2 — always a bad-input / usage error: the argument or option value is
  invalid before any I/O or gate check runs (serve with no downstream command,
  mode with an unknown name, enforcement with an unknown state, prefs with
  a missing or invalid value).
• 1 — always an operation failure: gate denied, runtime error, missing
  optional dependency, or partial-success with errors.

Breaking changes

None. No exit-code values were changed. This PR is documentation only.

Validation

grep -n "typer.Exit(code=" src/doberman/cli/main.py   # 42 sites, all in table
python -m pytest                                        # 2978 passed
ruff check .                                            # all checks passed

[Anonymous]

Ticket changed by: fu351

• status: open --> closed

[Anonymous]

Originally posted by: fu351

Merged, and thank you for this one. The audit is the real value here: 42 call sites checked, every one landing on 1 or 2, and writing down the split (1 = something failed, 2 = bad input caught before any state is touched) turns a fuzzy convention into something a script can actually branch on. That is exactly what [#193] was after.

One thing I fixed on your branch before merging, so you know what changed and why. GitHub's GFM renderer keeps a table "open" until it hits a blank line, and the diff had stripped the blank line after the Core-commands and Machine-readable-flags tables. So the sentence right after each one ("Global option..." and "When both are passed...") was being pulled in as a stray table row. I put one blank line back after each of those two tables and confirmed against GitHub's own renderer that the prose renders as its own paragraph again. Only those two lines; the audit content is all yours. Worth watching for next time: an editor that trims surrounding blank lines is a common way a clean docs edit picks up a rendering surprise.

If you want another in the same vein, #409 (a small docs/ index page, good first issue) is a natural companion to the CLI reference you have been shaping here. Thanks again.

[Anonymous]

Originally posted by: Maqbool61

Merged, and thank you for this one. The audit is the real value here: 42 call sites checked, every one landing on 1 or 2, and writing down the split (1 = something failed, 2 = bad input caught before any state is touched) turns a fuzzy convention into something a script can actually branch on. That is exactly what [#193] was after.

One thing I fixed on your branch before merging, so you know what changed and why. GitHub's GFM renderer keeps a table "open" until it hits a blank line, and the diff had stripped the blank line after the Core-commands and Machine-readable-flags tables. So the sentence right after each one ("Global option..." and "When both are passed...") was being pulled in as a stray table row. I put one blank line back after each of those two tables and confirmed against GitHub's own renderer that the prose renders as its own paragraph again. Only those two lines; the audit content is all yours. Worth watching for next time: an editor that trims surrounding blank lines is a common way a clean docs edit picks up a rendering surprise.

If you want another in the same vein, #409 (a small docs/ index page, good first issue) is a natural companion to the CLI reference you have been shaping here. Thanks again.

Thank you for the merge and the GFM table tip — I'll keep an eye on blank lines
around tables in future docs edits.

For the next one I'd like to pick up a coding issue rather than documentation.
Would you be able to point me toward a level-5 or level-6 coding issue, or is
there one in the backlog you think would be a good fit after the audit/sink work
I've been doing?