Documentation
¶
Overview ¶
Ports packages/coding-agent/src/core/package-manager.ts.
Package packagecontent discovers resources exposed by Pi packages and cross-harness plugin manifests.
Index ¶
- func ApplyConfiguredDelta(kind Kind, relativePaths, basePatterns, deltaPatterns []string) ([]string, error)
- func ApplyPatterns(allPaths, patterns []string, baseDir string, kind Kind) ([]string, error)
- func Collect(paths []string, kind Kind) []string
- func Deduplicate(values []string) []string
- func DescribesResources(root string) bool
- func DiscoverAgentSkillDirs(dir string) []string
- func DiscoverAutomatic(dir string, kind Kind) []string
- func DiscoverSkillDirs(dir string) []string
- func DiscoversExtensionRoot(dir string) bool
- func EnabledByOverrides(resourcePath string, patterns []string, baseDir string, kind Kind) (bool, error)
- func FilterAutomatic(paths, overrides []string, baseDir string, kind Kind) ([]string, error)
- func FindMember(resources Resources, kind Kind, name string) (string, error)
- func FindSourceMember(root string, kind Kind, name string) (string, error)
- func HasPiManifest(root string) bool
- func InspectConfigured(root string, filters map[Kind][]string) (Resources, []MissingMember, error)
- func InspectConfiguredFiltered(root string, filters map[Kind][]string, resolve extsource.ResolveFunc) (Resources, []MissingMember, error)
- func InspectConfiguredWithResolver(root string, filters map[Kind][]string, resolve extsource.ResolveFunc) (Resources, []MissingMember, error)
- func ManifestGlobsThrow(root string) bool
- func MemberEnabled(root, member string, patterns []string) (bool, error)
- func OverridesThrow(patterns []string) bool
- func PackagePatternsThrow(root string, filters map[Kind][]string) bool
- func PatternsThrow(patterns []string) bool
- func PublicName(kind Kind, resourcePath, packageName string) (string, error)
- func ResolveConfigured(entries []string, baseDir string, kind Kind) []string
- func ResolveConfiguredWithError(entries []string, baseDir string, kind Kind) ([]string, error)
- func ResolvePackageChangelogPath(packageRoot string) string
- func ResourceEnabled(relativePath string, patterns []string) (bool, error)
- func SkillFile(resourcePath string) string
- func SplitPatterns(entries []string) (plain, patterns []string)
- func ValidateConfiguredEntries(entries []string, baseDir string, kind Kind) error
- func ValidateConfiguredForStartup(root string, filters map[Kind][]string) (Resources, []MissingMember, []ExtensionIssue, error)
- func ValidateConfiguredForStartupWithResolver(root string, filters map[Kind][]string, resolve extsource.ResolveFunc) (Resources, []MissingMember, []ExtensionIssue, error)
- func ValidateMember(root string, kind Kind, resourcePath string) error
- func ValidatePackageManifestSyntax(data []byte) error
- type ExtensionIssue
- type Kind
- type MissingMember
- type PackagePatternError
- type PatternState
- type PiManifest
- type ResourceState
- type Resources
- func Discover(root string) (Resources, error)
- func DiscoverCollecting(root string, collects func(Kind) bool) (Resources, error)
- func DiscoverConfigured(root string, collects func(Kind) bool, filters map[Kind][]string) (Resources, error)
- func DiscoverFiltered(root string, filters map[Kind][]string) (Resources, error)
- func Validate(root string) (Resources, error)
- func ValidateConfigured(root string, filters map[Kind][]string) (Resources, error)
- func ValidatePackage(root string) (Resources, error)
- func ValidatePackageManifest(root string, data []byte) (Resources, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ApplyConfiguredDelta ¶
func ApplyConfiguredDelta(kind Kind, relativePaths, basePatterns, deltaPatterns []string) ([]string, error)
ApplyConfiguredDelta validates and resolves exact Package-relative selector overrides. Authored autoload-disabled filters use ApplyAutoloadDisabledPatterns.
func ApplyPatterns ¶
ApplyPatterns applies allowlist, exclude, force-include, and force-exclude patterns without changing input order (applyPatterns, package-manager.ts:745-791). An include or exclude pattern that minimatch cannot compile fails when a path first reaches it.
func Collect ¶
Collect expands files or conventional resource directories for kind. Ports packages/coding-agent/src/core/package-manager.ts (collectFiles, collectAutoSkillEntries, collectAutoPromptEntries, collectAutoThemeEntries, collectAutoExtensionEntries, applyPatterns, isEnabledByOverrides).
func Deduplicate ¶
Deduplicate removes empty and repeated strings without changing order.
func DescribesResources ¶
DescribesResources reports whether root declares Package resources: a "pi" or "pig" package.json block, plugin metadata, or a conventional resource directory, even an empty one. Upstream collectPackageResources answers the same question for Pi's kinds (package-manager.ts:2235-2262); a local source directory that declares none is itself an extension.
func DiscoverAgentSkillDirs ¶
DiscoverAgentSkillDirs applies the cross-agent `.agents/skills` convention: root Markdown files are documentation, while nested Markdown files are standalone skills.
func DiscoverAutomatic ¶
DiscoverAutomatic returns resources in one conventional resource directory.
func DiscoverSkillDirs ¶
DiscoverSkillDirs recursively discovers skill roots and root-level Markdown skills. A directory containing SKILL.md is one skill and is not traversed further. Symlinked files and directories are followed, while hidden entries, node_modules, and paths excluded by .gitignore, .ignore, or .fdignore are skipped.
func DiscoversExtensionRoot ¶
DiscoversExtensionRoot reports whether auto-discovery loads dir as an extension when it sits in an extensions directory: Pi's package.json "pi.extensions", index.ts or index.js rule, or one of PiG's Go, Rust, Python or Lisp roots. A directory that holds only other entry files, such as index.mjs, loads when a path names it but is not found by discovery.
pig additive (D28): `pig install --validate-only` states what discovery would load.
func EnabledByOverrides ¶
func EnabledByOverrides(resourcePath string, patterns []string, baseDir string, kind Kind) (bool, error)
EnabledByOverrides reports whether one automatically discovered path remains active after configured overrides (isEnabledByOverrides, package-manager.ts:718-737). An exclude pattern that minimatch cannot compile fails.
func FilterAutomatic ¶
FilterAutomatic applies configured overrides to automatically discovered paths. It fails where Pi's isEnabledByOverrides throws.
func FindMember ¶
FindMember selects one discovered resource by public kind/name identity. pig additive (D18): named Piglet Package origins require stable member identity across exact and conventional Package resources. Extension source paths and Skill frontmatter are authoritative.
func FindSourceMember ¶
source may itself be one resource or a package/plugin root containing it.
func HasPiManifest ¶
HasPiManifest reports whether root's package.json has a "pi" object, which makes upstream resolve root as a Package (readPiManifest).
func InspectConfigured ¶
InspectConfigured returns the discovery inventory, including safe declarations whose files are missing. It uses discovery's tolerant manifest parsing and validates lexical, absolute-path, glob, and symlink boundaries. Missing declarations are data so pig config can disable them; ValidateConfigured remains strict for explicit validation.
func InspectConfiguredFiltered ¶
func InspectConfiguredFiltered(root string, filters map[Kind][]string, resolve extsource.ResolveFunc) (Resources, []MissingMember, error)
InspectConfiguredFiltered is InspectConfiguredWithResolver for a Package configured as a settings object; DiscoverFiltered states which kinds fall back to conventional directories.
func InspectConfiguredWithResolver ¶
func InspectConfiguredWithResolver(root string, filters map[Kind][]string, resolve extsource.ResolveFunc) (Resources, []MissingMember, error)
InspectConfiguredWithResolver returns the configured inventory while using resolve for extension validation. It preserves InspectConfigured semantics while allowing startup to reuse its source-resolution snapshot.
func ManifestGlobsThrow ¶
ManifestGlobsThrow reports whether the "pi" block of root's package.json declares, for a kind Pi collects, a glob that Node's globSync throws for. globSync builds its matcher before it reads a directory, so this reads only package.json; a caller that looks only for that throw discovers nothing when it is false.
func MemberEnabled ¶
MemberEnabled is applyPackageFilter's choice for one member of the Package at root (package-manager.ts:2280-2306): a nil filter enables it, an empty one disables it, and otherwise applyPatterns matches the member's absolute path with root as the base, so a pattern can name the member relative to root, by its base name or by its absolute path. A relative member is joined to root; a skill is its SKILL.md or Markdown file. A pattern minimatch cannot compile fails.
func OverridesThrow ¶
OverridesThrow reports whether isEnabledByOverrides can throw for patterns: whether some "!" pattern is one minimatch cannot compile. Only then can checking a path against them fail, so a caller looking only for that error collects no paths otherwise.
func PackagePatternsThrow ¶
PackagePatternsThrow reports whether collecting the Package at root with filters can throw: a manifest glob that globSync throws for (ManifestGlobsThrow), or an override of its "pi" block or a configured filter that minimatch cannot compile. Only these throw, so a caller looking only for the throw discovers nothing when it is false.
func PatternsThrow ¶
PatternsThrow reports whether applyPatterns can throw for patterns: whether some include or "!" pattern is one minimatch cannot compile.
func PublicName ¶
PublicName returns the stable kind/name identity for one Package resource. PackageName supplies the fallback identity for a root Dev Container.
func ResolveConfigured ¶
ResolveConfigured expands configured paths and applies their include/exclude patterns relative to baseDir. It returns nil if a path cannot be resolved. Use ResolveConfiguredWithError when resolution errors must be surfaced.
func ResolveConfiguredWithError ¶
ResolveConfiguredWithError expands configured paths and applies their include/exclude patterns relative to baseDir. Invalid file URLs return Node's error, and a pattern minimatch cannot compile returns its error, as Pi's resolveLocalEntries throws them.
func ResolvePackageChangelogPath ¶
ResolvePackageChangelogPath is package-manager.ts resolvePackageChangelogPath (b4b72a35): the changelog file of the package at packageRoot, or "" when it has none. The file is the manifest's `pi.changelogPath`, else CHANGELOG.md; an empty manifest value means no changelog, without the fallback. A path that does not exist, is not a regular file, or leaves the package root (once symbolic links are resolved) is ignored. Ports packages/coding-agent/src/core/package-manager.ts (resolvePackageChangelogPath).
func ResourceEnabled ¶
ResourceEnabled applies the shared include, exclude, exact force-include, and exact force-exclude rules to one package-relative resource path. A nil filter enables the resource; an explicit empty filter disables it. A pattern minimatch cannot compile fails.
func SkillFile ¶
SkillFile returns the Markdown file that defines the skill at resourcePath: resourcePath itself when it is a file, as a declared SKILL.md or a root-level Markdown skill is, else the SKILL.md inside the skill directory.
func SplitPatterns ¶
SplitPatterns separates literal entries from glob and override entries.
func ValidateConfiguredEntries ¶
ValidateConfiguredEntries returns the error ResolveConfiguredWithError returns for entries: a plain entry's resolution error, or the first pattern error a collected path meets. It collects the paths only when some pattern can throw.
func ValidateConfiguredForStartup ¶
func ValidateConfiguredForStartup(root string, filters map[Kind][]string) (Resources, []MissingMember, []ExtensionIssue, error)
ValidateConfiguredForStartup uses discovery's tolerant manifest parsing, then checks the enabled resources. Invalid JSON falls back to conventions and malformed Pi fields declare no members, without a diagnostic. Missing declarations and unresolvable extensions are returned separately so callers can continue loading other resources. Each enabled extension resolves once.
func ValidateConfiguredForStartupWithResolver ¶
func ValidateConfiguredForStartupWithResolver(root string, filters map[Kind][]string, resolve extsource.ResolveFunc) (Resources, []MissingMember, []ExtensionIssue, error)
ValidateConfiguredForStartupWithResolver applies startup validation using resolve for extension source classification. A startup-owned resolver can therefore share the exact Definition or error with later loading.
func ValidateMember ¶
ValidateMember validates one explicitly selected Package member.
func ValidatePackageManifestSyntax ¶
ValidatePackageManifestSyntax checks the typed Package manifest boundary without resolving members. It is used before authoring edits so malformed existing fields are never silently discarded or rewritten.
Types ¶
type ExtensionIssue ¶
ExtensionIssue is one enabled Package extension whose source does not resolve to a loadable extension.
type MissingMember ¶
MissingMember is one safe authored Package declaration that currently resolves to no file. Configuration UIs use it to recover by disabling the normal Package filter without treating the declaration as a runtime resource.
type PackagePatternError ¶
PackagePatternError is a pattern of a Package that Pi's collectPackageResources throws for: a manifest glob that Node's globSync rejects (expandPackageGlob), or a manifest override or configured filter that minimatch cannot compile (applyPatterns). Kind is the resource kind whose collection threw. Its message is the JavaScript error's.
func (*PackagePatternError) Error ¶
func (e *PackagePatternError) Error() string
func (*PackagePatternError) Unwrap ¶
func (e *PackagePatternError) Unwrap() error
type PatternState ¶
PatternState retains the first-match insertion order of upstream's path-to-enabled Map.
func ApplyAutoloadDisabledPatterns ¶
func ApplyAutoloadDisabledPatterns(allPaths, patterns []string, baseDir string, kind Kind) ([]PatternState, error)
ApplyAutoloadDisabledPatterns returns only paths touched by a pattern, with later patterns replacing their state. Plus/minus match exact paths; other entries use minimatch, and fail where its Minimatch constructor throws (applyAutoloadDisabledPatterns, package-manager.ts:793-810).
type PiManifest ¶
type PiManifest struct {
Extensions []string
Skills []string
Prompts []string
Themes []string
// ChangelogPath is the package-relative changelog file the "pi" object names. Nil when the field is absent or not a string; a
// present empty string means the package has no changelog (resolvePackageChangelogPath).
ChangelogPath *string
}
PiManifest mirrors upstream pi-manifest.ts PiManifest: the resource lists a package.json "pi" object declares. A nil field was absent or malformed.
func ReadPiManifest ¶
func ReadPiManifest(packageJSONPath string) *PiManifest
ReadPiManifest mirrors upstream readPiManifest. It returns nil when the file cannot be read or parsed, or when the package or its "pi" value is not a JSON object. A resource field is kept only when it is an array of strings.
type ResourceState ¶
ResourceState is a resource path and whether the configured patterns enable it.
func AutomaticStates ¶
func AutomaticStates(paths, overrides []string, baseDir string, kind Kind) ([]ResourceState, error)
AutomaticStates lists automatically discovered paths with whether the overrides leave each enabled (package-manager.ts addAutoDiscoveredResources). It fails where Pi's isEnabledByOverrides throws.
func ResolveConfiguredStates ¶
func ResolveConfiguredStates(entries []string, baseDir string, kind Kind) []ResourceState
ResolveConfiguredStates lists every resource the plain entries resolve, in collection order, with whether the patterns keep it (package-manager.ts resolveLocalEntries adds all files, then marks those the patterns enable).
type Resources ¶
type Resources struct {
PackageName string
PromptFiles []string
ThemeFiles []string
SkillDirs []string
ExtensionEntries []string
AgentFiles []string
MCPFiles []string
HookFiles []string
AgentEnvironments []string
}
Resources is the resource inventory discovered from one materialized source root.
func Discover ¶
Discover returns the package and plugin resources exposed by root. A Pi package.json supplies every Pi resource kind when it has a pi block; plugin metadata supplies Pi kinds only without that block. Missing or malformed manifests fall back to conventional directory discovery. A manifest glob that Node's globSync throws for stops discovery as it stops Pi's collectPackageResources: the error is a *PackagePatternError, and the Resources hold the kinds collected before it.
func DiscoverCollecting ¶
DiscoverCollecting is Discover for a Package whose configuration collects only some kinds: collects reports whether a kind is collected, and nil collects every kind. Pi collects no manifest entries for a kind that an autoload-disabled Package's patterns leave empty (applyPackageDeltaFilter), so such a kind cannot stop discovery.
func DiscoverConfigured ¶
func DiscoverConfigured(root string, collects func(Kind) bool, filters map[Kind][]string) (Resources, error)
DiscoverConfigured is DiscoverFiltered for a Package whose configuration collects only some kinds, as DiscoverCollecting states them.
func DiscoverFiltered ¶
DiscoverFiltered is Discover for a Package configured as a settings object. Upstream collectPackageResources reads such a Package kind by kind: a kind with patterns comes from the manifest entries when there are any and from the conventional directory otherwise (collectManifestFiles), and a kind without patterns comes from the manifest entries when it declares the kind and from the conventional directory when it does not (collectDefaultResources). Only a bare source string loads nothing for an undeclared kind of a "pi" block (package-manager.ts:2214-2358 collectPackageResources, collectDefaultResources, collectManifestFiles).
func Validate ¶
Validate checks a source inventory and its portable local file closure. A source without package.json remains valid for direct-resource installation.
func ValidateConfigured ¶
ValidateConfigured validates only resources enabled by installed Package filters. Authored Package validation remains strict through ValidatePackage.
func ValidatePackage ¶
ValidatePackage checks a Package manifest, inventory, public identities, and portable local closure. Unlike Validate, package.json and its name are required.
func ValidatePackageManifest ¶
ValidatePackageManifest validates prospective package.json data without writing it. Package authoring uses this before atomically replacing a manifest so a failed operation cannot leave invalid state behind.