Doc system test

Create

cyanprint create adds a template to a folder, or upgrades or reruns it when the folder already has it; one command, three modes.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/project-lifecycle
  • durian.cloud/cyanprint/prompting
  • durian.cloud/cyanprint/composition
type
feature
issues
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+stack-order-unsorted-on-rerun
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+cache-key-before-questions

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 --> B
How create picks its mode

The three modes

ModeWhenCurrent specsHistory entry saved for
new templateno state file, or no record for <user>/<template>every stacked template (saved) + this one (no answers)this template
upgradea record exists, last entry has another versionevery stacked template (saved); this one at the new version with its saved answersthis template
reruna record exists, last entry has the same versionevery stacked template with answers clearedthis 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

  1. Folder. Create the folder if missing. A headless run remembers the first folder it created, and removes it again if it stops before done.
  2. Fetch. Get the template version from the registry (newest if no version is given).
  3. Check the template. A template with neither dependencies nor images is refused: "Templates must have either dependencies or execution artifacts."
  4. Pick the mode (diagram above) and build previous and current specs.
  5. Headless answers are seeded only into this template's spec, never into other stacked templates.
  6. Batch run: run, stack, merge, write (batch run).
  7. 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.

Four creates and their modes
  1. Step 1: create atomi/web:5 ./shop

    No folder, no state file: new template. Questions asked for the whole web:5 tree.

    modenew template
    previous(none)
    currentweb:5 (no answers)
  2. Step 3: create atomi/ci:2 ./shop

    State file has atomi/web only: new template. web:5 runs twice, ci:2 once.

    modenew template
    previousweb:5
    currentweb:5, ci:2 (no answers)
  3. 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.

    modererun
    previousweb:5, ci:2 (unsorted)
    currentweb:5, ci:2 (all answers cleared)
  4. 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.

    modenew template
    askednothing (cache hit)

Here is the real code for the mode choice and the three branches.

sulfone.iridiumcyancoordinator/src/template/history.rs
  1. 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 template
    if !state_file_path.exists() {
    return Ok(TemplateUpdateType::NewTemplate);
    }
    // Load the state file
    let state = self.state_manager.load_state_file(&state_file_path)?;
    // Check if this template exists in history
    let 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 entry
    if let Some(latest_entry) = template_state.history.last() {
    // Check if versions match
    if latest_entry.version == template.principal.version {
    // Same version - user wants to re-run
    Ok(TemplateUpdateType::RerunTemplate {
    previous_version: latest_entry.version,
    previous_answers: latest_entry.answers.clone(),
    previous_states: latest_entry.deterministic_states.clone(),
    })
    } else {
    // Different version - upgrade flow
    Ok(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 history
    Ok(TemplateUpdateType::NewTemplate)
    }
    }
  2. 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>);
    }
  3. 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 primitives
    let 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 added
    let 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])
    }
  4. 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 version
    let target_key = format!("{}/{}", username, template.template.name);
    // Build prev_specs with the OLD version for the target template
    let 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 template
    let 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 changed
    let upgraded: Vec<_> = curr
    .iter()
    .filter(|s| s.key() == target_key)
    .cloned()
    .collect();
    (prev, curr, upgraded)
    }
  5. 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 template
    let 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_specs
    let 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)
    }
  6. 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

  1. Should a rerun clear only the named template's answers?
  2. Should a create into a folder that has the template be allowed at all, or should upgrades go only through update?
  3. Should the cache ever answer questions on a first create?