ruact 0.0.4 → 0.0.6

data/lib/ruact/railtie.rb

@@ -8,7 +8,6 @@ module Ruact
       require_relative "controller"
       # Story 9.1 — the v2 route-driven marker concern (`include Ruact::Server`).
       require_relative "server"
-      require_relative "server_action"
       # Story 9.4 (D8) — requiring ruact/routing installs the `ruact_queries`
       # macro into ActionDispatch::Routing::Mapper (a Mapper extension, NOT a
       # mounted route — the host's routes.rb explicitly mounts each query
@@ -17,64 +16,8 @@ module Ruact
       require_relative "routing"
     end
 
-    # Story 8.3 — register `app/server_actions/` as a Rails `paths` entry
-    # AND as an autoload + eager-load path so Zeitwerk discovers standalone
-    # `Ruact::ServerAction` modules the same way it discovers
-    # controllers/models/jobs. Registering via `config.paths.add` (vs.
-    # `config.autoload_paths <<` only) is what makes
-    # `Rails.application.config.paths["app/server_actions"].existent`
-    # work — that path enumerator is what
-    # {.server_actions_paths_for} consumes during force-load.
-    initializer "ruact.register_server_actions_path", before: :set_autoload_paths do |app|
-      app.config.paths.add "app/server_actions", with: "app/server_actions"
-      candidate = app.root.join("app/server_actions")
-      if candidate.directory?
-        app.config.autoload_paths   << candidate.to_s
-        app.config.eager_load_paths << candidate.to_s
-      end
-    end
-
     rake_tasks { load File.expand_path("../tasks/ruact.rake", __dir__) }
 
-    # Story 8.1 — clear the action/query registries on every code reload so
-    # removed `ruact_action` declarations don't linger in the registry. We hook
-    # `before_class_unload` (BEFORE Zeitwerk tears down constants) rather than
-    # `to_prepare` (AFTER reload): controller class bodies re-evaluate during
-    # the reload itself, and clearing in `to_prepare` would wipe their fresh
-    # registrations.
-    #
-    # First-boot is naturally safe — registries start empty, so there's nothing
-    # to clear; the very first controller class-body evaluation populates them.
-    # In production this hook never fires (no reloads), which is correct.
-    initializer "ruact.attach_registry_clear_hook" do |app|
-      app.reloader.before_class_unload do
-        Ruact.action_registry.clear!
-        Ruact.query_registry.clear!
-      end
-    end
-
-    # Story 8.1 — mount the single gem-managed endpoint that dispatches all
-    # `ruact_action` calls. The route is `POST /__ruact/fn/:name`; the
-    # controller resolves `:name` against `Ruact.action_registry` (and, once
-    # Story 9.1 lands, `Ruact.query_registry`) and delegates execution to the
-    # entry's host controller class via Rails' normal `dispatch` flow.
-    #
-    # Story 8.1 Re-run-2 (2026-05-14) — `routes.prepend` (not `.append`) so
-    # the gem's reserved `/__ruact/fn/:name` endpoint wins ahead of any host
-    # catch-all (e.g. `match "*path", to: "errors#not_found"` or a wildcard
-    # POST handler) that would otherwise swallow every server-function call
-    # before Ruact saw it. The `/__ruact/fn/` URL prefix is the gem's
-    # documented reserved namespace; hosts that route under `/__ruact/` are
-    # using the same prefix at their own risk.
-    initializer "ruact.mount_server_functions_route" do |app|
-      app.routes.prepend do
-        post "/__ruact/fn/:name",
-             to: "ruact/server_functions/endpoint#dispatch_action",
-             as: :ruact_server_function,
-             constraints: { name: /[a-zA-Z_][a-zA-Z0-9_]*/ }
-      end
-    end
-
     # Load the client manifest at boot (and on each code reload in development).
     # config.to_prepare runs once in production and before every code reload in
     # development, ensuring the manifest is always current without file I/O per
@@ -104,30 +47,27 @@ module Ruact
       ActionView::Base.include(Ruact::ViewHelper)
       ActionView::Template::Handlers::ERB.prepend(Ruact::ErbPreprocessorHook)
 
-      # Story 8.1 review-batch 3 (2026-05-14) — force-load all controller
-      # files BEFORE writing the snapshot so the registry sees every
-      # `ruact_action` declaration. Without this, lazy autoload (Rails dev's
-      # default for `eager_load = false`) means a controller that hasn't
-      # been requested yet isn't loaded, so its `ruact_action` calls don't
-      # populate the registry — the codegen would then emit a stale TS
-      # module missing those exports until the controller is hit at least
-      # once. The endpoint controller would also 404 those names.
-      #
-      # Story 8.3 — the force-loader was renamed from
-      # `force_load_controllers!` to `force_load_server_function_hosts!`
-      # and now walks BOTH `app/controllers/**/*_controller.rb` and
-      # `app/server_actions/**/*.rb` so standalone modules also register
-      # at boot. The old method name is kept as an alias for back-compat
-      # with anything outside the gem calling it.
-      Ruact::Railtie.force_load_server_function_hosts!
-
+      # Story 9.9 — the route-driven (v2) codegen is the SOLE writer of the
+      # real Rails↔Vite bridge (`tmp/cache/ruact/server-functions.json`, which
+      # the Vite plugin renders into `app/javascript/.ruact/server-functions.ts`).
+      # The v1 registry path was demolished in this story (epic decision #6:
+      # the parallel `.next` target ceases to exist; route-driven codegen owns
+      # the real file unconditionally — there are no v1 declarations possible
+      # anymore).
       Ruact::Railtie.write_server_functions_snapshot!
-      Ruact::ServerFunctions.write_v2_snapshot!(route_set: Rails.application.routes, root: Rails.root)
     end
 
     # Detect streaming capability at boot and log the active mode (AC#1–3).
     # Also warns in development if the Vite dev server is not running (AC#4, #7).
     config.after_initialize do
+      # Story 9.9 — guaranteed-correct first-boot codegen. By `after_initialize`
+      # the route table is fully drawn on EVERY Rails version, so this write
+      # always sees the complete route set (the `to_prepare` write above can run
+      # mid-finalization on Rails < 8, before routes exist — that write is the
+      # dev-reload refresh path; this one is the authoritative boot write).
+      # Write-if-changed makes the pair idempotent — at most one real write.
+      Ruact::Railtie.write_server_functions_snapshot!
+
       Ruact::Railtie.detect_streaming_mode!
       next unless Rails.env.development?
 
@@ -166,138 +106,54 @@ module Ruact
                         "— run npm run dev for HMR"
     end
 
-    # Story 8.1 review-batch 3 (2026-05-14) — force-loads every controller
-    # file under `Rails.application.config.paths["app/controllers"]` so the
-    # `ruact_action` registrations populate the registry on a clean boot.
-    #
-    # Without this, Rails' dev-mode lazy autoload only loads a controller
-    # when it's first referenced (typically the first request that routes
-    # to it). That means the codegen snapshot in `to_prepare` would miss
-    # any controller not yet touched.
-    #
-    # Implementation: glob the `app/controllers` directories listed in the
-    # Rails paths configuration and `require_dependency` each
-    # `*_controller.rb` file. `require_dependency` works in both Zeitwerk
-    # (Rails 7+) and the classic autoloader. On Zeitwerk it is implemented
-    # as `Rails.autoloaders.main.load_file(path)` under the hood.
+    # Story 9.9 — writes the route-driven (v2) server-functions JSON snapshot
+    # to the REAL bridge (`tmp/cache/ruact/server-functions.json`) on every
+    # `config.to_prepare`. The Vite plugin renders this JSON into
+    # `app/javascript/.ruact/server-functions.ts`. The write is short-circuited
+    # when the entries are unchanged (Story 8.0a pitfall #1 — dev mode fires
+    # `to_prepare` per request; a naive rewrite would burn IOPS and churn the
+    # Vite plugin's chokidar watcher).
     #
-    # Errors are surfaced as `Ruact::Error` with a controller hint so the
-    # developer sees a meaningful boot failure instead of a silent skip.
+    # Cold-boot ordering (folded in from the Story 9.8 host workaround): on the
+    # very first boot `to_prepare` can run BEFORE `routes.rb` is drawn, leaving
+    # the route set empty so the codegen would emit zero functions. Force the
+    # route table to load first via `routes_reloader.execute_unless_loaded` so
+    # RouteSource/QuerySource see every route.
     #
-    # Re-run-6 (2026-05-15) — also walks every mounted `Rails::Engine`
-    # (and `Rails::Railtie` with `paths["app/controllers"]`) so engine-
-    # owned controllers that declare `ruact_action` populate the registry
-    # at boot. Without this an engine's `ruact_action` declarations would
-    # only register on first request that touches the engine controller —
-    # codegen + endpoint dispatch would lag behind boot.
+    # The force-load is guarded: when `to_prepare` fires from INSIDE the
+    # boot finisher (Rails draws routes during `initialize!`, and on Rails < 8
+    # re-entering `execute_unless_loaded` there raises `FrozenError` against the
+    # in-progress route set), we SKIP THE WRITE ENTIRELY rather than publish a
+    # snapshot from a mid-draw/incomplete route set (which Vite could observe as
+    # a transient empty/stale bridge — Codex R1). The authoritative boot write
+    # is the `after_initialize` call, which always sees the fully-drawn table;
+    # the dev-reload `to_prepare` then refreshes from a settled table.
     #
-    # @return [Integer] number of controller files loaded.
-    def self.force_load_server_function_hosts!
-      loaded = 0
-
-      controller_paths_for(Rails.application).each do |dir|
-        loaded += force_load_dir(dir, glob: "**/*_controller.rb")
-      end
-      server_actions_paths_for(Rails.application).each do |dir|
-        loaded += force_load_dir(dir, glob: "**/*.rb")
-      end
-
-      if defined?(Rails::Engine)
-        Rails::Engine.subclasses.each do |engine_class|
-          # Skip the host app itself; `Rails.application.class` is a
-          # `Rails::Engine` subclass and was already covered above.
-          next if engine_class == Rails.application.class
-
-          engine = safe_engine_instance(engine_class)
-          next unless engine
-
-          controller_paths_for(engine).each { |dir| loaded += force_load_dir(dir, glob: "**/*_controller.rb") }
-          server_actions_paths_for(engine).each { |dir| loaded += force_load_dir(dir, glob: "**/*.rb") }
-        end
-      end
-
-      loaded
-    rescue LoadError, NameError => e
-      raise Ruact::Error,
-            "ruact: failed to force-load a server-function host while populating " \
-            "Ruact.action_registry: #{e.class}: #{e.message}. The gem " \
-            "force-loads `app/controllers/**/*_controller.rb` and " \
-            "`app/server_actions/**/*.rb` at `config.to_prepare` so " \
-            "registries are complete on first boot."
-    end
-
-    # Story 8.3 — back-compat alias. Older code paths (rake tasks shipped
-    # in previous gem versions, downstream tooling) may call the old
-    # name; the new name describes the wider behavior accurately.
-    class << self
-      alias force_load_controllers! force_load_server_function_hosts!
-    end
-
-    # @param engine [Rails::Engine] either `Rails.application` or a mounted engine
-    # @return [Array<String>] existing controller directory paths
-    def self.controller_paths_for(engine)
-      return [] unless engine.respond_to?(:config) && engine.config.respond_to?(:paths)
-
-      paths = engine.config.paths["app/controllers"]
-      return [] unless paths.respond_to?(:existent)
-
-      paths.existent
-    end
-
-    # @param dir [String]
-    # @param glob [String] glob pattern relative to +dir+; defaults to
-    #   `**/*_controller.rb` for back-compat with pre-Story-8.3 callers.
-    # @return [Integer] number of files loaded
-    def self.force_load_dir(dir, glob: "**/*_controller.rb")
-      Dir.glob("#{dir}/#{glob}").each do |file|
-        require_dependency(file)
-      end.length
-    end
-
-    # Story 8.3 — locates `app/server_actions/` for the host application
-    # or a mounted engine. Uses the Rails `paths` enumerator (populated by
-    # the Railtie initializer) when present, falling back to a direct
-    # `engine.root.join` lookup for engines that haven't registered the
-    # path. Returns an empty array when the directory doesn't exist —
-    # silent no-op for hosts that don't use standalone actions.
-    def self.server_actions_paths_for(engine)
-      if engine.respond_to?(:config) && engine.config.respond_to?(:paths)
-        paths = engine.config.paths["app/server_actions"]
-        if paths.respond_to?(:existent)
-          existent = paths.existent
-          return existent unless existent.empty?
-        end
-      end
-
-      return [] unless engine.respond_to?(:root) && engine.root
-
-      candidate = engine.root.join("app/server_actions")
-      candidate.directory? ? [candidate.to_s] : []
-    end
+    # @return [Array<Hash>, nil] the exposed v2 entries, or nil if the write was
+    #   skipped because routes were mid-draw.
+    def self.write_server_functions_snapshot!
+      return nil unless force_routes_loaded!
 
-    # Some engine subclasses are abstract (no `.instance` defined yet) or fail
-    # at `.instance` if their config block raises. Swallow those quietly —
-    # the gem's responsibility is to load whatever it can; engines whose
-    # `.instance` blows up will surface on first request anyway.
-    def self.safe_engine_instance(engine_class)
-      engine_class.instance
-    rescue StandardError
-      nil
+      Ruact::ServerFunctions.write_v2_snapshot!(
+        route_set: Rails.application.routes, root: Rails.root
+      )
     end
 
-    # Writes the server-functions JSON snapshot to tmp/cache/ruact/ on every
-    # config.to_prepare. The write is short-circuited when the registry payload
-    # is unchanged (Story 8.0a — pitfall #1: dev mode fires to_prepare per
-    # request; a naive rewrite would burn IOPS and confuse the Vite plugin's
-    # chokidar watcher).
+    # Idempotently force the route table to load. Returns true when the table is
+    # safely loaded (so the caller may read it), false when the force re-entered
+    # the boot finisher's in-progress draw (Rails < 8 raises `FrozenError`
+    # there) — in which case the caller must NOT write, leaving the table to the
+    # routes initializer + the later `after_initialize` write.
     #
-    # @return [Boolean] true if a fresh file was written, false if unchanged.
-    def self.write_server_functions_snapshot!
-      Ruact::ServerFunctions::Snapshot.generate!(
-        action_registry: Ruact.action_registry,
-        query_registry: Ruact.query_registry,
-        path: Rails.root.join("tmp/cache/ruact/server-functions.json")
-      )
+    # @return [Boolean] true if routes are safe to read, false if mid-draw.
+    def self.force_routes_loaded!
+      reloader = Rails.application.routes_reloader
+      return true unless reloader.respond_to?(:execute_unless_loaded)
+
+      reloader.execute_unless_loaded
+      true
+    rescue FrozenError
+      false
     end
 
     # Checks whether the manifest exists and either warns (dev) or raises (prod).

data/lib/ruact/server.rb

@@ -14,6 +14,7 @@ require_relative "../ruact"
 require_relative "server_functions/error_rendering"
 require_relative "server_functions/bucket_two_payload"
 require_relative "server_functions/name_bridge"
+require_relative "validation_errors_collector"
 
 module Ruact
   # Story 9.1 (route-driven redesign, Phase A) — the v2 server-functions
@@ -59,16 +60,16 @@ module Ruact
   #   Contract simplification: the concern assumes the host includes it after
   #   `protect_from_forgery`; no runtime callback-order verifier runs here.
   #
-  # Both bodies live in {Ruact::ServerFunctions::ErrorRendering}, shared with
-  # the v1 {Ruact::ServerFunctions::EndpointController} during the
-  # strangler-fig transition so the wire contract is identical by
-  # construction. Dual-bucket response negotiation (ivar serialization,
+  # Both bodies live in {Ruact::ServerFunctions::ErrorRendering} (Story 9.9 —
+  # this concern is now the sole home; the v1 endpoint that previously shared it
+  # was demolished). Dual-bucket response negotiation (ivar serialization,
   # `$redirect`, 204, `Vary: Accept`) is Story 9.2; this concern only
   # contributes the discrimination predicate 9.2 will reuse.
   module Server
     extend ActiveSupport::Concern
 
     include Ruact::ServerFunctions::ErrorRendering
+    include Ruact::ValidationErrorsCollector
 
     included do
       # Story 8.5 salvage — prepended so the size check wins the race against
@@ -159,7 +160,7 @@ module Ruact
           raise Ruact::ConfigurationError,
                 "ruact_function_name :#{action}, as: #{as.inspect} — " \
                 "\"#{js}\" is a reserved JS word or is already bound by the ruact runtime " \
-                "(`_makeRef` / `_makeServerFunction` / `revalidate`); pick another name"
+                "(`_makeServerFunction` / `_makeQuery` / `revalidate` / `useQuery`); pick another name"
         end
 
         __ruact_function_name_overrides[action.to_s] = js
@@ -194,7 +195,28 @@ module Ruact
     def default_render(*)
       return super unless __ruact_function_call?
 
-      assigns = view_assigns
+      # Story 13.3 (FR98) — the collector's framework-internal ivars (and a stray
+      # dev `@errors`) are dropped from the serialized assigns; Rails' own
+      # `view_assigns` only filters a fixed set of `@_` ivars, not every `@__`
+      # one (see {Ruact::ValidationErrorsCollector::RESERVED_ASSIGN_KEYS}).
+      assigns = view_assigns.except(*ValidationErrorsCollector::RESERVED_ASSIGN_KEYS)
+
+      # Story 13.3 (FR98, AC3) — when the host opted into the validation-error
+      # round-trip (`ruact_errors(@record)` was called this request), inject the
+      # collected errors under the reserved JSON key `"errors"` alongside the
+      # serialized ivars, even on an otherwise-empty assigns set: an opted-in
+      # success must still surface `{"errors": {}}` so the client's `await`
+      # result carries `result.errors` on a single code path.
+      if __ruact_errors_touched?
+        payload = ServerFunctions::BucketTwoPayload.build(
+          assigns, strict: Ruact.config.strict_serialization
+        )
+        payload["errors"] = __ruact_errors
+        return render(json: payload)
+      end
+
+      # An UNTOUCHED collector changes nothing — the 9.2 `204 No Content`
+      # empty-Bucket-2 contract is preserved.
       return head(:no_content) if assigns.empty?
 
       render json: ServerFunctions::BucketTwoPayload.build(