plugins

Documentation

Overview

Package plugins provides a unified plugin system for managing both skills (model-invoked capabilities) and recipes (user-invoked templates). It handles discovery, installation, and removal of plugins from GitHub repositories.

Index

• func IsExecutableFile(entry fs.DirEntry) bool
• func PluginNameToUserFacing(pluginName string) string
• func ValidateRepoName(repo string) error
• type Discovery
  • func NewDiscovery(opts ...DiscoveryOption) (*Discovery, error)
  • func (d *Discovery) DiscoverAll() ([]Plugin, error)
  • func (d *Discovery) DiscoverRecipes() (map[string]Plugin, error)
  • func (d *Discovery) DiscoverSkills() (map[string]Plugin, error)
  • func (d *Discovery) HookDirs() []PluginDirConfig
  • func (d *Discovery) ListInstalledPlugins(global bool) ([]InstalledPlugin, error)
  • func (d *Discovery) RecipeDirs() []string
  • func (d *Discovery) SkillDirs() []string
• type DiscoveryOption
  • func WithBaseDir(dir string) DiscoveryOption
  • func WithHomeDir(dir string) DiscoveryOption
• type InstallResult
• type InstalledPlugin
• type Installer
  • func NewInstaller(opts ...InstallerOption) (*Installer, error)
  • func (i *Installer) Install(ctx context.Context, repo string, ref string) (*InstallResult, error)
• type InstallerOption
  • func WithForce(force bool) InstallerOption
  • func WithGlobal(global bool) InstallerOption
• type Plugin
• type PluginDirConfig
  • func ScanPluginSubdirs(pluginsDir, subdir string) []PluginDirConfig
  • func (c PluginDirConfig) PrefixedName(name string) string
• type PluginMetadata
• type PluginType
• type RecipePlugin
  • func NewRecipePlugin(name, description, directory string) *RecipePlugin
  • func (r *RecipePlugin) Description() string
  • func (r *RecipePlugin) Directory() string
  • func (r *RecipePlugin) Name() string
  • func (r *RecipePlugin) Type() PluginType
• type Remover
  • func NewRemover(opts ...InstallerOption) (*Remover, error)
  • func (r *Remover) ListPlugins() ([]string, error)
  • func (r *Remover) Remove(name string) error
• type SkillPlugin
  • func NewSkillPlugin(name, description, directory string) *SkillPlugin
  • func (s *SkillPlugin) Description() string
  • func (s *SkillPlugin) Directory() string
  • func (s *SkillPlugin) Name() string
  • func (s *SkillPlugin) Type() PluginType

Functions

func IsExecutableFile

func IsExecutableFile(entry fs.DirEntry) bool

IsExecutableFile checks if a file entry is executable (has any execute bit set). This is used for hook discovery across both installation and listing.

func PluginNameToUserFacing

func PluginNameToUserFacing(pluginName string) string

PluginNameToUserFacing converts "org@repo" directory format to "org/repo" user-facing format.

func ValidateRepoName

func ValidateRepoName(repo string) error

ValidateRepoName validates a GitHub repository name format. Expected format: "owner/repo" (e.g., "jingkaihe/skills"). Returns an error if the format is invalid.

Types

type Discovery

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

Discovery handles plugin discovery from configured directories

func NewDiscovery

func NewDiscovery(opts ...DiscoveryOption) (*Discovery, error)

NewDiscovery creates a new plugin discovery instance

func (*Discovery) DiscoverAll

func (d *Discovery) DiscoverAll() ([]Plugin, error)

DiscoverAll discovers all plugins (skills and recipes) with proper naming

func (*Discovery) DiscoverRecipes

func (d *Discovery) DiscoverRecipes() (map[string]Plugin, error)

DiscoverRecipes discovers all recipes with proper naming and precedence

func (*Discovery) DiscoverSkills

func (d *Discovery) DiscoverSkills() (map[string]Plugin, error)

DiscoverSkills discovers all skills with proper naming and precedence

func (*Discovery) HookDirs

func (d *Discovery) HookDirs() []PluginDirConfig

HookDirs returns the hook discovery directories with prefix info in precedence order. This is used by the hooks package for plugin-based hook discovery.

func (*Discovery) ListInstalledPlugins

func (d *Discovery) ListInstalledPlugins(global bool) ([]InstalledPlugin, error)

ListInstalledPlugins returns all installed plugin packages from the specified location Plugin directories use "org@repo" naming format

func (*Discovery) RecipeDirs

func (d *Discovery) RecipeDirs() []string

RecipeDirs returns the recipe discovery directories in precedence order

func (*Discovery) SkillDirs

func (d *Discovery) SkillDirs() []string

SkillDirs returns the skill discovery directories in precedence order

type DiscoveryOption

type DiscoveryOption func(*Discovery) error

DiscoveryOption configures a Discovery instance

func WithBaseDir

func WithBaseDir(dir string) DiscoveryOption

WithBaseDir sets a custom base directory (for testing)

func WithHomeDir

func WithHomeDir(dir string) DiscoveryOption

WithHomeDir sets a custom home directory (for testing)

type InstallResult

type InstallResult struct {
	PluginName string
	Skills     []string
	Recipes    []string
	Hooks      []string
}

InstallResult contains information about installed plugins

type InstalledPlugin

type InstalledPlugin struct {
	Name    string   // Plugin package name (e.g., "my-plugin-repo")
	Path    string   // Full path to the plugin directory
	Skills  []string // List of skill names contained in this plugin
	Recipes []string // List of recipe names contained in this plugin
	Hooks   []string // List of hook names contained in this plugin
}

InstalledPlugin represents a plugin package that may contain multiple skills, recipes, and hooks

type Installer

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

Installer handles plugin installation from GitHub repositories

func NewInstaller

func NewInstaller(opts ...InstallerOption) (*Installer, error)

NewInstaller creates a new plugin installer

func (*Installer) Install

func (i *Installer) Install(ctx context.Context, repo string, ref string) (*InstallResult, error)

Install installs plugins from a GitHub repository

type InstallerOption

type InstallerOption func(*Installer)

InstallerOption configures an Installer instance

func WithForce

func WithForce(force bool) InstallerOption

WithForce overwrites existing plugins

func WithGlobal

func WithGlobal(global bool) InstallerOption

WithGlobal installs plugins to the global directory

type Plugin

type Plugin interface {
	Name() string
	Description() string
	Directory() string
	Type() PluginType
}

Plugin represents a discoverable plugin (skill or recipe)

type PluginDirConfig

type PluginDirConfig struct {
	Dir    string // Directory path containing skills or recipes
	Prefix string // Prefix to prepend to discovered item names (e.g., "org/repo/")
}

PluginDirConfig represents a plugin directory with its prefix for discovery. Used by skills and fragments packages for plugin-based discovery.

func ScanPluginSubdirs

func ScanPluginSubdirs(pluginsDir, subdir string) []PluginDirConfig

ScanPluginSubdirs scans a plugins directory and returns all plugin subdirectories that contain the specified subdir (e.g., "skills" or "recipes"). Each returned PluginDirConfig has the full path to the subdir and a prefix derived from the plugin's directory name (e.g., "org@repo" -> "org@repo/").

func (PluginDirConfig) PrefixedName

func (c PluginDirConfig) PrefixedName(name string) string

PrefixedName returns the name with the prefix prepended. If prefix is empty, returns the name unchanged.

type PluginMetadata

type PluginMetadata struct {
	Name        string `yaml:"name"`
	Description string `yaml:"description"`
}

PluginMetadata contains common metadata for all plugins

type PluginType

type PluginType string

PluginType represents the type of plugin

const (
	PluginTypeSkill  PluginType = "skill"
	PluginTypeRecipe PluginType = "recipe"
	PluginTypeHook   PluginType = "hook"
)

Plugin types

type RecipePlugin

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

RecipePlugin represents a discovered recipe plugin

func NewRecipePlugin

func NewRecipePlugin(name, description, directory string) *RecipePlugin

NewRecipePlugin creates a new recipe plugin

func (*RecipePlugin) Description

func (r *RecipePlugin) Description() string

Description returns the recipe description

func (*RecipePlugin) Directory

func (r *RecipePlugin) Directory() string

Directory returns the recipe directory path

func (*RecipePlugin) Name

func (r *RecipePlugin) Name() string

Name returns the recipe name

func (*RecipePlugin) Type

func (r *RecipePlugin) Type() PluginType

Type returns the plugin type (recipe)

type Remover

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

Remover handles plugin removal

func NewRemover

func NewRemover(opts ...InstallerOption) (*Remover, error)

NewRemover creates a new plugin remover

func (*Remover) ListPlugins

func (r *Remover) ListPlugins() ([]string, error)

ListPlugins returns all installed plugin names in "org/repo" user-facing format.

func (*Remover) Remove

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

Remove removes a plugin by name Accepts both "org/repo" format (converted to "org@repo") and direct "org@repo" format

type SkillPlugin

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

SkillPlugin represents a discovered skill plugin

func NewSkillPlugin

func NewSkillPlugin(name, description, directory string) *SkillPlugin

NewSkillPlugin creates a new skill plugin

func (*SkillPlugin) Description

func (s *SkillPlugin) Description() string

Description returns the skill description

func (*SkillPlugin) Directory

func (s *SkillPlugin) Directory() string

Directory returns the skill directory path

func (*SkillPlugin) Name

func (s *SkillPlugin) Name() string

Name returns the skill name

func (*SkillPlugin) Type

func (s *SkillPlugin) Type() PluginType

Type returns the plugin type (skill)