"""Probe the real GL stack from inside a Qt window and write a diagnostic report.

Stage 1 deliverable (``docs/architecture/studio-3d-stages.md``).

It must create an **actual** Qt widget and read the context that Qt actually
obtained — asking the system whether ``libGL`` exists proves nothing, and an
offscreen UI test cannot stand in for a board's GPU. What it writes is the input
to the platform decision: which profile a board gets, and whether the renderer is
a real GPU.

Until stage 1 lands, the script explains what it will do and exits non-zero, so a
build script cannot mistake "not implemented" for "probe passed".
"""

from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path

_STAGE = "stage 1 (platform PoC)"


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    parser.add_argument(
        "--profile",
        choices=("desktop33", "gles30"),
        default="desktop33",
        help="the start-up profile to probe (one per process)",
    )
    parser.add_argument(
        "--output",
        type=Path,
        default=None,
        help="write the diagnostic report here as JSON",
    )
    parser.add_argument(
        "--windowed",
        action="store_true",
        help="create a visible window instead of a short-lived one",
    )
    args = parser.parse_args(argv)

    report = {
        "status": "not_implemented",
        "profile": args.profile,
        "stage": _STAGE,
        "note": (
            "The probe creates a real QOpenGLWidget and reports the context Qt "
            "obtained: vendor, renderer, GL/GLSL version, DPR, framebuffer size, "
            "and whether the renderer is a software rasteriser. It never reports "
            "a board as verified from an offscreen or virtual context."
        ),
    }
    text = json.dumps(report, indent=2, ensure_ascii=False)
    if args.output is not None:
        args.output.write_text(text + "\n", encoding="utf-8")
    print(text)
    return 2


if __name__ == "__main__":
    sys.exit(main())