Module package_discovery 

Package progressive discovery, resource composition, and registry.

Provides the discovery and registry system for packages that compose extensions, skills, prompt fragments, and themes through validated manifests or conventional directories. Package metadata (name, description, version) is available without eagerly loading any contained resource content.

Package Format

Each package is a directory containing a package.toml manifest and optional resource subdirectories:

my-package/
  package.toml
  extensions/
    my-ext/
      extension.toml
  skills/
    my-skill/
      SKILL.md
  fragments/
    my-frag/
      FRAGMENT.md
  themes/
    my-theme/
      theme.toml

package.toml Format

name = "my-package"
description = "A collection of productivity tools."
version = "1.0.0"               # optional

# Optional: explicit resource allowlists (absent = auto-discover all)
extensions = ["my-ext"]
skills = ["my-skill"]
fragments = ["my-frag"]
themes = ["my-theme"]

# Optional: resources to exclude by name (matched across all types)
disabled = ["deprecated-skill"]

Validated Manifests vs Conventional Directories

When resource lists (extensions, skills, fragments, themes) are present, the package uses validated manifest mode: only listed resources are included, and all listed resources must exist (missing assets produce errors).

When resource lists are absent, the package uses conventional directory mode: all valid resources found in the subdirectories are included.

Discovery Precedence

Packages use the same precedence-based discovery as extensions and skills (see crate::resource). Higher precedence values override lower ones when package names collide.

Security

Resource paths are validated to stay within the package directory. Path traversal attempts (via symlinks or .. components) produce security diagnostic errors.

Unstable

This module is part of the unstable 0.x extension API. Breaking changes may occur between minor versions without a major version bump.

Structs

ComposedResource

A discovered resource within a package.

PackageComposedResourceLayers

Discovery layers produced by composing package-contained resources.

PackageManifest

Parsed package manifest from package.toml.

PackageRegistry

A registry of discovered packages supporting progressive disclosure and resource composition.

PackageResource

A discovered package resource with its manifest, filesystem path, and layer precedence.

Enums

PackageDiscoveryError

Errors from package discovery, manifest parsing, and resource composition.

ResourceKind

The kind of a resource within a package.

Functions

discover_packages

Discover packages across multiple layers with precedence-based deduplication.

package_composed_resource_layers

Compose package resources into direct discovery layers grouped by kind.