windows-development-sandbox 1.5.0 → 1.9.0

package/dist/cli/manifest.js

@@ -1,6 +1,10 @@
 // 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.
+// parser from it and menu.ts builds the interactive menu from it, so a command added here works both ways. Commands of
+// the shared core (status, sessions, stop ... and actions such as config get) come from their definitions' CLI hints
+// (cli/operations/spec.ts); this list shrinks as areas move into src/app.
 import { z } from 'zod';
+// The file rather than the barrel: the barrel's handlers need the registry, which needs the commands.
+import { withOperationCommands } from './operations/spec.js';
 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.');
@@ -26,6 +30,13 @@ export const OptionSpecSchema = z.strictObject({
     when: z.string().optional(),
     /** Never offered in the menu (dangerous shortcuts such as --yes); typing it on the command line still works. */
     noMenu: z.boolean().optional(),
+    /** Heading for this option in the command's --help (launch: Session, Folder ...). */
+    group: z.string().optional(),
+    /** The name shown in --help; `flag` stays accepted as a hidden alias (--agent shown, --harness still works). */
+    shownAs: z
+        .string()
+        .regex(/^--[a-z][a-z0-9-]*$/)
+        .optional(),
 });
 export const ArgSpecSchema = z.strictObject({
     name: z.string(),
@@ -33,6 +44,8 @@ export const ArgSpecSchema = z.strictObject({
     required: z.boolean(),
     variadic: z.boolean().optional(),
     choices: ChoicesSchema.optional(),
+    /** Spellings accepted besides `choices` but not listed (old names). */
+    aliases: z.array(z.string()).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(),
 });
@@ -40,7 +53,7 @@ export const ArgSpecSchema = 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 GroupSchema = z.enum(['Agents', 'Sessions', 'Projects & accounts', 'Data', 'Web', 'Health', 'Advanced']);
 export const CommandSpecSchema = z.strictObject({
     name: z.string(),
     summary: z.string(),
@@ -53,6 +66,8 @@ export const CommandSpecSchema = z.strictObject({
     /** Takes over the terminal or ends the session: the menu does not come back afterwards. */
     interactive: z.boolean().optional(),
     hidden: z.boolean().optional(),
+    /** Command lines shown in an Examples block at the end of the command's --help. */
+    examples: z.array(z.string()).optional(),
 });
 function bool(flag, description, extra = {}) {
     return {
@@ -91,16 +106,25 @@ const LABELS = {
 function labelled(options) {
     return options.map((o) => (LABELS[o.flag] ? { ...o, label: LABELS[o.flag] } : o));
 }
+const SESSION = 'Session';
+const FOLDER = 'Folder';
+const VERSIONS = 'Versions & services';
+const TRUST = 'Trust';
 const SANDBOX_OPTIONS = labelled([
-    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)', {
+    bool('--terminal', "attach this terminal (reuses this folder's session if nobody is watching it)", {
+        short: '-t',
+        group: SESSION,
+    }),
+    bool('--headless', 'hide the sandbox window (sandbox show brings it back)', { group: SESSION }),
+    bool('--new', 'always start a new session, even if this folder has an unattached one', { group: SESSION }),
+    text('--workspace', 'dir', 'use this folder instead of the current one', { group: FOLDER }),
+    text('--node', 'version', "Node version (default: your project's .nvmrc or this PC's version)", {
         advanced: true,
+        group: VERSIONS,
     }),
-    text('--python', 'version', 'Python 3 version (default: .sandbox-config.json > .python-version > config)', {
+    text('--python', 'version', "Python 3 version (default: your project's .python-version or your settings)", {
         advanced: true,
+        group: VERSIONS,
     }),
     {
         flag: '--database',
@@ -109,6 +133,7 @@ const SANDBOX_OPTIONS = labelled([
         description: 'also start this database (postgres, mysql, mongodb, redis, dynamodb; repeatable)',
         choices: ['postgres', 'mysql', 'mongodb', 'redis', 'dynamodb'],
         advanced: true,
+        group: VERSIONS,
     },
     {
         flag: '--script',
@@ -116,24 +141,26 @@ const SANDBOX_OPTIONS = labelled([
         value: 'file',
         description: 'run this .ps1/.mjs/.cmd inside the sandbox first (repeatable)',
         advanced: true,
+        group: VERSIONS,
     },
-    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('--yes', 'when this folder is not in the running sandbox, or wants what it started without (vGPU, folders), restart without asking', { noMenu: true }),
+    bool('--window', 'show the sandbox window even if your settings say headless', { advanced: true, group: SESSION }),
+    bool('--trust-config', "approve the folder's .sandbox-config.json without asking", { advanced: true, group: TRUST }),
+    bool('--no-local-config', "ignore the folder's .sandbox-config.json", { advanced: true, group: TRUST }),
+    bool('--yes', 'restart the sandbox without asking if this folder needs it', { noMenu: true, group: TRUST }),
 ]);
 const AGENT_OPTIONS = labelled([
-    text('--harness', 'name', 'agent to run', { choices: 'harnesses' }),
+    text('--harness', 'name', 'agent to run', { choices: 'harnesses', shownAs: '--agent', group: SESSION }),
     {
         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)',
+        description: 'start several sessions at once (repeatable; see the examples below; -t attaches the first)',
         noMenu: true,
+        group: SESSION,
     },
-    text('--account', 'name', 'Claude account for this sandbox', { choices: 'accounts' }),
+    text('--account', 'name', 'Claude account for this sandbox', { choices: 'accounts', group: SESSION }),
     ...SANDBOX_OPTIONS,
-    bool('--no-agent', 'set up the sandbox but do not start an agent', { advanced: true }),
+    bool('--no-agent', 'set up the sandbox but do not start an agent', { advanced: true, group: SESSION }),
 ]);
 const json = true;
 const COMMAND_LIST = [
@@ -145,11 +172,17 @@ const COMMAND_LIST = [
         options: AGENT_OPTIONS,
         passthrough: 'agent',
         interactive: true,
+        examples: [
+            'sandbox claude -t                  start Claude here and attach this terminal',
+            'sandbox launch --agent codex       start Codex in the current folder',
+            'sandbox launch --session claude@C:\\code\\api --session "codex@C:\\code\\web|--model o3"',
+            "                                   two sessions at once (after | = that agent's own arguments)",
+        ],
     },
     {
         name: 'start',
         summary: 'start a sandbox with no agent (tools and databases only)',
-        group: 'Sandbox',
+        group: 'Agents',
         args: [],
         options: SANDBOX_OPTIONS.filter((o) => o.flag !== '--new'),
         interactive: true,
@@ -157,7 +190,7 @@ const COMMAND_LIST = [
     {
         name: 'generate',
         summary: 'show what a start would do, without starting anything',
-        group: 'Health',
+        group: 'Advanced',
         args: [],
         options: AGENT_OPTIONS,
         passthrough: 'agent',
@@ -173,25 +206,16 @@ const COMMAND_LIST = [
     {
         name: 'resume',
         summary: 'reopen the sessions from the last sandbox',
-        group: 'Sessions',
+        group: 'Agents',
         args: [],
         options: [
             bool('--auto', 'used by the background sync after a crash: no questions', { noMenu: true, advanced: 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',
+        group: 'Sessions',
         args: [
             { name: 'action', description: 'list, start or stop', required: false, choices: ['list', 'start', 'stop'] },
             {
@@ -206,7 +230,11 @@ const COMMAND_LIST = [
     {
         name: 'exec',
         summary: 'run a command inside the sandbox and print its output',
-        group: 'Sandbox',
+        group: 'Sessions',
+        examples: [
+            'sandbox exec -- npm test            run a command in the running sandbox',
+            'sandbox exec --json -- node -v      the result as JSON',
+        ],
         args: [{ name: 'command', description: 'command and its arguments', required: true, variadic: true }],
         options: [
             {
@@ -221,28 +249,16 @@ const COMMAND_LIST = [
         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',
+        group: 'Projects & accounts',
         json,
+        examples: [
+            'sandbox projects                   list your projects',
+            'sandbox projects add .             remember this folder',
+            'sandbox projects roots add C:\\code   share every project in C:\\code',
+        ],
         args: [
             {
                 name: 'action',
@@ -258,14 +274,16 @@ const COMMAND_LIST = [
             },
             { name: 'folder', description: '(roots add/remove) the folder', required: false, when: 'roots' },
         ],
-        options: [],
+        options: [bool('--yes', 'do not ask before removing', { short: '-y', when: 'remove', noMenu: true })],
     },
-    { 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',
+        group: 'Projects & accounts',
+        examples: [
+            'sandbox account save work          save the login you signed in with inside the sandbox',
+            'sandbox account use work           the sandbox uses it (running sessions restart)',
+        ],
         args: [
             {
                 name: 'action',
@@ -283,6 +301,7 @@ const COMMAND_LIST = [
             }),
             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' }),
+            bool('--yes', '(remove) do not ask first', { short: '-y', when: 'remove', noMenu: true }),
         ],
         json,
     },
@@ -291,7 +310,13 @@ const COMMAND_LIST = [
         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: 'action',
+                description: 'show or clean',
+                required: false,
+                choices: ['show', 'clean'],
+                aliases: ['info', 'list', 'remove'],
+            },
             {
                 name: 'targets',
                 description: 'what to clean, e.g. tools/go databases logs',
@@ -300,7 +325,62 @@ const COMMAND_LIST = [
                 when: 'clean',
             },
         ],
-        options: [bool('--yes', 'do not ask before deleting', { noMenu: true })],
+        options: [bool('--yes', 'do not ask before deleting', { short: '-y', noMenu: true })],
+        json,
+        examples: [
+            'sandbox data clean                 pick what to delete from a list',
+            'sandbox data clean logs tools/go   delete these',
+        ],
+    },
+    {
+        name: 'storage',
+        summary: 'where your saved data lives: show it, move it to another folder, switch folders, or (beta) keep it in a disk image',
+        group: 'Data',
+        examples: [
+            'sandbox storage                    where the data is',
+            'sandbox storage move D:\\sandbox-data   move it (asks first)',
+            'sandbox storage contained status   (beta) the disk image for tools, state and logs',
+            'sandbox storage contained on       (beta) keep them in a disk image (asks first)',
+        ],
+        args: [
+            {
+                name: 'action',
+                description: 'show, move, use or contained',
+                required: false,
+                choices: ['show', 'move', 'use', 'contained'],
+            },
+            {
+                name: 'folder',
+                description: 'the folder to move to, or to use; for contained: on, off or status',
+                required: false,
+                when: ['move', 'use', 'contained'],
+            },
+        ],
+        options: [
+            bool('--yes', 'do not ask before moving or switching', { short: '-y', noMenu: true }),
+            bool('--keep-old', 'copy instead of moving: the old folder stays (needs room for both)', { when: 'move' }),
+        ],
+        json,
+    },
+    {
+        name: 'engine',
+        summary: '(beta) what runs your sandbox (Windows Sandbox or HCS) and what each engine can do on this PC',
+        group: 'Health',
+        examples: [
+            'sandbox engine                  the engine in use and what each can do',
+            'sandbox engine check hcs        what this PC lacks for the HCS engine, and the commands that would fix it',
+        ],
+        args: [
+            { name: 'action', description: 'show or check', required: false, choices: ['show', 'check'] },
+            {
+                name: 'engine',
+                description: 'the engine to check',
+                required: false,
+                choices: ['windows-sandbox', 'hcs'],
+                when: 'check',
+            },
+        ],
+        options: [],
         json,
     },
     {
@@ -316,12 +396,13 @@ const COMMAND_LIST = [
                 description: 'launch folders older than this many days',
                 default: 7,
             },
+            bool('--yes', 'do not ask before deleting', { short: '-y', noMenu: true }),
         ],
     },
     { 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)',
+        summary: 'what happened in your sandboxes: programs started, files changed, sessions, repo guard (turn it on: sandbox config set audit.enabled true)',
         group: 'Health',
         json,
         args: [],
@@ -338,7 +419,10 @@ const COMMAND_LIST = [
         summary: 'print the newest sandbox log',
         group: 'Health',
         args: [],
-        options: [bool('--follow', 'keep printing new lines', { short: '-f' })],
+        options: [
+            bool('--follow', 'keep printing new lines', { short: '-f' }),
+            bool('--crash', 'print the report of the last crash (what Windows logged, this PC and the sandbox memory)'),
+        ],
     },
     {
         name: 'setup',
@@ -349,10 +433,14 @@ const COMMAND_LIST = [
     },
     {
         name: 'doctor',
-        summary: 'check this PC and show what will be copied or downloaded',
+        summary: 'check this PC, the install, your settings and the sandbox, and offer to fix what it finds',
         group: 'Health',
         args: [],
-        options: [text('--harness', 'name', 'agent to check', { choices: 'harnesses' })],
+        options: [
+            text('--harness', 'name', 'agent to check', { choices: 'harnesses', shownAs: '--agent' }),
+            bool('--fix', 'fix what can be fixed without asking', { noMenu: true }),
+        ],
+        json: true,
     },
     {
         name: 'migrate',
@@ -364,6 +452,7 @@ const COMMAND_LIST = [
             text('--restore', 'backup', 'put back the files saved before an update (a folder under <storage>\\backups)', {
                 advanced: true,
             }),
+            bool('--yes', '(--restore) do not ask first', { short: '-y', noMenu: true }),
         ],
     },
     {
@@ -374,6 +463,7 @@ const COMMAND_LIST = [
         options: [
             bool('--check', 'only look whether a newer version exists'),
             bool('--rollback', 'go back to the version before the last update'),
+            bool('--yes', '(--rollback) do not ask first', { short: '-y', noMenu: true }),
             text('--auto', 'on|off', 'install new versions by themselves (for everyone on this PC: needs an admin terminal)', {
                 choices: ['on', 'off'],
             }),
@@ -386,15 +476,17 @@ const COMMAND_LIST = [
     },
     {
         name: 'repair',
-        summary: 'find and fix common problems (stale state, broken downloads, half-installed tools)',
+        summary: 'find and fix problems (install, data folder, settings, stale state, half-installed tools)',
         group: 'Health',
         args: [],
-        options: [],
+        options: [bool('--yes', 'do not ask before fixing', { short: '-y', noMenu: true })],
+        json: true,
     },
     {
         name: 'self-test',
         summary: 'run the built-in tests',
         group: 'Health',
+        hidden: true,
         args: [
             {
                 name: 'suite',
@@ -408,32 +500,69 @@ const COMMAND_LIST = [
     {
         name: 'config',
         summary: "show or create your settings file, or check a project's .sandbox-config.json",
-        group: 'Config',
+        group: 'Health',
         args: [
             {
                 name: 'action',
                 description: 'what to do',
                 required: false,
-                choices: ['show', 'path', 'init', 'schema', 'check'],
+                choices: ['show', 'path', 'init', 'schema', 'check', 'get', 'set', 'export', 'import'],
+                aliases: ['summary'],
+            },
+            {
+                name: 'key',
+                description: '(get, set, reset) the setting, e.g. sandbox.memoryMb; (export, import) the .json file',
+                required: false,
+                when: ['get', 'set', 'export', 'import'],
             },
+            { name: 'value', description: '(set) the new value', required: false, when: 'set' },
+        ],
+        options: [
+            text('--workspace', 'dir', '(check) the project folder; default: the current one'),
+            bool('--with-paths', '(export) keep folders and files of this PC in the file', { when: 'export' }),
+            bool('--yes', '(import) do not ask before changing your settings', { short: '-y', when: 'import', noMenu: true }),
+        ],
+        examples: [
+            'sandbox config set sandbox.memoryMb 8192',
+            'sandbox config get sandbox.memoryMb',
+            'sandbox config reset sandbox.memoryMb',
+            'sandbox config list',
+            'sandbox config export team-settings.json',
+            'sandbox config import team-settings.json',
         ],
-        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',
+        group: 'Advanced',
         args: [{ name: 'action', description: 'on, off or status', required: false, choices: ['status', 'on', 'off'] }],
         options: [],
     },
+    {
+        name: 'vpn',
+        summary: 'the VPN for the sandbox: save your login, see whether it is on (NordVPN first)',
+        group: 'Advanced',
+        args: [
+            {
+                name: 'action',
+                description: 'status, login or logout',
+                required: false,
+                choices: ['status', 'login', 'logout'],
+            },
+        ],
+        options: [],
+        json: true,
+        examples: ['sandbox vpn login', 'sandbox vpn status'],
+    },
     {
         name: 'host-claude',
-        summary: 'run Claude on this PC, NOT sandboxed, with its own profile',
+        summary: 'run Claude on this PC, NOT sandboxed, with its own profile (same as: sandbox host claude)',
         group: 'Agents',
         args: [],
         options: [bool('--personal', 'use your normal Claude profile')],
         passthrough: 'agent',
         interactive: true,
+        hidden: true,
     },
     {
         name: 'host',
@@ -447,15 +576,41 @@ const COMMAND_LIST = [
     {
         name: 'menu',
         summary: 'the interactive menu (what `sandbox` opens with no arguments)',
-        group: 'Config',
+        group: 'Advanced',
         args: [],
         options: [],
         hidden: true,
         interactive: true,
     },
+    {
+        name: 'web',
+        summary: '(beta) your sandbox sessions in a browser on this PC: start, stop, status or open',
+        group: 'Web',
+        examples: ['sandbox web open               start the web UI and open it in your browser'],
+        args: [
+            {
+                name: 'action',
+                description: 'start the server, stop it, show whether it runs, or open it in your browser',
+                required: false,
+                choices: ['start', 'stop', 'status', 'open'],
+            },
+        ],
+        options: [],
+        json,
+    },
     { name: '_watch', summary: 'background history sync', group: 'Data', args: [], options: [], hidden: true },
+    {
+        name: '_web',
+        summary: 'the web UI server (started by sandbox web start)',
+        group: 'Web',
+        args: [],
+        options: [],
+        hidden: true,
+    },
 ];
-export const COMMANDS = z.array(CommandSpecSchema).parse(COMMAND_LIST);
+export const COMMANDS = z
+    .array(CommandSpecSchema)
+    .parse(withOperationCommands(z.array(CommandSpecSchema).parse(COMMAND_LIST)));
 export function commandSpec(name) {
     return COMMANDS.find((c) => c.name === name);
 }

package/dist/cli/menu/add-agent.d.ts

@@ -0,0 +1,47 @@
+import type { Harness } from '../../core/types.js';
+import type { App } from '../tui/index.js';
+import type { ConfigFile } from '../../app/features/settings/index.js';
+import type { Draft } from './settings/draft.js';
+/** How a new agent gets into the sandbox. */
+export type AgentSource = 'npm' | 'uv' | 'host';
+/** Nothing wrong with the name (true), or what is wrong. Pure. */
+export declare function agentNameProblem(name: string, taken: readonly string[]): true | string;
+/** The command a package usually provides: "@scope/my-agent@latest" gives "my-agent". Pure. */
+export declare function commandFromPackage(pkg: string): string;
+/** The config entry for a new agent. Pure. */
+export declare function newAgent(source: AgentSource, what: string, command: string, hostDir?: string): Harness;
+/** What `harnesses` should say with `name` taken out. Pure. */
+export declare function withoutAgent(current: unknown, name: string): Record<string, unknown>;
+/** Writes a setting to your config file now, or adds it to the unsaved changes when it has some already. */
+export declare function writeOrStage(file: ConfigFile, draft: Draft, key: string[], value: unknown): {
+    saved: boolean;
+};
+/** What `harnesses` should say with `name` added to what is staged or in the file now. Pure. */
+export declare function withAgent(current: unknown, name: string, harness: Harness): Record<string, unknown>;
+/** Makes `name` the agent that starts by default (written now, or joined to unsaved changes to that setting). */
+export declare function makeDefaultAgent(file: ConfigFile, draft: Draft, name: string): {
+    saved: boolean;
+};
+/** Takes an agent you added out of your settings (the built-in ones are not removable). */
+export declare function removeAgent(file: ConfigFile, draft: Draft, name: string): {
+    saved: boolean;
+};
+export interface AddedAgent {
+    readonly name: string;
+    /** Written to your config file now (false: waiting for Ctrl+S with the other unsaved changes). */
+    readonly saved: boolean;
+}
+export declare class AddAgent {
+    private readonly app;
+    private readonly file;
+    private readonly draft;
+    /** Every agent that exists now (the new name must be different). */
+    private readonly taken;
+    constructor(app: App, file: ConfigFile, draft: Draft, 
+    /** Every agent that exists now (the new name must be different). */
+    taken: readonly string[]);
+    /** Asks, then adds the agent. Undefined when you backed out. */
+    run(): Promise<AddedAgent | undefined>;
+    /** Validates and writes (or stages) the entry. */
+    private add;
+}