windows-development-sandbox 1.1.0 → 1.4.1

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));

package/dist/cli/menu/settings/config-file.d.ts

@@ -0,0 +1,40 @@
+import type { Config } from '../../../core/types.js';
+import { SchemaNode } from './schema-node.js';
+/** The user's own config, or a project's .sandbox-config.json (a smaller schema; nothing is merged with defaults). */
+export type SettingsTarget = 'user' | 'project';
+/** What the value is in this JSON text (undefined when it is not set there). */
+export declare const fileValue: (text: string, key: string[]) => unknown;
+/**
+ * Applies one change (undefined = remove the line, back to the default) to config text and returns the new text, or
+ * the problems that make the result invalid. Pure; ConfigFile writes it.
+ */
+export declare const editConfigText: (text: string, key: string[], value: unknown, target?: SettingsTarget) => {
+    text: string;
+} | {
+    problems: string[];
+};
+export declare class ConfigFile {
+    readonly target: SettingsTarget;
+    readonly file: string;
+    readonly schema: SchemaNode;
+    constructor(target: SettingsTarget, file: string);
+    static user(configPath: string | null): ConfigFile;
+    static project(dir: string): ConfigFile;
+    get isProject(): boolean;
+    get exists(): boolean;
+    text(): string;
+    /** The value written in this file (undefined = not set here). */
+    valueInFile(key: string[]): unknown;
+    /** Your own settings with the built-in defaults filled in (what a sandbox uses without a project file). */
+    userConfig(): Config;
+    /** What is in effect: for your file the merged config, for a project file only what the file sets. */
+    effective(key: string[], config?: Config): unknown;
+    defaultOf(key: string[]): unknown;
+    /**
+     * Saves one setting. In your own file a value equal to the default is removed instead (no line needed). Returns
+     * 'unchanged', 'saved', or the problems that stopped it.
+     */
+    set(key: string[], value: unknown): 'unchanged' | 'saved' | {
+        problems: string[];
+    };
+}

package/dist/cli/menu/settings/config-file.js

@@ -0,0 +1,71 @@
+// One config file being edited: your own settings, or a project's .sandbox-config.json. One setting is changed at a time
+// through jsonc-parser, so comments and formatting stay, and nothing is written unless the whole file is still valid.
+import fs from 'node:fs';
+import path from 'node:path';
+import { applyEdits, modify, parse } from 'jsonc-parser';
+import _ from 'lodash';
+import { DEFAULTS, loadConfig, mergeConfig, userConfigPath } from '../../../core/config.js';
+import { LOCAL_CONFIG_NAME } from '../../../core/local-config.js';
+import { Config as ConfigSchema, describeIssues, LocalOverrides } from '../../../core/schema.js';
+import { SchemaNode } from './schema-node.js';
+/** What the value is in this JSON text (undefined when it is not set there). */
+export const fileValue = (text, key) => _.get(parse(text) ?? {}, key);
+/**
+ * Applies one change (undefined = remove the line, back to the default) to config text and returns the new text, or
+ * the problems that make the result invalid. Pure; ConfigFile writes it.
+ */
+export const editConfigText = (text, key, value, target = 'user') => {
+    // Removing a setting the file does not have changes nothing (jsonc-parser throws on it).
+    const edits = value === undefined && fileValue(text || '{}', key) === undefined ? [] : modify(text || '{}', key, value, { formattingOptions: { insertSpaces: true, tabSize: 2, eol: '\n' } });
+    const next = applyEdits(text || '{}', edits);
+    const parsed = target === 'project' ? LocalOverrides.safeParse(parse(next) ?? {}) : ConfigSchema.safeParse(mergeConfig(DEFAULTS, parse(next) ?? {}));
+    return parsed.success ? { text: next.endsWith('\n') ? next : next + '\n' } : { problems: describeIssues(parsed.error) };
+};
+export class ConfigFile {
+    target;
+    file;
+    schema;
+    constructor(target, file) {
+        this.target = target;
+        this.file = file;
+        this.schema = new SchemaNode(target === 'project' ? LocalOverrides : ConfigSchema);
+    }
+    static user(configPath) { return new ConfigFile('user', configPath ?? userConfigPath()); }
+    static project(dir) { return new ConfigFile('project', path.join(dir, LOCAL_CONFIG_NAME)); }
+    get isProject() { return this.target === 'project'; }
+    get exists() { return fs.existsSync(this.file); }
+    text() { return this.exists ? fs.readFileSync(this.file, 'utf8') : ''; }
+    /** The value written in this file (undefined = not set here). */
+    valueInFile(key) { return fileValue(this.text(), key); }
+    /** Your own settings with the built-in defaults filled in (what a sandbox uses without a project file). */
+    userConfig() {
+        const file = this.isProject ? userConfigPath() : this.file;
+        try {
+            return loadConfig(fs.existsSync(file) ? file : undefined).config;
+        }
+        catch {
+            return loadConfig(undefined).config;
+        }
+    }
+    /** What is in effect: for your file the merged config, for a project file only what the file sets. */
+    effective(key, config = this.userConfig()) {
+        return this.isProject ? this.valueInFile(key) : _.get(config, key);
+    }
+    defaultOf(key) { return _.get(DEFAULTS, key); }
+    /**
+     * Saves one setting. In your own file a value equal to the default is removed instead (no line needed). Returns
+     * 'unchanged', 'saved', or the problems that stopped it.
+     */
+    set(key, value) {
+        const text = this.text();
+        const next = !this.isProject && value !== undefined && _.isEqual(value, this.defaultOf(key)) ? undefined : value;
+        if (_.isEqual(next, fileValue(text, key)) && (this.isProject || _.isEqual(value, _.get(this.userConfig(), key))))
+            return 'unchanged';
+        const result = editConfigText(text, key, next, this.target);
+        if ('problems' in result)
+            return result;
+        fs.mkdirSync(path.dirname(this.file), { recursive: true });
+        fs.writeFileSync(this.file, result.text, 'utf8');
+        return 'saved';
+    }
+}

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

@@ -0,0 +1,30 @@
+import { App } from '../../tui/index.js';
+import { SchemaNode } from './schema-node.js';
+/** The new value, or undefined when you backed out without changing anything. */
+export type Edited = {
+    value: unknown;
+} | undefined;
+/** A value in one short line, for the right-hand column. */
+export declare const formatValue: (value: unknown, max?: number) => string;
+/** Optional extra knowledge: values to suggest for some settings (the configured agents for defaultHarness). */
+export interface EditorHints {
+    suggestions?: (key: string[]) => string[] | undefined;
+}
+export declare class ValueEditor {
+    private readonly app;
+    private readonly hints;
+    constructor(app: App, hints?: EditorHints);
+    edit(path: string[], key: string[], node: SchemaNode, current: unknown): Promise<Edited>;
+    private pick;
+    private suggest;
+    private json;
+}
+/** One object as a form: each field with its value, Enter to change it, r to clear an optional one. */
+export declare class ObjectEditor {
+    private readonly app;
+    private readonly path;
+    private readonly node;
+    private readonly editor;
+    constructor(app: App, path: string[], node: SchemaNode, editor: ValueEditor);
+    run(start: Record<string, unknown>, isNew?: boolean): Promise<Edited>;
+}