forestui 0.9.0__tar.gz

forestui-0.9.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+permissions:
+  id-token: write
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  release:
+    name: Build and Publish
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Set version from GITHUB_REF
+        run: |
+          # GITHUB_REF is refs/tags/v1.2.3 - extract "1.2.3"
+          echo "GITHUB_REF: ${{ github.ref }}"
+          export VERSION=$(echo ${{ github.ref }} | sed -e 's,.*/\(.*\),\1,' -e 's/^v//')
+          echo "Setting version to $VERSION"
+          sed -i "s/^version = \".*\"/version = \"$VERSION\"/" pyproject.toml
+          echo "======================================"
+          echo "Version line in pyproject.toml:"
+          grep "^version" pyproject.toml
+          echo "======================================"
+
+      - name: Build wheels and source tarball
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@v1.13.0

forestui-0.9.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

forestui-0.9.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.11
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

forestui-0.9.0/.python-version

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

forestui-0.9.0/CLAUDE.md

@@ -0,0 +1,200 @@
+# CLAUDE.md - AI Development Guidelines
+
+This file provides context for AI assistants (like Claude) working on forestui.
+
+## Project Overview
+
+forestui is a terminal UI for managing Git worktrees, built with Python and Textual. It's designed to run inside tmux and provides a cohesive experience for developers managing multiple worktrees.
+
+## Tech Stack
+
+- **Python 3.14+** with strict type hints (mypy strict mode)
+- **Textual 7.2+** for the TUI framework
+- **Pydantic 2.12+** for data models and validation
+- **Click 8.1+** for CLI parsing
+- **uv** for package management
+
+## Project Structure
+
+```
+forestui/
+├── forestui/
+│   ├── __init__.py          # Package init, version
+│   ├── __main__.py           # Module entry point
+│   ├── app.py                # Main Textual application
+│   ├── cli.py                # Click CLI with --self-update
+│   ├── models.py             # Pydantic data models
+│   ├── state.py              # Application state management
+│   ├── theme.py              # CSS styling
+│   ├── components/
+│   │   ├── modals.py         # Modal dialogs (settings, add repo, etc.)
+│   │   ├── sidebar.py        # Repository/worktree sidebar
+│   │   ├── repository_detail.py
+│   │   └── worktree_detail.py
+│   └── services/
+│       ├── settings.py       # User preferences + runtime forest path
+│       ├── git.py            # Async git operations
+│       ├── claude_session.py # Claude Code session tracking
+│       └── tmux.py           # tmux window management
+├── pyproject.toml            # Project config, dependencies
+├── Makefile                  # Development commands
+├── install.sh                # Installation script
+└── README.md
+```
+
+## Development Commands
+
+```bash
+make lint       # Run ruff linter
+make typecheck  # Run mypy type checker
+make check      # Run both lint and typecheck
+make format     # Format code with ruff
+make dev        # Install dev dependencies
+make run        # Run the app
+make clean      # Clean build artifacts
+```
+
+Always run `make check` before committing changes.
+
+## Code Conventions
+
+### Type Hints
+- All functions must have type hints (mypy strict mode)
+- Use `from __future__ import annotations` for forward references
+- Prefer `X | None` over `Optional[X]`
+
+### Imports
+- Use absolute imports: `from forestui.services.git import GitService`
+- Imports are auto-sorted by ruff (isort rules)
+
+### Textual Patterns
+- Components emit `Message` classes for parent communication
+- Use `@work` decorator for async operations that update UI
+- CSS is defined in `theme.py` as `APP_CSS`
+
+### Async Operations & Reactive UI
+
+**IMPORTANT:** Never block the UI with slow operations. The app must start instantly.
+
+For any operation that may take time (CLI calls, network requests, file I/O):
+1. Render UI immediately with a loading state ("Loading...", "Checking...")
+2. Dispatch work to a background task using `@work` decorator
+3. When the task completes, update the UI reactively
+
+Example pattern:
+```python
+# In compose(), show loading state:
+yield Label("Loading...", id="my-loading")
+
+# In on_mount() or elsewhere, dispatch background work:
+self._fetch_data()
+
+@work
+async def _fetch_data(self) -> None:
+    data = await slow_operation()
+    # Update UI when ready
+    self.query_one("#my-loading").update(f"Result: {data}")
+```
+
+This applies to:
+- External CLI integrations (gh, git, etc.)
+- Network requests
+- File system operations that may be slow
+- Any operation that could fail or hang
+
+The UI should always remain responsive. Users should never see the app freeze.
+
+### Services
+- Services are singletons accessed via `get_*_service()` functions
+- State is persisted automatically via `_save_state()` methods
+
+## Key Design Decisions
+
+### tmux Requirement
+forestui requires tmux and will auto-exec into a tmux session if not already inside one. This enables:
+- TUI editors opening in tmux windows
+- Session persistence
+- Fast switching between editor/app/claude windows
+
+### Multi-Forest Support
+The forest directory is a CLI argument, not a setting:
+```bash
+forestui ~/forest      # default
+forestui ~/work        # different forest
+```
+
+Each forest has its own `.forestui-config.json` state file.
+
+### Coexistence with forest (macOS)
+- forestui uses `.forestui-config.json`
+- forest uses `.forest-config.json`
+- Both can share the same `~/forest` directory safely
+
+## Common Tasks
+
+### Adding a New Service
+1. Create `forestui/services/myservice.py`
+2. Implement singleton pattern with `get_myservice()` function
+3. Export from `forestui/services/__init__.py`
+
+### Adding a New Component
+1. Create `forestui/components/mycomponent.py`
+2. Define `Message` classes for events
+3. Handle messages in `app.py` with `on_mycomponent_*` methods
+
+### Adding a New CLI Option
+1. Add to `@click.option` in `forestui/cli.py`
+2. Handle in the `main()` function
+
+### Modifying Settings
+1. Update `Settings` model in `models.py`
+2. Update `SettingsModal` in `components/modals.py`
+3. Settings are auto-persisted to `~/.config/forestui/settings.json`
+
+## Testing
+
+Currently no test suite. When adding tests:
+- Use pytest
+- Place tests in `tests/` directory
+- Add pytest to dev dependencies
+
+## Versioning
+
+Version is defined in **both** `forestui/__init__.py` and `pyproject.toml`:
+```python
+__version__ = "0.1.0"
+```
+
+**IMPORTANT:** The `main` branch represents the release. Every feature, fix, or change merged to `main` **must** include a version bump in both files:
+- **Patch** (0.0.X): Bug fixes, dead code removal, minor cleanup
+- **Minor** (0.X.0): New features, enhancements
+- **Major** (X.0.0): Breaking changes
+
+This is required for `--self-update` to work correctly - it compares the local version against the remote to detect updates. If you forget to bump the version, users won't see the update.
+
+### Workflow: Test Before Commit
+
+**Do NOT bump the version, commit, or push until the user has tested and approved the changes.**
+
+Every commit to `main` with a bumped version is an actual release that will propagate to all users via `--self-update`. The workflow should be:
+
+1. Make code changes
+2. Run `make check` to verify lint/typecheck pass (do this BEFORE bumping version - if linter reformats code, you don't want to bump twice)
+3. **Ask the user to test the changes** before proceeding
+4. Bump version in both `forestui/__init__.py` and `pyproject.toml`
+5. Commit and push
+
+This keeps a human in the loop for quality control before releasing.
+
+## Git Commits
+
+- Do NOT include `Co-Authored-By` attribution
+- Do NOT include "Generated with Claude Code" footer
+- Write clear, concise commit messages
+
+## References
+
+- [forest (macOS)](https://github.com/ricwo/forest) - Original inspiration
+- [Textual Documentation](https://textual.textualize.io/)
+- [Pydantic Documentation](https://docs.pydantic.dev/)
+- [Click Documentation](https://click.palletsprojects.com/)

forestui-0.9.0/Makefile

@@ -0,0 +1,46 @@
+.PHONY: lint typecheck check format install dev clean
+
+# Run ruff linter
+lint:
+	uv run ruff check forestui/
+
+# Run mypy type checker
+typecheck:
+	uv run mypy forestui/
+
+# Run all checks (lint + typecheck)
+check: lint typecheck
+
+# Format code with ruff
+format:
+	uv run ruff format forestui/
+	uv run ruff check --fix forestui/
+
+# Install the package locally
+install:
+	uv pip install -e .
+
+# Install with dev dependencies
+dev:
+	uv sync --group dev
+
+# Clean build artifacts
+clean:
+	rm -rf build/ dist/ *.egg-info/ .mypy_cache/ .ruff_cache/
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+
+# Run the app
+run:
+	uv run forestui
+
+# Show help
+help:
+	@echo "Available targets:"
+	@echo "  make lint      - Run ruff linter"
+	@echo "  make typecheck - Run mypy type checker"
+	@echo "  make check     - Run all checks (lint + typecheck)"
+	@echo "  make format    - Format code with ruff"
+	@echo "  make install   - Install package locally"
+	@echo "  make dev       - Install with dev dependencies"
+	@echo "  make clean     - Clean build artifacts"
+	@echo "  make run       - Run the app"

forestui-0.9.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: forestui
+Version: 0.9.0
+Summary: A Terminal UI for managing Git worktrees
+Author: cadu
+Keywords: git,terminal,textual,tui,worktree
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.14
+Requires-Dist: click>=8.1.0
+Requires-Dist: humanize>=4.9.0
+Requires-Dist: libtmux>=0.37.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: textual>=7.2.0
+Description-Content-Type: text/markdown
+
+# forestui
+
+> A terminal UI for managing Git worktrees, inspired by [forest](https://github.com/ricwo/forest) for macOS by [@ricwo](https://github.com/ricwo).
+
+forestui brings the power of Git worktree management to the terminal with a beautiful TUI interface built on [Textual](https://textual.textualize.io/), featuring deep integration with [Claude Code](https://claude.ai/code).
+
+![forestui screenshot](doc/screenshot_small.png)
+
+## Features
+
+- **Repository Management**: Add and track multiple Git repositories
+- **Worktree Operations**: Create, rename, archive, and delete worktrees
+- **TUI Editor Integration**: Opens TUI editors (vim, nvim, helix, etc.) in tmux windows
+- **Claude Code Integration**: Track and resume Claude Code sessions per worktree
+- **Multi-Forest Support**: Manage multiple forest directories via CLI argument
+- **tmux Native**: Runs inside tmux for a cohesive terminal experience
+
+## Requirements
+
+- Python 3.14+
+- tmux
+- uv (for installation)
+
+## Installing
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/flipbit03/forestui/main/install.sh | bash
+```
+
+## Usage
+
+```bash
+# Start with default forest directory (~/forest)
+forestui
+
+# Start with a custom forest directory
+forestui ~/my-projects
+
+# Update to latest version
+forestui --self-update
+
+# Show help
+forestui --help
+```
+
+### Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `a` | Add repository |
+| `w` | Add worktree |
+| `e` | Open in editor |
+| `t` | Open in terminal |
+| `o` | Open in file manager |
+| `n` | Start Claude session |
+| `y` | Start Claude session (YOLO mode) |
+| `h` | Toggle archive |
+| `d` | Delete |
+| `s` | Settings |
+| `r` | Refresh |
+| `?` | Show help |
+| `q` | Quit |
+
+### TUI Editor Integration
+
+When your default editor is a TUI editor (vim, nvim, helix, nano, etc.), forestui opens it in a new tmux window named `edit:<worktree>`. This keeps your editing session organized alongside forestui and any Claude sessions.
+
+Supported TUI editors: `vim`, `nvim`, `vi`, `emacs`, `nano`, `helix`, `hx`, `micro`, `kakoune`, `kak`
+
+### Multi-Forest Support
+
+forestui stores its state (`.forestui-config.json`) in the forest directory itself, allowing you to manage multiple independent forests:
+
+```bash
+forestui ~/work      # Uses ~/work/.forestui-config.json
+forestui ~/personal  # Uses ~/personal/.forestui-config.json
+```
+
+User preferences (editor, theme, branch prefix) are stored globally in `~/.config/forestui/settings.json`.
+
+## Configuration
+
+Settings are stored in `~/.config/forestui/settings.json`:
+
+```json
+{
+  "default_editor": "nvim",
+  "branch_prefix": "feat/",
+  "theme": "system"
+}
+```
+
+Press `s` in the app to open the settings modal.
+
+## Development
+
+```bash
+# Clone and enter the repo
+git clone https://github.com/flipbit03/forestui.git
+cd forestui
+
+# Install dev dependencies
+make dev
+
+# Run checks
+make check
+
+# Format code
+make format
+
+# Run the app
+make run
+```
+
+See [CLAUDE.md](CLAUDE.md) for AI-assisted development guidelines.
+
+## Compatibility with forest (macOS)
+
+forestui is designed to coexist with [forest](https://github.com/ricwo/forest) for macOS:
+
+- Both apps can share the same `~/forest` directory for worktrees
+- Each app maintains its own state file:
+  - forest: `.forest-config.json` (stored in `~/.config/forest/`)
+  - forestui: `.forestui-config.json` (stored in the forest folder itself)
+- Worktrees created by either app work seamlessly with both
+
+**Key difference:** forestui stores its state inside the forest folder (`~/forest/.forestui-config.json`) rather than in a global config directory. This design enables multi-forest support - you can run `forestui ~/work` and `forestui ~/personal` with completely independent state for each.
+
+## License
+
+MIT

forestui-0.9.0/README.md

@@ -0,0 +1,131 @@
+# forestui
+
+> A terminal UI for managing Git worktrees, inspired by [forest](https://github.com/ricwo/forest) for macOS by [@ricwo](https://github.com/ricwo).
+
+forestui brings the power of Git worktree management to the terminal with a beautiful TUI interface built on [Textual](https://textual.textualize.io/), featuring deep integration with [Claude Code](https://claude.ai/code).
+
+![forestui screenshot](doc/screenshot_small.png)
+
+## Features
+
+- **Repository Management**: Add and track multiple Git repositories
+- **Worktree Operations**: Create, rename, archive, and delete worktrees
+- **TUI Editor Integration**: Opens TUI editors (vim, nvim, helix, etc.) in tmux windows
+- **Claude Code Integration**: Track and resume Claude Code sessions per worktree
+- **Multi-Forest Support**: Manage multiple forest directories via CLI argument
+- **tmux Native**: Runs inside tmux for a cohesive terminal experience
+
+## Requirements
+
+- Python 3.14+
+- tmux
+- uv (for installation)
+
+## Installing
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/flipbit03/forestui/main/install.sh | bash
+```
+
+## Usage
+
+```bash
+# Start with default forest directory (~/forest)
+forestui
+
+# Start with a custom forest directory
+forestui ~/my-projects
+
+# Update to latest version
+forestui --self-update
+
+# Show help
+forestui --help
+```
+
+### Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `a` | Add repository |
+| `w` | Add worktree |
+| `e` | Open in editor |
+| `t` | Open in terminal |
+| `o` | Open in file manager |
+| `n` | Start Claude session |
+| `y` | Start Claude session (YOLO mode) |
+| `h` | Toggle archive |
+| `d` | Delete |
+| `s` | Settings |
+| `r` | Refresh |
+| `?` | Show help |
+| `q` | Quit |
+
+### TUI Editor Integration
+
+When your default editor is a TUI editor (vim, nvim, helix, nano, etc.), forestui opens it in a new tmux window named `edit:<worktree>`. This keeps your editing session organized alongside forestui and any Claude sessions.
+
+Supported TUI editors: `vim`, `nvim`, `vi`, `emacs`, `nano`, `helix`, `hx`, `micro`, `kakoune`, `kak`
+
+### Multi-Forest Support
+
+forestui stores its state (`.forestui-config.json`) in the forest directory itself, allowing you to manage multiple independent forests:
+
+```bash
+forestui ~/work      # Uses ~/work/.forestui-config.json
+forestui ~/personal  # Uses ~/personal/.forestui-config.json
+```
+
+User preferences (editor, theme, branch prefix) are stored globally in `~/.config/forestui/settings.json`.
+
+## Configuration
+
+Settings are stored in `~/.config/forestui/settings.json`:
+
+```json
+{
+  "default_editor": "nvim",
+  "branch_prefix": "feat/",
+  "theme": "system"
+}
+```
+
+Press `s` in the app to open the settings modal.
+
+## Development
+
+```bash
+# Clone and enter the repo
+git clone https://github.com/flipbit03/forestui.git
+cd forestui
+
+# Install dev dependencies
+make dev
+
+# Run checks
+make check
+
+# Format code
+make format
+
+# Run the app
+make run
+```
+
+See [CLAUDE.md](CLAUDE.md) for AI-assisted development guidelines.
+
+## Compatibility with forest (macOS)
+
+forestui is designed to coexist with [forest](https://github.com/ricwo/forest) for macOS:
+
+- Both apps can share the same `~/forest` directory for worktrees
+- Each app maintains its own state file:
+  - forest: `.forest-config.json` (stored in `~/.config/forest/`)
+  - forestui: `.forestui-config.json` (stored in the forest folder itself)
+- Worktrees created by either app work seamlessly with both
+
+**Key difference:** forestui stores its state inside the forest folder (`~/forest/.forestui-config.json`) rather than in a global config directory. This design enables multi-forest support - you can run `forestui ~/work` and `forestui ~/personal` with completely independent state for each.
+
+## License
+
+MIT

forestui-0.9.0/forestui/__init__.py

@@ -0,0 +1,3 @@
+"""forestui - A Terminal UI for managing Git worktrees."""
+
+__version__ = "0.9.0"

forestui-0.9.0/forestui/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for forestui."""
+
+from forestui.app import main
+
+if __name__ == "__main__":
+    main()