erk 0.4.5__py3-none-any.whl

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

@@ -0,0 +1,159 @@
+"""Set up .impl/ folder from GitHub issue in current worktree.
+
+This exec command fetches a plan from a GitHub issue, creates a feature branch,
+checks it out, and creates the .impl/ folder structure for implementation.
+
+Usage:
+    erk exec setup-impl-from-issue <issue-number> [--session-id <id>]
+
+Output:
+    Structured JSON output with success status and folder details
+
+Exit Codes:
+    0: Success (.impl/ folder created, branch checked out)
+    1: Error (issue not found, plan fetch failed, git operations failed)
+
+Examples:
+    $ erk exec setup-impl-from-issue 1028
+    {"success": true, "impl_path": "/path/to/.impl", "issue_number": 1028, "branch": "P1028-..."}
+"""
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+
+import click
+
+from erk_shared.context.helpers import require_cwd, require_git, require_repo_root
+from erk_shared.gateway.time.real import RealTime
+from erk_shared.git.abc import Git
+from erk_shared.github.issues import RealGitHubIssues
+from erk_shared.impl_folder import create_impl_folder, save_issue_reference
+from erk_shared.naming import generate_issue_branch_name
+from erk_shared.plan_store.github import GitHubPlanStore
+
+
+def _get_current_branch(git: Git, cwd: Path) -> str:
+    """Get current branch via gateway, raising if detached HEAD."""
+    branch = git.get_current_branch(cwd)
+    if branch is None:
+        msg = "Cannot set up implementation from detached HEAD state"
+        raise click.ClickException(msg)
+    return branch
+
+
+def _is_trunk_branch(branch: str) -> bool:
+    """Check if branch is a trunk branch (main/master)."""
+    return branch in ("main", "master")
+
+
+@click.command(name="setup-impl-from-issue")
+@click.argument("issue_number", type=int)
+@click.option(
+    "--session-id",
+    default=None,
+    help="Claude session ID for marker creation",
+)
+@click.option(
+    "--no-impl",
+    is_flag=True,
+    help="Skip .impl/ folder creation (for local execution without file overhead)",
+)
+@click.pass_context
+def setup_impl_from_issue(
+    ctx: click.Context,
+    issue_number: int,
+    session_id: str | None,
+    no_impl: bool,
+) -> None:
+    """Set up .impl/ folder from GitHub issue in current worktree.
+
+    Fetches plan content from GitHub issue, creates/checks out a feature branch,
+    and creates .impl/ folder structure with plan.md, progress.md, and issue.json.
+
+    ISSUE_NUMBER: GitHub issue number containing the plan
+
+    The command:
+    1. Fetches the plan from the GitHub issue
+    2. Creates a feature branch from current branch (stacked) or trunk
+    3. Checks out the new branch in the current worktree
+    4. Creates .impl/ folder with plan content
+    5. Saves issue reference for PR linking
+    """
+    cwd = require_cwd(ctx)
+    repo_root = require_repo_root(ctx)
+    git = require_git(ctx)
+
+    # Direct instantiation of required dependencies
+    time = RealTime()
+    github_issues = RealGitHubIssues(target_repo=None)
+    plan_store = GitHubPlanStore(github_issues, time)
+
+    # Step 1: Fetch plan from GitHub
+    try:
+        plan = plan_store.get_plan(repo_root, str(issue_number))
+    except RuntimeError as e:
+        error_output = {
+            "success": False,
+            "error": "plan_not_found",
+            "message": f"Could not fetch plan for issue #{issue_number}: {e}. "
+            f"Ensure issue has erk-plan label and plan content.",
+        }
+        click.echo(json.dumps(error_output), err=True)
+        raise SystemExit(1) from e
+
+    # Step 2: Determine base branch and create feature branch
+    current_branch = _get_current_branch(git, cwd)
+
+    # Generate branch name from issue
+    timestamp = datetime.now(UTC)
+    branch_name = generate_issue_branch_name(issue_number, plan.title, timestamp)
+
+    # Check if branch already exists
+    local_branches = git.list_local_branches(repo_root)
+
+    if branch_name in local_branches:
+        # Branch exists - just check it out
+        click.echo(f"Branch '{branch_name}' already exists, checking out...", err=True)
+        git.checkout_branch(cwd, branch_name)
+    else:
+        # Determine base branch: stack on feature branch, or use trunk
+        if _is_trunk_branch(current_branch):
+            base_branch = current_branch
+        else:
+            # Stack on current feature branch
+            base_branch = current_branch
+
+        # Create and checkout branch
+        git.create_branch(repo_root, branch_name, base_branch)
+        git.checkout_branch(cwd, branch_name)
+        click.echo(f"Created branch '{branch_name}' from '{base_branch}'", err=True)
+
+    # Step 3: Create .impl/ folder with plan content (unless --no-impl)
+    impl_path_str: str | None = None
+
+    if not no_impl:
+        impl_path = cwd / ".impl"
+        impl_path_str = str(impl_path)
+
+        # Use overwrite=True since we may be re-running after a failed attempt
+        create_impl_folder(
+            worktree_path=cwd,
+            plan_content=plan.body,
+            overwrite=True,
+        )
+
+        # Step 4: Save issue reference for PR linking
+        save_issue_reference(impl_path, issue_number, plan.url, plan.title)
+
+    # Output structured success result
+    output: dict[str, str | int | bool | None] = {
+        "success": True,
+        "impl_path": impl_path_str,
+        "issue_number": issue_number,
+        "issue_url": plan.url,
+        "branch": branch_name,
+        "plan_title": plan.title,
+        "no_impl": no_impl,
+    }
+    click.echo(json.dumps(output))

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

@@ -0,0 +1,102 @@
+"""Get the last objective issue for the current slot.
+
+This exec command looks up the current worktree's slot and returns
+the last_objective_issue from pool.json.
+
+Usage:
+    erk exec slot-objective
+
+Output:
+    JSON with objective_issue (null if not found or not in a slot)
+
+Exit Codes:
+    0: Success (even if no objective found)
+
+Examples:
+    $ erk exec slot-objective
+    {"objective_issue": 123, "slot_name": "erk-managed-wt-01"}
+
+    $ erk exec slot-objective  # Not in a slot worktree
+    {"objective_issue": null, "slot_name": null}
+"""
+
+import json
+from pathlib import Path
+
+import click
+
+from erk.core.worktree_pool import load_pool_state
+from erk_shared.context.helpers import require_cwd
+from erk_shared.context.types import NoRepoSentinel
+
+
+def _null_result() -> None:
+    """Output null result and return."""
+    click.echo(json.dumps({"objective_issue": None, "slot_name": None}))
+
+
+@click.command(name="slot-objective")
+@click.pass_context
+def slot_objective(ctx: click.Context) -> None:
+    """Get the last objective issue for the current slot.
+
+    Looks up the current worktree in pool.json and returns
+    the slot's last_objective_issue if set.
+    """
+    if ctx.obj is None:
+        _null_result()
+        return
+
+    cwd = require_cwd(ctx)
+    repo = ctx.obj.repo
+
+    # Check if we're in a repo
+    if isinstance(repo, NoRepoSentinel):
+        _null_result()
+        return
+
+    # Load pool state
+    state = load_pool_state(repo.pool_json_path)
+    if state is None:
+        _null_result()
+        return
+
+    # Find assignment for current worktree
+    cwd_resolved = cwd.resolve()
+    slot_name: str | None = None
+
+    for assignment in state.assignments:
+        if not assignment.worktree_path.exists():
+            continue
+        if assignment.worktree_path.resolve() == cwd_resolved:
+            slot_name = assignment.slot_name
+            break
+
+    if slot_name is None:
+        # Check if cwd is within an assignment's worktree
+        for assignment in state.assignments:
+            if _is_path_within(cwd_resolved, assignment.worktree_path):
+                slot_name = assignment.slot_name
+                break
+
+    if slot_name is None:
+        _null_result()
+        return
+
+    # Find slot info to get last_objective_issue
+    objective_issue: int | None = None
+    for slot in state.slots:
+        if slot.name == slot_name:
+            objective_issue = slot.last_objective_issue
+            break
+
+    result = {"objective_issue": objective_issue, "slot_name": slot_name}
+    click.echo(json.dumps(result))
+
+
+def _is_path_within(child: Path, parent: Path) -> bool:
+    """Check if child path is within parent path."""
+    if not parent.exists():
+        return False
+    parent_resolved = parent.resolve()
+    return child == parent_resolved or parent_resolved in child.parents

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

@@ -0,0 +1,20 @@
+#!/usr/bin/env python3
+"""Tripwires Reminder Hook."""
+
+import click
+
+from erk.hooks.decorators import HookContext, hook_command
+
+
+@hook_command()
+def tripwires_reminder_hook(ctx: click.Context, *, hook_ctx: HookContext) -> None:
+    """Output tripwires reminder for UserPromptSubmit hook."""
+    # Scope check: only run in erk-managed projects
+    if not hook_ctx.is_erk_project:
+        return
+
+    click.echo("🚧 Ensure docs/learned/tripwires.md is loaded and follow its directives.")
+
+
+if __name__ == "__main__":
+    tripwires_reminder_hook()

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

@@ -0,0 +1,116 @@
+"""Update dispatch info in GitHub issue plan-header metadata.
+
+Usage:
+    erk exec update-dispatch-info <issue-number> <run-id> <node-id> <dispatched-at>
+
+Output:
+    JSON with success status and issue_number
+
+Exit Codes:
+    0: Success
+    1: Error (issue not found, invalid inputs, no plan-header block)
+"""
+
+import json
+from dataclasses import asdict, dataclass
+
+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.plan_header import update_plan_header_dispatch
+
+
+@dataclass(frozen=True)
+class UpdateSuccess:
+    """Success response for dispatch info update."""
+
+    success: bool
+    issue_number: int
+    run_id: str
+    node_id: str
+
+
+@dataclass(frozen=True)
+class UpdateError:
+    """Error response for dispatch info update."""
+
+    success: bool
+    error: str
+    message: str
+
+
+@click.command(name="update-dispatch-info")
+@click.argument("issue_number", type=int)
+@click.argument("run_id")
+@click.argument("node_id")
+@click.argument("dispatched_at")
+@click.pass_context
+def update_dispatch_info(
+    ctx: click.Context,
+    issue_number: int,
+    run_id: str,
+    node_id: str,
+    dispatched_at: str,
+) -> None:
+    """Update dispatch info in GitHub issue plan-header metadata.
+
+    Fetches the issue, updates the plan-header block with last_dispatched_run_id,
+    last_dispatched_node_id, and last_dispatched_at, and posts the updated body
+    back to GitHub.
+
+    If issue uses old format (no plan-header block), exits with error code 1.
+    """
+    # Get dependencies from context
+    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 = UpdateError(
+            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
+
+    # Update dispatch info
+    try:
+        updated_body = update_plan_header_dispatch(
+            issue_body=issue.body,
+            run_id=run_id,
+            node_id=node_id,
+            dispatched_at=dispatched_at,
+        )
+    except ValueError as e:
+        # plan-header block not found (old format issue)
+        result = UpdateError(
+            success=False,
+            error="no-plan-header-block",
+            message=str(e),
+        )
+        click.echo(json.dumps(asdict(result)), err=True)
+        raise SystemExit(1) from None
+
+    # Update issue body
+    try:
+        github_issues.update_issue_body(repo_root, issue_number, updated_body)
+    except RuntimeError as e:
+        result = UpdateError(
+            success=False,
+            error="github-api-failed",
+            message=f"Failed to update issue body: {e}",
+        )
+        click.echo(json.dumps(asdict(result)), err=True)
+        raise SystemExit(1) from None
+
+    result_success = UpdateSuccess(
+        success=True,
+        issue_number=issue_number,
+        run_id=run_id,
+        node_id=node_id,
+    )
+    click.echo(json.dumps(asdict(result_success)))

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

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""UserPromptSubmit hook for erk.
+
+Consolidates multiple hooks into a single script:
+1. Session ID injection + file persistence
+2. Coding standards reminders
+3. Tripwires reminder
+
+Exit codes:
+    0: All checks pass, stdout goes to Claude's context
+
+This command is invoked via:
+    ERK_HOOK_ID=user-prompt-hook erk exec user-prompt-hook
+"""
+
+from pathlib import Path
+
+import click
+
+from erk.hooks.decorators import HookContext, hook_command
+
+# ============================================================================
+# Pure Functions for Output Building
+# ============================================================================
+
+
+def build_session_context(session_id: str | None) -> str:
+    """Build the session ID context string.
+
+    Pure function - string building only.
+    """
+    if session_id is None:
+        return ""
+    return f"session: {session_id}"
+
+
+def build_coding_standards_reminder() -> str:
+    """Return coding standards context.
+
+    Pure function - returns static string.
+    """
+    return """No direct Bash for: pytest/ty/ruff/prettier/make/gt
+Use Task(subagent_type='devrun') instead.
+dignified-python: CRITICAL RULES (examples - full skill has more):
+NO try/except for control flow (use LBYL - check conditions first)
+NO default parameter values (no `foo: bool = False`)
+NO mutable/non-frozen dataclasses (always `@dataclass(frozen=True)`)
+MANDATORY: Load and READ the full dignified-python skill documents.
+   These are examples only. You MUST strictly abide by ALL rules in the skill.
+AFTER completing Python changes: Verify sufficient test coverage.
+Behavior changes ALWAYS need tests."""
+
+
+def build_tripwires_reminder() -> str:
+    """Return tripwires context.
+
+    Pure function - returns static string.
+    """
+    return "Ensure docs/learned/tripwires.md is loaded and follow its directives."
+
+
+# ============================================================================
+# I/O Helper Functions
+# ============================================================================
+
+
+def _persist_session_id(repo_root: Path, session_id: str | None) -> None:
+    """Write session ID to file.
+
+    Args:
+        repo_root: Path to the git repository root.
+        session_id: The current session ID, or None if not available.
+    """
+    if session_id is None:
+        return
+
+    session_file = repo_root / ".erk" / "scratch" / "current-session-id"
+    session_file.parent.mkdir(parents=True, exist_ok=True)
+    session_file.write_text(session_id, encoding="utf-8")
+
+
+# ============================================================================
+# Main Hook Entry Point
+# ============================================================================
+
+
+@hook_command(name="user-prompt-hook")
+def user_prompt_hook(ctx: click.Context, *, hook_ctx: HookContext) -> None:
+    """UserPromptSubmit hook for session persistence and coding reminders.
+
+    This hook runs on every user prompt submission in erk-managed projects.
+
+    Exit codes:
+        0: Success - context emitted to stdout
+    """
+    # Scope check: only run in erk-managed projects
+    if not hook_ctx.is_erk_project:
+        return
+
+    # Persist session ID
+    _persist_session_id(hook_ctx.repo_root, hook_ctx.session_id)
+
+    # Build and emit context
+    context_parts = [
+        build_session_context(hook_ctx.session_id),
+        build_coding_standards_reminder(),
+        build_tripwires_reminder(),
+    ]
+    click.echo("\n".join(p for p in context_parts if p))
+
+
+if __name__ == "__main__":
+    user_prompt_hook()

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

@@ -0,0 +1,98 @@
+"""Validate plan content structure and quality.
+
+This exec command validates that plan content meets minimum requirements
+for structure and length. It accepts plan content via stdin.
+
+Usage:
+    echo "$plan" | erk exec validate-plan-content
+
+Output:
+    JSON with validation status and details
+
+Exit Codes:
+    0: Success (always - check JSON for validation result)
+
+Examples:
+    $ echo "# My Plan\n\n- Step 1\n- Step 2" | erk exec validate-plan-content
+    {"valid": true, "error": null, "details": {"length": 29, "has_headers": true,
+    "has_lists": true}}
+
+    $ echo "too short" | erk exec validate-plan-content
+    {"valid": false, "error": "Plan too short (9 characters, minimum 100)",
+    "details": {"length": 9, "has_headers": false, "has_lists": false}}
+"""
+
+import json
+import sys
+
+import click
+
+
+def _validate_plan_content(content: str) -> tuple[bool, str | None, dict[str, bool | int]]:
+    """Validate plan content meets minimum requirements.
+
+    Args:
+        content: Plan content as string
+
+    Returns:
+        Tuple of (valid, error_message, details_dict)
+        - valid: True if plan passes all checks
+        - error_message: None if valid, descriptive error if invalid
+        - details_dict: Dict with length, has_headers, has_lists
+    """
+    # Strip whitespace for validation
+    content_stripped = content.strip()
+    length = len(content_stripped)
+
+    # Check for structural elements
+    has_headers = any(line.startswith("#") for line in content_stripped.split("\n"))
+    has_lists = any(
+        line.strip().startswith(("-", "*", "+"))
+        or (line.strip() and line.strip()[0].isdigit() and ". " in line)
+        for line in content_stripped.split("\n")
+    )
+
+    details = {
+        "length": length,
+        "has_headers": has_headers,
+        "has_lists": has_lists,
+    }
+
+    # Validation checks
+    if not content_stripped:
+        return False, "Plan is empty or contains only whitespace", details
+
+    if length < 100:
+        return False, f"Plan too short ({length} characters, minimum 100)", details
+
+    if not has_headers and not has_lists:
+        return (
+            False,
+            "Plan lacks structure (no headers or lists found)",
+            details,
+        )
+
+    return True, None, details
+
+
+@click.command(name="validate-plan-content")
+def validate_plan_content() -> None:
+    """Validate plan content from stdin.
+
+    Reads plan content from stdin and validates:
+    - Minimum 100 characters
+    - Contains structural elements (headers OR lists)
+    - Not empty/whitespace only
+
+    Outputs JSON with validation result and details.
+    """
+    content = sys.stdin.read()
+    valid, error, details = _validate_plan_content(content)
+
+    result = {
+        "valid": valid,
+        "error": error,
+        "details": details,
+    }
+
+    click.echo(json.dumps(result))

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

@@ -0,0 +1,34 @@
+"""Wrap a plan in a collapsible GitHub metadata block."""
+
+import sys
+
+import click
+
+
+@click.command(name="wrap-plan-in-metadata-block")
+def wrap_plan_in_metadata_block() -> None:
+    """Return plan content for issue body.
+
+    Reads plan content from stdin and returns it as-is (stripped).
+    Formatting and workflow instructions will be added via a separate comment.
+
+    Usage:
+        echo "$plan" | erk exec wrap-plan-in-metadata-block
+
+    Exit Codes:
+        0: Success
+        1: Error (empty input)
+    """
+    # Read plan content from stdin
+    plan_content = sys.stdin.read()
+
+    # Validate input is not empty
+    if not plan_content or not plan_content.strip():
+        click.echo("Error: Empty plan content received", err=True)
+        raise SystemExit(1)
+
+    # Return plan content as-is (metadata wrapping delegated to separate comments)
+    result = plan_content.strip()
+
+    # Output the result
+    click.echo(result)