windows-development-sandbox 1.25.0 → 1.25.1

package/dist/shared/browser-policy.js

@@ -0,0 +1,22 @@
+// The machine policy of the sandbox's browsers (Edge and Chrome), written under HKLM at every boot by the guest: no GPU
+// and the folder downloads go to. Pure (no reads or writes here): the guest runs reg.exe with these entries and the
+// self-test checks them.
+import path from 'node:path';
+export const BROWSER_POLICY_KEYS = [
+    'HKLM\\SOFTWARE\\Policies\\Microsoft\\Edge',
+    'HKLM\\SOFTWARE\\Policies\\Google\\Chrome',
+];
+/**
+ * The policies for each browser: no hardware acceleration (today's behaviour) and, when a downloads folder is given,
+ * DefaultDownloadDirectory (the default only: Playwright's download path and the user's own choice still win).
+ */
+export function browserPolicies(o) {
+    if (o.downloads !== null && (!path.win32.isAbsolute(o.downloads) || /["\r\n%]/.test(o.downloads)))
+        throw new Error('not a folder');
+    return BROWSER_POLICY_KEYS.flatMap((key) => [
+        { key, name: 'HardwareAccelerationModeEnabled', type: 'REG_DWORD', data: '0' },
+        ...(o.downloads === null
+            ? []
+            : [{ key, name: 'DefaultDownloadDirectory', type: 'REG_SZ', data: o.downloads }]),
+    ]);
+}

package/dist/shared/io/index.d.ts

@@ -6,3 +6,4 @@ export * from './copy-tree.js';
 export * from './bounded.js';
 export * from './text.js';
 export * from './disk.js';
+export * from './rotate-log.js';

package/dist/shared/io/index.js

@@ -6,3 +6,4 @@ export * from './copy-tree.js';
 export * from './bounded.js';
 export * from './text.js';
 export * from './disk.js';
+export * from './rotate-log.js';

package/dist/shared/io/rotate-log.d.ts

@@ -0,0 +1,2 @@
+/** Moves `file` to `file + '.1'` (replacing the older copy) when it is over `maxBytes`; true when it moved. */
+export declare function rotateLog(file: string, maxBytes: number): boolean;

package/dist/shared/io/rotate-log.js

@@ -0,0 +1,16 @@
+// Keeps a log that a detached program appends to from growing for ever: past the limit it becomes <log>.1.
+import fs from 'node:fs';
+/** Moves `file` to `file + '.1'` (replacing the older copy) when it is over `maxBytes`; true when it moved. */
+export function rotateLog(file, maxBytes) {
+    try {
+        if (fs.statSync(file).size <= maxBytes)
+            return false;
+        fs.rmSync(file + '.1', { force: true });
+        fs.renameSync(file, file + '.1');
+        return true;
+    }
+    catch {
+        // No log yet, or it is held open: the next start tries again.
+        return false;
+    }
+}

package/dist/shared/memory/policy.d.ts

@@ -67,3 +67,8 @@ export declare function chooseTargetDir(targetDir: string, freeBytes: number): {
 };
 /** The most heavy compilers (rustc, clippy-driver, link ...) that run at once in the agents' job: only with vGPU on. */
 export declare function maxCompilers(cpus: number, profile: LoadProfile): number | null;
+/**
+ * The cargo variable that names the linker of a Rust host (`x86_64-pc-windows-msvc` ->
+ * `CARGO_TARGET_X86_64_PC_WINDOWS_MSVC_LINKER`).
+ */
+export declare function cargoLinkerVar(host: string): string;

package/dist/shared/memory/policy.js

@@ -108,3 +108,10 @@ export function chooseTargetDir(targetDir, freeBytes) {
 export function maxCompilers(cpus, profile) {
     return profile === 'gentle' ? Math.min(4, Math.max(2, Math.floor(cpus / 4))) : null;
 }
+/**
+ * The cargo variable that names the linker of a Rust host (`x86_64-pc-windows-msvc` ->
+ * `CARGO_TARGET_X86_64_PC_WINDOWS_MSVC_LINKER`).
+ */
+export function cargoLinkerVar(host) {
+    return 'CARGO_TARGET_' + host.toUpperCase().replace(/[^A-Z0-9]/g, '_') + '_LINKER';
+}

package/dist/shared/paths/pc-installs.d.ts

@@ -1,6 +1,6 @@
 /** Where this PC's installs appear in the sandbox (reserved: RESERVED_GUEST). */
 export declare const PC_INSTALLS_GUEST = "C:\\PcInstalls";
-export type PcInstallKind = 'steam-game' | 'steam-library' | 'epic-game' | 'unreal' | 'unity';
+export type PcInstallKind = 'steam-game' | 'steam-library' | 'epic-game' | 'unreal' | 'unreal-vault' | 'unity';
 export interface PcInstall {
     readonly kind: PcInstallKind;
     /** The Steam app ID or library (library1), the Epic app name, the engine (UE_5.4) or editor version. */
@@ -9,8 +9,19 @@ export interface PcInstall {
     readonly version?: string;
     /** The folder on this PC (never sent to the sandbox). */
     readonly host: string;
-    /** Where it appears in the sandbox, read-only. */
+    /** Where it appears in the sandbox, read-only unless `writable`. */
     readonly guest: string;
+    /** Mapped writable: an engine folder you registered (pcInstalls.unrealEngineFolders). */
+    readonly writable?: boolean;
+    /** An Unreal source build's registered name on this PC (HKCU\Software\Epic Games\Unreal Engine\Builds). */
+    readonly buildId?: string;
+    /** The Epic Games Launcher's own ids of the app (from this PC's LauncherInstalled.dat). */
+    readonly launcher?: {
+        readonly namespaceId: string;
+        readonly itemId: string;
+        readonly artifactId: string;
+        readonly appVersion: string;
+    };
 }
 /** What session.json says about them: no host paths. */
 export interface PcInstallManifest {

package/dist/shared/paths/pc-installs.js

@@ -9,6 +9,7 @@ const AREA = {
     'steam-library': 'steam',
     'epic-game': 'epic',
     unreal: 'unreal',
+    'unreal-vault': 'unreal',
     unity: 'unity',
 };
 /** The guest folder of one install: C:\PcInstalls\steam\<appid>, \epic\<AppName>, \unreal\UE_5.4, \unity\<ver>. */

package/dist/shared/readiness.d.ts

@@ -3,7 +3,6 @@ export declare const NOT_READY: {
     readonly toolchains: readonly ["unity", "godot", "android", "flutter", "dart", "reactNative"];
     /** Service sign-ins whose host or guest side is a stub: the menu and the web do not list them. */
     readonly kinds: readonly ["unity", "keystore", "play", "expo", "appstore"];
-    readonly unreal: readonly ["engines"];
 };
 export declare const isToolchainReady: (name: string) => boolean;
 export declare const isKindReady: (kind: string) => boolean;

package/dist/shared/readiness.js

@@ -5,7 +5,6 @@ export const NOT_READY = {
     toolchains: ['unity', 'godot', 'android', 'flutter', 'dart', 'reactNative'],
     /** Service sign-ins whose host or guest side is a stub: the menu and the web do not list them. */
     kinds: ['unity', 'keystore', 'play', 'expo', 'appstore'],
-    unreal: ['engines'],
 };
 export const isToolchainReady = (name) => !NOT_READY.toolchains.includes(name);
 export const isKindReady = (kind) => !NOT_READY.kinds.includes(kind);

package/dist/shared/signer.d.ts

@@ -21,4 +21,8 @@ export declare const SIGNERS: {
     readonly unity: {
         readonly subject: readonly ["^CN=\"?Unity Technologies"];
     };
+    /** The Epic Games Launcher's MSI (checked on EpicInstaller-20.3.3.msi). */
+    readonly epic: {
+        readonly subject: readonly ["^CN=Epic Games Inc\\., O=Epic Games Inc\\., L=Cary, S=North Carolina, C=US"];
+    };
 };

package/dist/shared/signer.js

@@ -12,4 +12,6 @@ export const SIGNERS = {
     microsoft: { subject: ['^CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US$'] },
     valve: { subject: ['^CN="?Valve(,| Corp)'] },
     unity: { subject: ['^CN="?Unity Technologies'] },
+    /** The Epic Games Launcher's MSI (checked on EpicInstaller-20.3.3.msi). */
+    epic: { subject: ['^CN=Epic Games Inc\\., O=Epic Games Inc\\., L=Cary, S=North Carolina, C=US'] },
 };

package/dist/shared/unreal/engines.d.ts

@@ -0,0 +1,161 @@
+/** Where an engine came from, which decides whether it is writable and how it is listed. */
+export type EngineOrigin = 
+/** Installed on this PC, mapped read-only under C:\PcInstalls\unreal (pcInstalls.unrealEngines). */
+'pc'
+/** A folder of this PC you registered (pcInstalls.unrealEngineFolders), mapped writable. */
+ | 'pc-folder'
+/** Installed by the Epic Games Launcher in a sandbox, in tools\unreal\engines on the data disk. */
+ | 'launcher'
+/** Another engine folder in tools\unreal\engines (a source build or a copy). */
+ | 'data'
+/** A source build found in a project root (C:\Projects\<root>\<folder>). */
+ | 'project';
+export declare const ORIGIN_LABELS: Readonly<Record<EngineOrigin, string>>;
+export interface BuildVersion {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+    readonly changelist: number;
+    readonly branch: string;
+}
+/** One engine the sandbox knows. */
+export interface UnrealEngine {
+    /** UE_5.4 for an installed build; the source build's registered name (a GUID or a plain name). */
+    readonly id: string;
+    /** The engine's folder (holds Engine\Build\Build.version). */
+    readonly dir: string;
+    readonly version: BuildVersion;
+    /** "installed": a launcher or installed build (InstalledBuild.txt); "source": built from the engine's source. */
+    readonly build: 'installed' | 'source';
+    readonly origin: EngineOrigin;
+    readonly writable: boolean;
+}
+/** How engine files are read: bounded reads, folder lists, existence. */
+export interface EngineFs {
+    exists(file: string): boolean;
+    /** At most `max` bytes, null when it is missing, too big or not a file. */
+    read(file: string, max: number): Buffer | null;
+    /** The names in a folder ([] when it is not one). */
+    list(dir: string): string[];
+}
+/** Engine\Build\Build.version: the version of an engine folder, or null when the text is not one. */
+export declare function parseBuildVersion(text: string): BuildVersion | null;
+/** "5.4": the name the launcher and the registry give an engine version. */
+export declare const majorMinor: (v: BuildVersion) => string;
+/** "5.4.4": the full version for people. */
+export declare const versionText: (v: BuildVersion) => string;
+/** "UE_5.4": the launcher's app name (and the folder it installs into). */
+export declare const launcherAppName: (v: BuildVersion) => string;
+export declare function compareVersions(a: BuildVersion, b: BuildVersion): number;
+/** Engine\Build\Build.version of a folder, or null when it is not an engine. */
+export declare function readEngineVersion(dir: string, fs: EngineFs): BuildVersion | null;
+/** Whether an engine folder is an installed build (what the launcher installs): Engine\Build\InstalledBuild.txt. */
+export declare function isInstalledBuild(dir: string, fs: EngineFs): boolean;
+/** Whether a name can be a source build's registered name (UnrealVersionSelector writes a {GUID}). */
+export declare const isBuildId: (id: string) => boolean;
+/**
+ * A source build's registered name when it has none of its own: a GUID made from its folder, so it is the same every
+ * boot and a project that was switched to it keeps finding it.
+ */
+export declare function stableBuildId(dir: string): string;
+/** The engine in a folder, or null when it is not one. `id`: a source build's registered name (else one is made). */
+export declare function engineAt(dir: string, origin: EngineOrigin, writable: boolean, fs: EngineFs, id?: string): UnrealEngine | null;
+/** What the guest knows of this PC's engines (session.json's pcInstalls items of kind "unreal"). */
+export interface MappedEngine {
+    readonly guest: string;
+    readonly id: string;
+    /** A registered folder of this PC: mapped writable. */
+    readonly writable?: boolean;
+    /** A source build's registered name on this PC (HKCU ... Builds), kept so the project's association still matches. */
+    readonly buildId?: string;
+}
+export interface EngineSources {
+    /** Engines of this PC mapped into the sandbox. */
+    readonly mapped: readonly MappedEngine[];
+    /** tools\unreal\engines on the data disk. */
+    readonly enginesRoot: string;
+    /** The folders of the engines the launcher installed there (from its saved manifests). */
+    readonly launcherDirs: readonly string[];
+    /** Project roots in the sandbox (C:\Projects\<root>): their folders are looked at for source builds. */
+    readonly projectRoots: readonly string[];
+}
+/** At most this many engines are used. */
+export declare const MAX_ENGINES = 16;
+/** Every engine the sandbox can use, in a fixed order (this PC's, the data disk's, the project roots'), once each. */
+export declare function findEngines(s: EngineSources, fs: EngineFs): UnrealEngine[];
+export type EngineAssociation = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'version';
+    readonly version: string;
+} | {
+    readonly kind: 'build';
+    readonly id: string;
+};
+/** What a .uproject's EngineAssociation names: "5.4" (an installed build), "{GUID}" or a name (a source build). */
+export declare function parseEngineAssociation(value: unknown): EngineAssociation;
+/** The EngineAssociation of a .uproject's text (null when it is not JSON). */
+export declare function uprojectAssociation(text: string): EngineAssociation | null;
+/** A project's .uproject: in its folder, else one folder down (the first by name), or null. */
+export declare function findUproject(workspace: string, fs: EngineFs): string | null;
+export interface EngineChoice {
+    readonly engine: UnrealEngine | null;
+    /** Why this one, in plain words (or why none). */
+    readonly reason: string;
+    /** The name the project gave a source build that is not registered here by that name: register it for this engine. */
+    readonly alias?: string;
+}
+/**
+ * The engine a project builds with: the one its EngineAssociation names (a version: a writable one before this PC's
+ * read-only one; a build: that registered build), else the newest. Null when the project names one that is not here.
+ */
+export declare function chooseEngine(engines: readonly UnrealEngine[], association: EngineAssociation): EngineChoice;
+/** One registry value the sandbox writes (string values only). */
+export interface RegistryValue {
+    readonly hive: 'HKLM' | 'HKCU';
+    readonly key: string;
+    /** '' is the default value. */
+    readonly name: string;
+    readonly value: string;
+}
+/** Installed builds: where an installer records them (UnrealVersionSelector and the editor read it). */
+export declare const INSTALLED_KEY = "SOFTWARE\\EpicGames\\Unreal Engine";
+/** Source builds: UnrealVersionSelector's list (name = the build's id, value = its folder). */
+export declare const BUILDS_KEY = "Software\\Epic Games\\Unreal Engine\\Builds";
+/**
+ * The installed build of each version that the editor and UnrealVersionSelector use: one per major.minor, chosen the
+ * way chooseEngine chooses (writable before read-only, then the newest).
+ */
+export declare function preferredInstalled(engines: readonly UnrealEngine[]): UnrealEngine[];
+/**
+ * The registry values that make Unreal find the engines: an installed build as HKLM\SOFTWARE\EpicGames\Unreal
+ * Engine\<5.4> InstalledDirectory (one per version: the one a project would pick), a source build as a value under
+ * HKCU\Software\Epic Games\Unreal Engine\Builds. `aliases`: names a project uses for a source build here (its GUID on
+ * this PC), registered for the folder they stand for, so the .uproject works unchanged.
+ */
+export declare function registryPlan(engines: readonly UnrealEngine[], aliases?: readonly {
+    readonly id: string;
+    readonly dir: string;
+}[]): RegistryValue[];
+/** UnrealVersionSelector inside an engine (it opens, switches and generates project files for .uproject files). */
+export declare function versionSelectorIn(dir: string): string;
+/**
+ * The .uproject file association UnrealVersionSelector /fileassociations writes (per user): open in the editor, launch
+ * the game, generate Visual Studio project files, switch the engine version.
+ */
+export declare function fileAssociationPlan(selector: string): RegistryValue[];
+/** The folders of an engine an agent runs its tools from (those that exist), in PATH order. */
+export declare function engineToolDirs(dir: string, fs: Pick<EngineFs, 'exists'>): string[];
+/** The engine folders put at the END of PATH: they hold many DLLs, which every program started from PATH would load. */
+export declare function engineExtraDirs(dir: string, fs: Pick<EngineFs, 'exists'>): string[];
+/** Variables for the project's engine: UE_ROOT (the engine folder) and UE_ENGINE_DIR (its Engine folder). */
+export declare function engineVars(engine: UnrealEngine): Record<string, string>;
+/**
+ * The derived data cache: UE-LocalDataCachePath moves the local cache (and from 5.4 the Zen store, in its Zen
+ * subfolder) out of the engine and off the sandbox's disk. "local" leaves Unreal's own place (the sandbox's disk).
+ */
+export declare function ddcVars(mode: 'persisted' | 'local', ddcDir: string): Record<string, string>;
+/** The editor's MCP server (Unreal 5.8's ModelContextProtocol plugin): its default address. */
+export declare const UNREAL_MCP_URL = "http://127.0.0.1:8000/mcp";
+/** Whether an engine ships the ModelContextProtocol plugin (5.8 and later). */
+export declare function hasMcpPlugin(engine: UnrealEngine, fs: Pick<EngineFs, 'exists'>): boolean;

package/dist/shared/unreal/engines.js

@@ -0,0 +1,308 @@
+// Unreal engines, pure: what an engine folder is (Engine\Build\Build.version; Engine\Build\InstalledBuild.txt makes it
+// an installed build), where the sandbox finds them (this PC read-only, the Epic Games Launcher's folder on the data
+// disk, source builds in a project root or registered by you), which one a project builds with (its .uproject's
+// EngineAssociation, then a writable engine over a read-only one, then the newest), and what the sandbox writes so
+// UnrealBuildTool, UnrealVersionSelector and the editor find them (registry plan) and an agent can run them (PATH,
+// variables, the derived data cache). Every file is read through the EngineFs it is given (bounded): the guest passes
+// the real disk, the self-test its fixtures.
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { z } from 'zod';
+const win = path.win32;
+export const ORIGIN_LABELS = {
+    pc: 'this PC, read-only',
+    'pc-folder': 'your folder on this PC',
+    launcher: 'Epic Games Launcher, data disk',
+    data: 'data disk',
+    project: 'in a project folder',
+};
+const BuildVersionSchema = z.object({
+    MajorVersion: z.number().int().min(4).max(99),
+    MinorVersion: z.number().int().min(0).max(99),
+    PatchVersion: z.number().int().min(0).max(999),
+    Changelist: z.number().int().optional(),
+    BranchName: z.string().optional(),
+});
+const stripBom = (text) => text.replace(/^\uFEFF/, '');
+/** Engine\Build\Build.version: the version of an engine folder, or null when the text is not one. */
+export function parseBuildVersion(text) {
+    try {
+        const v = BuildVersionSchema.parse(JSON.parse(stripBom(text)));
+        return {
+            major: v.MajorVersion,
+            minor: v.MinorVersion,
+            patch: v.PatchVersion,
+            changelist: v.Changelist ?? 0,
+            branch: (v.BranchName ?? '').replace(/[^\x20-\x7e]/g, '').slice(0, 100),
+        };
+    }
+    catch {
+        return null; // Not JSON, or not a Build.version.
+    }
+}
+/** "5.4": the name the launcher and the registry give an engine version. */
+export const majorMinor = (v) => v.major + '.' + v.minor;
+/** "5.4.4": the full version for people. */
+export const versionText = (v) => v.major + '.' + v.minor + '.' + v.patch;
+/** "UE_5.4": the launcher's app name (and the folder it installs into). */
+export const launcherAppName = (v) => 'UE_' + majorMinor(v);
+export function compareVersions(a, b) {
+    return a.major - b.major || a.minor - b.minor || a.patch - b.patch || a.changelist - b.changelist;
+}
+/** Engine\Build\Build.version of a folder, or null when it is not an engine. */
+export function readEngineVersion(dir, fs) {
+    const bytes = fs.read(win.join(dir, 'Engine', 'Build', 'Build.version'), 64 * 1024);
+    return bytes ? parseBuildVersion(bytes.toString('utf8')) : null;
+}
+/** Whether an engine folder is an installed build (what the launcher installs): Engine\Build\InstalledBuild.txt. */
+export function isInstalledBuild(dir, fs) {
+    return fs.exists(win.join(dir, 'Engine', 'Build', 'InstalledBuild.txt'));
+}
+const BUILD_ID = /^[^\x00-\x1f"\\/]{1,64}$/;
+/** Whether a name can be a source build's registered name (UnrealVersionSelector writes a {GUID}). */
+export const isBuildId = (id) => id === id.trim() && BUILD_ID.test(id);
+/**
+ * A source build's registered name when it has none of its own: a GUID made from its folder, so it is the same every
+ * boot and a project that was switched to it keeps finding it.
+ */
+export function stableBuildId(dir) {
+    const h = crypto.createHash('sha1').update(win.normalize(dir).toLowerCase()).digest('hex').toUpperCase();
+    return ('{' +
+        h.slice(0, 8) +
+        '-' +
+        h.slice(8, 12) +
+        '-' +
+        h.slice(12, 16) +
+        '-' +
+        h.slice(16, 20) +
+        '-' +
+        h.slice(20, 32) +
+        '}');
+}
+/** The engine in a folder, or null when it is not one. `id`: a source build's registered name (else one is made). */
+export function engineAt(dir, origin, writable, fs, id) {
+    if (!win.isAbsolute(dir) || /["\r\n]/.test(dir))
+        return null;
+    const version = readEngineVersion(dir, fs);
+    if (!version)
+        return null;
+    const build = isInstalledBuild(dir, fs) ? 'installed' : 'source';
+    const name = build === 'installed' ? launcherAppName(version) : id && isBuildId(id) ? id : stableBuildId(dir);
+    return { id: name, dir: win.normalize(dir), version, build, origin, writable };
+}
+/** At most this many folders are looked at in one place (a project root may hold many projects). */
+const MAX_LOOK = 200;
+/** At most this many engines are used. */
+export const MAX_ENGINES = 16;
+/** Every engine the sandbox can use, in a fixed order (this PC's, the data disk's, the project roots'), once each. */
+export function findEngines(s, fs) {
+    const found = [];
+    const add = (e) => {
+        if (!e || found.length >= MAX_ENGINES)
+            return;
+        if (found.some((f) => f.dir.toLowerCase() === e.dir.toLowerCase()))
+            return;
+        found.push(e);
+    };
+    for (const m of s.mapped)
+        add(engineAt(m.guest, m.writable ? 'pc-folder' : 'pc', m.writable === true, fs, m.buildId));
+    const launched = new Set(s.launcherDirs.map((d) => win.normalize(d).toLowerCase()));
+    for (const name of fs.list(s.enginesRoot).slice(0, MAX_LOOK)) {
+        if (name.startsWith('.'))
+            continue;
+        const dir = win.join(s.enginesRoot, name);
+        add(engineAt(dir, launched.has(dir.toLowerCase()) ? 'launcher' : 'data', true, fs));
+    }
+    for (const root of s.projectRoots)
+        for (const name of fs.list(root).slice(0, MAX_LOOK)) {
+            const dir = win.join(root, name);
+            if (fs.exists(win.join(dir, 'Engine', 'Build', 'Build.version')))
+                add(engineAt(dir, 'project', true, fs));
+        }
+    return found;
+}
+/** What a .uproject's EngineAssociation names: "5.4" (an installed build), "{GUID}" or a name (a source build). */
+export function parseEngineAssociation(value) {
+    if (typeof value !== 'string' || !value.trim())
+        return { kind: 'none' };
+    const text = value.trim();
+    const version = /^(\d{1,2}\.\d{1,2})(?:\.\d{1,3})?$/.exec(text);
+    if (version)
+        return { kind: 'version', version: version[1] };
+    return isBuildId(text) ? { kind: 'build', id: text } : { kind: 'none' };
+}
+/** The EngineAssociation of a .uproject's text (null when it is not JSON). */
+export function uprojectAssociation(text) {
+    try {
+        const json = JSON.parse(stripBom(text));
+        if (!json || typeof json !== 'object' || Array.isArray(json))
+            return null;
+        return parseEngineAssociation(json.EngineAssociation);
+    }
+    catch {
+        return null;
+    }
+}
+/** A project's .uproject: in its folder, else one folder down (the first by name), or null. */
+export function findUproject(workspace, fs) {
+    const own = (dir) => {
+        const hit = fs
+            .list(dir)
+            .filter((n) => /\.uproject$/i.test(n))
+            .sort()[0];
+        return hit ? win.join(dir, hit) : null;
+    };
+    const here = own(workspace);
+    if (here)
+        return here;
+    for (const name of fs.list(workspace).slice(0, MAX_LOOK).sort()) {
+        if (name.startsWith('.') || /^(node_modules|Engine|Binaries|Intermediate|Saved|DerivedDataCache)$/i.test(name))
+            continue;
+        const hit = own(win.join(workspace, name));
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+/** Writable before read-only (the editor writes into a project's engine plugins), installed before source. */
+const preference = (e) => (e.writable ? 0 : 2) + (e.build === 'installed' ? 0 : 1);
+/**
+ * The engine a project builds with: the one its EngineAssociation names (a version: a writable one before this PC's
+ * read-only one; a build: that registered build), else the newest. Null when the project names one that is not here.
+ */
+export function chooseEngine(engines, association) {
+    const best = (list) => [...list].sort((a, b) => preference(a) - preference(b) || compareVersions(b.version, a.version))[0] ?? null;
+    if (association.kind === 'version') {
+        const engine = best(engines.filter((e) => majorMinor(e.version) === association.version));
+        return engine
+            ? { engine, reason: 'the project asks for ' + association.version }
+            : { engine: null, reason: 'the project asks for Unreal Engine ' + association.version + ', which is not here' };
+    }
+    if (association.kind === 'build') {
+        const exact = engines.find((e) => e.id.toLowerCase() === association.id.toLowerCase());
+        if (exact)
+            return { engine: exact, reason: 'the project asks for the source build ' + association.id };
+        // The project names a source build of this PC's registry; here the source sits in a project root or on the data
+        // disk under another name: use the newest of those and register the project's name for it.
+        const source = [...engines]
+            .filter((e) => e.build === 'source' && e.writable)
+            .sort((a, b) => compareVersions(b.version, a.version))[0];
+        return source
+            ? {
+                engine: source,
+                alias: association.id,
+                reason: 'the project names the source build ' +
+                    association.id +
+                    ' (registered on your PC); using the source build at ' +
+                    source.dir,
+            }
+            : { engine: null, reason: 'the project asks for the source build ' + association.id + ', which is not here' };
+    }
+    const newest = [...engines].sort((a, b) => compareVersions(b.version, a.version) || preference(a) - preference(b))[0];
+    return newest
+        ? { engine: newest, reason: 'the newest engine here' }
+        : { engine: null, reason: 'no engine is installed yet' };
+}
+/** Installed builds: where an installer records them (UnrealVersionSelector and the editor read it). */
+export const INSTALLED_KEY = 'SOFTWARE\\EpicGames\\Unreal Engine';
+/** Source builds: UnrealVersionSelector's list (name = the build's id, value = its folder). */
+export const BUILDS_KEY = 'Software\\Epic Games\\Unreal Engine\\Builds';
+/**
+ * The installed build of each version that the editor and UnrealVersionSelector use: one per major.minor, chosen the
+ * way chooseEngine chooses (writable before read-only, then the newest).
+ */
+export function preferredInstalled(engines) {
+    const sorted = engines
+        .filter((e) => e.build === 'installed')
+        .sort((a, b) => preference(a) - preference(b) || compareVersions(b.version, a.version));
+    const seen = new Set();
+    return sorted.filter((e) => {
+        const v = majorMinor(e.version);
+        if (seen.has(v))
+            return false;
+        seen.add(v);
+        return true;
+    });
+}
+/**
+ * The registry values that make Unreal find the engines: an installed build as HKLM\SOFTWARE\EpicGames\Unreal
+ * Engine\<5.4> InstalledDirectory (one per version: the one a project would pick), a source build as a value under
+ * HKCU\Software\Epic Games\Unreal Engine\Builds. `aliases`: names a project uses for a source build here (its GUID on
+ * this PC), registered for the folder they stand for, so the .uproject works unchanged.
+ */
+export function registryPlan(engines, aliases = []) {
+    const values = engines
+        .filter((e) => e.build === 'source')
+        .map((e) => ({ hive: 'HKCU', key: BUILDS_KEY, name: e.id, value: e.dir }));
+    for (const a of aliases)
+        values.push({ hive: 'HKCU', key: BUILDS_KEY, name: a.id, value: a.dir });
+    for (const e of preferredInstalled(engines))
+        values.push({
+            hive: 'HKLM',
+            key: INSTALLED_KEY + '\\' + majorMinor(e.version),
+            name: 'InstalledDirectory',
+            value: e.dir,
+        });
+    return values;
+}
+/** UnrealVersionSelector inside an engine (it opens, switches and generates project files for .uproject files). */
+export function versionSelectorIn(dir) {
+    return win.join(dir, 'Engine', 'Binaries', 'Win64', 'UnrealVersionSelector.exe');
+}
+/**
+ * The .uproject file association UnrealVersionSelector /fileassociations writes (per user): open in the editor, launch
+ * the game, generate Visual Studio project files, switch the engine version.
+ */
+export function fileAssociationPlan(selector) {
+    if (!win.isAbsolute(selector) || /["\r\n]/.test(selector))
+        throw new Error('not a program path: ' + selector);
+    const exe = '"' + selector + '"';
+    const classes = 'Software\\Classes';
+    const type = classes + '\\Unreal.ProjectFile';
+    const v = (key, value, name = '') => ({ hive: 'HKCU', key, name, value });
+    const verb = (id, label, args) => [
+        v(type + '\\shell\\' + id, label),
+        v(type + '\\shell\\' + id + '\\command', exe + ' ' + args + ' "%1"'),
+    ];
+    return [
+        v(classes + '\\.uproject', 'Unreal.ProjectFile'),
+        v(type, 'Unreal Engine Project File'),
+        v(type + '\\DefaultIcon', exe),
+        ...verb('open', 'Open', '/editor'),
+        ...verb('run', 'Launch game', '/game'),
+        ...verb('rungenproj', 'Generate Visual Studio project files', '/projectfiles'),
+        ...verb('switchversion', 'Switch Unreal Engine version...', '/switchversion'),
+    ];
+}
+// ---- Environment, PATH, derived data cache ---------------------------------------------------------------------
+/** The folders of an engine an agent runs its tools from (those that exist), in PATH order. */
+export function engineToolDirs(dir, fs) {
+    return [win.join(dir, 'Engine', 'Build', 'BatchFiles')].filter((d) => fs.exists(d));
+}
+/** The engine folders put at the END of PATH: they hold many DLLs, which every program started from PATH would load. */
+export function engineExtraDirs(dir, fs) {
+    return [
+        win.join(dir, 'Engine', 'Binaries', 'Win64'),
+        win.join(dir, 'Engine', 'Binaries', 'DotNET', 'UnrealBuildTool'),
+    ].filter((d) => fs.exists(d));
+}
+/** Variables for the project's engine: UE_ROOT (the engine folder) and UE_ENGINE_DIR (its Engine folder). */
+export function engineVars(engine) {
+    return { UE_ROOT: engine.dir, UE_ENGINE_DIR: win.join(engine.dir, 'Engine') };
+}
+/**
+ * The derived data cache: UE-LocalDataCachePath moves the local cache (and from 5.4 the Zen store, in its Zen
+ * subfolder) out of the engine and off the sandbox's disk. "local" leaves Unreal's own place (the sandbox's disk).
+ */
+export function ddcVars(mode, ddcDir) {
+    return mode === 'persisted' ? { 'UE-LocalDataCachePath': ddcDir } : {};
+}
+/** The editor's MCP server (Unreal 5.8's ModelContextProtocol plugin): its default address. */
+export const UNREAL_MCP_URL = 'http://127.0.0.1:8000/mcp';
+const MCP_PLUGIN = ['Experimental', 'ModelContextProtocol', 'ModelContextProtocol.uplugin'];
+/** Whether an engine ships the ModelContextProtocol plugin (5.8 and later). */
+export function hasMcpPlugin(engine, fs) {
+    if (engine.version.major < 5 || (engine.version.major === 5 && engine.version.minor < 8))
+        return false;
+    return fs.exists(win.join(engine.dir, 'Engine', 'Plugins', ...MCP_PLUGIN));
+}

package/dist/shared/unreal/guide.d.ts

@@ -0,0 +1,19 @@
+import type { UnrealStatus } from './status.js';
+export interface UnrealGuideProject {
+    /** The project's folder in the sandbox. */
+    readonly workspace: string;
+    /** Its .uproject, when it has one. */
+    readonly uproject: string | null;
+}
+/** Optional extra guide sections. */
+export interface UnrealGuideExtras {
+    /** The Mixamo lines (where downloads land, the import script when one ships). */
+    readonly mixamo?: {
+        readonly downloads: string;
+        readonly script: string | null;
+    };
+}
+/** The guide's Unreal lines for these projects (none when Unreal is not set up). */
+export declare function unrealGuideLines(status: UnrealStatus, projects: readonly UnrealGuideProject[], extras?: UnrealGuideExtras): string[];
+/** The short tool-summary line of a project's engine. */
+export declare function unrealSummaryLine(status: UnrealStatus, workspace: string): string;