Doc system test

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.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/project-lifecycle
  • durian.cloud/cyanprint/prompting
  • durian.cloud/cyanprint/registry
type
feature
issues
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+update-drops-history

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 aborted
Update, step by step

What it does

  1. 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.
  2. Read the state file. No templates, or none active: done, nothing changes.
  3. 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.
  4. Classify. A template whose version changed is "upgraded"; the others run at their saved version.
  5. 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).
  6. Questions. A new version is asked only questions its saved answers do not cover. Headless answers go only to the upgraded templates.
  7. 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.

Two updates of ./shop
  1. Step 4: pick versions

    web's newest is 6, ci's newest is 2. Only web is upgraded.

    previousweb:5, ci:2
    currentweb:6, ci:2
    upgradedweb
  2. Step 4: questions

    web:6 reuses name, port, features, node_version and module_type, and asks only runtime.

    askedruntime
    answerbun
  3. Step 4: merge

    jest.config.js deleted; README.md and app.config.json get conflict markers; Dockerfile updated.

    folderweb:6 + ci:2 output, merged with user edits
  4. Step 4: history appended

    The batch run appends web's new entry to the file on disk.

    file on diskweb: [v5, v6 runtime=bun]
  5. Step 4: state saved

    update saves the copy it read before the run. The v6 entry is gone.

    file on diskweb: [v5]
  6. Step 5: update again

    The base is rebuilt from web:5 again, and web:6 asks runtime again because the saved answers lack it.

    previousweb:5, ci:2
    currentweb:6, ci:2
    askedruntime (again)

Here is the real code for the dirty check, the classification and the lost history.

sulfone.iridiumcyanprint/src/update/orchestrator.rs
  1. 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>);
    }
  2. 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>
    })?;
  3. 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 ordering
    sort_specs(&mut prev_specs);
    sort_specs(&mut curr_specs);
  4. 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
    };
  5. 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 only
    if !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.answers
    let 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,
    )?;
    }
    }
  6. 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 features from a checkbox into a text question, the saved StringArray reaches a text question; the Node SDK throws "Incorrect answer type" and the run fails. A select and a text question both take a String, 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. --interactive lets the user pick an older version; it is treated like any other version change.
  • Create has no dirty check. Upgrading one template with create skips step 1.

Questions for the designer

  1. Was update meant to save the batch run's new history entries? (Today they are overwritten.)
  2. What should happen to saved answers whose question was removed, renamed or changed type?
  3. Should create (upgrade and rerun) also check for a dirty folder?