vibe-reader 0.1.0__tar.gz

vibe_reader-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

vibe_reader-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.log

vibe_reader-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

vibe_reader-0.1.0/AGENTS.md

@@ -0,0 +1,35 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `backend/`: FastAPI routers (`main.py`, `tmux.py`, `files.py`) and any new backend utilities.
+- `frontend/`: eink UI assets (`index.html`, `app.js`, `styles.css`) with vanilla JS and utility-first CSS.
+- `src/vibe_reader/`: packaging glue and shared Python modules; keep type markers here.
+- `tests/`: mirror backend modules with `test_*` files (e.g., `tests/test_tmux.py`, `tests/test_files.py`).
+
+## Build, Test, and Development Commands
+- `uv sync`: install project dependencies (add `HTTP(S)_PROXY` env vars when required).
+- `uv run uvicorn backend.main:app --host 0.0.0.0 --port 28000 --reload`: local dev server with hot reload.
+- `uv run uvicorn backend.main:app --host 0.0.0.0 --port 28000`: production preview.
+- `uv run pytest`: execute the test suite once pytest is listed under dev dependencies.
+
+## Coding Style & Naming Conventions
+- Python: 3.10+, four-space indents, type hints, and FastAPI error handling via `HTTPException`.
+- JavaScript: keep DOM refs camelCase at the top of `frontend/app.js`; stay framework-free.
+- CSS: high-contrast, animation-free styles optimized for eink; prefer reusable utility classes.
+- Share helpers across routers via dedicated modules in `backend/`.
+
+## Testing Guidelines
+- Use `pytest` with `pytest-asyncio` for coroutine coverage; mock `libtmux.Server`.
+- Target ≥80% coverage on new paths; assert edge cases (empty tmux sessions, missing panes, binary file rejection).
+- Name tests `test_*` and keep fixtures local when possible.
+
+## Commit & Pull Request Guidelines
+- Commit subjects: imperative mood (“Add scrollback scrollbar”); include brief bodies for behavior changes.
+- Reference issues with `Fixes #123` when applicable.
+- PRs should summarize intent, list validation steps (`uv run pytest`, tmux capture checks, file browser smoke tests), and include eink UI screenshots for frontend tweaks.
+- Request cross-review when touching both backend and frontend layers.
+
+## Security & Configuration Tips
+- Expose the backend only behind VPN/SSH; never ship tmux without access controls.
+- Keep proxy env vars out of committed scripts.
+- Document new flags in `README.md` and surface user-configurable options in the Config view.

vibe_reader-0.1.0/CLAUDE.md

@@ -0,0 +1,99 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Vibe Reader is a web application for reading terminal output and code files on eink devices during vibe coding sessions. It provides eink-optimized UI with scrollback history, visual scrollbars, and configuration options.
+
+## Development Commands
+
+### Running the Server
+
+```bash
+# Development with auto-reload
+uv run uvicorn backend.main:app --host 0.0.0.0 --port 28000 --reload
+
+# Production
+uv run uvicorn backend.main:app --host 0.0.0.0 --port 28000
+```
+
+### Dependency Management
+
+If you encounter network issues, use the proxy:
+```bash
+HTTP_PROXY=http://127.0.0.1:9082 HTTPS_PROXY=http://127.0.0.1:9082 uv sync
+```
+
+## Architecture
+
+### Backend (FastAPI + libtmux)
+
+- **Modular routers**:
+  - `backend/main.py` - Main app with router includes
+  - `backend/tmux.py` - Tmux endpoints (APIRouter)
+  - `backend/files.py` - File browser endpoints (APIRouter)
+- **Static file serving**: FastAPI serves frontend from `/frontend` directory at `/static`
+- **Tmux integration**: Uses libtmux library to access tmux server with 1000-line scrollback
+
+### Frontend (Vanilla JS)
+
+- **Single-page application**: All UI in `frontend/index.html`
+- **Three views**: Tmux, Files, and Config (toggle via navbar)
+- **Layout**: Collapsible sidebar + main content area + visual scrollbars
+- **Config persistence**: localStorage for scrollback lines and font size settings
+- **Eink optimizations**: No animations, high contrast, instant updates (`scroll-behavior: auto`, `transition: none`)
+
+### Critical Implementation Details
+
+**Tmux Window/Pane Indexing**:
+- Tmux uses actual indices (can be non-contiguous: 2, 3, 4, 5, 6)
+- DO NOT use array positions to access windows/panes
+- Always iterate to find matching `window.index` or `pane.index`
+- See `backend/tmux.py:47-94` for correct implementation
+
+**Tmux Scrollback History**:
+- Backend captures last N lines (default 1000, configurable)
+- Uses `pane.capture_pane(start='-1000')` to get scrollback
+- Returns only `content` string
+
+**Scrollbar Implementation**:
+- Traditional scrollbar design with thumb showing viewport size
+- Tmux: Bar represents total scrollback, thumb shows viewport position
+- Files: Bar represents file length, thumb shows viewport position
+- Position calculation uses scroll ratio: `currentScrollRatio = scrollTop / maxScrollTop`
+- Thumb position: `thumbTop = (scrollbarHeight - thumbHeight) * currentScrollRatio`
+
+**Single-pane Window Handling**:
+- Windows with one pane show window name as clickable (no pane list)
+- Detect via `window.panes.length === 1` in frontend
+- Apply `.single-pane` class for special styling
+
+**Auto-scroll Behavior**:
+- Tmux: Auto-scroll to end of content when enabled, preserve scroll position when disabled
+- File content: Always scrolls to top when loaded
+- Manual scrolling: Page up/down buttons scroll 90% of viewport height
+
+**Configuration**:
+- Settings stored in localStorage as JSON
+- `scrollbackLines`: 100-10000 (default 1000)
+- `fontSize`: 12-20px (default 14px)
+- Applied dynamically via `element.style.fontSize`
+
+## API Endpoints
+
+### Tmux (backend/tmux.py)
+- `GET /api/tmux/tree` - Returns full session/window/pane hierarchy
+- `GET /api/tmux/pane/{session}/{window}/{pane}` - Captures pane content with scrollback
+  - Returns: `content` (string)
+
+### Files (backend/files.py)
+- `GET /api/files?path=<path>` - Lists directory contents
+- `GET /api/files/content?path=<path>` - Returns file content
+
+## Design Constraints
+
+1. **Eink-first**: No animations, transitions, or smooth scrolling
+2. **Single-page viewport**: All content must fit without page scrolling
+3. **High contrast**: Black/white color scheme only
+4. **Space-efficient**: Collapsible sidebar, compact controls

vibe_reader-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: vibe-reader
+Version: 0.1.0
+Summary: Add your description here
+Author-email: PsychArch <PsychArch@github.com>
+Requires-Python: >=3.13
+Requires-Dist: fastapi
+Requires-Dist: libtmux
+Requires-Dist: markdown
+Requires-Dist: pygments
+Requires-Dist: uvicorn
+Provides-Extra: dev
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Vibe Reader
+
+Read terminal output and code files on your eink device. Designed for comfortable reading during vibe coding sessions.
+
+## Features
+
+### Tmux Integration
+- Browse and view tmux session/window/pane output
+- **1000-line scrollback history** capture (configurable)
+- **Smart auto-scroll**: Follow content end or freeze position
+- **Visual scrollbar**: Shows position in scrollback and viewport size
+
+### File Browser
+- Navigate directories and view file contents
+- Visual scrollbar showing file length and current position
+- Server-side syntax highlighting for code and Markdown (tables supported)
+
+### Configuration
+- Adjustable scrollback lines (100-10000)
+- Font size selection (12-20px)
+- Settings persist via localStorage
+
+### Eink-Optimized UI
+- High contrast, large fonts, no animations
+- Collapsible sidebar, compact window display
+- Page up/down buttons for manual scrolling
+- Single-page design that fits viewport
+
+## Quick Start
+
+```bash
+# Install dependencies (use proxy if needed)
+HTTP_PROXY=http://127.0.0.1:9082 HTTPS_PROXY=http://127.0.0.1:9082 uv sync
+
+# Start server (restricts file browsing to current directory by default)
+uv run uvicorn backend.main:app --host 0.0.0.0 --port 28000
+
+# Optional: Set custom project root for file browser
+VIBE_READER_ROOT=/path/to/project uv run uvicorn backend.main:app --host 0.0.0.0 --port 28000
+
+# Open on your eink device
+# Navigate to: http://YOUR_SERVER_IP:28000
+```
+
+## Usage
+
+### Tmux View
+- Click **☰** to toggle sidebar
+- Select session → window (→ pane if multiple)
+- Click **Refresh** to update content
+- Use **Page ↑/↓** for manual scrolling
+- Toggle **Auto↓** to enable/disable auto-scroll to end
+- **Scrollbar** shows your position in scrollback history
+
+### Files View
+- Enter path or browse directories
+- Click folders to navigate, files to view
+- **Page ↑/↓** for scrolling
+- **Scrollbar** shows file length and current position
+- **Security**: File browsing is restricted to the project root (configurable via `VIBE_READER_ROOT`)
+- **File size limit**: Maximum 10MB per file
+
+### Config View
+- Adjust scrollback lines (100-10000, default 1000)
+- Change font size (12-20px, default 14px)
+- Set auto-refresh interval (0-60 seconds, default 5s)
+- Click **Save Settings** to persist changes
+
+## Technical Details
+
+**Backend**: FastAPI + libtmux
+**Frontend**: Vanilla JS, eink-optimized CSS
+**Package Manager**: uv
+
+### Environment Variables
+
+- `VIBE_READER_ROOT`: Sets the root directory for file browsing (default: current working directory)
+  - Files outside this directory cannot be accessed
+  - Use this to restrict file browsing to a specific project
+
+### API Endpoints
+
+**Tmux:**
+- `GET /api/tmux/tree` - List all sessions/windows/panes
+- `GET /api/tmux/pane/{session}/{window}/{pane}?scrollback=1000` - Get pane content with configurable scrollback
+
+**Files:**
+- `GET /api/files?path=.` - List directory contents (relative to project root)
+- `GET /api/files/content?path=file.txt` - Render file content (max 10MB) with fields `path`, `render_mode`, `html`, and `metadata`
+
+## Design Principles
+
+1. **Eink-first**: No animations, high contrast, instant updates
+2. **Minimal overhead**: Direct tmux capture, simple file operations
+3. **Space-efficient**: Every pixel counts on small eink screens
+4. **Single-page**: All content fits viewport, reduces refresh artifacts
+
+## Project Structure
+
+```
+vibe-reader/
+   backend/
+      main.py          # FastAPI app with router includes
+      tmux.py          # Tmux endpoints
+      files.py         # File browser endpoints
+   frontend/
+      index.html       # Single-page UI (Tmux/Files/Config views)
+      styles.css       # Eink-optimized styles
+      app.js           # Client logic with scrollbar management
+   pyproject.toml       # uv configuration
+```
+
+
+## Requirements
+
+- Python 3.13+
+- tmux (for tmux viewing feature)
+- Modern browser on eink device
+
+## License
+
+MIT

vibe_reader-0.1.0/README.md

@@ -0,0 +1,122 @@
+# Vibe Reader
+
+Read terminal output and code files on your eink device. Designed for comfortable reading during vibe coding sessions.
+
+## Features
+
+### Tmux Integration
+- Browse and view tmux session/window/pane output
+- **1000-line scrollback history** capture (configurable)
+- **Smart auto-scroll**: Follow content end or freeze position
+- **Visual scrollbar**: Shows position in scrollback and viewport size
+
+### File Browser
+- Navigate directories and view file contents
+- Visual scrollbar showing file length and current position
+- Server-side syntax highlighting for code and Markdown (tables supported)
+
+### Configuration
+- Adjustable scrollback lines (100-10000)
+- Font size selection (12-20px)
+- Settings persist via localStorage
+
+### Eink-Optimized UI
+- High contrast, large fonts, no animations
+- Collapsible sidebar, compact window display
+- Page up/down buttons for manual scrolling
+- Single-page design that fits viewport
+
+## Quick Start
+
+```bash
+# Install dependencies (use proxy if needed)
+HTTP_PROXY=http://127.0.0.1:9082 HTTPS_PROXY=http://127.0.0.1:9082 uv sync
+
+# Start server (restricts file browsing to current directory by default)
+uv run uvicorn backend.main:app --host 0.0.0.0 --port 28000
+
+# Optional: Set custom project root for file browser
+VIBE_READER_ROOT=/path/to/project uv run uvicorn backend.main:app --host 0.0.0.0 --port 28000
+
+# Open on your eink device
+# Navigate to: http://YOUR_SERVER_IP:28000
+```
+
+## Usage
+
+### Tmux View
+- Click **☰** to toggle sidebar
+- Select session → window (→ pane if multiple)
+- Click **Refresh** to update content
+- Use **Page ↑/↓** for manual scrolling
+- Toggle **Auto↓** to enable/disable auto-scroll to end
+- **Scrollbar** shows your position in scrollback history
+
+### Files View
+- Enter path or browse directories
+- Click folders to navigate, files to view
+- **Page ↑/↓** for scrolling
+- **Scrollbar** shows file length and current position
+- **Security**: File browsing is restricted to the project root (configurable via `VIBE_READER_ROOT`)
+- **File size limit**: Maximum 10MB per file
+
+### Config View
+- Adjust scrollback lines (100-10000, default 1000)
+- Change font size (12-20px, default 14px)
+- Set auto-refresh interval (0-60 seconds, default 5s)
+- Click **Save Settings** to persist changes
+
+## Technical Details
+
+**Backend**: FastAPI + libtmux
+**Frontend**: Vanilla JS, eink-optimized CSS
+**Package Manager**: uv
+
+### Environment Variables
+
+- `VIBE_READER_ROOT`: Sets the root directory for file browsing (default: current working directory)
+  - Files outside this directory cannot be accessed
+  - Use this to restrict file browsing to a specific project
+
+### API Endpoints
+
+**Tmux:**
+- `GET /api/tmux/tree` - List all sessions/windows/panes
+- `GET /api/tmux/pane/{session}/{window}/{pane}?scrollback=1000` - Get pane content with configurable scrollback
+
+**Files:**
+- `GET /api/files?path=.` - List directory contents (relative to project root)
+- `GET /api/files/content?path=file.txt` - Render file content (max 10MB) with fields `path`, `render_mode`, `html`, and `metadata`
+
+## Design Principles
+
+1. **Eink-first**: No animations, high contrast, instant updates
+2. **Minimal overhead**: Direct tmux capture, simple file operations
+3. **Space-efficient**: Every pixel counts on small eink screens
+4. **Single-page**: All content fits viewport, reduces refresh artifacts
+
+## Project Structure
+
+```
+vibe-reader/
+   backend/
+      main.py          # FastAPI app with router includes
+      tmux.py          # Tmux endpoints
+      files.py         # File browser endpoints
+   frontend/
+      index.html       # Single-page UI (Tmux/Files/Config views)
+      styles.css       # Eink-optimized styles
+      app.js           # Client logic with scrollbar management
+   pyproject.toml       # uv configuration
+```
+
+
+## Requirements
+
+- Python 3.13+
+- tmux (for tmux viewing feature)
+- Modern browser on eink device
+
+## License
+
+MIT

vibe_reader-0.1.0/backend/__init__.py

@@ -0,0 +1 @@
+"""Backend package for FastAPI routers."""

vibe_reader-0.1.0/backend/files.py

@@ -0,0 +1,100 @@
+from fastapi import APIRouter, HTTPException
+from pathlib import Path
+import os
+
+from backend.rendering import render_text_content
+
+router = APIRouter(prefix="/api/files", tags=["files"])
+
+# Maximum file size to read (10MB)
+MAX_FILE_SIZE = 10 * 1024 * 1024
+
+def get_project_root() -> Path:
+    """Get configurable project root. Defaults to current working directory."""
+    # Can be configured via environment variable
+    root = os.getenv("VIBE_READER_ROOT", os.getcwd())
+    return Path(root).resolve()
+
+def resolve_and_validate_path(path: str, must_be_dir: bool = False, must_be_file: bool = False) -> Path:
+    """Resolve path and validate it's within project root."""
+    project_root = get_project_root()
+    target_path = Path(path).resolve()
+
+    # Security check: ensure path is within project root
+    try:
+        target_path.relative_to(project_root)
+    except ValueError:
+        raise HTTPException(status_code=403, detail="Access denied: path outside project root")
+
+    if not target_path.exists():
+        raise HTTPException(status_code=404, detail="Path not found")
+
+    if must_be_dir and not target_path.is_dir():
+        raise HTTPException(status_code=400, detail="Path is not a directory")
+
+    if must_be_file and target_path.is_dir():
+        raise HTTPException(status_code=400, detail="Path is a directory")
+
+    return target_path
+
+@router.get("")
+async def list_files(path: str = "."):
+    """List files in a directory"""
+    try:
+        target_path = resolve_and_validate_path(path, must_be_dir=True)
+        project_root = get_project_root()
+
+        files = []
+        for item in sorted(target_path.iterdir()):
+            # Return paths relative to project root for display
+            try:
+                relative_path = item.relative_to(project_root)
+                display_path = str(relative_path)
+            except ValueError:
+                display_path = str(item)
+
+            files.append({
+                "name": item.name,
+                "path": display_path,
+                "is_dir": item.is_dir()
+            })
+        return files
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.get("/content")
+async def get_file_content(path: str):
+    """Get content of a file"""
+    try:
+        target_path = resolve_and_validate_path(path, must_be_file=True)
+        project_root = get_project_root()
+
+        # Check file size before reading
+        file_size = target_path.stat().st_size
+        if file_size > MAX_FILE_SIZE:
+            raise HTTPException(status_code=400, detail=f"File too large (max {MAX_FILE_SIZE // 1024 // 1024}MB)")
+
+        content = target_path.read_text()
+        render_result = render_text_content(target_path, content)
+
+        # Return path relative to project root
+        try:
+            relative_path = target_path.relative_to(project_root)
+            display_path = str(relative_path)
+        except ValueError:
+            display_path = str(target_path)
+
+        return {
+            "path": display_path,
+            "render_mode": render_result.mode,
+            "html": render_result.html,
+            "metadata": render_result.metadata,
+        }
+    except UnicodeDecodeError:
+        raise HTTPException(status_code=400, detail="Cannot read binary file")
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

vibe_reader-0.1.0/backend/main.py

@@ -0,0 +1,26 @@
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+
+from backend.tmux import router as tmux_router
+from backend.files import router as files_router
+
+app = FastAPI()
+
+# Include routers
+app.include_router(tmux_router)
+app.include_router(files_router)
+
+# Serve frontend
+app.mount("/static", StaticFiles(directory="frontend"), name="static")
+
+@app.get("/")
+async def root():
+    return FileResponse("frontend/index.html")
+
+def main():
+    import uvicorn
+    uvicorn.run("backend.main:app", host="0.0.0.0", port=28000)
+
+if __name__ == "__main__":
+    main()