output

package
v1.2.15 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 13, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package output defines the shared CLI response contract for agent-friendly output modes.

Index

Constants

View Source
const (
	// CodeError is the generic structured error code.
	CodeError = "error"
	// CodeUsage identifies invalid command usage.
	CodeUsage = "usage_error"
	// CodeOutputMode identifies an invalid output mode selection.
	CodeOutputMode = "invalid_output_mode"
	// CodeProjectNotFound identifies commands run outside an Andurel project.
	CodeProjectNotFound = "project_not_found"
	// CodeMissingTool identifies a missing external tool dependency.
	CodeMissingTool = "missing_tool"
	// CodeInvalidExtension identifies an unknown extension name.
	CodeInvalidExtension = "invalid_extension"
	// CodeInvalidInertiaAdapter identifies an unsupported Inertia adapter.
	CodeInvalidInertiaAdapter = "invalid_inertia_adapter"
	// CodeUnsafeAction identifies an action that requires explicit confirmation.
	CodeUnsafeAction = "unsafe_action_requires_confirmation"
	// CodeGenerationFailed identifies a failed code generation command.
	CodeGenerationFailed = "generation_failed"
	// CodeExternalCommandFailed identifies a failed external command.
	CodeExternalCommandFailed = "external_command_failed"
	// CodeConfigError identifies invalid or unreadable configuration.
	CodeConfigError = "config_error"
	// CodeAmbiguousInput identifies user input that cannot be resolved safely.
	CodeAmbiguousInput = "ambiguous_input"
	// CodeUpdateRequired identifies an operation that requires a newer Andurel CLI.
	CodeUpdateRequired = "update_required"
	// ExitUsage is the exit code for command usage errors.
	ExitUsage = 1
	// ExitProject is the exit code for missing project context.
	ExitProject = 2
	// ExitDependency is the exit code for missing dependencies.
	ExitDependency = 3
	// ExitUnsafe is the exit code for unsafe unconfirmed actions.
	ExitUnsafe = 4
	// ExitGeneration is the exit code for generation failures.
	ExitGeneration = 5
	// ExitExternal is the exit code for failed external commands.
	ExitExternal = 6
	// ExitConfig is the exit code for configuration errors.
	ExitConfig = 7
	// ExitAmbiguous is the exit code for ambiguous input.
	ExitAmbiguous = 8
)

Variables

This section is empty.

Functions

func ExitCode

func ExitCode(err error) int

ExitCode returns the process exit code for an error.

func OK

func OK(cmd *cobra.Command, data any, summary string, breadcrumbs ...Breadcrumb) error

OK renders a successful response using the selected output mode.

func RegisterPersistentFlags

func RegisterPersistentFlags(cmd *cobra.Command)

RegisterPersistentFlags adds the shared agent-friendly output flags.

func RenderError

func RenderError(cmd *cobra.Command, err error) error

RenderError renders a failed response using the selected output mode.

func SuppressesHumanOutput

func SuppressesHumanOutput(opts Options) bool

SuppressesHumanOutput reports whether command progress from lower-level routines should be hidden before rendering the final response.

func UsesStructuredOutput

func UsesStructuredOutput(opts Options) bool

UsesStructuredOutput reports whether a command should render through the shared output contract instead of human prose.

Types

type Breadcrumb struct {
	Command     string `json:"cmd"`
	Description string `json:"description,omitempty"`
}

Breadcrumb is a follow-up action an agent or human can take.

type CLIError

type CLIError struct {
	Code     string
	Message  string
	Hint     string
	ExitCode int
	Cause    error
}

CLIError is a typed command error with a stable machine-readable code.

func NewError

func NewError(code, message string, exitCode int, hint string) *CLIError

NewError creates a typed CLI error.

func WrapError

func WrapError(code string, cause error, exitCode int, hint string) *CLIError

WrapError creates a typed CLI error while preserving the wrapped cause.

func (*CLIError) Error

func (e *CLIError) Error() string

Error returns the best available human-readable error message.

func (*CLIError) Unwrap

func (e *CLIError) Unwrap() error

Unwrap returns the underlying cause, if one was recorded.

type Envelope

type Envelope struct {
	OK          bool         `json:"ok"`
	Data        any          `json:"data,omitempty"`
	Summary     string       `json:"summary,omitempty"`
	Breadcrumbs []Breadcrumb `json:"breadcrumbs,omitempty"`
}

Envelope wraps successful structured command output.

type ErrorEnvelope

type ErrorEnvelope struct {
	OK       bool   `json:"ok"`
	Code     string `json:"code"`
	Error    string `json:"error"`
	Hint     string `json:"hint,omitempty"`
	ExitCode int    `json:"exit_code,omitempty"`
}

ErrorEnvelope wraps failed structured command output.

func Fail

func Fail(err error) ErrorEnvelope

Fail converts any error into a structured error envelope.

type Mode

type Mode string

Mode is the selected output format for a command invocation.

const (
	// ModeHuman renders the default human-readable output.
	ModeHuman Mode = "human"
	// ModeJSON renders structured JSON output.
	ModeJSON Mode = "json"
	// ModeAgent renders structured output optimized for agent workflows.
	ModeAgent Mode = "agent"
	// ModeMarkdown renders Markdown output.
	ModeMarkdown Mode = "markdown"
)

type Options

type Options struct {
	Mode    Mode
	Quiet   bool
	JQ      string
	IDsOnly bool
	Count   bool
	Verbose bool
}

Options are parsed from the root persistent output flags.

func ParseOptions

func ParseOptions(cmd *cobra.Command) (Options, error)

ParseOptions returns output options from command flags.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL