Help us shape the future of Go! Take the 2026 Go Developer Survey

app

package
v0.17.0 Latest Latest
Warning

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

 Go to latest Published: Oct 5, 2026 License: AGPL-3.0 Imports: 52 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 an interrupt or termination signal cancels. The application uses it for graceful shutdown.

func ExitOnError 

func ExitOnError(err error)

ExitOnError is a helper that prints an error and exits with status 1. Use it 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 an App with the given version information. It applies functional options to the default configuration.

func NewForCommand added in v0.17.0 

func NewForCommand(version, commit, date, builtBy string) *App

NewForCommand defers configuration until Cobra parses the command flags. Help and version flags remain available without a valid deployment configuration.

func (*App) AdministrationConfig added in v0.17.0 

func (a *App) AdministrationConfig() (administration.Config, error)

AdministrationConfig selects private server state and its catalog authority audience.

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) CatalogAcquisition added in v0.17.0 

func (a *App) CatalogAcquisition(client *starmap.Client) (*acquisition.Syncer, error)

CatalogAcquisition composes manual acquisition for CLI updates and HTTP requests. It applies the same provider binding set as the connected runtime. Source startup follows the configured runtime policy.

func (*App) CatalogPath 

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

CatalogPath returns the resolved human catalog workspace without creating it. An explicit empty canonical workspace disables the optional workspace.

func (*App) CatalogSettings added in v0.16.0 

func (a *App) CatalogSettings() settings.Config

CatalogSettings returns the canonical catalog settings that this process read. The report and the readiness answer name the same settings.

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) CompleteRuntimeMigration added in v0.17.0 

func (a *App) CompleteRuntimeMigration(ctx context.Context, request runtime.DirectoryMigrationRequest) (result runtime.DirectoryMigrationPublication, resultErr error)

CompleteRuntimeMigration verifies saved selection, opens the replacement, and records completion. The command closes its replacement runtime before returning.

func (*App) Config 

func (a *App) Config() *Config

Config returns the application configuration.

func (*App) ConfigurationReports added in v0.17.0 

func (a *App) ConfigurationReports() (*administration.Reports, error)

ConfigurationReports describes resolved configuration without opening the catalog runtime.

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) FileManifest added in v0.17.0 

func (a *App) FileManifest() (productpaths.FileManifest, error)

FileManifest reports selected locations without opening catalog state or creating files. Planned paths identify remaining features and do not imply current file support.

func (*App) InspectFiles added in v0.17.0 

func (a *App) InspectFiles(ctx context.Context, limit int) (productpaths.FileManifest, error)

InspectFiles adds bounded filesystem observations without opening application state.

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 catalog store from the configured human catalog workspace path into the CLI's machine state root.

func (*App) NewAdminCommand added in v0.17.0 

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

NewAdminCommand returns explicit local standalone administration commands.

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) NewConfigCommand added in v0.17.0 

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

NewConfigCommand returns passive configuration inspection commands.

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) PrepareRuntimeMigration added in v0.17.0 

func (a *App) PrepareRuntimeMigration(ctx context.Context, request runtime.DirectoryMigrationRequest) (runtime.DirectoryMigrationPreparation, error)

PrepareRuntimeMigration records an inventory with this process's selected owner.

func (*App) PublishRuntimeMigration added in v0.17.0 

func (a *App) PublishRuntimeMigration(ctx context.Context, request runtime.DirectoryMigrationRequest) (runtime.DirectoryMigrationPublication, error)

PublishRuntimeMigration publishes the replacement without editing host configuration.

func (*App) Readiness 

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

Readiness reports catalog availability and active embedded-bootstrap budgets.

func (*App) ResolveOperationPath added in v0.17.0 

func (a *App) ResolveOperationPath(value, field string) (string, error)

ResolveOperationPath resolves an explicit legacy command path before catalog access.

func (*App) ResolvedPaths added in v0.17.0 

func (a *App) ResolvedPaths() (ProductPaths, error)

ResolvedPaths uses the same directory resolution as application startup.

func (*App) Runtime added in v0.16.0 

func (a *App) Runtime(ctx context.Context, extra ...runtime.Option) (*runtime.Runtime, error)

Runtime returns the process-owned connected runtime. It opens the runtime once and reuses it. The runtime serves the verified embedded catalog at once and pulls the selected source in the background, so no command waits for the network. Extra options apply last, so a command overrides one setting.

func (*App) RuntimeStatus added in v0.16.0 

func (a *App) RuntimeStatus() runtime.Status

RuntimeStatus reports the connected-runtime status of this process. A process that opened no runtime reports the closed status.

func (*App) Shutdown 

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

Shutdown gracefully stops background tasks and releases resources. The context sets the timeout and can abort the shutdown.

func (*App) SourceDirectories added in v0.17.0 

func (a *App) SourceDirectories() (productpaths.SourceDirectories, error)

SourceDirectories returns the configured source cache and checkout roots without creating files.

func (*App) StageRuntimeMigration added in v0.17.0 

func (a *App) StageRuntimeMigration(ctx context.Context, request runtime.DirectoryMigrationRequest) (runtime.DirectoryMigrationStage, error)

StageRuntimeMigration verifies a private copy with this process's selected owner.

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
	// ConfigAccess selects the checked primary input policy independently of its contents.
	ConfigAccess string

	// PathValues retains the selected file's node directory and identity settings.
	PathValues map[string]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
	// CatalogValues retains canonical file values before environment resolution.
	CatalogValues map[string]string
	// CatalogOrigins and CatalogIgnored identify configuration authorities without values.
	CatalogOrigins map[string]string
	CatalogIgnored []catalogconfig.Ignored
	// DotenvConflicts lists safe duplicate-key diagnostics from explicit files.
	DotenvConflicts    []DotenvConflict
	LegacyCatalogNames []string

	// Logging configuration
	LogLevel  string
	LogFormat string
	LogOutput string
	// contains filtered or unexported fields
}

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. Explicit dotenv files loaded by command composition 4. config.yaml under the selected configuration root 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 DotenvConflict added in v0.17.0 

type DotenvConflict struct {
	Name         string
	ReplacedFile string
	SelectedFile string
}

DotenvConflict identifies a duplicate key without retaining either value.

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.

type ProductPaths added in v0.17.0 

type ProductPaths struct {
	Roots                   productpaths.Roots `json:"roots"`
	Configuration           productpaths.Path  `json:"configuration"`
	Workspace               productpaths.Path  `json:"workspace"`
	CatalogStore            productpaths.Path  `json:"catalog_store"`
	Runtime                 productpaths.Path  `json:"runtime"`
	CredentialPolicy        productpaths.Path  `json:"credential_policy"`
	Baselines               productpaths.Path  `json:"baselines"`
	SourceCache             productpaths.Path  `json:"source_cache"`
	SourceCheckout          productpaths.Path  `json:"source_checkout"`
	SourceFile              productpaths.Path  `json:"source_file,omitzero"`
	DeploymentID            string             `json:"deployment_id"`
	InstanceID              string             `json:"instance_id"`
	SchedulerIdentity       string             `json:"scheduler_identity,omitempty"`
	SchedulerIdentityOrigin string             `json:"scheduler_identity_origin"`
	RelativePathBase        string             `json:"relative_path_base"`
	RelativePathBaseOrigin  string             `json:"relative_path_base_origin"`
}

ProductPaths reports the selected roots and stable catalog paths without creating files.

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.