windows-development-sandbox 1.4.1 → 1.4.3

package/dist/cli/manifest.js

@@ -1,16 +1,23 @@
 // 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'])])
+const ChoicesSchema = 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(),
+export const OptionSpecSchema = 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(),
+    choices: ChoicesSchema.optional(),
     /** Advanced options are only asked in the menu after "Show advanced options". */
     advanced: z.boolean().optional(),
     /** Only asked in the menu when the command's first argument has this value (account save: --from-host). */
@@ -18,24 +25,26 @@ export const OptionSpec = z.strictObject({
     /** Never offered in the menu (dangerous shortcuts such as --yes); typing it on the command line still works. */
     noMenu: z.boolean().optional(),
 });
-export const ArgSpec = z.strictObject({
+export const ArgSpecSchema = z.strictObject({
     name: z.string(),
     description: z.string(),
     required: z.boolean(),
     variadic: z.boolean().optional(),
-    choices: Choices.optional(),
+    choices: ChoicesSchema.optional(),
     /** Only asked in the menu when the command's first argument has this value, or one of these (data clean: targets). */
     when: z.union([z.string(), z.array(z.string())]).optional(),
 });
 /** Is an argument or option with this `when` asked, given the first argument's answer? */
-export const askedWhen = (when, first) => when === undefined || (Array.isArray(when) ? when.includes(first) : when === first);
-export const Group = z.enum(['Agents', 'Sandbox', 'Sessions', 'Accounts', 'Data', 'Health', 'Config']);
-export const CommandSpec = z.strictObject({
+export function askedWhen(when, first) {
+    return when === undefined || (Array.isArray(when) ? when.includes(first) : when === first);
+}
+export const GroupSchema = z.enum(['Agents', 'Sandbox', 'Sessions', 'Accounts', 'Data', 'Health', 'Config']);
+export const CommandSpecSchema = z.strictObject({
     name: z.string(),
     summary: z.string(),
-    group: Group,
-    args: z.array(ArgSpec),
-    options: z.array(OptionSpec),
+    group: GroupSchema,
+    args: z.array(ArgSpecSchema),
+    options: z.array(OptionSpecSchema),
     /** 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(),
@@ -43,70 +52,335 @@ export const CommandSpec = z.strictObject({
     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 });
+function bool(flag, description, extra = {}) {
+    return {
+        flag,
+        type: 'boolean',
+        description,
+        ...extra,
+    };
+}
+function text(flag, value, description, extra = {}) {
+    return {
+        flag,
+        type: 'string',
+        value,
+        description,
+        ...extra,
+    };
+}
 const SANDBOX_OPTIONS = [
-    bool('--terminal', 'attach this terminal (reuses this folder\'s session if nobody is watching it)', { short: '-t' }),
+    bool('--terminal', "attach this terminal (reuses 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 an unattached one'),
     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)', choices: ['postgres', 'mysql', 'mongodb', 'redis', 'dynamodb'], advanced: true },
-    { flag: '--script', type: 'list', value: 'file', description: 'run this .ps1/.mjs/.cmd inside the sandbox first (repeatable)', advanced: true },
+    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)',
+        choices: ['postgres', 'mysql', 'mongodb', 'redis', 'dynamodb'],
+        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 }),
+    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 }),
     bool('--yes', 'when this folder is not in the running sandbox, or wants what it started without (vGPU, folders), restart without asking', { noMenu: true }),
 ];
 const AGENT_OPTIONS = [
     text('--harness', 'name', 'agent to run', { choices: 'harnesses' }),
-    { flag: '--session', type: 'list', value: 'agent@folder', description: 'start several sessions at once, e.g. --session claude@C:\\code\\api --session "codex@C:\\code\\web|--model o3" (repeatable; after | = that agent\'s own arguments; -t attaches the first)', noMenu: true },
+    {
+        flag: '--session',
+        type: 'list',
+        value: 'agent@folder',
+        description: 'start several sessions at once, e.g. --session claude@C:\\code\\api --session "codex@C:\\code\\web|--model o3" (repeatable; after | = that agent\'s own arguments; -t attaches the first)',
+        noMenu: true,
+    },
     text('--account', 'name', 'Claude account for this sandbox', { choices: 'accounts' }),
     ...SANDBOX_OPTIONS,
     bool('--no-agent', 'set up the sandbox but do not start 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 a sandbox with no agent (tools and databases only)', group: 'Sandbox', args: [], options: SANDBOX_OPTIONS.filter((o) => o.flag !== '--new'), interactive: true },
-    { name: 'generate', summary: 'show what a start would do, without starting anything', 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 },
+const COMMAND_LIST = [
+    {
+        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 a sandbox with no agent (tools and databases only)',
+        group: 'Sandbox',
+        args: [],
+        options: SANDBOX_OPTIONS.filter((o) => o.flag !== '--new'),
+        interactive: true,
+    },
+    {
+        name: 'generate',
+        summary: 'show what a start would do, without starting anything',
+        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: 'show what the sandbox is doing', 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 this project\'s running agents in place; they resume their conversation', group: 'Sessions', args: [], options: [text('--harness', 'name', 'only this agent', { choices: 'harnesses' }), bool('--all', 'every project\'s sessions, not only this folder\'s')] },
-    { name: 'stop', summary: 'shut the sandbox down (every project\'s sessions end)', group: 'Sandbox', args: [], options: [bool('--yes', 'do not ask when other projects\' sessions would end', { noMenu: true })] },
     {
-        name: 'projects', summary: 'the projects a sandbox can open without a restart: list, choose, roots, all/exclude', group: 'Sandbox', json,
+        name: 'db',
+        summary: 'list, start or stop databases in the running sandbox',
+        group: 'Sandbox',
         args: [
-            { name: 'action', description: 'list, choose, add, remove, include, exclude, all, roots', required: false, choices: ['list', 'choose', 'add', 'remove', 'include', 'exclude', 'all', 'roots'] },
-            { name: 'value', description: 'a folder (add, remove, include, exclude), on/off (all), or list/add/remove (roots)', required: false, when: ['add', 'remove', 'include', 'exclude', 'all', 'roots'] },
+            { 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 this project's running agents in place; they resume their conversation",
+        group: 'Sessions',
+        args: [],
+        options: [
+            text('--harness', 'name', 'only this agent', { choices: 'harnesses' }),
+            bool('--all', "every project's sessions, not only this folder's"),
+        ],
+    },
+    {
+        name: 'stop',
+        summary: "shut the sandbox down (every project's sessions end)",
+        group: 'Sandbox',
+        args: [],
+        options: [bool('--yes', "do not ask when other projects' sessions would end", { noMenu: true })],
+    },
+    {
+        name: 'projects',
+        summary: 'the projects a sandbox can open without a restart: list, choose, roots, all/exclude',
+        group: 'Sandbox',
+        json,
+        args: [
+            {
+                name: 'action',
+                description: 'list, choose, add, remove, include, exclude, all, roots',
+                required: false,
+                choices: ['list', 'choose', 'add', 'remove', 'include', 'exclude', 'all', 'roots'],
+            },
+            {
+                name: 'value',
+                description: 'a folder (add, remove, include, exclude), on/off (all), or list/add/remove (roots)',
+                required: false,
+                when: ['add', 'remove', 'include', 'exclude', 'all', 'roots'],
+            },
             { name: 'folder', description: '(roots add/remove) the folder', required: false, when: 'roots' },
         ],
         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 logins: 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', { when: 'save' }), bool('--no-restart', '(use) do not restart running sessions', { when: 'use' })], json },
-    { name: 'data', summary: 'show what is kept between sandboxes (tools, databases, logins, logs), or delete some of 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, when: 'clean' }], options: [bool('--yes', 'do not ask before deleting', { noMenu: true })], 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: 'account',
+        summary: 'Claude logins: 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", { when: 'save' }),
+            bool('--no-restart', '(use) do not restart running sessions', { when: 'use' }),
+        ],
+        json,
+    },
+    {
+        name: 'data',
+        summary: 'show what is kept between sandboxes (tools, databases, logins, logs), or delete some of 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,
+                when: 'clean',
+            },
+        ],
+        options: [bool('--yes', 'do not ask before deleting', { noMenu: true })],
+        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 conversation history back to this PC now', group: 'Data', args: [], options: [] },
     {
-        name: 'audit', summary: 'what happened in your sandboxes: programs started, files changed, sessions, repo guard (audit.enabled)', group: 'Health', json,
+        name: 'audit',
+        summary: 'what happened in your sandboxes: programs started, files changed, sessions, repo guard (audit.enabled)',
+        group: 'Health',
+        json,
+        args: [],
+        options: [
+            { flag: '--days', type: 'number', value: 'n', description: 'the last n days (default: today)', default: 1 },
+            text('--kind', 'kind', 'only proc, file, session or guard events', {
+                choices: ['proc', 'file', 'session', 'guard'],
+            }),
+            text('--grep', 'text', 'only events containing this text'),
+        ],
+    },
+    {
+        name: 'logs',
+        summary: 'print the newest sandbox log',
+        group: 'Health',
         args: [],
-        options: [{ flag: '--days', type: 'number', value: 'n', description: 'the last n days (default: today)', default: 1 }, text('--kind', 'kind', 'only proc, file, session or guard events', { choices: ['proc', 'file', 'session', 'guard'] }), text('--grep', 'text', 'only events containing this text')],
-    },
-    { 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: [{ name: 'suite', description: 'run only these test suites, e.g. config live-daemon (default: all)', required: false, variadic: true }], options: [] },
-    { name: 'config', summary: 'show or create your settings file, 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: 'agent-commands', summary: '(Beta) make claude, codex ... on this PC start in a hidden sandbox and attach', group: 'Agents', args: [{ name: 'action', description: 'on, off or status', required: false, choices: ['status', 'on', 'off'] }], options: [] },
-    { name: 'host-claude', summary: 'run Claude on this PC, NOT sandboxed, with its own 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 },
+        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: [
+            {
+                name: 'suite',
+                description: 'run only these test suites, e.g. config live-daemon (default: all)',
+                required: false,
+                variadic: true,
+            },
+        ],
+        options: [],
+    },
+    {
+        name: 'config',
+        summary: "show or create your settings file, 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: 'agent-commands',
+        summary: '(Beta) make claude, codex ... on this PC start in a hidden sandbox and attach',
+        group: 'Agents',
+        args: [{ name: 'action', description: 'on, off or status', required: false, choices: ['status', 'on', 'off'] }],
+        options: [],
+    },
+    {
+        name: 'host-claude',
+        summary: 'run Claude on this PC, NOT sandboxed, with its own 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);
+];
+export const COMMANDS = z.array(CommandSpecSchema).parse(COMMAND_LIST);
+export function commandSpec(name) {
+    return COMMANDS.find((c) => c.name === name);
+}

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

@@ -1,5 +1,5 @@
-import { App } from '../tui/index.js';
-import type { ConfigFile } from './settings/config-file.js';
+import { type App } from '../tui/index.js';
+import type { ConfigFile } from './settings/index.js';
 export declare class AppsCatalogue {
     private readonly app;
     private readonly file;
@@ -13,9 +13,11 @@ export declare class AppsCatalogue {
     /** Shows the catalogue until you save (Enter) or leave it (Esc); returns the notice to show afterwards. */
     run(): Promise<string | undefined>;
     private save;
-    /** Your own programs: the apps.custom map, each entry a form (GitHub release or link, program, command line or not). */
+    /**
+     * Your own programs: the apps.custom map, each entry a form (GitHub release or link, program, command line or not).
+     */
     private editCustom;
 }
 /** For the home screen: "12 apps chosen". */
-export declare const appsSummary: (file: ConfigFile) => string;
-export declare const appLabel: (id: string) => string;
+export declare function appsSummary(file: ConfigFile): string;
+export declare function appLabel(id: string): string;

package/dist/cli/menu/apps.js

@@ -5,9 +5,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import _ from 'lodash';
-import { APP_CATEGORIES, APPS } from '../../shared/apps.js';
+import { APP_CATEGORIES, APPS } from '../../shared/apps/index.js';
 import { Text, Theme } from '../tui/index.js';
-import { ValueEditor } from './settings/editors.js';
+// Direct, not the barrel: settings/settings-editor.ts imports this file.
+import { ValueEditor } from './settings/value-editor.js';
 const CUSTOM = '@custom';
 export class AppsCatalogue {
     app;
@@ -32,16 +33,32 @@ export class AppsCatalogue {
     }
     item(entry, install) {
         const notes = [
-            Theme.muted('Download  ') + '~' + entry.size + ' once, kept in C:\\AgentData\\tools\\' + (entry.setting ? '' : 'apps\\') + entry.id,
-            Theme.muted('Starts    ') + (entry.cli ? 'from a terminal (on PATH)' : 'from the desktop or Start > Sandbox apps'),
-            ...(entry.needs?.includes('mesa') ? [Theme.muted('Graphics  ') + 'OpenGL on the CPU (Mesa) is added for it'] : []),
+            Theme.muted('Download  ') +
+                '~' +
+                entry.size +
+                ' once, kept in C:\\AgentData\\tools\\' +
+                (entry.setting ? '' : 'apps\\') +
+                entry.id,
+            Theme.muted('Starts    ') +
+                (entry.cli ? 'from a terminal (on PATH)' : 'from the desktop or Start > Sandbox apps'),
+            ...(entry.needs?.includes('mesa')
+                ? [Theme.muted('Graphics  ') + 'OpenGL on the CPU (Mesa) is added for it']
+                : []),
             ...(entry.fullGitOnly ? [Theme.warn('Needs provisioning.git.access "full" (it pushes with its own git).')] : []),
             ...(entry.setting ? [Theme.muted('Setting   ') + entry.setting] : []),
         ];
         return {
-            value: entry.id, label: entry.name, category: entry.category, description: entry.about, details: notes, keywords: entry.id,
-            hint: (this.installed(entry) ? Theme.ok('installed ') : '') + Theme.muted(entry.size), checked: this.chosen(entry, install),
-            ...(this.file.isProject && entry.setting ? { disabled: 'A project cannot change this; it is in your own settings.' } : {}),
+            value: entry.id,
+            label: entry.name,
+            category: entry.category,
+            description: entry.about,
+            details: notes,
+            keywords: entry.id,
+            hint: (this.installed(entry) ? Theme.ok('installed ') : '') + Theme.muted(entry.size),
+            checked: this.chosen(entry, install),
+            ...(this.file.isProject && entry.setting
+                ? { disabled: 'A project cannot change this; it is in your own settings.' }
+                : {}),
         };
     }
     /** Shows the catalogue until you save (Enter) or leave it (Esc); returns the notice to show afterwards. */
@@ -54,10 +71,29 @@ export class AppsCatalogue {
                 path: [this.file.isProject ? 'Project settings' : 'Apps'],
                 intro: 'Tick the apps every sandbox should have (space), then Enter to save. Each is downloaded once and kept; c = your own programs.',
                 multi: true,
-                categories: [...APP_CATEGORIES, ...(this.file.isProject ? [] : [{ id: 'custom', label: 'Your own programs', description: 'Programs you added yourself (c to add or change them).' }])],
+                categories: [
+                    ...APP_CATEGORIES,
+                    ...(this.file.isProject
+                        ? []
+                        : [
+                            {
+                                id: 'custom',
+                                label: 'Your own programs',
+                                description: 'Programs you added yourself (c to add or change them).',
+                            },
+                        ]),
+                ],
                 items: [
                     ...entries.map((a) => this.item(a, install)),
-                    ...Object.entries(custom).map(([id, a]) => ({ value: CUSTOM + id, label: a.name, category: 'custom', description: a.github ? 'From the latest ' + a.github + ' release.' : 'From ' + a.url, hint: Theme.muted(a.cli ? 'command line' : 'desktop'), checked: true, disabled: 'Your own programs are always installed; c to change or remove them.' })),
+                    ...Object.entries(custom).map(([id, a]) => ({
+                        value: CUSTOM + id,
+                        label: a.name,
+                        category: 'custom',
+                        description: a.github ? 'From the latest ' + a.github + ' release.' : 'From ' + a.url,
+                        hint: Theme.muted(a.cli ? 'command line' : 'desktop'),
+                        checked: true,
+                        disabled: 'Your own programs are always installed; c to change or remove them.',
+                    })),
                 ],
                 actions: this.file.isProject ? [] : [{ key: 'c', label: 'your own programs' }],
             });
@@ -97,9 +133,17 @@ export class AppsCatalogue {
             return Theme.error(Theme.glyph.cross + ' Not saved: ' + problems.join('; '));
         if (!changed)
             return Theme.muted('Apps unchanged.');
-        return Theme.ok(Theme.glyph.ok + ' Saved: ' + (install.length ? install.length + ' app' + (install.length === 1 ? '' : 's') : 'no apps') + '.') + Theme.muted(this.file.isProject ? ' The next launch asks you to approve the project file again.' : ' The next sandbox installs what it does not have yet.');
+        return (Theme.ok(Theme.glyph.ok +
+            ' Saved: ' +
+            (install.length ? install.length + ' app' + (install.length === 1 ? '' : 's') : 'no apps') +
+            '.') +
+            Theme.muted(this.file.isProject
+                ? ' The next launch asks you to approve the project file again.'
+                : ' The next sandbox installs what it does not have yet.'));
     }
-    /** Your own programs: the apps.custom map, each entry a form (GitHub release or link, program, command line or not). */
+    /**
+     * Your own programs: the apps.custom map, each entry a form (GitHub release or link, program, command line or not).
+     */
     async editCustom() {
         const node = this.file.schema.child('apps')?.child('custom');
         if (!node)
@@ -110,13 +154,17 @@ export class AppsCatalogue {
         const result = this.file.set(['apps', 'custom'], edited.value);
         if (typeof result === 'object')
             return Theme.error(Theme.glyph.cross + ' Not saved: ' + result.problems.join('; '));
-        return result === 'saved' ? Theme.ok(Theme.glyph.ok + ' Saved your programs (' + Object.keys(edited.value).length + ').') : undefined;
+        return result === 'saved'
+            ? Theme.ok(Theme.glyph.ok + ' Saved your programs (' + Object.keys(edited.value).length + ').')
+            : undefined;
     }
 }
 /** For the home screen: "12 apps chosen". */
-export const appsSummary = (file) => {
+export function appsSummary(file) {
     const config = file.userConfig();
     const n = config.apps.install.length + Object.keys(config.apps.custom).length;
     return n ? n + ' chosen' : 'none chosen';
-};
-export const appLabel = (id) => APPS.find((a) => a.id === id)?.name ?? Text.humanize(id);
+}
+export function appLabel(id) {
+    return APPS.find((a) => a.id === id)?.name ?? Text.humanize(id);
+}

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

@@ -0,0 +1,15 @@
+import { type ArgSpec, type OptionSpec } from '../manifest.js';
+/** What an option accepts, checked while typing (undefined = fine). */
+export declare function optionProblem(o: OptionSpec, v: string): string | undefined;
+export type Field = {
+    kind: 'arg';
+    spec: ArgSpec;
+    index: number;
+} | {
+    kind: 'option';
+    spec: OptionSpec;
+} | {
+    kind: 'json';
+} | {
+    kind: 'extra';
+};

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

@@ -0,0 +1,23 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { splitArgs } from '../args.js';
+import { validNodeSpec, validPythonSpec } from '../validate.js';
+/** What an option accepts, checked while typing (undefined = fine). */
+export function 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;
+}