proxmox/scripts/verify/build-external-submission-packet-index.py

#!/usr/bin/env python3
"""Build an index of external submission packets and current probe artifacts."""

from __future__ import annotations

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


ROOT = Path(__file__).resolve().parents[2]
OUT_JSON = ROOT / "reports/status/external-submission-packet-index-latest.json"
OUT_MD = ROOT / "docs/04-configuration/EXTERNAL_SUBMISSION_PACKET_INDEX.md"

PACKETS: list[dict[str, Any]] = [
    {
        "provider": "Etherscan",
        "status": "repo_ready_external_acceptance_pending",
        "primaryPacket": "docs/04-configuration/etherscan/CWUSDC_MAINNET_ETHERSCAN_PROFILE_PACKET.md",
        "supporting": [
            "docs/04-configuration/etherscan/CWUSDC_ETHERSCAN_E2E_RECOMMENDATIONS.md",
            "docs/04-configuration/etherscan/CWUSDC_ETHERSCAN_VALUE_EXECUTION_PLAN.md",
            "reports/status/cwusdc-etherscan-value-dossier-latest.json",
        ],
        "nextRepoAction": "Refresh dossier and capture post-submit response evidence.",
    },
    {
        "provider": "CoinGecko",
        "status": "repo_ready_external_price_entry_missing",
        "primaryPacket": "docs/04-configuration/coingecko/CWUSDC_MAINNET_TRACKER_SUBMISSION_PACKET.md",
        "supporting": [
            "docs/04-configuration/coingecko/CWUSDC_MAINNET_EXTERNAL_SUBMISSION_CHECKLIST.md",
            "docs/04-configuration/coingecko/submissions/cwusdc-coingecko-listing-request-20260509.json",
            "reports/status/cwusdc-external-trackers-live-latest.json",
        ],
        "nextRepoAction": "Keep token-price API blocker visible and attach current supply/liquidity caveats.",
    },
    {
        "provider": "CoinMarketCap",
        "status": "dex_page_visible_full_value_acceptance_pending",
        "primaryPacket": "docs/04-configuration/coingecko/CWUSDC_MAINNET_TRACKER_SUBMISSION_PACKET.md",
        "supporting": [
            "reports/status/token-aggregation-cmc-report-chain1-latest.json",
            "reports/status/cmc-provider-report-sanity-latest.json",
            "reports/status/cmc-top10-ecosystem-coverage-latest.json",
        ],
        "nextRepoAction": "Use CMC sanity report to avoid overclaiming liquidity or quote-asset identity.",
    },
    {
        "provider": "DexScreener",
        "status": "api_not_indexing_pairs",
        "primaryPacket": "docs/04-configuration/dexscreener/CWUSDC_DEXSCREENER_INDEXING_AND_PROFILE_PACKET_20260509.md",
        "supporting": [
            "reports/status/cwusdc-external-trackers-live-latest.json",
            "reports/status/cwusdc-provider-handoff-latest.md",
        ],
        "nextRepoAction": "Keep pair/profile request evidence updated after fresh public swap/liquidity events.",
    },
    {
        "provider": "GeckoTerminal",
        "status": "pool_api_visible_low_reserve",
        "primaryPacket": "docs/04-configuration/coingecko/CWUSDC_MAINNET_TRACKER_SUBMISSION_PACKET.md",
        "supporting": [
            "reports/status/cwusdc-external-trackers-live-latest.json",
            "reports/status/cmc-provider-report-sanity-latest.json",
        ],
        "nextRepoAction": "Track reserve USD and 24h volume separately from listing acceptance.",
    },
    {
        "provider": "MetaMask",
        "status": "metadata_path_ready_price_provider_external",
        "primaryPacket": "docs/04-configuration/metamask/METAMASK_ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md",
        "supporting": [
            "docs/04-configuration/metamask/METAMASK_EIP747_CONTRACT_METADATA_REFERENCE_PACKET.md",
            "docs/04-configuration/metamask/METAMASK_CWUSDC_API_FEED_SPIDER_WEB_RESEARCH.md",
            "reports/status/cwusdc-provider-readiness-ci-latest.json",
        ],
        "nextRepoAction": "Keep CAIP-19, EIP-747, logo URL, and external price-provider blockers aligned.",
    },
]


def exists(path: str) -> bool:
    return (ROOT / path).exists()


def table(headers: list[str], rows: list[list[Any]]) -> str:
    def cell(value: Any) -> str:
        if isinstance(value, list):
            value = "<br>".join(str(item) for item in value)
        return str(value).replace("|", "\\|").replace("\n", "<br>")

    return "\n".join(
        [
            f"| {' | '.join(cell(header) for header in headers)} |",
            f"| {' | '.join('---' for _ in headers)} |",
            *[f"| {' | '.join(cell(value) for value in row)} |" for row in rows],
        ]
    )


def main() -> int:
    generated_at = datetime.now(timezone.utc).isoformat()
    packets = []
    for packet in PACKETS:
        row = dict(packet)
        row["primaryExists"] = exists(row["primaryPacket"])
        row["supportingExists"] = [{"path": path, "exists": exists(path)} for path in row["supporting"]]
        row["allArtifactsPresent"] = row["primaryExists"] and all(item["exists"] for item in row["supportingExists"])
        packets.append(row)
    payload = {
        "schema": "external-submission-packet-index/v1",
        "generatedAt": generated_at,
        "summary": {
            "providerCount": len(packets),
            "allArtifactsPresent": all(row["allArtifactsPresent"] for row in packets),
            "missingArtifactCount": sum(1 for row in packets if not row["allArtifactsPresent"]),
        },
        "packets": packets,
    }
    OUT_JSON.parent.mkdir(parents=True, exist_ok=True)
    OUT_JSON.write_text(json.dumps(payload, indent=2) + "\n")

    lines = [
        "# External Submission Packet Index",
        "",
        f"- Generated: `{generated_at}`",
        f"- All artifacts present: `{payload['summary']['allArtifactsPresent']}`",
        "",
        table(
            ["Provider", "Status", "Primary packet", "Supporting artifacts", "Next repo action"],
            [
                [
                    row["provider"],
                    row["status"],
                    f"`{row['primaryPacket']}` ({row['primaryExists']})",
                    [f"`{item['path']}` ({item['exists']})" for item in row["supportingExists"]],
                    row["nextRepoAction"],
                ]
                for row in packets
            ],
        ),
        "",
        "## Boundary",
        "",
        "This index tracks repo-side evidence availability only. Provider submission, review, acceptance, and price propagation remain external states.",
    ]
    OUT_MD.parent.mkdir(parents=True, exist_ok=True)
    OUT_MD.write_text("\n".join(lines) + "\n")
    print(f"Wrote {OUT_JSON.relative_to(ROOT)}")
    print(f"Wrote {OUT_MD.relative_to(ROOT)}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())