feat: macOS GUI .app dual-track bundle — GUI + bestasr-mcp + CLI, signed/notarized/stapled

[kiki830621]

Problem

bestASR currently ships three surfaces: the CLI, the Claude Code plugin
(~/bin auto-download of the notarized bestasr-mcp, #80), and the MCP
server. A Claude Desktop .mcpb extension was considered but parked: in
Desktop's chat surface, a long transcription means the human sits waiting in the
chat with no progress — a bad UX for exactly the workload bestASR is for.

A macOS GUI .app is the better human-facing vehicle, and it can be
dual-track: the same signed bundle hosts the GUI (for humans, with a
progress UI) and the bestasr-mcp helper (for agents), from one artifact.

Original text (maintainer, roadmap discussion 2026-07-09):
「中期：做 macOS GUI .app，把 bestASR(GUI) + bestasr-mcp + bestasr(CLI) 打包進一顆 signed+stapled bundle，雙軌上線。這是新產品級投入（SwiftUI、檔案選擇、進度、結果檢視、設定），真要動我會照規矩用 apple-xcode-skills（SwiftUI）來寫，不憑記憶硬幹。」

Type

feature

Expected

A SwiftUI macOS app bundling all executables into one bundle:

bestASR.app/Contents/MacOS/
├── bestASR          # GUI (double-click; file picker, progress, results, settings)
├── bestasr-mcp      # MCP helper — claude mcp add bestasr -- /Applications/bestASR.app/Contents/MacOS/bestasr-mcp
└── bestasr          # CLI

• One Developer ID sign + notarize + STAPLE (stapling = offline
  verification, which the bare ~/bin binary cannot do — bare executables
  aren't stapleable).
• Drag-to-/Applications install; no terminal, no build-from-source.
• Additive — the Claude Code plugin (~/bin auto-download, enhancement: MCP server surface — 第三個消費面（CLI / plugin / MCP 三位一體） #80) path stays
  untouched. This is a 4th surface (a GUI for humans), not a replacement.

Actual

No GUI. Humans either use the CLI or wait in a blocking MCP chat with no
progress. The only one-artifact install today is the Claude Code plugin, which
is agent-facing.

Impact

• Reaches humans who want "drag a file → get an SRT" without Claude / terminal.
• Better TCC story: a real .app bundle identity + Info.plist usage
  descriptions vs. a bare ~/bin binary.
• Better notarization: a stapled bundle verifies offline.

Constraints / notes:

• New-product-level investment (SwiftUI, file pickers, progress, results view,
  settings) — not a packaging change. Scope accordingly.
• MUST use apple-xcode-skills (swiftui-specialist etc.) — Apple's official
  current guidance, not from-memory Swift.
• Reuses the che-mcps-notary sign/notarize pipeline (already provisioned).
• The binary stays small; models still download at runtime (~1.5 GB to
  ~/.cache) — same as today.
• The async MCP job mode (feat: MCP transcribe async job mode — non-blocking transcribe for agents on long audio #86) benefits the bundled bestasr-mcp helper too
  (solves the agent long-wait; the GUI solves the human long-wait).

---

Related: #86 (MCP async job mode — the agent-side half of the long-wait problem).
Priority: P3 (mid-term).

[kiki830621]

Diagnosis

Type

feature

Root Cause / Analysis

Requirements breakdown (from the issue's Expected + constraints):

1. SwiftUI GUI executable — a human-facing macOS app: file picker + drag-and-drop, backend/model/language/effort selection, progress during transcription, result view, export (SRT/VTT/TXT), settings. New-product-level surface, explicitly scoped as such by the issue.
2. Dual-track bundle — one bestASR.app whose Contents/MacOS/ carries three executables: the GUI, bestasr-mcp (agents point claude mcp add at the bundle path), and the bestasr CLI. Additive: the existing Claude Code plugin ~/bin auto-download path stays untouched.
3. Sign + notarize + staple pipeline — Developer ID + hardened runtime for every nested executable and the bundle, notarized via the existing che-mcps-notary keychain profile, stapled (the bundle form finally allows offline Gatekeeper verification, which bare ~/bin binaries cannot).
4. Hard constraint — all SwiftUI work MUST go through apple-xcode-skills (swiftui-specialist), per the issue and the maintainer's standing instruction; no from-memory SwiftUI.

Existing assets to reuse: CommandCore (Sendable, engine-injectable — the GUI calls the same core as the CLI/MCP), BestASRVersion, the release-mcp.sh sign/notarize scaffolding (#85), and the async-job groundwork (#86) that already solved the agent half of the long-wait problem.

Impact

• New target(s) in Package.swift (SwiftUI executable), new Sources/bestasr-gui/ (or similar) app code.
• New packaging script (scripts/release-app.sh or equivalent): universal build → bundle assembly (Info.plist, icons optional in v1) → codesign nested binaries + bundle → notarize → staple → dmg/zip artifact.
• Docs: README install section gains the .app track.
• No changes to existing CLI/MCP/plugin behavior (additive surface Turn bestASR into a Claude plugin marketplace with an agent-facing plugin (sibling concern from #3) #4).

Strategy

• Design fork resolution (spectra-discuss): SwiftPM-built SwiftUI app vs Xcode project; progress model for v1 (stage + elapsed vs true percent); single-file vs batch v1; bundle identity/Info.plist shape.
• Spec the capability (spectra-propose): new gui-app capability spec (ADDED requirements: GUI flow, dual-track bundle contents, sign/notarize/staple gate) + tasks.
• Implement (spectra-apply): SwiftUI app (view model with injected core, testable), bundle assembly script, signing pipeline reuse; load apple-xcode-skills:swiftui-specialist before writing SwiftUI.
• Verify (opus adversarial) + PR.

Conflict Class

A_parallel_safe — new target + new script + docs; no shared mutable resource with in-flight work (no other active changes remain after the #80/#86/#88 archive).

Complexity

Spectra — Layer 2/3: new product-level capability, multiple subsystems (app target, packaging, signing), architecture decisions with trade-offs (SwiftPM vs Xcode project, progress model), and a spec-worthy durable surface (bundle contract + notarization gate).

Risks

• SwiftPM-built GUI apps need hand-rolled bundle assembly (no Xcode "Archive"); Info.plist/entitlements mistakes surface only at notarize/staple or first launch — mitigated by a bundle-structure smoke test + the staple xcrun stapler validate gate.
• True inference progress isn't plumbed through CommandCore; v1 ships stage+elapsed progress (documented), not fake percentages.
• Notarize round-trips (2–10 min) make the release script slow to iterate; keep build/assemble testable without signing (signing stages behind flags, like release-mcp.sh).
• GUI cancellation can cancel the awaiting task but may not abort engine inference mid-flight (WhisperKit limitation) — must be documented honestly in the UI/design.

Residue

The issue's horizon — "a 4th surface that reaches humans" (product/distribution ambition, App Store vs direct-download strategy, icon/branding, localization) — is not operationalized in this change; v1 is a functional signed bundle. Marked, not silently dropped.

[kiki830621]

✅ Verify — #87 GUI dual-track bundle (opus adversarial pass, 3 lenses)

Verdict: SHIP WITH FIX (applied) — three independent opus reviewers (concurrency/state-machine, Spectra artifact↔implementation symmetry, shell/release-pipeline adversarial). No CRITICAL. The one HIGH and one MEDIUM are fixed in e2b0eb5; the state machine and artifact symmetry passed clean.

Findings

#	Severity	Lens	Finding	Status
1	HIGH	script	"${BUILD_ENV[@]}" on an empty array aborts under set -u on /bin/bash 3.2 (the shebang + stock-macOS shell) — killing the release build exactly on the recommended Xcode-toolchain path (empirically reproduced). Same latent defect found in release-mcp.sh and install.sh (sister-occurrence sweep).	✅ fixed — ${BUILD_ENV[@]+…} guard in all three scripts, re-verified under /bin/bash 3.2
2	MEDIUM	script	The Info.plist version sed parse wasn't scoped to enum BestASRVersion — a second numeric static let current anywhere earlier in DataModels.swift would silently bake the wrong version into a release.	✅ fixed — awk-scoped to the enum block + semver-shape assert (mirrors release-mcp.sh)
3	NIT	spec	design D4 implied a GUI diarize: argument; v1 has no diarize control (defaults false).	✅ fixed — D4 wording
4	LOW	spec	install.sh's bare swift build -c release now also compiles the GUI target (ride-along; installed binaries unchanged).	✅ annotated in install.sh
5	LOW	concurrency	awaitTerminal test helper is a bounded 2000-yield poll — structurally gate-driven (not the #86 sleep-race class); flake risk judged very low.	~ accepted, documented
6	LOW	script	BundleAssemblyTests has no waitUntilExit timeout; assemble-only is deterministic/fast, low real risk.	~ accepted, documented
7	INFO	script	Identical stub binaries mean the test can't detect a GUI↔CLI source swap; the security-relevant case-insensitive-collision invariant IS covered (naive layout collapses to 2 entries → fail).	~ accepted
8	INFO	spec	0.11.0 version consistency comes from ancestor commit (#86 branch history) — merge the branch whole (as the PR does), don't cherry-pick #87 alone onto an older main.	noted for merge

What the adversarial pass confirmed clean

• State machine: the generation guard is airtight on MainActor (stale-completion overwrite refuted across cancel→start→old-completion interleavings); no Sendable violations under Swift 5 mode; main thread never blocked (runner off-main, preview read detached).
• Artifact symmetry: all four Spectra artifacts + README + script + tests agree, including the mid-implementation bestasr-cli rename — the issue's original Contents/MacOS/{bestASR,bestasr-mcp,bestasr} layout is impossible on default (case-insensitive) APFS: bestasr IS bestASR, so the CLI copy silently overwrites the GUI. Caught by the bundle smoke test on its first run; spec/design/proposal/tasks were updated before the code, and the deviation is documented at every reader-facing site.
• Signing pipeline: nested-first signing order correct (--deep only for verify, per Apple guidance); the Plugin bundles the bestasr-mcp MCP server (notarized auto-download) #85 EOF-race-safe smoke pattern reused; stale-dist contamination impossible (rm -rf + gitignored dist/); CI-safe (no credentials/network needed by tests).

Real-artifact verification

• 335 tests / 72 suites green (includes 6 new session-state-machine tests + the bundle smoke test).
• Real universal (arm64+x86_64) --assemble-only run under /bin/bash 3.2: three executables, correct Info.plist, lipo -archs confirms universal.
• GUI launch smoke: the assembled bestASR binary launches and stays alive (no startup crash).
• Full sign→notarize→staple stages are maintainer-only (need Developer ID + notary round-trip) — an honest, documented gap; everything below the signing line is test-covered.

Stopping at verified — PR follows; merge + manual close are yours.

Refs #87

[kiki830621]

Closing Summary

Problem

bestASR had no human-facing surface: the CLI needs a terminal, and the MCP paths serve agents. A person who wants "drop a file → get an SRT" had nothing, and the parked .mcpb route was rejected for exactly that UX (blocking chat during long transcriptions). The roadmap called for a signed macOS GUI .app that also carries the MCP helper and CLI — one stapled artifact serving humans and agents (#87).

Root Cause

Feature gap (new product surface), not a defect. Groundwork was already in place: CommandCore as an injectable engine seam, the #85 sign/notarize pipeline, and #86's async jobs covering the agent-side long-wait.

Solution

Spectra change gui-app-dual-track (4 artifacts in-repo):

• bestasr-gui SwiftUI app, split as BestASRGUICore (testable @MainActor @Observable session state machine — idle/running/done/failed with a generation guard, single-flight start, honest cancel semantics — over an injected CommandCore runner) + a thin executable (per-section View structs, pickers persisted via @AppStorage, stage+elapsed progress, result preview + reveal-in-Finder, verbatim typed-error failure state). Written under apple-xcode-skills:swiftui-specialist.
• scripts/release-app.sh: universal build → bestASR.app assembly → Developer ID sign (nested-first, hardened runtime) → notarize → staple + validate → zip; --assemble-only unsigned mode keeps the structure testable without credentials.
• Two field findings shaped the design: (1) the issue's original bundle layout is impossible on default APFS — case-insensitive, so a bestasr entry IS bestASR and the CLI copy silently overwrites the GUI; caught by the bundle smoke test's first run, the CLI ships as bestasr-cli (spec/design updated before code). (2) swift build takes one --product per invocation — a triple-flag call silently builds only the last product.
• Verify HIGH fixed repo-wide: /bin/bash 3.2 aborts on empty-array expansion under set -u, which would have killed the release build exactly on the recommended Xcode-toolchain path — guarded in release-app.sh and the same latent defect in release-mcp.sh + install.sh. MEDIUM: the Info.plist version parse is enum-scoped + semver-asserted.

Verification

• 3-lens opus adversarial verify (concurrency/state-machine: SHIP; artifact symmetry: SHIP; shell/pipeline: SHIP WITH FIX — applied): feat: macOS GUI .app dual-track bundle — GUI + bestasr-mcp + CLI, signed/notarized/stapled #87 (comment)
• 335 tests / 72 suites green (6 new gate-driven session tests + bundle smoke test); real universal (arm64+x86_64) assemble verified under /bin/bash 3.2; GUI launch smoke OK. PR macOS GUI dual-track bundle — SwiftUI app + sign/notarize/staple pipeline #93 CI green.
• Honest gap: the sign→notarize→staple stages are maintainer-only (need Developer ID + notary round-trip) — everything below the signing line is test-covered.

Changes

• 254190e docs(spectra): gui-app-dual-track proposal/design/spec/tasks
• 5e436da feat: macOS GUI dual-track bundle — SwiftUI app + sign/notarize/staple pipeline
• e2b0eb5 fix: bash-3.2 empty-array guard in all release/install scripts + scoped version parse (verify)
• PR macOS GUI dual-track bundle — SwiftUI app + sign/notarize/staple pipeline #93 (squash-merged)

Distribution Sync

Pending, maintainer-run: scripts/release-app.sh (sign + notarize + staple + zip, ~2–10 min notary round-trip) then attach the artifact to a release tag. Also still pending from the #86 close: a v0.12.0 release-mcp.sh run + /plugin-update bestasr so the async MCP tools reach plugin users. Neither is auto-run at close time.

Residue

The issue's product horizon stays open by design: App Store vs direct-download strategy, custom icon/branding, localization, batch queue, true percent progress. v1 delivers the functional signed bundle; these are future issues if wanted.