gitstow 0.2.8__tar.gz → 0.3.0__tar.gz

{gitstow-0.2.8 → gitstow-0.3.0}/.github/workflows/ci.yml

@@ -8,10 +8,14 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
     strategy:
       matrix:
+        os: [ubuntu-latest]
         python-version: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          - os: macos-latest
+            python-version: "3.12"
+    runs-on: ${{ matrix.os }}
 
     steps:
       - uses: actions/checkout@v4

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

@@ -9,9 +9,9 @@ Post-v0.1.0 improvements tracked here. See [GitHub Issues](https://github.com/ri
 - [x] **Network retry/resume for batch operations** (#3) — `--retry N` flag on add and pull; cleans up partial clones before retry
 - [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] **Publish to PyPI** (#6) — Release workflow created (`.github/workflows/publish.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.
+- [x] **Fix TUI breakage** — Resolved by retirement: the Textual TUI was removed in v0.3.0; `gitstow ui` (web dashboard) is the visual surface going forward.
 
 ## Documentation
 

{gitstow-0.2.8 → gitstow-0.3.0}/CHANGELOG.md

@@ -4,6 +4,37 @@ 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.3.0] - 2026-07-12
+
+### Added
+
+- **Composition-aware status everywhere.** `gitstow status` now shows a Local Changes column (modified/staged/untracked counts) and a separate Remote column (in-sync/ahead/behind/diverged). The web dashboard rows, repo drawer, and help legend all use the same shared classifier — a repo with only staged or untracked files can no longer display as "clean". JSON output gains additive `local` and `remote` keys (all existing keys preserved).
+- **`gitstow fetch_repos` MCP tool** and a `last_fetched` timestamp in all JSON outputs — MCP clients can now see fetch state, matching the CLI and web dashboard.
+- **Untracked-repo hints on `list` and `status`.** Repos found on disk but not in the registry are now surfaced with a hint pointing at `workspace scan`, instead of being silently invisible.
+- **`doctor` detects orphaned workspaces**, and `workspace remove` now warns when repos would be left pointing at a removed workspace.
+- **`clone_timeout` setting** (`gitstow config set clone_timeout <seconds>`) — clone operations on very large repos no longer fail on a hardcoded 300s limit.
+- **macOS added to the CI test matrix**, matching the packaging classifiers.
+- **CHANGELOG gate in the release script** — `scripts/release.sh` now refuses to cut a release without a corresponding changelog entry.
+
+### Changed
+
+- **`add` clones multiple repos in parallel** and now detects remote mismatches and duplicate URLs before cloning, instead of silently registering whatever is already on disk.
+- **`search` now runs across repos in parallel**, matching `exec`.
+- **Pull, fetch, and the MCP server share one operations layer.** The MCP server now follows the same bulk-pull rule as the CLI and web dashboard (modified/staged skip, diverged skip, untracked-only pulls).
+- **`open` prefers `$VISUAL`/`$EDITOR`** over guessing an editor, and runs terminal editors in the foreground so they actually get a usable TTY.
+- **Disk sizing (`stats`, `repo info`) now shells out to `du`** instead of walking every file in Python — much faster on large repos.
+- **`collection import` honors each entry's recorded workspace** instead of dumping everything into one workspace, and now fails loudly (with a printed error) on newer file versions instead of exiting silently.
+- **The web dashboard's dependencies (FastAPI, uvicorn, Jinja2) moved to the optional `[ui]` extra.** Existing installs keep working; fresh CLI-only installs are ~15 packages lighter. Install with `pip install "gitstow[ui]"` to keep the dashboard.
+- **Bulk pull rule unified and refined (behavior change).** CLI `pull` and the dashboard's Pull-all now follow one rule: repos with modified or staged files are skipped (with the composition shown), diverged repos are skipped (fast-forward pull cannot succeed), and repos with only untracked files ARE pulled — previously the CLI skipped them forever while the web pulled everything.
+
+### Fixed
+
+- **`search`, `exec`, and `status` `--json` now emit pure JSON on an empty filter match** — previously they printed a "no repos match" banner and no payload at all, even with `--json` set.
+
+### Removed
+
+- **The Textual TUI (`gitstow tui`).** The web dashboard (`gitstow ui`) replaced it as the visual surface in v0.2.0; the TUI had been broken and parked since. Git history preserves it.
+
 ## [0.2.8] - 2026-07-12
 
 ### Fixed

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

@@ -25,21 +25,20 @@ src/gitstow/
 │   ├── 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
+│   ├── 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
+│   ├── status_model.py  # Shared repo-state classifier — local composition vs remote relationship
+│   ├── operations.py    # Shared filter + bulk-runner layer (pull/fetch/MCP)
+│   ├── locking.py       # Cross-process file lock guarding repos.yaml writes
 │   └── __init__.py
 ├── web/          # FastAPI browser dashboard (gitstow ui)
 │   ├── server.py          # FastAPI app, uvicorn runner, app.state.server stash
@@ -64,15 +63,18 @@ src/gitstow/
 - `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).
+- `core/status_model.py` — `RepoState` — the single source of truth for local (modified/staged/untracked) vs remote (in-sync/ahead/behind/diverged) classification, consumed by CLI, web, and JSON.
+- `core/operations.py` — Shared `filter_repo_pairs()` + bulk-runner used by `pull`, `fetch`, and the MCP server so surfaces can't drift.
+- `core/locking.py` — `file_lock()` cross-process advisory lock guarding `repos.yaml` against concurrent CLI/web writes.
 - `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.
+- `~/.gitstow/repos.lock` — Cross-process advisory lock file (`core/locking.py`) held during `repos.yaml` writes. Not user-facing data; safe to ignore/delete if orphaned.
 
 ### repos.yaml format
 ```yaml
@@ -86,14 +88,14 @@ active:
     tags: [active]
 ```
 
-## All Commands (32)
+## All Commands (37)
 
 **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`
+**Shell:** `shell pick`, `shell init`, `shell completions`, `shell setup`, `ui`
 **Setup:** `onboard`, `config show/set/path/migrate-root`, `doctor`, `install-skill`, `setup-ai`, `update`
 
 ## Development
@@ -101,9 +103,8 @@ active:
 ```bash
 cd ~/labs/projects/gitstow
 pip install -e ".[dev]"
-pytest                    # 44 tests
+pytest                    # full suite — keep green
 ruff check src/
-pip install -e ".[tui]"   # For TUI development
 ```
 
 ## Patterns
@@ -123,7 +124,7 @@ pip install -e ".[tui]"   # For TUI development
 
 - 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.
+- Keep CLI, 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.
@@ -139,6 +140,6 @@ pip install -e ".[tui]"   # For TUI development
 **Optional: MCP server** (`src/gitstow/mcp/server.py`)
 - For non-Claude-Code AI tools (Claude Desktop, Cursor, Windsurf)
 - Install: `pip install gitstow[mcp]`, entry point: `gitstow-mcp`
-- 13 tools + 3 resources, wraps same `core/` modules as CLI
+- 14 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.2.8 → gitstow-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitstow
-Version: 0.2.8
+Version: 0.3.0
 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,21 +26,25 @@ 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
+Requires-Dist: typer>=0.9
 Provides-Extra: dev
+Requires-Dist: fastapi>=0.110; extra == 'dev'
 Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: jinja2>=3.1; extra == 'dev'
+Requires-Dist: mcp>=1.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: python-multipart>=0.0.9; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: uvicorn>=0.27; extra == 'dev'
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.0; extra == 'mcp'
-Provides-Extra: tui
-Requires-Dist: textual>=0.50; extra == 'tui'
+Provides-Extra: ui
+Requires-Dist: fastapi>=0.110; extra == 'ui'
+Requires-Dist: jinja2>=3.1; extra == 'ui'
+Requires-Dist: python-multipart>=0.0.9; extra == 'ui'
+Requires-Dist: uvicorn>=0.27; extra == 'ui'
 Description-Content-Type: text/markdown
 
 # gitstow
@@ -62,8 +66,8 @@ Existing tools solve parts of this:
 ## Quick Start
 
 ```bash
-pipx install gitstow   # recommended
-# or: pip install gitstow
+pipx install "gitstow[ui]"   # recommended — CLI + browser dashboard
+# or: pip install gitstow    # CLI only; add [ui] for the dashboard
 
 # First-run setup (optional — works without it)
 gitstow onboard
@@ -99,6 +103,8 @@ gitstow workspace scan active
 ```bash
 gitstow add anthropic/claude-code facebook/react torvalds/linux
 ```
+Multiple URLs clone concurrently (bounded by `parallel_limit`, default 6) — a mismatched remote on an existing path errors instead of silently registering, and duplicate URLs in the same invocation are deduped.
+
 Creates (in a structured workspace):
 ```
 ~/oss/
@@ -117,8 +123,9 @@ gitstow -w oss pull             # Only update oss workspace
 gitstow pull --tag ai           # Only repos tagged 'ai'
 gitstow pull --exclude-tag stale # Everything except stale repos
 gitstow status                  # Git status dashboard
-gitstow -w active status --dirty # Dirty repos in active workspace
+gitstow -w active status --dirty # Repos with local changes in active workspace
 ```
+`status` shows local changes as a composition (e.g. "2 modified · 1 staged · 3 untracked") rather than a single "dirty" bucket, and keeps the remote relationship (ahead/behind/diverged) in its own column.
 
 ### Freeze & Tags
 ```bash
@@ -182,17 +189,13 @@ gsp                              # gitstow pull shorthand
 
 ### Browser Dashboard
 ```bash
-gitstow ui             # opens http://127.0.0.1:7853 in your browser
+pip install "gitstow[ui]"   # if you installed CLI-only
+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 terminal dashboard (SSH-friendly)
-```
-
 ### JSON Output
 Every command supports `--json` for scripting and AI consumption:
 ```bash
@@ -237,7 +240,6 @@ gitstow status --json
 | `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-0.2.8 → gitstow-0.3.0}/README.md

@@ -17,8 +17,8 @@ Existing tools solve parts of this:
 ## Quick Start
 
 ```bash
-pipx install gitstow   # recommended
-# or: pip install gitstow
+pipx install "gitstow[ui]"   # recommended — CLI + browser dashboard
+# or: pip install gitstow    # CLI only; add [ui] for the dashboard
 
 # First-run setup (optional — works without it)
 gitstow onboard
@@ -54,6 +54,8 @@ gitstow workspace scan active
 ```bash
 gitstow add anthropic/claude-code facebook/react torvalds/linux
 ```
+Multiple URLs clone concurrently (bounded by `parallel_limit`, default 6) — a mismatched remote on an existing path errors instead of silently registering, and duplicate URLs in the same invocation are deduped.
+
 Creates (in a structured workspace):
 ```
 ~/oss/
@@ -72,8 +74,9 @@ gitstow -w oss pull             # Only update oss workspace
 gitstow pull --tag ai           # Only repos tagged 'ai'
 gitstow pull --exclude-tag stale # Everything except stale repos
 gitstow status                  # Git status dashboard
-gitstow -w active status --dirty # Dirty repos in active workspace
+gitstow -w active status --dirty # Repos with local changes in active workspace
 ```
+`status` shows local changes as a composition (e.g. "2 modified · 1 staged · 3 untracked") rather than a single "dirty" bucket, and keeps the remote relationship (ahead/behind/diverged) in its own column.
 
 ### Freeze & Tags
 ```bash
@@ -137,17 +140,13 @@ gsp                              # gitstow pull shorthand
 
 ### Browser Dashboard
 ```bash
-gitstow ui             # opens http://127.0.0.1:7853 in your browser
+pip install "gitstow[ui]"   # if you installed CLI-only
+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 terminal dashboard (SSH-friendly)
-```
-
 ### JSON Output
 Every command supports `--json` for scripting and AI consumption:
 ```bash
@@ -192,7 +191,6 @@ gitstow status --json
 | `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-0.2.8 → gitstow-0.3.0}/docs/building/audit-2026-07-06.md

@@ -3,7 +3,7 @@
 **Date:** 2026-07-06
 **Auditor:** Claude (Fable 5), full read of all source (~9.5k lines Python), planning docs, tests, CI, packaging
 **Baseline:** commit `1aefe9a`, 139 tests passing
-**Status:** Awaiting greenlight — see [Implementation Waves](#implementation-waves)
+**Status:** COMPLETE — all three waves shipped (Wave 1 → 0.2.8; Waves 2+3 → 0.3.0)
 
 This document is the working tracker for the post-audit improvement effort. Each finding
 has an ID for reference. Check items off as waves land.
@@ -119,27 +119,27 @@ Opus (substantial) / Sonnet (mechanical) subagents.
 - [x] B12 path-containment check in CLI `remove --delete`
 - [x] B11 workspace label validation
 
-### Wave 2 — Shared status model (Opus) — NOT STARTED
-- [ ] P5 retire the Textual TUI (decision: retire; clears the third surface before the refactor)
-- [ ] A1/P4 `core/status_model.py`: one classifier separating local composition (modified/staged/untracked counts) from remote relationship (in-sync/ahead/behind/diverged) + frozen/missing overlays
-- [ ] Consume from CLI `status`, web dashboard, and `--json` payloads (per CLAUDE.md standards)
-- [ ] B6 one pull rule on both surfaces: modified/staged skip, untracked-only pulls (decision locked)
-- [ ] E1 parallelize web status gathering via `run_parallel` (off the event loop)
-- [ ] E2 batch RepoStore updates — `bulk()` (single save per bulk op)
-- [ ] Tests covering the classifier matrix
-
-### Wave 3 — Structure & polish (Sonnet-heavy, Opus for A3/A4) — NOT STARTED
-- [ ] P1/E3 parallel `add` clones; P2 remote-mismatch conflict error
-- [ ] E4 parallel `search`
-- [ ] A4 `core/operations.py` extraction (filters + bulk runner); collapse pull/fetch duplication
-- [ ] A3 MCP server consumes operations layer; add `last_fetched` everywhere (DOC3); new `fetch_repos` tool
-- [ ] P3 reconciliation hints surfacing untracked repos in `list`/`status` (human output only; JSON shapes unchanged)
-- [ ] B7 import preserves workspace; loud version error. B8 orphaned-workspace detection in doctor + workspace remove warning
-- [ ] B9 `$VISUAL`/`$EDITOR`-first open logic; terminal editors run foreground
-- [ ] A2 web stack → `[ui]` extra (decision locked; ships 0.3.0)
-- [ ] E5 `du`-backed disk sizing; E6 configurable `clone_timeout` setting
-- [ ] D2 macOS CI; D3 changelog gate in release.sh; D4 typer extra; D5 fetch/MCP tests
-- [ ] DOC1/DOC2 docs sync
+### Wave 2 — Shared status model (Opus) — COMPLETE (2026-07-12)
+- [x] P5 retire the Textual TUI (decision: retire; clears the third surface before the refactor)
+- [x] A1/P4 `core/status_model.py`: one classifier separating local composition (modified/staged/untracked counts) from remote relationship (in-sync/ahead/behind/diverged) + frozen/missing overlays
+- [x] Consume from CLI `status`, web dashboard, and `--json` payloads (per CLAUDE.md standards)
+- [x] B6 one pull rule on both surfaces: modified/staged skip, untracked-only pulls (decision locked)
+- [x] E1 parallelize web status gathering via `run_parallel` (off the event loop)
+- [x] E2 batch RepoStore updates — `bulk()` (single save per bulk op)
+- [x] Tests covering the classifier matrix
+
+### Wave 3 — Structure & polish (Sonnet-heavy, Opus for A3/A4) — COMPLETE (2026-07-12)
+- [x] P1/E3 parallel `add` clones; P2 remote-mismatch conflict error
+- [x] E4 parallel `search`
+- [x] A4 `core/operations.py` extraction (filters + bulk runner); collapse pull/fetch duplication
+- [x] A3 MCP server consumes operations layer; add `last_fetched` everywhere (DOC3); new `fetch_repos` tool
+- [x] P3 reconciliation hints surfacing untracked repos in `list`/`status` (human output only; JSON shapes unchanged)
+- [x] B7 import preserves workspace; loud version error. B8 orphaned-workspace detection in doctor + workspace remove warning
+- [x] B9 `$VISUAL`/`$EDITOR`-first open logic; terminal editors run foreground
+- [x] A2 web stack → `[ui]` extra (decision locked; ships 0.3.0)
+- [x] E5 `du`-backed disk sizing; E6 configurable `clone_timeout` setting
+- [x] D2 macOS CI; D3 changelog gate in release.sh; D4 typer extra; D5 fetch/MCP tests
+- [x] DOC1/DOC2 docs sync
 
 ## Verification notes
 

{gitstow-0.2.8 → gitstow-0.3.0}/docs/user/commands.md

@@ -83,8 +83,10 @@ gitstow add anthropic/claude-code --update
 - Repos are added to the default workspace (first configured), or the workspace specified with `-w`
 - If the repo is already tracked: skips (or pulls with `--update`)
 - If the path exists on disk but isn't tracked: registers it automatically
+- If the path exists on disk with a **different** remote than the one requested: errors with a remote-mismatch message instead of silently registering — move the directory or pick another workspace
 - If the path exists but isn't a git repo: errors
-- Multiple URLs are cloned in parallel
+- Equivalent URLs passed twice in the same invocation (e.g. HTTPS and SSH forms of the same repo) are deduplicated — only the first is cloned, the rest are reported as duplicates
+- Multiple URLs are cloned concurrently (bounded by `parallel_limit`, default 6), with per-clone retry via `--retry`
 
 ---
 
@@ -132,7 +134,9 @@ gitstow pull --include-frozen
 
 **Behavior:**
 - Frozen repos are skipped (shown as "Frozen" in summary)
-- Dirty repos are skipped (never risks losing local changes)
+- Repos with modified or staged files are skipped — the composition is shown in the summary (e.g. "2 modified · 1 staged")
+- Diverged repos (local and remote both have commits the other lacks) are skipped — resolve manually (rebase or merge)
+- Repos with only untracked files ARE pulled — an ff-only pull can't lose them
 - Uses `--ff-only` — won't create merge commits
 - Runs in parallel (configurable, default 6 concurrent)
 - Updates `last_pulled` timestamp on success
@@ -217,6 +221,8 @@ gitstow list --paths            # Show full paths
 gitstow list --json             # Machine-readable output
 ```
 
+If a workspace has repos on disk that aren't tracked yet, `list` prints a hint (e.g. `⚠ 2 untracked repos in oss — run gitstow workspace scan oss`) — suppressed by `--json`/`--quiet`.
+
 ---
 
 ### `gitstow status`
@@ -233,19 +239,25 @@ gitstow status [flags]
 |------|-------|-------------|
 | `--tag` | `-t` | Filter by tag. |
 | `--owner` | | Filter by owner. |
-| `--dirty` | | Show only dirty repos. |
+| `--dirty` | | Show only repos with local changes. |
 | `--json` | `-j` | JSON output. |
 | `--quiet` | `-q` | Minimal output. |
 
-Shows: repo name, branch, clean/dirty status (with file counts), ahead/behind remote, last commit message and date.
+Shows: repo name, branch, a **Local Changes** column (composition — e.g. "2 modified · 1 staged · 3 untracked", or "clean"), a separate **Remote** column (in-sync / ahead / behind / diverged / no-upstream), and last commit message and date. Local working-tree state and remote relationship are always shown as two separate dimensions — never a bare "dirty" bucket.
+
+**JSON output** (`--json`) keeps all existing flat fields (`dirty`, `staged`, `untracked`, `ahead`, `behind`, `clean`, `status_symbol`, ...) and adds two keys from the shared status model:
+- `local` — `{modified, staged, untracked, summary}`
+- `remote` — `{state, ahead, behind}`, where `state` is one of `in-sync` / `ahead` / `behind` / `diverged` / `no-upstream` / `unknown`
 
-**Status symbols:**
+**Status symbols** (legacy `status_symbol` JSON field):
 - `✓` clean
 - `*` unstaged changes
 - `+` staged changes
 - `?` untracked files
 - `❄` frozen
 
+Like `list`, `status` prints an untracked-repos hint per workspace when repos exist on disk but aren't tracked — suppressed by `--json`/`--quiet`.
+
 ---
 
 ### `gitstow remove`
@@ -406,12 +418,12 @@ gitstow open <owner/repo> [flags]
 
 | Flag | Short | Description |
 |------|-------|-------------|
-| `--editor` | `-e` | Open in default editor (VS Code, Cursor, etc.). |
+| `--editor` | `-e` | Open in your editor (`$VISUAL`/`$EDITOR`, then VS Code/Cursor). This is the default. |
 | `--browser` | `-b` | Open the repo on GitHub/GitLab in your browser. |
 | `--finder` | `-f` | Open in Finder/file manager. |
 | `--path` | `-p` | Just print the path to stdout. |
 
-With no flags, opens in the default editor. The `--path` flag is useful for shell integration:
+With no flags, opens in an editor: `$VISUAL`, then `$EDITOR`, then a fallback of VS Code (`code`) or Cursor (`cursor`) if installed. Terminal editors (`vi`, `vim`, `nvim`, `nano`, `emacs`, `hx`, `kak`, `micro`) run in the foreground since they need the TTY; GUI editors are launched detached. The `--path` flag is useful for shell integration:
 
 ```bash
 cd "$(gitstow open anthropic/claude-code -p)"
@@ -517,25 +529,12 @@ Completes:
 - Workspace labels for `-w/--workspace`
 - Tag names for `-t/--tag`
 
-### `gitstow tui`
-
-Interactive terminal dashboard built with [Textual](https://github.com/Textualize/textual). Requires `pip install gitstow[tui]`.
-
-Keyboard shortcuts:
-- `r` — Refresh
-- `p` — Pull all unfrozen repos
-- `P` — Pull selected repo only
-- `f` — Toggle freeze on selected repo
-- `w` — Cycle workspace filter
-- `t` — Cycle tag filter
-- `Enter` — Show repo details
-- `/` — Focus filter input
-- `q` — Quit
-
 ### `gitstow ui`
 
 Launch a local browser dashboard — a dark-themed web UI for daily repo management. Binds to `127.0.0.1` only; auto-opens your default browser.
 
+> Requires the `ui` extra: `pip install "gitstow[ui]"` (or `pipx install "gitstow[ui]"`). Running `gitstow ui` without it prints an install hint and exits.
+
 ```bash
 gitstow ui                     # http://127.0.0.1:7853
 gitstow ui --port 8080         # custom port
@@ -561,8 +560,8 @@ Every interactive element has a hover tooltip. There's also a `?` button in the
 | | Meaning | What to do |
 |---|---|---|
 | clean | Working tree matches HEAD; in sync with the last fetch | Nothing |
-| dirty | Uncommitted local changes | Commit or stash before pulling |
-| conflict | Dirty AND behind remote | Resolve locally before pulling |
+| dirty | Local changes — the label shows the composition (e.g. "2 modified · 1 staged · 3 untracked") | Commit/stash modified or staged files before pulling; untracked-only repos can still pull |
+| conflict | Local changes (modified/staged) AND behind remote, or local and remote have diverged | Resolve locally before pulling |
 | behind | Remote has commits you don't | Click the orange Pull button |
 | ahead | You have local commits not yet pushed | Consider `git push` |
 | frozen | Intentionally skipped by "Pull all" | Unfreeze from the ⋯ menu |
@@ -570,8 +569,8 @@ Every interactive element has a hover tooltip. There's also a `?` button in the
 **The Pull button color encodes priority**:
 
 - **Orange** `↓ Pull 5` — repo is behind; clicking fast-forwards by the shown count
-- **Ghost** (gray) — already up to date, or working tree is dirty/ahead. The button still works; it just won't change anything useful
-- **Disabled** — frozen, in conflict, or missing on disk
+- **Ghost** (gray) — already up to date, has local changes, or ahead. The button still works; it just won't change anything useful. (Untracked-only local changes still pull fine — a bulk pull only skips modified/staged files.)
+- **Disabled** — frozen, in conflict, diverged from remote, or missing on disk
 
 **Remote Δ** (`↑ N`, `↓ N`, or `—`) reflects your *last fetch*, not live remote state. If the counts look stale, pull (or run `git fetch --all` manually) to refresh them.
 
@@ -615,20 +614,26 @@ Change a setting.
 gitstow config set default_host gitlab.com
 gitstow config set prefer_ssh true
 gitstow config set parallel_limit 8
+gitstow config set clone_timeout 900
 ```
 
+Valid keys: `default_host`, `prefer_ssh`, `parallel_limit`, `clone_timeout` (clone timeout in seconds).
+
 > **Note:** The old `root_path` setting has been replaced by workspaces. Use `gitstow workspace add` to manage where repos are stored.
 
 ### `gitstow config migrate-root`
 
-Move all repos to a new root directory.
+Move one workspace's repos to a new directory and update that workspace's `path` in config.
 
 ```bash
-gitstow config migrate-root ~/new-location
-gitstow config migrate-root ~/new-location --copy    # Keep originals
-gitstow config migrate-root ~/new-location --yes      # Skip confirmation
+gitstow config migrate-root ~/new-location            # Moves the default workspace
+gitstow -w active config migrate-root ~/new-location  # Moves a specific workspace
+gitstow config migrate-root ~/new-location --copy      # Keep originals
+gitstow config migrate-root ~/new-location --yes       # Skip confirmation
 ```
 
+> **Note:** `migrate-root` has no local `--workspace` flag — target a non-default workspace with the global `-w` flag *before* `config`, not after `migrate-root`.
+
 ### `gitstow config path`
 
 Print the config file path.
@@ -774,13 +779,14 @@ Then add to your AI tool's config:
 
 Or use `gitstow setup-ai` to auto-detect and configure.
 
-### MCP Tools (12)
+### MCP Tools (14)
 
 | Tool | Description |
 |------|-------------|
 | `list_repos` | List repos with tag/owner/query filters |
 | `add_repo` | Clone a repo (shorthand or full URL) |
 | `pull_repos` | Bulk pull with tag/exclude/frozen filters |
+| `fetch_repos` | Bulk fetch (updates ahead/behind, no merge; includes frozen) |
 | `repo_status` | Git status dashboard across repos |
 | `repo_info` | Detailed single repo info |
 | `freeze_repo` | Freeze a repo (skip during pull) |
@@ -790,6 +796,7 @@ Or use `gitstow setup-ai` to auto-detect and configure.
 | `remove_repo` | Remove from tracking (optionally delete) |
 | `search_repos` | Grep across repos with pattern and glob |
 | `collection_stats` | Disk usage, owner breakdown, tag counts |
+| `list_workspaces` | List configured workspaces with repo counts |
 
 ### MCP Resources (3)
 

{gitstow-0.2.8 → gitstow-0.3.0}/docs/user/getting-started.md

@@ -22,10 +22,13 @@ Get gitstow installed and managing repos in about 5 minutes.
 pip install gitstow
 ```
 
+Want the browser dashboard (`gitstow ui`) too? Add the `[ui]` extra: `pip install "gitstow[ui]"`.
+
 Or with [pipx](https://pipx.pypa.io/) (recommended — keeps it isolated):
 
 ```bash
-pipx install gitstow
+pipx install "gitstow[ui]"   # CLI + browser dashboard
+# or: pipx install gitstow   # CLI only
 ```
 
 Verify it worked:
@@ -163,6 +166,7 @@ This is also done automatically during `gitstow onboard` and auto-updates when y
 ## Prefer a Browser?
 
 ```bash
+pip install "gitstow[ui]"   # only needed if you installed CLI-only above
 gitstow ui
 ```
 

{gitstow-0.2.8 → gitstow-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gitstow"
-version = "0.2.8"
+version = "0.3.0"
 description = "A git repository library manager — clone, organize, and maintain collections of repos you learn from"
 readme = "README.md"
 license = "MIT"
@@ -30,14 +30,10 @@ classifiers = [
 ]
 
 dependencies = [
-    "typer[all]>=0.9",
+    "typer>=0.9",
     "pyyaml>=6.0",
     "rich>=13.0",
     "beaupy>=3.0",
-    "fastapi>=0.110",
-    "uvicorn>=0.27",
-    "jinja2>=3.1",
-    "python-multipart>=0.0.9",
 ]
 
 [project.urls]
@@ -48,13 +44,21 @@ Issues = "https://github.com/rishmadaan/gitstow/issues"
 Changelog = "https://github.com/rishmadaan/gitstow/blob/main/CHANGELOG.md"
 
 [project.optional-dependencies]
+ui = [
+    "fastapi>=0.110",
+    "uvicorn>=0.27",
+    "jinja2>=3.1",
+    "python-multipart>=0.0.9",
+]
 dev = [
     "pytest>=8.0",
     "ruff>=0.4",
     "httpx>=0.27",
-]
-tui = [
-    "textual>=0.50",
+    "fastapi>=0.110",
+    "uvicorn>=0.27",
+    "jinja2>=3.1",
+    "python-multipart>=0.0.9",
+    "mcp>=1.0",
 ]
 mcp = [
     "mcp>=1.0",