windows-development-sandbox 1.17.3 → 1.18.0

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

@@ -1,163 +1,26 @@
-// Unreal Engine development (toolchains.unreal): Visual Studio Community 2022 with the C++ game workload and the parts
-// Unreal's build tool looks for (it finds Visual Studio through the Setup API, so the portable MSVC does not do), and
-// the DirectX End-User Runtime. Real installers: they run every boot. The installers are kept in tools\ and run only
-// when Microsoft's signature on them checks out; with keepInstallFiles an offline copy of the install files
-// (tools\visualstudio\layout) spares later boots the download. The engine itself comes from the Epic Games Launcher.
-import fs from 'node:fs';
+// Unreal Engine development (toolchains.unreal): the DirectX End-User Runtime the engine lists (a real installer: it
+// runs every boot), then the engines (engines/unreal-engines.ts: the launcher's install folder on the data disk, PC
+// engines from pcInstalls, the derived data cache). Visual Studio Community with the C++ game workload is its own step
+// (visual-studio.ts), which the plan runs first. The engine itself comes from the Epic Games Launcher or its source.
 import os from 'node:os';
 import path from 'node:path';
-import { z } from 'zod';
 import { spawnAsync } from '../../../shared/download/index.js';
-import { writeJsonAtomic } from '../../../shared/io/json.js';
 import { safeRemove } from '../../../shared/io/safe-remove.js';
 import { dryRun } from '../../runtime/paths.js';
-import { execOutput } from '../../runtime/process.js';
 import { exists, mkdirp } from '../../runtime/fs.js';
-import { log, warn } from '../../runtime/log.js';
-import { errMsg } from '../../../core/util/errors.js';
-import { downloadFile } from '../install.js';
+import { log } from '../../runtime/log.js';
+import { setupUnrealEngines } from '../engines/unreal-engines.js';
+import { SIGNERS, signedInstaller } from '../installers.js';
 import { tool } from '../tool-env.js';
-import { MICROSOFT_SIGNER, signerOf } from './vcruntime.js';
-const BOOTSTRAPPER_URL = 'https://aka.ms/vs/17/release/vs_community.exe';
+import { installedVs } from './visual-studio.js';
+export { UNREAL_COMPONENTS } from './vs-request.js';
 const DIRECTX_URL = 'https://download.microsoft.com/download/8/4/A/84A35BF1-DAFE-4AE8-82AF-AD2AE20B6B14/directx_Jun2010_redist.exe';
-/**
- * What Epic lists for Unreal Engine 5 with Visual Studio 2022: the game workload, MSVC v143, a Windows SDK of
- * 10.0.18362 or newer, the C++ profiling tools, the .NET Framework targeting packs some engine tools build against,
- * Visual Studio's Unreal support and the Unreal Engine installer (the Epic Games Launcher).
- */
-export const UNREAL_COMPONENTS = [
-    'Microsoft.VisualStudio.Workload.NativeGame',
-    'Microsoft.VisualStudio.Component.VC.Tools.x86.x64',
-    'Microsoft.VisualStudio.Component.Windows11SDK.22621',
-    'Microsoft.VisualStudio.Component.VC.DiagnosticTools',
-    'Microsoft.Net.Component.4.6.2.TargetingPack',
-    'Microsoft.Net.Component.4.8.SDK',
-    'Component.Unreal.Ide',
-    'Component.Unreal',
-];
-/** Visual Studio installer exit codes that mean installed: 0, and 3010 (a restart would finish it, not needed here). */
-const OK_EXIT_CODES = [0, 3010];
-/** Free room the offline copy needs before it is made (it grows to about 10 GB). */
-const LAYOUT_ROOM_BYTES = 15 * 1024 ** 3;
-/**
- * Free room on the sandbox's own disk before Visual Studio goes on it: it takes about 7 GB, and the disk (about 40 GB)
- * also holds the paging file and every build, so it is installed only when about 13 GB stay free after it.
- */
-const INSTALL_ROOM_BYTES = 20 * 1024 ** 3;
-const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
-const VS_DIR = tool('visualstudio');
-const BOOTSTRAPPER = path.join(VS_DIR, 'vs_community.exe');
-const LAYOUT = path.join(VS_DIR, 'layout');
-const LAYOUT_MARKER = path.join(LAYOUT, '.complete.json');
-const LayoutSchema = z.object({ components: z.array(z.string()) });
-const VSWHERE = path.join(process.env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)', 'Microsoft Visual Studio', 'Installer', 'vswhere.exe');
-/** The newest Visual Studio with the C++ compiler: its folder and version, or null. */
-function installedVs() {
-    if (!exists(VSWHERE))
-        return null;
-    const ask = (property) => execOutput(VSWHERE, [
-        '-latest',
-        '-products',
-        '*',
-        '-requires',
-        'Microsoft.VisualStudio.Component.VC.Tools.x86.x64',
-        '-property',
-        property,
-    ]);
-    const at = ask('installationPath');
-    return at ? { path: at, version: ask('installationVersion') || 'installed' } : null;
-}
-/** A Microsoft-signed installer kept in tools\ (downloaded once); a file with a bad signature is deleted. */
-async function signedInstaller(url, file, what) {
-    if (!exists(file)) {
-        log('Downloading ' + what + ' ...');
-        mkdirp(path.dirname(file));
-        await downloadFile(url, file);
-    }
-    if (signerOf(file) !== MICROSOFT_SIGNER) {
-        fs.rmSync(file, { force: true });
-        throw new Error(path.basename(file) + ' is not signed by Microsoft; deleted it (it is downloaded again next boot)');
-    }
-    return file;
-}
-function freeBytes(dir) {
-    try {
-        const s = fs.statfsSync(dir);
-        return s.bavail * s.bsize;
-    }
-    catch {
-        return 0;
-    }
-}
-/** The offline copy's installer when it holds every component; made or completed when there is room. */
-async function layoutInstaller(bootstrapper, ids) {
-    const installer = path.join(LAYOUT, 'vs_community.exe');
-    const has = () => {
-        if (!exists(LAYOUT_MARKER) || !exists(installer))
-            return false;
-        try {
-            const done = LayoutSchema.parse(JSON.parse(fs.readFileSync(LAYOUT_MARKER, 'utf8')));
-            return ids.every((id) => done.components.includes(id));
-        }
-        catch {
-            return false;
-        }
-    };
-    if (has())
-        return installer;
-    if (freeBytes(mkdirp(VS_DIR)) < LAYOUT_ROOM_BYTES) {
-        warn('unreal: not keeping the install files (less than 15 GB free in ' + VS_DIR + '); downloading this boot');
-        return null;
-    }
-    log('Saving the Visual Studio install files for later boots (~10 GB, once) ...');
-    fs.rmSync(LAYOUT_MARKER, { force: true });
-    const code = await spawnAsync(bootstrapper, [
-        '--layout',
-        LAYOUT,
-        '--lang',
-        'en-US',
-        '--quiet',
-        '--wait',
-        ...ids.flatMap((id) => ['--add', id]),
-    ]);
-    if (!OK_EXIT_CODES.includes(code) || !exists(installer)) {
-        warn('unreal: saving the install files failed (exit ' + code + '); downloading this boot');
-        return null;
-    }
-    writeJsonAtomic(LAYOUT_MARKER, { components: [...ids] });
-    return installer;
-}
-async function installVisualStudio(config, ids) {
-    const bootstrapper = await signedInstaller(BOOTSTRAPPER_URL, BOOTSTRAPPER, 'the Visual Studio installer');
-    let installer = null;
-    if (config.keepInstallFiles) {
-        try {
-            installer = await layoutInstaller(bootstrapper, ids);
-        }
-        catch (e) {
-            warn('unreal: the offline copy failed (' + errMsg(e) + '); downloading this boot');
-        }
-    }
-    log('Installing Visual Studio Community 2022 with the C++ game workload' +
-        (installer ? ' from the saved install files' : ' (downloads ~5-8 GB)') +
-        ' ...');
-    const code = await spawnAsync(installer ?? bootstrapper, [
-        '--quiet',
-        '--wait',
-        '--norestart',
-        '--nocache',
-        ...(installer ? ['--noWeb'] : []),
-        ...ids.flatMap((id) => ['--add', id]),
-    ]);
-    if (!OK_EXIT_CODES.includes(code) || !installedVs())
-        throw new Error('the Visual Studio installer failed (exit ' + code + '); its logs are the dd_*.log files in ' + os.tmpdir());
-}
 /** The June 2010 DirectX End-User Runtime (D3DX, XAudio 2.7, XInput 1.3), which Epic lists for the engine. */
 async function installDirectX() {
     const system32 = path.join(process.env.WINDIR ?? 'C:\\Windows', 'System32');
     if (exists(path.join(system32, 'd3dx9_43.dll')) && exists(path.join(system32, 'XAudio2_7.dll')))
         return;
-    const redist = await signedInstaller(DIRECTX_URL, path.join(VS_DIR, 'directx_Jun2010_redist.exe'), 'the DirectX End-User Runtime (~95 MB once)');
+    const redist = await signedInstaller(DIRECTX_URL, path.join(tool('visualstudio'), 'directx_Jun2010_redist.exe'), 'the DirectX End-User Runtime (~95 MB once)', SIGNERS.microsoft);
     const unpacked = path.join(os.tmpdir(), 'directx-redist');
     safeRemove(unpacked, os.tmpdir());
     mkdirp(unpacked);
@@ -168,31 +31,17 @@ async function installDirectX() {
     if (code !== 0)
         throw new Error('the DirectX End-User Runtime installer failed (exit ' + code + ')');
 }
-export async function setupUnreal(env, config) {
+export async function setupUnreal(env, config, ctx) {
     if (!config.acceptLicense)
         throw new Error('Unreal tools are installed only with toolchains.unreal.acceptLicense = true: Visual Studio Community and the DirectX End-User Runtime come under Microsoft licence terms (https://visualstudio.microsoft.com/license-terms/)');
-    const bad = config.components.find((id) => !ID.test(id));
-    if (bad)
-        throw new Error('toolchains.unreal.components: "' + bad + '" is not a Visual Studio component ID');
-    const ids = [...new Set([...UNREAL_COMPONENTS, ...config.components])];
     if (dryRun) {
-        log('(dry run) would install Visual Studio Community 2022 with ' + ids.join(', ') + ' and DirectX');
+        log('(dry run) would install the DirectX End-User Runtime and set up the Unreal engines');
         return;
     }
-    if (!installedVs()) {
-        const programFiles = process.env.ProgramFiles ?? 'C:\\Program Files';
-        const free = freeBytes(programFiles);
-        if (free < INSTALL_ROOM_BYTES)
-            throw new Error('not installing Visual Studio: the sandbox disk has ' +
-                (free / 1024 ** 3).toFixed(1) +
-                ' GB free and it needs 20 GB (7 GB for Visual Studio, the rest for builds and the paging file)');
-        await installVisualStudio(config, ids);
-    }
     await installDirectX();
+    await setupUnrealEngines(env, config, ctx);
     const vs = installedVs();
-    env.summary.push('unreal: Visual Studio Community ' +
-        vs.version +
-        ' (C++ game workload, Windows 11 SDK, Unreal support) at ' +
-        vs.path +
-        '; DirectX End-User Runtime; get the engine from the Epic Games Launcher (Start menu)');
+    env.summary.push('unreal: ' +
+        (vs ? 'Visual Studio ' + vs.version + ' (C++ game workload, Windows 11 SDK, Unreal support); ' : '') +
+        'DirectX End-User Runtime; get the engine from the Epic Games Launcher (Start menu)');
 }

package/dist/guest/toolchains/native/visual-studio.d.ts

@@ -0,0 +1,15 @@
+import { type ToolEnv } from '../tool-env.js';
+import type { VsRequest } from './vs-request.js';
+export { BUILD_TOOLS_COMPONENTS, UNREAL_COMPONENTS, visualStudioWanted, type VsRequest } from './vs-request.js';
+/** The newest Visual Studio (or Build Tools) with the C++ compiler: its folder and version, or null. */
+export declare function installedVs(): {
+    path: string;
+    version: string;
+} | null;
+/** Visual Studio as asked for: installed at boot when it is not there yet; its folder and version. */
+export declare function ensureVisualStudio(env: ToolEnv, req: VsRequest, o: {
+    keepInstallFiles: boolean;
+}): Promise<{
+    path: string;
+    version: string;
+}>;

package/dist/guest/toolchains/native/visual-studio.js

@@ -0,0 +1,159 @@
+// Visual Studio for the toolchains that need the real one (vs-request.ts says which): Community with the C++ game
+// workload for Unreal (its build tool finds Visual Studio through the Setup API, so the portable MSVC does not do), or
+// the Build Tools' C++ parts for Flutter desktop and Unity IL2CPP. A real installer: it runs every boot, on the
+// sandbox's own disk, and never while sessions run (they would need a restart). The bootstrapper is kept in tools\
+// and run only when Microsoft's signature checks out; with keepInstallFiles an offline copy of the install files
+// (tools\visualstudio\layout) spares later boots the download.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { z } from 'zod';
+import { spawnAsync } from '../../../shared/download/index.js';
+import { writeJsonAtomic } from '../../../shared/io/json.js';
+import { execOutput } from '../../runtime/process.js';
+import { exists, mkdirp } from '../../runtime/fs.js';
+import { log, warn } from '../../runtime/log.js';
+import { duringSession } from '../../runtime/project-context.js';
+import { errMsg } from '../../../core/util/errors.js';
+import { SIGNERS, signedInstaller } from '../installers.js';
+import { assertLocalRoom, freeBytes } from '../persisted.js';
+import { tool } from '../tool-env.js';
+export { BUILD_TOOLS_COMPONENTS, UNREAL_COMPONENTS, visualStudioWanted } from './vs-request.js';
+const BOOTSTRAPPERS = {
+    community: {
+        url: 'https://aka.ms/vs/17/release/vs_community.exe',
+        file: 'vs_community.exe',
+        name: 'Visual Studio Community 2022',
+    },
+    buildtools: {
+        url: 'https://aka.ms/vs/17/release/vs_buildtools.exe',
+        file: 'vs_buildtools.exe',
+        name: 'Visual Studio Build Tools 2022',
+    },
+};
+/** What each takes on the sandbox's own disk (13 GB more must stay free: assertLocalRoom). */
+const INSTALL_BYTES = {
+    community: 7 * 1024 ** 3,
+    buildtools: 5 * 1024 ** 3,
+};
+/** Visual Studio installer exit codes that mean installed: 0, and 3010 (a restart would finish it, not needed here). */
+const OK_EXIT_CODES = [0, 3010];
+/** Free room the offline copy needs before it is made (it grows to about 10 GB). */
+const LAYOUT_ROOM_BYTES = 15 * 1024 ** 3;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
+const VS_DIR = tool('visualstudio');
+const LayoutSchema = z.object({ components: z.array(z.string()) });
+const VSWHERE = path.join(process.env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)', 'Microsoft Visual Studio', 'Installer', 'vswhere.exe');
+/** The newest Visual Studio (or Build Tools) with the C++ compiler: its folder and version, or null. */
+export function installedVs() {
+    if (!exists(VSWHERE))
+        return null;
+    const ask = (property) => execOutput(VSWHERE, [
+        '-latest',
+        '-products',
+        '*',
+        '-requires',
+        'Microsoft.VisualStudio.Component.VC.Tools.x86.x64',
+        '-property',
+        property,
+    ]);
+    const at = ask('installationPath');
+    return at ? { path: at, version: ask('installationVersion') || 'installed' } : null;
+}
+function layoutDir(product) {
+    return path.join(VS_DIR, product === 'community' ? 'layout' : 'layout-buildtools');
+}
+/** The offline copy's installer when it holds every component; made or completed when there is room. */
+async function layoutInstaller(req, bootstrapper) {
+    const layout = layoutDir(req.product);
+    const marker = path.join(layout, '.complete.json');
+    const installer = path.join(layout, BOOTSTRAPPERS[req.product].file);
+    const has = () => {
+        if (!exists(marker) || !exists(installer))
+            return false;
+        try {
+            const done = LayoutSchema.parse(JSON.parse(fs.readFileSync(marker, 'utf8')));
+            return req.components.every((id) => done.components.includes(id));
+        }
+        catch {
+            return false;
+        }
+    };
+    if (has())
+        return installer;
+    if (freeBytes(mkdirp(VS_DIR)) < LAYOUT_ROOM_BYTES) {
+        warn('Visual Studio: not keeping the install files (less than 15 GB free in ' + VS_DIR + '); downloading this boot');
+        return null;
+    }
+    log('Saving the Visual Studio install files for later boots (~10 GB, once) ...');
+    fs.rmSync(marker, { force: true });
+    const code = await spawnAsync(bootstrapper, [
+        '--layout',
+        layout,
+        '--lang',
+        'en-US',
+        '--quiet',
+        '--wait',
+        ...req.components.flatMap((id) => ['--add', id]),
+    ]);
+    if (!OK_EXIT_CODES.includes(code) || !exists(installer)) {
+        warn('Visual Studio: saving the install files failed (exit ' + code + '); downloading this boot');
+        return null;
+    }
+    writeJsonAtomic(marker, { components: [...req.components] });
+    return installer;
+}
+async function install(req, keepInstallFiles) {
+    const boot = BOOTSTRAPPERS[req.product];
+    const bootstrapper = await signedInstaller(boot.url, path.join(VS_DIR, boot.file), 'the ' + boot.name + ' installer', SIGNERS.microsoft);
+    let installer = null;
+    if (keepInstallFiles) {
+        try {
+            installer = await layoutInstaller(req, bootstrapper);
+        }
+        catch (e) {
+            warn('Visual Studio: the offline copy failed (' + errMsg(e) + '); downloading this boot');
+        }
+    }
+    log('Installing ' + boot.name + (installer ? ' from the saved install files' : ' (downloads ~5-8 GB)') + ' ...');
+    const code = await spawnAsync(installer ?? bootstrapper, [
+        '--quiet',
+        '--wait',
+        '--norestart',
+        '--nocache',
+        ...(installer ? ['--noWeb'] : []),
+        ...req.components.flatMap((id) => ['--add', id]),
+    ]);
+    if (!OK_EXIT_CODES.includes(code) || !installedVs())
+        throw new Error('the Visual Studio installer failed (exit ' + code + '); its logs are the dd_*.log files in ' + os.tmpdir());
+}
+/** Visual Studio as asked for: installed at boot when it is not there yet; its folder and version. */
+export async function ensureVisualStudio(env, req, o) {
+    if (!req.accepted)
+        throw new Error('Visual Studio (for ' +
+            req.for.join(', ') +
+            ') is installed only with ' +
+            req.licence +
+            ' = true: it comes under Microsoft licence terms (https://visualstudio.microsoft.com/license-terms/)');
+    const bad = req.components.find((id) => !ID.test(id));
+    if (bad)
+        throw new Error('"' + bad + '" is not a Visual Studio component ID');
+    const have = installedVs();
+    if (have)
+        return have;
+    if (duringSession())
+        throw new Error('Visual Studio is installed when the sandbox starts: restart it (sandbox restart) to get it');
+    assertLocalRoom(INSTALL_BYTES[req.product], BOOTSTRAPPERS[req.product].name);
+    await install(req, o.keepInstallFiles);
+    const vs = installedVs();
+    env.summary.push('visual studio: ' +
+        BOOTSTRAPPERS[req.product].name +
+        ' ' +
+        vs.version +
+        ' at ' +
+        vs.path +
+        ' (for ' +
+        req.for.join(', ') +
+        ')');
+    return vs;
+}

package/dist/guest/toolchains/native/vs-request.d.ts

@@ -0,0 +1,19 @@
+import type { Toolchains } from '../../../core/types.js';
+/**
+ * What Epic lists for Unreal Engine 5 with Visual Studio 2022: the game workload, MSVC v143, a Windows SDK of
+ * 10.0.18362 or newer, the C++ profiling tools, the .NET Framework targeting packs some engine tools build against,
+ * Visual Studio's Unreal support and the Unreal Engine installer (the Epic Games Launcher).
+ */
+export declare const UNREAL_COMPONENTS: readonly ["Microsoft.VisualStudio.Workload.NativeGame", "Microsoft.VisualStudio.Component.VC.Tools.x86.x64", "Microsoft.VisualStudio.Component.Windows11SDK.22621", "Microsoft.VisualStudio.Component.VC.DiagnosticTools", "Microsoft.Net.Component.4.6.2.TargetingPack", "Microsoft.Net.Component.4.8.SDK", "Component.Unreal.Ide", "Component.Unreal"];
+/** The Build Tools' C++ desktop parts: MSVC v143 and a Windows 11 SDK (Flutter desktop, Unity IL2CPP). */
+export declare const BUILD_TOOLS_COMPONENTS: readonly ["Microsoft.VisualStudio.Workload.VCTools", "Microsoft.VisualStudio.Component.VC.Tools.x86.x64", "Microsoft.VisualStudio.Component.Windows11SDK.22621"];
+export interface VsRequest {
+    readonly product: 'community' | 'buildtools';
+    readonly components: readonly string[];
+    /** Who asks for it (for messages): unreal, flutter, unity. */
+    readonly for: readonly string[];
+    /** The licence setting that must be on (toolchains.unreal.acceptLicense or toolchains.msvc.acceptLicense). */
+    readonly licence: string;
+    readonly accepted: boolean;
+}
+export declare function visualStudioWanted(t: Toolchains, on?: (setting: boolean | 'auto', name: string) => boolean): VsRequest | null;

package/dist/guest/toolchains/native/vs-request.js

@@ -0,0 +1,46 @@
+/**
+ * What Epic lists for Unreal Engine 5 with Visual Studio 2022: the game workload, MSVC v143, a Windows SDK of
+ * 10.0.18362 or newer, the C++ profiling tools, the .NET Framework targeting packs some engine tools build against,
+ * Visual Studio's Unreal support and the Unreal Engine installer (the Epic Games Launcher).
+ */
+export const UNREAL_COMPONENTS = [
+    'Microsoft.VisualStudio.Workload.NativeGame',
+    'Microsoft.VisualStudio.Component.VC.Tools.x86.x64',
+    'Microsoft.VisualStudio.Component.Windows11SDK.22621',
+    'Microsoft.VisualStudio.Component.VC.DiagnosticTools',
+    'Microsoft.Net.Component.4.6.2.TargetingPack',
+    'Microsoft.Net.Component.4.8.SDK',
+    'Component.Unreal.Ide',
+    'Component.Unreal',
+];
+/** The Build Tools' C++ desktop parts: MSVC v143 and a Windows 11 SDK (Flutter desktop, Unity IL2CPP). */
+export const BUILD_TOOLS_COMPONENTS = [
+    'Microsoft.VisualStudio.Workload.VCTools',
+    'Microsoft.VisualStudio.Component.VC.Tools.x86.x64',
+    'Microsoft.VisualStudio.Component.Windows11SDK.22621',
+];
+/** Whether a toolchain is on (the host resolved "auto"; a session file that still says "auto" counts as off). */
+const isOn = (setting) => setting === true;
+export function visualStudioWanted(t, on = isOn) {
+    const unreal = on(t.unreal.enabled, 'unreal');
+    const flutter = on(t.flutter.enabled, 'flutter') && t.flutter.windowsDesktop;
+    const unity = on(t.unity.enabled, 'unity') && t.unity.modules.includes('windows-il2cpp');
+    const users = [...(unreal ? ['unreal'] : []), ...(flutter ? ['flutter'] : []), ...(unity ? ['unity'] : [])];
+    if (!users.length)
+        return null;
+    if (unreal)
+        return {
+            product: 'community',
+            components: [...new Set([...UNREAL_COMPONENTS, ...t.unreal.components])],
+            for: users,
+            licence: 'toolchains.unreal.acceptLicense',
+            accepted: t.unreal.acceptLicense,
+        };
+    return {
+        product: 'buildtools',
+        components: [...BUILD_TOOLS_COMPONENTS],
+        for: users,
+        licence: 'toolchains.msvc.acceptLicense',
+        accepted: t.msvc.acceptLicense,
+    };
+}

package/dist/guest/toolchains/not-yet.d.ts

@@ -0,0 +1,2 @@
+import type { ToolEnv } from './tool-env.js';
+export declare function notAvailableYet(env: ToolEnv, what: string): void;

package/dist/guest/toolchains/not-yet.js

@@ -0,0 +1,6 @@
+// What a toolchain step whose module is not written yet does: says so in the log and the summary, installs nothing.
+import { log } from '../runtime/log.js';
+export function notAvailableYet(env, what) {
+    log(what + ': not available yet (nothing installed)');
+    env.summary.push(what + ': not available yet');
+}

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

@@ -0,0 +1,48 @@
+import { type InstallRecord } from '../../shared/installs.js';
+/** What stays free on the sandbox's own disk after a real installer: the paging file and every build need it. */
+export declare const LOCAL_RESERVE_BYTES: number;
+export interface InstallSpec {
+    /** The tools\ folder of the tool: unity, godot, fivem\artifacts ... (letters, digits, . _ - and one /). */
+    readonly name: string;
+    readonly version: string;
+    /** Room it needs while installing (download, unpacked copy). */
+    readonly needBytes: number;
+    /** A file (relative to the version folder) that only a finished install has: Editor\Unity.exe. */
+    readonly marker: string;
+    /** What it is, for messages: "Unity 6000.0.32f1". */
+    readonly what: string;
+    /** How many versions of this tool to keep (default: all). */
+    readonly keepVersions?: number;
+}
+export interface Installed {
+    readonly dir: string;
+    /** Installed now (false: it was there). */
+    readonly fresh: boolean;
+    readonly sizeBytes: number | null;
+}
+export { InstallRecordsSchema, type InstallRecord } from '../../shared/installs.js';
+export interface PersistedDeps {
+    /** C:\AgentData\tools (the self-test passes its own folder). */
+    readonly toolsDir?: string;
+    /** The sandbox's own disk, for real installers. */
+    readonly localDir?: string;
+    readonly statfs?: (dir: string) => {
+        bavail: number;
+        bsize: number;
+    };
+    readonly log?: (line: string) => void;
+}
+/** Free bytes for this user on the disk holding `dir` (0 when it cannot be told). */
+export declare function freeBytes(dir: string, deps?: PersistedDeps): number;
+/** Throws (with the fix) when the disk holding `dir` has less than `needBytes` free. */
+export declare function assertRoom(dir: string, needBytes: number, what: string, fix: string, deps?: PersistedDeps): void;
+/** A real installer on the sandbox's own disk (C:): its size plus 13 GB must stay free (paging file, builds). */
+export declare function assertLocalRoom(needBytes: number, what: string, deps?: PersistedDeps): void;
+export declare function installRecords(deps?: PersistedDeps): readonly InstallRecord[];
+/** Notes that a version was used now (it is kept over ones used longer ago). */
+export declare function recordUse(name: string, version: string, deps?: PersistedDeps): void;
+/**
+ * The version's folder, installed by `install(staging, temp)` when it is not there yet. The installer puts the
+ * version's files in `staging` and its temporary files in `temp` (inside staging); a failed install leaves nothing.
+ */
+export declare function ensurePersisted(spec: InstallSpec, install: (staging: string, temp: string) => Promise<void>, deps?: PersistedDeps): Promise<Installed>;