Documentation
¶
Overview ¶
Package output centralises CLI output routing.
Two design rules drive the package:
In JSON mode, stdout carries ONLY the JSON payload (or a structured error envelope). Every status line, spinner, prompt, progress bar, and human-readable note goes to stderr. Agents and `jq` pipelines can rely on `vulncheck <cmd> --json` producing parseable output.
In text mode, everything goes to stdout, matching today's behaviour. Styling is suppressed when stdout is not a TTY or when NO_COLOR is set.
Commands obtain a Renderer once and call its methods instead of reaching for fmt.Print / pkg/ui directly. The Renderer is the single seam between "thing happened" and "bytes on a file descriptor".
Index ¶
- Constants
- func ColorEnabled() bool
- func Interactive() bool
- func IsCI() bool
- func IsTTY(f *os.File) bool
- func WithContext(ctx context.Context, r *Renderer) context.Context
- type Mode
- type Options
- type Renderer
- func (r *Renderer) Color() bool
- func (r *Renderer) Info(format string, args ...any)
- func (r *Renderer) InfoStream() io.Writer
- func (r *Renderer) Interactive() bool
- func (r *Renderer) IsJSON() bool
- func (r *Renderer) JSON(payload any) error
- func (r *Renderer) Mode() Mode
- func (r *Renderer) Printf(format string, args ...any)
- func (r *Renderer) Println(args ...any)
- func (r *Renderer) Quiet() bool
- func (r *Renderer) Stat(label, value string)
- func (r *Renderer) Stderr() io.Writer
- func (r *Renderer) Stdout() io.Writer
- func (r *Renderer) Success(format string, args ...any)
- func (r *Renderer) Warn(format string, args ...any)
Constants ¶
const SchemaVersion = 1
SchemaVersion is the integer version of the CLI's machine-readable payload shapes (the error envelope, auth status, version info, batch results, sync summaries). Bump it on a breaking change so agents can detect a CLI they don't speak.
Stability contract:
- schema_version is stamped only on CLI-shaped payloads. Pass-through API responses (cpe / purl / tag / pdns / indices list) keep the server's existing shape.
- Adding optional fields is NOT a breaking change.
- Removing or renaming a field IS a breaking change → bump.
Variables ¶
This section is empty.
Functions ¶
func ColorEnabled ¶
func ColorEnabled() bool
ColorEnabled reports whether ANSI colour output should be emitted on stdout. Honours NO_COLOR (https://no-color.org) and TERM=dumb, and falls back to "stdout is a terminal" otherwise.
func Interactive ¶
func Interactive() bool
Interactive reports whether the process can safely show interactive UI (prompts, spinners, full-screen TUIs). False whenever stdin or stdout is non-TTY, or when CI/NO_COLOR-style signals are set.
func IsCI ¶
func IsCI() bool
IsCI reports whether the process appears to be running under a CI system. Mirrors the heuristic used elsewhere in the codebase; kept here so the output package has no dependency on pkg/config.
Types ¶
type Options ¶
type Options struct {
Mode Mode
Color bool // when false, callers should render without ANSI sequences
Quiet bool
Interactive bool // when false, commands MUST NOT block on prompts
Stdout io.Writer // defaults to os.Stdout
Stderr io.Writer // defaults to os.Stderr
}
Options controls Renderer construction.
type Renderer ¶
type Renderer struct {
// contains filtered or unexported fields
}
Renderer routes informational, payload, and error output to the right stream based on the selected Mode. Zero value is not useful; use New().
func FromCmd ¶
FromCmd is shorthand for FromContext(cmd.Context()). Use in command RunE bodies: `r := output.FromCmd(cmd)`.
func FromContext ¶
FromContext returns the Renderer attached to ctx, or a sensible default (text mode, env-derived) when none is present. Always returns non-nil.
func New ¶
New constructs a Renderer from explicit options. Callers that want environment defaults should use NewFromEnv.
func NewFromEnv ¶
NewFromEnv builds a Renderer using TTY / NO_COLOR / CI detection. Mode is taken from the caller (typically a --json flag); everything else is inferred from the environment.
func (*Renderer) Color ¶
Color reports whether ANSI styling should be applied. Callers that build their own styled strings (lipgloss, etc.) should consult this.
func (*Renderer) Info ¶
Info writes an informational status line. Routed to stderr in JSON mode so the stdout payload stays clean. Suppressed entirely when quiet.
func (*Renderer) InfoStream ¶
InfoStream returns the stream that informational output should go to. stderr in JSON mode, stdout otherwise. Useful when wiring a third-party component (taskin, bubbletea) that takes an io.Writer.
func (*Renderer) Interactive ¶
Interactive reports whether commands may block on TUI prompts (huh forms, bubbletea screens). Returns false under CI, --no-interactive, when stdin is non-TTY, or when --json is set (JSON output is for machines — never block them on prompts).
func (*Renderer) JSON ¶
JSON marshals payload as indented JSON and writes it, followed by a newline, to stdout. HTML-escaping (< > &) is disabled: the CLI's stdout is not an HTML embedding, so escaping "<name>" to "<name>" just makes example strings and validation messages unreadable.
func (*Renderer) Mode ¶
Mode returns the renderer's mode. Useful for commands that need to choose between two payload shapes (table vs JSON) at a single call site.
func (*Renderer) Printf ¶
Printf writes a plain text fragment to the payload stream. Has no effect in JSON mode.
func (*Renderer) Println ¶
Println writes a plain text line to the payload stream. Has no effect in JSON mode (where stdout is reserved for the JSON document).
func (*Renderer) Stderr ¶
Stderr returns the diagnostic stream. Use for progress bars, spinners, and anything that must not contaminate stdout in JSON mode.
func (*Renderer) Stdout ¶
Stdout returns the payload stream. Use for raw payload writes when the structured helpers (JSON, Println) are not a fit — e.g. a command that streams bytes (backup download to stdout).
Source Files