windows-development-sandbox 1.25.0 → 1.27.0

package/dist/shared/unity/release.js

@@ -0,0 +1,83 @@
+// Unity's release API (services.api.unity.com): the editor installer, its changeset and its modules for one version.
+// The answer is untrusted JSON: it is parsed with zod, every list and text bounded.
+import { z } from 'zod';
+import { UNITY_CHANGESET } from './version.js';
+const API = 'https://services.api.unity.com/unity/editor/release/v1/releases';
+const MARGIN = 1.1;
+/** The request for one editor version (Windows, x86_64, one result). */
+export function releaseUrl(version) {
+    return API + '?version=' + encodeURIComponent(version) + '&platform=WINDOWS&architecture=X86_64&limit=1';
+}
+const Size = z.object({ value: z.number().min(0) });
+const Text = (max) => z.string().max(max);
+const SubModule = z.lazy(() => z.object({
+    id: z.string().regex(/^[A-Za-z0-9._-]{1,80}$/),
+    downloadSize: Size.optional(),
+    installedSize: Size.optional(),
+    integrity: Text(200).optional(),
+    subModules: z.array(SubModule).max(50).optional(),
+}));
+const ReleaseResponseSchema = z.object({
+    results: z
+        .array(z.object({
+        version: Text(40),
+        shortRevision: z.string().regex(UNITY_CHANGESET),
+        downloads: z
+            .array(z.object({
+            url: z.string().url().max(2000).startsWith('https://'),
+            type: Text(20),
+            integrity: Text(200).optional(),
+            downloadSize: Size,
+            installedSize: Size,
+            modules: z.array(SubModule).max(200).default([]),
+        }))
+            .min(1)
+            .max(10),
+    }))
+        .max(10),
+});
+function flatten(m, depth = 0) {
+    if (depth > 3)
+        return [];
+    return (m.subModules ?? []).flatMap((s) => [s, ...flatten(s, depth + 1)]);
+}
+/** The first release an API answer holds (the EXE installer), or null when it holds none or has another shape. */
+export function pickRelease(json) {
+    const parsed = ReleaseResponseSchema.safeParse(json);
+    if (!parsed.success)
+        return null;
+    const r = parsed.data.results[0];
+    const d = r?.downloads.find((x) => x.type.toUpperCase() === 'EXE') ?? r?.downloads[0];
+    if (!r || !d)
+        return null;
+    return {
+        version: r.version,
+        changeset: r.shortRevision,
+        editor: {
+            url: d.url,
+            integrity: d.integrity ?? null,
+            downloadBytes: d.downloadSize.value,
+            installedBytes: d.installedSize.value,
+        },
+        modules: d.modules.map((m) => {
+            const kids = flatten(m);
+            return {
+                id: m.id,
+                downloadBytes: m.downloadSize?.value ?? 0,
+                installedBytes: m.installedSize?.value ?? 0,
+                integrity: m.integrity ?? null,
+                children: kids.map((k) => k.id),
+                childDownloadBytes: kids.reduce((n, k) => n + (k.downloadSize?.value ?? 0), 0),
+                childInstalledBytes: kids.reduce((n, k) => n + (k.installedSize?.value ?? 0), 0),
+            };
+        }),
+    };
+}
+/** Room an install needs: (editor download + installed + the chosen modules with their children) plus 10%. */
+export function installNeedBytes(r, modules) {
+    let bytes = r.editor.downloadBytes + r.editor.installedBytes;
+    for (const m of r.modules)
+        if (modules.includes(m.id))
+            bytes += m.downloadBytes + m.installedBytes + m.childDownloadBytes + m.childInstalledBytes;
+    return Math.ceil(bytes * MARGIN);
+}

package/dist/shared/unity/status.d.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+/** The file in tools\unity. */
+export declare const UNITY_STATUS_FILE = "status.json";
+export declare const UnityStatusSchema: z.ZodObject<{
+    updatedAt: z.ZodString;
+    cli: z.ZodNullable<z.ZodObject<{
+        version: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strip>>;
+    editors: z.ZodArray<z.ZodObject<{
+        version: z.ZodString;
+        root: z.ZodString;
+        origin: z.ZodEnum<{
+            pc: "pc";
+            data: "data";
+        }>;
+        writable: z.ZodBoolean;
+        modules: z.ZodArray<z.ZodString>;
+        sizeBytes: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    projects: z.ZodArray<z.ZodObject<{
+        workspace: z.ZodString;
+        version: z.ZodNullable<z.ZodString>;
+        editor: z.ZodNullable<z.ZodString>;
+        reason: z.ZodString;
+        bridge: z.ZodNullable<z.ZodEnum<{
+            pipeline: "pipeline";
+            coplay: "coplay";
+        }>>;
+    }, z.core.$strip>>;
+    licence: z.ZodObject<{
+        state: z.ZodEnum<{
+            unknown: "unknown";
+            none: "none";
+            active: "active";
+            invalid: "invalid";
+        }>;
+        kind: z.ZodString;
+        detail: z.ZodString;
+        user: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    assetCache: z.ZodObject<{
+        mode: z.ZodEnum<{
+            pc: "pc";
+            persisted: "persisted";
+            local: "local";
+        }>;
+        dir: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    pcAssets: z.ZodArray<z.ZodString>;
+    hub: z.ZodObject<{
+        installed: z.ZodBoolean;
+        path: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    mcp: z.ZodNullable<z.ZodString>;
+    skills: z.ZodBoolean;
+    problem: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type UnityStatus = z.infer<typeof UnityStatusSchema>;

package/dist/shared/unity/status.js

@@ -0,0 +1,45 @@
+// What the sandbox last found for Unity (tools\unity\status.json): the CLI, the editors, which editor each project
+// opens with, the licence, the Asset Store cache. The sandbox writes it; the Unity page on this PC reads it with this
+// schema (bounded strings and lists) and prints its text through safeText.
+import { z } from 'zod';
+/** The file in tools\unity. */
+export const UNITY_STATUS_FILE = 'status.json';
+const Text = (max = 400) => z.string().max(max);
+export const UnityStatusSchema = z.object({
+    updatedAt: Text(40),
+    cli: z.object({ version: Text(40), path: Text() }).nullable(),
+    editors: z
+        .array(z.object({
+        version: Text(40),
+        root: Text(),
+        origin: z.enum(['pc', 'data']),
+        writable: z.boolean(),
+        modules: z.array(Text(60)).max(20),
+        sizeBytes: z.number().int().min(0).nullable(),
+    }))
+        .max(32),
+    projects: z
+        .array(z.object({
+        workspace: Text(),
+        /** The version its ProjectVersion.txt asks for. */
+        version: Text(40).nullable(),
+        /** The root of the editor it opens with, null when there is none for it. */
+        editor: Text().nullable(),
+        reason: Text(),
+        bridge: z.enum(['pipeline', 'coplay']).nullable(),
+    }))
+        .max(64),
+    licence: z.object({
+        state: z.enum(['active', 'none', 'invalid', 'unknown']),
+        kind: Text(60),
+        detail: Text(),
+        user: Text(256).nullable(),
+    }),
+    assetCache: z.object({ mode: z.enum(['persisted', 'pc', 'local']), dir: Text().nullable() }),
+    pcAssets: z.array(Text()).max(4),
+    hub: z.object({ installed: z.boolean(), path: Text().nullable() }),
+    /** The MCP server's name when it was registered. */
+    mcp: Text(100).nullable(),
+    skills: z.boolean(),
+    problem: Text(600).nullable(),
+});

package/dist/shared/unity/version.d.ts

@@ -0,0 +1,27 @@
+export declare const UNITY_VERSION: RegExp;
+/** A changeset (short revision) as Unity prints it. */
+export declare const UNITY_CHANGESET: RegExp;
+export interface UnityVersion {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+    /** a (alpha), b (beta), f (final), p (patch). */
+    readonly stage: 'a' | 'b' | 'f' | 'p';
+    readonly build: number;
+}
+export declare function parseUnityVersion(text: string): UnityVersion | null;
+/** Negative when a is older than b, 0 when equal; an unreadable version sorts first. */
+export declare function compareUnityVersions(a: string, b: string): number;
+export interface ProjectVersion {
+    readonly version: string;
+    readonly changeset: string | null;
+}
+/** The editor a ProjectVersion.txt asks for: m_EditorVersion, and the changeset of m_EditorVersionWithRevision. */
+export declare function parseProjectVersion(text: string): ProjectVersion | null;
+/**
+ * The editor to open a project with: its own ProjectVersion.txt always wins (another version upgrades its files); the
+ * setting's version ("project" or e.g. "6000.0.32f1") is only for folders without one.
+ */
+export declare function wantedVersion(projectFile: string | null, setting: string): ProjectVersion | null;
+/** The Unity Pipeline package (and so `unity command` / `unity eval`) needs Unity 6 or later. */
+export declare function supportsPipeline(version: string): boolean;

package/dist/shared/unity/version.js

@@ -0,0 +1,75 @@
+// Unity editor versions ("6000.0.58f2") and the ProjectSettings/ProjectVersion.txt that names one. Pure; the text read
+// from a project is bounded (the first 50 lines of at most 64 KB).
+export const UNITY_VERSION = /^(\d{1,4})\.(\d{1,3})\.(\d{1,3})([abfp])(\d{1,3})$/;
+/** A changeset (short revision) as Unity prints it. */
+export const UNITY_CHANGESET = /^[0-9a-f]{12}$/;
+const MAX_PROJECT_VERSION_BYTES = 64 * 1024;
+const MAX_PROJECT_VERSION_LINES = 50;
+const STAGES = 'abfp';
+export function parseUnityVersion(text) {
+    const m = UNITY_VERSION.exec(text);
+    if (!m)
+        return null;
+    return {
+        major: Number(m[1]),
+        minor: Number(m[2]),
+        patch: Number(m[3]),
+        stage: m[4],
+        build: Number(m[5]),
+    };
+}
+/** Negative when a is older than b, 0 when equal; an unreadable version sorts first. */
+export function compareUnityVersions(a, b) {
+    const x = parseUnityVersion(a);
+    const y = parseUnityVersion(b);
+    if (!x || !y)
+        return x ? 1 : y ? -1 : a.localeCompare(b);
+    return (x.major - y.major ||
+        x.minor - y.minor ||
+        x.patch - y.patch ||
+        STAGES.indexOf(x.stage) - STAGES.indexOf(y.stage) ||
+        x.build - y.build);
+}
+/** The editor a ProjectVersion.txt asks for: m_EditorVersion, and the changeset of m_EditorVersionWithRevision. */
+export function parseProjectVersion(text) {
+    let version = null;
+    let changeset = null;
+    const lines = text.slice(0, MAX_PROJECT_VERSION_BYTES).split('\n', MAX_PROJECT_VERSION_LINES);
+    for (const raw of lines) {
+        const line = raw.replace(/^\uFEFF/, '').trim();
+        if (line.startsWith('m_EditorVersionWithRevision:')) {
+            const rest = line.slice('m_EditorVersionWithRevision:'.length).trim();
+            const open = rest.indexOf('(');
+            const close = rest.indexOf(')', open);
+            const v = (open < 0 ? rest : rest.slice(0, open)).trim();
+            if (UNITY_VERSION.test(v))
+                version ??= v;
+            if (open >= 0 && close > open) {
+                const cs = rest.slice(open + 1, close).trim();
+                if (UNITY_CHANGESET.test(cs))
+                    changeset = cs;
+            }
+        }
+        else if (line.startsWith('m_EditorVersion:')) {
+            const v = line.slice('m_EditorVersion:'.length).trim();
+            if (UNITY_VERSION.test(v))
+                version = v;
+        }
+    }
+    return version ? { version, changeset } : null;
+}
+/**
+ * The editor to open a project with: its own ProjectVersion.txt always wins (another version upgrades its files); the
+ * setting's version ("project" or e.g. "6000.0.32f1") is only for folders without one.
+ */
+export function wantedVersion(projectFile, setting) {
+    const own = projectFile === null ? null : parseProjectVersion(projectFile);
+    if (own)
+        return own;
+    return setting !== 'project' && UNITY_VERSION.test(setting) ? { version: setting, changeset: null } : null;
+}
+/** The Unity Pipeline package (and so `unity command` / `unity eval`) needs Unity 6 or later. */
+export function supportsPipeline(version) {
+    const v = parseUnityVersion(version);
+    return v !== null && v.major >= 6000;
+}

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;