Documentation
¶
Overview ¶
Package hcl provides an HCL → YAML converter for docker-agent configuration files. The HCL surface mirrors the YAML schema with a few conventions:
- Top-level keyed maps (agents, models, providers, mcps, rag) are written as labeled blocks, e.g. `agent "root" { ... }` becomes `agents: { root: { ... } }`.
- Inside an agent, `command "name" { ... }` becomes `commands: { name: { ... } }`.
- Toolsets use the label as the `type` field: `toolset "mcp" { ... }` becomes `toolsets: [{ type: mcp, ... }]`. At the top level, `toolsets "name" { ... }` instead defines a reusable, named toolset under `toolsets: { name: { ... } }`.
- Multi-line strings should use heredocs. Because HCL templates expand `${...}` interpolation, any literal `${...}` (such as `${shell({cmd: "..."})}`) must be escaped as `$${...}`.
- The custom `file("path")` function reads a UTF-8 text file and returns its contents as a string. An optional second argument renders the file as an HCL template, e.g. `file("prompt.md", { name = "Ada" })` expands `${name}` inside the file. Relative paths are resolved from the HCL config file's directory.
The converter does not validate the resulting document against the configuration schema; that is left to the existing YAML/JSON loader.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsHCLSource ¶ added in v1.132.0
IsHCLSource reports whether a source named name holding data should be parsed as HCL: the .hcl extension wins, otherwise the content is sniffed.
func LabelKeyedMapOutKeys ¶
LabelKeyedMapOutKeys returns the set of YAML keys produced by HCL block rules that map a labeled block into a label-keyed map (e.g. agent "x" {} becomes agents.x). It is exported so tests can verify the HCL conventions stay in sync with top-level keyed maps in the JSON schema.
func LooksLikeHCL ¶
LooksLikeHCL reports whether the given bytes look like an HCL document rather than a YAML one. The detection is heuristic and is intended for callers that do not have a filename hint to rely on (for example, OCI artifacts). It looks for top-level labeled blocks of the docker-agent HCL schema, e.g. `agent "..." {`, which are not valid YAML.
Types ¶
type Source ¶ added in v1.132.0
type Source interface {
Name() string
ParentDir() string
Read(ctx context.Context) ([]byte, error)
}
Source mirrors config.Source so this package can decorate agent sources without importing pkg/config.
func NewSource ¶ added in v1.132.0
NewSource decorates an agent source so HCL documents are transparently converted to YAML on read. Detection uses the source name's .hcl extension or, when that is absent (OCI artifacts, URLs), the content itself; anything else passes through untouched. config.Load only understands YAML, so wrap sources that may carry HCL before loading them.
Source Files