chartwright 0.1.0__py3-none-any.whl

chartwright/cli.py

@@ -0,0 +1,222 @@
+"""CLI: the deterministic back-half the LLM front-end drives.
+
+    chartwright schema                          print the JSON Schema the LLM must satisfy
+    chartwright validate spec.json              schema-validate only (no network)
+    chartwright compile spec.json -o out.zip    compile bundle with a stub resolution (golden/debug)
+    chartwright check spec.json --profile P     pre-flight referential resolution
+    chartwright apply spec.json --profile P     check -> compile -> import -> smoke
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from .spec import json_schema, load_spec
+
+
+def _load(path: str):
+    try:
+        # Explicit UTF-8: Windows' locale default (cp1252) would mojibake or
+        # reject the non-ASCII titles/markdown LLM-written specs contain.
+        data = json.loads(Path(path).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError) as e:
+        _die({"stage": "parse", "errors": [{"code": "unreadable_spec", "detail": str(e)}]})
+    try:
+        return load_spec(data)
+    except ValidationError as e:
+        _die({"stage": "schema", "errors": json.loads(e.json())})
+
+
+def _die(payload: dict, code: int = 1) -> None:
+    print(json.dumps(payload, indent=2, default=str))
+    sys.exit(code)
+
+
+def _client(profile_name: str):
+    from .client import SupersetClient
+    from .profiles import load_profile, ProfileError
+
+    try:
+        p = load_profile(profile_name)
+    except ProfileError as e:
+        _die({"stage": "profile", "errors": [{"code": "profile", "detail": str(e)}]})
+    c = SupersetClient(p.base_url, p.username, p.password, auth_provider=p.auth_provider,
+                       ca_bundle=p.ca_bundle, verify=p.verify)
+    c.login()
+    return c
+
+
+def main(argv: list[str] | None = None) -> None:
+    try:
+        _main(argv)
+    except SystemExit:
+        raise
+    except Exception as e:  # noqa: BLE001 - CLI boundary: tracebacks are not the contract
+        from .client import SupersetAPIError
+
+        code = "api" if isinstance(e, SupersetAPIError) else "unexpected"
+        detail = str(e)
+        if code == "unexpected":
+            detail = f"{type(e).__name__}: {e} (please report this; it should have been a typed error)"
+        _die({"stage": "error", "errors": [{"code": code, "detail": detail}]})
+
+
+def _main(argv: list[str] | None = None) -> None:
+    ap = argparse.ArgumentParser(prog="chartwright", description=__doc__)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("schema")
+
+    v = sub.add_parser("validate")
+    v.add_argument("spec")
+
+    comp = sub.add_parser("compile")
+    comp.add_argument("spec")
+    comp.add_argument("-o", "--output", default=None)
+
+    for name in ("check", "apply", "plan"):
+        p = sub.add_parser(name)
+        p.add_argument("spec")
+        p.add_argument("--profile", required=True)
+
+    dec = sub.add_parser("decompile")
+    dec.add_argument("dashboard", help="slug or numeric id of a live dashboard")
+    dec.add_argument("--profile", required=True)
+    dec.add_argument("-o", "--output", default=None, help="write spec JSON here; losses go to stdout")
+
+    ab = sub.add_parser("absorb", help="patch LIVE UI height polish back into the spec (heights only)")
+    ab.add_argument("spec")
+    ab.add_argument("--profile", required=True)
+    ab.add_argument("--dry-run", action="store_true", help="report without writing the spec file")
+
+    rst = sub.add_parser("restore", help="re-import a backup bundle written by a prior apply")
+    rst.add_argument("bundle", help="path to a bundle zip written by a prior apply")
+    rst.add_argument("--profile", required=True)
+
+    args = ap.parse_args(argv)
+
+    if args.cmd == "schema":
+        print(json.dumps(json_schema(), indent=2))
+        return
+
+    if args.cmd == "validate":
+        _load(args.spec)
+        print(json.dumps({"ok": True, "stage": "schema"}))
+        return
+
+    if args.cmd == "compile":
+        spec = _load(args.spec)
+        from .compiler import compile_bundle
+        from .testing import stub_resolution
+
+        bundle = compile_bundle(spec, stub_resolution(spec))
+        out = Path(args.output or f"{spec.dashboard.slug}.zip")
+        out.write_bytes(bundle)
+        print(json.dumps({"ok": True, "stage": "compile", "output": str(out), "bytes": len(bundle),
+                          "note": "stub resolution (fake dataset ids); use apply for a real import"}))
+        return
+
+    if args.cmd == "check":
+        spec = _load(args.spec)
+        client = _client(args.profile)
+        from .apply import check
+
+        res = check(spec, client)
+        payload = {"ok": res.ok, "stage": "resolve", "errors": [e.as_dict() for e in res.errors]}
+        print(json.dumps(payload, indent=2))
+        sys.exit(0 if res.ok else 1)
+
+    if args.cmd == "apply":
+        spec = _load(args.spec)
+        client = _client(args.profile)
+        from .apply import apply as run_apply
+
+        report = run_apply(spec, client, args.profile)
+        print(report.to_json())
+        sys.exit(0 if report.ok else 1)
+
+    if args.cmd == "plan":
+        spec = _load(args.spec)
+        client = _client(args.profile)
+        from .dashdiff import plan as run_plan
+
+        p = run_plan(spec, client)
+        print(p.to_json())
+        sys.exit(0 if p.clean else 1)
+
+    if args.cmd == "absorb":
+        spec = _load(args.spec)
+        client = _client(args.profile)
+        from .absorb import absorb_heights
+        from .apply import _ownership_guard
+
+        guard = _ownership_guard(spec, client)
+        if guard:
+            _die({"stage": "absorb", "errors": [{"code": "ownership", "detail": guard}]})
+        existing = client.find_dashboard_by_slug(spec.dashboard.slug)
+        if existing is None:
+            _die({"stage": "absorb", "errors": [{"code": "not_found",
+                  "detail": f"no live dashboard at slug {spec.dashboard.slug!r}; apply first"}]})
+        detail = client.get(f"/api/v1/dashboard/{existing['id']}")["result"]
+        live_position = json.loads(detail.get("position_json") or "{}")
+        spec_data = json.loads(Path(args.spec).read_text(encoding="utf-8"))
+        new_data, report = absorb_heights(spec, spec_data, live_position)
+        if report.absorbed and not args.dry_run:
+            Path(args.spec).write_text(
+                json.dumps(new_data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        print(report.to_json())
+        sys.exit(0)
+
+    if args.cmd == "decompile":
+        client = _client(args.profile)
+        from .decompile import decompile_live
+
+        try:
+            result = decompile_live(args.dashboard, client)
+        except ValueError as e:
+            _die({"stage": "decompile", "errors": [{"code": "decompile", "detail": str(e)}]})
+        if args.output:
+            Path(args.output).write_text(json.dumps(result.spec, indent=2) + "\n")
+            print(json.dumps({"ok": True, "stage": "decompile", "output": args.output,
+                              "losses": result.losses_json()}, indent=2))
+        else:
+            print(json.dumps({"spec": result.spec, "losses": result.losses_json()}, indent=2))
+        return
+
+    if args.cmd == "restore":
+        try:
+            blob = Path(args.bundle).read_bytes()
+        except OSError as e:
+            _die({"stage": "restore", "errors": [{"code": "unreadable_bundle", "detail": str(e)}]})
+        # Only tool-owned bundles are restorable: same ownership rule as apply.
+        import io
+        import zipfile
+
+        import yaml
+
+        from . import ids
+
+        zf = zipfile.ZipFile(io.BytesIO(blob))
+        dash_files = [n for n in zf.namelist() if "/dashboards/" in n and n.endswith(".yaml")]
+        if not dash_files:
+            _die({"stage": "restore", "errors": [{"code": "bad_bundle", "detail": "no dashboard yaml in bundle"}]})
+        dash = yaml.safe_load(zf.read(dash_files[0]))
+        slug, u = dash.get("slug"), str(dash.get("uuid"))
+        if not slug or u != str(ids.dashboard_uuid(slug)):
+            _die({"stage": "restore", "errors": [{"code": "not_owned",
+                  "detail": f"bundle dashboard (slug={slug!r}) is not owned by this tool; refusing to import"}]})
+        client = _client(args.profile)
+        from .apply import restore_bundle
+
+        report = restore_bundle(blob, slug, client)
+        print(report.to_json())
+        sys.exit(0 if report.ok else 1)
+
+
+if __name__ == "__main__":
+    main()

chartwright/client.py

@@ -0,0 +1,227 @@
+"""Thin Superset REST client. Auth = JWT login + CSRF token + session cookie
+(Superset requires all three for mutating multipart endpoints).
+
+Enterprise-network posture: every requests-level failure is converted into a
+typed SupersetAPIError with a hint (TLS interception -> ca_bundle, proxy,
+timeouts), login guards against SSO/proxy HTML pages, and an expired access
+token triggers exactly one re-login + retry (long applies on big estates).
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Callable
+
+import requests
+
+
+class SupersetAPIError(RuntimeError):
+    def __init__(self, message: str, status: int | None = None, body: str | None = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+@dataclass
+class SupersetClient:
+    base_url: str
+    username: str
+    password: str
+    auth_provider: str = "db"
+    ca_bundle: str | None = None
+    verify: bool = True
+    session: requests.Session = field(default_factory=requests.Session)
+    _csrf: str | None = None
+    _logged_in: bool = False
+
+    def __post_init__(self) -> None:
+        self.base_url = self.base_url.rstrip("/")
+        # Corporate TLS interception: custom root CA, or (last resort) no verify.
+        self.session.verify = self.ca_bundle if self.ca_bundle else self.verify
+
+    # -- transport ------------------------------------------------------------
+
+    def _send(self, fn: Callable[[], requests.Response], relogin_on_401: bool = True,
+              tries_429: int = 3) -> requests.Response:
+        """Run one request with typed network errors, a single 401 retry, and
+        polite 429 backoff (Superset ships a rate limiter; corporate gateways
+        add their own)."""
+        try:
+            r = fn()
+        except requests.exceptions.SSLError as e:
+            raise SupersetAPIError(
+                "TLS verification failed; corporate TLS interception? Set ca_bundle "
+                "in the profile (path to your corp root CA .pem) or REQUESTS_CA_BUNDLE; "
+                f"verify=false is the last resort. Underlying: {str(e)[:300]}"
+            ) from e
+        except requests.exceptions.ProxyError as e:
+            raise SupersetAPIError(
+                f"proxy error; check HTTPS_PROXY/HTTP_PROXY/NO_PROXY: {str(e)[:300]}"
+            ) from e
+        except requests.exceptions.Timeout as e:
+            raise SupersetAPIError(f"request timed out against {self.base_url}: {str(e)[:200]}") from e
+        except requests.exceptions.RequestException as e:
+            raise SupersetAPIError(f"connection to {self.base_url} failed: {str(e)[:300]}") from e
+        if r.status_code == 401 and relogin_on_401 and self._logged_in:
+            # Access token expired mid-run (default TTLs are short); one refresh.
+            self.login()
+            r = self._send(fn, relogin_on_401=False)
+        if r.status_code == 429 and tries_429 > 0:
+            try:
+                delay = min(float(r.headers.get("Retry-After") or 2), 30)
+            except (TypeError, ValueError):
+                delay = 2.0
+            time.sleep(delay)
+            r = self._send(fn, relogin_on_401=relogin_on_401, tries_429=tries_429 - 1)
+        return r
+
+    # -- auth ---------------------------------------------------------------
+
+    def login(self) -> None:
+        r = self._send(lambda: self.session.post(
+            f"{self.base_url}/api/v1/security/login",
+            json={
+                "username": self.username,
+                "password": self.password,
+                "provider": self.auth_provider,
+                "refresh": True,
+            },
+            timeout=30,
+        ), relogin_on_401=False)
+        self._raise_for(r, "login failed")
+        try:
+            token = r.json()["access_token"]
+        except (ValueError, KeyError) as e:
+            raise SupersetAPIError(
+                "login returned a non-JSON or tokenless response; usually an SSO portal "
+                "or proxy login page intercepting the API. If this instance is SSO-only, "
+                "the password login API is disabled (known limitation).",
+                r.status_code, r.text[:300],
+            ) from e
+        self.session.headers["Authorization"] = f"Bearer {token}"
+        r = self._send(lambda: self.session.get(
+            f"{self.base_url}/api/v1/security/csrf_token/", timeout=30), relogin_on_401=False)
+        self._raise_for(r, "csrf token fetch failed")
+        self._csrf = r.json()["result"]
+        self.session.headers["X-CSRFToken"] = self._csrf
+        self.session.headers["Referer"] = self.base_url
+        self._logged_in = True
+
+    # -- generic ------------------------------------------------------------
+
+    def get(self, path: str, **params) -> dict:
+        q = {}
+        if params:
+            q["q"] = json.dumps(params.pop("q")) if "q" in params else None
+            q = {k: v for k, v in q.items() if v is not None}
+            q.update(params)
+        r = self._send(lambda: self.session.get(f"{self.base_url}{path}", params=q, timeout=60))
+        self._raise_for(r, f"GET {path} failed")
+        return r.json()
+
+    def post_json(self, path: str, payload: dict) -> requests.Response:
+        return self._send(lambda: self.session.post(f"{self.base_url}{path}", json=payload, timeout=120))
+
+    def put_json(self, path: str, payload: dict) -> requests.Response:
+        return self._send(lambda: self.session.put(f"{self.base_url}{path}", json=payload, timeout=120))
+
+    # -- datasets / databases -----------------------------------------------
+
+    def find_datasets(self, table: str) -> list[dict]:
+        out = self.get(
+            "/api/v1/dataset/",
+            q={
+                "filters": [{"col": "table_name", "opr": "eq", "value": table}],
+                "columns": ["id", "table_name", "schema", "uuid", "database.database_name", "database.id"],
+                "page_size": 100,
+            },
+        )
+        return out["result"]
+
+    def dataset_detail(self, dataset_id: int) -> dict:
+        return self.get(f"/api/v1/dataset/{dataset_id}")["result"]
+
+    # -- dashboards / charts ------------------------------------------------
+
+    def find_dashboard_by_slug(self, slug: str) -> dict | None:
+        out = self.get(
+            "/api/v1/dashboard/",
+            q={"filters": [{"col": "slug", "opr": "eq", "value": slug}], "page_size": 10},
+        )
+        results = out["result"]
+        return results[0] if results else None
+
+    def find_charts_by_name(self, name: str) -> list[dict]:
+        """Targeted lookup (never scans the estate; corporate instances can
+        hold tens of thousands of charts)."""
+        out = self.get(
+            "/api/v1/chart/",
+            q={
+                "filters": [{"col": "slice_name", "opr": "eq", "value": name}],
+                "columns": ["id", "slice_name", "uuid"],
+                "page_size": 100,
+            },
+        )
+        return out["result"]
+
+    def charts_by_uuids(self, uuid_to_name: dict[str, str]) -> dict[str, dict]:
+        """uuid -> chart summary for uuids that exist, looked up per chart NAME
+        (indexed server-side) and matched by uuid client-side."""
+        found: dict[str, dict] = {}
+        for u, name in uuid_to_name.items():
+            for c in self.find_charts_by_name(name):
+                if str(c.get("uuid")) == u:
+                    found[u] = c
+        return found
+
+    def dashboard_charts(self, dashboard_id: int) -> list[dict]:
+        return self.get(f"/api/v1/dashboard/{dashboard_id}/charts")["result"]
+
+    def delete_chart(self, chart_id: int) -> None:
+        r = self._send(lambda: self.session.delete(f"{self.base_url}/api/v1/chart/{chart_id}", timeout=60))
+        self._raise_for(r, f"delete chart {chart_id} failed")
+
+    # -- import / export ----------------------------------------------------
+
+    def import_dashboard_bundle(self, zip_bytes: bytes, overwrite: bool = True) -> requests.Response:
+        return self._send(lambda: self.session.post(
+            f"{self.base_url}/api/v1/dashboard/import/",
+            files={"formData": ("bundle.zip", zip_bytes, "application/zip")},
+            data={"overwrite": json.dumps(overwrite)},
+            # Without this, command errors can render the static HTML 500 page
+            # instead of the 422 JSON body (docs/CONTRACTS.md).
+            headers={"Accept": "application/json"},
+            timeout=120,
+        ))
+
+    def export_dashboard(self, dashboard_id: int) -> bytes:
+        r = self._send(lambda: self.session.get(
+            f"{self.base_url}/api/v1/dashboard/export/",
+            params={"q": json.dumps([dashboard_id])},
+            timeout=120,
+        ))
+        self._raise_for(r, "dashboard export failed")
+        return r.content
+
+    def export_dataset(self, dataset_id: int) -> bytes:
+        r = self._send(lambda: self.session.get(
+            f"{self.base_url}/api/v1/dataset/export/",
+            params={"q": json.dumps([dataset_id])},
+            timeout=120,
+        ))
+        self._raise_for(r, "dataset export failed")
+        return r.content
+
+    # -- chart data (smoke) ---------------------------------------------------
+
+    def chart_data(self, query_context: dict) -> requests.Response:
+        return self.post_json("/api/v1/chart/data", query_context)
+
+    # -- helpers --------------------------------------------------------------
+
+    @staticmethod
+    def _raise_for(r: requests.Response, message: str) -> None:
+        if r.status_code >= 400:
+            raise SupersetAPIError(f"{message}: HTTP {r.status_code}", r.status_code, r.text[:2000])