M6: onboarding, app bundle scripts, shortcuts

[kalil0321]

Final stack PR — distribution polish.

What's in

• OnboardingView — 3-step welcome sheet shown once on first launch (gated by @AppStorage("hasCompletedOnboarding")). Each step has a button that triggers the corresponding action, with live "Installed / Active / Capturing" state.
• Keyboard shortcuts — ⌘R toggle capture, ⌘K clear flows, ⇧⌘E export HAR.
• Resources/Info.plist — bundle metadata, LSMinimumSystemVersion=14.0, AppleEvents usage description for the networksetup prompt.
• Resources/ReverseAPI.entitlements — hardened-runtime compatible, no sandbox (the proxy + Keychain + AppleScript flow needs full access), network.client + network.server + automation.apple-events.
• scripts/build-app.sh — universal swift build (arm64 + x86_64), assembles build/ReverseAPI.app/Contents/{MacOS,Info.plist,Resources}.
• scripts/sign-and-notarize.sh — codesign with SIGNING_IDENTITY, deep verify, optional NOTARY_PROFILE-driven notarytool submit --wait + staple.
• scripts/make-dmg.sh — hdiutil DMG with /Applications symlink, optional resigning of the DMG.

Release flow

cd macos
./scripts/build-app.sh
SIGNING_IDENTITY="Developer ID Application: …" \
NOTARY_PROFILE="rae-notary" \
  ./scripts/sign-and-notarize.sh
./scripts/make-dmg.sh

Drops build/ReverseAPI.dmg. Upload to a GitHub release and ship.

Out of scope

• App icon (placeholder; add Resources/AppIcon.icns)
• Auto-update (Sparkle) — can layer in if needed
• Python sidecar bundling — backend still lives at ~/Library/Application Support/ReverseAPI/...-relative or PATH's python3 for now; bundling python-build-standalone is a follow-up

---

Generated by Claude Code

---

Summary by cubic

Adds a first-launch onboarding flow, a universal macOS app bundle with an embedded Python runtime, and scripts to sign/notarize and package a DMG. Polishes branding and reliability with light/dark themes, a splash screen, Fraunces wordmark, and crash-safe proxy recovery.

• New Features

  • Onboarding: 3-step sheet (trust CA → enable system proxy → start capture) with live status; shown once via @AppStorage("hasCompletedOnboarding").
  • Reliability: persist pre-app proxy snapshot to disk before enabling; only load/restore if the system proxy points at our port; SIGINT/SIGTERM/SIGHUP handlers restore the proxy before exit.
  • UI/Brand: dynamic light/dark theme; Fraunces italic bundled and registered at app init; section headers use it; composer input is brighter with a 1pt border and a brand‑pink send button; capture dot is brand‑pink with a gentle pulse; search button gets a pink hover accent; status chips use a softer elevated background.
  • Launch splash: short “rae” splash with a subtle asterisk animation that fades into the main window.

• Distribution

  • Bundle: Resources/Info.plist (min macOS 14.0, AppleEvents usage, automatic/sudden termination disabled) and Resources/rae.entitlements (Hardened Runtime; no sandbox; network.client, network.server, automation.apple-events).
  • Build: scripts/build-app.sh (universal arm64/x86_64; outputs macos/build/rae.app; copies static Info.plist; copies SwiftPM resource bundle ReverseAPI_ReverseAPI.bundle for fonts; embeds Python at Contents/Resources/agent-runtime; installs backend; trims caches; unsets proxy env vars before uv).
  • Signing/Packaging: scripts/sign-and-notarize.sh (codesigns with entitlements; explicitly signs nested runtime components; optional notarytool submit + staple) and scripts/make-dmg.sh (DMG with /Applications symlink; EXIT-trap cleanup; optional DMG signing).

^{Written for commit 0d92412. Summary will update on new commits. Review in cubic}

Greptile Summary

This PR delivers the final distribution layer for the app: a first-launch onboarding sheet, keyboard shortcuts, a production-ready Info.plist and trimmed entitlements file, and three shell scripts to build a universal app bundle, codesign/notarize it, and package it as a DMG. It also adds an important reliability improvement — the pre-proxy snapshot is now persisted to disk so a crash or abrupt kill can restore the user's original network settings on next launch.

• Onboarding flow: OnboardingView is a 3-step sheet gated by @AppStorage(\"hasCompletedOnboarding\"); both footer buttons explicitly set the flag before calling dismiss(). However, the set: closure on the isPresented binding in ContentView still fires when the sheet is dismissed via Escape, silently marking onboarding complete without any setup step.
• Crash-recovery: applySystemProxy now writes the snapshot to disk before enabling the proxy and deletes it on every clean restore/disable path; SIGINT/SIGTERM/SIGHUP dispatch sources call restoreProxyBeforeExit before re-raising.
• Distribution scripts: make-dmg.sh correctly places the EXIT trap immediately after mktemp; sign-and-notarize.sh drops deprecated --deep and signs nested runtime components explicitly; entitlements have been stripped to the minimal required set.

Confidence Score: 4/5

Safe to merge once the onboarding sheet binding is fixed; all other changes are additive and well-guarded.

The sheet binding set: closure still silently marks onboarding complete when the user presses Escape, leaving CA trust, system proxy, and capture steps uncompleted with no way for the sheet to reappear on next launch. Everything else — crash-recovery snapshot, signal handlers, trimmed entitlements, and distribution scripts — looks correct.

macos/Sources/ReverseAPI/UI/ContentView.swift — the isPresented binding set: clause needs to be a no-op and .interactiveDismissDisabled() added to the sheet content.

Important Files Changed

Filename	Overview
macos/Sources/ReverseAPI/UI/ContentView.swift	Adds onboarding sheet wiring; the binding's set: closure still marks completion on Escape dismiss, violating the explicit design intent
macos/Sources/ReverseAPI/UI/OnboardingView.swift	New 3-step onboarding sheet; explicit button handlers correctly set the completion flag and call dismiss()
macos/Sources/ReverseAPI/App/AppState.swift	Adds disk-backed proxy snapshot for crash-recovery; snapshot is written before enabling proxy and deleted on every clean exit/restore path
macos/Sources/ReverseAPI/App/ReverseAPIApp.swift	Adds SIGINT/SIGTERM/SIGHUP dispatch-source handlers to restore proxy before process exit; re-raises the signal for correct exit status
macos/Resources/rae.entitlements	Entitlements file trimmed to the minimal required set: sandbox=false, network.client/server, automation.apple-events
macos/Resources/Info.plist	NSSupportsAutomaticTermination and NSSupportsSuddenTermination both set to false; LSMinimumSystemVersion=14.0 and NSAppleEventsUsageDescription added
macos/scripts/build-app.sh	Updated for universal arm64+x86_64 build; copies static Info.plist and optional AppIcon from Resources/
macos/scripts/sign-and-notarize.sh	New script; drops deprecated --deep for signing, signs nested runtime components explicitly, EXIT trap cleans up ZIP artifact
macos/scripts/make-dmg.sh	New script; EXIT trap for STAGING directory placed immediately after mktemp, correctly covers all failure paths
macos/Sources/ReverseAPIProxy/System/SystemProxyController.swift	Adds Codable conformance and explicit memberwise initializer to ProxyServiceSnapshot to support JSON disk persistence

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
macos/Sources/ReverseAPI/UI/ContentView.swift:110-115
**Sheet `set:` closure still marks onboarding complete on Escape**

The binding's `set: { if !$0 { hasCompletedOnboarding = true } }` runs any time SwiftUI transitions `isPresented` to `false`, including when the user presses Escape to dismiss the sheet. On macOS this is a natural keyboard shortcut for closing dialogs, so a user who presses Escape without completing any setup step has their onboarding silently flagged as done — contradicting the code comment's stated guarantee ("closing the window before acknowledging doesn't silently mark it complete").

Fix: make `set:` a no-op and add `.interactiveDismissDisabled()` to `OnboardingView`. The explicit button handlers in `OnboardingView` already set `hasCompletedOnboarding = true` before calling `dismiss()`, so the binding's `get:` will return `false` on the next render and the sheet will stay closed. Any non-button dismiss path (Escape, window close) will leave `hasCompletedOnboarding = false` and the sheet will reappear on next launch.

```suggestion
        .sheet(isPresented: Binding(
            get: { !hasCompletedOnboarding },
            set: { _ in } // completion is set only by explicit button actions inside OnboardingView
        )) {
            OnboardingView(hasCompletedOnboarding: $hasCompletedOnboarding)
                .interactiveDismissDisabled()
        }
```

_{Reviews (4): Last reviewed commit: "fix(macos): gate persisted snapshot load..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

[cubic-dev-ai]

2 issues found across 8 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[kind-agent]

⚠️ Error — The test run failed unexpectedly.

Grok 4 Fast is deprecated. xAI recommends switching to Grok 4.3 (https://openrouter.ai/x-ai/grok-4.3)

This is likely a transient issue. You can re-trigger a run from the dashboard.

[kalil0321]

@greptile review

---

Generated by Claude Code

[kalil0321]

@greptile review

---

Generated by Claude Code

[cubic-dev-ai]

2 issues found across 3 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[chatgpt-codex-connector]

To use Codex here, create a Codex account and connect to github.

[cubic-dev-ai]

4 issues found across 10 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="macos/Sources/ReverseAPI/UI/ContentView.swift">

<violation number="1" location="macos/Sources/ReverseAPI/UI/ContentView.swift:112">
P2: The sheet binding setter completes onboarding on any dismiss, which bypasses the intended explicit "Get started/Skip" acknowledgment flow.</violation>
</file>

<file name="macos/scripts/sign-and-notarize.sh">

<violation number="1" location="macos/scripts/sign-and-notarize.sh:52">
P2: The nested runtime signing pass is incomplete: it only signs `.dylib`/`.so` files, so other executable code in `agent-runtime` can remain unsigned and break verification/notarization.</violation>
</file>

<file name="macos/Sources/ReverseAPI/App/ReverseAPIApp.swift">

<violation number="1" location="macos/Sources/ReverseAPI/App/ReverseAPIApp.swift:111">
P2: If a signal arrives while `isTerminating` is already true, the handler returns without re-raising the signal, which can leave the process stuck and unresponsive to normal termination signals.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The sheet binding setter completes onboarding on any dismiss, which bypasses the intended explicit "Get started/Skip" acknowledgment flow.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At macos/Sources/ReverseAPI/UI/ContentView.swift, line 112:

<comment>The sheet binding setter completes onboarding on any dismiss, which bypasses the intended explicit "Get started/Skip" acknowledgment flow.</comment>

<file context>
@@ -102,6 +107,12 @@ struct ContentView: View {
         }
+        .sheet(isPresented: Binding(
+            get: { !hasCompletedOnboarding },
+            set: { if !$0 { hasCompletedOnboarding = true } }
+        )) {
+            OnboardingView(hasCompletedOnboarding: $hasCompletedOnboarding)
</file context>

Suggested change

	set: { if !$0 { hasCompletedOnboarding = true } }
	set: { _ in }

[cubic-dev-ai]

P2: The nested runtime signing pass is incomplete: it only signs .dylib/.so files, so other executable code in agent-runtime can remain unsigned and break verification/notarization.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At macos/scripts/sign-and-notarize.sh, line 52:

<comment>The nested runtime signing pass is incomplete: it only signs `.dylib`/`.so` files, so other executable code in `agent-runtime` can remain unsigned and break verification/notarization.</comment>

<file context>
@@ -0,0 +1,90 @@
+        codesign --force --options runtime --timestamp \
+            --sign "$SIGNING_IDENTITY" \
+            "$bin"
+    done < <(find "$EMBEDDED_RUNTIME" \( -name "*.dylib" -o -name "*.so" \) -print0)
+    if [ -x "$EMBEDDED_RUNTIME/bin/python3" ]; then
+        codesign --force --options runtime --timestamp \
</file context>

[cubic-dev-ai]

P2: If a signal arrives while isTerminating is already true, the handler returns without re-raising the signal, which can leave the process stuck and unresponsive to normal termination signals.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At macos/Sources/ReverseAPI/App/ReverseAPIApp.swift, line 111:

<comment>If a signal arrives while `isTerminating` is already true, the handler returns without re-raising the signal, which can leave the process stuck and unresponsive to normal termination signals.</comment>

<file context>
@@ -77,6 +78,47 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
+
+    @MainActor
+    private func handleSignal(_ sig: Int32) {
+        guard !isTerminating else { return }
+        isTerminating = true
+        // Synchronous restore — we have no async budget once the OS has
</file context>

Suggested change

	guard !isTerminating else { return }
	guard !isTerminating else {
	signal(sig, SIG_DFL)
	raise(sig)
	return
	}

[greptile-apps]

Sheet set: closure still marks onboarding complete on Escape

The binding's set: { if !$0 { hasCompletedOnboarding = true } } runs any time SwiftUI transitions isPresented to false, including when the user presses Escape to dismiss the sheet. On macOS this is a natural keyboard shortcut for closing dialogs, so a user who presses Escape without completing any setup step has their onboarding silently flagged as done — contradicting the code comment's stated guarantee ("closing the window before acknowledging doesn't silently mark it complete").

Fix: make set: a no-op and add .interactiveDismissDisabled() to OnboardingView. The explicit button handlers in OnboardingView already set hasCompletedOnboarding = true before calling dismiss(), so the binding's get: will return false on the next render and the sheet will stay closed. Any non-button dismiss path (Escape, window close) will leave hasCompletedOnboarding = false and the sheet will reappear on next launch.

Suggested change

	.sheet(isPresented: Binding(
	get: { !hasCompletedOnboarding },
	set: { if !$0 { hasCompletedOnboarding = true } }
	)) {
	OnboardingView(hasCompletedOnboarding: $hasCompletedOnboarding)
	}
	.sheet(isPresented: Binding(
	get: { !hasCompletedOnboarding },
	set: { _ in } // completion is set only by explicit button actions inside OnboardingView
	)) {
	OnboardingView(hasCompletedOnboarding: $hasCompletedOnboarding)
	.interactiveDismissDisabled()
	}

Prompt To Fix With AI

This is a comment left during a code review.
Path: macos/Sources/ReverseAPI/UI/ContentView.swift
Line: 110-115

Comment:
**Sheet `set:` closure still marks onboarding complete on Escape**

The binding's `set: { if !$0 { hasCompletedOnboarding = true } }` runs any time SwiftUI transitions `isPresented` to `false`, including when the user presses Escape to dismiss the sheet. On macOS this is a natural keyboard shortcut for closing dialogs, so a user who presses Escape without completing any setup step has their onboarding silently flagged as done — contradicting the code comment's stated guarantee ("closing the window before acknowledging doesn't silently mark it complete").

Fix: make `set:` a no-op and add `.interactiveDismissDisabled()` to `OnboardingView`. The explicit button handlers in `OnboardingView` already set `hasCompletedOnboarding = true` before calling `dismiss()`, so the binding's `get:` will return `false` on the next render and the sheet will stay closed. Any non-button dismiss path (Escape, window close) will leave `hasCompletedOnboarding = false` and the sheet will reappear on next launch.

```suggestion
        .sheet(isPresented: Binding(
            get: { !hasCompletedOnboarding },
            set: { _ in } // completion is set only by explicit button actions inside OnboardingView
        )) {
            OnboardingView(hasCompletedOnboarding: $hasCompletedOnboarding)
                .interactiveDismissDisabled()
        }
```

How can I resolve this? If you propose a fix, please make it concise.

[cubic-dev-ai]

2 issues found across 7 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="macos/Sources/ReverseAPI/UI/Fonts.swift">

<violation number="1" location="macos/Sources/ReverseAPI/UI/Fonts.swift:31">
P3: Use Logger instead of print for diagnostic messages so font-loading issues are visible in Console.app on production builds.</violation>

<violation number="2" location="macos/Sources/ReverseAPI/UI/Fonts.swift:37">
P3: Use Logger instead of print for diagnostic messages so font registration failures are visible in Console.app on production builds.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: Use Logger instead of print for diagnostic messages so font registration failures are visible in Console.app on production builds.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At macos/Sources/ReverseAPI/UI/Fonts.swift, line 37:

<comment>Use Logger instead of print for diagnostic messages so font registration failures are visible in Console.app on production builds.</comment>

<file context>
@@ -0,0 +1,53 @@
+            var error: Unmanaged<CFError>?
+            if !CTFontManagerRegisterFontsForURL(url as CFURL, .process, &error) {
+                let message = (error?.takeRetainedValue()).map { String(describing: $0) } ?? "unknown"
+                print("[BrandFont] failed to register \(name): \(message)")
+            }
+        }
</file context>

[cubic-dev-ai]

P3: Use Logger instead of print for diagnostic messages so font-loading issues are visible in Console.app on production builds.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At macos/Sources/ReverseAPI/UI/Fonts.swift, line 31:

<comment>Use Logger instead of print for diagnostic messages so font-loading issues are visible in Console.app on production builds.</comment>

<file context>
@@ -0,0 +1,53 @@
+            let url = Bundle.module.url(forResource: name, withExtension: "ttf", subdirectory: "Resources")
+                ?? Bundle.module.url(forResource: name, withExtension: "ttf")
+            guard let url else {
+                print("[BrandFont] \(name).ttf not found in bundle — falling back to system font")
+                continue
+            }
</file context>

[cubic-dev-ai]

You're iterating quickly on this pull request. To help protect your rate limits, cubic has paused automatic reviews on new pushes for now—when you're ready for another review, comment @cubic-dev-ai review.