gw-cli 0.12.10__tar.gz

gw_cli-0.12.10/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - run: uv sync --dev
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Format
+        run: uv run ruff format --check src/ tests/
+
+      - name: Test
+        run: uv run pytest tests/ -v

gw_cli-0.12.10/.github/workflows/release.yml

@@ -0,0 +1,86 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Verify version matches pyproject.toml
+        run: |
+          project_version=$(python3 -c "
+          import re
+          with open('pyproject.toml') as f:
+              match = re.search(r'version\s*=\s*\"(.+?)\"', f.read())
+              print(match.group(1))
+          ")
+          if [ "$project_version" != "${{ steps.version.outputs.version }}" ]; then
+            echo "::error::Tag version (${{ steps.version.outputs.version }}) does not match pyproject.toml version ($project_version)"
+            exit 1
+          fi
+
+      - name: Create GitHub Release
+        run: |
+          if [ -f release_notes.md ]; then
+            gh release create "$GITHUB_REF_NAME" \
+              --title "Grove ${{ steps.version.outputs.version }}" \
+              --notes-file release_notes.md
+          else
+            gh release create "$GITHUB_REF_NAME" \
+              --title "Grove ${{ steps.version.outputs.version }}" \
+              --generate-notes
+          fi
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build and publish to PyPI
+        run: |
+          pip install build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Update Homebrew tap
+        env:
+          TAP_GITHUB_TOKEN: ${{ secrets.TAP_GITHUB_TOKEN }}
+        run: |
+          # Install grove to resolve all dependencies
+          pip install .
+
+          # Compute SHA256 of the release tarball
+          tarball_url="https://github.com/${{ github.repository }}/archive/refs/tags/${GITHUB_REF_NAME}.tar.gz"
+          sha256=$(curl -sL "$tarball_url" | sha256sum | awk '{print $1}')
+
+          # Generate the full formula from installed packages
+          python3 scripts/generate_formula.py "$tarball_url" "$sha256" > /tmp/grove.rb
+
+          # Clone the tap repo and update
+          git clone "https://x-access-token:${TAP_GITHUB_TOKEN}@github.com/nicksenap/homebrew-grove.git" tap
+          cd tap
+          cp /tmp/grove.rb Formula/grove.rb
+
+          # Commit and push
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add Formula/grove.rb
+          git diff --cached --quiet && exit 0
+          git commit -m "grove ${{ steps.version.outputs.version }}"
+          git push

gw_cli-0.12.10/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Tool caches
+.pytest_cache/
+.ruff_cache/

gw_cli-0.12.10/.python-version

@@ -0,0 +1 @@
+3.14

gw_cli-0.12.10/CLAUDE.md

@@ -0,0 +1,62 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What is Grove?
+
+Git Worktree Workspace Orchestrator — CLI tool invoked as `gw`. Manages multi-repo worktree-based workspaces so developers can spin up isolated branches across several repos at once.
+
+## Development
+
+- Python 3.12+, managed with `uv`
+- Run `just check` for lint + format + tests
+- Run `just dev` for editable install
+- Run `just install` to install globally via uv tool
+- Run a single test: `uv run pytest tests/test_workspace.py::test_name -v`
+- Auto-fix lint: `just fix` / auto-format: `just fmt`
+- Linter: ruff (line-length 100, rules: E, F, I, N, UP, B, SIM)
+
+## Release Process
+
+1. Bump version in `pyproject.toml`
+2. Run `uv lock` to update the lockfile
+3. Optionally write release notes in `release_notes.md` (root of repo)
+4. Commit everything
+5. Tag + push: `just release X.Y.Z`
+   - Validates version in pyproject.toml matches
+   - Creates annotated tag `vX.Y.Z`
+   - Pushes tag to origin (triggers release workflow)
+   - Workflow uses `release_notes.md` if present, otherwise auto-generates
+   - Workflow auto-generates Homebrew formula with all Python resources
+
+## Per-repo config
+
+Repos managed by Grove can have a `.grove.toml` at their root:
+- `base_branch` — override the default branch for new worktrees (e.g. `stage`)
+- `setup` — command(s) to run after worktree creation (string or list of strings)
+
+## Architecture
+
+All source lives in `src/grove/`. Entry point: `gw` → `grove.cli:app` (Typer).
+
+### Data flow
+
+`cli.py` → `workspace.py` → `git.py` (subprocess) + `state.py` (JSON persistence) + `config.py` (TOML)
+
+- **cli.py** — Typer commands and interactive pickers (simple-term-menu). Orchestrates user interaction.
+- **workspace.py** — Core worktree orchestration (create, delete, status). Uses `_parallel()` for concurrent multi-repo operations via ThreadPoolExecutor.
+- **git.py** — Thin wrappers around `git` subprocess calls. Raises `GitError` on failure. Includes `read_grove_config()` (LRU-cached — tests must clear it).
+- **state.py** — Workspace state persisted to `~/.grove/state.json`. Uses atomic writes.
+- **config.py** — Global config from `~/.grove/config.toml`. Defines `GROVE_DIR`, `CONFIG_PATH`, `DEFAULT_WORKSPACE_DIR` constants (patched in tests).
+- **models.py** — Pure dataclasses: `Config`, `Workspace`, `RepoWorktree` with `to_dict`/`from_dict` serialization.
+- **discover.py** — Finds git repos in configured directories. Caches remote URLs on disk (`~/.grove/cache/remotes.json`, 24h TTL).
+- **tui.py** — Textual TUI for running workspace processes with sidebar + log pane.
+- **claude.py** — Syncs Claude Code memory directories between source repos and worktrees.
+- **console.py** — Rich output helpers (`success`, `error`, `info`, `warning`, `make_table`).
+- **update.py** — Non-blocking version check (cached, background refresh).
+
+### Testing patterns
+
+- Tests use `tmp_grove` fixture (from `conftest.py`) which patches `GROVE_DIR`, `CONFIG_PATH`, `DEFAULT_WORKSPACE_DIR`, and `STATE_PATH` to temp directories.
+- `fake_repos` fixture creates mock repo directories with `.git` dirs (not real git repos).
+- The `read_grove_config` LRU cache is auto-cleared between tests via autouse fixture.

gw_cli-0.12.10/Justfile

@@ -0,0 +1,66 @@
+set dotenv-load := false
+
+# List available recipes
+default:
+    @just --list
+
+# Run all checks (lint + format + tests)
+check: lint fmt-check test
+
+# Run ruff linter
+lint:
+    uv run ruff check src/ tests/
+
+# Auto-fix lint errors
+fix:
+    uv run ruff check --fix src/ tests/
+
+# Check formatting
+fmt-check:
+    uv run ruff format --check src/ tests/
+
+# Auto-format code
+fmt:
+    uv run ruff format src/ tests/
+
+# Run tests
+test *args:
+    uv run pytest tests/ {{ args }}
+
+# Run tests with verbose output
+test-v *args:
+    uv run pytest tests/ -v {{ args }}
+
+# Install gw as editable for development (local venv only)
+dev:
+    uv pip install -e .
+
+# Install gw globally, linked to local source (changes reflect immediately)
+dev-global:
+    uv tool install --editable . --force --reinstall
+
+# Switch back to Homebrew-installed gw
+undev:
+    -uv tool uninstall grove
+    @echo "Homebrew gw is now active (if installed)"
+
+# Install gw as a uv tool (globally)
+install:
+    uv tool install . --force --reinstall
+
+# Reinstall and reload shell integration
+reload: install
+    @echo 'Run: eval "$(gw shell-init)"'
+
+# Tag a new release (usage: just release 0.4.0)
+release version:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    current=$(python3 -c "import re; f=open('pyproject.toml').read(); print(re.search(r'version\s*=\s*\"(.+?)\"', f).group(1))")
+    if [ "$current" != "{{ version }}" ]; then
+        echo "Error: pyproject.toml version ($current) does not match {{ version }}"
+        echo "Update pyproject.toml first, then run this again."
+        exit 1
+    fi
+    git tag -a "v{{ version }}" -m "Release {{ version }}"
+    git push origin "v{{ version }}"

gw_cli-0.12.10/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: gw-cli
+Version: 0.12.10
+Summary: Git Worktree Workspace Orchestrator
+Author-email: Nick Song <nick.song@footway.com>
+Requires-Python: >=3.12
+Requires-Dist: rich>=13.0
+Requires-Dist: simple-term-menu>=1.6.6
+Requires-Dist: textual>=1.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/logo-light.png" alt="Grove logo" width="120">
+</p>
+
+<h1 align="center">Grove (<code>gw</code>)</h1>
+
+<p align="center"><b>grove</b> /ɡrōv/ <i>noun</i> — a small group of trees growing together.</p>
+
+## Why?
+
+Monorepos solve cross-project work, but not everyone has one. You've got separate repos, separate CI, separate deploys — and that's fine until you need to work across them.
+
+One feature across three services means `git worktree add` three times, tracking three branches, jumping between three directories, cleaning up three worktrees when you're done. It's annoying.
+
+Grove gives you the multi-repo worktree workflow that monorepos get for free. One command, one workspace, all repos on the same branch.
+
+## Install
+
+### Homebrew
+
+```bash
+brew tap nicksenap/grove
+brew install grove
+```
+
+### PyPI
+
+```bash
+pipx install gw-cli
+# or
+pip install gw-cli
+```
+
+### From source
+
+```bash
+uv tool install .
+```
+
+Then add shell integration to your `.zshrc` (or `.bashrc`):
+
+```bash
+eval "$(gw shell-init)"
+```
+
+This enables `gw go` to change your working directory and auto-cds into new workspaces after `gw create`.
+
+## Usage
+
+```bash
+# Setup — register one or more directories containing your repos
+gw init ~/dev ~/work/microservices
+gw add-dir ~/other/repos
+gw remove-dir ~/old/repos
+gw explore                                             # deep-scan for repos (2–3 levels)
+
+# Workspaces
+gw create my-feature -r svc-a,svc-b -b feat/login     # create workspace
+gw list                                                # list workspaces
+gw list -s                                             # list with git status summary
+gw status my-feature                                   # git status across repos
+gw sync my-feature                                     # rebase all repos onto base branch
+gw go my-feature                                       # cd into workspace
+gw run my-feature                                      # run dev processes (TUI)
+gw add-repo my-feature -r svc-c                        # add a repo to existing workspace
+gw remove-repo my-feature -r svc-a                     # remove a repo from workspace
+gw rename my-feature --to new-name                     # rename a workspace
+gw doctor                                              # diagnose workspace health issues
+gw delete my-feature                                   # clean up (worktrees + branches)
+
+# Presets — save repo groups for quick workspace creation
+gw preset add backend -r svc-auth,svc-api,svc-worker
+gw preset list
+gw preset remove backend
+gw create my-feature -p backend                        # use a preset instead of -r
+```
+
+All interactive menus support **type-to-search** filtering, arrow-key navigation (single-select), or arrow + tab (multi-select) with an `(all)` shortcut.
+
+## Per-repo config
+
+Drop a `.grove.toml` in any repo to override defaults:
+
+```toml
+# merchant-portal/.grove.toml
+base_branch = "stage"              # branch from origin/stage instead of origin/main
+setup = "pnpm install"             # run after worktree creation
+teardown = "rm -rf node_modules"   # run before worktree removal
+pre_sync = "pnpm run build:check"  # run before rebase during sync
+post_sync = "pnpm install"         # run after successful rebase
+pre_run = "docker compose pull"    # run before gw run starts
+run = "pnpm dev"                   # started by gw run (foreground)
+post_run = "docker compose down"   # run on gw run exit / Ctrl+C
+```
+
+All hook keys accept a string or a list of commands:
+
+```toml
+setup = ["uv sync", "uv run pre-commit install"]
+```
+
+Hook failures are warnings — they never block the operation they're attached to.
+
+### Design philosophy
+
+The hook system follows the npm-style `pre`/`post` convention: one primitive (`run`, `sync`) with optional `pre_` and `post_` counterparts that fire around it. Instead of building special-purpose features (secret injection, dependency installs, container management), Grove gives you generic hook points and gets out of the way.
+
+| When | Hooks | Example use |
+|------|-------|-------------|
+| Worktree created | `setup` | `pnpm install`, inject secrets, seed DB |
+| Worktree removed | `teardown` | `rm -rf node_modules`, revoke temp creds |
+| Before/after rebase | `pre_sync`, `post_sync` | Type-check before rebase, reinstall after |
+| Dev session | `pre_run`, `run`, `post_run` | Pull containers, start dev server, tear down |
+
+### `gw run`
+
+`gw run` launches a [Textual](https://github.com/Textualize/textual) TUI that manages `run` hooks across all repos. Each repo gets its own log pane with a sidebar showing status indicators (green = running, yellow = starting, red = exited with error).
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` / `↑` / `↓` | Navigate repos |
+| `g` / `G` | Jump to first / last |
+| `1`–`9` | Quick-select repo by number |
+| `r` | Restart selected repo |
+| `q` | Quit (terminates all processes) |
+
+Pre-run hooks fire before the TUI launches, post-run hooks fire after it exits.
+
+## Dashboard (`gw dash`)
+
+A Textual TUI for monitoring Claude Code agents across all your workspaces. Agents are sorted into a kanban board with four columns — **Active**, **Attention**, **Idle**, **Done** — based on live status. Inspired by [Clorch](https://github.com/androsovm/clorch).
+
+```bash
+gw dash install   # install Claude Code hooks
+gw dash           # launch the dashboard
+gw dash uninstall # remove hooks
+```
+
+| Key | Action |
+|-----|--------|
+| `h` / `l` | Navigate columns |
+| `j` / `k` | Navigate cards |
+| `Enter` | Jump to agent's Zellij tab |
+| `y` / `n` | Approve / deny permission request |
+| `/` | Search / filter agents |
+| `Escape` | Clear search |
+| `r` | Refresh |
+| `q` | Quit |
+
+### How it works
+
+Claude Code hooks write agent state to `~/.grove/status/<session_id>.json` on every event. The dashboard polls these files every 500ms and renders a real-time kanban view of all active agents.
+
+**Tracked per agent:** status, working directory, git branch, dirty file count, last tool used, tool/error/subagent counts, activity sparkline, permission request details, and initial prompt.
+
+### Zellij tab matching
+
+When you press `Enter` to jump to an agent, the dashboard finds the right Zellij tab using a multi-step strategy:
+
+| Priority | Strategy | Example |
+|----------|----------|---------|
+| 1 | Exact tab name = project name | `grove` → tab `grove` |
+| 2 | Case-insensitive tab name | `Grove` → tab `grove` |
+| 3 | Workspace name from CWD matched against tab names | CWD has `feat-rewrite` → tab matching |
+| 4 | CWD path match via `zellij action dump-layout` | Agent CWD under tab CWD or vice versa |
+| 5 | Project name substring in tab name | `api` → tab `public-api` |
+
+## Works with AI coding tools
+
+Worktrees mean isolation. That makes Grove a natural fit for tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — spin up a workspace, let your AI agent work across repos without touching anything else, clean up when done:
+
+```bash
+gw create -p backend -b fix/auth-bug
+claude "fix the auth token expiry bug across svc-auth and api-gateway"
+gw delete fix-auth-bug   # removes worktrees, branches, and workspace
+```
+
+Grove copies your `CLAUDE.md` into new workspaces, so your agent gets project context from the start.
+
+## Requirements
+
+Python 3.12+ (installed automatically by Homebrew)

gw_cli-0.12.10/README.md

@@ -0,0 +1,182 @@
+<p align="center">
+  <img src="assets/logo-light.png" alt="Grove logo" width="120">
+</p>
+
+<h1 align="center">Grove (<code>gw</code>)</h1>
+
+<p align="center"><b>grove</b> /ɡrōv/ <i>noun</i> — a small group of trees growing together.</p>
+
+## Why?
+
+Monorepos solve cross-project work, but not everyone has one. You've got separate repos, separate CI, separate deploys — and that's fine until you need to work across them.
+
+One feature across three services means `git worktree add` three times, tracking three branches, jumping between three directories, cleaning up three worktrees when you're done. It's annoying.
+
+Grove gives you the multi-repo worktree workflow that monorepos get for free. One command, one workspace, all repos on the same branch.
+
+## Install
+
+### Homebrew
+
+```bash
+brew tap nicksenap/grove
+brew install grove
+```
+
+### PyPI
+
+```bash
+pipx install gw-cli
+# or
+pip install gw-cli
+```
+
+### From source
+
+```bash
+uv tool install .
+```
+
+Then add shell integration to your `.zshrc` (or `.bashrc`):
+
+```bash
+eval "$(gw shell-init)"
+```
+
+This enables `gw go` to change your working directory and auto-cds into new workspaces after `gw create`.
+
+## Usage
+
+```bash
+# Setup — register one or more directories containing your repos
+gw init ~/dev ~/work/microservices
+gw add-dir ~/other/repos
+gw remove-dir ~/old/repos
+gw explore                                             # deep-scan for repos (2–3 levels)
+
+# Workspaces
+gw create my-feature -r svc-a,svc-b -b feat/login     # create workspace
+gw list                                                # list workspaces
+gw list -s                                             # list with git status summary
+gw status my-feature                                   # git status across repos
+gw sync my-feature                                     # rebase all repos onto base branch
+gw go my-feature                                       # cd into workspace
+gw run my-feature                                      # run dev processes (TUI)
+gw add-repo my-feature -r svc-c                        # add a repo to existing workspace
+gw remove-repo my-feature -r svc-a                     # remove a repo from workspace
+gw rename my-feature --to new-name                     # rename a workspace
+gw doctor                                              # diagnose workspace health issues
+gw delete my-feature                                   # clean up (worktrees + branches)
+
+# Presets — save repo groups for quick workspace creation
+gw preset add backend -r svc-auth,svc-api,svc-worker
+gw preset list
+gw preset remove backend
+gw create my-feature -p backend                        # use a preset instead of -r
+```
+
+All interactive menus support **type-to-search** filtering, arrow-key navigation (single-select), or arrow + tab (multi-select) with an `(all)` shortcut.
+
+## Per-repo config
+
+Drop a `.grove.toml` in any repo to override defaults:
+
+```toml
+# merchant-portal/.grove.toml
+base_branch = "stage"              # branch from origin/stage instead of origin/main
+setup = "pnpm install"             # run after worktree creation
+teardown = "rm -rf node_modules"   # run before worktree removal
+pre_sync = "pnpm run build:check"  # run before rebase during sync
+post_sync = "pnpm install"         # run after successful rebase
+pre_run = "docker compose pull"    # run before gw run starts
+run = "pnpm dev"                   # started by gw run (foreground)
+post_run = "docker compose down"   # run on gw run exit / Ctrl+C
+```
+
+All hook keys accept a string or a list of commands:
+
+```toml
+setup = ["uv sync", "uv run pre-commit install"]
+```
+
+Hook failures are warnings — they never block the operation they're attached to.
+
+### Design philosophy
+
+The hook system follows the npm-style `pre`/`post` convention: one primitive (`run`, `sync`) with optional `pre_` and `post_` counterparts that fire around it. Instead of building special-purpose features (secret injection, dependency installs, container management), Grove gives you generic hook points and gets out of the way.
+
+| When | Hooks | Example use |
+|------|-------|-------------|
+| Worktree created | `setup` | `pnpm install`, inject secrets, seed DB |
+| Worktree removed | `teardown` | `rm -rf node_modules`, revoke temp creds |
+| Before/after rebase | `pre_sync`, `post_sync` | Type-check before rebase, reinstall after |
+| Dev session | `pre_run`, `run`, `post_run` | Pull containers, start dev server, tear down |
+
+### `gw run`
+
+`gw run` launches a [Textual](https://github.com/Textualize/textual) TUI that manages `run` hooks across all repos. Each repo gets its own log pane with a sidebar showing status indicators (green = running, yellow = starting, red = exited with error).
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` / `↑` / `↓` | Navigate repos |
+| `g` / `G` | Jump to first / last |
+| `1`–`9` | Quick-select repo by number |
+| `r` | Restart selected repo |
+| `q` | Quit (terminates all processes) |
+
+Pre-run hooks fire before the TUI launches, post-run hooks fire after it exits.
+
+## Dashboard (`gw dash`)
+
+A Textual TUI for monitoring Claude Code agents across all your workspaces. Agents are sorted into a kanban board with four columns — **Active**, **Attention**, **Idle**, **Done** — based on live status. Inspired by [Clorch](https://github.com/androsovm/clorch).
+
+```bash
+gw dash install   # install Claude Code hooks
+gw dash           # launch the dashboard
+gw dash uninstall # remove hooks
+```
+
+| Key | Action |
+|-----|--------|
+| `h` / `l` | Navigate columns |
+| `j` / `k` | Navigate cards |
+| `Enter` | Jump to agent's Zellij tab |
+| `y` / `n` | Approve / deny permission request |
+| `/` | Search / filter agents |
+| `Escape` | Clear search |
+| `r` | Refresh |
+| `q` | Quit |
+
+### How it works
+
+Claude Code hooks write agent state to `~/.grove/status/<session_id>.json` on every event. The dashboard polls these files every 500ms and renders a real-time kanban view of all active agents.
+
+**Tracked per agent:** status, working directory, git branch, dirty file count, last tool used, tool/error/subagent counts, activity sparkline, permission request details, and initial prompt.
+
+### Zellij tab matching
+
+When you press `Enter` to jump to an agent, the dashboard finds the right Zellij tab using a multi-step strategy:
+
+| Priority | Strategy | Example |
+|----------|----------|---------|
+| 1 | Exact tab name = project name | `grove` → tab `grove` |
+| 2 | Case-insensitive tab name | `Grove` → tab `grove` |
+| 3 | Workspace name from CWD matched against tab names | CWD has `feat-rewrite` → tab matching |
+| 4 | CWD path match via `zellij action dump-layout` | Agent CWD under tab CWD or vice versa |
+| 5 | Project name substring in tab name | `api` → tab `public-api` |
+
+## Works with AI coding tools
+
+Worktrees mean isolation. That makes Grove a natural fit for tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — spin up a workspace, let your AI agent work across repos without touching anything else, clean up when done:
+
+```bash
+gw create -p backend -b fix/auth-bug
+claude "fix the auth token expiry bug across svc-auth and api-gateway"
+gw delete fix-auth-bug   # removes worktrees, branches, and workspace
+```
+
+Grove copies your `CLAUDE.md` into new workspaces, so your agent gets project context from the start.
+
+## Requirements
+
+Python 3.12+ (installed automatically by Homebrew)