feat: add kanban CLI and centralize shortcut display strings

rogeriochaves · rogeriochaves · commit 8a7420bbaa90 · 2026-04-03T15:08:15.000+02:00
- Install `kanban` CLI to ~/.local/bin on app launch
  - `kanban` opens the app, `kanban .` or `kanban &lt;path&gt;` opens a project
  - Uses file-based IPC to avoid URL scheme duplicate window issues
  - Creates project automatically if it doesn't exist
- Add `kanbancode://open?path=...` deep link for cold launch
- Add `displayString` computed property to AppShortcut enum
  - Derives display (e.g. "⌘N") from key + modifiers automatically
  - All CommandItem shortcuts now reference AppShortcut.displayString
- Add `newTask` and `openSettings` cases to AppShortcut
- Move CommandItem to its own file
- Show "⌘N" shortcut hint on New Task buttons
- Fix "No sessions yet" blinking caused by setLoading on every reconcile
diff --git a/Sources/KanbanCode/App.swift b/Sources/KanbanCode/App.swift
@@ -89,6 +89,9 @@ final class AppDelegate: NSObject, NSApplicationDelegate, NSWindowDelegate, UNUs
             NSApp.applicationIconImage = icon
         }
 
+        // Install `kanban` CLI to ~/.local/bin
+        Self.installCLI()
+
         // Set up notifications: delegate must be set BEFORE requesting authorization
         let center = UNUserNotificationCenter.current()
         center.delegate = self
@@ -101,6 +104,51 @@ final class AppDelegate: NSObject, NSApplicationDelegate, NSWindowDelegate, UNUs
         }
     }
 
+    /// Install a `kanban` shell script to ~/.local/bin so users can run
+    /// `kanban`, `kanban .`, or `kanban /path/to/project` from any terminal.
+    private static func installCLI() {
+        let binDir = FileManager.default.homeDirectoryForCurrentUser
+            .appendingPathComponent(".local/bin")
+        let scriptPath = binDir.appendingPathComponent("kanban")
+        // The CLI writes the path to a file, then activates the app.
+        // The app picks up the file in applicationDidBecomeActive.
+        // This avoids URL scheme issues that create duplicate windows.
+        let script = """
+        #!/bin/sh
+        # Installed by Kanban Code — opens the app and selects a project.
+        # Usage: kanban [path]   (defaults to current directory)
+        if [ -n "$1" ]; then
+            resolved="$(cd "$1" 2>/dev/null && pwd -P || echo "$1")"
+            mkdir -p ~/.kanban-code
+            echo "$resolved" > ~/.kanban-code/open-project
+        fi
+        open -a "KanbanCode"
+        """
+        do {
+            try FileManager.default.createDirectory(at: binDir, withIntermediateDirectories: true)
+            try script.write(to: scriptPath, atomically: true, encoding: .utf8)
+            try FileManager.default.setAttributes(
+                [.posixPermissions: 0o755], ofItemAtPath: scriptPath.path
+            )
+        } catch {
+            print("[Kanban Code] Failed to install CLI: \(error)")
+        }
+    }
+
+    /// Check for a pending project open request from the CLI.
+    func applicationDidBecomeActive(_ notification: Notification) {
+        let file = FileManager.default.homeDirectoryForCurrentUser
+            .appendingPathComponent(".kanban-code/open-project")
+        guard let path = try? String(contentsOf: file, encoding: .utf8)
+            .trimmingCharacters(in: .whitespacesAndNewlines),
+              !path.isEmpty else { return }
+        try? FileManager.default.removeItem(at: file)
+        NotificationCenter.default.post(
+            name: .kanbanCodeOpenProject, object: nil,
+            userInfo: ["path": path]
+        )
+    }
+
     /// Prevent Cmd+W from closing the single window — close terminal tab instead.
     func windowShouldClose(_ sender: NSWindow) -> Bool {
         NotificationCenter.default.post(name: .kanbanCloseTerminalTab, object: nil)
@@ -150,7 +198,7 @@ final class AppDelegate: NSObject, NSApplicationDelegate, NSWindowDelegate, UNUs
         process.waitUntilExit()
     }
 
-    // Handle kanbancode:// deep links (from Pushover tap, browser, etc.)
+    // Handle kanbancode:// deep links (from Pushover tap, browser, CLI, etc.)
     func application(_ application: NSApplication, open urls: [URL]) {
         for url in urls {
             guard url.scheme == "kanbancode" else { continue }
@@ -162,6 +210,16 @@ final class AppDelegate: NSObject, NSApplicationDelegate, NSWindowDelegate, UNUs
                     userInfo: ["cardId": cardId]
                 )
             }
+            // kanbancode://open?path=/some/project
+            if url.host == "open",
+               let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
+               let path = components.queryItems?.first(where: { $0.name == "path" })?.value,
+               !path.isEmpty {
+                NotificationCenter.default.post(
+                    name: .kanbanCodeOpenProject, object: nil,
+                    userInfo: ["path": path]
+                )
+            }
         }
         NSApp.activate(ignoringOtherApps: true)
         if let window = NSApp.windows.first(where: { $0.canBecomeMain }) {
@@ -236,4 +294,5 @@ extension Notification.Name {
     static let kanbanCloseTerminalTab = Notification.Name("kanbanCloseTerminalTab")
     static let chatCardExpanded = Notification.Name("chatCardExpanded")
     static let kanbanCodeAddLink = Notification.Name("kanbanCodeAddLink")
+    static let kanbanCodeOpenProject = Notification.Name("kanbanCodeOpenProject")
 }
diff --git a/Sources/KanbanCode/BoardView.swift b/Sources/KanbanCode/BoardView.swift
@@ -145,7 +145,7 @@ struct BoardView: View {
                         .foregroundStyle(.tertiary)
 
                     Button(action: onNewTask) {
-                        Label("New Task", systemImage: "plus")
+                        Label("New Task  \(AppShortcut.newTask.displayString)", systemImage: "plus")
                     }
                     .buttonStyle(.borderedProminent)
                     .controlSize(.small)
diff --git a/Sources/KanbanCode/CommandItem.swift b/Sources/KanbanCode/CommandItem.swift
@@ -0,0 +1,17 @@
+import SwiftUI
+
+struct CommandItem: Identifiable {
+    let id: String
+    let title: String
+    let icon: String
+    let shortcut: String?
+    let action: () -> Void
+
+    init(_ title: String, icon: String, shortcut: String? = nil, action: @escaping () -> Void) {
+        self.id = "cmd:\(title)"
+        self.title = title
+        self.icon = icon
+        self.shortcut = shortcut
+        self.action = action
+    }
+}
diff --git a/Sources/KanbanCode/ContentView.swift b/Sources/KanbanCode/ContentView.swift
@@ -1033,6 +1033,11 @@ struct ContentView: View {
                     store.dispatch(.selectCard(cardId: cardId))
                 }
             }
+            .onReceive(NotificationCenter.default.publisher(for: .kanbanCodeOpenProject)) { notification in
+                if let path = notification.userInfo?["path"] as? String {
+                    openOrCreateProject(path: path)
+                }
+            }
             .onReceive(NotificationCenter.default.publisher(for: .kanbanCodeAddLink)) { notification in
                 if let cardId = notification.userInfo?["cardId"] as? String {
                     showAddLinkCardId = cardId
@@ -1575,10 +1580,10 @@ struct ContentView: View {
 
     private var paletteCommands: [CommandItem] {
         var cmds: [CommandItem] = [
-            CommandItem("Open Settings", icon: "gear", shortcut: "⌘,") {
+            CommandItem("Open Settings", icon: "gear", shortcut: AppShortcut.openSettings.displayString) {
                 NSApp.sendAction(Selector(("showSettingsWindow:")), to: nil, from: nil)
             },
-            CommandItem("Toggle View Mode", icon: isExpandedDetail ? "square.split.2x1" : "list.bullet", shortcut: "⌘↩") { [self] in
+            CommandItem("Toggle View Mode", icon: isExpandedDetail ? "square.split.2x1" : "list.bullet", shortcut: AppShortcut.toggleExpanded.displayString) { [self] in
                 if isExpandedDetail {
                     isExpandedDetail = false
                     boardViewModeRaw = BoardViewMode.kanban.rawValue
@@ -1588,19 +1593,20 @@ struct ContentView: View {
                     boardViewModeRaw = BoardViewMode.list.rawValue
                 }
             },
-            CommandItem("New Task", icon: "plus", shortcut: "⌘N") { [self] in
+            CommandItem("New Task", icon: "plus", shortcut: AppShortcut.newTask.displayString) { [self] in
                 presentNewTask()
             },
         ]
 
         // Project switching
         let visibleProjects = store.state.configuredProjects.filter(\.visible)
         if !visibleProjects.isEmpty {
-            cmds.append(CommandItem("Show All Projects", icon: "folder", shortcut: "⌘1") { [self] in
+            cmds.append(CommandItem("Show All Projects", icon: "folder", shortcut: AppShortcut.project1.displayString) { [self] in
                 setSelectedProject(nil)
             })
             for (i, project) in visibleProjects.enumerated() {
-                let shortcut = i < 8 ? "⌘\(i + 2)" : nil
+                let projectShortcuts: [AppShortcut] = [.project2, .project3, .project4, .project5, .project6, .project7, .project8, .project9]
+                let shortcut = i < projectShortcuts.count ? projectShortcuts[i].displayString : nil
                 let path = project.path
                 cmds.append(CommandItem("Switch to \(project.name)", icon: "folder", shortcut: shortcut) { [self] in
                     setSelectedProject(path)
@@ -2033,6 +2039,24 @@ struct ContentView: View {
         }
     }
 
+    /// Open a project by path — select it if it exists, otherwise create and select it.
+    /// Called from the `kanban` CLI via file-based IPC.
+    private func openOrCreateProject(path: String) {
+        // Check if project already exists (match by path or repoRoot)
+        if store.state.configuredProjects.contains(where: { $0.path == path || $0.repoRoot == path }) {
+            setSelectedProject(path)
+            return
+        }
+        // Project doesn't exist — create it, select first to avoid empty flash
+        let project = Project(path: path)
+        setSelectedProject(path)
+        Task {
+            try? await settingsStore.addProject(project)
+            await store.loadSettingsAndCache()
+            await store.reconcile()
+        }
+    }
+
     // MARK: - Add from Path Sheet
 
     private var addFromPathSheet: some View {
diff --git a/Sources/KanbanCode/KeyboardShortcuts.swift b/Sources/KanbanCode/KeyboardShortcuts.swift
@@ -30,6 +30,10 @@ enum AppShortcut: CaseIterable {
     case openPaletteP           // Cmd+P
     case openCommandMode        // Cmd+Shift+P
 
+    // Global actions
+    case newTask                // Cmd+N
+    case openSettings           // Cmd+,
+
     // Detail panel
     case toggleExpanded         // Cmd+Enter (only when palette closed)
     case toggleSidebar          // Cmd+B (only in expanded mode, palette closed)
@@ -49,6 +53,7 @@ enum AppShortcut: CaseIterable {
 
     static var allCases: [AppShortcut] {
         [.openPaletteK, .openPaletteP, .openCommandMode,
+         .newTask, .openSettings,
          .toggleExpanded, .toggleSidebar, .newTerminal, .deepSearch,
          .deselect, .deleteCard, .deleteCardForward,
          .project1, .project2, .project3, .project4, .project5,
@@ -60,6 +65,8 @@ enum AppShortcut: CaseIterable {
         case .openPaletteK: return "k"
         case .openPaletteP: return "p"
         case .openCommandMode: return "p"
+        case .newTask: return "n"
+        case .openSettings: return ","
         case .toggleExpanded, .deepSearch: return .return
         case .toggleSidebar: return "b"
         case .newTerminal: return "t"
@@ -82,6 +89,7 @@ enum AppShortcut: CaseIterable {
         switch self {
         case .openPaletteK, .openPaletteP: return .command
         case .openCommandMode: return [.command, .shift]
+        case .newTask, .openSettings: return .command
         case .toggleExpanded, .deepSearch: return .command
         case .toggleSidebar: return .command
         case .newTerminal: return .command
@@ -91,11 +99,32 @@ enum AppShortcut: CaseIterable {
         }
     }
 
+    /// Human-readable shortcut string derived from key + modifiers (e.g. "⌘N").
+    var displayString: String {
+        var parts = ""
+        if modifiers.contains(.control) { parts += "⌃" }
+        if modifiers.contains(.option) { parts += "⌥" }
+        if modifiers.contains(.shift) { parts += "⇧" }
+        if modifiers.contains(.command) { parts += "⌘" }
+
+        let keyStr: String
+        switch key {
+        case .return: keyStr = "↩"
+        case .escape: keyStr = "⎋"
+        case .delete: keyStr = "⌫"
+        case .deleteForward: keyStr = "⌦"
+        case .space: keyStr = "␣"
+        default: keyStr = String(key.character).uppercased()
+        }
+        return parts + keyStr
+    }
+
     /// Whether this shortcut should be active given the current context.
     func isActive(in ctx: AppShortcutContext) -> Bool {
         switch self {
         // Palette open/close works everywhere
-        case .openPaletteK, .openPaletteP, .openCommandMode:
+        case .openPaletteK, .openPaletteP, .openCommandMode,
+             .newTask, .openSettings:
             return true
 
         // Toggle between kanban and expanded+sidebar mode
diff --git a/Sources/KanbanCode/ListBoardView.swift b/Sources/KanbanCode/ListBoardView.swift
@@ -169,7 +169,7 @@ struct ListBoardView: View {
                     .foregroundStyle(.tertiary)
 
                 Button(action: onNewTask) {
-                    Label("New Task", systemImage: "plus")
+                    Label("New Task  \(AppShortcut.newTask.displayString)", systemImage: "plus")
                 }
                 .buttonStyle(.borderedProminent)
                 .controlSize(.small)
diff --git a/Sources/KanbanCode/SearchOverlay.swift b/Sources/KanbanCode/SearchOverlay.swift
@@ -1,22 +1,6 @@
 import SwiftUI
 import KanbanCodeCore
 
-struct CommandItem: Identifiable {
-    let id: String
-    let title: String
-    let icon: String
-    let shortcut: String?
-    let action: () -> Void
-
-    init(_ title: String, icon: String, shortcut: String? = nil, action: @escaping () -> Void) {
-        self.id = "cmd:\(title)"
-        self.title = title
-        self.icon = icon
-        self.shortcut = shortcut
-        self.action = action
-    }
-}
-
 struct SearchOverlay: View {
     @Binding var isPresented: Bool
     let cards: [KanbanCodeCard]
diff --git a/Sources/KanbanCodeCore/UseCases/BoardStore.swift b/Sources/KanbanCodeCore/UseCases/BoardStore.swift
@@ -1462,7 +1462,8 @@ public final class BoardStore: @unchecked Sendable {
         isReconciling = true
         defer { isReconciling = false }
 
-        dispatch(.setLoading(true))
+        // Only show loading indicator on first reconcile, not periodic refreshes
+        if state.links.isEmpty { dispatch(.setLoading(true)) }
         let reconcileStart = ContinuousClock.now
 
         do {

Original file line number	Diff line number	Diff line change
`@@ -145,7 +145,7 @@ struct BoardView: View {`
`145`	`145`	`.foregroundStyle(.tertiary)`
`146`	`146`
`147`	`147`	`Button(action: onNewTask) {`
`148`		`- Label("New Task", systemImage: "plus")`
	`148`	`+ Label("New Task \(AppShortcut.newTask.displayString)", systemImage: "plus")`
`149`	`149`	`}`
`150`	`150`	`.buttonStyle(.borderedProminent)`
`151`	`151`	`.controlSize(.small)`
Original file line number	Diff line number	Diff line change
`@@ -169,7 +169,7 @@ struct ListBoardView: View {`
`169`	`169`	`.foregroundStyle(.tertiary)`
`170`	`170`
`171`	`171`	`Button(action: onNewTask) {`
`172`		`- Label("New Task", systemImage: "plus")`
	`172`	`+ Label("New Task \(AppShortcut.newTask.displayString)", systemImage: "plus")`
`173`	`173`	`}`
`174`	`174`	`.buttonStyle(.borderedProminent)`
`175`	`175`	`.controlSize(.small)`