earthforge-cli 0.1.0__tar.gz

earthforge_cli-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Claude
+.claude/

earthforge_cli-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: earthforge-cli
+Version: 0.1.0
+Summary: EarthForge CLI — thin Typer dispatch layer for cloud-native geospatial operations
+License-Expression: GPL-3.0-or-later
+Requires-Python: >=3.11
+Requires-Dist: earthforge-core>=0.1.0
+Requires-Dist: textual>=0.52
+Requires-Dist: typer>=0.9
+Description-Content-Type: text/markdown
+
+# earthforge-cli
+
+Typer-based CLI for EarthForge — thin dispatch layer with no business logic.
+
+See the [main README](../../README.md) for project documentation.

earthforge_cli-0.1.0/README.md

@@ -0,0 +1,5 @@
+# earthforge-cli
+
+Typer-based CLI for EarthForge — thin dispatch layer with no business logic.
+
+See the [main README](../../README.md) for project documentation.

earthforge_cli-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "earthforge-cli"
+version = "0.1.0"
+description = "EarthForge CLI — thin Typer dispatch layer for cloud-native geospatial operations"
+readme = "README.md"
+license = "GPL-3.0-or-later"
+requires-python = ">=3.11"
+dependencies = [
+    "earthforge-core>=0.1.0",
+    "typer>=0.9",
+    "textual>=0.52",
+]
+
+[project.scripts]
+earthforge = "earthforge.cli.main:app"
+tf = "earthforge.cli.main:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/earthforge"]

earthforge_cli-0.1.0/src/earthforge/cli/__init__.py

@@ -0,0 +1,6 @@
+"""EarthForge CLI — thin dispatch layer for cloud-native geospatial operations.
+
+This package contains NO business logic. Every command handler parses arguments,
+calls an async library function via ``asyncio.run()``, and passes the result to
+the output renderer. That's it.
+"""

earthforge_cli-0.1.0/src/earthforge/cli/commands/__init__.py

@@ -0,0 +1,5 @@
+"""EarthForge CLI command modules.
+
+Each module in this package defines one or more Typer command handlers.
+Handlers are thin: parse args → call async library function → render output.
+"""

earthforge_cli-0.1.0/src/earthforge/cli/commands/bench_cmd.py

@@ -0,0 +1,215 @@
+"""EarthForge ``bench`` command group — performance benchmarks.
+
+Measures I/O and query performance for EarthForge operations and reports
+timing, throughput, and comparison baselines. Results are emitted as a
+structured table or JSON for CI performance tracking.
+
+Available benchmarks
+--------------------
+vector-query
+    Compares GeoParquet bbox query (with predicate pushdown) against a
+    full sequential scan of the same data. Reports rows returned, elapsed
+    time, and estimated data read ratio.
+
+raster-info
+    Measures round-trip time for COG header reads via HTTP range requests.
+    Reports bytes transferred and time to first metadata.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any
+
+import typer
+from pydantic import BaseModel, Field
+
+from earthforge.core.output import render_to_console
+
+app = typer.Typer(
+    name="bench",
+    help="Run EarthForge performance benchmarks.",
+    no_args_is_help=True,
+)
+
+
+class BenchResult(BaseModel):
+    """Structured result for a single benchmark run.
+
+    Attributes:
+        benchmark: Name of the benchmark (e.g. ``"vector-query"``).
+        description: Human-readable description of what was measured.
+        runs: Number of timed repetitions.
+        results: Per-run timing and metric data.
+        summary: Aggregated summary (min/mean/max elapsed, comparison).
+    """
+
+    benchmark: str = Field(title="Benchmark")
+    description: str = Field(title="Description")
+    runs: int = Field(title="Runs")
+    results: list[dict[str, Any]] = Field(default_factory=list, title="Results")
+    summary: dict[str, Any] = Field(default_factory=dict, title="Summary")
+
+
+def _stats(times: list[float]) -> dict[str, float]:
+    """Compute min/mean/max for a list of elapsed times."""
+    return {
+        "min_s": round(min(times), 4),
+        "mean_s": round(sum(times) / len(times), 4),
+        "max_s": round(max(times), 4),
+    }
+
+
+def vector_query(
+    ctx: typer.Context,
+    source: str = typer.Argument(
+        help="Path to a GeoParquet file to benchmark against.",
+    ),
+    bbox: str = typer.Option(
+        "-85.5,37.0,-84.0,38.5",
+        "--bbox",
+        help="Bounding box for the query benchmark: west,south,east,north.",
+    ),
+    runs: int = typer.Option(
+        3,
+        "--runs",
+        "-n",
+        help="Number of timed repetitions per method.",
+    ),
+) -> None:
+    """Benchmark GeoParquet bbox query — predicate pushdown vs. full scan.
+
+    Runs the same spatial query twice: once using EarthForge's predicate
+    pushdown path (reads only intersecting row groups) and once by loading
+    the entire file and filtering in Python. Reports timing and data read
+    ratios for both methods.
+    """
+    from earthforge.cli.main import get_state
+
+    state = get_state(ctx)
+
+    parts = [float(v.strip()) for v in bbox.split(",")]
+    if len(parts) != 4:
+        typer.echo("Error: --bbox requires west,south,east,north", err=True)
+        raise typer.Exit(code=1)
+    bbox_tuple = (parts[0], parts[1], parts[2], parts[3])
+
+    async def _run_bench() -> BenchResult:
+        from pathlib import Path
+
+        try:
+            import geopandas as gpd
+            import pyarrow.parquet as pq
+        except ImportError as exc:
+            typer.echo(f"Error: geopandas and pyarrow required for bench: {exc}", err=True)
+            raise typer.Exit(code=1) from exc
+
+        from earthforge.vector.query import query_features
+
+        file_size = Path(source).stat().st_size
+
+        pushdown_times: list[float] = []
+        fullscan_times: list[float] = []
+        pushdown_rows = 0
+        fullscan_rows = 0
+
+        for _ in range(runs):
+            # Method 1: EarthForge predicate pushdown
+            t0 = time.perf_counter()
+            result = await query_features(source, bbox=list(bbox_tuple))
+            pushdown_times.append(time.perf_counter() - t0)
+            pushdown_rows = result.feature_count
+
+            # Method 2: Full scan — load all, filter in Python
+            t0 = time.perf_counter()
+            gdf = gpd.read_parquet(source)
+            west, south, east, north = bbox_tuple
+            _ = gdf.cx[west:east, south:north]  # type: ignore[misc]
+            fullscan_times.append(time.perf_counter() - t0)
+            fullscan_rows = len(_)
+
+        # Estimate row groups read by pushdown (pyarrow metadata)
+        pf = pq.ParquetFile(source)
+        total_row_groups = pf.metadata.num_row_groups
+
+        speedup = (
+            round(sum(fullscan_times) / sum(pushdown_times), 2) if sum(pushdown_times) > 0 else 0.0
+        )
+
+        return BenchResult(
+            benchmark="vector-query",
+            description=(
+                f"GeoParquet bbox query: pushdown vs. full scan "
+                f"({file_size:,} bytes, {total_row_groups} row groups)"
+            ),
+            runs=runs,
+            results=[
+                {
+                    "method": "earthforge predicate pushdown",
+                    "rows_returned": pushdown_rows,
+                    **_stats(pushdown_times),
+                },
+                {
+                    "method": "geopandas full scan",
+                    "rows_returned": fullscan_rows,
+                    **_stats(fullscan_times),
+                },
+            ],
+            summary={
+                "file_size_bytes": file_size,
+                "total_row_groups": total_row_groups,
+                "pushdown_speedup_x": speedup,
+                "bbox": list(bbox_tuple),
+            },
+        )
+
+    result = asyncio.run(_run_bench())
+    render_to_console(result, state.output, no_color=state.no_color)
+
+
+def raster_info(
+    ctx: typer.Context,
+    source: str = typer.Argument(
+        help="URL or path to a COG to benchmark header read time.",
+    ),
+    runs: int = typer.Option(
+        3,
+        "--runs",
+        "-n",
+        help="Number of timed repetitions.",
+    ),
+) -> None:
+    """Benchmark COG header read time via HTTP range requests."""
+    from earthforge.cli.main import get_state
+
+    state = get_state(ctx)
+
+    async def _run_bench() -> BenchResult:
+        from earthforge.raster.info import inspect_raster
+
+        times: list[float] = []
+        for _ in range(runs):
+            t0 = time.perf_counter()
+            info = await inspect_raster(source)
+            times.append(time.perf_counter() - t0)
+
+        return BenchResult(
+            benchmark="raster-info",
+            description=f"COG header read via range request: {source}",
+            runs=runs,
+            results=[{"run": i + 1, "elapsed_s": round(t, 4)} for i, t in enumerate(times)],
+            summary={
+                **_stats(times),
+                "dimensions": f"{info.width}x{info.height}",
+                "overview_count": info.overview_count,
+                "compression": info.compression,
+            },
+        )
+
+    result = asyncio.run(_run_bench())
+    render_to_console(result, state.output, no_color=state.no_color)
+
+
+app.command(name="vector-query", help="Benchmark GeoParquet bbox query performance.")(vector_query)
+app.command(name="raster-info", help="Benchmark COG header read time.")(raster_info)

earthforge_cli-0.1.0/src/earthforge/cli/commands/completions_cmd.py

@@ -0,0 +1,92 @@
+"""EarthForge ``completions`` command — shell completion script generation.
+
+Generates shell completion scripts for bash, zsh, and fish. The output is
+printed to stdout so it can be redirected to the appropriate location:
+
+    earthforge completions bash >> ~/.bashrc
+    earthforge completions zsh  >> ~/.zshrc
+    earthforge completions fish > ~/.config/fish/completions/earthforge.fish
+
+Typer also installs completions automatically via the hidden flags
+``--install-completion`` and ``--show-completion`` that it adds to the root
+app. This module provides an explicit, documentable command as an alternative.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+import typer
+
+_SUPPORTED_SHELLS = ("bash", "zsh", "fish")
+
+_INSTRUCTIONS: dict[str, str] = {
+    "bash": "# Add to ~/.bashrc:\n# source <(earthforge completions bash)",
+    "zsh": "# Add to ~/.zshrc:\n# source <(earthforge completions zsh)",
+    "fish": "# Save to ~/.config/fish/completions/earthforge.fish",
+}
+
+
+def completions(
+    shell: str = typer.Argument(
+        help=f"Shell to generate completions for: {', '.join(_SUPPORTED_SHELLS)}.",
+    ),
+) -> None:
+    """Print a shell completion script to stdout.
+
+    Redirect the output to your shell's configuration to enable tab completion:
+
+        earthforge completions bash >> ~/.bashrc
+
+        earthforge completions zsh >> ~/.zshrc
+
+        earthforge completions fish > ~/.config/fish/completions/earthforge.fish
+    """
+    if shell not in _SUPPORTED_SHELLS:
+        typer.echo(
+            f"Error: unsupported shell '{shell}'. Supported: {', '.join(_SUPPORTED_SHELLS)}",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    # Typer/Click exposes shell completions via the _COMPLETE env var mechanism.
+    # We invoke the CLI subprocess with the appropriate env variable to capture
+    # the completion script rather than re-implementing the generation logic.
+    import os
+
+    env_key = f"_{_app_name().upper().replace('-', '_')}_COMPLETE"
+    env_val = f"{shell}_source"
+
+    try:
+        env = os.environ.copy()
+        env[env_key] = env_val
+        result = subprocess.run(  # noqa: S603
+            [sys.executable, "-m", "earthforge"],
+            env=env,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        script = result.stdout or result.stderr
+    except (subprocess.TimeoutExpired, OSError):
+        # Fallback: emit the instructions comment and let the user use
+        # --show-completion instead
+        script = ""
+
+    if script.strip():
+        typer.echo(f"# Generated by earthforge completions {shell}")
+        typer.echo(f"{_INSTRUCTIONS[shell]}\n")
+        typer.echo(script, nl=False)
+    else:
+        # Typer's built-in mechanism is more reliable — guide the user
+        typer.echo(f"{_INSTRUCTIONS[shell]}\n")
+        typer.echo(
+            f"# Run the following to install completions directly:\n"
+            f"earthforge --install-completion {shell}"
+        )
+
+
+def _app_name() -> str:
+    """Return the CLI entry-point name for the completion env variable."""
+    return "earthforge"

earthforge_cli-0.1.0/src/earthforge/cli/commands/config_cmd.py

@@ -0,0 +1,69 @@
+"""EarthForge ``config`` command group — manage configuration profiles.
+
+Provides commands for initializing, viewing, and managing EarthForge
+configuration profiles. Profiles control STAC API endpoints, cloud storage
+backends, and authentication settings.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from earthforge.core.output import render_to_console
+
+app = typer.Typer(
+    name="config",
+    help="Manage EarthForge configuration profiles.",
+    no_args_is_help=True,
+)
+
+
+def init(
+    ctx: typer.Context,
+    overwrite: bool = typer.Option(
+        False,
+        "--overwrite",
+        help="Overwrite existing config file.",
+    ),
+) -> None:
+    """Create a default configuration file."""
+    from earthforge.cli.main import run_command
+    from earthforge.core.config import init_config
+
+    result = run_command(ctx, init_config(overwrite=overwrite))
+    if result is not None:
+        typer.echo(f"Config file created: {result}")
+
+
+def show(
+    ctx: typer.Context,
+) -> None:
+    """Show the active profile configuration."""
+    from pydantic import BaseModel, Field
+
+    from earthforge.cli.main import get_state, run_command
+    from earthforge.core.config import EarthForgeProfile, load_profile
+
+    class ProfileView(BaseModel):
+        """Rendered view of a profile for CLI output."""
+
+        name: str = Field(title="Profile")
+        stac_api: str | None = Field(default=None, title="STAC API")
+        storage_backend: str = Field(title="Storage")
+        storage_options: dict[str, str] = Field(default_factory=dict, title="Options")
+
+    state = get_state(ctx)
+    result = run_command(ctx, load_profile(state.profile))
+
+    if isinstance(result, EarthForgeProfile):
+        view = ProfileView(
+            name=result.name,
+            stac_api=result.stac_api,
+            storage_backend=result.storage_backend,
+            storage_options=result.storage_options,
+        )
+        render_to_console(view, state.output, no_color=state.no_color)
+
+
+app.command(name="init", help="Create a default configuration file.")(init)
+app.command(name="show", help="Show the active profile configuration.")(show)

earthforge_cli-0.1.0/src/earthforge/cli/commands/cube_cmd.py

@@ -0,0 +1,104 @@
+"""EarthForge ``cube`` command group — Zarr and NetCDF datacube operations.
+
+Provides commands for inspecting and slicing multidimensional geospatial
+datacubes stored as Zarr or NetCDF. Inspection reads only consolidated
+metadata; slicing fetches only the chunks that intersect the requested
+spatiotemporal extent.
+"""
+
+from __future__ import annotations
+
+import typer
+from pydantic import BaseModel
+
+from earthforge.core.output import render_to_console
+
+app = typer.Typer(
+    name="cube",
+    help="Inspect and slice Zarr and NetCDF datacubes.",
+    no_args_is_help=True,
+)
+
+
+def info(
+    ctx: typer.Context,
+    source: str = typer.Argument(
+        help="Zarr store path/URL or NetCDF file path.",
+    ),
+) -> None:
+    """Inspect datacube metadata (dimensions, variables, CRS, extent)."""
+    from earthforge.cli.main import get_state, run_command
+    from earthforge.cube.info import inspect_cube
+
+    state = get_state(ctx)
+    result = run_command(ctx, inspect_cube(source))
+    if isinstance(result, BaseModel):
+        render_to_console(result, state.output, no_color=state.no_color)
+
+
+def slice_cmd(
+    ctx: typer.Context,
+    source: str = typer.Argument(
+        help="Zarr store path/URL or NetCDF file path.",
+    ),
+    output: str = typer.Option(
+        ...,
+        "--output",
+        "-o",
+        help="Output path. Use .zarr suffix for Zarr output, .nc for NetCDF.",
+    ),
+    variables: str | None = typer.Option(
+        None,
+        "--var",
+        help="Comma-separated variable names to include. Default: all.",
+    ),
+    bbox: str | None = typer.Option(
+        None,
+        "--bbox",
+        help="Spatial filter: west,south,east,north (dataset CRS units).",
+    ),
+    time_range: str | None = typer.Option(
+        None,
+        "--time",
+        help="Time range: YYYY-MM-DD/YYYY-MM-DD or YYYY-MM/YYYY-MM.",
+    ),
+) -> None:
+    """Slice a datacube by variables, bounding box, and/or time range."""
+    from earthforge.cli.main import get_state, run_command
+    from earthforge.cube.slice import slice_cube
+
+    state = get_state(ctx)
+
+    # Parse bbox
+    bbox_tuple: tuple[float, float, float, float] | None = None
+    if bbox:
+        parts = [float(v.strip()) for v in bbox.split(",")]
+        if len(parts) != 4:
+            typer.echo(
+                "Error: --bbox requires exactly 4 values: west,south,east,north",
+                err=True,
+            )
+            raise typer.Exit(code=1)
+        bbox_tuple = (parts[0], parts[1], parts[2], parts[3])
+
+    # Parse variables
+    var_list: list[str] | None = None
+    if variables:
+        var_list = [v.strip() for v in variables.split(",")]
+
+    result = run_command(
+        ctx,
+        slice_cube(
+            source,
+            variables=var_list,
+            bbox=bbox_tuple,
+            time_range=time_range,
+            output=output,
+        ),
+    )
+    if isinstance(result, BaseModel):
+        render_to_console(result, state.output, no_color=state.no_color)
+
+
+app.command(name="info", help="Inspect datacube metadata.")(info)
+app.command(name="slice", help="Slice a datacube by variables, bbox, and time.")(slice_cmd)

earthforge_cli-0.1.0/src/earthforge/cli/commands/explore_cmd.py

@@ -0,0 +1,98 @@
+"""EarthForge ``explore`` command — interactive STAC TUI.
+
+Launches the Textual-based interactive terminal user interface for browsing
+STAC catalogs. The TUI provides a three-panel layout:
+
+- **Collections** — all collections at the STAC API endpoint
+- **Items** — up to 50 items in the selected collection
+- **Detail** — full metadata, assets, and links for the selected item
+
+Keyboard shortcuts inside the TUI
+----------------------------------
+``q``
+    Quit the explorer.
+``r``
+    Refresh the collection list.
+``/``
+    Show filter hint (bbox filtering is applied at launch).
+``Tab`` / ``Shift+Tab``
+    Cycle focus between the three panels.
+``Enter``
+    Select the focused collection or item.
+``↑`` / ``↓``
+    Navigate within a panel.
+"""
+
+from __future__ import annotations
+
+import typer
+
+app = typer.Typer(name="explore", help="Interactive STAC catalog explorer (TUI).")
+
+_DEFAULT_API = "https://earth-search.aws.element84.com/v1"
+
+
+@app.callback(invoke_without_command=True)
+def explore(
+    ctx: typer.Context,
+    api: str = typer.Option(
+        _DEFAULT_API,
+        "--api",
+        help="STAC API root URL to browse.",
+        show_default=True,
+    ),
+    collection: str | None = typer.Option(
+        None,
+        "--collection",
+        "-c",
+        help="Pre-select and open this collection on startup.",
+    ),
+    bbox: str | None = typer.Option(
+        None,
+        "--bbox",
+        help="Spatial filter: west,south,east,north (applied to item searches).",
+    ),
+) -> None:
+    """Launch the interactive STAC catalog explorer.
+
+    Opens a full-screen terminal UI connected to the given STAC API. Browse
+    collections, inspect items, and view asset metadata — all without leaving
+    the terminal.
+
+    Parameters:
+        ctx: Typer command context (for global state).
+        api: STAC API endpoint URL.
+        collection: Optional collection to open on startup.
+        bbox: Optional bounding-box filter string.
+
+    Raises:
+        typer.Exit: With code 1 on invalid ``--bbox`` input.
+    """
+    try:
+        from earthforge.cli.tui.app import ExploreApp
+    except ImportError as exc:
+        typer.echo(
+            f"Error: textual is required for explore: {exc}\n"
+            "Install with: pip install earthforge[cli]",
+            err=True,
+        )
+        raise typer.Exit(code=1) from exc
+
+    bbox_tuple: tuple[float, float, float, float] | None = None
+    if bbox:
+        parts = [v.strip() for v in bbox.split(",")]
+        if len(parts) != 4:
+            typer.echo("Error: --bbox requires west,south,east,north", err=True)
+            raise typer.Exit(code=1)
+        try:
+            w, s, e, n = (float(p) for p in parts)
+        except ValueError:
+            typer.echo("Error: --bbox values must be numeric", err=True)
+            raise typer.Exit(code=1)  # noqa: B904
+        bbox_tuple = (w, s, e, n)
+
+    ExploreApp(
+        api_url=api,
+        initial_collection=collection,
+        bbox=bbox_tuple,
+    ).run()