packs

Documentation

Overview

Package packs implements pack discovery, loading, and the in-memory registry the engine consults at execution time.

Pack discovery:

• A configured path that contains pack.yaml is treated as a single pack.
• Otherwise the path is treated as a parent directory; every immediate child that contains a pack.yaml is loaded.

All references inside a pack (action paths, script paths) are resolved relative to the pack root and must remain inside it. Duplicate action IDs (within or across packs) abort the load — fail closed.

Index

• func Fetch(ctx context.Context, srcURL string, client *http.Client) (dir string, cleanup func(), err error)
• type DegradedPack
• type LoadOptions
• type PackFile
• type Registry
  • func LoadAll(dirs []string, opts LoadOptions) (*Registry, error)
  • func LoadOne(root string, opts LoadOptions) (*Registry, error)
  • func (r *Registry) Action(id string) (*actionspec.Action, bool)
  • func (r *Registry) Actions() []*actionspec.Action
  • func (r *Registry) Degraded() []DegradedPack
  • func (r *Registry) OutputSchema(actionID string) (*outputschema.Validator, bool)
  • func (r *Registry) Pack(id string) (*packspec.Pack, bool)
  • func (r *Registry) PackFiles(packID string) ([]PackFile, error)
  • func (r *Registry) PackHash(packID string) (string, bool)
  • func (r *Registry) Packs() []*packspec.Pack
  • func (r *Registry) RecomputePackHash(packID string) (string, error)
  • func (r *Registry) ScriptInfo(actionID string) (ScriptInfo, bool)
• type ScriptInfo

Functions

func Fetch

func Fetch(ctx context.Context, srcURL string, client *http.Client) (dir string, cleanup func(), err error)

Fetch downloads a gzip-compressed tarball of a pack from srcURL and extracts it into a fresh temp directory. The returned dir contains the pack's files at its root (pack.yaml, actions/…) ready for LoadOne. The caller MUST invoke cleanup when done to remove the temp tree.

The HTTP transport and timeout are the caller's; redirect security is always enforced. A nil client defaults to a 30s timeout.

Types

type DegradedPack

type DegradedPack struct {
	Dir    string
	Reason string
}

DegradedPack is a pack directory a SkipBrokenPacks load skipped because it failed to parse, hash, or validate — recorded so the daemon, doctor, and operators can see exactly what is broken instead of silently serving less.

type LoadOptions

type LoadOptions struct {
	// Logger is the structured logger used for load-time events
	// (duplicate IDs, etc.). Defaults to slog.Default.
	Logger *slog.Logger

	// SkipBrokenPacks records a pack directory that fails to load as degraded
	// (Registry.Degraded) and keeps loading the rest, instead of failing the
	// whole load. The connect daemon and doctor set it: one unparseable
	// installed pack must degrade that pack, not crash-loop the runner and
	// take every healthy pack's incident-response surface down with it.
	// Publisher and install-verification paths keep the default fail-fast —
	// a broken pack must never silently vanish from a published catalog.
	SkipBrokenPacks bool
}

LoadOptions controls loader behaviour. The zero value works for the common case.

type PackFile

type PackFile struct {
	Rel  string
	Data []byte
}

PackFile is one file that contributes to a pack's content hash — its pack-relative path and current on-disk bytes.

type Registry

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

Registry is the in-memory index of loaded packs and actions.

func LoadAll

func LoadAll(dirs []string, opts LoadOptions) (*Registry, error)

LoadAll discovers and loads packs from each path in dirs. The runner fails closed if any pack is invalid.

func LoadOne

func LoadOne(root string, opts LoadOptions) (*Registry, error)

LoadOne loads a single pack at root (which must contain pack.yaml). Used by `emisar pack validate`.

func (*Registry) Action

func (r *Registry) Action(id string) (*actionspec.Action, bool)

Action returns an action by id.

func (*Registry) Actions

func (r *Registry) Actions() []*actionspec.Action

Actions returns all actions sorted by id.

func (*Registry) Degraded

func (r *Registry) Degraded() []DegradedPack

Degraded returns the pack directories a SkipBrokenPacks load skipped, in load order.

func (*Registry) OutputSchema

func (r *Registry) OutputSchema(actionID string) (*outputschema.Validator, bool)

OutputSchema returns the compiled typed-result contract for an action.

func (*Registry) Pack

func (r *Registry) Pack(id string) (*packspec.Pack, bool)

Pack returns a pack by id.

func (*Registry) PackFiles

func (r *Registry) PackFiles(packID string) ([]PackFile, error)

PackFiles returns exactly the files that form packID's content hash (pack.yaml + its referenced action YAMLs + referenced scripts), read fresh from disk. The published tarball is built from THIS set, never a directory walk, so no unreferenced file (a stray README, a .DS_Store, an editor backup) ever ships inside the content-addressed artifact outside what the hash covers.

func (*Registry) PackHash

func (r *Registry) PackHash(packID string) (string, bool)

PackHash returns the content-addressable hash for a pack id, cached from load time (or the most recent SIGHUP reload).

func (*Registry) Packs

func (r *Registry) Packs() []*packspec.Pack

Packs returns all packs sorted by id.

func (*Registry) RecomputePackHash

func (r *Registry) RecomputePackHash(packID string) (string, error)

RecomputePackHash re-reads the pack's files fresh from disk and returns the hash for the current bytes. Same algorithm as the load- time hash. Used by the dispatch path to detect post-load tampering (the cached `PackHash` was computed when the pack was last loaded / SIGHUP'd; this asks "what's the hash *right now*?"). The set of relpaths the rehash walks is the same set we computed at load time; added files between then and now don't change the hash, but that's the same boundary the cloud's trust pin is drawn against.

func (*Registry) ScriptInfo

func (r *Registry) ScriptInfo(actionID string) (ScriptInfo, bool)

ScriptInfo returns the cached script info for a script-kind action.

type ScriptInfo

type ScriptInfo struct {
	Path   string
	SHA256 string
}

ScriptInfo is the cached metadata for a script-kind action's payload.