Question
The six kinds of question a template can ask, their fields and ids, how each becomes a terminal prompt, and what Esc does.
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"]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 fields | Terminal prompt | Answer |
|---|---|---|---|
text | default, initial, validator | free text; default shown, initial pre-filled | String |
password | confirmation, validator | masked input; asks twice unless confirmation: false | String |
select | options | pick one from the list | String |
checkbox | options | pick any number from the list | StringArray |
confirm | default, errorMessage | yes/no; errorMessage shows on a bad y/n | Bool |
date | default, minDate, maxDate, validator | calendar picker, bounded | String 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_inputgets 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):
{ "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):
{ "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:
| Field | Question reply (HTTP) | Headless envelope |
|---|---|---|
| date bounds | minDate, maxDate | min_date, max_date |
| confirm error text | errorMessage | dropped |
| password default | none (no such field) | none, on purpose |
| id in a multi-template tree | raw | <version id>/<id> |
How a question becomes a prompt
- The init call returns a question reply; the CLI maps its JSON to a
Questionvalue of one of the six kinds. prompt_mapperbuilds an inquire prompt: message, help fromdesc, and the kind's extras. A date'sdefault,minDateandmaxDateare parsed as%Y-%m-%d; a bad one is an error for the whole loop.- For text, password and date, a validator is attached that makes a validate call per attempt.
- Every prompt is shown with
prompt_skippable: the user can type an answer or press Esc. - 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.
- 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),} - 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>)})}) - 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)} - 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)), - 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 matchinglet question_id = &q.question.id();last_question_id = Some(question_id.clone()); - 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 skippedNone => {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.
- docker:7 asks node_version
docker:7 is the first node and nothing feeds it answers, so its answer map is empty.
node docker:7answer map {}asked node_version - 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.
node docker:7exit code 0./shop exists, emptysession left for the coordinator's own cleanup - 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.
node web:5answer map node_version, module_type, nameasked port - Esc at port
The map is not empty, so the engine removes 'port' from it. 'port' was never there: nothing changes. name stays answered.
node web:5answer map node_version, module_type, nameremoved port (absent) - Next init call
The same answers replay to the same place: port is asked again.
node web:5asked portway out answer, 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 createsee 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_versionandmodule_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), butcyan_runstill returns the error tomain, which printsError:and returns success (main.rs:458-463, exit 0). The folder made atrun.rs:525stays, 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
minDatethat does not parse as%Y-%m-%dends 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. ADatebuilt 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 aselectthat reuses atextid 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
- 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?
- Should select, checkbox and confirm accept a validator?
- Should Esc on the first question exit with a non-zero code and release the session?
- Should interactive and headless treat a malformed date bound the same way, and which way?
- 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?
- Should a repeated id with the same answer type be rejected when the script is built, instead of sharing one answer?