windows-development-sandbox 1.1.0 → 1.4.0

package/dist/cli/menu/settings/schema-node.d.ts

@@ -0,0 +1,62 @@
+import type { z } from 'zod';
+type Def = {
+    type: string;
+    options?: ZodLike[];
+    values?: unknown[];
+    entries?: Record<string, string>;
+    element?: ZodLike;
+    innerType?: ZodLike;
+    keyType?: ZodLike;
+    valueType?: ZodLike;
+    defaultValue?: unknown;
+    in?: ZodLike;
+    out?: ZodLike;
+};
+type ZodLike = z.ZodType & {
+    _zod: {
+        def: Def;
+    };
+    shape?: Record<string, ZodLike>;
+    description?: string;
+    minValue?: number | null;
+    maxValue?: number | null;
+};
+/** The editor a setting gets. */
+export type EditorKind = 'boolean' | 'choice' | 'union' | 'number' | 'string' | 'string-list' | 'choice-list' | 'object-list' | 'string-map' | 'object-map' | 'object' | 'json';
+export declare class SchemaNode {
+    readonly schema: ZodLike;
+    constructor(schema: unknown);
+    /** The real type under optional() / default() / nullable() / transforms. */
+    get inner(): ZodLike;
+    get type(): string;
+    /** A group of settings (an object with known fields), opened rather than edited. */
+    get isSection(): boolean;
+    /** The description, which .partial() / .optional() wrappers may carry on the inner schema instead. */
+    get description(): string | undefined;
+    get min(): number | undefined;
+    get max(): number | undefined;
+    /** The fields of an object, in schema order. */
+    children(): [string, SchemaNode][];
+    child(name: string): SchemaNode | undefined;
+    /** Every setting below this one that has an editor of its own (not a section), with its path. */
+    leaves(key?: string[]): {
+        key: string[];
+        node: SchemaNode;
+    }[];
+    /** Array items, or a map's values. */
+    get element(): SchemaNode | undefined;
+    /** Union members. */
+    get options(): SchemaNode[];
+    /** The values an enum or literal allows. */
+    get choices(): unknown[];
+    get editor(): EditorKind;
+    /** Every value a choice allows (booleans of a union included). */
+    get choiceValues(): unknown[];
+    /** The member of a union that is not a fixed value (a number, a string ...), edited after "Custom...". */
+    get openOption(): SchemaNode | undefined;
+    /** What a new entry (in a list or a map) starts as: the default if there is one, otherwise the simplest valid shape. */
+    initial(): unknown;
+    /** Is `value` acceptable here on its own? (The whole file is checked again when it is saved.) */
+    check(value: unknown): true | string;
+}
+export {};

package/dist/cli/menu/settings/schema-node.js

@@ -0,0 +1,104 @@
+/** Settings never shown (the link to the JSON Schema). */
+const HIDDEN = new Set(['$schema']);
+export class SchemaNode {
+    schema;
+    constructor(schema) { this.schema = schema; }
+    /** The real type under optional() / default() / nullable() / transforms. */
+    get inner() {
+        let s = this.schema;
+        for (;;) {
+            const def = s._zod.def;
+            if (['optional', 'default', 'nullable', 'prefault', 'readonly'].includes(def.type) && def.innerType)
+                s = def.innerType;
+            else if (def.type === 'pipe' && def.in)
+                s = def.in;
+            else
+                return s;
+        }
+    }
+    get type() { return this.inner._zod.def.type; }
+    /** A group of settings (an object with known fields), opened rather than edited. */
+    get isSection() { return this.type === 'object' && Boolean(this.inner.shape); }
+    /** The description, which .partial() / .optional() wrappers may carry on the inner schema instead. */
+    get description() { return this.schema.description ?? this.inner.description; }
+    get min() { return this.inner.minValue ?? undefined; }
+    get max() { return this.inner.maxValue ?? undefined; }
+    /** The fields of an object, in schema order. */
+    children() {
+        return Object.entries(this.inner.shape ?? {}).filter(([name]) => !HIDDEN.has(name)).map(([name, s]) => [name, new SchemaNode(s)]);
+    }
+    child(name) {
+        const s = this.inner.shape?.[name];
+        return s ? new SchemaNode(s) : undefined;
+    }
+    /** Every setting below this one that has an editor of its own (not a section), with its path. */
+    leaves(key = []) {
+        return this.children().flatMap(([name, child]) => (child.isSection ? child.leaves([...key, name]) : [{ key: [...key, name], node: child }]));
+    }
+    /** Array items, or a map's values. */
+    get element() {
+        const def = this.inner._zod.def;
+        return def.type === 'array' && def.element ? new SchemaNode(def.element) : def.type === 'record' && def.valueType ? new SchemaNode(def.valueType) : undefined;
+    }
+    /** Union members. */
+    get options() { return (this.inner._zod.def.options ?? []).map((o) => new SchemaNode(o)); }
+    /** The values an enum or literal allows. */
+    get choices() {
+        const def = this.inner._zod.def;
+        if (def.type === 'enum')
+            return Object.values(def.entries ?? {});
+        if (def.type === 'literal')
+            return def.values ?? [];
+        return [];
+    }
+    get editor() {
+        const type = this.type;
+        if (type === 'boolean')
+            return 'boolean';
+        if (type === 'enum' || type === 'literal')
+            return 'choice';
+        if (type === 'union')
+            return this.options.every((o) => ['literal', 'enum', 'boolean'].includes(o.type)) ? 'choice' : 'union';
+        if (type === 'number' || type === 'string')
+            return type;
+        const element = this.element;
+        if (type === 'array' && element)
+            return element.type === 'string' ? 'string-list' : element.type === 'enum' ? 'choice-list' : element.type === 'object' ? 'object-list' : 'json';
+        if (type === 'record' && element)
+            return ['string', 'number', 'boolean'].includes(element.type) ? 'string-map' : element.type === 'object' ? 'object-map' : 'json';
+        if (type === 'object')
+            return 'object';
+        return 'json';
+    }
+    /** Every value a choice allows (booleans of a union included). */
+    get choiceValues() {
+        if (this.type !== 'union')
+            return this.choices;
+        return this.options.flatMap((o) => (o.type === 'boolean' ? [true, false] : o.choices));
+    }
+    /** The member of a union that is not a fixed value (a number, a string ...), edited after "Custom...". */
+    get openOption() { return this.options.find((o) => !['literal', 'enum', 'boolean'].includes(o.type)); }
+    /** What a new entry (in a list or a map) starts as: the default if there is one, otherwise the simplest valid shape. */
+    initial() {
+        const def = this.schema._zod.def;
+        if (def.type === 'default')
+            return structuredClone(def.defaultValue);
+        switch (this.type) {
+            case 'boolean': return false;
+            case 'number': return this.min ?? 0;
+            case 'string': return '';
+            case 'enum':
+            case 'literal': return this.choices[0];
+            case 'union': return this.options[0]?.initial();
+            case 'array': return [];
+            case 'record': return {};
+            case 'object': return Object.fromEntries(this.children().filter(([, c]) => !['optional', 'default'].includes(c.schema._zod.def.type)).map(([name, c]) => [name, c.initial()]));
+            default: return null;
+        }
+    }
+    /** Is `value` acceptable here on its own? (The whole file is checked again when it is saved.) */
+    check(value) {
+        const result = this.schema.safeParse(value);
+        return result.success ? true : result.error.issues.map((i) => (i.path.length ? i.path.join('.') + ': ' : '') + i.message).join('; ');
+    }
+}

package/dist/cli/{menu-multi.d.ts → menu/several.d.ts}

@@ -1,4 +1,5 @@
-import type { Context } from './commands/context.js';
+import type { Context } from '../commands/context.js';
+import { App } from '../tui/index.js';
 /** Folders worth offering: this one, the projects started before, and the folders inside your roots. */
 export declare const candidateFolders: (ctx: Context, cwd?: string) => string[];
 /** The command line for several sessions: one --session per (agent, folder), with the shared options. */
@@ -9,4 +10,11 @@ export declare const severalAgentsArgv: (sessions: {
     headless: boolean;
     attachFirst: boolean;
 }) => string[];
-export declare const askSeveralAgents: (ctx: Context) => Promise<string[] | null>;
+export declare class SeveralAgents {
+    private readonly app;
+    private readonly ctx;
+    private readonly path;
+    constructor(app: App, ctx: Context);
+    run(): Promise<string[] | null>;
+    private folders;
+}

package/dist/cli/menu/several.js

@@ -0,0 +1,102 @@
+// "Start several agents": projects, then agents for each, then where to attach. It only builds a command line
+// (sandbox launch --session <agent>@<folder> ...), so "repeat last" works and typing it does the same.
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertSafeWorkspace } from '../../core/safe-paths.js';
+import { errMsg, expandPath } from '../../core/util.js';
+import { readKnown } from '../../host/projects.js';
+import { isWithin } from '../../shared/projects.js';
+import { commandLine } from '../history.js';
+import { Text, Theme } from '../tui/index.js';
+/** Folders worth offering: this one, the projects started before, and the folders inside your roots. */
+export const candidateFolders = (ctx, cwd = process.cwd()) => {
+    const roots = ctx.loaded.config.projects.roots.map((r) => expandPath(r, ctx.loaded.base));
+    const inRoots = roots.flatMap((r) => { try {
+        return fs.readdirSync(r, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.isSymbolicLink() && !e.name.startsWith('.')).slice(0, 200).map((e) => path.join(r, e.name));
+    }
+    catch {
+        return [];
+    } });
+    const all = [path.resolve(cwd), ...readKnown(ctx.storageRoot).map((k) => k.host), ...inRoots];
+    return all.filter((f, i) => all.findIndex((g) => g.toLowerCase() === f.toLowerCase()) === i && fs.existsSync(f));
+};
+/** The command line for several sessions: one --session per (agent, folder), with the shared options. */
+export const severalAgentsArgv = (sessions, o) => ['launch', ...sessions.flatMap((s) => ['--session', s.harness + '@' + s.folder]), ...(o.headless ? ['--headless'] : []), ...(o.attachFirst ? ['-t'] : [])];
+const ADD = '@add';
+export class SeveralAgents {
+    app;
+    ctx;
+    path = ['Start several agents'];
+    constructor(app, ctx) {
+        this.app = app;
+        this.ctx = ctx;
+    }
+    async run() {
+        const folders = await this.folders();
+        if (!folders?.length)
+            return null;
+        const agents = Object.keys(this.ctx.loaded.config.harnesses);
+        const sessions = [];
+        for (const folder of folders) {
+            const picked = await this.app.list({
+                path: [...this.path, path.basename(folder)], intro: 'Agents for ' + folder + ' (one session each). Space ticks, Enter continues.', multi: true,
+                items: agents.map((a) => ({ value: a, label: a, checked: a === this.ctx.loaded.config.defaultHarness })),
+            });
+            if (picked.kind !== 'multi')
+                return null;
+            sessions.push(...picked.values.map((harness) => ({ harness, folder })));
+        }
+        if (!sessions.length)
+            return null;
+        const headless = await this.app.confirm({ path: this.path, question: 'Hide the sandbox window (headless)?', about: ['sandbox show brings it back.'], initial: this.ctx.loaded.config.sandbox.headless });
+        const attach = await this.app.choose(this.path, 'Attach this terminal to one of them? Each session also has a tab inside the sandbox; sandbox attach shows any of them later.', [
+            { value: -1, label: 'None' },
+            ...sessions.map((s, i) => ({ value: i, label: s.harness + ' in ' + Text.middle(s.folder, 60) })),
+        ], 0);
+        if (attach === undefined)
+            return null;
+        // The one to attach goes first: -t attaches the first session.
+        const ordered = attach >= 0 ? [sessions[attach], ...sessions.filter((_s, i) => i !== attach)] : sessions;
+        const argv = severalAgentsArgv(ordered, { headless, attachFirst: attach >= 0 });
+        const projects = [...new Set(sessions.map((s) => path.basename(s.folder)))];
+        const go = await this.app.confirm({
+            path: this.path, question: 'Start them?',
+            about: ['One sandbox with ' + sessions.length + ' session' + (sessions.length === 1 ? '' : 's') + ': ' + ordered.map((s) => s.harness + ' in ' + path.basename(s.folder)).join(', ') + '. Maps ' + projects.join(' and ') + '.', '', '$ ' + commandLine(argv)],
+        });
+        return go ? argv : null;
+    }
+    async folders() {
+        const here = path.resolve(process.cwd());
+        const candidates = candidateFolders(this.ctx);
+        const picked = await this.app.list({
+            path: this.path, intro: 'Which projects? Each gets its own sessions; all of them are mapped into one sandbox. Space ticks, Enter continues.', multi: true,
+            items: [
+                ...candidates.map((f) => ({ value: f, label: Text.middle(f, 90), hint: isWithin(f, here) && isWithin(here, f) ? Theme.muted('this folder') : undefined, checked: f.toLowerCase() === here.toLowerCase() })),
+                { value: ADD, label: '+ Another folder…' },
+            ],
+        });
+        if (picked.kind !== 'multi')
+            return null;
+        const folders = picked.values.filter((f) => f !== ADD);
+        if (picked.values.includes(ADD)) {
+            const extra = await this.app.text({
+                path: this.path, label: 'Folder to add',
+                validate: (v) => {
+                    const dir = path.resolve(v.trim());
+                    if (!v.trim() || !fs.existsSync(dir) || !fs.statSync(dir).isDirectory())
+                        return 'Not a folder: ' + dir;
+                    try {
+                        assertSafeWorkspace(dir, this.ctx.packageRoot, this.ctx.storageRoot);
+                        return true;
+                    }
+                    catch (e) {
+                        return errMsg(e);
+                    }
+                },
+            });
+            if (extra)
+                folders.push(path.resolve(extra.trim()));
+        }
+        return folders;
+    }
+}

package/dist/cli/tui/app.d.ts

@@ -0,0 +1,39 @@
+import { MessageScreen, type ConfirmOptions, type TextOptions } from './dialogs.js';
+import { type FrameParts } from './frame.js';
+import { type ListOptions, type ListResult } from './list-screen.js';
+import { Terminal, type Key } from './terminal.js';
+export interface Size {
+    width: number;
+    height: number;
+}
+/** What a screen's key handler returns: `{ done: value }` ends the screen, nothing keeps it open (and redraws it). */
+export type Step<T> = {
+    done: T;
+} | undefined | void;
+export interface Screen<T> {
+    render(size: Size): FrameParts;
+    handle(key: Key): Step<T> | Promise<Step<T>>;
+}
+export declare class App {
+    readonly terminal: Terminal;
+    /** The status line for screens that do not set their own (refreshed on every draw). */
+    status: () => string;
+    constructor(terminal?: Terminal);
+    /** Shows `screen` until its handler says it is done, and returns what it returned. */
+    show<T>(screen: Screen<T>): Promise<T>;
+    list<T>(o: ListOptions<T>): Promise<ListResult<T>>;
+    text(o: TextOptions): Promise<string | undefined>;
+    confirm(o: ConfirmOptions): Promise<boolean>;
+    message(o: ConstructorParameters<typeof MessageScreen>[0]): Promise<void>;
+    /** One of a few values (undefined = back). */
+    choose<T>(path: string[], intro: string, choices: {
+        value: T;
+        label: string;
+        description?: string;
+        hint?: string;
+    }[], current?: T): Promise<T | undefined>;
+    /** Runs `work` on the normal screen (command output, interactive commands); the next show() takes the screen back. */
+    suspend<T>(work: () => Promise<T>): Promise<T>;
+    /** Leaves the alternate screen for good. */
+    close(): void;
+}

package/dist/cli/tui/app.js

@@ -0,0 +1,52 @@
+// The menu as an application: screens are shown one at a time in the frame, each until it is done. Commands that print
+// (or take over the terminal) run with the terminal handed back, and the next screen takes it again.
+import { ConfirmScreen, MessageScreen, TextScreen } from './dialogs.js';
+import { Frame } from './frame.js';
+import { ListScreen } from './list-screen.js';
+import { Terminal } from './terminal.js';
+import { Theme } from './theme.js';
+export class App {
+    terminal;
+    /** The status line for screens that do not set their own (refreshed on every draw). */
+    status = () => '';
+    constructor(terminal = new Terminal()) {
+        this.terminal = terminal;
+    }
+    /** Shows `screen` until its handler says it is done, and returns what it returned. */
+    async show(screen) {
+        this.terminal.start();
+        const draw = () => {
+            const { width, height } = this.terminal;
+            const parts = screen.render({ width, height: Frame.bodyHeight(height) });
+            this.terminal.render(Frame.render({ ...parts, status: parts.status ?? this.status() }, width, height));
+        };
+        this.terminal.onResized(draw);
+        try {
+            for (;;) {
+                draw();
+                const step = await screen.handle(await this.terminal.key());
+                if (step)
+                    return step.done;
+            }
+        }
+        finally {
+            this.terminal.onResized(null);
+        }
+    }
+    list(o) { return this.show(new ListScreen(o)); }
+    text(o) { return this.show(new TextScreen(o)); }
+    confirm(o) { return this.show(new ConfirmScreen(o)); }
+    message(o) { return this.show(new MessageScreen(o)); }
+    /** One of a few values (undefined = back). */
+    async choose(path, intro, choices, current) {
+        const picked = await this.list({ path, intro, items: choices.map((c) => ({ ...c, icon: c.value === current ? Theme.ok(Theme.glyph.on) : Theme.muted(Theme.glyph.off) })), startAt: current });
+        return picked.kind === 'pick' ? picked.value : undefined;
+    }
+    /** Runs `work` on the normal screen (command output, interactive commands); the next show() takes the screen back. */
+    async suspend(work) {
+        this.terminal.stop();
+        return work();
+    }
+    /** Leaves the alternate screen for good. */
+    close() { this.terminal.stop(); }
+}

package/dist/cli/tui/dialogs.d.ts

@@ -0,0 +1,57 @@
+import type { FrameParts } from './frame.js';
+import type { Screen, Size, Step } from './app.js';
+import type { Key } from './terminal.js';
+export interface TextOptions {
+    path: string[];
+    label: string;
+    /** Explanation above the field (plain lines). */
+    about?: string[];
+    initial?: string;
+    placeholder?: string;
+    /** true = fine, a string = what is wrong (shown under the field). */
+    validate?: (value: string) => true | string;
+    /** Allow an empty answer (otherwise Enter on an empty field cancels). */
+    allowEmpty?: boolean;
+}
+/** One line of text. Resolves to the text, or undefined when you press Esc. */
+export declare class TextScreen implements Screen<string | undefined> {
+    private readonly o;
+    private value;
+    private cursor;
+    private problem;
+    constructor(o: TextOptions);
+    render(size: Size): FrameParts;
+    handle(key: Key): Step<string | undefined>;
+    private check;
+}
+export interface ConfirmOptions {
+    path: string[];
+    question: string;
+    about?: string[];
+    yes?: string;
+    no?: string;
+    initial?: boolean;
+    danger?: boolean;
+}
+/** Yes or no. Esc answers no. */
+export declare class ConfirmScreen implements Screen<boolean> {
+    private readonly o;
+    private yes;
+    constructor(o: ConfirmOptions);
+    render(size: Size): FrameParts;
+    handle(key: Key): Step<boolean>;
+}
+/** Text to read (scrolls); any key but the arrows closes it. */
+export declare class MessageScreen implements Screen<void> {
+    private readonly o;
+    private offset;
+    private height;
+    constructor(o: {
+        path: string[];
+        title?: string;
+        lines: string[];
+        tone?: 'ok' | 'warn' | 'error';
+    });
+    render(size: Size): FrameParts;
+    handle(key: Key): Step<void>;
+}

package/dist/cli/tui/dialogs.js

@@ -0,0 +1,162 @@
+import { Text } from './text.js';
+import { Theme } from './theme.js';
+/** Plain lines are wrapped to the width; coloured ones are kept as they are (the frame cuts them). */
+const paragraphs = (lines, width) => lines.flatMap((l) => (Text.strip(l) === l ? Text.wrap(l, width - 4) : [l]).map((x) => '  ' + x));
+/** One line of text. Resolves to the text, or undefined when you press Esc. */
+export class TextScreen {
+    o;
+    value;
+    cursor;
+    problem;
+    constructor(o) {
+        this.o = o;
+        this.value = o.initial ?? '';
+        this.cursor = [...this.value].length;
+    }
+    render(size) {
+        const width = Math.min(size.width - 4, 100);
+        const chars = [...this.value];
+        // Scroll the field so the cursor stays visible.
+        const inner = width - 4;
+        const start = Math.max(0, this.cursor - inner + 1);
+        const shown = chars.slice(start, start + inner);
+        const before = shown.slice(0, this.cursor - start).join('');
+        const at = shown[this.cursor - start] ?? ' ';
+        const after = shown.slice(this.cursor - start + 1).join('');
+        const text = this.value === '' && this.o.placeholder ? Theme.muted(this.o.placeholder) : before + (Theme.colour ? '\x1b[7m' + at + '\x1b[27m' : '_') + after;
+        const body = [
+            '',
+            '  ' + Theme.bold(this.o.label),
+            ...(this.o.about?.length ? paragraphs(this.o.about, size.width).map((l) => Theme.muted(l)) : []),
+            '',
+            '  ' + Theme.accent('╭' + '─'.repeat(width - 2) + '╮'),
+            '  ' + Theme.accent('│') + ' ' + Text.fit(text, inner) + ' ' + Theme.accent('│'),
+            '  ' + Theme.accent('╰' + '─'.repeat(width - 2) + '╯'),
+            this.problem ? '  ' + Theme.error(Theme.glyph.cross + ' ' + this.problem) : '',
+        ];
+        return { path: this.o.path, body, keys: [['↵', 'save'], ['esc', 'cancel'], ['ctrl+u', 'clear'], ['←→', 'move']] };
+    }
+    handle(key) {
+        const chars = [...this.value];
+        const set = (next, cursor) => { this.value = next.join(''); this.cursor = Math.max(0, Math.min(next.length, cursor)); this.check(); };
+        if (key.name === 'escape')
+            return { done: undefined };
+        if (key.name === 'return') {
+            if (this.value === '' && !this.o.allowEmpty)
+                return { done: undefined };
+            const verdict = this.o.validate?.(this.value) ?? true;
+            if (verdict !== true) {
+                this.problem = verdict;
+                return;
+            }
+            return { done: this.value };
+        }
+        if (key.name === 'left') {
+            this.cursor = Math.max(0, this.cursor - 1);
+            return;
+        }
+        if (key.name === 'right') {
+            this.cursor = Math.min(chars.length, this.cursor + 1);
+            return;
+        }
+        if (key.name === 'home') {
+            this.cursor = 0;
+            return;
+        }
+        if (key.name === 'end') {
+            this.cursor = chars.length;
+            return;
+        }
+        if (key.name === 'backspace') {
+            if (this.cursor > 0)
+                set([...chars.slice(0, this.cursor - 1), ...chars.slice(this.cursor)], this.cursor - 1);
+            return;
+        }
+        if (key.name === 'delete') {
+            set([...chars.slice(0, this.cursor), ...chars.slice(this.cursor + 1)], this.cursor);
+            return;
+        }
+        if (key.ctrl && key.name === 'u') {
+            set([], 0);
+            return;
+        }
+        if (key.text) {
+            const add = [...key.text.replace(/[\r\n]/g, '')];
+            set([...chars.slice(0, this.cursor), ...add, ...chars.slice(this.cursor)], this.cursor + add.length);
+        }
+        return;
+    }
+    check() {
+        const verdict = this.value === '' ? true : this.o.validate?.(this.value) ?? true;
+        this.problem = verdict === true ? undefined : verdict;
+    }
+}
+/** Yes or no. Esc answers no. */
+export class ConfirmScreen {
+    o;
+    yes;
+    constructor(o) {
+        this.o = o;
+        this.yes = o.initial ?? true;
+    }
+    render(size) {
+        const button = (label, on, danger = false) => (on ? (danger ? Theme.colour ? '\x1b[48;5;160m\x1b[97m ' + label + ' \x1b[0m' : '[' + label + ']' : Theme.selected(' ' + label + ' ')) : Theme.muted(' ' + label + ' '));
+        const body = [
+            '',
+            '  ' + Theme.bold(this.o.question),
+            ...(this.o.about?.length ? ['', ...paragraphs(this.o.about, size.width)] : []),
+            '',
+            '  ' + button(this.o.yes ?? 'Yes', this.yes, this.o.danger) + '   ' + button(this.o.no ?? 'No', !this.yes),
+        ];
+        return { path: this.o.path, body, keys: [['←→', 'choose'], ['↵', 'confirm'], ['y/n', 'answer'], ['esc', 'no']] };
+    }
+    handle(key) {
+        if (key.name === 'left' || key.name === 'right' || key.name === 'tab') {
+            this.yes = !this.yes;
+            return;
+        }
+        if (key.text?.toLowerCase() === 'y')
+            return { done: true };
+        if (key.text?.toLowerCase() === 'n' || key.name === 'escape')
+            return { done: false };
+        if (key.name === 'return')
+            return { done: this.yes };
+        return;
+    }
+}
+/** Text to read (scrolls); any key but the arrows closes it. */
+export class MessageScreen {
+    o;
+    offset = 0;
+    height = 10;
+    constructor(o) {
+        this.o = o;
+    }
+    render(size) {
+        const paint = this.o.tone === 'ok' ? Theme.ok : this.o.tone === 'warn' ? Theme.warn : this.o.tone === 'error' ? Theme.error : Theme.bold;
+        const head = this.o.title ? ['', '  ' + paint(this.o.title), ''] : [''];
+        const lines = this.o.lines.flatMap((l) => (Text.width(l) > size.width - 4 && Text.strip(l) === l ? Text.wrap(l, size.width - 4) : [l])).map((l) => '  ' + l);
+        this.height = size.height - head.length;
+        this.offset = Math.max(0, Math.min(this.offset, lines.length - this.height));
+        return { path: this.o.path, body: [...head, ...lines.slice(this.offset, this.offset + this.height)], keys: lines.length > this.height ? [['↑↓', 'scroll'], ['↵', 'close']] : [['any key', 'close']] };
+    }
+    handle(key) {
+        if (key.name === 'up') {
+            this.offset--;
+            return;
+        }
+        if (key.name === 'down') {
+            this.offset++;
+            return;
+        }
+        if (key.name === 'pageup') {
+            this.offset -= this.height;
+            return;
+        }
+        if (key.name === 'pagedown') {
+            this.offset += this.height;
+            return;
+        }
+        return { done: undefined };
+    }
+}

package/dist/cli/tui/frame.d.ts

@@ -0,0 +1,18 @@
+export interface FrameParts {
+    /** Where you are, e.g. ['Settings', 'Languages and tools']. */
+    path: string[];
+    /** Short line under the title (what is running, which folder). */
+    status?: string;
+    body: string[];
+    /** [key, what it does] pairs, e.g. [['↵', 'open'], ['esc', 'back']]. */
+    keys: [string, string][];
+    /** A message for the last action (saved, invalid ...), shown above the footer. */
+    notice?: string;
+}
+export declare class Frame {
+    static title: string;
+    static version: string;
+    /** Rows the body may use on a terminal `height` rows high (title, status, two rules, notice and keys take 6). */
+    static bodyHeight(height: number): number;
+    static render(parts: FrameParts, width: number, height: number): string[];
+}

package/dist/cli/tui/frame.js

@@ -0,0 +1,27 @@
+// The frame every screen is drawn in: a title bar with where you are, a status line, the screen's own body and a footer
+// with the keys that work here.
+import { Text } from './text.js';
+import { Theme } from './theme.js';
+export class Frame {
+    static title = 'Windows Development Sandbox';
+    static version = '';
+    /** Rows the body may use on a terminal `height` rows high (title, status, two rules, notice and keys take 6). */
+    static bodyHeight(height) {
+        return Math.max(3, height - 6);
+    }
+    static render(parts, width, height) {
+        const w = width - 1;
+        const crumbs = [Frame.title, ...parts.path].map((p, i, all) => (i === all.length - 1 ? Theme.bold(p) : p)).join(Theme.dim(' › '));
+        const right = Frame.version ? 'v' + Frame.version + ' ' : '';
+        const title = Theme.bar(Text.fit(' ' + Theme.accent('◆') + ' ' + crumbs, w - Text.width(right)) + right);
+        const status = ' ' + Text.truncate(parts.status ?? '', w - 2);
+        const rule = Theme.dim(Theme.glyph.line.repeat(w));
+        const bodyRows = Frame.bodyHeight(height);
+        const body = parts.body.slice(0, bodyRows);
+        while (body.length < bodyRows)
+            body.push('');
+        const notice = parts.notice ? ' ' + Text.truncate(parts.notice, w - 2) : '';
+        const keys = ' ' + parts.keys.map(([k, what]) => Theme.key(k) + ' ' + Theme.muted(what)).join('  ');
+        return [title, status, rule, ...body, notice, rule, Text.truncate(keys, w)];
+    }
+}

package/dist/cli/tui/index.d.ts

@@ -0,0 +1,7 @@
+export { App, type Screen, type Size, type Step } from './app.js';
+export { ConfirmScreen, MessageScreen, TextScreen } from './dialogs.js';
+export { Frame } from './frame.js';
+export { ListScreen, type Category, type ListItem, type ListOptions, type ListResult, type Tab } from './list-screen.js';
+export { ExitRequested, Terminal, type Key } from './terminal.js';
+export { Text } from './text.js';
+export { Theme } from './theme.js';

package/dist/cli/tui/index.js

@@ -0,0 +1,8 @@
+// The menu's screen toolkit: a full-screen app (App) showing one screen at a time in a common frame.
+export { App } from './app.js';
+export { ConfirmScreen, MessageScreen, TextScreen } from './dialogs.js';
+export { Frame } from './frame.js';
+export { ListScreen } from './list-screen.js';
+export { ExitRequested, Terminal } from './terminal.js';
+export { Text } from './text.js';
+export { Theme } from './theme.js';