windows-development-sandbox 1.4.1 → 1.4.3

package/dist/cli/menu/command-form.d.ts

@@ -1,15 +1,13 @@
 import type { Context } from '../commands/context.js';
-import { type CommandSpecT, type OptionSpecT } from '../manifest.js';
-import { App } from '../tui/index.js';
-/** What an option accepts, checked while typing (undefined = fine). */
-export declare const optionProblem: (o: OptionSpecT, v: string) => string | undefined;
+import { type CommandSpec } from '../manifest.js';
+import { type App } from '../tui/index.js';
 export declare class CommandForm {
     private readonly app;
     private readonly ctx;
     private readonly spec;
     /** Answers by field id (arg:<name>, opt:<flag>, json, extra). */
     private readonly values;
-    constructor(app: App, ctx: Context, spec: CommandSpecT, preset?: string[]);
+    constructor(app: App, ctx: Context, spec: CommandSpec, preset?: string[]);
     /** Values a choices list names, filled in from config and the running sandbox. */
     private choices;
     private first;

package/dist/cli/menu/command-form.js

@@ -1,38 +1,17 @@
 // One command as a form: its arguments and options listed with their current values, each changed in place, and the
 // exact command line it will run shown live (the same line you could type yourself). Built from manifest.ts, so a new
 // command or option appears here on its own.
-import fs from 'node:fs';
-import path from 'node:path';
 import { humanBytes } from '../../core/disk.js';
-import { fail, plainText } from '../../core/util.js';
-import { listAccounts } from '../../host/accounts.js';
-import { runningSessions } from '../../host/channel.js';
-import { isSandboxRunning } from '../../host/platform.js';
+import { fail, plainText } from '../../core/util/index.js';
+import { AccountStore } from '../../host/profile/index.js';
+import { SandboxChannel } from '../../host/channel/index.js';
+import { isSandboxRunning } from '../../host/sandbox/index.js';
 import { splitArgs } from '../args.js';
 import { cleanTargetOf, collectDataEntries } from '../commands/data/collect.js';
 import { commandLine } from '../history.js';
 import { askedWhen } from '../manifest.js';
 import { Text, Theme } from '../tui/index.js';
-import { validNodeSpec, validPythonSpec } from '../validate.js';
-/** What an option accepts, checked while typing (undefined = fine). */
-export const optionProblem = (o, v) => {
-    if (v === '')
-        return undefined;
-    if (o.type === 'number' && !(Number(v) > 0))
-        return 'Enter a number greater than 0.';
-    if (o.flag === '--node' && !validNodeSpec(v))
-        return 'Use a number like 22 or 22.11.0, or lts, latest.';
-    if (o.flag === '--python' && !validPythonSpec(v))
-        return 'Use 3, 3.12 or 3.12.4.';
-    if (o.value === 'dir' && !fs.existsSync(path.resolve(v)))
-        return 'That folder does not exist.';
-    if (o.value === 'file') {
-        const missing = splitArgs(v).find((f) => !fs.existsSync(path.resolve(f)));
-        if (missing)
-            return missing + ' does not exist.';
-    }
-    return undefined;
-};
+import { optionProblem } from './command-fields.js';
 const RUN = '@run';
 export class CommandForm {
     app;
@@ -49,7 +28,10 @@ export class CommandForm {
             if (option?.type === 'boolean')
                 this.values.set('opt:' + option.flag, true);
             else if (option)
-                this.values.set('opt:' + option.flag, [...(this.values.get('opt:' + option.flag) ?? []), preset[++i]]);
+                this.values.set('opt:' + option.flag, [
+                    ...(this.values.get('opt:' + option.flag) ?? []),
+                    preset[++i],
+                ]);
         }
     }
     /** Values a choices list names, filled in from config and the running sandbox. */
@@ -59,22 +41,34 @@ export class CommandForm {
         if (choices === 'harnesses')
             return Object.keys(this.ctx.loaded.config.harnesses);
         if (choices === 'accounts')
-            return listAccounts(this.ctx.storageRoot, this.ctx.dataPath).map((a) => a.name);
+            return new AccountStore(this.ctx.storageRoot).list(this.ctx.dataPath).map((a) => a.name);
         if (choices === 'sessions')
-            return isSandboxRunning() ? runningSessions(this.ctx.dataPath).map((s) => plainText(s.id)) : [];
+            return isSandboxRunning()
+                ? new SandboxChannel(this.ctx.dataPath).runningSessions().map((s) => plainText(s.id))
+                : [];
         return [];
     }
-    first() { return this.values.get('arg:' + this.spec.args[0]?.name)?.[0] ?? ''; }
+    first() {
+        return this.values.get('arg:' + this.spec.args[0]?.name)?.[0] ?? '';
+    }
     fields() {
         const first = this.first();
         return [
-            ...this.spec.args.map((spec, index) => ({ kind: 'arg', spec, index })).filter((f) => f.kind === 'arg' && (f.index === 0 || askedWhen(f.spec.when, first))),
-            ...this.spec.options.filter((o) => !o.noMenu && askedWhen(o.when, first) && !(typeof o.choices === 'string' && !this.choices(o.choices).length)).map((spec) => ({ kind: 'option', spec })),
+            ...this.spec.args
+                .map((spec, index) => ({ kind: 'arg', spec, index }))
+                .filter((f) => f.kind === 'arg' && (f.index === 0 || askedWhen(f.spec.when, first))),
+            ...this.spec.options
+                .filter((o) => !o.noMenu &&
+                askedWhen(o.when, first) &&
+                !(typeof o.choices === 'string' && !this.choices(o.choices).length))
+                .map((spec) => ({ kind: 'option', spec })),
             ...(this.spec.json && !(this.spec.name === 'data' && first === 'clean') ? [{ kind: 'json' }] : []),
             ...(this.spec.passthrough ? [{ kind: 'extra' }] : []),
         ];
     }
-    id(f) { return f.kind === 'arg' ? 'arg:' + f.spec.name : f.kind === 'option' ? 'opt:' + f.spec.flag : f.kind; }
+    id(f) {
+        return f.kind === 'arg' ? 'arg:' + f.spec.name : f.kind === 'option' ? 'opt:' + f.spec.flag : f.kind;
+    }
     /** The command line the form stands for now. */
     argv() {
         const fields = this.fields();
@@ -99,19 +93,62 @@ export class CommandForm {
     }
     /** The name of a required argument that has no value yet. */
     missing() {
-        const field = this.fields().find((f) => f.kind === 'arg' && f.spec.required && !(this.values.get(this.id(f))?.length));
+        const field = this.fields().find((f) => f.kind === 'arg' && f.spec.required && !this.values.get(this.id(f))?.length);
         return field?.kind === 'arg' ? Text.humanize(field.spec.name) : undefined;
     }
     item(f) {
         const v = this.values.get(this.id(f));
-        const shown = v === true ? Theme.ok('On') : v === false || v === undefined ? Theme.muted(f.kind === 'option' && f.spec.type === 'boolean' || f.kind === 'json' ? 'Off' : f.kind === 'option' && f.spec.default !== undefined ? 'default ' + f.spec.default : f.kind === 'arg' && f.spec.required ? 'required' : 'not set') : Array.isArray(v) && v.length ? v.join(' ') : Theme.muted('not set');
+        const shown = v === true
+            ? Theme.ok('On')
+            : v === false || v === undefined
+                ? Theme.muted((f.kind === 'option' && f.spec.type === 'boolean') || f.kind === 'json'
+                    ? 'Off'
+                    : f.kind === 'option' && f.spec.default !== undefined
+                        ? 'default ' + f.spec.default
+                        : f.kind === 'arg' && f.spec.required
+                            ? 'required'
+                            : 'not set')
+                : Array.isArray(v) && v.length
+                    ? v.join(' ')
+                    : Theme.muted('not set');
         if (f.kind === 'arg')
-            return { value: this.id(f), label: Text.humanize(f.spec.name), hint: shown, description: f.spec.description, section: 'What', keywords: f.spec.name };
+            return {
+                value: this.id(f),
+                label: Text.humanize(f.spec.name),
+                hint: shown,
+                description: f.spec.description,
+                section: 'What',
+                keywords: f.spec.name,
+            };
         if (f.kind === 'json')
-            return { value: 'json', label: 'Machine-readable output', hint: shown, description: 'Print JSON instead of a table (--json).', section: 'Output' };
+            return {
+                value: 'json',
+                label: 'Machine-readable output',
+                hint: shown,
+                description: 'Print JSON instead of a table (--json).',
+                section: 'Output',
+            };
         if (f.kind === 'extra')
-            return { value: 'extra', label: this.spec.passthrough === 'agent' ? 'Extra arguments for the agent' : 'Arguments for the command', hint: shown, description: this.spec.passthrough === 'agent' ? 'Passed on to the agent, e.g. --continue.' : 'The rest of the command line.', section: 'Output' };
-        return { value: this.id(f), label: f.spec.flag.replace(/^--/, '').replace(/-/g, ' ').replace(/^./, (c) => c.toUpperCase()), hint: shown, description: f.spec.description, section: f.spec.advanced ? 'Advanced' : 'Options', keywords: f.spec.flag };
+            return {
+                value: 'extra',
+                label: this.spec.passthrough === 'agent' ? 'Extra arguments for the agent' : 'Arguments for the command',
+                hint: shown,
+                description: this.spec.passthrough === 'agent'
+                    ? 'Passed on to the agent, e.g. --continue.'
+                    : 'The rest of the command line.',
+                section: 'Output',
+            };
+        return {
+            value: this.id(f),
+            label: f.spec.flag
+                .replace(/^--/, '')
+                .replace(/-/g, ' ')
+                .replace(/^./, (c) => c.toUpperCase()),
+            hint: shown,
+            description: f.spec.description,
+            section: f.spec.advanced ? 'Advanced' : 'Options',
+            keywords: f.spec.flag,
+        };
     }
     /** Shows the form until you run the command (its argv) or go back (null). */
     async run() {
@@ -126,7 +163,13 @@ export class CommandForm {
                 intro: this.spec.summary.replace(/^./, (c) => c.toUpperCase()) + '.',
                 status: Theme.muted('$ ') + Theme.accent(line),
                 items: [
-                    { value: RUN, label: Theme.ok('▶ Run'), hint: Theme.muted(Text.truncate(line, 60)), description: 'Runs: ' + line, section: 'Run' },
+                    {
+                        value: RUN,
+                        label: Theme.ok('▶ Run'),
+                        hint: Theme.muted(Text.truncate(line, 60)),
+                        description: 'Runs: ' + line,
+                        section: 'Run',
+                    },
                     ...fields.map((f) => this.item(f)),
                 ],
                 startAt: focus,
@@ -175,14 +218,22 @@ export class CommandForm {
         const list = f.kind === 'extra' ? [] : this.choices(f.spec.choices);
         const many = (f.kind === 'option' && f.spec.type === 'list') || (f.kind === 'arg' && f.spec.variadic);
         if (list.length && many) {
-            const picked = await this.app.list({ path: [...path, label], intro: about, multi: true, items: list.map((v) => ({ value: v, label: v, checked: Array.isArray(current) && current.includes(v) })) });
+            const picked = await this.app.list({
+                path: [...path, label],
+                intro: about,
+                multi: true,
+                items: list.map((v) => ({ value: v, label: v, checked: Array.isArray(current) && current.includes(v) })),
+            });
             if (picked.kind === 'multi')
                 this.values.set(id, picked.values);
             return;
         }
         if (list.length) {
             const optional = !(f.kind === 'arg' && f.spec.required);
-            const picked = await this.app.choose([...path, label], about.join(' '), [...list.map((v) => ({ value: v, label: v })), ...(optional ? [{ value: '', label: Theme.muted('(not set)') }] : [])], Array.isArray(current) ? current[0] : undefined);
+            const picked = await this.app.choose([...path, label], about.join(' '), [
+                ...list.map((v) => ({ value: v, label: v })),
+                ...(optional ? [{ value: '', label: Theme.muted('(not set)') }] : []),
+            ], Array.isArray(current) ? current[0] : undefined);
             if (picked !== undefined) {
                 if (picked === '')
                     this.values.delete(id);
@@ -192,11 +243,20 @@ export class CommandForm {
             return;
         }
         if (f.kind === 'arg' && typeof f.spec.choices === 'string')
-            fail('There is nothing to choose from: no ' + f.spec.choices + ' yet.', f.spec.choices === 'accounts' ? 'Sign in inside the sandbox, then run: sandbox account save <name>' : 'Start one first (sandbox claude).');
+            fail('There is nothing to choose from: no ' + f.spec.choices + ' yet.', f.spec.choices === 'accounts'
+                ? 'Sign in inside the sandbox, then run: sandbox account save <name>'
+                : 'Start one first (sandbox claude).');
         const typed = await this.app.text({
-            path: [...path, label], label, about, allowEmpty: true,
-            initial: Array.isArray(current) ? (many || f.kind === 'extra' ? current.map((x) => (/\s/.test(x) ? '"' + x + '"' : x)).join(' ') : current[0]) : '',
-            validate: (v) => (f.kind === 'option' ? optionProblem(f.spec, v) ?? true : true),
+            path: [...path, label],
+            label,
+            about,
+            allowEmpty: true,
+            initial: Array.isArray(current)
+                ? many || f.kind === 'extra'
+                    ? current.map((x) => (/\s/.test(x) ? '"' + x + '"' : x)).join(' ')
+                    : current[0]
+                : '',
+            validate: (v) => (f.kind === 'option' ? (optionProblem(f.spec, v) ?? true) : true),
         });
         if (typed === undefined)
             return;
@@ -208,12 +268,20 @@ export class CommandForm {
     }
     /** `data clean` targets, ticked from a list with their sizes (never "all": that is typed on purpose). */
     async dataTargets(path) {
-        const rows = collectDataEntries(this.ctx.dataPath, this.ctx.storageRoot).flatMap((e) => { const target = cleanTargetOf(e); return target ? [{ target, bytes: e.bytes }] : []; });
+        const rows = collectDataEntries(this.ctx.dataPath, this.ctx.storageRoot).flatMap((e) => {
+            const target = cleanTargetOf(e);
+            return target ? [{ target, bytes: e.bytes }] : [];
+        });
         if (!rows.length) {
             await this.app.message({ path, title: 'Nothing is saved yet', lines: ['There is nothing to delete.'] });
             return undefined;
         }
-        const picked = await this.app.list({ path: [...path, 'Delete what'], intro: 'Tick what to delete (space), then Enter. You confirm once more before anything is deleted.', multi: true, items: rows.map((r) => ({ value: r.target, label: r.target, hint: humanBytes(r.bytes) })) });
+        const picked = await this.app.list({
+            path: [...path, 'Delete what'],
+            intro: 'Tick what to delete (space), then Enter. You confirm once more before anything is deleted.',
+            multi: true,
+            items: rows.map((r) => ({ value: r.target, label: r.target, hint: humanBytes(r.bytes) })),
+        });
         return picked.kind === 'multi' && picked.values.length ? picked.values : undefined;
     }
 }

package/dist/cli/menu/home.d.ts

@@ -0,0 +1,22 @@
+import { type Category } from '../tui/index.js';
+/** What a home entry does. */
+export type Action = {
+    kind: 'run';
+    argv: string[];
+} | {
+    kind: 'form';
+    command: string;
+    preset?: string[];
+} | {
+    kind: 'several';
+} | {
+    kind: 'settings';
+    target: 'user' | 'project';
+} | {
+    kind: 'apps';
+    target: 'user' | 'project';
+};
+export declare const CATEGORIES: Category[];
+/** Readable names for commands on the home screen (the manifest's summaries are the descriptions). */
+export declare const TITLES: Record<string, string>;
+export declare const CATEGORY_OF_GROUP: Record<string, string>;

package/dist/cli/menu/home.js

@@ -0,0 +1,72 @@
+export const CATEGORIES = [
+    {
+        id: 'start',
+        label: 'Start',
+        description: 'Start an agent (or several) in a sandbox, or a sandbox with only your tools.',
+    },
+    {
+        id: 'sessions',
+        label: 'Sessions',
+        description: 'Agent sessions in the running sandbox: show one in this terminal, list them, restart them.',
+    },
+    {
+        id: 'sandbox',
+        label: 'Sandbox',
+        description: 'The running sandbox: its status, window, databases, projects, and stopping it.',
+    },
+    {
+        id: 'apps',
+        label: 'Apps & tools',
+        description: 'Desktop apps and command-line tools for every sandbox: editors, database clients, API clients, game engines, cloud CLIs ... and programs of your own.',
+    },
+    {
+        id: 'settings',
+        label: 'Settings',
+        description: 'Every setting, for all projects or just this one, edited in place.',
+    },
+    { id: 'accounts', label: 'Claude accounts', description: 'Saved Claude logins: save one, switch, set the default.' },
+    {
+        id: 'data',
+        label: 'Data & cleanup',
+        description: 'What is kept between sandboxes (tools, databases, logins, logs), and deleting it.',
+    },
+    { id: 'health', label: 'Health & repair', description: 'Check this PC, find and fix problems, read the logs.' },
+];
+/** Readable names for commands on the home screen (the manifest's summaries are the descriptions). */
+export const TITLES = {
+    start: 'Start a sandbox without an agent',
+    'host-claude': 'Claude on this PC (NOT sandboxed)',
+    attach: 'Show a session in this terminal',
+    sessions: 'List sessions',
+    restart: "Restart this project's agents",
+    status: 'Sandbox status',
+    db: 'Databases',
+    exec: 'Run a command inside',
+    stop: 'Stop the sandbox',
+    projects: 'Projects',
+    show: 'Show the sandbox window',
+    hide: 'Hide the sandbox window',
+    account: 'Claude accounts',
+    data: 'Saved data',
+    clean: 'Clean up old files',
+    sync: 'Sync history now',
+    logs: 'Logs',
+    setup: 'Set up this PC',
+    doctor: 'Doctor (check this PC)',
+    repair: 'Repair',
+    'self-test': 'Self-test',
+    generate: 'Preview a start (no sandbox)',
+    config: 'Config file',
+    audit: 'Audit log',
+    'agent-commands': 'Agent commands (Beta)',
+    launch: 'Start an agent',
+};
+export const CATEGORY_OF_GROUP = {
+    Agents: 'start',
+    Sandbox: 'sandbox',
+    Sessions: 'sessions',
+    Accounts: 'accounts',
+    Data: 'data',
+    Health: 'health',
+    Config: 'settings',
+};

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

@@ -1,26 +1,4 @@
 import type { Context } from '../commands/context.js';
-export { optionProblem } from './command-form.js';
+export { optionProblem } from './command-fields.js';
 export { candidateFolders, severalAgentsArgv } from './several.js';
-export declare class Menu {
-    private readonly ctx;
-    private readonly runArgv;
-    private readonly app;
-    private last;
-    /** The result of the last action (saved apps ...), shown on the home screen once. */
-    private notice;
-    constructor(ctx: Context, runArgv: (argv: string[]) => Promise<number>);
-    private status;
-    /** Is this agent already in the sandbox's persistent storage (so starting it needs no install)? */
-    private installed;
-    private homeItems;
-    /** Runs the menu until you leave it, or until a command that takes over the terminal (launch, attach) has run. */
-    start(): Promise<number>;
-    private fileFor;
-    /** Does what a home entry says. A number ends the menu with that exit code. */
-    private perform;
-    /** Runs an argv like typing it, on the normal screen; the menu comes back afterwards unless the command took over. */
-    private execute;
-    /** The settings screen may have switched agentCommands (Beta): apply it now, from the saved file. */
-    private applyAgentCommands;
-}
-export declare const menu: (ctx: Context, run: (argv: string[]) => Promise<number>) => Promise<number>;
+export declare function menu(ctx: Context, run: (argv: string[]) => Promise<number>): Promise<number>;

package/dist/cli/menu/index.js

@@ -1,180 +1,6 @@
-// The interactive menu (`sandbox` with no arguments): a full-screen app. The home screen groups everything into
-// categories (start, sessions, sandbox, apps, settings ...); commands open as a form that shows the exact command line,
-// which then runs like typing it. Settings and the project's .sandbox-config.json are edited in place.
-import fs from 'node:fs';
-import path from 'node:path';
-import { errMsg, plainText } from '../../core/util.js';
-import { loadConfig } from '../../core/config.js';
-import { runningSessions } from '../../host/channel.js';
-import { isSandboxRunning } from '../../host/platform.js';
-import { syncAgentCommands } from '../commands/agent-commands.js';
-import { commandLine, readHistory } from '../history.js';
-import { COMMANDS, commandSpec } from '../manifest.js';
-import { App, ExitRequested, Frame, Text, Theme } from '../tui/index.js';
-import { AppsCatalogue, appsSummary } from './apps.js';
-import { CommandForm } from './command-form.js';
-import { ConfigFile, SettingsEditor } from './settings/index.js';
-import { SeveralAgents } from './several.js';
-export { optionProblem } from './command-form.js';
+import { Menu } from './menu.js';
+export { optionProblem } from './command-fields.js';
 export { candidateFolders, severalAgentsArgv } from './several.js';
-const CATEGORIES = [
-    { id: 'start', label: 'Start', description: 'Start an agent (or several) in a sandbox, or a sandbox with only your tools.' },
-    { id: 'sessions', label: 'Sessions', description: 'Agent sessions in the running sandbox: show one in this terminal, list them, restart them.' },
-    { id: 'sandbox', label: 'Sandbox', description: 'The running sandbox: its status, window, databases, projects, and stopping it.' },
-    { id: 'apps', label: 'Apps & tools', description: 'Desktop apps and command-line tools for every sandbox: editors, database clients, API clients, game engines, cloud CLIs ... and programs of your own.' },
-    { id: 'settings', label: 'Settings', description: 'Every setting, for all projects or just this one, edited in place.' },
-    { id: 'accounts', label: 'Claude accounts', description: 'Saved Claude logins: save one, switch, set the default.' },
-    { id: 'data', label: 'Data & cleanup', description: 'What is kept between sandboxes (tools, databases, logins, logs), and deleting it.' },
-    { id: 'health', label: 'Health & repair', description: 'Check this PC, find and fix problems, read the logs.' },
-];
-/** Readable names for commands on the home screen (the manifest's summaries are the descriptions). */
-const TITLES = {
-    start: 'Start a sandbox without an agent', 'host-claude': 'Claude on this PC (NOT sandboxed)', attach: 'Show a session in this terminal', sessions: 'List sessions',
-    restart: 'Restart this project\'s agents', status: 'Sandbox status', db: 'Databases', exec: 'Run a command inside', stop: 'Stop the sandbox', projects: 'Projects',
-    show: 'Show the sandbox window', hide: 'Hide the sandbox window', account: 'Claude accounts', data: 'Saved data', clean: 'Clean up old files', sync: 'Sync history now',
-    logs: 'Logs', setup: 'Set up this PC', doctor: 'Doctor (check this PC)', repair: 'Repair', 'self-test': 'Self-test', generate: 'Preview a start (no sandbox)',
-    config: 'Config file', audit: 'Audit log', 'agent-commands': 'Agent commands (Beta)', launch: 'Start an agent',
-};
-const CATEGORY_OF_GROUP = { Agents: 'start', Sandbox: 'sandbox', Sessions: 'sessions', Accounts: 'accounts', Data: 'data', Health: 'health', Config: 'settings' };
-export class Menu {
-    ctx;
-    runArgv;
-    app = new App();
-    last;
-    /** The result of the last action (saved apps ...), shown on the home screen once. */
-    notice;
-    constructor(ctx, runArgv) {
-        this.ctx = ctx;
-        this.runArgv = runArgv;
-        this.app.status = () => this.status();
-        try {
-            Frame.version = JSON.parse(fs.readFileSync(path.join(ctx.packageRoot, 'package.json'), 'utf8')).version ?? '';
-        }
-        catch { /* no version shown */ }
-    }
-    status() {
-        const folder = Theme.muted(Text.middle(process.cwd(), 70));
-        if (!isSandboxRunning())
-            return Theme.muted(Theme.glyph.off + ' No sandbox running') + '   ' + folder;
-        const n = runningSessions(this.ctx.dataPath).length;
-        return Theme.ok(Theme.glyph.on + ' Sandbox running') + Theme.muted(' · ' + n + ' session' + (n === 1 ? '' : 's')) + '   ' + folder;
-    }
-    /** Is this agent already in the sandbox's persistent storage (so starting it needs no install)? */
-    installed(name) {
-        const h = this.ctx.loaded.config.harnesses[name];
-        const dir = path.join(this.ctx.dataPath, 'tools', 'agents', name);
-        return Boolean(h) && [h.hostExecutable, h.npmBin && h.npmBin + '.cmd', h.uvBin && h.uvBin + '.exe'].some((f) => f && fs.existsSync(path.join(dir, f)));
-    }
-    homeItems() {
-        const config = this.ctx.loaded.config;
-        const def = config.defaultHarness;
-        const last = readHistory()[0];
-        const items = [];
-        const add = (category, section, label, action, description, hint) => { items.push({ value: JSON.stringify(action), label, category, section, description, hint }); };
-        if (last)
-            add('start', 'Quick start', 'Repeat last', { kind: 'run', argv: last.argv }, 'Runs the last command again.', Theme.muted(Text.truncate(commandLine(last.argv), 50)));
-        add('start', 'Quick start', 'Start ' + def + ' in this folder', { kind: 'run', argv: ['launch', '--harness', def] }, 'Starts ' + def + ' in a sandbox for ' + process.cwd() + ' (or another session in the running sandbox).', this.installed(def) ? Theme.ok('ready') : Theme.muted('installs on first start'));
-        add('start', 'Quick start', 'Start ' + def + ' with options…', { kind: 'form', command: 'launch', preset: ['--harness', def] }, 'Choose options first: attach this terminal, Node or Python version, databases, scripts ...');
-        add('start', 'Quick start', 'Start several agents…', { kind: 'several' }, 'One or more projects, one or more agents each, all in one sandbox; attach to any of them.');
-        for (const name of Object.keys(config.harnesses).filter((n) => n !== def))
-            add('start', 'Other agents', 'Start ' + name, { kind: 'form', command: 'launch', preset: ['--harness', name] }, 'Opens the start form for ' + name + '.', this.installed(name) ? Theme.ok('ready') : Theme.muted('installs on first start'));
-        if (isSandboxRunning()) {
-            for (const s of runningSessions(this.ctx.dataPath).slice(-12)) {
-                add('sessions', 'Running now', plainText(s.harness) + ' · ' + plainText(path.win32.basename(s.cwd)), { kind: 'run', argv: ['attach', plainText(s.id)] }, 'Shows this session in this terminal (Ctrl+] detaches; the session keeps running).', Theme.muted(plainText(s.id)));
-            }
-        }
-        const userFile = ConfigFile.user(this.ctx.loaded.configPath);
-        add('apps', 'Apps', 'Browse the apps catalogue…', { kind: 'apps', target: 'user' }, 'Tick the apps every sandbox should have: by category, searchable, with sizes. Each downloads once and is kept.', Theme.muted(appsSummary(userFile)));
-        add('apps', 'Apps', 'Apps for this project only…', { kind: 'apps', target: 'project' }, 'Catalogue apps this project needs (saved in its .sandbox-config.json, added to yours).');
-        add('settings', 'Settings', 'Settings for all projects', { kind: 'settings', target: 'user' }, 'Your own settings, used by every project: languages, databases, the sandbox machine, agents, security ... (Tab switches to this project\'s.)', Theme.scopeGlobal(' YOURS '));
-        add('settings', 'Settings', 'Settings for this project', { kind: 'settings', target: 'project' }, 'This folder\'s .sandbox-config.json: only what a project may set, on top of yours. A changed file needs your approval at the next launch. (Tab switches to all projects.)', Theme.scopeProject(' PROJECT '));
-        for (const spec of COMMANDS.filter((s) => !s.hidden && s.name !== 'launch')) {
-            const category = CATEGORY_OF_GROUP[spec.group];
-            const section = category === 'start' ? 'More' : category === 'settings' ? 'Tools' : 'Commands';
-            add(category, section, TITLES[spec.name] ?? Text.humanize(spec.name), { kind: 'form', command: spec.name }, spec.summary.replace(/^./, (c) => c.toUpperCase()) + '.', Theme.muted('sandbox ' + spec.name));
-        }
-        return items;
-    }
-    /** Runs the menu until you leave it, or until a command that takes over the terminal (launch, attach) has run. */
-    async start() {
-        if (!process.stdin.isTTY) {
-            console.log('The menu needs an interactive terminal. Run sandbox --help for the commands.');
-            return 1;
-        }
-        try {
-            for (;;) {
-                const picked = await this.app.list({ path: [], items: this.homeItems(), categories: CATEGORIES, startAt: this.last, escapeLabel: 'quit', notice: this.notice });
-                this.notice = undefined;
-                if (picked.kind === 'back')
-                    return 0;
-                if (picked.kind !== 'pick')
-                    continue;
-                this.last = picked.value;
-                const code = await this.perform(JSON.parse(picked.value));
-                if (code !== undefined)
-                    return code;
-            }
-        }
-        catch (e) {
-            // Ctrl+C anywhere: leave quietly.
-            if (e instanceof ExitRequested || (e instanceof Error && e.name === 'ExitPromptError'))
-                return 130;
-            throw e;
-        }
-        finally {
-            this.app.close();
-        }
-    }
-    fileFor(target) { return target === 'user' ? ConfigFile.user(this.ctx.loaded.configPath) : ConfigFile.project(process.cwd()); }
-    /** Does what a home entry says. A number ends the menu with that exit code. */
-    async perform(action) {
-        if (action.kind === 'settings') {
-            await new SettingsEditor(this.app, { user: this.fileFor('user'), project: this.fileFor('project') }, action.target, this.ctx.dataPath).run();
-            this.applyAgentCommands();
-            return undefined;
-        }
-        if (action.kind === 'apps') {
-            this.notice = await new AppsCatalogue(this.app, this.fileFor(action.target), this.ctx.dataPath).run();
-            return undefined;
-        }
-        const argv = action.kind === 'run' ? action.argv : action.kind === 'several' ? await new SeveralAgents(this.app, this.ctx).run() : await new CommandForm(this.app, this.ctx, commandSpec(action.command), action.preset).run();
-        return argv ? this.execute(argv) : undefined;
-    }
-    /** Runs an argv like typing it, on the normal screen; the menu comes back afterwards unless the command took over. */
-    async execute(argv) {
-        const code = await this.app.suspend(async () => {
-            process.stdout.write('\x1b[2J\x1b[3J\x1b[H' + Theme.muted('$ ' + commandLine(argv)) + '\n\n');
-            return this.runArgv(argv);
-        });
-        if (commandSpec(argv[0])?.interactive)
-            return code;
-        await pressAnyKey((code === 0 ? Theme.ok('Done.') : Theme.warn('Exit code ' + code + '.')) + Theme.muted(' Press any key for the menu…'));
-        return undefined;
-    }
-    /** The settings screen may have switched agentCommands (Beta): apply it now, from the saved file. */
-    applyAgentCommands() {
-        try {
-            syncAgentCommands(this.ctx, loadConfig(this.ctx.loaded.configPath ?? undefined).config);
-        }
-        catch (e) {
-            console.warn('Agent commands (Beta): ' + errMsg(e));
-        }
-    }
+export function menu(ctx, run) {
+    return new Menu(ctx, run).start();
 }
-/** Waits for one key on the normal screen, so a command's output stays until you have read it. Ctrl+C leaves. */
-const pressAnyKey = (message) => new Promise((resolve, reject) => {
-    process.stdout.write('\n' + message);
-    const { stdin } = process;
-    stdin.setRawMode(true);
-    stdin.resume();
-    stdin.once('data', (key) => {
-        stdin.setRawMode(false);
-        stdin.pause();
-        process.stdout.write('\n');
-        if (key[0] === 3)
-            reject(new ExitRequested());
-        else
-            resolve();
-    });
-});
-export const menu = (ctx, run) => new Menu(ctx, run).start();

package/dist/cli/menu/menu.d.ts

@@ -0,0 +1,23 @@
+import type { Context } from '../commands/context.js';
+export declare class Menu {
+    private readonly ctx;
+    private readonly runArgv;
+    private readonly app;
+    private last;
+    /** The result of the last action (saved apps ...), shown on the home screen once. */
+    private notice;
+    constructor(ctx: Context, runArgv: (argv: string[]) => Promise<number>);
+    private status;
+    /** Is this agent already in the sandbox's persistent storage (so starting it needs no install)? */
+    private installed;
+    private homeItems;
+    /** Runs the menu until you leave it, or until a command that takes over the terminal (launch, attach) has run. */
+    start(): Promise<number>;
+    private fileFor;
+    /** Does what a home entry says. A number ends the menu with that exit code. */
+    private perform;
+    /** Runs an argv like typing it, on the normal screen; the menu comes back afterwards unless the command took over. */
+    private execute;
+    /** The settings screen may have switched agentCommands (Beta): apply it now, from the saved file. */
+    private applyAgentCommands;
+}