gitstow 0.1.0__py3-none-any.whl

gitstow/skill/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: gitstow
+description: >
+  ALWAYS use this skill when the user wants to clone, add, or download a git
+  repository — gitstow replaces raw `git clone`. Also activate for: "update repos",
+  "pull all", "list repos", "check repo status", "freeze/tag a repo", "search across
+  repos", "which repos need pushing", or any multi-repo management. Trigger on any
+  git URL (github.com, gitlab.com, etc.) or owner/repo shorthand.
+allowed-tools: Bash(gitstow *), Read
+---
+
+# gitstow — Repo Manager Operator Guide
+
+You are an expert operator of `gitstow`, a CLI tool that replaces `git clone` and manages repos across multiple workspaces. **Every repo should be added via `gitstow add`, never raw `git clone`** — this ensures it's tracked, organized, and visible in status dashboards.
+
+## Key Concept: Workspaces
+
+gitstow organizes repos into **workspaces** — directories with a label, layout mode, and optional auto-tags:
+
+- **structured** layout: `workspace/owner/repo/` (good for open-source collections)
+- **flat** layout: `workspace/repo/` (good for active projects)
+
+Use `-w <label>` on any command to filter to a specific workspace.
+
+## Cardinal Rule: Never Use Raw `git clone`
+
+When the user asks to clone, download, or get a repo, **always use `gitstow add`**. Never fall back to `git clone` — even for a single repo. `gitstow add` clones AND tracks the repo, so it appears in status dashboards and bulk operations.
+
+```bash
+# WRONG — repo cloned but invisible to gitstow
+git clone https://github.com/owner/repo
+
+# RIGHT — repo tracked, organized into workspace, visible everywhere
+gitstow add owner/repo
+gitstow -w active add owner/repo    # clone into a specific workspace
+```
+
+## Before Running Any Command
+
+**Pre-flight check** — on first use in a session, verify gitstow is available:
+
+```bash
+gitstow --version
+```
+
+If not installed: suggest `pip install gitstow` or `pipx install gitstow`.
+If installed but not configured (no `~/.gitstow/config.yaml`): guide with `gitstow onboard`.
+
+## Core Principle: Use --json for Machine Output
+
+When running gitstow commands programmatically, always use `--json --quiet` flags to parse structured output. Present a clean summary to the user, not raw JSON.
+
+For commands shown to the user to run themselves, use the human-readable form (no --json).
+
+## Command Decision Tree
+
+| User wants to... | Command |
+|---|---|
+| Add/clone a repo | `gitstow add "owner/repo"` or `gitstow add "url"` |
+| Add to specific workspace | `gitstow -w active add "owner/repo"` |
+| Add multiple repos | `gitstow add repo1 repo2 repo3` |
+| Update all repos | `gitstow pull` |
+| Update one workspace | `gitstow -w oss pull` |
+| Update repos by tag | `gitstow pull --tag ai` |
+| List all repos | `gitstow list` |
+| List one workspace | `gitstow -w active list` |
+| Search repos | `gitstow list searchterm` |
+| Check git status | `gitstow status` |
+| Status for one workspace | `gitstow -w active status` |
+| See dirty repos only | `gitstow status --dirty` |
+| Freeze a repo | `gitstow repo freeze owner/repo` |
+| Unfreeze a repo | `gitstow repo unfreeze owner/repo` |
+| Tag a repo | `gitstow repo tag owner/repo tagname` |
+| Remove a tag | `gitstow repo untag owner/repo tagname` |
+| List all tags | `gitstow repo tags` |
+| Repo details | `gitstow repo info owner/repo` |
+| Remove a repo | `gitstow remove owner/repo` |
+| Adopt existing repos | `gitstow migrate /path/to/repo` |
+| Run command in all repos | `gitstow exec -- git log -1 --oneline` |
+| Search across all repos | `gitstow search "pattern" --glob "*.py"` |
+| Open in editor | `gitstow open owner/repo` |
+| Open in browser | `gitstow open owner/repo --browser` |
+| Collection stats | `gitstow stats` |
+| Export collection | `gitstow collection export -o repos.yaml` |
+| Import collection | `gitstow collection import repos.yaml` |
+| See current config | `gitstow config show` |
+| Change settings | `gitstow config set key value` |
+| List workspaces | `gitstow workspace list` |
+| Add a workspace | `gitstow workspace add ~/path --label name --layout flat` |
+| Remove a workspace | `gitstow workspace remove name` |
+| Scan workspace for repos | `gitstow workspace scan name` |
+| Run setup wizard | `gitstow onboard` |
+| Health check | `gitstow doctor` |
+
+## URL Shorthand
+
+gitstow supports shorthand — GitHub is the default host:
+
+```bash
+# These are equivalent:
+gitstow add anthropic/claude-code
+gitstow add https://github.com/anthropic/claude-code
+```
+
+For non-GitHub repos, use full URLs:
+```bash
+gitstow add https://gitlab.com/group/project
+gitstow add git@bitbucket.org:owner/repo.git
+```
+
+## Common Workflows
+
+### "Add this repo" / "Clone this"
+```bash
+gitstow add "owner/repo" --json --quiet
+```
+Parse the JSON result and tell the user: repo name, where it was cloned, success/failure.
+
+### "Add to my active projects workspace"
+```bash
+gitstow -w active add "owner/repo" --json --quiet
+```
+
+### "Update everything" / "Pull all repos"
+```bash
+gitstow pull --json --quiet
+```
+Parse results and summarize: N pulled, N up to date, N skipped, N errors.
+
+### "What repos do I have?"
+```bash
+gitstow list --json
+```
+Present as a clean grouped list. Mention total count, frozen repos, and tags.
+
+### "Which repos need pushing?" / "What's dirty?"
+```bash
+gitstow status --dirty --json
+```
+
+### "Show me just my active project status"
+```bash
+gitstow -w active status --json
+```
+
+### "Freeze this repo" / "Don't update this anymore"
+```bash
+gitstow repo freeze owner/repo
+```
+
+### "What's the status of X?"
+```bash
+gitstow repo info owner/repo --json
+```
+
+### "Search for something across all repos"
+```bash
+gitstow search "pattern" --json --quiet
+```
+
+### "Run this command in every repo"
+```bash
+gitstow exec --json -- git log -1 --oneline
+```
+
+### "How much disk space do my repos use?"
+```bash
+gitstow stats --json
+```
+
+### "Share my repo list" / "Export my collection"
+```bash
+gitstow collection export -o /tmp/repos.yaml
+```
+
+### "Point gitstow at my existing projects"
+```bash
+gitstow workspace add ~/labs/projects --label active --layout flat --auto-tag active
+gitstow workspace scan active
+```
+
+## Bulk Operations from a File
+
+```bash
+cat > /tmp/repos.txt << 'EOF'
+anthropic/claude-code
+facebook/react
+torvalds/linux
+EOF
+
+cat /tmp/repos.txt | gitstow add --quiet --json
+```
+
+## Safety Rules
+
+1. **Always quote URLs** in shell commands
+2. **Don't run `gitstow onboard`** without telling the user — it's interactive
+3. **Don't run `gitstow remove --delete`** without explicit user confirmation — it deletes files
+4. **Use `--json --quiet`** when parsing output programmatically
+5. **Check `gitstow doctor`** if something seems broken
+
+## Note on MCP Server
+
+An optional MCP server exists (`pip install gitstow[mcp]`, run `gitstow-mcp`) for AI tools that can't run CLI commands (Claude Desktop, Cursor). **You don't need it** — this skill gives you full access to all gitstow commands via Bash. The MCP server provides the same operations but costs tokens in every conversation even when idle.
+
+## File Locations
+
+- Config: `~/.gitstow/config.yaml`
+- Repo metadata: `~/.gitstow/repos.yaml` (central, nested by workspace)
+- Repos: across configured workspaces (default first workspace: `~/oss/`)

gitstow/tui/__init__.py

@@ -0,0 +1 @@
+"""gitstow TUI — interactive terminal dashboard built with Textual."""

gitstow/tui/app.py

@@ -0,0 +1,384 @@
+"""gitstow TUI — main application."""
+
+from __future__ import annotations
+
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Container, Horizontal
+from textual.widgets import DataTable, Footer, Header, Static, Input
+from textual.screen import ModalScreen
+from textual import work
+
+from gitstow.core.config import load_config, Workspace
+from gitstow.core.git import get_status, is_git_repo, pull as git_pull, RepoStatus
+from gitstow.core.repo import Repo, RepoStore
+
+
+class RepoDetailScreen(ModalScreen):
+    """Modal screen showing detailed info for a repo."""
+
+    BINDINGS = [
+        Binding("escape", "dismiss", "Close"),
+        Binding("f", "toggle_freeze", "Freeze/Unfreeze"),
+    ]
+
+    def __init__(self, repo: Repo, status: RepoStatus | None, ws: Workspace):
+        super().__init__()
+        self.repo = repo
+        self.repo_status = status
+        self.ws = ws
+
+    def compose(self) -> ComposeResult:
+        frozen_str = "YES" if self.repo.frozen else "no"
+        tags_str = ", ".join(self.repo.tags) if self.repo.tags else "none"
+        branch = self.repo_status.branch if self.repo_status else "unknown"
+        status_str = self.repo_status.status_symbol if self.repo_status else "?"
+
+        info = (
+            f"[bold]{self.repo.key}[/bold]  [dim]({self.repo.workspace})[/dim]\n\n"
+            f"  Remote:      {self.repo.remote_url}\n"
+            f"  Path:        {self.repo.get_path(self.ws.get_path())}\n"
+            f"  Branch:      {branch}\n"
+            f"  Status:      {status_str}\n"
+            f"  Frozen:      {frozen_str}\n"
+            f"  Tags:        {tags_str}\n"
+            f"  Workspace:   {self.repo.workspace}\n"
+            f"  Added:       {self.repo.added or 'unknown'}\n"
+            f"  Last pulled: {self.repo.last_pulled or 'never'}\n\n"
+            f"  [dim]Press [bold]f[/bold] to toggle freeze, [bold]Escape[/bold] to close[/dim]"
+        )
+        yield Container(
+            Static(info, id="detail-content"),
+            id="detail-modal",
+        )
+
+    def action_toggle_freeze(self) -> None:
+        store = RepoStore()
+        store.update(self.repo.key, workspace=self.repo.workspace, frozen=not self.repo.frozen)
+        self.repo.frozen = not self.repo.frozen
+        self.dismiss(True)  # Signal refresh needed
+
+
+class GitstowApp(App):
+    """gitstow interactive dashboard."""
+
+    TITLE = "gitstow"
+    SUB_TITLE = "repo library manager"
+
+    CSS = """
+    #header-bar {
+        dock: top;
+        height: 1;
+        background: $primary;
+        color: $text;
+        padding: 0 1;
+    }
+    #filter-bar {
+        dock: top;
+        height: 3;
+        padding: 0 1;
+    }
+    #filter-input {
+        width: 40;
+    }
+    #summary-bar {
+        dock: bottom;
+        height: 1;
+        background: $surface;
+        color: $text-muted;
+        padding: 0 1;
+    }
+    #detail-modal {
+        align: center middle;
+        width: 70;
+        height: 20;
+        border: tall $primary;
+        background: $surface;
+        padding: 1 2;
+    }
+    DataTable {
+        height: 1fr;
+    }
+    """
+
+    BINDINGS = [
+        Binding("q", "quit", "Quit"),
+        Binding("r", "refresh", "Refresh"),
+        Binding("p", "pull_all", "Pull All"),
+        Binding("P", "pull_selected", "Pull Selected", show=False),
+        Binding("f", "toggle_freeze", "Freeze/Unfreeze"),
+        Binding("w", "cycle_workspace", "Workspace"),
+        Binding("t", "cycle_tag", "Tag"),
+        Binding("enter", "show_detail", "Details"),
+        Binding("/", "focus_filter", "Filter"),
+        Binding("escape", "clear_filter", "Clear Filter"),
+    ]
+
+    def __init__(self):
+        super().__init__()
+        self.settings = load_config()
+        self.store = RepoStore()
+        self._ws_map: dict[str, Workspace] = {}  # global_key -> workspace
+        self._repos: list[Repo] = []
+        self._statuses: dict[str, RepoStatus] = {}
+        self._filter = ""
+        self._ws_filter: str = ""  # "" = all workspaces
+        self._tag_filter: str = ""  # "" = all tags
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield Horizontal(
+            Static(" Filter: ", id="filter-label"),
+            Input(placeholder="type to filter...", id="filter-input"),
+            id="filter-bar",
+        )
+        yield DataTable(id="repo-table")
+        yield Static("Loading...", id="summary-bar")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        table = self.query_one("#repo-table", DataTable)
+        table.cursor_type = "row"
+        table.add_columns(
+            "Repo", "Branch", "Status", "Ahead/Behind",
+            "Frozen", "Tags", "Last Pulled",
+        )
+        self.load_repos()
+
+    def on_input_changed(self, event: Input.Changed) -> None:
+        if event.input.id == "filter-input":
+            self._filter = event.value.lower()
+            self._refresh_table()
+
+    def action_focus_filter(self) -> None:
+        self.query_one("#filter-input", Input).focus()
+
+    def action_clear_filter(self) -> None:
+        inp = self.query_one("#filter-input", Input)
+        inp.value = ""
+        self._filter = ""
+        self._refresh_table()
+        self.query_one("#repo-table", DataTable).focus()
+
+    @work(thread=True)
+    def load_repos(self) -> None:
+        """Load repos and their statuses in a background thread."""
+        self.store.load()
+        self._repos = self.store.list_all()
+
+        # Build workspace map
+        self._ws_map = {}
+        for repo in self._repos:
+            ws = self.settings.get_workspace(repo.workspace)
+            if ws:
+                self._ws_map[repo.global_key] = ws
+
+        for repo in self._repos:
+            ws = self._ws_map.get(repo.global_key)
+            if not ws:
+                continue
+            path = repo.get_path(ws.get_path())
+            if path.exists() and is_git_repo(path):
+                self._statuses[repo.global_key] = get_status(path)
+
+        self.call_from_thread(self._refresh_table)
+
+    def _refresh_table(self) -> None:
+        table = self.query_one("#repo-table", DataTable)
+        table.clear()
+
+        filtered = self._repos
+        if self._ws_filter:
+            filtered = [r for r in filtered if r.workspace == self._ws_filter]
+        if self._tag_filter:
+            filtered = [r for r in filtered if self._tag_filter in r.tags]
+        if self._filter:
+            filtered = [
+                r for r in filtered
+                if self._filter in r.key.lower()
+                or any(self._filter in t for t in r.tags)
+                or self._filter in r.owner.lower()
+            ]
+
+        for repo in filtered:
+            status = self._statuses.get(repo.global_key)
+
+            branch = status.branch if status else "?"
+            status_str = status.status_symbol if status else "?"
+            ab = status.ahead_behind_str if status else "?"
+            frozen = "❄" if repo.frozen else ""
+            tags = ", ".join(repo.tags) if repo.tags else ""
+            pulled = self._format_pulled(repo.last_pulled)
+
+            table.add_row(
+                repo.key, branch, status_str, ab,
+                frozen, tags, pulled,
+                key=repo.global_key,
+            )
+
+        # Summary
+        total = len(filtered)
+        clean = sum(1 for r in filtered if self._statuses.get(r.global_key, None) and self._statuses[r.global_key].clean)
+        frozen = sum(1 for r in filtered if r.frozen)
+        dirty = total - clean - frozen
+        summary = f" {total} repos | {clean} clean | {dirty} dirty | {frozen} frozen"
+        if self._ws_filter:
+            summary += f" | ws: {self._ws_filter}"
+        if self._tag_filter:
+            summary += f" | tag: {self._tag_filter}"
+        if self._filter:
+            summary += f" | filter: '{self._filter}'"
+        self.query_one("#summary-bar", Static).update(summary)
+
+    def action_refresh(self) -> None:
+        self.query_one("#summary-bar", Static).update(" Refreshing...")
+        self.load_repos()
+
+    @work(thread=True)
+    def action_pull_all(self) -> None:
+        """Pull all unfrozen repos."""
+        self.call_from_thread(
+            lambda: self.query_one("#summary-bar", Static).update(" Pulling...")
+        )
+
+        from datetime import datetime
+        pulled = 0
+        for repo in self._repos:
+            if repo.frozen:
+                continue
+            ws = self._ws_map.get(repo.global_key)
+            if not ws:
+                continue
+            path = repo.get_path(ws.get_path())
+            if not path.exists() or not is_git_repo(path):
+                continue
+            status = self._statuses.get(repo.global_key)
+            if status and not status.clean:
+                continue
+
+            result = git_pull(path)
+            if result.success:
+                pulled += 1
+                self.store.update(repo.key, workspace=repo.workspace, last_pulled=datetime.now().isoformat())
+
+        self.call_from_thread(self.load_repos)
+        self.call_from_thread(
+            lambda: self.notify(f"Pulled {pulled} repos")
+        )
+
+    def action_cycle_workspace(self) -> None:
+        """Cycle workspace filter: all → ws1 → ws2 → ... → all."""
+        labels = [ws.label for ws in self.settings.get_workspaces()]
+        if not labels:
+            return
+        if not self._ws_filter:
+            self._ws_filter = labels[0]
+        else:
+            try:
+                idx = labels.index(self._ws_filter)
+                self._ws_filter = labels[idx + 1] if idx + 1 < len(labels) else ""
+            except ValueError:
+                self._ws_filter = ""
+        self._refresh_table()
+        label = self._ws_filter or "all"
+        self.notify(f"Workspace: {label}")
+
+    def action_cycle_tag(self) -> None:
+        """Cycle tag filter: all → tag1 → tag2 → ... → all."""
+        all_tags = sorted(self.store.all_tags())
+        if not all_tags:
+            return
+        if not self._tag_filter:
+            self._tag_filter = all_tags[0]
+        else:
+            try:
+                idx = all_tags.index(self._tag_filter)
+                self._tag_filter = all_tags[idx + 1] if idx + 1 < len(all_tags) else ""
+            except ValueError:
+                self._tag_filter = ""
+        self._refresh_table()
+        label = self._tag_filter or "all"
+        self.notify(f"Tag: {label}")
+
+    @work(thread=True)
+    def action_pull_selected(self) -> None:
+        """Pull only the selected repo."""
+        repo, ws = self.call_from_thread(self._get_selected_repo)
+        if not repo or not ws:
+            return
+        if repo.frozen:
+            self.call_from_thread(lambda: self.notify(f"{repo.key} is frozen", severity="warning"))
+            return
+        path = repo.get_path(ws.get_path())
+        if not path.exists() or not is_git_repo(path):
+            self.call_from_thread(lambda: self.notify(f"{repo.key} not on disk", severity="error"))
+            return
+        self.call_from_thread(
+            lambda: self.query_one("#summary-bar", Static).update(f" Pulling {repo.key}...")
+        )
+        result = git_pull(path)
+        if result.success:
+            from datetime import datetime
+            self.store.update(repo.key, workspace=repo.workspace, last_pulled=datetime.now().isoformat())
+            self.call_from_thread(lambda: self.notify(f"Pulled {repo.key}"))
+        else:
+            self.call_from_thread(lambda: self.notify(f"Failed: {result.error}", severity="error"))
+        self.call_from_thread(self.load_repos)
+
+    def _get_selected_repo(self) -> tuple[Repo | None, Workspace | None]:
+        """Get the repo and workspace for the currently selected table row."""
+        table = self.query_one("#repo-table", DataTable)
+        if table.cursor_row is None:
+            return None, None
+        row_key = table.get_row_at(table.cursor_row)
+        global_key = str(row_key.value) if row_key else None
+        if not global_key:
+            return None, None
+        # Find repo by global_key
+        for repo in self._repos:
+            if repo.global_key == global_key:
+                ws = self._ws_map.get(global_key)
+                return repo, ws
+        return None, None
+
+    def action_toggle_freeze(self) -> None:
+        repo, ws = self._get_selected_repo()
+        if repo:
+            self.store.update(repo.key, workspace=repo.workspace, frozen=not repo.frozen)
+            repo.frozen = not repo.frozen
+            self._refresh_table()
+            action = "Froze" if repo.frozen else "Unfroze"
+            self.notify(f"{action} {repo.key}")
+
+    def action_show_detail(self) -> None:
+        repo, ws = self._get_selected_repo()
+        if repo and ws:
+            status = self._statuses.get(repo.global_key)
+
+            def on_dismiss(refresh_needed: bool) -> None:
+                if refresh_needed:
+                    self.store.load()
+                    self._repos = self.store.list_all()
+                    self._refresh_table()
+
+            self.push_screen(
+                RepoDetailScreen(repo, status, ws),
+                callback=on_dismiss,
+            )
+
+    @staticmethod
+    def _format_pulled(iso_str: str) -> str:
+        if not iso_str:
+            return "never"
+        from datetime import datetime
+        try:
+            dt = datetime.fromisoformat(iso_str)
+            diff = (datetime.now() - dt).total_seconds()
+            if diff < 3600:
+                return f"{int(diff/60)}m ago"
+            elif diff < 86400:
+                return f"{int(diff/3600)}h ago"
+            else:
+                return f"{int(diff/86400)}d ago"
+        except (ValueError, TypeError):
+            return "?"