windows-development-sandbox 1.4.3 → 1.7.0

package/dist/cli/services/web-service.d.ts

@@ -0,0 +1,22 @@
+import type { SessionStatus } from '../../core/types.js';
+import type { WebBackend } from '../../host/web/index.js';
+import type { Endpoint } from '../../shared/pty/index.js';
+import type { NewSessionRequest, WebInfo, WebSession } from '../../shared/web/index.js';
+import type { Context } from '../commands/context.js';
+import { type ListedSession } from './sessions-service.js';
+/** A session as the browser may see it: no attach address or token, text made safe. */
+export declare function webSession(s: SessionStatus | ListedSession, viewers: number | null | undefined): WebSession;
+export declare class WebService implements WebBackend {
+    private readonly ctx;
+    private cached;
+    constructor(ctx: Context);
+    /** The running sandbox as this user sees it, or null when none runs. */
+    private view;
+    /** The sandbox is this user's, or another user's and shared with them. */
+    private mayUse;
+    private projects;
+    info(): Promise<WebInfo>;
+    sessions(): Promise<WebSession[]>;
+    endpoint(sessionId: string): Endpoint | null;
+    create(request: NewSessionRequest): Promise<WebSession>;
+}

package/dist/cli/services/web-service.js

@@ -0,0 +1,111 @@
+// What the web UI's server may do with the running sandbox: the same sessions, projects and rules as the CLI (another
+// user's sandbox is shown and used only as far as the sharing rules allow). Returns data, never prints.
+import path from 'node:path';
+import { fail, safeText } from '../../core/util/index.js';
+import { hostEndpoint, SandboxChannel } from '../../host/channel/index.js';
+import { insideSandbox, isSandboxRunning } from '../../host/sandbox/index.js';
+import { ownerRule } from '../../host/sharing/index.js';
+import { RunDir } from '../../shared/channel/index.js';
+import { lookAtSandbox } from '../commands/shared-use.js';
+import { registryOf } from '../commands/projects/here.js';
+import { SessionsService } from './sessions-service.js';
+/** The owner is asked (a process listing) at most this often: the browser polls. */
+const VIEW_TTL_MS = 3000;
+const SESSION_START_MS = 15 * 60 * 1000;
+const MAX_SESSIONS = 50;
+/** A session as the browser may see it: no attach address or token, text made safe. */
+export function webSession(s, viewers) {
+    return {
+        id: s.id,
+        harness: safeText(s.harness),
+        project: safeText(('projectName' in s ? s.projectName : undefined) ?? s.project ?? path.win32.basename(s.cwd)),
+        cwd: safeText(s.cwd),
+        phase: s.phase,
+        message: safeText(s.message).slice(0, 300),
+        startedAt: s.startedAt,
+        viewers: viewers ?? null,
+        canOpen: s.phase === 'running' && hostEndpoint(s) !== null,
+    };
+}
+export class WebService {
+    ctx;
+    cached = null;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** The running sandbox as this user sees it, or null when none runs. */
+    view() {
+        const now = Date.now();
+        if (this.cached && now - this.cached.at < VIEW_TTL_MS)
+            return this.cached.view;
+        const view = !insideSandbox() && isSandboxRunning() ? lookAtSandbox(this.ctx) : null;
+        this.cached = { at: now, view };
+        return view;
+    }
+    /** The sandbox is this user's, or another user's and shared with them. */
+    mayUse(view) {
+        return !view.owner || ownerRule(view.owner, { kind: 'use' }).kind === 'allow';
+    }
+    projects(view) {
+        const known = registryOf(view.ctx).read()?.projects ?? [];
+        if (known.length)
+            return known.map((p) => ({ name: p.name, guest: safeText(p.guest) }));
+        // A sandbox from before projects existed has only its launch folder.
+        const status = new RunDir(view.ctx.dataPath).readSandboxStatus();
+        return status ? [{ name: 'workspace', guest: safeText(status.guestWorkspace) }] : [];
+    }
+    info() {
+        const config = this.ctx.loaded.config;
+        const view = this.view();
+        return Promise.resolve({
+            sandbox: view ? 'running' : 'stopped',
+            owner: view?.line ?? null,
+            canUse: view !== null && this.mayUse(view),
+            harnesses: Object.keys(config.harnesses),
+            defaultHarness: config.defaultHarness,
+            projects: view && this.mayUse(view) ? this.projects(view) : [],
+        });
+    }
+    async sessions() {
+        const view = this.view();
+        if (!view || !this.mayUse(view))
+            return [];
+        const launchId = new RunDir(view.ctx.dataPath).readSandboxStatus()?.launchId;
+        const listed = await new SessionsService(view.ctx).list();
+        return listed
+            .filter((s) => s.launchId === launchId && (s.phase === 'running' || s.phase === 'starting'))
+            .reverse()
+            .slice(0, MAX_SESSIONS)
+            .map((s) => webSession(s, s.viewers === undefined ? undefined : (s.viewers?.viewers ?? null)));
+    }
+    endpoint(sessionId) {
+        const view = this.view();
+        if (!view || !this.mayUse(view))
+            return null;
+        const run = new RunDir(view.ctx.dataPath);
+        const session = run.readSession(sessionId);
+        if (!session || session.phase !== 'running' || session.launchId !== run.readSandboxStatus()?.launchId)
+            return null;
+        return hostEndpoint(session);
+    }
+    async create(request) {
+        const view = this.view();
+        if (!view)
+            return fail('No Windows Sandbox is running.', 'Start one with sandbox claude, then try again.');
+        if (view.owner && view.owner.kind !== 'none' && view.owner.kind !== 'mine') {
+            const rule = ownerRule(view.owner, { kind: 'use' });
+            if (rule.kind === 'refuse')
+                return fail(rule.reason, rule.fix);
+        }
+        const project = this.projects(view).find((p) => p.name === request.project);
+        if (!project)
+            return fail('The running sandbox has no project "' + request.project + '".');
+        const harness = view.ctx.loaded.config.harnesses[request.harness];
+        if (!harness)
+            return fail('There is no agent called "' + request.harness + '".');
+        const channel = new SandboxChannel(view.ctx.dataPath);
+        const id = channel.requestSession(request.harness, [], project.guest, { harnessSpec: harness });
+        const session = await channel.waitForSession(id, SESSION_START_MS, () => undefined);
+        return webSession(session, null);
+    }
+}

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

@@ -1,6 +1,9 @@
 import { type ConfirmOptions } from './dialogs/confirm-screen.js';
 import { MessageScreen } from './dialogs/message-screen.js';
 import { type TextOptions } from './dialogs/text-screen.js';
+import { type PathPickerOptions } from './dialogs/path-picker.js';
+import { type OverlayOptions } from './dialogs/overlay.js';
+import type { NavState } from './nav.js';
 import { type ListOptions, type ListResult } from './list/list-types.js';
 import { Terminal } from './terminal.js';
 import type { Screen } from './screen.js';
@@ -8,11 +11,24 @@ export declare class App {
     readonly terminal: Terminal;
     /** The status line for screens that do not set their own (refreshed on every draw). */
     status: () => string;
+    /** The navigation on the left of every screen (none: no navigation column). */
+    nav: () => NavState | undefined;
+    /** The screens being shown, innermost last: a dialog is drawn over the one below it. */
+    private readonly shown;
+    private redrawNow;
     constructor(terminal?: Terminal);
+    /** Draws the screen on top again now (before a slow piece of work, so its notice is visible). */
+    redraw(): void;
     /** Shows `screen` until its handler says it is done, and returns what it returned. */
     show<T>(screen: Screen<T>): Promise<T>;
+    /** A dialog over the screen below (Save / Discard / Cancel, Yes / No ...). */
+    dialog<T>(o: OverlayOptions<T>): Promise<T>;
+    /** Yes or no over the current screen; Esc is no. */
+    ask(title: string, lines: readonly string[], yes?: string, danger?: boolean): Promise<boolean>;
     list<T>(o: ListOptions<T>): Promise<ListResult<T>>;
     text(o: TextOptions): Promise<string | undefined>;
+    /** Choose a folder (or a file): the path on top, the folders to browse below. Undefined = cancelled. */
+    pickPath(o: PathPickerOptions): Promise<string | undefined>;
     confirm(o: ConfirmOptions): Promise<boolean>;
     message(o: ConstructorParameters<typeof MessageScreen>[0]): Promise<void>;
     /** One of a few values (undefined = back). */

package/dist/cli/tui/app.js

@@ -3,6 +3,8 @@
 import { ConfirmScreen } from './dialogs/confirm-screen.js';
 import { MessageScreen } from './dialogs/message-screen.js';
 import { TextScreen } from './dialogs/text-screen.js';
+import { PathPickerScreen } from './dialogs/path-picker.js';
+import { OverlayScreen } from './dialogs/overlay.js';
 import { Frame } from './frame.js';
 import { ListScreen } from './list/list-screen.js';
 import { Terminal } from './terminal.js';
@@ -11,17 +13,32 @@ export class App {
     terminal;
     /** The status line for screens that do not set their own (refreshed on every draw). */
     status = () => '';
+    /** The navigation on the left of every screen (none: no navigation column). */
+    nav = () => undefined;
+    /** The screens being shown, innermost last: a dialog is drawn over the one below it. */
+    shown = [];
+    redrawNow = null;
     constructor(terminal = new Terminal()) {
         this.terminal = terminal;
     }
+    /** Draws the screen on top again now (before a slow piece of work, so its notice is visible). */
+    redraw() {
+        this.redrawNow?.();
+    }
     /** Shows `screen` until its handler says it is done, and returns what it returned. */
     async show(screen) {
         this.terminal.start();
+        this.shown.push(screen);
+        const outer = this.redrawNow;
         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));
+            const nav = this.nav();
+            // A screen over the menu (a dialog, an editor) leaves the navigation visible but grey.
+            const covered = this.shown.length > 1;
+            const parts = screen.render({ width: Frame.bodyWidth(width, nav), height: Frame.bodyHeight(height) });
+            this.terminal.render(Frame.render({ ...parts, status: parts.status ?? this.status(), nav: nav && { ...nav, dimmed: nav.dimmed || covered } }, width, height));
         };
+        this.redrawNow = draw;
         this.terminal.onResized(draw);
         try {
             for (;;) {
@@ -32,15 +49,39 @@ export class App {
             }
         }
         finally {
-            this.terminal.onResized(null);
+            this.shown.pop();
+            this.redrawNow = outer;
+            this.terminal.onResized(outer);
         }
     }
+    /** A dialog over the screen below (Save / Discard / Cancel, Yes / No ...). */
+    dialog(o) {
+        const below = this.shown[this.shown.length - 1];
+        return this.show(new OverlayScreen(below ?? { render: () => ({ path: [], body: [], keys: [] }) }, o));
+    }
+    /** Yes or no over the current screen; Esc is no. */
+    ask(title, lines, yes = 'Yes', danger = false) {
+        return this.dialog({
+            title,
+            lines,
+            choices: [
+                { value: true, label: yes, key: 'y', danger },
+                { value: false, label: 'Cancel', key: 'n' },
+            ],
+            initial: danger ? 1 : 0,
+            escape: false,
+        });
+    }
     list(o) {
         return this.show(new ListScreen(o));
     }
     text(o) {
         return this.show(new TextScreen(o));
     }
+    /** Choose a folder (or a file): the path on top, the folders to browse below. Undefined = cancelled. */
+    pickPath(o) {
+        return this.show(new PathPickerScreen(o));
+    }
     confirm(o) {
         return this.show(new ConfirmScreen(o));
     }

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

@@ -0,0 +1,34 @@
+import type { FrameParts } from '../frame.js';
+import type { Screen, Size, Step } from '../screen.js';
+import type { Key } from '../terminal.js';
+export interface OverlayChoice<T> {
+    readonly value: T;
+    readonly label: string;
+    /** Pressing this letter picks it. */
+    readonly key: string;
+    readonly danger?: boolean;
+}
+export interface OverlayOptions<T> {
+    readonly title: string;
+    readonly lines: readonly string[];
+    readonly choices: readonly OverlayChoice<T>[];
+    /** Index of the choice that is highlighted first. */
+    readonly initial?: number;
+    /** Chosen by Esc. */
+    readonly escape: T;
+}
+/** `box` drawn over the middle of `base` rows; what is around the box is dimmed. Pure. */
+export declare function overlayBox(base: readonly string[], box: readonly string[], width: number): string[];
+/** The box itself: a title, the lines and the choices as buttons. Pure. */
+export declare function dialogBox(o: Pick<OverlayOptions<unknown>, 'title' | 'lines'> & {
+    buttons: string;
+}, maxWidth: number): string[];
+/** Shows `background` with a dialog over it. Left/right or the letters choose, Enter confirms, Esc cancels. */
+export declare class OverlayScreen<T> implements Screen<T> {
+    private readonly background;
+    private readonly o;
+    private index;
+    constructor(background: Pick<Screen<unknown>, 'render'>, o: OverlayOptions<T>);
+    render(size: Size): FrameParts;
+    handle(key: Key): Step<T>;
+}

package/dist/cli/tui/dialogs/overlay.js

@@ -0,0 +1,104 @@
+import { Text } from '../text.js';
+import { Theme } from '../theme.js';
+/** Columns [from, to) of plain text. */
+function sliceColumns(plain, from, to) {
+    let column = 0;
+    let out = '';
+    for (const ch of plain) {
+        const w = Text.charWidth(ch.codePointAt(0));
+        if (column >= from && column + w <= to)
+            out += ch;
+        column += w;
+    }
+    return out;
+}
+/** `box` drawn over the middle of `base` rows; what is around the box is dimmed. Pure. */
+export function overlayBox(base, box, width) {
+    const boxWidth = Math.max(...box.map((l) => Text.width(l)));
+    const left = Math.max(0, Math.floor((width - 1 - boxWidth) / 2));
+    const top = Math.max(0, Math.floor((base.length - box.length) / 2));
+    return base.map((row, i) => {
+        const plain = Text.fit(Text.strip(row), width - 1);
+        const line = box[i - top];
+        if (line === undefined)
+            return Theme.dim(plain);
+        return (Theme.dim(sliceColumns(plain, 0, left)) +
+            '\x1b[0m' +
+            Text.fit(line, boxWidth) +
+            '\x1b[0m' +
+            Theme.dim(sliceColumns(plain, left + boxWidth, width - 1)));
+    });
+}
+/** The box itself: a title, the lines and the choices as buttons. Pure. */
+export function dialogBox(o, maxWidth) {
+    const inner = Math.max(24, Math.min(maxWidth - 6, 64));
+    const wrapped = o.lines.flatMap((l) => (l === '' ? [''] : Text.wrap(l, inner)));
+    const edge = (text) => Theme.accent(Theme.glyph.vline) + ' ' + Text.fit(text, inner) + ' ' + Theme.accent(Theme.glyph.vline);
+    const rule = (l, r) => Theme.accent(l + Theme.glyph.line.repeat(inner + 2) + r);
+    return [
+        rule('┌', '┐'),
+        edge(Theme.bold(o.title)),
+        edge(''),
+        ...wrapped.map((l) => edge(l)),
+        edge(''),
+        edge(o.buttons),
+        rule('└', '┘'),
+    ];
+}
+/** Shows `background` with a dialog over it. Left/right or the letters choose, Enter confirms, Esc cancels. */
+export class OverlayScreen {
+    background;
+    o;
+    index;
+    constructor(background, o) {
+        this.background = background;
+        this.o = o;
+        this.index = o.initial ?? 0;
+    }
+    render(size) {
+        const parts = this.background.render(size);
+        const buttons = this.o.choices
+            .map((c, i) => {
+            // The chosen button is in brackets too, so it shows without colour.
+            if (i !== this.index)
+                return Theme.muted('  ' + c.label + '  ');
+            const text = '[ ' + c.label + ' ]';
+            return c.danger && Theme.colour ? '\x1b[48;5;160m\x1b[97m' + text + '\x1b[0m' : Theme.selected(text);
+        })
+            .join('  ');
+        const box = dialogBox({ title: this.o.title, lines: this.o.lines, buttons: buttons }, size.width);
+        const body = parts.body.slice(0, size.height);
+        while (body.length < size.height)
+            body.push('');
+        return {
+            ...parts,
+            body: overlayBox(body, box, size.width),
+            notice: undefined,
+            keys: [
+                ['↵', 'confirm', 1],
+                ...this.o.choices.map((c) => [c.key, c.label.toLowerCase(), 2]),
+                ['←→', 'choose', 4],
+                ['esc', 'cancel', 0],
+            ],
+        };
+    }
+    handle(key) {
+        if (key.name === 'left') {
+            this.index = (this.index + this.o.choices.length - 1) % this.o.choices.length;
+            return;
+        }
+        if (key.name === 'right' || key.name === 'tab') {
+            this.index = (this.index + 1) % this.o.choices.length;
+            return;
+        }
+        if (key.name === 'return')
+            return { done: this.o.choices[this.index].value };
+        if (key.name === 'escape')
+            return { done: this.o.escape };
+        const pressed = key.text.toLowerCase();
+        const hit = pressed ? this.o.choices.find((c) => c.key === pressed) : undefined;
+        if (hit)
+            return { done: hit.value };
+        return;
+    }
+}

package/dist/cli/tui/dialogs/path-listing.d.ts

@@ -0,0 +1,43 @@
+export type EntryKind = 'drive' | 'up' | 'dir' | 'file' | 'link';
+export interface PickEntry {
+    readonly kind: EntryKind;
+    readonly name: string;
+    /** The full path it opens or picks ('' for the "This PC" level above a drive). */
+    readonly path: string;
+    /** Extra words: free space of a drive, "link". */
+    readonly detail?: string;
+}
+export interface Listing {
+    readonly entries: readonly PickEntry[];
+    /** Entries left out because of the cap. */
+    readonly more: number;
+    /** Why the folder could not be read. */
+    readonly error?: string;
+}
+/** Entries listed at most; the rest is counted ("... more"). */
+export declare const LIST_CAP = 2000;
+/** What was typed, split into the folder it names (or is in) and the start of a name in it. '' = This PC. */
+export declare function splitInput(input: string): {
+    dir: string;
+    prefix: string;
+};
+/** The folder above, or '' (This PC) above a drive's root. */
+export declare function parentOf(dir: string): string;
+/** `dir` with exactly one trailing backslash (for the input line). */
+export declare function withSeparator(dir: string): string;
+/**
+ * The folders (and files when asked) in `dir`. Links and junctions are listed, marked, never opened; unreadable
+ * folders give an error text; at most `cap` entries come back.
+ */
+export declare function listFolder(dir: string, files?: boolean, cap?: number): Listing;
+/** The drives of this PC with their free space ("This PC"). */
+export declare function listDrives(): PickEntry[];
+/** Entries whose name starts with `prefix` (no case), or contains `text` when filtering. */
+export declare function narrow(entries: readonly PickEntry[], prefix: string, text?: string): PickEntry[];
+/**
+ * Completes the last name of `input` from the folders listed: the longest start they share, and a backslash when
+ * exactly one folder fits. The input is returned unchanged when nothing fits.
+ */
+export declare function completeInput(input: string, folders: readonly PickEntry[]): string;
+/** A name for a new folder: not empty, no path characters, not . or .., not reserved. */
+export declare function folderNameProblem(name: string): string | null;

package/dist/cli/tui/dialogs/path-listing.js

@@ -0,0 +1,127 @@
+// What the path picker needs from the disk and from text, as plain functions (tested): splitting what was typed,
+// listing a folder without ever following links, completing a name, filtering, and the drives of "This PC".
+import fs from 'node:fs';
+import path from 'node:path';
+import { diskUsage } from '../../../core/disk.js';
+const win = path.win32;
+/** Entries listed at most; the rest is counted ("... more"). */
+export const LIST_CAP = 2000;
+const SEPARATOR = /[\\/]$/;
+/** What was typed, split into the folder it names (or is in) and the start of a name in it. '' = This PC. */
+export function splitInput(input) {
+    const text = input.trim();
+    if (text === '')
+        return { dir: '', prefix: '' };
+    if (/^[A-Za-z]:$/.test(text))
+        return { dir: text + '\\', prefix: '' };
+    if (SEPARATOR.test(text))
+        return { dir: text, prefix: '' };
+    const dir = win.dirname(text);
+    const base = win.basename(text);
+    // A bare name (no folder) has no folder to look in.
+    return dir === '.' ? { dir: '', prefix: base } : { dir, prefix: base };
+}
+/** The folder above, or '' (This PC) above a drive's root. */
+export function parentOf(dir) {
+    if (dir === '')
+        return '';
+    const parent = win.dirname(win.resolve(dir));
+    return parent.toLowerCase() === win.resolve(dir).toLowerCase() ? '' : parent;
+}
+/** `dir` with exactly one trailing backslash (for the input line). */
+export function withSeparator(dir) {
+    return dir === '' ? '' : dir.replace(/[\\/]+$/, '') + '\\';
+}
+/** Folders first, then files, each by name without regard to case. */
+function byKindThenName(a, b) {
+    const rank = (e) => (e.kind === 'file' ? 1 : 0);
+    return rank(a) - rank(b) || a.name.localeCompare(b.name, undefined, { sensitivity: 'base' });
+}
+/**
+ * The folders (and files when asked) in `dir`. Links and junctions are listed, marked, never opened; unreadable
+ * folders give an error text; at most `cap` entries come back.
+ */
+export function listFolder(dir, files = false, cap = LIST_CAP) {
+    let found;
+    try {
+        found = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch (e) {
+        const code = e.code;
+        return {
+            entries: [],
+            more: 0,
+            error: code === 'ENOENT' || code === 'ENOTDIR' ? 'No such folder' : 'Cannot open it',
+        };
+    }
+    const entries = [];
+    for (const d of found) {
+        const full = win.join(dir, d.name);
+        if (d.isSymbolicLink())
+            entries.push({ kind: 'link', name: d.name, path: full, detail: 'link' });
+        else if (d.isDirectory())
+            entries.push({ kind: 'dir', name: d.name, path: full });
+        else if (files)
+            entries.push({ kind: 'file', name: d.name, path: full });
+    }
+    entries.sort(byKindThenName);
+    return { entries: entries.slice(0, cap), more: Math.max(0, entries.length - cap) };
+}
+/** The drives of this PC with their free space ("This PC"). */
+export function listDrives() {
+    return diskUsage('C:\\').map((d) => ({
+        kind: 'drive',
+        name: d.drive,
+        path: d.drive,
+        detail: freeText(d.freeBytes, d.totalBytes),
+    }));
+}
+function freeText(free, total) {
+    const gb = (n) => (n / 1024 ** 3 >= 10 ? Math.round(n / 1024 ** 3) : (n / 1024 ** 3).toFixed(1)) + ' GB';
+    return gb(free) + ' free of ' + gb(total);
+}
+/** Entries whose name starts with `prefix` (no case), or contains `text` when filtering. */
+export function narrow(entries, prefix, text = '') {
+    const start = prefix.toLowerCase();
+    const inside = text.toLowerCase();
+    return entries.filter((e) => {
+        const name = e.name.toLowerCase();
+        return name.startsWith(start) && name.includes(inside);
+    });
+}
+/**
+ * Completes the last name of `input` from the folders listed: the longest start they share, and a backslash when
+ * exactly one folder fits. The input is returned unchanged when nothing fits.
+ */
+export function completeInput(input, folders) {
+    const { dir, prefix } = splitInput(input);
+    const names = folders
+        .filter((f) => f.kind === 'dir' && f.name.toLowerCase().startsWith(prefix.toLowerCase()))
+        .map((f) => f.name);
+    if (names.length === 0)
+        return input;
+    let common = names[0];
+    for (const name of names.slice(1)) {
+        let n = 0;
+        while (n < common.length && n < name.length && common[n].toLowerCase() === name[n].toLowerCase())
+            n++;
+        common = common.slice(0, n);
+    }
+    // Never shorten what was typed (the typed spelling wins when the listing only differs in case).
+    const completed = common.length >= prefix.length ? common : prefix;
+    const base = dir === '' ? '' : withSeparator(dir);
+    return base + completed + (names.length === 1 && completed.length === names[0].length ? '\\' : '');
+}
+/** A name for a new folder: not empty, no path characters, not . or .., not reserved. */
+export function folderNameProblem(name) {
+    const trimmed = name.trim();
+    if (trimmed === '')
+        return 'Type a name.';
+    if (/[<>:"/\\|?*\x00-\x1f]/.test(trimmed))
+        return 'A folder name cannot contain  < > : " / \\ | ? *';
+    if (/^\.+$/.test(trimmed) || /[. ]$/.test(trimmed))
+        return 'A folder name cannot end with a dot or a space.';
+    if (/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i.test(trimmed))
+        return '"' + trimmed + '" is a reserved name in Windows.';
+    return null;
+}

package/dist/cli/tui/dialogs/path-picker.d.ts

@@ -0,0 +1,67 @@
+import type { FrameParts } from '../frame.js';
+import type { Screen, Size, Step } from '../screen.js';
+import type { Key } from '../terminal.js';
+export interface PathPickerOptions {
+    path: string[];
+    title: string;
+    about?: string[];
+    /** The path in the input at first (also where the browser starts). */
+    initial?: string;
+    /** Show files (dim) and let them be picked; folders only by default. */
+    files?: boolean;
+    /** Label of the choose key, e.g. "use this folder". */
+    use?: string;
+    /** true = fine, a string = why this path cannot be chosen. */
+    validate?: (path: string) => true | string;
+    /** Typed words that are fine as they are (a setting that also takes "auto"). */
+    literals?: readonly string[];
+    /** A relative path may be typed too (it is kept as typed, not made absolute). */
+    relative?: boolean;
+}
+/** Resolves to the chosen path, or undefined when you press Esc. */
+export declare class PathPickerScreen implements Screen<string | undefined> {
+    private readonly o;
+    private mode;
+    private input;
+    private cursor;
+    private dir;
+    private listing;
+    private loadedDir;
+    private selected;
+    private scroll;
+    private filter;
+    private newName;
+    private problem;
+    private notice;
+    private rows;
+    constructor(o: PathPickerOptions);
+    render(size: Size): FrameParts;
+    handle(key: Key): Promise<Step<string | undefined>>;
+    /** The entries on screen: the folder's, narrowed by what is typed after the last backslash and by the filter. */
+    private visible;
+    private dirIsTyped;
+    private row;
+    private where;
+    private verdict;
+    private verdictLine;
+    private keys;
+    /** What choosing now would pick. In the browser a highlighted folder (or file) wins over the folder being shown. */
+    private candidate;
+    private choose;
+    /** Is this typed text kept as typed: one of the allowed words, or a relative path where those are allowed? */
+    private kept;
+    /** Reads the folder the input names (only when it changed), keeping what was typed as a filter. */
+    private syncListing;
+    private openDir;
+    private go;
+    private keepSelectedInView;
+    private typing;
+    private edit;
+    /** A path ending in a backslash is opened to look inside; any other typed path is chosen. */
+    private enterInput;
+    private browsing;
+    private open;
+    private filtering;
+    private startName;
+    private naming;
+}