@tmustier/pi-files-widget 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to this extension will be documented in this file.
+
+## [0.1.6] - 2026-01-24
+
+### Added
+- Clearer install instructions and dependency notes in README
+
+## [0.1.5] - 2026-01-24
+
+### Added
+- Demo recording embedded in README
+
+### Changed
+- Comment sending now queues with follow-up delivery in streaming sessions
+- Split viewer logic into `viewer.ts` and shared helpers
+- Reduced browser render duplication with node format helpers
+
+## [0.1.4] - 2026-01-24
+
+### Changed
+- Split viewer logic into `viewer.ts` and shared helpers
+- Reduced browser render duplication with node format helpers
+
+## [0.1.3] - 2026-01-24
+
+### Changed
+- `c` in viewer now opens an inline comment prompt and sends a follow-up message
+
+## [0.1.2] - 2026-01-24
+
+### Changed
+- `c` in viewer now appends selection to editor input instead of sending immediately
+
+## [0.1.1] - 2026-01-24
+
+### Added
+- README with install steps, dependencies, and keybindings
+
+### Changed
+- Refactored into modular files (browser, git, tree, viewer, utils)
+
+## [0.1.0] - 2026-01-24
+
+### Added
+- `/files` command opens full-screen file browser
+- File tree with j/k navigation, Enter to open, h/l to collapse/expand
+- File viewer with syntax highlighting via `bat`
+- Markdown rendering via `glow`
+- Git diff view via `delta` with line numbers
+- Git status indicators (M, A, D, ?) on files
+- Agent-modified file tracking (🤖 indicator)
+- Changed files filter (`c` to toggle)
+- Jump to next/prev changed file (`]`/`[`)
+- Search in file tree (`/` then type)
+- Search in file viewer (`/` then type, `n`/`N` for next/prev match)
+- Select mode (`v`) to select lines and comment (`c`) to send to agent
+- Line counts and diff stats (+/-) on files and collapsed folders
+- Auto-refresh git status every 3 seconds (preserves expansion state)
+- PageUp/PageDown support in browser and viewer
+- Height adjustment (`+`/`-`)
+- Works in non-git directories (git features gracefully disabled)
+
+### Dependencies
+- `bat` - syntax highlighting (recommended)
+- `glow` - markdown rendering (recommended)
+- `delta` - diff formatting (recommended)
+
+Install with: `brew install bat git-delta glow`

package/DESIGN.md

@@ -0,0 +1,452 @@
+# Pi Editor Extension
+
+A Pi extension that provides an in-terminal file browser, viewer, and review workflow - enabling you to navigate, view, and comment on files without leaving Pi or interrupting the agent.
+
+## Problem Statement
+
+When working with coding agents in Pi:
+- Viewing files requires either putting full content into context (`cat`) or leaving the terminal
+- Reviewing diffs and agent changes means context-switching to an external editor
+- No way to easily browse the project structure while the agent works
+- No feedback loop for "I see this line, let me comment on it and send to agent"
+
+## Goals
+
+### MVP (v0.1)
+1. **File Tree Widget** - Toggleable file browser showing project structure
+2. **File Viewer** - View files with syntax highlighting, scroll, search
+3. **Diff View** - Toggle diff vs HEAD for modified files
+4. **Markdown Rendering** - Render .md files nicely (via `glow` or similar)
+5. **Select + Comment + Send** - Select text, add comment, send to agent as steering message
+
+### Future Enhancements
+- Agent vs human edit attribution (Cursor Blame style)
+- Word-level diff for prose (not just line-level git diff)
+- Multiple comments before sending (queue workflow)
+- Per-model attribution for agent edits
+- Side-by-side diff view
+
+## Architecture
+
+### Extension Type
+Pi extension (`~/.pi/agent/extensions/editor/index.ts`) using:
+- `ctx.ui.setWidget()` for the file browser panel
+- `ctx.ui.custom()` for the file viewer modal
+- `pi.registerShortcut()` for hotkeys
+- `pi.on("tool_result")` to track agent file modifications
+
+### External Dependencies
+- `bat` - Syntax highlighting for code files (falls back to `cat`)
+- `delta` - Pretty git diff output (falls back to `git diff`)
+- `glow` - Markdown rendering (falls back to plain text)
+- `fd` or `find` - Fast file discovery
+- `git` - Status, diff operations
+
+### UI Layout
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ [Agent output / streaming...]                               │
+│                                                             │
+├─────────────────────────────────────────────────────────────┤
+│ 📁 File Browser (widget, toggleable with Ctrl+E)            │
+│ ┌─────────────────────────────────────────────────────────┐ │
+│ │ > src/                                                  │ │
+│ │   ├── index.ts          M                               │ │
+│ │   ├── utils.ts          M                               │ │
+│ │   └── types.ts                                          │ │
+│ │ > tests/                                                │ │
+│ │   README.md             ?                               │ │
+│ └─────────────────────────────────────────────────────────┘ │
+├─────────────────────────────────────────────────────────────┤
+│ [Your input editor]                                         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+When you press Enter on a file, it opens the **File Viewer** (full-screen via `ctx.ui.custom()`):
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ src/index.ts                              [Diff: ON] [q]uit │
+├─────────────────────────────────────────────────────────────┤
+│   1 │ import { foo } from './utils';                        │
+│   2 │ import { Bar } from './types';                        │
+│   3 │                                                       │
+│   4 │+export function main() {           <- added line      │
+│   5 │+  console.log('hello');                               │
+│   6 │+}                                                     │
+│   7 │                                                       │
+│                                                             │
+├─────────────────────────────────────────────────────────────┤
+│ j/k: scroll  v: select  d: toggle diff  g: glow (md)  q: quit│
+└─────────────────────────────────────────────────────────────┘
+```
+
+Selection mode (`v` to enter):
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ src/index.ts                    [SELECT MODE] lines 4-6     │
+├─────────────────────────────────────────────────────────────┤
+│   1 │ import { foo } from './utils';                        │
+│   2 │ import { Bar } from './types';                        │
+│   3 │                                                       │
+│ ▌ 4 │ export function main() {           <- selected        │
+│ ▌ 5 │   console.log('hello');            <- selected        │
+│ ▌ 6 │ }                                  <- selected        │
+│   7 │                                                       │
+│                                                             │
+├─────────────────────────────────────────────────────────────┤
+│ j/k: extend  c: comment  Esc: cancel                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+After pressing `c`, comment dialog appears, then sends to agent:
+
+```
+Steering message sent to agent:
+
+In `src/index.ts` (lines 4-6):
+```ts
+export function main() {
+  console.log('hello');
+}
+```
+
+User comment: "This should take a name parameter and greet by name"
+```
+
+## Keybindings
+
+| Key | Context | Action |
+|-----|---------|--------|
+| `Ctrl+E` | Global | Toggle file browser widget |
+| `j/k` | File browser | Navigate files |
+| `Enter` | File browser | Open file viewer |
+| `/` | File browser | Fuzzy search |
+| `q` | File viewer | Close viewer, return to pi |
+| `j/k` | File viewer | Scroll up/down |
+| `g/G` | File viewer | Go to top/bottom |
+| `d` | File viewer | Toggle diff view |
+| `v` | File viewer | Enter selection mode |
+| `j/k` | Selection mode | Extend selection |
+| `c` | Selection mode | Add comment to selection |
+| `Esc` | Selection mode | Cancel selection |
+
+## Implementation Plan
+
+### Phase 1: File Browser Widget
+- [ ] Create extension scaffold
+- [ ] Implement file tree data structure (respect .gitignore)
+- [ ] Git status integration (modified, untracked, staged indicators)
+- [ ] Widget rendering with `ctx.ui.setWidget()`
+- [ ] Toggle hotkey `Ctrl+E`
+- [ ] Navigation (j/k, Enter to open)
+- [ ] Fuzzy search (/)
+
+### Phase 2: File Viewer
+- [ ] Full-screen viewer via `ctx.ui.custom()`
+- [ ] Syntax highlighting via `bat` (with fallback)
+- [ ] Scroll, go to line
+- [ ] Markdown rendering via `glow` (with fallback)
+- [ ] Diff toggle via `delta`/`git diff`
+
+### Phase 3: Select + Comment + Send
+- [ ] Selection mode (v to enter, j/k to extend)
+- [ ] Comment input dialog
+- [ ] Format and send as steering message via `pi.sendUserMessage()`
+- [ ] Handle mid-stream delivery (`deliverAs: "steer"`)
+
+### Phase 4: Agent Awareness (Future)
+- [ ] Track agent file modifications via `tool_result` events
+- [ ] Badge files in tree with "agent modified" indicator
+- [ ] Store modification metadata in session via `pi.appendEntry()`
+- [ ] Per-line attribution (which tool call modified which lines)
+
+## Technical Notes
+
+### File Tree Performance
+- Use `fd` if available (respects .gitignore by default, fast)
+- Fall back to `find` + manual .gitignore parsing
+- Cache tree, invalidate on file system events or manual refresh
+
+### Syntax Highlighting
+```bash
+# Check for bat
+bat --style=numbers,changes --color=always "$file"
+
+# Fallback
+cat -n "$file"
+```
+
+### Diff Display
+```bash
+# Check for delta
+git diff HEAD -- "$file" | delta --side-by-side
+
+# Fallback
+git diff HEAD -- "$file"
+```
+
+### Markdown Rendering
+```bash
+# Check for glow
+glow "$file"
+
+# Fallback: just show raw markdown with bat
+bat "$file"
+```
+
+### Git Status
+```bash
+git status --porcelain
+# M  = modified (staged)
+# _M = modified (unstaged)  
+# ?? = untracked
+# A  = added
+# D  = deleted
+```
+
+## Research Notes
+
+### Cursor Blame (Cursor 2.4, Jan 2025)
+
+Cursor introduced "Cursor Blame" which provides per-line attribution:
+- Distinguishes code from **Tab completions**, **agent runs** (broken down by model), and **human edits**
+- Gutter annotations showing who/what wrote each line
+- Addresses the "which model made this change?" problem
+- Users on Reddit specifically requested this to compare model performance
+
+**Relevance**: The "agent vs human" distinction we want for Phase 4 is similar. We can track this via `tool_result` events for `write` and `edit` tools.
+
+### tuicr (Rust, `cargo install tuicr`)
+
+GitHub: https://github.com/agavra/tuicr
+
+A TUI for reviewing AI-generated diffs like a GitHub PR:
+- **Infinite scroll diff view** - all changed files in one continuous scroll
+- **Vim keybindings** - j/k, Ctrl-d/u, g/G, {/} for file jumping
+- **Comments** - file-level or line-level with types (Note, Suggestion, Issue, Praise)
+- **Visual mode** - select line ranges with v/V, comment on multiple lines
+- **Session persistence** - reviews auto-save and reload
+- **Clipboard export** - structured Markdown optimized for LLM consumption
+- Supports git, jujutsu, mercurial
+
+**Sample export format**:
+```markdown
+In `src/index.ts` (lines 4-6):
+```ts
+export function main() {
+  console.log('hello');
+}
+```
+[Issue] This should take a name parameter
+```
+
+**Relevance**: The "select + comment + export for LLM" workflow is exactly what we want. Could either integrate tuicr or replicate the pattern.
+
+### critique (Bun/TypeScript, `bunx critique`)
+
+GitHub: https://github.com/remorses/critique
+
+Beautiful terminal diff viewer:
+- **Word-level diff** - not just line-level, shows exactly what changed within lines
+- **Split view** - side-by-side comparison
+- **Syntax highlighting** - via tree-sitter
+- **Watch mode** - `critique --watch` auto-refreshes on file changes
+- **AI-powered explanation** - `critique review` uses Claude Code or OpenCode to explain changes
+- **Web preview** - `critique web` generates shareable URL
+- **Lazygit integration** - can be used as custom pager
+- **Branch comparison** - `critique main feature-branch` for PR-style diffs
+
+Commands:
+```bash
+critique              # View unstaged changes
+critique --staged     # View staged changes
+critique HEAD         # View last commit
+critique --watch      # Auto-refresh on changes
+critique review       # AI-powered explanation
+critique web          # Generate shareable web preview
+```
+
+**Relevance**: Word-level diff is important for prose/markdown review. Could shell out to critique for diff viewing, or adopt their approach.
+
+### Integration Options Considered
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| Shell out to tuicr/critique | Battle-tested, feature-rich | Context switch, lose pi output visibility |
+| Embed in pi widget | No context switch, agent-aware | More work, rebuild existing features |
+| Hybrid (tree in pi, diff in external) | Best of both | Still some context switch |
+
+**Decision**: Build file browser in pi (stays visible), use external tools for complex diff viewing if user wants, but provide basic in-pi diff view for quick checks.
+
+### tuicr Integration Analysis
+
+**Value**: High - tuicr was built specifically for the "review AI changes and send feedback" workflow we want.
+
+**Key Features**:
+- Clipboard export in LLM-optimized markdown format
+- Comment types (Note, Suggestion, Issue, Praise)
+- Session persistence (reviews survive restarts)
+- Visual mode for multi-line selection
+
+**Integration Approach**:
+```bash
+# User triggers review mode from pi
+# 1. Pi extension spawns tuicr
+tuicr
+
+# 2. User reviews, adds comments, presses :wq or y (copy to clipboard)
+# 3. tuicr exits, clipboard contains structured review
+
+# 4. Pi extension reads clipboard and sends to agent
+pbpaste | pi.sendUserMessage(...)
+```
+
+**Feasibility**: Medium
+- tuicr is a full TUI that takes over the terminal (can't see pi output while reviewing)
+- No stdout/file output mode - only clipboard (would need to read clipboard after exit)
+- User must quit tuicr to return to pi
+- But: the workflow is natural - "let me review these changes" → review → return with feedback
+
+**Proposed UX**:
+```
+You: [working with agent]
+Agent: [makes changes to multiple files]
+You: /review                          # or Ctrl+R
+     [tuicr opens, shows all unstaged changes]
+     [user navigates, adds comments]
+     [user presses :wq]
+     [tuicr exits, review copied to clipboard]
+     [pi reads clipboard, sends as steering message]
+Agent: [receives structured feedback, addresses comments]
+```
+
+**Implementation**:
+```typescript
+pi.registerCommand("review", {
+  description: "Open tuicr to review changes, send feedback to agent",
+  handler: async (args, ctx) => {
+    // Check if tuicr is installed
+    if (!hasCommand("tuicr")) {
+      ctx.ui.notify("Install tuicr: brew install agavra/tap/tuicr", "error");
+      return;
+    }
+
+    // Spawn tuicr (takes over terminal)
+    const result = await ctx.exec("tuicr", [], { stdio: "inherit" });
+
+    // Read clipboard after tuicr exits
+    const review = execSync("pbpaste", { encoding: "utf-8" });
+
+    if (review.includes("## Review Summary") || review.includes("```")) {
+      // Looks like a tuicr export, send to agent
+      pi.sendUserMessage(review, { deliverAs: "steer" });
+      ctx.ui.notify("Review sent to agent", "success");
+    }
+  },
+});
+```
+
+### critique Integration Analysis
+
+**Value**: High for diff viewing, medium for review workflow (no built-in comment system).
+
+**Key Features**:
+- Word-level diff (great for prose/markdown)
+- `--watch` mode for live updates
+- `--stdin` for piping (lazygit integration)
+- `critique review` uses AI to explain changes
+- `critique web` for shareable URLs
+
+**Integration Approaches**:
+
+1. **As diff viewer only** (simple):
+   ```bash
+   # View specific file diff
+   critique --filter "src/index.ts"
+
+   # Watch mode while agent works
+   critique --watch
+   ```
+
+2. **As lazygit pager** (if user has lazygit):
+   ```yaml
+   # ~/.config/lazygit/config.yml
+   git:
+     paging:
+       pager: critique --stdin
+   ```
+
+3. **Web preview for sharing** (useful for async review):
+   ```bash
+   critique web --title "Agent changes for review"
+   # Returns URL like critique.work/v/abc123
+   ```
+
+**Feasibility**: High
+- `--watch` mode is ideal for "keep an eye on changes while agent works"
+- No comment system, but pairs well with our in-pi select+comment flow
+- Requires Bun (not Node.js)
+
+**Proposed UX**:
+```
+You: /diff                            # Quick diff view
+     [critique opens showing current changes]
+     [user reviews, presses q to quit]
+     [returns to pi]
+
+You: /diff --watch                    # Live watch mode
+     [critique opens in watch mode]
+     [updates as agent modifies files]
+     [user presses q when done]
+```
+
+### Recommended Integration Strategy
+
+**Phase 1 (MVP)**: Built-in basic diff
+- Simple `git diff` via `delta` in pi's file viewer
+- No external dependencies required
+- Good enough for quick checks
+
+**Phase 2**: Optional tuicr integration
+- `/review` command spawns tuicr
+- Clipboard capture sends review to agent
+- Requires `brew install agavra/tap/tuicr`
+
+**Phase 3**: Optional critique integration
+- `/diff` command spawns critique
+- `/diff --watch` for live monitoring
+- Requires Bun + `bun install -g critique`
+
+**Phase 4**: Deep integration
+- Track which tool calls modified which files
+- Pass this metadata to tuicr/critique
+- Show "agent modified" vs "human modified" in diff view
+
+### Tools for Syntax Highlighting / Rendering
+
+| Tool | Purpose | Install |
+|------|---------|---------|
+| `bat` | Syntax highlighting, line numbers | `brew install bat` |
+| `delta` | Git diff beautifier, side-by-side | `brew install git-delta` |
+| `glow` | Markdown rendering | `brew install glow` |
+| `fd` | Fast file finder (respects .gitignore) | `brew install fd` |
+
+These are standalone tools. This extension aims to provide similar functionality *inside* Pi without context switching, while optionally leveraging these tools for rendering.
+
+### Pi Extension Capabilities Used
+- `ctx.ui.setWidget()` - Persistent widget above/below editor
+- `ctx.ui.custom()` - Full-screen custom TUI component
+- `pi.registerShortcut()` - Custom keybindings
+- `pi.sendUserMessage()` - Send steering messages to agent
+- `pi.on("tool_result")` - Track file modifications
+- `pi.appendEntry()` - Persist state in session
+
+## Open Questions
+
+1. **Widget height** - Fixed height or percentage of terminal? Collapsible?
+2. **Multi-file comments** - Queue comments across files before sending, or send immediately?
+3. **Diff base** - Always vs HEAD, or configurable (vs staged, vs specific commit)?
+4. **File watcher** - Auto-refresh tree when files change, or manual refresh?

package/README.md

@@ -0,0 +1,120 @@
+# files-widget
+
+In-terminal file browser and viewer for Pi. Navigate files, view diffs, select code, and send comments to the agent without leaving the terminal.
+
+![Demo](demo.svg)
+
+## Install
+
+**Quick install (Pi package manager):**
+
+```bash
+pi install npm:@tmustier/pi-files-widget
+```
+
+```bash
+pi install git:github.com/tmustier/pi-extensions
+```
+
+Then add to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "packages": [
+    {
+      "source": "git:github.com/tmustier/pi-extensions",
+      "extensions": ["files-widget/index.ts"]
+    }
+  ]
+}
+```
+
+**Local clone:**
+
+Add to your Pi extensions list:
+
+```json
+{
+  "extensions": [
+    "~/pi-extensions/files-widget"
+  ]
+}
+```
+
+If you prefer symlinking into `~/.pi/agent/extensions`:
+
+```bash
+ln -sfn ~/pi-extensions/files-widget ~/.pi/agent/extensions/files-widget
+```
+
+Then reference it in your settings:
+
+```json
+{
+  "extensions": [
+    "~/.pi/agent/extensions/files-widget"
+  ]
+}
+```
+
+## Dependencies (recommended)
+
+```bash
+brew install bat git-delta glow
+```
+
+- `bat`: syntax highlighting
+- `delta`: formatted diffs
+- `glow`: markdown rendering
+
+If any are missing, the extension will notify you at session start and gracefully fall back to plain rendering.
+
+## Commands
+
+- `/files` - open the file browser
+- `/review` - open tuicr review flow
+- `/diff` - open critique (bunx critique)
+
+### Review/Diff Dependencies
+
+```bash
+brew install agavra/tap/tuicr
+brew install oven-sh/bun/bun
+```
+
+- `tuicr` is required for `/review`
+- `bun` is required for `/diff`
+
+If missing, `/review` or `/diff` will show a clear install prompt.
+
+## Browser Keybindings
+
+- `j/k` or `↑/↓`: move
+- `Enter`: open file / expand folder
+- `h/l` or `←/→`: collapse/expand folder
+- `PgUp/PgDn`: page up/down
+- `c`: toggle changed-only view
+- `]` / `[`: next/prev changed file
+- `/`: search (type to filter, `Esc` to exit)
+- `+` / `-`: increase/decrease browser height
+- `q`: close
+
+## Viewer Keybindings
+
+- `j/k` or `↑/↓`: scroll
+- `PgUp/PgDn`: page up/down
+- `g/G`: top/bottom
+- `d`: toggle diff (tracked files only)
+- `/`: search (type to search)
+- `n` / `N`: next/prev match
+- `v`: select mode (line selection)
+- `c`: comment on selected lines (inline prompt)
+- `]` / `[`: next/prev changed file
+- `+` / `-`: increase/decrease viewer height
+- `q`: back to browser
+
+## Notes
+
+- Untracked files show as `[UNTRACKED]` and open in normal view.
+- Folder LOCs are shown only when the folder is collapsed (expanded folders would duplicate counts).
+- Git status refreshes every 3 seconds while `/files` is open.