plugins

package
v0.11.2 Latest Latest
Warning

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

Go to latest
Published: May 26, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func InstallFromGitHub

func InstallFromGitHub(ctx context.Context, repo string) error

InstallFromGitHub downloads the latest release tarball from a GitHub repo and installs it to ~/.ratchet/plugins/<name>/. repo must be in "owner/name" format.

func InstallFromLocal

func InstallFromLocal(src string) error

InstallFromLocal copies src to ~/.ratchet/plugins/<name>/ and registers it. src must contain a valid plugin manifest.

func Uninstall

func Uninstall(name string) error

Uninstall removes a plugin directory and its registry entry.

Types

type Author

type Author struct {
	Name  string `json:"name"`
	Email string `json:"email,omitempty"`
}

Author holds plugin author metadata.

type Capabilities

type Capabilities struct {
	Skills   string `json:"skills,omitempty"`   // relative dir path
	Agents   string `json:"agents,omitempty"`   // relative dir path
	Commands string `json:"commands,omitempty"` // relative dir path
	Tools    string `json:"tools,omitempty"`    // relative dir path
	Hooks    string `json:"hooks,omitempty"`    // relative file path
	MCP      string `json:"mcp,omitempty"`      // relative file path
}

Capabilities declares which capability directories/files a plugin provides.

type Command

type Command struct {
	Name    string // slash command name (derived from filename without extension)
	Content string // full markdown content
	Path    string
}

Command represents a slash command contributed by a plugin.

type DaemonTool

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

DaemonTool manages a long-running plugin process that handles multiple tool calls over its lifetime using JSON-RPC 2.0 over stdin/stdout.

func StartDaemon

func StartDaemon(ctx context.Context, binPath string) (*DaemonTool, error)

StartDaemon launches the daemon binary, performs the initialize handshake, and returns a ready DaemonTool.

func (*DaemonTool) Call

func (d *DaemonTool) Call(ctx context.Context, name string, args map[string]any) (any, error)

Call invokes a named tool on the daemon. It is goroutine-safe.

func (*DaemonTool) Defs

func (d *DaemonTool) Defs() []ToolDef

Defs returns the tool definitions declared by the daemon at initialize time.

func (*DaemonTool) Stop

func (d *DaemonTool) Stop() error

Stop gracefully shuts down the daemon: closes stdin, waits for exit with a timeout, then kills if necessary.

type DaemonToolRef

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

DaemonToolRef wraps a single named tool exposed by a DaemonTool.

func NewDaemonToolRef

func NewDaemonToolRef(daemon *DaemonTool, def ToolDef) *DaemonToolRef

NewDaemonToolRef creates a DaemonToolRef for the named tool.

func (*DaemonToolRef) Definition

func (r *DaemonToolRef) Definition() provider.ToolDef

Definition implements plugin.Tool.

func (*DaemonToolRef) Description

func (r *DaemonToolRef) Description() string

Description implements plugin.Tool.

func (*DaemonToolRef) Execute

func (r *DaemonToolRef) Execute(ctx context.Context, args map[string]any) (any, error)

Execute implements plugin.Tool by delegating to the parent daemon.

func (*DaemonToolRef) Name

func (r *DaemonToolRef) Name() string

Name implements plugin.Tool.

type ExecTool

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

ExecTool implements plugin.Tool by spawning a new process for each call. The binary receives JSON-encoded arguments on stdin and must write a JSON result to stdout.

func LoadExecTool

func LoadExecTool(toolDir string) (*ExecTool, error)

LoadExecTool reads tool.json from toolDir and locates the binary. The binary must be an executable file inside toolDir named after the tool.

func (*ExecTool) Definition

func (t *ExecTool) Definition() provider.ToolDef

Definition implements plugin.Tool.

func (*ExecTool) Description

func (t *ExecTool) Description() string

Description implements plugin.Tool.

func (*ExecTool) Execute

func (t *ExecTool) Execute(ctx context.Context, args map[string]any) (any, error)

Execute implements plugin.Tool. It marshals args to JSON, writes to stdin, and parses the binary's stdout as JSON.

func (*ExecTool) Name

func (t *ExecTool) Name() string

Name implements plugin.Tool.

type LoadResult

type LoadResult struct {
	Skills     []skills.Skill
	Agents     []agent.AgentDefinition
	Commands   []Command
	Hooks      *hooks.HookConfig
	Tools      []plugin.Tool
	MCPConfigs []MCPConfig
	// Daemons holds all started daemon processes so callers can stop them.
	// Call StopDaemons() to cleanly shut them all down.
	Daemons []*DaemonTool
}

LoadResult aggregates all capabilities discovered across loaded plugins.

func (*LoadResult) StopDaemons

func (r *LoadResult) StopDaemons()

StopDaemons stops all daemon tool processes tracked by this LoadResult.

type Loader

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

Loader discovers and loads plugins from a directory.

func NewLoader

func NewLoader(pluginDir string) *Loader

NewLoader creates a Loader targeting pluginDir.

func (*Loader) LoadAll

func (l *Loader) LoadAll(ctx context.Context) (*LoadResult, error)

LoadAll scans pluginDir for plugin directories, parses their manifests, and returns all discovered capabilities aggregated in a LoadResult. Daemon tools are started using ctx; cancel ctx to terminate them.

type MCPConfig

type MCPConfig struct {
	PluginName string
	PluginDir  string
	Servers    map[string]MCPServerSpec `json:"mcpServers"`
}

MCPConfig holds all MCP server declarations from a plugin's .mcp.json.

type MCPServerSpec

type MCPServerSpec struct {
	Command string            `json:"command"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
}

MCPServerSpec describes a single MCP server entry from .mcp.json.

type Manifest

type Manifest struct {
	Name         string       `json:"name"`
	Version      string       `json:"version"`
	Description  string       `json:"description"`
	Author       Author       `json:"author"`
	Capabilities Capabilities `json:"capabilities"`
}

Manifest represents a plugin's plugin.json manifest.

func LoadManifest

func LoadManifest(pluginDir string) (*Manifest, error)

LoadManifest reads a plugin manifest from pluginDir. It tries .ratchet-plugin/plugin.json first, then .claude-plugin/plugin.json.

type Registry

type Registry struct {
	Plugins map[string]RegistryEntry `json:"plugins"`
	// contains filtered or unexported fields
}

Registry tracks installed plugins in ~/.ratchet/plugins/registry.json.

func Load

func Load() (*Registry, error)

Load reads the registry from disk. Returns an empty registry if the file doesn't exist.

func LoadFrom

func LoadFrom(path string) (*Registry, error)

LoadFrom reads the registry from a specific path.

func (*Registry) Add

func (r *Registry) Add(name string, entry RegistryEntry) error

Add inserts or replaces a plugin entry and saves.

func (*Registry) Get

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

Get retrieves a plugin entry by name.

func (*Registry) Remove

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

Remove deletes a plugin entry and saves. Returns nil if the entry doesn't exist.

func (*Registry) Save

func (r *Registry) Save() error

Save writes the registry to disk.

type RegistryEntry

type RegistryEntry struct {
	Source      string    `json:"source"` // "github:org/repo" or "local:/path"
	Version     string    `json:"version"`
	InstalledAt time.Time `json:"installed_at"`
	Path        string    `json:"path"`
}

RegistryEntry records an installed plugin.

type ToolDef

type ToolDef struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Parameters  map[string]any `json:"parameters"`
	Protocol    string         `json:"protocol"` // "exec" or "daemon"
}

ToolDef is the on-disk format for a tool's tool.json definition file.

Jump to

Keyboard shortcuts

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