code-mower 0.5.0b5__py3-none-any.whl

code_mower/cloud_client/__init__.py

@@ -0,0 +1,173 @@
+"""CodeMower.com client internals."""
+
+from .bundle import (
+    BUNDLE_MANIFEST_FILENAME,
+    BUNDLE_SCHEMA,
+    EXCLUDED_CONTENT,
+    EXPECTED_BUNDLE_ENTRIES,
+    MAX_EVENT_COUNT,
+    MAX_REPORT_UPLOAD_BYTES,
+    SAFE_EVENT_TYPES,
+    SAFE_REPORT_KINDS,
+    is_bundle_manifest,
+    validate_metadata_payload,
+)
+from .endpoints import (
+    DEFAULT_DASHBOARD_PATH,
+    DEFAULT_HEALTH_PATH,
+    dashboard_url_for_endpoint,
+    health_url_for_endpoint,
+    is_local_http_endpoint,
+    probe_cloud_service,
+    validate_upload_endpoint,
+)
+from .export import (
+    build_cloud_bundle,
+    existing_bundle_manifest,
+    plan_report,
+    render_bundle_readme,
+    safe_target_name,
+    stage_reports,
+    swap_reports,
+    unexpected_bundle_entries,
+)
+from .dogfood import (
+    DEFAULT_DOGFOOD_REPORTS,
+    DogfoodPlan,
+    build_dogfood_dry_run_preview,
+    build_dogfood_plan,
+    default_dogfood_reports,
+)
+from .doctor import (
+    render_cloud_doctor_text,
+    run_cloud_doctor,
+)
+from .events import (
+    EVENT_SCHEMA,
+    GITHUB_RUN_LIST_FIELDS,
+    build_dogfood_event,
+    build_workflow_run_event,
+    event_id_from_github_run,
+    load_event_file,
+    normalize_event,
+    parse_event_args,
+    run_gh_run_list,
+    safe_event_type,
+    safe_kind,
+    utc_now,
+)
+from .git_metadata import (
+    detect_repo_slug,
+    repo_slug_from_remote,
+    run_git,
+)
+from .manifest import (
+    load_bundle_manifest,
+    report_path_from_manifest,
+)
+from .reports import included_report_payloads
+from .operations import (
+    catch_up_upload,
+    dogfood_upload,
+    parse_repo_sync_spec,
+    repo_sync_output_name,
+    repo_sync_upload,
+    reviewer_runs_upload,
+)
+from .errors import CloudBundleError
+from .setup import (
+    DEFAULT_INSTALL_ID_ENV,
+    DEFAULT_SETUP_INSTALL_ID,
+    DEFAULT_TEAM_ID_ENV,
+    DEFAULT_TOKEN_ENV,
+    DEFAULT_UPLOAD_ENDPOINT,
+    default_setup_path,
+    read_token_file,
+    render_setup_env,
+    resolve_setup_token,
+    run_cloud_setup,
+    safe_config_stem,
+    token_prefix,
+    write_setup_env_file,
+)
+from .upload import (
+    UPLOAD_SCHEMA,
+    build_upload_payload,
+    post_upload_payload,
+)
+
+__all__ = [
+    "BUNDLE_MANIFEST_FILENAME",
+    "BUNDLE_SCHEMA",
+    "DEFAULT_DASHBOARD_PATH",
+    "DEFAULT_HEALTH_PATH",
+    "EXCLUDED_CONTENT",
+    "EXPECTED_BUNDLE_ENTRIES",
+    "DEFAULT_DOGFOOD_REPORTS",
+    "MAX_EVENT_COUNT",
+    "MAX_REPORT_UPLOAD_BYTES",
+    "SAFE_EVENT_TYPES",
+    "SAFE_REPORT_KINDS",
+    "UPLOAD_SCHEMA",
+    "CloudBundleError",
+    "DEFAULT_INSTALL_ID_ENV",
+    "DEFAULT_SETUP_INSTALL_ID",
+    "DEFAULT_TEAM_ID_ENV",
+    "DEFAULT_TOKEN_ENV",
+    "DEFAULT_UPLOAD_ENDPOINT",
+    "DogfoodPlan",
+    "EVENT_SCHEMA",
+    "GITHUB_RUN_LIST_FIELDS",
+    "build_dogfood_event",
+    "build_dogfood_dry_run_preview",
+    "build_dogfood_plan",
+    "build_workflow_run_event",
+    "build_cloud_bundle",
+    "build_upload_payload",
+    "catch_up_upload",
+    "dashboard_url_for_endpoint",
+    "default_setup_path",
+    "detect_repo_slug",
+    "default_dogfood_reports",
+    "dogfood_upload",
+    "event_id_from_github_run",
+    "existing_bundle_manifest",
+    "health_url_for_endpoint",
+    "included_report_payloads",
+    "is_local_http_endpoint",
+    "is_bundle_manifest",
+    "load_bundle_manifest",
+    "load_event_file",
+    "normalize_event",
+    "plan_report",
+    "parse_repo_sync_spec",
+    "parse_event_args",
+    "post_upload_payload",
+    "probe_cloud_service",
+    "read_token_file",
+    "render_bundle_readme",
+    "render_cloud_doctor_text",
+    "render_setup_env",
+    "repo_slug_from_remote",
+    "repo_sync_output_name",
+    "repo_sync_upload",
+    "report_path_from_manifest",
+    "resolve_setup_token",
+    "reviewer_runs_upload",
+    "run_cloud_doctor",
+    "run_cloud_setup",
+    "run_gh_run_list",
+    "run_git",
+    "safe_target_name",
+    "safe_config_stem",
+    "safe_event_type",
+    "safe_kind",
+    "stage_reports",
+    "swap_reports",
+    "token_prefix",
+    "unexpected_bundle_entries",
+    "utc_now",
+    "validate_metadata_payload",
+    "validate_upload_endpoint",
+    "write_setup_env_file",
+]

code_mower/cloud_client/bundle.py

@@ -0,0 +1,155 @@
+"""Cloud bundle schema and safety metadata."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from .errors import CloudBundleError
+
+
+BUNDLE_SCHEMA = "code_mower.cloudBenchmarkBundle.v1"
+BUNDLE_MANIFEST_FILENAME = "code-mower-cloud-bundle.json"
+MAX_REPORT_UPLOAD_BYTES = 1_000_000
+MAX_EVENT_COUNT = 500
+MAX_METADATA_DEPTH = 32
+SAFE_REPORT_KINDS = {
+    "authoring-runs",
+    "calibration-runs",
+    "lane-policy",
+    "reviewer-metrics",
+    "spend",
+    "value-report",
+}
+SAFE_EVENT_TYPES = {
+    "calibration_run",
+    "dogfood_upload",
+    "lane_policy_snapshot",
+    "reviewer_run",
+    "value_report_snapshot",
+    "workflow_run",
+}
+EXCLUDED_CONTENT = (
+    "source_code",
+    "raw_diffs",
+    "raw_model_transcripts",
+    "raw_stdout_stderr",
+    "auth_probe_output",
+    "secrets",
+)
+EXPECTED_BUNDLE_ENTRIES = {
+    "README.md",
+    BUNDLE_MANIFEST_FILENAME,
+    "reports",
+    ".README.md.tmp",
+    f".{BUNDLE_MANIFEST_FILENAME}.tmp",
+    ".reports.tmp",
+}
+UNSAFE_METADATA_KEY_FRAGMENTS = (
+    "api_key",
+    "apikey",
+    "auth_output",
+    "auth_preview",
+    "auth_probe_output",
+    "authorization",
+    "cookie",
+    "output_preview",
+    "password",
+    "private_key",
+    "raw_diff",
+    "raw_diffs",
+    "raw_model_transcript",
+    "raw_model_transcripts",
+    "raw_output",
+    "raw_stderr",
+    "raw_stdout",
+    "raw_stdout_stderr",
+    "secret",
+    "session_id",
+    "source_code",
+    "stderr",
+    "stdout",
+    "token_prefix",
+    "token_value",
+    "transcript",
+)
+UNSAFE_METADATA_VALUE_PATTERNS = tuple(
+    re.compile(pattern, re.IGNORECASE)
+    for pattern in (
+        r"gh[pousr]_[A-Za-z0-9_]{20,}",
+        r"github_pat_[A-Za-z0-9_]{20,}",
+        r"sk-[A-Za-z0-9_-]{20,}",
+        r"cmw_(?:live|test)_[A-Za-z0-9_-]{8,}",
+        r"AIza[0-9A-Za-z\-_]{20,}",
+        r"-----BEGIN [A-Z ]*PRIVATE KEY-----",
+        r"Bearer\s+[A-Za-z0-9._~+/=-]{12,}",
+        r"(?:ANTHROPIC_API_KEY|CODE_MOWER_CLOUD_TOKEN|GEMINI_API_KEY|GITHUB_TOKEN|OPENAI_API_KEY)=",
+    )
+)
+
+
+def is_bundle_manifest(manifest: Any) -> bool:
+    return isinstance(manifest, dict) and manifest.get("schema") == BUNDLE_SCHEMA
+
+
+def _is_unsafe_metadata_key(key: str) -> bool:
+    with_word_boundaries = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "_", key.strip())
+    normalized = re.sub(r"[^A-Za-z0-9]+", "_", with_word_boundaries).lower().strip("_")
+    if normalized == "token" or normalized.endswith("_token"):
+        return True
+    return any(fragment in normalized for fragment in UNSAFE_METADATA_KEY_FRAGMENTS)
+
+
+def _unsafe_metadata_value_reason(value: str) -> str:
+    for pattern in UNSAFE_METADATA_VALUE_PATTERNS:
+        if pattern.search(value):
+            return pattern.pattern
+    return ""
+
+
+def validate_metadata_payload(
+    value: Any,
+    *,
+    path: str = "$",
+    depth: int = 0,
+    max_depth: int = MAX_METADATA_DEPTH,
+) -> None:
+    """Reject structured cloud metadata that looks like raw output or secrets."""
+
+    if depth > max_depth:
+        raise CloudBundleError(
+            "structured cloud metadata is too deeply nested at "
+            f"{path!r}; max depth is {max_depth}"
+        )
+    if isinstance(value, dict):
+        for key, item in value.items():
+            key_text = str(key)
+            child_path = f"{path}.{key_text}"
+            if _is_unsafe_metadata_key(key_text):
+                raise CloudBundleError(
+                    "structured cloud metadata contains unsafe field "
+                    f"{child_path!r}; exclude raw output, auth state, and secrets"
+                )
+            validate_metadata_payload(
+                item,
+                path=child_path,
+                depth=depth + 1,
+                max_depth=max_depth,
+            )
+        return
+    if isinstance(value, list):
+        for index, item in enumerate(value):
+            validate_metadata_payload(
+                item,
+                path=f"{path}[{index}]",
+                depth=depth + 1,
+                max_depth=max_depth,
+            )
+        return
+    if isinstance(value, str):
+        reason = _unsafe_metadata_value_reason(value)
+        if reason:
+            raise CloudBundleError(
+                "structured cloud metadata contains a secret-like value at "
+                f"{path!r}; matched safety pattern {reason!r}"
+            )

code_mower/cloud_client/doctor.py

@@ -0,0 +1,206 @@
+"""Cloud upload readiness diagnostics."""
+
+from __future__ import annotations
+
+import os
+import shlex
+from pathlib import Path
+from typing import Any
+
+from .bundle import BUNDLE_MANIFEST_FILENAME
+from .endpoints import (
+    dashboard_url_for_endpoint,
+    health_url_for_endpoint,
+    is_local_http_endpoint,
+    probe_cloud_service,
+    validate_upload_endpoint,
+)
+from .errors import CloudBundleError
+from .upload import build_upload_payload
+
+
+def _validate_upload_endpoint(endpoint: str) -> None:
+    try:
+        validate_upload_endpoint(endpoint)
+    except ValueError as exc:
+        raise CloudBundleError(str(exc)) from exc
+
+
+def run_cloud_doctor(
+    *,
+    bundle_dir: Path,
+    endpoint: str,
+    token_env: str,
+    require_token: bool = True,
+    probe_service: bool = False,
+    timeout: float = 5.0,
+) -> dict[str, Any]:
+    checks: list[dict[str, Any]] = []
+    endpoint_is_valid = False
+
+    try:
+        _validate_upload_endpoint(endpoint)
+        endpoint_is_valid = True
+        checks.append(
+            {
+                "name": "endpoint",
+                "status": "pass",
+                "message": f"upload endpoint is allowed: {endpoint}",
+            }
+        )
+    except CloudBundleError as exc:
+        checks.append(
+            {
+                "name": "endpoint",
+                "status": "fail",
+                "message": str(exc),
+            }
+        )
+
+    if probe_service and endpoint_is_valid:
+        checks.append(probe_cloud_service(endpoint, timeout=timeout))
+    elif endpoint_is_valid:
+        checks.append(
+            {
+                "name": "service",
+                "status": "skip",
+                "message": "service health probe skipped; pass --probe-service to check it",
+                "detail": {"health_url": health_url_for_endpoint(endpoint)},
+            }
+        )
+
+    token_present = bool(os.environ.get(token_env, ""))
+    if token_present:
+        checks.append(
+            {
+                "name": "token",
+                "status": "pass",
+                "message": f"{token_env} is set",
+            }
+        )
+    elif is_local_http_endpoint(endpoint):
+        checks.append(
+            {
+                "name": "token",
+                "status": "warn",
+                "message": (
+                    f"{token_env} is not set; local configless ingest may still work"
+                ),
+            }
+        )
+    elif not require_token:
+        checks.append(
+            {
+                "name": "token",
+                "status": "warn",
+                "message": f"{token_env} is not set; upload will remain disabled",
+                "remediation": (
+                    "Run `code-mower cloud setup --token-stdin` or export "
+                    f"{token_env} before using --yes."
+                ),
+            }
+        )
+    else:
+        checks.append(
+            {
+                "name": "token",
+                "status": "fail",
+                "message": f"{token_env} is not set",
+                "remediation": (
+                    "Set CODE_MOWER_CLOUD_TOKEN to a team ingest token before "
+                    "running cloud upload --yes."
+                ),
+            }
+        )
+
+    manifest_path = bundle_dir / BUNDLE_MANIFEST_FILENAME
+    if manifest_path.is_file():
+        try:
+            payload = build_upload_payload(bundle_dir=bundle_dir, include_reports=False)
+            checks.append(
+                {
+                    "name": "bundle",
+                    "status": "pass",
+                    "message": (
+                        f"bundle is readable with {len(payload['reports'])} report summaries "
+                        f"and {len(payload['events'])} structured events"
+                    ),
+                }
+            )
+        except CloudBundleError as exc:
+            checks.append(
+                {
+                    "name": "bundle",
+                    "status": "fail",
+                    "message": str(exc),
+                }
+            )
+    else:
+        checks.append(
+            {
+                "name": "bundle",
+                "status": "warn",
+                "message": (
+                    f"bundle manifest not found at {manifest_path}; run cloud export first"
+                ),
+            }
+        )
+
+    failures = sum(1 for check in checks if check["status"] == "fail")
+    warnings = sum(1 for check in checks if check["status"] == "warn")
+    return {
+        "mode": "cloud-doctor",
+        "status": "fail" if failures else "pass",
+        "endpoint": endpoint,
+        "dashboard_url": dashboard_url_for_endpoint(endpoint),
+        "health_url": health_url_for_endpoint(endpoint),
+        "token_env": token_env,
+        "bundle_dir": str(bundle_dir),
+        "checks": checks,
+        "failures": failures,
+        "warnings": warnings,
+        "next_steps": [
+            {
+                "id": "open-dashboard",
+                "label": "Open the Code Mower Cloud dashboard",
+                "url": dashboard_url_for_endpoint(endpoint),
+            },
+            {
+                "id": "setup-token",
+                "label": "Store a dashboard-issued token locally",
+                "command": (
+                    "code-mower cloud setup --token-stdin "
+                    "--team-id YOUR_TEAM_SLUG --install-id YOUR_INSTALL_ID"
+                ),
+            },
+            {
+                "id": "dry-run-upload",
+                "label": "Preview the metadata upload without network transfer",
+                "command": f"code-mower cloud upload {shlex.quote(str(bundle_dir))} --dry-run --json",
+            },
+            {
+                "id": "upload",
+                "label": "Upload metadata after inspecting the dry run",
+                "command": f"code-mower cloud upload {shlex.quote(str(bundle_dir))} --yes --json",
+            },
+        ],
+    }
+
+
+def render_cloud_doctor_text(report: dict[str, Any]) -> str:
+    lines = [
+        "Code Mower cloud doctor",
+        f"Status: {report['status']}",
+        f"Endpoint: {report['endpoint']}",
+        f"Dashboard: {report.get('dashboard_url', '')}",
+        f"Token env: {report['token_env']}",
+        f"Bundle: {report['bundle_dir']}",
+        "",
+    ]
+    for check in report["checks"]:
+        lines.append(
+            f"- {check['status'].upper()} {check['name']}: {check['message']}"
+        )
+        if check.get("remediation"):
+            lines.append(f"  remediation: {check['remediation']}")
+    return "\n".join(lines) + "\n"

code_mower/cloud_client/dogfood.py

@@ -0,0 +1,78 @@
+"""Routine dogfood upload planning helpers.
+
+The cloud CLI remains the public API. These helpers keep the repeatable
+dogfood bundle shape separate from network posting and argument parsing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_DOGFOOD_REPORTS: tuple[tuple[str, str], ...] = (
+    ("docs/reviewer-value-report.md", "value-report"),
+    ("docs/lane-promotion-policy.md", "lane-policy"),
+    (".code-mower/reviewer-value-report.md", "value-report"),
+    (".code-mower/reviewer-metrics.json", "reviewer-metrics"),
+)
+
+
+@dataclass(frozen=True)
+class DogfoodPlan:
+    repo_slug: str
+    team_id: str
+    install_id: str
+    source: str
+    report_count: int
+    extra_event_count: int
+
+
+def default_dogfood_reports(repo_path: Path) -> list[tuple[Path, str]]:
+    seen: set[Path] = set()
+    reports: list[tuple[Path, str]] = []
+    for relative_path, kind in DEFAULT_DOGFOOD_REPORTS:
+        path = repo_path / relative_path
+        if path in seen or not path.is_file():
+            continue
+        seen.add(path)
+        reports.append((path, kind))
+    return reports
+
+
+def build_dogfood_plan(
+    *,
+    repo_slug: str,
+    team_id: str,
+    install_id: str,
+    source: str,
+    reports: list[tuple[Path, str]],
+    events: list[dict[str, Any]],
+) -> DogfoodPlan:
+    return DogfoodPlan(
+        repo_slug=repo_slug,
+        team_id=team_id,
+        install_id=install_id,
+        source=source,
+        report_count=len(reports),
+        extra_event_count=len(events),
+    )
+
+
+def build_dogfood_dry_run_preview(
+    *,
+    endpoint: str,
+    payload: dict[str, Any],
+) -> dict[str, Any]:
+    return {
+        "mode": "cloud-upload-dry-run",
+        "endpoint": endpoint,
+        "would_upload": False,
+        "requires_yes": True,
+        "upload_mode": payload["upload_mode"],
+        "report_count": len(payload["reports"]),
+        "event_count": len(payload["events"]),
+        "privacy_mode": payload["privacy_mode"],
+        "excluded_content": payload["excluded_content"],
+    }