Update
cyanprint update moves every stacked template in a folder to its newest (or a picked) version, reusing saved answers and asking only new questions.
What it is. cyanprint update <folder> brings every stacked template in the folder to a newer version in one run, keeping the user's edits.
What problem it solves. A template author ships web:6; every project made from web:5 should get the change without retyping its answers and without losing local edits.
What newcomers get wrong. Update does not upgrade one template; it re-runs all of them. And today it does not record what it did: the state file still names the old versions afterwards.
The picture shows the steps and where a run can stop.
stateDiagram-v2
[*] --> DirtyCheck
DirtyCheck --> AskProceed: uncommitted changes (interactive)
DirtyCheck --> Failed: uncommitted changes (headless)
DirtyCheck --> ReadState: clean, no git, or --force
AskProceed --> Aborted: No
AskProceed --> ReadState: Yes
ReadState --> Done: no templates / none active
ReadState --> PickVersions
PickVersions --> BatchRun: newest, or chosen with --interactive
BatchRun --> NeedInput: headless, a question has no answer
BatchRun --> Failed: error (sessions released)
BatchRun --> SaveState
SaveState --> Commands
Commands --> Done
Commands --> Failed: a command failed (headless) or abortedWhat it does
- Git dirty check. Unless
--force: uncommitted changes make an interactive run ask "Do you want to proceed with the update?" and a headless run fail. No git, or not a repo: a note, then it runs. - Read the state file. No templates, or none active: done, nothing changes.
- Pick versions. For each stacked template, fetch every version from the registry. Default: the highest version number. With
--interactive: a list to choose from, newest first (an older version may be picked too). Headless always takes the newest. - Classify. A template whose version changed is "upgraded"; the others run at their saved version.
- Batch run. Previous specs = saved versions; current specs = picked versions with saved answers. Both are sorted by time. Every template runs twice, the outputs are stacked, and the three-way merge writes the folder (batch run).
- Questions. A new version is asked only questions its saved answers do not cover. Headless answers go only to the upgraded templates.
- Save state and run post-template commands.
Worked example: ./shop, steps 4 and 5
Step through what update does to ./shop (from the shop example) and what the state file says afterwards.
- Step 4: pick versions
web's newest is 6, ci's newest is 2. Only web is upgraded.
previous web:5, ci:2current web:6, ci:2upgraded web - Step 4: questions
web:6 reuses name, port, features, node_version and module_type, and asks only runtime.
asked runtimeanswer bun - Step 4: merge
jest.config.js deleted; README.md and app.config.json get conflict markers; Dockerfile updated.
folder web:6 + ci:2 output, merged with user edits - Step 4: history appended
The batch run appends web's new entry to the file on disk.
file on disk web: [v5, v6 runtime=bun] - Step 4: state saved
update saves the copy it read before the run. The v6 entry is gone.
file on disk web: [v5] - Step 5: update again
The base is rebuilt from web:5 again, and web:6 asks runtime again because the saved answers lack it.
previous web:5, ci:2current web:6, ci:2asked runtime (again)
Here is the real code for the dirty check, the classification and the lost history.
- lines 65-77Dirty and headless: an error envelope, never a prompt.
cyanprint/src/update/orchestrator.rs:65-77rust if !force {match is_git_dirty(target_dir) {Ok(true) => {if headless {// Headless mode cannot answer an interactive Select prompt,// and silently overwriting uncommitted changes would be unsafe.// Surface the dirty state as an error envelope (exit 1) so the// caller resolves the working tree or re-runs with --force.return Err(Box::new(std::io::Error::other("working directory has uncommitted changes; commit/stash them or re-run with --force",)) as Box<dyn Error + Send>);} - lines 161-168The state file is read here, once, before anything runs.
cyanprint/src/update/orchestrator.rs:161-168rust let state_file_path = target_dir.join(".cyan_state.yaml");let state_manager = DefaultStateManager::new();let mut cyan_state = state_manager.load_state_file(&state_file_path).map_err(|e| {Box::new(std::io::Error::other(format!("Failed to load state: {e}")))as Box<dyn Error + Send>})?; - lines 189-193Pick versions, then sort both lists by time.
cyanprint/src/update/orchestrator.rs:189-193rust let mut curr_specs = manager.update(prev_specs.clone(), interactive)?;// Sort both lists by installation time for consistent LWW orderingsort_specs(&mut prev_specs);sort_specs(&mut curr_specs); - lines 198-204Upgraded = version differs from the saved one, or new.
cyanprint/src/update/orchestrator.rs:198-204rust let is_upgraded = |c: &TemplateSpec| {prev_specs.iter().find(|p| p.key() == c.key()).map(|p| p.version != c.version).unwrap_or(true) // New template}; - sulfone.iridium/cyanprint/src/run.rs:290-327Inside the batch run: append a history entry for each upgraded template, on disk.
cyanprint/src/run.rs:290-327rust // Save metadata for upgraded templates onlyif !upgraded_specs.is_empty() {crate::hprogress!(headless,"💾 Saving template metadata for {} upgraded templates",upgraded_specs.len());for spec in upgraded_specs {let template_res = registry.get_template(spec.username.clone(),spec.template_name.clone(),Some(spec.version),)?;// Use final answers from execution (includes Q&A answers) if available,// otherwise fall back to spec.answerslet final_answers = final_answers_map.get(&spec.key()).cloned().unwrap_or_else(|| spec.answers.clone());let template_state = TemplateState::Complete(Cyan {processors: Vec::new(),plugins: Vec::new(),},final_answers,);operator.get_template_history().save_template_metadata(target_dir,&template_res,&template_state,&spec.username,)?;}} - lines 272-279Back in update: set clashes and managed files on the early copy and save it over the file.
cyanprint/src/update/orchestrator.rs:272-279rust // Persist file conflicts to state file (always update to clear stale entries)let conflicts_count = file_conflicts.len();cyan_state.file_conflicts = file_conflicts;// Recompute the managed-files manifest wholesale from this run's active templates.cyan_state.set_managed_files(&managed_by_template);let managed_count = cyan_state.managed_files.len();// A save failure here drops the still-armed `session_guard`, releasing the sessions.state_manager.save_state_file(&cyan_state, &state_file_path)?;
Why it works this way
Hard cases
- A changed question. Saved answers are matched by question id only. If web:7 turned
featuresfrom a checkbox into a text question, the savedStringArrayreaches a text question; the Node SDK throws "Incorrect answer type" and the run fails. A select and a text question both take aString, so a changed option list is not checked. - A removed question. Its saved answer is still sent and still saved; nothing removes it.
- A renamed question id is a new question: it is asked, and the old answer stays in the file.
- Every stacked template runs, upgraded or not, twice. An update of five templates where one changed runs ten trees.
- Version going down.
--interactivelets the user pick an older version; it is treated like any other version change. - Create has no dirty check. Upgrading one template with
createskips step 1.
Questions for the designer
- Was update meant to save the batch run's new history entries? (Today they are overwritten.)
- What should happen to saved answers whose question was removed, renamed or changed type?
- Should
create(upgrade and rerun) also check for a dirty folder?