feat(digest): add weekly summary generator and Discord dispatcher (fixes #29)

apps/api/src/hackproof/cli.py

@@ -1,7 +1,9 @@
 import argparse
 import asyncio
 import logging
+from pathlib import Path
 
+from hackproof.digest import run_digest_job
 from hackproof.export.jobs import run_export
 from hackproof.github.jobs import run_discover, run_scan
 from hackproof.indexer.sync import run_sync
@@ -23,6 +25,18 @@ def main() -> None:
     )
     commands.add_parser("reconcile", help="link chain activity to repos and build projects")
     commands.add_parser("export", help="write the json and yaml export and its schema")
+
+    digest_parser = commands.add_parser("digest", help="render and post weekly digest")
+    digest_parser.add_argument(
+        "--fixture",
+        type=Path,
+        help="path to JSON fixture containing previous and current run snapshots",
+    )
+    digest_parser.add_argument(
+        "--webhook",
+        help="discord webhook url (defaults to DISCORD_WEBHOOK_URL env)",
+    )
+
     args = parser.parse_args()
 
     logging.basicConfig(level=logging.INFO, format="%(asctime)s %(message)s")
@@ -38,3 +52,5 @@ def main() -> None:
             asyncio.run(run_reconcile())
         case "export":
             asyncio.run(run_export())
+        case "digest":
+            asyncio.run(run_digest_job(args.fixture, args.webhook))

apps/api/src/hackproof/config.py

@@ -31,6 +31,10 @@ class Settings(BaseSettings):
     github_tokens: Annotated[list[str], NoDecode] = Field(
         default_factory=list, validation_alias="HACKPROOF_GITHUB_TOKEN"
     )
+    discord_webhook_url: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("DISCORD_WEBHOOK_URL", "HACKPROOF_DISCORD_WEBHOOK_URL"),
+    )
     cors_origins: list[str] = ["http://localhost:5173"]
 
     @field_validator("github_tokens", mode="before")

apps/api/src/hackproof/digest.py

@@ -0,0 +1,175 @@
+import json
+import logging
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, Field
+
+from hackproof.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+
+def safe_print(text: str) -> None:
+    """Print text safely, replacing unencodable characters if stdout does not support UTF-8."""
+    try:
+        print(text)
+    except UnicodeEncodeError:
+        encoding = sys.stdout.encoding or "utf-8"
+        print(text.encode(encoding, errors="replace").decode(encoding))
+
+
+class Graduation(BaseModel):
+    project_id: str
+    name: str | None = None
+    target: str = "mainnet"
+    details: str | None = None
+
+
+class SCFLink(BaseModel):
+    project_id: str
+    name: str | None = None
+    round: str | None = None
+    award_amount: str | None = None
+
+
+class RunSnapshot(BaseModel):
+    run_id: str | None = None
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    projects_count: int = 0
+    contracts_count: int = 0
+    builders_count: int = 0
+    failed_txs_count: int = 0
+    survival_points: dict[str, int] | None = None
+    graduations: list[Graduation] | None = None
+    scf_links: list[SCFLink] | None = None
+
+
+def format_delta(delta: int) -> str:
+    if delta > 0:
+        return f"+{delta}"
+    return str(delta)
+
+
+def generate_digest(prev: RunSnapshot, curr: RunSnapshot) -> str:
+    """Generate a clean, deterministic markdown digest comparing two weekly runs."""
+    date_str = curr.timestamp.strftime("%Y-%m-%d")
+    delta_projects = curr.projects_count - prev.projects_count
+    delta_contracts = curr.contracts_count - prev.contracts_count
+    delta_builders = curr.builders_count - prev.builders_count
+    delta_failed = curr.failed_txs_count - prev.failed_txs_count
+
+    lines: list[str] = [
+        f"# 🚀 HackProof Weekly Digest ({date_str})",
+        "",
+        "### 📊 Ecosystem Growth",
+        f"- **Projects**: {curr.projects_count} ({format_delta(delta_projects)} this week)",
+        f"- **Contracts**: {curr.contracts_count} ({format_delta(delta_contracts)} this week)",
+        f"- **Builders**: {curr.builders_count} ({format_delta(delta_builders)} this week)",
+        f"- **Failed Txs**: {curr.failed_txs_count} ({format_delta(delta_failed)} this week)",
+    ]
+
+    # Section: Survival Points (skipped if table / data does not exist)
+    if prev.survival_points is not None and curr.survival_points is not None:
+        movers: list[tuple[str, int, int]] = []
+        for pid, curr_pts in curr.survival_points.items():
+            prev_pts = prev.survival_points.get(pid, 0)
+            diff = curr_pts - prev_pts
+            if diff > 0:
+                movers.append((pid, curr_pts, diff))
+
+        movers.sort(key=lambda x: x[2], reverse=True)
+        if movers:
+            lines.append("")
+            lines.append("### ⭐ Top Survival Movers")
+            for pid, curr_pts, diff in movers[:5]:
+                lines.append(f"- **{pid}**: {curr_pts} pts (+{diff} pts)")
+
+    # Section: Graduations (skipped if table / data does not exist)
+    if curr.graduations:
+        lines.append("")
+        lines.append("### 🎓 New Graduations")
+        for g in curr.graduations:
+            label = g.name or g.project_id
+            desc = f" ({g.details})" if g.details else ""
+            lines.append(f"- **{label}**: deployed to {g.target}{desc}")
+
+    # Section: SCF Links (skipped if table / data does not exist)
+    if curr.scf_links:
+        lines.append("")
+        lines.append("### 🏆 SCF Highlights")
+        for scf in curr.scf_links:
+            label = scf.name or scf.project_id
+            round_info = f"[{scf.round}] " if scf.round else ""
+            award = f" - {scf.award_amount}" if scf.award_amount else ""
+            lines.append(f"- **{label}**: {round_info}funded{award}")
+
+    lines.append("")
+    lines.append("---")
+    lines.append("*Track real-time ecosystem activity on [HackProof](https://hackproof.dev)*")
+
+    return "\n".join(lines)
+
+
+async def post_to_discord(markdown: str, webhook_url: str) -> bool:
+    """Post markdown digest content to Discord webhook."""
+    payload = {"content": markdown}
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        resp = await client.post(webhook_url, json=payload)
+        resp.raise_for_status()
+        return True
+
+
+def load_runs_from_fixture(fixture_path: Path) -> tuple[RunSnapshot, RunSnapshot]:
+    with fixture_path.open("r", encoding="utf-8") as f:
+        data: dict[str, Any] = json.load(f)
+
+    prev = RunSnapshot.model_validate(data["previous_run"])
+    curr = RunSnapshot.model_validate(data["current_run"])
+    return prev, curr
+
+
+async def run_digest_job(
+    fixture_path: Path | None = None,
+    webhook_url: str | None = None,
+) -> str:
+    """Execute weekly digest: generate summary and deliver to Discord or stdout."""
+    if fixture_path and fixture_path.exists():
+        prev_run, curr_run = load_runs_from_fixture(fixture_path)
+    else:
+        now = datetime.now(UTC)
+        prev_run = RunSnapshot(
+            run_id="run-baseline-01",
+            timestamp=now,
+            projects_count=120,
+            contracts_count=85,
+            builders_count=78,
+            failed_txs_count=12,
+        )
+        curr_run = RunSnapshot(
+            run_id="run-baseline-02",
+            timestamp=now,
+            projects_count=135,
+            contracts_count=98,
+            builders_count=89,
+            failed_txs_count=15,
+        )
+
+    digest = generate_digest(prev_run, curr_run)
+    dest_webhook = webhook_url or get_settings().discord_webhook_url
+
+    if dest_webhook:
+        try:
+            await post_to_discord(digest, dest_webhook)
+            logger.info("Successfully delivered weekly digest to Discord webhook.")
+        except Exception as e:
+            logger.error("Failed to post weekly digest to Discord: %s", e)
+            safe_print(digest)
+            raise
+    else:
+        safe_print(digest)
+
+    return digest

apps/api/tests/fixtures/weekly_runs.json

@@ -0,0 +1,45 @@
+{
+  "previous_run": {
+    "run_id": "2026-W42",
+    "timestamp": "2026-10-18T12:00:00Z",
+    "projects_count": 50,
+    "contracts_count": 30,
+    "builders_count": 42,
+    "failed_txs_count": 5,
+    "survival_points": {
+      "repo:ethan-r13n/nest": 100,
+      "repo:0xDanomite/alloy-stellar": 80
+    },
+    "graduations": [],
+    "scf_links": []
+  },
+  "current_run": {
+    "run_id": "2026-W43",
+    "timestamp": "2026-10-25T12:00:00Z",
+    "projects_count": 65,
+    "contracts_count": 45,
+    "builders_count": 54,
+    "failed_txs_count": 8,
+    "survival_points": {
+      "repo:ethan-r13n/nest": 140,
+      "repo:0xDanomite/alloy-stellar": 115,
+      "repo:troqpay/private-yield": 60
+    },
+    "graduations": [
+      {
+        "project_id": "repo:ethan-r13n/nest",
+        "name": "Nest",
+        "target": "mainnet",
+        "details": "contract CABC123"
+      }
+    ],
+    "scf_links": [
+      {
+        "project_id": "repo:0xDanomite/alloy-stellar",
+        "name": "Alloy Stellar",
+        "round": "Round 31",
+        "award_amount": "$25,000 USDC"
+      }
+    ]
+  }
+}

apps/api/tests/test_digest.py

@@ -0,0 +1,94 @@
+from datetime import UTC, datetime
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from hackproof.digest import (
+    RunSnapshot,
+    generate_digest,
+    load_runs_from_fixture,
+    post_to_discord,
+    run_digest_job,
+)
+
+
+def test_generate_digest_from_fixture():
+    fixture_path = Path(__file__).parent / "fixtures" / "weekly_runs.json"
+    prev, curr = load_runs_from_fixture(fixture_path)
+
+    digest = generate_digest(prev, curr)
+
+    assert "# 🚀 HackProof Weekly Digest (2026-10-25)" in digest
+    assert "- **Projects**: 65 (+15 this week)" in digest
+    assert "- **Contracts**: 45 (+15 this week)" in digest
+    assert "- **Builders**: 54 (+12 this week)" in digest
+    assert "- **Failed Txs**: 8 (+3 this week)" in digest
+
+    # Check top movers
+    assert "### ⭐ Top Survival Movers" in digest
+    assert "- **repo:troqpay/private-yield**: 60 pts (+60 pts)" in digest
+    assert "- **repo:ethan-r13n/nest**: 140 pts (+40 pts)" in digest
+    assert "- **repo:0xDanomite/alloy-stellar**: 115 pts (+35 pts)" in digest
+
+    # Check graduations
+    assert "### 🎓 New Graduations" in digest
+    assert "- **Nest**: deployed to mainnet (contract CABC123)" in digest
+
+    # Check SCF links
+    assert "### 🏆 SCF Highlights" in digest
+    assert "- **Alloy Stellar**: [Round 31] funded - $25,000 USDC" in digest
+
+
+def test_generate_digest_skips_missing_tables():
+    prev = RunSnapshot(
+        run_id="run-01",
+        timestamp=datetime(2026, 10, 18, 12, 0, tzinfo=UTC),
+        projects_count=10,
+        contracts_count=5,
+        builders_count=8,
+        failed_txs_count=1,
+    )
+    curr = RunSnapshot(
+        run_id="run-02",
+        timestamp=datetime(2026, 10, 25, 12, 0, tzinfo=UTC),
+        projects_count=12,
+        contracts_count=7,
+        builders_count=10,
+        failed_txs_count=1,
+    )
+
+    digest = generate_digest(prev, curr)
+
+    assert "# 🚀 HackProof Weekly Digest (2026-10-25)" in digest
+    assert "- **Projects**: 12 (+2 this week)" in digest
+    assert "- **Contracts**: 7 (+2 this week)" in digest
+    assert "- **Failed Txs**: 1 (0 this week)" in digest
+
+    # Assert non-existent tables are cleanly skipped
+    assert "### ⭐ Top Survival Movers" not in digest
+    assert "### 🎓 New Graduations" not in digest
+    assert "### 🏆 SCF Highlights" not in digest
+
+
+@pytest.mark.asyncio
+async def test_post_to_discord():
+    with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
+        mock_response = MagicMock()
+        mock_response.raise_for_status.return_value = None
+        mock_post.return_value = mock_response
+
+        ok = await post_to_discord("Test content", "https://discord.com/api/webhooks/test/123")
+        assert ok is True
+        mock_post.assert_awaited_once_with(
+            "https://discord.com/api/webhooks/test/123",
+            json={"content": "Test content"},
+        )
+
+
+@pytest.mark.asyncio
+async def test_run_digest_job():
+    fixture_path = Path(__file__).parent / "fixtures" / "weekly_runs.json"
+    digest = await run_digest_job(fixture_path=fixture_path)
+    assert "# 🚀 HackProof Weekly Digest" in digest
+    assert "Projects**: 65" in digest