cache

package
v0.8.1 Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AliasesForGitHubEntry

func AliasesForGitHubEntry(owner, repo, inRepoPath, packageName string) []string

func BlobParentPrefixes

func BlobParentPrefixes(blobPath string) []string

func CheckLockEntries

func CheckLockEntries(lock lockfile.PackLock) error

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 ClassifyMaterialized(root, displayURL string, source githubsource.Source, commit, cacheKey string) (lockfile.Package, error)

func ClaudePluginManifestPath

func ClaudePluginManifestPath(root string) string

func CodexPluginManifestPath

func CodexPluginManifestPath(root string) string

func ComputeKey

func ComputeKey(identity string) string

func CopyPackageDirToCache

func CopyPackageDirToCache(source, identityPrefix string) (cacheKey, commit, destination string, err error)

func CursorPluginManifestPath

func CursorPluginManifestPath(root string) string

func DependencyKey

func DependencyKey(module, owner, repo, path string) string

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 EnsurePlugin

func EnsurePlugin(root string) error

func EntryDir

func EntryDir(cacheKey string) (string, error)

func FetchGitHubAssetURL

func FetchGitHubAssetURL(ctx context.Context, client *http.Client, rawURL string) (lockfile.Package, error)

func FileURL

func FileURL(filePath string) string

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 HasPluginManifest(root string) bool

func Inside

func Inside(root, path string) bool

Inside reports whether path is root or lies below it. Both must already be free of symbolic links.

func IsPackageRoot

func IsPackageRoot(root string) bool

func ListKeys

func ListKeys() ([]string, error)

func LookupAlias

func LookupAlias(alias string) (string, bool, error)

func MatchesContentHash

func MatchesContentHash(root, expected, actual string) bool

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 MaterializeGitHubTree(ctx context.Context, client *http.Client, source githubsource.Source, displayURL string, forceRefresh bool) (lockfile.Package, error)

func NormalizePluginLayout

func NormalizePluginLayout(root string) error

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 RepoDirIsPackageRoot(relativePaths map[string]struct{}, directory string) bool

func ResolveInside

func ResolveInside(root, declared string) (string, error)

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

func SourceFiles(root string) ([]string, error)

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

func StatFingerprint(lock lockfile.PackLock) (string, error)

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

func TreeDigest(root string) (string, error)

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

func VerifyLockCacheIntegrity(lock lockfile.PackLock) error

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

func VerifyLockCacheLayout(lock lockfile.PackLock) error

VerifyLockCacheLayout checks only that every cache entry still looks like a package. It reads no file contents and proves nothing about them.

func VerifyPackage

func VerifyPackage(pkg lockfile.Package) error

VerifyPackage recomputes the cache entry digest and compares it with the lock. A package without a content hash is unverified and passes.

Types

type CatalogOnlyError

type CatalogOnlyError struct {
	Spec    string
	Name    string
	Catalog string
	Missing []string
}

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 EntryRecord struct {
	Kind          lockfile.PackageKind `json:"kind"`
	SourceURL     string               `json:"source_url"`
	Owner         string               `json:"owner"`
	Repo          string               `json:"repo"`
	Path          string               `json:"path"`
	Commit        string               `json:"commit"`
	FetchedAtUnix int64                `json:"fetched_at_unix"`
}

func GetEntry

func GetEntry(cacheKey string) (EntryRecord, bool, error)

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

type LockEntryError struct {
	Package  lockfile.Package
	Expected string
}

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

type MultiplePluginsError struct {
	Root  string
	Names []string
}

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 is "codex", "cursor", or "claude".
	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: 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

type RemoteRestoreFunc func(pkg lockfile.Package, destination string) error

func GitHubRestore

func GitHubRestore(ctx context.Context, client *http.Client) RemoteRestoreFunc

Jump to

Keyboard shortcuts

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