windows-development-sandbox 1.0.5 → 1.1.0

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.js

@@ -8,7 +8,7 @@ import { setupSingleExe } from './runtimes.js';
 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, versionArgs: ['-Version'], note: ' (PowerShell 7; powershell is still 5.1)' });
+    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.js

@@ -5,6 +5,7 @@ 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');
@@ -13,21 +14,26 @@ const installPython = async (pkg, spec) => {
     const dir = tool('python', pkg + '-' + version);
     const exe = path.join(dir, 'python.exe');
     if (!exists(exe)) {
-        log('Downloading ' + pkg + ' ' + version + ' ...');
+        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;
 };
-/** Writes `<name>.cmd` into tools\shims, e.g. python2.cmd. */
-const shim = (name, command) => {
-    fs.writeFileSync(path.join(mkdirp(tool('shims')), name + '.cmd'), '@echo off\r\n' + command + ' %*\r\n');
+/**
+ * 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 = (version, dir) => {
+const shimPair = (folder, version, dir) => {
     const python = '"' + path.join(dir, 'python.exe') + '"';
-    shim('python' + version, python);
-    shim('pip' + version, python + ' -m pip');
+    shim(folder, 'python' + version, python);
+    shim(folder, 'pip' + version, python + ' -m pip');
 };
 export const setupPython = async (env, config, versions) => {
     if (dryRun) {
@@ -35,13 +41,14 @@ export const setupPython = async (env, config, versions) => {
         return;
     }
     const py3 = await installPython('python', versions.python.spec);
-    shimPair('3', py3);
-    env.prepend.push(py3, path.join(py3, 'Scripts'), tool('shims'));
+    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('2', py2);
+    shimPair(shims, '2', py2);
     env.summary.push('python2: ' + path.basename(py2).replace('python2-', ''));
 };

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

@@ -7,6 +7,8 @@ export interface SingleExeOptions {
     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>;

package/dist/guest/toolchains/runtimes.js

@@ -1,8 +1,7 @@
 // Bun, uv and Deno: single-binary tools from GitHub releases (claude-mem needs Bun and uv).
 import path from 'node:path';
-import { githubAsset, installArchive } from '../../shared/download.js';
 import { dryRun, exists, localDir, log } from '../env.js';
-import { arch, tool, versionOf } from './common.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) {
@@ -12,9 +11,8 @@ export const setupSingleExe = async (env, name, repo, pattern, exeName, dir, opt
     const bin = options.subdir ? path.join(dir, options.subdir) : dir;
     const exe = path.join(bin, exeName);
     if (!exists(exe) || options.refresh) {
-        const asset = await githubAsset(repo, pattern);
-        log('Downloading ' + asset.name + ' ...');
-        await installArchive(asset.url, dir, { sha256: asset.sha256, fileName: asset.name, ...(options.subdir ? {} : { locate: exeName }) });
+        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);
@@ -22,19 +20,19 @@ export const setupSingleExe = async (env, name, repo, pattern, exeName, dir, opt
     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'));
+    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'));
+    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'));
+    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>;

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

@@ -0,0 +1,45 @@
+// The Visual C++ runtime (vcruntime140.dll & co.) that PHP and other native tools need.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnAsync } from '../../../shared/download.js';
+import { SYSTEM } from '../../../shared/system.js';
+import { dryRun, execOutput, exists, log } from '../../env.js';
+import { downloadFile, tool } from '../common.js';
+const VC_REDIST = 'https://aka.ms/vs/17/release/vc_redist.x64.exe';
+const MICROSOFT_SIGNER = 'CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US';
+/** 1638: a newer version is already installed; 3010: installed, a restart would finish it (not needed for the DLLs). */
+const OK_EXIT_CODES = [0, 1638, 3010];
+/** The subject of a valid Authenticode signature, or '' when the file is unsigned or tampered with. */
+const signerOf = (file) => execOutput(SYSTEM.powershell(), ['-NoLogo', '-NoProfile', '-Command',
+    "$s = Get-AuthenticodeSignature -LiteralPath '" + file.replace(/'/g, "''") + "'; if ($s.Status -eq 'Valid') { $s.SignerCertificate.Subject }"]).trim();
+/**
+ * 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 const setupVcRuntime = async (env, summary = true) => {
+    if (dryRun) {
+        log('(dry run) would install the Visual C++ runtime');
+        return false;
+    }
+    const system32 = path.join(process.env.WINDIR ?? 'C:\\Windows', 'System32');
+    const missing = !exists(path.join(system32, 'vcruntime140.dll')) || !exists(path.join(system32, 'msvcp140.dll'));
+    if (missing) {
+        const installer = tool('vcredist', 'vc_redist.x64.exe');
+        if (!exists(installer)) {
+            log('Downloading the Visual C++ runtime (~25 MB once) ...');
+            await downloadFile(VC_REDIST, installer);
+        }
+        if (signerOf(installer) !== MICROSOFT_SIGNER) {
+            fs.rmSync(installer, { force: true });
+            throw new Error('vc_redist.x64.exe is not signed by Microsoft; deleted it (it is downloaded again next boot)');
+        }
+        log('Installing the Visual C++ runtime ...');
+        const code = await spawnAsync(installer, ['/install', '/quiet', '/norestart']);
+        if (!OK_EXIT_CODES.includes(code ?? -1) || !exists(path.join(system32, 'vcruntime140.dll')))
+            throw new Error('the Visual C++ runtime installer failed (exit ' + code + ')');
+    }
+    if (summary)
+        env.summary.push('vc++ runtime: installed');
+    return missing;
+};

package/dist/guest/view.js

@@ -3,8 +3,28 @@
 import { connect, runTerminalClient } from '../shared/pty-client.js';
 import { readSession } from '../shared/rundir.js';
 import { dataDir } from './env.js';
+/** A session that is still being set up (its project provisioning, its agent installing): show the progress until it runs. */
+const waitUntilStarted = async (id) => {
+    let last = '';
+    for (let i = 0; i < 3600; i++) {
+        const s = readSession(dataDir, id);
+        if (s && s.phase !== 'starting')
+            return s;
+        if (s && s.message !== last) {
+            console.log('  ' + s.message);
+            last = s.message;
+        }
+        await new Promise((r) => setTimeout(r, 500));
+    }
+    return readSession(dataDir, id);
+};
 export const viewSession = async (id) => {
-    const session = readSession(dataDir, id);
+    const session = await waitUntilStarted(id);
+    if (session?.phase === 'failed') {
+        console.error('Session ' + id + ' could not start: ' + session.message);
+        await new Promise((r) => setTimeout(r, 30000));
+        return 1;
+    }
     if (!session?.attach) {
         console.error('Session ' + id + ' is not running.');
         return 1;

package/dist/host/accounts.js

@@ -4,8 +4,14 @@
 // restarted in place with --continue so the conversation carries on.
 import fs from 'node:fs';
 import path from 'node:path';
+import { z } from 'zod';
+import { isSafeFileName } from '../shared/paths.js';
+import { assertTestWritable } from './test-guard.js';
+import { readValid, writeJsonAtomic } from '../shared/rundir.js';
 import { assertNoLinks, fail, fileExists, isLink, removeLink, tryReadJson, writeJson } from '../core/util.js';
 const NAME = /^[A-Za-z0-9_-]{1,40}$/;
+const AccountSchema = z.object({ name: z.string().regex(NAME), savedAt: z.string().max(64), email: z.string().max(200).nullable(), credentials: z.looseObject({}), oauthAccount: z.unknown() });
+const IndexSchema = z.object({ default: z.string().regex(NAME).optional(), active: z.record(z.string().max(200), z.string().regex(NAME)).optional() });
 const ACCOUNT_CACHES = ['remote-settings.json', 'policy-limits.json', 'policy-limits.json.stamp.json'];
 const MAX_LOGIN_BYTES = 1024 * 1024;
 /** .claude.json holds per-project state and can be large; it is still capped so a hostile file cannot exhaust memory. */
@@ -16,15 +22,17 @@ const storageOf = (dataPath) => path.dirname(path.dirname(dataPath));
 const dataName = (dataPath) => path.basename(dataPath);
 const accountFile = (storageRoot, name) => path.join(accountsDir(storageRoot), name + '.json');
 const indexFile = (storageRoot) => path.join(accountsDir(storageRoot), 'index.json');
-const readIndex = (storageRoot) => tryReadJson(indexFile(storageRoot)) ?? {};
-const updateIndex = (storageRoot, change) => writeJson(indexFile(storageRoot), change(readIndex(storageRoot)));
-const assertName = (name) => { if (!NAME.test(name))
+const readIndex = (storageRoot) => readValid(IndexSchema, indexFile(storageRoot)) ?? {};
+const updateIndex = (storageRoot, change) => writeJsonAtomic(indexFile(storageRoot), change(readIndex(storageRoot)));
+/** A file name of its own: not "index" (the index file), not a Windows device name such as con or nul. */
+const validName = (name) => NAME.test(name) && name.toLowerCase() !== 'index' && isSafeFileName(name + '.json');
+const assertName = (name) => { if (!validName(name))
     fail('Invalid account name "' + name + '".', 'Use letters, numbers, - and _ only (max 40), e.g. work or personal.'); };
 const emailOf = (oauthAccount) => {
     const email = oauthAccount?.emailAddress;
     return typeof email === 'string' ? email.slice(0, 200) : null;
 };
-export const readAccount = (storageRoot, name) => (NAME.test(name) ? tryReadJson(accountFile(storageRoot, name)) : null);
+export const readAccount = (storageRoot, name) => (validName(name) ? readValid(AccountSchema, accountFile(storageRoot, name)) : null);
 export const defaultAccount = (storageRoot) => readIndex(storageRoot).default ?? null;
 export const activeAccount = (dataPath) => readIndex(storageOf(dataPath)).active?.[dataName(dataPath)] ?? null;
 const setActive = (dataPath, name) => updateIndex(storageOf(dataPath), (i) => ({ ...i, active: { ...i.active, [dataName(dataPath)]: name } }));
@@ -51,7 +59,7 @@ const readLogin = (claudeDir, globalStateFile) => {
 };
 const store = (storageRoot, name, login) => {
     const account = { name, savedAt: new Date().toISOString(), email: emailOf(login.oauthAccount), ...login };
-    writeJson(accountFile(storageRoot, name), account);
+    writeJsonAtomic(accountFile(storageRoot, name), account);
     return account;
 };
 const sandboxLogin = (dataPath) => {
@@ -71,6 +79,7 @@ export const saveAccount = (storageRoot, dataPath, name, fromHost) => {
 };
 /** Replaces a file that may be a sandbox-planted link instead of writing through it. */
 const writeSandboxJson = (file, value) => {
+    assertTestWritable(file);
     if (isLink(file))
         removeLink(file);
     writeJson(file, value);

package/dist/host/agent-commands.d.ts

@@ -0,0 +1,25 @@
+import type { Config } from '../core/types.js';
+export declare const commandsDir: (storageRoot: string) => string;
+export interface AgentCommand {
+    harness: string;
+    command: string;
+    real: string;
+}
+/** The agent's own executable on this PC, skipping this tool's forwarding files. */
+export declare const realAgent: (command: string, skipDir: string, pathValue?: string) => string | null;
+/** The agents that get a forwarding command: installed on this PC, and listed (or "auto" = all of them). */
+export declare const agentCommands: (config: Config, storageRoot: string, pathValue?: string) => AgentCommand[];
+/** The .cmd file for one agent (cmd, PowerShell and Windows Terminal all run it). */
+export declare const forwardingCmd: (a: AgentCommand, node: string, entry: string) => string;
+/** The same for Git Bash, which looks for a file without an extension. */
+export declare const forwardingSh: (a: AgentCommand, node: string, entry: string) => string;
+export interface Reconciled {
+    on: boolean;
+    commands: AgentCommand[];
+    changed: boolean;
+}
+/**
+ * Makes this PC match agentCommands: on = a forwarding file per installed agent and the folder first on your PATH;
+ * off = no files, no PATH entry. Only touches files it wrote and its own PATH entry; does nothing when already right.
+ */
+export declare const reconcileAgentCommands: (config: Config, storageRoot: string, node: string, entry: string) => Reconciled;