windows-development-sandbox 1.0.5 → 1.1.0

package/dist/cli/menu.js

@@ -4,31 +4,46 @@
 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 { humanBytes } from '../core/disk.js';
+import { errMsg, fail } 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;
+import { cleanTargetOf, collectDataEntries } from './commands/data/collect.js';
+import { c, clearScreen, pageSizeFor, shorten, shortenMiddle, termWidth } from './colors.js';
+import { commandLine, readHistory } from './history.js';
+import { settingsMenu } from './settings/index.js';
+import { splitArgs } from './args.js';
+import { syncAgentCommands } from './commands/agent-commands.js';
+import { loadConfig } from '../core/config.js';
+import { askedWhen, COMMANDS, Group } from './manifest.js';
+import { askSeveralAgents } from './menu-multi.js';
+import { validNodeSpec, validPythonSpec } from './validate.js';
+// ---- the screen ------------------------------------------------------------------------------------------------------
+/** The settings screen may have switched agentCommands (Beta): apply it now, from the saved file. */
+const applyAgentCommands = (ctx) => {
     try {
-        writeJson(historyFile(), [{ argv, at: new Date().toISOString() }, ...readHistory().filter((h) => h.argv.join('\0') !== argv.join('\0'))].slice(0, 10));
+        syncAgentCommands(ctx, loadConfig(ctx.loaded.configPath ?? undefined).config);
+    }
+    catch (e) {
+        console.warn('Agent commands (Beta): ' + errMsg(e));
     }
-    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(' ');
+/** Waits for one key, so the output of a command stays on screen until you have read it. Ctrl+C leaves. */
+const pressAnyKey = (message) => new Promise((resolve) => {
+    process.stdout.write('\n' + c.dim(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)
+            process.exit(130);
+        resolve();
+    });
+});
 // ---- asking for one command ------------------------------------------------------------------------------------------
 /** Values for a choices list the manifest names (filled in from config and the running sandbox). */
 const choicesFor = (ctx, choices) => {
@@ -43,27 +58,77 @@ const choicesFor = (ctx, choices) => {
     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) => {
+export { splitArgs };
+/** What this option accepts, checked while typing (undefined = anything). */
+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;
+};
+/** Targets of `data clean` as a checkbox list with sizes (never "all", never --yes: those are typed on purpose). */
+const askDataTargets = async (ctx) => {
+    console.log(c.dim('Measuring the saved data (big folders take a moment)...'));
+    const rows = collectDataEntries(ctx.dataPath, ctx.storageRoot).flatMap((e) => { const target = cleanTargetOf(e); return target ? [{ target, bytes: e.bytes }] : []; });
+    if (!rows.length) {
+        console.log('Nothing is saved yet, so there is nothing to delete.');
+        return [];
+    }
+    const width = Math.max(...rows.map((r) => r.target.length));
+    return checkbox({
+        message: 'Delete which? ' + c.dim('(space to tick, enter to continue; you confirm once more)'),
+        pageSize: pageSizeFor(16),
+        choices: rows.map((r) => ({ name: r.target.padEnd(width) + '  ' + humanBytes(r.bytes).padStart(8), value: r.target, short: r.target })),
+        validate: (picked) => (picked.length > 0 ? true : 'Tick at least one with space, or press Ctrl+C to go back.'),
+    });
+};
+const askArg = async (ctx, spec, arg) => {
+    if (spec.name === 'data' && arg.name === 'targets')
+        return askDataTargets(ctx);
     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') });
+    // A list the manifest fills in at run time (saved accounts, running sessions) that is empty: nothing to pick, so do not ask.
+    if (typeof arg.choices === 'string' && !arg.required)
+        return [];
+    if (typeof arg.choices === 'string')
+        fail('There is nothing to choose from: no ' + arg.choices + ' yet.', arg.choices === 'accounts' ? 'Sign in inside the sandbox, then run: sandbox account save <name>' : 'Start one first (sandbox claude).');
+    const answer = await input({ message: arg.description + (arg.required ? '' : c.dim(' (optional)')), validate: (v) => (!arg.required || v.trim() !== '' ? true : 'This is 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 })) }));
+        argv.push(...await checkbox({ message: 'Options ' + c.dim('(space to toggle, enter to continue)'), choices: flags.map((o) => ({ name: o.flag + c.dim('  ' + shorten(o.description, Math.max(20, termWidth() - o.flag.length - 8))), 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);
+        // A named list that is empty (no saved accounts) has nothing to pick: leave the option out.
+        if (typeof o.choices === 'string' && !list.length)
+            continue;
+        if (o.type === 'list' && list.length) {
+            for (const v of await checkbox({ message: label, choices: list.map((v) => ({ name: v, value: v })) }))
+                argv.push(o.flag, v);
+            continue;
+        }
         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') });
+            ? await select({ message: label, choices: [{ name: c.dim('(default' + (o.choices === 'harnesses' ? ': ' + ctx.loaded.config.defaultHarness : o.choices === 'accounts' ? ': none chosen' : '') + ')'), value: '' }, ...list.map((v) => ({ name: v, value: v }))] })
+            : await input({ message: label + c.dim(o.default !== undefined ? ' (default ' + o.default + ')' : ' (empty = default)'), validate: (v) => optionProblem(o, v) ?? true });
         if (!value)
             continue;
         for (const v of o.type === 'list' ? splitArgs(value) : [value])
@@ -73,16 +138,34 @@ const askOptions = async (ctx, options) => {
 };
 /** 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));
+    console.log('\n' + c.bold(spec.name) + c.dim('  ' + shorten(spec.summary, termWidth() - spec.name.length - 3)));
     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);
+    // The common case needs one answer: start with the settings you already have, or change them first.
+    if (spec.name === 'launch' && preset.length) {
+        const quick = await select({ message: 'Start ' + (preset[preset.indexOf('--harness') + 1] ?? 'the agent') + ' in ' + shortenMiddle(process.cwd(), Math.max(20, termWidth() - 30)), choices: [{ name: 'Start now', value: 'now' }, { name: 'Change options first...', value: 'custom' }, { name: c.dim('< back'), value: 'back' }] });
+        if (quick === 'back')
+            return null;
+        if (quick === 'now') {
+            console.log(c.dim('  ' + commandLine(argv)));
+            return argv;
+        }
+    }
+    let first = '';
+    for (const [i, arg] of spec.args.entries()) {
+        if (!askedWhen(arg.when, first))
+            continue;
+        const answer = await askArg(ctx, spec, arg);
+        if (i === 0)
+            first = answer[0] ?? '';
+        argv.push(...answer);
+    }
+    const offered = (o) => !o.noMenu && askedWhen(o.when, first);
+    const basic = spec.options.filter((o) => !o.advanced && !preset.includes(o.flag) && offered(o));
+    const advanced = spec.options.filter((o) => o.advanced && offered(o));
     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 }))
+    if (spec.json && !(spec.name === 'data' && first === 'clean') && 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)') }));
@@ -99,12 +182,13 @@ const agentInstalled = (ctx, 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 GROUP_TITLES = { Agents: 'Start an agent', Sandbox: 'Sandbox', Sessions: 'Sessions', Accounts: 'Claude accounts', Data: 'Saved data and cleanup', Health: 'Diagnostics and repair', Config: 'Configuration' };
 const pickAgent = async (ctx) => {
     const names = Object.keys(ctx.loaded.config.harnesses);
+    clearScreen();
     const name = await select({
         message: 'Which agent?',
-        pageSize: 16,
+        pageSize: pageSizeFor(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(),
@@ -119,13 +203,15 @@ const pickAgent = async (ctx) => {
 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')));
+    clearScreen();
+    console.log(c.bold(c.cyan('Windows Development Sandbox')) + c.dim('  ' + shortenMiddle(process.cwd(), Math.max(20, termWidth() - 32))) + '\n' + (running ? c.green('  A sandbox is running') + c.dim(' (' + runningSessions(ctx.dataPath).length + ' session(s))') : c.dim('  No sandbox running')) + '\n');
     return select({
         message: 'What would you like to do?',
-        pageSize: 14,
+        pageSize: pageSizeFor(14),
         choices: [
-            ...(last ? [{ name: 'Repeat last: ' + c.cyan(commandLine(last.argv)), value: { kind: 'run', argv: last.argv } }] : []),
+            ...(last ? [{ name: 'Repeat last: ' + c.cyan(shorten(commandLine(last.argv), Math.max(20, termWidth() - 20))), 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 several agents (one or more projects, attach to any)...', value: { kind: 'several' } },
             { 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(),
@@ -136,14 +222,17 @@ const mainMenu = async (ctx) => {
         ],
     });
 };
-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: '' } },
-    ],
-});
+const groupMenu = async (group) => {
+    clearScreen();
+    return select({
+        message: GROUP_TITLES[group] ?? group,
+        pageSize: pageSizeFor(16),
+        choices: [
+            ...COMMANDS.filter((s) => s.group === group && !s.hidden).map((s) => ({ name: s.name.padEnd(10), description: 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.
@@ -159,20 +248,34 @@ export const menu = async (ctx, run) => {
                 return 0;
             if (pick.kind === 'group' && pick.group === '@settings') {
                 await settingsMenu(ctx.loaded.configPath);
+                applyAgentCommands(ctx);
                 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);
+                // Ctrl+C while answering the questions of one command goes back to the menu; on the menu itself it leaves.
+                let argv;
+                try {
+                    clearScreen();
+                    argv = pick.kind === 'run' ? pick.argv : pick.kind === 'several' ? await askSeveralAgents(ctx) : await askCommand(ctx, pick.spec, pick.preset);
+                }
+                catch (e) {
+                    if (e instanceof Error && e.name === 'ExitPromptError')
+                        argv = null;
+                    else
+                        throw e;
+                }
                 if (!argv) {
                     pick = await mainMenu(ctx);
                     continue;
                 }
+                clearScreen();
+                console.log(c.dim('$ ' + commandLine(argv)) + '\n');
                 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') });
+                await pressAnyKey((code === 0 ? c.green('Done.') : yellowCode(code)) + ' Press any key for the menu...');
                 pick = await mainMenu(ctx);
             }
         }

package/dist/cli/progress.d.ts

@@ -0,0 +1,9 @@
+/** Can a line be redrawn in place? */
+export declare const canAnimate: (env: NodeJS.ProcessEnv, isTTY: boolean) => boolean;
+/** "12 s", "2 min 5 s". */
+export declare const elapsed: (ms: number) => string;
+/**
+ * Shows `message` while work runs and removes the line afterwards. The spinner only moves while the event loop is free
+ * (waiting on the sandbox); for long synchronous work (measuring folders) the static line is what you see.
+ */
+export declare const working: <T>(message: string | (() => string), work: () => Promise<T> | T, enabled?: boolean) => Promise<T>;

package/dist/cli/progress.js

@@ -0,0 +1,49 @@
+// Feedback for slow work: a spinner line on stderr (so --json and piped output stay clean). Without a terminal (pipe, CI,
+// TERM=dumb) it prints one plain line instead of animating.
+import { colorEnabled, shorten, termWidth } from './colors.js';
+const FRAMES = ['|', '/', '-', '\\'];
+/** Can a line be redrawn in place? */
+export const canAnimate = (env, isTTY) => isTTY && !env.CI && env.TERM !== 'dumb';
+/** "12 s", "2 min 5 s". */
+export const elapsed = (ms) => {
+    const s = Math.round(ms / 1000);
+    return s < 60 ? s + ' s' : Math.floor(s / 60) + ' min ' + (s % 60) + ' s';
+};
+/**
+ * Shows `message` while work runs and removes the line afterwards. The spinner only moves while the event loop is free
+ * (waiting on the sandbox); for long synchronous work (measuring folders) the static line is what you see.
+ */
+export const working = async (message, work, enabled = true) => {
+    if (!enabled)
+        return work();
+    const err = process.stderr;
+    const start = Date.now();
+    // A function: the message follows the work (e.g. the sandbox's boot step); without a terminal each new one is a line.
+    const text = () => (typeof message === 'function' ? message() : message);
+    if (!canAnimate(process.env, Boolean(err.isTTY))) {
+        let last = text();
+        err.write(last + '...\n');
+        const follow = typeof message === 'function' ? setInterval(() => { const now = text(); if (now !== last) {
+            last = now;
+            err.write(now + '\n');
+        } }, 500) : null;
+        try {
+            return await work();
+        }
+        finally {
+            if (follow)
+                clearInterval(follow);
+        }
+    }
+    let frame = 0;
+    const draw = () => { err.write('\r\x1b[2K' + (colorEnabled(process.env, true) ? '\x1b[36m' : '') + FRAMES[frame++ % FRAMES.length] + (colorEnabled(process.env, true) ? '\x1b[0m' : '') + ' ' + shorten(text(), termWidth() - 14) + (Date.now() - start > 3000 ? ' (' + elapsed(Date.now() - start) + ')' : '')); };
+    draw();
+    const timer = setInterval(draw, 120);
+    try {
+        return await work();
+    }
+    finally {
+        clearInterval(timer);
+        err.write('\r\x1b[2K');
+    }
+};

package/dist/cli/settings/edit.d.ts

@@ -0,0 +1,13 @@
+/** 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 the file (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 the config text and returns the new text, or
+ * the problems that make the result invalid.
+ */
+export declare const editConfigText: (text: string, key: string[], value: unknown, target?: SettingsTarget) => {
+    text: string;
+} | {
+    problems: string[];
+};

package/dist/cli/settings/edit.js

@@ -0,0 +1,19 @@
+// Changing a config file's text: one setting at a time, through jsonc-parser so comments and formatting stay, and never
+// into something invalid. Pure; the caller writes the file.
+import { applyEdits, modify, parse } from 'jsonc-parser';
+import _ from 'lodash';
+import { DEFAULTS, mergeConfig } from '../../core/config.js';
+import { Config, describeIssues, LocalOverrides } from '../../core/schema.js';
+/** What the value is in the file (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 the config text and returns the new text, or
+ * the problems that make the result invalid.
+ */
+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) ?? {}) : Config.safeParse(mergeConfig(DEFAULTS, parse(next) ?? {}));
+    return parsed.success ? { text: next.endsWith('\n') ? next : next + '\n' } : { problems: describeIssues(parsed.error) };
+};

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

@@ -0,0 +1,8 @@
+export { editConfigText } from './edit.js';
+/** Titles of the top-level sections in the menu. A test makes sure every section of the schema has one. */
+export declare const SECTION_TITLES: Record<string, string>;
+/**
+ * The settings screen: first which file to edit (your own, or this folder's project file), then its settings. Your file
+ * is created when missing; so is the project file once a setting is saved.
+ */
+export declare const settingsMenu: (configPath: string | null, projectDir?: string) => Promise<void>;

package/dist/cli/settings/index.js

@@ -0,0 +1,131 @@
+// The settings screen in the menu: every setting, generated from the zod schemas (so nothing needs to be listed by
+// hand), shown with its current value and description, edited with a fitting prompt and saved to a config file. Two
+// files can be edited: your own (all projects) and this folder's .sandbox-config.json (only what a project may set).
+// Edits keep comments and formatting, and nothing is written unless the whole file is still valid.
+import fs from 'node:fs';
+import path from 'node:path';
+import { select, Separator } from '@inquirer/prompts';
+import _ from 'lodash';
+import { DEFAULTS, loadConfig, userConfigPath } from '../../core/config.js';
+import { LOCAL_CONFIG_NAME, NEVER_LOOSER } from '../../core/local-config.js';
+import { Config as ConfigSchema, LocalOverrides } from '../../core/schema.js';
+import { c, clearScreen, pageSizeFor, shortenMiddle, termWidth } from '../colors.js';
+import { editConfigText, fileValue } from './edit.js';
+import { askValue } from './prompts.js';
+import { childrenOf, describeSetting, isSection, unwrap } from './schema.js';
+export { editConfigText } from './edit.js';
+/** Titles of the top-level sections in the menu. A test makes sure every section of the schema has one. */
+export const SECTION_TITLES = {
+    toolchains: 'Languages and tools', databases: 'Databases', sandbox: 'The sandbox machine (memory, window, GPU, network)', attach: 'Attaching (auto attach, auto hide)', agentCommands: 'Agent commands: claude, codex ... start in a sandbox (Beta)',
+    provisioning: 'Provisioning and git', downloads: 'Downloads (checksums)', secrets: 'Secrets', claudeProfile: 'Your Claude settings and history', storage: 'Storage',
+    network: 'Network', hooks: 'Hooks', personalization: 'Desktop look', projects: 'Several projects (project roots, adding folders while running)',
+};
+/** A value in one short line: maps as their keys, long lists shortened. */
+const show = (value) => {
+    if (value === undefined)
+        return c.dim('(not set)');
+    if (typeof value === 'string')
+        return value;
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const keys = Object.keys(value);
+        return keys.length ? '{ ' + _.truncate(keys.join(', '), { length: 60 }) + ' }' : '{}';
+    }
+    return _.truncate(JSON.stringify(value), { length: 70 });
+};
+const readText = (file) => (fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '');
+/** The user's settings with the built-in defaults filled in (what a sandbox would use without a project file). */
+const userConfig = (file) => loadConfig(fs.existsSync(file) ? file : undefined).config;
+/** What is in effect now: for your own file the merged config, for a project file only what that file sets. */
+const currentValue = (session, key, text, config) => session.target === 'project' ? fileValue(text, key) : _.get(config, key);
+/** Edits one setting: shows it, asks, saves (or resets it to the default / removes it from the project file). */
+const editSetting = async (session, schema, key, config) => {
+    const { file, target } = session;
+    const text = readText(file);
+    const inFile = fileValue(text, key);
+    const project = target === 'project';
+    console.log('\n' + c.cyan(key.join('.')) + (describeSetting(schema) ? '\n' + c.dim(describeSetting(schema)) : ''));
+    if (project && NEVER_LOOSER.includes(key.join('.')))
+        console.log(c.yellow('A project can only make this stricter than your own setting; a looser value is ignored.'));
+    console.log('Now: ' + (project ? show(inFile) + c.dim(inFile === undefined ? '  (not set in this project; yours: ' + show(_.get(config, key)) + ')' : '  (set in ' + file + ')') : show(_.get(config, key)) + (inFile === undefined ? c.dim('  (built-in default)') : c.dim('  (set in ' + file + ')'))));
+    const resetLabel = project ? 'Remove from this project file' : 'Reset to the default (' + show(_.get(DEFAULTS, key)) + ')';
+    const action = inFile === undefined ? 'change' : await select({ message: 'What now?', choices: [{ name: 'Change it', value: 'change' }, { name: resetLabel, value: 'reset' }, { name: c.dim('< back'), value: 'back' }] });
+    if (action === 'back')
+        return;
+    const answer = action === 'reset' ? { value: undefined } : await askValue(schema, key, project ? inFile ?? _.get(config, key) : _.get(config, key), config);
+    if (!answer)
+        return;
+    // In your own file the default needs no line; an unchanged value needs no save.
+    const value = !project && _.isEqual(answer.value, _.get(DEFAULTS, key)) ? undefined : answer.value;
+    if (value === inFile && (project || _.isEqual(answer.value, _.get(config, key)))) {
+        console.log(c.dim('Unchanged.'));
+        return;
+    }
+    const result = editConfigText(text, key, value, target);
+    if ('problems' in result) {
+        console.log(c.red('Not saved: ') + result.problems.join('; '));
+        return;
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, result.text, 'utf8');
+    console.log(c.green('Saved') + c.dim(' to ' + file + (project ? '.' : '. New sandboxes use it.')));
+    // The approval is tied to the file's exact contents, so any change makes the project file untrusted again.
+    if (project)
+        console.log(c.yellow('This project file is not approved any more: the next launch shows what it applies and asks you to approve it.'));
+};
+/** Browses one level of settings; sections open, leaves are edited. */
+const browse = async (session, schema, key) => {
+    for (;;) {
+        const config = userConfig(session.target === 'user' ? session.file : userConfigPath());
+        const entries = childrenOf(schema);
+        const text = readText(session.file);
+        clearScreen();
+        console.log(c.dim('Editing ' + shortenMiddle(session.file, termWidth() - 10)) + '\n' + c.dim('Values in ') + c.yellow('yellow') + c.dim(' (marked *) are set in that file; the rest are defaults.') + '\n');
+        const pickName = await select({
+            message: key.length ? key.join('.') : 'Settings',
+            pageSize: pageSizeFor(18),
+            choices: [
+                ...entries.map(([name, s]) => {
+                    const full = [...key, name];
+                    const changed = fileValue(text, full) !== undefined;
+                    const shown = show(currentValue(session, full, text, config));
+                    const label = isSection(s) ? (key.length ? name : SECTION_TITLES[name] ?? name) + c.dim(' ...') : name.padEnd(18) + ' ' + (changed ? c.yellow(shown) + ' *' : shown);
+                    return { name: label, value: name, description: describeSetting(s) };
+                }),
+                new Separator(),
+                { name: c.dim('< back'), value: '@back' },
+            ],
+        });
+        if (pickName === '@back')
+            return;
+        const child = unwrap(schema).shape[pickName];
+        if (isSection(child))
+            await browse(session, child, [...key, pickName]);
+        else
+            await editSetting(session, child, [...key, pickName], config);
+    }
+};
+/**
+ * The settings screen: first which file to edit (your own, or this folder's project file), then its settings. Your file
+ * is created when missing; so is the project file once a setting is saved.
+ */
+export const settingsMenu = async (configPath, projectDir = process.cwd()) => {
+    const sessions = {
+        user: { target: 'user', file: configPath ?? userConfigPath(), schema: ConfigSchema },
+        project: { target: 'project', file: path.join(projectDir, LOCAL_CONFIG_NAME), schema: LocalOverrides },
+    };
+    for (;;) {
+        clearScreen();
+        const which = await select({
+            message: 'Which settings?',
+            choices: [
+                { name: 'Your settings (all projects)', description: sessions.user.file, value: 'user' },
+                { name: 'This project', description: sessions.project.file + ' (only what a project may set; needs your approval at launch)', value: 'project' },
+                new Separator(),
+                { name: c.dim('< back'), value: '@back' },
+            ],
+        });
+        if (which === '@back')
+            return;
+        await browse(sessions[which], sessions[which].schema, []);
+    }
+};

package/dist/cli/settings/prompts.d.ts

@@ -0,0 +1,7 @@
+import type { Config } from '../../core/types.js';
+import { type Schema } from './schema.js';
+export type Answer = {
+    value: unknown;
+} | undefined;
+/** `key` is the setting's path; `config` (the user's settings) lets the default agent be picked from the configured ones. */
+export declare const askValue: (schema: Schema, key: string[], current: unknown, config?: Config) => Promise<Answer>;

package/dist/cli/settings/prompts.js

@@ -0,0 +1,48 @@
+// The prompt that fits a setting's type. Returns the new value, or undefined to change nothing.
+import { input, select } from '@inquirer/prompts';
+import { c } from '../colors.js';
+import { jsonExample, kind, promptKind, unwrap } from './schema.js';
+const CANCEL = '@cancel';
+const cancel = { name: c.dim('< cancel'), value: CANCEL };
+const pick = async (label, choices, current) => {
+    const v = await select({ message: label, choices: [...choices, cancel], default: current });
+    return v === CANCEL ? undefined : { value: v };
+};
+const typed = async (label, current, validate, convert) => {
+    const shown = current === undefined ? '' : typeof current === 'string' ? current : JSON.stringify(current);
+    const answer = await input({ message: label + c.dim(' (empty = cancel)'), default: shown, validate: (v) => (v === '' ? true : validate(v)) });
+    return answer === '' ? undefined : { value: convert(answer) };
+};
+const BOOLEANS = [{ name: 'true', value: true }, { name: 'false', value: false }];
+/** `key` is the setting's path; `config` (the user's settings) lets the default agent be picked from the configured ones. */
+export const askValue = async (schema, key, current, config) => {
+    const label = key.join('.');
+    const s = unwrap(schema);
+    // The default agent is one of the configured ones: a list, not free text.
+    if (label === 'defaultHarness' && config)
+        return pick(label, Object.keys(config.harnesses).map((h) => ({ name: h, value: h })), current);
+    switch (promptKind(s)) {
+        case 'boolean': return pick(label, BOOLEANS, current);
+        case 'enum': return pick(label, Object.values(s._zod.def.entries ?? {}).map((v) => ({ name: String(v), value: v })), current);
+        case 'union': {
+            const options = s._zod.def.options ?? [];
+            const literals = options.filter((o) => kind(o) === 'literal').flatMap((o) => unwrap(o)._zod.def.values ?? []);
+            const other = options.find((o) => !['literal', 'boolean'].includes(kind(o)));
+            const choices = [...(options.some((o) => kind(o) === 'boolean') ? BOOLEANS : []), ...literals.map((v) => ({ name: String(v), value: v }))];
+            if (!other)
+                return pick(label, choices, current);
+            const chosen = await pick(label, [...choices, { name: 'a ' + kind(other) + ' ...', value: '@other' }], current);
+            return chosen?.value === '@other' ? askValue(other, key, current) : chosen;
+        }
+        case 'number': return typed(label, current, (v) => (Number.isFinite(Number(v)) ? true : 'Enter a number, e.g. 8192.'), Number);
+        case 'string': return typed(label, current, () => true, (v) => v);
+        case 'string-list': return typed(label + c.dim(' (comma separated, [] = none)'), current, () => true, (v) => (v.trim() === '[]' ? [] : v.split(',').map((x) => x.trim()).filter(Boolean)));
+        default: return typed(label + c.dim(' (JSON, e.g. ' + jsonExample(key, s) + ')'), current, (v) => { try {
+            JSON.parse(v);
+            return true;
+        }
+        catch {
+            return 'valid JSON';
+        } }, (v) => JSON.parse(v));
+    }
+};

package/dist/cli/settings/schema.d.ts

@@ -0,0 +1,33 @@
+import type { z } from 'zod';
+export type Schema = z.ZodType & {
+    _zod: {
+        def: {
+            type: string;
+            options?: Schema[];
+            values?: unknown[];
+            entries?: Record<string, string>;
+            element?: Schema;
+            innerType?: Schema;
+        };
+    };
+    shape?: Record<string, Schema>;
+    description?: string;
+};
+/** optional()/default() wrappers hide the real type. */
+export declare const unwrap: (s: Schema) => Schema;
+export declare const kind: (s: Schema) => string;
+export declare const isSection: (s: Schema) => boolean;
+/** The settings one level below a section (or the top level), in schema order. */
+export declare const childrenOf: (schema: Schema) => [string, Schema][];
+/** The description, which `.partial()` and `.optional()` wrappers may carry on the inner schema instead. */
+export declare const describeSetting: (s: Schema) => string | undefined;
+/** Every setting that is edited with a prompt of its own (everything that is not a section), with its path. */
+export declare const leavesOf: (schema: Schema, key?: string[]) => {
+    key: string[];
+    schema: Schema;
+}[];
+export type PromptKind = 'boolean' | 'enum' | 'union' | 'number' | 'string' | 'string-list' | 'json';
+/** Which prompt edits this setting. Lists of objects and maps (mappings, harnesses, environment) fall back to JSON. */
+export declare const promptKind: (schema: Schema) => PromptKind;
+/** A one-line example of the JSON a setting expects, shown in its prompt. */
+export declare const jsonExample: (key: string[], schema: Schema) => string;