veltro-cli 0.15.7__py3-none-any.whl

veltro_cli/lib/status.py

@@ -0,0 +1,170 @@
+"""veltro status — compose ps + HTTP probes + suite version."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Mapping
+
+from veltro_cli.lib.compose import ComposeClient
+from veltro_cli.lib.errors import VeltroCliError
+from veltro_cli.lib.products import read_env_file
+from veltro_cli.lib.release import latest_release_version, release_tag
+from veltro_cli.lib.toml_config import VELTRO_TOML, read_config
+
+Fetcher = Callable[[str, float], tuple[int, str]]
+
+
+@dataclass(frozen=True)
+class Probe:
+    name: str
+    path: str
+
+
+PROBES = (Probe("suite-status", "/api/suite/status"),)
+
+
+def default_fetcher(
+    url: str,
+    timeout: float = 3.0,
+    *,
+    headers: Mapping[str, str] | None = None,
+) -> tuple[int, str]:
+    request_headers = {"Accept": "application/json", **dict(headers or {})}
+    req = urllib.request.Request(url, headers=request_headers, method="GET")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            body = resp.read().decode("utf-8", errors="replace")
+            return int(resp.status), body
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace") if exc.fp else ""
+        return int(exc.code), body
+    except Exception as exc:  # noqa: BLE001 — surface any transport failure
+        return 0, str(exc)
+
+def fetch_latest_suite_version(
+    *, opener: Callable[..., Any] = urllib.request.urlopen
+) -> str | None:
+    """The newest release's tag, or None when the lookup is unavailable."""
+    try:
+        return release_tag(latest_release_version(opener=opener, timeout=3))
+    except VeltroCliError:
+        return None
+
+
+
+def collect_status(
+    root: Path,
+    *,
+    products: tuple[str, ...] = ("vectorflow", "chad", "warden"),
+    public_url: str = "http://localhost",
+    client: ComposeClient | None = None,
+    fetcher: Fetcher = default_fetcher,
+    tls_mode: str = "off",
+    check_latest: bool = True,
+) -> dict[str, Any]:
+    client = client or ComposeClient(root, products=products, tls_mode=tls_mode)
+    ps = client.ps("--format", "json")
+    services: list[dict[str, Any]] = []
+    if ps.returncode == 0 and ps.stdout.strip():
+        # compose ps --format json emits either a JSON array or NDJSON depending on version.
+        text = ps.stdout.strip()
+        try:
+            parsed = json.loads(text)
+            if isinstance(parsed, list):
+                services = parsed
+            elif isinstance(parsed, dict):
+                services = [parsed]
+        except json.JSONDecodeError:
+            for line in text.splitlines():
+                try:
+                    services.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+
+    base = public_url.rstrip("/")
+    probes = PROBES
+
+    probe_results = []
+    for probe in probes:
+        url = base.rstrip("/") + probe.path
+        code, body = fetcher(url, 3.0)
+        state = "ready" if 200 <= code < 300 else ("down" if code == 0 else "degraded")
+        probe_results.append(
+            {
+                "name": probe.name,
+                "url": url,
+                "http_status": code,
+                "state": state,
+                "body_preview": body[:200],
+            }
+        )
+        if probe.name == "suite-status" and 200 <= code < 300:
+            try:
+                suite_status = json.loads(body)
+            except json.JSONDecodeError:
+                suite_status = None
+            if isinstance(suite_status, dict) and suite_status.get("schema") == "veltro-suite-status/v2":
+                components = suite_status.get("components")
+                if isinstance(components, list):
+                    for component in components:
+                        if not isinstance(component, dict):
+                            continue
+                        name = component.get("id")
+                        component_state = component.get("status")
+                        if not isinstance(name, str) or component_state not in {"ready", "degraded", "down", "unknown", "not_installed"}:
+                            continue
+                        probe_results.append(
+                            {
+                                "name": name,
+                                "url": url,
+                                "http_status": code,
+                                "state": component_state,
+                                "body_preview": json.dumps(component, separators=(",", ":"))[:200],
+                            }
+                        )
+
+    pins = read_env_file(root / "versions.env")
+    cfg = read_config(root / VELTRO_TOML)
+    return {
+        "products": list(products),
+        "public_url": public_url,
+        "installed_suite_version": cfg.installed_suite_version if cfg else None,
+        "latest_suite_version": fetch_latest_suite_version() if check_latest else None,
+        "suite_pins": pins,
+        "services": services,
+        "probes": probe_results,
+        "compose_ps_returncode": ps.returncode,
+        "compose_ps_stderr": ps.stderr.strip(),
+    }
+
+
+def format_status(doc: dict[str, Any]) -> str:
+    installed = doc.get("installed_suite_version") or "unknown"
+    latest = doc.get("latest_suite_version") or "offline"
+    lines = [
+        f"products: {','.join(doc['products']) or '(core only)'}",
+        f"public_url: {doc['public_url']}",
+        f"suite_version: {installed} (latest: {latest})",
+        "pins:",
+    ]
+    for key in ("VF_VERSION", "CHAD_VERSION", "WARDEN_VERSION", "VELTRO_VERSION"):
+        if key in doc.get("suite_pins", {}):
+            lines.append(f"  {key}={doc['suite_pins'][key]}")
+    lines.append("services:")
+    services = doc.get("services") or []
+    if not services:
+        lines.append("  (none — is the stack up?)")
+    for svc in services:
+        name = svc.get("Service") or svc.get("Name") or svc.get("Name") or "?"
+        state = svc.get("State") or svc.get("Status") or "?"
+        health = svc.get("Health") or ""
+        extra = f" health={health}" if health else ""
+        lines.append(f"  {name}: {state}{extra}")
+    lines.append("probes:")
+    for probe in doc.get("probes") or []:
+        lines.append(f"  {probe['name']}: {probe['state']} (HTTP {probe['http_status']}) {probe['url']}")
+    return "\n".join(lines) + "\n"

veltro_cli/lib/suite_http.py

@@ -0,0 +1,227 @@
+"""Minimal suite HTTP client: cookie session, CSRF, JSON — stdlib only.
+
+The transport is injectable so every caller can be tested without a network or
+a running stack: pass ``transport=`` a callable
+``(method, url, headers, body) -> (status, headers, text)``.
+
+Cookie and CSRF handling mirrors scripts/seed-demo.sh exactly, because they are
+talking to the same three planes:
+
+* identity (`/api/auth/*`, `/api/trpc/*`) validates `x-csrf-token` against the
+  token `GET /api/auth/csrf` issued for this jar;
+* CHAD and Warden run a double-submit check against the `csrf_token` cookie
+  they set on the first safe request;
+* the ingest plane (`/api/logs/<suffix>`) is bearer-authenticated and takes no
+  cookie at all.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from http.cookies import SimpleCookie
+from typing import Any, Callable, Mapping
+
+from veltro_cli.lib.errors import VeltroCliError
+
+Transport = Callable[[str, str, Mapping[str, str], bytes | None], "tuple[int, Mapping[str, str], str]"]
+
+SESSION_COOKIE = "authjs.session-token"
+PRODUCT_CSRF_COOKIE = "csrf_token"
+DEFAULT_TIMEOUT = 30
+# Every answer this client reads is a JSON control-plane document: the largest
+# real one is a 500-row CHAD alert page. Reading an unbounded body into memory
+# because a product (or something in front of it) streamed one is not a
+# failure mode a demo seeder needs, so the read is capped and named rather
+# than silently truncated, which would surface as a JSON parse error instead.
+MAX_RESPONSE_BYTES = 32 * 1024 * 1024
+
+
+@dataclass(frozen=True)
+class Response:
+    status: int
+    headers: Mapping[str, str]
+    text: str
+
+    @property
+    def ok(self) -> bool:
+        return 200 <= self.status < 300
+
+    def json(self, default: Any = None) -> Any:
+        try:
+            return json.loads(self.text)
+        except (json.JSONDecodeError, TypeError):
+            return default
+
+    def detail(self, limit: int = 300) -> str:
+        """FastAPI `detail`, CHAD `message`, tRPC error, else a truncated body."""
+        body = self.json()
+        if isinstance(body, Mapping):
+            for key in ("detail", "message"):
+                value = body.get(key)
+                if isinstance(value, str) and value.strip():
+                    return value.strip()
+            error = body.get("error")
+            if isinstance(error, Mapping):
+                inner = error.get("json")
+                if isinstance(inner, Mapping) and isinstance(inner.get("message"), str):
+                    return str(inner["message"])
+            unmapped = body.get("unmapped_fields")
+            if unmapped:
+                return f"unmapped_fields={unmapped}"
+        return (self.text or "")[:limit]
+
+
+def _read_capped(reader: Any, method: str, url: str) -> str:
+    """Read at most `MAX_RESPONSE_BYTES`, refusing anything longer by name."""
+    payload = reader.read(MAX_RESPONSE_BYTES + 1)
+    if len(payload) > MAX_RESPONSE_BYTES:
+        raise VeltroCliError(
+            f"{method} {url} answered with more than {MAX_RESPONSE_BYTES} bytes",
+            remedy="narrow the request (page it with `limit=`), or check what is answering that path",
+        )
+    return payload.decode("utf-8", "replace")
+
+
+def _urllib_transport(
+    method: str, url: str, headers: Mapping[str, str], body: bytes | None
+) -> tuple[int, Mapping[str, str], str]:
+    request = urllib.request.Request(url, data=body, method=method)
+    for name, value in headers.items():
+        request.add_header(name, value)
+    try:
+        with urllib.request.urlopen(request, timeout=DEFAULT_TIMEOUT) as response:
+            return response.status, dict(response.headers.items()), _read_capped(response, method, url)
+    except urllib.error.HTTPError as error:  # a status is an answer, not a failure
+        payload = _read_capped(error, method, url) if error.fp else ""
+        return error.code, dict(error.headers.items() if error.headers else {}), payload
+    except urllib.error.URLError as error:
+        raise VeltroCliError(
+            f"{method} {url} failed: {error.reason}",
+            remedy="check the suite is running and PUBLIC_BASE_URL is reachable (`veltro status`)",
+        ) from error
+
+
+@dataclass
+class SuiteSession:
+    """One authenticated browser-equivalent session against the suite origin."""
+
+    base_url: str
+    transport: Transport = _urllib_transport
+    cookies: dict[str, str] = field(default_factory=dict)
+    identity_csrf: str | None = None
+
+    def url(self, path: str) -> str:
+        if path.startswith("http://") or path.startswith("https://"):
+            return path
+        return f"{self.base_url.rstrip('/')}{path if path.startswith('/') else '/' + path}"
+
+    def _absorb_cookies(self, headers: Mapping[str, str]) -> None:
+        raw = headers.get("Set-Cookie") or headers.get("set-cookie")
+        if not raw:
+            return
+        jar = SimpleCookie()
+        # Multiple Set-Cookie headers arrive joined by ", " through
+        # http.client's header folding; SimpleCookie parses that shape.
+        jar.load(raw)
+        for name, morsel in jar.items():
+            # A cookie cleared by the server (empty value) must not linger:
+            # a stale session cookie would make a 401 look like a live session.
+            if morsel.value == "":
+                self.cookies.pop(name, None)
+            else:
+                self.cookies[name] = morsel.value
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any = None,
+        raw_body: bytes | None = None,
+        headers: Mapping[str, str] | None = None,
+        bearer: str | None = None,
+        send_cookies: bool = True,
+    ) -> Response:
+        outgoing: dict[str, str] = {"accept": "application/json"}
+        body = raw_body
+        if json_body is not None:
+            body = json.dumps(json_body).encode("utf-8")
+            outgoing["content-type"] = "application/json"
+        if send_cookies and self.cookies:
+            outgoing["cookie"] = "; ".join(f"{name}={value}" for name, value in self.cookies.items())
+        if method.upper() not in {"GET", "HEAD"}:
+            product_csrf = self.cookies.get(PRODUCT_CSRF_COOKIE)
+            if product_csrf:
+                outgoing["X-CSRF-Token"] = product_csrf
+        if bearer:
+            outgoing["authorization"] = f"Bearer {bearer}"
+        for name, value in (headers or {}).items():
+            outgoing[name] = value
+        status, response_headers, text = self.transport(method.upper(), self.url(path), outgoing, body)
+        self._absorb_cookies(response_headers)
+        return Response(status=status, headers=response_headers, text=text)
+
+    def get(self, path: str, **kwargs: Any) -> Response:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> Response:
+        return self.request("POST", path, **kwargs)
+
+    # --- authentication -----------------------------------------------------
+
+    def login(self, email: str, password: str) -> None:
+        """Mint the suite session cookie the whole seed runs under."""
+        csrf = self.get("/api/auth/csrf")
+        token = (csrf.json({}) or {}).get("csrfToken") if csrf.ok else None
+        if not token:
+            raise VeltroCliError(
+                f"GET /api/auth/csrf did not issue a token (HTTP {csrf.status})",
+                remedy="check the identity application is ready (`veltro status`)",
+            )
+        self.identity_csrf = str(token)
+        response = self.post(
+            "/api/auth/login",
+            json_body={"email": email, "password": password},
+            headers={"x-csrf-token": self.identity_csrf},
+        )
+        if SESSION_COOKIE not in self.cookies:
+            raise VeltroCliError(
+                f"suite login for {email} minted no session cookie (HTTP {response.status}): {response.detail()}",
+                remedy="check VF_ADMIN_EMAIL / VF_ADMIN_PASSWORD name a suite admin",
+            )
+
+    # --- identity tRPC ------------------------------------------------------
+
+    def trpc_query(self, procedure: str, payload: Any = None) -> Response:
+        suffix = "" if payload is None else f"?input={urllib.parse.quote(json.dumps(payload))}"
+        return self.get(f"/api/trpc/{procedure}{suffix}")
+
+    def trpc_mutation(self, procedure: str, payload: Any) -> Response:
+        if not self.identity_csrf:
+            csrf = self.get("/api/auth/csrf")
+            token = (csrf.json({}) or {}).get("csrfToken") if csrf.ok else None
+            if not token:
+                raise VeltroCliError(
+                    "no identity CSRF token available for a tRPC mutation",
+                    remedy="log in first (`SuiteSession.login`)",
+                )
+            self.identity_csrf = str(token)
+        return self.post(
+            f"/api/trpc/{procedure}",
+            json_body=payload,
+            headers={"x-csrf-token": self.identity_csrf},
+        )
+
+
+def trpc_data(response: Response) -> Any:
+    """The `result.data` payload of an identity tRPC response, or None."""
+    body = response.json()
+    if isinstance(body, Mapping):
+        result = body.get("result")
+        if isinstance(result, Mapping):
+            return result.get("data")
+    return None

veltro_cli/lib/support.py

@@ -0,0 +1,35 @@
+"""veltro support-bundle — thin wrapper over scripts/support_bundle.py."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from veltro_cli.lib.errors import VeltroCliError
+from veltro_cli.lib.paths import resolve_dir
+
+
+def capture_support_bundle(
+    *,
+    directory: str | Path | None = None,
+    output: str | Path | None = None,
+    base_url: str | None = None,
+) -> Path:
+    root = resolve_dir(directory)
+    scripts = root / "scripts"
+    sys.path.insert(0, str(scripts))
+    try:
+        import support_bundle as sb  # type: ignore
+    except ImportError as exc:
+        raise VeltroCliError(
+            "support_bundle.py not importable from scripts/",
+            remedy="run from a full Veltro checkout/install",
+        ) from exc
+    out = Path(output) if output else root / "support-bundle.json"
+    argv = ["support_bundle.py", "--versions", str(root / "versions.env"), "--output", str(out)]
+    if base_url:
+        argv.extend(["--base-url", base_url])
+    code = sb.main(argv[1:])
+    if code != 0:
+        raise VeltroCliError("support bundle capture failed", remedy="check product diagnostics endpoints")
+    return out

veltro_cli/lib/tls.py

@@ -0,0 +1,113 @@
+"""TLS mode helpers — Caddyfile rendering and compose env."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from urllib.parse import urlparse
+
+from veltro_cli.lib.errors import VeltroCliError
+from veltro_cli.lib.toml_config import TLS_MODES
+
+UPSTREAM = "veltro-nginx:80"
+
+
+def host_from_public_url(public_url: str) -> str:
+    parsed = urlparse(public_url if "://" in public_url else f"https://{public_url}")
+    host = parsed.hostname
+    if not host:
+        raise VeltroCliError(
+            f"unparseable public url {public_url!r}",
+            remedy="pass --public-url https://soc.example.com",
+        )
+    return host
+
+def validate_tls_public_url(public_url: str) -> None:
+    parsed = urlparse(public_url)
+    if parsed.scheme.lower() != "https" or not parsed.hostname:
+        raise VeltroCliError(
+            f"TLS requires an https public URL, got {public_url!r}",
+            remedy="pass --public-url https://soc.example.com, or use --tls off behind an external proxy",
+        )
+
+
+def render_caddyfile(
+    *,
+    tls_mode: str,
+    public_url: str,
+    products: tuple[str, ...] = ("vectorflow", "chad", "warden"),
+    ingest_upstream: str = "chad-backend:8001",
+) -> str:
+    if tls_mode not in TLS_MODES or tls_mode == "off":
+        raise VeltroCliError(
+            f"tls mode {tls_mode!r} does not need a Caddyfile",
+            remedy="use auto|internal|custom",
+        )
+    validate_tls_public_url(public_url)
+    host = host_from_public_url(public_url)
+    # Bind the public origin to the single gateway for every selection.
+    site = public_url if "://" in public_url else f"https://{host}"
+
+    if tls_mode == "auto":
+        tls_directive = "\t# ACME (HTTP-01 / TLS-ALPN) — requires public DNS\n"
+    elif tls_mode == "internal":
+        tls_directive = "\ttls internal\n"
+    else:  # custom
+        tls_directive = (
+            "\ttls /etc/caddy/tls/fullchain.pem /etc/caddy/tls/privkey.pem\n"
+        )
+
+    ingest_site = ""
+    if "chad" in products:
+        ingest_tls = (
+            "\ttls internal\n"
+            if tls_mode != "custom"
+            else "\ttls /etc/caddy/tls/fullchain.pem /etc/caddy/tls/privkey.pem\n"
+        )
+        ingest_site = (
+            "\n# Direct CHAD ingest over TLS (raw :8001 stays private).\n"
+            ":8443 {\n"
+            f"{ingest_tls}"
+            f"\treverse_proxy {ingest_upstream}\n"
+            "}\n"
+        )
+
+    return (
+        "# Generated by veltro-cli — do not hand-edit; re-run `veltro install --tls …`.\n"
+        "{\n"
+        "\tadmin off\n"
+        "}\n"
+        "\n"
+        "# Container-local liveness endpoint; never published by Compose.\n"
+        "http://127.0.0.1:2019 {\n"
+        "\trespond /healthz 200\n"
+        "}\n"
+        "\n"
+        f"{site} {{\n"
+        f"{tls_directive}"
+        "\tencode gzip\n"
+        f"\treverse_proxy {UPSTREAM}\n"
+        "}\n"
+        f"{ingest_site}"
+    )
+
+
+def write_caddyfile(root: Path, **kwargs) -> Path:
+    text = render_caddyfile(**kwargs)
+    path = root / "compose" / "Caddyfile"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+    # Host mounts make the internal root CA operator-accessible.
+    for directory in ("caddy-data", "caddy-config"):
+        (root / "tls" / directory).mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def tls_compose_env(tls_mode: str, public_url: str) -> dict[str, str]:
+    if tls_mode == "off":
+        return {}
+    return {
+        "VELTRO_TLS_MODE": tls_mode,
+        "PUBLIC_BASE_URL": public_url,
+        "VELTRO_TLS_UPSTREAM": UPSTREAM,
+        "VELTRO_TLS_INGEST_UPSTREAM": "chad-backend:8001",
+    }

veltro_cli/lib/toml_config.py

@@ -0,0 +1,130 @@
+"""Minimal veltro.toml read/write (stdlib only, fixed key set)."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass, fields
+from pathlib import Path
+from typing import Any, Mapping
+
+from veltro_cli.lib.errors import VeltroCliError
+
+VELTRO_TOML = "veltro.toml"
+
+TLS_MODES = ("auto", "internal", "custom", "off")
+
+
+@dataclass
+class VeltroConfig:
+    products: str = "vectorflow,chad,warden"
+    public_url: str = "http://localhost"
+    tls_mode: str = "off"
+    dir: str = "."
+    installed_suite_version: str = ""
+    monitoring: bool = False
+
+    def validate(self) -> None:
+        from veltro_cli.lib.products import parse_products
+
+        parse_products(self.products)
+        if self.tls_mode not in TLS_MODES:
+            raise ValueError(f"tls_mode must be one of {TLS_MODES}, got {self.tls_mode!r}")
+
+
+_KEY_RE = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$")
+
+
+def _parse_value(raw: str) -> Any:
+    raw = raw.strip()
+    if len(raw) >= 2 and raw[0] == raw[-1] and raw[0] in "\"'":
+        inner = raw[1:-1]
+        if raw[0] == '"':
+            return (
+                inner.replace("\\n", "\n")
+                .replace("\\t", "\t")
+                .replace('\\"', '"')
+                .replace("\\\\", "\\")
+            )
+        return inner
+    if raw.lower() in ("true", "false"):
+        return raw.lower() == "true"
+    if re.fullmatch(r"-?\d+", raw):
+        return int(raw)
+    return raw
+
+
+def _format_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    text = str(value)
+    escaped = (
+        text.replace("\\", "\\\\")
+        .replace('"', '\\"')
+        .replace("\n", "\\n")
+        .replace("\t", "\\t")
+    )
+    return f'"{escaped}"'
+
+
+def loads(text: str) -> dict[str, Any]:
+    data: dict[str, Any] = {}
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or stripped.startswith("["):
+            continue
+        match = _KEY_RE.match(stripped)
+        if not match:
+            continue
+        data[match.group(1)] = _parse_value(match.group(2))
+    return data
+
+
+def dumps(config: VeltroConfig | Mapping[str, Any]) -> str:
+    if isinstance(config, VeltroConfig):
+        payload = asdict(config)
+    else:
+        payload = dict(config)
+    lines = [
+        "# Generated by veltro-cli — do not hand-edit keys the CLI owns.",
+        "[veltro]",
+    ]
+    for key in (
+        "products",
+        "public_url",
+        "tls_mode",
+        "dir",
+        "installed_suite_version",
+        "monitoring",
+    ):
+        if key in payload and payload[key] is not None:
+            lines.append(f"{key} = {_format_value(payload[key])}")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def read_config(path: Path) -> VeltroConfig | None:
+    if not path.is_file():
+        return None
+    raw = loads(path.read_text(encoding="utf-8"))
+    legacy_profile = raw.pop("profile", None)
+    if legacy_profile == "full":
+        raw.setdefault("products", "vectorflow,chad,warden")
+    elif legacy_profile is not None:
+        raise VeltroCliError(
+            f"legacy standalone profile {legacy_profile!r} cannot be upgraded in place",
+            remedy="import its users and product data into Veltro core plus the product, "
+            "then replace profile with products in veltro.toml",
+        )
+    known = {f.name for f in fields(VeltroConfig)}
+    kwargs = {k: v for k, v in raw.items() if k in known}
+    cfg = VeltroConfig(**kwargs)
+    cfg.validate()
+    return cfg
+
+
+def write_config(path: Path, config: VeltroConfig) -> None:
+    config.validate()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(dumps(config), encoding="utf-8")