output

Documentation

Overview

Package output renders command results, enforcing the project's agent contract: machine-readable data goes to stdout, while human-oriented text, progress and diagnostics go to stderr. JSON/NDJSON/YAML output never contains log lines, so an agent can parse stdout unconditionally.

Index

• func NewTabWriter(w io.Writer) *tabwriter.Writer
• type ErrorPayload
• type Format
  • func ParseFormat(s string) (Format, error)
  • func (f Format) Machine() bool
• type HumanFunc
• type Printer
  • func (p *Printer) Emit(v any, human HumanFunc) error
  • func (p *Printer) EmitError(pl ErrorPayload)
  • func (p *Printer) Info(format string, args ...any)

Functions

func NewTabWriter

func NewTabWriter(w io.Writer) *tabwriter.Writer

NewTabWriter returns a tabwriter configured for the project's table style. Callers write tab-separated rows and must Flush.

Types

type ErrorPayload

type ErrorPayload struct {
	// Code is a stable, lowercase machine token, e.g. "not_found", "auth", "validation".
	Code string `json:"code"`
	// Message is a human-readable, single-line description.
	Message string `json:"message"`
	// HTTPStatus is the upstream Mealie status code, when the error came from the API.
	HTTPStatus int `json:"http_status,omitempty"`
	// Retryable indicates the operation may succeed if retried (transient).
	Retryable bool `json:"retryable"`
	// RequestID echoes a server/request correlation id when available.
	RequestID string `json:"request_id,omitempty"`
	// Details carries structured, error-specific context (e.g. validation fields).
	Details map[string]any `json:"details,omitempty"`
	// Hint is an actionable next step for humans (e.g. "run `mealie auth login`").
	Hint string `json:"hint,omitempty"`
}

ErrorPayload is the stable, machine-readable error contract. In any machine output format it is emitted to stderr wrapped in an {"error": {...}} envelope, so agents can branch on `code`, `http_status` and `retryable` without parsing prose. Treat the field set and `code` vocabulary as a versioned API.

type Format

type Format string

Format is a machine- or human-facing rendering of command output.

const (
	// FormatTable is the default human-friendly rendering (aligned columns).
	FormatTable Format = "table"
	// FormatJSON renders a single pretty-printed JSON document.
	FormatJSON Format = "json"
	// FormatNDJSON renders newline-delimited JSON: one compact object per line,
	// ideal for streaming lists into agents and tools like jq.
	FormatNDJSON Format = "ndjson"
	// FormatYAML renders a single YAML document.
	FormatYAML Format = "yaml"
)

func ParseFormat

func ParseFormat(s string) (Format, error)

ParseFormat normalises a user-supplied format string. An empty string maps to the table default.

func (Format) Machine

func (f Format) Machine() bool

Machine reports whether the format is intended for programmatic consumption.

type HumanFunc

type HumanFunc func(w io.Writer) error

HumanFunc renders a value for human consumption (table mode). It receives the stdout writer. Commands typically build aligned tables via NewTabWriter.

type Printer

type Printer struct {
	Out    io.Writer
	Err    io.Writer
	Format Format
	// Quiet suppresses incidental human messages (Info/Hintf). It never affects
	// machine data on stdout.
	Quiet bool
	// Color enables ANSI styling in human output. Callers should set this from a
	// TTY check plus NO_COLOR/--no-color handling.
	Color bool
}

Printer is the single sink for command output. Construct it once per command invocation from the resolved global flags.

func (*Printer) Emit

func (p *Printer) Emit(v any, human HumanFunc) error

Emit renders v in the configured format. In machine formats v is marshalled directly; in table mode the human callback is used (falling back to JSON if nil so no command is ever silent).

func (*Printer) EmitError

func (p *Printer) EmitError(pl ErrorPayload)

EmitError writes the error to stderr. Machine formats emit the JSON envelope; table mode emits a concise human message plus an optional hint. Errors always go to stderr so stdout stays a clean data channel.

func (*Printer) Info

func (p *Printer) Info(format string, args ...any)

Info writes a human-oriented message to stderr unless quiet. Use for progress and confirmations — never for data an agent needs to parse.