quantilica-cli 0.9.1__tar.gz → 0.10.1__tar.gz

{quantilica_cli-0.9.1 → quantilica_cli-0.10.1}/CHANGELOG.md

@@ -5,6 +5,34 @@ Todas as mudanças notáveis deste projeto serão documentadas neste arquivo.
 O formato segue [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/),
 e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/).
 
+## [0.10.1] - 2026-10-08
+
+### Corrigido
+
+- `sdk`: `check_entry` considera `local.exists() or sidecar.exists()`, preservando
+  o status de `manifest-fresh` em ambientes de ingestão efêmera sem forçar
+  re-download redundante quando o dado bruto já foi espelhado.
+
+## [0.10.0] - 2026-10-07
+
+### Adicionado
+
+- `FetcherApp`: comando `check` — verificação remoto × local (HEAD por
+  entrada) com plano de freshness, sem baixar; `--json` emite plano
+  consumível por `sync --from-plan`.
+- `FetcherApp.sync`: opção `--from-plan <arquivo.json>` — baixa somente as
+  entradas com ação `download` do plano.
+- SDK: `CheckPlan`/`CheckPlanItem` (tabela Rich + round-trip JSON) e
+  `default_client()` com overrides via ambiente (`QUANTILICA_CA_BUNDLE`,
+  `QUANTILICA_SSL_VERIFY`, `QUANTILICA_HTTP_ATTEMPTS/TIMEOUT/RETRY_DELAY`).
+
+### Alterado
+
+- Piso de `quantilica-core` elevado para `>=0.10.0` (símbolos usados:
+  `is_remote_more_recent`, `resolve_verify_from_env`).
+- Workers internos do `download_datasets` propagam o `transport` customizado
+  do client canônico.
+
 ## [0.9.1] - 2026-10-04
 
 Correção de escape inválido introduzido na v0.8.0 (Onda A.2 do SDK).

{quantilica_cli-0.9.1 → quantilica_cli-0.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quantilica-cli
-Version: 0.9.1
+Version: 0.10.1
 Summary: Unified CLI for Quantilica open data fetchers
 Author-email: "Komesu, D.K." <daniel@dkko.me>
 License-Expression: MIT
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
-Requires-Dist: quantilica-core>=0.7.0
+Requires-Dist: quantilica-core>=0.10.1
 Requires-Dist: rich>=13.0.0
 Requires-Dist: typer>=0.15.0
 Description-Content-Type: text/markdown

{quantilica_cli-0.9.1 → quantilica_cli-0.10.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quantilica-cli"
-version = "0.9.1"
+version = "0.10.1"
 description = "Unified CLI for Quantilica open data fetchers"
 readme = "README.md"
 authors = [{ name = "Komesu, D.K.", email = "daniel@dkko.me" }]
@@ -20,7 +20,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "quantilica-core>=0.7.0",
+    "quantilica-core>=0.10.1",
     "rich>=13.0.0",
     "typer>=0.15.0",
 ]

{quantilica_cli-0.9.1 → quantilica_cli-0.10.1}/src/quantilica/cli/sdk.py

@@ -8,6 +8,9 @@ from __future__ import annotations
 import concurrent.futures
 import contextlib
 import datetime as dt
+import email.utils
+import json
+import os
 import threading
 from collections.abc import Callable, Iterable
 from dataclasses import dataclass, field
@@ -17,8 +20,15 @@ from typing import Annotated, Any
 import typer
 from quantilica.core.exceptions import FetchError
 from quantilica.core.ftp import FtpClient
-from quantilica.core.http import HttpClient, HttpStatusError, ProgressCallback
+from quantilica.core.http import (
+    HttpClient,
+    HttpStatusError,
+    ProgressCallback,
+    is_remote_more_recent,
+    resolve_verify_from_env,
+)
 from quantilica.core.logging import get_logger
+from quantilica.core.manifests import manifest_sidecar_path
 from quantilica.core.storage import (
     StampedDataRepository,
     build_stamped_filename,
@@ -41,6 +51,8 @@ from quantilica.cli.ui import (
 logger = get_logger(__name__)
 
 __all__ = [
+    "CheckPlan",
+    "CheckPlanItem",
     "DataRepository",
     "FetcherApp",
     "SyncPlan",
@@ -113,17 +125,231 @@ class SyncPlan:
         )
 
 
+def _partition_label(entry: dict[str, Any]) -> str | None:
+    """Human-readable partition label for a dataset entry."""
+    if entry.get("semester") is not None:
+        return f"{entry['year']}-S{entry['semester']}"
+    if entry.get("month") is not None:
+        return f"{entry['year']}-{entry['month']:02d}"
+    if entry.get("year") is not None:
+        return str(entry["year"])
+    return None
+
+
+def _parse_head_date(value: str | None) -> dt.date | None:
+    """Parse an HTTP Last-Modified header value into a date, or None."""
+    if not value:
+        return None
+    with contextlib.suppress(Exception):
+        return email.utils.parsedate_to_datetime(value).date()
+    return None
+
+
+def _short_remote(item: CheckPlanItem) -> str:
+    """Compact remote description for table display (narrow terminals)."""
+    date = _parse_head_date(item.remote_last_modified)
+    remote = date.isoformat() if date else (item.remote_last_modified or "—")
+    if item.remote_size:
+        remote += f" ({item.remote_size} B)"
+    return remote
+
+
+@dataclass(frozen=True)
+class CheckPlanItem:
+    """Freshness verdict for a single dataset entry (no download performed).
+
+    Args:
+        dataset: Canonical dataset (group) identifier.
+        id: Dataset entry identifier.
+        url: Remote URL that was checked.
+        partition: Human-readable partition label, or None.
+        local_path: Local destination path the entry maps to.
+        remote_etag: Remote ETag header, or None.
+        remote_last_modified: Remote Last-Modified header, or None.
+        remote_size: Remote Content-Length, or None.
+        local_exists: Whether the artifact already exists locally — this
+            covers either the raw file itself or its ephemeral ``.manifest.json``
+            sidecar marker (file deleted for retention, sidecar still fresh).
+        action: ``"download"`` or ``"skip-up-to-date"``.
+        reason: Machine-readable reason for the action.
+        entry: Original dataset entry (allows ``sync --from-plan`` round-trip).
+    """
+
+    dataset: str
+    id: str
+    url: str
+    partition: str | None
+    local_path: str
+    remote_etag: str | None
+    remote_last_modified: str | None
+    remote_size: int | None
+    local_exists: bool
+    action: str
+    reason: str
+    entry: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class CheckPlan:
+    """Freshness plan for a verification run (``check`` command).
+
+    Args:
+        fetcher: Name of the fetcher that produced the plan.
+        output_dir: Output directory the plan was computed against.
+        generated_at: ISO-8601 UTC timestamp of plan generation.
+        items: Per-entry verdicts.
+    """
+
+    fetcher: str
+    output_dir: str
+    generated_at: str
+    items: list[CheckPlanItem] = field(default_factory=list)
+
+    def render_table(self, console: Console | None = None) -> None:
+        """Render the plan as a Rich table with a summary footer."""
+        con = console or get_console()
+        table = Table(
+            "Dataset",
+            "ID",
+            "Ação",
+            "Motivo",
+            "Remoto",
+            title="Verificação remoto × local (check)",
+        )
+        for item in self.items:
+            table.add_row(
+                item.dataset,
+                item.id,
+                item.action,
+                item.reason,
+                _short_remote(item),
+            )
+        con.print(table)
+        counts: dict[str, int] = {}
+        for item in self.items:
+            counts[item.action] = counts.get(item.action, 0) + 1
+        summary = ", ".join(f"{v} {k}" for k, v in sorted(counts.items()))
+        con.print(f"[bold]{len(self.items)}[/bold] verificado(s): {summary}.")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the JSON-serializable representation of the plan."""
+        return {
+            "fetcher": self.fetcher,
+            "output_dir": self.output_dir,
+            "generated_at": self.generated_at,
+            "items": [
+                {
+                    "dataset": it.dataset,
+                    "id": it.id,
+                    "url": it.url,
+                    "partition": it.partition,
+                    "local_path": it.local_path,
+                    "remote_etag": it.remote_etag,
+                    "remote_last_modified": it.remote_last_modified,
+                    "remote_size": it.remote_size,
+                    "local_exists": it.local_exists,
+                    "action": it.action,
+                    "reason": it.reason,
+                    "entry": it.entry,
+                }
+                for it in self.items
+            ],
+        }
+
+    def to_json(self) -> str:
+        """Serialize the plan to a JSON string (for ``sync --from-plan``)."""
+        return json.dumps(self.to_dict(), ensure_ascii=False, indent=2)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CheckPlan:
+        """Rebuild a plan from :meth:`to_dict` output.
+
+        Raises:
+            ValueError: If the payload is not a valid check plan.
+        """
+        if not isinstance(data, dict) or not isinstance(data.get("items"), list):
+            raise ValueError("not a check plan: missing 'items' list")
+        items = []
+        for raw in data["items"]:
+            if not isinstance(raw, dict):
+                raise ValueError("not a check plan: invalid item")
+            try:
+                entry = raw["entry"]
+                action = raw["action"]
+                eid = raw["id"]
+            except KeyError as exc:
+                raise ValueError(f"not a check plan: item missing {exc}") from exc
+            if not isinstance(entry, dict) or action not in (
+                "download",
+                "skip-up-to-date",
+            ):
+                raise ValueError("not a check plan: invalid item")
+            items.append(
+                CheckPlanItem(
+                    dataset=str(raw.get("dataset", "")),
+                    id=str(eid),
+                    url=str(raw.get("url", "")),
+                    partition=raw.get("partition"),
+                    local_path=str(raw.get("local_path", "")),
+                    remote_etag=raw.get("remote_etag"),
+                    remote_last_modified=raw.get("remote_last_modified"),
+                    remote_size=raw.get("remote_size"),
+                    local_exists=bool(raw.get("local_exists", False)),
+                    action=action,
+                    reason=str(raw.get("reason", "")),
+                    entry=entry,
+                )
+            )
+        return cls(
+            fetcher=str(data.get("fetcher", "")),
+            output_dir=str(data.get("output_dir", "")),
+            generated_at=str(data.get("generated_at", "")),
+            items=items,
+        )
+
+    @classmethod
+    def from_json(cls, payload: str) -> CheckPlan:
+        """Parse a plan serialized with :meth:`to_json`.
+
+        Raises:
+            ValueError: If the payload is not valid JSON or not a plan.
+        """
+        try:
+            data = json.loads(payload)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"not a check plan: invalid JSON ({exc})") from exc
+        return cls.from_dict(data)
+
+
 def default_client() -> HttpClient:
     """Create a default HttpClient with standard configuration.
 
+    TLS verification and retry budget can be overridden via environment:
+
+    - ``QUANTILICA_CA_BUNDLE``: path to a custom CA bundle.
+    - ``QUANTILICA_SSL_VERIFY``: ``0``/``false`` disables verification
+      (ops escape hatch for hosts with broken chains — never default);
+      a path uses it as CA bundle.
+    - ``QUANTILICA_HTTP_ATTEMPTS`` / ``QUANTILICA_HTTP_TIMEOUT`` /
+      ``QUANTILICA_HTTP_RETRY_DELAY``: retry budget overrides.
+
     Returns:
         A pre-configured HttpClient instance (browser-like WAF headers + pooling).
     """
+    verify = resolve_verify_from_env()
+    if verify is False:
+        logger.warning(
+            "TLS verification disabled via QUANTILICA_SSL_VERIFY — "
+            "use only for hosts with broken chains"
+        )
+    attempts = int(os.environ.get("QUANTILICA_HTTP_ATTEMPTS", "5"))
+    timeout = float(os.environ.get("QUANTILICA_HTTP_TIMEOUT", "180.0"))
+    retry_base_delay = float(os.environ.get("QUANTILICA_HTTP_RETRY_DELAY", "2.0"))
     return HttpClient(
-        timeout=180.0,
-        verify=True,
-        attempts=5,
-        retry_base_delay=2.0,
+        timeout=timeout,
+        verify=verify,
+        attempts=attempts,
+        retry_base_delay=retry_base_delay,
         emulate_browser=True,
     )
 
@@ -648,6 +874,7 @@ class FetcherApp:
                     attempts=self.client.attempts,
                     retry_base_delay=self.client.retry_base_delay,
                     verify=self.client.verify,
+                    transport=self.client.transport,
                     limits=self.client.limits,
                     emulate_browser=True,
                 )
@@ -696,6 +923,137 @@ class FetcherApp:
 
         return downloaded, total, errors
 
+    def check_entry(self, entry: dict[str, Any], output_dir: Path) -> CheckPlanItem:
+        """Check one dataset entry against the remote without downloading.
+
+        Performs HEAD requests (same URLs ``download_entry`` would try,
+        including ``fallback_urls``) and compares against the local stamped
+        file using the same freshness predicate as the download path.
+
+        Args:
+            entry: Dictionary containing dataset metadata (url, id, etc).
+            output_dir: Destination directory used for path computation.
+
+        Returns:
+            The freshness verdict for the entry.
+        """
+        dataset = str(entry.get("group") or entry.get("id") or "datasets")
+        eid = str(entry.get("id", "unknown"))
+        partition = _partition_label(entry)
+        urls_to_try = [entry["url"]]
+        if "fallback_urls" in entry and entry["fallback_urls"]:
+            urls_to_try.extend(entry["fallback_urls"])
+
+        head = None
+        head_error: Exception | None = None
+        for url in urls_to_try:
+            try:
+                candidate = self.client.head(url)
+            except HttpStatusError as exc:
+                if exc.status_code == 404:
+                    head_error = exc
+                    continue
+                head_error = exc
+                break
+            except Exception as exc:  # noqa: BLE001 - metadata best effort
+                head_error = exc
+                break
+            head = candidate
+            break
+
+        if head is None:
+            local = self.path_builder(output_dir, entry, None)
+            return CheckPlanItem(
+                dataset=dataset,
+                id=eid,
+                url=str(entry["url"]),
+                partition=partition,
+                local_path=str(local),
+                remote_etag=None,
+                remote_last_modified=None,
+                remote_size=None,
+                local_exists=local.exists(),
+                action="download",
+                reason=f"metadata-unavailable: {head_error}",
+                entry=dict(entry),
+            )
+
+        etag = head.headers.get("ETag")
+        size_raw = head.headers.get("Content-Length")
+        try:
+            size = int(size_raw) if size_raw else None
+        except (TypeError, ValueError):
+            size = None
+        last_modified = _parse_head_date(head.headers.get("Last-Modified"))
+        local = self.path_builder(output_dir, entry, last_modified)
+        sidecar = manifest_sidecar_path(local)
+        exists = local.exists() or sidecar.exists()
+        if exists and not is_remote_more_recent(head, local):
+            if local.exists():
+                action, reason = "skip-up-to-date", "local-fresh"
+            else:
+                action, reason = "skip-up-to-date", "manifest-fresh"
+        else:
+            action = "download"
+            reason = "not-present" if not exists else "remote-newer"
+        return CheckPlanItem(
+            dataset=dataset,
+            id=eid,
+            url=str(head.url),
+            partition=partition,
+            local_path=str(local),
+            remote_etag=etag,
+            remote_last_modified=head.headers.get("Last-Modified"),
+            remote_size=size,
+            local_exists=exists,
+            action=action,
+            reason=reason,
+            entry=dict(entry),
+        )
+
+    def check_datasets(
+        self,
+        entries: list[dict[str, Any]],
+        output_dir: Path,
+        workers: int = 4,
+    ) -> CheckPlan:
+        """Checks freshness for a list of dataset entries (no downloads).
+
+        Args:
+            entries: List of dataset entries to check.
+            output_dir: The base directory used for path computation.
+            workers: Maximum number of parallel checks.
+
+        Returns:
+            A :class:`CheckPlan` with one verdict per entry.
+        """
+        results: list[CheckPlanItem | None] = [None] * len(entries)
+
+        def _worker(index: int, entry: dict[str, Any]) -> None:
+            results[index] = self.check_entry(entry, output_dir)
+            if (index + 1) % 100 == 0 or index + 1 == len(entries):
+                logger.info("[check] %d/%d verificados", index + 1, len(entries))
+
+        with graceful_executor(max_workers=workers) as executor:
+            try:
+                futures = {
+                    executor.submit(_worker, index, entry): index
+                    for index, entry in enumerate(entries)
+                }
+                for future in concurrent.futures.as_completed(futures):
+                    future.result()
+            except KeyboardInterrupt:
+                get_console().print("\n[yellow]Interrompido.[/yellow]")
+                raise typer.Exit(130) from None
+
+        generated = dt.datetime.now(dt.UTC).isoformat(timespec="seconds")
+        return CheckPlan(
+            fetcher=self.name,
+            output_dir=str(output_dir),
+            generated_at=generated,
+            items=[item for item in results if item is not None],
+        )
+
     def _build_commands(self) -> None:
         console = get_console()
 
@@ -716,6 +1074,15 @@ class FetcherApp:
             workers: Annotated[
                 int, typer.Option("--workers", help="Downloads paralelos")
             ] = 4,
+            from_plan: Annotated[
+                Path | None,
+                typer.Option(
+                    "--from-plan",
+                    help="Baixar somente as entradas com ação 'download' "
+                    "de um plano gerado por 'check' (ignora a seleção "
+                    "de grupos).",
+                ),
+            ] = None,
             verbose: Annotated[
                 bool, typer.Option("--verbose", help="Logs detalhados")
             ] = False,
@@ -723,14 +1090,28 @@ class FetcherApp:
             setup_rich_logging(verbose, console=console)
             actual_output = output or self.default_output
 
-            try:
-                target_groups = self.resolve_groups(groups)
-            except ValueError as exc:
-                console.print(f"[red]{exc}[/red]")
-                console.print(f"Grupos válidos: {', '.join(self.all_keys)}")
-                raise typer.Exit(1) from None
+            if from_plan is not None:
+                try:
+                    plan = CheckPlan.from_json(from_plan.read_text(encoding="utf-8"))
+                except (OSError, ValueError) as exc:
+                    console.print(f"[red]Plano inválido: {exc}[/red]")
+                    raise typer.Exit(1) from None
+                entries = [
+                    dict(item.entry) for item in plan.items if item.action == "download"
+                ]
+                console.print(
+                    f"[dim]Plano {from_plan}: {len(entries)} entrada(s) "
+                    f"com ação 'download' de {len(plan.items)} verificada(s).[/dim]"
+                )
+            else:
+                try:
+                    target_groups = self.resolve_groups(groups)
+                except ValueError as exc:
+                    console.print(f"[red]{exc}[/red]")
+                    console.print(f"Grupos válidos: {', '.join(self.all_keys)}")
+                    raise typer.Exit(1) from None
 
-            entries = [e for g in target_groups for e in self.list_datasets(g)]
+                entries = [e for g in target_groups for e in self.list_datasets(g)]
 
             if dry_run:
                 table = Table("Grupo", "ID", "URL", title="Arquivos a baixar (dry-run)")
@@ -752,6 +1133,49 @@ class FetcherApp:
                 for eid, emsg in errors:
                     console.print(f"  {eid}: {emsg}")
 
+        @self.app.command("check")
+        def check(
+            groups: Annotated[
+                list[str] | None,
+                typer.Argument(
+                    help="Grupos a verificar. Use 'list' para ver grupos disponíveis. Padrão: todos."
+                ),
+            ] = None,
+            output: Annotated[
+                Path | None, typer.Option("-o", "--output", help="Diretório de saída")
+            ] = None,
+            workers: Annotated[
+                int, typer.Option("--workers", help="Verificações paralelas")
+            ] = 4,
+            as_json: Annotated[
+                bool,
+                typer.Option(
+                    "--json",
+                    help="Imprime o plano em JSON (para 'sync --from-plan')",
+                ),
+            ] = False,
+            verbose: Annotated[
+                bool, typer.Option("--verbose", help="Logs detalhados")
+            ] = False,
+        ) -> None:
+            setup_rich_logging(verbose, console=console)
+            actual_output = output or self.default_output
+
+            try:
+                target_groups = self.resolve_groups(groups)
+            except ValueError as exc:
+                console.print(f"[red]{exc}[/red]")
+                console.print(f"Grupos válidos: {', '.join(self.all_keys)}")
+                raise typer.Exit(1) from None
+
+            entries = [e for g in target_groups for e in self.list_datasets(g)]
+            plan = self.check_datasets(entries, actual_output, workers=workers)
+
+            if as_json:
+                print(plan.to_json())
+            else:
+                plan.render_table()
+
         @self.app.command("list")
         def cmd_list(
             verbose: Annotated[

{quantilica_cli-0.9.1 → quantilica_cli-0.10.1}/src/quantilica/cli/sources.py

@@ -37,6 +37,7 @@ SOURCES_REGISTRY: dict[str, str] = {
     "rtn": "rtn-fetcher",
     "sidra": "sidra-fetcher",
     "td": "tesouro-direto-fetcher",
+    "tse": "tse-fetcher",
 }
 
 

{quantilica_cli-0.9.1 → quantilica_cli-0.10.1}/tests/test_sdk.py

@@ -3,16 +3,21 @@
 from __future__ import annotations
 
 import datetime as dt
+import json
 from pathlib import Path
 from typing import Annotated
 
+import httpx2
 import pytest
 import typer
+from quantilica.core.http import HttpClient
 from typer.testing import CliRunner
 
 from quantilica.cli.sdk import (
+    CheckPlan,
     DataRepository,
     FetcherApp,
+    default_client,
     default_path_builder,
     make_resolve_groups,
 )
@@ -275,3 +280,220 @@ def test_builtin_list():
     result = runner.invoke(app.app, ["list"])
     assert result.exit_code == 0, result.output
     assert "2 dataset(s) no catálogo." in result.output
+
+
+# ---------------------------------------------------------------
+# check (verificação remoto × local, sem download) + sync --from-plan
+# ---------------------------------------------------------------
+
+
+def _head_handler(payload: bytes = b"0123456789"):
+    def handler(request):
+        if request.method == "HEAD":
+            return httpx2.Response(
+                200,
+                headers={
+                    "Content-Length": str(len(payload)),
+                    "Last-Modified": "Mon, 01 Jan 2024 00:00:00 GMT",
+                    "ETag": '"abc123"',
+                },
+            )
+        return httpx2.Response(200, content=payload)
+
+    return handler
+
+
+def _mock_client(payload: bytes = b"0123456789") -> HttpClient:
+    return HttpClient(
+        attempts=1, transport=httpx2.MockTransport(_head_handler(payload))
+    )
+
+
+def test_check_entry_missing_downloads(tmp_path: Path):
+    app = make_app(client=_mock_client())
+    entry = sample_list_datasets("exp")[0]
+    item = app.check_entry(entry, tmp_path)
+    assert item.action == "download"
+    assert item.reason == "not-present"
+    assert item.remote_etag == '"abc123"'
+    assert item.remote_size == 10
+    assert item.remote_last_modified == "Mon, 01 Jan 2024 00:00:00 GMT"
+    assert item.local_exists is False
+
+
+def test_check_entry_fresh_skips(tmp_path: Path):
+    from quantilica.cli.sdk import default_path_builder
+
+    app = make_app(client=_mock_client())
+    entry = sample_list_datasets("exp")[0]
+    local = default_path_builder(tmp_path, entry, dt.date(2024, 1, 1))
+    local.parent.mkdir(parents=True, exist_ok=True)
+    local.write_bytes(b"0123456789")
+    item = app.check_entry(entry, tmp_path)
+    assert item.action == "skip-up-to-date"
+    assert item.reason == "local-fresh"
+    assert item.local_exists is True
+
+
+def test_check_entry_head_error_downloads(tmp_path: Path):
+    def handler(request):
+        raise httpx2.ConnectError("down")
+
+    app = make_app(
+        client=HttpClient(attempts=1, transport=httpx2.MockTransport(handler))
+    )
+    entry = sample_list_datasets("exp")[0]
+    item = app.check_entry(entry, tmp_path)
+    assert item.action == "download"
+    assert item.reason.startswith("metadata-unavailable")
+
+
+def test_check_plan_json_roundtrip(tmp_path: Path):
+    app = make_app(client=_mock_client())
+    entries = sample_list_datasets("exp")
+    plan = app.check_datasets(entries, tmp_path, workers=1)
+    restored = CheckPlan.from_json(plan.to_json())
+    assert restored.fetcher == plan.fetcher
+    assert [it.id for it in restored.items] == [it.id for it in plan.items]
+    assert restored.items[0].entry["url"] == entries[0]["url"]
+
+
+def test_check_plan_from_json_rejects_garbage():
+    with pytest.raises(ValueError, match="not a check plan"):
+        CheckPlan.from_json('{"foo": 1}')
+    with pytest.raises(ValueError, match="not a check plan"):
+        CheckPlan.from_json("not json")
+
+
+def test_builtin_check_command(tmp_path: Path):
+    app = make_app(client=_mock_client())
+    result = runner.invoke(app.app, ["check", "exp", "-o", str(tmp_path)])
+    assert result.exit_code == 0, result.output
+    assert "download" in result.output
+
+
+def test_builtin_check_json_output(tmp_path: Path):
+    app = make_app(client=_mock_client())
+    result = runner.invoke(app.app, ["check", "exp", "-o", str(tmp_path), "--json"])
+    assert result.exit_code == 0, result.output
+    data = json.loads(result.output)
+    assert data["items"][0]["action"] == "download"
+
+
+def test_builtin_sync_from_plan_downloads_only_planned(tmp_path: Path):
+    from quantilica.cli.sdk import default_path_builder
+
+    payload = b"0123456789"
+    app = make_app(client=_mock_client(payload))
+    fresh_entry = sample_list_datasets("exp")[0]
+    stale_entry = dict(sample_list_datasets("imp")[0])
+    local = default_path_builder(tmp_path, fresh_entry, dt.date(2024, 1, 1))
+    local.parent.mkdir(parents=True, exist_ok=True)
+    local.write_bytes(payload)
+
+    plan = app.check_datasets([fresh_entry, stale_entry], tmp_path, workers=1)
+    actions = {it.id: it.action for it in plan.items}
+    assert actions == {"exp-monthly": "skip-up-to-date", "imp-monthly": "download"}
+
+    plan_file = tmp_path / "plan.json"
+    plan_file.write_text(plan.to_json(), encoding="utf-8")
+    result = runner.invoke(
+        app.app, ["sync", "--from-plan", str(plan_file), "-o", str(tmp_path)]
+    )
+    assert result.exit_code == 0, result.output
+    assert "1/1 arquivo(s) baixado(s)" in result.output
+
+
+def test_builtin_sync_from_plan_invalid_file(tmp_path: Path):
+    app = make_app(client=_mock_client())
+    bad = tmp_path / "bad.json"
+    bad.write_text('{"nope": true}', encoding="utf-8")
+    result = runner.invoke(app.app, ["sync", "--from-plan", str(bad)])
+    assert result.exit_code == 1
+    assert "Plano inválido" in result.output
+
+
+# ---------------------------------------------------------------
+# default_client: overrides via ambiente
+# ---------------------------------------------------------------
+
+
+def test_default_client_verify_defaults_true(monkeypatch):
+    monkeypatch.delenv("QUANTILICA_SSL_VERIFY", raising=False)
+    monkeypatch.delenv("QUANTILICA_CA_BUNDLE", raising=False)
+    assert default_client().verify is True
+
+
+def test_default_client_verify_env_disable(monkeypatch):
+    monkeypatch.delenv("QUANTILICA_CA_BUNDLE", raising=False)
+    monkeypatch.setenv("QUANTILICA_SSL_VERIFY", "0")
+    assert default_client().verify is False
+
+
+def test_default_client_attempts_env_override(monkeypatch):
+    monkeypatch.delenv("QUANTILICA_SSL_VERIFY", raising=False)
+    monkeypatch.delenv("QUANTILICA_CA_BUNDLE", raising=False)
+    monkeypatch.setenv("QUANTILICA_HTTP_ATTEMPTS", "9")
+    assert default_client().attempts == 9
+
+
+def test_check_entry_ephemeral_manifest_fresh(tmp_path: Path):
+    """Raw file deleted but sidecar manifest survives -> manifest-fresh skip."""
+    from quantilica.core.manifests import (
+        DownloadManifest,
+        SourceMetadata,
+        write_manifest_sidecar,
+    )
+
+    app = make_app(client=_mock_client())
+    entry = sample_list_datasets("exp")[0]
+    local = default_path_builder(tmp_path, entry, dt.date(2024, 1, 1))
+    local.parent.mkdir(parents=True, exist_ok=True)
+    write_manifest_sidecar(
+        local,
+        DownloadManifest(
+            source_id="src",
+            dataset_id="ds",
+            url=entry["url"],
+            fetched_at="2024-01-02T00:00:00+00:00",
+            sha256="0" * 64,
+            size_bytes=10,
+            source_meta=SourceMetadata(
+                etag='"abc123"',
+                last_modified="Mon, 01 Jan 2024 00:00:00 GMT",
+            ),
+        ),
+    )
+    item = app.check_entry(entry, tmp_path)
+    assert item.action == "skip-up-to-date"
+    assert item.reason == "manifest-fresh"
+    assert item.local_exists is True
+
+
+def test_check_entry_ephemeral_stale_downloads(tmp_path: Path):
+    """Sidecar with stale metadata (remote ETag differs) -> download."""
+    from quantilica.core.manifests import (
+        DownloadManifest,
+        SourceMetadata,
+        write_manifest_sidecar,
+    )
+
+    app = make_app(client=_mock_client())
+    entry = sample_list_datasets("exp")[0]
+    local = default_path_builder(tmp_path, entry, dt.date(2024, 1, 1))
+    local.parent.mkdir(parents=True, exist_ok=True)
+    write_manifest_sidecar(
+        local,
+        DownloadManifest(
+            source_id="src",
+            dataset_id="ds",
+            url=entry["url"],
+            fetched_at="2023-12-31T00:00:00+00:00",
+            sha256="0" * 64,
+            size_bytes=10,
+            source_meta=SourceMetadata(etag='"outdated"', last_modified=None),
+        ),
+    )
+    item = app.check_entry(entry, tmp_path)
+    assert item.action == "download"
+    assert item.reason == "remote-newer"