plugins

type Author struct {
	Name  string `json:"name,omitempty"`
	Email string `json:"email,omitempty"`
	URL   string `json:"url,omitempty"`
}

type BuildOptions = skills.BuildOptions

type BuildResult = skills.BuildResult

type ComponentInventory = ociplugins.ComponentInventory

type ComponentType string

type ContentOptions = skills.ContentOptions

type DematerializeRequest struct {
	// Name is the plugin name (kebab-case).
	Name string
	// Scope is the installation scope (user or project).
	Scope Scope
	// ProjectRoot is the project root path for project-scoped installs.
	// Empty for user-scoped.
	ProjectRoot string
}

type Dependency = skills.Dependency

type InfoOptions = skills.InfoOptions

type InstallOptions struct {
	// Name is the plugin name or OCI reference to install.
	Name string `json:"name"`
	// Version is the specific version to install. Empty means latest.
	Version string `json:"version,omitempty"`
	// Scope is the installation scope.
	Scope Scope `json:"scope,omitempty"`
	// Clients lists target clients (e.g., "claude-code").
	Clients []string `json:"clients,omitempty"`
	// Force allows overwriting unmanaged plugin directories.
	Force bool `json:"force,omitempty"`
	// ProjectRoot is the project root path for project-scoped installs.
	ProjectRoot string `json:"project_root,omitempty"`
	// Group is the group name to add the plugin to after installation.
	Group string `json:"group,omitempty"`
	// LayerData is the tar.gz content from an OCI layer. Internal use only — NOT exposed via HTTP API.
	LayerData []byte `json:"-"`
	// Reference is the full OCI reference (e.g. ghcr.io/org/plugin:v1).
	Reference string `json:"-"`
	// Digest is the OCI digest for upgrade detection.
	Digest string `json:"-"`
	// Components is the plugin's component inventory, hydrated from the OCI
	// artifact config by install-from-OCI/git flows. Internal use only.
	Components ComponentInventory `json:"-"`
	// Dependencies is the plugin's external dependency list, hydrated from the
	// OCI artifact config. Internal use only.
	Dependencies []Dependency `json:"-"`
	// Tag is the OCI tag, hydrated from the resolved reference. Internal use only.
	Tag string `json:"-"`
	// Description is the plugin description, hydrated from the OCI artifact
	// config or git manifest. Internal use only.
	Description string `json:"-"`
}

type InstallResult struct {
	// Plugin is the installed plugin.
	Plugin InstalledPlugin `json:"plugin"`
}

type InstallStatus = skills.InstallStatus

type InstalledPlugin struct {
	// Metadata contains the plugin's metadata.
	Metadata PluginMetadata `json:"metadata"`
	// Scope is the installation scope (user or project).
	Scope Scope `json:"scope"`
	// ProjectRoot is the project root path for project-scoped plugins. Empty for user-scoped.
	ProjectRoot string `json:"project_root,omitempty"`
	// Reference is the full OCI reference (e.g. ghcr.io/org/plugin:v1).
	Reference string `json:"reference,omitempty"`
	// Tag is the OCI tag (e.g. v1.0.0).
	Tag string `json:"tag,omitempty"`
	// Digest is the OCI digest (sha256:...) for upgrade detection.
	Digest string `json:"digest,omitempty"`
	// Status is the current installation status.
	Status InstallStatus `json:"status"`
	// InstalledAt is the timestamp when the plugin was installed.
	InstalledAt time.Time `json:"installed_at"`
	// Clients is the list of client identifiers the plugin is installed for.
	Clients []string `json:"clients,omitempty"`
	// Components is the inventory of component types declared by the plugin
	// (e.g. {"commands": 3, "skills": 2}). Extracted from the OCI artifact.
	Components ComponentInventory `json:"components,omitempty"`
	// Signature is the optional signing signature for the plugin artifact.
	Signature string `json:"signature,omitempty"`
	// Dependencies is the list of external plugin dependencies.
	Dependencies []Dependency `json:"dependencies,omitempty"`
}

type ListOptions = skills.ListOptions

type LocalBuild = skills.LocalBuild

type MaterializationAdapter interface {
	// Materialize extracts the plugin into the client's directory layout and,
	// for config-based clients, mutates the client config. Must be idempotent
	// for re-installs under the same (name, scope, projectRoot) — a force
	// reinstall overwrites the prior install.
	Materialize(ctx context.Context, req MaterializeRequest) (*MaterializeResult, error)
	// Dematerialize removes the plugin's filesystem footprint and reverts any
	// config mutations the adapter itself made. Must be idempotent: a missing
	// install is not an error.
	Dematerialize(ctx context.Context, req DematerializeRequest) error
	// SupportedComponents returns the component types this adapter loads.
	SupportedComponents() []ComponentType
	// ScopeSupport reports whether a project-scoped install degrades for this
	// client — i.e. the adapter can only materialize at user scope (typically
	// because it mutates a user-scoped config file). The returned struct also
	// carries an optional reason (not yet consumed by Info). Used by Info to
	// surface ProjectScopeDegradedClients without re-running Materialize.
	ScopeSupport() ScopeSupport
}

type MaterializeRequest struct {
	// Name is the plugin name (kebab-case).
	Name string
	// LayerData is the OCI tar.gz layer containing the whole plugin tree
	// (commands/, agents/, skills/, hooks/, .claude-plugin/). Produced by
	// OCI pull or built in-memory from a git clone.
	LayerData []byte
	// Scope is the installation scope (user or project).
	Scope Scope
	// ProjectRoot is the project root path for project-scoped installs.
	// Empty for user-scoped.
	ProjectRoot string
	// Components is the plugin's component inventory, used to warn on
	// component types the adapter does not materialize (e.g. Codex drops
	// commands/agents).
	Components ComponentInventory
}

type MaterializeResult struct {
	// InstalledComponents lists the component types the adapter materialized.
	InstalledComponents []ComponentType
	// DroppedComponents lists component types the plugin declares that this
	// adapter does NOT materialize.
	DroppedComponents []ComponentType
	// InstallPath is the root directory the adapter wrote (informational).
	InstallPath string
	// ProjectScopeDegraded is true when a project-scope install degrades
	// because the target client only supports user-scope materialization.
	ProjectScopeDegraded bool
}

type PluginContent struct {
	// Name is the plugin name from the OCI config labels.
	Name string `json:"name"`
	// Description is the plugin description from the OCI config labels.
	Description string `json:"description,omitempty"`
	// Version is the plugin version from the OCI config labels.
	Version string `json:"version,omitempty"`
	// License is the SPDX license identifier from the OCI config labels.
	License string `json:"license,omitempty"`
	// Manifest is the raw .claude-plugin/plugin.json body.
	Manifest string `json:"manifest"`
	// Files is the list of all files in the artifact with their sizes.
	Files []PluginFileEntry `json:"files"`
}

type PluginFileEntry = skills.SkillFileEntry

type PluginInfo struct {
	// Metadata contains the plugin's metadata.
	Metadata PluginMetadata `json:"metadata"`
	// InstalledPlugin contains the full installation record.
	InstalledPlugin *InstalledPlugin `json:"installed_plugin,omitempty"`
	// UnmaterializedComponents lists, per client type, the component types the
	// plugin declares that the installed client adapter does NOT load. Populated
	// by Info by diffing InstalledPlugin.Components against each installed
	// client adapter's SupportedComponents.
	UnmaterializedComponents map[string][]ComponentType `json:"unmaterialized_components,omitempty"`
	// ProjectScopeDegradedClients lists the client types for which a
	// project-scoped install degraded (the adapter could only materialize at
	// user scope — e.g. Codex always writes to the user-scoped config.toml).
	// Populated by Info; empty for user-scoped installs. Recomputed at read
	// time from the stored scope + each adapter's capability, mirroring the
	// UnmaterializedComponents pattern (no persistence needed — the degradation
	// is deterministic from scope + client type).
	ProjectScopeDegradedClients []string `json:"project_scope_degraded_clients,omitempty"`
}

type PluginManifest struct {
	Name        string `json:"name"`
	Version     string `json:"version,omitempty"`
	Description string `json:"description,omitempty"`
	Author      Author `json:"author,omitempty"`
	Homepage    string `json:"homepage,omitempty"`
	Repository  string `json:"repository,omitempty"`
	License     string `json:"license,omitempty"`
	// Keywords MUST be a JSON array (a string is a hard error — see strictStringSlice).
	Keywords strictStringSlice `json:"keywords"`
	// Component directories: each entry must be a relative path starting with "./".
	Commands   []string        `json:"commands,omitempty"`
	Agents     []string        `json:"agents,omitempty"`
	Skills     []string        `json:"skills,omitempty"`
	Hooks      []string        `json:"hooks,omitempty"`
	McpServers json.RawMessage `json:"mcpServers,omitempty"`
	LspServers json.RawMessage `json:"lspServers,omitempty"`
	// Raw is the full original document, preserved for round-tripping unknown fields.
	Raw json.RawMessage `json:"-"`
}

type PluginMetadata struct {
	// Name is the unique name of the plugin (kebab-case).
	Name string `json:"name"`
	// Version is the semantic version of the plugin.
	Version string `json:"version,omitempty"`
	// Description is a human-readable description of the plugin.
	Description string `json:"description,omitempty"`
	// Author is the plugin author or maintainer.
	Author string `json:"author,omitempty"`
	// License is the SPDX license identifier for the plugin.
	License string `json:"license,omitempty"`
	// Keywords is a list of keywords for categorization/search.
	Keywords []string `json:"keywords,omitempty"`
}

type PluginService interface {
	// Validate checks whether a plugin definition is valid.
	Validate(ctx context.Context, path string) (*ValidationResult, error)
	// Build builds a plugin from a local directory into an OCI artifact.
	Build(ctx context.Context, opts BuildOptions) (*BuildResult, error)
	// Push pushes a built plugin artifact to a remote registry.
	Push(ctx context.Context, opts PushOptions) error
	// ListBuilds returns all locally-built OCI plugin artifacts in the local store.
	ListBuilds(ctx context.Context) ([]LocalBuild, error)
	// DeleteBuild removes a locally-built OCI plugin artifact from the local store.
	DeleteBuild(ctx context.Context, tag string) error
	// GetContent retrieves the plugin.json body and file listing from an OCI
	// artifact without installing it. Works for both remote registry references
	// and local build tags.
	GetContent(ctx context.Context, opts ContentOptions) (*PluginContent, error)
	// Install resolves a plugin reference (OCI, git, or registry name), extracts
	// it, materializes it into each target client's directory layout via the
	// configured MaterializationAdapters, and persists the install record.
	Install(ctx context.Context, opts InstallOptions) (*InstallResult, error)
	// Uninstall removes a plugin from all target clients (dematerialize) and
	// deletes the install record. Idempotent for already-removed plugins.
	Uninstall(ctx context.Context, opts UninstallOptions) error
	// List returns installed plugins, optionally filtered by scope, client, or
	// group membership.
	List(ctx context.Context, opts ListOptions) ([]InstalledPlugin, error)
	// Info returns details for a single installed plugin, including the
	// component types each installed client adapter does NOT load.
	Info(ctx context.Context, opts InfoOptions) (*PluginInfo, error)
}

type PushOptions = skills.PushOptions

type Scope = skills.Scope

type ScopeSupport struct {
	// DegradesOnProjectScope is true when a project-scoped install degrades
	// for this client (typically because the adapter mutates a user-scoped
	// config file).
	DegradesOnProjectScope bool
	// Reason is an optional human-readable explanation intended for future
	// surfacing via Info (not yet consumed by Info — it currently reads only
	// DegradesOnProjectScope). Empty when the client does not degrade.
	Reason string
}

type UninstallOptions = skills.UninstallOptions

type ValidationResult = skills.ValidationResult