windows-development-sandbox 1.5.0 → 1.9.0

package/dist/cli/commands/repair/run.js

@@ -0,0 +1,133 @@
+// `sandbox doctor` and `sandbox repair`: both run the same checks through the same engine, a line each as it ends.
+// doctor only looks (and offers to fix, or fixes with --fix); repair looks, lists what it would change, asks once, then
+// fixes and writes a log. --json prints the results instead and never asks.
+import path from 'node:path';
+import { confirm } from '@inquirer/prompts';
+import { DEFAULTS, userDir } from '../../../core/config/index.js';
+import { packageVersion } from '../../../core/package-info.js';
+import { expandPath, UserError } from '../../../core/util/index.js';
+import { insideSandbox } from '../../../host/sandbox/index.js';
+import { printJson, table } from '../../output/index.js';
+import { HealthService } from '../../services/index.js';
+import { createContext, requireOnPc } from '../context.js';
+import { ALL_CHECKS } from './checks/index.js';
+import { buildEnv } from './env.js';
+import { HealthRun, summarize } from './engine.js';
+import { logText, writeRepairLog } from './log.js';
+import { HealthPrinter } from './printer.js';
+const interactive = () => Boolean(process.stdin.isTTY && process.stdout.isTTY);
+const stdout = { write: (text) => void process.stdout.write(text) };
+/** Runs the checks, then (when allowed) the fixes. `printer` is null for --json. */
+export async function runHealth(env, printer, plan, checks = ALL_CHECKS, confirmFix = (q) => confirm({ message: q, default: true })) {
+    const run = new HealthRun(checks, env, printer?.hooks());
+    const found = await run.look();
+    const fixable = found.filter((r) => r.fixable);
+    let final = found;
+    let changed = false;
+    if (fixable.length) {
+        let go = plan.yes;
+        if (!go && plan.ask) {
+            printer?.plan(fixable);
+            go = await confirmFix(plan.question(fixable.length));
+        }
+        if (go) {
+            if (plan.yes)
+                printer?.plan(fixable);
+            final = await run.fix(found);
+            changed = true;
+        }
+        else
+            printer?.line('\nNothing was changed.');
+    }
+    return { found, final, summary: summarize(final), changed };
+}
+function quote(n, what) {
+    return n + ' ' + what + (n === 1 ? '' : 's');
+}
+/** `sandbox doctor` */
+export async function runDoctor(ctx) {
+    const health = new HealthService(ctx);
+    if (insideSandbox()) {
+        table(health.doctor());
+        return 0;
+    }
+    const json = ctx.options.json;
+    const printer = json ? null : new HealthPrinter(stdout);
+    printer?.title('Checking this PC, the install, your settings and the sandbox...');
+    const env = buildEnv(ctx);
+    const report = await runHealth(env, printer, {
+        yes: ctx.options.fix,
+        ask: !json && interactive(),
+        question: (n) => quote(n, 'problem') + ' can be fixed. Fix ' + (n === 1 ? 'it' : 'them') + ' now?',
+    });
+    const details = health.doctor();
+    if (printJson(ctx, { checks: report.final, summary: report.summary, details }))
+        return 0;
+    printer?.summary(report.final, report.summary);
+    const left = report.final.filter((r) => r.fixable).length;
+    if (left && !report.changed)
+        printer?.line('\n' + quote(left, 'problem') + ' can be fixed: run sandbox repair (or sandbox doctor --fix).');
+    printer?.line('\n' + 'Details');
+    table(details);
+    return 0;
+}
+/** `sandbox repair` for a loaded context. */
+export async function runRepair(ctx, configError = null) {
+    requireOnPc('repair');
+    const json = ctx.options.json;
+    const printer = json ? null : new HealthPrinter(stdout);
+    printer?.title('Checking this PC, the install, your settings and the sandbox...');
+    const env = buildEnv(ctx, configError);
+    const yes = ctx.options.yes;
+    const ask = !json && interactive();
+    const report = await runHealth(env, printer, {
+        yes,
+        ask,
+        question: (n) => 'Fix ' + (n === 1 ? 'this problem' : 'these ' + n + ' problems') + '?',
+    });
+    const when = new Date();
+    const log = writeRepairLog(ctx.storageRoot, logText({
+        when,
+        version: packageVersion(),
+        command: 'sandbox repair' + (yes ? ' --yes' : ''),
+        found: report.found,
+        final: report.final,
+        summary: report.summary,
+    }), when);
+    const stillFixable = report.final.filter((r) => r.fixable).length;
+    if (printJson(ctx, { checks: report.final, summary: report.summary, changed: report.changed, log })) {
+        return report.summary.needsYou ? 1 : 0;
+    }
+    printer?.summary(report.final, report.summary);
+    if (stillFixable && !ask && !yes)
+        printer?.line('\n' + quote(stillFixable, 'problem') + ' can be fixed: run sandbox repair --yes.');
+    printer?.line(log
+        ? '\nLog of what was found and changed: ' + log
+        : '\nNo log was written (the storage folder does not exist yet).');
+    return report.summary.needsYou ? 1 : 0;
+}
+/**
+ * Entry point that works even when the config file is broken (createContext would throw): falls back to the built-in
+ * defaults so the other checks still run, and reports the settings problem as a check of its own.
+ */
+export function repairCommand(packageRoot, entry, options) {
+    let ctx;
+    try {
+        ctx = createContext(packageRoot, entry, options);
+    }
+    catch (e) {
+        if (!(e instanceof UserError))
+            throw e;
+        const loaded = { config: structuredClone(DEFAULTS), configPath: null, base: userDir() };
+        const storageRoot = expandPath(loaded.config.storage.root, loaded.base);
+        return runRepair({
+            packageRoot,
+            entry,
+            options,
+            loaded,
+            storageRoot,
+            dataPath: path.join(storageRoot, 'data', loaded.config.storage.dataName),
+        }, e);
+    }
+    return runRepair(ctx);
+}

package/dist/cli/commands/repair/types.d.ts

@@ -1,11 +1,89 @@
 import type { UserError } from '../../../core/util/index.js';
+import type { InstallLayout, InstallRecord } from '../../../host/install/index.js';
+import type { SystemProbe } from '../../../host/health/index.js';
+import type { MachineFacts } from '../setup/facts.js';
+import type { Migration } from '../../../host/migrate/index.js';
 import type { Context } from '../context.js';
 export type RepairStatus = 'ok' | 'fixed' | 'needs-you' | 'warn' | 'skipped';
+/** The headings the output is grouped under, in the order they are shown. */
+export declare const CHECK_GROUPS: readonly ["This PC", "Install", "Data folder", "Settings", "Sandbox", "Agents & tools", "Network"];
+export type CheckGroup = (typeof CHECK_GROUPS)[number];
+/** The short form of a result (the menu shows these). */
 export interface RepairResult {
     name: string;
     status: RepairStatus;
     detail: string;
 }
+/** What a check's run() finds. */
+export interface Finding {
+    /** ok, a warning (nothing to do now), something you need to do, or not checked. */
+    status: 'ok' | 'warn' | 'needs-you' | 'skipped';
+    /** One line: what was found. */
+    detail: string;
+    /** What it means for you (shown when not ok). */
+    means?: string;
+    /** What to do about it yourself, when repair cannot (a command or a step). */
+    fix?: string;
+    /** What repair would change, in a few words ("remove 2 stale records"). Set only when fix() can mend this. */
+    plan?: string;
+    /** More lines shown under the plan when repair lists what it will change (a diff, the folders). */
+    lines?: string[];
+    /** Handed to fix() unchanged: what run() decided (the folders to remove ...). */
+    data?: unknown;
+}
+/** What a fix reports: what it changed. The before/after lines come from running the check again. */
+export interface FixOutcome {
+    done: string;
+}
+export interface Check {
+    /** Stable id (kebab-case): used in --json and the repair log. */
+    id: string;
+    group: CheckGroup;
+    /** Short label for the result line ("Data folder"). */
+    name: string;
+    /** "the data folder" in "Checking the data folder..."; the lower-cased name when left out. */
+    checking?: string;
+    /** Not shown at all when it returns false (an all-users check on another install). */
+    applies?: (env: RepairEnv) => boolean;
+    /** Slower checks (the network, Windows tools) say how long they may take; the default is 20 seconds. */
+    timeoutMs?: number;
+    /** look: do not even look while a sandbox runs (the folders are in use). fix: look, but fix only when none runs. */
+    needsIdle?: 'look' | 'fix';
+    run: (env: RepairEnv) => Finding | Promise<Finding>;
+    fix?: (env: RepairEnv, finding: Finding) => FixOutcome | Promise<FixOutcome>;
+}
+export interface CheckResult extends RepairResult {
+    id: string;
+    group: CheckGroup;
+    means?: string;
+    fix?: string;
+    plan?: string;
+    lines?: string[];
+    /** Repair can mend this one (a plan exists and the check has a fix). */
+    fixable: boolean;
+    timedOut?: boolean;
+    /** Milliseconds the look took. */
+    ms: number;
+    /** After a fix: what was changed, and what the check said before. */
+    applied?: {
+        done: string;
+        before: string;
+        after: string;
+    };
+    /** After a fix that failed: why. */
+    error?: string;
+}
+export interface Summary {
+    total: number;
+    ok: number;
+    fixed: number;
+    warn: number;
+    needsYou: number;
+    skipped: number;
+    /** Results repair could still mend. */
+    fixable: number;
+}
+/** Everything the checks read, in one place: injectable, so tests point it at temp folders. */
 export interface RepairEnv {
     ctx: Context;
     running: boolean;
@@ -13,14 +91,24 @@ export interface RepairEnv {
     storageRoot: string;
     toolsDir: string;
     configError: UserError | null;
+    /** The managed install this program runs from, or null (npm). */
+    layout: InstallLayout | null;
+    /** install.json of that install. */
+    record: InstallRecord | null;
+    /** %ProgramData%\AgentSandbox (the PC-wide folder of an all-users install). */
+    machineHome: string;
+    /** ~/.agent-sandbox: the settings file and what belongs to it. */
+    userDir: string;
+    /** The settings file in use (--config, AGENT_SANDBOX_CONFIG, else <userDir>\config.json). */
+    configFile: string;
+    /** The settings updates that exist (a test gives its own). */
+    migrations: readonly Migration[];
+    /** The user-scope install folder next to an all-users one (checked for leftovers). */
+    userInstallRoot: string | null;
+    system: SystemProbe;
+    now: () => number;
+    /** What `sandbox setup` learns about this PC (looked up once, the first time a check asks). */
+    facts: () => MachineFacts;
 }
-export interface RepairCheck {
-    name: string;
-    run: (env: RepairEnv) => Omit<RepairResult, 'name'>;
-}
-export declare function ok(detail: string): Omit<RepairResult, 'name'>;
 /** For fixes that must not touch folders a running sandbox may be using. */
-export declare const whileRunning: {
-    status: "skipped";
-    detail: string;
-};
+export declare const WHILE_RUNNING = "a sandbox is running and may be using it; run repair again once it is closed";

package/dist/cli/commands/repair/types.js

@@ -1,8 +1,12 @@
-export function ok(detail) {
-    return { status: 'ok', detail };
-}
+/** The headings the output is grouped under, in the order they are shown. */
+export const CHECK_GROUPS = [
+    'This PC',
+    'Install',
+    'Data folder',
+    'Settings',
+    'Sandbox',
+    'Agents & tools',
+    'Network',
+];
 /** For fixes that must not touch folders a running sandbox may be using. */
-export const whileRunning = {
-    status: 'skipped',
-    detail: 'a sandbox is running and may be using it; run repair again once it is closed',
-};
+export const WHILE_RUNNING = 'a sandbox is running and may be using it; run repair again once it is closed';

package/dist/cli/commands/resume.js

@@ -24,7 +24,7 @@ export async function resume(ctx) {
     const { storageRoot, dataPath, options } = ctx;
     const saved = new SessionLedger(storageRoot, dataPath).read();
     if (!saved) {
-        console.log('Nothing to reopen: no sandbox of this tool has been recorded yet.');
+        console.log('Nothing to resume. Start one: sandbox claude.');
         return 0;
     }
     // By hand, you asked for it. From the watcher, the setting decides.
@@ -32,7 +32,7 @@ export async function resume(ctx) {
     const life = new LifeRecord(storageRoot, dataPath).read();
     const reopening = !options.auto || shouldReopen(setting === 'ask' ? 'always' : setting, life, saved) === 'reopen';
     if (!options.auto && !saved.sessions.length) {
-        console.log('Nothing to reopen: no agent sessions were running in the last sandbox.');
+        console.log('Nothing to resume. Start one: sandbox claude.');
         return 0;
     }
     if (reopening && saved.sessions.length)

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

@@ -1,6 +1,2 @@
 export * from './attach.js';
-export * from './list.js';
-export * from './status.js';
 export * from './exec.js';
-export * from './control.js';
-export * from './window.js';

package/dist/cli/commands/sessions/index.js

@@ -1,9 +1,5 @@
-// Working with a running sandbox: attach, sessions, status, exec, restart, stop, show/hide. Each knows which project
-// you run it from (project.ts): attach and sessions put that project's sessions first, exec and db run in it, restart
-// restarts its sessions, stop warns about the other projects' sessions.
+// Working with a running sandbox: attach and exec. Each knows which project you run it from (projects/here.ts): attach
+// puts that project's sessions first, exec and db run in it. Status, sessions, restart, stop and show/hide are the
+// shared core's (src/app/features/sandbox and sessions).
 export * from './attach.js';
-export * from './list.js';
-export * from './status.js';
 export * from './exec.js';
-export * from './control.js';
-export * from './window.js';

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

@@ -1,2 +1,7 @@
 import { type Context } from '../context.js';
+/**
+ * First start on a PC without Windows Sandbox: offers to turn it on (the setup steps) instead of a bare error.
+ * Returns the setup's exit code, or undefined when there is nothing to offer (it is on, no terminal, or declined).
+ */
+export declare function offerSetupWhenOff(ctx: Context): Promise<number | undefined>;
 export declare function setup(ctx: Context): Promise<number>;

package/dist/cli/commands/setup/index.js

@@ -1,6 +1,10 @@
 // `sandbox setup`: checks this PC can run Windows Sandbox and offers to turn the feature on.
+import { spawnSync } from 'node:child_process';
 import { askYesNo } from '../../../core/prompt.js';
-import { fail } from '../../../core/util/index.js';
+import { fail, isWin } from '../../../core/util/index.js';
+import { insideSandbox, sandboxFeatureInstalled } from '../../../host/sandbox/index.js';
+import { refuseInSelfTest } from '../../../host/test-guard.js';
+import { SYSTEM } from '../../../shared/system.js';
 import { c, table } from '../../output/index.js';
 import { HealthService } from '../../services/index.js';
 import { ENABLE_COMMAND } from './facts.js';
@@ -12,6 +16,25 @@ const LABEL = {
 function print(checks) {
     table(checks.map((check) => [LABEL[check.status], check.name, check.detail]));
 }
+/** Seconds Windows waits before it restarts (shutdown /a cancels in that time). */
+const RESTART_DELAY_SECONDS = 30;
+/** After turning the feature on Windows must restart: offered, never done without a yes. */
+async function offerRestart() {
+    if (!(await askYesNo('Restart Windows now?')))
+        return;
+    refuseInSelfTest('restart Windows');
+    spawnSync(SYSTEM.shutdown(), ['/r', '/t', String(RESTART_DELAY_SECONDS)], { windowsHide: true });
+    console.log('Windows restarts in ' + RESTART_DELAY_SECONDS + ' seconds. To cancel: shutdown /a');
+}
+/**
+ * First start on a PC without Windows Sandbox: offers to turn it on (the setup steps) instead of a bare error.
+ * Returns the setup's exit code, or undefined when there is nothing to offer (it is on, no terminal, or declined).
+ */
+export async function offerSetupWhenOff(ctx) {
+    if (!isWin || insideSandbox() || sandboxFeatureInstalled() || !process.stdin.isTTY)
+        return undefined;
+    return (await askYesNo('Windows Sandbox is not turned on. Turn it on now?', true)) ? setup(ctx) : undefined;
+}
 export async function setup(ctx) {
     const health = new HealthService(ctx);
     health.assertWindows();
@@ -28,6 +51,7 @@ export async function setup(ctx) {
             console.log('Done. Restart Windows to finish, then run sandbox setup again.\n');
             checks = health.setupReport().checks;
             print(checks);
+            await offerRestart();
         }
         else
             console.log('To do it yourself, in an admin PowerShell run:\n  ' + ENABLE_COMMAND + '\nthen restart Windows.');

package/dist/cli/commands/shared-use.d.ts

@@ -21,9 +21,12 @@ export interface SandboxView {
 }
 /** For status and sessions: they work for anyone, and say whose sandbox this is. */
 export declare function lookAtSandbox(ctx: Context): SandboxView;
+/** Asks for a typed confirmation ("Type alice to confirm"); true when it was typed. */
+export type TypedConfirm = (prompt: string, expected: string) => Promise<boolean>;
 /**
  * For a command that acts on the running sandbox: refuses with the reason when this user may not, asks for the typed
- * confirmation when the rule wants one (--yes in a script), and returns the context to use.
+ * confirmation when the rule wants one (--yes in a script; `confirm` asks it, by default on the terminal), and returns
+ * the context to use.
  */
-export declare function useSharedSandbox(ctx: Context, action: OwnerAction | ((shared: Context) => OwnerAction)): Promise<Context>;
+export declare function useSharedSandbox(ctx: Context, action: OwnerAction | ((shared: Context) => OwnerAction), confirm?: TypedConfirm): Promise<Context>;
 export {};

package/dist/cli/commands/shared-use.js

@@ -47,11 +47,18 @@ export function lookAtSandbox(ctx) {
         return { ctx: borrowedContext(ctx, owner), line, limited: false, owner };
     return { ctx, line, limited: owner.kind !== 'mine' && owner.kind !== 'none', owner };
 }
+/** On the terminal: no terminal fails and says how to do it in a script. */
+const terminalTypedConfirm = async (prompt, expected) => {
+    if (!(process.stdin.isTTY && process.stdout.isTTY))
+        fail(prompt + ' It was not stopped.', 'In a script, add --yes to do it anyway.');
+    return askTyped(prompt, expected);
+};
 /**
  * For a command that acts on the running sandbox: refuses with the reason when this user may not, asks for the typed
- * confirmation when the rule wants one (--yes in a script), and returns the context to use.
+ * confirmation when the rule wants one (--yes in a script; `confirm` asks it, by default on the terminal), and returns
+ * the context to use.
  */
-export async function useSharedSandbox(ctx, action) {
+export async function useSharedSandbox(ctx, action, confirm = terminalTypedConfirm) {
     const owner = ownerNow();
     if (!owner || owner.kind === 'mine' || owner.kind === 'none')
         return ctx;
@@ -59,11 +66,7 @@ export async function useSharedSandbox(ctx, action) {
     const rule = ownerRule(owner, typeof action === 'function' ? action(target) : action);
     if (rule.kind === 'refuse')
         return fail(rule.reason, rule.fix);
-    if (rule.kind === 'confirm' && !ctx.options.yes) {
-        if (!(process.stdin.isTTY && process.stdout.isTTY))
-            fail(rule.prompt + ' It was not stopped.', 'In a script, add --yes to do it anyway.');
-        if (!(await askTyped(rule.prompt, rule.expected)))
-            fail('Nothing changed.');
-    }
+    if (rule.kind === 'confirm' && !ctx.options.yes && !(await confirm(rule.prompt, rule.expected)))
+        fail('Nothing changed.');
     return target;
 }

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

@@ -0,0 +1,3 @@
+import type { Context } from '../context.js';
+/** `sandbox storage contained [status|on|off]`. */
+export declare function contained(ctx: Context): Promise<number>;

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

@@ -0,0 +1,179 @@
+// `sandbox storage contained on|off|status` (beta): keep the data set's tools, state and logs in a
+// disk image that is mounted only while a sandbox runs. The work is in host/storage/contained; this file asks, shows
+// size and time, and prints.
+import fs from 'node:fs';
+import { userConfigPath } from '../../../core/config/index.js';
+import { humanBytes } from '../../../core/disk.js';
+import { askRequired } from '../../../core/prompt.js';
+import { fail } from '../../../core/util/index.js';
+import { isSandboxRunning, realContainedDeps } from '../../../host/sandbox/index.js';
+import { assertTargetsFree, containedAvailability, ContainedStorage, describeDuration, describeSize, planTransfer, runTransfer, setStateOf, StateFile, writeContainedSetting, } from '../../../host/storage/index.js';
+import { c, printJson, working } from '../../output/index.js';
+const BETA = 'Beta, and not yet tested on a real PC. ';
+function storageFor(ctx) {
+    const { config } = ctx.loaded;
+    return new ContainedStorage(realContainedDeps(ctx.storageRoot, config.storage.containedMaxGb), config.storage.dataName);
+}
+function requireAvailable() {
+    const check = containedAvailability();
+    if (!check.available)
+        fail('Contained storage cannot be used: ' + check.reasons.join(' '), check.fixes.join(' '));
+}
+function requireNoSandbox() {
+    if (isSandboxRunning())
+        fail('A sandbox is running.', 'Close it (sandbox stop) first: the folders in the image are in use.');
+}
+async function status(ctx) {
+    const storage = storageFor(ctx);
+    const check = containedAvailability();
+    const state = new StateFile(storage.paths).read();
+    const record = setStateOf(state, storage.set);
+    const reality = check.available && storage.imageExists() ? await storage.reality() : null;
+    const answer = {
+        setting: ctx.loaded.config.storage.contained,
+        maxGb: ctx.loaded.config.storage.containedMaxGb,
+        available: check.available,
+        reasons: check.reasons,
+        image: storage.paths.image,
+        imageExists: storage.imageExists(),
+        imageBytes: reality?.imageBytes ?? null,
+        mountFolder: storage.paths.mount,
+        recordedMounted: record.mounted,
+        holders: record.holders.length,
+        mountedNow: reality?.mountIsMountPoint ?? null,
+    };
+    if (printJson(ctx, answer))
+        return 0;
+    console.log(c.yellow('Contained storage (beta, untested on a real PC)'));
+    console.log('  setting:      storage.contained = ' + answer.setting + ' (limit ' + answer.maxGb + ' GB)');
+    console.log('  this PC:      ' +
+        (check.available ? 'can use it' : 'cannot use it: ' + check.reasons.join(' ') + ' ' + check.fixes.join(' ')));
+    console.log('  image:        ' +
+        answer.image +
+        (answer.imageExists ? ' (' + humanBytes(answer.imageBytes ?? 0) + ' on disk)' : ' (not made yet)'));
+    console.log('  mount folder: ' + answer.mountFolder);
+    if (reality)
+        console.log('  mounted now:  ' +
+            (reality.mountIsMountPoint ? 'yes' : 'no') +
+            (record.mounted !== reality.mountIsMountPoint
+                ? ' (the record says ' + (record.mounted ? 'yes' : 'no') + '; sandbox doctor looks into it)'
+                : ''));
+    console.log('\nTurn it on with: sandbox storage contained on   Turn it off with: sandbox storage contained off');
+    return 0;
+}
+function printPlan(plan, to) {
+    for (const f of plan.folders)
+        console.log('  ' + f.name + ': ' + describeSize(f.measured));
+    console.log('  total: ' + describeSize(plan.total) + ' to ' + to);
+    console.log('  time:  about ' + describeDuration(plan.estimate.seconds) + ' (copied, then the originals are removed)');
+    if (!plan.estimate.fits)
+        fail('Not enough free space for the copy.', 'Free some space on that drive and try again.');
+}
+async function turnOn(ctx) {
+    requireAvailable();
+    requireNoSandbox();
+    const storage = storageFor(ctx);
+    const { config } = ctx.loaded;
+    const configFile = ctx.loaded.configPath ?? userConfigPath();
+    console.log(c.yellow(BETA + 'Contained storage keeps the sandbox tools, state and logs in one disk image file.'));
+    console.log('  image:  ' + storage.paths.image + (storage.imageExists() ? ' (exists, it is used as it is)' : ''));
+    console.log('  limit:  ' + config.storage.containedMaxGb + ' GB (storage.containedMaxGb; the file grows only as it fills)');
+    console.log('  Windows asks for permission to mount it each time a sandbox starts (and once when it closes).');
+    if (!ctx.options.yes &&
+        !(await askRequired('Turn contained storage on?', 'Add --yes to turn it on without asking.', true)))
+        return fail('Nothing was changed.', 'Run sandbox storage contained on when you want it.');
+    const mount = await working('Making and mounting the image (Windows asks for permission)', () => storage.acquire({ id: 'cli', pid: process.pid }, { create: true }));
+    try {
+        const plan = planTransfer(ctx.dataPath, mount, ctx.storageRoot);
+        if (plan.folders.length > 0) {
+            console.log('\nThese folders hold your tools, state and logs now:');
+            printPlan(plan, 'the image');
+            assertTargetsFree(plan);
+            const move = ctx.options.yes || (await askRequired('Move them into the image?', 'Add --yes to move without asking.', true));
+            if (move) {
+                let line = 'Copying';
+                const result = await working(() => line, () => runTransfer(plan, ctx.dataPath, (p) => {
+                    line = 'Copying: ' + p.files.toLocaleString('en-US') + ' files, ' + humanBytes(p.bytes);
+                }));
+                console.log('Moved ' + result.files.toLocaleString('en-US') + ' files into the image.');
+                for (const note of result.notes)
+                    console.log(c.yellow(note));
+            }
+            else
+                console.log('They stay where they are and are not used: tools are downloaded again into the image. Delete them later with sandbox data clean.');
+        }
+        writeContainedSetting(configFile, 'vhdx');
+    }
+    finally {
+        const done = await working('Dismounting the image (Windows asks for permission)', () => storage.release('cli'));
+        if (!done.dismounted)
+            console.log(c.yellow('The image stays mounted (' + (done.note ?? '') + '). sandbox repair dismounts it.'));
+    }
+    console.log('Contained storage is on. sandbox launch mounts the image first.');
+    return 0;
+}
+async function turnOff(ctx) {
+    requireAvailable();
+    requireNoSandbox();
+    const storage = storageFor(ctx);
+    const configFile = ctx.loaded.configPath ?? userConfigPath();
+    console.log(c.yellow(BETA + 'Turning contained storage off moves the files back into plain folders.'));
+    if (!storage.imageExists()) {
+        writeContainedSetting(configFile, 'off');
+        console.log('There is no image, so there was nothing to move. Contained storage is off.');
+        return 0;
+    }
+    const mount = await working('Mounting the image (Windows asks for permission)', () => storage.acquire({ id: 'cli', pid: process.pid }));
+    let moved = false;
+    try {
+        const plan = planTransfer(mount, ctx.dataPath, ctx.dataPath);
+        if (plan.folders.length > 0) {
+            console.log('\nIn the image:');
+            printPlan(plan, ctx.dataPath);
+            assertTargetsFree(plan);
+            if (!ctx.options.yes &&
+                !(await askRequired('Move them back out of the image?', 'Add --yes to move without asking.', true)))
+                return fail('Nothing was moved.', 'Contained storage is still on.');
+            let line = 'Copying';
+            const result = await working(() => line, () => runTransfer(plan, mount, (p) => {
+                line = 'Copying: ' + p.files.toLocaleString('en-US') + ' files, ' + humanBytes(p.bytes);
+            }));
+            console.log('Moved ' + result.files.toLocaleString('en-US') + ' files back.');
+            for (const note of result.notes)
+                console.log(c.yellow(note));
+        }
+        writeContainedSetting(configFile, 'off');
+        moved = true;
+    }
+    finally {
+        const done = await working('Dismounting the image (Windows asks for permission)', () => storage.release('cli'));
+        if (!done.dismounted)
+            console.log(c.yellow('The image stays mounted (' + (done.note ?? '') + '). sandbox repair dismounts it.'));
+        else if (!moved)
+            console.log('The image was dismounted; contained storage is still on.');
+    }
+    console.log('Contained storage is off: tools, state and logs are plain folders in ' + ctx.dataPath + '.');
+    const bytes = fs.statSync(storage.paths.image).size;
+    if (!ctx.options.yes &&
+        (await askRequired('Delete the image file now (' + humanBytes(bytes) + ')? Everything in it was moved out.', 'Answer no to keep it.', false))) {
+        await storage.deleteImage();
+        console.log('Deleted ' + storage.paths.image + '.');
+    }
+    else
+        console.log('The image file is kept: ' + storage.paths.image + ' (delete it yourself when you are sure).');
+    return 0;
+}
+/** `sandbox storage contained [status|on|off]`. */
+export function contained(ctx) {
+    const [, mode = 'status'] = ctx.options.positionals;
+    switch (mode) {
+        case 'status':
+            return status(ctx);
+        case 'on':
+            return turnOn(ctx);
+        case 'off':
+            return turnOff(ctx);
+        default:
+            return Promise.resolve(fail('Unknown action "' + mode + '" for contained storage.', 'Use: sandbox storage contained on, off or status'));
+    }
+}

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

@@ -0,0 +1,2 @@
+export { storage, storageBusy, performMove } from './storage.js';
+export { storageBeforeCommand } from './offer.js';

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

@@ -0,0 +1,2 @@
+export { storage, storageBusy, performMove } from './storage.js';
+export { storageBeforeCommand } from './offer.js';

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

@@ -0,0 +1,3 @@
+import { type Context } from '../context.js';
+/** Before a command (after the saved settings are up to date). A failed move never stops the command. */
+export declare function storageBeforeCommand(ctx: Context, command: string): Promise<void>;