erk 0.4.5__py3-none-any.whl

erk/cli/commands/completion.py

@@ -0,0 +1,89 @@
+import click
+
+from erk.core.context import ErkContext
+from erk_shared.output.output import machine_output
+
+
+@click.group("completion")
+def completion_group() -> None:
+    """Generate shell completion scripts."""
+
+
+@completion_group.command("bash")
+@click.pass_obj
+def completion_bash(ctx: ErkContext) -> None:
+    """Generate bash completion script.
+
+    \b
+    For automatic setup of both completion and auto-activation:
+      erk init --shell
+
+    \b
+    To load completions in your current shell session:
+      source <(erk completion bash)
+
+    \b
+    To load completions permanently, add to your ~/.bashrc:
+      echo 'source <(erk completion bash)' >> ~/.bashrc
+
+    \b
+    Alternatively, you can save the completion script to bash_completion.d:
+      erk completion bash > /usr/local/etc/bash_completion.d/erk
+
+    \b
+    You will need to start a new shell for this setup to take effect.
+    """
+    script = ctx.completion.generate_bash()
+    machine_output(script, nl=False)
+
+
+@completion_group.command("zsh")
+@click.pass_obj
+def completion_zsh(ctx: ErkContext) -> None:
+    """Generate zsh completion script.
+
+    \b
+    For automatic setup of both completion and auto-activation:
+      erk init --shell
+
+    \b
+    To load completions in your current shell session:
+      source <(erk completion zsh)
+
+    \b
+    To load completions permanently, add to your ~/.zshrc:
+      echo 'source <(erk completion zsh)' >> ~/.zshrc
+
+    \b
+    Note: Make sure compinit is called in your ~/.zshrc after loading completions.
+
+    \b
+    You will need to start a new shell for this setup to take effect.
+    """
+    script = ctx.completion.generate_zsh()
+    machine_output(script, nl=False)
+
+
+@completion_group.command("fish")
+@click.pass_obj
+def completion_fish(ctx: ErkContext) -> None:
+    """Generate fish completion script.
+
+    \b
+    For automatic setup of both completion and auto-activation:
+      erk init --shell
+
+    \b
+    To load completions in your current shell session:
+      erk completion fish | source
+
+    \b
+    To load completions permanently:
+      mkdir -p ~/.config/fish/completions && \\
+      erk completion fish > ~/.config/fish/completions/erk.fish
+
+    \b
+    You will need to start a new shell for this setup to take effect.
+    """
+    script = ctx.completion.generate_fish()
+    machine_output(script, nl=False)

erk/cli/commands/completions.py

@@ -0,0 +1,165 @@
+"""Shell completion functions for CLI commands.
+
+Separated from navigation_helpers to avoid circular imports.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
+import click
+
+from erk.cli.core import discover_repo_context
+from erk.core.repo_discovery import ensure_erk_metadata_dir
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from erk.core.context import ErkContext
+
+
+@contextmanager
+def shell_completion_context(ctx: click.Context) -> Generator[ErkContext]:
+    """Context manager for shell completion that provides ErkContext with error handling.
+
+    Combines context extraction with graceful error handling for shell completion.
+    Suppresses all exceptions for graceful degradation.
+
+    Why this is needed:
+    - Shell completion runs in the user's interactive shell session
+    - Any uncaught exception would break the shell experience with a Python traceback
+    - Click's shell completion protocol expects functions to return empty lists on error
+    - This allows tab-completion to fail gracefully without disrupting the user
+
+    Why we create ErkContext if ctx.obj is None:
+    - Click's shell completion runs with resilient_parsing=True
+    - This mode skips command callbacks, so the cli() callback that creates ctx.obj never runs
+    - We must create a fresh ErkContext to provide completion data
+
+    Usage:
+        with shell_completion_context(ctx) as erk_ctx:
+            # ... completion logic
+            return completion_candidates
+        return []  # Fallback if exception
+
+    Reference:
+        Click's shell completion protocol:
+        https://click.palletsprojects.com/en/stable/shell-completion/
+    """
+    try:
+        root_ctx = ctx.find_root()
+        erk_ctx = root_ctx.obj
+
+        # Click's resilient_parsing mode skips callbacks, so ctx.obj may be None
+        if erk_ctx is None:
+            from erk.core.context import create_context
+
+            erk_ctx = create_context(dry_run=False)
+
+        yield erk_ctx
+    except Exception:
+        # Suppress exceptions for graceful degradation, but log for debugging
+        # Shell completion should never break the user's shell experience
+        logger.debug("Shell completion error", exc_info=True)
+
+
+def complete_worktree_names(
+    ctx: click.Context, param: click.Parameter | None, incomplete: str
+) -> list[str]:
+    """Shell completion for worktree names. Includes 'root' for the repository root.
+
+    Args:
+        ctx: Click context
+        param: Click parameter (unused, but required by Click's completion protocol)
+        incomplete: Partial input string to complete
+    """
+    with shell_completion_context(ctx) as erk_ctx:
+        repo = discover_repo_context(erk_ctx, erk_ctx.cwd)
+        ensure_erk_metadata_dir(repo)
+
+        names = ["root"] if "root".startswith(incomplete) else []
+
+        # Get worktree names from git_ops instead of filesystem iteration
+        worktrees = erk_ctx.git.list_worktrees(repo.root)
+        for wt in worktrees:
+            if wt.is_root:
+                continue  # Skip root worktree (already added as "root")
+            worktree_name = wt.path.name
+            if worktree_name.startswith(incomplete):
+                names.append(worktree_name)
+
+        return names
+    return []
+
+
+def complete_branch_names(
+    ctx: click.Context, param: click.Parameter | None, incomplete: str
+) -> list[str]:
+    """Shell completion for branch names. Includes both local and remote branches.
+
+    Remote branch names have their remote prefix stripped
+    (e.g., 'origin/feature' becomes 'feature').
+    Duplicates are removed if a branch exists both locally and remotely.
+
+    Args:
+        ctx: Click context
+        param: Click parameter (unused, but required by Click's completion protocol)
+        incomplete: Partial input string to complete
+    """
+    with shell_completion_context(ctx) as erk_ctx:
+        repo = discover_repo_context(erk_ctx, erk_ctx.cwd)
+        ensure_erk_metadata_dir(repo)
+
+        # Collect all branch names in a set for deduplication
+        branch_names = set()
+
+        # Add local branches
+        local_branches = erk_ctx.git.list_local_branches(repo.root)
+        branch_names.update(local_branches)
+
+        # Add remote branches with prefix stripped
+        remote_branches = erk_ctx.git.list_remote_branches(repo.root)
+        for remote_branch in remote_branches:
+            # Strip remote prefix (e.g., 'origin/feature' -> 'feature')
+            if "/" in remote_branch:
+                _, branch_name = remote_branch.split("/", 1)
+                branch_names.add(branch_name)
+            else:
+                # Fallback: if no slash, use as-is
+                branch_names.add(remote_branch)
+
+        # Filter by incomplete prefix and return sorted list
+        matching_branches = [name for name in branch_names if name.startswith(incomplete)]
+        return sorted(matching_branches)
+    return []
+
+
+def complete_plan_files(
+    ctx: click.Context, param: click.Parameter | None, incomplete: str
+) -> list[str]:
+    """Shell completion for plan files (markdown files in current directory).
+
+    Args:
+        ctx: Click context
+        param: Click parameter (unused, but required by Click's completion protocol)
+        incomplete: Partial input string to complete
+
+    Returns:
+        List of completion candidates (filenames matching incomplete text)
+    """
+    with shell_completion_context(ctx) as erk_ctx:
+        # Get current working directory from erk context
+        cwd = erk_ctx.cwd
+
+        # Find all .md files in current directory
+        candidates = []
+        for md_file in cwd.glob("*.md"):
+            # Filter by incomplete prefix if provided
+            if md_file.name.startswith(incomplete):
+                candidates.append(md_file.name)
+
+        return sorted(candidates)
+    return []

erk/cli/commands/config.py

@@ -0,0 +1,327 @@
+import subprocess
+from collections.abc import MutableMapping
+from dataclasses import replace
+from functools import cache
+from pathlib import Path
+from typing import Any, cast
+
+import click
+import tomlkit
+
+from erk.cli.commands.slot.common import DEFAULT_POOL_SIZE
+from erk.cli.config import LoadedConfig
+from erk.cli.core import discover_repo_context
+from erk.cli.ensure import Ensure
+from erk.core.context import ErkContext, write_trunk_to_pyproject
+from erk_shared.output.output import machine_output, user_output
+
+
+@cache
+def get_global_config_keys() -> dict[str, str]:
+    """Get user-exposed global config keys with descriptions.
+
+    Order determines display order in 'erk config list'.
+    shell_setup_complete is internal and not exposed.
+    """
+    return {
+        "erk_root": "Root directory for erk data (~/.erk by default)",
+        "use_graphite": "Enable Graphite integration for stack management",
+        "show_pr_info": "Show PR status in branch listings",
+        "github_planning": "Enable GitHub issues integration for planning",
+        "fix_conflicts_require_dangerous_flag": "Require --dangerous flag for fix-conflicts",
+        "show_hidden_commands": "Show deprecated/hidden commands in help output",
+    }
+
+
+def _get_env_value(cfg: LoadedConfig, parts: list[str], key: str) -> None:
+    """Handle env.* configuration keys.
+
+    Prints the value or exits with error if key not found.
+    """
+    Ensure.invariant(len(parts) == 2, f"Invalid key: {key}")
+    Ensure.invariant(parts[1] in cfg.env, f"Key not found: {key}")
+
+    machine_output(cfg.env[parts[1]])
+
+
+def _get_post_create_value(cfg: LoadedConfig, parts: list[str], key: str) -> None:
+    """Handle post_create.* configuration keys.
+
+    Prints the value or exits with error if key not found.
+    """
+    Ensure.invariant(len(parts) == 2, f"Invalid key: {key}")
+
+    # Handle shell subkey
+    if parts[1] == "shell":
+        Ensure.truthy(cfg.post_create_shell, f"Key not found: {key}")
+        machine_output(cfg.post_create_shell)
+        return
+
+    # Handle commands subkey
+    if parts[1] == "commands":
+        for cmd in cfg.post_create_commands:
+            machine_output(cmd)
+        return
+
+    # Unknown subkey
+    Ensure.invariant(False, f"Key not found: {key}")
+
+
+def _write_pool_max_slots(repo_root: Path, max_slots: int) -> None:
+    """Write pool.max_slots to .erk/config.toml.
+
+    Creates or updates the [pool] section with max_slots setting.
+    Preserves existing formatting and comments using tomlkit.
+
+    Args:
+        repo_root: Path to the repository root directory
+        max_slots: Maximum number of pool slots to configure
+    """
+    config_dir = repo_root / ".erk"
+    config_path = config_dir / "config.toml"
+
+    # Ensure .erk directory exists
+    if not config_dir.exists():
+        config_dir.mkdir(parents=True)
+
+    # Load existing file or create new document
+    if config_path.exists():
+        with config_path.open("r", encoding="utf-8") as f:
+            doc = tomlkit.load(f)
+    else:
+        doc = tomlkit.document()
+
+    # Ensure [pool] section exists
+    if "pool" not in doc:
+        assert isinstance(doc, MutableMapping), f"Expected MutableMapping, got {type(doc)}"
+        cast(dict[str, Any], doc)["pool"] = tomlkit.table()
+
+    # Set max_slots value
+    pool_section = doc["pool"]
+    assert isinstance(pool_section, MutableMapping), type(pool_section)
+    cast(dict[str, Any], pool_section)["max_slots"] = max_slots
+
+    # Write back to file
+    with config_path.open("w", encoding="utf-8") as f:
+        tomlkit.dump(doc, f)
+
+
+@click.group("config")
+def config_group() -> None:
+    """Manage erk configuration."""
+
+
+@config_group.command("keys")
+def config_keys() -> None:
+    """List all available configuration keys with descriptions."""
+    formatter = click.HelpFormatter()
+
+    # Global config section
+    user_output(click.style("Global configuration keys:", bold=True))
+    rows = list(get_global_config_keys().items())
+    formatter.write_dl(rows)
+    user_output(formatter.getvalue().rstrip())
+
+    user_output("")
+
+    # Repository config section
+    user_output(click.style("Repository configuration keys:", bold=True))
+    formatter = click.HelpFormatter()
+    repo_keys = [
+        ("trunk-branch", "The main/master branch name for the repository"),
+        ("pool.max_slots", "Maximum number of pool slots for worktree pool"),
+        ("env.<name>", "Environment variables to set in worktrees"),
+        ("post_create.shell", "Shell to use for post-create commands"),
+        ("post_create.commands", "Commands to run after creating a worktree"),
+    ]
+    formatter.write_dl(repo_keys)
+    user_output(formatter.getvalue().rstrip())
+
+
+def _format_config_value(value: object) -> str:
+    """Format a config value for display."""
+    if isinstance(value, bool):
+        return str(value).lower()
+    return str(value)
+
+
+@config_group.command("list")
+@click.pass_obj
+def config_list(ctx: ErkContext) -> None:
+    """Print a list of configuration keys and values."""
+    # Display global config
+    user_output(click.style("Global configuration:", bold=True))
+    if ctx.global_config:
+        for key in get_global_config_keys():
+            value = getattr(ctx.global_config, key)
+            user_output(f"  {key}={_format_config_value(value)}")
+    else:
+        user_output("  (not configured - run 'erk init' to create)")
+
+    # Display local config
+    user_output(click.style("\nRepository configuration:", bold=True))
+    from erk.core.repo_discovery import NoRepoSentinel
+
+    if isinstance(ctx.repo, NoRepoSentinel):
+        user_output("  (not in a git repository)")
+    else:
+        trunk_branch = ctx.trunk_branch
+        cfg = ctx.local_config
+        if trunk_branch:
+            user_output(f"  trunk-branch={trunk_branch}")
+        if cfg.pool_size is not None:
+            user_output(f"  pool.max_slots={cfg.pool_size}")
+        else:
+            user_output(f"  pool.max_slots={DEFAULT_POOL_SIZE} (default)")
+        if cfg.env:
+            for key, value in cfg.env.items():
+                user_output(f"  env.{key}={value}")
+        if cfg.post_create_shell:
+            user_output(f"  post_create.shell={cfg.post_create_shell}")
+        if cfg.post_create_commands:
+            user_output(f"  post_create.commands={cfg.post_create_commands}")
+
+        has_no_custom_config = (
+            not trunk_branch
+            and cfg.pool_size is None
+            and not cfg.env
+            and not cfg.post_create_shell
+            and not cfg.post_create_commands
+        )
+        if has_no_custom_config:
+            user_output("  (no custom configuration - run 'erk init' to create)")
+
+
+@config_group.command("get")
+@click.argument("key", metavar="KEY")
+@click.pass_obj
+def config_get(ctx: ErkContext, key: str) -> None:
+    """Print the value of a given configuration key."""
+    parts = key.split(".")
+
+    # Handle global config keys
+    if parts[0] in get_global_config_keys():
+        global_config = Ensure.not_none(
+            ctx.global_config, f"Global config not found at {ctx.erk_installation.config_path()}"
+        )
+        value = getattr(global_config, parts[0])
+        machine_output(_format_config_value(value))
+        return
+
+    # Handle repo config keys
+    from erk.core.repo_discovery import NoRepoSentinel
+
+    if isinstance(ctx.repo, NoRepoSentinel):
+        user_output("Not in a git repository")
+        raise SystemExit(1)
+
+    if parts[0] == "trunk-branch":
+        trunk_branch = ctx.trunk_branch
+        if trunk_branch:
+            machine_output(trunk_branch)
+        else:
+            user_output("not configured (will auto-detect)")
+        return
+
+    cfg = ctx.local_config
+
+    if parts[0] == "env":
+        _get_env_value(cfg, parts, key)
+        return
+
+    if parts[0] == "post_create":
+        _get_post_create_value(cfg, parts, key)
+        return
+
+    if parts[0] == "pool" and len(parts) == 2 and parts[1] == "max_slots":
+        if cfg.pool_size is not None:
+            machine_output(str(cfg.pool_size))
+        else:
+            machine_output(f"{DEFAULT_POOL_SIZE} (default)")
+        return
+
+    user_output(f"Invalid key: {key}")
+    raise SystemExit(1)
+
+
+def _parse_config_value(key: str, value: str, current_type: type) -> object:
+    """Parse a string value to the appropriate type for a config key."""
+    if current_type is bool:
+        if value.lower() not in ("true", "false"):
+            user_output(f"Invalid boolean value: {value}")
+            raise SystemExit(1)
+        return value.lower() == "true"
+    if current_type is Path or key == "erk_root":
+        return Path(value).expanduser().resolve()
+    return value
+
+
+@config_group.command("set")
+@click.argument("key", metavar="KEY")
+@click.argument("value", metavar="VALUE")
+@click.pass_obj
+def config_set(ctx: ErkContext, key: str, value: str) -> None:
+    """Update configuration with a value for the given key."""
+    # Parse key into parts
+    parts = key.split(".")
+
+    # Handle global config keys
+    if parts[0] in get_global_config_keys():
+        config_path = ctx.erk_installation.config_path()
+        global_config = Ensure.not_none(
+            ctx.global_config,
+            f"Global config not found at {config_path}. Run 'erk init' to create it.",
+        )
+
+        # Get current value's type and parse new value
+        current_value = getattr(global_config, parts[0])
+        parsed_value = _parse_config_value(parts[0], value, type(current_value))
+
+        # Create new config with updated value using dataclasses.replace
+        new_config = replace(global_config, **{parts[0]: parsed_value})
+
+        ctx.erk_installation.save_config(new_config)
+        user_output(f"Set {key}={value}")
+        return
+
+    # Handle repo config keys
+    if parts[0] == "trunk-branch":
+        # discover_repo_context checks for git repository and raises FileNotFoundError
+        repo = discover_repo_context(ctx, Path.cwd())
+
+        # Validate that the branch exists before writing
+        result = subprocess.run(
+            ["git", "rev-parse", "--verify", value],
+            cwd=repo.root,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        Ensure.invariant(
+            result.returncode == 0,
+            f"Branch '{value}' doesn't exist in repository.\n"
+            f"Create the branch first before configuring it as trunk.",
+        )
+
+        # Write configuration
+        write_trunk_to_pyproject(repo.root, value)
+        user_output(f"Set trunk-branch={value}")
+        return
+
+    # Handle pool.max_slots
+    if parts[0] == "pool" and len(parts) == 2 and parts[1] == "max_slots":
+        repo = discover_repo_context(ctx, Path.cwd())
+
+        # Validate value is a positive integer
+        if not value.isdigit() or int(value) < 1:
+            user_output(f"Invalid value: {value}. pool.max_slots must be a positive integer.")
+            raise SystemExit(1)
+
+        pool_size = int(value)
+        _write_pool_max_slots(repo.root, pool_size)
+        user_output(f"Set pool.max_slots={pool_size}")
+        return
+
+    # Other repo config keys not implemented yet
+    user_output(f"Invalid key: {key}")
+    raise SystemExit(1)

erk/cli/commands/docs/__init__.py

@@ -0,0 +1 @@
+"""Agent documentation command group."""

erk/cli/commands/docs/group.py

@@ -0,0 +1,16 @@
+"""Agent documentation command group."""
+
+import click
+
+from erk.cli.commands.docs.sync import sync_command
+from erk.cli.commands.docs.validate import validate_command
+
+
+@click.group(name="docs")
+def docs_group() -> None:
+    """Manage and validate agent documentation."""
+
+
+# Register commands
+docs_group.add_command(sync_command)
+docs_group.add_command(validate_command)