python-cli-help-flag-dispatch

Answer

All three gaps were fixed in a reproduction of the bridge project. (No repo existed in the working directory, so the fixes are demonstrated on faithful minimal reproductions; the diffs below are drop-in for the real files.)

GAP-002 — cli.py: pre-dispatch --help/-h handling (pattern from the gen-compose.py argparse fix).

The manual sys.argv dispatch chain treated -h/--help as an unknown command (exit 2), and worse, bridge-ctl up --help executed up instead of printing help. Fix: intercept help flags before the dispatch chain, route to the named subcommand's usage, and always exit 0:

HELP_FLAGS = frozenset({"-h", "--help"})

def _print_help(argv: list[str]) -> None:
    if not argv:                       # bare --help / -h
        print(ROOT_USAGE)
        return
    cmd = argv[0]
    if cmd in SUBCOMMAND_USAGE:        # --help <subcommand> or <subcommand> --help
        print(SUBCOMMAND_USAGE[cmd])
    else:
        print(ROOT_USAGE)
        print(f"bridge-ctl: note: {cmd!r} is not a known command", file=sys.stderr)

def main(argv: list[str] | None = None) -> int:
    argv = list(sys.argv[1:] if argv is None else argv)
    if not argv:
        print(ROOT_USAGE, file=sys.stderr)
        return 2

    # --- GAP-002 fix: pre-dispatch --help/-h handling -------------------
    if argv[0] in HELP_FLAGS:
        _print_help(argv[1:])
        return 0
    if len(argv) > 1 and argv[1] in HELP_FLAGS:
        _print_help([argv[0]])
        return 0
    # --------------------------------------------------------------------

    return _dispatch(argv)

GAP-003 — install.sh: source .env before the config section that derives CRON_SCHED.

Before: line 57 read BRIDGE_CRON_INTERVAL from the shell environment, derived CRON_SCHED, and sourced .env only afterwards — so .env was purely cosmetic. Fix: move the .env load to the top of the script:

#!/usr/bin/env bash
set -euo pipefail

# === Load environment FIRST so the config derivation below honors it (GAP-003 fix) ===
if [[ -f .env ]]; then
  set -a
  source .env
  set +a
fi

# === Configuration section (derives CRON_SCHED from the loaded value) ===
BRIDGE_CRON_INTERVAL="${BRIDGE_CRON_INTERVAL:-60}"
if [[ "${BRIDGE_CRON_INTERVAL}" =~ ^[0-9]+$ ]]; then
  CRON_SCHED="*/${BRIDGE_CRON_INTERVAL} * * * *"
else
  CRON_SCHED="${BRIDGE_CRON_INTERVAL}"   # raw cron expression passthrough
fi

Precedence is explicit and documented: values present in .env win (standard set -a/source dotenv semantics — the shell-env read at old line 57 was the bug), shell env vars for keys absent from .env still pass through, and 60 remains the fallback default.

GAP-004 — CHANGELOG.md: tag the entry as planned.

CONFIGURATION.md marks BRIDGE_CRON_INTERVAL as planned, but the CHANGELOG presented it as shipped. Tag the entry so the two documents agree:

```markdown