fix(docs): resolve verify-docs harness spawn enoent root cause (#2178) (#2210)

The "Node 22 test-runner spawn ENOENT" the verify-docs harness reported
was not a Node regression. The real chain:

1. `wheels new` exits 0 even when it cannot locate vendor/wheels/ (it
   prints a red error, cleans up the partial scaffold, then returns 0).
2. `createFixture` saw exit 0 and returned the expected fixture path.
3. The next spawn used that path as `cwd`. Node's posix_spawn can't
   chdir there, so it reports `spawn PROGRAM ENOENT` — pointing at the
   program instead of the missing cwd, which read as a program-lookup
   bug.

Changes:

- `createFixture` now stats the returned path. If `wheels new` exited 0
  but didn't create the directory, throw immediately with the captured
  stdout/stderr and a pointer to `WHEELS_FRAMEWORK_PATH`.
- Workflow sets `WHEELS_FRAMEWORK_PATH` to `${{ github.workspace }}/vendor/wheels`
  so `wheels new` can find the framework in CI. Drops the Node 20 pin
  and the Node 22 restore step — both were treating the symptom.
- VALIDATION.md documents the `WHEELS_FRAMEWORK_PATH` requirement for
  local harness runs.
- Updates stale comments in exec.mjs that speculated about a Node 22
  posix_spawn quirk.

The `wheels new` exit-0-on-error behavior is a separate upstream bug
(tracked elsewhere); catching the missing fixture dir makes the harness
robust to it in the meantime.

Author: bpamiri

.github/workflows/docs-verify.yml

@@ -70,43 +70,27 @@ jobs:
         # the harness spawns `wheels`.
         run: wheels --version >/dev/null
 
-      - name: Set up Node.js (harness tests)
-        # Pin Node 20 for the harness unit tests only. Node 22's test-runner
-        # workers on Linuxbrew return spawn ENOENT on EVERY absolute path —
-        # including /bin/bash itself — even when statSync/accessSync confirm
-        # the file is executable and spawnable from the main process. Node 20
-        # is unaffected. Tracked as issue #2178 (workaround pending upstream
-        # Node fix). The main content gate (Verify v4 docs) continues on
-        # Node 22 below.
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: pnpm
-          cache-dependency-path: web/pnpm-lock.yaml
-
       - name: Run harness unit tests
         working-directory: web/sites/guides
-        # Runs on Node 20 to avoid the Node 22 spawn ENOENT bug (see the
-        # "Set up Node.js (harness tests)" step above). Ref #2178.
+        # Runs on Node 22 (no longer pinned to Node 20). The "spawn ENOENT"
+        # that looked like a Node 22 posix_spawn regression was actually
+        # caused by `wheels new` exiting 0 after a framework-not-found
+        # error, leaving the fixture cwd missing; Node's spawn then reports
+        # ENOENT against the program instead of the cwd. Setting
+        # WHEELS_FRAMEWORK_PATH at the checked-out repo's vendor/wheels
+        # lets `wheels new` succeed, which makes fixture cwds real. See
+        # #2178 for the full root-cause write-up.
         #
-        # Still soft-fail for now: with Node 20 the spawns work, which
-        # surfaces 7 pre-existing tutorial-driver failures (blog-tutorial
-        # fixture's lucee.json is no longer emitted by `wheels new`).
-        # Tracked separately — once fixtures are fixed, drop
-        # continue-on-error so regressions fail CI as originally intended.
+        # Still soft-fail: surfaces the remaining tutorial-driver fixture
+        # issues (e.g., blog-tutorial's lucee.json emission). Drop
+        # continue-on-error once those are fixed.
         continue-on-error: true
+        env:
+          WHEELS_FRAMEWORK_PATH: ${{ github.workspace }}/vendor/wheels
         run: |
           export LUCLI_HOME="$HOME/.wheels"
           pnpm test:docs-harness
 
-      - name: Set up Node.js (main)
-        # Restore Node 22 for the content gate and the guides build below.
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: pnpm
-          cache-dependency-path: web/pnpm-lock.yaml
-
       - name: Verify v4 docs
         working-directory: web/sites/guides
         # Soft-fail: at 290 tagged blocks / 4-way concurrency, LuCLI's

web/sites/guides/scripts/verify-docs/VALIDATION.md

@@ -110,3 +110,21 @@ Blocks that cannot or should not compile:
 ```cfm title="illustrative — do not type"
 someAPI.callThat.doesntExistYet();
 ```
+
+## Running the harness locally
+
+The drivers spawn `wheels new` into a temp directory per test. `wheels new`
+needs a `vendor/wheels/` source tree, and a temp directory has none in its
+ancestry. Point the CLI at this repo's checkout before running either the
+harness unit tests or the full content gate:
+
+```sh
+export WHEELS_FRAMEWORK_PATH="$(git rev-parse --show-toplevel)/vendor/wheels"
+pnpm --filter @wheels/guides test:docs-harness   # harness unit tests
+pnpm --filter @wheels/guides verify:docs         # full content gate
+```
+
+Without `WHEELS_FRAMEWORK_PATH`, `wheels new` prints a framework-not-found
+error and exits 0 anyway; the harness detects the missing fixture directory
+and throws with a pointer back to this doc rather than surfacing a
+misleading `spawn … ENOENT` on the next child process.

web/sites/guides/scripts/verify-docs/lib/exec.mjs

@@ -48,12 +48,13 @@ export function runExec(program, args = [], opts = {}) {
   if (timeout !== undefined) spawnOpts.timeout = timeout;
 
   // Substitute the absolute `wheels` path resolved at module load.
-  // Workers inherit default env from the parent; the resolved path
-  // sidesteps PATH lookup fragility inside test-runner workers. On
-  // Linuxbrew + node --test workers, spawn ALSO ENOENTs on absolute
-  // paths including /bin/bash (Node 22 test-runner posix_spawn quirk
-  // we couldn't pin down). The main verify-docs run works — only the
-  // harness unit tests hit this; those are soft-failed in CI.
+  // Belt-and-braces: also protects against shells where PATH doesn't
+  // include the homebrew bin dir (e.g., a test runner spawned from a
+  // stripped env). The separate "spawn PROGRAM ENOENT" failures we
+  // used to see under node --test were not a Node bug — they came
+  // from spawning with a cwd that no longer existed because
+  // `wheels new` exited 0 despite a framework-not-found error. See
+  // fixtures.mjs `createFixture` for the guard.
   const resolvedProgram = program === 'wheels' ? RESOLVED_WHEELS : program;
 
   return new Promise((resolve) => {

web/sites/guides/scripts/verify-docs/lib/fixtures.mjs

@@ -1,4 +1,4 @@
-import { mkdtemp, rm } from 'node:fs/promises';
+import { mkdtemp, rm, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { runExec } from './exec.mjs';
@@ -39,7 +39,28 @@ export async function createFixture(name = 'fixture') {
       ['new', name, '--no-open-browser'],
       { cwd: parent },
     );
-    if (result.code === 0) return join(parent, name);
+    const expected = join(parent, name);
+    if (result.code === 0) {
+      // `wheels new` can exit 0 even when framework lookup fails (it prints
+      // an error, cleans up the partial scaffold, and still returns 0). If
+      // we don't catch that here, downstream spawns run with cwd=<missing>
+      // and Node surfaces misleading "spawn PROGRAM ENOENT" errors that
+      // point at the executable instead of the cwd. See #2178.
+      try {
+        await stat(expected);
+      } catch {
+        await rm(parent, { recursive: true, force: true });
+        throw new Error(
+          `wheels new reported success (exit 0) but did not create ${expected}.\n` +
+          `Likely cause: the wheels CLI could not locate the framework source. ` +
+          `Set WHEELS_FRAMEWORK_PATH to a vendor/wheels/ directory (e.g., the ` +
+          `wheels repo checkout) before running the harness.\n` +
+          `--- wheels stderr ---\n${result.stderr || ''}\n` +
+          `--- wheels stdout ---\n${result.stdout || ''}`,
+        );
+      }
+      return expected;
+    }
     await rm(parent, { recursive: true, force: true });
     const combined = `${result.stderr || ''}${result.stdout || ''}`;
     const transient = TRANSIENT_PATTERNS.some((p) => p.test(combined));