plugin

Documentation

Overview

Package plugin provides a plugin system for the core CLI.

Plugins extend the CLI with additional commands and functionality. They are distributed as GitHub repositories and managed via a local registry.

Plugin lifecycle:

• Install: Download from GitHub, validate manifest, register
• Init: Parse manifest and prepare plugin
• Start: Activate plugin functionality
• Stop: Deactivate and clean up
• Remove: Unregister and delete files

Index

• func ParseSource(source string) (org, repo, version string, err error)
• type BasePlugin
  • func (p *BasePlugin) Init(_ context.Context) error
  • func (p *BasePlugin) Name() string
  • func (p *BasePlugin) Start(_ context.Context) error
  • func (p *BasePlugin) Stop(_ context.Context) error
  • func (p *BasePlugin) Version() string
• type Installer
  • func NewInstaller(m io.Medium, registry *Registry) *Installer
  • func (i *Installer) Install(ctx context.Context, source string) error
  • func (i *Installer) Remove(name string) error
  • func (i *Installer) Update(ctx context.Context, name string) error
• type Loader
  • func NewLoader(m io.Medium, baseDir string) *Loader
  • func (l *Loader) Discover() ([]*Manifest, error)
  • func (l *Loader) LoadPlugin(name string) (*Manifest, error)
• type Manifest
  • func LoadManifest(m io.Medium, path string) (*Manifest, error)
  • func (m *Manifest) Validate() error
• type Plugin
• type PluginConfig
• type Registry
  • func NewRegistry(m io.Medium, basePath string) *Registry
  • func (r *Registry) Add(cfg *PluginConfig) error
  • func (r *Registry) Get(name string) (*PluginConfig, bool)
  • func (r *Registry) List() []*PluginConfig
  • func (r *Registry) Load() error
  • func (r *Registry) Remove(name string) error
  • func (r *Registry) Save() error

Functions

func ParseSource

func ParseSource(source string) (org, repo, version string, err error)

ParseSource parses a plugin source string into org, repo, and version. Accepted formats:

• "org/repo" -> org="org", repo="repo", version=""
• "org/repo@v1.0" -> org="org", repo="repo", version="v1.0"

Types

type BasePlugin

type BasePlugin struct {
	PluginName    string
	PluginVersion string
}

BasePlugin provides a default implementation of Plugin. Embed this in concrete plugin types to inherit default behaviour.

func (*BasePlugin) Init

func (p *BasePlugin) Init(_ context.Context) error

Init is a no-op default implementation.

func (*BasePlugin) Name

func (p *BasePlugin) Name() string

Name returns the plugin name.

func (*BasePlugin) Start

func (p *BasePlugin) Start(_ context.Context) error

Start is a no-op default implementation.

func (*BasePlugin) Stop

func (p *BasePlugin) Stop(_ context.Context) error

Stop is a no-op default implementation.

func (*BasePlugin) Version

func (p *BasePlugin) Version() string

Version returns the plugin version.

type Installer

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

Installer handles plugin installation from GitHub.

func NewInstaller

func NewInstaller(m io.Medium, registry *Registry) *Installer

NewInstaller creates a new plugin installer.

func (*Installer) Install

func (i *Installer) Install(ctx context.Context, source string) error

Install downloads and installs a plugin from GitHub. The source format is "org/repo" or "org/repo@version".

func (*Installer) Remove

func (i *Installer) Remove(name string) error

Remove uninstalls a plugin by removing its files and registry entry.

func (*Installer) Update

func (i *Installer) Update(ctx context.Context, name string) error

Update updates a plugin to the latest version.

type Loader

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

Loader loads plugins from the filesystem.

func NewLoader

func NewLoader(m io.Medium, baseDir string) *Loader

NewLoader creates a new plugin loader.

func (*Loader) Discover

func (l *Loader) Discover() ([]*Manifest, error)

Discover finds all plugin directories under baseDir and returns their manifests. Directories without a valid plugin.json are silently skipped.

func (*Loader) LoadPlugin

func (l *Loader) LoadPlugin(name string) (*Manifest, error)

LoadPlugin loads a single plugin's manifest by name.

type Manifest

type Manifest struct {
	Name         string   `json:"name"`
	Version      string   `json:"version"`
	Description  string   `json:"description"`
	Author       string   `json:"author"`
	Entrypoint   string   `json:"entrypoint"`
	Dependencies []string `json:"dependencies,omitempty"`
	MinVersion   string   `json:"min_version,omitempty"`
}

Manifest represents a plugin.json manifest file. Each plugin repository must contain a plugin.json at its root.

func LoadManifest

func LoadManifest(m io.Medium, path string) (*Manifest, error)

LoadManifest reads and parses a plugin.json file from the given path.

func (*Manifest) Validate

func (m *Manifest) Validate() error

Validate checks the manifest for required fields. Returns an error if name, version, or entrypoint are missing.

type Plugin

type Plugin interface {
	// Name returns the plugin's unique identifier.
	Name() string

	// Version returns the plugin's semantic version.
	Version() string

	// Init prepares the plugin for use.
	Init(ctx context.Context) error

	// Start activates the plugin.
	Start(ctx context.Context) error

	// Stop deactivates the plugin and releases resources.
	Stop(ctx context.Context) error
}

Plugin is the interface that all plugins must implement.

type PluginConfig

type PluginConfig struct {
	Name        string `json:"name" yaml:"name"`
	Version     string `json:"version" yaml:"version"`
	Source      string `json:"source" yaml:"source"` // e.g., "github:org/repo"
	Enabled     bool   `json:"enabled" yaml:"enabled"`
	InstalledAt string `json:"installed_at" yaml:"installed_at"` // RFC 3339 timestamp
}

PluginConfig holds configuration for a single installed plugin.

type Registry

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

Registry manages installed plugins. Plugin metadata is stored in a registry.json file under the base path.

func NewRegistry

func NewRegistry(m io.Medium, basePath string) *Registry

NewRegistry creates a new plugin registry.

func (*Registry) Add

func (r *Registry) Add(cfg *PluginConfig) error

Add registers a plugin in the registry.

func (*Registry) Get

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

Get returns a plugin by name. The second return value indicates whether the plugin was found.

func (*Registry) List

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

List returns all installed plugins sorted by name.

func (*Registry) Load

func (r *Registry) Load() error

Load reads the plugin registry from disk. If the registry file does not exist, the registry starts empty.

func (*Registry) Remove

func (r *Registry) Remove(name string) error

Remove unregisters a plugin from the registry.

func (*Registry) Save

func (r *Registry) Save() error

Save writes the plugin registry to disk.