viva-catalog 0.1.0__tar.gz

viva_catalog-0.1.0/.github/workflows/build-index.yml

@@ -0,0 +1,65 @@
+name: Build ecosystem index
+
+# Rebuilds ecosystem-index.json by harvesting every repo's published workbench
+# dashboard, commits it back to main, and publishes modules.json + the index to
+# gh-pages so any published workbench can fetch them same-origin.
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 6 * * *"   # daily
+  push:
+    branches: [main]
+    paths:
+      - "viva_catalog/modules.json"
+      - "scripts/build_ecosystem_index.py"
+
+permissions:
+  contents: write
+
+concurrency:
+  group: build-index
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install PyYAML (for study/investigation/composite YAML scanning)
+        run: python -m pip install --quiet pyyaml
+
+      - name: Discover repos (viva-marketplace topic) + clone/scan → index
+        env:
+          # discovery queries the org for public repos with the viva-marketplace
+          # topic; the default workflow token authenticates the search API.
+          GITHUB_TOKEN: ${{ github.token }}
+        run: python scripts/build_ecosystem_index.py
+
+      - name: Commit the refreshed registry + index (if changed)
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add viva_catalog/modules.json viva_catalog/ecosystem-index.json
+          if ! git diff --cached --quiet; then
+            git commit -m "chore: refresh registry (topic discovery) + ecosystem-index [skip ci]"
+            git push
+          else
+            echo "registry + index unchanged"
+          fi
+
+      - name: Assemble the public ledger (modules + index)
+        run: |
+          mkdir -p public
+          cp viva_catalog/modules.json public/modules.json
+          cp viva_catalog/ecosystem-index.json public/ecosystem-index.json
+
+      - name: Publish ledger to gh-pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./public
+          keep_files: false

viva_catalog-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,20 @@
+name: release
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch: {}   # manual fallback (tag-push events have been unreliable on this repo)
+permissions:
+  id-token: write   # for PyPI trusted publishing
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: {python-version: "3.11"}
+      - name: Install uv
+        run: pip install uv
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

viva_catalog-0.1.0/.github/workflows/validate.yml

@@ -0,0 +1,20 @@
+name: Validate registry
+
+# PR gate: any change to the repo registry (modules.json) is validated before it
+# can merge. Adding/updating a repo goes through a pull request — see CONTRIBUTING.md.
+on:
+  pull_request:
+    paths:
+      - "viva_catalog/modules.json"
+      - "scripts/validate_modules.py"
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Validate modules.json
+        run: python scripts/validate_modules.py

viva_catalog-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+public/
+.venv/

viva_catalog-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to viva-catalog
+
+viva-catalog is the **ecosystem ledger** for the vivarium / process-bigraph
+workbench. Both files are now **machine-generated** — you don't hand-edit them:
+
+- `viva_catalog/modules.json` — the registry of repos, **discovered from
+  GitHub topics** (see below).
+- `viva_catalog/ecosystem-index.json` — the aggregated artifact index,
+  built by cloning + scanning each discovered repo.
+
+## Publish your repository to the marketplace
+
+**Add the `viva-marketplace` GitHub topic to your repo.** That's the whole step:
+
+```bash
+gh repo edit vivarium-collective/<your-repo> --add-topic viva-marketplace
+```
+
+(Or add it via the repo's GitHub page → About → ⚙ → Topics.) Your repo must be
+**public** and not archived.
+
+The nightly builder (and any manual re-run) then discovers every public,
+non-archived `vivarium-collective` repo carrying the topic, refreshes
+`modules.json` from that set, and **clones your repo and scans its source** — your
+composites (`@composite_generator` / `*.composite.yaml`), `Process`/`Step`
+subclasses, `studies/<slug>/study.yaml`, and
+`investigations/<slug>/investigation.yaml` all appear in `ecosystem-index.json`
+automatically. You never hand-write your artifact list.
+
+To make your artifacts discoverable, follow the usual conventions:
+`@composite_generator(name=…, description=…)` for composites, `Process`/`Step`
+subclasses (with a `description` attribute or docstring) for processes, and the
+`studies/`/`investigations/` YAML for those.
+
+## Update your listing
+
+Your `description` and `tags` come straight from your repo's **GitHub description
+and topics** — edit them on GitHub and the next build picks them up. The artifact
+index refreshes from your repo's source, so just keep your source current.
+
+## Remove your repository
+
+Remove the `viva-marketplace` topic (or archive / make the repo private) — it
+drops out of the registry on the next build:
+
+```bash
+gh repo edit vivarium-collective/<your-repo> --remove-topic viva-marketplace
+```
+
+## Ground rules
+
+- **Membership = the `viva-marketplace` topic on a public, non-archived repo.**
+  No hand-maintained list to drift.
+- Both `modules.json` and `ecosystem-index.json` are generated — don't hand-edit
+  them (changes are overwritten on the next build).
+
+## Rebuild locally
+
+```bash
+pip install pyyaml
+export GITHUB_TOKEN=$(gh auth token)      # discovery authenticates the search API
+python scripts/build_ecosystem_index.py               # discover + clone/scan all
+python scripts/build_ecosystem_index.py --no-discover # use committed modules.json as-is
+python scripts/build_ecosystem_index.py --only viva-biofilm  # just one repo
+```

viva_catalog-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.5
+Name: viva-catalog
+Version: 0.1.0
+Summary: Ecosystem ledger for the vivarium / process-bigraph workbench: the registry of repos + an aggregated artifact index.
+Project-URL: Homepage, https://github.com/vivarium-collective/viva-catalog
+Author: Vivarium Collective
+License: MIT
+Keywords: marketplace,process-bigraph,vivarium,workbench
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# viva-catalog
+
+The **ecosystem ledger** for the [vivarium](https://github.com/vivarium-collective) /
+[process-bigraph](https://github.com/vivarium-collective/process-bigraph) workbench.
+
+It answers two questions for the [vivarium-workbench](https://github.com/vivarium-collective/vivarium-workbench)
+Registry, so a workbench can browse the **whole ecosystem** — not just what's
+installed locally — and offer **Install to use**:
+
+| File | What it is |
+|---|---|
+| [`viva_catalog/modules.json`](viva_catalog/modules.json) | The registry of ecosystem repos — `name`, `source`, `description`, `tags`. **Generated** by discovering every public `vivarium-collective` repo with the `viva-marketplace` GitHub topic. |
+| [`viva_catalog/ecosystem-index.json`](viva_catalog/ecosystem-index.json) | The aggregated **artifact index** — every repo's processes / steps / composites / studies / investigations (name + description + counts). Regenerated by CI. |
+
+Previously the registry lived in `viva_superpowers/catalog/modules.json` (the
+Claude-Code plugin). It moved here so the ledger is owned by a dedicated repo.
+
+**Adding a repo?** Just add the **`viva-marketplace` GitHub topic** to your
+public repo (`gh repo edit vivarium-collective/<repo> --add-topic
+viva-marketplace`) — the nightly builder discovers it, refreshes `modules.json`,
+and scans its source into the index. No PR needed. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## How the index is built
+
+`scripts/build_ecosystem_index.py` reads `modules.json` and, for each repo,
+**shallow-clones it and scans the source** — no published dashboard required:
+
+- **composites** — `@composite_generator(name=…, description=…)` decorators (AST)
+  + any `*.composite.yaml` files
+- **processes / steps** — top-level classes whose base ends in `Process` / `Step`
+  (AST), described by a `description` class attribute or the class docstring
+- **studies** — `**/studies/*/study.yaml` (name + objective/title)
+- **investigations** — `**/investigations/*/investigation.yaml` (name + title)
+
+This gives complete coverage across the ecosystem whether or not a repo publishes
+a workbench dashboard. Repos that can't be cloned are still listed (empty
+artifacts, `cloned: false`).
+
+```bash
+python scripts/build_ecosystem_index.py            # rebuild the index locally
+python scripts/build_ecosystem_index.py --only Viva-munk,pbg-copasi   # subset
+```
+
+Needs `git` + `PyYAML`.
+
+## Consuming the ledger
+
+**Python** (viva-superpowers, vivarium-workbench):
+
+```python
+import viva_catalog
+repos = viva_catalog.load_modules()          # the repo registry
+index = viva_catalog.load_ecosystem_index()  # aggregated artifacts
+```
+
+**Over HTTP** (published to gh-pages, same-origin for any published workbench):
+
+```
+https://vivarium-collective.github.io/viva-catalog/modules.json
+https://vivarium-collective.github.io/viva-catalog/ecosystem-index.json
+```
+
+## CI
+
+[`.github/workflows/build-index.yml`](.github/workflows/build-index.yml) rebuilds
+`ecosystem-index.json` daily (and on `modules.json` changes), commits it to `main`,
+and publishes `modules.json` + the index to `gh-pages`.

viva_catalog-0.1.0/README.md

@@ -0,0 +1,68 @@
+# viva-catalog
+
+The **ecosystem ledger** for the [vivarium](https://github.com/vivarium-collective) /
+[process-bigraph](https://github.com/vivarium-collective/process-bigraph) workbench.
+
+It answers two questions for the [vivarium-workbench](https://github.com/vivarium-collective/vivarium-workbench)
+Registry, so a workbench can browse the **whole ecosystem** — not just what's
+installed locally — and offer **Install to use**:
+
+| File | What it is |
+|---|---|
+| [`viva_catalog/modules.json`](viva_catalog/modules.json) | The registry of ecosystem repos — `name`, `source`, `description`, `tags`. **Generated** by discovering every public `vivarium-collective` repo with the `viva-marketplace` GitHub topic. |
+| [`viva_catalog/ecosystem-index.json`](viva_catalog/ecosystem-index.json) | The aggregated **artifact index** — every repo's processes / steps / composites / studies / investigations (name + description + counts). Regenerated by CI. |
+
+Previously the registry lived in `viva_superpowers/catalog/modules.json` (the
+Claude-Code plugin). It moved here so the ledger is owned by a dedicated repo.
+
+**Adding a repo?** Just add the **`viva-marketplace` GitHub topic** to your
+public repo (`gh repo edit vivarium-collective/<repo> --add-topic
+viva-marketplace`) — the nightly builder discovers it, refreshes `modules.json`,
+and scans its source into the index. No PR needed. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## How the index is built
+
+`scripts/build_ecosystem_index.py` reads `modules.json` and, for each repo,
+**shallow-clones it and scans the source** — no published dashboard required:
+
+- **composites** — `@composite_generator(name=…, description=…)` decorators (AST)
+  + any `*.composite.yaml` files
+- **processes / steps** — top-level classes whose base ends in `Process` / `Step`
+  (AST), described by a `description` class attribute or the class docstring
+- **studies** — `**/studies/*/study.yaml` (name + objective/title)
+- **investigations** — `**/investigations/*/investigation.yaml` (name + title)
+
+This gives complete coverage across the ecosystem whether or not a repo publishes
+a workbench dashboard. Repos that can't be cloned are still listed (empty
+artifacts, `cloned: false`).
+
+```bash
+python scripts/build_ecosystem_index.py            # rebuild the index locally
+python scripts/build_ecosystem_index.py --only Viva-munk,pbg-copasi   # subset
+```
+
+Needs `git` + `PyYAML`.
+
+## Consuming the ledger
+
+**Python** (viva-superpowers, vivarium-workbench):
+
+```python
+import viva_catalog
+repos = viva_catalog.load_modules()          # the repo registry
+index = viva_catalog.load_ecosystem_index()  # aggregated artifacts
+```
+
+**Over HTTP** (published to gh-pages, same-origin for any published workbench):
+
+```
+https://vivarium-collective.github.io/viva-catalog/modules.json
+https://vivarium-collective.github.io/viva-catalog/ecosystem-index.json
+```
+
+## CI
+
+[`.github/workflows/build-index.yml`](.github/workflows/build-index.yml) rebuilds
+`ecosystem-index.json` daily (and on `modules.json` changes), commits it to `main`,
+and publishes `modules.json` + the index to `gh-pages`.

viva_catalog-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "viva-catalog"
+version = "0.1.0"
+description = "Ecosystem ledger for the vivarium / process-bigraph workbench: the registry of repos + an aggregated artifact index."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Vivarium Collective" }]
+keywords = ["vivarium", "process-bigraph", "workbench", "marketplace"]
+
+[project.urls]
+Homepage = "https://github.com/vivarium-collective/viva-catalog"
+
+[tool.hatch.build.targets.wheel]
+packages = ["viva_catalog", "viva_marketplace"]
+
+# Ship the ledger data files inside the wheel so consumers can read them via
+# viva_catalog.load_modules() / load_ecosystem_index().
+[tool.hatch.build.targets.wheel.force-include]
+"viva_catalog/modules.json" = "viva_catalog/modules.json"
+"viva_catalog/ecosystem-index.json" = "viva_catalog/ecosystem-index.json"

viva_catalog-0.1.0/scripts/build_ecosystem_index.py

@@ -0,0 +1,304 @@
+#!/usr/bin/env python3
+"""Build ``viva_catalog/ecosystem-index.json`` from the repo registry.
+
+For every repo in ``modules.json`` we **shallow-clone the repo and scan its
+source** — no published dashboard required. What we extract:
+
+- **composites** — ``@composite_generator(name=…, description=…)`` decorators
+  (AST) plus any ``*.composite.yaml`` files.
+- **processes / steps** — top-level classes whose base ends in ``Process`` /
+  ``Step`` (AST), with the description taken from a ``description`` class
+  attribute or the class docstring.
+- **studies** — ``**/studies/*/study.yaml`` (name + objective/title).
+- **investigations** — ``**/investigations/*/investigation.yaml`` (name + title).
+
+This gives complete coverage across the ecosystem regardless of whether a repo
+publishes a workbench dashboard. Repos that can't be cloned are still listed
+(empty artifacts, ``cloned: false``).
+
+Usage:  python scripts/build_ecosystem_index.py [--out PATH] [--timeout N] [--jobs N]
+Needs: git + PyYAML.
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover
+    yaml = None
+
+ROOT = Path(__file__).resolve().parent.parent
+PKG = ROOT / "viva_catalog"
+
+_PROC_BASE = re.compile(r"(Process|Step)$")
+
+# A repo "publishes to the marketplace" by adding this GitHub topic. Membership
+# is discovered from the org (no hand-maintained list) — see discover_modules.
+MARKETPLACE_TOPIC = "viva-marketplace"
+ORG = "vivarium-collective"
+
+
+def discover_modules(timeout: float = 60.0) -> list[dict]:
+    """Discover the marketplace registry from GitHub: every PUBLIC, non-archived
+    ``vivarium-collective`` repo carrying the ``viva-marketplace`` topic.
+
+    This replaces the hand-maintained ``modules.json`` membership list — a repo
+    joins the marketplace by adding the topic (``gh repo edit --add-topic
+    viva-marketplace``), and the daily index build picks it up automatically.
+    Returns registry entries in the same shape modules.json used
+    (name/source/ref/package/homepage/description/tags), sorted by name.
+    """
+    import urllib.parse
+    import urllib.request
+
+    token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    q = f"org:{ORG} topic:{MARKETPLACE_TOPIC} archived:false"
+    modules: list[dict] = []
+    page = 1
+    while True:
+        url = ("https://api.github.com/search/repositories?q="
+               + urllib.parse.quote(q)
+               + f"&per_page=100&page={page}&sort=full_name&order=asc")
+        headers = {"Accept": "application/vnd.github+json",
+                   "User-Agent": "viva-marketplace-index"}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        req = urllib.request.Request(url, headers=headers)
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            data = json.loads(resp.read())
+        items = data.get("items", []) or []
+        for it in items:
+            modules.append({
+                "name": it["name"],
+                "source": it.get("clone_url") or f"{it['html_url']}.git",
+                "ref": it.get("default_branch") or "main",
+                "package": it["name"].replace("-", "_"),
+                "homepage": it.get("html_url"),
+                "description": it.get("description") or "",
+                "tags": sorted(t for t in (it.get("topics") or [])
+                               if t != MARKETPLACE_TOPIC),
+            })
+        total = int(data.get("total_count") or 0)
+        if len(items) < 100 or len(modules) >= total:
+            break
+        page += 1
+    modules.sort(key=lambda m: m["name"].lower())
+    return modules
+
+
+def _org_repo(source: str) -> tuple[str, str]:
+    s = re.sub(r"\.git$", "", (source or "").strip())
+    s = re.sub(r"^git@github\.com:", "https://github.com/", s)
+    m = re.search(r"github\.com[/:]([^/]+)/([^/]+)/?$", s)
+    return (m.group(1), m.group(2)) if m else ("vivarium-collective", s.rsplit("/", 1)[-1])
+
+
+def _clone(url: str, ref: str, dest: Path, timeout: float) -> bool:
+    """Shallow-clone url@ref into dest. Falls back to the default branch if the
+    ref doesn't exist. Returns True on success."""
+    base = ["git", "clone", "--depth", "1", "--quiet"]
+    for args in ([*base, "--branch", ref, url, str(dest)] if ref else None,
+                 [*base, url, str(dest)]):
+        if args is None:
+            continue
+        try:
+            subprocess.run(args, check=True, capture_output=True, text=True, timeout=timeout)
+            return True
+        except (subprocess.CalledProcessError, subprocess.TimeoutExpired):
+            continue
+    return False
+
+
+def _class_description(node: ast.ClassDef) -> str:
+    # Prefer a `description = "..."` class attribute (pbg convention), else the
+    # first line of the docstring.
+    for stmt in node.body:
+        if (isinstance(stmt, ast.Assign)
+                and any(isinstance(t, ast.Name) and t.id == "description" for t in stmt.targets)
+                and isinstance(stmt.value, ast.Constant) and isinstance(stmt.value.value, str)):
+            return stmt.value.value.strip().splitlines()[0]
+    doc = ast.get_docstring(node) or ""
+    return doc.strip().splitlines()[0] if doc.strip() else ""
+
+
+def _kw_str(call: ast.Call, name: str) -> str:
+    for kw in call.keywords:
+        if kw.arg == name and isinstance(kw.value, ast.Constant) and isinstance(kw.value.value, str):
+            return kw.value.value
+    return ""
+
+
+def _scan_python(root: Path) -> tuple[list, list, list]:
+    composites, processes, steps = [], [], []
+    seen_c, seen_p, seen_s = set(), set(), set()
+    for py in root.rglob("*.py"):
+        # Skip vendored / test / build noise.
+        parts = set(py.parts)
+        if parts & {".git", "tests", "test", "build", "dist", "node_modules", ".venv", "venv"}:
+            continue
+        try:
+            tree = ast.parse(py.read_text(encoding="utf-8", errors="ignore"))
+        except (SyntaxError, ValueError):
+            continue
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ClassDef):
+                for b in node.bases:
+                    bname = b.attr if isinstance(b, ast.Attribute) else (b.id if isinstance(b, ast.Name) else "")
+                    if not _PROC_BASE.search(bname or "") or node.name in ("Process", "Step"):
+                        continue
+                    if bname.endswith("Step"):
+                        if node.name not in seen_s:
+                            seen_s.add(node.name)
+                            steps.append({"name": node.name, "description": _class_description(node)})
+                    else:
+                        if node.name not in seen_p:
+                            seen_p.add(node.name)
+                            processes.append({"name": node.name, "description": _class_description(node)})
+                    break
+            elif isinstance(node, ast.Call):
+                fn = node.func
+                fname = fn.attr if isinstance(fn, ast.Attribute) else (fn.id if isinstance(fn, ast.Name) else "")
+                if fname == "composite_generator":
+                    nm = _kw_str(node, "name")
+                    if nm and nm not in seen_c:
+                        seen_c.add(nm)
+                        composites.append({"name": nm, "description": _kw_str(node, "description")})
+    # *.composite.yaml files
+    for cy in root.rglob("*.composite.yaml"):
+        if ".git" in cy.parts:
+            continue
+        nm = cy.name[: -len(".composite.yaml")]
+        desc = ""
+        if yaml:
+            try:
+                d = yaml.safe_load(cy.read_text(encoding="utf-8")) or {}
+                nm = d.get("name") or nm
+                desc = d.get("description") or ""
+            except Exception:  # noqa: BLE001
+                pass
+        if nm not in seen_c:
+            seen_c.add(nm)
+            composites.append({"name": nm, "description": desc})
+    return composites, processes, steps
+
+
+def _scan_specs(root: Path, kind: str, spec_name: str, desc_keys) -> list:
+    out, seen = [], set()
+    for spec in root.rglob(f"{kind}/*/{spec_name}"):
+        if ".git" in spec.parts:
+            continue
+        name, desc = spec.parent.name, ""
+        if yaml:
+            try:
+                d = yaml.safe_load(spec.read_text(encoding="utf-8")) or {}
+                name = d.get("name") or name
+                for k in desc_keys:
+                    v = d.get(k)
+                    if isinstance(v, dict):
+                        v = v.get("question") or v.get("objective")
+                    if v:
+                        desc = str(v); break
+            except Exception:  # noqa: BLE001
+                pass
+        if name not in seen:
+            seen.add(name)
+            out.append({"name": name, "description": desc})
+    return out
+
+
+def harvest_repo(module: dict, timeout: float) -> dict:
+    name = module.get("name") or module.get("package") or ""
+    source = module.get("source") or module.get("homepage") or ""
+    ref = module.get("ref") or ""
+    org, repo = _org_repo(source)
+    entry = {
+        "name": name, "repo": repo, "source": re.sub(r"\.git$", "", source),
+        "homepage": module.get("homepage") or f"https://github.com/{org}/{repo}",
+        "description": module.get("description") or "", "tags": module.get("tags") or [],
+        "cloned": False, "processes": [], "steps": [], "composites": [],
+        "studies": [], "investigations": [],
+    }
+    with tempfile.TemporaryDirectory() as td:
+        dest = Path(td) / repo
+        if _clone(re.sub(r"^git@github\.com:", "https://github.com/", source) or f"https://github.com/{org}/{repo}.git",
+                  ref, dest, timeout):
+            entry["cloned"] = True
+            comps, procs, steps = _scan_python(dest)
+            entry["composites"] = comps
+            entry["processes"] = procs
+            entry["steps"] = steps
+            entry["studies"] = _scan_specs(dest, "studies", "study.yaml",
+                                           ("objective", "purpose", "title", "description"))
+            entry["investigations"] = _scan_specs(dest, "investigations", "investigation.yaml",
+                                                  ("title", "description", "objective"))
+    entry["counts"] = {k: len(entry[k]) for k in
+                       ("processes", "steps", "composites", "studies", "investigations")}
+    return entry
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--out", default=str(PKG / "ecosystem-index.json"))
+    ap.add_argument("--timeout", type=float, default=120.0)
+    ap.add_argument("--stamp", default=None)
+    ap.add_argument("--only", default=None, help="comma-separated repo names to limit (debug)")
+    ap.add_argument("--no-discover", action="store_true",
+                    help="skip GitHub topic discovery; use the committed modules.json as-is "
+                         "(offline / no token)")
+    args = ap.parse_args(argv)
+
+    # Discover the registry from the `viva-marketplace` GitHub topic and refresh
+    # the committed modules.json (the generated cache). Fall back to the committed
+    # list if discovery fails (offline / API error) so the build never breaks.
+    if not args.no_discover:
+        try:
+            discovered = discover_modules(args.timeout)
+            (PKG / "modules.json").write_text(
+                json.dumps(discovered, indent=2) + "\n", encoding="utf-8")
+            print(f"discovered {len(discovered)} repos via topic "
+                  f"'{MARKETPLACE_TOPIC}' -> refreshed modules.json", file=sys.stderr)
+        except Exception as e:  # noqa: BLE001
+            print(f"WARNING: topic discovery failed ({e}); using committed "
+                  f"modules.json", file=sys.stderr)
+
+    modules = json.loads((PKG / "modules.json").read_text(encoding="utf-8"))
+    if isinstance(modules, dict):
+        modules = modules.get("modules") or []
+    only = set(args.only.split(",")) if args.only else None
+
+    repos = []
+    for m in modules:
+        if not isinstance(m, dict):
+            continue
+        if only and m.get("name") not in only:
+            continue
+        entry = harvest_repo(m, args.timeout)
+        c = entry["counts"]
+        print(f"  {entry['name']:24} cloned={str(entry['cloned']):5} "
+              f"proc={c['processes']} step={c['steps']} comp={c['composites']} "
+              f"study={c['studies']} inv={c['investigations']}", file=sys.stderr)
+        repos.append(entry)
+
+    index = {
+        "generated_at": args.stamp or datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "n_repos": len(repos),
+        "n_cloned": sum(1 for r in repos if r["cloned"]),
+        "repos": repos,
+    }
+    Path(args.out).write_text(json.dumps(index, indent=2) + "\n", encoding="utf-8")
+    print(f"wrote {args.out}: {index['n_repos']} repos, {index['n_cloned']} cloned", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())