windows-development-sandbox 1.5.0 → 1.9.0

package/dist/app/kernel/define.js

@@ -0,0 +1,42 @@
+import { fail } from '../../core/util/errors.js';
+import { issuesText } from './errors.js';
+export const SURFACE_NAMES = ['cli', 'menu', 'web'];
+export function defineOperation(def) {
+    return { ...def, cli: def.cli, kind: 'operation' };
+}
+export function defineQuery(def) {
+    return { ...def, cli: def.cli, kind: 'query' };
+}
+export function defineView(def) {
+    return { ...def, kind: 'view' };
+}
+/** Why a definition is not on a surface, or undefined when it is. */
+export function exemption(def, surface) {
+    return def.surfaces === undefined || def.surfaces === 'all' ? undefined : def.surfaces.except[surface];
+}
+export function onSurface(def, surface) {
+    return exemption(def, surface) === undefined;
+}
+/** Binds implement() to the program's context type once (app/context.ts), so features write implement(def, run). */
+export function implementer() {
+    return function implement(def, run) {
+        return { def, run: async (ctx, input, io) => run(ctx, input, io) };
+    };
+}
+/** The input as the definition reads it (defaults filled in); a value that does not fit says what is wrong. */
+export function parseInput(def, input) {
+    const parsed = def.input.safeParse(input ?? {});
+    if (!parsed.success)
+        fail('That does not work for ' + def.title.toLowerCase() + ': ' + issuesText(parsed.error));
+    return parsed.data;
+}
+/** Runs an implementation the way every surface must: input checked before, output checked after. */
+export async function invoke(impl, ctx, input, io) {
+    const output = await impl.run(ctx, parseInput(impl.def, input), io);
+    return impl.def.output.parse(output);
+}
+/** The inputs a view's queries run with for these parameters (defaults filled in). */
+export function viewInputs(view, params) {
+    const given = view.inputs?.(params) ?? {};
+    return Object.fromEntries(Object.entries(view.queries).map(([name, query]) => [name, parseInput(query, given[name])]));
+}

package/dist/app/kernel/errors.d.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+export declare const ErrorKindSchema: z.ZodEnum<{
+    user: "user";
+    cancelled: "cancelled";
+    invalid: "invalid";
+    bug: "bug";
+}>;
+export type ErrorKind = z.output<typeof ErrorKindSchema>;
+/** A failure as every surface shows it (and as the web receives it). */
+export declare const WireErrorSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        user: "user";
+        cancelled: "cancelled";
+        invalid: "invalid";
+        bug: "bug";
+    }>;
+    message: z.ZodString;
+    fix: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type WireError = z.output<typeof WireErrorSchema>;
+/** The user said no to a question the operation needed: nothing changed. */
+export declare class Cancelled extends Error {
+    constructor(message?: string);
+}
+/** Ends an operation because a question was declined. */
+export declare function cancelled(message?: string): never;
+/** What the user is told about a bug (its stack never leaves this PC). */
+export declare const BUG_MESSAGE = "Something went wrong.";
+/** Any thrown value as message + fix. */
+export declare function toWireError(e: unknown): WireError;
+/** The error to throw on the receiving side (the web client, a test). */
+export declare function fromWireError(w: WireError): Error;
+/** "key: problem; other: problem" for a value that did not fit its schema. */
+export declare function issuesText(e: z.ZodError): string;

package/dist/app/kernel/errors.js

@@ -0,0 +1,45 @@
+// How a failure crosses a surface: a UserError (fail(message, fix)) stays a message and a fix everywhere, a declined
+// question is "cancelled" (nothing changed), a value that does not fit a schema is "invalid", and anything else is a
+// bug whose details stay on this PC.
+import { z } from 'zod';
+import { UserError } from '../../core/util/errors.js';
+export const ErrorKindSchema = z.enum(['user', 'cancelled', 'invalid', 'bug']);
+/** A failure as every surface shows it (and as the web receives it). */
+export const WireErrorSchema = z.strictObject({
+    kind: ErrorKindSchema,
+    message: z.string().max(2000),
+    fix: z.string().max(2000).optional(),
+});
+/** The user said no to a question the operation needed: nothing changed. */
+export class Cancelled extends Error {
+    constructor(message = 'Nothing changed.') {
+        super(message);
+        this.name = 'Cancelled';
+    }
+}
+/** Ends an operation because a question was declined. */
+export function cancelled(message) {
+    throw new Cancelled(message);
+}
+/** What the user is told about a bug (its stack never leaves this PC). */
+export const BUG_MESSAGE = 'Something went wrong.';
+/** Any thrown value as message + fix. */
+export function toWireError(e) {
+    if (e instanceof Cancelled)
+        return { kind: 'cancelled', message: e.message };
+    if (e instanceof UserError)
+        return { kind: 'user', message: e.message, ...(e.fix ? { fix: e.fix } : {}) };
+    if (e instanceof z.ZodError)
+        return { kind: 'invalid', message: issuesText(e) };
+    return { kind: 'bug', message: BUG_MESSAGE };
+}
+/** The error to throw on the receiving side (the web client, a test). */
+export function fromWireError(w) {
+    if (w.kind === 'cancelled')
+        return new Cancelled(w.message);
+    return new UserError(w.message, w.fix);
+}
+/** "key: problem; other: problem" for a value that did not fit its schema. */
+export function issuesText(e) {
+    return e.issues.map((i) => (i.path.length ? i.path.join('.') + ': ' : '') + i.message).join('; ');
+}

package/dist/app/kernel/fields.d.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import { SchemaNode } from './schema-node.js';
+export declare const FIELD_KINDS: readonly ["boolean", "enum", "number", "text", "secret", "path", "list", "map", "object", "json"];
+export type FieldKind = (typeof FIELD_KINDS)[number];
+/** A folder or a file on this PC. */
+export type PathKind = 'dir' | 'file';
+export type ChoiceValue = string | number | boolean;
+export interface Choice {
+    readonly value: ChoiceValue;
+    readonly label: string;
+}
+export interface Field {
+    /** The last part of the key ('' for a whole schema). */
+    readonly name: string;
+    /** Where the value sits, from the root of the schema (settings: sandbox.memoryMb). */
+    readonly key: readonly string[];
+    readonly kind: FieldKind;
+    readonly label: string;
+    readonly help?: string;
+    /** May be left out (it is optional or has a default). */
+    readonly optional: boolean;
+    /** The default (secrets: never sent; `***` when there is one). */
+    readonly default?: unknown;
+    /** enum: the values offered. */
+    readonly choices?: readonly Choice[];
+    /** enum: a value of your own is allowed too (a number, a text): typed as this field. */
+    readonly open?: Field;
+    /** number: the range and whether it must be whole; `range` says it in words ("1 to 365"). */
+    readonly min?: number;
+    readonly max?: number;
+    readonly integer?: boolean;
+    readonly range?: string;
+    /** path: a folder or a file; `literals` are words allowed instead of a path ("auto"). */
+    readonly pathKind?: PathKind;
+    readonly literals?: readonly string[];
+    /** list / map: one entry. */
+    readonly element?: Field;
+    /** object: its fields, in schema order. */
+    readonly fields?: readonly Field[];
+}
+/** The wire shape of a Field (validated wherever Fields arrive from elsewhere). */
+export declare const FieldSchema: z.ZodType<Field>;
+/** The kind of path a value holds (its key without list positions), or undefined when it is not a path. */
+export declare function pathKindOf(key: readonly string[]): PathKind | undefined;
+/** Words that are fine instead of a path ("auto"), read from the description. */
+export declare function pathLiterals(node: SchemaNode): string[];
+/** "On", "Off" or the value itself: how a choice is named. */
+export declare function choiceLabel(v: unknown): string;
+/** The Field for a schema (or one part of it, `key` naming where it sits). */
+export declare function fieldOf(schema: z.ZodType | SchemaNode, key?: readonly string[], label?: string): Field;
+/** The Fields of an object schema, in schema order (`key` = where the object sits). */
+export declare function fieldsOf(schema: z.ZodType | SchemaNode, key?: readonly string[]): Field[];
+/** A value in one short line, and the tone it is shown in (secrets as ***). */
+export interface ValueText {
+    readonly text: string;
+    readonly tone?: 'ok' | 'muted';
+}
+/** A one-line name for an object in a list (a mapped folder, an agent's package ...). */
+export declare function summary(value: unknown): string;
+/** How a value reads in a list: On/Off, "not set", counts for lists and maps, *** for a secret. */
+export declare function valueText(value: unknown, field?: Pick<Field, 'kind' | 'element'>, max?: number): ValueText;
+/** What was typed for a value as the value it stands for: true/false/on/off, a number, JSON, or plain text. */
+export declare function valueFromText(node: SchemaNode, text: string): unknown;
+/** What a value accepts, in words: its fixed values, a number and its range, true or false. */
+export declare function allowedText(node: SchemaNode): string;
+/**
+ * What is wrong with a value for a Field, as far as the Field can tell (required, a number in range, one of the
+ * choices); undefined when nothing is. Forms check this as you type; the operation checks the value fully again.
+ */
+export declare function fieldProblem(field: Field, value: unknown): string | undefined;

package/dist/app/kernel/fields.js

@@ -0,0 +1,243 @@
+// One form model for every surface: any zod schema (an operation's input, the whole settings schema) becomes Field
+// descriptors - the kind of input, its label and help (from .describe()), default, range, choices, whether it is a
+// folder or a file. The menu's editors and the web's inputs both read Fields, so a new option or setting is editable
+// everywhere as soon as it is in a schema. Fields are plain data (FieldSchema), so they can travel to the browser.
+import { z } from 'zod';
+import { SchemaNode } from './schema-node.js';
+import { humanize } from './text.js';
+export const FIELD_KINDS = [
+    'boolean',
+    'enum',
+    'number',
+    'text',
+    'secret',
+    'path',
+    'list',
+    'map',
+    'object',
+    'json',
+];
+const ChoiceValueSchema = z.union([z.string(), z.number(), z.boolean()]);
+/** The wire shape of a Field (validated wherever Fields arrive from elsewhere). */
+export const FieldSchema = z.lazy(() => z.strictObject({
+    name: z.string(),
+    key: z.array(z.string()),
+    kind: z.enum(FIELD_KINDS),
+    label: z.string(),
+    help: z.string().optional(),
+    optional: z.boolean(),
+    default: z.unknown().optional(),
+    choices: z.array(z.strictObject({ value: ChoiceValueSchema, label: z.string() })).optional(),
+    open: FieldSchema.optional(),
+    min: z.number().optional(),
+    max: z.number().optional(),
+    integer: z.boolean().optional(),
+    range: z.string().optional(),
+    pathKind: z.enum(['dir', 'file']).optional(),
+    literals: z.array(z.string()).optional(),
+    element: FieldSchema.optional(),
+    fields: z.array(FieldSchema).optional(),
+}));
+/** Settings whose value (or list entries) are folders or files, besides the names that say so (…Dir, …File). */
+const PATH_KINDS = {
+    'storage.root': 'dir',
+    'projects.roots': 'dir',
+    'projects.exclude': 'dir',
+    'projects.declinedRoots': 'dir',
+    'claudeProfile.hostDir': 'dir',
+    'claudeProfile.globalStateFile': 'file',
+    scripts: 'file',
+};
+/** The kind of path a value holds (its key without list positions), or undefined when it is not a path. */
+export function pathKindOf(key) {
+    const id = key.join('.');
+    const last = key[key.length - 1] ?? '';
+    if (PATH_KINDS[id])
+        return PATH_KINDS[id];
+    if (key[0] === 'mappings' && last === 'host')
+        return 'dir';
+    if (last === 'hostDir')
+        return 'dir';
+    if (/(Dir|Folder)$/.test(last))
+        return 'dir';
+    if (/File$/.test(last))
+        return 'file';
+    return undefined;
+}
+/** Words that are fine instead of a path ("auto"), read from the description. */
+export function pathLiterals(node) {
+    return /"auto"/.test(node.description ?? '') ? ['auto'] : [];
+}
+/** "On", "Off" or the value itself: how a choice is named. */
+export function choiceLabel(v) {
+    return v === true ? 'On' : v === false ? 'Off' : String(v);
+}
+/** A real bound (zod reports none as ±Infinity or the safe-integer limits). */
+function isLimit(n) {
+    return n !== undefined && Number.isFinite(n) && Math.abs(n) < Number.MAX_SAFE_INTEGER;
+}
+/** The schema's default, if it has one. */
+function defaultOf(node) {
+    const def = node.schema._zod.def;
+    return def.type === 'default' ? def.defaultValue : undefined;
+}
+/** The Field for a schema (or one part of it, `key` naming where it sits). */
+export function fieldOf(schema, key = [], label) {
+    const node = schema instanceof SchemaNode ? schema : new SchemaNode(schema);
+    const name = key[key.length - 1] ?? '';
+    const base = {
+        name,
+        key: [...key],
+        label: label ?? (name ? humanize(name) : ''),
+        ...(node.description ? { help: node.description } : {}),
+        optional: node.optional,
+    };
+    const fallback = defaultOf(node);
+    const withDefault = (secret) => fallback === undefined ? {} : { default: secret ? (fallback === '' ? '' : '***') : fallback };
+    switch (node.editor) {
+        case 'boolean':
+            return { ...base, kind: 'boolean', ...withDefault(false) };
+        case 'choice':
+        case 'union': {
+            const open = node.openOption;
+            return {
+                ...base,
+                kind: 'enum',
+                ...withDefault(false),
+                choices: node.choiceValues
+                    .filter((v) => ['string', 'number', 'boolean'].includes(typeof v))
+                    .map((v) => ({ value: v, label: choiceLabel(v) })),
+                ...(open ? { open: fieldOf(open, key, base.label) } : {}),
+            };
+        }
+        case 'number': {
+            const range = node.rangeText();
+            return {
+                ...base,
+                kind: 'number',
+                ...withDefault(false),
+                ...(isLimit(node.min) ? { min: node.min } : {}),
+                ...(isLimit(node.max) ? { max: node.max } : {}),
+                ...(node.integer ? { integer: true } : {}),
+                ...(range ? { range } : {}),
+            };
+        }
+        case 'string': {
+            if (node.secret)
+                return { ...base, kind: 'secret', ...withDefault(true) };
+            const pathKind = pathKindOf(key);
+            if (pathKind)
+                return { ...base, kind: 'path', ...withDefault(false), pathKind, literals: pathLiterals(node) };
+            return { ...base, kind: 'text', ...withDefault(false) };
+        }
+        case 'string-list':
+        case 'choice-list':
+        case 'object-list':
+            return { ...base, kind: 'list', ...withDefault(false), element: fieldOf(node.element, key, 'Entry') };
+        case 'string-map':
+        case 'object-map':
+            return { ...base, kind: 'map', ...withDefault(node.element?.secret ?? false), element: elementOf(node, key) };
+        case 'object':
+            return { ...base, kind: 'object', ...withDefault(false), fields: fieldsOf(node, key) };
+        default:
+            return { ...base, kind: 'json', ...withDefault(false) };
+    }
+}
+/** A map's entry: named by its key, so it is not a path or secret by the map's own name alone. */
+function elementOf(node, key) {
+    return fieldOf(node.element, [...key, '*'], 'Value');
+}
+/** The Fields of an object schema, in schema order (`key` = where the object sits). */
+export function fieldsOf(schema, key = []) {
+    const node = schema instanceof SchemaNode ? schema : new SchemaNode(schema);
+    return node.children().map(([name, child]) => fieldOf(child, [...key, name]));
+}
+/** A one-line name for an object in a list (a mapped folder, an agent's package ...). */
+export function summary(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return String(value);
+    const o = value;
+    if (typeof o.host === 'string' && typeof o.guest === 'string')
+        return o.host + ' → ' + o.guest + (o.readOnly ? ' (read-only)' : '');
+    const strings = Object.values(o).filter((v) => typeof v === 'string' && v !== '');
+    return strings.slice(0, 2).join(' · ') || '{ ' + Object.keys(o).join(', ') + ' }';
+}
+/** Cuts text to `max` characters with an ellipsis. */
+function cut(text, max) {
+    return text.length > max ? text.slice(0, Math.max(0, max - 1)) + '…' : text;
+}
+/** How a value reads in a list: On/Off, "not set", counts for lists and maps, *** for a secret. */
+export function valueText(value, field, max = 60) {
+    if (value === undefined)
+        return { text: 'not set', tone: 'muted' };
+    if (field?.kind === 'secret')
+        return value === '' ? { text: '(empty)', tone: 'muted' } : { text: '***' };
+    if (value === true)
+        return { text: 'On', tone: 'ok' };
+    if (value === false)
+        return { text: 'Off', tone: 'muted' };
+    if (value === null)
+        return { text: 'none', tone: 'muted' };
+    if (typeof value === 'string')
+        return value === '' ? { text: '(empty)', tone: 'muted' } : { text: cut(value, max) };
+    if (typeof value === 'number')
+        return { text: String(value) };
+    if (Array.isArray(value))
+        return value.length === 0
+            ? { text: 'none', tone: 'muted' }
+            : {
+                text: cut(value.length + ' · ' + value.map((v) => (typeof v === 'object' ? summary(v) : String(v))).join(', '), max),
+            };
+    const keys = Object.keys(value);
+    return keys.length ? { text: cut(keys.length + ' · ' + keys.join(', '), max) } : { text: 'none', tone: 'muted' };
+}
+/** What was typed for a value as the value it stands for: true/false/on/off, a number, JSON, or plain text. */
+export function valueFromText(node, text) {
+    const word = text.trim().toLowerCase();
+    if (node.type === 'string')
+        return text;
+    if (node.type === 'boolean' || node.options.some((o) => o.type === 'boolean')) {
+        if (['true', 'on', 'yes'].includes(word))
+            return true;
+        if (['false', 'off', 'no'].includes(word))
+            return false;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // Not JSON: a bare word such as auto or a path is the text itself.
+        return node.type === 'array' ? text.split(',').map((t) => t.trim()) : text;
+    }
+}
+/** What a value accepts, in words: its fixed values, a number and its range, true or false. */
+export function allowedText(node) {
+    if (node.type === 'boolean')
+        return 'Use true or false.';
+    const values = node.choiceValues.map((v) => String(v));
+    const open = node.openOption ?? (node.type === 'number' ? node : undefined);
+    const range = (n) => (n.rangeText() ? ' (' + n.rangeText() + ')' : '');
+    const more = open ? (open.type === 'number' ? 'a number' + range(open) : 'text') : '';
+    const parts = [...values, ...(more ? [more] : [])];
+    return parts.length ? 'Allowed: ' + parts.join(', or ') + '.' : 'Check the value.';
+}
+/**
+ * What is wrong with a value for a Field, as far as the Field can tell (required, a number in range, one of the
+ * choices); undefined when nothing is. Forms check this as you type; the operation checks the value fully again.
+ */
+export function fieldProblem(field, value) {
+    if (value === undefined || value === '')
+        return field.optional || field.kind === 'text' ? undefined : 'Required.';
+    if (field.kind === 'number') {
+        const n = typeof value === 'number' ? value : Number(value);
+        if (!Number.isFinite(n))
+            return 'Enter a number.';
+        if (field.integer && !Number.isInteger(n))
+            return 'Enter a whole number.';
+        if ((field.min !== undefined && n < field.min) || (field.max !== undefined && n > field.max))
+            return field.range ? 'Use ' + field.range + '.' : 'Out of range.';
+    }
+    if (field.kind === 'enum' && !field.open && !field.choices?.some((c) => c.value === value))
+        return 'Choose one.';
+    return undefined;
+}

package/dist/app/kernel/index.d.ts

@@ -0,0 +1,8 @@
+export * from './define.js';
+export * from './errors.js';
+export * from './fields.js';
+export * from './io.js';
+export * from './rpc.js';
+export * from './schema-node.js';
+export * from './text.js';
+export * from './view.js';

package/dist/app/kernel/index.js

@@ -0,0 +1,10 @@
+// The kernel of the shared core: pure (zod and nothing of Node, the terminal or the DOM), so the CLI, the menu, the
+// web server and the browser all import the same definitions, view model, form fields, questions and RPC messages.
+export * from './define.js';
+export * from './errors.js';
+export * from './fields.js';
+export * from './io.js';
+export * from './rpc.js';
+export * from './schema-node.js';
+export * from './text.js';
+export * from './view.js';

package/dist/app/kernel/io.d.ts

@@ -0,0 +1,193 @@
+import { z } from 'zod';
+import type { Tone } from './view.js';
+declare const ChoiceSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type QuestionChoice = z.output<typeof ChoiceSchema>;
+export declare const ConfirmQuestionSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"confirm">;
+    title: z.ZodString;
+    lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    yes: z.ZodOptional<z.ZodString>;
+    danger: z.ZodOptional<z.ZodBoolean>;
+    typed: z.ZodOptional<z.ZodString>;
+    implied: z.ZodOptional<z.ZodBoolean>;
+    noTerminal: z.ZodOptional<z.ZodObject<{
+        message: z.ZodString;
+        fix: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const ChooseQuestionSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"choose">;
+    title: z.ZodString;
+    lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    choices: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    initial: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const TextQuestionSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"text">;
+    title: z.ZodString;
+    lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    initial: z.ZodOptional<z.ZodString>;
+    allowEmpty: z.ZodOptional<z.ZodBoolean>;
+    problem: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const SecretQuestionSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"secret">;
+    title: z.ZodString;
+    lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    problem: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const PathQuestionSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"path">;
+    title: z.ZodString;
+    lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    pathKind: z.ZodEnum<{
+        file: "file";
+        dir: "dir";
+    }>;
+    initial: z.ZodOptional<z.ZodString>;
+    literals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    problem: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const ChecklistQuestionSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"checklist">;
+    title: z.ZodString;
+    lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    choices: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    checked: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const QuestionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"confirm">;
+    title: z.ZodString;
+    lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    yes: z.ZodOptional<z.ZodString>;
+    danger: z.ZodOptional<z.ZodBoolean>;
+    typed: z.ZodOptional<z.ZodString>;
+    implied: z.ZodOptional<z.ZodBoolean>;
+    noTerminal: z.ZodOptional<z.ZodObject<{
+        message: z.ZodString;
+        fix: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"choose">;
+    title: z.ZodString;
+    lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    choices: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    initial: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"text">;
+    title: z.ZodString;
+    lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    initial: z.ZodOptional<z.ZodString>;
+    allowEmpty: z.ZodOptional<z.ZodBoolean>;
+    problem: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"secret">;
+    title: z.ZodString;
+    lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    problem: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"path">;
+    title: z.ZodString;
+    lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    pathKind: z.ZodEnum<{
+        file: "file";
+        dir: "dir";
+    }>;
+    initial: z.ZodOptional<z.ZodString>;
+    literals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    problem: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"checklist">;
+    title: z.ZodString;
+    lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    choices: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    checked: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>], "kind">;
+export type Question = z.output<typeof QuestionSchema>;
+export type ConfirmQuestion = z.output<typeof ConfirmQuestionSchema>;
+export type ChooseQuestion = z.output<typeof ChooseQuestionSchema>;
+export type TextQuestion = z.output<typeof TextQuestionSchema>;
+export type SecretQuestion = z.output<typeof SecretQuestionSchema>;
+export type PathQuestion = z.output<typeof PathQuestionSchema>;
+export type ChecklistQuestion = z.output<typeof ChecklistQuestionSchema>;
+/** The answer each kind of question gets (undefined = backed out). */
+export interface AnswerOf {
+    confirm: boolean;
+    choose: string | undefined;
+    text: string | undefined;
+    secret: string | undefined;
+    path: string | undefined;
+    checklist: string[] | undefined;
+}
+export type Answer = AnswerOf[keyof AnswerOf];
+/** The wire shape of an answer for each kind (the server checks what the browser sends). */
+export declare const ANSWER_SCHEMAS: {
+    readonly [K in keyof AnswerOf]: z.ZodType<AnswerOf[K]>;
+};
+/** A check of a typed answer: true, or what is wrong (the question is asked again with it). */
+export type Validate = (value: string) => true | string;
+type Ask<K extends keyof AnswerOf, Q> = (question: Omit<Q, 'kind'>) => Promise<AnswerOf[K]>;
+type AskTyped<K extends keyof AnswerOf, Q> = (question: Omit<Q, 'kind'> & {
+    validate?: Validate;
+}) => Promise<AnswerOf[K]>;
+export interface OperationIO {
+    /** What is happening now (a spinner in the CLI, a notice in the menu, a progress line in the web). */
+    progress(text: string): void;
+    /** A line of output worth keeping. */
+    log(text: string, tone?: Tone): void;
+    confirm: Ask<'confirm', ConfirmQuestion>;
+    choose: Ask<'choose', ChooseQuestion>;
+    text: AskTyped<'text', TextQuestion>;
+    secret: AskTyped<'secret', SecretQuestion>;
+    path: AskTyped<'path', PathQuestion>;
+    checklist: Ask<'checklist', ChecklistQuestion>;
+}
+/** Asks one question the way a surface can. */
+export type Asker = <Q extends Question>(question: Q) => Promise<AnswerOf[Q['kind']]>;
+/** Where progress and log lines go. */
+export interface OutputSink {
+    progress(text: string): void;
+    log(text: string, tone?: Tone): void;
+}
+/** An OperationIO from one way of asking and one place for output lines. */
+export declare function ioFromAsker(asker: Asker, sink: OutputSink): OperationIO;
+/** What a FakeIO saw: every question asked and every line written. */
+export interface FakeIORecord {
+    readonly questions: Question[];
+    readonly progress: string[];
+    readonly logs: {
+        text: string;
+        tone?: Tone;
+    }[];
+}
+/**
+ * An OperationIO for tests: answers come from a list in order (a function gets the question). Running out of answers
+ * fails the test with the question that had none.
+ */
+export declare function fakeIO(answers?: readonly (Answer | ((q: Question) => Answer))[]): {
+    io: OperationIO;
+    seen: FakeIORecord;
+};
+/** For reads that never ask (queries): output is dropped, and a question is a bug. */
+export declare const NO_QUESTIONS: OperationIO;
+export {};