windows-development-sandbox 0.0.0-stage → 1.1.0

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

@@ -0,0 +1,7 @@
+import type { SpawnOptions } from 'node:child_process';
+/**
+ * Returns the installer for one crate: `cargo binstall` (prebuilt only: its own compile fallback is off, so a crate
+ * without a Windows build is compiled by our `cargo install` with the linker settings in `cargoEnv`), then
+ * `cargo install --locked`. cargo-binstall is fetched on first use, so boots with every crate installed download nothing.
+ */
+export declare const crateInstaller: (cargoHome: string, cargoEnv: SpawnOptions) => ((crate: string) => Promise<void>);

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

@@ -0,0 +1,52 @@
+// toolchains.rust.crates with prebuilt binaries: cargo-binstall (from its own GitHub release) fetches a crate's
+// published Windows build in seconds; only crates without one are compiled with `cargo install --locked`.
+import fs from 'node:fs';
+import path from 'node:path';
+import { errMsg, execAsync, exists, log, warn } from '../../env.js';
+import { binstallAsset } from '../catalogue.js';
+import { arch, installFromGithub, tool } from '../common.js';
+/**
+ * cargo-binstall.exe into CARGO_HOME\bin (so `cargo binstall` works for the agent too). Downloaded into its own
+ * tools\cargo-binstall folder first: installArchive replaces its destination, which must never be cargo's bin.
+ */
+const ensureBinstall = async (cargoBin) => {
+    const target = path.join(cargoBin, 'cargo-binstall.exe');
+    if (exists(target))
+        return true;
+    try {
+        const dir = tool('cargo-binstall');
+        if (!exists(path.join(dir, 'cargo-binstall.exe'))) {
+            await installFromGithub('cargo-bins/cargo-binstall', binstallAsset(arch), { dest: dir, what: 'cargo-binstall for prebuilt Rust tools (~10 MB once)', locate: 'cargo-binstall.exe' });
+        }
+        fs.copyFileSync(path.join(dir, 'cargo-binstall.exe'), target);
+        return true;
+    }
+    catch (e) {
+        warn('cargo-binstall unavailable, compiling crates with cargo install instead: ' + errMsg(e));
+        return false;
+    }
+};
+/**
+ * Returns the installer for one crate: `cargo binstall` (prebuilt only: its own compile fallback is off, so a crate
+ * without a Windows build is compiled by our `cargo install` with the linker settings in `cargoEnv`), then
+ * `cargo install --locked`. cargo-binstall is fetched on first use, so boots with every crate installed download nothing.
+ */
+export const crateInstaller = (cargoHome, cargoEnv) => {
+    const cargo = path.join(cargoHome, 'bin', 'cargo.exe');
+    let binstall = null;
+    // quick-install's install statistics are opt-out; the sandbox opts out.
+    const binstallEnv = { ...cargoEnv, env: { ...(cargoEnv.env ?? process.env), BINSTALL_DISABLE_TELEMETRY: 'true' } };
+    return async (crate) => {
+        binstall ??= ensureBinstall(path.join(cargoHome, 'bin'));
+        if (await binstall) {
+            try {
+                await execAsync(cargo, ['binstall', '--no-confirm', '--locked', '--disable-strategies', 'compile', crate], binstallEnv);
+                return;
+            }
+            catch {
+                log('No prebuilt ' + crate + ' for Windows; compiling it with cargo (takes a few minutes) ...');
+            }
+        }
+        await execAsync(cargo, ['install', '--locked', crate], cargoEnv);
+    };
+};

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

@@ -0,0 +1,4 @@
+import type { Toolchains } from '../../../core/types.js';
+import { type ToolEnv } from '../common.js';
+/** MinGW-w64 GCC from WinLibs: gcc/g++/mingw32-make for the agent, and the linker for Rust's GNU host. */
+export declare const setupCpp: (env: ToolEnv, config: Toolchains["cpp"]) => Promise<void>;

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

@@ -0,0 +1,38 @@
+// C/C++: MinGW-w64 GCC (with CMake, Ninja, make) and the flex/bison parser generators.
+import path from 'node:path';
+import { dryRun, exists, log, warn } from '../../env.js';
+import { arch, installFromGithub, tool, versionOf } from '../common.js';
+import { CMAKE_FLOOR, cmakeTooOld } from '../versions.js';
+/** MinGW-w64 GCC from WinLibs: gcc/g++/mingw32-make for the agent, and the linker for Rust's GNU host. */
+export const setupCpp = async (env, config) => {
+    const bin = tool('mingw', 'mingw64', 'bin');
+    const gcc = path.join(bin, 'gcc.exe');
+    if (dryRun) {
+        log('(dry run) would provision MinGW-w64 GCC');
+        return;
+    }
+    if (!exists(gcc)) {
+        const pattern = arch === 'arm64' ? /^winlibs-aarch64-.*\.zip$/ : /^winlibs-x86_64-posix-seh-gcc-.*\.zip$/;
+        await installFromGithub('brechtsanders/winlibs_mingw', pattern, { dest: tool('mingw'), what: 'the C/C++ compiler, MinGW-w64 GCC with CMake and Ninja (~270 MB once)', searchOlder: true });
+    }
+    if (!exists(gcc))
+        throw new Error('gcc.exe missing after installing MinGW');
+    // Appended (not prepended) so MinGW's tools never shadow Windows or toolchain commands of the same name.
+    env.append.unshift(bin);
+    env.vars.CARGO_TARGET_X86_64_PC_WINDOWS_GNU_LINKER = gcc;
+    const cmake = versionOf(path.join(bin, 'cmake.exe'));
+    if (cmakeTooOld(cmake))
+        warn('The bundled CMake ' + cmake + ' is older than ' + CMAKE_FLOOR + ', which many projects need; set toolchains.cpp.enabled to refresh it, or install a newer CMake into C:\\AgentData\\tools\\bin.');
+    env.summary.push('gcc: ' + versionOf(gcc) + ' (MinGW-w64, with cmake ' + cmake + ', ninja, premake5)');
+    if (config.flexBison)
+        await setupFlexBison(env);
+};
+/** win_flex / win_bison (CMake's FindFLEX/FindBISON look for these names). Kept with the C/C++ tools on PATH. */
+const setupFlexBison = async (env) => {
+    const dir = tool('winflexbison');
+    if (!exists(path.join(dir, 'win_bison.exe'))) {
+        await installFromGithub('lexxmark/winflexbison', /^win_flex_bison-[\d.]+\.zip$/, { dest: dir, what: 'win_flex / win_bison (~1 MB once)', locate: 'win_bison.exe' });
+    }
+    env.append.push(dir);
+    env.summary.push('win_flex/win_bison: ' + versionOf(path.join(dir, 'win_bison.exe')));
+};

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

@@ -0,0 +1,4 @@
+import type { Toolchains } from '../../../core/types.js';
+import { type ToolEnv } from '../common.js';
+/** .NET SDK channels from config plus whatever the workspace's global.json pins. Installs are remembered in a marker. */
+export declare const setupDotnet: (env: ToolEnv, config: Toolchains["dotnet"], refresh: boolean) => Promise<void>;

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

@@ -0,0 +1,103 @@
+// .NET: the SDK (dotnet-install.ps1), .NET Framework reference assemblies for old-style projects, and .NET Framework 3.5.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { fetchJson, installArchive } from '../../../shared/download.js';
+import { readJsonFile, writeJsonAtomic } from '../../../shared/rundir.js';
+import { safeRemove } from '../../../shared/safe-remove.js';
+import { SYSTEM } from '../../../shared/system.js';
+import { dataDir, dryRun, errMsg, execAsync, execOutput, exists, log, mkdirp, warn } from '../../env.js';
+import { projectWorkspace } from '../../project-context.js';
+import { downloadFile, installOnce, tool } from '../common.js';
+/** tools\dotnet\.agent-sandbox-installed.json: which install keys (channel:8.0, global.json:...) already ran. */
+const DotnetMarker = z.record(z.string(), z.boolean());
+/** .NET SDK channels from config plus whatever the workspace's global.json pins. Installs are remembered in a marker. */
+export const setupDotnet = async (env, config, refresh) => {
+    const root = tool('dotnet');
+    const marker = path.join(root, '.agent-sandbox-installed.json');
+    const script = tool('dotnet-install.ps1');
+    if (dryRun) {
+        log('(dry run) would provision .NET SDK channels ' + config.channels.join(', '));
+        return;
+    }
+    // A corrupt or hand-edited marker just means "nothing recorded yet" (the installs are idempotent).
+    const recorded = DotnetMarker.safeParse(exists(marker) && !refresh ? readJsonFile(marker) : {});
+    const done = recorded.success ? recorded.data : {};
+    const globalJson = path.join(projectWorkspace(), 'global.json');
+    const installs = [
+        ...config.channels.map((c) => ['channel:' + c, ['-Channel', c]]),
+        ...(exists(globalJson) ? [['global.json:' + fs.readFileSync(globalJson, 'utf8').replace(/\s+/g, ''), ['-JSonFile', globalJson]]] : []),
+    ];
+    for (const [key, args] of installs.filter(([k]) => !done[k])) {
+        // Fetched every time something is installed (it is small): an interrupted earlier download must not be run.
+        await downloadFile('https://dot.net/v1/dotnet-install.ps1', script);
+        log('Installing the .NET SDK ' + (key.startsWith('channel:') ? key.slice(8) : 'pinned in global.json') + ' (~250 MB once) ...');
+        await execAsync(SYSTEM.powershell(), ['-NoLogo', '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', script, ...args, '-InstallDir', root, '-NoPath']);
+        done[key] = true;
+        writeJsonAtomic(marker, done);
+    }
+    const home = mkdirp(tool('dotnet-home'));
+    Object.assign(env.vars, { DOTNET_ROOT: root, DOTNET_CLI_HOME: home, DOTNET_CLI_TELEMETRY_OPTOUT: '1', DOTNET_NOLOGO: '1', DOTNET_SKIP_FIRST_TIME_EXPERIENCE: '1', NUGET_PACKAGES: tool('nuget', 'packages') });
+    env.prepend.push(root, path.join(home, '.dotnet', 'tools'));
+    env.summary.push('dotnet: ' + execOutput(path.join(root, 'dotnet.exe'), ['--list-sdks']).split(/\r?\n/).map((l) => l.split(' ')[0]).filter(Boolean).join(', '));
+    const dotnet = path.join(root, 'dotnet.exe');
+    const dotnetEnv = { env: { ...process.env, ...env.vars, PATH: root + path.delimiter + (process.env.PATH ?? '') } };
+    await installOnce(env, 'dotnet workload', config.workloads, (w) => execAsync(dotnet, ['workload', 'install', w, '--skip-manifest-update'], dotnetEnv));
+    await installOnce(env, 'dotnet tool', config.tools, (t) => execAsync(dotnet, ['tool', 'install', '--global', t], dotnetEnv));
+    await setupFrameworkReferences(env, config.frameworkTargets);
+    if (config.netfx35)
+        await setupNetFx35(env);
+};
+/**
+ * .NET Framework reference assemblies (the "targeting packs" Visual Studio would install) from NuGet, so net4x projects,
+ * old-style .csproj included, build with the SDK's MSBuild. MSBuild reads TargetFrameworkRootPath from the environment.
+ * Running .NET Framework 4.8 apps needs nothing: Windows ships it.
+ */
+const setupFrameworkReferences = async (env, targets) => {
+    if (!targets.length)
+        return;
+    const root = tool('netfx-references');
+    for (const target of targets) {
+        const id = 'microsoft.netframework.referenceassemblies.' + target.toLowerCase();
+        const marker = path.join(root, '.installed-' + target.toLowerCase());
+        if (exists(marker))
+            continue;
+        const staging = tool('netfx-references-' + target.toLowerCase());
+        try {
+            const { versions } = await fetchJson('https://api.nuget.org/v3-flatcontainer/' + id + '/index.json');
+            const version = versions.filter((v) => /^\d+(\.\d+)*$/.test(v)).pop();
+            if (!version)
+                throw new Error('no stable version of ' + id);
+            log('Downloading the .NET Framework ' + target + ' reference assemblies (~30 MB once) ...');
+            await installArchive('https://api.nuget.org/v3-flatcontainer/' + id + '/' + version + '/' + id + '.' + version + '.nupkg', staging, { fileName: id + '.zip' });
+            fs.cpSync(path.join(staging, 'build', '.NETFramework'), path.join(root, '.NETFramework'), { recursive: true });
+            fs.writeFileSync(marker, version);
+        }
+        catch (e) {
+            warn('.NET Framework ' + target + ' reference assemblies could not be installed (projects targeting it will not build): ' + errMsg(e));
+        }
+        finally {
+            safeRemove(staging, dataDir);
+        }
+    }
+    if (!exists(path.join(root, '.NETFramework')))
+        return;
+    env.vars.TargetFrameworkRootPath = root + path.sep;
+    env.summary.push('.NET Framework targeting: ' + fs.readdirSync(path.join(root, '.NETFramework')).join(', '));
+};
+/** .NET Framework 3.5 is a Windows feature the sandbox image lacks; DISM fetches it from Windows Update on every boot. */
+const setupNetFx35 = async (env) => {
+    if (execOutput(SYSTEM.reg(), ['query', 'HKLM\\SOFTWARE\\Microsoft\\NET Framework Setup\\NDP\\v3.5', '/v', 'Install']).includes('0x1')) {
+        env.summary.push('.NET Framework 3.5: on');
+        return;
+    }
+    log('Enabling .NET Framework 3.5 (downloads from Windows Update, a few minutes) ...');
+    try {
+        await execAsync(SYSTEM.dism(), ['/Online', '/Enable-Feature', '/FeatureName:NetFx3', '/All', '/NoRestart', '/Quiet'], { stdio: 'ignore' });
+        env.summary.push('.NET Framework 3.5: on');
+    }
+    catch (e) {
+        warn('.NET Framework 3.5 could not be enabled: ' + errMsg(e));
+        env.summary.push('.NET Framework 3.5: FAILED');
+    }
+};

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

@@ -0,0 +1,7 @@
+import type { Toolchains } from '../../../core/types.js';
+import { type ToolEnv } from '../common.js';
+/**
+ * Mesa 3D for Windows (llvmpipe): OpenGL 4.5 on the CPU when the sandbox has no GPU. Windows only offers OpenGL 1.1 in
+ * software, and opengl32.dll cannot be replaced system-wide, so programs pick Mesa up from their own folder.
+ */
+export declare const setupMesa: (env: ToolEnv, config: Toolchains["mesa"]) => Promise<void>;

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

@@ -0,0 +1,46 @@
+// Mesa for running OpenGL and Vulkan programs without a GPU (llvmpipe, lavapipe).
+import path from 'node:path';
+import { installArchive } from '../../../shared/download.js';
+import { SYSTEM } from '../../../shared/system.js';
+import { dryRun, execAsync, exists, log } from '../../env.js';
+import { arch, installFromGithub, tool } from '../common.js';
+/**
+ * Mesa 3D for Windows (llvmpipe): OpenGL 4.5 on the CPU when the sandbox has no GPU. Windows only offers OpenGL 1.1 in
+ * software, and opengl32.dll cannot be replaced system-wide, so programs pick Mesa up from their own folder.
+ */
+export const setupMesa = async (env, config) => {
+    if (dryRun) {
+        log('(dry run) would provision Mesa 3D');
+        return;
+    }
+    const root = tool('mesa');
+    const dir = path.join(root, arch === 'arm64' ? 'arm64' : 'x64');
+    if (!exists(path.join(dir, 'opengl32.dll'))) {
+        await installFromGithub('pal1000/mesa-dist-win', /^mesa3d-[\d.]+-release-msvc\.7z$/, { dest: root, what: 'Mesa 3D for software OpenGL (~100 MB once)', locate: 'opengl32.dll', up: 1 });
+    }
+    Object.assign(env.vars, { MESA_DIR: dir, GALLIUM_DRIVER: 'llvmpipe' });
+    env.summary.push('mesa (software OpenGL 4.5): copy opengl32.dll + libgallium_wgl.dll from %MESA_DIR% next to a game\'s .exe');
+    if (config.vulkan)
+        await setupLavapipe(env, dir);
+};
+const VULKAN_RUNTIME = 'https://sdk.lunarg.com/sdk/download/latest/windows/vulkan-runtime-components.zip';
+/**
+ * Software Vulkan: Mesa's lavapipe plus the Khronos loader (vulkan-1.dll, from LunarG's runtime components; Windows
+ * Sandbox has no Vulkan loader). The loader ignores VK_DRIVER_FILES in elevated processes, and everything in the
+ * sandbox runs elevated, so lavapipe is registered where the loader looks (HKLM; the registry is new every boot).
+ */
+const setupLavapipe = async (env, mesaDir) => {
+    const icd = path.join(mesaDir, arch === 'arm64' ? 'lvp_icd.aarch64.json' : 'lvp_icd.x86_64.json');
+    if (!exists(icd))
+        throw new Error('this Mesa build has no lavapipe (' + path.basename(icd) + ')');
+    const dir = tool('vulkan');
+    if (!exists(path.join(dir, 'vulkan-1.dll'))) {
+        log('Downloading the Vulkan loader (~10 MB once) ...');
+        // LunarG publishes no checksum for this zip; it comes over HTTPS from LunarG, the Khronos SDK's maintainer.
+        // The zip has x86 and x64 folders: only the 64-bit loader (and vulkaninfo) is extracted.
+        await installArchive(VULKAN_RUNTIME, dir, { locate: 'vulkan-1.dll', fileName: 'vulkan-runtime.zip', members: ['*/x64/*'] });
+    }
+    await execAsync(SYSTEM.reg(), ['add', 'HKLM\\SOFTWARE\\Khronos\\Vulkan\\Drivers', '/v', icd, '/t', 'REG_DWORD', '/d', '0', '/f'], { stdio: 'ignore' });
+    env.prepend.push(dir);
+    env.summary.push('vulkan: lavapipe (software Vulkan 1.4 on the CPU), vulkaninfo on PATH; WGPU_BACKEND=vulkan for wgpu');
+};

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

@@ -0,0 +1,16 @@
+export interface VcEnv {
+    vars: Record<string, string>;
+    path: string[];
+}
+/** Variables vcvars64.bat would set for this tree (host x64, target x64). */
+export declare const vcvars: (root: string, msvc: string, sdk: string) => VcEnv;
+/** vcvars64.bat / vcvarsall.bat in the usual place, for scripts that `call` them. */
+export declare const writeVcvars: (env: VcEnv) => void;
+/** vswhere.exe where Visual Studio's installer would put it, answering with this tree. */
+export declare const installVswhere: (msvc: string) => void;
+/**
+ * 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 declare const removeTelemetry: (msvc: string) => void;

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>;