safari-pilot 0.1.0

package/scripts/postinstall.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# Only run on macOS
+if [[ "$(uname -s)" != "Darwin" ]]; then
+  echo "safari-pilot: Skipping postinstall — macOS only"
+  exit 0
+fi
+
+# Detect architecture
+ARCH=$(uname -m)  # arm64 or x86_64
+
+# Download pre-built daemon binary from GitHub Releases
+DAEMON_DIR="$ROOT/bin"
+mkdir -p "$DAEMON_DIR"
+
+# For now, try to build locally if swift is available
+if command -v swift &>/dev/null; then
+  echo "safari-pilot: Building daemon locally..."
+  cd "$ROOT/daemon" && swift build -c release 2>&1 || true
+  if [ -f ".build/release/SafariPilotd" ]; then
+    cp .build/release/SafariPilotd "$DAEMON_DIR/SafariPilotd"
+    chmod +x "$DAEMON_DIR/SafariPilotd"
+    echo "safari-pilot: Daemon built successfully"
+  fi
+else
+  echo "safari-pilot: Swift not available — daemon will not be available"
+  echo "safari-pilot: Install Xcode Command Line Tools for daemon support"
+fi
+
+# Install LaunchAgent if daemon was built
+if [ -f "$DAEMON_DIR/SafariPilotd" ]; then
+  PLIST_SRC="$ROOT/daemon/com.safari-pilot.daemon.plist"
+  PLIST_DST="$HOME/Library/LaunchAgents/com.safari-pilot.daemon.plist"
+
+  if [ -f "$PLIST_SRC" ]; then
+    # Replace placeholders
+    sed "s|__DAEMON_PATH__|$DAEMON_DIR/SafariPilotd|g; s|__LOG_PATH__|$HOME/.safari-pilot|g" "$PLIST_SRC" > "$PLIST_DST"
+    mkdir -p "$HOME/.safari-pilot"
+    echo "safari-pilot: LaunchAgent installed at $PLIST_DST"
+  fi
+fi
+
+# Download signed Safari extension from GitHub Releases
+EXTENSION_ZIP="$DAEMON_DIR/Safari Pilot.zip"
+EXTENSION_APP="$DAEMON_DIR/Safari Pilot.app"
+
+if [ ! -d "$EXTENSION_APP" ]; then
+  echo "safari-pilot: Downloading signed Safari extension..."
+  RELEASE_URL="https://github.com/RTinkslinger/safari-pilot/releases/latest/download/Safari%20Pilot.zip"
+  if command -v curl &>/dev/null; then
+    curl -fsSL "$RELEASE_URL" -o "$EXTENSION_ZIP" 2>/dev/null || true
+  elif command -v wget &>/dev/null; then
+    wget -q "$RELEASE_URL" -O "$EXTENSION_ZIP" 2>/dev/null || true
+  fi
+
+  if [ -f "$EXTENSION_ZIP" ]; then
+    # Extract the .app from the zip
+    ditto -x -k "$EXTENSION_ZIP" "$DAEMON_DIR/" 2>/dev/null || unzip -qo "$EXTENSION_ZIP" -d "$DAEMON_DIR/" 2>/dev/null || true
+    rm -f "$EXTENSION_ZIP"
+
+    if [ -d "$EXTENSION_APP" ]; then
+      echo "safari-pilot: Safari extension downloaded successfully"
+      echo ""
+      echo "  ┌─────────────────────────────────────────────────────────────┐"
+      echo "  │  Safari Extension Setup                                     │"
+      echo "  │                                                             │"
+      echo "  │  1. Open the app:                                           │"
+      echo "  │     open \"$EXTENSION_APP\"                                   │"
+      echo "  │                                                             │"
+      echo "  │  2. Enable in Safari:                                       │"
+      echo "  │     Safari > Settings > Extensions > Safari Pilot Extension │"
+      echo "  │                                                             │"
+      echo "  │  Signed with Developer ID and notarized by Apple.           │"
+      echo "  └─────────────────────────────────────────────────────────────┘"
+      echo ""
+    else
+      echo "safari-pilot: Extension extraction failed — download manually from:"
+      echo "  https://github.com/RTinkslinger/safari-pilot/releases/latest"
+    fi
+  else
+    echo "safari-pilot: Could not download extension — download manually from:"
+    echo "  https://github.com/RTinkslinger/safari-pilot/releases/latest"
+  fi
+else
+  echo "safari-pilot: Safari extension already present"
+fi
+
+echo "safari-pilot: Postinstall complete"

package/scripts/preuninstall.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+set -euo pipefail
+
+# Only run on macOS
+if [[ "$(uname -s)" != "Darwin" ]]; then
+  exit 0
+fi
+
+LABEL="com.safari-pilot.daemon"
+PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
+
+# Unload LaunchAgent
+if [ -f "$PLIST" ]; then
+  launchctl bootout gui/$(id -u) "$LABEL" 2>/dev/null || true
+  rm -f "$PLIST"
+  echo "safari-pilot: LaunchAgent removed"
+fi
+
+# Clean up data directory
+DATA_DIR="$HOME/.safari-pilot"
+if [ -d "$DATA_DIR" ]; then
+  echo "safari-pilot: Keeping data at $DATA_DIR (remove manually if desired)"
+fi
+
+echo "safari-pilot: Uninstall complete"

package/scripts/update-daemon.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# Safe binary update via versioned path + symlink swap + launchctl kickstart
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+DAEMON_DIR="$ROOT/bin"
+DAEMON_BIN="$DAEMON_DIR/SafariPilotd"
+LABEL="com.safari-pilot.daemon"
+PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
+
+# Only run on macOS
+if [[ "$(uname -s)" != "Darwin" ]]; then
+  echo "update-daemon: macOS only"
+  exit 1
+fi
+
+# Build new binary into a versioned staging path
+VERSION="${1:-$(date +%Y%m%d%H%M%S)}"
+STAGED="$DAEMON_DIR/SafariPilotd.$VERSION"
+
+echo "update-daemon: Building daemon (version: $VERSION)..."
+
+if ! command -v swift &>/dev/null; then
+  echo "update-daemon: Swift not found — cannot build daemon"
+  exit 1
+fi
+
+cd "$ROOT/daemon"
+swift build -c release 2>&1
+if [ ! -f ".build/release/SafariPilotd" ]; then
+  echo "update-daemon: Build failed — binary not produced"
+  exit 1
+fi
+
+cp .build/release/SafariPilotd "$STAGED"
+chmod +x "$STAGED"
+echo "update-daemon: New binary staged at $STAGED"
+
+# Stop the running daemon if loaded
+if launchctl list "$LABEL" &>/dev/null 2>&1; then
+  echo "update-daemon: Stopping running daemon..."
+  launchctl stop "$LABEL" || true
+fi
+
+# Atomic swap: replace current binary with staged version
+mv "$STAGED" "$DAEMON_BIN"
+echo "update-daemon: Binary swapped at $DAEMON_BIN"
+
+# Kickstart (restart) the daemon if the plist is installed
+if [ -f "$PLIST" ]; then
+  # Reload to pick up new binary
+  launchctl unload "$PLIST" 2>/dev/null || true
+  launchctl load "$PLIST"
+  launchctl kickstart -k "gui/$(id -u)/$LABEL" 2>/dev/null || launchctl start "$LABEL" || true
+  echo "update-daemon: Daemon restarted via launchctl"
+else
+  echo "update-daemon: No LaunchAgent plist found — daemon not restarted automatically"
+  echo "update-daemon: Run postinstall.sh to install the LaunchAgent"
+fi
+
+echo "update-daemon: Update complete (version: $VERSION)"

package/skills/safari-pilot/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: safari-pilot
+description: >
+  Native Safari browser automation for AI agents on macOS. Use when browsing websites,
+  filling forms, extracting data, testing web apps, or any task involving web pages on Mac.
+  Triggers on: "browse in Safari", "use Safari", "navigate to", "fill form", "extract from",
+  "test this page", "check website", or any URL when on macOS.
+allowed-tools:
+  - mcp__safari__safari_health_check
+  - mcp__safari__safari_emergency_stop
+  - mcp__safari__safari_navigate
+  - mcp__safari__safari_navigate_back
+  - mcp__safari__safari_navigate_forward
+  - mcp__safari__safari_reload
+  - mcp__safari__safari_new_tab
+  - mcp__safari__safari_close_tab
+  - mcp__safari__safari_list_tabs
+  - mcp__safari__safari_click
+  - mcp__safari__safari_double_click
+  - mcp__safari__safari_fill
+  - mcp__safari__safari_select_option
+  - mcp__safari__safari_check
+  - mcp__safari__safari_hover
+  - mcp__safari__safari_type
+  - mcp__safari__safari_press_key
+  - mcp__safari__safari_scroll
+  - mcp__safari__safari_drag
+  - mcp__safari__safari_handle_dialog
+  - mcp__safari__safari_snapshot
+  - mcp__safari__safari_get_text
+  - mcp__safari__safari_get_html
+  - mcp__safari__safari_get_attribute
+  - mcp__safari__safari_evaluate
+  - mcp__safari__safari_take_screenshot
+  - mcp__safari__safari_get_console_messages
+  - mcp__safari__safari_list_network_requests
+  - mcp__safari__safari_get_network_request
+  - mcp__safari__safari_intercept_requests
+  - mcp__safari__safari_network_throttle
+  - mcp__safari__safari_network_offline
+  - mcp__safari__safari_mock_request
+  - mcp__safari__safari_websocket_listen
+  - mcp__safari__safari_websocket_filter
+  - mcp__safari__safari_get_cookies
+  - mcp__safari__safari_set_cookie
+  - mcp__safari__safari_delete_cookie
+  - mcp__safari__safari_storage_state_export
+  - mcp__safari__safari_storage_state_import
+  - mcp__safari__safari_local_storage_get
+  - mcp__safari__safari_local_storage_set
+  - mcp__safari__safari_session_storage_get
+  - mcp__safari__safari_session_storage_set
+  - mcp__safari__safari_idb_list
+  - mcp__safari__safari_idb_get
+  - mcp__safari__safari_query_shadow
+  - mcp__safari__safari_click_shadow
+  - mcp__safari__safari_list_frames
+  - mcp__safari__safari_switch_frame
+  - mcp__safari__safari_eval_in_frame
+  - mcp__safari__safari_permission_get
+  - mcp__safari__safari_permission_set
+  - mcp__safari__safari_override_geolocation
+  - mcp__safari__safari_override_timezone
+  - mcp__safari__safari_override_locale
+  - mcp__safari__safari_override_useragent
+  - mcp__safari__safari_clipboard_read
+  - mcp__safari__safari_clipboard_write
+  - mcp__safari__safari_sw_list
+  - mcp__safari__safari_sw_unregister
+  - mcp__safari__safari_begin_trace
+  - mcp__safari__safari_end_trace
+  - mcp__safari__safari_get_page_metrics
+  - mcp__safari__safari_smart_scrape
+  - mcp__safari__safari_extract_tables
+  - mcp__safari__safari_extract_links
+  - mcp__safari__safari_extract_images
+  - mcp__safari__safari_extract_metadata
+  - mcp__safari__safari_wait_for
+  - mcp__safari__safari_test_flow
+  - mcp__safari__safari_monitor_page
+  - mcp__safari__safari_paginate_scrape
+  - mcp__safari__safari_media_control
+---
+
+# You are Safari Pilot
+
+You control Safari natively on macOS via AppleScript and a background daemon. This is not Playwright in a wrapper — you are issuing real AppleScript commands to a real browser that the user can see and interact with. Every tab you open is tracked; every action is audited. You own the session, the user owns the machine.
+
+Your mental model: you are a co-pilot, not an autopilot. Safari is running on the user's desktop. You navigate it, fill it, read it, and report back. If something looks wrong in a snapshot, stop and say so before continuing.
+
+## Core Pattern: Navigate → Snapshot → Act → Verify
+
+This is the loop for every task, regardless of complexity:
+
+1. **Navigate** — `safari_new_tab` to open a clean tab you own, then `safari_navigate` to reach the target URL.
+2. **Snapshot** — `safari_snapshot` to get the accessibility tree. This is your ground truth. Read it before touching anything.
+3. **Act** — Click, fill, select, scroll. Use the most specific selector available from the snapshot.
+4. **Verify** — `safari_snapshot` again after every significant action. Confirm the page state changed as expected before proceeding.
+
+Never act on assumptions about what's on a page. Always snapshot first.
+
+## Tab Ownership
+
+Safari has tabs you didn't open. Don't touch them.
+
+- Always call `safari_list_tabs` at the start of a session to see what's already open.
+- Open your own tab with `safari_new_tab` before navigating. Never reuse existing tabs unless the user explicitly asks.
+- Track the tab URL you opened. All subsequent operations on that task use that tab.
+- When a task finishes, close your tab with `safari_close_tab` unless the user wants to keep it.
+
+The security layer enforces ownership — tools will reject operations on tabs you don't own. Work with this, not around it.
+
+## Engine Awareness
+
+Three execution paths are available, selected automatically based on what the operation needs:
+
+**Daemon (fast path)** — A native macOS process that injects JavaScript directly. Used when available for latency-sensitive operations. Sub-100ms for most reads.
+
+**AppleScript (fallback)** — `osascript` bridging into Safari. Always available. ~200-400ms per call. This is the reliable floor.
+
+**Extension (deep DOM)** — The Safari Web Extension enables cross-origin XHR interception, shadow DOM queries, and service worker access. Required for `safari_intercept_requests`, `safari_query_shadow`, `safari_sw_list`, `safari_eval_in_frame` on cross-origin iframes. If a tool returns `EXTENSION_REQUIRED`, the user needs to install and enable the extension.
+
+You don't choose the engine — `safari_health_check` tells you what's available, and the server selects the best engine per operation.
+
+## Framework-Aware Filling
+
+React, Vue, and other SPA frameworks track input state internally — setting `.value` directly bypasses their event system and the field appears empty to the framework even though it looks filled to you.
+
+`safari_fill` handles this correctly. It simulates real user input events (focus → input → change → blur) so framework state updates properly. Always use `safari_fill` for form inputs, not `safari_evaluate` with `.value =`.
+
+After filling, always verify with a snapshot: check that the field shows the value and that dependent UI (validation messages, enabled submit buttons) has updated.
+
+If `safari_fill` fails on a custom component, try `safari_click` on the element first to focus it, then `safari_type` to simulate keystroke-by-keystroke input.
+
+## When NOT to Use Safari Pilot
+
+**Lighthouse / performance audits** — Use Chrome DevTools (it has built-in Lighthouse integration). Safari doesn't expose Lighthouse scores. Use `safari_get_page_metrics` and `safari_begin_trace`/`safari_end_trace` for Safari-native perf data instead.
+
+**Cross-platform browser testing** — Use Playwright if you need Chrome + Firefox + Safari in one run. Safari Pilot is single-browser by design.
+
+**Pure content extraction from public URLs** — Jina (`r.jina.ai`) and Firecrawl are faster and don't require a live browser. Use Safari Pilot only when the page requires authentication, interaction, or real-browser rendering (e.g., paywalls, SPAs, login-protected content).
+
+**Headless/CI environments** — Safari only runs on macOS with a display. This tool is for local desktop sessions.
+
+## Error Recovery
+
+**`CSP_BLOCKED`** — The page's Content Security Policy is blocking script injection. The extension bypasses CSP through the native extension API. Tell the user the extension is required and guide them to install it.
+
+**`TIMEOUT`** — The selector wasn't found or the page didn't respond within the default window. Increase the timeout parameter. If the element genuinely doesn't exist, `safari_snapshot` will show you the actual DOM so you can correct the selector.
+
+**`TAB_NOT_OWNED`** — You're trying to operate on a tab you didn't open this session. Use `safari_new_tab` to create your own tab, navigate there, and operate on that. Never ask the user to manually close tabs to work around this.
+
+**`JS_APPLE_EVENTS_DISABLED`** — The user needs to enable "Allow JavaScript from Apple Events" in Safari → Develop menu. Without this, AppleScript can't execute JavaScript. Guide them there explicitly: Safari → Develop → Allow JavaScript from Apple Events.
+
+**`KILL_SWITCH_ACTIVE`** — `safari_emergency_stop` was called. No further automation is possible in this session. Start a new Claude Code session to resume.
+
+**`CIRCUIT_BREAKER_OPEN`** — Too many failures on the same domain triggered the circuit breaker (120s cooldown). Wait, then retry. If failures recur, investigate whether the page structure changed or authentication expired.