RubyGems - ruact - Versions diffs - 0.0.4 → 0.0.6 - Mend

ruact 0.0.4 → 0.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (132) hide show

checksums.yaml +4 -4
data/.github/workflows/ci.yml +54 -2
data/.rubocop_todo.yml +3 -115
data/CHANGELOG.md +68 -17
data/bench/server_functions_dispatch_bench.rb +109 -142
data/bench/server_functions_dispatch_bench.results.md +29 -0
data/docs/internal/decisions/server-functions-api.md +402 -0
data/lib/generators/ruact/install/install_generator.rb +310 -25
data/lib/generators/ruact/install/templates/Procfile.dev.tt +2 -0
data/lib/generators/ruact/install/templates/dev.tt +16 -0
data/lib/generators/ruact/install/templates/package.json.tt +17 -0
data/lib/generators/ruact/install/templates/vite.config.js.tt +3 -1
data/lib/generators/ruact/scaffold/scaffold_attribute.rb +114 -0
data/lib/generators/ruact/scaffold/scaffold_form_helpers.rb +114 -0
data/lib/generators/ruact/scaffold/scaffold_generator.rb +491 -0
data/lib/generators/ruact/scaffold/scaffold_shadcn_preflight.rb +229 -0
data/lib/generators/ruact/scaffold/templates/components/DeleteDialog.tsx.tt +104 -0
data/lib/generators/ruact/scaffold/templates/components/Form.tsx.tt +212 -0
data/lib/generators/ruact/scaffold/templates/components/List.tsx.tt +338 -0
data/lib/generators/ruact/scaffold/templates/components/agnostic/DeleteDialog.tsx.tt +92 -0
data/lib/generators/ruact/scaffold/templates/components/agnostic/Form.tsx.tt +174 -0
data/lib/generators/ruact/scaffold/templates/components/agnostic/List.tsx.tt +253 -0
data/lib/generators/ruact/scaffold/templates/controller.rb.tt +130 -0
data/lib/generators/ruact/scaffold/templates/queries/application_query.rb.tt +13 -0
data/lib/generators/ruact/scaffold/templates/queries/query.rb.tt +59 -0
data/lib/generators/ruact/scaffold/templates/request_spec.rb.tt +77 -0
data/lib/generators/ruact/scaffold/templates/views/edit.html.erb.tt +7 -0
data/lib/generators/ruact/scaffold/templates/views/index.html.erb.tt +6 -0
data/lib/generators/ruact/scaffold/templates/views/new.html.erb.tt +5 -0
data/lib/generators/ruact/scaffold/templates/views/show.html.erb.tt +16 -0
data/lib/ruact/client_manifest.rb +37 -36
data/lib/ruact/component_contract.rb +115 -0
data/lib/ruact/configuration.rb +80 -28
data/lib/ruact/controller.rb +69 -421
data/lib/ruact/doctor.rb +133 -4
data/lib/ruact/erb_preprocessor.rb +65 -12
data/lib/ruact/erb_preprocessor_hook.rb +4 -1
data/lib/ruact/errors.rb +30 -44
data/lib/ruact/html_converter.rb +22 -1
data/lib/ruact/railtie.rb +56 -200
data/lib/ruact/server.rb +28 -6
data/lib/ruact/server_functions/codegen.rb +49 -188
data/lib/ruact/server_functions/codegen_v2.rb +23 -6
data/lib/ruact/server_functions/codegen_v2_query_params.rb +140 -0
data/lib/ruact/server_functions/error_payload.rb +1 -1
data/lib/ruact/server_functions/error_rendering.rb +22 -29
data/lib/ruact/server_functions/name_bridge.rb +14 -16
data/lib/ruact/server_functions/query_source.rb +35 -8
data/lib/ruact/server_functions/route_source.rb +3 -4
data/lib/ruact/server_functions/snapshot.rb +12 -139
data/lib/ruact/server_functions/validation_errors.rb +70 -0
data/lib/ruact/server_functions.rb +21 -25
data/lib/ruact/signed_references.rb +162 -0
data/lib/ruact/string_distance.rb +72 -0
data/lib/ruact/validation_errors_collector.rb +139 -0
data/lib/ruact/version.rb +1 -1
data/lib/ruact/view_helper.rb +102 -0
data/lib/ruact.rb +19 -19
data/lib/tasks/ruact.rake +10 -53
data/spec/fixtures/story_7_9_views/controller_request_spec_support/errors_demo/new.html.erb +3 -0
data/spec/ruact/client_manifest_spec.rb +36 -0
data/spec/ruact/component_contract_spec.rb +119 -0
data/spec/ruact/configuration_spec.rb +51 -34
data/spec/ruact/controller_request_spec.rb +264 -0
data/spec/ruact/controller_spec.rb +63 -326
data/spec/ruact/doctor_spec.rb +201 -0
data/spec/ruact/erb_preprocessor_hook_spec.rb +4 -1
data/spec/ruact/erb_preprocessor_spec.rb +127 -0
data/spec/ruact/errors_spec.rb +0 -45
data/spec/ruact/html_converter_spec.rb +50 -0
data/spec/ruact/install_generator_spec.rb +591 -4
data/spec/ruact/query_request_spec.rb +109 -1
data/spec/ruact/scaffold_generator_spec.rb +1835 -0
data/spec/ruact/server_bucket_request_spec.rb +142 -0
data/spec/ruact/server_function_name_spec.rb +1 -1
data/spec/ruact/server_functions/codegen_spec.rb +158 -269
data/spec/ruact/server_functions/name_bridge_spec.rb +9 -9
data/spec/ruact/server_functions/query_source_spec.rb +51 -0
data/spec/ruact/server_functions/railtie_integration_spec.rb +71 -268
data/spec/ruact/server_functions/rake_spec.rb +29 -29
data/spec/ruact/server_functions/snapshot_spec.rb +53 -213
data/spec/ruact/server_rescue_request_spec.rb +6 -6
data/spec/ruact/server_spec.rb +8 -9
data/spec/ruact/signed_references_spec.rb +164 -0
data/spec/ruact/string_distance_spec.rb +38 -0
data/spec/ruact/validation_errors_spec.rb +116 -0
data/spec/ruact/view_helper_spec.rb +79 -0
data/spec/spec_helper.rb +0 -5
data/vendor/javascript/ruact-server-functions-runtime/index.d.ts +44 -47
data/vendor/javascript/ruact-server-functions-runtime/index.js +151 -107
data/vendor/javascript/ruact-server-functions-runtime/index.test.mjs +72 -75
data/vendor/javascript/ruact-server-functions-runtime/package.json +2 -2
data/vendor/javascript/ruact-server-functions-runtime/usequery.test.mjs +187 -0
data/vendor/javascript/vite-plugin-ruact/bootstrap.test.mjs +96 -0
data/vendor/javascript/vite-plugin-ruact/index.js +353 -7
data/vendor/javascript/vite-plugin-ruact/manifest-contract.test.mjs +182 -0
data/vendor/javascript/vite-plugin-ruact/package-lock.json +16 -0
data/vendor/javascript/vite-plugin-ruact/package.json +3 -1
data/vendor/javascript/vite-plugin-ruact/registry.test.mjs +199 -0
data/vendor/javascript/vite-plugin-ruact/runtime/bootstrap.jsx +68 -0
data/vendor/javascript/vite-plugin-ruact/runtime/flight-client.js +235 -0
data/vendor/javascript/vite-plugin-ruact/runtime/ruact-router.js +473 -0
data/vendor/javascript/vite-plugin-ruact/server-functions-codegen.mjs +114 -139
data/vendor/javascript/vite-plugin-ruact/server-functions-codegen.test.mjs +199 -262
data/vendor/javascript/vite-plugin-ruact/tsconfig.json +18 -0
data/vendor/javascript/vite-plugin-ruact/tsconfig.scaffold-agnostic.json +18 -0
data/vendor/javascript/vite-plugin-ruact/tsconfig.scaffold.json +20 -0
data/vendor/javascript/vite-plugin-ruact/type-tests/emitted-module.test-d.ts +23 -0
data/vendor/javascript/vite-plugin-ruact/type-tests/scaffold/PostDeleteDialog.tsx +90 -0
data/vendor/javascript/vite-plugin-ruact/type-tests/scaffold/PostForm.tsx +238 -0
data/vendor/javascript/vite-plugin-ruact/type-tests/scaffold/PostList.tsx +339 -0
data/vendor/javascript/vite-plugin-ruact/type-tests/scaffold/agnostic/PostDeleteDialog.tsx +85 -0
data/vendor/javascript/vite-plugin-ruact/type-tests/scaffold/agnostic/PostForm.tsx +216 -0
data/vendor/javascript/vite-plugin-ruact/type-tests/scaffold/agnostic/PostList.tsx +269 -0
data/vendor/javascript/vite-plugin-ruact/type-tests/scaffold/agnostic/ambient.d.ts +78 -0
data/vendor/javascript/vite-plugin-ruact/type-tests/scaffold/ambient.d.ts +166 -0
data/vendor/javascript/vite-plugin-ruact/type-tests/typed-query.test-d.ts +48 -0
data/vendor/javascript/vite-plugin-ruact/type-tests/usequery.test-d.ts +26 -0
metadata +55 -15
data/lib/generators/ruact/install/templates/application.jsx.tt +0 -51
data/lib/ruact/server_action.rb +0 -131
data/lib/ruact/server_functions/endpoint_controller.rb +0 -237
data/lib/ruact/server_functions/registry.rb +0 -148
data/lib/ruact/server_functions/registry_entry.rb +0 -26
data/lib/ruact/server_functions/standalone_context.rb +0 -103
data/lib/ruact/server_functions/standalone_dispatcher.rb +0 -178
data/spec/ruact/server_functions/csrf_request_spec.rb +0 -380
data/spec/ruact/server_functions/dispatch_request_spec.rb +0 -819
data/spec/ruact/server_functions/registry_spec.rb +0 -199
data/spec/ruact/server_functions/standalone_action_spec.rb +0 -224
data/spec/ruact/server_functions/standalone_context_spec.rb +0 -142
data/spec/ruact/server_functions/standalone_dispatcher_spec.rb +0 -273

data/spec/ruact/install_generator_spec.rb CHANGED Viewed

@@ -3,6 +3,7 @@
 require "spec_helper"
 require "tmpdir"
 require "fileutils"
+require "json"
 require "ruact"
 RSpec.describe Ruact do # rubocop:disable RSpec/SpecFilePathFormat
@@ -215,8 +216,6 @@ RSpec.describe Ruact do # rubocop:disable RSpec/SpecFilePathFormat
       let(:gitignore_entries) do
         [
           "app/javascript/.ruact/server-functions.ts",
-          # Story 9.3 — route-driven (v2) parallel inspection target.
-          "app/javascript/.ruact/server-functions.next.ts",
           "tmp/cache/ruact/"
         ]
       end
@@ -263,8 +262,10 @@ RSpec.describe Ruact do # rubocop:disable RSpec/SpecFilePathFormat
         append_gitignore_entries(tmpdir)
         content = read_file(".gitignore")
         expect(content).to include("app/javascript/.ruact/server-functions.ts")
-        expect(content).to include("app/javascript/.ruact/server-functions.next.ts")
         expect(content).to include("tmp/cache/ruact/")
+        # Story 9.9 — the v1 parallel `.next` target was demolished; the
+        # generator must no longer scaffold its gitignore entry.
+        expect(content).not_to include("server-functions.next.ts")
       end
       it "is idempotent — running twice does not duplicate entries (Story 8.0a — pitfall #5)" do
@@ -279,7 +280,7 @@ RSpec.describe Ruact do # rubocop:disable RSpec/SpecFilePathFormat
       it "does not write to .gitignore when both entries already exist" do
         write_file(".gitignore", "/tmp\napp/javascript/.ruact/server-functions.ts\n" \
-                                 "app/javascript/.ruact/server-functions.next.ts\ntmp/cache/ruact/\n")
+                                 "tmp/cache/ruact/\n")
         result = append_gitignore_entries(tmpdir)
         expect(result).to eq(:already_present)
       end
@@ -301,5 +302,591 @@ RSpec.describe Ruact do # rubocop:disable RSpec/SpecFilePathFormat
         expect(content).to include("app/javascript/.ruact/server-functions.ts")
       end
     end
+    # REGRESSION (Sprint Change Proposal 2026-06-16 §4.5): a fresh `rails new`
+    # crashed `rails generate ruact:install` on Rails 8.1 / Thor because the
+    # generator called `destination_root.join(...)` — Thor returns
+    # `destination_root` as a String (`File.expand_path`), which has no
+    # path-style `#join`, so the installer raised `NoMethodError` before writing
+    # a single file. The fix wraps every site in `Pathname(destination_root)`.
+    #
+    # The "generator action helpers" tests above reimplement the file logic with
+    # `File.join`, so they never run Thor's path handling and masked the bug.
+    # These tests invoke the REAL generator against a String destination_root, so
+    # a revert of the Pathname fix fails loudly here.
+    describe "real generator invocation against a String destination_root" do
+      require "stringio"
+      require "generators/ruact/install/install_generator"
+      let(:app_root) { Dir.mktmpdir("ruact_install_real") }
+      after { FileUtils.rm_rf(app_root) }
+      def build_generator(root)
+        Ruact::Generators::InstallGenerator.new([], {}, destination_root: root)
+      end
+      def silently
+        original = $stdout
+        $stdout = StringIO.new
+        yield
+      ensure
+        $stdout = original
+      end
+      before do
+        FileUtils.mkdir_p(File.join(app_root, "app/controllers"))
+        File.write(File.join(app_root, "app/controllers/application_controller.rb"),
+                   "class ApplicationController < ActionController::Base\nend\n")
+        FileUtils.mkdir_p(File.join(app_root, "app/views/layouts"))
+        File.write(File.join(app_root, "app/views/layouts/application.html.erb"),
+                   "<!DOCTYPE html>\n<html>\n  <body>\n    <%= yield %>\n  </body>\n</html>\n")
+        File.write(File.join(app_root, ".gitignore"), "/log/*\n")
+      end
+      it "hands the generator a String destination_root (the exact crashing condition)" do
+        expect(build_generator(app_root).destination_root).to be_a(String)
+      end
+      it "runs every path-touching action without raising and writes the files", :aggregate_failures do
+        gen = build_generator(app_root)
+        silently do
+          expect do
+            gen.inject_controller_concern
+            gen.inject_layout_shell
+            gen.create_components_directory
+            gen.create_server_functions_directory
+            gen.append_gitignore_entries
+            gen.create_vite_config
+          end.not_to raise_error
+        end
+        expect(File.read(File.join(app_root, "app/controllers/application_controller.rb")))
+          .to include("include Ruact::Controller")
+        expect(File.read(File.join(app_root, "app/views/layouts/application.html.erb")))
+          .to include('<div id="root"></div>')
+        expect(File).to exist(File.join(app_root, "app/javascript/components/.keep"))
+        expect(File).to exist(File.join(app_root, "app/javascript/.ruact/.gitkeep"))
+        expect(File.read(File.join(app_root, ".gitignore")))
+          .to include("app/javascript/.ruact/server-functions.ts")
+        expect(File).to exist(File.join(app_root, "vite.config.js"))
+      end
+    end
+  end
+  # Story 14.1 (FR101) — one-command install: `ruact:install` now runs
+  # `npm install` by default (behind a stubbable `run_npm_install` seam),
+  # skippable via `--skip-npm`, with an npm-on-PATH guard and outcome-aware
+  # post-install messaging. The shell-out is ALWAYS stubbed here — no real
+  # npm / network call is made in CI. Reuses the "real generator against a
+  # String destination_root" pattern (instantiate + call action methods).
+  describe "install generator — one-command npm install (Story 14.1 — FR101)", :story_14_1 do
+    require "stringio"
+    require "generators/ruact/install/install_generator"
+    let(:app_root) { Dir.mktmpdir("ruact_install_npm") }
+    after { FileUtils.rm_rf(app_root) }
+    def build_generator(root, opts = {})
+      Ruact::Generators::InstallGenerator.new([], opts, destination_root: root)
+    end
+    def silently
+      original = $stdout
+      $stdout = StringIO.new
+      yield
+    ensure
+      $stdout = original
+    end
+    # Captures and returns the generator's say/say_status stdout for text asserts.
+    def capture_stdout
+      original = $stdout
+      $stdout = StringIO.new
+      yield
+      $stdout.string
+    ensure
+      $stdout = original
+    end
+    describe "--skip-npm class option (AC#2)", :aggregate_failures do
+      it "is registered as a boolean class_option defaulting to false" do
+        option = Ruact::Generators::InstallGenerator.class_options[:skip_npm]
+        expect(option).not_to be_nil
+        expect(option.type).to eq(:boolean)
+        expect(option.default).to be false
+      end
+    end
+    describe "default run installs JS deps (AC#1, AC#6a)" do
+      it "invokes the run_npm_install seam exactly once" do
+        gen = build_generator(app_root)
+        allow(gen).to receive_messages(npm_on_path?: true, run_npm_install: true)
+        silently { gen.install_javascript_dependencies }
+        expect(gen).to have_received(:run_npm_install).once
+        expect(gen.instance_variable_get(:@npm_outcome)).to eq(:installed)
+      end
+      it "runs the npm step AFTER the file-producing actions and BEFORE show_post_install_message",
+         :aggregate_failures do
+        # Thor runs public action methods in SOURCE definition order, so assert
+        # on source line numbers (public_instance_methods order is not
+        # guaranteed to match definition order). Story 14.2 removed
+        # create_javascript_entry; create_vite_config is the last file-writing
+        # action before the npm step.
+        klass = Ruact::Generators::InstallGenerator
+        line = ->(name) { klass.instance_method(name).source_location.last }
+        expect(line.call(:create_vite_config)).to be < line.call(:install_javascript_dependencies)
+        expect(line.call(:install_javascript_dependencies)).to be < line.call(:show_post_install_message)
+      end
+    end
+    describe "run_npm_install seam (AC#6a)", :aggregate_failures do
+      it "shells out `npm install` inside the destination_root" do
+        gen = build_generator(app_root)
+        allow(gen).to receive(:inside).and_yield
+        allow(gen).to receive(:run)
+        silently { gen.send(:run_npm_install) }
+        expect(gen).to have_received(:inside).with(gen.destination_root)
+        expect(gen).to have_received(:run).with("npm install")
+      end
+    end
+    describe "--skip-npm opts out (AC#2, AC#6b)" do
+      it "does not invoke the run_npm_install seam and emits a skip notice" do
+        gen = build_generator(app_root, { skip_npm: true })
+        allow(gen).to receive(:run_npm_install)
+        output = capture_stdout { gen.install_javascript_dependencies }
+        expect(gen).not_to have_received(:run_npm_install)
+        expect(output).to match(/skip/i)
+      end
+    end
+    describe "--pretend dry run", :aggregate_failures do
+      # Thor's `run` returns nil under --pretend (the command is previewed, not
+      # executed) — that must NOT be misread as an npm failure.
+      it "treats a pretend run as a no-op, not an npm failure" do
+        gen = build_generator(app_root, { pretend: true })
+        allow(gen).to receive_messages(npm_on_path?: true, run_npm_install: nil)
+        run_output = capture_stdout { gen.install_javascript_dependencies }
+        expect(gen.instance_variable_get(:@npm_outcome)).to eq(:pretend)
+        expect(run_output).not_to match(/did not complete|reported a failure/i)
+      end
+    end
+    describe "npm not on PATH (AC#5)", :aggregate_failures do
+      it "does not raise, skips the seam, and prints an actionable message naming --skip-npm" do
+        gen = build_generator(app_root)
+        allow(gen).to receive(:npm_on_path?).and_return(false)
+        allow(gen).to receive(:run_npm_install)
+        output = nil
+        expect { output = capture_stdout { gen.install_javascript_dependencies } }
+          .not_to raise_error
+        expect(gen).not_to have_received(:run_npm_install)
+        expect(output).to include("--skip-npm")
+        expect(output).to match(/npm/i)
+        expect(output).to match(/node/i)
+      end
+    end
+    describe "post-install message reflects the outcome (AC#3)", :aggregate_failures do
+      it "states deps are installed and next step is bin/dev when npm ran" do
+        gen = build_generator(app_root)
+        allow(gen).to receive_messages(npm_on_path?: true, run_npm_install: true)
+        silently { gen.install_javascript_dependencies }
+        output = capture_stdout { gen.show_post_install_message }
+        expect(output).to include("are installed")
+        expect(output).not_to include("not yet installed")
+        expect(output).to include("bin/dev")
+      end
+      # AC#3 — Thor's `run` returns false on a non-zero exit (generators do not
+      # exit_on_failure?), so a FAILED `npm install` must NOT report success.
+      it "does NOT claim deps are installed when npm install fails (AC#3)" do
+        gen = build_generator(app_root)
+        allow(gen).to receive_messages(npm_on_path?: true, run_npm_install: false)
+        run_output = capture_stdout { gen.install_javascript_dependencies }
+        message    = capture_stdout { gen.show_post_install_message }
+        expect(gen.instance_variable_get(:@npm_outcome)).to eq(:failed)
+        expect(run_output).to match(/did not complete|failure/i)
+        expect(message).not_to include("are installed")
+        expect(message).to include("not yet installed")
+        expect(message).to include("bin/dev")
+      end
+      it "tells the developer to install manually then bin/dev when skipped" do
+        gen = build_generator(app_root, { skip_npm: true })
+        silently { gen.install_javascript_dependencies }
+        output = capture_stdout { gen.show_post_install_message }
+        expect(output).to include("not yet installed")
+        expect(output).to include("npm install")
+        expect(output).to include("bin/dev")
+      end
+    end
+  end
+  # Story 14.2 (FR104) — the generator no longer leaks ruact plumbing into the
+  # user's tree. After a fresh install, `app/javascript/` holds only the user's
+  # `components/` (+ the gitignored typed `.ruact/server-functions.ts`); the
+  # bootstrap entry is the virtual module `virtual:ruact/bootstrap`, and
+  # `flight-client.js` / `ruact-router.js` live inside the gem.
+  describe "install generator — hidden plumbing, no app/javascript leak (Story 14.2 — FR104)", :story_14_2 do
+    require "stringio"
+    require "generators/ruact/install/install_generator"
+    let(:app_root) { Dir.mktmpdir("ruact_install_1402") }
+    after { FileUtils.rm_rf(app_root) }
+    def build_generator(root, opts = {})
+      Ruact::Generators::InstallGenerator.new([], opts, destination_root: root)
+    end
+    def silently
+      original = $stdout
+      $stdout = StringIO.new
+      yield
+    ensure
+      $stdout = original
+    end
+    before do
+      FileUtils.mkdir_p(File.join(app_root, "app/controllers"))
+      File.write(File.join(app_root, "app/controllers/application_controller.rb"),
+                 "class ApplicationController < ActionController::Base\nend\n")
+      FileUtils.mkdir_p(File.join(app_root, "app/views/layouts"))
+      File.write(File.join(app_root, "app/views/layouts/application.html.erb"),
+                 "<!DOCTYPE html>\n<html>\n  <body>\n    <%= yield %>\n  </body>\n</html>\n")
+      File.write(File.join(app_root, ".gitignore"), "/log/*\n")
+    end
+    it "does NOT define a create_javascript_entry action (no application.jsx writer)" do
+      expect(Ruact::Generators::InstallGenerator.instance_methods).not_to include(:create_javascript_entry)
+    end
+    it "no longer ships the application.jsx template (its source moved into the gem runtime)" do
+      template = File.expand_path(
+        "../../lib/generators/ruact/install/templates/application.jsx.tt", __dir__
+      )
+      expect(File).not_to exist(template)
+    end
+    it "writes no application.jsx / flight-client.js / ruact-router.js into app/javascript", :aggregate_failures do
+      gen = build_generator(app_root)
+      silently do
+        gen.create_components_directory
+        gen.create_server_functions_directory
+        gen.append_gitignore_entries
+        gen.create_vite_config
+      end
+      expect(File).not_to exist(File.join(app_root, "app/javascript/application.jsx"))
+      expect(File).not_to exist(File.join(app_root, "app/javascript/flight-client.js"))
+      expect(File).not_to exist(File.join(app_root, "app/javascript/ruact-router.js"))
+      # The user's components dir + the typed registry scaffold still exist.
+      expect(File).to exist(File.join(app_root, "app/javascript/components/.keep"))
+      expect(File).to exist(File.join(app_root, "app/javascript/.ruact/.gitkeep"))
+    end
+    it "keeps the .ruact/server-functions.ts gitignore entry unchanged (server-functions.ts stays)" do
+      gen = build_generator(app_root)
+      silently { gen.append_gitignore_entries }
+      expect(File.read(File.join(app_root, ".gitignore")))
+        .to include("app/javascript/.ruact/server-functions.ts")
+    end
+    describe "migration advisory for an earlier-layout app (AC7 — no half-wired state)" do
+      def capture_stdout
+        original = $stdout
+        $stdout = StringIO.new
+        yield
+        $stdout.string
+      ensure
+        $stdout = original
+      end
+      it "prints the exact delete steps + virtual entry when stale plumbing files exist", :aggregate_failures do
+        %w[application.jsx flight-client.js ruact-router.js].each do |f|
+          FileUtils.mkdir_p(File.join(app_root, "app/javascript"))
+          File.write(File.join(app_root, "app/javascript", f), "// stale\n")
+        end
+        gen = build_generator(app_root)
+        output = capture_stdout { gen.advise_plumbing_migration }
+        expect(output).to match(/earlier ruact layout detected/i)
+        expect(output).to include("delete app/javascript/application.jsx")
+        expect(output).to include("delete app/javascript/flight-client.js")
+        expect(output).to include("delete app/javascript/ruact-router.js")
+        expect(output).to include(described_class.bootstrap_virtual_id)
+        expect(output).to include("ruact_js_assets")
+      end
+      it "is a no-op on a fresh install (no stale files → no notice)" do
+        gen = build_generator(app_root)
+        output = capture_stdout { gen.advise_plumbing_migration }
+        expect(output).to be_empty
+      end
+    end
+    describe "vite.config input targets the virtual bootstrap (AC3 — single source of truth)" do
+      let(:template_path) do
+        File.expand_path("../../lib/generators/ruact/install/templates/vite.config.js.tt", __dir__)
+      end
+      it "renders the input from Ruact.bootstrap_virtual_id, not a hardcoded application.jsx", :aggregate_failures do
+        content = File.read(template_path)
+        expect(content).to include("Ruact.bootstrap_virtual_id")
+        # The `input:` line must NOT hardcode the old application.jsx entry
+        # (a prose mention in a comment is fine — only the directive matters).
+        expect(content).not_to match(%r{input:\s*['"]app/javascript/application\.jsx['"]})
+      end
+      it "the generated input equals the id the ViewHelper/prod manifest lookup uses (no drift)" do
+        gen = build_generator(app_root)
+        silently { gen.create_vite_config }
+        generated = File.read(File.join(app_root, "vite.config.js"))
+        expect(generated).to include("input: '#{described_class.bootstrap_virtual_id}'")
+      end
+      it "leaves an existing vite.config.js untouched when --force is not passed" do
+        File.write(File.join(app_root, "vite.config.js"), "// hand-written\n")
+        gen = build_generator(app_root)
+        silently { gen.create_vite_config }
+        expect(File.read(File.join(app_root, "vite.config.js"))).to eq("// hand-written\n")
+      end
+      it "actually regenerates an existing vite.config.js under --force (the message's promise)", :aggregate_failures do
+        File.write(File.join(app_root, "vite.config.js"), "// hand-written\n")
+        gen = build_generator(app_root, { force: true })
+        silently { gen.create_vite_config }
+        regenerated = File.read(File.join(app_root, "vite.config.js"))
+        expect(regenerated).not_to include("hand-written")
+        expect(regenerated).to include("input: '#{described_class.bootstrap_virtual_id}'")
+      end
+    end
+  end
+  # Story 14.6 (FR101, Epic 14 DoD) — `ruact:install` now emits the missing
+  # launch pieces so the literal `bin/dev` produces a working app: a
+  # `package.json` (so 14.1's `npm install` resolves React + Vite) and a
+  # `Procfile.dev` + foreman `bin/dev` that boot BOTH Rails and the Vite dev
+  # server. Each is guarded (non-clobbering, --force overwrites) and idempotent.
+  describe "install generator — launch files: package.json + Procfile.dev + bin/dev (Story 14.6)",
+           :story_14_6 do
+    require "stringio"
+    require "generators/ruact/install/install_generator"
+    let(:app_root) { Dir.mktmpdir("ruact_install_1406") }
+    after { FileUtils.rm_rf(app_root) }
+    def build_generator(root, opts = {})
+      Ruact::Generators::InstallGenerator.new([], opts, destination_root: root)
+    end
+    def silently
+      original = $stdout
+      $stdout = StringIO.new
+      yield
+    ensure
+      $stdout = original
+    end
+    describe "create_package_json (AC#1 — JS deps to install)", :aggregate_failures do
+      it "writes a package.json declaring React + Vite (and a `dev` script)" do
+        gen = build_generator(app_root)
+        silently { gen.create_package_json }
+        path = File.join(app_root, "package.json")
+        expect(File).to exist(path)
+        pkg = JSON.parse(File.read(path))
+        expect(pkg.dig("dependencies", "react")).to be_a(String)
+        expect(pkg.dig("dependencies", "react-dom")).to be_a(String)
+        expect(pkg.dig("devDependencies", "vite")).to be_a(String)
+        expect(pkg.dig("devDependencies", "@vitejs/plugin-react")).to be_a(String)
+        expect(pkg.dig("scripts", "dev")).to eq("vite")
+        expect(pkg["type"]).to eq("module")
+      end
+      it "does NOT list the bundled ruact Vite plugin as an npm dependency " \
+         "(vite.config imports it by absolute path)" do
+        gen = build_generator(app_root)
+        silently { gen.create_package_json }
+        expect(File.read(File.join(app_root, "package.json"))).not_to include("vite-plugin-ruact")
+      end
+      it "derives a valid lowercase npm name from the app directory" do
+        gen = build_generator(app_root)
+        silently { gen.create_package_json }
+        name = JSON.parse(File.read(File.join(app_root, "package.json")))["name"]
+        expect(name).to match(/\A[a-z0-9._-]+\z/)
+      end
+      it "leaves an existing package.json untouched without --force (non-clobbering)" do
+        File.write(File.join(app_root, "package.json"), %({ "name": "mine" }\n))
+        gen = build_generator(app_root)
+        silently { gen.create_package_json }
+        expect(File.read(File.join(app_root, "package.json"))).to eq(%({ "name": "mine" }\n))
+      end
+      it "overwrites an existing package.json under --force" do
+        File.write(File.join(app_root, "package.json"), %({ "name": "mine" }\n))
+        gen = build_generator(app_root, { force: true })
+        silently { gen.create_package_json }
+        expect(File.read(File.join(app_root, "package.json"))).to include("\"vite\"")
+      end
+    end
+    describe "create_launch_files (Epic DoD — bin/dev boots both processes)", :aggregate_failures do
+      it "writes Procfile.dev with BOTH a Rails web process and a Vite process" do
+        gen = build_generator(app_root)
+        silently { gen.create_launch_files }
+        procfile = File.read(File.join(app_root, "Procfile.dev"))
+        expect(procfile).to match(/^web:.*rails server/)
+        expect(procfile).to match(/^vite:.*npm run dev/)
+      end
+      it "writes an executable bin/dev that execs foreman against Procfile.dev" do
+        gen = build_generator(app_root)
+        silently { gen.create_launch_files }
+        dev = File.join(app_root, "bin/dev")
+        expect(File).to exist(dev)
+        expect(File).to be_executable(dev)
+        body = File.read(dev)
+        expect(body).to include("foreman start -f Procfile.dev")
+        expect(body).to include("gem install foreman")
+      end
+      # Live clean-room fix — ruact OWNS bin/dev. `rails new` (Rails 8.x) writes a
+      # bin/dev that starts ONLY `rails server`; left in place, Vite never runs,
+      # the client manifest is never written, and the first render 500s. So the
+      # foreman launcher must TAKE OVER that default rather than skip it.
+      it "takes ownership of the Rails-default bin/dev (one that only runs rails server)" do
+        FileUtils.mkdir_p(File.join(app_root, "bin"))
+        File.write(File.join(app_root, "bin/dev"),
+                   %(#!/usr/bin/env ruby\nexec "./bin/rails", "server", *ARGV\n))
+        gen = build_generator(app_root)
+        silently { gen.create_launch_files }
+        body = File.read(File.join(app_root, "bin/dev"))
+        expect(body).to include("foreman start -f Procfile.dev")
+        expect(body).not_to include('exec "./bin/rails", "server"')
+        expect(File).to be_executable(File.join(app_root, "bin/dev"))
+      end
+      # Idempotency (invariant 14.1) — re-running the generator must not churn:
+      # the bin/dev we wrote already drives Procfile.dev, so the second run skips
+      # it. (Detection is content-based: our launcher execs foreman against
+      # Procfile.dev, so a marker comment proves the file was NOT rewritten.)
+      it "is idempotent — a second run does not rewrite the foreman bin/dev it already wrote" do
+        gen = build_generator(app_root)
+        silently { gen.create_launch_files }
+        marked = "#{File.read(File.join(app_root, 'bin/dev'))}# ruact-idempotency-marker\n"
+        File.write(File.join(app_root, "bin/dev"), marked)
+        gen2 = build_generator(app_root)
+        silently { gen2.create_launch_files }
+        expect(File.read(File.join(app_root, "bin/dev"))).to include("# ruact-idempotency-marker")
+      end
+      # Codex R1 — detection must be stricter than a bare `include?("Procfile.dev")`:
+      # a bin/dev that only NAMES Procfile.dev in a comment (but still runs only
+      # `rails server`) must be taken over, not skipped — else the 500 survives.
+      it "takes ownership when Procfile.dev appears only in a comment (runs only rails server)" do
+        FileUtils.mkdir_p(File.join(app_root, "bin"))
+        File.write(File.join(app_root, "bin/dev"),
+                   %(#!/usr/bin/env ruby\n# TODO: switch to Procfile.dev + foreman one day\n) +
+                   %(exec "./bin/rails", "server", *ARGV\n))
+        gen = build_generator(app_root)
+        silently { gen.create_launch_files }
+        body = File.read(File.join(app_root, "bin/dev"))
+        expect(body).to include("foreman start -f Procfile.dev")
+        expect(body).not_to include('exec "./bin/rails", "server"')
+      end
+      # Codex R2/R3 — a runner name that is only MENTIONED (not invoked as the
+      # command) must not count as a real launcher. Each of these bin/dev files
+      # names "foreman"/"Procfile.dev" somewhere but actually runs `rails server`,
+      # so each must be taken over (else the original 500 survives).
+      [
+        ["echoed in a string",
+         %(echo "switch to: foreman start -f Procfile.dev"\nexec ./bin/rails server\n)],
+        ["assigned to a variable",
+         %(MSG="switch to: foreman start -f Procfile.dev"\nexec ./bin/rails server\n)],
+        ["named inside a command -v test",
+         %(if command -v foreman; then echo Procfile.dev; fi\nexec ./bin/rails server\n)],
+        ["referenced only in an inline comment on a runner diagnostic line",
+         %(foreman --version # TODO: switch to Procfile.dev\nexec ./bin/rails server\n)],
+        ["a runner look-alike command (not the real runner)",
+         %(foreman-old start -f Procfile.dev\nexec ./bin/rails server\n)]
+      ].each do |(label, contents)|
+        it "takes ownership when a foreman command is only #{label} (still runs rails server)" do
+          FileUtils.mkdir_p(File.join(app_root, "bin"))
+          File.write(File.join(app_root, "bin/dev"), "#!/usr/bin/env bash\n#{contents}")
+          gen = build_generator(app_root)
+          silently { gen.create_launch_files }
+          body = File.read(File.join(app_root, "bin/dev"))
+          expect(body).to include("gem install foreman")
+          expect(body).not_to include("exec ./bin/rails server")
+        end
+      end
+      # Non-clobbering of a DELIBERATE foreman launcher — a developer's own
+      # bin/dev that already drives Procfile.dev is ruact-compatible and is left
+      # untouched (it boots Vite via the same Procfile.dev ruact writes).
+      it "leaves a developer's existing foreman launcher (driving Procfile.dev) untouched" do
+        FileUtils.mkdir_p(File.join(app_root, "bin"))
+        File.write(File.join(app_root, "bin/dev"),
+                   "#!/usr/bin/env bash\n# my custom launcher\nexec foreman start -f Procfile.dev\n")
+        gen = build_generator(app_root)
+        silently { gen.create_launch_files }
+        expect(File.read(File.join(app_root, "bin/dev"))).to include("# my custom launcher")
+      end
+      it "overwrites even a Procfile.dev-driving launcher under --force" do
+        FileUtils.mkdir_p(File.join(app_root, "bin"))
+        File.write(File.join(app_root, "bin/dev"),
+                   "#!/usr/bin/env bash\n# my custom launcher\nexec foreman start -f Procfile.dev\n")
+        gen = build_generator(app_root, { force: true })
+        silently { gen.create_launch_files }
+        body = File.read(File.join(app_root, "bin/dev"))
+        expect(body).to include("gem install foreman")
+        expect(body).not_to include("# my custom launcher")
+      end
+    end
+    describe "action ordering (npm install needs package.json on disk first)" do
+      it "defines create_package_json BEFORE install_javascript_dependencies", :aggregate_failures do
+        klass = Ruact::Generators::InstallGenerator
+        line = ->(name) { klass.instance_method(name).source_location.last }
+        expect(line.call(:create_package_json)).to be < line.call(:install_javascript_dependencies)
+        expect(line.call(:create_launch_files)).to be < line.call(:install_javascript_dependencies)
+      end
+    end
   end
 end