erk 0.4.5__py3-none-any.whl

erk/cli/github_parsing.py

@@ -0,0 +1,96 @@
+"""CLI-level wrappers for GitHub URL parsing with error handling.
+
+This module provides CLI-friendly wrappers around the shared parsing functions
+in erk_shared.github.parsing. These wrappers handle user input (not just URLs)
+and raise SystemExit(1) with appropriate error messages for invalid input.
+
+Two-layer architecture:
+- erk_shared.github.parsing: Pure parsing functions, return None on failure (LBYL-friendly)
+- src/erk/cli/github_parsing.py: CLI wrappers that raise SystemExit(1)
+"""
+
+import click
+
+from erk_shared.github.parsing import (
+    parse_issue_number_from_url,
+    parse_pr_number_from_url,
+)
+from erk_shared.output.output import user_output
+
+
+def parse_issue_identifier(identifier: str) -> int:
+    """Parse issue number from plain number or GitHub issue URL.
+
+    This is a CLI-level function that handles user input.
+
+    Args:
+        identifier: Plain number ("42") or GitHub issue URL
+
+    Returns:
+        Issue number as int
+
+    Raises:
+        SystemExit: If identifier cannot be parsed
+
+    Examples:
+        >>> parse_issue_identifier("42")
+        42
+        >>> parse_issue_identifier("https://github.com/owner/repo/issues/123")
+        123
+    """
+    # Plain number (handles leading zeros like "0042" -> 42)
+    if identifier.isdigit():
+        return int(identifier)
+
+    # GitHub URL
+    issue_number = parse_issue_number_from_url(identifier)
+    if issue_number is not None:
+        return issue_number
+
+    user_output(
+        click.style("Error: ", fg="red")
+        + f"Invalid issue number or URL: {identifier}\n\n"
+        + "Expected formats:\n"
+        + "  • Plain number: 123\n"
+        + "  • GitHub URL: https://github.com/owner/repo/issues/456"
+    )
+    raise SystemExit(1)
+
+
+def parse_pr_identifier(identifier: str) -> int:
+    """Parse PR number from plain number or GitHub PR URL.
+
+    This is a CLI-level function that handles user input.
+
+    Args:
+        identifier: Plain number ("42") or GitHub PR URL
+
+    Returns:
+        PR number as int
+
+    Raises:
+        SystemExit: If identifier cannot be parsed
+
+    Examples:
+        >>> parse_pr_identifier("42")
+        42
+        >>> parse_pr_identifier("https://github.com/owner/repo/pull/123")
+        123
+    """
+    # Plain number (handles leading zeros like "0042" -> 42)
+    if identifier.isdigit():
+        return int(identifier)
+
+    # Try strict github.com /pull/ URL only
+    pr_number = parse_pr_number_from_url(identifier)
+    if pr_number is not None:
+        return pr_number
+
+    user_output(
+        click.style("Error: ", fg="red")
+        + f"Invalid PR number or URL: {identifier}\n\n"
+        + "Expected formats:\n"
+        + "  • Plain number: 123\n"
+        + "  • GitHub URL: https://github.com/owner/repo/pull/456"
+    )
+    raise SystemExit(1)

erk/cli/graphite.py

@@ -0,0 +1,81 @@
+"""Graphite integration for erk.
+
+Graphite (https://graphite.com) is a stacked git workflow tool that allows developers
+to manage dependent branches in linear stacks. This module provides utility functions
+for working with worktree stacks.
+
+For comprehensive gt mental model and command reference, see:
+.agent/GT_MENTAL_MODEL.md
+
+## What is Graphite?
+
+Graphite organizes branches into "stacks" - linear chains of dependent branches built
+on top of each other. For example:
+
+    main (trunk)
+      └─ feature/phase-1
+           └─ feature/phase-2
+                └─ feature/phase-3
+
+Each branch in the stack depends on its parent, making it easy to work on multiple
+related changes while keeping them in separate PRs.
+
+## Graphite Abstraction
+
+This module uses the Graphite abstraction to read Graphite cache data. Production
+code should use ctx.graphite_ops methods directly instead of importing functions from
+this module.
+
+See erk.core.graphite_ops for the abstraction interface.
+"""
+
+from pathlib import Path
+
+from erk.core.context import ErkContext
+from erk_shared.git.abc import WorktreeInfo
+
+
+def find_worktrees_containing_branch(
+    ctx: ErkContext,
+    repo_root: Path,
+    worktrees: list[WorktreeInfo],
+    target_branch: str,
+) -> list[WorktreeInfo]:
+    """Find all worktrees that have target_branch checked out (exact match only).
+
+    Args:
+        ctx: Erk context with git operations
+        repo_root: Path to the repository root
+        worktrees: List of all worktrees from list_worktrees()
+        target_branch: Branch name to search for
+
+    Returns:
+        List of WorktreeInfo objects where target_branch is checked out.
+        Empty list if no worktrees have the branch checked out.
+
+    Algorithm:
+        1. For each worktree:
+           a. Get the worktree's checked-out branch
+           b. Skip worktrees with detached HEAD (branch=None)
+           c. Check if worktree.branch == target_branch (exact string match)
+           d. If yes, add worktree to results
+        2. Return all matching worktrees
+
+    Example:
+        >>> worktrees = ctx.git_ops.list_worktrees(repo.root)
+        >>> matching = find_worktrees_containing_branch(ctx, repo.root, worktrees, "feature-2")
+        >>> print([wt.path for wt in matching])
+        [Path("/path/to/work/feature-work")]
+    """
+    matching_worktrees: list[WorktreeInfo] = []
+
+    for wt in worktrees:
+        # Skip worktrees with detached HEAD
+        if wt.branch is None:
+            continue
+
+        # Check if target_branch is exactly checked out in this worktree
+        if wt.branch == target_branch:
+            matching_worktrees.append(wt)
+
+    return matching_worktrees

erk/cli/graphite_command.py

@@ -0,0 +1,80 @@
+"""Custom Click command classes that require Graphite integration.
+
+This module provides declarative command classes that automatically:
+1. Check Graphite availability before command execution
+2. Are hidden from help output when Graphite is unavailable
+
+Usage:
+    @click.command("list", cls=GraphiteCommand)
+    def list_stack(ctx: ErkContext) -> None:
+        # No need for Ensure.graphite_available(ctx) - handled by GraphiteCommand
+        ...
+
+    @click.command("up", cls=GraphiteCommandWithHiddenOptions)
+    @script_option
+    def up_cmd(ctx: ErkContext, script: bool) -> None:
+        # Combines Graphite check with hidden options support
+        ...
+
+    @click.group("stack", cls=GraphiteGroup)
+    def stack_group() -> None:
+        # Entire group hidden when Graphite unavailable
+        ...
+"""
+
+from typing import Any
+
+import click
+
+from erk.cli.ensure import Ensure
+from erk.cli.help_formatter import CommandWithHiddenOptions
+
+
+class GraphiteCommand(click.Command):
+    """Command that requires Graphite integration.
+
+    Automatically checks Graphite availability before command execution.
+    When Graphite is unavailable, this command is hidden from help output
+    but can still be invoked directly (failing with a helpful error message).
+
+    Use this class for commands that depend on Graphite functionality
+    but don't need hidden options support.
+    """
+
+    def invoke(self, ctx: click.Context) -> Any:
+        """Invoke command after validating Graphite availability."""
+        if ctx.obj is not None:
+            Ensure.graphite_available(ctx.obj)
+        return super().invoke(ctx)
+
+
+class GraphiteCommandWithHiddenOptions(CommandWithHiddenOptions):
+    """GraphiteCommand + hidden options support.
+
+    Combines the Graphite availability check from GraphiteCommand
+    with the hidden options formatting from CommandWithHiddenOptions.
+
+    Use this class for commands that:
+    1. Require Graphite functionality
+    2. Have hidden options (like --script)
+    """
+
+    def invoke(self, ctx: click.Context) -> Any:
+        """Invoke command after validating Graphite availability."""
+        if ctx.obj is not None:
+            Ensure.graphite_available(ctx.obj)
+        return super().invoke(ctx)
+
+
+class GraphiteGroup(click.Group):
+    """Group that requires Graphite integration.
+
+    When used with cls=GraphiteGroup, the entire command group is hidden
+    from help output when Graphite is unavailable. Commands within the
+    group can still be invoked directly and will fail with helpful error
+    messages via their own GraphiteCommand classes.
+
+    The hiding logic is implemented in ErkCommandGroup.format_commands().
+    """
+
+    pass

erk/cli/help_formatter.py

@@ -0,0 +1,345 @@
+"""Custom Click help formatter for organized command display."""
+
+import shutil
+from collections.abc import Callable
+from typing import Any, TypeVar, cast
+
+import click
+
+from erk.cli.alias import get_aliases
+from erk_shared.gateway.erk_installation.real import RealErkInstallation
+from erk_shared.gateway.graphite.disabled import GraphiteDisabled
+
+F = TypeVar("F", bound=Callable[..., object])
+
+# Type names for Graphite-requiring commands (checked by string to avoid circular imports)
+_GRAPHITE_COMMAND_TYPES = frozenset(
+    {
+        "GraphiteCommand",
+        "GraphiteCommandWithHiddenOptions",
+        "GraphiteGroup",
+    }
+)
+
+
+def _requires_graphite(cmd: click.Command) -> bool:
+    """Check if a command requires Graphite integration.
+
+    Uses class name matching to avoid circular imports with graphite_command.py.
+    """
+    return type(cmd).__name__ in _GRAPHITE_COMMAND_TYPES
+
+
+def _get_show_hidden_from_context(ctx: click.Context) -> bool:
+    """Check if hidden items should be shown based on config.
+
+    Checks ctx.obj.global_config if available (tests),
+    otherwise loads config from disk (direct CLI invocation).
+    """
+    if ctx.obj is not None:
+        config = getattr(ctx.obj, "global_config", None)
+        if config is not None:
+            return bool(getattr(config, "show_hidden_commands", False))
+    # Fallback to loading from disk
+    installation = RealErkInstallation()
+    if installation.config_exists():
+        return installation.load_config().show_hidden_commands
+    return False
+
+
+def _set_param_hidden(param: click.Parameter, hidden: bool) -> None:
+    """Set hidden attribute on Click parameter.
+
+    Click's Option class has a 'hidden' attribute, but Parameter (the base class)
+    doesn't expose it in type stubs. We use cast(Any, ...) since we've already
+    verified via getattr that this parameter has the 'hidden' attribute.
+    """
+    cast(Any, param).hidden = hidden
+
+
+def _set_ctx_show_hidden(ctx: click.Context, value: bool) -> None:
+    """Set show_hidden attribute on Click context.
+
+    Click's Context allows dynamic attributes at runtime (documented API behavior).
+    We use cast(Any, ...) to bypass type stubs that don't include dynamic attrs.
+    """
+    cast(Any, ctx).show_hidden = value
+
+
+def _is_graphite_available(ctx: click.Context) -> bool:
+    """Check if Graphite is available for command visibility.
+
+    Checks ctx.obj.graphite if available (tests or after callback),
+    otherwise loads config from disk and checks gt binary (help before callback).
+    """
+    if ctx.obj is not None:
+        return not isinstance(ctx.obj.graphite, GraphiteDisabled)
+    # Fallback to loading from disk (for help before callback runs)
+    installation = RealErkInstallation()
+    if installation.config_exists():
+        config = installation.load_config()
+        if config.use_graphite:
+            # Config says use Graphite - check if gt is installed
+            return shutil.which("gt") is not None
+    return False
+
+
+class CommandWithHiddenOptions(click.Command):
+    """Command that respects show_hidden_commands config for hidden options.
+
+    Use this class for any command with hidden options (like --script).
+    Hidden options are shown in a separate "Hidden Options" section when
+    show_hidden_commands is enabled in config.
+    """
+
+    def format_options(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        """Format options, showing hidden ones if config allows."""
+        show_hidden = _get_show_hidden_from_context(ctx)
+
+        opts = []
+        hidden_opts = []
+        for param in self.get_params(ctx):
+            # Use getattr since only Option has 'hidden', not all Parameter types
+            is_hidden = getattr(param, "hidden", False)
+
+            if is_hidden:
+                if show_hidden:
+                    # Temporarily unhide to get help record (Click returns None for hidden)
+                    _set_param_hidden(param, hidden=False)
+                    rv = param.get_help_record(ctx)
+                    _set_param_hidden(param, hidden=True)
+                    if rv is not None:
+                        hidden_opts.append(rv)
+            else:
+                rv = param.get_help_record(ctx)
+                if rv is not None:
+                    opts.append(rv)
+
+        if opts:
+            with formatter.section("Options"):
+                formatter.write_dl(opts)
+
+        if hidden_opts:
+            with formatter.section("Hidden Options"):
+                formatter.write_dl(hidden_opts)
+
+
+def script_option(fn: F) -> F:
+    """Decorator that adds --script option with proper settings.
+
+    Must be applied to a function decorated with @click.command(cls=CommandWithHiddenOptions).
+    The --script flag is hidden by default but visible when show_hidden_commands=True.
+
+    Example:
+        @click.command("up", cls=CommandWithHiddenOptions)
+        @script_option
+        def up_cmd(ctx: ErkContext, script: bool) -> None:
+            ...
+    """
+    return click.option(
+        "--script",
+        is_flag=True,
+        hidden=True,
+        help="Output shell script for integration. NOT a dry run.",
+    )(fn)
+
+
+class ErkCommandGroup(click.Group):
+    """Click Group that organizes commands into logical sections in help output.
+
+    Commands are organized into sections based on their usage patterns:
+    - Core Navigation: Primary workflow commands
+    - Command Groups: Organized subcommands
+    - Quick Access: Backward compatibility aliases
+
+    Args:
+        grouped: If True, organize commands into sections. If False, show flat list.
+    """
+
+    def __init__(self, grouped: bool = True, **kwargs: object) -> None:
+        super().__init__(**cast(dict[str, Any], kwargs))
+        self.grouped = grouped
+
+    def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        """Format help output, setting show_hidden based on config first.
+
+        This hook runs after context creation but before format_commands,
+        allowing us to set ctx.show_hidden based on the global config.
+        """
+        # Set show_hidden based on config before formatting help
+        self._set_show_hidden_from_context(ctx)
+
+        # Call parent to format help (which will call format_commands)
+        super().format_help(ctx, formatter)
+
+    def _set_show_hidden_from_context(self, ctx: click.Context) -> None:
+        """Set ctx.show_hidden based on config.
+
+        Checks ctx.obj.global_config if available (tests),
+        otherwise loads config from disk (direct CLI invocation).
+        """
+        # If ctx.obj is provided (tests or already-created context), use its config
+        if ctx.obj is not None:
+            config = getattr(ctx.obj, "global_config", None)
+            if config is not None and getattr(config, "show_hidden_commands", False):
+                _set_ctx_show_hidden(ctx, value=True)
+            return
+
+        # Otherwise try to load config directly from disk
+        installation = RealErkInstallation()
+        if installation.config_exists():
+            config = installation.load_config()
+            if config.show_hidden_commands:
+                _set_ctx_show_hidden(ctx, value=True)
+
+    def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        """Format commands into organized sections or flat list."""
+        show_hidden = getattr(ctx, "show_hidden", False)
+
+        # Check if Graphite is available (for hiding Graphite-dependent commands)
+        graphite_available = _is_graphite_available(ctx)
+
+        commands = []
+        hidden_commands = []
+        # Build alias map: alias_name -> primary_name
+        alias_map: dict[str, str] = {}
+
+        for subcommand in self.list_commands(ctx):
+            cmd = self.get_command(ctx, subcommand)
+            if cmd is None:
+                continue
+
+            # Build alias map from decorator-declared aliases
+            for alias_name in get_aliases(cmd):
+                alias_map[alias_name] = subcommand
+
+            # Commands are effectively hidden if:
+            # 1. They have hidden=True, OR
+            # 2. They require Graphite and Graphite is unavailable
+            effectively_hidden = cmd.hidden or (_requires_graphite(cmd) and not graphite_available)
+
+            if effectively_hidden:
+                if show_hidden:
+                    hidden_commands.append((subcommand, cmd))
+                continue
+            commands.append((subcommand, cmd))
+
+        if not commands:
+            return
+
+        # Flat output mode - single "Commands:" section
+        if not self.grouped:
+            # Filter out aliases (they'll be shown with their primary command)
+            primary_commands = [(n, c) for n, c in commands if n not in alias_map]
+            with formatter.section("Commands"):
+                self._format_command_list(ctx, formatter, primary_commands)
+
+            if hidden_commands:
+                with formatter.section("Hidden"):
+                    self._format_command_list(ctx, formatter, hidden_commands)
+            return
+
+        # Grouped output mode - organize into sections
+        # Define command organization (aliases now derived from decorator, not hardcoded)
+        top_level_commands = [
+            "checkout",
+            "dash",
+            "delete",
+            "doctor",
+            "down",
+            "implement",
+            "land",
+            "list",
+            "up",
+            "upgrade",
+        ]
+        command_groups = [
+            "admin",
+            "artifact",
+            "branch",
+            "cc",
+            "completion",
+            "config",
+            "docs",
+            "hook",
+            "info",
+            "md",
+            "objective",
+            "plan",
+            "planner",
+            "pr",
+            "project",
+            "run",
+            "slot",
+            "stack",
+            "wt",
+        ]
+        initialization = ["init"]
+
+        # Categorize commands
+        top_level_cmds = []
+        group_cmds = []
+        init_cmds = []
+        other_cmds = []
+
+        for name, cmd in commands:
+            # Skip aliases (they'll be shown with their primary command)
+            if name in alias_map:
+                continue
+
+            if name in top_level_commands:
+                top_level_cmds.append((name, cmd))
+            elif name in command_groups:
+                group_cmds.append((name, cmd))
+            elif name in initialization:
+                init_cmds.append((name, cmd))
+            else:
+                # Other commands
+                other_cmds.append((name, cmd))
+
+        # Format sections
+        if top_level_cmds:
+            with formatter.section("Top-Level Commands"):
+                self._format_command_list(ctx, formatter, top_level_cmds)
+
+        if group_cmds:
+            with formatter.section("Command Groups"):
+                self._format_command_list(ctx, formatter, group_cmds)
+
+        if init_cmds:
+            with formatter.section("Initialization"):
+                self._format_command_list(ctx, formatter, init_cmds)
+
+        if other_cmds:
+            with formatter.section("Other"):
+                self._format_command_list(ctx, formatter, other_cmds)
+
+        if hidden_commands:
+            with formatter.section("Hidden"):
+                self._format_command_list(ctx, formatter, hidden_commands)
+
+    def _format_command_list(
+        self,
+        ctx: click.Context,
+        formatter: click.HelpFormatter,
+        commands: list[tuple[str, click.Command]],
+    ) -> None:
+        """Format a list of commands with their help text.
+
+        Commands with aliases (declared via @alias decorator) are displayed
+        as 'checkout (co)'.
+        """
+        rows = []
+        for name, cmd in commands:
+            # Get aliases for this command and format display name
+            aliases = get_aliases(cmd)
+            if aliases:
+                display_name = f"{name} ({', '.join(aliases)})"
+            else:
+                display_name = name
+
+            help_text = cmd.get_short_help_str(limit=formatter.width)
+            rows.append((display_name, help_text))
+
+        if rows:
+            formatter.write_dl(rows)