@pugi/cli 0.1.0-beta.98 → 1.0.0-alpha.1

package/dist/tools/ask-user-question.js

@@ -1,337 +0,0 @@
-/**
- * AskUserQuestion structured tool — .
- *
- * Mirrors the standard structured-question convention
- * pattern: clarifying questions go through a structured multi-choice
- * tool, NOT free-text prose. The model dispatches the tool with a
- * `question` + a `header` chip + 2-4 `options` (each with `label` +
- * `description`). The UI renders the modal, auto-appends an "Other"
- * fallback for custom text, and surfaces the operator's pick back to
- * the model as a tool_result frame.
- *
- * Why P0 leverage: the structured form forecloses Pugi's recurring
- * "agent rambles instead of dispatching" failure mode at the schema
- * level. When the model is uncertain, the cheapest legal output is
- * `ask_user_question` — not a prose menu, not a fake "Шипану через
- * 8 минут" dispatch promise.
- *
- * Relationship to ask-user.ts (β1 T2):
- *  - ask-user.ts is the LEGACY string-array form (`options: string[]`).
- *    Kept for back-compat; the existing prompt envelope `<pugi-ask>`
- *    and the persona prompts still emit that grammar.
- *  - ask-user-question.ts is the STRUCTURED form layered on top. It
- *    normalises a {label, description} option into the legacy string
- *    before delegating to `askUser`, so the Ink modal does not need
- *    two render paths and the abort/timeout race logic is shared.
- *
- * Hard rules (enforced by Zod):
- *  - question: 5-500 chars, must end with "?". Plain English.
- *  - header: 2-12 chars (short chip label, e.g. "Auth method").
- *  - options: 2-4 strict (no more, no less). Mutually exclusive.
- *    UI auto-adds "Other" — the model NEVER emits it.
- *  - multiSelect: default false.
- */
-import { z } from 'zod';
-import { askUser } from './ask-user.js';
-/** Cap matches the Ink modal layout: 12 chars fits the header chip. */
-export const ASK_USER_QUESTION_HEADER_MIN = 2;
-export const ASK_USER_QUESTION_HEADER_MAX = 12;
-/** Question must be a real question (ends with ?). 5-500 chars. */
-export const ASK_USER_QUESTION_MIN = 5;
-export const ASK_USER_QUESTION_MAX = 500;
-/** Each option label: 2-40 chars (1-5 words). */
-export const ASK_USER_QUESTION_OPTION_LABEL_MIN = 2;
-export const ASK_USER_QUESTION_OPTION_LABEL_MAX = 40;
-/** Each option description: 10-200 chars (one short sentence). */
-export const ASK_USER_QUESTION_OPTION_DESC_MIN = 10;
-export const ASK_USER_QUESTION_OPTION_DESC_MAX = 200;
-/** Option count: 2-4 strict. UI adds "Other" automatically. */
-export const ASK_USER_QUESTION_OPTIONS_MIN = 2;
-export const ASK_USER_QUESTION_OPTIONS_MAX = 4;
-/**
- * Preview pane cap (PUGI-130). Lets the model attach a multi-line
- * ASCII / code / diagram preview to an option. When ANY option в a
- * single-select question carries `preview`, the UI switches к
- * side-by-side layout (options column left, preview pane right).
- *
- * Capped at 5000 chars так что a single payload can stash a full
- * component sketch / SQL migration / diagram, but не enough rope для
- * a model to dump the entire codebase в a preview field.
- *
- * **multiSelect rule:** previews are REJECTED on multi-select questions.
- * Rendering N preview panes simultaneously breaks the layout invariant
- * (single 80-col terminal can host ONE side panel, not N). The schema
- * validator enforces this at the tool boundary с a clear error message.
- */
-export const ASK_USER_QUESTION_OPTION_PREVIEW_MIN = 1;
-export const ASK_USER_QUESTION_OPTION_PREVIEW_MAX = 5000;
-/** PUGI-480 short-format chip rules: ≤ 5 words / option label, ≤ 3 questions / call. */
-export const ASK_USER_QUESTION_CHIP_LABEL_WORD_MAX = 5;
-export const ASK_USER_QUESTION_CHIPS_MAX = 3;
-/**
- * Reusable validator for option labels rendered в chip mode.
- * Counts whitespace-delimited words. Throws с a clear message that
- * names the offending question + option so the model can self-correct.
- */
-export function assertChipLabelWordCap(questionHeader, optionLabel) {
-    const words = optionLabel.trim().split(/\s+/u).filter((w) => w.length > 0);
-    if (words.length > ASK_USER_QUESTION_CHIP_LABEL_WORD_MAX) {
-        throw new Error(`ask_user_question chip "${questionHeader}" option "${optionLabel}" ` +
-            `exceeds the ${ASK_USER_QUESTION_CHIP_LABEL_WORD_MAX}-word label cap ` +
-            `(saw ${words.length} words). Shorten the label before dispatch.`);
-    }
-}
-/**
- * Structured option. `label` is the display text; `description` is the
- * implication line shown dim below it. Both are required — the model
- * cannot ship a label-only option (forces it to think about why each
- * choice exists).
- */
-export const askUserQuestionOptionSchema = z.strictObject({
-    label: z
-        .string()
-        .min(ASK_USER_QUESTION_OPTION_LABEL_MIN)
-        .max(ASK_USER_QUESTION_OPTION_LABEL_MAX)
-        .describe('Display text. Concise (1-5 words).'),
-    description: z
-        .string()
-        .min(ASK_USER_QUESTION_OPTION_DESC_MIN)
-        .max(ASK_USER_QUESTION_OPTION_DESC_MAX)
-        .describe('What this option means / implications.'),
-    preview: z
-        .string()
-        .min(ASK_USER_QUESTION_OPTION_PREVIEW_MIN)
-        .max(ASK_USER_QUESTION_OPTION_PREVIEW_MAX)
-        .optional()
-        .describe('Optional ASCII / code preview (≤ 5000 chars, multi-line OK). When ' +
-        'ANY option in the set carries this field, the UI switches к ' +
-        'side-by-side layout (options column left, preview pane right). ' +
-        'Use для visual comparison of mockups, config snippets, diagram ' +
-        'variations. REJECTED on multiSelect questions (one pane fits one ' +
-        'preview).'),
-});
-export const askUserQuestionSchema = z
-    .strictObject({
-    question: z
-        .string()
-        .min(ASK_USER_QUESTION_MIN)
-        .max(ASK_USER_QUESTION_MAX)
-        .refine((q) => q.trim().endsWith('?'), {
-        message: 'question must end with "?"',
-    })
-        .describe('The complete question. Must end with "?". Plain English, no jargon.'),
-    header: z
-        .string()
-        .min(ASK_USER_QUESTION_HEADER_MIN)
-        .max(ASK_USER_QUESTION_HEADER_MAX)
-        .describe('Short chip label (max 12 chars). E.g. "Auth method".'),
-    options: z
-        .array(askUserQuestionOptionSchema)
-        .min(ASK_USER_QUESTION_OPTIONS_MIN)
-        .max(ASK_USER_QUESTION_OPTIONS_MAX)
-        .describe('2-4 mutually-exclusive options. NEVER add "Other" — UI auto-adds.'),
-    multiSelect: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Allow multiple selections. Default false.'),
-})
-    .superRefine((payload, ctx) => {
-    // PUGI-130 invariant: previews are single-pane only. Side-by-side
-    // layout can host ONE preview at a time; multiSelect implies the
-    // operator may toggle several options and each would want its own
-    // pane. Reject at the schema boundary so the model gets immediate
-    // feedback instead of a silently dropped preview field at render.
-    if (payload.multiSelect === true) {
-        payload.options.forEach((opt, idx) => {
-            if (typeof opt.preview === 'string' && opt.preview.length > 0) {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    path: ['options', idx, 'preview'],
-                    message: 'preview is not allowed on multiSelect questions — ' +
-                        'side-by-side layout supports ONE preview pane at a time. ' +
-                        'Drop the preview field OR switch к single-select.',
-                });
-            }
-        });
-    }
-});
-/**
- * PUGI-480 multi-question chip payload — a bundle of up to 3 short-format
- * chip questions rendered side-by-side. Schema is intentionally narrow:
- * the chip renderer relies on the ≤ 5-word label invariant и will
- * truncate с "…" if the model ever bypasses Zod. The 3-question cap
- * forecloses paragraph-wall prompts at the schema level — the model
- * cannot legally ask "10 quick questions" in one shot.
- */
-export const askUserQuestionChipsQuestionSchema = z.strictObject({
-    header: z
-        .string()
-        .min(ASK_USER_QUESTION_HEADER_MIN)
-        .max(ASK_USER_QUESTION_HEADER_MAX)
-        .describe('Short chip label (max 12 chars). E.g. "Stack".'),
-    question: z
-        .string()
-        .min(ASK_USER_QUESTION_MIN)
-        .max(ASK_USER_QUESTION_MAX)
-        .optional()
-        .describe('Optional full-prose question (shown in non-TTY fallback only).'),
-    options: z
-        .array(askUserQuestionOptionSchema)
-        .min(ASK_USER_QUESTION_OPTIONS_MIN)
-        .max(ASK_USER_QUESTION_OPTIONS_MAX + 1)
-        .superRefine((opts, ctx) => {
-        // Enforce ≤ 5-word label cap on every option. Schema-level so
-        // the model gets immediate feedback on overflow rather than a
-        // silent truncation at render time.
-        for (const opt of opts) {
-            const words = opt.label
-                .trim()
-                .split(/\s+/u)
-                .filter((w) => w.length > 0);
-            if (words.length > ASK_USER_QUESTION_CHIP_LABEL_WORD_MAX) {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    message: `option "${opt.label}" has ${words.length} words; chip labels must be ≤ ${ASK_USER_QUESTION_CHIP_LABEL_WORD_MAX} words`,
-                });
-            }
-        }
-    })
-        .describe('2-5 mutually-exclusive options. Each label ≤ 5 words. UI inserts "Skip — use defaults" as a final option when defaults are present.'),
-});
-export const askUserQuestionChipsSchema = z.strictObject({
-    questions: z
-        .array(askUserQuestionChipsQuestionSchema)
-        .min(1)
-        .max(ASK_USER_QUESTION_CHIPS_MAX)
-        .describe('Bundle of 1-3 short clarifier questions rendered side-by-side as chips.'),
-});
-/**
- * Dispatch the structured tool: validate args via Zod, then route
- * through the shared `askUser` primitive so abort/timeout/non-TTY
- * envelope behaviour is identical to the legacy form.
- *
- * The bridge surface is the same `AskUserBridge` signature — the
- * structured form just gives the Ink modal richer metadata to render
- * (header chip + per-option description). The bridge sees the legacy
- * `{question, options: string[]}` shape because all production bridges
- * (Ink modal + non-TTY envelope emitter) already consume that shape.
- * Per-option descriptions and the header chip are surfaced separately
- * via `enrich` — the modal layer reads them off the dispatched payload
- * stash, NOT off the bridge input, so structured callers can layer on
- * top of the legacy interface without touching the modal contract.
- *
- * Return contract:
- *  - Interactive + bridge present + operator picks N options →
- *    `[ask_user_question:answered] <labels joined by ", ">`.
- *  - Interactive + bridge present + operator cancels →
- *    `[ask_user_question:cancelled]`.
- *  - Interactive + bridge present + timeout →
- *    `[ask_user_question:timeout]`.
- *  - Non-TTY or no bridge → `[user_input_required]<json>[/...]`
- *    envelope identical to the legacy form. Includes `header` +
- *    structured options so a scripted caller can parse the full shape.
- */
-export async function dispatchAskUserQuestion(ctx, rawArgs) {
-    const parsed = askUserQuestionSchema.parse(rawArgs);
-    // Schema-level guard against the "Other" leak: the prompt rules tell
-    // the model NEVER to include "Other" in `options`, but we still reject
-    // it defensively in case a future model misreads the spec. The Ink
-    // modal auto-appends "Other" itself; a model-supplied duplicate would
-    // render two "Other" rows.
-    for (const opt of parsed.options) {
-        const trimmed = opt.label.trim().toLowerCase();
-        if (trimmed === 'other' || trimmed === 'другое') {
-            throw new Error('ask_user_question: do NOT include "Other" in options — UI auto-adds it');
-        }
-    }
-    const legacyOptions = parsed.options.map((opt) => opt.label);
-    const result = await askUser(ctx, {
-        question: parsed.question,
-        options: legacyOptions,
-        multiSelect: parsed.multiSelect ?? false,
-    });
-    if (result.answers && result.answers.length > 0) {
-        return {
-            answers: result.answers,
-            envelope: `[ask_user_question:answered] ${result.answers.join(', ')}`,
-        };
-    }
-    // Non-TTY / cancelled / timeout. Re-wrap the envelope so callers can
-    // grep for the structured tool name even when the underlying primitive
-    // surfaced its legacy `[user_input_required]` envelope.
-    if (result.envelope.includes('"reason":"timeout"')) {
-        return { envelope: '[ask_user_question:timeout]' };
-    }
-    if (result.envelope.includes('"reason":"cancelled"')) {
-        return { envelope: '[ask_user_question:cancelled]' };
-    }
-    // Default to the legacy envelope verbatim — it is still
-    // grep-friendly and includes the structured payload above.
-    return { envelope: result.envelope };
-}
-/**
- * JSON-Schema fragment surfaced to the model via the tool-bridge
- * `parameters` field. Mirrors the Zod schema 1:1 — kept hand-written
- * because the runtime engine wires OpenAI-compatible JSON Schema and
- * the Zod-to-JSON-Schema converter pulls in a transitive dep we have
- * not greenlit. If the Zod schema above changes, mirror the change here.
- */
-export const askUserQuestionJsonSchema = {
-    type: 'object',
-    additionalProperties: false,
-    required: ['question', 'header', 'options'],
-    properties: {
-        question: {
-            type: 'string',
-            minLength: ASK_USER_QUESTION_MIN,
-            maxLength: ASK_USER_QUESTION_MAX,
-            description: 'The complete question. Must end with "?". Plain English, no jargon.',
-        },
-        header: {
-            type: 'string',
-            minLength: ASK_USER_QUESTION_HEADER_MIN,
-            maxLength: ASK_USER_QUESTION_HEADER_MAX,
-            description: 'Short chip label (max 12 chars). E.g. "Auth method".',
-        },
-        options: {
-            type: 'array',
-            minItems: ASK_USER_QUESTION_OPTIONS_MIN,
-            maxItems: ASK_USER_QUESTION_OPTIONS_MAX,
-            items: {
-                type: 'object',
-                additionalProperties: false,
-                required: ['label', 'description'],
-                properties: {
-                    label: {
-                        type: 'string',
-                        minLength: ASK_USER_QUESTION_OPTION_LABEL_MIN,
-                        maxLength: ASK_USER_QUESTION_OPTION_LABEL_MAX,
-                        description: 'Display text. Concise (1-5 words).',
-                    },
-                    description: {
-                        type: 'string',
-                        minLength: ASK_USER_QUESTION_OPTION_DESC_MIN,
-                        maxLength: ASK_USER_QUESTION_OPTION_DESC_MAX,
-                        description: 'What this option means / implications.',
-                    },
-                    preview: {
-                        type: 'string',
-                        minLength: ASK_USER_QUESTION_OPTION_PREVIEW_MIN,
-                        maxLength: ASK_USER_QUESTION_OPTION_PREVIEW_MAX,
-                        description: 'Optional multi-line ASCII / code / diagram preview (≤ 5000 chars). ' +
-                            'When ANY option carries this, UI switches к side-by-side layout. ' +
-                            'Single-select only — REJECTED if multiSelect is true.',
-                    },
-                },
-            },
-            description: '2-4 mutually-exclusive options. NEVER add "Other" — UI auto-adds.',
-        },
-        multiSelect: {
-            type: 'boolean',
-            description: 'Allow multiple selections. Default false. When true, option.preview ' +
-                'is forbidden (one terminal pane fits one preview at a time).',
-        },
-    },
-};
-//# sourceMappingURL=ask-user-question.js.map

package/dist/tools/ask-user.js

@@ -1,115 +0,0 @@
-export const ASK_USER_DEFAULT_TIMEOUT_MS = 5 * 60 * 1_000;
-/**
- * Schema cap: keep the option count tight so the modal stays scannable.
- * Mirrors `ASK_MAX_OPTIONS` in `core/repl/ask.ts` (4).
- */
-export const ASK_USER_MAX_OPTIONS = 4;
-export const ASK_USER_MAX_QUESTION_LEN = 1_000;
-export const ASK_USER_MAX_OPTION_LEN = 200;
-export async function askUser(ctx, input) {
-    validate(input);
-    if (ctx.interactive && ctx.bridge) {
-        // β1a r1 : wrap the bridge in an abort-aware race so a
-        // pending modal cannot block the engine loop forever. Two signals
-        // can interrupt:
-        //  1. `ctx.signal` — the operator cancelled the parent task via
-        //     Ctrl-C; the engine forwards the loop's AbortSignal here.
-        //  2. `ctx.timeoutMs` (default 5 minutes) — operator walked away;
-        //     the modal stays renderable but the tool surface returns the
-        //     `cancelled` envelope so the model can make progress.
-        // The bridge receives the same `signal` so an Ink-based modal can
-        // tear down its render loop and free its keyboard handlers on
-        // abort. Bridges that ignore the signal still get pre-empted by
-        // the race — they just leak a render until the next operator
-        // keystroke.
-        const timeoutMs = ctx.timeoutMs ?? ASK_USER_DEFAULT_TIMEOUT_MS;
-        // Pre-flight: short-circuit when the caller's signal is already
-        // aborted. Avoids constructing a bridge promise that races against
-        // an already-resolved abort sentinel — the race ordering is
-        // unspecified for promises that have all settled by the time
-        // Promise.race is called, which would non-deterministically let
-        // the bridge's answer leak through after an explicit cancel.
-        if (ctx.signal?.aborted) {
-            return { envelope: formatEnvelope(input, 'cancelled') };
-        }
-        const controller = new AbortController();
-        if (ctx.signal) {
-            ctx.signal.addEventListener('abort', () => controller.abort(), { once: true });
-        }
-        let timeoutHandle;
-        const timeoutPromise = new Promise((resolve) => {
-            timeoutHandle = setTimeout(() => resolve('timeout'), timeoutMs);
-        });
-        const abortPromise = new Promise((resolve) => {
-            controller.signal.addEventListener('abort', () => resolve('aborted'), { once: true });
-        });
-        let picked;
-        try {
-            picked = await Promise.race([
-                ctx.bridge(input, { signal: controller.signal }),
-                timeoutPromise,
-                abortPromise,
-            ]);
-        }
-        finally {
-            if (timeoutHandle)
-                clearTimeout(timeoutHandle);
-        }
-        if (picked === 'timeout') {
-            controller.abort();
-            return { envelope: formatEnvelope(input, 'timeout') };
-        }
-        if (picked === 'aborted') {
-            return { envelope: formatEnvelope(input, 'cancelled') };
-        }
-        if (!Array.isArray(picked) || picked.length === 0) {
-            // Operator declined / closed the modal — surface a structured
-            // "no answer" envelope so the model can decide whether to retry.
-            const envelope = formatEnvelope(input, 'cancelled');
-            return { envelope };
-        }
-        return {
-            answers: picked,
-            envelope: formatAnswer(picked),
-        };
-    }
-    // Non-TTY or no bridge — surface the envelope. Caller parses it and
-    // either pipes an answer back on a follow-up turn or aborts.
-    const envelope = formatEnvelope(input, 'no_tty');
-    return { envelope };
-}
-function validate(input) {
-    const question = input.question?.trim();
-    if (!question)
-        throw new Error('ask_user: question is required');
-    if (question.length > ASK_USER_MAX_QUESTION_LEN) {
-        throw new Error(`ask_user: question exceeds ${ASK_USER_MAX_QUESTION_LEN} char cap`);
-    }
-    if (!Array.isArray(input.options) || input.options.length < 2) {
-        throw new Error('ask_user: at least 2 options required');
-    }
-    if (input.options.length > ASK_USER_MAX_OPTIONS) {
-        throw new Error(`ask_user: at most ${ASK_USER_MAX_OPTIONS} options allowed`);
-    }
-    for (const opt of input.options) {
-        if (typeof opt !== 'string' || !opt.trim()) {
-            throw new Error('ask_user: every option must be a non-empty string');
-        }
-        if (opt.length > ASK_USER_MAX_OPTION_LEN) {
-            throw new Error(`ask_user: option exceeds ${ASK_USER_MAX_OPTION_LEN} char cap`);
-        }
-    }
-}
-function formatEnvelope(input, reason) {
-    const payload = {
-        question: input.question,
-        options: input.options,
-        multiSelect: input.multiSelect === true,
-        reason,
-    };
-    return `[user_input_required]${JSON.stringify(payload)}[/user_input_required]`;
-}
-function formatAnswer(answers) {
-    return answers.join(', ');
-}
-//# sourceMappingURL=ask-user.js.map