windows-development-sandbox 1.4.1 → 1.4.3

package/dist/guest/toolchains/native/msvc/packages.js

@@ -3,24 +3,40 @@
 // .vsix files, the SDK from its .msi files with `msiexec /a`.
 import fs from 'node:fs';
 import path from 'node:path';
-import { download, extractArchive, fetchJson } from '../../../../shared/download.js';
-import { safeRemove } from '../../../../shared/safe-remove.js';
+import { downloader, extractArchive, fetchJson } from '../../../../shared/download/index.js';
+import { safeRemove } from '../../../../shared/io/safe-remove.js';
 import { system32 } from '../../../../shared/system.js';
-import { execAsync, exists, log, mkdirp } from '../../../env.js';
-import { msiCabs, pickMsvcVersion, pickWindowsSdk } from '../../versions.js';
+import { execAsync } from '../../../runtime/process.js';
+import { exists, mkdirp } from '../../../runtime/fs.js';
+import { log } from '../../../runtime/log.js';
+import { msiCabs, pickMsvcVersion, pickWindowsSdk } from '../../../../core/detect/versions.js';
 import { hostBin, ROOT } from './tree.js';
 const CHANNEL = 'https://aka.ms/vs/17/release/channel';
 const MANIFEST_DAY_MS = 24 * 60 * 60 * 1000;
 /** The compiler's packages (host x64, target x64): tools, resources, CRT headers/libs, ASAN/PGO headers. */
-const MSVC_PARTS = ['tools.hostx64.targetx64.base', 'tools.hostx64.targetx64.res.base', 'crt.headers.base', 'crt.x64.desktop.base', 'crt.x64.store.base', 'crt.source.base', 'asan.headers.base', 'pgo.headers.base'];
+const MSVC_PARTS = [
+    'tools.hostx64.targetx64.base',
+    'tools.hostx64.targetx64.res.base',
+    'crt.headers.base',
+    'crt.x64.desktop.base',
+    'crt.x64.store.base',
+    'crt.source.base',
+    'asan.headers.base',
+    'pgo.headers.base',
+];
 /** Without these the compiler is unusable; the other parts are taken when the manifest has them. */
 const REQUIRED_PARTS = ['tools', 'crt.headers', 'crt.x64.desktop'];
 /** The SDK's .msi files (Desktop + UCRT + Store headers/libs/tools for x64), as in portable-msvc.py. */
 const SDK_MSIS = [
-    'Windows SDK for Windows Store Apps Tools-x86_en-us.msi', 'Windows SDK for Windows Store Apps Headers-x86_en-us.msi',
-    'Windows SDK for Windows Store Apps Headers OnecoreUap-x86_en-us.msi', 'Windows SDK for Windows Store Apps Libs-x86_en-us.msi',
-    'Universal CRT Headers Libraries and Sources-x86_en-us.msi', 'Windows SDK Desktop Headers x86-x86_en-us.msi',
-    'Windows SDK Desktop Headers x64-x86_en-us.msi', 'Windows SDK Desktop Libs x64-x86_en-us.msi', 'Windows SDK Desktop Tools x64-x86_en-us.msi',
+    'Windows SDK for Windows Store Apps Tools-x86_en-us.msi',
+    'Windows SDK for Windows Store Apps Headers-x86_en-us.msi',
+    'Windows SDK for Windows Store Apps Headers OnecoreUap-x86_en-us.msi',
+    'Windows SDK for Windows Store Apps Libs-x86_en-us.msi',
+    'Universal CRT Headers Libraries and Sources-x86_en-us.msi',
+    'Windows SDK Desktop Headers x86-x86_en-us.msi',
+    'Windows SDK Desktop Headers x64-x86_en-us.msi',
+    'Windows SDK Desktop Libs x64-x86_en-us.msi',
+    'Windows SDK Desktop Tools x64-x86_en-us.msi',
 ];
 /** The VS manifest (~18 MB), cached for a day. */
 const manifest = async () => {
@@ -30,16 +46,19 @@ const manifest = async () => {
         try {
             return JSON.parse(fs.readFileSync(cached, 'utf8'));
         }
-        catch { /* downloaded again below */ }
+        catch {
+            /* downloaded again below */
+        }
     }
     const channel = await fetchJson(CHANNEL);
-    const item = channel.channelItems.find((i) => i.id === 'Microsoft.VisualStudio.Manifests.VisualStudio')?.payloads?.[0];
+    const item = channel.channelItems.find((i) => i.id === 'Microsoft.VisualStudio.Manifests.VisualStudio')
+        ?.payloads?.[0];
     if (!item)
         throw new Error('the Visual Studio channel has no package manifest');
     mkdirp(ROOT);
     // The channel's sha256 for the manifest is not the file's hash (portable-msvc.py does not check it either); the
     // manifest comes over HTTPS from Microsoft, and every package payload it lists IS checked against its own sha256.
-    await download(item.url, cached);
+    await downloader.file(item.url, cached);
     return JSON.parse(fs.readFileSync(cached, 'utf8'));
 };
 /** .vsix contents are percent-encoded file names under Contents/; unpack them into the root, names decoded. */
@@ -54,7 +73,9 @@ const unpackVsix = async (vsix, work) => {
                 if (name.includes('%'))
                     name = decodeURIComponent(name);
             }
-            catch { /* not percent-encoded after all */ }
+            catch {
+                /* not percent-encoded after all */
+            }
             const to = path.join(dir, name);
             if (to !== from)
                 fs.renameSync(from, to);
@@ -66,15 +87,29 @@ const unpackVsix = async (vsix, work) => {
     fs.cpSync(path.join(out, 'Contents'), ROOT, { recursive: true, force: true });
     safeRemove(out, work);
 };
-/** An administrative install only unpacks files; its verbose log explains a failure (e.g. a path over 260 characters). */
+/**
+ * An administrative install only unpacks files; its verbose log explains a failure (e.g. a path over 260 characters).
+ */
 const unpackMsi = async (msi) => {
     const logFile = msi + '.log';
     try {
-        await execAsync(system32('msiexec.exe'), ['/a', msi, '/quiet', '/qn', 'TARGETDIR=' + ROOT, '/l*v', logFile], { stdio: 'ignore' });
+        await execAsync(system32('msiexec.exe'), ['/a', msi, '/quiet', '/qn', 'TARGETDIR=' + ROOT, '/l*v', logFile], {
+            stdio: 'ignore',
+        });
     }
     catch (e) {
-        const lines = exists(logFile) ? fs.readFileSync(logFile, 'utf16le').split(/\r?\n/).filter((l) => /error|return value 3|failed/i.test(l)).slice(-4).join(' | ') : '';
-        throw new Error(path.basename(msi) + ' did not unpack: ' + (e instanceof Error ? e.message : String(e)) + (lines ? ' (' + lines.slice(0, 600) + ')' : ''));
+        const lines = exists(logFile)
+            ? fs
+                .readFileSync(logFile, 'utf16le')
+                .split(/\r?\n/)
+                .filter((l) => /error|return value 3|failed/i.test(l))
+                .slice(-4)
+                .join(' | ')
+            : '';
+        throw new Error(path.basename(msi) +
+            ' did not unpack: ' +
+            (e instanceof Error ? e.message : String(e)) +
+            (lines ? ' (' + lines.slice(0, 600) + ')' : ''));
     }
 };
 /** The manifest's packages by id, with the lookups the installer needs. */
@@ -91,16 +126,23 @@ const catalogue = (m) => {
 const payloadFetcher = (work) => async (p) => {
     const file = path.join(work, path.basename(p.fileName.replace(/\\/g, '/')));
     if (!exists(file))
-        await download(p.url, file, p.sha256);
+        await downloader.file(p.url, file, p.sha256);
     return file;
 };
-/** Newest folder under VC\Tools\MSVC that holds a compiler (named after the toolset, 14.44.35207, not the package version). */
+/**
+ * Newest folder under VC\Tools\MSVC that holds a compiler (named after the toolset, 14.44.35207, not the package
+ * version).
+ */
 const unpackedToolset = () => {
     const toolsRoot = path.join(ROOT, 'VC', 'Tools', 'MSVC');
-    return fs.readdirSync(toolsRoot).filter((d) => exists(hostBin(d, 'cl.exe'))).sort((a, b) => a.localeCompare(b, undefined, { numeric: true })).pop();
+    return fs
+        .readdirSync(toolsRoot)
+        .filter((d) => exists(hostBin(d, 'cl.exe')))
+        .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
+        .pop();
 };
 /** Downloads and unpacks MSVC and the Windows SDK into tools\msvc; resolves with the toolset and SDK folder names. */
-export const installPackages = async (config) => {
+export async function installPackages(config) {
     const { ids, pick } = catalogue(await manifest());
     const version = pickMsvcVersion(ids, config.msvcVersion);
     if (!version)
@@ -146,11 +188,15 @@ export const installPackages = async (config) => {
     for (const name of fs.readdirSync(ROOT).filter((n) => n.toLowerCase().endsWith('.msi')))
         fs.rmSync(path.join(ROOT, name), { force: true });
     safeRemove(work, ROOT);
-    const sdkVersion = fs.readdirSync(path.join(ROOT, 'Windows Kits', '10', 'Include')).filter((d) => d.startsWith('10.0.' + sdk.build)).sort().pop();
+    const sdkVersion = fs
+        .readdirSync(path.join(ROOT, 'Windows Kits', '10', 'Include'))
+        .filter((d) => d.startsWith('10.0.' + sdk.build))
+        .sort()
+        .pop();
     if (!sdkVersion)
         throw new Error('the Windows SDK did not unpack (no Include\\10.0.' + sdk.build + '.*)');
     const toolset = unpackedToolset();
     if (!toolset)
         throw new Error('MSVC ' + version + ' did not unpack (no cl.exe under VC\\Tools\\MSVC)');
     return { msvc: toolset, sdk: sdkVersion };
-};
+}

package/dist/guest/toolchains/native/msvc/tree.d.ts

@@ -1,15 +1,15 @@
 import { z } from 'zod';
 export declare const ROOT: string;
 export declare const MARKER: string;
-export declare const msvcTools: (msvc: string, ...parts: string[]) => string;
-export declare const hostBin: (msvc: string, ...parts: string[]) => string;
-export declare const hasCompiler: (msvc: string) => boolean;
-declare const Installed: z.ZodObject<{
+export declare function msvcTools(msvc: string, ...parts: string[]): string;
+export declare function hostBin(msvc: string, ...parts: string[]): string;
+export declare function hasCompiler(msvc: string): boolean;
+declare const InstalledSchema: z.ZodObject<{
     msvc: z.ZodString;
     sdk: z.ZodString;
     want: z.ZodString;
 }, z.core.$strip>;
-export type Installed = z.infer<typeof Installed>;
+export type Installed = z.infer<typeof InstalledSchema>;
 /** What the last finished install recorded; null for a missing, unreadable or half-written marker. */
-export declare const readInstalled: () => Installed | null;
+export declare function readInstalled(): Installed | null;
 export {};

package/dist/guest/toolchains/native/msvc/tree.js

@@ -2,20 +2,26 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { z } from 'zod';
-import { exists } from '../../../env.js';
-import { tool } from '../../common.js';
+import { exists } from '../../../runtime/fs.js';
+import { tool } from '../../tool-env.js';
 export const ROOT = tool('msvc');
 export const MARKER = path.join(ROOT, '.installed.json');
-export const msvcTools = (msvc, ...parts) => path.join(ROOT, 'VC', 'Tools', 'MSVC', msvc, ...parts);
-export const hostBin = (msvc, ...parts) => msvcTools(msvc, 'bin', 'Hostx64', 'x64', ...parts);
-export const hasCompiler = (msvc) => exists(hostBin(msvc, 'cl.exe'));
-const Installed = z.object({ msvc: z.string().min(1), sdk: z.string().min(1), want: z.string() });
+export function msvcTools(msvc, ...parts) {
+    return path.join(ROOT, 'VC', 'Tools', 'MSVC', msvc, ...parts);
+}
+export function hostBin(msvc, ...parts) {
+    return msvcTools(msvc, 'bin', 'Hostx64', 'x64', ...parts);
+}
+export function hasCompiler(msvc) {
+    return exists(hostBin(msvc, 'cl.exe'));
+}
+const InstalledSchema = z.object({ msvc: z.string().min(1), sdk: z.string().min(1), want: z.string() });
 /** What the last finished install recorded; null for a missing, unreadable or half-written marker. */
-export const readInstalled = () => {
+export function readInstalled() {
     try {
-        return Installed.safeParse(JSON.parse(fs.readFileSync(MARKER, 'utf8'))).data ?? null;
+        return InstalledSchema.safeParse(JSON.parse(fs.readFileSync(MARKER, 'utf8'))).data ?? null;
     }
     catch {
         return null;
     }
-};
+}

package/dist/guest/toolchains/native/rust-extras.d.ts

@@ -0,0 +1,23 @@
+import type { Toolchains } from '../../../core/types.js';
+import { type ToolEnv } from '../tool-env.js';
+/** "separate": tools\shims\cargo\cargo.exe in front of the real cargo, which it runs with the checkout's target dir. */
+export declare function cargoShim(env: ToolEnv, rust: Toolchains['rust']): void;
+/**
+ * GNU host: Rust links through tools\shims\linkgate.exe (sandbox/linkgate.cs), which lets only `linkSlots` links run
+ * at once in the whole sandbox and, with linker "lld", has MinGW's gcc use Rust's own lld instead of GNU ld.
+ */
+export declare function linkGate(env: ToolEnv, rust: Toolchains['rust'], host: string): void;
+/**
+ * Cargo defaults that fit Windows, written only when there is no $CARGO_HOME\config.toml yet: fewer parallel jobs
+ * (parallel rustc ran out of paging file) and, for the GNU host, only line tables as debug info (full debug info made
+ * test executables bigger than the 2 GB Windows allows).
+ */
+export declare function cargoDefaults(host: string): void;
+/**
+ * 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.
+ */
+export declare function rustCaches(rust: Toolchains['rust']): Record<string, string>;
+/** "auto": the msvc host when the MSVC step runs (as on most PCs), else GNU with MinGW. */
+export declare function rustHost(config: Toolchains): string;

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

@@ -0,0 +1,100 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { dataDir, localDir } from '../../runtime/paths.js';
+import { exists, mkdirp } from '../../runtime/fs.js';
+import { execOutput } from '../../runtime/process.js';
+import { ensureCompiled } from '../../runtime/csc.js';
+import { arch, tool } from '../tool-env.js';
+import { wanted } from '../detect.js';
+/**
+ * Where cargo builds: shared with the PC's target\, one on the sandbox's disk, or a path. "separate" sets no variable:
+ * the cargo shim (sandbox/cargoshim.cs) gives every checkout its own target\sandbox, so git worktrees of several agents
+ * never overwrite each other's builds.
+ */
+const cargoTarget = (targetDir) => {
+    if (targetDir === 'shared' || targetDir === 'separate')
+        return null;
+    if (targetDir === 'local')
+        return path.join(localDir, 'cargo-target');
+    return targetDir;
+};
+/** "separate": tools\shims\cargo\cargo.exe in front of the real cargo, which it runs with the checkout's target dir. */
+export function cargoShim(env, rust) {
+    const real = path.join(tool('rust', 'cargo', 'bin'), 'cargo.exe');
+    if (rust.targetDir !== 'separate' || !exists(real))
+        return;
+    const dir = mkdirp(tool('shims', 'cargo'));
+    fs.copyFileSync(ensureCompiled('cargoshim'), path.join(dir, 'cargo.exe'));
+    env.prepend.unshift(dir);
+    env.vars.AGENT_REAL_CARGO = real;
+}
+/**
+ * GNU host: Rust links through tools\shims\linkgate.exe (sandbox/linkgate.cs), which lets only `linkSlots` links run
+ * at once in the whole sandbox and, with linker "lld", has MinGW's gcc use Rust's own lld instead of GNU ld.
+ */
+export function linkGate(env, rust, host) {
+    const gcc = tool('mingw', 'mingw64', 'bin', 'gcc.exe');
+    if (!host.endsWith('-pc-windows-gnu') || !exists(gcc))
+        return;
+    const gate = path.join(mkdirp(tool('shims')), 'linkgate.exe');
+    fs.copyFileSync(ensureCompiled('linkgate'), gate);
+    const memoryGb = os.totalmem() / 1024 ** 3;
+    const slots = rust.linkSlots === 'auto' ? Math.max(2, Math.min(4, Math.floor(memoryGb / 8))) : rust.linkSlots;
+    env.vars.AGENT_LINK_SLOTS = String(slots);
+    env.vars.AGENT_REAL_LINKER = gcc;
+    env.vars.CARGO_TARGET_X86_64_PC_WINDOWS_GNU_LINKER = gate;
+    const rustEnv = { ...process.env, RUSTUP_HOME: tool('rust', 'rustup'), CARGO_HOME: tool('rust', 'cargo') };
+    const sysroot = rust.linker === 'lld'
+        ? execOutput(tool('rust', 'cargo', 'bin', 'rustc.exe'), ['--print', 'sysroot'], { env: rustEnv })
+        : '';
+    const lld = sysroot ? path.join(sysroot, 'lib', 'rustlib', host, 'bin', 'gcc-ld') : '';
+    if (lld && exists(path.join(lld, 'ld.lld.exe')))
+        env.vars.AGENT_LLD_DIR = lld;
+    env.summary.push('rust linking: ' +
+        (env.vars.AGENT_LLD_DIR ? 'lld' : 'GNU ld') +
+        ', at most ' +
+        env.vars.AGENT_LINK_SLOTS +
+        ' at once');
+}
+/**
+ * Cargo defaults that fit Windows, written only when there is no $CARGO_HOME\config.toml yet: fewer parallel jobs
+ * (parallel rustc ran out of paging file) and, for the GNU host, only line tables as debug info (full debug info made
+ * test executables bigger than the 2 GB Windows allows).
+ */
+export function cargoDefaults(host) {
+    const file = tool('rust', 'cargo', 'config.toml');
+    if (exists(file) || !exists(path.dirname(file)))
+        return;
+    // Several agents often build at once: up to 4 jobs each (8 each crashed Windows inside the sandbox on 13 Oct 2026).
+    const jobs = Math.max(2, Math.min(4, Math.floor(os.cpus().length / 4)));
+    const gnu = host.endsWith('-gnu');
+    fs.writeFileSync(file, [
+        '# Written by windows-development-sandbox once; edit freely, it is never overwritten.',
+        '[build]',
+        'jobs = ' + jobs,
+        '',
+        ...(gnu
+            ? ['[profile.dev]', 'debug = "line-tables-only"', '', '[profile.test]', 'debug = "line-tables-only"', '']
+            : []),
+    ].join('\n'));
+}
+/**
+ * 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.
+ */
+export function 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. */
+export function 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');
+}

package/dist/guest/toolchains/native/rust.d.ts

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

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

@@ -1,10 +1,15 @@
 // 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 { dryRun } from '../../runtime/paths.js';
+import { execAsync } from '../../runtime/process.js';
+import { exists } from '../../runtime/fs.js';
+import { log } from '../../runtime/log.js';
+import { arch, tool, versionOf } from '../tool-env.js';
+import { downloadFile } from '../install.js';
+import { installOnce } from '../package-ledger.js';
 import { crateInstaller } from './binstall.js';
 import { installedMsvcEnv } from './msvc/index.js';
-export const setupRust = async (env, config, refresh) => {
+export async function setupRust(env, config, refresh) {
     const RUSTUP_HOME = tool('rust', 'rustup');
     const CARGO_HOME = tool('rust', 'cargo');
     const rustEnv = { env: { ...process.env, RUSTUP_HOME, CARGO_HOME } };
@@ -16,13 +21,27 @@ export const setupRust = async (env, config, refresh) => {
     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);
+        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, ['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);
@@ -38,8 +57,20 @@ export const setupRust = async (env, config, refresh) => {
     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).
+        ? {
+            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).
     await installOnce(env, 'cargo', config.crates, crateInstaller(CARGO_HOME, cargoEnv));
-};
+}

package/dist/guest/toolchains/{scripting → native}/vcruntime.d.ts

@@ -1,7 +1,7 @@
-import { type ToolEnv } from '../common.js';
+import { type ToolEnv } from '../tool-env.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>;
+export declare function setupVcRuntime(env: ToolEnv, summary?: boolean): Promise<boolean>;

package/dist/guest/toolchains/{scripting → native}/vcruntime.js

@@ -1,23 +1,33 @@
 // 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 { spawnAsync } from '../../../shared/download/index.js';
 import { SYSTEM } from '../../../shared/system.js';
-import { dryRun, execOutput, exists, log } from '../../env.js';
-import { downloadFile, tool } from '../common.js';
+import { dryRun } from '../../runtime/paths.js';
+import { execOutput } from '../../runtime/process.js';
+import { exists } from '../../runtime/fs.js';
+import { log } from '../../runtime/log.js';
+import { downloadFile } from '../install.js';
+import { tool } from '../tool-env.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();
+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) => {
+export async function setupVcRuntime(env, summary = true) {
     if (dryRun) {
         log('(dry run) would install the Visual C++ runtime');
         return false;
@@ -42,4 +52,4 @@ export const setupVcRuntime = async (env, summary = true) => {
     if (summary)
         env.summary.push('vc++ runtime: installed');
     return missing;
-};
+}

package/dist/guest/toolchains/package-ledger.d.ts

@@ -0,0 +1,17 @@
+import { type ToolEnv } from './tool-env.js';
+export declare class PackageLedger {
+    private readonly file;
+    constructor(file?: () => string);
+    has(group: string, pkg: string): boolean;
+    /** Records `pkg` as installed now (re-read first: parallel steps write the same file). */
+    mark(group: string, pkg: string): void;
+    /**
+     * Installs each package that is not installed yet (group e.g. "npm@22.11.0"). One failing package is reported and
+     * skipped; it is tried again next boot.
+     */
+    installOnce(env: ToolEnv, group: string, packages: readonly string[], install: (pkg: string) => void | Promise<void>): Promise<void>;
+    private read;
+}
+export declare const packageLedger: PackageLedger;
+/** packageLedger.installOnce: installs the packages of `group` that are not installed yet. */
+export declare function installOnce(env: ToolEnv, group: string, packages: readonly string[], install: (pkg: string) => void | Promise<void>): Promise<void>;

package/dist/guest/toolchains/package-ledger.js

@@ -0,0 +1,54 @@
+// Global packages (npm, gems, go tools, uv tools, cargo crates) installed once: remembered in
+// tools\installed-packages.json under "<group>:<package>" with the time it was installed.
+import { z } from 'zod';
+import { writeJsonAtomic } from '../../shared/io/json.js';
+import { log, warn } from '../runtime/log.js';
+import { errMsg } from '../../core/util/errors.js';
+import { tool } from './tool-env.js';
+import { readState } from './state-file.js';
+const LedgerSchema = z.record(z.string(), z.string());
+export class PackageLedger {
+    file;
+    constructor(file = () => tool('installed-packages.json')) {
+        this.file = file;
+    }
+    has(group, pkg) {
+        return Boolean(this.read()[group + ':' + pkg]);
+    }
+    /** Records `pkg` as installed now (re-read first: parallel steps write the same file). */
+    mark(group, pkg) {
+        writeJsonAtomic(this.file(), { ...this.read(), [group + ':' + pkg]: new Date().toISOString() });
+    }
+    /**
+     * Installs each package that is not installed yet (group e.g. "npm@22.11.0"). One failing package is reported and
+     * skipped; it is tried again next boot.
+     */
+    async installOnce(env, group, packages, install) {
+        const todo = packages.filter((p) => !this.has(group, p));
+        for (const pkg of todo) {
+            try {
+                log('Installing ' + pkg + ' (' + group + ') ...');
+                await install(pkg);
+                this.mark(group, pkg);
+            }
+            catch (e) {
+                warn(pkg +
+                    ' (' +
+                    group +
+                    ') could not be installed and is skipped; the next start tries again. Reason: ' +
+                    errMsg(e));
+            }
+        }
+        const ok = packages.filter((p) => this.has(group, p));
+        if (ok.length)
+            env.summary.push(group.split('@')[0] + ' packages: ' + ok.join(', '));
+    }
+    read() {
+        return readState(this.file(), LedgerSchema, {});
+    }
+}
+export const packageLedger = new PackageLedger();
+/** packageLedger.installOnce: installs the packages of `group` that are not installed yet. */
+export function installOnce(env, group, packages, install) {
+    return packageLedger.installOnce(env, group, packages, install);
+}

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

@@ -1,24 +1,3 @@
-import type { Config, DatabasePlan, GitAccess, Toolchains, ToolVersions } from '../../core/types.js';
-import { type ToolEnv } from './common.js';
-/** apps: the boot only (apps are machine-wide; a project that joins later shares them). */
-export interface ToolchainOptions {
-    gitEnabled: boolean;
-    gitAccess: GitAccess;
-    hostGit: boolean;
-    refresh: boolean;
-    databases: DatabasePlan[];
-    apps?: Config['apps'];
-}
-/**
- * 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[];
+import type { Toolchains, ToolVersions } from '../../core/types.js';
+import type { ToolchainOptions, ToolchainStep } from './step.js';
+export declare function plan(config: Toolchains, versions: ToolVersions, o: ToolchainOptions): ToolchainStep[];