app

README

docs

Documentation

Overview

Package app is the urfave/cli/v3 framework shared by gomatic CLIs. It supplies the generic, command-agnostic glue — the runner/action combinators, the logger-in-metadata convention, the standard global flags, and the run harness — and nothing tied to any one command. Command-specific flags, errors, and trees stay in their own repositories.

Index

• Constants
• func Default[C, R any](cfg *C, runner Runner[C, R]) func(context.Context, *cli.Command) error
• func GetLogger(c *cli.Command) *slog.Logger
• func Interactive[C, R any](cfg *C, runner Runner[C, R]) func(context.Context, *cli.Command) error
• func LoggerBefore(getLogger GetLoggerFunc) func(context.Context, *cli.Command) (context.Context, error)
• func OutputFlag(envPrefix EnvPrefix) cli.Flag
• func Run(ctx context.Context, cmd *cli.Command, args []string, exit func(int))
• type EnvPrefix
• type GetLoggerFunc
• type LoggerFlags
  • func (f LoggerFlags) FormatFlag(def log.Format) cli.Flag
  • func (f LoggerFlags) LevelFlag() cli.Flag
• type Runner

Constants

const LoggerMetadataKey = "logger"

LoggerMetadataKey is the cli.Command metadata key under which the configured logger is stored for retrieval by command actions.

Functions

func Default

func Default[C, R any](cfg *C, runner Runner[C, R]) func(context.Context, *cli.Command) error

Default binds a config pointer and runner into a cli action function.

func GetLogger

func GetLogger(c *cli.Command) *slog.Logger

GetLogger returns the logger stored in the root command metadata, or slog.Default when absent or the command is nil.

func Interactive

func Interactive[C, R any](cfg *C, runner Runner[C, R]) func(context.Context, *cli.Command) error

Interactive binds a config pointer and runner into a cli action function for a command that owns its output — an interactive REPL, say — and so has no result for the app tier to render. The runner's result is intentionally discarded; only its error propagates. Use Default whenever the command produces a result to encode; result rendering is the common case, not a requirement.

func LoggerBefore

func LoggerBefore(getLogger GetLoggerFunc) func(context.Context, *cli.Command) (context.Context, error)

LoggerBefore returns a cli Before hook that stores the logger built by getLogger in the root command metadata, where GetLogger then finds it.

func OutputFlag

func OutputFlag(envPrefix EnvPrefix) cli.Flag

OutputFlag returns the standard --output/-o global flag selecting the result encoding, sourced from <envPrefix>OUTPUT and defaulting to json. The action combinator reads it to encode each command's result.

func Run

func Run(ctx context.Context, cmd *cli.Command, args []string, exit func(int))

Run executes cmd with signal-aware cancellation (SIGINT/SIGTERM), logging a non-nil error under the command's name and exiting non-zero via exit. The args and exit function are injected so a main can be exercised in tests.

Types

type EnvPrefix

type EnvPrefix string

EnvPrefix is the namespace prepended to each standard flag's environment variable source (e.g. "APP_" yields APP_LOG_LEVEL, APP_LOG_FORMAT, APP_OUTPUT).

type GetLoggerFunc

type GetLoggerFunc func(*cli.Command) *slog.Logger

GetLoggerFunc retrieves a logger for a command; injected so mains and tests can substitute one.

type LoggerFlags

type LoggerFlags struct {
	// Config receives the parsed flag values; it must be non-nil.
	Config *log.LoggerConfig
	// EnvPrefix namespaces the flags' environment variable sources.
	EnvPrefix EnvPrefix
}

LoggerFlags binds the standard logging flags to a shared logger configuration. The config pointer is carried as a field (the binder pattern) so the flag constructors take no pointer parameters; each flag's Destination still writes through to Config as the command line is parsed.

func (LoggerFlags) FormatFlag

func (f LoggerFlags) FormatFlag(def log.Format) cli.Flag

FormatFlag returns the standard --log-format global flag, sourced from <EnvPrefix>LOG_FORMAT, bound to Config, defaulting to def (consumers differ: a CLI defaults to text, a daemon to json).

func (LoggerFlags) LevelFlag

func (f LoggerFlags) LevelFlag() cli.Flag

LevelFlag returns the standard --log-level global flag, sourced from <EnvPrefix>LOG_LEVEL and bound to Config.

type Runner

type Runner[CONFIG any, RESULT any] func(context.Context, *slog.Logger, CONFIG, ...string) (RESULT, error)

Runner executes a command's work: it receives the bound config and positional arguments and returns a result to be encoded. Implementations live in the orchestration (domain) packages of each consumer.