Documentation
¶
Overview ¶
Package piglet provides piglet-based capability scoping for pig sessions.
D18: Stock Pig's generic `pig piglet` command and in-session capability scoping.
The package has two entry points:
- RunCommand: pre-session CLI (pig piglet list|show|validate|schema|add|remove)
- BuildExtension: in-session runtime scoping via extension.Extension
The extension reads a piglet YAML (from --piglet flag, PIG_PIGLET_PATH env, PIG_PIGLET_NAME env, or search paths), parses per-source tool scoping rules, and calls SetActiveTools to filter the tool set before the first agent turn.
Piglet is used by:
- managed runtimes (mounted YAML through PIG_PIGLET_PATH)
- local Pig invocations (--piglet flag or ~/.pig/piglets/<name>.yaml)
Piglet YAML schema types and parser.
A piglet is the complete agent definition: extensions with per-source capability scoping, MCP servers, skills, prompts, model config. The same YAML format is used locally (~/.pig/piglets/), on platform (ConfigMap from Agent CRD spec.piglet), and in independently published Piglet source.
Piglet is the agent-author scoping mechanism. A hosting platform may apply an additional administrative policy ceiling without rewriting the Piglet.
Index ¶
- Constants
- func ActiveAgentEnvironmentIdentity() string
- func AmbientPigletPath() string
- func BuildExtensionWithPiglet(initial *Piglet) extension.Extension
- func BuildExtensionWithPigletTools(initial *Piglet, owner func(extension.ToolInfo) string) extension.Extension
- func CheckRemoteAddable(path string) error
- func DistributionOffline() bool
- func RenderLineage(w io.Writer, out *LineageOutput)
- func RenderTree(w io.Writer, roots []*TreeNode)
- func Resolve(nameOrPath string) (string, error)
- func ResolveWithTrust(nameOrPath string, trustOverride *bool) (string, error)
- func RunCommand(args []string, stdout, stderr io.Writer) int
- func SchemaJSON() []byte
- func ScopeTools(piglet *Piglet, allTools []ToolInfo) []string
- func ShadowedWorkspacePiglet(nameOrPath string, trustOverride *bool) string
- func StripBuildTags() []string
- func StripDeltaReport(name string, current *StripSpec) []string
- func SystemPigletsDir() string
- func ValidateAgainstSchema(yamlBytes []byte) error
- func ValidateRemoteSource(raw string) error
- type AgentEnvironment
- type AgentEnvironmentPolicy
- type AgentEnvironmentRuntimeOptions
- type AgentEnvironmentRuntimeResult
- type AgentMount
- type AgentPigRuntime
- type AgentSecretBinding
- type AgentSecretTarget
- type AgentWorkspace
- type BinaryLineage
- type BuildSpec
- type Discovery
- type EffectiveResolution
- type ExtendsSpec
- type ExtensionEntry
- type LineageEntry
- type LineageLink
- type LineageOutput
- type LineageReport
- type LinkChanges
- type ModelConfig
- type NPMBinaries
- type NPMSource
- type NPMSourceOptions
- type Piglet
- func (p *Piglet) EffectiveAgentEnvironment() *AgentEnvironment
- func (p *Piglet) FrontendDir() (string, error)
- func (p *Piglet) HasFrontend() bool
- func (p *Piglet) ResolutionIdentity() ([]LineageEntry, string, string)
- func (p *Piglet) SourcePath() string
- func (p *Piglet) Validate() error
- func (p *Piglet) ValidateAgentEnvironmentLaunch() error
- func (p *Piglet) ValidateAgentEnvironmentRuntime() error
- type PigletInfo
- type PromptRef
- type ProvenanceCheck
- type RecordComponent
- type RecordInfo
- type ReleaseSpec
- type RemoveSpec
- type ResolveOptions
- type ResolvedAgentEnvironment
- type ResolvedExtension
- type ResolvedPackage
- type ResolvedSecrets
- type ResolvedSkill
- type RuntimeIO
- type SecretDeclaration
- type SecretSource
- type SetChange
- type SkillEntry
- type SlotMember
- type Slots
- type StripDelta
- type StripIDList
- type StripKeep
- type StripSpec
- func (s *StripSpec) BuildTags() []string
- func (s *StripSpec) HasFeature(id string) bool
- func (s *StripSpec) IsEmpty() bool
- func (s *StripSpec) KeepLists() []StripIDList
- func (s StripSpec) MarshalYAML() (any, error)
- func (s *StripSpec) Record() (undo func())
- func (s *StripSpec) StrippedIDs() []StrippedID
- type StrippedID
- type ToolInfo
- type TreeNode
Constants ¶
const ( StripKindTool = "tool" StripKindCommand = "command" StripKindExtension = "extension" StripKindAPI = "api" StripKindFeature = "feature" )
Strip kinds name the five strip lists in records and `pig piglet show`.
const ( // StripDispositionRuntime marks a built-in that stays compiled in and is // disabled when the Piglet runs. StripDispositionRuntime = "runtime" // StripDispositionBinary marks a built-in the Piglet Binary does not // link. Stock PiG running the Piglet disables it at runtime. StripDispositionBinary = "binary" )
Strip dispositions say how a Piglet Binary strips a built-in.
const InspectCommand = "piglet"
InspectCommand is the name of the read-only /piglet command the in-session extension registers. Its strip ID is "/piglet" in the commands list (pig additive, D92).
const MCPAdapterExtensionName = "pig-mcp-adapter"
MCPAdapterExtensionName is the conventional owner of MCP tools.
const MCPSourcePrefix = "mcp:"
MCPSourcePrefix identifies tools registered by an MCP adapter for one server.
const NPMKeyword = "pig-piglet"
NPMKeyword is the npm keyword that lists a package as a Piglet source. Catalogs find published Piglets by this keyword the way Pi's gallery finds Pi packages by `pi-package`.
Variables ¶
This section is empty.
Functions ¶
func ActiveAgentEnvironmentIdentity ¶
func ActiveAgentEnvironmentIdentity() string
ActiveAgentEnvironmentIdentity returns the already-verified active environment identity injected into the inner process, or empty for host execution. It never reads secret values.
func AmbientPigletPath ¶
func AmbientPigletPath() string
AmbientPigletPath is the Piglet file a container image bakes in at /opt/pig/piglet.yaml, or "" when there is none or the platform has no such location.
func BuildExtensionWithPiglet ¶
BuildExtensionWithPiglet returns an extension.Extension that applies Piglet-based tool scoping at runtime. The caller supplies the Piglet selected before extension loading. The extension applies tool scope on session_start and before_agent_start events. If the Piglet declares a systemPrompt, the extension returns it from before_agent_start so Pig core uses it as the session system prompt.
The returned Extension registers read-only /piglet inspection unless the process strips it (strip.commands: /piglet). Piglet selection/editing is deliberately not available in-session: a different composition is selected by a separate Pig invocation.
func BuildExtensionWithPigletTools ¶
func BuildExtensionWithPigletTools(initial *Piglet, owner func(extension.ToolInfo) string) extension.Extension
BuildExtensionWithPigletTools is BuildExtensionWithPiglet with the owner of extension-registered tools: owner names the Piglet extension entry whose `tools` allowlist scopes a tool, or "" when no loaded extension registered it.
func CheckRemoteAddable ¶
CheckRemoteAddable applies the checks `pig piglet add npm:<package>` makes to published Piglet source that need neither network nor materialized Packages. It guarantees that a source which passes can be registered from npm.
pig additive (D18): npm Piglet source publication.
func DistributionOffline ¶
func DistributionOffline() bool
DistributionOffline reports whether PI_OFFLINE or PIG_OFFLINE forbids the network access that remote Piglet distribution commands need.
func RenderLineage ¶
func RenderLineage(w io.Writer, out *LineageOutput)
RenderLineage writes the chain root first. Each link below the root lists what it adds (+), removes (-) and alters (~) against its base.
func RenderTree ¶
RenderTree draws roots with box-drawing characters. `*` marks the current Piglet, `[installed]` one with a built Binary, `(external)` a base outside the inventory.
func Resolve ¶
Resolve finds a piglet by name, checking the resolution order:
- Explicit path (already absolute or relative)
- PIG_PIGLET_PATH env var
- PIG_PIGLET_NAME env var → search paths
- Workspace: .pig/piglets/<name>.yaml, only when the project is trusted
- User: ~/.pig/piglets/<name>.yaml
- System: /etc/pig/piglets/<name>.yaml
The workspace is project config, so it follows project trust: a stored decision for the project, no prompt. Resolve reads that decision; ResolveWithTrust takes the run's --approve / --no-approve override ahead of it.
func ResolveWithTrust ¶
ResolveWithTrust is Resolve with a project trust override: nil defers to the stored decision for the working directory.
func RunCommand ¶
RunCommand handles `pig piglet <subcommand>`. Returns -1 if args do not match, 0 on success, and 1+ on error.
func SchemaJSON ¶
func SchemaJSON() []byte
SchemaJSON returns the published Piglet JSON Schema v1 bytes.
func ScopeTools ¶
ScopeTools intersects registered tools with root and extension allowlists. Resource loading/discovery decides which extensions exist; this function does not use Piglet membership as a second discovery gate.
func ShadowedWorkspacePiglet ¶
ShadowedWorkspacePiglet returns the name the run selected when the project defines a Piglet of that name in its config directory and project trust withholds it, or "" when nothing is withheld. An explicit path and an empty selection are never shadowed.
func StripBuildTags ¶
func StripBuildTags() []string
StripBuildTags lists every build tag a Piglet Binary can be built with, sorted: one for each built-in extension, strippable API and compile-out feature in the generated ID table.
func StripDeltaReport ¶
StripDeltaReport returns the strip delta report for the Piglet against its newest Binary record, with current as the Piglet's strip spec resolved now (nil reads the modes from the record). It returns nil when PiG has built no Binary for the Piglet.
func SystemPigletsDir ¶
func SystemPigletsDir() string
SystemPigletsDir is the machine-wide Piglet directory, or "" where PiG has none. A rooted path without a volume is drive-relative on Windows (C:\etc\pig\piglets), a place any local user can create, so Windows has no ambient system Piglet directory.
func ValidateAgainstSchema ¶
ValidateAgainstSchema checks Piglet YAML against the published JSON Schema closed vocabulary. It is the schema half of the schema/parser agreement; Go parsing (ParseBytes) adds the semantic checks the vocabulary schema cannot express.
func ValidateRemoteSource ¶
ValidateRemoteSource checks that raw is an npm or Git source reference that carries no authentication material, so it can be published. Rejected references and parser diagnostics never enter its errors.
Types ¶
type AgentEnvironment ¶
type AgentEnvironment struct {
Image string `yaml:"image,omitempty"`
DevContainer string `yaml:"devContainer,omitempty"`
Source string `yaml:"source,omitempty"`
PigRuntime *AgentPigRuntime `yaml:"pigRuntime,omitempty"`
Policy *AgentEnvironmentPolicy `yaml:"policy,omitempty"`
Workspace *AgentWorkspace `yaml:"workspace,omitempty"`
Mounts []AgentMount `yaml:"mounts,omitempty"`
Secrets []AgentSecretBinding `yaml:"secrets,omitempty"`
}
AgentEnvironment is a required whole-agent runtime when present. Exactly one source form is set; runtime and policy defaults are projected without rewriting the authored Piglet.
type AgentEnvironmentPolicy ¶
type AgentEnvironmentPolicy struct {
Preset string `yaml:"preset,omitempty"`
}
type AgentEnvironmentRuntimeOptions ¶
type AgentEnvironmentRuntimeOptions struct {
Engine string
Workspace string
Args []string
PigVersion string
StateRoot string
UnsafeHost bool
Commands runtimeCommands
IO RuntimeIO
}
AgentEnvironmentRuntimeOptions are machine-local execution inputs. They are never serialized into a Piglet or included in its portable identity.
type AgentEnvironmentRuntimeResult ¶
AgentEnvironmentRuntimeResult tells the caller whether startup should continue in the current process or terminate with the child engine's status.
func RunAgentEnvironment ¶
func RunAgentEnvironment(ctx context.Context, p *Piglet, options AgentEnvironmentRuntimeOptions) (AgentEnvironmentRuntimeResult, error)
RunAgentEnvironment enters a supported required Piglet environment before model, session, extension, or tool initialization. The current slice supports direct-image Piglets in explicit image-runtime mode with standard policy. Every other environment form remains fail-closed.
type AgentMount ¶
type AgentMount struct {
Source string `yaml:"source"`
Target string `yaml:"target"`
ReadOnly bool `yaml:"readonly,omitempty"`
}
AgentMount is one additional host bind exposed to the environment. Extra mounts are an elevated-policy capability because each one widens the host surface the agent can read or write.
func (*AgentMount) UnmarshalYAML ¶
func (m *AgentMount) UnmarshalYAML(node *yaml.Node) error
type AgentPigRuntime ¶
type AgentSecretBinding ¶
type AgentSecretBinding struct {
SecretRef string `yaml:"secretRef"`
Target AgentSecretTarget `yaml:"target"`
}
AgentSecretBinding maps one logical secret to a child environment target.
type AgentSecretTarget ¶
type AgentSecretTarget struct {
Env string `yaml:"env,omitempty"`
}
AgentSecretTarget currently supports child environment injection. File targets wait for the environment runtime materialization slice.
type AgentWorkspace ¶
type AgentWorkspace struct {
Folder string `yaml:"folder,omitempty"` // container path; default image WorkingDir then /workspace
ReadOnly *bool `yaml:"readonly,omitempty"` // nil = policy default (minimal read-only, else read-write)
}
AgentWorkspace selects where the invocation workspace lands inside the environment. The host source stays a machine-local execution input (default the current directory), so it is intentionally not a Piglet field.
func (*AgentWorkspace) UnmarshalYAML ¶
func (w *AgentWorkspace) UnmarshalYAML(node *yaml.Node) error
type BinaryLineage ¶
type BinaryLineage struct {
Path string `json:"path"`
Name string `json:"name"`
Version string `json:"version,omitempty"`
Digest string `json:"digest"`
Source string `json:"sourceDigest"`
Signer string `json:"signer"`
Trusted bool `json:"trusted"`
// Verified is false when the signature check fails: the executable bytes changed after signing, the signer is revoked, or the trust policy rejects the signer. The identity above is then only what the unverified manifest claims.
Verified bool `json:"verified"`
Signature string `json:"signature"`
}
BinaryLineage is the lineage a signed Piglet Binary carries: the identity it records, not an extends chain (the record keeps digests, not the chain). pig additive (D170): `pig piglet lineage` reports a Binary from its signed manifest.
type BuildSpec ¶
type BuildSpec struct {
Targets []string `yaml:"targets,omitempty"`
OutputName string `yaml:"outputName,omitempty"`
ExtensionRealization string `yaml:"extensionRealization,omitempty"`
}
BuildSpec defines portable build defaults. Builder selection and verification policy remain execution inputs and are intentionally not serialized here. pig additive (D18): Piglets own Pig's additive artifact build defaults. BuildSpec carries portable build defaults only. Delivery tier, strictness, update endpoint, release version, builder, credentials, and verification are execution or publication inputs, not portable Piglet source.
type Discovery ¶
type Discovery struct {
Extensions []string `yaml:"extensions,omitempty"`
Skills []string `yaml:"skills,omitempty"`
}
Discovery selects ambient Resource scopes by kind. Explicit Piglet entries are independent of discovery. Nil and empty lists both mean no ambient Resources in an active Piglet.
type EffectiveResolution ¶
type EffectiveResolution struct {
Piglet *Piglet `json:"-"`
Lineage []LineageEntry `json:"lineage"`
SourceDigest string `json:"sourceDigest"`
EffectiveDigest string `json:"effectiveDigest"`
GraphDigest string `json:"graphDigest"`
}
EffectiveResolution is a source Piglet resolved through its exact base lineage. Piglet contains no release/build/extends/remove metadata.
func ResolveEffective ¶
func ResolveEffective(path string) (*EffectiveResolution, error)
ResolveEffective resolves with no workspace anchor. Piglets that require a workspace:-anchored field fail until the caller supplies one explicitly.
func ResolveEffectiveWithOptions ¶
func ResolveEffectiveWithOptions(path string, options ResolveOptions) (*EffectiveResolution, error)
ResolveEffectiveWithOptions resolves path's typed extends lineage and deterministic merge algebra. Each source's Piglet-owned local paths are anchored before merge, so inherited resources are never re-anchored to a child directory.
pig additive (D18): additive Piglet derivation and exact lineage.
type ExtendsSpec ¶
type ExtendsSpec struct {
Source string `yaml:"source"`
Version string `yaml:"version,omitempty"`
AllowWiden bool `yaml:"allowWiden,omitempty"`
Remove *RemoveSpec `yaml:"remove,omitempty"`
}
ExtendsSpec selects one base Piglet source plus an optional author version constraint. Resolution pins the exact content digest in lineage.
type ExtensionEntry ¶
type ExtensionEntry struct {
Name string `yaml:"name"`
Origins []string `yaml:"origins,omitempty"`
Tools *[]string `yaml:"tools,omitempty"`
}
ExtensionEntry selects one extension and optionally limits its model tools. A nil Tools pointer means every registered tool; a non-nil empty slice means none.
func (*ExtensionEntry) UnmarshalYAML ¶
func (e *ExtensionEntry) UnmarshalYAML(node *yaml.Node) error
UnmarshalYAML handles the bare extension-name shorthand.
type LineageEntry ¶
type LineageEntry struct {
Source string `json:"source"`
Version string `json:"version,omitempty"`
Digest string `json:"digest"`
}
LineageEntry pins one source in an effective Piglet's inheritance chain.
type LineageLink ¶
type LineageLink struct {
Name string `json:"name"`
Source string `json:"source"`
Version string `json:"version,omitempty"`
Digest string `json:"digest"`
Changes *LinkChanges `json:"changes,omitempty"`
}
LineageLink is one Piglet in an inheritance chain: its identity and what it changes against the Piglet it extends. The root has no Changes. pig additive (D170): Piglet lineage diagnostics report the chain `extends` already resolves.
type LineageOutput ¶
type LineageOutput struct {
Kind string `json:"kind"`
Piglet string `json:"piglet"`
Chain []LineageLink `json:"chain"`
Binary *BinaryLineage `json:"binary,omitempty"`
Provenance *ProvenanceCheck `json:"provenance,omitempty"`
Advisories []string `json:"advisories"`
}
LineageOutput is the `pig piglet lineage` result. Chain is root first. Advisories lists advisories the chain inherits; stock Pig records none, so the list stays empty until a Piglet source supplies them.
func Lineage ¶
func Lineage(target, source, workspace string) (*LineageOutput, error)
Lineage reports target, a Piglet name or source path or a signed Piglet Binary. For a Binary, source (a name or path) supplies the extends chain and the Binary's recorded digests are checked against it. It reads local files.
type LineageReport ¶
type LineageReport struct {
Piglet string `json:"piglet"`
Source string `json:"source"`
Chain []LineageLink `json:"chain"`
}
LineageReport is the inheritance chain of one source Piglet, root first.
func SourceLineage ¶
func SourceLineage(path, workspace string) (*LineageReport, error)
SourceLineage reports the chain of the source Piglet at path with each link's change against its base. It reads local files only.
type LinkChanges ¶
type LinkChanges struct {
Extensions SetChange `json:"extensions"`
Packages SetChange `json:"packages"`
Skills SetChange `json:"skills"`
Tools SetChange `json:"tools"`
Permissions SetChange `json:"permissions"`
Slots SetChange `json:"slots"`
Strip SetChange `json:"strip"`
Settings SetChange `json:"settings"`
}
LinkChanges is the effective difference between a Piglet and its base: extensions, packages, skills, built-in tools, permissions (the agent environment), slots, strip lists and the remaining settings.
func (LinkChanges) Empty ¶
func (c LinkChanges) Empty() bool
Empty reports that the Piglet changes nothing against its base.
type ModelConfig ¶
type ModelConfig struct {
Provider string `yaml:"provider,omitempty"`
Name string `yaml:"name,omitempty"`
ContextWindow int `yaml:"contextWindow,omitempty"`
Thinking string `yaml:"thinking,omitempty"`
}
ModelConfig specifies the model to use.
type NPMBinaries ¶
NPMBinaries names the signed Piglet Binary release that matches a published npm source. Catalogs show `pig piglet pull <Ref>` next to the source install command.
type NPMSource ¶
type NPMSource struct {
// Dir is a new temporary directory. The caller removes it.
Dir string
Name string
Version string
// Packages maps each Package alias to its source in the published Piglet.
Packages map[string]string
// Files lists every file in Dir, slash-separated and sorted.
Files []string
Warnings []string
}
NPMSource is one generated, publishable npm package directory.
func BuildNPMSource ¶
func BuildNPMSource(options NPMSourceOptions) (source NPMSource, err error)
BuildNPMSource validates an authored Piglet and writes the npm package that publishes it into a new temporary directory.
The generated piglet.yaml is the authored file with every local Package replaced by the npm reference of that Package, because a remote Piglet source cannot take local paths. The generated package.json carries the Piglet's name and release.version, the `pig-piglet` keyword, and the `pig.piglet` path that `pig piglet add` reads. The authored files are not modified.
pig additive (D18): npm Piglet source publication.
type NPMSourceOptions ¶
type NPMSourceOptions struct {
// Path is the authored Piglet YAML file.
Path string
// Workspace anchors workspace-bound Piglet inputs during validation.
Workspace string
// NPMName overrides the published package name. The default is the name in a package.json beside the Piglet, then the Piglet's own name.
NPMName string
// PackageMap maps a Package alias to the npm reference that replaces its source.
PackageMap map[string]string
// Binaries is recorded in the generated package.json when the release has signed Binaries.
Binaries *NPMBinaries
}
NPMSourceOptions selects the authored Piglet and the publication choices that its YAML cannot express.
type Piglet ¶
type Piglet struct {
Name string `yaml:"name"`
Description string `yaml:"description,omitempty"`
Extends *ExtendsSpec `yaml:"extends,omitempty"`
BuiltinTools *[]string `yaml:"tools,omitempty"`
Packages map[string]string `yaml:"packages,omitempty"`
Extensions []ExtensionEntry `yaml:"extensions,omitempty"`
Skills []SkillEntry `yaml:"skills,omitempty"`
Discovery *Discovery `yaml:"discovery,omitempty"`
SystemPrompt *PromptRef `yaml:"systemPrompt,omitempty"`
AgentEnv *AgentEnvironment `yaml:"agentEnv,omitempty"`
Model *ModelConfig `yaml:"model,omitempty"`
Slots *Slots `yaml:"slots,omitempty"`
Build *BuildSpec `yaml:"build,omitempty"`
Release *ReleaseSpec `yaml:"release,omitempty"`
Secrets []SecretDeclaration `yaml:"secrets,omitempty"`
Strip *StripSpec `yaml:"strip,omitempty"` // pig additive (D92): built-ins this Piglet disables at runtime.
// contains filtered or unexported fields
}
Piglet is the top-level piglet YAML structure.
func Clone ¶
Clone returns an independent Piglet value while preserving its resolved source anchors. Runtime caches and locks are intentionally reset.
func ParseBytes ¶
ParseBytes parses and validates piglet YAML from bytes. Unknown keys are rejected to catch typos and unsupported fields early.
func (*Piglet) EffectiveAgentEnvironment ¶
func (p *Piglet) EffectiveAgentEnvironment() *AgentEnvironment
EffectiveAgentEnvironment applies semantic defaults without mutating source.
func (*Piglet) FrontendDir ¶
FrontendDir returns the absolute directory of the frontend slot's member, or "" when the Piglet has no frontend member. An inherited member resolves against the Piglet file that names it; the directory must exist inside that file's directory. pig additive (D91): a Piglet frontend member draws the interactive mode.
func (*Piglet) HasFrontend ¶
HasFrontend reports whether the Piglet fills the frontend slot. pig additive (D91): a Piglet frontend member draws the interactive mode.
func (*Piglet) ResolutionIdentity ¶
func (p *Piglet) ResolutionIdentity() ([]LineageEntry, string, string)
ResolutionIdentity returns copies of the exact lineage and effective/graph digests attached by ResolveEffective. Source-only Piglets return zero values.
func (*Piglet) SourcePath ¶
SourcePath returns the parsed Piglet source path when available.
func (*Piglet) ValidateAgentEnvironmentLaunch ¶
ValidateAgentEnvironmentLaunch reports whether the current runtime slice can launch this Piglet without inspecting machine-local engine availability.
func (*Piglet) ValidateAgentEnvironmentRuntime ¶
ValidateAgentEnvironmentRuntime blocks a Piglet Binary build until the builder can preserve and execute the required whole-process environment. Launch support is checked separately because runtime slices can land before portable Binary/Image execution.
type PigletInfo ¶
type PigletInfo struct {
Name string
Description string
Path string
Location string // "workspace", "user", "system", or "binary"
Records []RecordInfo
}
PigletInfo describes discovered Piglet source and Binary facets.
func List ¶
func List() ([]PigletInfo, error)
List returns all discoverable Piglet rows, merging source and managed Piglet Binary records. Malformed state is an error. pig additive (D41): Piglet inventory includes Piglet Binary facets.
type ProvenanceCheck ¶
type ProvenanceCheck struct {
Source string `json:"source"`
SourceDigest string `json:"sourceDigest"`
EffectiveDigest string `json:"effectiveDigest"`
Matches bool `json:"matches"`
//portlint:allow emptydrop PiG-only format with no Pi counterpart (Pi has no Piglets or runtime slot)
Mismatches []string `json:"mismatches,omitempty"`
}
ProvenanceCheck compares the Piglet digests a Binary's signed manifest records with those recomputed from a source Piglet.
func CheckProvenance ¶
func CheckProvenance(manifest signature.Manifest, source string) (*ProvenanceCheck, error)
CheckProvenance recomputes the source and effective digests of the Piglet named by source and compares them with manifest. A mismatch returns the check and an error naming each differing digest.
type RecordComponent ¶
RecordComponent is one executable component's realization and materialization as recorded in a managed Piglet resolution record's component plan.
type RecordInfo ¶
type RecordInfo struct {
Path string
ResolutionPath string
ArtifactPath string
PigletDigest string
ReleaseVersion string
Target string
ArtifactDigest string
VerificationOK bool
ComponentPlanDigest string
ResolutionDigest string
BinaryDigest string
CurrentPath string
Components []RecordComponent
// Strip lists the built-ins the Binary record says its Piglet strips.
Strip []StrippedID
// StripKeep lists the Binary's keep-mode strip lists and their kept IDs.
StripKeep []StripIDList
}
RecordInfo describes one managed Piglet Binary record/artifact facet.
type ReleaseSpec ¶
type ReleaseSpec struct {
Version string `yaml:"version,omitempty"`
}
ReleaseSpec carries Piglet release identity, separate from portable build defaults. release.version is the distributed artifact's SemVer.
type RemoveSpec ¶
type RemoveSpec struct {
Packages []string `yaml:"packages,omitempty"`
Extensions []string `yaml:"extensions,omitempty"`
Skills []string `yaml:"skills,omitempty"`
// Slots names inherited slots whose member is removed, so PiG's own
// part applies again.
// pig additive (D91): a Piglet frontend member draws the interactive mode.
Slots []string `yaml:"slots,omitempty"`
// Strip re-enables inherited strip entries. It widens the base, so it
// requires allowWiden.
// pig additive (D92): Piglet strip lists.
Strip *StripSpec `yaml:"strip,omitempty"`
}
RemoveSpec names inherited collection members removed before child replacement/addition.
type ResolveOptions ¶
type ResolveOptions struct {
Workspace string
}
ResolveOptions supplies machine-local anchors that are not portable Piglet identity.
type ResolvedAgentEnvironment ¶
ResolvedAgentEnvironment identifies the concrete image or Dev Container selected by a Piglet environment source.
func ResolveAgentEnvironment ¶
func ResolveAgentEnvironment(p *Piglet) (*ResolvedAgentEnvironment, error)
ResolveAgentEnvironment validates and materializes the optional environment. It does not start an engine or execute lifecycle commands.
type ResolvedExtension ¶
type ResolvedExtension struct {
Entry ExtensionEntry
Path string // Resolved filesystem path
Origin string // The first typed origin that resolved successfully.
}
ResolvedExtension is an extension with its origin resolved to a concrete path.
func ResolveExtensions ¶
func ResolveExtensions(p *Piglet) ([]ResolvedExtension, []error)
ResolveExtensions resolves all extension origins to concrete filesystem paths. pig additive (D18): Package and typed-source origins use the generic side-effect-free install materializer before member selection. Returns resolved extensions and any errors for unresolvable entries.
type ResolvedPackage ¶
func ResolvePackages ¶
func ResolvePackages(p *Piglet) ([]ResolvedPackage, error)
ResolvePackages materializes every declared Package without mutating Package settings and returns its canonical root for lock/record construction.
type ResolvedSecrets ¶
type ResolvedSecrets struct {
// contains filtered or unexported fields
}
ResolvedSecrets contains transient secret values for immediate consumers. It must never be serialized, logged, placed in records/sessions, or returned by inspection APIs.
func ResolveRequiredSecrets ¶
func ResolveRequiredSecrets(ctx context.Context, p *Piglet) (*ResolvedSecrets, error)
ResolveRequiredSecrets resolves every logical secret consumed by the agent environment. Unused declarations remain inspectable without requiring machine-local availability.
func (*ResolvedSecrets) AgentEnvironment ¶
func (r *ResolvedSecrets) AgentEnvironment(p *Piglet) (map[string]string, error)
AgentEnvironment returns child environment variables for declared bindings. Values are copied so callers may zero their map without mutating the resolver.
func (*ResolvedSecrets) Clear ¶
func (r *ResolvedSecrets) Clear()
Clear overwrites transient values and drops references after immediate use.
func (*ResolvedSecrets) RuntimeEnvironment ¶
func (r *ResolvedSecrets) RuntimeEnvironment() (map[string]string, error)
RuntimeEnvironment carries resolved logical values into a verified inner Pig process without exposing values on argv. Keys reveal no logical names.
type ResolvedSkill ¶
type ResolvedSkill struct {
Entry SkillEntry
Path string // Resolved filesystem path
Origin string // The first typed origin that resolved successfully.
}
ResolvedSkill is a skill with its origin resolved to a concrete path.
func ResolveSkills ¶
func ResolveSkills(p *Piglet) ([]ResolvedSkill, []error)
ResolveSkills resolves all skill origins to concrete filesystem paths.
type SecretDeclaration ¶
type SecretDeclaration struct {
Name string `yaml:"name"`
From SecretSource `yaml:"from"`
}
SecretDeclaration declares a logical secret name and exactly one machine- local source. Values never enter portable Piglet state.
type SecretSource ¶
type SecretSource struct {
Env string `yaml:"env,omitempty"`
File string `yaml:"file,omitempty"`
Ref string `yaml:"ref,omitempty"`
}
SecretSource is the closed env|file|ref source union.
type SetChange ¶
type SetChange struct {
//portlint:allow emptydrop PiG-only format with no Pi counterpart (Pi has no Piglets or runtime slot)
Added []string `json:"added,omitempty"`
//portlint:allow emptydrop PiG-only format with no Pi counterpart (Pi has no Piglets or runtime slot)
Removed []string `json:"removed,omitempty"`
//portlint:allow emptydrop PiG-only format with no Pi counterpart (Pi has no Piglets or runtime slot)
Changed []string `json:"changed,omitempty"`
}
SetChange lists the names a Piglet adds, removes and alters against its base.
type SkillEntry ¶
type SkillEntry struct {
Name string `yaml:"name"`
Origins []string `yaml:"origins,omitempty"` // Required unless Content is embedded.
Description string `yaml:"description,omitempty"`
Content string `yaml:"content,omitempty"`
}
SkillEntry represents a skill with an origin.
func (*SkillEntry) UnmarshalYAML ¶
func (s *SkillEntry) UnmarshalYAML(node *yaml.Node) error
UnmarshalYAML handles the bare skill-name shorthand.
type SlotMember ¶
type SlotMember struct {
// Member is the member's directory, relative to the Piglet file that
// names it.
Member string `yaml:"member"`
// contains filtered or unexported fields
}
SlotMember is the member that fills one slot.
type Slots ¶
type Slots struct {
// Frontend is the frontend member: a Go module whose root package
// exports func Frontend() frontend.Frontend. The native builder fuses
// it into the Binary.
Frontend *SlotMember `yaml:"frontend,omitempty"`
}
Slots names the members that replace a part of PiG. A child Piglet inherits each slot, replaces a slot by naming it, or removes one with extends.remove.slots. pig additive (D91): a Piglet frontend member draws the interactive mode.
type StripDelta ¶
type StripDelta struct {
// FromPigVersion is the version of the core that built the Binary.
FromPigVersion string
// ToPigVersion is the running core's version.
ToPigVersion string
// Added counts the IDs the running core's table adds.
Added int
// LeftOut names the added IDs a keep-mode list strips, as slot IDs.
LeftOut []string
// NowIncluded names the added IDs a deny-mode list leaves enabled.
NowIncluded []string
}
StripDelta is the change of the strip table since a Piglet's newest Binary.
func (StripDelta) Lines ¶
func (d StripDelta) Lines() []string
Lines renders the report: one header line, then the two lists when the table adds an ID.
type StripIDList ¶
StripIDList is one strip list's IDs: a keep-mode list's kept IDs, or the list's part of the generated strip table.
func StripTable ¶
func StripTable() []StripIDList
StripTable returns the running core's generated strip table, one entry per list in manifest order. A Binary record keeps it, so a later core can name the built-ins it adds.
func (StripIDList) Field ¶
func (l StripIDList) Field() string
Field names the list as in a Piglet's strip key: tools, commands, extensions, apis or features.
type StripKeep ¶
type StripKeep struct {
Tools *[]string `yaml:"tools,omitempty"`
Commands *[]string `yaml:"commands,omitempty"`
Extensions *[]string `yaml:"extensions,omitempty"`
APIs *[]string `yaml:"apis,omitempty"`
Features *[]string `yaml:"features,omitempty"`
}
StripKeep names the built-ins each keep-mode list keeps. A nil list is in deny mode; an empty list keeps nothing. It has no keep key of its own.
type StripSpec ¶
type StripSpec struct {
Tools []string `yaml:"tools,omitempty"`
Commands []string `yaml:"commands,omitempty"`
Extensions []string `yaml:"extensions,omitempty"`
APIs []string `yaml:"apis,omitempty"`
Features []string `yaml:"features,omitempty"`
Keep *StripKeep `yaml:"keep,omitempty"`
}
StripSpec names the built-ins a Piglet strips. Every entry is a stable ID from the generated strip ID table (strip_ids_generated.go): a built-in tool name, a slash command written with its leading slash, a built-in extension name, a model API, or a feature ID.
Each list is in deny mode (the list names what is stripped) or in keep mode (Keep names what stays; every other ID of that list in the table is stripped, including IDs a later core adds). One list is never in both modes in one Piglet file. Parsing expands keep mode against the running core's table, so a parsed or resolved spec also carries the stripped IDs of a keep-mode list in the deny field, and every consumer reads the deny fields alone.
func (*StripSpec) BuildTags ¶
BuildTags returns the sorted build tags that compile the stripped built-ins out of a Piglet Binary.
func (*StripSpec) HasFeature ¶
HasFeature reports whether the spec names the feature ID. The builder and manifest validation read a Piglet's spec with it; the running process asks pigstrip.Has, which Record fills.
func (*StripSpec) IsEmpty ¶
IsEmpty reports whether the spec strips nothing and keeps no list in keep mode. A nil spec is empty.
func (*StripSpec) KeepLists ¶
func (s *StripSpec) KeepLists() []StripIDList
KeepLists returns each keep-mode list with its kept IDs, in manifest order. A spec without keep mode returns nil.
func (StripSpec) MarshalYAML ¶
MarshalYAML writes the spec as a Piglet file states it: a keep-mode list writes its keep list and not its expansion, so a baked Piglet re-expands against its Binary's own table and parses again.
func (*StripSpec) Record ¶
func (s *StripSpec) Record() (undo func())
Record records every entry of the spec in pigstrip, the process's one strip state, as a Piglet Binary's OFF shims record the built-ins it compiled out. The returned function undoes the records this call added.
func (*StripSpec) StrippedIDs ¶
func (s *StripSpec) StrippedIDs() []StrippedID
StrippedIDs returns every stripped built-in in canonical order: tools, commands, extensions, APIs, then features, each sorted by ID, with the disposition a Piglet Binary gives it.
type StrippedID ¶
StrippedID is one stripped built-in.
func (StrippedID) SlotID ¶
func (id StrippedID) SlotID() string
SlotID names the stripped built-in by its manifest path, the strip list and the ID: tools.grep, commands./share, extensions.mcp, features.themes.
type TreeNode ¶
type TreeNode struct {
Name string `json:"name"`
Version string `json:"version,omitempty"`
Location string `json:"location,omitempty"`
Source string `json:"source,omitempty"`
Installed bool `json:"installed"`
Current bool `json:"current"`
External bool `json:"external,omitempty"`
Children []*TreeNode `json:"children"`
}
TreeNode is one Piglet in the extends tree. Installed means a built Piglet Binary is recorded for it; Current means the environment selects it (PIG_PIGLET_NAME or PIG_PIGLET_PATH). External marks a base that is named by an `extends` but is not in the inventory. pig additive (D170): `pig piglet tree` reports the inventory `pig piglet list` reads, arranged by `extends`.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package artifact defines executable Piglet component plans and artifact records.
|
Package artifact defines executable Piglet component plans and artifact records. |
|
internal
|
|
|
genstripids
command
Command genstripids writes internal/pigstrip/ids_generated.go, the table of stable IDs a Piglet strip list may name.
|
Command genstripids writes internal/pigstrip/ids_generated.go, the table of stable IDs a Piglet strip list may name. |
|
Package release verifies and installs signed Piglet Binary releases.
|
Package release verifies and installs signed Piglet Binary releases. |
|
Package signature signs and verifies Piglet Binaries.
|
Package signature signs and verifies Piglet Binaries. |