@@ -18,6 +18,8 @@ on:
       - 'scripts/tests/**'
       - 'scripts/requirements-dev.txt'
       - '.github/workflows/validate-catalog-scripts.yaml'
+      - 'catalog-info.yaml'
+      - 'workspaces/*/catalog-info.yaml'
   workflow_dispatch:
 
 concurrency:
@@ -46,3 +48,6 @@ jobs:
       - name: Run tests
         working-directory: scripts
         run: python -m pytest tests/ -v
+
+      - name: Check generated software-catalog catalog-info.yaml
+        run: python scripts/generateCatalogInfo.py --check
@@ -0,0 +1,27 @@
+# Generated by scripts/generateCatalogInfo.py. Do not edit by hand.
+# Re-run: python3 scripts/generateCatalogInfo.py
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: rhdh-plugin-export-overlays
+  title: RHDH Plugin Export Overlays
+  description: Packaging and OCI publish layer for RHDH dynamic plugins. Contains 65 overlay workspaces.
+  annotations:
+    github.com/project-slug: rhdh-parasol/rhdh-plugin-export-overlays
+  tags:
+    - overlay
+    - dynamic-plugin
+    - repository
+  links:
+    - url: https://github.com/rhdh-parasol/rhdh-plugin-export-overlays
+      title: GitHub repository
+      icon: github
+      type: source
+    - url: https://github.com/rhdh-parasol/rhdh-plugin-export-overlays/actions/workflows/publish-workspace-plugins.yaml
+      title: Publish workflow
+      type: ci
+spec:
+  type: repository
+  lifecycle: experimental
+  owner: rhdh-team
+  system: rhdh
@@ -0,0 +1,341 @@
+#!/usr/bin/env python3
+#
+# Copyright (c) Red Hat, Inc.
+# This program and the accompanying materials are made
+# available under the terms of the Eclipse Public License 2.0
+# which is available at https://www.eclipse.org/legal/epl-2.0/
+#
+# SPDX-License-Identifier: EPL-2.0
+#
+# Generate software-catalog catalog-info.yaml files for this overlay
+# repository. These are Backstage kind: Component descriptors consumed by
+# GithubEntityProvider (path /workspaces/*/catalog-info.yaml), not the
+# Extensions Catalog Plugin/Package entities under metadata/ and
+# catalog-entities/extensions/.
+#
+# Usage:
+#   python3 scripts/generateCatalogInfo.py
+#   python3 scripts/generateCatalogInfo.py --check
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import yaml
+
+from plugin_utils import (
+    log_error,
+    log_info,
+    log_warn,
+    read_plugins_list,
+    set_debug,
+)
+
+GENERATED_HEADER = """\
+# Generated by scripts/generateCatalogInfo.py. Do not edit by hand.
+# Re-run: python3 scripts/generateCatalogInfo.py
+"""
+
+DEFAULT_OVERLAY_SLUG = "rhdh-parasol/rhdh-plugin-export-overlays"
+ROOT_COMPONENT_NAME = "rhdh-plugin-export-overlays"
+
+# Software-catalog Component metadata.name in rhdh-plugins workspaces/*/catalog-info.yaml.
+# Only set spec.dependsOn when the source plugin already has a Component in the
+# Parasol software catalog. Overlay workspaces sourced from community-plugins
+# (or other repos) are omitted on purpose.
+RHDH_PLUGINS_COMPONENT_BY_WORKSPACE: dict[str, str] = {
+    "adoption-insights": "adoption-insights",
+    "ai-integrations": "ai-integrations",
+    "app-defaults": "app-defaults",
+    "boost": "boost",
+    "bulk-import": "red-hat-developer-hub-bulk-import",
+    "cost-management": "cost-management",
+    "extensions": "red-hat-developer-hub-extensions",
+    "global-header": "red-hat-developer-hub-global-header",
+    "homepage": "red-hat-developer-hub-homepage",
+    "intelligent-assistant": "developer-intelligent-assistant",
+    "mcp-integrations": "mcp-integrations",
+    "orchestrator": "red-hat-developer-hub-orchestrator",
+    "quickstart": "quickstart",
+    "scorecard": "scorecard",
+    "theme": "red-hat-developer-hub-theme",
+    "translations": "translations",
+    "x2a": "red-hat-developer-hub-x2a-frontend",
+}
+
+
+def overlay_entity_name(workspace: str) -> str:
+    return f"overlay-{workspace}"
+
+
+def is_rhdh_plugins_source(repo: str) -> bool:
+    return repo.rstrip("/").endswith("/rhdh-plugins")
+
+
+def source_tree_url(source: dict, workspace: str) -> str:
+    repo = source["repo"].rstrip("/")
+    ref = source.get("repo-ref") or "main"
+    if source.get("repo-flat"):
+        return f"{repo}/tree/{ref}"
+    return f"{repo}/tree/{ref}/workspaces/{workspace}"
+
+
+def overlay_tree_url(overlay_slug: str, workspace: str) -> str:
+    return f"https://github.com/{overlay_slug}/tree/main/workspaces/{workspace}"
+
+
+def export_workflow_url(overlay_slug: str) -> str:
+    return (
+        f"https://github.com/{overlay_slug}/actions/workflows/"
+        "publish-workspace-plugins.yaml"
+    )
+
+
+def rhdh_plugins_depends_on(workspace: str) -> str | None:
+    return RHDH_PLUGINS_COMPONENT_BY_WORKSPACE.get(workspace)
+
+
+def load_source_json(workspace_dir: Path) -> dict:
+    source_file = workspace_dir / "source.json"
+    with source_file.open(encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+class _IndentDumper(yaml.SafeDumper):
+    """Keep list items indented under their parent key."""
+
+    def increase_indent(self, flow=False, indentless=False):
+        return super().increase_indent(flow, False)
+
+
+def dump_entity(entity: dict) -> str:
+    body = yaml.dump(
+        entity,
+        Dumper=_IndentDumper,
+        sort_keys=False,
+        default_flow_style=False,
+        allow_unicode=True,
+        width=120,
+    )
+    return GENERATED_HEADER + body
+
+
+def build_root_entity(overlay_slug: str, workspace_count: int) -> dict:
+    return {
+        "apiVersion": "backstage.io/v1alpha1",
+        "kind": "Component",
+        "metadata": {
+            "name": ROOT_COMPONENT_NAME,
+            "title": "RHDH Plugin Export Overlays",
+            "description": (
+                "Packaging and OCI publish layer for RHDH dynamic plugins. "
+                f"Contains {workspace_count} overlay workspaces."
+            ),
+            "annotations": {
+                "github.com/project-slug": overlay_slug,
+            },
+            "tags": ["overlay", "dynamic-plugin", "repository"],
+            "links": [
+                {
+                    "url": f"https://github.com/{overlay_slug}",
+                    "title": "GitHub repository",
+                    "icon": "github",
+                    "type": "source",
+                },
+                {
+                    "url": export_workflow_url(overlay_slug),
+                    "title": "Publish workflow",
+                    "type": "ci",
+                },
+            ],
+        },
+        "spec": {
+            "type": "repository",
+            "lifecycle": "experimental",
+            "owner": "rhdh-team",
+            "system": "rhdh",
+        },
+    }
+
+
+def build_workspace_entity(
+    workspace: str,
+    source: dict,
+    plugin_paths: list[str],
+    overlay_slug: str,
+) -> dict:
+    plugin_count = len(plugin_paths)
+    package_word = "package" if plugin_count == 1 else "packages"
+    ref = source.get("repo-ref") or "main"
+    short_ref = ref[:7] if len(ref) >= 7 else ref
+    entity: dict = {
+        "apiVersion": "backstage.io/v1alpha1",
+        "kind": "Component",
+        "metadata": {
+            "name": overlay_entity_name(workspace),
+            "title": f"Overlay workspace {workspace}",
+            "description": (
+                f"Dynamic-plugin export overlay for workspace '{workspace}' "
+                f"({plugin_count} {package_word}). "
+                f"Upstream source pinned at {short_ref}."
+            ),
+            "annotations": {
+                "github.com/project-slug": overlay_slug,
+            },
+            "tags": ["overlay", "dynamic-plugin"],
+            "links": [
+                {
+                    "url": overlay_tree_url(overlay_slug, workspace),
+                    "title": "Overlay workspace",
+                    "icon": "github",
+                    "type": "source",
+                },
+                {
+                    "url": source_tree_url(source, workspace),
+                    "title": "Upstream source",
+                    "icon": "github",
+                    "type": "upstream",
+                },
+                {
+                    "url": export_workflow_url(overlay_slug),
+                    "title": "Latest export workflow",
+                    "type": "ci",
+                },
+            ],
+        },
+        "spec": {
+            "type": "rhdh-overlay-workspace",
+            "lifecycle": "experimental",
+            "owner": "rhdh-team",
+            "system": "rhdh",
+            "subcomponentOf": ROOT_COMPONENT_NAME,
+        },
+    }
+    depends_on = rhdh_plugins_depends_on(workspace)
+    if depends_on and is_rhdh_plugins_source(source.get("repo", "")):
+        entity["spec"]["dependsOn"] = [f"component:default/{depends_on}"]
+    return entity
+
+
+def discover_workspaces(repo_root: Path) -> list[Path]:
+    workspaces_dir = repo_root / "workspaces"
+    if not workspaces_dir.is_dir():
+        return []
+    found = []
+    for path in sorted(workspaces_dir.iterdir()):
+        if path.is_dir() and (path / "source.json").is_file():
+            found.append(path)
+    return found
+
+
+def planned_files(
+    repo_root: Path, overlay_slug: str
+) -> list[tuple[Path, str]]:
+    workspaces = discover_workspaces(repo_root)
+    files: list[tuple[Path, str]] = [
+        (
+            repo_root / "catalog-info.yaml",
+            dump_entity(build_root_entity(overlay_slug, len(workspaces))),
+        )
+    ]
+    for workspace_dir in workspaces:
+        source = load_source_json(workspace_dir)
+        plugin_paths = read_plugins_list(workspace_dir)
+        entity = build_workspace_entity(
+            workspace_dir.name, source, plugin_paths, overlay_slug
+        )
+        files.append((workspace_dir / "catalog-info.yaml", dump_entity(entity)))
+    return files
+
+
+def write_files(files: list[tuple[Path, str]], dry_run: bool) -> None:
+    for path, content in files:
+        if dry_run:
+            log_info(f"would write {path}")
+            continue
+        path.write_text(content, encoding="utf-8")
+        log_info(f"wrote {path}")
+
+
+def check_files(files: list[tuple[Path, str]]) -> int:
+    stale = []
+    for path, content in files:
+        if not path.is_file():
+            stale.append(f"missing {path}")
+            continue
+        if path.read_text(encoding="utf-8") != content:
+            stale.append(f"stale {path}")
+    if stale:
+        for item in stale:
+            log_error(item)
+        log_error(
+            f"{len(stale)} catalog-info.yaml file(s) out of date. "
+            "Re-run: python3 scripts/generateCatalogInfo.py"
+        )
+        return 1
+    log_info(f"{len(files)} catalog-info.yaml file(s) up to date")
+    return 0
+
+
+def repo_root_from_script() -> Path:
+    return Path(__file__).resolve().parent.parent
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Generate software-catalog catalog-info.yaml files for overlay "
+            "workspaces."
+        )
+    )
+    parser.add_argument(
+        "--repo-root",
+        type=Path,
+        default=None,
+        help="Overlay repository root (default: parent of scripts/)",
+    )
+    parser.add_argument(
+        "--overlay-slug",
+        default=DEFAULT_OVERLAY_SLUG,
+        help=f"GitHub org/repo for this overlay fork (default: {DEFAULT_OVERLAY_SLUG})",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Exit 1 if generated files would change (do not write)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print paths that would be written, do not write",
+    )
+    parser.add_argument("--debug", action="store_true")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    set_debug(args.debug)
+    repo_root = (args.repo_root or repo_root_from_script()).resolve()
+    if not (repo_root / "workspaces").is_dir():
+        log_error(f"no workspaces/ directory under {repo_root}")
+        return 1
+
+    files = planned_files(repo_root, args.overlay_slug)
+    if not files:
+        log_warn("no overlay workspaces with source.json found")
+        return 1
+
+    if args.check:
+        return check_files(files)
+
+    write_files(files, dry_run=args.dry_run)
+    log_info(f"{len(files)} catalog-info.yaml file(s)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())