windows-development-sandbox 1.4.3 → 1.5.0

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

@@ -0,0 +1,125 @@
+import { errMsg, fail, safeText } from '../../core/util/index.js';
+import { SandboxChannel } from '../../host/channel/index.js';
+import { RepoGuardStore } from '../../host/guard/index.js';
+import { SessionLedger } from '../../host/life/index.js';
+import { hideSandboxWindow, isSandboxRunning, showSandboxWindow } from '../../host/sandbox/index.js';
+import { RunDir } from '../../shared/channel/index.js';
+import { isWithin, projectForGuestDir } from '../../shared/paths/index.js';
+import { watcherRunning } from '../../sync/index.js';
+import { hereDir, locateHere, registryOf } from '../commands/projects/here.js';
+import { AccountsService } from './accounts-service.js';
+import { DatabasesService } from './databases-service.js';
+import { SessionsService, viewerText } from './sessions-service.js';
+export class SandboxService {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    isRunning() {
+        return isSandboxRunning();
+    }
+    /** Everything `status` shows. Text that comes from the sandbox goes through safeText. */
+    async status() {
+        const { ctx } = this;
+        const running = isSandboxRunning();
+        const run = new RunDir(ctx.dataPath);
+        const channel = new SandboxChannel(ctx.dataPath);
+        // The owner's repo guard, logins and watcher are their host state, outside the folders shared with this user.
+        const guard = ctx.borrowed ? null : new RepoGuardStore(ctx.dataPath);
+        const sandbox = run.readSandboxStatus();
+        const registry = running ? registryOf(ctx).read() : null;
+        const ready = running && sandbox?.phase === 'ready';
+        const daemon = ready
+            ? await channel.ping().then((r) => r.message, (e) => 'no answer (' + errMsg(e) + ')')
+            : '-';
+        const here = running ? locateHere(ctx, sandbox) : { project: null, guestDir: null };
+        const sessionList = running ? await new SessionsService(ctx).list() : [];
+        const provisioning = running ? run.listProjectStatus() : [];
+        const ports = ready && sandbox ? await new DatabasesService(ctx).runningPorts(sandbox.guestWorkspace) : null;
+        const findings = guard?.findings() ?? [];
+        const startedAt = Number(/^(\d+)-/.exec(registry?.launchId ?? sandbox?.launchId ?? '')?.[1]) || null;
+        const all = registry?.projects ?? [];
+        const facts = { here: here.project?.name ?? null, provisioning, sessions: sessionList, ports, findings };
+        const projects = all.map((p) => projectInfo(p, all, facts));
+        return {
+            sandbox: {
+                running,
+                phase: running ? (sandbox?.phase ?? 'unknown') : 'stopped',
+                message: sandbox?.message,
+                headless: sandbox?.headless,
+                startedAt: running ? startedAt : null,
+                daemon,
+                account: ctx.borrowed ? null : new AccountsService(ctx).activeName(),
+                syncWatcher: ctx.borrowed ? false : watcherRunning(ctx.dataPath),
+            },
+            here: { folder: hereDir(ctx), project: here.project?.name ?? null, guest: here.guestDir },
+            roots: registry?.roots ?? [],
+            projects,
+            otherSessions: sessionList
+                .filter((s) => s.phase === 'running' && !projects.some((p) => p.sessions.some((x) => x.id === s.id)))
+                .map((s) => ({ id: s.id, harness: safeText(s.harness), cwd: safeText(s.cwd) })),
+            repoGuard: {
+                guarded: guard?.guarded().length ?? 0,
+                findings: findings.map((f) => f.kind + ': ' + f.detail),
+            },
+        };
+    }
+    /** Brings the sandbox window to the front. */
+    showWindow() {
+        if (!showSandboxWindow(this.ctx.storageRoot))
+            fail('Could not find the Windows Sandbox window.', 'It may still be starting; try again in a few seconds.');
+    }
+    async hideWindow() {
+        if (!(await hideSandboxWindow(this.ctx.storageRoot, 5)))
+            fail('Could not find a visible Windows Sandbox window.', 'It may already be hidden (sbx-show brings it back).');
+    }
+    /** What stopping ends. Fails when this sandbox was not started by this tool. */
+    stopPlan() {
+        const sandbox = new RunDir(this.ctx.dataPath).readSandboxStatus() ??
+            fail('This sandbox was not started by this tool.', 'Close its window instead.');
+        // Stopping ends every project's sessions, not just this folder's.
+        const here = locateHere(this.ctx, sandbox);
+        const running = new SandboxChannel(this.ctx.dataPath).currentSessions();
+        const others = running.filter((s) => !(here.guestDir && isWithin(here.project?.guest ?? here.guestDir, s.cwd)));
+        return { sandbox, running, others };
+    }
+    /** Asks the sandbox to shut down (history and claude-mem sync back when it closes). */
+    async shutdown(sandbox) {
+        // On purpose, not a crash: its sessions are kept for the next start, and the watcher does not restart it. (Another
+        // user's sandbox: that record is theirs; its watcher sees a shutdown with nothing wrong.)
+        if (!this.ctx.borrowed)
+            new SessionLedger(this.ctx.storageRoot, this.ctx.dataPath).markClosedOnPurpose();
+        await new SandboxChannel(this.ctx.dataPath).exec(['C:\\Windows\\System32\\shutdown.exe', '/s', '/t', '2'], sandbox.guestWorkspace, 30);
+    }
+}
+/** One project: its setup, databases, running sessions and repo guard findings (sandbox text through safeText). */
+function projectInfo(p, all, facts) {
+    const prov = facts.provisioning.find((s) => s.name.toLowerCase() === p.name.toLowerCase());
+    const own = facts.sessions.filter((s) => s.phase === 'running' && projectForGuestDir(all, s.cwd)?.name === p.name);
+    const { ports } = facts;
+    return {
+        name: p.name,
+        host: p.host,
+        guest: p.guest,
+        mechanism: p.mechanism,
+        here: facts.here === p.name,
+        setup: prov
+            ? { phase: prov.phase, message: safeText(prov.message) }
+            : { phase: 'not set up yet', message: 'set up when you first start a session or command there' },
+        databases: (prov?.databases ?? []).map((d) => ({
+            database: safeText(d.database),
+            port: d.port,
+            state: ports ? (ports.has(d.port) ? 'running' : 'stopped') : 'unknown',
+        })),
+        sessions: own.map((s) => ({
+            id: s.id,
+            harness: safeText(s.harness),
+            viewers: viewerText(s.viewers),
+            started: s.startedAt,
+        })),
+        // With several guarded folders each finding starts with its folder.
+        repoGuard: facts.findings
+            .filter((f) => f.detail.toLowerCase().startsWith(p.host.toLowerCase() + ':'))
+            .map((f) => f.kind + ': ' + safeText(f.detail)),
+    };
+}

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

@@ -0,0 +1,42 @@
+import type { SessionStatus } from '../../core/types.js';
+import type { RegistryEntry } from '../../host/projects/index.js';
+import type { Viewers } from '../../shared/pty/index.js';
+import type { Context } from '../commands/context.js';
+export declare function viewerText(v: Viewers | null | undefined): string;
+export declare function projectOf(projects: RegistryEntry[], s: SessionStatus): string;
+/** A session with who is watching it and whether it is in the project of the current folder. */
+export type ListedSession = SessionStatus & {
+    readonly viewers?: Viewers | null;
+    readonly here?: boolean;
+    readonly projectName?: string;
+};
+/** Which sessions a restart touches: the current folder's project, or every session. */
+export interface RestartScope {
+    /** Guest folder of the project, or undefined for every session. */
+    readonly guest: string | undefined;
+    readonly projectName: string | undefined;
+    /** The folder is not a project of the running sandbox (and --all was not given): every session restarts. */
+    readonly notAProject: boolean;
+    readonly folder: string;
+}
+export declare class SessionsService {
+    private readonly ctx;
+    constructor(ctx: Context);
+    private get channel();
+    /** Sessions with who is watching them; `here` marks the ones in the project of the current folder. */
+    list(): Promise<ListedSession[]>;
+    /** This folder's project first, newest first within each group. */
+    ordered(list: readonly ListedSession[]): ListedSession[];
+    /** The project name to show for a session. */
+    projectName(s: SessionStatus): string;
+    runningCount(): number;
+    /** Running sessions, those in the guest folder first. */
+    running(guestDir: string | null): SessionStatus[];
+    /** The session to attach to: the one named, else the newest of the folder's project, else the newest. */
+    pick(sessionId?: string, guestDir?: string | null): SessionStatus;
+    /** What a restart from this folder touches. */
+    restartScope(all: boolean): RestartScope;
+    /** Restarts the agents (one kind, or all) of a project or of every session; returns the sandbox's message. */
+    restart(harness: string | null, scope?: string): Promise<string>;
+    private projects;
+}

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

@@ -0,0 +1,81 @@
+// Agent sessions of the running sandbox: list, pick one to attach to, restart. Returns data, never prints.
+import _ from 'lodash';
+import { SandboxChannel, sessionsFirstIn, sessionViewers } from '../../host/channel/index.js';
+import { isSandboxRunning } from '../../host/sandbox/index.js';
+import { RunDir } from '../../shared/channel/index.js';
+import { isWithin, projectForGuestDir } from '../../shared/paths/index.js';
+import { hereDir, locateHere, registryOf } from '../commands/projects/here.js';
+export function viewerText(v) {
+    return v === undefined
+        ? '-'
+        : v === null
+            ? 'unknown (older session)'
+            : v.remote + ' here, ' + (v.viewers - v.remote) + ' in sandbox';
+}
+export function projectOf(projects, s) {
+    return s.project ?? projectForGuestDir(projects, s.cwd)?.name ?? '-';
+}
+export class SessionsService {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    get channel() {
+        return new SandboxChannel(this.ctx.dataPath);
+    }
+    /** Sessions with who is watching them; `here` marks the ones in the project of the current folder. */
+    async list() {
+        // Who is attached comes from each session itself, so a terminal that was closed is never counted.
+        const live = isSandboxRunning();
+        // Only this sandbox's sessions are asked (and at most MAX_QUERIED_SESSIONS): the sandbox writes these files.
+        const ask = new Set(live ? this.channel.currentSessions().map((s) => s.id) : []);
+        const here = live ? locateHere(this.ctx, new RunDir(this.ctx.dataPath).readSandboxStatus()) : { guestDir: null };
+        const projects = this.projects();
+        return Promise.all(new RunDir(this.ctx.dataPath).listSessions().map(async (s) => ({
+            ...s,
+            projectName: projectOf(projects, s),
+            here: Boolean(here.guestDir && isWithin(here.guestDir, s.cwd)),
+            ...(ask.has(s.id) ? { viewers: await sessionViewers(s) } : {}),
+        })));
+    }
+    /** This folder's project first, newest first within each group. */
+    ordered(list) {
+        return [
+            ..._.sortBy(list.filter((s) => s.here), (s) => s.startedAt).reverse(),
+            ..._.sortBy(list.filter((s) => !s.here), (s) => s.startedAt).reverse(),
+        ];
+    }
+    /** The project name to show for a session. */
+    projectName(s) {
+        return projectOf(this.projects(), s);
+    }
+    runningCount() {
+        return this.channel.runningSessions().length;
+    }
+    /** Running sessions, those in the guest folder first. */
+    running(guestDir) {
+        return sessionsFirstIn(this.channel.runningSessions(), guestDir);
+    }
+    /** The session to attach to: the one named, else the newest of the folder's project, else the newest. */
+    pick(sessionId, guestDir = null) {
+        return this.channel.pickSession(sessionId, guestDir);
+    }
+    /** What a restart from this folder touches. */
+    restartScope(all) {
+        const here = locateHere(this.ctx, new RunDir(this.ctx.dataPath).readSandboxStatus());
+        const scope = all || !here.project ? undefined : here.project.guest;
+        return {
+            guest: scope,
+            projectName: scope ? here.project?.name : undefined,
+            notAProject: !scope && !all,
+            folder: hereDir(this.ctx),
+        };
+    }
+    /** Restarts the agents (one kind, or all) of a project or of every session; returns the sandbox's message. */
+    async restart(harness, scope) {
+        return (await this.channel.restart(harness, scope)).message;
+    }
+    projects() {
+        return registryOf(this.ctx).read()?.projects ?? [];
+    }
+}

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

@@ -0,0 +1,74 @@
+import { InstallLayout } from '../../host/install/index.js';
+import { type ReleaseInfo, type ReleaseSource, type UpdateNotice, type UpdateResult, type UpdateState } from '../../host/update/index.js';
+/** The command for an install that is not managed (npm). */
+export declare const NPM_UPDATE_COMMAND = "npm install -g windows-development-sandbox";
+export interface UpdateStatus {
+    /** Installed by the installer: it can update itself. */
+    readonly managed: boolean;
+    readonly version: string;
+    readonly scope: 'user' | 'machine' | null;
+    readonly autoUpdate: boolean;
+    readonly state: UpdateState;
+}
+export interface CheckResult {
+    readonly current: string;
+    readonly latest: ReleaseInfo | null;
+    /** A newer version exists and has not failed before. */
+    readonly available: boolean;
+    /** A newer version exists but failed to install; only a still newer one is tried. */
+    readonly blocked: boolean;
+}
+/** The scheduled task, as the service needs it (a fake in tests). */
+export interface UpdateTaskPort {
+    register(): void;
+    remove(): void;
+}
+export interface UpdateServiceOptions {
+    readonly source?: ReleaseSource;
+    readonly sandboxRunning?: () => boolean;
+    readonly task?: UpdateTaskPort;
+    readonly version?: string;
+    /** Where this user's "already told you" marker lives. */
+    readonly userDir?: string;
+    readonly now?: () => Date;
+}
+/** The Windows service account the scheduled task runs as: it may not use a folder feed. */
+export declare function runsAsSystem(env?: NodeJS.ProcessEnv, username?: string): boolean;
+export declare class UpdateService {
+    private readonly layout;
+    private readonly options;
+    private readonly source;
+    private readonly sandboxRunning;
+    private readonly version;
+    private readonly now;
+    private readonly task;
+    constructor(layout: InstallLayout | null, options?: UpdateServiceOptions);
+    /** The service for the install this package runs from; `feed` is a folder with feed.json (tests, offline). */
+    static forPackage(packageRoot: string, feed?: string, options?: UpdateServiceOptions): UpdateService;
+    get managed(): boolean;
+    status(): UpdateStatus;
+    /** Asks the source what is newest. Changes nothing (the time of the look is not recorded). */
+    check(): Promise<CheckResult>;
+    /** Installs the newest version if there is one (never while a sandbox runs). null: another update is running. */
+    run(): Promise<UpdateResult | null>;
+    /** Goes back to the version the last update replaced. Returns it. */
+    rollback(): string;
+    /**
+     * Automatic updates on or off. For an all-users install this also creates or removes the scheduled task (admin
+     * needed); the setting is changed only when that worked.
+     */
+    setAuto(on: boolean): void;
+    /**
+     * Should this CLI start update by itself? Only current-user installs (an all-users install has its scheduled task),
+     * with automatic updates on, the last look at the source over a day ago, and no sandbox running.
+     */
+    autoUpdateDue(): boolean;
+    /** What this user has not been told yet about an update that ran without them, or null. */
+    notice(): UpdateNotice | null;
+    /** Remembers that this user has been told (best effort: a failure only means the notice shows again). */
+    markNoticeSeen(notice: UpdateNotice): void;
+    private seenFile;
+    private managedLayout;
+    /** An all-users install lives where only administrators write: say so before anything is downloaded. */
+    private assertCanWrite;
+}

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

@@ -0,0 +1,185 @@
+// Keeping the program itself up to date: the logic behind `sandbox update`, the automatic update at the start of a
+// command and the Maintenance row. Only an install made by the installer (versions side by side) can update itself;
+// an npm install is updated with npm. Returns data, never prints.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { z } from 'zod';
+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 { 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';
+/** How long a CLI start waits after the last look at GitHub before it looks again (current-user installs). */
+const AUTO_CHECK_HOURS = 24;
+const SeenSchema = z.object({ seen: z.string() });
+/** The Windows service account the scheduled task runs as: it may not use a folder feed. */
+export function runsAsSystem(env = process.env, username = os.userInfo().username) {
+    return username.toUpperCase() === 'SYSTEM' || (env.USERNAME ?? '').endsWith('$');
+}
+export class UpdateService {
+    layout;
+    options;
+    source;
+    sandboxRunning;
+    version;
+    now;
+    task;
+    constructor(layout, options = {}) {
+        this.layout = layout;
+        this.options = options;
+        this.source = options.source ?? new GithubReleases();
+        this.sandboxRunning = options.sandboxRunning ?? isSandboxRunning;
+        this.version = options.version ?? packageVersion();
+        this.now = options.now ?? (() => new Date());
+        // Only an all-users install has the scheduled task; a current-user install checks from the CLI start instead.
+        this.task = layout?.scope === 'machine' ? (options.task ?? new UpdateTask(layout)) : null;
+    }
+    /** The service for the install this package runs from; `feed` is a folder with feed.json (tests, offline). */
+    static forPackage(packageRoot, feed, options = {}) {
+        if (feed && runsAsSystem())
+            fail('A feed folder cannot be used by the SYSTEM account.', 'Run sandbox update --feed in your own terminal.');
+        return new UpdateService(InstallLayout.detect(packageRoot), {
+            ...options,
+            source: options.source ?? (feed ? new FolderFeed(feed) : undefined),
+        });
+    }
+    get managed() {
+        return this.layout !== null;
+    }
+    status() {
+        const layout = this.layout;
+        if (!layout)
+            return { managed: false, version: this.version, scope: null, autoUpdate: false, state: {} };
+        return {
+            managed: true,
+            version: layout.activeVersion() ?? this.version,
+            scope: layout.scope,
+            autoUpdate: new InstallRecordFile(layout.root).read()?.autoUpdate ?? false,
+            state: new UpdateStateFile(layout.root).read(),
+        };
+    }
+    /** Asks the source what is newest. Changes nothing (the time of the look is not recorded). */
+    async check() {
+        const layout = this.managedLayout();
+        const current = layout.activeVersion() ?? this.version;
+        const latest = await this.source.latest();
+        const state = new UpdateStateFile(layout.root).read();
+        const decision = decideUpdate({
+            current,
+            latest,
+            state,
+            now: this.now(),
+            sandboxRunning: false,
+            minHoursBetweenChecks: 0,
+            force: true,
+        });
+        return {
+            current,
+            latest,
+            available: decision.kind === 'install',
+            blocked: !!latest && compareVersions(latest.version, current) > 0 && decision.kind === 'skip',
+        };
+    }
+    /** Installs the newest version if there is one (never while a sandbox runs). null: another update is running. */
+    async run() {
+        const layout = this.managedLayout();
+        this.assertCanWrite(layout);
+        const release = new UpdateLock(layout.root, this.now).acquire();
+        if (!release)
+            return null;
+        try {
+            const updater = new Updater(layout, this.source, { now: this.now });
+            return await updater.run({ sandboxRunning: this.sandboxRunning(), force: true });
+        }
+        finally {
+            release();
+        }
+    }
+    /** Goes back to the version the last update replaced. Returns it. */
+    rollback() {
+        const layout = this.managedLayout();
+        this.assertCanWrite(layout);
+        const release = new UpdateLock(layout.root, this.now).acquire();
+        if (!release)
+            fail('An update is running right now.', 'Try again in a minute.');
+        try {
+            return new Updater(layout, this.source, { now: this.now }).rollback();
+        }
+        finally {
+            release();
+        }
+    }
+    /**
+     * Automatic updates on or off. For an all-users install this also creates or removes the scheduled task (admin
+     * needed); the setting is changed only when that worked.
+     */
+    setAuto(on) {
+        const layout = this.managedLayout();
+        this.assertCanWrite(layout);
+        if (this.task) {
+            if (on)
+                this.task.register();
+            else
+                this.task.remove();
+        }
+        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.');
+    }
+    /**
+     * Should this CLI start update by itself? Only current-user installs (an all-users install has its scheduled task),
+     * with automatic updates on, the last look at the source over a day ago, and no sandbox running.
+     */
+    autoUpdateDue() {
+        const layout = this.layout;
+        if (!layout || layout.scope !== 'user')
+            return false;
+        const status = this.status();
+        return status.autoUpdate && !isTooSoon(status.state, this.now(), AUTO_CHECK_HOURS) && !this.sandboxRunning();
+    }
+    /** What this user has not been told yet about an update that ran without them, or null. */
+    notice() {
+        const layout = this.layout;
+        if (!layout)
+            return null;
+        const seen = this.seenFile()?.read()?.seen;
+        return updateNotice(new UpdateStateFile(layout.root).read(), layout.activeVersion() ?? this.version, seen);
+    }
+    /** Remembers that this user has been told (best effort: a failure only means the notice shows again). */
+    markNoticeSeen(notice) {
+        try {
+            this.seenFile()?.write({ seen: notice.key });
+        }
+        catch {
+            // Nothing to do: the notice is shown once more.
+        }
+    }
+    seenFile() {
+        return this.options.userDir
+            ? new JsonFile(SeenSchema, path.join(this.options.userDir, 'update-notice.json'))
+            : null;
+    }
+    managedLayout() {
+        return (this.layout ??
+            fail('This copy was installed with npm, so it cannot update itself.', 'Update it with: ' + NPM_UPDATE_COMMAND));
+    }
+    /** An all-users install lives where only administrators write: say so before anything is downloaded. */
+    assertCanWrite(layout) {
+        const probe = path.join(layout.root, '.write-test-' + process.pid);
+        try {
+            fs.writeFileSync(probe, '');
+            fs.rmSync(probe, { force: true });
+        }
+        catch (e) {
+            fail(layout.scope === 'machine'
+                ? 'This install is for everyone on this PC, so changing it needs admin rights.'
+                : 'Cannot write to ' + layout.root + ': ' + errMsg(e), layout.scope === 'machine'
+                ? 'Run this in an admin PowerShell (right-click Start > Terminal (Admin)).'
+                : undefined);
+        }
+    }
+}

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

@@ -1,6 +1,8 @@
 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 OverlayOptions } from './dialogs/overlay.js';
+import { type TabsState } from './frame.js';
 import { type ListOptions, type ListResult } from './list/list-types.js';
 import { Terminal } from './terminal.js';
 import type { Screen } from './screen.js';
@@ -8,9 +10,20 @@ 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 tabs shown across the top of every screen (none: no tab row). */
+    tabs: () => TabsState | 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>;
     confirm(o: ConfirmOptions): Promise<boolean>;

package/dist/cli/tui/app.js

@@ -3,6 +3,7 @@
 import { ConfirmScreen } from './dialogs/confirm-screen.js';
 import { MessageScreen } from './dialogs/message-screen.js';
 import { TextScreen } from './dialogs/text-screen.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 +12,30 @@ export class App {
     terminal;
     /** The status line for screens that do not set their own (refreshed on every draw). */
     status = () => '';
+    /** The tabs shown across the top of every screen (none: no tab row). */
+    tabs = () => 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 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));
         };
+        this.redrawNow = draw;
         this.terminal.onResized(draw);
         try {
             for (;;) {
@@ -32,9 +46,29 @@ 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));
     }

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>;
+}