windows-development-sandbox 1.5.0 → 1.9.0

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

@@ -9,6 +9,8 @@ export interface UpdateStatus {
     readonly scope: 'user' | 'machine' | null;
     readonly autoUpdate: boolean;
     readonly state: UpdateState;
+    /** Set when a failed update was undone and switched automatic updates off: the sentence to show (menu, CLI). */
+    readonly autoOffText?: string | null;
 }
 export interface CheckResult {
     readonly current: string;

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

@@ -9,7 +9,7 @@ import { errMsg, fail } from '../../core/util/index.js';
 import { packageVersion } from '../../core/package-info.js';
 import { InstallLayout, InstallRecordFile, UpdateTask, compareVersions } from '../../host/install/index.js';
 import { isSandboxRunning } from '../../host/sandbox/index.js';
-import { FolderFeed, GithubReleases, UpdateLock, Updater, UpdateStateFile, decideUpdate, isTooSoon, updateNotice, } from '../../host/update/index.js';
+import { FolderFeed, GithubReleases, UpdateLock, Updater, UpdateStateFile, autoOffText, decideUpdate, isTooSoon, updateNotice, } from '../../host/update/index.js';
 import { JsonFile } from '../../shared/io/index.js';
 /** The command for an install that is not managed (npm). */
 export const NPM_UPDATE_COMMAND = 'npm install -g windows-development-sandbox';
@@ -53,13 +53,17 @@ export class UpdateService {
     status() {
         const layout = this.layout;
         if (!layout)
-            return { managed: false, version: this.version, scope: null, autoUpdate: false, state: {} };
+            return { managed: false, version: this.version, scope: null, autoUpdate: false, state: {}, autoOffText: null };
+        const version = layout.activeVersion() ?? this.version;
+        const autoUpdate = new InstallRecordFile(layout.root).read()?.autoUpdate ?? false;
+        const state = new UpdateStateFile(layout.root).read();
         return {
             managed: true,
-            version: layout.activeVersion() ?? this.version,
+            version,
             scope: layout.scope,
-            autoUpdate: new InstallRecordFile(layout.root).read()?.autoUpdate ?? false,
-            state: new UpdateStateFile(layout.root).read(),
+            autoUpdate,
+            state,
+            autoOffText: !autoUpdate && state.autoOff ? autoOffText(state.autoOff.version, version) : null,
         };
     }
     /** Asks the source what is newest. Changes nothing (the time of the look is not recorded). */
@@ -92,7 +96,7 @@ export class UpdateService {
         if (!release)
             return null;
         try {
-            const updater = new Updater(layout, this.source, { now: this.now });
+            const updater = new Updater(layout, this.source, { now: this.now, task: this.task });
             return await updater.run({ sandboxRunning: this.sandboxRunning(), force: true });
         }
         finally {
@@ -129,6 +133,9 @@ export class UpdateService {
         const record = new InstallRecordFile(layout.root);
         if (!record.setAutoUpdate(on))
             fail('This install has no install.json.', 'Run the installer again: it writes the file.');
+        // Turned back on by the user: the "turned off by a failed update" remark is history.
+        if (on)
+            new UpdateStateFile(layout.root).update(({ autoOff: _gone, ...rest }) => rest);
     }
     /**
      * Should this CLI start update by itself? Only current-user installs (an all-users install has its scheduled task),

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

@@ -0,0 +1,28 @@
+import type { Config } from '../../core/types.js';
+import type { VpnProvider } from '../../core/schema/index.js';
+import { type LoginState, type VpnCredentials, type VpnLine } from '../../host/vpn/index.js';
+import type { Context } from '../commands/context.js';
+export interface VpnReport {
+    readonly enabled: boolean;
+    readonly provider: VpnProvider;
+    readonly protocol: Config['vpn']['protocol'];
+    readonly country: string;
+    readonly killSwitch: boolean;
+    readonly login: LoginState;
+    readonly loginSavedAt: string | null;
+    /** The running sandbox's tunnel, when one runs with the VPN on. */
+    readonly running: VpnLine | null;
+}
+/** The steps to get the NordVPN service credentials, in the words of Nord Account (shown before asking). */
+export declare const NORD_STEPS: readonly string[];
+export declare class VpnService {
+    private readonly ctx;
+    private readonly login;
+    constructor(ctx: Context);
+    private get config();
+    get provider(): VpnProvider;
+    report(): Promise<VpnReport>;
+    loginState(): LoginState;
+    save(credentials: VpnCredentials): void;
+    remove(): boolean;
+}

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

@@ -0,0 +1,46 @@
+import { isSandboxRunning } from '../../host/sandbox/index.js';
+import { hostPublicIp, readVpnLine, VpnLogin, } from '../../host/vpn/index.js';
+/** The steps to get the NordVPN service credentials, in the words of Nord Account (shown before asking). */
+export const NORD_STEPS = [
+    'Sign in at https://my.nordaccount.com with your usual NordVPN e-mail and password.',
+    'Open NordVPN, then "Set up NordVPN manually" (under Advanced settings).',
+    'Verify your e-mail if it asks, then copy the "Service credentials": a user name and a password.',
+    'These are NOT your account password. You can revoke them in the same place whenever you like.',
+];
+export class VpnService {
+    ctx;
+    login;
+    constructor(ctx) {
+        this.ctx = ctx;
+        this.login = new VpnLogin(ctx.storageRoot);
+    }
+    get config() {
+        return this.ctx.loaded.config.vpn;
+    }
+    get provider() {
+        return this.config.provider;
+    }
+    async report() {
+        const c = this.config;
+        const running = isSandboxRunning();
+        return {
+            enabled: c.enabled,
+            provider: c.provider,
+            protocol: c.protocol,
+            country: c.country,
+            killSwitch: c.killSwitch,
+            login: this.login.state(c.provider),
+            loginSavedAt: this.login.savedAt(c.provider),
+            running: running ? readVpnLine(this.ctx.dataPath, await hostPublicIp()) : null,
+        };
+    }
+    loginState() {
+        return this.login.state(this.provider);
+    }
+    save(credentials) {
+        this.login.save(this.provider, credentials);
+    }
+    remove() {
+        return this.login.remove(this.provider);
+    }
+}

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,23 +1,29 @@
 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 TabsState } from './frame.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';
 export declare class App {
     readonly terminal: Terminal;
-    /** The status line for screens that do not set their own (refreshed on every draw). */
+    /** The status line for screens that do not set their own (read on every draw: it must not wait for anything). */
     status: () => string;
-    /** The tabs shown across the top of every screen (none: no tab row). */
-    tabs: () => TabsState | undefined;
+    /** Awaited after an action changed something, before the screen loads what it shows again. */
+    afterAction: () => Promise<void>;
+    /** 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;
+    private redrawTimer;
     constructor(terminal?: Terminal);
     /** Draws the screen on top again now (before a slow piece of work, so its notice is visible). */
     redraw(): void;
+    /** Draws it again soon: what happens between two keys (a resize, fresh facts) is drawn once, not once each. */
+    requestRedraw(): 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 ...). */
@@ -26,6 +32,8 @@ export declare class App {
     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,27 +3,46 @@
 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';
 import { Theme } from './theme.js';
+/** Changes that arrive together (a resize, fresh facts) are drawn once, this long after the first. */
+const REDRAW_DELAY_MS = 16;
+/** While keys are waiting, the screen is still drawn at least this often. */
+const MAX_STALE_MS = 100;
 export class App {
     terminal;
-    /** The status line for screens that do not set their own (refreshed on every draw). */
+    /** The status line for screens that do not set their own (read on every draw: it must not wait for anything). */
     status = () => '';
-    /** The tabs shown across the top of every screen (none: no tab row). */
-    tabs = () => undefined;
+    /** Awaited after an action changed something, before the screen loads what it shows again. */
+    afterAction = () => Promise.resolve();
+    /** 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;
+    redrawTimer;
     constructor(terminal = new Terminal()) {
         this.terminal = terminal;
+        terminal.onResized(() => this.requestRedraw());
     }
     /** Draws the screen on top again now (before a slow piece of work, so its notice is visible). */
     redraw() {
         this.redrawNow?.();
     }
+    /** Draws it again soon: what happens between two keys (a resize, fresh facts) is drawn once, not once each. */
+    requestRedraw() {
+        if (this.redrawTimer)
+            return;
+        this.redrawTimer = setTimeout(() => {
+            this.redrawTimer = undefined;
+            if (this.terminal.running)
+                this.redrawNow?.();
+        }, REDRAW_DELAY_MS);
+    }
     /** Shows `screen` until its handler says it is done, and returns what it returned. */
     async show(screen) {
         this.terminal.start();
@@ -31,15 +50,22 @@ export class App {
         const outer = this.redrawNow;
         const draw = () => {
             const { width, height } = this.terminal;
-            const tabs = this.tabs();
-            const parts = screen.render({ width, height: Frame.bodyHeight(height, Boolean(tabs)) });
-            this.terminal.render(Frame.render({ ...parts, status: parts.status ?? this.status(), tabs: parts.tabs ?? tabs }, 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);
+        let drawnAt = 0;
         try {
             for (;;) {
-                draw();
+                // Keys that are already waiting (a held arrow, a paste) are handled first: the screen shows the result of the
+                // last one, but never stays stale for longer than MAX_STALE_MS.
+                if (!this.terminal.hasKeys || Date.now() - drawnAt >= MAX_STALE_MS) {
+                    draw();
+                    drawnAt = Date.now();
+                }
                 const step = await screen.handle(await this.terminal.key());
                 if (step)
                     return step.done;
@@ -48,7 +74,6 @@ export class App {
         finally {
             this.shown.pop();
             this.redrawNow = outer;
-            this.terminal.onResized(outer);
         }
     }
     /** A dialog over the screen below (Save / Discard / Cancel, Yes / No ...). */
@@ -75,6 +100,10 @@ export class App {
     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/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;
+}