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 ¶
- func BuildPlugin(pluginDir string) error
- func SyncSkills(plugins []*Plugin)
- type BuildConfig
- type ConfigItem
- type HookAdapter
- type HookEntry
- type HooksConfig
- type Loader
- func (l *Loader) GetPluginConfig(pluginName, key string) (string, bool)
- func (l *Loader) InjectPluginConfigEnv()
- func (l *Loader) InstallFromDir(srcDir string) (*Plugin, error)
- func (l *Loader) InstallFromGit(gitURL string) (*Plugin, error)
- func (l *Loader) ListInstalled() []PluginInfo
- func (l *Loader) ListPluginConfig(pluginName string) map[string]string
- func (l *Loader) LoadAll() []*Plugin
- func (l *Loader) LoadDev() []*Plugin
- func (l *Loader) LoadUser() []*Plugin
- func (l *Loader) RegisterDevPlugin(name, absDir string) error
- func (l *Loader) RemovePlugin(name string, keepData bool) error
- func (l *Loader) SetEnabled(name string, enabled bool) error
- func (l *Loader) SetPluginConfig(pluginName, key, value string)
- func (l *Loader) UnregisterDevPlugin(name string) error
- func (l *Loader) UnsetPluginConfig(pluginName, key string) bool
- type MCPServer
- type Manifest
- type Plugin
- func (p *Plugin) LoadHooks() (*HooksConfig, error)
- func (p *Plugin) ResolveCLIOverlay(serverKey string) (mcptypes.CLIOverlay, bool)
- func (p *Plugin) SkillsDir() string
- func (p *Plugin) StdioClients(uc *UserContext) []StdioServerClient
- func (p *Plugin) ToServerDescriptors() []mcptypes.ServerDescriptor
- type PluginInfo
- type Settings
- type StdioServerClient
- type UserContext
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildPlugin ¶
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) 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 (*Loader) GetPluginConfig ¶
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 ¶
InstallFromDir copies a plugin from a source directory to the user plugins directory.
func (*Loader) InstallFromGit ¶
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 ¶
ListPluginConfig returns all config key-value pairs for a plugin.
func (*Loader) LoadDev ¶
LoadDev loads dev plugins registered via `dws plugin dev`. Dev plugins are loaded from their source directories without copying.
func (*Loader) RegisterDevPlugin ¶
RegisterDevPlugin registers a source directory as a dev plugin.
func (*Loader) RemovePlugin ¶
RemovePlugin removes an installed plugin by name.
func (*Loader) SetEnabled ¶
SetEnabled enables or disables a plugin in settings.json.
func (*Loader) SetPluginConfig ¶
SetPluginConfig persists a config key-value pair for a plugin.
func (*Loader) UnregisterDevPlugin ¶
UnregisterDevPlugin removes a dev plugin registration.
func (*Loader) UnsetPluginConfig ¶
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 ¶
ParseManifest reads and parses a plugin.json file.
type Plugin ¶
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) ResolveCLIOverlay ¶ added in v1.0.54
func (p *Plugin) ResolveCLIOverlay(serverKey string) (mcptypes.CLIOverlay, bool)
ResolveCLIOverlay resolves inline or external manifest CLI metadata exactly once. External files are opened relative to the plugin root with os.Root so absolute paths, parent traversal, and escaping symlinks fail closed.
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() []mcptypes.ServerDescriptor
ToServerDescriptors converts a loaded plugin's MCP servers into mcptypes.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
UserContext holds the minimal user identity fields injected into stdio plugin subprocesses via environment variables.