unity-mcp-cli 0.69.1 → 0.71.0

package/dist/lib/types.d.ts

@@ -15,6 +15,40 @@ export type ProgressEvent = {
     phase: 'dependencies-resolved';
     message: string;
     version: string;
+} | {
+    phase: 'detecting-editor-version';
+    message: string;
+} | {
+    phase: 'editors-located';
+    message: string;
+    found: boolean;
+} | {
+    phase: 'editor-resolved';
+    message: string;
+    editorPath: string;
+    version?: string;
+} | {
+    phase: 'connection-details';
+    message: string;
+    projectPath: string;
+    editorPath: string;
+    envVars: Record<string, string>;
+} | {
+    phase: 'launching-editor';
+    message: string;
+    editorPath: string;
+    projectPath: string;
+} | {
+    phase: 'editor-launched';
+    message: string;
+    pid?: number;
+} | {
+    phase: 'launch-errors-dismissed';
+    message: string;
+    /** Button label that was clicked (e.g. `Ignore`). */
+    button: string;
+    /** Platform on which the dismiss was performed (`win32` | `darwin` | `linux`). */
+    platform: string;
 } | {
     phase: 'done';
     message: string;
@@ -185,3 +219,160 @@ export interface SetupMcpFailure {
     error: Error;
 }
 export type SetupMcpResult = SetupMcpSuccess | SetupMcpFailure;
+/** Auth option propagated to the Editor as `UNITY_MCP_AUTH_OPTION`. */
+export type OpenProjectAuthOption = 'none' | 'required';
+/** Transport propagated to the Editor as `UNITY_MCP_TRANSPORT`. */
+export type OpenProjectTransport = 'streamableHttp' | 'stdio';
+export interface OpenProjectOptions {
+    /**
+     * Path to the Unity project to open. Absolute or relative; defaults
+     * to `process.cwd()` if omitted.
+     */
+    projectPath?: string;
+    /** Specific Unity Editor version to use (e.g. `"2022.3.62f3"`). */
+    unityVersion?: string;
+    /**
+     * If `true`, skip wiring the MCP connection environment variables
+     * onto the spawned editor process. Mirrors the CLI's `--no-connect`
+     * flag semantics. Defaults to `false`.
+     */
+    noConnect?: boolean;
+    /** MCP server URL — sets `UNITY_MCP_HOST` on the editor process. */
+    url?: string;
+    /** Auth token — sets `UNITY_MCP_TOKEN` on the editor process. */
+    token?: string;
+    /** Auth option — sets `UNITY_MCP_AUTH_OPTION` on the editor process. */
+    auth?: OpenProjectAuthOption;
+    /** Comma-separated list of tool names — sets `UNITY_MCP_TOOLS`. */
+    tools?: string;
+    /**
+     * If `true`, sets `UNITY_MCP_KEEP_CONNECTED=true`. Auto-enabled by
+     * Cloud-mode auto-detection when a `cloudToken` is present in the
+     * project's config.
+     */
+    keepConnected?: boolean;
+    /** Transport — sets `UNITY_MCP_TRANSPORT`. */
+    transport?: OpenProjectTransport;
+    /**
+     * If set, sets `UNITY_MCP_START_SERVER=true|false`. Use a boolean to
+     * avoid the CLI's stringly-typed `"true"`/`"false"` parse step.
+     */
+    startServer?: boolean;
+    /**
+     * If `true` (the default), poll for the Unity Editor's
+     * "compile errors at launch" dialog after the editor process has
+     * been spawned and click `Ignore` (or the platform-equivalent
+     * button) so the editor finishes initialising. Set to `false` to
+     * disable the polling loop entirely — corresponds to the CLI's
+     * `--no-auto-dismiss-launch-errors` flag.
+     *
+     * The polling loop runs concurrently with the existing wait-for-
+     * ready logic (which is the authoritative ready signal); when no
+     * dialog appears, behaviour is unchanged from the pre-feature
+     * baseline (no spurious clicks, no extra delay).
+     */
+    autoDismissLaunchErrors?: boolean;
+    /**
+     * Overall timeout (milliseconds) for the launch-errors dismissal
+     * polling loop. The loop ticks every
+     * `launchDismissPollIntervalMs` until either the dialog is
+     * dismissed, this timeout elapses, or `openProject` returns. Default
+     * `30000` (30 s).
+     */
+    launchDismissTimeoutMs?: number;
+    /**
+     * Polling tick interval (milliseconds) for the launch-errors
+     * dismissal loop. Default `1500`.
+     */
+    launchDismissPollIntervalMs?: number;
+    /**
+     * Optional abort signal that, when fired, stops the launch-errors
+     * dismissal polling loop early. Intended for callers that have an
+     * authoritative "Unity is ready" signal in scope (e.g. a parallel
+     * `wait-for-ready` poll) so the dismissal loop does not keep
+     * ticking after Unity has finished initialising.
+     *
+     * When omitted, the loop falls back to a grace window after the
+     * editor process is spawned: if no dialog has been observed within
+     * ~15s of polling, the loop exits early on the assumption that the
+     * dialog is not going to appear for this launch. The grace window
+     * has to cover Unity's full startup phase (process spawn → Package
+     * Manager connect → first compile pass) because the launch-errors
+     * dialog (`"Enter Safe Mode?"` on Unity 2020.2+) appears at the end
+     * of that phase, not the start of it (issue #737).
+     */
+    launchDismissAbortSignal?: AbortSignal;
+    /**
+     * Optional progress callback — fires for `start`,
+     * `detecting-editor-version`, `editors-located`, `editor-resolved`,
+     * `connection-details`, `launching-editor`, `editor-launched`,
+     * `launch-errors-dismissed` (only when a dialog was actually
+     * dismissed), and `done`.
+     */
+    onProgress?: ProgressCallback;
+}
+/** Successful `openProject` outcome. Narrow with `kind === 'success'`. */
+export interface OpenProjectSuccess {
+    kind: 'success';
+    /** Always `true` for the success variant. */
+    success: true;
+    /** Absolute path to the Unity Editor binary that was launched. */
+    editorPath: string;
+    /**
+     * PID of the spawned editor process. May be `undefined` if the OS
+     * has not yet reported a PID by the time the call returns (rare;
+     * the value is captured asynchronously from the child process's
+     * `spawn` event).
+     */
+    editorPid?: number;
+    /** Editor version string used (e.g. `"2022.3.62f3"`), if known. */
+    unityVersion?: string;
+    /** Resolved absolute project path. */
+    projectPath: string;
+    /** Non-fatal warnings collected during the run. */
+    warnings: string[];
+    /**
+     * `true` when an existing Unity Editor process was already running
+     * with this project and a launch was therefore skipped. The
+     * `editorPid` will be the existing process's PID in that case.
+     */
+    alreadyRunning?: boolean;
+}
+/** Failed `openProject` outcome. Narrow with `kind === 'failure'`. */
+export interface OpenProjectFailure {
+    kind: 'failure';
+    /** Always `false` for the failure variant. */
+    success: false;
+    /** Resolved absolute project path, if it could be determined. */
+    projectPath?: string;
+    /** Editor path, if locating the editor succeeded. */
+    editorPath?: string;
+    /** Editor version, if it could be detected before failure. */
+    unityVersion?: string;
+    /** Non-fatal warnings collected before the failure. */
+    warnings: string[];
+    /** Human-readable error message — never thrown past the public boundary. */
+    errorMessage: string;
+    /** The captured error. */
+    error: Error;
+}
+export type OpenProjectResult = OpenProjectSuccess | OpenProjectFailure;
+/**
+ * Subset of `OpenProjectOptions` consumed by `buildOpenEnv` — every
+ * field on this interface is potentially mapped to a `UNITY_MCP_*`
+ * environment variable. Declared as a dedicated interface (rather
+ * than a `Pick<OpenProjectOptions, …>` re-listed inline) so adding a
+ * new env-bearing option to `OpenProjectOptions` is a one-step change
+ * here that `buildOpenEnv` picks up by signature, with no risk of the
+ * Pick list silently drifting.
+ */
+export interface OpenEnvInputs {
+    noConnect?: OpenProjectOptions['noConnect'];
+    url?: OpenProjectOptions['url'];
+    token?: OpenProjectOptions['token'];
+    auth?: OpenProjectOptions['auth'];
+    tools?: OpenProjectOptions['tools'];
+    keepConnected?: OpenProjectOptions['keepConnected'];
+    transport?: OpenProjectOptions['transport'];
+    startServer?: OpenProjectOptions['startServer'];
+}

package/dist/lib.d.ts

@@ -2,4 +2,5 @@ export { installPlugin } from './lib/install-plugin.js';
 export { removePlugin } from './lib/remove-plugin.js';
 export { configure } from './lib/configure.js';
 export { setupMcp, listAgentIds } from './lib/setup-mcp.js';
-export type { ProgressEvent, ProgressCallback, ResultKind, InstallPluginOptions, InstallResult, InstallSuccess, InstallFailure, RemovePluginOptions, RemoveResult, RemoveSuccess, RemoveFailure, ConfigureOptions, ConfigureResult, ConfigureSuccess, ConfigureFailure, ConfigureSnapshot, FeatureAction, McpFeatureSnapshot, SetupMcpOptions, SetupMcpResult, SetupMcpSuccess, SetupMcpFailure, McpTransport, } from './lib/types.js';
+export { openProject } from './lib/open.js';
+export type { ProgressEvent, ProgressCallback, ResultKind, InstallPluginOptions, InstallResult, InstallSuccess, InstallFailure, RemovePluginOptions, RemoveResult, RemoveSuccess, RemoveFailure, ConfigureOptions, ConfigureResult, ConfigureSuccess, ConfigureFailure, ConfigureSnapshot, FeatureAction, McpFeatureSnapshot, SetupMcpOptions, SetupMcpResult, SetupMcpSuccess, SetupMcpFailure, McpTransport, OpenProjectOptions, OpenProjectResult, OpenProjectSuccess, OpenProjectFailure, OpenProjectAuthOption, OpenProjectTransport, } from './lib/types.js';

package/dist/lib.js

@@ -19,4 +19,5 @@ export { installPlugin } from './lib/install-plugin.js';
 export { removePlugin } from './lib/remove-plugin.js';
 export { configure } from './lib/configure.js';
 export { setupMcp, listAgentIds } from './lib/setup-mcp.js';
+export { openProject } from './lib/open.js';
 //# sourceMappingURL=lib.js.map

package/dist/lib.js.map

@@ -1 +1 @@
-{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,EAAE;AACF,qDAAqD;AACrD,iEAAiE;AACjE,sEAAsE;AACtE,oDAAoD;AACpD,yEAAyE;AACzE,0EAA0E;AAC1E,0EAA0E;AAC1E,uEAAuE;AACvE,uEAAuE;AACvE,iEAAiE;AACjE,oEAAoE;AACpE,2BAA2B;AAC3B,EAAE;AACF,sEAAsE;AACtE,sDAAsD;AAEtD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,EAAE;AACF,qDAAqD;AACrD,iEAAiE;AACjE,sEAAsE;AACtE,oDAAoD;AACpD,yEAAyE;AACzE,0EAA0E;AAC1E,0EAA0E;AAC1E,uEAAuE;AACvE,uEAAuE;AACvE,iEAAiE;AACjE,oEAAoE;AACpE,2BAA2B;AAC3B,EAAE;AACF,sEAAsE;AACtE,sDAAsD;AAEtD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/utils/launch-error-dismiss.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Supported `process.platform` values for the launch-errors dialog
+ * dismiss helper. Narrowed alias of NodeJS.Platform — keeps the
+ * platform-dispatch table exhaustive in tests without forcing callers
+ * to import a Node-internal type.
+ */
+export type DismissPlatform = 'win32' | 'darwin' | 'linux';
+/**
+ * Outcome of a single dismiss attempt against the running OS desktop.
+ *
+ * `dismissed`: the dialog was found AND a click was dispatched
+ * successfully. The polling loop should stop and return.
+ *
+ * `not-found`: no matching dialog was visible on this poll tick. The
+ * polling loop should continue ticking until either the overall
+ * timeout elapses or Unity reports ready (the existing wait-for-ready
+ * logic, which runs in parallel, is the authoritative ready signal).
+ *
+ * `error`: an unexpected platform error happened (a required tool was
+ * missing, a syscall failed). The polling loop logs the error once
+ * and continues with `not-found` semantics — the dialog may simply
+ * not be open yet, and a single transient error must not abort the
+ * whole launch flow.
+ */
+export type DismissOutcome = {
+    kind: 'dismissed';
+    button: string;
+} | {
+    kind: 'not-found';
+} | {
+    kind: 'error';
+    message: string;
+};
+/**
+ * Window-title fragments matched against the Unity launch-errors
+ * dialog. Both legacy and current strings are listed so the matcher
+ * stays resilient across Unity versions. The match is case-insensitive
+ * and substring-based — Unity's actual title varies by version but
+ * always contains one of these.
+ *
+ * Exposed so tests can assert the matcher knows about both spellings
+ * without grepping the implementation.
+ */
+export declare const LAUNCH_ERROR_DIALOG_TITLE_FRAGMENTS: readonly string[];
+/** The button label this helper presses to dismiss the dialog. */
+export declare const DISMISS_BUTTON_LABEL = "Ignore";
+/**
+ * Producer-side prefixes for error messages that callers treat as
+ * permanent (the polling loop bails out instead of ticking again).
+ *
+ * Exported so the bailout matcher in `lib/open.ts` and the
+ * error-construction sites below reference the SAME literal — a
+ * future re-word lands in both places at once.
+ *
+ * The matcher in `lib/open.ts` uses `String.includes`, so each
+ * constant just needs to be a stable substring of the full message.
+ */
+export declare const LINUX_XDOTOOL_MISSING_PREFIX = "xdotool not found on PATH";
+export declare const UNSUPPORTED_PLATFORM_PREFIX = "Unsupported platform for launch-errors auto-dismiss";
+/**
+ * Try once to find and dismiss the Unity launch-errors dialog on the
+ * current OS desktop. Pure-ish — performs a single OS call and
+ * returns; never blocks past the underlying syscall's own timeout.
+ *
+ * Library-safe: never throws (errors are returned in the
+ * `DismissOutcome` union), never writes to stdout/stderr, never
+ * mutates global state.
+ *
+ * The helper is platform-dispatched:
+ * - **Windows**: Win32 (`FindWindowW` / `EnumWindows` /
+ *   `EnumChildWindows` / `GetWindowTextW` / `SendMessageW(BM_CLICK)`)
+ *   driven from PowerShell so we do not pull in a native node-gyp
+ *   dependency. UI Automation is the documented fallback if title
+ *   matching breaks on a future Unity release.
+ * - **macOS**: AppleScript via `osascript` (the leaner
+ *   AX-C-API-direct path is a documented follow-up). Requires the
+ *   user to have granted Accessibility permission to the terminal /
+ *   `unity-mcp-cli` binary once.
+ * - **Linux/X11**: `xdotool` (documented as a Linux platform
+ *   dependency; `wmctrl` is acceptable as an alternative window
+ *   enumerator). Wayland is deferred — call out explicitly in the
+ *   error message so the user does not waste time debugging.
+ */
+export declare function tryDismissLaunchErrorsDialog(platform?: DismissPlatform): Promise<DismissOutcome>;
+/**
+ * The PowerShell payload that probes for the Unity launch-errors
+ * dialog and clicks `Ignore` if found. Exported as a string (not a
+ * function) so tests can assert the script shape without launching
+ * PowerShell.
+ *
+ * Strategy:
+ *   1. P/Invoke `EnumWindows` via Add-Type to enumerate every visible
+ *      top-level window owned by `Unity.exe`.
+ *   2. Filter by title fragment (case-insensitive substring).
+ *   3. Walk child windows with `EnumChildWindows`, looking for a
+ *      Button whose text equals `Ignore`.
+ *   4. Send `BM_CLICK` (0x00F5) to the matched button. `BM_CLICK` is
+ *      preferred over a synthesised mouse event — it works even if
+ *      the user is mid-click in another app, and it does not steal
+ *      focus.
+ *
+ * The script writes a single-token result to stdout:
+ *   - `dismissed:<button>` on success
+ *   - `not-found` when no dialog was matched
+ *   - `error:<message>` on an unexpected exception
+ */
+export declare const WINDOWS_DISMISS_PS_SCRIPT: string;
+/**
+ * The AppleScript snippet used for the macOS dismiss path. Exposed as
+ * a string for testability.
+ *
+ * Strategy: iterate every window of the Unity application process and
+ * click the first button titled `Ignore`. If the Unity process is not
+ * running OR no matching button exists, the script reports
+ * `not-found`. Any AppleScript exception (e.g. Accessibility
+ * permission not granted) is reported as `error:<message>` so the
+ * caller can surface it once and continue polling.
+ *
+ * Requires the Terminal / `unity-mcp-cli` binary to have been granted
+ * Accessibility permission in System Settings → Privacy & Security →
+ * Accessibility. Documented in the README.
+ */
+export declare const MACOS_DISMISS_APPLESCRIPT = "\non run\n  try\n    tell application \"System Events\"\n      if not (exists process \"Unity\") then\n        return \"not-found\"\n      end if\n      tell process \"Unity\"\n        repeat with w in windows\n          try\n            if exists (button \"Ignore\" of w) then\n              click button \"Ignore\" of w\n              return \"dismissed:Ignore\"\n            end if\n          end try\n        end repeat\n      end tell\n    end tell\n    return \"not-found\"\n  on error errMsg\n    return \"error:\" & errMsg\n  end try\nend run\n";
+/**
+ * Reset the cached `xdotool` presence flag. Test-only — production
+ * code never needs to call this. Exposed so tests can simulate "the
+ * tool was installed mid-process" without affecting other tests.
+ */
+export declare function _resetXdotoolPresenceForTests(): void;
+/**
+ * Escape a literal string for safe use in `xdotool search --name`.
+ * `xdotool search --name` interprets its argument as a regex; without
+ * escaping, a future fragment containing metacharacters (e.g.
+ * `(Hold On)` or `Compiler Errors v2.0+`) would silently change the
+ * match semantics. The current fragments are regex-safe but this
+ * helper is defensive and zero-runtime-cost.
+ *
+ * Exposed for tests so the regex-safety contract is locked down.
+ */
+export declare function regexEscapeForXdotool(s: string): string;
+/**
+ * Parse the single-token contract every platform-specific dispatcher
+ * writes to stdout. Exposed for tests so we can exhaustively cover
+ * the parser without invoking PowerShell / osascript / xdotool.
+ *
+ * Inspects the LAST non-empty line of stdout, not the whole buffer:
+ * a stray PowerShell warning, `osascript` deprecation notice, or
+ * `xdotool` chatter printed before the contract token must not
+ * misclassify the result as `not-found`.
+ *
+ * Contract:
+ *   - `dismissed:<button>` → `{ kind: 'dismissed', button }`
+ *   - `not-found`          → `{ kind: 'not-found' }`
+ *   - `error:<message>`    → `{ kind: 'error', message }`
+ *   - any other / empty    → `{ kind: 'not-found' }` (defensive — a
+ *     transient parse miss is treated as "not yet visible" rather
+ *     than aborting the polling loop)
+ */
+export declare function parseDismissOutput(stdout: string): DismissOutcome;