errs

Documentation

Overview

Package errs defines gskill's typed errors and their mapping to process exit codes. Errors wrap their cause with %w so errors.Is and errors.As traverse the chain, and ExitCode resolves any error to a stable code in the range 0-12 documented in contracts/cli-commands.md.

Index

• Variables
• func ExitCode(err error) int
• func HintOf(err error) string
• func New(code Code, msg string) error
• func WithHint(err error, hint string) error
• func Wrap(code Code, msg string, cause error) error
• type Code
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Is(target error) bool
  • func (e *Error) Unwrap() error

Examples

• ExitCode
• ExitCode (Unknown)

Variables

var (
	ErrUsage             = &Error{Code: CodeUsage, Msg: "usage error"}
	ErrInvalidManifest   = &Error{Code: CodeInvalidManifest, Msg: "invalid manifest"}
	ErrLockMismatch      = &Error{Code: CodeLockMismatch, Msg: "lockfile mismatch"}
	ErrSourceUnavailable = &Error{Code: CodeSourceUnavailable, Msg: "source unavailable"}
	ErrIntegrity         = &Error{Code: CodeIntegrity, Msg: "integrity failure"}
	ErrDrift             = &Error{Code: CodeDrift, Msg: "drift detected"}
	ErrUpdateAvailable   = &Error{Code: CodeUpdateAvailable, Msg: "update available"}
	ErrUnsupportedAgent  = &Error{Code: CodeUnsupportedAgent, Msg: "unsupported or undetected agent"}
	ErrPartialInstall    = &Error{Code: CodePartialInstall, Msg: "partial installation"}
	ErrAuth              = &Error{Code: CodeAuth, Msg: "authentication failure"}
	ErrCacheLock         = &Error{Code: CodeCacheLock, Msg: "cache or lock failure"}
)

Sentinel errors, one per exit code. Wrap them with %w (or Wrap) to attach context while preserving the code.

Functions

func ExitCode

func ExitCode(err error) int

ExitCode resolves err to its process exit code: 0 for nil, the Code of the first *Error found in the chain, or CodeGeneric (1) for any other error.

Example

package main

import (
	"fmt"

	"github.com/glapsfun/gskill/internal/errs"
)

func main() {
	// A wrapped sentinel keeps its exit code through %w wrapping.
	err := fmt.Errorf("git fetch: %w", errs.ErrAuth)
	fmt.Println(errs.ExitCode(err))
}

Output:
11

Example (Unknown)

package main

import (
	"errors"
	"fmt"

	"github.com/glapsfun/gskill/internal/errs"
)

func main() {
	fmt.Println(errs.ExitCode(errors.New("something unexpected")))
}

Output:
1

func HintOf

func HintOf(err error) string

HintOf returns the first non-empty hint found along err's chain, or "".

func New

func New(code Code, msg string) error

New returns an *Error carrying code and msg with no underlying cause.

func WithHint

func WithHint(err error, hint string) error

WithHint returns err with an actionable next-step hint attached. The returned error reports the same message as err, resolves to the same exit code, and keeps the full chain reachable for errors.Is/As. A nil err returns nil.

func Wrap

func Wrap(code Code, msg string, cause error) error

Wrap returns an *Error carrying code and msg that wraps cause. cause may be nil, in which case the result behaves like New.

Types

type Code

type Code int

Code is a gskill process exit code.

const (
	CodeOK                Code = 0  // success
	CodeGeneric           Code = 1  // generic/unexpected error
	CodeUsage             Code = 2  // usage error (bad flags/args)
	CodeInvalidManifest   Code = 3  // invalid manifest
	CodeLockMismatch      Code = 4  // lockfile mismatch (--frozen-lockfile would change)
	CodeSourceUnavailable Code = 5  // source unavailable / network
	CodeIntegrity         Code = 6  // integrity failure (checksum mismatch)
	CodeDrift             Code = 7  // drift detected (--fail-on-drift)
	CodeUpdateAvailable   Code = 8  // update available (outdated --exit-code)
	CodeUnsupportedAgent  Code = 9  // unsupported / undetected agent
	CodePartialInstall    Code = 10 // partial installation
	CodeAuth              Code = 11 // authentication failure
	CodeCacheLock         Code = 12 // cache / lock failure (incl. lock-acquire timeout)
)

Exit codes (FR-038). These are the process's external contract and must not be renumbered.

type Error

type Error struct {
	Code Code
	Msg  string
	Err  error
	Hint string
}

Error carries a gskill exit Code and, optionally, an underlying cause that remains reachable through errors.Is, errors.As, and errors.Unwrap, plus an optional Hint: a one-line actionable next step the CLI renders after the error message ("→ run 'gskill init' to create one"). Hint never changes Error() output, code mapping, or errors.Is/As matching.

func (*Error) Error

func (e *Error) Error() string

Error implements the error interface.

func (*Error) Is

func (e *Error) Is(target error) bool

Is reports whether target is an *Error with the same Code, so a wrapped error matches the sentinel for its category.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap returns the wrapped cause, if any.