Template stacking
How several templates installed into one target folder are run side by side and laid on top of each other on the user's machine.
A target folder can hold many stacked templates: each cyanprint create into a folder that already has a state file adds one more.
On every create or update, the CLI runs each stacked template on its own, then lays their file sets on top of each other,
ordered by the time in each template's latest history entry. It uses the same layering rules as a dependency tree, with resolvers from the stacked templates only.
Stacking is not a dependency tree. Nothing in the registry links the stacked templates; only the target folder's state file does. This is what "client-side" means: the stack exists only on the user's machine.
The flow
flowchart LR
S[state file<br/>one record per template] --> P[previous specs]
S --> C[current specs]
P --> RP[run each spec<br/>own dependency tree]
C --> RC[run each spec<br/>own dependency tree]
RP --> LP[stack: layer by time]
RC --> LC[stack: layer by time]
LP -->|base| M[three-way merge]
L[target folder] -->|local| M
LC -->|incoming| M
M --> W[write + save state]1. Read the stack from the state file
- Each template record key is
<username>/<template>. Only records withactive: truecount (update/spec.rs:79). - Each record's latest history entry gives a spec: version, answers, and a time (
spec.rs:82-90).
2. Make previous and current specs
| Command | Previous specs | Current specs | Code |
|---|---|---|---|
create, template not in folder | the stack | the stack plus the new template | run.rs:627-643 |
create, same template, other version | the stack | the stack, that one at the new version | run.rs:644-722 |
create, same template, same version | the stack | the stack with every template's answers cleared, so every question is asked again | run.rs:723-773 |
update | the stack | every record at its latest version, or a picked one with --interactive | orchestrator.rs:179-189, spec.rs:97-148 |
3. Order the stack
Both lists are sorted by the spec time, oldest first (spec.rs:165-167). The newest spec is the top layer.
4. Run and stack
- Each spec runs its full dependency tree on its own (
run.rs:140-230). - More than one spec: the file sets are layered with
layer_merge_with_resolvers(run.rs:241-267). - Resolver votes come only from the stacked templates themselves, not from their dependencies (
run.rs:233;operator.rs:617-654). - The result is the base (from previous specs) or the incoming set (from current specs) of the three-way merge.
Worked example
The folder was made with atomi/web on 1 Mar, then atomi/ci was added on 9 Mar. Both make .editorconfig; neither declares a resolver for it.
# .cyan_state.yaml (cut down)atomi/web:active: truehistory:- version: 5time: 2026-03-01T10:00:00Zanswers: { name: { type: String, value: shop } }deterministic_states: {}atomi/ci:active: truehistory:- version: 2time: 2026-03-09T10:00:00Zanswers: {}deterministic_states: {}
cyanprint create atomi/web:6 ./shopupgradesweb: current specs areatomi/web:6andatomi/ci:2.- Order:
web(1 Mar), thenci(9 Mar).ciis the top layer, so its.editorconfigwins in both base and incoming. - After the merge,
webgets a new history entry with today's time (services.rs:66-71). - On the next run
webis the newest, soweb's.editorconfigwins. Found while reading, not run: an upgrade can change which stacked template wins a clash. (cyanprint updateloses its new history entries; see update.)
Rules worth knowing
- Order is by the latest history entry, not by install. The
installed_atfield is filled fromhistory.last().time(spec.rs:82-89), and every save writes the current time (services.rs:68). - Every stacked template runs on every create or update, twice: once for the base, once for the incoming set.
- A stacked template's own dependencies' resolvers do not vote in the stack. They vote only inside that template's tree.
- Only upgraded or added templates get a new history entry (
run.rs:290-327). The others keep their old entry and time.
Why this way
- Stack on the client. Inferred: a user can add a template to a project at any time without anyone publishing a new template group, and update each one on its own.
- Same layering rules as a dependency tree. One clash rule for the whole product: vote for a resolver, else the top layer wins.