erk 0.4.5__py3-none-any.whl

erk/cli/commands/exec/scripts/get_plan_metadata.py

@@ -0,0 +1,95 @@
+"""Extract arbitrary metadata fields from a plan issue's plan-header block.
+
+Usage:
+    erk exec get-plan-metadata <issue-number> <field-name>
+
+Output:
+    JSON with success status and field value (or null if field doesn't exist)
+
+Exit Codes:
+    0: Success (field found or null)
+    1: Error (issue not found)
+"""
+
+import json
+from dataclasses import asdict, dataclass
+from typing import Any
+
+import click
+
+from erk_shared.context.helpers import require_issues as require_github_issues
+from erk_shared.context.helpers import require_repo_root
+from erk_shared.github.metadata.core import find_metadata_block
+
+
+@dataclass(frozen=True)
+class MetadataSuccess:
+    """Success response for metadata extraction."""
+
+    success: bool
+    value: Any
+    issue_number: int
+    field: str
+
+
+@dataclass(frozen=True)
+class MetadataError:
+    """Error response for metadata extraction."""
+
+    success: bool
+    error: str
+    message: str
+
+
+@click.command(name="get-plan-metadata")
+@click.argument("issue_number", type=int)
+@click.argument("field_name")
+@click.pass_context
+def get_plan_metadata(
+    ctx: click.Context,
+    issue_number: int,
+    field_name: str,
+) -> None:
+    """Extract a metadata field from a plan issue's plan-header block.
+
+    Fetches the issue, extracts the plan-header block, and returns the
+    specified field value. Returns null if the field doesn't exist.
+    """
+    github_issues = require_github_issues(ctx)
+    repo_root = require_repo_root(ctx)
+
+    # Fetch current issue
+    try:
+        issue = github_issues.get_issue(repo_root, issue_number)
+    except RuntimeError as e:
+        result = MetadataError(
+            success=False,
+            error="issue_not_found",
+            message=f"Issue #{issue_number} not found: {e}",
+        )
+        click.echo(json.dumps(asdict(result)), err=True)
+        raise SystemExit(1) from None
+
+    # Extract plan-header block
+    block = find_metadata_block(issue.body, "plan-header")
+    if block is None:
+        # No plan-header block - return null for the field
+        result_success = MetadataSuccess(
+            success=True,
+            value=None,
+            issue_number=issue_number,
+            field=field_name,
+        )
+        click.echo(json.dumps(asdict(result_success)))
+        return
+
+    # Get field value (None if field doesn't exist)
+    field_value = block.data.get(field_name)
+
+    result_success = MetadataSuccess(
+        success=True,
+        value=field_value,
+        issue_number=issue_number,
+        field=field_name,
+    )
+    click.echo(json.dumps(asdict(result_success)))

erk/cli/commands/exec/scripts/get_pr_body_footer.py

@@ -0,0 +1,70 @@
+"""Generate PR body footer for remote implementation PRs.
+
+This exec command generates a footer section for PR descriptions that includes
+the `erk pr checkout` command. This is used by the GitHub Actions workflow when
+creating PRs from remote implementations.
+
+Usage:
+    erk exec get-pr-body-footer --pr-number 123
+    erk exec get-pr-body-footer --pr-number 123 --issue-number 456
+
+Output:
+    Markdown footer with checkout command and optional issue closing reference
+
+Exit Codes:
+    0: Success
+    1: Error (missing pr-number)
+
+Examples:
+    $ erk exec get-pr-body-footer --pr-number 1895
+
+    ---
+
+    To checkout this PR in a fresh worktree and environment locally, run:
+
+    ```
+    erk pr checkout 1895 && erk pr sync --dangerous
+    ```
+
+    $ erk exec get-pr-body-footer --pr-number 1895 --issue-number 123
+
+    ---
+
+    Closes #123
+
+    To checkout this PR in a fresh worktree and environment locally, run:
+
+    ```
+    erk pr checkout 1895 && erk pr sync --dangerous
+    ```
+"""
+
+import click
+
+from erk_shared.github.pr_footer import build_pr_body_footer
+
+
+@click.command(name="get-pr-body-footer")
+@click.option("--pr-number", type=int, required=True, help="PR number for checkout command")
+@click.option("--issue-number", type=int, required=False, help="Issue number to close")
+@click.option(
+    "--plans-repo", type=str, required=False, help="Target repo in owner/repo format (cross-repo)"
+)
+def get_pr_body_footer(pr_number: int, issue_number: int | None, plans_repo: str | None) -> None:
+    """Generate PR body footer with checkout command.
+
+    Outputs a markdown footer section that includes the `erk pr checkout` command,
+    allowing users to easily checkout the PR in a fresh worktree locally.
+
+    When issue_number is provided, includes "Closes #N" (or "Closes owner/repo#N"
+    for cross-repo plans) to auto-close the issue when the PR is merged.
+
+    Args:
+        pr_number: The PR number to include in the checkout command
+        issue_number: Optional issue number to close when PR is merged
+        plans_repo: Optional target repo in "owner/repo" format for cross-repo
+    """
+    output = build_pr_body_footer(
+        pr_number=pr_number, issue_number=issue_number, plans_repo=plans_repo
+    )
+    click.echo(output, nl=False)

erk/cli/commands/exec/scripts/get_pr_discussion_comments.py

@@ -0,0 +1,149 @@
+"""Fetch PR discussion comments (main conversation thread) for agent context injection.
+
+This exec command fetches discussion comments from the PR's main conversation
+(not inline code review comments) and outputs them as JSON for agent processing.
+
+Usage:
+    erk exec get-pr-discussion-comments
+    erk exec get-pr-discussion-comments --pr 123
+
+Output:
+    JSON with success status, PR info, and discussion comments
+
+Exit Codes:
+    0: Success (or graceful error with JSON output)
+    1: Context not initialized
+
+Examples:
+    $ erk exec get-pr-discussion-comments
+    {"success": true, "pr_number": 123, "comments": [...]}
+
+    $ erk exec get-pr-discussion-comments --pr 456
+    {"success": true, "pr_number": 456, "comments": [...]}
+"""
+
+import json
+from typing import TypedDict
+
+import click
+
+from erk.cli.script_output import exit_with_error
+from erk_shared.context.helpers import (
+    get_current_branch,
+    require_github,
+    require_repo_root,
+)
+from erk_shared.context.helpers import (
+    require_issues as require_github_issues,
+)
+from erk_shared.github.checks import GitHubChecks
+from erk_shared.github.issues.types import IssueComment
+from erk_shared.github.types import PRDetails
+from erk_shared.non_ideal_state import (
+    BranchDetectionFailed,
+    GitHubAPIFailed,
+    NoPRForBranch,
+    PRNotFoundError,
+)
+
+
+def _ensure_branch(branch_result: str | BranchDetectionFailed) -> str:
+    """Ensure branch was detected, exit with error if not."""
+    if isinstance(branch_result, BranchDetectionFailed):
+        exit_with_error(branch_result.error_type, branch_result.message)
+    assert not isinstance(branch_result, BranchDetectionFailed)  # Type narrowing after NoReturn
+    return branch_result
+
+
+def _ensure_pr_result_for_branch(
+    pr_result: PRDetails | NoPRForBranch,
+) -> PRDetails:
+    """Ensure PR lookup by branch succeeded, exit with appropriate error if not."""
+    if isinstance(pr_result, NoPRForBranch):
+        exit_with_error(pr_result.error_type, pr_result.message)
+    assert not isinstance(pr_result, NoPRForBranch)  # Type narrowing after NoReturn
+    return pr_result
+
+
+def _ensure_pr_result_by_number(
+    pr_result: PRDetails | PRNotFoundError,
+) -> PRDetails:
+    """Ensure PR lookup by number succeeded, exit with appropriate error if not."""
+    if isinstance(pr_result, PRNotFoundError):
+        exit_with_error(pr_result.error_type, pr_result.message)
+    assert not isinstance(pr_result, PRNotFoundError)  # Type narrowing after NoReturn
+    return pr_result
+
+
+def _ensure_comments(
+    comments_result: list[IssueComment] | GitHubAPIFailed,
+) -> list[IssueComment]:
+    """Ensure comments fetch succeeded, exit with error if not."""
+    if isinstance(comments_result, GitHubAPIFailed):
+        exit_with_error(comments_result.error_type, comments_result.message)
+    assert not isinstance(comments_result, GitHubAPIFailed)  # Type narrowing after NoReturn
+    return comments_result
+
+
+class DiscussionCommentDict(TypedDict):
+    """Typed dict for a single discussion comment in JSON output."""
+
+    id: int
+    author: str
+    body: str
+    url: str
+
+
+@click.command(name="get-pr-discussion-comments")
+@click.option("--pr", type=int, default=None, help="PR number (defaults to current branch's PR)")
+@click.pass_context
+def get_pr_discussion_comments(ctx: click.Context, pr: int | None) -> None:
+    """Fetch PR discussion comments for agent context injection.
+
+    Queries GitHub for discussion comments on a pull request's main
+    conversation thread (not inline code review comments) and outputs
+    structured JSON for agent processing.
+
+    If --pr is not specified, finds the PR for the current branch.
+    """
+    # Get dependencies from context
+    repo_root = require_repo_root(ctx)
+    github = require_github(ctx)
+    github_issues = require_github_issues(ctx)
+
+    # Get PR details - either from current branch or specified PR number
+    if pr is None:
+        branch = _ensure_branch(GitHubChecks.branch(get_current_branch(ctx)))
+        pr_details = _ensure_pr_result_for_branch(
+            GitHubChecks.pr_for_branch(github, repo_root, branch)
+        )
+    else:
+        pr_details = _ensure_pr_result_by_number(GitHubChecks.pr_by_number(github, repo_root, pr))
+
+    # Fetch discussion comments (exits on failure)
+    comments = _ensure_comments(
+        GitHubChecks.issue_comments(github_issues, repo_root, pr_details.number)
+    )
+
+    # Format comments for JSON output
+    formatted_comments: list[DiscussionCommentDict] = []
+    for comment in comments:
+        assert isinstance(comment, IssueComment)  # Runtime verification for type safety
+        formatted_comments.append(
+            {
+                "id": comment.id,
+                "author": comment.author,
+                "body": comment.body,
+                "url": comment.url,
+            }
+        )
+
+    result = {
+        "success": True,
+        "pr_number": pr_details.number,
+        "pr_url": pr_details.url,
+        "pr_title": pr_details.title,
+        "comments": formatted_comments,
+    }
+    click.echo(json.dumps(result, indent=2))
+    raise SystemExit(0)

erk/cli/commands/exec/scripts/get_pr_review_comments.py

@@ -0,0 +1,155 @@
+"""Fetch PR review comments for agent context injection.
+
+This exec command fetches unresolved (or all) PR review comments from GitHub
+and outputs them as JSON for agent processing.
+
+Usage:
+    erk exec get-pr-review-comments
+    erk exec get-pr-review-comments --pr 123
+    erk exec get-pr-review-comments --include-resolved
+
+Output:
+    JSON with success status, PR info, and review threads
+
+Exit Codes:
+    0: Success (or graceful error with JSON output)
+    1: Context not initialized
+
+Examples:
+    $ erk exec get-pr-review-comments
+    {"success": true, "pr_number": 123, "threads": [...]}
+
+    $ erk exec get-pr-review-comments --pr 456
+    {"success": true, "pr_number": 456, "threads": [...]}
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from typing import TypedDict
+
+import click
+
+from erk.cli.script_output import exit_with_error
+from erk_shared.context.helpers import get_current_branch, require_github, require_repo_root
+from erk_shared.github.types import PRDetails, PRNotFound, PRReviewThread
+
+
+class ReviewCommentDict(TypedDict):
+    """Typed dict for a single review comment in JSON output."""
+
+    author: str
+    body: str
+    created_at: str
+
+
+class ReviewThreadDict(TypedDict):
+    """Typed dict for a review thread in JSON output."""
+
+    id: str
+    path: str
+    line: int | None
+    is_outdated: bool
+    comments: list[ReviewCommentDict]
+
+
+@dataclass(frozen=True)
+class ReviewCommentSuccess:
+    """Success response for PR review comments."""
+
+    success: bool
+    pr_number: int
+    pr_url: str
+    pr_title: str
+    threads: list[ReviewThreadDict]
+
+
+def _ensure_branch(branch: str | None) -> str:
+    """Ensure branch was detected, exit with error if not."""
+    if branch is None:
+        exit_with_error("branch-detection-failed", "Could not determine current branch")
+    assert branch is not None  # Type narrowing after NoReturn
+    return branch
+
+
+def _ensure_pr_result(
+    pr_result: PRDetails | PRNotFound,
+    *,
+    branch: str | None,
+    pr_number: int | None,
+) -> PRDetails:
+    """Ensure PR lookup succeeded, exit with appropriate error if not."""
+    if isinstance(pr_result, PRNotFound):
+        if branch is not None:
+            exit_with_error("no-pr-for-branch", f"No PR found for branch '{branch}'")
+        else:
+            exit_with_error("pr-not-found", f"PR #{pr_number} not found")
+    assert not isinstance(pr_result, PRNotFound)  # Type narrowing after NoReturn
+    return pr_result
+
+
+def _format_thread_for_json(thread: PRReviewThread) -> ReviewThreadDict:
+    """Format a PRReviewThread for JSON output."""
+    comments: list[ReviewCommentDict] = []
+    for comment in thread.comments:
+        comments.append(
+            {
+                "author": comment.author,
+                "body": comment.body,
+                "created_at": comment.created_at,
+            }
+        )
+
+    return {
+        "id": thread.id,
+        "path": thread.path,
+        "line": thread.line,
+        "is_outdated": thread.is_outdated,
+        "comments": comments,
+    }
+
+
+@click.command(name="get-pr-review-comments")
+@click.option("--pr", type=int, default=None, help="PR number (defaults to current branch's PR)")
+@click.option("--include-resolved", is_flag=True, help="Include resolved threads")
+@click.pass_context
+def get_pr_review_comments(ctx: click.Context, pr: int | None, include_resolved: bool) -> None:
+    """Fetch PR review comments for agent context injection.
+
+    Queries GitHub for review threads on a pull request and outputs
+    structured JSON for agent processing. By default, excludes resolved
+    threads.
+
+    If --pr is not specified, finds the PR for the current branch.
+    """
+    # Get dependencies from context
+    repo_root = require_repo_root(ctx)
+    github = require_github(ctx)
+
+    # Get PR details - either from current branch or specified PR number
+    if pr is None:
+        branch = _ensure_branch(get_current_branch(ctx))
+        pr_result = _ensure_pr_result(
+            github.get_pr_for_branch(repo_root, branch), branch=branch, pr_number=None
+        )
+    else:
+        pr_result = _ensure_pr_result(github.get_pr(repo_root, pr), branch=None, pr_number=pr)
+
+    # Fetch review threads
+    try:
+        threads = github.get_pr_review_threads(
+            repo_root, pr_result.number, include_resolved=include_resolved
+        )
+    except RuntimeError as e:
+        exit_with_error("github-api-failed", str(e))
+
+    result_success = ReviewCommentSuccess(
+        success=True,
+        pr_number=pr_result.number,
+        pr_url=pr_result.url,
+        pr_title=pr_result.title,
+        threads=[_format_thread_for_json(t) for t in threads],
+    )
+    click.echo(json.dumps(asdict(result_success), indent=2))
+    raise SystemExit(0)

erk/cli/commands/exec/scripts/impl_init.py

@@ -0,0 +1,158 @@
+"""Initialize implementation by validating .impl/ folder.
+
+This exec command validates .impl/ folder for /erk:plan-implement:
+- Validates .impl/ folder structure (plan.md exists)
+- Checks for GitHub issue tracking (issue.json)
+- Parses "Related Documentation" section for skills and docs
+
+Usage:
+    erk exec impl-init --json
+
+Output:
+    JSON with validation status and related docs
+    Always outputs JSON (for machine parsing by slash command)
+
+Exit Codes:
+    0: Success
+    1: Validation error
+
+Examples:
+    $ erk exec impl-init --json
+    {"valid": true, "impl_type": "impl", "has_issue_tracking": true, ...}
+"""
+
+import json
+import re
+from pathlib import Path
+from typing import NoReturn
+
+import click
+
+from erk_shared.impl_folder import read_issue_reference
+
+
+def _error_json(error_type: str, message: str) -> NoReturn:
+    """Output error as JSON and exit with code 1."""
+    result = {"valid": False, "error_type": error_type, "message": message}
+    click.echo(json.dumps(result))
+    raise SystemExit(1)
+
+
+def _validate_impl_folder() -> tuple[Path, str]:
+    """Validate .impl/ or .worker-impl/ folder exists and has required files.
+
+    Returns:
+        Tuple of (impl_dir Path, impl_type string)
+
+    Raises:
+        SystemExit: If validation fails
+    """
+    cwd = Path.cwd()
+
+    # Check .impl/ first, then .worker-impl/
+    impl_dir = cwd / ".impl"
+    impl_type = "impl"
+
+    if not impl_dir.exists():
+        impl_dir = cwd / ".worker-impl"
+        impl_type = "worker-impl"
+
+    if not impl_dir.exists():
+        _error_json(
+            "no_impl_folder",
+            "No .impl/ or .worker-impl/ folder found in current directory",
+        )
+
+    plan_file = impl_dir / "plan.md"
+    if not plan_file.exists():
+        _error_json("no_plan_file", f"No plan.md found in {impl_dir.name}/ folder")
+
+    return impl_dir, impl_type
+
+
+def _extract_related_docs(plan_content: str) -> dict[str, list[str]]:
+    """Extract Related Documentation section from plan content.
+
+    Parses markdown like:
+    ## Related Documentation
+
+    **Skills:**
+    - `dignified-python-313`
+
+    **Docs:**
+    - [Kit CLI Testing](docs/agent/testing/kit-cli-testing.md)
+
+    Args:
+        plan_content: Full plan markdown content
+
+    Returns:
+        Dict with 'skills' and 'docs' lists
+    """
+    result: dict[str, list[str]] = {"skills": [], "docs": []}
+
+    # Find Related Documentation section
+    related_docs_pattern = re.compile(
+        r"##\s+Related Documentation\s*\n(.*?)(?=\n##|\Z)",
+        re.DOTALL | re.IGNORECASE,
+    )
+    match = related_docs_pattern.search(plan_content)
+
+    if match is None:
+        return result
+
+    section = match.group(1)
+
+    # Extract skills (backtick-enclosed names after bullet points)
+    skills_section = re.search(r"\*\*Skills:\*\*\s*\n(.*?)(?=\*\*|\Z)", section, re.DOTALL)
+    if skills_section:
+        skill_pattern = re.compile(r"-\s*`([^`]+)`")
+        result["skills"] = skill_pattern.findall(skills_section.group(1))
+
+    # Extract docs (markdown links or plain paths)
+    docs_section = re.search(r"\*\*Docs:\*\*\s*\n(.*?)(?=\*\*|\Z)", section, re.DOTALL)
+    if docs_section:
+        # Match markdown links [text](path) or backtick paths `path`
+        link_pattern = re.compile(r"-\s*(?:\[[^\]]*\]\(([^)]+)\)|`([^`]+)`)")
+        for m in link_pattern.finditer(docs_section.group(1)):
+            doc_path = m.group(1) or m.group(2)
+            if doc_path:
+                result["docs"].append(doc_path)
+
+    return result
+
+
+@click.command(name="impl-init")
+@click.option("--json", "json_output", is_flag=True, default=True, help="Output JSON (default)")
+def impl_init(json_output: bool) -> None:
+    """Initialize implementation by validating .impl/ folder.
+
+    Validates .impl/ folder for /erk:plan-implement.
+    Returns structured JSON with validation status and related documentation.
+    """
+    # Validate folder structure
+    impl_dir, impl_type = _validate_impl_folder()
+
+    # Get issue reference info
+    issue_ref = read_issue_reference(impl_dir)
+    has_issue_tracking = issue_ref is not None
+    issue_number = issue_ref.issue_number if issue_ref else None
+
+    # Read plan content
+    plan_file = impl_dir / "plan.md"
+    plan_content = plan_file.read_text(encoding="utf-8")
+
+    # Extract related documentation
+    related_docs = _extract_related_docs(plan_content)
+
+    # Build result
+    result: dict = {
+        "valid": True,
+        "impl_type": impl_type,
+        "has_issue_tracking": has_issue_tracking,
+        "related_docs": related_docs,
+    }
+
+    if issue_number is not None:
+        result["issue_number"] = issue_number
+
+    click.echo(json.dumps(result))