Doc system test

UL

Words: prompting

Namespace: durian.cloud/cyanprint/prompting

How the CLI gets a template's answers - the question loop between the CLI and one template container, interactive or headless. The CLI holds every answer; the container holds none.

WordMeaning
QuestionOne thing a template script asks - text, password, select, checkbox, confirm or date - with a question id, a message and optional extras.
Question idThe string a question's answer is stored under - in the answer map, the answers file, the state file and the node cache.
AnswerThe value for one question id - a String, a StringArray or a Bool - written { type, value } in files and { type, answer } on the wire.
Answer mapEvery answer known so far in one run, keyed by question id; the CLI sends the whole map on every init call.
Stateless replayAsking a template's questions by running its script from the top on every call, with every answer so far, until it stops at an unanswered one.
Init callOne POST to a template's /api/template/init with the answer map and the deterministic state; it returns a question reply or a final reply.
Validate callOne POST to a template's /api/template/validate; the template replays to its first unanswered question and runs its validator on a candidate.
Question replyAn init call's answer when the script stopped at an unanswered question - type: questionnaire, the question, and the deterministic state so far.
Final replyAn init call's answer when every question was answered - type: final and the Cyan, with no deterministic state.
Checkpoint exceptionThe exception an SDK's inquirer throws when the script asks a question whose id is not in the answer map; the SDK turns it into a question reply.
Deterministic stateThe map of values a template made with d.get (a UUID, a date) that the CLI passes back on every init call, so one run sees one value.
Prompt outcomeHow one template's question loop ends - Complete (Cyan and answers), NeedInput (headless, a question), or Err (a message).
Headless modeRunning create, update or try with --headless - answers from a file or stdin, no prompts, one JSON envelope on stdout, exit 0/2/1.
Answers fileThe headless input - one JSON object of question id to { type, value }, read from --answers <path> or piped stdin.
EnvelopeThe one JSON object a headless run prints on stdout - {status: done}, {status: need_input, question} or {status: error, message}.
Need inputThe headless outcome when a replay reaches a question with no supplied answer - the run stops before any file is written.
Answer validationChecking an answer before it is used - the template's own validator through a validate call for text, password and date, local shape checks for the rest.
Discovery walkThe first of two headless walks - feed supplied answers one question at a time so each reached answer is validated.
Outcome walkThe second headless walk - send the full supplied map from empty state and stop at need input, the final reply, or an error.
Revealed answersThe supplied answers whose question the discovery walk actually reached; the engine returns these, not the whole answers file.
Secret redactionKeeping supplied answer values out of headless error messages and password defaults out of the envelope.
SkipPressing Esc at an interactive prompt - removes the asked question's answer (normally absent) so the next replay asks it again.

Question

One thing a template script asks - text, password, select, checkbox, confirm or date - with a question id, a message and optional extras.

  • In code: Question (cyanprompt), QuestionRes, QuestionWire, TextQ and SelectQ etc. (SDKs)
  • See: Question id, Answer, Question reply

Six kinds, fixed. Each kind has its own extra fields (default, initial, options, min/max date, confirmation, error message). A question exists only while a replay is stopped at it: the template sends it in a question reply; it is never stored. Only text, password and date questions carry a validator (a function in the template, never sent over the wire).

Example: web:5 asks name (text), port (text, default "3000", validator) and features (checkbox: docker, storybook).

Not to be confused with:

  • prompt: the terminal widget (inquire) the CLI builds from a question
  • need input: the headless outcome that carries a question

Question id

The string a question's answer is stored under - in the answer map, the answers file, the state file and the node cache.

  • Do not say: key, question name
  • See: Answer

Chosen by the template author. The only link between a question and its answer: kinds are never compared on the way in. Two questions with one id share one answer. In a composition with more than one executable node, a question surfaced in need input is prefixed <version id>/ (answer namespacing).

Example: name in web:5; surfaced headless as e5d07b3a-2f1e-4d3c-9b8a-7f6e5d4c3b2a/name because web:5's tree has four executable nodes.

Not to be confused with:

  • deterministic state key: the key of a d.get value, a separate map
  • version id: the GUID of a template version

Answer

The value for one question id - a String, a StringArray or a Bool - written { type, value } in files and { type, answer } on the wire.

  • Do not say: response, input
  • In code: Answer, AnswerReq, AnswerRes
  • See: Question id

Three spellings of one value: state file, answers file and node cache use {type: String|StringArray|Bool, value}; the HTTP calls to a template use {type: string|str_array|boolean, answer}; preset answers in cyan.yaml are plain YAML. Text, password, select and date give a String (date as YYYY-MM-DD); checkbox gives a StringArray; confirm gives a Bool.

Example: name: { type: String, value: shop }, features: { type: StringArray, value: [docker] }.

Answer map

Every answer known so far in one run, keyed by question id; the CLI sends the whole map on every init call.

  • In code: answers (TemplateEngine), TemplateAnswerInput.answers
  • See: Stateless replay

Starts from saved answers, preset answers and answers carried from earlier nodes; grows by one per question reply. Answers are looked up, never consumed, so extra keys are harmless to the template and are sent along.

Example: Before web:5 asks name: { node_version: 22, module_type: esm }.

Stateless replay

Asking a template's questions by running its script from the top on every call, with every answer so far, until it stops at an unanswered one.

  • Also called: client-state prompting
  • Do not say: session, conversation, wizard
  • In code: TemplateEngine::start_with, TemplateService.template
  • See: Question reply, Final reply, Checkpoint exception

The CLI keeps the answer map and the deterministic state; the template keeps nothing between calls. A script with N questions runs N+1 times (plus one replay per validation). Code before a question runs again on every call.

Example: web:5 (3 questions) gets four init calls; d.get("instance-id") runs in all four.

Init call

One POST to a template's /api/template/init with the answer map and the deterministic state; it returns a question reply or a final reply.

  • In code: CyanClient::prompt_template, TemplateAnswerReq
  • See: Validate call

Sent through the coordinator's proxy route /proxy/template/<version id>/api/template/init. Request field deterministicStates (plural).

Example: {"answers":{"name":{"type":"string","answer":"shop"}},"deterministicStates":{}}

Validate call

One POST to a template's /api/template/validate; the template replays to its first unanswered question and runs its validator on a candidate.

  • In code: CyanClient::validate_template, TemplateValidateReq
  • See: Answer validation

Carries no question id: the answer map must stop the replay at the right question. Reply { "valid": null } means accepted, { "valid": "<reason>" } means refused. A JSON body with no valid key (a coordinator error, a Python {"error": ...}) also decodes as accepted (bug).

Example: Checking port 80 for web:5: answers {node_version, module_type, name}, validate: "80" → { "valid": "Use a port from 1024 to 65535" }.

Question reply

An init call's answer when the script stopped at an unanswered question - type: questionnaire, the question, and the deterministic state so far.

  • In code: TemplateQnARes, TemplateOutput::QnA
  • See: Final reply

Made when the script throws the checkpoint exception. Field deterministicState (singular). HTTP 200, never an error status.

Example: { "type": "questionnaire", "question": { "type": "text", "id": "port", ... }, "deterministicState": { "instance-id": "4f9c2e71-aaaa" } }

Final reply

An init call's answer when every question was answered - type: final and the Cyan, with no deterministic state.

  • In code: TemplateFinalRes, TemplateOutput::Final
  • See: Deterministic state

Values the script made with d.get after its last question, and the whole map, go nowhere: the reply has no field for them.

Example: { "type": "final", "cyan": { "processors": [ ... ], "plugins": [] } }

Checkpoint exception

The exception an SDK's inquirer throws when the script asks a question whose id is not in the answer map; the SDK turns it into a question reply.

  • Do not say: interrupt, pause
  • In code: OutOfAnswerException
  • See: Question reply

Named OutOfAnswerException in all three SDKs. It unwinds the author's script mid-run, so the script never waits for a person. Any other exception is a real error and is not caught by the template service.

Example: web:5's script reaches i.text(... 'port' ...) with no port answer: OutOfAnswerException carries the port question.

Deterministic state

The map of values a template made with d.get (a UUID, a date) that the CLI passes back on every init call, so one run sees one value.

  • Do not say: pin, seed, cache
  • In code: deterministicStates (request), deterministicState (reply), state_data, deterministic_states (history entry)
  • See: Stateless replay

Key to string. Made in the template, carried by the CLI between calls of one template's Q&A only. Lost at four places: the final reply has none, the Complete prompt outcome has none, the state writer saves {}, and a headless walk starts from {}.

Example: web:5 makes instance-id: 4f9c2e71-aaaa on its first init call; calls two to four send it back.

Not to be confused with:

  • determinism helper: the SDK function d.get that reads and writes this map (authoring)
  • state file: the project's saved record; its deterministic_states field is always {}
  • try's deterministic states count: a map of the String answers, printed as a number; not d.get values

Prompt outcome

How one template's question loop ends - Complete (Cyan and answers), NeedInput (headless, a question), or Err (a message).

  • Do not say: template state, result
  • In code: TemplateState (cyanprompt)
  • See: Need input

A fourth value, QnA, means "still asking" and never leaves the loop. Code name TemplateState in cyanprompt, which is also the name of a state file type in cyancoordinator: say "prompt outcome" or "template record".

Example: web:5 interactive: Complete with the Cyan and {node_version, module_type, name, port, features}.

Not to be confused with:

  • template record: the state file entry, also called TemplateState in code

Headless mode

Running create, update or try with --headless - answers from a file or stdin, no prompts, one JSON envelope on stdout, exit 0/2/1.

  • Do not say: batch mode, CI mode
  • In code: start_headless, finish_headless, HeadlessEnvelope
  • See: Answers file, Envelope, Need input

The caller loops: run, read the envelope, add the asked answer, run again. Each run is a fresh replay of the whole batch. --headless and --interactive cannot be combined on update.

Example: cyanprint create atomi/web:5 ./shop --headless --answers answers.json exits 2 with the node_version question first.

Answers file

The headless input - one JSON object of question id to { type, value }, read from --answers <path> or piped stdin.

  • Do not say: answer file, input file
  • In code: parse_answers, read_answers_from
  • See: Headless mode

Same answer spelling as the state file. Empty or blank input means no answers. No flat shorthand, no YAML, no deterministic state. --answers - is a file named -, not stdin.

Example: { "name": { "type": "String", "value": "shop" } }

Envelope

The one JSON object a headless run prints on stdout - {status: done}, {status: need_input, question} or {status: error, message}.

  • Also called: headless envelope
  • Do not say: response, output
  • In code: HeadlessEnvelope, QuestionWire, emit_to
  • See: Need input

Exit codes 0, 2 and 1. done carries nothing else, never the answers. Today a create or update with the node cache on prints a cache line on stdout before it.

Example: {"status":"need_input","question":{"type":"text","id":"e5d0…/name",...}} then exit 2.

Need input

The headless outcome when a replay reaches a question with no supplied answer - the run stops before any file is written.

  • Do not say: missing answer, prompt
  • In code: TemplateState::NeedInput, CompositionState.need_input
  • See: Envelope

Envelope need_input, exit 2. The rest of the batch is not run; a target folder this run created is removed; sessions are released.

Example: First headless create of web:5 with an empty answers file: need input for docker:7's node_version.

Answer validation

Checking an answer before it is used - the template's own validator through a validate call for text, password and date, local shape checks for the rest.

  • In code: add_template_validator, validate_answer, validateable_value
  • See: Discovery walk, Validate call

Interactive: inquire runs the validator when the user presses Enter; answers already in the map at the start are never validated. Headless: a discovery walk validates every supplied answer the replay reaches, before the outcome walk. The validator's sibling map is the whole map interactively, but only the answers this node revealed so far in headless (bug).

Example: Typing 80 for web:5's port shows Use a port from 1024 to 65535 and the prompt stays open.

Discovery walk

The first of two headless walks - feed supplied answers one question at a time so each reached answer is validated.

  • In code: validate_supplied_answers
  • See: Outcome walk

Starts from an empty map and empty state, adds an answer only when its question is asked. Stops at the first question with no supplied answer, or at the final reply. Returns the revealed answers; the engine hands only those back as the node's answers, but the batch run then saves the whole supplied map (bug, see headless mode).

Example: Answers for docker:7 {node_version: 22}: call 1 asks node_version (checked: 22 is an option), call 2 is final.

Outcome walk

The second headless walk - send the full supplied map from empty state and stop at need input, the final reply, or an error.

  • In code: start_headless
  • See: Discovery walk

With the SDKs' first-unanswered behaviour this is usually one init call. Deterministic state from discovery is not passed on.

Example: docker:7 with {node_version: 22}: one init call returns the final reply.

Revealed answers

The supplied answers whose question the discovery walk actually reached; the engine returns these, not the whole answers file.

  • In code: revealed (start_headless)

Over-supplied ids and answers for branches not taken are dropped from what the engine returns. The batch run then saves the whole supplied map anyway, so a stale value still lands in the state file (bug).

Example: Supplying {node_version: 22, colour: blue} to docker:7: the engine returns node_version only; the run still saves colour.

Secret redaction

Keeping supplied answer values out of headless error messages and password defaults out of the envelope.

  • Do not say: masking, encryption
  • In code: redact_coordinator_message, InFlightAnswers, value_echoed
  • See: Answer validation

Covers three paths only: answers-file parse errors, validation refusals, and init call errors during a headless walk.

Example: A refused password npm_token gives invalid answer for question 'npm_token' with the template's reason dropped.

Skip

Pressing Esc at an interactive prompt - removes the asked question's answer (normally absent) so the next replay asks it again.

  • Do not say: go back, undo
  • In code: prompt_skippable, last_question_id

It does not go back to the previous question. With an empty answer map it ends the CLI at once with exit code 0; with a non-empty map (every node after the first) it never ends the run.

Example: Esc at web:5's port: port is not in the map, nothing changes, port is asked again.