windows-development-sandbox 1.5.0 → 1.9.0

package/dist/cli/commands/storage/offer.js

@@ -0,0 +1,91 @@
+// At the start of an interactive command: makes sure the storage folder exists (private when it should be) and, once,
+// offers to move saved data from another folder to where it belongs. Never asks without a terminal.
+import { select } from '@inquirer/prompts';
+import { userDir } from '../../../core/config/index.js';
+import { errMsg } from '../../../core/util/index.js';
+import { isSandboxRunning, insideSandbox } from '../../../host/sandbox/index.js';
+import { protectPrivateFolder } from '../../../host/sharing/index.js';
+import { describeDuration, describeSize, ensureStorageRoot, estimate, measureFolder, moveWarning, planOffer, staleMountNote, StorageHistory, } from '../../../host/storage/index.js';
+import { c, working } from '../../output/index.js';
+import { refreshStorage } from '../context.js';
+import { performMove } from './storage.js';
+/** Commands that do not touch the storage folder, or must work whatever state it is in. */
+const NO_STORAGE = ['self-test', '_watch', '_web', 'update', 'storage', 'migrate', 'repair'];
+/** Commands that start something the user is sitting in front of: the offer is shown before them. */
+const OFFERS = ['menu', 'launch'];
+async function ask(text) {
+    console.error('\n' + text + '\n');
+    return select({
+        message: 'Move it now?',
+        choices: [
+            { name: 'Move now', value: 'now' },
+            { name: 'Not now', value: 'later' },
+            { name: "Don't ask again", value: 'never' },
+        ],
+        default: 'now',
+    });
+}
+function offerText(offer, size, time, warning) {
+    const where = offer.toIsDefault
+        ? 'The default folder is now ' + offer.to + ', which works for both kinds of install.'
+        : 'Your folder is ' + offer.to + '.';
+    return ('Your saved data (' +
+        size +
+        ') is in ' +
+        offer.from +
+        '. ' +
+        where +
+        ' Move it there now? ' +
+        time +
+        '.' +
+        (warning ? '\n' + warning : ''));
+}
+async function offerMove(ctx, history) {
+    const offer = planOffer(ctx.storageRoot, history);
+    if (!offer || isSandboxRunning())
+        return;
+    const measured = await working('Looking at your saved data', () => measureFolder(offer.from));
+    const est = estimate(offer.from, offer.to, measured);
+    const spoken = est.sameVolume ? 'a few seconds' : describeDuration(est.seconds);
+    const time = spoken.charAt(0).toUpperCase() + spoken.slice(1);
+    if (!est.fits) {
+        console.error(c.dim(moveWarning(measured, est) ?? ''));
+        return;
+    }
+    const answer = await ask(offerText(offer, describeSize(measured), time, moveWarning(measured, est)));
+    if (answer === 'never')
+        history.setDontAsk();
+    else if (answer === 'later')
+        history.setNotNow();
+    if (answer !== 'now')
+        return;
+    const result = await performMove({ ...ctx, storageRoot: offer.from }, offer.to, false);
+    console.error('Moved. Your data is now in ' + result.to + '.');
+    for (const note of result.notes)
+        console.error(c.dim(note));
+    refreshStorage(ctx);
+}
+/** Before a command (after the saved settings are up to date). A failed move never stops the command. */
+export async function storageBeforeCommand(ctx, command) {
+    if (insideSandbox() || NO_STORAGE.includes(command))
+        return;
+    if (OFFERS.includes(command) &&
+        process.stdin.isTTY &&
+        process.stdout.isTTY &&
+        !ctx.options.json &&
+        !ctx.options.unattended) {
+        try {
+            await offerMove(ctx, new StorageHistory(userDir()));
+        }
+        catch (e) {
+            console.error(c.red('Could not move your data: ') + errMsg(e));
+        }
+    }
+    ensureStorageRoot(ctx.storageRoot, protectPrivateFolder);
+    // Contained storage (beta): a mount an earlier sandbox left behind is only mentioned here; repair fixes it.
+    if (command !== 'launch' && !ctx.options.json) {
+        const stale = staleMountNote(ctx.storageRoot, ctx.loaded.config.storage.dataName, isSandboxRunning());
+        if (stale)
+            console.error(c.yellow(stale));
+    }
+}

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

@@ -0,0 +1,8 @@
+import { type MoveResult } from '../../../host/storage/index.js';
+import { type Context } from '../context.js';
+/** Why a move cannot start (a background sync is still on a data folder in the old storage), or null. */
+export declare function storageBusy(root: string): string | null;
+/** Moves the data with progress on the terminal; remembers both folders. Used by the command and the start offer. */
+export declare function performMove(ctx: Context, to: string, keepOld: boolean): Promise<MoveResult>;
+/** `sandbox storage [show|move <folder>|use <folder>]`. */
+export declare function storage(ctx: Context): number | Promise<number>;

package/dist/cli/commands/storage/storage.js

@@ -0,0 +1,179 @@
+// `sandbox storage`: where everything kept between sandboxes lives, moving it to another folder (with the size, an
+// estimate and a warning first) and switching to a folder without moving. The work is in host/storage.
+import fs from 'node:fs';
+import path from 'node:path';
+import { userConfigPath, userDir } from '../../../core/config/index.js';
+import { diskUsage, humanBytes } from '../../../core/disk.js';
+import { askChoice, askName, askRequired } from '../../../core/prompt.js';
+import { expandPath, fail } from '../../../core/util/index.js';
+import { describeDuration, describeSize, estimate, holdsData, measureFolder, mountedSets, moveWarning, otherDataFolders, sharedDefaultRoot, StorageHistory, StorageMove, } from '../../../host/storage/index.js';
+import { isSandboxRunning } from '../../../host/sandbox/index.js';
+import { protectPrivateFolder } from '../../../host/sharing/index.js';
+import { watcherRunning } from '../../../sync/index.js';
+import { printJson, working } from '../../output/index.js';
+import { requireOnPc } from '../context.js';
+import { contained } from './contained.js';
+/** Why a move cannot start (a background sync is still on a data folder in the old storage), or null. */
+export function storageBusy(root) {
+    const mounted = mountedSets(root);
+    if (mounted.length > 0)
+        return ('The contained storage of "' +
+            mounted.join('", "') +
+            '" is mounted (a disk image; moving now would reach into it).');
+    const data = path.join(root, 'data');
+    try {
+        for (const name of fs.readdirSync(data))
+            if (watcherRunning(path.join(data, name)))
+                return 'The background sync of "' + name + '" is still finishing.';
+    }
+    catch {
+        // no data folder: nothing runs
+    }
+    return null;
+}
+function mover(ctx) {
+    return new StorageMove(ctx.loaded.configPath ?? userConfigPath(), () => storageBusy(ctx.storageRoot), isSandboxRunning, protectPrivateFolder);
+}
+/** The path as typed (variables and ~ expand, relative to the current folder). */
+function typedPath(value) {
+    return expandPath(value, process.cwd());
+}
+/** The folder typed, or picked from the default folder, folders that hold data and the drives (or typed in). */
+async function folderOf(ctx, value, what) {
+    if (value)
+        return typedPath(value);
+    const fix = 'Use: sandbox storage ' + what + ' <folder>';
+    const typed = 'type';
+    const known = [sharedDefaultRoot(), ...otherDataFolders(ctx.storageRoot, new StorageHistory(userDir()))];
+    const drives = diskUsage(ctx.storageRoot)
+        .filter((d) => !d.holdsStorage)
+        .map((d) => path.join(d.drive, 'AgentSandbox'));
+    const choices = [...new Set([...known, ...drives])]
+        .filter((f) => f.toLowerCase() !== ctx.storageRoot.toLowerCase())
+        .map((f) => ({ name: f, value: f }));
+    const picked = await askChoice('Which folder?', [...choices, { name: 'Type a path...', value: typed }], fix);
+    if (picked !== typed)
+        return picked;
+    const answer = await askName('Folder:', fix, (v) => v.length > 0 || 'Type a folder path.');
+    return typedPath(answer);
+}
+async function show(ctx) {
+    const history = new StorageHistory(userDir());
+    const measured = await working('Measuring your saved data (big folders take a moment)', () => measureFolder(ctx.storageRoot), !ctx.options.json);
+    const others = otherDataFolders(ctx.storageRoot, history);
+    const shared = sharedDefaultRoot();
+    if (printJson(ctx, {
+        root: ctx.storageRoot,
+        exists: fs.existsSync(ctx.storageRoot),
+        ...measured,
+        defaultRoot: shared,
+        otherFoldersWithData: others,
+    }))
+        return 0;
+    const inUse = shared.toLowerCase() === ctx.storageRoot.toLowerCase() ? ' (in use)' : '';
+    console.log('Your saved data is in: ' + ctx.storageRoot);
+    console.log('  ' + (holdsData(ctx.storageRoot) ? describeSize(measured) : 'nothing in it yet'));
+    console.log('The default folder is: ' + shared + inUse);
+    for (const other of others)
+        console.log('Another folder with data: ' + other);
+    console.log('\nMove it with: sandbox storage move <folder>  (or switch without moving: sandbox storage use <folder>)');
+    console.log('What takes the space: sandbox data');
+    return 0;
+}
+function printPlan(from, to, measured, copyOnly) {
+    const est = estimate(from, to, measured, copyOnly);
+    const time = est.sameVolume
+        ? 'a few seconds (same drive, nothing is copied)'
+        : describeDuration(est.seconds) + ' (copied to another drive)';
+    console.log('Move from: ' + from);
+    console.log('       to: ' + to);
+    console.log('     size: ' + describeSize(measured));
+    console.log('     time: ' + time);
+    const warning = moveWarning(measured, est);
+    if (warning)
+        console.log('Warning: ' + warning);
+    if (!est.fits)
+        fail('Not enough free space on the target drive.', 'Free some space or pick another drive.');
+}
+/** Moves the data with progress on the terminal; remembers both folders. Used by the command and the start offer. */
+export async function performMove(ctx, to, keepOld) {
+    const from = ctx.storageRoot;
+    const history = new StorageHistory(userDir());
+    let line = 'Moving your data';
+    const result = await working(() => line, () => mover(ctx).move(from, to, {
+        keepOld,
+        onProgress: (p) => {
+            line = 'Copying: ' + p.files.toLocaleString('en-US') + ' files, ' + humanBytes(p.bytes);
+        },
+    }));
+    history.remember(from);
+    history.remember(to);
+    return result;
+}
+async function move(ctx) {
+    const to = await folderOf(ctx, ctx.options.positionals[1], 'move');
+    const from = ctx.storageRoot;
+    if (!fs.existsSync(from))
+        fail('There is nothing to move: ' + from + ' does not exist.', 'Use sandbox storage use ' + to + ' to switch.');
+    mover(ctx).validate(from, to);
+    const measured = await working('Measuring your saved data', () => measureFolder(from), !ctx.options.json);
+    const keepOld = ctx.options.keepOld;
+    printPlan(from, to, measured, keepOld);
+    if (!ctx.options.yes) {
+        if (!(await askRequired('Move your data to ' + to + '?', 'Add --yes to move without asking.', true))) {
+            console.log('Nothing was moved.');
+            return 1;
+        }
+    }
+    const result = await performMove(ctx, to, keepOld);
+    if (printJson(ctx, result))
+        return 0;
+    const left = result.removedOld ? '' : '; the old folder is still at ' + result.from;
+    console.log('Moved ' + result.files.toLocaleString('en-US') + ' files. Your data is now in ' + result.to + left + '.');
+    for (const note of result.notes)
+        console.log(note);
+    console.log('Your settings now point to ' + result.pinned + ', so older versions find the data too.');
+    return 0;
+}
+async function use(ctx) {
+    const to = await folderOf(ctx, ctx.options.positionals[1], 'use');
+    if (to.toLowerCase() === ctx.storageRoot.toLowerCase()) {
+        console.log('That folder is in use already.');
+        return 0;
+    }
+    const busy = storageBusy(ctx.storageRoot);
+    if (busy)
+        fail(busy, 'Wait a minute, then try again.');
+    const state = holdsData(to)
+        ? to + ' is used as it is.'
+        : to + ' starts empty: tools, logins and history are set up again.';
+    console.log('Warning: your data stays in ' + ctx.storageRoot + '. ' + state);
+    if (!ctx.options.yes) {
+        if (!(await askRequired('Use ' + to + ' from now on, without moving your data?', 'Add --yes to switch without asking.'))) {
+            console.log('Nothing was changed.');
+            return 1;
+        }
+    }
+    new StorageHistory(userDir()).remember(ctx.storageRoot);
+    mover(ctx).pin(to);
+    console.log('Your data is now looked for in ' + to + '. Move it later with: sandbox storage move <folder>');
+    return 0;
+}
+/** `sandbox storage [show|move <folder>|use <folder>]`. */
+export function storage(ctx) {
+    requireOnPc('storage');
+    const [action = 'show'] = ctx.options.positionals;
+    switch (action) {
+        case 'show':
+        case 'info':
+            return show(ctx);
+        case 'move':
+            return move(ctx);
+        case 'use':
+            return use(ctx);
+        case 'contained':
+            return contained(ctx);
+        default:
+            return fail('Unknown storage action "' + action + '".', 'Use: sandbox storage, sandbox storage move <folder>, sandbox storage use <folder> or sandbox storage contained on|off|status');
+    }
+}

package/dist/cli/commands/user-config.js

@@ -6,7 +6,7 @@ import { parse } from 'jsonc-parser';
 import _ from 'lodash';
 import { userConfigPath } from '../../core/config/index.js';
 import { fail } from '../../core/util/index.js';
-import { editConfigText } from '../menu/settings/index.js';
+import { editConfigText } from '../../app/features/settings/index.js';
 export function configFile(ctx) {
     return ctx.loaded.configPath ?? userConfigPath();
 }
@@ -21,7 +21,7 @@ export function setSetting(ctx, key, value) {
     const text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
     const result = editConfigText(text, key, value);
     if ('problems' in result)
-        fail('Could not change ' + key.join('.') + ':\n  ' + result.problems.join('\n  '));
+        fail('Could not change ' + key.join('.') + ':\n  ' + result.problems.join('\n  '), 'Nothing was written. Fix the value, or the settings file: ' + file);
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, result.text, 'utf8');
 }

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

@@ -0,0 +1,4 @@
+import { type Context } from './context.js';
+/** The warnings every VPN user must see. */
+export declare const VPN_WARNINGS: readonly string[];
+export declare function vpn(ctx: Context): Promise<number> | number;

package/dist/cli/commands/vpn.js

@@ -0,0 +1,91 @@
+// `sandbox vpn [status|login|logout]`: the VPN login (kept encrypted on this PC, never printed) and what the VPN is
+// doing.
+import { askSecret } from '../../core/prompt.js';
+import { fail } from '../../core/util/index.js';
+import { c, nextStep, printJson, table } from '../output/index.js';
+import { NORD_STEPS, VpnService } from '../services/vpn-service.js';
+import { requireOnPc } from './context.js';
+const LOGIN_TEXT = {
+    none: c.yellow('not saved'),
+    saved: c.green('saved (encrypted)'),
+    unreadable: c.red('cannot be read'),
+};
+/** The warnings every VPN user must see. */
+export const VPN_WARNINGS = [
+    'The agent in the sandbox can read the VPN login (a service login you can revoke) and can turn the tunnel off, because it is the administrator there.',
+    'Free VPNs see all your traffic: use one you trust.',
+];
+async function status(ctx) {
+    const report = await new VpnService(ctx).report();
+    if (printJson(ctx, report))
+        return 0;
+    table([
+        ['VPN', report.enabled ? c.green('on') : 'off  (turn on: sandbox config set vpn.enabled true)'],
+        [
+            'Provider',
+            report.provider === 'nordvpn'
+                ? 'NordVPN'
+                : report.provider === 'wireguard-file'
+                    ? 'your own WireGuard .conf'
+                    : 'your own .ovpn file',
+        ],
+        ['Protocol', report.protocol],
+        ['Country', report.country || 'best available'],
+        ['Kill switch', report.killSwitch ? 'on (no internet if the tunnel fails)' : c.yellow('off')],
+        [
+            'Login',
+            report.provider === 'wireguard-file'
+                ? c.dim('not needed (the keys are in your config)')
+                : LOGIN_TEXT[report.login] + (report.loginSavedAt ? c.dim('  ' + report.loginSavedAt.slice(0, 10)) : ''),
+        ],
+        ...(report.running ? [['Running now', report.running.text]] : []),
+    ]);
+    if (report.provider !== 'wireguard-file' && report.login === 'none')
+        nextStep('sandbox vpn login');
+    if (report.login === 'unreadable')
+        console.log(c.dim('Only the Windows user that saved it can read it. Save it again: sandbox vpn login'));
+    for (const w of VPN_WARNINGS)
+        console.log(c.dim(w));
+    return 0;
+}
+async function login(ctx) {
+    requireOnPc('vpn login');
+    const service = new VpnService(ctx);
+    if (service.provider === 'wireguard-file') {
+        console.log('A WireGuard config needs no login: the keys are in the file vpn.configFile points to.');
+        return 0;
+    }
+    const nord = service.provider === 'nordvpn';
+    console.log(nord
+        ? 'NordVPN needs its service credentials, not your usual login. To get them:'
+        : 'Type the user name and password your VPN profile asks for.');
+    if (nord)
+        NORD_STEPS.forEach((s, i) => console.log('  ' + (i + 1) + '. ' + s));
+    console.log(c.dim('What you type is not shown. It is kept encrypted for your Windows user and never printed.\n'));
+    const fix = 'Run sandbox vpn login in a terminal.';
+    const username = await askSecret(nord ? 'Service user name' : 'User name', fix);
+    const password = await askSecret(nord ? 'Service password' : 'Password', fix);
+    service.save({ username, password });
+    console.log(c.green('Saved.') + ' Turn the VPN on with: sandbox config set vpn.enabled true');
+    for (const w of VPN_WARNINGS)
+        console.log(c.dim(w));
+    return 0;
+}
+function logout(ctx) {
+    requireOnPc('vpn logout');
+    console.log(new VpnService(ctx).remove() ? 'The saved VPN login is deleted.' : 'No VPN login was saved.');
+    return 0;
+}
+export function vpn(ctx) {
+    const action = ctx.options.positionals[0] ?? 'status';
+    switch (action) {
+        case 'status':
+            return status(ctx);
+        case 'login':
+            return login(ctx);
+        case 'logout':
+            return logout(ctx);
+        default:
+            return fail('Unknown VPN action "' + action + '".', 'Use: sandbox vpn status | login | logout');
+    }
+}

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

@@ -0,0 +1,4 @@
+import { type Context } from './context.js';
+export declare function web(ctx: Context): Promise<number>;
+/** Body of the background process (`sandbox _web`): runs until stopped. */
+export declare function webServer(ctx: Context): Promise<void>;

package/dist/cli/commands/web.js

@@ -0,0 +1,97 @@
+// `sandbox web start | stop | status | open`: the web UI's server runs in the background (as `_web`, like the sync
+// watcher) and keeps running when no sandbox does. The work is in host/web.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fail, sleep } from '../../core/util/index.js';
+import { spawnDetached } from '../../host/sandbox/index.js';
+import { openBrowser, WebControl, WebRunner, WebStore } from '../../host/web/index.js';
+import { printJson } from '../output/index.js';
+import { createRpcHost } from '../../app/registry.js';
+import { WebService } from '../services/index.js';
+import { requireOnPc } from './context.js';
+const START_WAIT_MS = 15000;
+function controlOf(ctx) {
+    return new WebControl(new WebStore(ctx.storageRoot));
+}
+/** Starts the background server (when it is not running) and waits until it answers. */
+async function startServer(ctx, control) {
+    const before = await control.status();
+    if (before.running && before.state) {
+        console.log('The web UI is already running on port ' + before.state.port + '.');
+        return before.state.port;
+    }
+    if (before.state)
+        control.clear();
+    const { config } = ctx.loaded;
+    if (!config.web.enabled)
+        console.log('web.enabled is off: this starts the web UI for now only. Set it to true in Settings to keep it allowed.');
+    const configFile = ctx.options.config;
+    spawnDetached(ctx.entry, ['_web', ...(configFile ? ['--config', path.resolve(configFile)] : [])]);
+    for (const started = Date.now(); Date.now() - started < START_WAIT_MS; await sleep(300)) {
+        const now = await control.status();
+        if (now.running && now.state) {
+            console.log('The web UI is running at http://127.0.0.1:' + now.state.port + '/ (this PC only).');
+            console.log('Open it already signed in with: sandbox web open');
+            return now.state.port;
+        }
+    }
+    return fail('The web UI did not start.', 'Run sandbox _web to see why (the port ' + config.web.port + ' may be taken: change web.port).');
+}
+export async function web(ctx) {
+    requireOnPc('web');
+    const action = ctx.options.positionals[0] ?? 'status';
+    const control = controlOf(ctx);
+    switch (action) {
+        case 'start':
+            await startServer(ctx, control);
+            return 0;
+        case 'open': {
+            await startServer(ctx, control);
+            const { state } = await control.status();
+            if (!state)
+                return fail('The web UI stopped right away.', 'Run sandbox web start again.');
+            openBrowser(control.url(state));
+            console.log('Opened in your browser.');
+            return 0;
+        }
+        case 'stop': {
+            const { running, state } = await control.status();
+            if (!state) {
+                console.log('The web UI is not running.');
+                return 0;
+            }
+            if (!running || (await control.stop(state)))
+                control.clear();
+            else
+                return fail('The web UI did not stop.', 'End the process ' + state.pid + ' in Task Manager.');
+            console.log('The web UI stopped.');
+            return 0;
+        }
+        case 'status': {
+            const { running, state } = await control.status();
+            const port = running && state ? state.port : null;
+            if (printJson(ctx, { running, port, address: port ? 'http://127.0.0.1:' + port + '/' : null }))
+                return 0;
+            console.log(running && port
+                ? 'The web UI is running at http://127.0.0.1:' + port + '/ (sandbox web open signs you in).'
+                : 'The web UI is not running (sandbox web start).');
+            return 0;
+        }
+        default:
+            return fail('Unknown action "' + action + '".', 'Use start, stop, status or open.');
+    }
+}
+/** Body of the background process (`sandbox _web`): runs until stopped. */
+export async function webServer(ctx) {
+    const staticRoot = path.join(ctx.packageRoot, 'dist', 'web');
+    if (!fs.existsSync(path.join(staticRoot, 'index.html')))
+        fail('The web app is not built (' + staticRoot + ').', 'Run npm run build in the install folder.');
+    await new WebRunner({
+        storageRoot: ctx.storageRoot,
+        port: ctx.loaded.config.web.port,
+        backend: new WebService(ctx),
+        rpc: createRpcHost(ctx),
+        staticRoot,
+    }).run();
+    process.exit(0);
+}

package/dist/cli/history.js

@@ -7,7 +7,7 @@ const HistorySchema = z.array(z.strictObject({ argv: z.array(z.string()).max(200
 function historyFile() {
     return new JsonFile(HistorySchema, path.join(userDir(), 'history.json'));
 }
-const HIDDEN = new Set(['menu', '_watch', 'self-test']);
+const HIDDEN = new Set(['menu', '_watch', '_web', 'self-test']);
 export function readHistory() {
     return historyFile().read() ?? [];
 }

package/dist/cli/index.js

@@ -1,18 +1,40 @@
 import path from 'node:path';
 import { buildProgram, parseCli } from './args.js';
-import { commandSpec } from './manifest.js';
+import { COMMANDS, commandSpec } from './manifest.js';
 import { recordHistory } from './history.js';
 import { menu } from './menu/index.js';
-import { validateOptions } from './validate.js';
+import { closest, validateOptions } from './validate.js';
 import { loadConfig } from '../core/config/index.js';
 import * as commands from './commands/index.js';
 import { fail } from '../core/util/index.js';
-import { PACKAGE_ROOT } from '../core/package-info.js';
+import { PACKAGE_ROOT, packageVersion } from '../core/package-info.js';
+import { takeHiddenInstallNotice } from '../host/install/index.js';
+import { c } from './output/index.js';
 import { dropInheritedModulePath } from '../shared/system.js';
 import { withConfig, hoistConfig, withoutConfig } from './argv.js';
 import { report } from './report.js';
+import { versionText } from './version.js';
 import { HANDLERS } from './commands/index.js';
+import { operationHandler } from './operations/index.js';
 const entry = path.join(PACKAGE_ROOT, 'dist', 'bin', 'agent-sandbox.js');
+/** A first word that is no command and no agent, but close to one: "Did you mean: sandbox status?". */
+function failOnTypo(word, agents) {
+    const names = [...COMMANDS.filter((c) => !c.hidden).map((c) => c.name), ...agents];
+    const hint = closest(word, names);
+    if (hint)
+        fail('Unknown command "' + word + '". Did you mean: sandbox ' + hint + '?', 'Run sandbox --help for the list of commands, or sandbox for the menu.');
+}
+/** One yellow line, once per version, when this is not the managed install but one exists (it is hidden). */
+function hiddenInstallNotice(storageRoot) {
+    try {
+        const line = takeHiddenInstallNotice(storageRoot, PACKAGE_ROOT, packageVersion());
+        if (line)
+            console.log(c.yellow(line));
+    }
+    catch {
+        // A note that cannot be saved is not worth stopping a start for.
+    }
+}
 /** Runs an argv from the menu exactly as if it had been typed, reporting errors instead of throwing. */
 const runFromMenu = (config) => (argv) => main(withConfig(argv, config)).catch((e) => report(e));
 /**
@@ -33,10 +55,27 @@ export async function main(rawArgv, preset = {}) {
         }
     };
     if (!preset.command && !preset.harness) {
+        const version = versionText(withoutConfig(argv), PACKAGE_ROOT);
+        if (version !== null) {
+            console.log(version);
+            return 0;
+        }
         if (argv.length === 0)
             return process.stdin.isTTY ? main(['menu']) : (buildProgram(() => undefined).outputHelp(), 0);
         if (isAgent(argv[0]))
             return main(argv.slice(1), { harness: argv[0] });
+        const first = argv.slice(0, 1)[0];
+        if (first && !first.startsWith('-') && !commandSpec(first) && first !== 'help') {
+            const at = argv.indexOf('--config');
+            let agents = [];
+            try {
+                agents = Object.keys(loadConfig(at >= 0 ? argv[at + 1] : undefined).config.harnesses);
+            }
+            catch {
+                // A broken settings file: the commands alone are suggested.
+            }
+            failOnTypo(first, agents);
+        }
     }
     const options = parseCli(preset.command ? [preset.command, ...argv] : argv, Boolean(preset.harness));
     if (preset.harness)
@@ -48,8 +87,10 @@ export async function main(rawArgv, preset = {}) {
             : argv;
     if (options.command === 'menu') {
         const menuCtx = commands.createContext(PACKAGE_ROOT, entry, options);
+        hiddenInstallNotice(menuCtx.storageRoot);
         await commands.migrateBeforeCommand(menuCtx, options.command);
         commands.updatesBeforeCommand(entry, options.command);
+        await commands.storageBeforeCommand(menuCtx, options.command);
         return menu(menuCtx, runFromMenu(options.config));
     }
     // Loaded only when asked for: normal commands never load test code.
@@ -63,13 +104,16 @@ export async function main(rawArgv, preset = {}) {
     // update works on the install, not on a sandbox: it needs no settings (and a broken file must not stop it).
     if (options.command === 'update')
         return commands.update(options);
-    const handler = HANDLERS[options.command];
+    const handler = operationHandler(options.command, options.positionals) ?? HANDLERS[options.command];
     if (!handler)
         return fail('Unknown command "' + options.command + '".', 'Run sandbox --help for the list of commands, or sandbox for the menu.');
     const ctx = commands.createContext(PACKAGE_ROOT, entry, options);
     validateOptions(ctx);
+    if (options.command === 'launch')
+        hiddenInstallNotice(ctx.storageRoot);
     await commands.migrateBeforeCommand(ctx, options.command);
     commands.updatesBeforeCommand(entry, options.command);
+    await commands.storageBeforeCommand(ctx, options.command);
     // Only what parsed and validated is offered again by the menu, without the --config (it is the same every time).
     recordHistory(withoutConfig(typed));
     return (await handler(ctx)) ?? 0;