@ebowwa/osascript 1.1.0

package/src/index.ts

@@ -0,0 +1,844 @@
+/**
+ * @fileoverview osascript MCP - macOS automation via AppleScript/JXA
+ *
+ * Provides programmatic access to macOS automation through osascript.
+ * Supports AppleScript and JavaScript for Automation (JXA).
+ */
+
+import { spawn } from "child_process";
+
+import type {
+  OsascriptResult,
+  ExecuteOptions,
+  DialogOptions,
+  DialogResult,
+  NotificationOptions,
+  WindowInfo,
+  ApplicationInfo,
+  KeystrokeOptions,
+  KeyCodeOptions,
+  VolumeInfo,
+  DisplayInfo,
+  FinderItem,
+  ScriptLanguage,
+} from "./types.js";
+
+export type {
+  OsascriptResult,
+  ExecuteOptions,
+  DialogOptions,
+  DialogResult,
+  NotificationOptions,
+  WindowInfo,
+  ApplicationInfo,
+  KeystrokeOptions,
+  KeyCodeOptions,
+  VolumeInfo,
+  DisplayInfo,
+  FinderItem,
+  ScriptLanguage,
+};
+
+// ==============
+// Core Executor
+// ==============
+
+/**
+ * Execute osascript command
+ */
+export async function executeOsascript(
+  script: string,
+  options: ExecuteOptions = {}
+): Promise<OsascriptResult> {
+  const { language = "applescript", timeout = 30000 } = options;
+
+  const args: string[] = [];
+  if (language === "javascript") {
+    args.push("-l", "JavaScript");
+  }
+  args.push("-e", script);
+
+  return new Promise((resolve) => {
+    const proc = spawn("osascript", args, { timeout });
+    let stdout = "";
+    let stderr = "";
+
+    proc.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+
+    proc.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+
+    const timer = setTimeout(() => {
+      proc.kill();
+      resolve({
+        success: false,
+        stdout: stdout.trim(),
+        stderr: "Timeout exceeded",
+        exitCode: 1,
+      });
+    }, timeout);
+
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({
+        success: code === 0,
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        exitCode: code ?? 1,
+      });
+    });
+
+    proc.on("error", (error) => {
+      clearTimeout(timer);
+      resolve({
+        success: false,
+        stdout: "",
+        stderr: error.message,
+        exitCode: 1,
+      });
+    });
+  });
+}
+
+/**
+ * Execute AppleScript
+ */
+export async function executeAppleScript(script: string, timeout = 30000): Promise<OsascriptResult> {
+  return executeOsascript(script, { language: "applescript", timeout });
+}
+
+/**
+ * Execute JavaScript for Automation (JXA)
+ */
+export async function executeJXA(script: string, timeout = 30000): Promise<OsascriptResult> {
+  return executeOsascript(script, { language: "javascript", timeout });
+}
+
+// ==============
+// System Operations
+// ==============
+
+/**
+ * Display a macOS notification
+ */
+export async function displayNotification(options: NotificationOptions): Promise<OsascriptResult> {
+  const { title = "Notification", subtitle, message, soundName } = options;
+
+  let script = `display notification "${escapeString(message)}"`;
+  if (title) script += ` with title "${escapeString(title)}"`;
+  if (subtitle) script += ` subtitle "${escapeString(subtitle)}"`;
+  if (soundName) script += ` sound name "${escapeString(soundName)}"`;
+
+  return executeAppleScript(script);
+}
+
+/**
+ * Display a dialog
+ */
+export async function displayDialog(options: DialogOptions): Promise<DialogResult> {
+  const { title, message, buttons = ["OK"], defaultButton = 1, icon, givingUpAfter } = options;
+
+  let script = `display dialog "${escapeString(message)}"`;
+  script += ` buttons ${JSON.stringify(buttons)}`;
+  script += ` default button ${defaultButton}`;
+  if (icon) script += ` with icon ${icon}`;
+  if (givingUpAfter) script += ` giving up after ${givingUpAfter}`;
+
+  const result = await executeAppleScript(script);
+
+  if (!result.success) {
+    throw new Error(`Dialog failed: ${result.stderr}`);
+  }
+
+  // Parse result: "button returned:OK" or "button returned:OK, gave up:true"
+  const buttonMatch = result.stdout.match(/button returned:(\w+)/);
+  const gaveUpMatch = result.stdout.match(/gave up:(\w+)/);
+
+  return {
+    buttonReturned: buttonMatch ? buttonMatch[1] : buttons[0],
+    gaveUp: gaveUpMatch ? gaveUpMatch[1] === "true" : false,
+  };
+}
+
+/**
+ * Get system volume
+ */
+export async function getVolume(): Promise<VolumeInfo> {
+  const script = `
+    output volume of (get volume settings) as integer
+  `;
+
+  const volumeResult = await executeAppleScript(script);
+  const mutedScript = `
+    output muted of (get volume settings) as boolean
+  `;
+  const mutedResult = await executeAppleScript(mutedScript);
+
+  return {
+    volume: parseInt(volumeResult.stdout) || 0,
+    muted: mutedResult.stdout.toLowerCase() === "true",
+  };
+}
+
+/**
+ * Set system volume (0-100)
+ */
+export async function setVolume(volume: number, muted?: boolean): Promise<OsascriptResult> {
+  const safeVolume = Math.max(0, Math.min(100, Math.round(volume)));
+  let script = `set volume output volume ${safeVolume}`;
+  if (muted !== undefined) {
+    script += muted ? " with output muted" : " without output muted";
+  }
+  return executeAppleScript(script);
+}
+
+/**
+ * Get clipboard contents
+ */
+export async function getClipboard(): Promise<string> {
+  const result = await executeAppleScript("the clipboard");
+  if (!result.success) {
+    throw new Error(`Failed to get clipboard: ${result.stderr}`);
+  }
+  return result.stdout;
+}
+
+/**
+ * Set clipboard contents
+ */
+export async function setClipboard(text: string): Promise<OsascriptResult> {
+  const script = `set the clipboard to "${escapeString(text)}"`;
+  return executeAppleScript(script);
+}
+
+/**
+ * Clear clipboard
+ */
+export async function clearClipboard(): Promise<OsascriptResult> {
+  return executeAppleScript("set the clipboard to \"\"");
+}
+
+// ==============
+// Application Control
+// ==============
+
+/**
+ * List running applications
+ */
+export async function listRunningApplications(): Promise<ApplicationInfo[]> {
+  const script = `
+    tell application "System Events"
+      set appList to name of every process whose background only is false
+      set output to ""
+      repeat with appName in appList
+        set output to output & appName & linefeed
+      end repeat
+      return output
+    end tell
+  `;
+
+  const result = await executeAppleScript(script);
+  if (!result.success) {
+    throw new Error(`Failed to list applications: ${result.stderr}`);
+  }
+
+  const apps = result.stdout
+    .split("\n")
+    .filter((name) => name.trim())
+    .map((name) => ({
+      name: name.trim(),
+      running: true,
+    }));
+
+  return apps;
+}
+
+/**
+ * Get detailed application info
+ */
+export async function getApplicationInfo(appName: string): Promise<ApplicationInfo> {
+  const script = `
+    tell application "System Events"
+      if exists process "${escapeString(appName)}" then
+        set theProcess to process "${escapeString(appName)}"
+        set theName to name of theProcess
+        set thePath to POSIX path of (application file of theProcess as alias)
+        set thePID to unix id of theProcess
+        set windowCount to count of windows of theProcess
+        return theName & "|" & thePath & "|" & thePID & "|" & windowCount
+      else
+        return "NOT_RUNNING"
+      end if
+    end tell
+  `;
+
+  const result = await executeAppleScript(script);
+  if (!result.success || result.stdout === "NOT_RUNNING") {
+    return {
+      name: appName,
+      running: false,
+    };
+  }
+
+  const [name, path, pid, windowCount] = result.stdout.split("|");
+
+  return {
+    name,
+    path,
+    processId: parseInt(pid),
+    running: true,
+    windowCount: parseInt(windowCount),
+  };
+}
+
+/**
+ * Activate (bring to front) an application
+ */
+export async function activateApplication(appName: string): Promise<OsascriptResult> {
+  const script = `
+    tell application "${escapeString(appName)}"
+      activate
+    end tell
+  `;
+  return executeAppleScript(script);
+}
+
+/**
+ * Quit an application
+ */
+export async function quitApplication(appName: string, force = false): Promise<OsascriptResult> {
+  let script: string;
+  if (force) {
+    script = `
+      tell application "System Events"
+        set theProcess to process "${escapeString(appName)}"
+        set thePID to unix id of theProcess
+        do shell script "kill -9 " & thePID
+      end tell
+    `;
+  } else {
+    script = `
+      tell application "${escapeString(appName)}"
+        quit
+      end tell
+    `;
+  }
+  return executeAppleScript(script);
+}
+
+/**
+ * Launch an application
+ */
+export async function launchApplication(appName: string): Promise<OsascriptResult> {
+  const script = `
+    tell application "${escapeString(appName)}"
+      launch
+    end tell
+  `;
+  return executeAppleScript(script);
+}
+
+/**
+ * Get frontmost application name
+ */
+export async function getFrontmostApplication(): Promise<string> {
+  const script = `
+    tell application "System Events"
+      name of first process whose frontmost is true
+    end tell
+  `;
+
+  const result = await executeAppleScript(script);
+  if (!result.success) {
+    throw new Error(`Failed to get frontmost app: ${result.stderr}`);
+  }
+  return result.stdout;
+}
+
+// ==============
+// Window Management
+// ==============
+
+/**
+ * Get window list for an application
+ */
+export async function getApplicationWindows(appName: string): Promise<WindowInfo[]> {
+  const script = `
+    tell application "System Events"
+      tell process "${escapeString(appName)}"
+        set windowList to {}
+        repeat with theWindow in windows
+          set windowName to name of theWindow
+          set windowId to id of theWindow
+          set windowIndex to index of theWindow
+          set end of windowList to windowName & "|" & windowId & "|" & windowIndex
+        end repeat
+        return windowList as text
+      end tell
+    end tell
+  `;
+
+  const result = await executeAppleScript(script);
+  if (!result.success) {
+    return [];
+  }
+
+  if (!result.stdout.trim()) {
+    return [];
+  }
+
+  const windows = result.stdout
+    .split(", ")
+    .filter((w) => w.trim())
+    .map((w) => {
+      const [name, id, index] = w.split("|");
+      return {
+        name: name || null,
+        id: parseInt(id) || 0,
+        index: parseInt(index) || 0,
+      };
+    });
+
+  return windows;
+}
+
+/**
+ * Set window bounds (position and size)
+ */
+export async function setWindowBounds(
+  appName: string,
+  windowIndex: number,
+  bounds: { x: number; y: number; width: number; height: number }
+): Promise<OsascriptResult> {
+  const script = `
+    tell application "System Events"
+      tell process "${escapeString(appName)}"
+        set position of window ${windowIndex} to {${bounds.x}, ${bounds.y}}
+        set size of window ${windowIndex} to {${bounds.width}, ${bounds.height}}
+      end tell
+    end tell
+  `;
+  return executeAppleScript(script);
+}
+
+/**
+ * Minimize window
+ */
+export async function minimizeWindow(
+  appName: string,
+  windowIndex: number
+): Promise<OsascriptResult> {
+  const script = `
+    tell application "System Events"
+      tell process "${escapeString(appName)}"
+        set value of attribute "AXMinimized" of window ${windowIndex} to true
+      end tell
+    end tell
+  `;
+  return executeAppleScript(script);
+}
+
+// ==============
+// Keyboard Input
+// ==============
+
+/**
+ * Send keystroke (text input)
+ */
+export async function sendKeystroke(options: KeystrokeOptions): Promise<OsascriptResult> {
+  const { key, modifiers = [], delay = 0 } = options;
+
+  const modifierStr = modifiers.map((m) => m + " down").join(", ");
+  const usingStr = modifierStr ? ` using {${modifierStr}}` : "";
+
+  const script = `
+    tell application "System Events"
+      keystroke "${escapeString(key)}"${usingStr}
+      ${delay > 0 ? `delay ${delay}` : ""}
+    end tell
+  `;
+
+  return executeAppleScript(script);
+}
+
+/**
+ * Send key code (for special keys)
+ */
+export async function sendKeyCode(options: KeyCodeOptions): Promise<OsascriptResult> {
+  const { keyCode, modifiers = [] } = options;
+
+  const modifierStr = modifiers.map((m) => m + " down").join(", ");
+  const usingStr = modifierStr ? ` using {${modifierStr}}` : "";
+
+  const script = `
+    tell application "System Events"
+      key code ${keyCode}${usingStr}
+    end tell
+  `;
+
+  return executeAppleScript(script);
+}
+
+/**
+ * Type text (simulate typing)
+ */
+export async function typeText(text: string, delayBetweenChars = 0.01): Promise<OsascriptResult> {
+  const script = `
+    tell application "System Events"
+      keystroke "${escapeString(text)}"
+      ${delayBetweenChars > 0 ? `delay ${delayBetweenChars}` : ""}
+    end tell
+  `;
+
+  return executeAppleScript(script);
+}
+
+/**
+ * Press key combination (e.g., Command+C)
+ */
+export async function pressKeyCombination(
+  key: string,
+  modifiers: ("command" | "shift" | "option" | "control")[]
+): Promise<OsascriptResult> {
+  return sendKeystroke({ key, modifiers });
+}
+
+// Common key codes
+export const KeyCodes = {
+  RETURN: 36,
+  TAB: 48,
+  SPACE: 49,
+  DELETE: 51,
+  ESCAPE: 53,
+  LEFT_ARROW: 123,
+  RIGHT_ARROW: 124,
+  DOWN_ARROW: 125,
+  UP_ARROW: 126,
+  F1: 122,
+  F2: 120,
+  F3: 99,
+  F4: 118,
+  F5: 96,
+  F6: 97,
+  F7: 98,
+  F8: 100,
+  F9: 101,
+  F10: 109,
+  F11: 103,
+  F12: 111,
+  HOME: 115,
+  END: 119,
+  PAGE_UP: 116,
+  PAGE_DOWN: 121,
+} as const;
+
+// ==============
+// Safari
+// ==============
+
+/**
+ * Get current Safari URL
+ */
+export async function getSafariURL(): Promise<string> {
+  const script = `
+    tell application "Safari"
+      return URL of current tab of front window
+    end tell
+  `;
+
+  const result = await executeAppleScript(script);
+  if (!result.success) {
+    throw new Error(`Failed to get Safari URL: ${result.stderr}`);
+  }
+  return result.stdout;
+}
+
+/**
+ * Set Safari URL (navigate)
+ */
+export async function setSafariURL(url: string): Promise<OsascriptResult> {
+  const script = `
+    tell application "Safari"
+      set URL of current tab of front window to "${escapeString(url)}"
+    end tell
+  `;
+  return executeAppleScript(script);
+}
+
+/**
+ * Get Safari tab titles
+ */
+export async function getSafariTabTitles(): Promise<string[]> {
+  const script = `
+    tell application "Safari"
+      set tabTitles to name of every tab of front window
+      return tabTitles as text
+    end tell
+  `;
+
+  const result = await executeAppleScript(script);
+  if (!result.success) {
+    return [];
+  }
+
+  return result.stdout.split(", ").filter((t) => t.trim());
+}
+
+/**
+ * Execute JavaScript in Safari
+ */
+export async function executeSafariJS(jsCode: string): Promise<string> {
+  const script = `
+    tell application "Safari"
+      do JavaScript "${escapeString(jsCode)}" in current tab of front window
+    end tell
+  `;
+
+  const result = await executeAppleScript(script);
+  if (!result.success) {
+    throw new Error(`Failed to execute Safari JS: ${result.stderr}`);
+  }
+  return result.stdout;
+}
+
+// ==============
+// Finder
+// ==============
+
+/**
+ * Get Finder selection
+ */
+export async function getFinderSelection(): Promise<FinderItem[]> {
+  const script = `
+    tell application "Finder"
+      set selectedItems to selection
+      set output to ""
+      repeat with theItem in selectedItems
+        set itemName to name of theItem
+        set itemPath to POSIX path of (theItem as alias)
+        set itemKind to kind of theItem
+        set output to output & itemName & "|" & itemPath & "|" & itemKind & linefeed
+      end repeat
+      return output
+    end tell
+  `;
+
+  const result = await executeAppleScript(script);
+  if (!result.success || !result.stdout.trim()) {
+    return [];
+  }
+
+  return result.stdout
+    .split("\n")
+    .filter((line) => line.trim())
+    .map((line) => {
+      const [name, path, kind] = line.split("|");
+      const type = kind?.toLowerCase().includes("folder")
+        ? "folder"
+        : kind?.toLowerCase().includes("application")
+          ? "application"
+          : "file";
+
+      return {
+        name,
+        path,
+        type: type as FinderItem["type"],
+        exists: true,
+      };
+    });
+}
+
+/**
+ * Open Finder window at path
+ */
+export async function openFinderWindow(path: string): Promise<OsascriptResult> {
+  const script = `
+    tell application "Finder"
+      activate
+      open POSIX file "${escapeString(path)}"
+    end tell
+  `;
+  return executeAppleScript(script);
+}
+
+/**
+ * Create new folder in Finder
+ */
+export async function createFolder(
+  parentPath: string,
+  folderName: string
+): Promise<OsascriptResult> {
+  const script = `
+    tell application "Finder"
+      make new folder at POSIX file "${escapeString(parentPath)}" with properties {name:"${escapeString(folderName)}"}
+    end tell
+  `;
+  return executeAppleScript(script);
+}
+
+/**
+ * Move file/folder to trash
+ */
+export async function moveToTrash(path: string): Promise<OsascriptResult> {
+  const script = `
+    tell application "Finder"
+      delete POSIX file "${escapeString(path)}"
+    end tell
+  `;
+  return executeAppleScript(script);
+}
+
+// ==============
+// Display
+// ==============
+
+/**
+ * Get display information
+ */
+export async function getDisplayInfo(): Promise<DisplayInfo[]> {
+  // Using JXA for better display info
+  const script = `
+    ObjC.import('Cocoa');
+    var screens = $.NSScreen.screens;
+    var count = screens.count;
+    var result = [];
+    for (var i = 0; i < count; i++) {
+      var screen = screens.objectAtIndex(i);
+      var frame = screen.frame;
+      result.push({
+        id: i,
+        width: frame.size.width,
+        height: frame.size.height,
+        main: i === 0
+      });
+    }
+    JSON.stringify(result);
+  `;
+
+  const result = await executeJXA(script);
+  if (!result.success) {
+    // Fallback to AppleScript
+    const fallbackScript = `
+      tell application "System Events"
+        set screenWidth to word 3 of (do shell script "system_profiler SPDisplaysDataType | grep Resolution")
+        set screenHeight to word 5 of (do shell script "system_profiler SPDisplaysDataType | grep Resolution")
+        return screenWidth & "x" & screenHeight
+      end tell
+    `;
+    const fallback = await executeAppleScript(fallbackScript);
+    const [width, height] = fallback.stdout.split("x").map((n) => parseInt(n));
+
+    return [
+      {
+        id: 0,
+        width: width || 1920,
+        height: height || 1080,
+        main: true,
+      },
+    ];
+  }
+
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    return [
+      {
+        id: 0,
+        width: 1920,
+        height: 1080,
+        main: true,
+      },
+    ];
+  }
+}
+
+/**
+ * Get screen resolution
+ */
+export async function getScreenResolution(): Promise<{ width: number; height: number }> {
+  const displays = await getDisplayInfo();
+  const mainDisplay = displays.find((d) => d.main) || displays[0];
+  return {
+    width: mainDisplay?.width || 1920,
+    height: mainDisplay?.height || 1080,
+  };
+}
+
+// ==============
+// Utilities
+// ==============
+
+/**
+ * Check if running on macOS
+ */
+export function isMacOS(): boolean {
+  return process.platform === "darwin";
+}
+
+/**
+ * Ensure running on macOS
+ */
+export function ensureMacOS(): void {
+  if (!isMacOS()) {
+    throw new Error("osascript MCP only works on macOS");
+  }
+}
+
+/**
+ * Escape string for AppleScript
+ */
+export function escapeString(str: string): string {
+  return str
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, "\\n")
+    .replace(/\r/g, "\\r")
+    .replace(/\t/g, "\\t");
+}
+
+/**
+ * Delay execution
+ */
+export async function delay(seconds: number): Promise<void> {
+  await executeAppleScript(`delay ${seconds}`);
+}
+
+/**
+ * Say text using system voice
+ */
+export async function sayText(
+  text: string,
+  voice?: string,
+  rate?: number
+): Promise<OsascriptResult> {
+  let script = `say "${escapeString(text)}"`;
+  if (voice) script += ` using "${voice}"`;
+  if (rate) script += ` speaking rate ${rate}`;
+
+  return executeAppleScript(script);
+}
+
+/**
+ * Beep
+ */
+export async function beep(count = 1): Promise<OsascriptResult> {
+  return executeAppleScript(`beep ${count}`);
+}
+
+/**
+ * Get current date/time from system
+ */
+export async function getSystemDateTime(): Promise<string> {
+  const script = `
+    get current date
+  `;
+
+  const result = await executeAppleScript(script);
+  if (!result.success) {
+    throw new Error(`Failed to get system date: ${result.stderr}`);
+  }
+  return result.stdout;
+}