erk 0.4.5__py3-none-any.whl

erk/core/pr_utils.py

@@ -0,0 +1,30 @@
+"""Utility functions for PR handling."""
+
+from erk_shared.github.types import PullRequestInfo
+
+
+def select_display_pr(prs: list[PullRequestInfo]) -> PullRequestInfo | None:
+    """Select PR to display: prefer open, then merged, then closed.
+
+    Args:
+        prs: List of PRs sorted by created_at descending (most recent first)
+
+    Returns:
+        PR to display, or None if no PRs
+    """
+    # Check for open PRs (published or draft)
+    open_prs = [pr for pr in prs if pr.state in ("OPEN", "DRAFT")]
+    if open_prs:
+        return open_prs[0]  # Most recent open
+
+    # Fallback to merged PRs
+    merged_prs = [pr for pr in prs if pr.state == "MERGED"]
+    if merged_prs:
+        return merged_prs[0]  # Most recent merged
+
+    # Fallback to closed PRs
+    closed_prs = [pr for pr in prs if pr.state == "CLOSED"]
+    if closed_prs:
+        return closed_prs[0]  # Most recent closed
+
+    return None

erk/core/release_notes.py

@@ -0,0 +1,263 @@
+"""Release notes management for erk.
+
+Provides functionality for:
+- Parsing CHANGELOG.md into structured data
+- Detecting version changes since last run
+- Displaying upgrade banners
+"""
+
+import importlib.metadata
+import re
+from dataclasses import dataclass, field
+from functools import cache
+from pathlib import Path
+
+from erk_shared.gateway.erk_installation.abc import ErkInstallation
+
+
+@dataclass
+class ReleaseEntry:
+    """A single release entry from the changelog.
+
+    Items are stored as tuples of (text, indent_level) where indent_level
+    is 0 for top-level bullets, 1 for first nesting level, etc.
+    """
+
+    version: str
+    date: str | None
+    content: str
+    items: list[tuple[str, int]] = field(default_factory=list)
+    categories: dict[str, list[tuple[str, int]]] = field(default_factory=dict)
+
+
+@cache
+def _changelog_path() -> Path | None:
+    """Get the path to CHANGELOG.md.
+
+    In development, reads from repo root. In installed package, reads from bundled data dir.
+
+    Returns:
+        Path to CHANGELOG.md if found, None otherwise
+    """
+    # Bundled location (installed package via force-include)
+    bundled = Path(__file__).parent.parent / "data" / "CHANGELOG.md"
+    if bundled.exists():
+        return bundled
+
+    # Development fallback: repo root (3 levels up from src/erk/core/)
+    dev_root = Path(__file__).parent.parent.parent.parent / "CHANGELOG.md"
+    if dev_root.exists():
+        return dev_root
+
+    return None
+
+
+def get_current_version() -> str:
+    """Get the currently installed version of erk.
+
+    Returns:
+        Version string (e.g., "0.2.1")
+    """
+    return importlib.metadata.version("erk")
+
+
+def _parse_version(version: str) -> tuple[int, ...]:
+    """Parse a semantic version string into a tuple of integers.
+
+    Args:
+        version: Version string (e.g., "0.2.4")
+
+    Returns:
+        Tuple of integers (e.g., (0, 2, 4))
+    """
+    return tuple(int(part) for part in version.split("."))
+
+
+def _is_upgrade(current: str, last_seen: str) -> bool:
+    """Check if current version is newer than last_seen version.
+
+    Args:
+        current: Current version string
+        last_seen: Previously seen version string
+
+    Returns:
+        True if current is a newer version than last_seen
+    """
+    return _parse_version(current) > _parse_version(last_seen)
+
+
+def get_last_seen_version(erk_installation: ErkInstallation) -> str | None:
+    """Get the last version the user was notified about.
+
+    Args:
+        erk_installation: ErkInstallation gateway for accessing ~/.erk/
+
+    Returns:
+        Version string if tracking file exists, None otherwise
+    """
+    return erk_installation.get_last_seen_version()
+
+
+def update_last_seen_version(erk_installation: ErkInstallation, version: str) -> None:
+    """Update the last seen version tracking file.
+
+    Args:
+        erk_installation: ErkInstallation gateway for accessing ~/.erk/
+        version: Version string to record
+    """
+    erk_installation.update_last_seen_version(version)
+
+
+def parse_changelog(content: str) -> list[ReleaseEntry]:
+    """Parse CHANGELOG.md content into structured release entries.
+
+    Args:
+        content: Raw markdown content of CHANGELOG.md
+
+    Returns:
+        List of ReleaseEntry objects, one per version section
+    """
+    entries: list[ReleaseEntry] = []
+
+    # Match "## [0.2.1] - 2025-12-11" or "## [0.2.1] - 2025-12-11 14:30 PT" or "## [Unreleased]"
+    version_pattern = re.compile(
+        r"^## \[([^\]]+)\](?:\s*-\s*(\d{4}-\d{2}-\d{2}(?: \d{2}:\d{2} PT)?))?",
+        re.MULTILINE,
+    )
+
+    matches = list(version_pattern.finditer(content))
+
+    for i, match in enumerate(matches):
+        version = match.group(1)
+        date = match.group(2)
+
+        # Extract content between this header and the next
+        start = match.end()
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(content)
+        section_content = content[start:end].strip()
+
+        # Extract bullet items grouped by category (### Added, ### Changed, etc.)
+        # Items are stored as (text, indent_level) tuples to preserve nesting
+        items: list[tuple[str, int]] = []
+        categories: dict[str, list[tuple[str, int]]] = {}
+        current_category: str | None = None
+
+        for line in section_content.split("\n"):
+            # Count leading spaces to detect nesting level
+            stripped = line.lstrip()
+            leading_spaces = len(line) - len(stripped)
+            indent_level = leading_spaces // 2  # 2 spaces = 1 nesting level
+
+            # Check for category header (### Added, ### Changed, ### Fixed, etc.)
+            if stripped.startswith("### "):
+                current_category = stripped[4:]
+                categories[current_category] = []
+            elif stripped.startswith("- "):
+                item_text = stripped[2:]
+                item_tuple = (item_text, indent_level)
+                items.append(item_tuple)
+                if current_category is not None:
+                    categories[current_category].append(item_tuple)
+
+        entries.append(
+            ReleaseEntry(
+                version=version,
+                date=date,
+                content=section_content,
+                items=items,
+                categories=categories,
+            )
+        )
+
+    return entries
+
+
+def get_changelog_content() -> str | None:
+    """Read the CHANGELOG.md content.
+
+    Returns:
+        Changelog content if file exists, None otherwise
+    """
+    path = _changelog_path()
+    if path is None:
+        return None
+    return path.read_text(encoding="utf-8")
+
+
+def get_releases() -> list[ReleaseEntry]:
+    """Get all release entries from the bundled changelog.
+
+    Returns:
+        List of ReleaseEntry objects, empty if changelog not found
+    """
+    content = get_changelog_content()
+    if content is None:
+        return []
+    return parse_changelog(content)
+
+
+def get_release_for_version(version: str) -> ReleaseEntry | None:
+    """Get the release entry for a specific version.
+
+    Args:
+        version: Version string to look up
+
+    Returns:
+        ReleaseEntry if found, None otherwise
+    """
+    releases = get_releases()
+    for release in releases:
+        if release.version == version:
+            return release
+    return None
+
+
+def check_for_version_change(
+    erk_installation: ErkInstallation,
+) -> tuple[bool, list[ReleaseEntry]]:
+    """Check if the version has changed since last run.
+
+    Args:
+        erk_installation: ErkInstallation gateway for accessing ~/.erk/
+
+    Returns:
+        Tuple of (changed: bool, new_releases: list[ReleaseEntry])
+        where new_releases contains all releases newer than last seen
+    """
+    current = get_current_version()
+    last_seen = get_last_seen_version(erk_installation)
+
+    # First run - no notification needed, just update tracking
+    if last_seen is None:
+        update_last_seen_version(erk_installation, current)
+        return (False, [])
+
+    # No change
+    if current == last_seen:
+        return (False, [])
+
+    # Only show banner for upgrades, not downgrades
+    # This prevents repeated banners when switching between worktrees
+    # with different erk versions installed
+    if not _is_upgrade(current, last_seen):
+        # Don't update tracking on downgrade - keep tracking the max version seen
+        # This prevents repeated banners when switching between worktrees
+        return (False, [])
+
+    # Upgrade detected - find all releases between last_seen and current
+    releases = get_releases()
+    new_releases: list[ReleaseEntry] = []
+
+    for release in releases:
+        # Skip unreleased section
+        if release.version == "Unreleased":
+            continue
+        # Stop at last seen version
+        if release.version == last_seen:
+            break
+        new_releases.append(release)
+
+    # Update tracking file
+    update_last_seen_version(erk_installation, current)
+
+    return (True, new_releases)

erk/core/repo_discovery.py

@@ -0,0 +1,126 @@
+"""Repository discovery functionality.
+
+Discovers git repository information from a given path without requiring
+full ErkContext (enables config loading before context creation).
+"""
+
+from pathlib import Path
+
+# Re-export context types from erk_shared for backwards compatibility
+from erk_shared.context.types import NoRepoSentinel as NoRepoSentinel
+from erk_shared.context.types import RepoContext as RepoContext
+from erk_shared.git.abc import Git
+from erk_shared.git.real import RealGit
+from erk_shared.github.parsing import parse_git_remote_url
+from erk_shared.github.types import GitHubRepoId
+
+
+def in_erk_repo(repo_root: Path) -> bool:
+    """Check if the given path is inside the erk development repository.
+
+    This is used internally to detect when erk is running in its own development
+    repo, where artifacts are read directly from source rather than installed.
+
+    Args:
+        repo_root: Repository root path to check
+
+    Returns:
+        True if this appears to be the erk development repo
+    """
+    return (repo_root / "packages" / "erk-shared").exists()
+
+
+def discover_repo_or_sentinel(
+    cwd: Path, erk_root: Path, git_ops: Git | None = None
+) -> RepoContext | NoRepoSentinel:
+    """Walk up from `cwd` to find a directory containing `.git`.
+
+    Returns a RepoContext pointing to the repo root and the worktrees directory
+    for this repository, or NoRepoSentinel if not inside a git repo.
+
+    Note: For worktrees, `root` is the worktree directory (where git commands run),
+    while `repo_name` is derived from the main repository (for consistent metadata paths).
+
+    Args:
+        cwd: Current working directory to start search from
+        erk_root: Global erks root directory (from config)
+        git_ops: Git operations interface (defaults to RealGit)
+
+    Returns:
+        RepoContext if inside a git repository, NoRepoSentinel otherwise
+    """
+    ops = git_ops if git_ops is not None else RealGit()
+
+    if not ops.path_exists(cwd):
+        return NoRepoSentinel(message=f"Start path '{cwd}' does not exist")
+
+    cur = cwd.resolve()
+
+    # root: the actual working tree root (where git commands should run)
+    # main_repo_root: the main repository root (for deriving repo_name and metadata paths)
+    root: Path | None = None
+    main_repo_root: Path | None = None
+
+    git_common_dir = ops.get_git_common_dir(cur)
+    if git_common_dir is not None:
+        # We're in a git repository (possibly a worktree)
+        # git_common_dir points to the main repo's .git directory
+        main_repo_root = git_common_dir.parent.resolve()
+        # Use --show-toplevel to get the actual worktree root
+        root = ops.get_repository_root(cur)
+    else:
+        for parent in [cur, *cur.parents]:
+            git_path = parent / ".git"
+            if not ops.path_exists(git_path):
+                continue
+
+            if ops.is_dir(git_path):
+                root = parent
+                main_repo_root = parent
+                break
+
+    if root is None or main_repo_root is None:
+        return NoRepoSentinel(message="Not inside a git repository (no .git found up the tree)")
+
+    # Use main_repo_root for repo_name to ensure consistent metadata paths across worktrees
+    repo_name = main_repo_root.name
+    repo_dir = erk_root / "repos" / repo_name
+    worktrees_dir = repo_dir / "worktrees"
+    pool_json_path = repo_dir / "pool.json"
+
+    # Extract GitHub identity from remote URL
+    repo_id: GitHubRepoId | None = None
+    try:
+        remote_url = ops.get_remote_url(root, "origin")
+        owner_repo = parse_git_remote_url(remote_url)
+        repo_id = GitHubRepoId(owner=owner_repo[0], repo=owner_repo[1])
+    except ValueError:
+        # No origin remote or not a GitHub URL - continue without GitHub identity
+        pass
+
+    return RepoContext(
+        root=root,
+        main_repo_root=main_repo_root,
+        repo_name=repo_name,
+        repo_dir=repo_dir,
+        worktrees_dir=worktrees_dir,
+        pool_json_path=pool_json_path,
+        github=repo_id,
+    )
+
+
+def ensure_erk_metadata_dir(repo: RepoContext) -> Path:
+    """Ensure the erk metadata directory and worktrees subdirectory exist.
+
+    Creates repo.repo_dir (~/.erk/repos/<repo-name>) and repo.worktrees_dir
+    subdirectory if they don't exist.
+
+    Args:
+        repo: Repository context containing metadata paths
+
+    Returns:
+        Path to the erk metadata directory (repo.repo_dir), not git root
+    """
+    repo.repo_dir.mkdir(parents=True, exist_ok=True)
+    repo.worktrees_dir.mkdir(parents=True, exist_ok=True)
+    return repo.repo_dir

erk/core/script_writer.py

@@ -0,0 +1,41 @@
+"""Activation script writing operations.
+
+This module provides the RealScriptWriter implementation.
+ABC and types are imported from erk_shared.core.
+"""
+
+from erk.cli.shell_utils import write_script_to_temp
+from erk_shared.core.script_writer import ScriptResult as ScriptResult
+from erk_shared.core.script_writer import ScriptWriter as ScriptWriter
+
+
+class RealScriptWriter(ScriptWriter):
+    """Production implementation that writes real temp files."""
+
+    def write_activation_script(
+        self,
+        content: str,
+        *,
+        command_name: str,
+        comment: str,
+    ) -> ScriptResult:
+        """Write activation script to temp file.
+
+        Args:
+            content: The shell script content
+            command_name: Command generating the script
+            comment: Description for the script header
+
+        Returns:
+            ScriptResult with path to created temp file and full content
+        """
+        script_path = write_script_to_temp(
+            content,
+            command_name=command_name,
+            comment=comment,
+        )
+
+        # Read back the full content that was written (includes headers)
+        full_content = script_path.read_text(encoding="utf-8")
+
+        return ScriptResult(path=script_path, content=full_content)

erk/core/services/__init__.py

@@ -0,0 +1 @@
+"""Service layer for erk operations."""

erk/core/services/plan_list_service.py

@@ -0,0 +1,94 @@
+"""Service for efficiently fetching plan list data via batched API calls.
+
+Uses GraphQL nodes(ids: [...]) for O(1) batch lookup of workflow runs (~200ms for any N).
+All plan issues store last_dispatched_node_id in the plan-header metadata block.
+
+Performance optimization: When PR linkages are needed, uses unified GraphQL query via
+get_issues_with_pr_linkages() to fetch issues + PR linkages in a single API call (~600ms),
+instead of separate calls for issues (~500ms) and PR linkages (~1500ms).
+"""
+
+from erk_shared.core.plan_list_service import PlanListData as PlanListData
+from erk_shared.core.plan_list_service import PlanListService
+from erk_shared.github.abc import GitHub
+from erk_shared.github.issues import GitHubIssues
+from erk_shared.github.metadata.plan_header import extract_plan_header_dispatch_info
+from erk_shared.github.types import GitHubRepoLocation, WorkflowRun
+
+
+class RealPlanListService(PlanListService):
+    """Service for efficiently fetching plan list data.
+
+    Composes GitHub and GitHubIssues integrations to batch fetch all data
+    needed for plan listing. Uses GraphQL nodes(ids: [...]) for efficient
+    batch lookup of workflow runs by node_id.
+    """
+
+    def __init__(self, github: GitHub, github_issues: GitHubIssues) -> None:
+        """Initialize PlanListService with required integrations.
+
+        Args:
+            github: GitHub integration for PR and workflow operations
+            github_issues: GitHub issues integration for issue operations
+        """
+        self._github = github
+        self._github_issues = github_issues
+
+    def get_plan_list_data(
+        self,
+        *,
+        location: GitHubRepoLocation,
+        labels: list[str],
+        state: str | None = None,
+        limit: int | None = None,
+        skip_workflow_runs: bool = False,
+        creator: str | None = None,
+    ) -> PlanListData:
+        """Batch fetch all data needed for plan listing.
+
+        Args:
+            location: GitHub repository location (local root + repo identity)
+            labels: Labels to filter issues by (e.g., ["erk-plan"])
+            state: Filter by state ("open", "closed", or None for all)
+            limit: Maximum number of issues to return (None for no limit)
+            skip_workflow_runs: If True, skip fetching workflow runs (for performance)
+            creator: Filter by creator username (e.g., "octocat"). If provided,
+                only issues created by this user are returned.
+
+        Returns:
+            PlanListData containing issues, PR linkages, and workflow runs
+        """
+        # Always use unified path: issues + PR linkages in one API call (~600ms)
+        issues, pr_linkages = self._github.get_issues_with_pr_linkages(
+            location,
+            labels,
+            state=state,
+            limit=limit,
+            creator=creator,
+        )
+
+        # Conditionally fetch workflow runs (skip for performance when not needed)
+        workflow_runs: dict[int, WorkflowRun | None] = {}
+        if not skip_workflow_runs:
+            # Extract node_ids from plan-header metadata
+            node_id_to_issue: dict[str, int] = {}
+            for issue in issues:
+                _, node_id, _ = extract_plan_header_dispatch_info(issue.body)
+                if node_id is not None:
+                    node_id_to_issue[node_id] = issue.number
+
+            # Batch fetch workflow runs via GraphQL nodes(ids: [...])
+            if node_id_to_issue:
+                runs_by_node_id = self._github.get_workflow_runs_by_node_ids(
+                    location.root,
+                    list(node_id_to_issue.keys()),
+                )
+                for node_id, run in runs_by_node_id.items():
+                    issue_number = node_id_to_issue[node_id]
+                    workflow_runs[issue_number] = run
+
+        return PlanListData(
+            issues=issues,
+            pr_linkages=pr_linkages,
+            workflow_runs=workflow_runs,
+        )

erk/core/shell.py

@@ -0,0 +1,51 @@
+"""Shell detection and tool availability operations.
+
+This module provides abstraction over shell-specific operations like detecting
+the current shell and checking if command-line tools are installed. This abstraction
+enables dependency injection for testing without mock.patch.
+
+The Shell ABC and implementations (RealShell, FakeShell) are defined in erk_shared
+and re-exported here. Erk-specific helper functions remain in this module.
+"""
+
+import json
+
+# Re-export all Shell types from erk_shared
+from erk_shared.gateway.shell import FakeShell as FakeShell
+from erk_shared.gateway.shell import RealShell as RealShell
+from erk_shared.gateway.shell import Shell as Shell
+from erk_shared.gateway.shell import detect_shell_from_env as detect_shell_from_env
+from erk_shared.subprocess_utils import run_subprocess_with_context as run_subprocess_with_context
+
+
+def _extract_issue_url_from_output(output: str) -> str | None:
+    """Extract issue_url from Claude CLI output that may contain mixed content.
+
+    Claude CLI with --print mode can output conversation/thinking text before
+    the final JSON. This function searches from the end of the output to find
+    a JSON object containing issue_url.
+
+    Args:
+        output: The stdout from Claude CLI (may contain non-JSON text)
+
+    Returns:
+        The issue_url string if found, None otherwise.
+    """
+    if not output:
+        return None
+
+    # Search from the end of output to find JSON with issue_url
+    for line in reversed(output.strip().split("\n")):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            data = json.loads(line)
+            if isinstance(data, dict):
+                issue_url = data.get("issue_url")
+                if isinstance(issue_url, str):
+                    return issue_url
+        except json.JSONDecodeError:
+            continue
+
+    return None

erk/core/user_feedback.py

@@ -0,0 +1,11 @@
+"""User-facing diagnostic output with mode awareness.
+
+This is a thin shim that re-exports from erk_shared.gateway.feedback.
+All implementations are in erk_shared for sharing across packages.
+"""
+
+# Re-export all UserFeedback types from erk_shared
+from erk_shared.gateway.feedback import FakeUserFeedback as FakeUserFeedback
+from erk_shared.gateway.feedback import InteractiveFeedback as InteractiveFeedback
+from erk_shared.gateway.feedback import SuppressedFeedback as SuppressedFeedback
+from erk_shared.gateway.feedback import UserFeedback as UserFeedback

erk/core/version_check.py

@@ -0,0 +1,55 @@
+"""Version checking for erk tool installation.
+
+Compares the installed version against a repository-specified required version.
+Used to warn users when their installed erk is outdated compared to what the
+repository requires.
+"""
+
+from pathlib import Path
+
+from packaging.version import Version
+
+
+def get_required_version(repo_root: Path) -> str | None:
+    """Read required version from .erk/required-erk-uv-tool-version.
+
+    Args:
+        repo_root: Path to the git repository root
+
+    Returns:
+        Version string if file exists, None otherwise
+    """
+    version_file = repo_root / ".erk" / "required-erk-uv-tool-version"
+    if not version_file.exists():
+        return None
+    return version_file.read_text(encoding="utf-8").strip()
+
+
+def is_version_mismatch(installed: str, required: str) -> bool:
+    """Check if installed version doesn't match required version exactly.
+
+    Args:
+        installed: Currently installed version (e.g., "0.2.7")
+        required: Required version from repo (e.g., "0.2.8")
+
+    Returns:
+        True if versions don't match exactly, False if they match
+    """
+    return Version(installed) != Version(required)
+
+
+def format_version_warning(installed: str, required: str) -> str:
+    """Format warning message for version mismatch.
+
+    Args:
+        installed: Currently installed version
+        required: Required version from repo
+
+    Returns:
+        Formatted warning message
+    """
+    return (
+        f"⚠️  Your erk ({installed}) doesn't match required ({required})\n"
+        f"   You must update or erk may not work properly.\n"
+        f"   Update: uv tool upgrade erk"
+    )