Merge remote-tracking branch 'origin/main' into codex/pr-3231-reviews

* origin/main:
  fix(pro-dummy): make manual node-renderer validation reliable (#3200)
  [codex] Add Markdown Prettier CI check (#3242)
  Add /stress-test Claude Code command for adversarial QA (#3207)

Author: justin808

.claude/commands/stress-test.md

@@ -2,7 +2,7 @@
 
 Automated tests can pass while the development environment is completely broken. CI starts services explicitly and runs in a controlled environment — it does not exercise `bin/dev`, Procfile orchestration, or the actual browser experience. This guide ensures agents verify the dev environment works end-to-end before submitting a PR.
 
-**Related:** [PR Testing Guide](pr-testing-guide.md), [Testing Build Scripts](testing-build-scripts.md)
+**Related:** [PR Testing Guide](pr-testing-guide.md), [Testing Build Scripts](testing-build-scripts.md), [Validating Node Renderer Changes](validating-node-renderer-changes.md)
 
 ## The Rule
 

.claude/docs/manual-dev-environment-testing.md

@@ -0,0 +1,132 @@
+# Validating Node Renderer Changes
+
+Manual validation checklist for changes under `packages/react-on-rails-pro-node-renderer/src/**`.
+
+**Why this exists:** the Pro dummy app consumes the _built_ renderer at
+`packages/react-on-rails-pro-node-renderer/lib/**`. Editing TypeScript under `src/` does
+nothing until that lib output is regenerated, so a correct fix can look broken (or worse,
+a regression can look fine because the dummy is still running stale lib output).
+
+**Related:** [Manual Dev Environment Testing](manual-dev-environment-testing.md)
+
+## When This Applies
+
+If your PR touches **any** of these, run through the checklist below:
+
+- `packages/react-on-rails-pro-node-renderer/src/**`
+- `packages/react-on-rails-pro-node-renderer/package.json` (especially `protocolVersion`,
+  `exports`, or runtime dependencies)
+- Any worker pool, JWT auth, integrations (Sentry/Honeybadger), or VM-context code in the
+  renderer
+
+## Pre-flight: Toolchain
+
+Ruby 3.3.x is the documented baseline for the Pro dummy app, and this workflow
+has also been verified on Ruby 3.4.8. On Ruby 3.5+, the dummy's Gemfile pulls in
+`ostruct`, `logger`, and `benchmark` as explicit gems for stdlib compatibility.
+If a newer Ruby hits unrelated incompatibilities, fall back to the documented
+Ruby version.
+
+```bash
+cd react_on_rails_pro/spec/dummy
+bundle install
+
+# Optional fallback if your local Ruby fails:
+mise shell ruby@3.3.7  # or rbenv/asdf equivalent
+bundle install
+```
+
+## Step 1: Rebuild the Renderer Package
+
+Pick **one** of these depending on how you plan to iterate:
+
+**One-shot rebuild (recommended for a single validation pass):**
+
+```bash
+pnpm --filter react-on-rails-pro-node-renderer run build
+```
+
+**Or use the dummy's convenience script:**
+
+```bash
+cd react_on_rails_pro/spec/dummy
+pnpm run node-renderer:fresh   # builds, then starts the renderer standalone
+```
+
+This starts the renderer in the foreground on port 3800. For a full-stack dummy
+run, either stop it before Step 2 and let `bin/dev` start the renderer, or leave
+it running and comment out the `node-renderer:` line in `Procfile.dev` before
+running `bin/dev`.
+
+**Watch mode (recommended when iterating on the renderer source):**
+
+Either uncomment the `node-renderer-build` line in `react_on_rails_pro/spec/dummy/Procfile.dev`,
+or in a separate terminal run:
+
+```bash
+pnpm --filter react-on-rails-pro-node-renderer run build-watch
+```
+
+> If you skip this step, the dummy app will silently keep using the previous lib build.
+> Symptoms: a fix you just applied does not change behavior, or a regression you expected
+> to see does not appear.
+
+## Step 2: Start the Dummy App
+
+```bash
+cd react_on_rails_pro/spec/dummy
+bin/dev
+```
+
+Verify:
+
+- [ ] `bin/dev` starts without `overlay.sockPort should be a number` (webpack-dev-server)
+- [ ] `bin/dev` starts without `cannot load such file -- ostruct` (Rails precompile)
+- [ ] All Procfile.dev processes are healthy after 30 seconds
+- [ ] The `node-renderer` process logs that it bound to port 3800
+
+## Step 3: Exercise the SSR Endpoints
+
+For PRs touching streaming, hydration, RSC, or VM-context code, hit the routes that
+actually exercise the renderer (not just static pages):
+
+- [ ] `http://localhost:3000/stream_native_metadata` — renders without `ReferenceError`
+      (e.g. `performance is not defined`) in the renderer logs
+- [ ] `http://localhost:3000/hybrid_metadata_streaming` — same
+- [ ] Any route specifically related to your change
+
+For each route:
+
+- [ ] Page returns 200 and renders SSR content (view-source shows component markup)
+- [ ] No errors in the `node-renderer` Procfile pane
+- [ ] No errors in the Rails server log
+- [ ] No errors in the browser console
+
+## Step 4: Confirm You Tested the New Code
+
+It is easy to validate stale lib output without realizing it. Confirm:
+
+- [ ] The built `lib/` file corresponding to your edit is newer than the `src/`
+      file you changed. Compare the specific files with `stat` or use a
+      per-file freshness check, for example:
+      `find packages/react-on-rails-pro-node-renderer/lib -newer packages/react-on-rails-pro-node-renderer/src/<changed-file>.ts | head`
+- [ ] If you used watch mode, you saw a rebuild line in the watcher output after your
+      most recent edit
+- [ ] Restart the `node-renderer` Procfile process after the rebuild — `node` does not
+      hot-reload required modules
+
+## Reporting Results in the PR
+
+```markdown
+## Node Renderer Validation
+
+- [x] Rebuilt `react-on-rails-pro-node-renderer` package
+- [x] Verified the rebuilt `lib/` file is newer than the changed `src/` file
+- [x] `bin/dev` starts cleanly
+- [x] `/stream_native_metadata` renders without errors
+- [x] `/hybrid_metadata_streaming` renders without errors
+- [x] No errors in node-renderer logs
+```
+
+If you cannot validate manually (e.g. no local Ruby toolchain), say so explicitly and
+note that the change is type-checked / unit-tested only.

.claude/docs/validating-node-renderer-changes.md

@@ -10,18 +10,60 @@ on:
       - '**.md'
       - '.github/workflows/check-markdown-links.yml'
       - '.lychee.toml'
+      - '.prettierignore'
+      - '.prettierrc'
+      - 'pnpm-lock.yaml'
   pull_request:
     paths:
       - '**.md'
       - '.github/workflows/check-markdown-links.yml'
       - '.lychee.toml'
+      - '.prettierignore'
+      - '.prettierrc'
+      - 'pnpm-lock.yaml'
   schedule:
     # Run daily at 3am UTC to catch stale cached links
     # See: https://lychee.cli.rs/github_action_recipes/caching/
     - cron: '0 3 * * *'
   workflow_dispatch:
 
 jobs:
+  markdown-format-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: ./.github/actions/setup-node-with-retry
+        with:
+          # Pin to 22.11.0 (LTS) to avoid V8 bug in 22.21.0
+          node-version: '22.11.0'
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --ignore-scripts --filter='{.}'
+
+      - name: Check markdown formatting
+        shell: bash
+        run: |
+          markdown_files=()
+          while IFS= read -r -d '' file; do
+            if [ -f "$file" ] && [ ! -L "$file" ]; then
+              markdown_files+=("$file")
+            fi
+          done < <(git ls-files -z -- '*.md' '*.mdx' '*.markdown')
+
+          if [ "${#markdown_files[@]}" -eq 0 ]; then
+            echo "No markdown files to check."
+            exit 0
+          fi
+
+          pnpm exec prettier --check -- "${markdown_files[@]}"
+
   markdown-link-check:
     runs-on: ubuntu-latest
     steps:

.github/workflows/check-markdown-links.yml

@@ -45,5 +45,6 @@ Use these docs for Claude-oriented operational guidance:
 - `.claude/docs/docs-competitive-landscape.md`
 - `.claude/docs/docs-templates.md`
 - `.claude/docs/manual-dev-environment-testing.md`
+- `.claude/docs/validating-node-renderer-changes.md`
 
 For Pro-package specifics, also read `react_on_rails_pro/CLAUDE.md`.

CLAUDE.md

@@ -14,7 +14,7 @@ It is a `pnpm` workspace app and already points at the local packages in this mo
 
 ### Quick start: debugging with the full stack running
 
-If you already have the dummy app running via `bin/dev` (which uses `Procfile.dev`), the node renderer is already listening on port 3800 with `--inspect` enabled. To debug:
+If you already have the dummy app running via `bin/dev` (which uses `Procfile.dev`), the node renderer is listening on port 3800 but without `--inspect`. To attach a debugger you first need to restart it with `--inspect` — either stop the renderer process and run `pnpm run node-renderer:debug`, or temporarily add `--inspect` to the `node-renderer:` entry in `Procfile.dev` and `overmind restart node-renderer`. Then:
 
 1. Open `chrome://inspect` in Chrome and connect to the renderer process.
 2. Use overmind to isolate renderer logs: `overmind connect node-renderer` (Ctrl-B to detach).
@@ -42,7 +42,7 @@ Use this when you need full control over the renderer process — different flag
 1. If you want to attach a debugger instead, run:
    ```bash
    cd react_on_rails_pro/spec/dummy
-   pnpm run node-renderer-debug
+   pnpm run node-renderer:debug
    ```
 1. Reload the page that triggers the SSR issue and reproduce the problem.
 1. If you change Ruby code in loaded gems, restart the Rails server.

docs/oss/building-features/node-renderer/debugging.md

@@ -58,6 +58,16 @@ The node renderer is a standalone Fastify HTTP server (separate Node.js process)
 - Integrations: Sentry, Honeybadger (optional peer deps)
 - Protocol versioning: `protocolVersion` in package.json must match gem expectations
 
+**Validating source changes against the dummy app:** the dummy consumes the _built_
+`packages/react-on-rails-pro-node-renderer/lib/**`, so edits under `src/**` are not
+picked up until the package is rebuilt. Use one of:
+
+- `pnpm --filter react-on-rails-pro-node-renderer run build` (one-shot)
+- `cd react_on_rails_pro/spec/dummy && pnpm run node-renderer:fresh` (rebuild + start)
+- `pnpm --filter react-on-rails-pro-node-renderer run build-watch` (watch in another shell)
+
+See `.claude/docs/validating-node-renderer-changes.md` for the full checklist.
+
 ### Yalc Dependency Chain
 
 Pro dummy's preinstall builds and links packages in this order:

react_on_rails_pro/CLAUDE.md

@@ -54,6 +54,12 @@ group :development, :test do
   gem "rbs", require: false
   gem "scss_lint", require: false
   gem "fakefs", require: "fakefs/safe"
+
+  # Ruby 3.5+ removed these from the default gem set; they must now be declared explicitly
+  # to avoid `cannot load such file` errors from gems that lazy-require them (e.g. jbuilder).
+  gem "benchmark", require: false
+  gem "logger", require: false
+  gem "ostruct", require: false
 end
 
 group :test do

react_on_rails_pro/Gemfile.development_dependencies

@@ -247,6 +247,7 @@ GEM
       racc (~> 1.4)
     nokogiri (1.19.2-x86_64-linux-gnu)
       racc (~> 1.4)
+    ostruct (0.6.3)
     package_json (0.2.0)
     parallel (1.27.0)
     parser (3.3.10.0)
@@ -475,6 +476,7 @@ PLATFORMS
 
 DEPENDENCIES
   amazing_print
+  benchmark
   bootsnap
   bundler
   capybara (>= 3.38.0)
@@ -490,9 +492,11 @@ DEPENDENCIES
   jquery-rails
   launchy
   listen
+  logger
   net-http
   net-imap
   net-smtp
+  ostruct
   pg
   pry (>= 0.14.1)
   pry-byebug!

react_on_rails_pro/Gemfile.lock

@@ -271,6 +271,7 @@ GEM
       racc (~> 1.4)
     nokogiri (1.19.2-x86_64-linux-musl)
       racc (~> 1.4)
+    ostruct (0.6.3)
     package_json (0.2.0)
     parallel (1.27.0)
     parser (3.3.10.0)
@@ -524,6 +525,7 @@ PLATFORMS
 
 DEPENDENCIES
   amazing_print
+  benchmark
   bootsnap
   capybara (>= 3.38.0)
   capybara-screenshot
@@ -538,9 +540,11 @@ DEPENDENCIES
   jquery-rails
   launchy
   listen
+  logger
   net-http
   net-imap
   net-smtp
+  ostruct
   pg
   prism-rails
   pry (>= 0.14.1)