Documentation
¶
Index ¶
- Constants
- func AliasesForGitHubEntry(owner, repo, inRepoPath, packageName string) []string
- func BlobParentPrefixes(blobPath string) []string
- func CheckLockEntries(lock lockfile.PackLock) error
- func ClassifyMaterialized(root, displayURL string, source githubsource.Source, commit, cacheKey string) (lockfile.Package, error)
- func ClaudePluginManifestPath(root string) string
- func CodexPluginManifestPath(root string) string
- func ComputeKey(identity string) string
- func CopyPackageDirToCache(source, identityPrefix string) (cacheKey, commit, destination string, err error)
- func CursorPluginManifestPath(root string) string
- func DependencyKey(module, owner, repo, path string) string
- func EnsureLockCached(pkg lockfile.Package, restoreRemote RemoteRestoreFunc) (bool, error)
- func EnsureLockCachedVerifying(pkg lockfile.Package, restoreRemote RemoteRestoreFunc, ...) (bool, error)
- func EnsurePlugin(root string) error
- func EntryDir(cacheKey string) (string, error)
- func ExtractPeerTar(input io.Reader, destination string) error
- func FetchGitHubAssetURL(ctx context.Context, client *http.Client, rawURL string) (lockfile.Package, error)
- func FileURL(filePath string) string
- func HasPluginManifest(root string) bool
- func Inside(root, path string) bool
- func IsPackageRoot(root string) bool
- func ListKeys() ([]string, error)
- func LookupAlias(alias string) (string, bool, error)
- func MatchesContentHash(root, expected, actual string) bool
- func MaterializeGitHubTree(ctx context.Context, client *http.Client, source githubsource.Source, ...) (lockfile.Package, error)
- func NormalizePluginLayout(root string) error
- func RefetchPackage(pkg lockfile.Package, restoreRemote RemoteRestoreFunc) (digest string, replaced bool, err error)
- func RepoDirIsPackageRoot(relativePaths map[string]struct{}, directory string) bool
- func ResolveInside(root, declared string) (string, error)
- func SourceFiles(root string) ([]string, error)
- func StatFingerprint(lock lockfile.PackLock) (string, error)
- func TreeDigest(root string) (string, error)
- func UpsertEntry(cacheKey string, record EntryRecord, aliases []string) error
- func ValidKey(key string) bool
- func VerifyLockCacheIntegrity(lock lockfile.PackLock) error
- func VerifyLockCacheLayout(lock lockfile.PackLock) error
- func VerifyPackage(pkg lockfile.Package) error
- func VerifyPackageIncremental(pkg lockfile.Package) error
- func WithPeerRestore(ctx context.Context, ...) context.Context
- func WritePeerTar(root string, out io.Writer) error
- type CatalogOnlyError
- type CatalogPlugin
- type EntryRecord
- type IntegrityError
- type LockEntryError
- type MultiplePluginsError
- type PluginManifest
- type RemoteRestoreFunc
Constants ¶
const MaxPeerTarBytes = 512 << 20
Variables ¶
This section is empty.
Functions ¶
func AliasesForGitHubEntry ¶
func BlobParentPrefixes ¶
func CheckLockEntries ¶
CheckLockEntries verifies that every content-hashed GitHub entry still names the cache slot of its own repository, path and commit. agentpack writes the three together, so a commit that no longer matches its cache_key means the lock was edited by hand, and the content hash describes some other commit.
func ClassifyMaterialized ¶
func CodexPluginManifestPath ¶
func ComputeKey ¶
func CopyPackageDirToCache ¶
func DependencyKey ¶
func EnsureLockCached ¶
func EnsureLockCached(pkg lockfile.Package, restoreRemote RemoteRestoreFunc) (bool, error)
EnsureLockCached makes the cache entry for pkg usable and, when the lock carries a content hash, proves it matches before returning. An existing entry is never repaired here: a mismatch is an IntegrityError. A missing entry is built in a temporary directory and installed only once verified.
func EnsureLockCachedVerifying ¶ added in v0.12.11
func EnsureLockCachedVerifying(pkg lockfile.Package, restoreRemote RemoteRestoreFunc, verify func(lockfile.Package) error) (bool, error)
EnsureLockCachedVerifying is EnsureLockCached with the check an existing entry must pass, for a caller that has already proved it or may reuse a proof.
func EnsurePlugin ¶
func ExtractPeerTar ¶ added in v0.14.0
ExtractPeerTar uses an OS-confined root; package integrity is checked before installation.
func FetchGitHubAssetURL ¶
func FileURL ¶
FileURL returns a portable absolute file URL. Windows drive paths need a leading slash so net/url emits file:///C:/... instead of an opaque URL.
func HasPluginManifest ¶
func Inside ¶
Inside reports whether path is root or lies below it. Both must already be free of symbolic links.
func IsPackageRoot ¶
func MatchesContentHash ¶
MatchesContentHash reports whether the tree at root, whose digest is actual, is the tree a lock entry pins with expected.
agentpack 0.4.8 and earlier wrote every symbolic link of a GitHub archive as an empty file, and recorded the digest of that tree. The same package is now extracted with its in-package links kept, so a hash locked by those versions is also accepted when it equals the digest of this tree with each link counted as an empty file. Every file's bytes and every path are still covered; a new lock records the links themselves.
func MaterializeGitHubTree ¶
func NormalizePluginLayout ¶
func RefetchPackage ¶
func RefetchPackage(pkg lockfile.Package, restoreRemote RemoteRestoreFunc) (digest string, replaced bool, err error)
RefetchPackage builds the package again from its pinned source in a temporary directory and installs it over the cache entry only when it differs from what is cached. A fetched tree that contradicts the lock entry's content hash is discarded and leaves the cache untouched.
func RepoDirIsPackageRoot ¶
func ResolveInside ¶
ResolveInside resolves a path a package declares about itself. Symbolic links are followed, and the result must stay inside root: a declaration can name any part of the package and nothing else on the machine.
func SourceFiles ¶
SourceFiles returns sorted regular files without following symlinks. In a Git worktree it asks Git to apply repository, parent, info, global, and system excludes in one batch, including for tracked files via --no-index.
func StatFingerprint ¶
StatFingerprint digests the metadata of every content-hashed package's cache entry: each file's path, type, permission bits, size, and modification time. It reads no file contents, so it cannot replace VerifyPackage. It answers one question cheaply: has anything visibly changed since the entries were last verified in full?
func TreeDigest ¶
TreeDigest computes the sha256-tree-v1 digest of a package directory.
Every regular file and symbolic link below root is one record; directories and their modes are not recorded, so empty directories do not count. Records are ordered by slash-separated relative path, compared bytewise, and each is written to one SHA-256 stream as
kind 0x00 path 0x00 decimal-length 0x00 payload
where kind is "f" for a regular file, "x" for a regular file with any execute permission bit, and "l" for a symbolic link. The payload is the file bytes, or the link target for a link, which is never followed. Other permission bits, ownership, and timestamps are ignored. Any other file type is an error. The result is the algorithm prefix followed by lowercase hex.
func UpsertEntry ¶
func UpsertEntry(cacheKey string, record EntryRecord, aliases []string) error
func VerifyLockCacheIntegrity ¶
VerifyLockCacheIntegrity checks every locked package's cache entry: its content hash when the lock has one, and that it still looks like a package.
func VerifyLockCacheLayout ¶
VerifyLockCacheLayout checks only that every cache entry still looks like a package. It is read-only and proves nothing about file contents.
func VerifyPackage ¶
VerifyPackage recomputes the cache entry digest and compares it with the lock. A package without a content hash is unverified and passes.
func VerifyPackageIncremental ¶ added in v0.12.11
VerifyPackageIncremental is VerifyPackage for launches: an entry proved by an earlier full check is not read again while its metadata is unchanged. This is the trust the launch fast path already gives metadata.
Types ¶
type CatalogOnlyError ¶
CatalogOnlyError reports a marketplace catalog entry that defines a plugin in the catalog itself (Claude Code's "strict": false) and names component paths that its directory does not hold.
func (*CatalogOnlyError) Error ¶
func (err *CatalogOnlyError) Error() string
type CatalogPlugin ¶
type CatalogPlugin struct {
Name string
Catalog string
// Local says the plugin is a directory of the marketplace repository
// itself; Path is then relative to the repository root.
Local bool
// Owner, Repo and Ref name the GitHub repository and the commit, tag or
// branch of an entry that points at another repository.
Owner, Repo, Ref string
Path string
}
CatalogPlugin is where one named plugin of a marketplace catalog lives.
func ResolveCatalogPlugin ¶
func ResolveCatalogPlugin(archive []byte, directory, name string) (CatalogPlugin, error)
ResolveCatalogPlugin finds a plugin by name in the marketplace catalogs (.claude-plugin/marketplace.json, .cursor-plugin/marketplace.json, .agents/plugins/marketplace.json) below directory in a repository archive. It understands every source kind of the Claude Code marketplace schema that names a directory or a git repository: a relative path, {"source":"local"}, {"source":"github"}, {"source":"url"} and {"source":"git-subdir"}. An entry pinned with "sha" resolves to that commit, otherwise to its "ref".
type EntryRecord ¶
type IntegrityError ¶
type IntegrityError struct {
Package lockfile.Package
Path string
Expected string
Actual string
Fetched bool
}
IntegrityError reports a package tree that does not match its lock entry. Fetched distinguishes bytes just downloaded from an existing cache entry.
func (*IntegrityError) Details ¶
func (err *IntegrityError) Details() string
Details lays the same facts out one per line, so the digests and the cache path survive a renderer that reflows error text.
func (*IntegrityError) Error ¶
func (err *IntegrityError) Error() string
func (*IntegrityError) Repaired ¶
func (err *IntegrityError) Repaired() string
Repaired is the one-line report for a mismatch that RefetchPackage fixed.
func (*IntegrityError) Summary ¶
func (err *IntegrityError) Summary() string
Summary is the short form to show next to Details.
type LockEntryError ¶
LockEntryError reports a lock entry whose integrity fields contradict each other, which only happens when the entry was edited after it was locked.
func (*LockEntryError) Details ¶
func (err *LockEntryError) Details() string
func (*LockEntryError) Error ¶
func (err *LockEntryError) Error() string
func (*LockEntryError) Summary ¶
func (err *LockEntryError) Summary() string
type MultiplePluginsError ¶
MultiplePluginsError reports a marketplace catalog that lists more than one plugin where a single package was expected. `agentpack add` answers it by adding every plugin the catalog lists.
func (*MultiplePluginsError) Error ¶
func (err *MultiplePluginsError) Error() string
type PluginManifest ¶
type PluginManifest struct {
// Vendor names the harness that owns this manifest.
Vendor string
// Relative is the manifest path inside the package, slash-separated.
Relative string
Fields map[string]json.RawMessage
}
PluginManifest is one vendor's plugin.json as published in a package.
func ReadPluginManifests ¶
func ReadPluginManifests(root string) []PluginManifest
ReadPluginManifests returns the plugin manifests of a package in merge order: OMP, Codex, Cursor, then Claude, so that a later one wins where two vendors declare the same thing. An unreadable manifest is left out.
func (PluginManifest) Declared ¶
func (manifest PluginManifest) Declared(field string) (paths []string, inline []json.RawMessage)
Declared splits a manifest component field into the paths it names and the values it defines inline. Vendors accept a path, an inline value, or an array mixing the two.
type RemoteRestoreFunc ¶
func GitHubRestore ¶
func GitHubRestore(ctx context.Context, client *http.Client) RemoteRestoreFunc