@hasna/recordings 0.2.13 → 0.3.1

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

@@ -59,17 +59,61 @@ public struct SettingsView: View {
                 HStack {
                     Text("Shortcut")
                     Spacer()
+                    // Re-evaluate on change, not just log: a chord the system already
+                    // reserves has to be reported the moment it is picked, not at next launch.
                     KeyboardShortcuts.Recorder(for: .toggleRecording) { _ in
-                        engine.updateStatus()
+                        engine.refreshTriggerDiagnostics()
                     }
                     Button("Reset to F5") {
                         KeyboardShortcuts.setShortcut(.init(.f5), for: .toggleRecording)
-                        engine.updateStatus()
+                        engine.refreshTriggerDiagnostics()
                     }
                 }
+                // No .onChange here: `RecordingEngine.useFnKey`'s own didSet re-arms the
+                // monitor and logs the resolved trigger, so it also covers a change made
+                // from the CLI or anywhere else — a view-local hook would not.
                 Toggle("Use fn/Globe as recording key", isOn: $engine.useFnKey)
-                Text("Hold to record, release to transcribe and paste.")
+                Text("Hold to record, release to transcribe and paste. fn needs Accessibility; the hotkey above needs no permission.")
                     .foregroundStyle(.secondary)
+                // A trigger that is switched on but cannot arm must say so next to its own
+                // switch. Silence here is what made 51 recorded hotkey presses look like a
+                // working trigger while nothing was delivered.
+                //
+                // Scoped to the trigger sources, and the button keyed to each reason's own
+                // remedy. Rendering the composed `engine.blockedReason` here instead meant a
+                // secure-input paste failure showed "transcript copied, press Cmd-V" under
+                // Recording Shortcut beside an "Open Accessibility Settings" button — wrong
+                // remedy, wrong section, wrong cause. A hotkey collision took that button too,
+                // and the Accessibility pane does nothing for a chord clash either.
+                ForEach(engine.blockedReasonEntries.filter(\.isTriggerHealth)) { entry in
+                    Label(entry.message, systemImage: "exclamationmark.triangle.fill")
+                        .foregroundStyle(.orange)
+                    // `switch`, not `==`. This file's engine forbids `==` against an enum case in
+                    // three separate comments for the same reason: it answers `false` for every
+                    // case added later, so a fourth remedy carrying a button would silently render
+                    // none. Exhaustive here means adding one forces the decision.
+                    switch entry.remedy {
+                    case .openAccessibilitySettings:
+                        Button("Open Accessibility Settings") {
+                            engine.openAccessibilitySettings()
+                        }
+                    case .chooseAnotherShortcut, .messageOnly:
+                        EmptyView()
+                    }
+                }
+            }
+
+            // Delivery reasons are not trigger health, but they are the ONLY message telling the
+            // owner their transcript is still recoverable — so they need a surface here, not just
+            // a wordless warning triangle in the menu bar and a caption behind a click. Scoping
+            // the trigger section was right; dropping these entirely was not.
+            if !engine.blockedReasonEntries.filter({ !$0.isTriggerHealth }).isEmpty {
+                Section("Last Delivery") {
+                    ForEach(engine.blockedReasonEntries.filter { !$0.isTriggerHealth }) { entry in
+                        Label(entry.message, systemImage: "exclamationmark.triangle.fill")
+                            .foregroundStyle(.orange)
+                    }
+                }
             }
 
             Section("Permissions") {

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

@@ -20,12 +20,17 @@ public struct VoiceShortcut: Identifiable, Codable {
 public final class VoiceShortcuts: ObservableObject {
     @Published public var shortcuts: [VoiceShortcut] = []
 
-    private let storageURL: URL = {
-        let home = FileManager.default.homeDirectoryForCurrentUser
-        return home.appendingPathComponent(".hasna/recordings/voice-shortcuts.json")
-    }()
-
-    public init() {
+    private let storageURL: URL
+
+    /// Injected for the same reason as `RecordingEngine.home`, and named to match the
+    /// `homePath:` seam the rest of the package already uses: the default resolves through the
+    /// password database (`getpwuid`), not `$HOME`, so a test cannot redirect this write by
+    /// overriding the environment and has to pass a temp directory explicitly. Without it a
+    /// test that touches voice shortcuts rewrites the operator's real
+    /// `~/.hasna/recordings/voice-shortcuts.json`.
+    public init(homePath: String = FileManager.default.homeDirectoryForCurrentUser.path) {
+        storageURL = URL(fileURLWithPath: homePath)
+            .appendingPathComponent(".hasna/recordings/voice-shortcuts.json")
         load()
     }
 

package/src/native/Recordings/RecordingsTests/CLIRunnerTests.swift

@@ -360,7 +360,7 @@ struct CLIRunnerTests {
         // commandCLI closure on a detached task, budgeted by commandRewriteTimeout — the
         // observable wall time must stay inside the budget even though the helper never
         // exits on its own and ignores SIGTERM.
-        let runCLI = RecordingEngine().commandCLI
+        let runCLI = RecordingEngine(homePath: home.path).commandCLI
         let homePath = home.path
         let startedAt = ContinuousClock.now
         let output = await Task.detached {
@@ -454,7 +454,7 @@ struct CLIRunnerTests {
         // also runs to exhaustion. The observable wall time must still land under the
         // public ceiling — the return margin absorbs spawn, poll overshoot, capture
         // shutdown, and the task hops.
-        let runCLI = RecordingEngine().commandCLI
+        let runCLI = RecordingEngine(homePath: home.path).commandCLI
         let homePath = home.path
         let startedAt = ContinuousClock.now
         let output = await Task.detached {
@@ -1113,7 +1113,7 @@ struct CLIRunnerTests {
         // SIGTERM and the silent holder keeps both pipes open, so every deadline in the
         // chain — execution window, termination grace, drain wait — runs to exhaustion
         // with zero bytes ever arriving to wake a reader.
-        let runCLI = RecordingEngine().commandCLI
+        let runCLI = RecordingEngine(homePath: home.path).commandCLI
         let homePath = home.path
         let startedAt = ContinuousClock.now
         let output = await Task.detached {

package/src/native/Recordings/RecordingsTests/EnhancementScreenTests.swift

@@ -0,0 +1,191 @@
+import Foundation
+import Testing
+@testable import RecordingsLib
+
+// MARK: - Cross-language enhancement fixtures
+
+/// Fixture table shared verbatim with `src/__tests__/enhancer.test.ts`
+/// ("cross-language fixtures pinned to EnhancementScreenTests.swift"). The CLI's
+/// `needsEnhancement` and the app's `EnhancementScreen` must agree on every row;
+/// change either implementation and both suites must be updated together.
+enum EnhancementFixtures {
+    /// The default trigger list from `src/lib/config.ts`, frozen the same way the
+    /// engine forwards it to the helper (`--enhance-triggers-json`).
+    static let defaultTriggersJSON = """
+    ["say it better","rewrite this","make it sound","clean this up","fix this",\
+    "rephrase","write it properly","make it professional","improve this","polish this"]
+    """
+
+    /// Rows the CLI enhances in `auto` mode: one per built-in instruction pattern,
+    /// plus an explicit configured trigger.
+    static let mayEnhance: [String] = [
+        "this is my draft say it better",
+        "write an email to the team about the outage",
+        "give them full instructions for the deploy",
+        "tell them to restart the ingest service",
+        "make this sound more professional",
+        "okay so write that we are postponing the launch",
+        "i need the agent to build a dashboard for the metrics",
+    ]
+
+    /// Rows the CLI passes through untouched, including near-misses of the
+    /// instruction patterns ("draft beer", "asked them").
+    static let plainDictation: [String] = [
+        "meet me at noon by the north entrance",
+        "the deploy finished and the metrics look stable",
+        "draft beer is better than bottled in my opinion",
+        "she asked them about the schedule yesterday",
+    ]
+}
+
+struct EnhancementScreenTests {
+    @Test("every enhancement-eligible fixture is screened as may-enhance")
+    func detectsEligibleRows() {
+        for text in EnhancementFixtures.mayEnhance {
+            #expect(
+                EnhancementScreen.mayRequireEnhancement(
+                    text: text,
+                    enhanceTriggersJSON: EnhancementFixtures.defaultTriggersJSON
+                ),
+                "expected may-enhance: \(text)"
+            )
+        }
+    }
+
+    @Test("plain dictation fixtures are provably not enhanceable")
+    func passesPlainDictation() {
+        for text in EnhancementFixtures.plainDictation {
+            #expect(
+                !EnhancementScreen.mayRequireEnhancement(
+                    text: text,
+                    enhanceTriggersJSON: EnhancementFixtures.defaultTriggersJSON
+                ),
+                "expected plain dictation: \(text)"
+            )
+        }
+    }
+
+    @Test("trigger matching is case-insensitive, like the CLI's")
+    func caseInsensitiveTriggers() {
+        #expect(EnhancementScreen.mayRequireEnhancement(
+            text: "REWRITE THIS whole paragraph",
+            enhanceTriggersJSON: EnhancementFixtures.defaultTriggersJSON
+        ))
+    }
+
+    @Test("an empty trigger payload still applies the built-in instruction patterns")
+    func emptyTriggersKeepPatterns() {
+        #expect(EnhancementScreen.mayRequireEnhancement(
+            text: "write an email to the team about the outage",
+            enhanceTriggersJSON: ""
+        ))
+        #expect(!EnhancementScreen.mayRequireEnhancement(
+            text: "meet me at noon by the north entrance",
+            enhanceTriggersJSON: ""
+        ))
+    }
+
+    @Test("an empty trigger STRING inside the payload fails closed to may-enhance")
+    func emptyTriggerRowFailsClosed() {
+        // The CLI's `lower.includes("")` is true for every transcript, so one empty row in the
+        // configured list means the helper rewrites everything. The mirror special-cases the row
+        // instead of testing it, because Swift's answer for an empty needle depends on which
+        // `contains` overload resolves and nothing executes this suite (see EnhancementScreen).
+        #expect(EnhancementScreen.mayRequireEnhancement(
+            text: "meet me at noon by the north entrance",
+            enhanceTriggersJSON: #"[""]"#
+        ))
+        #expect(EnhancementScreen.mayRequireEnhancement(
+            text: "meet me at noon by the north entrance",
+            enhanceTriggersJSON: #"["rewrite this",""]"#
+        ))
+    }
+
+    @Test("undecodable trigger payloads fail closed to may-enhance")
+    func malformedTriggersFailClosed() {
+        #expect(EnhancementScreen.mayRequireEnhancement(
+            text: "meet me at noon by the north entrance",
+            enhanceTriggersJSON: "not json"
+        ))
+        #expect(EnhancementScreen.mayRequireEnhancement(
+            text: "meet me at noon by the north entrance",
+            enhanceTriggersJSON: #"{"triggers":[]}"#
+        ))
+    }
+}
+
+// MARK: - Paste-before-persistence in auto mode
+
+struct AutoModePasteBeforePersistenceTests {
+    @Test("auto mode pastes plain dictation ahead of persistence")
+    func autoDictationPastesFirst() {
+        #expect(RecordingEngine.shouldPasteBeforePersistence(
+            postProcessingMode: PostProcessingMode.auto.rawValue,
+            transcript: "meet me at noon by the north entrance",
+            hasSelection: false,
+            intentDetectionEnabled: true,
+            enhanceTriggersJSON: EnhancementFixtures.defaultTriggersJSON
+        ))
+    }
+
+    @Test("auto mode persists first whenever the helper could rewrite the transcript")
+    func autoEnhanceableSpeechPersistsFirst() {
+        for text in EnhancementFixtures.mayEnhance {
+            #expect(
+                !RecordingEngine.shouldPasteBeforePersistence(
+                    postProcessingMode: PostProcessingMode.auto.rawValue,
+                    transcript: text,
+                    hasSelection: false,
+                    intentDetectionEnabled: true,
+                    enhanceTriggersJSON: EnhancementFixtures.defaultTriggersJSON
+                ),
+                "expected persist-first: \(text)"
+            )
+        }
+    }
+
+    @Test("auto mode still defers to the intent screens for non-dictation shapes")
+    func autoNonDictationPersistsFirst() {
+        // Question-shaped speech may become a conversation — persist first.
+        #expect(!RecordingEngine.shouldPasteBeforePersistence(
+            postProcessingMode: PostProcessingMode.auto.rawValue,
+            transcript: "what's the capital of France?",
+            hasSelection: false,
+            intentDetectionEnabled: true,
+            enhanceTriggersJSON: EnhancementFixtures.defaultTriggersJSON
+        ))
+    }
+
+    @Test("auto mode fails closed to persist-first on a malformed trigger payload")
+    func autoMalformedTriggersPersistFirst() {
+        #expect(!RecordingEngine.shouldPasteBeforePersistence(
+            postProcessingMode: PostProcessingMode.auto.rawValue,
+            transcript: "meet me at noon by the north entrance",
+            hasSelection: false,
+            intentDetectionEnabled: true,
+            enhanceTriggersJSON: "not json"
+        ))
+    }
+
+    @Test("always mode keeps persisting first even for plain dictation")
+    func alwaysModePersistsFirst() {
+        #expect(!RecordingEngine.shouldPasteBeforePersistence(
+            postProcessingMode: PostProcessingMode.always.rawValue,
+            transcript: "meet me at noon by the north entrance",
+            hasSelection: false,
+            intentDetectionEnabled: true,
+            enhanceTriggersJSON: EnhancementFixtures.defaultTriggersJSON
+        ))
+    }
+
+    @Test("off mode is unchanged by the trigger payload")
+    func offModeUnchanged() {
+        #expect(RecordingEngine.shouldPasteBeforePersistence(
+            postProcessingMode: PostProcessingMode.off.rawValue,
+            transcript: "this is my draft say it better",
+            hasSelection: false,
+            intentDetectionEnabled: true,
+            enhanceTriggersJSON: EnhancementFixtures.defaultTriggersJSON
+        ))
+    }
+}

package/src/native/Recordings/RecordingsTests/MenuBarPresentationTests.swift

@@ -9,8 +9,10 @@ struct MenuBarPresentationTests {
     func idle() {
         let presentation = MenuBarPresentation(
             isRecording: false,
+            isWarmingUpCapture: false,
             canStartRecording: true,
-            statusMessage: "Ready"
+            statusMessage: "Ready",
+            blockedReason: nil
         )
         #expect(presentation.iconName == "mic.fill")
         #expect(presentation.accessibilityLabel == "Recordings")
@@ -22,8 +24,10 @@ struct MenuBarPresentationTests {
     func recording() {
         let presentation = MenuBarPresentation(
             isRecording: true,
+            isWarmingUpCapture: false,
             canStartRecording: false,
-            statusMessage: "Recording — release to stop"
+            statusMessage: "Recording — release to stop",
+            blockedReason: nil
         )
         #expect(presentation.iconName == "waveform")
         #expect(presentation.accessibilityLabel == "Recordings, recording")
@@ -36,8 +40,10 @@ struct MenuBarPresentationTests {
         for status in ["Transcribing...", "Deciding...", "Answering...", "Rewriting...", "Pasting..."] {
             let presentation = MenuBarPresentation(
                 isRecording: false,
+                isWarmingUpCapture: false,
                 canStartRecording: false,
-                statusMessage: status
+                statusMessage: status,
+                blockedReason: nil
             )
             #expect(presentation.iconName == "ellipsis.circle", "expected busy icon for \(status)")
             #expect(!presentation.primaryActionEnabled, "Start must be disabled during \(status)")
@@ -47,6 +53,80 @@ struct MenuBarPresentationTests {
         }
     }
 
+    /// The defect this pins: the idle branch discarded `statusMessage` and set `mic.fill` /
+    /// "Recordings", and the always-visible menu-bar item renders ONLY the icon and the
+    /// accessibility label. So a blocked app was byte-identical to Ready for sighted and
+    /// VoiceOver users alike, and "press Cmd-V" lived only in a popover nobody had opened.
+    @Test("a blocked idle app is distinguishable from Ready by BOTH icon and label")
+    func blockedIsVisible() {
+        let reason = "This field blocks typing (secure input) — transcript copied, press Cmd-V"
+        let ready = MenuBarPresentation(
+            isRecording: false,
+            isWarmingUpCapture: false,
+            canStartRecording: true,
+            statusMessage: "Ready",
+            blockedReason: nil
+        )
+        let blocked = MenuBarPresentation(
+            isRecording: false,
+            isWarmingUpCapture: false,
+            canStartRecording: true,
+            statusMessage: "Ready",
+            blockedReason: reason
+        )
+
+        #expect(blocked.iconName != ready.iconName, "the icon is the only signal a sighted user gets")
+        #expect(
+            blocked.accessibilityLabel != ready.accessibilityLabel,
+            "the label is the only signal VoiceOver gets"
+        )
+        #expect(blocked.iconName == MenuBarPresentation.blockedIconName)
+        #expect(blocked.accessibilityLabel.contains(reason))
+        #expect(blocked.statusText == reason)
+        #expect(blocked.isBlocked)
+        #expect(!ready.isBlocked)
+        // A blocked trigger or a blocked paste does not make Start unavailable, and the
+        // presentation must keep matching `canStartRecording` exactly.
+        #expect(blocked.primaryActionEnabled)
+    }
+
+    @Test("an empty blocked reason is not a blocked state")
+    func emptyReasonIsNotBlocked() {
+        let presentation = MenuBarPresentation(
+            isRecording: false,
+            isWarmingUpCapture: false,
+            canStartRecording: true,
+            statusMessage: "Ready",
+            blockedReason: ""
+        )
+        #expect(presentation.iconName == MenuBarPresentation.idleIconName)
+        #expect(!presentation.isBlocked)
+    }
+
+    @Test("recording and busy states outrank a blocked reason")
+    func liveStatesWin() {
+        let recording = MenuBarPresentation(
+            isRecording: true,
+            isWarmingUpCapture: false,
+            canStartRecording: false,
+            statusMessage: "Recording",
+            blockedReason: "stale reason"
+        )
+        #expect(recording.iconName == "waveform")
+        #expect(!recording.isBlocked)
+
+        let busy = MenuBarPresentation(
+            isRecording: false,
+            isWarmingUpCapture: false,
+            canStartRecording: false,
+            statusMessage: "Transcribing...",
+            blockedReason: "stale reason"
+        )
+        #expect(busy.iconName == "ellipsis.circle")
+        #expect(!busy.primaryActionEnabled)
+        #expect(!busy.isBlocked)
+    }
+
     @Test("presentation follows canStartRecording exactly, not isTranscribing alone")
     func presentationTracksTheStartGate() {
         // A pending intent decision keeps canStartRecording false even though
@@ -54,12 +134,72 @@ struct MenuBarPresentationTests {
         // the click. The contract requires busy.
         let deciding = MenuBarPresentation(
             isRecording: false,
+            isWarmingUpCapture: false,
             canStartRecording: false,
-            statusMessage: "Deciding..."
+            statusMessage: "Deciding...",
+            blockedReason: nil
         )
         #expect(!deciding.primaryActionEnabled)
         #expect(deciding.statusText == "Deciding")
     }
+
+    @Test("the warm-up window presents as recording, never as busy or idle")
+    func warmUpPresentsAsRecording() {
+        // Between `recorder.start()` returning and the first PCM chunk the user is holding the
+        // key. `isRecording` is false there — no audio exists yet — so without this branch the
+        // glyph drops to the busy ellipsis for ~100 ms in the middle of a hold.
+        let presentation = MenuBarPresentation(
+            isRecording: false,
+            isWarmingUpCapture: true,
+            canStartRecording: false,
+            statusMessage: "Recording — release to stop",
+            blockedReason: nil
+        )
+        #expect(presentation.iconName == "waveform")
+        #expect(presentation.accessibilityLabel == "Recordings, recording")
+        #expect(presentation.statusText == "Recording")
+        #expect(presentation.primaryActionEnabled, "Stop must be live during warm-up")
+        #expect(!presentation.isBlocked)
+    }
+
+    @Test("an attempt that captured nothing is disclosed on the glyph, not just in a status line")
+    func emptyAttemptIsDisclosedOnTheGlyph() {
+        // Recordings is LSUIElement: a status line behind a popover click is not feedback. The
+        // engine routes these through `blockedReason`, so they must reach the always-visible
+        // icon and the VoiceOver label, and must not look like plain idle.
+        for alert in [RecordingAttemptAlert.releasedBeforeAudio, .noAudioCaptured] {
+            let presentation = MenuBarPresentation(
+                isRecording: false,
+                isWarmingUpCapture: false,
+                canStartRecording: true,
+                statusMessage: "Ready",
+                blockedReason: alert.message
+            )
+            #expect(presentation.iconName == MenuBarPresentation.blockedIconName, "expected the blocked glyph for \(alert)")
+            #expect(presentation.iconName != MenuBarPresentation.idleIconName)
+            #expect(presentation.statusText == alert.message)
+            #expect(presentation.accessibilityLabel == "Recordings, blocked: \(alert.message)")
+            #expect(presentation.isBlocked)
+            #expect(presentation.primaryActionEnabled, "the attempt is over — Start stays available")
+        }
+    }
+
+    @Test("a hold in progress outranks a still-visible empty-attempt disclosure")
+    func recordingOutranksADisclosure() {
+        // `blockedReason` is cleared by the next `startRecording`, but the warm-up branch must
+        // win regardless: showing "released too soon" over a live hold would be a lie.
+        for warmingUp in [true, false] {
+            let presentation = MenuBarPresentation(
+                isRecording: !warmingUp,
+                isWarmingUpCapture: warmingUp,
+                canStartRecording: false,
+                statusMessage: "Recording — release to stop",
+                blockedReason: RecordingAttemptAlert.releasedBeforeAudio.message
+            )
+            #expect(presentation.iconName == "waveform")
+            #expect(!presentation.isBlocked)
+        }
+    }
 }
 
 /// Reduce Transparency surface contract: chrome must resolve to an opaque surface — never