gitforest 0.1.0 → 1.0.0

package/docs/ai/ui-enhancement-plan.md

@@ -1,562 +0,0 @@
-# Gitforest TUI Enhancement Plan
-
-## Overview
-
-This document outlines a comprehensive UI overhaul for Gitforest's TUI interface, transforming it from a basic list view into a feature-rich repository management interface with rich status indicators, detailed repo views, and comprehensive filtering.
-
----
-
-## 1. Enhanced Repository List Item (Rich Status Display)
-
-**Current**: Basic name, source icon, branch, sync badges, last activity
-
-**Proposed**: Multi-column layout with visual indicators
-
-```
-┌─ Status Indicators ────────────────────────────────────────────────────────────────────────┐
-│ [>] [x] ☁ ● autoclaude      ⎇ main    🔒 TS   ↑2 ↓0   ★12 🍴3   📅 1w ago   45.2 KB       │
-│     [ ] 🔗 ✓ gitforest          ⎇ feat    🌐 TS   ✓sync   ★0  🍴0   📅 today    12.1 KB       │
-│     [ ] 💻 ● local-only     ⎇ main    —  RS   no-rem  —   —     📅 3d ago   8.4 KB        │
-│     [ ] ☁   bander          —  —      🔒 JS   —       ★5  🍴1   📅 5d ago   2.1 MB        │
-└────────────────────────────────────────────────────────────────────────────────────────────┘
-```
-
-### Legend
-
-| Symbol | Meaning |
-|--------|---------|
-| **Source** | |
-| ☁ | GitHub-only (not cloned locally) |
-| 💻 | Local-only (not on GitHub) |
-| 🔗 | Both (synced local + GitHub) |
-| **Status** | |
-| ● | Dirty (uncommitted changes) |
-| ✓ | Clean |
-| ? | Unknown |
-| **Privacy** | |
-| 🔒 | Private repository |
-| 🌐 | Public repository |
-| **Language** | 2-char abbreviation (TS, JS, RS, PY, GO, etc.) |
-| **Sync** | |
-| ↑N | N unpushed commits |
-| ↓N | N unpulled commits |
-| ✓sync | Fully synchronized |
-| no-rem | No remote configured |
-| **Stats** | |
-| ★ | GitHub stars |
-| 🍴 | GitHub forks |
-| **Size** | Repository size (KB/MB/GB) |
-
----
-
-## 2. New Data Fields from GitHub API
-
-Extend `GitHubRepoInfo` interface with additional fields:
-
-```typescript
-interface GitHubRepoInfo {
-  // Existing fields...
-  name: string;
-  fullName: string;
-  owner: string;
-  description: string | null;
-  htmlUrl: string;
-  sshUrl: string;
-  cloneUrl: string;
-  isPrivate: boolean;
-  isArchived: boolean;
-  isFork: boolean;
-  pushedAt: Date | null;
-  updatedAt: Date | null;
-  defaultBranch: string;
-  language: string | null;
-  size: number;
-
-  // NEW fields:
-  stargazersCount: number;
-  forksCount: number;
-  openIssuesCount: number;
-  watchersCount: number;
-  topics: string[];
-  license: string | null;
-  hasIssues: boolean;
-  hasWiki: boolean;
-  hasDiscussions: boolean;
-  visibility: "public" | "private" | "internal";
-}
-```
-
----
-
-## 3. Enhanced Filter Bar with Global Options
-
-Press `?` to show filter options popup:
-
-```
-┌─ Filter Options ──────────────────────────────────────────────┐
-│ Quick Filters:                                                │
-│   0 All    1 Dirty   2 Unpushed   3 No-remote                │
-│   4 GitHub-only   5 Local-only   6 Private   7 Public        │
-│   8 Archived   9 Forks                                        │
-│                                                               │
-│ Language Filter: (type to filter by language)                 │
-│   l:typescript  l:javascript  l:rust  l:python  l:go         │
-│                                                               │
-│ Sort: s to cycle (name → status → activity → stars → size)   │
-│ Search: / to search by name, description, or path            │
-│                                                               │
-│ Press any key to close                                        │
-└───────────────────────────────────────────────────────────────┘
-```
-
-### New Quick Filters
-
-| Key | Filter | Description |
-|-----|--------|-------------|
-| 0 | All | Show all repositories |
-| 1 | Dirty | Repos with uncommitted changes |
-| 2 | Unpushed | Repos with unpushed commits |
-| 3 | No-remote | Local repos without remote |
-| 4 | GitHub-only | Repos on GitHub but not cloned |
-| 5 | Local-only | Local repos (cloned or local-only) |
-| 6 | Private | Private repositories |
-| 7 | Public | Public repositories |
-| 8 | Archived | Archived repositories |
-| 9 | Forks | Forked repositories |
-
-### Language Filter
-
-Type `l:` followed by language name to filter:
-- `l:typescript` or `l:ts`
-- `l:javascript` or `l:js`
-- `l:rust` or `l:rs`
-- `l:python` or `l:py`
-- `l:go`
-
----
-
-## 4. Column Headers (Sortable)
-
-```
-┌─ Column Headers ───────────────────────────────────────────────────────────────────────────┐
-│   Sel  Src Status Name              Branch  Vis Lang  Sync     Stars  Fork   Updated  Size│
-│   ─── ─── ────── ────────────────── ─────── ─── ───── ──────── ────── ───── ──────── ────│
-│                                                                                 [▼ sort]  │
-└────────────────────────────────────────────────────────────────────────────────────────────┘
-```
-
-Press `s` to cycle through sort fields:
-1. Status (default) - prioritizes repos needing attention
-2. Name - alphabetical
-3. Last Activity - most recently updated first
-4. Stars - most starred first
-5. Size - largest first
-
----
-
-## 5. Repository Detail Modal
-
-Press `Enter` to open, `Escape` to close.
-
-```
-┌─────────────────────────────────── autoclaude ────────────────────────────────────────────┐
-│                                                                                           │
-│  ☁ GitHub: bsunter/autoclaude                     🔒 Private   ★ 12   🍴 3   👀 5        │
-│  💻 Local: /Users/brian/code/autoclaude           ⎇ main       Size: 45.2 KB             │
-│                                                                                           │
-│  ┌─ Status ─────────────────────────────────────────────────────────────────────────────┐ │
-│  │  ● Dirty: 3 modified, 1 staged, 2 untracked                                          │ │
-│  │  ↑ 2 commits to push   ↓ 0 commits to pull                                           │ │
-│  │  Last local commit: 2 hours ago                                                       │ │
-│  │  Last GitHub push: 1 week ago                                                         │ │
-│  └──────────────────────────────────────────────────────────────────────────────────────┘ │
-│                                                                                           │
-│  ┌─ Actions ────────────────────────────────────────────────────────────────────────────┐ │
-│  │  [p] Push   [P] Pull   [f] Fetch   [o] Open in Browser   [c] Copy Clone URL          │ │
-│  │  [d] Open in Editor   [g] Open GitHub   [A] Archive                                  │ │
-│  └──────────────────────────────────────────────────────────────────────────────────────┘ │
-│                                                                                           │
-│  ┌─ README.md ──────────────────────────────────────────────────────────────────────────┐ │
-│  │                                                                                       │ │
-│  │  # Autoclaude                                                                         │ │
-│  │                                                                                       │ │
-│  │  > An AI-powered development assistant using Claude                                   │ │
-│  │                                                                                       │ │
-│  │  ## Features                                                                          │ │
-│  │                                                                                       │ │
-│  │  - **Code Generation**: Generate boilerplate and implement features                   │ │
-│  │  - **Code Review**: Get instant feedback on your code                                 │ │
-│  │  - **Documentation**: Auto-generate docs from code                                    │ │
-│  │                                                                                       │ │
-│  │  ## Installation                                                                      │ │
-│  │                                                                                       │ │
-│  │  ```bash                                                                              │ │
-│  │  bun install autoclaude                                                               │ │
-│  │  ```                                                                                  │ │
-│  │                                                                                       │ │
-│  │  [↑↓ scroll]                                                                          │ │
-│  └──────────────────────────────────────────────────────────────────────────────────────┘ │
-│                                                                                           │
-│  Topics: ai, claude, typescript, automation                                              │
-│  License: MIT   Created: Jan 2024   Language: TypeScript                                 │
-│                                                                                           │
-│  [Esc] Close   [j/k] Scroll README   [Tab] Next section                                  │
-└───────────────────────────────────────────────────────────────────────────────────────────┘
-```
-
-### Modal Sections
-
-1. **Header**: Repo name, GitHub link, privacy, stats
-2. **Location Info**: Local path, branch, size
-3. **Status Panel**: Git status details (dirty state, sync status, timestamps)
-4. **Actions Panel**: Quick action buttons with keyboard shortcuts
-5. **README Panel**: Scrollable markdown-rendered README
-6. **Footer**: Topics, license, language, help text
-
-### Modal Actions
-
-| Key | Action | Description |
-|-----|--------|-------------|
-| p | Push | Push local commits to remote |
-| P | Pull | Pull remote changes |
-| f | Fetch | Fetch remote without merging |
-| o | Open in Browser | Open GitHub page in browser |
-| c | Copy Clone URL | Copy SSH/HTTPS clone URL to clipboard |
-| d | Open in Editor | Open repo in configured editor |
-| g | Open GitHub | Open GitHub repo page |
-| A | Archive | Archive the repository on GitHub |
-| j/k | Scroll | Scroll README up/down |
-| Esc | Close | Close the modal |
-
----
-
-## 6. TUI Markdown Renderer
-
-For README display, implement a terminal-friendly markdown renderer:
-
-### Supported Elements
-
-| Element | Rendering |
-|---------|-----------|
-| `# Header` | Bold + cyan color |
-| `## H2` | Bold + blue color |
-| `### H3` | Bold |
-| `**bold**` | Bold text |
-| `*italic*` | Italic/dim text |
-| `` `code` `` | Gray background |
-| ```` ```code``` ```` | Gray background block |
-| `- list` | Indented bullet points |
-| `> quote` | Gray with `│` prefix |
-| `[link](url)` | Cyan underlined |
-| `---` | Horizontal line |
-
----
-
-## 7. New State & Types
-
-### Extended App Mode
-
-```typescript
-export type AppMode = 
-  | "normal" 
-  | "filter" 
-  | "action" 
-  | "help" 
-  | "confirm" 
-  | "clone" 
-  | "detail"          // NEW: Detail modal open
-  | "filter-options"; // NEW: Filter options overlay
-```
-
-### Detail Modal State
-
-```typescript
-export interface DetailModalState {
-  repo: UnifiedRepo;
-  readmeContent: string | null;
-  readmeLoading: boolean;
-  readmeError: string | null;
-  readmeScrollOffset: number;
-  activeSection: "status" | "actions" | "readme";
-}
-```
-
-### Extended Quick Filters
-
-```typescript
-export type QuickFilter = 
-  | "all" 
-  | "dirty" 
-  | "unpushed" 
-  | "no-remote" 
-  | "github-only" 
-  | "local-only"
-  | "private"    // NEW
-  | "public"     // NEW
-  | "archived"   // NEW
-  | "forks";     // NEW
-```
-
-### Language Filter State
-
-```typescript
-export interface FilterState {
-  text: string;
-  quickFilter: QuickFilter;
-  language: string | null;  // NEW: Filter by programming language
-}
-```
-
----
-
-## 8. Key Bindings Summary
-
-### Global Keys
-
-| Key | Action |
-|-----|--------|
-| `q` | Quit application |
-| `?` | Show filter options overlay |
-| `Tab` | Cycle view mode (local/github/all) |
-| `r` | Refresh repository list |
-
-### Navigation
-
-| Key | Action |
-|-----|--------|
-| `j` / `↓` | Move cursor down |
-| `k` / `↑` | Move cursor up |
-| `g` | Go to top |
-| `G` | Go to bottom |
-| `Enter` | Open detail modal |
-
-### Selection
-
-| Key | Action |
-|-----|--------|
-| `Space` | Toggle selection |
-| `a` | Select all / Deselect all |
-
-### Filtering & Sorting
-
-| Key | Action |
-|-----|--------|
-| `/` | Enter text search mode |
-| `s` | Cycle sort field |
-| `0-9` | Quick filters |
-| `l` | Enter language filter mode |
-| `Esc` | Cancel filter / Close modal |
-
-### Git Operations (List View)
-
-| Key | Action |
-|-----|--------|
-| `p` | Push selected repos |
-| `P` | Pull all repos |
-| `f` | Fetch all remotes |
-| `i` | Init git in selected |
-
-### GitHub Operations (List View)
-
-| Key | Action |
-|-----|--------|
-| `D` | Clone GitHub repos |
-| `c` | Create GitHub repo |
-| `C` | Full setup (init + create + push) |
-| `A` | Archive GitHub repo |
-
-### Detail Modal Keys
-
-| Key | Action |
-|-----|--------|
-| `Esc` | Close modal |
-| `j/k` | Scroll README |
-| `Tab` | Cycle sections |
-| `p` | Push |
-| `P` | Pull |
-| `f` | Fetch |
-| `o` | Open in browser |
-| `c` | Copy clone URL |
-| `d` | Open in editor |
-
----
-
-## 9. Implementation Plan
-
-### Phase 1: Enhanced List View (Priority: High)
-
-1. Update `GitHubRepoInfo` type with new fields
-2. Update GitHub service to fetch additional data (stars, forks, etc.)
-3. Redesign `UnifiedProjectItem` component with compact rich display
-4. Create `ColumnHeader` component for sortable columns
-5. Update filtering to support new quick filters
-
-**Files to modify:**
-- `src/types/index.ts`
-- `src/services/github.ts`
-- `src/components/UnifiedProjectItem.tsx`
-- `src/components/ColumnHeader.tsx` (new)
-- `src/state/store.tsx`
-
-### Phase 2: Detail Modal (Priority: High)
-
-1. Create `RepoDetailModal` component
-2. Implement `MarkdownRenderer` component for TUI
-3. Add README fetching from GitHub API (or local file)
-4. Add modal state management
-5. Implement scrollable README view
-
-**Files to create:**
-- `src/components/RepoDetailModal.tsx`
-- `src/components/MarkdownRenderer.tsx`
-- `src/utils/markdown.ts`
-
-**Files to modify:**
-- `src/types/index.ts`
-- `src/state/store.tsx`
-- `src/components/Layout.tsx`
-
-### Phase 3: Enhanced Filtering (Priority: Medium)
-
-1. Create `FilterOptionsOverlay` component
-2. Add language filter functionality
-3. Add private/public/archived/fork filters
-4. Update filter state management
-5. Update keybindings
-
-**Files to create:**
-- `src/components/FilterOptionsOverlay.tsx`
-
-**Files to modify:**
-- `src/hooks/useKeyBindings.ts`
-- `src/state/store.tsx`
-- `src/github/unified.ts`
-
-### Phase 4: Actions & Polish (Priority: Medium)
-
-1. Implement action handlers in detail modal
-2. Add "Open in Browser" functionality (using `open` command)
-3. Add "Open in Editor" functionality (configurable editor)
-4. Add clipboard support for copying URLs
-5. Add loading states and error handling
-6. Performance optimization
-
-**Files to modify:**
-- `src/components/RepoDetailModal.tsx`
-- `src/hooks/useKeyBindings.ts`
-- `src/types/index.ts` (add editor config)
-
-### Phase 5: Testing & Documentation (Priority: Low)
-
-1. Add unit tests for new components
-2. Add integration tests for new features
-3. Update help overlay with new keybindings
-4. Update README with new features
-
----
-
-## 10. File Structure
-
-### New Files
-
-```
-src/
-├── components/
-│   ├── RepoDetailModal.tsx      # Full-screen detail view
-│   ├── FilterOptionsOverlay.tsx # Filter help popup
-│   ├── ColumnHeader.tsx         # Sortable column headers
-│   └── MarkdownRenderer.tsx     # TUI markdown rendering
-└── utils/
-    └── markdown.ts              # Markdown parsing utilities
-```
-
-### Modified Files
-
-```
-src/
-├── types/
-│   └── index.ts                 # Extended types
-├── components/
-│   ├── UnifiedProjectItem.tsx   # Rich status display
-│   ├── Layout.tsx               # Modal routing
-│   ├── FilterBar.tsx            # Enhanced filters
-│   └── HelpOverlay.tsx          # Updated keybindings
-├── state/
-│   └── store.tsx                # New state management
-├── hooks/
-│   └── useKeyBindings.ts        # New keybindings
-├── services/
-│   └── github.ts                # Fetch additional data
-└── github/
-    └── unified.ts               # New filter functions
-```
-
----
-
-## 11. Technical Considerations
-
-### Performance
-
-- Use virtualization for long lists (already implemented)
-- Lazy-load README content only when modal opens
-- Cache GitHub API responses
-- Debounce filter input
-
-### Accessibility
-
-- Ensure all actions have keyboard shortcuts
-- Provide clear visual feedback for current state
-- Use consistent color coding
-
-### Error Handling
-
-- Graceful fallback when GitHub API fails
-- Show loading states during async operations
-- Display meaningful error messages
-
-### Configuration
-
-- Editor command (default: `$EDITOR` or `code`)
-- Browser command (default: `open` on macOS)
-- Default visibility for new repos
-- Cache TTL settings
-
----
-
-## 12. Success Metrics
-
-After implementation, the UI should:
-
-1. **Show more information at a glance** - Users can see status, privacy, language, stars, and sync status without opening details
-2. **Faster filtering** - Quick filters allow instant narrowing of repo list
-3. **Better repo understanding** - Detail modal shows README and comprehensive status
-4. **Faster actions** - Common operations available via single keystroke
-5. **Intuitive navigation** - Consistent vim-like keybindings throughout
-
----
-
-## Appendix: Language Abbreviations
-
-| Language | Abbreviation |
-|----------|-------------|
-| TypeScript | TS |
-| JavaScript | JS |
-| Rust | RS |
-| Python | PY |
-| Go | GO |
-| Ruby | RB |
-| Java | JV |
-| C | C |
-| C++ | C+ |
-| C# | C# |
-| PHP | PH |
-| Swift | SW |
-| Kotlin | KT |
-| Scala | SC |
-| Elixir | EX |
-| Haskell | HS |
-| Shell | SH |
-| HTML | HT |
-| CSS | CS |
-| Vue | VU |
-| Svelte | SV |