a2acalling 0.6.75 → 0.6.76

package/docs/plans/2026-03-06-a2a-100-tauri-auto-updater.md

@@ -0,0 +1,519 @@
+# A2A-100: Tauri Auto-Updater Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add self-update capability to the A2A Callbook macOS app using Tauri's built-in updater plugin, so direct-download users receive updates without manual re-download.
+
+**Architecture:** Uses `tauri-plugin-updater` (official Tauri v2 plugin) with a GitHub Releases-hosted update manifest (`latest.json`). The app checks for updates on launch (background, non-blocking) and shows a dashboard banner when available. CI generates and uploads the manifest alongside existing build artifacts.
+
+**Tech Stack:** Rust (tauri-plugin-updater), vanilla JS (dashboard banner), GitHub Actions CI, shell scripting.
+
+**PREREQUISITE:** A Tauri signing key pair must be generated before this can be fully deployed. Run `cargo tauri signer generate -w ~/.tauri/a2a-callbook.key` on a macOS dev machine. The private key becomes a GitHub Actions secret (`TAURI_SIGNING_PRIVATE_KEY`), and the public key is embedded in `tauri.conf.json`.
+
+---
+
+## Task 1: Add tauri-plugin-updater Dependency
+
+**Files:**
+- Modify: `native/macos/src-tauri/Cargo.toml`
+
+**Step 1: Add the plugin dependency**
+
+Add `tauri-plugin-updater` to the `[dependencies]` section:
+
+```toml
+tauri-plugin-updater = "2"
+```
+
+**Step 2: Commit**
+
+```bash
+git add native/macos/src-tauri/Cargo.toml
+git commit -m "feat(a2a-100): add tauri-plugin-updater dependency"
+```
+
+---
+
+## Task 2: Configure Updater in tauri.conf.json
+
+**Files:**
+- Modify: `native/macos/src-tauri/tauri.conf.json`
+
+**Step 1: Add updater plugin configuration**
+
+Add to the `plugins` section:
+
+```json
+"updater": {
+  "endpoints": [
+    "https://github.com/onthegonow/a2a_calling/releases/latest/download/latest.json"
+  ],
+  "pubkey": "PLACEHOLDER_REPLACE_WITH_ACTUAL_PUBLIC_KEY",
+  "dialog": false
+}
+```
+
+Also update the `bundle` section to include the updater target — add `"updater"` to the `targets` array:
+
+```json
+"targets": ["dmg", "app", "updater"]
+```
+
+**NOTE:** The `pubkey` must be replaced with the actual public key generated by `cargo tauri signer generate`. This is a placeholder that will cause builds to fail until replaced — this is intentional to prevent unsigned updates.
+
+**Step 2: Commit**
+
+```bash
+git add native/macos/src-tauri/tauri.conf.json
+git commit -m "feat(a2a-100): configure Tauri updater plugin"
+```
+
+---
+
+## Task 3: Create updater.rs Module
+
+**Files:**
+- Create: `native/macos/src-tauri/src/updater.rs`
+
+**Step 1: Create the updater module**
+
+This module handles update checking, rate limiting (max once per hour), and emitting events to the frontend.
+
+```rust
+use serde::Serialize;
+use std::sync::Mutex;
+use std::time::{Duration, Instant};
+use tauri::{Emitter, Manager};
+use tauri_plugin_updater::UpdaterExt;
+
+const CHECK_INTERVAL: Duration = Duration::from_secs(3600); // 1 hour
+
+/// Shared state tracking last update check time.
+pub struct UpdateCheckState {
+    last_check: Mutex<Option<Instant>>,
+}
+
+impl UpdateCheckState {
+    pub fn new() -> Self {
+        Self {
+            last_check: Mutex::new(None),
+        }
+    }
+
+    /// Returns true if enough time has passed since the last check.
+    fn should_check(&self) -> bool {
+        let guard = self.last_check.lock().unwrap();
+        match *guard {
+            Some(last) => last.elapsed() >= CHECK_INTERVAL,
+            None => true,
+        }
+    }
+
+    fn mark_checked(&self) {
+        let mut guard = self.last_check.lock().unwrap();
+        *guard = Some(Instant::now());
+    }
+}
+
+#[derive(Clone, Serialize)]
+pub struct UpdateStatus {
+    pub available: bool,
+    pub version: Option<String>,
+    pub body: Option<String>,
+    pub error: Option<String>,
+}
+
+/// Check for updates in the background. Emits "update-status" event to frontend.
+/// Respects rate limit unless `force` is true (for manual checks).
+pub async fn check_for_update(app: tauri::AppHandle, force: bool) {
+    let state = app.state::<UpdateCheckState>();
+
+    if !force && !state.should_check() {
+        return;
+    }
+
+    state.mark_checked();
+
+    let updater = match app.updater() {
+        Ok(u) => u,
+        Err(e) => {
+            let _ = app.emit("update-status", UpdateStatus {
+                available: false,
+                version: None,
+                body: None,
+                error: Some(format!("Updater init failed: {}", e)),
+            });
+            return;
+        }
+    };
+
+    match updater.check().await {
+        Ok(Some(update)) => {
+            let _ = app.emit("update-status", UpdateStatus {
+                available: true,
+                version: Some(update.version.clone()),
+                body: update.body.clone(),
+                error: None,
+            });
+        }
+        Ok(None) => {
+            let _ = app.emit("update-status", UpdateStatus {
+                available: false,
+                version: None,
+                body: None,
+                error: None,
+            });
+        }
+        Err(e) => {
+            let _ = app.emit("update-status", UpdateStatus {
+                available: false,
+                version: None,
+                body: None,
+                error: Some(format!("{}", e)),
+            });
+        }
+    }
+}
+
+/// Download and install the available update. Emits progress events.
+pub async fn install_update(app: tauri::AppHandle) -> Result<(), String> {
+    let updater = app.updater().map_err(|e| format!("Updater init failed: {}", e))?;
+
+    let update = updater
+        .check()
+        .await
+        .map_err(|e| format!("Check failed: {}", e))?
+        .ok_or_else(|| "No update available".to_string())?;
+
+    // A2A-100: Download with progress events
+    let app_clone = app.clone();
+    update
+        .download_and_install(
+            move |chunk_length, content_length| {
+                let _ = app_clone.emit("update-download-progress", serde_json::json!({
+                    "chunkLength": chunk_length,
+                    "contentLength": content_length
+                }));
+            },
+            || {
+                // Download finished — restart will happen after this returns
+            },
+        )
+        .await
+        .map_err(|e| format!("Install failed: {}", e))?;
+
+    Ok(())
+}
+```
+
+**Step 2: Commit**
+
+```bash
+git add native/macos/src-tauri/src/updater.rs
+git commit -m "feat(a2a-100): create updater module with rate-limited checks"
+```
+
+---
+
+## Task 4: Wire Updater into lib.rs
+
+**Files:**
+- Modify: `native/macos/src-tauri/src/lib.rs`
+
+**Step 1: Add module declaration and commands**
+
+Add `mod updater;` after the other mod declarations.
+
+Add two new Tauri commands:
+
+```rust
+#[tauri::command]
+async fn check_update(app: tauri::AppHandle, force: bool) -> Result<(), String> {
+    updater::check_for_update(app, force).await;
+    Ok(())
+}
+
+#[tauri::command]
+async fn install_update(app: tauri::AppHandle) -> Result<(), String> {
+    updater::install_update(app).await
+}
+```
+
+**Step 2: Register the plugin and commands**
+
+In the `run()` function, add the updater plugin:
+
+```rust
+.plugin(tauri_plugin_updater::Builder::new().build())
+```
+
+Add `UpdateCheckState` to managed state:
+
+```rust
+.manage(updater::UpdateCheckState::new())
+```
+
+Add the new commands to the invoke handler:
+
+```rust
+.invoke_handler(tauri::generate_handler![discover_server, start_server, restart_server, check_update, install_update])
+```
+
+**Step 3: Add "Check for Updates" menu item**
+
+In `build_menu()`, add a menu item to the View menu:
+
+```rust
+let check_updates = MenuItem::with_id(app, "check-updates", "Check for Updates\u{2026}", true, None::<&str>)?;
+```
+
+Add it to the view menu items list (before the restart separator).
+
+In the menu event handler, add:
+
+```rust
+"check-updates" => {
+    let handle = app_handle.clone();
+    tauri::async_runtime::spawn(async move {
+        updater::check_for_update(handle, true).await;
+    });
+    None
+}
+```
+
+**Step 4: Trigger background check after setup**
+
+After `notifications::start_event_stream_listener()` in the setup closure, add:
+
+```rust
+// A2A-100: Background update check after app launch (non-blocking)
+let update_handle = app.handle().clone();
+tauri::async_runtime::spawn(async move {
+    // Small delay to let the app finish loading before checking
+    tokio::time::sleep(std::time::Duration::from_secs(5)).await;
+    updater::check_for_update(update_handle, false).await;
+});
+```
+
+**Step 5: Commit**
+
+```bash
+git add native/macos/src-tauri/src/lib.rs
+git commit -m "feat(a2a-100): wire updater plugin, commands, and menu item"
+```
+
+---
+
+## Task 5: Dashboard Update Banner UI
+
+**Files:**
+- Modify: `src/dashboard/public/app.js` — add Tauri update event listeners
+- Modify: `src/dashboard/public/index.html` — add update banner element
+- Modify: `src/dashboard/public/style.css` — add banner styles
+
+**Step 1: Add update banner HTML to index.html**
+
+Add immediately after `<main class="main-content">` and before the bg-orb divs:
+
+```html
+<!-- A2A-100: Native app update notification banner -->
+<div id="update-banner" class="update-banner" style="display:none;">
+  <span class="material-symbols-outlined update-banner-icon">system_update</span>
+  <span id="update-banner-text">A new version is available.</span>
+  <sl-button id="update-banner-install" variant="primary" size="small">Update Now</sl-button>
+  <sl-button id="update-banner-dismiss" variant="text" size="small">Later</sl-button>
+</div>
+```
+
+**Step 2: Add banner CSS to style.css**
+
+```css
+/* A2A-100: Update notification banner */
+.update-banner {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  padding: 0.6rem 1rem;
+  background: rgba(59, 130, 246, 0.12);
+  border: 1px solid rgba(59, 130, 246, 0.3);
+  border-radius: 8px;
+  margin: 0 0 1rem;
+  font-size: 0.9rem;
+}
+
+.update-banner-icon {
+  font-size: 20px;
+  color: var(--accent);
+}
+```
+
+**Step 3: Add Tauri event listeners in app.js**
+
+At the end of the DOMContentLoaded handler, add Tauri-specific update listeners that only activate when running inside the native app:
+
+```js
+// A2A-100: Native app update events (only when running in Tauri)
+if (window.__TAURI__) {
+  const { listen } = window.__TAURI__.event;
+  const { invoke } = window.__TAURI__.core;
+
+  listen('update-status', (event) => {
+    const status = event.payload;
+    const banner = document.getElementById('update-banner');
+    const text = document.getElementById('update-banner-text');
+    if (status.available && status.version) {
+      text.textContent = `Version ${status.version} is available.`;
+      banner.style.display = 'flex';
+    }
+  });
+
+  document.getElementById('update-banner-install')?.addEventListener('click', async () => {
+    const btn = document.getElementById('update-banner-install');
+    btn.loading = true;
+    btn.disabled = true;
+    document.getElementById('update-banner-text').textContent = 'Downloading update...';
+    try {
+      await invoke('install_update');
+    } catch (err) {
+      document.getElementById('update-banner-text').textContent = 'Update failed: ' + (err || 'unknown error');
+      btn.loading = false;
+      btn.disabled = false;
+    }
+  });
+
+  document.getElementById('update-banner-dismiss')?.addEventListener('click', () => {
+    document.getElementById('update-banner').style.display = 'none';
+  });
+}
+```
+
+**Step 4: Run `npm test` to verify no regressions**
+
+Run: `npm test`
+Expected: All tests pass.
+
+**Step 5: Commit**
+
+```bash
+git add src/dashboard/public/index.html src/dashboard/public/app.js src/dashboard/public/style.css
+git commit -m "feat(a2a-100): add update notification banner to dashboard"
+```
+
+---
+
+## Task 6: Generate Update Manifest in CI
+
+**Files:**
+- Modify: `.github/workflows/tauri-build.yml` — add manifest generation and upload steps
+- Create: `scripts/generate-update-manifest.sh` — generates `latest.json`
+
+**Step 1: Create manifest generation script**
+
+```bash
+#!/usr/bin/env bash
+# A2A-100: Generate Tauri updater manifest (latest.json) for GitHub Releases.
+# Usage: bash scripts/generate-update-manifest.sh <version> <signature_file> <notes>
+
+set -euo pipefail
+
+VERSION="${1:?Usage: generate-update-manifest.sh <version> <sig_file> [notes]}"
+SIG_FILE="${2:?Signature file path required}"
+NOTES="${3:-Release v${VERSION}}"
+
+REPO="onthegonow/a2a_calling"
+TAR_NAME="A2A-Callbook-${VERSION}.app.tar.gz"
+URL="https://github.com/${REPO}/releases/download/v${VERSION}/${TAR_NAME}"
+
+if [ ! -f "${SIG_FILE}" ]; then
+  echo "Signature file not found: ${SIG_FILE}" >&2
+  exit 1
+fi
+
+SIGNATURE=$(cat "${SIG_FILE}")
+
+cat <<EOF
+{
+  "version": "${VERSION}",
+  "notes": "${NOTES}",
+  "pub_date": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "platforms": {
+    "darwin-universal": {
+      "signature": "${SIGNATURE}",
+      "url": "${URL}"
+    },
+    "darwin-aarch64": {
+      "signature": "${SIGNATURE}",
+      "url": "${URL}"
+    },
+    "darwin-x86_64": {
+      "signature": "${SIGNATURE}",
+      "url": "${URL}"
+    }
+  }
+}
+EOF
+```
+
+**Step 2: Add CI steps to tauri-build.yml**
+
+After the "Package artifacts" step, before "Upload artifacts", add:
+
+```yaml
+      - name: Generate updater manifest
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          VERSION="$(node -p "require('./package.json').version")"
+          SIG_FILE="native/macos/src-tauri/target/universal-apple-darwin/release/bundle/macos/A2A Callbook.app.tar.gz.sig"
+          bash scripts/generate-update-manifest.sh "${VERSION}" "${SIG_FILE}" "Release v${VERSION}" > latest.json
+```
+
+Add `latest.json` to the upload artifact paths and GitHub Release files.
+
+Also update the `TAURI_SIGNING_PRIVATE_KEY` env var in the build step (change from empty string to the secret):
+
+```yaml
+TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+```
+
+**Step 3: Commit**
+
+```bash
+chmod +x scripts/generate-update-manifest.sh
+git add scripts/generate-update-manifest.sh .github/workflows/tauri-build.yml
+git commit -m "feat(a2a-100): add updater manifest generation to CI"
+```
+
+---
+
+## Task 7: Update CONVENTIONS.md
+
+**Files:**
+- Modify: `CONVENTIONS.md`
+
+**Step 1: Add auto-updater section**
+
+Add after the Native App Sidecar Lifecycle section (or after the Onboarding Wizard section if A2A-99 was merged first):
+
+```markdown
+## Native App Auto-Updater (A2A-100)
+
+The Tauri app uses `tauri-plugin-updater` to check for and install updates from GitHub Releases:
+- Update manifest (`latest.json`) is uploaded as a GitHub Release asset by CI
+- Background check runs 5 seconds after app launch, rate-limited to once per hour via `UpdateCheckState`
+- Manual check available from View → Check for Updates menu and Settings tab
+- Updates require user consent — banner shows in dashboard, user clicks "Update Now"
+- Signing key pair: private key in `TAURI_SIGNING_PRIVATE_KEY` GitHub secret, public key in `tauri.conf.json`
+- Do NOT auto-restart without user consent
+```
+
+**Step 2: Run full test suite**
+
+Run: `npm test`
+Expected: All tests pass.
+
+**Step 3: Commit**
+
+```bash
+git add CONVENTIONS.md
+git commit -m "docs(a2a-100): add auto-updater conventions"
+```