feat: contesto data-explorer — temi, gap analysis, deploy status (#35)

* feat: consuma themes.json da data-explorer per context arricchito

ACB legge catalog/themes.json (contratto gia' pubblico su data-explorer)
e arricchisce tutti e 3 gli output:

- session_bootstrap.md: nuova sezione EXPLORER con temi, dataset pubblicati,
  e gap analysis (clean_ready non su explorer)
- workspace_triage.json: nuovo campo 'explorer' con themes, published_count,
  clean_ready_not_published
- topic_index.json: nuova sezione 'explorer_themes'

Contratto: data-explorer/catalog/themes.json formalizzato come upstream
artifact. Nessuna modifica a data-explorer.

Test: 68/68 passati. Build locale verificato.

* feat: aggiungi deploy status data-explorer a context

- GitHubCollector.get_latest_workflow_run() nuova API generica
- DataExplorerFetcher.fetch_deploy_status() via GitHub Actions API
- workspace_triage.json: explorer.last_deploy con run_id, conclusion, date
- session_bootstrap.md: riga deploy con icona ✅/❌ e data

Operativo, non strutturale — se API fallisce, last_deploy = null

* fix: filtra workflow per nome (deploy.yml) in get_latest_workflow_run

Aggiunto parametro workflow_id opzionale — quando fornito usa
l'endpoint /actions/workflows/{workflow_id}/runs invece del
generico /actions/runs, evitando ambiguità con altri workflow
che condividono lo stesso evento (push).

DataExplorerFetcher ora passa workflow_id='deploy.yml'.

Author: Gabrymi93

src/agent_context_builder/github.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Optional
+from typing import Any, Optional
 
 from lab_connectors.http import HttpClient
 
@@ -187,6 +187,63 @@ def get_repos_info(self, repos: list[str]) -> dict[str, RepoInfo]:
                 self.fetch_errors[f"{repo}:info"] = str(exc)
         return result_map
 
+    def get_latest_workflow_run(
+        self,
+        repo: str,
+        event: str = "push",
+        status: str = "completed",
+        workflow_id: str | None = None,
+    ) -> dict[str, Any] | None:
+        """Fetch the latest workflow run for a repo.
+
+        If workflow_id is provided, uses the workflow-specific endpoint
+        (e.g. ``deploy.yml``) to avoid ambiguity when multiple workflows
+        trigger on the same event.
+
+        Args:
+            repo: Repository name (under self.org)
+            event: Event type filter (e.g. push, workflow_dispatch)
+            status: Status filter (e.g. completed, success)
+            workflow_id: Workflow filename (e.g. ``deploy.yml``) for
+                         precise targeting. Optional.
+
+        Returns:
+            Dict with run_id, name, status, conclusion, started_at, completed_at, html_url,
+            or None if no runs found or on error.
+        """
+        if workflow_id:
+            url = (
+                f"{self.base_url}/repos/{self.org}/{repo}"
+                f"/actions/workflows/{workflow_id}/runs"
+            )
+        else:
+            url = f"{self.base_url}/repos/{self.org}/{repo}/actions/runs"
+        params = {
+            "event": event,
+            "status": status,
+            "per_page": 1,
+        }
+        try:
+            result = self._http.get(url, params=params, headers=self._headers())
+            self._raise_on_bad_status(result, url)
+            data = result.response.json()  # type: ignore[union-attr]
+            runs = data.get("workflow_runs", [])
+            if not runs:
+                return None
+            run = runs[0]
+            return {
+                "run_id": run.get("id"),
+                "name": run.get("name", ""),
+                "status": run.get("status", ""),
+                "conclusion": run.get("conclusion"),
+                "started_at": run.get("run_started_at", ""),
+                "completed_at": run.get("updated_at", ""),
+                "html_url": run.get("html_url", ""),
+            }
+        except Exception as exc:
+            self.fetch_errors[f"{repo}:workflow_runs"] = str(exc)
+            return None
+
     def _get_repo_issues(self, repo: str, state: str = "open") -> list[Issue]:
         """Get issues for a specific repo (excluding pull requests).
 

src/agent_context_builder/render.py

@@ -9,9 +9,11 @@
 from .discussions import DiscussionCollector
 from .github import GitHubCollector, PR
 from .git_local import GitLocalCollector, GitState
+from .sources.de import DataExplorerFetcher
 from .sources.di import DatasetIncubatorFetcher
 from .sources.so import SourceObservatoryFetcher
 from .signals import (
+    ExplorerTheme,
     RadarSummary,
     SourceObservatorySignals,
 )
@@ -44,6 +46,7 @@ def __init__(
         self.fixed_timestamp = fixed_timestamp or datetime.now().isoformat()
         self._so_fetcher = SourceObservatoryFetcher(self.github_collector)
         self._di_fetcher = DatasetIncubatorFetcher(self.github_collector)
+        self._de_fetcher = DataExplorerFetcher(self.github_collector)
 
     def render_session_bootstrap(self) -> str:
         """Render session_bootstrap.md.
@@ -137,6 +140,51 @@ def render_session_bootstrap(self) -> str:
             lines.append("**Dataset Catalog**: unavailable")
         lines.append("")
 
+        # ── EXPLORER ──────────────────────────────────────────────────────
+        explorer_themes = self._fetch_explorer_themes()
+        if explorer_themes is not None:
+            lines.append("## 🗂 EXPLORER")
+            lines.append("")
+
+            # Count themed datasets
+            themed_slugs: set[str] = set()
+            for t in explorer_themes:
+                themed_slugs.update(t.datasets)
+
+            # Gap analysis
+            catalog = self._fetch_di_clean_catalog()
+            clean_ready_slugs: set[str] = set()
+            if catalog is not None:
+                for ds in catalog.clean_ready:
+                    clean_ready_slugs.add(ds.slug)
+            gap = sorted(clean_ready_slugs - themed_slugs)
+
+            lines.append(
+                f"**Pubblicati**: {len(themed_slugs)} dataset · "
+                f"{len(explorer_themes)} temi"
+            )
+            for t in explorer_themes:
+                lines.append(f"  · **{t.name}**: {len(t.datasets)} dataset")
+            if gap:
+                lines.append(f"  ⚠ {len(gap)} dataset clean_ready non ancora su explorer:")
+                for slug in gap[:5]:
+                    lines.append(f"    · {slug}")
+                if len(gap) > 5:
+                    lines.append(f"    · ... e altri {len(gap) - 5}")
+
+            # Deploy status
+            last_deploy = self._de_fetcher.fetch_deploy_status()
+            if last_deploy is not None:
+                conclusion = last_deploy.get("conclusion", "unknown")
+                icon = "✅" if conclusion == "success" else "❌"
+                completed = (last_deploy.get("completed_at", "")[:10]
+                             if last_deploy.get("completed_at") else "?")
+                lines.append(f"  **Deploy**: {icon} {conclusion} ({completed})")
+            else:
+                lines.append(f"  **Deploy**: dati non disponibili")
+
+            lines.append("")
+
         # ── OPEN ─────────────────────────────────────────────────────────
         prs = self.github_collector.get_prs(self.config.repos)
         github_errors = self.github_collector.fetch_errors
@@ -225,10 +273,14 @@ def render_workspace_triage(self) -> dict[str, Any]:
             self.fixed_timestamp,
             so_fetcher=self._so_fetcher,
             di_fetcher=self._di_fetcher,
+            de_fetcher=self._de_fetcher,
         )
 
 
 
+    def _fetch_explorer_themes(self) -> list[ExplorerTheme] | None:
+        return self._de_fetcher.fetch_themes()
+
     def _fetch_di_pipeline_signals(self) -> RepoSignals | None:
         return self._di_fetcher.fetch_pipeline_signals()
 
@@ -329,11 +381,25 @@ def render_topic_index(self) -> dict[str, Any]:
                 "next": topic.next,
             }
 
+        # Explorer themes from data-explorer
+        explorer_themes_list: list[dict[str, Any]] = []
+        explorer_themes = self._fetch_explorer_themes()
+        if explorer_themes is not None:
+            explorer_themes_list = [
+                {
+                    "slug": t.slug,
+                    "name": t.name,
+                    "datasets": t.datasets,
+                }
+                for t in explorer_themes
+            ]
+
         return {
             "schema_version": 2,
             "generated_at": self.fixed_timestamp,
             "repos": repos_section,
             "datasets_by_source": datasets_by_source,
             "candidates_by_source": candidates_by_source,
             "operational_topics": operational_topics,
+            "explorer_themes": explorer_themes_list,
         }

src/agent_context_builder/signals.py

@@ -320,6 +320,45 @@ def unhealthy(self) -> list[RadarSource]:
         return [s for s in self.sources if s.status in ("YELLOW", "RED")]
 
 
+@dataclass
+class ExplorerTheme:
+    """Single theme entry from data-explorer catalog/themes.json."""
+
+    slug: str
+    name: str
+    datasets: list[str]
+
+
+def parse_explorer_themes(raw: str) -> list[ExplorerTheme]:
+    """Parse data-explorer catalog/themes.json into ExplorerTheme instances.
+
+    Args:
+        raw: Raw JSON content of themes.json
+
+    Returns:
+        List of ExplorerTheme instances
+
+    Raises:
+        ValueError: If the JSON is invalid
+    """
+    try:
+        data: list[dict[str, Any]] = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid JSON: {exc}") from exc
+
+    if not isinstance(data, list):
+        raise ValueError("Expected JSON array at root")
+
+    return [
+        ExplorerTheme(
+            slug=item.get("slug", ""),
+            name=item.get("name", ""),
+            datasets=item.get("datasets", []),
+        )
+        for item in data
+    ]
+
+
 def parse_radar_summary(raw: str) -> RadarSummary:
     try:
         data: dict[str, Any] = json.loads(raw)

src/agent_context_builder/sources/de.py

@@ -0,0 +1,76 @@
+"""Data-explorer fetch and parse helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from ..github import GitHubCollector
+from ..signals import ExplorerTheme, parse_explorer_themes
+
+
+@dataclass
+class DataExplorerData:
+    """Cached data-explorer artifact bundle."""
+
+    themes: list[ExplorerTheme] | None
+    last_deploy: dict[str, Any] | None
+
+
+class DataExplorerFetcher:
+    """Fetch data-explorer artifacts from GitHub raw URLs + API.
+
+    Consumes:
+      - catalog/themes.json (editorial theme assignments)
+      - GitHub Actions API (deploy status, operativo)
+    """
+
+    def __init__(self, collector: GitHubCollector):
+        self.collector = collector
+        self._themes_cache: list[ExplorerTheme] | None | object = _UNSET
+        self._deploy_cache: dict[str, Any] | None | object = _UNSET
+
+    def fetch(self) -> DataExplorerData:
+        """Fetch all data-explorer artifacts."""
+        return DataExplorerData(
+            themes=self.fetch_themes(),
+            last_deploy=self.fetch_deploy_status(),
+        )
+
+    def fetch_themes(self) -> list[ExplorerTheme] | None:
+        """Fetch and parse catalog/themes.json from data-explorer.
+
+        Returns None if the artifact is unavailable or malformed.
+        """
+        if self._themes_cache is not _UNSET:
+            return self._themes_cache  # type: ignore[return-value]
+        raw = self.collector.get_raw_file("data-explorer", "catalog/themes.json")
+        if raw is None:
+            self._themes_cache = None
+            return None
+        try:
+            result = parse_explorer_themes(raw)
+        except ValueError as exc:
+            self.collector.fetch_errors["data-explorer:themes"] = str(exc)
+            result = None
+        self._themes_cache = result
+        return result
+
+    def fetch_deploy_status(self) -> dict[str, Any] | None:
+        """Fetch latest deploy workflow run for data-explorer.
+
+        Returns a dict with run_id, name, status, conclusion, started_at,
+        completed_at, html_url — or None if unavailable.
+        """
+        if self._deploy_cache is not _UNSET:
+            return self._deploy_cache  # type: ignore[return-value]
+        result = self.collector.get_latest_workflow_run("data-explorer", workflow_id="deploy.yml")
+        self._deploy_cache = result
+        return result
+
+
+class _Unset:
+    pass
+
+
+_UNSET = _Unset()