Feature: Interactive Pomodoro Timer & Work Time Tracker (Focus Mode Integration)

[arkalon76]

📌 Feature Overview & Motivation

HalpTask features a dedicated Focus Mode (🎯 FOCUS) that highlights the active priority task and displays a top Focus Banner. The natural next step for deep-work power users is an Integrated Pomodoro Timer & Work Time Tracker.

This feature allows users to execute timed focus sprints (e.g. 25m work / 5m break) directly inside the terminal without switching to external timer tools, while automatically tracking time spent per task.

---

🎯 User Stories & Key Scenarios

1. Integrated Pomodoro Countdown:
   • When in Focus Mode (fo / tf), pressing <space> p s (or <space> t p) starts an interactive 25-minute Pomodoro timer.
   • The top Focus Banner dynamically updates with real-time countdown progress, sprint count, and session phase:

     ┌─ 🎯 ACTIVE FOCUS ────────────────────────────────────────────────────────┐
     │ Task: Refactor storage proto serialization (#dev)                        │
     │ Timer: 🍅 19:42 / 25:00 [Sprint 2/4] • Total Logged: 1h 15m            │
     └──────────────────────────────────────────────────────────────────────────┘
     

2. Work / Break State Machine:
   • Cycles through: Work (25m) ➜ Short Break (5m) ➜ Work (25m) ... ➜ Long Break (15m) after 4 sprints.
   • Customizable durations via config.yaml or Config Dashboard modal (<space> c c).
3. Session Completion Alerts:
   • Plays terminal bell (\a) and optionally triggers OS desktop notification when a sprint/break ends.
4. Task Time Tracking & Persistence:
   • Total active time spent is accumulated and saved in task metadata (TimeSpentSeconds).
   • Display total time logged badge (e.g. ⏱️ 45m) on the task.

---

🏗️ Architectural Touchpoints

1. Protobuf Schema & Data Model

• proto/v1/storage.proto:
  Add to ItemProto:

  int64 time_spent_seconds = 17; // Accumulated active focus time in seconds

• model/item.go:
  • Add TimeSpentSeconds int64 to Item.
  • Add methods:
    • (i *Item) AddTimeSpent(seconds int64)
    • (i *Item) FormattedTimeSpent() string (e.g. "1h 25m", "45m")
  • Update Item.Clone() to preserve TimeSpentSeconds.

2. Pomodoro Engine & Timer Subscription (ui/pomodoro.go)

• Create type PomodoroState struct:
  • Phase: PomodoroWork, PomodoroShortBreak, PomodoroLongBreak, PomodoroIdle, PomodoroPaused
  • RemainingSeconds int
  • TotalSeconds int
  • CompletedSprints int
  • TargetItemID string
• Bubble Tea timer integration:
  • Return tea.Tick(time.Second, func(t time.Time) tea.Msg { return pomodoroTickMsg{Time: t} }) when timer is active.
  • In Update(msg tea.Msg) in ui/app.go, handle pomodoroTickMsg, decrement RemainingSeconds, increment TimeSpentSeconds on the active focused item, and transition phases when reaching 0.

3. UI & Top Focus Banner Updates

• ui/treeview.go & ui/app.go:
  • Update Focus Banner renderer to display the live Pomodoro timer pill and sprint badges.
  • Display subtle ⏱️ [45m] badge in the tree view for items with logged time.
• ui/keys.go:
  • Add Pomodoro leader keybindings:
    • <space> p s: Start / Pause Pomodoro timer
    • <space> p r: Reset Pomodoro timer
    • <space> p n: Skip to next Pomodoro phase (Work/Break)
    • <space> p c: Clear timer & unassign
  • Register in WhichKey menu under <space> p (Pomodoro).

4. Configuration Options (config/config.go)

• Add fields to Config struct:

  pomodoro_work_mins: 25
  pomodoro_short_break_mins: 5
  pomodoro_long_break_mins: 15
  pomodoro_sound: true

• Expose toggles in interactive Config Dashboard (<space> c c).

---

📋 Step-by-Step Implementation Plan

• Phase 1: Model & Proto Persistence
  • Add time_spent_seconds (tag 17) to proto/v1/storage.proto and storage.pb.go.
  • Update model/item.go struct, methods, and cloning logic.
• Phase 2: Pomodoro State Engine
  • Implement ui/pomodoro.go state machine and tea.Tick message handler.
  • Handle pause, resume, reset, phase transitions, and time accumulation.
• Phase 3: UI & Focus Banner Integration
  • Update Top Focus Banner to render live timer, progress bar, and sprint indicators.
  • Add ANSI-safe time spent badges in ui/treeview.go.
  • Register <space> p keybindings in ui/keys.go and WhichKey menu.
• Phase 4: Config & Notifications
  • Add Pomodoro settings to config/config.go and ui/configmodal.go.
  • Add audio bell and desktop notification support on sprint complete.
• Phase 5: Tests & Documentation
  • Add unit tests in ui/pomodoro_test.go and model/item_test.go.
  • Update README.md, wiki/Power-User-Guide.md, and wiki/Keybindings-Reference.md.

---

✅ Acceptance Criteria

1. Starting Pomodoro via <space> p s initiates a 1-second interval ticker that renders smoothly in the Top Focus Banner.
2. Completed work seconds accurately accumulate into item.TimeSpentSeconds and persist across file save/reload.
3. Keybinding prefix tests pass without collisions in ui/keys_test.go.
4. Tests pass across all packages with zero race conditions (go test -race ./...).