plugin

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Apr 6, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package plugin provides YAML-based one-shot command definitions.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func InterpolateFlags 

func InterpolateFlags(template string, flags map[string]string) string

InterpolateFlags replaces ${FLAG:name} and ${FLAG:name|default} patterns with flag values.

Types

type ActionDef 

type ActionDef struct {
	Name        string            `yaml:"name"`
	Description string            `yaml:"description"`
	Command     string            `yaml:"command"` // prepend_file, clipboard, etc.
	Args        map[string]string `yaml:"args,omitempty"`
}

ActionDef defines a post-result action.

type ContextGatherer 

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

ContextGatherer collects context from various sources for plugin execution.

func NewContextGatherer 

func NewContextGatherer(workDir string, flags map[string]string) *ContextGatherer

NewContextGatherer creates a context gatherer for the given working directory.

func (*ContextGatherer) Audit 

func (g *ContextGatherer) Audit() *transparency.ContextAudit

Audit returns the context audit for transparency.

func (*ContextGatherer) Gather 

func (g *ContextGatherer) Gather(sources []ContextSource) (string, error)

Gather collects context from all specified sources.

type ContextSource 

type ContextSource struct {
	Type     string `yaml:"type"` // git_log, file, agents_md, env, etc.
	Path     string `yaml:"path,omitempty"`
	Since    string `yaml:"since,omitempty"`
	Format   string `yaml:"format,omitempty"`
	Optional bool   `yaml:"optional,omitempty"`
	MaxBytes int    `yaml:"max_bytes,omitempty"`
}

ContextSource defines a context gathering source.

type Definition 

type Definition struct {
	// Name is the command name (e.g., "changelog")
	Name string `yaml:"name"`

	// Version is the plugin version
	Version string `yaml:"version"`

	// SourcePath is the file path this definition was loaded from (set by loader)
	SourcePath string `yaml:"-"`

	// Description is a short description for help text
	Description string `yaml:"description"`

	// Tool defines the model's structured output contract
	Tool ToolDef `yaml:"tool"`

	// Context defines what sources to gather
	Context []ContextSource `yaml:"context"`

	// Flags defines CLI flags for this command
	Flags []FlagDef `yaml:"flags"`

	// Output defines how to render and handle the result
	Output OutputDef `yaml:"output"`
}

Definition is the YAML structure for a one-shot plugin.

func (*Definition) ToCommand 

func (d *Definition) ToCommand() *oneshot.Command

ToCommand converts a plugin definition to a oneshot command.

func (*Definition) ToToolDefinition 

func (d *Definition) ToToolDefinition() tools.Definition

ToToolDefinition converts the YAML tool def to a tools.Definition.

type ExecuteResult 

type ExecuteResult struct {
	// Output is the rendered output
	Output string

	// RawResult is the raw tool call result from the model
	RawResult map[string]interface{}

	// ContextAudit shows what context was gathered
	ContextAudit *transparency.ContextAudit

	// Trace contains model call details
	Trace *transparency.Trace

	// Error if execution failed
	Error error
}

ExecuteResult contains the result of plugin execution.

type Executor 

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

Executor runs plugin commands.

func NewExecutor 

func NewExecutor(invoker *oneshot.DefaultInvoker, workDir string) *Executor

NewExecutor creates a plugin executor.

func NewExecutorWithPool 

func NewExecutorWithPool(invoker *oneshot.DefaultInvoker, workDir string, pool *PluginProcessPool) *Executor

NewExecutorWithPool creates a plugin executor with a custom process pool.

func (*Executor) Execute 

func (e *Executor) Execute(ctx context.Context, def *Definition, flags map[string]string) (*ExecuteResult, error)

Execute runs a plugin with the given flags. This method maintains backward compatibility.

func (*Executor) ExecuteAction 

func (e *Executor) ExecuteAction(action ActionDef, result *ExecuteResult) error

ExecuteAction runs a post-execution action.

func (*Executor) ExecuteWithContext 

func (e *Executor) ExecuteWithContext(ctx context.Context, def *Definition, flags map[string]string) (*ExecuteResult, error)

ExecuteWithContext runs a plugin with the given flags and context. Supports timeout via context and cancellation.

func (*Executor) ExecuteWithRetry 

func (e *Executor) ExecuteWithRetry(ctx context.Context, def *Definition, flags map[string]string, retryConfig *RetryConfig) (*ExecuteResult, error)

ExecuteWithRetry runs a plugin with retry logic for transient failures.

type FlagDef 

type FlagDef struct {
	Name        string `yaml:"name"`
	Type        string `yaml:"type"` // string, bool, int, duration
	Description string `yaml:"description"`
	Default     string `yaml:"default,omitempty"`
	Required    bool   `yaml:"required,omitempty"`
}

FlagDef defines a CLI flag.

type GoTemplateEngine 

type GoTemplateEngine struct{}

GoTemplateEngine uses Go's text/template.

func (*GoTemplateEngine) Render 

func (e *GoTemplateEngine) Render(tmpl string, data map[string]interface{}) (string, error)

type HandlebarsEngine 

type HandlebarsEngine struct{}

HandlebarsEngine provides Handlebars-compatible templating. Uses a subset of Handlebars syntax compatible with Go.

func (*HandlebarsEngine) Render 

func (e *HandlebarsEngine) Render(tmpl string, data map[string]interface{}) (string, error)

type Jinja2Engine 

type Jinja2Engine struct{}

Jinja2Engine provides Jinja2-compatible templating. Uses a subset of Jinja2 syntax compatible with Go.

func (*Jinja2Engine) Render 

func (e *Jinja2Engine) Render(tmpl string, data map[string]interface{}) (string, error)

type Loader 

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

Loader discovers and loads plugin definitions.

func DefaultLoader 

func DefaultLoader() *Loader

DefaultLoader creates a loader with standard search paths.

func NewLoader 

func NewLoader(paths ...string) *Loader

NewLoader creates a plugin loader that searches the given paths.

func (*Loader) LoadAll 

func (l *Loader) LoadAll() ([]*Definition, error)

LoadAll discovers and loads all plugins from search paths.

func (*Loader) LoadFile 

func (l *Loader) LoadFile(path string) (*Definition, error)

LoadFile loads a single plugin definition from a YAML file.

func (*Loader) Register 

func (l *Loader) Register(registry *oneshot.Registry) error

Register loads all plugins and registers them with the oneshot registry.

type OutputDef 

type OutputDef struct {
	Template string      `yaml:"template"` // simple, go, handlebars, jinja2
	Format   string      `yaml:"format"`   // The template string
	Actions  []ActionDef `yaml:"actions,omitempty"`
}

OutputDef defines how to render and handle results.

type ParamDef 

type ParamDef struct {
	Type        string              `yaml:"type"`
	Description string              `yaml:"description"`
	Enum        []string            `yaml:"enum,omitempty"`
	Items       *ParamDef           `yaml:"items,omitempty"`
	Properties  map[string]ParamDef `yaml:"properties,omitempty"`
	MaxLength   int                 `yaml:"maxLength,omitempty"`
}

ParamDef defines a tool parameter.

type PluginProcess 

type PluginProcess struct {
	PluginID string
	Cmd      *exec.Cmd
	Stdin    *json.Encoder
	Stdout   *json.Decoder
	Stderr   *bufio.Reader
	LastUsed time.Time
	UseCount int
	// contains filtered or unexported fields
}

PluginProcess represents a running plugin process that can be reused.

func (*PluginProcess) Execute 

func (p *PluginProcess) Execute(ctx context.Context, request PluginRequest) (*PluginResponse, error)

Execute sends a request to the plugin process and returns the response.

func (*PluginProcess) IsHealthy 

func (p *PluginProcess) IsHealthy() bool

IsHealthy checks if the process is still alive and healthy.

func (*PluginProcess) Kill 

func (p *PluginProcess) Kill() error

Kill terminates the plugin process.

type PluginProcessPool 

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

PluginProcessPool manages a pool of reusable plugin processes.

func NewPluginProcessPool 

func NewPluginProcessPool(config PoolConfig) *PluginProcessPool

NewPluginProcessPool creates a new process pool with the given configuration.

func (*PluginProcessPool) GetProcess 

func (p *PluginProcessPool) GetProcess(pluginID string, spawnFunc func() (*PluginProcess, error)) (*PluginProcess, error)

GetProcess gets or spawns a process for the given plugin. If no process is available and max pool size is reached, it waits for one to be released.

func (*PluginProcessPool) ReleaseProcess 

func (p *PluginProcessPool) ReleaseProcess(pluginID string, proc *PluginProcess)

ReleaseProcess returns a process to the pool.

func (*PluginProcessPool) Shutdown 

func (p *PluginProcessPool) Shutdown()

Shutdown gracefully shuts down all processes in the pool.

func (*PluginProcessPool) Stats 

func (p *PluginProcessPool) Stats() PoolStats

Stats returns current pool statistics.

type PluginRequest 

type PluginRequest struct {
	Action  string                 `json:"action"`
	Payload map[string]interface{} `json:"payload"`
}

PluginRequest is the request format for plugin processes.

type PluginResponse 

type PluginResponse struct {
	Success bool                   `json:"success"`
	Result  map[string]interface{} `json:"result,omitempty"`
	Error   string                 `json:"error,omitempty"`
}

PluginResponse is the response format for plugin processes.

type PoolConfig 

type PoolConfig struct {
	// MaxSize is the maximum number of processes per plugin (default 3)
	MaxSize int

	// MaxUsesPerProcess is the maximum number of times a process can be reused (0 = unlimited)
	MaxUsesPerProcess int

	// IdleTimeout is how long a process can be idle before being cleaned up (0 = no cleanup)
	IdleTimeout time.Duration

	// HealthCheckInterval is how often to check process health (0 = no background checks)
	HealthCheckInterval time.Duration
}

PoolConfig configures the plugin process pool.

func DefaultPoolConfig 

func DefaultPoolConfig() PoolConfig

DefaultPoolConfig returns the default pool configuration.

type PoolStats 

type PoolStats struct {
	TotalPlugins   int
	TotalProcesses int
	AvailableCount int
	InUseCount     int
	UnhealthyCount int
}

PoolStats returns statistics about the process pool.

type RetryConfig 

type RetryConfig struct {
	// MaxRetries is the maximum number of retry attempts (0 = no retries)
	MaxRetries int

	// InitialBackoff is the initial backoff duration between retries
	InitialBackoff time.Duration

	// MaxBackoff is the maximum backoff duration
	MaxBackoff time.Duration

	// BackoffMultiplier is the factor by which backoff increases after each retry
	BackoffMultiplier float64

	// RetryableErrors is a list of error strings that should trigger a retry
	// If empty, all transient errors are retried
	RetryableErrors []string
}

RetryConfig configures retry behavior for plugin execution.

func DefaultRetryConfig 

func DefaultRetryConfig() *RetryConfig

DefaultRetryConfig returns a default retry configuration.

func (*RetryConfig) IsRetryableError 

func (r *RetryConfig) IsRetryableError(err error) bool

IsRetryableError checks if an error should trigger a retry.

type SimpleEngine 

type SimpleEngine struct{}

SimpleEngine uses ${var} syntax for simple variable substitution.

func (*SimpleEngine) Render 

func (e *SimpleEngine) Render(tmpl string, data map[string]interface{}) (string, error)

type TemplateEngine 

type TemplateEngine interface {
	Render(tmpl string, data map[string]interface{}) (string, error)
}

TemplateEngine renders output using a template.

func GetTemplateEngine 

func GetTemplateEngine(templateType string) (TemplateEngine, error)

GetTemplateEngine returns the appropriate engine for the template type.

type ToolDef 

type ToolDef struct {
	Name        string              `yaml:"name"`
	Description string              `yaml:"description"`
	Parameters  map[string]ParamDef `yaml:"parameters"`
	Required    []string            `yaml:"required"`
}

ToolDef defines the tool schema in YAML.

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.