erk 0.4.5__py3-none-any.whl

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

@@ -0,0 +1,163 @@
+"""Marker file operations for inter-process communication.
+
+Usage:
+    erk exec marker create --session-id SESSION_ID <name>
+    erk exec marker exists --session-id SESSION_ID <name>
+    erk exec marker delete --session-id SESSION_ID <name>
+
+Marker files are stored in `.erk/scratch/sessions/<session-id>/` and are used for
+inter-process communication between hooks and commands. Session ID can be provided
+via `--session-id` flag or `$CLAUDE_CODE_SESSION_ID` environment variable.
+
+The `--session-id` flag takes precedence over the environment variable.
+
+Exit codes:
+    create: 0 = created, 1 = error (missing session ID)
+    exists: 0 = exists, 1 = does not exist
+    delete: 0 = deleted (or didn't exist), 1 = error (missing session ID)
+"""
+
+import json
+import os
+
+import click
+
+from erk_shared.context.helpers import require_repo_root
+from erk_shared.scratch.scratch import get_scratch_dir
+
+MARKER_EXTENSION = ".marker"
+
+
+def _resolve_session_id(session_id: str | None) -> str | None:
+    """Resolve session ID from explicit argument or environment variable.
+
+    Priority:
+    1. Explicit session_id argument (if provided)
+    2. CLAUDE_CODE_SESSION_ID environment variable
+    3. None (if neither available)
+    """
+    if session_id is not None:
+        return session_id
+    return os.environ.get("CLAUDE_CODE_SESSION_ID")
+
+
+def _output_json(success: bool, message: str) -> None:
+    """Output JSON response."""
+    click.echo(json.dumps({"success": success, "message": message}))
+
+
+@click.group(name="marker")
+def marker() -> None:
+    """Manage marker files for inter-process communication."""
+
+
+@marker.command(name="create")
+@click.argument("name")
+@click.option(
+    "--session-id",
+    default=None,
+    help="Session ID for marker storage (default: $CLAUDE_CODE_SESSION_ID)",
+)
+@click.option(
+    "--associated-objective",
+    type=int,
+    default=None,
+    help="Associated objective issue number (stored in marker file)",
+)
+@click.pass_context
+def marker_create(
+    ctx: click.Context, name: str, session_id: str | None, associated_objective: int | None
+) -> None:
+    """Create a marker file.
+
+    NAME is the marker name (e.g., 'incremental-plan').
+    The '.marker' extension is added automatically.
+
+    If --associated-objective is provided, the issue number is stored
+    in the marker file content. Otherwise, an empty file is created.
+    """
+    resolved_session_id = _resolve_session_id(session_id)
+    if resolved_session_id is None:
+        msg = (
+            "Missing session ID: provide --session-id or set "
+            "CLAUDE_CODE_SESSION_ID environment variable"
+        )
+        _output_json(False, msg)
+        raise SystemExit(1) from None
+
+    repo_root = require_repo_root(ctx)
+    scratch_dir = get_scratch_dir(resolved_session_id, repo_root=repo_root)
+    marker_file = scratch_dir / f"{name}{MARKER_EXTENSION}"
+    if associated_objective is not None:
+        marker_file.write_text(str(associated_objective), encoding="utf-8")
+    else:
+        marker_file.touch()
+    _output_json(True, f"Created marker: {name}")
+
+
+@marker.command(name="exists")
+@click.argument("name")
+@click.option(
+    "--session-id",
+    default=None,
+    help="Session ID for marker storage (default: $CLAUDE_CODE_SESSION_ID)",
+)
+@click.pass_context
+def marker_exists(ctx: click.Context, name: str, session_id: str | None) -> None:
+    """Check if a marker file exists.
+
+    NAME is the marker name (e.g., 'incremental-plan').
+    Exit code 0 if exists, 1 if not.
+    """
+    resolved_session_id = _resolve_session_id(session_id)
+    if resolved_session_id is None:
+        msg = (
+            "Missing session ID: provide --session-id or set "
+            "CLAUDE_CODE_SESSION_ID environment variable"
+        )
+        _output_json(False, msg)
+        raise SystemExit(1) from None
+
+    repo_root = require_repo_root(ctx)
+    scratch_dir = get_scratch_dir(resolved_session_id, repo_root=repo_root)
+    marker_file = scratch_dir / f"{name}{MARKER_EXTENSION}"
+
+    if marker_file.exists():
+        _output_json(True, f"Marker exists: {name}")
+    else:
+        _output_json(False, f"Marker does not exist: {name}")
+        raise SystemExit(1) from None
+
+
+@marker.command(name="delete")
+@click.argument("name")
+@click.option(
+    "--session-id",
+    default=None,
+    help="Session ID for marker storage (default: $CLAUDE_CODE_SESSION_ID)",
+)
+@click.pass_context
+def marker_delete(ctx: click.Context, name: str, session_id: str | None) -> None:
+    """Delete a marker file.
+
+    NAME is the marker name (e.g., 'incremental-plan').
+    Succeeds even if marker doesn't exist (idempotent).
+    """
+    resolved_session_id = _resolve_session_id(session_id)
+    if resolved_session_id is None:
+        msg = (
+            "Missing session ID: provide --session-id or set "
+            "CLAUDE_CODE_SESSION_ID environment variable"
+        )
+        _output_json(False, msg)
+        raise SystemExit(1) from None
+
+    repo_root = require_repo_root(ctx)
+    scratch_dir = get_scratch_dir(resolved_session_id, repo_root=repo_root)
+    marker_file = scratch_dir / f"{name}{MARKER_EXTENSION}"
+
+    if marker_file.exists():
+        marker_file.unlink()
+        _output_json(True, f"Deleted marker: {name}")
+    else:
+        _output_json(True, f"Marker already deleted: {name}")

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

@@ -0,0 +1,109 @@
+"""Save plan as objective GitHub issue.
+
+Usage:
+    erk exec objective-save-to-issue [OPTIONS]
+
+This command extracts a plan and creates a GitHub issue with:
+- erk-plan + erk-objective labels (like extraction has erk-plan + erk-extraction)
+- No title suffix
+- Plan content directly in body (no metadata block)
+- No commands section
+
+Options:
+    --session-id ID: Session ID for scoped plan lookup
+    --format: json (default) or display
+
+Exit Codes:
+    0: Success - objective issue created
+    1: Error - no plan found, gh failure, etc.
+"""
+
+import json
+
+import click
+
+from erk_shared.context.helpers import (
+    require_claude_installation,
+    require_cwd,
+    require_repo_root,
+)
+from erk_shared.context.helpers import (
+    require_issues as require_github_issues,
+)
+from erk_shared.github.plan_issues import create_objective_issue
+
+
+@click.command(name="objective-save-to-issue")
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["json", "display"]),
+    default="json",
+    help="Output format: json (default) or display (formatted text)",
+)
+@click.option(
+    "--session-id",
+    default=None,
+    help="Session ID for scoped plan lookup",
+)
+@click.pass_context
+def objective_save_to_issue(ctx: click.Context, output_format: str, session_id: str | None) -> None:
+    """Save plan as objective GitHub issue.
+
+    Creates a GitHub issue with erk-plan + erk-objective labels and plan content in body.
+    """
+    # Get dependencies from context
+    github = require_github_issues(ctx)
+    repo_root = require_repo_root(ctx)
+    cwd = require_cwd(ctx)
+    claude_installation = require_claude_installation(ctx)
+
+    # Get plan content
+    plan = claude_installation.get_latest_plan(cwd, session_id=session_id)
+
+    if not plan:
+        if output_format == "display":
+            click.echo("Error: No plan found in ~/.claude/plans/", err=True)
+            click.echo("\nTo fix:", err=True)
+            click.echo("1. Create a plan (enter Plan mode if needed)", err=True)
+            click.echo("2. Exit Plan mode using ExitPlanMode tool", err=True)
+            click.echo("3. Run this command again", err=True)
+        else:
+            click.echo(json.dumps({"success": False, "error": "No plan found in ~/.claude/plans/"}))
+        raise SystemExit(1)
+
+    # Create objective issue
+    result = create_objective_issue(
+        github_issues=github,
+        repo_root=repo_root,
+        plan_content=plan,
+        title=None,
+        extra_labels=None,
+    )
+
+    if not result.success:
+        if output_format == "display":
+            click.echo(f"Error: {result.error}", err=True)
+        else:
+            click.echo(json.dumps({"success": False, "error": result.error}))
+        raise SystemExit(1)
+
+    # Guard for type narrowing
+    if result.issue_number is None:
+        raise RuntimeError("Unexpected: issue_number is None after success")
+
+    if output_format == "display":
+        click.echo(f"Objective saved to GitHub issue #{result.issue_number}")
+        click.echo(f"Title: {result.title}")
+        click.echo(f"URL: {result.issue_url}")
+    else:
+        click.echo(
+            json.dumps(
+                {
+                    "success": True,
+                    "issue_number": result.issue_number,
+                    "issue_url": result.issue_url,
+                    "title": result.title,
+                }
+            )
+        )

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

@@ -0,0 +1,269 @@
+"""Extract plan from ~/.claude/plans/ and create GitHub issue in one operation.
+
+Usage:
+    erk exec plan-save-to-issue [OPTIONS]
+
+This command combines plan extraction and issue creation:
+1. Extract plan from specified file, session-scoped lookup, or latest from ~/.claude/plans/
+2. Create GitHub issue with plan content
+
+Options:
+    --plan-file PATH: Use specific plan file (highest priority)
+    --session-id ID: Use session-scoped lookup to find plan by slug
+    (neither): Fall back to most recent plan by modification time
+
+Output:
+    --format json (default): {"success": true, "issue_number": N, ...}
+    --format display: Formatted text ready for display
+
+Exit Codes:
+    0: Success - plan extracted and issue created
+    1: Error - no plan found, gh failure, etc.
+"""
+
+import json
+from pathlib import Path
+
+import click
+
+from erk_shared.context.helpers import (
+    get_repo_identifier,
+    require_claude_installation,
+    require_cwd,
+    require_local_config,
+    require_repo_root,
+)
+from erk_shared.context.helpers import (
+    require_issues as require_github_issues,
+)
+from erk_shared.github.plan_issues import create_plan_issue
+from erk_shared.output.next_steps import format_next_steps_plain
+from erk_shared.scratch.plan_snapshots import snapshot_plan_for_session
+from erk_shared.scratch.scratch import get_scratch_dir
+
+
+def _create_plan_saved_marker(session_id: str, repo_root: Path) -> None:
+    """Create marker file to indicate plan was saved to GitHub.
+
+    Args:
+        session_id: The session ID for the scratch directory.
+        repo_root: The repository root path.
+    """
+    marker_dir = get_scratch_dir(session_id, repo_root=repo_root)
+    marker_file = marker_dir / "exit-plan-mode-hook.plan-saved.marker"
+    marker_file.write_text(
+        "Created by: exit-plan-mode-hook (via /erk:plan-save)\n"
+        "Trigger: Plan was successfully saved to GitHub\n"
+        "Effect: Next ExitPlanMode call will be BLOCKED (remain in plan mode, session complete)\n"
+        "Lifecycle: Deleted after being read by next hook invocation\n",
+        encoding="utf-8",
+    )
+
+
+@click.command(name="plan-save-to-issue")
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["json", "display"]),
+    default="json",
+    help="Output format: json (default) or display (formatted text)",
+)
+@click.option(
+    "--plan-file",
+    type=click.Path(exists=True, path_type=Path),
+    default=None,
+    help="Path to specific plan file (highest priority)",
+)
+@click.option(
+    "--session-id",
+    default=None,
+    help="Session ID for scoped plan lookup (uses slug from session logs)",
+)
+@click.option(
+    "--objective-issue",
+    type=int,
+    default=None,
+    help="Link plan to parent objective issue number",
+)
+@click.pass_context
+def plan_save_to_issue(
+    ctx: click.Context,
+    output_format: str,
+    plan_file: Path | None,
+    session_id: str | None,
+    objective_issue: int | None,
+) -> None:
+    """Extract plan from ~/.claude/plans/ and create GitHub issue.
+
+    Combines plan extraction and issue creation in a single operation.
+    """
+    # Get dependencies from context
+    github = require_github_issues(ctx)
+    repo_root = require_repo_root(ctx)
+    cwd = require_cwd(ctx)
+    claude_installation = require_claude_installation(ctx)
+
+    # session_id comes from --session-id CLI option (or None if not provided)
+    effective_session_id = session_id
+
+    # Step 1: Extract plan (priority: plan_file > session_id > most recent)
+    if plan_file:
+        plan = plan_file.read_text(encoding="utf-8")
+    else:
+        plan = claude_installation.get_latest_plan(cwd, session_id=effective_session_id)
+
+    if not plan:
+        if output_format == "display":
+            click.echo("Error: No plan found in ~/.claude/plans/", err=True)
+            click.echo("\nTo fix:", err=True)
+            click.echo("1. Create a plan (enter Plan mode if needed)", err=True)
+            click.echo("2. Exit Plan mode using ExitPlanMode tool", err=True)
+            click.echo("3. Run this command again", err=True)
+        else:
+            click.echo(json.dumps({"success": False, "error": "No plan found in ~/.claude/plans/"}))
+        raise SystemExit(1)
+
+    # 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
+    config = require_local_config(ctx)
+    if config.plans_repo is not None:
+        source_repo = get_repo_identifier(ctx)
+
+    # Use consolidated create_plan_issue for the entire workflow
+    result = create_plan_issue(
+        github_issues=github,
+        repo_root=repo_root,
+        plan_content=plan,
+        title=None,
+        plan_type=None,
+        extra_labels=None,
+        title_suffix=None,
+        source_plan_issues=None,
+        extraction_session_ids=None,
+        source_repo=source_repo,
+        objective_issue=objective_issue,
+    )
+
+    if not result.success:
+        if result.issue_number is not None:
+            # Partial success - issue created but comment failed
+            if output_format == "display":
+                click.echo(f"Warning: {result.error}", err=True)
+                click.echo(f"Please manually add plan content to: {result.issue_url}", err=True)
+            else:
+                click.echo(
+                    json.dumps(
+                        {
+                            "success": False,
+                            "error": result.error,
+                            "issue_number": result.issue_number,
+                            "issue_url": result.issue_url,
+                        }
+                    )
+                )
+        else:
+            if output_format == "display":
+                click.echo(f"Error: {result.error}", err=True)
+            else:
+                click.echo(json.dumps({"success": False, "error": result.error}))
+        raise SystemExit(1)
+
+    # DISABLED: Session context embedding is temporarily disabled while rethinking extraction plans
+    # To re-enable, uncomment the following block and restore imports:
+    #   from erk_shared.context.helpers import require_git
+    #   from erk_shared.extraction.session_context import collect_session_context
+    #   from erk_shared.github.metadata import render_session_content_blocks
+    #
+    #   git = require_git(ctx)
+    #   session_result = collect_session_context(
+    #       git=git,
+    #       cwd=cwd,
+    #       session_store=session_store,
+    #       current_session_id=effective_session_id,
+    #       min_size=1024,
+    #       limit=20,
+    #   )
+    #
+    #   if session_result is not None and result.issue_number is not None:
+    #       # Render and post as comments
+    #       session_label = session_result.branch_context.current_branch or "planning-session"
+    #       content_blocks = render_session_content_blocks(
+    #           content=session_result.combined_xml,
+    #           session_label=session_label,
+    #           extraction_hints=["Planning session context for downstream analysis"],
+    #       )
+    #
+    #       # Post each block as a comment (failures are non-blocking)
+    #       for block in content_blocks:
+    #           try:
+    #               github.add_comment(repo_root, result.issue_number, block)
+    #               session_context_chunks += 1
+    #           except RuntimeError:
+    #               # Session context is supplementary - don't fail the command
+    #               pass
+    #
+    #       session_ids = session_result.session_ids
+
+    # Output JSON still includes these for backwards compatibility
+    session_context_chunks = 0
+    session_ids: list[str] = []
+
+    # Step 9: Create marker file to indicate plan was saved
+    snapshot_result = None
+    if effective_session_id:
+        _create_plan_saved_marker(effective_session_id, repo_root)
+
+        # Step 9.1: Snapshot the plan file to session-scoped storage
+        # Determine plan file path
+        if plan_file:
+            snapshot_path = plan_file
+        else:
+            # Look up slug from session to find plan file
+            snapshot_path = claude_installation.find_plan_for_session(cwd, effective_session_id)
+
+        if snapshot_path is not None and snapshot_path.exists():
+            snapshot_result = snapshot_plan_for_session(
+                session_id=effective_session_id,
+                plan_file_path=snapshot_path,
+                project_cwd=cwd,
+                claude_installation=claude_installation,
+                repo_root=repo_root,
+            )
+            # NOTE: Plan file deletion moved to impl_signal.py on 'started' event
+            # This allows the user to modify and re-save the plan before implementing
+
+    # Step 10: Output success
+    # Detect enrichment status for informational output
+    is_enriched = "## Enrichment Details" in plan
+
+    # At this point result.success is True, so issue_number must be set
+    # Guard for type narrowing
+    if result.issue_number is None:
+        raise RuntimeError("Unexpected: issue_number is None after successful create_plan_issue")
+
+    if output_format == "display":
+        click.echo(f"Plan saved to GitHub issue #{result.issue_number}")
+        click.echo(f"Title: {result.title}")
+        click.echo(f"URL: {result.issue_url}")
+        click.echo(f"Enrichment: {'Yes' if is_enriched else 'No'}")
+        if session_context_chunks > 0:
+            click.echo(f"Session context: {session_context_chunks} chunks")
+        if snapshot_result is not None:
+            click.echo(f"Archived: {snapshot_result.snapshot_dir}")
+        click.echo()
+        click.echo(format_next_steps_plain(result.issue_number))
+    else:
+        output_data = {
+            "success": True,
+            "issue_number": result.issue_number,
+            "issue_url": result.issue_url,
+            "title": result.title,
+            "enriched": is_enriched,
+            "session_context_chunks": session_context_chunks,
+            "session_ids": session_ids,
+        }
+        if snapshot_result is not None:
+            output_data["archived_to"] = str(snapshot_result.snapshot_dir)
+        click.echo(json.dumps(output_data))

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

@@ -0,0 +1,147 @@
+"""Update an existing GitHub issue's plan comment with new content.
+
+Usage:
+    erk exec plan-update-issue --issue-number N [OPTIONS]
+
+This command updates the plan content comment on an existing GitHub issue:
+1. Find plan file (from session scratch, --plan-path, or ~/.claude/plans/)
+2. Get the first comment ID from the issue (where plan body lives)
+3. Update that comment with new plan content
+
+Options:
+    --issue-number N: GitHub issue number to update (required)
+    --session-id ID: Session ID to find plan file in scratch storage
+    --plan-path PATH: Direct path to plan file (overrides session lookup)
+
+Output:
+    --format json (default): {"success": true, ...}
+    --format display: Formatted text
+
+Exit Codes:
+    0: Success - plan comment updated
+    1: Error - issue not found, no plan found, no comments, etc.
+"""
+
+import json
+from pathlib import Path
+
+import click
+
+from erk_shared.context.helpers import (
+    require_claude_installation,
+    require_cwd,
+    require_repo_root,
+)
+from erk_shared.context.helpers import (
+    require_issues as require_github_issues,
+)
+from erk_shared.github.metadata.plan_header import format_plan_content_comment
+
+
+@click.command(name="plan-update-issue")
+@click.option(
+    "--issue-number",
+    type=int,
+    required=True,
+    help="GitHub issue number to update",
+)
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["json", "display"]),
+    default="json",
+    help="Output format: json (default) or display (formatted text)",
+)
+@click.option(
+    "--plan-path",
+    type=click.Path(exists=True, path_type=Path),
+    help="Direct path to plan file (overrides session lookup)",
+)
+@click.option(
+    "--session-id",
+    help="Session ID to find plan file in scratch storage",
+)
+@click.pass_context
+def plan_update_issue(
+    ctx: click.Context,
+    issue_number: int,
+    output_format: str,
+    plan_path: Path | None,
+    session_id: str | None,
+) -> None:
+    """Update an existing GitHub issue's plan comment with new content."""
+    # Get dependencies from context
+    github = require_github_issues(ctx)
+    repo_root = require_repo_root(ctx)
+    cwd = require_cwd(ctx)
+    claude_installation = require_claude_installation(ctx)
+
+    # Step 1: Find plan content (priority: plan_path > session > latest)
+    if plan_path is not None:
+        plan_content = plan_path.read_text(encoding="utf-8")
+    else:
+        plan_content = claude_installation.get_latest_plan(cwd, session_id=session_id)
+
+    if not plan_content:
+        error_msg = "No plan found in ~/.claude/plans/"
+        if output_format == "display":
+            click.echo(f"Error: {error_msg}", err=True)
+        else:
+            click.echo(json.dumps({"success": False, "error": error_msg}))
+        raise SystemExit(1)
+
+    # Step 2: Get existing issue to verify it exists
+    try:
+        issue = github.get_issue(repo_root, issue_number)
+    except RuntimeError as e:
+        error_msg = f"Failed to get issue #{issue_number}: {e}"
+        if output_format == "display":
+            click.echo(f"Error: {error_msg}", err=True)
+        else:
+            click.echo(json.dumps({"success": False, "error": error_msg}))
+        raise SystemExit(1) from e
+
+    # Step 3: Get first comment ID (where plan body lives in Schema v2)
+    comments = github.get_issue_comments_with_urls(repo_root, issue_number)
+    if not comments:
+        error_msg = f"Issue #{issue_number} has no comments - cannot update plan content"
+        if output_format == "display":
+            click.echo(f"Error: {error_msg}", err=True)
+        else:
+            click.echo(json.dumps({"success": False, "error": error_msg}))
+        raise SystemExit(1)
+
+    first_comment = comments[0]
+    comment_id = first_comment.id
+
+    # Step 4: Format plan content and update comment
+    formatted_plan = format_plan_content_comment(plan_content.strip())
+
+    try:
+        github.update_comment(repo_root, comment_id, formatted_plan)
+    except RuntimeError as e:
+        error_msg = f"Failed to update comment: {e}"
+        if output_format == "display":
+            click.echo(f"Error: {error_msg}", err=True)
+        else:
+            click.echo(json.dumps({"success": False, "error": error_msg}))
+        raise SystemExit(1) from e
+
+    # Step 5: Output success
+    if output_format == "display":
+        click.echo(f"Plan updated on issue #{issue_number}")
+        click.echo(f"Title: {issue.title}")
+        click.echo(f"URL: {issue.url}")
+        click.echo(f"Comment: {first_comment.url}")
+    else:
+        click.echo(
+            json.dumps(
+                {
+                    "success": True,
+                    "issue_number": issue_number,
+                    "issue_url": issue.url,
+                    "comment_id": comment_id,
+                    "comment_url": first_comment.url,
+                }
+            )
+        )