Documentation
¶
Overview ¶
Package plugin defines the plugin system interface and registry for registering, managing, and coordinating sidecar plugins with shared context.
Index ¶
- func IsStale(ctx *Context, msg EpochMessage) bool
- type BindingRegistrar
- type Category
- type Command
- type Context
- type Diagnostic
- type DiagnosticProvider
- type EpochMessage
- type OpenFileMsg
- type Plugin
- type PluginFocusedMsg
- type Registry
- func (r *Registry) Context() *Context
- func (r *Registry) Get(id string) Plugin
- func (r *Registry) Plugins() []Plugin
- func (r *Registry) Register(p Plugin) error
- func (r *Registry) Reinit(newWorkDir, newProjectRoot string) []tea.Cmd
- func (r *Registry) Start() []tea.Cmd
- func (r *Registry) Stop()
- func (r *Registry) Unavailable() map[string]string
- type TextInputConsumer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsStale ¶
func IsStale(ctx *Context, msg EpochMessage) bool
IsStale returns true if the message's epoch doesn't match the current context epoch. Use this in Update() handlers to discard messages from previous projects:
if plugin.IsStale(p.ctx, msg) { return p, nil }
Types ¶
type BindingRegistrar ¶
type BindingRegistrar interface {
RegisterPluginBinding(key, command, context string)
}
BindingRegistrar allows plugins to register key bindings dynamically. This is implemented by keymap.Registry.
type Category ¶
type Category string
Category represents a logical grouping of commands for the command palette.
type Command ¶
type Command struct {
ID string // Unique identifier (e.g., "stage-file")
Name string // Short name for footer (e.g., "Stage")
Description string // Full description for palette
Category Category // Logical grouping for palette display
Handler func() tea.Cmd // Action to execute (optional)
Context string // Activation context
Priority int // Footer display priority: 1=highest, 0=default (treated as 99)
}
Command represents a keybinding command exposed by a plugin.
type Context ¶
type Context struct {
WorkDir string // Actual working directory (worktree path for linked worktrees)
ProjectRoot string // Main repo root for shared state (same as WorkDir for non-worktrees)
ConfigDir string
Config *config.Config
Adapters map[string]adapter.Adapter
EventBus *event.Dispatcher
Logger *slog.Logger
Keymap BindingRegistrar // For plugins to register dynamic bindings
Epoch uint64 // Incremented on project switch to invalidate stale async messages
}
Context provides shared resources to plugins during initialization.
type Diagnostic ¶
Diagnostic represents a health/status check result.
type DiagnosticProvider ¶
type DiagnosticProvider interface {
Diagnostics() []Diagnostic
}
DiagnosticProvider is implemented by plugins that expose diagnostics.
type EpochMessage ¶
type EpochMessage interface {
GetEpoch() uint64
}
EpochMessage is implemented by async messages that need staleness detection. Messages from async operations should embed an Epoch field and implement this interface.
type OpenFileMsg ¶
type OpenFileMsg struct {
Editor string // Editor command (e.g., "vim", "code")
Path string // File path to open
LineNo int // Line number to open at (0 = start of file)
}
OpenFileMsg requests opening a file in an external editor. Sent by plugins, handled by app to exec the editor process.
type Plugin ¶
type Plugin interface {
ID() string
Name() string
Icon() string
Init(ctx *Context) error
Start() tea.Cmd
Stop()
Update(msg tea.Msg) (Plugin, tea.Cmd)
View(width, height int) string
IsFocused() bool
SetFocused(bool)
Commands() []Command
FocusContext() string
}
Plugin defines the interface for all sidecar plugins.
type PluginFocusedMsg ¶
type PluginFocusedMsg struct{}
PluginFocusedMsg is sent to a plugin when it becomes the active plugin. Plugins can use this to refresh data or update their state on focus.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry manages plugin registration and lifecycle.
func NewRegistry ¶
NewRegistry creates a new plugin registry with the given context.
func (*Registry) Register ¶
Register adds a plugin to the registry. If Init fails, the plugin is marked unavailable (silent degradation).
func (*Registry) Reinit ¶
Reinit stops all plugins, updates the context with a new WorkDir and ProjectRoot, and reinitializes all plugins. Returns the start commands for all plugins.
func (*Registry) Stop ¶
func (r *Registry) Stop()
Stop stops all registered plugins in reverse order.
func (*Registry) Unavailable ¶
Unavailable returns a map of plugin IDs to their failure reasons.
type TextInputConsumer ¶
type TextInputConsumer interface {
ConsumesTextInput() bool
}
TextInputConsumer is an optional capability for plugins that need alphanumeric key input to be forwarded as typed text instead of being intercepted by app-level shortcuts.