ruflet_rails 0.0.10 → 0.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ffd81f0143fcba01b93a6d0f773d1d0e4aa983a01c4bf282ed383a631273b13
-  data.tar.gz: 8840d1be44c36b8d82789f9a9d8055bd2ab0f8e893bafe1fc2ab6f8f082f90d0
+  metadata.gz: d142d63121dae012354a763ef756504d64534adbc4b2c11eaf0dc51b514c6b32
+  data.tar.gz: d3d1e6cbf9af94c81d5514b71325484e547b40ba34afe3d8601a111f08e4af6a
 SHA512:
-  metadata.gz: 456e8aaf3966f272a7b5b0945163a8f96955c240577fb5a1f4f5023ec635260eb531872505e03d552199f6d52c5a68839cbb3a2a4115d82d25f3e1c0bcf95765
-  data.tar.gz: a63099e903e698ceb130f8b678deaa8a2cb238335266615704fdac47b41f1775fc8e1d677789bab3c6a3961034173d323719325ac159d1b679b4dfd772636a03
+  metadata.gz: daf5bf66b258ece12da18cbb4c455d2f9f5dd141faa3638c2ef0ec9a64d85be9b25d94add15ae0374a96c6694f6e393ee015290df62368bd1d9cd6920a3185f3
+  data.tar.gz: 075def7cfb22688619559ba1ca55ede0d4c152c403c95a2273c1fa322a2862b20aafe7bda0507bf73bb4a8e8f40e03eb6c87b9505900fb31aa3ac08098dbf88b

data/README.md

@@ -24,7 +24,8 @@ bin/rails generate ruflet:install --web --desktop
 This generator will:
 - create `app/views/ruflet/main.rb`
 - create `ruflet.yaml`
-- add the Ruflet mount route to `config/routes.rb`
+- add the Ruflet WebSocket route to `config/routes.rb`
+- add a `/ruflet` web mount when `--web` is used
 - download prebuilt clients from GitHub releases when `--web`, `--desktop`, or
   `--client=web|desktop|all` is used
 
@@ -44,12 +45,30 @@ assets:
 
 For Rails apps, those asset paths are resolved from `app/assets/` during build.
 
-## Build client from Rails
+## Web client
 
-Uses the same build pipeline as `ruflet build`:
+Rails installs the prebuilt web client into `frontend/`; it does not need
+Flutter source or a Flutter web build:
+
+```bash
+bundle exec rake ruflet:web
+```
+
+Mount the installed client and a developer-owned Ruflet entrypoint:
+
+```ruby
+mount Ruflet::Rails.web_app(app_file: Rails.root.join("app/views/ruflet/main.rb")), at: "/app"
+```
+
+The install generator adds the same mount at `/ruflet` when `--web` is used.
+The mount serves the static client and its WebSocket endpoint together. The
+same `main.rb` also drives native clients through the generated `/ws` route.
+
+## Build native clients from Rails
+
+Uses the same native build pipeline as `ruflet build`:
 
 ```bash
-bundle exec rake ruflet:build[web]
 bundle exec rake ruflet:build[macos]
 bundle exec rake ruflet:build[windows]
 bundle exec rake ruflet:build[linux]
@@ -59,8 +78,6 @@ bundle exec rake ruflet:build[ios]
 bundle exec rake ruflet:build[aab]
 ```
 
-Rails web builds are published to `public/ruflet` and served by Rails at `/ruflet/`.
-
 `desktop` is also accepted as a host-platform alias:
 
 ```bash
@@ -82,16 +99,14 @@ bin/rails s --desktop
 
 ## Update prebuilt clients
 
-Uses the same GitHub release assets as `ruflet update`:
+Reinstall web or update native desktop clients:
 
 ```bash
-bundle exec rake ruflet:update[web]
+bundle exec rake ruflet:web
 bundle exec rake ruflet:update[desktop]
-bundle exec rake ruflet:update[all]
 ```
 
-For web, the downloaded static client is published to `public/ruflet` and served
-by Rails at `/ruflet/`. The Rails app does not vendor Flutter source code.
+The Rails app does not vendor Flutter source code.
 
 ## Install mobile build
 
@@ -104,7 +119,7 @@ bundle exec rake ruflet:install[DEVICE_ID]
 
 ## Ruflet resource scaffolds
 
-Generate a Ruflet CRUD view for an existing Rails model:
+Generate a mountable Ruflet CRUD component for an existing Rails model:
 
 ```bash
 bin/rails generate ruflet:scaffold Post
@@ -113,30 +128,6 @@ bin/rails generate ruflet:scaffold Post
 The scaffold creates generated app code the Rails developer can own and edit:
 
 ```ruby
-# app/views/ruflet/posts_view.rb
-require_relative "components/posts/post_component"
-
-class PostView < RufletView
-  include Ruflet::Rails::FormHelpers
-
-  route "/posts"
-
-  def render
-    page.title = resource_title
-    render_index
-  end
-
-  private
-
-  def records
-    # edit resource query logic here
-  end
-
-  def component
-    @component ||= PostComponent.new(page, controller: self)
-  end
-end
-
 # app/views/ruflet/components/posts/post_component.rb
 class PostComponent < Ruflet::Rails::ResourceComponent
   def render
@@ -145,11 +136,16 @@ class PostComponent < Ruflet::Rails::ResourceComponent
 end
 ```
 
-The generated view contains the resource logic: query, model helpers, field
-introspection, save/delete, dialog close, and display formatting. The generated
-component contains the UI: tables, lists, and dialogs. `ruflet_rails` only
-provides the base classes and generic helpers. The generator does not dump field
-declarations like `title:string` or literal metadata tables into the app.
+Mount it explicitly in `config/routes.rb`:
+
+```ruby
+mount Ruflet::Rails.web_app(view: "PostComponent"), at: "/posts"
+```
+
+The generated component contains the developer-owned UI and persistence calls.
+`ruflet_rails` provides the reusable model, navigation, dialog, and formatting
+helpers. Component files under `app/views/ruflet/components` are loaded by the
+Railtie so both web mounts and `main.rb` can reference them.
 
 ## Ruflet model forms
 
@@ -175,8 +171,8 @@ when that base component does not already exist.
 
 ## Shared Ruflet components
 
-Put shared Ruflet UI components under `app/views/ruflet/components`. Component
-files are loaded before `*_view.rb` files, so views can call them directly:
+Put shared Ruflet UI components under `app/views/ruflet/components`. Those files
+are reloaded with Rails application code:
 
 ```ruby
 # app/views/ruflet/components/page_title_component.rb
@@ -188,11 +184,9 @@ end
 ```
 
 ```ruby
-# app/views/ruflet/posts/posts_view.rb
-class PostsView < RufletView
-  def render
-    page.add(PageTitleComponent.render(page, "Posts"))
-  end
+# app/views/ruflet/main.rb
+Ruflet.run do |page|
+  page.add(PageTitleComponent.render(page, "Posts"))
 end
 ```
 

data/lib/generators/ruflet/install/install_generator.rb

@@ -6,8 +6,9 @@ require "ruflet/rails/install_support"
 module Ruflet
   module Generators
     class InstallGenerator < ::Rails::Generators::Base
+      class_option :web, type: :boolean, default: false, desc: "Install the prebuilt Ruflet web client"
       class_option :desktop, type: :boolean, default: false, desc: "Download the server-driven desktop Ruflet client"
-      class_option :client, type: :string, default: nil, desc: "Download prebuilt client from GitHub releases: desktop or none"
+      class_option :client, type: :string, default: nil, desc: "Install prebuilt clients: web, desktop, all, or none"
 
       desc "Install Ruflet into a Rails app."
 
@@ -25,15 +26,24 @@ module Ruflet
         create_file target, Ruflet::Rails::InstallSupport.default_ruflet_yaml(app_name: app_name)
       end
 
-      def add_routes
-        target = File.join(destination_root, "config/routes.rb")
-        return unless File.file?(target)
+      # Mount the native WebSocket endpoint explicitly in config/routes.rb.
+      # Nothing is auto-mounted — the dev owns the route, like any other.
+      def mount_websocket
+        routes = File.join(destination_root, "config", "routes.rb")
+        return unless File.file?(routes)
+        return if File.read(routes).include?("Ruflet::Rails.app(")
 
-        route = Ruflet::Rails::InstallSupport.route_snippet(entrypoint: entrypoint_path)
-        source = File.read(target)
-        return if source.include?(route)
+        route Ruflet::Rails::InstallSupport.route_snippet(entrypoint: entrypoint_path)
+      end
+
+      def mount_web_app
+        return unless web_requested?
+
+        routes = File.join(destination_root, "config", "routes.rb")
+        return unless File.file?(routes)
+        return if File.read(routes).include?("Ruflet::Rails.web_app(")
 
-        insert_into_file target, "  #{route}\n", after: /Rails\.application\.routes\.draw do\s*\n/
+        route Ruflet::Rails::InstallSupport.web_route_snippet(entrypoint: entrypoint_path)
       end
 
       def add_desktop_flag_to_binstubs
@@ -47,14 +57,8 @@ module Ruflet
         client = requested_client
         return if client == "none"
 
-        require "ruflet/cli"
-        exit_code = Dir.chdir(destination_root) do
-          Ruflet::CLI.command_update([client])
-        end
-        unless exit_code.to_i.zero?
-          @client_download_failed = true
-          say_status(:warn, "Ruflet client download failed; install files were generated and build/update steps are printed below", :yellow)
-        end
+        install_web_client if %w[web all].include?(client)
+        install_desktop_client if %w[desktop all].include?(client)
       rescue StandardError => e
         @client_download_failed = true
         say_status(:warn, "Ruflet client download failed: #{e.class}: #{e.message}", :yellow)
@@ -81,24 +85,47 @@ module Ruflet
       def requested_client
         explicit = options[:client].to_s.strip.downcase
         unless explicit.empty?
-          raise Thor::Error, "--client must be desktop or none" unless %w[desktop none].include?(explicit)
+          raise Thor::Error, "--client must be web, desktop, all, or none" unless %w[web desktop all none].include?(explicit)
 
           return explicit
         end
 
+        return "all" if options[:web] && options[:desktop]
+        return "web" if options[:web]
         return "desktop" if options[:desktop]
 
         "none"
       end
 
       def desktop_requested?
-        requested_client == "desktop"
+        %w[desktop all].include?(requested_client)
+      end
+
+      def web_requested?
+        %w[web all].include?(requested_client)
       end
 
       def install_target
         "ruflet"
       end
 
+      def install_web_client
+        return if Ruflet::Rails::WebInstaller.install!(root: destination_root)
+
+        client_download_failed("web")
+      end
+
+      def install_desktop_client
+        require "ruflet/cli"
+        exit_code = Dir.chdir(destination_root) { Ruflet::CLI.command_update(["desktop"]) }
+        client_download_failed("desktop") unless exit_code.to_i.zero?
+      end
+
+      def client_download_failed(client)
+        @client_download_failed = true
+        say_status(:warn, "Ruflet #{client} client download failed; install files were still generated", :yellow)
+      end
+
       def install_desktop_flag_bootstrap(relative_path)
         target = File.join(destination_root, relative_path)
         return unless File.file?(target)

data/lib/generators/ruflet/scaffold/scaffold_generator.rb

@@ -10,17 +10,7 @@ module Ruflet
       argument :model_name, type: :string
       argument :attributes, type: :array, default: [], banner: "field:type field:type"
 
-      desc "Generate a Rails-first Ruflet resource view for an existing model."
-
-      def create_ruflet_resource_view
-        create_file(
-          File.join(destination_root, scaffold_view_path),
-          Ruflet::Rails::InstallSupport.scaffold_view_template(
-            model_name: model_name,
-            attributes: scaffold_attributes
-          )
-        )
-      end
+      desc "Generate a Rails-first Ruflet resource component for an existing model."
 
       def create_ruflet_resource_component
         create_file(
@@ -33,15 +23,19 @@ module Ruflet
       end
 
       def print_scaffold_status
-        say "Ruflet scaffold generated at #{scaffold_view_path}"
-        say "Ruflet UI component generated at #{scaffold_component_path}"
-        say "The generated view owns the resource logic; the generated component owns the UI."
+        say "Ruflet resource component generated at #{scaffold_component_path}"
+        say "Mount it in config/routes.rb:"
+        say "  mount Ruflet::Rails.web_app(view: #{scaffold_component_class.inspect}), at: \"/#{scaffold_route_segment}\""
       end
 
       private
 
-      def scaffold_view_path
-        Ruflet::Rails::InstallSupport.scaffold_view_path(model_name)
+      def scaffold_component_class
+        "#{model_name.to_s.camelize}Component"
+      end
+
+      def scaffold_route_segment
+        model_name.to_s.underscore.pluralize
       end
 
       def scaffold_component_path

data/lib/ruflet/rails/assets.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Ruflet
+  module Rails
+    # Resolve Rails assets to absolute URLs the Flutter client can load over
+    # HTTP, so server-driven UI can show app images:
+    #
+    #   image(src: Ruflet::Rails.asset_url("logo.png"))
+    #   image(src: Ruflet::Rails.image_url("brand/header.png"), fit: "cover")
+    #
+    # The *path* comes from the Rails asset pipeline — digested in production
+    # (/assets/logo-<digest>.png), plain otherwise — so it survives
+    # fingerprinting and CDNs. The *host* is resolved, in order, from:
+    #
+    #   1. an explicit `host:` argument
+    #   2. Ruflet::Rails.config.backend_url
+    #   3. the host the client connected on (the live WebSocket request)
+    #
+    # The client is a separate device (simulator, phone, browser), so a bare
+    # "/assets/..." path would not resolve — the URL must be absolute. If Rails
+    # already has an asset_host/CDN configured, the pipeline returns an absolute
+    # URL and it is used unchanged. A value that is already a full URL passes
+    # through untouched.
+    module_function
+
+    # The base URL the Flutter client uses to reach this Rails app — the single
+    # source of truth for asset URLs, the build-time RUFLET_URL define and the
+    # desktop launcher. A Rails Ruflet app always needs one, so this always
+    # resolves to a usable value:
+    #
+    #   1. an explicit host: argument
+    #   2. Ruflet::Rails.config.backend_url (set it in config/initializers/ruflet.rb)
+    #   3. the host the client connected on (the live WebSocket request)
+    #
+    # Returns "" only when none of those are available (e.g. a build with no
+    # configured backend_url) — set config.backend_url to cover that case.
+    def backend_url(host: nil)
+      candidate = host || config.backend_url
+      candidate = request_base_url if candidate.to_s.strip.empty?
+      candidate.to_s.strip.sub(%r{/+\z}, "")
+    end
+
+    def asset_url(source, host: nil)
+      raw = source.to_s
+      return raw if absolute_url?(raw)
+
+      path = asset_pipeline_path(raw)
+      return path if absolute_url?(path)
+
+      base = backend_url(host: host)
+      base.empty? ? path : "#{base}#{path}"
+    end
+
+    # Readability alias for image sources — identical resolution.
+    def image_url(source, host: nil)
+      asset_url(source, host: host)
+    end
+
+    def asset_pipeline_path(source)
+      ::ActionController::Base.helpers.asset_path(source)
+    rescue StandardError
+      source.start_with?("/") ? source : "/#{source}"
+    end
+    private_class_method :asset_pipeline_path
+
+    # Derive scheme://host from the live WebSocket request env so the URL points
+    # back at the exact host the client reached — the one address guaranteed to
+    # be reachable from that device.
+    def request_base_url
+      env = Protocol::Context.current_env
+      return nil unless env
+
+      host = env["HTTP_X_FORWARDED_HOST"] || env["HTTP_HOST"]
+      return nil if host.to_s.strip.empty?
+
+      scheme = (env["HTTP_X_FORWARDED_PROTO"] || env["rack.url_scheme"] || "http").to_s.split(",").first.to_s.strip
+      scheme = "http" if scheme.empty?
+      "#{scheme}://#{host}"
+    end
+    private_class_method :request_base_url
+
+    def absolute_url?(value)
+      !(value.to_s =~ %r{\A[a-z][a-z0-9+.-]*://}i).nil?
+    end
+    private_class_method :absolute_url?
+  end
+end

data/lib/ruflet/rails/configuration.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Ruflet
+  module Rails
+    # Central configuration for ruflet_rails.
+    #
+    # An install needs no config/initializers/ruflet.rb: routes mount
+    # app/views/ruflet/main.rb explicitly and build metadata is read from
+    # ruflet.yaml. Add an initializer only to override these settings:
+    #
+    #   Ruflet::Rails.configure do |config|
+    #     # Runtime / server
+    #     config.backend_url = Rails.env.production? ? "https://example.com" : "http://localhost:3000"
+    #
+    #     # App metadata (ruflet.yaml → app:)
+    #     config.app_name = "My App"
+    #
+    #     # Services (ruflet.yaml → services:)
+    #     config.services = []
+    #
+    #     # Assets (ruflet.yaml → assets:)
+    #     config.splash_screen = Rails.root.join("app/assets/images/splash.png")
+    #     config.splash_dark   = Rails.root.join("app/assets/images/splash_dark.png")
+    #     config.icon_launcher = Rails.root.join("app/assets/images/icon.png")
+    #     config.icon_android  = Rails.root.join("app/assets/images/icon_android.png")
+    #     config.icon_ios      = Rails.root.join("app/assets/images/icon_ios.png")
+    #     config.icon_web      = Rails.root.join("app/assets/images/icon_web.png")
+    #     config.icon_windows  = Rails.root.join("app/assets/images/icon_windows.png")
+    #     config.icon_macos    = Rails.root.join("app/assets/images/icon_macos.png")
+    #
+    #     # Build options (ruflet.yaml → build:)
+    #     config.splash_color      = "#FFFFFF"
+    #     config.splash_dark_color = "#000000"
+    #     config.icon_background   = "#FFFFFF"
+    #     config.theme_color       = "#FFFFFF"
+    #   end
+    class Configuration
+      # --- Runtime / server ---
+
+      # Backend base URL. Used as --dart-define=RUFLET_URL at build time
+      # and by the desktop launcher. Replaces ruflet.yaml → app.backend_url.
+      attr_accessor :backend_url
+
+      # --- App metadata (ruflet.yaml → app:) ---
+
+      attr_accessor :app_name
+
+      # --- Services (ruflet.yaml → services:) ---
+
+      attr_accessor :services
+
+      # --- Assets (ruflet.yaml → assets:) ---
+
+      attr_accessor :splash_screen
+      attr_accessor :splash_dark
+      attr_accessor :icon_launcher
+      attr_accessor :icon_android
+      attr_accessor :icon_ios
+      attr_accessor :icon_web
+      attr_accessor :icon_windows
+      attr_accessor :icon_macos
+
+      # --- Build options (ruflet.yaml → build:) ---
+
+      attr_accessor :splash_color
+      attr_accessor :splash_dark_color
+      attr_accessor :icon_background
+      attr_accessor :theme_color
+
+      def initialize
+        @backend_url = nil
+        @app_name = nil
+        @services = []
+      end
+
+      # Serialises config to the ruflet.yaml hash structure so the CLI can
+      # consume it without a yaml file on disk (written to a temp file by
+      # the Railtie's build task).
+      def to_ruflet_yaml_hash
+        hash = {}
+
+        app = {}
+        app["name"]        = @app_name    if @app_name
+        app["backend_url"] = @backend_url if @backend_url
+        hash["app"] = app unless app.empty?
+
+        hash["services"] = Array(@services)
+
+        assets = {}
+        assets["splash_screen"] = @splash_screen.to_s if @splash_screen
+        assets["splash_dark"]   = @splash_dark.to_s   if @splash_dark
+        assets["icon_launcher"] = @icon_launcher.to_s  if @icon_launcher
+        assets["icon_android"]  = @icon_android.to_s   if @icon_android
+        assets["icon_ios"]      = @icon_ios.to_s        if @icon_ios
+        assets["icon_web"]      = @icon_web.to_s        if @icon_web
+        assets["icon_windows"]  = @icon_windows.to_s    if @icon_windows
+        assets["icon_macos"]    = @icon_macos.to_s      if @icon_macos
+        hash["assets"] = assets unless assets.empty?
+
+        build = {}
+        build["splash_color"]      = @splash_color      if @splash_color
+        build["splash_dark_color"] = @splash_dark_color if @splash_dark_color
+        build["icon_background"]   = @icon_background   if @icon_background
+        build["theme_color"]       = @theme_color       if @theme_color
+        hash["build"] = build unless build.empty?
+
+        hash
+      end
+    end
+  end
+end