macos: add ability for agents to run debug app

macos/AGENTS.md

@@ -9,3 +9,17 @@
   - Build: `build.nu [--scheme Ghostty] [--configuration Debug] [--action build]`
   - Output: `build/<configuration>/Ghostty.app` (e.g. `build/Debug/Ghostty.app`)
 - Run unit tests directly with `build.nu --action test`
+## AppleScript
+
+- The AppleScript scripting definition is in `Ghostty.sdef`.
+- Test AppleScript support:
+  (1) Build with `build.nu`
+  (2) Launch and activate the app via osascript using the absolute path
+      to the built app bundle:
+      `osascript -e 'tell application "<absolute path to build/Debug/Ghostty.app>" to activate'`
+  (3) Wait a few seconds for the app to fully launch and open a terminal.
+  (4) Run test scripts with `osascript`, always targeting the app by
+      its absolute path (not by name) to avoid calling the wrong
+      application.
+  (5) When done, quit via:
+      `osascript -e 'tell application "<absolute path to build/Debug/Ghostty.app>" to quit'`

macos/Ghostty.sdef

@@ -5,6 +5,7 @@
   <suite name="Ghostty Suite" code="Ghst" description="Ghostty scripting support.">
     <class name="application" code="capp" description="The Ghostty application.">
       <cocoa class="NSApplication"/>
+      <responds-to command="perform action"/>
       <element type="terminal" access="r">
         <cocoa key="terminals"/>
       </element>

macos/Sources/Features/AppleScript/AppDelegate+AppleScript.swift

@@ -54,7 +54,7 @@ extension NSApplication {
             return nil
         }
 
-        return terminal.perform(action: action)
+        return NSNumber(value: terminal.perform(action: action))
     }
 
     /// Discovers all currently alive terminal surfaces across normal and quick