gitforest 0.1.0

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

@@ -0,0 +1,562 @@
+# 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 |

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "gitforest",
+  "version": "0.1.0",
+  "description": "TUI for managing multiple Git repositories and GitHub integration",
+  "module": "src/index.tsx",
+  "type": "module",
+  "bin": {
+    "gitforest": "./src/index.tsx"
+  },
+  "scripts": {
+    "start": "bun run src/index.tsx",
+    "dev": "bun --hot run src/index.tsx",
+    "tui": "bun run src/index.tsx",
+    "cli": "bun run src/cli/index.ts",
+    "test": "bun test --timeout 30000 && bun test --timeout 10000 ./test/unit/hooks/useKeyBindings.isolated.ts && bun test --timeout 20000 ./test/integration/app.isolated.tsx",
+    "test:unit": "bun test --timeout 10000 test/unit/utils/ test/unit/cli/ test/unit/components/ test/unit/config/ test/unit/types/ test/unit/state/ test/unit/operations/ test/unit/github/ test/unit/services/ && bun test --timeout 15000 test/unit/scanner/ && bun test --timeout 15000 test/unit/git/",
+    "test:db": "./run-db-tests.sh",
+    "test:integration": "bun test --timeout 30000 test/integration/scanner.test.ts && bun test --timeout 20000 ./test/integration/app.isolated.tsx",
+    "test:all": "bun run test",
+    "test:fast": "bun test test/unit/utils/ test/unit/cli/ test/unit/components/ test/unit/config/ test/unit/types/ test/unit/state/ test/unit/operations/ test/unit/github/ test/unit/services/",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "test:hooks": "./run-hooks-tests.sh",
+    "test:scanner": "bun test --timeout 15000 test/unit/scanner/",
+    "test:git": "bun test --timeout 15000 test/unit/git/",
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run typecheck",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate"
+  },
+  "dependencies": {
+    "ink": "^5.0.1",
+    "@inkjs/ui": "^2.0.0",
+    "ink-select-input": "^6.0.0",
+    "react": "^18.3.1",
+    "zod": "^3.23.8",
+    "yaml": "^2.6.1",
+    "drizzle-orm": "^0.36.4",
+    "chalk": "^5.3.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^18.3.12",
+    "drizzle-kit": "^0.28.1",
+    "ink-testing-library": "^4.0.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/app.tsx

@@ -0,0 +1,43 @@
+import React from "react";
+import { StoreProvider } from "./state/store.tsx";
+import { Layout } from "./components/Layout.tsx";
+import { useUnifiedRepos } from "./hooks/useUnifiedRepos.ts";
+import { useKeyBindings } from "./hooks/useKeyBindings.ts";
+import { useBackgroundFetch } from "./hooks/useBackgroundFetch.ts";
+import type { GitforestConfig, UnifiedRepo } from "./types/index.ts";
+
+interface AppContentProps {
+  config: GitforestConfig;
+}
+
+function AppContent({ config }: AppContentProps) {
+  const { loadUnifiedRepos, batchClone } = useUnifiedRepos(config);
+
+  // Clone handler for Layout
+  const handleClone = async (repos: UnifiedRepo[], targetDir: string, useSSH: boolean) => {
+    await batchClone(repos, targetDir, useSSH);
+  };
+
+  // Set up keyboard bindings
+  useKeyBindings({
+    config,
+    onRefresh: loadUnifiedRepos,
+  });
+
+  // Set up background fetch
+  useBackgroundFetch(config, loadUnifiedRepos);
+
+  return <Layout config={config} onRefresh={loadUnifiedRepos} onClone={handleClone} />;
+}
+
+interface AppProps {
+  config: GitforestConfig;
+}
+
+export function App({ config }: AppProps) {
+  return (
+    <StoreProvider>
+      <AppContent config={config} />
+    </StoreProvider>
+  );
+}