erk 0.4.5__py3-none-any.whl

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

@@ -0,0 +1,237 @@
+"""Post extraction workflow status comments to GitHub issues.
+
+Usage:
+    erk exec post-extraction-comment \
+        --issue-number 123 \
+        --status started \
+        --workflow-run-url "https://..."
+
+Status options:
+    - started: Extraction workflow has begun
+    - failed: Extraction failed with error
+    - complete: Extraction succeeded with PR
+    - no-changes: No documentation changes needed
+
+Output:
+    JSON with success status and comment_url
+"""
+
+import json
+from datetime import UTC, datetime
+
+import click
+
+from erk_shared.context.helpers import require_issues as require_github_issues
+from erk_shared.context.helpers import require_repo_root
+
+
+def _format_started_comment(workflow_run_url: str | None) -> str:
+    """Format the started status comment."""
+    started_at = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    lines = [
+        "⚙️ **Documentation extraction started**",
+        "",
+        "<details>",
+        "<summary>📋 Metadata</summary>",
+        "",
+        "```yaml",
+        "status: started",
+        f"started_at: {started_at}",
+    ]
+
+    if workflow_run_url:
+        lines.append(f"workflow_run_url: {workflow_run_url}")
+
+    lines.extend(
+        [
+            "```",
+            "",
+            "</details>",
+            "",
+            "---",
+            "",
+            "Extracting session data from issue comments...",
+        ]
+    )
+
+    if workflow_run_url:
+        lines.extend(["", f"[View workflow run]({workflow_run_url})"])
+
+    return "\n".join(lines)
+
+
+def _format_failed_comment(
+    workflow_run_url: str | None,
+    error_message: str | None,
+) -> str:
+    """Format the failed status comment."""
+    lines = ["❌ **Documentation extraction failed**", ""]
+
+    if error_message:
+        lines.extend([f"**Error:** {error_message}", ""])
+
+    lines.extend(
+        [
+            "No session content was found in the issue comments. This may happen if:",
+            "- The raw extraction issue was created without session XML",
+            "- The session content blocks are malformed",
+        ]
+    )
+
+    if workflow_run_url:
+        lines.extend(["", f"[View workflow run]({workflow_run_url})"])
+
+    lines.extend(
+        [
+            "",
+            "To retry, run the extraction manually:",
+            "```",
+            "/erk:create-extraction-plan",
+            "```",
+        ]
+    )
+
+    return "\n".join(lines)
+
+
+def _format_complete_comment(pr_url: str | None) -> str:
+    """Format the complete status comment."""
+    completed_at = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    lines = [
+        "✅ **Documentation extraction complete**",
+        "",
+    ]
+
+    if pr_url:
+        lines.extend([f"**PR:** {pr_url}", ""])
+
+    lines.extend(
+        [
+            "<details>",
+            "<summary>📋 Metadata</summary>",
+            "",
+            "```yaml",
+            "status: complete",
+            f"completed_at: {completed_at}",
+        ]
+    )
+
+    if pr_url:
+        lines.append(f"pr_url: {pr_url}")
+
+    lines.extend(
+        [
+            "```",
+            "",
+            "</details>",
+            "",
+            "---",
+            "",
+            "The extraction has created documentation improvements. Please review the PR.",
+        ]
+    )
+
+    return "\n".join(lines)
+
+
+def _format_no_changes_comment() -> str:
+    """Format the no-changes status comment."""
+    return "\n".join(
+        [
+            "ℹ️ **No documentation changes needed**",
+            "",
+            "The extraction analysis did not produce any documentation changes.",
+            "This may happen if the session did not contain extractable patterns.",
+        ]
+    )
+
+
+@click.command(name="post-extraction-comment")
+@click.option(
+    "--issue-number",
+    type=int,
+    required=True,
+    help="GitHub issue number",
+)
+@click.option(
+    "--status",
+    type=click.Choice(["started", "failed", "complete", "no-changes"]),
+    required=True,
+    help="Extraction status",
+)
+@click.option(
+    "--workflow-run-url",
+    type=str,
+    default=None,
+    help="URL to the workflow run (for started/failed)",
+)
+@click.option(
+    "--error-message",
+    type=str,
+    default=None,
+    help="Error message (for failed status)",
+)
+@click.option(
+    "--pr-url",
+    type=str,
+    default=None,
+    help="PR URL (for complete status)",
+)
+@click.pass_context
+def post_extraction_comment(
+    ctx: click.Context,
+    issue_number: int,
+    status: str,
+    workflow_run_url: str | None,
+    error_message: str | None,
+    pr_url: str | None,
+) -> None:
+    """Post extraction workflow status comment to a GitHub issue.
+
+    Posts a formatted status comment based on the extraction workflow stage.
+    """
+    github = require_github_issues(ctx)
+    repo_root = require_repo_root(ctx)
+
+    # Format the comment based on status
+    if status == "started":
+        comment_body = _format_started_comment(workflow_run_url)
+    elif status == "failed":
+        comment_body = _format_failed_comment(workflow_run_url, error_message)
+    elif status == "complete":
+        comment_body = _format_complete_comment(pr_url)
+    elif status == "no-changes":
+        comment_body = _format_no_changes_comment()
+    else:
+        click.echo(json.dumps({"success": False, "error": f"Unknown status: {status}"}))
+        raise SystemExit(1)
+
+    # Post the comment
+    try:
+        github.add_comment(repo_root, issue_number, comment_body)
+    except RuntimeError as e:
+        click.echo(
+            json.dumps(
+                {
+                    "success": False,
+                    "error": f"Failed to post comment: {e}",
+                }
+            )
+        )
+        raise SystemExit(1) from e
+
+    click.echo(
+        json.dumps(
+            {
+                "success": True,
+                "issue_number": issue_number,
+                "status": status,
+            }
+        )
+    )
+
+
+if __name__ == "__main__":
+    post_extraction_comment()

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

@@ -0,0 +1,133 @@
+"""Post or update a PR summary comment with a unique marker.
+
+This exec command finds an existing PR comment containing a marker,
+updates it if found, or creates a new comment if not found.
+
+Usage:
+    erk exec post-or-update-pr-summary --pr-number 123 \\
+        --marker "<!-- my-marker -->" --body "Summary text"
+
+Output:
+    JSON with success status, action taken (created/updated), and comment ID
+
+Exit Codes:
+    0: Always (even on error, to support || true pattern)
+
+Examples:
+    $ erk exec post-or-update-pr-summary --pr-number 123 \\
+        --marker "<!-- review -->" --body "# Review"
+    {"success": true, "action": "created", "comment_id": 12345}
+
+    $ erk exec post-or-update-pr-summary --pr-number 123 \\
+        --marker "<!-- review -->" --body "# Updated"
+    {"success": true, "action": "updated", "comment_id": 12345}
+"""
+
+import json
+from dataclasses import asdict, dataclass
+
+import click
+
+from erk_shared.context.helpers import require_github, require_repo_root
+
+
+@dataclass(frozen=True)
+class SummaryCommentSuccess:
+    """Success response for summary comment posting."""
+
+    success: bool
+    action: str  # "created" or "updated"
+    comment_id: int
+
+
+@dataclass(frozen=True)
+class SummaryCommentError:
+    """Error response for summary comment posting."""
+
+    success: bool
+    error_type: str
+    message: str
+
+
+@click.command(name="post-or-update-pr-summary")
+@click.option("--pr-number", required=True, type=int, help="PR number to comment on")
+@click.option("--marker", required=True, help="HTML marker to identify the comment")
+@click.option("--body", required=True, help="Comment body text (must include marker)")
+@click.pass_context
+def post_or_update_pr_summary(
+    ctx: click.Context,
+    pr_number: int,
+    marker: str,
+    body: str,
+) -> None:
+    """Post or update a PR summary comment.
+
+    Finds an existing comment containing the marker and updates it,
+    or creates a new comment if none found. The body should include
+    the marker for future lookups.
+
+    PR_NUMBER: The PR to comment on
+    MARKER: HTML marker to identify the comment (e.g., <!-- my-review -->)
+    BODY: Comment text (should include the marker for future updates)
+    """
+    repo_root = require_repo_root(ctx)
+    github = require_github(ctx)
+
+    # Ensure body contains the marker for future lookups
+    if marker not in body:
+        result = SummaryCommentError(
+            success=False,
+            error_type="marker_not_in_body",
+            message=f"The body must contain the marker '{marker}' for future lookups",
+        )
+        click.echo(json.dumps(asdict(result), indent=2))
+        raise SystemExit(0)
+
+    # Try to find existing comment with marker
+    try:
+        existing_id = github.find_pr_comment_by_marker(repo_root, pr_number, marker)
+    except RuntimeError as e:
+        result = SummaryCommentError(
+            success=False,
+            error_type="find_failed",
+            message=f"Failed to search for existing comment: {e}",
+        )
+        click.echo(json.dumps(asdict(result), indent=2))
+        raise SystemExit(0) from None
+
+    if existing_id is not None:
+        # Update existing comment
+        try:
+            github.update_pr_comment(repo_root, existing_id, body)
+            result_success = SummaryCommentSuccess(
+                success=True,
+                action="updated",
+                comment_id=existing_id,
+            )
+            click.echo(json.dumps(asdict(result_success), indent=2))
+        except RuntimeError as e:
+            result = SummaryCommentError(
+                success=False,
+                error_type="update_failed",
+                message=str(e),
+            )
+            click.echo(json.dumps(asdict(result), indent=2))
+    else:
+        # Create new comment
+        try:
+            comment_id = github.create_pr_comment(repo_root, pr_number, body)
+            result_success = SummaryCommentSuccess(
+                success=True,
+                action="created",
+                comment_id=comment_id,
+            )
+            click.echo(json.dumps(asdict(result_success), indent=2))
+        except RuntimeError as e:
+            result = SummaryCommentError(
+                success=False,
+                error_type="create_failed",
+                message=str(e),
+            )
+            click.echo(json.dumps(asdict(result), indent=2))
+
+    raise SystemExit(0)

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

@@ -0,0 +1,143 @@
+"""Post an inline review comment on a specific line of a PR.
+
+This exec command creates a pull request review comment attached to a
+specific line of a file in the PR diff.
+
+Usage:
+    erk exec post-pr-inline-comment --pr-number 123 \\
+        --path "src/foo.py" --line 42 --body "Comment text"
+
+Output:
+    JSON with success status and comment ID
+
+Exit Codes:
+    0: Always (even on error, to support || true pattern)
+
+Examples:
+    $ erk exec post-pr-inline-comment --pr-number 123 \\
+        --path "src/foo.py" --line 42 --body "Use LBYL"
+    {"success": true, "comment_id": 12345}
+
+    $ erk exec post-pr-inline-comment --pr-number 123 \\
+        --path "bad.py" --line 999 --body "Comment"
+    {"success": false, "error_type": "github_api_failed", "message": "..."}
+"""
+
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+import click
+
+from erk_shared.context.helpers import require_github, require_repo_root
+from erk_shared.github.parsing import execute_gh_command
+
+
+@dataclass(frozen=True)
+class InlineCommentSuccess:
+    """Success response for inline comment posting."""
+
+    success: bool
+    comment_id: int
+
+
+@dataclass(frozen=True)
+class InlineCommentError:
+    """Error response for inline comment posting."""
+
+    success: bool
+    error_type: str
+    message: str
+
+
+def _get_pr_head_sha(repo_root: Path, pr_number: int) -> str:
+    """Get the head commit SHA for a PR.
+
+    Uses gh CLI REST API to fetch the PR head ref SHA.
+    Uses REST API instead of GraphQL (`gh pr view`) to avoid hitting
+    GraphQL rate limits. GraphQL and REST have separate quotas.
+
+    Args:
+        repo_root: Repository root directory
+        pr_number: PR number to query
+
+    Returns:
+        The head commit SHA as a string
+
+    Raises:
+        RuntimeError: If gh command fails
+    """
+    # GH-API-AUDIT: REST - GET pulls/{number}
+    cmd = [
+        "gh",
+        "api",
+        f"repos/{{owner}}/{{repo}}/pulls/{pr_number}",
+        "--jq",
+        ".head.sha",
+    ]
+    stdout = execute_gh_command(cmd, repo_root)
+    return stdout.strip()
+
+
+@click.command(name="post-pr-inline-comment")
+@click.option("--pr-number", required=True, type=int, help="PR number to comment on")
+@click.option("--path", required=True, help="File path relative to repo root")
+@click.option("--line", required=True, type=int, help="Line number in the diff")
+@click.option("--body", required=True, help="Comment body text")
+@click.pass_context
+def post_pr_inline_comment(
+    ctx: click.Context,
+    pr_number: int,
+    path: str,
+    line: int,
+    body: str,
+) -> None:
+    """Post an inline review comment on a PR.
+
+    Creates a pull request review comment attached to a specific line
+    of a file in the PR diff. Automatically fetches the PR head commit SHA.
+
+    PR_NUMBER: The PR to comment on
+    PATH: File path relative to repository root
+    LINE: Line number in the diff to attach comment to
+    BODY: Comment text (markdown supported)
+    """
+    repo_root = require_repo_root(ctx)
+    github = require_github(ctx)
+
+    # Get the PR head commit SHA
+    try:
+        commit_sha = _get_pr_head_sha(repo_root, pr_number)
+    except RuntimeError as e:
+        result = InlineCommentError(
+            success=False,
+            error_type="pr-not-found",
+            message=f"Could not get PR head commit: {e}",
+        )
+        click.echo(json.dumps(asdict(result), indent=2))
+        raise SystemExit(0) from None
+
+    # Create the inline comment
+    try:
+        comment_id = github.create_pr_review_comment(
+            repo_root,
+            pr_number,
+            body,
+            commit_sha,
+            path,
+            line,
+        )
+        result_success = InlineCommentSuccess(
+            success=True,
+            comment_id=comment_id,
+        )
+        click.echo(json.dumps(asdict(result_success), indent=2))
+    except RuntimeError as e:
+        result = InlineCommentError(
+            success=False,
+            error_type="github-api-failed",
+            message=str(e),
+        )
+        click.echo(json.dumps(asdict(result), indent=2))
+
+    raise SystemExit(0)

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

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""Post a "workflow started" comment to a GitHub issue with YAML metadata block.
+
+This command posts a structured comment to a GitHub issue indicating that a
+GitHub Actions workflow has started. The comment includes a YAML metadata block
+that can be parsed programmatically.
+
+This replaces ~40 lines of bash heredoc template assembly in GitHub Actions workflows.
+
+Usage:
+    erk exec post-workflow-started-comment \\
+        --issue-number 123 \\
+        --branch-name my-feature-branch \\
+        --pr-number 456 \\
+        --run-id 12345678 \\
+        --run-url https://github.com/owner/repo/actions/runs/12345678 \\
+        --repository owner/repo
+
+Output:
+    JSON object with success status
+
+Exit Codes:
+    0: Success (comment posted)
+    1: Error (GitHub API failed)
+
+Examples:
+    $ erk exec post-workflow-started-comment \\
+        --issue-number 123 \\
+        --branch-name feat-auth \\
+        --pr-number 456 \\
+        --run-id 99999 \\
+        --run-url https://github.com/acme/app/actions/runs/99999 \\
+        --repository acme/app
+    {
+      "success": true,
+      "issue_number": 123
+    }
+"""
+
+import json
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
+
+import click
+
+from erk_shared.context.helpers import require_issues as require_github_issues
+from erk_shared.context.helpers import require_repo_root
+
+
+@dataclass(frozen=True)
+class PostSuccess:
+    """Success result when comment is posted."""
+
+    success: bool
+    issue_number: int
+
+
+@dataclass(frozen=True)
+class PostError:
+    """Error result when comment posting fails."""
+
+    success: bool
+    error: str
+    message: str
+
+
+def _build_workflow_started_comment(
+    issue_number: int,
+    branch_name: str,
+    pr_number: int,
+    run_id: str,
+    run_url: str,
+    repository: str,
+) -> str:
+    """Build the workflow started comment body.
+
+    Args:
+        issue_number: GitHub issue number
+        branch_name: Git branch name
+        pr_number: Pull request number
+        run_id: GitHub Actions workflow run ID
+        run_url: Full URL to the workflow run
+        repository: Repository in owner/repo format
+
+    Returns:
+        Formatted markdown comment body
+    """
+    started_at = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    return f"""⚙️ GitHub Action Started
+
+<details>
+<summary>📋 Metadata</summary>
+
+<!-- erk:metadata-block:workflow-started -->
+```yaml
+schema: workflow-started
+status: started
+started_at: {started_at}
+workflow_run_id: "{run_id}"
+workflow_run_url: {run_url}
+branch_name: {branch_name}
+issue_number: {issue_number}
+```
+<!-- /erk:metadata-block:workflow-started -->
+
+</details>
+
+---
+
+Setup completed successfully.
+
+**Branch:** `{branch_name}`
+**PR:** [#{pr_number}](https://github.com/{repository}/pull/{pr_number})
+**Status:** Ready for implementation
+
+[View workflow run]({run_url})
+"""
+
+
+@click.command(name="post-workflow-started-comment")
+@click.option("--issue-number", type=int, required=True, help="GitHub issue number")
+@click.option("--branch-name", type=str, required=True, help="Git branch name")
+@click.option("--pr-number", type=int, required=True, help="Pull request number")
+@click.option("--run-id", type=str, required=True, help="GitHub Actions workflow run ID")
+@click.option("--run-url", type=str, required=True, help="Full URL to workflow run")
+@click.option("--repository", type=str, required=True, help="Repository in owner/repo format")
+@click.pass_context
+def post_workflow_started_comment(
+    ctx: click.Context,
+    issue_number: int,
+    branch_name: str,
+    pr_number: int,
+    run_id: str,
+    run_url: str,
+    repository: str,
+) -> None:
+    """Post a workflow started comment to a GitHub issue.
+
+    Posts a structured comment with YAML metadata block indicating that a
+    GitHub Actions workflow has started processing the issue.
+    """
+    github = require_github_issues(ctx)
+    repo_root = require_repo_root(ctx)
+
+    # Build comment body
+    comment_body = _build_workflow_started_comment(
+        issue_number=issue_number,
+        branch_name=branch_name,
+        pr_number=pr_number,
+        run_id=run_id,
+        run_url=run_url,
+        repository=repository,
+    )
+
+    # Post comment
+    try:
+        github.add_comment(repo_root, issue_number, comment_body)
+        result = PostSuccess(success=True, issue_number=issue_number)
+        click.echo(json.dumps(asdict(result), indent=2))
+    except RuntimeError as e:
+        result = PostError(
+            success=False,
+            error="github-api-failed",
+            message=str(e),
+        )
+        click.echo(json.dumps(asdict(result), indent=2))
+        raise SystemExit(1) from e