errors

Documentation

Overview

Package errors defines the CLI's typed error surface and maps errors to documented exit codes.

Index

• Constants
• func Classify(err error) int
• func Name(code int) string
• type CLIError
  • func New(code int, msg string, cause error) *CLIError
  • func Wrap(err error, code int, msg string) *CLIError
  • func (e *CLIError) Error() string
  • func (e *CLIError) Unwrap() error

Constants

const (
	CodeOK        = 0
	CodeGeneric   = 1
	CodeUsage     = 2
	CodeAuth      = 3
	CodeNetwork   = 4
	CodePartial   = 5
	CodeNoInput   = 66
	CodeCantCreat = 73
	CodeConfig    = 78
)

Exit codes — the authoritative surface documented in specs/001-readur-upload-cli/contracts/exit-codes.md. Scripts consume these values; changing any of them is a breaking change per the constitution's versioning policy.

Functions

func Classify

func Classify(err error) int

Classify walks the error chain and returns the best-matching exit code. Precedence order is documented in exit-codes.md §Precedence and enforced by errors_test.go.

If err is nil, returns CodeOK. If no CLIError is found in the chain, returns CodeGeneric.

func Name

func Name(code int) string

Name returns the exported constant name for an exit code, used in verbose log output and JSON error objects.

Types

type CLIError

type CLIError struct {
	Code    int    // one of the Code* constants in codes.go
	Message string // human-readable, free of stack traces
	Cause   error  // wrapped underlying error (optional)
}

CLIError carries an exit-code category plus a user-facing message. The command layer returns a CLIError (or wraps one) and main.go runs it through Classify to select the process exit code.

func New

func New(code int, msg string, cause error) *CLIError

New constructs a CLIError with the given code, message, and optional cause. The cause may be nil.

func Wrap

func Wrap(err error, code int, msg string) *CLIError

Wrap promotes an existing error to a CLIError with the provided code and message. If err is already a *CLIError, its Code is preserved unless overrideCode is true.

func (*CLIError) Error

func (e *CLIError) Error() string

Error implements the error interface.

If Message and Cause carry the same text (common when wrapping a retryablehttp error whose own string is already user-grade), the duplicate is suppressed.

func (*CLIError) Unwrap

func (e *CLIError) Unwrap() error

Unwrap allows errors.Is / errors.As traversal to reach the cause.