feat(structerr): structured JSON errors with typed interception and semantic exit codes

[leodido]

Summary

• HandleError(cmd, err, writer) — classifies errors, writes JSON to stderr, returns semantic exit code
• ExecuteOrExit(cmd) — one-line convenience for main(), auto-sets SilenceErrors/SilenceUsage, uses ExecuteC() for correct command resolution
• SetupFlagErrors(rootCmd) — intercepts flag parsing errors via cobra.SetFlagErrorFunc producing typed FlagError values, eliminating regex for ~90% of error classification
• structerr subpackage following config/debug/jsonschema pattern
• Full source attribution: CLI flags vs env vars vs config
• Rich validation output via ValidationError.Details() with per-field violations
• Enum violation detection via EnumValuer annotations (exit code 15)

Two layers of error classification

Layer 1: SetupFlagErrors (typed, preferred)

Intercepts errors at creation time via cobra.SetFlagErrorFunc, producing typed FlagError values with structured metadata. HandleError uses errors.As — no regex needed.

Layer 2: Regex fallback (for cobra string errors)

When SetupFlagErrors is not called, or for error types cobra doesn't expose typed errors for (required flags, unknown commands), HandleError falls back to string pattern matching on cobra's error messages.

Usage

One-line:

func main() {
    rootCmd := buildMyCLI()
    structcli.SetupFlagErrors(rootCmd)           // optional: typed flag errors
    structcli.ExecuteOrExit(rootCmd)              // JSON errors to stderr, semantic exit codes
}

Manual control:

structcli.SetupFlagErrors(rootCmd)
cmd, err := rootCmd.ExecuteC()                   // ExecuteC returns the subcommand
if err != nil {
    os.Exit(structcli.HandleError(cmd, err, os.Stderr))
}

Important: HandleError requires the command where the error originated, not the root. Use ExecuteC() or ExecuteOrExit to get this right. See doc comment for details.

Error classification

Error source	Detection	JSON error	Exit code
Missing required flag	String pattern	missing_required_flag	10
Invalid flag value (CLI)	FlagError or string pattern + Changed()	invalid_flag_value	11
Invalid enum value	FlagError + EnumValuer annotation	invalid_flag_enum	15
Invalid flag value (env)	Source attribution via env annotation + os.Getenv	env_invalid_value	25
Unknown flag	FlagError or string pattern	unknown_flag	12
Unknown command	String pattern	unknown_command	14
Validation failed	errors.As on ValidationError + Details()	validation_failed	13
Unmarshal decode error	Mapstructure pattern + source attribution	invalid_flag_value or env_invalid_value	11/25
Config errors	String patterns	config_*	20-23
Anything else	Fallthrough	error	1

Changes

File	What
structerr/types.go (new)	structerr.Options subpackage
structerr.go (new)	SetupFlagErrors, HandleError, ExecuteOrExit, StructuredError, Violation, classification engine
structerr_test.go (new)	Tests: typed path, regex fallback, every error category, source attribution, validation details, enum violations, edge cases
errors/errors.go	FlagError type with Kind/FlagName/Value/Cause fields
examples/simple/main.go	Uses ExecuteOrExit with SilenceErrors/SilenceUsage
examples/structerr/ (new)	Dedicated example stress-testing every error path

Test coverage

Function	Coverage
classify	100%
classifyUnmarshalError	100%
parseDecodeError	100%
flagType	100%
findFlagForField	100%
flagEnvVars	100%
flagEnumValues	100%
flagValidateRules	100%
extractLongFlagName	100%
parseQuotedList	100%
commandPath	100%
classifyMissingRequired	93%
classifyInvalidArg	92%
classifyUnknownCommand	86%
SetupFlagErrors	78%
HandleError	78%
classifyValidation	61%
ExecuteOrExit	0% (calls os.Exit)