The shop example
One project, ./shop, built up in eight steps with real file contents, including every nasty case the other docs explain.
This is the one example every doc uses: the same folder, the same templates, the same versions and the same answers. Each step shows the command, what CyanPrint does, and the files before and after. Every behaviour is traced in the code; nothing here was run. The steps include the hard cases on purpose: a clash between dependencies, a clash between stacked templates, conflict markers, a dropped file, a new question on upgrade, a rerun, a pinned dependency and a stale cache.
The templates
Everything lives in the registry under the user atomi. A version id is a GUID; only its sort order matters here, so the table shows the first four characters.
| Template version | Version id | Asks | Makes |
|---|---|---|---|
| atomi/lint:2 | 3c1f… | nothing | .eslintrc.json, .gitignore, package.json |
| atomi/docker:7 | 7a90… | node_version | Dockerfile, .dockerignore, package.json |
| atomi/node-base:3 | b2e4… | module_type | package.json, tsconfig.json, .gitignore, src/index.ts |
| atomi/web:5 | e5d0… | name, port, features | README.md, app.config.json, src/server.ts, jest.config.js, .editorconfig, package.json |
Later steps add three more versions:
| Template version | Version id | Change |
|---|---|---|
| atomi/docker:8 | 8b11… | a newer base image |
| atomi/web:6 | 1f6a… | new question runtime; drops jest.config.js; README run line depends on runtime; pins docker:8 |
| atomi/ci:2 | 42c8… | asks ci_provider; makes .github/workflows/ci.yml, .editorconfig, package.json |
Which templates declare the conflict resolver atomi/json-merger:1 for package.json (all with config {"arrays":"concat"}):
| Template version | Declares json-merger for package.json |
|---|---|
| lint:2 | no |
| docker:7, node-base:3, web:5, web:6, ci:2 | yes |
The web script makes one random value with the determinism helper and writes it to app.config.json:
const instanceId = d.get('instance-id', () => crypto.randomUUID());
Step 0. Push pins the docker dependency
atomi/web:5's cyan.yaml lists its dependencies like this. atomi/docker has no version.
templates:- ref: atomi/node-base:3answers:module_type: esm- ref: atomi/docker
When cyanprint push publishes web:5, the registry turns atomi/docker into the latest docker version at that moment, docker:7, and stores its version id in web:5 (reference pinning).
Later atomi/docker:8 is pushed. web:5 still runs docker:7, forever. web:6, pushed after docker:8 existed, runs docker:8.
Step 1. Create the shop
cyanprint create atomi/web:5 ./shop
- Run order. Dependency flattening sorts siblings by version id, children first, root last: docker:7, lint:2, node-base:3, web:5.
cyan.yamllisted node-base first; the GUID order puts docker first. - Questions. In run order: docker:7 asks
node_version(22). lint:2 asks nothing. node-base:3 does not askmodule_type: the preset answeresmfills it. web:5 asksname(shop),port(3000),features(docker). - Determinism. While web:5's questions are asked, its script runs four times.
d.get('instance-id')makes4f9c2e71-aaaaon the first call, and the CLI hands it back on the next three, so it stays the same. - Layering. Four outputs are laid on top of each other (dependency layering):
package.jsonis written by all four. Votes: json-merger, none (lint:2), json-merger, json-merger. Not every writer votes the same, so last layer wins: web:5's file. The eslint devDependency (lint:2) and the docker script (docker:7) are lost..gitignoreis written by lint:2 and node-base:3, neither with a resolver: node-base:3 wins.- Every other path has one writer and is copied.
- Merge and write. No state file yet, so the merge base is empty and the folder is empty: every file is written.
- State. One template record
atomi/webwith one history entry.deterministic_statesis{}.
The tree below is ./shop after step 1, with the files that matter later.
- src/
- index.tsadded
- server.tsadded
- .cyan_state.yamladded
- .dockerignoreadded
.editorconfigaddedshow file
root = true [*] indent_size = 2- .eslintrc.jsonadded
.gitignoreaddednode-base:3 won over lint:2show file
node_modules/ dist/app.config.jsonaddedshow file
{ "name": "shop", "port": 3000, "instanceId": "4f9c2e71-aaaa" }Dockerfileaddedshow file
FROM node:22-alpine- jest.config.jsadded
package.jsonaddedweb:5's file won; lint and docker parts lostshow file
{ "scripts": { "dev": "node src/server.ts", "test": "jest" } }README.mdaddedshow file
# shop Run: npm run dev- tsconfig.jsonadded
The state file after step 1:
atomi/web:active: truehistory:- version: 5time: 2026-03-01T10:00:00Zanswers:node_version: { type: String, value: "22" }module_type: { type: String, value: esm }name: { type: String, value: shop }port: { type: String, value: "3000" }features: { type: StringArray, value: [docker] }deterministic_states: {}files: [.dockerignore, .editorconfig, .eslintrc.json, .gitignore, Dockerfile, README.md, app.config.json, jest.config.js, package.json, src/index.ts, src/server.ts, tsconfig.json]managed_files: [.dockerignore, .editorconfig, .eslintrc.json, .gitignore, Dockerfile, README.md, app.config.json, jest.config.js, package.json, src/index.ts, src/server.ts, tsconfig.json]file_conflicts:- path: package.jsonresolution: lww_no_consensuswinner_template: e5d07b3a-2f1e-4d3c-9b8a-7f6e5d4c3b2a- path: .gitignoreresolution: lww_all_no_resolverwinner_template: b2e4911f-7c6d-4e5f-8a9b-1c2d3e4f5a6b
module_type (a preset) and node_version (docker's question) are saved under web, because a stacked template's saved answers are every answer its whole tree used. The file_conflicts entries are shortened: each also lists every writer under variations.
The node cache. Each of the four nodes is stored in the node cache under a key made before its questions were asked. For docker:7 and web:5 that key holds whatever answers came before them in the run; for docker:7, the first node, it holds none. This matters in steps 6 and 7.
Step 2. The user edits
The user changes one line in README.md, adds a file of their own, and commits.
README.mdkeptshow file
# shop Run: npm run dev
notes.mdaddedthe user's own fileshow file
Deploy on Fridays.README.mdchangedshow file
# shop Run: npm run dev -- --port 3000
Step 3. Stack a second template
cyanprint create atomi/ci:2 ./shop
- Mode. The folder has a state file without
atomi/ci, so this adds a stacked template. Previous specs: web:5 with its saved answers. Current specs: web:5 with its saved answers, then ci:2 with none. - web:5 runs twice: once for the merge base, once for the incoming set. ci:2 asks
ci_provider(github). - Stacking. web:5 (1 Mar) is laid first, ci:2 (now) on top (template stacking):
.editorconfig: both write it, neither declares a resolver for it → ci:2 wins (indent 4).package.json: both declare json-merger:1 with the same config → they agree → the resolver is called with both files and returns one merged file.
- Determinism, by luck. web:5's saved history has no deterministic state, so a live run makes a new UUID.
The base run's cache key now holds the full saved answers (not step 1's), so it misses, runs live, makes B and stores it. The incoming web:5 run has the same key, hits, and also gets B.
Base equals incoming, so the merge keeps the folder's A. With the cache off, base makes B, incoming makes C, and
app.config.jsongets conflict markers. - Merge.
README.md: the template did not change it (base = incoming), so the user's edit stays.notes.mdstays. ci's files are added.
The tree below is ./shop after step 3.
.editorconfigkeptshow file
root = true [*] indent_size = 2- notes.mdkept
- package.jsonkept
- README.mdkeptuser's edit
- .github/
- workflows/
- ci.ymladded
- workflows/
.editorconfigchangedci:2 won the clashshow file
root = true [*] indent_size = 4- app.config.jsonkeptstill A, only because the cache made base equal incoming
- notes.mdkept
package.jsonchangedjson-merger joined web and cishow file
{ "scripts": { "dev": "node src/server.ts", "test": "jest", "ci": "npm test" } }- README.mdkeptuser's edit kept
The state file gains atomi/ci. file_conflicts now lists only the stacking clashes (.editorconfig, package.json); step 1's clashes inside web:5's tree are gone from the record, because only the last layering pass is kept.
Step 4. Update to the newest versions
git commit -am "before update" # on a dirty folder, update asks before it runscyanprint update ./shop
- Versions. web: newest is 6. ci: newest is 2. Both lists are sorted by time: previous = [web:5, ci:2], current = [web:6, ci:2]. web keeps its 1 Mar time.
- Run order of web:6. docker:8 (8b11) sorts before node-base:3 (b2e4): docker:8, lint:2, node-base:3, web:6.
- Questions. Saved answers are reused. web:6's only new question,
runtime, is asked (bun). - Merge, file by file:
jest.config.js: in the base, unchanged in the folder, not in incoming → deleted.README.md: baseRun: npm run dev, folderRun: npm run dev -- --port 3000, incomingRun: bun dev→ the same line changed on both sides → conflict markers.app.config.json: base web:5 from the cache (B), folder A, incoming web:6 live (D) → conflict markers. This happens on every upgrade, cache or not, because deterministic state is not saved.Dockerfile: docker:8's text replaces docker:7's (the user never edited it).notes.md: only in the folder → kept.
The tree below is ./shop after step 4.
- app.config.jsonkept
Dockerfilekeptshow file
FROM node:22-alpine- jest.config.jskept
- notes.mdkept
README.mdkeptshow file
# shop Run: npm run dev -- --port 3000
- app.config.jsonconflictA vs D: lost determinism
Dockerfilechangedshow file
FROM node:22-bookworm-slim- jest.config.jsremoved
- notes.mdkept
README.mdconflictshow file
# shop <<<<<<< Run: npm run dev -- --port 3000 ======= Run: bun dev >>>>>>>
Bug today: the new version is not recorded. The batch run appends web's new history entry (version 6, runtime: bun) to the state file. Then cyanprint update saves the copy of the state it read before the run over it. The state file still says web:5, with no runtime.
Step 5. Update again
git commit -am "fixed conflicts"cyanprint update ./shop
Because step 4 lost web's new history entry, this update builds the merge base from web:5 again and asks runtime again.
If the user answers bun again and their fix of the README line is not exactly Run: bun dev, the merge sees both sides change that line again and the conflict markers come back.
Step 6. Rerun the ci template
cyanprint create atomi/ci:2 ./shop
- Mode. The folder already has ci at version 2: a rerun.
- Answers. The rerun clears the answers of every stacked template, not only ci's.
- Cache on (the default). Every node is looked up with the same, empty starting answers as its first run in steps 1 and 3. Those keys were stored then → every node hits → no question is asked, and the old outputs and answers come back.
- Cache off. Every question of web and ci is asked again.
- Order. A rerun builds its spec lists from the state file's map without sorting by time, so web and ci can be stacked in either order. Which
.editorconfigwins can change between two runs of this same command.
Step 7. A second project on the same machine
cyanprint create atomi/web:5 ./blog
With the cache on, every web:5 node has the same key as in step 1, so every node hits. ./blog gets shop's answers and files (name shop, port 3000, instance id A) without a single question.
Where each step is explained
| Step | What it shows | Doc |
|---|---|---|
| 0 | pinning at push | reference pinning |
| 1 | run order | dependency flattening |
| 1 | clashes inside one tree | dependency layering |
| 1 | one value across replays | stateless replay |
| 3 | clashes between stacked templates | template stacking |
| 3, 4 | lost determinism | client-side state and determinism |
| 4 | conflict markers, dropped file | three-way merge |
| 4, 5 | lost history | update |
| 6, 7 | stale cache | node cache |