windows-development-sandbox 0.0.0-stage → 1.1.0

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

@@ -0,0 +1,38 @@
+// PostgreSQL from EnterpriseDB's Windows binaries (without pgAdmin).
+import path from 'node:path';
+import { fetchJson, installArchive } from '../../../shared/download.js';
+import { execAsync, exists, log, logsDir } from '../../env.js';
+import { resolveCached, tool } from '../common.js';
+import { portOpen } from '../../ports.js';
+import { clearStaleLocks, createOnce, dataFor } from './server.js';
+/** The data folder of a PostgreSQL major version (one cluster per major). */
+export const postgresData = (version) => dataFor('postgres-' + version.split('.')[0]);
+export const setupPostgres = async (env, plan) => {
+    const exact = await resolveCached('postgres:' + plan.version, async () => {
+        const versions = (await fetchJson('https://www.postgresql.org/versions.json')).filter((v) => v.supported);
+        const hit = plan.version === 'latest' ? versions.find((v) => v.current) ?? versions[versions.length - 1] : versions.find((v) => v.major === plan.version.split('.')[0]);
+        return hit ? hit.major + '.' + hit.latestMinor : Promise.reject(new Error('No supported PostgreSQL ' + plan.version));
+    });
+    const home = tool('postgres', exact);
+    const bin = path.join(home, 'bin');
+    if (!exists(path.join(bin, 'pg_ctl.exe'))) {
+        log('Downloading PostgreSQL ' + exact + ' (~330 MB once) ...');
+        // EDB publishes no checksums; the download is HTTPS from EnterpriseDB, PostgreSQL's official Windows packager.
+        await installArchive('https://get.enterprisedb.com/postgresql/postgresql-' + exact + '-1-windows-x64-binaries.zip', home, {
+            locate: 'pg_ctl.exe', up: 1, fileName: 'postgresql-' + exact + '.zip', members: ['pgsql/bin', 'pgsql/lib', 'pgsql/share', 'pgsql/include'],
+        });
+    }
+    const data = postgresData(exact);
+    await createOnce(data, 'PG_VERSION', async () => {
+        log('Creating the PostgreSQL database (first start) ...');
+        await execAsync(path.join(bin, 'initdb.exe'), ['-D', data, '-U', 'postgres', '-A', 'trust', '-E', 'UTF8', '--locale=C'], { stdio: 'ignore' });
+    });
+    if (await portOpen(plan.port))
+        throw new Error('port ' + plan.port + ' is already in use (change databases.postgres.port)');
+    await clearStaleLocks(data, ['postmaster.pid'], plan.port);
+    // postgres.exe refuses to run as an administrator (the sandbox user is one); pg_ctl drops the rights first.
+    await execAsync(path.join(bin, 'pg_ctl.exe'), ['start', '-D', data, '-w', '-t', '60', '-l', path.join(logsDir, 'postgres.log'), '-o', '-p ' + plan.port + ' -c listen_addresses=localhost'], { stdio: 'ignore' });
+    Object.assign(env.vars, { PGHOST: 'localhost', PGPORT: String(plan.port), PGUSER: 'postgres' });
+    env.prepend.push(bin);
+    env.summary.push('postgres ' + exact + ': localhost:' + plan.port + ', user postgres, no password (postgres://postgres@localhost:' + plan.port + '/postgres)');
+};

package/dist/guest/toolchains/databases/redis.d.ts

@@ -0,0 +1,3 @@
+import type { DatabasePlan } from '../../../core/types.js';
+import { type ToolEnv } from '../common.js';
+export declare const setupRedis: (env: ToolEnv, plan: DatabasePlan) => Promise<void>;

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

@@ -0,0 +1,16 @@
+// Redis (the maintained community Windows build of upstream Redis).
+import path from 'node:path';
+import { exists, mkdirp } from '../../env.js';
+import { installFromGithub, tool } from '../common.js';
+import { dataFor, startServer } from './server.js';
+export const setupRedis = async (env, plan) => {
+    const home = tool('redis');
+    if (!exists(path.join(home, 'redis-server.exe'))) {
+        // Redis has no official Windows build; this one is built from upstream Redis with MSYS2.
+        await installFromGithub('redis-windows/redis-windows', /^Redis-[\d.]+-Windows-x64-msys2\.zip$/, { dest: home, what: (a) => 'Redis (' + a.name + ', ~10 MB once)', locate: 'redis-server.exe' });
+    }
+    const data = mkdirp(dataFor('redis'));
+    await startServer('redis', path.join(home, 'redis-server.exe'), ['--port', String(plan.port), '--bind', '127.0.0.1', '--dir', data.replace(/\\/g, '/'), '--appendonly', 'yes'], plan.port);
+    env.prepend.push(home);
+    env.summary.push('redis: redis://127.0.0.1:' + plan.port + ' (redis-cli on PATH)');
+};

package/dist/guest/toolchains/databases/server.d.ts

@@ -0,0 +1,14 @@
+/** C:\AgentData\databases\<name>: the data survives the sandbox. */
+export declare const dataFor: (name: string) => string;
+/** Starts a server detached (it outlives the boot script) with its output in logs\<name>.log, and waits for its port. */
+export declare const startServer: (name: string, exe: string, args: string[], port: number) => Promise<void>;
+/**
+ * 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 declare const clearStaleLocks: (dir: string, files: string[], port: number) => Promise<void>;
+/**
+ * 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 declare const createOnce: (data: string, marker: string, create: () => Promise<void>) => Promise<void>;

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.d.ts

@@ -0,0 +1,3 @@
+import type { GitAccess } from '../../core/types.js';
+import { type ToolEnv } from './common.js';
+export declare const setupGit: (env: ToolEnv, hostCopy: boolean, refresh: boolean, access: GitAccess) => Promise<void>;

package/dist/guest/toolchains/git.js

@@ -0,0 +1,121 @@
+// Full Git for Windows (with bash: Claude Code on Windows needs Git Bash). Copied from the host when installed there.
+// provisioning.git.access decides what the agent gets: 'full' git, a 'readonly' guarded git, or 'none' (bash only).
+import fs from 'node:fs';
+import path from 'node:path';
+import { download, githubAsset, moveIntoPlace, stagingFolder } from '../../shared/download.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 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
+ * git.exe), plus git config from the environment (which repository config cannot override).
+ */
+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.
+    // 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, {
+        AGENT_GIT_ACCESS: access, AGENT_REAL_GIT: access === 'readonly' ? realGit : '',
+        AGENT_GUARD_NODE: process.execPath, AGENT_GUARD_SCRIPT: guard, BASH_ENV: posix(path.join(dir, 'bashenv.sh')),
+    });
+    if (access === 'readonly') {
+        const hooks = mkdirp(path.join(dir, 'hooks'));
+        for (const hook of BLOCKED_HOOKS)
+            fs.writeFileSync(path.join(hooks, hook), '#!/bin/sh\necho "git is read-only in this sandbox: ' + hook + ' refused." >&2\nexit 1\n');
+        Object.assign(env.vars, { GIT_CONFIG_COUNT: '1', GIT_CONFIG_KEY_0: 'core.hooksPath', GIT_CONFIG_VALUE_0: posix(hooks) });
+    }
+    else {
+        // Even a git.exe found some other way sees no repository.
+        env.vars.GIT_DIR = path.join(dataDir, 'git-disabled');
+    }
+};
+/**
+ * Git copied from this PC keeps its installer's absolute paths in etc\gitconfig, e.g. http.sslCAInfo =
+ * C:/Program Files/Git/mingw64/etc/ssl/certs/ca-bundle.crt, which does not exist here: every HTTPS clone/fetch failed
+ * with "error setting certificate file". Point it at the bundle inside this copy.
+ */
+const pointAtOwnCertificates = (root) => {
+    const config = path.join(root, 'etc', 'gitconfig');
+    const bundle = path.join(root, 'mingw64', 'etc', 'ssl', 'certs', 'ca-bundle.crt');
+    if (!exists(config) || !exists(bundle))
+        return;
+    const text = fs.readFileSync(config, 'utf8');
+    const fixed = text.replace(/^(\s*sslCAInfo\s*=\s*).*$/gim, (_m, key) => key + posix(bundle));
+    if (fixed !== text)
+        fs.writeFileSync(config, fixed);
+};
+export const setupGit = async (env, hostCopy, refresh, access) => {
+    const root = tool('git');
+    const bash = path.join(root, 'bin', 'bash.exe');
+    const gitExe = path.join(root, 'cmd', 'git.exe');
+    const hostGit = path.join(hostToolsDir, 'git');
+    if (exists(root) && !exists(bash)) {
+        log('Replacing the old MinGit (no bash) with full Git for Windows.');
+        safeRemove(root, toolsDir);
+    }
+    if (!exists(bash) || refresh) {
+        if (dryRun) {
+            log('(dry run) would provision Git for Windows' + (hostCopy ? ' from this PC' : '') + ' (access: ' + access + ')');
+            return;
+        }
+        // Into a staging folder, then renamed: an interrupted copy/extraction must not leave a tools\git that has bash.exe
+        // (so looks installed) but is missing the rest.
+        const work = stagingFolder(root);
+        try {
+            if (hostCopy && exists(path.join(hostGit, 'bin', 'bash.exe'))) {
+                log('Copying Git for Windows from this PC ...');
+                robocopy(hostGit, work);
+            }
+            else
+                await installPortableGit(work);
+            if (!exists(path.join(work, 'bin', 'bash.exe')))
+                throw new Error('bash.exe missing after installing Git');
+            moveIntoPlace(work, root);
+        }
+        finally {
+            safeRemove(work, toolsDir);
+        }
+    }
+    if (!exists(bash))
+        throw new Error('bash.exe missing after installing Git');
+    pointAtOwnCertificates(root);
+    env.vars.CLAUDE_CODE_GIT_BASH_PATH = bash;
+    env.append.push(path.join(root, 'usr', 'bin'));
+    const version = execOutput(gitExe, ['--version']).replace(/^git version /, '');
+    if (access === 'full') {
+        env.prepend.push(path.join(root, 'cmd'));
+        env.summary.push('git: ' + version);
+        return;
+    }
+    installGuard(env, access, gitExe);
+    env.summary.push(access === 'readonly' ? 'git: ' + version + ' READ-ONLY (status/log/diff/show/blame; no commit, push, checkout, ...)' : 'git: DISABLED (bash only; the agent cannot use git)');
+};

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

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

package/dist/guest/toolchains/go.js

@@ -0,0 +1,33 @@
+// Go from go.dev (checksum-verified zip). Modules, build cache and `go install` binaries live in persistent storage;
+// GOTOOLCHAIN=auto lets a go.mod that needs a newer Go fetch it itself.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fetchJson, installArchive } from '../../shared/download.js';
+import { dryRun, execAsync, exists, log } from '../env.js';
+import { arch, installOnce, resolveCached, tool, versionOf } from './common.js';
+import { pickGoRelease } from './versions.js';
+const findRelease = async (spec) => pickGoRelease(await fetchJson('https://go.dev/dl/?mode=json&include=all'), spec) ?? Promise.reject(new Error('No Go release matches "' + spec + '"'));
+export const setupGo = async (env, config) => {
+    if (dryRun) {
+        log('(dry run) would provision Go ' + config.version);
+        return;
+    }
+    const version = await resolveCached('go:' + config.version, async () => (await findRelease(config.version)).version);
+    const root = tool('go', version);
+    if (!exists(path.join(root, 'bin', 'go.exe'))) {
+        const goArch = arch === 'arm64' ? 'arm64' : 'amd64';
+        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 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');
+    const vars = { GOROOT: root, GOPATH, GOBIN: path.join(GOPATH, 'bin'), GOMODCACHE: path.join(GOPATH, 'pkg', 'mod'), GOCACHE: tool('go-cache'), GOTOOLCHAIN: 'auto', GOTELEMETRY: 'off' };
+    fs.mkdirSync(vars.GOBIN, { recursive: true });
+    Object.assign(env.vars, vars);
+    env.prepend.push(path.join(root, 'bin'), vars.GOBIN);
+    const go = path.join(root, 'bin', 'go.exe');
+    env.summary.push('go: ' + versionOf(go, ['version']));
+    await installOnce(env, 'go', config.tools, (pkg) => execAsync(go, ['install', pkg.includes('@') ? pkg : pkg + '@latest'], { env: { ...process.env, ...vars } }));
+};

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

@@ -0,0 +1,17 @@
+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 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, run?: RunOptions) => Promise<ToolchainResult>;

package/dist/guest/toolchains/index.js

@@ -0,0 +1,80 @@
+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;
+/** 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);
+    }
+};
+/** 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)
+        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 exclusive(s.name, () => 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());
+    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(), steps: Object.fromEntries(envs) };
+    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, 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/';
+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 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;
+    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 = emptyEnv();
+    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 + ' (~10 MB once) ...');
+        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 + ' (~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');
+    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/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.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,84 @@
+// 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 { 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(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 {
+        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 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']) {
+        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: projectWorkspace(), stdio: 'ignore' });
+        }
+        catch (e) {
+            warn('Volta could not install ' + toolName + '@' + version + ': ' + errMsg(e));
+        }
+    }
+    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
+ * 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 + ' (~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' });
+    }
+    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)');
+};