Doc system test

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.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/project-lifecycle
  • durian.cloud/cyanprint/composition
type
flow

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 with active: true count (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

CommandPrevious specsCurrent specsCode
create, template not in folderthe stackthe stack plus the new templaterun.rs:627-643
create, same template, other versionthe stackthe stack, that one at the new versionrun.rs:644-722
create, same template, same versionthe stackthe stack with every template's answers cleared, so every question is asked againrun.rs:723-773
updatethe stackevery record at its latest version, or a picked one with --interactiveorchestrator.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.

yamlyaml
# .cyan_state.yaml (cut down)
atomi/web:
active: true
history:
- version: 5
time: 2026-03-01T10:00:00Z
answers: { name: { type: String, value: shop } }
deterministic_states: {}
atomi/ci:
active: true
history:
- version: 2
time: 2026-03-09T10:00:00Z
answers: {}
deterministic_states: {}
  1. cyanprint create atomi/web:6 ./shop upgrades web: current specs are atomi/web:6 and atomi/ci:2.
  2. Order: web (1 Mar), then ci (9 Mar). ci is the top layer, so its .editorconfig wins in both base and incoming.
  3. After the merge, web gets a new history entry with today's time (services.rs:66-71).
  4. On the next run web is the newest, so web's .editorconfig wins. Found while reading, not run: an upgrade can change which stacked template wins a clash. (cyanprint update loses its new history entries; see update.)

Rules worth knowing

  • Order is by the latest history entry, not by install. The installed_at field is filled from history.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.