plugin

package
v0.74.1 Latest Latest
Warning

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

Go to latest
Published: Feb 19, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package plugin defines the plugin system interface and registry for registering, managing, and coordinating sidecar plugins with shared context.

Index

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.

const (
	CategoryNavigation Category = "Navigation"
	CategoryActions    Category = "Actions"
	CategoryView       Category = "View"
	CategorySearch     Category = "Search"
	CategoryEdit       Category = "Edit"
	CategoryGit        Category = "Git"
	CategorySystem     Category = "System"
)

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

type Diagnostic struct {
	ID     string
	Status string
	Detail string
}

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

func NewRegistry(ctx *Context) *Registry

NewRegistry creates a new plugin registry with the given context.

func (*Registry) Context

func (r *Registry) Context() *Context

Context returns the current context.

func (*Registry) Get

func (r *Registry) Get(id string) Plugin

Get returns a plugin by ID, or nil if not found.

func (*Registry) Plugins

func (r *Registry) Plugins() []Plugin

Plugins returns all active plugins.

func (*Registry) Register

func (r *Registry) Register(p Plugin) error

Register adds a plugin to the registry. If Init fails, the plugin is marked unavailable (silent degradation).

func (*Registry) Reinit

func (r *Registry) Reinit(newWorkDir, newProjectRoot string) []tea.Cmd

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) Start

func (r *Registry) Start() []tea.Cmd

Start starts all registered plugins and returns their initial commands.

func (*Registry) Stop

func (r *Registry) Stop()

Stop stops all registered plugins in reverse order.

func (*Registry) Unavailable

func (r *Registry) Unavailable() map[string]string

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL