windows-development-sandbox 1.0.5 → 1.1.0

package/dist/guest/toolchains/databases/server.js

@@ -0,0 +1,52 @@
+// What every database module shares: where data lives, starting a server detached, and safe first-time creation.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { safeRemove } from '../../../shared/safe-remove.js';
+import { dataDir, exists, logsDir, mkdirp } from '../../env.js';
+import { portOpen, waitForPort } from '../../ports.js';
+/** C:\AgentData\databases\<name>: the data survives the sandbox. */
+export const dataFor = (name) => path.join(dataDir, 'databases', name);
+/** Starts a server detached (it outlives the boot script) with its output in logs\<name>.log, and waits for its port. */
+export const startServer = async (name, exe, args, port) => {
+    if (await portOpen(port))
+        throw new Error('port ' + port + ' is already in use (change databases.' + name + '.port)');
+    const logFile = path.join(logsDir, name + '.log');
+    const out = fs.openSync(logFile, 'a');
+    spawn(exe, args, { detached: true, stdio: ['ignore', out, out], windowsHide: true }).unref();
+    fs.closeSync(out);
+    if (!(await waitForPort(port, 60)))
+        throw new Error(name + ' did not start listening on port ' + port + '; see ' + logFile);
+};
+/**
+ * Lock files a sandbox that was closed without shutting the server down leaves behind. Only when nothing listens on
+ * the port: a server already running in this VM keeps its lock.
+ */
+export const clearStaleLocks = async (dir, files, port) => {
+    if (await portOpen(port))
+        return;
+    for (const f of files)
+        fs.rmSync(path.join(dir, f), { force: true });
+};
+/**
+ * Creates a database folder with `create` (initdb, install-db) unless `marker` is there. A failed or interrupted run
+ * removes the folder again when this call made it, so the half-made one is not taken for a finished database next boot.
+ */
+export const createOnce = async (data, marker, create) => {
+    if (exists(path.join(data, marker)))
+        return;
+    const existed = exists(data);
+    mkdirp(path.dirname(data));
+    try {
+        await create();
+    }
+    catch (e) {
+        if (!existed) {
+            try {
+                safeRemove(data, dataDir);
+            }
+            catch { /* the original error is the one to report */ }
+        }
+        throw e;
+    }
+};

package/dist/guest/toolchains/git.js

@@ -3,18 +3,24 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { download, githubAsset, moveIntoPlace, stagingFolder } from '../../shared/download.js';
-import { dataDir, dryRun, errMsg, execAsync, execOutput, exists, hostToolsDir, launchDir, log, mkdirp, robocopy, warn } from '../env.js';
-import { ensureCompiled } from '../ptyhost.js';
+import { safeRemove } from '../../shared/safe-remove.js';
+import { dataDir, dryRun, errMsg, execAsync, execOutput, exists, hostToolsDir, launchDir, log, mkdirp, robocopy, toolsDir, warn } from '../env.js';
+import { ensureCompiled } from '../helpers.js';
 import { arch, tool } from './common.js';
+import { duringSession } from '../project-context.js';
 const BLOCKED_HOOKS = ['pre-commit', 'commit-msg', 'pre-merge-commit', 'pre-push', 'pre-rebase', 'pre-applypatch', 'applypatch-msg'];
 const posix = (p) => p.replace(/\\/g, '/');
 const installPortableGit = async (root) => {
     const asset = await githubAsset('git-for-windows/git', arch === 'arm64' ? /^PortableGit-[\d.]+-arm64\.7z\.exe$/ : /^PortableGit-[\d.]+-64-bit\.7z\.exe$/);
     const sfx = tool(asset.name);
-    log('Downloading ' + asset.name + ' ...');
-    await download(asset.url, sfx, asset.sha256);
-    await execAsync(sfx, ['-o' + root, '-y'], { stdio: 'ignore' });
-    fs.rmSync(sfx, { force: true });
+    log('Downloading Git for Windows (' + asset.name + ', ~60 MB once) ...');
+    try {
+        await download(asset.url, sfx, asset.sha256);
+        await execAsync(sfx, ['-o' + root, '-y'], { stdio: 'ignore' });
+    }
+    finally {
+        fs.rmSync(sfx, { force: true });
+    }
 };
 /**
  * readonly / none: a `git` wrapper first on PATH and as a bash function (Git Bash would otherwise find the real
@@ -24,14 +30,17 @@ const installGuard = (env, access, realGit) => {
     const dir = mkdirp(tool('gitguard'));
     const guard = path.join(launchDir, 'runtime', 'gitguard.js');
     // A real git.exe (programs like Claude Code only look for .exe); a .cmd only if the C# compiler is unavailable.
-    try {
-        fs.copyFileSync(ensureCompiled('gitshim'), path.join(dir, 'git.exe'));
-        fs.rmSync(path.join(dir, 'git.cmd'), { force: true });
-    }
-    catch (e) {
-        warn('git guard: falling back to git.cmd (' + errMsg(e) + ')');
-        fs.writeFileSync(path.join(dir, 'git.cmd'), '@"' + process.execPath + '" "' + guard + '" %*\r\n');
-    }
+    // A project added later reuses the boot's: sessions may be running it, and Windows cannot replace a running exe.
+    if (duringSession() && (exists(path.join(dir, 'git.exe')) || exists(path.join(dir, 'git.cmd')))) { /* keep it */ }
+    else
+        try {
+            fs.copyFileSync(ensureCompiled('gitshim'), path.join(dir, 'git.exe'));
+            fs.rmSync(path.join(dir, 'git.cmd'), { force: true });
+        }
+        catch (e) {
+            warn('git guard: falling back to git.cmd (' + errMsg(e) + ')');
+            fs.writeFileSync(path.join(dir, 'git.cmd'), '@"' + process.execPath + '" "' + guard + '" %*\r\n');
+        }
     fs.writeFileSync(path.join(dir, 'bashenv.sh'), 'git() { "' + posix(process.execPath) + '" "' + posix(guard) + '" "$@"; }\nexport -f git\n');
     env.prepend.unshift(dir);
     Object.assign(env.vars, {
@@ -71,7 +80,7 @@ export const setupGit = async (env, hostCopy, refresh, access) => {
     const hostGit = path.join(hostToolsDir, 'git');
     if (exists(root) && !exists(bash)) {
         log('Replacing the old MinGit (no bash) with full Git for Windows.');
-        fs.rmSync(root, { recursive: true, force: true });
+        safeRemove(root, toolsDir);
     }
     if (!exists(bash) || refresh) {
         if (dryRun) {
@@ -93,7 +102,7 @@ export const setupGit = async (env, hostCopy, refresh, access) => {
             moveIntoPlace(work, root);
         }
         finally {
-            fs.rmSync(work, { recursive: true, force: true });
+            safeRemove(work, toolsDir);
         }
     }
     if (!exists(bash))

package/dist/guest/toolchains/go.js

@@ -19,7 +19,7 @@ export const setupGo = async (env, config) => {
         const file = (await findRelease(version)).files.find((f) => f.os === 'windows' && f.arch === goArch && f.kind === 'archive');
         if (!file)
             throw new Error(version + ' has no Windows ' + goArch + ' zip');
-        log('Downloading ' + file.filename + ' ...');
+        log('Downloading Go ' + version.replace(/^go/, '') + ' (~80 MB once) ...');
         await installArchive('https://go.dev/dl/' + file.filename, root, { sha256: file.sha256, locate: 'VERSION', fileName: file.filename });
     }
     const GOPATH = tool('go-path');

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

@@ -1,13 +1,17 @@
-import type { DatabasePlan, GitAccess, Toolchains, ToolVersions } from '../../core/types.js';
+import type { Toolchains, ToolVersions } from '../../core/types.js';
 import { type ToolEnv } from './common.js';
+import { type ToolchainOptions } from './plan.js';
 export type { ToolEnv } from './common.js';
-export { pickNodeVersion, pickPackageVersion } from './versions.js';
-export interface ToolchainOptions {
-    gitEnabled: boolean;
-    gitAccess: GitAccess;
-    hostGit: boolean;
-    refresh: boolean;
-    databases: DatabasePlan[];
+export type { ToolchainOptions } from './plan.js';
+export interface RunOptions {
+    /** Progress lines ("Installing Go, Rust (3 of 9 done)"); default: the sandbox's boot status. */
+    report?: (message: string) => void;
+    /** What machine-wide (shared) steps contributed at boot: reused instead of run again. */
+    reuse?: Record<string, ToolEnv>;
+}
+/** The combined environment, plus what each step contributed (the boot keeps it so later projects can reuse shared steps). */
+export interface ToolchainResult extends ToolEnv {
+    steps: Record<string, ToolEnv>;
 }
 /** Provisions every enabled toolchain and database, and returns the combined environment for the agent. */
-export declare const setupToolchains: (config: Toolchains, versions: ToolVersions, options: ToolchainOptions) => Promise<ToolEnv>;
+export declare const setupToolchains: (config: Toolchains, versions: ToolVersions, options: ToolchainOptions, run?: RunOptions) => Promise<ToolchainResult>;

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