gamr 0.1.1__tar.gz

gamr-0.1.1/.bandit

@@ -0,0 +1,3 @@
+skips:
+  - B101
+  - B110

gamr-0.1.1/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.gamrstate

gamr-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,31 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: detect-private-key
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.1
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.8.3
+    hooks:
+      - id: bandit
+        args: [-r, -c, .bandit]
+        files: ^src/
+
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: v0.10.0.1
+    hooks:
+      - id: shellcheck
+        args: [-x, -e, SC2016]

gamr-0.1.1/.python-version

@@ -0,0 +1 @@
+3.14

gamr-0.1.1/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+0.1.1 (2025-06-10)
+
+  Initial public release.
+
+  - Live file watching with automatic tree updates (watchdog + polling fallback)
+  - Pure Python git integration via Dulwich — no git binary required
+  - File status indicators (Modified, Added, Deleted, Untracked, Staged)
+  - Three diff modes: full file, gutter markers, unified diff
+  - Three view modes: tree, flat filenames, flat relative paths
+  - Fuzzy filename search with RapidFuzz
+  - Git status filtering toggles
+  - Syntax-highlighted preview with Monokai theme
+  - Column sorting, resizable split pane, state persistence
+  - Background blame loading (author + last modified)
+  - .gitignore support
+  - Graceful degradation on non-git directories

gamr-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edouard Poor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gamr-0.1.1/Makefile

@@ -0,0 +1,145 @@
+# Makefile for Gamr — Git-aware Agent Monitor & Review
+#
+# Usage:
+#   make              Show all available targets
+#   make <target>     Run a specific target
+
+.PHONY: help
+help: ## Show this help message
+	@echo "Available targets:"
+	@echo ""
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2}'
+	@echo ""
+	@echo "Common workflows:"
+	@echo "  make install test     # Set up and run tests"
+	@echo "  make lint format      # Check and fix code"
+	@echo "  make security test    # Full validation"
+
+# ============================================================================
+# Setup and Installation
+# ============================================================================
+
+.PHONY: install
+install: ## Install dependencies with uv
+	uv sync
+
+.PHONY: install-hooks
+install-hooks: ## Install pre-commit git hooks
+	uv run pre-commit install
+
+# ============================================================================
+# Code Quality
+# ============================================================================
+
+.PHONY: lint
+lint: ## Run linting checks (ruff check + format check)
+	./scripts/lint.sh
+
+.PHONY: format
+format: ## Auto-fix formatting and linting issues
+	./scripts/lint.sh --fix
+
+.PHONY: pre-commit
+pre-commit: ## Run all pre-commit hooks manually
+	uv run pre-commit run --all-files
+
+.PHONY: security
+security: ## Run security scans (bandit + pip-audit)
+	uv run bandit -r src/ -c .bandit
+	uv run pip-audit
+
+# ============================================================================
+# Testing
+# ============================================================================
+
+.PHONY: test
+test: ## Run all tests
+	uv run pytest tests/ -q
+
+.PHONY: test-verbose
+test-verbose: ## Run tests with verbose output
+	uv run pytest tests/ -v
+
+.PHONY: coverage
+coverage: ## Run tests with coverage report
+	uv run pytest tests/ -q --cov=gamr --cov-report=term-missing
+
+# ============================================================================
+# Dependencies
+# ============================================================================
+
+.PHONY: update-deps
+update-deps: ## Update dependencies (7-day lag for supply chain protection)
+	@echo "╔══════════════════════════════════════════════════════════════╗"
+	@echo "║  Updating dependencies with 7-day publication lag            ║"
+	@echo "║  (packages published less than 7 days ago are excluded)      ║"
+	@echo "╚══════════════════════════════════════════════════════════════╝"
+	@echo ""
+	uv lock --upgrade --exclude-newer "$$(date -v-7d +%Y-%m-%dT00:00:00Z)"
+	uv sync
+	@echo ""
+	@echo "Running security audit..."
+	uv run pip-audit
+	@echo ""
+	@echo "✅ Dependencies updated. Run 'make test' to verify."
+
+# ============================================================================
+# Build
+# ============================================================================
+
+.PHONY: build
+build: ## Build wheel and sdist
+	uv build
+
+# ============================================================================
+# Run
+# ============================================================================
+
+.PHONY: run
+run: ## Run the app on the current directory
+	uv run gamr .
+
+# ============================================================================
+# Release
+# ============================================================================
+
+.PHONY: release
+release: ## Release (interactive — asks for bump type)
+	@CHOICE=$$(uv run scripts/chooser.py --title "Release type?" patch minor major 3>&1 1>&2) || exit 1; \
+	./scripts/release.sh $$CHOICE
+
+.PHONY: release-patch
+release-patch: ## Release a patch version (bug fixes)
+	./scripts/release.sh patch
+
+.PHONY: release-minor
+release-minor: ## Release a minor version (new features)
+	./scripts/release.sh minor
+
+.PHONY: release-major
+release-major: ## Release a major version (breaking changes)
+	./scripts/release.sh major
+
+# ============================================================================
+# Cleanup
+# ============================================================================
+
+.PHONY: clean
+clean: ## Remove build artifacts and caches
+	rm -rf dist/ .pytest_cache .ruff_cache .coverage
+
+# ============================================================================
+# Validation (Full Quality Check)
+# ============================================================================
+
+.PHONY: validate
+validate: lint security test ## Run lint, security, and tests
+	@echo ""
+	@echo "✅ Validation complete!"
+
+# ============================================================================
+# Default Target
+# ============================================================================
+
+.DEFAULT_GOAL := help

gamr-0.1.1/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: gamr
+Version: 0.1.1
+Summary: Git-aware Agent Monitor & Review — a TUI for reviewing AI agent work
+Author: Edouard Poor
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: dulwich>=0.22.7
+Requires-Dist: rapidfuzz>=3.14.0
+Requires-Dist: textual>=1.0.0
+Requires-Dist: watchdog>=6.0.0

gamr-0.1.1/README.md

@@ -0,0 +1,99 @@
+# Gamr
+
+**G**it-aware **A**gent **M**onitor & **R**eview — a TUI for reviewing AI agent work with live watching, fuzzy search, and diff preview.
+
+## Features
+
+- **Live file watching** — tree updates automatically when files change (watchdog + polling fallback)
+- **Git integration** — pure Python via Dulwich, no git binary required
+  - File status indicators (Modified, Added, Deleted, Untracked, Staged)
+  - Three diff modes: full file diff, gutter markers, unified diff (`d`/`D` to cycle)
+  - Blame data (last author, last modified) loaded in background
+  - Respects `.gitignore` rules
+- **Three view modes** — tree, flat filenames, flat relative paths (`v` to cycle)
+- **Column sorting** — click any column header to sort asc/desc/none
+- **Fuzzy search** — fzf-like filename filtering with RapidFuzz
+- **Git status filtering** — toggle buttons to show only modified, added, etc.
+- **Syntax-highlighted preview** — Monokai theme, scrollable, line numbers
+- **Copy file references** — double-click or drag lines to copy `path:line` to clipboard
+- **Full file diff** — syntax highlighting with inline +/- markers and colored backgrounds
+- **Diff overview bar** — 1-column change map (line or braille style) in full diff mode
+- **Gradient colors** — size and modification time columns colored by relative magnitude
+- **File icons** — loads from `~/.config/lsd/icons.yaml` if present
+- **Resizable split pane** — drag the divider between tree and preview
+- **Desktop-style navigation** — ←/→ to collapse/expand folders, ← on file collapses parent
+- **State persistence** — view mode, columns, collapsed dirs, selection, filters saved between sessions
+- **Graceful degradation** — works on non-git directories (hides git UI)
+
+## Install
+
+Requires Python 3.11+.
+
+```sh
+uv sync
+uv run gamr [path]
+```
+
+## Keybindings
+
+| Key      | Action                                             |
+| -------- | -------------------------------------------------- |
+| `↑`/`↓`  | Navigate files                                     |
+| `→`      | Expand directory                                   |
+| `←`      | Collapse directory (or parent if on file)          |
+| `space`  | Toggle expand/collapse                             |
+| `v`      | Cycle view mode (tree → flat name → flat path)     |
+| `d`      | Cycle diff mode (full → gutter → unified)           |
+| `D`      | Cycle diff mode reverse                            |
+| `m`      | Toggle Modified filter                             |
+| `f`      | Toggle follow mode (auto-select last changed file) |
+| `ctrl+f` | Focus search input                                 |
+| `b`      | Toggle blame columns (last author, git time)       |
+| `1`–`6`  | Toggle individual columns                          |
+| `tab`    | Switch focus between tree and preview              |
+| `ctrl+p` | Command palette (spaced paths, gradient toggle)    |
+| `q`      | Quit (saves state)                                 |
+
+Column headers are clickable to sort (ascending → descending → none).
+
+## Architecture
+
+```
+src/gamr/
+├── app.py              # Textual app, keybindings, orchestration
+├── commands.py         # Command palette provider
+├── models.py           # FileEntry, GitStatus, DiffMode, etc.
+├── state.py            # Persistent state management
+├── gamr.tcss          # Stylesheet
+├── services/
+│   ├── diff_parser.py  # Unified diff parsing into DiffData
+│   ├── file_scanner.py # Watchdog + polling fallback + git state watcher
+│   ├── file_index.py   # Merges scanner + git into FileEntry list
+│   ├── git_provider.py # GitProvider ABC + Dulwich implementation
+│   ├── filter.py       # Fuzzy and status filtering
+│   └── icons.py        # lsd icons.yaml loader
+└── widgets/
+    ├── file_tree_table.py  # DataTable with tree semantics
+    ├── tree_data.py        # Tree building and sorting logic
+    ├── filter_bar.py       # Git status toggles + search input
+    ├── preview_pane.py     # Syntax highlighting + diff view
+    └── split.py            # Resizable horizontal split
+```
+
+## Dependencies
+
+- [Textual](https://textual.textualize.io/) — TUI framework
+- [Dulwich](https://dulwich.io/) — pure Python git (no compiled deps)
+- [watchdog](https://github.com/gorakhargosh/watchdog) — filesystem events
+- [RapidFuzz](https://github.com/rapidfuzz/RapidFuzz) — fuzzy string matching
+
+## Tests
+
+```sh
+uv run pytest
+```
+
+## Documentation
+
+- [UI Design Rules](docs/UI_DESIGN.md) — all interaction behaviors and edge cases
+- [Architecture Decision Records](docs/adrs/README.md) — 23 ADRs covering all design choices

gamr-0.1.1/docs/UI_DESIGN.md

@@ -0,0 +1,151 @@
+# UI Design Rules
+
+## Navigation
+
+- **↑/↓** — Move cursor between rows in the file tree
+- **→** on a collapsed directory — Expand it
+- **→** on a file — No action
+- **←** on an expanded directory — Collapse it; cursor stays on the directory; preview clears or shows nothing (dirs have no content)
+- **←** on a file or collapsed directory — Collapse the parent folder, cursor moves to parent; preview clears (now on a directory)
+- **←** on a file at root level (no parent to collapse) — No action; preview stays on current file
+- **←** on a collapsed directory at root level — No action; preview unchanged
+
+### Edge cases for ← (collapse/navigate-to-parent)
+
+| Current selection                          | Action                        | Cursor after            | Preview after                     |
+| ------------------------------------------ | ----------------------------- | ----------------------- | --------------------------------- |
+| Expanded directory                         | Collapse it                   | Stays on that directory | Clears (directory has no preview) |
+| File inside `src/`                         | Collapse `src/`               | Moves to `src/` row     | Clears (now on directory)         |
+| Collapsed directory inside `src/`          | Collapse `src/`               | Moves to `src/` row     | Clears                            |
+| File at root level (no parent dir in tree) | Nothing                       | Unchanged               | Unchanged                         |
+| Root-level directory (already collapsed)   | Nothing                       | Unchanged               | Unchanged                         |
+| File while in flat view mode               | No action (no tree hierarchy) | Unchanged               | Unchanged                         |
+
+**Preview pane rule:** When cursor lands on a directory (after ← collapses parent), the preview pane shows nothing meaningful — directories don't have file content. The preview should retain its last content but dim or show "Select a file to preview" if we want to be explicit. Current behavior: preview simply doesn't update (the `NodeHighlighted` message carries `entry=None` for directory nodes, which is filtered out before rendering).
+- **Space** on a directory — Toggle expand/collapse
+- **Tab** — Switch focus between the file tree and preview pane
+- After expand/collapse, the cursor remains on the same directory row
+
+## View Modes
+
+- **v** — Cycle through: tree → flat name → flat path
+- **Tree** — Hierarchical with expand/collapse, dirs with ▶/▼ twisties
+- **Flat name** — Leaf filenames only, no paths, no hierarchy
+- **Flat path** — Relative paths (e.g., `src / worker / foo.py`)
+- Spaced paths (`/` → ` / `) is the default; toggled via command palette
+- When sorting is activated, tree mode auto-switches to flat path (sorting requires a flat list)
+- When sort is removed, the view restores to tree mode if that's where it was
+
+## Column Sorting
+
+- Click any column header — Cycle: ascending (▲) → descending (▼) → no sort
+- Sorting only applies in flat view modes
+- Sort indicators shown as suffix on the column header text
+
+## Filtering
+
+- **m** — Toggle the Modified git status filter
+- **ctrl+f** — Focus the search input
+- Filter buttons (M, A, D, ?, S) toggle git status filters
+- Search input provides fzf-like fuzzy filename matching (RapidFuzz)
+- Filters compose: status filter applied first, then fuzzy search
+- Filter state (selected filter IDs + search query) persisted between sessions
+
+## Follow Mode
+
+- **f** — Toggle follow mode on/off (notification shown)
+- When ON and the file watcher detects a change:
+  - The tree cursor automatically jumps to the last changed file
+  - Parent folders are expanded to reveal it
+  - The preview pane renders the file
+  - If the file is git-modified, the preview scrolls to the first diff hunk
+- When OFF, file watcher changes preserve the current cursor position
+- Follow mode does not persist between sessions (always starts OFF)
+
+## Preview Pane
+
+- Automatically shows the highlighted file's content
+- **d** — Cycle diff mode forward: full diff → gutter → unified diff
+- **D** (shift) — Cycle diff mode backward
+- Diff modes only apply to files with git changes; clean files show gutter mode as plain file
+- Full diff — Syntax-highlighted full file with `+`/`-` markers and colored backgrounds (green `#002200` for added, red `#300000` for removed)
+- Gutter — Syntax-highlighted file with a change column after line numbers: orange `●` for changed lines, green `+` for added, red `_` where deletions follow. When file has no changes, renders as plain file (no gutter column, no overview bar).
+- Unified diff — Standard coloured unified diff output
+- Preview and full diff share identical rendering (same line numbers, same syntax highlighting)
+- Monokai background (`#272822`) fills the entire pane
+- Header bar (pinned, doesn't scroll) shows filename on left, diff mode on right
+- When switching diff modes, scroll position is preserved by source line number mapping
+- Preview doesn't change when new files appear in the tree (stable during file watcher updates)
+- When the previewed file changes on disk, scroll position is preserved by source line mapping
+- The 10-second timestamp refresh does not reset preview scroll
+- **Double-click** a line → copies `path:line` to clipboard, flashes highlight
+- **Drag** across lines → live highlight, copies `path:start-end` on release
+- Invalid lines in unified diff (headers, removed) are not selectable
+
+## Columns
+
+- **1–6** — Toggle individual columns
+- **b** — Toggle blame columns (author + git time) and trigger background load
+- Available columns: Name, Status (St), Lines (+/-), Size, Modified, Author, Git Time
+- Size and Modified columns use a 256-color gradient by relative magnitude
+- Gradient toggled via command palette
+- Blame columns show "..." while loading, then populate progressively
+
+## Gradient Colors
+
+- Applied to Size and Modified columns
+- Color ramp: `[15, 51, 45, 39, 33, 27, 57, 93, 129, 165, 201, 200, 199, 198, 197, 196]`
+- White/cyan (low) → blue/purple (mid) → magenta/red (high)
+- Ranges computed per the currently visible/filtered file set
+
+## File Icons
+
+- Loaded from `~/.config/lsd/icons.yaml` if present
+- Resolution order: exact filename → file extension → filetype fallback (file/dir)
+- No PyYAML dependency required (custom parser)
+
+## Git Integration
+
+- Graceful degradation for non-git directories: hides status/lines columns and filter buttons
+- `.gitignore` rules enforced via Dulwich's `IgnoreFilterManager` (handles nesting, negation, `**` globs)
+- Git status: M (modified), A (added), D (deleted), ? (untracked), SM/SA/SD (staged variants)
+- Diff computed against HEAD
+
+## Live File Watching
+
+- File tree updates automatically when files change on disk
+- Watchdog for native filesystem events; polling fallback if watchdog fails
+- On change: rebuild file index, re-apply filters, sync table incrementally (only changed rows update)
+- Column headers preserved during data refreshes (no flicker)
+- Parent folders of changed files are auto-expanded to ensure visibility
+- Preview updates in-place (no scroll reset) when the selected file's content changes
+- Relative timestamps refresh every 10 seconds via `update_cell()` (no table rebuild)
+- `.gamrstate` excluded from watching (prevents feedback loop)
+
+## State Persistence
+
+- Saved to `~/.config/gamr/state.json` on quit
+- Restored on next launch if target directory matches
+- Persisted state: view mode, diff mode, column toggles, spaced paths, gradient, collapsed directories, split position, selected file, selected filter IDs, search query
+
+## Resizable Split
+
+- Draggable 1-character divider between tree and preview panes
+- Divider is subtle (`$surface-lighten-1`, one shade lighter on hover)
+- Split fraction persisted between sessions
+- Uses `fr` units for pane sizing to avoid rounding gaps
+
+## Diff Overview Bar
+
+- 1-column bar docked to the right of the preview pane
+- Only visible in full diff mode; hidden in unified diff and plain preview
+- Shows file-level change distribution: green (added), red (removed), yellow (mixed), dim (unchanged)
+- Two styles toggled via command palette (`ctrl+p` → "braille"):
+  - **Line mode** (default): `┃`/`│` characters
+  - **Braille mode**: Unicode braille dots packing 4 source lines per terminal row
+
+## Command Palette (ctrl+p)
+
+- Toggle spaced paths
+- Toggle gradient colors
+- Toggle diff overview style (line/braille)

gamr-0.1.1/docs/adrs/001-use-textual-framework.md

@@ -0,0 +1,28 @@
+---
+status: accepted
+date: 2026-06-08
+deciders: edouard
+---
+
+# ADR-001: Use Textual as TUI Framework
+
+## Context and Problem Statement
+
+Which Python TUI framework should we use to build an interactive, responsive file browser with split panes, data tables, and async workers?
+
+## Considered Options
+
+1. Textual — modern, CSS-like styling, async-native, rich widget library
+2. urwid — mature but lower-level, manual layout
+3. blessed/curses — very low-level, no built-in widgets
+
+## Decision Outcome
+
+Chosen option: **Textual** because it provides DataTable, Tree, reactive attributes, CSS styling, built-in Workers API for background tasks, and a pilot testing framework. Its async event loop integrates cleanly with our concurrency needs.
+
+### Consequences
+
+- Good, because DataTable gives us proper column alignment and headers
+- Good, because Workers API handles thread↔UI bridging elegantly
+- Good, because CSS separation keeps styling maintainable
+- Neutral, because Textual is relatively new and API may evolve

gamr-0.1.1/docs/adrs/002-pure-python-git-dulwich.md

@@ -0,0 +1,33 @@
+---
+status: accepted
+date: 2026-06-08
+deciders: edouard
+---
+
+# ADR-002: Pure Python Git via Dulwich
+
+## Context and Problem Statement
+
+How should we interact with git repositories? We need status, diff, blame, and gitignore support without requiring the git binary.
+
+## Considered Options
+
+1. Dulwich — pure Python, no compiled deps, no git binary needed
+2. pygit2 — libgit2 bindings, fast but requires native compilation
+3. GitPython — wraps the git CLI, requires git installed
+4. Shell out to git — simple but fragile, requires git binary
+
+## Decision Outcome
+
+Chosen option: **Dulwich** because it's pure Python (works anywhere Python does), has no compiled dependencies, provides porcelain + low-level APIs for status/diff/log, and includes `IgnoreFilterManager` for proper .gitignore handling.
+
+### Consequences
+
+- Good, because zero native deps — easy install on any platform
+- Good, because `IgnoreFilterManager` handles nested .gitignore, negation, and global excludes
+- Bad, because some operations (blame) are slower than native git
+- Mitigation: expensive operations run in background thread workers
+
+## Design Note
+
+The `GitProvider` ABC allows swapping Dulwich for another backend (e.g., pygit2 for performance) without changing the rest of the app.

gamr-0.1.1/docs/adrs/003-watchdog-polling-fallback.md

@@ -0,0 +1,28 @@
+---
+status: accepted
+date: 2026-06-08
+deciders: edouard
+---
+
+# ADR-003: Watchdog with Polling Fallback for File Watching
+
+## Context and Problem Statement
+
+How do we detect filesystem changes in real-time to keep the file tree up to date?
+
+## Considered Options
+
+1. watchdog — cross-platform, uses FSEvents on macOS, inotify on Linux
+2. OS-native only (PyObjC/fsevents) — macOS-specific
+3. Pure polling — simple but high latency and CPU cost
+4. watchdog + polling fallback — best of both
+
+## Decision Outcome
+
+Chosen option: **watchdog with polling fallback** because watchdog provides efficient native filesystem events on all platforms, and polling ensures the app still works if watchdog fails (e.g., network filesystems, Docker volumes).
+
+### Consequences
+
+- Good, because native events are near-instant on macOS (FSEvents)
+- Good, because polling fallback ensures robustness on edge-case filesystems
+- Neutral, watchdog runs its own thread — requires queue-based bridging to Textual's event loop

gamr-0.1.1/docs/adrs/004-datatable-tree-semantics.md

@@ -0,0 +1,32 @@
+---
+status: accepted
+date: 2026-06-08
+deciders: edouard
+---
+
+# ADR-004: DataTable with Tree Semantics (Not Tree Widget)
+
+## Context and Problem Statement
+
+How do we display a file tree alongside metadata columns with proper alignment?
+
+## Considered Options
+
+1. Textual's Tree widget with render_label() override — single text column, manual padding
+2. DataTable with tree-rendered first column — real columns, proper alignment
+3. Side-by-side Tree + DataTable with scroll sync — complex sync logic
+
+## Decision Outcome
+
+Chosen option: **DataTable with tree semantics in column 1** because it gives us real, properly-aligned columns with headers (clickable for sorting), while the first column renders indentation and expand/collapse icons to simulate tree behavior.
+
+### Consequences
+
+- Good, because columns are independently sized, have headers, support sorting
+- Good, because DataTable cursor_type="row" gives us keyboard navigation for free
+- Bad, because we reimplement expand/collapse logic (space key handler)
+- Neutral, tree state is internal; the DataTable is rebuilt on expand/collapse
+
+## Supersedes
+
+Initial implementation used Tree widget with render_label() appending padded metadata — but columns didn't align when filenames varied in length.

gamr-0.1.1/docs/adrs/005-thread-workers-for-git-ops.md

@@ -0,0 +1,37 @@
+---
+status: accepted
+date: 2026-06-08
+deciders: edouard
+---
+
+# ADR-005: Thread Workers for Blocking Git Operations
+
+## Context and Problem Statement
+
+Textual runs on a single asyncio event loop. Dulwich operations (status, diff, blame) are synchronous and can block for seconds on large repos. How do we prevent UI freezes?
+
+## Decision Outcome
+
+Use Textual's `@work(thread=True)` decorator to run blocking operations in thread workers.
+
+### Concurrency Architecture
+
+| Operation | Worker Type | Strategy |
+|-----------|------------|----------|
+| Git status | Thread, exclusive | Debounced after file changes |
+| Diff stats (+/- lines) | Thread, exclusive | Deferred after initial load |
+| Git blame/log | Thread, group | Progressive per-file updates |
+| File watcher | Thread, long-running | Polls queue every 0.5s |
+| Fuzzy filter | Inline (sync) | Fast enough for <10k files |
+
+### Key Constraints
+
+- **watchdog → UI**: Events arrive on watchdog's thread; bridged via `call_from_thread()` or `post_message()` (thread-safe)
+- **Dulwich → UI**: Results pushed via `call_from_thread()`; check `worker.is_cancelled` before updating
+- **Exclusive workers**: Cancel previous work when user changes selection/filter (prevents stale writes)
+
+### Consequences
+
+- Good, because UI stays responsive during expensive git operations
+- Good, because Textual manages worker lifecycle (auto-cleanup on widget removal)
+- Neutral, blame columns show "..." placeholder while loading