plugin

package
v0.1.5 Latest Latest
Warning

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

Go to latest
Published: Sep 19, 2026 License: MIT Imports: 12 Imported by: 0

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

View Source
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.

View Source
const (
	ManifestDir     = ".claude-plugin"
	MarketplaceName = "marketplace.json"
	PluginName      = "plugin.json"
)

Manifest directory and file names, fixed by the convention this package reads and writes.

View Source
const RegistryVersion = 1

RegistryVersion is the on-disk schema version of installed.json.

Variables

This section is empty.

Functions

func MarketplaceDir

func MarketplaceDir(piHome, name string) string

MarketplaceDir returns the clone directory for a marketplace.

func NormalizeSource

func NormalizeSource(source string) string

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 PluginDir

func PluginDir(piHome, name string) string

PluginDir returns the install directory for a plugin.

func RegistryPath

func RegistryPath(piHome string) string

RegistryPath returns the path of the installed.json registry.

func ResolveSkillsDir

func ResolveSkillsDir(pluginDir string, inst Installed) string

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 Root

func Root(piHome string) string

Root returns the plugins directory under a pi-go home.

func ValidName

func ValidName(name string) error

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

type Logf func(format string, args ...any)

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

func (m *Manager) AddMarketplace(ctx context.Context, source string) (MarketplaceRecord, error)

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

func (m *Manager) Install(ctx context.Context, spec string) (*Installed, error)

Install installs the plugin named by spec, either "plugin" or "plugin@marketplace".

func (*Manager) List

func (m *Manager) List() ([]Installed, error)

List returns every installed plugin, ordered by name.

func (*Manager) ListMarketplaces

func (m *Manager) ListMarketplaces() ([]MarketplaceRecord, error)

ListMarketplaces returns every registered marketplace, ordered by name.

func (*Manager) MarketplacePlugins

func (m *Manager) MarketplacePlugins(ctx context.Context, name string) ([]MarketplacePlugin, error)

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".

func (*Manager) Uninstall

func (m *Manager) Uninstall(name string) error

Uninstall removes an installed plugin and its files.

func (*Manager) Update

func (m *Manager) Update(ctx context.Context, name string) (bool, error)

Update re-installs a plugin from its recorded source, reporting whether the commit changed. An empty name updates every installed plugin.

func (*Manager) UpdateMarketplace

func (m *Manager) UpdateMarketplace(ctx context.Context, name string) error

UpdateMarketplace refreshes registered marketplaces so their catalogs pick up new plugin versions.

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

func ReadManifest(dir string) (Manifest, error)

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 Owner

type Owner struct {
	Name  string `json:"name"`
	Email string `json:"email"`
}

Owner identifies a marketplace or plugin author.

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

func LoadRegistry(piHome string) (*Registry, error)

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

func (r *Registry) Save(piHome string) error

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

func (r *Registry) SkillDirs(piHome string) []string

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

func (s Source) IsRemote() bool

IsRemote reports whether the source must be cloned rather than read from the marketplace repository already on disk.

func (*Source) UnmarshalJSON

func (s *Source) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts either the bare-string or the object form. A bare string is always a path within the marketplace repository.

Jump to

Keyboard shortcuts

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