Add experimental demo fleet control plane

Author: justin808

.github/workflows/demo-fleet-ci.yml

@@ -0,0 +1,27 @@
+name: Demo Fleet CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+
+      - name: Run lint
+        run: bundle exec rubocop lib/demo_fleet.rb lib/demo_fleet script test/demo_fleet_test.rb Rakefile
+
+      - name: Run tests
+        run: ruby -Ilib test/demo_fleet_test.rb
+
+      - name: Validate manifest
+        run: script/demo-fleet validate --manifest test/fixtures/demo-fleet.yml

.github/workflows/demo-fleet-freshness.yml

@@ -0,0 +1,25 @@
+name: Demo Fleet Freshness Plan
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '17 10 * * 1'
+
+permissions:
+  contents: read
+
+jobs:
+  plan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+
+      - name: Validate manifest
+        run: script/demo-fleet validate
+
+      - name: Render freshness update plan
+        run: script/demo-fleet update-plan --track freshness >> "$GITHUB_STEP_SUMMARY"

.github/workflows/demo-fleet-release-plan.yml

@@ -0,0 +1,108 @@
+name: Demo Fleet Release Plan
+
+on:
+  workflow_dispatch:
+    inputs:
+      react_on_rails:
+        description: React on Rails gem version
+        required: true
+      react_on_rails_pro:
+        description: React on Rails Pro gem version
+        required: true
+      react_on_rails_npm:
+        description: react-on-rails npm version
+        required: true
+      react_on_rails_pro_npm:
+        description: react-on-rails-pro npm version
+        required: true
+      react_on_rails_pro_node_renderer_npm:
+        description: react-on-rails-pro-node-renderer npm version
+        required: true
+      react_on_rails_rsc_npm:
+        description: react-on-rails-rsc npm version
+        required: true
+      shakapacker:
+        description: Optional ShakaPacker gem version
+        required: false
+      shakapacker_npm:
+        description: Optional ShakaPacker npm version
+        required: false
+      shakapacker_rspack_npm:
+        description: Optional shakapacker-rspack npm version
+        required: false
+      cpflow:
+        description: Optional CPFlow gem version
+        required: false
+      tier:
+        description: Optional tier filter, such as hard_gate
+        required: false
+      repo:
+        description: Optional repo id filter, such as react-on-rails-demo-marketplace-rsc
+        required: false
+
+permissions:
+  contents: read
+
+jobs:
+  plan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+
+      - name: Validate manifest
+        run: script/demo-fleet validate
+
+      - name: Dry-run release update plan
+        env:
+          REACT_ON_RAILS_GEM: ${{ inputs.react_on_rails }}
+          REACT_ON_RAILS_PRO_GEM: ${{ inputs.react_on_rails_pro }}
+          REACT_ON_RAILS_NPM: ${{ inputs.react_on_rails_npm }}
+          REACT_ON_RAILS_PRO_NPM: ${{ inputs.react_on_rails_pro_npm }}
+          REACT_ON_RAILS_PRO_NODE_RENDERER_NPM: ${{ inputs.react_on_rails_pro_node_renderer_npm }}
+          REACT_ON_RAILS_RSC_NPM: ${{ inputs.react_on_rails_rsc_npm }}
+          SHAKAPACKER_GEM: ${{ inputs.shakapacker }}
+          SHAKAPACKER_NPM: ${{ inputs.shakapacker_npm }}
+          SHAKAPACKER_RSPACK_NPM: ${{ inputs.shakapacker_rspack_npm }}
+          CPFLOW_GEM: ${{ inputs.cpflow }}
+          TIER: ${{ inputs.tier }}
+          REPO: ${{ inputs.repo }}
+        run: |
+          args=(
+            --track release
+            --gem "react_on_rails=$REACT_ON_RAILS_GEM"
+            --gem "react_on_rails_pro=$REACT_ON_RAILS_PRO_GEM"
+            --npm "react-on-rails=$REACT_ON_RAILS_NPM"
+            --npm "react-on-rails-pro=$REACT_ON_RAILS_PRO_NPM"
+            --npm "react-on-rails-pro-node-renderer=$REACT_ON_RAILS_PRO_NODE_RENDERER_NPM"
+            --npm "react-on-rails-rsc=$REACT_ON_RAILS_RSC_NPM"
+          )
+
+          if [[ -n "$SHAKAPACKER_GEM" ]]; then
+            args+=(--gem "shakapacker=$SHAKAPACKER_GEM")
+          fi
+
+          if [[ -n "$SHAKAPACKER_NPM" ]]; then
+            args+=(--npm "shakapacker=$SHAKAPACKER_NPM")
+          fi
+
+          if [[ -n "$SHAKAPACKER_RSPACK_NPM" ]]; then
+            args+=(--npm "shakapacker-rspack=$SHAKAPACKER_RSPACK_NPM")
+          fi
+
+          if [[ -n "$CPFLOW_GEM" ]]; then
+            args+=(--gem "cpflow=$CPFLOW_GEM")
+          fi
+
+          if [[ -n "$TIER" ]]; then
+            args+=(--tier "$TIER")
+          fi
+
+          if [[ -n "$REPO" ]]; then
+            args+=(--repo "$REPO")
+          fi
+
+          script/demo-fleet execute-plan --dry-run "${args[@]}" >> "$GITHUB_STEP_SUMMARY"

.rubocop.yml

@@ -9,9 +9,9 @@ AllCops:
   TargetRubyVersion: 3.1
   Exclude:
     - 'node_modules/**/*'
-    - 'demos/**/*'  # Each demo has its own Gemfile and rubocop config
+    - 'demos/**/*' # Each demo has its own Gemfile and rubocop config
     - 'packages/shakacode_demo_common/node_modules/**/*'
-    - 'bin/conductor-exec'  # Shell script, not Ruby
+    - 'bin/conductor-exec' # Shell script, not Ruby
 
 # Allow longer blocks in specs, Rakefiles, and bin scripts
 Metrics/BlockLength:
@@ -22,29 +22,49 @@ Metrics/BlockLength:
     - '**/Rakefile'
     - 'packages/shakacode_demo_common/lib/tasks/**/*.rake'
     - 'bin/*'
+    - 'test/**/*_test.rb'
 
 # Allow longer methods in demo creation (complex setup)
 Metrics/MethodLength:
   Max: 20
+  AllowedMethods:
+    - split_ruby_arguments
   Exclude:
     - 'lib/demo_scripts/demo_creator.rb'
     - 'lib/demo_scripts/demo_scaffolder.rb'
+    - 'lib/demo_fleet/cli.rb'
+    - 'lib/demo_fleet/update_planner.rb'
+    - 'test/**/*_test.rb'
 
 # Allow longer classes for demo creators and bin scripts (lots of setup code)
 Metrics/ClassLength:
   Max: 300
   Exclude:
     - 'bin/*'
+    - 'test/**/*_test.rb'
 
 # Allow more complex methods for demo scaffolding
 Metrics/AbcSize:
   Max: 25
+  AllowedMethods:
+    - split_ruby_arguments
+  Exclude:
+    - 'lib/demo_fleet/cli.rb'
+    - 'lib/demo_fleet/executor.rb'
+    - 'lib/demo_fleet/update_planner.rb'
+    - 'test/**/*_test.rb'
 
 Metrics/CyclomaticComplexity:
   Max: 10
+  AllowedMethods:
+    - split_ruby_arguments
+  Exclude:
+    - 'test/**/*_test.rb'
 
 Metrics/PerceivedComplexity:
   Max: 12
+  AllowedMethods:
+    - split_ruby_arguments
 
 # Allow more parameters for demo scaffolder (lots of options)
 Metrics/ParameterLists:

README.md

@@ -66,6 +66,48 @@ npm run format:check
 
 See [Development Setup](./docs/CONTRIBUTING_SETUP.md) for details.
 
+## Cross-Repository Demo Fleet
+
+This repository also hosts the experimental runtime for planning dependency updates across the
+ShakaCode demo fleet. Release policy, the fleet inventory, RC prompts, and the final go/no-go
+decision remain authoritative in
+[`shakacode/react_on_rails`](https://github.com/shakacode/react_on_rails/tree/main/internal/contributor-info).
+The runtime reads that canonical manifest directly instead of maintaining a second fleet list.
+
+```bash
+# Validate the current canonical manifest.
+script/demo-fleet validate
+
+# Render a non-mutating plan for one published release.
+script/demo-fleet execute-plan \
+  --track release \
+  --dry-run \
+  --gem react_on_rails=17.0.0.rc.10 \
+  --gem react_on_rails_pro=17.0.0.rc.10 \
+  --npm react-on-rails=17.0.0-rc.10 \
+  --npm react-on-rails-pro=17.0.0-rc.10 \
+  --npm react-on-rails-pro-node-renderer=17.0.0-rc.10 \
+  --npm react-on-rails-rsc=19.2.1-rc.1
+```
+
+Entries marked `verify: true` in the canonical manifest are deliberately excluded from plans. At
+the time this pilot was added, all canonical entries were still pending that one-time verification,
+so execution refuses to run until the release-policy owner confirms the metadata, including the
+review-app name, and clears those flags. This makes stale or placeholder metadata visible without
+turning it into repository mutations.
+
+The release updater handles direct npm declarations in nested applications, runs installs beside
+each changed manifest, and permits missing targets only when a repo explicitly marks them as
+transitive-only. It rejects tracked, staged, or untracked output outside dependency manifests,
+lockfiles, Yarn Berry dependency artifacts, and the verification script.
+
+Use `--manifest PATH_OR_URL` or `DEMO_FLEET_MANIFEST` to test an unmerged manifest change. Remote
+mutation is opt-in: `execute-plan` requires both `--execute --workspace PATH`, and it only pushes
+branches or opens draft PRs when `--allow-remote-prs` is also present.
+
+See the [control-plane notes](./docs/demo-fleet-control-plane-design.md) for the ownership boundary,
+current limitations, and verification commands.
+
 ### Bootstrap All Demos
 
 ```bash

Rakefile

@@ -7,7 +7,12 @@ require 'rubocop/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new
 
+desc 'Run demo fleet control-plane tests'
+task :demo_fleet_test do
+  ruby '-Ilib', 'test/demo_fleet_test.rb'
+end
+
 task default: %i[spec rubocop]
 
 desc 'Run all tests and linting'
-task test: :default
+task test: %i[default demo_fleet_test]

docs/demo-fleet-control-plane-design.md

@@ -0,0 +1,68 @@
+# Demo Fleet Control Plane
+
+## Ownership
+
+The control plane has a deliberately split ownership model:
+
+1. [`shakacode/react_on_rails`](https://github.com/shakacode/react_on_rails/tree/main/internal/contributor-info)
+   owns release policy, the canonical `demo-fleet.yml`, RC prompts, tracking issues, and final
+   release decisions.
+2. This repository owns reusable runtime mechanics: parsing the canonical manifest, rendering
+   deterministic plans, applying exact versions, bounded parallel execution, and opt-in PR setup.
+3. Each demo repository owns its tests, build, review-app deployment, smoke behavior, and any
+   repository-specific upgrade work.
+
+The runtime defaults to the manifest on `react_on_rails/main`. A release manager can pass
+`--manifest PATH_OR_URL` (or set `DEMO_FLEET_MANIFEST`) to exercise an unmerged policy change. This
+keeps one inventory and prevents an operational snapshot here from silently drifting.
+
+The canonical manifest's `verify: true` marker means an entry is still a draft. Such entries are
+reported by `validate` but excluded from actionable plans. `execute-plan --dry-run` reports an empty
+selection successfully for hosted planning, while mutating execution refuses an empty selection,
+and an entry cannot become actionable until `review_app.cpflow_app_name` is present unless it
+explicitly sets `review_app: null` to opt out. The exact-version updater fails if a requested gem is
+absent from the checkout's root `Gemfile`. For npm, it searches
+bounded repository manifests (excluding dependency, cache, and generated directories), updates every
+direct declaration, and only permits a missing declaration when that package is named in the repo's
+`transitive_only_npm_packages`. Installs run in each directory whose `package.json` changed, which
+covers split layouts such as HiChee's root and `client` applications.
+
+Pro-only apps are a bounded exception: directly declaring the Pro gem or npm package satisfies the
+corresponding base React on Rails target because Pro depends on it. Other absent targets still fail
+closed unless the canonical manifest marks them as transitive-only.
+
+## Safety Boundary
+
+`update-plan` and `execute-plan --dry-run` do not mutate demo repositories. The pilot executor
+requires an explicit workspace for mutations. It commits local changes but does not push or open a
+draft PR unless `--allow-remote-prs` is supplied.
+
+Mutating runs require an authenticated GitHub CLI. Fresh checkouts use its configured Git protocol
+so the same path works for public and private fleet repositories and later pushes retain that
+authenticated remote.
+
+The executor starts from a clean checkout, stages dependency manifests and lockfiles at any depth,
+plus Yarn Berry PnP/cache artifacts, and rejects tracked, staged, or untracked changes outside that
+allowlist. Verification-generated drift therefore fails the lane instead of being silently included
+or left behind.
+
+Freshness is plan-only in this pilot. The CLI rejects `--track freshness --execute` until it can
+resolve registry candidates and enforce the canonical minimum-age policy before changing a repo.
+Release-track execution remains available for explicitly supplied React on Rails package versions.
+
+The executor is not yet a release gate. It does not poll hosted CI, discover CPFlow review-app
+URLs, run behavioral browser smoke, update the tracking issue, or make a go/no-go decision. Those
+steps remain in the canonical React on Rails release process and its copy/paste batch prompts.
+
+## Verification
+
+```bash
+ruby -Ilib test/demo_fleet_test.rb
+script/demo-fleet validate
+script/demo-fleet update-plan --track freshness
+```
+
+The Ruby runtime uses only the standard library. The default manifest validation requires network
+access; tests pass local temporary manifests and are deterministic. When every canonical entry is
+still pending verification, hosted dry-runs report an intentionally empty plan and mutating execution
+refuses to run it.

docs/prompts/demo-fleet-update-agent.md

@@ -0,0 +1,10 @@
+# Demo Fleet Agent Prompts
+
+Copy/paste release prompts live with the release policy in the canonical
+[`RC Testing Plan`](https://github.com/shakacode/react_on_rails/blob/main/internal/contributor-info/rc-testing-plan.md).
+They are filled with exact release versions, tag and commit evidence, tracking issue, owned lanes,
+model routing, privacy constraints, and merge authority.
+
+Do not keep a release prompt template in this repository. A generic placeholder prompt is too easy
+to launch with stale versions or the wrong fleet snapshot. Use this runtime to render a mechanical
+plan, then use the current release's filled prompt from `react_on_rails` to coordinate the work.