plugin

package
v1.0.22 Latest Latest
Warning

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

Go to latest
Published: May 7, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package plugin implements the DWS CLI plugin system. It loads, validates, and injects plugin capabilities (MCP servers, skills, pipeline hooks) into the existing CLI infrastructure.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuildPlugin

func BuildPlugin(pluginDir string) error

BuildPlugin runs the build command declared in plugin.json. It compiles the plugin's stdio server into a native binary so that users don't need language runtimes. Returns nil if no build is configured.

func SyncSkills

func SyncSkills(plugins []*Plugin)

SyncSkills copies plugin SKILL.md files into all detected agent skill directories (e.g. ~/.claude/skills/dws/, ~/.cursor/skills/dws/). This makes plugin skills available to AI agents without CLI releases.

Types

type BuildConfig

type BuildConfig struct {
	// Command is the shell command to compile the server.
	// Executed via "sh -c" in the plugin root directory.
	// Examples: "bun build --compile src/server.ts --outfile bin/server"
	//           "go build -o bin/server ./cmd/server"
	//           "pip install pyinstaller && pyinstaller --onefile src/server.py -n server --distpath bin/"
	Command string `json:"command"`

	// Output is the path to the compiled binary, relative to the plugin root.
	// Used to verify the build succeeded. Example: "bin/server"
	Output string `json:"output"`
}

BuildConfig declares how to compile the plugin's stdio server into a native binary. DWS runs this automatically during install so that plugin users never need language runtimes or dependency managers.

type ConfigItem

type ConfigItem struct {
	Description string `json:"description,omitempty"`
	Default     string `json:"default,omitempty"`
	Sensitive   bool   `json:"sensitive,omitempty"`
}

ConfigItem describes a user-configurable setting for a plugin.

type HookAdapter

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

HookAdapter wraps a plugin hook entry as a pipeline.Handler.

func NewHookAdapter

func NewHookAdapter(pluginName string, entry HookEntry) *HookAdapter

NewHookAdapter creates a pipeline handler from a plugin hook entry.

func (*HookAdapter) Handle

func (h *HookAdapter) Handle(ctx *pipeline.Context) error

func (*HookAdapter) Name

func (h *HookAdapter) Name() string

func (*HookAdapter) Phase

func (h *HookAdapter) Phase() pipeline.Phase

type HookEntry

type HookEntry struct {
	Phase   string `json:"phase"`             // "pre-request", "post-response", etc.
	Matcher string `json:"matcher,omitempty"` // glob pattern, e.g. "conference.*"
	Command string `json:"command"`           // shell command to execute
	Timeout int    `json:"timeout,omitempty"` // seconds, default 30
}

HookEntry describes a single pipeline hook.

type HooksConfig

type HooksConfig struct {
	Hooks []HookEntry `json:"hooks"`
}

HooksConfig describes pipeline hooks declared in a hooks.json file.

type Loader

type Loader struct {
	// PluginsDir is the root directory for all plugins.
	// Defaults to ~/.dws/plugins/.
	PluginsDir string

	// CLIVersion is the current CLI version, used for
	// minCLIVersion compatibility checks.
	CLIVersion string
}

Loader scans plugin directories and returns loaded, validated plugins.

func NewLoader

func NewLoader(cliVersion string) *Loader

NewLoader creates a Loader with default paths.

func (*Loader) GetPluginConfig

func (l *Loader) GetPluginConfig(pluginName, key string) (string, bool)

GetPluginConfig returns the value of a config key for a plugin. It checks pluginConfigs in settings.json first, then falls back to the userConfig default in the plugin's manifest.

func (*Loader) InjectPluginConfigEnv

func (l *Loader) InjectPluginConfigEnv()

func (*Loader) InstallFromDir

func (l *Loader) InstallFromDir(srcDir string) (*Plugin, error)

InstallFromDir copies a plugin from a source directory to the user plugins directory.

func (*Loader) InstallFromGit

func (l *Loader) InstallFromGit(gitURL string) (*Plugin, error)

InstallFromGit clones a git repository and installs the plugin. The workspace is extracted from the git URL (e.g. github.com/{workspace}/{name}).

func (*Loader) ListInstalled

func (l *Loader) ListInstalled() []PluginInfo

ListInstalled returns info about all installed plugins.

func (*Loader) ListPluginConfig

func (l *Loader) ListPluginConfig(pluginName string) map[string]string

ListPluginConfig returns all config key-value pairs for a plugin.

func (*Loader) LoadAll

func (l *Loader) LoadAll() []*Plugin

LoadAll loads user + dev plugins.

func (*Loader) LoadDev

func (l *Loader) LoadDev() []*Plugin

LoadDev loads dev plugins registered via `dws plugin dev`. Dev plugins are loaded from their source directories without copying.

func (*Loader) LoadUser

func (l *Loader) LoadUser() []*Plugin

LoadUser scans ~/.dws/plugins/user/ and returns enabled user plugins.

func (*Loader) RegisterDevPlugin

func (l *Loader) RegisterDevPlugin(name, absDir string) error

RegisterDevPlugin registers a source directory as a dev plugin.

func (*Loader) RemovePlugin

func (l *Loader) RemovePlugin(name string, keepData bool) error

RemovePlugin removes an installed plugin by name.

func (*Loader) SetEnabled

func (l *Loader) SetEnabled(name string, enabled bool) error

SetEnabled enables or disables a plugin in settings.json.

func (*Loader) SetPluginConfig

func (l *Loader) SetPluginConfig(pluginName, key, value string)

SetPluginConfig persists a config key-value pair for a plugin.

func (*Loader) UnregisterDevPlugin

func (l *Loader) UnregisterDevPlugin(name string) error

UnregisterDevPlugin removes a dev plugin registration.

func (*Loader) UnsetPluginConfig

func (l *Loader) UnsetPluginConfig(pluginName, key string) bool

UnsetPluginConfig removes a config key for a plugin.

type MCPServer

type MCPServer struct {
	Type     string            `json:"type"`               // "streamable-http" or "stdio"
	Endpoint string            `json:"endpoint,omitempty"` // required for streamable-http
	Command  string            `json:"command,omitempty"`  // required for stdio
	Args     []string          `json:"args,omitempty"`
	Env      map[string]string `json:"env,omitempty"`
	Headers  map[string]string `json:"headers,omitempty"` // custom HTTP headers (e.g. Authorization for third-party APIs)
	CLI      json.RawMessage   `json:"cli,omitempty"`     // CLIOverlay, passed through
}

MCPServer describes a single MCP server declared by a plugin.

type Manifest

type Manifest struct {
	Name          string                `json:"name"`
	Version       string                `json:"version"`
	Description   string                `json:"description,omitempty"`
	Type          string                `json:"type,omitempty"` // "managed" or "user"
	MinCLIVersion string                `json:"minCLIVersion,omitempty"`
	MCPServers    map[string]*MCPServer `json:"mcpServers,omitempty"`
	Skills        string                `json:"skills,omitempty"`
	Hooks         string                `json:"hooks,omitempty"`
	Permissions   []string              `json:"permissions,omitempty"`
	UserConfig    map[string]ConfigItem `json:"userConfig,omitempty"`
	Build         *BuildConfig          `json:"build,omitempty"`
}

Manifest represents the parsed contents of a plugin.json file.

func ParseManifest

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

ParseManifest reads and parses a plugin.json file.

func (*Manifest) Validate

func (m *Manifest) Validate(cliVersion string) error

Validate checks that a manifest is well-formed. It returns an error describing the first problem found, or nil if the manifest is valid. cliVersion is the current CLI version string for compatibility checks.

type Plugin

type Plugin struct {
	Manifest Manifest
	Root     string // absolute path to plugin directory
}

Plugin is a loaded, validated plugin ready for injection.

func (*Plugin) LoadHooks

func (p *Plugin) LoadHooks() (*HooksConfig, error)

LoadHooks reads the hooks.json file referenced by the manifest.

func (*Plugin) SkillsDir

func (p *Plugin) SkillsDir() string

SkillsDir returns the absolute path to the plugin's skills directory.

func (*Plugin) StdioClients

func (p *Plugin) StdioClients(uc *UserContext) []StdioServerClient

StdioClients returns StdioClient instances for all stdio-type MCP servers declared by this plugin. uc is the current user's identity; if non-nil, DWS_USER_ID and DWS_CORP_ID are injected as environment variables so that the subprocess can identify the caller without implementing its own auth.

func (*Plugin) ToServerDescriptors

func (p *Plugin) ToServerDescriptors() []market.ServerDescriptor

ToServerDescriptors converts a loaded plugin's MCP servers into market.ServerDescriptor values suitable for SetDynamicServers. Only streamable-http servers are converted; stdio servers are skipped (they require the stdio transport extension).

type PluginInfo

type PluginInfo struct {
	Name        string `json:"name"`
	Version     string `json:"version"`
	Type        string `json:"type"` // "user" or "dev"
	Enabled     bool   `json:"enabled"`
	Path        string `json:"path"`
	Description string `json:"description,omitempty"`
}

InstalledPlugins returns the list of all installed plugins with their status info. Used by `dws plugin list`.

type Settings

type Settings struct {
	EnabledPlugins   map[string]bool           `json:"enabledPlugins,omitempty"`
	PluginConfigs    map[string]map[string]any `json:"pluginConfigs,omitempty"`
	PluginAutoUpdate bool                      `json:"pluginAutoUpdate,omitempty"`
	DevPlugins       map[string]string         `json:"devPlugins,omitempty"` // name → absolute path
}

Settings holds user preferences for plugin management.

type StdioServerClient

type StdioServerClient struct {
	Key    string
	Client *transport.StdioClient
}

StdioServerClient pairs a transport.StdioClient with its server key.

type UserContext added in v1.0.10

type UserContext struct {
	UserID string
	CorpID string
}

UserContext holds the minimal user identity fields injected into stdio plugin subprocesses via environment variables.

Jump to

Keyboard shortcuts

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