catalog

Documentation

Overview

Package catalog fetches the agentdex agent catalog from the CUE Central Registry, validates it by evaluating the fetched module against its bundled schema, caches the resolved module version, and decodes the catalog into an internal representation. The root package agentdex maps each KnownAgent into its public types at detect time; this package never imports the root package, keeping the dependency one-way.

Index

• Constants
• Variables
• type Catalog
  • func LoadDir(dir string) (*Catalog, error)
• type KnownAgent
• type Loader
  • func New(registry Registry, opts ...Option) *Loader
  • func (l *Loader) Load(ctx context.Context) (*Result, error)
• type Option
  • func WithCacheDir(dir string) Option
  • func WithClock(now func() time.Time) Option
  • func WithModulePath(modulePath string) Option
  • func WithTTL(ttl time.Duration) Option
• type PathPair
• type Registry
  • func NewRegistry() (Registry, error)
• type Result
• type SkillsPaths
• type SkillsScope

Constants

const DefaultModulePath = "github.com/p3bot/agentdex/catalog@v1"

DefaultModulePath is the published catalog module loaded unless overridden.

const DefaultTTL = 24 * time.Hour

DefaultTTL is the version-resolution cache lifetime.

Variables

var (
	// ErrUnavailable signals that the catalog could not be loaded at all: the
	// registry was unreachable and no cached version or module data remained.
	// The root package wraps this; this sentinel states only the cause.
	ErrUnavailable = errors.New("no cached fallback available")

	// ErrInvalidCatalog signals that a fetched catalog module failed to load,
	// validate against its bundled schema, or decode. Distinct from
	// ErrUnavailable: the data was reachable but does not satisfy the contract.
	ErrInvalidCatalog = errors.New("invalid agentdex catalog")
)

Types

type Catalog

type Catalog struct {
	Agents map[string]KnownAgent
}

Catalog is the loaded set of known agents in this package's internal representation, keyed by catalog id.

func LoadDir

func LoadDir(dir string) (*Catalog, error)

LoadDir loads, validates, and decodes an agent catalog from a local CUE module directory, bypassing the registry entirely. Validation uses the same evaluation step as a fetched module, so schema rejects fail with ErrInvalidCatalog. No version is resolved and no network is used, so it is never stale and never raises ErrUnavailable.

type KnownAgent

type KnownAgent struct {
	ID          string
	Name        string
	Bin         string
	Description string
	Config      PathPair
	Skills      *SkillsPaths
	Agnostic    bool
	Provider    []string
	Homepage    string
}

KnownAgent is one decoded catalog entry. ID is populated from the catalog map key by the loader; the schema's #KnownAgent has no id field. Agnostic agents carry no Provider list; home-provider agents always have at least one.

type Loader

type Loader struct {
	// contains filtered or unexported fields
}

Loader fetches, validates, and decodes the agent catalog. Registry, clock, and cache directory are injected so load and cache logic are testable from inputs.

func New

func New(registry Registry, opts ...Option) *Loader

New constructs a Loader over the given registry with built-in defaults: the default module path, the default cache directory under $XDG_CACHE_HOME, the default TTL, and the wall clock. Options override any of these.

func (*Loader) Load

func (l *Loader) Load(ctx context.Context) (*Result, error)

Load resolves the catalog module version (honouring the cache and TTL), fetches the module, validates it against its bundled schema, and decodes it.

Version resolution requires the network; fetching a canonical module@version is served from CUE's content cache offline. After a first successful run the catalog loads offline within the TTL; a failed re-resolution after the TTL keeps the last resolved version (reported as stale); a first run with no network and no cached resolution fails with ErrUnavailable.

type Option

type Option func(*Loader)

Option configures a Loader.

func WithCacheDir

func WithCacheDir(dir string) Option

WithCacheDir overrides the version-resolution cache directory.

func WithClock

func WithClock(now func() time.Time) Option

WithClock overrides the clock; used to make TTL behaviour deterministic in tests.

func WithModulePath

func WithModulePath(modulePath string) Option

WithModulePath overrides the source catalog module path. The resolution cache is keyed by module path, so switching the override needs no special invalidation.

func WithTTL

func WithTTL(ttl time.Duration) Option

WithTTL overrides the version-resolution cache TTL.

type PathPair

type PathPair struct {
	Global string
	Local  string
}

PathPair is a catalog global/local directory pair before any expansion.

type Registry

type Registry interface {
	// ResolveLatestVersion maps a major-version module path (…/catalog@v1) to a
	// canonical version (…/catalog@v1.0.3). Requires the network.
	ResolveLatestVersion(ctx context.Context, modulePath string) (string, error)

	// Fetch returns the on-disk source directory for a canonical module@version.
	// Served from CUE's content cache offline once previously fetched.
	Fetch(ctx context.Context, modulePath string) (sourceDir string, err error)
}

Registry is the loader's boundary to the CUE module registry. Production wires the modconfig-backed implementation; tests substitute a stub. Nondeterministic network access lives entirely behind this interface.

func NewRegistry

func NewRegistry() (Registry, error)

NewRegistry constructs the production registry client. modconfig.NewRegistry configures itself from the environment (CUE_REGISTRY, cue login, CUE cache dir).

type Result

type Result struct {
	Catalog *Catalog
	// Version is the canonical module version the catalog was loaded from.
	Version string
	// Stale is true when re-resolution failed after the TTL expired and the last
	// resolved version was reused. The catalog is still usable; a caller may warn.
	Stale bool
}

Result is the outcome of a successful load.

type SkillsPaths

type SkillsPaths struct {
	Global SkillsScope
	Local  SkillsScope
}

SkillsPaths is catalog skills roots before expansion, split by scope. Primary is not stored; the library derives it after resolve.

type SkillsScope

type SkillsScope struct {
	Agents       string
	Native       string
	Alternatives []string
}

SkillsScope is one scope's classified skill roots before expansion. Empty strings and a nil Alternatives mean that role is unsupported. Alternatives is priority order (first is primary when agents and native are unset).