create-plugin

name	create-plugin
description	Create new sidecar plugins implementing the plugin.Plugin interface, rendering views with Bubble Tea, handling keyboard input via keymap contexts, and integrating with the app shell (footer hints, event bus, adapters). Use when creating a new plugin, modifying plugin architecture, or debugging plugin rendering/lifecycle issues. See references/ for sidebar list and fixed footer layout details.

Create Plugin

Architecture Overview

• Bubble Tea model: internal/app/model.go owns the active plugin index, dispatches key events, renders plugin views.
• Registry: internal/plugin/registry.go stores plugins, handles lifecycle with panic protection, keeps an unavailable map when Init fails (silent degradation).
• Plugin contract: internal/plugin/plugin.go defines the interface every plugin must satisfy.
• Context: internal/plugin/context.go provides WorkDir, ConfigDir, Adapters, EventBus, Logger, Epoch, and Keymap.
• Keymap: internal/keymap maps keys to command IDs. Footer/help reads bindings by context using Plugin.Commands() + Plugin.FocusContext().

Plugin Interface

Every plugin must implement all of these methods:

ID() string              // Stable kebab-case identifier
Name() string            // Short human label for headers/help
Icon() string            // Single-character glyph for tab strip
Init(ctx *Context) error // Lightweight setup; return error to degrade gracefully
Start() tea.Cmd          // Kick off async work (non-blocking)
Update(msg tea.Msg) (Plugin, tea.Cmd) // Pure state transition
View(width, height int) string        // Render within provided dimensions
IsFocused() bool         // Check focus state
SetFocused(bool)         // App calls this on tab switch
Commands() []plugin.Command           // Footer hints per context
FocusContext() string    // Current context name for keymap
Stop()                   // Idempotent cleanup

Optional: implement Diagnostics() []plugin.Diagnostic for the diagnostics overlay.

Lifecycle Order

1. Registration (cmd/sidecar/main.go): registry.Register(myplugin.New()). No work here.
2. Init: Detect prerequisites (repos, adapters, env vars). Use ctx.Logger for warnings. Return error to degrade gracefully.
3. Start: Batch initial commands with tea.Batch. Never block.
4. Update: Pattern-match on custom Msg types and tea.KeyMsg. Keep I/O in commands, not directly in Update.
5. View: Render only; no side-effects. Honor width/height.
6. Focus/Blur: SetFocused called on tab switch. Pause expensive work when unfocused.
7. Stop: Close watchers, timers, channels. Guard with sync.Once/flags.

Epoch Pattern (Stale Message Detection)

When switching projects/worktrees, async operations may deliver stale data. Use the epoch pattern:

Step 1: Add Epoch to message type

type MyDataLoadedMsg struct {
    Epoch uint64
    Data  string
    Err   error
}
func (m MyDataLoadedMsg) GetEpoch() uint64 { return m.Epoch }

Step 2: Capture epoch in command creators

func (p *Plugin) loadData() tea.Cmd {
    epoch := p.ctx.Epoch // Capture synchronously before closure
    return func() tea.Msg {
        data, err := fetchData()
        return MyDataLoadedMsg{Epoch: epoch, Data: data, Err: err}
    }
}

Step 3: Check staleness in Update

case MyDataLoadedMsg:
    if plugin.IsStale(p.ctx, msg) {
        return p, nil // Discard stale message
    }
    p.data = msg.Data

Apply this to any async message that fetches data from filesystem/external sources or updates project-specific state.

Keymap, Contexts, and Commands

• Define contexts mirroring your view modes (e.g., git-status, git-diff). Return the active one from FocusContext().
• Expose commands with matching contexts via Commands(). These power footer hints and help overlay.
• Add default bindings in internal/keymap/bindings.go.
• Keep command IDs stable (verbs preferred: open-file, toggle-diff-mode).

Command structure

plugin.Command{
    ID:       "stage-file",
    Name:     "Stage",           // Keep 1-2 words max
    Category: plugin.CategoryGit,
    Priority: 10,                // Lower = higher priority; 0 treated as 99
    Context:  "git-status",
}

Categories: CategoryNavigation, CategoryActions, CategoryView, CategorySearch, CategoryEdit, CategoryGit, CategorySystem

Context naming convention

• plugin-name for main view
• plugin-name-detail for detail/preview
• plugin-name-modal for modals
• plugin-name-search for search modes

Dynamic binding registration

func (p *Plugin) Init(ctx *plugin.Context) error {
    if ctx.Keymap != nil {
        ctx.Keymap.RegisterPluginBinding("g g", "go-to-top", "my-context")
    }
    return nil
}

Event Bus (Cross-Plugin Communication)

• Subscribe: ch := ctx.EventBus.Subscribe("topic") in Start(), forward messages into Update.
• Publish: ctx.EventBus.Publish("topic", event.NewEvent(event.TypeRefreshNeeded, "topic", payload)).
• Best-effort, buffered (size 16), drops when full. Design listeners to be resilient.

Inter-Plugin Messages

App-level messages (internal/app/commands.go):

• FocusPluginByIDMsg{PluginID} / app.FocusPlugin(id)

File browser messages (internal/plugins/filebrowser/plugin.go):

• NavigateToFileMsg{Path} - navigate to and preview a file

Pattern for cross-plugin navigation:

func (p *Plugin) openInFileBrowser(path string) tea.Cmd {
    return tea.Batch(
        app.FocusPlugin("file-browser"),
        func() tea.Msg { return filebrowser.NavigateToFileMsg{Path: path} },
    )
}

Plugin Focus Events

PluginFocusedMsg (from internal/app): sent when your plugin becomes active tab. Use to refresh data only needed when visible:

case app.PluginFocusedMsg:
    if p.pendingRefresh {
        p.pendingRefresh = false
        return p, p.refresh()
    }

External Editor Integration

func (p *Plugin) openFile(path string, lineNo int) tea.Cmd {
    editor := p.ctx.Config.EditorCommand
    return func() tea.Msg {
        return plugin.OpenFileMsg{Editor: editor, Path: path, LineNo: lineNo}
    }
}

Rendering Rules

CRITICAL: Always constrain plugin output height. The app header/footer are always visible. Plugins must not exceed allocated height.

lipgloss.NewStyle().Width(width).Height(height).MaxHeight(height).Render(content)

Do NOT render footers in plugin View(). The app renders footer using Commands() and keymap bindings.

Additional rendering rules:

• Keep View deterministic; drive dynamic data through state in Update.
• Cache width/height in plugin state.
• Expand \t to spaces before width checks.
• Use ANSI-aware helpers (ansi.Truncate, lipgloss.Width) for content with escape codes.
• Use small helper render functions per view mode.

See references/sidebar-list-guide.md for scrollable list implementation patterns. See references/fixed-footer-layout-guide.md for footer and layout math details.

Persisting User Preferences

Use internal/state to persist layout preferences across restarts:

1. Add field to state.State struct with getter/setter.
2. Load in Init(): if saved := state.GetMyPaneWidth(); saved > 0 { p.paneWidth = saved }
3. Save on user action: _ = state.SetMyPaneWidth(p.paneWidth)

Adapters

• ctx.Adapters holds integrations. Check capability in Init before using.
• Watcher data from adapters should feed messages through Update.

Error Handling

• Return lightweight errors from Init; registry records them without crashing.
• Use ctx.Logger with structured fields.
• Surface recoverable issues as status/toast messages, not panics.

New Plugin Checklist

1. Create internal/plugins/<id>/ with plugin.go plus supporting files.
2. Implement the plugin.Plugin interface; consider DiagnosticProvider.
3. Register in cmd/sidecar/main.go.
4. Add default key bindings in internal/keymap/bindings.go.
5. Ensure Commands() covers every binding so hints/help work.
6. Wire external needs (adapters, env detection) in Init; degrade gracefully.
7. Provide cleanup in Stop; keep Start/Update non-blocking.

Testing

• Keep business logic in testable helpers; wire Bubble Tea plumbing around it.
• Use small typed messages (type RefreshMsg struct{}) to keep Update readable.
• Enable --debug for verbose logs from registry and plugins.