refactor(e2e): single populate script, @cluster-free tag scoping, review fixes

Apply the code-review findings on the cluster-free harness:

- Extract the dynamic-plugins-root populate step into
  e2e-tests/local-harness/populate.sh — the single source of truth used by
  CI, the docs, and the global-setup error message (they had already
  diverged: CI installed the harness OCI set pinned to CLI 0.2.0 while the
  docs/error message pointed at the catalog index, unversioned).
- Drop the unused CATALOG_INDEX_IMAGE env from the workflow: with the
  harness dynamic-plugins.yaml (no includes), the CLI only used it to
  extract a catalog index that nothing consumed — a wasted :latest quay
  pull on every run. Fix the workflow header comment accordingly (plugins
  come from ghcr OCI, not the catalog index).
- Scope the harness run by a @cluster-free test tag instead of a title
  regex; widening coverage is now tagging the validated test and
  allowlisting its spec file in testMatch.
- Count only directories in the global-setup guard: the installer writes
  its generated global-config file into dynamic-plugins-root even when
  zero plugins install, which previously satisfied the guard and produced
  the confusing locator timeout it exists to prevent.
- Rewrite the docs populate section: the OCI/populate.sh path (what CI
  uses, works from a fresh clone) is primary; the catalog-index path is
  demoted to after-source-build use since its default.yaml references
  ./dynamic-plugins/dist paths that don't exist otherwise.
- Gitignore the root dynamic-plugins.yaml copy the populate script leaves
  behind (the CLI hardcodes that path).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: gustavolira

.github/workflows/e2e-cluster-free.yaml

@@ -2,9 +2,9 @@ name: E2E Cluster-free Harness
 
 # Runs the cluster-free local E2E harness (RHIDP-13501 / RHIDP-15075): boots the
 # backend and the legacy app dev server in-process and drives Playwright against
-# them, with dynamic plugins pulled from the public catalog index via the
-# install-dynamic-plugins CLI (skopeo). No OpenShift/Kubernetes cluster or image.
-# See docs/e2e-tests/local-e2e-harness.md.
+# them, with dynamic plugins installed from the public OCI registry (ghcr) via
+# the install-dynamic-plugins CLI (skopeo). No OpenShift/Kubernetes cluster or
+# image. See docs/e2e-tests/local-e2e-harness.md.
 
 on:
   pull_request:
@@ -28,10 +28,6 @@ concurrency:
 permissions:
   contents: read
 
-env:
-  # Public index; release branches can override to the matching :1.y tag.
-  CATALOG_INDEX_IMAGE: quay.io/rhdh/plugin-catalog-index:latest
-
 jobs:
   legacy-local:
     name: Cluster-free E2E (legacy app)
@@ -77,14 +73,11 @@ jobs:
         run: yarn install --mode=skip-build
 
       - name: Populate dynamic-plugins-root (OCI, no source build)
-        # install-dynamic-plugins pulls the dynamic-home-page frontend plugin from the
-        # public OCI registry (ghcr) via skopeo — the core plugins in the catalog
-        # index's default.yaml reference local ./dynamic-plugins/dist paths that only
-        # exist after a source build, so we install the OCI-published build instead.
-        run: |
-          mkdir -p dynamic-plugins-root
-          cp e2e-tests/local-harness/dynamic-plugins.yaml dynamic-plugins.yaml
-          npx -y @red-hat-developer-hub/cli-module-install-dynamic-plugins@0.2.0 install dynamic-plugins-root
+        # install-dynamic-plugins pulls the harness plugin set from the public OCI
+        # registry (ghcr) via skopeo — the core plugins in the catalog index's
+        # default.yaml reference local ./dynamic-plugins/dist paths that only exist
+        # after a source build, so we install the OCI-published builds instead.
+        run: ./e2e-tests/local-harness/populate.sh
 
       - name: Run cluster-free E2E (legacy app)
         working-directory: ./e2e-tests

.gitignore

@@ -64,6 +64,8 @@ site
 # Dynamic plugins root content
 dynamic-plugins-root/*
 !dynamic-plugins-root/.gitkeep
+# install-dynamic-plugins config copied to the repo root by e2e-tests/local-harness/populate.sh
+/dynamic-plugins.yaml
 
 #dev caches
 .webpack-cache

docs/e2e-tests/local-e2e-harness.md

@@ -22,21 +22,36 @@ sign in."_
 
 ### 1. Populate `dynamic-plugins-root` (one-time)
 
-Production-faithful — full plugin set and generated config, the same source CI uses:
+Run the same script CI uses — it installs the harness plugin set
+(`e2e-tests/local-harness/dynamic-plugins.yaml`) from the public OCI registry (ghcr)
+via `install-dynamic-plugins` + skopeo, pinned to the same CLI version as CI. No
+source build needed; works from a fresh clone. Requires skopeo (Linux/CI — not
+available on macOS):
 
 ```bash
-# main branch -> :latest; release branches -> the matching :1.y tag
-CATALOG_INDEX_IMAGE=quay.io/rhdh/plugin-catalog-index:latest \
-  npx @red-hat-developer-hub/cli-module-install-dynamic-plugins install dynamic-plugins-root
+./e2e-tests/local-harness/populate.sh
 ```
 
-Offline alternative (frontend plugins only; requires a reconciled workspace —
-see "Known issues"):
+Alternatives:
 
-```bash
-yarn --cwd dynamic-plugins export-dynamic
-yarn --cwd dynamic-plugins copy-dynamic-plugins ../dynamic-plugins-root
-```
+- **Catalog index** — the index's `dynamic-plugins.default.yaml` references the core
+  plugins by local `./dynamic-plugins/dist/…` paths that only exist after a source
+  build, so on a fresh clone most plugins are skipped. Use only after building
+  `dynamic-plugins` from source (main -> `:latest`; release branches -> the matching
+  `:1.y` tag):
+
+  ```bash
+  CATALOG_INDEX_IMAGE=quay.io/rhdh/plugin-catalog-index:latest \
+    npx @red-hat-developer-hub/cli-module-install-dynamic-plugins install dynamic-plugins-root
+  ```
+
+- **Offline from-source** (frontend plugins only; requires a reconciled workspace —
+  see "Known issues"):
+
+  ```bash
+  yarn --cwd dynamic-plugins export-dynamic
+  yarn --cwd dynamic-plugins copy-dynamic-plugins ../dynamic-plugins-root
+  ```
 
 ### 2. Run
 
@@ -47,11 +62,12 @@ yarn --cwd e2e-tests e2e:legacy-local
 Playwright (`playwright.legacy-local.config.ts`) boots the backend and the legacy app
 dev server with `app-config.yaml` + `app-config.dynamic-plugins.yaml` +
 `app-config.local-e2e.yaml`. A `globalSetup` first fails fast with the populate command
-if `dynamic-plugins-root` is empty.
+if `dynamic-plugins-root` has no plugins.
 
-By default the run is scoped (via `grep`) to the one test verified green off-cluster so
-far — the `guest-signin-happy-path` home-page test. Widen `testMatch`/`grep` as more
-specs are validated (see "Known issues").
+The run is scoped to tests tagged `@cluster-free` within the spec files allowlisted in
+`testMatch` — today the one test verified green off-cluster, the
+`guest-signin-happy-path` home-page test. To widen coverage, tag a validated test with
+`@cluster-free` and add its spec file to `testMatch` (see "Known issues").
 
 ### Verified
 
@@ -63,11 +79,11 @@ frontend plugin renders with no cluster.
 ## CI
 
 `.github/workflows/e2e-cluster-free.yaml` runs this harness on GitHub Actions in a
-cluster-free phase: it installs deps + skopeo, populates `dynamic-plugins-root` from the
-public catalog index via the `install-dynamic-plugins` CLI (the same mechanism the
-nightly sanity check uses), then runs `yarn e2e:legacy-local`. No cluster or container
-image is built. It triggers on `e2e-tests/**` and `app-config*.yaml` changes; the scope
-can widen to `packages/app/**` / `packages/backend/**` once it is proven stable.
+cluster-free phase: it installs deps + skopeo, populates `dynamic-plugins-root` via
+`./e2e-tests/local-harness/populate.sh` (the harness plugin set from the public OCI
+registry, ghcr), then runs `yarn e2e:legacy-local`. No cluster or container image is
+built. It triggers on `e2e-tests/**` and `app-config*.yaml` changes; the scope can
+widen to `packages/app/**` / `packages/backend/**` once it is proven stable.
 
 ## Why the legacy app, not app-next
 

e2e-tests/local-harness/dynamic-plugins.yaml

@@ -1,5 +1,6 @@
-# Cluster-free harness plugin set — installed via install-dynamic-plugins from OCI
-# (ghcr, pulled with skopeo), so no dynamic-plugins/dist source build is needed.
+# Cluster-free harness plugin set — installed by ./populate.sh via
+# install-dynamic-plugins from OCI (ghcr, pulled with skopeo), so no
+# dynamic-plugins/dist source build is needed.
 #
 # app-config.dynamic-plugins.yaml (loaded by the harness) already configures these
 # plugins, so the existing RHDH specs render off-cluster.

e2e-tests/local-harness/populate.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+#
+# Populates dynamic-plugins-root for the cluster-free E2E harness — the single
+# source of truth for the populate step (CI, the docs, and the global-setup
+# error message all point here).
+#
+# Installs the plugin set from e2e-tests/local-harness/dynamic-plugins.yaml
+# from the public OCI registry (ghcr) via install-dynamic-plugins + skopeo —
+# no dynamic-plugins/dist source build and no cluster. Requires skopeo
+# (Linux/CI; not available on macOS — see docs/e2e-tests/local-e2e-harness.md).
+set -e
+
+# Pinned so local runs install the exact CLI version CI uses.
+CLI_VERSION="0.2.0"
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$REPO_ROOT"
+
+mkdir -p dynamic-plugins-root
+# The CLI hardcodes ./dynamic-plugins.yaml (cwd) as its config file; the copy at
+# the repo root is gitignored.
+cp e2e-tests/local-harness/dynamic-plugins.yaml dynamic-plugins.yaml
+npx -y "@red-hat-developer-hub/cli-module-install-dynamic-plugins@$CLI_VERSION" install dynamic-plugins-root

e2e-tests/playwright.legacy-local.config.ts

@@ -10,14 +10,9 @@ import { defineConfig, devices } from "@playwright/test";
  * OpenShift/Kubernetes cluster or container images. Playwright boots the backend and
  * the legacy app dev server itself and drives the browser against them.
  *
- *   # one-time: populate dynamic-plugins-root (production-faithful — full plugin set
- *   # and generated config, same source CI uses):
- *   # main -> :latest; release branches -> the matching :1.y tag
- *   CATALOG_INDEX_IMAGE=quay.io/rhdh/plugin-catalog-index:latest \
- *     npx @red-hat-developer-hub/cli-module-install-dynamic-plugins install dynamic-plugins-root
- *   # (offline alternative, frontend plugins only, needs reconciled deps:
- *   #  yarn --cwd dynamic-plugins export-dynamic && \
- *   #  yarn --cwd dynamic-plugins copy-dynamic-plugins ../dynamic-plugins-root)
+ *   # one-time: populate dynamic-plugins-root (same script CI uses — OCI, no build;
+ *   # alternatives in docs/e2e-tests/local-e2e-harness.md):
+ *   ./e2e-tests/local-harness/populate.sh
  *
  *   yarn --cwd e2e-tests e2e:legacy-local
  *
@@ -42,13 +37,16 @@ export default defineConfig({
   testDir: "./playwright",
   // Fails fast if dynamic-plugins-root has not been populated.
   globalSetup: "./playwright/support/local-harness-global-setup.ts",
-  // Runs the guest-signin home-page test, verified green off-cluster (the dynamic
-  // home-page plugin renders from OCI). `grep` scopes to it because the sibling
-  // Settings/Sign-out tests navigate via the top-right profile dropdown, which needs
-  // the global-header plugin to *mount* in the layout — it loads off-cluster but
-  // rendering it needs more config (follow-up). Widen as specs are validated.
+  // A test runs cluster-free when its spec file is listed in `testMatch` (an
+  // allowlist, so unvalidated specs are never loaded) AND it carries the
+  // @cluster-free tag. To widen coverage: tag the test where it lives and add its
+  // spec file here. Today that is the guest-signin home-page test, verified green
+  // off-cluster (the dynamic home-page plugin renders from OCI); its sibling
+  // Settings/Sign-out tests stay untagged because they navigate via the top-right
+  // profile dropdown, which needs the global-header plugin to *mount* in the
+  // layout — it loads off-cluster but rendering it needs more config (follow-up).
   testMatch: ["e2e/guest-signin-happy-path.spec.ts"],
-  grep: /Homepage renders with Search Bar/u,
+  grep: /@cluster-free/u,
   timeout: 90 * 1000,
   forbidOnly: isCI,
   retries: isCI ? 1 : 0,

e2e-tests/playwright/e2e/guest-signin-happy-path.spec.ts

@@ -27,11 +27,16 @@ test.describe("Guest Signing Happy path", () => {
     await common.loginAsGuest();
   });
 
-  test("Verify the Homepage renders with Search Bar, Quick Access and Starred Entities", async () => {
-    await uiHelper.verifyHeading("Welcome back!");
-    await uiHelper.openSidebar("Home");
-    await homePage.verifyQuickAccess("Developer Tools", "Podman Desktop");
-  });
+  // @cluster-free: verified green on the cluster-free harness (playwright.legacy-local.config.ts)
+  test(
+    "Verify the Homepage renders with Search Bar, Quick Access and Starred Entities",
+    { tag: "@cluster-free" },
+    async () => {
+      await uiHelper.verifyHeading("Welcome back!");
+      await uiHelper.openSidebar("Home");
+      await homePage.verifyQuickAccess("Developer Tools", "Podman Desktop");
+    },
+  );
 
   test("Verify Profile is Guest in the Settings page", async () => {
     await uiHelper.goToSettingsPage();

e2e-tests/playwright/support/local-harness-global-setup.ts

@@ -12,18 +12,22 @@ export default function requireDynamicPluginsPopulated(): void {
   // process.cwd() is e2e-tests when Playwright runs; the plugins root is at repo root.
   const root = resolve(process.cwd(), "..", "dynamic-plugins-root");
 
+  // Plugins are installed as one directory each; count only directories so the
+  // installer's generated global-config file (written into the same root even when
+  // zero plugins install) does not satisfy the guard.
   let pluginCount = 0;
   try {
-    pluginCount = readdirSync(root).filter((entry) => entry !== ".gitkeep").length;
+    pluginCount = readdirSync(root, { withFileTypes: true }).filter((entry) =>
+      entry.isDirectory(),
+    ).length;
   } catch {
     // root missing — treated as empty below.
   }
 
   if (pluginCount === 0) {
     throw new Error(
-      `dynamic-plugins-root is empty — populate it before running e2e:legacy-local:\n\n` +
-        `  CATALOG_INDEX_IMAGE=quay.io/rhdh/plugin-catalog-index:latest \\\n` +
-        `    npx @red-hat-developer-hub/cli-module-install-dynamic-plugins install dynamic-plugins-root\n\n` +
+      `dynamic-plugins-root has no plugins — populate it before running e2e:legacy-local:\n\n` +
+        `  ./e2e-tests/local-harness/populate.sh\n\n` +
         `See docs/e2e-tests/local-e2e-harness.md.`,
     );
   }