dexverse-cli 0.0.2__py3-none-any.whl

dexverse/__init__.py

@@ -0,0 +1,54 @@
+"""DexVerse Downloader — S3-compatible dataset downloader.
+
+Public API:
+
+    from dexverse import DexVerseClient, download_manifest
+    from dexverse import Manifest, FileSpec
+"""
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+import tomlkit
+
+from .client import DexVerseClient, DexVerseError, download_manifest
+from .manifest import (
+    FileSpec,
+    Manifest,
+    Storage,
+    StorageCredentials,
+    DownloadOptions,
+    resolve_dest,
+    resolve_relpath,
+)
+
+def _resolve_version() -> str:
+    """Read the single source version in development, package metadata otherwise."""
+    pyproject = Path(__file__).resolve().parent.parent / "pyproject.toml"
+    if pyproject.is_file():
+        document = tomlkit.parse(pyproject.read_text(encoding="utf-8"))
+        project_version = document.get("project", {}).get("version")
+        if isinstance(project_version, str):
+            return project_version
+    try:
+        return version("dexverse")
+    except PackageNotFoundError:
+        return "0.0.0+unknown"
+
+
+__version__ = _resolve_version()
+
+__all__ = [
+    "DexVerseClient",
+    "DexVerseError",
+    "download_manifest",
+    "Manifest",
+    "FileSpec",
+    "Storage",
+    "StorageCredentials",
+    "DownloadOptions",
+    "resolve_dest",
+    "resolve_relpath",
+    "__version__",
+]

dexverse/cli.py

@@ -0,0 +1,422 @@
+"""Command-line interface (doc §10).
+
+    dexverse-dl login   --server URL [--token TOKEN]
+    dexverse-dl download --manifest PATH | --task ID  --out DIR
+                         [--parallel N] [--backend http|python|s5cmd]
+                         [--server URL] [--no-verify] [--deep]
+    dexverse-dl verify  --manifest PATH --out DIR [--deep]
+    dexverse-dl repair  --manifest PATH --out DIR [--backend http|python|s5cmd] [--deep]
+    dexverse-dl convert -i PATH | --input-dir DIR -o DIR [--strategy default]
+                        # 还原下载的 HDF5 为可训练原始数据（图片 + pose_record JSON）
+"""
+from __future__ import annotations
+
+import threading
+import time
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.filesize import decimal
+from rich.progress import (
+    BarColumn,
+    Progress,
+    SpinnerColumn,
+    TextColumn,
+)
+from rich.table import Table
+
+from .client import DexVerseClient, DexVerseError, download_manifest
+from .config import config_path, save_profile
+from .downloader.manager import DownloadManager, repair as repair_fn
+from .downloader.s5cmd_backend import S5CmdNotAvailable
+from .downloader.verify import verify_files, summarize
+from .manifest import Manifest
+from .convert import convert_batch as convert_hdf5_batch
+from .convert.hdf5_to_raw import DefaultAlignmentStrategy
+
+app = typer.Typer(
+    name="dexverse-dl",
+    help="DexVerse dataset downloader (S3-compatible).",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+class _RichDownloadProgress:
+    """Render aggregate byte progress for a single manager run."""
+
+    def __init__(self) -> None:
+        self._progress = Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            TextColumn("{task.completed:.0f}/{task.total:.0f} files"),
+            BarColumn(),
+            TextColumn("{task.fields[transfer]}"),
+            console=console,
+        )
+        self._task_id: Optional[int] = None
+        self._downloaded_bytes = 0
+        self._total_bytes: Optional[int] = None
+        self._started_at = 0.0
+        self._lock = threading.Lock()
+
+    def start(self, *, total_bytes: Optional[int], total_files: int) -> None:
+        self._total_bytes = total_bytes
+        self._started_at = time.monotonic()
+        self._progress.start()
+        self._task_id = self._progress.add_task(
+            "Downloading",
+            total=total_files,
+            transfer="0 bytes",
+        )
+
+    def advance(self, bytes_count: int) -> None:
+        if self._task_id is not None and bytes_count > 0:
+            with self._lock:
+                self._downloaded_bytes += bytes_count
+                downloaded = self._downloaded_bytes
+            elapsed = time.monotonic() - self._started_at
+            amount = decimal(downloaded)
+            if self._total_bytes is not None:
+                amount = f"{amount}/{decimal(self._total_bytes)}"
+            speed = decimal(downloaded / elapsed) if elapsed > 0 else "0 bytes"
+            self._progress.update(
+                self._task_id,
+                transfer=f"{amount} • {speed}/s",
+            )
+
+    def complete_file(self) -> None:
+        if self._task_id is not None:
+            self._progress.advance(self._task_id, 1)
+
+    def finish(self) -> None:
+        self._progress.stop()
+
+
+# --------------------------------------------------------------------------- #
+# login
+# --------------------------------------------------------------------------- #
+@app.command(help="Save a server + token to the active profile.")
+def login(
+    server: str = typer.Option(..., "--server", "-s", help="Platform base URL"),
+    token: Optional[str] = typer.Option(
+        None, "--token", "-t", help="Bearer token (dev-token in mock mode)"
+    ),
+    profile: str = typer.Option("default", "--profile", help="Profile name"),
+):
+    save_profile(profile, server, token)
+    console.print(f"[green]✓[/green] Saved profile [bold]{profile}[/bold] → {server}")
+    console.print(f"  config: {config_path()}")
+
+
+# --------------------------------------------------------------------------- #
+# download
+# --------------------------------------------------------------------------- #
+@app.command(help="Download by --manifest (Phase 0) or --task (Phase 1+).")
+def download(
+    out: Path = typer.Option(..., "--out", "-o", help="Local download root"),
+    manifest: Optional[Path] = typer.Option(
+        None, "--manifest", "-m",
+        help="Local manifest.json path, or '-' to read JSON from stdin",
+    ),
+    task: Optional[str] = typer.Option(None, "--task", help="Platform download taskId"),
+    parallel: Optional[int] = typer.Option(None, "--parallel", "-p"),
+    backend: str = typer.Option("http", "--backend", "-b",
+                                help="http | python | s5cmd"),
+    server: Optional[str] = typer.Option(None, "--server", help="Override profile server"),
+    token: Optional[str] = typer.Option(None, "--token", help="Override profile token"),
+    no_verify: bool = typer.Option(False, "--no-verify", help="Skip post-download verify"),
+    deep: bool = typer.Option(False, "--deep", help="Also verify sha256 where recorded"),
+    http_timeout: float = typer.Option(
+        120.0,
+        "--http-read-timeout",
+        help="HTTP read-idle timeout in seconds",
+    ),
+    http_retries: int = typer.Option(
+        5,
+        "--http-retries",
+        help="Retries per file after transient HTTP/network failures",
+    ),
+    insecure: Optional[bool] = typer.Option(
+        None, "--insecure/--secure", "-k",
+        help=(
+            "TLS mode for http/presigned downloads. Default: --insecure for "
+            "http, secure for python/s5cmd."
+        ),
+    ),
+):
+    if (manifest is None) == (task is None):
+        console.print("[red]error:[/red] pass exactly one of --manifest or --task")
+        raise typer.Exit(code=2)
+
+    effective_insecure = _effective_insecure(insecure, backend)
+    _warn_insecure(effective_insecure, backend, explicit=insecure is True)
+    progress = _RichDownloadProgress()
+    backend_kwargs = _http_backend_kwargs(
+        backend,
+        timeout=http_timeout,
+        max_retries=http_retries,
+    )
+
+    try:
+        if manifest is not None:
+            report = download_manifest(
+                "-" if manifest == Path("-") else manifest, out,
+                parallel=parallel, backend=backend,
+                verify=not no_verify, deep=deep, insecure=effective_insecure,
+                progress=progress, backend_kwargs=backend_kwargs,
+            )
+        else:
+            # download_task returns the out-path per §11.1; run the manager here
+            # so the CLI can print a full report.
+            with DexVerseClient(server=server, token=token) as client:
+                man = client.get_manifest(task)
+            report = DownloadManager(
+                out, backend=backend, parallel=parallel,
+                verify=not no_verify, deep=deep, insecure=effective_insecure,
+                progress=progress, backend_kwargs=backend_kwargs,
+            ).run(man)
+    except S5CmdNotAvailable as exc:
+        console.print(f"[red]s5cmd not available:[/red] {exc}")
+        console.print("  hint: omit [cyan]--backend s5cmd[/cyan], or use [cyan]--backend python[/cyan]")
+        raise typer.Exit(code=2)
+    except DexVerseError as exc:
+        console.print(f"[red]error:[/red] {exc}")
+        raise typer.Exit(code=1)
+    except (FileNotFoundError, ValueError) as exc:
+        console.print(f"[red]error:[/red] {exc}")
+        raise typer.Exit(code=1)
+
+    _print_report(report)
+    if not report.ok:
+        raise typer.Exit(code=1)
+
+
+# --------------------------------------------------------------------------- #
+# convert
+# --------------------------------------------------------------------------- #
+@app.command(help="将下载的 HDF5 还原为可训练的原始数据结构（多路相机图片 + pose_record JSON）。")
+def convert(
+    input: Optional[Path] = typer.Option(
+        None, "--input", "-i", help="单个 HDF5 文件路径",
+    ),
+    input_dir: Optional[Path] = typer.Option(
+        None, "--input-dir", help="目录，批量递归处理其下所有 *.hdf5",
+    ),
+    output: Path = typer.Option(..., "--output", "-o", help="输出根目录"),
+    strategy: str = typer.Option(
+        "default", "--strategy", help="对齐策略（当前仅 default，预留扩展）",
+    ),
+):
+    """下载完的 HDF5 落在下载时的 --out 下，把它作为 -i / --input-dir 传入即可。"""
+    if strategy != "default":
+        console.print(f"[red]error:[/red] 未知策略 {strategy!r}（当前仅支持 default）")
+        raise typer.Exit(code=2)
+
+    if (input is None) == (input_dir is None):
+        console.print("[red]error:[/red] 必须指定 -i/--input 或 --input-dir 之一")
+        raise typer.Exit(code=2)
+
+    input_path = Path(input if input is not None else input_dir)  # type: ignore[arg-type]
+    if not input_path.exists():
+        console.print(f"[red]error:[/red] 输入路径不存在: {input_path}")
+        raise typer.Exit(code=1)
+
+    try:
+        success, total_frames = convert_hdf5_batch(
+            input_path, Path(output), strategy=DefaultAlignmentStrategy(),
+        )
+    except (FileNotFoundError, ValueError) as exc:
+        console.print(f"[red]error:[/red] {exc}")
+        raise typer.Exit(code=1)
+
+    if success == 0:
+        console.print("[yellow]未还原任何文件[/yellow]")
+        raise typer.Exit(code=1)
+    console.print(
+        f"[green]OK[/green] 还原 {success} 个文件, 共 {total_frames} 帧 -> {output}"
+    )
+
+
+# --------------------------------------------------------------------------- #
+# verify
+# --------------------------------------------------------------------------- #
+@app.command(help="Verify downloaded files against a manifest (size, or --deep sha256).")
+def verify(
+    manifest: Path = typer.Option(
+        ..., "--manifest", "-m",
+        help="Local manifest.json path, or '-' to read JSON from stdin",
+    ),
+    out: Path = typer.Option(..., "--out", "-o"),
+    deep: bool = typer.Option(False, "--deep", help="Also check sha256"),
+):
+    try:
+        man = (Manifest.parse_stdin() if manifest == Path("-")
+               else Manifest.parse_file(manifest))
+        results = verify_files(man.files, out, deep=deep)
+    except (FileNotFoundError, ValueError) as exc:
+        console.print(f"[red]error:[/red] {exc}")
+        raise typer.Exit(code=1)
+    summary = summarize(results)
+
+    table = Table(title=f"Verify — task {man.effective_task_id()}")
+    table.add_column("status")
+    table.add_column("count", justify="right")
+    table.add_row("[green]ok[/green]", str(summary.ok))
+    table.add_row("missing", str(summary.missing))
+    table.add_row("size mismatch", str(summary.size_mismatch))
+    table.add_row("sha256 mismatch", str(summary.sha256_mismatch))
+    console.print(table)
+
+    for r in summary.bad_results:
+        console.print(f"  [red]✗[/red] {r.relpath}  ({r.reason})")
+
+    console.print(
+        f"\n{summary.ok}/{summary.total} files verified"
+        f"{' [bold green]all good[/bold green]' if summary.all_ok else ''}"
+    )
+    if not summary.all_ok:
+        raise typer.Exit(code=1)
+
+
+# --------------------------------------------------------------------------- #
+# repair
+# --------------------------------------------------------------------------- #
+@app.command(help="Re-download missing / size-mismatched / sha256-mismatched files. "
+                  "Use --task to fetch a fresh manifest (refreshes expired presigned URLs).")
+def repair(
+    out: Path = typer.Option(..., "--out", "-o"),
+    manifest: Optional[Path] = typer.Option(
+        None, "--manifest", "-m",
+        help="Local manifest.json path, or '-' to read JSON from stdin",
+    ),
+    task: Optional[str] = typer.Option(None, "--task", help="Refresh manifest from backend"),
+    server: Optional[str] = typer.Option(None, "--server"),
+    token: Optional[str] = typer.Option(None, "--token"),
+    backend: str = typer.Option("http", "--backend", "-b",
+                                help="http | python | s5cmd"),
+    parallel: Optional[int] = typer.Option(None, "--parallel", "-p"),
+    deep: bool = typer.Option(False, "--deep", help="Detect sha256 corruption too"),
+    http_timeout: float = typer.Option(
+        120.0,
+        "--http-read-timeout",
+        help="HTTP read-idle timeout in seconds",
+    ),
+    http_retries: int = typer.Option(
+        5,
+        "--http-retries",
+        help="Retries per file after transient HTTP/network failures",
+    ),
+    insecure: Optional[bool] = typer.Option(
+        None, "--insecure/--secure", "-k",
+        help=(
+            "TLS mode for http/presigned downloads. Default: --insecure for "
+            "http, secure for python/s5cmd."
+        ),
+    ),
+):
+    if (manifest is None) == (task is None):
+        console.print("[red]error:[/red] pass exactly one of --manifest or --task")
+        raise typer.Exit(code=2)
+
+    effective_insecure = _effective_insecure(insecure, backend)
+    _warn_insecure(effective_insecure, backend, explicit=insecure is True)
+    progress = _RichDownloadProgress()
+    backend_kwargs = _http_backend_kwargs(
+        backend,
+        timeout=http_timeout,
+        max_retries=http_retries,
+    )
+
+    try:
+        if task is not None:
+            # fresh manifest = fresh presigned URLs (the persisted copy's may be expired)
+            with DexVerseClient(server=server, token=token) as client:
+                man = client.get_manifest(task)
+        elif manifest == Path("-"):
+            man = Manifest.parse_stdin()
+        else:
+            man = Manifest.parse_file(manifest)
+        report = repair_fn(man, out, backend=backend, parallel=parallel,
+                           deep=deep, insecure=effective_insecure,
+                           progress=progress, backend_kwargs=backend_kwargs)
+    except S5CmdNotAvailable as exc:
+        console.print(f"[red]s5cmd not available:[/red] {exc}")
+        console.print("  hint: omit [cyan]--backend s5cmd[/cyan], or use [cyan]--backend python[/cyan]")
+        raise typer.Exit(code=2)
+    except DexVerseError as exc:
+        console.print(f"[red]error:[/red] {exc}")
+        raise typer.Exit(code=1)
+    except (FileNotFoundError, ValueError) as exc:
+        console.print(f"[red]error:[/red] {exc}")
+        raise typer.Exit(code=1)
+    _print_report(report)
+    if not report.ok:
+        raise typer.Exit(code=1)
+
+
+# --------------------------------------------------------------------------- #
+# helpers
+# --------------------------------------------------------------------------- #
+def _is_http_backend(backend: str) -> bool:
+    return (backend or "http").lower() in ("http", "https", "presigned")
+
+
+def _http_backend_kwargs(
+    backend: str,
+    *,
+    timeout: float,
+    max_retries: int,
+) -> dict:
+    if not _is_http_backend(backend):
+        return {}
+    return {"timeout": timeout, "max_retries": max_retries}
+
+
+def _effective_insecure(insecure: Optional[bool], backend: str) -> bool:
+    if insecure is not None:
+        return insecure
+    return _is_http_backend(backend)
+
+
+def _warn_insecure(insecure: bool, backend: str, *, explicit: bool = False) -> None:
+    if not insecure:
+        return
+    backend = (backend or "").lower()
+    if backend in ("http", "https", "presigned"):
+        if not explicit:
+            console.print(
+                "[yellow]WARNING:[/yellow] TLS verification is disabled by default for "
+                "http/presigned downloads. Use [cyan]--secure[/cyan] to require a valid "
+                "certificate."
+            )
+            return
+        console.print(
+            "[yellow]WARNING:[/yellow] --insecure disables TLS verification. For "
+            "self-authenticating presigned URLs, TLS is the only transport-integrity "
+            "check — any certificate will be accepted and redirects followed."
+        )
+    else:
+        console.print(
+            "[yellow]WARNING:[/yellow] --insecure disables TLS verification "
+            "(self-signed/internal endpoint)."
+        )
+
+
+def _print_report(report) -> None:
+    console.print(f"\n[bold]Download report[/bold] — {report.summary_line()}")
+    console.print(f"  out:       {report.out}")
+    console.print(f"  task dir:  {report.task_dir}")
+    console.print(f"  state:     {report.state_path}")
+    if report.failures:
+        console.print(f"  [red]failures:[/red]")
+        for fl in report.failures[:20]:
+            console.print(f"    ✗ {fl['relpath']} — {fl.get('error')}")
+        if len(report.failures) > 20:
+            console.print(f"    ... and {len(report.failures) - 20} more")
+
+
+if __name__ == "__main__":
+    app()

dexverse/client.py

@@ -0,0 +1,128 @@
+"""Python SDK client (doc §11).
+
+``DexVerseClient`` talks to the platform backend to fetch a manifest for a
+taskId, then hands it to the download manager. ``download_manifest`` runs the
+manager directly off a local manifest file (Phase 0, no server).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, Optional, Union
+
+import httpx
+
+from .config import active_profile
+from .downloader.base import ProgressReporter
+from .downloader.manager import DownloadManager, DownloadReport, get_backend  # noqa: F401
+from .manifest import Manifest
+
+
+class DexVerseError(RuntimeError):
+    pass
+
+
+def _download_error(report: DownloadReport) -> DexVerseError:
+    message = (
+        f"download completed with {report.failed + report.corrupt} problem(s): "
+        f"{report.summary_line()}"
+    )
+    if report.failures:
+        first = report.failures[0]
+        message += (
+            f"; first failure: {first.get('relpath')}: "
+            f"{first.get('error') or 'verification failed'}"
+        )
+    return DexVerseError(message)
+
+
+class DexVerseClient:
+    def __init__(self, server: Optional[str] = None, token: Optional[str] = None, *,
+                 timeout: float = 30.0):
+        # Fall back to the active profile saved by `dexverse-dl login`.
+        if not server or not token:
+            prof = active_profile()
+            if prof:
+                server = server or prof.server
+                token = token if token is not None else prof.token
+        if not server:
+            raise DexVerseError("no server configured (run `dexverse-dl login` first)")
+        self.server = server.rstrip("/")
+        self.token = token
+        self._client = httpx.Client(timeout=timeout)
+
+    def _headers(self) -> dict:
+        h = {"Accept": "application/json"}
+        if self.token:
+            h["Authorization"] = f"Bearer {self.token}"
+        return h
+
+    def get_manifest(self, task_id: str) -> Manifest:
+        url = f"{self.server}/api/download-tasks/{task_id}/manifest"
+        resp = self._client.get(url, headers=self._headers())
+        if resp.status_code == 404:
+            raise DexVerseError(f"task not found: {task_id}")
+        if resp.status_code in (401, 403):
+            raise DexVerseError(f"auth failed ({resp.status_code}) for task {task_id}")
+        resp.raise_for_status()
+        return Manifest.from_payload(resp.json())
+
+    def download_task(self, task_id: str, out: Union[str, Path], *,
+                      parallel: Optional[int] = None,
+                      backend: str = "http",
+                      verify: bool = True,
+                      deep: bool = False,
+                      insecure: bool = True,
+                      backend_kwargs: Optional[Dict[str, object]] = None) -> Path:
+        """Download a task by id; returns the local out directory (doc §11.1).
+
+        ``local_root = client.download_task(...)`` is the user-supplied ``out``,
+        with files landed at their original relative paths. Raises DexVerseError
+        if the run finishes with failures.
+        """
+        manifest = self.get_manifest(task_id)
+        mgr = DownloadManager(out, backend=backend, parallel=parallel,
+                              verify=verify, deep=deep, insecure=insecure,
+                              backend_kwargs=backend_kwargs or {})
+        report = mgr.run(manifest)
+        if not report.ok:
+            raise _download_error(report)
+        return report.out
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "DexVerseClient":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+
+def download_manifest(manifest_path: Union[str, Path], out: Union[str, Path], *,
+                      parallel: Optional[int] = None,
+                      backend: str = "http",
+                      verify: bool = True,
+                      deep: bool = False,
+                      insecure: bool = True,
+                      progress: Optional[ProgressReporter] = None,
+                      backend_kwargs: Optional[Dict[str, object]] = None) -> DownloadReport:
+    """Run a download straight from a local manifest file (Phase 0).
+
+    Returns the detailed DownloadReport (counts + failures). Note this differs
+    from ``DexVerseClient.download_task``, which returns the out path per §11.1.
+
+    ``manifest_path == "-"`` reads the manifest from stdin, so callers can pipe
+    a JSON payload (``echo '<json>' | dexverse-dl download --manifest - ...``)
+    without saving a file first — useful because presigned URLs expire fast.
+    """
+    if str(manifest_path) == "-":
+        manifest = Manifest.parse_stdin()
+    else:
+        manifest = Manifest.parse_file(Path(manifest_path))
+    mgr = DownloadManager(out, backend=backend, parallel=parallel,
+                          verify=verify, deep=deep, insecure=insecure,
+                          progress=progress, backend_kwargs=backend_kwargs or {})
+    report = mgr.run(manifest)
+    if not report.ok:
+        raise _download_error(report)
+    return report

dexverse/config.py

@@ -0,0 +1,85 @@
+"""Login / server configuration.
+
+Stores the active server URL and bearer token per *profile* in a TOML file at
+``~/.dexverse/config.toml``. The file is created with mode 0600 where the OS
+supports it. Secrets are never written into the manifest or into Git
+(see doc §13.1).
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import tomlkit
+
+
+def config_path() -> Path:
+    """Location of the CLI config file (overridable via DEXVERSE_CONFIG)."""
+    override = os.getenv("DEXVERSE_CONFIG")
+    if override:
+        return Path(override)
+    return Path.home() / ".dexverse" / "config.toml"
+
+
+@dataclass
+class Profile:
+    server: str
+    token: Optional[str] = None
+
+
+def _read() -> tomlkit.TOMLDocument:
+    p = config_path()
+    if not p.exists():
+        return tomlkit.document()
+    try:
+        return tomlkit.parse(p.read_text(encoding="utf-8"))
+    except Exception:
+        return tomlkit.document()
+
+
+def _write(doc: tomlkit.TOMLDocument) -> None:
+    p = config_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    # Best-effort restrictive permissions (POSIX only; no-op on Windows).
+    p.write_text(tomlkit.dumps(doc), encoding="utf-8")
+    try:
+        os.chmod(p, 0o600)
+    except OSError:
+        pass
+
+
+def save_profile(name: str, server: str, token: Optional[str]) -> None:
+    doc = _read()
+    profiles = doc.get("profiles")
+    if not isinstance(profiles, tomlkit.items.Table) or profiles is None:
+        profiles = tomlkit.table()
+        doc["profiles"] = profiles
+    table = tomlkit.table()
+    table["server"] = server
+    if token:
+        table["token"] = token
+    profiles[name] = table  # type: ignore[assignment]
+    doc["active"] = name
+    _write(doc)
+
+
+def load_profile(name: Optional[str] = None) -> Optional[Profile]:
+    """Load the named profile, or the active one if name is None."""
+    doc = _read()
+    profiles = doc.get("profiles")
+    if not isinstance(profiles, dict):
+        return None
+    target = name or doc.get("active")
+    if not target or target not in profiles:
+        return None
+    row = profiles[target]
+    server = row.get("server")
+    if not server:
+        return None
+    return Profile(server=server, token=row.get("token"))
+
+
+def active_profile() -> Optional[Profile]:
+    return load_profile(None)