repo-control 0.1.0__tar.gz

repo_control-0.1.0/.github/workflows/publish.yaml

@@ -0,0 +1,21 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+
+      - run: uv build
+
+      - uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # release/v1

repo_control-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+.venv/
+.python-version
+dist/
+build/
+*.egg-info/
+
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/

repo_control-0.1.0/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: repo-control
+Version: 0.1.0
+Summary: Mirror open GitHub PRs as per-repo git worktree clusters
+Requires-Python: >=3.12

repo_control-0.1.0/README.md

@@ -0,0 +1,87 @@
+# repo-control
+
+Mirror every open GitHub PR you've authored as a per-repo cluster of git worktrees under a single base path. One folder per tracked repo, named `<repo>-control/`, holding `main/` plus one worktree per open PR.
+
+```
+<base_path>/
+  Backend-control/
+    main/                        # always kept, fast-forwarded each sync
+    2851-fix_parser_foo/         # one worktree per open PR
+    2850-fix_data_ingestion_fmt/
+  metering-sdk-control/
+    main/
+    522-feat_android_mercado_libre_br/
+```
+
+A single daily `repo-control sync` clones missing repos, creates worktrees for new PRs, refreshes existing ones, and removes worktrees whose PRs were merged/closed (only if the worktree is clean). First creation runs `mise install` / `uv sync` / `npm install` automatically when those manifests exist.
+
+## Install
+
+From PyPI:
+
+```bash
+uv tool install repo-control
+```
+
+Or with pipx / pip:
+
+```bash
+pipx install repo-control
+# pip install --user repo-control
+```
+
+From a local checkout (editable):
+
+```bash
+uv tool install --editable "/path/to/repo-control"
+```
+
+Then:
+
+```bash
+repo-control setup           # interactive config (also auto-triggered on first sync)
+repo-control install-skill   # symlinks the bundled Claude skill into ~/.claude/skills/
+```
+
+Requires `gh` (authenticated) and `uv` on PATH. Python 3.12+.
+
+## Usage
+
+```bash
+repo-control sync               # daily refresh (auto-runs setup on first invocation)
+repo-control list               # table of repo / pr / branch / status / path
+repo-control open <pr>          # launch the configured IDE on that worktree
+repo-control open <pr> --ide=code
+repo-control clean              # prune stale worktrees (clean only)
+repo-control clean --force      # confirm-then-drop dirty ones too
+repo-control setup              # re-run interactive config
+repo-control install-skill      # symlink the bundled skill (or --uninstall)
+```
+
+`<pr>` is the GitHub PR number. If the same number exists across multiple repos (rare), use `<owner>/<repo>#<n>`.
+
+## Config
+
+XDG-conformant paths:
+
+- Config: `$XDG_CONFIG_HOME/repo-control/config.toml` (default `~/.config/repo-control/config.toml`).
+- Default base path: `$XDG_DATA_HOME/repo-control/` (default `~/.local/share/repo-control/`).
+
+```toml
+base_path = "/home/<user>/.local/share/repo-control"
+ide = "idea"                   # any binary on PATH; suggestions: idea, code, zed
+skip_repos = []                # ["owner/repo", ...] to ignore
+```
+
+`repo-control setup` is interactive — first sync triggers it automatically; re-run any time to change settings.
+
+## Bundled Claude skill
+
+The skill ships inside the Python package at `repo_control/skill/SKILL.md`. `repo-control install-skill` symlinks it into `~/.claude/skills/repo-control/` so Claude Code picks it up. Idempotent; `--uninstall` removes the symlink.
+
+## Safety properties
+
+- Idempotent. Re-running `sync` immediately is a no-op.
+- A worktree with uncommitted work, stashes, or unpushed commits is never auto-removed; sync flags it and moves on.
+- `gh` auth or network failure aborts before any filesystem mutation.
+- If two different `<owner>/<repo>` pairs would collide on `<repo>-control/`, sync skips the second with a warning rather than overwriting.

repo_control-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "repo-control"
+version = "0.1.0"
+description = "Mirror open GitHub PRs as per-repo git worktree clusters"
+requires-python = ">=3.12"
+dependencies = []
+
+[project.scripts]
+repo-control = "repo_control.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/repo_control"]

repo_control-0.1.0/src/repo_control/__main__.py

@@ -0,0 +1,457 @@
+import argparse
+import os
+import shlex
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from repo_control import config, gh, git, ide, setup, state
+
+SKILL_NAME = "repo-control"
+
+
+@dataclass(frozen=True)
+class WorktreeRow:
+    repo_slug: str
+    pr_number: int | None
+    branch: str | None
+    path: Path
+    status: str
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="repo-control",
+        description="Mirror your open GitHub PRs as per-repo worktree folders under a base path.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("sync", help="Refresh worktrees from open PRs")
+    sub.add_parser("list", help="Show all tracked worktrees")
+    open_p = sub.add_parser("open", help="Open a PR's worktree in the IDE")
+    open_p.add_argument("pr", help="PR number (or owner/repo#N for disambiguation)")
+    open_p.add_argument(
+        "--ide",
+        default=None,
+        help=f"Editor command (e.g. {', '.join(ide.KNOWN)}, or any binary on PATH; quote to pass args)",
+    )
+    clean_p = sub.add_parser("clean", help="Remove stale worktrees")
+    clean_p.add_argument("--force", action="store_true", help="Also drop dirty worktrees (with confirmation)")
+    install_p = sub.add_parser("install-skill", help="Symlink the bundled Claude skill into ~/.claude/skills/")
+    install_p.add_argument("--uninstall", action="store_true", help="Remove the symlink")
+    install_p.add_argument("--force", action="store_true", help="Replace an existing non-symlink at the destination")
+    sub.add_parser("setup", help="Interactive first-run configuration (or re-configure later)")
+
+    args = parser.parse_args()
+    try:
+        if args.cmd == "sync":
+            return cmd_sync()
+        if args.cmd == "list":
+            return cmd_list()
+        if args.cmd == "open":
+            return cmd_open(reference=args.pr, ide_override=args.ide)
+        if args.cmd == "clean":
+            return cmd_clean(force=args.force)
+        if args.cmd == "install-skill":
+            return cmd_install_skill(uninstall=args.uninstall, force=args.force)
+        if args.cmd == "setup":
+            return cmd_setup()
+    except (gh.GhError, git.GitError, ValueError, RuntimeError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def cmd_sync() -> int:
+    gh.check_auth()
+    if not config.exists():
+        print("No config found; running first-run setup.\n")
+        rc = cmd_setup()
+        if rc != 0:
+            return rc
+        print()
+    cfg = config.load()
+    skip = set(cfg["skip_repos"])
+    base = config.base_path(cfg=cfg)
+    base.mkdir(parents=True, exist_ok=True)
+
+    prs = gh.list_open_prs()
+    desired: dict[tuple[str, str], dict[int, gh.OpenPR]] = {}
+    for pr in prs:
+        if pr.base_slug in skip:
+            continue
+        desired.setdefault((pr.base_owner, pr.base_repo), {})[pr.number] = pr
+
+    created: list[Path] = []
+    refreshed: list[Path] = []
+    removed: list[Path] = []
+    kept_dirty: list[Path] = []
+    setup_steps: dict[Path, list[str]] = {}
+
+    for (owner, name), prs_by_num in sorted(desired.items()):
+        repo_path = state.resolve_repo_dir(base_path=base, owner=owner, name=name)
+        main_path = repo_path / "main"
+        if repo_path.exists() and main_path.exists():
+            existing = git.remote_url(repo_path=main_path)
+            existing_parsed = git.parse_owner_repo(url=existing) if existing else None
+            if existing_parsed is not None and existing_parsed != (owner, name):
+                print(
+                    f"skipping {owner}/{name}: {repo_path} already mirrors "
+                    f"{existing_parsed[0]}/{existing_parsed[1]} (name collision)"
+                )
+                continue
+        if not main_path.exists():
+            print(f"cloning {owner}/{name} ...")
+            git.clone(owner=owner, name=name, target=main_path)
+        git.fetch(repo_path=main_path)
+        default = git.default_branch(repo_path=main_path)
+        git.fast_forward(repo_path=main_path, branch=default)
+
+        for pr_number, pr in sorted(prs_by_num.items()):
+            wt_name = state.worktree_dir_name(pr_number=pr_number, branch=pr.head_branch)
+            wt_path = repo_path / wt_name
+            local_branch = f"pr-{pr_number}" if pr.is_fork else pr.head_branch
+            if wt_path.exists():
+                if pr.is_fork and pr.fork_clone_url:
+                    git.fetch_fork(
+                        repo_path=main_path,
+                        fork_url=pr.fork_clone_url,
+                        head_branch=pr.head_branch,
+                        local_branch=local_branch,
+                    )
+                else:
+                    git.fetch(repo_path=main_path, refspec=pr.head_branch)
+                refreshed.append(wt_path)
+                continue
+            if pr.is_fork and pr.fork_clone_url:
+                git.fetch_fork(
+                    repo_path=main_path,
+                    fork_url=pr.fork_clone_url,
+                    head_branch=pr.head_branch,
+                    local_branch=local_branch,
+                )
+            else:
+                git.fetch(repo_path=main_path, refspec=pr.head_branch)
+            git.worktree_add(repo_path=main_path, target=wt_path, branch=local_branch)
+            created.append(wt_path)
+            setup_steps[wt_path] = setup.run_init(worktree_path=wt_path)
+
+    for repo in state.discover_repos(base_path=base):
+        wanted = desired.get((repo.owner, repo.name), {})
+        wanted_paths = {repo.path / state.worktree_dir_name(pr_number=pr.number, branch=pr.head_branch) for pr in wanted.values()}
+        wanted_paths.add(repo.main_path)
+        default = git.default_branch(repo_path=repo.main_path)
+        for worktree in state.existing_worktrees(repo=repo):
+            wt_path = worktree.path.resolve()
+            if wt_path == repo.main_path.resolve():
+                continue
+            if wt_path in {p.resolve() for p in wanted_paths}:
+                continue
+            if not git.is_clean(worktree_path=wt_path):
+                kept_dirty.append(wt_path)
+                continue
+            git.worktree_remove(repo_path=repo.main_path, target=wt_path)
+            if worktree.branch and worktree.branch != default:
+                git.delete_branch(repo_path=repo.main_path, branch=worktree.branch)
+            removed.append(wt_path)
+
+    _print_sync_summary(
+        created=created,
+        refreshed=refreshed,
+        removed=removed,
+        kept_dirty=kept_dirty,
+        setup_steps=setup_steps,
+    )
+    return 0
+
+
+def cmd_list() -> int:
+    rows = _collect_rows()
+    if not rows:
+        print("no worktrees tracked yet — run `repo-control sync`")
+        return 0
+    _print_table(rows=rows)
+    return 0
+
+
+def cmd_open(*, reference: str, ide_override: str | None) -> int:
+    cfg = config.load()
+    chosen = ide_override or cfg["ide"]
+    path = _resolve_pr(reference=reference)
+    if path is None:
+        print(f"no worktree found for {reference!r}", file=sys.stderr)
+        return 1
+    ide.launch(ide=chosen, path=path)
+    print(f"launching {chosen} on {path}")
+    return 0
+
+
+def cmd_clean(*, force: bool) -> int:
+    gh.check_auth()
+    cfg = config.load()
+    base = config.base_path(cfg=cfg)
+    prs = gh.list_open_prs()
+    wanted_by_repo: dict[tuple[str, str], set[Path]] = {}
+    for pr in prs:
+        key = (pr.base_owner, pr.base_repo)
+        repo_path = state.resolve_repo_dir(base_path=base, owner=pr.base_owner, name=pr.base_repo)
+        wt = repo_path / state.worktree_dir_name(pr_number=pr.number, branch=pr.head_branch)
+        wanted_by_repo.setdefault(key, set()).add(wt.resolve())
+
+    stale_clean: list[tuple[Path, Path, str | None]] = []
+    stale_dirty: list[tuple[Path, Path]] = []  # (main_path, wt_path)
+    for repo in state.discover_repos(base_path=base):
+        wanted = wanted_by_repo.get((repo.owner, repo.name), set())
+        default = git.default_branch(repo_path=repo.main_path)
+        for worktree in state.existing_worktrees(repo=repo):
+            wt_path = worktree.path.resolve()
+            if wt_path == repo.main_path.resolve():
+                continue
+            if wt_path in wanted:
+                continue
+            if git.is_clean(worktree_path=wt_path):
+                stale_clean.append((repo.main_path, wt_path, worktree.branch if worktree.branch != default else None))
+            else:
+                stale_dirty.append((repo.main_path, wt_path))
+
+    for main_path, wt_path, branch in stale_clean:
+        git.worktree_remove(repo_path=main_path, target=wt_path)
+        if branch:
+            git.delete_branch(repo_path=main_path, branch=branch)
+        print(f"removed {wt_path}")
+
+    if not stale_dirty:
+        return 0
+    if not force:
+        print(f"\n{len(stale_dirty)} dirty stale worktree(s) preserved:")
+        for _, path in stale_dirty:
+            print(f"  {path}")
+        print("re-run with --force to drop them anyway")
+        return 0
+    print(f"\nabout to remove {len(stale_dirty)} dirty worktree(s):")
+    for _, path in stale_dirty:
+        print(f"  {path}")
+    answer = input("type 'yes' to confirm: ").strip().lower()
+    if answer != "yes":
+        print("aborted")
+        return 1
+    for main_path, wt_path in stale_dirty:
+        git.worktree_remove(repo_path=main_path, target=wt_path)
+        print(f"removed {wt_path}")
+    return 0
+
+
+def _prompt(*, label: str, default: str) -> str:
+    try:
+        raw = input(f"{label} [{default}]: ").strip()
+    except EOFError:
+        return default
+    return raw or default
+
+
+def cmd_setup() -> int:
+    cfg = config.load()
+    print(f"Writing config to {config.config_path()}\n")
+
+    base = os.path.expanduser(_prompt(
+        label="Base path (where <repo>-control/ folders live)",
+        default=cfg["base_path"],
+    ))
+
+    ide_choice = _prompt(
+        label=f"Default editor (suggestions: {', '.join(ide.KNOWN)}; any binary on PATH works, quote to pass args)",
+        default=cfg["ide"],
+    )
+    binary = shlex.split(ide_choice)[0] if ide_choice else ""
+    if binary and shutil.which(binary) is None:
+        print(f"  warning: {binary!r} not on PATH — saving anyway; install or fix before `open`")
+
+    skip_raw = _prompt(
+        label="Repos to skip (comma-separated owner/repo)",
+        default=", ".join(cfg["skip_repos"]),
+    )
+    skip_repos = [item.strip() for item in skip_raw.split(",") if item.strip()]
+
+    Path(base).mkdir(parents=True, exist_ok=True)
+    written = config.write(base_path=base, ide=ide_choice, skip_repos=skip_repos)
+    print(f"\nWrote {written}")
+    return 0
+
+
+def cmd_install_skill(*, uninstall: bool, force: bool) -> int:
+    source = _bundled_skill_source()
+    target = Path.home() / ".claude" / "skills" / SKILL_NAME
+
+    if uninstall:
+        if not target.exists() and not target.is_symlink():
+            print(f"{target} does not exist; nothing to remove")
+            return 0
+        if target.is_symlink():
+            target.unlink()
+            print(f"unlinked {target}")
+            return 0
+        if not force:
+            print(
+                f"refusing to remove {target}: not a symlink. "
+                "Inspect manually or re-run with --force.",
+                file=sys.stderr,
+            )
+            return 1
+        if target.is_dir():
+            _rmtree(target)
+        else:
+            target.unlink()
+        print(f"removed {target}")
+        return 0
+
+    if not source.exists():
+        print(
+            f"bundled skill source not found at {source}; "
+            "is this an editable install?",
+            file=sys.stderr,
+        )
+        return 1
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if target.is_symlink():
+        if target.resolve() == source.resolve():
+            print(f"{target} -> {source} already in place")
+            return 0
+        target.unlink()
+    elif target.exists():
+        if not force:
+            print(
+                f"refusing to overwrite {target}: not a symlink. "
+                "Back it up and re-run with --force.",
+                file=sys.stderr,
+            )
+            return 1
+        if target.is_dir():
+            _rmtree(target)
+        else:
+            target.unlink()
+
+    target.symlink_to(source, target_is_directory=True)
+    print(f"linked {target} -> {source}")
+    return 0
+
+
+def _rmtree(path: Path) -> None:
+    import shutil
+    shutil.rmtree(path)
+
+
+def _bundled_skill_source() -> Path:
+    return Path(__file__).resolve().parent / "skill"
+
+
+def _collect_rows() -> list[WorktreeRow]:
+    rows: list[WorktreeRow] = []
+    cfg = config.load()
+    base = config.base_path(cfg=cfg)
+    for repo in state.discover_repos(base_path=base):
+        default = git.default_branch(repo_path=repo.main_path)
+        for worktree in state.existing_worktrees(repo=repo):
+            wt_path = worktree.path
+            if wt_path.resolve() == repo.main_path.resolve():
+                rows.append(WorktreeRow(
+                    repo_slug=repo.slug,
+                    pr_number=None,
+                    branch=default,
+                    path=wt_path,
+                    status="main",
+                ))
+                continue
+            pr_number = _pr_number_from_dir(name=wt_path.name)
+            status = "clean" if git.is_clean(worktree_path=wt_path) else "dirty"
+            rows.append(WorktreeRow(
+                repo_slug=repo.slug,
+                pr_number=pr_number,
+                branch=worktree.branch,
+                path=wt_path,
+                status=status,
+            ))
+    return rows
+
+
+def _pr_number_from_dir(*, name: str) -> int | None:
+    head, _, _ = name.partition("-")
+    if head.isdigit():
+        return int(head)
+    return None
+
+
+def _resolve_pr(*, reference: str) -> Path | None:
+    rows = _collect_rows()
+    if "#" in reference:
+        slug, _, num = reference.partition("#")
+        target = int(num)
+        for row in rows:
+            if row.repo_slug == slug and row.pr_number == target:
+                return row.path
+        return None
+    if not reference.isdigit():
+        return None
+    target = int(reference)
+    matches = [row for row in rows if row.pr_number == target]
+    if len(matches) == 0:
+        return None
+    if len(matches) > 1:
+        print("ambiguous PR number; matches:", file=sys.stderr)
+        for row in matches:
+            print(f"  {row.repo_slug}#{row.pr_number}  {row.path}", file=sys.stderr)
+        return None
+    return matches[0].path
+
+
+def _print_table(*, rows: list[WorktreeRow]) -> None:
+    headers = ("repo", "pr", "branch", "status", "path")
+    data = [
+        (
+            row.repo_slug,
+            str(row.pr_number) if row.pr_number is not None else "-",
+            row.branch or "-",
+            row.status,
+            str(row.path),
+        )
+        for row in rows
+    ]
+    widths = [len(h) for h in headers]
+    for record in data:
+        for i, cell in enumerate(record):
+            widths[i] = max(widths[i], len(cell))
+    fmt = "  ".join(f"{{:<{w}}}" for w in widths)
+    print(fmt.format(*headers))
+    print(fmt.format(*["-" * w for w in widths]))
+    for record in data:
+        print(fmt.format(*record))
+
+
+def _print_sync_summary(
+    *,
+    created: list[Path],
+    refreshed: list[Path],
+    removed: list[Path],
+    kept_dirty: list[Path],
+    setup_steps: dict[Path, list[str]],
+) -> None:
+    print()
+    print(f"created:  {len(created)}")
+    for path in created:
+        steps = setup_steps.get(path, [])
+        suffix = f" [{', '.join(steps)}]" if steps else ""
+        print(f"  + {path}{suffix}")
+    print(f"refreshed: {len(refreshed)}")
+    for path in refreshed:
+        print(f"  ~ {path}")
+    print(f"removed:  {len(removed)}")
+    for path in removed:
+        print(f"  - {path}")
+    if kept_dirty:
+        print(f"kept dirty: {len(kept_dirty)} (PR closed but worktree has uncommitted work)")
+        for path in kept_dirty:
+            print(f"  ! {path}")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

repo_control-0.1.0/src/repo_control/config.py

@@ -0,0 +1,54 @@
+import os
+import tomllib
+from pathlib import Path
+
+
+def xdg_config_home() -> Path:
+    raw = os.environ.get("XDG_CONFIG_HOME")
+    return Path(raw) if raw else Path.home() / ".config"
+
+
+def xdg_data_home() -> Path:
+    raw = os.environ.get("XDG_DATA_HOME")
+    return Path(raw) if raw else Path.home() / ".local" / "share"
+
+
+DEFAULTS: dict = {
+    "base_path": str(xdg_data_home() / "repo-control"),
+    "ide": "idea",
+    "skip_repos": [],
+}
+
+
+def config_path() -> Path:
+    return xdg_config_home() / "repo-control" / "config.toml"
+
+
+def exists() -> bool:
+    return config_path().exists()
+
+
+def load() -> dict:
+    path = config_path()
+    if not path.exists():
+        return dict(DEFAULTS)
+    with path.open("rb") as handle:
+        data = tomllib.load(handle)
+    return {**DEFAULTS, **data}
+
+
+def write(*, base_path: str, ide: str, skip_repos: list[str]) -> Path:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    skip_repr = ", ".join(f'"{r}"' for r in skip_repos)
+    path.write_text(
+        f'base_path = "{base_path}"\n'
+        f'ide = "{ide}"\n'
+        f"skip_repos = [{skip_repr}]\n"
+    )
+    return path
+
+
+def base_path(*, cfg: dict | None = None) -> Path:
+    settings = cfg or load()
+    return Path(os.path.expanduser(settings["base_path"]))

repo_control-0.1.0/src/repo_control/gh.py

@@ -0,0 +1,88 @@
+import json
+import subprocess
+from dataclasses import dataclass
+
+QUERY = """
+query {
+  search(query: "author:@me is:pr state:open archived:false", type: ISSUE, first: 100) {
+    nodes {
+      ... on PullRequest {
+        number
+        title
+        url
+        isCrossRepository
+        headRefName
+        baseRepository { name owner { login } }
+        headRepository { name url }
+        headRepositoryOwner { login }
+      }
+    }
+  }
+}
+"""
+
+
+@dataclass(frozen=True)
+class OpenPR:
+    number: int
+    title: str
+    url: str
+    base_owner: str
+    base_repo: str
+    head_branch: str
+    is_fork: bool
+    fork_clone_url: str | None
+
+    @property
+    def base_slug(self) -> str:
+        return f"{self.base_owner}/{self.base_repo}"
+
+
+class GhError(RuntimeError):
+    pass
+
+
+def check_auth() -> None:
+    result = subprocess.run(
+        ["gh", "auth", "status"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise GhError(
+            "gh is not authenticated. Run `gh auth login` and re-try.\n" + result.stderr.strip()
+        )
+
+
+def list_open_prs() -> list[OpenPR]:
+    try:
+        result = subprocess.run(
+            ["gh", "api", "graphql", "-f", f"query={QUERY}"],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    except subprocess.CalledProcessError as error:
+        raise GhError(f"gh api graphql failed: {error.stderr.strip()}") from error
+    payload = json.loads(result.stdout)
+    if "errors" in payload:
+        raise GhError(f"graphql errors: {payload['errors']}")
+    nodes = payload["data"]["search"]["nodes"]
+    out: list[OpenPR] = []
+    for node in nodes:
+        if not node:
+            continue
+        head_repo = node.get("headRepository") or {}
+        out.append(
+            OpenPR(
+                number=node["number"],
+                title=node["title"],
+                url=node["url"],
+                base_owner=node["baseRepository"]["owner"]["login"],
+                base_repo=node["baseRepository"]["name"],
+                head_branch=node["headRefName"],
+                is_fork=bool(node["isCrossRepository"]),
+                fork_clone_url=(f"{head_repo['url']}.git" if node["isCrossRepository"] and head_repo else None),
+            )
+        )
+    return out

repo_control-0.1.0/src/repo_control/git.py

@@ -0,0 +1,181 @@
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class GitError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class Worktree:
+    path: Path
+    branch: str | None  # None for detached HEAD
+
+
+def _run(args: list[str], *, cwd: Path | None = None, check: bool = True) -> subprocess.CompletedProcess:
+    try:
+        return subprocess.run(
+            args,
+            cwd=cwd,
+            check=check,
+            capture_output=True,
+            text=True,
+        )
+    except subprocess.CalledProcessError as error:
+        raise GitError(f"{' '.join(args)} failed: {error.stderr.strip()}") from error
+
+
+def clone(*, owner: str, name: str, target: Path) -> None:
+    target.parent.mkdir(parents=True, exist_ok=True)
+    _run(["gh", "repo", "clone", f"{owner}/{name}", str(target)])
+
+
+def default_branch(*, repo_path: Path) -> str:
+    result = _run(
+        ["git", "symbolic-ref", "--short", "refs/remotes/origin/HEAD"],
+        cwd=repo_path,
+        check=False,
+    )
+    if result.returncode == 0:
+        return result.stdout.strip().removeprefix("origin/")
+    for candidate in ("main", "master"):
+        check = _run(
+            ["git", "rev-parse", "--verify", f"refs/heads/{candidate}"],
+            cwd=repo_path,
+            check=False,
+        )
+        if check.returncode == 0:
+            return candidate
+    raise GitError(f"could not determine default branch for {repo_path}")
+
+
+def remote_url(*, repo_path: Path) -> str | None:
+    result = _run(
+        ["git", "config", "--get", "remote.origin.url"],
+        cwd=repo_path,
+        check=False,
+    )
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+def parse_owner_repo(*, url: str) -> tuple[str, str] | None:
+    cleaned = url.removesuffix(".git").rstrip("/")
+    for marker in ("github.com:", "github.com/"):
+        idx = cleaned.find(marker)
+        if idx == -1:
+            continue
+        tail = cleaned[idx + len(marker):]
+        parts = tail.split("/")
+        if len(parts) < 2:
+            return None
+        return parts[0], parts[1]
+    return None
+
+
+def fetch(*, repo_path: Path, refspec: str | None = None) -> None:
+    args = ["git", "fetch", "origin", "--prune"]
+    if refspec is not None:
+        args.append(refspec)
+    _run(args, cwd=repo_path)
+
+
+def fetch_fork(*, repo_path: Path, fork_url: str, head_branch: str, local_branch: str) -> None:
+    _run(
+        [
+            "git",
+            "fetch",
+            fork_url,
+            f"+{head_branch}:refs/heads/{local_branch}",
+        ],
+        cwd=repo_path,
+    )
+
+
+def fast_forward(*, repo_path: Path, branch: str) -> bool:
+    head = _run(["git", "symbolic-ref", "--short", "HEAD"], cwd=repo_path, check=False)
+    on_branch = head.returncode == 0 and head.stdout.strip() == branch
+    if not on_branch:
+        return False
+    if not is_clean(worktree_path=repo_path):
+        return False
+    result = _run(
+        ["git", "merge", "--ff-only", f"origin/{branch}"],
+        cwd=repo_path,
+        check=False,
+    )
+    return result.returncode == 0
+
+
+def list_worktrees(*, repo_path: Path) -> list[Worktree]:
+    result = _run(["git", "worktree", "list", "--porcelain"], cwd=repo_path)
+    out: list[Worktree] = []
+    current_path: Path | None = None
+    current_branch: str | None = None
+    detached = False
+    for line in result.stdout.splitlines():
+        if line.startswith("worktree "):
+            if current_path is not None:
+                out.append(Worktree(path=current_path, branch=None if detached else current_branch))
+            current_path = Path(line.removeprefix("worktree ").strip())
+            current_branch = None
+            detached = False
+            continue
+        if line.startswith("branch "):
+            current_branch = line.removeprefix("branch ").strip().removeprefix("refs/heads/")
+            continue
+        if line.startswith("detached"):
+            detached = True
+            continue
+    if current_path is not None:
+        out.append(Worktree(path=current_path, branch=None if detached else current_branch))
+    return out
+
+
+def worktree_add(*, repo_path: Path, target: Path, branch: str) -> None:
+    target.parent.mkdir(parents=True, exist_ok=True)
+    _run(
+        ["git", "worktree", "add", str(target), branch],
+        cwd=repo_path,
+    )
+
+
+def worktree_remove(*, repo_path: Path, target: Path) -> None:
+    _run(
+        ["git", "worktree", "remove", str(target)],
+        cwd=repo_path,
+    )
+
+
+def delete_branch(*, repo_path: Path, branch: str) -> None:
+    _run(["git", "branch", "-D", branch], cwd=repo_path, check=False)
+
+
+def is_clean(*, worktree_path: Path) -> bool:
+    status = _run(["git", "status", "--porcelain"], cwd=worktree_path)
+    if status.stdout.strip():
+        return False
+    stash = _run(["git", "stash", "list"], cwd=worktree_path)
+    if stash.stdout.strip():
+        return False
+    head = _run(["git", "symbolic-ref", "--short", "HEAD"], cwd=worktree_path, check=False)
+    if head.returncode != 0:
+        return True
+    branch = head.stdout.strip()
+    upstream = _run(
+        ["git", "rev-parse", "--abbrev-ref", f"{branch}@{{upstream}}"],
+        cwd=worktree_path,
+        check=False,
+    )
+    if upstream.returncode != 0:
+        return False
+    ahead = _run(
+        ["git", "rev-list", "--count", f"{upstream.stdout.strip()}..{branch}"],
+        cwd=worktree_path,
+        check=False,
+    )
+    if ahead.returncode != 0:
+        return True
+    return ahead.stdout.strip() == "0"

repo_control-0.1.0/src/repo_control/ide.py

@@ -0,0 +1,23 @@
+import shlex
+import shutil
+import subprocess
+from pathlib import Path
+
+KNOWN = ("idea", "code", "zed")
+
+
+def launch(*, ide: str, path: Path) -> None:
+    parts = shlex.split(ide)
+    if not parts:
+        raise ValueError("ide is empty")
+    binary, *extra = parts
+    if shutil.which(binary) is None:
+        raise RuntimeError(
+            f"{binary!r} not on PATH; install its CLI launcher or pick a different --ide"
+        )
+    subprocess.Popen(
+        [binary, *extra, str(path)],
+        start_new_session=True,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )

repo_control-0.1.0/src/repo_control/setup.py

@@ -0,0 +1,18 @@
+import shutil
+import subprocess
+from pathlib import Path
+
+
+def run_init(*, worktree_path: Path) -> list[str]:
+    """Run mise/uv/npm init for a freshly-created worktree. Returns list of steps run."""
+    steps: list[str] = []
+    if (worktree_path / "mise.toml").exists() and shutil.which("mise"):
+        subprocess.run(["mise", "install"], cwd=worktree_path, check=False)
+        steps.append("mise install")
+    if (worktree_path / "pyproject.toml").exists() and shutil.which("uv"):
+        subprocess.run(["uv", "sync"], cwd=worktree_path, check=False)
+        steps.append("uv sync")
+    if (worktree_path / "package.json").exists() and shutil.which("npm"):
+        subprocess.run(["npm", "install"], cwd=worktree_path, check=False)
+        steps.append("npm install")
+    return steps

repo_control-0.1.0/src/repo_control/skill/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: repo-control
+description: Use when the user says "sync my PRs", "sync repo-control", "refresh my worktrees", "open PR <n>", "what am I working on", or otherwise wants to inspect or refresh the local per-repo worktree mirrors created by the `repo-control` CLI. Wraps the `repo-control` command.
+allowed-tools: Bash
+---
+
+# repo-control
+
+For every open PR the user has authored on GitHub, the `repo-control` CLI scaffolds a sibling `<repo>-control/` folder under one configurable base path (default `~/.local/share/repo-control/`, XDG_DATA_HOME). Each folder holds the repo's `main/` worktree plus one worktree per open PR.
+
+```
+<base_path>/
+  Backend-control/
+    main/                        # always kept
+    2851-fix_parser_foo/         # one worktree per open PR
+    2850-fix_data_ingestion_fmt/
+  metering-sdk-control/
+    main/
+    522-feat_android_mercado_libre_br/
+```
+
+Configuration lives at `~/.config/repo-control/config.toml` (XDG_CONFIG_HOME). Created interactively by `repo-control setup` or on first `sync`.
+
+```toml
+base_path = "/home/<user>/.local/share/repo-control"
+ide = "idea"          # any binary on PATH; suggestions: idea, code, zed
+skip_repos = []       # ["owner/repo", ...]
+```
+
+## Preflight (once per session)
+
+Before the first `repo-control` invocation, confirm the environment:
+
+```bash
+command -v repo-control && gh auth status
+```
+
+If either fails, halt and report the exact remediation:
+
+- `gh auth status` failure → `gh auth login` (user runs themselves).
+- `repo-control` missing → install via `uv tool install --editable <repo-path>` or `uv tool install repo-control` (once published).
+
+Do not retry blindly. Do not bootstrap silently.
+
+## Mode dispatch
+
+| User says | Run |
+|---|---|
+| "sync my PRs", "sync repo-control", "refresh worktrees" | `repo-control sync` |
+| "list my worktrees", "what am I working on" | `repo-control list` |
+| "open PR 5432", "open the parser fix" (after resolving) | `repo-control open <pr>` |
+| "clean stale worktrees", "prune merged ones" | `repo-control clean` |
+| "set up repo-control", "reconfigure repo-control" | `repo-control setup` |
+| "install the skill", "link the skill" | `repo-control install-skill` |
+
+## sync
+
+Run `repo-control sync` and show the summary verbatim. If no config exists yet, sync will auto-launch `setup` which is interactive — let it complete. After sync finishes, surface anything that needs the user's attention:
+
+- Worktrees kept dirty (PR closed but uncommitted work present) — call them out by path.
+- Fork PRs that failed to fetch — print the error.
+
+Never auto-rerun on failure. Never run `clean` as a follow-up unless the user asks.
+
+## open
+
+If the user's reference is ambiguous (e.g. "open the parser fix"), run `repo-control list` first and show matches, then ask which one. Once the PR is unambiguous, invoke `repo-control open <pr>`. Pass `--ide=<binary>` (e.g. `code`, `idea`, `zed`, or any command on PATH; quote to include args) to override the configured default for one call.
+
+## clean
+
+Never run `repo-control clean --force` without explicit user authorisation in this turn. The plain `repo-control clean` removes only worktrees that are clean and whose PR no longer exists — that's safe and you can run it when asked.
+
+## setup
+
+Interactive. Prompts for base_path, ide, skip_repos. Re-running it overwrites the existing config. Use when the user explicitly wants to change settings.
+
+## install-skill
+
+Symlinks the skill (bundled inside the installed Python package) to `~/.claude/skills/repo-control/`. Idempotent. Run when:
+
+- The user just installed the package on a new machine.
+- The user moved or reinstalled the package.
+- `--uninstall` removes the symlink.
+
+## Out of scope
+
+This skill never:
+
+- Commits, pushes, or opens PRs (that's `graphite-cli` / `parley`).
+- Auto-syncs on session start.
+- Modifies the user's working tree in any worktree other than via `git worktree add` / `remove`.

repo_control-0.1.0/src/repo_control/state.py

@@ -0,0 +1,67 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+from repo_control import git
+
+REPO_DIR_SUFFIX = "-control"
+
+
+@dataclass(frozen=True)
+class RepoDir:
+    owner: str
+    name: str
+    path: Path
+
+    @property
+    def main_path(self) -> Path:
+        return self.path / "main"
+
+    @property
+    def slug(self) -> str:
+        return f"{self.owner}/{self.name}"
+
+
+def slugify_branch(*, branch: str) -> str:
+    return branch.replace("/", "-").replace(" ", "-")
+
+
+def repo_dir_name(*, name: str) -> str:
+    return f"{name}{REPO_DIR_SUFFIX}"
+
+
+def worktree_dir_name(*, pr_number: int, branch: str) -> str:
+    return f"{pr_number}-{slugify_branch(branch=branch)}"
+
+
+def resolve_repo_dir(*, base_path: Path, owner: str, name: str) -> Path:
+    return base_path / repo_dir_name(name=name)
+
+
+def discover_repos(*, base_path: Path) -> list[RepoDir]:
+    """Walk <base>/*-control/ dirs and recover (owner, name) from each main/'s remote."""
+    if not base_path.exists():
+        return []
+    out: list[RepoDir] = []
+    for child in sorted(base_path.iterdir()):
+        if not child.is_dir() or child.name.startswith("."):
+            continue
+        if not child.name.endswith(REPO_DIR_SUFFIX):
+            continue
+        main = child / "main"
+        if not main.exists():
+            continue
+        url = git.remote_url(repo_path=main)
+        if url is None:
+            continue
+        parsed = git.parse_owner_repo(url=url)
+        if parsed is None:
+            continue
+        owner, name = parsed
+        out.append(RepoDir(owner=owner, name=name, path=child))
+    return out
+
+
+def existing_worktrees(*, repo: RepoDir) -> list[git.Worktree]:
+    if not repo.main_path.exists():
+        return []
+    return git.list_worktrees(repo_path=repo.main_path)