erk 0.4.5__py3-none-any.whl

erk/cli/activation.py

@@ -0,0 +1,132 @@
+"""Shell activation script generation for worktree environments.
+
+This module provides utilities for generating shell scripts that activate
+worktree environments by setting up virtual environments and loading .env files.
+"""
+
+import shlex
+from collections.abc import Sequence
+from pathlib import Path
+
+
+def _render_logging_helper() -> str:
+    """Return shell helper functions for transparency logging.
+
+    These helpers handle ERK_QUIET and ERK_VERBOSE environment variables
+    to control output verbosity during worktree activation.
+
+    Normal mode (default): Shows brief progress indicators
+    Quiet mode (ERK_QUIET=1): Suppresses transparency output (errors still shown)
+    Verbose mode (ERK_VERBOSE=1): Shows full details with paths
+    """
+    return """# Transparency logging helper
+__erk_log() {
+  [ -n "$ERK_QUIET" ] && return
+  local prefix="$1" msg="$2"
+  if [ -t 2 ]; then
+    printf '\\033[0;36m%s\\033[0m %s\\n' "$prefix" "$msg" >&2
+  else
+    printf '%s %s\\n' "$prefix" "$msg" >&2
+  fi
+}
+__erk_log_verbose() {
+  [ -z "$ERK_VERBOSE" ] && return
+  __erk_log "$1" "$2"
+}"""
+
+
+def render_activation_script(
+    *,
+    worktree_path: Path,
+    target_subpath: Path | None,
+    post_cd_commands: Sequence[str] | None,
+    final_message: str,
+    comment: str,
+) -> str:
+    """Return shell code that activates a worktree's venv and .env.
+
+    The script:
+      - cds into the worktree (optionally to a subpath within it)
+      - creates .venv with `uv sync` if not present
+      - sources `.venv/bin/activate` if present
+      - exports variables from `.env` if present
+      - runs optional post-activation commands (e.g., git pull)
+    Works in bash and zsh.
+
+    Args:
+        worktree_path: Path to the worktree directory
+        target_subpath: Optional relative path within the worktree to cd to.
+            If the subpath doesn't exist, a warning is shown and the script
+            falls back to the worktree root.
+        post_cd_commands: Optional sequence of shell commands to run after venv
+            activation, before final message. Useful for git pull after landing a PR.
+            Pass None if no post-cd commands are needed.
+        final_message: Shell command for final echo message
+        comment: Comment line for script identification
+
+    Returns:
+        Shell script as a string with newlines
+
+    Example:
+        >>> script = render_activation_script(
+        ...     worktree_path=Path("/path/to/worktree"),
+        ...     target_subpath=Path("src/lib"),
+        ...     post_cd_commands=None,
+        ...     final_message='echo "Ready: $(pwd)"',
+        ...     comment="work activate-script",
+        ... )
+    """
+    wt = shlex.quote(str(worktree_path))
+    venv_dir = shlex.quote(str(worktree_path / ".venv"))
+    venv_activate = shlex.quote(str(worktree_path / ".venv" / "bin" / "activate"))
+
+    # Generate the cd command with optional subpath handling
+    if target_subpath is not None:
+        subpath_quoted = shlex.quote(str(target_subpath))
+        # Check if subpath exists in target worktree, fall back to root with warning
+        cd_command = f"""__erk_log "->" "cd {worktree_path}"
+cd {wt}
+# Try to preserve relative directory position
+if [ -d {subpath_quoted} ]; then
+  cd {subpath_quoted}
+else
+  echo "Warning: '{target_subpath}' doesn't exist in target, using worktree root" >&2
+fi"""
+    else:
+        cd_command = f"""__erk_log "->" "cd {worktree_path}"
+cd {wt}"""
+
+    logging_helper = _render_logging_helper()
+
+    # Build optional post-activation commands section
+    post_activation_section = ""
+    if post_cd_commands:
+        post_activation_section = (
+            "# Post-activation commands\n" + "\n".join(post_cd_commands) + "\n"
+        )
+
+    return f"""# {comment}
+{logging_helper}
+{cd_command}
+# Unset VIRTUAL_ENV to avoid conflicts with previous activations
+unset VIRTUAL_ENV
+# Create venv if it doesn't exist
+if [ ! -d {venv_dir} ]; then
+  echo 'Creating virtual environment with uv sync...'
+  uv sync
+fi
+if [ -f {venv_activate} ]; then
+  . {venv_activate}
+  __py_ver=$(python -c 'import sys; print(".".join(map(str, sys.version_info[:3])))')
+  __erk_log "->" "Activating venv: {worktree_path / ".venv"} ($__py_ver)"
+fi
+# Load .env into the environment (allexport)
+set -a
+if [ -f ./.env ]; then
+  __erk_log "->" "Loading .env"
+  . ./.env
+fi
+set +a
+{post_activation_section}# Optional: show where we are
+{final_message}
+"""

erk/cli/alias.py

@@ -0,0 +1,53 @@
+"""Command alias decorator for CLI commands."""
+
+from collections.abc import Callable
+from typing import TypeVar
+
+import click
+
+F = TypeVar("F", bound=click.Command)
+C = TypeVar("C", bound=Callable[..., object])
+
+# Store alias metadata on command objects
+ALIAS_ATTR = "_erk_aliases"
+
+
+def alias(*names: str) -> Callable[[F], F]:
+    """Decorator to declare aliases for a Click command.
+
+    Must be applied BEFORE @click.command (i.e., listed above it in the decorator stack).
+    This is because decorators are applied bottom-to-top, so @alias runs AFTER @click.command
+    creates the Command object.
+
+    Usage:
+        @alias("co")
+        @click.command("checkout")
+        def checkout_cmd(...):
+            ...
+    """
+
+    def decorator(cmd: F) -> F:
+        existing = getattr(cmd, ALIAS_ATTR, [])
+        setattr(cmd, ALIAS_ATTR, existing + list(names))
+        return cmd
+
+    return decorator
+
+
+def get_aliases(cmd: click.Command) -> list[str]:
+    """Get aliases declared on a command."""
+    return getattr(cmd, ALIAS_ATTR, [])
+
+
+def register_with_aliases(group: click.Group, cmd: click.Command, name: str | None = None) -> None:
+    """Register a command and its declared aliases with a group.
+
+    Args:
+        group: The Click group to register the command with
+        cmd: The command to register
+        name: Optional explicit name (defaults to cmd.name)
+    """
+    cmd_name = name or cmd.name
+    group.add_command(cmd, name=cmd_name)
+    for alias_name in get_aliases(cmd):
+        group.add_command(cmd, name=alias_name)

erk/cli/cli.py

@@ -0,0 +1,221 @@
+import logging
+import os
+import sys
+from pathlib import Path
+
+import click
+
+from erk.cli.alias import register_with_aliases
+from erk.cli.commands.admin import admin_group
+from erk.cli.commands.artifact.group import artifact_group
+from erk.cli.commands.branch import branch_group
+from erk.cli.commands.cc import cc_group
+from erk.cli.commands.completion import completion_group
+from erk.cli.commands.config import config_group
+from erk.cli.commands.docs.group import docs_group
+from erk.cli.commands.doctor import doctor_cmd
+from erk.cli.commands.down import down_cmd
+from erk.cli.commands.exec.group import exec_group
+from erk.cli.commands.implement import implement
+from erk.cli.commands.info import info_group
+from erk.cli.commands.init import init_cmd
+from erk.cli.commands.land_cmd import land
+from erk.cli.commands.log_cmd import log_cmd
+from erk.cli.commands.md.group import md_group
+from erk.cli.commands.objective import objective_group
+from erk.cli.commands.plan import plan_group
+from erk.cli.commands.plan.list_cmd import dash
+from erk.cli.commands.planner import planner_group
+from erk.cli.commands.pr import pr_group
+from erk.cli.commands.prepare_cwd_recovery import prepare_cwd_recovery_cmd
+from erk.cli.commands.project import project_group
+from erk.cli.commands.run import run_group
+from erk.cli.commands.shell_integration import hidden_shell_cmd
+from erk.cli.commands.slot import slot_group
+from erk.cli.commands.stack import stack_group
+from erk.cli.commands.up import up_cmd
+from erk.cli.commands.upgrade import upgrade_cmd
+from erk.cli.commands.wt import wt_group
+from erk.cli.help_formatter import ErkCommandGroup
+from erk.core.command_log import get_cli_args, log_command_start, register_exit_handler
+from erk.core.context import create_context
+from erk.core.release_notes import check_for_version_change, get_current_version
+from erk.core.version_check import (
+    format_version_warning,
+    get_required_version,
+    is_version_mismatch,
+)
+from erk_shared.gateway.erk_installation.real import RealErkInstallation
+from erk_shared.git.real import RealGit
+
+CONTEXT_SETTINGS = dict(help_option_names=["-h", "--help"])  # terse help flags
+
+
+def _show_version_change_banner() -> None:
+    """Show upgrade banner with full release notes if version has changed.
+
+    Displays all release notes since the last seen version and prompts user
+    to confirm before continuing. This function is designed to never fail -
+    exceptions are logged but don't break the CLI.
+    """
+    try:
+        erk_installation = RealErkInstallation()
+        changed, releases = check_for_version_change(erk_installation)
+        if not changed or not releases:
+            return
+
+        current = get_current_version()
+
+        # Build banner header
+        click.echo(file=sys.stderr)
+        click.echo(
+            click.style(f"  ✨ erk updated to v{current}", fg="green", bold=True), file=sys.stderr
+        )
+        click.echo(click.style("  " + "─" * 50, dim=True), file=sys.stderr)
+        click.echo(file=sys.stderr)
+
+        # Show all releases with their items grouped by category
+        for release in releases:
+            # Skip releases with no items
+            if not release.items:
+                continue
+
+            # Version header
+            header = f"  [{release.version}]"
+            if release.date:
+                header += f" - {release.date}"
+            click.echo(click.style(header, bold=True), file=sys.stderr)
+
+            # Show items grouped by category if available
+            if release.categories:
+                for category, category_items in release.categories.items():
+                    if not category_items:
+                        continue
+                    click.echo(click.style(f"    {category}", dim=True), file=sys.stderr)
+                    for item_text, indent_level in category_items:
+                        # Base indent (6 spaces) + extra indent per nesting level (2 spaces)
+                        indent = "      " + ("  " * indent_level)
+                        click.echo(f"{indent}• {item_text}", file=sys.stderr)
+            else:
+                # Fallback to flat list for releases without categories
+                for item_text, indent_level in release.items:
+                    indent = "    " + ("  " * indent_level)
+                    click.echo(f"{indent}• {item_text}", file=sys.stderr)
+            click.echo(file=sys.stderr)
+
+        click.echo(click.style("  " + "─" * 50, dim=True), file=sys.stderr)
+        click.echo(file=sys.stderr)
+
+        # Prompt user to continue (only if stdin is a TTY)
+        if sys.stdin.isatty():
+            click.pause(info=click.style("  Press Enter to continue...", dim=True), err=True)
+    except click.Abort:
+        # User pressed Ctrl+C or declined - exit gracefully
+        raise SystemExit(0) from None
+    except Exception as e:
+        # Never let release notes break the CLI, but warn so issues can be diagnosed
+        logging.warning("Failed to show version change banner: %s", e)
+
+
+def _show_version_warning() -> None:
+    """Show warning if installed erk version doesn't match repo-required version.
+
+    This is designed to never fail - exceptions are logged but don't break the CLI.
+    """
+    # Skip if user has disabled version checking
+    if os.environ.get("ERK_SKIP_VERSION_CHECK") == "1":
+        return
+
+    try:
+        # Find git repo root (if in a git repo)
+        git = RealGit()
+        repo_root = git.get_repository_root(Path.cwd())
+        if repo_root is None:
+            return
+
+        # Read required version from repo
+        required = get_required_version(repo_root)
+        if required is None:
+            return
+
+        # Compare versions
+        installed = get_current_version()
+        if not is_version_mismatch(installed, required):
+            return
+
+        # Show warning
+        click.echo(format_version_warning(installed, required), err=True)
+        click.echo(file=sys.stderr)
+    except RuntimeError as e:
+        # Expected for global commands outside git repos
+        if "get repository root" in str(e):
+            logging.debug("Version check skipped: not in git repo")
+            return
+        logging.warning("Failed to check version: %s", e)
+    except Exception as e:
+        # Never let version checking break the CLI, but warn so issues can be diagnosed
+        logging.warning("Failed to check version: %s", e)
+
+
+@click.group(cls=ErkCommandGroup, context_settings=CONTEXT_SETTINGS)
+@click.version_option(package_name="erk")
+@click.option("--debug", is_flag=True, help="Enable debug logging")
+@click.pass_context
+def cli(ctx: click.Context, debug: bool) -> None:
+    """Manage git worktrees in a global worktrees directory."""
+    if debug:
+        logging.basicConfig(level=logging.DEBUG, format="%(name)s - %(levelname)s - %(message)s")
+
+    # Show version change banner (only on actual CLI runs, not completions)
+    if not ctx.resilient_parsing:
+        _show_version_change_banner()
+        _show_version_warning()
+
+    # Only create context if not already provided (e.g., by tests)
+    if ctx.obj is None:
+        ctx.obj = create_context(dry_run=False)
+
+
+# Register all commands
+# Commands with @alias decorators use register_with_aliases() to auto-register aliases
+cli.add_command(admin_group)
+cli.add_command(artifact_group)
+register_with_aliases(cli, branch_group)  # Has @alias("br")
+cli.add_command(cc_group)
+cli.add_command(completion_group)
+cli.add_command(config_group)
+cli.add_command(doctor_cmd)
+cli.add_command(down_cmd)
+register_with_aliases(cli, implement)  # Has @alias("impl")
+cli.add_command(init_cmd)
+cli.add_command(land)
+admin_group.add_command(log_cmd)
+cli.add_command(dash)
+cli.add_command(plan_group)
+cli.add_command(planner_group)
+cli.add_command(pr_group)
+cli.add_command(info_group)
+cli.add_command(objective_group)
+cli.add_command(project_group)
+cli.add_command(slot_group)
+cli.add_command(run_group)
+cli.add_command(stack_group)
+cli.add_command(up_cmd)
+cli.add_command(upgrade_cmd)
+cli.add_command(wt_group)
+cli.add_command(hidden_shell_cmd)
+cli.add_command(prepare_cwd_recovery_cmd)
+
+# Additional command groups
+cli.add_command(docs_group)
+cli.add_command(exec_group)
+cli.add_command(md_group)
+
+
+def main() -> None:
+    """CLI entry point used by the `erk` console script."""
+    # Log command start and register exit handler for completion logging
+    entry_id = log_command_start(get_cli_args(), Path.cwd())
+    register_exit_handler(entry_id)
+
+    cli()

erk/cli/commands/admin.py

@@ -0,0 +1,153 @@
+"""Admin commands for repository configuration."""
+
+from typing import Literal
+
+import click
+
+from erk.cli.core import discover_repo_context
+from erk.core.context import ErkContext
+from erk.core.implementation_queue.github.real import RealGitHubAdmin
+from erk_shared.github.types import GitHubRepoLocation
+from erk_shared.output.output import user_output
+
+
+@click.group("admin")
+def admin_group() -> None:
+    """Administrative commands for repository configuration."""
+    pass
+
+
+@admin_group.command("github-pr-setting")
+@click.option(
+    "--enable",
+    "action",
+    flag_value="enable",
+    help="Enable PR creation for GitHub Actions workflows",
+)
+@click.option(
+    "--disable",
+    "action",
+    flag_value="disable",
+    help="Disable PR creation for GitHub Actions workflows",
+)
+@click.pass_obj
+def github_pr_setting(ctx: ErkContext, action: Literal["enable", "disable"] | None) -> None:
+    """Manage GitHub Actions workflow permission for PR creation.
+
+    Without flags: Display current setting
+    With --enable: Enable PR creation for workflows
+    With --disable: Disable PR creation for workflows
+
+    This setting controls whether GitHub Actions workflows can create
+    and approve pull requests in your repository.
+
+    GitHub UI location: Settings > Actions > General > Workflow permissions
+    """
+    # Discover repository context
+    repo = discover_repo_context(ctx, ctx.cwd)
+
+    # Check for GitHub identity
+    if repo.github is None:
+        user_output(click.style("Error: ", fg="red") + "Not a GitHub repository")
+        user_output("This command requires the repository to have a GitHub remote configured.")
+        raise SystemExit(1)
+
+    # Create admin interface
+    # TODO: Use injected admin from context when dry-run support is added
+    admin = RealGitHubAdmin()
+    location = GitHubRepoLocation(root=repo.root, repo_id=repo.github)
+
+    if action is None:
+        # Display current setting
+        try:
+            perms = admin.get_workflow_permissions(location)
+            enabled = perms.get("can_approve_pull_request_reviews", False)
+
+            user_output(click.style("GitHub Actions PR Creation Setting", bold=True))
+            user_output("")
+
+            status_text = "Enabled" if enabled else "Disabled"
+            status_color = "green" if enabled else "red"
+            user_output(f"Current status: {click.style(status_text, fg=status_color)}")
+            user_output("")
+
+            if enabled:
+                user_output("Workflows can create and approve pull requests in this repository.")
+            else:
+                user_output("Workflows cannot create pull requests in this repository.")
+
+            user_output("")
+            user_output(click.style("GitHub UI location:", fg="white", dim=True))
+            user_output(
+                click.style(
+                    "  Settings > Actions > General > Workflow permissions",
+                    fg="white",
+                    dim=True,
+                )
+            )
+
+        except RuntimeError as e:
+            user_output(click.style("Error: ", fg="red") + str(e))
+            raise SystemExit(1) from e
+
+    elif action == "enable":
+        # Enable PR creation
+        try:
+            admin.set_workflow_pr_permissions(location, enabled=True)
+
+            user_output(
+                click.style("✓", fg="green") + " Enabled PR creation for GitHub Actions workflows"
+            )
+            user_output("")
+            user_output("Workflows can now create and approve pull requests.")
+
+        except RuntimeError as e:
+            user_output(click.style("Error: ", fg="red") + str(e))
+            raise SystemExit(1) from e
+
+    elif action == "disable":
+        # Disable PR creation
+        try:
+            admin.set_workflow_pr_permissions(location, enabled=False)
+
+            user_output(
+                click.style("✓", fg="green") + " Disabled PR creation for GitHub Actions workflows"
+            )
+            user_output("")
+            user_output("Workflows can no longer create pull requests.")
+
+        except RuntimeError as e:
+            user_output(click.style("Error: ", fg="red") + str(e))
+            raise SystemExit(1) from e
+
+
+@admin_group.command("upgrade-repo")
+@click.pass_obj
+def upgrade_repo(ctx: ErkContext) -> None:
+    """Upgrade repo to match installed erk version.
+
+    Updates .erk/required-erk-uv-tool-version and prints next steps.
+    """
+    from erk.core.release_notes import get_current_version
+
+    repo = discover_repo_context(ctx, ctx.cwd)
+    current_version = get_current_version()
+
+    # Check if this is an erk-managed repository
+    erk_dir = repo.root / ".erk"
+    if not erk_dir.exists():
+        user_output(click.style("Error: ", fg="red") + "Not an erk-managed repository")
+        user_output(f"The directory {repo.root} does not contain a .erk directory.")
+        user_output("This command only works in repositories initialized with erk.")
+        raise SystemExit(1)
+
+    # Update version file
+    version_file = erk_dir / "required-erk-uv-tool-version"
+    version_file.write_text(f"{current_version}\n", encoding="utf-8")
+    user_output(f"Updated required version to {current_version}")
+
+    # Print next steps
+    user_output("")
+    user_output("Next steps:")
+    user_output("  erk artifact sync   # Sync skills, commands, hooks")
+    user_output("  erk doctor          # Verify the upgrade")

erk/cli/commands/artifact/__init__.py

@@ -0,0 +1 @@
+# Empty file