windows-development-sandbox 0.0.0-stage → 1.0.5

package/dist/guest/toolchains/index.js

@@ -0,0 +1,122 @@
+import path from 'node:path';
+import { dataDir, execAsync, exists, localDir, log, mkdirp, setSandboxStatus, workspace } from '../env.js';
+import { arch, emptyEnv, installOnce, step, tool, wanted } from './common.js';
+import { DATABASE_NAMES, setupDatabase } from './databases.js';
+import { setupGit } from './git.js';
+import { setupGo } from './go.js';
+import { setupJava } from './java.js';
+import { setupMsvc } from './msvc.js';
+import { setupPwsh } from './pwsh.js';
+import { setupCli } from './cli.js';
+import { setupPyenv, setupVolta, wantsPyenv, wantsVolta } from './managers.js';
+import { setupNode } from './node.js';
+import { setupPython } from './python.js';
+import { setupCpp, setupDotnet, setupMesa, setupRust } from './native.js';
+import { setupBun, setupDeno, setupUv, uvVars } from './runtimes.js';
+import { setupPhp, setupRuby, setupVcRuntime } from './scripting.js';
+import { setupVscode } from './vscode.js';
+export { pickNodeVersion, pickPackageVersion } from './versions.js';
+/** How many installers run at once: enough to overlap downloads with installs, few enough not to thrash the disk. */
+const PARALLEL = 4;
+/** 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 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 = rust.targetDir === 'shared' ? null
+        : rust.targetDir === 'separate' ? path.join(workspace, 'target', 'sandbox')
+            : rust.targetDir === 'local' ? path.join(localDir, 'cargo-target')
+                : 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;
+    return (arch === 'arm64' ? 'aarch64' : 'x86_64') + (wanted(config.msvc.enabled, 'msvc') ? '-pc-windows-msvc' : '-pc-windows-gnu');
+};
+/** The toolchains and databases for this sandbox, in the order their PATH entries are listed. */
+const plan = (config, versions, o) => {
+    const java = wanted(config.java.enabled, 'java');
+    return [
+        { name: 'Git', on: o.gitEnabled, 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: wanted(config.python.enabled, 'python'), run: (env) => setupPython(env, config.python, versions) },
+        { name: 'pyenv-win', on: wanted(config.python.enabled, '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)); } },
+        { 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.
+        { name: 'Visual C++ runtime', on: config.vcRuntime.enabled, 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, run: (env) => setupMesa(env, config.mesa) },
+        { name: 'VS Code', on: config.vscode.enabled, run: (env) => setupVscode(env, o.refresh) },
+        { name: 'Python tools', on: wanted(config.python.enabled, '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.
+        ...o.databases.map((db) => ({ name: DATABASE_NAMES[db.database], on: true, after: db.database === 'dynamodb' && java ? ['Java'] : [], run: (env) => setupDatabase(env, db) })),
+    ];
+};
+/** Provisions every enabled toolchain and database, and returns the combined environment for the agent. */
+export const setupToolchains = async (config, versions, options) => {
+    const steps = plan(config, versions, options).filter((s) => s.on);
+    const envs = new Map(steps.map((s) => [s.name, emptyEnv()]));
+    const finished = new Map();
+    const running = new Set();
+    const waiting = [];
+    let done = 0;
+    const report = () => { if (running.size)
+        setSandboxStatus('provisioning', 'Installing ' + [...running].join(', ') + ' (' + done + ' of ' + steps.length + ' done)'); };
+    for (const s of steps) {
+        // Dependencies first (they are earlier in the plan, so their promises exist), then a free slot.
+        finished.set(s.name, (async () => {
+            await Promise.all((s.after ?? []).map((name) => finished.get(name)));
+            while (running.size >= PARALLEL)
+                await new Promise((r) => waiting.push(r));
+            running.add(s.name);
+            report();
+            try {
+                await step(s.name, envs.get(s.name), async () => s.run(envs.get(s.name)));
+            }
+            finally {
+                running.delete(s.name);
+                done++;
+                report();
+                waiting.shift()?.();
+            }
+        })());
+    }
+    await Promise.all(finished.values());
+    // Merged in plan order, so PATH order never depends on which download finished first.
+    const env = emptyEnv();
+    env.prepend.push(mkdirp(tool('bin')));
+    for (const part of envs.values()) {
+        Object.assign(env.vars, part.vars);
+        env.prepend.push(...part.prepend);
+        env.append.push(...part.append);
+        env.summary.push(...part.summary);
+    }
+    Object.assign(env.vars, config.environment);
+    log('Set up ' + steps.length + ' toolchains and databases.');
+    return env;
+};

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

@@ -0,0 +1,8 @@
+import type { Toolchains } from '../../core/types.js';
+import { type ToolEnv } from './common.js';
+/**
+ * A JDK for tools that run on Java (DynamoDB Local): the newest one already installed, else the newest LTS. Returns its
+ * folder; the agent's Java on PATH stays whatever toolchains.java says.
+ */
+export declare const ensureJdk: () => Promise<string>;
+export declare const setupJava: (env: ToolEnv, config: Toolchains["java"]) => Promise<void>;

package/dist/guest/toolchains/java.js

@@ -0,0 +1,96 @@
+// Java: Eclipse Temurin JDK (Adoptium), plus Maven and Gradle. All checksum-verified; the Maven repository and Gradle
+// caches live in persistent storage, so dependencies download once.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fetchJson, fetchText, installArchive } from '../../shared/download.js';
+import { dryRun, errMsg, exists, log, warn } from '../env.js';
+import { arch, resolveCached, tool, versionFromFiles } from './common.js';
+import { javaMajorFrom, pickPackageVersion } from './versions.js';
+const ADOPTIUM = 'https://api.adoptium.net/v3';
+const MAVEN = 'https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/';
+const temurin = async (major) => {
+    const assets = await fetchJson(ADOPTIUM + '/assets/latest/' + major + '/hotspot?image_type=jdk&os=windows&vendor=eclipse&architecture=' + (arch === 'arm64' ? 'aarch64' : 'x64'));
+    return assets.find((a) => a.binary.package.name.endsWith('.zip')) ?? Promise.reject(new Error('No Temurin ' + major + ' JDK zip for Windows'));
+};
+/** A project's .java-version / .sdkmanrc, else the configured version ("lts" = the newest LTS). */
+const javaMajor = async (config) => {
+    const fromProject = versionFromFiles(['.java-version', '.sdkmanrc'], (text, name) => javaMajorFrom(text, name === '.sdkmanrc'));
+    if (fromProject)
+        return { major: fromProject.spec, source: fromProject.source };
+    const spec = config.version.trim().toLowerCase();
+    if (spec !== 'lts')
+        return { major: javaMajorFrom(spec) ?? spec, source: 'config' };
+    const lts = await resolveCached('java:lts', async () => String((await fetchJson(ADOPTIUM + '/info/available_releases')).most_recent_lts));
+    return { major: lts, source: 'newest LTS' };
+};
+const setupJdk = async (env, config) => {
+    const { major, source } = await javaMajor(config);
+    const release = await resolveCached('java:' + major, async () => (await temurin(major)).release_name);
+    const home = tool('java', release.replace(/[^A-Za-z0-9.-]/g, '_'));
+    if (!exists(path.join(home, 'bin', 'java.exe'))) {
+        const asset = await temurin(major);
+        log('Downloading ' + asset.binary.package.name + ' ...');
+        await installArchive(asset.binary.package.link, home, { sha256: asset.binary.package.checksum, locate: 'release', fileName: asset.binary.package.name });
+    }
+    env.vars.JAVA_HOME = home;
+    env.prepend.push(path.join(home, 'bin'));
+    env.summary.push('java: ' + release + ' (Temurin, from ' + source + ')');
+};
+/**
+ * A JDK for tools that run on Java (DynamoDB Local): the newest one already installed, else the newest LTS. Returns its
+ * folder; the agent's Java on PATH stays whatever toolchains.java says.
+ */
+export const ensureJdk = async () => {
+    const root = tool('java');
+    const installed = exists(root) ? fs.readdirSync(root).filter((d) => exists(path.join(root, d, 'bin', 'java.exe'))).sort((a, b) => b.localeCompare(a, undefined, { numeric: true })) : [];
+    if (installed.length)
+        return path.join(root, installed[0]);
+    const scratch = { vars: {}, prepend: [], append: [], summary: [] };
+    await setupJdk(scratch, { enabled: true, version: 'lts', maven: false, gradle: false });
+    return scratch.vars.JAVA_HOME;
+};
+const setupMaven = async (env) => {
+    const version = await resolveCached('maven:3', async () => {
+        const versions = [...(await fetchText(MAVEN + 'maven-metadata.xml')).matchAll(/<version>([^<]+)<\/version>/g)].map((m) => m[1]);
+        return pickPackageVersion(versions, '3') ?? Promise.reject(new Error('No Maven 3 release found'));
+    });
+    const home = tool('maven', version);
+    if (!exists(path.join(home, 'bin', 'mvn.cmd'))) {
+        const url = MAVEN + version + '/apache-maven-' + version + '-bin.zip';
+        log('Downloading Maven ' + version + ' ...');
+        await installArchive(url, home, { sha512: (await fetchText(url + '.sha512')).trim().split(/\s+/)[0], locate: 'LICENSE' });
+    }
+    const repo = tool('maven-repository');
+    Object.assign(env.vars, { MAVEN_HOME: home, M2_HOME: home, MAVEN_OPTS: '-Dmaven.repo.local=' + repo });
+    env.prepend.push(path.join(home, 'bin'));
+    env.summary.push('maven: ' + version);
+};
+const setupGradle = async (env) => {
+    const current = await fetchJson('https://services.gradle.org/versions/current').catch(() => null);
+    const version = await resolveCached('gradle', async () => current?.version ?? Promise.reject(new Error('Gradle version lookup failed')));
+    const home = tool('gradle', version);
+    if (!exists(path.join(home, 'bin', 'gradle.bat'))) {
+        if (!current || current.version !== version)
+            throw new Error('Gradle ' + version + ' is not installed and cannot be downloaded right now');
+        log('Downloading Gradle ' + version + ' ...');
+        await installArchive(current.downloadUrl, home, { sha256: (await fetchText(current.checksumUrl)).trim(), locate: 'LICENSE', fileName: 'gradle-' + version + '.zip' });
+    }
+    const userHome = tool('gradle-home');
+    fs.mkdirSync(userHome, { recursive: true });
+    // File-system watching does not work on mapped folders (harmless but noisy "Couldn't add watch" on every build).
+    Object.assign(env.vars, { GRADLE_HOME: home, GRADLE_USER_HOME: userHome, GRADLE_OPTS: '-Dorg.gradle.vfs.watch=false' });
+    env.prepend.push(path.join(home, 'bin'));
+    env.summary.push('gradle: ' + version);
+};
+export const setupJava = async (env, config) => {
+    if (dryRun) {
+        log('(dry run) would provision Java ' + config.version + (config.maven ? ' + Maven' : '') + (config.gradle ? ' + Gradle' : ''));
+        return;
+    }
+    await setupJdk(env, config);
+    // Maven and Gradle are extras: one failing must not take the JDK down with it.
+    for (const [on, name, work] of [[config.maven, 'Maven', setupMaven], [config.gradle, 'Gradle', setupGradle]]) {
+        if (on)
+            await work(env).catch((e) => { env.summary.push(name.toLowerCase() + ': FAILED'); warn(name + ' setup failed (continuing without it): ' + errMsg(e)); });
+    }
+};

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

@@ -0,0 +1,16 @@
+import type { Toolchains } from '../../core/types.js';
+import { type ToolEnv } from './common.js';
+/** The "volta" block of the workspace's package.json ({ node, npm, yarn, pnpm }), if any. */
+export declare const voltaPins: () => Record<string, string>;
+export declare const wantsVolta: (setting: Toolchains["node"]["volta"]) => boolean;
+export declare const wantsPyenv: (setting: Toolchains["python"]["pyenv"]) => boolean;
+/**
+ * Volta from its portable zip. With pins, its shims go first on PATH (the project gets exactly what package.json says,
+ * fetched ahead of time); without, Volta is just available and nvm's Node stays the default.
+ */
+export declare const setupVolta: (env: ToolEnv) => Promise<void>;
+/**
+ * pyenv-win from its source archive (it ships no release assets). Its versions persist in tools\pyenv. It comes after
+ * the Python step on PATH, so `python` is the sandbox's own until you `pyenv install` / `pyenv local`.
+ */
+export declare const setupPyenv: (env: ToolEnv) => Promise<void>;

package/dist/guest/toolchains/managers.js

@@ -0,0 +1,82 @@
+// Version managers people already use: Volta (Node, npm, yarn, pnpm pinned in package.json) and pyenv-win. nvm and
+// the Python step still provide the default versions; these come along when the project or this PC uses them.
+import fs from 'node:fs';
+import path from 'node:path';
+import { githubAsset, installArchive, latestGithubTag } from '../../shared/download.js';
+import { dryRun, errMsg, execAsync, exists, log, mkdirp, session, warn, workspace } from '../env.js';
+import { arch, resolveCached, tool, versionOf } from './common.js';
+/** The "volta" block of the workspace's package.json ({ node, npm, yarn, pnpm }), if any. */
+export const voltaPins = () => {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(workspace, 'package.json'), 'utf8').replace(/^/, ''));
+        return Object.fromEntries(Object.entries(pkg.volta ?? {}).filter((e) => ['node', 'npm', 'yarn', 'pnpm'].includes(e[0]) && typeof e[1] === 'string'));
+    }
+    catch {
+        return {};
+    }
+};
+export const wantsVolta = (setting) => setting === 'auto' ? Object.keys(voltaPins()).length > 0 || Boolean(session.hostTools.volta) : setting;
+export const wantsPyenv = (setting) => setting === 'auto' ? Boolean(session.hostTools.pyenv) : setting;
+/**
+ * Volta from its portable zip. With pins, its shims go first on PATH (the project gets exactly what package.json says,
+ * fetched ahead of time); without, Volta is just available and nvm's Node stays the default.
+ */
+export const setupVolta = async (env) => {
+    if (dryRun) {
+        log('(dry run) would provision Volta');
+        return;
+    }
+    const dir = tool('volta');
+    if (!exists(path.join(dir, 'volta.exe'))) {
+        const asset = await githubAsset('volta-cli/volta', arch === 'arm64' ? /^volta-[\d.]+-windows-arm64\.zip$/ : /^volta-[\d.]+-windows\.zip$/);
+        log('Downloading ' + asset.name + ' ...');
+        await installArchive(asset.url, dir, { sha256: asset.sha256, locate: 'volta.exe', fileName: asset.name });
+    }
+    // The MSI puts these shims (copies of volta-shim.exe) next to volta.exe; the portable zip leaves that to us.
+    for (const shim of ['node', 'npm', 'npx', 'pnpm', 'pnpx', 'yarn', 'yarnpkg']) {
+        const target = path.join(dir, shim + '.exe');
+        if (!exists(target))
+            fs.copyFileSync(path.join(dir, 'volta-shim.exe'), target);
+    }
+    const home = mkdirp(tool('volta-home'));
+    const shims = mkdirp(path.join(home, 'bin'));
+    const vars = { VOLTA_HOME: home, VOLTA_FEATURE_PNPM: '1' };
+    Object.assign(env.vars, vars);
+    const pins = voltaPins();
+    if (Object.keys(pins).length)
+        env.prepend.push(dir, shims);
+    else
+        env.append.push(dir, shims);
+    const volta = path.join(dir, 'volta.exe');
+    // `volta install` fetches the pinned versions now (not on the agent's first `node`) and makes them the defaults.
+    for (const [toolName, version] of Object.entries(pins)) {
+        try {
+            await execAsync(volta, ['install', toolName + '@' + version], { env: { ...process.env, ...vars }, cwd: workspace, stdio: 'ignore' });
+        }
+        catch (e) {
+            warn('Volta could not install ' + toolName + '@' + version + ': ' + errMsg(e));
+        }
+    }
+    env.summary.push('volta: ' + versionOf(volta) + (Object.keys(pins).length ? ' (pins from package.json: ' + Object.entries(pins).map(([k, v]) => k + '@' + v).join(', ') + ')' : ' (no pins in this project; nvm\'s node is the default)'));
+};
+/**
+ * pyenv-win from its source archive (it ships no release assets). Its versions persist in tools\pyenv. It comes after
+ * the Python step on PATH, so `python` is the sandbox's own until you `pyenv install` / `pyenv local`.
+ */
+export const setupPyenv = async (env) => {
+    if (dryRun) {
+        log('(dry run) would provision pyenv-win');
+        return;
+    }
+    const root = tool('pyenv', 'pyenv-win');
+    if (!exists(path.join(root, 'bin', 'pyenv.bat'))) {
+        const tag = await resolveCached('pyenv-win', () => latestGithubTag('pyenv-win/pyenv-win'));
+        log('Downloading pyenv-win ' + tag + ' ...');
+        // GitHub's tag archive: no published checksum, but HTTPS from github.com for the project's own tag.
+        await installArchive('https://github.com/pyenv-win/pyenv-win/archive/refs/tags/' + encodeURIComponent(tag) + '.zip', root, { locate: 'pyenv.bat', up: 1, fileName: 'pyenv-win.zip' });
+    }
+    const home = root + path.sep;
+    Object.assign(env.vars, { PYENV: home, PYENV_ROOT: home, PYENV_HOME: home });
+    env.append.push(path.join(root, 'bin'), path.join(root, 'shims'));
+    env.summary.push('pyenv-win: pyenv install <version> / pyenv local <version> (versions persist)');
+};

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

@@ -0,0 +1,10 @@
+import type { Toolchains } from '../../core/types.js';
+import { type ToolEnv } from './common.js';
+/** Variables vcvars64.bat would set for this tree (host x64, target x64). */
+export declare const vcvars: (root: string, msvc: string, sdk: string) => {
+    vars: Record<string, string>;
+    path: string[];
+};
+/** The vcvars environment of an installed tree (for steps that run before the agent's environment exists). */
+export declare const installedMsvcEnv: () => ReturnType<typeof vcvars> | null;
+export declare const setupMsvc: (env: ToolEnv, config: Toolchains["msvc"]) => Promise<void>;

package/dist/guest/toolchains/msvc.js

@@ -0,0 +1,216 @@
+// MSVC (cl, link) and the Windows SDK without an installer, the way mmozeiko's portable-msvc.py does it: packages
+// from Microsoft's Visual Studio channel manifest (each payload checked against the manifest's sha256), the compiler
+// unpacked from its .vsix, the SDK from its .msi files with `msiexec /a`. Laid out like a Build Tools install, with
+// vcvars64.bat and a vswhere that points at it, 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 { download, extractArchive, fetchJson } from '../../shared/download.js';
+import { safeRemove } from '../../shared/safe-remove.js';
+import { system32 } from '../../shared/system.js';
+import { dryRun, execAsync, exists, log, mkdirp } from '../env.js';
+import { ensureCompiled } from '../ptyhost.js';
+import { tool } from './common.js';
+import { msiCabs, pickMsvcVersion, pickWindowsSdk } from './versions.js';
+const CHANNEL = 'https://aka.ms/vs/17/release/channel';
+const ROOT = tool('msvc');
+const MANIFEST_DAY_MS = 24 * 60 * 60 * 1000;
+/** 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');
+/** 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)
+        return JSON.parse(fs.readFileSync(cached, 'utf8'));
+    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'));
+};
+/** The compiler's packages (host x64, target x64): tools, resources, CRT headers/libs, ASAN/PGO headers, DIA SDK. */
+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'];
+/** 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',
+];
+/** .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);
+};
+const install = async (config) => {
+    const m = await manifest();
+    const byId = new Map();
+    for (const p of m.packages)
+        byId.set(p.id.toLowerCase(), [...(byId.get(p.id.toLowerCase()) ?? []), p]);
+    const pick = (id) => byId.get(id.toLowerCase())?.find((p) => !p.language || p.language === 'en-US');
+    const ids = [...byId.keys()];
+    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 = 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;
+    };
+    log('Downloading MSVC ' + version + ' (compiler, CRT) ...');
+    for (const part of MSVC_PARTS) {
+        const p = pick('microsoft.vc.' + version + '.' + part);
+        if (!p) {
+            if (part.startsWith('tools') || part.startsWith('crt.headers') || part.startsWith('crt.x64.desktop'))
+                throw new Error('MSVC ' + version + ' has no ' + part);
+            continue;
+        }
+        for (const payload of p.payloads ?? [])
+            await unpackVsix(await fetchPayload(payload), work);
+    }
+    const dia = pick('microsoft.visualcpp.dia.sdk');
+    for (const payload of dia?.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) ...');
+    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);
+        }
+    }
+    for (const msi of msis) {
+        // An administrative install only unpacks files; its verbose log explains a failure (e.g. a path over 260 characters).
+        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) + ')' : ''));
+        }
+    }
+    // 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 + '.*)');
+    // The tools folder is named after the toolset (14.44.35207), not the package version (14.44.17.14).
+    const toolsRoot = path.join(ROOT, 'VC', 'Tools', 'MSVC');
+    const tools = fs.readdirSync(toolsRoot).filter((d) => exists(path.join(toolsRoot, d, 'bin', 'Hostx64', 'x64', 'cl.exe'))).sort((a, b) => a.localeCompare(b, undefined, { numeric: true })).pop();
+    if (!tools)
+        throw new Error('MSVC ' + version + ' did not unpack (no cl.exe under VC\\Tools\\MSVC)');
+    return { msvc: tools, sdk: sdkVersion };
+};
+/** 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. */
+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. */
+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') }));
+};
+/** The vcvars environment of an installed tree (for steps that run before the agent's environment exists). */
+export const installedMsvcEnv = () => {
+    try {
+        const done = JSON.parse(fs.readFileSync(path.join(ROOT, '.installed.json'), 'utf8'));
+        return exists(path.join(ROOT, 'VC', 'Tools', 'MSVC', done.msvc, 'bin', 'Hostx64', 'x64', 'cl.exe')) ? vcvars(ROOT, done.msvc, done.sdk) : null;
+    }
+    catch {
+        return null;
+    }
+};
+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 marker = path.join(ROOT, '.installed.json');
+    const want = config.msvcVersion + '/' + config.sdkVersion;
+    let done = exists(marker) ? JSON.parse(fs.readFileSync(marker, 'utf8')) : null;
+    if (!done || done.want !== want || !exists(path.join(ROOT, 'VC', 'Tools', 'MSVC', done.msvc, 'bin', 'Hostx64', 'x64', 'cl.exe'))) {
+        log('Installing MSVC and the Windows SDK (~1-2 GB, once; licence accepted in toolchains.msvc.acceptLicense) ...');
+        // A previous attempt's verified downloads (.download) are kept; everything it unpacked is redone.
+        if (exists(ROOT))
+            for (const name of fs.readdirSync(ROOT).filter((n) => n !== '.manifest.json' && n !== '.download'))
+                safeRemove(path.join(ROOT, name), ROOT);
+        const installed = await install(config);
+        done = { ...installed, want };
+        fs.writeFileSync(marker, JSON.stringify(done, null, 2));
+    }
+    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.d.ts

@@ -0,0 +1,12 @@
+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>;
+/**
+ * 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>;
+export declare const setupRust: (env: ToolEnv, config: Toolchains["rust"], refresh: boolean) => Promise<void>;
+/** .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>;