unity-open-mcp 0.1.0

package/dist/dialog-dismiss.d.ts

@@ -0,0 +1,197 @@
+/**
+ * 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.
+ *
+ * `not-found`: no matching dialog was visible on this poll tick.
+ *
+ * `error`: an unexpected platform error happened (a required tool was
+ * missing, a syscall failed). The caller logs it 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 references the SAME literal as the producers.
+ */
+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 (`EnumWindows` / `EnumChildWindows` /
+ *   `GetWindowTextW` / `SendMessageW(BM_CLICK)`) driven from PowerShell so
+ *   we do not pull in a native node-gyp dependency.
+ * - **macOS**: AppleScript via `osascript`. Requires Accessibility
+ *   permission for the terminal / `node` binary once.
+ * - **Linux/X11**: `xdotool`. Wayland is deferred — the error message calls
+ *   this out 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` 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. Preferred over a
+ *      synthesised mouse event — it works even if the user is mid-click in
+ *      another app and 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 Unity 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:<msg>`.
+ *
+ * Requires the Terminal / `node` binary to have been granted Accessibility
+ * permission in System Settings → Privacy & Security → Accessibility.
+ */
+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.
+ */
+export declare function _resetXdotoolPresenceForTests(): void;
+/**
+ * Escape a literal string for safe use in `xdotool search --name`. The
+ * argument is interpreted as a regex; without escaping, a future fragment
+ * containing metacharacters would silently change the match semantics.
+ */
+export declare function regexEscapeForXdotool(s: string): string;
+/**
+ * Parse the single-token contract every platform-specific dispatcher writes
+ * to stdout. 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)
+ */
+export declare function parseDismissOutput(stdout: string): DismissOutcome;
+/** Default dismiss probe timeout — Unity-MCP parity (30s overall budget). */
+export declare const DEFAULT_DISMISS_TIMEOUT_MS = 30000;
+/** Default dismiss probe poll interval — Unity-MCP parity (1.5s tick). */
+export declare const DEFAULT_DISMISS_INTERVAL_MS = 1500;
+/**
+ * Resolve the dismiss-feature config from the environment.
+ *
+ *   - `UNITY_OPEN_MCP_NO_AUTO_DISMISS_LAUNCH_ERRORS=1` disables the feature
+ *     entirely (preserves pre-feature behaviour — no OS clicks).
+ *   - `UNITY_OPEN_MCP_DISMISS_TIMEOUT_MS` overrides the overall timeout.
+ *   - `UNITY_OPEN_MCP_DISMISS_INTERVAL_MS` overrides the poll interval.
+ *
+ * Pure / no I/O. Exposed for tests.
+ */
+export interface DismissConfig {
+    enabled: boolean;
+    timeoutMs: number;
+    intervalMs: number;
+}
+export declare function readDismissConfig(env?: NodeJS.ProcessEnv): DismissConfig;
+/**
+ * Sink for per-dismissal audit logging. Default writes to stderr (the MCP
+ * server's stdio transport owns stdout; logs must go to stderr). Abstracted
+ * so tests can capture dismiss events without intercepting process.stderr.
+ */
+export type DismissLog = (line: string) => void;
+export interface PollAndDismissOptions {
+    timeoutMs: number;
+    intervalMs: number;
+    /**
+     * Override the platform — exposed for tests so the polling logic can be
+     * exercised across all three OS branches without hopping process.platform.
+     * Defaults to the running platform.
+     */
+    platform?: DismissPlatform;
+    /**
+     * Override the dismiss probe — exposed for tests so the loop can be
+     * exercised without invoking PowerShell / osascript / xdotool. Defaults
+     * to `tryDismissLaunchErrorsDialog`.
+     */
+    probe?: typeof tryDismissLaunchErrorsDialog;
+    /**
+     * When fired, the loop exits immediately. Intended for callers that have
+     * an authoritative readiness signal in scope (e.g. the parallel compile
+     * wait in LiveClient). The moment the bridge is reachable + idle, there
+     * is no launch-errors dialog left to dismiss, so the loop stops.
+     */
+    abortSignal?: AbortSignal;
+    /** Per-dismissal audit sink. Defaults to stderr. */
+    log?: DismissLog;
+}
+/**
+ * Poll the OS desktop for the Unity launch-errors dialog and click `Ignore`
+ * every time the probe reports it as found. Returns once the abort signal
+ * has fired (authoritative readiness), the overall timeout has elapsed, or
+ * a permanent platform error has been observed.
+ *
+ * Re-entrant dismissals are supported: when the dialog re-appears after a
+ * successful click (resolver-fix → dialog-reappears cycle), each subsequent
+ * dismissal emits its own log line so the recurrence shows in the audit log.
+ *
+ * Never throws. Transient platform errors (a momentary syscall failure) are
+ * logged once and then suppressed; permanent errors bail out after the first
+ * occurrence so the helper does not spawn doomed tool invocations on a fixed
+ * budget.
+ *
+ * The loop keeps polling until aborted even when no dialog appears — unlike
+ * Unity-MCP's standalone `open` CLI, this loop runs CONCURRENTLY with the
+ * LiveClient compile wait. The compile wait's resolution (compiling → idle)
+ * is the authoritative "no more launch dialog" signal and aborts this loop.
+ */
+export declare function pollAndDismissLaunchErrors(opts: PollAndDismissOptions): Promise<void>;