plugins

Documentation

Overview

SPDX-License-Identifier: MIT Purpose: plugin manifest format + validator. Plugins live in ~/.local/share/sin-code/plugins/<name>/ with a plugin.toml file describing their subcommands, agents, and tools.

SPDX-License-Identifier: MIT Purpose: plugin registry — discovers plugins on disk, exposes their subcommands via cobra, their agents via the orchestrator registry, and their tools via the MCP server. SOTA pattern: gh-extensions, oh-my-zsh.

Index

• Constants
• func DefaultPluginDir() string
• func ResolvePluginDir(override string) string
• type HookDef
• type MCPToolDef
• type Plugin
  • func Load(path string) (*Plugin, error)
  • func LoadDir(dir string) ([]*Plugin, error)
  • func (p *Plugin) Dir() string
  • func (p *Plugin) Disable() error
  • func (p *Plugin) Enable() error
  • func (p *Plugin) Validate() error
• type PluginAgent
• type PluginHook
• type PluginSubcmd
• type PluginTool
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) AddSubcommandsTo(root *cobra.Command)
  • func (r *Registry) AgentConfigs() []orchestrator.AgentConfig
  • func (r *Registry) Get(name string) (*Plugin, bool)
  • func (r *Registry) HooksFor(event string) []HookDef
  • func (r *Registry) List() []*Plugin
  • func (r *Registry) LoadFromDir(dir string) error
  • func (r *Registry) MCPTools() []MCPToolDef
  • func (r *Registry) Register(p *Plugin)

Constants

const ManifestFile = "plugin.toml"

Functions

func DefaultPluginDir

func DefaultPluginDir() string

func ResolvePluginDir

func ResolvePluginDir(override string) string

ResolvePluginDir returns the plugin dir to use. Empty arg → env override (SIN_CODE_CONFIG_DIR) → default user config dir. Lets testscripts redirect discovery to a tmp dir without touching HOME.

Types

type HookDef

type HookDef struct {
	Plugin  string
	Event   string
	Command string
	Timeout int
}

HookDef is a plugin-registered todo event hook. Plugin hooks are run as subprocesses with the same SIN_TODO_* env vars the built-in todo hooks receive.

type MCPToolDef

type MCPToolDef struct {
	Name        string
	Description string
	Plugin      string
	PluginPath  string
	Tool        string
	Binary      string
	Args        []string
	Timeout     int
	Schema      map[string]any
}

MCPToolDef describes one plugin tool to be exposed via the MCP server. The Name uses the canonical "sin_plugin_<plugin>_<tool>" form, the Description comes from the manifest, and Schema is built from the manifest's Args slice (each arg → JSON Schema string property).

type Plugin

type Plugin struct {
	Name         string         `toml:"name"`
	Version      string         `toml:"version"`
	Description  string         `toml:"description"`
	Author       string         `toml:"author"`
	Homepage     string         `toml:"homepage"`
	License      string         `toml:"license"`
	MinSinCode   string         `toml:"min_sin_code"`
	Capabilities []string       `toml:"capabilities"`
	Subcommands  []PluginSubcmd `toml:"subcommand"`
	Agents       []PluginAgent  `toml:"agents"`
	Tools        []PluginTool   `toml:"tools"`
	Hooks        []PluginHook   `toml:"hooks"`

	Enabled bool   `toml:"-"`
	Path    string `toml:"-"`
}

func Load

func Load(path string) (*Plugin, error)

func LoadDir

func LoadDir(dir string) ([]*Plugin, error)

func (*Plugin) Dir

func (p *Plugin) Dir() string

func (*Plugin) Disable

func (p *Plugin) Disable() error

func (*Plugin) Enable

func (p *Plugin) Enable() error

func (*Plugin) Validate

func (p *Plugin) Validate() error

type PluginAgent

type PluginAgent struct {
	Name     string `toml:"name"`
	Type     string `toml:"type"`
	Model    string `toml:"model"`
	System   string `toml:"system_file"`
	Provider string `toml:"provider"`
}

type PluginHook

type PluginHook struct {
	Event   string `toml:"event"`
	Command string `toml:"command"`
	Timeout int    `toml:"timeout"`
}

type PluginSubcmd

type PluginSubcmd struct {
	Name        string   `toml:"name"`
	Description string   `toml:"description"`
	Binary      string   `toml:"binary"`
	Args        []string `toml:"args"`
	Env         []string `toml:"env"`
}

type PluginTool

type PluginTool struct {
	Name        string   `toml:"name"`
	Description string   `toml:"description"`
	Binary      string   `toml:"binary"`
	Args        []string `toml:"args"`
	Timeout     int      `toml:"timeout"`
}

type Registry

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

func NewRegistry

func NewRegistry() *Registry

func (*Registry) AddSubcommandsTo

func (r *Registry) AddSubcommandsTo(root *cobra.Command)

AddSubcommandsTo attaches all enabled plugin subcommands to the given root cobra command. Each subcommand becomes a real cobra.Command that exec's the plugin binary.

func (*Registry) AgentConfigs

func (r *Registry) AgentConfigs() []orchestrator.AgentConfig

AgentConfigs returns the agents contributed by all enabled plugins, converted to orchestrator.AgentConfig.

func (*Registry) Get

func (r *Registry) Get(name string) (*Plugin, bool)

func (*Registry) HooksFor

func (r *Registry) HooksFor(event string) []HookDef

HooksFor returns all enabled plugin hooks matching the given event name (e.g. "post_complete"). Unknown events yield no hooks.

func (*Registry) List

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

func (*Registry) LoadFromDir

func (r *Registry) LoadFromDir(dir string) error

func (*Registry) MCPTools

func (r *Registry) MCPTools() []MCPToolDef

MCPTools returns one MCPToolDef per enabled plugin tool, named "sin_plugin_<plugin>_<tool>" so they are easily greppable and don't collide with the built-in sin_* MCP tools.

func (*Registry) Register

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