Doc system test

The shop example

One project, ./shop, built up in eight steps with real file contents, including every nasty case the other docs explain.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/project-lifecycle
  • durian.cloud/cyanprint/composition
  • durian.cloud/cyanprint/prompting
  • durian.cloud/cyanprint/registry
type
tutorial
related

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 versionVersion idAsksMakes
atomi/lint:23c1f…nothing.eslintrc.json, .gitignore, package.json
atomi/docker:77a90…node_versionDockerfile, .dockerignore, package.json
atomi/node-base:3b2e4…module_typepackage.json, tsconfig.json, .gitignore, src/index.ts
atomi/web:5e5d0…name, port, featuresREADME.md, app.config.json, src/server.ts, jest.config.js, .editorconfig, package.json

Later steps add three more versions:

Template versionVersion idChange
atomi/docker:88b11…a newer base image
atomi/web:61f6a…new question runtime; drops jest.config.js; README run line depends on runtime; pins docker:8
atomi/ci:242c8…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 versionDeclares json-merger for package.json
lint:2no
docker:7, node-base:3, web:5, web:6, ci:2yes

The web script makes one random value with the determinism helper and writes it to app.config.json:

typescripttypescript
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.

yamlyaml
templates:
- ref: atomi/node-base:3
answers:
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

shellscriptshellscript
cyanprint create atomi/web:5 ./shop
  1. Run order. Dependency flattening sorts siblings by version id, children first, root last: docker:7, lint:2, node-base:3, web:5. cyan.yaml listed node-base first; the GUID order puts docker first.
  2. Questions. In run order: docker:7 asks node_version (22). lint:2 asks nothing. node-base:3 does not ask module_type: the preset answer esm fills it. web:5 asks name (shop), port (3000), features (docker).
  3. Determinism. While web:5's questions are asked, its script runs four times. d.get('instance-id') makes 4f9c2e71-aaaa on the first call, and the CLI hands it back on the next three, so it stays the same.
  4. Layering. Four outputs are laid on top of each other (dependency layering):
    • package.json is 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.
    • .gitignore is 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.
  5. Merge and write. No state file yet, so the merge base is empty and the folder is empty: every file is written.
  6. State. One template record atomi/web with one history entry. deterministic_states is {}.

The tree below is ./shop after step 1, with the files that matter later.

./shop after step 1
  • 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:

yamlyaml
atomi/web:
active: true
history:
- version: 5
time: 2026-03-01T10:00:00Z
answers:
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.json
resolution: lww_no_consensus
winner_template: e5d07b3a-2f1e-4d3c-9b8a-7f6e5d4c3b2a
- path: .gitignore
resolution: lww_all_no_resolver
winner_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.

./shop after the user's edits
Before
  • README.mdkeptshow file
    # shop
    
    Run: npm run dev
    
After
  • 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

shellscriptshellscript
cyanprint create atomi/ci:2 ./shop
  1. 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.
  2. web:5 runs twice: once for the merge base, once for the incoming set. ci:2 asks ci_provider (github).
  3. 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.
  4. 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.json gets conflict markers.
  5. Merge. README.md: the template did not change it (base = incoming), so the user's edit stays. notes.md stays. ci's files are added.

The tree below is ./shop after step 3.

./shop after step 3
Before
  • .editorconfigkeptshow file
    root = true
    [*]
    indent_size = 2
    
  • notes.mdkept
  • package.jsonkept
  • README.mdkeptuser's edit
After
  • .github/
    • workflows/
      • ci.ymladded
  • .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

shellscriptshellscript
git commit -am "before update" # on a dirty folder, update asks before it runs
cyanprint update ./shop
  1. 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.
  2. Run order of web:6. docker:8 (8b11) sorts before node-base:3 (b2e4): docker:8, lint:2, node-base:3, web:6.
  3. Questions. Saved answers are reused. web:6's only new question, runtime, is asked (bun).
  4. Merge, file by file:
    • jest.config.js: in the base, unchanged in the folder, not in incoming → deleted.
    • README.md: base Run: npm run dev, folder Run: npm run dev -- --port 3000, incoming Run: 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.

./shop after step 4
Before
  • app.config.jsonkept
  • Dockerfilekeptshow file
    FROM node:22-alpine
    
  • jest.config.jskept
  • notes.mdkept
  • README.mdkeptshow file
    # shop
    
    Run: npm run dev -- --port 3000
    
After
  • 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

shellscriptshellscript
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

shellscriptshellscript
cyanprint create atomi/ci:2 ./shop
  1. Mode. The folder already has ci at version 2: a rerun.
  2. Answers. The rerun clears the answers of every stacked template, not only ci's.
  3. 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.
  4. Cache off. Every question of web and ci is asked again.
  5. 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 .editorconfig wins can change between two runs of this same command.

Step 7. A second project on the same machine

shellscriptshellscript
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

StepWhat it showsDoc
0pinning at pushreference pinning
1run orderdependency flattening
1clashes inside one treedependency layering
1one value across replaysstateless replay
3clashes between stacked templatestemplate stacking
3, 4lost determinismclient-side state and determinism
4conflict markers, dropped filethree-way merge
4, 5lost historyupdate
6, 7stale cachenode cache