ruby_everywhere 0.6.0 → 0.8.0

data/lib/everywhere/config/deep_linking.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Everywhere
+  class Config
+    module DeepLinking
+      # Deep linking / universal links. Declares the app's association with its
+      # web domains so the OS can hand matching URLs to the app instead of the
+      # browser. The gem serves the two well-known association files this needs —
+      # /.well-known/apple-app-site-association and /.well-known/assetlinks.json —
+      # generated from this config (Everywhere::Engine in Rails; MobileConfigEndpoint
+      # for Sinatra/Hanami). The iOS builder stamps the matching Associated Domains
+      # entitlement, and the shell routes an incoming link to its path.
+      #
+      #   deep_linking:
+      #     team_id: ABCDE12345          # derives the iOS app id from bundle_id
+      #     # or set app ids explicitly:
+      #     # apple_app_id: ABCDE12345.com.example.app
+      #     # apple_app_ids: ["ABCDE12345.com.example.app"]
+      #     paths: ["/*"]                # which paths open the app (default: all)
+      #     domains: ["www.example.com"] # extra applinks: domains (remote host is implicit)
+      #     android:
+      #       package: com.example.app
+      #       sha256_cert_fingerprints: ["AB:CD:EF:..."]
+      def deep_linking = @data.fetch("deep_linking", nil) || {}
+
+      # The iOS/tvOS/... app identifiers (TeamID.bundleID) the association file
+      # advertises. Explicit ids win; otherwise team_id + the app's iOS bundle id.
+      def deep_linking_apple_app_ids
+        explicit = Array(deep_linking["apple_app_ids"]) + [deep_linking["apple_app_id"]].compact
+        return explicit.map(&:to_s).uniq unless explicit.empty?
+
+        team = deep_linking["team_id"].to_s.strip
+        team.empty? ? [] : ["#{team}.#{bundle_id(target: "ios")}"]
+      end
+
+      # URL path patterns that open the app. Modern (iOS 14+) component form;
+      # defaults to every path.
+      def deep_linking_paths
+        paths = Array(deep_linking["paths"]).map(&:to_s).reject(&:empty?)
+        paths.empty? ? ["*"] : paths
+      end
+
+      def deep_linking_android = deep_linking["android"].is_a?(Hash) ? deep_linking["android"] : {}
+      def deep_linking_android_package = deep_linking_android["package"]&.to_s
+
+      def deep_linking_android_fingerprints
+        Array(deep_linking_android["sha256_cert_fingerprints"]).map { |f| f.to_s.strip }.reject(&:empty?)
+      end
+
+      def deep_linking_android? = !deep_linking_android_package.to_s.empty? && !deep_linking_android_fingerprints.empty?
+
+      def deep_linking_apple? = !deep_linking_apple_app_ids.empty?
+
+      def deep_linking? = deep_linking_apple? || deep_linking_android?
+
+      # Domains for the iOS Associated Domains entitlement (applinks:<host>) and
+      # the shell's universal-link host allowlist: the remote host plus any extra
+      # `domains:`. Bare hostnames (no scheme, no path).
+      def deep_linking_domains
+        hosts = []
+        if remote_url
+          require "uri"
+          hosts << URI(remote_url).host
+        end
+        hosts += Array(deep_linking["domains"]).map { |d| d.to_s.sub(%r{\Ahttps?://}, "").sub(%r{/.*\z}, "") }
+        hosts.compact.reject(&:empty?).uniq
+      rescue URI::InvalidURIError
+        Array(deep_linking["domains"]).map(&:to_s).reject(&:empty?).uniq
+      end
+
+      # The apple-app-site-association document (a Hash), or nil when no Apple app
+      # ids are configured. `applinks` for universal links; `webcredentials` so
+      # associated-domains password autofill / Face ID credentials work too.
+      def apple_app_site_association
+        ids = deep_linking_apple_app_ids
+        return nil if ids.empty?
+
+        { "applinks" => {
+            "details" => [{ "appIDs" => ids, "components" => deep_linking_paths.map { |p| { "/" => p } } }]
+          },
+          "webcredentials" => { "apps" => ids } }
+      end
+
+      def apple_app_site_association_json
+        require "json"
+        doc = apple_app_site_association or return nil
+        JSON.generate(doc)
+      end
+
+      # The Digital Asset Links document (an Array), or nil without an Android app.
+      def asset_links
+        return nil unless deep_linking_android?
+
+        [{ "relation" => ["delegate_permission/common.handle_all_urls"],
+           "target" => { "namespace" => "android_app",
+                         "package_name" => deep_linking_android_package,
+                         "sha256_cert_fingerprints" => deep_linking_android_fingerprints } }]
+      end
+
+      def asset_links_json
+        require "json"
+        doc = asset_links or return nil
+        JSON.generate(doc)
+      end
+    end
+  end
+end

data/lib/everywhere/config/desktop_ui.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Everywhere
+  class Config
+    module DesktopUi
+      # Custom native menu items (macOS app menu). Each entry: label + path
+      # (+ optional accelerator), or "separator". Clicks arrive in the page as
+      # "everywhere:menu" events and navigate via Turbo.
+      def menu
+        entries = @data["menu"]
+        return [] unless entries.is_a?(Array)
+
+        entries.filter_map do |item|
+          if item == "separator" || (item.is_a?(Hash) && item["separator"])
+            { "separator" => true }
+          elsif item.is_a?(Hash) && item["label"] && item["path"]
+            { "label" => item["label"], "path" => item["path"],
+              "accelerator" => item["accelerator"] }.compact
+          end
+        end
+      end
+
+      # System tray: same entry shape as `menu:` plus `action: quit | show`.
+      #
+      #   tray:
+      #     - label: "Open My App"
+      #       action: show
+      #     - label: "New Note"
+      #       path: /notes/new
+      #     - separator
+      #     - label: Quit
+      #       action: quit
+      def tray
+        entries = @data["tray"]
+        return [] unless entries.is_a?(Array)
+
+        entries.filter_map do |item|
+          if item == "separator" || (item.is_a?(Hash) && item["separator"])
+            { "separator" => true }
+          elsif item.is_a?(Hash) && item["label"] && (item["path"] || item["action"])
+            { "label" => item["label"], "path" => item["path"],
+              "action" => item["action"] }.compact
+          end
+        end
+      end
+
+      # Desktop window chrome. Desktop-only: on mobile the OS owns the frame, so
+      # mobile builds ignore this section entirely.
+      #
+      #   window:
+      #     title_bar: overlay   # decorated (default) | overlay | frameless
+      #     title: false         # draw the title text (default true)
+      #     size: [1100, 750]    # initial inner size
+      #     min_size: [600, 400]
+      #     resizable: true
+      #     drag_height: 28      # top strip that drags the window; 0 turns it off
+      #
+      # Every reader returns nil when the key is absent so `to_shell_hash` drops it
+      # and the shell keeps its own default — there is exactly one place each
+      # default lives, and it's the Rust side.
+      #
+      # `overlay` is the macOS "traffic lights floating over your content" look
+      # (TitleBarStyle::Overlay + hidden title). Windows and Linux have no such
+      # style, so the shell falls back to frameless there and the page draws its
+      # own controls via Everywhere.window.
+      WINDOW_TITLE_BARS = %w[decorated overlay frameless].freeze
+
+      def window
+        section = @data["window"]
+        section.is_a?(Hash) ? section : {}
+      end
+
+      def window_title_bar
+        value = window["title_bar"].to_s
+        value if WINDOW_TITLE_BARS.include?(value)
+      end
+
+      # Tri-state, like native_ios_lazy_load_tabs: an absent key leaves the shell
+      # on its default rather than forcing one.
+      def window_title = boolean_or_nil(window["title"])
+      def window_resizable = boolean_or_nil(window["resizable"])
+
+      def window_size = window_dimensions("size")
+      def window_min_size = window_dimensions("min_size")
+
+      # How much of the top of the page drags the window, in CSS pixels. Only
+      # meaningful for overlay/frameless, where there's no system title bar left
+      # to grab. nil leaves the shell's 28px default (the height of the macOS
+      # traffic-light band); 0 turns dragging off for an app that wants to place
+      # its own drag regions.
+      def window_drag_height
+        value = window["drag_height"]
+        value.to_f if value.is_a?(Numeric) && !value.negative?
+      end
+
+      # The window subset the shell needs. nil (absent from everywhere.json) when
+      # the app declares nothing, so the shell's own defaults stand untouched.
+      def window_shell_hash
+        hash = {
+          "title_bar" => window_title_bar,
+          "title" => window_title,
+          "resizable" => window_resizable,
+          "size" => window_size,
+          "min_size" => window_min_size,
+          "drag_height" => window_drag_height
+        }.compact
+        hash unless hash.empty?
+      end
+
+      def window_errors
+        raw = @data["window"]
+        return [] if raw.nil?
+        return ["window: must be a mapping"] unless raw.is_a?(Hash)
+
+        errors = []
+        bar = raw["title_bar"]
+        if bar && !WINDOW_TITLE_BARS.include?(bar.to_s)
+          errors << "window.title_bar #{bar.to_s.inspect} must be one of " \
+                    "#{WINDOW_TITLE_BARS.join(" / ")}"
+        end
+
+        errors += %w[size min_size].filter_map do |key|
+          next if raw[key].nil? || window_dimensions(key)
+
+          "window.#{key} must be two positive numbers, like [1100, 750]"
+        end
+
+        drag = raw["drag_height"]
+        unless drag.nil? || (drag.is_a?(Numeric) && !drag.negative?)
+          errors << "window.drag_height must be a number of pixels (0 turns dragging off)"
+        end
+
+        errors + %w[title resizable].filter_map do |key|
+          next if raw[key].nil? || boolean_or_nil(raw[key]) == raw[key]
+
+          "window.#{key} must be true or false"
+        end
+      end
+
+      private
+
+      # A [width, height] pair. Rejects the near-misses (one number, three, a
+      # negative) rather than silently building a 0-pixel window.
+      def window_dimensions(key)
+        value = window[key]
+        return unless value.is_a?(Array) && value.length == 2
+        return unless value.all? { |n| n.is_a?(Numeric) && n.positive? }
+
+        value.map(&:to_f)
+      end
+    end
+  end
+end

data/lib/everywhere/config/mobile.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module Everywhere
+  class Config
+    module Mobile
+      # Mobile tab bar, platform-neutral. Icons are per-platform (ios = SF
+      # Symbol, android = Material icon later), with a shared `icon:` fallback:
+      #
+      #   tabs:
+      #     - name: Builds
+      #       path: /builds
+      #       icons:
+      #         ios: hammer
+      #         android: build
+      #
+      # Tabs ship two ways from the same source: baked into the app's bundled
+      # path-configuration.json at build time (offline/first-launch), and served
+      # live from /everywhere/<platform>_v1.json (MobileConfigEndpoint) so tab
+      # changes deploy with the web app — no app-store release.
+      def tabs
+        entries = @data["tabs"]
+        return [] unless entries.is_a?(Array)
+
+        entries.filter_map do |tab|
+          next unless tab.is_a?(Hash) && tab["name"] && tab["path"]
+
+          path = tab["path"].start_with?("/") ? tab["path"] : "/#{tab["path"]}"
+          { "name" => tab["name"], "path" => path,
+            "icon" => tab["icon"], "icons" => (tab["icons"] if tab["icons"].is_a?(Hash)) }.compact
+        end
+      end
+
+      # Tabs with the icon resolved for one platform: icons.<os>, then the
+      # shared icon, then a safe default.
+      def tabs_for(os)
+        tabs.map do |tab|
+          { "title" => tab["name"], "path" => tab["path"],
+            "icon" => tab.dig("icons", os.to_s) || tab["icon"] || DEFAULT_TAB_ICONS[os.to_s] }.compact
+        end
+      end
+
+      DEFAULT_TAB_ICONS = { "ios" => "circle", "android" => "circle" }.freeze
+
+      # The Hotwire Native path-configuration rules every RubyEverywhere mobile
+      # shell starts from. Single source of truth: the builder bakes this into
+      # the app bundle and MobileConfigEndpoint serves it live.
+      MOBILE_PATH_RULES = [
+        { "patterns" => [".*"],
+          "properties" => { "context" => "default", "pull_to_refresh_enabled" => true } },
+        { "patterns" => ["/new$", "/edit$"],
+          "properties" => { "context" => "modal", "pull_to_refresh_enabled" => false } }
+      ].freeze
+
+      # Native permissions the app declares (top-level `permissions:`). Only
+      # declared permissions can be requested at runtime — the shell answers
+      # `undeclared` for everything else, so an app that doesn't need a
+      # permission can never prompt for it. For camera and location the value is
+      # the user-facing usage string iOS shows in the permission prompt (the
+      # "why"); it's mandatory there because requesting without one crashes the
+      # app. Notifications need no string — declare with `true`.
+      #
+      #   permissions:
+      #     notifications: true
+      #     camera: "Scan QR codes to pair devices."
+      #     location:
+      #       ios: "Find build agents near you."
+      #     biometrics: "Unlock your account with Face ID."
+      #
+      # Returns { name => { "ios" => usage-or-nil, ... } }.
+      MOBILE_PERMISSIONS = %w[notifications camera location biometrics].freeze
+
+      # Info.plist usage-description keys per permission. Presence here makes
+      # the usage string mandatory on iOS.
+      IOS_USAGE_KEYS = {
+        "camera" => "NSCameraUsageDescription",
+        "location" => "NSLocationWhenInUseUsageDescription",
+        "biometrics" => "NSFaceIDUsageDescription"
+      }.freeze
+
+      # Manifest <uses-permission> names per permission, stamped into
+      # src/stamped/AndroidManifest.xml. Deliberately *not* the mirror of
+      # IOS_USAGE_KEYS: presence here mandates nothing, because Android has no
+      # Info.plist-style contract — a runtime request without a rationale string
+      # prompts normally instead of terminating the process, and the rationale is
+      # a dialog the app draws itself, not a manifest value. So the map only
+      # answers "which manifest entry does this permission need", and every
+      # declared name has one.
+      #
+      # ACCESS_FINE_LOCATION implies ACCESS_COARSE_LOCATION on API 31+ only when
+      # both are declared, but the shell asks for precise location, so the fine
+      # permission alone is the honest declaration.
+      ANDROID_PERMISSIONS = {
+        "notifications" => "android.permission.POST_NOTIFICATIONS",
+        "camera" => "android.permission.CAMERA",
+        "location" => "android.permission.ACCESS_FINE_LOCATION",
+        "biometrics" => "android.permission.USE_BIOMETRIC"
+      }.freeze
+
+      def permissions
+        entries = @data["permissions"]
+        return {} unless entries.is_a?(Hash)
+
+        entries.each_with_object({}) do |(name, value), acc|
+          next if value.nil? || value == false
+
+          acc[name.to_s] =
+            case value
+            when String then { "ios" => value }
+            when Hash then value.transform_keys(&:to_s).transform_values(&:to_s)
+            else {}
+            end
+        end
+      end
+
+      # The manifest permissions an Android build declares, in declaration order.
+      # Only known names map to anything; permission_errors("android") has
+      # already failed the build on the rest by the time the builder asks.
+      def android_manifest_permissions
+        permissions.keys.filter_map { |name| ANDROID_PERMISSIONS[name] }.uniq
+      end
+
+      # Problems with the permissions declaration for one platform, as
+      # human-readable strings — unknown names, and camera/location missing the
+      # mandatory usage string. Empty means buildable.
+      #
+      # Only the unknown-name half applies to Android: the usage string exists to
+      # satisfy iOS, which kills the app when a prompt has no Info.plist entry.
+      # Android just prompts, so requiring the sentence there would fail builds
+      # over a value nothing reads.
+      def permission_errors(os)
+        permissions.flat_map do |name, usage|
+          unless MOBILE_PERMISSIONS.include?(name)
+            next ["unknown permission #{name.inspect} — supported: #{MOBILE_PERMISSIONS.join(", ")}"]
+          end
+
+          if os == "ios" && IOS_USAGE_KEYS.key?(name) && usage["ios"].to_s.strip.empty?
+            next ["#{name} needs a usage string — the sentence iOS shows when asking. " \
+                  "In config/everywhere.yml:\n  permissions:\n    #{name}: \"Why the app needs #{name}.\""]
+          end
+
+          []
+        end
+      end
+
+      # App-declared Hotwire Native path-configuration rules (everywhere.yml
+      # top-level `rules:`), appended after MOBILE_PATH_RULES — later rules win
+      # per property, so apps can make routes modal, disable pull-to-refresh,
+      # or set any other Hotwire path property without touching native code:
+      #
+      #   rules:
+      #     - patterns: ["/preferences$"]
+      #       properties:
+      #         context: default        # not a modal, unlike other /edit routes
+      #     - patterns: ["/live/"]
+      #       properties:
+      #         pull_to_refresh_enabled: false
+      # Native screens are selected by a different property on each platform, so
+      # `os` decides how a rule's `view_controller:` is read (see
+      # #android_screen_properties).
+      def mobile_rules(os = nil)
+        entries = @data["rules"]
+        return [] unless entries.is_a?(Array)
+
+        entries.filter_map do |rule|
+          next unless rule.is_a?(Hash) && rule["patterns"].is_a?(Array) && rule["properties"].is_a?(Hash)
+
+          properties = rule["properties"]
+          properties = android_screen_properties(properties) if android_target?(os)
+          { "patterns" => rule["patterns"].map(&:to_s), "properties" => properties }
+        end
+      end
+
+      # Hotwire Native iOS picks a native screen with `view_controller: <id>`;
+      # Android picks one with `uri: hotwire://fragment/<id>`, matched against the
+      # Fragment's own @HotwireDestinationDeepLink annotation. Same rule, same
+      # identifier, different property name — so the Android document derives the
+      # `uri` rather than making apps write the route twice and keep the two in
+      # sync by hand.
+      #
+      # Derived only for ids declared under native.android.screens: an id that
+      # names an iOS-only screen must fall through to the web fragment, because a
+      # `uri` pointing at a Fragment this build doesn't contain resolves to
+      # nothing and the visit dead-ends. An explicit `uri:` always wins — that's
+      # the escape hatch for a screen whose annotation says something else.
+      def android_screen_properties(properties)
+        id = properties["view_controller"]
+        return properties if id.nil? || properties.key?("uri")
+        return properties unless native_android_screens.key?(id.to_s)
+
+        properties.merge("uri" => "hotwire://fragment/#{id}")
+      end
+
+      # The full path-configuration document for one mobile platform — rules plus
+      # our settings (tabs live in settings, per Hotwire Native convention).
+      # Pass `tabs:` to override the resolved list (the mobile config endpoint
+      # passes a per-request-filtered list; build-time stamping omits it and
+      # bakes them all).
+      def path_configuration_hash(os, tabs: nil)
+        settings = {}
+        platform_tabs = tabs || tabs_for(os)
+        settings["tabs"] = platform_tabs unless platform_tabs.empty?
+        { "settings" => settings, "rules" => MOBILE_PATH_RULES + mobile_rules(os) }
+      end
+
+      def path_configuration_json(os, tabs: nil)
+        require "json"
+        JSON.generate(path_configuration_hash(os, tabs: tabs))
+      end
+    end
+  end
+end

data/lib/everywhere/config/native_desktop.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require_relative "native_mobile"
+
+module Everywhere
+  class Config
+    module NativeDesktop
+      # The desktop half of "supernative": Rust the app repo carries in
+      # native/desktop/ that `every build` compiles into the Tauri shell.
+      #
+      # The shape differs from ios/android because desktop differs: the whole UI
+      # is a webview, so there are no native screens or splash views to register.
+      # What an app actually wants down here is the machine — a serial port, a USB
+      # device, an FFI library, a Tauri plugin — reached from the page.
+      #
+      #   native:
+      #     desktop:
+      #       commands: [scan_ports]        # fns reachable from the page
+      #       setup: true                   # run native/desktop/setup.rs at boot
+      #       crates:
+      #         serialport: "4.3"
+      #         reqwest: { version: "0.12", features: [json] }
+      #
+      # A command is a plain function, NOT a #[tauri::command] — Tauri's typed
+      # commands only arrive through invoke, and invoke is unavailable to our
+      # pages (they're served over http; see extension_host.rs in the shell). The
+      # signature is uniform:
+      #
+      #   pub fn scan_ports(app: &tauri::AppHandle, payload: serde_json::Value)
+      #       -> Result<serde_json::Value, String>
+      #
+      # Declaring anything here has a real cost the mobile sections don't have:
+      # the shell stops being one prebuilt crate shared by every app and gets
+      # stamped and compiled per app (see Builders::Desktop). Apps that declare
+      # nothing keep the fast path.
+      def native_desktop
+        section = @data.dig("native", "desktop")
+        section.is_a?(Hash) ? section : {}
+      end
+
+      def native_desktop_commands = Array(native_desktop["commands"]).map { |name| name.to_s.strip }
+
+      def native_desktop_setup? = native_desktop["setup"] == true
+
+      # Cargo dependencies, normalized to { "name" => {...table} } so the
+      # generator has one shape to write. The short form (a bare version string)
+      # becomes { "version" => "4.3" }.
+      def native_desktop_crates
+        entries = native_desktop["crates"]
+        return {} unless entries.is_a?(Hash)
+
+        entries.to_h do |name, spec|
+          table = spec.is_a?(Hash) ? spec : { "version" => spec.to_s }
+          [name.to_s.strip, table]
+        end
+      end
+
+      def native_desktop? = !(native_desktop_commands.empty? && native_desktop_crates.empty?) ||
+                            native_desktop_setup?
+
+      # Everything here is interpolated into generated Rust and TOML, so names are
+      # validated hard — same reasoning as MAVEN_COORDINATE above. A command name
+      # becomes a path segment in a generate_handler! list; a crate name and its
+      # features become bare TOML keys and quoted strings.
+      RUST_FN_NAME = /\A[a-z_][a-z0-9_]*\z/
+      CRATE_NAME = /\A[a-zA-Z0-9_][a-zA-Z0-9_-]*\z/
+      # Cargo's requirement syntax, loosely: ^1.2, ~1.2, >=1.0, 1.*, 1.2.3-beta.1.
+      # Deliberately no spaces and no commas — a multi-requirement string would
+      # need quoting rules we don't want to own, and cargo reports anything
+      # subtler at build time.
+      CRATE_VERSION = /\A[\^~<>=]{0,2}\d+(\.\d+){0,2}(\.\*)?(-[0-9A-Za-z.-]+)?\z/
+      CRATE_FEATURE = /\A[A-Za-z0-9_][A-Za-z0-9_+-]*\z/
+      # Where a git dependency may point. Same rule the SPM packages use —
+      # named through NativeMobile because a sibling section module's constants
+      # aren't in scope here the way they were when both lived in Config.
+      CRATE_GIT_URL = NativeMobile::PACKAGE_URL
+
+      def native_desktop_errors
+        raw = @data.dig("native", "desktop")
+        return [] if raw.nil?
+        return ["native.desktop must be a mapping"] unless raw.is_a?(Hash)
+
+        errors = []
+        commands = raw["commands"]
+        if !commands.nil? && !commands.is_a?(Array)
+          errors << "native.desktop.commands must be a list of function names"
+        else
+          errors += native_desktop_commands.reject { |name| name.match?(RUST_FN_NAME) }.map do |name|
+            "native.desktop.commands: #{name.inspect} is not a Rust function name — " \
+              "snake_case (letters, digits, _), matching the fn in native/desktop/"
+          end
+          duplicates = native_desktop_commands.tally.select { |_name, count| count > 1 }.keys
+          errors += duplicates.map do |name|
+            "native.desktop.commands: #{name.inspect} is listed twice"
+          end
+        end
+
+        setup = raw["setup"]
+        errors << "native.desktop.setup must be true or false" unless setup.nil? || boolean_or_nil(setup) == setup
+
+        errors + native_desktop_crate_errors
+      end
+
+      def native_desktop_crate_errors
+        raw = native_desktop["crates"]
+        return [] if raw.nil?
+        return ["native.desktop.crates must be a mapping of crate name to version"] unless raw.is_a?(Hash)
+
+        raw.flat_map do |name, spec|
+          at = "native.desktop.crates.#{name}"
+          errors = []
+          unless name.to_s.strip.match?(CRATE_NAME)
+            errors << "#{at}: #{name.to_s.inspect} is not a crate name (letters, digits, _, -)"
+          end
+          errors + crate_spec_errors(at, spec)
+        end
+      end
+
+      private
+
+      # One crate's dependency spec: either a bare version string or a table.
+      def crate_spec_errors(at, spec)
+        return version_errors(at, spec) unless spec.is_a?(Hash)
+
+        errors = []
+        # A crate needs somewhere to come from. version: is the common case; git:
+        # and path: are the two escape hatches cargo itself offers.
+        unless %w[version git path].any? { |key| !spec[key].to_s.strip.empty? }
+          errors << "#{at} needs a version: (or git: / path:)"
+        end
+        errors += version_errors("#{at}.version", spec["version"]) if spec.key?("version")
+
+        git = spec["git"].to_s.strip
+        unless git.empty? || git.match?(CRATE_GIT_URL)
+          errors << "#{at}.git #{git.inspect} must be an https:// or git@ URL"
+        end
+
+        # branch/tag/rev/path have no useful shape to check, but they DO end up
+        # inside quoted TOML strings — so the one thing that matters is that they
+        # can't close the quote or start a new line.
+        errors += %w[branch tag rev path].filter_map do |key|
+          value = spec[key].to_s
+          next if value.empty? || !value.match?(/["\\\n\r]/)
+
+          "#{at}.#{key} can't contain quotes, backslashes or newlines"
+        end
+
+        features = spec["features"]
+        if !features.nil? && !features.is_a?(Array)
+          errors << "#{at}.features must be a list"
+        else
+          errors += Array(features).reject { |f| f.to_s.match?(CRATE_FEATURE) }.map do |feature|
+            "#{at}.features: #{feature.to_s.inspect} is not a feature name (letters, digits, _, +, -)"
+          end
+        end
+        errors
+      end
+
+      def version_errors(at, value)
+        version = value.to_s.strip
+        return [] if version.empty?
+        return [] if version.match?(CRATE_VERSION)
+
+        ["#{at} #{version.inspect} is not a cargo version requirement — like \"1.2\", \"^1.2.3\" or \"~0.4\""]
+      end
+    end
+  end
+end