cli

Documentation

Overview

Package cli implements the stacktower command-line interface.

Index

• Constants
• Variables
• func ExitCodeForError(err error) int
• func NewSystemError(message string, hint string) error
• func NewUserError(message string, hint string) error
• func WrapSystemError(cause error, message string, hint string) error
• func WrapUserError(cause error, message string, hint string) error
• type CLI
  • func New(w io.Writer, level log.Level) (*CLI, error)
  • func (c *CLI) AttachOrderingSpinner(s *ui.Spinner)
  • func (c *CLI) RootCommand() *cobra.Command
  • func (c *CLI) SetLogLevel(level log.Level)
  • func (c *CLI) SetQuiet(q bool)
• type CLIError
  • func (e *CLIError) Error() string
  • func (e *CLIError) Unwrap() error
• type ErrorKind
• type VulnError
  • func (e *VulnError) Error() string

Constants

const (
	LogDebug = log.DebugLevel
	LogInfo  = log.InfoLevel
)

Log levels exported for use in main.go.

const (
	// ExitCodeFailure is a generic runtime failure.
	ExitCodeFailure = 1
	// ExitCodeUsage indicates invalid input/usage from the caller.
	ExitCodeUsage = 2
	// ExitCodeVuln signals that new vulnerabilities were detected (used by diff --fail-on-vuln).
	ExitCodeVuln = 3
	// ExitCodeInterrupted follows shell convention for SIGINT/SIGTERM.
	ExitCodeInterrupted = 130
)

const (
	FormatText = "text"
	FormatJSON = "json"
)

Format constants for the "text | json" output switch used by analysis commands (why, stats, diff, sbom). Centralizing these keeps help text and default values aligned across commands.

Variables

var ErrCancelled = errors.New("operation cancelled")

var ErrNotLoggedIn = errors.New("not logged in")

ErrNotLoggedIn is a sentinel used by loadGitHubSession when no session exists. Checked structurally via errors.Is in the login flow.

Functions

func ExitCodeForError

func ExitCodeForError(err error) int

ExitCodeForError maps errors to stable process exit codes.

Mapping:

• nil → 0
• context.Canceled → 130 (SIGINT/SIGTERM convention)
• VulnError → 3 (diff --fail-on-vuln)
• CLIError{Kind:User} → 2 (usage/input errors)
• anything else → 1 (generic runtime failure)

Note: context.DeadlineExceeded intentionally maps to 1 (runtime failure), not 130, because a timeout is typically a system/network condition rather than a user-initiated interrupt.

func NewSystemError

func NewSystemError(message string, hint string) error

NewSystemError constructs an execution/network/runtime error with optional hint.

func NewUserError

func NewUserError(message string, hint string) error

NewUserError constructs a usage/input error with an optional actionable hint.

func WrapSystemError

func WrapSystemError(cause error, message string, hint string) error

WrapSystemError wraps a cause as an execution/network/runtime error.

func WrapUserError

func WrapUserError(cause error, message string, hint string) error

WrapUserError wraps a cause as a usage/input error.

Types

type CLI

type CLI struct {
	Logger *log.Logger
	// contains filtered or unexported fields
}

CLI holds shared state for all commands.

NOTE: ui.SetQuiet and observability.Set*Hooks are package-global, so only one CLI instance can be active per process. This is fine for a CLI binary but means tests that construct multiple CLI values cannot run in parallel with different quiet/log configurations. New returns an error on a second call to catch accidental double-initialization (e.g. a test constructing two CLI values without coordinating globals).

func New

func New(w io.Writer, level log.Level) (*CLI, error)

New creates a new CLI instance with a default logger. Registers observability hooks for pipeline and security events.

Only one CLI instance may be created per process; calling New a second time returns an error. The stacktower binary only creates one CLI, and tests that need to validate behavior across multiple configurations should do so through the single instance rather than constructing several.

func (*CLI) AttachOrderingSpinner

func (c *CLI) AttachOrderingSpinner(s *ui.Spinner)

AttachOrderingSpinner wires a spinner to receive ordering-progress updates via the pipeline hook. Pass nil (e.g. in a defer) to detach. The hook only ever knows about the ui.Spinner through this seam; the ordering algorithm itself stays free of CLI/TTY dependencies.

func (*CLI) RootCommand

func (c *CLI) RootCommand() *cobra.Command

RootCommand creates the root cobra command with all subcommands registered.

func (*CLI) SetLogLevel

func (c *CLI) SetLogLevel(level log.Level)

SetLogLevel updates the logger's level.

func (*CLI) SetQuiet

func (c *CLI) SetQuiet(q bool)

SetQuiet suppresses non-essential CLI output (success messages, stats, hints).

type CLIError

type CLIError struct {
	Kind    ErrorKind
	Message string
	Hint    string
	Cause   error
}

CLIError is a structured CLI-facing error.

func (*CLIError) Error

func (e *CLIError) Error() string

func (*CLIError) Unwrap

func (e *CLIError) Unwrap() error

type ErrorKind

type ErrorKind string

ErrorKind classifies CLI failures for exit-code mapping.

const (
	ErrorKindUser   ErrorKind = "user"
	ErrorKindSystem ErrorKind = "system"
)

type VulnError

type VulnError struct {
	Count int
}

VulnError is returned when --fail-on-vuln detects new vulnerabilities. It maps to ExitCodeVuln (3) via ExitCodeForError.

func (*VulnError) Error

func (e *VulnError) Error() string