gitstow 0.3.0__tar.gz → 0.5.0__tar.gz

{gitstow-0.3.0 → gitstow-0.5.0}/AGENTS.md

@@ -1,8 +1,8 @@
-# gitstow - AI Developer Guide
+# 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.
+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
 
@@ -14,14 +14,15 @@ A CLI tool that manages collections of git repositories across multiple workspac
 
 ## Product Standards
 
-- 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.
+- For `web/` changes, HTTP-level tests (TestClient, curl) are necessary but not sufficient — they pass on bugs below the HTTP layer. Before calling a `web/` change done, verify form structure against the parsed DOM (browsers silently drop nested `<form>` tags) and verify layout/geometry in a real browser (`overflow-x: auto` clips absolutely-positioned children even without horizontal overflow).
 
 ## Key Concept: Workspaces
 
-Repos are organized into **workspaces** - directories with a label and layout mode:
+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)
 
@@ -40,60 +41,62 @@ 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
 │   ├── 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/        # Claude Code skill (SKILL.md)
     └── SKILL.md
 ```
 
 **Key rules:**
-1. CLI never touches git directly - it calls `core/git.py`
+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
+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.
+- `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).
+- `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.
 
 ## Data Files
 
-- `~/.gitstow/config.yaml` - Settings (workspaces list, default host, SSH pref).
-- `~/.gitstow/repos.yaml` - Repo metadata nested by workspace label. Central location.
+- `~/.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
 oss:
-  anthropic/Codex:
-    remote_url: https://github.com/anthropic/Codex.git
+  anthropic/claude-code:
+    remote_url: https://github.com/anthropic/claude-code.git
     tags: [ai]
 active:
   gitstow:
@@ -101,14 +104,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
@@ -116,11 +119,13 @@ 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
 ```
 
+- **Worktree gotcha:** tests run from a git worktree silently exercise the main checkout (the editable install points at the primary clone). From a worktree, run `PYTHONPATH=<worktree>/src .venv/bin/python -m pytest -q`.
+- **Releasing publishes to PyPI.** `scripts/release.sh X.Y.Z` tags and pushes; the tag triggers a public PyPI publish. Require the user's explicit in-session instruction to release — plan approval or a "let's go" on implementation does not cover it.
+
 ## Patterns
 
 - `--json -j` and `--quiet -q` on all main commands
@@ -132,19 +137,19 @@ pip install -e ".[tui]"   # For TUI development
 - 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)
+- 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`
+**Primary: Claude Code skill** (`src/gitstow/skill/SKILL.md`)
+- Installed to `~/.claude/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
+- Zero context cost when inactive — only loaded when task matches the skill description
+- Claude 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)
+- 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.5.0/BACKLOG.md

@@ -0,0 +1,43 @@
+# Backlog
+
+Post-v0.1.0 improvements tracked here. See [GitHub Issues](https://github.com/rishmadaan/gitstow/issues) for discussion.
+
+## Enhancements
+
+- [x] **TUI: expand beyond read-only dashboard** (#1) — Added pull selected (P), workspace cycling (w), tag cycling (t)
+- [x] **Shell completion for repo names** (#2) — `gitstow shell completions` for bash/zsh/fish; `--quiet` on list/tags/workspace list
+- [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/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.
+- [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
+
+- [x] **Record demo GIF for README** (#7) — Recorded with VHS, embedded in README
+
+## Post-0.3.0 follow-ups
+
+Triaged non-blocking items from the 2026-07 audit remediation (see
+[docs/building/audit-2026-07-06.md](docs/building/audit-2026-07-06.md) for the full effort).
+
+- [ ] **URL parser: schemeless multi-dot hosts** — `dev.azure.com/org/project/_git/repo` without
+  `https://` parses as owner/repo shorthand and builds a garbage clone URL (`_LOOKS_LIKE_HOST`
+  regex can't match a multi-dot first segment). Pre-existing; 0.3.1 candidate.
+- [ ] **Route search subprocesses through a hardened runner** — `git grep`/`rg` in `cli/search.py`
+  and `mcp/server.py` shell raw `subprocess.run` without the `GIT_TERMINAL_PROMPT=0`/`LC_ALL=C`
+  env applied to all other git calls. Local-only operations, negligible risk — consistency cleanup.
+- [ ] **Test strengthening batch** — frozen-collapse MCP test needs two frozen same-named repos;
+  `run_bulk` missing-status retry + `on_attempt` callback untested; locking mutual-exclusion test
+  passes without a lock (use an event-based barrier); status JSON legacy-key test covers 3/13 keys.
+- [ ] **Small edges** — `add` on an on-disk repo with no remote falls through to a doomed clone;
+  whitespace-only `$EDITOR` raises IndexError; fully-untracked workspaces never get the untracked
+  hint (early return; `doctor` covers); dashboard vs single-row-refresh number sources diverge for
+  orphaned-workspace repos.
+- [ ] **Product call: `pull --force` escape hatch** — CLI explicit args follow the bulk skip rule
+  while a web single-row Pull click pulls unconditionally; a `--force` flag would reconcile the
+  "explicit intent" asymmetry.
+- [ ] **Product call: frozen + diverged + `--include-frozen`** — surfaces as an ff-only error row
+  instead of a clean "diverged" skip (check `remote_state` directly in the worker if the messaging
+  matters).

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

@@ -4,6 +4,36 @@ 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.5.0] - 2026-07-16
+
+### Added
+
+- **Move repos between workspaces.** From the dashboard's repo detail page (new Workspace section: pick a target, confirm, done) or the new `gitstow repo move <repo> <workspace>` command. The folder physically relocates on disk following the target workspace's layout (structured `owner/repo` vs flat), the catalog updates in the same locked operation, existing tags are kept and the target's auto-tags merge in, and repos that own linked git worktrees get `git worktree repair` run automatically after the move.
+- **Move safety net.** Collisions are refused before anything is touched (catalog, disk, even dangling symlinks); sources that can't move safely are refused with actionable errors (symlinked repos, linked-worktree gitfiles, relative `.git` symlinks, non-repo directories squatting on a tracked path); catalog keys can never escape their workspace on disk; and if anything fails mid-move, the rollback restores the folder without ever deleting data it can't prove is its own.
+
+## [0.4.0] - 2026-07-12
+
+### Added
+
+- **Dashboard filters that actually filter.** The search box, workspace dropdown, and Hide-frozen toggle now work — instant client-side filtering that survives auto-refresh and pull updates.
+- **Settings save.** The Settings page persists changes for real (and gains Parallel limit + Clone timeout fields).
+- **`local` badge.** Repos without an upstream remote show a `local` Remote Δ badge; bulk pulls skip them with a clear reason instead of failing every run.
+- **Responsive dashboard.** Works down to half-monitor width — columns collapse by priority, the table scrolls within its own container, and row menus flip upward when space runs out.
+- **Last-fetched visibility.** The repo detail page shows when each repo was last pulled AND last fetched (hover for exact times); Remote Δ tooltips state which fetch the counts reflect.
+
+### Changed
+
+- **Fully offline dashboard.** htmx and both fonts are now bundled — no CDN, no network needed for the UI itself.
+- **Styled confirmations.** Native browser confirm/alert dialogs replaced with an in-app dialog (also makes the dashboard automatable).
+- **Web collection import honors recorded workspaces**, sharing one implementation with the CLI.
+- **Honest metrics chips.** Diverged and missing repos get their own hero chips instead of hiding inside 'conflict'; the pull summary reads 'N attempted' with exclusions stated.
+- **Cleaner micro-interactions.** Styled file picker, a LIVE dot that actually goes red when the server is unreachable, keyboard-visible focus rings, Escape closes menus, add-repo shows a Cloning… state.
+
+### Fixed
+
+- **Pull all / Fetch all spinners stop when the operation completes** (htmx indicator/disable double-count).
+- **Repo detail timestamps** no longer render raw machine format.
+
 ## [0.3.0] - 2026-07-12
 
 ### Added

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

@@ -107,6 +107,9 @@ pytest                    # full suite — keep green
 ruff check src/
 ```
 
+- **Worktree gotcha:** tests run from a git worktree silently exercise the main checkout (the editable install points at the primary clone). From a worktree, run `PYTHONPATH=<worktree>/src .venv/bin/python -m pytest -q`.
+- **Releasing publishes to PyPI.** `scripts/release.sh X.Y.Z` tags and pushes; the tag triggers a public PyPI publish. Require the user's explicit in-session instruction to release — plan approval or a "let's go" on implementation does not cover it.
+
 ## Patterns
 
 - `--json -j` and `--quiet -q` on all main commands
@@ -128,6 +131,7 @@ ruff check src/
 - 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.
+- For `web/` changes, HTTP-level tests (pytest TestClient, curl) are necessary but not sufficient — they pass on bugs that live below the HTTP layer. Before calling a UI change done, verify form structure against the parsed DOM (browsers silently drop nested `<form>` tags) and verify layout/geometry in a real browser (e.g. `overflow-x: auto` clips absolutely-positioned children even without horizontal overflow).
 
 ## AI Integration
 

{gitstow-0.3.0 → gitstow-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitstow
-Version: 0.3.0
+Version: 0.5.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