app

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 11, 2026 License: AGPL-3.0 Imports: 34 Imported by: 0

Documentation

Overview

Package app provides the application context and dependency management for the starmap CLI. It follows idiomatic Go patterns for CLI applications by centralizing configuration, dependency injection, and lifecycle management.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Context 

func Context() (context.Context, context.CancelFunc)

Context creates a new context with signal handling for the application. This is a convenience wrapper around ContextWithSignals that uses context.Background() as the parent.

func ContextWithSignals 

func ContextWithSignals(parent context.Context) (context.Context, context.CancelFunc)

ContextWithSignals creates a context that is cancelled when the application receives an interrupt or termination signal. This enables graceful shutdown.

func ExitOnError 

func ExitOnError(err error)

ExitOnError is a helper that prints an error and exits with status 1. This is meant to be used in main.go for top-level error handling.

func NewLogger 

func NewLogger(config *Config) zerolog.Logger

NewLogger creates a configured logger based on the application configuration. Log level precedence (highest to lowest):

  1. --log-level flag (explicit always wins)
  2. -v/--verbose flag (shortcut for debug)
  3. -q/--quiet flag (shortcut for warn)
  4. LOG_LEVEL environment variable
  5. Default (info)

Types

type App 

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

App represents the starmap application with all its dependencies. It provides a centralized place for configuration, logging, and the starmap instance, following the dependency injection pattern.

func New 

func New(version, commit, date, builtBy string, opts ...Option) (*App, error)

New creates a new App instance with the given version information. The app is initialized with default configuration that can be customized using functional options.

func (*App) BuiltBy 

func (a *App) BuiltBy() string

BuiltBy returns the build system identifier.

func (*App) Catalog 

func (a *App) Catalog() (*catalogs.Catalog, error)

Catalog returns the current immutable catalog from the starmap instance. This is a convenience method that handles the starmap initialization and catalog retrieval in one call.

Thread Safety: sm.Catalog atomically loads an immutable generation. Collection reads return caller-owned copies behind interfaces that expose no mutation methods.

func (*App) CatalogPath 

func (a *App) CatalogPath() (string, error)

CatalogPath returns the configured human provider-YAML workspace, or the canonical per-user default when no override is configured.

func (*App) CatalogState 

func (a *App) CatalogState() (starmap.CatalogState, error)

CatalogState atomically returns the current catalog and generation identity.

func (*App) Commit 

func (a *App) Commit() string

Commit returns the git commit hash.

func (*App) Config 

func (a *App) Config() *Config

Config returns the application configuration.

func (*App) CredentialResolver added in v0.4.0 

func (a *App) CredentialResolver() (sources.ProviderCredentialResolver, error)

CredentialResolver returns the process-owned catalog-acquisition resolver. One resolver owns source caching and single-flight refresh for the process.

func (*App) Date 

func (a *App) Date() string

Date returns the build date.

func (*App) Execute 

func (a *App) Execute(ctx context.Context, args []string) error

Execute runs the starmap CLI application with the given arguments. This is the main entry point called from main.go.

func (*App) Logger 

func (a *App) Logger() *zerolog.Logger

Logger returns the application logger.

func (*App) MigrateCatalogWorkspace 

func (a *App) MigrateCatalogWorkspace(ctx context.Context) (workspace.LegacyLayoutMigrationResult, error)

MigrateCatalogWorkspace explicitly relocates the pre-plan generation store from the configured human workspace path into the CLI's machine state root.

func (*App) NewAuthCommand 

func (a *App) NewAuthCommand() *cobra.Command

NewAuthCommand returns a new auth command with app dependencies.

func (*App) NewAuthorsCommand 

func (a *App) NewAuthorsCommand() *cobra.Command

NewAuthorsCommand returns a new authors command with app dependencies.

func (*App) NewCompletionCommand 

func (a *App) NewCompletionCommand() *cobra.Command

NewCompletionCommand returns a new completion command. This overrides Cobra's auto-generated completion command to add install/uninstall subcommands.

func (*App) NewDepsCommand 

func (a *App) NewDepsCommand() *cobra.Command

NewDepsCommand returns a new deps command with app dependencies.

func (*App) NewEmbedCommand 

func (a *App) NewEmbedCommand() *cobra.Command

NewEmbedCommand returns a new embed command with app dependencies.

func (*App) NewManCommand 

func (a *App) NewManCommand() *cobra.Command

NewManCommand returns a new man command.

func (*App) NewMigrateCommand 

func (a *App) NewMigrateCommand() *cobra.Command

NewMigrateCommand returns the explicit local-storage migration command.

func (*App) NewModelsCommand 

func (a *App) NewModelsCommand() *cobra.Command

NewModelsCommand returns a new models command with app dependencies.

func (*App) NewProvidersCommand 

func (a *App) NewProvidersCommand() *cobra.Command

NewProvidersCommand returns a new providers command with app dependencies.

func (*App) NewServeCommand 

func (a *App) NewServeCommand() *cobra.Command

NewServeCommand returns a new serve command with app dependencies.

func (*App) NewUpdateCommand 

func (a *App) NewUpdateCommand() *cobra.Command

NewUpdateCommand returns a new update command with app dependencies.

func (*App) NewValidateCommand 

func (a *App) NewValidateCommand() *cobra.Command

NewValidateCommand returns a new validate command with app dependencies.

func (*App) NewVersionCommand 

func (a *App) NewVersionCommand() *cobra.Command

NewVersionCommand returns a new version command.

func (*App) OutputFormat 

func (a *App) OutputFormat() string

OutputFormat returns the configured output format.

func (*App) Readiness 

func (a *App) Readiness() (starmap.CatalogReadiness, error)

Readiness reports catalog availability and active embedded-bootstrap budgets.

func (*App) Shutdown 

func (a *App) Shutdown(ctx context.Context) error

Shutdown performs graceful shutdown of the application. It stops any running background tasks and cleans up resources. The context controls the shutdown timeout - shutdown will abort if context is cancelled.

func (*App) Starmap 

func (a *App) Starmap(opts ...starmap.Option) (*starmap.Client, error)

Starmap returns the starmap instance with optional configuration. When called without options, returns the default cached instance (lazy-initialized, thread-safe). When called with options, creates a new instance with custom configuration (no caching).

func (*App) Version 

func (a *App) Version() string

Version returns the version information.

type Config 

type Config struct {
	// Global flags
	Verbose bool
	Quiet   bool
	NoColor bool
	Output  string

	// Config file
	ConfigFile string

	// Starmap configuration
	// CatalogPath is the human-editable provider YAML workspace.
	CatalogPath                   string
	EmbeddedBootstrapMaxAge       time.Duration
	EmbeddedBootstrapMaxSizeBytes int64
	RemoteServerURL               string
	RemoteServerAPIKey            string
	RemoteServerOnly              bool
	CredentialSources             map[string]map[string]CredentialSourceConfig

	// Logging configuration
	LogLevel  string
	LogFormat string
	LogOutput string
}

Config holds the application configuration loaded from various sources including config files, environment variables, and .env files.

func LoadConfig 

func LoadConfig() (*Config, error)

LoadConfig loads configuration from all sources in order of precedence: 1. Command-line flags (handled by cobra) 2. Environment variables 3. .env files 4. Config file (~/.starmap/config.yaml) 5. Defaults.

type CredentialSourceConfig added in v0.4.0 

type CredentialSourceConfig struct {
	Reference       string `mapstructure:"reference"`
	FallbackAmbient bool   `mapstructure:"fallback_ambient"`
}

CredentialSourceConfig selects one explicit provider-field source.

type Option 

type Option func(*App) error

Option is a functional option for configuring the App.

func WithClient 

func WithClient(sm *starmap.Client) Option

WithClient sets a custom starmap instance (useful for testing).

func WithConfig 

func WithConfig(config *Config) Option

WithConfig sets a custom configuration.

func WithLogger 

func WithLogger(logger *zerolog.Logger) Option

WithLogger sets a custom logger.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.