windows-development-sandbox 1.5.0 → 1.9.0

package/dist/app/registry.js

@@ -0,0 +1,50 @@
+import { invoke, NO_QUESTIONS, onSurface, } from './kernel/index.js';
+import { hideWindowRun, sandboxStatusRun, showWindowRun, stopSandboxRun } from './features/sandbox/index.js';
+import { listSessionsRun, restartSessionsRun } from './features/sessions/index.js';
+import { getSettingRun, listSettingsRun, resetSettingRun, setSettingRun } from './features/settings/index.js';
+export const IMPLEMENTATIONS = [
+    sandboxStatusRun,
+    showWindowRun,
+    hideWindowRun,
+    stopSandboxRun,
+    listSessionsRun,
+    restartSessionsRun,
+    listSettingsRun,
+    getSettingRun,
+    setSettingRun,
+    resetSettingRun,
+];
+export function implementationOf(id) {
+    return IMPLEMENTATIONS.find((i) => i.def.id === id);
+}
+/** Runs a definition by id: input checked before, output checked after. */
+export function runDefinition(id, ctx, input, io) {
+    const impl = implementationOf(id);
+    if (!impl)
+        throw new Error('No implementation for ' + id);
+    return invoke(impl, ctx, input, io);
+}
+/** Reads a query in-process (the menu): typed output, and no questions. */
+export async function readQuery(def, ctx, input = {}) {
+    return (await runDefinition(def.id, ctx, input, NO_QUESTIONS));
+}
+/** What the web server may run: the registered definitions whose surfaces include the web. */
+export function createRpcHost(ctx) {
+    const allowed = (id) => {
+        const impl = implementationOf(id);
+        return impl && onSurface(impl.def, 'web') ? impl : undefined;
+    };
+    return {
+        kind: (id) => allowed(id)?.def.kind,
+        liveMs: (id) => {
+            const def = allowed(id)?.def;
+            return def?.kind === 'query' ? def.live?.everyMs : undefined;
+        },
+        run: (id, input, io) => {
+            const impl = allowed(id);
+            if (!impl)
+                throw new Error('Not allowed on the web: ' + id);
+            return invoke(impl, ctx, input, io);
+        },
+    };
+}

package/dist/cli/args.d.ts

@@ -3,6 +3,8 @@ export interface CliOptions {
     command: string;
     positionals: string[];
     passthrough: string[];
+    /** The options as commander parsed them, by attribute name (operation commands build their input from these). */
+    raw: Readonly<Record<string, unknown>>;
     config?: string;
     workspace?: string;
     harness?: string;
@@ -25,8 +27,15 @@ export interface CliOptions {
     accountTo?: string;
     noRestart: boolean;
     follow: boolean;
+    crash: boolean;
     json: boolean;
     yes: boolean;
+    /** sessions --wide: also the folder column. */
+    wide: boolean;
+    /** storage move: keep the old folder (copy instead of rename). */
+    keepOld: boolean;
+    /** config export: keep folders and files of this PC in the file. */
+    withPaths: boolean;
     timeout: number;
     days: number;
     /** restart: every session, not only this folder's project's. */
@@ -38,6 +47,8 @@ export interface CliOptions {
     grep?: string;
     /** migrate --dry-run, and --restore <backup folder>. */
     dryRun: boolean;
+    /** doctor --fix: repair what it finds without asking. */
+    fix: boolean;
     restore?: string;
     /** resume --auto: called by the background watcher after a crash. */
     auto: boolean;
@@ -62,7 +73,12 @@ export declare function splitArgs(text: string): string[];
  * `cwd`. Pure; validate.ts checks that the agent and folder exist.
  */
 export declare function parseSessionWant(input: string, cwd?: string): SessionWant;
-/** Every command, its options and help text, from manifest.ts. Actions only record what was parsed. */
-export declare function buildProgram(record: (name: string, cmd: Command) => void): Command;
+/** "Unknown command" with the suggestion in our words; other commander errors only lose the lower-case start. */
+export declare function friendlyError(text: string): string;
+/**
+ * Every command, its options and help text, from manifest.ts. Actions only record what was parsed. `wrapper` = the
+ * sandbox <agent> spelling: --agent stays the agent's own flag there (Claude has one), only --harness is ours.
+ */
+export declare function buildProgram(record: (name: string, cmd: Command) => void, wrapper?: boolean): Command;
 /** Parses argv into the command name and options. Throws commander errors for unknown commands/options. */
 export declare function parseCli(argv: string[], wrapper?: boolean): CliOptions;

package/dist/cli/args.js

@@ -2,9 +2,10 @@
 // dispatches the result. sandbox claude & co parse as `launch`: every option launch does not own goes to the agent, in
 // order.
 import path from 'node:path';
-import { Command, InvalidArgumentError, Option } from 'commander';
+import { Argument, Command, InvalidArgumentError, Option } from 'commander';
 import { fail } from '../core/util/index.js';
 import { c } from './output/index.js';
+import { insideSandbox } from '../host/sandbox/index.js';
 import { COMMANDS } from './manifest.js';
 import { packageVersion } from '../core/package-info.js';
 /** Splits a command line like a shell: "quoted words" and 'quoted words' stay together. */
@@ -38,45 +39,109 @@ function positiveNumber(value) {
 function collect(value, previous = []) {
     return [...previous, value];
 }
-/** One commander option from its manifest entry. */
-function toOption(o) {
-    const flags = (o.short ? o.short + ', ' : '') + o.flag + (o.type === 'boolean' ? '' : ' <' + (o.value ?? 'value') + '>');
-    const option = new Option(flags, o.description);
-    if (o.type === 'number')
-        option.argParser(positiveNumber);
-    if (o.type === 'list')
-        option.argParser(collect);
-    if (o.default !== undefined)
-        option.default(o.default);
-    return option;
+/** Commands in --help, group by group, in this order (a command not listed comes last in its group). */
+const HELP_ORDER = [
+    ['Agents', ['launch', 'start', 'resume', 'restart', 'stop', 'host']],
+    ['Sessions', ['sessions', 'attach', 'status', 'exec', 'show', 'hide', 'db']],
+    ['Projects & accounts', ['projects', 'account']],
+    ['Data', ['data', 'storage', 'clean', 'sync']],
+    ['Web', ['web']],
+    ['Health', ['setup', 'doctor', 'repair', 'logs', 'audit', 'update', 'migrate', 'config']],
+    ['Advanced', ['generate', 'agent-commands', 'vpn']],
+];
+/** The commands in the order --help lists them. */
+function helpOrdered() {
+    const flat = HELP_ORDER.flatMap(([, names]) => names);
+    const rank = (name) => {
+        const i = flat.indexOf(name);
+        return i < 0 ? flat.length : i;
+    };
+    return [...COMMANDS].sort((x, y) => rank(x.name) - rank(y.name));
+}
+/** The options of one manifest entry: the visible one, and a hidden old spelling when `shownAs` renames it. */
+function toOptions(o, wrapper) {
+    const shown = o.shownAs && !wrapper ? o.shownAs : o.flag;
+    const placeholder = o.type === 'boolean' ? '' : ' <' + (o.value ?? 'value') + '>';
+    const make = (flag) => {
+        const option = new Option((o.short ? o.short + ', ' : '') + flag + placeholder, o.description);
+        if (o.type === 'number')
+            option.argParser(positiveNumber);
+        if (o.type === 'list')
+            option.argParser(collect);
+        if (o.default !== undefined)
+            option.default(o.default);
+        if (o.group)
+            option.helpGroup(o.group + ':');
+        return option;
+    };
+    const visible = make(shown);
+    return shown === o.flag ? [visible] : [visible, make(o.flag).hideHelp()];
 }
-/** Every command, its options and help text, from manifest.ts. Actions only record what was parsed. */
-export function buildProgram(record) {
+/** A positional argument; fixed choices are checked by the parser and listed in --help. */
+function toArgument(arg) {
+    const name = (arg.required ? '<' : '[') + arg.name + (arg.variadic ? '...' : '') + (arg.required ? '>' : ']');
+    const argument = new Argument(name, arg.description);
+    if (Array.isArray(arg.choices)) {
+        argument.choices(arg.choices);
+        const aliases = arg.aliases ?? [];
+        const check = argument.parseArg;
+        if (aliases.length && check)
+            argument.argParser((value, previous) => aliases.includes(value) ? value : check(value, previous));
+    }
+    return argument;
+}
+/** "Unknown command" with the suggestion in our words; other commander errors only lose the lower-case start. */
+export function friendlyError(text) {
+    const m = /^error: unknown command '(.*)'\n\(Did you mean (.*)\?\)\n?$/.exec(text);
+    if (m) {
+        const names = m[2].replace(/^one of /, '').split(', ');
+        return 'Unknown command "' + m[1] + '". Did you mean: ' + names.map((n) => 'sandbox ' + n).join(' or ') + '?\n';
+    }
+    return text.replace(/^error: /, '').replace(/^./, (ch) => ch.toUpperCase());
+}
+function rootHelp() {
+    const lines = [
+        '',
+        'Start an agent by name: sandbox claude, sandbox codex ... (the same as sandbox launch --agent <name>).',
+        'Put --config <file> before or after the command to use another settings file.',
+    ];
+    if (insideSandbox())
+        lines.push('You are inside a sandbox: launch, resume, attach, restart, stop, exec, show, hide, storage and web control it from your PC and do not work here.');
+    lines.push('', 'Examples:', '  sandbox                       the menu', '  sandbox claude -t             start Claude and attach this terminal', '  sandbox data clean logs       delete the saved logs', '  sandbox exec -- npm test      run a command in the running sandbox');
+    return lines.join('\n');
+}
+/**
+ * Every command, its options and help text, from manifest.ts. Actions only record what was parsed. `wrapper` = the
+ * sandbox <agent> spelling: --agent stays the agent's own flag there (Claude has one), only --harness is ours.
+ */
+export function buildProgram(record, wrapper = false) {
     const program = new Command('sandbox')
         .description('A disposable Windows Sandbox for development, with or without an AI agent, for the folder you are in. Run it with no arguments for the menu.')
         .version(packageVersion(), '-v, --version', 'show the version')
         .enablePositionalOptions()
         .showHelpAfterError('  Fix:  run the command with --help to see how to use it.')
-        .configureOutput({
-        outputError: (text, write) => write(c.red('Error: ') + text.replace(/^error: /, '').replace(/^./, (ch) => ch.toUpperCase())),
-    })
-        .addHelpText('after', '\nPut --config <file> before or after the command to use another settings file.\nExamples:\n  sandbox                       the menu\n  sandbox claude -t             start Claude and attach this terminal\n  sandbox data clean logs       delete the saved logs\n  sandbox exec -- npm test      run a command in the running sandbox')
+        .configureOutput({ outputError: (text, write) => write(c.red('Error: ') + friendlyError(text)) })
+        .addHelpText('after', rootHelp)
         .exitOverride();
-    for (const spec of COMMANDS) {
+    for (const spec of helpOrdered()) {
         const cmd = program
             .command(spec.name, { hidden: spec.hidden })
             .description(spec.summary)
-            .option('--config <file>', 'config file (default: ~/.agent-sandbox/config.json)');
+            .helpGroup(spec.group + ':')
+            .addOption(new Option('--config <file>', 'config file (default: ~/.agent-sandbox/config.json)').hideHelp());
         for (const option of spec.options)
-            cmd.addOption(toOption(option));
+            for (const o of toOptions(option, wrapper))
+                cmd.addOption(o);
         if (spec.json)
             cmd.option('--json', 'machine-readable output');
         for (const arg of spec.args)
-            cmd.argument((arg.required ? '<' : '[') + arg.name + (arg.variadic ? '...' : '') + (arg.required ? '>' : ']'), arg.description);
+            cmd.addArgument(toArgument(arg));
         if (spec.passthrough === 'agent')
             cmd.argument('[agentArgs...]', 'passed to the agent').allowUnknownOption().allowExcessArguments();
         if (spec.passthrough === 'command')
             cmd.passThroughOptions();
+        if (spec.examples?.length)
+            cmd.addHelpText('after', '\nExamples:\n' + spec.examples.map((l) => '  ' + l).join('\n'));
         cmd.action((...args) => record(spec.name, args[args.length - 1]));
     }
     return program;
@@ -99,7 +164,7 @@ export function parseCli(argv, wrapper = false) {
     let parsed = null;
     const program = buildProgram((name, cmd) => {
         parsed = { name, cmd };
-    });
+    }, wrapper);
     const launchFlags = new Set(program.commands
         .find((c) => c.name() === 'launch')
         .options.map((o) => o.long)
@@ -121,9 +186,10 @@ export function parseCli(argv, wrapper = false) {
         command: name === 'start' ? 'launch' : name,
         positionals: forAgent || name === 'exec' ? [] : operands,
         passthrough: forAgent || name === 'exec' ? operands : [],
+        raw: o,
         config: o.config,
         workspace: o.workspace,
-        harness: o.harness,
+        harness: o.harness ?? (name !== 'account' && typeof o.agent === 'string' ? o.agent : undefined),
         account: o.account,
         node: o.node,
         python: o.python,
@@ -144,8 +210,12 @@ export function parseCli(argv, wrapper = false) {
         accountTo: name === 'account' && typeof o.to === 'string' ? o.to : undefined,
         noRestart: o.restart === false,
         follow: Boolean(o.follow),
+        crash: Boolean(o.crash),
         json: Boolean(o.json),
         yes: Boolean(o.yes),
+        wide: Boolean(o.wide),
+        keepOld: Boolean(o.keepOld),
+        withPaths: Boolean(o.withPaths),
         all: Boolean(o.all),
         sessions: (o.session ?? []).map((s) => parseSessionWant(s)),
         timeout: o.timeout ?? 600,
@@ -153,6 +223,7 @@ export function parseCli(argv, wrapper = false) {
         kind: o.kind,
         grep: o.grep,
         dryRun: Boolean(o.dryRun),
+        fix: Boolean(o.fix),
         auto: o.auto === true,
         restore: o.restore,
         check: Boolean(o.check),
@@ -175,6 +246,7 @@ function defaults() {
         command: '',
         positionals: [],
         passthrough: [],
+        raw: {},
         scripts: [],
         databases: [],
         terminal: false,
@@ -186,13 +258,18 @@ function defaults() {
         fromHost: false,
         noRestart: false,
         follow: false,
+        crash: false,
         dryRun: false,
+        fix: false,
         auto: false,
         check: false,
         rollback: false,
         unattended: false,
         json: false,
         yes: false,
+        wide: false,
+        keepOld: false,
+        withPaths: false,
         all: false,
         sessions: [],
         timeout: 600,

package/dist/cli/commands/accounts.js

@@ -1,6 +1,7 @@
 // `account list | save | use | default | rename | remove [--agent <name>]`
+import { askChoice, askName, askRequired } from '../../core/prompt.js';
 import { fail, safeText } from '../../core/util/index.js';
-import { printJson, table } from '../output/index.js';
+import { nextStep, printJson, table } from '../output/index.js';
 import { AccountsService } from '../services/index.js';
 function label(a) {
     return '"' + a.name + '"' + (a.email ? ' (' + a.email + ')' : '');
@@ -31,38 +32,65 @@ function list(ctx, accounts, agent) {
     return 0;
 }
 async function use(ctx, accounts, name, agent) {
-    console.log('Sandbox now uses ' + label(accounts.activate(name, agent)) + '.');
+    const used = accounts.activate(name, agent);
+    console.log('Sandbox now uses ' + label(used) + '.');
+    if (used.note)
+        console.log(safeText(used.note));
     if (accounts.hasRunningSessions(agent) && !ctx.options.noRestart)
         console.log(safeText(await accounts.restart(agent)) + ' with --continue; the conversation carries on under the new account.');
     return 0;
 }
+/** The account the command is about: the one typed, or one picked from the saved accounts. */
+async function accountName(accounts, action, agent, given) {
+    if (given)
+        return given;
+    const usage = 'Usage: sandbox account ' + action + ' <name>';
+    if (action === 'save')
+        return askName('Name for this login:', usage, (v) => v.length > 0 || 'Type a name.');
+    const rows = accounts.list(agent);
+    if (!rows.length)
+        fail('No saved accounts.', 'Sign in inside the sandbox, then run: sandbox account save <name>');
+    return askChoice('Which account?', rows.map((a) => ({ name: safeText(label(a)), value: a.name })), usage);
+}
+async function remove(ctx, accounts, name, agent) {
+    const sure = ctx.options.yes ||
+        (await askRequired('Remove the saved account "' + name + '"? Its login cannot be recovered; you would sign in again.', 'Add --yes to remove it without asking.'));
+    if (!sure) {
+        console.log('Nothing removed.');
+        return 1;
+    }
+    accounts.remove(name, agent);
+    console.log('Removed account ' + name + '.');
+    return 0;
+}
 export async function account(ctx) {
-    const [action = 'list', name] = ctx.options.positionals;
-    const newName = ctx.options.accountTo;
+    const [action = 'list', given] = ctx.options.positionals;
     const agent = ctx.options.accountAgent ?? 'claude';
     const accounts = new AccountsService(ctx);
-    const needName = () => name ?? fail('Missing account name.', 'Usage: sandbox account ' + action + ' <name>');
+    if (action === 'list')
+        return list(ctx, accounts, agent);
+    const name = await accountName(accounts, action, agent, given);
     switch (action) {
-        case 'list':
-            return list(ctx, accounts, agent);
         case 'save':
-            console.log('Saved account ' + label(accounts.save(needName(), Boolean(ctx.options.fromHost), agent)) + '.');
+            console.log('Saved account ' + label(accounts.save(name, Boolean(ctx.options.fromHost), agent)) + '.');
+            nextStep('sandbox account use ' + name + '   (the sandbox uses it)');
             return 0;
         case 'use':
-            return use(ctx, accounts, needName(), agent);
+            return use(ctx, accounts, name, agent);
         case 'default':
-            accounts.setDefault(needName(), agent);
+            accounts.setDefault(name, agent);
             console.log('Default account: ' + name);
             return 0;
-        case 'rename':
-            accounts.rename(needName(), newName ?? fail('Missing the new name.', 'Usage: sandbox account rename <name> --to <new-name>'), agent);
-            console.log('Renamed account ' + name + ' to ' + newName);
+        case 'rename': {
+            const to = ctx.options.accountTo ??
+                (await askName('New name for "' + name + '":', 'Usage: sandbox account rename <name> --to <new-name>', (v) => v.length > 0 || 'Type a name.'));
+            accounts.rename(name, to, agent);
+            console.log('Renamed account ' + name + ' to ' + to + '.');
             return 0;
+        }
         case 'remove':
-            accounts.remove(needName(), agent);
-            console.log('Removed account ' + name);
-            return 0;
+            return remove(ctx, accounts, name, agent);
         default:
-            fail('Unknown account action "' + action + '".', 'Use one of: sandbox account list | save <name> | use <name> | default <name> | rename <name> --to <new-name> | remove <name>');
+            return fail('Unknown account action "' + action + '".', 'Use one of: sandbox account list | save <name> | use <name> | default <name> | rename <name> --to <new-name> | remove <name>');
     }
 }

package/dist/cli/commands/context.d.ts

@@ -15,6 +15,8 @@ export interface Context {
     borrowed?: Borrowed;
 }
 export declare function createContext(packageRoot: string, entry: string, options: CliOptions): Context;
+/** Reads the config again and takes the storage folder from it (after a migration or a move changed it). */
+export declare function refreshStorage(ctx: Context): void;
 /** For commands that control the sandbox from your PC: inside the sandbox they make no sense. */
 export declare function requireOnPc(what: string): void;
 export declare function requireRunning(hint?: string): void;

package/dist/cli/commands/context.js

@@ -36,14 +36,21 @@ export function createContext(packageRoot, entry, options) {
         dataPath: insideSandbox() ? GUEST_DATA_DIR : path.join(storageRoot, 'data', loaded.config.storage.dataName),
     };
 }
+/** Reads the config again and takes the storage folder from it (after a migration or a move changed it). */
+export function refreshStorage(ctx) {
+    ctx.loaded = loadConfig(ctx.options.config);
+    ctx.storageRoot = expandPath(ctx.loaded.config.storage.root, ctx.loaded.base);
+    if (!insideSandbox())
+        ctx.dataPath = path.join(ctx.storageRoot, 'data', ctx.loaded.config.storage.dataName);
+}
 /** For commands that control the sandbox from your PC: inside the sandbox they make no sense. */
 export function requireOnPc(what) {
     if (insideSandbox())
-        fail('You are inside the sandbox already, so "sandbox ' + what + '" has nothing to control.', 'Run it from a terminal on your PC.');
+        fail('You are inside the sandbox already, so "sandbox ' + what + '" has nothing to control.', 'Run it from a terminal on your PC. Inside the sandbox these work: sandbox status, sessions, config, data, db, doctor, logs.');
 }
 export function requireRunning(hint = '') {
     if (!isSandboxRunning())
-        fail('No Windows Sandbox is running.', hint || 'Start one with sandbox claude.');
+        fail('No Windows Sandbox is running.', hint || 'Start one: sandbox start (no agent) or sandbox claude.');
 }
 /**
  * Maps a folder on this PC to its path inside the running sandbox (only folders inside the mapped workspace exist

package/dist/cli/commands/data/clean.js

@@ -1,13 +1,34 @@
 // `sandbox data clean`: asks, then removes the folders the targets name (DataService does the work).
 import { humanBytes } from '../../../core/disk.js';
-import { askTyped, askYesNo } from '../../../core/prompt.js';
+import { askChoices, askRequired, askTyped } from '../../../core/prompt.js';
 import { fail } from '../../../core/util/index.js';
-import { table } from '../../output/index.js';
+import { nextStep, table, working } from '../../output/index.js';
 import { DataService } from '../../services/index.js';
+import { cleanTargetOf } from './collect.js';
 export { resolveCleanTargets } from '../../services/index.js';
+/** No target typed: a list of what can be cleaned, with sizes, to tick from (a terminal is needed). */
+async function pickTargets(service) {
+    const fix = 'Name them: sandbox data clean logs tools/go   (what exists: sandbox data)';
+    if (!process.stdin.isTTY)
+        fail('Which data should be cleaned?', fix);
+    const rows = await working('Measuring the saved data (big folders take a moment)', () => service.entries());
+    const choices = rows.flatMap((e) => {
+        const target = cleanTargetOf(e);
+        return target ? [{ name: target.padEnd(28) + humanBytes(e.bytes), value: target }] : [];
+    });
+    if (!choices.length)
+        return [];
+    return askChoices('What do you want to delete? (space ticks, enter confirms)', choices, fix);
+}
 export async function dataClean(ctx) {
     const service = new DataService(ctx);
-    const { targets, present: sized, totalBytes: total } = service.plan(ctx.options.positionals.slice(1));
+    const typed = ctx.options.positionals.slice(1);
+    const inputs = typed.length ? typed : await pickTargets(service);
+    if (!inputs.length) {
+        console.log('Nothing chosen, nothing removed.');
+        return 0;
+    }
+    const { targets, present: sized, totalBytes: total } = service.plan(inputs);
     if (!sized.length) {
         console.log('Nothing to remove: ' + targets.map((t) => t.target).join(', ') + ' do(es) not exist.');
         return 0;
@@ -20,18 +41,20 @@ export async function dataClean(ctx) {
     if (!yes) {
         const ok = sized.some((t) => t.target === 'all')
             ? await askTyped('This cannot be undone; the next sandbox starts from scratch and reinstalls everything.', 'all')
-            : await askYesNo('Delete ' + sized.map((t) => t.target).join(', ') + ' (' + humanBytes(total) + ')? This cannot be undone.');
+            : await askRequired('Delete ' + sized.map((t) => t.target).join(', ') + ' (' + humanBytes(total) + ')? This cannot be undone.', 'Add --yes to delete without asking.');
         if (!ok) {
-            console.log('Nothing removed.' + (process.stdin.isTTY ? '' : ' Pass --yes to confirm without a prompt.'));
+            console.log('Nothing removed.');
             return 1;
         }
     }
     const outcome = service.clean({ targets, present: sized, totalBytes: total });
-    console.log('Freed ' +
-        humanBytes(outcome.freedBytes) +
-        '. ' +
-        (outcome.touchedData ? 'The next sandbox reinstalls what it needs.' : ''));
     if (outcome.failed.length)
         fail('Could not remove everything: ' + outcome.failed.join('; '), 'Close programs using those folders and run the same command again.');
+    console.log('Removed ' +
+        sized.map((t) => t.target).join(', ') +
+        ' and freed ' +
+        humanBytes(outcome.freedBytes) +
+        (outcome.touchedData ? '; the next sandbox reinstalls what it needs.' : '.'));
+    nextStep('sandbox data   (see what is left)');
     return 0;
 }

package/dist/cli/commands/engine.d.ts

@@ -0,0 +1,2 @@
+import type { Context } from './context.js';
+export declare function engine(ctx: Context): Promise<number>;

package/dist/cli/commands/engine.js

@@ -0,0 +1,60 @@
+// `sandbox engine`: the engine in use and, for each engine, what it can do and whether this PC can run it.
+import { fail } from '../../core/util/index.js';
+import { engineReports } from '../../host/engines/index.js';
+import { c, printJson, table } from '../output/index.js';
+const CAPABILITY_NAMES = {
+    desktop: 'desktop window',
+    gpu: 'GPU',
+    clipboard: 'clipboard',
+    audio: 'audio',
+    video: 'camera',
+    printers: 'printers',
+    liveFolderAdd: 'add folders while running',
+    attachedDisks: 'attached disks',
+    multipleInstances: 'several at once',
+    hvsocket: 'Hyper-V sockets',
+};
+/** sandbox engine check <engine>: the reasons and the exact commands, in plain words. Nothing is run or changed. */
+async function checkEngine(ctx, name) {
+    const report = (await engineReports(ctx.loaded.config)).find((r) => r.id === name);
+    if (!report)
+        return fail('Unknown engine: ' + name, 'Use windows-sandbox or hcs.');
+    if (printJson(ctx, report))
+        return report.check.available ? 0 : 1;
+    if (report.check.available) {
+        console.log(c.green(name + ' can be used on this PC.'));
+        if (name === 'hcs')
+            console.log('HCS is in alpha: starting it is not enabled yet (docs/design/engines.md).');
+        return 0;
+    }
+    console.log(c.yellow(name + ' cannot be used on this PC yet:'));
+    report.check.reasons.forEach((reason, i) => {
+        console.log('\n  ' + (i + 1) + '. ' + reason);
+        console.log('     To fix: ' + (report.check.fixes[i] ?? 'see docs/design/engines.md'));
+    });
+    console.log('\nNothing was changed. These commands change Windows, so they are yours to run (or not).');
+    return 1;
+}
+export async function engine(ctx) {
+    const [action = 'show', name = 'hcs'] = ctx.options.positionals;
+    if (action === 'check')
+        return checkEngine(ctx, name);
+    const reports = await engineReports(ctx.loaded.config);
+    const using = reports.find((r) => r.inUse);
+    if (printJson(ctx, { engine: using?.id, engines: reports }))
+        return 0;
+    console.log('Engine in use: ' + (using?.id ?? ctx.loaded.config.sandbox.engine) + '  (setting: sandbox.engine)');
+    for (const report of reports) {
+        console.log('\n' + report.id + (report.inUse ? '  (in use)' : ''));
+        console.log('  ' + (report.check.available ? c.green('can be used on this PC') : c.yellow('cannot be used yet')));
+        for (const reason of report.check.reasons)
+            console.log('  ' + reason);
+        for (const fix of report.check.fixes)
+            console.log('  Fix: ' + fix);
+        table(Object.entries(CAPABILITY_NAMES).map(([key, name]) => [
+            '  ' + name,
+            report.capabilities[key] ? 'yes' : 'no',
+        ]));
+    }
+    return 0;
+}

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

@@ -2,8 +2,9 @@ export { createContext, type Context } from './context.js';
 export { launch } from './launch/index.js';
 export { setup } from './setup/index.js';
 export { data } from './data/index.js';
+export { storage, storageBeforeCommand } from './storage/index.js';
 export { repairCommand } from './repair/index.js';
-export { attach, db, exec, hide, show, restart, stop, sessions, status } from './sessions/index.js';
+export { attach, db, exec } from './sessions/index.js';
 export { account } from './accounts.js';
 export { resume } from './resume.js';
 export { projects } from './projects/index.js';

package/dist/cli/commands/index.js

@@ -2,8 +2,9 @@ export { createContext } from './context.js';
 export { launch } from './launch/index.js';
 export { setup } from './setup/index.js';
 export { data } from './data/index.js';
+export { storage, storageBeforeCommand } from './storage/index.js';
 export { repairCommand } from './repair/index.js';
-export { attach, db, exec, hide, show, restart, stop, sessions, status } from './sessions/index.js';
+export { attach, db, exec } from './sessions/index.js';
 export { account } from './accounts.js';
 export { resume } from './resume.js';
 export { projects } from './projects/index.js';

package/dist/cli/commands/launch/add-root.d.ts

@@ -1,7 +1,8 @@
 import type { ResolvedRun } from '../../../core/types.js';
 import { type Context } from '../context.js';
 /**
- * Asked once per parent folder: map it at every start (a project root), so the projects next to this one open in the
- * running sandbox without a restart. The answer is saved to your config.
+ * Asked at a start from a folder whose parent is not shared yet ("Not now" asks again next time): map it at every
+ * start (a project root), so the projects next to this one open in the running sandbox without a restart. The answer is
+ * saved to your config.
  */
 export declare function maybeAddRoot(ctx: Context, run: ResolvedRun): Promise<void>;