manifest

Documentation

Overview

Package manifest models txco.package.yaml — a TxCo package's identity, compatibility, op-resolution contract, and advisory metadata — and validates a package tree against it.

The Go struct + Validate are AUTHORITATIVE (the JSON Schema shipped under docs/ is editor-tooling only): the meaningful checks are semantic — does each bundled compute file exist? does every required op appear as an EXTERNAL op:// ref (no colocated compute)? does every rule parse? — and cannot be expressed in JSON Schema.

Index

• Constants
• func Validate(m *Manifest, fsys fs.FS, root string) []error
• type Build
• type BundledOp
• type Compatibility
• type Inlet
• type InstallSpec
• type Manifest
  • func Parse(b []byte) (*Manifest, error)
  • func ParseFile(path string) (*Manifest, error)
• type Metadata
• type Operations
• type PackageSpec
• type RequiredOp
• type RequiredPackage
• type Requires

Constants

const (
	APIVersion = "thanks.computer/v1alpha1"
	Kind       = "Package"
)

APIVersion and Kind are the only accepted header values in v1alpha1. (thanks.computer is the project domain group.)

const FileName = "txco.package.yaml"

FileName is the manifest filename at a package root.

Functions

func Validate

func Validate(m *Manifest, fsys fs.FS, root string) []error

Validate checks a manifest against the package tree rooted at root within fsys (use os.DirFS(pkgRoot) + "." for an on-disk package). It accumulates ALL problems rather than failing fast, mirroring the apply validate-loop's report style, so `txco package validate` can show everything at once.

The semantic core is the op-resolution contract (design §4): every op:// ref is classified as bundled (a colocated <name>.js/.ts sibling exists, exactly as apply's resolveOpRefsColocated decides) or external (none). The manifest must declare each accordingly.

Types

type Build

type Build struct {
	Requires []string `yaml:"requires,omitempty" json:"requires,omitempty"` // advisory toolchain, e.g. "javy >= 1.0"
}

type BundledOp

type BundledOp struct {
	Name string `yaml:"name" json:"name"`
	Path string `yaml:"path" json:"path"`                     // OPS/.../<name>.js — relative to the package root
	Lang string `yaml:"lang,omitempty" json:"lang,omitempty"` // js | ts
}

type Compatibility

type Compatibility struct {
	Txco string `yaml:"txco,omitempty" json:"txco,omitempty"` // semver constraint; advisory in v1
}

type Inlet

type Inlet struct {
	Type               string `yaml:"type" json:"type"`
	SuggestedLocalPart string `yaml:"suggestedLocalPart,omitempty" json:"suggestedLocalPart,omitempty"`
	Description        string `yaml:"description,omitempty" json:"description,omitempty"`
}

type InstallSpec

type InstallSpec struct {
	DefaultMode    string `yaml:"defaultMode,omitempty" json:"defaultMode,omitempty"`       // as-stack | into-stack | vendor-only
	SuggestedStack string `yaml:"suggestedStack,omitempty" json:"suggestedStack,omitempty"` // default for --as
}

type Manifest

type Manifest struct {
	APIVersion    string        `yaml:"apiVersion" json:"apiVersion"`
	Kind          string        `yaml:"kind" json:"kind"`
	Name          string        `yaml:"name" json:"name"`
	Version       string        `yaml:"version" json:"version"`
	Summary       string        `yaml:"summary,omitempty" json:"summary,omitempty"`
	Package       PackageSpec   `yaml:"package,omitempty" json:"package,omitempty"`
	Compatibility Compatibility `yaml:"compatibility,omitempty" json:"compatibility,omitempty"`
	Operations    Operations    `yaml:"operations,omitempty" json:"operations,omitempty"`
	Build         Build         `yaml:"build,omitempty" json:"build,omitempty"`
	Capabilities  []string      `yaml:"capabilities,omitempty" json:"capabilities,omitempty"`
	Inlets        []Inlet       `yaml:"inlets,omitempty" json:"inlets,omitempty"`
	Requires      Requires      `yaml:"requires,omitempty" json:"requires,omitempty"` // reserved (Phase 4)
	Metadata      Metadata      `yaml:"metadata,omitempty" json:"metadata,omitempty"`
}

Manifest is the parsed txco.package.yaml. The manifest carries IDENTITY only (name + version); a package's registry/namespace/publisher are provenance derived from the resolved ref and recorded in the lockfile, so a copied package cannot lie about its origin.

func Parse

func Parse(b []byte) (*Manifest, error)

Parse unmarshals manifest bytes. Shape/syntax errors only; semantic checks are in Validate.

func ParseFile

func ParseFile(path string) (*Manifest, error)

ParseFile reads and parses a manifest from an on-disk path.

type Metadata

type Metadata struct {
	Homepage string `yaml:"homepage,omitempty" json:"homepage,omitempty"`
	Source   string `yaml:"source,omitempty" json:"source,omitempty"`
	License  string `yaml:"license,omitempty" json:"license,omitempty"`
}

type Operations

type Operations struct {
	Bundled  []BundledOp  `yaml:"bundled,omitempty" json:"bundled,omitempty"`
	Required []RequiredOp `yaml:"required,omitempty" json:"required,omitempty"`
}

Operations is the load-bearing op-resolution contract: which op:// refs ride along as colocated computes (bundled) vs which are external endpoints the installer must wire into txco.yaml (required).

type PackageSpec

type PackageSpec struct {
	Kind    string      `yaml:"kind,omitempty" json:"kind,omitempty"` // department | stack-template | op-pack
	Install InstallSpec `yaml:"install,omitempty" json:"install,omitempty"`
}

type RequiredOp

type RequiredOp struct {
	Name        string `yaml:"name" json:"name"`
	Kind        string `yaml:"kind,omitempty" json:"kind,omitempty"` // http | mcp (advisory)
	Description string `yaml:"description,omitempty" json:"description,omitempty"`
	Example     string `yaml:"example,omitempty" json:"example,omitempty"`
}

type RequiredPackage

type RequiredPackage struct {
	Ref  string `yaml:"ref" json:"ref"`
	Mode string `yaml:"mode,omitempty" json:"mode,omitempty"`
}

type Requires

type Requires struct {
	Packages []RequiredPackage `yaml:"packages,omitempty" json:"packages,omitempty"`
}