cli

Documentation

Overview

Package cli implements BatchWeaver's command-line interface using only the standard library.

The design keeps output injectable and avoids os.Exit inside library code: App.Run returns a typed ExitCode that the executable maps to a process exit status. This makes every command deterministically testable. The command set is intentionally minimal in the bootstrap; only functionality that actually exists is advertised.

Index

• type App
  • func New(stdout, stderr io.Writer) *App
  • func (a *App) Run(ctx context.Context, args []string) ExitCode
  • func (a *App) Stderr() io.Writer
  • func (a *App) Stdout() io.Writer
• type Command
• type CommandError
  • func (e *CommandError) Error() string
• type ExitCode

Types

type App

type App struct {
	// contains filtered or unexported fields
}

App is a BatchWeaver CLI instance. Construct it with New. Output is written to the configured writers so tests can capture it.

func New

func New(stdout, stderr io.Writer) *App

New returns an App that writes to stdout and stderr. It registers the commands available in this build.

func (*App) Run

func (a *App) Run(ctx context.Context, args []string) ExitCode

Run executes the CLI with the given arguments, which must exclude the program name (that is, pass os.Args[1:]). It returns a typed ExitCode and never calls os.Exit.

func (*App) Stderr

func (a *App) Stderr() io.Writer

Stderr returns the writer used for standard error.

func (*App) Stdout

func (a *App) Stdout() io.Writer

Stdout returns the writer used for standard output.

type Command

type Command struct {
	// Name is the token used to invoke the command, for example "version".
	Name string
	// Summary is a one-line description shown in the command list.
	Summary string
	// Usage is a short usage string, excluding the program name.
	Usage string
	// Run executes the command with the arguments that follow the command name.
	// It returns an error on failure; it must not call os.Exit.
	Run func(ctx context.Context, app *App, args []string) error
}

Command is a single BatchWeaver subcommand. Commands are values with no hidden global state; everything they need is passed through the App and their arguments.

type CommandError

type CommandError struct {
	// Code is the exit code to use.
	Code ExitCode
	// Message, when non-empty, is written to stderr by the CLI.
	Message string
}

CommandError lets a command control the process exit code and whether the CLI prints a generic error line. A command that has already written its own output (for example rendered diagnostics) returns a CommandError with an empty Message so nothing further is printed.

func (*CommandError) Error

func (e *CommandError) Error() string

Error implements the error interface.

type ExitCode

type ExitCode int

ExitCode is a typed process exit status. Library code returns an ExitCode rather than calling os.Exit, so that behavior stays testable; the executable entry point performs the single os.Exit call.

const (
	// ExitOK indicates successful execution.
	ExitOK ExitCode = 0
	// ExitError indicates an internal or unexpected runtime error.
	ExitError ExitCode = 1
	// ExitUsage indicates the command line was used incorrectly, for example an
	// unknown command or bad flags.
	ExitUsage ExitCode = 2
	// ExitConfigInvalid indicates the configuration was loaded but is invalid.
	ExitConfigInvalid ExitCode = 3
	// ExitConfigNotFound indicates no configuration file was found.
	ExitConfigNotFound ExitCode = 4
	// ExitStale indicates a stale analysis, proof, source, or plan.
	ExitStale ExitCode = 5
	// ExitGoCommand indicates the underlying Go command reported failure.
	ExitGoCommand ExitCode = 6
	// ExitMaterialize indicates a materialization or revert conflict.
	ExitMaterialize ExitCode = 7
)