erk 0.4.5__py3-none-any.whl

erk/cli/shell_integration/handler.py

@@ -0,0 +1,338 @@
+import os
+import shlex
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+import click
+
+from erk.cli.commands.prepare_cwd_recovery import generate_recovery_script
+from erk.cli.shell_utils import (
+    STALE_SCRIPT_MAX_AGE_SECONDS,
+    cleanup_stale_scripts,
+)
+from erk.cli.uvx_detection import get_uvx_warning_message, is_running_via_uvx
+from erk.core.context import create_context
+from erk_shared.debug import debug_log
+from erk_shared.output.output import user_confirm, user_output
+
+PASSTHROUGH_MARKER: Final[str] = "__ERK_PASSTHROUGH__"
+PASSTHROUGH_COMMANDS: Final[set[str]] = {"sync"}
+
+# Global flags that should be stripped from args before command matching
+# These are top-level flags that don't affect which command is being invoked
+GLOBAL_FLAGS: Final[set[str]] = {"--debug", "--dry-run", "--verbose", "-v"}
+
+# Commands that require shell integration (directory switching)
+# Maps command names (as received from shell) to CLI command paths (for subprocess)
+# Keys are what the shell handler receives, values are what gets passed to subprocess
+SHELL_INTEGRATION_COMMANDS: Final[dict[str, list[str]]] = {
+    # Top-level commands (key matches CLI path)
+    "checkout": ["checkout"],
+    "co": ["checkout"],  # Alias for checkout
+    "up": ["up"],
+    "down": ["down"],
+    "implement": ["implement"],
+    "impl": ["implement"],  # Alias for implement
+    "land": ["land"],  # Top-level land command
+    # Subcommands under pr
+    "pr checkout": ["pr", "checkout"],
+    "pr co": ["pr", "checkout"],  # Alias for pr checkout
+    # Legacy top-level aliases (map to actual CLI paths)
+    "create": ["wt", "create"],
+    "consolidate": ["stack", "consolidate"],
+    # Subcommands under wt
+    "wt create": ["wt", "create"],
+    "wt checkout": ["wt", "checkout"],
+    "wt co": ["wt", "checkout"],  # Alias for wt checkout
+    # Subcommands under stack
+    "stack consolidate": ["stack", "consolidate"],
+    # Subcommands under branch
+    "branch checkout": ["branch", "checkout"],
+    "branch co": ["branch", "checkout"],
+    "br checkout": ["branch", "checkout"],
+    "br co": ["branch", "checkout"],
+    "branch land": ["branch", "land"],
+    "br land": ["branch", "land"],
+    # Subcommands under slot
+    "slot checkout": ["slot", "checkout"],
+    "slot co": ["slot", "checkout"],
+}
+
+
+@dataclass(frozen=True)
+class ShellIntegrationResult:
+    """Result returned by shell integration handlers."""
+
+    passthrough: bool
+    script: str | None
+    exit_code: int
+
+
+def process_command_result(
+    exit_code: int,
+    stdout: str | None,
+    stderr: str | None,
+    command_name: str,
+    exception: BaseException | None = None,
+) -> ShellIntegrationResult:
+    """Process command result and determine shell integration behavior.
+
+    This function implements the core logic for deciding whether to use a script
+    or passthrough based on command output. It prioritizes script availability
+    over exit code to handle destructive commands that output scripts early.
+
+    Args:
+        exit_code: Command exit code
+        stdout: Command stdout (expected to be script path if successful)
+        stderr: Command stderr (error messages)
+        command_name: Name of the command (for user messages)
+        exception: Exception from CliRunner result (e.g., Click's MissingParameter)
+
+    Returns:
+        ShellIntegrationResult with passthrough, script, and exit_code
+    """
+    script_path = stdout.strip() if stdout else None
+
+    debug_log(f"Handler: Got script_path={script_path}, exit_code={exit_code}")
+
+    # Check if the script exists (only if we have a path)
+    script_exists = False
+    if script_path:
+        script_exists = Path(script_path).exists()
+        debug_log(f"Handler: Script exists? {script_exists}")
+
+    # If we have a valid script, use it even if command had errors.
+    # This handles destructive commands (like pr land) that output the script
+    # before failure. The shell can still navigate to the destination.
+    if script_path and script_exists:
+        # Forward stderr so user sees status messages even on success
+        # (e.g., "✓ Removed worktree", "✓ Deleted branch", etc.)
+        if stderr:
+            user_output(stderr, nl=False)
+        return ShellIntegrationResult(passthrough=False, script=script_path, exit_code=exit_code)
+
+    # No script available - if command failed, forward the error and don't passthrough.
+    # Passthrough would run the command again WITHOUT --script, which for commands
+    # like 'pr land' would show a misleading "requires shell integration" error
+    # instead of the actual failure reason.
+    if exit_code != 0:
+        if stderr:
+            user_output(stderr, nl=False)
+        elif exception is not None:
+            # Handle Click exceptions that don't go to stderr (e.g., MissingParameter)
+            # When using standalone_mode=False, Click stores usage errors in result.exception
+            # but leaves stderr empty, causing silent exits without this handling.
+            user_output(f"Error: {exception}")
+        return ShellIntegrationResult(passthrough=False, script=None, exit_code=exit_code)
+
+    # Forward stderr messages to user (only for successful commands)
+    if stderr:
+        user_output(stderr, nl=False)
+
+    # Note when command completed successfully but no directory change is needed
+    if script_path is None or not script_path:
+        user_output(f"Note: '{command_name}' completed (no directory change needed)")
+
+    return ShellIntegrationResult(passthrough=False, script=script_path, exit_code=exit_code)
+
+
+def _invoke_hidden_command(command_name: str, args: tuple[str, ...]) -> ShellIntegrationResult:
+    """Invoke a command with --script flag for shell integration.
+
+    If args contain help flags or explicit --script, passthrough to regular command.
+    Otherwise, add --script flag and run as subprocess with live stderr streaming.
+
+    Uses subprocess.run instead of CliRunner to allow stderr (user messages)
+    to stream directly to the terminal in real-time, while capturing stdout
+    (the activation script path) for shell integration.
+    """
+    # Check if help flags, --script, --dry-run, or non-interactive flags are present
+    # These should pass through to avoid shell integration adding --script.
+    # --yolo and --no-interactive conflict with --script (mutually exclusive).
+    passthrough_flags = {"-h", "--help", "--script", "--dry-run", "--yolo", "--no-interactive"}
+    if passthrough_flags & set(args):
+        return ShellIntegrationResult(passthrough=True, script=None, exit_code=0)
+
+    cli_cmd_parts = SHELL_INTEGRATION_COMMANDS.get(command_name)
+    if cli_cmd_parts is None:
+        if command_name in PASSTHROUGH_COMMANDS:
+            return _build_passthrough_script(command_name, args)
+        return ShellIntegrationResult(passthrough=True, script=None, exit_code=0)
+
+    # Check for uvx invocation and warn (command is already confirmed in SHELL_INTEGRATION_COMMANDS)
+    if is_running_via_uvx():
+        user_output(click.style("Warning: ", fg="yellow") + get_uvx_warning_message(command_name))
+        user_output("")  # Blank line for readability
+        if not user_confirm("Continue anyway?", default=False):
+            return ShellIntegrationResult(passthrough=False, script=None, exit_code=1)
+
+    # Clean up stale scripts before running (opportunistic cleanup)
+    cleanup_stale_scripts(max_age_seconds=STALE_SCRIPT_MAX_AGE_SECONDS)
+
+    # Build full command: erk <cli_cmd_parts> <args> --script
+    # cli_cmd_parts contains the actual CLI path (e.g., ["wt", "create"] for "create")
+    cmd = ["erk", *cli_cmd_parts, *args, "--script"]
+
+    debug_log(f"Handler: Running subprocess: {cmd}")
+
+    # Run subprocess with:
+    # - stdout captured (contains activation script path)
+    # - stderr passed through to terminal (live streaming of user messages)
+    result = subprocess.run(
+        cmd,
+        stdout=subprocess.PIPE,  # Capture stdout for script path
+        stderr=None,  # Let stderr pass through to terminal (live streaming)
+        text=True,
+        check=False,  # Don't raise on non-zero exit
+    )
+
+    return process_command_result(
+        exit_code=result.returncode,
+        stdout=result.stdout,
+        stderr=None,  # stderr already shown to user
+        command_name=command_name,
+        exception=None,  # No exception from subprocess
+    )
+
+
+def handle_shell_request(args: tuple[str, ...]) -> ShellIntegrationResult:
+    """Dispatch shell integration handling based on the original CLI invocation."""
+    if len(args) == 0:
+        return ShellIntegrationResult(passthrough=True, script=None, exit_code=0)
+
+    # Strip global flags from the beginning of args before command matching
+    # This ensures commands like "erk --debug pr land" are recognized correctly
+    args_list = list(args)
+    while args_list and args_list[0] in GLOBAL_FLAGS:
+        args_list.pop(0)
+
+    if len(args_list) == 0:
+        return ShellIntegrationResult(passthrough=True, script=None, exit_code=0)
+
+    # Try compound command first (e.g., "wt create", "stack consolidate")
+    if len(args_list) >= 2:
+        compound_name = f"{args_list[0]} {args_list[1]}"
+        if compound_name in SHELL_INTEGRATION_COMMANDS:
+            return _invoke_hidden_command(compound_name, tuple(args_list[2:]))
+
+    # Fall back to single command
+    command_name = args_list[0]
+    command_args = tuple(args_list[1:]) if len(args_list) > 1 else ()
+    return _invoke_hidden_command(command_name, command_args)
+
+
+def _build_passthrough_script(command_name: str, args: tuple[str, ...]) -> ShellIntegrationResult:
+    """Create a passthrough script tailored for the caller's shell."""
+    shell_name = os.environ.get("ERK_SHELL", "bash").lower()
+    ctx = create_context(dry_run=False)
+    recovery_path = generate_recovery_script(ctx)
+
+    script_content = _render_passthrough_script(shell_name, command_name, args, recovery_path)
+    result = ctx.script_writer.write_activation_script(
+        script_content,
+        command_name=f"{command_name}-passthrough",
+        comment="generated by __shell passthrough handler",
+    )
+    return ShellIntegrationResult(passthrough=False, script=str(result.path), exit_code=0)
+
+
+def _render_passthrough_script(
+    shell_name: str,
+    command_name: str,
+    args: tuple[str, ...],
+    recovery_path: Path | None,
+) -> str:
+    """Render shell-specific script that runs the command and performs recovery."""
+    if shell_name == "fish":
+        return _render_fish_passthrough(command_name, args, recovery_path)
+    return _render_posix_passthrough(command_name, args, recovery_path)
+
+
+def _render_posix_passthrough(
+    command_name: str,
+    args: tuple[str, ...],
+    recovery_path: Path | None,
+) -> str:
+    quoted_args = " ".join(shlex.quote(part) for part in (command_name, *args))
+    recovery_literal = shlex.quote(str(recovery_path)) if recovery_path is not None else "''"
+    lines = [
+        f"command erk {quoted_args}",
+        "__erk_exit=$?",
+        f"__erk_recovery={recovery_literal}",
+        'if [ -n "$__erk_recovery" ] && [ -f "$__erk_recovery" ]; then',
+        '  if [ ! -d "$PWD" ]; then',
+        '    . "$__erk_recovery"',
+        "  fi",
+        '  if [ -z "$ERK_KEEP_SCRIPTS" ]; then',
+        '    rm -f "$__erk_recovery"',
+        "  fi",
+        "fi",
+        "return $__erk_exit",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def _quote_fish(arg: str) -> str:
+    if not arg:
+        return '""'
+
+    escape_map = {
+        "\\": "\\\\",
+        '"': '\\"',
+        "$": "\\$",
+        "`": "\\`",
+        "~": "\\~",
+        "*": "\\*",
+        "?": "\\?",
+        "{": "\\{",
+        "}": "\\}",
+        "[": "\\[",
+        "]": "\\]",
+        "(": "\\(",
+        ")": "\\)",
+        "<": "\\<",
+        ">": "\\>",
+        "|": "\\|",
+        ";": "\\;",
+        "&": "\\&",
+    }
+    escaped_parts: list[str] = []
+    for char in arg:
+        if char == "\n":
+            escaped_parts.append("\\n")
+            continue
+        if char == "\t":
+            escaped_parts.append("\\t")
+            continue
+        escaped_parts.append(escape_map.get(char, char))
+
+    escaped = "".join(escaped_parts)
+    return f'"{escaped}"'
+
+
+def _render_fish_passthrough(
+    command_name: str,
+    args: tuple[str, ...],
+    recovery_path: Path | None,
+) -> str:
+    command_parts = " ".join(_quote_fish(part) for part in (command_name, *args))
+    recovery_literal = _quote_fish(str(recovery_path)) if recovery_path is not None else '""'
+    lines = [
+        f"command erk {command_parts}",
+        "set __erk_exit $status",
+        f"set __erk_recovery {recovery_literal}",
+        'if test -n "$__erk_recovery"',
+        '    if test -f "$__erk_recovery"',
+        '        if not test -d "$PWD"',
+        '            source "$__erk_recovery"',
+        "        end",
+        "        if not set -q ERK_KEEP_SCRIPTS",
+        '            rm -f "$__erk_recovery"',
+        "        end",
+        "    end",
+        "end",
+        "return $__erk_exit",
+    ]
+    return "\n".join(lines) + "\n"

erk/cli/shell_integration/zsh_wrapper.sh

@@ -0,0 +1,32 @@
+# Erk shell integration for zsh
+# This function wraps the erk CLI to provide seamless worktree switching
+
+erk() {
+  # Don't intercept if we're doing shell completion
+  [ -n "$_ERK_COMPLETE" ] && { command erk "$@"; return; }
+
+  local script_path exit_status
+  script_path=$(ERK_SHELL=zsh command erk __shell "$@")
+  exit_status=$?
+
+  # Passthrough mode: run the original command directly
+  [ "$script_path" = "__ERK_PASSTHROUGH__" ] && { command erk "$@"; return; }
+
+  # Source the script file if it exists, regardless of exit code.
+  # This matches Python handler logic: use script even if command had errors.
+  # The script contains important state changes (like cd to target dir).
+  if [ -n "$script_path" ] && [ -f "$script_path" ]; then
+    source "$script_path"
+    local source_exit=$?
+
+    # Clean up unless ERK_KEEP_SCRIPTS is set
+    if [ -z "$ERK_KEEP_SCRIPTS" ]; then
+      rm -f "$script_path"
+    fi
+
+    return $source_exit
+  fi
+
+  # Only return exit_status if no script was provided
+  [ $exit_status -ne 0 ] && return $exit_status
+}

erk/cli/shell_utils.py

@@ -0,0 +1,171 @@
+"""Utilities for generating shell integration scripts."""
+
+import os
+import tempfile
+import time
+import uuid
+from datetime import datetime
+from pathlib import Path
+
+from erk.cli.activation import _render_logging_helper, render_activation_script
+from erk_shared.debug import debug_log
+
+STALE_SCRIPT_MAX_AGE_SECONDS = 3600
+
+
+def render_cd_script(path: Path, *, comment: str, success_message: str) -> str:
+    """Generate shell script to change directory with feedback.
+
+    Args:
+        path: Target directory path to cd into.
+        comment: Shell comment describing the operation.
+        success_message: Message to echo after successful cd.
+
+    Returns:
+        Shell script that changes directory and shows success message.
+    """
+    path_str = str(path)
+    path_name = path.name
+    quoted_path = "'" + path_str.replace("'", "'\\''") + "'"
+    logging_helper = _render_logging_helper()
+    lines = [
+        f"# {comment}",
+        logging_helper,
+        f'__erk_log "->" "Switching to: {path_name}"',
+        f'__erk_log_verbose "->" "Directory: $(pwd) -> {path}"',
+        f"cd {quoted_path}",
+        f'echo "{success_message}"',
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def render_navigation_script(
+    target_path: Path,
+    repo_root: Path,
+    *,
+    comment: str,
+    success_message: str,
+) -> str:
+    """Generate navigation script that automatically chooses between simple cd or full activation.
+
+    This function determines whether the target is the root worktree or a non-root worktree
+    and generates the appropriate navigation script:
+
+    - Root worktree (target_path == repo_root): Simple cd script via render_cd_script()
+      - Only changes directory
+      - No venv activation needed (user manages their own environment)
+
+    - Non-root worktree (target_path != repo_root): Full activation script via
+      render_activation_script()
+      - Changes directory
+      - Creates/activates virtual environment
+      - Loads .env file
+      - Required for erk-managed worktrees
+
+    Args:
+        target_path: Directory to navigate to
+        repo_root: Repository root path (used to determine if target is root worktree)
+        comment: Shell comment describing the operation
+        success_message: Message to display after successful navigation
+
+    Returns:
+        Shell script that performs appropriate navigation based on worktree type
+
+    Example:
+        >>> # Navigate to root worktree (simple cd)
+        >>> script = render_navigation_script(
+        ...     Path("/repo"),
+        ...     Path("/repo"),
+        ...     comment="return to root",
+        ...     success_message="At root"
+        ... )
+        >>>
+        >>> # Navigate to non-root worktree (full activation)
+        >>> script = render_navigation_script(
+        ...     Path("/repo/worktrees/feature"),
+        ...     Path("/repo"),
+        ...     comment="switch to feature",
+        ...     success_message="Activated feature"
+        ... )
+    """
+    if target_path == repo_root:
+        return render_cd_script(
+            target_path,
+            comment=comment,
+            success_message=success_message,
+        )
+    return render_activation_script(
+        worktree_path=target_path,
+        target_subpath=None,
+        post_cd_commands=None,
+        final_message=f'echo "{success_message}"',
+        comment=comment,
+    )
+
+
+def write_script_to_temp(
+    script_content: str,
+    *,
+    command_name: str,
+    comment: str | None = None,
+) -> Path:
+    """Write shell script to temp file with unique UUID.
+
+    Args:
+        script_content: The shell script to write
+        command_name: Command that generated this (e.g., 'sync', 'switch', 'create')
+        comment: Optional comment to include in script header
+
+    Returns:
+        Path to the temp file
+
+    Filename format: erk-{command}-{uuid}.sh
+    """
+    unique_id = uuid.uuid4().hex[:8]  # 8 chars sufficient (4 billion combinations)
+    temp_dir = Path(tempfile.gettempdir())
+    temp_file = temp_dir / f"erk-{command_name}-{unique_id}.sh"
+
+    # Add metadata header
+    header = [
+        "#!/bin/bash",
+        f"# erk {command_name}",
+        f"# Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
+        f"# UUID: {unique_id}",
+        f"# User: {os.getenv('USER', 'unknown')}",
+        f"# Working dir: {Path.cwd()}",
+    ]
+
+    if comment:
+        header.append(f"# {comment}")
+
+    header.append("")  # Blank line before script
+
+    full_content = "\n".join(header) + "\n" + script_content
+    temp_file.write_text(full_content, encoding="utf-8")
+
+    # Make executable for good measure
+    temp_file.chmod(0o755)
+
+    debug_log(f"write_script_to_temp: Created {temp_file}")
+    debug_log(f"write_script_to_temp: Content:\n{full_content}")
+
+    return temp_file
+
+
+def cleanup_stale_scripts(*, max_age_seconds: int = STALE_SCRIPT_MAX_AGE_SECONDS) -> None:
+    """Remove erk temp scripts older than max_age_seconds.
+
+    Args:
+        max_age_seconds: Maximum age before cleanup (default 1 hour)
+    """
+    temp_dir = Path(tempfile.gettempdir())
+    cutoff = time.time() - max_age_seconds
+
+    for script_file in temp_dir.glob("erk-*.sh"):
+        if script_file.exists():
+            try:
+                if script_file.stat().st_mtime < cutoff:
+                    script_file.unlink()
+            except (FileNotFoundError, PermissionError):
+                # Scripts may disappear between stat/unlink or be owned by another user.
+                continue

erk/cli/subprocess_utils.py

@@ -0,0 +1,92 @@
+"""Utilities for running subprocesses with better error reporting.
+
+This module provides CLI-layer subprocess execution with user-friendly error output.
+
+For integration layer subprocess calls (raises RuntimeError), use:
+    from erk_shared.subprocess_utils import run_subprocess_with_context
+
+For CLI-layer subprocess calls (prints message, raises SystemExit), use:
+    from erk.cli.subprocess_utils import run_with_error_reporting (this module)
+"""
+
+import subprocess
+from collections.abc import Sequence
+from pathlib import Path
+
+from erk_shared.output.output import user_output
+
+
+def run_with_error_reporting(
+    cmd: Sequence[str],
+    *,
+    cwd: Path | None = None,
+    error_prefix: str = "Command failed",
+    troubleshooting: list[str] | None = None,
+    show_output: bool = False,
+) -> subprocess.CompletedProcess[str]:
+    """Run subprocess command with user-friendly error reporting for CLI layer.
+
+    This function is designed for CLI commands that need to display error messages
+    directly to users and exit the program. For integration layer code that needs
+    to raise exceptions with context, use run_subprocess_with_context() instead.
+
+    Args:
+        cmd: Command to run as a list of strings
+        cwd: Working directory for the command
+        error_prefix: Prefix for error message
+        troubleshooting: Optional list of troubleshooting suggestions
+        show_output: If True, show stdout/stderr in real-time (default: False)
+
+    Returns:
+        CompletedProcess if successful
+
+    Raises:
+        SystemExit: If command fails (after displaying user-friendly error)
+
+    Example:
+        >>> run_with_error_reporting(
+        ...     ["gh", "pr", "view", "123"],
+        ...     cwd=repo_root,
+        ...     error_prefix="Failed to view PR",
+        ...     troubleshooting=["Ensure gh is installed", "Run 'gh auth login'"]
+        ... )
+
+    Notes:
+        - This is for CLI-layer code (commands that interact with users)
+        - For integration layer code, use run_subprocess_with_context() instead
+        - Uses check=False and manually handles errors for user-friendly output
+        - Displays stderr/stdout to user before raising SystemExit
+        - When show_output=True, output streams directly to terminal
+    """
+    result = subprocess.run(cmd, cwd=cwd, check=False, capture_output=not show_output, text=True)
+
+    if result.returncode != 0:
+        # When show_output=True, output already displayed, only show error context
+        if show_output:
+            message_parts = [
+                f"Error: {error_prefix}.\n",
+                f"Command: {' '.join(cmd)}",
+                f"Exit code: {result.returncode}\n",
+            ]
+        else:
+            error_msg = result.stderr.strip() if result.stderr else result.stdout.strip()
+
+            # Build error message
+            message_parts = [
+                f"Error: {error_prefix}.\n",
+                f"Command: {' '.join(cmd)}",
+                f"Exit code: {result.returncode}\n",
+            ]
+
+            if error_msg:
+                message_parts.append(f"Output:\n{error_msg}\n")
+
+        if troubleshooting:
+            message_parts.append("Troubleshooting:")
+            for tip in troubleshooting:
+                message_parts.append(f"  • {tip}")
+
+        user_output("\n".join(message_parts))
+        raise SystemExit(1)
+
+    return result

erk/cli/uvx_detection.py

@@ -0,0 +1,59 @@
+"""Detection for uvx (uv tool run) invocation.
+
+This module detects when erk is running via 'uvx erk' or 'uv tool run erk',
+which prevents shell integration from working properly.
+"""
+
+import sys
+from pathlib import Path
+
+
+def is_running_via_uvx() -> bool:
+    """Detect if running via uvx/uv tool run (best effort, not officially supported).
+
+    Detection strategy:
+    1. Check pyvenv.cfg for uv marker - if absent, not a uv-created venv
+    2. Check if prefix path contains ephemeral cache markers (uvx uses cache, not tool dir)
+
+    Note: uvx environments are ephemeral (live in cache directory), while
+    `uv tool install` environments are persistent. We only want to detect uvx.
+
+    Returns:
+        True if running via uvx, False otherwise
+    """
+    prefix = Path(sys.prefix)
+
+    # Check pyvenv.cfg for uv marker
+    pyvenv_cfg = prefix / "pyvenv.cfg"
+    if pyvenv_cfg.exists():
+        content = pyvenv_cfg.read_text(encoding="utf-8")
+        if "uv = " not in content:
+            return False  # Not a uv-created venv
+
+    # uvx environments are ephemeral (in cache), not persistent (in UV_TOOL_DIR)
+    prefix_str = str(prefix)
+    ephemeral_markers = (
+        "/uv/archive-v",  # uvx ephemeral environments
+        "/.cache/uv/",
+        "/cache/uv/",
+    )
+    return any(marker in prefix_str for marker in ephemeral_markers)
+
+
+def get_uvx_warning_message(command_name: str) -> str:
+    """Get the warning message to display when running via uvx.
+
+    Args:
+        command_name: The shell integration command being invoked (e.g., "checkout", "up")
+
+    Returns:
+        Multi-line warning message explaining the issue and fix
+    """
+    return f"""Running 'erk {command_name}' via uvx - this command requires shell integration
+
+Shell integration commands need to change your shell's directory, which doesn't work
+when running in uvx's isolated subprocess.
+
+To fix this:
+  1. Install erk in uv's tools: uv tool install erk
+  2. Set up shell integration: erk init --shell"""