plugin

Documentation

Index

• Constants
• func DecodeRenderResponse(result json.RawMessage) (string, error)
• func FormatHookResults(w io.Writer, results []HookResult, asJSON bool) error
• type Arg
• type Command
• type Diagnostic
• type Flag
• type HookConfig
• type HookFile
• type HookParams
• type HookResult
  • func RunPrePushHook(reg *Registry, params HookParams) ([]HookResult, error)
• type InstalledPlugin
• type Manifest
  • func LoadManifest(path string) (*Manifest, error)
  • func (m *Manifest) RendererForMethod(method string) string
• type PluginHost
  • func NewPluginHost() *PluginHost
  • func (h *PluginHost) Execute(pluginName, method string, params any) (json.RawMessage, error)
  • func (h *PluginHost) GetManifest(name string) *Manifest
  • func (h *PluginHost) ListLoaded() []string
  • func (h *PluginHost) Load(pluginDir string) error
  • func (h *PluginHost) Render(pluginName, method string, params RenderRequest) (string, error)
  • func (h *PluginHost) Stop(name string) error
  • func (h *PluginHost) StopAll() error
• type RPCClient
  • func NewRPCClient(entrypoint string) (*RPCClient, error)
  • func (c *RPCClient) Call(method string, params any) (json.RawMessage, error)
  • func (c *RPCClient) Close() error
• type RPCError
  • func (e *RPCError) Error() string
• type RPCRequest
• type RPCResponse
• type Registry
  • func NewRegistry() (*Registry, error)
  • func (r *Registry) GetPluginDir(name string) (string, error)
  • func (r *Registry) Install(source string) error
  • func (r *Registry) List() ([]InstalledPlugin, error)
  • func (r *Registry) Remove(name string) error
• type RenderContext
• type RenderRequest
• type RenderResponse
• type Subcommand

Constants

const RenderFormatText = "text"

Functions

func DecodeRenderResponse

func DecodeRenderResponse(result json.RawMessage) (string, error)

DecodeRenderResponse validates and extracts a renderer response. An empty text value is valid, but the text field itself is required.

func FormatHookResults

func FormatHookResults(w io.Writer, results []HookResult, asJSON bool) error

FormatHookResults writes hook diagnostics to w. When asJSON is true, the results are marshaled as JSON. Otherwise, a human-readable text format is used.

Types

type Arg

type Arg struct {
	Name        string `toml:"name"`
	Description string `toml:"description,omitempty"`
	Required    bool   `toml:"required,omitempty"`
}

Arg describes a positional argument for a command or subcommand.

type Command

type Command struct {
	Name        string       `toml:"name"`
	Description string       `toml:"description"`
	Method      string       `toml:"method,omitempty"`
	Renderer    string       `toml:"renderer,omitempty"`
	Args        []Arg        `toml:"args,omitempty"`
	Flags       []Flag       `toml:"flags,omitempty"`
	Subcommands []Subcommand `toml:"subcommands,omitempty"`
}

Command is a top-level command exposed by a plugin.

type Diagnostic

type Diagnostic struct {
	File     string `json:"file"`
	Severity string `json:"severity"` // "error", "warning", "info"
	Message  string `json:"message"`
	Rule     string `json:"rule,omitempty"`
	Path     string `json:"path,omitempty"` // JSON pointer within file
}

Diagnostic is a single issue reported by a hook.

type Flag

type Flag struct {
	Name        string `toml:"name"`
	Description string `toml:"description,omitempty"`
	Type        string `toml:"type,omitempty"`
	Default     string `toml:"default,omitempty"`
}

Flag describes a named flag for a command or subcommand. Supported types: "string" (default), "int", "bool", "string-array", "int-array".

type HookConfig

type HookConfig struct {
	PrePush  string `toml:"pre-push,omitempty"`
	PostPull string `toml:"post-pull,omitempty"` // reserved, not dispatched yet
}

HookConfig declares lifecycle hooks a plugin wants to intercept.

type HookFile

type HookFile struct {
	Path       string `json:"path"`
	Status     string `json:"status"` // "new", "modified", "deleted", "unchanged"
	ServerPath string `json:"server_path,omitempty"`
}

HookFile describes a single file in the hook payload.

type HookParams

type HookParams struct {
	ProjectRoot string     `json:"project_root"`
	Files       []HookFile `json:"files"`
}

HookParams is the input sent to a plugin's pre-push hook method.

type HookResult

type HookResult struct {
	PluginName  string       `json:"plugin_name"`
	Passed      bool         `json:"passed"`
	Diagnostics []Diagnostic `json:"diagnostics"`
}

HookResult is the response from a single plugin's hook execution.

func RunPrePushHook

func RunPrePushHook(reg *Registry, params HookParams) ([]HookResult, error)

RunPrePushHook executes the pre-push hook for every installed plugin that declares one. Returns nil, nil if no plugins declare a pre-push hook. Individual plugin failures are fail-open: a warning HookResult is returned but the error does not propagate.

type InstalledPlugin

type InstalledPlugin struct {
	Name    string
	Version string
	Dir     string
}

InstalledPlugin describes a plugin found in the registry.

type Manifest

type Manifest struct {
	Name        string     `toml:"name"`
	Version     string     `toml:"version"`
	Description string     `toml:"description"`
	Entrypoint  string     `toml:"entrypoint"`
	Commands    []Command  `toml:"commands"`
	Hooks       HookConfig `toml:"hooks"`
}

Manifest represents a plugin.toml file describing a plugin.

func LoadManifest

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

LoadManifest reads and parses a plugin.toml file.

func (*Manifest) RendererForMethod

func (m *Manifest) RendererForMethod(method string) string

RendererForMethod returns the optional text renderer declared for method. It is primarily used by built-in aliases that delegate to a plugin method without being registered from the plugin's command declaration.

type PluginHost

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

PluginHost manages multiple loaded plugin processes.

func NewPluginHost

func NewPluginHost() *PluginHost

NewPluginHost creates an empty plugin host.

func (*PluginHost) Execute

func (h *PluginHost) Execute(pluginName, method string, params any) (json.RawMessage, error)

Execute routes an RPC call to the named plugin.

func (*PluginHost) GetManifest

func (h *PluginHost) GetManifest(name string) *Manifest

GetManifest returns the manifest for a loaded plugin, or nil if not found.

func (*PluginHost) ListLoaded

func (h *PluginHost) ListLoaded() []string

ListLoaded returns the names of all loaded plugins.

func (*PluginHost) Load

func (h *PluginHost) Load(pluginDir string) error

Load reads a plugin manifest from pluginDir and starts its RPC process.

func (*PluginHost) Render

func (h *PluginHost) Render(pluginName, method string, params RenderRequest) (string, error)

Render calls a plugin's presentation-only renderer without displaying a second progress spinner for the same user command.

func (*PluginHost) Stop

func (h *PluginHost) Stop(name string) error

Stop stops a single loaded plugin process.

func (*PluginHost) StopAll

func (h *PluginHost) StopAll() error

StopAll stops all loaded plugin processes.

type RPCClient

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

RPCClient communicates with a plugin subprocess via JSON-RPC over stdio.

func NewRPCClient

func NewRPCClient(entrypoint string) (*RPCClient, error)

NewRPCClient starts a plugin subprocess and returns an RPC client for it.

func (*RPCClient) Call

func (c *RPCClient) Call(method string, params any) (json.RawMessage, error)

Call sends a JSON-RPC request and waits for the response.

func (*RPCClient) Close

func (c *RPCClient) Close() error

Close sends a shutdown notification and stops the plugin process.

type RPCError

type RPCError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    any    `json:"data,omitempty"`
}

RPCError is the error object in a JSON-RPC 2.0 response.

func (*RPCError) Error

func (e *RPCError) Error() string

type RPCRequest

type RPCRequest struct {
	JSONRPC string `json:"jsonrpc"`
	Method  string `json:"method"`
	Params  any    `json:"params,omitempty"`
	ID      int    `json:"id"`
}

RPCRequest is a JSON-RPC 2.0 request.

type RPCResponse

type RPCResponse struct {
	JSONRPC string          `json:"jsonrpc"`
	Result  json.RawMessage `json:"result,omitempty"`
	Error   *RPCError       `json:"error,omitempty"`
	ID      int             `json:"id"`
}

RPCResponse is a JSON-RPC 2.0 response.

type Registry

type Registry struct {
	Dir string
}

Registry manages installed plugins on disk at ~/.wk/plugins/.

func NewRegistry

func NewRegistry() (*Registry, error)

NewRegistry creates a Registry with the default directory (~/.wk/plugins/). It creates the directory if it does not exist. If WK_HOME is set, it is used instead of ~/.wk/ (useful for testing).

func (*Registry) GetPluginDir

func (r *Registry) GetPluginDir(name string) (string, error)

GetPluginDir returns the path to an installed plugin's directory.

func (*Registry) Install

func (r *Registry) Install(source string) error

Install copies a plugin from source into the registry. It reads the plugin.toml at source to determine the plugin name.

func (*Registry) List

func (r *Registry) List() ([]InstalledPlugin, error)

List scans the registry directory for installed plugins.

func (*Registry) Remove

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

Remove deletes an installed plugin by name.

type RenderContext

type RenderContext struct {
	Format      string `json:"format"`
	CommandPath string `json:"command_path,omitempty"`
}

RenderContext describes the CLI output request. Fields may be added over time; renderers should ignore context fields they do not recognize.

type RenderRequest

type RenderRequest struct {
	Result  json.RawMessage `json:"result"`
	Context RenderContext   `json:"context"`
}

RenderRequest asks a plugin to present an already-computed command result. Rendering is a presentation-only operation and must not rerun the command.

type RenderResponse

type RenderResponse struct {
	Text string `json:"text"`
}

RenderResponse is the result envelope returned by a plugin renderer.

type Subcommand

type Subcommand struct {
	Name        string `toml:"name"`
	Description string `toml:"description"`
	Method      string `toml:"method"`
	Renderer    string `toml:"renderer,omitempty"`
	Args        []Arg  `toml:"args,omitempty"`
	Flags       []Flag `toml:"flags,omitempty"`
}

Subcommand is a nested command under a top-level plugin command.