windows-development-sandbox 1.5.0 → 1.7.0

package/dist/cli/commands/repair/checks/pc.js

@@ -0,0 +1,55 @@
+// This PC: Windows itself, what Windows Sandbox needs of it, and whether Windows wants a restart. The hardware and
+// edition answers come from the same look `sandbox setup` takes (once per run).
+import { isWin } from '../../../../core/util/index.js';
+import { updateRestartPending } from '../../../../host/life/index.js';
+import { buildChecks } from '../../setup/checks.js';
+import { ok } from './common.js';
+const STATUS = { ok: 'ok', warn: 'warn', action: 'needs-you' };
+/** One line of the setup checklist as a check. */
+export function fromFacts(id, group, setupName, name = setupName) {
+    return {
+        id,
+        group,
+        name,
+        timeoutMs: 60_000,
+        run: (env) => {
+            const row = buildChecks(env.facts()).find((c) => c.name === setupName);
+            if (!row)
+                return { status: 'skipped', detail: 'no answer for "' + setupName + '"' };
+            return { status: STATUS[row.status], detail: row.detail };
+        },
+    };
+}
+export const PC_CHECKS = [
+    {
+        id: 'pc-windows',
+        group: 'This PC',
+        name: 'Windows',
+        run: () => isWin
+            ? ok('Windows ' + process.arch)
+            : {
+                status: 'needs-you',
+                detail: 'this is not Windows',
+                means: 'Windows Sandbox only runs on Windows.',
+                fix: 'Run sandbox on a Windows 10/11 Pro, Enterprise or Education PC.',
+            },
+    },
+    fromFacts('pc-edition', 'This PC', 'Windows edition', 'Windows edition'),
+    fromFacts('pc-virtualization', 'This PC', 'CPU virtualization', 'CPU virtualization'),
+    fromFacts('pc-memory', 'This PC', 'Memory', 'Memory'),
+    fromFacts('pc-node', 'This PC', 'Node.js', 'Node.js'),
+    {
+        id: 'pc-restart-pending',
+        group: 'This PC',
+        name: 'Windows restart',
+        timeoutMs: 40_000,
+        run: () => updateRestartPending()
+            ? {
+                status: 'warn',
+                detail: 'Windows is waiting for a restart',
+                means: 'Windows may restart on its own and close a running sandbox.',
+                fix: 'Restart Windows when it suits you, or pause Windows updates while you work.',
+            }
+            : ok('no restart pending'),
+    },
+];

package/dist/cli/commands/repair/checks/sandbox.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from '../types.js';
+export declare const SANDBOX_CHECKS: Check[];

package/dist/cli/commands/repair/checks/sandbox.js

@@ -0,0 +1,267 @@
+// The sandbox: Windows Sandbox itself, whether one runs, and what a closed or crashed one leaves behind (run files,
+// hidden windows, background watchers, old launch folders), plus the helper programs this tool builds or downloads
+// on the PC.
+import fs from 'node:fs';
+import path from 'node:path';
+import { dirExists, fileExists, isLink } from '../../../../core/util/index.js';
+import { SandboxChannel } from '../../../../host/channel/index.js';
+import { orphanWatchers, runStateProblems, staleLaunchFolders, watcherRecords } from '../../../../host/health/index.js';
+import { hostToolsExe } from '../../../../host/native.js';
+import { sandboxFeatureInstalled } from '../../../../host/sandbox/index.js';
+import { assertTestWritable, refuseInSelfTest } from '../../../../host/test-guard.js';
+import { conptyDir, terminalDir, terminalExe } from '../../../../host/tools/index.js';
+import { RunDir } from '../../../../shared/channel/index.js';
+import { safeRemove } from '../../../../shared/io/index.js';
+import { removeTree } from '../../data/remove.js';
+import { deadPidFiles } from '../finders.js';
+import { fromFacts } from './pc.js';
+import { ok, plural, rel } from './common.js';
+const LAUNCH_DAYS = 7;
+const hiddenWindowsFile = (env) => path.join(env.storageRoot, 'run', 'hidden-windows.json');
+export const SANDBOX_CHECKS = [
+    {
+        id: 'sandbox-exe',
+        group: 'Sandbox',
+        name: 'WindowsSandbox.exe',
+        run: () => sandboxFeatureInstalled()
+            ? ok('present')
+            : {
+                status: 'needs-you',
+                detail: 'WindowsSandbox.exe is not in Windows\\System32',
+                means: 'Windows Sandbox is not turned on (it appears after the restart that follows turning it on).',
+                fix: 'Run: sandbox setup (it checks this PC and offers to turn it on).',
+            },
+    },
+    fromFacts('sandbox-feature', 'Sandbox', 'Windows Sandbox feature', 'Windows Sandbox feature'),
+    {
+        id: 'sandbox-running',
+        group: 'Sandbox',
+        name: 'Running sandbox',
+        run: (env) => {
+            if (!env.running)
+                return ok('none running');
+            const run = new RunDir(env.dataPath);
+            const known = fs.existsSync(run.sandboxFile) || run.listSessions().length > 0;
+            if (known)
+                return ok('one is running, with its status in your data folder; fixes that touch its folders wait');
+            return {
+                status: 'warn',
+                detail: 'a Windows Sandbox is running, but nothing of yours is in the data folder',
+                means: 'It was started by another user, by hand, or its status files were removed. Windows allows only one at a time.',
+                fix: 'Close its window (or run sandbox stop) before starting yours.',
+            };
+        },
+    },
+    {
+        id: 'sandbox-run-state',
+        group: 'Sandbox',
+        name: 'Sandbox run state',
+        run: (env) => {
+            const run = new RunDir(env.dataPath);
+            if (env.running)
+                return ok('a sandbox is running; its state is in use');
+            if (isLink(run.root))
+                return {
+                    status: 'needs-you',
+                    detail: 'the run folder is a link',
+                    means: 'It could lead anywhere on this PC; it is never followed.',
+                    plan: 'remove the link itself',
+                };
+            const problems = runStateProblems(env.dataPath);
+            if (!problems.any)
+                return ok('clean');
+            const what = [
+                problems.sessions ? plural(problems.sessions, 'session') + ' still marked running' : '',
+                problems.requests ? plural(problems.requests, 'request') + ' never answered' : '',
+                problems.unfinishedBoot ? 'a start that stopped while ' + problems.unfinishedBoot : '',
+            ].filter(Boolean);
+            return {
+                status: 'needs-you',
+                detail: 'no sandbox is running, but ' + what.join(', '),
+                means: 'sandbox status and attach would show sessions that are not there.',
+                plan: 'clear the run state of the closed sandbox (' + what.length + ' item' + (what.length === 1 ? '' : 's') + ')',
+                lines: what,
+            };
+        },
+        fix: (env) => {
+            new SandboxChannel(env.dataPath, () => env.running).reset();
+            return { done: 'cleared the run state of the closed sandbox' };
+        },
+    },
+    {
+        id: 'sandbox-hidden-windows',
+        group: 'Sandbox',
+        name: 'Hidden-window list',
+        run: (env) => {
+            const file = hiddenWindowsFile(env);
+            if (!fs.existsSync(file) && !isLink(file))
+                return ok('clean');
+            if (env.running)
+                return ok('a sandbox is running; kept');
+            return {
+                status: 'needs-you',
+                detail: 'a list of hidden windows from a sandbox that is no longer running',
+                plan: 'remove the saved hidden-window list',
+            };
+        },
+        fix: (env) => {
+            const file = hiddenWindowsFile(env);
+            assertTestWritable(file);
+            fs.rmSync(file, { force: true });
+            return { done: 'removed the saved hidden-window list' };
+        },
+    },
+    {
+        id: 'sandbox-watcher-records',
+        group: 'Sandbox',
+        name: 'Sync watcher records',
+        run: (env) => {
+            const dead = deadPidFiles(path.join(env.storageRoot, 'run'), (pid) => env.system.pidAlive(pid));
+            if (!dead.length)
+                return ok('no stale records');
+            return {
+                status: 'needs-you',
+                detail: plural(dead.length, 'record') + ' of a history sync watcher that is no longer running',
+                plan: 'remove ' + plural(dead.length, 'stale watcher record') + ' (the next start begins a new watcher)',
+                data: dead,
+            };
+        },
+        fix: (_env, finding) => {
+            const dead = Array.isArray(finding.data) ? finding.data : [];
+            for (const f of dead) {
+                assertTestWritable(f);
+                fs.rmSync(f, { force: true });
+            }
+            return { done: 'removed ' + plural(dead.length, 'stale watcher record') };
+        },
+    },
+    {
+        id: 'sandbox-orphan-watchers',
+        group: 'Sandbox',
+        name: 'Background watchers',
+        timeoutMs: 40_000,
+        run: (env) => {
+            const infos = watcherRecords(env.storageRoot, env.now());
+            const rows = infos.length && !env.running ? env.system.processes() : [];
+            const image = (pid) => rows.find((r) => r.pid === pid)?.image ?? null;
+            const orphans = orphanWatchers(infos, { running: env.running, alive: (pid) => env.system.pidAlive(pid), image });
+            if (!orphans.length)
+                return ok(infos.length ? 'every watcher has a sandbox to watch' : 'none running');
+            return {
+                status: 'needs-you',
+                detail: plural(orphans.length, 'background history watcher') + ' running with no sandbox',
+                means: 'They use memory and keep files open until stopped.',
+                plan: 'stop ' + plural(orphans.length, 'orphaned watcher') + ' (history already synced stays)',
+                lines: orphans.map((o) => 'process ' + o.pid + ' (' + rel(env.storageRoot, o.file) + ')'),
+                data: orphans.map((o) => ({ pid: o.pid, file: o.file })),
+            };
+        },
+        fix: (env, finding) => {
+            const list = Array.isArray(finding.data) ? finding.data : [];
+            for (const w of list) {
+                env.system.stop(w.pid);
+                assertTestWritable(w.file);
+                fs.rmSync(w.file, { force: true });
+            }
+            return { done: 'stopped ' + plural(list.length, 'orphaned watcher') };
+        },
+    },
+    {
+        id: 'sandbox-launch-folders',
+        group: 'Sandbox',
+        name: 'Old launch folders',
+        needsIdle: 'fix',
+        run: (env) => {
+            const old = staleLaunchFolders(env.storageRoot, LAUNCH_DAYS, env.now());
+            if (!old.length)
+                return ok('none older than ' + LAUNCH_DAYS + ' days');
+            return {
+                status: 'needs-you',
+                detail: plural(old.length, 'launch folder') + ' older than ' + LAUNCH_DAYS + ' days',
+                means: 'Each belongs to a start that is long over; they only use disk space.',
+                plan: 'remove ' + plural(old.length, 'old launch folder'),
+                lines: old.map((o) => rel(env.storageRoot, o.path) + ' (' + o.ageDays + ' days)'),
+                data: old.map((o) => o.path),
+            };
+        },
+        fix: (env, finding) => {
+            const old = Array.isArray(finding.data) ? finding.data : [];
+            for (const p of old)
+                safeRemove(p, env.storageRoot);
+            return { done: 'removed ' + plural(old.length, 'old launch folder') };
+        },
+    },
+    {
+        id: 'sandbox-hosttools',
+        group: 'Sandbox',
+        name: 'HostTools.exe',
+        timeoutMs: 150_000,
+        run: (env) => {
+            const bin = path.join(env.storageRoot, 'bin');
+            const built = dirExists(bin) && fs.readdirSync(bin).some((n) => /^HostTools-[0-9a-f]+\.exe$/i.test(n));
+            if (built)
+                return ok('built in ' + bin);
+            return {
+                status: 'warn',
+                detail: 'HostTools.exe is not built yet',
+                means: 'It keeps this PC awake and edits your PATH; it is built the first time one is needed, and until then a slower PowerShell fallback runs.',
+                plan: 'build HostTools.exe now',
+            };
+        },
+        fix: (env) => {
+            refuseInSelfTest('build HostTools.exe');
+            const exe = hostToolsExe(env.storageRoot);
+            if (!exe)
+                throw new Error('it could not be built (is the .NET Framework compiler csc.exe missing?)');
+            return { done: 'built ' + exe };
+        },
+    },
+    {
+        id: 'sandbox-conpty',
+        group: 'Sandbox',
+        name: 'Pseudo console (conpty)',
+        needsIdle: 'fix',
+        run: (env) => {
+            const dir = conptyDir(env.dataPath);
+            if (!dirExists(dir))
+                return ok('not downloaded yet (the next start downloads it)');
+            if (fileExists(path.join(dir, 'conpty.dll')) && fileExists(path.join(dir, 'OpenConsole.exe')))
+                return ok('downloaded');
+            return {
+                status: 'warn',
+                detail: 'the conpty download is incomplete',
+                means: 'Agent terminals would use the older Windows console and can garble after a resize.',
+                plan: 'remove the incomplete download (the next start downloads it again)',
+                data: dir,
+            };
+        },
+        fix: (env, finding) => {
+            removeTree(String(finding.data), env.dataPath);
+            return { done: 'removed the incomplete conpty download' };
+        },
+    },
+    {
+        id: 'sandbox-terminal',
+        group: 'Sandbox',
+        name: 'Windows Terminal download',
+        needsIdle: 'fix',
+        run: (env) => {
+            const dir = terminalDir(env.dataPath);
+            if (!dirExists(dir))
+                return ok('not downloaded yet (the next start downloads it)');
+            if (fileExists(terminalExe(env.dataPath)))
+                return ok('downloaded');
+            return {
+                status: 'warn',
+                detail: 'the Windows Terminal download is incomplete',
+                means: 'The sandbox window falls back to a plain console.',
+                plan: 'remove the incomplete download (the next start downloads it again)',
+                data: dir,
+            };
+        },
+        fix: (env, finding) => {
+            removeTree(String(finding.data), env.dataPath);
+            return { done: 'removed the incomplete Windows Terminal download' };
+        },
+    },
+];

package/dist/cli/commands/repair/checks/settings.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from '../types.js';
+export declare const SETTINGS_CHECKS: Check[];

package/dist/cli/commands/repair/checks/settings.js

@@ -0,0 +1,169 @@
+// Settings: does config.json load, are the updates to your saved settings done, and are the project files you approved
+// still the ones you approved. A settings file that does not load can be put back from the copy an update saved
+// (the broken one is kept beside it).
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULTS, mergeConfig, validateConfig } from '../../../../core/config/index.js';
+import { trustStorePath } from '../../../../core/local-config/index.js';
+import { errMsg, readJsonc, tryReadJson } from '../../../../core/util/index.js';
+import { configBackups, lineDiff } from '../../../../host/health/index.js';
+import { assertTestWritable } from '../../../../host/test-guard.js';
+import { MigrateService } from '../../../services/migrate-service.js';
+import { ok, plural } from './common.js';
+const MAX_PROJECT_FILE_BYTES = 1024 * 1024;
+/** The newest saved copy of the settings file that itself loads. */
+function goodBackup(env) {
+    return (configBackups(env.storageRoot, env.configFile).find((b) => {
+        try {
+            validateConfig(mergeConfig(DEFAULTS, readJsonc(b.copy)), b.copy);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }) ?? null);
+}
+const messageOf = (e) => e.message.split('\n')[0] + (e.fix ? ' ' + e.fix : '');
+/** The files in <storage>\trusted-configs.json whose approval no longer matches the file (hash differs). */
+function changedApprovals(storageRoot) {
+    const store = tryReadJson(trustStorePath(storageRoot));
+    if (!store || typeof store !== 'object')
+        return [];
+    const changed = [];
+    for (const [file, hash] of Object.entries(store)) {
+        if (typeof hash !== 'string' || !path.isAbsolute(file))
+            continue;
+        try {
+            const stat = fs.statSync(file);
+            if (!stat.isFile() || stat.size > MAX_PROJECT_FILE_BYTES)
+                continue;
+            if (crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex') !== hash)
+                changed.push(file);
+        }
+        catch {
+            // the project is gone or not readable: nothing to compare
+        }
+    }
+    return changed;
+}
+export const SETTINGS_CHECKS = [
+    {
+        id: 'settings-config',
+        group: 'Settings',
+        name: 'Settings file',
+        run: (env) => {
+            const error = env.configError;
+            if (!error)
+                return ok(env.ctx.loaded.configPath
+                    ? env.ctx.loaded.configPath + ' is valid'
+                    : 'no settings file; the built-in defaults apply');
+            const base = {
+                status: 'needs-you',
+                detail: messageOf(error),
+                means: 'Every command that reads your settings stops until this is fixed (built-in defaults were used for the other checks).',
+            };
+            let backup = null;
+            try {
+                backup = fs.existsSync(env.configFile) ? goodBackup(env) : null;
+            }
+            catch (e) {
+                return {
+                    ...base,
+                    fix: 'Fix ' + env.configFile + ' by hand (the backups could not be read: ' + errMsg(e) + ').',
+                };
+            }
+            if (!backup)
+                return {
+                    ...base,
+                    fix: 'Open ' + env.configFile + ' and correct what is listed, or delete it to start again with the defaults.',
+                };
+            const diff = lineDiff(fs.readFileSync(env.configFile, 'utf8'), fs.readFileSync(backup.copy, 'utf8'));
+            return {
+                ...base,
+                plan: 'put back the settings saved before the update ' +
+                    backup.label +
+                    ' (your current file is kept as config.json.broken-...)',
+                lines: [
+                    'Changes from your file (-) to the saved copy (+):',
+                    ...(diff.length ? diff : ['(the files read the same)']),
+                ],
+                data: backup.copy,
+            };
+        },
+        fix: (env, finding) => {
+            const copy = String(finding.data);
+            assertTestWritable(env.configFile);
+            const kept = env.configFile + '.broken-' + new Date(env.now()).toISOString().replace(/\D/g, '').slice(0, 14);
+            fs.copyFileSync(env.configFile, kept);
+            fs.copyFileSync(copy, env.configFile);
+            // The engine looks again after the fix; the config is read from the file, not from the earlier error.
+            env.configError = null;
+            try {
+                validateConfig(mergeConfig(DEFAULTS, readJsonc(env.configFile)), env.configFile);
+            }
+            catch (e) {
+                env.configError = e;
+            }
+            return {
+                done: 'put the saved settings back in ' + env.configFile + '; the broken file is kept as ' + path.basename(kept),
+            };
+        },
+    },
+    {
+        id: 'settings-updates',
+        group: 'Settings',
+        name: 'Saved settings up to date',
+        run: (env) => {
+            const service = new MigrateService({ storageRoot: env.storageRoot, userDir: env.userDir, configPath: env.ctx.loaded.configPath }, undefined, env.migrations, () => env.running);
+            let pending;
+            try {
+                pending = service.plan();
+            }
+            catch (e) {
+                return {
+                    status: 'needs-you',
+                    detail: errMsg(e),
+                    means: 'The record of which updates ran is damaged, so none can be applied.',
+                };
+            }
+            if (!pending.length)
+                return ok('nothing waits');
+            return {
+                status: 'needs-you',
+                detail: plural(pending.length, 'change') + ' to your saved settings wait',
+                means: 'This version expects your settings in a newer form.',
+                plan: 'bring your saved settings up to date (a backup is made first)',
+                lines: pending,
+            };
+        },
+        fix: async (env) => {
+            const service = new MigrateService({ storageRoot: env.storageRoot, userDir: env.userDir, configPath: env.ctx.loaded.configPath }, undefined, env.migrations, () => env.running);
+            const notes = [];
+            const result = await service.run((line) => notes.push(line));
+            return {
+                done: (result.applied.length ? 'applied ' + result.applied.join(', ') : 'applied nothing') +
+                    (result.postponed.length ? '; ' + result.postponed.join(', ') + ' wait until no sandbox runs' : ''),
+            };
+        },
+    },
+    {
+        id: 'settings-approvals',
+        group: 'Settings',
+        name: 'Approved project files',
+        run: (env) => {
+            const changed = changedApprovals(env.storageRoot);
+            if (!changed.length)
+                return ok('every project file you approved is unchanged');
+            return {
+                status: 'warn',
+                detail: plural(changed.length, 'project file') +
+                    ' changed since you approved ' +
+                    (changed.length === 1 ? 'it' : 'them'),
+                means: 'Its settings are ignored until you approve the new version; the next launch in that project asks again.',
+                fix: 'Nothing to repair. Read the changes, then run sandbox in that project and answer the question (or sandbox config check).',
+                lines: changed,
+            };
+        },
+    },
+];

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

@@ -0,0 +1,2 @@
+import type { Check } from '../types.js';
+export declare const VPN_CHECKS: Check[];

package/dist/cli/commands/repair/checks/vpn.js

@@ -0,0 +1,53 @@
+// The VPN, when it is on: is the login saved and readable, can the OpenVPN download be reached. Not shown when the
+// VPN is off. (That the storage folder is private is checked with the data folder.)
+import { VpnLogin } from '../../../../host/vpn/index.js';
+import { OPENVPN_MSI } from '../../../../shared/vpn/download.js';
+import { ok } from './common.js';
+const REACH_MS = 6000;
+const vpnOn = (env) => env.ctx.loaded.config.vpn.enabled;
+export const VPN_CHECKS = [
+    {
+        id: 'vpn-login',
+        group: 'Network',
+        name: 'VPN login',
+        checking: 'the saved VPN login',
+        applies: vpnOn,
+        run: (env) => {
+            const { provider } = env.ctx.loaded.config.vpn;
+            const state = new VpnLogin(env.storageRoot).state(provider);
+            if (state === 'saved')
+                return ok('saved, encrypted, and this Windows user can read it');
+            return state === 'none'
+                ? {
+                    status: 'needs-you',
+                    detail: 'the VPN is on but no login is saved',
+                    means: 'The sandbox cannot start its VPN, so a launch stops.',
+                    fix: 'Run sandbox vpn login (or turn the VPN off: sandbox config set vpn.enabled false).',
+                }
+                : {
+                    status: 'needs-you',
+                    detail: 'a login is saved but this Windows user cannot decrypt it',
+                    means: 'It was saved by another Windows user or on another PC, so the VPN cannot start.',
+                    fix: 'Save it again: sandbox vpn login',
+                };
+        },
+    },
+    {
+        id: 'vpn-download',
+        group: 'Network',
+        name: 'OpenVPN download',
+        checking: 'whether the OpenVPN download can be reached',
+        applies: vpnOn,
+        timeoutMs: REACH_MS + 4000,
+        run: async (env) => {
+            if (await env.system.reachable(OPENVPN_MSI.base, REACH_MS))
+                return ok('swupdate.openvpn.org answers');
+            return {
+                status: 'warn',
+                detail: 'swupdate.openvpn.org did not answer within ' + REACH_MS / 1000 + ' seconds',
+                means: 'The sandbox downloads OpenVPN there at its first VPN start (it is kept afterwards).',
+                fix: 'Check your internet connection or proxy, then run this again.',
+            };
+        },
+    },
+];

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

@@ -0,0 +1,32 @@
+import { type Check, type CheckResult, type RepairEnv, type Summary } from './types.js';
+export declare const DEFAULT_TIMEOUT_MS = 20000;
+export declare const FIX_TIMEOUT_MS = 120000;
+/** What the output hooks into: each step, as it happens. */
+export interface RunHooks {
+    lookStart?: (check: Check) => void;
+    lookEnd?: (result: CheckResult) => void;
+    fixStart?: (result: CheckResult) => void;
+    fixEnd?: (result: CheckResult) => void;
+}
+/** Resolves with `work`, or rejects with TimedOut after `ms` (a check that blocks the process cannot be stopped). */
+export declare function withTimeout<T>(work: () => T | Promise<T>, ms: number): Promise<T>;
+/** The checks in the order they are shown: by group, then as listed. */
+export declare function inGroupOrder(checks: readonly Check[]): Check[];
+export declare function summarize(results: readonly CheckResult[]): Summary;
+export declare class HealthRun {
+    private readonly env;
+    private readonly hooks;
+    private readonly limits;
+    private readonly findings;
+    private readonly checks;
+    constructor(checks: readonly Check[], env: RepairEnv, hooks?: RunHooks, limits?: {
+        lookMs?: number;
+        fixMs?: number;
+    });
+    /** Runs every check without changing anything. */
+    look(): Promise<CheckResult[]>;
+    /** Applies the fix of every result repair can mend (or only those in `only`), then looks again. */
+    fix(results: readonly CheckResult[], only?: readonly string[]): Promise<CheckResult[]>;
+    private lookAt;
+    private fixOne;
+}