gitstow 0.1.0__tar.gz → 0.2.8__tar.gz

gitstow-0.2.8/.claude/settings.json

@@ -0,0 +1,19 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python -m pytest tests/test_serve.py -v)",
+      "Bash(python -c \"from gitstow.cli.main import app; from typer.testing import CliRunner; r = CliRunner\\(\\); print\\(r.invoke\\(app, ['ui', '--help']\\).output\\)\")",
+      "Bash(python3 -m pytest tests/test_serve.py -v)",
+      "Bash(python3 -c \"from gitstow.cli.main import app; from typer.testing import CliRunner; r = CliRunner\\(\\); print\\(r.invoke\\(app, ['ui', '--help']\\).output\\)\")",
+      "Bash(python3 -c \"from gitstow.cli.main import app; from typer.testing import CliRunner; r = CliRunner\\(\\); print\\(r.invoke\\(app, ['serve', '--help']\\).output\\)\")",
+      "Bash(python3 -m pytest -v)",
+      "Bash(git commit -m ':*)",
+      "Bash(python3 -m pytest tests/test_git.py tests/test_serve.py -v)",
+      "Bash(python3 -c \"from gitstow.cli.main import app; from typer.testing import CliRunner; r = CliRunner\\(\\); print\\(r.invoke\\(app, ['fetch', '--help']\\).output\\)\")",
+      "Bash(git tag:*)",
+      "Bash(python3 -c \"import gitstow; print\\(gitstow.__version__\\)\")",
+      "Bash(pip3 show:*)",
+      "Bash(python3 -m pytest tests/test_serve.py::TestFetch -v)"
+    ]
+  }
+}

gitstow-0.2.8/.github/workflows/publish.yml

@@ -0,0 +1,84 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/
+
+      - name: Test
+        run: pytest --tb=short
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Verify version matches tag
+        run: |
+          python - <<'PY'
+          import os
+          import pathlib
+          import re
+          import sys
+          import tomllib
+
+          tag_version = os.environ["GITHUB_REF"].removeprefix("refs/tags/v")
+
+          with open("pyproject.toml", "rb") as f:
+              package_version = tomllib.load(f)["project"]["version"]
+
+          init_text = pathlib.Path("src/gitstow/__init__.py").read_text()
+          match = re.search(r'__version__ = "([^"]+)"', init_text)
+          init_version = match.group(1) if match else None
+
+          errors = []
+          if tag_version != package_version:
+              errors.append(
+                  f"Tag v{tag_version} does not match package version {package_version}"
+              )
+          if init_version != package_version:
+              errors.append(
+                  f"src/gitstow/__init__.py version {init_version} "
+                  f"does not match package version {package_version}"
+              )
+
+          if errors:
+              for error in errors:
+                  print(f"::error::{error}")
+              sys.exit(1)
+
+          print(f"Publishing gitstow v{package_version}")
+          PY
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

gitstow-0.2.8/AGENTS.md

@@ -0,0 +1,150 @@
+# gitstow - AI Developer Guide
+
+## What is this?
+
+A CLI tool that manages collections of git repositories across multiple workspaces. Think "package manager for repos" - whether they're open-source projects you learn from or active projects you work on.
+
+## Operating Contract
+
+- Prefer proper long-term solutions over shortcut patches. If a feature is incomplete in one surface, build the feature into that surface instead of papering over it with wording, partial conditionals, or one-off display logic.
+- Do not recommend quick fixes, temporary patches, or narrow workarounds unless the user explicitly asks for a shortcut.
+- Read the relevant existing code before proposing or editing. Let the current architecture decide where the change belongs.
+- Keep changes scoped to the requested behavior. Avoid unrelated refactors, formatting churn, or drive-by cleanups.
+- Do not revert user changes or generated local state unless the user explicitly asks.
+
+## Product Standards
+
+- Keep CLI, TUI, web dashboard, JSON output, docs, and tests semantically aligned when changing user-facing status behavior.
+- For repo state presentation, avoid using "dirty" as a broad user-facing bucket for every local change. Present it as local/uncommitted changes with the composition visible: modified, staged, and untracked counts.
+- Keep local working-tree state separate from remote relationship state. For example: local changes, clean, ahead, behind, diverged, frozen, missing.
+- When improving the web dashboard, implement the actual missing dashboard feature and shared classification/model behavior instead of copying a CLI-only assumption into the template.
+
+## Key Concept: Workspaces
+
+Repos are organized into **workspaces** - directories with a label and layout mode:
+- **structured** layout: `workspace/owner/repo/` (open-source collections)
+- **flat** layout: `workspace/repo/` (active projects, no owner subdirectory)
+
+Each workspace can have auto-tags applied to all repos it discovers.
+
+## Architecture
+
+```
+src/gitstow/
+├── cli/          # Typer commands (thin — delegates to core)
+│   ├── main.py          # App entry, command registration, global --workspace flag
+│   ├── helpers.py       # Shared workspace resolution, repo lookup, iteration
+│   ├── add.py, pull.py, list_cmd.py, status.py, remove.py  # Core commands
+│   ├── workspace_cmd.py # workspace list/add/remove/scan subcommands
+│   ├── manage.py        # freeze/unfreeze/tag/untag/info subcommands
+│   ├── exec_cmd.py, search.py, open_cmd.py, stats.py       # Power commands
+│   ├── export_cmd.py    # export/import collection
+│   ├── shell.py         # Shell integration (fzf, aliases)
+│   ├── tui.py           # TUI launcher
+│   ├── serve.py         # Web dashboard launcher
+│   ├── migrate.py, config_cmd.py, onboard.py, doctor.py, skill_cmd.py
+│   └── __init__.py
+├── core/         # Business logic (git ops, URL parsing, state)
+│   ├── paths.py       # Path constants, central repos.yaml resolution
+│   ├── config.py      # Workspace + Settings dataclasses, load/save
+│   ├── repo.py        # Repo dataclass + RepoStore (nested YAML CRUD)
+│   ├── url_parser.py  # URL → (host, owner, repo) extraction
+│   ├── git.py         # All git subprocess calls
+│   ├── discovery.py   # Walk directory tree (structured + flat), reconcile
+│   ├── parallel.py    # Async execution with semaphore
+│   └── __init__.py
+├── tui/          # Textual interactive dashboard
+│   ├── app.py         # Main TUI application
+│   └── __init__.py
+├── web/          # FastAPI browser dashboard (gitstow ui)
+│   ├── server.py          # FastAPI app, uvicorn runner, app.state.server stash
+│   ├── static/app.css     # Dark theme, Bricolage Grotesque + JetBrains Mono
+│   ├── templates/         # Jinja2 — base.html + page templates + partials/
+│   └── routes/            # dashboard.py, repos.py, workspaces.py, collection.py, pages.py, system.py
+└── skill/        # Codex skill (SKILL.md)
+    └── SKILL.md
+```
+
+**Key rules:**
+1. CLI never touches git directly - it calls `core/git.py`
+2. `core/repo.py` (RepoStore) is the only module that reads/writes `repos.yaml`
+3. `core/config.py` defines Workspace dataclass - all workspace logic flows from here
+4. `cli/helpers.py` provides `resolve_workspaces()`, `resolve_repo()`, `iter_repos_with_workspace()`
+
+## Key Files
+
+- `core/config.py` - Workspace + Settings dataclasses. `get_workspaces()` with legacy migration shim.
+- `core/repo.py` - Repo with workspace field, RepoStore with nested YAML format, legacy auto-migration.
+- `core/discovery.py` - `discover_repos(root, layout)` supports structured and flat layouts.
+- `core/url_parser.py` - URL parsing (the hardest part). Test changes here thoroughly.
+- `core/git.py` - All git subprocess calls. Uses `git status --porcelain=v2 --branch` for single-call efficiency.
+- `core/parallel.py` - Async execution with semaphore (max 6 concurrent).
+- `cli/helpers.py` - Shared workspace resolution used by all CLI commands.
+- `cli/workspace_cmd.py` - workspace list/add/remove/scan subcommands.
+- `cli/main.py` - Typer app, global `-w/--workspace` option, command registration.
+- `tui/app.py` - Textual dashboard with DataTable, filter, pull, freeze toggle.
+
+## Data Files
+
+- `~/.gitstow/config.yaml` - Settings (workspaces list, default host, SSH pref).
+- `~/.gitstow/repos.yaml` - Repo metadata nested by workspace label. Central location.
+
+### repos.yaml format
+```yaml
+oss:
+  anthropic/Codex:
+    remote_url: https://github.com/anthropic/Codex.git
+    tags: [ai]
+active:
+  gitstow:
+    remote_url: https://github.com/rishmadaan/gitstow.git
+    tags: [active]
+```
+
+## All Commands (32)
+
+**Core:** `add`, `pull`, `fetch`, `list`, `status`, `remove`, `migrate`
+**Workspace:** `workspace list`, `workspace add`, `workspace remove`, `workspace scan`
+**Repo management:** `repo freeze`, `repo unfreeze`, `repo tag`, `repo untag`, `repo tags`, `repo info`
+**Power:** `exec`, `search`, `open`, `stats`
+**Sharing:** `collection export`, `collection import`
+**Shell:** `shell pick`, `shell init`, `shell completions`, `shell setup`, `tui`, `ui`
+**Setup:** `onboard`, `config show/set/path/migrate-root`, `doctor`, `install-skill`, `setup-ai`, `update`
+
+## Development
+
+```bash
+cd ~/labs/projects/gitstow
+pip install -e ".[dev]"
+pytest                    # 44 tests
+ruff check src/
+pip install -e ".[tui]"   # For TUI development
+```
+
+## Patterns
+
+- `--json -j` and `--quiet -q` on all main commands
+- Global `-w/--workspace` flag filters all commands to a single workspace
+- `cli/helpers.py` for workspace resolution (don't repeat in each command)
+- Rich console for stdout, err_console for stderr
+- Typer with `rich_markup_mode="rich"`, `typer.Context` for global options
+- YAML for persistence (not JSON, not SQLite)
+- asyncio with semaphore for parallel git ops
+- `git status --porcelain=v2 --branch` for single-call status (vs gita's 4-5 calls)
+- Repo.global_key (`workspace:key`) for unique identification across workspaces
+- Legacy format auto-migration (flat repos.yaml -> nested, root_path -> workspaces)
+
+## AI Integration
+
+**Primary: Codex skill** (`src/gitstow/skill/SKILL.md`)
+- Installed to `~/.Codex/skills/gitstow/` via `gitstow install-skill` or `gitstow onboard`
+- Auto-updates on version bumps (checks `.version` marker on every CLI invocation)
+- Zero context cost when inactive - only loaded when task matches the skill description
+- Codex runs gitstow CLI commands via Bash - full access to all commands
+
+**Optional: MCP server** (`src/gitstow/mcp/server.py`)
+- For non-Codex AI tools (Codex Desktop, Cursor, Windsurf)
+- Install: `pip install gitstow[mcp]`, entry point: `gitstow-mcp`
+- 13 tools + 3 resources, wraps same `core/` modules as CLI
+- **Tradeoff:** MCP tools are always loaded into context (costs tokens even when idle).
+  The skill has no such cost. Only use MCP for dedicated repo-management setups.

{gitstow-0.1.0 → gitstow-0.2.8}/BACKLOG.md

@@ -10,7 +10,9 @@ Post-v0.1.0 improvements tracked here. See [GitHub Issues](https://github.com/ri
 - [x] **Export format versioning and checksums** (#4) — Added `version: 1` to YAML/JSON exports; validates on import; backward-compatible with unversioned files
 - [x] **Progress indication during long clones** (#5) — `git clone --progress`; pull shows live counter `[5/47]`
 - [x] **Publish to PyPI** (#6) — Release workflow created (`.github/workflows/release.yml`); publish on GitHub release
+- [x] **Web dashboard (`gitstow ui`)** — Dark local browser UI wrapping core/ for daily repo management. FastAPI + Jinja2 + HTMX, dark + ember accent aesthetic. See [CHANGELOG.md](CHANGELOG.md) v0.2.0.
+- [ ] **Fix TUI breakage** — Multiple issues across the Textual TUI; currently unusable in daily flow. Keep around for SSH/remote use case but triage and repair when time allows.
 
 ## Documentation
 
-- [ ] **Record demo GIF for README** (#7) — VHS tape script created (`demo.tape`); run `vhs demo.tape` to record
+- [x] **Record demo GIF for README** (#7) — Recorded with VHS, embedded in README

gitstow-0.2.8/CHANGELOG.md

@@ -0,0 +1,141 @@
+# Changelog
+
+All notable changes to gitstow will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.2.8] - 2026-07-12
+
+### Fixed
+
+- **Pasted GitHub browse URLs now resolve correctly.** URLs like `/tree/...`, `/blob/...`, `/pull/...` now resolve to the repo root instead of being misparsed.
+- **`config migrate-root`** now actually updates workspace paths, and honors the global `-w/--workspace` flag.
+- **`repo freeze/unfreeze/tag/untag`** now honor `-w/--workspace` and report cross-workspace ambiguity clearly instead of guessing.
+- **`pull --json` and `fetch --json`** always emit pure JSON on stdout — no more banners or progress lines interleaved with the payload.
+- **Pull summary** keeps per-workspace identity for same-named frozen repos in different workspaces.
+- **Bulk git operations** no longer hang on credential prompts and are now locale-independent.
+- **`remove --delete`** refuses to delete paths that resolve outside the workspace root.
+- **Workspace labels** are now validated (lowercase alphanumeric, dash, underscore only).
+
+### Added
+
+- **Atomic, cross-process-locked writes** to `repos.yaml`, safe for concurrent CLI and web UI use.
+- **Test gate before PyPI publish** — releases now require a passing test suite.
+
+### Security
+
+- **Web dashboard CSRF protection.** POST routes now reject cross-origin and DNS-rebinding requests on the localhost UI.
+
+## [0.2.7] - 2026-05-28
+
+### Fixed
+
+- **`gitstow onboard`** now uses Beaupy's `default_is_yes` confirmation parameter, fixing first-run setup crashes on confirmation prompts.
+- **AI integration setup** now renders MCP warning text with balanced Rich markup during onboarding and `gitstow setup-ai`.
+
+## [0.2.5] - 2026-04-19
+
+### Added
+
+- **`gitstow fetch`** — new CLI command to fetch all remotes without merging. Updates ahead/behind counts. Includes frozen repos (fetch is non-destructive). Supports `--tag`, `--exclude-tag`, `--owner`, `--retry`, `--json`, `--quiet` flags.
+- **Web dashboard — Fetch all button.** New `btn-outline` button in the action bar between Refresh and Add repo. Fetches all remotes in parallel (including frozen repos), then shows a summary panel. No confirmation needed — fetch is non-destructive.
+- **Web dashboard — single-repo Fetch.** New "Fetch" action in each row's three-dot menu. Updates that row's ahead/behind counts in place via HTMX.
+- **`last_fetched` timestamp** tracked per repo in `repos.yaml`. Stamped on successful fetch operations. Backward-compatible — existing repos default to empty.
+- Updated help dialog and tooltips to reference Fetch all instead of "fetch manually."
+
+## [0.2.4] - 2026-04-19
+
+### Changed
+
+- **Renamed `gitstow serve` → `gitstow ui`** — more intuitive command name for the browser dashboard. `gitstow serve` remains as a hidden alias for backwards compatibility.
+- **Removed `WEB_GUI_PLAN.md`** — shipped planning artifact retired; git history preserves it.
+
+## [0.2.3] - 2026-04-18
+
+### Fixed
+
+- **Web dashboard — "Open folder" now actually opens the folder.** The row-menu and drawer buttons were previously no-ops; they now POST to a new `/repos/{ws}/{key}/open-folder` route which shells out to the platform opener (`open` on macOS, `xdg-open` on Linux, `explorer` on Windows). The server binds to `127.0.0.1` only, so no exposure beyond localhost.
+
+### Added
+
+- **Web dashboard — Copy URL / Copy path / Copy local path actions.** The `⋯` row menu and the repo drawer each expose three clipboard actions: Copy URL (remote clone URL), Copy path (repo key like `owner/repo`), Copy local path (absolute filesystem path). Implemented client-side with `navigator.clipboard` and a textarea fallback for non-secure contexts.
+- **Toast notifications.** A new bottom-center toast surfaces success/failure for Open folder and the copy actions (reads an optional `data-toast` attr on any `hx-post` button and an error message from the JSON response body on failure).
+
+## [0.2.2] - 2026-04-18
+
+### Added
+
+- **Dashboard tooltips everywhere.** Every interactive element now has a `title=` explaining what it does or what its state means — status pills (with the recommended next step), delta badges, workspace chips, tags, last-pull, Pull button (text varies by repo state), the `⋯` menu and each of its items, action-bar buttons, column headers, the nav links, the live dot, the Shutdown button, the lock icon. Hover over anything.
+- **Pull button now shows the commit count when behind.** `↓ Pull 5` instead of just `Pull` — the action's payload is visible at a glance without hover.
+- **"Reading the dashboard" help dialog.** New `?` button in the hero opens a native `<dialog>` modal with: statuses + what each means + what to do, the Pull button color convention, what Remote Δ reflects (last fetch, not live remote), what auto-refresh actually does (local state only; does NOT run `git fetch`), and a reference for every action. Click the backdrop or press Esc to close.
+- Matching `docs/user/commands.md` "Reading the dashboard" subsection under `gitstow ui` so the legend exists in prose too, not only in the UI.
+
+### Changed
+
+- `_classify` and `_delta` helpers in `web/routes/dashboard.py` now also return tooltip strings; `_pull_tooltip` maps (variant × status) to the exact explanation shown on each Pull button. Partial template `partials/repo_row.html` threads these through consistently so HTMX row swaps after pull keep the tooltips accurate.
+
+## [0.2.1] - 2026-04-17
+
+### Added
+
+- **`gitstow update`** — self-upgrade from PyPI. Detects the install method (pipx, pip, or editable) and runs the matching upgrade command. Use `--check` / `-c` to query PyPI without installing — shows newer-version-available or up-to-date. Editable installs get a friendly note pointing at `git pull` instead of trying to pip-upgrade.
+- Smoke tests for `serve` and `update` command help.
+
+### Fixed
+
+- **CI**: added `httpx` to `[dev]` extras. `fastapi.testclient.TestClient` re-exports Starlette's version, which imports `httpx` at module load. Fresh CI installs were failing at test collection; local envs passed because `httpx` was already present from other packages.
+
+## [0.2.0] - 2026-04-17
+
+### Added
+
+- **`gitstow ui`** — a persistent local browser dashboard for daily repo management. Launches a FastAPI + Jinja2 + HTMX server at `http://127.0.0.1:7853` and auto-opens your default browser. Dark theme (Bricolage Grotesque display, JetBrains Mono data) with ember-orange primary accent and signal-blue secondary.
+  - **Dashboard** — ledger view of every tracked repo: colored-dot status (clean / dirty / conflict / behind / ahead / frozen), workspace chip, branch, remote delta, tags, last-pull time. Hero metrics strip summarizes counts. Hover reveals an accent indicator line on the row's left edge.
+  - **Pull** — single-repo pull with HTMX row swap in place; **Pull all** runs every non-frozen repo in parallel via the existing `core.parallel` semaphore and renders a summary panel (`N ok · N failed · N skipped`) with per-repo failure details.
+  - **Add repo** — form with URL parser, workspace selector, and optional tags; merges workspace auto-tags on clone.
+  - **Remove** — registry-only from the row's ⋯ menu (HTMX row-delete); registry + disk from the repo drawer (defensive path check; refuses to rmtree outside the workspace root).
+  - **Freeze / tag toggles** — row-menu freeze with HTMX label flip; drawer freeze checkbox posts on change; drawer tag editor replaces the list from a comma-separated input.
+  - **Workspaces** — list, add (label + path + layout + auto-tags), remove (files untouched), **Scan** (discovers untracked repos on disk and catalogs them with auto-tags merged).
+  - **Collection export / import** — under Settings; downloads YAML (canonical round-trip), JSON, or plain URL list; upload accepts any of the three.
+  - **Auto-refresh** — dashboard tbody reloads every 30s via HTMX `hx-trigger="every 30s"` without touching hero, metrics, or action bar.
+  - **Shutdown** — footer button POSTs `/shutdown`, which flips `uvicorn.Server.should_exit` (Ctrl+C also works).
+- **New core dependencies** (shipped, not behind an extra): `fastapi>=0.110`, `uvicorn>=0.27`, `jinja2>=3.1`, `python-multipart>=0.0.9`.
+- **30 FastAPI TestClient smoke tests** covering every route + mutation path. Monkeypatches isolate config/repo files to tmp; git calls are mocked (never shells out).
+
+### Changed
+
+- Command count 29 → 30 (`serve` added).
+- `CLAUDE.md` architecture tree expanded to document the new `web/` module.
+
+### Security
+
+- `gitstow ui` binds `127.0.0.1` only. There is no `--host` flag — arbitrary git execution must not be LAN-reachable.
+- All mutations are POST; `/shutdown` is POST so stray links can't terminate the server.
+- Registry + disk delete resolves the repo path and verifies it lives under the workspace root before `rmtree`.
+
+### Deferred
+
+- The Textual TUI has multiple breakages and is parked in [BACKLOG.md](BACKLOG.md); `gitstow ui` is the primary visual dashboard now. TUI remains for the eventual SSH / remote use case.
+- Web GUI is intentionally single-user + localhost-only. Auth, multi-user, HTTPS, remote access, and daemonization are explicitly out of scope for v0.2.
+
+## [0.1.0] - 2026-04-10
+
+Initial release.
+
+### Added
+
+- **Core commands:** `add`, `pull`, `list`, `status`, `remove`, `migrate`
+- **Workspace system:** Multiple workspaces with structured (`owner/repo`) and flat (`repo`) layouts
+- **Workspace commands:** `workspace list`, `workspace add`, `workspace remove`, `workspace scan`
+- **Repo management:** `repo freeze`, `repo unfreeze`, `repo tag`, `repo untag`, `repo tags`, `repo info`
+- **Bulk operations:** Parallel pull/status with configurable concurrency (default 6)
+- **Power commands:** `exec` (run commands across repos), `search` (grep across repos via ripgrep), `open` (editor/browser/finder), `stats`
+- **Collection sharing:** `collection export` (YAML/JSON/URLs) and `collection import`
+- **Shell integration:** `shell pick` (fzf picker), `shell init` (aliases), `shell setup`
+- **Interactive TUI:** `tui` command with Textual-based dashboard (filter, pull, freeze toggle)
+- **URL parsing:** GitHub, GitLab, Bitbucket, Codeberg, Azure DevOps, custom hosts; HTTPS, SSH, and shorthand formats
+- **AI integration:** Claude Code skill (auto-installed via `onboard` or `install-skill`) and optional MCP server
+- **Setup:** `onboard` wizard, `doctor` health check, `config show/set`
+- **Output modes:** `--json` and `--quiet` flags on all main commands
+- **Global workspace filter:** `-w/--workspace` flag on all commands
+- **Error isolation:** One failing repo never blocks operations on others

{gitstow-0.1.0 → gitstow-0.2.8}/CLAUDE.md

@@ -26,6 +26,7 @@ src/gitstow/
 │   ├── export_cmd.py    # export/import collection
 │   ├── shell.py         # Shell integration (fzf, aliases)
 │   ├── tui.py           # TUI launcher
+│   ├── serve.py         # Web dashboard launcher
 │   ├── migrate.py, config_cmd.py, onboard.py, doctor.py, skill_cmd.py
 │   └── __init__.py
 ├── core/         # Business logic (git ops, URL parsing, state)
@@ -40,6 +41,11 @@ src/gitstow/
 ├── tui/          # Textual interactive dashboard
 │   ├── app.py         # Main TUI application
 │   └── __init__.py
+├── web/          # FastAPI browser dashboard (gitstow ui)
+│   ├── server.py          # FastAPI app, uvicorn runner, app.state.server stash
+│   ├── static/app.css     # Dark theme, Bricolage Grotesque + JetBrains Mono
+│   ├── templates/         # Jinja2 — base.html + page templates + partials/
+│   └── routes/            # dashboard.py, repos.py, workspaces.py, collection.py, pages.py, system.py
 └── skill/        # Claude Code skill (SKILL.md)
     └── SKILL.md
 ```
@@ -80,15 +86,15 @@ active:
     tags: [active]
 ```
 
-## All Commands (26)
+## All Commands (32)
 
-**Core:** `add`, `pull`, `list`, `status`, `remove`, `migrate`
+**Core:** `add`, `pull`, `fetch`, `list`, `status`, `remove`, `migrate`
 **Workspace:** `workspace list`, `workspace add`, `workspace remove`, `workspace scan`
 **Repo management:** `repo freeze`, `repo unfreeze`, `repo tag`, `repo untag`, `repo tags`, `repo info`
 **Power:** `exec`, `search`, `open`, `stats`
 **Sharing:** `collection export`, `collection import`
-**Shell:** `shell pick`, `shell init`, `shell setup`, `tui`
-**Setup:** `onboard`, `config show/set/path/migrate-root`, `doctor`, `install-skill`
+**Shell:** `shell pick`, `shell init`, `shell completions`, `shell setup`, `tui`, `ui`
+**Setup:** `onboard`, `config show/set/path/migrate-root`, `doctor`, `install-skill`, `setup-ai`, `update`
 
 ## Development
 
@@ -113,6 +119,15 @@ pip install -e ".[tui]"   # For TUI development
 - Repo.global_key (`workspace:key`) for unique identification across workspaces
 - Legacy format auto-migration (flat repos.yaml → nested, root_path → workspaces)
 
+## Product & Implementation Standards
+
+- Prefer proper long-term solutions over shortcut patches. If a feature is incomplete in one surface, build the feature into that surface instead of papering over it with wording, partial conditionals, or one-off display logic.
+- Do not recommend quick fixes, temporary patches, or narrow workarounds unless the user explicitly asks for a shortcut.
+- Keep CLI, TUI, web dashboard, JSON output, docs, and tests semantically aligned when changing user-facing status behavior.
+- For repo state presentation, avoid using "dirty" as a broad user-facing bucket for every local change. Present it as local/uncommitted changes with the composition visible: modified, staged, and untracked counts.
+- Keep local working-tree state separate from remote relationship state. For example: local changes, clean, ahead, behind, diverged, frozen, missing.
+- When improving the web dashboard, implement the actual missing dashboard feature and shared classification/model behavior instead of copying a CLI-only assumption into the template.
+
 ## AI Integration
 
 **Primary: Claude Code skill** (`src/gitstow/skill/SKILL.md`)

{gitstow-0.1.0 → gitstow-0.2.8}/CONTRIBUTING.md

@@ -40,6 +40,7 @@ The codebase has a strict layered architecture:
 cli/     → Thin command layer (Typer). Delegates to core/.
 core/    → Business logic. Git ops, config, repo store, URL parsing.
 tui/     → Textual interactive dashboard.
+web/     → FastAPI + Jinja2 + HTMX browser dashboard (`gitstow ui`).
 skill/   → Claude Code skill (SKILL.md).
 mcp/     → MCP server for non-Claude-Code AI tools.
 ```
@@ -67,6 +68,17 @@ See `CLAUDE.md` for a detailed architecture guide.
 - The Claude Code skill auto-updates when the version changes (checked on every CLI invocation)
 - Follow [Semantic Versioning](https://semver.org/): breaking.feature.fix
 
+Release from a `main` branch with no tracked changes:
+
+```bash
+bash scripts/release.sh 0.2.6 "short release note"
+```
+
+The release script updates both version files, commits the bump, creates `vX.Y.Z`,
+and pushes the commit plus tag. The `Publish to PyPI` workflow runs on pushed `v*`
+tags and verifies the tag, `pyproject.toml`, and `src/gitstow/__init__.py` versions
+match before publishing.
+
 ## What to Work On
 
 - Check [open issues](https://github.com/rishmadaan/gitstow/issues) for things to pick up

{gitstow-0.1.0 → gitstow-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitstow
-Version: 0.1.0
+Version: 0.2.8
 Summary: A git repository library manager — clone, organize, and maintain collections of repos you learn from
 Project-URL: Homepage, https://github.com/rishmadaan/gitstow
 Project-URL: Repository, https://github.com/rishmadaan/gitstow
@@ -26,10 +26,15 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Version Control :: Git
 Requires-Python: >=3.10
 Requires-Dist: beaupy>=3.0
+Requires-Dist: fastapi>=0.110
+Requires-Dist: jinja2>=3.1
+Requires-Dist: python-multipart>=0.0.9
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0
 Requires-Dist: typer[all]>=0.9
+Requires-Dist: uvicorn>=0.27
 Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Provides-Extra: mcp
@@ -42,6 +47,8 @@ Description-Content-Type: text/markdown
 
 A git repository library manager — clone, organize, and maintain collections of repos you learn from.
 
+![gitstow demo](demo.gif)
+
 ## Why?
 
 AI-assisted development has created a new relationship with open source. Developers increasingly maintain local clones of repositories they study and reference, not just repos they contribute to. `gitstow` manages this collection as a first-class concern.
@@ -70,11 +77,10 @@ gitstow pull
 
 # See your collection
 gitstow list
-
-# Check git status across all repos
-gitstow status
 ```
 
+Prefer a GUI? Run `gitstow ui` — a local dark-themed browser dashboard opens automatically. Dirty state, branch deltas, Pull / Pull-all, add / remove / freeze / tag, workspace CRUD, collection export/import — all in one tab you leave open. See [Browser Dashboard](#browser-dashboard).
+
 ## Features
 
 ### Workspaces
@@ -174,9 +180,17 @@ gse                              # Open repo in editor (fzf picker)
 gsp                              # gitstow pull shorthand
 ```
 
-### Interactive Dashboard
+### Browser Dashboard
+```bash
+gitstow ui             # opens http://127.0.0.1:7853 in your browser
+gitstow ui --port 8080
+gitstow ui --no-browser
+```
+Persistent local web dashboard for daily repo management — a tab you leave open. Shows dirty state across your library, pulls single repos or all-of-them with a parallel summary panel, adds/removes repos, edits tags, freezes stale ones. Auto-refreshes row status every 30 seconds. Binds `127.0.0.1` only (arbitrary git execution must not be LAN-reachable). Click **Shutdown** in the footer — or Ctrl+C — to stop.
+
+### Interactive Dashboard (TUI)
 ```bash
-gitstow tui    # Keyboard-driven dashboard with filter, pull, freeze
+gitstow tui    # Keyboard-driven terminal dashboard (SSH-friendly)
 ```
 
 ### JSON Output
@@ -220,14 +234,21 @@ gitstow status --json
 | `gitstow collection import <file>` | Import a collection from file |
 | **Shell** | |
 | `gitstow shell setup` | Show shell integration instructions |
+| `gitstow shell init` | Print shell functions to source in rc file |
 | `gitstow shell pick` | fzf-powered repo picker |
+| `gitstow shell completions` | Tab completion for repo names, workspaces, tags |
 | `gitstow tui` | Interactive terminal dashboard |
+| `gitstow fetch` | Fetch all remotes — update ahead/behind counts without merging |
+| `gitstow ui` | Launch local browser dashboard (http://127.0.0.1:7853) |
+| `gitstow update` | Upgrade gitstow itself from PyPI (detects pipx / pip / editable) |
+| `gitstow update --check` | Check PyPI for a newer version without installing |
 | **Config** | |
 | `gitstow config show` | Show current config and workspaces |
 | `gitstow config set <key> <value>` | Change a setting |
 | `gitstow onboard` | First-run setup wizard |
 | `gitstow doctor` | Health check |
 | `gitstow install-skill` | Install Claude Code skill |
+| `gitstow setup-ai` | Auto-detect AI tools and configure integration |
 
 All commands accept `-w <label>` to filter to a specific workspace.
 
@@ -299,6 +320,15 @@ pytest
 ruff check src/
 ```
 
+Release from a `main` branch with no tracked changes:
+
+```bash
+bash scripts/release.sh 0.2.6 "short release note"
+```
+
+The script bumps `pyproject.toml` and `src/gitstow/__init__.py`, commits the bump,
+creates `vX.Y.Z`, and pushes the commit plus tag. Pushing the tag publishes to PyPI.
+
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
 
 ## License