gitstow 0.1.0__tar.gz → 0.2.6__tar.gz

gitstow-0.2.6/.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.6/.github/workflows/publish.yml

@@ -0,0 +1,65 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    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.1.0 → gitstow-0.2.6}/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.6/CHANGELOG.md

@@ -0,0 +1,112 @@
+# 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.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.6}/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
 

{gitstow-0.1.0 → gitstow-0.2.6}/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.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitstow
-Version: 0.1.0
+Version: 0.2.6
 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

{gitstow-0.1.0 → gitstow-0.2.6}/README.md

@@ -2,6 +2,8 @@
 
 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.
@@ -30,11 +32,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
@@ -134,9 +135,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
@@ -180,14 +189,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.
 
@@ -259,6 +275,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

{gitstow-0.1.0 → gitstow-0.2.6}/demo.tape

@@ -1,5 +1,8 @@
 # gitstow demo — record with: vhs demo.tape
 # Install vhs: brew install charmbracelet/tap/vhs
+#
+# NOTE: This clones real repos. Run in a temp workspace or clean up after.
+# Before recording, ensure gitstow is configured with a test workspace.
 
 Output demo.gif
 
@@ -12,32 +15,38 @@ Type "# Add repos with gitstow"
 Enter
 Sleep 500ms
 
-Type "gitstow add anthropic/claude-code facebook/react"
+Type "gitstow -w demo add charmbracelet/vhs charmbracelet/gum --shallow"
 Enter
-Sleep 3s
+Sleep 12s
 
+Type ""
+Enter
 Type "# See your collection"
 Enter
 Sleep 500ms
 
-Type "gitstow list"
+Type "gitstow -w demo list"
 Enter
 Sleep 2s
 
+Type ""
+Enter
 Type "# Git status across all repos"
 Enter
 Sleep 500ms
 
-Type "gitstow status"
+Type "gitstow -w demo status"
 Enter
 Sleep 2s
 
+Type ""
+Enter
 Type "# Update everything"
 Enter
 Sleep 500ms
 
-Type "gitstow pull"
+Type "gitstow -w demo pull"
 Enter
-Sleep 3s
+Sleep 4s
 
 Sleep 1s

{gitstow-0.1.0 → gitstow-0.2.6}/docs/building/implementation-plan.md

@@ -628,11 +628,11 @@ dev = [
 12. **Skill** — SKILL.md + install-skill command
 13. **README** — user-facing documentation
 
-### Stage 2 — Polish & Power (future)
+### Stage 2 — Polish & Power (shipped in v0.1.0)
 
 | Component | Description |
 |-----------|-------------|
-| TUI | Interactive dashboard via Textual (`gitstow tui`) |
+| TUI | Interactive dashboard via Textual (`gitstow tui`) — broken, parked in BACKLOG |
 | MCP server | Expose tools to any AI tool via Model Context Protocol |
 | `search` | Grep across all repos |
 | `open` | Open repo in editor/browser/Finder |
@@ -642,6 +642,18 @@ dev = [
 | Shell integration | fzf helpers, shell completions, cd shortcut |
 | GitHub Actions | Automated PyPI publishing on tag |
 
+### Stage 3 — Browser GUI (shipped in v0.2.0 / v0.2.1)
+
+| Component | Description |
+|-----------|-------------|
+| `gitstow ui` | Persistent localhost browser dashboard (FastAPI + Jinja2 + HTMX, dark theme). Core feature, not an extra. `src/gitstow/web/` |
+| Read-only dashboard | Status ledger with auto-refresh every 30s via HTMX; repo detail drawer |
+| Mutations | Add / pull single / pull all (parallel) / remove / delete / freeze / tag — HTMX row swaps, no SPA toolchain |
+| Workspace CRUD + Scan | Add/remove workspaces, scan-and-catalog from the UI |
+| Collection I/O | Export YAML/JSON/URLs, import uploads — under Settings |
+| Shutdown | Footer button POSTs `/shutdown` → flips `uvicorn.Server.should_exit` |
+| `gitstow update` (v0.2.1) | Self-upgrade command — detects pipx/pip/editable and runs the right upgrade; `--check` queries PyPI without installing |
+
 ---
 
 ## Patterns Adopted