plugin

type AppContext ¶

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

AppContext is the public API available to plugins. It is immutable — constructed once per command run by the framework, then read-only.

ServiceDir is the resolved absolute path; use it for runtime file I/O. For pipeline artifact paths (CI templates), use Config.ServiceDir which preserves the original relative value from .terraci.yaml.

The Config returned by Config() is shared and must be treated as read-only by plugins. Mutate a deep copy if a plugin needs to derive a configuration.

AppContext is safe for concurrent reads from any goroutine because all fields are written exactly once at construction.

func FromContext(ctx context.Context) *AppContext

appCtx := plugin.FromContext(cmd.Context())

func NewAppContext(opts AppContextOptions) *AppContext

func (ctx *AppContext) Config() *config.Config

func (ctx *AppContext) Reports() *ReportRegistry

func (ctx *AppContext) Resolver() Resolver

func (ctx *AppContext) ServiceDir() string

func (ctx *AppContext) Version() string

func (ctx *AppContext) WorkDir() string

type AppContextOptions ¶ added in v0.10.0

type AppContextOptions struct {
	// Config is the loaded TerraCi configuration. Treated as read-only.
	Config *config.Config
	// WorkDir is the project working directory for the current command.
	WorkDir string
	// ServiceDir is the resolved absolute service directory path.
	ServiceDir string
	// Version is the current TerraCi version string.
	Version string
	// Reports is the shared in-process report registry. Defaults to a fresh
	// empty registry if nil.
	Reports *ReportRegistry
	// Resolver is the per-run plugin resolver. Defaults to NoopResolver{}
	// when nil — plugins may always call ctx.Resolver() without nil-checks.
	Resolver Resolver
}

AppContextOptions describes how to construct an AppContext.

type BasePlugin ¶ added in v0.7.5

type BasePlugin[C any] struct {
	PluginName string
	PluginDesc string
	PluginKey  string       // config key; defaults to PluginName if empty
	EnableMode EnablePolicy // how the framework checks if this plugin is active
	DefaultCfg func() C     // factory for default config

	// IsEnabledFn is an optional custom check for EnabledExplicitly and EnabledByDefault.
	// For EnabledExplicitly: called when configured, must return true to activate.
	// For EnabledByDefault: called when configured, return false to deactivate.
	IsEnabledFn func(C) bool
	// contains filtered or unexported fields
}

BasePlugin provides shared implementation for all plugins that have configuration. C is the plugin's concrete config type. Embedding this gives you:

• Name(), Description()
• ConfigKey(), NewConfig(), DecodeAndSet(), IsConfigured(), IsEnabled()
• Config() (typed access to config)
• Reset() (resets config state; override to reset custom fields)
• Validate() (registration-time sanity check; see Validator)

func (b *BasePlugin[C]) Config() C

func (b *BasePlugin[C]) ConfigKey() string

func (b *BasePlugin[C]) DecodeAndSet(decode func(target any) error) error

func (b *BasePlugin[C]) Description() string

func (b *BasePlugin[C]) IsConfigured() bool

func (b *BasePlugin[C]) IsEnabled() bool

func (b *BasePlugin[C]) Name() string

func (b *BasePlugin[C]) NewConfig() any

func (b *BasePlugin[C]) Reset()

func (b *BasePlugin[C]) SetTypedConfig(cfg C)

func (b *BasePlugin[C]) Validate() error

type BlobStoreOptions ¶ added in v0.9.4

type BlobStoreOptions struct {
	RootDir string
}

BlobStoreOptions carries optional backend-specific initialization overrides. Pass the zero value to use the backend's defaults.

type BlobStoreProvider ¶ added in v0.9.4

type BlobStoreProvider interface {
	Plugin
	NewBlobStore(ctx context.Context, appCtx *AppContext, opts BlobStoreOptions) (blobcache.Store, error)
}

BlobStoreProvider creates a blob store backend for plugin consumers. Pass BlobStoreOptions{} to use the backend's defaults.

type CIInfoProvider ¶ added in v0.9.4

type CIInfoProvider interface {
	Plugin
	ProviderName() string
	PipelineID() string
	CommitSHA() string
}

CIInfoProvider provides CI-specific metadata.

type CapabilityResolver ¶ added in v0.10.0

type CapabilityResolver interface {
	// ResolveCIProvider returns the active CI provider in the current set.
	ResolveCIProvider() (*ResolvedCIProvider, error)

	// ResolveChangeDetector returns the active change-detection provider.
	ResolveChangeDetector() (ChangeDetectionProvider, error)

	// ResolveKVCacheProvider returns the named KV cache backend provider.
	ResolveKVCacheProvider(name string) (KVCacheProvider, error)

	// ResolveBlobStoreProvider returns the named blob store backend provider.
	ResolveBlobStoreProvider(name string) (BlobStoreProvider, error)
}

CapabilityResolver resolves the canonical capability backings — CI provider, change detector, named cache backends. Each method returns a typed handle or a sentinel error explaining why no plugin satisfies the capability.

type ChangeDetectionProvider ¶

type ChangeDetectionProvider interface {
	Plugin
	DetectChangedModules(ctx context.Context, workDir, baseRef string, moduleIndex *discovery.ModuleIndex) (changed []*discovery.Module, changedFiles []string, err error)
	DetectChangedLibraries(ctx context.Context, workDir, baseRef string, libraryPaths []string) ([]string, error)
}

ChangeDetectionProvider detects changed modules from git (or other VCS).

type CommandProvider ¶

type CommandProvider interface {
	Plugin
	Commands() []*cobra.Command
}

CommandProvider adds CLI subcommands to TerraCi. The framework calls Commands() once during root command registration. Inside RunE, plugins retrieve the per-run AppContext via plugin.FromContext(cmd.Context()).

type CommentServiceFactory ¶ added in v0.9.4

type CommentServiceFactory interface {
	Plugin
	NewCommentService(ctx *AppContext) ci.CommentService
}

CommentServiceFactory creates PR/MR comment services.

type ConfigLoader ¶ added in v0.7.5

type ConfigLoader interface {
	Plugin
	ConfigKey() string
	NewConfig() any
	DecodeAndSet(decode func(target any) error) error
	IsConfigured() bool
	IsEnabled() bool
}

ConfigLoader declares a config section under "extensions:" in .terraci.yaml. Implemented automatically by embedding BasePlugin[C].

type EnablePolicy ¶ added in v0.7.5

type EnablePolicy int

EnablePolicy controls how the framework determines if a plugin is active.

const (
	// EnabledWhenConfigured means the plugin is active if its config section
	// exists in .terraci.yaml.
	EnabledWhenConfigured EnablePolicy = iota

	// EnabledExplicitly requires an explicit opt-in beyond having config.
	// When IsEnabledFn is set: called after config is loaded, must return true to activate.
	// When IsEnabledFn is nil: always returns false, even if configured.
	EnabledExplicitly

	// EnabledByDefault means the plugin is active unless enabled: false is set.
	EnabledByDefault

	// EnabledAlways means the plugin is always active regardless of config.
	EnabledAlways
)

type EnvDetector ¶ added in v0.7.5

type EnvDetector interface {
	Plugin
	DetectEnv() bool
}

EnvDetector detects whether this plugin's CI environment is active.

type FlagOverridable ¶ added in v0.7.5

type FlagOverridable interface {
	Plugin
	SetPlanOnly(bool)
	SetAutoApprove(bool)
}

FlagOverridable plugins support direct CLI flag overrides on their config.

type KVCache ¶ added in v0.9.4

type KVCache interface {
	Get(ctx context.Context, namespace, key string) ([]byte, bool, error)
	Set(ctx context.Context, namespace, key string, value []byte, ttl time.Duration) error
	Delete(ctx context.Context, namespace, key string) error
	DeleteNamespace(ctx context.Context, namespace string) error
}

KVCache is a pluggable key/value cache backend.

Values are stored as opaque bytes. Consumers own serialization, key layout, namespaces, and write-time TTL selection.

type KVCacheProvider ¶ added in v0.9.4

type KVCacheProvider interface {
	Plugin
	NewKVCache(ctx context.Context, appCtx *AppContext) (KVCache, error)
}

KVCacheProvider creates a KV cache backend for plugin consumers.

Providers are registered like any other TerraCi plugin and resolved by name through the global plugin registry.

type LifecycleSource ¶ added in v0.10.0

type LifecycleSource interface {
	// CollectContributions gathers pipeline contributions from enabled
	// PipelineContributor plugins.
	CollectContributions(ctx *AppContext) []*pipeline.Contribution

	// PreflightsForStartup returns enabled plugins that participate in
	// framework startup preflight for the current configuration state.
	PreflightsForStartup() []Preflightable
}

LifecycleSource exposes plugin-collection hooks the framework uses to drive pipeline construction and startup preflight.

type Lookup ¶ added in v0.10.0

type Lookup interface {
	// All returns every plugin in the current command-scoped set.
	All() []Plugin

	// GetPlugin returns a plugin by name from the current set.
	GetPlugin(name string) (Plugin, bool)
}

Lookup is the read-side of the command-scoped plugin set: enumeration and name lookup. External callers (e.g. tests for non-capability code) only need this slice of Resolver and can mock it cheaply.

type NoopResolver ¶ added in v0.10.0

type NoopResolver struct{}

NoopResolver is the default-deny Resolver. It is bound to AppContext when no real resolver is supplied (so plugins may always call ctx.Resolver() without nil-checks) and is also intended for tests: embed it and override only the methods relevant to the case at hand.

func (NoopResolver) All() []Plugin

func (NoopResolver) CollectContributions(*AppContext) []*pipeline.Contribution

func (NoopResolver) GetPlugin(string) (Plugin, bool)

func (NoopResolver) PreflightsForStartup() []Preflightable

func (NoopResolver) ResolveBlobStoreProvider(string) (BlobStoreProvider, error)

func (NoopResolver) ResolveCIProvider() (*ResolvedCIProvider, error)

func (NoopResolver) ResolveChangeDetector() (ChangeDetectionProvider, error)

func (NoopResolver) ResolveKVCacheProvider(string) (KVCacheProvider, error)

type PipelineContributor ¶

type PipelineContributor interface {
	Plugin
	PipelineContribution(ctx *AppContext) *pipeline.Contribution
}

PipelineContributor plugins add steps or jobs to the generated CI pipeline.

type PipelineGeneratorFactory ¶ added in v0.9.4

type PipelineGeneratorFactory interface {
	Plugin
	NewGenerator(ctx *AppContext, ir *pipeline.IR) pipeline.Generator
}

PipelineGeneratorFactory creates pipeline generators bound to a pre-built IR. Core builds the IR once via pipeline.Build(opts) and passes it here, so providers do not need depGraph, target modules, or contributions — they only render the IR.

type Plugin ¶

type Plugin interface {
	// Name returns a unique plugin identifier.
	Name() string
	// Description returns a human-readable description.
	Description() string
}

Plugin is the core interface every plugin must implement.

type Preflightable ¶ added in v0.9.0

type Preflightable interface {
	Plugin
	Preflight(ctx context.Context, appCtx *AppContext) error
}

Preflightable plugins run cheap validation after config is loaded, before any command runs. Preflight should stay side-effect-light: do not cache mutable command state or perform heavy runtime setup that can be created lazily inside plugin use-cases.

type ReportRegistry ¶ added in v0.7.5

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

ReportRegistry allows plugins to publish and consume reports in-memory. In CI (multi-process), reports are still written to JSON files for artifacts. The registry provides an in-process fast path for single-process runs.

func NewReportRegistry() *ReportRegistry

func (r *ReportRegistry) All() []*ci.Report

func (r *ReportRegistry) Get(producer string) (*ci.Report, bool)

func (r *ReportRegistry) Publish(report *ci.Report)

type ResolvedCIProvider ¶ added in v0.9.4

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

ResolvedCIProvider is the resolved CI provider, assembled from the focused interfaces above. Returned by ResolveCIProvider(). CommentServiceFactory is optional — not all CI providers support PR/MR comments.

func NewResolvedCIProvider(p Plugin, meta CIInfoProvider, gen PipelineGeneratorFactory, comment CommentServiceFactory) *ResolvedCIProvider

func (c *ResolvedCIProvider) CommitSHA() string

func (c *ResolvedCIProvider) Description() string

func (c *ResolvedCIProvider) Name() string

func (c *ResolvedCIProvider) NewCommentService(ctx *AppContext) (ci.CommentService, bool)

func (c *ResolvedCIProvider) NewGenerator(ctx *AppContext, ir *pipeline.IR) pipeline.Generator

func (c *ResolvedCIProvider) PipelineID() string

func (c *ResolvedCIProvider) Plugin() Plugin

func (c *ResolvedCIProvider) ProviderName() string

type Resolver ¶ added in v0.10.0

type Resolver interface {
	Lookup
	CapabilityResolver
	LifecycleSource
}

Resolver is the full command-scoped plugin surface exposed to plugins through AppContext. It composes Lookup, CapabilityResolver, and LifecycleSource — split apart so test mocks only need to implement the sub-interface their callee depends on.

type RuntimeProvider ¶ added in v0.9.0

type RuntimeProvider interface {
	Plugin
	Runtime(ctx context.Context, appCtx *AppContext) (any, error)
}

RuntimeProvider is the preferred pattern for plugins with heavy command-time setup. Runtime creation is lazy and command-driven; the framework does not invoke it automatically during startup or preflight.

Use Preflightable for cheap validation and environment checks. Use RuntimeProvider for typed runtime construction inside plugin commands and use-cases.

Typical shape:

func (p *Plugin) Runtime(_ context.Context, appCtx *AppContext) (any, error) {
	return newRuntime(appCtx, p.Config(), runtimeOptions{})
}

func (p *Plugin) runtime(ctx context.Context, appCtx *AppContext, opts runtimeOptions) (*myRuntime, error) {
	if opts == (runtimeOptions{}) {
		rawRuntime, err := p.Runtime(ctx, appCtx)
		if err != nil {
			return nil, err
		}
		return RuntimeAs[*myRuntime](rawRuntime)
	}
	return newRuntime(appCtx, p.Config(), opts)
}

package main

import (
	"context"
	"fmt"

	"github.com/edelwud/terraci/pkg/plugin"
)

type exampleRuntime struct {
	workDir string
}

type exampleRuntimePlugin struct {
	plugin.BasePlugin[*exampleRuntimeConfig]
}

type exampleRuntimeConfig struct {
	Enabled bool
}

func (p *exampleRuntimePlugin) Runtime(_ context.Context, appCtx *plugin.AppContext) (any, error) {
	if p.Config() == nil || !p.Config().Enabled {
		return nil, fmt.Errorf("example runtime is not enabled")
	}
	return &exampleRuntime{workDir: appCtx.WorkDir()}, nil
}

func main() {
	p := &exampleRuntimePlugin{
		BasePlugin: plugin.BasePlugin[*exampleRuntimeConfig]{
			PluginName:  "example",
			PluginDesc:  "example runtime plugin",
			EnableMode:  plugin.EnabledExplicitly,
			DefaultCfg:  func() *exampleRuntimeConfig { return &exampleRuntimeConfig{} },
			IsEnabledFn: func(cfg *exampleRuntimeConfig) bool { return cfg != nil && cfg.Enabled },
		},
	}
	p.SetTypedConfig(&exampleRuntimeConfig{Enabled: true})

	appCtx := plugin.NewAppContext(plugin.AppContextOptions{
		WorkDir:    "/repo",
		ServiceDir: "/repo/.terraci",
		Version:    "test",
	})
	rawRuntime, _ := p.Runtime(context.Background(), appCtx)
	runtime, _ := plugin.RuntimeAs[*exampleRuntime](rawRuntime)

	fmt.Println(runtime.workDir)
}

Output:
/repo

type Validator ¶ added in v0.10.0

type Validator interface {
	Validate() error
}

Validator is implemented by plugins that want the registry to perform a startup sanity check. The framework calls Validate() once after the plugin is constructed by its factory; a non-nil error panics in RegisterFactory with a clear message identifying the misconfigured plugin.

type VersionProvider ¶

type VersionProvider interface {
	Plugin
	VersionInfo() map[string]string
}

VersionProvider plugins contribute version info to `terraci version`.