@lattices/cli 0.3.0

package/README.md

@@ -0,0 +1,155 @@
+<picture>
+  <img alt="lattices" src="site/public/og.png" />
+</picture>
+
+# lattices
+
+A workspace control plane for macOS. Manage persistent terminal sessions,
+tile and organize your windows, and index the text on your screen — all
+controllable from the CLI or a 30-method daemon API.
+
+## Install
+
+```sh
+npm install -g @lattices/cli
+```
+
+## Quick start
+
+```sh
+# Launch the menu bar app
+lattices app
+
+# Open the command palette from anywhere
+# Cmd+Shift+M
+```
+
+## Persistent terminal sessions
+
+Declare your dev environment in a `.lattices.json`: which panes, which
+commands, what layout. Lattices builds it, runs it, and keeps it alive.
+Close your laptop, reboot, come back a week later — your editor, dev
+server, and test runner are exactly where you left them.
+
+```sh
+cd my-project && lattices
+```
+
+No config? It reads your `package.json` and picks the right dev command
+automatically.
+
+### Configuration
+
+Drop a `.lattices.json` in your project root:
+
+```json
+{
+  "ensure": true,
+  "panes": [
+    { "name": "claude", "cmd": "claude", "size": 60 },
+    { "name": "server", "cmd": "pnpm dev" },
+    { "name": "tests",  "cmd": "pnpm test --watch" }
+  ]
+}
+```
+
+### Layouts
+
+```
+2 panes              3+ panes
+
+┌──────────┬───────┐ ┌──────────┬───────┐
+│  claude  │server │ │  claude  │server │
+│  (60%)   │(40%)  │ │  (60%)   ├───────┤
+└──────────┴───────┘ │          │tests  │
+                     └──────────┴───────┘
+```
+
+### Workspace layers
+
+Group projects into switchable contexts. `Cmd+Option+1` tiles your
+frontend and API side by side. `Cmd+Option+2` for the mobile stack.
+Sessions stay alive across switches.
+
+### Tab groups
+
+Bundle related repos as tabs in one session. Each tab gets its own
+pane layout from its `.lattices.json`.
+
+```sh
+lattices group talkie      # Launch iOS, macOS, Web, API as tabs
+lattices tab talkie iOS    # Switch to the iOS tab
+```
+
+## Window tiling and awareness
+
+A native menu bar app tracks every window across all your monitors.
+Tile with hotkeys, organize into switchable layers, snap to grids.
+
+It reads your windows too — extracting text from UI elements every
+60 seconds and running Vision OCR on background windows every 2 hours.
+Everything is searchable.
+
+```sh
+lattices scan                  # View current screen text
+lattices scan search "error"   # Search across all indexed text
+lattices scan recent           # Browse scan history
+lattices scan deep             # Trigger a Vision OCR scan now
+```
+
+## A programmable desktop
+
+The menu bar app runs a daemon with 30 RPC methods and 5 real-time
+events over WebSocket. Anything you can do from the app, an agent or
+script can do over the API.
+
+```js
+import { daemonCall } from '@lattices/cli/daemon-client'
+
+const windows = await daemonCall('windows.list')
+await daemonCall('session.launch', { path: '/Users/you/dev/frontend' })
+await daemonCall('window.tile', { session: 'frontend-a1b2c3', position: 'left' })
+
+// Read the screen
+await daemonCall('ocr.scan')
+const errors = await daemonCall('ocr.search', { query: 'error OR failed' })
+```
+
+Claude Code skills, MCP servers, or your own scripts can drive your
+desktop the same way you do.
+
+## CLI
+
+```
+lattices                    Create or reattach to session
+lattices init               Generate .lattices.json
+lattices ls                 List active sessions
+lattices kill [name]        Kill a session
+lattices tile <position>    Tile frontmost window
+lattices group [id]         Launch or attach a tab group
+lattices tab <group> [tab]  Switch tab within a group
+lattices scan               View current screen text
+lattices scan search <q>    Search indexed text
+lattices scan recent [n]    Browse scan history
+lattices scan deep          Trigger Vision OCR now
+lattices app                Launch the menu bar app
+lattices help               Show help
+```
+
+## Requirements
+
+- macOS 13.0+
+- Node.js 18+
+
+### Optional
+
+- tmux for persistent terminal sessions (`brew install tmux`)
+- Swift 5.9+ to build the menu bar app from source
+
+## Docs
+
+[lattices.dev/docs](https://lattices.dev/docs/overview)
+
+## License
+
+MIT

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

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>CFBundleIdentifier</key>
+    <string>com.arach.lattices</string>
+    <key>CFBundleName</key>
+    <string>Lattices</string>
+    <key>CFBundleExecutable</key>
+    <string>Lattices</string>
+    <key>CFBundleIconFile</key>
+    <string>AppIcon</string>
+    <key>CFBundlePackageType</key>
+    <string>APPL</string>
+    <key>CFBundleVersion</key>
+    <string>1</string>
+    <key>CFBundleShortVersionString</key>
+    <string>0.1.0</string>
+    <key>LSUIElement</key>
+    <true/>
+    <key>NSSupportsAutomaticTermination</key>
+    <true/>
+</dict>
+</plist>

package/app/Package.swift

@@ -0,0 +1,13 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "Lattices",
+    platforms: [.macOS(.v13)],
+    targets: [
+        .executableTarget(
+            name: "Lattices",
+            path: "Sources"
+        )
+    ]
+)

package/app/Sources/AccessibilityTextExtractor.swift

@@ -0,0 +1,111 @@
+import AppKit
+
+// Private API: get CGWindowID from an AXUIElement (already declared in WindowTiler.swift)
+// We reuse the same _AXUIElementGetWindow binding.
+
+struct AXTextResult {
+    let wid: UInt32
+    let texts: [String]
+    let fullText: String
+}
+
+final class AccessibilityTextExtractor {
+    static let timeoutSeconds: TimeInterval = 0.2
+    static let maxDepth: Int = 4
+    static let maxChildrenPerNode: Int = 30
+
+    /// Extract text from a window's AX element tree.
+    /// Returns nil if AX fails or yields fewer than `minChars` characters.
+    func extract(pid: Int32, wid: UInt32, minChars: Int = 12) -> AXTextResult? {
+        let appRef = AXUIElementCreateApplication(pid)
+
+        // Find the AXUIElement matching this wid
+        var windowsRef: CFTypeRef?
+        let err = AXUIElementCopyAttributeValue(appRef, kAXWindowsAttribute as CFString, &windowsRef)
+        guard err == .success, let axWindows = windowsRef as? [AXUIElement] else { return nil }
+
+        var targetWindow: AXUIElement?
+        for axWin in axWindows {
+            var winID: CGWindowID = 0
+            if _AXUIElementGetWindow(axWin, &winID) == .success, winID == CGWindowID(wid) {
+                targetWindow = axWin
+                break
+            }
+        }
+
+        guard let window = targetWindow else { return nil }
+
+        let deadline = Date().addingTimeInterval(Self.timeoutSeconds)
+        var collected: [String] = []
+
+        walkChildren(element: window, depth: 0, deadline: deadline, collected: &collected)
+
+        let fullText = collected.joined(separator: "\n")
+        guard fullText.count >= minChars else { return nil }
+
+        return AXTextResult(wid: wid, texts: collected, fullText: fullText)
+    }
+
+    // MARK: - Tree Walker
+
+    private func walkChildren(
+        element: AXUIElement,
+        depth: Int,
+        deadline: Date,
+        collected: inout [String]
+    ) {
+        guard depth < Self.maxDepth, Date() < deadline else { return }
+
+        // Extract text attributes from this element
+        extractText(from: element, into: &collected)
+
+        // Get children — prefer visible children, fall back to all children
+        var childrenRef: CFTypeRef?
+        var gotChildren = false
+
+        let visErr = AXUIElementCopyAttributeValue(element, kAXVisibleChildrenAttribute as CFString, &childrenRef)
+        if visErr == .success, let children = childrenRef as? [AXUIElement], !children.isEmpty {
+            gotChildren = true
+            let capped = children.prefix(Self.maxChildrenPerNode)
+            for child in capped {
+                guard Date() < deadline else { return }
+                walkChildren(element: child, depth: depth + 1, deadline: deadline, collected: &collected)
+            }
+        }
+
+        if !gotChildren {
+            childrenRef = nil
+            let childErr = AXUIElementCopyAttributeValue(element, kAXChildrenAttribute as CFString, &childrenRef)
+            if childErr == .success, let children = childrenRef as? [AXUIElement] {
+                let capped = children.prefix(Self.maxChildrenPerNode)
+                for child in capped {
+                    guard Date() < deadline else { return }
+                    walkChildren(element: child, depth: depth + 1, deadline: deadline, collected: &collected)
+                }
+            }
+        }
+    }
+
+    private func extractText(from element: AXUIElement, into collected: inout [String]) {
+        // kAXValueAttribute — text field contents, labels, etc.
+        var valueRef: CFTypeRef?
+        if AXUIElementCopyAttributeValue(element, kAXValueAttribute as CFString, &valueRef) == .success,
+           let str = valueRef as? String, !str.isEmpty, str.count > 1 {
+            collected.append(str)
+        }
+
+        // kAXTitleAttribute — window/button titles
+        var titleRef: CFTypeRef?
+        if AXUIElementCopyAttributeValue(element, kAXTitleAttribute as CFString, &titleRef) == .success,
+           let str = titleRef as? String, !str.isEmpty, str.count > 1 {
+            collected.append(str)
+        }
+
+        // kAXDescriptionAttribute — accessible descriptions
+        var descRef: CFTypeRef?
+        if AXUIElementCopyAttributeValue(element, kAXDescriptionAttribute as CFString, &descRef) == .success,
+           let str = descRef as? String, !str.isEmpty, str.count > 1 {
+            collected.append(str)
+        }
+    }
+}

package/app/Sources/ActionRow.swift

@@ -0,0 +1,61 @@
+import SwiftUI
+
+/// A single action row with shortcut badge, label, optional icon, and hotkey hint.
+struct ActionRow: View {
+    let shortcut: String
+    let label: String
+    var hotkey: String? = nil
+    var icon: String? = nil
+    var accentColor: Color = Palette.textDim
+    var action: () -> Void
+
+    @State private var isHovered = false
+
+    var body: some View {
+        Button(action: action) {
+            HStack(spacing: 10) {
+                // Shortcut badge
+                Text(shortcut)
+                    .font(Typo.monoBold(10))
+                    .foregroundColor(accentColor)
+                    .frame(width: 18, height: 18)
+                    .background(
+                        RoundedRectangle(cornerRadius: 4)
+                            .fill(accentColor.opacity(0.12))
+                    )
+
+                // Icon
+                if let icon {
+                    Image(systemName: icon)
+                        .font(.system(size: 11, weight: .medium))
+                        .foregroundColor(isHovered ? Palette.text : Palette.textDim)
+                        .frame(width: 14)
+                }
+
+                // Label
+                Text(label)
+                    .font(Typo.mono(12))
+                    .foregroundColor(isHovered ? Palette.text : Palette.textDim)
+                    .lineLimit(1)
+
+                Spacer()
+
+                // Hotkey
+                if let hotkey {
+                    Text(hotkey)
+                        .font(Typo.mono(10))
+                        .foregroundColor(Palette.textMuted)
+                }
+            }
+            .padding(.horizontal, 10)
+            .padding(.vertical, 6)
+            .background(
+                RoundedRectangle(cornerRadius: 5)
+                    .fill(isHovered ? Palette.surfaceHov : Color.clear)
+            )
+            .contentShape(Rectangle())
+        }
+        .buttonStyle(.plain)
+        .onHover { isHovered = $0 }
+    }
+}

package/app/Sources/App.swift

@@ -0,0 +1,10 @@
+import SwiftUI
+
+@main
+struct LatticesApp: App {
+    @NSApplicationDelegateAdaptor(AppDelegate.self) var delegate
+
+    var body: some Scene {
+        Settings { EmptyView() }
+    }
+}

package/app/Sources/AppDelegate.swift

@@ -0,0 +1,242 @@
+import AppKit
+import SwiftUI
+
+/// 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 var statusItem: NSStatusItem!
+    private var popover: NSPopover?
+    private var contextMenu: NSMenu!
+
+    /// 3×3 grid icon for the menu bar — L-shape bright, rest dim (template for auto light/dark)
+    private static let menuBarIcon: NSImage = {
+        let size: CGFloat = 18
+        let img = NSImage(size: NSSize(width: size, height: size), flipped: true) { _ in
+            let pad: CGFloat = 2
+            let gap: CGFloat = 1.5
+            let cellSize = (size - 2 * pad - 2 * gap) / 3
+
+            let solidCells: Set<Int> = [0, 3, 6, 7, 8]
+
+            for row in 0..<3 {
+                for col in 0..<3 {
+                    let idx = row * 3 + col
+                    let x = pad + CGFloat(col) * (cellSize + gap)
+                    let y = pad + CGFloat(row) * (cellSize + gap)
+                    let rect = NSRect(x: x, y: y, width: cellSize, height: cellSize)
+
+                    if solidCells.contains(idx) {
+                        NSColor.black.setFill()
+                    } else {
+                        NSColor.black.withAlphaComponent(0.25).setFill()
+                    }
+                    let path = NSBezierPath(roundedRect: rect, xRadius: 0.8, yRadius: 0.8)
+                    path.fill()
+                }
+            }
+            return true
+        }
+        img.isTemplate = true
+        return img
+    }()
+
+    /// Toggle between .accessory (hidden from Dock/Cmd+Tab) and .regular (visible)
+    /// based on whether any managed windows are open.
+    static func updateActivationPolicy() {
+        let hasVisibleWindow =
+            CommandModeWindow.shared.isVisible ||
+            CommandPaletteWindow.shared.isVisible ||
+            MainWindow.shared.isVisible ||
+            ScreenMapWindowController.shared.isVisible ||
+            OmniSearchWindow.shared.isVisible
+        let desired: NSApplication.ActivationPolicy = hasVisibleWindow ? .regular : .accessory
+        if NSApp.activationPolicy() != desired {
+            NSApp.setActivationPolicy(desired)
+            if desired == .regular {
+                NSApp.activate(ignoringOtherApps: true)
+            }
+        }
+    }
+
+    func applicationDidFinishLaunching(_ notification: Notification) {
+        NSApp.setActivationPolicy(.accessory)
+        NSApp.appearance = NSAppearance(named: .darkAqua)
+
+        // --- Status item ---
+        statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.squareLength)
+        if let button = statusItem.button {
+            button.image = Self.menuBarIcon
+            button.action = #selector(statusItemClicked(_:))
+            button.sendAction(on: [.leftMouseUp, .rightMouseUp])
+            button.target = self
+        }
+
+        // --- Context menu (right-click) ---
+        contextMenu = buildContextMenu()
+
+        // --- Hotkey registration ---
+        let scanner = ProjectScanner.shared
+        CommandPaletteWindow.shared.configure(scanner: scanner)
+
+        let store = HotkeyStore.shared
+        store.register(action: .palette) { CommandPaletteWindow.shared.toggle() }
+        store.register(action: .screenMap) { ScreenMapWindowController.shared.toggle() }
+        store.register(action: .bezel) { WindowBezel.showBezelForFrontmostWindow() }
+        store.register(action: .cheatSheet) { CheatSheetHUD.shared.toggle() }
+        store.register(action: .desktopInventory) { CommandModeWindow.shared.toggle() }
+        store.register(action: .omniSearch) { OmniSearchWindow.shared.toggle() }
+
+        // Layer-switching hotkeys
+        let workspace = WorkspaceManager.shared
+        let layerCount = (workspace.config?.layers ?? []).count
+        for (i, action) in HotkeyAction.layerActions.prefix(layerCount).enumerated() {
+            let index = i
+            store.register(action: action) {
+                workspace.tileLayer(index: index, launch: true, force: true)
+                EventBus.shared.post(.layerSwitched(index: index))
+            }
+        }
+
+        // Tiling hotkeys
+        let tileMap: [(HotkeyAction, TilePosition)] = [
+            (.tileLeft, .left), (.tileRight, .right),
+            (.tileMaximize, .maximize), (.tileCenter, .center),
+            (.tileTopLeft, .topLeft), (.tileTopRight, .topRight),
+            (.tileBottomLeft, .bottomLeft), (.tileBottomRight, .bottomRight),
+            (.tileTop, .top), (.tileBottom, .bottom),
+            (.tileLeftThird, .leftThird), (.tileCenterThird, .centerThird),
+            (.tileRightThird, .rightThird),
+        ]
+        for (action, position) in tileMap {
+            store.register(action: action) { WindowTiler.tileFrontmostViaAX(to: position) }
+        }
+        store.register(action: .tileDistribute) { WindowTiler.distributeVisible() }
+
+        // Check macOS permissions (Accessibility, Screen Recording)
+        PermissionChecker.shared.check()
+
+        // Start daemon services
+        let diag = DiagnosticLog.shared
+        let tBoot = diag.startTimed("Daemon services boot")
+        OcrStore.shared.open()
+        DesktopModel.shared.start()
+        OcrModel.shared.start()
+        TmuxModel.shared.start()
+        ProcessModel.shared.start()
+        LatticesApi.setup()
+        DaemonServer.shared.start()
+        diag.finish(tBoot)
+
+        // --diagnostics flag: auto-open diagnostics panel on launch
+        if CommandLine.arguments.contains("--diagnostics") {
+            DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {
+                DiagnosticWindow.shared.show()
+            }
+        }
+
+        // --screen-map flag: auto-open screen map on launch
+        if CommandLine.arguments.contains("--screen-map") {
+            DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {
+                ScreenMapWindowController.shared.show()
+            }
+        }
+    }
+
+    // MARK: - Status item click handler
+
+    @objc private func statusItemClicked(_ sender: Any?) {
+        guard let event = NSApp.currentEvent, let button = statusItem.button else { return }
+
+        if event.type == .rightMouseUp {
+            // Right-click → context menu
+            contextMenu.popUp(positioning: nil, at: NSPoint(x: 0, y: button.bounds.height + 4), in: button)
+        } else {
+            // Left-click → toggle 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()
+            }
+        }
+    }
+
+    /// Dismiss the popover programmatically (e.g. from the pop-out button).
+    func dismissPopover() {
+        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.
+    private func makePopover() -> NSPopover {
+        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: 520)
+        p.appearance = NSAppearance(named: .darkAqua)
+        p.delegate = self
+        popover = p
+        DiagnosticLog.shared.finish(t)
+        return p
+    }
+
+    func popoverDidClose(_ notification: Notification) {
+        // Tear down the SwiftUI view tree so observed models stop driving re-renders
+        popover?.contentViewController = nil
+        popover = nil
+    }
+
+    // MARK: - Context menu
+
+    private func buildContextMenu() -> NSMenu {
+        let menu = NSMenu()
+
+        let actions: [(String, String, Selector)] = [
+            ("Command Palette", "⌘⇧M", #selector(menuCommandPalette)),
+            ("Screen Map", "", #selector(menuScreenMap)),
+            ("Desktop Inventory", "", #selector(menuDesktopInventory)),
+            ("Window Bezel", "", #selector(menuWindowBezel)),
+            ("Cheat Sheet", "", #selector(menuCheatSheet)),
+            ("Omni Search", "", #selector(menuOmniSearch)),
+        ]
+        for (title, shortcut, action) in actions {
+            let item = NSMenuItem(title: title, action: action, keyEquivalent: "")
+            item.target = self
+            if !shortcut.isEmpty {
+                // Display-only; the actual hotkey is global
+            }
+            menu.addItem(item)
+        }
+
+        menu.addItem(.separator())
+
+        let settings = NSMenuItem(title: "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")
+        quit.target = self
+        menu.addItem(quit)
+
+        return menu
+    }
+
+    @objc private func menuCommandPalette() { CommandPaletteWindow.shared.toggle() }
+    @objc private func menuScreenMap() { ScreenMapWindowController.shared.toggle() }
+    @objc private func menuDesktopInventory() { CommandModeWindow.shared.toggle() }
+    @objc private func menuWindowBezel() { WindowBezel.showBezelForFrontmostWindow() }
+    @objc private func menuCheatSheet() { CheatSheetHUD.shared.toggle() }
+    @objc private func menuOmniSearch() { OmniSearchWindow.shared.toggle() }
+    @objc private func menuSettings() { SettingsWindowController.shared.show() }
+    @objc private func menuDiagnostics() { DiagnosticWindow.shared.toggle() }
+    @objc private func menuQuit() { NSApp.terminate(nil) }
+}

package/app/Sources/AppShellView.swift

@@ -0,0 +1,62 @@
+import SwiftUI
+
+// MARK: - Navigation Pages
+
+enum AppPage: String, CaseIterable {
+    case screenMap
+    case settings
+    case docs
+
+    var label: String {
+        switch self {
+        case .screenMap: return "Screen Map"
+        case .settings:  return "Settings"
+        case .docs:      return "Docs"
+        }
+    }
+
+    var icon: String {
+        switch self {
+        case .screenMap: return "rectangle.3.group"
+        case .settings:  return "gearshape"
+        case .docs:      return "book"
+        }
+    }
+}
+
+// MARK: - App Shell View
+
+struct AppShellView: View {
+    @ObservedObject var controller: ScreenMapController
+    @ObservedObject var windowController = ScreenMapWindowController.shared
+
+    var body: some View {
+        contentArea
+            .background(Palette.bg)
+    }
+
+    // MARK: - Content Area
+
+    @ViewBuilder
+    private var contentArea: some View {
+        switch windowController.activePage {
+        case .screenMap:
+            ScreenMapView(controller: controller, onNavigate: { page in
+                windowController.activePage = page
+            })
+        case .settings:
+            SettingsContentView(
+                prefs: Preferences.shared,
+                scanner: ProjectScanner.shared,
+                onBack: { windowController.activePage = .screenMap; controller.enter() }
+            )
+        case .docs:
+            SettingsContentView(
+                page: .docs,
+                prefs: Preferences.shared,
+                scanner: ProjectScanner.shared,
+                onBack: { windowController.activePage = .screenMap; controller.enter() }
+            )
+        }
+    }
+}