ruby_native 0.13.0 → 0.14.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c31d1051712c237ce11a48f7ab2681ac6083c81f8fc1bb155c918f7283390d79
-  data.tar.gz: 7f3f059d502a92a389b5110cd3e8f0028adfece442dee9e44f29f2d6d5629bff
+  metadata.gz: 50767dda7ff4152200308b0a1fedfe0718a37f2dc44d30a826c2a5002931b466
+  data.tar.gz: 389fca631075081cd61d842992cf656ce86869d49b1edce7dd4fcf00b21893df
 SHA512:
-  metadata.gz: 15d77625c818cd4a63f82b1e03490a7365b3a91cd1c75e41ca893f64d9813c197683f27198e9aaa7fc96a2eb25f702f042e55cd8e333fa9812749cea9d16839c
-  data.tar.gz: b7cca8fcc74f7151a6eabfe2706f5644cb6e51ccf7cb9f375c60a029c036565005a9d9d1dd698dd517f08529ba98ad8126006f39e6540b2e43b2df68957c3b46
+  metadata.gz: 8c6e2010a14b01628306fc6be5c22168a1f6077276d98ccaed5c96c271c9cdf9b8cf101719a2458cfb1fe844211ef3fc1845ebc7eb8b02a5a0ed168bbe59b4da
+  data.tar.gz: 53f833324974af66b48e44caec11ba90b259cb40e32a0ff670b37b92ca02f887f20ebe18a415fa731f390ae9a344647e43580173c9c27250dea86d7060bc46fc

data/README.md

@@ -80,6 +80,10 @@ See [rubynative.com/docs/cli](https://rubynative.com/docs/cli) for `deploy`, `lo
 
 Building with Inertia instead of ERB? `@ruby-native/react` and `@ruby-native/vue` provide the same helpers as npm packages, versioned alongside this gem. See [rubynative.com/docs/inertia](https://rubynative.com/docs/inertia) for setup.
 
+## AI agents
+
+Every docs page serves markdown: append `.md` to the URL or request `Accept: text/markdown`. For an index of everything, fetch [rubynative.com/llms.txt](https://rubynative.com/llms.txt), or [llms-full.txt](https://rubynative.com/llms-full.txt) for the complete docs as a single file.
+
 ## License
 
 MIT.

data/app/controllers/ruby_native/config_controller.rb

@@ -2,8 +2,16 @@ module RubyNative
   class ConfigController < ::ActionController::Base
     def show
       RubyNative.load_config if Rails.env.local?
+      # The version header stays on the 404 so `ruby_native preview` can tell
+      # missing config apart from an unmounted engine.
       response.set_header("X-Ruby-Native-Version", RubyNative::VERSION)
-      render json: RubyNative.config_as_json
+
+      config = RubyNative.config_as_json
+      if config.nil?
+        render json: { error: "config/ruby_native.yml is missing or empty" }, status: :not_found
+      else
+        render json: config
+      end
     end
   end
 end

data/lib/generators/ruby_native/templates/ruby_native.yml

@@ -56,6 +56,20 @@ appearance:
   #   # Omit to let the system decide.
   #   status_bar: light
 
+  # On Android, the bars are a neutral gray, light or dark to match the theme,
+  # with tint_color on the selected tab, matching iOS. Override either bar
+  # here; iOS keeps the system Liquid Glass bars. (The floating action button
+  # is colored per page from native_fab_tag instead.)
+  # https://rubynative.com/docs/appearance#android-chrome-colors
+  # android:
+  #   navbar:
+  #     # Each accepts a hex string, or { light:, dark: } for dark mode support.
+  #     background_color: "#1E293B"
+  #     # Title and icon color. Defaults to black or white, picked for contrast.
+  #     foreground_color: "#FFFFFF"
+  #   tab_bar:
+  #     background_color: "#1E293B"
+
   # Show a launch splash while the first screen loads. It holds your launch icon
   # and background_color in frame, with a spinner, until the web content paints.
   # Off by default; set enabled: true to turn it on.

data/lib/ruby_native/cli/credentials.rb

@@ -4,28 +4,42 @@ require "fileutils"
 module RubyNative
   class CLI
     class Credentials
-      PATH = File.join(Dir.home, ".ruby_native", "credentials")
+      class << self
+        attr_writer :path
+      end
+
+      # Lazy: Dir.home raises in HOME-less containers, and that must not kill
+      # commands that only use RUBY_NATIVE_TOKEN.
+      def self.path
+        @path ||= File.join(Dir.home, ".ruby_native", "credentials")
+      end
 
       def self.token
-        ENV["RUBY_NATIVE_TOKEN"] || file_token
+        env_token || file_token
+      end
+
+      # A misspelled CI secret interpolates to "", which must not shadow the
+      # credentials file or `ruby_native login` can never fix auth.
+      def self.env_token
+        value = ENV["RUBY_NATIVE_TOKEN"].to_s.strip
+        value unless value.empty?
       end
 
       def self.file_token
-        return unless File.exist?(PATH)
-        JSON.parse(File.read(PATH))["token"]
-      rescue JSON::ParserError
+        return unless File.exist?(path)
+        JSON.parse(File.read(path))["token"]
+      rescue JSON::ParserError, ArgumentError
         nil
       end
 
       def self.save(token)
-        dir = File.dirname(PATH)
-        FileUtils.mkdir_p(dir)
-        File.write(PATH, JSON.generate(token: token))
-        File.chmod(0600, PATH)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, JSON.generate(token: token))
+        File.chmod(0600, path)
       end
 
       def self.clear
-        File.delete(PATH) if File.exist?(PATH)
+        File.delete(path) if File.exist?(path)
       end
     end
   end

data/lib/ruby_native/cli/deploy.rb

@@ -1,6 +1,7 @@
 require "json"
 require "net/http"
 require "uri"
+require "openssl"
 require "ruby_native/cli/credentials"
 require "ruby_native/version"
 
@@ -11,8 +12,22 @@ module RubyNative
       HOST = ENV.fetch("RUBY_NATIVE_HOST", "https://rubynative.com")
       POLL_INTERVAL = 5
       POLL_TIMEOUT = 600
+      PLATFORMS = %w[ios android].freeze
+      # Consecutive failures tolerated mid-poll; one blip must not kill a
+      # deploy whose build is succeeding server-side.
+      MAX_POLL_FAILURES = 3
 
       TokenExpiredError = Class.new(StandardError)
+      ConnectionError = Class.new(StandardError)
+
+      NETWORK_ERRORS = [
+        SocketError,
+        Errno::ECONNREFUSED,
+        Errno::ECONNRESET,
+        Net::OpenTimeout,
+        Net::ReadTimeout,
+        OpenSSL::SSL::SSLError
+      ].freeze
 
       def initialize(argv)
         @if_needed = argv.include?("--if-needed")
@@ -33,15 +48,37 @@ module RubyNative
         return if @if_needed
 
         poll_build_status(app_id, build)
+      rescue TokenExpiredError
+        abort_token_expired!
+      rescue ConnectionError => error
+        puts error.message
+        puts "Check your internet connection and run `ruby_native deploy` again."
+        exit 1
       end
 
       private
 
       def ensure_authenticated!
-        unless Credentials.token
+        return if Credentials.token
+
+        if ENV.key?("RUBY_NATIVE_TOKEN")
+          puts "RUBY_NATIVE_TOKEN is set but empty, so there is no usable token."
+          puts "Check the CI secret it references, or unset it and run `ruby_native login`."
+        else
           puts "Not logged in. Run `ruby_native login` first."
-          exit 1
         end
+        exit 1
+      end
+
+      def abort_token_expired!
+        if Credentials.env_token
+          puts "The server rejected your token."
+          puts "RUBY_NATIVE_TOKEN is set and overrides `ruby_native login`, so update"
+          puts "that environment variable with a fresh token."
+        else
+          puts "Token expired. Run `ruby_native login` again."
+        end
+        exit 1
       end
 
       def load_config!
@@ -50,8 +87,36 @@ module RubyNative
           exit 1
         end
 
+        @config = read_config
+      end
+
+      def read_config
         require "yaml"
-        @config = YAML.load_file(CONFIG_PATH, symbolize_names: true) || {}
+        YAML.load(rendered_config, filename: CONFIG_PATH, symbolize_names: true, aliases: true) || {}
+      rescue Psych::SyntaxError => error
+        puts "config/ruby_native.yml has a YAML syntax error:"
+        puts "  #{error.message}"
+        puts "Fix it and run `ruby_native deploy` again."
+        exit 1
+      end
+
+      # Rails renders this file as ERB before parsing, so the CLI must too or
+      # any <% %> tag breaks deploys while the app works fine.
+      def rendered_config
+        require "erb"
+        ERB.new(File.read(CONFIG_PATH), trim_mode: "-").result(erb_stub_binding)
+      rescue StandardError, SyntaxError
+        # A template only Rails can render still deploys; the CLI needs just app_id.
+        File.read(CONFIG_PATH)
+      end
+
+      # View helpers like image_url do not exist outside Rails; render them to
+      # "" rather than failing the deploy over values the CLI never reads.
+      def erb_stub_binding
+        stub = Object.new
+        def stub.method_missing(*, **) = ""
+        def stub.respond_to_missing?(*) = true
+        stub.instance_eval { binding }
       end
 
       def resolve_app_id!
@@ -94,7 +159,7 @@ module RubyNative
         when Net::HTTPNoContent
           nil
         when Net::HTTPSuccess
-          JSON.parse(response.body)
+          parse_json(response)
         when Net::HTTPUnauthorized
           raise TokenExpiredError
         else
@@ -119,30 +184,36 @@ module RubyNative
         when Net::HTTPUnauthorized
           raise TokenExpiredError
         when Net::HTTPCreated
-          build = JSON.parse(response.body)
+          build = parse_json(response)
+          unless build
+            puts "The build was queued, but its details could not be read."
+            puts "Check the Ruby Native dashboard for progress: #{HOST}/dashboard"
+            exit 0
+          end
           puts "Build ##{build["number"]} (v#{build["version"]}) queued."
+          print_notice(build)
           build
         when Net::HTTPTooManyRequests
           puts "Build limit reached. Try again later."
           exit 1
         when Net::HTTPConflict
-          data = JSON.parse(response.body)
-          puts data["error"]
+          data = parse_json(response)
+          puts data&.dig("error") || "A build is already in progress. Check the Ruby Native dashboard."
           exit 1
         when Net::HTTPUnprocessableEntity
-          data = JSON.parse(response.body)
-          puts "Cannot build: #{data["error"]}"
+          data = parse_json(response)
+          puts "Cannot build: #{data&.dig("error") || "the server rejected the request (422)."}"
           exit 1
         when Net::HTTPNotFound
-          puts "App not found. Remove ruby_native.app_id from config/ruby_native.yml and run `ruby_native deploy` again to re-link."
+          puts "The app linked in config/ruby_native.yml was not found on your account."
+          puts "It may have been archived. Check your apps first: #{HOST}/dashboard"
+          puts "If you meant to link a different app, remove `app_id` from"
+          puts "config/ruby_native.yml and run `ruby_native deploy` again."
           exit 1
         else
           puts "Failed to trigger build: #{response.code} #{response.message}"
           exit 1
         end
-      rescue TokenExpiredError
-        puts "Token expired. Run `ruby_native login` again."
-        exit 1
       end
 
       # --- Polling ---
@@ -155,6 +226,9 @@ module RubyNative
         print_status(last_status)
 
         started_at = Time.now
+        connection_failures = 0
+        not_found_count = 0
+        reported_error = nil
 
         loop do
           sleep POLL_INTERVAL
@@ -165,8 +239,43 @@ module RubyNative
             exit 1
           end
 
-          data = fetch_build_status(app_id, build_id)
-          next unless data
+          begin
+            state, payload = fetch_build_status(app_id, build_id)
+            connection_failures = 0
+          rescue ConnectionError => error
+            connection_failures += 1
+            next if connection_failures < MAX_POLL_FAILURES
+
+            puts ""
+            puts error.message
+            puts "Your build is most likely still running server-side. Check the"
+            puts "Ruby Native dashboard for the result: #{HOST}/dashboard"
+            exit 1
+          end
+
+          case state
+          when :not_found
+            not_found_count += 1
+            next if not_found_count < MAX_POLL_FAILURES
+
+            puts ""
+            puts "The server can no longer find this build (404). The app or build"
+            puts "may have been deleted or archived. Check the Ruby Native"
+            puts "dashboard: #{HOST}/dashboard"
+            exit 1
+          when :error
+            # The build keeps running server-side through a 500, so keep polling.
+            if payload != reported_error
+              reported_error = payload
+              puts ""
+              puts "#{URI(HOST).host} returned #{payload} while checking the build. Still trying..."
+            end
+            next
+          end
+
+          not_found_count = 0
+          data = payload
+          print_notice(data)
 
           if data["status"] != last_status
             last_status = data["status"]
@@ -196,6 +305,8 @@ module RubyNative
         puts "Check the Ruby Native dashboard for status."
       end
 
+      # Returns [:ok, data], [:not_found, nil], or [:error, description].
+      # Raises ConnectionError when the request never completed.
       def fetch_build_status(app_id, build_id)
         uri = URI("#{HOST}/api/v1/apps/#{app_id}/builds/#{build_id}")
         req = Net::HTTP::Get.new(uri)
@@ -205,11 +316,18 @@ module RubyNative
 
         case response
         when Net::HTTPSuccess
-          JSON.parse(response.body)
+          begin
+            [:ok, JSON.parse(response.body)]
+          rescue JSON::ParserError
+            [:error, "an unreadable response (HTTP #{response.code})"]
+          end
         when Net::HTTPUnauthorized
           puts ""
-          puts "Token expired. Run `ruby_native login` again."
-          exit 1
+          abort_token_expired!
+        when Net::HTTPNotFound
+          [:not_found, nil]
+        else
+          [:error, "HTTP #{response.code}"]
         end
       end
 
@@ -218,6 +336,17 @@ module RubyNative
         puts "  #{label}..." if label
       end
 
+      # Server-provided warnings (a lapsed payment, say) reach customers with
+      # no gem release. Deduped, since every status poll repeats the string.
+      def print_notice(data)
+        notice = data["notice"]
+        return unless notice.is_a?(String) && !notice.strip.empty?
+        return if notice == @printed_notice
+
+        @printed_notice = notice
+        puts "Notice: #{notice}"
+      end
+
       def status_labels
         if android?
           {
@@ -248,9 +377,14 @@ module RubyNative
         return "android" if argv.include?("--android")
 
         flag = argv.find { |a| a.start_with?("--platform=") }
-        return flag.split("=", 2).last if flag
+        return "ios" unless flag
 
-        "ios"
+        value = flag.split("=", 2).last
+        unless PLATFORMS.include?(value)
+          puts "Unknown platform #{value.inspect}. Use --platform=ios or --platform=android."
+          exit 1
+        end
+        value
       end
 
       def requested_platform
@@ -311,7 +445,7 @@ module RubyNative
         when Net::HTTPUnauthorized
           raise TokenExpiredError
         when Net::HTTPSuccess
-          JSON.parse(response.body)
+          parse_json(response)
         else
           puts "Failed to fetch apps: #{response.code}"
           nil
@@ -329,8 +463,7 @@ module RubyNative
 
         File.write(CONFIG_PATH, raw)
 
-        require "yaml"
-        @config = YAML.load_file(CONFIG_PATH, symbolize_names: true) || {}
+        @config = read_config
       end
 
       # --- HTTP ---
@@ -341,6 +474,17 @@ module RubyNative
         http.open_timeout = 10
         http.read_timeout = 30
         http.request(req)
+      rescue *NETWORK_ERRORS => error
+        raise ConnectionError, "Could not connect to #{uri.host} (#{error.class}: #{error.message})."
+      end
+
+      # Proxies and WAFs answer with HTML error pages; nil instead of a
+      # JSON::ParserError backtrace.
+      def parse_json(response)
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        puts "Unexpected response from #{URI(HOST).host}: HTTP #{response.code} with a body that is not JSON."
+        nil
       end
     end
   end

data/lib/ruby_native/cli/login.rb

@@ -3,12 +3,24 @@ require "securerandom"
 require "net/http"
 require "uri"
 require "json"
+require "openssl"
 require "ruby_native/cli/credentials"
 
 module RubyNative
   class CLI
     class Login
       HOST = ENV.fetch("RUBY_NATIVE_HOST", "https://rubynative.com")
+      POLL_INTERVAL = 2
+      MAX_ATTEMPTS = 60
+
+      NETWORK_ERRORS = [
+        SocketError,
+        Errno::ECONNREFUSED,
+        Errno::ECONNRESET,
+        Net::OpenTimeout,
+        Net::ReadTimeout,
+        OpenSSL::SSL::SSLError
+      ].freeze
 
       def initialize(argv = [])
       end
@@ -21,7 +33,8 @@ module RubyNative
         challenge = Digest::SHA256.hexdigest(verifier)
         url = "#{HOST}/cli/session/new?challenge=#{challenge}"
 
-        puts "Opening browser to authorize..."
+        puts "Opening your browser to authorize. If nothing opens, visit:"
+        puts "  #{url}"
         open_browser(url)
         puts "Waiting for authorization..."
 
@@ -31,7 +44,7 @@ module RubyNative
           Credentials.save(token)
           puts "Logged in to Ruby Native."
         else
-          puts "Authorization timed out. Please try again."
+          print_poll_failure
           exit 1
         end
       end
@@ -52,23 +65,64 @@ module RubyNative
       def poll_for_token(verifier)
         uri = URI("#{HOST}/cli/session/poll?verifier=#{verifier}")
         attempts = 0
-        max_attempts = 60
 
         loop do
           attempts += 1
-          return nil if attempts > max_attempts
+          return nil if attempts > MAX_ATTEMPTS
+
+          sleep POLL_INTERVAL
 
-          sleep 2
+          response = poll_once(uri)
+          next unless response
 
-          response = Net::HTTP.get_response(uri)
-          if response.is_a?(Net::HTTPSuccess)
-            data = JSON.parse(response.body)
-            return data["token"]
+          @network_error = nil
+
+          case response
+          when Net::HTTPSuccess
+            token = parse_token(response)
+            return token if token
+            @unexpected = "HTTP #{response.code} with a body that is not JSON"
+          when Net::HTTPNotFound
+            # Pending: the server answers 404 until the browser flow completes.
+            @unexpected = nil
+          else
+            @unexpected = "HTTP #{response.code}"
           end
         end
       rescue Interrupt
         nil
       end
+
+      def poll_once(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = 5
+        http.read_timeout = 5
+        http.request(Net::HTTP::Get.new(uri))
+      rescue *NETWORK_ERRORS => error
+        @network_error = "#{error.class}: #{error.message}"
+        nil
+      end
+
+      def parse_token(response)
+        JSON.parse(response.body)["token"]
+      rescue JSON::ParserError
+        nil
+      end
+
+      def print_poll_failure
+        if @unexpected
+          puts "Authorization did not complete. While waiting, #{HOST} kept responding"
+          puts "with #{@unexpected}."
+          puts "Check that #{HOST} loads in a browser, then run `ruby_native login` again."
+        elsif @network_error
+          puts "Could not reach #{HOST} (#{@network_error})."
+          puts "Check your internet connection and run `ruby_native login` again."
+        else
+          puts "Authorization timed out. Run `ruby_native login` again and approve"
+          puts "the request in your browser."
+        end
+      end
     end
   end
 end

data/lib/ruby_native/cli/preview.rb

@@ -13,6 +13,7 @@ module RubyNative
       PUBLIC_NAMESERVERS = ["1.1.1.1", "8.8.8.8"].freeze
       DEFAULT_PORT = 3000
       PORT_RANGE = (1..65_535)
+      OUTPUT_TAIL_LINES = 5
 
       def initialize(argv)
         @url = parse_option(argv, "--url")
@@ -32,6 +33,16 @@ module RubyNative
         uri = URI("#{@upstream}#{CONFIG_PATH}")
         response = fetch_config_response(uri)
 
+        if config_missing?(response)
+          puts "Rails server is reachable at #{upstream_description}, but it has no Ruby Native config."
+          puts ""
+          puts "config/ruby_native.yml is missing or empty. Create it with:"
+          puts "  bin/rails generate ruby_native:install"
+          puts ""
+          puts "Then restart your Rails server and run `ruby_native preview` again."
+          exit 1
+        end
+
         return if response.is_a?(Net::HTTPSuccess)
 
         puts "Rails server is reachable at #{upstream_description}, but #{CONFIG_PATH} returned #{response.code}."
@@ -70,6 +81,20 @@ module RubyNative
         exit 1
       end
 
+      # An older gem serves 200 "null" when config/ruby_native.yml is missing;
+      # current gems serve 404 with the version header still set. Both mean the
+      # same thing: mounted, but nothing to serve.
+      def config_missing?(response)
+        case response
+        when Net::HTTPSuccess
+          response.body.to_s.strip == "null"
+        when Net::HTTPNotFound
+          !response["X-Ruby-Native-Version"].nil?
+        else
+          false
+        end
+      end
+
       def fetch_config_response(uri, ip: nil)
         http = Net::HTTP.new(uri.host, uri.port)
         http.ipaddr = ip if ip
@@ -181,29 +206,65 @@ module RubyNative
         end
         puts ""
 
-        stdin, stdout_err, wait_thread = Open3.popen2e(
-          "cloudflared", "tunnel", "--url", @upstream
-        )
-        stdin.close
+        output, wait_thread = spawn_tunnel
 
         @tunnel_pid = wait_thread.pid
         trap_interrupt
 
         tunnel_url = nil
+        recent_output = []
 
-        stdout_err.each_line do |line|
-          if line =~ TUNNEL_URL_PATTERN
+        output.each_line do |line|
+          recent_output << line.strip
+          recent_output.shift if recent_output.length > OUTPUT_TAIL_LINES
+          if tunnel_url.nil? && line =~ TUNNEL_URL_PATTERN
             tunnel_url = line[TUNNEL_URL_PATTERN]
             wait_for_tunnel(tunnel_url)
             display_qr(tunnel_url)
           end
         end
+
+        # Ctrl+C exits inside the trap, so reaching here means cloudflared
+        # itself stopped. Silence looked like either a hang or a clean exit.
+        report_tunnel_exit(tunnel_url, wait_thread.value, recent_output)
       rescue Interrupt
         # Handled by trap
       ensure
         kill_tunnel
       end
 
+      def spawn_tunnel
+        stdin, stdout_err, wait_thread = Open3.popen2e(
+          "cloudflared", "tunnel", "--url", @upstream
+        )
+        stdin.close
+        [stdout_err, wait_thread]
+      end
+
+      def report_tunnel_exit(tunnel_url, status, recent_output)
+        puts ""
+        if tunnel_url
+          puts "The tunnel stopped: cloudflared exited (#{describe_exit(status)})."
+        else
+          puts "cloudflared exited (#{describe_exit(status)}) before the tunnel came up."
+        end
+
+        unless recent_output.empty?
+          puts ""
+          puts "Last output from cloudflared:"
+          recent_output.each { |line| puts "  #{line}" }
+        end
+
+        puts ""
+        puts "This usually means cloudflared could not reach Cloudflare. Check your"
+        puts "internet connection and run `ruby_native preview` again."
+        exit 1
+      end
+
+      def describe_exit(status)
+        status.exitstatus ? "status #{status.exitstatus}" : status.to_s
+      end
+
       def display_qr(url)
         require "rqrcode"
 

data/lib/ruby_native/cli.rb

@@ -22,15 +22,33 @@ module RubyNative
         warn "Screenshots are now captured by rubynative.com against your deployed site."
         warn "See https://rubynative.com/docs/screenshots for the new flow."
         exit 1
+      when nil
+        print_usage
       else
-        puts "Usage: ruby_native <command>"
+        puts "Unknown command: #{command}"
         puts ""
-        puts "Commands:"
-        puts "  deploy        Trigger an iOS build (use --android for Android)"
-        puts "  login         Authenticate with Ruby Native"
-        puts "  logout        Remove stored credentials"
-        puts "  preview       Start a tunnel and display a QR code"
+        print_usage
+        exit 1
       end
+    rescue => error
+      puts "Something went wrong: #{error.class}: #{error.message}"
+      puts "If this keeps happening, report it: https://github.com/ruby-native/gem/issues"
+      exit 1
+    end
+
+    def self.print_usage
+      puts "Usage: ruby_native <command> [options]"
+      puts ""
+      puts "Commands:"
+      puts "  deploy        Trigger a build and wait for it to finish"
+      puts "    --android          Build for Android instead of iOS"
+      puts "    --platform=NAME    Build for ios or android"
+      puts "    --if-needed        Skip when this gem version is already built"
+      puts "  login         Authenticate with Ruby Native"
+      puts "  logout        Remove stored credentials"
+      puts "  preview       Start a tunnel and display a QR code"
+      puts "    --port PORT        Rails server port (default: PORT or 3000)"
+      puts "    --url URL          Tunnel to this URL instead of localhost"
     end
   end
 end

data/lib/ruby_native/helper.rb

@@ -189,15 +189,43 @@ module RubyNative
       tag.div(data: data, hidden: true) { builder.to_html }
     end
 
-    def native_fab_tag(icon: nil, icons: nil, href: nil, click: nil)
+    # `color:` tints the button: tinted Liquid Glass on iOS, a colored
+    # Material FAB on Android. The icon color is derived automatically to
+    # stay readable against it. Pass `:tint` instead of a hex to inherit
+    # `appearance.tint_color`, keeping the button in sync with the app accent.
+    def native_fab_tag(icon: nil, icons: nil, href: nil, click: nil, color: nil)
       resolved = RubyNative::Helper.resolve_icon(icon: icon, icons: icons, platform: try(:native_platform))
       raise ArgumentError, "native_fab_tag requires an icon" if resolved.nil?
       data = { native_fab: true, native_icon: resolved }
       data[:native_href] = href if href
       data[:native_click] = click if click
+      data[:native_color] = color if color
       tag.div(data: data, hidden: true)
     end
 
+    # Attaches a native menu to an element already on the page. `anchor:` is a
+    # CSS selector for that element; tapping it in the app opens a native menu
+    # anchored to it with the block's items, and picking one navigates or
+    # clicks a web element exactly like a nav bar menu item does.
+    #
+    #   <span id="status-pill">Want to read</span>
+    #
+    #   <%= native_menu_tag anchor: "#status-pill" do |menu| %>
+    #     <% menu.item "Currently reading", click: "#status-reading" %>
+    #     <% menu.item "Finished",          click: "#status-finished" %>
+    #   <% end %>
+    #
+    # The anchor element stays an ordinary element on the web, so give it its
+    # own web behavior (or a `native-hidden` fallback) if it needs one there.
+    def native_menu_tag(anchor:, &block)
+      anchor = anchor.to_s
+      raise ArgumentError, "native_menu_tag requires an anchor CSS selector" if anchor.strip.empty?
+
+      builder = NavbarMenuBuilder.new(self)
+      capture(builder, &block) if block
+      tag.div(data: { native_menu: "", native_anchor: anchor }, hidden: true) { builder.to_html }
+    end
+
     def native_overscroll_tag(top:, bottom: nil)
       tag.div(data: { native_overscroll_top: top, native_overscroll_bottom: bottom || top }, hidden: true)
     end
@@ -392,13 +420,14 @@ module RubyNative
         @items = []
       end
 
-      def item(title, href: nil, click: nil, icon: nil, icons: nil, selected: false, action: nil)
+      def item(title, href: nil, click: nil, icon: nil, icons: nil, selected: false, action: nil, destructive: false)
         resolved = RubyNative::Helper.resolve_icon(icon: icon, icons: icons, platform: @context.try(:native_platform))
         data = { native_menu_item: "", native_title: title }
         data[:native_href] = href if href
         data[:native_click] = click if click
         data[:native_icon] = resolved if resolved
         data[:native_selected] = "" if selected
+        data[:native_destructive] = "" if destructive
         data[:native_action] = RubyNative::Helper.validate_action(action) if action
         add(@context.tag.div(data: data))
       end

data/lib/ruby_native/native_detection.rb

@@ -2,16 +2,17 @@ module RubyNative
   module NativeDetection
     extend ActiveSupport::Concern
 
-    # Matches "Ruby Native iOS/5.2/35 iOS/26.5.2 RubyNative/0.12.5". The build and
-    # OS groups are optional: apps built before the UA carried them send only
-    # "Ruby Native iOS/5.2", and the optional group keeps the OS capture from
-    # swallowing that app version.
-    SIGNATURE = %r{Ruby Native (?:iOS|Android)/([\d.]+)(?:/([\d.]+) (?:iOS|Android)/([\d.]+))?}
+    # Matches "Ruby Native iOS/5.2/35 iOS/26.5.2/23F79 RubyNative/0.12.5". The
+    # build, OS, and OS build groups are optional: apps built before the UA
+    # carried them send only "Ruby Native iOS/5.2" (or later "... iOS/26.5.2"
+    # without the OS build), and the optional groups keep the OS capture from
+    # swallowing the app version.
+    SIGNATURE = %r{Ruby Native (?:iOS|Android)/([\d.]+)(?:/([\d.]+) (?:iOS|Android)/([\d.]+)(?:/([\w.]+))?)?}
 
     included do
       if respond_to?(:helper_method)
         helper_method :native_app?, :native_version, :native_platform,
-          :native_app_version, :native_app_build, :native_os_version
+          :native_app_version, :native_app_build, :native_os_version, :native_os_build
       end
     end
 
@@ -49,5 +50,11 @@ module RubyNative
     def native_os_version
       request.user_agent.to_s[SIGNATURE, 3]
     end
+
+    # The device's OS build, like "23F79" (iOS) or "UQ1A.240205.004" (Android).
+    # Nil for web browsers and apps built before the User-Agent carried it.
+    def native_os_build
+      request.user_agent.to_s[SIGNATURE, 4]
+    end
   end
 end

data/lib/ruby_native/version.rb

@@ -1,3 +1,3 @@
 module RubyNative
-  VERSION = "0.13.0"
+  VERSION = "0.14.2"
 end

data/lib/ruby_native.rb

@@ -44,7 +44,16 @@ module RubyNative
     path = Rails.root.join("config", "ruby_native.yml")
     return unless path.exist?
 
-    self.config = YAML.load(render_config(path)).deep_symbolize_keys
+    parsed = YAML.load(render_config(path), filename: path.to_s, aliases: true)
+
+    # An empty file, comments only, or ERB rendering to nothing parses to nil;
+    # treat it like a missing file instead of crashing Rails boot.
+    unless parsed.is_a?(Hash)
+      Rails.logger.warn("[RubyNative] #{path} is empty or not a YAML mapping; ignoring it.")
+      return
+    end
+
+    self.config = parsed.deep_symbolize_keys
     self.config[:app] ||= {}
     self.config[:app][:entry_path] ||= self.config.dig(:tabs, 0, :path) || "/"
     self.config[:auth] ||= {}
@@ -56,7 +65,7 @@ module RubyNative
 
   # config/ruby_native.yml is rendered as ERB before it is parsed, so a
   # developer can interpolate Rails helpers into it. The motivating case is the
-  # navbar logo: `logo: "<%= image_url("logo.png") %>"` resolves to a
+  # navbar logo: `logo: '<%= image_url("logo.png") %>'` resolves to a
   # fingerprinted asset URL the native app downloads and caches, and because the
   # digest changes whenever the asset changes, the cache busts itself. A full
   # URL (a CDN, say) works just as well; the app only ever sees a URL to fetch.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_native
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.2
 platform: ruby
 authors:
 - Joe Masilotti
@@ -111,10 +111,14 @@ files:
 - lib/ruby_native/screenshots/sign_in_helper.rb
 - lib/ruby_native/tunnel_cookie_middleware.rb
 - lib/ruby_native/version.rb
-homepage: https://github.com/ruby-native/gem
+homepage: https://rubynative.com
 licenses:
 - MIT
-metadata: {}
+metadata:
+  documentation_uri: https://rubynative.com/docs
+  source_code_uri: https://github.com/ruby-native/gem
+  changelog_uri: https://github.com/ruby-native/gem/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib