@forgecart/cli 2.202609301225.0 → 2.202610020334.0

package/dist/src/question/prompt-arm.js

@@ -0,0 +1,263 @@
+import { GUTTER, defaultAnswer, gutterLine, questionHeader } from './util/question-frame.util.js';
+import { displayWidth, withoutLastGrapheme } from './util/terminal-text.util.js';
+const IGNORE = { kind: 'ignore' };
+const REDRAW = { kind: 'redraw' };
+/** The row a `both` question adds after its options; taking it opens the free-text buffer. */
+const OTHER_LABEL = 'Other…';
+/** The keys each arm takes, as its frame prints them under the rows (record `prompt`). */
+const SELECT_KEYS = '  ↑↓ · Enter';
+const MULTISELECT_KEYS = '  ↑↓ move · Space toggle · Enter confirm · none selected is a valid answer';
+const MULTILINE_KEYS = '└ Enter starts a new line · an empty line then Ctrl-D finishes · Ctrl-C aborts';
+/** Why Esc did not answer: a question without a default has no Esc arm. */
+const NO_DEFAULT_REASON = 'This question has no default, so Esc cannot answer it.';
+/** Why Ctrl-D did not answer: an empty answer is refused, never sent. */
+const EMPTY_ANSWER_REASON = 'An empty answer is refused — type it, then an empty line and Ctrl-D.';
+/** The first code point a terminal prints rather than acts on. */
+const FIRST_PRINTABLE_CODE_POINT = 0x20;
+/**
+ * One way of answering a question on a terminal, as a key-event reducer: each
+ * keypress returns the step it takes, and {@link frame} draws the state it
+ * leaves. Esc is the same everywhere — the question's declared default with
+ * `defaulted: true`, or, with none declared, a redraw that says why.
+ */
+export class PromptArm {
+    question;
+    constructor(question) {
+        this.question = question;
+    }
+    /** The arm a question opens on: the free-text buffer, a checklist or a list. */
+    static of(question) {
+        if (question.kind === 'text')
+            return new MultilineArm(question);
+        if (question.allowMultiple)
+            return new MultiselectArm(question);
+        return new SelectArm(question);
+    }
+    escape() {
+        const answer = defaultAnswer(this.question);
+        if (answer === undefined)
+            return { kind: 'refuse', reason: NO_DEFAULT_REASON };
+        return { kind: 'answer', answer };
+    }
+    /** The key line's Esc arm, naming the default it takes — none without a default. */
+    escapeHint() {
+        const fallback = this.question.options.find((option) => option.id === this.question.defaultOptionId);
+        return fallback === undefined ? '' : ` · Esc → default (${fallback.label})`;
+    }
+}
+/**
+ * A cursor list over a question's options, plus "Other…" on a `both` question.
+ * The `❯` is the cursor; ↑ and ↓ move it and wrap at either end.
+ */
+class ListArm extends PromptArm {
+    cursor = 0;
+    /** The row "Other…" stands on — past the last option. */
+    get otherRow() {
+        return this.question.options.length;
+    }
+    /** Every row's label, "Other…" last on a `both` question. */
+    rowLabels() {
+        const labels = this.question.options.map((option) => option.label);
+        return this.question.kind === 'both' ? [...labels, OTHER_LABEL] : labels;
+    }
+    move(step) {
+        const rows = this.rowLabels().length;
+        this.cursor = (this.cursor + step + rows) % rows;
+        return REDRAW;
+    }
+    marker(row) {
+        return row === this.cursor ? '❯' : ' ';
+    }
+}
+/**
+ * A single choice (record `prompt?case=select`): the hint under each label,
+ * Enter answers the option under the cursor, "Other…" opens the free-text
+ * buffer.
+ */
+class SelectArm extends ListArm {
+    press(key) {
+        switch (key.name) {
+            case 'up':
+                return this.move(-1);
+            case 'down':
+                return this.move(1);
+            case 'return':
+            case 'enter':
+                return this.choose();
+            case 'escape':
+                return this.escape();
+            default:
+                return IGNORE;
+        }
+    }
+    frame(columns) {
+        const rows = this.rowLabels().flatMap((label, row) => this.rowLines(label, row));
+        return {
+            lines: [
+                ...questionHeader(this.question, columns),
+                ...rows,
+                '',
+                `${SELECT_KEYS}${this.escapeHint()}`,
+            ],
+        };
+    }
+    rowLines(label, row) {
+        const line = `${this.marker(row)} ${label}`;
+        const hint = this.question.options.at(row)?.hint;
+        return hint === undefined ? [line] : [line, `    ${hint}`];
+    }
+    choose() {
+        const option = this.question.options.at(this.cursor);
+        if (option === undefined)
+            return { kind: 'open', arm: new MultilineArm(this.question) };
+        return { kind: 'answer', answer: { questionId: this.question.id, optionIds: [option.id] } };
+    }
+}
+/**
+ * Several choices (record `prompt?case=multiselect`): `◉` / `◯` carry what is
+ * chosen and the `❯` where the cursor is — two things that never move
+ * together. Space toggles the row under the cursor; Enter answers the whole
+ * set, and an empty set is an answer. With "Other…" ticked, Enter opens the
+ * free-text buffer and the ticked options ride along with the text.
+ */
+class MultiselectArm extends ListArm {
+    ticked = new Set();
+    press(key) {
+        switch (key.name) {
+            case 'up':
+                return this.move(-1);
+            case 'down':
+                return this.move(1);
+            case 'space':
+                return this.toggle();
+            case 'return':
+            case 'enter':
+                return this.confirm();
+            case 'escape':
+                return this.escape();
+            default:
+                return IGNORE;
+        }
+    }
+    frame(columns) {
+        const rows = this.rowLabels().map((label, row) => `${this.marker(row)} ${this.ticked.has(row) ? '◉' : '◯'} ${label}`);
+        return {
+            lines: [
+                ...questionHeader(this.question, columns),
+                ...rows,
+                '',
+                `${MULTISELECT_KEYS}${this.escapeHint()}`,
+            ],
+        };
+    }
+    toggle() {
+        if (this.ticked.has(this.cursor)) {
+            this.ticked.delete(this.cursor);
+            return REDRAW;
+        }
+        this.ticked.add(this.cursor);
+        return REDRAW;
+    }
+    confirm() {
+        const optionIds = this.question.options
+            .filter((_option, row) => this.ticked.has(row))
+            .map((option) => option.id);
+        if (this.ticked.has(this.otherRow)) {
+            return { kind: 'open', arm: new MultilineArm(this.question, optionIds) };
+        }
+        return { kind: 'answer', answer: { questionId: this.question.id, optionIds } };
+    }
+}
+/**
+ * Free text (record `prompt?case=multiline`): a buffer behind the `│` gutter.
+ * Enter starts a new line, because a terminal has no Answer button; Ctrl-D on
+ * an empty line finishes, and an empty buffer is refused rather than sent. The
+ * placeholder is drawn once as the prompt's example line, never as text inside
+ * the buffer.
+ */
+class MultilineArm extends PromptArm {
+    ticked;
+    /** The lines Enter has closed. */
+    lines = [];
+    /** The line being typed. */
+    current = '';
+    /**
+     * @param ticked the options ticked beside "Other…" on a checklist: they are
+     *   answered with the text; absent when the text is the whole answer.
+     */
+    constructor(question, ticked) {
+        super(question);
+        this.ticked = ticked;
+    }
+    press(key) {
+        if (key.name === 'escape')
+            return this.escape();
+        if (key.ctrl === true && key.name === 'd')
+            return this.finish();
+        if (key.name === 'return' || key.name === 'enter')
+            return this.newline();
+        if (key.name === 'backspace')
+            return this.erase();
+        const text = this.printable(key);
+        if (text === undefined)
+            return IGNORE;
+        this.current += text;
+        return REDRAW;
+    }
+    frame(columns) {
+        const { placeholder } = this.question;
+        const example = placeholder === undefined ? [] : [`  ${placeholder}`];
+        const above = [...questionHeader(this.question, columns), ...example, ''];
+        const buffer = [...this.lines, this.current].map(gutterLine);
+        return {
+            lines: [...above, ...buffer, `${MULTILINE_KEYS}${this.escapeHint()}`],
+            cursor: {
+                line: above.length + this.lines.length,
+                column: displayWidth(GUTTER) + 1 + displayWidth(this.current),
+            },
+        };
+    }
+    /** Ctrl-D: finishes only on an empty line, and never with an empty answer. */
+    finish() {
+        if (this.current !== '')
+            return IGNORE;
+        const text = this.lines.join('\n').trimEnd();
+        if (text === '')
+            return { kind: 'refuse', reason: EMPTY_ANSWER_REASON };
+        return { kind: 'answer', answer: this.answer(text) };
+    }
+    answer(text) {
+        if (this.ticked === undefined)
+            return { questionId: this.question.id, text };
+        return { questionId: this.question.id, optionIds: [...this.ticked], text };
+    }
+    newline() {
+        this.lines.push(this.current);
+        this.current = '';
+        return REDRAW;
+    }
+    /** Backspace: the last character, or — on an empty line — back onto the line above. */
+    erase() {
+        if (this.current !== '') {
+            this.current = withoutLastGrapheme(this.current);
+            return REDRAW;
+        }
+        const previous = this.lines.pop();
+        if (previous === undefined)
+            return IGNORE;
+        this.current = previous;
+        return REDRAW;
+    }
+    /**
+     * The character a keypress types — none for a chord, a control key or an
+     * escape sequence, each of which opens below the first printable code point.
+     */
+    printable(key) {
+        const { sequence } = key;
+        if (sequence === undefined || key.ctrl === true || key.meta === true)
+            return;
+        const lead = sequence.codePointAt(0) ?? 0;
+        return lead >= FIRST_PRINTABLE_CODE_POINT ? sequence : undefined;
+    }
+}
+//# sourceMappingURL=prompt-arm.js.map

package/dist/src/question/prompt-arm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-arm.js","sourceRoot":"","sources":["../../../src/question/prompt-arm.ts"],"names":[],"mappings":"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"}

package/dist/src/question/question-prompt.adapter.d.ts

@@ -0,0 +1,36 @@
+import { type Command } from 'commander';
+import type { QuestionPromptInput } from './type/question-prompt.input.js';
+import type { CliQuestion, QuestionPrompt, QuestionPromptAnswer, QuestionPromptIo } from './type/question-prompt.types.js';
+/**
+ * The ONE way a `forgecart` command asks its questions (#2771; record
+ * `refs/design/cli-improvements`, screen `prompt`).
+ *
+ * A question is answered by the run first — `--answer`, then `--answers-file`,
+ * then `--yes`'s default. One they leave open is asked on the terminal when
+ * stdin AND stdout are TTYs: a cursor list, a checklist or a free-text buffer.
+ * On anything else it is refused with exit 2, naming the question — a run
+ * without a terminal never waits for one.
+ */
+export declare class QuestionPromptAdapter implements QuestionPrompt {
+    private readonly flags;
+    private readonly io;
+    /**
+     * @param flags the command's parsed `--answer`, `--answers-file` and `--yes`.
+     * @param io the terminal to ask on.
+     */
+    constructor(flags: QuestionPromptInput, io?: QuestionPromptIo);
+    /**
+     * Register the three flags on a command whose questions this adapter asks.
+     * They stay out of `--help`: which questions a run asks is decided at run
+     * time, so the flags are taught where they apply — a run that leaves a
+     * question unanswered is told all three beside the question's id.
+     */
+    static registerOptions(command: Command): Command;
+    /** Answer `questions`, in their order — from the run's flags, or on the terminal. */
+    ask(questions: readonly CliQuestion[]): Promise<QuestionPromptAnswer[]>;
+    private askOnTerminal;
+    /** A prompt renders only when both ends are a terminal: a TTY to read and a TTY to draw on. */
+    private isTerminal;
+    /** A choice needs options to choose from, and a default must be one of them. */
+    private static assertAskable;
+}

package/dist/src/question/question-prompt.adapter.js

@@ -0,0 +1,81 @@
+import { Option } from 'commander';
+import { GivenAnswers } from './given-answers.js';
+import { QuestionUnansweredRefusal } from './question-unanswered-refusal.js';
+import { TerminalQuestionSession } from './terminal-question-session.js';
+import { collectAnswerFlag } from './util/answer-flag.util.js';
+/**
+ * The ONE way a `forgecart` command asks its questions (#2771; record
+ * `refs/design/cli-improvements`, screen `prompt`).
+ *
+ * A question is answered by the run first — `--answer`, then `--answers-file`,
+ * then `--yes`'s default. One they leave open is asked on the terminal when
+ * stdin AND stdout are TTYs: a cursor list, a checklist or a free-text buffer.
+ * On anything else it is refused with exit 2, naming the question — a run
+ * without a terminal never waits for one.
+ */
+export class QuestionPromptAdapter {
+    flags;
+    io;
+    /**
+     * @param flags the command's parsed `--answer`, `--answers-file` and `--yes`.
+     * @param io the terminal to ask on.
+     */
+    constructor(flags, io = { input: process.stdin, output: process.stdout }) {
+        this.flags = flags;
+        this.io = io;
+    }
+    /**
+     * Register the three flags on a command whose questions this adapter asks.
+     * They stay out of `--help`: which questions a run asks is decided at run
+     * time, so the flags are taught where they apply — a run that leaves a
+     * question unanswered is told all three beside the question's id.
+     */
+    static registerOptions(command) {
+        return command
+            .addOption(new Option('--answer <question=answer>', 'Answer a question without a terminal: its id or key, then an option id, comma-separated option ids, or the text (repeatable)')
+            .argParser(collectAnswerFlag)
+            .hideHelp())
+            .addOption(new Option('--answers-file <path>', 'Answer questions from a JSON object of question ids or keys to option ids or text').hideHelp())
+            .addOption(new Option('--yes', "Take each question's default; a question without one still needs an answer").hideHelp());
+    }
+    /** Answer `questions`, in their order — from the run's flags, or on the terminal. */
+    async ask(questions) {
+        for (const question of questions)
+            QuestionPromptAdapter.assertAskable(question);
+        const given = await GivenAnswers.from(this.flags);
+        const resolved = questions.map((question) => ({ question, answer: given.answerFor(question) }));
+        const open = resolved
+            .filter(({ answer }) => answer === undefined)
+            .map(({ question }) => question);
+        const asked = new Map();
+        if (open.length > 0) {
+            for (const answer of await this.askOnTerminal(open))
+                asked.set(answer.questionId, answer);
+        }
+        return resolved
+            .map(({ question, answer }) => answer ?? asked.get(question.id))
+            .filter((answer) => answer !== undefined);
+    }
+    async askOnTerminal(questions) {
+        if (!this.isTerminal())
+            throw new QuestionUnansweredRefusal(questions);
+        return new TerminalQuestionSession(this.io, questions).run();
+    }
+    /** A prompt renders only when both ends are a terminal: a TTY to read and a TTY to draw on. */
+    isTerminal() {
+        return this.io.input.isTTY === true && this.io.output.isTTY === true;
+    }
+    /** A choice needs options to choose from, and a default must be one of them. */
+    static assertAskable(question) {
+        if (question.kind !== 'text' && question.options.length === 0) {
+            throw new Error(`Question ${question.id} is a ${question.kind} question without options.`);
+        }
+        const { defaultOptionId } = question;
+        if (defaultOptionId === undefined)
+            return;
+        if (question.options.some((option) => option.id === defaultOptionId))
+            return;
+        throw new Error(`Question ${question.id} defaults to ${defaultOptionId}, which is none of its options.`);
+    }
+}
+//# sourceMappingURL=question-prompt.adapter.js.map

package/dist/src/question/question-prompt.adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-prompt.adapter.js","sourceRoot":"","sources":["../../../src/question/question-prompt.adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAgB,MAAM,WAAW,CAAC;AAEjD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAQzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAE/D;;;;;;;;;GASG;AACH,MAAM,OAAO,qBAAqB;IAMb;IACA;IANnB;;;OAGG;IACH,YACmB,KAA0B,EAC1B,KAAuB,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;QADvE,UAAK,GAAL,KAAK,CAAqB;QAC1B,OAAE,GAAF,EAAE,CAAqE;IACvF,CAAC;IAEJ;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,OAAgB;QACrC,OAAO,OAAO;aACX,SAAS,CACR,IAAI,MAAM,CACR,4BAA4B,EAC5B,8HAA8H,CAC/H;aACE,SAAS,CAAC,iBAAiB,CAAC;aAC5B,QAAQ,EAAE,CACd;aACA,SAAS,CACR,IAAI,MAAM,CACR,uBAAuB,EACvB,mFAAmF,CACpF,CAAC,QAAQ,EAAE,CACb;aACA,SAAS,CACR,IAAI,MAAM,CACR,OAAO,EACP,4EAA4E,CAC7E,CAAC,QAAQ,EAAE,CACb,CAAC;IACN,CAAC;IAED,qFAAqF;IACrF,KAAK,CAAC,GAAG,CAAC,SAAiC;QACzC,KAAK,MAAM,QAAQ,IAAI,SAAS;YAAE,qBAAqB,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAChF,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAClD,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;QAChG,MAAM,IAAI,GAAG,QAAQ;aAClB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,KAAK,SAAS,CAAC;aAC5C,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC;QACnC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAgC,CAAC;QACtD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,KAAK,MAAM,MAAM,IAAI,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;gBAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QAC5F,CAAC;QACD,OAAO,QAAQ;aACZ,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,IAAI,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;aAC/D,MAAM,CAAC,CAAC,MAAM,EAAkC,EAAE,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC;IAC9E,CAAC;IAEO,KAAK,CAAC,aAAa,CAAC,SAAiC;QAC3D,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE;YAAE,MAAM,IAAI,yBAAyB,CAAC,SAAS,CAAC,CAAC;QACvE,OAAO,IAAI,uBAAuB,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC,GAAG,EAAE,CAAC;IAC/D,CAAC;IAED,+FAA+F;IACvF,UAAU;QAChB,OAAO,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,CAAC;IACvE,CAAC;IAED,gFAAgF;IACxE,MAAM,CAAC,aAAa,CAAC,QAAqB;QAChD,IAAI,QAAQ,CAAC,IAAI,KAAK,MAAM,IAAI,QAAQ,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9D,MAAM,IAAI,KAAK,CAAC,YAAY,QAAQ,CAAC,EAAE,SAAS,QAAQ,CAAC,IAAI,4BAA4B,CAAC,CAAC;QAC7F,CAAC;QACD,MAAM,EAAE,eAAe,EAAE,GAAG,QAAQ,CAAC;QACrC,IAAI,eAAe,KAAK,SAAS;YAAE,OAAO;QAC1C,IAAI,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,KAAK,eAAe,CAAC;YAAE,OAAO;QAC7E,MAAM,IAAI,KAAK,CACb,YAAY,QAAQ,CAAC,EAAE,gBAAgB,eAAe,iCAAiC,CACxF,CAAC;IACJ,CAAC;CACF"}

package/dist/src/question/question-unanswered-refusal.d.ts

@@ -0,0 +1,15 @@
+import { CliRefusal } from '../exit-ladder.js';
+import type { CliQuestion } from './type/question-prompt.types.js';
+/**
+ * Questions a run neither answered nor could ask — exit
+ * {@link CliExitLadder.questionUnanswered}, never a hang (record
+ * `prompt?case=headless`). One line per question, naming it by the id
+ * `--answer` takes and the three flags that answer it; `--yes` is offered only
+ * where a default exists for it to take.
+ */
+export declare class QuestionUnansweredRefusal extends CliRefusal {
+    constructor(questions: readonly CliQuestion[]);
+    private static lineFor;
+    /** What `--answer` would carry: the declared default, or the shape an answer takes. */
+    private static exampleFor;
+}

package/dist/src/question/question-unanswered-refusal.js

@@ -0,0 +1,35 @@
+import { CliExitLadder, CliRefusal } from '../exit-ladder.js';
+/** The answers file a refusal points a headless run at. */
+const ANSWERS_FILE = 'answers.json';
+/**
+ * Questions a run neither answered nor could ask — exit
+ * {@link CliExitLadder.questionUnanswered}, never a hang (record
+ * `prompt?case=headless`). One line per question, naming it by the id
+ * `--answer` takes and the three flags that answer it; `--yes` is offered only
+ * where a default exists for it to take.
+ */
+export class QuestionUnansweredRefusal extends CliRefusal {
+    constructor(questions) {
+        super(CliExitLadder.questionUnanswered, questions.map((question) => QuestionUnansweredRefusal.lineFor(question)));
+        this.name = 'QuestionUnansweredRefusal';
+    }
+    static lineFor(question) {
+        const unanswered = `question ${question.id} "${question.question}" needs an answer`;
+        const answer = `--answer ${question.id}=${QuestionUnansweredRefusal.exampleFor(question)}`;
+        if (question.defaultOptionId === undefined) {
+            return `${unanswered} — pass ${answer} or --answers-file ${ANSWERS_FILE} (--yes cannot answer it: it has no default)`;
+        }
+        return `${unanswered} — pass ${answer}, --answers-file ${ANSWERS_FILE} or --yes`;
+    }
+    /** What `--answer` would carry: the declared default, or the shape an answer takes. */
+    static exampleFor(question) {
+        if (question.defaultOptionId !== undefined)
+            return question.defaultOptionId;
+        if (question.kind === 'text')
+            return '<text>';
+        if (question.kind === 'both')
+            return '<optionId|text>';
+        return question.allowMultiple ? '<optionId,…>' : '<optionId>';
+    }
+}
+//# sourceMappingURL=question-unanswered-refusal.js.map

package/dist/src/question/question-unanswered-refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-unanswered-refusal.js","sourceRoot":"","sources":["../../../src/question/question-unanswered-refusal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAI9D,2DAA2D;AAC3D,MAAM,YAAY,GAAG,cAAc,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,OAAO,yBAA0B,SAAQ,UAAU;IACvD,YAAY,SAAiC;QAC3C,KAAK,CACH,aAAa,CAAC,kBAAkB,EAChC,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,yBAAyB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CACzE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC1C,CAAC;IAEO,MAAM,CAAC,OAAO,CAAC,QAAqB;QAC1C,MAAM,UAAU,GAAG,YAAY,QAAQ,CAAC,EAAE,KAAK,QAAQ,CAAC,QAAQ,mBAAmB,CAAC;QACpF,MAAM,MAAM,GAAG,YAAY,QAAQ,CAAC,EAAE,IAAI,yBAAyB,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3F,IAAI,QAAQ,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;YAC3C,OAAO,GAAG,UAAU,WAAW,MAAM,sBAAsB,YAAY,8CAA8C,CAAC;QACxH,CAAC;QACD,OAAO,GAAG,UAAU,WAAW,MAAM,oBAAoB,YAAY,WAAW,CAAC;IACnF,CAAC;IAED,uFAAuF;IAC/E,MAAM,CAAC,UAAU,CAAC,QAAqB;QAC7C,IAAI,QAAQ,CAAC,eAAe,KAAK,SAAS;YAAE,OAAO,QAAQ,CAAC,eAAe,CAAC;QAC5E,IAAI,QAAQ,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,QAAQ,CAAC;QAC9C,IAAI,QAAQ,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,iBAAiB,CAAC;QACvD,OAAO,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,YAAY,CAAC;IAChE,CAAC;CACF"}

package/dist/src/question/terminal-question-session.d.ts

@@ -0,0 +1,36 @@
+import type { CliQuestion, QuestionPromptAnswer, QuestionPromptIo } from './type/question-prompt.types.js';
+/**
+ * Asks questions on a terminal, one prompt at a time: the keyboard in raw mode,
+ * each keypress reduced by the question's {@link PromptArm} and the frame it
+ * leaves drawn in place. An answered prompt collapses to the answer it sent and
+ * the next question is drawn below it — straight away, so keys typed ahead land
+ * on it. Ctrl-C aborts; a keyboard that ends leaves the rest unanswered.
+ */
+export declare class TerminalQuestionSession {
+    private readonly io;
+    private readonly questions;
+    private readonly screen;
+    private readonly answers;
+    private arm;
+    /** Why the last keypress was refused, drawn under the frame until the next one. */
+    private note;
+    private settlement;
+    /** @param questions the questions to ask, in order — at least one. */
+    constructor(io: QuestionPromptIo, questions: readonly CliQuestion[]);
+    /** Ask every question; resolves with their answers, in order, once the last is answered. */
+    run(): Promise<QuestionPromptAnswer[]>;
+    /** The question being asked: the first one without an answer. */
+    private get current();
+    private readonly onKeypress;
+    private readonly onEnd;
+    private readonly onError;
+    private open;
+    private close;
+    private apply;
+    private redraw;
+    private draw;
+    /** Collapse the answered prompt to its answer, then ask the next question — or end. */
+    private settle;
+    private finish;
+    private fail;
+}

package/dist/src/question/terminal-question-session.js

@@ -0,0 +1,126 @@
+import { emitKeypressEvents } from 'node:readline';
+import { PromptArm } from './prompt-arm.js';
+import { QuestionUnansweredRefusal } from './question-unanswered-refusal.js';
+import { TerminalScreen } from './terminal-screen.js';
+import { answeredLines } from './util/question-frame.util.js';
+/**
+ * Asks questions on a terminal, one prompt at a time: the keyboard in raw mode,
+ * each keypress reduced by the question's {@link PromptArm} and the frame it
+ * leaves drawn in place. An answered prompt collapses to the answer it sent and
+ * the next question is drawn below it — straight away, so keys typed ahead land
+ * on it. Ctrl-C aborts; a keyboard that ends leaves the rest unanswered.
+ */
+export class TerminalQuestionSession {
+    io;
+    questions;
+    screen;
+    answers = [];
+    arm;
+    /** Why the last keypress was refused, drawn under the frame until the next one. */
+    note;
+    settlement;
+    /** @param questions the questions to ask, in order — at least one. */
+    constructor(io, questions) {
+        this.io = io;
+        this.questions = questions;
+        this.screen = new TerminalScreen(io.output);
+        this.arm = PromptArm.of(this.current);
+    }
+    /** Ask every question; resolves with their answers, in order, once the last is answered. */
+    run() {
+        return new Promise((resolve, reject) => {
+            this.settlement = { resolve, reject };
+            this.open();
+            this.draw();
+        });
+    }
+    /** The question being asked: the first one without an answer. */
+    get current() {
+        return this.questions[this.answers.length];
+    }
+    onKeypress = (_sequence, key) => {
+        if (key.ctrl === true && key.name === 'c') {
+            this.fail(new Error(`Aborted with Ctrl-C at question ${this.current.id}.`));
+            return;
+        }
+        this.apply(this.arm.press(key));
+    };
+    onEnd = () => {
+        this.fail(new QuestionUnansweredRefusal(this.questions.slice(this.answers.length)));
+    };
+    onError = (error) => {
+        this.fail(error);
+    };
+    open() {
+        const { input } = this.io;
+        emitKeypressEvents(input);
+        input.setRawMode?.(true);
+        input.on('keypress', this.onKeypress);
+        input.on('end', this.onEnd);
+        input.on('error', this.onError);
+        input.resume();
+    }
+    close() {
+        const { input } = this.io;
+        input.off('keypress', this.onKeypress);
+        input.off('end', this.onEnd);
+        input.off('error', this.onError);
+        input.setRawMode?.(false);
+        input.pause();
+        this.screen.release();
+        this.screen.restoreCursor();
+    }
+    apply(step) {
+        switch (step.kind) {
+            case 'ignore':
+                return;
+            case 'redraw':
+                this.redraw();
+                return;
+            case 'refuse':
+                this.redraw(step.reason);
+                return;
+            case 'open':
+                this.arm = step.arm;
+                this.redraw();
+                return;
+            case 'answer':
+                this.settle(step.answer);
+        }
+    }
+    redraw(note) {
+        this.note = note;
+        this.draw();
+    }
+    draw() {
+        const frame = this.arm.frame(this.screen.columns);
+        if (this.note === undefined) {
+            this.screen.draw(frame);
+            return;
+        }
+        this.screen.draw({ ...frame, lines: [...frame.lines, `  ${this.note}`] });
+    }
+    /** Collapse the answered prompt to its answer, then ask the next question — or end. */
+    settle(answer) {
+        this.screen.draw({ lines: answeredLines(this.current, answer, this.screen.columns) });
+        this.screen.release();
+        this.answers.push(answer);
+        if (this.answers.length === this.questions.length) {
+            this.finish();
+            return;
+        }
+        this.arm = PromptArm.of(this.current);
+        this.redraw();
+    }
+    finish() {
+        this.close();
+        this.settlement?.resolve(this.answers);
+        this.settlement = undefined;
+    }
+    fail(error) {
+        this.close();
+        this.settlement?.reject(error);
+        this.settlement = undefined;
+    }
+}
+//# sourceMappingURL=terminal-question-session.js.map

package/dist/src/question/terminal-question-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-question-session.js","sourceRoot":"","sources":["../../../src/question/terminal-question-session.ts"],"names":[],"mappings":"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"}

package/dist/src/question/terminal-screen.d.ts

@@ -0,0 +1,26 @@
+import type { PromptFrame, TerminalDisplay } from './type/question-prompt.types.js';
+/**
+ * The block of terminal rows a prompt owns. Each frame erases the one before it
+ * and is drawn in its place, so a prompt redraws without scrolling; rows are
+ * counted as the terminal wraps them, so a long line still erases whole.
+ */
+export declare class TerminalScreen {
+    private readonly display;
+    /** Rows the drawn block covers. */
+    private blockRows;
+    /** The row of the block the cursor rests on — `blockRows` when it rests below it. */
+    private cursorRow;
+    constructor(display: TerminalDisplay);
+    /** The terminal's width in cells. */
+    get columns(): number;
+    /** Replace the drawn block with `frame`. */
+    draw(frame: PromptFrame): void;
+    /** Leave the drawn block on screen; whatever is written next starts on the row below it. */
+    release(): void;
+    /** Hand the terminal its cursor back. */
+    restoreCursor(): void;
+    /** Put the cursor where the frame asks, or hide it below the block. */
+    private rest;
+    /** The rows one line takes once the terminal wraps it — an empty line still takes one. */
+    private rowsOf;
+}