Merge Staging into Prod

.claude/skills

@@ -0,0 +1 @@
+../skills

.github/actions/build-docs-site/action.yml

@@ -0,0 +1,114 @@
+name: Build docs site
+description: Populate generated sources and render a complete documentation site
+
+inputs:
+  profile:
+    description: Quarto profile to render
+    required: true
+  docs_ci_ro_pat:
+    description: Read-only token for private source repositories
+    required: true
+  quarto_version:
+    description: Quarto version to install
+    required: true
+  library_ref:
+    description: validmind-library revision to build
+    required: true
+  installation_ref:
+    description: installation revision to build
+    required: true
+  release_notes_ref:
+    description: release-notes revision to build
+    required: true
+  backend_ref:
+    description: backend revision to build
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Check out validmind-library repository
+      uses: actions/checkout@v4
+      with:
+        repository: validmind/validmind-library
+        ref: ${{ inputs.library_ref }}
+        path: site/_source/validmind-library
+        token: ${{ inputs.docs_ci_ro_pat }}
+
+    - name: Check out installation repository
+      uses: actions/checkout@v4
+      with:
+        repository: validmind/installation
+        ref: ${{ inputs.installation_ref }}
+        path: site/_source/installation
+        token: ${{ inputs.docs_ci_ro_pat }}
+        sparse-checkout: |
+          site/installation
+        sparse-checkout-cone-mode: true
+
+    - name: Check out release-notes repository
+      uses: actions/checkout@v4
+      with:
+        repository: validmind/release-notes
+        ref: ${{ inputs.release_notes_ref }}
+        path: site/_source/release-notes
+        token: ${{ inputs.docs_ci_ro_pat }}
+        sparse-checkout: |
+          releases
+        sparse-checkout-cone-mode: true
+
+    - name: Check out backend repository
+      uses: actions/checkout@v4
+      with:
+        repository: validmind/backend
+        ref: ${{ inputs.backend_ref }}
+        path: site/_source/backend
+        token: ${{ inputs.docs_ci_ro_pat }}
+        sparse-checkout: |
+          src/backend/templates/documentation/model_documentation
+        sparse-checkout-cone-mode: true
+
+    - name: Set up Quarto
+      uses: quarto-dev/quarto-actions/setup@v2
+      with:
+        version: ${{ inputs.quarto_version }}
+
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v5
+
+    - name: Generate Python library docs
+      shell: bash
+      run: |
+        cd site/_source/validmind-library
+        make install && make quarto-docs
+        cd ../../
+        rm -rf validmind
+        mkdir -p validmind
+        rsync -av --exclude '_build' --exclude 'templates' _source/validmind-library/docs/ validmind/
+
+    - name: Generate template schema docs
+      shell: bash
+      run: BACKEND_ROOT=site/_source/backend uv run --with json-schema-for-humans python scripts/generate_template_schema_docs.py
+
+    - name: Populate installation
+      shell: bash
+      run: cp -r site/_source/installation/site/installation site/installation
+
+    - name: Populate release notes
+      shell: bash
+      run: |
+        cp -r site/_source/release-notes/releases site
+        rm -f site/releases/backend-releases.qmd site/releases/cmvm-releases.qmd
+
+    - name: Render docs site
+      shell: bash
+      env:
+        QUARTO_PROFILE: ${{ inputs.profile }}
+      run: |
+        cd site
+        quarto render --profile "$QUARTO_PROFILE" &> render_errors.log || {
+          echo "Quarto render failed immediately"
+          cat render_errors.log
+          exit 1
+        }
+        make generate-sitemap

.github/scripts/merge_quarto_indexes.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
+
+"""Merge Quarto indexes from a partial render into full-site indexes."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+
+def merge_items(
+    base: list[dict[str, Any]], partial: list[dict[str, Any]], key: str
+) -> list[dict[str, Any]]:
+    """Return base items with partial items replacing entries with the same key."""
+    merged: dict[str, dict[str, Any]] = {}
+    for item in [*base, *partial]:
+        value = item.get(key)
+        if not isinstance(value, str) or not value:
+            raise ValueError(f"Every index item must have a non-empty {key!r}")
+        merged[value] = item
+    return list(merged.values())
+
+
+def merge_file(base_path: Path, partial_path: Path, key: str) -> None:
+    base = json.loads(base_path.read_text())
+    partial = json.loads(partial_path.read_text())
+    if not isinstance(base, list) or not isinstance(partial, list):
+        raise ValueError("Quarto indexes must contain JSON arrays")
+    partial_path.write_text(
+        json.dumps(merge_items(base, partial, key), separators=(",", ":"))
+    )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--base-search", type=Path, required=True)
+    parser.add_argument("--partial-search", type=Path, required=True)
+    parser.add_argument("--base-listings", type=Path, required=True)
+    parser.add_argument("--partial-listings", type=Path, required=True)
+    args = parser.parse_args()
+
+    merge_file(args.base_search, args.partial_search, "objectID")
+    merge_file(args.base_listings, args.partial_listings, "listing")
+
+
+if __name__ == "__main__":
+    main()

.github/scripts/select_docs_preview_targets.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
+
+"""Select pages that are safe to render incrementally for a PR preview."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+
+PAGE_SUFFIXES = {".qmd", ".md", ".ipynb"}
+ASSET_SUFFIXES = {".avif", ".gif", ".jpeg", ".jpg", ".pdf", ".png", ".svg", ".webp"}
+UNSAFE_TOP_LEVEL = {
+    "_extensions",
+    "_freeze",
+    "_source",
+    "environments",
+    "llm",
+    "scripts",
+}
+STATUS_MAP = {
+    "added": "A",
+    "modified": "M",
+    "removed": "D",
+    "renamed": "R",
+    "copied": "C",
+    "changed": "T",
+}
+
+
+@dataclass(frozen=True)
+class Selection:
+    targets: tuple[str, ...] = ()
+    assets: tuple[str, ...] = ()
+    fallback_reason: str | None = None
+
+    @property
+    def is_targeted(self) -> bool:
+        return self.fallback_reason is None
+
+
+def select(changes: list[tuple[str, tuple[str, ...]]]) -> Selection:
+    targets: set[str] = set()
+    assets: set[str] = set()
+
+    for status, paths in changes:
+        if status not in {"A", "M"} or len(paths) != 1:
+            return Selection(fallback_reason=f"{status} change requires a full render")
+
+        path = PurePosixPath(paths[0])
+        if not path.parts or path.parts[0] != "site" or len(path.parts) < 2:
+            return Selection(fallback_reason=f"{path} is outside targetable site content")
+
+        relative = PurePosixPath(*path.parts[1:])
+        if relative.parts[0] in UNSAFE_TOP_LEVEL:
+            return Selection(fallback_reason=f"{path} can affect generated or global content")
+        if any(part.startswith("_") for part in relative.parts):
+            return Selection(fallback_reason=f"{path} is Quarto metadata or shared content")
+
+        suffix = relative.suffix.lower()
+        if suffix in PAGE_SUFFIXES:
+            targets.add(relative.as_posix())
+        elif suffix in ASSET_SUFFIXES:
+            assets.add(relative.as_posix())
+        else:
+            return Selection(fallback_reason=f"{path} is not a targetable page or asset")
+
+    if not targets:
+        return Selection(fallback_reason="no changed renderable pages were found")
+
+    return Selection(tuple(sorted(targets)), tuple(sorted(assets)))
+
+
+def parse_changed_files(output: str) -> list[tuple[str, tuple[str, ...]]]:
+    changes: list[tuple[str, tuple[str, ...]]] = []
+    for line in output.splitlines():
+        fields = line.split("\t")
+        if len(fields) < 2:
+            raise ValueError(f"Unexpected changed-file line: {line!r}")
+        status = STATUS_MAP.get(fields[0], fields[0][0].upper())
+        changes.append((status, tuple(field for field in fields[1:] if field)))
+    return changes
+
+
+def write_lines(path: Path, values: tuple[str, ...]) -> None:
+    path.write_text("".join(f"{value}\n" for value in values))
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--changes", default="-")
+    parser.add_argument("--targets", type=Path, required=True)
+    parser.add_argument("--assets", type=Path, required=True)
+    args = parser.parse_args()
+
+    if args.changes == "-":
+        changed_files = sys.stdin.read()
+    else:
+        changed_files = Path(args.changes).read_text()
+
+    selection = select(parse_changed_files(changed_files))
+    if not selection.is_targeted:
+        print(f"Full render required: {selection.fallback_reason}")
+        return 3
+
+    write_lines(args.targets, selection.targets)
+    write_lines(args.assets, selection.assets)
+    print("Targeted render pages:")
+    print("\n".join(selection.targets))
+    if selection.assets:
+        print("Targeted preview assets:")
+        print("\n".join(selection.assets))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.github/scripts/test_merge_quarto_indexes.py

@@ -0,0 +1,49 @@
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
+
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from merge_quarto_indexes import merge_file, merge_items
+
+
+class MergeQuartoIndexesTest(unittest.TestCase):
+    def test_partial_items_replace_matching_base_items(self):
+        base = [{"objectID": "old", "text": "keep"}, {"objectID": "changed", "text": "old"}]
+        partial = [{"objectID": "changed", "text": "new"}, {"objectID": "new", "text": "add"}]
+
+        self.assertEqual(
+            merge_items(base, partial, "objectID"),
+            [
+                {"objectID": "old", "text": "keep"},
+                {"objectID": "changed", "text": "new"},
+                {"objectID": "new", "text": "add"},
+            ],
+        )
+
+    def test_merge_file_updates_partial_path(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base_path = Path(directory) / "base.json"
+            partial_path = Path(directory) / "partial.json"
+            base_path.write_text(json.dumps([{"listing": "/old", "items": ["a"]}]))
+            partial_path.write_text(json.dumps([{"listing": "/new", "items": ["b"]}]))
+
+            merge_file(base_path, partial_path, "listing")
+
+            self.assertEqual(
+                json.loads(partial_path.read_text()),
+                [
+                    {"listing": "/old", "items": ["a"]},
+                    {"listing": "/new", "items": ["b"]},
+                ],
+            )
+
+    def test_missing_key_is_rejected(self):
+        with self.assertRaises(ValueError):
+            merge_items([], [{"text": "missing object id"}], "objectID")
+
+
+if __name__ == "__main__":
+    unittest.main()