v0.9.0: swrag-helper.app bundle + native notifications

* Convert helper to a code-signed `.app` bundle. macOS TCC tracks raw
  binaries by absolute-path + checksum — both change on every
  `brew upgrade` because the materialised cache path encodes the
  tarball size. A `.app` is tracked by `CFBundleIdentifier` +
  ad-hoc-sign checksum, so Screen Recording / Microphone /
  Notifications grants survive upgrades. Bundle identity:
  `ai.swrag.helper`. Build pipeline lipo's arm64 + x86_64 into
  `Contents/MacOS/swrag-helper`, copies `Info.plist`, signs with
  `codesign --sign -`, then tars to `vendor/swrag-helper.app.tar`.

* New `notify` subcommand in the helper, backed by
  `UNUserNotificationCenter`. Posts a banner with the requested action
  buttons; prints the chosen action lowercased on stdout (or
  `timeout` on banner expiry); exits non-zero with a clear stderr
  message if authorization is denied / not-yet-granted. Run-loop
  driven, no Dock icon (LSUIElement=true). Fail-fast on auth so
  the daemon never deadlocks waiting for a user response.

* Replace the `osascript display dialog` modal start-recording popup
  with a native banner via `fireStartRecordingNotification`.
  Non-modal (no focus theft), Notification-Center-persistent if
  missed, honors Focus / Do Not Disturb. Same daemon-visible
  contract: `"record" | "skip" | "timeout"`. Helper failures
  (auth denied / spawn / bad stdout) degrade to `"timeout"` so the
  daemon never crashes on a notification-path failure.

* TS materialisation switched from single-file embed to tarball
  embed + extract. The tar is `with { type: "file" }`-imported,
  extracted to a stable per-user cache dir on first call, the
  resulting bundle path stays the same across upgrades (this is
  the bit TCC's ad-hoc heuristics care about). Legacy v0.8.x
  raw-binary cache entries are swept on materialisation.

* `permissions-check` gains a fourth permission (`notifications`),
  surfaced through to `swrag doctor`. Includes `provisional` as a
  fifth state (Apple's silent-opt-in notification mode).

* Tests: stub `fireNotification` instead of `osascript` for the
  start-recording path. Real-binary notify smoke runs to a short
  timeout and asserts the stdout shape (skipped via
  `SWRAG_SKIP_NOTIFY_SMOKE=1` for environments where auth state
  is unknown). 374 tests pass; pre-v0.8.0 modal-dialog parser
  tests removed (no longer relevant on the banner path).

Author: NikitaHerndlhofer

.gitignore

@@ -60,6 +60,13 @@ typings/
 # lives in `swift-helper/`; the binary is rebuilt fresh on every release
 # by `scripts/build-swift-helper.sh` (called from `scripts/build.ts`).
 /swift-helper/.build/
+# The Swift helper .app bundle + its tarball are build artifacts.
+# Build via `bash scripts/build-swift-helper.sh`.
+/vendor/swrag-helper.app/
+/vendor/swrag-helper.app.tar
+# Legacy raw-binary path from v0.8.x — the build script removes it
+# automatically, but list it here so a stale checkout doesn't leak
+# the artifact back into commits.
 /vendor/swrag-helper-darwin-universal
 
 # Local-only Homebrew formula used for testing the build pipeline against

package.json

@@ -1,6 +1,6 @@
 {
   "name": "superwhisper-rag",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Local SQL archive for Super Whisper dictation history with full-text + semantic search.",
   "type": "module",
   "private": true,

scripts/build-swift-helper.sh

@@ -1,22 +1,43 @@
 #!/usr/bin/env bash
-# Build the Swift helper for arm64 + x86_64 and lipo into a universal
-# Mach-O at vendor/swrag-helper-darwin-universal.
+# Build the Swift helper for arm64 + x86_64 and assemble a code-signed
+# .app bundle at vendor/swrag-helper.app/. Also emit a deterministic
+# tarball of the bundle at vendor/swrag-helper.app.tar — the compiled
+# swrag CLI embeds the tarball via `with { type: "file" }` and
+# extracts it to a per-user cache dir on first use.
 #
-# Idempotent: re-running with no source changes is a near-noop because
-# SPM caches builds per-arch. Fail clearly when the swift toolchain is
-# missing — Apple's Command Line Tools provide it; we don't fall back
-# to a brittle "install Xcode" path.
+# Why a bundle?
 #
-# Layout:
+#   * macOS TCC tracks raw binaries by (absolute path + checksum).
+#     Both change on every brew upgrade because the per-user cache
+#     dir suffix encodes the file size. Result: Screen Recording /
+#     Microphone grants are revoked on every release.
+#
+#   * A code-signed .app is tracked by (bundle identifier + sign
+#     checksum). Ad-hoc sign with `--sign -` is sufficient for TCC
+#     persistence; we don't need (and can't economically afford) a
+#     Developer ID certificate.
+#
+#   * UNUserNotificationCenter (used by the `notify` subcommand)
+#     refuses to register a delegate or post alerts outside of a
+#     real bundle. The .app is a hard prerequisite for the native
+#     start-recording banner.
+#
+# Idempotent: re-running with no source changes is fast because SPM
+# caches builds per-arch.
+#
+# Layout produced:
 #   swift-helper/.build/{arm64-apple-macosx,x86_64-apple-macosx}/release/SwragHelper
 #   ↓ lipo
-#   vendor/swrag-helper-darwin-universal
+#   vendor/swrag-helper.app/Contents/MacOS/swrag-helper   (universal)
+#   vendor/swrag-helper.app/Contents/Info.plist           (verbatim copy)
+#   vendor/swrag-helper.app.tar                           (tarball of .app)
 set -euo pipefail
 
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 PKG_DIR="$REPO_ROOT/swift-helper"
 VENDOR_DIR="$REPO_ROOT/vendor"
-OUT="$VENDOR_DIR/swrag-helper-darwin-universal"
+APP_DIR="$VENDOR_DIR/swrag-helper.app"
+APP_TAR="$VENDOR_DIR/swrag-helper.app.tar"
 
 if ! command -v swift >/dev/null 2>&1; then
   echo "[swift-helper] error: 'swift' not found on PATH." >&2
@@ -44,11 +65,54 @@ if [[ ! -x "$X64_BIN" ]]; then
   exit 1
 fi
 
-echo "[swift-helper] lipo into $OUT"
-lipo -create -output "$OUT" "$ARM_BIN" "$X64_BIN"
-chmod +x "$OUT"
+# Assemble bundle from scratch. We do `rm -rf` rather than overwriting
+# in place so a previous-run with different layout never lingers.
+rm -rf "$APP_DIR"
+mkdir -p "$APP_DIR/Contents/MacOS"
+
+echo "[swift-helper] lipo into $APP_DIR/Contents/MacOS/swrag-helper"
+lipo -create -output "$APP_DIR/Contents/MacOS/swrag-helper" "$ARM_BIN" "$X64_BIN"
+chmod +x "$APP_DIR/Contents/MacOS/swrag-helper"
+
+cp "$PKG_DIR/Resources/Info.plist" "$APP_DIR/Contents/Info.plist"
+
+# Ad-hoc sign. `--force` lets us re-sign over the existing identity
+# every build (the bundle is fresh, but defensive); `--deep` walks
+# nested executables — we only have one, but future-proofs against
+# adding helper sub-binaries. `--sign -` is the magic ad-hoc identity:
+# no Developer ID required, but produces a stable signature checksum
+# tied to the binary contents + Info.plist that TCC uses to identify
+# the bundle across upgrades.
+echo "[swift-helper] codesign --sign - $APP_DIR"
+codesign --force --deep --sign - "$APP_DIR"
+codesign --verify --deep --strict "$APP_DIR" 2>/dev/null || {
+  echo "[swift-helper] error: codesign verification failed" >&2
+  exit 1
+}
+
+# Tarball the bundle for embedding in the swrag CLI binary. We use
+# `-C` so paths in the tarball start at `swrag-helper.app/...` (not
+# `vendor/swrag-helper.app/...`), which keeps extraction simple on
+# the runtime side. Plain tar (not gzip) — the swrag CLI is already
+# inside a gzipped release tarball, so an inner gzip layer would
+# just waste CPU.
+echo "[swift-helper] tar -> $APP_TAR"
+( cd "$VENDOR_DIR" && tar -cf "$APP_TAR" swrag-helper.app )
+
+# Clean up the legacy raw binary path from v0.8.x so a partial-state
+# checkout (or a tap formula that still points at the old path) fails
+# loudly instead of silently running the previous version.
+LEGACY_RAW="$VENDOR_DIR/swrag-helper-darwin-universal"
+if [[ -e "$LEGACY_RAW" ]]; then
+  echo "[swift-helper] removing legacy raw binary at $LEGACY_RAW"
+  rm -f "$LEGACY_RAW"
+fi
 
-size=$(stat -f%z "$OUT")
-echo "[swift-helper] wrote $OUT ($size bytes)"
+app_size=$(du -sh "$APP_DIR" | awk '{print $1}')
+tar_size=$(stat -f%z "$APP_TAR")
+echo "[swift-helper] bundle: $APP_DIR ($app_size on disk)"
+echo "[swift-helper] tar:    $APP_TAR ($tar_size bytes)"
 echo "[swift-helper] archs:"
-lipo -info "$OUT"
+lipo -info "$APP_DIR/Contents/MacOS/swrag-helper"
+echo "[swift-helper] codesign:"
+codesign -dvv "$APP_DIR" 2>&1 | sed 's/^/  /'

scripts/build.ts

@@ -45,7 +45,9 @@ async function main() {
 
   // The Swift helper is built locally (no npm package to fetch from).
   // We always run the build script — it's idempotent and SPM's cache
-  // makes a no-source-change rebuild near-instant.
+  // makes a no-source-change rebuild near-instant. Starting in v0.9.0
+  // the script produces a code-signed .app bundle plus a tarball; the
+  // tarball is what gets embedded into the swrag CLI binary.
   console.log("[build] building swift helper");
   const helper = Bun.spawnSync({
     cmd: ["bash", "scripts/build-swift-helper.sh"],
@@ -61,9 +63,13 @@ async function main() {
         "`xcode-select --install`.",
     );
   }
-  const helperPath = join(ROOT, "vendor", "swrag-helper-darwin-universal");
-  if (!existsSync(helperPath)) {
-    throw new Error(`swift helper missing after build: ${helperPath}`);
+  const helperTar = join(ROOT, "vendor", "swrag-helper.app.tar");
+  const helperApp = join(ROOT, "vendor", "swrag-helper.app");
+  if (!existsSync(helperTar)) {
+    throw new Error(`swift helper tarball missing after build: ${helperTar}`);
+  }
+  if (!existsSync(helperApp)) {
+    throw new Error(`swift helper bundle missing after build: ${helperApp}`);
   }
 
   if (existsSync(DIST)) rmSync(DIST, { recursive: true, force: true });

src/commands/doctor.ts

@@ -193,10 +193,11 @@ const PERM_LABELS = {
   granted: "granted",
   denied: "DENIED",
   not_determined: "not_determined",
+  provisional: "provisional",
 } as const;
 
 function buildPermissionsCheck(perms: Permissions | null): Check {
-  const name = "macOS permissions (mic + screen + automation)";
+  const name = "macOS permissions (mic + screen + automation + notifications)";
   if (perms == null) {
     return {
       name,
@@ -207,6 +208,11 @@ function buildPermissionsCheck(perms: Permissions | null): Check {
   }
   const mic = PERM_LABELS[perms.microphone];
   const screen = PERM_LABELS[perms.screen_recording];
+  // Notifications: `provisional` is treated as "ok-ish" — it's
+  // Apple's silent-opt-in mode where alerts go straight to
+  // Notification Center without prompting. We still display the
+  // status verbatim so the user knows where they're at.
+  const notif = PERM_LABELS[perms.notifications];
   const automationEntries = Object.entries(perms.automation);
   const automationGranted = automationEntries.filter(([, v]) => v === "granted").length;
   const automationDenied = automationEntries
@@ -218,15 +224,20 @@ function buildPermissionsCheck(perms: Permissions | null): Check {
       : automationDenied.length > 0
         ? `automation=${automationGranted}/${automationEntries.length} granted (denied: ${automationDenied.join(", ")})`
         : `automation=${automationGranted}/${automationEntries.length} granted`;
-  const detail = `mic=${mic}, screen=${screen}, ${automationDetail}`;
+  const detail = `mic=${mic}, screen=${screen}, notifications=${notif}, ${automationDetail}`;
   const anyDenied =
-    perms.microphone === "denied" || perms.screen_recording === "denied" || automationDenied.length > 0;
+    perms.microphone === "denied" ||
+    perms.screen_recording === "denied" ||
+    perms.notifications === "denied" ||
+    automationDenied.length > 0;
   // Treat `not_determined` as soft-fail: the user hasn't been
   // prompted yet; the watcher will prompt on first use. We surface
-  // it so the user knows they can warm them eagerly.
+  // it so the user knows they can warm them eagerly. `provisional`
+  // is the OS's silent-opt-in mode and doesn't need a prompt.
   const anyUndecided =
     perms.microphone === "not_determined" ||
     perms.screen_recording === "not_determined" ||
+    perms.notifications === "not_determined" ||
     automationEntries.some(([, v]) => v === "not_determined");
   const ok = !anyDenied && !anyUndecided;
   return {

src/config.ts

@@ -1,4 +1,4 @@
-export const VERSION = "0.8.0";
+export const VERSION = "0.9.0";
 
 /**
  * Per-call embed timeout. With `keep_alive: "15m"` (our default — see