Documentation
¶
Overview ¶
Package prepare provides a standalone function for loading and preparing a solution for execution. It decouples solution preparation from CLI-specific types, making it reusable by both CLI commands and the MCP server.
Index ¶
- func BuildPluginFetcher(ctx context.Context) (*plugin.Fetcher, error)
- func BuildPluginFetcherWithConfig(ctx context.Context, override PluginFetcherOverrides) (*plugin.Fetcher, error)
- func NewDefaultGetter(ctx context.Context, noCache bool) get.Interface
- func ResolveOfficialAuthHandlers(ctx context.Context, authReg *auth.Registry, cooldown *plugin.FetchCooldown, ...) ([]*plugin.AuthHandlerClient, error)
- func ResolveOfficialProviders(ctx context.Context, sol *solution.Solution, reg *provider.Registry, ...) ([]*plugin.Client, error)
- type Option
- func WithAuthRegistry(r *auth.Registry) Option
- func WithClientOptions(opts ...plugin.ClientOption) Option
- func WithDiscoveryMode(mode settings.DiscoveryMode) Option
- func WithGetter(g get.Interface) Option
- func WithLockPlugins(plugins []bundler.LockPlugin) Option
- func WithMetrics(out io.Writer) Option
- func WithNoCache() Option
- func WithOfficialAuthHandlers(r *authofficial.Registry) Option
- func WithOfficialProviders(r *official.Registry) Option
- func WithPluginConfig(cfg *plugin.ProviderConfig) Option
- func WithPluginFetcher(f *plugin.Fetcher) Option
- func WithPluginPool(p *plugin.Pool) Option
- func WithRegistry(r *provider.Registry) Option
- func WithStdin(r io.Reader) Option
- func WithStrict(strict bool) Option
- type PluginFetcherOverrides
- type Result
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildPluginFetcher ¶ added in v0.14.0
BuildPluginFetcher creates a plugin.Fetcher from the context's config and auth registry. Returns an error when the catalog chain cannot be built. Callers should treat errors as non-fatal: plugin auto-fetch is simply disabled.
func BuildPluginFetcherWithConfig ¶ added in v0.14.0
func BuildPluginFetcherWithConfig(ctx context.Context, override PluginFetcherOverrides) (*plugin.Fetcher, error)
BuildPluginFetcherWithConfig creates a plugin.Fetcher from the context's config and auth registry, applying optional overrides for policy fields. Catalog, BinaryName, Logger, and Cache are always derived from context.
func NewDefaultGetter ¶ added in v0.8.0
NewDefaultGetter creates a default solution getter with catalog and remote resolution support. When noCache is true, the artifact cache is disabled so the catalog is always queried directly.
func ResolveOfficialAuthHandlers ¶ added in v0.14.0
func ResolveOfficialAuthHandlers( ctx context.Context, authReg *auth.Registry, cooldown *plugin.FetchCooldown, pluginCfg *plugin.ProviderConfig, clientOpts ...plugin.ClientOption, ) ([]*plugin.AuthHandlerClient, error)
ResolveOfficialAuthHandlers fetches all official auth handlers that are not already registered in the auth registry. Unlike the solution-level autoResolveOfficialAuthHandlers (which only resolves handlers referenced in a solution), this function resolves ALL missing official handlers to support direct CLI commands like "scafctl auth login github".
It reads the official auth handler registry and auth registry from context, builds a plugin fetcher on demand, and uses the provided FetchCooldown to skip recently-failed fetches.
Returns the auth handler plugin clients created (caller must defer Kill on each), or nil when no handlers needed resolution or fetching was not possible.
func ResolveOfficialProviders ¶ added in v0.14.0
func ResolveOfficialProviders(ctx context.Context, sol *solution.Solution, reg *provider.Registry, clientOpts ...plugin.ClientOption) ([]*plugin.Client, error)
ResolveOfficialProviders fetches any official providers referenced by the solution that are missing from the registry. It reads the official provider registry from context and builds a plugin fetcher on demand. Returns the plugin clients created (caller must defer Kill on each), or nil when no providers needed resolution or fetching failed non-fatally.
Types ¶
type Option ¶
type Option func(*prepareConfig)
Option configures the PrepareSolution function.
func WithAuthRegistry ¶
WithAuthRegistry provides an auth handler registry for registering auth handler plugins. If not set, auth handler plugin loading is skipped.
func WithClientOptions ¶ added in v0.8.0
func WithClientOptions(opts ...plugin.ClientOption) Option
WithClientOptions provides options for plugin client creation, such as host-side dependencies (secrets, auth) for callback services.
func WithDiscoveryMode ¶ added in v0.10.0
func WithDiscoveryMode(mode settings.DiscoveryMode) Option
WithDiscoveryMode sets the discovery mode used when auto-discovering solution files. See settings.DiscoveryMode for available modes.
func WithGetter ¶
WithGetter provides a custom solution getter. If not set, one is created from context (with catalog resolution support).
func WithLockPlugins ¶
func WithLockPlugins(plugins []bundler.LockPlugin) Option
WithLockPlugins provides lock file plugin entries for reproducible plugin resolution. When provided, pinned versions and digests are used instead of resolving constraints against catalogs.
func WithMetrics ¶
WithMetrics enables metrics collection and specifies where to write metrics output.
func WithNoCache ¶ added in v0.6.0
func WithNoCache() Option
WithNoCache disables artifact caching when loading solutions from the catalog. When set, the catalog is always queried directly, bypassing the filesystem cache.
func WithOfficialAuthHandlers ¶ added in v0.14.0
func WithOfficialAuthHandlers(r *authofficial.Registry) Option
WithOfficialAuthHandlers provides an official auth handler registry for auto-resolving missing auth handlers at runtime. When set (and strict is false), auth handlers referenced by the identity provider that are not in the auth registry are checked against the official list and auto-fetched via the plugin fetcher.
func WithOfficialProviders ¶ added in v0.14.0
WithOfficialProviders provides an official provider registry for auto-resolving missing providers at runtime. When set (and strict is false), providers not found in the registry are checked against the official list and auto-fetched via the plugin fetcher.
func WithPluginConfig ¶ added in v0.8.0
func WithPluginConfig(cfg *plugin.ProviderConfig) Option
WithPluginConfig provides configuration that is sent to plugin providers after registration via ConfigureProvider. If not set, plugins use defaults.
func WithPluginFetcher ¶
WithPluginFetcher provides a plugin fetcher for auto-fetching plugin binaries from catalogs at runtime. If not set, plugin auto-fetching is skipped (plugins must be available via --plugin-dir).
func WithPluginPool ¶ added in v0.29.0
WithPluginPool delegates provider plugin lifecycle to a shared, long-lived plugin pool instead of fetching, registering, and killing plugin processes per call. This is the correct mode for long-lived servers (MCP, HTTP API): the pool registers provider wrappers into the shared registry exactly once and keeps the processes alive across requests, while each prepared solution merely acquires a reference for its lifetime and releases (never kills) it on cleanup. This prevents registry poisoning where a per-request Kill would leave dead-backed provider wrappers in a registry shared by future requests.
The pool MUST have been constructed with the same provider registry passed via WithRegistry. When nil, prepare falls back to the per-call fetch/register/kill behavior suitable for one-shot CLI invocations.
func WithRegistry ¶
WithRegistry provides a custom provider registry. If not set, builtin.DefaultRegistry is used.
func WithStrict ¶ added in v0.14.0
WithStrict disables auto-resolution of official providers. When strict is true, missing providers produce an error instructing the user to declare them explicitly in bundle.plugins.
type PluginFetcherOverrides ¶ added in v0.14.0
type PluginFetcherOverrides struct {
// AllowedCatalogs restricts which catalog names plugins may be fetched from
// (Fetcher-level post-resolve check, belt-and-suspenders).
AllowedCatalogs []string
// ChainAllowedCatalogs restricts which catalogs are included in the chain
// during construction. Catalogs not in this list are excluded entirely.
ChainAllowedCatalogs []string
// PerCatalogArtifacts restricts which artifact names each catalog may serve.
// Keys are catalog names, values describe the policy for that catalog.
// Each matching catalog is wrapped with an AllowlistCatalog decorator.
PerCatalogArtifacts map[string]catalog.PluginPolicy
// Cache overrides the local plugin cache. When nil, a default unbounded
// cache is created inside the Fetcher.
Cache *plugin.Cache
// Platform overrides the target platform. If empty, auto-detected.
Platform string
// NoCache bypasses the local cache when true.
NoCache bool
// SignaturePolicy overrides the signature verification policy derived
// from config. When non-nil, takes precedence over config values.
SignaturePolicy *plugin.SignaturePolicy
}
PluginFetcherOverrides holds the subset of FetcherConfig fields that BuildPluginFetcherWithConfig can override. Other fields (Catalog, BinaryName, Logger, Cache) are always derived from context.
type Result ¶
type Result struct {
// Solution is the loaded and prepared solution.
Solution *solution.Solution `json:"solution" yaml:"solution" doc:"The loaded solution"`
// Registry is the provider registry with all providers registered,
// including the solution provider.
Registry *provider.Registry `json:"-" yaml:"-"`
// SolutionDir is the directory containing the solution file, resolved to
// an absolute path. Empty when loaded from stdin or a catalog reference.
// Callers can use this to set provider.WithSolutionDirectory for relative
// path resolution during execution.
SolutionDir string `json:"solutionDir,omitempty" yaml:"solutionDir,omitempty" doc:"Directory containing the solution file"`
// Cleanup must be deferred by the caller. It handles temp directory
// removal, working directory restoration, and metrics output.
Cleanup func() `json:"-" yaml:"-"`
// DiscoveredFrom holds metadata about how the solution file was discovered.
// Only populated when auto-discovery is used (path was empty).
DiscoveredFrom get.DiscoveryResult `json:"-" yaml:"-"`
// ProviderCtx enriches a context with solution provider dependencies
// (loader, registry, plugin deps, client tracker). Callers must apply
// this to the execution context before running resolvers or actions so
// the solution provider can resolve sub-solutions. May be nil when no
// solution provider is registered.
ProviderCtx func(ctx context.Context) context.Context `json:"-" yaml:"-"`
}
Result holds the output of PrepareSolution.
func Solution ¶
Solution loads a solution from the given path, extracts any bundle, merges plugin defaults, sets up the provider registry, and registers the solution provider. The returned Result.Cleanup function must be deferred.
This function is the standalone equivalent of the CLI's sharedResolverOptions.prepareSolutionForExecution method, decoupled from CLI-specific types so it can be used by the MCP server and other callers.
Source Files