hop3-cli 0.4.0b1__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,190 @@
+# 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 tarfile
+from pathlib import Path
+
+import pathspec
+
+from hop3_cli.types import JsonDict
+
+__all__ = ["generate_archive", "get_extra_args", "pack_repository"]
+
+
+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 = _parse_deploy_args(args[1:])
+
+            # 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)
+
+            # Include env vars if any were specified
+            if env_vars:
+                extra_args["env_vars"] = env_vars
+
+    return extra_args
+
+
+def _parse_deploy_args(args: list[str]) -> tuple[dict[str, str], list[str]]:
+    """Parse deploy command arguments, extracting --env flags.
+
+    Args:
+        args: Arguments after 'deploy' command (app_name, --env flags, directory)
+
+    Returns:
+        Tuple of (env_vars dict, remaining args without --env flags)
+
+    Example:
+        >>> _parse_deploy_args(['myapp', '--env', 'FOO=bar', '--env', 'BAZ=qux', '.'])
+        ({'FOO': 'bar', 'BAZ': 'qux'}, ['myapp', '.'])
+    """
+    env_vars: dict[str, str] = {}
+    remaining: list[str] = []
+    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
+        else:
+            remaining.append(arg)
+            i += 1
+
+    return env_vars, remaining
+
+
+def pack_repository(directory: Path = Path()) -> str:
+    """Pack a directory into a base64-encoded tar.gz archive.
+
+    Args:
+        directory: Directory to pack (defaults to current directory)
+
+    Returns:
+        Base64-encoded tar.gz archive
+    """
+    tar_gz = generate_archive(directory)
+    return base64.b64encode(tar_gz).decode("ascii")
+
+
+def generate_archive(source_dir: Path) -> bytes:
+    """
+    Creates an in-memory tar.gz archive of a source directory as a bytes object,
+    excluding files and directories specified in a .gitignore file.
+
+    Args:
+        source_dir: The path to the directory to archive.
+
+    Returns:
+        The content of the .tar.gz archive as a bytes object.
+
+    Raises:
+        ValueError: If the source_dir is not a valid directory.
+        FileNotFoundError: If the source_dir does not exist.
+    """
+    source_dir = Path(source_dir).resolve()
+
+    if not source_dir.exists():
+        msg = f"Source directory not found: {source_dir}"
+        raise FileNotFoundError(msg)
+    if not source_dir.is_dir():
+        msg = f"Source path is not a directory: {source_dir}"
+        raise ValueError(msg)
+
+    # --- 1. Load .gitignore rules ---
+    spec = get_ignored_spec(source_dir)
+
+    # --- 2. Walk the directory and gather files to include ---
+    files_to_add = get_files_to_add(source_dir, spec)
+
+    # --- 3. Create the tar.gz archive in memory ---
+    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))
+
+    return fileobj.getvalue()
+
+
+def get_ignored_spec(source_dir: Path) -> pathspec.PathSpec | None:
+    """Load .gitignore rules from a directory."""
+    gitignore_path = source_dir / ".gitignore"
+    spec: pathspec.PathSpec | None = None
+    if gitignore_path.is_file():
+        with gitignore_path.open(encoding="utf-8") as f:
+            spec = pathspec.PathSpec.from_lines("gitignore", f)
+    return spec
+
+
+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,100 @@
+# 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.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_destructive_action(cli_args: list[str], printer: RichPrinter) -> bool:
+    """Prompt user to confirm a destructive action.
+
+    Args:
+        cli_args: Command-line arguments
+        printer: Printer for output (for JSON mode detection)
+
+    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:]
+
+    # app:destroy or destroy command - requires type-to-confirm
+    if command in {"app:destroy", "destroy"}:
+        if not args:
+            # No app name provided, let server handle error
+            return True
+
+        app_name = args[0]
+        show_destructive_warning(
+            "destroy",
+            f"app '{app_name}'",
+            "All files, data, and configuration will be permanently deleted.",
+        )
+        return type_to_confirm(f"Type '{app_name}' to confirm:", app_name)
+
+    # backup:delete command
+    if command == "backup:delete":
+        if not args:
+            return True
+
+        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?")
+
+    # services:destroy command
+    if command == "services:destroy":
+        if not args:
+            return True
+
+        addon_name = args[0]
+        show_destructive_warning(
+            "destroy",
+            f"service '{addon_name}'",
+            "All data in this service will be permanently deleted.",
+        )
+        return type_to_confirm(f"Type '{addon_name}' to confirm:", addon_name)
+
+    # Unknown destructive command (shouldn't happen)
+    return confirm("This action cannot be undone. Continue?")

hop3_cli/commands/flags.py

@@ -0,0 +1,122 @@
+# Copyright (c) 2023-2025, Abilian SAS
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""CLI flag parsing and handling."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+def _get_env_verbosity() -> int | None:
+    """Get verbosity from HOP3_VERBOSITY environment variable.
+
+    Returns:
+        Verbosity level (0-3) or None if not set or invalid
+    """
+    env_val = os.environ.get("HOP3_VERBOSITY", "").strip()
+    if not env_val:
+        return None
+    try:
+        level = int(env_val)
+        return max(0, min(3, level))  # Clamp to 0-3
+    except ValueError:
+        return None
+
+
+@dataclass(frozen=True)
+class CliFlags:
+    """CLI flags that control output and behavior."""
+
+    json_output: bool = False  # --json, -j: Machine-readable JSON output
+    skip_confirm: bool = False  # -y, --yes, --force: Skip confirmation prompts
+
+    # Verbosity is now stored as a level (0=quiet, 1=normal, 2=verbose, 3=debug)
+    # This allows -vv, -vvv, -qq, etc.
+    verbosity: int = field(default_factory=lambda: _get_env_verbosity() or 1)
+
+    @property
+    def quiet(self) -> bool:
+        """True if verbosity is 0 (quiet mode)."""
+        return self.verbosity == 0
+
+    @property
+    def verbose(self) -> bool:
+        """True if verbosity is 2 or higher (verbose mode)."""
+        return self.verbosity >= 2
+
+    @property
+    def debug(self) -> bool:
+        """True if verbosity is 3 (debug mode)."""
+        return self.verbosity >= 3
+
+
+def parse_flags(args: list[str]) -> tuple[CliFlags, list[str]]:
+    """Parse CLI flags from arguments and return flags + remaining args.
+
+    Supports:
+        --json, -j: Machine-readable JSON output
+        -y, --yes, --force: Skip confirmation prompts
+        -v, --verbose: Increase verbosity (can stack: -vv, -vvv)
+        -q, --quiet: Decrease verbosity (can stack: -qq)
+        --debug: Maximum verbosity (level 3)
+
+    Environment variable:
+        HOP3_VERBOSITY: Set default verbosity level (0-3)
+
+    Args:
+        args: Command-line arguments (e.g., ['deploy', 'my-app', '--json', '-y'])
+
+    Returns:
+        Tuple of (CliFlags, remaining_args)
+        remaining_args has flags removed
+
+    Examples:
+        >>> parse_flags(['deploy', 'my-app', '--json'])
+        (CliFlags(json_output=True, ...), ['deploy', 'my-app'])
+
+        >>> parse_flags(['destroy', 'my-app', '-y', '-vv'])
+        (CliFlags(verbosity=3, skip_confirm=True, ...), ['destroy', 'my-app'])
+    """
+    json_output = False
+    skip_confirm = False
+
+    # Start with environment default or normal (1)
+    verbosity = _get_env_verbosity() or 1
+
+    # Flags to recognize
+    json_flags = {"--json", "-j"}
+    yes_flags = {"-y", "--yes", "--force"}
+
+    # Filter out flags from args
+    remaining_args = []
+    for arg in args:
+        if arg in json_flags:
+            json_output = True
+        elif arg in yes_flags:
+            skip_confirm = True
+        elif arg == "--debug":
+            verbosity = 3
+        elif arg == "--verbose":
+            verbosity = max(verbosity, 2)
+        elif arg == "--quiet":
+            verbosity = 0
+        elif arg.startswith("-") and all(c == "v" for c in arg[1:]):
+            # Handle -v, -vv, -vvv
+            verbosity = min(3, 1 + len(arg) - 1)  # -v=2, -vv=3, -vvv=3
+        elif arg.startswith("-") and all(c == "q" for c in arg[1:]):
+            # Handle -q, -qq (but -q is enough for quiet=0)
+            verbosity = 0
+        else:
+            # Not a flag, keep it
+            remaining_args.append(arg)
+
+    flags = CliFlags(
+        json_output=json_output,
+        skip_confirm=skip_confirm,
+        verbosity=verbosity,
+    )
+
+    return flags, remaining_args

hop3_cli/commands/help.py

@@ -0,0 +1,182 @@
+# Copyright (c) 2025, Abilian SAS
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Help flag handling and help output injection."""
+
+from __future__ import annotations
+
+from .local import LOCAL_COMMANDS_INFO
+
+
+def handle_help_flags(args: list[str]) -> list[str]:
+    """Convert --help/-h flags to help command invocations.
+
+    Examples:
+        ["--help"] -> ["help"]
+        ["-h"] -> ["help"]
+        ["run", "--help"] -> ["help", "run"]
+        ["run", "-h"] -> ["help", "run"]
+        ["run", "myapp", "--help"] -> ["help", "run"]  # help for run, not run with --help
+
+    Args:
+        args: Command-line arguments
+
+    Returns:
+        Modified arguments with --help converted to help command
+    """
+    if not args:
+        return args
+
+    # Handle --version and -V flags
+    if "--version" in args or "-V" in args:
+        return ["version"]
+
+    # Check if --help or -h is anywhere in the args
+    if "--help" in args or "-h" in args:
+        # Remove --help and -h from args
+        filtered_args = [arg for arg in args if arg not in {"--help", "-h"}]
+
+        if not filtered_args:
+            # Just "--help" with no command -> show general help
+            return ["help"]
+        # "command --help" -> "help command"
+        # Only use the first argument as the command name
+        return ["help", filtered_args[0]]
+
+    return args
+
+
+def is_help_command(cli_args: list[str]) -> bool:
+    """Check if this is a help command (with or without --all flag).
+
+    Args:
+        cli_args: Command-line arguments
+
+    Returns:
+        True if this is a help command that should have local commands injected
+    """
+    if not cli_args:
+        return False
+    # Match "help" or "help --all" but not "help <command>"
+    if cli_args[0] != "help":
+        return False
+    # "help" alone or "help --all"
+    return len(cli_args) == 1 or cli_args == ["help", "--all"]
+
+
+def inject_local_commands_into_help(result: list[dict]) -> list[dict]:
+    """Inject local CLI commands into the help output from the server.
+
+    Local commands (init, login, settings) are handled by the CLI and don't
+    exist on the server, so we add them to help output for discoverability.
+
+    Args:
+        result: The help response from the server
+
+    Returns:
+        Modified result with local commands injected alphabetically
+    """
+    modified_result = []
+    for item in result:
+        if item.get("t") != "text":
+            modified_result.append(item)
+            continue
+
+        text = item.get("text", "")
+        if "\n" in text and "COMMANDS" in text:
+            new_text = _process_help_text_with_local_commands(text, LOCAL_COMMANDS_INFO)
+            modified_result.append({"t": "text", "text": new_text})
+        else:
+            modified_result.append(item)
+
+    return modified_result
+
+
+def _process_help_text_with_local_commands(
+    text: str,
+    local_commands: dict[str, str],
+) -> str:
+    """Process help text and inject local commands into COMMANDS section."""
+    lines = text.split("\n")
+    new_lines = []
+    in_commands_section = False
+    injected: set[str] = set()
+
+    for line in lines:
+        if line.strip() in {"COMMANDS", "ALL COMMANDS"}:
+            in_commands_section = True
+            new_lines.append(line)
+            continue
+
+        if in_commands_section and line.strip() and not line.startswith("  "):
+            # Leaving COMMANDS section - inject remaining commands first
+            new_lines.extend(_inject_remaining_commands(local_commands, injected))
+            in_commands_section = False
+
+        if in_commands_section and _is_command_line(line):
+            current_cmd = _get_command_name(line)
+            if current_cmd:
+                new_lines.extend(
+                    _inject_commands_before(current_cmd, local_commands, injected)
+                )
+
+        new_lines.append(line)
+
+    # If still in commands section at end, inject remaining
+    if in_commands_section:
+        remaining = _inject_remaining_commands(local_commands, injected)
+        if remaining:
+            # Insert after last command line
+            insert_idx = len(new_lines)
+            for i in range(len(new_lines) - 1, -1, -1):
+                if _is_command_line(new_lines[i]):
+                    insert_idx = i + 1
+                    break
+            for j, cmd_line in enumerate(remaining):
+                new_lines.insert(insert_idx + j, cmd_line)
+
+    return "\n".join(new_lines)
+
+
+def _inject_remaining_commands(
+    local_commands: dict[str, str],
+    injected: set[str],
+) -> list[str]:
+    """Return all local commands not yet injected."""
+    lines = []
+    for cmd in sorted(local_commands.keys()):
+        if cmd not in injected:
+            lines.append(_format_help_command(cmd, local_commands[cmd]))
+            injected.add(cmd)
+    return lines
+
+
+def _is_command_line(line: str) -> bool:
+    """Check if a line is a command entry (indented, non-empty)."""
+    return line.startswith("  ") and bool(line.strip())
+
+
+def _get_command_name(line: str) -> str | None:
+    """Extract command name from a help line."""
+    parts = line.strip().split(None, 1)
+    return parts[0] if parts else None
+
+
+def _inject_commands_before(
+    current_cmd: str,
+    local_commands: dict[str, str],
+    injected: set[str],
+) -> list[str]:
+    """Return local commands that should appear before current_cmd alphabetically."""
+    lines = []
+    for cmd in sorted(local_commands.keys()):
+        if cmd not in injected and cmd < current_cmd:
+            lines.append(_format_help_command(cmd, local_commands[cmd]))
+            injected.add(cmd)
+    return lines
+
+
+def _format_help_command(name: str, description: str) -> str:
+    """Format a command entry for help output."""
+    return f"  {name:16} {description}"