output

Documentation

Overview

Package output selects between human-readable and JSON output modes and enforces the stdout/stderr split required by the UX contract.

Index

• func ConflictQuietVerbose(quiet, verbose bool) error
• type ErrorEnvelope
• type ErrorJSON
• type Mode
• type Verbosity
• type Writer
  • func New() *Writer
  • func (w *Writer) ApplyFlags(jsonMode, quiet, verbose, noColor bool) error
  • func (w *Writer) Debugf(format string, args ...any)
  • func (w *Writer) ExitTrailer(code int)
  • func (w *Writer) Infof(format string, args ...any)
  • func (w *Writer) Primary(v any) error
  • func (w *Writer) RenderError(err error)
  • func (w *Writer) Warnf(format string, args ...any)

Functions

func ConflictQuietVerbose

func ConflictQuietVerbose(quiet, verbose bool) error

ConflictQuietVerbose returns a USAGE CLIError if both quiet and verbose are set — enforced by root.go before any I/O.

Types

type ErrorEnvelope

type ErrorEnvelope struct {
	Error    ErrorJSON `json:"error"`
	ExitCode int       `json:"exit_code"`
}

ErrorEnvelope is the top-level JSON produced on failure. Callers may wrap it with command-specific fields before emitting.

type ErrorJSON

type ErrorJSON struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

ErrorJSON is the wire shape used inside JSON primary output when an error is returned instead of a success record.

type Mode

type Mode int

Mode selects the primary-output formatter.

const (
	// ModeHuman formats stdout primary output for human readers (default).
	ModeHuman Mode = iota
	// ModeJSON formats stdout primary output as JSON.
	ModeJSON
)

type Verbosity

type Verbosity int

Verbosity controls stderr diagnostic chatter.

const (
	// VerbosityNormal is the default: info+warn on stderr.
	VerbosityNormal Verbosity = iota
	// VerbosityQuiet suppresses progress/info on stderr. Warnings still emitted.
	VerbosityQuiet
	// VerbosityVerbose emits debug-level diagnostics on stderr and
	// includes an "exit=<code> reason=<name>" trailer.
	VerbosityVerbose
)

type Writer

type Writer struct {
	// Stdout carries primary data only. Tests may wire a buffer here.
	Stdout io.Writer
	// Stderr carries diagnostics, progress, and prompts.
	Stderr io.Writer
	// Mode selects human vs JSON primary output.
	Mode Mode
	// Verbosity gates the stderr stream.
	Verbosity Verbosity
	// NoColor disables ANSI formatting (currently informational; color
	// is not yet enabled, so this bit is reserved for future use).
	NoColor bool
}

Writer is the single object every command writes through. It enforces the stdout/stderr split (Constitution III) and handles JSON vs human selection (contracts/json-output.md).

func New

func New() *Writer

New returns a Writer wired to os.Stdout/os.Stderr with human output and normal verbosity. Commands typically construct one per invocation and override fields from persistent flags.

func (*Writer) ApplyFlags

func (w *Writer) ApplyFlags(jsonMode, quiet, verbose, noColor bool) error

ApplyFlags resolves the combined flag state into Writer fields. The NO_COLOR environment variable is honored here rather than in each command.

func (*Writer) Debugf

func (w *Writer) Debugf(format string, args ...any)

Debugf writes a debug line to stderr only in verbose mode.

func (*Writer) ExitTrailer

func (w *Writer) ExitTrailer(code int)

ExitTrailer emits the verbose exit summary line when verbose is on.

func (*Writer) Infof

func (w *Writer) Infof(format string, args ...any)

Infof writes a progress/info line to stderr unless quiet.

func (*Writer) Primary

func (w *Writer) Primary(v any) error

Primary writes v to stdout. In human mode, v must implement fmt.Stringer or be a plain string. In JSON mode, v is JSON-marshalled + newline.

func (*Writer) RenderError

func (w *Writer) RenderError(err error)

RenderError writes the human-readable error tree to stderr and, in JSON mode, writes the ErrorEnvelope to stdout.

func (*Writer) Warnf

func (w *Writer) Warnf(format string, args ...any)

Warnf writes a warning line to stderr regardless of quiet.