profile

package
v0.0.21 Latest Latest
Warning

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

 Go to latest Published: Sep 14, 2026 License: MPL-2.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ReadmeProfilesBegin = "<!-- BEGIN tpd profiles -->"
	ReadmeProfilesEnd   = "<!-- END tpd profiles -->"
)

README markers delimiting the built-in profiles table. The generator replaces only the rows between them, leaving surrounding prose untouched.

Variables

This section is empty.

Functions

func CatalogDoc added in v0.0.8 

func CatalogDoc() (string, error)

CatalogDoc renders docs/catalog.md: every built-in profile and fragment as a heading with its meta description and its full source in a <details> spoiler, fragments grouped by their top-level folder. A contents list anchors the group and fragment headings for navigation.

func DefaultFragmentDir 

func DefaultFragmentDir() string

DefaultFragmentDir returns the default user fragment directory, a sibling of DefaultProfileDir under the tpd config root.

func DefaultProfileDir 

func DefaultProfileDir() string

DefaultProfileDir returns the default user profile directory for the current OS. Honors XDG_CONFIG_HOME on Linux via os.UserConfigDir. Used by the CLI when --profile-dir is not set.

func LoadFragments 

func LoadFragments(fsys fs.ReadFileFS, root string) (map[string]RawProfile, error)

LoadFragments loads YAML fragment files from an embedded filesystem (e.g. catalog.Fragments) and returns them keyed by fragment name. Each file must be a bare profile fragment (caches/mounts/tools/labels/env), optionally extending other fragments, without image/build/command/version — validateFragmentName enforces this.

func ParseMemoryBytes 

func ParseMemoryBytes(s string) (int64, error)

ParseMemoryBytes converts a Docker-style memory string to bytes using docker/go-units, the same parser Docker's --memory uses. Rejects empty and unparseable values.

func ParseNanoCPUs 

func ParseNanoCPUs(s string) (int64, error)

ParseNanoCPUs converts a CPU-count string ("2", "1.5") to nanos, matching Docker's --cpus semantics. Rejects NaN, infinities, values <= 0, and values that would overflow int64 after scaling (a fractional count above ~9.2e9).

func PatchReadme added in v0.0.8 

func PatchReadme(data []byte, rows string) ([]byte, error)

PatchReadme replaces the profiles table between the README markers with rows (the full table including the header), returning the patched content.

func ProfileNameFromPath 

func ProfileNameFromPath(path string) string

func ProfilesTable added in v0.0.8 

func ProfilesTable() (string, error)

ProfilesTable renders the README built-in profiles table (header + rows, profiles only, sorted by display name) from the embedded catalog.

func ValidateName 

func ValidateName(name string) error

ValidateName checks a user-supplied profile name for the init flow. It rejects empty names, names unsafe for use as a file path (an invalid segment, ".."), a reserved-namespace first segment, and single-segment names reserved for subcommands. Fragment collisions are checked separately by the caller against the catalog.

Types

type CachePaths 

type CachePaths []string

CachePaths is the set of container paths a single cache volume backs. A scalar ("caches: {foo: ~/.foo}") and a list both decode; a single path marshals back as a scalar so single-path caches read naturally in show.

func (CachePaths) MarshalYAML 

func (c CachePaths) MarshalYAML() (interface{}, error)

func (*CachePaths) UnmarshalYAML 

func (c *CachePaths) UnmarshalYAML(value *yaml.Node) error

type Catalog 

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

Catalog is the merged set of built-in + user raw profiles and fragments, keyed by FullName (canonical "ns/name").

func LoadCatalog added in v0.0.7 

func LoadCatalog(pfs, ffs fs.ReadFileFS, userDir string) (Catalog, error)

LoadCatalog loads a catalog from explicit built-in sources plus a user profile directory, mirroring LoadProfiles with the built-in filesystems injected. Intended for loading stable test fixtures; production code uses LoadProfiles.

func LoadLocal added in v0.0.21 

func LoadLocal(rootPath string) (Catalog, string, error)

LoadLocal loads rootPath and its extends closure into a side catalog containing only local/* entries, and returns the catalog plus the root entry's qualified FullName. Extends targets resolve inside the root file's directory (subdirs fine, never above); user/core entries are structurally absent, so no local file can reach one.

func LoadProfiles 

func LoadProfiles(userDir string) (Catalog, error)

LoadProfiles loads embedded built-ins, then user profiles from userDir (if non-empty), with user entries shadowing built-ins of the same name.

func LoadProfilesTolerant 

func LoadProfilesTolerant(userDir string, warn func(string)) (Catalog, error)

LoadProfilesTolerant is like LoadProfiles but skips a malformed user profile/fragment file (logging it via warn) instead of aborting the whole load. Built-ins always load strictly. Used by `tpd prune`, where one broken user file must not prevent computing liveness for the rest — a strict abort there is a regression from the old prune (which never read profiles) and risks pruning live resources. Also used by shell completion (cmd/tpd/completion.go) so a malformed user file never breaks tab completion.

func NewProfileCatalogForTest 

func NewProfileCatalogForTest(entries map[string]RawProfile) Catalog

NewProfileCatalogForTest creates a Catalog from a raw map, stamping every entry as a core-namespace built-in. For test use only; production code uses LoadProfiles.

func (*Catalog) AddRaw 

func (c *Catalog) AddRaw(ns, name string, rc RawProfile)

AddRaw inserts a raw profile into the catalog under its FullName, shadowing any existing entry of the same name. Used by init to overlay generated content for validation.

func (Catalog) Clone added in v0.0.8 

func (c Catalog) Clone() Catalog

Clone returns a copy of the catalog with independent entry/fragment maps, so callers can overlay generated content (AddRaw) without mutating the original.

func (Catalog) Description added in v0.0.8 

func (c Catalog) Description(displayName string) string

Description returns the meta description of the entry backing a display name. A user entry shadows a core entry of the same name, so its description wins; an entry without meta yields "".

func (Catalog) DisplayNames 

func (c Catalog) DisplayNames() []string

DisplayNames returns the set of unqualified display names, deduplicated across namespaces. A user entry shadows a core entry of the same display name (user wins, shown once). Core-only entries show as the bare name.

func (Catalog) FragmentByDisplayName 

func (c Catalog) FragmentByDisplayName(name string) (string, bool)

FragmentByDisplayName resolves a fragment display name to its canonical FullName. A user fragment wins over a core fragment of the same name.

func (Catalog) FragmentDisplayNames added in v0.0.7 

func (c Catalog) FragmentDisplayNames() []string

FragmentDisplayNames is DisplayNames filtered to fragments only.

func (Catalog) Get 

func (c Catalog) Get(name string) (RawProfile, bool)

func (Catalog) IsFragment 

func (c Catalog) IsFragment(name string) bool

func (Catalog) Names 

func (c Catalog) Names() []string

func (Catalog) Namespaces 

func (c Catalog) Namespaces() map[string]bool

Namespaces returns the registered namespace set (for CLI ref parsing).

func (Catalog) ParseRefForCatalog 

func (c Catalog) ParseRefForCatalog(s string) (Ref, error)

ParseRefForCatalog parses s against the catalog's registered namespaces.

func (Catalog) ProfileDisplayNames 

func (c Catalog) ProfileDisplayNames() []string

ProfileDisplayNames is DisplayNames filtered to non-fragments.

func (Catalog) ProfileNames 

func (c Catalog) ProfileNames() []string

func (Catalog) ResolveRef 

func (c Catalog) ResolveRef(ref Ref) (string, bool)

ResolveRef resolves a Ref to a canonical catalog FullName (an entries key). For unqualified names (ref.Namespace == ""), returns the user key (bare name) if present, else the core key ("core/"+name). For qualified names, returns the qualified key directly (no fallback). Returns ok=false if no entry matches.

func (Catalog) Source 

func (c Catalog) Source(displayName string) string

Source reports the provenance of a display name: "user" (user-only), "core" (core-only), or "user shadow" (user entry shadowing a core entry).

type ChainEntry added in v0.0.8 

type ChainEntry struct {
	FullName    string
	DisplayName string
	Path        string
	Extends     []string
}

ChainEntry is one catalog entry in a resolved profile's extends chain, in pre-order, deduped. Extends is the entry's own declared extends as written. Rendered by tpd show --provenance.

type Contributor added in v0.0.7 

type Contributor struct {
	FullName  string
	Namespace string
}

Contributor identifies a catalog entry that contributed a value. Stored in provenance so the approval filter can decide trust without access to the catalog: a user entry (Namespace == "") is trusted and not gated; a core or remote-namespace entry is gated.

func (Contributor) Trusted added in v0.0.7 

func (c Contributor) Trusted() bool

Trusted reports whether this contributor is user-owned and therefore not subject to the approval gate.

type DbusConfig 

type DbusConfig struct {
	Talk map[string]*struct{} `yaml:"talk,omitempty"`
	Own  map[string]*struct{} `yaml:"own,omitempty"`
}

DbusConfig is a flatpak-style session-bus allowlist. Talk names may be called; Own names may be acquired. Each name maps to an empty object; a null value drops an inherited name (the pointer distinguishes allow from remove). Values are maps (not lists) so profiles extending a base merge their names key-by-key.

type DbusProvenance added in v0.0.7 

type DbusProvenance struct {
	Talk map[string]Contributor
	Own  map[string]Contributor
}

type DeviceBind 

type DeviceBind struct {
	Source      string `yaml:"source,omitempty"`
	Permissions string `yaml:"permissions,omitempty"`
	Cgroup      bool   `yaml:"cgroup,omitempty"`
}

type ExitCoder 

type ExitCoder interface {
	Error() string
	ExitCode() int
}

type ExtendsList 

type ExtendsList struct {
	Raw      []string `yaml:"-"`
	Resolved []Ref    `yaml:"-"`
}

ExtendsList is the yaml-decoded extends field. Raw holds the strings as written; Resolved is filled by Resolve splitting each Raw string against the registered namespaces. MarshalYAML emits Resolved (canonical strings) when available, else Raw (for round-tripping un-resolved lists).

func (ExtendsList) MarshalYAML 

func (e ExtendsList) MarshalYAML() (interface{}, error)

MarshalYAML emits Resolved (if non-empty) as canonical strings, else Raw.

func (*ExtendsList) Resolve 

func (e *ExtendsList) Resolve(namespaces map[string]bool) error

Resolve splits each Raw string against the registered namespaces into Resolved. Idempotent. A string matching a registered namespace prefix at a segment boundary splits into (namespace, remainder); a slash string matching no prefix is kept as an unqualified hierarchical name. An empty local name is an error.

func (*ExtendsList) UnmarshalYAML 

func (e *ExtendsList) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML decodes a scalar or list of strings into Raw. No namespace splitting happens here (yaml.v3 gives no context). Resolved stays nil.

type File 

type File struct {
	Content string `yaml:"content"`
	Mode    uint32 `yaml:"mode,omitempty"`
}

File is a single file written into the container at launch, keyed by its target path. Content is embedded inline and rendered as a {{ }} template; Mode is the raw permission bits (default 0644).

type Meta added in v0.0.8 

type Meta struct {
	Description string   `yaml:"description,omitempty"`
	Tags        []string `yaml:"tags,omitempty"`
}

Meta describes a catalog entry itself — never inherited through extends. The leaf entry's own meta is stamped onto a resolved profile; a child that declares none has none. Tags are stored for future consumers; nothing renders them yet.

type Mount 

type Mount struct {
	Source   string `yaml:"source,omitempty"`
	Service  string `yaml:"service,omitempty"`
	Socket   string `yaml:"socket,omitempty"`
	ReadOnly bool   `yaml:"read_only,omitempty"`
	Create   bool   `yaml:"create,omitempty"` // mkdir the source if missing (directories only)
}

func (Mount) MarshalYAML 

func (m Mount) MarshalYAML() (interface{}, error)

MarshalYAML omits read_only when it equals the per-kind default, keeping only explicit overrides.

func (*Mount) UnmarshalYAML 

func (m *Mount) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML defaults read_only to true for bind mounts and false for service-socket mounts, so a mount without an explicit read_only key gets the kind-appropriate default.

type PortBind 

type PortBind struct {
	Host     string `yaml:"host,omitempty"`
	HostIP   string `yaml:"host_ip,omitempty"`
	Protocol string `yaml:"protocol,omitempty"`
}

PortBind publishes a container port to the host. Empty Host means the host port is auto-allocated at launch.

type Profile 

type Profile struct {
	Version     int                   `yaml:"version"`
	ExtendsList ExtendsList           `yaml:"extends,omitempty"`
	Image       string                `yaml:"image,omitempty"`
	Packages    []string              `yaml:"packages,omitempty"`
	Repos       map[string]Repo       `yaml:"repos,omitempty"`
	Files       map[string]File       `yaml:"files,omitempty"`
	Command     []string              `yaml:"command,omitempty"`
	Caches      map[string]CachePaths `yaml:"caches,omitempty"`
	Mounts      map[string]Mount      `yaml:"mounts,omitempty"`
	Env         map[string]string     `yaml:"environment,omitempty"`
	Labels      map[string]string     `yaml:"labels,omitempty"`
	Network     string                `yaml:"network,omitempty"`
	Resources   *Resources            `yaml:"resources,omitempty"`
	TTY         string                `yaml:"tty,omitempty"`
	Tools       map[string]Tool       `yaml:"tools,omitempty"`
	Ports       map[string]PortBind   `yaml:"ports,omitempty"`
	Devices     map[string]DeviceBind `yaml:"devices,omitempty"`
	Dbus        *DbusConfig           `yaml:"dbus,omitempty"`
	Services    map[string]Service    `yaml:"services,omitempty"`
	Meta        *Meta                 `yaml:"meta,omitempty"`
}

Profile is a resolved tpd profile (after extends-merge and validation). YAML tags match the schema in the design doc §4.1.

func ResolveFragment 

func ResolveFragment(cat Catalog, name string) (Profile, error)

ResolveFragment resolves a fragment's extends chain into a merged Profile without the profile-only validation. Fragments are composition-only and carry no image/command, which ResolveProfile requires; resolving them is still useful for showing the effective merged view (e.g. edit seeds).

func ResolveProfile 

func ResolveProfile(cat Catalog, name string) (Profile, error)

Resolve walks the extends chain for name and produces a fully merged Profile. Cycles are detected and rejected. Validation runs on the result.

func ResolveTildes 

func ResolveTildes(cfg Profile, mode workspace.Mode, hostHome, runtimeHome string, ports map[string]string) (Profile, error)

ResolveTildes expands leading ~/ on mount sources (→ hostHome) and mount/cache targets (→ runtimeHome) per spec §5.6, then renders {{ }} text/template expressions against the host environment. Files targets expand ~ (→ runtimeHome) too, and each File.Content is rendered as a template. Absolute paths are left as-is. ModeUnknown (dry-run without a daemon) keeps ~ targets literal rather than claiming a home; the caller otherwise determines runtimeHome based on the mode.

type ProfileError 

type ProfileError struct {
	Path    string
	Line    int
	Message string
}

ProfileError is a profile-layer error (parse, merge, validation) carrying the source file path and line for reporting (spec §10: exit code 2).

func (ProfileError) Error 

func (e ProfileError) Error() string

func (ProfileError) ExitCode 

func (e ProfileError) ExitCode() int

type Provenance added in v0.0.7 

type Provenance struct {
	Mounts    map[string]Contributor
	Devices   map[string]Contributor
	Env       map[string]Contributor
	Ports     map[string]Contributor
	Dbus      DbusProvenance
	Network   Contributor
	Services  map[string]Contributor
	Tools     map[string]Contributor
	Caches    map[string]Contributor
	Repos     map[string]Contributor
	Files     map[string]Contributor
	Labels    map[string]Contributor
	Packages  map[string]Contributor
	Resources ResourcesProvenance
	Image     Contributor
	Command   Contributor
	TTY       Contributor
}

Provenance records, for each declared key, the Contributor that last wrote it. Keys whose final value came from a user entry are not gated; keys from a core/remote entry are.

type RawProfile 

type RawProfile struct {
	Profile
	Namespace  string                     `yaml:"-"` // source identity, stamped by loaders
	Name       string                     `yaml:"-"` // path relative to the profiles/fragments root minus .yaml (may contain /)
	Path       string                     `yaml:"-"` // file path for error reporting
	NullKeys   map[string]map[string]bool `yaml:"-"` // field → set of keys that are explicitly null (delete-on-inherit)
	Provenance Provenance                 `yaml:"-"`
}

RawProfile is a profile as loaded from disk, before extends-merge. It carries its source identity (Namespace + Name) and file path. Namespace is "core" for embedded built-ins, "" for user files, or a future remote namespace ("github.com/user/project"). Name is the path relative to the profiles/fragments root minus .yaml (may contain /). FullName is the canonical catalog key; DisplayName is the unqualified name used in user-facing output.

func MergeProfiles 

func MergeProfiles(parent, child RawProfile) RawProfile

scalars replace, maps merge key-by-key with null-to-delete, lists replace.

func ParseRaw 

func ParseRaw(data []byte, path string) (RawProfile, error)

func (RawProfile) DisplayName 

func (rc RawProfile) DisplayName() string

DisplayName is the unqualified name used in user-facing output (list, wizard).

func (RawProfile) FullName 

func (rc RawProfile) FullName() string

FullName is the canonical catalog key and the qualified YAML/string form.

type Ref 

type Ref struct {
	Namespace string
	Name      string
}

Ref is a parsed-but-not-yet-resolved reference to a profile or fragment. Namespace == "" means unqualified (resolve via user-first-then-core fallback); any other value ("core", a future remote namespace) means qualified (direct lookup, no fallback).

func ParseRef 

func ParseRef(s string, namespaces map[string]bool) (Ref, error)

ParseRef splits a reference string against the registered namespaces into a Ref. A string with no "/" is unqualified (Ref{Namespace: "", Name: s}). A string with "/" is matched against the longest registered namespace prefix at a segment boundary (ns + "/"); the remainder is the local name and may itself be multi-segment (toolchain/go). A slash string matching no registered prefix is an unqualified hierarchical name (user namespaces like toolchain/go parse this way), not an error. An empty local name ("core/") is rejected.

func (Ref) FullName 

func (r Ref) FullName() string

FullName returns the canonical string form: "ns/name", or the bare name when Namespace is "".

type Repo 

type Repo struct {
	ExtRepo    string `yaml:"extrepo,omitempty"`
	URL        string `yaml:"url,omitempty"`
	KeyURL     string `yaml:"key_url,omitempty"`
	Suites     string `yaml:"suites,omitempty"`
	Components string `yaml:"components,omitempty"`
}

Repo is a single extra apt source, keyed by its merge identity (a logical repo name). Either ExtRepo (an extrepo catalog name) or a fully inline custom repo (URL/KeyURL/Suites/Components) must be set.

type Resolved added in v0.0.7 

type Resolved struct {
	Profile
	Prov        Provenance
	FullName    string
	DisplayName string
	Chain       []ChainEntry
}

Resolved is a fully merged profile plus per-field provenance attribution for every merged field and the catalog identity of the resolved entry. Returned by ResolveProfileWithProv. ResolveProfile is a thin wrapper that discards provenance for callers that don't gate (tpd show --resolved discards it).

func ResolveFragmentWithProv added in v0.0.7 

func ResolveFragmentWithProv(cat Catalog, name string) (Resolved, error)

ResolveFragmentWithProv is the fragment analogue of ResolveProfileWithProv.

func ResolveProfileWithProv added in v0.0.7 

func ResolveProfileWithProv(cat Catalog, name string) (Resolved, error)

ResolveProfileWithProv resolves name into a fully merged Profile with provenance and catalog identity. The FullName is the resolved catalog key (e.g. "core/opencode"); DisplayName is the unqualified name for human-facing output.

func (Resolved) ProvenanceYAML added in v0.0.8 

func (r Resolved) ProvenanceYAML() (string, error)

ProvenanceYAML renders the resolved profile as one section per chain entry, in chain (pre-)order. Each section shows the entry's own declared extends plus only the keys it owns in the final merge. Sections are diagnostic output, not a single parseable YAML document. yaml.v3 sorts map keys, so key order within a section is deterministic.

type Resources 

type Resources struct {
	Memory string `yaml:"memory,omitempty"`
	CPUs   string `yaml:"cpus,omitempty"`
}

Resources are optional resource hints (best-effort; runtime may ignore).

type ResourcesProvenance added in v0.0.8 

type ResourcesProvenance struct {
	Memory Contributor
	CPUs   Contributor
}

type Service added in v0.0.7 

type Service struct {
	Image       string                `yaml:"image,omitempty"`
	Packages    []string              `yaml:"packages,omitempty"`
	Repos       map[string]Repo       `yaml:"repos,omitempty"`
	Files       map[string]File       `yaml:"files,omitempty"`
	Command     []string              `yaml:"command,omitempty"`
	Caches      map[string]CachePaths `yaml:"caches,omitempty"`
	Mounts      map[string]Mount      `yaml:"mounts,omitempty"`
	Env         map[string]string     `yaml:"environment,omitempty"`
	Labels      map[string]string     `yaml:"labels,omitempty"`
	Exposes     map[string]string     `yaml:"exposes,omitempty"`
	Privileged  bool                  `yaml:"privileged,omitempty"`
	Version     int                   `yaml:"version,omitempty"`
	ExtendsList ExtendsList           `yaml:"extends,omitempty"`
	Network     string                `yaml:"network,omitempty"`
	TTY         string                `yaml:"tty,omitempty"`
	Resources   *Resources            `yaml:"resources,omitempty"`
	Tools       map[string]Tool       `yaml:"tools,omitempty"`
	Dbus        *DbusConfig           `yaml:"dbus,omitempty"`
	Ports       map[string]PortBind   `yaml:"ports,omitempty"`
	Devices     map[string]DeviceBind `yaml:"devices,omitempty"`
	Services    map[string]Service    `yaml:"services,omitempty"`
	Hash        string                `yaml:"-"`
}

Service is a companion container started alongside the launch container.

type Tool 

type Tool struct {
	Version      string
	SHA256       string
	SHA256ByArch map[string]string
}

Tool is a single mise tool: the version plus optional verification metadata. SHA256 is a universal asset digest; SHA256ByArch keys are the schema's arch set ("amd64", "aarch64"), which the appimage backend maps its RUNTIME.archType to. Decodes from a YAML scalar (the version) or a map ({version, sha256}).

func (Tool) MarshalYAML 

func (t Tool) MarshalYAML() (interface{}, error)

func (*Tool) UnmarshalYAML 

func (t *Tool) UnmarshalYAML(node *yaml.Node) error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.