@hasna/recordings 0.3.13 → 0.5.0

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

@@ -0,0 +1,34 @@
+import SwiftUI
+import AppKit
+
+/// One live macOS material per surface. No opaque tint below the blur and no
+/// per-meter-tick Liquid Glass surfaces; content remains legible in accessibility mode.
+public struct RecordingGlassBackground: View {
+    @Environment(\.accessibilityReduceTransparency) private var reduceTransparency
+    public var radius: CGFloat
+    public init(radius: CGFloat = 16) { self.radius = radius }
+    public var body: some View {
+        ZStack {
+            if ChromeSurface.forReducedTransparency(reduceTransparency) == .opaque {
+                Color(NSColor.windowBackgroundColor)
+            } else {
+                NativeRecordingGlass()
+                LinearGradient(colors: [.white.opacity(0.18), .clear, .white.opacity(0.06)], startPoint: .topLeading, endPoint: .bottomTrailing)
+            }
+        }
+        .clipShape(RoundedRectangle(cornerRadius: radius))
+        .overlay(RoundedRectangle(cornerRadius: radius).strokeBorder(.white.opacity(0.45), lineWidth: 0.5))
+    }
+}
+
+private struct NativeRecordingGlass: NSViewRepresentable {
+    func makeNSView(context: Context) -> NSVisualEffectView {
+        let view = NSVisualEffectView()
+        view.material = .hudWindow
+        view.alphaValue = 0.9
+        view.blendingMode = .behindWindow
+        view.state = .active
+        return view
+    }
+    func updateNSView(_ view: NSVisualEffectView, context: Context) {}
+}

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

@@ -0,0 +1,114 @@
+import AppKit
+import Foundation
+
+/// An observed app process, not a bundle-ID request to launch or find another instance.
+public struct RecordingPasteTarget: Equatable, Sendable {
+    public let processIdentifier: pid_t
+    public let bundleIdentifier: String
+    public let launchDate: Date
+    public let applicationName: String
+
+    init?(observation: PasteApplicationObservation, currentPID: pid_t) {
+        guard observation.pid > 0, observation.pid != currentPID,
+              observation.isRegular, !observation.isTerminated,
+              let bundle = observation.bundleIdentifier, !bundle.isEmpty,
+              let launchDate = observation.launchDate else { return nil }
+        processIdentifier = observation.pid
+        bundleIdentifier = bundle
+        self.launchDate = launchDate
+        applicationName = observation.name ?? "Application"
+    }
+
+    func matches(_ observation: PasteApplicationObservation) -> Bool {
+        observation.pid == processIdentifier && observation.bundleIdentifier == bundleIdentifier
+            && observation.launchDate == launchDate && observation.isRegular && !observation.isTerminated
+    }
+}
+
+/// Omission preserves the recorder's existing frontmost-app behavior. A frozen nil
+/// explicitly means no destination; it never adopts another app at delivery time.
+public enum RecordingPasteTargetSelection: Equatable, Sendable {
+    case frontmostApplication
+    case frozen(RecordingPasteTarget?)
+}
+
+struct PasteApplicationObservation: Sendable {
+    var pid: pid_t
+    var bundleIdentifier: String?
+    var launchDate: Date?
+    var name: String?
+    var isRegular: Bool
+    var isTerminated: Bool
+
+    init(_ app: NSRunningApplication) {
+        pid = app.processIdentifier; bundleIdentifier = app.bundleIdentifier
+        launchDate = app.launchDate; name = app.localizedName
+        isRegular = app.activationPolicy == .regular; isTerminated = app.isTerminated
+    }
+    init(pid: pid_t, bundleIdentifier: String?, launchDate: Date?, name: String? = nil,
+         isRegular: Bool = true, isTerminated: Bool = false) {
+        self.pid = pid; self.bundleIdentifier = bundleIdentifier; self.launchDate = launchDate
+        self.name = name; self.isRegular = isRegular; self.isTerminated = isTerminated
+    }
+}
+
+/// Keep one tracker for the host application's lifetime, before presenting its UI.
+/// Observes workspace activation only; never installs input handlers, queries AX,
+/// activates apps, reads their documents, or accesses the clipboard.
+@MainActor public final class RecordingPasteTargetTracker {
+    private let currentPID: pid_t
+    private let frontmost: () -> PasteApplicationObservation?
+    private let lookup: (pid_t) -> PasteApplicationObservation?
+    private var lastExternal: RecordingPasteTarget?
+    private var observers: [NSObjectProtocol] = []
+    private var center: NotificationCenter?
+
+    public convenience init() {
+        self.init(currentPID: ProcessInfo.processInfo.processIdentifier,
+                  frontmost: { NSWorkspace.shared.frontmostApplication.map(PasteApplicationObservation.init) },
+                  lookup: { NSRunningApplication(processIdentifier: $0).map(PasteApplicationObservation.init) })
+        let center = NSWorkspace.shared.notificationCenter
+        self.center = center
+        observers.append(center.addObserver(forName: NSWorkspace.didActivateApplicationNotification, object: nil, queue: .main) { [weak self] notification in
+            guard let app = notification.userInfo?[NSWorkspace.applicationUserInfoKey] as? NSRunningApplication else { return }
+            let observation = PasteApplicationObservation(app)
+            MainActor.assumeIsolated { self?.observe(observation) }
+        })
+        observers.append(center.addObserver(forName: NSWorkspace.didTerminateApplicationNotification, object: nil, queue: .main) { [weak self] notification in
+            guard let app = notification.userInfo?[NSWorkspace.applicationUserInfoKey] as? NSRunningApplication else { return }
+            let observation = PasteApplicationObservation(app)
+            MainActor.assumeIsolated { self?.terminated(observation) }
+        })
+    }
+
+    init(currentPID: pid_t, frontmost: @escaping () -> PasteApplicationObservation?,
+         lookup: @escaping (pid_t) -> PasteApplicationObservation?) {
+        self.currentPID = currentPID; self.frontmost = frontmost; self.lookup = lookup
+        if let app = frontmost() { observe(app) }
+    }
+
+    isolated deinit { for observer in observers { center?.removeObserver(observer) } }
+
+    func observe(_ app: PasteApplicationObservation) {
+        guard let target = RecordingPasteTarget(observation: app, currentPID: currentPID) else { return }
+        lastExternal = target
+    }
+
+    func terminated(_ app: PasteApplicationObservation) {
+        guard let target = lastExternal, app.pid == target.processIdentifier,
+              app.bundleIdentifier == target.bundleIdentifier, app.launchDate == target.launchDate else { return }
+        lastExternal = nil
+    }
+
+    /// Revalidate now, then pass this value to startRecording as `.frozen(value)`.
+    /// A terminated or replaced process clears the remembered destination; older
+    /// apps are not searched as a substitute.
+    public func snapshot() -> RecordingPasteTarget? {
+        if let app = frontmost() { observe(app) }
+        guard let target = lastExternal else { return nil }
+        guard let live = lookup(target.processIdentifier), target.matches(live) else {
+            lastExternal = nil; return nil
+        }
+        return target
+    }
+}

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

@@ -0,0 +1,112 @@
+import Foundation
+
+/// A separate application must opt into its own filesystem and preferences roots.
+/// This configuration never installs shortcuts or uses the legacy provider, Keychain,
+/// environment variables, helper CLI, or service connection. Providers own their credentials.
+public struct RecordingEngineConfiguration: Sendable {
+    public let isolatedHomePath: String
+    public let preferencesSuiteName: String
+
+    public init(isolatedHomePath: String, preferencesSuiteName: String) throws {
+        let path = URL(fileURLWithPath: isolatedHomePath).standardizedFileURL.resolvingSymlinksInPath()
+        let liveHome = FileManager.default.homeDirectoryForCurrentUser.resolvingSymlinksInPath()
+        let state = path.appendingPathComponent(".hasna/recordings").resolvingSymlinksInPath()
+        let liveState = liveHome.appendingPathComponent(".hasna/recordings").resolvingSymlinksInPath()
+        guard isolatedHomePath.hasPrefix("/"), path != liveHome,
+              state != liveState,
+              !preferencesSuiteName.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty,
+              preferencesSuiteName != "com.hasna.recordings",
+              preferencesSuiteName != "NSGlobalDomain",
+              preferencesSuiteName != "NSArgumentDomain" else {
+            throw RecordingProviderError.invalidIsolation
+        }
+        self.isolatedHomePath = path.path
+        self.preferencesSuiteName = preferencesSuiteName
+    }
+}
+
+/// The native capture format is fixed so providers can forward PCM without conversion.
+public struct RecordingProviderSessionConfiguration: Sendable {
+    public let captureID: String
+    public let language: String
+    public let sampleRate: Int = 24_000
+    public let channels: Int = 1
+    public let bitsPerSample: Int = 16
+
+    public init(captureID: String, language: String) {
+        self.captureID = captureID
+        self.language = language
+    }
+}
+
+public struct RecordingTranscriptionRequest: Sendable {
+    public let captureID: String
+    /// A complete 24 kHz, mono, signed little-endian PCM16 WAV, excluding paused audio.
+    public let audioURL: URL
+    public let duration: TimeInterval
+    public let language: String
+
+    public init(captureID: String, audioURL: URL, duration: TimeInterval, language: String) {
+        self.captureID = captureID
+        self.audioURL = audioURL
+        self.duration = duration
+        self.language = language
+    }
+}
+
+public struct RecordingProviderResult: Sendable, Equatable {
+    public let rawText: String
+    public let processedText: String?
+
+    public init(rawText: String, processedText: String? = nil) {
+        self.rawText = rawText
+        self.processedText = processedText
+    }
+}
+
+public protocol RecordingTranscriptionProvider: Sendable {
+    /// Construct promptly; start network/recognition work asynchronously inside the session.
+    /// Freeze mutable provider settings here so they cannot switch beneath a capture.
+    /// Each partial callback replaces the complete current transcript, rather than appending.
+    func makeSession(
+        configuration: RecordingProviderSessionConfiguration,
+        onPartialTranscript: @escaping @Sendable (String) -> Void
+    ) throws -> any RecordingTranscriptionSession
+}
+
+public protocol RecordingTranscriptionSession: Sendable {
+    /// Called in capture order with variable-sized admitted PCM packets, off the audio
+    /// callback. Empty packets are omitted; all admitted packets precede inputEnded().
+    /// Return promptly. Providers must bound any queue while connecting or sending.
+    /// An in-flight append may race cancel; a cancelled session must ignore it.
+    func appendPCM(_ data: Data)
+    /// Called once after all capture/converter PCM drains, before the fallback WAV is written.
+    /// Streaming providers may close input now and cache an early final result. Return promptly;
+    /// this does not authorize publishing text or reading audioURL before finish is called.
+    /// Must be thread-safe and idempotent, and ignore calls after cancellation.
+    func inputEnded()
+    /// Called once after capture drains and the fallback WAV is safely written.
+    /// File-based providers may ignore appendPCM and recognize this file locally.
+    func finish(_ request: RecordingTranscriptionRequest) async throws -> RecordingProviderResult
+    /// Must be thread-safe and idempotent, including cancellation during finish.
+    func cancel()
+}
+
+public extension RecordingTranscriptionSession {
+    /// File providers and existing adapters keep their finish-after-WAV behavior.
+    func inputEnded() {}
+}
+
+public enum RecordingProviderError: Error, LocalizedError, Sendable {
+    case invalidIsolation
+    case noAudio
+    case emptyTranscript
+
+    public var errorDescription: String? {
+        switch self {
+        case .invalidIsolation: "Provide a separate absolute state home and preferences suite for this app."
+        case .noAudio: "No audio was captured."
+        case .emptyTranscript: "No speech was recognized."
+        }
+    }
+}

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

@@ -33,25 +33,32 @@ public enum RecordingsCLI {
               command.argumentsPrefix.isEmpty else {
             throw Failure(message: "Packaged companion resolver did not select the embedded helper")
         }
-        let versionOutput = CLIRunner.run(["--version"], home: home)
+        // The resolver smoke checks a throwaway local store, never the owner's API.
+        let probeEnvironment = [
+            "HOME": home,
+            "PATH": "/usr/bin:/bin:/usr/sbin:/sbin",
+            "HASNA_RECORDINGS_CLIENT_STORE": "sqlite",
+            "HASNA_RECORDINGS_DB_PATH": "\(home)/recordings.db",
+        ]
+        let versionOutput = CLIRunner.run(["--version"], home: home, environment: probeEnvironment)
             .trimmingCharacters(in: .whitespacesAndNewlines)
         if let error = CLIRunner.parseError(versionOutput) { throw Failure(message: error) }
         let expectedVersion = Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String
         guard !versionOutput.isEmpty, versionOutput == expectedVersion else {
             throw Failure(message: "Packaged companion version does not match the app")
         }
-        let project = try registerProject(
-            name: "Activated Helper Contract",
-            path: "recordings-app://install/activated-helper-contract",
-            description: "Installed app resolver verification",
-            home: home
-        )
+        let project = try decode(CanonicalProject.self, from: CLIRunner.run([
+            "--json", "project", "register", "--name", "Activated Helper Contract",
+            "--path", "recordings-app://install/activated-helper-contract",
+            "--description", "Installed app resolver verification",
+        ], home: home, environment: probeEnvironment))
         guard project.name == "Activated Helper Contract" else {
             throw Failure(message: "Packaged companion project capability failed")
         }
         let saved = CLIRunner.run(
             ["--json", "save-text", "Activated helper contract", "--source", "native_install_contract", "--post-processing", "off"],
-            home: home
+            home: home,
+            environment: probeEnvironment
         )
         struct SavedRecording: Decodable { let raw_text: String }
         let recording = try decode(SavedRecording.self, from: saved)
@@ -115,7 +122,7 @@ public enum RecordingsCLI {
 
     public static func delete(id: String, home: String = defaultHome) throws {
         let output = CLIRunner.run(["delete", id], home: home)
-        if let err = CLIRunner.parseError(output) { throw Failure(message: err) }
+        if let err = CLIRunner.parseError(output, serviceAPI: true) { throw Failure(message: err) }
     }
 
     public struct CanonicalProject: Codable, Sendable {
@@ -141,7 +148,7 @@ public enum RecordingsCLI {
 
     private static func runDecoding<T: Decodable>(_ type: T.Type, _ args: [String], home: String) throws -> T {
         let output = CLIRunner.run(args, home: home)
-        if let err = CLIRunner.parseError(output) { throw Failure(message: err) }
+        if let err = CLIRunner.parseError(output, serviceAPI: true) { throw Failure(message: err) }
         return try decode(type, from: output)
     }
 

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

@@ -0,0 +1,107 @@
+import Foundation
+import Security
+
+/// Bridges Finder/menu-bar launches to the same environment contract as the CLI.
+/// The endpoint is user configuration; credentials live in Keychain, scoped to that URL.
+public enum ServiceAPIConfiguration {
+    public static let defaultsKey = "recordingsServiceAPIURL"
+    public static let didChangeNotification = Notification.Name("recordingsServiceAPIConfigurationDidChange")
+    private static let keychainService = "com.hasna.recordings.service-api"
+
+    enum Failure: Error, LocalizedError {
+        case invalidURL
+        case keychain(OSStatus)
+
+        var errorDescription: String? {
+            switch self {
+            case .invalidURL:
+                "Enter an HTTPS API URL without credentials, query parameters, or a fragment. Localhost may use HTTP."
+            case .keychain(let status):
+                "Could not access the Recordings API credential in Keychain (\(status))."
+            }
+        }
+    }
+
+    public static func normalizedURL(_ value: String) throws -> String {
+        guard var url = URLComponents(string: value.trimmingCharacters(in: .whitespacesAndNewlines)),
+              let host = url.host, !host.isEmpty,
+              url.user == nil, url.password == nil, url.query == nil, url.fragment == nil,
+              url.scheme == "https" || (url.scheme == "http" && ["localhost", "127.0.0.1", "[::1]", "::1"].contains(host)) else {
+            throw Failure.invalidURL
+        }
+        var path = url.path
+        while path.hasSuffix("/") { path.removeLast() }
+        if !path.hasSuffix("/v1") { path += "/v1" }
+        url.path = path
+        guard let result = url.url?.absoluteString else { throw Failure.invalidURL }
+        return result
+    }
+
+    public static func configuredURL(
+        environment: [String: String] = ProcessInfo.processInfo.environment,
+        defaults: UserDefaults = .standard
+    ) -> String {
+        environment["HASNA_RECORDINGS_API_URL"] ?? defaults.string(forKey: defaultsKey) ?? ""
+    }
+
+    public static func save(url: String, apiKey: String, defaults: UserDefaults = .standard) throws {
+        let endpoint = try normalizedURL(url)
+        let key = apiKey.trimmingCharacters(in: .whitespacesAndNewlines)
+        if !key.isEmpty {
+            let query: [String: Any] = [
+                kSecClass as String: kSecClassGenericPassword,
+                kSecAttrService as String: keychainService,
+                kSecAttrAccount as String: endpoint,
+            ]
+            let value = [kSecValueData as String: Data(key.utf8)]
+            var status = SecItemUpdate(query as CFDictionary, value as CFDictionary)
+            if status == errSecItemNotFound {
+                var item = query.merging(value) { _, new in new }
+                item[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+                status = SecItemAdd(item as CFDictionary, nil)
+            }
+            guard status == errSecSuccess else { throw Failure.keychain(status) }
+        }
+        defaults.set(endpoint, forKey: defaultsKey)
+        NotificationCenter.default.post(name: didChangeNotification, object: nil)
+    }
+
+    static func loadKey(for endpoint: String) throws -> String? {
+        let query: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: keychainService,
+            kSecAttrAccount as String: endpoint,
+            kSecReturnData as String: true,
+            kSecMatchLimit as String: kSecMatchLimitOne,
+            kSecUseAuthenticationUI as String: kSecUseAuthenticationUIFail,
+        ]
+        var result: CFTypeRef?
+        let status = SecItemCopyMatching(query as CFDictionary, &result)
+        if status == errSecItemNotFound { return nil }
+        guard status == errSecSuccess else { throw Failure.keychain(status) }
+        return (result as? Data).flatMap { String(data: $0, encoding: .utf8) }
+    }
+
+    static func childEnvironment(
+        base: [String: String],
+        defaults: UserDefaults = .standard,
+        keyLoader: (String) throws -> String? = loadKey
+    ) throws -> [String: String] {
+        // Explicit environment routing wins. Never attach a saved credential to an
+        // unrelated environment endpoint, or silently turn a local override into HTTP.
+        if base["HASNA_RECORDINGS_LOCAL"] == "1" || base["RECORDINGS_LOCAL"] == "1" { return base }
+        if ["HASNA_RECORDINGS_API_URL"]
+            .contains(where: { !(base[$0] ?? "").trimmingCharacters(in: .whitespacesAndNewlines).isEmpty }) {
+            return base
+        }
+        guard let saved = defaults.string(forKey: defaultsKey), !saved.isEmpty else { return base }
+        let endpoint = try normalizedURL(saved)
+        var result = base
+        result["HASNA_RECORDINGS_API_URL"] = endpoint
+        if ["HASNA_RECORDINGS_API_KEY_OVERRIDE", "HASNA_RECORDINGS_API_KEY"]
+            .allSatisfy({ (base[$0] ?? "").isEmpty }), let key = try keyLoader(endpoint), !key.isEmpty {
+            result["HASNA_RECORDINGS_API_KEY_OVERRIDE"] = key
+        }
+        return result
+    }
+}

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

@@ -0,0 +1,76 @@
+import SwiftUI
+
+struct ServiceConnectionView: View {
+    let home: String
+    @State private var apiURL = ServiceAPIConfiguration.configuredURL()
+    @State private var apiKey = ""
+    @State private var status: String?
+    @State private var checking = false
+
+    private var environmentManaged: Bool {
+        ["HASNA_RECORDINGS_API_URL", "HASNA_RECORDINGS_CLIENT_STORE", "RECORDINGS_CLIENT_STORE"]
+            .contains { !(ProcessInfo.processInfo.environment[$0] ?? "").isEmpty }
+    }
+
+    var body: some View {
+        Section("Recordings API") {
+            TextField("API URL", text: $apiURL)
+                .textFieldStyle(.roundedBorder)
+                .disabled(environmentManaged)
+            SecureField("API key", text: $apiKey)
+                .textFieldStyle(.roundedBorder)
+                .disabled(environmentManaged)
+            Text(environmentManaged
+                 ? "Connection managed by the launch environment."
+                 : "The URL is configurable. Saved API keys stay in Keychain and are used only for this endpoint.")
+                .font(.caption).foregroundStyle(.secondary)
+            HStack {
+                if !environmentManaged {
+                    Button("Save Connection", action: save)
+                        .disabled(checking || apiURL.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
+                }
+                Button("Test Connection", action: testConnection)
+                    .disabled(checking)
+                if checking { ProgressView().controlSize(.small) }
+            }
+            if let status { Text(status).font(.caption).foregroundStyle(.secondary) }
+        }
+    }
+
+    private func save() {
+        do {
+            try ServiceAPIConfiguration.save(url: apiURL, apiKey: apiKey)
+            apiURL = ServiceAPIConfiguration.configuredURL()
+            apiKey = ""
+            status = "Connection saved."
+        } catch {
+            status = error.localizedDescription
+        }
+    }
+
+    private func testConnection() {
+        if !environmentManaged {
+            do {
+                try ServiceAPIConfiguration.save(url: apiURL, apiKey: apiKey)
+                apiKey = ""
+            } catch {
+                status = error.localizedDescription
+                return
+            }
+        }
+        checking = true
+        status = nil
+        Task {
+            let result = await Task.detached {
+                do {
+                    _ = try RecordingsCLI.list(limit: 1, home: home)
+                    return "Connected. Recordings are available."
+                } catch {
+                    return (error as? RecordingsCLI.Failure)?.message ?? error.localizedDescription
+                }
+            }.value
+            status = result
+            checking = false
+        }
+    }
+}