luv-cli 0.0.1__tar.gz

luv_cli-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

luv_cli-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Exosphere Host
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

luv_cli-0.0.1/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: luv-cli
+Version: 0.0.1
+Summary: Launch Claude Code agents on GitHub repos with isolated workspaces and optional Docker dev environments
+Project-URL: Homepage, https://github.com/exospherehost/luv
+Project-URL: Repository, https://github.com/exospherehost/luv
+Project-URL: Issues, https://github.com/exospherehost/luv/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,claude,cli,docker,github
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# luv
+
+A CLI that launches [Claude Code](https://docs.anthropic.com/en/docs/claude-code) agents on GitHub repos with isolated workspaces and optional Docker dev environments.
+
+`luv` clones a repo, creates a branch, and drops you into a Claude session ready to work. When the repo ships a `.luv/settings.json`, it spins up Docker Compose automatically so every command runs in the right environment.
+
+## Install
+
+```bash
+# With uv (recommended)
+uv tool install luv-cli
+
+# With pip
+pip install luv-cli
+```
+
+**Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI and [GitHub CLI](https://cli.github.com/) (`gh`) must be installed and authenticated.
+
+## Quick start
+
+```bash
+# Configure your default GitHub org (one-time setup)
+luv --init
+
+# Create a new workspace and launch Claude
+luv my-repo "add user authentication"
+
+# Use a different org inline
+luv other-org/my-repo "fix the bug"
+
+# Reopen workspace #42
+luv my-repo 42
+
+# Open any GitHub PR by URL
+luv -l https://github.com/org/repo/pull/123
+
+# Open a shell instead of Claude
+luv -n my-repo 42
+
+# Resume last Claude session
+luv -r my-repo 42
+
+# Clean up fully-merged workspaces
+luv --clean
+```
+
+## How it works
+
+1. Clones the repo into `~/prs/{repo}-{number}/`
+2. Creates a new branch `luv-{number}`
+3. Trusts the project in Claude Code config
+4. Launches Claude with Opus and max effort
+
+All workspaces live under `~/prs/`. The number comes from the repo's GitHub issue counter to avoid collisions.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `luv --init` | Configure default GitHub org |
+| `luv [org/]<repo> [prompt...]` | Create a new workspace and launch Claude |
+| `luv [org/]<repo> <number> [prompt]` | Reopen an existing workspace |
+| `luv -l <PR URL> [prompt]` | Open any GitHub PR by URL |
+| `luv [org/]<repo> -pr <number> [prompt]` | Open a PR by repo + number |
+| `luv --clean` | Delete workspaces where the branch is fully pushed/merged |
+| `luv --clean -f` | Force delete all workspaces |
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `-n` | Navigate: open a shell instead of Claude |
+| `-r` | Resume: resume the last Claude session |
+| `-f`, `--force` | Skip safety checks (with `--clean`) |
+
+## Docker dev environments
+
+If a repo contains `.luv/settings.json` with a `compose_file` key, `luv` automatically starts a Docker Compose environment and runs Claude inside the `dev-environment` container.
+
+### Setup
+
+**1. Create `.luv/settings.json` in your repo:**
+
+```json
+{
+  "compose_file": ".luv/docker-compose.yml"
+}
+```
+
+The `compose_file` path is relative to the repo root.
+
+**2. Create the Docker Compose file:**
+
+```yaml
+services:
+  dev-environment:
+    image: your-org/dev-env:latest
+    volumes:
+      - .:/workspace
+    working_dir: /workspace
+    stdin_open: true
+    tty: true
+    depends_on:
+      - postgres
+
+  postgres:
+    image: postgres:16
+    environment:
+      POSTGRES_PASSWORD: dev
+```
+
+The `dev-environment` service **must** have [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed in its image.
+
+### How Docker mode works
+
+1. Detects `.luv/settings.json` with `compose_file` key
+2. Tears down any stale environment from a previous run
+3. Starts `docker compose up -d --build` with a unique project name (`luv-{repo}-{number}`) for network/volume isolation
+4. Verifies the `dev-environment` service is running
+5. Runs Claude inside the container via `docker compose exec`
+6. The repo is volume-mounted, so all file changes and git commits are visible on the host
+7. On exit (including Ctrl-C), tears down the environment with `docker compose down -v`
+
+Docker mode works with all flags: `-n` opens a bash shell in the container, `-r` resumes a Claude session in the container.
+
+## Workspace cleanup
+
+`luv --clean` scans `~/prs/` and safely removes workspaces that are fully pushed. It checks:
+
+- Working tree is clean (no uncommitted changes)
+- No unpushed commits
+- If the remote branch is gone, verifies the PR was merged and local HEAD matches
+
+Use `luv --clean -f` to skip all safety checks and delete everything.
+
+## Configuration
+
+Run `luv --init` to set your default GitHub org. This saves to `~/.luv/config.json`.
+
+You can also pass `org/repo` inline to override the default for any command (e.g., `luv other-org/my-repo`).
+
+## License
+
+MIT

luv_cli-0.0.1/README.md

@@ -0,0 +1,144 @@
+# luv
+
+A CLI that launches [Claude Code](https://docs.anthropic.com/en/docs/claude-code) agents on GitHub repos with isolated workspaces and optional Docker dev environments.
+
+`luv` clones a repo, creates a branch, and drops you into a Claude session ready to work. When the repo ships a `.luv/settings.json`, it spins up Docker Compose automatically so every command runs in the right environment.
+
+## Install
+
+```bash
+# With uv (recommended)
+uv tool install luv-cli
+
+# With pip
+pip install luv-cli
+```
+
+**Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI and [GitHub CLI](https://cli.github.com/) (`gh`) must be installed and authenticated.
+
+## Quick start
+
+```bash
+# Configure your default GitHub org (one-time setup)
+luv --init
+
+# Create a new workspace and launch Claude
+luv my-repo "add user authentication"
+
+# Use a different org inline
+luv other-org/my-repo "fix the bug"
+
+# Reopen workspace #42
+luv my-repo 42
+
+# Open any GitHub PR by URL
+luv -l https://github.com/org/repo/pull/123
+
+# Open a shell instead of Claude
+luv -n my-repo 42
+
+# Resume last Claude session
+luv -r my-repo 42
+
+# Clean up fully-merged workspaces
+luv --clean
+```
+
+## How it works
+
+1. Clones the repo into `~/prs/{repo}-{number}/`
+2. Creates a new branch `luv-{number}`
+3. Trusts the project in Claude Code config
+4. Launches Claude with Opus and max effort
+
+All workspaces live under `~/prs/`. The number comes from the repo's GitHub issue counter to avoid collisions.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `luv --init` | Configure default GitHub org |
+| `luv [org/]<repo> [prompt...]` | Create a new workspace and launch Claude |
+| `luv [org/]<repo> <number> [prompt]` | Reopen an existing workspace |
+| `luv -l <PR URL> [prompt]` | Open any GitHub PR by URL |
+| `luv [org/]<repo> -pr <number> [prompt]` | Open a PR by repo + number |
+| `luv --clean` | Delete workspaces where the branch is fully pushed/merged |
+| `luv --clean -f` | Force delete all workspaces |
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `-n` | Navigate: open a shell instead of Claude |
+| `-r` | Resume: resume the last Claude session |
+| `-f`, `--force` | Skip safety checks (with `--clean`) |
+
+## Docker dev environments
+
+If a repo contains `.luv/settings.json` with a `compose_file` key, `luv` automatically starts a Docker Compose environment and runs Claude inside the `dev-environment` container.
+
+### Setup
+
+**1. Create `.luv/settings.json` in your repo:**
+
+```json
+{
+  "compose_file": ".luv/docker-compose.yml"
+}
+```
+
+The `compose_file` path is relative to the repo root.
+
+**2. Create the Docker Compose file:**
+
+```yaml
+services:
+  dev-environment:
+    image: your-org/dev-env:latest
+    volumes:
+      - .:/workspace
+    working_dir: /workspace
+    stdin_open: true
+    tty: true
+    depends_on:
+      - postgres
+
+  postgres:
+    image: postgres:16
+    environment:
+      POSTGRES_PASSWORD: dev
+```
+
+The `dev-environment` service **must** have [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed in its image.
+
+### How Docker mode works
+
+1. Detects `.luv/settings.json` with `compose_file` key
+2. Tears down any stale environment from a previous run
+3. Starts `docker compose up -d --build` with a unique project name (`luv-{repo}-{number}`) for network/volume isolation
+4. Verifies the `dev-environment` service is running
+5. Runs Claude inside the container via `docker compose exec`
+6. The repo is volume-mounted, so all file changes and git commits are visible on the host
+7. On exit (including Ctrl-C), tears down the environment with `docker compose down -v`
+
+Docker mode works with all flags: `-n` opens a bash shell in the container, `-r` resumes a Claude session in the container.
+
+## Workspace cleanup
+
+`luv --clean` scans `~/prs/` and safely removes workspaces that are fully pushed. It checks:
+
+- Working tree is clean (no uncommitted changes)
+- No unpushed commits
+- If the remote branch is gone, verifies the PR was merged and local HEAD matches
+
+Use `luv --clean -f` to skip all safety checks and delete everything.
+
+## Configuration
+
+Run `luv --init` to set your default GitHub org. This saves to `~/.luv/config.json`.
+
+You can also pass `org/repo` inline to override the default for any command (e.g., `luv other-org/my-repo`).
+
+## License
+
+MIT

luv_cli-0.0.1/luv/__init__.py

@@ -0,0 +1,617 @@
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+LUV_DIR = Path.home() / ".luv"
+CONFIG_FILE = LUV_DIR / "config.json"
+PRS_DIR = Path.home() / "prs"
+CLAUDE_JSON = Path.home() / ".claude.json"
+
+PR_RULES = """
+# Pull Request Management
+
+One PR per folder. Each folder maps to exactly one PR — create it once, then keep updating it across subsequent tasks.
+
+## Rules
+
+- Before creating a PR, check if one already exists for that folder (by title or branch name convention).
+- If no PR exists for the folder: create one, then record its URL/number so it can be reused.
+- If a PR already exists for the folder: push new commits to the same branch and do NOT open a new PR.
+- PR titles should clearly identify the folder they cover (e.g. `[folder-name] ...`).
+- Never open a second PR for the same folder — always update the existing one.
+"""
+
+
+def die(msg: str) -> None:
+    print(f"luv: error: {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+def run(cmd: list[str], *, cwd: str | None = None) -> subprocess.CompletedProcess:
+    return subprocess.run(cmd, capture_output=True, text=True, cwd=cwd)
+
+
+def load_config() -> dict:
+    """Read ~/.luv/config.json, or return {} on missing/corrupt."""
+    if not CONFIG_FILE.exists():
+        return {}
+    try:
+        return json.loads(CONFIG_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def save_config(data: dict) -> None:
+    """Atomic-write config JSON to ~/.luv/config.json."""
+    LUV_DIR.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(
+        "w", encoding="utf-8", dir=str(LUV_DIR), delete=False,
+    ) as tmp:
+        json.dump(data, tmp, indent=2)
+        tmp.write("\n")
+        tmp_path = Path(tmp.name)
+    os.replace(tmp_path, CONFIG_FILE)
+
+
+def parse_github_remote(cwd: str) -> tuple[str, str] | None:
+    """Extract (org, repo) from origin remote URL. Returns None on failure."""
+    r = run(["git", "remote", "get-url", "origin"], cwd=cwd)
+    if r.returncode != 0:
+        return None
+    url = r.stdout.strip()
+    m = re.match(r"https://github\.com/([^/]+)/([^/.]+)", url)
+    if not m:
+        m = re.match(r"git@github\.com:([^/]+)/([^/.]+)", url)
+    if m:
+        return m.group(1), m.group(2)
+    return None
+
+
+def resolve_org(explicit: str | None = None) -> str:
+    """Resolve GitHub org: explicit arg > config file > error."""
+    if explicit:
+        return explicit
+    cfg = load_config()
+    org = cfg.get("org")
+    if org:
+        return org
+    die("no default org configured.\nRun 'luv --init' to set one, or use 'org/repo' syntax.")
+    return ""  # unreachable, keeps type checkers happy
+
+
+def trust_project(path: Path) -> None:
+    data: dict[str, object] = {}
+    if CLAUDE_JSON.exists():
+        try:
+            with CLAUDE_JSON.open("r", encoding="utf-8") as f:
+                loaded = json.load(f)
+            if isinstance(loaded, dict):
+                data = loaded
+        except (json.JSONDecodeError, OSError):
+            data = {}
+
+    projects = data.get("projects")
+    if not isinstance(projects, dict):
+        projects = {}
+        data["projects"] = projects
+
+    entry = projects.get(str(path))
+    if not isinstance(entry, dict):
+        entry = {}
+        projects[str(path)] = entry
+
+    entry["hasTrustDialogAccepted"] = True
+    CLAUDE_JSON.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(
+        "w",
+        encoding="utf-8",
+        dir=str(CLAUDE_JSON.parent),
+        delete=False,
+    ) as tmp:
+        json.dump(data, tmp, indent=2)
+        tmp.write("\n")
+        tmp_path = Path(tmp.name)
+    os.replace(tmp_path, CLAUDE_JSON)
+
+
+def ensure_pr_rules() -> None:
+    claude_dir = Path.home() / ".claude"
+    claude_md = claude_dir / "CLAUDE.md"
+    claude_dir.mkdir(parents=True, exist_ok=True)
+    existing = claude_md.read_text() if claude_md.exists() else ""
+    if "# Pull Request Management" not in existing:
+        with claude_md.open("a") as f:
+            f.write(PR_RULES)
+
+
+def cmd_init() -> None:
+    """Interactive setup: choose a default GitHub org."""
+    if not sys.stdin.isatty():
+        die("--init requires an interactive terminal")
+
+    r = run(["gh", "api", "user", "--jq", ".login"])
+    if r.returncode != 0:
+        die("'gh' not found or not authenticated. Run 'gh auth login' first.")
+    username = r.stdout.strip()
+
+    r = run(["gh", "api", "user/orgs", "--jq", ".[].login"])
+    orgs = [line for line in r.stdout.strip().splitlines() if line] if r.returncode == 0 else []
+
+    choices = [f"{username} (personal)"] + orgs
+    print("luv: select default GitHub owner:")
+    for i, name in enumerate(choices, 1):
+        print(f"  {i}) {name}")
+    other_idx = len(choices) + 1
+    print(f"  {other_idx}) other (type manually)")
+
+    raw = input(f"Choice [1]: ").strip()
+    if not raw:
+        idx = 1
+    else:
+        try:
+            idx = int(raw)
+        except ValueError:
+            die(f"invalid choice: '{raw}'")
+
+    if idx == other_idx:
+        selected = input("GitHub org or username: ").strip()
+        if not selected:
+            die("no org entered")
+    elif 1 <= idx <= len(choices):
+        selected = choices[idx - 1].split(" (")[0]  # strip " (personal)" suffix
+    else:
+        die(f"invalid choice: {idx}")
+
+    config = load_config()
+    config["org"] = selected
+    save_config(config)
+    print(f"luv: default org set to '{selected}'. Saved to ~/.luv/config.json")
+
+
+def load_luv_settings(clone_dir: Path) -> dict | None:
+    """Read .luv/settings.json from the repo, or return None."""
+    settings_file = clone_dir / ".luv" / "settings.json"
+    if not settings_file.exists():
+        return None
+    try:
+        return json.loads(settings_file.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def docker_project_name(clone_dir: Path) -> str:
+    """Unique Compose project name — scopes networks and volumes."""
+    return f"luv-{clone_dir.name}"
+
+
+def docker_compose_base(clone_dir: Path, compose_file: str, project: str) -> list[str]:
+    """Base docker compose command with project directory and file."""
+    return ["docker", "compose", "-f", str(clone_dir / compose_file),
+            "--project-directory", str(clone_dir), "-p", project]
+
+
+def start_docker(clone_dir: Path, compose_file: str, project: str) -> None:
+    """Start a fresh Docker Compose environment with isolated network/volumes."""
+    compose_path = clone_dir / compose_file
+    if not compose_path.exists():
+        die(f"compose file not found: {compose_file}")
+
+    base = docker_compose_base(clone_dir, compose_file, project)
+
+    # Tear down stale environment (ignore errors if nothing exists)
+    subprocess.run(base + ["down", "-v", "--remove-orphans"], capture_output=True)
+
+    # Start fresh
+    print(f"luv: starting docker environment ({project})...")
+    r = subprocess.run(base + ["up", "-d", "--build"])
+    if r.returncode != 0:
+        die("docker compose up failed")
+
+    # Verify dev-environment service is running
+    r = subprocess.run(base + ["ps", "--format", "json", "dev-environment"],
+                       capture_output=True, text=True)
+    if r.returncode != 0 or "running" not in r.stdout.lower():
+        subprocess.run(base + ["logs", "dev-environment"])
+        die("'dev-environment' service is not running")
+
+    print("luv: docker environment ready")
+
+
+def stop_docker(clone_dir: Path, compose_file: str, project: str) -> None:
+    """Tear down Docker Compose environment, removing volumes and orphans."""
+    base = docker_compose_base(clone_dir, compose_file, project)
+    print(f"luv: tearing down docker environment ({project})...")
+    subprocess.run(base + ["down", "-v", "--remove-orphans"])
+
+
+def navigate(clone_dir: Path) -> None:
+    """Chdir into the work folder and exec a shell — replacing this process."""
+    os.chdir(str(clone_dir))
+    settings = load_luv_settings(clone_dir)
+    compose_file = (settings or {}).get("compose_file")
+
+    if compose_file:
+        project = docker_project_name(clone_dir)
+        start_docker(clone_dir, compose_file, project)
+        try:
+            base = docker_compose_base(clone_dir, compose_file, project)
+            r = subprocess.run(base + ["exec", "-it", "dev-environment", "bash"])
+            sys.exit(r.returncode)
+        finally:
+            stop_docker(clone_dir, compose_file, project)
+    else:
+        shell = os.environ.get("SHELL", "/bin/bash")
+        os.execv(shell, [shell])
+
+
+def resume(clone_dir: Path) -> None:
+    """Trust, chdir, and exec claude --resume — replacing this process."""
+    trust_project(clone_dir)
+    os.chdir(str(clone_dir))
+    settings = load_luv_settings(clone_dir)
+    compose_file = (settings or {}).get("compose_file")
+
+    if compose_file:
+        project = docker_project_name(clone_dir)
+        start_docker(clone_dir, compose_file, project)
+        try:
+            base = docker_compose_base(clone_dir, compose_file, project)
+            r = subprocess.run(base + ["exec", "-it", "dev-environment",
+                                       "claude", "--dangerously-skip-permissions",
+                                       "--model", "claude-opus-4-6",
+                                       "--effort", "max", "--resume"])
+            sys.exit(r.returncode)
+        finally:
+            stop_docker(clone_dir, compose_file, project)
+    else:
+        claude_bin = shutil.which("claude")
+        if not claude_bin:
+            die("'claude' not found in PATH")
+        os.execv(claude_bin, [claude_bin, "--dangerously-skip-permissions",
+                              "--model", "claude-opus-4-6", "--effort", "max", "--resume"])
+
+
+def launch(clone_dir: Path, prompt: str | None) -> None:
+    """Trust, resolve claude, chdir, and exec — replacing this process."""
+    trust_project(clone_dir)
+    os.chdir(str(clone_dir))
+    settings = load_luv_settings(clone_dir)
+    compose_file = (settings or {}).get("compose_file")
+
+    if compose_file:
+        project = docker_project_name(clone_dir)
+        start_docker(clone_dir, compose_file, project)
+        try:
+            base = docker_compose_base(clone_dir, compose_file, project)
+            claude_cmd = ["claude", "--dangerously-skip-permissions",
+                          "--permission-mode", "bypassPermissions",
+                          "--model", "claude-opus-4-6", "--effort", "max"]
+            if prompt:
+                claude_cmd.append(f"/plan {prompt}")
+            r = subprocess.run(base + ["exec", "-it", "dev-environment"] + claude_cmd)
+            sys.exit(r.returncode)
+        finally:
+            stop_docker(clone_dir, compose_file, project)
+    else:
+        claude_bin = shutil.which("claude")
+        if not claude_bin:
+            die("'claude' not found in PATH")
+        base_args = [claude_bin, "--dangerously-skip-permissions",
+                     "--permission-mode", "bypassPermissions",
+                     "--model", "claude-opus-4-6", "--effort", "max"]
+        if prompt:
+            os.execv(claude_bin, base_args + [f"/plan {prompt}"])
+        else:
+            os.execv(claude_bin, base_args)
+
+
+def cmd_clean(force: bool = False) -> None:
+    """Scan ~/prs/ and delete fully-pushed, clean work folders."""
+    if not PRS_DIR.exists():
+        print("luv: nothing to clean (~/prs/ does not exist)")
+        return
+
+    cleaned: list[str] = []
+    skipped: list[tuple[str, str]] = []
+
+    for entry in sorted(PRS_DIR.iterdir()):
+        if not entry.is_dir():
+            continue
+
+        parts = entry.name.rsplit("-", 1)
+        if len(parts) != 2 or not parts[1].isdigit():
+            continue  # doesn't match {repo}-{number} — skip silently
+
+        if force:
+            shutil.rmtree(entry)
+            cleaned.append(entry.name)
+            continue
+
+        number_str = parts[1]
+        branch = f"luv-{number_str}"
+        cwd = str(entry)
+
+        # Must be a git repo
+        if run(["git", "rev-parse", "--git-dir"], cwd=cwd).returncode != 0:
+            continue
+
+        # 1. Working tree must be clean
+        r = run(["git", "status", "--porcelain"], cwd=cwd)
+        if r.returncode != 0 or r.stdout.strip():
+            skipped.append((entry.name, "uncommitted changes"))
+            continue
+
+        # 2. Fetch remote branch; if gone, check for a merged PR
+        fetch_ok = run(["git", "fetch", "origin", branch], cwd=cwd).returncode == 0
+
+        if not fetch_ok:
+            remote_info = parse_github_remote(cwd)
+            if remote_info is None:
+                skipped.append((entry.name, "cannot determine org from git remote"))
+                continue
+            remote_org, repo_name = remote_info
+            r = run(["gh", "api", f"repos/{remote_org}/{repo_name}/pulls",
+                     "-f", "state=closed", "-f", f"head={remote_org}:{branch}",
+                     "-f", "per_page=5"])
+            if r.returncode != 0:
+                skipped.append((entry.name, "branch not on remote"))
+                continue
+            prs = json.loads(r.stdout)
+            merged = [pr for pr in prs if pr.get("merged_at")]
+            if not merged:
+                skipped.append((entry.name, "branch not on remote"))
+                continue
+            pr_head_sha = merged[0]["head"]["sha"]
+            local_sha = run(["git", "rev-parse", "HEAD"], cwd=cwd).stdout.strip()
+            if local_sha != pr_head_sha:
+                skipped.append((entry.name, "local HEAD differs from merged PR head"))
+                continue
+            shutil.rmtree(entry)
+            cleaned.append(entry.name)
+            continue
+
+        # 3. No unpushed commits (branch still exists on remote)
+        r = run(["git", "rev-list", f"origin/{branch}..HEAD", "--count"], cwd=cwd)
+        if r.returncode != 0 or r.stdout.strip() != "0":
+            skipped.append((entry.name, "unpushed commits"))
+            continue
+
+        shutil.rmtree(entry)
+        cleaned.append(entry.name)
+
+    if skipped:
+        print("luv: skipped (not clean):")
+        for name, reason in skipped:
+            print(f"  {name}: {reason}")
+
+    if cleaned:
+        print("luv: cleaned:")
+        for name in cleaned:
+            print(f"  {name}")
+
+    if not skipped and not cleaned:
+        print("luv: nothing to clean")
+
+
+def open_existing(org: str, repo: str, number: int, prompt: str | None, nav_mode: bool = False, resume_mode: bool = False) -> None:
+    """Open an existing work folder or remote branch by number."""
+    clone_dir = PRS_DIR / f"{repo}-{number}"
+
+    # 1. Local folder takes priority
+    if clone_dir.exists():
+        print(f"luv: opening existing folder {clone_dir.name}")
+        ensure_pr_rules()
+        if nav_mode:
+            navigate(clone_dir)
+        elif resume_mode:
+            resume(clone_dir)
+        else:
+            launch(clone_dir, prompt)
+        return  # unreachable
+
+    # 2. Check remote branch luv-{number}
+    branch = f"luv-{number}"
+    clone_url = f"https://github.com/{org}/{repo}"
+    r = run(["git", "ls-remote", "--heads", clone_url, branch])
+    if branch not in r.stdout:
+        die(f"no local folder '{repo}-{number}' and no remote branch '{branch}'")
+
+    # 3. Clone and checkout the existing branch
+    PRS_DIR.mkdir(parents=True, exist_ok=True)
+    print(f"luv: cloning {clone_url} -> {clone_dir} (branch {branch})")
+    r = subprocess.run(["git", "clone", clone_url, str(clone_dir)])
+    if r.returncode != 0:
+        die(f"git clone failed (exit {r.returncode})")
+    r = subprocess.run(["git", "checkout", branch], cwd=str(clone_dir))
+    if r.returncode != 0:
+        die(f"git checkout {branch} failed (exit {r.returncode})")
+
+    print(f"luv: ready — {clone_dir.name}, branch {branch}")
+    ensure_pr_rules()
+    if nav_mode:
+        navigate(clone_dir)
+    elif resume_mode:
+        resume(clone_dir)
+    else:
+        launch(clone_dir, prompt)
+
+
+def open_pr(org: str, repo: str, number: int, prompt: str | None, nav_mode: bool = False, resume_mode: bool = False) -> None:
+    """Open any GitHub PR by org/repo/number, cloning if needed."""
+    clone_dir = PRS_DIR / f"{repo}-{number}"
+
+    if clone_dir.exists():
+        print(f"luv: opening existing folder {clone_dir.name}")
+        ensure_pr_rules()
+        if nav_mode:
+            navigate(clone_dir)
+        elif resume_mode:
+            resume(clone_dir)
+        else:
+            launch(clone_dir, prompt)
+        return  # unreachable
+
+    # Resolve the actual branch name via GitHub API
+    r = run(["gh", "api", f"repos/{org}/{repo}/pulls/{number}"])
+    if r.returncode != 0:
+        die(f"PR {org}/{repo}#{number} not found.\n{r.stderr.strip()}")
+    pr_data = json.loads(r.stdout)
+    branch = pr_data["head"]["ref"]
+    clone_url = pr_data["head"]["repo"]["clone_url"]
+
+    PRS_DIR.mkdir(parents=True, exist_ok=True)
+    print(f"luv: cloning {clone_url} -> {clone_dir} (branch {branch})")
+    r = subprocess.run(["git", "clone", clone_url, str(clone_dir)])
+    if r.returncode != 0:
+        die(f"git clone failed (exit {r.returncode})")
+    r = subprocess.run(["git", "checkout", branch], cwd=str(clone_dir))
+    if r.returncode != 0:
+        die(f"git checkout {branch} failed (exit {r.returncode})")
+
+    print(f"luv: ready — {clone_dir.name}, branch {branch}")
+    ensure_pr_rules()
+    if nav_mode:
+        navigate(clone_dir)
+    elif resume_mode:
+        resume(clone_dir)
+    else:
+        launch(clone_dir, prompt)
+
+
+def main() -> None:
+    args = sys.argv[1:]
+
+    nav_mode = "-n" in args
+    resume_mode = "-r" in args
+    force = "-f" in args or "--force" in args
+    args = [a for a in args if a not in ("-n", "-r", "-f", "--force")]
+
+    if not args or args[0] in ("-h", "--help"):
+        print("""\
+Usage: luv [flags] <command>
+
+Flags:
+  -n            navigate: open a shell in the work folder instead of launching Claude
+  -r            resume: resume the last Claude session in the work folder
+  -f, --force   (with --clean) skip safety checks and delete all work folders
+
+Commands:
+  luv --init                              configure default GitHub org
+  luv [org/]<repo> [prompt...]            create a new PR workspace
+  luv [org/]<repo> <number> [prompt]      reopen an existing work folder by number
+  luv -l <PR URL> [prompt]                open any GitHub PR by URL
+  luv [org/]<repo> -pr <number> [prompt]  open a GitHub PR by repo + number
+  luv --clean [-f]                        delete fully-pushed work folders
+
+Org resolution:
+  Explicit org/repo overrides the default. Run 'luv --init' to set a default.
+  Config: ~/.luv/config.json
+
+Docker:
+  If the repo contains .luv/settings.json with a "compose_file" key,
+  luv starts a Docker Compose environment and runs Claude inside the
+  "dev-environment" service. Torn down automatically on exit.""")
+        sys.exit(0)
+
+    if args[0] == "--clean":
+        cmd_clean(force=force)
+        return
+
+    if args[0] == "--init":
+        cmd_init()
+        return
+
+    # luv -l <PR URL>
+    if args[0] == "-l":
+        if len(args) < 2:
+            die("usage: luv -l <PR URL>")
+        url = args[1]
+        m = re.match(r"https://github\.com/([^/]+)/([^/]+)/pull/(\d+)", url)
+        if not m:
+            die(f"cannot parse PR URL: {url}")
+        org, repo, number = m.group(1), m.group(2), int(m.group(3))
+        prompt = " ".join(args[2:]) or None
+        open_pr(org, repo, number, prompt, nav_mode, resume_mode)
+        return
+
+    raw = args[0].rstrip("/")
+    if "/" in raw:
+        explicit_org, repo = raw.split("/", 1)
+    else:
+        explicit_org, repo = None, raw
+
+    # luv [org/]<repo> -pr <number>
+    if "-pr" in args:
+        idx = args.index("-pr")
+        if idx + 1 >= len(args):
+            die("usage: luv <repo> -pr <number>")
+        try:
+            number = int(args[idx + 1])
+        except ValueError:
+            die(f"expected a PR number after -pr, got '{args[idx + 1]}'")
+        prompt_parts = [a for i, a in enumerate(args) if i not in (0, idx, idx + 1)]
+        prompt = " ".join(prompt_parts) or None
+        open_pr(resolve_org(explicit_org), repo, number, prompt, nav_mode, resume_mode)
+        return
+
+    # Detect optional numeric second argument
+    if len(args) > 1 and args[1].isdigit():
+        number = int(args[1])
+        prompt = " ".join(args[2:]) or None
+        open_existing(resolve_org(explicit_org), repo, number, prompt, nav_mode, resume_mode)
+        return
+
+    org = resolve_org(explicit_org)
+    prompt = " ".join(args[1:]) if len(args) > 1 else None
+
+    # 1. Verify repo exists
+    r = run(["gh", "api", f"repos/{org}/{repo}"])
+    if r.returncode != 0:
+        die(f"repo '{org}/{repo}' not found or gh auth failed.\n{r.stderr.strip()}")
+
+    # 2. Get latest issue/PR number (shared counter on GitHub)
+    r = run(["gh", "api",
+             f"repos/{org}/{repo}/issues?state=all&per_page=1&sort=created&direction=desc"])
+    if r.returncode != 0:
+        die(f"failed to fetch issues.\n{r.stderr.strip()}")
+    items = json.loads(r.stdout)
+    latest = items[0]["number"] if items else 0
+    candidate = latest + 1
+
+    # 3. Find free local folder
+    PRS_DIR.mkdir(parents=True, exist_ok=True)
+    while (PRS_DIR / f"{repo}-{candidate}").exists():
+        candidate += 1
+    clone_dir = PRS_DIR / f"{repo}-{candidate}"
+
+    # 4. Clone
+    clone_url = f"https://github.com/{org}/{repo}"
+    print(f"luv: cloning {clone_url} -> {clone_dir}")
+    r = subprocess.run(["git", "clone", clone_url, str(clone_dir)])
+    if r.returncode != 0:
+        die(f"git clone failed (exit {r.returncode})")
+
+    # 5. Create branch
+    branch = f"luv-{candidate}"
+    print(f"luv: creating branch {branch}")
+    r = subprocess.run(["git", "checkout", "-b", branch], cwd=str(clone_dir))
+    if r.returncode != 0:
+        die(f"git checkout -b failed (exit {r.returncode})")
+
+    # 6. Ensure PR rules in ~/.claude/CLAUDE.md
+    ensure_pr_rules()
+
+    print(f"luv: ready — {clone_dir.name}, branch {branch}")
+
+    # 7. Launch claude, resume session, or open shell (replace this process)
+    if nav_mode:
+        navigate(clone_dir)
+    elif resume_mode:
+        resume(clone_dir)
+    else:
+        launch(clone_dir, prompt)

luv_cli-0.0.1/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "luv-cli"
+version = "0.0.1"
+description = "Launch Claude Code agents on GitHub repos with isolated workspaces and optional Docker dev environments"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = []
+readme = "README.md"
+keywords = ["claude", "cli", "github", "ai", "agent", "docker"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+
+[project.urls]
+Homepage = "https://github.com/exospherehost/luv"
+Repository = "https://github.com/exospherehost/luv"
+Issues = "https://github.com/exospherehost/luv/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["luv"]
+
+[project.scripts]
+luv = "luv:main"