scripts/devpost_submission_preview.py

#!/usr/bin/env python3
"""Build a one-page, claim-safe Devpost preview for judges and final review."""

from __future__ import annotations

import argparse
from datetime import datetime, timezone
import json
from pathlib import Path
from typing import Any


ROOT = Path(__file__).resolve().parents[1]
DEFAULT_JSON = ROOT / "docs" / "assets" / "devpost-submission-preview.json"
DEFAULT_MD = ROOT / "docs" / "assets" / "devpost-submission-preview.md"
SCHEMA = "proofframe.devpost_submission_preview.v1"

SOURCE_SPECS = {
    "packet": ("docs/assets/devpost-submission-packet.json", "proofframe.devpost_packet.v1"),
    "form_kit": ("docs/assets/devpost-form-kit.json", "proofframe.devpost_form_kit.v1"),
    "judge_brief": ("docs/assets/judge-brief.json", "proofframe.judge_brief.v1"),
    "judge_crosswalk": ("docs/assets/judge-crosswalk.json", "proofframe.judge_crosswalk.v1"),
    "public_screenshot": (
        "docs/assets/public-demo-screenshot-report.json",
        "proofframe.public_demo_screenshot.v1",
    ),
    "public_space_sync": (
        "docs/assets/public-space-sync-report.json",
        "proofframe.public_space_sync.v1",
    ),
    "final_control": (
        "docs/assets/final-submission-control.json",
        "proofframe.final_submission_control.v1",
    ),
    "submit_checklist": (
        "docs/assets/devpost-submission-checklist.json",
        "proofframe.devpost_submission_checklist.v1",
    ),
    "submission_audit": (
        "docs/assets/submission-audit-report.json",
        "proofframe.submission_audit.v1",
    ),
    "secret_scan": ("docs/assets/secret-scan-report.json", "proofframe.secret_scan.v1"),
}

FINAL_BLOCKER_LABELS = {
    "b2_live_proof": "live Backblaze B2 proof",
    "genblaze_live_proof": "live Genblaze proof",
    "public_video": "final public video",
    "public_video_check": "public video URL check",
    "final_secret_scan": "final secret scan task completion",
    "final_submission_audit": "strict final submission audit",
    "devpost_submitted": "Devpost submission receipt",
}


def utc_now() -> str:
    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")


def load_json(path: Path) -> dict[str, Any] | None:
    try:
        data = json.loads(path.read_text(encoding="utf-8"))
    except (FileNotFoundError, json.JSONDecodeError):
        return None
    return data if isinstance(data, dict) else None


def dict_field(value: dict[str, Any] | None, key: str) -> dict[str, Any]:
    if not value:
        return {}
    field = value.get(key)
    return field if isinstance(field, dict) else {}


def list_field(value: dict[str, Any] | None, key: str) -> list[Any]:
    if not value:
        return []
    field = value.get(key)
    return field if isinstance(field, list) else []


def source_record(root: Path, source_id: str, relative_path: str, expected_schema: str) -> dict[str, Any]:
    data = load_json(root / relative_path)
    return {
        "id": source_id,
        "path": relative_path,
        "present": data is not None,
        "schema": data.get("schema") if data else None,
        "schema_ok": bool(data and data.get("schema") == expected_schema),
        "mode": data.get("mode") if data else None,
        "ok": data.get("ok") if data else None,
    }


def source_status(root: Path) -> dict[str, dict[str, Any]]:
    return {
        source_id: source_record(root, source_id, relative_path, expected_schema)
        for source_id, (relative_path, expected_schema) in SOURCE_SPECS.items()
    }


def text_list(items: list[Any]) -> list[str]:
    return [str(item).strip() for item in items if str(item).strip()]


def screenshot_ready(report: dict[str, Any] | None) -> bool:
    markers = dict_field(report, "markers")
    screenshot = dict_field(report, "screenshot")
    return bool(
        report
        and report.get("schema") == "proofframe.public_demo_screenshot.v1"
        and report.get("ok") is True
        and report.get("safe_to_commit") is True
        and markers.get("visible_ok") is True
        and markers.get("html_ok") is True
        and screenshot.get("path") == "docs/assets/proofframe-hf-public-smoke.png"
        and (screenshot.get("bytes") or 0) >= 100_000
        and (screenshot.get("width") or 0) >= 1200
        and (screenshot.get("height") or 0) >= 900
    )


def public_space_ready(report: dict[str, Any] | None) -> bool:
    observed = dict_field(report, "observed")
    screenshot = dict_field(observed, "public_demo_screenshot")
    return bool(
        report
        and report.get("schema") == "proofframe.public_space_sync.v1"
        and report.get("ok") is True
        and report.get("mode") == "public_space_synced"
        and screenshot.get("ok") is True
        and screenshot.get("visible_ok") is True
        and screenshot.get("html_ok") is True
    )


def final_blockers(control: dict[str, Any] | None) -> list[dict[str, Any]]:
    blockers = []
    for item in list_field(control, "blocking_items"):
        if not isinstance(item, dict):
            continue
        blocker_id = str(item.get("id") or "")
        blockers.append(
            {
                "id": blocker_id,
                "label": FINAL_BLOCKER_LABELS.get(blocker_id, str(item.get("label") or blocker_id)),
                "detail": str(item.get("detail") or ""),
                "evidence": str(item.get("evidence") or ""),
            }
        )
    return blockers


def field_rollup(form_kit: dict[str, Any] | None) -> dict[str, Any]:
    fields = [field for field in list_field(form_kit, "fields") if isinstance(field, dict)]
    final_pending = [
        {"id": field.get("id"), "label": field.get("label")}
        for field in fields
        if field.get("ok_for_final") is not True
    ]
    return {
        "field_count": len(fields),
        "mock_ready": bool(form_kit and form_kit.get("mock_form_ready") is True),
        "final_ready": bool(form_kit and form_kit.get("final_form_ready") is True),
        "public_video_ready": bool(form_kit and form_kit.get("public_video_ready") is True),
        "final_pending_fields": final_pending,
    }


def criteria_rollup(crosswalk: dict[str, Any] | None) -> dict[str, Any]:
    rows = [row for row in list_field(crosswalk, "rows") if isinstance(row, dict)]
    official_criteria = [
        str(item.get("name"))
        for item in list_field(crosswalk, "official_criteria")
        if isinstance(item, dict) and item.get("present") is True
    ]
    return {
        "mode": crosswalk.get("mode") if crosswalk else None,
        "safe_to_submit": crosswalk.get("safe_to_submit") if crosswalk else None,
        "official_criteria": official_criteria,
        "row_count": len(rows),
    }


def build_preview(root: Path = ROOT) -> dict[str, Any]:
    root = root.resolve()
    packet = load_json(root / "docs/assets/devpost-submission-packet.json")
    form_kit = load_json(root / "docs/assets/devpost-form-kit.json")
    judge_brief = load_json(root / "docs/assets/judge-brief.json")
    crosswalk = load_json(root / "docs/assets/judge-crosswalk.json")
    public_screenshot = load_json(root / "docs/assets/public-demo-screenshot-report.json")
    public_space = load_json(root / "docs/assets/public-space-sync-report.json")
    final_control = load_json(root / "docs/assets/final-submission-control.json")
    submit_checklist = load_json(root / "docs/assets/devpost-submission-checklist.json")
    submission_audit = load_json(root / "docs/assets/submission-audit-report.json")
    secret_scan = load_json(root / "docs/assets/secret-scan-report.json")

    sources = source_status(root)
    source_schemas_ok = all(source["schema_ok"] for source in sources.values())
    screenshot_ok = screenshot_ready(public_screenshot)
    public_space_ok = public_space_ready(public_space)
    form = field_rollup(form_kit)
    blockers = final_blockers(final_control)
    safe_to_share = bool(
        source_schemas_ok
        and screenshot_ok
        and public_space_ok
        and form["mock_ready"]
        and secret_scan
        and secret_scan.get("ok") is True
        and packet
        and packet.get("mode") in {"pre_live_safe", "post_live_verified"}
    )
    safe_to_submit = bool(
        safe_to_share
        and packet
        and packet.get("mode") == "post_live_verified"
        and form["final_ready"]
        and final_control
        and final_control.get("safe_to_submit") is True
        and submit_checklist
        and submit_checklist.get("safe_to_submit") is True
        and submission_audit
        and submission_audit.get("ok") is True
        and not blockers
    )
    mode = "final_preview_ready" if safe_to_submit else "pre_live_preview_ready" if safe_to_share else "preview_blocked"

    links = dict_field(judge_brief, "links")
    project = {
        "name": packet.get("project_name") if packet else "ProofFrame",
        "tagline": packet.get("tagline") if packet else None,
        "one_liner": packet.get("one_liner") if packet else None,
        "repository_url": packet.get("repository_url") if packet else links.get("repository"),
        "demo_url": packet.get("demo_url") if packet else links.get("public_demo"),
        "video_url": packet.get("video_url") if packet else links.get("devpost_video"),
    }
    return {
        "schema": SCHEMA,
        "created_at": utc_now(),
        "mode": mode,
        "ok": safe_to_share,
        "safe_to_share": safe_to_share,
        "safe_to_submit": safe_to_submit,
        "project": project,
        "copy_blocks": {
            "thirty_second_pitch": judge_brief.get("judge_opening_30s") if judge_brief else "",
            "short_description": packet.get("short_description") if packet else "",
            "backblaze_b2_usage": packet.get("b2_usage") if packet else "",
            "genblaze_usage": packet.get("genblaze_usage") if packet else "",
            "accomplishments": text_list(packet.get("accomplishments", []) if packet else []),
            "whats_next": text_list(packet.get("whats_next", []) if packet else []),
            "judge_note": (
                "Use this preview as a copy/reference pack. It is not final-submittable until "
                "safe_to_submit becomes true."
            ),
        },
        "submission_readiness": {
            "packet_mode": packet.get("mode") if packet else None,
            "form_mode": form_kit.get("mode") if form_kit else None,
            "final_control_mode": final_control.get("mode") if final_control else None,
            "submit_checklist_mode": submit_checklist.get("mode") if submit_checklist else None,
            "submission_audit_mode": submission_audit.get("mode") if submission_audit else None,
            "secret_scan_mode": secret_scan.get("mode") if secret_scan else None,
            "public_space_mode": public_space.get("mode") if public_space else None,
            "public_screenshot_mode": public_screenshot.get("mode") if public_screenshot else None,
            "final_blockers": blockers,
        },
        "field_rollup": form,
        "criteria_rollup": criteria_rollup(crosswalk),
        "evidence_links": {
            "public_demo": project["demo_url"],
            "repository": project["repository_url"],
            "public_screenshot": "docs/assets/proofframe-hf-public-smoke.png",
            "screenshot_report": "docs/assets/public-demo-screenshot-report.json",
            "public_space_sync": "docs/assets/public-space-sync-report.json",
            "judge_brief": "docs/assets/judge-brief.json",
            "judge_crosswalk": "docs/assets/judge-crosswalk.json",
            "form_kit": "docs/assets/devpost-form-kit.json",
            "final_control": "docs/assets/final-submission-control.json",
            "submission_bundle": "docs/assets/submission-bundle-manifest.json",
        },
        "claim_boundary": [
            "Public demo evidence proves only the credential-free local/mock judge flow.",
            "Do not claim completed live Backblaze B2 storage until T020 has sanitized live evidence.",
            "Do not claim completed live Genblaze generation until T021 has sanitized live evidence.",
            "Do not submit this packet as final until safe_to_submit is true.",
        ],
        "source_status": sources,
        "next_actions": next_actions(
            safe_to_submit=safe_to_submit,
            blockers=blockers,
            form=form,
            public_space_ok=public_space_ok,
            screenshot_ok=screenshot_ok,
        ),
    }


def next_actions(
    *,
    safe_to_submit: bool,
    blockers: list[dict[str, Any]],
    form: dict[str, Any],
    public_space_ok: bool,
    screenshot_ok: bool,
) -> list[str]:
    if safe_to_submit:
        return ["Use this preview to fill Devpost and archive the submission receipt."]
    actions: list[str] = []
    if not public_space_ok:
        actions.append("Refresh the public Hugging Face Space and rerun public_space_sync.")
    if not screenshot_ok:
        actions.append("Regenerate the public judge-mode screenshot report.")
    if form["final_pending_fields"]:
        labels = ", ".join(str(item["label"]) for item in form["final_pending_fields"][:4])
        actions.append(f"Finalize Devpost fields: {labels}.")
    for blocker in blockers:
        actions.append(f"Resolve final blocker: {blocker['label']}.")
    actions.append("Rerun secret scan, strict final audit, and final submission control before Devpost submit.")
    return list(dict.fromkeys(actions))[:8]


def render_markdown(preview: dict[str, Any]) -> str:
    project = preview["project"]
    readiness = preview["submission_readiness"]
    lines = [
        "# ProofFrame Devpost Submission Preview",
        "",
        f"Mode: `{preview['mode']}`",
        f"Safe to share: `{str(preview['safe_to_share']).lower()}`",
        f"Safe to submit: `{str(preview['safe_to_submit']).lower()}`",
        "",
        "## Project",
        "",
        f"- Name: {project.get('name')}",
        f"- Tagline: {project.get('tagline')}",
        f"- Repository: {project.get('repository_url')}",
        f"- Demo: {project.get('demo_url')}",
        f"- Video: {project.get('video_url')}",
        "",
        "## Copy Blocks",
        "",
        "### 30-Second Pitch",
        "",
        preview["copy_blocks"]["thirty_second_pitch"],
        "",
        "### Short Description",
        "",
        preview["copy_blocks"]["short_description"],
        "",
        "### Backblaze B2 Usage",
        "",
        preview["copy_blocks"]["backblaze_b2_usage"],
        "",
        "### Genblaze Usage",
        "",
        preview["copy_blocks"]["genblaze_usage"],
        "",
        "## Evidence Links",
        "",
    ]
    for label, value in preview["evidence_links"].items():
        lines.append(f"- `{label}`: {value}")
    lines.extend(["", "## Readiness", ""])
    for key in [
        "packet_mode",
        "form_mode",
        "final_control_mode",
        "submit_checklist_mode",
        "submission_audit_mode",
        "secret_scan_mode",
        "public_space_mode",
        "public_screenshot_mode",
    ]:
        lines.append(f"- `{key}`: `{readiness.get(key)}`")
    lines.extend(["", "## Final Blockers", ""])
    if readiness["final_blockers"]:
        for blocker in readiness["final_blockers"]:
            lines.append(f"- `{blocker['id']}`: {blocker['label']} - {blocker['detail']}")
    else:
        lines.append("- None.")
    lines.extend(["", "## Claim Boundary", ""])
    lines.extend(f"- {item}" for item in preview["claim_boundary"])
    lines.extend(["", "## Next Actions", ""])
    lines.extend(f"- {action}" for action in preview["next_actions"])
    return "\n".join(lines).rstrip() + "\n"


def write_outputs(preview: dict[str, Any], json_path: Path, markdown_path: Path) -> None:
    json_path.parent.mkdir(parents=True, exist_ok=True)
    markdown_path.parent.mkdir(parents=True, exist_ok=True)
    json_path.write_text(json.dumps(preview, indent=2) + "\n", encoding="utf-8")
    markdown_path.write_text(render_markdown(preview), encoding="utf-8")


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description="Build a claim-safe ProofFrame Devpost preview.")
    parser.add_argument("--root", type=Path, default=ROOT)
    parser.add_argument("--json-out", type=Path, default=DEFAULT_JSON)
    parser.add_argument("--markdown-out", type=Path, default=DEFAULT_MD)
    parser.add_argument("--strict-final", action="store_true", help="Fail unless safe_to_submit is true.")
    return parser


def main() -> None:
    args = build_parser().parse_args()
    preview = build_preview(args.root)
    write_outputs(preview, args.json_out, args.markdown_out)
    ok = preview["safe_to_submit"] if args.strict_final else preview["safe_to_share"]
    print(
        json.dumps(
            {
                "ok": ok,
                "mode": preview["mode"],
                "safe_to_share": preview["safe_to_share"],
                "safe_to_submit": preview["safe_to_submit"],
                "json": str(args.json_out),
                "markdown": str(args.markdown_out),
                "next_actions": preview["next_actions"][:4],
            },
            indent=2,
        )
    )
    raise SystemExit(0 if ok else 2)


if __name__ == "__main__":
    main()