Documentation
¶
Overview ¶
Package errors provides structured CLI error classification.
CLIError is the single typed error surface returned from the CLI to its callers (terminal users and the desktop app over IPC). Classify inspects a raw Go error and any captured sub-process stderr against a fingerprint table (see patterns.go) and produces a CLIError with a user-facing message, an actionable hint, and a documentation link.
The JSON shape of CLIError — and in particular the field names code, message, hint, docUrl, provider, and cause — is the IPC contract with the desktop app and MUST NOT change without coordinated changes in both repos.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CLIError ¶
type CLIError struct {
Code Code `json:"code"`
Message string `json:"message"`
Hint string `json:"hint,omitempty"`
DocURL string `json:"docUrl,omitempty"`
Provider string `json:"provider,omitempty"`
Cause string `json:"cause,omitempty"`
// contains filtered or unexported fields
}
CLIError is a structured error suitable for both terminal rendering and JSON-IPC transport to the desktop app.
func Classify ¶
func Classify(err error, ctx ClassifyContext) *CLIError
Classify maps a Go error and optional sub-process stderr to a typed CLIError. It always returns a non-nil *CLIError when err is non-nil. Returns nil only when err is nil.
The classifier walks the fingerprint table in declaration order; the first matching pattern wins. Unmatched errors fall through to CodeUnknown with the original error text as the message.
func (*CLIError) MarshalJSON ¶
MarshalJSON ensures stable field ordering and matches the IPC contract.
func (*CLIError) MarshalLogObject ¶
func (e *CLIError) MarshalLogObject(enc zapcore.ObjectEncoder) error
MarshalLogObject teaches zap to encode a *CLIError as a structured JSON object (instead of falling back to .Error()). Field names must stay in lock-step with MarshalJSON and the IPC contract documented at the top of this file.
type ClassifyContext ¶
type ClassifyContext struct {
// Provider is the name of the provider the error originated from
// (e.g. "aws", "docker"). Empty when not applicable.
Provider string
// Stderr is the captured stderr of a sub-process invocation, if any.
// Many sub-binaries (provider plugins) exit with "exit status 1" while
// the actionable detail lives in stderr.
Stderr string
}
ClassifyContext carries optional information that helps Classify produce a more specific CLIError. Both fields are optional.
type Code ¶
type Code string
Code is the stable, machine-readable identifier for a class of CLI errors. The string values are part of the IPC contract.
const ( CodeAWSProfileMissing Code = "AWS_PROFILE_MISSING" //nolint:gosec // G101 false positive: this is an error-code identifier, not a credential. CodeAWSCredsInvalid Code = "AWS_CREDS_INVALID" CodeAWSRegionMissing Code = "AWS_REGION_MISSING" CodeDockerNotRunning Code = "DOCKER_NOT_RUNNING" CodeDockerPermDenied Code = "DOCKER_PERMISSION_DENIED" CodeKubeConfigMissing Code = "KUBE_CONFIG_MISSING" CodeKubeUnreachable Code = "KUBE_UNREACHABLE" CodePodmanSocket Code = "PODMAN_SOCKET_UNAVAILABLE" CodeProviderInitFailed Code = "PROVIDER_INIT_FAILED" CodeUnknown Code = "UNKNOWN" )
Source Files