ruflet_rails 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91f92e0fef72cbb500ba43ac12d81590bac485bb9cf4642c93563aab2736811f
-  data.tar.gz: 609e6b2720465ca414898482223d561d264ddca837d717e07a2b54c1f874df6f
+  metadata.gz: aefcbfd0f43a7987f825223bcb14311816dc94a4e81039d6d955d504b51f01ae
+  data.tar.gz: d274aedaf03e16b8298b2fabd68a3dbd14aea153ac0abf0664a5198244aaf4df
 SHA512:
-  metadata.gz: 1f9e56edf7b86fccf776d7bfc8ee630ce501f42fde7854a9bb4f660a31ef85dfbe0e1a50ebe7a5c09dfe307e80eb88ca561a77d69777006a00810c34770dbba5
-  data.tar.gz: 23792bdae076841ddc0ed099475a25ab4bfd0240a244e90a0d71eb3d011c11c8e67e5610102bf8475a86e35dae2ea2aac6c8f58d1b75c1a8bf23ddf9682da60e
+  metadata.gz: 5d8fb4d2f5dfc8ab871999d0aed10672fc164790a13c4a9286ef079ff4f7777820b01e01188d3fcc605919d60e8ee79e8a085805c03ee5446805ab92d2f7dc56
+  data.tar.gz: 061b1e5641f03da87372ed31f47b841c9c9ab0f16a0cbd05639f8bfbf7aec5248879f2b8b608fb388c68f0dbe599976a2cfd1271005cf7883570fd58f511e5f8

data/README.md

@@ -16,20 +16,24 @@ gem "ruflet_rails", ">= 0.0.5"
 
 ```bash
 bin/rails generate ruflet:install
+bin/rails generate ruflet:install --web
+bin/rails generate ruflet:install --desktop
+bin/rails generate ruflet:install --web --desktop
 ```
 
 This generator will:
-- create `app/mobile/main.rb`
+- create `app/views/ruflet/main.rb`
 - create `ruflet.yaml`
 - add the Ruflet mount route to `config/routes.rb`
-- copy/configure `ruflet_client` when the template is available locally
+- download prebuilt clients from GitHub releases when `--web`, `--desktop`, or
+  `--client=web|desktop|all` is used
 
 Generated `ruflet.yaml`:
 
 ```yaml
 app:
   name: My App
-  ruflet_client_url: ""
+  backend_url: http://localhost:3000
 
 services: []
 
@@ -55,10 +59,147 @@ 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
+bundle exec rake ruflet:build[desktop]
+```
+
+Rails desktop builds are server-driven. The built desktop app connects back to the
+Rails backend configured in `ruflet.yaml`; it does not package a self-contained
+Ruby runtime.
+
+Plain Rails dev server commands do not launch the desktop app. Request a desktop
+client explicitly with a flag:
+
+```bash
+bin/dev --desktop
+bin/rails server --desktop
+bin/rails s --desktop
+```
+
+## Update prebuilt clients
+
+Uses the same GitHub release assets as `ruflet update`:
+
+```bash
+bundle exec rake ruflet:update[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.
+
+## Install mobile build
+
+Uses the same install pipeline as `ruflet install`:
+
+```bash
+bundle exec rake ruflet:install
+bundle exec rake ruflet:install[DEVICE_ID]
+```
+
+## Ruflet resource scaffolds
+
+Generate a Ruflet CRUD view for an existing Rails model:
+
+```bash
+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
+    # edit the scaffold layout here
+  end
+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.
+
+## Ruflet model forms
+
+Generate only a reusable Ruflet form for an existing Rails model:
+
+```bash
+bin/rails generate ruflet:form Post
+```
+
+When no fields are passed, the generator reads the model columns and skips `id`,
+`created_at`, and `updated_at`. You can also pass fields explicitly:
+
+```bash
+bin/rails generate ruflet:form Post title:string body:text published:boolean category:references
+```
+
+Foreign keys and references, such as `category:references` or `user_id`, render
+as Ruflet dropdowns populated from the associated Rails model.
+
+The generated form lives at `app/views/ruflet/components/posts/post_form.rb`.
+The form generator creates `app/views/ruflet/components/application_component.rb`
+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:
+
+```ruby
+# app/views/ruflet/components/page_title_component.rb
+class PageTitleComponent < ApplicationComponent
+  def render(value)
+    text(value, size: desktop? || web? ? 28 : 24, weight: "bold")
+  end
+end
+```
+
+```ruby
+# app/views/ruflet/posts/posts_view.rb
+class PostsView < RufletView
+  def render
+    page.add(PageTitleComponent.render(page, "Posts"))
+  end
+end
+```
+
 ## Manual usage
 
 ```ruby
-# app/mobile/main.rb
+# app/views/ruflet/main.rb
 require "ruflet"
 
 Ruflet.run do |page|
@@ -67,4 +208,10 @@ Ruflet.run do |page|
 end
 ```
 
-Connect mobile to Rails base URL, e.g. `http://10.0.2.2:3000`.
+Mount it in Rails:
+
+```ruby
+match "/ws", to: Ruflet::Rails.app(Rails.root.join("app/views/ruflet/main.rb")), via: :all
+```
+
+The same mounted Ruby entrypoint drives mobile, web, and desktop clients.

data/lib/generators/ruflet/form/form_generator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "active_support/core_ext/string/inflections"
+require "ruflet/rails/install_support"
+
+module Ruflet
+  module Generators
+    class FormGenerator < ::Rails::Generators::Base
+      argument :model_name, type: :string
+      argument :attributes, type: :array, default: [], banner: "field:type field:type"
+
+      desc "Generate only a Ruflet form for an existing Rails model."
+
+      def create_application_component
+        target = File.join(destination_root, Ruflet::Rails::InstallSupport.application_component_path)
+        return if File.exist?(target)
+
+        create_file target, Ruflet::Rails::InstallSupport.application_component_template
+      end
+
+      def create_ruflet_form
+        target = File.join(destination_root, form_view_path)
+
+        create_file(
+          target,
+          Ruflet::Rails::InstallSupport.form_view_template(
+            model_name: model_name,
+            attributes: form_attributes
+          )
+        )
+      end
+
+      def print_form_status
+        names = Ruflet::Rails::InstallSupport.model_names(model_name)
+        say "Ruflet form generated at #{form_view_path}"
+        say "Call #{names[:class_name]}Form.render(page, record: #{names[:class_name]}.new) from any Ruflet view."
+      end
+
+      private
+
+      def form_view_path
+        Ruflet::Rails::InstallSupport.form_view_path(model_name)
+      end
+
+      def form_attributes
+        return attributes unless attributes.empty?
+
+        model_class = model_name.to_s.camelize.safe_constantize
+        inferred = Ruflet::Rails::InstallSupport.attributes_from_model(model_class)
+        inferred.empty? ? attributes : inferred
+      end
+    end
+  end
+end

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

@@ -6,50 +6,88 @@ require "ruflet/rails/install_support"
 module Ruflet
   module Generators
     class InstallGenerator < ::Rails::Generators::Base
+      class_option :frontend, type: :boolean, default: false, desc: "Install the Rails-hosted Ruflet web client"
+      class_option :web, type: :boolean, default: false, desc: "Install the Rails-hosted 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: web, desktop, all, or none"
+
       desc "Install Ruflet into a Rails app."
 
-      def create_mobile_entrypoint
-        target = File.join(destination_root, "app/mobile/main.rb")
+      def create_app_entrypoint
+        target = File.join(destination_root, entrypoint_path)
         return if File.exist?(target)
 
-        FileUtils.mkdir_p(File.dirname(target))
-        File.write(
-          target,
-          Ruflet::Rails::InstallSupport.default_mobile_app_template(app_title: app_name)
-        )
+        create_file target, Ruflet::Rails::InstallSupport.default_app_template(app_title: app_name)
       end
 
       def create_ruflet_yaml
         target = File.join(destination_root, "ruflet.yaml")
         return if File.exist?(target)
 
-        File.write(
-          target,
-          Ruflet::Rails::InstallSupport.default_ruflet_yaml(app_name: app_name)
-        )
-      end
-
-      def copy_client_template
-        copied = Ruflet::Rails::InstallSupport.copy_ruflet_client_template(destination_root)
-        say_status(:warn, "ruflet_client template not found; add it manually before building", :yellow) unless copied
-      end
-
-      def configure_client_template
-        Ruflet::Rails::InstallSupport.configure_ruflet_client(destination_root)
+        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)
 
-        route = Ruflet::Rails::InstallSupport.route_snippet
+        route = Ruflet::Rails::InstallSupport.route_snippet(entrypoint: entrypoint_path)
         return if File.read(target).include?(route)
 
         insert_into_file target, "  #{route}\n", after: /Rails\.application\.routes\.draw do\s*\n/
       end
 
+      def add_desktop_flag_to_binstubs
+        return unless desktop_requested?
+
+        install_desktop_flag_bootstrap("bin/rails")
+        install_desktop_flag_bootstrap("bin/dev")
+      end
+
+      def download_prebuilt_client
+        client = requested_client
+        @web_client_published = false
+        return if client == "none"
+
+        if %w[web all].include?(client)
+          @web_client_published = Ruflet::Rails::InstallSupport.publish_web_build(destination_root)
+          if @web_client_published
+            say "Ruflet web build copied from build/web to public/#{Ruflet::Rails::InstallSupport.default_web_public_path}"
+            return if client == "web"
+          end
+        end
+
+        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)
+          return
+        end
+
+        return unless %w[web all].include?(client)
+
+        published = Ruflet::Rails::InstallSupport.publish_prebuilt_web_client(destination_root)
+        @web_client_published = published
+        if published
+          say "Ruflet web client published at /#{Ruflet::Rails::InstallSupport.default_web_public_path}/"
+        else
+          say_status(:warn, "Ruflet web client downloaded, but no prebuilt web index.html was found to publish", :yellow)
+        end
+      rescue StandardError => e
+        @client_download_failed = true
+        say_status(:warn, "Ruflet client download failed: #{e.class}: #{e.message}", :yellow)
+      end
+
       def print_install_status
-        say "ruflet.yaml generated"
+        Ruflet::Rails::InstallSupport.install_next_steps(
+          target: install_target,
+          entrypoint: entrypoint_path,
+          client: requested_client,
+          web_published: !!@web_client_published
+        ).each { |line| say line }
       end
 
       private
@@ -57,6 +95,57 @@ module Ruflet
       def app_name
         File.basename(destination_root).gsub(/[_-]+/, " ").split.map(&:capitalize).join(" ")
       end
+
+      def entrypoint_path
+        Ruflet::Rails::InstallSupport.default_entrypoint_path
+      end
+
+      def requested_client
+        explicit = options[:client].to_s.strip.downcase
+        unless explicit.empty?
+          raise Thor::Error, "--client must be web, desktop, all, or none" unless %w[web desktop all none].include?(explicit)
+
+          return explicit
+        end
+
+        wants_web = options[:frontend] || options[:web]
+        wants_desktop = options[:desktop]
+        return "all" if wants_web && wants_desktop
+        return "web" if wants_web
+        return "desktop" if wants_desktop
+
+        "none"
+      end
+
+      def desktop_requested?
+        %w[desktop all].include?(requested_client)
+      end
+
+      def install_target
+        "ruflet"
+      end
+
+      def install_desktop_flag_bootstrap(relative_path)
+        target = File.join(destination_root, relative_path)
+        return unless File.file?(target)
+
+        source = File.read(target)
+        return if source.include?("ruflet_rails desktop flag")
+
+        bootstrap =
+          if source.start_with?("#!/usr/bin/env ruby") || source.start_with?("#!/usr/bin/ruby")
+            if File.basename(relative_path) == "dev"
+              Ruflet::Rails::InstallSupport.ruby_dev_desktop_flag_bootstrap
+            else
+              Ruflet::Rails::InstallSupport.ruby_desktop_flag_bootstrap
+            end
+          elsif source.start_with?("#!/usr/bin/env sh") || source.start_with?("#!/bin/sh")
+            Ruflet::Rails::InstallSupport.shell_desktop_flag_bootstrap
+          end
+        return unless bootstrap
+
+        insert_into_file target, "#{bootstrap}\n", after: /\A#!.*\n/
+      end
     end
   end
 end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "active_support/core_ext/string/inflections"
+require "ruflet/rails/install_support"
+
+module Ruflet
+  module Generators
+    class ScaffoldGenerator < ::Rails::Generators::Base
+      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
+
+      def create_ruflet_resource_component
+        create_file(
+          File.join(destination_root, scaffold_component_path),
+          Ruflet::Rails::InstallSupport.scaffold_component_template(
+            model_name: model_name,
+            attributes: scaffold_attributes
+          )
+        )
+      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."
+      end
+
+      private
+
+      def scaffold_view_path
+        Ruflet::Rails::InstallSupport.scaffold_view_path(model_name)
+      end
+
+      def scaffold_component_path
+        Ruflet::Rails::InstallSupport.scaffold_component_path(model_name)
+      end
+
+      def scaffold_attributes
+        return attributes unless attributes.empty?
+
+        model_class = model_name.to_s.camelize.safe_constantize
+        inferred = Ruflet::Rails::InstallSupport.attributes_from_model(model_class)
+        inferred.empty? ? attributes : inferred
+      end
+    end
+  end
+end

data/lib/ruflet/rails/desktop_launcher.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Ruflet
+  module Rails
+    module DesktopLauncher
+      module_function
+
+      def launch_once(root:, argv: ARGV, env: ENV, wait: 1.0)
+        return false unless desktop_enabled?(root: root, argv: argv, env: env)
+        return false unless env["RUFLET_RAILS_DESKTOP_SERVER"].to_s.downcase == "true" || rails_server_command?(argv)
+        return false if env["RUFLET_RAILS_DESKTOP"].to_s.downcase == "false"
+        return false if launched?
+
+        @launched = true
+        url = backend_url(root: root, argv: argv, env: env)
+        Thread.new do
+          sleep wait.to_f if wait.to_f.positive?
+          launch(url, root: root)
+        end
+        true
+      end
+
+      def launch(url, root:)
+        require "ruflet/cli"
+
+        Dir.chdir(root.to_s) do
+          wait_for_backend(url)
+          if Ruflet::CLI.respond_to?(:launch_desktop_client, true)
+            Ruflet::CLI.send(:launch_desktop_client, url)
+          else
+            warn "Ruflet desktop launcher is unavailable in this ruflet version."
+            nil
+          end
+        end
+      rescue StandardError => e
+        warn "Failed to launch Ruflet desktop client: #{e.class}: #{e.message}"
+        nil
+      end
+
+      def backend_url(root:, argv: ARGV, env: ENV)
+        explicit = env["RUFLET_BACKEND_URL"].to_s.strip
+        return explicit unless explicit.empty?
+
+        config_url = ruflet_yaml_backend_url(root)
+        cli_port = rails_server_port(argv)
+        return replace_url_port(config_url, cli_port) if cli_port
+        return config_url if config_url
+
+        "http://localhost:#{env["PORT"].to_s.empty? ? 3000 : env["PORT"]}"
+      end
+
+      def desktop_enabled?(root:, argv: ARGV, env: ENV)
+        return true if env["RUFLET_RAILS_DESKTOP_SERVER"].to_s.downcase == "true"
+        return true if env["RUFLET_RAILS_DESKTOP"].to_s.downcase == "true"
+        return true if Array(argv).map(&:to_s).include?("--desktop")
+
+        false
+      end
+
+      def rails_server_command?(argv)
+        command = Array(argv).find { |value| !value.to_s.start_with?("-") }.to_s
+        %w[server s].include?(command)
+      end
+
+      def rails_server_port(argv)
+        values = Array(argv).map(&:to_s)
+        values.each_with_index do |value, index|
+          return values[index + 1].to_i if %w[-p --port].include?(value) && values[index + 1].to_i.positive?
+          return value.split("=", 2).last.to_i if value.start_with?("--port=") && value.split("=", 2).last.to_i.positive?
+        end
+        nil
+      end
+
+      def ruflet_yaml_backend_url(root)
+        path = %w[ruflet.yaml ruflet.yml].map { |name| File.join(root.to_s, name) }.find { |candidate| File.file?(candidate) }
+        return nil unless path
+
+        require "yaml"
+        config = YAML.safe_load(File.read(path), aliases: true) || {}
+        value = config.dig("app", "backend_url") || config["backend_url"] || config["server_url"]
+        value.to_s.strip.empty? ? nil : value.to_s.strip
+      rescue StandardError
+        nil
+      end
+
+      def replace_url_port(url, port)
+        return "http://localhost:#{port}" if url.to_s.strip.empty?
+
+        uri = URI.parse(url)
+        uri.port = port.to_i
+        uri.to_s
+      rescue URI::InvalidURIError
+        "http://localhost:#{port}"
+      end
+
+      def wait_for_backend(url)
+        return unless Ruflet::CLI.respond_to?(:wait_for_server_boot, true)
+
+        uri = URI.parse(url)
+        Ruflet::CLI.send(:wait_for_server_boot, uri.port) if uri.port
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      def launched?
+        !!@launched
+      end
+
+      def reset!
+        @launched = false
+      end
+    end
+  end
+end