windows-development-sandbox 0.0.0-stage → 1.1.0

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

@@ -0,0 +1,45 @@
+// Rust: rustup + cargo, with crates installed prebuilt where possible (binstall.ts).
+import path from 'node:path';
+import { dryRun, execAsync, exists, log } from '../../env.js';
+import { arch, downloadFile, installOnce, tool, versionOf } from '../common.js';
+import { crateInstaller } from './binstall.js';
+import { installedMsvcEnv } from './msvc/index.js';
+export const setupRust = async (env, config, refresh) => {
+    const RUSTUP_HOME = tool('rust', 'rustup');
+    const CARGO_HOME = tool('rust', 'cargo');
+    const rustEnv = { env: { ...process.env, RUSTUP_HOME, CARGO_HOME } };
+    const rustup = path.join(CARGO_HOME, 'bin', 'rustup.exe');
+    if (dryRun) {
+        log('(dry run) would provision Rust ' + config.toolchain + ' (' + config.host + ')');
+        return;
+    }
+    if (!exists(rustup)) {
+        const init = tool('rust', 'rustup-init.exe');
+        log('Installing Rust with rustup (~300 MB once; the toolchain downloads after rustup itself) ...');
+        await downloadFile('https://static.rust-lang.org/rustup/dist/' + (arch === 'arm64' ? 'aarch64' : 'x86_64') + '-pc-windows-msvc/rustup-init.exe', init);
+        await execAsync(init, ['-y', '--no-modify-path', '--profile', 'default', '--default-host', config.host, '--default-toolchain', config.toolchain], rustEnv);
+    }
+    else {
+        // The host can change (GNU <-> msvc with toolchains.msvc): install the toolchain for it; a no-op when it is there.
+        await execAsync(rustup, ['set', 'default-host', config.host], { ...rustEnv, stdio: 'ignore' });
+        await execAsync(rustup, ['toolchain', 'install', config.toolchain, '--profile', 'default', '--no-self-update'], { ...rustEnv, stdio: 'ignore' });
+        await execAsync(rustup, ['default', config.toolchain], { ...rustEnv, stdio: 'ignore' });
+        if (refresh)
+            await execAsync(rustup, ['update'], rustEnv);
+    }
+    Object.assign(env.vars, { RUSTUP_HOME, CARGO_HOME });
+    env.prepend.push(path.join(CARGO_HOME, 'bin'));
+    env.summary.push('rust: ' + versionOf(path.join(CARGO_HOME, 'bin', 'rustc.exe'), ['--version'], rustEnv) + ' [' + config.host + ']');
+    const toolchainKey = 'rustup@' + config.toolchain;
+    await installOnce(env, toolchainKey + ' components', config.components, (c) => execAsync(rustup, ['component', 'add', c], rustEnv));
+    await installOnce(env, toolchainKey + ' targets', config.targets, (t) => execAsync(rustup, ['target', 'add', t], rustEnv));
+    // cargo install links with MSVC's link.exe (msvc host) or MinGW's gcc (GNU host). Those steps ran first, but their
+    // PATH only reaches the agent at the end, so it is put together here.
+    const msvc = config.host.endsWith('-msvc') ? installedMsvcEnv() : null;
+    const mingw = tool('mingw', 'mingw64', 'bin');
+    const cargoEnv = msvc
+        ? { env: { ...rustEnv.env, ...msvc.vars, PATH: [path.join(CARGO_HOME, 'bin'), ...msvc.path, process.env.PATH ?? ''].join(path.delimiter) } }
+        : { env: { ...rustEnv.env, CARGO_TARGET_X86_64_PC_WINDOWS_GNU_LINKER: path.join(mingw, 'gcc.exe'), PATH: [path.join(CARGO_HOME, 'bin'), mingw, process.env.PATH ?? ''].join(path.delimiter) } };
+    // Prebuilt through cargo-binstall where the crate publishes a Windows build, else compiled (same "cargo" keys as before).
+    await installOnce(env, 'cargo', config.crates, crateInstaller(CARGO_HOME, cargoEnv));
+};

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

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

package/dist/guest/toolchains/node.js

@@ -0,0 +1,152 @@
+// Node through nvm-windows. Versions live in C:\AgentData\tools\nvm (persistent); the active-version symlink lives on
+// the sandbox's own disk (C:\nvm\nodejs), because a symlink inside a mapped folder would point at the host's paths.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fetchJson, githubAsset, installArchive } from '../../shared/download.js';
+import { safeRemove } from '../../shared/safe-remove.js';
+import { copyNode, dryRun, errMsg, execAsync, exists, hostToolsDir, localDir, log, mkdirp, warn } from '../env.js';
+import { arch, installOnce, resolveCached, tool } from './common.js';
+import { duringSession } from '../project-context.js';
+import { pickNodeVersion, pickSpreadVersions } from './versions.js';
+const NVM_HOME = tool('nvm');
+const NVM_SYMLINK = path.join(localDir, 'nodejs');
+const HOST_NVM = path.join(hostToolsDir, 'nvm');
+/** Most Node versions taken from this PC's nvm, the selected one included. */
+const HOST_VERSIONS_MAX = 3;
+const hostNvmVersions = () => exists(HOST_NVM)
+    ? fs.readdirSync(HOST_NVM).filter((d) => /^v\d+\.\d+\.\d+$/.test(d) && exists(path.join(HOST_NVM, d, 'node.exe'))).map((d) => d.slice(1))
+    : [];
+const resolveNode = (spec) => resolveCached('node:' + spec, async () => {
+    const exact = spec.replace(/^v/, '');
+    if (/^\d+\.\d+\.\d+$/.test(exact))
+        return exact;
+    const releases = await fetchJson('https://nodejs.org/dist/index.json');
+    return pickNodeVersion(releases, spec) ?? Promise.reject(new Error('No Node.js release matches "' + spec + '"'));
+});
+/** nvm unpacks here and then moves the version into NVM_HOME: a move from the sandbox's own disk into a mapped folder
+ *  fails silently, so it must be on the same (mapped) disk. */
+const NVM_TEMP = path.join(NVM_HOME, '.tmp');
+/** nvm, without blocking the event loop (`nvm install` downloads). Resolves with its output. */
+const nvm = (args) => new Promise((resolve) => {
+    const child = spawn(path.join(NVM_HOME, 'nvm.exe'), args, { windowsHide: true, env: { ...process.env, NVM_HOME, NVM_SYMLINK, TEMP: NVM_TEMP, TMP: NVM_TEMP } });
+    let out = '';
+    child.stdout.on('data', (d) => { out += d.toString(); });
+    child.stderr.on('data', (d) => { out += d.toString(); });
+    child.once('error', (e) => resolve(out + e.message));
+    child.once('close', () => resolve(out));
+});
+/** nvm itself: copied from the host's nvm when there is one, else the portable build. */
+const ensureNvm = async () => {
+    if (exists(path.join(NVM_HOME, 'nvm.exe')))
+        return;
+    if (exists(path.join(HOST_NVM, 'nvm.exe'))) {
+        log('Copying nvm from this PC ...');
+        mkdirp(NVM_HOME);
+        // nvm.exe last: it is what marks the install as done, so an interrupted copy is redone.
+        const files = fs.readdirSync(HOST_NVM).filter((f) => /\.(exe|cmd|vbs)$/i.test(f)).sort((a, b) => Number(a.toLowerCase() === 'nvm.exe') - Number(b.toLowerCase() === 'nvm.exe'));
+        for (const file of files)
+            fs.copyFileSync(path.join(HOST_NVM, file), path.join(NVM_HOME, file));
+        return;
+    }
+    // nvm-windows 2.x only ships installers; the portable build is the newest 1.x release that has nvm-noinstall.zip.
+    const asset = await githubAsset('coreybutler/nvm-windows', /^nvm-noinstall\.zip$/, true);
+    log('Downloading nvm-windows (' + asset.url.split('/').slice(-2, -1)[0] + ') ...');
+    await installArchive(asset.url, NVM_HOME, { sha256: asset.sha256, locate: 'nvm.exe', fileName: asset.name });
+};
+/** A Node version: from the host's nvm when it has it (fast, offline), else `nvm install`. */
+const installNodeVersion = async (version) => {
+    const dir = path.join(NVM_HOME, 'v' + version);
+    const fromHost = path.join(HOST_NVM, 'v' + version);
+    if (exists(path.join(dir, 'node.exe')))
+        return;
+    if (exists(path.join(fromHost, 'node.exe'))) {
+        log('Copying Node ' + version + ' from this PC\'s nvm (without global packages) ...');
+        copyNode(fromHost, dir);
+        return;
+    }
+    log('Downloading Node ' + version + ' (~30 MB once) ...');
+    mkdirp(NVM_TEMP);
+    let out;
+    try {
+        out = await nvm(['install', version]);
+    }
+    finally {
+        safeRemove(NVM_TEMP, NVM_HOME);
+    }
+    if (!exists(path.join(dir, 'node.exe')))
+        throw new Error('nvm install ' + version + ' failed: ' + out.trim().split('\n').slice(-2).join(' '));
+};
+const activate = async (version) => {
+    await nvm(['use', version]);
+    if (exists(path.join(NVM_SYMLINK, 'node.exe')))
+        return;
+    fs.rmSync(NVM_SYMLINK, { recursive: true, force: true });
+    fs.symlinkSync(path.join(NVM_HOME, 'v' + version), NVM_SYMLINK, 'junction');
+};
+export const setupNode = async (env, versions, config) => {
+    if (dryRun) {
+        log('(dry run) would provision nvm and Node ' + versions.node.spec + ' (from ' + versions.node.source + ')');
+        return;
+    }
+    await ensureNvm();
+    fs.writeFileSync(path.join(NVM_HOME, 'settings.txt'), ['root: ' + NVM_HOME, 'path: ' + NVM_SYMLINK, 'arch: ' + (arch === 'arm64' ? 'arm64' : '64'), 'proxy: none', ''].join('\r\n'));
+    mkdirp(localDir);
+    for (const extra of versions.nodeExtra) {
+        try {
+            await installNodeVersion(await resolveNode(extra));
+        }
+        catch (e) {
+            warn('Extra Node ' + extra + ': ' + errMsg(e));
+        }
+    }
+    const main = await resolveNode(versions.node.spec);
+    await installNodeVersion(main);
+    // A few more of this PC's versions (copied, never downloaded) so `nvm use` works offline; capped to keep boot fast.
+    for (const version of pickSpreadVersions(hostNvmVersions(), main, HOST_VERSIONS_MAX).slice(1)) {
+        try {
+            await installNodeVersion(version);
+        }
+        catch (e) {
+            warn('Node ' + version + ' from this PC: ' + errMsg(e));
+        }
+    }
+    Object.assign(env.vars, { NVM_HOME, NVM_SYMLINK });
+    // At boot, nvm's symlink selects the version. A project added later must not switch it under the sessions already
+    // running: its own version's folder goes first on its sessions' PATH instead.
+    if (duringSession())
+        env.prepend.push(path.join(NVM_HOME, 'v' + main), NVM_HOME, NVM_SYMLINK);
+    else {
+        await activate(main);
+        env.prepend.push(NVM_HOME, NVM_SYMLINK);
+    }
+    env.summary.push('node: ' + main + ' (from ' + versions.node.source + ', switch with nvm use)');
+    await packageManagers(env, config, main);
+};
+/** Global npm packages (per Node version, like nvm keeps them) and pnpm/yarn through corepack. */
+const packageManagers = async (env, config, version) => {
+    const dir = path.join(NVM_HOME, 'v' + version);
+    const nodeEnv = { ...process.env, PATH: dir + path.delimiter + (process.env.PATH ?? '') };
+    const npm = (args) => execAsync(path.join(dir, 'node.exe'), [path.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js'), ...args], { env: nodeEnv, stdio: 'ignore' });
+    const corepackJs = path.join(dir, 'node_modules', 'corepack', 'dist', 'corepack.js');
+    // Versions copied from this PC come without their global packages, corepack included, and Node 25+ dropped it.
+    const extra = config.corepack && !exists(corepackJs) ? ['corepack'] : [];
+    await installOnce(env, 'npm@' + version, [...extra, ...config.globalPackages], (pkg) => npm(['install', '--global', pkg, '--no-fund', '--no-audit']));
+    if (!config.corepack)
+        return;
+    // Without a packageManager pin, corepack's own known-good versions: the newest pnpm can be one this corepack cannot
+    // start. Mapped folders allow no symlinks, so pnpm uses a flat (hoisted) node_modules instead of its linked layout.
+    Object.assign(env.vars, { COREPACK_HOME: tool('corepack'), COREPACK_ENABLE_DOWNLOAD_PROMPT: '0', COREPACK_DEFAULT_TO_LATEST: '0', npm_config_node_linker: 'hoisted' });
+    // The shims are shared by every session: a project added later keeps the ones made at boot.
+    if (duringSession() && exists(tool('bin', 'pnpm.cmd'))) {
+        env.summary.push('pnpm, yarn: via corepack');
+        return;
+    }
+    try {
+        await execAsync(path.join(dir, 'node.exe'), [corepackJs, 'enable', '--install-directory', mkdirp(tool('bin')), 'pnpm', 'yarn'], { env: nodeEnv, stdio: 'ignore' });
+        env.summary.push('pnpm, yarn: via corepack (package.json "packageManager" picks the version)');
+    }
+    catch (e) {
+        warn('corepack enable failed: ' + errMsg(e));
+    }
+};

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

@@ -0,0 +1,22 @@
+import type { DatabasePlan, GitAccess, Toolchains, ToolVersions } from '../../core/types.js';
+import { type ToolEnv } from './common.js';
+export interface ToolchainOptions {
+    gitEnabled: boolean;
+    gitAccess: GitAccess;
+    hostGit: boolean;
+    refresh: boolean;
+    databases: DatabasePlan[];
+}
+/**
+ * shared: the step's effect is machine-wide and the same for every project (an installer, a registry entry, a
+ * shortcut, the git guard). A project added after boot reuses what the boot's run contributed instead of running it
+ * again under the sessions that already use it.
+ */
+export interface Step {
+    name: string;
+    on: boolean;
+    after?: string[];
+    shared?: boolean;
+    run: (env: ToolEnv) => Promise<void> | void;
+}
+export declare const plan: (config: Toolchains, versions: ToolVersions, o: ToolchainOptions) => Step[];

package/dist/guest/toolchains/plan.js

@@ -0,0 +1,96 @@
+// Which toolchain and database steps this sandbox runs, in the order their PATH entries are listed, and what each
+// step depends on. The scheduler (index.ts) runs them.
+import path from 'node:path';
+import { dataDir, execAsync, exists, localDir } from '../env.js';
+import { projectWorkspace } from '../project-context.js';
+import { arch, installOnce, tool, wanted } from './common.js';
+import { DATABASE_NAMES, setupDatabase } from './databases/index.js';
+import { setupGit } from './git.js';
+import { setupGo } from './go.js';
+import { setupJava } from './java.js';
+import { setupCli } from './cli.js';
+import { setupPyenv, setupVolta, wantsPyenv, wantsVolta } from './managers.js';
+import { setupCpp } from './native/cpp.js';
+import { setupDotnet } from './native/dotnet.js';
+import { setupMesa } from './native/mesa.js';
+import { setupMsvc } from './native/msvc/index.js';
+import { setupRust } from './native/rust.js';
+import { setupNode } from './node.js';
+import { setupPwsh } from './pwsh.js';
+import { setupPython } from './python.js';
+import { setupBun, setupDeno, setupUv, uvVars } from './runtimes.js';
+import { setupPhp } from './scripting/php.js';
+import { setupRuby } from './scripting/ruby.js';
+import { setupVcRuntime } from './scripting/vcruntime.js';
+import { setupVscode } from './vscode.js';
+/** 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: shared with the PC's target\, a separate folder next to it, one on the sandbox's disk, or a path. */
+const cargoTarget = (targetDir) => {
+    if (targetDir === 'shared')
+        return null;
+    if (targetDir === 'separate')
+        return path.join(projectWorkspace(), 'target', 'sandbox');
+    if (targetDir === 'local')
+        return path.join(localDir, 'cargo-target');
+    return targetDir;
+};
+/**
+ * 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 = cargoTarget(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;
+    const cpu = arch === 'arm64' ? 'aarch64' : 'x86_64';
+    return cpu + (wanted(config.msvc.enabled, 'msvc') ? '-pc-windows-msvc' : '-pc-windows-gnu');
+};
+export const plan = (config, versions, o) => {
+    const java = wanted(config.java.enabled, 'java');
+    const python = wanted(config.python.enabled, 'python');
+    return [
+        { name: 'Git', on: o.gitEnabled, shared: true, 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: python, run: (env) => setupPython(env, config.python, versions) },
+        { name: 'pyenv-win', on: 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, shared: true, 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, shared: true, run: (env) => setupMesa(env, config.mesa) },
+        { name: 'VS Code', on: config.vscode.enabled, shared: true, run: (env) => setupVscode(env, o.refresh) },
+        { name: 'Python tools', on: 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.
+        // One server per database in the sandbox: a project that joins later shares the one the boot started.
+        ...o.databases.map((db) => ({ name: DATABASE_NAMES[db.database], on: true, shared: true, after: db.database === 'dynamodb' && java ? ['Java'] : [], run: (env) => setupDatabase(env, db) })),
+    ];
+};

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

@@ -0,0 +1,4 @@
+import { type ToolEnv } from './common.js';
+/** Where pwsh.exe lives (the host's Windows Terminal profile points at the same folder under C:\AgentData). */
+export declare const pwshDir: () => string;
+export declare const setupPwsh: (env: ToolEnv, refresh?: boolean) => Promise<void>;

package/dist/guest/toolchains/pwsh.js

@@ -0,0 +1,14 @@
+// PowerShell 7 (pwsh): the portable zip from PowerShell/PowerShell releases (no MSI: Windows Sandbox would lose it on
+// every boot). Only `pwsh` is added; Windows PowerShell 5.1 (`powershell`, SYSTEM.powershell()) stays what the
+// sandbox's own hooks and scripts use.
+import { pwshAsset } from './catalogue.js';
+import { arch, tool } from './common.js';
+import { setupSingleExe } from './runtimes.js';
+/** Where pwsh.exe lives (the host's Windows Terminal profile points at the same folder under C:\AgentData). */
+export const pwshDir = () => tool('pwsh');
+export const setupPwsh = async (env, refresh = false) => {
+    // pwsh.exe sits at the zip's root next to its runtime and modules: the whole folder is kept.
+    await setupSingleExe(env, 'pwsh', 'PowerShell/PowerShell', pwshAsset(arch), 'pwsh.exe', pwshDir(), { refresh, size: '100 MB', versionArgs: ['-Version'], note: ' (PowerShell 7; powershell is still 5.1)' });
+    // No update banner or telemetry from a copy that provisioning.refresh replaces anyway.
+    Object.assign(env.vars, { POWERSHELL_UPDATECHECK: 'Off', POWERSHELL_TELEMETRY_OPTOUT: '1' });
+};

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

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

package/dist/guest/toolchains/python.js

@@ -0,0 +1,54 @@
+// Python 3 and Python 2: full CPython from the official NuGet packages (portable, with pip).
+import fs from 'node:fs';
+import path from 'node:path';
+import { fetchJson, installArchive } from '../../shared/download.js';
+import { dryRun, execAsync, exists, log, mkdirp } from '../env.js';
+import { resolveCached, tool } from './common.js';
+import { pickPackageVersion } from './versions.js';
+import { duringSession } from '../project-context.js';
+const installPython = async (pkg, spec) => {
+    const version = await resolveCached(pkg + ':' + spec, async () => {
+        const { versions } = await fetchJson('https://api.nuget.org/v3-flatcontainer/' + pkg + '/index.json');
+        return pickPackageVersion(versions, spec) ?? Promise.reject(new Error('No ' + pkg + ' release matches "' + spec + '"'));
+    });
+    const dir = tool('python', pkg + '-' + version);
+    const exe = path.join(dir, 'python.exe');
+    if (!exists(exe)) {
+        log('Downloading Python ' + version + (pkg === 'python2' ? ' (Python 2, ' : ' (') + '~30 MB once) ...');
+        await installArchive('https://api.nuget.org/v3-flatcontainer/' + pkg + '/' + version + '/' + pkg + '.' + version + '.nupkg', dir, { locate: 'python.exe', fileName: pkg + '.' + version + '.zip' });
+    }
+    if (!exists(path.join(dir, 'Scripts', 'pip.exe')) && !exists(path.join(dir, 'Scripts', 'pip2.exe')))
+        await execAsync(exe, ['-m', 'ensurepip', '--default-pip'], { stdio: 'ignore' });
+    return dir;
+};
+/**
+ * The shims folder: tools\shims at boot. A project added later gets one per Python version (tools\shims\<version>)
+ * so the boot project's python3.cmd keeps pointing at its own version.
+ */
+const shimDir = (dir) => (duringSession() ? tool('shims', path.basename(dir)) : tool('shims'));
+/** Writes `<name>.cmd` into the shims folder, e.g. python2.cmd. */
+const shim = (folder, name, command) => {
+    fs.writeFileSync(path.join(mkdirp(folder), name + '.cmd'), '@echo off\r\n' + command + ' %*\r\n');
+};
+const shimPair = (folder, version, dir) => {
+    const python = '"' + path.join(dir, 'python.exe') + '"';
+    shim(folder, 'python' + version, python);
+    shim(folder, 'pip' + version, python + ' -m pip');
+};
+export const setupPython = async (env, config, versions) => {
+    if (dryRun) {
+        log('(dry run) would provision Python ' + versions.python.spec + (config.python2 ? ' and Python 2.7' : ''));
+        return;
+    }
+    const py3 = await installPython('python', versions.python.spec);
+    const shims = shimDir(py3);
+    shimPair(shims, '3', py3);
+    env.prepend.push(py3, path.join(py3, 'Scripts'), shims);
+    env.vars.PYTHONIOENCODING = 'utf-8';
+    env.summary.push('python: ' + path.basename(py3).replace('python-', '') + ' (from ' + versions.python.source + ')');
+    if (!config.python2)
+        return;
+    const py2 = await installPython('python2', '2.7');
+    shimPair(shims, '2', py2);
+    env.summary.push('python2: ' + path.basename(py2).replace('python2-', ''));
+};

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

@@ -0,0 +1,19 @@
+import { type ToolEnv } from './common.js';
+export interface SingleExeOptions {
+    /** Download again even when installed (provisioning.refresh). */
+    refresh?: boolean;
+    /** Keep the whole archive and put this folder inside it on PATH (default: keep only the folder holding the exe). */
+    subdir?: string;
+    versionArgs?: string[];
+    /** Appended to the summary line, e.g. " (PowerShell 7)". */
+    note?: string;
+    /** Rough download size for the progress line, e.g. "35 MB". */
+    size?: string;
+}
+/** A tool from one GitHub release archive, into `dir` (atomically), on PATH. */
+export declare const setupSingleExe: (env: ToolEnv, name: string, repo: string, pattern: RegExp, exeName: string, dir: string, options?: SingleExeOptions) => Promise<void>;
+export declare const setupBun: (env: ToolEnv) => Promise<void>;
+export declare const setupDeno: (env: ToolEnv) => Promise<void>;
+/** Where uv keeps its cache, Pythons and tools (persistent). */
+export declare const uvVars: () => Record<string, string>;
+export declare const setupUv: (env: ToolEnv) => Promise<void>;

package/dist/guest/toolchains/runtimes.js

@@ -0,0 +1,38 @@
+// Bun, uv and Deno: single-binary tools from GitHub releases (claude-mem needs Bun and uv).
+import path from 'node:path';
+import { dryRun, exists, localDir, log } from '../env.js';
+import { arch, installFromGithub, tool, versionOf } from './common.js';
+/** A tool from one GitHub release archive, into `dir` (atomically), on PATH. */
+export const setupSingleExe = async (env, name, repo, pattern, exeName, dir, options = {}) => {
+    if (dryRun) {
+        log('(dry run) would provision ' + name);
+        return;
+    }
+    const bin = options.subdir ? path.join(dir, options.subdir) : dir;
+    const exe = path.join(bin, exeName);
+    if (!exists(exe) || options.refresh) {
+        const size = options.size ? ', ~' + options.size : '';
+        await installFromGithub(repo, pattern, { dest: dir, what: (a) => name + ' (' + a.name + size + ' once)', ...(options.subdir ? {} : { locate: exeName }) });
+    }
+    if (!exists(exe))
+        throw new Error(exeName + ' missing after installing ' + name);
+    env.prepend.push(bin);
+    env.summary.push(name + ': ' + versionOf(exe, options.versionArgs) + (options.note ?? ''));
+};
+export const setupBun = async (env) => {
+    await setupSingleExe(env, 'bun', 'oven-sh/bun', arch === 'arm64' ? /^bun-windows-aarch64\.zip$/ : /^bun-windows-x64\.zip$/, 'bun.exe', tool('bun', 'bin'), { size: '35 MB' });
+    // Bun cannot keep its cache or temp files on a mapped folder (EINVAL); they go to the sandbox's own disk.
+    Object.assign(env.vars, { BUN_INSTALL: tool('bun'), BUN_INSTALL_CACHE_DIR: path.join(localDir, 'bun-cache'), BUN_TMPDIR: path.join(localDir, 'bun-tmp') });
+};
+export const setupDeno = async (env) => {
+    await setupSingleExe(env, 'deno', 'denoland/deno', arch === 'arm64' ? /^deno-aarch64-pc-windows-msvc[.]zip$/ : /^deno-x86_64-pc-windows-msvc[.]zip$/, 'deno.exe', tool('deno', 'bin'), { size: '40 MB' });
+    // `deno install` puts commands in DENO_INSTALL_ROOT/bin: the folder deno.exe is in, already on PATH.
+    Object.assign(env.vars, { DENO_DIR: tool('deno-cache'), DENO_INSTALL_ROOT: tool('deno'), DENO_NO_UPDATE_CHECK: '1' });
+};
+/** Where uv keeps its cache, Pythons and tools (persistent). */
+export const uvVars = () => ({ UV_CACHE_DIR: tool('uv-cache'), UV_PYTHON_INSTALL_DIR: tool('uv-python'), UV_TOOL_DIR: tool('uv-tools'), UV_TOOL_BIN_DIR: tool('uv-bin') });
+export const setupUv = async (env) => {
+    await setupSingleExe(env, 'uv', 'astral-sh/uv', arch === 'arm64' ? /^uv-aarch64-pc-windows-msvc\.zip$/ : /^uv-x86_64-pc-windows-msvc\.zip$/, 'uv.exe', tool('uv'), { size: '20 MB' });
+    Object.assign(env.vars, uvVars());
+    env.prepend.push(tool('uv-bin'));
+};

package/dist/guest/toolchains/scripting/php.d.ts

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

package/dist/guest/toolchains/scripting/php.js

@@ -0,0 +1,71 @@
+// PHP from windows.php.net, with Composer. Composer's global packages live in persistent storage.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fetchJson, fetchText, installArchive } from '../../../shared/download.js';
+import { dryRun, execOutput, exists, log, mkdirp } from '../../env.js';
+import { downloadFile, resolveCached, tool, versionFromFiles } from '../common.js';
+import { pickPackageVersion } from '../versions.js';
+import { setupVcRuntime } from './vcruntime.js';
+const PHP_EXTENSIONS = ['curl', 'fileinfo', 'gd', 'intl', 'mbstring', 'openssl', 'pdo_mysql', 'pdo_pgsql', 'pdo_sqlite', 'sodium', 'sqlite3', 'zip'];
+const COMPOSER = 'https://getcomposer.org/download/latest-stable/composer.phar';
+/** The non-thread-safe x64 zip of the newest release matching `spec` ("8" -> newest 8.x, "8.3" -> newest 8.3.x). */
+const phpBuild = async (spec) => {
+    const releases = await fetchJson('https://windows.php.net/downloads/releases/releases.json');
+    const pick = pickPackageVersion(Object.values(releases).map((r) => r.version), spec);
+    const release = Object.values(releases).find((r) => r.version === pick);
+    const build = release && Object.entries(release).find(([key, value]) => /^nts-vs\d+-x64$/.test(key) && typeof value === 'object' && value.zip)?.[1];
+    if (!release || typeof build !== 'object' || !build.zip)
+        throw new Error('No PHP build for Windows matches "' + spec + '"');
+    return { version: release.version, ...build.zip };
+};
+/** php.ini from the development template with the common extensions switched on (written whole, then renamed). */
+const writePhpIni = (home) => {
+    const ini = path.join(home, 'php.ini');
+    if (exists(ini) || !exists(path.join(home, 'php.ini-development')))
+        return;
+    let text = fs.readFileSync(path.join(home, 'php.ini-development'), 'utf8')
+        .replace(/^;\s*extension_dir\s*=\s*"ext"/m, 'extension_dir = "' + path.join(home, 'ext') + '"');
+    for (const ext of PHP_EXTENSIONS.filter((e) => exists(path.join(home, 'ext', 'php_' + e + '.dll'))))
+        text = text.replace(new RegExp('^;(extension=' + ext + ')\\s*$', 'm'), '$1');
+    fs.writeFileSync(ini + '.tmp', text);
+    fs.renameSync(ini + '.tmp', ini);
+};
+/** Writes `<name>.cmd` into tools\shims (on PATH). */
+const shim = (env, name, command) => {
+    fs.writeFileSync(path.join(mkdirp(tool('shims')), name + '.cmd'), '@echo off\r\n' + command + ' %*\r\n');
+    env.prepend.push(tool('shims'));
+};
+const setupComposer = async (env, php) => {
+    const phar = tool('composer', 'composer.phar');
+    if (!exists(phar)) {
+        log('Downloading Composer (~3 MB once) ...');
+        const sha256 = (await fetchText(COMPOSER + '.sha256sum')).trim().split(/\s+/)[0];
+        await downloadFile(COMPOSER, phar, sha256);
+    }
+    const composerHome = tool('composer-home');
+    env.vars.COMPOSER_HOME = composerHome;
+    env.prepend.push(path.join(composerHome, 'vendor', 'bin'));
+    shim(env, 'composer', '"' + php + '" "' + phar + '"');
+    env.summary.push('composer: ' + (/\d+\.\d+\.\d+/.exec(execOutput(php, [phar, '--version', '--no-ansi']))?.[0] ?? 'installed'));
+};
+export const setupPhp = async (env, config) => {
+    const wantedSpec = versionFromFiles(['.php-version']) ?? { spec: config.version, source: 'config' };
+    if (dryRun) {
+        log('(dry run) would provision PHP ' + wantedSpec.spec + (config.composer ? ' + Composer' : ''));
+        return;
+    }
+    // No summary line of its own: the Visual C++ runtime step (which runs first) already reports it.
+    await setupVcRuntime(env, false);
+    const version = await resolveCached('php:' + wantedSpec.spec, async () => (await phpBuild(wantedSpec.spec)).version);
+    const home = tool('php', version);
+    if (!exists(path.join(home, 'php.exe'))) {
+        const build = await phpBuild(version);
+        log('Downloading PHP ' + version + ' (~30 MB once) ...');
+        await installArchive('https://windows.php.net/downloads/releases/' + build.path, home, { sha256: build.sha256, locate: 'php.exe', fileName: build.path });
+    }
+    writePhpIni(home);
+    env.prepend.push(home);
+    env.summary.push('php: ' + version + ' (from ' + wantedSpec.source + ')');
+    if (config.composer)
+        await setupComposer(env, path.join(home, 'php.exe'));
+};

package/dist/guest/toolchains/scripting/ruby.d.ts

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

package/dist/guest/toolchains/scripting/ruby.js

@@ -0,0 +1,47 @@
+// Ruby from RubyInstaller. Gems live in persistent storage.
+import path from 'node:path';
+import { fetchJson, installArchive } from '../../../shared/download.js';
+import { SYSTEM } from '../../../shared/system.js';
+import { dryRun, execAsync, exists, log } from '../../env.js';
+import { installOnce, resolveCached, tool, versionFromFiles, versionOf } from '../common.js';
+import { pickPackageVersion } from '../versions.js';
+const RUBY_ASSET = /^rubyinstaller-(\d+\.\d+\.\d+)-(\d+)-x64\.7z$/;
+/** The build number after the version in a RubyInstaller file name (rubyinstaller-3.3.1-1-x64.7z -> 1). */
+const buildNumber = (asset) => Number(RUBY_ASSET.exec(asset.name)?.[2] ?? 0);
+/** RubyInstaller builds per Ruby version (newest build of each), from its GitHub releases. */
+const rubyBuilds = async () => {
+    const releases = await fetchJson('https://api.github.com/repos/oneclick/rubyinstaller2/releases?per_page=100');
+    const builds = new Map();
+    for (const asset of releases.filter((r) => !r.draft && !r.prerelease).flatMap((r) => r.assets)) {
+        const version = RUBY_ASSET.exec(asset.name)?.[1];
+        if (!version)
+            continue;
+        const known = builds.get(version);
+        if (!known || buildNumber(known) < buildNumber(asset))
+            builds.set(version, asset);
+    }
+    return builds;
+};
+const sha256Of = (asset) => (asset.digest?.startsWith('sha256:') ? asset.digest.slice(7) : null);
+export const setupRuby = async (env, config) => {
+    const wantedSpec = versionFromFiles(['.ruby-version']) ?? { spec: config.version, source: 'config' };
+    if (dryRun) {
+        log('(dry run) would provision Ruby ' + wantedSpec.spec);
+        return;
+    }
+    const version = await resolveCached('ruby:' + wantedSpec.spec, async () => pickPackageVersion([...(await rubyBuilds()).keys()], wantedSpec.spec) ?? Promise.reject(new Error('No RubyInstaller build matches "' + wantedSpec.spec + '"')));
+    const home = tool('ruby', version);
+    if (!exists(path.join(home, 'bin', 'ruby.exe'))) {
+        const asset = (await rubyBuilds()).get(version);
+        if (!asset)
+            throw new Error('RubyInstaller ' + version + ' is no longer published');
+        log('Downloading Ruby ' + version + ' (~100 MB once) ...');
+        await installArchive(asset.browser_download_url, home, { sha256: sha256Of(asset), locate: 'ruby.exe', up: 1, fileName: asset.name });
+    }
+    const gems = tool('ruby-gems', version.split('.').slice(0, 2).join('.'));
+    Object.assign(env.vars, { GEM_HOME: gems, BUNDLE_USER_HOME: tool('bundle-home') });
+    env.prepend.push(path.join(home, 'bin'), path.join(gems, 'bin'));
+    env.summary.push('ruby: ' + versionOf(path.join(home, 'bin', 'ruby.exe')) + ' (from ' + wantedSpec.source + '; gems with C extensions need MSYS2, not included)');
+    const gem = path.join(home, 'bin', 'gem.cmd');
+    await installOnce(env, 'gem@' + version, config.gems, (pkg) => execAsync(SYSTEM.cmd(), ['/d', '/c', gem, 'install', pkg, '--no-document'], { env: { ...process.env, GEM_HOME: gems } }));
+};

package/dist/guest/toolchains/scripting/vcruntime.d.ts

@@ -0,0 +1,7 @@
+import { type ToolEnv } from '../common.js';
+/**
+ * A real installer (it writes to System32), so it runs on every boot; the installer itself is kept in persistent
+ * storage and only run when Microsoft's signature on it checks out. Resolves true when this call ran the installer.
+ * Only the "Visual C++ runtime" step reports it (`summary`); PHP calls it again just to be sure.
+ */
+export declare const setupVcRuntime: (env: ToolEnv, summary?: boolean) => Promise<boolean>;