feat(docs): replay the Relay tutorial from its page

.github/scripts/ci_changes.py

@@ -166,15 +166,14 @@
     "docs/site/src/content/docs/tutorials/publish-and-consume-discovery-index.mdx",
 )
 
-# The Relay V2 tutorial teaches readers to hand-author its registry contract
-# across eleven fences rather than run a single product script, so its gate
-# follows the Evidence tutorial's fence-replay shape and reuses its shared
-# helper. This tuple keeps the CI trigger honest with what actually replays
-# the tutorial.
+# Every input the Relay V2 tutorial gate replays: the page runner and the page
+# whose frontmatter it replays. The binaries it runs are Relay V2 packages, so
+# package routing already carries their build inputs.
 RELAY_TUTORIAL_INPUTS = (
-    "docs/site/scripts/check-relay-tutorial.sh",
-    "docs/site/scripts/check-relay-tutorial.test.mjs",
-    "docs/site/scripts/evidence-tutorial-fence.sh",
+    "docs/site/package-lock.json",
+    "docs/site/package.json",
+    "docs/site/scripts/run-tutorial.mjs",
+    "docs/site/scripts/tutorial-runner/**",
     "docs/site/src/content/docs/tutorials/publish-governed-sqlite-registry.mdx",
 )
 
@@ -1281,7 +1280,7 @@ def classify(
         or any(path in DISCOVERY_TUTORIAL_INPUTS for path in paths),
         "relay_v2_contracts": registry_record_cross_product
         or bool(affected & RELAY_V2_PACKAGES)
-        or any(path in RELAY_TUTORIAL_INPUTS for path in paths),
+        or any(matches(path, *RELAY_TUTORIAL_INPUTS) for path in paths),
         "relay_client_contracts": bool(affected & RELAY_CLIENT_PACKAGES),
         "breg_contracts": breg_contracts,
         "evidence_contracts": bool(affected & EVIDENCE_PACKAGES),

.github/scripts/test_ci_changes.py

@@ -620,10 +620,45 @@ def test_every_discovery_tutorial_input_replays_the_product_gate(self) -> None:
 
     def test_every_relay_tutorial_input_replays_the_product_gate(self) -> None:
         for path in RELAY_TUTORIAL_INPUTS:
+            if path.endswith("/**"):
+                continue
             with self.subTest(path=path):
                 self.assertTrue(Path(path).is_file())
                 self.assertTrue(classify(self.workspace, (path,))["relay_v2_contracts"])
 
+    def test_relay_tutorial_routing(self) -> None:
+        infrastructure = (
+            "docs/site/scripts/run-tutorial.mjs",
+            "docs/site/scripts/tutorial-runner/toolsets.mjs",
+            "docs/site/src/content/docs/tutorials/publish-governed-sqlite-registry.mdx",
+            "docs/site/package.json",
+        )
+        for path in infrastructure:
+            with self.subTest(path=path):
+                self.assertTrue(
+                    classify(self.workspace, (path,))["relay_v2_contracts"]
+                )
+
+    def test_relay_tutorial_inputs_cover_every_replayed_tutorial(self) -> None:
+        docs = Path(__file__).resolve().parents[2] / "docs/site/src/content/docs"
+        slugs = []
+        for section in ("start", "tutorials"):
+            for page in sorted((docs / section).glob("*.mdx")):
+                frontmatter = yaml.safe_load(page.read_text().split("---\n")[1])
+                declaration = frontmatter.get("tutorial_test") or {}
+                if declaration.get("toolset") == "relay" and "skip" not in declaration:
+                    slugs.append(f"{section}/{page.stem}")
+        self.assertIn("tutorials/publish-governed-sqlite-registry", slugs)
+        for slug in slugs:
+            with self.subTest(slug=slug):
+                page = f"docs/site/src/content/docs/{slug}.mdx"
+                self.assertTrue(
+                    any(
+                        fnmatch.fnmatchcase(page, pattern)
+                        for pattern in RELAY_TUTORIAL_INPUTS
+                    )
+                )
+
     def test_relay_v2_paths_select_the_editor_and_reverse_dependents(self) -> None:
         outputs = classify(
             self.workspace,

.github/workflows/ci.yml

@@ -603,6 +603,13 @@ jobs:
           persist-credentials: false
           submodules: false
 
+      - name: Setup Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: 22.12.0
+          cache: npm
+          cache-dependency-path: docs/site/package-lock.json
+
       - name: Cache Cargo registry
         uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
         with:
@@ -621,8 +628,28 @@ jobs:
           RELAY_V2_STOCK_ISSUER: "1"
         run: products/relay-v2/scripts/test-http.sh
 
-      - name: Relay V2 tutorial reader gate
-        run: docs/site/scripts/check-relay-tutorial.sh
+      - name: Install docs dependencies
+        working-directory: docs/site
+        run: npm ci
+
+      - name: Test the tutorial runner
+        working-directory: docs/site
+        run: npm run test:tutorial:runner
+
+      - name: Check tutorial command drift
+        working-directory: docs/site
+        run: npm run check:tutorial:relay:dry-run
+
+      - name: Build the Relay V2 toolset under test
+        run: cargo build --locked -p registry-relay-v2 --features tooling -p registry-relayctl --bins
+
+      - name: Execute the Relay V2 tutorial from a reader directory
+        env:
+          RELAY_BIN: ${{ github.workspace }}/target/debug/relay
+          RELAYCTL_BIN: ${{ github.workspace }}/target/debug/relayctl
+        # The page serves on 127.0.0.1:8080, which nothing on this runner
+        # holds, so the replay runs on the port a reader gets.
+        run: node docs/site/scripts/run-tutorial.mjs --gate relay
 
   relay-client-contracts:
     name: Relay client contract and source neutrality

docs/site/package.json

@@ -45,8 +45,8 @@
     "check:tutorial:dry-run": "scripts/check-tutorial.sh --dry-run",
     "check:tutorial:discovery": "bash scripts/check-discovery-tutorial.sh",
     "check:tutorial:discovery:dry-run": "bash scripts/check-discovery-tutorial.sh --dry-run",
-    "check:tutorial:relay": "bash scripts/check-relay-tutorial.sh",
-    "check:tutorial:relay:dry-run": "bash scripts/check-relay-tutorial.sh --dry-run",
+    "check:tutorial:relay": "node scripts/run-tutorial.mjs --gate relay",
+    "check:tutorial:relay:dry-run": "node scripts/run-tutorial.mjs --gate relay --dry-run",
     "check:tutorial:evidence": "node scripts/run-tutorial.mjs --gate evidence",
     "check:tutorial:evidence:dry-run": "node scripts/run-tutorial.mjs --gate evidence --dry-run",
     "test:tutorial:runner": "node --test \"scripts/tutorial-runner/*.test.mjs\"",