feat: add SQL favorites with keyword expansion (#332)

* feat: add SQL favorites with keyword expansion and sidebar UI

* fix: resolve recursive opaque type and exhaustive switch errors

* feat: redesign favorites sidebar with segmented tabs and native macOS dialog

* fix: move SSH tunnel relay I/O off cooperative thread pool to prevent deadlock

* fix: polish SQL favorites — accessibility, delete confirmation, localization, edge cases

* fix: fetch all favorites including those inside folders for tree building

* fix: favorites UX — full query fallback, search includes query text, hit testing, scope default

* fix: favorites selection state, keyboard delete, reliable dialog query passing

* fix: add .tag() to nested favorite items inside DisclosureGroup to fix selection

* fix: batch delete favorites with single notification to prevent partial deletion

* fix: inline tree rendering with AnyView for reliable List selection across folders

* feat: add drag and drop to move favorites between folders and to root

* fix: replace janky drag-drop with native 'Move to' context menu submenu

* fix: reuse current empty query tab instead of opening new tab for favorites

* fix: create tab inline when no tabs exist instead of opening new window

* fix: append favorite query to editor instead of replacing existing content

* fix: preserve trailing semicolons in SQL statements for history and favorites

* fix: address PR review — access control, validation, accessibility, thread safety

* fix: critical review issues — semicolon regression, keyword scope SQL, transaction safety, sheet identity

* docs: rewrite favorites docs — fix Vietnamese diacritics, add Chinese, update for tab design

Author: datlechin

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- SQL Favorites: save and organize frequently used queries with optional keyword bindings for autocomplete expansion
 - Copy selected rows as JSON from context menu and Edit menu
 - iCloud Sync (Pro): sync connections, groups, tags, settings, and query history across Macs via CloudKit
 - Pro feature gating system with license-aware UI overlay for Pro-only features

TablePro/ContentView.swift

@@ -237,7 +237,7 @@ struct ContentView: View {
                 .searchable(
                     text: sidebarSearchTextBinding(for: currentSession.connection.id),
                     placement: .sidebar,
-                    prompt: "Filter"
+                    prompt: sidebarSearchPrompt(for: currentSession.connection.id)
                 )
                 .navigationSplitViewColumnWidth(min: 200, ideal: 250, max: 600)
             } detail: {
@@ -355,6 +355,16 @@ struct ContentView: View {
         )
     }
 
+    private func sidebarSearchPrompt(for connectionId: UUID) -> String {
+        let state = SharedSidebarState.forConnection(connectionId)
+        switch state.selectedSidebarTab {
+        case .tables:
+            return String(localized: "Filter")
+        case .favorites:
+            return String(localized: "Filter favorites")
+        }
+    }
+
     private var sessionTableOperationOptionsBinding: Binding<[String: TableOperationOptions]> {
         createSessionBinding(
             get: { $0.tableOperationOptions },

TablePro/Core/Autocomplete/CompletionEngine.swift

@@ -46,6 +46,11 @@ final class CompletionEngine {
 
     // MARK: - Public API
 
+    /// Update favorite keywords for autocomplete expansion
+    func updateFavoriteKeywords(_ keywords: [String: (name: String, query: String)]) {
+        provider.updateFavoriteKeywords(keywords)
+    }
+
     /// Get completions for the given text and cursor position
     /// This is a pure function - no side effects
     func getCompletions(

TablePro/Core/Autocomplete/SQLCompletionItem.swift

@@ -18,6 +18,7 @@ enum SQLCompletionKind: String, CaseIterable {
     case schema     // Database/schema names
     case alias      // Table aliases
     case `operator` // Operators (=, <>, LIKE, etc.)
+    case favorite   // Saved SQL favorite (keyword expansion)
 
     /// SF Symbol for display
     var iconName: String {
@@ -30,6 +31,7 @@ enum SQLCompletionKind: String, CaseIterable {
         case .schema: return "s.circle.fill"
         case .alias: return "a.circle.fill"
         case .operator: return "equal.circle.fill"
+        case .favorite: return "star.circle.fill"
         }
     }
 
@@ -44,12 +46,14 @@ enum SQLCompletionKind: String, CaseIterable {
         case .schema: return .systemGreen
         case .alias: return .systemGray
         case .operator: return .systemIndigo
+        case .favorite: return .systemYellow
         }
     }
 
     /// Base sort priority (lower = higher priority in same context)
     var basePriority: Int {
         switch self {
+        case .favorite: return 50
         case .column: return 100
         case .table: return 200
         case .view: return 210
@@ -259,4 +263,15 @@ extension SQLCompletionItem {
             documentation: documentation
         )
     }
+
+    /// Create a favorite keyword expansion item
+    static func favorite(keyword: String, name: String, query: String) -> SQLCompletionItem {
+        SQLCompletionItem(
+            label: keyword,
+            kind: .favorite,
+            insertText: query,
+            detail: name,
+            documentation: String(query.prefix(200))
+        )
+    }
 }

TablePro/Core/Autocomplete/SQLCompletionProvider.swift

@@ -17,6 +17,7 @@ final class SQLCompletionProvider {
     private var databaseType: DatabaseType?
     private var cachedDialect: SQLDialectDescriptor?
     private var cachedStatementCompletions: [CompletionEntry] = []
+    private var favoriteKeywords: [String: (name: String, query: String)] = [:]
 
     /// Minimum prefix length to trigger suggestions
     private let minPrefixLength = 1
@@ -41,6 +42,11 @@ final class SQLCompletionProvider {
         self.cachedStatementCompletions = statementCompletions
     }
 
+    /// Update cached favorite keywords for autocomplete expansion
+    func updateFavoriteKeywords(_ keywords: [String: (name: String, query: String)]) {
+        self.favoriteKeywords = keywords
+    }
+
     // MARK: - Public API
 
     /// Get completion suggestions for the current cursor position
@@ -81,6 +87,14 @@ final class SQLCompletionProvider {
     ) async -> [SQLCompletionItem] {
         var items: [SQLCompletionItem] = []
 
+        // Check for favorite keyword matches first (highest priority)
+        if !favoriteKeywords.isEmpty && !context.prefix.isEmpty {
+            let lowerPrefix = context.prefix.lowercased()
+            for (keyword, value) in favoriteKeywords where keyword.lowercased().hasPrefix(lowerPrefix) {
+                items.append(.favorite(keyword: keyword, name: value.name, query: value.query))
+            }
+        }
+
         // If we have a dot prefix, we're looking for columns of a specific table
         if let dotPrefix = context.dotPrefix {
             // Resolve the table name from alias or direct reference

TablePro/Core/SSH/LibSSH2Tunnel.swift

@@ -30,6 +30,13 @@ internal final class LibSSH2Tunnel: @unchecked Sendable {
     private let isAlive = OSAllocatedUnfairLock(initialState: true)
     private let relayTasks = OSAllocatedUnfairLock(initialState: [Task<Void, Never>]())
 
+    /// Dedicated queue for blocking I/O (poll, send, recv, libssh2 calls).
+    /// Keeps blocking work off the Swift cooperative thread pool.
+    private static let relayQueue = DispatchQueue(
+        label: "com.TablePro.ssh.relay",
+        qos: .utility
+    )
+
     /// Callback invoked when the tunnel dies (keep-alive failure, etc.)
     var onDeath: ((UUID) -> Void)?
 
@@ -64,34 +71,41 @@ internal final class LibSSH2Tunnel: @unchecked Sendable {
 
         forwardingTask = Task.detached { [weak self] in
             guard let self else { return }
-            Self.logger.info("Forwarding started on port \(self.localPort) -> \(remoteHost):\(remotePort)")
 
-            while !Task.isCancelled && self.isRunning {
-                let clientFD = self.acceptClient()
-                guard clientFD >= 0 else {
-                    if !Task.isCancelled && self.isRunning {
-                        // accept timed out or was interrupted, retry
-                        continue
-                    }
-                    break
-                }
+            await withCheckedContinuation { (continuation: CheckedContinuation<Void, Never>) in
+                Self.relayQueue.async { [weak self] in
+                    defer { continuation.resume() }
+                    guard let self else { return }
 
-                let channel = self.openDirectTcpipChannel(
-                    remoteHost: remoteHost,
-                    remotePort: remotePort
-                )
+                    Self.logger.info("Forwarding started on port \(self.localPort) -> \(remoteHost):\(remotePort)")
 
-                guard let channel else {
-                    Self.logger.error("Failed to open direct-tcpip channel")
-                    Darwin.close(clientFD)
-                    continue
-                }
+                    while self.isRunning {
+                        let clientFD = self.acceptClient()
+                        guard clientFD >= 0 else {
+                            if self.isRunning {
+                                continue
+                            }
+                            break
+                        }
 
-                Self.logger.debug("Client connected, relaying to \(remoteHost):\(remotePort)")
-                self.spawnRelay(clientFD: clientFD, channel: channel)
-            }
+                        let channel = self.openDirectTcpipChannel(
+                            remoteHost: remoteHost,
+                            remotePort: remotePort
+                        )
 
-            Self.logger.info("Forwarding loop ended for port \(self.localPort)")
+                        guard let channel else {
+                            Self.logger.error("Failed to open direct-tcpip channel")
+                            Darwin.close(clientFD)
+                            continue
+                        }
+
+                        Self.logger.debug("Client connected, relaying to \(remoteHost):\(remotePort)")
+                        self.spawnRelay(clientFD: clientFD, channel: channel)
+                    }
+
+                    Self.logger.info("Forwarding loop ended for port \(self.localPort)")
+                }
+            }
         }
     }
 
@@ -271,36 +285,57 @@ internal final class LibSSH2Tunnel: @unchecked Sendable {
     }
 
     /// Bidirectional relay between a client socket and an SSH channel.
+    /// Runs on a dedicated dispatch queue to avoid blocking Swift's cooperative thread pool.
     private func spawnRelay(clientFD: Int32, channel: OpaquePointer) {
+        // Wrap the blocking relay in a Task so close() can cancel/await it,
+        // but immediately hop to the dedicated dispatch queue for the actual I/O.
         let task = Task.detached { [weak self] in
             guard let self else {
                 Darwin.close(clientFD)
                 return
             }
 
-            let buffer = UnsafeMutablePointer<CChar>.allocate(capacity: Self.relayBufferSize)
-            defer {
-                buffer.deallocate()
-                Darwin.close(clientFD)
-                // Only clean up libssh2 channel if the tunnel is still running.
-                // When close() tears down the tunnel, the session is freed first,
-                // making channel calls invalid (use-after-free).
-                if self.isRunning {
-                    libssh2_channel_close(channel)
-                    libssh2_channel_free(channel)
+            await withCheckedContinuation { (continuation: CheckedContinuation<Void, Never>) in
+                Self.relayQueue.async { [weak self] in
+                    defer { continuation.resume() }
+                    guard let self else {
+                        Darwin.close(clientFD)
+                        return
+                    }
+                    self.runRelay(clientFD: clientFD, channel: channel)
                 }
             }
+        }
 
-            while !Task.isCancelled && self.isRunning {
-                var pollFDs = [
-                    pollfd(fd: clientFD, events: Int16(POLLIN), revents: 0),
-                    pollfd(fd: self.socketFD, events: Int16(POLLIN), revents: 0),
-                ]
+        relayTasks.withLock { tasks in
+            tasks.removeAll { $0.isCancelled }
+            tasks.append(task)
+        }
+    }
+
+    /// Blocking relay loop — must only be called on `relayQueue`, never the cooperative pool.
+    private func runRelay(clientFD: Int32, channel: OpaquePointer) {
+        let buffer = UnsafeMutablePointer<CChar>.allocate(capacity: Self.relayBufferSize)
+        defer {
+            buffer.deallocate()
+            Darwin.close(clientFD)
+            if self.isRunning {
+                libssh2_channel_close(channel)
+                libssh2_channel_free(channel)
+            }
+        }
+
+        while self.isRunning {
+            var pollFDs = [
+                pollfd(fd: clientFD, events: Int16(POLLIN), revents: 0),
+                pollfd(fd: self.socketFD, events: Int16(POLLIN), revents: 0),
+            ]
 
-                let pollResult = poll(&pollFDs, 2, 100) // 100ms timeout
-                if pollResult < 0 { break }
+            let pollResult = poll(&pollFDs, 2, 100) // 100ms timeout
+            if pollResult < 0 { break }
 
-                // Read from SSH channel -> write to client
+            // Only read from SSH channel when the SSH socket has data ready
+            if pollFDs[1].revents & Int16(POLLIN) != 0 {
                 let channelRead = tablepro_libssh2_channel_read(
                     channel, buffer, Self.relayBufferSize
                 )
@@ -317,42 +352,62 @@ internal final class LibSSH2Tunnel: @unchecked Sendable {
                         totalSent += sent
                     }
                 } else if channelRead == 0 || libssh2_channel_eof(channel) != 0 {
-                    // Channel EOF
                     return
                 } else if channelRead != Int(LIBSSH2_ERROR_EAGAIN) {
-                    // Real error
                     return
                 }
+            }
 
-                // Read from client -> write to SSH channel
-                if pollFDs[0].revents & Int16(POLLIN) != 0 {
-                    let clientRead = recv(clientFD, buffer, Self.relayBufferSize, 0)
-                    if clientRead <= 0 { return }
-
-                    var totalWritten = 0
-                    while totalWritten < Int(clientRead) {
-                        let written = tablepro_libssh2_channel_write(
-                            channel,
-                            buffer.advanced(by: totalWritten),
-                            Int(clientRead) - totalWritten
+            // Also attempt a non-blocking channel read when poll timed out,
+            // because libssh2 may have buffered data internally
+            if pollResult == 0 {
+                let channelRead = tablepro_libssh2_channel_read(
+                    channel, buffer, Self.relayBufferSize
+                )
+                if channelRead > 0 {
+                    var totalSent = 0
+                    while totalSent < Int(channelRead) {
+                        let sent = send(
+                            clientFD,
+                            buffer.advanced(by: totalSent),
+                            Int(channelRead) - totalSent,
+                            0
                         )
-                        if written > 0 {
-                            totalWritten += Int(written)
-                        } else if written == Int(LIBSSH2_ERROR_EAGAIN) {
-                            _ = self.waitForSocket(
-                                session: self.session,
-                                socketFD: self.socketFD,
-                                timeoutMs: 1_000
-                            )
-                        } else {
-                            return
-                        }
+                        if sent <= 0 { return }
+                        totalSent += sent
+                    }
+                } else if channelRead == 0 || libssh2_channel_eof(channel) != 0 {
+                    return
+                }
+                // Ignore EAGAIN on timeout read — no data buffered
+            }
+
+            // Read from client -> write to SSH channel
+            if pollFDs[0].revents & Int16(POLLIN) != 0 {
+                let clientRead = recv(clientFD, buffer, Self.relayBufferSize, 0)
+                if clientRead <= 0 { return }
+
+                var totalWritten = 0
+                while totalWritten < Int(clientRead) {
+                    let written = tablepro_libssh2_channel_write(
+                        channel,
+                        buffer.advanced(by: totalWritten),
+                        Int(clientRead) - totalWritten
+                    )
+                    if written > 0 {
+                        totalWritten += Int(written)
+                    } else if written == Int(LIBSSH2_ERROR_EAGAIN) {
+                        _ = self.waitForSocket(
+                            session: self.session,
+                            socketFD: self.socketFD,
+                            timeoutMs: 1_000
+                        )
+                    } else {
+                        return
                     }
                 }
             }
         }
-
-        relayTasks.withLock { $0.append(task) }
     }
 
     /// Wait for the SSH socket to become ready, based on libssh2's block directions.

TablePro/Core/Services/Infrastructure/AppNotifications.swift

@@ -18,4 +18,8 @@ extension Notification.Name {
 
     static let connectionUpdated = Notification.Name("connectionUpdated")
     static let databaseDidConnect = Notification.Name("databaseDidConnect")
+
+    // MARK: - SQL Favorites
+
+    static let sqlFavoritesDidUpdate = Notification.Name("sqlFavoritesDidUpdate")
 }