code-mower 0.5.0b5__py3-none-any.whl

code_mower/cloud_client/endpoints.py

@@ -0,0 +1,114 @@
+"""Endpoint normalization and health checks for CodeMower.com uploads."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+
+DEFAULT_HEALTH_PATH = "/api/health"
+DEFAULT_DASHBOARD_PATH = "/dashboard"
+
+
+def is_local_http_endpoint(endpoint: str) -> bool:
+    parsed_endpoint = urllib.parse.urlparse(endpoint)
+    return (
+        parsed_endpoint.scheme == "http"
+        and parsed_endpoint.hostname in {"localhost", "127.0.0.1"}
+    )
+
+
+def validate_upload_endpoint(endpoint: str) -> None:
+    parsed_endpoint = urllib.parse.urlparse(endpoint)
+    if parsed_endpoint.scheme != "https" and not is_local_http_endpoint(endpoint):
+        raise ValueError("upload endpoint must be https:// or a local development endpoint")
+    if not parsed_endpoint.netloc:
+        raise ValueError(f"upload endpoint is missing a host: {endpoint!r}")
+
+
+def origin_for_endpoint(endpoint: str) -> str:
+    parsed_endpoint = urllib.parse.urlparse(endpoint)
+    if not parsed_endpoint.scheme or not parsed_endpoint.netloc:
+        return ""
+    return urllib.parse.urlunparse(
+        (parsed_endpoint.scheme, parsed_endpoint.netloc, "", "", "", "")
+    )
+
+
+def url_for_endpoint_path(endpoint: str, path: str) -> str:
+    origin = origin_for_endpoint(endpoint)
+    if not origin:
+        return ""
+    return urllib.parse.urljoin(origin + "/", path.lstrip("/"))
+
+
+def dashboard_url_for_endpoint(endpoint: str) -> str:
+    return url_for_endpoint_path(endpoint, DEFAULT_DASHBOARD_PATH)
+
+
+def health_url_for_endpoint(endpoint: str) -> str:
+    return url_for_endpoint_path(endpoint, DEFAULT_HEALTH_PATH)
+
+
+def probe_cloud_service(endpoint: str, *, timeout: float) -> dict[str, Any]:
+    health_url = health_url_for_endpoint(endpoint)
+    if not health_url:
+        return {
+            "name": "service",
+            "status": "fail",
+            "message": "unable to derive health URL from upload endpoint",
+        }
+    request = urllib.request.Request(
+        health_url,
+        headers={
+            "Accept": "application/json",
+            "User-Agent": "code-mower-cloud-doctor",
+        },
+        method="GET",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            response_body = response.read().decode("utf-8", errors="replace")
+            status_code = response.getcode()
+    except urllib.error.HTTPError as exc:
+        return {
+            "name": "service",
+            "status": "fail",
+            "message": f"health check failed with HTTP {exc.code}",
+            "detail": {"health_url": health_url, "status_code": exc.code},
+        }
+    except urllib.error.URLError as exc:
+        return {
+            "name": "service",
+            "status": "fail",
+            "message": f"health check failed: {exc.reason}",
+            "detail": {"health_url": health_url},
+        }
+    parsed: dict[str, Any] = {}
+    if response_body.strip():
+        try:
+            maybe_parsed = json.loads(response_body)
+            if isinstance(maybe_parsed, dict):
+                parsed = maybe_parsed
+        except json.JSONDecodeError:
+            parsed = {}
+    if 200 <= status_code < 300:
+        detail: dict[str, Any] = {"health_url": health_url, "status_code": status_code}
+        for key in ("app", "supabaseConfigured"):
+            if key in parsed and isinstance(parsed[key], str | bool | int | float):
+                detail[key] = parsed[key]
+        return {
+            "name": "service",
+            "status": "pass",
+            "message": f"health endpoint is reachable: {health_url}",
+            "detail": detail,
+        }
+    return {
+        "name": "service",
+        "status": "fail",
+        "message": f"health check returned HTTP {status_code}",
+        "detail": {"health_url": health_url, "status_code": status_code},
+    }

code_mower/cloud_client/errors.py

@@ -0,0 +1,7 @@
+"""Shared CodeMower.com client exceptions."""
+
+from __future__ import annotations
+
+
+class CloudBundleError(ValueError):
+    """Raised when a cloud bundle or upload request is unsafe or invalid."""

code_mower/cloud_client/events.py

@@ -0,0 +1,278 @@
+"""Structured cloud event and repository metadata helpers."""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import subprocess
+import uuid
+from pathlib import Path
+from typing import Any
+
+from .bundle import MAX_EVENT_COUNT, SAFE_EVENT_TYPES, SAFE_REPORT_KINDS, validate_metadata_payload
+from .dogfood import DogfoodPlan
+from .errors import CloudBundleError
+from .git_metadata import run_git
+
+
+EVENT_SCHEMA = "code_mower.benchmarkEvent.v1"
+GITHUB_RUN_LIST_FIELDS = (
+    "databaseId",
+    "name",
+    "status",
+    "conclusion",
+    "event",
+    "headBranch",
+    "headSha",
+    "createdAt",
+    "updatedAt",
+    "url",
+)
+
+
+def safe_kind(value: str) -> str:
+    kind = value.strip()
+    if kind not in SAFE_REPORT_KINDS:
+        allowed = ", ".join(sorted(SAFE_REPORT_KINDS))
+        raise CloudBundleError(f"unsupported report kind {value!r}; allowed: {allowed}")
+    return kind
+
+
+def safe_event_type(value: str) -> str:
+    event_type = value.strip()
+    if event_type not in SAFE_EVENT_TYPES:
+        allowed = ", ".join(sorted(SAFE_EVENT_TYPES))
+        raise CloudBundleError(
+            f"unsupported event type {value!r}; allowed: {allowed}"
+        )
+    return event_type
+
+
+def utc_now() -> str:
+    return dt.datetime.now(dt.UTC).replace(microsecond=0).isoformat()
+
+
+def build_dogfood_event(
+    *,
+    repo_path: Path,
+    plan: DogfoodPlan,
+) -> dict[str, Any]:
+    status = run_git(repo_path, ["status", "--porcelain"])
+    return {
+        "schema": EVENT_SCHEMA,
+        "event_id": str(uuid.uuid4()),
+        "event_type": "dogfood_upload",
+        "created_at": utc_now(),
+        "repo_slug": plan.repo_slug,
+        "team_id": plan.team_id,
+        "install_id": plan.install_id,
+        "source": plan.source,
+        "provider": "",
+        "lens": "",
+        "status": "observed",
+        "git": {
+            "sha": run_git(repo_path, ["rev-parse", "HEAD"]),
+            "branch": run_git(repo_path, ["branch", "--show-current"]),
+            "dirty": bool(status),
+        },
+        "metrics": {
+            "report_count": plan.report_count,
+            "extra_event_count": plan.extra_event_count,
+        },
+        "dimensions": {
+            "command": "code-mower cloud dogfood",
+        },
+    }
+
+
+def event_id_from_github_run(repo_slug: str, run: dict[str, Any]) -> str:
+    database_id = str(run.get("databaseId") or "").strip()
+    if database_id:
+        run_url = f"https://github.com/{repo_slug}/actions/runs/{database_id}"
+        return str(uuid.uuid5(uuid.NAMESPACE_URL, run_url))
+    run_url = str(run.get("url") or "").strip()
+    if run_url:
+        return str(uuid.uuid5(uuid.NAMESPACE_URL, run_url))
+    return str(uuid.uuid4())
+
+
+def run_gh_run_list(
+    *,
+    repo_slug: str,
+    limit: int,
+    repo_path: Path,
+) -> list[dict[str, Any]]:
+    command = [
+        "gh",
+        "run",
+        "list",
+        "--repo",
+        repo_slug,
+        "--limit",
+        str(limit),
+        "--json",
+        ",".join(GITHUB_RUN_LIST_FIELDS),
+    ]
+    try:
+        completed = subprocess.run(
+            command,
+            cwd=repo_path,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+    except OSError as exc:
+        raise CloudBundleError("GitHub Actions catch-up requires the `gh` CLI") from exc
+    if completed.returncode != 0:
+        detail = completed.stderr.strip() or completed.stdout.strip()
+        raise CloudBundleError(
+            "unable to read GitHub Actions runs with `gh run list`"
+            + (f": {detail}" if detail else "")
+        )
+    try:
+        parsed = json.loads(completed.stdout or "[]")
+    except json.JSONDecodeError as exc:
+        raise CloudBundleError("`gh run list --json` returned invalid JSON") from exc
+    if not isinstance(parsed, list):
+        raise CloudBundleError("`gh run list --json` must return a JSON array")
+    runs: list[dict[str, Any]] = []
+    for item in parsed:
+        if not isinstance(item, dict):
+            raise CloudBundleError("`gh run list --json` returned a non-object run")
+        runs.append(item)
+    return runs
+
+
+def build_workflow_run_event(
+    *,
+    repo_slug: str,
+    team_id: str,
+    install_id: str,
+    source: str,
+    run: dict[str, Any],
+    include_git_ref: bool,
+) -> dict[str, Any]:
+    status = str(run.get("conclusion") or run.get("status") or "observed")
+    dimensions: dict[str, Any] = {
+        "workflow_name": str(run.get("name") or ""),
+        "trigger": str(run.get("event") or ""),
+        "run_status": str(run.get("status") or ""),
+        "run_conclusion": str(run.get("conclusion") or ""),
+        "run_url": str(run.get("url") or ""),
+        "updated_at": str(run.get("updatedAt") or ""),
+    }
+    if include_git_ref:
+        dimensions["head_branch"] = str(run.get("headBranch") or "")
+        dimensions["head_sha"] = str(run.get("headSha") or "")
+    event = {
+        "schema": EVENT_SCHEMA,
+        "event_id": event_id_from_github_run(repo_slug, run),
+        "event_type": "workflow_run",
+        "created_at": str(run.get("createdAt") or utc_now()),
+        "repo_slug": repo_slug,
+        "team_id": team_id,
+        "install_id": install_id,
+        "source": source,
+        "provider": "",
+        "lens": "base",
+        "status": status,
+        "metrics": {},
+        "dimensions": dimensions,
+    }
+    return normalize_event(event, "workflow_run")
+
+
+def normalize_event(value: dict[str, Any], event_type: str) -> dict[str, Any]:
+    validate_metadata_payload(value)
+    normalized = dict(value)
+    normalized["schema"] = str(normalized.get("schema") or EVENT_SCHEMA)
+    if normalized["schema"] != EVENT_SCHEMA:
+        raise CloudBundleError(
+            f"unsupported event schema {normalized['schema']!r}; expected {EVENT_SCHEMA}"
+        )
+    normalized["event_type"] = safe_event_type(
+        str(normalized.get("event_type") or event_type)
+    )
+    normalized["event_id"] = str(normalized.get("event_id") or uuid.uuid4())
+    normalized["created_at"] = str(normalized.get("created_at") or utc_now())
+    for key in (
+        "repo_slug",
+        "team_id",
+        "install_id",
+        "source",
+        "provider",
+        "lens",
+        "status",
+    ):
+        normalized[key] = str(normalized.get(key) or "")
+    metrics = normalized.get("metrics")
+    if metrics is None:
+        normalized["metrics"] = {}
+    elif not isinstance(metrics, dict):
+        raise CloudBundleError("structured event metrics must be an object")
+    dimensions = normalized.get("dimensions")
+    if dimensions is None:
+        normalized["dimensions"] = {}
+    elif not isinstance(dimensions, dict):
+        raise CloudBundleError("structured event dimensions must be an object")
+    validate_metadata_payload(normalized)
+    return normalized
+
+
+def load_event_file(path: Path, event_type: str) -> list[dict[str, Any]]:
+    source = path.expanduser()
+    if not source.is_file():
+        raise CloudBundleError(f"event file does not exist or is not a file: {source}")
+    try:
+        text = source.read_text(encoding="utf-8")
+    except UnicodeDecodeError as exc:
+        raise CloudBundleError(f"event file is not UTF-8 text: {source}") from exc
+    except OSError as exc:
+        raise CloudBundleError(f"unable to read event file {source}: {exc}") from exc
+    if not text.strip():
+        return []
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError:
+        parsed = []
+        for line_number, line in enumerate(text.splitlines(), start=1):
+            if not line.strip():
+                continue
+            try:
+                parsed.append(json.loads(line))
+            except json.JSONDecodeError as exc:
+                raise CloudBundleError(
+                    f"event file {source} line {line_number} is not JSON"
+                ) from exc
+    if isinstance(parsed, dict):
+        parsed_events = [parsed]
+    elif isinstance(parsed, list):
+        parsed_events = parsed
+    else:
+        raise CloudBundleError(
+            f"event file must contain an object, array, or JSONL: {source}"
+        )
+    events: list[dict[str, Any]] = []
+    for item in parsed_events:
+        if not isinstance(item, dict):
+            raise CloudBundleError(
+                f"event file contains a non-object event: {source}"
+            )
+        events.append(normalize_event(item, event_type))
+    return events
+
+
+def parse_event_args(values: list[str]) -> list[dict[str, Any]]:
+    events: list[dict[str, Any]] = []
+    for raw in values:
+        if "=" not in raw:
+            raise CloudBundleError(
+                "--event entries must use EVENT_TYPE=PATH, for example reviewer_run=run.json"
+            )
+        event_type, path_text = raw.split("=", 1)
+        events.extend(load_event_file(Path(path_text), safe_event_type(event_type)))
+    if len(events) > MAX_EVENT_COUNT:
+        raise CloudBundleError(
+            f"too many events: {len(events)}; max {MAX_EVENT_COUNT}"
+        )
+    return events

code_mower/cloud_client/export.py

@@ -0,0 +1,272 @@
+"""Local cloud benchmark bundle materialization."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+from typing import Any
+
+from .bundle import (
+    BUNDLE_MANIFEST_FILENAME,
+    BUNDLE_SCHEMA,
+    EXCLUDED_CONTENT,
+    EXPECTED_BUNDLE_ENTRIES,
+    MAX_EVENT_COUNT,
+    is_bundle_manifest,
+)
+from .errors import CloudBundleError
+from .events import normalize_event, safe_kind
+
+
+def safe_target_name(path: Path, index: int, *, anonymous: bool = False) -> str:
+    suffix = path.suffix.lower()
+    if suffix not in {".json", ".jsonl", ".md", ".txt"}:
+        raise CloudBundleError(
+            f"unsupported report file extension for {path}; expected .json, .jsonl, .md, or .txt"
+        )
+    if anonymous:
+        return f"{index:02d}-report{suffix}"
+    stem = "".join(char if char.isalnum() or char in {"-", "_"} else "-" for char in path.stem)
+    stem = stem.strip("-_") or f"report-{index}"
+    return f"{index:02d}-{stem}{suffix}"
+
+
+def plan_report(
+    path: Path,
+    output_dir: Path,
+    kind: str,
+    index: int,
+    *,
+    anonymous: bool,
+) -> dict[str, Any]:
+    source = path.expanduser()
+    if not source.is_file():
+        raise CloudBundleError(f"report does not exist or is not a file: {source}")
+    target_name = safe_target_name(source, index, anonymous=anonymous)
+    reports_dir = output_dir / "reports"
+    try:
+        if source.resolve().is_relative_to(reports_dir.resolve()):
+            raise CloudBundleError(
+                f"report source must not be inside the bundle reports directory: {source}"
+            )
+    except OSError as exc:
+        raise CloudBundleError(f"unable to resolve report path {source}: {exc}") from exc
+    return {
+        "kind": kind,
+        "source": source,
+        "source_basename": "" if anonymous else source.name,
+        "target_name": target_name,
+        "target": f"reports/{target_name}",
+    }
+
+
+def stage_reports(
+    planned_reports: list[dict[str, Any]],
+    output_dir: Path,
+) -> tuple[list[dict[str, Any]], Path]:
+    stage_dir = output_dir / ".reports.tmp"
+    if stage_dir.exists():
+        if not stage_dir.is_dir():
+            raise CloudBundleError(f"bundle staging path is not a directory: {stage_dir}")
+        try:
+            shutil.rmtree(stage_dir)
+        except OSError as exc:
+            raise CloudBundleError(f"unable to clear stale staging directory: {exc}") from exc
+    try:
+        stage_dir.mkdir(parents=True)
+    except OSError as exc:
+        raise CloudBundleError(f"unable to create bundle staging directory: {exc}") from exc
+
+    included_reports: list[dict[str, Any]] = []
+    try:
+        for report in planned_reports:
+            source = report["source"]
+            target = stage_dir / report["target_name"]
+            shutil.copyfile(source, target)
+            stat = target.stat()
+            included_reports.append(
+                {
+                    "kind": report["kind"],
+                    "source_basename": report["source_basename"],
+                    "target": report["target"],
+                    "bytes": stat.st_size,
+                }
+            )
+    except OSError as exc:
+        shutil.rmtree(stage_dir, ignore_errors=True)
+        raise CloudBundleError(f"unable to stage bundle reports: {exc}") from exc
+    return included_reports, stage_dir
+
+
+def swap_reports(stage_dir: Path, reports_dir: Path) -> None:
+    try:
+        if reports_dir.exists():
+            shutil.rmtree(reports_dir)
+        stage_dir.replace(reports_dir)
+    except OSError as exc:
+        shutil.rmtree(stage_dir, ignore_errors=True)
+        raise CloudBundleError(f"unable to install staged bundle reports: {exc}") from exc
+
+
+def existing_bundle_manifest(output_dir: Path) -> bool:
+    manifest_path = output_dir / BUNDLE_MANIFEST_FILENAME
+    if not manifest_path.is_file():
+        return False
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+        return False
+    return is_bundle_manifest(manifest)
+
+
+def unexpected_bundle_entries(output_dir: Path) -> list[str]:
+    try:
+        return sorted(
+            entry.name
+            for entry in output_dir.iterdir()
+            if entry.name not in EXPECTED_BUNDLE_ENTRIES
+        )
+    except OSError as exc:
+        raise CloudBundleError(f"unable to inspect bundle output directory: {exc}") from exc
+
+
+def build_cloud_bundle(
+    *,
+    reports: list[tuple[Path, str]],
+    events: list[dict[str, Any]] | None = None,
+    output_dir: Path,
+    repo_slug: str = "",
+    install_id: str = "",
+    team_id: str = "",
+    anonymous: bool = False,
+) -> dict[str, Any]:
+    if output_dir.exists():
+        if not output_dir.is_dir():
+            raise CloudBundleError(f"bundle output path is not a directory: {output_dir}")
+        try:
+            has_existing_content = any(output_dir.iterdir())
+        except OSError as exc:
+            raise CloudBundleError(f"unable to inspect bundle output directory: {exc}") from exc
+        if has_existing_content and not existing_bundle_manifest(output_dir):
+            raise CloudBundleError(
+                "refusing to write into an existing non-bundle output directory; "
+                "choose a fresh --output-dir"
+            )
+        unexpected_entries = unexpected_bundle_entries(output_dir)
+        if unexpected_entries:
+            sample = ", ".join(unexpected_entries[:3])
+            if len(unexpected_entries) > 3:
+                sample += f", ... ({len(unexpected_entries)} total)"
+            raise CloudBundleError(
+                f"refusing to reuse bundle directory with unexpected entries: {sample}"
+            )
+    else:
+        try:
+            output_dir.mkdir(parents=True, exist_ok=True)
+        except OSError as exc:
+            raise CloudBundleError(
+                f"unable to create bundle output directory {output_dir}: {exc}"
+            ) from exc
+    planned_reports = [
+        plan_report(path, output_dir, safe_kind(kind), index, anonymous=anonymous)
+        for index, (path, kind) in enumerate(reports, start=1)
+    ]
+    included_reports, stage_dir = stage_reports(planned_reports, output_dir)
+    included_events = [
+        normalize_event(event, str(event.get("event_type") or "dogfood_upload"))
+        for event in events or []
+    ]
+    if len(included_events) > MAX_EVENT_COUNT:
+        raise CloudBundleError(
+            f"too many events: {len(included_events)}; max {MAX_EVENT_COUNT}"
+        )
+    manifest = {
+        "schema": BUNDLE_SCHEMA,
+        "privacy_mode": "anonymous" if anonymous else "metadata_and_reports",
+        "upload_ready": False,
+        "upload_status": "local_export_only",
+        "repo_slug": "" if anonymous else repo_slug,
+        "team_id": "" if anonymous else team_id,
+        "install_id": "" if anonymous else install_id,
+        "included_reports": included_reports,
+        "events": [] if anonymous else included_events,
+        "excluded_content": list(EXCLUDED_CONTENT),
+        "notes": [
+            "This bundle is local-only; upload support must present a dry-run before network transfer.",
+            "Do not include source code, raw diffs, raw transcripts, raw stdout/stderr, auth output, or secrets.",
+            "Reports are copied exactly as supplied; review them before sharing outside your machine.",
+            "Structured events are metadata-only and should not contain source, diffs, transcripts, stdout/stderr, auth output, or secrets.",
+        ],
+    }
+    manifest_path = output_dir / BUNDLE_MANIFEST_FILENAME
+    readme = output_dir / "README.md"
+    manifest_tmp = output_dir / f".{BUNDLE_MANIFEST_FILENAME}.tmp"
+    readme_tmp = output_dir / ".README.md.tmp"
+    try:
+        manifest_tmp.write_text(
+            json.dumps(manifest, indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+    except OSError as exc:
+        shutil.rmtree(stage_dir, ignore_errors=True)
+        raise CloudBundleError(f"unable to write bundle manifest {manifest_tmp}: {exc}") from exc
+    try:
+        readme_tmp.write_text(render_bundle_readme(manifest), encoding="utf-8")
+    except OSError as exc:
+        shutil.rmtree(stage_dir, ignore_errors=True)
+        manifest_tmp.unlink(missing_ok=True)
+        raise CloudBundleError(f"unable to write bundle README {readme_tmp}: {exc}") from exc
+    swap_reports(stage_dir, output_dir / "reports")
+    try:
+        manifest_tmp.replace(manifest_path)
+        readme_tmp.replace(readme)
+    except OSError as exc:
+        raise CloudBundleError(f"unable to install bundle manifest files: {exc}") from exc
+    return {
+        "mode": "cloud-export",
+        "output_dir": str(output_dir),
+        "manifest": str(manifest_path),
+        "readme": str(readme),
+        "included_reports": included_reports,
+        "event_count": len(manifest["events"]),
+        "upload_ready": False,
+    }
+
+
+def render_bundle_readme(manifest: dict[str, Any]) -> str:
+    lines = [
+        "# Code Mower Cloud Benchmark Bundle",
+        "",
+        "This local bundle is the cloud-ready handoff shape for opt-in benchmark reporting.",
+        "It is not uploaded by the OSS CLI.",
+        "",
+        "Excluded by default:",
+    ]
+    lines.extend(f"- {item}" for item in manifest["excluded_content"])
+    lines.extend(["", "Included reports:"])
+    if manifest["included_reports"]:
+        lines.extend(
+            f"- {entry['target']} ({entry['kind']}, {entry['bytes']} bytes)"
+            for entry in manifest["included_reports"]
+        )
+    else:
+        lines.append("- none")
+    lines.extend(["", "Structured events:"])
+    events = manifest.get("events", [])
+    if events:
+        lines.extend(
+            f"- {entry.get('event_type', 'unknown')} ({entry.get('event_id', 'no-id')})"
+            for entry in events
+        )
+    else:
+        lines.append("- none")
+    lines.extend(
+        [
+            "",
+            "Before sharing this bundle, inspect every file under `reports/`.",
+            "Future upload support should require an explicit dry run and user confirmation.",
+            "",
+        ]
+    )
+    return "\n".join(lines)