windows-development-sandbox 0.0.0-stage → 1.0.5

package/dist/cli/index.d.ts

@@ -0,0 +1,14 @@
+/** The package folder (this file is dist/cli/index.js). */
+export declare const packageRoot: string;
+export interface Preset {
+    harness?: string;
+    command?: string;
+}
+/**
+ * CLI entry. `preset` lets wrapper binaries fix the command/agent (sandbox claude = launch --harness claude). No arguments
+ * opens the menu; `sandbox <agent> [agent args]` starts that agent.
+ */
+export declare const main: (argv: string[], preset?: Preset) => Promise<number>;
+/** Prints a problem the way a user can act on it: what happened, how to fix it; stack traces only for real bugs. */
+export declare const report: (e: unknown) => number;
+export declare const run: (argv: string[], preset?: Preset) => void;

package/dist/cli/index.js

@@ -0,0 +1,96 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CommanderError } from 'commander';
+import { buildProgram, parseCli } from './args.js';
+import { commandSpec } from './manifest.js';
+import { menu, recordHistory } from './menu.js';
+import { loadConfig } from '../core/config.js';
+import * as commands from './commands/index.js';
+import { UserError, errMsg, fail } from '../core/util.js';
+/** The package folder (this file is dist/cli/index.js). */
+export const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const entry = path.join(packageRoot, 'dist', 'bin', 'agent-sandbox.js');
+const HANDLERS = {
+    launch: (ctx) => commands.launch(ctx),
+    generate: (ctx) => commands.launch(ctx, true),
+    attach: commands.attach,
+    sessions: commands.sessions,
+    status: commands.status,
+    exec: commands.exec,
+    db: commands.db,
+    restart: commands.restart,
+    stop: commands.stop,
+    show: commands.show,
+    hide: commands.hide,
+    account: commands.account,
+    sync: commands.sync,
+    logs: commands.logs,
+    clean: commands.clean,
+    config: commands.config,
+    doctor: commands.doctor,
+    setup: commands.setup,
+    data: commands.data,
+    'host-claude': commands.claudeHost,
+    _watch: commands.watcher,
+};
+const red = (s) => '\x1b[31m' + s + '\x1b[0m';
+const dim = (s) => '\x1b[2m' + s + '\x1b[0m';
+/** Runs an argv from the menu exactly as if it had been typed, reporting errors instead of throwing. */
+const runFromMenu = (argv) => main(argv).catch((e) => report(e));
+/**
+ * CLI entry. `preset` lets wrapper binaries fix the command/agent (sandbox claude = launch --harness claude). No arguments
+ * opens the menu; `sandbox <agent> [agent args]` starts that agent.
+ */
+export const main = async (argv, preset = {}) => {
+    const isAgent = (name) => {
+        if (!name || name.startsWith('-') || commandSpec(name))
+            return false;
+        const at = argv.indexOf('--config');
+        try {
+            return Boolean(loadConfig(at >= 0 ? argv[at + 1] : undefined).config.harnesses[name]);
+        }
+        catch {
+            return false;
+        }
+    };
+    if (!preset.command && !preset.harness) {
+        if (argv.length === 0)
+            return process.stdin.isTTY ? main(['menu']) : (buildProgram(() => undefined).outputHelp(), 0);
+        if (isAgent(argv[0]))
+            return main(argv.slice(1), { harness: argv[0] });
+    }
+    const options = parseCli(preset.command ? [preset.command, ...argv] : argv, Boolean(preset.harness));
+    if (preset.harness)
+        options.harness = preset.harness;
+    recordHistory(preset.harness ? ['launch', '--harness', preset.harness, ...argv] : preset.command ? [preset.command, ...argv] : argv);
+    if (options.command === 'menu')
+        return menu(commands.createContext(packageRoot, entry, options), runFromMenu);
+    // Loaded only when asked for: normal commands never load test code.
+    if (options.command === 'self-test')
+        return (await import('../selftest/index.js')).selfTest(packageRoot);
+    // repair must run even when the config file is broken (createContext would refuse it).
+    if (options.command === 'repair')
+        return commands.repairCommand(packageRoot, entry, options);
+    const handler = HANDLERS[options.command];
+    if (!handler)
+        return fail('Unknown command "' + options.command + '".', 'Run sandbox --help for the list of commands, or sandbox for the menu.');
+    return (await handler(commands.createContext(packageRoot, entry, options))) ?? 0;
+};
+/** Prints a problem the way a user can act on it: what happened, how to fix it; stack traces only for real bugs. */
+export const report = (e) => {
+    if (e instanceof CommanderError)
+        return ['commander.helpDisplayed', 'commander.help', 'commander.version'].includes(e.code) ? 0 : e.exitCode || 1;
+    if (e instanceof UserError) {
+        console.error(red('Error: ') + e.message);
+        if (e.fix)
+            console.error('  Fix:  ' + e.fix);
+        return 1;
+    }
+    console.error(red('Unexpected error: ') + errMsg(e));
+    console.error(dim('This is a bug in windows-development-sandbox. Details: ' + (e instanceof Error && e.stack ? e.stack.split('\n').slice(1, 4).join(' | ').trim() : 'none')));
+    console.error('  Please report it with the output of: sandbox doctor');
+    return 1;
+};
+export const run = (argv, preset) => {
+    main(argv, preset).then((code) => { process.exitCode = code; }, (e) => { process.exitCode = report(e); });
+};

package/dist/cli/manifest.d.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+export declare const OptionSpec: z.ZodObject<{
+    flag: z.ZodString;
+    short: z.ZodOptional<z.ZodString>;
+    type: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        list: "list";
+    }>;
+    value: z.ZodOptional<z.ZodString>;
+    description: z.ZodString;
+    default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    choices: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodEnum<{
+        harnesses: "harnesses";
+        sessions: "sessions";
+        accounts: "accounts";
+    }>]>>;
+    advanced: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const ArgSpec: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    required: z.ZodBoolean;
+    variadic: z.ZodOptional<z.ZodBoolean>;
+    choices: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodEnum<{
+        harnesses: "harnesses";
+        sessions: "sessions";
+        accounts: "accounts";
+    }>]>>;
+}, z.core.$strict>;
+export declare const Group: z.ZodEnum<{
+    Agents: "Agents";
+    Sandbox: "Sandbox";
+    Sessions: "Sessions";
+    Accounts: "Accounts";
+    Data: "Data";
+    Health: "Health";
+    Config: "Config";
+}>;
+export declare const CommandSpec: z.ZodObject<{
+    name: z.ZodString;
+    summary: z.ZodString;
+    group: z.ZodEnum<{
+        Agents: "Agents";
+        Sandbox: "Sandbox";
+        Sessions: "Sessions";
+        Accounts: "Accounts";
+        Data: "Data";
+        Health: "Health";
+        Config: "Config";
+    }>;
+    args: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        required: z.ZodBoolean;
+        variadic: z.ZodOptional<z.ZodBoolean>;
+        choices: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodEnum<{
+            harnesses: "harnesses";
+            sessions: "sessions";
+            accounts: "accounts";
+        }>]>>;
+    }, z.core.$strict>>;
+    options: z.ZodArray<z.ZodObject<{
+        flag: z.ZodString;
+        short: z.ZodOptional<z.ZodString>;
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            list: "list";
+        }>;
+        value: z.ZodOptional<z.ZodString>;
+        description: z.ZodString;
+        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        choices: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodEnum<{
+            harnesses: "harnesses";
+            sessions: "sessions";
+            accounts: "accounts";
+        }>]>>;
+        advanced: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    passthrough: z.ZodOptional<z.ZodEnum<{
+        command: "command";
+        agent: "agent";
+    }>>;
+    json: z.ZodOptional<z.ZodBoolean>;
+    interactive: z.ZodOptional<z.ZodBoolean>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type OptionSpecT = z.output<typeof OptionSpec>;
+export type ArgSpecT = z.output<typeof ArgSpec>;
+export type CommandSpecT = z.output<typeof CommandSpec>;
+export declare const COMMANDS: CommandSpecT[];
+export declare const commandSpec: (name: string) => CommandSpecT | undefined;

package/dist/cli/manifest.js

@@ -0,0 +1,87 @@
+// Every command, defined once: name, group, arguments and options with their types. args.ts builds the commander
+// parser from it and menu.ts builds the interactive menu from it, so a command added here works both ways.
+import { z } from 'zod';
+const Choices = z.union([z.array(z.string()), z.enum(['harnesses', 'accounts', 'sessions'])])
+    .describe('Fixed values, or a list the menu fills in at run time.');
+export const OptionSpec = z.strictObject({
+    flag: z.string().regex(/^--[a-z][a-z0-9-]*$/).describe('Long flag, e.g. --terminal.'),
+    short: z.string().regex(/^-[a-zA-Z]$/).optional(),
+    type: z.enum(['boolean', 'string', 'number', 'list']).describe('list = repeatable string option.'),
+    value: z.string().optional().describe('Placeholder shown in help, e.g. name for --account <name>.'),
+    description: z.string(),
+    default: z.union([z.string(), z.number()]).optional(),
+    choices: Choices.optional(),
+    /** Advanced options are only asked in the menu after "Show advanced options". */
+    advanced: z.boolean().optional(),
+});
+export const ArgSpec = z.strictObject({
+    name: z.string(),
+    description: z.string(),
+    required: z.boolean(),
+    variadic: z.boolean().optional(),
+    choices: Choices.optional(),
+});
+export const Group = z.enum(['Agents', 'Sandbox', 'Sessions', 'Accounts', 'Data', 'Health', 'Config']);
+export const CommandSpec = z.strictObject({
+    name: z.string(),
+    summary: z.string(),
+    group: Group,
+    args: z.array(ArgSpec),
+    options: z.array(OptionSpec),
+    /** Unknown options and extra arguments are passed on to the agent (launch) or the program (exec). */
+    passthrough: z.enum(['agent', 'command']).optional(),
+    json: z.boolean().optional(),
+    /** Takes over the terminal or ends the session: the menu does not come back afterwards. */
+    interactive: z.boolean().optional(),
+    hidden: z.boolean().optional(),
+});
+const bool = (flag, description, extra = {}) => ({ flag, type: 'boolean', description, ...extra });
+const text = (flag, value, description, extra = {}) => ({ flag, type: 'string', value, description, ...extra });
+const SANDBOX_OPTIONS = [
+    bool('--terminal', 'run in THIS terminal (reattaches to this folder\'s session if nobody is watching it)', { short: '-t' }),
+    bool('--headless', 'hide the sandbox window (sbx-show brings it back)'),
+    bool('--new', 'always start a new session, even if this folder has one nobody is attached to'),
+    text('--workspace', 'dir', 'use this folder instead of the current one'),
+    text('--node', 'version', 'Node version for nvm (default: .sandbox-config.json > .nvmrc > this PC)', { advanced: true }),
+    text('--python', 'version', 'Python 3 version (default: .sandbox-config.json > .python-version > config)', { advanced: true }),
+    { flag: '--database', type: 'list', value: 'name', description: 'also start this database (postgres, mysql, mongodb, redis, dynamodb; repeatable)', advanced: true },
+    { flag: '--script', type: 'list', value: 'file', description: 'run this .ps1/.mjs/.cmd inside the sandbox first (repeatable)', advanced: true },
+    bool('--window', 'show the sandbox window even if config says headless', { advanced: true }),
+    bool('--trust-config', 'approve the folder\'s .sandbox-config.json without asking', { advanced: true }),
+    bool('--no-local-config', 'ignore the folder\'s .sandbox-config.json', { advanced: true }),
+];
+const AGENT_OPTIONS = [
+    text('--harness', 'name', 'agent to run', { choices: 'harnesses' }),
+    text('--account', 'name', 'Claude account for this sandbox', { choices: 'accounts' }),
+    ...SANDBOX_OPTIONS,
+    bool('--no-agent', 'provision the sandbox without starting an agent', { advanced: true }),
+];
+const json = true;
+export const COMMANDS = z.array(CommandSpec).parse([
+    { name: 'launch', summary: 'start the sandbox and an agent (or another session in the running sandbox)', group: 'Agents', args: [], options: AGENT_OPTIONS, passthrough: 'agent', interactive: true },
+    { name: 'start', summary: 'start the sandbox WITHOUT an agent: just the machine, toolchains and databases', group: 'Sandbox', args: [], options: SANDBOX_OPTIONS.filter((o) => o.flag !== '--new'), interactive: true },
+    { name: 'generate', summary: 'dry run: write the .wsb and launch folder and show what would happen, start nothing', group: 'Health', args: [], options: AGENT_OPTIONS, passthrough: 'agent' },
+    { name: 'attach', summary: 'show a running session in this terminal (Ctrl+] detaches)', group: 'Sessions', args: [{ name: 'id', description: 'session (default: the newest)', required: false, choices: 'sessions' }], options: [], interactive: true },
+    { name: 'sessions', summary: 'list agent sessions and who is attached', group: 'Sessions', args: [], options: [], json },
+    { name: 'status', summary: 'sandbox overview', group: 'Sandbox', args: [], options: [], json },
+    { name: 'db', summary: 'list, start or stop databases in the running sandbox', group: 'Sandbox', args: [{ name: 'action', description: 'list, start or stop', required: false, choices: ['list', 'start', 'stop'] }, { name: 'name', description: 'postgres, mysql, mongodb, redis or dynamodb', required: false, choices: ['postgres', 'mysql', 'mongodb', 'redis', 'dynamodb'] }], options: [] },
+    { name: 'exec', summary: 'run a command inside the sandbox and print its output', group: 'Sandbox', args: [{ name: 'command', description: 'command and its arguments', required: true, variadic: true }], options: [{ flag: '--timeout', type: 'number', value: 'seconds', description: 'give up after this many seconds', default: 600 }, text('--workspace', 'dir', 'folder (inside the mapped workspace) to run in')], passthrough: 'command', json },
+    { name: 'restart', summary: 'restart running agents in place; they resume their conversation', group: 'Sessions', args: [], options: [text('--harness', 'name', 'only this agent', { choices: 'harnesses' })] },
+    { name: 'stop', summary: 'shut the sandbox down', group: 'Sandbox', args: [], options: [] },
+    { name: 'show', summary: 'show the sandbox window', group: 'Sandbox', args: [], options: [] },
+    { name: 'hide', summary: 'hide the sandbox window (it keeps running)', group: 'Sandbox', args: [], options: [] },
+    { name: 'account', summary: 'Claude accounts: list, save, use, set the default, remove', group: 'Accounts', args: [{ name: 'action', description: 'what to do', required: false, choices: ['list', 'save', 'use', 'default', 'remove'] }, { name: 'name', description: 'account name', required: false, choices: 'accounts' }], options: [bool('--from-host', '(save) save this PC\'s login instead of the sandbox\'s'), bool('--no-restart', '(use) do not restart running sessions')], json },
+    { name: 'data', summary: 'what persists between sandboxes (tools, databases, logins, logs), and cleaning it', group: 'Data', args: [{ name: 'action', description: 'show or clean', required: false, choices: ['show', 'clean'] }, { name: 'targets', description: 'what to clean, e.g. tools/go databases logs', required: false, variadic: true }], options: [bool('--yes', 'do not ask before deleting')], json },
+    { name: 'clean', summary: 'delete old launch folders, logs and leftovers', group: 'Data', args: [], options: [{ flag: '--days', type: 'number', value: 'n', description: 'launch folders older than this many days', default: 7 }] },
+    { name: 'sync', summary: 'copy history (and claude-mem, once closed) back to this PC now', group: 'Data', args: [], options: [] },
+    { name: 'logs', summary: 'print the newest sandbox log', group: 'Health', args: [], options: [bool('--follow', 'keep printing new lines', { short: '-f' })] },
+    { name: 'setup', summary: 'check this PC can run Windows Sandbox and offer to turn it on', group: 'Health', args: [], options: [] },
+    { name: 'doctor', summary: 'check this PC and show what will be copied or downloaded', group: 'Health', args: [], options: [text('--harness', 'name', 'agent to check', { choices: 'harnesses' })] },
+    { name: 'repair', summary: 'find and fix common problems (stale state, broken downloads, half-installed tools)', group: 'Health', args: [], options: [] },
+    { name: 'self-test', summary: 'run the built-in tests', group: 'Health', args: [], options: [] },
+    { name: 'config', summary: 'show the effective config, its path, create it, editor schemas, or check a project\'s .sandbox-config.json', group: 'Config', args: [{ name: 'action', description: 'what to do', required: false, choices: ['show', 'path', 'init', 'schema', 'check'] }], options: [text('--workspace', 'dir', '(check) the project folder; default: the current one')] },
+    { name: 'host-claude', summary: 'Claude on this PC (NOT sandboxed) with a separate profile', group: 'Agents', args: [], options: [bool('--personal', 'use your normal Claude profile')], passthrough: 'agent', interactive: true },
+    { name: 'menu', summary: 'the interactive menu (what `sandbox` opens with no arguments)', group: 'Config', args: [], options: [], hidden: true, interactive: true },
+    { name: '_watch', summary: 'background history sync', group: 'Data', args: [], options: [], hidden: true },
+]);
+export const commandSpec = (name) => COMMANDS.find((c) => c.name === name);

package/dist/cli/menu.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import type { Context } from './commands/context.js';
+import { type CommandSpecT } from './manifest.js';
+declare const History: z.ZodArray<z.ZodObject<{
+    argv: z.ZodArray<z.ZodString>;
+    at: z.ZodString;
+}, z.core.$strict>>;
+export declare const readHistory: () => z.output<typeof History>;
+/** Remembers a command (menu or typed) so the menu can offer it again. Never fails the command itself. */
+export declare const recordHistory: (argv: string[]) => void;
+/** argv as you would type it (quoted where needed). */
+export declare const commandLine: (argv: string[]) => string;
+/** Splits "a b 'c d'" like a shell would (enough for agent arguments and exec commands). */
+export declare const splitArgs: (text: string) => string[];
+/** Asks everything a command takes and returns its argv (or null when the user backs out). */
+export declare const askCommand: (ctx: Context, spec: CommandSpecT, preset?: string[]) => Promise<string[] | null>;
+/**
+ * Runs the menu until Exit, or until a command that takes over the terminal (launch, attach) has run. `run` executes
+ * an argv exactly like typing it.
+ */
+export declare const menu: (ctx: Context, run: (argv: string[]) => Promise<number>) => Promise<number>;
+export {};

package/dist/cli/menu.js

@@ -0,0 +1,187 @@
+// The interactive menu (`sandbox` with no arguments). Built from manifest.ts: pick a command, answer one question per
+// argument and option (on/off options as checkboxes), see the exact command line, run it. The command line it shows is
+// what you would type yourself, and the last one is offered again at the top next time.
+import fs from 'node:fs';
+import path from 'node:path';
+import { checkbox, confirm, input, select, Separator } from '@inquirer/prompts';
+import { z } from 'zod';
+import { userDir } from '../core/config.js';
+import { tryReadJson, writeJson } from '../core/util.js';
+import { listAccounts } from '../host/accounts.js';
+import { runningSessions } from '../host/channel.js';
+import { isSandboxRunning } from '../host/platform.js';
+import { settingsMenu } from './settings.js';
+import { COMMANDS, Group } from './manifest.js';
+const c = { bold: (s) => '\x1b[1m' + s + '\x1b[0m', dim: (s) => '\x1b[2m' + s + '\x1b[0m', cyan: (s) => '\x1b[36m' + s + '\x1b[0m', green: (s) => '\x1b[32m' + s + '\x1b[0m', yellow: (s) => '\x1b[33m' + s + '\x1b[0m' };
+// ---- history ---------------------------------------------------------------------------------------------------------
+const History = z.array(z.strictObject({ argv: z.array(z.string()).max(200), at: z.string() })).max(20);
+const historyFile = () => path.join(userDir(), 'history.json');
+const HIDDEN = new Set(['menu', '_watch', 'self-test']);
+export const readHistory = () => History.safeParse(tryReadJson(historyFile())).data ?? [];
+/** Remembers a command (menu or typed) so the menu can offer it again. Never fails the command itself. */
+export const recordHistory = (argv) => {
+    if (!argv.length || HIDDEN.has(argv[0]) || argv.includes('--help'))
+        return;
+    try {
+        writeJson(historyFile(), [{ argv, at: new Date().toISOString() }, ...readHistory().filter((h) => h.argv.join('\0') !== argv.join('\0'))].slice(0, 10));
+    }
+    catch { /* history is a convenience */ }
+};
+/** argv as you would type it (quoted where needed). */
+export const commandLine = (argv) => ['sandbox', ...argv].map((a) => (/[\s"]/.test(a) || a === '' ? '"' + a.replace(/"/g, '\\"') + '"' : a)).join(' ');
+// ---- asking for one command ------------------------------------------------------------------------------------------
+/** Values for a choices list the manifest names (filled in from config and the running sandbox). */
+const choicesFor = (ctx, choices) => {
+    if (Array.isArray(choices))
+        return choices;
+    if (choices === 'harnesses')
+        return Object.keys(ctx.loaded.config.harnesses);
+    if (choices === 'accounts')
+        return listAccounts(ctx.storageRoot, ctx.dataPath).map((a) => a.name);
+    if (choices === 'sessions')
+        return isSandboxRunning() ? runningSessions(ctx.dataPath).map((s) => s.id) : [];
+    return [];
+};
+/** Splits "a b 'c d'" like a shell would (enough for agent arguments and exec commands). */
+export const splitArgs = (text) => [...text.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)].map((m) => m[1] ?? m[2] ?? m[3]);
+const askArg = async (ctx, arg) => {
+    const list = choicesFor(ctx, arg.choices);
+    if (list.length && !arg.variadic) {
+        const picked = await select({ message: arg.description, choices: [...list.map((v) => ({ name: v, value: v })), ...(arg.required ? [] : [{ name: c.dim('(skip)'), value: '' }])] });
+        return picked ? [picked] : [];
+    }
+    const answer = await input({ message: arg.description + (arg.required ? '' : c.dim(' (optional)')), validate: (v) => (!arg.required || v.trim() !== '' ? true : 'required') });
+    return arg.variadic ? splitArgs(answer) : answer.trim() ? [answer.trim()] : [];
+};
+const askOptions = async (ctx, options) => {
+    const argv = [];
+    const flags = options.filter((o) => o.type === 'boolean');
+    if (flags.length)
+        argv.push(...await checkbox({ message: 'Options ' + c.dim('(space to toggle, enter to continue)'), choices: flags.map((o) => ({ name: o.flag + c.dim('  ' + o.description), value: o.flag })) }));
+    for (const o of options.filter((x) => x.type !== 'boolean')) {
+        const list = choicesFor(ctx, o.choices);
+        const label = o.flag + c.dim('  ' + o.description);
+        const value = list.length
+            ? await select({ message: label, choices: [{ name: c.dim('(default)'), value: '' }, ...list.map((v) => ({ name: v, value: v }))] })
+            : await input({ message: label + c.dim(o.default !== undefined ? ' (default ' + o.default + ')' : ' (empty = default)'), validate: (v) => (o.type !== 'number' || v === '' || Number(v) > 0 ? true : 'a positive number') });
+        if (!value)
+            continue;
+        for (const v of o.type === 'list' ? splitArgs(value) : [value])
+            argv.push(o.flag, v);
+    }
+    return argv;
+};
+/** Asks everything a command takes and returns its argv (or null when the user backs out). */
+export const askCommand = async (ctx, spec, preset = []) => {
+    console.log('\n' + c.bold(spec.name) + c.dim('  ' + spec.summary));
+    const argv = [spec.name, ...preset];
+    for (const arg of spec.args)
+        argv.push(...await askArg(ctx, arg));
+    const basic = spec.options.filter((o) => !o.advanced && !preset.includes(o.flag));
+    const advanced = spec.options.filter((o) => o.advanced);
+    argv.push(...await askOptions(ctx, basic));
+    if (advanced.length && await confirm({ message: 'Change advanced options (' + advanced.map((o) => o.flag).join(', ') + ')?', default: false }))
+        argv.push(...await askOptions(ctx, advanced));
+    if (spec.json && await confirm({ message: 'Machine-readable output (--json)?', default: false }))
+        argv.push('--json');
+    if (spec.passthrough) {
+        const extra = splitArgs(await input({ message: spec.passthrough === 'agent' ? 'Extra arguments for the agent ' + c.dim('(optional, e.g. --continue)') : 'Arguments for the command' + c.dim(' (optional)') }));
+        if (extra.length)
+            argv.push(...(spec.passthrough === 'agent' ? ['--', ...extra] : extra));
+    }
+    console.log(c.dim('  ' + commandLine(argv)));
+    return await confirm({ message: 'Run it?', default: true }) ? argv : null;
+};
+// ---- the menu --------------------------------------------------------------------------------------------------------
+/** Is this agent already in the sandbox's persistent storage (so starting it needs no install)? */
+const agentInstalled = (ctx, name) => {
+    const h = ctx.loaded.config.harnesses[name];
+    const dir = path.join(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)));
+};
+const GROUP_TITLES = { Agents: 'Start an agent', Sandbox: 'Sandbox', Sessions: 'Sessions (attach, restart)', Accounts: 'Claude accounts', Data: 'Persisted data, sync and cleanup', Health: 'Diagnostics and repair (doctor, setup, repair, dry run, logs)', Config: 'Configuration' };
+const pickAgent = async (ctx) => {
+    const names = Object.keys(ctx.loaded.config.harnesses);
+    const name = await select({
+        message: 'Which agent?',
+        pageSize: 16,
+        choices: [
+            ...names.map((n) => ({ name: n.padEnd(10) + (agentInstalled(ctx, n) ? c.green(' installed') : c.dim(' installs on first start')) + (n === ctx.loaded.config.defaultHarness ? c.dim('  (default)') : ''), value: n })),
+            new Separator(),
+            { name: 'Claude on this PC, NOT sandboxed (host-claude)', value: '@host' },
+            { name: c.dim('< back'), value: '' },
+        ],
+    });
+    if (name === '@host')
+        return { kind: 'ask', spec: COMMANDS.find((s) => s.name === 'host-claude') };
+    return name ? { kind: 'ask', spec: COMMANDS.find((s) => s.name === 'launch'), preset: ['--harness', name] } : { kind: 'group', group: '' };
+};
+const mainMenu = async (ctx) => {
+    const last = readHistory()[0];
+    const running = isSandboxRunning();
+    console.log('\n' + c.bold(c.cyan('Windows Development Sandbox')) + c.dim('  ' + process.cwd()) + '\n' + (running ? c.green('  A sandbox is running') + c.dim(' (' + runningSessions(ctx.dataPath).length + ' session(s))') : c.dim('  No sandbox running')));
+    return select({
+        message: 'What would you like to do?',
+        pageSize: 14,
+        choices: [
+            ...(last ? [{ name: 'Repeat last: ' + c.cyan(commandLine(last.argv)), value: { kind: 'run', argv: last.argv } }] : []),
+            { name: 'Start ' + ctx.loaded.config.defaultHarness + ' in this folder', value: { kind: 'ask', spec: COMMANDS.find((s) => s.name === 'launch'), preset: ['--harness', ctx.loaded.config.defaultHarness] } },
+            { name: 'Start another agent...', value: { kind: 'group', group: '@agents' } },
+            { name: 'Start a sandbox without an agent', value: { kind: 'ask', spec: COMMANDS.find((s) => s.name === 'start') } },
+            new Separator(),
+            ...Group.options.filter((g) => g !== 'Agents').map((g) => ({ name: GROUP_TITLES[g] + '...', value: { kind: 'group', group: g } })),
+            { name: 'Settings ' + c.dim('(every setting, saved to your config file)'), value: { kind: 'group', group: '@settings' } },
+            new Separator(),
+            { name: 'Exit', value: { kind: 'exit' } },
+        ],
+    });
+};
+const groupMenu = async (group) => select({
+    message: GROUP_TITLES[group] ?? group,
+    pageSize: 16,
+    choices: [
+        ...COMMANDS.filter((s) => s.group === group && !s.hidden).map((s) => ({ name: s.name.padEnd(10) + c.dim(' ' + s.summary), value: { kind: 'ask', spec: s } })),
+        { name: c.dim('< back'), value: { kind: 'group', group: '' } },
+    ],
+});
+/**
+ * Runs the menu until Exit, or until a command that takes over the terminal (launch, attach) has run. `run` executes
+ * an argv exactly like typing it.
+ */
+export const menu = async (ctx, run) => {
+    if (!process.stdin.isTTY) {
+        console.log('The menu needs an interactive terminal. Run sandbox --help for the commands.');
+        return 1;
+    }
+    try {
+        for (let pick = await mainMenu(ctx);;) {
+            if (pick.kind === 'exit')
+                return 0;
+            if (pick.kind === 'group' && pick.group === '@settings') {
+                await settingsMenu(ctx.loaded.configPath);
+                pick = await mainMenu(ctx);
+            }
+            else if (pick.kind === 'group')
+                pick = pick.group === '' ? await mainMenu(ctx) : pick.group === '@agents' ? await pickAgent(ctx) : await groupMenu(pick.group);
+            else {
+                const argv = pick.kind === 'run' ? pick.argv : await askCommand(ctx, pick.spec, pick.preset);
+                if (!argv) {
+                    pick = await mainMenu(ctx);
+                    continue;
+                }
+                const code = await run(argv);
+                if (COMMANDS.find((s) => s.name === argv[0])?.interactive)
+                    return code;
+                await input({ message: c.dim((code === 0 ? 'Done' : yellowCode(code)) + '. Press Enter for the menu') });
+                pick = await mainMenu(ctx);
+            }
+        }
+    }
+    catch (e) {
+        // Ctrl+C in a prompt: leave quietly.
+        if (e instanceof Error && e.name === 'ExitPromptError')
+            return 130;
+        throw e;
+    }
+};
+const yellowCode = (code) => c.yellow('Exit code ' + code);

package/dist/cli/settings.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Applies one change (undefined = back to the default) to the config text and returns the new text, or the problems
+ * that make the result invalid. Pure: the caller writes the file.
+ */
+export declare const editConfigText: (text: string, key: string[], value: unknown) => {
+    text: string;
+} | {
+    problems: string[];
+};
+/** The settings screen. Changes are saved to the user config file (created when missing). */
+export declare const settingsMenu: (configPath: string | null) => Promise<void>;