safari-pilot 0.1.4 → 0.1.26

package/.claude-plugin/commands/start.md

@@ -0,0 +1,41 @@
+---
+name: start
+description: Start the Safari Pilot daemon (idempotent — safe to call if already running)
+allowed-tools: Bash
+---
+
+Start the SafariPilotd daemon process. This is idempotent — if the daemon is already running, report its PID and exit.
+
+## Steps
+
+1. Check if the daemon is already running:
+   ```bash
+   pgrep -f SafariPilotd
+   ```
+
+2. **If already running**, report the PID and exit:
+   > Safari Pilot daemon already running (PID: {pid})
+
+3. **If not running**, start it:
+   ```bash
+   DAEMON_BIN="${CLAUDE_PLUGIN_ROOT}/bin/SafariPilotd"
+   DATA_DIR="${HOME}/.safari-pilot"
+   mkdir -p "$DATA_DIR"
+   "$DAEMON_BIN" --daemon >> "$DATA_DIR/daemon.log" 2>&1 &
+   echo $! > "$DATA_DIR/daemon.pid"
+   ```
+
+4. Verify it started (check PID is alive):
+   ```bash
+   kill -0 $(cat ~/.safari-pilot/daemon.pid) 2>/dev/null
+   ```
+
+5. Report the result:
+   > Safari Pilot daemon started (PID: {pid})
+   >
+   > The Safari extension is managed separately in Safari > Settings > Extensions.
+
+## If the daemon binary is missing
+
+Report:
+> SafariPilotd not found at {path}. Run `npm install` in the safari-pilot directory to build it, or install Xcode Command Line Tools if Swift is not available.

package/.claude-plugin/commands/stop.md

@@ -0,0 +1,57 @@
+---
+name: stop
+description: Stop the Safari Pilot daemon gracefully
+allowed-tools: Bash
+---
+
+Stop the SafariPilotd daemon process. Attempts graceful SIGTERM shutdown, falls back to SIGKILL if needed.
+
+## Steps
+
+1. Find the daemon PID from the PID file or process list:
+   ```bash
+   PID_FILE="${HOME}/.safari-pilot/daemon.pid"
+   if [ -f "$PID_FILE" ]; then
+     PID=$(cat "$PID_FILE")
+   else
+     PID=$(pgrep -f SafariPilotd)
+   fi
+   ```
+
+2. **If PID was found**, verify the process is actually alive:
+   ```bash
+   kill -0 "$PID" 2>/dev/null
+   ```
+   If the process is not alive, clean up the stale PID file and report:
+   ```bash
+   rm -f "${HOME}/.safari-pilot/daemon.pid"
+   ```
+   > Safari Pilot daemon is not running (cleaned up stale PID file).
+
+3. **If no PID was found or process is dead**, report and exit:
+   > Safari Pilot daemon is not running.
+
+4. **If running**, send SIGTERM for graceful shutdown:
+   ```bash
+   kill "$PID" 2>/dev/null
+   ```
+
+5. Wait up to 3 seconds for the process to exit:
+   ```bash
+   for i in 1 2 3; do
+     kill -0 "$PID" 2>/dev/null || break
+     sleep 1
+   done
+   ```
+
+6. Check if it stopped:
+   - **If stopped**: clean up the PID file and report:
+     ```bash
+     rm -f "${HOME}/.safari-pilot/daemon.pid"
+     ```
+     > Safari Pilot daemon stopped (was PID: {pid})
+   - **If still running after 3s**: report the fallback command:
+     > Daemon did not stop gracefully. To force kill: `kill -9 {pid}`
+
+7. Always note:
+   > The Safari extension remains active independently in Safari > Settings > Extensions.

package/.claude-plugin/plugin.json

@@ -6,6 +6,10 @@
   "license": "MIT",
   "homepage": "https://github.com/RTinkslinger/safari-pilot",
   "components": {
+    "commands": [
+      "commands/start.md",
+      "commands/stop.md"
+    ],
     "mcpServers": {
       "safari": {
         "command": "node",

package/README.md

@@ -4,7 +4,7 @@
 
 Safari Pilot gives Claude Code direct control of Safari through AppleScript and a persistent Swift daemon — no Chrome, no Playwright, no third-party code touching your browser. Your real Safari, with all your logins, automated natively.
 
-> **74 tools** | **3 engine tiers** | **92x faster than raw AppleScript** | **9 security layers** | **macOS 12+**
+> **82 tools** | **3 engine tiers** | **92x faster than raw AppleScript** | **9 security layers** | **macOS 14+ recommended** (12+ minimum)
 
 ---
 
@@ -69,7 +69,13 @@ The extension unlocks advanced features that are impossible without it.
 6. Set to **"Allow on all websites"** when prompted
 7. Click **"Manage Profiles"** and enable for your active profile
 
-The extension is signed with Developer ID and notarized by Apple — it persists permanently across Safari restarts. No "Allow Unsigned Extensions" needed.
+The extension is signed with Developer ID and notarized by Apple — it persists permanently across Safari restarts.
+
+> **Troubleshooting:** If Safari shows **"Safari detected an app or service that interfered with clicking"** when you try to enable the extension, this is a Safari security feature triggered by other apps on your Mac that have Accessibility, Screen Recording, or Input Monitoring permissions (e.g., terminal emulators, screen sharing tools, window managers). To work around it:
+> 1. Go to **Safari > Develop > Allow Unsigned Extensions** (check it temporarily)
+> 2. Enable Safari Pilot in **Safari > Settings > Extensions**
+> 3. Quit and reopen Safari
+> 4. Optionally uncheck "Allow Unsigned Extensions" — the notarized extension stays enabled
 
 **What the extension adds:**
 
@@ -85,7 +91,8 @@ Without the extension, Safari Pilot still works for ~80% of use cases (navigatio
 
 ### System Requirements
 
-- **macOS 12.0 (Monterey)** or later
+- **macOS 14.0 (Sonoma)** or later — recommended; required for the extension engine (the daemon's HTTP poll server uses Hummingbird, which requires macOS 14+)
+- **macOS 12.0 (Monterey)** — minimum; daemon + AppleScript engines work, extension features are unavailable
 - **Safari** (pre-installed on every Mac)
 - **Node.js 20+**
 
@@ -113,7 +120,7 @@ Monitor news.ycombinator.com for any post about our company
 Open my X.com bookmarks and extract the top 5 posts with author profiles
 ```
 
-## Tool Catalog (74 Tools)
+## Tool Catalog (82 Tools)
 
 ### Navigation (7)
 `safari_navigate` | `safari_navigate_back` | `safari_navigate_forward` | `safari_reload` | `safari_new_tab` | `safari_close_tab` | `safari_list_tabs`
@@ -121,20 +128,26 @@ Open my X.com bookmarks and extract the top 5 posts with author profiles
 ### Interaction (11)
 `safari_click` | `safari_double_click` | `safari_fill` | `safari_select_option` | `safari_check` | `safari_hover` | `safari_type` | `safari_press_key` | `safari_scroll` | `safari_drag` | `safari_handle_dialog`
 
+### File Upload (1)
+`safari_file_upload` — programmatic upload to standard `<input type=file>` elements, including hidden inputs behind `<label>` (use `force: true`). 25 MiB / file × 4 / call. Path B architecture: out-of-band byte transport via daemon staging → extension fetch. Does NOT support drag-and-drop dropzones, custom pickers, or native OS dialogs.
+
 ### Extraction (7)
 `safari_snapshot` | `safari_get_text` | `safari_get_html` | `safari_get_attribute` | `safari_evaluate` | `safari_take_screenshot` | `safari_get_console_messages`
 
-### Network (8)
-`safari_list_network_requests` | `safari_get_network_request` | `safari_intercept_requests` | `safari_network_throttle` | `safari_network_offline` | `safari_mock_request` | `safari_websocket_listen` | `safari_websocket_filter`
+### Network (10)
+`safari_list_network_requests` | `safari_get_network_request` | `safari_intercept_requests` | `safari_network_throttle` | `safari_network_offline` | `safari_mock_request` | `safari_websocket_listen` | `safari_websocket_filter` | `safari_dump_har` | `safari_route_from_har`
 
 ### Storage (11)
 `safari_get_cookies` | `safari_set_cookie` | `safari_delete_cookie` | `safari_storage_state_export` | `safari_storage_state_import` | `safari_local_storage_get` | `safari_local_storage_set` | `safari_session_storage_get` | `safari_session_storage_set` | `safari_idb_list` | `safari_idb_get`
 
+### Authentication (2)
+`safari_authenticate` | `safari_clear_authentication` — HTTP Basic auth via DNR header injection (extension required).
+
 ### Shadow DOM (2)
 `safari_query_shadow` | `safari_click_shadow`
 
-### Frames (3)
-`safari_list_frames` | `safari_switch_frame` | `safari_eval_in_frame`
+### Frames (2)
+`safari_list_frames` | `safari_eval_in_frame`
 
 ### Permissions & Overrides (6)
 `safari_permission_get` | `safari_permission_set` | `safari_override_geolocation` | `safari_override_timezone` | `safari_override_locale` | `safari_override_useragent`
@@ -154,9 +167,18 @@ Open my X.com bookmarks and extract the top 5 posts with author profiles
 ### Compound Workflows (4)
 `safari_test_flow` | `safari_monitor_page` | `safari_paginate_scrape` | `safari_media_control`
 
+### Downloads (1)
+`safari_wait_for_download` — wait for download triggered by a click, capture metadata + optional `saveAs`.
+
+### PDF (1)
+`safari_export_pdf` — export the frontmost Safari tab as a PDF via WKWebView.
+
 ### Wait (1)
 `safari_wait_for` — 7 condition types: selector, selectorHidden, text, textGone, urlMatch, networkidle, function
 
+### Diagnostics (2)
+`safari_extension_health` | `safari_extension_debug_dump` — observability for the extension engine. Read-only; safe to call any time.
+
 ### System (2)
 `safari_health_check` | `safari_emergency_stop`
 
@@ -224,11 +246,11 @@ Safari Pilot runs on your local machine with access to your real browser session
 
 **Domain Policy** — Per-domain rate limits prevent runaway automation. Banking and financial domains flagged as untrusted by default.
 
-**Rate Limiter + Circuit Breaker** — Global limit of 120 actions/minute. Circuit breaker trips after 5 consecutive errors, backs off for 120 seconds.
+**Rate Limiter + Circuit Breaker** — Configurable via `safari-pilot.config.json`. Defaults: 120 actions/minute, circuit breaker trips at 5 errors with 120s cooldown.
 
 **IDPI Scanner** — Indirect Prompt Injection defense. Scans extracted text for 9 known injection patterns.
 
-**Kill Switch** — `safari_emergency_stop` immediately halts all automation. One command, full stop.
+**Kill Switch** — `safari_emergency_stop` immediately halts all automation. Configurable auto-activation on error threshold.
 
 **Human Approval** — Sensitive actions (OAuth consent, financial forms, downloads) flagged for explicit approval.
 
@@ -238,6 +260,34 @@ Safari Pilot runs on your local machine with access to your real browser session
 
 **No Credential Access** — Safari Pilot **never** accesses the macOS Keychain. Authentication works through real browser interaction.
 
+## Configuration
+
+All security settings are tunable via `safari-pilot.config.json` in the package root:
+
+```json
+{
+  "schemaVersion": "1.0",
+  "rateLimit": { "maxActionsPerMinute": 120, "windowMs": 60000 },
+  "circuitBreaker": { "errorThreshold": 5, "windowMs": 60000, "cooldownMs": 120000 },
+  "domainPolicy": { "defaultMaxActionsPerMinute": 60, "blocked": [], "trusted": [] },
+  "killSwitch": { "autoActivation": false, "maxErrors": 5, "windowSeconds": 60 },
+  "audit": { "maxEntries": 10000, "logPath": "~/.safari-pilot/audit.log" },
+  "daemon": { "timeoutMs": 30000 },
+  "healthCheck": { "timeoutMs": 3000 }
+}
+```
+
+Missing file → all defaults. Partial file → deep-merge with defaults. Sensitive domain protections (banking, PayPal, etc.) cannot be overridden via config.
+
+Set `SAFARI_PILOT_CONFIG` env var to use a custom config path.
+
+### Daemon Lifecycle
+
+```bash
+/safari-pilot start   # Start daemon, report PID (idempotent)
+/safari-pilot stop    # Graceful shutdown with SIGKILL fallback
+```
+
 ## Development
 
 ### Building from Source
@@ -246,33 +296,37 @@ Safari Pilot runs on your local machine with access to your real browser session
 # TypeScript server
 npm run build
 
-# Swift daemon
-cd daemon && swift build -c release
-cp .build/release/SafariPilotd ../bin/
+# Swift daemon (rebuild + atomic swap + launchctl restart)
+bash scripts/update-daemon.sh
 
-# Safari extension (requires Xcode)
+# Safari extension (Xcode archive → sign → notarize)
 bash scripts/build-extension.sh
 ```
 
 ### Testing
 
 ```bash
-# All tests
-npm test
+# Default — unit tests, no Safari required
+npm test                    # 398 unit tests
+npm run test:unit           # alias for above
 
-# By category
-npm run test:unit          # 705 tests, no Safari needed
-npm run test:integration   # 372 tests, some need Safari
-npm run test:security      # 27 security-focused tests
-npm run test:e2e           # 31 tests against real Safari
+# Real Safari required (production stack must be running)
+npm run test:e2e            # ~30 e2e tests across 12+ files
+npm run test:e2e:harness    # 5 tests requiring DEBUG_HARNESS build (auto-rebuilds release after)
 
-# Swift daemon tests
-cd daemon && swift run SafariPilotdTests
+# Both
+npm run test:all            # unit + e2e
 
-# Canary deployment
-bash test/canary/install-test.sh
+# Swift daemon (real Swift types, mocked at NSAppleScript boundary only)
+cd daemon && swift test     # 153 tests
 ```
 
+**Test policy:**
+- Unit tests (`test/unit/`) cover pure logic; can mock Node boundaries (`fs`, `net`, `child_process`) but never internal modules.
+- E2E tests (`test/e2e/`) spawn a real MCP server, drive Safari through the real stack, and use ZERO mocks (enforced by pre-commit hook). They fail closed on any `vi.mock` or direct `import from '../../src/'`.
+- The harness-dependent tests (`t21`, `t22`, `t27`, `t44`, `t55a`) require `SAFARI_PILOT_TEST_MODE=1` build markers stripped from production. `npm run test:e2e:harness` automates the test build → run → release-rebuild flow. Local-only (refuses on CI).
+- See `CLAUDE.md` "End-to-End Testing (HARD RULES)" for the full contract.
+
 ### Adding a New Tool
 
 1. Add the handler to the appropriate module in `src/tools/`
@@ -280,6 +334,31 @@ bash test/canary/install-test.sh
 3. Write tests in `test/unit/tools/`
 4. The server auto-registers tools from all modules in `initialize()`
 5. Add the tool name to `skills/safari-pilot/SKILL.md` allowed-tools
+6. If touching `extension/*` or `daemon/Sources/*`, follow `CLAUDE.md` "Extension Build: Hard Rules" — version bump in lockstep, ditto with metadata-stripping flags, run `bash scripts/pre-tag-check.sh` before any tag push.
+
+### Releasing a new version
+
+The release pipeline is automated via `.github/workflows/release.yml` on tag push. Before tagging, run the local SOP gate:
+
+```bash
+# 1. Bump versions in lockstep
+#    Edit package.json + extension/manifest.json (must match)
+
+# 2. Rebuild extension if extension/* changed
+bash scripts/build-extension.sh
+
+# 3. Local install rehearsal
+open "bin/Safari Pilot.app"     # verify in Safari Settings
+
+# 4. Mandatory pre-tag check (mirrors every CI verify step)
+bash scripts/pre-tag-check.sh   # must print "ALL CHECKS PASSED"
+
+# 5. Commit, tag, push
+git tag -a v0.1.X -m "..."
+git push origin main && git push origin v0.1.X
+```
+
+The pre-tag check catches: AppleDouble (`._*`) metadata in zip, codesign --deep --strict failures, missing entitlements, version mismatch, dangling tag, prepublish hook misconfiguration, unit test regressions. It runs in seconds and saves CI round-trips.
 
 ## What Safari Pilot Does NOT Replace
 
@@ -308,7 +387,7 @@ The daemon detects Safari crashes (error codes -600/-609) and retries with expon
 Safari Pilot is built from scratch — no code from third-party Safari MCP packages. Every line that touches your browser is first-party and auditable. We also add 9 security layers, a persistent Swift daemon (92x faster), and structured extraction tools.
 
 **Q: Does the Swift daemon run all the time?**
-Only when Claude Code is active. The LaunchAgent starts the daemon on demand and it shuts down with the session.
+The daemon starts on Claude Code session start (via the SessionStart hook) and stays running between sessions for fast restart. Use `/safari-pilot stop` to shut it down manually. The LaunchAgent auto-restarts it if it crashes.
 
 **Q: Do I need the Safari extension?**
 No — Safari Pilot works without it for ~80% of use cases. The extension adds Shadow DOM traversal, CSP bypass, dialog interception, and network mocking. Install it from the [GitHub Release](https://github.com/RTinkslinger/safari-pilot/releases/latest) if you need those features.

package/bin/Safari Pilot.app/Contents/Info.plist

@@ -23,29 +23,29 @@
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>0.1.3</string>
+	<string>0.1.26</string>
 	<key>CFBundleSupportedPlatforms</key>
 	<array>
 		<string>MacOSX</string>
 	</array>
 	<key>CFBundleVersion</key>
-	<string>202604130112</string>
+	<string>202605041322</string>
 	<key>DTCompiler</key>
 	<string>com.apple.compilers.llvm.clang.1_0</string>
 	<key>DTPlatformBuild</key>
-	<string>25E236</string>
+	<string>25E251</string>
 	<key>DTPlatformName</key>
 	<string>macosx</string>
 	<key>DTPlatformVersion</key>
 	<string>26.4</string>
 	<key>DTSDKBuild</key>
-	<string>25E236</string>
+	<string>25E251</string>
 	<key>DTSDKName</key>
 	<string>macosx26.4</string>
 	<key>DTXcode</key>
-	<string>2640</string>
+	<string>2641</string>
 	<key>DTXcodeBuild</key>
-	<string>17E192</string>
+	<string>17E202</string>
 	<key>LSMinimumSystemVersion</key>
 	<string>26.4</string>
 	<key>NSMainStoryboardFile</key>
@@ -53,6 +53,6 @@
 	<key>NSPrincipalClass</key>
 	<string>NSApplication</string>
 	<key>SFSafariWebExtensionConverterVersion</key>
-	<string>26.4</string>
+	<string>26.4.1</string>
 </dict>
 </plist>

package/bin/Safari Pilot.app/Contents/PlugIns/Safari Pilot Extension.appex/Contents/Info.plist

@@ -19,29 +19,29 @@
 	<key>CFBundlePackageType</key>
 	<string>XPC!</string>
 	<key>CFBundleShortVersionString</key>
-	<string>0.1.3</string>
+	<string>0.1.26</string>
 	<key>CFBundleSupportedPlatforms</key>
 	<array>
 		<string>MacOSX</string>
 	</array>
 	<key>CFBundleVersion</key>
-	<string>202604130112</string>
+	<string>202605041322</string>
 	<key>DTCompiler</key>
 	<string>com.apple.compilers.llvm.clang.1_0</string>
 	<key>DTPlatformBuild</key>
-	<string>25E236</string>
+	<string>25E251</string>
 	<key>DTPlatformName</key>
 	<string>macosx</string>
 	<key>DTPlatformVersion</key>
 	<string>26.4</string>
 	<key>DTSDKBuild</key>
-	<string>25E236</string>
+	<string>25E251</string>
 	<key>DTSDKName</key>
 	<string>macosx26.4</string>
 	<key>DTXcode</key>
-	<string>2640</string>
+	<string>2641</string>
 	<key>DTXcodeBuild</key>
-	<string>17E192</string>
+	<string>17E202</string>
 	<key>LSMinimumSystemVersion</key>
 	<string>10.14</string>
 	<key>NSExtension</key>