fix: make every script pass the --help gate AGENTS.md documents #6

Merged

nugget merged 1 commit from fix/help-gate into main

2026-08-21 14:24:33 -05:00

claude commented

2026-08-21 13:15:12 -05:00

Collaborator

AGENTS.md tells contributors to verify a change with:

for f in lib/*.py; do python3 "$f" --help >/dev/null || echo "FAILED $f"; done

Three scripts have never passed it. Each crashed with a traceback rather than
printing usage:

Script	Failure
`pickthumb.py`	`IndexError` on a missing `sys.argv[2]`
`probe_mkv.py`	handed `--help` to `ffprobe`, then failed to parse the empty result
`scan_titles.py`	tried to open `--help` as a log file

Each now prints its docstring and exits 0 for -h/--help, and gives a
one-line usage message for a wrong argument count — the same shape
scan_streams.py already uses.

scan_titles.py and probe_mkv.py had no docstring at all, so they get a
one-line description of the question they answer, which is what --help now
prints.

Verification

Behaviour with correct arguments is unchanged, and all three were re-run
against real media to confirm rather than assumed:

scan_titles.py on a live scan log — title table renders as before
probe_mkv.py on an episode — stream list with names and flags intact
pickthumb.py on an extra — picked a frame, wrote a 49 KB JPEG, reported
window 55-75% Y=121 dev=170 sat=26 ok

Usage errors still read clearly:

$ python3 lib/scan_titles.py
usage: scan_titles.py LOG
$ python3 lib/pickthumb.py onearg
usage: pickthumb.py SRC DST [WIDTH]

The gate now passes on all 9 scripts.

`AGENTS.md` tells contributors to verify a change with: ```bash for f in lib/*.py; do python3 "$f" --help >/dev/null || echo "FAILED $f"; done ``` Three scripts have never passed it. Each crashed with a traceback rather than printing usage: | Script | Failure | |---|---| | `pickthumb.py` | `IndexError` on a missing `sys.argv[2]` | | `probe_mkv.py` | handed `--help` to `ffprobe`, then failed to parse the empty result | | `scan_titles.py` | tried to open `--help` as a log file | Each now prints its docstring and exits 0 for `-h`/`--help`, and gives a one-line usage message for a wrong argument count — the same shape `scan_streams.py` already uses. `scan_titles.py` and `probe_mkv.py` had no docstring at all, so they get a one-line description of the question they answer, which is what `--help` now prints. ### Verification Behaviour with correct arguments is unchanged, and all three were re-run against real media to confirm rather than assumed: - `scan_titles.py` on a live scan log — title table renders as before - `probe_mkv.py` on an episode — stream list with names and flags intact - `pickthumb.py` on an extra — picked a frame, wrote a 49 KB JPEG, reported `window 55-75% Y=121 dev=170 sat=26 ok` Usage errors still read clearly: ``` $ python3 lib/scan_titles.py usage: scan_titles.py LOG $ python3 lib/pickthumb.py onearg usage: pickthumb.py SRC DST [WIDTH] ``` **The gate now passes on all 9 scripts.**

claude added 1 commit

2026-08-21 13:15:13 -05:00

fix: make every script pass the --help gate AGENTS.md documents fb2889d580

AGENTS.md tells contributors to verify a change with

    for f in lib/*.py; do python3 "$f" --help >/dev/null || echo "FAILED $f"; done

but three scripts have never passed it. Each crashed with a traceback instead
of printing usage: pickthumb.py on a missing sys.argv[2], probe_mkv.py by
handing '--help' to ffprobe and failing to parse the empty result, and
scan_titles.py by trying to open '--help' as a log file.

Each now prints its docstring and exits 0 for -h/--help, and gives a one-line
usage message for a wrong argument count. scan_titles.py and probe_mkv.py had
no docstring at all, so they get a one-line description of what they answer --
which is what --help now prints.

Behaviour with correct arguments is unchanged; all three were re-run against
real media to confirm it.