windows-development-sandbox 1.1.0 → 1.4.0

package/dist/cli/menu/apps.js

@@ -0,0 +1,122 @@
+// The apps catalogue in the menu: every app by category, searchable, ticked = installed in every sandbox. VS Code and
+// Windows Terminal are listed too (they have settings of their own, which ticking changes). Your own programs
+// (apps.custom) are edited as a list of small forms. Saved to your config file (or, for catalogue apps only, the
+// project's .sandbox-config.json).
+import fs from 'node:fs';
+import path from 'node:path';
+import _ from 'lodash';
+import { APP_CATEGORIES, APPS } from '../../shared/apps.js';
+import { Text, Theme } from '../tui/index.js';
+import { ValueEditor } from './settings/editors.js';
+const CUSTOM = '@custom';
+export class AppsCatalogue {
+    app;
+    file;
+    dataPath;
+    constructor(app, file, dataPath) {
+        this.app = app;
+        this.file = file;
+        this.dataPath = dataPath;
+    }
+    /** Downloaded already (into this data folder), so the next sandbox starts it without a download. */
+    installed(entry) {
+        if (entry.id === 'vscode')
+            return fs.existsSync(path.join(this.dataPath, 'tools', 'vscode', 'Code.exe'));
+        if (entry.id === 'windows-terminal')
+            return fs.existsSync(path.join(this.dataPath, 'tools', 'terminal', 'WindowsTerminal.exe'));
+        return fs.existsSync(path.join(this.dataPath, 'tools', 'apps', entry.id, '.agent-sandbox-app'));
+    }
+    /** Is this entry on now (its setting, or listed in apps.install)? */
+    chosen(entry, install) {
+        return entry.setting ? _.get(this.file.userConfig(), entry.setting) === true : install.includes(entry.id);
+    }
+    item(entry, install) {
+        const notes = [
+            Theme.muted('Download  ') + '~' + entry.size + ' once, kept in C:\\AgentData\\tools\\' + (entry.setting ? '' : 'apps\\') + entry.id,
+            Theme.muted('Starts    ') + (entry.cli ? 'from a terminal (on PATH)' : 'from the desktop or Start > Sandbox apps'),
+            ...(entry.needs?.includes('mesa') ? [Theme.muted('Graphics  ') + 'OpenGL on the CPU (Mesa) is added for it'] : []),
+            ...(entry.fullGitOnly ? [Theme.warn('Needs provisioning.git.access "full" (it pushes with its own git).')] : []),
+            ...(entry.setting ? [Theme.muted('Setting   ') + entry.setting] : []),
+        ];
+        return {
+            value: entry.id, label: entry.name, category: entry.category, description: entry.about, details: notes, keywords: entry.id,
+            hint: (this.installed(entry) ? Theme.ok('installed ') : '') + Theme.muted(entry.size), checked: this.chosen(entry, install),
+            ...(this.file.isProject && entry.setting ? { disabled: 'A project cannot change this; it is in your own settings.' } : {}),
+        };
+    }
+    /** Shows the catalogue until you save (Enter) or leave it (Esc); returns the notice to show afterwards. */
+    async run() {
+        for (;;) {
+            const install = (this.file.isProject ? this.file.valueInFile(['apps', 'install']) : this.file.userConfig().apps.install) ?? [];
+            const custom = this.file.isProject ? {} : this.file.userConfig().apps.custom;
+            const entries = APPS.filter((a) => !(this.file.isProject && a.setting));
+            const picked = await this.app.list({
+                path: [this.file.isProject ? 'Project settings' : 'Apps'],
+                intro: 'Tick the apps every sandbox should have (space), then Enter to save. Each is downloaded once and kept; c = your own programs.',
+                multi: true,
+                categories: [...APP_CATEGORIES, ...(this.file.isProject ? [] : [{ id: 'custom', label: 'Your own programs', description: 'Programs you added yourself (c to add or change them).' }])],
+                items: [
+                    ...entries.map((a) => this.item(a, install)),
+                    ...Object.entries(custom).map(([id, a]) => ({ value: CUSTOM + id, label: a.name, category: 'custom', description: a.github ? 'From the latest ' + a.github + ' release.' : 'From ' + a.url, hint: Theme.muted(a.cli ? 'command line' : 'desktop'), checked: true, disabled: 'Your own programs are always installed; c to change or remove them.' })),
+                ],
+                actions: this.file.isProject ? [] : [{ key: 'c', label: 'your own programs' }],
+            });
+            if (picked.kind === 'back')
+                return undefined;
+            if (picked.kind === 'action') {
+                const notice = await this.editCustom();
+                if (notice)
+                    return notice;
+                continue;
+            }
+            if (picked.kind !== 'multi')
+                continue;
+            return this.save(picked.values.filter((v) => !v.startsWith(CUSTOM)));
+        }
+    }
+    save(ids) {
+        const problems = [];
+        let changed = 0;
+        for (const entry of APPS.filter((a) => a.setting && !this.file.isProject)) {
+            const on = ids.includes(entry.id);
+            if (on === this.chosen(entry, []))
+                continue;
+            const result = this.file.set(entry.setting.split('.'), on);
+            if (typeof result === 'object')
+                problems.push(...result.problems);
+            else if (result === 'saved')
+                changed++;
+        }
+        const install = APPS.filter((a) => !a.setting && ids.includes(a.id)).map((a) => a.id);
+        const result = this.file.set(['apps', 'install'], install.length || this.file.isProject ? install : undefined);
+        if (typeof result === 'object')
+            problems.push(...result.problems);
+        else if (result === 'saved')
+            changed++;
+        if (problems.length)
+            return Theme.error(Theme.glyph.cross + ' Not saved: ' + problems.join('; '));
+        if (!changed)
+            return Theme.muted('Apps unchanged.');
+        return Theme.ok(Theme.glyph.ok + ' Saved: ' + (install.length ? install.length + ' app' + (install.length === 1 ? '' : 's') : 'no apps') + '.') + Theme.muted(this.file.isProject ? ' The next launch asks you to approve the project file again.' : ' The next sandbox installs what it does not have yet.');
+    }
+    /** Your own programs: the apps.custom map, each entry a form (GitHub release or link, program, command line or not). */
+    async editCustom() {
+        const node = this.file.schema.child('apps')?.child('custom');
+        if (!node)
+            return undefined;
+        const edited = await new ValueEditor(this.app).edit(['Apps', 'Your own programs'], ['apps', 'custom'], node, this.file.userConfig().apps.custom);
+        if (!edited)
+            return undefined;
+        const result = this.file.set(['apps', 'custom'], edited.value);
+        if (typeof result === 'object')
+            return Theme.error(Theme.glyph.cross + ' Not saved: ' + result.problems.join('; '));
+        return result === 'saved' ? Theme.ok(Theme.glyph.ok + ' Saved your programs (' + Object.keys(edited.value).length + ').') : undefined;
+    }
+}
+/** For the home screen: "12 apps chosen". */
+export const appsSummary = (file) => {
+    const config = file.userConfig();
+    const n = config.apps.install.length + Object.keys(config.apps.custom).length;
+    return n ? n + ' chosen' : 'none chosen';
+};
+export const appLabel = (id) => APPS.find((a) => a.id === id)?.name ?? Text.humanize(id);

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

@@ -0,0 +1,28 @@
+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;
+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[]);
+    /** Values a choices list names, filled in from config and the running sandbox. */
+    private choices;
+    private first;
+    private fields;
+    private id;
+    /** The command line the form stands for now. */
+    argv(): string[];
+    /** The name of a required argument that has no value yet. */
+    private missing;
+    private item;
+    /** Shows the form until you run the command (its argv) or go back (null). */
+    run(): Promise<string[] | null>;
+    private edit;
+    /** `data clean` targets, ticked from a list with their sizes (never "all": that is typed on purpose). */
+    private dataTargets;
+}

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

@@ -0,0 +1,219 @@
+// 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 { 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;
+};
+const RUN = '@run';
+export class CommandForm {
+    app;
+    ctx;
+    spec;
+    /** Answers by field id (arg:<name>, opt:<flag>, json, extra). */
+    values = new Map();
+    constructor(app, ctx, spec, preset = []) {
+        this.app = app;
+        this.ctx = ctx;
+        this.spec = spec;
+        for (let i = 0; i < preset.length; i++) {
+            const option = spec.options.find((o) => o.flag === preset[i]);
+            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]]);
+        }
+    }
+    /** Values a choices list names, filled in from config and the running sandbox. */
+    choices(choices) {
+        if (Array.isArray(choices))
+            return choices;
+        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);
+        if (choices === 'sessions')
+            return isSandboxRunning() ? runningSessions(this.ctx.dataPath).map((s) => plainText(s.id)) : [];
+        return [];
+    }
+    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.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; }
+    /** The command line the form stands for now. */
+    argv() {
+        const fields = this.fields();
+        const list = (f) => this.values.get(this.id(f)) ?? [];
+        const argv = [this.spec.name, ...fields.filter((f) => f.kind === 'arg').flatMap(list)];
+        for (const f of fields) {
+            if (f.kind !== 'option')
+                continue;
+            const v = this.values.get(this.id(f));
+            if (v === true)
+                argv.push(f.spec.flag);
+            else if (Array.isArray(v))
+                for (const x of v)
+                    argv.push(f.spec.flag, x);
+        }
+        if (this.values.get('json') === true)
+            argv.push('--json');
+        const extra = list({ kind: 'extra' });
+        if (extra.length)
+            argv.push(...(this.spec.passthrough === 'agent' ? ['--', ...extra] : extra));
+        return argv;
+    }
+    /** 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));
+        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');
+        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 };
+        if (f.kind === 'json')
+            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 };
+    }
+    /** Shows the form until you run the command (its argv) or go back (null). */
+    async run() {
+        let focus;
+        let notice;
+        const path = [Text.humanize(this.spec.name)];
+        for (;;) {
+            const fields = this.fields();
+            const line = commandLine(this.argv());
+            const picked = await this.app.list({
+                path,
+                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' },
+                    ...fields.map((f) => this.item(f)),
+                ],
+                startAt: focus,
+                actions: [{ key: 'r', label: 'clear' }],
+                notice,
+            });
+            notice = undefined;
+            if (picked.kind === 'back')
+                return null;
+            if (picked.kind === 'pick' && picked.value === RUN) {
+                const missing = this.missing();
+                if (missing) {
+                    notice = Theme.warn(missing + ' is required.');
+                    continue;
+                }
+                return this.argv();
+            }
+            if (picked.kind !== 'pick' && picked.kind !== 'action')
+                continue;
+            const field = fields.find((f) => this.id(f) === picked.value);
+            if (!field)
+                continue;
+            focus = picked.value;
+            if (picked.kind === 'action') {
+                this.values.delete(this.id(field));
+                continue;
+            }
+            await this.edit(field, path);
+        }
+    }
+    async edit(f, path) {
+        const id = this.id(f);
+        const current = this.values.get(id);
+        if (f.kind === 'json' || (f.kind === 'option' && f.spec.type === 'boolean')) {
+            this.values.set(id, current !== true);
+            return;
+        }
+        const label = f.kind === 'extra' ? 'Arguments' : f.kind === 'arg' ? Text.humanize(f.spec.name) : f.spec.flag;
+        const about = f.kind === 'extra' ? [] : [f.spec.description];
+        if (f.kind === 'arg' && this.spec.name === 'data' && f.spec.name === 'targets') {
+            const picked = await this.dataTargets(path);
+            if (picked)
+                this.values.set(id, picked);
+            return;
+        }
+        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) })) });
+            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);
+            if (picked !== undefined) {
+                if (picked === '')
+                    this.values.delete(id);
+                else
+                    this.values.set(id, [picked]);
+            }
+            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).');
+        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),
+        });
+        if (typed === undefined)
+            return;
+        const value = many || f.kind === 'extra' ? splitArgs(typed) : typed.trim() ? [typed.trim()] : [];
+        if (value.length)
+            this.values.set(id, value);
+        else
+            this.values.delete(id);
+    }
+    /** `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 }] : []; });
+        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) })) });
+        return picked.kind === 'multi' && picked.values.length ? picked.values : undefined;
+    }
+}

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

@@ -0,0 +1,26 @@
+import type { Context } from '../commands/context.js';
+export { optionProblem } from './command-form.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>;

package/dist/cli/menu/index.js

@@ -0,0 +1,180 @@
+// 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';
+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));
+        }
+    }
+}
+/** 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/settings/categories.d.ts

@@ -0,0 +1,9 @@
+export interface SettingsCategory {
+    id: string;
+    label: string;
+    description: string;
+    keys: string[];
+}
+export declare const CATEGORIES: SettingsCategory[];
+export declare const nameOf: (key: string) => string;
+export declare const categoryOf: (topKey: string) => SettingsCategory | undefined;

package/dist/cli/menu/settings/categories.js

@@ -0,0 +1,28 @@
+// How the settings are grouped on screen: categories in the sidebar, readable names for sections and toolchains. Every
+// top-level setting of both files must belong to a category (a self-test checks it), so nothing is ever hidden.
+import { Text } from '../../tui/index.js';
+export const CATEGORIES = [
+    { id: 'general', label: 'General', description: 'Which agent starts, where the project appears in the sandbox, and extra folders from this PC.', keys: ['defaultHarness', 'harness', 'guestWorkspace', 'readOnly', 'mappings', 'scripts'] },
+    { id: 'machine', label: 'Sandbox machine', description: 'Memory, CPU, window, GPU, clipboard, audio and network of the sandbox itself.', keys: ['sandbox'] },
+    { id: 'languages', label: 'Languages & tools', description: 'Toolchains installed in the sandbox. "auto" follows your project\'s files and what this PC has.', keys: ['toolchains'] },
+    { id: 'apps', label: 'Apps', description: 'Desktop apps installed in the sandbox: editors, database clients, API clients, game engines ... (also: Apps catalogue on the home screen).', keys: ['apps'] },
+    { id: 'databases', label: 'Databases', description: 'Databases that run inside the sandbox. Their data persists between sandboxes.', keys: ['databases'] },
+    { id: 'agents', label: 'Agents & attaching', description: 'The agents you can start, attaching your terminal to them, and the (Beta) agent commands.', keys: ['harnesses', 'attach', 'agentCommands'] },
+    { id: 'claude', label: 'Claude profile', description: 'Which of your Claude settings, history and memory are copied in and synced back.', keys: ['claudeProfile'] },
+    { id: 'network', label: 'Network', description: 'What the sandbox can reach: your LAN, only some hosts, blocked hosts, DNS, a proxy, and ports forwarded from this PC to servers inside. (No network at all: Sandbox machine > Networking.)', keys: ['network'] },
+    { id: 'security', label: 'Security & privacy', description: 'Git-ignored files kept out, secrets kept out of the sandbox, download checks and what is kept on this PC.', keys: ['workspaceFilter', 'audit', 'secrets', 'downloads', 'storage'] },
+    { id: 'setup', label: 'Setup & hooks', description: 'How tools get into the sandbox (copied from this PC or downloaded), Git, the terminal, and hook scripts.', keys: ['provisioning', 'hooks'] },
+    { id: 'projects', label: 'Projects', description: 'Several projects in one sandbox: project roots mapped at every start, adding folders while it runs.', keys: ['projects'] },
+    { id: 'desktop', label: 'Desktop look', description: 'Copy your theme, accent colour, taskbar and wallpaper into the sandbox.', keys: ['personalization'] },
+];
+/** Readable names for sections and toolchains (anything missing gets a name made from its key). */
+const NAMES = {
+    sandbox: 'Sandbox machine', attach: 'Attaching your terminal', agentCommands: 'Agent commands (Beta)', provisioning: 'Provisioning', downloads: 'Downloads',
+    secrets: 'Secrets', claudeProfile: 'Claude profile', storage: 'Storage on this PC', network: 'Network', hooks: 'Hooks', personalization: 'Desktop look',
+    projects: 'Projects', harnesses: 'Agents', databases: 'Databases', toolchains: 'Toolchains', git: 'Git', terminal: 'Windows Terminal', conpty: 'Pseudo console',
+    node: 'Node.js', python: 'Python', java: 'Java (JDK)', dotnet: '.NET', go: 'Go', rust: 'Rust', cpp: 'C / C++ (MinGW)', msvc: 'Visual C++ (MSVC)', ruby: 'Ruby',
+    php: 'PHP', deno: 'Deno', bun: 'Bun', pwsh: 'PowerShell 7', vscode: 'VS Code', mesa: 'OpenGL (Mesa)', uv: 'uv', pnpm: 'pnpm', yarn: 'Yarn', cli: 'Command-line tools',
+    postgres: 'PostgreSQL', mysql: 'MySQL', mongodb: 'MongoDB', redis: 'Redis', dynamodb: 'DynamoDB Local', environment: 'Environment variables', workspaceFilter: 'Git-ignored files', audit: 'Audit log',
+};
+export const nameOf = (key) => NAMES[key] ?? Text.humanize(key);
+export const categoryOf = (topKey) => CATEGORIES.find((c) => c.keys.includes(topKey));