Documentation
¶
Overview ¶
Package output provides JSON/Markdown output formatting and error handling.
Index ¶
- Constants
- func ExitCodeFor(code string) int
- func NormalizeData(data any) any
- func TruncationNotice(count, defaultLimit int, all bool, explicitLimit int) string
- func TruncationNoticeWithTotal(count, totalCount int) string
- type Breadcrumb
- type Error
- func AsError(err error) *Error
- func ErrAPI(status int, msg string) *Error
- func ErrAmbiguous(resource string, matches []string) *Error
- func ErrAuth(msg string) *Error
- func ErrForbidden(msg string) *Error
- func ErrForbiddenScope() *Error
- func ErrNetwork(cause error) *Error
- func ErrNotFound(resource, identifier string) *Error
- func ErrNotFoundHint(resource, identifier, hint string) *Error
- func ErrRateLimit(retryAfter int) *Error
- func ErrUsage(msg string) *Error
- func ErrUsageHint(msg, hint string) *Error
- type ErrorResponse
- type ErrorResponseOption
- type Format
- type Options
- type Response
- type ResponseOption
- type Writer
Constants ¶
const ( ExitOK = 0 // Success ExitUsage = 1 // Invalid arguments or flags ExitNotFound = 2 // Resource not found ExitAuth = 3 // Not authenticated ExitForbidden = 4 // Access denied (scope issue) ExitRateLimit = 5 // Rate limited (429) ExitNetwork = 6 // Connection/DNS/timeout error ExitAPI = 7 // Server returned error ExitAmbiguous = 8 // Multiple matches for name )
Exit codes matching the Bash implementation.
const ( CodeUsage = "usage" CodeNotFound = "not_found" CodeAuth = "auth_required" CodeForbidden = "forbidden" CodeRateLimit = "rate_limit" CodeNetwork = "network" CodeAPI = "api_error" CodeAmbiguous = "ambiguous" )
Error codes for JSON envelope.
Variables ¶
This section is empty.
Functions ¶
func ExitCodeFor ¶
ExitCodeFor returns the exit code for a given error code.
func NormalizeData ¶
NormalizeData converts json.RawMessage and other types to standard Go types.
func TruncationNotice ¶
TruncationNotice returns a notice string if results may be truncated. Returns empty string if no truncation warning is needed.
func TruncationNoticeWithTotal ¶
TruncationNoticeWithTotal returns a truncation notice when results are truncated. Uses totalCount from API's X-Total-Count header to show accurate counts. Returns empty string if no truncation or totalCount is 0 (unavailable).
Types ¶
type Breadcrumb ¶
type Breadcrumb struct {
Action string `json:"action"`
Cmd string `json:"cmd"`
Description string `json:"description"`
}
Breadcrumb is a suggested follow-up action.
type Error ¶
type Error struct {
Code string
Message string
Hint string
HTTPStatus int
Retryable bool
Cause error
}
Error is a structured error with code, message, and optional hint.
func ErrAmbiguous ¶
func ErrForbidden ¶
func ErrForbiddenScope ¶
func ErrForbiddenScope() *Error
func ErrNetwork ¶
func ErrNotFound ¶
func ErrNotFoundHint ¶
func ErrRateLimit ¶
func ErrUsageHint ¶
type ErrorResponse ¶
type ErrorResponse struct {
OK bool `json:"ok"`
Error string `json:"error"`
Code string `json:"code"`
Hint string `json:"hint,omitempty"`
Meta map[string]any `json:"meta,omitempty"`
}
ErrorResponse is the error envelope for JSON output.
type ErrorResponseOption ¶
type ErrorResponseOption func(*ErrorResponse)
ErrorResponseOption modifies an ErrorResponse.
type Options ¶
Options controls output behavior.
func DefaultOptions ¶
func DefaultOptions() Options
DefaultOptions returns options for standard output.
type Response ¶
type Response struct {
OK bool `json:"ok"`
Data any `json:"data,omitempty"`
Summary string `json:"summary,omitempty"`
Notice string `json:"notice,omitempty"`
Breadcrumbs []Breadcrumb `json:"breadcrumbs,omitempty"`
Context map[string]any `json:"context,omitempty"`
Meta map[string]any `json:"meta,omitempty"`
}
Response is the success envelope for JSON output.
type ResponseOption ¶
type ResponseOption func(*Response)
ResponseOption modifies a Response.
func WithBreadcrumbs ¶
func WithBreadcrumbs(b ...Breadcrumb) ResponseOption
WithBreadcrumbs adds breadcrumbs to the response.
func WithContext ¶
func WithContext(key string, value any) ResponseOption
WithContext adds context to the response.
func WithMeta ¶
func WithMeta(key string, value any) ResponseOption
WithMeta adds metadata to the response.
func WithNotice ¶
func WithNotice(s string) ResponseOption
WithNotice adds an informational notice to the response.
func WithSummary ¶
func WithSummary(s string) ResponseOption
WithSummary adds a summary to the response.
func WithoutBreadcrumbs ¶
func WithoutBreadcrumbs() ResponseOption
WithoutBreadcrumbs removes all breadcrumbs from the response.
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer handles all output formatting.
func (*Writer) EffectiveFormat ¶
EffectiveFormat resolves FormatAuto based on TTY detection.
Source Files