@hasna/recordings 0.2.13 → 0.3.1

package/src/native/Recordings/Package.swift

@@ -20,10 +20,24 @@ let package = Package(
     ],
     dependencies: [
         .package(url: "https://github.com/sindresorhus/KeyboardShortcuts", exact: "1.12.0"),
-        // Swift Testing pinned to the toolchain-matched release. The stations build with
-        // CommandLineTools (no bundled Testing module), so the package is required — but it
-        // must track the compiler: the archived 0.99 shim under the 6.2 compiler silently
-        // corrupted `#expect` Bool-comparison evaluation, passing false assertions.
+        // Swift Testing. The stations build with CommandLineTools (no bundled Testing
+        // module), so the package is required. The original rule here was "the pin must
+        // track the compiler", because an archived 0.99 shim under the 6.2 compiler once
+        // silently corrupted `#expect` Bool-comparison evaluation, passing false assertions.
+        //
+        // Measured on station06 (Apple Swift 6.3.2, swiftlang-6.3.2.1.108): the 6.3.x line
+        // CANNOT be used here. From swift-6.3-RELEASE onward swift-testing's own manifest adds
+        // `.linkedLibrary("_TestingInterop")` under `#if compiler(>=6.3)`. That library ships
+        // in the toolchain at `$(xcode-select -p)/Library/Developer/usr/lib`, which is not on
+        // SwiftPM's default search path, so `swift build --build-tests` fails with
+        // `ld: library '_TestingInterop' not found`. It links only if every invocation adds
+        // `-Xlinker -L$(xcode-select -p)/Library/Developer/usr/lib`, which nothing in this repo
+        // supplies. Repinning to 6.3.2 would therefore break `swift test` for every caller.
+        //
+        // So the pin stays on the 6.2 line, and the rule it was standing in for is now
+        // enforced directly instead of by version matching: ExpectationIntegrityTests asserts
+        // that `#expect` both admits true Bool comparisons and *records issues* for false ones.
+        // That turns the silent failure mode into a red test, which a version pin never could.
         .package(url: "https://github.com/apple/swift-testing.git", revision: "swift-6.2-RELEASE"),
     ],
     targets: [
@@ -46,7 +60,12 @@ let package = Package(
         .executableTarget(
             name: "RecordingsUpdateBroker",
             dependencies: ["RecordingsUpdateProtocol", "RecordingsVerifierLauncher"],
-            path: "Updater/Broker"
+            path: "Updater/Broker",
+            // PeerIdentity resolves the XPC peer's audit token into a PID and EUID with
+            // audit_token_to_pid/_euid, which live in libbsm. Without this the broker
+            // compiles and then fails at link, which `swift build --target` does not
+            // surface because it stops short of linking the executable product.
+            linkerSettings: [.linkedLibrary("bsm")]
         ),
         .target(
             name: "RecordingsVerifierLauncher",

package/src/native/Recordings/RecordingsLib/EnhancementScreen.swift

@@ -0,0 +1,91 @@
+import Foundation
+
+/// Deterministic local pre-screen for the CLI's enhancement decision.
+///
+/// The helper CLI owns the real decision (`needsEnhancement` in `src/lib/enhancer.ts`):
+/// in `auto` post-processing mode it rewrites transcripts that carry an explicit
+/// configured trigger phrase or an instruction-shaped opening. Delivery may only run
+/// ahead of persistence when that rewrite provably cannot happen — the user asked for
+/// the rewritten text, so an eligible transcript must keep pasting the helper's output.
+///
+/// This screen therefore mirrors the CLI's detection *conservatively*: it answers
+/// "may the helper enhance this?" and fails closed (true) whenever it cannot decide.
+/// The trigger list is config-owned and arrives as the same frozen JSON array the
+/// engine already forwards to the helper via `--enhance-triggers-json`, so both sides
+/// read one source of truth for the configurable half. The instruction patterns mirror
+/// the CLI's built-in regexes; `EnhancementScreenTests` and the `enhancer.test.ts`
+/// "cross-language fixture" suite pin both implementations to one shared fixture table
+/// so they cannot drift apart silently.
+public enum EnhancementScreen {
+    /// Built-in instruction shapes, mirrored from `instructionPatterns` in
+    /// `src/lib/enhancer.ts`. Order and wording must match the CLI; the shared fixture
+    /// tests fail when either side changes alone.
+    static let instructionPatternSources: [String] = [
+        #"(?:write|draft|compose|create)\s+(?:an?\s+)?(?:email|message|response|reply|letter|note|text|slack|dm)"#,
+        #"(?:give|provide|send)\s+(?:them|him|her|it|the\s+agent|the\s+team)\s+(?:full\s+)?instructions"#,
+        #"(?:tell|ask)\s+(?:them|him|her|it|the\s+agent)\s+(?:to|that)"#,
+        #"(?:make\s+it|make\s+this)\s+(?:sound|look|read)\s+(?:more\s+)?(?:professional|formal|casual|friendly|better)"#,
+        #"(?:ok\s+so|okay\s+so|alright\s+so)\s+(?:say|write|tell|put)"#,
+        #"(?:i\s+need|i\s+want)\s+(?:the\s+agent|it|them|you)\s+to\s+(?:build|create|implement|design|make)"#,
+    ]
+
+    private static let instructionPatterns: [NSRegularExpression]? = {
+        var patterns: [NSRegularExpression] = []
+        for source in instructionPatternSources {
+            guard let pattern = try? NSRegularExpression(
+                pattern: source,
+                options: [.caseInsensitive]
+            ) else { return nil }
+            patterns.append(pattern)
+        }
+        return patterns
+    }()
+
+    /// True when the helper CLI could rewrite `text` in `auto` mode — or when this
+    /// screen cannot prove it will not (malformed trigger JSON, an unbuildable
+    /// pattern): enhancement-eligible speech must never be pasted raw ahead of the
+    /// helper, so every unprovable case persists first.
+    public static func mayRequireEnhancement(text: String, enhanceTriggersJSON: String) -> Bool {
+        guard let triggers = decodeTriggers(enhanceTriggersJSON) else { return true }
+        let lowered = text.lowercased()
+        for trigger in triggers {
+            let loweredTrigger = trigger.lowercased()
+            // An EMPTY configured trigger matches EVERYTHING in the CLI:
+            // `needsEnhancement` tests `lower.includes(trigger.toLowerCase())` and
+            // JavaScript's `includes("")` is true for every string, so one empty row
+            // makes the helper rewrite every transcript (MEASURED on the CLI:
+            // needs=true, reason `Explicit trigger: ""`). This screen must answer
+            // may-enhance for the same input or it admits that speech to
+            // paste-before-persistence and pastes raw text where the user asked for
+            // the rewrite.
+            //
+            // Special-cased rather than left to `contains`, because Swift's answer for
+            // an empty needle depends on which overload resolves — Foundation's
+            // `range(of:)`-based one answers false, the stdlib `Collection` one answers
+            // true — and NO machine has ever executed this file, so neither answer may
+            // be assumed. That overload claim is an UNVERIFIED INFERENCE from the
+            // language, not a measurement; `return true` is the fail-closed answer
+            // under either.
+            guard !loweredTrigger.isEmpty else { return true }
+            if lowered.contains(loweredTrigger) { return true }
+        }
+
+        guard let instructionPatterns else { return true }
+        let range = NSRange(text.startIndex..., in: text)
+        return instructionPatterns.contains { pattern in
+            pattern.firstMatch(in: text, range: range) != nil
+        }
+    }
+
+    /// Decodes the frozen trigger array the engine forwards to the helper. An empty
+    /// string means "no configured triggers" (the built-in patterns still apply);
+    /// anything else must parse as a JSON string array or the screen fails closed.
+    private static func decodeTriggers(_ json: String) -> [String]? {
+        let trimmed = json.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return [] }
+        guard let data = trimmed.data(using: .utf8),
+              let decoded = try? JSONDecoder().decode([String].self, from: data)
+        else { return nil }
+        return decoded
+    }
+}

package/src/native/Recordings/RecordingsLib/FnKeyMonitor.swift

@@ -12,15 +12,31 @@ final class FnKeyMonitor: @unchecked Sendable {
     private var healthCheckTimer: Timer?
     private var fnIsDown = false
 
-    var isRunning: Bool { eventTap != nil }
+    /// Whether the tap exists *and* is still enabled.
+    ///
+    /// `eventTap != nil` was not enough: macOS disables a tap when Accessibility is revoked
+    /// at runtime, and only `stop()` ever cleared the handle — so a dead tap reported itself
+    /// as running, the engine saw no blocker, and the `!isRunning` retry guard prevented
+    /// recovery. Ask the tap, not the handle.
+    var isRunning: Bool {
+        guard let eventTap else { return false }
+        return CGEvent.tapIsEnabled(tap: eventTap)
+    }
 
     private static let fnKeyCode: UInt16 = 63
 
     /// Start monitoring. Returns true if successful.
     func start() -> Bool {
-        guard eventTap == nil else {
-            fputs("[FnKeyMonitor] Already running\n", stderr)
-            return true
+        if eventTap != nil {
+            guard !isRunning else {
+                fputs("[FnKeyMonitor] Already running\n", stderr)
+                return true
+            }
+            // A handle we still hold but that the system has disabled cannot be revived by
+            // re-enabling it here — the grant that backed it is gone. Tear it down so the
+            // code below can build a fresh one once trust returns.
+            fputs("[FnKeyMonitor] Existing tap is disabled — discarding it before retry\n", stderr)
+            stop()
         }
 
         let eventMask: CGEventMask = 1 << CGEventType.flagsChanged.rawValue
@@ -63,6 +79,13 @@ final class FnKeyMonitor: @unchecked Sendable {
                 if !CGEvent.tapIsEnabled(tap: tap) {
                     fputs("[FnKeyMonitor] Tap was disabled, re-enabling\n", stderr)
                     CGEvent.tapEnable(tap: tap, enable: true)
+                    // If it will not come back, the permission behind it is gone. Drop the
+                    // tap so `isRunning` turns false and the engine can report a blocker and
+                    // rebuild, instead of polling a corpse every three seconds forever.
+                    if !CGEvent.tapIsEnabled(tap: tap) {
+                        fputs("[FnKeyMonitor] Re-enable failed — tearing down\n", stderr)
+                        self.stop()
+                    }
                 }
             }
 

package/src/native/Recordings/RecordingsLib/Info.plist

@@ -17,11 +17,11 @@
     <key>CFBundleIdentifier</key>
     <string>com.hasna.recordings</string>
     <key>CFBundleVersion</key>
-    <string>0.2.13</string>
+    <string>0.3.1</string>
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleShortVersionString</key>
-    <string>0.2.13</string>
+    <string>0.3.1</string>
     <key>LSMinimumSystemVersion</key>
     <string>26.0</string>
     <key>NSMicrophoneUsageDescription</key>

package/src/native/Recordings/RecordingsLib/MenuBarPresentation.swift

@@ -7,6 +7,12 @@ import Foundation
 /// present a busy state and a disabled Start affordance, never an idle state it would
 /// then refuse.
 public struct MenuBarPresentation: Equatable, Sendable {
+    /// Symbol for idle-but-blocked. `exclamationmark.triangle.fill` on purpose: it has shipped
+    /// since macOS 11, so it cannot resolve to nothing. An invalid `Image(systemName:)` renders
+    /// an EMPTY image, which would make the blocked state *less* visible than the bug it fixes.
+    public static let blockedIconName = "exclamationmark.triangle.fill"
+    public static let idleIconName = "mic.fill"
+
     public let iconName: String
     public let accessibilityLabel: String
     public let statusText: String
@@ -14,24 +20,71 @@ public struct MenuBarPresentation: Equatable, Sendable {
     /// (always enabled) Stop affordance; otherwise it is Start and must match
     /// `RecordingEngine.canStartRecording` exactly.
     public let primaryActionEnabled: Bool
+    /// Whether this is the idle-but-blocked state. Published so a view can tint or badge without
+    /// string-matching `statusText` to guess.
+    public let isBlocked: Bool
 
-    public init(isRecording: Bool, canStartRecording: Bool, statusMessage: String) {
-        if isRecording {
+    /// - Parameter blockedReason: `RecordingEngine.blockedReason` — why the app cannot record or
+    ///   deliver, when the reason outlives one status write.
+    ///
+    /// `blockedReason` is a parameter rather than something inferred from `statusMessage` because
+    /// the always-visible menu-bar item renders **only** `iconName` and `accessibilityLabel`
+    /// (`MenuBarStatusView.swift`: `Image(systemName:).accessibilityLabel(...)`). Until this
+    /// existed, the idle branch set `mic.fill` / "Recordings" and discarded `statusMessage`
+    /// entirely — so a blocked app was **byte-identical to Ready** in that surface, for sighted
+    /// and VoiceOver users alike, and the only channel carrying "press Cmd-V" was a popover the
+    /// user had to click open. A reason with no view consumer is not a disclosure.
+    /// - Parameter isWarmingUpCapture: `RecordingEngine.isWarmingUpCapture` — the microphone is
+    ///   open but has not delivered a sample yet. No default: `false` is the *invisible* value,
+    ///   and a surface that forgot it would compile and drop the glyph to the busy ellipsis for
+    ///   ~100 ms in the middle of a hold.
+    ///
+    /// `blockedReason` has no default either, for exactly the same reason and after exactly the
+    /// same regression: `nil` is its invisible value, and while it was defaulted
+    /// `App/RuntimeSmoke.swift` omitted it and compiled — a surface silently rendering every
+    /// blocked state as plain idle. An argument whose absent value *is* the failure mode does
+    /// not get to be optional.
+    public init(
+        isRecording: Bool,
+        isWarmingUpCapture: Bool,
+        canStartRecording: Bool,
+        statusMessage: String,
+        blockedReason: String?
+    ) {
+        // Warm-up presents as recording. The user is holding the key and Stop is live; anything
+        // else would read as a dead app for the ~100 ms between `recorder.start()` returning and
+        // the first PCM chunk.
+        if isRecording || isWarmingUpCapture {
             iconName = "waveform"
             accessibilityLabel = "Recordings, recording"
             statusText = "Recording"
             primaryActionEnabled = true
+            isBlocked = false
         } else if !canStartRecording {
             let normalizedBusyStatus = statusMessage.trimmingCharacters(in: .punctuationCharacters)
             iconName = "ellipsis.circle"
             accessibilityLabel = "Recordings, \(normalizedBusyStatus.lowercased())"
             statusText = normalizedBusyStatus
             primaryActionEnabled = false
+            isBlocked = false
+        } else if let blockedReason, !blockedReason.isEmpty {
+            // Idle and startable, but something the owner has to act on is wrong. Distinct icon
+            // AND distinct label: the icon is the only signal a sighted user gets from the menu
+            // bar, and the label is the only signal VoiceOver gets. Fixing one and not the other
+            // leaves half the users exactly where they were.
+            iconName = Self.blockedIconName
+            accessibilityLabel = "Recordings, blocked: \(blockedReason)"
+            statusText = blockedReason
+            // Still true, and still this type's other contract: a blocked trigger or a blocked
+            // paste does not make Start unavailable, and `canStartRecording` is what governs.
+            primaryActionEnabled = true
+            isBlocked = true
         } else {
-            iconName = "mic.fill"
+            iconName = Self.idleIconName
             accessibilityLabel = "Recordings"
             statusText = statusMessage
             primaryActionEnabled = true
+            isBlocked = false
         }
     }
 }

package/src/native/Recordings/RecordingsLib/NativePCMRecorder.swift

@@ -127,6 +127,19 @@ final class NativePCMRecorder: @unchecked Sendable {
         }
 
         do {
+            // These two calls are the ~520 ms a cold start costs, and they are why a short tap
+            // cannot capture anything: `RecordingEngine` only reports a live capture once the
+            // tap above delivers its first buffer, ~100 ms after `start()` returns.
+            //
+            // Pre-warming (holding a started engine between recordings, or hoisting
+            // `prepare()` to app launch) is the only way to make a sub-500 ms press record.
+            // It is deliberately NOT done here: a running engine with an installed input tap
+            // holds the input device open, which lights the macOS microphone-in-use indicator
+            // and lists the app under Control Center's microphone recents for as long as it
+            // runs. A permanently lit indicator is a worse regression than the bug. Whether
+            // `prepare()` alone — resource allocation without starting the IO thread — both
+            // absorbs a useful share of the 520 ms and leaves the indicator dark has to be
+            // measured on real hardware before anyone acts on it.
             engine.prepare()
             try engine.start()
             finishStart()