ruby_native 0.12.4 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4883fe85db15b632a0b17e249b3a9f64bf56ce41de2662042d389be80b8b1290
-  data.tar.gz: db953ec4cf72600febd4cdb3e7363ec453e0b92c9997c4d2d92a7b10e452e20c
+  metadata.gz: 9ba0a91ec78db490b4baf13e77f7b412d4f2f344cddbb2ad5ef8f09b28254459
+  data.tar.gz: 25ca1ff3cecb136ba1f98146fd6f3a21447462c4e92167b55d4bd6bd940ded44
 SHA512:
-  metadata.gz: d62fa5f93299513db36f9651c3e58323f00c5d9318b334b05ddb9ef3f24ad0ff8b5b384542238149b41200b3011205c1ff412edb11b4ae3d2e32b86d983e69a5
-  data.tar.gz: bc5e6e13c115242628065ac3d0795b1b183e1144f0cbbf0d2075dc03499c05839e6462ffe314d55c7620d535db116bcb3a7f99de77a8e7259f5bb18adf5234be
+  metadata.gz: cb3a1b0cf45efe647d2cc5794bfafb6c1aec60549ace2a0e8109118d573b4ec72ebf2d5fdfd4ea090c12b32049feed77de6b8992a529b1da4d4f80024e260fe8
+  data.tar.gz: 99c67fa20a4ee36f5a311d5fe43e3ba0b4ae6cc5df867ff3decdc41681da30a79c319290821b06903b60d12467a897bcf5909db00fdbf651c41e463254a42ea0

data/README.md

@@ -72,12 +72,18 @@ This starts a Cloudflare tunnel and shows a QR code for the Ruby Native app to s
 brew install cloudflare/cloudflare/cloudflared
 ```
 
+The tunnel points at port 3000, or at `PORT` when it is set, the same way `rails server` picks its port. Pass `--port 4000` to override, or `--url` for an upstream that isn't on localhost.
+
 See [rubynative.com/docs/cli](https://rubynative.com/docs/cli) for `deploy`, `login`, and auto-deploying from CI.
 
 ## React and Vue
 
 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/assets/stylesheets/ruby_native.css

@@ -2,22 +2,50 @@
   display: none !important;
 }
 
-/* Android's WebView doesn't populate env(safe-area-inset-*) from system bars
-   (only display cutouts), so the native shell pushes the real top/bottom
-   system bar heights into these CSS variables. iOS leaves the variables
-   undefined and falls back to env(), which works there. */
+/* Public API for app CSS. Android's WebView doesn't populate
+   env(safe-area-inset-*) from system bars (only display cutouts), so the
+   native shell pushes the real heights into the internal -inset- variables;
+   iOS leaves them undefined and falls back to env(). */
+:root {
+  --ruby-native-safe-area-top: var(--ruby-native-safe-area-inset-top, env(safe-area-inset-top, 0px));
+  --ruby-native-safe-area-bottom: var(--ruby-native-safe-area-inset-bottom, env(safe-area-inset-bottom, 0px));
+}
+
 .native-inset-top::before,
 .native-inset::before {
   content: "";
   display: block;
-  height: var(--ruby-native-safe-area-inset-top, env(safe-area-inset-top));
+  height: var(--ruby-native-safe-area-top);
 }
 
 .native-inset-bottom::after,
 .native-inset::after {
   content: "";
   display: block;
-  height: var(--ruby-native-safe-area-inset-bottom, env(safe-area-inset-bottom));
+  height: var(--ruby-native-safe-area-bottom);
+}
+
+/* In-app defaults so pages feel native without any setup: no gray tap flash,
+   no selecting button labels on long-press, no double-tap zoom on controls.
+   Pair with :active styles for pressed feedback; the bridge makes them apply
+   instantly on touch. */
+[data-native-app] * {
+  -webkit-tap-highlight-color: transparent;
+}
+
+[data-native-app] button,
+[data-native-app] [role="button"] {
+  -webkit-user-select: none;
+  user-select: none;
+  -webkit-touch-callout: none;
+}
+
+[data-native-app] a,
+[data-native-app] button,
+[data-native-app] input,
+[data-native-app] label,
+[data-native-app] [role="button"] {
+  touch-action: manipulation;
 }
 
 .native-back-button {

data/app/controllers/ruby_native/aasa_controller.rb

@@ -12,7 +12,7 @@ module RubyNative
       render json: {
         applinks: {
           details: [
-            { appIDs: [ app_id ], components: oauth_exclusions + [ { "/": "*" } ] }
+            { appIDs: [ app_id ], components: oauth_exclusions + linked_components }
           ]
         },
         webcredentials: {
@@ -37,5 +37,15 @@ module RubyNative
         { "/": "#{path}*", exclude: true }
       end
     end
+
+    # `linked_paths` scopes Universal Links to those prefixes; without it every
+    # URL on the domain is linked. Password sharing (webcredentials) stays
+    # domain-wide either way; there is no path concept for it.
+    def linked_components
+      paths = Array(RubyNative.config&.dig(:linked_paths))
+      return [ { "/": "*" } ] if paths.empty?
+
+      paths.map { |path| { "/": "#{path}*" } }
+    end
   end
 end

data/app/controllers/ruby_native/assetlinks_controller.rb

@@ -0,0 +1,30 @@
+module RubyNative
+  class AssetlinksController < ::ActionController::Base
+    def show
+      RubyNative.load_config if Rails.env.development?
+
+      package = RubyNative.config&.dig(:android, :package)
+      # The Digital Asset Links spec wants uppercase colon-separated hex, so a
+      # lowercase paste from keytool still verifies.
+      fingerprints = Array(RubyNative.config&.dig(:android, :cert_fingerprint))
+        .map { |fingerprint| fingerprint.to_s.strip.upcase }
+        .reject(&:empty?)
+      return head :not_found unless package.present? && fingerprints.present?
+
+      response.set_header("Cache-Control", "no-cache")
+      render json: [
+        {
+          relation: [
+            "delegate_permission/common.handle_all_urls",
+            "delegate_permission/common.get_login_creds"
+          ],
+          target: {
+            namespace: "android_app",
+            package_name: package,
+            sha256_cert_fingerprints: fingerprints
+          }
+        }
+      ]
+    end
+  end
+end

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/install_generator.rb

@@ -10,14 +10,24 @@ module RubyNative
       end
 
       def add_allowed_host
-        host_line = '  config.hosts << ".trycloudflare.com"'
+        host_line = %(  config.hosts << ".trycloudflare.com" if config.hosts.is_a?(Array)\n)
         dev_config = "config/environments/development.rb"
 
         return unless File.exist?(File.join(destination_root, dev_config))
-        return if File.read(File.join(destination_root, dev_config)).include?("trycloudflare")
+        contents = File.read(File.join(destination_root, dev_config))
+        return if contents.include?("trycloudflare")
 
-        environment(host_line, env: "development")
-        say "  Added .trycloudflare.com to allowed hosts in development.rb", :green
+        # Match any configure block, not just Rails.application.configure; some
+        # apps use MyApp::Application.configure and Thor's environment helper
+        # silently skips those.
+        configure_block = /^[\w:.]+\.configure do\s*\n/
+        if contents.match?(configure_block)
+          inject_into_file dev_config, host_line, after: configure_block, verbose: false
+          say "  Added .trycloudflare.com to allowed hosts in development.rb", :green
+        else
+          say "  Couldn't find a configure block in development.rb. Add this line inside it:", :yellow
+          say "  #{host_line.strip}", :yellow
+        end
       end
 
       def add_gitignore

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.
@@ -109,6 +123,16 @@ tabs:
 # ios:
 #   bundle_id: com.example.myapp
 #   team_id: ABCD123456
+# android:
+#   package: com.example.myapp
+#   # Play Console -> Setup -> App integrity -> App signing key certificate.
+#   cert_fingerprint: "AA:BB:CC:..."
+
+# Link only these path prefixes instead of the whole domain. Links outside
+# them keep opening in the browser. Applies to iOS on your next deploy and
+# to Android on your next build.
+# linked_paths:
+#   - /pair/
 
 # Enable OAuth. Each path triggers a native ASWebAuthenticationSession
 # on iOS instead of an in-app web view. List only the authorize path for each

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

@@ -11,10 +11,13 @@ module RubyNative
       TUNNEL_READY_TIMEOUT = 60
       TUNNEL_POLL_INTERVAL = 1
       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")
-        @port = parse_port(argv)
+        @port, @port_from_env = resolve_port(argv)
         @upstream = @url || "http://localhost:#{@port}"
       end
 
@@ -30,9 +33,19 @@ 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}, but #{CONFIG_PATH} returned #{response.code}."
+        puts "Rails server is reachable at #{upstream_description}, but #{CONFIG_PATH} returned #{response.code}."
         puts ""
 
         # 404 is what an unmounted engine returns; any other code means the app
@@ -57,7 +70,7 @@ module RubyNative
           puts ""
           puts "Make sure your Rails server is reachable at that URL."
         else
-          puts "Nothing is running on port #{@port}."
+          puts "Nothing is running on port #{port_description}."
           puts ""
           puts "Start your Rails server in another terminal:"
           puts "  bin/rails server -p #{@port}"
@@ -68,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
@@ -121,9 +148,36 @@ module RubyNative
         Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end
 
-      def parse_port(argv)
-        value = parse_option(argv, "--port")
-        value ? value.to_i : 3000
+      # --port, then PORT, then 3000 is the precedence rails server itself uses,
+      # so a preview lands on the port the app is already serving. Anything
+      # unusable in PORT falls back rather than failing: the variable gets set
+      # for plenty of reasons that have nothing to do with a local Rails server.
+      def resolve_port(argv)
+        flag = parse_option(argv, "--port")
+        return [flag.to_i, false] if flag
+
+        env = env_port
+        env ? [env, true] : [DEFAULT_PORT, false]
+      end
+
+      def env_port
+        value = ENV["PORT"].to_s.strip
+        return unless value.match?(/\A\d+\z/)
+
+        port = value.to_i
+        port if PORT_RANGE.cover?(port)
+      end
+
+      # Naming the source keeps a port nobody typed from reading as a bug.
+      def port_description
+        @port_from_env ? "#{@port} (from PORT)" : @port.to_s
+      end
+
+      # @port_from_env can be true alongside --url, which ignores the port.
+      def upstream_description
+        return @upstream if @url || !@port_from_env
+
+        "#{@upstream} (port from PORT)"
       end
 
       def parse_option(argv, flag)
@@ -148,33 +202,69 @@ module RubyNative
         if @url
           puts "Make sure your Rails server is reachable at #{@url}."
         else
-          puts "Make sure your Rails server is running on port #{@port} in another terminal."
+          puts "Make sure your Rails server is running on port #{port_description} in another terminal."
         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"
 
@@ -201,7 +291,7 @@ module RubyNative
         if @url
           puts "Keep this running and your Rails server reachable at #{@url}."
         else
-          puts "Keep this running and your Rails server on port #{@port} in another terminal."
+          puts "Keep this running and your Rails server on port #{port_description} in another terminal."
         end
         puts "Press Ctrl+C to stop."
       end

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/engine.rb

@@ -51,6 +51,7 @@ module RubyNative
     initializer "ruby_native.routes" do |app|
       app.routes.prepend do
         get "/.well-known/apple-app-site-association", to: "ruby_native/aasa#show"
+        get "/.well-known/assetlinks.json", to: "ruby_native/assetlinks#show"
         mount RubyNative::Engine, at: "/native"
       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,8 +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.]+))?}
+
     included do
-      helper_method :native_app?, :native_version, :native_platform if respond_to?(:helper_method)
+      if respond_to?(:helper_method)
+        helper_method :native_app?, :native_version, :native_platform,
+          :native_app_version, :native_app_build, :native_os_version
+      end
     end
 
     def native_app?
@@ -23,5 +32,22 @@ module RubyNative
       return "android" if ua.include?("Ruby Native Android")
       nil
     end
+
+    # The app's marketing version, like "5.2". Nil for web browsers.
+    def native_app_version
+      request.user_agent.to_s[SIGNATURE, 1]
+    end
+
+    # The app's build number (CFBundleVersion / versionCode), like "35". Nil for
+    # web browsers and apps built before the User-Agent carried it.
+    def native_app_build
+      request.user_agent.to_s[SIGNATURE, 2]
+    end
+
+    # The device's OS version, like "26.5.2". Nil for web browsers and apps built
+    # before the User-Agent carried it.
+    def native_os_version
+      request.user_agent.to_s[SIGNATURE, 3]
+    end
   end
 end

data/lib/ruby_native/version.rb

@@ -1,3 +1,3 @@
 module RubyNative
-  VERSION = "0.12.4"
+  VERSION = "0.14.0"
 end

data/lib/ruby_native.rb

@@ -44,18 +44,28 @@ 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] ||= {}
     normalize_oauth_paths
+    normalize_linked_paths
     backfill_tab_icons
     backfill_error_icons
   end
 
   # 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.
@@ -183,4 +193,17 @@ module RubyNative
     )
     self.config[:auth][:oauth_paths] = paths - callbacks
   end
+
+  # Entries are path prefixes: "/pair/" links every URL under it. A leading
+  # slash is added when missing, and a trailing "*" (an easy slip, since the
+  # AASA file uses one) is stripped so both platforms receive a plain prefix.
+  # Left absent when unconfigured so config.json doesn't grow an empty key.
+  def self.normalize_linked_paths
+    return unless self.config.key?(:linked_paths)
+
+    self.config[:linked_paths] = Array(self.config[:linked_paths])
+      .map { |path| path.to_s.strip.sub(/\*+\z/, "") }
+      .reject(&:empty?)
+      .map { |path| path.start_with?("/") ? path : "/#{path}" }
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_native
 version: !ruby/object:Gem::Version
-  version: 0.12.4
+  version: 0.14.0
 platform: ruby
 authors:
 - Joe Masilotti
@@ -70,6 +70,7 @@ files:
 - README.md
 - app/assets/stylesheets/ruby_native.css
 - app/controllers/ruby_native/aasa_controller.rb
+- app/controllers/ruby_native/assetlinks_controller.rb
 - app/controllers/ruby_native/auth/sessions_controller.rb
 - app/controllers/ruby_native/auth/start_controller.rb
 - app/controllers/ruby_native/config_controller.rb
@@ -110,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