hop3-cli 0.4.0__py3-none-any.whl

hop3_cli/__init__.py

@@ -0,0 +1 @@
+# Copyright (c) 2023-2025, Abilian SAS

hop3_cli/commands/__init__.py

@@ -0,0 +1,47 @@
+# Copyright (c) 2025, Abilian SAS
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Command processing for the Hop3 CLI.
+
+This package handles command parsing and local command execution:
+- local: Commands handled locally without server RPC
+- help: Help flag handling and help output injection
+- destructive: Confirmation prompts for destructive commands
+- flags: CLI flag parsing (--json, --quiet, -y, etc.)
+- arguments: Argument generation (e.g., deploy archive)
+"""
+
+from __future__ import annotations
+
+from .arguments import generate_archive, get_extra_args, pack_repository
+from .destructive import confirm_destructive_action, is_destructive_command
+from .flags import CliFlags, parse_flags
+from .help import (
+    handle_help_flags,
+    inject_local_commands_into_help,
+    is_help_command,
+)
+from .local import (
+    LOCAL_COMMANDS,
+    LOCAL_COMMANDS_INFO,
+    handle_local_command,
+    is_local_command,
+)
+
+__all__ = [
+    "LOCAL_COMMANDS",
+    "LOCAL_COMMANDS_INFO",
+    "CliFlags",
+    "confirm_destructive_action",
+    "generate_archive",
+    "get_extra_args",
+    "handle_help_flags",
+    "handle_local_command",
+    "inject_local_commands_into_help",
+    "is_destructive_command",
+    "is_help_command",
+    "is_local_command",
+    "pack_repository",
+    "parse_flags",
+]

hop3_cli/commands/arguments.py

@@ -0,0 +1,455 @@
+# Copyright (c) 2025, Abilian SAS
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Argument generation for CLI commands."""
+
+from __future__ import annotations
+
+import base64
+import io
+import sys
+import tarfile
+from collections import Counter
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pathspec
+
+if TYPE_CHECKING:
+    from hop3_cli.types import JsonDict
+
+__all__ = ["generate_archive", "get_extra_args", "pack_repository"]
+
+# tomllib is stdlib in Python 3.11+, use toml package for 3.10
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import toml as tomllib
+
+# Archive size limits (in bytes)
+# Soft limit: warn the user but proceed
+# Hard limit: refuse to upload (can be overridden on server)
+SOFT_SIZE_LIMIT = 100 * 1024 * 1024  # 100 MB
+HARD_SIZE_LIMIT = 1024 * 1024 * 1024  # 1 GB
+
+# Ignore files in priority order (first found is used)
+IGNORE_FILES = [".hop3ignore", ".dockerignore", ".gitignore"]
+
+
+def get_extra_args(args: list[str], verbosity: int = 1) -> JsonDict:
+    """Generate a dictionary of extra arguments for RPC commands.
+
+    Args:
+        args: Command-line arguments
+        verbosity: Verbosity level (0=quiet, 1=normal, 2=verbose, 3=debug)
+
+    Returns:
+        Dictionary with extra arguments. Verbosity is always included as it's
+        used by the server to set the logging context for all commands.
+    """
+    # Always include verbosity - server extracts it and uses it as context
+    extra_args: JsonDict = {"verbosity": verbosity}
+
+    if not args:
+        return extra_args
+
+    command = args[0]
+
+    match command:
+        case "deploy":
+            # Parse deploy-specific flags
+            # args[0]="deploy", args[1]=app_name, remaining args may include --env and directory
+            env_vars, remaining_args, streaming = _parse_deploy_args(args[1:])
+
+            # Skip expensive archive generation if no app name provided
+            # Let the server return a proper usage error instead
+            if not remaining_args:
+                return extra_args
+
+            # Directory is the last non-flag argument (if any)
+            directory = Path(remaining_args[-1]) if len(remaining_args) > 1 else Path()
+            extra_args["repository"] = pack_repository(directory, verbosity=verbosity)
+
+            # Include env vars if any were specified
+            if env_vars:
+                extra_args["env_vars"] = env_vars  # type: ignore[assignment]  # pyrefly: ignore
+
+            # Enable streaming by default for real-time log output
+            extra_args["streaming"] = streaming
+
+    return extra_args
+
+
+def _parse_deploy_args(args: list[str]) -> tuple[dict[str, str], list[str], bool]:
+    """Parse deploy command arguments, extracting --env and --no-stream flags.
+
+    Args:
+        args: Arguments after 'deploy' command (app_name, --env flags, directory)
+
+    Returns:
+        Tuple of (env_vars dict, remaining args, streaming enabled)
+
+    Example:
+        >>> _parse_deploy_args(['myapp', '--env', 'FOO=bar', '--env', 'BAZ=qux', '.'])
+        ({'FOO': 'bar', 'BAZ': 'qux'}, ['myapp', '.'], True)
+        >>> _parse_deploy_args(['myapp', '--no-stream'])
+        ({}, ['myapp'], False)
+    """
+    env_vars: dict[str, str] = {}
+    remaining: list[str] = []
+    streaming = True  # Enabled by default
+    i = 0
+
+    while i < len(args):
+        arg = args[i]
+
+        if arg in {"--env", "-e"}:
+            # Next argument should be KEY=VALUE
+            if i + 1 < len(args):
+                env_spec = args[i + 1]
+                if "=" in env_spec:
+                    key, _, value = env_spec.partition("=")
+                    env_vars[key] = value
+                i += 2
+            else:
+                i += 1  # Skip malformed --env without value
+        elif arg.startswith("--env="):
+            # Handle --env=KEY=VALUE format
+            env_spec = arg[6:]  # Remove --env=
+            if "=" in env_spec:
+                key, _, value = env_spec.partition("=")
+                env_vars[key] = value
+            i += 1
+        elif arg == "--no-stream":
+            # Disable real-time streaming (fallback to batch output)
+            streaming = False
+            i += 1
+        elif arg == "--stream":
+            # Explicitly enable streaming (default, but allow explicit)
+            streaming = True
+            i += 1
+        else:
+            remaining.append(arg)
+            i += 1
+
+    return env_vars, remaining, streaming
+
+
+def pack_repository(directory: Path = Path(), verbosity: int = 1) -> str:
+    """Pack a directory into a base64-encoded tar.gz archive.
+
+    Args:
+        directory: Directory to pack (defaults to current directory)
+        verbosity: Verbosity level (0=quiet, 1=normal, 2+=verbose)
+
+    Returns:
+        Base64-encoded tar.gz archive
+    """
+    tar_gz = generate_archive(directory, verbosity=verbosity)
+    return base64.b64encode(tar_gz).decode("ascii")
+
+
+def generate_archive(source_dir: Path, verbosity: int = 1) -> bytes:
+    """
+    Creates an in-memory tar.gz archive of a source directory as a bytes object,
+    excluding files and directories specified in ignore files.
+
+    Ignore files are checked in priority order: .hop3ignore, .dockerignore, .gitignore
+
+    Args:
+        source_dir: The path to the directory to archive.
+        verbosity: Verbosity level (0=quiet, 1=normal, 2+=verbose)
+
+    Returns:
+        The content of the .tar.gz archive as a bytes object.
+
+    Raises:
+        ValueError: If the source_dir is not a valid directory or has too many files.
+        FileNotFoundError: If the source_dir does not exist.
+    """
+    source_dir = Path(source_dir).resolve()
+    verbose = verbosity >= 2
+
+    if not source_dir.exists():
+        msg = (
+            f"Directory not found: {source_dir}\n\n"
+            f"Make sure you are in the directory containing your application code,\n"
+            f"or specify the path as the last argument:\n"
+            f"  hop3 deploy <app_name> /path/to/app"
+        )
+        raise FileNotFoundError(msg)
+    if not source_dir.is_dir():
+        msg = f"Path is not a directory: {source_dir}"
+        raise ValueError(msg)
+
+    # Check if directory looks like an application
+    _check_directory_is_app(source_dir, verbose)
+
+    if verbose:
+        print(f"Creating archive from: {source_dir}", file=sys.stderr)
+
+    # --- 1. Load ignore rules (.hop3ignore, .dockerignore, or .gitignore) ---
+    spec, ignore_file = get_ignored_spec(source_dir)
+    if verbose:
+        if ignore_file:
+            print(f"Using ignore patterns from: {ignore_file}", file=sys.stderr)
+        else:
+            print(
+                "No ignore file found (.hop3ignore, .dockerignore, .gitignore)",
+                file=sys.stderr,
+            )
+
+    # --- 2. Walk the directory and gather files to include ---
+    if verbose:
+        print("Scanning files...", file=sys.stderr)
+    files_to_add = get_files_to_add(source_dir, spec)
+
+    # --- 3. Log file count ---
+    file_count = len(files_to_add)
+    if verbose:
+        print(f"Found {file_count} files to archive", file=sys.stderr)
+
+    # --- 4. Create the tar.gz archive in memory ---
+    if verbose:
+        print("Creating archive...", file=sys.stderr)
+
+    fileobj = io.BytesIO()
+
+    # The 'w:gz' mode creates a gzip-compressed tar file.
+    # We pass our BytesIO object as the file to write to.
+    with tarfile.open(fileobj=fileobj, mode="w:gz") as tar:
+        for file_path in files_to_add:
+            relative_path = file_path.relative_to(source_dir)
+            arcname = Path() / relative_path
+            tar.add(file_path, arcname=str(arcname))
+
+    archive_bytes = fileobj.getvalue()
+    _check_archive_size(archive_bytes, files_to_add, source_dir, verbose)
+
+    return archive_bytes
+
+
+def _check_archive_size(
+    archive_bytes: bytes,
+    files: list[Path],
+    source_dir: Path,
+    verbose: bool,
+) -> None:
+    """Check archive size against soft and hard limits.
+
+    Args:
+        archive_bytes: The archive content
+        files: List of files in the archive (for diagnostics)
+        source_dir: Source directory (for computing relative paths)
+        verbose: Whether to print verbose output
+    """
+    archive_size = len(archive_bytes)
+    size_mb = archive_size / (1024 * 1024)
+
+    if verbose:
+        print(f"Archive created: {size_mb:.2f} MB", file=sys.stderr)
+
+    if archive_size > HARD_SIZE_LIMIT:
+        top_dirs = _get_top_directories_by_file_count(files, source_dir)
+        dir_summary = "\n".join(f"  {d}: {c} files" for d, c in top_dirs[:5])
+        hard_limit_mb = HARD_SIZE_LIMIT / (1024 * 1024)
+
+        msg = (
+            f"Archive too large: {size_mb:.1f} MB exceeds the {hard_limit_mb:.0f} MB limit.\n"
+            f"\n"
+            f"Directories with most files:\n"
+            f"{dir_summary}\n"
+            f"\n"
+            f"Add directories to .hop3ignore to exclude them from deployment.\n"
+            f"The server may also have configurable size limits."
+        )
+        raise ValueError(msg)
+
+    if archive_size > SOFT_SIZE_LIMIT:
+        soft_limit_mb = SOFT_SIZE_LIMIT / (1024 * 1024)
+        print(
+            f"Warning: Large archive ({size_mb:.1f} MB). "
+            f"Uploads over {soft_limit_mb:.0f} MB may be slow.",
+            file=sys.stderr,
+        )
+
+
+def get_ignored_spec(source_dir: Path) -> tuple[pathspec.PathSpec | None, str | None]:
+    """Load ignore rules from a directory.
+
+    Checks sources in priority order:
+    1. [build].ignore patterns in hop3.toml
+    2. [build].ignore-file reference in hop3.toml
+    3. .hop3ignore file
+    4. .dockerignore file
+    5. .gitignore file
+
+    The first source found with patterns is used.
+
+    Returns:
+        Tuple of (PathSpec or None, source description or None)
+    """
+    # 1. Check hop3.toml for inline ignore patterns or ignore-file reference
+    hop3_toml_spec, hop3_toml_source = _get_hop3_toml_ignore_spec(source_dir)
+    if hop3_toml_spec is not None:
+        return hop3_toml_spec, hop3_toml_source
+
+    # 2. Fall back to ignore files in priority order
+    for ignore_file in IGNORE_FILES:
+        ignore_path = source_dir / ignore_file
+        if ignore_path.is_file():
+            lines = ignore_path.read_text(encoding="utf-8").splitlines()
+            spec = pathspec.PathSpec.from_lines("gitignore", lines)  # pyrefly: ignore
+            return spec, ignore_file
+
+    return None, None
+
+
+def _get_hop3_toml_ignore_spec(
+    source_dir: Path,
+) -> tuple[pathspec.PathSpec | None, str | None]:
+    """Extract ignore patterns from hop3.toml if present.
+
+    Checks for:
+    1. [build].ignore - inline list of patterns
+    2. [build].ignore-file - reference to an ignore file
+
+    Returns:
+        Tuple of (PathSpec or None, source description or None)
+    """
+    # Check for hop3.toml in standard locations
+    hop3_toml_paths = [
+        source_dir / "hop3" / "hop3.toml",
+        source_dir / "hop3.toml",
+    ]
+
+    for hop3_toml_path in hop3_toml_paths:
+        if not hop3_toml_path.is_file():
+            continue
+
+        try:
+            content = hop3_toml_path.read_text(encoding="utf-8")
+            data = tomllib.loads(content)
+        except Exception:
+            # If TOML parsing fails, skip and try next location
+            continue
+
+        build_section = data.get("build", {})
+        if not isinstance(build_section, dict):
+            continue
+
+        # Check for inline ignore patterns
+        ignore_patterns = build_section.get("ignore")
+        if ignore_patterns and isinstance(ignore_patterns, list):
+            spec = pathspec.PathSpec.from_lines("gitignore", ignore_patterns)
+            return spec, f"hop3.toml [build].ignore ({len(ignore_patterns)} patterns)"
+
+        # Check for ignore-file reference
+        ignore_file_ref = build_section.get("ignore-file")
+        if ignore_file_ref and isinstance(ignore_file_ref, str):
+            ignore_file_path = source_dir / ignore_file_ref
+            if ignore_file_path.is_file():
+                lines = ignore_file_path.read_text(encoding="utf-8").splitlines()
+                spec = pathspec.PathSpec.from_lines("gitignore", lines)  # pyrefly: ignore
+                return spec, f"hop3.toml [build].ignore-file -> {ignore_file_ref}"
+
+    return None, None
+
+
+def _get_top_directories_by_file_count(
+    files: list[Path], source_dir: Path
+) -> list[tuple[str, int]]:
+    """Get the top-level directories sorted by file count.
+
+    Args:
+        files: List of file paths
+        source_dir: The source directory (for computing relative paths)
+
+    Returns:
+        List of (directory_name, file_count) tuples, sorted by count descending
+    """
+    dir_counts: Counter[str] = Counter()
+    for f in files:
+        rel = f.relative_to(source_dir)
+        # Get top-level directory, or "(root)" for files in root
+        top_dir = rel.parts[0] if len(rel.parts) > 1 else "(root)"
+        dir_counts[top_dir] += 1
+
+    return dir_counts.most_common()
+
+
+def _check_directory_is_app(source_dir: Path, verbose: bool) -> None:
+    """Check if the directory looks like an application and warn if not.
+
+    Args:
+        source_dir: The directory to check
+        verbose: Whether to print verbose output
+    """
+    # Common app indicators
+    app_indicators = [
+        "Procfile",
+        "hop3.toml",
+        "package.json",
+        "requirements.txt",
+        "pyproject.toml",
+        "Cargo.toml",
+        "go.mod",
+        "Gemfile",
+        "composer.json",
+        "pom.xml",
+        "build.gradle",
+        "Makefile",
+        "Dockerfile",
+        "docker-compose.yml",
+        "docker-compose.yaml",
+        "index.html",
+        "index.php",
+    ]
+
+    has_indicator = any((source_dir / f).exists() for f in app_indicators)
+
+    if not has_indicator:
+        # Check if directory has any files at all
+        files = list(source_dir.iterdir())
+        if not files:
+            msg = (
+                f"Directory is empty: {source_dir}\n\n"
+                f"The deploy command expects a directory containing your application code.\n"
+                f"Make sure you are in the correct directory."
+            )
+            raise ValueError(msg)
+
+        # Directory has files but no recognizable app structure
+        if verbose:
+            print(
+                f"Warning: No recognized application files found in {source_dir}\n"
+                f"Expected one of: {', '.join(app_indicators[:5])}...\n"
+                f"Proceeding anyway - the server will attempt to deploy.",
+                file=sys.stderr,
+            )
+
+
+def get_files_to_add(source_dir: Path, spec: pathspec.PathSpec | None) -> list[Path]:
+    """Get list of files to add to archive, excluding gitignored files."""
+    files_to_add: list[Path] = []
+    for file_path in source_dir.rglob("*"):
+        relative_path = file_path.relative_to(source_dir)
+        relative_str = str(relative_path)
+
+        # Always exclude .git directory (not deployment material)
+        if relative_str.startswith(".git") and (
+            relative_str == ".git" or relative_str.startswith(".git/")
+        ):
+            continue
+
+        # Let pathspec determine if the file should be ignored
+        if spec and spec.match_file(relative_str):
+            continue
+
+        # We only add files to the tar, not directories
+        if not file_path.is_file():
+            continue
+
+        files_to_add.append(file_path)
+    return files_to_add

hop3_cli/commands/destructive.py

@@ -0,0 +1,191 @@
+# Copyright (c) 2025, Abilian SAS
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Destructive command handling and confirmation prompts."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from hop3_cli.ui.prompts import confirm, show_destructive_warning, type_to_confirm
+
+if TYPE_CHECKING:
+    from hop3_cli.config import Config
+    from hop3_cli.ui.rich_printer import RichPrinter
+
+
+def is_destructive_command(cli_args: list[str]) -> bool:
+    """Check if the command is destructive (requires confirmation).
+
+    Args:
+        cli_args: Command-line arguments
+
+    Returns:
+        True if command is destructive, False otherwise
+    """
+    if not cli_args:
+        return False
+
+    command = cli_args[0]
+
+    # List of destructive commands that require confirmation
+    destructive_commands = {
+        "app:destroy",
+        "destroy",  # Alias for app:destroy
+        "backup:delete",
+        "services:destroy",
+    }
+
+    return command in destructive_commands
+
+
+def _confirm_protected_context(config: Config | None) -> tuple[bool, str | None]:
+    """Check if context is protected and confirm if needed.
+
+    Returns:
+        Tuple of (is_protected, context_name).
+        Returns (False, None) if user cancelled the confirmation.
+    """
+    if not config:
+        return False, None
+
+    is_protected = config.is_protected_context()
+    context_name = config.get_current_context_name()
+
+    if not is_protected:
+        return False, context_name
+
+    # Show extra warning for protected contexts
+    print(f"\n  WARNING: You are operating on protected context '{context_name}'")
+    print("  This context is marked as protected to prevent accidental changes.\n")
+
+    if not confirm("Are you sure you want to continue with this destructive action?"):
+        # Signal cancellation by returning special value
+        return True, None  # is_protected=True but context_name=None means cancelled
+
+    return True, context_name
+
+
+def confirm_destructive_action(
+    cli_args: list[str], printer: RichPrinter, config: Config | None = None
+) -> bool:
+    """Prompt user to confirm a destructive action.
+
+    For protected contexts, extra confirmation is required.
+
+    Args:
+        cli_args: Command-line arguments
+        printer: Printer for output (for JSON mode detection)
+        config: Configuration for checking protected context (optional)
+
+    Returns:
+        True if user confirmed, False if cancelled
+    """
+    if printer.json_output:
+        # In JSON mode, auto-confirm (user should use -y flag)
+        return True
+
+    command = cli_args[0]
+    args = cli_args[1:]
+
+    # Check if required arguments are present BEFORE any confirmation prompts
+    # If missing, let the server handle the error message
+    if not _has_required_args(command, args):
+        return True
+
+    # Check if this is a protected context
+    is_protected, context_name = _confirm_protected_context(config)
+    if is_protected and context_name is None:
+        # User cancelled protected context confirmation
+        return False
+
+    # app:destroy or destroy command - requires type-to-confirm
+    if command in {"app:destroy", "destroy"}:
+        return _confirm_app_destroy(args, is_protected, context_name)
+
+    # backup:delete command
+    if command == "backup:delete":
+        return _confirm_backup_delete(args)
+
+    # services:destroy command
+    if command == "services:destroy":
+        return _confirm_service_destroy(args, is_protected, context_name)
+
+    # Unknown destructive command (shouldn't happen)
+    return confirm("This action cannot be undone. Continue?")
+
+
+def _has_required_args(command: str, args: list[str]) -> bool:
+    """Check if a destructive command has its required arguments.
+
+    Args:
+        command: The command name
+        args: The arguments (excluding the command itself)
+
+    Returns:
+        True if required args are present, False otherwise
+    """
+    # Commands that require at least one argument (the target name)
+    commands_requiring_target = {
+        "app:destroy",
+        "destroy",
+        "backup:delete",
+        "services:destroy",
+    }
+
+    if command in commands_requiring_target:
+        return len(args) >= 1
+
+    return True
+
+
+def _confirm_app_destroy(
+    args: list[str], is_protected: bool, context_name: str | None
+) -> bool:
+    """Confirm app:destroy command."""
+    app_name = args[0]
+    show_destructive_warning(
+        "destroy",
+        f"app '{app_name}'",
+        "All files, data, and configuration will be permanently deleted.",
+    )
+
+    # For protected contexts, require typing context name AND app name
+    if is_protected and context_name:
+        confirm_text = f"{context_name}/{app_name}"
+        return type_to_confirm(
+            f"Type '{confirm_text}' to confirm (context/app):", confirm_text
+        )
+    return type_to_confirm(f"Type '{app_name}' to confirm:", app_name)
+
+
+def _confirm_backup_delete(args: list[str]) -> bool:
+    """Confirm backup:delete command."""
+    backup_id = args[0]
+    show_destructive_warning(
+        "delete",
+        f"backup '{backup_id}'",
+        "This backup cannot be recovered once deleted.",
+    )
+    return confirm("Are you sure you want to delete this backup?")
+
+
+def _confirm_service_destroy(
+    args: list[str], is_protected: bool, context_name: str | None
+) -> bool:
+    """Confirm services:destroy command."""
+    addon_name = args[0]
+    show_destructive_warning(
+        "destroy",
+        f"service '{addon_name}'",
+        "All data in this service will be permanently deleted.",
+    )
+
+    # For protected contexts, require typing context name AND service name
+    if is_protected and context_name:
+        confirm_text = f"{context_name}/{addon_name}"
+        return type_to_confirm(
+            f"Type '{confirm_text}' to confirm (context/service):", confirm_text
+        )
+    return type_to_confirm(f"Type '{addon_name}' to confirm:", addon_name)