templates

Documentation

Overview

Package templates provides Go scaffolding for loading the YAML-based workflow template system that mirrors the TS implementation in packages/core/src/templates/ of the legacy agentfactory repo.

Current state (Phase H): stub loader only. Full Handlebars rendering, partial support, TemplateContext, and ToolPermissionAdapter are deferred to H+1 … H+4 follow-up lanes. See docs/templates-port-audit.md for the porting plan.

Index

• Variables
• type Kind
• type Metadata
• type Registry
  • func New() (*Registry, error)
  • func NewFromFS(fsys fs.FS, root string) (*Registry, error)
  • func (r *Registry) Has(name string) bool
  • func (r *Registry) Names() []string
  • func (r *Registry) Render(name string, ctx interface{}) (string, error)
• type Template
  • func Load(path string) (Template, error)
• type ToolPermission
  • func (t *ToolPermission) UnmarshalYAML(value *yaml.Node) error
• type ToolsBlock

Variables

var ErrTemplateNotFound = fmt.Errorf("template not found")

ErrTemplateNotFound is returned by Render when the requested template name is not present in the Registry.

Types

type Kind

type Kind string

Kind discriminates the two top-level YAML document types in the template system. The TS side uses string literals; Go uses a typed constant for exhaustive switch safety.

const (
	KindWorkflowTemplate Kind = "WorkflowTemplate"
	KindPartialTemplate  Kind = "PartialTemplate"
)

Kind values for the template envelope.

type Metadata

type Metadata struct {
	Name        string `yaml:"name"`
	Description string `yaml:"description,omitempty"`
	// WorkType is present on WorkflowTemplate metadata.
	WorkType string `yaml:"workType,omitempty"`
	// Frontend is present on PartialTemplate metadata; when set the
	// partial is frontend-specific (e.g., "linear").
	Frontend string `yaml:"frontend,omitempty"`
}

Metadata is the metadata block shared by both template kinds.

type Registry

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

Registry holds a set of parsed and raymond-compiled templates, indexed by their metadata.name value. It is safe for concurrent use after construction — all mutation happens inside New/NewFromFS, which are single-threaded by design.

Phase H+1 coverage:

• WorkflowTemplate YAML loading + raymond compilation
• eq / neq / hasFlag helper registration
• Render(name, ctx) producing rendered strings

Partial template support ({{> partial-name}}) is deferred to H+2.

func New

func New() (*Registry, error)

New constructs a Registry pre-loaded with the built-in YAML templates embedded in this package (*.yaml files in the templates/ directory).

func NewFromFS

func NewFromFS(fsys fs.FS, root string) (*Registry, error)

NewFromFS constructs a Registry by walking fsys rooted at root and loading every *.yaml file found. Files that fail to parse or validate are returned as errors immediately — partial load is not supported.

func (*Registry) Has

func (r *Registry) Has(name string) bool

Has returns true when a template with the given name is registered.

func (*Registry) Names

func (r *Registry) Names() []string

Names returns the sorted list of registered template names. Primarily useful in tests and debugging.

func (*Registry) Render

func (r *Registry) Render(name string, ctx interface{}) (string, error)

Render executes the named template against ctx and returns the rendered string. ctx must be a map[string]interface{} or a struct whose exported fields raymond can reflect on.

Returns ErrTemplateNotFound when name is not present in the registry.

type Template

type Template struct {
	APIVersion string `yaml:"apiVersion"`
	Kind       Kind   `yaml:"kind"`
	Metadata   Metadata

	// Prompt is populated for WorkflowTemplate documents.
	Prompt string `yaml:"prompt,omitempty"`
	// Content is populated for PartialTemplate documents.
	Content string `yaml:"content,omitempty"`
	// Tools is populated for WorkflowTemplate documents.
	Tools *ToolsBlock `yaml:"tools,omitempty"`
}

Template is the unified Go representation of a parsed YAML template document. Both WorkflowTemplate and PartialTemplate decode into this struct; the Kind field discriminates them.

Phase H only populates the frontmatter fields (apiVersion, kind, metadata, tools). The prompt/content string is kept as a raw string pending the raymond Handlebars integration in H+1.

func Load

func Load(path string) (Template, error)

Load reads the YAML file at path, parses it into a Template, and validates the frontmatter. It returns a non-nil error when the file cannot be read, is malformed YAML, or fails basic schema validation.

Load is the single entry point for the templates package in Phase H. Rendering (Handlebars) and registry management are deferred to H+1.

type ToolPermission

type ToolPermission struct {
	// Shell is set when the YAML entry is { shell: "pnpm *" }.
	Shell string `yaml:"shell,omitempty"`
	// Raw is set when the YAML entry is a plain string, e.g. "user-input".
	Raw string `yaml:"-"`
}

ToolPermission is the provider-agnostic permission value that lives inside a template's tools.allow / tools.disallow list.

The TS union type is:

type ToolPermission = { shell: string } | "user-input" | string

In YAML the value is either a plain string (e.g. "user-input") or a mapping with a single "shell" key. We decode both into this struct: when Shell is empty the raw string is stored in Raw.

func (*ToolPermission) UnmarshalYAML

func (t *ToolPermission) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML decodes a ToolPermission from either a plain scalar string or a { shell: "…" } mapping.

type ToolsBlock

type ToolsBlock struct {
	Allow    []ToolPermission `yaml:"allow,omitempty"`
	Disallow []ToolPermission `yaml:"disallow,omitempty"`
}

ToolsBlock is the optional tools section of a WorkflowTemplate.