unity-open-mcp 0.1.0 → 0.3.0

package/dist/hub-control.d.ts

@@ -0,0 +1,247 @@
+/** An installed Unity editor, enriched with build-target platforms. */
+export interface InstalledEditor {
+    /** Unity version string as named by the install folder (e.g. "6000.4.0f1"). */
+    version: string;
+    /** Absolute path to the Unity executable. */
+    path: string;
+    /** Friendly build-target platform names scanned from `Data/PlaybackEngines/`. */
+    platforms: string[];
+    /** Release stream inferred from the version suffix: "LTS" | "TECH" | "Beta" | "Alpha" | "". */
+    releaseType: string;
+}
+/** One release entry from Unity's public download-archive feed. */
+export interface AvailableRelease {
+    version: string;
+    /** "LTS" | "Supported" | "TECH" | "Beta" | "Alpha". */
+    stream: string;
+    /** ISO date (`YYYY-MM-DD`) or null. */
+    releaseDate: string | null;
+    /** `https://unity.com/releases/editor/whats-new/<version>`. */
+    releaseNotesUrl: string;
+    /** Changeset hash extracted from the `unityhub://` deep link, or null. */
+    changeset: string | null;
+}
+/** Result of the available-releases fetch — entries + staleness flag. */
+export interface AvailableReleasesResult {
+    entries: AvailableRelease[];
+    /** True when the data is a fallback (offline snapshot), not a live fetch. */
+    stale: boolean;
+    /** RFC 3339 timestamp of when the data was produced. */
+    fetchedAt: string;
+}
+/**
+ * Mapping from a Unity `Data/PlaybackEngines/<folder>` name to the friendly
+ * build-target label. Covers the Windows/macOS/Linux keys Unity ships on all
+ * hosts. Unknown folders fall back to the lowercased name so a new platform
+ * is never silently dropped. TS port of the Rust
+ * `friendly_playback_engine_name`.
+ */
+export declare function friendlyPlaybackEngineName(folder: string): string;
+/**
+ * Resolve the editor install's `Data/` folder. On macOS the editor lives
+ * inside `Unity.app/Contents/`; on Windows/Linux it sits in an `Editor/`
+ * subfolder (Hub layout) or as a sibling (source build). Returns null when no
+ * `Data/` directory exists. TS port of the Rust `editor_data_folder`.
+ */
+export declare function editorDataFolder(installDir: string): string | null;
+/**
+ * Scan an editor install's `Data/PlaybackEngines/` directory and return the
+ * friendly platform names of every build target Unity shipped modules for.
+ * Returns an empty array when the install is missing the directory (a minimal
+ * / custom build). TS port of the Rust `scan_playback_engines`.
+ */
+export declare function scanPlaybackEngines(installDir: string): string[];
+/**
+ * Release stream inferred from the Unity version suffix. TS port of the Rust
+ * `release_type_for`.
+ */
+export declare function releaseTypeFor(version: string): string;
+/**
+ * List installed Unity editors by scanning the Hub install roots (+ `UNITY_HUB`
+ * env override), enriching each with build-target platforms and a release
+ * stream. `roots` is an optional test hook (forwarded to
+ * `discoverUnityInstalls`); when omitted the real machine roots are scanned.
+ *
+ * The primary discovery path is filesystem scanning (matches what the Hub
+ * launcher and `unity-install-discovery.ts` do). Never throws.
+ */
+export declare function listInstalledEditors(roots?: string[]): InstalledEditor[];
+/** A version + path pair parsed from `Unity Hub --headless editors --installed`. */
+export interface ParsedEditor {
+    version: string;
+    path: string;
+}
+/**
+ * Parse the stdout of `Unity Hub --headless editors --installed`. Each line
+ * looks like `2022.3.0f1 , installed at C:\Program Files\Unity\...`. Lines that
+ * do not match are ignored. Pure (string in, list out) so it can be unit-tested
+ * against captured output.
+ */
+export declare function parseInstalledEditors(stdout: string): ParsedEditor[];
+/**
+ * Parse the stdout of `Unity Hub --headless install-path`. The Hub normally
+ * prints the bare path on its own line; some builds prefix it with a label
+ * like `Default install path: /path`. Returns the trimmed path, or null when
+ * the output is empty/unparseable. Pure.
+ *
+ * Strip-rule: a `Label: <path>` prefix is removed only when the text before
+ * the colon is a plain word/phrase (alphanumerics + spaces, no path
+ * separators) — so a Windows drive path `C:\Program Files\...` (colon at
+ * index 1, left side `C`) is left intact.
+ */
+export declare function parseInstallPath(stdout: string): string | null;
+/**
+ * Per-platform default Unity Hub binary locations. The Hub registers itself as
+ * the system handler for `unityhub://`, but the headless CLI needs the binary
+ * directly. Honors the `UNITY_HUB_PATH` env var (highest precedence). Returns
+ * null when the candidate does not exist on disk.
+ *
+ * macOS: `/Applications/Unity Hub.app/Contents/MacOS/Unity Hub`
+ * Windows: `%ProgramFiles%\Unity Hub\Unity Hub.exe`
+ * Linux: `$HOME/Unity Hub/Unity Hub` (Hub ships as an AppImage; the extracted
+ *   binary path is the common install location).
+ */
+export declare function resolveHubCliPath(): string | null;
+/** Test-only: reset the cached Hub CLI path. */
+export declare function _resetHubCliPathCacheForTests(): void;
+/**
+ * Map a raw Unity archive `stream` string to our label. Unknown values fall
+ * back to "TECH" (a conservative stable-ish default) so a future Unity string
+ * is never dropped. Mirrors the Rust `ReleaseStream::from_unity_str`.
+ */
+export declare function streamFromUnityStr(raw: string): string;
+/**
+ * Extract the changeset hash from a `unityhub://<version>/<changeset>` deep
+ * link. Returns null when the link is missing or malformed. TS port of the
+ * Rust `extract_changeset`.
+ */
+export declare function extractChangeset(deepLink?: string | null): string | null;
+/**
+ * Normalize the archive feed's full ISO timestamp (`2026-06-17T15:09:23.805Z`)
+ * down to the date portion (`2026-06-17`). Passes through values that don't
+ * look like an ISO date unchanged. TS port of the Rust `normalize_release_date`.
+ */
+export declare function normalizeReleaseDate(raw?: string | null): string | null;
+/**
+ * Parse the Next.js RSC payload embedded in the Unity download-archive page
+ * HTML and return the list of releases. The page emits the GraphQL result as
+ * one `self.__next_f.push([1,"31:<json>"])` script segment; we locate that
+ * segment, JSON-decode the string literal (un-escaping the inner JSON), strip
+ * the `31:` RSC prefix, and deserialize the result. Returns null when no
+ * releases segment is found. TS port of the Rust `parse_archive_payload`.
+ *
+ * Pure (string in, list out) so it can be unit-tested against a captured
+ * fixture without touching the network.
+ */
+export declare function parseArchivePayload(html: string): AvailableRelease[] | null;
+/**
+ * Bundled snapshot of recent Unity release streams. NOT the primary source —
+ * the offline / network-failure fallback served when the live archive fetch
+ * fails. Kept small and corrected to the right streams so we never mislabel a
+ * version. Mirrors the Rust `snapshot_entries` (newest-first).
+ */
+export declare function snapshotReleases(): AvailableRelease[];
+/**
+ * Signature of the Hub CLI invocation. Runs the Unity Hub binary in headless
+ * mode and returns `{ stdout, stderr, exitCode }`. The default implementation
+ * uses `execFileSync`; tests inject a fake.
+ */
+export type HubCliRunner = (args: string[], opts?: {
+    timeoutMs?: number;
+}) => {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+};
+/** Result of `getInstallPath` — the resolved path or a structured error. */
+export interface InstallPathResult {
+    path: string | null;
+    /** Structured error when the Hub CLI is missing or the call failed. */
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    /** Whether the Hub CLI was used (vs filesystem inference). */
+    source: "hub-cli" | "filesystem" | "none";
+}
+/**
+ * Get the default Unity editor install directory. Tries the Hub CLI
+ * (`install-path`) first; falls back to inferring from the Hub install roots
+ * (`scannedHubRoots`) when the CLI is unavailable. The `roots` override is a
+ * test hook forwarded to the filesystem fallback.
+ */
+export declare function getInstallPath(opts?: {
+    runHubCli?: HubCliRunner;
+    roots?: string[];
+}): InstallPathResult;
+/**
+ * Set the default Unity editor install directory via the Hub CLI
+ * (`install-path --set <path>`). This is the one Hub operation the
+ * `unityhub://` deep-link transport cannot perform, so it genuinely requires
+ * the headless CLI. Returns a structured `hub_cli_not_found` error when the Hub
+ * binary is absent.
+ */
+export declare function setInstallPath(path: string, opts?: {
+    runHubCli?: HubCliRunner;
+}): {
+    success: boolean;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    output: string;
+};
+/**
+ * Signature of the OS URL-opener. The default implementation dispatches per
+ * platform (`open` / `xdg-open` / `start`); tests inject a fake.
+ */
+export type UrlOpener = (url: string) => {
+    opened: boolean;
+    error: string | null;
+};
+/**
+ * Build the `unityhub://` deep link for a release. When a changeset is
+ * available the link is `unityhub://<version>/<changeset>`, which the Hub
+ * resolves to the exact build; without one it is `unityhub://<version>`. Older
+ * Hub versions may ignore a changeset-less link, so the caller should fall back
+ * to the release-notes URL in that case.
+ */
+export declare function buildInstallDeepLink(version: string, changeset?: string | null): string;
+/**
+ * Result of `openInstallDeepLink` — whether the OS handler accepted the link.
+ */
+export interface OpenDeepLinkResult {
+    deepLink: string;
+    opened: boolean;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+}
+/**
+ * Open Unity Hub at its install dialog for `<version>` by firing the
+ * `unityhub://` deep link via the OS URL handler. The Hub must be installed
+ * and registered as the system handler for the scheme. Single-instance, real
+ * progress bar — the install happens inside the Hub, outside this process.
+ * There is no in-app completion detection; the caller should re-list editors
+ * after the Hub finishes.
+ */
+export declare function openInstallDeepLink(version: string, changeset?: string | null, opts?: {
+    openUrl?: UrlOpener;
+}): OpenDeepLinkResult;
+/**
+ * Signature of the archive-page fetcher. The default implementation uses
+ * `node:https`; tests inject a fake that returns a captured HTML fixture.
+ */
+export type ArchiveFetcher = (url: string) => Promise<string>;
+/** Public archive URL — the same source the Hub launcher fetches. */
+export declare const ARCHIVE_URL = "https://unity.com/releases/editor/archive";
+/**
+ * Fetch Unity's public download-archive page and parse the release catalog.
+ * Falls back to the bundled snapshot (with `stale: true`) on any network or
+ * parse failure, so the call never hard-errors — a network outage surfaces as
+ * stale data, not an empty result.
+ */
+export declare function fetchAvailableReleases(opts?: {
+    fetcher?: ArchiveFetcher;
+}): Promise<AvailableReleasesResult>;