setup

package
v1.10.5 Latest Latest
Warning

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

 Go to latest Published: Apr 2, 2026 License: MIT Imports: 36 Imported by: 0

README

Setup

Bootstrapping logic for tool initialization and self-updating capabilities.

Features

  • Interactive tool initialization (init flow)
  • GitHub & GitLab authentication and SSH key management
  • Automated self-update system with pluggable release providers
  • Semantic version management

For detailed documentation and integration guides, see the Setup Component Documentation.

Documentation

Overview

Package setup provides initialisation helpers for GTB-based tools, including configuration directory bootstrapping, default config file creation, and self-update orchestration.

The Initialiser interface supports a modular hook-based pattern for extending the init process — SSH key setup, authentication configuration, and custom post-init steps can be composed and ordered. Update checks use semantic version comparison against the configured release source (GitHub or GitLab).

Package setup provides self-update and bootstrap functionality for GTB-based tools. This file registers all built-in release providers via blank imports so that they are available whenever pkg/setup is imported.

Index

Constants

View Source 
const (
	UpdatedKey = timeSinceKey("updated")
	CheckedKey = timeSinceKey("checked")
)
View Source 
const (
	DefaultConfigFilename = "config.yaml"
)

Variables

View Source 
var DefaultConfig []byte

Functions

func AddCommandWithMiddleware added in v1.6.0 

func AddCommandWithMiddleware(parent, cmd *cobra.Command, feature props.FeatureCmd)

AddCommandWithMiddleware adds a command to a parent and applies all registered middleware (global and feature-specific) to it and its subcommands.

func ApplyMiddlewareRecursively added in v1.6.0 

func ApplyMiddlewareRecursively(cmd *cobra.Command, feature props.FeatureCmd)

ApplyMiddlewareRecursively applies middleware to a command and all of its children recursively. This is useful when adding a command tree that was built outside of the standard GTB registration flow.

func Chain added in v1.6.0 

func Chain(feature props.FeatureCmd, runE func(cmd *cobra.Command, args []string) error) func(cmd *cobra.Command, args []string) error

Chain applies all registered middleware (global + feature-specific) to the given RunE function and returns the wrapped function.

func GetChecks added in v1.4.0 

func GetChecks() map[props.FeatureCmd][]CheckProvider

GetChecks returns all registered check providers.

func GetDefaultConfigDir 

func GetDefaultConfigDir(fs afero.Fs, name string) string

GetDefaultConfigDir returns the default config directory for the named tool (~/.toolname/).

func GetFeatureFlags 

func GetFeatureFlags() map[props.FeatureCmd][]FeatureFlag

GetFeatureFlags returns all registered feature flag providers.

func GetInitialisers 

func GetInitialisers() map[props.FeatureCmd][]InitialiserProvider

GetInitialisers returns all registered initialiser providers.

func GetSubcommands 

func GetSubcommands() map[props.FeatureCmd][]SubcommandProvider

GetSubcommands returns all registered subcommand providers.

func GetTimeSinceLast 

func GetTimeSinceLast(fs afero.Fs, name string, status timeSinceKey) time.Duration

GetTimeSinceLast returns the duration since the last update check or update.

func Initialise 

func Initialise(props *props.Props, opts InitOptions) (string, error)

Initialise creates the default configuration file in the specified directory.

func Register 

func Register(feature props.FeatureCmd, ips []InitialiserProvider, sps []SubcommandProvider, fps []FeatureFlag)

Register adds initialisers, subcommands, and flags for a specific feature.

func RegisterChecks added in v1.4.0 

func RegisterChecks(feature props.FeatureCmd, cps []CheckProvider)

RegisterChecks adds diagnostic check providers for a specific feature.

func RegisterGlobalMiddleware added in v1.6.0 

func RegisterGlobalMiddleware(mw ...Middleware)

RegisterGlobalMiddleware adds middleware that is applied to all feature commands. Global middleware runs before feature-specific middleware in the chain.

func RegisterMiddleware added in v1.6.0 

func RegisterMiddleware(feature props.FeatureCmd, mw ...Middleware)

RegisterMiddleware adds middleware that will be applied to commands belonging to the specified feature. Middleware is applied in registration order.

func ResetRegistryForTesting added in v1.6.0 

func ResetRegistryForTesting()

ResetRegistryForTesting clears the middleware registry. This should only be used in tests to avoid state leakage between test runs.

func Seal added in v1.6.0 

func Seal()

Seal prevents further middleware registration. Called after all commands have been registered.

func SetTimeSinceLast 

func SetTimeSinceLast(fs afero.Fs, name string, status timeSinceKey) error

SetTimeSinceLast records the current time as the last check or update timestamp.

func SkipUpdateCheck 

func SkipUpdateCheck(fs afero.Fs, name string, cmd *cobra.Command) bool

SkipUpdateCheck returns true if the update check should be skipped for this invocation.

func VerifyChecksum added in v1.8.0 

func VerifyChecksum(fs afero.Fs, sidecarPath string, data []byte) error

VerifyChecksum reads a SHA-256 sidecar file and verifies it against the provided data. The sidecar format is "<hex-hash> <filename>\n" (matching sha256sum output and GoReleaser checksums.txt entries). Returns nil if the checksum matches, or an error with a hint on mismatch.

Types

type CheckFunc added in v1.4.0 

type CheckFunc func(ctx context.Context, props *props.Props) CheckResult

CheckFunc is the signature for individual diagnostic checks.

type CheckProvider added in v1.4.0 

type CheckProvider func(p *props.Props) []CheckFunc

CheckProvider is a function that returns diagnostic checks for a feature.

type CheckResult added in v1.4.0 

type CheckResult struct {
	Name    string `json:"name"`
	Status  string `json:"status"`
	Message string `json:"message"`
	Details string `json:"details,omitempty"`
}

CheckResult represents the outcome of a single diagnostic check.

type FeatureFlag 

type FeatureFlag func(cmd *cobra.Command)

FeatureFlag is a function that registers flags on a cobra command.

type FeatureRegistry 

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

FeatureRegistry holds the registered initialisers, subcommands, flags, and checks for features.

type InitOptions 

type InitOptions struct {
	Dir          string
	Clean        bool
	SkipLogin    bool
	SkipKey      bool
	SkipAI       bool
	Initialisers []Initialiser
}

InitOptions holds the options for the Initialise function.

type Initialiser 

type Initialiser interface {
	// Name returns a human-readable name for logging.
	Name() string
	// IsConfigured returns true if this initialiser's config is already present.
	IsConfigured(cfg config.Containable) bool
	// Configure runs the interactive config and writes values into cfg.
	Configure(p *props.Props, cfg config.Containable) error
}

Initialiser is an optional config step that can check if it's already configured and, if not, interactively populate the shared viper config.

type InitialiserProvider 

type InitialiserProvider func(p *props.Props) Initialiser

InitialiserProvider is a function that creates an Initialiser.

type Middleware added in v1.6.0 

type Middleware func(next func(cmd *cobra.Command, args []string) error) func(cmd *cobra.Command, args []string) error

Middleware wraps a cobra RunE function with additional behaviour. The middleware receives the next handler in the chain and returns a new handler that may execute logic before and/or after calling next.

func WithAuthCheck added in v1.6.0 

func WithAuthCheck(keys ...string) Middleware

WithAuthCheck returns middleware that validates the specified configuration keys are non-empty before allowing command execution. If any key is empty, a descriptive error is returned without executing the command.

func WithRecovery added in v1.6.0 

func WithRecovery(l logger.Logger) Middleware

WithRecovery returns middleware that catches panics in the command handler and converts them to errors. The panic value and stack trace are logged at Error level.

func WithTelemetry added in v1.9.3 

func WithTelemetry(p *props.Props) Middleware

WithTelemetry returns middleware that automatically tracks command invocations via the telemetry collector on Props. Records command name, duration, and exit code for every command execution. No-op when the collector is nil or telemetry is disabled (the collector is a noop in that case).

func WithTiming added in v1.6.0 

func WithTiming(l logger.Logger) Middleware

WithTiming returns middleware that logs command execution duration.

type SelfUpdater 

type SelfUpdater struct {
	Tool props.Tool

	CurrentVersion string
	NextRelease    release.Release
	Fs             afero.Fs
	// contains filtered or unexported fields
}

SelfUpdater manages checking for and applying tool updates.

func NewOfflineUpdater added in v1.8.0 

func NewOfflineUpdater(tool props.Tool, log logger.Logger, fs afero.Fs) *SelfUpdater

NewOfflineUpdater creates a SelfUpdater configured for file-based updates that do not require a VCS client or network access.

func NewUpdater 

func NewUpdater(p *props.Props, version string, force bool) (*SelfUpdater, error)

NewUpdater creates a SelfUpdater configured with the tools release source.

func (*SelfUpdater) DownloadAsset 

func (s *SelfUpdater) DownloadAsset(ctx context.Context, asset release.ReleaseAsset) (bytes.Buffer, error)

DownloadAsset downloads the raw bytes of a release asset.

func (*SelfUpdater) GetCurrentVersion added in v1.6.0 

func (s *SelfUpdater) GetCurrentVersion() string

func (*SelfUpdater) GetLatestRelease 

func (s *SelfUpdater) GetLatestRelease(ctx context.Context) (release.Release, error)

func (*SelfUpdater) GetLatestVersionString 

func (s *SelfUpdater) GetLatestVersionString(ctx context.Context) (string, error)

func (*SelfUpdater) GetReleaseNotes 

func (s *SelfUpdater) GetReleaseNotes(ctx context.Context, from string, to string) (string, error)

GetReleaseNotes retrieves the release notes for releases between the specified 'from' and 'to' versions (inclusive).

func (*SelfUpdater) GetStructuredReleaseNotes added in v1.8.0 

func (s *SelfUpdater) GetStructuredReleaseNotes(ctx context.Context, from, to string, archive ...bytes.Buffer) (*changelog.Changelog, error)

GetStructuredReleaseNotes retrieves release notes between two versions and returns them as a parsed Changelog. If an archive buffer is provided, it attempts to extract a bundled CHANGELOG.md first, falling back to per-release API calls when the archive contains no changelog.

func (*SelfUpdater) IsLatestVersion 

func (s *SelfUpdater) IsLatestVersion(ctx context.Context) (bool, string, error)

IsLatestVersion checks if the current running binary is the latest version.

func (*SelfUpdater) Update 

func (s *SelfUpdater) Update(ctx context.Context) (string, error)

Update installs the latest version of the binary to the resolved target path.

func (*SelfUpdater) UpdateFromFile added in v1.8.0 

func (s *SelfUpdater) UpdateFromFile(filePath string) (string, error)

UpdateFromFile installs a binary from a local .tar.gz file. If a .sha256 sidecar file exists at filePath+".sha256", the checksum is verified before extraction. Returns the installation target path.

type SubcommandProvider 

type SubcommandProvider func(p *props.Props) []*cobra.Command

SubcommandProvider is a function that creates a slice of cobra subcommands.

Source Files

View all Source files

Directories

Path Synopsis
Package ai provides factory functions that construct chat.ChatClient instances from Props configuration, resolving the configured provider (Claude, OpenAI, Gemini) and wiring API keys, model selection, and token limits for use in documentation generation and agentic verification loops.
 Package ai provides factory functions that construct chat.ChatClient instances from Props configuration, resolving the configured provider (Claude, OpenAI, Gemini) and wiring API keys, model selection, and token limits for use in documentation generation and agentic verification loops.
Package github provides GitHub-specific setup helpers including token resolution from configuration and environment, and authenticated HTTP client construction for use with the GitHub API.
 Package github provides GitHub-specific setup helpers including token resolution from configuration and environment, and authenticated HTTP client construction for use with the GitHub API.
Package telemetry registers the telemetry initialiser with the setup system.
 Package telemetry registers the telemetry initialiser with the setup system.

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.