Create
cyanprint create adds a template to a folder, or upgrades or reruns it when the folder already has it; one command, three modes.
What it is. cyanprint create <user>/<template>[:<version>] [folder] runs a template into a target folder (default: the current folder).
What problem it solves. One command both starts a project and adds more templates to it later; the folder's state file decides what "create" means this time.
What newcomers get wrong. Create into a folder that already has templates re-runs all of them, not just the one named. And creating a template the folder already has, at the same version, is a rerun that clears every template's answers.
The picture shows how create picks its mode from the state file.
flowchart TD
A["cyanprint create atomi/ci:2 ./shop"] --> S{".cyan_state.yaml exists?"}
S -- no --> N[new template]
S -- yes --> R{"record atomi/ci with history?"}
R -- no --> N
R -- yes --> V{"last entry version == 2?"}
V -- yes --> RR[rerun]
V -- no --> U[upgrade]
N --> B[batch run]
RR --> B
U --> BThe three modes
| Mode | When | Current specs | History entry saved for |
|---|---|---|---|
| new template | no state file, or no record for <user>/<template> | every stacked template (saved) + this one (no answers) | this template |
| upgrade | a record exists, last entry has another version | every stacked template (saved); this one at the new version with its saved answers | this template |
| rerun | a record exists, last entry has the same version | every stacked template with answers cleared | this template |
The record key is <user>/<template>: the user part of the reference typed on the command line, and the template's name.
What it does
- Folder. Create the folder if missing. A headless run remembers the first folder it created, and removes it again if it stops before
done. - Fetch. Get the template version from the registry (newest if no version is given).
- Check the template. A template with neither dependencies nor images is refused: "Templates must have either dependencies or execution artifacts."
- Pick the mode (diagram above) and build previous and current specs.
- Headless answers are seeded only into this template's spec, never into other stacked templates.
- Batch run: run, stack, merge, write (batch run).
- Save clashes and managed files; run post-template commands.
Worked example: ./shop, steps 1, 3, 6 and 7
Step through the four creates of the shop example and the mode each one takes.
- Step 1: create atomi/web:5 ./shop
No folder, no state file: new template. Questions asked for the whole web:5 tree.
mode new templateprevious (none)current web:5 (no answers) - Step 3: create atomi/ci:2 ./shop
State file has atomi/web only: new template. web:5 runs twice, ci:2 once.
mode new templateprevious web:5current web:5, ci:2 (no answers) - Step 6: create atomi/ci:2 ./shop
atomi/ci's last entry is version 2: rerun. Every spec's answers are cleared; with the cache on, every node hits and nothing is asked.
mode rerunprevious web:5, ci:2 (unsorted)current web:5, ci:2 (all answers cleared) - Step 7: create atomi/web:5 ./blog
New folder: new template. The cache holds the node keys stored in step 1 (docker:7's key has no answers; each later key has only the answers made before it), so ./blog gets shop's answers without a question.
mode new templateasked nothing (cache hit)
Here is the real code for the mode choice and the three branches.
- lines 69-115Mode: no file or no record = new; same version = rerun; other version = upgrade.
cyancoordinator/src/template/history.rs:69-115rust fn check_template_history(&self,target_dir: &Path,template: &TemplateVersionRes,username: &str,) -> Result<TemplateUpdateType, Box<dyn Error + Send>> {let state_file_path = target_dir.join(".cyan_state.yaml");// If state file doesn't exist, it's a new templateif !state_file_path.exists() {return Ok(TemplateUpdateType::NewTemplate);}// Load the state filelet state = self.state_manager.load_state_file(&state_file_path)?;// Check if this template exists in historylet template_key = format!("{}/{}", username, template.template.name);if let Some(template_state) = state.templates.get(&template_key) {// We found a matching template, get the most recent entryif let Some(latest_entry) = template_state.history.last() {// Check if versions matchif latest_entry.version == template.principal.version {// Same version - user wants to re-runOk(TemplateUpdateType::RerunTemplate {previous_version: latest_entry.version,previous_answers: latest_entry.answers.clone(),previous_states: latest_entry.deterministic_states.clone(),})} else {// Different version - upgrade flowOk(TemplateUpdateType::UpgradeTemplate {previous_version: latest_entry.version,previous_answers: latest_entry.answers.clone(),previous_states: latest_entry.deterministic_states.clone(),})}} else {// No history entries (shouldn't happen, but treat as new)Ok(TemplateUpdateType::NewTemplate)}} else {// Template not found in historyOk(TemplateUpdateType::NewTemplate)}} - sulfone.iridium/cyanprint/src/run.rs:602-607A template with no dependencies and no images is refused.
cyanprint/src/run.rs:602-607rust } else {return Err(Box::new(std::io::Error::new(std::io::ErrorKind::InvalidInput,"Invalid template: no dependencies and no execution artifacts. Templates must have either dependencies or execution artifacts.",)) as Box<dyn Error + Send>);} - sulfone.iridium/cyanprint/src/run.rs:618-643New template: the sorted saved specs plus the new one.
cyanprint/src/run.rs:618-643rust // Build specs using composable primitiveslet mut prev_specs = manager.get(&state);sort_specs(&mut prev_specs);let (prev_specs, curr_specs, upgraded_specs): (Vec<TemplateSpec>,Vec<TemplateSpec>,Vec<TemplateSpec>,) = match update_type {TemplateUpdateType::NewTemplate => {// New template being addedlet new_spec = TemplateSpec::new_template(username.clone(),template.template.name.clone(),template.principal.version,);let curr: Vec<_> = prev_specs.iter().cloned().chain(iter::once(new_spec.clone())).collect();// The new template is the only one that needs metadata saved(prev_specs, curr, vec![new_spec])} - sulfone.iridium/cyanprint/src/run.rs:644-722Upgrade: both lists rebuilt from the state map, not sorted.
cyanprint/src/run.rs:644-722rust TemplateUpdateType::UpgradeTemplate {previous_version,previous_answers,previous_states,} => {// Upgrade: prev uses old version, curr uses new versionlet target_key = format!("{}/{}", username, template.template.name);// Build prev_specs with the OLD version for the target templatelet prev: Vec<_> = state.templates.iter().filter(|(_, s)| s.active).filter_map(|(key, s)| {let (u, t) = parse_template_key(key)?;let entry = s.history.last()?;if key == &target_key {Some(TemplateSpec::new(u.to_string(),t.to_string(),previous_version,previous_answers.clone(),previous_states.clone(),entry.time,))} else {Some(TemplateSpec::new(u.to_string(),t.to_string(),entry.version,entry.answers.clone(),entry.deterministic_states.clone(),entry.time,))}}).collect();// Build curr_specs with the NEW version for the target templatelet curr: Vec<_> = state.templates.iter().filter(|(_, s)| s.active).filter_map(|(key, s)| {let (u, t) = parse_template_key(key)?;let entry = s.history.last()?;if key == &target_key {Some(TemplateSpec::new(u.to_string(),t.to_string(),template.principal.version,previous_answers.clone(),previous_states.clone(),entry.time,))} else {Some(TemplateSpec::new(u.to_string(),t.to_string(),entry.version,entry.answers.clone(),entry.deterministic_states.clone(),entry.time,))}}).collect();// Explicitly track what changedlet upgraded: Vec<_> = curr.iter().filter(|s| s.key() == target_key).cloned().collect();(prev, curr, upgraded)} - sulfone.iridium/cyanprint/src/run.rs:723-773Rerun: reset clears every spec's answers.
cyanprint/src/run.rs:723-773rust TemplateUpdateType::RerunTemplate {previous_version,previous_answers,previous_states,} => {// Rerun: prev uses old answers, curr uses empty answers (triggers Q&A)let target_key = format!("{}/{}", username, template.template.name);// Build prev_specs with the OLD answers for the target templatelet prev: Vec<_> = state.templates.iter().filter(|(_, s)| s.active).filter_map(|(key, s)| {let (u, t) = parse_template_key(key)?;let entry = s.history.last()?;if key == &target_key {Some(TemplateSpec::new(u.to_string(),t.to_string(),previous_version,previous_answers.clone(),previous_states.clone(),entry.time,))} else {Some(TemplateSpec::new(u.to_string(),t.to_string(),entry.version,entry.answers.clone(),entry.deterministic_states.clone(),entry.time,))}}).collect();// Use manager.reset() to clear answers for curr_specslet curr = manager.reset(prev.clone());// Explicitly track what changed (the rerun target)let upgraded: Vec<_> = curr.iter().filter(|s| s.key() == target_key).cloned().collect();(prev, curr, upgraded)} - sulfone.iridium/cyanprint/src/run.rs:785-801Headless answers only into the template being created.
cyanprint/src/run.rs:785-801rust let curr_specs: Vec<TemplateSpec> = if headless && !headless_answers.is_empty() {let upgraded_keys: std::collections::HashSet<String> =upgraded_specs.iter().map(|s| s.key()).collect();curr_specs.into_iter().map(|mut s| {if upgraded_keys.contains(&s.key()) {for (k, v) in &headless_answers {s.answers.insert(k.clone(), v.clone());}}s}).collect()} else {curr_specs};
Why it works this way
Hard cases
- Rerun clears everyone. Rerunning ci asks web's questions too (cache off), or asks nothing at all (cache on).
- Unsorted stack on upgrade and rerun. The lists come from a hash map; the clash winner can change between identical runs.
- The cache answers for you. A new create of a template version this machine has created before, with the same answers so far (usually none), is served from the node cache: no questions, the old answers.
- The record key ignores the version and the registry id. Two different users' templates with the same name are two records; a template renamed in the registry becomes a new record.
- No dirty check. Unlike update, create never looks at git status.
- Headless leaves no trace on a stop. A pending question or an error removes only the folders this run created; an existing folder is never touched.
Questions for the designer
- Should a rerun clear only the named template's answers?
- Should a create into a folder that has the template be allowed at all, or should upgrades go only through update?
- Should the cache ever answer questions on a first create?