@lattices/cli 0.4.2 → 0.4.6

package/README.md

@@ -58,6 +58,9 @@ To build a signed, notarized DMG for distribution:
 ```sh
 # Requires a Developer ID certificate and notarytool keychain profile
 ./scripts/build-dmg.sh
+
+# Update v<package.json version> and upload the DMG to GitHub Releases
+./scripts/ship.sh
 ```
 
 ## Quick start

package/app/Info.plist

@@ -15,9 +15,9 @@
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleVersion</key>
-    <string>0.4.2</string>
+    <string>0.4.6</string>
     <key>CFBundleShortVersionString</key>
-    <string>0.4.2</string>
+    <string>0.4.6</string>
     <key>LSMinimumSystemVersion</key>
     <string>13.0</string>
     <key>LSUIElement</key>

package/app/Lattices.app/Contents/Info.plist

@@ -15,9 +15,9 @@
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleVersion</key>
-    <string>0.4.2</string>
+    <string>0.4.6</string>
     <key>CFBundleShortVersionString</key>
-    <string>0.4.2</string>
+    <string>0.4.6</string>
     <key>LSMinimumSystemVersion</key>
     <string>13.0</string>
     <key>LSUIElement</key>

package/app/Package.swift

@@ -4,9 +4,15 @@ import PackageDescription
 let package = Package(
     name: "Lattices",
     platforms: [.macOS(.v13)],
+    dependencies: [
+        .package(path: "../swift")
+    ],
     targets: [
         .executableTarget(
             name: "Lattices",
+            dependencies: [
+                .product(name: "DeckKit", package: "swift")
+            ],
             path: "Sources",
             resources: [
                 .copy("../Resources/tap.wav"),

package/app/Sources/AppShell/App.swift

@@ -0,0 +1,20 @@
+import SwiftUI
+
+@main
+struct LatticesApp: App {
+    @NSApplicationDelegateAdaptor(AppDelegate.self) var delegate
+
+    var body: some Scene {
+        Settings { EmptyView() }
+            .commands {
+                CommandGroup(after: .appInfo) {
+                    Button("Update Lattices…") {
+                        AppUpdater.shared.promptForUpdate()
+                    }
+                    .disabled(!AppUpdater.shared.canUpdate)
+
+                    Divider()
+                }
+            }
+    }
+}

package/app/Sources/{AppDelegate.swift → AppShell/AppDelegate.swift}

@@ -1,9 +1,14 @@
 import AppKit
 import SwiftUI
 
+extension Notification.Name {
+    static let latticesPopoverWillShow = Notification.Name("latticesPopoverWillShow")
+}
+
 /// Manages the NSStatusItem (menu bar icon), left-click popover, and right-click context menu.
 /// Replaces the previous SwiftUI MenuBarExtra approach for full click-event control.
 class AppDelegate: NSObject, NSApplicationDelegate, NSPopoverDelegate {
+    private static weak var shared: AppDelegate?
 
     private var statusItem: NSStatusItem!
     private var popover: NSPopover?
@@ -45,6 +50,7 @@ class AppDelegate: NSObject, NSApplicationDelegate, NSPopoverDelegate {
     /// based on whether any managed windows are open.
     static func updateActivationPolicy() {
         let hasVisibleWindow =
+            (Self.shared?.popover?.isShown == true) ||
             CommandModeWindow.shared.isVisible ||
             CommandPaletteWindow.shared.isVisible ||
             MainWindow.shared.isVisible ||
@@ -60,6 +66,7 @@ class AppDelegate: NSObject, NSApplicationDelegate, NSPopoverDelegate {
     }
 
     func applicationDidFinishLaunching(_ notification: Notification) {
+        Self.shared = self
         NSApp.setActivationPolicy(.accessory)
         NSApp.appearance = NSAppearance(named: .darkAqua)
 
@@ -82,8 +89,12 @@ class AppDelegate: NSObject, NSApplicationDelegate, NSPopoverDelegate {
         let store = HotkeyStore.shared
         store.register(action: .palette) { CommandPaletteWindow.shared.toggle() }
         store.register(action: .unifiedWindow) { ScreenMapWindowController.shared.toggle() }
-        store.register(action: .bezel) { WindowBezel.showBezelForFrontmostWindow() }
-        store.register(action: .cheatSheet) { CheatSheetHUD.shared.toggle() }
+        store.register(action: .bezel) { Self.showWorkspaceInspector() }
+        store.register(action: .cheatSheet) { SettingsWindowController.shared.show() }
+        store.register(action: .desktopInventory) {
+            DiagnosticLog.shared.info("Hotkey: desktopInventory triggered")
+            ScreenMapWindowController.shared.showPage(.desktopInventory)
+        }
         store.register(action: .voiceCommand) {
             DiagnosticLog.shared.info("Hotkey: voiceCommand triggered")
             VoiceCommandWindow.shared.toggle()
@@ -103,7 +114,16 @@ class AppDelegate: NSObject, NSApplicationDelegate, NSPopoverDelegate {
 
         // Pre-render HUD panels off-screen for instant first open
         DispatchQueue.main.async { HUDController.shared.warmUp() }
+        // Pre-build the menu bar popover so the first click doesn't pay the SwiftUI mount cost.
+        // Touching `.view` forces NSHostingController to materialize the SwiftUI view tree.
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self else { return }
+            let p = self.makePopover()
+            _ = p.contentViewController?.view
+        }
         store.register(action: .omniSearch) { OmniSearchWindow.shared.toggle() }
+        WindowDragSnapController.shared.start()
+        MouseGestureController.shared.start()
 
         // Session layer cycling
         store.register(action: .layerNext) { SessionLayerStore.shared.cycleNext() }
@@ -140,7 +160,8 @@ class AppDelegate: NSObject, NSApplicationDelegate, NSPopoverDelegate {
         for (action, position) in tileMap {
             store.register(action: action) { WindowTiler.tileFrontmostViaAX(to: position) }
         }
-        store.register(action: .tileDistribute) { WindowTiler.distributeVisible() }
+        store.register(action: .tileDistribute) { WindowTiler.distributeVisible(reactivateLattices: false) }
+        store.register(action: .tileTypeGrid) { WindowTiler.distributeVisibleByFrontmostType(reactivateLattices: false) }
 
         // Onboarding on first launch; otherwise just check permissions
         if !OnboardingWindowController.shared.showIfNeeded() {
@@ -157,6 +178,7 @@ class AppDelegate: NSObject, NSApplicationDelegate, NSPopoverDelegate {
         ProcessModel.shared.start()
         LatticesApi.setup()
         DaemonServer.shared.start()
+        LatticesCompanionBridgeServer.shared.start()
         AgentPool.shared.start()
         diag.finish(tBoot)
 
@@ -167,14 +189,19 @@ class AppDelegate: NSObject, NSApplicationDelegate, NSPopoverDelegate {
             }
         }
 
-        // --screen-map flag: auto-open screen map on launch
+        // --screen-map flag: auto-open layout on launch
         if CommandLine.arguments.contains("--screen-map") {
             DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {
-                ScreenMapWindowController.shared.show()
+                ScreenMapWindowController.shared.showPage(.screenMap)
             }
         }
     }
 
+    func applicationWillTerminate(_ notification: Notification) {
+        LatticesCompanionBridgeServer.shared.stop()
+        DaemonServer.shared.stop()
+    }
+
     // MARK: - Status item click handler
 
     @objc private func statusItemClicked(_ sender: Any?) {
@@ -184,13 +211,11 @@ class AppDelegate: NSObject, NSApplicationDelegate, NSPopoverDelegate {
             // Right-click → context menu
             contextMenu.popUp(positioning: nil, at: NSPoint(x: 0, y: button.bounds.height + 4), in: button)
         } else {
-            // Left-click → toggle popover
+            // Left-click → toggle the menu bar projects popover.
             if let shown = popover, shown.isShown {
                 shown.performClose(sender)
             } else {
-                let p = makePopover()
-                p.show(relativeTo: button.bounds, of: button, preferredEdge: .minY)
-                p.contentViewController?.view.window?.makeKey()
+                showProjectsPopover()
             }
         }
     }
@@ -200,14 +225,16 @@ class AppDelegate: NSObject, NSApplicationDelegate, NSPopoverDelegate {
         popover?.performClose(nil)
     }
 
-    /// Create a fresh popover each time so the SwiftUI view tree isn't kept alive
-    /// when the popover is closed — prevents continuous CPU usage from @Published updates.
+    /// Cached popover — built lazily on first click, reused on every subsequent open.
+    /// Keeping the SwiftUI view tree alive avoids rebuilding on each click (slow first paint).
+    /// Data refresh is driven from `popoverWillShow` + a notification MainView listens to.
     private func makePopover() -> NSPopover {
+        if let p = popover { return p }
         let t = DiagnosticLog.shared.startTimed("makePopover")
         let p = NSPopover()
         p.contentViewController = NSHostingController(rootView: MainView(scanner: ProjectScanner.shared))
         p.behavior = .transient
-        p.contentSize = NSSize(width: 380, height: 560)
+        p.contentSize = NSSize(width: 380, height: 300)
         p.appearance = NSAppearance(named: .darkAqua)
         p.delegate = self
         popover = p
@@ -215,10 +242,20 @@ class AppDelegate: NSObject, NSApplicationDelegate, NSPopoverDelegate {
         return p
     }
 
+    private func showProjectsPopover() {
+        guard let button = statusItem.button else { return }
+        let p = makePopover()
+        p.show(relativeTo: button.bounds, of: button, preferredEdge: .minY)
+        p.contentViewController?.view.window?.makeKey()
+    }
+
+    func popoverWillShow(_ notification: Notification) {
+        Self.updateActivationPolicy()
+        NotificationCenter.default.post(name: .latticesPopoverWillShow, object: nil)
+    }
+
     func popoverDidClose(_ notification: Notification) {
-        // Tear down the SwiftUI view tree so observed models stop driving re-renders
-        popover?.contentViewController = nil
-        popover = nil
+        Self.updateActivationPolicy()
     }
 
     // MARK: - Context menu
@@ -227,10 +264,10 @@ class AppDelegate: NSObject, NSApplicationDelegate, NSPopoverDelegate {
         let menu = NSMenu()
 
         let actions: [(String, String, Selector)] = [
+            ("Home", "", #selector(menuWorkspace)),
+            ("Layout", "", #selector(menuLayout)),
+            ("Search", "", #selector(menuSearch)),
             ("Command Palette", "⌘⇧M", #selector(menuCommandPalette)),
-            ("Workspace", "", #selector(menuWorkspace)),
-            ("Assistant", "", #selector(menuAssistant)),
-            ("Help & Shortcuts", "", #selector(menuDocs)),
         ]
         for (title, shortcut, action) in actions {
             let item = NSMenuItem(title: title, action: action, keyEquivalent: "")
@@ -243,14 +280,29 @@ class AppDelegate: NSObject, NSApplicationDelegate, NSPopoverDelegate {
 
         menu.addItem(.separator())
 
-        let settings = NSMenuItem(title: "Settings…", action: #selector(menuSettings), keyEquivalent: ",")
+        let cliActions: [(String, Selector)] = [
+            ("Projects…", #selector(menuProjects)),
+            ("Initialize Project in Terminal…", #selector(menuInitializeProject)),
+            ("Launch Project in Terminal…", #selector(menuLaunchProject)),
+        ]
+        for (title, action) in cliActions {
+            let item = NSMenuItem(title: title, action: action, keyEquivalent: "")
+            item.target = self
+            menu.addItem(item)
+        }
+
+        menu.addItem(.separator())
+
+        let update = NSMenuItem(title: "Update Lattices…", action: #selector(menuUpdate), keyEquivalent: "")
+        update.target = self
+        menu.addItem(update)
+
+        menu.addItem(.separator())
+
+        let settings = NSMenuItem(title: "Help & Settings…", action: #selector(menuSettings), keyEquivalent: ",")
         settings.target = self
         menu.addItem(settings)
 
-        let diag = NSMenuItem(title: "Diagnostics", action: #selector(menuDiagnostics), keyEquivalent: "")
-        diag.target = self
-        menu.addItem(diag)
-
         menu.addItem(.separator())
 
         let quit = NSMenuItem(title: "Quit Lattices", action: #selector(menuQuit), keyEquivalent: "q")
@@ -262,19 +314,27 @@ class AppDelegate: NSObject, NSApplicationDelegate, NSPopoverDelegate {
 
     @objc private func menuCommandPalette() { CommandPaletteWindow.shared.toggle() }
     @objc private func menuWorkspace() { ScreenMapWindowController.shared.showPage(.home) }
-    @objc private func menuAssistant() {
-        if AudioLayer.shared.isListening || VoiceCommandWindow.shared.isVisible {
-            VoiceCommandWindow.shared.toggle()
-        } else {
-            OmniSearchWindow.shared.show()
-        }
-    }
-    @objc private func menuDocs() { ScreenMapWindowController.shared.showPage(.docs) }
+    @objc private func menuLayout() { ScreenMapWindowController.shared.showPage(.screenMap) }
+    @objc private func menuSearch() { ScreenMapWindowController.shared.showPage(.desktopInventory) }
+    @objc private func menuDocs() { SettingsWindowController.shared.show() }
+    @objc private func menuProjects() { DispatchQueue.main.async { self.showProjectsPopover() } }
+    @objc private func menuInitializeProject() { CliActionLauncher.initializeProjectInTerminal() }
+    @objc private func menuLaunchProject() { CliActionLauncher.launchProjectInTerminal() }
     @objc private func menuHUD() { HUDController.shared.toggle() }
-    @objc private func menuWindowBezel() { WindowBezel.showBezelForFrontmostWindow() }
-    @objc private func menuCheatSheet() { CheatSheetHUD.shared.toggle() }
+    @objc private func menuWindowBezel() { Self.showWorkspaceInspector() }
+    @objc private func menuCheatSheet() { SettingsWindowController.shared.show() }
     @objc private func menuOmniSearch() { OmniSearchWindow.shared.toggle() }
+    @MainActor @objc private func menuUpdate() { AppUpdater.shared.promptForUpdate() }
     @objc private func menuSettings() { SettingsWindowController.shared.show() }
-    @objc private func menuDiagnostics() { DiagnosticWindow.shared.toggle() }
     @objc private func menuQuit() { NSApp.terminate(nil) }
+
+    private static func showWorkspaceInspector() {
+        guard let entry = DesktopModel.shared.frontmostWindow(),
+              entry.app != "Lattices" else {
+            ScreenMapWindowController.shared.showPage(.screenMap)
+            return
+        }
+
+        ScreenMapWindowController.shared.showWindow(wid: entry.wid)
+    }
 }

package/app/Sources/{AppShellView.swift → AppShell/AppShellView.swift}

@@ -56,6 +56,10 @@ struct AppShellView: View {
         .background(Palette.bg)
         .onAppear {
             commandState.onDismiss = { windowController.activePage = .home }
+            syncPageState(windowController.activePage)
+        }
+        .onChange(of: windowController.activePage) { page in
+            syncPageState(page)
         }
     }
 
@@ -66,6 +70,7 @@ struct AppShellView: View {
             ForEach(AppPage.primaryTabs, id: \.rawValue) { tab in
                 tabButton(tab)
             }
+
             Spacer()
         }
         .padding(.horizontal, 12)
@@ -90,6 +95,7 @@ struct AppShellView: View {
             .foregroundColor(isActive ? Palette.text : Palette.textMuted)
             .padding(.horizontal, 12)
             .padding(.vertical, 6)
+            .contentShape(Rectangle())
             .background(
                 RoundedRectangle(cornerRadius: 6)
                     .fill(isActive ? Palette.surfaceHov : Color.clear)
@@ -114,7 +120,7 @@ struct AppShellView: View {
                 windowController.activePage = page
             })
         case .desktopInventory:
-            CommandModeView(state: commandState)
+            CommandModeView(state: commandState, presentation: .embedded)
         case .pi:
             PiWorkspaceView()
         case .settings:
@@ -132,4 +138,9 @@ struct AppShellView: View {
             )
         }
     }
+
+    private func syncPageState(_ page: AppPage) {
+        if page == .screenMap { controller.enter() }
+        if page == .desktopInventory { commandState.enter() }
+    }
 }

package/app/Sources/AppShell/AppUpdater.swift

@@ -0,0 +1,92 @@
+import AppKit
+import Combine
+import Foundation
+
+@MainActor
+final class AppUpdater: ObservableObject {
+    static let shared = AppUpdater()
+
+    @Published private(set) var isUpdating = false
+    @Published private(set) var statusMessage: String?
+
+    private init() {}
+
+    var currentVersion: String { LatticesRuntime.appVersion }
+
+    var canUpdate: Bool {
+        LatticesRuntime.bunPath != nil && LatticesRuntime.appHelperScriptPath != nil
+    }
+
+    var unavailableReason: String? {
+        if LatticesRuntime.bunPath == nil {
+            return "Install Bun to enable in-app updates."
+        }
+        if LatticesRuntime.appHelperScriptPath == nil {
+            return "Launch Lattices via `lattices app` so the updater can find the CLI bundle."
+        }
+        return nil
+    }
+
+    func promptForUpdate() {
+        guard canUpdate else {
+            presentAlert(
+                title: "Update Unavailable",
+                message: unavailableReason ?? "Lattices could not locate its updater."
+            )
+            return
+        }
+
+        let alert = NSAlert()
+        alert.alertStyle = .informational
+        alert.messageText = "Install the latest Lattices app update?"
+        alert.informativeText = "Lattices will download the latest released app bundle, close, and relaunch when the update is ready."
+        alert.addButton(withTitle: "Update")
+        alert.addButton(withTitle: "Cancel")
+
+        guard alert.runModal() == .alertFirstButtonReturn else { return }
+        startDetachedUpdate()
+    }
+
+    private func startDetachedUpdate() {
+        guard !isUpdating else { return }
+        guard let bunPath = LatticesRuntime.bunPath,
+              let scriptPath = LatticesRuntime.appHelperScriptPath else {
+            presentAlert(
+                title: "Update Unavailable",
+                message: unavailableReason ?? "Lattices could not locate its updater."
+            )
+            return
+        }
+
+        let proc = Process()
+        proc.executableURL = URL(fileURLWithPath: bunPath)
+        proc.arguments = [scriptPath, "update", "--detach", "--launch"]
+        if let cliRoot = LatticesRuntime.cliRoot {
+            proc.currentDirectoryURL = URL(fileURLWithPath: cliRoot)
+        }
+
+        var env = ProcessInfo.processInfo.environment
+        env.removeValue(forKey: "CLAUDECODE")
+        proc.environment = env
+
+        do {
+            try proc.run()
+            isUpdating = true
+            statusMessage = "Updating to the latest release. Lattices will relaunch when it's ready."
+        } catch {
+            presentAlert(
+                title: "Update Failed",
+                message: "Lattices could not start the updater.\n\n\(error.localizedDescription)"
+            )
+        }
+    }
+
+    private func presentAlert(title: String, message: String) {
+        let alert = NSAlert()
+        alert.alertStyle = .warning
+        alert.messageText = title
+        alert.informativeText = message
+        alert.addButton(withTitle: "OK")
+        alert.runModal()
+    }
+}

package/app/Sources/AppShell/CliActionLauncher.swift

@@ -0,0 +1,50 @@
+import AppKit
+
+enum CliActionLauncher {
+    private static var defaultDirectory: String {
+        let root = Preferences.shared.scanRoot
+        return root.isEmpty ? NSHomeDirectory() : root
+    }
+
+    private static func chooseProjectDirectory(message: String, prompt: String) -> String? {
+        let panel = NSOpenPanel()
+        panel.message = message
+        panel.prompt = prompt
+        panel.canChooseFiles = false
+        panel.canChooseDirectories = true
+        panel.allowsMultipleSelection = false
+        panel.directoryURL = URL(fileURLWithPath: defaultDirectory)
+        return panel.runModal() == .OK ? panel.url?.path : nil
+    }
+
+    static func initializeProjectInTerminal() {
+        guard let directory = chooseProjectDirectory(
+            message: "Choose a project folder to initialize with Lattices.",
+            prompt: "Initialize"
+        ) else { return }
+
+        Preferences.shared.terminal.launch(
+            command: "lattices init && lattices",
+            in: directory
+        )
+    }
+
+    static func launchProjectInTerminal() {
+        guard let directory = chooseProjectDirectory(
+            message: "Choose a project folder to launch with Lattices.",
+            prompt: "Launch"
+        ) else { return }
+
+        Preferences.shared.terminal.launch(
+            command: "lattices",
+            in: directory
+        )
+    }
+
+    static func installTmuxInTerminal() {
+        Preferences.shared.terminal.launch(
+            command: "brew install tmux",
+            in: defaultDirectory
+        )
+    }
+}

package/app/Sources/{HomeDashboardView.swift → AppShell/HomeDashboardView.swift}

@@ -4,6 +4,7 @@ struct HomeDashboardView: View {
     var onNavigate: ((AppPage) -> Void)? = nil
 
     @ObservedObject private var scanner = ProjectScanner.shared
+    @ObservedObject private var piSession = PiChatSession.shared
 
     var body: some View {
         VStack(spacing: 0) {
@@ -16,6 +17,9 @@ struct HomeDashboardView: View {
             MainView(scanner: scanner, layout: .embedded)
         }
         .background(Palette.bg)
+        .onAppear {
+            piSession.refreshBinaryAvailability()
+        }
     }
 
     private var hero: some View {
@@ -26,7 +30,7 @@ struct HomeDashboardView: View {
                         .font(Typo.heading(18))
                         .foregroundColor(Palette.text)
 
-                    Text("Launch workspaces, jump into the screen map, or open a full Pi session from one place.")
+                    Text("Workspace status, project launch, layout, search, and chat in one place.")
                         .font(Typo.mono(11))
                         .foregroundColor(Palette.textDim)
                         .fixedSize(horizontal: false, vertical: true)
@@ -37,8 +41,8 @@ struct HomeDashboardView: View {
 
             HStack(spacing: 10) {
                 homeActionCard(
-                    title: "Screen Map",
-                    subtitle: "Spatial window layout",
+                    title: "Layout",
+                    subtitle: "Arrange windows",
                     icon: "rectangle.3.group",
                     tint: Palette.running
                 ) {
@@ -46,19 +50,23 @@ struct HomeDashboardView: View {
                 }
 
                 homeActionCard(
-                    title: "Desktop Inventory",
-                    subtitle: "Enumerate displays and spaces",
-                    icon: "macwindow.on.rectangle",
+                    title: "Search",
+                    subtitle: "Find workspace context",
+                    icon: "magnifyingglass",
                     tint: Palette.detach
                 ) {
                     onNavigate?(.desktopInventory)
                 }
 
                 homeActionCard(
-                    title: "Pi Workspace",
-                    subtitle: "Standalone conversation surface",
-                    icon: "terminal",
-                    tint: Palette.text
+                    title: "Chat",
+                    subtitle: piSession.hasPiBinary
+                        ? (piSession.needsProviderSetup || piSession.isAuthenticating
+                            ? piSession.setupStatusSummary
+                            : "Standalone conversation surface")
+                        : "Install Pi to enable the assistant",
+                    icon: "bubble.left.and.bubble.right",
+                    tint: piSession.hasPiBinary ? Palette.text : Palette.kill
                 ) {
                     onNavigate?(.pi)
                 }

package/app/Sources/AppShell/LatticesRuntime.swift

@@ -0,0 +1,61 @@
+import Foundation
+
+enum LatticesRuntime {
+    static var cliRoot: String? {
+        if let idx = CommandLine.arguments.firstIndex(of: "--lattices-cli-root"),
+           CommandLine.arguments.indices.contains(idx + 1) {
+            let root = CommandLine.arguments[idx + 1]
+            if hasAppHelper(in: root) { return root }
+        }
+
+        let bundleDerivedRoot = Bundle.main.bundleURL
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .path
+        if hasAppHelper(in: bundleDerivedRoot) {
+            return bundleDerivedRoot
+        }
+
+        let devRoot = NSHomeDirectory() + "/dev/lattices"
+        if hasAppHelper(in: devRoot) {
+            return devRoot
+        }
+
+        return nil
+    }
+
+    static var appHelperScriptPath: String? {
+        guard let cliRoot else { return nil }
+        let path = cliRoot + "/bin/lattices-app.ts"
+        return FileManager.default.fileExists(atPath: path) ? path : nil
+    }
+
+    static var bunPath: String? {
+        let candidates = [
+            NSHomeDirectory() + "/.bun/bin/bun",
+            "/usr/local/bin/bun",
+            "/opt/homebrew/bin/bun",
+        ]
+        if let path = candidates.first(where: { FileManager.default.isExecutableFile(atPath: $0) }) {
+            return path
+        }
+
+        let resolved = ProcessQuery.shell(["/bin/zsh", "-lc", "command -v bun 2>/dev/null"])
+        if !resolved.isEmpty, FileManager.default.isExecutableFile(atPath: resolved) {
+            return resolved
+        }
+
+        return nil
+    }
+
+    static var appVersion: String {
+        let info = Bundle.main.infoDictionary
+        return (info?["CFBundleShortVersionString"] as? String)
+            ?? (info?["CFBundleVersion"] as? String)
+            ?? "unknown"
+    }
+
+    private static func hasAppHelper(in root: String) -> Bool {
+        FileManager.default.fileExists(atPath: root + "/bin/lattices-app.ts")
+    }
+}