hop3-cli 0.5.0.dev3__tar.gz → 0.6.0__tar.gz

{hop3_cli-0.5.0.dev3 → hop3_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hop3-cli
-Version: 0.5.0.dev3
+Version: 0.6.0
 Summary: 
 Author: Stefane Fermigier
 Author-email: Stefane Fermigier <sf@abilian.com>
@@ -57,9 +57,9 @@ hop3 apps
 hop3 use myapp
 
 # From here on, app-scoped commands resolve myapp automatically:
-hop3 logs
+hop3 app logs
 hop3 config set KEY=value
-hop3 restart
+hop3 app restart
 ```
 
 ## App Resolution
@@ -79,7 +79,7 @@ Use `hop3 --why <command>` to print the full trace and see which source won. `--
 
 ```bash
 # Explicit (always works):
-hop3 logs --app myapp
+hop3 app logs --app myapp
 hop3 config set --app myapp KEY=value
 
 # Per-shell:

{hop3_cli-0.5.0.dev3 → hop3_cli-0.6.0}/README.md

@@ -37,9 +37,9 @@ hop3 apps
 hop3 use myapp
 
 # From here on, app-scoped commands resolve myapp automatically:
-hop3 logs
+hop3 app logs
 hop3 config set KEY=value
-hop3 restart
+hop3 app restart
 ```
 
 ## App Resolution
@@ -59,7 +59,7 @@ Use `hop3 --why <command>` to print the full trace and see which source won. `--
 
 ```bash
 # Explicit (always works):
-hop3 logs --app myapp
+hop3 app logs --app myapp
 hop3 config set --app myapp KEY=value
 
 # Per-shell:

{hop3_cli-0.5.0.dev3 → hop3_cli-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hop3-cli"
-version = "0.5.0.dev3"
+version = "0.6.0"
 authors = [
     {name = "Stefane Fermigier", email = "sf@abilian.com"},
 ]

{hop3_cli-0.5.0.dev3 → hop3_cli-0.6.0}/src/hop3_cli/commands/__init__.py

@@ -19,6 +19,7 @@ from .destructive import confirm_destructive_action, is_destructive_command
 from .flags import CliFlags, parse_flags
 from .help import (
     append_feedback_footer,
+    append_local_commands_full_help,
     emit_status_line,
     handle_help_flags,
     inject_local_commands_into_help,
@@ -36,6 +37,7 @@ __all__ = [
     "LOCAL_COMMANDS_INFO",
     "CliFlags",
     "append_feedback_footer",
+    "append_local_commands_full_help",
     "confirm_destructive_action",
     "emit_status_line",
     "generate_archive",

{hop3_cli-0.5.0.dev3 → hop3_cli-0.6.0}/src/hop3_cli/commands/arguments.py

@@ -10,31 +10,67 @@ import base64
 import io
 import sys
 import tarfile
-from collections import Counter
+from operator import itemgetter
 from pathlib import Path
 from typing import TYPE_CHECKING
 
 import pathspec
 
+from hop3_cli.core.hop3_toml import read_hop3_toml
+
 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"]
+# The server's documented default upload limit (Litestar request_max_body_size
+# and nginx client_max_body_size). The real limit is server-configured, but at
+# this size a deploy is likely to be rejected with HTTP 413 — warn loudly and
+# show what's big, before wasting the upload. ponytail: hardcoded default; a
+# future /rpc capability handshake could report the server's actual limit.
+DEFAULT_SERVER_UPLOAD_LIMIT = 200 * 1024 * 1024  # 200 MB
+
+# What the `hop3 deploy` upload always excludes, regardless of deployment
+# method: VCS metadata, OS/IDE cruft, and dependency/build caches the server
+# regenerates (the toolchain runs npm/pip install; the venv is built
+# server-side). Per-app additions go in hop3.toml [build].ignore (ADR 046 §5).
+#
+# Deliberately NOT consulted for this upload:
+#   - .gitignore     governs the git-push deploy path only, not this upload.
+#   - .dockerignore  scopes the server-side `docker build` context (Docker
+#                    applies it there); e.g. Quarkus ships `*` + a target/
+#                    allowlist, which would gut the upload if honored here.
+_DEFAULT_IGNORE_PATTERNS = [
+    ".git/",
+    ".hg/",
+    ".svn/",
+    ".DS_Store",
+    ".idea/",
+    "__pycache__/",
+    "*.py[cod]",
+    "*.egg-info/",
+    ".venv/",
+    "venv/",
+    "node_modules/",
+    # Compiled-language build output, rebuilt server-side and never deployed.
+    # `target/` is both Rust's (cargo) and Java/Maven's output dir; cargo
+    # hardlinks the release binary into target/release/deps/, which the
+    # server's safe-extract refuses — and it is hundreds of MB. Same rationale
+    # as node_modules/.venv above.
+    "target/",
+    ".mypy_cache/",
+    ".pytest_cache/",
+    ".ruff_cache/",
+]
+
+# Deprecated Hop3-specific sidecar, superseded by hop3.toml [build].ignore.
+# Honored for one transition release with a loud warning, then removed (ADR 046).
+_DEPRECATED_IGNORE_FILE = ".hop3ignore"
 
 
 def get_extra_args(args: list[str], verbosity: int = 1) -> JsonDict:
@@ -67,17 +103,12 @@ def get_extra_args(args: list[str], verbosity: int = 1) -> JsonDict:
 
     match command:
         case "deploy":
-            # Parse deploy-specific flags
-            # args[0]="deploy", args[1]=app_name, remaining args may include --env and directory
+            # The app is the `--app` flag (ADR 036 D5), stripped by
+            # _parse_deploy_args — so `remaining_args` is just an optional source
+            # directory (default: the current 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()
+            directory = Path(remaining_args[0]) if remaining_args else Path()
             extra_args["repository"] = pack_repository(directory, verbosity=verbosity)
 
             # Include env vars if any were specified
@@ -87,9 +118,32 @@ def get_extra_args(args: list[str], verbosity: int = 1) -> JsonDict:
             # Enable streaming by default for real-time log output
             extra_args["streaming"] = streaming
 
+        case "addon":
+            # `addon <type> import <name> < dump.sql`: ship the piped dump to
+            # the server as a base64 blob (same approach as deploy's upload).
+            if len(args) >= 3 and args[2] == "import":
+                import_data = _read_import_data()
+                if import_data is not None:
+                    extra_args["import_data"] = import_data
+
     return extra_args
 
 
+def _read_import_data() -> str | None:
+    """Read a dump piped on stdin and base64-encode it for transport.
+
+    Returns None when stdin is a terminal (no dump piped) or empty, so the
+    server can emit a clear "pipe a dump" error instead of the CLI hanging on
+    a read from an interactive terminal.
+    """
+    if sys.stdin.isatty():
+        return None
+    raw = sys.stdin.buffer.read()
+    if not raw:
+        return None
+    return base64.b64encode(raw).decode("ascii")
+
+
 def _resolve_run_input(args: list[str]) -> None:
     """Resolve --input -/@path on `hop run` so the server gets literal bytes.
 
@@ -267,6 +321,12 @@ def _parse_deploy_args(args: list[str]) -> tuple[dict[str, str], list[str], bool
             # Explicitly enable streaming (default, but allow explicit)
             streaming = True
             i += 1
+        elif arg in {"--app", "-a"}:
+            # The app is a flag, not a positional (ADR 036 D5). Skip it (and its
+            # value) so it never gets mistaken for the source directory below.
+            i += 2 if i + 1 < len(args) else 1
+        elif arg.startswith(("--app=", "-a=")):
+            i += 1
         else:
             remaining.append(arg)
             i += 1
@@ -291,9 +351,8 @@ def pack_repository(directory: Path = Path(), verbosity: int = 1) -> str:
 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
+    excluding built-in defaults plus the app's hop3.toml [build].ignore patterns
+    (ADR 046 §5). .gitignore and .dockerignore are not consulted for this upload.
 
     Args:
         source_dir: The path to the directory to archive.
@@ -314,7 +373,7 @@ def generate_archive(source_dir: Path, verbosity: int = 1) -> bytes:
             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"
+            f"  hop3 deploy --app <app> /path/to/app"
         )
         raise FileNotFoundError(msg)
     if not source_dir.is_dir():
@@ -327,16 +386,10 @@ def generate_archive(source_dir: Path, verbosity: int = 1) -> bytes:
     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)
+    # --- 1. Load ignore rules (built-in defaults + hop3.toml [build].ignore) ---
+    spec, ignore_source = 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,
-            )
+        print(f"Using ignore patterns from: {ignore_source}", file=sys.stderr)
 
     # --- 2. Walk the directory and gather files to include ---
     if verbose:
@@ -389,22 +442,35 @@ def _check_archive_size(
         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])
+        dir_summary = _largest_dirs_summary(files, source_dir)
         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"Largest entries:\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."
+            f"Run 'hop3 deploy --dry-run' to see the full archive manifest.\n"
+            f"Add patterns to the [build].ignore list in hop3.toml to exclude\n"
+            f"them from deployment. The server may also have configurable size limits."
         )
         raise ValueError(msg)
 
-    if archive_size > SOFT_SIZE_LIMIT:
+    if archive_size > DEFAULT_SERVER_UPLOAD_LIMIT:
+        dir_summary = _largest_dirs_summary(files, source_dir)
+        limit_mb = DEFAULT_SERVER_UPLOAD_LIMIT / (1024 * 1024)
+        print(
+            f"Warning: archive ({size_mb:.1f} MB) exceeds the default server "
+            f"upload limit ({limit_mb:.0f} MB); the deploy will likely be "
+            f"rejected (HTTP 413).\n"
+            f"Largest entries:\n{dir_summary}\n"
+            f"Run 'hop3 deploy --dry-run' to see the full manifest. Exclude large "
+            f"entries via [build].ignore in hop3.toml, or ask the server admin to "
+            f"raise the limit.",
+            file=sys.stderr,
+        )
+    elif archive_size > SOFT_SIZE_LIMIT:
         soft_limit_mb = SOFT_SIZE_LIMIT / (1024 * 1024)
         print(
             f"Warning: Large archive ({size_mb:.1f} MB). "
@@ -413,108 +479,135 @@ def _check_archive_size(
         )
 
 
-def get_ignored_spec(source_dir: Path) -> tuple[pathspec.PathSpec | None, str | None]:
-    """Load ignore rules from a directory.
+def get_ignored_spec(source_dir: Path) -> tuple[pathspec.PathSpec, str]:
+    """Build the ignore spec for the `hop3 deploy` upload.
+
+    The upload always excludes a built-in set of never-deploy paths
+    (`_DEFAULT_IGNORE_PATTERNS`), extended by the canonical per-app source:
 
-    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
+    1. hop3.toml ``[build].ignore`` — the declarative ignore list (ADR 046 §5).
+    2. ``.hop3ignore`` — DEPRECATED sidecar, still honored for one release with
+       a loud warning; move its patterns into ``[build].ignore``.
 
-    The first source found with patterns is used.
+    ``.gitignore`` (git-push path) and ``.dockerignore`` (server-side
+    ``docker build``) are intentionally NOT consulted here.
 
     Returns:
-        Tuple of (PathSpec or None, source description or None)
+        Tuple of (PathSpec, human-readable description of the pattern sources).
     """
-    # 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
+    patterns = list(_DEFAULT_IGNORE_PATTERNS)
+    sources = ["built-in defaults"]
 
-    # 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
+    build_ignore = _get_build_ignore_patterns(source_dir)
+    if build_ignore is not None:
+        patterns.extend(build_ignore)
+        sources.append(f"hop3.toml [build].ignore ({len(build_ignore)} patterns)")
+    else:
+        deprecated = source_dir / _DEPRECATED_IGNORE_FILE
+        if deprecated.is_file():
+            patterns.extend(deprecated.read_text(encoding="utf-8").splitlines())
+            sources.append(f"{_DEPRECATED_IGNORE_FILE} (deprecated)")
+            print(
+                f"Warning: {_DEPRECATED_IGNORE_FILE} is deprecated and will stop "
+                f"being read in a future release. Move its patterns into the "
+                f"[build].ignore list in hop3.toml.",
+                file=sys.stderr,
+            )
 
+    spec = pathspec.PathSpec.from_lines("gitignore", patterns)  # pyrefly: ignore
+    return spec, ", ".join(sources)
 
-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
+def _get_build_ignore_patterns(source_dir: Path) -> list[str] | None:
+    """Return hop3.toml ``[build].ignore`` patterns, or None if not declared.
 
-    Returns:
-        Tuple of (PathSpec or None, source description or None)
+    Reads the app's hop3.toml from the standard locations. ``[build].ignore`` is
+    the canonical, declarative ignore list for the deploy upload (ADR 046 §5);
+    the legacy ``[build].ignore-file`` pointer is no longer supported.
     """
-    # Check for hop3.toml in standard locations
-    hop3_toml_paths = [
+    for hop3_toml_path in (
         source_dir / "hop3" / "hop3.toml",
         source_dir / "hop3.toml",
-    ]
-
-    for hop3_toml_path in hop3_toml_paths:
-        if not hop3_toml_path.is_file():
+    ):
+        # read_hop3_toml returns {} for a missing or unparseable file.
+        build_section = read_hop3_toml(hop3_toml_path).get("build", {})
+        if not isinstance(build_section, dict):
             continue
+        patterns = build_section.get("ignore")
+        if isinstance(patterns, list) and patterns:
+            return [str(p) for p in patterns]
+    return None
 
-        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
+def _human_size(num_bytes: int) -> str:
+    """Format a byte count as a short human-readable size (e.g. '207.8 MB')."""
+    size = float(num_bytes)
+    for unit in ("B", "KB", "MB"):
+        if size < 1024:
+            return f"{size:.0f} {unit}" if unit == "B" else f"{size:.1f} {unit}"
+        size /= 1024
+    return f"{size:.1f} GB"
 
-        # 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}"
+def _aggregate_by_top_dir(
+    sized_files: list[tuple[Path, int]], source_dir: Path
+) -> list[tuple[str, int]]:
+    """Total upload size per top-level entry, largest first.
 
-    return None, None
+    Size (not file count) is what matters for the 413 limit, and a top-level
+    entry is what you'd actually add to [build].ignore.
+    """
+    dir_sizes: dict[str, int] = {}
+    for f, size in sized_files:
+        rel = f.relative_to(source_dir)
+        top = rel.parts[0] if len(rel.parts) > 1 else "(root)"
+        dir_sizes[top] = dir_sizes.get(top, 0) + size
+    return sorted(dir_sizes.items(), key=itemgetter(1), reverse=True)
 
 
-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.
+def _largest_dirs_summary(files: list[Path], source_dir: Path, n: int = 5) -> str:
+    """A few-line summary of the largest top-level entries, by size."""
+    sized = [(f, f.stat().st_size) for f in files]
+    top = _aggregate_by_top_dir(sized, source_dir)[:n]
+    return "\n".join(f"  {_human_size(sz):>10}  {name}" for name, sz in top)
 
-    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
+def describe_archive(source_dir: Path) -> str:
+    """Human-readable manifest of what `hop3 deploy` would upload.
+
+    Walks the source, applies the SAME ignore rules as the real upload, and
+    reports the total size, the ignore rules in effect, and the largest
+    directories and files — so the user can see exactly what's in the archive
+    (and what to add to [build].ignore) instead of guessing. Stats only; does
+    not build the tarball.
     """
-    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
+    spec, sources = get_ignored_spec(source_dir)
+    files = get_files_to_add(source_dir, spec)
+    sized = [(f, f.stat().st_size) for f in files]
+    total = sum(size for _, size in sized)
+
+    lines = [
+        (
+            f"Deploy archive: {_human_size(total)} across {len(files)} files "
+            f"(uncompressed; the upload itself is gzipped)."
+        ),
+        f"Ignore rules: {sources}.",
+    ]
+
+    top_dirs = _aggregate_by_top_dir(sized, source_dir)
+    if top_dirs:
+        lines.append("\nLargest entries:")
+        lines += [f"  {_human_size(sz):>10}  {name}" for name, sz in top_dirs[:10]]
 
-    return dir_counts.most_common()
+    largest = sorted(sized, key=itemgetter(1), reverse=True)[:15]
+    if largest:
+        lines.append("\nLargest files:")
+        lines += [
+            f"  {_human_size(sz):>10}  {f.relative_to(source_dir)}" for f, sz in largest
+        ]
+
+    lines.append("\nTo shrink it, add large entries to [build].ignore in hop3.toml.")
+    return "\n".join(lines)
 
 
 def _check_directory_is_app(source_dir: Path, verbose: bool) -> None:
@@ -568,21 +661,16 @@ def _check_directory_is_app(source_dir: Path, verbose: bool) -> None:
             )
 
 
-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."""
+def get_files_to_add(source_dir: Path, spec: pathspec.PathSpec) -> list[Path]:
+    """Get list of files to add to archive, excluding ignored 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):
+        # Let pathspec determine if the file should be ignored (.git/ and other
+        # never-deploy paths are in _DEFAULT_IGNORE_PATTERNS).
+        if spec.match_file(relative_str):
             continue
 
         # We only add files to the tar, not directories