windows-development-sandbox 1.23.2 → 1.25.0

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

@@ -1,31 +1,28 @@
 // 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.
+// the Build Tools' C++ parts. Installed once with Microsoft's installer (the bootstrapper is kept in tools\ and run
+// only when Microsoft's signature checks out), then saved on the data disk (tools\visualstudio\persist, vs-persist.ts
+// says what goes where). Later boots put the saved copy back in seconds: no download, no install, nothing big on C:.
+// Never installed while sessions run (they would need a restart); putting a saved copy back only adds to the machine.
 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 { heavy, runInstaller } from '../../runtime/pools.js';
-import { writeJsonAtomic } from '../../../shared/io/json.js';
-import { robocopyFailed } from '../../../shared/io/robocopy-result.js';
+import { readValid, writeJsonAtomic } from '../../../shared/io/json.js';
 import { safeRemove } from '../../../shared/io/safe-remove.js';
-import { SYSTEM } from '../../../shared/system.js';
-import { execOutput } from '../../runtime/process.js';
+import { execOutput, runScriptWithJsonAsync } from '../../runtime/process.js';
 import { exists, mkdirp } from '../../runtime/fs.js';
 import { log, warn } from '../../runtime/log.js';
-import { logsDir } from '../../runtime/paths.js';
 import { duringSession } from '../../runtime/project-context.js';
 import { backgroundRunning } from '../../runtime/status.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';
-import { LAYOUT_STAGING_BYTES, layoutNextStep, STAGING_RESERVE_BYTES, vsExitText, } from './vs-request.js';
-export { BUILD_TOOLS_COMPONENTS, UNREAL_COMPONENTS, unrealUsesAutosdk, visualStudioWanted, } from './vs-request.js';
+import { vsExitText } from './vs-request.js';
+import { MARKER_FILE, markerFrom, newestInstance, persistCovers, productFolder, restoreInput, rewriteInstanceState, SaveResultSchema, saveInput, VsPersistMarkerSchema, winPlaces, } from './vs-persist.js';
+export { BUILD_TOOLS_COMPONENTS, UNREAL_BUILD_TOOLS_COMPONENTS, UNREAL_COMPONENTS, visualStudioWanted, } from './vs-request.js';
 const BOOTSTRAPPERS = {
     community: {
         url: 'https://aka.ms/vs/17/release/vs_community.exe',
@@ -38,187 +35,140 @@ const BOOTSTRAPPERS = {
         name: 'Visual Studio Build Tools 2022',
     },
 };
-/** What each takes on the sandbox's own disk (13 GB more must stay free: assertLocalRoom). */
+const GB = 1024 ** 3;
+/** What each takes on the sandbox's own disk while it is installed (13 GB more must stay free: assertLocalRoom). */
 const INSTALL_BYTES = {
-    community: 7 * 1024 ** 3,
-    buildtools: 5 * 1024 ** 3,
+    community: 7 * GB,
+    buildtools: 5 * GB,
 };
+/** Free room on the data disk the saved copy needs (Community with the Windows SDK is about 6.5 GB). */
+const SAVE_ROOM_BYTES = 8 * GB;
 /** 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. */
+const PERSIST_DIR = path.join(VS_DIR, 'persist');
+const MARKER = path.join(PERSIST_DIR, MARKER_FILE);
+/** What older versions left in tools\visualstudio: the offline install files, which the installer never finished. */
+const LEFTOVERS = ['layout', 'layout-buildtools', 'tmp'];
+const PLACES = winPlaces(process.env);
+const INSTALLER_DIR = path.join(PLACES.programFilesX86, 'Microsoft Visual Studio', 'Installer');
+const VSWHERE = path.join(INSTALLER_DIR, 'vswhere.exe');
+const VswhereSchema = z.array(z.looseObject({
+    instanceId: z.string(),
+    installationPath: z.string(),
+    installationVersion: z.string().optional(),
+}));
+/** The newest Visual Studio (or Build Tools) with the C++ compiler, installed or put back: where it is, or null. */
 export function installedVs() {
     if (!exists(VSWHERE))
         return null;
-    const ask = (property) => execOutput(VSWHERE, [
-        '-latest',
+    const out = execOutput(VSWHERE, [
         '-products',
         '*',
         '-requires',
         'Microsoft.VisualStudio.Component.VC.Tools.x86.x64',
-        '-property',
-        property,
+        '-format',
+        'json',
+        '-utf8',
     ]);
-    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 layout arguments of the bootstrapper (the same for the data disk and the staging folder). */
-const layoutArgs = (req, folder) => [
-    '--layout',
-    folder,
-    '--lang',
-    'en-US',
-    '--quiet',
-    '--wait',
-    ...req.components.flatMap((id) => ['--add', id]),
-];
-/** The bootstrapper's newest log (dd_bootstrapper_*.log) in these folders, or null. */
-function newestBootstrapperLog(folders) {
-    const logs = folders.flatMap((dir) => {
-        try {
-            return fs
-                .readdirSync(dir)
-                .filter((n) => /^dd_bootstrapper_.*\.log$/i.test(n))
-                .map((n) => path.join(dir, n));
-        }
-        catch {
-            return []; // The folder is not there: no log in it.
-        }
-    });
-    const stamp = (f) => {
-        try {
-            return fs.statSync(f).mtimeMs;
-        }
-        catch {
-            return 0; // Gone since the listing.
-        }
-    };
-    return logs.sort((x, y) => stamp(y) - stamp(x))[0] ?? null;
-}
-/** Says why the layout failed and keeps the installer's log where the sandbox's logs are. */
-function reportLayoutFailure(code, temps) {
-    warn('Visual Studio: saving the install files failed (exit ' + code + '): ' + vsExitText(code));
-    const found = newestBootstrapperLog(temps);
-    if (!found)
-        return;
-    const kept = path.join(logsDir, 'vs-layout-' + new Date().toISOString().slice(0, 10) + '.log');
+    let found;
     try {
-        fs.mkdirSync(logsDir, { recursive: true });
-        fs.copyFileSync(found, kept);
-        warn('Visual Studio: the installer log is ' + found + ' (a copy is in ' + kept + ')');
+        found = JSON.parse(out || '[]');
     }
-    catch (e) {
-        warn('Visual Studio: the installer log is ' + found + ' (could not copy it: ' + errMsg(e) + ')');
+    catch {
+        return null; // vswhere printed something else (it failed): no Visual Studio to use.
     }
+    const first = newestInstance(VswhereSchema.safeParse(found).data ?? []);
+    return first
+        ? { path: first.installationPath, version: first.installationVersion ?? 'installed', instanceId: first.instanceId }
+        : null;
 }
-/** Copies a finished layout onto the data disk (never /MOV: mapped folders refuse rename-over). */
-async function copyLayout(from, to) {
-    mkdirp(to);
-    const code = await heavy.run(() => spawnAsync(SYSTEM.robocopy(), [from, to, '/E', '/COPY:DAT', '/R:1', '/W:1', '/MT:8', '/NP']));
-    return !robocopyFailed(code);
-}
-/** The offline copy's installer when it holds every component; made or completed when there is room. */
-async function layoutInstaller(req, bootstrapper, lowPriority) {
-    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;
-        }
-    };
-    const finish = () => {
-        writeJsonAtomic(marker, { components: [...req.components] });
-        return installer;
-    };
-    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');
+/** The saved copy when it is complete and serves this request, else null. */
+function savedCopy(req) {
+    const marker = readValid(VsPersistMarkerSchema, MARKER);
+    if (!marker || !persistCovers(marker, req))
         return null;
+    const product = path.join(PERSIST_DIR, productFolder(marker.product));
+    const files = [
+        path.join(product, 'VC', 'Auxiliary', 'Build', 'vcvars64.bat'),
+        path.join(PERSIST_DIR, 'instance', 'state.json'),
+        path.join(PERSIST_DIR, 'Installer', 'vswhere.exe'),
+        path.join(PERSIST_DIR, 'Setup', 'x64', 'Microsoft.VisualStudio.Setup.Configuration.Native.dll'),
+    ];
+    return files.every(exists) ? marker : null;
+}
+/** Whether a later boot only puts Visual Studio back (quick enough to wait for) instead of installing it. */
+export function visualStudioSaved(req) {
+    return savedCopy(req) !== null;
+}
+/** Puts the saved copy back: its fixed-path folders, the instance, the registry; then vswhere must find it. */
+async function restoreSaved(marker) {
+    const started = Date.now();
+    log('Visual Studio: putting back the copy saved in ' + PERSIST_DIR + ' ...');
+    const plan = restoreInput(marker, PERSIST_DIR, PLACES);
+    await heavy.run(() => runScriptWithJsonAsync('restore-visual-studio.ps1', 'PlanFile', plan));
+    const vs = installedVs();
+    if (!vs)
+        throw new Error('vswhere does not find the Visual Studio that was put back');
+    log('Visual Studio ' + vs.version + ' is back in ' + Math.round((Date.now() - started) / 1000) + ' s (' + vs.path + ')');
+    return vs;
+}
+/**
+ * Saves a fresh install on the data disk for later boots (once). The marker goes last, after the instance's state is
+ * moved to the saved folder; a failure leaves no marker and only costs the next boot another install.
+ */
+async function saveInstall(req, vs, lowPriority) {
+    const free = freeBytes(mkdirp(PERSIST_DIR));
+    if (free < SAVE_ROOM_BYTES) {
+        warn('Visual Studio: not saved for later boots (' +
+            (free / GB).toFixed(1) +
+            ' GB free in ' +
+            PERSIST_DIR +
+            ', it needs 8 GB); the next boot installs it again');
+        return;
     }
-    log('Saving the Visual Studio install files for later boots (~10 GB, once) ...');
-    fs.rmSync(marker, { force: true });
-    // The installer crashes (0xE0434352) when it builds the layout in a mapped folder, so it is built on the sandbox's
-    // own disk and copied over. That runs before Visual Studio is installed and the copy on C: is deleted first, so it
-    // needs room for the layout only (STAGING_RESERVE_BYTES spare), not for the layout and the install together.
-    const drive = (process.env.SystemDrive ?? 'C:') + '\\';
-    if (layoutNextStep(null, freeBytes(drive), STAGING_RESERVE_BYTES) !== 'stage') {
-        warn('Visual Studio: less than ' +
-            Math.round((LAYOUT_STAGING_BYTES + STAGING_RESERVE_BYTES) / 1024 ** 3) +
-            ' GB free on ' +
-            drive +
-            ' to build the install files; downloading this boot');
-        return null;
+    fs.rmSync(MARKER, { force: true });
+    log('Saving Visual Studio in ' + PERSIST_DIR + ' for later boots (~6.5 GB, once) ...');
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sbx-vs-'));
+    const resultFile = path.join(dir, 'result.json');
+    try {
+        const plan = saveInput({ product: req.product, installationPath: vs.path, instanceId: vs.instanceId }, PERSIST_DIR, PLACES, resultFile);
+        await heavy.run(() => runScriptWithJsonAsync('save-visual-studio.ps1', 'PlanFile', plan, lowPriority ? ['-LowPriority'] : []));
+        const result = readValid(SaveResultSchema, resultFile);
+        if (!result)
+            throw new Error('the save script left no result');
+        const state = path.join(PERSIST_DIR, 'instance', 'state.json');
+        const saved = path.join(PERSIST_DIR, productFolder(req.product));
+        fs.writeFileSync(state, rewriteInstanceState(fs.readFileSync(state, 'utf8'), vs.path, saved), 'utf8');
+        // One product is kept: a Build Tools copy goes when Community replaces it (and the other way round).
+        safeRemove(path.join(PERSIST_DIR, productFolder(req.product === 'community' ? 'buildtools' : 'community')), VS_DIR);
+        writeJsonAtomic(MARKER, markerFrom(req, { installationPath: vs.path, instanceId: vs.instanceId, version: vs.version }, result, new Date().toISOString()));
+        log('Visual Studio is saved: later boots put it back in seconds');
     }
-    const staging = path.join(drive, 'vs-layout-staging');
-    log('Building the install files on ' + drive + ' and copying them to ' + layout + ' ...');
-    const stagedCode = await runInstaller(bootstrapper, layoutArgs(req, staging), { lowPriority });
-    const staged = path.join(staging, BOOTSTRAPPERS[req.product].file);
-    let kept = false;
-    if (OK_EXIT_CODES.includes(stagedCode) && exists(staged)) {
-        kept = await copyLayout(staging, layout);
-        if (!kept)
-            warn('Visual Studio: copying the install files to ' + layout + ' failed');
+    catch (e) {
+        warn('Visual Studio: saving it for later boots failed (' + errMsg(e) + '); the next boot installs it again');
     }
-    else {
-        reportLayoutFailure(stagedCode, [os.tmpdir()]);
+    finally {
+        fs.rmSync(dir, { recursive: true, force: true });
     }
-    safeRemove(staging, drive);
-    return kept && exists(installer) ? finish() : null;
 }
-/** The bootstrapper, downloaded (net pool) and checked; kept in tools\ for later boots. */
+/** The bootstrapper, downloaded (net pool) and checked; kept in tools\ for later installs. */
 function bootstrapperFor(req) {
     const boot = BOOTSTRAPPERS[req.product];
     return signedInstaller(boot.url, path.join(VS_DIR, boot.file), 'the ' + boot.name + ' installer', SIGNERS.microsoft);
 }
-/** Downloads the bootstrapper now, so the install later starts without waiting for it. */
+/** Downloads the bootstrapper now, so the install later starts without waiting (not needed with a saved copy). */
 export async function prefetchVisualStudio(req) {
-    if (!req.accepted || installedVs())
+    if (!req.accepted || installedVs() || savedCopy(req))
         return;
     await bootstrapperFor(req);
 }
-async function install(req, keepInstallFiles, lowPriority) {
+async function install(req, lowPriority) {
     const boot = BOOTSTRAPPERS[req.product];
     const bootstrapper = await bootstrapperFor(req);
-    let installer = null;
-    if (keepInstallFiles) {
-        try {
-            installer = await layoutInstaller(req, bootstrapper, lowPriority);
-        }
-        catch (e) {
-            warn('Visual Studio: the offline copy failed (' + errMsg(e) + '); downloading this boot');
-        }
-    }
-    const run = (from, offline) => runInstaller(from, [
-        '--quiet',
-        '--wait',
-        '--norestart',
-        '--nocache',
-        ...(offline ? ['--noWeb'] : []),
-        ...req.components.flatMap((id) => ['--add', id]),
-    ], { lowPriority });
-    log('Installing ' + boot.name + (installer ? ' from the saved install files' : ' (downloads ~5-8 GB)') + ' ...');
-    let code = await run(installer ?? bootstrapper, installer !== null);
-    if (installer && (!OK_EXIT_CODES.includes(code) || !installedVs())) {
-        // The saved copy is on the shared data disk: if installing from it fails, this boot downloads instead.
-        warn('Visual Studio: installing from the saved install files failed (' + vsExitText(code) + '); downloading');
-        code = await run(bootstrapper, false);
-    }
+    log('Installing ' + boot.name + ' (downloads ~5-8 GB, once: it is saved on the data disk afterwards) ...');
+    const code = await runInstaller(bootstrapper, ['--quiet', '--wait', '--norestart', '--nocache', ...req.components.flatMap((id) => ['--add', id])], { lowPriority });
     if (!OK_EXIT_CODES.includes(code) || !installedVs())
         throw new Error('the Visual Studio installer failed (exit ' +
             code +
@@ -227,8 +177,21 @@ async function install(req, keepInstallFiles, lowPriority) {
             '); 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) {
+/** Removes what older versions left in tools\visualstudio (best effort). */
+function removeLeftovers() {
+    for (const name of LEFTOVERS) {
+        const dir = path.join(VS_DIR, name);
+        try {
+            if (exists(dir))
+                safeRemove(dir, VS_DIR);
+        }
+        catch (e) {
+            warn('Visual Studio: could not remove ' + dir + ' (' + errMsg(e) + ')');
+        }
+    }
+}
+/** Visual Studio as asked for: put back from the data disk, or installed (and saved) the first time. */
+export async function ensureVisualStudio(env, req, o = {}) {
     if (!req.accepted)
         throw new Error('Visual Studio (for ' +
             req.for.join(', ') +
@@ -238,24 +201,32 @@ export async function ensureVisualStudio(env, req, o) {
     const bad = req.components.find((id) => !ID.test(id));
     if (bad)
         throw new Error('"' + bad + '" is not a Visual Studio component ID');
+    removeLeftovers();
+    const name = BOOTSTRAPPERS[req.product].name;
+    const done = (vs, how) => {
+        env.append.push(INSTALLER_DIR);
+        env.summary.push('visual studio: ' + name + ' ' + vs.version + ' at ' + vs.path + ' (' + how + '; for ' + req.for.join(', ') + ')');
+        return vs;
+    };
     const have = installedVs();
     if (have)
-        return have;
+        return done(have, 'installed');
+    const saved = savedCopy(req);
+    if (saved) {
+        try {
+            return done(await restoreSaved(saved), 'kept on the data disk');
+        }
+        catch (e) {
+            warn('Visual Studio: putting the saved copy back failed (' + errMsg(e) + '); installing it again');
+        }
+    }
     if (duringSession())
         throw new Error(backgroundRunning('Visual Studio')
             ? 'Visual Studio is still installing in the background; it is ready in a few minutes'
             : '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, o.lowPriority === true);
+    assertLocalRoom(INSTALL_BYTES[req.product], name);
+    await install(req, o.lowPriority === true);
     const vs = installedVs();
-    env.summary.push('visual studio: ' +
-        BOOTSTRAPPERS[req.product].name +
-        ' ' +
-        vs.version +
-        ' at ' +
-        vs.path +
-        ' (for ' +
-        req.for.join(', ') +
-        ')');
-    return vs;
+    await saveInstall(req, vs, o.lowPriority === true);
+    return done(vs, 'installed, saved for later boots');
 }

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

@@ -0,0 +1,189 @@
+import { z } from 'zod';
+import type { VsRequest } from './vs-request.js';
+/** The marker file in the saved copy's folder, written last. */
+export declare const MARKER_FILE = ".complete.json";
+/** The Setup Configuration COM class (vswhere and UnrealBuildTool find Visual Studio through it). */
+export declare const SETUP_CLSID = "{177F0C4A-1CD3-4DE7-A32C-71DBBB9FA36D}";
+/** The Windows folders an install uses (from the environment; the tests pass their own). */
+export interface WinPlaces {
+    readonly programFiles: string;
+    readonly programFilesX86: string;
+    readonly programData: string;
+}
+export declare function winPlaces(env: NodeJS.ProcessEnv): WinPlaces;
+export declare const FOLDER_NAMES: readonly ["Community", "BuildTools", "WindowsKits10", "NETFXSDK", "MicrosoftSDKs-v10.0A", "ReferenceAssemblies", "Installer", "Shared", "Setup", "instance"];
+export type FolderName = (typeof FOLDER_NAMES)[number];
+/**
+ * What a boot does with a saved folder: 'stay' on the data disk (registered there), 'copy' back to where it came from
+ * (programs look for it at a fixed path), or 'copy-missing': only the versions not there yet (the reference assemblies,
+ * where the .NET step may have put some).
+ */
+export type RestoreMode = 'stay' | 'copy' | 'copy-missing';
+export interface PersistFolder {
+    readonly name: FolderName;
+    /** Where the install put it. */
+    readonly source: string;
+    readonly restore: RestoreMode;
+    /** Not every install has it (the Build Tools without .NET parts): skipped when missing. */
+    readonly optional: boolean;
+}
+export declare function productFolder(product: VsRequest['product']): 'Community' | 'BuildTools';
+/** The instances folder of the Visual Studio installer (one subfolder per instance ID). */
+export declare function instancesDir(places: WinPlaces): string;
+/** Every folder a Visual Studio install spreads over, and what a boot does with each. */
+export declare function persistFolders(vs: {
+    readonly product: VsRequest['product'];
+    readonly installationPath: string;
+    readonly instanceId: string;
+}, places: WinPlaces): PersistFolder[];
+export declare const RegEntrySchema: z.ZodObject<{
+    view: z.ZodEnum<{
+        32: "32";
+        64: "64";
+    }>;
+    key: z.ZodString;
+    name: z.ZodString;
+    kind: z.ZodEnum<{
+        string: "string";
+        expand: "expand";
+        dword: "dword";
+    }>;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+}, z.core.$strict>;
+export type RegEntry = z.infer<typeof RegEntrySchema>;
+export interface RegRead {
+    readonly view: '64' | '32';
+    readonly key: string;
+    /** Only these values (null: every string and DWORD value). */
+    readonly names: readonly string[] | null;
+    readonly recurse: boolean;
+}
+/** The registry values that point at the saved folders, read in both views at capture time. */
+export declare const REGISTRY_READS: readonly Omit<RegRead, 'view'>[];
+export declare const VsPersistMarkerSchema: z.ZodObject<{
+    product: z.ZodEnum<{
+        buildtools: "buildtools";
+        community: "community";
+    }>;
+    version: z.ZodString;
+    components: z.ZodArray<z.ZodString>;
+    instanceId: z.ZodString;
+    installationPath: z.ZodString;
+    sdkVersion: z.ZodString;
+    folders: z.ZodArray<z.ZodEnum<{
+        Community: "Community";
+        BuildTools: "BuildTools";
+        WindowsKits10: "WindowsKits10";
+        NETFXSDK: "NETFXSDK";
+        "MicrosoftSDKs-v10.0A": "MicrosoftSDKs-v10.0A";
+        ReferenceAssemblies: "ReferenceAssemblies";
+        Installer: "Installer";
+        Shared: "Shared";
+        Setup: "Setup";
+        instance: "instance";
+    }>>;
+    registry: z.ZodArray<z.ZodObject<{
+        view: z.ZodEnum<{
+            32: "32";
+            64: "64";
+        }>;
+        key: z.ZodString;
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            string: "string";
+            expand: "expand";
+            dword: "dword";
+        }>;
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    }, z.core.$strict>>;
+    capturedAt: z.ZodString;
+}, z.core.$strict>;
+export type VsPersistMarker = z.infer<typeof VsPersistMarkerSchema>;
+/** What save-visual-studio.ps1 writes to its result file. */
+export declare const SaveResultSchema: z.ZodObject<{
+    copied: z.ZodArray<z.ZodEnum<{
+        Community: "Community";
+        BuildTools: "BuildTools";
+        WindowsKits10: "WindowsKits10";
+        NETFXSDK: "NETFXSDK";
+        "MicrosoftSDKs-v10.0A": "MicrosoftSDKs-v10.0A";
+        ReferenceAssemblies: "ReferenceAssemblies";
+        Installer: "Installer";
+        Shared: "Shared";
+        Setup: "Setup";
+        instance: "instance";
+    }>>;
+    registry: z.ZodArray<z.ZodObject<{
+        view: z.ZodEnum<{
+            32: "32";
+            64: "64";
+        }>;
+        key: z.ZodString;
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            string: "string";
+            expand: "expand";
+            dword: "dword";
+        }>;
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SaveResult = z.infer<typeof SaveResultSchema>;
+/**
+ * Whether the saved copy serves this request: the same product with every component, or Community for a Build Tools
+ * request (it holds the same C++ parts; only the workload IDs differ).
+ */
+export declare function persistCovers(marker: VsPersistMarker, req: Pick<VsRequest, 'product' | 'components'>): boolean;
+/**
+ * The instance's state.json with every mention of the install folder (JSON-escaped, any case) moved to `to`. A longer
+ * folder name that only starts the same (Community2) is left alone.
+ */
+export declare function rewriteInstanceState(text: string, from: string, to: string): string;
+/** `value` with a saved folder's old place swapped for its place on the data disk (case-insensitive prefix). */
+export declare function rebase(value: string, moves: readonly {
+    from: string;
+    to: string;
+}[]): string;
+/** What the boot writes under HKLM: the saved values (paths moved to the data disk) in both views, the COM class. */
+export declare function registryPlan(marker: VsPersistMarker, root: string, places: WinPlaces): RegEntry[];
+/**
+ * The newest of the instances vswhere lists. Chosen here, not with vswhere's -latest, which fails outright (0x8000FFFF)
+ * when two instances have the same install date, as a copy of an instance does.
+ */
+export declare function newestInstance<T extends {
+    readonly installationVersion?: string;
+}>(instances: readonly T[]): T | null;
+export interface SaveCopy {
+    readonly name: FolderName;
+    readonly from: string;
+    readonly to: string;
+    readonly optional: boolean;
+}
+/** The input of save-visual-studio.ps1: the folders to mirror onto the data disk and the registry values to read. */
+export declare function saveInput(vs: {
+    readonly product: VsRequest['product'];
+    readonly installationPath: string;
+    readonly instanceId: string;
+}, root: string, places: WinPlaces, resultFile: string): {
+    copies: SaveCopy[];
+    registry: RegRead[];
+    resultFile: string;
+};
+/** The marker for a finished capture (written after the instance's state is rewritten). */
+export declare function markerFrom(req: Pick<VsRequest, 'product' | 'components'>, vs: {
+    readonly installationPath: string;
+    readonly instanceId: string;
+    readonly version: string;
+}, result: SaveResult, capturedAt: string): VsPersistMarker;
+export interface RestoreCopy {
+    readonly name: FolderName;
+    readonly from: string;
+    readonly to: string;
+    /** 'all': what differs is copied; 'missing': each subfolder only when the target has none. */
+    readonly mode: 'all' | 'missing';
+}
+/** The input of restore-visual-studio.ps1: the folders copied back to their fixed places, then the registry values. */
+export declare function restoreInput(marker: VsPersistMarker, root: string, places: WinPlaces): {
+    copies: RestoreCopy[];
+    registry: RegEntry[];
+};