windows-development-sandbox 0.0.0-stage → 1.0.5

package/dist/cli/commands/repair.js

@@ -0,0 +1,332 @@
+// `sandbox repair`: finds and fixes common problems. Each check is a small function in CHECKS; it either confirms
+// all is well (OK), fixes the problem itself (FIXED), or says what you need to do (NEEDS YOU). Nothing under the data
+// folder is followed through a link, and toolchain/run-state fixes wait until no sandbox is running.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import _ from 'lodash';
+import { z } from 'zod';
+import { DEFAULTS, loadConfig, userDir } from '../../core/config.js';
+import { assertNoLinks, dirExists, errMsg, expandPath, fileExists, isLink, isWin, removeLink, UserError } from '../../core/util.js';
+import { resetRunDir } from '../../host/channel.js';
+import { isSandboxRunning, sandboxFeatureInstalled } from '../../host/platform.js';
+import { listSessions, runPaths, scanRequests } from '../../shared/rundir.js';
+import { createContext, printJson, table } from './context.js';
+import { humanBytes, removeTree } from './data.js';
+const GB = 1024 ** 3;
+const LABEL = { ok: 'OK', fixed: 'FIXED', 'needs-you': 'NEEDS YOU', warn: 'WARNING', skipped: 'SKIPPED' };
+const ok = (detail) => ({ status: 'ok', detail });
+const whileRunning = { status: 'skipped', detail: 'a sandbox is running and may be using it; run repair again once it is closed' };
+const rel = (root, p) => path.relative(root, p) || '.';
+// ---- pure helpers (exported for tests) ----
+/** Interrupted downloads and copies: `<name>.staging-<hex>` and `node-staging`, in tools\ and one folder down (tools\go\1.23.staging-ab12). */
+export const findStagingLeftovers = (toolsDir) => {
+    const isStaging = (name) => /\.staging-[0-9a-f]+$/i.test(name) || name.toLowerCase() === 'node-staging';
+    const realChildren = (dir) => (dirExists(dir) && !isLink(dir) ? fs.readdirSync(dir).map((n) => path.join(dir, n)) : []);
+    return realChildren(toolsDir).flatMap((p) => (isStaging(path.basename(p)) ? [p] : isLink(p) ? [] : realChildren(p).filter((c) => isStaging(path.basename(c)))));
+};
+export const TOOL_RULES = [
+    { folder: 'nvm', exe: ['nvm.exe'] },
+    { folder: 'nvm', exe: ['node.exe'], versions: true, match: /^v\d+\.\d+\.\d+$/ },
+    { folder: 'node', exe: ['node.exe'] },
+    { folder: 'git', exe: ['bin', 'bash.exe'] },
+    { folder: 'dotnet', exe: ['dotnet.exe'] },
+    { folder: 'go', exe: ['bin', 'go.exe'], versions: true },
+    { folder: 'java', exe: ['bin', 'java.exe'], versions: true },
+    { folder: 'python', exe: ['python.exe'], versions: true },
+];
+/** Toolchain folders that exist but lack their main program (an install that stopped half way). Never enters links. */
+export const findHalfInstalled = (toolsDir, rules = TOOL_RULES) => {
+    const realDir = (p) => dirExists(p) && !isLink(p);
+    const staging = (name) => /\.staging-[0-9a-f]+$/i.test(name) || name.toLowerCase() === 'node-staging';
+    return rules.flatMap((rule) => {
+        const base = path.join(toolsDir, rule.folder);
+        if (!realDir(base))
+            return [];
+        const folders = rule.versions
+            ? fs.readdirSync(base).filter((n) => !staging(n) && (!rule.match || rule.match.test(n))).map((n) => path.join(base, n)).filter(realDir)
+            : [base];
+        return folders.filter((f) => !fileExists(path.join(f, ...rule.exe))).map((f) => ({ path: f, missing: path.join(...rule.exe) }));
+    });
+};
+/**
+ * Every link or junction under `root` (the links themselves; nothing behind them is visited). Before descending into
+ * a folder its real path must still be inside root: a folder swapped for a junction between two looks is not followed.
+ */
+export const findLinks = (root) => {
+    if (isLink(root))
+        return [root];
+    const real = (p) => { try {
+        return fs.realpathSync.native(p).toLowerCase();
+    }
+    catch {
+        return '';
+    } };
+    const top = real(root);
+    const inside = (p) => { const r = real(p); return r !== '' && (r === top || r.startsWith(top + path.sep)); };
+    const walk = (dir) => {
+        if (!inside(dir))
+            return [];
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        return entries.flatMap((d) => {
+            const p = path.join(dir, d.name);
+            if (d.isSymbolicLink() || isLink(p))
+                return [p];
+            return d.isDirectory() ? walk(p) : [];
+        });
+    };
+    return dirExists(root) ? walk(root) : [];
+};
+const ResolvedVersions = z.record(z.string(), z.unknown());
+/** tools\resolved-versions.json is a JSON object (anything else makes the guest stumble). */
+export const resolvedVersionsValid = (text) => {
+    try {
+        return ResolvedVersions.safeParse(JSON.parse(text.replace(/^/, ''))).success;
+    }
+    catch {
+        return false;
+    }
+};
+const NpmList = z.object({ dependencies: z.record(z.string(), z.unknown()).optional() });
+/** Package names from `npm ls -g --json`; [] when the output is not what npm prints. */
+export const globalPackages = (json) => {
+    try {
+        return Object.keys(NpmList.parse(JSON.parse(json)).dependencies ?? {});
+    }
+    catch {
+        return [];
+    }
+};
+const Pid = z.coerce.number().int().positive();
+export const pidAlive = (pid) => { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch (e) {
+    return e.code === 'EPERM';
+} };
+/** Sync-watcher pid files (storage\run\watcher-*.pid) whose process is gone (or whose content is not a pid). */
+export const deadPidFiles = (runDir, alive = pidAlive) => (dirExists(runDir) ? fs.readdirSync(runDir) : [])
+    .filter((n) => /^watcher-.*\.pid$/i.test(n))
+    .map((n) => path.join(runDir, n))
+    .filter((f) => { try {
+    const pid = Pid.safeParse(fs.readFileSync(f, 'utf8').trim());
+    return !pid.success || !alive(pid.data);
+}
+catch {
+    return false;
+} });
+// ---- checks ----
+/** Fails (throws) unless every folder from the data folder to `p` is real. */
+const guard = (env, p) => assertNoLinks(path.dirname(env.dataPath), p);
+const CHECKS = [
+    {
+        name: 'Config file',
+        run: (env) => (env.configError
+            ? { status: 'needs-you', detail: env.configError.message + (env.configError.fix ? ' ' + env.configError.fix : '') + ' (repair never rewrites your config; built-in defaults were used for the other checks.)' }
+            : ok(env.ctx.loaded.configPath ? env.ctx.loaded.configPath + ' is valid.' : 'none; using the built-in defaults.')),
+    },
+    {
+        name: 'Windows Sandbox feature',
+        run: () => (sandboxFeatureInstalled() ? ok('enabled.') : { status: 'needs-you', detail: (isWin ? 'Windows Sandbox is not turned on.' : 'This is not Windows.') + ' Run: sandbox setup (it checks this PC and offers to turn it on).' }),
+    },
+    {
+        name: 'Links in the data folder',
+        run: (env) => {
+            if (isLink(env.dataPath))
+                return { status: 'needs-you', detail: env.dataPath + ' itself is a link or junction. agent-sandbox refuses to work through links; point storage.root at the real folder instead (sandbox config path).' };
+            // A running sandbox can swap folders for links while we look; only check a stopped one.
+            if (env.running)
+                return whileRunning;
+            const links = findLinks(env.dataPath);
+            if (!links.length)
+                return ok('none (nothing in ' + env.dataPath + ' points elsewhere).');
+            // A link here can only have been made inside the sandbox; it could point at this PC's own files. Remove the link
+            // itself, and only if every folder above it is still real.
+            for (const link of links) {
+                guard(env, path.dirname(link));
+                removeLink(link);
+            }
+            return { status: 'fixed', detail: 'removed ' + links.length + ' link(s)/junction(s) the sandbox created, without following them: ' + links.map((l) => rel(env.dataPath, l)).join(', ') };
+        },
+    },
+    {
+        name: 'Sandbox run state',
+        run: (env) => {
+            if (env.running)
+                return ok('a sandbox is running; its state is in use.');
+            if (isLink(runPaths(env.dataPath).run)) {
+                resetRunDir(env.dataPath);
+                return { status: 'fixed', detail: 'the run folder was a link; removed the link itself.' };
+            }
+            // The last sandbox's status file is normal after it closes; sessions still marked running or unanswered requests are not.
+            const ghosts = listSessions(env.dataPath).filter((s) => s.phase === 'running' || s.phase === 'starting').length;
+            const requests = scanRequests(env.dataPath);
+            const pending = requests.valid.length + requests.invalid.length;
+            if (!ghosts && !pending)
+                return ok('clean.');
+            resetRunDir(env.dataPath);
+            return { status: 'fixed', detail: 'no sandbox is running, but ' + _.compact([ghosts && ghosts + ' session(s) were still marked running', pending && pending + ' request(s) were never answered']).join(' and ') + '; cleared the run state so status/attach do not show ghosts.' };
+        },
+    },
+    {
+        name: 'Hidden-window state',
+        run: (env) => {
+            const file = path.join(env.storageRoot, 'run', 'hidden-windows.json');
+            if (!fs.existsSync(file) && !isLink(file))
+                return ok('clean.');
+            if (env.running)
+                return ok('a sandbox is running; kept.');
+            fs.rmSync(file, { force: true });
+            return { status: 'fixed', detail: 'removed the saved hidden-window list from a sandbox that is no longer running.' };
+        },
+    },
+    {
+        name: 'Sync watcher',
+        run: (env) => {
+            const dead = deadPidFiles(path.join(env.storageRoot, 'run'));
+            if (!dead.length)
+                return ok('no stale watcher records.');
+            for (const f of dead)
+                fs.rmSync(f, { force: true });
+            return { status: 'fixed', detail: 'removed ' + dead.length + ' record(s) of a history sync watcher that is no longer running (the next launch starts a new one).' };
+        },
+    },
+    {
+        name: 'Interrupted downloads',
+        run: (env) => {
+            if (env.running)
+                return whileRunning;
+            guard(env, env.toolsDir);
+            const found = findStagingLeftovers(env.toolsDir);
+            if (!found.length)
+                return ok('none.');
+            for (const p of found)
+                removeTree(p, env.dataPath);
+            return { status: 'fixed', detail: 'removed ' + found.length + ' half-finished download/copy folder(s): ' + found.map((p) => rel(env.toolsDir, p)).join(', ') };
+        },
+    },
+    {
+        name: 'Half-installed toolchains',
+        run: (env) => {
+            if (env.running)
+                return whileRunning;
+            guard(env, env.toolsDir);
+            const found = findHalfInstalled(env.toolsDir);
+            if (!found.length)
+                return ok('every toolchain folder has its program.');
+            for (const f of found)
+                removeTree(f.path, env.dataPath);
+            return { status: 'fixed', detail: 'removed ' + found.map((f) => rel(env.toolsDir, f.path) + ' (no ' + f.missing + ')').join(', ') + '; the next sandbox reinstalls them.' };
+        },
+    },
+    {
+        name: 'Resolved versions cache',
+        run: (env) => {
+            const file = path.join(env.toolsDir, 'resolved-versions.json');
+            if (!fs.existsSync(file) && !isLink(file))
+                return ok('not created yet.');
+            if (env.running)
+                return whileRunning;
+            guard(env, env.toolsDir);
+            if (isLink(file)) {
+                removeLink(file);
+                return { status: 'fixed', detail: 'removed a link in place of tools\\resolved-versions.json.' };
+            }
+            if (fs.statSync(file).size < 4 * 1024 * 1024 && resolvedVersionsValid(fs.readFileSync(file, 'utf8')))
+                return ok('valid.');
+            fs.rmSync(file, { force: true });
+            return { status: 'fixed', detail: 'tools\\resolved-versions.json was damaged; removed it (versions are looked up again on the next start).' };
+        },
+    },
+    {
+        name: 'Installed packages',
+        run: () => {
+            const npmCli = path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+            if (!fileExists(npmCli))
+                return { status: 'skipped', detail: 'npm not found next to this Node (' + npmCli + ').' };
+            // cwd = Node's own folder: npm reads .npmrc from the current folder, which could be a sandbox-writable workspace.
+            const result = spawnSync(process.execPath, [npmCli, 'ls', '-g', '--json', '--depth=0'], { cwd: path.dirname(process.execPath), encoding: 'utf8', windowsHide: true, timeout: 60000, maxBuffer: 16 * 1024 * 1024 });
+            const names = globalPackages(result.stdout ?? '');
+            if (!names.length)
+                return { status: 'skipped', detail: 'could not read the global npm packages.' };
+            if (names.includes('agent-sandbox') && names.includes('windows-development-sandbox'))
+                return { status: 'needs-you', detail: 'the old agent-sandbox package is still installed next to windows-development-sandbox, and their commands clash. Run: npm uninstall -g agent-sandbox' };
+            return ok(names.includes('agent-sandbox') ? 'agent-sandbox installed (the old name; fine on its own).' : 'no old agent-sandbox package.');
+        },
+    },
+    {
+        name: 'Free disk',
+        run: (env) => {
+            let at = path.resolve(env.storageRoot);
+            while (!fs.existsSync(at) && path.dirname(at) !== at)
+                at = path.dirname(at);
+            let free;
+            try {
+                const s = fs.statfsSync(at);
+                free = s.bavail * s.bsize;
+            }
+            catch {
+                return { status: 'skipped', detail: 'could not check the drive of ' + env.storageRoot };
+            }
+            if (free >= 20 * GB)
+                return ok(humanBytes(free) + ' free.');
+            return { status: 'warn', detail: humanBytes(free) + ' free on the drive of ' + env.storageRoot + (free < 5 * GB ? ': toolchains need several GB.' : ': getting low.') + ' See what is stored with: sandbox data, and free space with: sandbox data clean <target>' };
+        },
+    },
+];
+/** Runs every check in order; a check that throws is reported, never stops the rest. */
+export const runChecks = (env, checks = CHECKS) => checks.map((check) => {
+    try {
+        return { name: check.name, ...check.run(env) };
+    }
+    catch (e) {
+        return { name: check.name, status: 'needs-you', detail: 'check failed: ' + errMsg(e) + (e instanceof UserError && e.fix ? ' ' + e.fix : '') };
+    }
+});
+export const repair = (ctx, configError = null) => {
+    const env = { ctx, running: isSandboxRunning(), dataPath: ctx.dataPath, storageRoot: ctx.storageRoot, toolsDir: path.join(ctx.dataPath, 'tools'), configError };
+    // Re-check the config file even when the context loaded (it may have been edited since, or come from --config).
+    if (!env.configError) {
+        try {
+            loadConfig(ctx.options.config);
+        }
+        catch (e) {
+            if (e instanceof UserError)
+                env.configError = e;
+            else
+                throw e;
+        }
+    }
+    const results = runChecks(env);
+    if (printJson(ctx, results))
+        return results.some((r) => r.status === 'needs-you') ? 1 : 0;
+    table(results.map((r) => [LABEL[r.status], r.name, r.detail]));
+    const counts = _.countBy(results, 'status');
+    console.log('\n' + (counts['needs-you'] ? counts['needs-you'] + ' thing(s) need you (see NEEDS YOU above).' : 'All good' + (counts.fixed ? ': fixed ' + counts.fixed + ' problem(s).' : '.')));
+    return counts['needs-you'] ? 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 config problem as the first check.
+ */
+export const 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 repair({ packageRoot, entry, options, loaded, storageRoot, dataPath: path.join(storageRoot, 'data', loaded.config.storage.dataName) }, e);
+    }
+    return repair(ctx);
+};

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

@@ -0,0 +1,11 @@
+import { type Context } from './context.js';
+export declare const attach: (ctx: Context) => Promise<number>;
+export declare const sessions: (ctx: Context) => Promise<number>;
+export declare const status: (ctx: Context) => Promise<number>;
+export declare const exec: (ctx: Context) => Promise<number>;
+/** `sandbox db`: runs the sandbox's own `sbx-db`, which knows this project's database versions and ports. */
+export declare const db: (ctx: Context) => Promise<number>;
+export declare const restart: (ctx: Context) => Promise<number>;
+export declare const stop: (ctx: Context) => Promise<number>;
+export declare const show: (ctx: Context) => number;
+export declare const hide: (ctx: Context) => Promise<number>;

package/dist/cli/commands/sessions.js

@@ -0,0 +1,113 @@
+// Working with a running sandbox: attach, sessions, status, exec, restart, stop, show/hide.
+import _ from 'lodash';
+import { activeAccount } from '../../host/accounts.js';
+import { execInSandbox, pickSession, pingSandbox, restartSessions, currentSessions, runningSessions, sessionViewers, waitForReady } from '../../host/channel.js';
+import { isSandboxRunning } from '../../host/platform.js';
+import { repoFindings } from '../../host/repo-guard.js';
+import { hideSandboxWindow, showSandboxWindow } from '../../host/window.js';
+import { listSessions, readSandboxStatus } from '../../shared/rundir.js';
+import { watcherRunning } from '../../sync/watcher.js';
+import { errMsg, fail, safeText, sleep } from '../../core/util.js';
+import { currentGuestDir, printJson, requireRunning, sandboxAlive, table } from './context.js';
+import { attachHere } from './launch.js';
+export const attach = async (ctx) => {
+    requireRunning('Start one with: sandbox claude --terminal');
+    await waitForReady(ctx.dataPath, null, sandboxAlive);
+    const id = ctx.options.positionals[0];
+    if (!id && runningSessions(ctx.dataPath).length === 0)
+        await sleep(1500);
+    return attachHere(ctx, pickSession(ctx.dataPath, id));
+};
+const viewerText = (v) => (v === undefined ? '-' : v === null ? 'unknown (older session)' : v.remote + ' here, ' + (v.viewers - v.remote) + ' in sandbox');
+// harness, cwd and times are written by the sandbox: printed through safeText.
+const sessionRow = (s) => [s.id, safeText(s.harness), s.phase + (s.exitCode !== undefined ? ' (' + s.exitCode + ')' : ''), viewerText(s.viewers), safeText(s.cwd), safeText(new Date(s.startedAt).toLocaleTimeString())];
+export const sessions = async (ctx) => {
+    // Who is attached comes from each session itself, so a terminal that was closed is never counted.
+    const live = isSandboxRunning();
+    // Only this sandbox's sessions are asked (and at most MAX_QUERIED_SESSIONS): the sandbox writes these files.
+    const ask = new Set(live ? currentSessions(ctx.dataPath).map((s) => s.id) : []);
+    const list = await Promise.all(listSessions(ctx.dataPath).map(async (s) => (ask.has(s.id) ? { ...s, viewers: await sessionViewers(s) } : s)));
+    if (printJson(ctx, list.map((s) => _.omit(s, 'attach'))))
+        return 0;
+    if (list.length === 0)
+        console.log('No sessions.');
+    else
+        table([['ID', 'AGENT', 'STATE', 'ATTACHED', 'FOLDER', 'STARTED'], ...list.map(sessionRow)]);
+    return 0;
+};
+export const status = async (ctx) => {
+    const running = isSandboxRunning();
+    const sandbox = readSandboxStatus(ctx.dataPath);
+    const findings = repoFindings(ctx.dataPath);
+    const daemon = running && sandbox?.phase === 'ready' ? await pingSandbox(ctx.dataPath, sandboxAlive).then((r) => r.message, (e) => 'no answer (' + errMsg(e) + ')') : '-';
+    const info = {
+        running, phase: running ? sandbox?.phase ?? 'unknown' : 'stopped', message: sandbox?.message, workspace: sandbox?.workspaceHost, headless: sandbox?.headless,
+        daemon, account: activeAccount(ctx.dataPath), sessions: running ? runningSessions(ctx.dataPath).length : 0, syncWatcher: watcherRunning(ctx.dataPath),
+        repoGuard: findings.length ? findings.map((x) => x.kind + ': ' + x.detail).join('; ') : 'nothing from the sandbox needed neutralising',
+    };
+    if (!printJson(ctx, info))
+        table(Object.entries(info).map(([k, v]) => [_.startCase(k), safeText(String(v ?? '-'))]));
+    return 0;
+};
+export const exec = async (ctx) => {
+    const command = [...ctx.options.positionals, ...ctx.options.passthrough];
+    if (command.length === 0)
+        fail('No command given.', 'Usage: sandbox exec [--timeout <s>] -- <command> [args...]');
+    requireRunning();
+    const ready = await waitForReady(ctx.dataPath, null, sandboxAlive);
+    const result = await execInSandbox(ctx.dataPath, command, currentGuestDir(ctx, ready.workspaceHost, ready.guestWorkspace), ctx.options.timeout, sandboxAlive);
+    if (!printJson(ctx, result)) {
+        if (result.stdout)
+            process.stdout.write(safeText(result.stdout));
+        if (result.stderr)
+            process.stderr.write(safeText(result.stderr));
+        if (!result.ok && !result.stdout && !result.stderr)
+            console.error(result.message);
+    }
+    return result.exitCode ?? 1;
+};
+/** `sandbox db`: runs the sandbox's own `sbx-db`, which knows this project's database versions and ports. */
+export const db = async (ctx) => {
+    const [action = 'list', name] = ctx.options.positionals;
+    if (action !== 'list' && !name)
+        fail('Which database?', 'Usage: sandbox db ' + action + ' <postgres|mysql|mongodb|redis|dynamodb>');
+    requireRunning('Start one with: sandbox start --database <name>');
+    const ready = await waitForReady(ctx.dataPath, null, sandboxAlive);
+    // Starting can download the database the first time.
+    const result = await execInSandbox(ctx.dataPath, ['sbx-db', action, ...(name ? [name] : [])], ready.guestWorkspace, 1800, sandboxAlive);
+    if (result.stdout)
+        process.stdout.write(safeText(result.stdout));
+    if (result.stderr)
+        process.stderr.write(safeText(result.stderr));
+    if (!result.ok && !result.stdout && !result.stderr)
+        console.error(result.message);
+    return result.exitCode ?? 1;
+};
+export const restart = async (ctx) => {
+    requireRunning();
+    console.log((await restartSessions(ctx.dataPath, ctx.options.harness ?? null, sandboxAlive)).message);
+    return 0;
+};
+export const stop = async (ctx) => {
+    if (!isSandboxRunning()) {
+        console.log('No Windows Sandbox is running.');
+        return 0;
+    }
+    const sandbox = readSandboxStatus(ctx.dataPath) ?? fail('This sandbox was not started by this tool.', 'Close its window instead.');
+    await execInSandbox(ctx.dataPath, ['C:\\Windows\\System32\\shutdown.exe', '/s', '/t', '2'], sandbox.guestWorkspace, 30, sandboxAlive);
+    console.log('Sandbox is shutting down; history and claude-mem sync back when it closes.');
+    return 0;
+};
+export const show = (ctx) => {
+    requireRunning();
+    if (!showSandboxWindow(ctx.storageRoot))
+        fail('Could not find the Windows Sandbox window.', 'It may still be starting; try again in a few seconds.');
+    return 0;
+};
+export const hide = async (ctx) => {
+    requireRunning();
+    if (!(await hideSandboxWindow(ctx.storageRoot, 5)))
+        fail('Could not find a visible Windows Sandbox window.', 'It may already be hidden (sbx-show brings it back).');
+    console.log('Sandbox window hidden. Bring it back with: sbx-show');
+    return 0;
+};

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

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { type Context } from './context.js';
+export type CheckStatus = 'ok' | 'warn' | 'action';
+export interface Check {
+    name: string;
+    status: CheckStatus;
+    detail: string;
+}
+export type FeatureState = 'enabled' | 'pending' | 'disabled' | 'unknown';
+export type EditionSupport = 'supported' | 'home' | 'unsupported' | 'unknown';
+export interface MachineFacts {
+    edition: string | null;
+    build: number | null;
+    feature: FeatureState;
+    /** WindowsSandbox.exe exists (it appears only after the restart that follows enabling the feature). */
+    sandboxExe: boolean;
+    virtualizationFirmware: boolean | null;
+    hypervisorPresent: boolean | null;
+    totalRamBytes: number;
+    freeDiskBytes: number | null;
+    storageRoot: string;
+    nodeVersion: string;
+}
+export declare const ENABLE_COMMAND: string;
+/** `reg query <key>` output to { valueName: data }. */
+export declare const parseRegQuery: (text: string) => Record<string, string>;
+/** Windows Sandbox needs Pro, Enterprise or Education (build 18305+); Home ("Core*") and Server cannot run it. */
+export declare const editionSupport: (edition: string | null) => EditionSupport;
+/** The "State : ..." line of `Dism /Get-FeatureInfo` (English output only; anything else is unknown). */
+export declare const parseDismState: (text: string) => FeatureState;
+/** Win32_OptionalFeature.InstallState: 1 enabled, 2 disabled, 3 absent. */
+export declare const featureFromInstallState: (state: number | null | undefined) => FeatureState;
+export declare const nodeMajor: (version: string) => number;
+/** Offer to enable the feature only when it is off and this edition can have it. */
+export declare const canEnableFeature: (f: MachineFacts) => boolean;
+/** Turns what we learnt about the PC into the checklist (pure, so it can be tested). */
+export declare const buildChecks: (f: MachineFacts) => Check[];
+declare const Probe: z.ZodObject<{
+    virtualizationFirmware: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    hypervisorPresent: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    installState: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+export declare const parseProbe: (text: string) => z.infer<typeof Probe>;
+export declare const setup: (ctx: Context) => Promise<number>;
+export {};

package/dist/cli/commands/setup.js

@@ -0,0 +1,152 @@
+// `sandbox setup`: checks this PC can run Windows Sandbox and offers to turn the feature on.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import _ from 'lodash';
+import { z } from 'zod';
+import { askYesNo } from '../../core/workspace.js';
+import { fail, fileExists, isWin } from '../../core/util.js';
+import { SYSTEM, system32 } from '../../shared/system.js';
+import { table } from './context.js';
+const FEATURE = 'Containers-DisposableClientVM';
+export const ENABLE_COMMAND = 'Enable-WindowsOptionalFeature -Online -FeatureName ' + FEATURE + ' -All -NoRestart';
+const GB = 1024 ** 3;
+/** `reg query <key>` output to { valueName: data }. */
+export const parseRegQuery = (text) => Object.fromEntries(_.compact(text.split(/\r?\n/).map((line) => /^\s+(\S+)\s+REG_\w+\s+(.*)$/.exec(line)?.slice(1, 3))));
+/** Windows Sandbox needs Pro, Enterprise or Education (build 18305+); Home ("Core*") and Server cannot run it. */
+export const editionSupport = (edition) => {
+    if (!edition)
+        return 'unknown';
+    if (/^Core/i.test(edition))
+        return 'home';
+    if (/^Server/i.test(edition))
+        return 'unsupported';
+    return /^(Professional|Enterprise|Education|IoTEnterprise)/i.test(edition) ? 'supported' : 'unknown';
+};
+/** The "State : ..." line of `Dism /Get-FeatureInfo` (English output only; anything else is unknown). */
+export const parseDismState = (text) => {
+    const state = /^State\s*:\s*(.+?)\s*$/im.exec(text)?.[1].toLowerCase() ?? '';
+    if (state === 'enabled')
+        return 'enabled';
+    if (state.includes('pending'))
+        return 'pending';
+    return state.startsWith('disabled') ? 'disabled' : 'unknown';
+};
+/** Win32_OptionalFeature.InstallState: 1 enabled, 2 disabled, 3 absent. */
+export const featureFromInstallState = (state) => state === 1 ? 'enabled' : state === 2 || state === 3 ? 'disabled' : 'unknown';
+export const nodeMajor = (version) => Number(/^v?(\d+)/.exec(version.trim())?.[1] ?? 0);
+/** Offer to enable the feature only when it is off and this edition can have it. */
+export const canEnableFeature = (f) => f.feature !== 'enabled' && f.feature !== 'pending' && !f.sandboxExe && ['supported', 'unknown'].includes(editionSupport(f.edition));
+const formatGb = (bytes) => (bytes / GB).toFixed(1) + ' GB';
+/** Turns what we learnt about the PC into the checklist (pure, so it can be tested). */
+export const buildChecks = (f) => {
+    const support = editionSupport(f.edition);
+    const edition = (f.edition ?? 'unknown edition') + (f.build ? ', build ' + f.build : '');
+    const virt = f.hypervisorPresent || f.virtualizationFirmware;
+    const featureReady = f.feature === 'enabled' && f.sandboxExe;
+    return [
+        support === 'supported' && (f.build ?? 18305) >= 18305 ? { name: 'Windows edition', status: 'ok', detail: edition }
+            : support === 'home' ? { name: 'Windows edition', status: 'action', detail: edition + ': Windows Home cannot run Windows Sandbox. Upgrade to Pro (Settings > System > Activation).' }
+                : support === 'unsupported' ? { name: 'Windows edition', status: 'action', detail: edition + ': Windows Sandbox needs Windows 10/11 Pro, Enterprise or Education.' }
+                    : support === 'supported' ? { name: 'Windows edition', status: 'action', detail: edition + ': too old; Windows Sandbox needs Windows 10 version 1903 or newer.' }
+                        : { name: 'Windows edition', status: 'warn', detail: edition + ': not sure this edition has Windows Sandbox (it needs Pro, Enterprise or Education).' },
+        virt ? { name: 'CPU virtualization', status: 'ok', detail: f.hypervisorPresent ? 'on (hypervisor running)' : 'on' }
+            : virt === false ? { name: 'CPU virtualization', status: 'action', detail: 'off. Turn on Intel VT-x / AMD-V (SVM) in your PC\'s BIOS/UEFI settings, then run this again.' }
+                : { name: 'CPU virtualization', status: 'warn', detail: 'could not tell; if Windows Sandbox will not start, turn on VT-x / AMD-V in the BIOS/UEFI.' },
+        featureReady ? { name: 'Windows Sandbox feature', status: 'ok', detail: 'enabled' }
+            : f.feature === 'pending' || (f.feature === 'enabled' && !f.sandboxExe) ? { name: 'Windows Sandbox feature', status: 'action', detail: 'enabled, but Windows needs a restart to finish.' }
+                : f.sandboxExe ? { name: 'Windows Sandbox feature', status: 'ok', detail: 'installed' }
+                    : { name: 'Windows Sandbox feature', status: 'action', detail: 'not enabled. In an admin PowerShell: ' + ENABLE_COMMAND + ', then restart.' },
+        { name: 'Memory', status: f.totalRamBytes < 4 * GB ? 'action' : f.totalRamBytes < 8 * GB ? 'warn' : 'ok', detail: formatGb(f.totalRamBytes) + (f.totalRamBytes < 4 * GB ? ': Windows Sandbox needs at least 4 GB.' : f.totalRamBytes < 8 * GB ? ': works, but 8 GB or more is recommended.' : '') },
+        f.freeDiskBytes === null ? { name: 'Free disk', status: 'warn', detail: 'could not check the drive of ' + f.storageRoot }
+            : { name: 'Free disk', status: f.freeDiskBytes < 5 * GB ? 'action' : f.freeDiskBytes < 20 * GB ? 'warn' : 'ok', detail: formatGb(f.freeDiskBytes) + ' free for ' + f.storageRoot + (f.freeDiskBytes < 5 * GB ? ': free up space (toolchains need several GB).' : f.freeDiskBytes < 20 * GB ? ': getting low; toolchains and caches can use several GB.' : '') },
+        nodeMajor(f.nodeVersion) >= 20 ? { name: 'Node.js', status: 'ok', detail: f.nodeVersion } : { name: 'Node.js', status: 'action', detail: f.nodeVersion + ': needs 20 or newer (winget install OpenJS.NodeJS.LTS).' },
+    ];
+};
+// Fixed script (no outside data): CPU/hypervisor facts and the feature state, readable without admin rights.
+const PROBE = [
+    '$ErrorActionPreference = "SilentlyContinue"',
+    '$cpu = @(Get-CimInstance Win32_Processor)',
+    '$cs = Get-CimInstance Win32_ComputerSystem',
+    '$f = Get-CimInstance Win32_OptionalFeature -Filter "Name=\'' + FEATURE + '\'"',
+    '$v = $null; if ($cpu.Count) { $v = [bool]($cpu | Where-Object { $_.VirtualizationFirmwareEnabled }) }',
+    '$h = $null; if ($cs) { $h = [bool]$cs.HypervisorPresent }',
+    '$s = $null; if ($f) { $s = [int]$f.InstallState }',
+    '@{ virtualizationFirmware = $v; hypervisorPresent = $h; installState = $s } | ConvertTo-Json -Compress',
+].join('; ');
+const Probe = z.object({ virtualizationFirmware: z.boolean().nullable(), hypervisorPresent: z.boolean().nullable(), installState: z.number().nullable() }).partial();
+export const parseProbe = (text) => {
+    try {
+        return Probe.parse(JSON.parse(_.last(text.trim().split(/\r?\n/)) ?? ''));
+    }
+    catch {
+        return {};
+    }
+};
+const run = (exe, args) => {
+    const r = spawnSync(exe, args, { encoding: 'utf8', windowsHide: true, timeout: 60000 });
+    return r.status === 0 ? r.stdout : '';
+};
+const freeDisk = (dir) => {
+    let at = path.resolve(dir);
+    while (!fs.existsSync(at) && path.dirname(at) !== at)
+        at = path.dirname(at);
+    try {
+        const s = fs.statfsSync(at);
+        return s.bavail * s.bsize;
+    }
+    catch {
+        return null;
+    }
+};
+const gatherFacts = (storageRoot) => {
+    const reg = parseRegQuery(run(SYSTEM.reg(), ['query', 'HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion']));
+    const probe = parseProbe(run(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-Command', PROBE]));
+    // DISM knows about a pending restart but needs admin rights; the CIM state works for everyone.
+    const dism = parseDismState(run(SYSTEM.dism(), ['/English', '/Online', '/Get-FeatureInfo', '/FeatureName:' + FEATURE]));
+    return {
+        edition: reg.EditionID ?? null,
+        build: Number(reg.CurrentBuildNumber ?? reg.CurrentBuild) || null,
+        feature: dism === 'unknown' ? featureFromInstallState(probe.installState) : dism,
+        sandboxExe: fileExists(system32('WindowsSandbox.exe')),
+        virtualizationFirmware: probe.virtualizationFirmware ?? null,
+        hypervisorPresent: probe.hypervisorPresent ?? null,
+        totalRamBytes: os.totalmem(),
+        freeDiskBytes: freeDisk(storageRoot),
+        storageRoot,
+        nodeVersion: process.version,
+    };
+};
+const LABEL = { ok: '\x1b[32mOK\x1b[0m', warn: '\x1b[33mWARNING\x1b[0m', action: '\x1b[31mACTION NEEDED\x1b[0m' };
+const print = (checks) => table(checks.map((c) => [LABEL[c.status], c.name, c.detail]));
+/** Runs the enable command in an elevated PowerShell (Windows asks for permission); true if it worked. */
+const enableFeature = () => {
+    const inner = "'-NoProfile','-Command','" + ENABLE_COMMAND + " | Out-Null'";
+    const outer = "try { $p = Start-Process -FilePath '" + SYSTEM.powershell() + "' -Verb RunAs -Wait -PassThru -WindowStyle Hidden -ArgumentList " + inner + '; exit $p.ExitCode } catch { exit 1 }';
+    return spawnSync(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-Command', outer], { stdio: 'inherit' }).status === 0;
+};
+export const setup = async (ctx) => {
+    if (!isWin)
+        fail('Windows Sandbox only runs on Windows.', 'Run sandbox setup on a Windows 10/11 Pro, Enterprise or Education PC.');
+    console.log('Checking this PC for Windows Sandbox...\n');
+    const facts = gatherFacts(ctx.storageRoot);
+    let checks = buildChecks(facts);
+    print(checks);
+    if (canEnableFeature(facts)) {
+        console.log('');
+        if (await askYesNo('Turn on Windows Sandbox now? Windows will ask for admin permission.')) {
+            console.log('Enabling Windows Sandbox (this can take a minute)...');
+            if (!enableFeature())
+                fail('Windows Sandbox could not be enabled (or the admin prompt was declined).', 'In an admin PowerShell run: ' + ENABLE_COMMAND + ', then restart Windows.');
+            console.log('Done. Restart Windows to finish, then run sandbox setup again.\n');
+            checks = buildChecks(gatherFacts(ctx.storageRoot));
+            print(checks);
+        }
+        else
+            console.log('To do it yourself, in an admin PowerShell run:\n  ' + ENABLE_COMMAND + '\nthen restart Windows.');
+    }
+    const todo = checks.filter((c) => c.status === 'action').length;
+    console.log('\n' + (todo ? todo + ' thing(s) to fix before the sandbox can start (see ACTION NEEDED above).' : 'This PC is ready. cd into a project and run sandbox claude (or sandbox for no agent).'));
+    return todo ? 1 : 0;
+};