@ebowwa/osascript 1.1.0

package/README.md

@@ -0,0 +1,123 @@
+# @ebowwa/osascript
+
+macOS automation via osascript (AppleScript/JXA) with MCP interface.
+
+## Installation
+
+```bash
+bun add @ebowwa/osascript
+```
+
+## MCP Server
+
+Add to your Claude Code config:
+
+```json
+{
+  "mcpServers": {
+    "osascript": {
+      "command": "bunx",
+      "args": ["@ebowwa/osascript/mcp"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `osascript_execute` | Execute raw AppleScript or JXA code |
+| `osascript_display_notification` | Display a macOS notification |
+| `osascript_display_dialog` | Display a dialog with buttons |
+| `osascript_get_volume` | Get system volume level |
+| `osascript_set_volume` | Set system volume (0-100) |
+| `osascript_get_clipboard` | Get clipboard contents |
+| `osascript_set_clipboard` | Set clipboard contents |
+| `osascript_list_apps` | List all running applications |
+| `osascript_get_app_info` | Get detailed app information |
+| `osascript_activate_app` | Activate (bring to front) an app |
+| `osascript_quit_app` | Quit an application |
+| `osascript_launch_app` | Launch an application |
+| `osascript_get_frontmost_app` | Get the active application name |
+| `osascript_get_windows` | Get window list for an app |
+| `osascript_set_window_bounds` | Set window position and size |
+| `osascript_keystroke` | Send keystroke with modifiers |
+| `osascript_key_code` | Send key code (special keys) |
+| `osascript_type_text` | Type text (simulate keyboard) |
+| `osascript_safari_get_url` | Get current Safari URL |
+| `osascript_safari_set_url` | Navigate Safari to URL |
+| `osascript_safari_get_tabs` | Get Safari tab titles |
+| `osascript_safari_exec_js` | Execute JavaScript in Safari |
+| `osascript_finder_get_selection` | Get Finder selected files |
+| `osascript_finder_open` | Open Finder window at path |
+| `osascript_finder_create_folder` | Create new folder |
+| `osascript_finder_trash` | Move file to trash |
+| `osascript_get_displays` | Get display information |
+| `osascript_get_resolution` | Get screen resolution |
+| `osascript_say` | Say text using system voice |
+| `osascript_beep` | Play system beep |
+
+## Key Codes
+
+Common key codes for `osascript_key_code`:
+
+| Key | Code |
+|-----|------|
+| Return | 36 |
+| Tab | 48 |
+| Space | 49 |
+| Delete | 51 |
+| Escape | 53 |
+| Arrow Left | 123 |
+| Arrow Right | 124 |
+| Arrow Down | 125 |
+| Arrow Up | 126 |
+| Home | 115 |
+| End | 119 |
+| Page Up | 116 |
+| Page Down | 121 |
+
+## Usage Examples
+
+### Notification
+```typescript
+import { displayNotification } from "@ebowwa/osascript";
+
+await displayNotification({
+  title: "Task Complete",
+  message: "Your file has been processed",
+  soundName: "Glass"
+});
+```
+
+### Clipboard
+```typescript
+import { getClipboard, setClipboard } from "@ebowwa/osascript";
+
+await setClipboard("Hello, World!");
+const content = await getClipboard(); // "Hello, World!"
+```
+
+### Safari
+```typescript
+import { getSafariURL, setSafariURL } from "@ebowwa/osascript";
+
+const url = await getSafariURL();
+await setSafariURL("https://github.com");
+```
+
+### Keyboard
+```typescript
+import { sendKeystroke, KeyCodes, sendKeyCode } from "@ebowwa/osascript";
+
+// Send Command+C
+await sendKeystroke({ key: "c", modifiers: ["command"] });
+
+// Press Return
+await sendKeyCode({ keyCode: KeyCodes.RETURN });
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,574 @@
+// @bun
+// src/index.ts
+import { spawn } from "child_process";
+async function executeOsascript(script, options = {}) {
+  const { language = "applescript", timeout = 30000 } = options;
+  const args = [];
+  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
+      });
+    });
+  });
+}
+async function executeAppleScript(script, timeout = 30000) {
+  return executeOsascript(script, { language: "applescript", timeout });
+}
+async function executeJXA(script, timeout = 30000) {
+  return executeOsascript(script, { language: "javascript", timeout });
+}
+async function displayNotification(options) {
+  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);
+}
+async function displayDialog(options) {
+  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}`);
+  }
+  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
+  };
+}
+async function getVolume() {
+  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"
+  };
+}
+async function setVolume(volume, muted) {
+  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);
+}
+async function getClipboard() {
+  const result = await executeAppleScript("the clipboard");
+  if (!result.success) {
+    throw new Error(`Failed to get clipboard: ${result.stderr}`);
+  }
+  return result.stdout;
+}
+async function setClipboard(text) {
+  const script = `set the clipboard to "${escapeString(text)}"`;
+  return executeAppleScript(script);
+}
+async function clearClipboard() {
+  return executeAppleScript('set the clipboard to ""');
+}
+async function listRunningApplications() {
+  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(`
+`).filter((name) => name.trim()).map((name) => ({
+    name: name.trim(),
+    running: true
+  }));
+  return apps;
+}
+async function getApplicationInfo(appName) {
+  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)
+  };
+}
+async function activateApplication(appName) {
+  const script = `
+    tell application "${escapeString(appName)}"
+      activate
+    end tell
+  `;
+  return executeAppleScript(script);
+}
+async function quitApplication(appName, force = false) {
+  let script;
+  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);
+}
+async function launchApplication(appName) {
+  const script = `
+    tell application "${escapeString(appName)}"
+      launch
+    end tell
+  `;
+  return executeAppleScript(script);
+}
+async function getFrontmostApplication() {
+  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;
+}
+async function getApplicationWindows(appName) {
+  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;
+}
+async function setWindowBounds(appName, windowIndex, bounds) {
+  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);
+}
+async function minimizeWindow(appName, windowIndex) {
+  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);
+}
+async function sendKeystroke(options) {
+  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);
+}
+async function sendKeyCode(options) {
+  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);
+}
+async function typeText(text, delayBetweenChars = 0.01) {
+  const script = `
+    tell application "System Events"
+      keystroke "${escapeString(text)}"
+      ${delayBetweenChars > 0 ? `delay ${delayBetweenChars}` : ""}
+    end tell
+  `;
+  return executeAppleScript(script);
+}
+async function pressKeyCombination(key, modifiers) {
+  return sendKeystroke({ key, modifiers });
+}
+var 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
+};
+async function getSafariURL() {
+  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;
+}
+async function setSafariURL(url) {
+  const script = `
+    tell application "Safari"
+      set URL of current tab of front window to "${escapeString(url)}"
+    end tell
+  `;
+  return executeAppleScript(script);
+}
+async function getSafariTabTitles() {
+  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());
+}
+async function executeSafariJS(jsCode) {
+  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;
+}
+async function getFinderSelection() {
+  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(`
+`).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,
+      exists: true
+    };
+  });
+}
+async function openFinderWindow(path) {
+  const script = `
+    tell application "Finder"
+      activate
+      open POSIX file "${escapeString(path)}"
+    end tell
+  `;
+  return executeAppleScript(script);
+}
+async function createFolder(parentPath, folderName) {
+  const script = `
+    tell application "Finder"
+      make new folder at POSIX file "${escapeString(parentPath)}" with properties {name:"${escapeString(folderName)}"}
+    end tell
+  `;
+  return executeAppleScript(script);
+}
+async function moveToTrash(path) {
+  const script = `
+    tell application "Finder"
+      delete POSIX file "${escapeString(path)}"
+    end tell
+  `;
+  return executeAppleScript(script);
+}
+async function getDisplayInfo() {
+  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) {
+    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
+      }
+    ];
+  }
+}
+async function getScreenResolution() {
+  const displays = await getDisplayInfo();
+  const mainDisplay = displays.find((d) => d.main) || displays[0];
+  return {
+    width: mainDisplay?.width || 1920,
+    height: mainDisplay?.height || 1080
+  };
+}
+function isMacOS() {
+  return process.platform === "darwin";
+}
+function ensureMacOS() {
+  if (!isMacOS()) {
+    throw new Error("osascript MCP only works on macOS");
+  }
+}
+function escapeString(str) {
+  return str.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+}
+async function delay(seconds) {
+  await executeAppleScript(`delay ${seconds}`);
+}
+async function sayText(text, voice, rate) {
+  let script = `say "${escapeString(text)}"`;
+  if (voice)
+    script += ` using "${voice}"`;
+  if (rate)
+    script += ` speaking rate ${rate}`;
+  return executeAppleScript(script);
+}
+async function beep(count = 1) {
+  return executeAppleScript(`beep ${count}`);
+}
+async function getSystemDateTime() {
+  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;
+}
+export {
+  typeText,
+  setWindowBounds,
+  setVolume,
+  setSafariURL,
+  setClipboard,
+  sendKeystroke,
+  sendKeyCode,
+  sayText,
+  quitApplication,
+  pressKeyCombination,
+  openFinderWindow,
+  moveToTrash,
+  minimizeWindow,
+  listRunningApplications,
+  launchApplication,
+  isMacOS,
+  getVolume,
+  getSystemDateTime,
+  getScreenResolution,
+  getSafariURL,
+  getSafariTabTitles,
+  getFrontmostApplication,
+  getFinderSelection,
+  getDisplayInfo,
+  getClipboard,
+  getApplicationWindows,
+  getApplicationInfo,
+  executeSafariJS,
+  executeOsascript,
+  executeJXA,
+  executeAppleScript,
+  escapeString,
+  ensureMacOS,
+  displayNotification,
+  displayDialog,
+  delay,
+  createFolder,
+  clearClipboard,
+  beep,
+  activateApplication,
+  KeyCodes
+};