unity-open-mcp 0.1.0 → 0.3.0

package/dist/dialog-dismiss.d.ts

@@ -1,42 +1,57 @@
+import { type DialogPolicy, type DialogKind } from "./dialog-policy.js";
 /**
- * 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.
+ * Supported `process.platform` values for the 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.
+ * `dismissed`: a dialog was found AND a click was dispatched successfully.
  *
- * `not-found`: no matching dialog was visible on this poll tick.
+ * `not-found`: no dismissable dialog was visible on this poll tick (either no
+ * modal at all, or a known modal whose policy has no matching button).
  *
- * `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.
+ * `blocked`: a dialog was found that the policy explicitly declines to click
+ * (currently only project_upgrade without the opt-in). The caller logs an
+ * audit line and keeps polling — the dialog is still up and may need a human.
+ *
+ * `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;
+    dialog: DialogKind;
 } | {
     kind: "not-found";
+} | {
+    kind: "blocked";
+    dialog: DialogKind;
+    message: string;
 } | {
     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.
+ * Kept as the M13 T4.5 back-compat export (the launch-errors subset of
+ * {@link DIALOG_TITLE_FRAGMENTS}); the generalized matcher now consults the
+ * full per-kind table via {@link classifyDialogTitle}.
  *
- * Exposed so tests can assert the matcher knows about both spellings without
- * grepping the implementation.
+ * Both legacy and current strings are listed so the matcher stays resilient
+ * across Unity versions. The match is case-insensitive and substring-based.
  */
 export declare const LAUNCH_ERROR_DIALOG_TITLE_FRAGMENTS: readonly string[];
-/** The button label this helper presses to dismiss the dialog. */
+/**
+ * The button label this helper presses to dismiss the launch-errors dialog
+ * under the default (`ignore`) policy. Preserved from M13 T4.5 for back-compat
+ * with tests and any external references; the generalized path now selects
+ * the button via {@link preferenceTokensForPolicy}.
+ */
 export declare const DISMISS_BUTTON_LABEL = "Ignore";
 /**
  * Producer-side prefixes for error messages that callers treat as permanent
@@ -44,59 +59,83 @@ export declare const DISMISS_BUTTON_LABEL = "Ignore";
  * 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";
+export declare const UNSUPPORTED_PLATFORM_PREFIX = "Unsupported platform for Unity startup-dialog auto-dismiss";
+/** Options threaded through every platform probe. */
+export interface DismissProbeOptions {
+    platform: DismissPlatform;
+    policy: DialogPolicy;
+    allowProjectUpgrade: boolean;
+}
 /**
- * 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.
+ * Try once to find and dismiss a Unity startup dialog on the current OS
+ * desktop. Pure-ish — performs OS calls 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.
+ * Platform-dispatched:
+ * - **Windows**: Win32 (`EnumWindows` / `EnumChildWindows` / `GetWindowTextW`
+ *   / `SendMessageW(BM_CLICK)`) via PowerShell — no native node-gyp dep.
+ * - **macOS**: AppleScript via `osascript`. Clicks a named button per the
+ *   policy token table (requires Accessibility perm once).
+ * - **Linux/X11**: `xdotool`. Wayland is unsupported — the error message
+ *   calls this out so the user does not waste time debugging.
  */
-export declare function tryDismissLaunchErrorsDialog(platform?: DismissPlatform): Promise<DismissOutcome>;
+export declare function tryDismissDialog(opts: DismissProbeOptions): 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
+ * The PowerShell payload that probes for any Unity startup dialog and clicks
+ * the policy-selected button. 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
+ *   2. For each, normalize the title (alphanumeric lowercase) and match it
+ *      against the embedded per-kind fragment table to classify it.
+ *   3. If the kind is in the blocked list → emit `blocked:<kind>` and skip
+ *      the click. If the kind's token list is null → skip (not-found).
+ *   4. Walk child windows with `EnumChildWindows`, find a Button whose
+ *      normalized text contains one of the policy tokens (first match wins),
+ *      and send `BM_CLICK` (0x00F5). Preferred over a synthesised mouse event
+ *      — works even if the user is mid-click in another app, no focus steal.
+ *   5. Unknown titles fall back to the generic per-policy token list.
+ *
+ * The script writes a single-token result to stdout (last non-empty line):
+ *   - `dismissed:<button>:<kind>` on success
+ *   - `blocked:<kind>` when a dialog was found but the policy declines
+ *   - `not-found` when no dismissable dialog was matched
  *   - `error:<message>` on an unexpected exception
+ *
+ * The token table is passed via stdin (one JSON blob) so the script body
+ * stays constant and testable; embedding it inline would bloat the assertion.
  */
-export declare const WINDOWS_DISMISS_PS_SCRIPT: string;
+export declare const WINDOWS_DISMISS_PS_SCRIPT = "\n$ErrorActionPreference = 'Stop'\ntry {\n  if (-not ([System.Management.Automation.PSTypeName]'UnityOpenMcp.Dialogs.Dismisser').Type) {\n    Add-Type -TypeDefinition @\"\nusing System;\nusing System.Collections.Generic;\nusing System.Runtime.InteropServices;\nusing System.Text;\nnamespace UnityOpenMcp.Dialogs {\n  public static class Dismisser {\n    public delegate bool EnumWindowsProc(IntPtr hWnd, IntPtr lParam);\n    [DllImport(\"user32.dll\")] static extern bool EnumWindows(EnumWindowsProc lpEnumFunc, IntPtr lParam);\n    [DllImport(\"user32.dll\", CharSet=CharSet.Unicode)] static extern int GetWindowTextW(IntPtr hWnd, StringBuilder lpString, int nMaxCount);\n    [DllImport(\"user32.dll\", CharSet=CharSet.Unicode)] static extern int GetClassNameW(IntPtr hWnd, StringBuilder lpClassName, int nMaxCount);\n    [DllImport(\"user32.dll\")] static extern bool IsWindowVisible(IntPtr hWnd);\n    [DllImport(\"user32.dll\")] static extern bool EnumChildWindows(IntPtr hWndParent, EnumWindowsProc lpEnumFunc, IntPtr lParam);\n    [DllImport(\"user32.dll\")] static extern uint GetWindowThreadProcessId(IntPtr hWnd, out uint lpdwProcessId);\n    [DllImport(\"user32.dll\", CharSet=CharSet.Unicode)] static extern IntPtr SendMessageW(IntPtr hWnd, uint Msg, IntPtr wParam, IntPtr lParam);\n    const uint BM_CLICK = 0x00F5;\n    static string Norm(string s) {\n      var sb = new StringBuilder(s.Length);\n      foreach (var ch in s) {\n        if ((ch >= '0' && ch <= '9') || (ch >= 'A' && ch <= 'Z') || (ch >= 'a' && ch <= 'z')) {\n          sb.Append(char.ToLowerInvariant(ch));\n        }\n      }\n      return sb.ToString();\n    }\n    public static string TryDismiss(int[] unityPids, string tableJson) {\n      var unityPidSet = new HashSet<uint>();\n      for (int i = 0; i < unityPids.Length; i++) unityPidSet.Add((uint)unityPids[i]);\n      var table = System.Text.Json.JsonSerializer.Deserialize<Types.Table>(tableJson);\n      var candidates = new List<IntPtr>();\n      var sb = new StringBuilder(512);\n      EnumWindows((hWnd, lParam) => {\n        if (!IsWindowVisible(hWnd)) return true;\n        uint procId; GetWindowThreadProcessId(hWnd, out procId);\n        if (!unityPidSet.Contains(procId)) return true;\n        sb.Length = 0;\n        GetWindowTextW(hWnd, sb, sb.Capacity);\n        candidates.Add(hWnd);\n        return true;\n      }, IntPtr.Zero);\n      foreach (var hWnd in candidates) {\n        sb.Length = 0;\n        GetWindowTextW(hWnd, sb, sb.Capacity);\n        var title = sb.ToString();\n        var norm = Norm(title);\n        string kind = null;\n        foreach (var kv in table.kinds) {\n          foreach (var frag in kv.Value.fragments) {\n            if (norm.Contains(frag)) { kind = kv.Key; break; }\n          }\n          if (kind != null) break;\n        }\n        string[] tokens = null;\n        if (kind != null) {\n          if (table.blocked.Contains(kind)) return \"blocked:\" + kind;\n          if (!table.kinds[kind].tokensSpecified) continue;\n          tokens = table.kinds[kind].tokens;\n        } else {\n          if (table.genericTokens.Length == 0) continue;\n          tokens = table.genericTokens;\n        }\n        IntPtr matchedButton = IntPtr.Zero;\n        string matchedText = null;\n        EnumChildWindows(hWnd, (hChild, lParam) => {\n          sb.Length = 0;\n          GetClassNameW(hChild, sb, sb.Capacity);\n          if (sb.ToString() != \"Button\") return true;\n          sb.Length = 0;\n          GetWindowTextW(hChild, sb, sb.Capacity);\n          var text = sb.ToString();\n          var textNorm = Norm(text);\n          foreach (var token in tokens) {\n            if (textNorm.Contains(token)) { matchedButton = hChild; matchedText = text; return false; }\n          }\n          return true;\n        }, IntPtr.Zero);\n        if (matchedButton == IntPtr.Zero) continue;\n        SendMessageW(matchedButton, BM_CLICK, IntPtr.Zero, IntPtr.Zero);\n        return \"dismissed:\" + matchedText + \":\" + (kind ?? \"unknown\");\n      }\n      return \"not-found\";\n    }\n  }\n}\n\"@\n  }\n  $unityPids = @(Get-Process -Name 'Unity' -ErrorAction SilentlyContinue | ForEach-Object { [int]$_.Id })\n  if ($unityPids.Count -eq 0) { Write-Output 'not-found'; return }\n  $tableJson = [Console]::In.ReadToEnd();\n  Write-Output ([UnityOpenMcp.Dialogs.Dismisser]::TryDismiss([int[]]$unityPids, $tableJson))\n} catch {\n  Write-Output ('error:' + $_.Exception.Message)\n}\n";
 /**
- * The AppleScript snippet used for the macOS dismiss path. Exposed as a
- * string for testability.
+ * The AppleScript template used for the macOS dismiss path. Exposed as a
+ * function of the token table so tests can assert the script shape without
+ * launching osascript.
  *
- * 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>`.
+ * Strategy: iterate every window of the Unity process, normalize its title,
+ * classify it against the table, and click the first button whose normalized
+ * label contains a policy token. If the kind is blocked, emit `blocked:<kind>`
+ * without clicking. 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.
+ *
+ * The token table is JSON-escaped into the script header.
+ */
+export declare function macosDismissAppleScript(opts: DismissProbeOptions): string;
+/**
+ * Kept for M13 T4.5 back-compat — the original launch-errors-only AppleScript
+ * constant some external tests reference. Delegates to the generalized
+ * template under the default policy.
+ * @deprecated Use {@link macosDismissAppleScript} instead.
  */
-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";
+export declare const MACOS_DISMISS_APPLESCRIPT: string;
 /**
  * Reset the cached `xdotool` presence flag. Test-only — production code
  * never needs to call this.
@@ -116,31 +155,45 @@ export declare function regexEscapeForXdotool(s: string): string;
  * 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)
+ *   - `dismissed:<button>:<kind>` → `{ kind: "dismissed", button, dialog }`
+ *   - `dismissed:<button>`        → back-compat (T4.5) → launch_errors
+ *   - `blocked:<kind>`            → `{ kind: "blocked", dialog, message }`
+ *   - `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 abort)
  */
 export declare function parseDismissOutput(stdout: string): DismissOutcome;
-/** Default dismiss probe timeout — Unity-MCP parity (30s overall budget). */
+/** Default dismiss probe timeout (30s overall budget). */
 export declare const DEFAULT_DISMISS_TIMEOUT_MS = 30000;
-/** Default dismiss probe poll interval — Unity-MCP parity (1.5s tick). */
+/** Default dismiss probe poll interval (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).
+ *     entirely (preserves the pre-T4.5 baseline — no OS clicks). Kept as the
+ *     hard kill-switch for back-compat.
+ *   - `UNITY_OPEN_MCP_DIALOG_POLICY=auto|manual|ignore|recover|safe-mode|cancel`
+ *     selects which button to click per dialog kind (default `ignore`).
+ *     `manual` is equivalent to the kill-switch for the polling loop (no
+ *     clicks) but is reported distinctly in the config so callers can tell
+ *     "operator opted out of all dialogs" from "operator turned the feature
+ *     off entirely".
+ *   - `UNITY_OPEN_MCP_ALLOW_PROJECT_UPGRADE=1` opts in to auto-confirming the
+ *     Project Upgrade Required dialog (irreversible — off by default).
  *   - `UNITY_OPEN_MCP_DISMISS_TIMEOUT_MS` overrides the overall timeout.
  *   - `UNITY_OPEN_MCP_DISMISS_INTERVAL_MS` overrides the poll interval.
  *
+ * `enabled` is true only when the kill-switch is unset AND policy != manual.
  * Pure / no I/O. Exposed for tests.
  */
 export interface DismissConfig {
     enabled: boolean;
     timeoutMs: number;
     intervalMs: number;
+    policy: DialogPolicy;
+    allowProjectUpgrade: boolean;
 }
 export declare function readDismissConfig(env?: NodeJS.ProcessEnv): DismissConfig;
 /**
@@ -152,6 +205,8 @@ export type DismissLog = (line: string) => void;
 export interface PollAndDismissOptions {
     timeoutMs: number;
     intervalMs: number;
+    policy: DialogPolicy;
+    allowProjectUpgrade: boolean;
     /**
      * Override the platform — exposed for tests so the polling logic can be
      * exercised across all three OS branches without hopping process.platform.
@@ -161,37 +216,35 @@ export interface PollAndDismissOptions {
     /**
      * Override the dismiss probe — exposed for tests so the loop can be
      * exercised without invoking PowerShell / osascript / xdotool. Defaults
-     * to `tryDismissLaunchErrorsDialog`.
+     * to `tryDismissDialog`.
      */
-    probe?: typeof tryDismissLaunchErrorsDialog;
+    probe?: typeof tryDismissDialog;
     /**
      * 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.
+     * is no startup 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.
+ * Poll the OS desktop for any Unity startup dialog and click the policy-
+ * selected button 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
+ * Re-entrant dismissals are supported: when a 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.
+ * `blocked` outcomes (project_upgrade without opt-in) are logged once per
+ * occurrence and the loop keeps polling — a human still needs to dismiss that
+ * dialog, and the loop should not exit before the readiness abort fires.
  *
- * 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.
+ * Never throws. Transient platform errors are logged once then suppressed;
+ * permanent errors bail out after the first occurrence so the helper does
+ * not spawn doomed tool invocations on a fixed budget.
  */
-export declare function pollAndDismissLaunchErrors(opts: PollAndDismissOptions): Promise<void>;
+export declare function pollAndDismissDialogs(opts: PollAndDismissOptions): Promise<void>;