gitstow 0.4.0__tar.gz → 0.5.0__tar.gz

{gitstow-0.4.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.4.0 → gitstow-0.5.0}/CHANGELOG.md

@@ -4,6 +4,13 @@ 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

{gitstow-0.4.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.4.0 → gitstow-0.5.0}/PKG-INFO

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

gitstow-0.5.0/docs/building/plans/2026-07-16-move-repo-between-workspaces.md

@@ -0,0 +1,95 @@
+# Move repos between workspaces — spec
+
+**Date:** 2026-07-16
+**Status:** approved, pending implementation (Codex, new branch)
+
+## What
+
+A repo can be reassigned from one workspace to another. The folder physically
+moves on disk to the target workspace's directory, and the catalog
+(`repos.yaml`) updates to match. Surfaced in the web dashboard's repo detail
+page and as a thin CLI command. No such capability exists today in any surface.
+
+## Core logic — `move_repo()` in `src/gitstow/core/operations.py`
+
+```python
+def move_repo(store: RepoStore, settings: Settings, key: str, from_ws: str, to_ws: str) -> Repo
+```
+
+Raises `ValueError` with a human-readable message on any rule violation; on
+success returns the new `Repo` and has updated disk + catalog.
+
+Rules, in order:
+
+1. **Resolve:** repo must exist in catalog at `from_ws:key`; target workspace
+   label must exist in settings and differ from `from_ws`. Else error.
+2. **Re-key by target layout:**
+   - target `flat` → new `owner = ""`, new key = `name`.
+   - target `structured` → keep current owner; if owner is empty, parse it
+     from `remote_url` via `core/url_parser.py`; if still no owner, refuse:
+     a structured workspace files repos under `owner/repo` and discovery
+     would never find a bare folder.
+3. **Collision checks (before touching anything):**
+   - catalog: no existing repo at `to_ws:new_key`.
+   - disk: destination path (per target layout) must not exist.
+4. **Disk move:** if the source folder exists, `shutil.move` it to the
+   destination (create the owner parent dir first when structured). If the
+   source is missing on disk, skip the move — catalog-only reassignment of
+   an already-missing repo is allowed. After a structured-source move, remove
+   the now-empty owner directory if empty (ignore errors).
+5. **Catalog update (single locked mutation):** remove old entry, add new
+   `Repo` with updated `workspace`/`owner`; preserve `remote_url`, `frozen`,
+   `added`, `last_pulled`, `last_fetched`; tags = existing tags plus the
+   target workspace's `auto_tags` (deduped, order preserved).
+
+Ordering note: validate everything first, then disk move, then catalog write.
+
+## Web UI — repo detail page
+
+- New section "Workspace" on `_repo_drawer.html` (between Tags and Freeze):
+  a `<select name="target">` listing all *other* workspace labels, plus a
+  Move button. `data-confirm` message states the folder will move on disk.
+  If there is only one workspace, render the section disabled with a hint
+  instead of an empty select.
+- New route `POST /repos/{workspace}/{key:path}/move` in
+  `src/gitstow/web/routes/repos.py`, matching the existing route patterns
+  there (path param style, error handling, redirect style). On success,
+  303-redirect to the repo's new detail URL (`/repos/{to_ws}/{new_key}`).
+  On `ValueError`, re-render the drawer with the error shown the same way
+  other drawer errors are shown.
+- No nested `<form>` tags (browsers silently drop them — verify against
+  parsed DOM, per CLAUDE.md).
+
+## CLI — `gitstow repo move`
+
+- `gitstow repo move <key> <target-workspace>` in `src/gitstow/cli/manage.py`,
+  mirroring the `repo tag`/`repo freeze` conventions (helpers for repo
+  resolution, Rich output, same error style). Wraps the same `move_repo()`.
+
+## Tests
+
+- `tests/` — core: structured→flat, flat→structured (owner parsed from URL),
+  flat→structured with no derivable owner (refused), disk+catalog collision
+  refusals, missing-on-disk catalog-only move, tag merge with auto_tags,
+  metadata preserved. Use tmp_path fixtures; no network.
+- Web: TestClient test for the move route (success redirect + error render).
+- CLI: one exercise of `repo move` via the existing CLI test harness pattern.
+- Full suite stays green (`pytest` from the worktree with
+  `PYTHONPATH=<worktree>/src`).
+
+## Out of scope
+
+Bulk/multi-select move, drag-and-drop, moving across hosts, MCP tool parity
+(can wrap `move_repo()` later).
+
+Nested-group owners (`group/subgroup/repo`) in structured workspaces land at
+`root/group/subgroup/repo` — the same place `gitstow add` clones them today —
+which two-level structured discovery cannot see (pre-existing limitation
+across add/scan/doctor, flagged in Codex review pass 6; fix is a separate
+discovery feature).
+
+## Verification (post-implementation, by the session lead — not Codex)
+
+Review the full diff; run the suite; then verify in a real browser per
+CLAUDE.md web standards (form structure in parsed DOM, actual move of a
+scratch repo in `/private/tmp/gitstow-demo`).

{gitstow-0.4.0 → gitstow-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gitstow"
-version = "0.4.0"
+version = "0.5.0"
 description = "A git repository library manager — clone, organize, and maintain collections of repos you learn from"
 readme = "README.md"
 license = "MIT"

{gitstow-0.4.0 → gitstow-0.5.0}/src/gitstow/__init__.py

@@ -1,3 +1,3 @@
 """gitstow — a git repository library manager."""
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"

{gitstow-0.4.0 → gitstow-0.5.0}/src/gitstow/cli/manage.py

@@ -17,6 +17,7 @@ from gitstow.core.git import (
     format_size,
     is_git_repo,
 )
+from gitstow.core.operations import move_repo
 from gitstow.core.repo import RepoStore
 from gitstow.core.status_model import classify
 from gitstow.cli.helpers import resolve_repo
@@ -176,6 +177,36 @@ def remove_tags(
         console.print(f"  [dim]None of those tags were on {repo.key}.[/dim]")
 
 
+@manage_app.command("move")
+def move(
+    ctx: typer.Context,
+    repo_key: str = typer.Argument(help="Repo to move (owner/repo or name)."),
+    target: str = typer.Argument(help="Target workspace label."),
+) -> None:
+    """[bold]Move[/bold] a repo to another workspace — relocates its folder on disk.
+
+    \b
+    Examples:
+      gitstow repo move anthropic/claude-code active
+      gitstow -w oss repo move dupe active
+    """
+    settings = load_config()
+    store = RepoStore()
+    ws_label = (ctx.obj or {}).get("workspace")
+    repo, _ = resolve_repo(store, settings, repo_key, ws_label)
+
+    try:
+        moved = move_repo(store, settings, repo.key, repo.workspace, target)
+    except ValueError as exc:
+        err_console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=1)
+
+    console.print(
+        f"  [green]✓[/green] Moved {repo.key} → workspace [bold]{target}[/bold] "
+        f"(now [cyan]{moved.key}[/cyan])."
+    )
+
+
 @manage_app.command("tags")
 def list_tags(
     quiet: bool = typer.Option(False, "--quiet", "-q", help="One tag per line."),

{gitstow-0.4.0 → gitstow-0.5.0}/src/gitstow/core/git.py

@@ -280,6 +280,17 @@ def get_last_commit(repo_path: Path) -> CommitInfo:
     )
 
 
+def repair_worktrees(repo_path: Path) -> bool:
+    """Run `git worktree repair` from a repo that was just relocated.
+
+    Linked worktrees keep absolute back-pointers into the main repo's
+    .git/worktrees/; after the main repo moves, repair rewrites them.
+    Returns True on success.
+    """
+    result = _run_git(["worktree", "repair"], cwd=repo_path)
+    return result.returncode == 0
+
+
 def get_branch(repo_path: Path) -> str:
     """Get the current branch name."""
     result = _run_git(["branch", "--show-current"], cwd=repo_path)