Doc system test

Headless mode

create, update and try without a terminal - the answers file, the two walks, the JSON envelope, exit codes 0/2/1, cleanup, and the stdout contract.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/prompting
  • durian.cloud/cyanprint/project-lifecycle
  • durian.cloud/cyanprint/composition
  • durian.cloud/cyanprint/coordinator
type
flow
issues
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+headless-cache-summary-on-stdout
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+revealed-answers-pruning-undone
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+headless-ignores-deterministic-state
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+headless-rerun-stuck-on-cache-miss

The problem. CI jobs, scripts and other programs need to create and update projects, but the CLI asks its questions in a terminal. A program cannot answer a prompt, and it cannot hold a run open while it works out the next answer.

The idea. Turn the question loop inside out, like stateless replay does for templates: the caller supplies every answer it has, the CLI replays from scratch, and either finishes or prints the one question it is missing and exits. The caller adds that answer and runs the same command again. Each run is a complete, fresh replay.

The flow below is one headless invocation, from the answers file to the exit code.

flowchart TD
  A["--answers file, or piped stdin, or nothing"] --> P{"parse id → {type, value}"}
  P -->|bad JSON| E1["error envelope, exit 1"]
  P --> B["batch run: every template spec, every node"]
  B --> D["per node: discovery walk<br/>validate each reached supplied answer"]
  D -->|refused| ER["Err → error envelope, exit 1"]
  D --> O["outcome walk: full map, state {}"]
  O -->|unsupplied question| NI["NeedInput: stop the batch,<br/>no write, remove created folder"]
  O -->|final reply| BUILD["build phase, next node"]
  BUILD --> B
  B -->|all nodes done| W["merge, write, save state, commands"]
  NI --> C["release sessions"]
  W --> C2["release sessions"]
  C --> NE["need_input envelope, exit 2"]
  C2 --> DONE["done envelope, exit 0"]
One headless run

The answers file

  • Flags: --headless turns it on; --answers <path> names the answers file. Both exist on create, update, try template and try group. update refuses --headless with --interactive.
  • Source: --answers <path> if given; else stdin if stdin is not a terminal; else no answers. --answers - is a file called -.
  • Format: one JSON object, question id to an answer in file spelling. Empty or blank input means "no answers yet".
jsonjson
{
"7a90c2d4-1e3f-4b5a-8c6d-9e0f1a2b3c4d/node_version": { "type": "String", "value": "22" },
"e5d07b3a-2f1e-4d3c-9b8a-7f6e5d4c3b2a/name": { "type": "String", "value": "shop" },
"e5d07b3a-2f1e-4d3c-9b8a-7f6e5d4c3b2a/port": { "type": "String", "value": "3000" },
"e5d07b3a-2f1e-4d3c-9b8a-7f6e5d4c3b2a/features": { "type": "StringArray", "value": ["docker"] }
}
  • Not accepted: flat values ({"name": "shop"}), YAML, an {answers: …} wrapper, deterministic state.
  • A parse error names only the category and position, for example failed to parse answers JSON: answers JSON does not match the expected {id: {type, value}} shape (line 2, column 61); never the value.
  • Where answers go: only into the template this command adds, upgrades or reruns (create), or the upgraded templates (update). Other stacked templates replay with their saved answers only.
  • Ids: use the id exactly as a need_input envelope gave it. In a tree with more than one template with an image, that is <version id>/<id> (answer namespacing); a raw id also works but reaches every node that asks it.

The two walks, per node

Each template node runs two walks in start_headless. Details of the checks are in answer validation.

  1. Discovery walk. Start with an empty map and empty state. Each time the template asks a question the caller supplied, check and validate that answer, add it, carry the reply's state, call again. Stop at the first unsupplied question or the final reply. Result: the revealed answers.
  2. Outcome walk. Start again from empty state and send the whole supplied map. On a final reply, return Complete with the revealed answers. On a supplied question (a template that asks in a different order), validate and go on. On an unsupplied question, return NeedInput. With the SDKs' first-unanswered replay this is usually one call.
  3. Each walk stops with an error after 1000 calls. Any init call error is redacted before it becomes the message.

The envelope and exit codes

The envelope is one JSON object and a newline on stdout. The table is complete.

StatusShapeExitMeaning
done{"status":"done"}0files written, state saved, commands run
need_input{"status":"need_input","question":{…}}2add this answer and run again
error{"status":"error","message":"…"}1stopped; message names ids, not values
  • done never echoes answers or files.
  • The question uses snake_case fields and no password default (question).
  • A prompting error's message is the Rust debug print of a ProblemDetails (title: "🚨 Template Prompting Error", …, data: … "error": "invalid answer for question 'port': …"), not a short sentence.
  • If writing the envelope fails (closed pipe), the exit code is 1.

Cleanup and what a stopped run leaves

  • Nothing is written before done. A need_input stops the batch run before layering, merge, write, state save and commands.
  • A folder this run created is removed on need_input or error, down to the shallowest new parent (created folder cleanup). A folder that already existed is untouched.
  • Sessions are released at the command boundary, best effort.
  • Not undone: containers warmed, images pulled, node cache entries stored for nodes that completed, and anything after the write (a failed post-template command gives error with the files already on disk).

Here is the real code from ingestion to exit code.

sulfone.iridiumcyanprint/src/headless.rs
  1. lines 121-138Source order: --answers file, else stdin when piped, else empty.
    cyanprint/src/headless.rs:121-138rust
    pub fn read_answers_from(
    answers_path: Option<&str>,
    read_stdin: bool,
    stdin: impl Read,
    ) -> Result<HashMap<String, Answer>, Box<dyn Error + Send>> {
    if let Some(path) = answers_path {
    let content = fs::read_to_string(path).map_err(|e| {
    Box::new(std::io::Error::other(format!(
    "failed to read answers file '{path}': {e}"
    ))) as Box<dyn Error + Send>
    })?;
    return parse_answers(&content);
    }
    if read_stdin {
    return read_answers_reader(stdin);
    }
    Ok(HashMap::new())
    }
  2. lines 74-78Blank input is a valid empty map; anything else must map ids to typed answers.
    cyanprint/src/headless.rs:74-78rust
    pub fn parse_answers(raw: &str) -> Result<HashMap<String, Answer>, Box<dyn Error + Send>> {
    let trimmed = raw.trim();
    if trimmed.is_empty() {
    return Ok(HashMap::new());
    }
  3. sulfone.iridium/cyanprompt/src/domain/services/template/engine.rs:140-145Discovery first; then the outcome walk starts again from empty state.
    cyanprompt/src/domain/services/template/engine.rs:140-145rust
    let revealed = match self.validate_supplied_answers(&answers) {
    Ok(revealed) => revealed,
    Err(msg) => return TemplateState::Err(msg),
    };
    let mut state_data: HashMap<String, String> = HashMap::new();
  4. sulfone.iridium/cyanprompt/src/domain/services/template/engine.rs:176-188Outcome walk: final → Complete with the revealed answers only.
    cyanprompt/src/domain/services/template/engine.rs:176-188rust
    match self.client.prompt_template(input) {
    Ok(TemplateOutput::Final(c)) => {
    // Persist ONLY the answers the coordinator actually revealed and
    // accepted during the discovery walk — not the full caller-supplied
    // map. `revealed` excludes over-supplied / untaken-branch answers
    // (and their secrets), so a stale value for a question that was never
    // prompted cannot leak into persisted state and be silently reused on
    // a later run where the branch changes.
    return TemplateState::Complete(c.cyan, revealed);
    }
    Ok(TemplateOutput::QnA(q)) => {
    let question_id = q.question.id();
    if let Some(answer) = answers.get(&question_id) {
  5. sulfone.iridium/cyanprompt/src/domain/services/template/engine.rs:226-236A supplied question advances; an unsupplied one is NeedInput.
    cyanprompt/src/domain/services/template/engine.rs:226-236rust
    walked.insert(question_id, answer.clone());
    state_data = q.deterministic_state;
    }
    Err(msg) => {
    return TemplateState::Err(msg);
    }
    }
    } else {
    // First unanswered question — emit and stop.
    return TemplateState::NeedInput(q.question, q.deterministic_state);
    }
  6. sulfone.iridium/cyanprint/src/run.rs:829-843need_input returns before any write; the folder guard removes what this run created.
    cyanprint/src/run.rs:829-843rust
    // Headless: a question is pending. Do NOT persist state, write files, or run
    // post-commands — surface the question and stop (stateless replay). The still-armed
    // `dir_guard` drops on this return and removes the directory tree THIS invocation
    // created (the walk stopped before PHASE 4, so the tree is empty and removal is safe),
    // leaving the filesystem exactly as found; a pre-existing target is untouched.
    if let Some(question) = need_input {
    return Ok(CyanRunResult {
    session_ids,
    need_input: Some(question),
    });
    }
    // Past the `need_input` check the run is committed to producing output (`done`):
    // disarm the directory guard so the created tree is kept from here on.
    dir_guard.disarm();
  7. lines 211-234One boundary: release sessions, build the envelope, print it.
    cyanprint/src/headless.rs:211-234rust
    pub fn finish_headless<W, F>(
    r: Result<CyanRunResult, Box<dyn Error + Send>>,
    writer: &mut W,
    clean_sessions: F,
    ) -> Result<(), Box<dyn Error + Send>>
    where
    W: std::io::Write,
    F: FnOnce(&[String]),
    {
    use cyanprompt::domain::models::headless::{HeadlessEnvelope, QuestionWire};
    let env = match r {
    Ok(result) => {
    clean_sessions(&result.session_ids);
    match result.need_input {
    Some(question) => HeadlessEnvelope::NeedInput {
    question: QuestionWire::from(&question),
    },
    None => HeadlessEnvelope::Done,
    }
    }
    Err(e) => HeadlessEnvelope::error(e.to_string()),
    };
    emit_to(writer, &env).map_err(|e| Box::new(e) as Box<dyn Error + Send>)
    }
  8. lines 159-174One JSON line; done → Ok, need_input → 2, error → 1; a write failure → 1.
    cyanprint/src/headless.rs:159-174rust
    pub fn emit_to<W: std::io::Write>(
    writer: &mut W,
    envelope: &HeadlessEnvelope,
    ) -> Result<(), HeadlessExit> {
    // One JSON object + trailing newline. A write failure (e.g. a closed pipe) is
    // treated as a non-zero exit so a caller observing the exit code does not mistake
    // a truncated stream for success.
    let json = envelope.to_json();
    if writeln!(writer, "{json}").is_err() {
    return Err(HeadlessExit(1));
    }
    match envelope.exit_code() {
    0 => Ok(()),
    code => Err(HeadlessExit(code)),
    }
    }
  9. sulfone.iridium/cyanprint/src/main.rs:46-58main turns the code into the process exit status without printing again.
    cyanprint/src/main.rs:46-58rust
    match run() {
    Ok(()) => ExitCode::SUCCESS,
    Err(e) => {
    // Headless commands signal their exit code via HeadlessExit; the JSON
    // envelope has already been printed to stdout, so do not print an
    // "Error:" line — just propagate the code (need_input → 2, error → 1).
    if let Some(headless_exit) = e.downcast_ref::<crate::headless::HeadlessExit>() {
    return ExitCode::from(headless_exit.0);
    }
    eprintln!("Error: {e}");
    ExitCode::FAILURE
    }
    }

Worked example: a script creates ./shop

A CI job runs cyanprint create atomi/web:5 ./shop --headless --answers answers.json on a fresh machine, adding one answer per round. Step through the three rounds.

Three headless runs to create ./shop
  1. Run 1: empty answers

    docker:7 runs first. Its discovery walk has nothing to check; its outcome walk stops at node_version. lint:2, node-base:3 and web:5 never run.

    answers.json{}
    stdoutneed_input, id 7a90c2d4-…/node_version, select [20, 22]
    exit2
    ./shopcreated, then removed
  2. Run 2: node_version added

    docker:7 validates 22 against its options and completes (built and cached). lint:2 completes; node-base:3 completes with its preset module_type. web:5 stops at name.

    answers.jsonnode_version
    stdoutneed_input, id e5d07b3a-…/name, text
    exit2
    ./shopcreated, then removed
  3. Run 3: all answers

    docker:7, lint:2 and node-base:3 are served from the node cache (no questions, no validation). web:5's discovery walk validates name and port with two validate calls and checks features against its options; the outcome walk completes in one init call.

    answers.jsonnode_version, name, port, features
    stdout line 1♻️ Cache: 3/4 nodes served from cache
    stdout line 2{"status":"done"}
    exit0
  4. instance-id in run 3

    Discovery made a value X in its first call and carried it; the outcome walk started from {} and made a new value Y. The files hold Y, and the state file saves {}.

    discoveryX
    outcome walkY
    app.config.jsoninstanceId Y

Why it is built this way

Hard cases

  • stdout is not always one line. Create and update print the cache summary (♻️ Cache: …) on stdout before a done envelope whenever the cache is on, which is the default. try suppresses it. With cache debug on, per-node cache HIT/MISS lines also go to stdout.
  • Exit 2 is not only need_input. A bad flag (including --headless --interactive on update) is a clap usage error: it prints to stderr, no envelope, and clap exits with 2.
  • Over-supplied answers are still saved. The engine returns only revealed answers, but the composition state starts from the whole supplied map, and that map is what the state file saves. An answer for a branch not taken lands in .cyan_state.yaml.
  • Two walks, two random values. Discovery and outcome each start from {}, so d.get values differ between them, and a template that branches on one can be validated on one path and built on another.
  • Cache hits skip validation. A node served from the cache runs no walk at all, so its supplied answers are not checked.
  • Saved answers are re-validated. In an update, the upgraded template's saved answers are in the supplied map, so discovery validates them against the new version's validators. So are the saved answers of every other re-executed template that is not served from the cache: each node runs both walks over its whole map (executor.rs:208-211), so a stricter validator there can fail the run even when the caller supplies nothing. Found while reading; not run.
  • Validators see fewer siblings than in a terminal. The discovery walk's sibling map holds only the answers this node revealed, not carried or preset ones (answer validation).
  • A failed validate call passes. A JSON error body from the coordinator or a Python SDK decodes as "accepted", so the walk goes on (question protocol).
  • Work is repeated each round. Every round re-runs every node before the missing question, including warm and build; only the cache saves time.
  • An answer for a non-target template cannot be given. Supplied answers reach only the added or upgraded template; if another stacked template's replay ever stops at a question, no answers file can satisfy it.
  • A headless rerun can get stuck on a cache miss. In the shop's step 6 (cyanprint create atomi/ci:2 ./shop again) manager.reset clears the answers of every stacked template, web:5 included (run.rs:763), but supplied answers go only to the rerun target ci:2 (run.rs:785-801). With the node cache on, web:5 is a hit with answers {} and nothing is asked. With the cache off, or after a miss, web:5 asks name again, the run stops with need_input, and adding the answer changes nothing because it never reaches web:5: every round returns the same question. Found while reading; not run.

Questions for the designer

  1. Why exit code 2 for need_input, given clap also uses 2 for usage errors?
  2. Should the envelope carry the deterministic state, so the next round can pass it back?
  3. Should supplied answers be able to reach every stacked template, scoped by template?
  4. Should done report anything (files written, conflicts) for the caller?
  5. Should a headless rerun reuse the saved answers of the templates it does not target, instead of clearing them, so it can finish on a cache miss?