erk 0.4.5__py3-none-any.whl

erk/cli/commands/plan/check_cmd.py

@@ -0,0 +1,174 @@
+"""Command to validate plan format against Schema v2 requirements."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import click
+
+from erk.cli.core import discover_repo_context
+from erk.cli.github_parsing import parse_issue_identifier
+from erk.core.context import ErkContext
+from erk.core.repo_discovery import ensure_erk_metadata_dir
+from erk_shared.github.issues.abc import GitHubIssues
+from erk_shared.github.metadata.core import find_metadata_block
+from erk_shared.github.metadata.plan_header import extract_plan_from_comment
+from erk_shared.github.metadata.schemas import PlanHeaderSchema
+from erk_shared.output.output import user_output
+
+
+@dataclass(frozen=True)
+class PlanValidationSuccess:
+    """Validation completed (may have passed or failed checks).
+
+    Attributes:
+        passed: True if all validation checks passed
+        checks: List of (passed, description) tuples for each check
+        failed_count: Number of failed checks
+    """
+
+    passed: bool
+    checks: list[tuple[bool, str]]
+    failed_count: int
+
+
+@dataclass(frozen=True)
+class PlanValidationError:
+    """Could not complete validation (API error, network issue, etc.)."""
+
+    error: str
+
+
+PlanValidationResult = PlanValidationSuccess | PlanValidationError
+
+
+def validate_plan_format(
+    github_issues: GitHubIssues,
+    repo_root: Path,
+    issue_number: int,
+) -> PlanValidationResult:
+    """Validate plan format programmatically.
+
+    Validates that a plan stored in a GitHub issue conforms to Schema v2:
+    - Issue body has plan-header metadata block with required fields
+    - First comment has plan-body metadata block with extractable content
+
+    This function is designed to be called programmatically (e.g., from land_cmd).
+    It does not produce output or raise SystemExit. It never raises exceptions -
+    API failures are returned as PlanValidationError.
+
+    Args:
+        github_issues: GitHub issues interface
+        repo_root: Repository root path
+        issue_number: GitHub issue number to validate
+
+    Returns:
+        PlanValidationSuccess if validation completed (may have passed or failed checks)
+        PlanValidationError if unable to complete validation (API error, etc.)
+    """
+    # Track validation results
+    checks: list[tuple[bool, str]] = []
+
+    # Fetch issue from GitHub
+    try:
+        issue = github_issues.get_issue(repo_root, issue_number)
+    except RuntimeError as e:
+        return PlanValidationError(error=str(e))
+
+    issue_body = issue.body if issue.body else ""
+
+    # Check 1: plan-header metadata block exists
+    plan_header_block = find_metadata_block(issue_body, "plan-header")
+    if plan_header_block is None:
+        checks.append((False, "plan-header metadata block present"))
+    else:
+        checks.append((True, "plan-header metadata block present"))
+
+        # Check 2: plan-header has required fields and is valid
+        try:
+            schema = PlanHeaderSchema()
+            schema.validate(plan_header_block.data)
+            checks.append((True, "plan-header has required fields"))
+        except ValueError as e:
+            # Extract first error message for cleaner output
+            error_msg = str(e).split("\n")[0]
+            checks.append((False, f"plan-header validation failed: {error_msg}"))
+
+    # Check 3: First comment exists
+    try:
+        comments = github_issues.get_issue_comments(repo_root, issue_number)
+    except RuntimeError as e:
+        return PlanValidationError(error=str(e))
+
+    if not comments:
+        checks.append((False, "First comment exists"))
+    else:
+        checks.append((True, "First comment exists"))
+
+        # Check 4: plan-body content extractable
+        first_comment = comments[0]
+        plan_content = extract_plan_from_comment(first_comment)
+        if plan_content is None:
+            checks.append((False, "plan-body content extractable"))
+        else:
+            checks.append((True, "plan-body content extractable"))
+
+    # Determine overall result
+    failed_count = sum(1 for passed, _ in checks if not passed)
+
+    return PlanValidationSuccess(
+        passed=failed_count == 0,
+        checks=checks,
+        failed_count=failed_count,
+    )
+
+
+@click.command("check")
+@click.argument("identifier", type=str)
+@click.pass_obj
+def check_plan(ctx: ErkContext, identifier: str) -> None:
+    """Validate a plan's format against Schema v2 requirements.
+
+    Validates that a plan stored in a GitHub issue conforms to Schema v2:
+    - Issue body has plan-header metadata block with required fields
+    - First comment has plan-body metadata block with extractable content
+
+    Args:
+        identifier: Plan identifier (e.g., "42" or GitHub URL)
+    """
+    repo = discover_repo_context(ctx, ctx.cwd)
+    ensure_erk_metadata_dir(repo)  # Ensure erk metadata directories exist
+    repo_root = repo.root  # Use git repository root for GitHub operations
+
+    # Parse identifier - raises click.ClickException if invalid
+    issue_number = parse_issue_identifier(identifier)
+
+    user_output(f"Validating plan #{issue_number}...")
+    user_output("")
+
+    # Run validation
+    result = validate_plan_format(ctx.issues, repo_root, issue_number)
+
+    if isinstance(result, PlanValidationError):
+        user_output(click.style("Error: ", fg="red") + f"Failed to validate plan: {result.error}")
+        raise SystemExit(1)
+
+    # result is now PlanValidationSuccess
+    # Output results
+    for passed, description in result.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
+    if result.passed:
+        user_output(click.style("Plan validation passed", fg="green"))
+        raise SystemExit(0)
+    else:
+        check_word = "checks" if result.failed_count > 1 else "check"
+        user_output(
+            click.style(
+                f"Plan validation failed ({result.failed_count} {check_word} failed)", fg="red"
+            )
+        )
+        raise SystemExit(1)

erk/cli/commands/plan/close_cmd.py

@@ -0,0 +1,69 @@
+"""Command to close a plan."""
+
+from pathlib import Path
+
+import click
+
+from erk.cli.core import discover_repo_context
+from erk.cli.github_parsing import parse_issue_identifier
+from erk.core.context import ErkContext
+from erk.core.repo_discovery import ensure_erk_metadata_dir
+from erk_shared.output.output import user_output
+
+
+def _close_linked_prs(
+    ctx: ErkContext,
+    repo_root: Path,
+    issue_number: int,
+) -> list[int]:
+    """Close all OPEN PRs linked to an issue.
+
+    Returns list of PR numbers that were closed.
+    """
+    linked_prs = ctx.issues.get_prs_referencing_issue(repo_root, issue_number)
+
+    closed_prs: list[int] = []
+    for pr in linked_prs:
+        # Close all OPEN PRs (both drafts and non-drafts per user requirement)
+        if pr.state == "OPEN":
+            ctx.github.close_pr(repo_root, pr.number)
+            closed_prs.append(pr.number)
+
+    return closed_prs
+
+
+@click.command("close")
+@click.argument("identifier", type=str)
+@click.pass_obj
+def close_plan(ctx: ErkContext, identifier: str) -> None:
+    """Close a plan by issue number or GitHub URL.
+
+    Closes all OPEN PRs linked to the issue in addition to closing the issue itself.
+
+    Args:
+        identifier: Plan identifier (e.g., "42" or GitHub URL)
+    """
+    repo = discover_repo_context(ctx, ctx.cwd)
+    ensure_erk_metadata_dir(repo)  # Ensure erk metadata directories exist
+    repo_root = repo.root  # Use git repository root for GitHub operations
+
+    # Parse issue number - errors if invalid
+    number = parse_issue_identifier(identifier)
+
+    # Fetch plan - errors if not found
+    try:
+        _plan = ctx.plan_store.get_plan(repo_root, str(number))
+    except RuntimeError as e:
+        raise click.ClickException(str(e)) from e
+
+    # Close linked PRs before closing the plan
+    closed_prs = _close_linked_prs(ctx, repo_root, number)
+
+    # Close the plan (issue)
+    ctx.plan_store.close_plan(repo_root, identifier)
+
+    # Output
+    user_output(f"Closed plan #{number}")
+    if closed_prs:
+        pr_list = ", ".join(f"#{pr}" for pr in closed_prs)
+        user_output(f"Closed {len(closed_prs)} linked PR(s): {pr_list}")

erk/cli/commands/plan/create_cmd.py

@@ -0,0 +1,120 @@
+"""Command to create a plan issue from markdown content."""
+
+import sys
+from pathlib import Path
+
+import click
+
+from erk.cli.core import discover_repo_context
+from erk.cli.ensure import Ensure
+from erk.core.context import ErkContext
+from erk.core.repo_discovery import ensure_erk_metadata_dir
+from erk_shared.github.plan_issues import create_plan_issue
+from erk_shared.output.output import user_output
+
+
+@click.command("create")
+@click.option(
+    "--file",
+    "-f",
+    type=click.Path(exists=True, path_type=Path),
+    help="Plan file to read",
+)
+@click.option("--title", "-t", type=str, help="Issue title (default: extract from H1)")
+@click.option("--label", "-l", multiple=True, help="Additional labels")
+@click.pass_obj
+def create_plan(
+    ctx: ErkContext,
+    file: Path | None,
+    title: str | None,
+    label: tuple[str, ...],
+) -> None:
+    """Create a plan issue from markdown content.
+
+    Supports two input modes:
+    - File: --file PATH (recommended for automation)
+    - Stdin: pipe content via shell (for Unix composability)
+
+    Examples:
+        erk create --file plan.md
+        cat plan.md | erk create
+        erk create --file plan.md --title "Custom Title"
+        erk create --file plan.md --label bug --label urgent
+    """
+    repo = discover_repo_context(ctx, ctx.cwd)
+    ensure_erk_metadata_dir(repo)
+    repo_root = repo.root
+
+    # LBYL: Check input sources - exactly one required
+    # Priority: --file flag takes precedence over stdin
+    content = ""  # Initialize to ensure type safety
+    if file is not None:
+        # Use file input
+        Ensure.path_exists(ctx, file, f"File not found: {file}")
+        try:
+            content = file.read_text(encoding="utf-8")
+        except OSError as e:
+            user_output(click.style("Error: ", fg="red") + f"Failed to read file: {e}")
+            raise SystemExit(1) from e
+    elif not sys.stdin.isatty():
+        # Use stdin input (piped data)
+        try:
+            content = sys.stdin.read()
+        except OSError as e:
+            user_output(click.style("Error: ", fg="red") + f"Failed to read stdin: {e}")
+            raise SystemExit(1) from e
+    else:
+        # No input provided
+        Ensure.invariant(False, "No input provided. Use --file or pipe content to stdin.")
+
+    # Validate content is not empty
+    Ensure.not_empty(content.strip(), "Plan content is empty. Provide a non-empty plan.")
+
+    # Convert extra labels tuple to list
+    extra_labels = list(label) if label else None
+
+    # Determine source_repo for cross-repo plans
+    # When plans_repo is configured, plans are stored in a separate repo
+    # and source_repo records where implementation will happen
+    source_repo: str | None = None
+    plans_repo = ctx.local_config.plans_repo if ctx.local_config else None
+    if plans_repo is not None and repo.github is not None:
+        source_repo = f"{repo.github.owner}/{repo.github.repo}"
+
+    # Use consolidated create_plan_issue for the entire workflow
+    result = create_plan_issue(
+        github_issues=ctx.issues,
+        repo_root=repo_root,
+        plan_content=content,
+        title=title,
+        plan_type=None,
+        extra_labels=extra_labels,
+        title_suffix=None,
+        source_plan_issues=None,
+        extraction_session_ids=None,
+        source_repo=source_repo,
+        objective_issue=None,
+    )
+
+    if not result.success:
+        if result.issue_number is not None:
+            # Partial success - issue created but comment failed
+            user_output(
+                click.style("Warning: ", fg="yellow")
+                + f"Issue created but failed to add plan comment: {result.error}"
+            )
+            user_output(f"Issue #{result.issue_number} created but incomplete.")
+            user_output(f"URL: {result.issue_url}")
+        else:
+            user_output(click.style("Error: ", fg="red") + str(result.error))
+        raise SystemExit(1)
+
+    # Display success message with next steps
+    user_output(f"Created plan #{result.issue_number}")
+    user_output("")
+    user_output(f"Issue: {result.issue_url}")
+    user_output("")
+    user_output("Next steps:")
+    user_output(f"  View:       erk get {result.issue_number}")
+    user_output(f"  Implement:  erk implement {result.issue_number}")
+    user_output(f"  Submit:     erk submit {result.issue_number}")

erk/cli/commands/plan/docs/__init__.py

@@ -0,0 +1,18 @@
+"""Docs subcommand group for plan documentation extraction tracking."""
+
+import click
+
+from erk.cli.commands.plan.docs.extract_cmd import extract_docs
+from erk.cli.commands.plan.docs.unextract_cmd import unextract_docs
+from erk.cli.commands.plan.docs.unextracted_cmd import list_unextracted
+
+
+@click.group("docs")
+def docs_group() -> None:
+    """Track documentation extraction from plan sessions."""
+    pass
+
+
+docs_group.add_command(list_unextracted, name="unextracted")
+docs_group.add_command(extract_docs, name="extract")
+docs_group.add_command(unextract_docs, name="unextract")

erk/cli/commands/plan/docs/extract_cmd.py

@@ -0,0 +1,53 @@
+"""Command to mark a plan as having been analyzed for documentation."""
+
+import click
+
+from erk.cli.constants import (
+    DOCS_EXTRACTED_LABEL,
+    DOCS_EXTRACTED_LABEL_COLOR,
+    DOCS_EXTRACTED_LABEL_DESCRIPTION,
+)
+from erk.cli.core import discover_repo_context
+from erk.cli.github_parsing import parse_issue_identifier
+from erk.core.context import ErkContext
+from erk.core.repo_discovery import ensure_erk_metadata_dir
+from erk_shared.output.output import user_output
+
+
+@click.command("extract")
+@click.argument("identifier", type=str)
+@click.pass_obj
+def extract_docs(ctx: ErkContext, identifier: str) -> None:
+    """Mark a plan as having been analyzed for documentation.
+
+    Adds the docs-extracted label to the specified issue, indicating that
+    its session logs have been reviewed for documentation improvements.
+
+    Args:
+        identifier: Plan identifier (e.g., "42" or GitHub URL)
+    """
+    repo = discover_repo_context(ctx, ctx.cwd)
+    ensure_erk_metadata_dir(repo)
+    repo_root = repo.root
+
+    # Parse issue number
+    issue_number = parse_issue_identifier(identifier)
+
+    # Ensure label exists in repo (create if needed)
+    try:
+        ctx.issues.ensure_label_exists(
+            repo_root,
+            DOCS_EXTRACTED_LABEL,
+            DOCS_EXTRACTED_LABEL_DESCRIPTION,
+            DOCS_EXTRACTED_LABEL_COLOR,
+        )
+    except RuntimeError as e:
+        raise click.ClickException(f"Failed to ensure label exists: {e}") from e
+
+    # Add label to issue (idempotent)
+    try:
+        ctx.issues.ensure_label_on_issue(repo_root, issue_number, DOCS_EXTRACTED_LABEL)
+    except RuntimeError as e:
+        raise click.ClickException(f"Failed to add label to issue #{issue_number}: {e}") from e
+
+    user_output(f"Marked plan #{issue_number} as docs-extracted")

erk/cli/commands/plan/docs/unextract_cmd.py

@@ -0,0 +1,38 @@
+"""Command to remove the docs-extracted label from a plan (for re-analysis)."""
+
+import click
+
+from erk.cli.constants import DOCS_EXTRACTED_LABEL
+from erk.cli.core import discover_repo_context
+from erk.cli.github_parsing import parse_issue_identifier
+from erk.core.context import ErkContext
+from erk.core.repo_discovery import ensure_erk_metadata_dir
+from erk_shared.output.output import user_output
+
+
+@click.command("unextract")
+@click.argument("identifier", type=str)
+@click.pass_obj
+def unextract_docs(ctx: ErkContext, identifier: str) -> None:
+    """Remove the docs-extracted label from a plan (for re-analysis).
+
+    Removes the docs-extracted label from the specified issue, allowing it
+    to appear again in the unextracted list for future documentation review.
+
+    Args:
+        identifier: Plan identifier (e.g., "42" or GitHub URL)
+    """
+    repo = discover_repo_context(ctx, ctx.cwd)
+    ensure_erk_metadata_dir(repo)
+    repo_root = repo.root
+
+    # Parse issue number
+    issue_number = parse_issue_identifier(identifier)
+
+    # Remove label from issue
+    try:
+        ctx.issues.remove_label_from_issue(repo_root, issue_number, DOCS_EXTRACTED_LABEL)
+    except RuntimeError as e:
+        raise click.ClickException(f"Failed to remove label from issue #{issue_number}: {e}") from e
+
+    user_output(f"Removed docs-extracted label from plan #{issue_number}")

erk/cli/commands/plan/docs/unextracted_cmd.py

@@ -0,0 +1,72 @@
+"""Command to list closed plans that haven't been analyzed for documentation."""
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from erk.cli.constants import DOCS_EXTRACTED_LABEL, ERK_PLAN_LABEL
+from erk.cli.core import discover_repo_context
+from erk.core.context import ErkContext
+from erk.core.display_utils import format_relative_time
+from erk.core.repo_discovery import ensure_erk_metadata_dir
+from erk_shared.output.output import user_output
+
+
+@click.command("unextracted")
+@click.pass_obj
+def list_unextracted(ctx: ErkContext) -> None:
+    """List closed plans that haven't been analyzed for documentation.
+
+    Shows all closed erk-plan issues that don't have the docs-extracted label.
+    Use 'erk plan docs extract <number>' to mark a plan as extracted.
+    """
+    repo = discover_repo_context(ctx, ctx.cwd)
+    ensure_erk_metadata_dir(repo)
+    repo_root = repo.root
+
+    # Query all closed issues with erk-plan label
+    try:
+        issues = ctx.issues.list_issues(
+            repo_root,
+            labels=[ERK_PLAN_LABEL],
+            state="closed",
+        )
+    except RuntimeError as e:
+        raise click.ClickException(f"Failed to list issues: {e}") from e
+
+    # Filter out issues that already have docs-extracted label
+    unextracted = [issue for issue in issues if DOCS_EXTRACTED_LABEL not in issue.labels]
+
+    if not unextracted:
+        user_output("No unextracted plans found. All closed plans have been analyzed.")
+        return
+
+    # Build table
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("plan", style="cyan", no_wrap=True)
+    table.add_column("title", no_wrap=True)
+    table.add_column("closed", no_wrap=True)
+
+    for issue in unextracted:
+        # Format issue number with link
+        id_text = f"#{issue.number}"
+        if issue.url:
+            issue_id = f"[link={issue.url}][cyan]{id_text}[/cyan][/link]"
+        else:
+            issue_id = f"[cyan]{id_text}[/cyan]"
+
+        # Truncate title
+        title = issue.title
+        if len(title) > 50:
+            title = title[:47] + "..."
+
+        # Format closed time
+        closed_at = format_relative_time(issue.updated_at.isoformat()) if issue.updated_at else "-"
+
+        table.add_row(issue_id, title, closed_at)
+
+    user_output(f"\nFound {len(unextracted)} unextracted plan(s):\n")
+
+    console = Console(stderr=True, width=200, force_terminal=True)
+    console.print(table)
+    console.print()

erk/cli/commands/plan/extraction/__init__.py

@@ -0,0 +1,16 @@
+"""Extraction subcommand group for plan documentation extraction workflow."""
+
+import click
+
+from erk.cli.commands.plan.extraction.complete_cmd import complete_extraction
+from erk.cli.commands.plan.extraction.create_raw_cmd import create_raw
+
+
+@click.group("extraction")
+def extraction_group() -> None:
+    """Manage documentation extraction plans."""
+    pass
+
+
+extraction_group.add_command(complete_extraction, name="complete")
+extraction_group.add_command(create_raw, name="raw")

erk/cli/commands/plan/extraction/complete_cmd.py

@@ -0,0 +1,101 @@
+"""Command to complete an extraction plan and mark source plans as extracted."""
+
+import click
+
+from erk.cli.constants import (
+    DOCS_EXTRACTED_LABEL,
+    DOCS_EXTRACTED_LABEL_COLOR,
+    DOCS_EXTRACTED_LABEL_DESCRIPTION,
+)
+from erk.cli.core import discover_repo_context
+from erk.cli.github_parsing import parse_issue_identifier
+from erk.core.context import ErkContext
+from erk.core.repo_discovery import ensure_erk_metadata_dir
+from erk_shared.github.metadata.core import find_metadata_block
+from erk_shared.output.output import user_output
+
+
+@click.command("complete")
+@click.argument("identifier", type=str)
+@click.pass_obj
+def complete_extraction(ctx: ErkContext, identifier: str) -> None:
+    """Complete an extraction plan by marking source plans as docs-extracted.
+
+    Reads the extraction plan's metadata to find source_plan_issues,
+    then adds the docs-extracted label to each source plan.
+
+    This command is idempotent - safe to run multiple times.
+
+    Args:
+        identifier: Extraction plan identifier (e.g., "42" or GitHub URL)
+    """
+    repo = discover_repo_context(ctx, ctx.cwd)
+    ensure_erk_metadata_dir(repo)
+    repo_root = repo.root
+
+    # Parse extraction plan issue number
+    issue_number = parse_issue_identifier(identifier)
+
+    # Fetch the extraction plan issue to read its metadata
+    try:
+        issue_info = ctx.issues.get_issue(repo_root, issue_number)
+    except RuntimeError as e:
+        raise click.ClickException(f"Failed to fetch issue #{issue_number}: {e}") from e
+
+    # Extract plan-header metadata block
+    plan_header = find_metadata_block(issue_info.body, "plan-header")
+    if plan_header is None:
+        raise click.ClickException(
+            f"Issue #{issue_number} does not have a plan-header metadata block. "
+            "Is this an erk plan issue?"
+        )
+
+    # Check plan_type
+    plan_type = plan_header.data.get("plan_type")
+    if plan_type != "extraction":
+        raise click.ClickException(
+            f"Issue #{issue_number} is not an extraction plan (plan_type: {plan_type}). "
+            "This command only works on extraction plans."
+        )
+
+    # Get source_plan_issues
+    source_plan_issues = plan_header.data.get("source_plan_issues")
+    if not source_plan_issues:
+        raise click.ClickException(
+            f"Issue #{issue_number} has no source_plan_issues in its metadata. "
+            "Cannot determine which plans to mark as extracted."
+        )
+
+    # Ensure docs-extracted label exists
+    try:
+        ctx.issues.ensure_label_exists(
+            repo_root,
+            DOCS_EXTRACTED_LABEL,
+            DOCS_EXTRACTED_LABEL_DESCRIPTION,
+            DOCS_EXTRACTED_LABEL_COLOR,
+        )
+    except RuntimeError as e:
+        raise click.ClickException(f"Failed to ensure label exists: {e}") from e
+
+    # Mark each source plan as docs-extracted
+    marked_count = 0
+    for source_issue_number in source_plan_issues:
+        try:
+            ctx.issues.ensure_label_on_issue(repo_root, source_issue_number, DOCS_EXTRACTED_LABEL)
+            user_output(f"  Marked plan #{source_issue_number} as docs-extracted")
+            marked_count += 1
+        except RuntimeError as e:
+            # Log the error but continue with other issues
+            click.echo(f"  Warning: Failed to mark plan #{source_issue_number}: {e}", err=True)
+
+    # Summary
+    if marked_count == len(source_plan_issues):
+        user_output(
+            f"\nExtraction plan #{issue_number} completed: "
+            f"marked {marked_count} source plan(s) as docs-extracted"
+        )
+    else:
+        user_output(
+            f"\nExtraction plan #{issue_number} partially completed: "
+            f"marked {marked_count}/{len(source_plan_issues)} source plan(s) as docs-extracted"
+        )