Doc system test

Question

The six kinds of question a template can ask, their fields and ids, how each becomes a terminal prompt, and what Esc does.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/prompting
  • durian.cloud/cyanprint/authoring
  • durian.cloud/cyanprint/composition
type
format
issues
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+esc-on-first-question-exits-zero
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+date-bounds-differ-interactive-headless
  • https://github.com/AtomiCloud/sulfone.helium/issues?q=TBD+node-date-utc-shift
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+esc-never-exits-after-first-node
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+ctrl-c-leaves-folder-exit-zero

What it is. A question is one thing a template script asks: text, password, select, checkbox, confirm or date. It has a question id, a message, an optional description, and extras that depend on its kind.

What problem it solves. The script runs in a container on a server, but the person answering sits at a terminal. The question is the message that crosses that gap: the template describes what it needs, and the CLI turns it into a prompt.

What newcomers get wrong. A question is not stored anywhere: it exists only while a stateless replay is stopped at it. The id, not the order or the kind, ties it to its answer. And Esc does not go back to the previous question: it asks the same one again, or ends the CLI.

The picture shows one question's path, from the author's call to the terminal (or to the headless envelope).

flowchart TD
  A["author code in web:5<br/>i.text({ id: 'port', ... })"] --> B["SDK inquirer: no 'port' answer<br/>throws the checkpoint exception"]
  B --> C["question reply JSON<br/>type: text, id: port, default: 3000"]
  C --> D["CLI: Question::Text<br/>(cyanprompt)"]
  D -->|interactive| E["inquire Text prompt<br/>+ validator"]
  D -->|headless| F["envelope need_input<br/>QuestionWire, snake_case"]
  E --> G["Answer::String 3000, stored under id port"]
One question from script to terminal

The six kinds

Each kind has its own extras, its own terminal widget and its own answer type. The table is complete.

Kind (wire type)Extra fieldsTerminal promptAnswer
textdefault, initial, validatorfree text; default shown, initial pre-filledString
passwordconfirmation, validatormasked input; asks twice unless confirmation: falseString
selectoptionspick one from the listString
checkboxoptionspick any number from the listStringArray
confirmdefault, errorMessageyes/no; errorMessage shows on a bad y/nBool
datedefault, minDate, maxDate, validatorcalendar picker, boundedString YYYY-MM-DD

Every kind also has id, message and desc (shown as help text under the prompt). Only text, password and date can carry a validator: the SDK types give select, checkbox and confirm validate?: null, and the CLI attaches a validator only to those three prompts. The validator is a function in the template; it is never sent. See answer validation.

Ids

  • The author picks the id. It is the key of the answer in the answer map, the answers file, the state file and the node cache.
  • Two questions with one id get one answer. A second i.text(..., 'name') later in the script is answered silently by the first.
  • When a template's dependency tree has more than one template with an image, a question surfaced in headless need_input gets the prefix <version id>/ (answer namespacing). The template itself always sees the raw id.

Wire shapes

The same question has two JSON spellings. Here is web:5's port question as the template sends it in a question reply (camelCase, every optional field present as null):

jsonjson
{ "type": "text", "id": "port", "message": "Port?", "desc": "Port the dev server listens on",
"default": "3000", "initial": null }

And as a headless need_input envelope carries it (snake_case, id prefixed because web:5's tree has four templates with images):

jsonjson
{ "type": "text", "id": "e5d07b3a-2f1e-4d3c-9b8a-7f6e5d4c3b2a/port", "message": "Port?",
"desc": "Port the dev server listens on", "default": "3000", "initial": null }

Where the two differ:

FieldQuestion reply (HTTP)Headless envelope
date boundsminDate, maxDatemin_date, max_date
confirm error texterrorMessagedropped
password defaultnone (no such field)none, on purpose
id in a multi-template treeraw<version id>/<id>

How a question becomes a prompt

  1. The init call returns a question reply; the CLI maps its JSON to a Question value of one of the six kinds.
  2. prompt_mapper builds an inquire prompt: message, help from desc, and the kind's extras. A date's default, minDate and maxDate are parsed as %Y-%m-%d; a bad one is an error for the whole loop.
  3. For text, password and date, a validator is attached that makes a validate call per attempt.
  4. Every prompt is shown with prompt_skippable: the user can type an answer or press Esc.
  5. An answer is stored under the question id; Esc is a skip (next section).

Here is the real code, from the kind list to the prompt and the skip.

sulfone.iridiumcyanprompt/src/domain/models/question.rs
  1. lines 18-26Exactly six kinds; each variant holds its own struct with an id.
    cyanprompt/src/domain/models/question.rs:18-26rust
    #[derive(Clone, Debug)]
    pub enum Question {
    Confirm(ConfirmQuestion),
    Date(DateQuestion),
    Checkbox(CheckboxQuestion),
    Password(PasswordQuestion),
    Text(TextQuestion),
    Select(SelectQuestion),
    }
  2. sulfone.iridium/cyanprompt/src/http/mapper.rs:103-123Date: default, min and max are parsed as %Y-%m-%d; a parse error fails the mapping, so the loop ends with Err.
    cyanprompt/src/http/mapper.rs:103-123rust
    .and_then(|p| {
    date.default.as_ref().map_or(Ok(p.clone()), |s| {
    NaiveDate::parse_from_str(s, "%Y-%m-%d")
    .map(|e| p.with_default(e))
    .map_err(|e| Box::new(e) as Box<dyn std::error::Error + Send>)
    })
    })
    .and_then(|p| {
    date.min_date.as_ref().map_or(Ok(p.clone()), |s| {
    NaiveDate::parse_from_str(s, "%Y-%m-%d")
    .map(|e| p.with_min_date(e))
    .map_err(|e| Box::new(e) as Box<dyn std::error::Error + Send>)
    })
    })
    .and_then(|p| {
    date.max_date.as_ref().map_or(Ok(p.clone()), |s| {
    NaiveDate::parse_from_str(s, "%Y-%m-%d")
    .map(|e| p.with_max_date(e))
    .map_err(|e| Box::new(e) as Box<dyn std::error::Error + Send>)
    })
    })
  3. sulfone.iridium/cyanprompt/src/http/mapper.rs:132-149Password: masked; confirmation false turns the second entry off, true or null keeps it.
    cyanprompt/src/http/mapper.rs:132-149rust
    Question::Password(pw) => {
    Ok(inquire::Password::new(&pw.message).with_display_mode(PasswordDisplayMode::Masked))
    .map(|p| {
    pw.desc
    .as_ref()
    .map_or(p.clone(), |desc| p.with_help_message(desc))
    })
    .map(|p| {
    pw.confirmation.map_or(p.clone(), |confirm| {
    if confirm {
    p.clone()
    } else {
    p.without_confirmation()
    }
    })
    })
    .map(Prompts::Password)
    }
  4. sulfone.iridium/cyanprompt/src/domain/services/prompter.rs:4-21Every kind is shown skippable; Esc gives None, an answer gives the kind's Answer variant.
    cyanprompt/src/domain/services/prompter.rs:4-21rust
    pub fn prompt(p: Prompts) -> Result<Option<Answer>, Box<dyn std::error::Error + Send>> {
    match p {
    Prompts::Text(text) => text
    .prompt_skippable()
    .map_err(|e| Box::new(e) as Box<dyn std::error::Error + Send>)
    .map(|a| a.map(Answer::String)),
    Prompts::Confirm(cfm) => cfm
    .prompt_skippable()
    .map_err(|e| Box::new(e) as Box<dyn std::error::Error + Send>)
    .map(|a| a.map(Answer::Bool)),
    Prompts::Checkbox(cb) => cb
    .prompt_skippable()
    .map_err(|e| Box::new(e) as Box<dyn std::error::Error + Send>)
    .map(|a| a.map(Answer::StringArray)),
    Prompts::Select(s) => s
    .prompt_skippable()
    .map_err(|e| Box::new(e) as Box<dyn std::error::Error + Send>)
    .map(|a| a.map(Answer::String)),
  5. sulfone.iridium/cyanprompt/src/domain/services/template/engine.rs:48-51The id of the question being asked is remembered as last_question_id.
    cyanprompt/src/domain/services/template/engine.rs:48-51rust
    TemplateOutput::QnA(q) => {
    // Get ID from the Question struct using pattern matching
    let question_id = &q.question.id();
    last_question_id = Some(question_id.clone());
  6. sulfone.iridium/cyanprompt/src/domain/services/template/engine.rs:64-77Esc with no answers ends the process; otherwise it removes the current id (normally absent). An answer is stored under the id.
    cyanprompt/src/domain/services/template/engine.rs:64-77rust
    .map(|x| match x {
    // if skipped
    None => {
    if answers.is_empty() {
    println!("User aborted! Exiting...");
    exit(0)
    } else if let Some(last_id) = &last_question_id {
    answers.remove(last_id);
    }
    }
    Some(val) => {
    answers.insert(question_id.clone(), val);
    state_data = q.deterministic_state;
    }

Worked example: Esc during cyanprint create atomi/web:5 ./shop

The run order is docker:7, lint:2, node-base:3, web:5, and each runs its own question loop. Step through what Esc does at two points.

Pressing Esc during the first create of ./shop
  1. docker:7 asks node_version

    docker:7 is the first node and nothing feeds it answers, so its answer map is empty.

    nodedocker:7
    answer map{}
    askednode_version
  2. Esc at node_version

    The map is empty, so the engine prints 'User aborted! Exiting...' and calls exit(0). ./shop is left behind, empty, and the warmed session is not released.

    nodedocker:7
    exit code0
    ./shopexists, empty
    sessionleft for the coordinator's own cleanup
  3. Run again; web:5 asks port

    This time node_version is 22. lint:2 asks nothing; node-base:3's module_type is preset. web:5 asks name, then port.

    nodeweb:5
    answer mapnode_version, module_type, name
    askedport
  4. Esc at port

    The map is not empty, so the engine removes 'port' from it. 'port' was never there: nothing changes. name stays answered.

    nodeweb:5
    answer mapnode_version, module_type, name
    removedport (absent)
  5. Next init call

    The same answers replay to the same place: port is asked again.

    nodeweb:5
    askedport
    way outanswer, or Ctrl-C (Err outcome)

Why it is built this way

Hard cases

  • Esc is not "back". The remembered id is the current question's, so Esc never removes an earlier answer. To change an earlier answer the user must quit and run again.
  • Esc on an empty map exits with code 0. Scripts that wrap cyanprint create see success. The created folder stays, empty, and the session is not released.
  • Ctrl-C is an error, not a skip. inquire returns an interruption error; the loop ends with the Err prompt outcome.
  • Esc can trap the user. Esc exits only when the answer map is empty. From the second node of a tree on, the map already holds earlier nodes' answers (web:5's holds node_version and module_type), and any node with a preset or saved answer starts non-empty. There Esc never leaves the loop: the same question is asked again. Only Ctrl-C ends the run (next bullet). Found while reading; not run.
  • Ctrl-C leaves a folder behind and exits 0. The Err outcome makes the executor release the warmed session (executor.rs:268), but cyan_run still returns the error to main, which prints Error: and returns success (main.rs:458-463, exit 0). The folder made at run.rs:525 stays, because the folder guard removes anything only in headless runs (run.rs:419-425). Esc's leftovers are the other case, above. Found while reading; not run.
  • Bad date metadata. Interactive: a minDate that does not parse as %Y-%m-%d ends the loop with an error. Headless: the same bad bound is ignored and the answer is accepted.
  • Dates and time zones (Node SDK). The Node SDK writes date fields with toISOString().split('T')[0], which is the UTC date. A Date built at local midnight east of UTC is sent as the day before. Found while reading; not run.
  • Confirm's error text is shown interactively only; the headless envelope has no field for it.
  • A repeated id in one script is answered by the first answer. The check is on the answer type, not the kind. In the Node SDK text, select, password and date all read a String (stateless_inquirer.ts:84,108,128,148), so a select that reuses a text id silently takes the text answer, even a value that is not one of its options. Only a pair with different answer types (text, then checkbox) fails, with an ordinary SDK error (wrong answer type), not a new question.

Questions for the designer

  1. Should Esc go back to the previous question, as the design's "going back to change previous answers" suggests, or re-ask the current one as the code does?
  2. Should select, checkbox and confirm accept a validator?
  3. Should Esc on the first question exit with a non-zero code and release the session?
  4. Should interactive and headless treat a malformed date bound the same way, and which way?
  5. Esc is meant to skip a question, but it only exits on an empty map. Should Esc ever end the run after the first node, and should Ctrl-C exit non-zero and remove the created folder?
  6. Should a repeated id with the same answer type be rejected when the script is built, instead of sharing one answer?