a2acalling 0.6.74 → 0.6.75

package/docs/plans/2026-03-03-a2a-91-macos-packaging-plan.md

@@ -0,0 +1,144 @@
+# A2A-91: macOS App Packaging Plan
+
+## Executive Summary
+
+A2A Callbook currently exists as a Tauri v2 wrapper (`native/macos/`) that discovers a separately-running Node.js server via port scanning. To distribute a self-contained macOS app, we need to bundle the Node.js Express server as a Tauri sidecar binary, add code signing + notarization, and set up CI/CD for automated builds.
+
+**Recommended approach**: Tauri v2 + `@yao-pkg/pkg` sidecar (pragmatic today), with migration path to Node.js SEA as it matures.
+
+**App Store verdict**: Not viable. Node.js uses V8 JIT which conflicts with Apple's sandbox requirements. Direct DMG distribution with Developer ID signing + notarization is the correct path.
+
+## Current State
+
+| Aspect | Status |
+|--------|--------|
+| Tauri v2 shell | Working (v0.1.0) — menus, tray, deep links, SSE notifications |
+| Server integration | External discovery only (`which a2a` + port scan) |
+| Code signing | Not configured |
+| Notarization | Not configured |
+| Distribution | Unsigned `.app` + `.dmg` via GitHub Releases |
+| CI/CD | `tauri-build.yml` exists but no signing secrets |
+
+## Architecture Decision
+
+### Why Tauri + Sidecar (not Electron)
+
+| Factor | Tauri + Sidecar | Electron |
+|--------|----------------|----------|
+| App size | ~95MB | ~150MB |
+| Memory | ~80MB | ~300MB |
+| Existing code | Keep all Rust code | Rewrite from scratch |
+| Native feel | WebKit (system) | Chromium (bundled) |
+| Risk | Medium (new sidecar pipeline) | High (full rewrite) |
+
+Tauri is already working. The incremental cost of adding a sidecar is far lower than an Electron migration.
+
+### Why @yao-pkg/pkg (not Node.js SEA today)
+
+- **pkg** auto-extracts native `.node` addons (better-sqlite3) — SEA requires manual `process.dlopen()` shims
+- Tauri's official sidecar-nodejs guide recommends pkg
+- Migration to Node.js SEA is straightforward once `--build-sea` stabilizes (Node 25.5+)
+
+### Why not App Store
+
+Node.js embeds V8 JIT. Apple's Guideline 2.5.2 restricts JIT in sandboxed apps. The `com.apple.security.cs.allow-jit` entitlement exists but requires justification and has no precedent for Tauri+Node.js apps. Direct DMG distribution with notarization is the proven path.
+
+## Implementation Phases
+
+### Phase 1: Standalone Node.js Binary (Core)
+
+Create a build pipeline that compiles the Express server + better-sqlite3 into a single executable using `@yao-pkg/pkg`.
+
+**Key challenges:**
+- better-sqlite3 native addon must be compiled for the exact Node.js version pkg embeds
+- Universal binary support (aarch64 + x86_64) requires two pkg builds + `lipo`
+- The standalone binary must respect `A2A_CONFIG_DIR` and all existing env vars
+
+**Deliverables:**
+- `scripts/build-standalone.sh` — compiles server into standalone binary
+- Verification: binary starts, serves dashboard, handles calls in `A2A_RUNTIME=test`
+
+### Phase 2: Tauri Sidecar Integration
+
+Replace the current `which a2a` server discovery in `server.rs` with Tauri's sidecar API.
+
+**Changes:**
+- Place pkg output in `src-tauri/binaries/a2a-server-{target-triple}`
+- Add `externalBin` to `tauri.conf.json`
+- Rewrite `server.rs` to use `app.shell().sidecar("a2a-server")` instead of `which`
+- Update `discovery.rs` to check sidecar health before falling back to external
+- Add graceful shutdown: send SIGTERM to sidecar on app quit
+
+### Phase 3: Code Signing + Notarization
+
+Set up Apple Developer ID signing and notarization for Gatekeeper compliance.
+
+**Requirements:**
+- Apple Developer Program membership ($99/year)
+- Developer ID Application certificate
+- App-specific password or App Store Connect API key
+
+**Changes:**
+- Add signing identity to `tauri.conf.json` `bundle.macOS.signingIdentity`
+- Create entitlements plist (network access, JIT for V8)
+- Add GitHub Actions secrets for signing credentials
+- Notarization via `xcrun notarytool` (Tauri handles this automatically when env vars are set)
+
+### Phase 4: CI/CD Pipeline
+
+Automate the full build → sign → notarize → release pipeline.
+
+**Changes:**
+- Update `tauri-build.yml` to:
+  1. Build standalone Node.js binary (pkg)
+  2. Place in `src-tauri/binaries/`
+  3. Build universal Tauri app (`--target universal-apple-darwin`)
+  4. Sign + notarize
+  5. Upload `.dmg` to GitHub Release
+- Add version sync between `package.json` and `tauri.conf.json`
+
+### Phase 5: Server Lifecycle Management
+
+The self-contained app should fully manage the A2A server lifecycle.
+
+**Changes:**
+- Start sidecar on app launch, stop on quit
+- Restart on crash (with backoff)
+- Port allocation: pick available port, pass to sidecar via args
+- Show server status in tray icon (connected/disconnected already exists)
+- Log sidecar stdout/stderr for debugging
+
+### Phase 6: Testing Infrastructure
+
+Add automated testing for the packaging pipeline.
+
+**Changes:**
+- Smoke test: build standalone binary, verify it starts and responds to `/api/a2a/status`
+- Integration test: build full `.app`, verify sidecar spawns correctly
+- CI matrix: test on macOS 12 (Monterey), 13 (Ventura), 14 (Sonoma), 15 (Sequoia)
+
+## Resource Estimates
+
+| Item | Cost | Recurrence |
+|------|------|------------|
+| Apple Developer Program | $99 | Annual |
+| GitHub Actions macOS runner | ~$0.08/min | Per build |
+| Developer time (Phases 1-6) | ~40-60 hours | One-time |
+
+## Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| better-sqlite3 version mismatch with pkg | Medium | High | Pin Node.js version, test in CI |
+| Apple notarization rejection | Low | High | Entitlements plist, hardened runtime |
+| pkg deprecation (community fork) | Medium | Medium | Migration path to Node.js SEA ready |
+| V8 JIT blocked by future macOS | Low | High | Monitor Apple policy; sql.js (Wasm) fallback for SQLite |
+
+## Migration Path to Node.js SEA
+
+When Node.js SEA `--build-sea` reaches stability (currently 1.1 as of Node 25.5):
+1. Replace `@yao-pkg/pkg` with `node --build-sea`
+2. Add esbuild bundling step (pkg handles this; SEA needs it explicit)
+3. Add `process.dlopen()` shim for better-sqlite3
+4. Update `scripts/build-standalone.sh`
+5. No Tauri changes needed — sidecar interface is the same

package/docs/signing-setup.md

@@ -0,0 +1,49 @@
+# macOS Signing & Notarization Setup (A2A-94)
+
+This document describes the required Apple credentials for signed, notarized macOS release artifacts.
+
+## Prerequisites
+
+- Apple Developer Program membership (active)
+- Developer ID Application certificate for your team
+- Access to GitHub repository secrets for this project
+
+## 1) Create a Developer ID Application certificate
+
+1. Open Apple Developer portal → Certificates, IDs & Profiles.
+2. Create a new **Developer ID Application** certificate.
+3. Export the certificate + private key from Keychain as `.p12`.
+4. Protect the `.p12` export with a strong password.
+
+## 2) Create GitHub Actions secrets
+
+Upload the following repository secrets:
+
+- `APPLE_CERTIFICATE`: base64-encoded `.p12` archive
+- `APPLE_CERTIFICATE_PASSWORD`: password used for `.p12` export
+- `APPLE_SIGNING_IDENTITY`: exact certificate identity string
+- `APPLE_ID`: Apple account email used for notarization
+- `APPLE_PASSWORD`: app-specific password for notarization
+- `APPLE_TEAM_ID`: Apple Developer Team ID
+
+Example identity format:
+
+```text
+Developer ID Application: Your Name (TEAMID)
+```
+
+## 3) Validate the release output
+
+The macOS build workflow verifies all three checks before publishing artifacts:
+
+- `codesign --verify --deep --strict` on the `.app`
+- `spctl --assess --type execute` on the `.app`
+- `xcrun stapler validate` on the `.dmg`
+
+A release is considered valid only when all checks pass.
+
+## Security notes
+
+- Never commit `.p12`, `.cer`, or private key material.
+- Keep certificate exports in a local, encrypted store only.
+- Rotate Apple app-specific passwords if they are exposed.

package/native/macos/src-tauri/capabilities/default.json

@@ -11,6 +11,16 @@
     "notification:allow-request-permission",
     "notification:allow-notify",
     "deep-link:default",
-    "window-state:default"
+    "window-state:default",
+    {
+      "identifier": "shell:allow-execute",
+      "allow": [
+        {
+          "name": "binaries/a2a-server",
+          "sidecar": true,
+          "args": true
+        }
+      ]
+    }
   ]
 }

package/native/macos/src-tauri/entitlements.plist

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>com.apple.security.cs.allow-jit</key>
+    <true/>
+    <key>com.apple.security.network.client</key>
+    <true/>
+    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
+    <true/>
+    <key>com.apple.security.cs.disable-library-validation</key>
+    <true/>
+</dict>
+</plist>

package/native/macos/src-tauri/src/discovery.rs

@@ -139,11 +139,22 @@ async fn probe_port(port: u16) -> bool {
     false
 }
 
-/// Discover the running a2a server
-pub async fn discover_server() -> DiscoveryResult {
+/// Discover the running a2a server.
+/// If `sidecar_port` is provided, check it first before config/scan fallback.
+pub async fn discover_server(sidecar_port: Option<u16>) -> DiscoveryResult {
+    // 0. Check sidecar port first (highest priority)
+    if let Some(port) = sidecar_port {
+        if probe_port(port).await {
+            return DiscoveryResult {
+                port: Some(port),
+                source: "sidecar".to_string(),
+            };
+        }
+    }
+
     let config_ports = read_config_ports();
 
-    // 1. Try config-derived ports first
+    // 1. Try config-derived ports
     for &port in &config_ports {
         if probe_port(port).await {
             return DiscoveryResult {

package/native/macos/src-tauri/src/health.rs

@@ -18,6 +18,10 @@ pub fn set_connected(port: u16) {
     CONNECTED.store(true, Ordering::Relaxed);
 }
 
+pub fn set_disconnected() {
+    CONNECTED.store(false, Ordering::Relaxed);
+}
+
 /// Start background health check loop — emits "server-status" events
 pub fn start_health_monitor(app: tauri::AppHandle) {
     tauri::async_runtime::spawn(async move {

package/native/macos/src-tauri/src/lib.rs

@@ -9,8 +9,13 @@ mod notifications;
 mod server;
 
 #[tauri::command]
-async fn discover_server() -> Result<discovery::DiscoveryResult, String> {
-    let result = discovery::discover_server().await;
+async fn discover_server(app: tauri::AppHandle) -> Result<discovery::DiscoveryResult, String> {
+    let sidecar_port = app
+        .try_state::<server::SidecarState>()
+        .map(|state| state.port())
+        .filter(|&p| p > 0);
+
+    let result = discovery::discover_server(sidecar_port).await;
     if let Some(port) = result.port {
         health::set_connected(port);
     }
@@ -18,8 +23,19 @@ async fn discover_server() -> Result<discovery::DiscoveryResult, String> {
 }
 
 #[tauri::command]
-fn start_server() -> Result<server::StartResult, String> {
-    Ok(server::start_server())
+fn start_server(app: tauri::AppHandle) -> Result<server::StartResult, String> {
+    Ok(server::start_sidecar(&app))
+}
+
+#[tauri::command]
+fn restart_server(app: tauri::AppHandle) -> Result<server::StartResult, String> {
+    let result = server::restart_sidecar(&app);
+    if result.success {
+        if let Some(port) = result.port {
+            health::set_connected(port);
+        }
+    }
+    Ok(result)
 }
 
 fn build_menu(app: &tauri::AppHandle) -> tauri::Result<Menu<tauri::Wry>> {
@@ -45,9 +61,10 @@ fn build_menu(app: &tauri::AppHandle) -> tauri::Result<Menu<tauri::Wry>> {
     let logs = MenuItem::with_id(app, "tab-logs", "Logs", true, Some("CmdOrCtrl+5"))?;
     let sep2 = PredefinedMenuItem::separator(app)?;
     let refresh = MenuItem::with_id(app, "refresh", "Refresh", true, Some("CmdOrCtrl+R"))?;
+    let restart = MenuItem::with_id(app, "restart-server", "Restart Server", true, None::<&str>)?;
 
     let view_menu = Submenu::with_items(app, "View", true, &[
-        &contacts, &calls, &settings, &invites, &logs, &sep2, &refresh,
+        &contacts, &calls, &settings, &invites, &logs, &sep2, &refresh, &restart,
     ])?;
 
     // Edit menu (standard macOS)
@@ -74,7 +91,8 @@ pub fn run() {
         .plugin(tauri_plugin_notification::init())
         .plugin(tauri_plugin_deep_link::init())
         .plugin(tauri_plugin_window_state::Builder::new().build())
-        .invoke_handler(tauri::generate_handler![discover_server, start_server])
+        .manage(server::SidecarState::new())
+        .invoke_handler(tauri::generate_handler![discover_server, start_server, restart_server])
         .setup(|app| {
             let menu = build_menu(app.handle())?;
             app.set_menu(menu)?;
@@ -96,6 +114,15 @@ pub fn run() {
                         }
                         None
                     }
+                    "restart-server" => {
+                        let result = server::restart_sidecar(&app_handle);
+                        if result.success {
+                            if let Some(port) = result.port {
+                                health::set_connected(port);
+                            }
+                        }
+                        None
+                    }
                     _ => None,
                 };
 
@@ -107,6 +134,14 @@ pub fn run() {
                 }
             });
 
+            // Start the bundled A2A server sidecar
+            let start_result = server::start_sidecar(app.handle());
+            if start_result.success {
+                if let Some(port) = start_result.port {
+                    health::set_connected(port);
+                }
+            }
+
             // Start background health monitor
             health::start_health_monitor(app.handle().clone());
 
@@ -173,13 +208,19 @@ pub fn run() {
         .build(tauri::generate_context!())
         .expect("error building A2A Callbook");
 
-    // Cmd+W hides window instead of quitting
+    // Cmd+W hides window instead of quitting; kill sidecar on exit
     app.run(|app_handle, event| {
-        if let RunEvent::WindowEvent { label, event: WindowEvent::CloseRequested { api, .. }, .. } = &event {
-            api.prevent_close();
-            if let Some(window) = app_handle.get_webview_window(label) {
-                let _ = window.hide();
+        match &event {
+            RunEvent::WindowEvent { label, event: WindowEvent::CloseRequested { api, .. }, .. } => {
+                api.prevent_close();
+                if let Some(window) = app_handle.get_webview_window(label) {
+                    let _ = window.hide();
+                }
+            }
+            RunEvent::Exit => {
+                server::kill_sidecar(app_handle);
             }
+            _ => {}
         }
     });
 }