errs

Documentation

Overview

Package errs defines the mio CLI's typed error model and the stable process exit codes that AI agents and CI branch on.

Every command path that can fail should return (or wrap) a *CLIError so that main.go can translate it into the correct exit code. The exit-code contract is part of the public CLI surface — see the design doc §4.5 — and must not drift.

Index

• Constants
• func CodeOf(err error) int
• func ExitCodeForStatus(status int) int
• type CLIError
  • func New(code int, format string, args ...any) *CLIError
  • func Wrap(code int, err error) *CLIError
  • func (e *CLIError) Error() string
  • func (e *CLIError) Unwrap() error

Constants

const (
	ExitOK          = 0 // success
	ExitGeneric     = 1 // generic / unexpected error
	ExitUsage       = 2 // bad flags / usage error
	ExitAuth        = 3 // missing or invalid credentials
	ExitNotFound    = 4 // resource not found (404)
	ExitNeedsConfir = 5 // destructive op needs --yes in a non-TTY
	ExitRateLimited = 6 // rate limited (429)
	ExitServer      = 7 // upstream server error (5xx)
)

Exit codes. These are a stable public contract: agents and CI scripts branch on them, so values must never be reused for a different meaning.

Functions

func CodeOf

func CodeOf(err error) int

CodeOf extracts the exit code carried by err. A nil error is ExitOK; any error that is not (and does not wrap) a *CLIError is treated as ExitGeneric.

func ExitCodeForStatus

func ExitCodeForStatus(status int) int

ExitCodeForStatus maps an HTTP status code to a CLI exit code. Used by the client when an API call returns a non-2xx response so the exit code reflects the failure class even when the body has no structured error.

Types

type CLIError

type CLIError struct {
	// Code is the process exit code (one of the Exit* constants).
	Code int
	// Err is the underlying cause; its Error() string is shown to the user.
	Err error
}

CLIError carries both a human-facing error and the process exit code that should be returned when it propagates to main. It implements error and unwraps to the underlying cause so errors.Is/As keep working.

func New

func New(code int, format string, args ...any) *CLIError

New builds a *CLIError from a code and a formatted message.

func Wrap

func Wrap(code int, err error) *CLIError

Wrap attaches an exit code to an existing error. If err is nil it returns nil so callers can wrap unconditionally.

func (*CLIError) Error

func (e *CLIError) Error() string

Error implements the error interface.

func (*CLIError) Unwrap

func (e *CLIError) Unwrap() error

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