fix: scope cache files by extent_id and validate spatial coverage

[turban]

Breaking changes

• `CACHE_OVERRIDE` env var removed — deployments using `CACHE_OVERRIDE` to set the data directory must migrate to `data_dir` in `climate-api.yaml`.
• `data_dir` required in `climate-api.yaml` — the API raises `ValueError` at startup if a config file is present but `data_dir` is not set.
• `datasets_dir` renamed to `templates_dir` — any `climate-api.yaml` files using `datasets_dir` must be updated.

Summary

• Directory isolation per instance: Each deployment must now declare `data_dir` in `climate-api.yaml`. This prevents silent data reuse across instances (e.g. WorldPop data for Sierra Leone being served to a Norway instance).
• Data directory resolution: `data_dir` from config → XDG default (`~/.local/share/climate-api`). `CACHE_OVERRIDE` is gone.
• `templates_dir` (renamed from `datasets_dir`): Points at user-supplied YAML templates. The new name reflects that it will cover both dataset and processing templates going forward.
• Spatial coverage validation: `download_dataset` validates the request bbox against `extents.spatial.bbox` before hitting the provider, returning HTTP 400 with a clear message instead of a confusing provider error. Partial overlap is allowed; only fully outside requests are rejected.
• OGC-aligned extents in dataset templates: Replaced the custom `coverage:` field with an `extents:` block matching OGC API Collections (`extents.spatial.bbox` in `[xmin, ymin, xmax, ymax]` format, `extents.temporal` with `begin`, `trs`, and `resolution`). CHIRPS3 gets a restricted spatial bbox of `[-180, -50, 180, 50]`.

Background

Discovered during Norway instance setup: WorldPop data downloaded for Sierra Leone was silently reused for Norway (wrong bounding box), and a CHIRPS3 ingest for Norway returned an HTTP 403 with no clear message. The root fix is directory isolation per instance via `data_dir`.

Test plan

• `test_get_data_dir_*` — required field, relative path resolution, no-config fallback
• `test_resolve_download_dir_` / `test_resolve_artifacts_dir_` — config data_dir, XDG fallback
• `test_get_cache_prefix_uses_dataset_id`
• `test_validate_spatial_coverage_*` — OGC bbox validation cases
• `test_download_dataset_returns_400_when_bbox_outside_dataset_extents`
• `test_templates_dir_*` — custom template loading, relative path resolution, override by id
• All existing tests pass (164 passed, 1 skipped)

[Copilot]

Pull request overview

Updates Climate API instance isolation by requiring an explicit per-deployment data_dir, removes the legacy CACHE_OVERRIDE env var, and adds dataset-template extents metadata to validate request bounding boxes before calling upstream providers.

Changes:

• Add data_dir config resolution (required when a config file exists) and migrate download/artifact/pygeoapi directories to be scoped under it (with XDG fallback when no config is present).
• Rename datasets_dir → templates_dir and change custom template loading to templates_dir/datasets/.
• Introduce dataset template extents and validate ingestion request bboxes against extents.spatial.bbox (HTTP 400 when fully outside).

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/climate_api/config.py	Adds get_data_dir() to resolve required instance-scoped data directory.
src/climate_api/data_manager/services/downloader.py	Uses data_dir for downloads and adds spatial coverage validation based on template extents.
src/climate_api/ingestions/services.py	Moves artifacts directory under data_dir (XDG fallback otherwise).
src/climate_api/publications/services.py	Moves pygeoapi working directory under data_dir (XDG fallback otherwise).
src/climate_api/data_registry/services/datasets.py	Renames config key to templates_dir and loads custom datasets from templates_dir/datasets/.
src/climate_api/data/datasets/chirps3.yaml	Adds OGC-aligned extents metadata (with restricted spatial bbox).
src/climate_api/data/datasets/era5_land.yaml	Adds OGC-aligned extents metadata for both ERA5-Land templates.
src/climate_api/data/datasets/worldpop.yaml	Adds OGC-aligned extents metadata for WorldPop.
tests/conftest.py	Updates test instance config to include required data_dir.
tests/test_config.py	Adds tests for get_data_dir() behavior and updates to templates_dir semantics.
tests/test_downloader.py	Updates directory resolution tests and adds coverage validation tests.
tests/test_publications.py	Updates pygeoapi dir resolution tests to use data_dir.
tests/test_datasets.py	Adjusts test setup for Zarr path monkeypatching.
docs/setup_guide.md	Documents required data_dir and updates references to templates_dir.
docs/adding_custom_datasets.md	Updates guidance for templates_dir and documents extents blocks.
climate-api.yaml.example	Updates example config: adds required data_dir and renames templates_dir.
.env.example	Removes CACHE_OVERRIDE and updates comments for templates_dir.

Comments suppressed due to low confidence (1)

src/climate_api/data_manager/services/downloader.py:76

• Spatial coverage validation is performed before the effective bbox is resolved via _resolve_bbox(). If bbox is None (e.g. relying on DOWNLOAD_BBOX), _validate_spatial_coverage() will currently skip validation and the request can still reach the provider. Consider resolving the bbox (when applicable) first and validating the resolved bbox so all request paths get the intended early 400 response.

    _validate_spatial_coverage(dataset, bbox)
    ingestion = dataset["ingestion"]
    eo_download_func_path = ingestion["function"]
    eo_download_func = _get_dynamic_function(eo_download_func_path)
    before_files = {path.resolve(): path.stat().st_mtime_ns for path in get_cache_files(dataset)}

    params = dict(ingestion.get("default_params", {}))
    params.update(
        {
            "start": start,
            "end": end or datetime.date.today().isoformat(),
            "dirname": DOWNLOAD_DIR,
            "prefix": _get_cache_prefix(dataset),
            "overwrite": overwrite,
        }
    )

    sig = inspect.signature(eo_download_func)
    try:
        if "bbox" in sig.parameters:
            params["bbox"] = _resolve_bbox(bbox=bbox)
        if "country_code" in sig.parameters: