firecube 0.1.4__py3-none-any.whl

firecube/__init__.py

@@ -0,0 +1,23 @@
+# Copyright 2025-2026 EUMETSAT
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Firecube package."""
+
+from __future__ import annotations
+
+from firecube._version import VERSION
+
+__version__ = VERSION
+
+__all__ = ["__version__"]

firecube/__main__.py

@@ -0,0 +1,20 @@
+# Copyright 2025-2026 EUMETSAT
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Firecube CLI entrypoint."""
+
+from firecube.cli.main import cli
+
+if __name__ == "__main__":
+    cli()

firecube/_version.py

@@ -0,0 +1,46 @@
+# Copyright 2025-2026 EUMETSAT
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Resolve Firecube's package version from installed metadata or pyproject.toml."""
+
+from __future__ import annotations
+
+import importlib.metadata
+import tomllib
+from pathlib import Path
+
+_DISTRIBUTION_NAME = "firecube"
+_UNKNOWN_VERSION = "0.0.0+unknown"
+
+
+def _pyproject_version() -> str | None:
+    current = Path(__file__).resolve()
+    for parent in current.parents[:4]:
+        pyproject = parent / "pyproject.toml"
+        if not pyproject.exists():
+            continue
+        data = tomllib.loads(pyproject.read_text())
+        version = data.get("project", {}).get("version")
+        return version if isinstance(version, str) and version else None
+    return None
+
+
+def get_version() -> str:
+    try:
+        return importlib.metadata.version(_DISTRIBUTION_NAME)
+    except importlib.metadata.PackageNotFoundError:
+        return _pyproject_version() or _UNKNOWN_VERSION
+
+
+VERSION = get_version()

firecube/cli/_audience.py

@@ -0,0 +1,135 @@
+# Copyright 2025-2026 EUMETSAT
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from typing import Literal
+
+import click
+
+USER_FACING_PATHS: frozenset[tuple[str, ...]] = frozenset(
+    {
+        ("ingest",),
+        ("zarr", "validate"),
+        ("zarr", "multires"),
+        ("zarr", "preallocate"),
+        ("zarr", "slots"),
+        ("parquet", "validate"),
+        ("parquet", "consolidate"),
+        ("plugins", "list"),
+        ("plugins", "describe"),
+        ("plugins", "explain"),
+        ("plugins", "create"),
+        ("plugins", "install"),
+        ("plugins", "uninstall"),
+        ("advise", "batch-size"),
+        ("advise", "compliance"),
+        ("completion",),
+    }
+)
+
+OPERATOR_FACING_PATHS: frozenset[tuple[str, ...]] = frozenset(
+    {
+        ("chunks", "list"),
+        ("chunks", "delete"),
+        ("chunks", "delete-span"),
+        ("chunks", "claims", "list"),
+        ("chunks", "claims", "clear"),
+        ("chunks", "runs", "list"),
+        ("chunks", "runs", "abandon"),
+        ("chunks", "snapshots", "rebuild"),
+        ("chunks", "snapshots", "status"),
+        ("archive", "create"),
+        ("archive", "restore"),
+        ("archive", "info"),
+        ("archive", "validate"),
+        ("archive", "list"),
+        ("catalog", "intake"),
+    }
+)
+
+TIER_1_PATHS: frozenset[tuple[str, ...]] = frozenset(
+    {
+        ("chunks", "delete"),
+        ("chunks", "delete-span"),
+        ("archive", "create"),
+        ("archive", "restore"),
+    }
+)
+
+TIER_2_PATHS: frozenset[tuple[str, ...]] = frozenset(
+    {
+        ("chunks", "runs", "abandon"),
+        ("chunks", "claims", "clear"),
+    }
+)
+
+TIER_3_PATHS: frozenset[tuple[str, ...]] = frozenset(
+    {
+        ("chunks", "snapshots", "rebuild"),
+        ("zarr", "preallocate"),
+    }
+)
+
+INTERNAL_TOKENS_USER_FORBIDDEN = frozenset(
+    {
+        ".firecube",
+        "WAL",
+        "control-plane",
+        "DirectZarrIngestor",
+        "JOB_COMPLETION_INDEX",
+        "SUPPORTS_SLOT_RANGE_PARALLELISM",
+        "SchemaSizeMismatchError",
+    }
+)
+
+GROUP_AUDIENCE: dict[str, Literal["user", "operator"]] = {
+    "zarr": "user",
+    "archive": "operator",
+    "parquet": "user",
+    "chunks": "operator",
+    "advise": "user",
+    "plugins": "user",
+    "catalog": "operator",
+}
+
+_AUDIENCE_PATHS: dict[tuple[str, ...], Literal["user", "operator"]] = dict.fromkeys(
+    USER_FACING_PATHS, "user"
+)
+_AUDIENCE_PATHS.update(dict.fromkeys(OPERATOR_FACING_PATHS, "operator"))
+
+
+def classify(command_path: tuple[str, ...]) -> Literal["user", "operator"]:
+    """Return audience class for a command path.
+
+    Raises ``click.ClickException`` for unknown paths so the CLI boundary
+    renders a clean error instead of a Python traceback.
+    """
+
+    try:
+        return _AUDIENCE_PATHS[command_path]
+    except KeyError as exc:
+        raise click.ClickException(f"Unknown command path: {command_path!r}") from exc
+
+
+__all__ = [
+    "GROUP_AUDIENCE",
+    "INTERNAL_TOKENS_USER_FORBIDDEN",
+    "OPERATOR_FACING_PATHS",
+    "TIER_1_PATHS",
+    "TIER_2_PATHS",
+    "TIER_3_PATHS",
+    "USER_FACING_PATHS",
+    "classify",
+]

firecube/cli/_command_schemas.py

@@ -0,0 +1,112 @@
+# Copyright 2025-2026 EUMETSAT
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import click
+
+from firecube.cli._uri_policy import SCHEME_TO_STORAGE_TYPE
+from firecube.core.uris import infer_target_protocol
+
+
+@dataclass(slots=True)
+class IngestCommandConfig:
+    """Validated ingest command configuration.
+
+    Uses aggregate validation to report all missing/invalid command-level values at once.
+    """
+
+    plugin: str
+    input_data: str | Path | None
+    target: str
+    write_mode: str | None
+    storage_type: str | None
+    storage_driver: str | None
+    product_name: str | None = None
+    output_format: str = "zarr"
+    in_memory: bool = False
+    options: dict[str, Any] = field(default_factory=dict)
+
+    _VALID_WRITE_MODES = frozenset({"staged", "direct"})
+    _VALID_STORAGE_TYPES = frozenset({"local", "s3"})
+    _VALID_STORAGE_DRIVERS = frozenset({"fsspec", "obstore"})
+
+    def __post_init__(self) -> None:
+        """Aggregate all validation errors into a single Click usage error."""
+        errors: list[str] = []
+
+        if self.product_name is not None and self.product_name == "":
+            errors.append(
+                "--product-name was provided but is empty. Either omit it (use plugin "
+                "PRODUCT_NAME or config default_product_name), or provide a non-empty value."
+            )
+
+        if not self.target:
+            errors.append("--target is required.")
+
+        if self.write_mode is None:
+            errors.append(
+                "--write-mode is required. No inference from target locality. "
+                "Choose: staged (workspace-first then upload) or direct (stream to target)."
+            )
+        elif self.write_mode not in self._VALID_WRITE_MODES:
+            errors.append(
+                f"--write-mode must be one of: {', '.join(sorted(self._VALID_WRITE_MODES))} "
+                f"(got '{self.write_mode}')"
+            )
+
+        if self.storage_type is not None and self.storage_type not in self._VALID_STORAGE_TYPES:
+            errors.append(
+                f"--storage-type must be one of: {', '.join(sorted(self._VALID_STORAGE_TYPES))} "
+                f"(got '{self.storage_type}')"
+            )
+        if self.storage_type is not None and self.target:
+            try:
+                scheme = infer_target_protocol(self.target)
+            except ValueError as exc:
+                errors.append(str(exc))
+            else:
+                expected_storage_type = SCHEME_TO_STORAGE_TYPE.get(scheme)
+                if expected_storage_type is None:
+                    errors.append(
+                        f"Target URI scheme '{scheme}' is not supported. Use a file:// URI for "
+                        "--storage-type local, or an s3:// URI for --storage-type s3."
+                    )
+                elif expected_storage_type != self.storage_type:
+                    alternate_target = (
+                        "an s3://-compatible URI" if self.storage_type == "s3" else "a file:// URI"
+                    )
+                    errors.append(
+                        f"Target URI scheme '{scheme}' is incompatible with --storage-type "
+                        f"'{self.storage_type}'. Use --storage-type {expected_storage_type} "
+                        f"for {scheme}:// targets, or change --target to {alternate_target}."
+                    )
+
+        if (
+            self.storage_driver is not None
+            and self.storage_driver not in self._VALID_STORAGE_DRIVERS
+        ):
+            errors.append(
+                f"--storage-driver must be one of: {', '.join(sorted(self._VALID_STORAGE_DRIVERS))} "
+                f"(got '{self.storage_driver}')"
+            )
+
+        if errors:
+            raise click.UsageError(
+                "Invalid ingest configuration:\n" + "\n".join(f"  - {error}" for error in errors)
+            )

firecube/cli/_ctx.py

@@ -0,0 +1,85 @@
+# Copyright 2025-2026 EUMETSAT
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+import click
+
+from firecube.core.config import StorageConfig, load_config_file
+from firecube.core.runtime import identity_from_storage_config, resolve_storage_config
+
+log = logging.getLogger("firecube.cli")
+
+
+def get_config_file(ctx: click.Context) -> Path | None:
+    ctx.ensure_object(dict)
+    value = ctx.obj.get("config_file")
+    return value if isinstance(value, Path) else None
+
+
+def get_config(ctx: click.Context) -> dict[str, Any]:
+    """Load config TOML as a plain dictionary."""
+    return load_config_file(get_config_file(ctx))
+
+
+def get_storage_config(
+    ctx: click.Context,
+    *,
+    overrides: Mapping[str, str | None] | None = None,
+    set_global: bool = False,
+    cache: bool = True,
+) -> StorageConfig:
+    """Resolve StorageConfig from config + env + optional overrides.
+
+    This centralizes common CLI behavior:
+    - reads `--config-file` stored in `ctx.obj["config_file"]`
+    - caches the resolved StorageConfig in `ctx.obj["storage_config"]`
+    - wraps errors as Click-friendly exceptions
+    """
+    ctx.ensure_object(dict)
+    if cache and overrides is None:
+        cached = ctx.obj.get("storage_config")
+        if isinstance(cached, StorageConfig):
+            return cached
+
+    try:
+        storage_config = resolve_storage_config(
+            config_file=get_config_file(ctx),
+            overrides=dict(overrides) if overrides is not None else None,
+            set_global=set_global,
+        )
+    except Exception as exc:
+        raise click.ClickException(f"Failed to resolve storage configuration: {exc}") from exc
+
+    if cache and overrides is None:
+        ctx.obj["storage_config"] = storage_config
+        identity = identity_from_storage_config(storage_config)
+        product_uri = identity.product_uri if identity is not None else None
+        bucket = product_uri.authority if product_uri is not None else None
+        target_path = (
+            product_uri.path if product_uri is not None and product_uri.protocol == "file" else None
+        )
+        log.debug(
+            "Resolved StorageConfig (type=%s bucket=%s endpoint=%s target=%s)",
+            storage_config.storage_type,
+            bucket,
+            storage_config.endpoint_url,
+            target_path,
+        )
+    return storage_config

firecube/cli/_errors.py

@@ -0,0 +1,115 @@
+# Copyright 2025-2026 EUMETSAT
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import errno
+import functools
+from collections.abc import Callable
+
+import click
+
+_KNOWN_USER_ERROR_TYPE_NAMES: frozenset[str] = frozenset(
+    {
+        "ConfigurationError",
+        "GroupNotFoundError",
+        "FileNotFoundError",
+        "NodeNotFoundError",
+        "NotADirectoryError",
+        "PathNotFoundError",
+        "PermissionError",
+    }
+)
+
+
+def _is_known_user_error(exc: BaseException) -> bool:
+    return type(exc).__name__ in _KNOWN_USER_ERROR_TYPE_NAMES
+
+
+def _is_known_user_oserror(exc: BaseException) -> bool:
+    """True when exc is an OS-level error that is the user's fault (not infra)."""
+    return isinstance(exc, OSError) and exc.errno in {errno.ENOENT, errno.ENOTDIR, errno.EACCES}
+
+
+def wrap_user_facing_errors[**P, R](func: Callable[P, R]) -> Callable[P, R]:
+    """Convert known downstream errors to ``click.ClickException`` at the CLI boundary.
+
+    Only exceptions whose class name appears in ``_KNOWN_USER_ERROR_TYPE_NAMES``
+    are wrapped; ``click.ClickException`` and ``click.exceptions.Exit`` pass
+    through unchanged, and any other exception propagates so operators see the
+    real traceback.
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        try:
+            return func(*args, **kwargs)
+        except click.exceptions.Exit:
+            raise
+        except click.ClickException:
+            raise
+        except Exception as exc:
+            if _is_known_user_error(exc) or _is_known_user_oserror(exc):
+                raise click.ClickException(str(exc)) from exc
+            raise
+
+    return wrapper
+
+
+class UnknownOptionError(click.BadParameter):
+    def __init__(self, key: str, plugin: str, valid_keys: list[str]) -> None:
+        msg = (
+            f"Unknown option '{key}' for plugin '{plugin}'.\n"
+            f"Valid keys ({len(valid_keys)}): {', '.join(sorted(valid_keys))}\n"
+            f"Hint: run `firecube ingest {plugin} --show-options` to inspect. "
+            f"Experimental options must use the x_ prefix (e.g. --option x_foo=...)."
+        )
+        super().__init__(msg)
+
+
+class MissingProductNameError(click.UsageError):
+    def __init__(self, plugin: str) -> None:
+        super().__init__(
+            f"Missing product name for plugin '{plugin}'. Provide one of:\n"
+            f"  1. CLI flag:  --product-name <name>\n"
+            f"  2. Config file:  [plugins.{plugin}]\n  default_product_name = '<name>'\n"
+            f"  3. Plugin class attr:  {plugin}.PRODUCT_NAME = '<name>'  (preferred; declared at plugin source)"
+        )
+
+
+class MissingStorageTypeError(click.UsageError):
+    def __init__(self, target_uri: str) -> None:
+        super().__init__(
+            f"Missing --storage-type for target '{target_uri}'.\n"
+            f"Storage type is no longer inferred from URI scheme. Provide explicitly:\n"
+            f"  --storage-type [local|s3]"
+        )
+
+
+class MissingStorageDriverError(click.UsageError):
+    def __init__(self, target_uri: str) -> None:
+        super().__init__(
+            f"Missing --storage-driver for target '{target_uri}'. Provide explicitly:\n"
+            f"  --storage-driver [fsspec|obstore]"
+        )
+
+
+class MissingWriteModeError(click.UsageError):
+    def __init__(self) -> None:
+        super().__init__(
+            "Missing --write-mode. Required for all targets (no local-default inference). "
+            "Choose:\n"
+            "  --write-mode staged : workspace-first, then upload\n"
+            "  --write-mode direct : stream directly to target\n"
+        )