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 a template container

WordMeaning
QuestionOne prompt a template asks - text, password, select, checkbox, confirm or date - with an id and an optional validator.
Question idThe key a question's answer is stored under - in the replay, in headless answers, and in the state file.
AnswerA value for one question - a string, a list of strings, or a boolean - stored as type and value.
Stateless replayEach step the CLI sends every answer so far and the template script runs again from the top until it meets an unanswered question.
Question replyA template's reply naming the next unanswered question, with the deterministic state built so far.
Final replyA template's reply when every question is answered - the Cyan, and no deterministic state.
Deterministic stateValues a template makes once with d.get (a UUID, a date) so they stay the same across the replays of one run.
Prompt outcomeHow one prompt run ends - complete (answers and Cyan), need input (headless), or error.
Headless modeRunning without a terminal - answers from a file or stdin, one JSON envelope on stdout, exit 0 done, 2 need input, 1 error.
Need inputThe headless outcome when the walk meets a question with no supplied answer; nothing is written.
Answer validationChecking an answer with the template's own validator, by replaying to that question inside the template container.
Secret redactionDropping any headless error text that echoes a supplied answer value, so a password never reaches the JSON envelope.

Question

One prompt a template asks - text, password, select, checkbox, confirm or date - with an id and an optional validator.

  • See: Question id, Answer

Code: Question (cyanprompt/src/domain/models/question.rs); SDK: Question in sdks/node/src/domain/core/question.ts. Example: await i.text('Project name?', 'name') asks a text question with id name.

Question id

The key a question's answer is stored under - in the replay, in headless answers, and in the state file.

  • Do not say: key

Two templates that use one id share one answer in a composition, unless the caller scopes it (answer namespacing). Example: id name answered shop is sent to every later template in the run.

Answer

A value for one question - a string, a list of strings, or a boolean - stored as type and value.

Code: Answer enum, serde tag type, content value (cyanprompt/src/domain/models/answer.rs:4-10). Example: { type: Bool, value: true } for a confirm question.

Stateless replay

Each step the CLI sends every answer so far and the template script runs again from the top until it meets an unanswered question.

  • Do not say: session, conversation, wizard
  • See: Question reply, Final reply

Full walk-through: docs/domain/prompting/implementation/stateless-replay.md

Question reply

A template's reply naming the next unanswered question, with the deterministic state built so far.

Code: TemplateOutput::QnA / TemplateQnAOutput. The SDK sends it when the inquirer throws "out of answers".

Final reply

A template's reply when every question is answered - the Cyan, and no deterministic state.

  • See: Cyan

Code: TemplateOutput::Final. The Cyan is defined in the authoring words.

Deterministic state

Values a template makes once with d.get (a UUID, a date) so they stay the same across the replays of one run.

  • Do not say: pin, seed, determinism seed

A map of string to string. Returned with each question reply and sent back on the next step. It is not in the final reply and is saved empty in the state file, so a new run makes new values. Example: d.get('project-id', () => crypto.randomUUID()) gives the same UUID in steps 3 and 4 of one run.

Prompt outcome

How one prompt run ends - complete (answers and Cyan), need input (headless), or error.

  • Do not say: template state

Code name TemplateState (cyanprompt/src/domain/services/template/states.rs:7-18); that name is also a state file type.

Headless mode

Running without a terminal - answers from a file or stdin, one JSON envelope on stdout, exit 0 done, 2 need input, 1 error.

  • See: Need input

Flags --headless and --answers <file> on create, update, try template and try group. Example: a need-input run prints the question as JSON and exits 2; the caller adds the answer and runs again.

Need input

The headless outcome when the walk meets a question with no supplied answer; nothing is written.

Code: TemplateState::NeedInput, envelope need_input.

Answer validation

Checking an answer with the template's own validator, by replaying to that question inside the template container.

Call: POST /api/template/validate. An error text is shown to the user and the answer is refused.

Secret redaction

Dropping any headless error text that echoes a supplied answer value, so a password never reaches the JSON envelope.