bloomctl 0.1.0a1__tar.gz

bloomctl-0.1.0a1/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: bloomctl
+Version: 0.1.0a1
+Summary: Bloom command-line tool for Bloom Database
+Keywords: bloom,cli,plant-phenotyping,cylinder
+Author: Salk Harnessing Plants Initiative
+License-Expression: BSD-2-Clause
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: supabase>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: cryptography>=48.0.1
+Requires-Dist: pytest>=8.3 ; extra == 'test'
+Requires-Python: >=3.11
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# bloomctl
+
+Python command-line tool for the Bloom server — download cylinder experiments
+(metadata + images) and manage credentials. Successor to the Node
+`@salk-hpi/bloom-cli`. Tracked by issue #347.
+
+Full install + usage docs land with the `download` command.

bloomctl-0.1.0a1/README.md

@@ -0,0 +1,7 @@
+# bloomctl
+
+Python command-line tool for the Bloom server — download cylinder experiments
+(metadata + images) and manage credentials. Successor to the Node
+`@salk-hpi/bloom-cli`. Tracked by issue #347.
+
+Full install + usage docs land with the `download` command.

bloomctl-0.1.0a1/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "bloomctl"
+version = "0.1.0a1"
+description = "Bloom command-line tool for Bloom Database"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "BSD-2-Clause"
+authors = [{ name = "Salk Harnessing Plants Initiative" }]
+keywords = ["bloom", "cli", "plant-phenotyping","cylinder"]
+classifiers = [
+    "Programming Language :: Python :: 3.11",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "click>=8.1",
+    "rich>=13.0",
+    # /client-info bootstrap fetch (login).
+    "httpx>=0.27",
+    # Supabase PostgREST + Storage client (auth, metadata query, image signing).
+    "supabase>=2.0.0",
+    "python-dotenv>=1.0.0",
+    # Security floor for the supabase auth/JWT transitive dep, per repo convention
+    # (open floor past the upstream CVE fix; see bloommcp/pyproject.toml).
+    "cryptography>=48.0.1",
+]
+
+[project.scripts]
+bloomctl = "bloomctl.cli:cli"
+
+# Test stack lives in the `test` extra (not a dev dependency-group) so CI invokes
+# it as `uv run --extra test pytest` — the repo-wide convention enforced by
+# tests/unit/test_ci_workflow_uv_conventions.py.
+[project.optional-dependencies]
+test = [
+    "pytest>=8.3",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.0,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "bloomctl"
+module-root = "src"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+
+# Lint config lives here (matching bloommcp); CI runs ruff via `uvx ruff`
+# pinned to the repo's .pre-commit-config.yaml version, so ruff is not a
+# project dependency.
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+# Line length is owned by the formatter (black), per ruff's guidance for
+# formatter-managed projects — so E501 is not linted here.
+ignore = ["E501"]

bloomctl-0.1.0a1/src/bloomctl/__init__.py

@@ -0,0 +1,11 @@
+"""bloomctl — the Bloom command-line tool (Python successor to @salk-hpi/bloom-cli)."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # Single source of truth: the version comes from the installed package
+    # metadata (built from pyproject.toml), so `uv version --bump` can't drift
+    # from what `bloomctl --version` prints.
+    __version__ = version("bloomctl")
+except PackageNotFoundError:  # running from a source tree that isn't installed
+    __version__ = "0.0.0+unknown"

bloomctl-0.1.0a1/src/bloomctl/auth.py

@@ -0,0 +1,68 @@
+"""Auth helpers for bloomctl: anon-key bootstrap + login verification.
+
+Heavy imports (httpx, supabase) are deferred into the functions that use them so
+importing this module (e.g. for ``bloomctl --help``) stays fast.
+"""
+
+from __future__ import annotations
+
+DEFAULT_SERVER = "https://bloom.salk.edu"
+
+
+class AuthError(Exception):
+    """Login bootstrap or authentication failed."""
+
+
+def fetch_anon_credentials(
+    server: str = DEFAULT_SERVER, *, timeout: float = 10.0
+) -> tuple[str, str]:
+    """Fetch ``(api_url, anon_key)`` from ``<server>/api/client-info``.
+
+    Mirrors the legacy CLI bootstrap. Raises :class:`AuthError` if the endpoint
+    is unreachable (e.g. a 401 while the Kong basic-auth gate still covers it),
+    pointing the user at the ``--api-url`` / ``--anon-key`` overrides.
+    """
+    import httpx
+
+    url = f"{server.rstrip('/')}/api/client-info"
+    try:
+        resp = httpx.get(url, timeout=timeout)
+        resp.raise_for_status()
+        data = resp.json()
+        return data["api_url"], data["anon_key"]
+    except (httpx.HTTPError, KeyError, ValueError) as exc:
+        raise AuthError(
+            f"could not fetch client config from {url}: {exc}. "
+            "Pass --api-url and --anon-key to skip this fetch."
+        ) from exc
+
+
+def verify_credentials(api_url: str, anon_key: str, email: str, password: str) -> None:
+    """Authenticate against Supabase; raise :class:`AuthError` on failure."""
+    from supabase import create_client
+
+    client = create_client(api_url, anon_key)
+    try:
+        res = client.auth.sign_in_with_password({"email": email, "password": password})
+    except Exception as exc:  # supabase raises various AuthApiError subtypes
+        raise AuthError(f"sign-in failed: {exc}") from exc
+    if not getattr(res, "session", None):
+        raise AuthError("sign-in failed — check email/password")
+
+
+def make_authed_client(creds):
+    """Create a Supabase client signed in as ``creds`` (for authenticated queries)."""
+    from supabase import create_client
+
+    client = create_client(creds.api_url, creds.anon_key)
+    try:
+        res = client.auth.sign_in_with_password(
+            {"email": creds.email, "password": creds.password}
+        )
+    except Exception as exc:
+        raise AuthError(f"sign-in failed: {exc}") from exc
+    if not getattr(res, "session", None):
+        raise AuthError(
+            "sign-in failed — check stored credentials (try `bloomctl login`)"
+        )
+    return client

bloomctl-0.1.0a1/src/bloomctl/cli.py

@@ -0,0 +1,219 @@
+"""bloomctl command group (entry point ``bloomctl = bloomctl.cli:cli``)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from . import __version__
+from .auth import DEFAULT_SERVER
+from .credentials import DEFAULT_PROFILE
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="bloomctl")
+def cli() -> None:
+    """Bloom command-line tool"""
+
+
+@cli.command()
+@click.option(
+    "--server",
+    default=DEFAULT_SERVER,
+    show_default=True,
+    help="Which Bloom server to log in to — prod by default; pass a staging/local URL to switch.",
+)
+@click.option(
+    "--api-url",
+    default=None,
+    help="Supabase API URL (e.g. https://bloom.salk.edu/api). Pair with --anon-key to skip the /client-info fetch.",
+)
+@click.option(
+    "--anon-key",
+    default=None,
+    help="Public anon key — pair with --api-url to supply credentials manually when /client-info can't be fetched (interim / local / offline).",
+)
+@click.option(
+    "-p",
+    "--profile",
+    default=DEFAULT_PROFILE,
+    show_default=True,
+    help="Credentials profile to write (credentials.txt for prod).",
+)
+@click.option("--email", default=None, help="Login email (prompted if omitted).")
+@click.option("--password", default=None, help="Login password (prompted if omitted).")
+def login(
+    server: str,
+    api_url: str | None,
+    anon_key: str | None,
+    profile: str,
+    email: str | None,
+    password: str | None,
+) -> None:
+    """Log in to Bloom and save credentials to ~/.bloom/credentials.txt."""
+    from . import auth
+    from .credentials import Credentials, save_credentials
+
+    if not email:
+        email = click.prompt("Email")
+    if not password:
+        password = click.prompt("Password", hide_input=True)
+
+    # api_url + anon_key come from --api-url/--anon-key, else from /client-info.
+    if api_url and anon_key:
+        resolved_api_url, resolved_anon_key = api_url, anon_key
+    else:
+        try:
+            resolved_api_url, resolved_anon_key = auth.fetch_anon_credentials(server)
+        except auth.AuthError as exc:
+            raise click.ClickException(str(exc)) from exc
+
+    try:
+        auth.verify_credentials(resolved_api_url, resolved_anon_key, email, password)
+    except auth.AuthError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    path = save_credentials(
+        Credentials(
+            api_url=resolved_api_url,
+            anon_key=resolved_anon_key,
+            email=email,
+            password=password,
+        ),
+        profile=profile,
+    )
+    click.echo(f"Logged in as {email}. Credentials saved to {path}.")
+
+
+@cli.command()
+@click.argument("out_dir", type=click.Path(file_okay=False, path_type=Path))
+@click.option(
+    "--experiment-id",
+    "--experiment_id",
+    "experiment_id",
+    type=int,
+    default=None,
+    help="Download a whole experiment by ID (mutually exclusive with --scan-id).",
+)
+@click.option(
+    "--scan-id",
+    "--scan_id",
+    "scan_id",
+    type=int,
+    default=None,
+    help="Download a single scan by ID (mutually exclusive with --experiment-id).",
+)
+@click.option(
+    "-p",
+    "--profile",
+    default=DEFAULT_PROFILE,
+    show_default=True,
+    help="Credentials profile to use.",
+)
+@click.option(
+    "--meta-only",
+    "--meta_only",
+    "meta_only",
+    is_flag=True,
+    help="Write scans.csv only; skip image download.",
+)
+@click.option(
+    "--plant-qr-code",
+    "--plant_qr_code",
+    "plant_qr_code",
+    default=None,
+    help="Restrict to a single plant QR code.",
+)
+@click.option(
+    "--plant-age-min",
+    "--plant_age_min",
+    "plant_age_min",
+    type=int,
+    default=0,
+    show_default=True,
+    help="Minimum plant age in days.",
+)
+@click.option(
+    "--plant-age-max",
+    "--plant_age_max",
+    "plant_age_max",
+    type=int,
+    default=1000,
+    show_default=True,
+    help="Maximum plant age in days.",
+)
+@click.option(
+    "--limit",
+    type=int,
+    default=100000,
+    show_default=True,
+    help="Maximum number of scans to fetch.",
+)
+def download(
+    out_dir: Path,
+    experiment_id: int | None,
+    scan_id: int | None,
+    profile: str,
+    meta_only: bool,
+    plant_qr_code: str | None,
+    plant_age_min: int,
+    plant_age_max: int,
+    limit: int,
+) -> None:
+    """Download a cylinder experiment (--experiment-id) or a single scan (--scan-id):
+    metadata (scans.csv) and per-frame images."""
+    from . import auth
+    from . import download as dl
+    from .credentials import load_credentials
+
+    # Exactly one of --experiment-id / --scan-id.
+    if (experiment_id is None) == (scan_id is None):
+        raise click.UsageError("Pass exactly one of --experiment-id or --scan-id.")
+
+    try:
+        creds = load_credentials(profile)
+    except (FileNotFoundError, ValueError) as exc:
+        raise click.ClickException(f"{exc} — run `bloomctl login`.") from exc
+    try:
+        client = auth.make_authed_client(creds)
+    except auth.AuthError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    if scan_id is not None:
+        scan = dl.fetch_scan(client, scan_id)
+        if scan is None:
+            raise click.ClickException(f"Scan {scan_id} not found.")
+        scans = [scan]
+    else:
+        scans = dl.fetch_scans(
+            client,
+            experiment_id,
+            plant_qr_code=plant_qr_code,
+            plant_age_min=plant_age_min,
+            plant_age_max=plant_age_max,
+            limit=limit,
+        )
+    genotypes = dl.fetch_genotypes(client, [s.get("accession_id") for s in scans])
+    rows = [dl.build_scan_row(s, genotypes.get(s.get("accession_id"))) for s in scans]
+
+    out = Path(out_dir)
+    csv_path = out / "scans.csv"
+    dl.write_scans_csv(rows, csv_path)
+    click.echo(f"Wrote {len(rows)} scans -> {csv_path}")
+
+    if meta_only:
+        return
+
+    result = dl.download_images(client, scans, out)
+    log_path = out / "download_log.txt"
+    dl.write_download_log(result, log_path)
+    click.echo(
+        f"Downloaded {result.ok}/{result.total} image frames -> {out / 'images'}  (log: {log_path})"
+    )
+    if result.failed:
+        # Partial download: surface it and exit non-zero so a pipeline knows the
+        # output is incomplete (the log lists every failed frame).
+        raise click.ClickException(
+            f"{result.failed} of {result.total} frames failed to download — see {log_path}"
+        )

bloomctl-0.1.0a1/src/bloomctl/credentials.py

@@ -0,0 +1,104 @@
+"""Profile-based credential storage for bloomctl.
+
+Mirrors the legacy ``packages/bloom-fs`` format: a dotenv file at
+``~/.bloom/credentials.txt`` (profile ``prod``) or ``~/.bloom/credentials.<name>.txt``
+(profile ``<name>``), with keys BLOOM_EMAIL / BLOOM_PASSWORD / BLOOM_API_URL /
+BLOOM_ANON_KEY.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from dotenv import dotenv_values
+
+DEFAULT_PROFILE = "prod"
+_REQUIRED_KEYS = ("BLOOM_API_URL", "BLOOM_ANON_KEY", "BLOOM_EMAIL", "BLOOM_PASSWORD")
+# credentials.txt -> profile "prod"; credentials.<name>.txt -> profile "<name>"
+_CRED_RE = re.compile(r"^credentials(?:\.(.+))?\.txt$")
+
+
+@dataclass(frozen=True)
+class Credentials:
+    api_url: str
+    anon_key: str
+    email: str
+    password: str
+
+
+def default_config_dir() -> Path:
+    """The Bloom config directory (``~/.bloom``)."""
+    return Path.home() / ".bloom"
+
+
+def filename_for_profile(profile: str) -> str:
+    """Filename a profile is *written* to (`prod` -> credentials.txt)."""
+    return "credentials.txt" if profile == DEFAULT_PROFILE else f"credentials.{profile}.txt"
+
+
+def available_profiles(config_dir: Path) -> dict[str, Path]:
+    """Map profile name -> credentials file found in ``config_dir``.
+
+    Both ``credentials.txt`` and ``credentials.prod.txt`` resolve to ``prod`` —
+    having both is ambiguous and raises.
+    """
+    profiles: dict[str, Path] = {}
+    for path in sorted(config_dir.glob("credentials*.txt")):
+        match = _CRED_RE.match(path.name)
+        if not match:
+            continue
+        name = match.group(1) or DEFAULT_PROFILE
+        if name in profiles:
+            raise ValueError(
+                f"Conflicting credential files for profile '{name}': "
+                f"{profiles[name].name} and {path.name}. Keep only one."
+            )
+        profiles[name] = path
+    return profiles
+
+
+def resolve_profile_path(profile: str, config_dir: Path | None = None) -> Path:
+    """Path to the credentials file for ``profile``, or raise with a login hint."""
+    config_dir = config_dir or default_config_dir()
+    profiles = available_profiles(config_dir)
+    if profile not in profiles:
+        hint = "bloomctl login" + ("" if profile == DEFAULT_PROFILE else f" --profile {profile}")
+        raise FileNotFoundError(
+            f"No credentials for profile '{profile}'. Run `{hint}` "
+            f"(expected {config_dir / filename_for_profile(profile)})."
+        )
+    return profiles[profile]
+
+
+def load_credentials(profile: str = DEFAULT_PROFILE, config_dir: Path | None = None) -> Credentials:
+    """Load and validate the four credential keys for ``profile``."""
+    path = resolve_profile_path(profile, config_dir)
+    values = dotenv_values(path)
+    missing = [k for k in _REQUIRED_KEYS if not values.get(k)]
+    if missing:
+        raise ValueError(f"{path} is missing required keys: {', '.join(missing)}")
+    return Credentials(
+        api_url=values["BLOOM_API_URL"],
+        anon_key=values["BLOOM_ANON_KEY"],
+        email=values["BLOOM_EMAIL"],
+        password=values["BLOOM_PASSWORD"],
+    )
+
+
+def save_credentials(
+    creds: Credentials, profile: str = DEFAULT_PROFILE, config_dir: Path | None = None
+) -> Path:
+    """Write ``creds`` to the profile's dotenv file (creating ``config_dir``)."""
+    config_dir = config_dir or default_config_dir()
+    config_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+    path = config_dir / filename_for_profile(profile)
+    path.write_text(
+        f"BLOOM_EMAIL={creds.email}\n"
+        f"BLOOM_PASSWORD={creds.password}\n"
+        f"BLOOM_API_URL={creds.api_url}\n"
+        f"BLOOM_ANON_KEY={creds.anon_key}\n"
+    )
+    path.chmod(0o600)
+    return path

bloomctl-0.1.0a1/src/bloomctl/download.py

@@ -0,0 +1,211 @@
+"""Cylinder experiment download: metadata (scans.csv) + per-frame images.
+
+Pure helpers (column mapping, paths) are separated from the supabase/storage I/O
+so the contract is unit-testable without a live server.
+"""
+
+from __future__ import annotations
+
+import csv
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+# scans.csv schema: (output column, source key in a cyl_scans_extended row).
+# Order matches the legacy CLI's predict-container contract; `genotype` is
+# inserted after `accession_id`, and `scan_path` is derived (relative).
+_COLUMNS: list[tuple[str, str | None]] = [
+    ("scan_id", "scan_id"),
+    ("plant_qr_code", "qr_code"),
+    ("scan_path", None),  # derived
+    ("scanner_id", "scanner_id"),
+    ("species_id", "species_id"),
+    ("species_name", "species_name"),
+    ("species_genus", "species_genus"),
+    ("species_species", "species_species"),
+    ("uploaded_at", "uploaded_at"),
+    ("wave_id", "wave_id"),
+    ("wave_number", "wave_number"),
+    ("wave_name", "wave_name"),
+    ("accession_id", "accession_id"),
+    ("genotype", None),  # derived (accessions.name)
+    ("date_scanned", "date_scanned"),
+    ("experiment_id", "experiment_id"),
+    ("experiment_name", "experiment_name"),
+    ("germ_day", "germ_day"),
+    ("germ_day_color", "germ_day_color"),
+    ("phenotyper_id", "phenotyper_id"),
+    ("plant_age_days", "plant_age_days"),
+    ("plant_id", "plant_id"),
+]
+CSV_COLUMNS: list[str] = [name for name, _ in _COLUMNS]
+
+
+def scan_relative_dir(scan: dict[str, Any]) -> str:
+    """Per-scan image dir, relative to the output dir (where scans.csv lives)."""
+    wave = scan.get("wave_number") or 0
+    return f"images/Wave{wave}/Day{scan.get('plant_age_days')}_{scan.get('date_scanned')}/{scan.get('qr_code')}"
+
+
+def build_scan_row(scan: dict[str, Any], genotype: str | None) -> dict[str, Any]:
+    """Map a cyl_scans_extended row to the ordered scans.csv row."""
+    row: dict[str, Any] = {}
+    for name, key in _COLUMNS:
+        if name == "scan_path":
+            row[name] = scan_relative_dir(scan)
+        elif name == "genotype":
+            row[name] = genotype if genotype is not None else ""
+        else:
+            row[name] = scan.get(key, "")
+    return row
+
+
+def write_scans_csv(rows: list[dict[str, Any]], path: Path) -> None:
+    """Write rows to scans.csv with the fixed column order."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", newline="", encoding="utf-8") as fh:
+        writer = csv.DictWriter(fh, fieldnames=CSV_COLUMNS)
+        writer.writeheader()
+        writer.writerows(rows)
+
+
+def image_dest(out_dir: Path, scan: dict[str, Any], image: dict[str, Any]) -> Path:
+    """Absolute destination for one frame, preserving its real extension."""
+    ext = Path(image["object_path"]).suffix or ".png"
+    return Path(out_dir) / scan_relative_dir(scan) / f"{image['frame_number']}{ext}"
+
+
+# --- supabase / storage I/O -------------------------------------------------
+
+
+def fetch_scans(
+    client: Any,
+    experiment_id: int,
+    *,
+    plant_qr_code: str | None = None,
+    plant_age_min: int = 0,
+    plant_age_max: int = 1000,
+    limit: int = 100000,
+) -> list[dict[str, Any]]:
+    """Query cyl_scans_extended for an experiment (legacy filter semantics)."""
+    query = (
+        client.table("cyl_scans_extended")
+        .select("*")
+        .eq("experiment_id", experiment_id)
+    )
+    if plant_qr_code:
+        query = query.eq("qr_code", plant_qr_code)
+    else:
+        query = query.gte("plant_age_days", plant_age_min).lte(
+            "plant_age_days", plant_age_max
+        )
+    return query.limit(limit).execute().data or []
+
+
+def fetch_scan(client: Any, scan_id: Any) -> dict[str, Any] | None:
+    """Single cyl_scans_extended row for one scan_id, or None if not found."""
+    rows = (
+        client.table("cyl_scans_extended")
+        .select("*")
+        .eq("scan_id", scan_id)
+        .limit(1)
+        .execute()
+        .data
+        or []
+    )
+    return rows[0] if rows else None
+
+
+def fetch_genotypes(client: Any, accession_ids: list[Any]) -> dict[Any, str]:
+    """Map accession_id -> accessions.name for the given ids."""
+    ids = sorted({a for a in accession_ids if a is not None})
+    if not ids:
+        return {}
+    rows = (
+        client.table("accessions").select("id, name").in_("id", ids).execute().data
+        or []
+    )
+    return {row["id"]: row["name"] for row in rows}
+
+
+def fetch_images(client: Any, scan_id: Any) -> list[dict[str, Any]]:
+    """Frames for a scan, ordered by frame_number."""
+    return (
+        client.table("cyl_images")
+        .select("*")
+        .eq("scan_id", scan_id)
+        .order("frame_number")
+        .execute()
+        .data
+        or []
+    )
+
+
+@dataclass
+class FrameResult:
+    """Outcome of one frame download."""
+
+    scan_id: Any
+    frame_number: Any
+    object_path: str
+    ok: bool
+    error: str = ""
+
+
+@dataclass
+class DownloadResult:
+    """Aggregate outcome of a `download_images` run."""
+
+    frames: list[FrameResult]
+
+    @property
+    def ok(self) -> int:
+        return sum(1 for f in self.frames if f.ok)
+
+    @property
+    def failed(self) -> int:
+        return sum(1 for f in self.frames if not f.ok)
+
+    @property
+    def total(self) -> int:
+        return len(self.frames)
+
+
+def download_images(client: Any, scans: list[dict[str, Any]], out_dir: Path) -> DownloadResult:
+    """Download every frame for every scan from Storage bucket `images`.
+
+    Each frame is downloaded independently: a failure is recorded, not raised, so
+    one bad frame (missing object, transient 5xx) can't abort the whole run.
+    Signs server-side via Supabase Storage (no MinIO secrets, no legacy Lambda).
+    """
+    bucket = client.storage.from_("images")
+    frames: list[FrameResult] = []
+    for scan in scans:
+        for image in fetch_images(client, scan["scan_id"]):
+            object_path = image.get("object_path", "")
+            result = FrameResult(scan.get("scan_id"), image.get("frame_number"), object_path, ok=False)
+            try:
+                data = bucket.download(object_path)
+                if data is None:
+                    raise ValueError("empty response from storage")
+                dest = image_dest(out_dir, scan, image)
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                dest.write_bytes(data)
+                result.ok = True
+            except Exception as exc:  # per-frame: record and continue
+                result.error = str(exc)
+            frames.append(result)
+    return DownloadResult(frames)
+
+
+def write_download_log(result: DownloadResult, path: Path) -> None:
+    """Write a per-frame download log (one line per frame) with a summary footer."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines = []
+    for f in result.frames:
+        line = f"{'OK  ' if f.ok else 'FAIL'} scan={f.scan_id} frame={f.frame_number} {f.object_path}"
+        if not f.ok:
+            line += f"  error={f.error}"
+        lines.append(line)
+    lines.append(f"\nSummary: {result.ok} downloaded, {result.failed} failed, {result.total} total")
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")