cli

Documentation

Overview

Package cli is the command-line door.

It translates; it does not decide. A default, validation rule, or result field invented here is a second contract — defaults live in the ergonomic layer (behavior §17.3), and this package passes them through.

Index

• func Execute(ctx context.Context, args []string, out, errOut io.Writer, in io.Reader) int
• func Root() *cobra.Command
• type App
• type Envelope
• type EnvelopeError
• type FocusReport
• type RenameReport
• type StatusReport

Functions

func Execute

func Execute(ctx context.Context, args []string, out, errOut io.Writer, in io.Reader) int

Execute runs the CLI and returns the process exit code.

The exit code is derived in ONE place, from the error's own classification, so no command can invent its own mapping. The two operations that deliberately deviate — run, which reports the command's status, and attach, which reports its client's — do so locally and say so in their help (behavior §12.1).

func Root

func Root() *cobra.Command

Root builds the command tree, for generating documentation and completions from the one definition rather than maintaining a second copy of it.

Types

type App

type App struct {
	Out io.Writer
	Err io.Writer
	In  io.Reader
	// contains filtered or unexported fields
}

An App holds the streams and options one invocation runs with.

type Envelope

type Envelope struct {
	// OK is always present, and is the only field a consumer needs to branch
	// on.
	OK bool `json:"ok"`
	// Backend is the RESOLVED backend, never the requested one, and is present
	// on failure too — a failure is exactly when knowing which backend
	// answered matters most (behavior §0.4).
	Backend backend.Name `json:"backend,omitempty"`
	// Data is the per-operation payload, absent for operations with none.
	Data any `json:"data,omitempty"`
	// Warnings is omitted when empty, never null.
	Warnings []olympus.Warning `json:"warnings,omitempty"`
	// Error is present exactly when OK is false.
	Error *EnvelopeError `json:"error,omitempty"`
}

An Envelope is the structured output shape of api §2.

One shape for every operation, success and failure alike. The alternative — bare per-operation payloads — cannot carry the two cross-cutting fields that must appear everywhere: the resolved backend and the degraded-operation warnings.

type EnvelopeError

type EnvelopeError struct {
	Code    backend.Code `json:"code"`
	Message string       `json:"message"`
}

An EnvelopeError carries a code from the §12 vocabulary.

type FocusReport

type FocusReport struct {
	Target string `json:"target"`
}

A FocusReport is what the focus verb emits.

type RenameReport

type RenameReport struct {
	Target string `json:"target"`
	Name   string `json:"name"`
}

A RenameReport is what the rename verb emits.

type StatusReport

type StatusReport struct {
	Session string `json:"session"`
	Status  string `json:"status"`
}

A StatusReport is what the status verb emits, in every mode.

Set and wait report the same shape as a plain read so a caller parsing the output does not need three parsers for one verb.