sepehr
4f7e808855
Next.js dashboard with git statistics, AI-powered summaries via Ollama, and research documents for project planning. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
948 lines
37 KiB
Markdown
948 lines
37 KiB
Markdown
---
|
|
stepsCompleted: [step-01-validate-prerequisites, step-02-design-epics, step-03-create-stories, step-04-final-validation]
|
|
status: 'complete'
|
|
completedAt: '2025-04-25'
|
|
inputDocuments:
|
|
- "prd.md"
|
|
- "product-brief-gitpulse.md"
|
|
- "architecture.md"
|
|
- "ux-design-specification.md"
|
|
workflowType: 'epics-and-stories'
|
|
project_name: 'GitPulse'
|
|
user_name: 'Ramez'
|
|
date: '2025-04-25'
|
|
---
|
|
|
|
# GitPulse - Epic Breakdown
|
|
|
|
## Overview
|
|
|
|
This document provides the complete epic and story breakdown for GitPulse, decomposing the requirements from the PRD, UX Design, and Architecture requirements into implementable stories.
|
|
|
|
## Requirements Inventory
|
|
|
|
### Functional Requirements
|
|
|
|
FR1: The user can initiate a recursive disk scan to discover Git repositories on their machine
|
|
FR2: The user can configure which root directories to scan
|
|
FR3: The user can exclude directories from scanning via a `.gitpulseignore` file (glob syntax)
|
|
FR4: The system can detect Git repositories by identifying `.git` folders
|
|
FR5: The user can manually trigger a rescan to refresh the repository list
|
|
FR6: The system can gracefully handle inaccessible directories (skip and log, no crash)
|
|
FR7: The system can cache scan results for instant reload on subsequent launches
|
|
FR8: The user can view repositories in a card grid showing branch, status (clean/dirty/ahead/behind), last commit, and stash count
|
|
FR9: The user can view repositories in a sortable, filterable list view with multi-select
|
|
FR10: The user can toggle between card grid and list view
|
|
FR11: The user can sort repositories by status, last activity date, branch name, or ahead/behind count
|
|
FR12: The user can filter repositories by status (clean, dirty, ahead, behind, dormant)
|
|
FR13: The system can display visual status indicators (color/badges) for instant pattern recognition across all repos
|
|
FR14: The system can render large repository lists (100+) without UI degradation
|
|
FR15: The user can select multiple repositories and execute batch `git pull`
|
|
FR16: The user can select multiple repositories and execute batch `git push`
|
|
FR17: The user can select multiple repositories and execute batch `git fetch`
|
|
FR18: The user can batch `git status` across multiple repositories
|
|
FR19: The system can report per-repo results for batch operations (success/failure with details)
|
|
FR20: The system can handle partial success — repos that succeed continue, repos that fail are reported with error details
|
|
FR21: The user can see specific error details (e.g., merge conflicts, auth errors) for failed repos
|
|
FR22: The user can enable Ollama integration for local, private repository health summaries
|
|
FR23: The user can configure cloud API keys (Gemini, DeepSeek, OpenAI, Anthropic) for AI-powered analysis
|
|
FR24: The system can generate one-line repository health summaries via the configured AI backend
|
|
FR25: The system can suggest commit messages based on staged changes via the configured AI backend
|
|
FR26: The system can detect and flag dormant repositories beyond a configurable threshold
|
|
FR27: The user can see a visual privacy indicator showing whether data processing is local or cloud-based
|
|
FR28: The system can operate entirely without any AI backend configured (deterministic status parsing as default)
|
|
FR29: The user can route different AI tasks to different providers (e.g., Ollama for commits, cloud for analysis)
|
|
FR30: The system can provide cross-repo analysis when using a cloud AI model (e.g., shared library dependencies across repos)
|
|
FR31: The user can run GitPulse as a background system tray agent with the dashboard closed
|
|
FR32: The system can monitor for remote changes and alert the user via native OS notifications
|
|
FR33: The system can send push reminders for repos with unpushed commits older than a configurable threshold
|
|
FR34: The user can configure GitPulse to auto-launch at system startup (opt-in)
|
|
FR35: The user can access common operations (status, pull, push) via the system tray context menu
|
|
FR36: The user can configure scan root directories via a settings interface
|
|
FR37: The user can configure AI backend settings (Ollama endpoint, cloud API keys, per-task routing)
|
|
FR38: The user can configure notification behavior (frequency, types, thresholds)
|
|
FR39: The user can configure system tray agent behavior (launch at startup, monitoring interval)
|
|
FR40: User settings are persisted locally and survive application restarts
|
|
FR41: The user can reset all settings to defaults
|
|
FR42: The user can launch GitPulse without any account, login, or network configuration
|
|
FR43: The system can operate fully offline (all core features work without network access)
|
|
FR44: The user can manually check for application updates via system tray or settings
|
|
FR45: The user can download GitPulse as a single binary (no installer wizard required)
|
|
FR46: The system can run on Windows, macOS, and Linux from initial release
|
|
|
|
### NonFunctional Requirements
|
|
|
|
NFR1: Cold startup < 3 seconds
|
|
NFR2: Disk scan speed < 5 seconds (SSD, <100 repos)
|
|
NFR3: Memory usage < 200 MB with 50+ repos
|
|
NFR4: Binary size ~15 MB
|
|
NFR5: Batch operation throughput < 30 seconds (pull/push 20 repos)
|
|
NFR6: UI rendering responsiveness < 16ms per frame (60fps)
|
|
NFR7: Async AI loading — Smart Status does not block dashboard
|
|
NFR8: Incremental scan reload < 1 second from cache
|
|
NFR9: API key storage via OS keychain/secure storage, not plaintext
|
|
NFR10: Privacy by default — no data leaves machine unless cloud backend explicitly enabled
|
|
NFR11: Data flow transparency — visual indicator for cloud data transit
|
|
NFR12: Scan scope control — `.gitpulseignore` exclusions enforced
|
|
NFR13: Zero telemetry by default — opt-in only
|
|
NFR14: Git execution isolation — malicious repo cannot compromise application
|
|
NFR15: Dependency auditing — Rust/npm vulnerabilities checked before release
|
|
NFR16: Ollama version compatibility (API v1) with graceful fallback
|
|
NFR17: Cloud API compliance — stable API versions; rate limit handling
|
|
NFR18: Git version compatibility >= 2.20 on all platforms
|
|
NFR19: Native OS integration — platform-native tray, notifications, startup
|
|
NFR20: AI offline resilience — deterministic fallback when Ollama/cloud unavailable
|
|
NFR21: Scan fault tolerance — completes even if individual directories fail
|
|
NFR22: Batch fault tolerance — successful repos complete even when others fail
|
|
NFR23: Crash recovery — state preserved across crashes
|
|
NFR24: User data persistence — settings, scan configs, API keys survive updates
|
|
NFR25: Keyboard navigation for all core operations
|
|
NFR26: High contrast support — status indicators distinguishable in dark/high contrast mode
|
|
NFR27: Screen reader compatibility — ARIA markup on key dashboard components
|
|
|
|
### Additional Requirements (Architecture)
|
|
|
|
- Starter template: `npm create tauri-app@latest -- --template react-ts --manager npm gitpulse`
|
|
- Post-scaffold stack: Zustand, Tailwind CSS, Vitest, Playwright
|
|
- Tauri plugins: tauri-plugin-store, tauri-plugin-shell, tauri-plugin-fs, tauri-plugin-autostart, tauri-plugin-notification
|
|
- Rust crates: keyring (OS keychain), thiserror (errors), async-trait (AI trait)
|
|
- Virtualization: @tanstack/react-virtual for 100+ repo rendering (FR14/NFR6)
|
|
- AiProvider trait: health_summary, suggest_commit_message, cross_repo_analysis, provider_type, is_local
|
|
- 5 provider implementations: Ollama, Gemini, DeepSeek, OpenAI, Anthropic
|
|
- CI/CD: GitHub Actions matrix (Windows x64, macOS x64+ARM, Linux x64)
|
|
- Distribution: GitHub Releases, single binary per platform, manual updates only
|
|
- Code signing deferred to Phase 1.5
|
|
- Error handling: AppError enum (ScanError, GitError, AiError, ConfigError), no unwrap in production
|
|
- IPC: Commands (CRUD) + Events (async streaming), namespace:event format
|
|
- Frontend state: Zustand stores as presentation cache, Rust = source of truth
|
|
- Dormancy detection logic in scanner.rs or commands/dashboard.rs
|
|
- .gitpulseignore parser using ignore or globset crate
|
|
- i18n framework (react-i18next or typesafe-i18n) ready from day 1
|
|
|
|
### UX Design Requirements
|
|
|
|
UX-DR1: Implement Tailwind design token system — status colors (clean/dirty/ahead/behind/dormant), privacy colors (local/cloud), neutral palette, spacing scale (4px base)
|
|
UX-DR2: Implement StatusBadge component — 5 variants (color+icon+label), 3 sizes (sm/md/lg), WCAG AA accessible
|
|
UX-DR3: Implement RepoCard component — anatomy (header/branch/stats/footer/AI line), 6 states, keyboard nav, click-expand, right-click context menu
|
|
UX-DR4: Implement RepoRow component — checkbox, status icon, name, branch, ahead/behind, last commit, action menu, sortable columns
|
|
UX-DR5: Implement StatsBar component — 5 metric cards, collapsible, clickable-to-filter, collapse at <900px width
|
|
UX-DR6: Implement PrivacyBadge component — local (shield/green) and cloud (cloud/amber) modes, transition animation, aria-live
|
|
UX-DR7: Implement BatchToolbar component — slide-down on selection, progress counter, disable during ops
|
|
UX-DR8: Implement SmartStatusLine component — AI summary with blue left border, skeleton loading, graceful absence on error
|
|
UX-DR9: Implement EmptyState component — 0 repos CTA ("Open Settings"), 0 filter results ("Clear filter"), scan progress transition
|
|
UX-DR10: Implement dark mode (default) and light mode with system fonts and 4px spacing grid
|
|
UX-DR11: Implement Card Grid layout — auto-fill minmax(280px, 1fr), 16px gap, 2-5 cards per row based on window width
|
|
UX-DR12: Implement List View layout — 56px rows, fixed/flexible columns, virtualized rendering
|
|
UX-DR13: Implement TopBar (48px) — title, Grid/List toggle, filter pills with counts, rescan button, PrivacyBadge
|
|
UX-DR14: Implement command palette (Cmd/Ctrl+K) — fuzzy search, keyboard navigable, 8+ commands
|
|
UX-DR15: Implement keyboard shortcuts — Cmd/Ctrl+K/G/L/R/,, Cmd/Ctrl+A, Escape, Space, Enter
|
|
UX-DR16: Implement right-click context menu — Pull/Push/Fetch, Open Terminal/File Manager, Copy Path, Refresh
|
|
UX-DR17: Implement skeleton loading (initial scan), streaming progress (batch ops), inline loading (AI queries)
|
|
UX-DR18: Implement inline error feedback — red border + text on cards/rows, never modal for batch errors
|
|
UX-DR19: Implement WCAG 2.1 AA — 4.5:1 contrast, ARIA labels, focus indicators, screen reader support, reduced motion, high contrast mode
|
|
UX-DR20: Implement responsive window breakpoints — sm(<900px)/md(900-1199px)/lg(1200-1599px)/xl(>=1600px)
|
|
UX-DR21: Implement window persistence — position/size remembered via tauri-plugin-store
|
|
UX-DR22: Implement toastless design — all feedback inline, native OS notifications via tray only
|
|
UX-DR23: Implement window close behavior — close minimizes to tray, Cmd/Ctrl+Q quits
|
|
UX-DR24: Implement Radix UI primitives layer — Dialog, Select, Tooltip, DropdownMenu, Checkbox, ToggleGroup, Popover
|
|
UX-DR25: Implement 3-layer component architecture — Layer 1 (Radix+Tailwind primitives), Layer 2 (domain components), Layer 3 (feature compositions)
|
|
|
|
### FR Coverage Map
|
|
|
|
| FR | Epic | Description |
|
|
|---|---|---|
|
|
| FR1 | Epic 1 | Recursive disk scan for Git repos |
|
|
| FR2 | Epic 1 | Configure root directories to scan |
|
|
| FR3 | Epic 1 | `.gitpulseignore` exclusion |
|
|
| FR4 | Epic 1 | Detect repos via `.git` folders |
|
|
| FR5 | Epic 1 | Manual rescan trigger |
|
|
| FR6 | Epic 1 | Handle inaccessible directories |
|
|
| FR7 | Epic 1 | Cache scan results |
|
|
| FR8 | Epic 1 | Card grid view with repo details |
|
|
| FR9 | Epic 1 | Sortable/filterable list view |
|
|
| FR10 | Epic 1 | Toggle card/list view |
|
|
| FR11 | Epic 1 | Sort by status/activity/branch/ahead-behind |
|
|
| FR12 | Epic 1 | Filter by status |
|
|
| FR13 | Epic 1 | Visual status indicators |
|
|
| FR14 | Epic 1 | Render 100+ repos without degradation |
|
|
| FR15 | Epic 2 | Batch git pull |
|
|
| FR16 | Epic 2 | Batch git push |
|
|
| FR17 | Epic 2 | Batch git fetch |
|
|
| FR18 | Epic 2 | Batch git status |
|
|
| FR19 | Epic 2 | Per-repo batch results |
|
|
| FR20 | Epic 2 | Partial success handling |
|
|
| FR21 | Epic 2 | Error details for failed repos |
|
|
| FR22 | Epic 3 | Ollama integration for local AI |
|
|
| FR23 | Epic 3 | Cloud API key configuration |
|
|
| FR24 | Epic 3 | AI health summaries |
|
|
| FR25 | Epic 3 | AI commit message suggestions |
|
|
| FR26 | Epic 3 | Dormant repo detection |
|
|
| FR27 | Epic 3 | Visual privacy indicator |
|
|
| FR28 | Epic 3 | Operate without AI backend |
|
|
| FR29 | Epic 3 | Per-task AI provider routing |
|
|
| FR30 | Epic 3 | Cross-repo AI analysis |
|
|
| FR31 | Epic 4 | Background system tray agent |
|
|
| FR32 | Epic 4 | Remote change monitoring & alerts |
|
|
| FR33 | Epic 4 | Push reminders for unpushed commits |
|
|
| FR34 | Epic 4 | Auto-launch at startup (opt-in) |
|
|
| FR35 | Epic 4 | Tray context menu operations |
|
|
| FR36 | Epic 5 | Configure scan root directories |
|
|
| FR37 | Epic 5 | Configure AI backend settings |
|
|
| FR38 | Epic 5 | Configure notification behavior |
|
|
| FR39 | Epic 5 | Configure system tray behavior |
|
|
| FR40 | Epic 5 | Persist settings locally |
|
|
| FR41 | Epic 5 | Reset settings to defaults |
|
|
| FR42 | Cross-cutting | No account/login required |
|
|
| FR43 | Cross-cutting | Fully offline operation |
|
|
| FR44 | Cross-cutting | Manual update check |
|
|
| FR45 | Cross-cutting | Single binary distribution |
|
|
| FR46 | Cross-cutting | Windows/macOS/Linux support |
|
|
|
|
## Epic List
|
|
|
|
### Epic 1: Repository Discovery & Dashboard
|
|
|
|
Users can discover all Git repositories on their machine and see them at a glance with status, branch, and activity information in both card grid and list views.
|
|
|
|
**FRs covered:** FR1, FR2, FR3, FR4, FR5, FR6, FR7, FR8, FR9, FR10, FR11, FR12, FR13, FR14
|
|
|
|
**Key NFRs:** NFR1 (cold startup <3s), NFR2 (scan <5s), NFR3 (memory <200MB), NFR6 (60fps), NFR8 (cache reload <1s), NFR21 (scan fault tolerance), NFR23 (crash recovery)
|
|
|
|
**Standalone value:** "Launch and Know" moment — users open GitPulse and instantly see all their repos with visual status. Fully functional without any other epic.
|
|
|
|
### Epic 2: Batch Git Operations
|
|
|
|
Users can select multiple repositories and execute pull, push, fetch, and status operations in batch, with per-repo success/failure reporting and partial success handling.
|
|
|
|
**FRs covered:** FR15, FR16, FR17, FR18, FR19, FR20, FR21
|
|
|
|
**Key NFRs:** NFR5 (batch 20 repos <30s), NFR14 (git isolation), NFR22 (batch fault tolerance)
|
|
|
|
**Standalone value:** Once repos are displayed (Epic 1), users can immediately act on them in bulk. Complete batch operation domain.
|
|
|
|
### Epic 3: AI-Powered Repository Insights
|
|
|
|
Users can leverage local (Ollama) or cloud AI providers for repository health summaries, commit message suggestions, dormancy detection, and cross-repo analysis — with clear privacy indicators.
|
|
|
|
**FRs covered:** FR22, FR23, FR24, FR25, FR26, FR27, FR28, FR29, FR30
|
|
|
|
**Key NFRs:** NFR7 (async AI loading), NFR9 (API key via keychain), NFR10 (privacy by default), NFR11 (data flow transparency), NFR16 (Ollama compat), NFR17 (cloud API compliance), NFR20 (AI offline resilience)
|
|
|
|
**Standalone value:** Adds intelligent analysis layer. Works without AI (deterministic fallback) and with any combination of providers. Privacy-first with visual indicators.
|
|
|
|
### Epic 4: Background Agent & Notifications
|
|
|
|
Users can run GitPulse as a background system tray agent that monitors for remote changes, sends push reminders, and provides quick access to common operations via tray context menu.
|
|
|
|
**FRs covered:** FR31, FR32, FR33, FR34, FR35
|
|
|
|
**Key NFRs:** NFR19 (native OS integration), NFR18 (Git >= 2.20 compat)
|
|
|
|
**Standalone value:** Transforms GitPulse from a "check when needed" tool to an "always watching" agent. Tray menu provides quick operations even with dashboard closed.
|
|
|
|
### Epic 5: Settings & Preferences
|
|
|
|
Users can configure all aspects of GitPulse — scan roots, AI backends, per-task AI routing, notification behavior, system tray behavior — with settings persisted locally and resettable to defaults.
|
|
|
|
**FRs covered:** FR36, FR37, FR38, FR39, FR40, FR41
|
|
|
|
**Key NFRs:** NFR24 (data persistence)
|
|
|
|
**Standalone value:** Complete configuration management. Users can customize every aspect of their GitPulse experience.
|
|
|
|
### Cross-Cutting Requirements (span all epics)
|
|
|
|
**FRs:** FR42 (no account), FR43 (fully offline), FR44 (update check), FR45 (single binary), FR46 (cross-platform)
|
|
|
|
**NFRs:** NFR4 (binary ~15MB), NFR12 (scan scope control), NFR13 (zero telemetry), NFR15 (dependency auditing), NFR25 (keyboard nav), NFR26 (high contrast), NFR27 (screen reader)
|
|
|
|
**UX-DRs:** Applied across all epics as design system standards
|
|
|
|
### Natural Dependencies
|
|
|
|
- **Epic 1** is the foundation — all other epics build on having repos discovered and displayed
|
|
- **Epic 2** requires Epic 1 (needs repo list for batch operations)
|
|
- **Epic 3** requires Epic 1 (needs repo data for AI analysis), integrates with Epic 5 for AI config
|
|
- **Epic 4** requires Epic 1 (needs repo list for monitoring), integrates with Epic 5 for tray/notification config
|
|
- **Epic 5** can be developed in parallel with Epics 2-4, but settings UI for each epic should be available when that epic ships
|
|
|
|
## Epic 1: Repository Discovery & Dashboard
|
|
|
|
### Story 1.1: App Shell & First Launch Experience
|
|
|
|
As a user,
|
|
I want to launch GitPulse and see a polished dark-mode dashboard with an empty state prompting me to configure scan roots,
|
|
So that I have a clear starting point.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** GitPulse is launched for the first time
|
|
**When** no scan roots are configured
|
|
**Then** the dashboard shows an empty state with a "Open Settings" CTA
|
|
**And** the TopBar (48px) shows title, Grid/List toggle, filter area, rescan button, and PrivacyBadge placeholder
|
|
**And** dark mode is the default with system fonts and 4px spacing grid
|
|
**And** window position and size are persisted via tauri-plugin-store
|
|
|
|
**FRs:** FR2 (partial) | **UX-DRs:** UX-DR9, UX-DR10, UX-DR13, UX-DR22, UX-DR24, UX-DR25
|
|
|
|
---
|
|
|
|
### Story 1.2: Scan Root Configuration
|
|
|
|
As a user,
|
|
I want to configure which root directories GitPulse should scan for repositories,
|
|
So that I control the scope of discovery.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** the settings interface is open
|
|
**When** the user adds a scan root directory path
|
|
**Then** the path is validated (exists, is directory, readable)
|
|
**And** invalid paths show inline error feedback
|
|
**And** configured roots are persisted via tauri-plugin-store and survive restarts
|
|
**And** user can remove previously configured roots
|
|
|
|
**FRs:** FR2
|
|
|
|
---
|
|
|
|
### Story 1.3: Recursive Repository Discovery
|
|
|
|
As a user,
|
|
I want GitPulse to recursively scan my configured directories and discover Git repositories by detecting `.git` folders,
|
|
So that I don't have to manually add each one.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** scan root directories are configured
|
|
**When** a scan is initiated
|
|
**Then** the scanner recursively walks the directory tree
|
|
**And** detects Git repositories by identifying `.git` folders
|
|
**And** collects repo metadata (path, current branch, ahead/behind, dirty/clean status, last commit date, stash count)
|
|
**And** directories matching `.gitpulseignore` patterns (glob syntax) are excluded
|
|
**And** scan completes within 5 seconds on SSD with <100 repos
|
|
|
|
**FRs:** FR1, FR3, FR4 | **NFRs:** NFR2, NFR12
|
|
|
|
---
|
|
|
|
### Story 1.4: Scan Fault Tolerance
|
|
|
|
As a user,
|
|
I want GitPulse to skip inaccessible or permission-denied directories gracefully,
|
|
So that one problem directory doesn't stop the entire scan.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** a scan is running
|
|
**When** the scanner encounters an inaccessible or permission-denied directory
|
|
**Then** the directory is skipped and logged
|
|
**And** the scan continues without crashing
|
|
**And** error count is available for display
|
|
|
|
**FRs:** FR6 | **NFRs:** NFR21
|
|
|
|
---
|
|
|
|
### Story 1.5: Scan Result Caching & Manual Rescan
|
|
|
|
As a user,
|
|
I want GitPulse to cache scan results so subsequent launches load instantly, and I want a manual rescan button to refresh on demand,
|
|
So that I get instant access to my repos without waiting.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** a scan has completed successfully
|
|
**When** GitPulse is relaunched
|
|
**Then** cached results load within 1 second
|
|
**And** the user sees the repository dashboard immediately
|
|
**Given** the user clicks the rescan button in the TopBar
|
|
**When** a rescan is triggered
|
|
**Then** the scan runs fresh and updates the cache
|
|
**And** streaming progress is visible during the scan
|
|
|
|
**FRs:** FR5, FR7 | **NFRs:** NFR8, NFR23
|
|
|
|
---
|
|
|
|
### Story 1.6: Repository Card Grid View
|
|
|
|
As a user,
|
|
I want to see my discovered repositories as cards in a responsive grid, each showing branch, status indicator, last commit, and stash count,
|
|
So that I can assess all repos at a glance.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** repositories have been discovered
|
|
**When** the card grid view is active
|
|
**Then** each repo displays as a card with: repo name, branch name, StatusBadge (clean/dirty/ahead/behind/dormant), last commit relative time, stash count
|
|
**And** the grid uses auto-fill minmax(280px, 1fr) with 16px gap
|
|
**And** cards are keyboard navigable (Tab, Enter to expand)
|
|
**And** status colors use the design token system (clean=green, dirty=red, ahead=blue, behind=orange, dormant=gray)
|
|
**And** cards have 6 visual states (default, hover, selected, active, loading, error)
|
|
|
|
**FRs:** FR8, FR13 | **UX-DRs:** UX-DR1, UX-DR2, UX-DR3, UX-DR11
|
|
|
|
---
|
|
|
|
### Story 1.7: Repository List View with Multi-Select
|
|
|
|
As a user,
|
|
I want to see repositories in a compact list with sortable columns and multi-select checkboxes,
|
|
So that I can efficiently manage many repositories.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** repositories have been discovered
|
|
**When** the list view is active
|
|
**Then** repos display in 56px rows with columns: checkbox, status icon, name, branch, ahead/behind, last commit, action menu
|
|
**And** multi-select is supported via checkboxes and Cmd/Ctrl+A
|
|
**And** columns are sortable by clicking headers
|
|
**And** rendering is virtualized for 100+ repos
|
|
|
|
**FRs:** FR9, FR14 | **UX-DRs:** UX-DR4, UX-DR12 | **NFRs:** NFR6
|
|
|
|
---
|
|
|
|
### Story 1.8: View Toggle, Sorting, and Filtering
|
|
|
|
As a user,
|
|
I want to toggle between card and list view, sort by various fields, and filter by status,
|
|
So that I can customize the dashboard to my workflow.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** repositories are displayed in either view
|
|
**When** the user clicks the Grid/List toggle in the TopBar
|
|
**Then** the view switches between card grid and list view
|
|
**Given** the user clicks a column header or sort option
|
|
**Then** repos sort by status, last activity date, branch name, or ahead/behind count
|
|
**Given** the user clicks a filter pill in the TopBar
|
|
**Then** repos filter by status (clean, dirty, ahead, behind, dormant)
|
|
**And** filter pills show counts for each status
|
|
**And** keyboard shortcuts work: Cmd/Ctrl+G (grid), Cmd/Ctrl+L (list), Cmd/Ctrl+, (toggle)
|
|
|
|
**FRs:** FR10, FR11, FR12 | **UX-DRs:** UX-DR13, UX-DR15
|
|
|
|
---
|
|
|
|
### Story 1.9: Stats Bar & Command Palette
|
|
|
|
As a user,
|
|
I want to see aggregate stats across all repos and access a command palette for quick actions,
|
|
So that I have an overview and can navigate efficiently.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** repositories are loaded
|
|
**When** the StatsBar is visible
|
|
**Then** it shows 5 metric cards: total repos, clean, dirty, ahead, behind
|
|
**And** clicking a metric filters the repo list by that status
|
|
**And** StatsBar collapses at <900px width
|
|
**Given** the user presses Cmd/Ctrl+K
|
|
**When** the command palette opens
|
|
**Then** fuzzy search is available across 8+ commands (toggle view, rescan, filter by status, open settings, pull/push selected)
|
|
**And** the palette is keyboard navigable (arrows, Enter, Escape)
|
|
|
|
**UX-DRs:** UX-DR5, UX-DR14, UX-DR15
|
|
|
|
---
|
|
|
|
### Story 1.10: Loading States & Responsive Design
|
|
|
|
As a user,
|
|
I want skeleton loading during scans and a dashboard that adapts to window resizing,
|
|
So that the experience feels polished at any size and stage.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** a scan is in progress
|
|
**When** the dashboard is loading
|
|
**Then** skeleton loading placeholders are shown (not spinners)
|
|
**Given** the window is resized
|
|
**When** crossing breakpoints (sm<900, md 900-1199, lg 1200-1599, xl>=1600)
|
|
**Then** layout adapts with 2-5 cards per row accordingly
|
|
**And** window position and size are remembered across sessions
|
|
|
|
**UX-DRs:** UX-DR17, UX-DR20, UX-DR21
|
|
|
|
---
|
|
|
|
### Story 1.11: Accessibility Foundation
|
|
|
|
As a user,
|
|
I want the dashboard to be keyboard navigable with screen reader support and high contrast compatibility,
|
|
So that GitPulse is usable regardless of ability.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** the user navigates via keyboard
|
|
**Then** all core operations are accessible (Tab, Enter, Escape, arrow keys)
|
|
**And** focus indicators are visible and distinct
|
|
**Given** a screen reader is active
|
|
**Then** ARIA labels are present on key dashboard components
|
|
**And** StatusBadge includes aria-live for status changes
|
|
**Given** high contrast mode is enabled
|
|
**Then** status indicators are distinguishable beyond color alone (icons + labels)
|
|
|
|
**UX-DRs:** UX-DR19 | **NFRs:** NFR25, NFR26, NFR27
|
|
|
|
---
|
|
|
|
## Epic 2: Batch Git Operations
|
|
|
|
### Story 2.1: Repository Multi-Select & Batch Toolbar
|
|
|
|
As a user,
|
|
I want to select multiple repositories and see a batch action toolbar appear,
|
|
So that I know which operations I can run on my selection.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** repositories are displayed in list view
|
|
**When** the user selects one or more repos via checkboxes or Cmd/Ctrl+A
|
|
**Then** a BatchToolbar slides down showing Pull, Push, Fetch, Status buttons
|
|
**And** a selection counter shows "N repos selected"
|
|
**And** all batch buttons are disabled while an operation is in progress
|
|
|
|
**UX-DRs:** UX-DR7
|
|
|
|
---
|
|
|
|
### Story 2.2: Batch Git Pull
|
|
|
|
As a user,
|
|
I want to select multiple repos and execute `git pull` on all of them,
|
|
So that I can update all repos at once.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** multiple repos are selected and the batch toolbar is visible
|
|
**When** the user clicks "Pull"
|
|
**Then** `git pull` executes across selected repos in parallel via tokio::process::Command
|
|
**And** per-repo progress is shown in the streaming toolbar
|
|
**And** the operation completes within 30 seconds for 20 repos
|
|
|
|
**FRs:** FR15 | **NFRs:** NFR5, NFR14
|
|
|
|
---
|
|
|
|
### Story 2.3: Batch Git Push
|
|
|
|
As a user,
|
|
I want to batch push selected repositories,
|
|
So that I can sync local commits to remotes efficiently.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** multiple repos are selected
|
|
**When** the user clicks "Push"
|
|
**Then** `git push` executes across selected repos in parallel
|
|
**And** per-repo progress is shown
|
|
**And** auth errors are caught and reported per repo
|
|
|
|
**FRs:** FR16
|
|
|
|
---
|
|
|
|
### Story 2.4: Batch Git Fetch
|
|
|
|
As a user,
|
|
I want to batch fetch selected repositories,
|
|
So that I can check for remote changes without merging.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** multiple repos are selected
|
|
**When** the user clicks "Fetch"
|
|
**Then** `git fetch` executes across selected repos in parallel
|
|
**And** ahead/behind counts are updated after fetch
|
|
**And** per-repo results are shown
|
|
|
|
**FRs:** FR17
|
|
|
|
---
|
|
|
|
### Story 2.5: Batch Git Status
|
|
|
|
As a user,
|
|
I want to run `git status` across multiple repos,
|
|
So that I can see which repos have uncommitted changes.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** multiple repos are selected
|
|
**When** the user clicks "Status"
|
|
**Then** `git status` runs across selected repos
|
|
**And** dirty/clean status is updated for each repo
|
|
**And** cards/rows update their StatusBadge accordingly
|
|
|
|
**FRs:** FR18
|
|
|
|
---
|
|
|
|
### Story 2.6: Batch Results Reporting & Partial Success
|
|
|
|
As a user,
|
|
I want to see per-repo results with specific error details for batch operations,
|
|
So that I know exactly what succeeded and failed.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** a batch operation is running
|
|
**When** some repos succeed and others fail
|
|
**Then** successful repos complete normally (partial success)
|
|
**And** failed repos show inline error feedback (red border + error text on card/row, never modal)
|
|
**And** specific error details are shown (merge conflicts, auth errors, network errors)
|
|
**And** the toolbar shows final summary: "N succeeded, M failed"
|
|
|
|
**FRs:** FR19, FR20, FR21 | **UX-DRs:** UX-DR18 | **NFRs:** NFR22
|
|
|
|
---
|
|
|
|
### Story 2.7: Right-Click Context Menu
|
|
|
|
As a user,
|
|
I want to right-click a repository for quick actions like pull, push, fetch, open terminal, or open file manager,
|
|
So that I can act on individual repos without multi-selecting.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** the user right-clicks on a repo card or row
|
|
**When** the context menu appears
|
|
**Then** options include: Pull, Push, Fetch, Open in Terminal, Open in File Manager, Copy Path, Refresh
|
|
**And** each option triggers the corresponding action
|
|
**And** the menu is keyboard navigable
|
|
|
|
**UX-DRs:** UX-DR16
|
|
|
|
---
|
|
|
|
## Epic 3: AI-Powered Repository Insights
|
|
|
|
### Story 3.1: AI Provider Trait & Ollama Integration
|
|
|
|
As a user,
|
|
I want to connect GitPulse to my local Ollama instance for private AI-powered insights,
|
|
So that I can get intelligent summaries without sending data to the cloud.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** Ollama is configured with an endpoint URL
|
|
**When** GitPulse connects to Ollama
|
|
**Then** the AiProvider trait is implemented with health_summary, suggest_commit_message, cross_repo_analysis, provider_type, is_local methods
|
|
**And** Ollama provider uses API v1 with graceful fallback on version mismatch
|
|
**And** health check verifies the endpoint is reachable
|
|
**And** when Ollama is unavailable, deterministic status parsing is used as fallback
|
|
|
|
**FRs:** FR22, FR28 | **NFRs:** NFR16, NFR20
|
|
|
|
---
|
|
|
|
### Story 3.2: Cloud AI Provider Configuration & Secure Key Storage
|
|
|
|
As a user,
|
|
I want to configure API keys for cloud providers (Gemini, DeepSeek, OpenAI, Anthropic) stored in my OS keychain,
|
|
So that I can use cloud AI securely.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** the AI settings section is open
|
|
**When** the user enters an API key for a provider
|
|
**Then** the key is stored via the OS keychain (keyring crate), not plaintext
|
|
**And** a connection test verifies the key works
|
|
**And** the key is never displayed in full after saving
|
|
|
|
**FRs:** FR23 | **NFRs:** NFR9
|
|
|
|
---
|
|
|
|
### Story 3.3: AI Health Summary (Smart Status Line)
|
|
|
|
As a user,
|
|
I want to see a one-line AI-generated health summary for each repository,
|
|
So that I can quickly understand repo state without reading git output.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** an AI provider is configured and a repo has status data
|
|
**When** the SmartStatusLine component renders
|
|
**Then** a one-line summary appears with a blue left border
|
|
**And** loading shows skeleton animation (non-blocking)
|
|
**And** on error, the line is absent (graceful degradation, no error shown)
|
|
**And** PrivacyBadge indicates local vs cloud processing
|
|
|
|
**FRs:** FR24, FR27 | **UX-DRs:** UX-DR6, UX-DR8 | **NFRs:** NFR7, NFR10, NFR11
|
|
|
|
---
|
|
|
|
### Story 3.4: AI Commit Message Suggestions
|
|
|
|
As a user,
|
|
I want AI to suggest commit messages based on my staged changes,
|
|
So that I can write better commit messages faster.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** a repository has staged changes
|
|
**When** the user requests a commit message suggestion
|
|
**Then** the AI generates a suggestion based on the staged diff
|
|
**And** the suggestion is shown inline (non-blocking)
|
|
**And** the feature works with any configured AI provider
|
|
|
|
**FRs:** FR25
|
|
|
|
---
|
|
|
|
### Story 3.5: Dormant Repository Detection
|
|
|
|
As a user,
|
|
I want GitPulse to flag repositories with no activity beyond a configurable threshold,
|
|
So that I can identify stale projects.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** a configurable dormancy threshold (default: 30 days)
|
|
**When** a repo's last commit is older than the threshold
|
|
**Then** the repo is flagged with "dormant" status
|
|
**And** the StatusBadge shows the dormant variant (gray)
|
|
**And** dormant repos appear in the dormant filter
|
|
|
|
**FRs:** FR26
|
|
|
|
---
|
|
|
|
### Story 3.6: Per-Task AI Provider Routing
|
|
|
|
As a user,
|
|
I want to route different AI tasks to different providers,
|
|
So that I can optimize for speed, cost, or privacy per task type.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** multiple AI providers are configured
|
|
**When** the user sets routing rules (e.g., Ollama for commits, cloud for analysis)
|
|
**Then** each AI task routes to the configured provider
|
|
**And** fallback to a default provider if the routed provider is unavailable
|
|
|
|
**FRs:** FR29
|
|
|
|
---
|
|
|
|
### Story 3.7: Cross-Repository AI Analysis
|
|
|
|
As a user,
|
|
I want AI to analyze patterns across my repositories,
|
|
So that I can understand relationships like shared library dependencies.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** a cloud AI provider is configured (cross-repo analysis not available with Ollama)
|
|
**When** the user requests cross-repo analysis
|
|
**Then** the AI provides insights about shared dependencies, patterns, and relationships across repos
|
|
**And** PrivacyBadge shows "cloud" indicator during analysis
|
|
|
|
**FRs:** FR30 | **NFRs:** NFR17
|
|
|
|
---
|
|
|
|
## Epic 4: Background Agent & Notifications
|
|
|
|
### Story 4.1: System Tray Agent & Window Management
|
|
|
|
As a user,
|
|
I want GitPulse to minimize to the system tray when I close the window,
|
|
So that it stays available in the background.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** GitPulse is running
|
|
**When** the user closes the window
|
|
**Then** the app minimizes to system tray (platform-native tray icon)
|
|
**And** double-clicking the tray icon reopens the dashboard
|
|
**Given** the user presses Cmd/Ctrl+Q
|
|
**Then** the app quits entirely
|
|
|
|
**FRs:** FR31 | **UX-DRs:** UX-DR23 | **NFRs:** NFR19
|
|
|
|
---
|
|
|
|
### Story 4.2: Tray Context Menu Operations
|
|
|
|
As a user,
|
|
I want to right-click the tray icon for quick access to common operations,
|
|
So that I can act without opening the dashboard.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** GitPulse is running in the tray
|
|
**When** the user right-clicks the tray icon
|
|
**Then** a context menu shows: status overview, Pull All, Push All, Open Dashboard, Quit
|
|
**And** selecting an action executes it immediately
|
|
**And** status overview shows clean/dirty/ahead/behind counts
|
|
|
|
**FRs:** FR35
|
|
|
|
---
|
|
|
|
### Story 4.3: Remote Change Monitoring & Alerts
|
|
|
|
As a user,
|
|
I want GitPulse to periodically check for remote changes and alert me via native OS notifications,
|
|
So that I stay informed about upstream activity.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** background monitoring is enabled
|
|
**When** remote changes are detected on a monitored repo
|
|
**Then** a native OS notification is sent identifying the repo and change count
|
|
**And** the monitoring interval is configurable
|
|
|
|
**FRs:** FR32
|
|
|
|
---
|
|
|
|
### Story 4.4: Push Reminders for Unpushed Commits
|
|
|
|
As a user,
|
|
I want GitPulse to remind me about unpushed commits older than a configurable threshold,
|
|
So that I don't forget to push important work.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** a repo has unpushed commits older than the configured threshold
|
|
**When** the background check runs
|
|
**Then** a native OS notification reminds the user to push
|
|
**And** the notification identifies the repo and commit age
|
|
**And** the threshold is configurable in settings
|
|
|
|
**FRs:** FR33
|
|
|
|
---
|
|
|
|
### Story 4.5: Auto-Launch at System Startup
|
|
|
|
As a user,
|
|
I want to configure GitPulse to start automatically with my system,
|
|
So that monitoring begins without manual intervention.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** auto-launch is enabled in settings (opt-in, default off)
|
|
**When** the system starts up
|
|
**Then** GitPulse launches and minimizes to tray
|
|
**And** tauri-plugin-autostart handles platform-specific startup registration
|
|
|
|
**FRs:** FR34
|
|
|
|
---
|
|
|
|
## Epic 5: Settings & Preferences
|
|
|
|
### Story 5.1: Settings Interface Foundation
|
|
|
|
As a user,
|
|
I want a clean settings interface organized into sections,
|
|
So that I can find and configure any aspect of GitPulse easily.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** the user opens settings (via menu, keyboard shortcut, or empty state CTA)
|
|
**When** the settings dialog appears
|
|
**Then** sections are organized as: Scan, AI, Notifications, System Tray
|
|
**And** all settings are persisted via tauri-plugin-store
|
|
**And** settings survive application restarts
|
|
|
|
**FRs:** FR40
|
|
|
|
---
|
|
|
|
### Story 5.2: Scan Configuration Settings
|
|
|
|
As a user,
|
|
I want to manage scan root directories and exclusions in settings,
|
|
So that I can control repository discovery behavior.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** the Scan settings section
|
|
**When** the user adds/removes scan root directories
|
|
**Then** changes take effect on next scan
|
|
**And** the dormancy threshold is configurable
|
|
**And** .gitpulseignore patterns can be previewed
|
|
|
|
**FRs:** FR36
|
|
|
|
---
|
|
|
|
### Story 5.3: AI Backend Settings & Per-Task Routing
|
|
|
|
As a user,
|
|
I want to configure AI providers, API keys, and per-task routing,
|
|
So that I can control how AI features work.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** the AI settings section
|
|
**When** the user configures providers
|
|
**Then** Ollama endpoint URL is configurable
|
|
**And** cloud API keys can be entered (stored in OS keychain)
|
|
**And** per-task routing can be set (health summary → provider, commit message → provider)
|
|
**And** connection test buttons verify each provider
|
|
|
|
**FRs:** FR37
|
|
|
|
---
|
|
|
|
### Story 5.4: Notification Behavior Settings
|
|
|
|
As a user,
|
|
I want to configure notification frequency, types, and thresholds,
|
|
So that I'm alerted about what matters without being overwhelmed.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** the Notifications settings section
|
|
**When** the user configures notifications
|
|
**Then** individual notification types can be enabled/disabled (remote changes, push reminders)
|
|
**And** the monitoring interval is configurable
|
|
**And** push reminder threshold is configurable
|
|
|
|
**FRs:** FR38
|
|
|
|
---
|
|
|
|
### Story 5.5: System Tray & Startup Settings
|
|
|
|
As a user,
|
|
I want to configure tray behavior and auto-launch,
|
|
So that GitPulse runs the way I prefer.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** the System Tray settings section
|
|
**When** the user configures tray behavior
|
|
**Then** auto-launch at startup can be toggled (opt-in)
|
|
**And** minimize-to-tray on close can be toggled
|
|
**And** monitoring behavior is configurable
|
|
|
|
**FRs:** FR39
|
|
|
|
---
|
|
|
|
### Story 5.6: Reset Settings to Defaults
|
|
|
|
As a user,
|
|
I want to reset all settings to defaults,
|
|
So that I can start fresh if my configuration becomes problematic.
|
|
|
|
**Acceptance Criteria:**
|
|
|
|
**Given** any settings section
|
|
**When** the user clicks "Reset to Defaults"
|
|
**Then** a confirmation dialog appears
|
|
**And** on confirmation, all settings revert to defaults
|
|
**And** API keys are preserved (with option to clear)
|
|
|
|
**FRs:** FR41
|