Template packs
A template pack is a tamias package with type: template whose tamias.yaml carries a template: table. The port lives in scarab-template (pure domain — no I/O, no engine specifics); impls own the syntax.
Manifest schema
name: repo-bootstrap
type: template
version: "0.1.0"
template:
vars: # optional — flat name → JSON value map
env: dev
replicas: 1
extends: git:9aia/base//libraries/base-pack # optional — parent pack ref
files: # required, non-empty
- src: app.toml.tmpl # path inside the pack payload
into: ./config/app.toml # render target, relative to target dirtemplate.vars
BTreeMap<String, serde_json::Value> — defaults layer, lowest precedence. Values may be strings, numbers, bools, arrays, or tables; templates see them as engine-native values.
template.files[]
| Field | Meaning |
|---|---|
src | Template path inside the payload root |
into | Render target, relative to the deploy target dir |
into must normalize to a non-empty relative path — absolute paths, .., root/prefix components, and empty results are TemplateError::UnsafeTarget. src follows the same rule inside the payload (TemplateError::UnsafeSource).
template.extends
Optional tamias ref naming a parent template pack (git:org/repo//path, cf:…, a store name, …). The driver never resolves refs itself — resolution is tamias-side. See Composition below.
Composition (extends chains)
A pack may inherit from another template pack. tamias install resolves template.extends and materializes each ancestor's payload inside the child's at .scarab-parent/ — recursively, so a grandparent lands at .scarab-parent/.scarab-parent/, and so on.
The driver then renders the chain ancestor-first:
- parent
template.varsare the lowest-precedence defaults — folding vars ancestor→child means the child's defaults win - parent files write first, the child's last — on an
intoconflict the child wins; distinctintos all render - the state file records only the final (child) digest for a contested path, which is exactly what
uninstallneeds
Edge cases:
.scarab-parent/present withoutextendsis honored as a vendored parent — useful for local composition and testsextendsdeclared but.scarab-parent/absent is an error: the payload never went throughtamias install, and the driver can't fetch refsextends: ""(empty) fails manifest validation
TemplateEngine
The engine port — one impl per syntax family:
pub trait TemplateEngine: Send + Sync {
fn name(&self) -> &'static str;
fn render(&self, source: &str, ctx: &serde_json::Value)
-> Result<String, Box<dyn Error + Send + Sync>>;
}ctx is a JSON object; engines map it to their native value. MinijinjaEngine (scarab-template-minijinja) is the v1 impl — sandboxed, keeps the template's trailing newline so rendered config files stay POSIX-clean.
Variable context
merge_context(defaults, auto, file, args) merges flat name → JSON value layers, later winning:
ancestor template.vars … this pack's template.vars
< auto vars < --config file < env+argsOn an extends chain the driver folds every ancestor's template.vars into defaults ancestor-first, so nearer packs win. The driver supplies the layers:
template.varspack defaults — every ancestor's folded ancestor-first, then this pack's (nearest wins)- auto vars —
repo(gitremote.origin.urlbasename of the target dir, else canonical dir name) anduser($USER/$LOGNAME) --configfile — JSON by.json, TOML by.toml, YAML otherwise (incl. extensionless); must be a flat map$TEMPLATE_VAR_<NAME>env vars, name lowercased, value parsed as JSON falling back to string- trailing
key=valueargs — value parsed as JSON, falling back to string
Errors
| Variant | Meaning |
|---|---|
Manifest | Pack manifest or template: table failed to parse |
UnsafeTarget | into escaped the deploy dir |
UnsafeSource | src escaped the payload root |
NotUtf8 | Rendered output isn't valid UTF-8 text |