go-cli-flag-parsing

Answer

Root cause (GAP-015): config.Load() (whose requireEnv deliberately panics on missing env vars) ran at the top of each main(), so any invocation — including --version/--help — crashed with a goroutine dump before the flag package ever ran.

Fix (3 parts): 1. Parse stdlib flag before config.Load() in every cmd/<name>/main.go. 2. Handle --version / --help (custom flag.Usage) right after parse, exiting 0 before any config access. 3. Wrap config.Load() in a deferred recover at the process boundary that prints a one-line fatal: to stderr and os.Exit(1) — the library is untouched because its recover-based tests assert the panics.

Shared helper (internal/cli/cli.go) so every binary gets identical behavior:

package cli

import (
    "flag"
    "fmt"
    "os"
    "path/filepath"
    "strings"
)

// Version injected at build time:
//   go build -ldflags "-X <module>/internal/cli.Version=1.2.3" ...
var Version = "dev"

func binName() string { return filepath.Base(os.Args[0]) }

// Parse runs BEFORE any config access. Exits for --version (0),
// --help/-h (0), and malformed flags (2, stdlib, with our Usage).
func Parse() {
    version := flag.Bool("version", false, "print version and exit")
    help := flag.Bool("help", false, "print this help and exit")
    flag.Usage = func() {
        fmt.Fprintf(os.Stderr, "Usage: %s [flags]\n\nFlags:\n", binName())
        flag.PrintDefaults()
    }
    flag.Parse()
    if *version {
        fmt.Printf("%s %s\n", binName(), Version)
        os.Exit(0)
    }
    if *help {
        flag.Usage()
        os.Exit(0)
    }
}

// FatalRecover converts any panic (config.Load's requireEnv) into a
// single-line fatal + exit 1. The library tests assert the panics, so
// we recover here instead of changing the library.
func FatalRecover() {
    if r := recover(); r != nil {
        msg := strings.ReplaceAll(fmt.Sprint(r), "\n", " ") // guarantee one line
        fmt.Fprintf(os.Stderr, "fatal: %s\n", msg)
        os.Exit(1)
    }
}

Every cmd/<name>/main.go now follows this order:

package main

import (
    "gap015/internal/cli"
    "gap015/internal/config"
)

func main() {
    cli.Parse() // 1. flags FIRST — --version/--help exit before config

    defer cli.FatalRecover() // 2. process-boundary recover

    cfg := config.Load()     // 3. config — panic → one-line fatal, exit 1
    run(cfg)                 // 4. normal startup
}

No change to the config library, so internal/config/config_test.go (which asserts Load() panics) keeps passing as-is.