RubyGems - ruact - Versions diffs - 0.0.7 → 0.0.9 - Mend

ruact 0.0.7 → 0.0.9

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 (61) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +59 -1
data/docs/internal/decisions/server-functions-api.md +55 -0
data/lib/generators/ruact/install/install_generator.rb +378 -6
data/lib/generators/ruact/install/templates/AGENTS.md.tt +159 -0
data/lib/generators/ruact/install/templates/Procfile.dev.tt +3 -0
data/lib/generators/ruact/install/templates/globals.css.tt +20 -0
data/lib/generators/ruact/install/templates/initializer.rb.tt +9 -0
data/lib/generators/ruact/install/templates/package.json.tt +7 -1
data/lib/generators/ruact/install/templates/tsconfig.json.tt +18 -0
data/lib/generators/ruact/scaffold/scaffold_shadcn_preflight.rb +10 -0
data/lib/ruact/configuration.rb +73 -0
data/lib/ruact/controller/document_rendering.rb +210 -0
data/lib/ruact/controller.rb +14 -46
data/lib/ruact/doctor.rb +102 -12
data/lib/ruact/erb_preprocessor.rb +113 -0
data/lib/ruact/errors.rb +16 -0
data/lib/ruact/layout_source.rb +59 -0
data/lib/ruact/manifest_resolver.rb +2 -2
data/lib/ruact/serializable.rb +98 -6
data/lib/ruact/server.rb +163 -0
data/lib/ruact/server_functions/introspection.rb +81 -0
data/lib/ruact/server_functions.rb +26 -4
data/lib/ruact/testing/component_query.rb +113 -0
data/lib/ruact/testing/flight_extractor.rb +221 -0
data/lib/ruact/testing/flight_structure_diff.rb +267 -0
data/lib/ruact/testing/flight_wire_parser.rb +138 -0
data/lib/ruact/testing.rb +90 -0
data/lib/ruact/version.rb +1 -1
data/lib/ruact/view_helper.rb +10 -1
data/lib/ruact.rb +1 -0
data/lib/tasks/ruact.rake +55 -2
data/spec/fixtures/story_7_9_views/controller_request_spec_support/exploding_layout_demo/show.html.erb +3 -0
data/spec/fixtures/story_7_9_views/controller_request_spec_support/ghost_layout_demo/show.html.erb +3 -0
data/spec/fixtures/story_7_9_views/controller_request_spec_support/layout_demo/show.html.erb +3 -0
data/spec/fixtures/story_7_9_views/controller_request_spec_support/rootless_layout_demo/show.html.erb +3 -0
data/spec/fixtures/story_7_9_views/controller_request_spec_support/unwired_layout_demo/show.html.erb +3 -0
data/spec/fixtures/story_7_9_views/layouts/bare_host.html.erb +16 -0
data/spec/fixtures/story_7_9_views/layouts/exploding_host.html.erb +24 -0
data/spec/fixtures/story_7_9_views/layouts/rootless_host.html.erb +15 -0
data/spec/fixtures/story_7_9_views/layouts/ruact_host.html.erb +17 -0
data/spec/ruact/controller_request_spec.rb +203 -0
data/spec/ruact/doctor_spec.rb +222 -6
data/spec/ruact/erb_preprocessor_spec.rb +145 -0
data/spec/ruact/install_generator_spec.rb +727 -70
data/spec/ruact/layout_source_spec.rb +108 -0
data/spec/ruact/manifest_resolver_spec.rb +15 -0
data/spec/ruact/scaffold_generator_spec.rb +14 -0
data/spec/ruact/serializable_spec.rb +126 -0
data/spec/ruact/server_bucket_request_spec.rb +291 -0
data/spec/ruact/server_functions/introspection_spec.rb +135 -0
data/spec/ruact/tasks_json_introspection_spec.rb +141 -0
data/spec/ruact/testing/have_ruact_component_spec.rb +170 -0
data/spec/ruact/testing/no_production_load_spec.rb +41 -0
data/spec/support/flight_wire_parser.rb +12 -126
data/spec/support/matchers/flight_fixture_matcher.rb +7 -258
data/vendor/javascript/ruact-server-functions-runtime/index.d.ts +25 -0
data/vendor/javascript/ruact-server-functions-runtime/index.js +104 -7
data/vendor/javascript/ruact-server-functions-runtime/index.test.mjs +173 -0
data/vendor/javascript/vite-plugin-ruact/type-tests/auto-revalidate.test-d.ts +25 -0
metadata +30 -4

data/spec/ruact/install_generator_spec.rb CHANGED Viewed

@@ -88,22 +88,6 @@ RSpec.describe Ruact do # rubocop:disable RSpec/SpecFilePathFormat
       :injected
     end
-    # Reproduces inject_layout_shell logic from the generator
-    def inject_layout_shell(dest_root)
-      layout_file = File.join(dest_root, "app/views/layouts/application.html.erb")
-      return :missing unless File.exist?(layout_file)
-      content = File.read(layout_file)
-      return :already_present if content.include?("ruact: root")
-      modified = content.sub(
-        "  </body>",
-        "    <%# ruact: root %>\n    <div id=\"root\"></div>\n  </body>"
-      )
-      File.write(layout_file, modified)
-      :injected
-    end
     describe "ApplicationController injection (AC#1, AC#3)" do
       let(:controller_content) do
         "class ApplicationController < ActionController::Base\nend\n"
@@ -137,60 +121,6 @@ RSpec.describe Ruact do # rubocop:disable RSpec/SpecFilePathFormat
       end
     end
-    describe "Layout injection (AC#1, AC#3)" do
-      let(:layout_content) do
-        <<~HTML
-          <!DOCTYPE html>
-          <html>
-            <body>
-              <%= yield %>
-            </body>
-          </html>
-        HTML
-      end
-      it "injects the RSC root div before </body>" do
-        write_file("app/views/layouts/application.html.erb", layout_content)
-        result = inject_layout_shell(tmpdir)
-        expect(result).to eq(:injected)
-        content = read_file("app/views/layouts/application.html.erb")
-        expect(content).to include('<div id="root"></div>')
-        expect(content).to include("ruact: root")
-      end
-      it "returns :already_present on second run (idempotent, AC#3)" do
-        content_with_marker = layout_content.sub(
-          "  </body>",
-          "    <%# ruact: root %>\n    <div id=\"root\"></div>\n  </body>"
-        )
-        write_file("app/views/layouts/application.html.erb", content_with_marker)
-        result = inject_layout_shell(tmpdir)
-        expect(result).to eq(:already_present)
-      end
-      it "does not duplicate the root div when run twice (AC#3)" do
-        write_file("app/views/layouts/application.html.erb", layout_content)
-        inject_layout_shell(tmpdir)
-        inject_layout_shell(tmpdir)
-        content = read_file("app/views/layouts/application.html.erb")
-        occurrences = content.scan('<div id="root">').size
-        expect(occurrences).to eq(1)
-      end
-      it "places the root div before the closing </body> tag" do
-        write_file("app/views/layouts/application.html.erb", layout_content)
-        inject_layout_shell(tmpdir)
-        content = read_file("app/views/layouts/application.html.erb")
-        root_pos  = content.index('<div id="root">')
-        body_pos  = content.index("</body>")
-        expect(root_pos).to be < body_pos
-      end
-    end
     describe "vite.config.js template (AC#2)" do
       let(:template_path) do
         File.expand_path(
@@ -359,6 +289,7 @@ RSpec.describe Ruact do # rubocop:disable RSpec/SpecFilePathFormat
             gen.create_server_functions_directory
             gen.append_gitignore_entries
             gen.create_vite_config
+            gen.create_agents_md
           end.not_to raise_error
         end
@@ -371,6 +302,7 @@ RSpec.describe Ruact do # rubocop:disable RSpec/SpecFilePathFormat
         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"))
+        expect(File).to exist(File.join(app_root, "AGENTS.md"))
       end
     end
   end
@@ -889,4 +821,729 @@ RSpec.describe Ruact do # rubocop:disable RSpec/SpecFilePathFormat
       end
     end
   end
+  # Story 15.1 (FR105) — `ruact:install` emits an AGENTS.md teaching coding
+  # agents the ruact conventions, traps, and verification commands. The ruact
+  # content is delimited by explicit markers so re-runs are idempotent, a
+  # user-authored AGENTS.md is appended to (never clobbered), and --force
+  # refreshes ONLY the marked section. Content assertions grep stable tokens
+  # (commands, file paths, API names) — never full-file snapshots, since later
+  # stories (15.2/15.3/15.4) deliberately evolve the prose.
+  describe "install generator — AGENTS.md emission (Story 15.1 — FR105)", :story_15_1 do
+    require "stringio"
+    require "generators/ruact/install/install_generator"
+    let(:app_root) { Dir.mktmpdir("ruact_install_1501") }
+    let(:agents_md_path) { File.join(app_root, "AGENTS.md") }
+    let(:begin_marker) { "<!-- ruact:begin -->" }
+    let(:end_marker) { "<!-- ruact:end -->" }
+    let(:template_path) do
+      File.expand_path("../../lib/generators/ruact/install/templates/AGENTS.md.tt", __dir__)
+    end
+    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 "fresh emission (AC#1)" do
+      it "creates AGENTS.md delimited by the ruact markers", :aggregate_failures do
+        silently { build_generator(app_root).create_agents_md }
+        expect(File).to exist(agents_md_path)
+        content = File.read(agents_md_path)
+        expect(content).to start_with(begin_marker)
+        expect(content.rstrip).to end_with(end_marker)
+      end
+      it "covers the model, codegen, queries and verification areas", :aggregate_failures do
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+        # The verb rule (mutations = non-GET routed actions on Ruact::Server)
+        expect(content).to include("Ruact::Server")
+        expect(content).to include("non-GET")
+        # Route-driven codegen: ground-truth file + regenerate command
+        expect(content).to include("app/javascript/.ruact/server-functions.ts")
+        expect(content).to include("bin/rails ruact:server_functions:generate")
+        # Queries (reads)
+        expect(content).to include("Ruact::Query")
+        expect(content).to include("app/queries/")
+        expect(content).to include("ruact_queries")
+        expect(content).to include("useQuery")
+        # Verification commands (the only two that exist today)
+        expect(content).to include("bin/rails ruact:doctor")
+        # Docs pointers
+        expect(content).to include("https://ruact.dev")
+        expect(content).to include("llms.txt")
+      end
+      it "covers the five traps and the safety areas", :aggregate_failures do
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+        # Trap 1 — children unsupported / self-closing only
+        expect(content).to include("self-closing")
+        expect(content).to include("children")
+        # Trap 2 — Ruby (not JS) inside {} props
+        expect(content).to include("Ruby, not JavaScript")
+        # Trap 3 — Accept-header dual shape (exact application/json)
+        expect(content).to include("Accept")
+        expect(content).to include("application/json")
+        # Trap 4 — ruact_errors fall-through
+        expect(content).to include("ruact_errors")
+        expect(content).to include("fall-through")
+        # Trap 5 — name derivation from routes
+        expect(content).to include("createPost")
+        expect(content).to include("ruact_function_name")
+        # Serialization allowlist
+        expect(content).to include("ruact_props")
+        expect(content).to include("strict_serialization")
+        # SGID helpers (purpose + expiry required grain)
+        expect(content).to include("Ruact.signed_global_id")
+        expect(content).to include("Ruact.locate_signed")
+      end
+      it "makes no claim before its artifact (AC#4 — content honesty)", :aggregate_failures do
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+        # (The loud children `PreprocessorError` is Story 15.2's shipped
+        # artifact, and the `--json` introspection commands are Story 15.3's —
+        # both may now be claimed; see the `:story_15_2` / `:story_15_3` guards
+        # below that PIN each claim's presence. Story 15.4's public render
+        # helpers are now shipped too — see the `:story_15_4` guard below.)
+        #
+        # tsc does not run in a fresh install (no typescript devDep / tsconfig) —
+        # it may only appear conditionally phrased (D1).
+        expect(content).to match(/if your app has typescript tooling/i) if content.include?("tsc")
+        # Volatile strings must not be quoted: no gem version pins.
+        expect(content).not_to match(/\b0\.0\.\d+\b/)
+      end
+      # Story 15.2 (D2) — now that the loud children error is a shipped artifact,
+      # trap #1 truthfully claims it fails LOUDLY (was "fails silently" in 15.1).
+      it "trap #1 claims the loud PreprocessorError (Story 15.2 D2)", :aggregate_failures, :story_15_2 do
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+        expect(content).to include("PreprocessorError")
+        expect(content).to match(/fail LOUDLY/i)
+        expect(content).not_to match(/fail silently/i)
+      end
+      # Story 15.3 (D2) — now that the `--json` introspection surface is a shipped
+      # artifact, the "Verify your work" section references it (relaxes the 15.1
+      # honesty guard above). This PINS the claim AND its EXPERIMENTAL framing so
+      # the template never presents the JSON shape as a stable contract.
+      it "references --json introspection as EXPERIMENTAL (15.3 D2)", :aggregate_failures, :story_15_3 do
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+        expect(content).to include("ruact:routes -- --json")
+        expect(content).to include("ruact:doctor")
+        expect(content).to include("Append `-- --json`")
+        expect(content).to match(/EXPERIMENTAL/)
+        expect(content).to include("schema_version")
+      end
+      # Story 15.4 (D6) — now that the public render-assertion helpers are a
+      # shipped artifact (FR108), the "Verify your work" section references them.
+      # This PINS the claim (name + explicit require + the JSON-vs-Flight rule)
+      # so it stays consistent with `website/public/llms.txt`.
+      it "references the ruact/testing render helpers (15.4 D6)", :aggregate_failures, :story_15_4 do
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+        expect(content).to include(%(require "ruact/testing"))
+        expect(content).to include("have_ruact_component")
+        expect(content).to include("JSON.parse(response.body)")
+      end
+    end
+    describe "idempotency (AC#2 — double-run zero diff)" do
+      it "leaves the file byte-identical on a second run and reports a skip", :aggregate_failures do
+        silently { build_generator(app_root).create_agents_md }
+        first = File.read(agents_md_path)
+        output = capture_stdout { build_generator(app_root).create_agents_md }
+        expect(File.read(agents_md_path)).to eq(first)
+        expect(output).to include("skip")
+      end
+    end
+    describe "append mode (AC#2 — user-authored AGENTS.md)" do
+      let(:user_content) { "# My app\n\nUse pnpm here. Never touch config/secrets.yml.\n" }
+      it "appends the marked section preserving every pre-existing user byte", :aggregate_failures do
+        File.write(agents_md_path, user_content)
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+        expect(content).to start_with(user_content)
+        expect(content.scan(begin_marker).count).to eq(1)
+        expect(content.scan(end_marker).count).to eq(1)
+        expect(content).to include("\n\n#{begin_marker}")
+      end
+      it "blank-line separates the section when the user file lacks a trailing newline" do
+        File.write(agents_md_path, "# My app — no trailing newline")
+        silently { build_generator(app_root).create_agents_md }
+        expect(File.read(agents_md_path))
+          .to include("# My app — no trailing newline\n\n#{begin_marker}")
+      end
+      it "appending then re-running is idempotent (skip, zero diff)" do
+        File.write(agents_md_path, user_content)
+        silently { build_generator(app_root).create_agents_md }
+        appended = File.read(agents_md_path)
+        silently { build_generator(app_root).create_agents_md }
+        expect(File.read(agents_md_path)).to eq(appended)
+      end
+    end
+    describe "--force refresh (AC#2 — marked-block-only)" do
+      it "replaces ONLY the between-marker content, never user bytes outside", :aggregate_failures do
+        silently { build_generator(app_root).create_agents_md }
+        section = File.read(agents_md_path)
+        stale = section.sub("## Five traps", "## STALE CONTENT FROM AN OLDER GEM")
+        File.write(agents_md_path, "# mine, above\n\n#{stale}\n# mine, below\n")
+        silently { build_generator(app_root, { force: true }).create_agents_md }
+        content = File.read(agents_md_path)
+        expect(content).to start_with("# mine, above\n")
+        expect(content).to end_with("# mine, below\n")
+        expect(content).to include("## Five traps")
+        expect(content).not_to include("STALE CONTENT FROM AN OLDER GEM")
+        expect(content.scan(begin_marker).count).to eq(1)
+      end
+      it "creates the file under --force when none exists" do
+        silently { build_generator(app_root, { force: true }).create_agents_md }
+        expect(File.read(agents_md_path)).to include(begin_marker)
+      end
+    end
+    # Codex R1 — an incomplete marker state is ambiguous in BOTH directions
+    # (appending would duplicate content next to a stray marker; replacing
+    # would guess the range), so the only byte-safe move is warn + no-op.
+    describe "broken marker pair (byte-safety)" do
+      [
+        ["a begin marker without its end marker",
+         "# mine\n\n<!-- ruact:begin -->\ntruncated ruact section, no end marker\n"],
+        ["an end marker without its begin marker",
+         "# mine\n\nstray tail of a ruact section\n<!-- ruact:end -->\n"],
+        ["an end marker preceding the begin marker",
+         "# mine\n\n<!-- ruact:end -->\nreversed\n<!-- ruact:begin -->\n"],
+        # Codex R2 — a VALID pair plus stray extra markers is still ambiguous:
+        # skip/refresh would leave (or eat past) the unmatched marker.
+        ["a stray end marker before a valid pair",
+         "<!-- ruact:end -->\nstray\n\n<!-- ruact:begin -->\nsection\n<!-- ruact:end -->\n"],
+        ["a stray begin marker after a valid pair",
+         "<!-- ruact:begin -->\nsection\n<!-- ruact:end -->\n\nstray\n<!-- ruact:begin -->\n"],
+        ["two complete marker pairs",
+         "<!-- ruact:begin -->\none\n<!-- ruact:end -->\n\n<!-- ruact:begin -->\ntwo\n<!-- ruact:end -->\n"]
+      ].each do |(label, broken)|
+        it "warns and leaves the file untouched with #{label} (no --force)", :aggregate_failures do
+          File.write(agents_md_path, broken)
+          output = capture_stdout { build_generator(app_root).create_agents_md }
+          expect(File.read(agents_md_path)).to eq(broken)
+          expect(output).to include("warn")
+        end
+        it "warns and leaves the file untouched with #{label} (--force)", :aggregate_failures do
+          File.write(agents_md_path, broken)
+          output = capture_stdout { build_generator(app_root, { force: true }).create_agents_md }
+          expect(File.read(agents_md_path)).to eq(broken)
+          expect(output).to include("warn")
+        end
+      end
+    end
+    describe "action ordering + template budget" do
+      it "defines create_agents_md BEFORE install_javascript_dependencies" do
+        klass = Ruact::Generators::InstallGenerator
+        line = ->(name) { klass.instance_method(name).source_location.last }
+        expect(line.call(:create_agents_md)).to be < line.call(:install_javascript_dependencies)
+      end
+      # AC#3 tripwire — the ~150-line budget is the epic's scope probe; the
+      # tripwire's tolerance is 160 (the tripwire's, not the product contract's).
+      it "keeps the template body at or under 160 lines" do
+        expect(File.read(template_path).lines.count).to be <= 160
+      end
+    end
+  end
+  # The `--shadcn` prerequisites. The gap these close is concrete: shadcn's CLI
+  # aborts on a ruact app with "No Tailwind CSS configuration found" and "Could
+  # not find valid path aliases", because a ruact app ships neither Tailwind nor
+  # a tsconfig.json. Without them `ruact:scaffold --shadcn` emitted components
+  # whose classes resolved to nothing — styled markup with no styles.
+  describe "install generator — --shadcn prerequisites" do
+    require "stringio"
+    require "generators/ruact/install/install_generator"
+    let(:app_root) { Dir.mktmpdir("ruact_install_shadcn") }
+    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
+    def read(relative)
+      File.read(File.join(app_root, relative))
+    end
+    describe "with --shadcn", :aggregate_failures do
+      let(:generator) { build_generator(app_root, shadcn: true) }
+      it "writes the Tailwind entry shadcn points components.json at" do
+        silently { generator.create_shadcn_prerequisites }
+        expect(File).to exist(File.join(app_root, "app/javascript/styles/globals.css"))
+        expect(read("app/javascript/styles/globals.css")).to include('@import "tailwindcss"')
+      end
+      it "writes the tsconfig import alias shadcn probes for" do
+        silently { generator.create_shadcn_prerequisites }
+        tsconfig = JSON.parse(read("tsconfig.json"))
+        expect(tsconfig.dig("compilerOptions", "paths", "@/*")).to eq(["app/javascript/*"])
+      end
+      it "creates the builds directory Propshaft serves the compiled stylesheet from" do
+        silently { generator.create_shadcn_prerequisites }
+        expect(File).to exist(File.join(app_root, "app/assets/builds/.keep"))
+      end
+      it "declares Tailwind in package.json with a build:css script" do
+        silently { generator.create_package_json }
+        pkg = JSON.parse(read("package.json"))
+        expect(pkg.dig("devDependencies", "tailwindcss")).to be_a(String)
+        expect(pkg.dig("devDependencies", "@tailwindcss/cli")).to be_a(String)
+        expect(pkg.dig("devDependencies", "tw-animate-css")).to be_a(String)
+        expect(pkg.dig("scripts", "build:css")).to include("app/assets/builds/tailwind.css")
+      end
+      it "adds a css watch process so bin/dev rebuilds the stylesheet" do
+        silently { generator.create_launch_files }
+        expect(read("Procfile.dev")).to match(/^css: .*tailwind\.css --watch$/)
+      end
+      it "gitignores the compiled stylesheet (a build artifact of globals.css)" do
+        File.write(File.join(app_root, ".gitignore"), "/log/*\n")
+        silently { generator.append_gitignore_entries }
+        expect(read(".gitignore")).to include("app/assets/builds/tailwind.css")
+      end
+      # The one thing a reader cannot guess: current shadcn defaults to Base UI,
+      # but the components the scaffold generates import Radix primitives.
+      it "prints the two shadcn commands, pinning --base radix" do
+        expect { generator.send(:show_shadcn_next_steps) }
+          .to output(/npx shadcn@latest init --base radix/).to_stdout
+      end
+      it "prints the complete add-list, so the scaffold pre-flight cannot fail on a gap" do
+        expect { generator.send(:show_shadcn_next_steps) }
+          .to output(/add button input textarea switch select label badge table alert-dialog dropdown-menu/)
+          .to_stdout
+      end
+    end
+    # Codex review finding: the layout-migration branch was pinned only by the
+    # REPRODUCTION helper above, which cannot see the real generator's anchor
+    # regex. Invoking the actual generator caught that a layout written with
+    # single quotes matched nothing while the generator still printed a success
+    # message. These specs drive `InstallGenerator#inject_layout_shell` itself.
+    # Thor registers every PUBLIC instance method of a generator as a command and
+    # runs it in declaration order. A helper left public therefore executes on
+    # its own, out of context — this has bitten three times in this branch: a
+    # message printed twice, a `--shadcn`-only notice firing on the default
+    # path, and a helper taking a required argument being invoked with none.
+    # Pin the command list so the next one is caught here rather than in an app.
+    describe "Thor command surface" do
+      it "registers only the install steps, never the private helpers" do
+        expect(Ruact::Generators::InstallGenerator.commands.keys).to contain_exactly(
+          "create_initializer",
+          "inject_controller_concern",
+          "inject_layout_shell",
+          "create_shadcn_prerequisites",
+          "create_components_directory",
+          "create_server_functions_directory",
+          "append_gitignore_entries",
+          "prime_server_functions_codegen",
+          "create_vite_config",
+          "create_package_json",
+          "create_launch_files",
+          "advise_plumbing_migration",
+          "create_agents_md",
+          "install_javascript_dependencies",
+          "show_post_install_message"
+        )
+      end
+      it "has no command requiring arguments (Thor invokes them with none)" do
+        requiring_args = Ruact::Generators::InstallGenerator.commands.keys.reject do |name|
+          Ruact::Generators::InstallGenerator.instance_method(name).arity.zero?
+        end
+        expect(requiring_args).to be_empty
+      end
+    end
+    # Migrating an existing app is the path that matters most here, and Thor's
+    # `template` handles it badly: it raises an overwrite CONFLICT, offering a
+    # choice between losing every setting the app already had and ending up
+    # half-migrated (layout edited, `config.layout` still off) in silence.
+    describe "create_initializer on an app that already has one", :aggregate_failures do
+      def write_initializer(body)
+        path = File.join(app_root, "config/initializers/ruact.rb")
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, body)
+        path
+      end
+      it "adds config.layout without touching the app's existing settings" do
+        path = write_initializer(<<~RUBY)
+          Ruact.configure do |config|
+            config.strict_serialization = true
+            config.max_upload_bytes = 25 * 1024 * 1024
+          end
+        RUBY
+        silently { build_generator(app_root).create_initializer }
+        result = File.read(path)
+        expect(result).to include("config.layout = true")
+        expect(result).to include("config.strict_serialization = true")
+        expect(result).to include("config.max_upload_bytes = 25 * 1024 * 1024")
+      end
+      # `config.layout = false` is a deliberate choice (keep the built-in
+      # shell). Re-running install must not quietly reverse it.
+      it "leaves an explicit opt-out alone" do
+        path = write_initializer("Ruact.configure do |config|\n  config.layout = false\nend\n")
+        silently { build_generator(app_root).create_initializer }
+        expect(File.read(path)).to include("config.layout = false")
+        expect(File.read(path)).not_to include("config.layout = true")
+      end
+      it "is idempotent" do
+        path = write_initializer("Ruact.configure do |config|\nend\n")
+        silently { build_generator(app_root).create_initializer }
+        silently { build_generator(app_root).create_initializer }
+        expect(File.read(path).scan("config.layout").size).to eq(1)
+      end
+      # Never guess at an initializer we do not recognise — say what to add,
+      # because the silent outcome is an app whose CSS never reaches the page.
+      it "tells the user what to add when it cannot find the configure block" do
+        write_initializer("# hand-rolled\nRuact.config\n")
+        output = capture_generator_output { build_generator(app_root).create_initializer }
+        expect(output).to include("could not find the Ruact.configure block")
+        expect(output).to include("config.layout = true")
+      end
+      def capture_generator_output
+        original = $stdout
+        $stdout = StringIO.new
+        yield
+        $stdout.string
+      ensure
+        $stdout = original
+      end
+    end
+    describe "inject_layout_shell — the REAL generator", :aggregate_failures do
+      def write_layout(body)
+        path = File.join(app_root, "app/views/layouts/application.html.erb")
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, body)
+        path
+      end
+      def layout_after_run(body)
+        path = write_layout(body)
+        silently { build_generator(app_root).inject_layout_shell }
+        File.read(path)
+      end
+      # The fresh-install path. Previously covered only by a REPRODUCTION of the
+      # generator's logic, which twice drifted from the generator itself and hid
+      # real defects; the reproduction is gone and these drive the real thing.
+      it "adds both the root div and the asset call to a layout that has neither" do
+        path = write_layout(<<~HTML)
+          <html>
+            <body>
+              <%= yield %>
+            </body>
+          </html>
+        HTML
+        silently { build_generator(app_root).inject_layout_shell }
+        result = File.read(path)
+        expect(result).to include(%(<div id="root"></div>))
+        expect(result).to include("<%= ruact_js_assets %>")
+        expect(result).to include("ruact: root")
+      end
+      it "places them inside the body, before the closing tag" do
+        path = write_layout("<html>\n  <body>\n    <%= yield %>\n  </body>\n</html>\n")
+        silently { build_generator(app_root).inject_layout_shell }
+        result = File.read(path)
+        expect(result.index(%(<div id="root">))).to be < result.index("</body>")
+        expect(result.index(%(<div id="root">))).to be < result.index("ruact_js_assets")
+      end
+      it "is a no-op on a layout that is already migrated" do
+        path = write_layout(<<~HTML)
+          <html>
+            <body>
+              <%# ruact: root %>
+              <div id="root"></div>
+              <%= ruact_js_assets %>
+            </body>
+          </html>
+        HTML
+        before = File.read(path)
+        silently { build_generator(app_root).inject_layout_shell }
+        expect(File.read(path)).to eq(before)
+      end
+      it "migrates a layout whose root div uses single quotes" do
+        result = layout_after_run(<<~HTML)
+          <html>
+            <body>
+              <%# ruact: root %>
+              <div id='root'></div>
+            </body>
+          </html>
+        HTML
+        expect(result).to include("<%= ruact_js_assets %>")
+      end
+      it "migrates a layout whose root div carries extra attributes" do
+        result = layout_after_run(<<~HTML)
+          <html>
+            <body>
+              <%# ruact: root %>
+              <div class="app" id="root" data-turbo="false"></div>
+            </body>
+          </html>
+        HTML
+        expect(result).to include("<%= ruact_js_assets %>")
+      end
+      it "migrates a layout with the marker and the div on one line" do
+        result = layout_after_run(
+          %(<html><body><%# ruact: root %><div id="root"></div></body></html>\n)
+        )
+        expect(result).to include("<%= ruact_js_assets %>")
+      end
+      it "is idempotent — a second run adds nothing" do
+        path = write_layout(<<~HTML)
+          <html>
+            <body>
+              <%# ruact: root %>
+              <div id="root"></div>
+            </body>
+          </html>
+        HTML
+        silently { build_generator(app_root).inject_layout_shell }
+        silently { build_generator(app_root).inject_layout_shell }
+        expect(File.read(path).scan("ruact_js_assets").size).to eq(1)
+      end
+      # Round-2 finding: the anchor matched any attribute ENDING in `id`, so a
+      # layout with `data-id="root"` and no real mount point got the helper
+      # injected and a success message. It now reads as "no root present" and
+      # the generator writes a proper root + helper instead of warning — the
+      # look-alike div is left alone, being none of its business.
+      it "does not mistake a look-alike attribute for the React root" do
+        path = write_layout(<<~HTML)
+          <html>
+            <body>
+              <%# ruact: root %>
+              <div data-id="root"></div>
+            </body>
+          </html>
+        HTML
+        silently { build_generator(app_root).inject_layout_shell }
+        result = File.read(path)
+        expect(result).to match(%r{<div id="root"></div>})
+        expect(result).to include("<%= ruact_js_assets %>")
+      end
+      # The mirror of the legacy migration: the call is there, the mount target
+      # is not. Injecting the whole block would duplicate the helper.
+      it "adds only the missing root when the layout already calls the helper" do
+        path = write_layout(<<~HTML)
+          <html>
+            <body>
+              <%= yield %>
+              <%= ruact_js_assets %>
+            </body>
+          </html>
+        HTML
+        silently { build_generator(app_root).inject_layout_shell }
+        result = File.read(path)
+        expect(result).to match(%r{<div id="root"></div>})
+        expect(result.scan("ruact_js_assets").size).to eq(1)
+        expect(result.index(%(<div id="root">))).to be < result.index("ruact_js_assets")
+      end
+      # A root that is NOT an empty paired div (a spinner placeholder, say) has
+      # nothing safe to inject after, so the generator says so instead of
+      # guessing where the call belongs.
+      it "warns when the root div is not the empty form it knows how to anchor on" do
+        write_layout(<<~HTML)
+          <html>
+            <body>
+              <%# ruact: root %>
+              <div id="root">loading…</div>
+            </body>
+          </html>
+        HTML
+        output = capture_generator_output { build_generator(app_root).inject_layout_shell }
+        expect(output).to include("could not locate the React root div")
+      end
+      # Round-2 finding: the "already migrated, skip" guard was a substring
+      # match, so a TODO note about the helper made the generator skip an app
+      # that was never migrated.
+      it "does not treat a TODO comment naming the helper as already migrated" do
+        path = write_layout(<<~HTML)
+          <html>
+            <body>
+              <%# TODO: add ruact_js_assets %>
+              <%# ruact: root %>
+              <div id="root"></div>
+            </body>
+          </html>
+        HTML
+        silently { build_generator(app_root).inject_layout_shell }
+        expect(File.read(path)).to include("<%= ruact_js_assets %>")
+      end
+      # Silence here is the dangerous outcome: the app keeps rendering through
+      # ruact's CSS-less shell and nothing ever says why.
+      it "says so LOUDLY when it cannot find the root div, instead of claiming success" do
+        write_layout(<<~HTML)
+          <html>
+            <body>
+              <%# ruact: root %>
+              <span id="root"></span>
+            </body>
+          </html>
+        HTML
+        output = capture_generator_output { build_generator(app_root).inject_layout_shell }
+        expect(output).to include("could not locate the React root div")
+        expect(output).not_to include("added ruact_js_assets")
+      end
+      def capture_generator_output
+        original = $stdout
+        $stdout = StringIO.new
+        yield
+        $stdout.string
+      ensure
+        $stdout = original
+      end
+    end
+    describe "without --shadcn (the default path is untouched)", :aggregate_failures do
+      let(:generator) { build_generator(app_root) }
+      it "writes no Tailwind entry and no tsconfig" do
+        silently { generator.create_shadcn_prerequisites }
+        expect(File).not_to exist(File.join(app_root, "app/javascript/styles/globals.css"))
+        expect(File).not_to exist(File.join(app_root, "tsconfig.json"))
+      end
+      it "leaves package.json free of Tailwind" do
+        silently { generator.create_package_json }
+        pkg = JSON.parse(read("package.json"))
+        expect(pkg["devDependencies"].keys).not_to include("tailwindcss", "@tailwindcss/cli")
+        expect(pkg["scripts"]).not_to have_key("build:css")
+      end
+      it "leaves Procfile.dev at the two processes it always had" do
+        silently { generator.create_launch_files }
+        expect(read("Procfile.dev")).not_to include("css:")
+      end
+    end
+  end
 end