Documentation
¶
Overview ¶
Package bundle is the in-memory representation of a plugin's portable core: a flat, path-keyed set of files (SKILL.md, AGENTS.md, .mcp.json, hooks/*, commands/*, agents/*, bin/*, and the real .claude-plugin/plugin.json). It is loaded from a checked-out source tree (FromDir), scanned to derive the typed manifest (ParseManifest) and the governance inventory (BuildInventory), and translated into a harness's on-disk layout at deploy time.
The registry does NOT host bundles. A Plugin's spec points at an external source (a pinned git commit or OCI digest); the controller resolves that pointer and records the derived manifest/inventory in status, and deploys materialize the harness filesystem from the source. This package owns the in-memory bundle shape only — it performs no network or registry I/O.
Index ¶
Constants ¶
const ( // MaxBundleFiles caps the number of regular files FromDir will load from a // source tree — a guard against a hostile/huge repo exhausting memory. MaxBundleFiles = 10_000 // MaxBundleBytes caps the total bytes FromDir will load into memory. MaxBundleBytes int64 = 128 << 20 // 128 MiB )
const ManifestPath = ".claude-plugin/plugin.json"
ManifestPath is the canonical location of the plugin manifest within a bundle.
Variables ¶
var ErrInvalidBundle = errors.New("invalid plugin bundle")
ErrInvalidBundle is returned when bundle content cannot be represented canonically (path traversal, backslash, absolute or non-clean path), when a declared file (e.g. the manifest) is present but malformed, or when the source tree exceeds the bundle size/file-count ceilings.
Functions ¶
func BuildInventory ¶
func BuildInventory(b *CanonicalBundle) *v1alpha1.PluginInventory
BuildInventory indexes a canonical bundle into a PluginInventory: the skills, sub-agents, commands, MCP servers, hooks, and bin/ executables it actually ships — the legible governance risk surface, derived by scanning bundle files (not the author-supplied manifest). Best-effort: a malformed declarative file is skipped rather than failing the resolve. Output is deterministic (sorted).
func ParseManifest ¶
func ParseManifest(b *CanonicalBundle) (*v1alpha1.PluginManifest, error)
ParseManifest parses the bundle's real .claude-plugin/plugin.json into the typed, faithful PluginManifest (the canonical lingua-franca manifest). Returns (nil, nil) when the bundle ships no manifest, or (nil, err) when the manifest is present but malformed (the caller decides whether to fail).
Types ¶
type CanonicalBundle ¶
CanonicalBundle is the portable core of a plugin: a flat, path-keyed set of files. It is NOT harness-specific; translation to a harness's on-disk layout happens at deploy time.
Paths are clean, relative, forward-slash separated (no leading "/" or "..").
func FromDir ¶
func FromDir(dir string) (*CanonicalBundle, error)
FromDir reads a checked-out plugin source tree rooted at dir into a CanonicalBundle. Directories, symlinks, and the .git directory are skipped; every regular-file path is normalized to forward slashes and traversal-checked. It is the bridge from a freshly-cloned source directory to the in-memory bundle the controller scans and records in status.
Source Files