erk 0.4.5__py3-none-any.whl

erk/cli/commands/planner/create_cmd.py

@@ -0,0 +1,148 @@
+"""Create a new planner codespace."""
+
+import json
+import subprocess
+
+import click
+
+from erk.core.context import ErkContext
+from erk.core.planner.types import RegisteredPlanner
+
+
+def _find_codespace_by_display_name(display_name: str) -> dict | None:
+    """Find a codespace by its display name."""
+    # GH-API-AUDIT: REST - GET user/codespaces
+    result = subprocess.run(
+        ["gh", "codespace", "list", "--json", "name,repository,displayName"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        return None
+
+    content = result.stdout.strip()
+    if not content:
+        return None
+
+    try:
+        codespaces = json.loads(content)
+        for cs in codespaces:
+            if cs.get("displayName") == display_name:
+                return cs
+        return None
+    except json.JSONDecodeError:
+        return None
+
+
+@click.command("create")
+@click.argument("name", default="erk-planner-node")
+@click.option(
+    "-r",
+    "--repo",
+    default=None,
+    help="Repository to create codespace from (owner/repo). Defaults to current repo.",
+)
+@click.option(
+    "-b",
+    "--branch",
+    default=None,
+    help="Branch to create codespace from. Defaults to default branch.",
+)
+@click.option(
+    "--run/--dry-run",
+    default=False,
+    help="Actually run the command (default: just print it).",
+)
+@click.pass_obj
+def create_planner(
+    ctx: ErkContext,
+    name: str,
+    repo: str | None,
+    branch: str | None,
+    run: bool,
+) -> None:
+    """Create a new GitHub Codespace for use as a planner.
+
+    Creates a codespace with the right devcontainer configuration and
+    automatically registers it as a planner.
+
+    The codespace will be created with:
+    - GitHub CLI pre-installed
+    - Claude Code pre-installed
+    - uv and project dependencies
+
+    After creation, run 'erk planner configure NAME' to set up authentication.
+    """
+    # Check if name already exists
+    existing = ctx.planner_registry.get(name)
+    if existing is not None:
+        click.echo(f"Error: A planner named '{name}' already exists.", err=True)
+        raise SystemExit(1)
+
+    # GH-API-AUDIT: REST - POST user/codespaces
+    cmd = ["gh", "codespace", "create"]
+
+    if repo:
+        cmd.extend(["--repo", repo])
+
+    if branch:
+        cmd.extend(["--branch", branch])
+
+    cmd.extend(["--display-name", name])
+    cmd.extend(["--devcontainer-path", ".devcontainer/devcontainer.json"])
+
+    if run:
+        click.echo(f"Creating codespace '{name}'...", err=True)
+        click.echo(f"Running: {' '.join(cmd)}", err=True)
+        click.echo("", err=True)
+
+        result = subprocess.run(cmd, check=False)
+
+        if result.returncode != 0:
+            click.echo(f"\nCodespace creation failed (exit code {result.returncode}).", err=True)
+            raise SystemExit(1)
+
+        # Find and register the created codespace
+        click.echo("", err=True)
+        click.echo("Looking up created codespace...", err=True)
+
+        codespace = _find_codespace_by_display_name(name)
+        if codespace is None:
+            click.echo(f"Warning: Could not find codespace '{name}' to register.", err=True)
+            click.echo(f"Run 'erk planner register {name}' manually.", err=True)
+            raise SystemExit(1)
+
+        gh_name = codespace.get("name", "")
+        repository = codespace.get("repository", "")
+
+        planner = RegisteredPlanner(
+            name=name,
+            gh_name=gh_name,
+            repository=repository,
+            configured=False,
+            registered_at=ctx.time.now(),
+            last_connected_at=None,
+        )
+        ctx.planner_registry.register(planner)
+
+        # Set as default if first planner
+        if len(ctx.planner_registry.list_planners()) == 1:
+            ctx.planner_registry.set_default(name)
+            click.echo(f"Registered planner '{name}' (set as default)", err=True)
+        else:
+            click.echo(f"Registered planner '{name}'", err=True)
+
+        click.echo("", err=True)
+        click.echo("Next step:", err=True)
+        click.echo(f"  erk planner configure {name}", err=True)
+    else:
+        click.echo("Run this command to create the codespace:", err=True)
+        click.echo("", err=True)
+        click.echo(f"  {' '.join(cmd)}", err=True)
+        click.echo("", err=True)
+        click.echo("Or run with --run to execute directly:", err=True)
+        click.echo(f"  erk planner create {name} --run", err=True)
+        click.echo("", err=True)
+        click.echo("After creation, configure authentication:", err=True)
+        click.echo(f"  erk planner configure {name}", err=True)

erk/cli/commands/planner/list_cmd.py

@@ -0,0 +1,51 @@
+"""List registered planner boxes."""
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from erk.core.context import ErkContext
+
+
+@click.command("list")
+@click.pass_obj
+def list_planners(ctx: ErkContext) -> None:
+    """List all registered planner boxes."""
+    planners = ctx.planner_registry.list_planners()
+    default_name = ctx.planner_registry.get_default_name()
+
+    if not planners:
+        click.echo("No planners registered.", err=True)
+        click.echo("\nUse 'erk planner register <name>' to register a codespace.", err=True)
+        return
+
+    # Create Rich table
+    table = Table(show_header=True, header_style="bold", box=None)
+    table.add_column("name", style="cyan", no_wrap=True)
+    table.add_column("repository", style="yellow", no_wrap=True)
+    table.add_column("configured", no_wrap=True)
+    table.add_column("last connected", no_wrap=True)
+
+    for planner in sorted(planners, key=lambda p: p.name):
+        # Name with default indicator
+        name_cell = planner.name
+        if planner.name == default_name:
+            name_cell = f"[cyan bold]{planner.name}[/cyan bold] (default)"
+        else:
+            name_cell = f"[cyan]{planner.name}[/cyan]"
+
+        # Configured status
+        configured_cell = "[green]yes[/green]" if planner.configured else "[yellow]no[/yellow]"
+
+        # Last connected
+        if planner.last_connected_at:
+            # Format as relative time or date
+            last_connected = planner.last_connected_at.strftime("%Y-%m-%d %H:%M")
+        else:
+            last_connected = "-"
+
+        table.add_row(name_cell, planner.repository, configured_cell, last_connected)
+
+    # Output table to stderr (consistent with erk conventions)
+    console = Console(stderr=True, force_terminal=True)
+    console.print(table)

erk/cli/commands/planner/register_cmd.py

@@ -0,0 +1,105 @@
+"""Register an existing GitHub Codespace as a planner box."""
+
+import json
+import subprocess
+
+import click
+
+from erk.cli.ensure import Ensure
+from erk.core.context import ErkContext
+from erk.core.planner.types import RegisteredPlanner
+
+
+def _list_codespaces() -> list[dict]:
+    """List available codespaces from GitHub.
+
+    Returns:
+        List of codespace dicts with name, repository, displayName fields
+    """
+    # GH-API-AUDIT: REST - GET user/codespaces
+    result = subprocess.run(
+        ["gh", "codespace", "list", "--json", "name,repository,displayName"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+    if result.returncode != 0:
+        return []
+
+    # JSON parsing requires exception handling for malformed data
+    content = result.stdout.strip()
+    if not content:
+        return []
+    try:
+        parsed = json.loads(content)
+        if isinstance(parsed, list):
+            return parsed
+        return []
+    except json.JSONDecodeError:
+        return []
+
+
+@click.command("register")
+@click.argument("name")
+@click.pass_obj
+def register_planner(ctx: ErkContext, name: str) -> None:
+    """Register an existing GitHub Codespace as a planner box.
+
+    Lists available codespaces and prompts you to select one.
+    The selected codespace will be registered under NAME.
+    """
+    # Check if name already exists
+    existing = ctx.planner_registry.get(name)
+    if existing is not None:
+        click.echo(f"Error: A planner named '{name}' already exists.", err=True)
+        click.echo(f"Use 'erk planner unregister {name}' first to remove it.", err=True)
+        raise SystemExit(1)
+
+    # List available codespaces
+    click.echo("Fetching available codespaces...", err=True)
+    codespaces = _list_codespaces()
+
+    if not codespaces:
+        click.echo("No codespaces found.", err=True)
+        click.echo("\nCreate a codespace first, then run this command again.", err=True)
+        raise SystemExit(1)
+
+    # Display available codespaces
+    click.echo("\nAvailable codespaces:", err=True)
+    for i, cs in enumerate(codespaces, 1):
+        display_name = cs.get("displayName", cs.get("name", "unknown"))
+        repo = cs.get("repository", "unknown")
+        click.echo(f"  {i}. {display_name} ({repo})", err=True)
+
+    # Prompt for selection
+    click.echo("", err=True)
+    selection = click.prompt(
+        "Select codespace number",
+        type=click.IntRange(1, len(codespaces)),
+    )
+
+    selected = codespaces[selection - 1]
+    gh_name = Ensure.truthy(selected.get("name", ""), "Could not get codespace name.")
+    repository = selected.get("repository", "")
+
+    # Create and register the planner
+    planner = RegisteredPlanner(
+        name=name,
+        gh_name=gh_name,
+        repository=repository,
+        configured=False,
+        registered_at=ctx.time.now(),
+        last_connected_at=None,
+    )
+
+    ctx.planner_registry.register(planner)
+
+    # If this is the first planner, set it as default
+    if len(ctx.planner_registry.list_planners()) == 1:
+        ctx.planner_registry.set_default(name)
+        click.echo(f"\nRegistered planner '{name}' (set as default)", err=True)
+    else:
+        click.echo(f"\nRegistered planner '{name}'", err=True)
+
+    click.echo(f"\nRun 'erk planner configure {name}' for initial setup.", err=True)

erk/cli/commands/planner/set_default_cmd.py

@@ -0,0 +1,23 @@
+"""Set the default planner box."""
+
+import click
+
+from erk.cli.ensure import Ensure
+from erk.core.context import ErkContext
+
+
+@click.command("set-default")
+@click.argument("name")
+@click.pass_obj
+def set_default_planner(ctx: ErkContext, name: str) -> None:
+    """Set the default planner box.
+
+    The default planner is used when running 'erk planner' without arguments.
+    """
+    _planner = Ensure.not_none(
+        ctx.planner_registry.get(name),
+        f"No planner named '{name}' found.\n\nUse 'erk planner list' to see registered planners.",
+    )
+
+    ctx.planner_registry.set_default(name)
+    click.echo(f"Set '{name}' as the default planner.", err=True)

erk/cli/commands/planner/unregister_cmd.py

@@ -0,0 +1,43 @@
+"""Unregister a planner box."""
+
+import click
+
+from erk.core.context import ErkContext
+
+
+@click.command("unregister")
+@click.argument("name")
+@click.option("--force", "-f", is_flag=True, help="Skip confirmation prompt")
+@click.pass_obj
+def unregister_planner(ctx: ErkContext, name: str, force: bool) -> None:
+    """Remove a planner box from the registry.
+
+    This does not delete the codespace - it only removes the registration.
+    """
+    planner = ctx.planner_registry.get(name)
+    if planner is None:
+        click.echo(f"Error: No planner named '{name}' found.", err=True)
+        click.echo("\nUse 'erk planner list' to see registered planners.", err=True)
+        raise SystemExit(1)
+
+    # Check if this is the default
+    is_default = ctx.planner_registry.get_default_name() == name
+
+    if not force:
+        msg = f"Unregister planner '{name}'?"
+        if is_default:
+            msg = f"Unregister planner '{name}' (currently the default)?"
+        if not click.confirm(msg):
+            click.echo("Cancelled.", err=True)
+            raise SystemExit(0)
+
+    ctx.planner_registry.unregister(name)
+
+    click.echo(f"Unregistered planner '{name}'.", err=True)
+    if is_default:
+        click.echo("Note: Default planner has been cleared.", err=True)
+
+    # Suggest setting a new default if there are other planners
+    remaining = ctx.planner_registry.list_planners()
+    if remaining and is_default:
+        click.echo("\nUse 'erk planner set-default <name>' to set a new default.", err=True)

erk/cli/commands/pr/__init__.py

@@ -0,0 +1,23 @@
+"""PR management commands."""
+
+import click
+
+from erk.cli.alias import register_with_aliases
+from erk.cli.commands.pr.check_cmd import pr_check
+from erk.cli.commands.pr.checkout_cmd import pr_checkout
+from erk.cli.commands.pr.fix_conflicts_cmd import pr_fix_conflicts
+from erk.cli.commands.pr.submit_cmd import pr_submit
+from erk.cli.commands.pr.sync_cmd import pr_sync
+
+
+@click.group("pr")
+def pr_group() -> None:
+    """Manage pull requests."""
+    pass
+
+
+pr_group.add_command(pr_check, name="check")
+register_with_aliases(pr_group, pr_checkout)
+pr_group.add_command(pr_fix_conflicts, name="fix-conflicts")
+pr_group.add_command(pr_submit, name="submit")
+pr_group.add_command(pr_sync, name="sync")

erk/cli/commands/pr/check_cmd.py

@@ -0,0 +1,112 @@
+"""Command to validate PR rules for the current branch."""
+
+import click
+
+from erk.cli.ensure import Ensure
+from erk.core.context import ErkContext
+from erk_shared.gateway.pr.submit import (
+    has_checkout_footer_for_pr,
+    has_issue_closing_reference,
+)
+from erk_shared.github.types import PRNotFound
+from erk_shared.impl_folder import read_issue_reference, validate_issue_linkage
+from erk_shared.output.output import user_output
+
+
+@click.command("check")
+@click.pass_obj
+def pr_check(ctx: ErkContext) -> None:
+    """Validate PR rules for the current branch.
+
+    Checks that the PR:
+    1. Has issue closing reference (Closes #N) when .impl/issue.json exists
+    2. Has the standard checkout command footer
+    """
+    # Get current branch
+    branch = Ensure.not_none(
+        ctx.git.get_current_branch(ctx.cwd),
+        "Not on a branch (detached HEAD)",
+    )
+
+    # Get repo root for GitHub operations
+    repo_root = ctx.git.get_repository_root(ctx.cwd)
+
+    # Get PR for branch
+    pr = ctx.github.get_pr_for_branch(repo_root, branch)
+    if isinstance(pr, PRNotFound):
+        user_output(
+            click.style("Error: ", fg="red") + f"No pull request found for branch '{branch}'"
+        )
+        raise SystemExit(1)
+
+    pr_number = pr.number
+
+    user_output(f"Checking PR #{pr_number} for branch {branch}...")
+    user_output("")
+
+    # Track validation results
+    checks: list[tuple[bool, str]] = []
+
+    pr_body = pr.body
+
+    # .impl always lives at worktree/repo root
+    impl_dir = repo_root / ".impl"
+
+    # Check 0: Branch/issue.json agreement
+    # This catches cases where branch name says "P42-..." but issue.json says #99
+    issue_number: int | None = None
+    try:
+        issue_number = validate_issue_linkage(impl_dir, branch)
+        if issue_number is not None:
+            checks.append((True, f"Branch name and .impl/issue.json agree (#{issue_number})"))
+    except ValueError as e:
+        checks.append((False, str(e)))
+        # Continue with other checks - use the issue from .impl/issue.json as fallback
+        issue_ref_fallback = read_issue_reference(impl_dir)
+        if issue_ref_fallback is not None:
+            issue_number = issue_ref_fallback.issue_number
+
+    # Check 1: Issue closing reference (if issue number is discoverable)
+    issue_ref = read_issue_reference(impl_dir)
+
+    if issue_ref is not None:
+        expected_issue_number = issue_ref.issue_number
+        plans_repo = ctx.local_config.plans_repo if ctx.local_config else None
+        if has_issue_closing_reference(pr_body, expected_issue_number, plans_repo):
+            # Format expected reference for display
+            if plans_repo is None:
+                ref_display = f"#{expected_issue_number}"
+            else:
+                ref_display = f"{plans_repo}#{expected_issue_number}"
+            msg = f"PR body contains issue closing reference (Closes {ref_display})"
+            checks.append((True, msg))
+        else:
+            if plans_repo is None:
+                expected = f"Closes #{expected_issue_number}"
+            else:
+                expected = f"Closes {plans_repo}#{expected_issue_number}"
+            msg = f"PR body missing issue closing reference (expected: {expected})"
+            checks.append((False, msg))
+
+    # Check 2: Checkout footer
+    if has_checkout_footer_for_pr(pr_body, pr_number):
+        checks.append((True, "PR body contains checkout footer"))
+    else:
+        checks.append((False, "PR body missing checkout footer"))
+
+    # Output results
+    for passed, description in checks:
+        status = click.style("[PASS]", fg="green") if passed else click.style("[FAIL]", fg="red")
+        user_output(f"{status} {description}")
+
+    user_output("")
+
+    # Determine overall result
+    failed_count = sum(1 for passed, _ in checks if not passed)
+    if failed_count == 0:
+        user_output(click.style("All checks passed", fg="green"))
+        raise SystemExit(0)
+    else:
+        check_word = "check" if failed_count == 1 else "checks"
+        user_output(click.style(f"{failed_count} {check_word} failed", fg="red"))
+        raise SystemExit(1)

erk/cli/commands/pr/checkout_cmd.py

@@ -0,0 +1,165 @@
+"""Checkout a pull request into a worktree.
+
+This command fetches PR code and creates a worktree for local review/testing.
+"""
+
+import click
+
+from erk.cli.activation import render_activation_script
+from erk.cli.alias import alias
+from erk.cli.commands.pr.parse_pr_reference import parse_pr_reference
+from erk.cli.core import worktree_path_for
+from erk.cli.ensure import Ensure
+from erk.cli.help_formatter import CommandWithHiddenOptions, script_option
+from erk.core.context import ErkContext
+from erk.core.repo_discovery import NoRepoSentinel, RepoContext
+from erk_shared.github.types import PRNotFound
+from erk_shared.output.output import user_output
+
+
+@alias("co")
+@click.command("checkout", cls=CommandWithHiddenOptions)
+@click.argument("pr_reference")
+@script_option
+@click.pass_obj
+def pr_checkout(ctx: ErkContext, pr_reference: str, script: bool) -> None:
+    """Checkout PR into a worktree for review.
+
+    PR_REFERENCE can be a plain number (123) or GitHub URL
+    (https://github.com/owner/repo/pull/123).
+
+    Examples:
+
+        # Checkout by PR number
+        erk pr checkout 123
+
+        # Checkout by GitHub URL
+        erk pr checkout https://github.com/owner/repo/pull/123
+    """
+    # Validate preconditions upfront (LBYL)
+    Ensure.gh_authenticated(ctx)
+
+    if isinstance(ctx.repo, NoRepoSentinel):
+        ctx.feedback.error("Not in a git repository")
+        raise SystemExit(1)
+    repo: RepoContext = ctx.repo
+
+    pr_number = parse_pr_reference(pr_reference)
+
+    # Get PR details from GitHub
+    ctx.feedback.info(f"Fetching PR #{pr_number}...")
+    pr = ctx.github.get_pr(repo.root, pr_number)
+    if isinstance(pr, PRNotFound):
+        ctx.feedback.error(
+            f"Could not find PR #{pr_number}\n\n"
+            "Check the PR number and ensure you're authenticated with gh CLI."
+        )
+        raise SystemExit(1)
+
+    # Warn for closed/merged PRs
+    if pr.state != "OPEN":
+        ctx.feedback.info(f"Warning: PR #{pr_number} is {pr.state}")
+
+    # Determine branch name strategy
+    # For cross-repository PRs (forks), use pr/<number> to avoid conflicts
+    # For same-repository PRs, use the actual branch name
+    if pr.is_cross_repository:
+        branch_name = f"pr/{pr_number}"
+    else:
+        branch_name = pr.head_ref_name
+
+    # Check if branch already exists in a worktree
+    existing_worktree = ctx.git.find_worktree_for_branch(repo.root, branch_name)
+    if existing_worktree is not None:
+        # Branch already exists in a worktree - activate it
+        if script:
+            activation_script = render_activation_script(
+                worktree_path=existing_worktree,
+                target_subpath=None,
+                post_cd_commands=None,
+                final_message=f'echo "Went to existing worktree for PR #{pr_number}"',
+                comment="work activate-script",
+            )
+            result = ctx.script_writer.write_activation_script(
+                activation_script,
+                command_name="pr-checkout",
+                comment=f"activate PR #{pr_number}",
+            )
+            result.output_for_shell_integration()
+        else:
+            styled_path = click.style(str(existing_worktree), fg="cyan", bold=True)
+            user_output(f"PR #{pr_number} already checked out at {styled_path}")
+            user_output("\nShell integration not detected. Run 'erk init --shell' to set up.")
+            user_output(f"Or use: source <(erk pr checkout {pr_reference} --script)")
+        return
+
+    # For cross-repository PRs, always fetch via refs/pull/<n>/head
+    # For same-repo PRs, check if branch exists locally first
+    if pr.is_cross_repository:
+        # Fetch PR ref directly
+        ctx.git.fetch_pr_ref(repo.root, "origin", pr_number, branch_name)
+    else:
+        # Check if branch exists locally or on remote
+        local_branches = ctx.git.list_local_branches(repo.root)
+        if branch_name in local_branches:
+            # Branch already exists locally - just need to create worktree
+            pass
+        else:
+            # Check remote and fetch if needed
+            remote_branches = ctx.git.list_remote_branches(repo.root)
+            remote_ref = f"origin/{branch_name}"
+            if remote_ref in remote_branches:
+                ctx.git.fetch_branch(repo.root, "origin", branch_name)
+                ctx.git.create_tracking_branch(repo.root, branch_name, remote_ref)
+            else:
+                # Branch not on remote (maybe local-only PR?), fetch via PR ref
+                ctx.git.fetch_pr_ref(repo.root, "origin", pr_number, branch_name)
+
+    # Create worktree
+    worktree_path = worktree_path_for(repo.worktrees_dir, branch_name)
+    ctx.git.add_worktree(
+        repo.root,
+        worktree_path,
+        branch=branch_name,
+        ref=None,
+        create_branch=False,
+    )
+
+    # For stacked PRs (base is not trunk), rebase onto base branch
+    # This ensures git history includes the base branch as an ancestor,
+    # which `gt track` requires for proper stacking
+    trunk_branch = ctx.git.detect_trunk_branch(repo.root)
+    if pr.base_ref_name != trunk_branch and not pr.is_cross_repository:
+        ctx.feedback.info(f"Fetching base branch '{pr.base_ref_name}'...")
+        ctx.git.fetch_branch(repo.root, "origin", pr.base_ref_name)
+
+        ctx.feedback.info("Rebasing onto base branch...")
+        rebase_result = ctx.git.rebase_onto(worktree_path, f"origin/{pr.base_ref_name}")
+
+        if not rebase_result.success:
+            ctx.git.rebase_abort(worktree_path)
+            ctx.feedback.info(
+                f"Warning: Rebase had conflicts. Worktree created but needs manual rebase.\n"
+                f"Run: cd {worktree_path} && git rebase origin/{pr.base_ref_name}"
+            )
+
+    # Output based on mode
+    if script:
+        activation_script = render_activation_script(
+            worktree_path=worktree_path,
+            target_subpath=None,
+            post_cd_commands=None,
+            final_message=f'echo "Checked out PR #{pr_number} at $(pwd)"',
+            comment="work activate-script",
+        )
+        result = ctx.script_writer.write_activation_script(
+            activation_script,
+            command_name="pr-checkout",
+            comment=f"activate PR #{pr_number}",
+        )
+        result.output_for_shell_integration()
+    else:
+        styled_path = click.style(str(worktree_path), fg="cyan", bold=True)
+        user_output(f"Created worktree for PR #{pr_number} at {styled_path}")
+        user_output("\nShell integration not detected. Run 'erk init --shell' to set up.")
+        user_output(f"Or use: source <(erk pr checkout {pr_reference} --script)")