Documentation
¶
Overview ¶
Package plugin installs and tracks pi-go plugins — bundles of skills published through a Claude Code-compatible plugin marketplace.
It reads the same manifest format other agents already use, so the existing ecosystem (obra/superpowers-marketplace, claude-plugins-official, and any repository carrying a .claude-plugin/marketplace.json) works unchanged:
marketplace repo/.claude-plugin/marketplace.json catalog of plugins plugin repo/.claude-plugin/plugin.json one plugin's identity
Index ¶
- Constants
- func MarketplaceDir(piHome, name string) string
- func NormalizeSource(source string) string
- func PluginDir(piHome, name string) string
- func RegistryPath(piHome string) string
- func ResolveSkillsDir(pluginDir string, inst Installed) string
- func Root(piHome string) string
- func ValidName(name string) error
- type Installed
- type Logf
- type Manager
- func (m *Manager) AddMarketplace(ctx context.Context, source string) (MarketplaceRecord, error)
- func (m *Manager) Install(ctx context.Context, spec string) (*Installed, error)
- func (m *Manager) List() ([]Installed, error)
- func (m *Manager) ListMarketplaces() ([]MarketplaceRecord, error)
- func (m *Manager) MarketplacePlugins(ctx context.Context, name string) ([]MarketplacePlugin, error)
- func (m *Manager) ResolvePlugin(spec string) (MarketplacePlugin, MarketplaceRecord, string, error)
- func (m *Manager) Uninstall(name string) error
- func (m *Manager) Update(ctx context.Context, name string) (bool, error)
- func (m *Manager) UpdateMarketplace(ctx context.Context, name string) error
- type Manifest
- type Marketplace
- type MarketplaceMetadata
- type MarketplacePlugin
- type MarketplaceRecord
- type Owner
- type Registry
- type Source
Constants ¶
const ( // SourceRelative is a path inside the marketplace repository. SourceRelative = "relative" // SourceURL is a whole remote git repository holding one plugin. SourceURL = "url" // SourceGitSubdir is a subdirectory of a remote git repository. SourceGitSubdir = "git-subdir" // SourceGitHub is an "owner/name" shorthand for a GitHub repository. SourceGitHub = "github" )
Source kinds a marketplace entry can use. All three appear in the wild — across the marketplaces on this machine, url is the most common, git-subdir and plain relative paths follow.
const ( ManifestDir = ".claude-plugin" MarketplaceName = "marketplace.json" PluginName = "plugin.json" )
Manifest directory and file names, fixed by the convention this package reads and writes.
const RegistryVersion = 1
RegistryVersion is the on-disk schema version of installed.json.
Variables ¶
This section is empty.
Functions ¶
func MarketplaceDir ¶
MarketplaceDir returns the clone directory for a marketplace.
func NormalizeSource ¶
NormalizeSource turns a user-supplied marketplace or plugin source into a git URL or a local directory path.
Accepted forms: an absolute or relative directory, an http(s) or git URL, an scp-style git address (git@host:owner/repo), and the owner/repo shorthand for GitHub.
func RegistryPath ¶
RegistryPath returns the path of the installed.json registry.
func ResolveSkillsDir ¶
ResolveSkillsDir returns the directory holding a plugin's skills. An explicit SkillsDir on the record wins; otherwise the pi-go convention (.pi-go/skills) is preferred and the Claude Code convention (skills/) is the fallback. The plugin root is returned when neither exists, which is the convention for a plugin whose skills sit at the top level.
func ValidName ¶
ValidName reports whether a plugin or marketplace name is safe to use as a directory name.
Names come from a marketplace manifest, which is untrusted input fetched from a third-party repository: a name like "../../.ssh" would otherwise let a malicious catalog write outside the plugins directory.
Types ¶
type Installed ¶
type Installed struct {
// Name is the plugin name, which is also its directory under plugins/.
Name string `json:"name"`
// Marketplace is the marketplace it was installed from.
Marketplace string `json:"marketplace,omitempty"`
// Version is the catalog's version, when it records one.
Version string `json:"version,omitempty"`
// URL is the git remote it was cloned from, empty for local installs.
URL string `json:"url,omitempty"`
// Ref is the branch or tag that was checked out.
Ref string `json:"ref,omitempty"`
// Sha is the commit that was checked out, recorded so an update can tell
// whether anything actually moved.
Sha string `json:"sha,omitempty"`
// Path is the plugin's subdirectory within its repository: set for
// git-subdir sources, empty when the repository root is the plugin.
Path string `json:"path,omitempty"`
// SkillsDir is the relative path from the plugin root to its skills
// directory, empty when the default applies (see ResolveSkillsDir).
SkillsDir string `json:"skillsDir,omitempty"`
// InstalledAt is an RFC3339 timestamp.
InstalledAt string `json:"installedAt"`
}
Installed is one installed plugin.
type Logf ¶
Logf is a progress sink. A nil Logf discards messages — the TUI passes one that routes into the session log rather than the terminal, and the CLI passes one that prints.
type Manager ¶
type Manager struct {
// PiHome is the pi-go home directory, normally ~/.pi-go.
PiHome string
// Log receives progress messages; nil is safe and discards them.
Log Logf
}
Manager performs plugin and marketplace operations against one pi-go home.
func (*Manager) AddMarketplace ¶
AddMarketplace registers a marketplace from a local directory or a remote repository, and returns its record. Registering a marketplace that is already known refreshes it in place.
func (*Manager) Install ¶
Install installs the plugin named by spec, either "plugin" or "plugin@marketplace".
func (*Manager) ListMarketplaces ¶
func (m *Manager) ListMarketplaces() ([]MarketplaceRecord, error)
ListMarketplaces returns every registered marketplace, ordered by name.
func (*Manager) MarketplacePlugins ¶
MarketplacePlugins lists the plugins a registered marketplace offers.
func (*Manager) ResolvePlugin ¶
func (m *Manager) ResolvePlugin(spec string) (MarketplacePlugin, MarketplaceRecord, string, error)
ResolvePlugin finds a plugin's catalog entry, its marketplace record, and the directory the marketplace repository occupies.
A spec may be "plugin" — resolved against every registered marketplace, which is an error if more than one offers it — or "plugin@marketplace".
type Manifest ¶
type Manifest struct {
Name string `json:"name"`
Description string `json:"description"`
Version string `json:"version"`
Author Owner `json:"author"`
Homepage string `json:"homepage"`
Repository string `json:"repository"`
License string `json:"license"`
Keywords []string `json:"keywords"`
}
Manifest is a plugin's own identity, read from <plugin>/.claude-plugin/plugin.json.
func ReadManifest ¶
ReadManifest loads .claude-plugin/plugin.json from dir. A missing or nameless manifest is not an error — the caller falls back to the name the catalog used, and only treats the file as a best-effort version source.
type Marketplace ¶
type Marketplace struct {
Name string `json:"name"`
Description string `json:"description"`
Owner Owner `json:"owner"`
Metadata MarketplaceMetadata `json:"metadata"`
Plugins []MarketplacePlugin `json:"plugins"`
}
Marketplace is a catalog of installable plugins.
func ReadMarketplace ¶
func ReadMarketplace(dir string) (Marketplace, error)
ReadMarketplace loads .claude-plugin/marketplace.json from dir. A marketplace that does not name itself falls back to its directory name, so a catalog can always be addressed by name.
type MarketplaceMetadata ¶
type MarketplaceMetadata struct {
Description string `json:"description"`
Version string `json:"version"`
}
MarketplaceMetadata is the optional metadata block of a marketplace.
type MarketplacePlugin ¶
type MarketplacePlugin struct {
Name string `json:"name"`
Description string `json:"description"`
Version string `json:"version"`
Strict bool `json:"strict"`
Source Source `json:"source"`
}
MarketplacePlugin is one catalog entry.
func FindPlugin ¶
func FindPlugin(m Marketplace, name string) (MarketplacePlugin, bool)
FindPlugin returns the named entry from a marketplace catalog.
type MarketplaceRecord ¶
type MarketplaceRecord struct {
Name string `json:"name"`
// Source is the git URL or local directory the marketplace came from.
Source string `json:"source"`
// InstallLocation is the clone's directory.
InstallLocation string `json:"installLocation"`
// LastUpdated is an RFC3339 timestamp.
LastUpdated string `json:"lastUpdated"`
}
MarketplaceRecord is one registered marketplace.
type Registry ¶
type Registry struct {
Version int `json:"version"`
Marketplaces map[string]MarketplaceRecord `json:"marketplaces,omitempty"`
Plugins map[string]Installed `json:"plugins,omitempty"`
}
Registry is the persistent record of what a machine has installed.
func LoadRegistry ¶
LoadRegistry reads installed.json, returning an empty registry when the file does not exist yet. A registry written by a newer pi-go is an error rather than a silent downgrade: the fields it relies on may not be understood here.
func NewRegistry ¶
func NewRegistry() *Registry
NewRegistry returns an empty, usable registry. Both maps are initialized, so a caller can record into a freshly created registry without a nil-map panic.
func (*Registry) Save ¶
Save writes the registry, creating the plugins directory if needed. It writes to a temporary file and renames, so an interrupted save cannot leave a half-written registry that the next run would fail to parse.
func (*Registry) SkillDirs ¶
SkillDirs returns the skills directory of every installed plugin, ordered by plugin name for a stable result.
The order matters: skill loading lets a later directory override an earlier one, and callers place these *before* the user and project directories so an installed plugin can never silently replace a skill the user wrote or customized. Directories that do not exist are skipped, so a registry entry whose files were removed by hand does not break loading.
type Source ¶
type Source struct {
// Kind is one of the Source* constants.
Kind string
// Path is the plugin's directory: relative to the marketplace repository
// for SourceRelative, and to the cloned repository for SourceGitSubdir.
Path string
// URL is the git remote for the remote kinds.
URL string
// Repo is the "owner/name" form, for SourceGitHub.
Repo string
// Ref is a branch or tag to check out.
Ref string
// Sha is a commit the catalog pins, when it records one.
Sha string
}
Source locates a plugin. The convention expresses it either as a bare string path or as an object, so it unmarshals from both:
"./plugins/foo"
{"source":"url","url":"https://…/x.git","ref":"main","sha":"abc"}
{"source":"git-subdir","url":"https://…/x.git","path":"plugins/foo"}
{"source":"github","repo":"owner/name"}
func (Source) IsRemote ¶
IsRemote reports whether the source must be cloned rather than read from the marketplace repository already on disk.
func (*Source) UnmarshalJSON ¶
UnmarshalJSON accepts either the bare-string or the object form. A bare string is always a path within the marketplace repository.