hop3-cli 0.4.0b1__tar.gz

hop3_cli-0.4.0b1/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.3
+Name: hop3-cli
+Version: 0.4.0b1
+Summary: 
+Author: Stefane Fermigier
+Author-email: Stefane Fermigier <sf@abilian.com>
+License: MIT
+Requires-Dist: toml>=0.10.2,<1.0.0
+Requires-Dist: jsonrpcclient>=4.0.3,<5.0.0
+Requires-Dist: requests>=2.32.3,<3.0.0
+Requires-Dist: tabulate>=0.9.0,<1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sshtunnel>=0.4.0
+Requires-Dist: paramiko>=2.11.0,<3.0.0
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pathspec>=0.12.1
+Requires-Dist: platformdirs>=4.3.8
+Requires-Python: >=3.10, <4.0
+Description-Content-Type: text/markdown
+
+# hop3-cli
+
+Command-line interface for interacting with Hop3 servers.
+
+## Overview
+
+hop3-cli is a thin client that communicates with hop3-server via JSON-RPC over HTTP or SSH tunneling. It provides a familiar Heroku-like CLI experience for deploying and managing applications.
+
+## Features
+
+- **Application management** - Deploy, start, stop, restart, and scale applications
+- **Environment variables** - Securely manage app configuration
+- **Log streaming** - View real-time application logs
+- **Addon management** - Provision and manage backing services (PostgreSQL, Redis, MySQL)
+- **SSH tunneling** - Secure communication with remote servers
+- **Multiple output formats** - Human-readable, JSON, or quiet mode
+
+## Installation
+
+### From PyPI (end users)
+
+```bash
+pip install hop3-cli
+```
+
+### For development
+
+```bash
+# From workspace root
+cd packages/hop3-cli
+uv pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```bash
+# Configure server connection
+export HOP3_SERVER_URL="https://hop3.example.com"
+# Or use SSH tunneling
+export HOP3_SERVER="user@hop3.example.com"
+
+# Authenticate
+hop3 auth login
+
+# Deploy an application
+cd my-app
+hop3 deploy
+
+# View logs
+hop3 logs my-app
+
+# List applications
+hop3 apps
+```
+
+## Configuration
+
+Configuration can be set via environment variables or config file (`~/.config/hop3/config.toml`).
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HOP3_SERVER_URL` | Server URL (HTTP mode) | - |
+| `HOP3_SERVER` | Server hostname (SSH mode) | - |
+| `HOP3_AUTH_TOKEN` | Authentication token | - |
+| `HOP3_CONFIG_DIR` | Config directory | `~/.config/hop3` |
+
+## Architecture
+
+```
+hop3-cli/
+├── src/hop3_cli/
+│   ├── main.py          # Entry point, argument parsing
+│   ├── config.py        # Configuration management
+│   ├── tunnel.py        # SSH tunnel management
+│   ├── rpc/
+│   │   └── client.py    # JSON-RPC client
+│   ├── commands/
+│   │   ├── local.py     # Local commands (init, config)
+│   │   └── help.py      # Help system
+│   └── ui/
+│       ├── console.py   # Output formatting
+│       └── prompts.py   # Interactive prompts
+└── tests/
+```
+
+**Communication flow:**
+```
+User → CLI → [SSH Tunnel] → HTTP → hop3-server → JSON-RPC response → CLI → User
+```
+
+## Development
+
+### Running tests
+
+```bash
+# From package directory
+uv run pytest tests/ -v
+
+# With coverage
+uv run pytest tests/ --cov=hop3_cli
+```
+
+### Code quality
+
+```bash
+# Lint
+uv run ruff check src/
+
+# Format
+uv run ruff format src/
+
+# Type check
+uv run pyright src/
+```
+
+## Documentation
+
+- **User Guide**: [Main documentation](../../docs/src/guide.md)
+- **CLI Reference**: [Command reference](../../docs/src/cli-reference.md)
+- **System Architecture**: [Architecture overview](../../docs/src/dev/architecture.md)
+- **Package Internals**: [Deep-dive documentation](./docs/internals.md)
+
+## Related Packages
+
+- [hop3-server](../hop3-server/) - The server that hop3-cli communicates with
+- [hop3-tui](../hop3-tui/) - Alternative terminal UI interface
+
+## License
+
+Apache-2.0 - Copyright (c) 2024-2025, Abilian SAS

hop3_cli-0.4.0b1/README.md

@@ -0,0 +1,130 @@
+# hop3-cli
+
+Command-line interface for interacting with Hop3 servers.
+
+## Overview
+
+hop3-cli is a thin client that communicates with hop3-server via JSON-RPC over HTTP or SSH tunneling. It provides a familiar Heroku-like CLI experience for deploying and managing applications.
+
+## Features
+
+- **Application management** - Deploy, start, stop, restart, and scale applications
+- **Environment variables** - Securely manage app configuration
+- **Log streaming** - View real-time application logs
+- **Addon management** - Provision and manage backing services (PostgreSQL, Redis, MySQL)
+- **SSH tunneling** - Secure communication with remote servers
+- **Multiple output formats** - Human-readable, JSON, or quiet mode
+
+## Installation
+
+### From PyPI (end users)
+
+```bash
+pip install hop3-cli
+```
+
+### For development
+
+```bash
+# From workspace root
+cd packages/hop3-cli
+uv pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```bash
+# Configure server connection
+export HOP3_SERVER_URL="https://hop3.example.com"
+# Or use SSH tunneling
+export HOP3_SERVER="user@hop3.example.com"
+
+# Authenticate
+hop3 auth login
+
+# Deploy an application
+cd my-app
+hop3 deploy
+
+# View logs
+hop3 logs my-app
+
+# List applications
+hop3 apps
+```
+
+## Configuration
+
+Configuration can be set via environment variables or config file (`~/.config/hop3/config.toml`).
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HOP3_SERVER_URL` | Server URL (HTTP mode) | - |
+| `HOP3_SERVER` | Server hostname (SSH mode) | - |
+| `HOP3_AUTH_TOKEN` | Authentication token | - |
+| `HOP3_CONFIG_DIR` | Config directory | `~/.config/hop3` |
+
+## Architecture
+
+```
+hop3-cli/
+├── src/hop3_cli/
+│   ├── main.py          # Entry point, argument parsing
+│   ├── config.py        # Configuration management
+│   ├── tunnel.py        # SSH tunnel management
+│   ├── rpc/
+│   │   └── client.py    # JSON-RPC client
+│   ├── commands/
+│   │   ├── local.py     # Local commands (init, config)
+│   │   └── help.py      # Help system
+│   └── ui/
+│       ├── console.py   # Output formatting
+│       └── prompts.py   # Interactive prompts
+└── tests/
+```
+
+**Communication flow:**
+```
+User → CLI → [SSH Tunnel] → HTTP → hop3-server → JSON-RPC response → CLI → User
+```
+
+## Development
+
+### Running tests
+
+```bash
+# From package directory
+uv run pytest tests/ -v
+
+# With coverage
+uv run pytest tests/ --cov=hop3_cli
+```
+
+### Code quality
+
+```bash
+# Lint
+uv run ruff check src/
+
+# Format
+uv run ruff format src/
+
+# Type check
+uv run pyright src/
+```
+
+## Documentation
+
+- **User Guide**: [Main documentation](../../docs/src/guide.md)
+- **CLI Reference**: [Command reference](../../docs/src/cli-reference.md)
+- **System Architecture**: [Architecture overview](../../docs/src/dev/architecture.md)
+- **Package Internals**: [Deep-dive documentation](./docs/internals.md)
+
+## Related Packages
+
+- [hop3-server](../hop3-server/) - The server that hop3-cli communicates with
+- [hop3-tui](../hop3-tui/) - Alternative terminal UI interface
+
+## License
+
+Apache-2.0 - Copyright (c) 2024-2025, Abilian SAS

hop3_cli-0.4.0b1/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "hop3-cli"
+version = "0.4.0.beta1"
+authors = [
+    {name = "Stefane Fermigier", email = "sf@abilian.com"},
+]
+license = {text = "MIT"}
+requires-python = "<4.0,>=3.10"
+dependencies = [
+    # Configuration
+    "toml<1.0.0,>=0.10.2",
+    # Communication
+    "jsonrpcclient<5.0.0,>=4.0.3",
+    "requests<3.0.0,>=2.32.3",
+    # Presentation
+    "tabulate<1.0.0,>=0.9.0",
+    "rich>=13.0.0",  # Rich formatting, tables, progress bars, colors
+    # SSH tunneling - pin paramiko to 2.x for DSS key compatibility with sshtunnel
+    "sshtunnel>=0.4.0",
+    "paramiko>=2.11.0,<3.0.0",
+    "loguru>=0.7.3",
+    "pathspec>=0.12.1",
+    "platformdirs>=4.3.8",
+]
+description = ""
+readme = "README.md"
+
+[project.scripts]
+hop = "hop3_cli.main:main"
+hop3 = "hop3_cli.main:main"
+
+# ----------------------------------------
+
+[build-system]
+requires = ["uv-build>=0.8.4,<0.9.0"]
+build-backend = "uv_build"
+
+
+[tool.pytest.ini_options]
+filterwarnings = [
+    # paramiko uses TripleDES which cryptography has deprecated
+    "ignore:TripleDES has been moved:cryptography.utils.CryptographyDeprecationWarning",
+]
+
+# Was:
+#[build-system]
+#requires = ["pdm-backend"]
+#build-backend = "pdm.backend"
+#
+#[tool.pdm.build]
+#includes = ["src/hop3_cli"]

hop3_cli-0.4.0b1/src/hop3_cli/__init__.py

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

hop3_cli-0.4.0b1/src/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-0.4.0b1/src/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-0.4.0b1/src/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?")