automating-mac-apps

macOS アプリの自動化（Apple Events、AppleScript、JXA）

技術の状況

JXA と AppleScript はレガシーです（最後の大規模な更新：2015～2016年）。最新の代替手段：

• PyXA：アクティブに開発されている Python による自動化（インストール方法は以下を参照）
• Shortcuts App：ビジュアルなワークフロービルダー
• Swift/Objective-C：本番環境に対応した自動化

macOS Sequoia 15 に関する注意事項

以下の理由から、対象の macOS でスクリプトをテストしてください。

• TCC の権限がより厳格になっています
• Apple Events のセキュリティが強化されています
• サンドボックスが改善されています

基本的な考え方（このメンタルモデルを使ってください）

• Apple Events：macOS の自動化における、プロセス間通信（IPC）の基盤となるトランスポートです。
• AppleScript：Apple Events 用の元祖 DSL（ドメイン固有言語）です。仕様の調査、辞書の確認、手早いプロトタイプ作成に最適です。
• JXA（JavaScript for Automation）：Apple Events レイヤーへの JavaScript バインディングです。データ処理、JSON、保守しやすいロジックに最適です。
• ObjC Bridge：JavaScript から Objective-C フレームワーク（Foundation、AppKit）にアクセスし、アプリの辞書を超える高度な macOS 機能を利用できます。

どれを使うか

• 仕様の調査、辞書の確認、UI スクリプティング、手早い単発の処理には AppleScript を使います。
• 堅牢なロジック、JSON パイプライン、Python/Node との統合、長期間運用する自動化には JXA を使います。
• ハイブリッドパターン（推奨）：AppleScript で調査し、本番利用向けに JXA で実装します。

このスキルを使う場面

• アプリ固有のスキル（Calendar、Notes、Mail、Keynote、Excel、Reminders）の基盤として使います。
• 初回の自動化の前に自動化ウォームアップスクリプトを実行し、macOS の権限確認ダイアログを表示させます。
• 権限、シェル統合、UI スクリプティングの代替手段について、基本資料として使います。

ワークフロー（既定）

1. Script Editor を使って、対象アプリと辞書を特定します。
2. 動作する最小限のコマンドを試作します。
   • 例：tell application "Finder" to get name of first item in desktop
3. 上記のルールに従って言語を選択します。
4. エラーハンドリング、タイムアウト、権限チェックを追加して堅牢化します。
   • JXA：try { ... } catch (e) { console.log('Error:', e.message); }
   • AppleScript：try ... on error errMsg ... end try
5. 読み取り専用コマンドを実行して出力を確認し、検証します。
   • 例：osascript -e 'tell application "Finder" to get name of home'
   • 確認事項：出力が期待どおりであること（例：ユーザーのホームフォルダ名）
6. CLI やパイプラインで使う場合は、osascript 経由で統合します。
7. UI スクリプティングの代替手段は、辞書がない、または不完全な場合に限って使います。
   • UI スクリプトの例：tell application "System Events" to click button 1 of window 1 of process "App"
   • JXA の例：Application('System Events').processes.byName('App').windows[0].buttons[0].click()

検証チェックリスト

• 自動化／アクセシビリティの権限が付与されている（システム設定 > プライバシーとセキュリティ）
• アプリが実行中である：Application("App").running() が true を返す
• 操作前に状態を確認している（例：フォルダが存在する）
• 辞書のメソッドを使っている（UI スクリプティングではない）
• UI 操作に遅延／再試行を追加している
• 読み取り専用のテストコマンドが成功する
• 出力が期待値と一致する

自動化権限のウォームアップ

• 初回の自動化実行前、または macOS のアップデート後に、権限確認ダイアログを表示させるために使います。
  • すべてのアプリを一度に設定：skills/automating-mac-apps/scripts/request_automation_permissions.sh（または .py）。
  • アプリごとに設定：skills/automating-<app>/scripts/set_up_<app>_automation.{sh,py}（calendar、notes、mail、keynote、excel、reminders）。
  • ボイスメモ（辞書なし）：skills/automating-voice-memos/scripts/set_up_voice_memos_automation.sh を使ってアプリを起動し、データパスを確認します。アクセシビリティを有効にし、フルディスクアクセスも検討してください。
• 自動化に使う予定のものと同じホストから実行してください（Terminal と Python では異なります）。これにより、正しいアプリに「自動化」の承認が付与されます。
• 各スクリプトは読み取り専用の AppleScript 呼び出し（アカウント／カレンダー／フォルダの一覧表示など）を実行して、Terminal／Python による制御の許可を求めます。確認ダイアログが表示されたら「許可」をクリックしてください。

JXA に代わる最新の Python 手段

PyXA（Python for macOS Automation） - 新しいプロジェクトに推奨：

PyXA の機能

• 活発に開発中（v0.2.3 以降）で、最新の Python 構文に対応
• アプリの自動化：Safari、Calendar、Reminders、Mail、Music
• UI スクリプティング、クリップボード、通知、AppleScript との統合
• メソッドチェーン：app.lists().reminders().title()

PyXA のインストール {#pyxa-installation}

# Install PyXA
pip install mac-pyxa

# Or with pip3 explicitly
pip3 install mac-pyxa

# Requirements:
# - Python 3.10+ (check with: python3 --version)
# - macOS 12+ (Monterey or later recommended)
# - PyObjC is installed automatically as a dependency

# Verify installation
python3 -c "import PyXA; print(f'PyXA {PyXA.__version__} installed successfully')"

注記： このプラグイン内で PyXA の例を示すアプリ固有のスキルは、PyXA がインストールされていることを前提としています。インストール方法については、このセクションを参照してください。

PyXA の例（Safari の自動化）

import PyXA

# Launch Safari and navigate
safari = PyXA.Safari()
safari.activate()
safari.open_location("https://example.com")

# Get current tab URL
current_url = safari.current_tab.url
print(f"Current URL: {current_url}")

PyXA の例（Reminders）

import PyXA

reminders = PyXA.Reminders()
work_list = reminders.lists().by_name("Work")

# Add new reminder
new_reminder = work_list.reminders().push({
    "name": "Review PyXA documentation",
    "body": "Explore modern macOS automation options"
})

PyXA の公式リソース：

• ドキュメント：https://skaplanofficial.github.io/PyXA/
• GitHub：https://github.com/SKaplanOfficial/PyXA
• コミュニティ：活発な Discord と GitHub のディスカッション

---

PyObjC（Python と Objective-C のブリッジ） — macOS の低レベル統合向け：

PyObjC の機能

• フレームワークへの直接アクセス：AppKit、Foundation、およびすべての macOS フレームワーク
• Apple Events：Scripting Bridge 経由で Apple Events を送信
• スクリプトの実行：Python から AppleScript または JXA を実行
• システム API：CalendarStore、AddressBook、SystemEvents に直接アクセス

インストール

pip install pyobjc
# Installs bridges for major frameworks

PyObjC の例（AppleScript の実行）

from Foundation import NSAppleScript

# Execute AppleScript from Python
script_source = '''
tell application "Safari"
    return URL of current tab
end tell
'''

script = NSAppleScript.alloc().initWithSource_(script_source)
result, error = script.executeAndReturnError_(None)

if error:
    print(f"Error: {error}")
else:
    print(f"Current Safari URL: {result.stringValue()}")

PyObjC の例（Scripting Bridge によるアプリの制御）

from ScriptingBridge import SBApplication

# Control Mail app
mail = SBApplication.applicationWithBundleIdentifier_("com.apple.Mail")
inbox = mail.inboxes()[0]  # Access first inbox

# Get unread message count
unread_count = inbox.unreadCount()
print(f"Unread messages: {unread_count}")

PyObjC の公式リソース：

• ドキュメント：https://pyobjc.readthedocs.io
• 例：コードサンプルを含む GitHub リポジトリが多数あります

---

JXA の状況

JXA は 2016 年以降、更新されていません。新しいプロジェクトでは、可能な場合は PyXA を使用してください。

使用しない場合

• クロスプラットフォームの自動化（Web には Selenium／Playwright を使用してください）
• UI テスト全般（XCUITest または Appium を使用してください）
• Automation／Accessibility の権限がブロックされている環境
• macOS 以外のプラットフォーム
• シンプルなシェルスクリプトのタスク（Bash を直接使用してください）

関連スキル

• アプリ固有の自動化（必要に応じて automating-[app] スキルを作成してください）
• 自動化環境での高度な権限管理には ci-cd-tcc
• AppleScript 中心のワークフローには mastering-applescript

セキュリティのベストプラクティス

権限管理：

• セキュリティリスクを抑えるため、必要最小限の権限を要求してください
• 本番環境のスクリプトにはコード署名を使用してください（Developer ID 証明書）
• 認証情報は安全に保管してください（ハードコードせず、Keychain を使用）
• インジェクション攻撃を防ぐため、すべての入力を検証してください

Apple 公式のセキュリティガイダンス：

• Apple プラットフォームセキュリティガイド
• スクリプティングのセキュリティに関する考慮事項
• App Sandbox 設計ガイド

出力に関する期待事項

• 例は最小限にし、実行可能な状態にしてください。
• JSON 出力：CLI パイプラインでは、JXA の JSON.stringify(result) を使用してください。
  • 例：console.log(JSON.stringify({files: files, count: files.length}))
• 終了コード：成功時に osascript が 0、失敗時に 0 以外を返すようにしてください。

読み込む内容

Tier 1：基本（ここから開始）

• JXA の構文とパターン：automating-mac-apps/references/basics.md
• AppleScript の基本：automating-mac-apps/references/applescript-basics.md
• クックブック（一般的なレシピ）：automating-mac-apps/references/recipes.md

Tier 2：応用と本番環境

• JXA クックブック（要約版）：automating-mac-apps/references/cookbook.md
• パフォーマンスのパターン：automating-mac-apps/references/applescript-performance.md
• CI/CD と権限：automating-mac-apps/references/ci-cd-tcc.md
• シェル環境：automating-mac-apps/references/shell-environment.md
• UI スクリプティングインスペクター：automating-mac-apps/references/ui-scripting-inspector.md

Tier 3：専門・リファレンス

• PyXA コア API リファレンス（クラス／メソッドの完全なドキュメント）：automating-mac-apps/references/pyxa-core-api-reference.md
• PyXA の基礎：automating-mac-apps/references/pyxa-basics.md（最新の Python 自動化の基礎）
• AppleScript → PyXA 変換：automating-mac-apps/references/applescript-to-pyxa-conversion.md（例を含む移行ガイド）
• 変換チェックリスト（AppleScript → JXA）：automating-mac-apps/references/translation-checklist.md（例と注意点を含む包括的なガイド）
• JXA ヘルパーライブラリ：automating-mac-apps/references/helpers.js
• whose のバッチ処理パターン：automating-mac-apps/references/whos-batching.md
• 辞書の戦略：automating-mac-apps/references/dictionary-strategies.md
• ASObjC ヘルパー：automating-mac-apps/references/applescript-asobjc.md

関連スキル：

• web-browser-automation：ブラウザー自動化の完全ガイド（Chrome、Edge、Brave、Arc）