windows-development-sandbox 1.0.5 → 1.4.0

package/dist/guest/toolchains/native/msvc/environment.js

@@ -0,0 +1,57 @@
+// What makes the unpacked tree behave like a Build Tools install: the vcvars environment, vcvars64.bat, vswhere.
+import fs from 'node:fs';
+import path from 'node:path';
+import { errMsg, mkdirp, warn } from '../../../env.js';
+import { ensureCompiled } from '../../../helpers.js';
+import { hostBin, ROOT } from './tree.js';
+/** Where build tools look for vswhere (local to the sandbox, so it is written each boot). */
+const VSWHERE_DIR = path.join(process.env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)', 'Microsoft Visual Studio', 'Installer');
+/** Variables vcvars64.bat would set for this tree (host x64, target x64). */
+export const vcvars = (root, msvc, sdk) => {
+    const vc = path.join(root, 'VC', 'Tools', 'MSVC', msvc);
+    const kits = path.join(root, 'Windows Kits', '10');
+    const inc = (...p) => path.join(kits, 'Include', sdk, ...p);
+    const lib = (...p) => path.join(kits, 'Lib', sdk, ...p);
+    return {
+        vars: {
+            VSINSTALLDIR: root + '\\', VCINSTALLDIR: path.join(root, 'VC') + '\\', VCToolsInstallDir: vc + '\\', VCToolsVersion: msvc, VisualStudioVersion: '17.0',
+            WindowsSdkDir: kits + '\\', WindowsSDKVersion: sdk + '\\', WindowsSDKLibVersion: sdk + '\\', UniversalCRTSdkDir: kits + '\\', UCRTVersion: sdk,
+            VSCMD_ARG_HOST_ARCH: 'x64', VSCMD_ARG_TGT_ARCH: 'x64', Platform: 'x64',
+            INCLUDE: [path.join(vc, 'include'), inc('ucrt'), inc('shared'), inc('um'), inc('winrt'), inc('cppwinrt')].join(';'),
+            LIB: [path.join(vc, 'lib', 'x64'), lib('ucrt', 'x64'), lib('um', 'x64')].join(';'),
+            LIBPATH: [path.join(vc, 'lib', 'x64'), path.join(vc, 'lib', 'x86', 'store', 'references')].join(';'),
+        },
+        path: [path.join(vc, 'bin', 'Hostx64', 'x64'), path.join(kits, 'bin', sdk, 'x64')],
+    };
+};
+/** vcvars64.bat / vcvarsall.bat in the usual place, for scripts that `call` them. */
+export const writeVcvars = (env) => {
+    const dir = mkdirp(path.join(ROOT, 'VC', 'Auxiliary', 'Build'));
+    const lines = [
+        '@echo off', 'rem Written by Windows Development Sandbox for its portable MSVC (host x64, target x64).',
+        ...Object.entries(env.vars).map(([k, v]) => 'set "' + k + '=' + v + '"'),
+        'set "PATH=' + env.path.join(';') + ';%PATH%"', 'exit /b 0',
+    ];
+    fs.writeFileSync(path.join(dir, 'vcvars64.bat'), lines.join('\r\n') + '\r\n');
+    fs.writeFileSync(path.join(dir, 'vcvarsall.bat'), ['@echo off', 'rem Only x64 (amd64) is installed.', 'call "%~dp0vcvars64.bat"', 'exit /b %errorlevel%'].join('\r\n') + '\r\n');
+};
+/** vswhere.exe where Visual Studio's installer would put it, answering with this tree. */
+export const installVswhere = (msvc) => {
+    mkdirp(VSWHERE_DIR);
+    fs.copyFileSync(ensureCompiled('vswhere'), path.join(VSWHERE_DIR, 'vswhere.exe'));
+    const [major, minor] = msvc.split('.').slice(2);
+    fs.writeFileSync(path.join(VSWHERE_DIR, 'vswhere.json'), JSON.stringify({ installationPath: ROOT, installationVersion: '17.' + (minor ?? '0') + '.0.' + (major ?? '0') }));
+};
+/**
+ * cl.exe and link.exe start vctip.exe (Visual Studio's telemetry uploader), which lingers after the build and keeps the
+ * folder locked, so `sandbox repair` / `data clean` could not delete tools\msvc. Neither VSCMD_SKIP_SENDTELEMETRY nor
+ * the TurnOffSwitch registry value stops it; without the file the compiler simply skips it. Nothing else needs it.
+ */
+export const removeTelemetry = (msvc) => {
+    try {
+        fs.rmSync(hostBin(msvc, 'vctip.exe'), { force: true });
+    }
+    catch (e) {
+        warn('Could not remove MSVC\'s telemetry helper (vctip.exe); it may keep tools\\msvc locked: ' + errMsg(e));
+    }
+};

package/dist/guest/toolchains/native/msvc/index.d.ts

@@ -0,0 +1,6 @@
+import type { Toolchains } from '../../../../core/types.js';
+import type { ToolEnv } from '../../common.js';
+import { type VcEnv } from './environment.js';
+/** The vcvars environment of an installed tree (for steps that run before the agent's environment exists). */
+export declare const installedMsvcEnv: () => VcEnv | null;
+export declare const setupMsvc: (env: ToolEnv, config: Toolchains["msvc"]) => Promise<void>;

package/dist/guest/toolchains/native/msvc/index.js

@@ -0,0 +1,48 @@
+// MSVC (cl, link) and the Windows SDK without an installer (packages.ts), laid out like a Build Tools install with
+// vcvars64.bat and a vswhere that points at it (environment.ts), so CMake, cargo (msvc host), node-gyp and vcvars-based
+// scripts work. Use is governed by the Visual Studio licence terms: it only installs with toolchains.msvc.acceptLicense.
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeJsonAtomic } from '../../../../shared/rundir.js';
+import { safeRemove } from '../../../../shared/safe-remove.js';
+import { dryRun, exists, log } from '../../../env.js';
+import { installVswhere, removeTelemetry, vcvars, writeVcvars } from './environment.js';
+import { installPackages } from './packages.js';
+import { hasCompiler, MARKER, readInstalled, ROOT } from './tree.js';
+/** The vcvars environment of an installed tree (for steps that run before the agent's environment exists). */
+export const installedMsvcEnv = () => {
+    const done = readInstalled();
+    return done && hasCompiler(done.msvc) ? vcvars(ROOT, done.msvc, done.sdk) : null;
+};
+/** Empties tools\msvc for a fresh install, keeping the manifest and the verified downloads of an earlier attempt. */
+const clearTree = () => {
+    if (!exists(ROOT))
+        return;
+    for (const name of fs.readdirSync(ROOT).filter((n) => n !== '.manifest.json' && n !== '.download'))
+        safeRemove(path.join(ROOT, name), ROOT);
+};
+export const setupMsvc = async (env, config) => {
+    if (!config.acceptLicense) {
+        throw new Error('MSVC is installed only with toolchains.msvc.acceptLicense = true: its use is governed by the Visual Studio licence terms (https://visualstudio.microsoft.com/license-terms/), which need a Visual Studio licence');
+    }
+    if (dryRun) {
+        log('(dry run) would provision MSVC ' + config.msvcVersion + ' and Windows SDK ' + config.sdkVersion);
+        return;
+    }
+    const want = config.msvcVersion + '/' + config.sdkVersion;
+    let done = readInstalled();
+    if (!done || done.want !== want || !hasCompiler(done.msvc)) {
+        log('Installing MSVC and the Windows SDK (~1-2 GB, once; licence accepted in toolchains.msvc.acceptLicense) ...');
+        clearTree();
+        done = { ...(await installPackages(config)), want };
+        // Written last and atomically: without it (an interrupted install) the next boot starts over.
+        writeJsonAtomic(MARKER, done);
+    }
+    removeTelemetry(done.msvc);
+    const vc = vcvars(ROOT, done.msvc, done.sdk);
+    writeVcvars(vc);
+    installVswhere(done.msvc);
+    Object.assign(env.vars, vc.vars);
+    env.prepend.push(...vc.path);
+    env.summary.push('msvc: ' + done.msvc + ', Windows SDK ' + done.sdk + ' (cl, link; vcvars64.bat and vswhere work)');
+};

package/dist/guest/toolchains/native/msvc/packages.d.ts

@@ -0,0 +1,6 @@
+import type { Toolchains } from '../../../../core/types.js';
+/** Downloads and unpacks MSVC and the Windows SDK into tools\msvc; resolves with the toolset and SDK folder names. */
+export declare const installPackages: (config: Toolchains["msvc"]) => Promise<{
+    msvc: string;
+    sdk: string;
+}>;

package/dist/guest/toolchains/native/msvc/packages.js

@@ -0,0 +1,156 @@
+// Downloads the MSVC compiler and the Windows SDK from Microsoft's Visual Studio channel manifest, the way mmozeiko's
+// portable-msvc.py does: each payload is checked against the manifest's sha256, the compiler is unpacked from its
+// .vsix files, the SDK from its .msi files with `msiexec /a`.
+import fs from 'node:fs';
+import path from 'node:path';
+import { download, extractArchive, fetchJson } from '../../../../shared/download.js';
+import { safeRemove } from '../../../../shared/safe-remove.js';
+import { system32 } from '../../../../shared/system.js';
+import { execAsync, exists, log, mkdirp } from '../../../env.js';
+import { msiCabs, pickMsvcVersion, pickWindowsSdk } from '../../versions.js';
+import { hostBin, ROOT } from './tree.js';
+const CHANNEL = 'https://aka.ms/vs/17/release/channel';
+const MANIFEST_DAY_MS = 24 * 60 * 60 * 1000;
+/** The compiler's packages (host x64, target x64): tools, resources, CRT headers/libs, ASAN/PGO headers. */
+const MSVC_PARTS = ['tools.hostx64.targetx64.base', 'tools.hostx64.targetx64.res.base', 'crt.headers.base', 'crt.x64.desktop.base', 'crt.x64.store.base', 'crt.source.base', 'asan.headers.base', 'pgo.headers.base'];
+/** Without these the compiler is unusable; the other parts are taken when the manifest has them. */
+const REQUIRED_PARTS = ['tools', 'crt.headers', 'crt.x64.desktop'];
+/** The SDK's .msi files (Desktop + UCRT + Store headers/libs/tools for x64), as in portable-msvc.py. */
+const SDK_MSIS = [
+    'Windows SDK for Windows Store Apps Tools-x86_en-us.msi', 'Windows SDK for Windows Store Apps Headers-x86_en-us.msi',
+    'Windows SDK for Windows Store Apps Headers OnecoreUap-x86_en-us.msi', 'Windows SDK for Windows Store Apps Libs-x86_en-us.msi',
+    'Universal CRT Headers Libraries and Sources-x86_en-us.msi', 'Windows SDK Desktop Headers x86-x86_en-us.msi',
+    'Windows SDK Desktop Headers x64-x86_en-us.msi', 'Windows SDK Desktop Libs x64-x86_en-us.msi', 'Windows SDK Desktop Tools x64-x86_en-us.msi',
+];
+/** The VS manifest (~18 MB), cached for a day. */
+const manifest = async () => {
+    const cached = path.join(ROOT, '.manifest.json');
+    if (exists(cached) && Date.now() - fs.statSync(cached).mtimeMs < MANIFEST_DAY_MS) {
+        // A download cut short leaves unreadable JSON: fetch it again instead of failing until the day is over.
+        try {
+            return JSON.parse(fs.readFileSync(cached, 'utf8'));
+        }
+        catch { /* downloaded again below */ }
+    }
+    const channel = await fetchJson(CHANNEL);
+    const item = channel.channelItems.find((i) => i.id === 'Microsoft.VisualStudio.Manifests.VisualStudio')?.payloads?.[0];
+    if (!item)
+        throw new Error('the Visual Studio channel has no package manifest');
+    mkdirp(ROOT);
+    // The channel's sha256 for the manifest is not the file's hash (portable-msvc.py does not check it either); the
+    // manifest comes over HTTPS from Microsoft, and every package payload it lists IS checked against its own sha256.
+    await download(item.url, cached);
+    return JSON.parse(fs.readFileSync(cached, 'utf8'));
+};
+/** .vsix contents are percent-encoded file names under Contents/; unpack them into the root, names decoded. */
+const unpackVsix = async (vsix, work) => {
+    const out = mkdirp(path.join(work, 'vsix-' + path.basename(vsix)));
+    await extractArchive(vsix, out, ['Contents']);
+    const decode = (dir) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const from = path.join(dir, entry.name);
+            let name = entry.name;
+            try {
+                if (name.includes('%'))
+                    name = decodeURIComponent(name);
+            }
+            catch { /* not percent-encoded after all */ }
+            const to = path.join(dir, name);
+            if (to !== from)
+                fs.renameSync(from, to);
+            if (entry.isDirectory())
+                decode(to);
+        }
+    };
+    decode(out);
+    fs.cpSync(path.join(out, 'Contents'), ROOT, { recursive: true, force: true });
+    safeRemove(out, work);
+};
+/** An administrative install only unpacks files; its verbose log explains a failure (e.g. a path over 260 characters). */
+const unpackMsi = async (msi) => {
+    const logFile = msi + '.log';
+    try {
+        await execAsync(system32('msiexec.exe'), ['/a', msi, '/quiet', '/qn', 'TARGETDIR=' + ROOT, '/l*v', logFile], { stdio: 'ignore' });
+    }
+    catch (e) {
+        const lines = exists(logFile) ? fs.readFileSync(logFile, 'utf16le').split(/\r?\n/).filter((l) => /error|return value 3|failed/i.test(l)).slice(-4).join(' | ') : '';
+        throw new Error(path.basename(msi) + ' did not unpack: ' + (e instanceof Error ? e.message : String(e)) + (lines ? ' (' + lines.slice(0, 600) + ')' : ''));
+    }
+};
+/** The manifest's packages by id, with the lookups the installer needs. */
+const catalogue = (m) => {
+    const byId = new Map();
+    for (const p of m.packages)
+        byId.set(p.id.toLowerCase(), [...(byId.get(p.id.toLowerCase()) ?? []), p]);
+    return {
+        ids: [...byId.keys()],
+        pick: (id) => byId.get(id.toLowerCase())?.find((p) => !p.language || p.language === 'en-US'),
+    };
+};
+/** Downloads (once, verified) into `work`; a verified file from an earlier attempt is reused. */
+const payloadFetcher = (work) => async (p) => {
+    const file = path.join(work, path.basename(p.fileName.replace(/\\/g, '/')));
+    if (!exists(file))
+        await download(p.url, file, p.sha256);
+    return file;
+};
+/** Newest folder under VC\Tools\MSVC that holds a compiler (named after the toolset, 14.44.35207, not the package version). */
+const unpackedToolset = () => {
+    const toolsRoot = path.join(ROOT, 'VC', 'Tools', 'MSVC');
+    return fs.readdirSync(toolsRoot).filter((d) => exists(hostBin(d, 'cl.exe'))).sort((a, b) => a.localeCompare(b, undefined, { numeric: true })).pop();
+};
+/** Downloads and unpacks MSVC and the Windows SDK into tools\msvc; resolves with the toolset and SDK folder names. */
+export const installPackages = async (config) => {
+    const { ids, pick } = catalogue(await manifest());
+    const version = pickMsvcVersion(ids, config.msvcVersion);
+    if (!version)
+        throw new Error('no MSVC ' + config.msvcVersion + ' in the Visual Studio manifest');
+    const sdk = pickWindowsSdk(ids, config.sdkVersion);
+    if (!sdk)
+        throw new Error('no Windows SDK ' + config.sdkVersion + ' in the Visual Studio manifest');
+    const work = mkdirp(path.join(ROOT, '.download'));
+    const fetchPayload = payloadFetcher(work);
+    log('Downloading the MSVC ' + version + ' compiler and C/C++ libraries ...');
+    for (const part of MSVC_PARTS) {
+        const p = pick('microsoft.vc.' + version + '.' + part);
+        if (!p && REQUIRED_PARTS.some((r) => part.startsWith(r)))
+            throw new Error('MSVC ' + version + ' has no ' + part);
+        for (const payload of p?.payloads ?? [])
+            await unpackVsix(await fetchPayload(payload), work);
+    }
+    for (const payload of pick('microsoft.visualcpp.dia.sdk')?.payloads ?? [])
+        await unpackVsix(await fetchPayload(payload), work);
+    // The SDK component depends on the package that holds the .msi/.cab payloads (e.g. Win11SDK_10.0.26100).
+    const sdkPackage = pick(Object.keys(pick(sdk.componentId)?.dependencies ?? {})[0] ?? '');
+    if (!sdkPackage?.payloads)
+        throw new Error('the Windows SDK ' + sdk.build + ' package has no payloads');
+    log('Downloading the Windows SDK ' + sdk.build + ' (headers, libraries; the biggest part) ...');
+    const payload = (name) => sdkPackage.payloads.find((p) => p.fileName.toLowerCase() === ('installers\\' + name).toLowerCase());
+    const msis = [];
+    for (const name of SDK_MSIS) {
+        const p = payload(name);
+        if (!p)
+            throw new Error('the Windows SDK package has no ' + name);
+        const file = await fetchPayload(p);
+        msis.push(file);
+        for (const cab of msiCabs(fs.readFileSync(file))) {
+            const c = payload(cab);
+            if (c)
+                await fetchPayload(c);
+        }
+    }
+    log('Unpacking the Windows SDK (a few minutes) ...');
+    for (const msi of msis)
+        await unpackMsi(msi);
+    // msiexec /a also copies every .msi into the target; they are not needed.
+    for (const name of fs.readdirSync(ROOT).filter((n) => n.toLowerCase().endsWith('.msi')))
+        fs.rmSync(path.join(ROOT, name), { force: true });
+    safeRemove(work, ROOT);
+    const sdkVersion = fs.readdirSync(path.join(ROOT, 'Windows Kits', '10', 'Include')).filter((d) => d.startsWith('10.0.' + sdk.build)).sort().pop();
+    if (!sdkVersion)
+        throw new Error('the Windows SDK did not unpack (no Include\\10.0.' + sdk.build + '.*)');
+    const toolset = unpackedToolset();
+    if (!toolset)
+        throw new Error('MSVC ' + version + ' did not unpack (no cl.exe under VC\\Tools\\MSVC)');
+    return { msvc: toolset, sdk: sdkVersion };
+};

package/dist/guest/toolchains/native/msvc/tree.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+export declare const ROOT: string;
+export declare const MARKER: string;
+export declare const msvcTools: (msvc: string, ...parts: string[]) => string;
+export declare const hostBin: (msvc: string, ...parts: string[]) => string;
+export declare const hasCompiler: (msvc: string) => boolean;
+declare const Installed: z.ZodObject<{
+    msvc: z.ZodString;
+    sdk: z.ZodString;
+    want: z.ZodString;
+}, z.core.$strip>;
+export type Installed = z.infer<typeof Installed>;
+/** What the last finished install recorded; null for a missing, unreadable or half-written marker. */
+export declare const readInstalled: () => Installed | null;
+export {};

package/dist/guest/toolchains/native/msvc/tree.js

@@ -0,0 +1,21 @@
+// Where the portable MSVC lives (tools\msvc) and what the last finished install recorded about it.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { exists } from '../../../env.js';
+import { tool } from '../../common.js';
+export const ROOT = tool('msvc');
+export const MARKER = path.join(ROOT, '.installed.json');
+export const msvcTools = (msvc, ...parts) => path.join(ROOT, 'VC', 'Tools', 'MSVC', msvc, ...parts);
+export const hostBin = (msvc, ...parts) => msvcTools(msvc, 'bin', 'Hostx64', 'x64', ...parts);
+export const hasCompiler = (msvc) => exists(hostBin(msvc, 'cl.exe'));
+const Installed = z.object({ msvc: z.string().min(1), sdk: z.string().min(1), want: z.string() });
+/** What the last finished install recorded; null for a missing, unreadable or half-written marker. */
+export const readInstalled = () => {
+    try {
+        return Installed.safeParse(JSON.parse(fs.readFileSync(MARKER, 'utf8'))).data ?? null;
+    }
+    catch {
+        return null;
+    }
+};

package/dist/guest/toolchains/native/rust.d.ts

@@ -0,0 +1,3 @@
+import type { Toolchains } from '../../../core/types.js';
+import { type ToolEnv } from '../common.js';
+export declare const setupRust: (env: ToolEnv, config: Toolchains["rust"], refresh: boolean) => Promise<void>;

package/dist/guest/toolchains/native/rust.js

@@ -0,0 +1,45 @@
+// Rust: rustup + cargo, with crates installed prebuilt where possible (binstall.ts).
+import path from 'node:path';
+import { dryRun, execAsync, exists, log } from '../../env.js';
+import { arch, downloadFile, installOnce, tool, versionOf } from '../common.js';
+import { crateInstaller } from './binstall.js';
+import { installedMsvcEnv } from './msvc/index.js';
+export const setupRust = async (env, config, refresh) => {
+    const RUSTUP_HOME = tool('rust', 'rustup');
+    const CARGO_HOME = tool('rust', 'cargo');
+    const rustEnv = { env: { ...process.env, RUSTUP_HOME, CARGO_HOME } };
+    const rustup = path.join(CARGO_HOME, 'bin', 'rustup.exe');
+    if (dryRun) {
+        log('(dry run) would provision Rust ' + config.toolchain + ' (' + config.host + ')');
+        return;
+    }
+    if (!exists(rustup)) {
+        const init = tool('rust', 'rustup-init.exe');
+        log('Installing Rust with rustup (~300 MB once; the toolchain downloads after rustup itself) ...');
+        await downloadFile('https://static.rust-lang.org/rustup/dist/' + (arch === 'arm64' ? 'aarch64' : 'x86_64') + '-pc-windows-msvc/rustup-init.exe', init);
+        await execAsync(init, ['-y', '--no-modify-path', '--profile', 'default', '--default-host', config.host, '--default-toolchain', config.toolchain], rustEnv);
+    }
+    else {
+        // The host can change (GNU <-> msvc with toolchains.msvc): install the toolchain for it; a no-op when it is there.
+        await execAsync(rustup, ['set', 'default-host', config.host], { ...rustEnv, stdio: 'ignore' });
+        await execAsync(rustup, ['toolchain', 'install', config.toolchain, '--profile', 'default', '--no-self-update'], { ...rustEnv, stdio: 'ignore' });
+        await execAsync(rustup, ['default', config.toolchain], { ...rustEnv, stdio: 'ignore' });
+        if (refresh)
+            await execAsync(rustup, ['update'], rustEnv);
+    }
+    Object.assign(env.vars, { RUSTUP_HOME, CARGO_HOME });
+    env.prepend.push(path.join(CARGO_HOME, 'bin'));
+    env.summary.push('rust: ' + versionOf(path.join(CARGO_HOME, 'bin', 'rustc.exe'), ['--version'], rustEnv) + ' [' + config.host + ']');
+    const toolchainKey = 'rustup@' + config.toolchain;
+    await installOnce(env, toolchainKey + ' components', config.components, (c) => execAsync(rustup, ['component', 'add', c], rustEnv));
+    await installOnce(env, toolchainKey + ' targets', config.targets, (t) => execAsync(rustup, ['target', 'add', t], rustEnv));
+    // cargo install links with MSVC's link.exe (msvc host) or MinGW's gcc (GNU host). Those steps ran first, but their
+    // PATH only reaches the agent at the end, so it is put together here.
+    const msvc = config.host.endsWith('-msvc') ? installedMsvcEnv() : null;
+    const mingw = tool('mingw', 'mingw64', 'bin');
+    const cargoEnv = msvc
+        ? { env: { ...rustEnv.env, ...msvc.vars, PATH: [path.join(CARGO_HOME, 'bin'), ...msvc.path, process.env.PATH ?? ''].join(path.delimiter) } }
+        : { env: { ...rustEnv.env, CARGO_TARGET_X86_64_PC_WINDOWS_GNU_LINKER: path.join(mingw, 'gcc.exe'), PATH: [path.join(CARGO_HOME, 'bin'), mingw, process.env.PATH ?? ''].join(path.delimiter) } };
+    // Prebuilt through cargo-binstall where the crate publishes a Windows build, else compiled (same "cargo" keys as before).
+    await installOnce(env, 'cargo', config.crates, crateInstaller(CARGO_HOME, cargoEnv));
+};

package/dist/guest/toolchains/node.js

@@ -4,8 +4,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { fetchJson, githubAsset, installArchive } from '../../shared/download.js';
+import { safeRemove } from '../../shared/safe-remove.js';
 import { copyNode, dryRun, errMsg, execAsync, exists, hostToolsDir, localDir, log, mkdirp, warn } from '../env.js';
 import { arch, installOnce, resolveCached, tool } from './common.js';
+import { duringSession } from '../project-context.js';
 import { pickNodeVersion, pickSpreadVersions } from './versions.js';
 const NVM_HOME = tool('nvm');
 const NVM_SYMLINK = path.join(localDir, 'nodejs');
@@ -41,7 +43,9 @@ const ensureNvm = async () => {
     if (exists(path.join(HOST_NVM, 'nvm.exe'))) {
         log('Copying nvm from this PC ...');
         mkdirp(NVM_HOME);
-        for (const file of fs.readdirSync(HOST_NVM).filter((f) => /\.(exe|cmd|vbs)$/i.test(f)))
+        // nvm.exe last: it is what marks the install as done, so an interrupted copy is redone.
+        const files = fs.readdirSync(HOST_NVM).filter((f) => /\.(exe|cmd|vbs)$/i.test(f)).sort((a, b) => Number(a.toLowerCase() === 'nvm.exe') - Number(b.toLowerCase() === 'nvm.exe'));
+        for (const file of files)
             fs.copyFileSync(path.join(HOST_NVM, file), path.join(NVM_HOME, file));
         return;
     }
@@ -61,10 +65,15 @@ const installNodeVersion = async (version) => {
         copyNode(fromHost, dir);
         return;
     }
-    log('nvm install ' + version + ' ...');
+    log('Downloading Node ' + version + ' (~30 MB once) ...');
     mkdirp(NVM_TEMP);
-    const out = await nvm(['install', version]);
-    fs.rmSync(NVM_TEMP, { recursive: true, force: true });
+    let out;
+    try {
+        out = await nvm(['install', version]);
+    }
+    finally {
+        safeRemove(NVM_TEMP, NVM_HOME);
+    }
     if (!exists(path.join(dir, 'node.exe')))
         throw new Error('nvm install ' + version + ' failed: ' + out.trim().split('\n').slice(-2).join(' '));
 };
@@ -102,9 +111,15 @@ export const setupNode = async (env, versions, config) => {
             warn('Node ' + version + ' from this PC: ' + errMsg(e));
         }
     }
-    await activate(main);
     Object.assign(env.vars, { NVM_HOME, NVM_SYMLINK });
-    env.prepend.push(NVM_HOME, NVM_SYMLINK);
+    // At boot, nvm's symlink selects the version. A project added later must not switch it under the sessions already
+    // running: its own version's folder goes first on its sessions' PATH instead.
+    if (duringSession())
+        env.prepend.push(path.join(NVM_HOME, 'v' + main), NVM_HOME, NVM_SYMLINK);
+    else {
+        await activate(main);
+        env.prepend.push(NVM_HOME, NVM_SYMLINK);
+    }
     env.summary.push('node: ' + main + ' (from ' + versions.node.source + ', switch with nvm use)');
     await packageManagers(env, config, main);
 };
@@ -122,6 +137,11 @@ const packageManagers = async (env, config, version) => {
     // Without a packageManager pin, corepack's own known-good versions: the newest pnpm can be one this corepack cannot
     // start. Mapped folders allow no symlinks, so pnpm uses a flat (hoisted) node_modules instead of its linked layout.
     Object.assign(env.vars, { COREPACK_HOME: tool('corepack'), COREPACK_ENABLE_DOWNLOAD_PROMPT: '0', COREPACK_DEFAULT_TO_LATEST: '0', npm_config_node_linker: 'hoisted' });
+    // The shims are shared by every session: a project added later keeps the ones made at boot.
+    if (duringSession() && exists(tool('bin', 'pnpm.cmd'))) {
+        env.summary.push('pnpm, yarn: via corepack');
+        return;
+    }
     try {
         await execAsync(path.join(dir, 'node.exe'), [corepackJs, 'enable', '--install-directory', mkdirp(tool('bin')), 'pnpm', 'yarn'], { env: nodeEnv, stdio: 'ignore' });
         env.summary.push('pnpm, yarn: via corepack (package.json "packageManager" picks the version)');

package/dist/guest/toolchains/plan.d.ts

@@ -0,0 +1,24 @@
+import type { Config, DatabasePlan, GitAccess, Toolchains, ToolVersions } from '../../core/types.js';
+import { type ToolEnv } from './common.js';
+/** apps: the boot only (apps are machine-wide; a project that joins later shares them). */
+export interface ToolchainOptions {
+    gitEnabled: boolean;
+    gitAccess: GitAccess;
+    hostGit: boolean;
+    refresh: boolean;
+    databases: DatabasePlan[];
+    apps?: Config['apps'];
+}
+/**
+ * shared: the step's effect is machine-wide and the same for every project (an installer, a registry entry, a
+ * shortcut, the git guard). A project added after boot reuses what the boot's run contributed instead of running it
+ * again under the sessions that already use it.
+ */
+export interface Step {
+    name: string;
+    on: boolean;
+    after?: string[];
+    shared?: boolean;
+    run: (env: ToolEnv) => Promise<void> | void;
+}
+export declare const plan: (config: Toolchains, versions: ToolVersions, o: ToolchainOptions) => Step[];

package/dist/guest/toolchains/plan.js

@@ -0,0 +1,140 @@
+// Which toolchain and database steps this sandbox runs, in the order their PATH entries are listed, and what each
+// step depends on. The scheduler (index.ts) runs them.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { appsNeedMesa, setupApps } from '../apps/index.js';
+import { dataDir, dryRun, execAsync, exists, localDir, mkdirp } from '../env.js';
+import { ensureCompiled } from '../helpers.js';
+import { arch, installOnce, tool, wanted } from './common.js';
+import { DATABASE_NAMES, setupDatabase } from './databases/index.js';
+import { setupGit } from './git.js';
+import { setupGo } from './go.js';
+import { setupJava } from './java.js';
+import { setupCli } from './cli.js';
+import { setupPyenv, setupVolta, wantsPyenv, wantsVolta } from './managers.js';
+import { setupCpp } from './native/cpp.js';
+import { setupDotnet } from './native/dotnet.js';
+import { setupMesa } from './native/mesa.js';
+import { setupMsvc } from './native/msvc/index.js';
+import { setupRust } from './native/rust.js';
+import { setupNode } from './node.js';
+import { setupPwsh } from './pwsh.js';
+import { setupPython } from './python.js';
+import { setupBun, setupDeno, setupUv, uvVars } from './runtimes.js';
+import { setupPhp } from './scripting/php.js';
+import { setupRuby } from './scripting/ruby.js';
+import { setupVcRuntime } from './scripting/vcruntime.js';
+import { setupVscode } from './vscode.js';
+/** Python command-line tools through uv (each in its own environment, commands in uv's bin folder on PATH). */
+const setupPythonTools = async (env, tools) => {
+    const uv = tool('uv', 'uv.exe');
+    if (!exists(uv))
+        throw new Error('toolchains.python.tools needs uv (toolchains.uv.enabled)');
+    await installOnce(env, 'uv tool', tools, (pkg) => execAsync(uv, ['tool', 'install', pkg], { env: { ...process.env, ...uvVars() } }));
+};
+/**
+ * Where cargo builds: shared with the PC's target\, one on the sandbox's disk, or a path. "separate" sets no variable:
+ * the cargo shim (sandbox/cargoshim.cs) gives every checkout its own target\sandbox, so git worktrees of several agents
+ * never overwrite each other's builds.
+ */
+const cargoTarget = (targetDir) => {
+    if (targetDir === 'shared' || targetDir === 'separate')
+        return null;
+    if (targetDir === 'local')
+        return path.join(localDir, 'cargo-target');
+    return targetDir;
+};
+/** "separate": tools\shims\cargo\cargo.exe in front of the real cargo, which it runs with the checkout's target dir. */
+const cargoShim = (env, rust) => {
+    const real = path.join(tool('rust', 'cargo', 'bin'), 'cargo.exe');
+    if (rust.targetDir !== 'separate' || !exists(real))
+        return;
+    const dir = mkdirp(tool('shims', 'cargo'));
+    fs.copyFileSync(ensureCompiled('cargoshim'), path.join(dir, 'cargo.exe'));
+    env.prepend.unshift(dir);
+    env.vars.AGENT_REAL_CARGO = real;
+};
+/**
+ * Cargo defaults that fit Windows, written only when there is no $CARGO_HOME\config.toml yet: fewer parallel jobs
+ * (parallel rustc ran out of paging file) and, for the GNU host, only line tables as debug info (full debug info made
+ * test executables bigger than the 2 GB Windows allows).
+ */
+const cargoDefaults = (host) => {
+    const file = tool('rust', 'cargo', 'config.toml');
+    if (exists(file) || !exists(path.dirname(file)))
+        return;
+    // Several agents often build at once: up to 4 jobs each (8 each crashed Windows inside the sandbox on 13 Oct 2026).
+    const jobs = Math.max(2, Math.min(4, Math.floor(os.cpus().length / 4)));
+    const gnu = host.endsWith('-gnu');
+    fs.writeFileSync(file, [
+        '# Written by windows-development-sandbox once; edit freely, it is never overwritten.',
+        '[build]', 'jobs = ' + jobs, '',
+        ...(gnu ? ['[profile.dev]', 'debug = "line-tables-only"', '', '[profile.test]', 'debug = "line-tables-only"', ''] : []),
+    ].join('\n'));
+};
+/**
+ * Where cargo builds and where sccache keeps its cache. Cargo fingerprints hold absolute paths and the host toolchain,
+ * so a target\\ shared with builds on the PC rebuilds every time the side changes: "separate" (the default) keeps a
+ * sandbox one next to it. sccache's cache persists unless the project sets SCCACHE_DIR itself.
+ */
+const rustCaches = (rust) => {
+    const target = cargoTarget(rust.targetDir);
+    return { ...(target ? { CARGO_TARGET_DIR: target } : {}), ...(process.env.SCCACHE_DIR ? {} : { SCCACHE_DIR: path.join(dataDir, 'cache', 'sccache') }) };
+};
+/** "auto": the msvc host when the MSVC step runs (as on most PCs), else GNU with MinGW. */
+const rustHost = (config) => {
+    if (config.rust.host !== 'auto')
+        return config.rust.host;
+    const cpu = arch === 'arm64' ? 'aarch64' : 'x86_64';
+    return cpu + (wanted(config.msvc.enabled, 'msvc') ? '-pc-windows-msvc' : '-pc-windows-gnu');
+};
+export const plan = (config, versions, o) => {
+    const apps = Boolean(o.apps && (o.apps.install.length || Object.keys(o.apps.custom).length));
+    const java = wanted(config.java.enabled, 'java');
+    const python = wanted(config.python.enabled, 'python');
+    return [
+        { name: 'Git', on: o.gitEnabled, shared: true, run: (env) => setupGit(env, o.hostGit, o.refresh, o.gitAccess) },
+        // Before Node: with package.json pins, Volta's node/npm/pnpm/yarn come first on PATH.
+        { name: 'Volta', on: wantsVolta(config.node.volta), run: (env) => setupVolta(env) },
+        { name: 'Node ' + versions.node.spec, on: true, run: (env) => setupNode(env, versions, config.node) },
+        { name: 'Python', on: python, run: (env) => setupPython(env, config.python, versions) },
+        { name: 'pyenv-win', on: python && wantsPyenv(config.python.pyenv), run: (env) => setupPyenv(env) },
+        { name: 'C/C++', on: wanted(config.cpp.enabled, 'cpp') || wanted(config.rust.enabled, 'rust'), run: (env) => setupCpp(env, config.cpp) },
+        { name: 'MSVC', on: wanted(config.msvc.enabled, 'msvc'), run: (env) => setupMsvc(env, config.msvc) },
+        // Rust links with MSVC (msvc host) or MinGW's gcc (GNU host): whichever it uses goes first.
+        {
+            name: 'Rust', on: wanted(config.rust.enabled, 'rust'), after: ['C/C++', 'MSVC'],
+            run: async (env) => {
+                await setupRust(env, { ...config.rust, host: rustHost(config) }, o.refresh);
+                Object.assign(env.vars, rustCaches(config.rust));
+                if (!dryRun) {
+                    cargoDefaults(rustHost(config));
+                    cargoShim(env, config.rust);
+                }
+            },
+        },
+        { name: '.NET', on: wanted(config.dotnet.enabled, 'dotnet'), run: (env) => setupDotnet(env, config.dotnet, o.refresh) },
+        { name: 'Go', on: wanted(config.go.enabled, 'go'), run: (env) => setupGo(env, config.go) },
+        { name: 'Java', on: java, run: (env) => setupJava(env, config.java) },
+        { name: 'Ruby', on: wanted(config.ruby.enabled, 'ruby'), run: (env) => setupRuby(env, config.ruby) },
+        // PHP installs the Visual C++ runtime itself: one installer at a time.
+        // Many apps (bat, delta, Neovim, most GUIs, your own programs) are built against it too.
+        { name: 'Visual C++ runtime', on: config.vcRuntime.enabled || apps, shared: true, run: async (env) => { await setupVcRuntime(env); } },
+        { name: 'PHP', on: wanted(config.php.enabled, 'php'), after: ['Visual C++ runtime'], run: (env) => setupPhp(env, config.php) },
+        { name: 'Deno', on: wanted(config.deno.enabled, 'deno'), run: (env) => setupDeno(env) },
+        { name: 'Bun', on: config.bun.enabled, run: (env) => setupBun(env) },
+        { name: 'uv', on: config.uv.enabled, run: (env) => setupUv(env) },
+        { name: 'PowerShell 7', on: wanted(config.pwsh.enabled, 'pwsh'), run: (env) => setupPwsh(env, o.refresh) },
+        // The openssl tool comes from Git's install: after Git.
+        { name: 'CLI tools', on: Object.values(config.cli).some((v) => v !== false), after: ['Git'], run: (env) => setupCli(env, config.cli, o.gitAccess, o.refresh) },
+        { name: 'Mesa 3D', on: config.mesa.enabled || appsNeedMesa(o.apps), shared: true, run: (env) => setupMesa(env, config.mesa) },
+        { name: 'VS Code', on: config.vscode.enabled, shared: true, run: (env) => setupVscode(env, o.refresh) },
+        // Desktop apps and extra tools (apps.install / apps.custom); games and 3D apps copy Mesa's OpenGL next to them.
+        { name: 'Apps', on: apps, shared: true, after: ['Mesa 3D', 'Visual C++ runtime'], run: (env) => setupApps(env, o.apps, { gitAccess: o.gitAccess, refresh: o.refresh }) },
+        { name: 'Python tools', on: python && config.python.tools.length > 0, after: ['Python', 'uv'], run: (env) => setupPythonTools(env, config.python.tools) },
+        // DynamoDB Local runs on Java: the Java step installs the JDK first instead of racing it.
+        // One server per database in the sandbox: a project that joins later shares the one the boot started.
+        ...o.databases.map((db) => ({ name: DATABASE_NAMES[db.database], on: true, shared: true, after: db.database === 'dynamodb' && java ? ['Java'] : [], run: (env) => setupDatabase(env, db) })),
+    ];
+};

package/dist/guest/toolchains/pwsh.js

@@ -8,7 +8,7 @@ import { setupSingleExe } from './runtimes.js';
 export const pwshDir = () => tool('pwsh');
 export const setupPwsh = async (env, refresh = false) => {
     // pwsh.exe sits at the zip's root next to its runtime and modules: the whole folder is kept.
-    await setupSingleExe(env, 'pwsh', 'PowerShell/PowerShell', pwshAsset(arch), 'pwsh.exe', pwshDir(), { refresh, versionArgs: ['-Version'], note: ' (PowerShell 7; powershell is still 5.1)' });
+    await setupSingleExe(env, 'pwsh', 'PowerShell/PowerShell', pwshAsset(arch), 'pwsh.exe', pwshDir(), { refresh, size: '100 MB', versionArgs: ['-Version'], note: ' (PowerShell 7; powershell is still 5.1)' });
     // No update banner or telemetry from a copy that provisioning.refresh replaces anyway.
     Object.assign(env.vars, { POWERSHELL_UPDATECHECK: 'Off', POWERSHELL_TELEMETRY_OPTOUT: '1' });
 };