claude-dock 1.0.2 → 1.2.0

package/bin/cli.js

@@ -159,6 +159,11 @@ async function main() {
   log(`  ${colors.dim}⌘⌥T${colors.reset}  Toggle dock`);
   log(`  ${colors.dim}⌘⌥N${colors.reset}  Add new terminal`);
   log(`  ${colors.dim}⌘⌥R${colors.reset}  Reload config`);
+  log(`  ${colors.dim}⌘⌥L${colors.reset}  Move macOS Dock to left`);
+  log(`  ${colors.dim}⌘⌥B${colors.reset}  Move macOS Dock to bottom`);
+  log('');
+  log(`${colors.yellow}Tip:${colors.reset} If your macOS Dock is at the bottom, you'll be prompted to move it.`);
+  log(`  You can change this anytime with ${colors.dim}⌘⌥L${colors.reset} (left) or ${colors.dim}⌘⌥B${colors.reset} (bottom).`);
   log('');
 }
 

package/init.lua

@@ -13,8 +13,8 @@ local config = {
     addButtonWidth = 40,
     utilityButtonWidth = 28,
     initialSlots = 3,
-    elementsPerSlot = 4,  -- bg, border, title, status
-    baseElements = 4,     -- dock bg + border + minimize btn + minimize text
+    elementsPerSlot = 5,  -- bg, border, title, status, notification badge
+    baseElements = 6,     -- dock bg + border + help btn + help text + minimize btn + minimize text
     windowCaptureDelay = 0.3,
     windowCaptureRetries = 5,
     colors = {
@@ -30,7 +30,11 @@ local config = {
         addBtnText = { red = 0.6, green = 0.8, blue = 0.6, alpha = 1 },
         minBtnBg = { red = 0.18, green = 0.18, blue = 0.25, alpha = 1 },
         minBtnText = { red = 0.6, green = 0.6, blue = 0.9, alpha = 1 },
-    }
+        helpBtnBg = { red = 0.2, green = 0.18, blue = 0.12, alpha = 1 },
+        helpBtnText = { red = 0.9, green = 0.8, blue = 0.5, alpha = 1 },
+        notificationBadge = { red = 1, green = 0.3, blue = 0.3, alpha = 1 },
+    },
+    notificationBadgeSize = 12,
 }
 
 -- State
@@ -38,6 +42,28 @@ local slotCount = config.initialSlots
 local slots = {}
 local dock = nil
 local tooltip = nil
+local helpPanel = nil
+local macOSDockAtBottom = false
+
+-- Check macOS dock position
+local function getMacOSDockPosition()
+    local output, status = hs.execute("defaults read com.apple.dock orientation 2>/dev/null")
+    if status and output then
+        output = output:gsub("%s+", "")
+        if output == "left" or output == "right" then
+            return output
+        end
+    end
+    return "bottom"  -- default
+end
+
+-- Get macOS dock size (tile size + magnification consideration)
+local function getMacOSDockHeight()
+    local tileSize = hs.execute("defaults read com.apple.dock tilesize 2>/dev/null")
+    tileSize = tonumber(tileSize) or 48
+    -- Add padding for dock chrome and gaps
+    return tileSize + 20
+end
 
 -- Resource handles (for cleanup on reload)
 local windowFilter = nil
@@ -66,13 +92,17 @@ local function cleanup()
         tooltip:delete()
         tooltip = nil
     end
+    if helpPanel then
+        helpPanel:delete()
+        helpPanel = nil
+    end
 end
 cleanup()  -- Clean up any previous instance
 
 local function initSlots()
     for i = 1, slotCount do
         if not slots[i] then
-            slots[i] = { windowId = nil, customName = nil, pending = false }
+            slots[i] = { windowId = nil, customName = nil, pending = false, hasNotification = false }
         end
     end
 end
@@ -96,9 +126,14 @@ local function getDockFrame()
     local frame = screen:fullFrame()
     local dockWidth = getDockWidth()
     local dockHeight = getDockHeight()
+    local bottomOffset = config.bottomOffset
+    -- Add extra offset if macOS dock is at bottom
+    if macOSDockAtBottom then
+        bottomOffset = bottomOffset + getMacOSDockHeight()
+    end
     return {
         x = (frame.w - dockWidth) / 2,
-        y = frame.h - dockHeight - config.bottomOffset,
+        y = frame.h - dockHeight - bottomOffset,
         w = dockWidth,
         h = dockHeight
     }
@@ -119,6 +154,33 @@ local function getWindowTitle(win)
     return title
 end
 
+-- Find slot index by window ID
+local function findSlotByWindowId(windowId)
+    if not windowId then return nil end
+    for i, slot in ipairs(slots) do
+        if slot.windowId == windowId then
+            return i
+        end
+    end
+    return nil
+end
+
+-- Set notification for a slot (only if window is not focused)
+local function setSlotNotification(slotIndex)
+    local slot = slots[slotIndex]
+    if not slot then return end
+
+    local win = getWindow(slot.windowId)
+    if win then
+        local focusedWin = hs.window.focusedWindow()
+        -- Only show notification if window is not currently focused
+        if not focusedWin or focusedWin:id() ~= slot.windowId then
+            slot.hasNotification = true
+            updateSlotDisplay(slotIndex)
+        end
+    end
+end
+
 -- Tooltip helpers
 local function showTooltipAt(text, x, y)
     if tooltip then tooltip:delete() end
@@ -155,11 +217,11 @@ local function showButtonTooltip(text, buttonId)
     local tipHeight = 24
     local btnX, btnWidth
 
-    if buttonId == "minBtn" then
-        -- Left side utility button
+    if buttonId == "minBtn" or buttonId == "helpBtn" then
+        -- Left side utility buttons
         btnX = dockFrame.x + config.margin
         btnWidth = config.utilityButtonWidth
-    else
+    elseif buttonId == "addBtn" then
         -- Right side add button
         btnX = dockFrame.x + config.margin + config.utilityButtonWidth + config.gap + (slotCount * config.slotWidth) + (slotCount * config.gap)
         btnWidth = config.addButtonWidth
@@ -178,6 +240,128 @@ local function hideTooltip()
     end
 end
 
+-- Help panel
+local function hideHelpPanel()
+    if helpPanel then
+        helpPanel:delete()
+        helpPanel = nil
+    end
+end
+
+local function showHelpPanel()
+    if helpPanel then
+        hideHelpPanel()
+        return
+    end
+
+    local screen = hs.screen.mainScreen()
+    if not screen then return end
+    local screenFrame = screen:fullFrame()
+
+    local panelWidth = 280
+    local panelHeight = 260
+    local panelX = (screenFrame.w - panelWidth) / 2
+    local panelY = (screenFrame.h - panelHeight) / 2
+
+    helpPanel = hs.canvas.new({ x = panelX, y = panelY, w = panelWidth, h = panelHeight })
+
+    -- Background
+    helpPanel:appendElements({
+        type = "rectangle",
+        action = "fill",
+        roundedRectRadii = { xRadius = 12, yRadius = 12 },
+        fillColor = { red = 0.1, green = 0.1, blue = 0.1, alpha = 0.95 },
+        frame = { x = 0, y = 0, w = "100%", h = "100%" },
+    })
+
+    -- Border
+    helpPanel:appendElements({
+        type = "rectangle",
+        action = "stroke",
+        roundedRectRadii = { xRadius = 12, yRadius = 12 },
+        strokeColor = { red = 1, green = 1, blue = 1, alpha = 0.2 },
+        strokeWidth = 1,
+        frame = { x = 0, y = 0, w = "100%", h = "100%" },
+    })
+
+    -- Title
+    helpPanel:appendElements({
+        type = "text",
+        frame = { x = 0, y = 15, w = panelWidth, h = 24 },
+        text = "Claude Dock Shortcuts",
+        textAlignment = "center",
+        textColor = { red = 1, green = 1, blue = 1, alpha = 1 },
+        textSize = 16,
+        textFont = ".AppleSystemUIFontBold",
+    })
+
+    -- Shortcuts list
+    local shortcuts = {
+        { key = "⌘⌥T", desc = "Toggle dock" },
+        { key = "⌘⌥N", desc = "Add new terminal" },
+        { key = "⌘⌥M", desc = "Minimize all terminals" },
+        { key = "⌘⌥R", desc = "Reload config" },
+        { key = "⌘⌥L", desc = "Move macOS Dock left" },
+        { key = "⌘⌥B", desc = "Move macOS Dock bottom" },
+        { key = "⌥+Click", desc = "Rename slot" },
+    }
+
+    local startY = 50
+    for i, shortcut in ipairs(shortcuts) do
+        local y = startY + ((i - 1) * 24)
+        helpPanel:appendElements({
+            type = "text",
+            frame = { x = 20, y = y, w = 70, h = 20 },
+            text = shortcut.key,
+            textAlignment = "left",
+            textColor = { red = 0.6, green = 0.8, blue = 1, alpha = 1 },
+            textSize = 13,
+            textFont = ".AppleSystemUIFont",
+        })
+        helpPanel:appendElements({
+            type = "text",
+            frame = { x = 95, y = y, w = 170, h = 20 },
+            text = shortcut.desc,
+            textAlignment = "left",
+            textColor = { red = 0.8, green = 0.8, blue = 0.8, alpha = 1 },
+            textSize = 13,
+            textFont = ".AppleSystemUIFont",
+        })
+    end
+
+    -- Close button
+    local closeBtnY = panelHeight - 45
+    helpPanel:appendElements({
+        type = "rectangle",
+        action = "fill",
+        frame = { x = (panelWidth - 80) / 2, y = closeBtnY, w = 80, h = 30 },
+        roundedRectRadii = { xRadius = 6, yRadius = 6 },
+        fillColor = { red = 0.25, green = 0.25, blue = 0.25, alpha = 1 },
+        trackMouseUp = true,
+        id = "closeBtn",
+    })
+    helpPanel:appendElements({
+        type = "text",
+        frame = { x = (panelWidth - 80) / 2, y = closeBtnY + 6, w = 80, h = 20 },
+        text = "Close",
+        textAlignment = "center",
+        textColor = { red = 0.9, green = 0.9, blue = 0.9, alpha = 1 },
+        textSize = 13,
+        textFont = ".AppleSystemUIFont",
+        trackMouseUp = true,
+        id = "closeBtn",
+    })
+
+    helpPanel:mouseCallback(function(_, event, id)
+        if event == "mouseUp" and id == "closeBtn" then
+            hideHelpPanel()
+        end
+    end)
+
+    helpPanel:level(hs.canvas.windowLevels.modalPanel)
+    helpPanel:show()
+end
+
 -- Forward declarations
 local createDock
 local updateAllSlots
@@ -203,16 +387,19 @@ local function updateSlotDisplay(slotIndex)
             status = "active"
             bgColor = config.colors.slotActive
         end
+    elseif slot.windowId then
+        -- Window exists but not visible (probably on another space)
+        title = slot.customName or "Terminal"
+        status = "(other space)"
+        bgColor = config.colors.slotMinimized
     else
-        -- Don't clear customName if we're waiting for a window to spawn
-        if not slot.pending then
-            slot.windowId = nil
-            slot.customName = nil
-            title = "Empty"
-            status = "click to open"
-        else
+        -- No window assigned
+        if slot.pending then
             title = slot.customName or "Opening..."
             status = "launching"
+        else
+            title = "Empty"
+            status = "click to open"
         end
         bgColor = config.colors.slotEmpty
     end
@@ -226,6 +413,12 @@ local function updateSlotDisplay(slotIndex)
     if dock[baseIdx + 3] then
         dock[baseIdx + 3].text = status
     end
+    -- Update notification badge visibility
+    if dock[baseIdx + 4] then
+        dock[baseIdx + 4].fillColor = slot.hasNotification
+            and config.colors.notificationBadge
+            or { red = 0, green = 0, blue = 0, alpha = 0 }
+    end
 end
 
 updateAllSlots = function()
@@ -299,6 +492,9 @@ local function onSlotClick(slotIndex, isOptionClick)
         return
     end
 
+    -- Clear notification when clicked
+    slot.hasNotification = false
+
     local win = getWindow(slot.windowId)
     if win then
         if win:isMinimized() then
@@ -336,7 +532,7 @@ end
 -- Add a new slot and launch terminal
 local function addSlot()
     slotCount = slotCount + 1
-    slots[slotCount] = { windowId = nil, customName = nil, pending = false }
+    slots[slotCount] = { windowId = nil, customName = nil, pending = false, hasNotification = false }
 
     if dock then
         dock:delete()
@@ -374,14 +570,41 @@ createDock = function()
         frame = { x = 0, y = 0, w = "100%", h = "100%" },
     })
 
-    -- Minimize button (left side, small utility style)
-    local minBtnX = config.margin
-    local minBtnHeight = 28
-    local minBtnY = config.margin + (config.slotHeight - minBtnHeight) / 2
+    -- Utility buttons (left side, stacked: help on top, minimize on bottom)
+    local utilBtnX = config.margin
+    local btnGap = 4
+    local btnHeight = (config.slotHeight - btnGap) / 2
+
+    -- Help button (top)
+    local helpBtnY = config.margin
     dock:appendElements({
         type = "rectangle",
         action = "fill",
-        frame = { x = minBtnX, y = minBtnY, w = config.utilityButtonWidth, h = minBtnHeight },
+        frame = { x = utilBtnX, y = helpBtnY, w = config.utilityButtonWidth, h = btnHeight },
+        roundedRectRadii = { xRadius = 6, yRadius = 6 },
+        fillColor = config.colors.helpBtnBg,
+        trackMouseUp = true,
+        trackMouseEnterExit = true,
+        id = "helpBtn",
+    })
+    dock:appendElements({
+        type = "text",
+        frame = { x = utilBtnX, y = helpBtnY + 4, w = config.utilityButtonWidth, h = btnHeight },
+        text = "?",
+        textAlignment = "center",
+        textColor = config.colors.helpBtnText,
+        textSize = 16,
+        textFont = ".AppleSystemUIFontBold",
+        trackMouseUp = true,
+        id = "helpBtn",
+    })
+
+    -- Minimize button (bottom)
+    local minBtnY = config.margin + btnHeight + btnGap
+    dock:appendElements({
+        type = "rectangle",
+        action = "fill",
+        frame = { x = utilBtnX, y = minBtnY, w = config.utilityButtonWidth, h = btnHeight },
         roundedRectRadii = { xRadius = 6, yRadius = 6 },
         fillColor = config.colors.minBtnBg,
         trackMouseUp = true,
@@ -390,11 +613,11 @@ createDock = function()
     })
     dock:appendElements({
         type = "text",
-        frame = { x = minBtnX, y = minBtnY + 2, w = config.utilityButtonWidth, h = minBtnHeight },
+        frame = { x = utilBtnX, y = minBtnY + 4, w = config.utilityButtonWidth, h = btnHeight },
         text = "⌄",
         textAlignment = "center",
         textColor = config.colors.minBtnText,
-        textSize = 18,
+        textSize = 16,
         textFont = ".AppleSystemUIFont",
         trackMouseUp = true,
         id = "minBtn",
@@ -443,6 +666,16 @@ createDock = function()
             textSize = 10,
             textFont = ".AppleSystemUIFont",
         })
+
+        -- Notification badge (top-right corner of slot, overlapping edge like app badges)
+        local badgeSize = config.notificationBadgeSize
+        dock:appendElements({
+            type = "circle",
+            action = "fill",
+            center = { x = slotX + config.slotWidth - badgeSize/3, y = config.margin + badgeSize/3 },
+            radius = badgeSize / 2,
+            fillColor = { red = 0, green = 0, blue = 0, alpha = 0 },  -- Hidden by default
+        })
     end
 
     -- Add button (right side)
@@ -475,6 +708,8 @@ createDock = function()
                 addSlot()
             elseif id == "minBtn" then
                 minimizeAllTerminals()
+            elseif id == "helpBtn" then
+                showHelpPanel()
             elseif id and id:match("^slot") then
                 local idx = tonumber(id:match("%d+"))
                 if idx then
@@ -487,8 +722,10 @@ createDock = function()
                 showButtonTooltip("⌘⌥N", "addBtn")
             elseif id == "minBtn" then
                 showButtonTooltip("⌘⌥M", "minBtn")
+            elseif id == "helpBtn" then
+                showButtonTooltip("Help", "helpBtn")
             end
-        elseif event == "mouseExit" and (id == "addBtn" or id == "minBtn") then
+        elseif event == "mouseExit" and (id == "addBtn" or id == "minBtn" or id == "helpBtn") then
             hideTooltip()
         end
     end)
@@ -524,12 +761,64 @@ end
 -- Window event watcher for immediate updates
 windowFilter = hs.window.filter.new("Terminal")
 windowFilter:subscribe({
-    hs.window.filter.windowDestroyed,
     hs.window.filter.windowMinimized,
     hs.window.filter.windowUnminimized,
-    hs.window.filter.windowFocused,
 }, updateAllSlots)
 
+-- Handle window destruction - clear the slot
+windowFilter:subscribe(hs.window.filter.windowDestroyed, function(win, appName, event)
+    -- win may be nil at this point, so we need to check all slots
+    for i, slot in ipairs(slots) do
+        if slot.windowId then
+            local existingWin = getWindow(slot.windowId)
+            if not existingWin then
+                -- Try to verify window is truly gone (not just on another space)
+                -- by checking all Terminal windows
+                local allTerminals = hs.window.filter.new("Terminal"):getWindows()
+                local found = false
+                for _, w in ipairs(allTerminals) do
+                    if w:id() == slot.windowId then
+                        found = true
+                        break
+                    end
+                end
+                if not found then
+                    slot.windowId = nil
+                    slot.customName = nil
+                    slot.hasNotification = false
+                end
+            end
+        end
+    end
+    updateAllSlots()
+end)
+
+-- Clear notification when window is focused
+windowFilter:subscribe(hs.window.filter.windowFocused, function(win)
+    if win then
+        local slotIndex = findSlotByWindowId(win:id())
+        if slotIndex then
+            slots[slotIndex].hasNotification = false
+        end
+    end
+    updateAllSlots()
+end)
+
+-- Watch for window title changes (indicates terminal activity)
+windowFilter:subscribe(hs.window.filter.windowTitleChanged, function(win)
+    if win then
+        local slotIndex = findSlotByWindowId(win:id())
+        if slotIndex then
+            local focusedWin = hs.window.focusedWindow()
+            -- Only show notification if this window isn't focused
+            if not focusedWin or focusedWin:id() ~= win:id() then
+                slots[slotIndex].hasNotification = true
+                updateSlotDisplay(slotIndex)
+            end
+        end
+    end
+end)
+
 -- Periodic refresh as fallback
 updateTimer = hs.timer.doEvery(2, function()
     if dock and dock:isShowing() then
@@ -548,7 +837,53 @@ screenWatcher = hs.screen.watcher.new(function()
 end)
 screenWatcher:start()
 
+-- Move macOS dock position
+local function moveMacOSDockLeft()
+    hs.execute("defaults write com.apple.dock orientation left && killall Dock")
+    macOSDockAtBottom = false
+    hs.alert.show("macOS Dock moved to left")
+    -- Reposition Claude Dock
+    if dock then
+        local frame = getDockFrame()
+        if frame then dock:frame(frame) end
+    end
+end
+
+local function moveMacOSDockBottom()
+    hs.execute("defaults write com.apple.dock orientation bottom && killall Dock")
+    macOSDockAtBottom = true
+    hs.alert.show("macOS Dock moved to bottom")
+    -- Reposition Claude Dock
+    if dock then
+        local frame = getDockFrame()
+        if frame then dock:frame(frame) end
+    end
+end
+
+-- Check macOS dock and prompt user if at bottom
+-- Returns true if user chose to keep dock at bottom
+local function checkMacOSDockOnStartup()
+    local position = getMacOSDockPosition()
+    if position == "bottom" then
+        local button = hs.dialog.blockAlert(
+            "macOS Dock Position",
+            "Your macOS Dock is at the bottom of the screen, which may overlap with Claude Dock.\n\nWould you like to move it to the left side?",
+            "Move to Left",
+            "Keep at Bottom"
+        )
+        if button == "Move to Left" then
+            moveMacOSDockLeft()
+            return false
+        else
+            macOSDockAtBottom = true
+            return true
+        end
+    end
+    return false
+end
+
 -- Initialize
+local showRepositionedMsg = checkMacOSDockOnStartup()
 createDock()
 
 -- Hotkeys
@@ -556,8 +891,35 @@ hs.hotkey.bind({"cmd", "alt"}, "T", toggleDock)
 hs.hotkey.bind({"cmd", "alt"}, "N", addSlot)
 hs.hotkey.bind({"cmd", "alt"}, "M", minimizeAllTerminals)
 hs.hotkey.bind({"cmd", "alt"}, "R", hs.reload)
+hs.hotkey.bind({"cmd", "alt"}, "L", moveMacOSDockLeft)
+hs.hotkey.bind({"cmd", "alt"}, "B", moveMacOSDockBottom)
 
 hs.alert.show("Claude Dock Ready")
+if showRepositionedMsg then
+    hs.timer.doAfter(1.5, function()
+        hs.alert.show("Positioned above macOS Dock")
+    end)
+end
+
+-- Global function to trigger notification on a slot (for testing or external use)
+-- Usage: triggerNotification(1) to trigger on slot 1
+function triggerNotification(slotIndex)
+    if slotIndex and slots[slotIndex] then
+        setSlotNotification(slotIndex)
+        return true
+    end
+    return false
+end
+
+-- Global function to clear notification on a slot
+function clearNotification(slotIndex)
+    if slotIndex and slots[slotIndex] then
+        slots[slotIndex].hasNotification = false
+        updateSlotDisplay(slotIndex)
+        return true
+    end
+    return false
+end
 
 -- ===================
 -- TESTS (run with: hs -c "runTests()")
@@ -704,6 +1066,75 @@ function runTests()
         assert(ok, "should not error with invalid windowIds")
     end)
 
+    test("moveMacOSDockLeft is a function", function()
+        assert(type(moveMacOSDockLeft) == "function", "moveMacOSDockLeft should be a function")
+    end)
+
+    test("moveMacOSDockBottom is a function", function()
+        assert(type(moveMacOSDockBottom) == "function", "moveMacOSDockBottom should be a function")
+    end)
+
+    test("getMacOSDockPosition returns valid position", function()
+        local pos = getMacOSDockPosition()
+        assert(pos == "left" or pos == "right" or pos == "bottom", "position should be left, right, or bottom")
+    end)
+
+    test("getMacOSDockHeight returns number", function()
+        local height = getMacOSDockHeight()
+        assert(type(height) == "number", "height should be a number")
+        assert(height > 0, "height should be positive")
+    end)
+
+    test("checkMacOSDockOnStartup is a function", function()
+        assert(type(checkMacOSDockOnStartup) == "function", "checkMacOSDockOnStartup should be a function")
+    end)
+
+    test("showHelpPanel is a function", function()
+        assert(type(showHelpPanel) == "function", "showHelpPanel should be a function")
+    end)
+
+    test("hideHelpPanel is a function", function()
+        assert(type(hideHelpPanel) == "function", "hideHelpPanel should be a function")
+    end)
+
+    -- Notification badge tests
+    test("config has notification badge color", function()
+        assert(config.colors.notificationBadge, "notificationBadge color should exist")
+        assert(config.notificationBadgeSize, "notificationBadgeSize should exist")
+    end)
+
+    test("slots have hasNotification field", function()
+        slots = {}
+        slotCount = 2
+        initSlots()
+        assert(slots[1].hasNotification == false, "slot should have hasNotification = false")
+        restore()
+    end)
+
+    test("findSlotByWindowId returns nil for unknown window", function()
+        assertEqual(findSlotByWindowId(999999999), nil)
+    end)
+
+    test("findSlotByWindowId returns nil for nil input", function()
+        assertEqual(findSlotByWindowId(nil), nil)
+    end)
+
+    test("triggerNotification is a function", function()
+        assert(type(triggerNotification) == "function", "triggerNotification should be a function")
+    end)
+
+    test("clearNotification is a function", function()
+        assert(type(clearNotification) == "function", "clearNotification should be a function")
+    end)
+
+    test("triggerNotification returns false for invalid slot", function()
+        assertEqual(triggerNotification(9999), false)
+    end)
+
+    test("clearNotification returns false for invalid slot", function()
+        assertEqual(clearNotification(9999), false)
+    end)
+
     print("\n=== Results: " .. passed .. " passed, " .. failed .. " failed ===\n")
     return failed == 0
 end

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-dock",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "A lightweight terminal dock for macOS to manage Claude Code sessions",
   "bin": {
     "claude-dock": "bin/cli.js"