windows-development-sandbox 1.0.5 → 1.4.0

package/dist/guest/toolchains/index.js

@@ -1,102 +1,54 @@
-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';
+import { log, mkdirp, setSandboxStatus } from '../env.js';
+import { emptyEnv, step, tool } from './common.js';
+import { plan } from './plan.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) })),
-    ];
+/** One lock per kind of step ("Node 20" and "Node 22" share nvm's folders): held while that step runs, in any run. */
+const locks = new Map();
+const lockKey = (name) => name.split(' ')[0].toLowerCase();
+const exclusive = async (name, work) => {
+    const key = lockKey(name);
+    const previous = locks.get(key) ?? Promise.resolve();
+    let release = () => undefined;
+    const mine = new Promise((r) => { release = r; });
+    const chained = previous.then(() => mine);
+    locks.set(key, chained);
+    await previous;
+    try {
+        return await work();
+    }
+    finally {
+        release();
+        if (locks.get(key) === chained)
+            locks.delete(key);
+    }
 };
-/** 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);
+/** Runs the steps (each with its own environment) at most PARALLEL at a time, after the steps they depend on. */
+const runSteps = async (steps, o) => {
     const envs = new Map(steps.map((s) => [s.name, emptyEnv()]));
     const finished = new Map();
     const running = new Set();
     const waiting = [];
     let done = 0;
+    const say = o.report ?? ((message) => setSandboxStatus('provisioning', message));
     const report = () => { if (running.size)
-        setSandboxStatus('provisioning', 'Installing ' + [...running].join(', ') + ' (' + done + ' of ' + steps.length + ' done)'); };
+        say('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)));
+            const reused = s.shared ? o.reuse?.[s.name] : undefined;
+            if (reused) {
+                envs.set(s.name, structuredClone(reused));
+                done++;
+                return;
+            }
             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)));
+                await exclusive(s.name, () => step(s.name, envs.get(s.name), async () => s.run(envs.get(s.name))));
             }
             finally {
                 running.delete(s.name);
@@ -107,8 +59,14 @@ export const setupToolchains = async (config, versions, options) => {
         })());
     }
     await Promise.all(finished.values());
+    return envs;
+};
+/** Provisions every enabled toolchain and database, and returns the combined environment for the agent. */
+export const setupToolchains = async (config, versions, options, run = {}) => {
+    const steps = plan(config, versions, options).filter((s) => s.on);
+    const envs = await runSteps(steps, run);
     // Merged in plan order, so PATH order never depends on which download finished first.
-    const env = emptyEnv();
+    const env = { ...emptyEnv(), steps: Object.fromEntries(envs) };
     env.prepend.push(mkdirp(tool('bin')));
     for (const part of envs.values()) {
         Object.assign(env.vars, part.vars);

package/dist/guest/toolchains/java.js

@@ -4,7 +4,7 @@ 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 { arch, emptyEnv, 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/';
@@ -29,7 +29,7 @@ const setupJdk = async (env, config) => {
     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 + ' ...');
+        log('Downloading Java ' + release + ' (JDK, ~200 MB once) ...');
         await installArchive(asset.binary.package.link, home, { sha256: asset.binary.package.checksum, locate: 'release', fileName: asset.binary.package.name });
     }
     env.vars.JAVA_HOME = home;
@@ -45,7 +45,7 @@ export const ensureJdk = async () => {
     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: [] };
+    const scratch = emptyEnv();
     await setupJdk(scratch, { enabled: true, version: 'lts', maven: false, gradle: false });
     return scratch.vars.JAVA_HOME;
 };
@@ -57,7 +57,7 @@ const setupMaven = async (env) => {
     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 + ' ...');
+        log('Downloading Maven ' + version + ' (~10 MB once) ...');
         await installArchive(url, home, { sha512: (await fetchText(url + '.sha512')).trim().split(/\s+/)[0], locate: 'LICENSE' });
     }
     const repo = tool('maven-repository');
@@ -72,7 +72,7 @@ const setupGradle = async (env) => {
     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 + ' ...');
+        log('Downloading Gradle ' + version + ' (~130 MB once) ...');
         await installArchive(current.downloadUrl, home, { sha256: (await fetchText(current.checksumUrl)).trim(), locate: 'LICENSE', fileName: 'gradle-' + version + '.zip' });
     }
     const userHome = tool('gradle-home');

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

@@ -0,0 +1,2 @@
+/** Removes helper builds older versions left in persistent storage, and interrupted installs' staging folders. */
+export declare const pruneToolLeftovers: () => void;

package/dist/guest/toolchains/leftovers.js

@@ -0,0 +1,26 @@
+// Clean-up of what interrupted or older installs left in the tools folder.
+import fs from 'node:fs';
+import path from 'node:path';
+import { safeRemove } from '../../shared/safe-remove.js';
+import { toolsDir } from '../env.js';
+const STAGING = /\.staging-[0-9a-f]+$/i;
+const entries = (dir) => { try {
+    return fs.readdirSync(dir, { withFileTypes: true });
+}
+catch {
+    return [];
+} };
+/** Removes helper builds older versions left in persistent storage, and interrupted installs' staging folders. */
+export const pruneToolLeftovers = () => {
+    for (const legacy of ['ptyhost', 'gitshim'])
+        safeRemove(path.join(toolsDir, legacy), toolsDir);
+    // Staging folders sit next to their destination: tools\x.staging-ab12 and one level down (tools\nvm\v22.staging-ab12).
+    for (const top of entries(toolsDir)) {
+        const dir = path.join(toolsDir, top.name);
+        if (STAGING.test(top.name))
+            safeRemove(dir, toolsDir);
+        else if (top.isDirectory())
+            for (const sub of entries(dir).filter((e) => STAGING.test(e.name)))
+                safeRemove(path.join(dir, sub.name), dir);
+    }
+};

package/dist/guest/toolchains/managers.js

@@ -2,13 +2,14 @@
 // 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';
+import { installArchive, latestGithubTag } from '../../shared/download.js';
+import { dryRun, errMsg, execAsync, exists, log, mkdirp, session, warn } from '../env.js';
+import { projectWorkspace } from '../project-context.js';
+import { arch, installFromGithub, 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(/^/, ''));
+        const pkg = JSON.parse(fs.readFileSync(path.join(projectWorkspace(), '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 {
@@ -28,9 +29,8 @@ export const setupVolta = async (env) => {
     }
     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 });
+        const pattern = arch === 'arm64' ? /^volta-[\d.]+-windows-arm64\.zip$/ : /^volta-[\d.]+-windows\.zip$/;
+        await installFromGithub('volta-cli/volta', pattern, { dest: dir, what: 'Volta (~15 MB once)', locate: 'volta.exe' });
     }
     // 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']) {
@@ -51,13 +51,15 @@ export const setupVolta = async (env) => {
     // `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' });
+            await execAsync(volta, ['install', toolName + '@' + version], { env: { ...process.env, ...vars }, cwd: projectWorkspace(), 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)'));
+    const pinned = Object.entries(pins).map(([k, v]) => k + '@' + v);
+    const note = pinned.length ? ' (pins from package.json: ' + pinned.join(', ') + ')' : ' (no pins in this project; nvm\'s node is the default)';
+    env.summary.push('volta: ' + versionOf(volta) + note);
 };
 /**
  * pyenv-win from its source archive (it ships no release assets). Its versions persist in tools\pyenv. It comes after
@@ -71,7 +73,7 @@ export const setupPyenv = async (env) => {
     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 + ' ...');
+        log('Downloading pyenv-win ' + tag + ' (~5 MB once) ...');
         // 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' });
     }

package/dist/guest/toolchains/{binstall.js → native/binstall.js}

@@ -2,10 +2,9 @@
 // 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 { githubAsset, installArchive } from '../../shared/download.js';
-import { errMsg, execAsync, exists, log, warn } from '../env.js';
-import { binstallAsset } from './catalogue.js';
-import { arch, tool } from './common.js';
+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.
@@ -17,9 +16,7 @@ const ensureBinstall = async (cargoBin) => {
     try {
         const dir = tool('cargo-binstall');
         if (!exists(path.join(dir, 'cargo-binstall.exe'))) {
-            const asset = await githubAsset('cargo-bins/cargo-binstall', binstallAsset(arch));
-            log('Downloading ' + asset.name + ' (prebuilt Rust tools) ...');
-            await installArchive(asset.url, dir, { sha256: asset.sha256, locate: 'cargo-binstall.exe', fileName: asset.name });
+            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;
@@ -46,8 +43,8 @@ export const crateInstaller = (cargoHome, cargoEnv) => {
                 await execAsync(cargo, ['binstall', '--no-confirm', '--locked', '--disable-strategies', 'compile', crate], binstallEnv);
                 return;
             }
-            catch (e) {
-                log('No prebuilt ' + crate + ' for Windows (' + errMsg(e) + '); compiling it with cargo install ...');
+            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,56 @@
+// 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, execOutput, 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/*'] });
+    }
+    const register = (file) => execAsync(SYSTEM.reg(), ['add', 'HKLM\\SOFTWARE\\Khronos\\Vulkan\\Drivers', '/v', file, '/t', 'REG_DWORD', '/d', '0', '/f'], { stdio: 'ignore' });
+    await register(icd);
+    // sandbox.vGpu: the sandbox sees this PC's GPU through Direct3D 12, and Dozen runs Vulkan on it. Programs prefer it
+    // over lavapipe (a GPU before a CPU device); lavapipe stays for the ones that need it.
+    const dozen = path.join(mesaDir, arch === 'arm64' ? 'dzn_icd.aarch64.json' : 'dzn_icd.x86_64.json');
+    const gpu = hasGpu();
+    if (gpu && exists(dozen))
+        await register(dozen);
+    env.prepend.push(dir);
+    env.summary.push('vulkan: ' + (gpu && exists(dozen) ? 'Dozen (Vulkan on the GPU via Direct3D 12) and ' : '') + 'lavapipe (software Vulkan 1.4 on the CPU), vulkaninfo on PATH; WGPU_BACKEND=vulkan for wgpu');
+};
+/** A real display adapter (sandbox.vGpu on), not only the remote display or basic render driver. */
+const hasGpu = () => execOutput(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-Command', '(Get-CimInstance Win32_VideoController).Name'], { timeout: 30000 })
+    .split(/\r?\n/).map((n) => n.trim()).some((n) => n && !/^Microsoft (Remote Display|Basic (Render|Display))/i.test(n));

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;