fastlane-plugin-bugsee 1.0.2 → 1.1.0

data/README.md

@@ -12,8 +12,7 @@ fastlane add_plugin bugsee
 
 ## About bugsee
 
-Bugsee is free crash and bug reporting with video, network and logs. Sign up for a service at [https://www.bugsee.com](https://www.bugsee.com). This plugin implements fastlane action to upload debug
-symbol (dSYM) files to Bugsee servers.
+Bugsee is free crash and bug reporting with video, network and logs. Sign up for a service at [https://www.bugsee.com](https://www.bugsee.com). This plugin implements a fastlane action that uploads debug symbol (dSYM) files to Bugsee, and — when invoked from an Xcode build phase — also collects and registers the project's dependency graph.
 
 ## Usage
 
@@ -42,6 +41,107 @@ lane :refresh_dsyms do
 end
 ```
 
+## How symbol upload works
+
+Starting with `1.1.0`, symbol upload shells out to the [bugsee-cli](https://github.com/bugsee/bugsee-cli) Rust binary — the same uploader the Bugsee Android Gradle plugin uses for ProGuard/R8 mappings. One mechanism, one wire format across both platforms.
+
+On first use the CLI is downloaded from `https://download.bugsee.com/cli`, SHA-256 verified against the published sidecar, and cached at `~/.bugsee/cli/<version>/<host-triple>/`. Subsequent runs hit the cache — no per-build network round-trip past the dSYM upload itself.
+
+Override the auto-download with environment variables:
+
+| Variable | Purpose |
+| --- | --- |
+| `BUGSEE_CLI_PATH` | Path to a local `bugsee-cli` binary. Useful when developing the CLI itself or in air-gapped CI. |
+| `BUGSEE_CLI_VERSION` | Pin or test a specific CLI release; defaults to the version bundled with this plugin release. |
+
+Each `.dSYM` is uploaded as its own request, so the dashboard surfaces a per-framework symbol record. If a host architecture isn't supported by the published CLI (currently macOS / Linux / Windows on x86_64 + arm64, where each platform exists), the agent logs and skips — it does not fail the build.
+
+## Dependency collection
+
+When `BugseeAgent` runs from an Xcode build phase (where `SRCROOT` / `INFOPLIST_PATH` are set), it also scans the project for dependency lockfiles and registers the resolved graph with the build:
+
+- **CocoaPods** — `Podfile.lock` (provides direct/transitive distinction and parent edges).
+- **Swift Package Manager** — `Package.resolved` (both Xcode-managed and SPM CLI v2 formats).
+- **Carthage** — `Cartfile.resolved`.
+
+The emitted blob is wire-compatible with the Bugsee Android Gradle plugin's `DependencyCollector`, so iOS and Android deps render identically in the dashboard.
+
+No configuration is required — if a lockfile exists, it's collected.
+
+## Android mapping (ProGuard / R8) upload
+
+Starting with `1.1.0`, this plugin also supports uploading Android `mapping.txt` files via a separate `upload_mapping_to_bugsee` action. The canonical path remains the [Bugsee Android Gradle plugin](https://github.com/bugsee/bugsee-android-gradle-plugin), which does the upload automatically as part of every gradle build. Reach for this fastlane action only when one of the following applies:
+
+- **Your CI splits build (no token) from publish (production token).** The Gradle plugin builds the APK on machine A without uploading; this action uploads the mapping on machine B with the production token. The action looks for the Gradle plugin's `build-uuid.txt` (under `**/build/intermediates/bugsee/*/build-uuid.txt`) so the UUID matches what the SDK already has baked into the APK.
+- **The host app is not instrumented by the Bugsee Gradle plugin** — *and* uses Bugsee Android SDK 7.0.0-beta13+. The action synthesises a UUID Ruby-side from `(app_token, version, build)`; the SDK reproduces the same UUID at runtime via its third BUILD_UUID fallback (added in 7.0.0-beta13), so symbolication still works.
+
+If neither applies — i.e. you're using the Gradle plugin in the standard way — there's nothing to do; the Gradle plugin handles the upload as part of the existing `gradle` action.
+
+Example invocation:
+
+```ruby
+upload_mapping_to_bugsee(
+  app_token:    ENV["BUGSEE_APP_TOKEN"],
+  mapping_path: "./app/build/outputs/mapping/release/mapping.txt",
+  version:      "1.2.3",   # android:versionName
+  build:        "42",      # android:versionCode
+  # Optional:
+  # uuid:            "...",  # explicit override
+  # build_uuid_path: "app/build/intermediates/bugsee/release/build-uuid.txt",
+  # icon_path:       "app/src/main/res/mipmap-xxxhdpi/ic_launcher.png",
+)
+```
+
+**UUID resolution chain** (most authoritative to fallback):
+
+1. Explicit `:uuid` if passed.
+2. `:build_uuid_path` if given and the file exists.
+3. The Bugsee Gradle plugin's `build-uuid.txt`, auto-globbed under `**/build/intermediates/bugsee/*/build-uuid.txt`.
+4. Ruby-side synthesis: `nameUUIDFromBytes(app_token + 0x1F + version + 0x1F + build)` — matches the SDK's Channel 3 runtime fallback (7.0.0-beta13+).
+
+All four branches produce a UUID the SDK can independently reproduce, so server-side mapping lookup resolves crashes correctly regardless of which branch fired.
+
+The action `is_supported?(:android)` only.
+
+## iOS artefact upload (size analysis)
+
+This plugin also exposes an `upload_artifact_to_bugsee` action that packages a built `.app` into a byte-deterministic synthetic `.ipa` and uploads it to Bugsee for size analysis. The canonical path remains the [Bugsee iOS SDK](https://github.com/bugsee/bugsee-ios)'s `tools.bundle/BugseeAgent` build phase, which runs size analysis automatically when `BUGSEE_BUILD_INFO_ENABLED` is on (default). Reach for this fastlane action only when one of the following applies:
+
+- **Your CI doesn't integrate the SDK's build phase.** Binary-only CI, alternative build systems (Bazel, Tuist with custom phases), or pipelines that pre-build the `.app` and only invoke fastlane for publish.
+- **Your CI splits build (no token) from publish (production token).** The build machine produces the `.app` or `.xcarchive`; the publish machine runs this action with the production token.
+- **You want the size-trend chart without shipping bytes.** Pass `build_info_only: true` to record `artifact_size` on the server (so the dashboard's size-trend chart works) without uploading the `.ipa` bytes themselves. Useful for firewalled CI and privacy-sensitive setups.
+
+If the SDK's build phase already runs in the same Xcode build, the action's cross-producer handshake skips by default (the SDK writes a manifest at `build/bugsee/build-actions.json`; the action reads it and short-circuits when `artifact_upload: true`). Pass `force: true` to override.
+
+Example invocation:
+
+```ruby
+upload_artifact_to_bugsee(
+  app_token:      ENV["BUGSEE_APP_TOKEN"],
+  xcarchive_path: ENV["XCARCHIVE_PATH"],
+  # OR pass the .app directly:
+  # app_path:     "build/Products/Release-iphoneos/MyApp.app",
+  # Optional:
+  # version:          "1.2.3",   # CFBundleShortVersionString (else read from Info.plist)
+  # build:            "42",      # CFBundleVersion              (else read from Info.plist)
+  # build_info_only:  true,      # record size, skip the .ipa bytes upload
+  # force:            true,      # override the cross-producer handshake skip
+)
+```
+
+**App path resolution:**
+
+1. Explicit `:app_path` if passed.
+2. `:xcarchive_path` → the single `.app` under `<archive>/Products/Applications/`. Multiple `.app` siblings raise a `user_error` so the user can disambiguate.
+
+**Env var aliases** (all are also exposed via fastlane's `available_options`):
+
+- `BUGSEE_APP_TOKEN`, `BUGSEE_APP_PATH`, `BUGSEE_XCARCHIVE_PATH`
+- `BUGSEE_APP_VERSION`, `BUGSEE_APP_BUILD`
+- `BUGSEE_BUILD_INFO_ONLY`, `BUGSEE_FORCE`
+
+The action `is_supported?(:ios)` only.
+
 ## Documentation
 
 Further documentation about Bugsee crash symbolication is available at https://docs.bugsee.com

data/lib/fastlane/plugin/bugsee/actions/upload_artifact_to_bugsee.rb

@@ -0,0 +1,230 @@
+require 'fastlane/plugin/bugsee/helper/bugsee_handshake'
+
+module Fastlane
+  module Actions
+    # Upload an iOS build artefact (`.app`) to Bugsee for size analysis.
+    #
+    # When and why to use this:
+    #
+    #   The Bugsee iOS SDK's `tools.bundle/BugseeAgent` already runs
+    #   size analysis as a post-action build phase when
+    #   `BUGSEE_BUILD_INFO_ENABLED` is on (default). The most common
+    #   scenario for THIS fastlane action is CI pipelines that don't
+    #   integrate the SDK's build phase (binary-only CI, alternative
+    #   build systems) or that explicitly split build (machine A) from
+    #   publish (machine B, has the production token).
+    #
+    # What it does:
+    #
+    #   1. Locates the `.app` — explicit `:app_path`, OR resolved from
+    #      `:xcarchive_path` via `Products/Applications/<App>.app`.
+    #   2. Shells to `BugseeAgent --upload-artifact` which:
+    #      - Packages the `.app` into a synthetic byte-deterministic
+    #        `.ipa` (same posture as the SDK side and the Android
+    #        Gradle plugin so the back-end's content-hash dedup works
+    #        across producers).
+    #      - POSTs build registration to /v2/apps/<token>/builds with
+    #        `request_artifact_upload: true`, getting back a presigned
+    #        S3 PUT URL.
+    #      - PUTs the .ipa bytes to that URL.
+    #
+    # Cross-producer handshake: if the Bugsee iOS SDK's BugseeAgent
+    # build phase already uploaded this build's artefact, skip — same
+    # gating shape as upload_symbols_to_bugsee and
+    # upload_mapping_to_bugsee.
+    class UploadArtifactToBugseeAction < Action
+      BUGSEE_AGENT_PATH = File.expand_path(
+        File.join(File.dirname(__FILE__), '..', '..', '..', '..', '..', 'BugseeAgent'))
+
+      def self.run(params)
+        app_token  = params[:app_token]
+        host       = params[:host] || "https://api.bugsee.com"
+        version    = params[:version]
+        build      = params[:build]
+        agent_path = params[:agent_path] || BUGSEE_AGENT_PATH
+
+        UI.user_error!("Please provide an app token via app_token:") unless app_token
+
+        agent_path = File.expand_path(agent_path)
+        UI.user_error!("BugseeAgent helper script is missing: #{agent_path}") unless File.exist?(agent_path)
+
+        # ──────────────────────────────────────────────────────
+        # Resolve the `.app` path. Priority:
+        #   1. Explicit :app_path
+        #   2. :xcarchive_path → Products/Applications/<single .app>
+        # ──────────────────────────────────────────────────────
+        app_path = resolve_app_path(params)
+        UI.user_error!(
+          "Please provide either :app_path or :xcarchive_path (with a single .app inside Products/Applications/)"
+        ) unless app_path
+        UI.user_error!("App path does not exist: #{app_path}") unless File.directory?(app_path)
+        UI.user_error!(
+          "App path must end in .app: #{app_path}"
+        ) unless app_path.end_with?('.app')
+
+        # ──────────────────────────────────────────────────────
+        # Cross-producer handshake
+        # ──────────────────────────────────────────────────────
+        # `artifact_upload` is the manifest action name the SDK
+        # BugseeAgent writes when it successfully shipped the IPA.
+        unless params[:force]
+          manifest = Fastlane::Bugsee::Handshake.find_manifest(
+            search_root: Dir.pwd,
+            version_name: version,
+            version_code: build,
+          )
+          if Fastlane::Bugsee::Handshake.handled_by_other?(manifest, 'artifact_upload')
+            UI.important(Fastlane::Bugsee::Handshake.skip_message(manifest, 'artifact_upload'))
+            return
+          end
+        end
+
+        UI.message("Bugsee: uploading artefact for #{File.basename(app_path)}")
+
+        # Shell command shape:
+        #   python3 BugseeAgent -x \
+        #     -e <host> [-v <ver>] [-b <build>] \
+        #     --upload-artifact \
+        #     --app-path <path> \
+        #     <app_token>
+        cmd = []
+        cmd << agent_path.shellescape
+        cmd << "-x"   # not run from Xcode — synchronous, no daemonize
+        cmd << "-e #{host.shellescape}"
+        cmd << "-v #{version.to_s.shellescape}" if version && !version.to_s.empty?
+        cmd << "-b #{build.to_s.shellescape}"   if build   && !build.to_s.empty?
+        cmd << "--upload-artifact"
+        cmd << "--app-path #{app_path.shellescape}"
+        # When build_info_only is true, skip the .ipa bytes upload —
+        # the registration POST still records artifact_size on the
+        # server so the dashboard's size-trend chart works, but the
+        # bytes never leave the build host. Useful for firewalled CI
+        # and privacy-sensitive setups.
+        cmd << "--build-info-only" if params[:build_info_only]
+        cmd << app_token.shellescape
+
+        begin
+          Actions.sh(cmd.join(" "), log: false)
+        rescue => e
+          # Upload failure should NOT take the lane down — size
+          # analysis is a release-supporting feature, same posture as
+          # the other Bugsee fastlane actions.
+          UI.error(e.to_s)
+        end
+      end
+
+      # @api private
+      # Resolves the `.app` path the user wants packaged. Public-ish
+      # so RSpec can exercise each branch in isolation.
+      def self.resolve_app_path(params)
+        explicit = params[:app_path]
+        return explicit if explicit && !explicit.to_s.empty?
+
+        archive_path = params[:xcarchive_path]
+        return nil unless archive_path && !archive_path.to_s.empty?
+
+        # An .xcarchive bundles the built `.app` at
+        # `<archive>/Products/Applications/<App>.app`. Usually exactly
+        # one `.app` is present; if multiple are present (extensions
+        # are bundled inside the main .app's Frameworks/ subtree, not
+        # a sibling at Products/Applications), we pick the only entry
+        # and error if ambiguous so the user can disambiguate via
+        # `:app_path`.
+        apps_dir = File.join(archive_path, 'Products', 'Applications')
+        return nil unless File.directory?(apps_dir)
+
+        matches = Dir.entries(apps_dir).select do |e|
+          e.end_with?('.app') && File.directory?(File.join(apps_dir, e))
+        end
+        if matches.length == 1
+          return File.join(apps_dir, matches.first)
+        elsif matches.length > 1
+          UI.user_error!(
+            "Multiple .app bundles found under #{apps_dir}; pass :app_path to disambiguate. Found: #{matches.inspect}"
+          )
+        end
+        nil
+      end
+
+      def self.description
+        "Upload an iOS build artefact (.app → synthetic .ipa) to Bugsee for size analysis."
+      end
+
+      def self.details
+        <<~DETAILS
+          Packages a built `.app` into a byte-deterministic synthetic `.ipa`
+          and uploads it to Bugsee for size analysis. The Bugsee iOS SDK's
+          tools.bundle/BugseeAgent build phase already does this when
+          BUGSEE_BUILD_INFO_ENABLED is on (default); this action is for CI
+          pipelines that don't integrate that build phase, or for
+          split-build/publish setups where build and upload run on
+          different machines.
+
+          App path resolution: explicit :app_path > :xcarchive_path with a
+          single .app inside Products/Applications/.
+
+          Cross-producer handshake: if the SDK's BugseeAgent build phase
+          already uploaded this build's artefact (recorded in the
+          build-actions.json manifest), this action skips by default. Pass
+          force: true to override.
+        DETAILS
+      end
+
+      def self.available_options
+        [
+          FastlaneCore::ConfigItem.new(key: :agent_path,
+                                       env_name: "BUGSEE_AGENT_PATH",
+                                       description: "The path to the BugseeAgent helper script",
+                                       optional: true,
+                                       verify_block: proc do |value|
+                                         UI.user_error!("Couldn't find BugseeAgent at path '#{value}'") unless File.exist?(value)
+                                       end),
+          FastlaneCore::ConfigItem.new(key: :host,
+                                       env_name: "BUGSEE_API_HOST",
+                                       description: "The path to API endpoint",
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :app_token,
+                                       env_name: "BUGSEE_APP_TOKEN",
+                                       description: "Bugsee iOS application token",
+                                       optional: false),
+          FastlaneCore::ConfigItem.new(key: :app_path,
+                                       env_name: "BUGSEE_APP_PATH",
+                                       description: "Path to the built `.app` directory. When unset, resolved from :xcarchive_path",
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :xcarchive_path,
+                                       env_name: "BUGSEE_XCARCHIVE_PATH",
+                                       description: "Path to the .xcarchive — used to resolve a single .app under Products/Applications/. Ignored when :app_path is set",
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :version,
+                                       env_name: "BUGSEE_APP_VERSION",
+                                       description: "CFBundleShortVersionString (e.g. \"1.2.3\"). Optional — read from Info.plist by BugseeAgent if absent",
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :build,
+                                       env_name: "BUGSEE_APP_BUILD",
+                                       description: "CFBundleVersion (e.g. \"42\"). Optional — read from Info.plist by BugseeAgent if absent",
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :build_info_only,
+                                       env_name: "BUGSEE_BUILD_INFO_ONLY",
+                                       description: "When true, register the build (records artifact_size for the size-trend chart) but skip shipping the .ipa bytes. Useful for firewalled CI and privacy-sensitive setups",
+                                       is_string: false,
+                                       default_value: false,
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :force,
+                                       env_name: "BUGSEE_FORCE",
+                                       description: "Skip the cross-producer handshake check and always upload, even if the Bugsee iOS SDK's BugseeAgent build phase already handled this build's artefact",
+                                       is_string: false,
+                                       default_value: false,
+                                       optional: true)
+        ]
+      end
+
+      def self.authors
+        ["bugsee"]
+      end
+
+      def self.is_supported?(platform)
+        platform == :ios
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/bugsee/actions/upload_mapping_to_bugsee.rb

@@ -0,0 +1,260 @@
+require 'fastlane/plugin/bugsee/helper/bugsee_uuid'
+require 'fastlane/plugin/bugsee/helper/bugsee_handshake'
+
+module Fastlane
+  module Actions
+    # Upload an Android ProGuard / R8 mapping.txt to Bugsee.
+    #
+    # When and why to use this:
+    #
+    #   The Bugsee Android Gradle plugin already uploads mapping.txt
+    #   as part of the standard gradle build. The most common
+    #   scenario for this fastlane action is CI pipelines that split
+    #   build (machine A, no token) from publish (machine B, has the
+    #   production token) — gradle builds the APK on A; fastlane on
+    #   B uploads the mapping with the production token. The action
+    #   ALSO works for apps not instrumented by the Bugsee Gradle
+    #   plugin, but only when paired with Bugsee Android SDK
+    #   7.0.0-beta13+ (older SDKs cannot match crashes against a
+    #   synthesized UUID).
+    #
+    # UUID resolution chain (from most authoritative to fallback):
+    #
+    #   1. The :uuid ConfigItem when passed explicitly. Escape hatch.
+    #   2. The Bugsee Gradle plugin's BugseeBuildIdResolveTask
+    #      output file (build/intermediates/bugsee/<variant>/
+    #      build-uuid.txt). When this file is present, the Gradle
+    #      plugin IS in the loop and the UUID it computed is the
+    #      authoritative value that the SDK's asset / manifest
+    #      channels carry at runtime.
+    #   3. Ruby-side synthesis matching the SDK's Channel 3
+    #      fallback formula:
+    #        UUID.nameUUIDFromBytes(
+    #          app_token + 0x1F + version + 0x1F + build
+    #        )
+    #      Only useful when the host app uses SDK 7.0.0-beta13+
+    #      AND has no Gradle plugin in the loop.
+    #
+    # All three branches produce a UUID the SDK can independently
+    # reproduce at runtime, so the server-side mapping lookup
+    # resolves crashes correctly regardless of which branch fired.
+    class UploadMappingToBugseeAction < Action
+      BUGSEE_AGENT_PATH = File.expand_path(
+        File.join(File.dirname(__FILE__), '..', '..', '..', '..', '..', 'BugseeAgent'))
+
+      # Glob pattern for the Bugsee Gradle plugin's
+      # BugseeBuildIdResolveTask output. Used by the UUID resolution
+      # chain when :build_uuid_path isn't explicit. The leading
+      # `**/` covers multi-module projects where the `app/` module
+      # nests under a top-level checkout.
+      BUILD_UUID_GLOB = "**/build/intermediates/bugsee/*/build-uuid.txt".freeze
+
+      def self.run(params)
+        app_token    = params[:app_token]
+        mapping_path = params[:mapping_path]
+        host         = params[:host] || "https://api.bugsee.com"
+        version      = params[:version]
+        build        = params[:build]
+        icon_path    = params[:icon_path]
+        agent_path   = params[:agent_path] || BUGSEE_AGENT_PATH
+
+        UI.user_error!("Please provide an app token via app_token:") unless app_token
+        UI.user_error!("Please provide a path to the Android mapping.txt via mapping_path:") unless mapping_path
+        UI.user_error!("Mapping file does not exist: #{mapping_path}") unless File.exist?(mapping_path)
+        UI.user_error!("Please provide an app version via version: (android:versionName)") if version.nil? || version.to_s.empty?
+        UI.user_error!("Please provide a build number via build: (android:versionCode)") if build.nil? || build.to_s.empty?
+
+        agent_path = File.expand_path(agent_path)
+        UI.user_error!("BugseeAgent helper script is missing: #{agent_path}") unless File.exist?(agent_path)
+
+        if icon_path && !File.exist?(icon_path)
+          UI.important("Bugsee: icon_path does not exist (#{icon_path}); proceeding without icon")
+          icon_path = nil
+        end
+
+        # Cross-producer handshake: if the Bugsee Android Gradle
+        # plugin already uploaded this build's mapping, skip — the
+        # server would just dedupe by hash but the lane log gets
+        # noisy and CI pays for redundant bandwidth. The user can
+        # override with `force: true` for re-uploads / debugging.
+        unless params[:force]
+          manifest = Fastlane::Bugsee::Handshake.find_manifest(
+            search_root: Dir.pwd,
+            version_name: version,
+            version_code: build,
+          )
+          if Fastlane::Bugsee::Handshake.handled_by_other?(manifest, 'mapping_upload')
+            UI.important(Fastlane::Bugsee::Handshake.skip_message(manifest, 'mapping_upload'))
+            return
+          end
+        end
+
+        uuid = resolve_uuid(params, app_token, version, build)
+        UI.message("Bugsee: uploading mapping with UUID #{uuid}")
+
+        # Shell command shape:
+        #   python3 BugseeAgent -x \
+        #     -e <host> -v <version> -b <build> \
+        #     --upload-mapping \
+        #     --mapping-path <mapping.txt> \
+        #     --mapping-uuid <uuid> \
+        #     [--icon <icon>] \
+        #     [--cli-path <path> | --cli-version <ver>] \
+        #     <app_token>
+        cmd = []
+        cmd << agent_path.shellescape
+        cmd << "-x"   # not run from Xcode — synchronous, no daemonize
+        cmd << "-e #{host.shellescape}"
+        cmd << "-v #{version.to_s.shellescape}"
+        cmd << "-b #{build.to_s.shellescape}"
+        cmd << "--upload-mapping"
+        cmd << "--mapping-path #{mapping_path.shellescape}"
+        cmd << "--mapping-uuid #{uuid.shellescape}"
+        cmd << "--icon #{icon_path.shellescape}" if icon_path
+        cmd << "--cli-path #{params[:cli_path].shellescape}" if params[:cli_path]
+        cmd << "--cli-version #{params[:cli_version].shellescape}" if params[:cli_version]
+        cmd << app_token.shellescape
+
+        begin
+          Actions.sh(cmd.join(" "), log: false)
+        rescue => e
+          # Upload failure should NOT take the lane down — the
+          # symbols upload is a release-supporting nicety, same
+          # posture as upload_symbols_to_bugsee. The Ruby UI.error
+          # surfaces the cause in the build log.
+          UI.error(e.to_s)
+        end
+      end
+
+      # @api private
+      # Resolution chain implemented as documented in the class
+      # docstring above. Public-ish so the RSpec tests can exercise
+      # each branch in isolation.
+      def self.resolve_uuid(params, app_token, version, build)
+        explicit = params[:uuid]
+        return explicit if explicit && !explicit.to_s.empty?
+
+        # Branch 2: Gradle plugin's BugseeBuildIdResolveTask output.
+        # When :build_uuid_path is explicit, trust it. Otherwise glob
+        # under the current working directory (most fastlane lanes
+        # cd to the project root before invoking actions).
+        build_uuid_path = params[:build_uuid_path]
+        if build_uuid_path
+          if File.exist?(build_uuid_path)
+            return File.read(build_uuid_path).strip
+          else
+            UI.important("Bugsee: build_uuid_path given but not found: #{build_uuid_path}")
+          end
+        else
+          # Best-effort glob. Take the first match — multi-variant
+          # projects may have several; if the lane wants a specific
+          # variant, it should pass :build_uuid_path explicitly.
+          match = Dir.glob(BUILD_UUID_GLOB).first
+          return File.read(match).strip if match
+        end
+
+        # Branch 3: synthesize from (app_token, version, build).
+        # Matches the SDK's Channel 3 fallback formula byte-for-byte
+        # so a 7.0.0-beta13+ SDK at runtime computes the same UUID
+        # and the upload matches.
+        UI.message("Bugsee: no Gradle plugin build-uuid.txt found; " \
+                   "synthesizing UUID from app_token+version+build. " \
+                   "This requires Bugsee Android SDK >= 7.0.0-beta13 " \
+                   "at runtime.")
+        Fastlane::Bugsee::Uuid.synthesize_build_uuid(app_token, version, build)
+      end
+
+      def self.description
+        "Upload an Android ProGuard / R8 mapping.txt to Bugsee."
+      end
+
+      def self.details
+        <<~DETAILS
+          Uploads an Android ProGuard / R8 mapping.txt to Bugsee for crash
+          symbolication. The Bugsee Android Gradle plugin already does this
+          as part of the standard gradle build; this action is for split
+          build/publish CI pipelines and for apps not instrumented by the
+          Gradle plugin (the latter requires Bugsee Android SDK 7.0.0-beta13+).
+
+          UUID resolution: explicit :uuid > :build_uuid_path > the Gradle
+          plugin's build-uuid.txt (auto-globbed) > synthesized from
+          (app_token, version, build) matching the SDK's runtime fallback.
+        DETAILS
+      end
+
+      def self.available_options
+        [
+          FastlaneCore::ConfigItem.new(key: :agent_path,
+                                       env_name: "BUGSEE_AGENT_PATH",
+                                       description: "The path to the BugseeAgent helper script",
+                                       optional: true,
+                                       verify_block: proc do |value|
+                                         UI.user_error!("Couldn't find BugseeAgent at path '#{value}'") unless File.exist?(value)
+                                       end),
+          FastlaneCore::ConfigItem.new(key: :host,
+                                       env_name: "BUGSEE_API_HOST",
+                                       description: "The path to API endpoint",
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :app_token,
+                                       env_name: "BUGSEE_APP_TOKEN",
+                                       description: "Bugsee Android application token",
+                                       optional: false),
+          FastlaneCore::ConfigItem.new(key: :mapping_path,
+                                       env_name: "BUGSEE_MAPPING_PATH",
+                                       description: "Path to the Android mapping.txt (R8 / ProGuard)",
+                                       optional: false),
+          # Fastlane's Android `gradle` action publishes no
+          # SharedValues equivalent of iOS's VERSION_NUMBER /
+          # BUILD_NUMBER — :version / :build remain explicit
+          # ConfigItems with no auto-default. The action validates
+          # both in .run and raises a UI.user_error if missing.
+          # Consumers typically wire these from get_version_name /
+          # get_version_code (community actions) or read them from
+          # build.gradle themselves before calling this action.
+          FastlaneCore::ConfigItem.new(key: :version,
+                                       env_name: "BUGSEE_APP_VERSION",
+                                       description: "android:versionName (e.g. \"1.2.3\")",
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :build,
+                                       env_name: "BUGSEE_APP_BUILD",
+                                       description: "android:versionCode (e.g. \"42\")",
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :uuid,
+                                       env_name: "BUGSEE_BUILD_UUID",
+                                       description: "Override BUILD_UUID. When unset, the action reads the Bugsee Gradle plugin's build-uuid.txt OR synthesizes via MD5",
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :build_uuid_path,
+                                       env_name: "BUGSEE_BUILD_UUID_PATH",
+                                       description: "Explicit path to the Bugsee Gradle plugin's build-uuid.txt. When unset, the action globs **/build/intermediates/bugsee/*/build-uuid.txt",
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :icon_path,
+                                       env_name: "BUGSEE_ICON_PATH",
+                                       description: "Optional launcher icon PNG to attach to the symbol record",
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :cli_path,
+                                       env_name: "BUGSEE_CLI_PATH",
+                                       description: "Path to a local bugsee-cli binary (developer override)",
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :cli_version,
+                                       env_name: "BUGSEE_CLI_VERSION",
+                                       description: "bugsee-cli version to auto-download",
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :force,
+                                       env_name: "BUGSEE_FORCE",
+                                       description: "Skip the cross-producer handshake check and always upload, even if the Bugsee Android Gradle plugin already handled this build's mapping",
+                                       is_string: false,
+                                       default_value: false,
+                                       optional: true)
+        ]
+      end
+
+      def self.authors
+        ["bugsee"]
+      end
+
+      def self.is_supported?(platform)
+        platform == :android
+      end
+    end
+  end
+end