fastlane-plugin-pharen 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8cd4f080adf3fef449642139ef7ca42ee6f186325ca8948ee05dc7fdab939c3a
+  data.tar.gz: 4db24993e8d906973ab4c91e8df26d26bd01104c00c332c3d2419a85b62f4b54
+SHA512:
+  metadata.gz: a05b26ce9c1de6c6c1fa251948a7d6af63bd6e89bf4bef1338d7247c6ca37290e7dbbbe5864ab2d83f51450ed719b23ebdd2d6d993e9e0a4140e7891af2137c2
+  data.tar.gz: 3b6f71ab17e05f1b1f50488360a7533e2dbfe5757d0b36f536c42daef9f662f092be6a628f2b9e94bee3d4de2b9a4ff6671d6cd9dff164ad095e7253ea0b8f9a

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to `fastlane-plugin-pharen` are documented here.
+
+## 0.1.0 — initial release
+
+Three actions, a thin wrapper over the `pharen` CLI (auth, `.pharen.yml` resolution,
+debug-id parsing and server-side dedupe all live there):
+
+- **`pharen_release`** — the whole integration in one call after `build_app`: registers
+  the release, uploads every dSYM the archive produced, uploads the build, and returns
+  the OTA install link. Zero-arg by design — IPA and dSYMs come from the lane context,
+  version/build/bundle id are read from the IPA's own `Info.plist`, the commit sha from
+  git, org/app from the committed `.pharen.yml`, auth from `PHAREN_AUTH_TOKEN`.
+- **`pharen_upload_build`** — upload the IPA and get the install link back, standalone.
+- **`pharen_upload_symbols`** — upload dSYMs for crash symbolication, standalone. Accepts
+  `.dSYM` bundles, dSYM `.zip` files (as produced by `gym`/`download_dsyms`), or raw
+  DWARF binaries.
+
+**Failure posture:** warn-don't-fail by default — a telemetry step should never be the
+reason a release build fails. Pass `strict: true` (or set `PHAREN_STRICT=1`) in CI lanes
+where an unsymbolicated release must be a hard stop. A missing-dSYM situation always
+warns loudly regardless of mode, since a build shipped without symbols leaves every
+crash it produces unsymbolicated forever.
+
+**Auth:** `PHAREN_AUTH_TOKEN` is read from the environment only — the plugin never
+reads, prints, or passes it on a command line.
+
+**Dependencies:** none beyond `fastlane` itself at runtime. The plugin shells out to the
+`pharen` CLI and reads its JSON-on-stdout contract; all wire logic (auth, config
+resolution, debug-id parsing, dedupe) lives in the CLI.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucubra LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,132 @@
+# fastlane-plugin-pharen
+
+Ship an iOS build to Pharen from your Fastfile. One action, `pharen_release`, runs after
+`build_app`: it registers the release, uploads every dSYM for crash symbolication,
+uploads the build, and returns an OTA install link — with nothing to configure in the
+lane.
+
+The plugin is a thin wrapper over the `pharen` CLI. Authentication, `.pharen.yml`
+resolution, debug-id parsing, and server-side dedupe all live in the CLI; the plugin only
+derives what the CLI needs from the lane context and the built artifacts. It adds no
+runtime gem dependencies of its own.
+
+## Install
+
+```sh
+fastlane add_plugin pharen
+```
+
+Once per repository, you also need:
+
+- the `pharen` CLI on `PATH` (or point `pharen_binary:` / `PHAREN_BINARY` at it),
+- a committed `.pharen.yml` at the repo root (`org:` and `app:` — no secrets),
+- `PHAREN_AUTH_TOKEN` in the environment (your one secret — see [Configuration](#configuration)).
+
+## Quickstart
+
+```ruby
+lane :beta do
+  build_app(scheme: "MyApp")
+  pharen_release
+end
+```
+
+`pharen_release` derives everything else: the IPA and dSYMs from the lane context; the
+version, build number, and bundle id from the IPA's own `Info.plist`; the commit sha
+from git. It registers the release, uploads every dSYM the archive produced, uploads the
+build, prints the OTA install link, and returns it (also available in
+`lane_context[SharedValues::PHAREN_INSTALL_URL]`).
+
+## Actions
+
+### `pharen_release`
+
+The whole integration in one call after `build_app`.
+
+| Option | Env | Default | Description |
+|---|---|---|---|
+| `ipa` | `PHAREN_IPA` | lane context (`IPA_OUTPUT_PATH`) | Path to the `.ipa`. |
+| `dsym_paths` | `PHAREN_DSYM_PATHS` | lane context (`DSYM_OUTPUT_PATH` + `DSYM_PATHS`) | dSYM bundles or `.zip`s to upload. |
+| `pharen_binary` | `PHAREN_BINARY` | `pharen` | Command that invokes the CLI (may include arguments, e.g. `node /path/to/cli.js`). |
+| `strict` | `PHAREN_STRICT` | `false` | Fail the lane on any step's error instead of warning and continuing. |
+
+Returns the install link on success, or `nil` when a step is skipped or fails outside
+strict mode.
+
+### `pharen_upload_build`
+
+Upload the IPA and get the install link back, standalone.
+
+```ruby
+pharen_upload_build            # IPA from the lane context → install link
+```
+
+| Option | Env | Default | Description |
+|---|---|---|---|
+| `ipa` | `PHAREN_IPA` | lane context (`IPA_OUTPUT_PATH`) | Path to the `.ipa`. |
+| `pharen_binary` | `PHAREN_BINARY` | `pharen` | Command that invokes the CLI. |
+| `strict` | `PHAREN_STRICT` | `false` | Fail the lane on error instead of warning and continuing. |
+
+### `pharen_upload_symbols`
+
+Upload dSYMs for crash symbolication, standalone.
+
+```ruby
+pharen_upload_symbols                                    # dSYMs from the lane context
+pharen_upload_symbols(dsym_paths: ["path/to/App.dSYM"])  # or explicit
+```
+
+| Option | Env | Default | Description |
+|---|---|---|---|
+| `dsym_paths` | `PHAREN_DSYM_PATHS` | lane context (`DSYM_OUTPUT_PATH` + `DSYM_PATHS`) | `.dSYM` bundles, dSYM `.zip`s (as produced by `gym`/`download_dsyms`), or raw DWARF binaries. |
+| `pharen_binary` | `PHAREN_BINARY` | `pharen` | Command that invokes the CLI. |
+| `strict` | `PHAREN_STRICT` | `false` | Fail the lane on error instead of warning and continuing. |
+
+## Configuration
+
+Two things live outside the lane, and only one of them is a secret:
+
+- **`.pharen.yml`** — committed at the repo root, holding `org:` and `app:`. No secrets
+  belong in it. The CLI walks up from its working directory to find it, so it resolves
+  whether fastlane runs from the repo root or the `fastlane/` directory.
+- **`PHAREN_AUTH_TOKEN`** — your one secret, read from the environment (a CI secret in
+  practice). Only the CLI reads it, and only from the environment. The plugin never
+  reads, prints, or passes the token, so it never lands in a log line or a process
+  argument list.
+
+## Failure posture
+
+The default is **warn-don't-fail**: if a step errors, the plugin logs a loud warning and
+lets the build continue. A telemetry step should never be the reason a release build
+fails.
+
+Pass `strict: true` (or set `PHAREN_STRICT=1`) in CI lanes where an unsymbolicated or
+undistributed release must be a hard stop; then any step's error fails the lane.
+
+Two things hold regardless of mode:
+
+- **Missing dSYMs always warn loudly.** A build shipped without its symbols produces
+  crashes that can never be read, and uploading symbols later does not retroactively
+  symbolicate the crashes it already caused. Archive with
+  `DEBUG_INFORMATION_FORMAT=dwarf-with-dsym` so the dSYMs exist to upload.
+- **Re-runs are safe.** The server dedupes symbols by debug id, and the CLI exits 0 when
+  every file is already uploaded — so retrying a lane never double-uploads or errors on
+  work already done.
+
+## Troubleshooting
+
+- **`pharen` not found.** The CLI isn't on `PATH`. Install it and make `pharen`
+  resolvable, or point `pharen_binary:` / `PHAREN_BINARY` at it (it may include
+  arguments, e.g. `node /path/to/cli.js`).
+- **"no IPA" or "no dSYMs in the lane context".** Run the action after `build_app`/`gym`
+  (and `download_dsyms`, if you fetch symbols from App Store Connect), or pass `ipa:` /
+  `dsym_paths:` explicitly.
+- **Release registration warns but the build still uploads.** Expected in warn mode:
+  registration records provenance, so a failed registration degrades metadata without
+  stopping distribution. Use `strict: true` if you need it to stop the lane.
+- **Not using fastlane?** The `pharen` CLI runs the same three steps directly. See the
+  documentation at <https://pharen.ai/docs>.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/fastlane/plugin/pharen/actions/pharen_release_action.rb

@@ -0,0 +1,176 @@
+# pharen_release — the whole Pharen integration in ONE bare call after build_app:
+# register the release, upload every dSYM, upload the IPA, return the install link.
+#
+#   lane :beta do
+#     build_app(scheme: "MyApp")
+#     pharen_release
+#   end
+#
+# Zero-arg: the IPA and dSYMs default from the lane context (gym/download_dsyms);
+# version / build number / bundle id are read from the IPA's own Info.plist; the
+# commit sha from git; org/app from the committed .pharen.yml; auth from
+# PHAREN_AUTH_TOKEN (env-only, never echoed). It folds Pharen's three CLI steps
+# (releases new → upload-symbols → upload-build) into one, so registering a release
+# is never a step you have to remember to run.
+#
+# SYMBOLS ARE NOT OPTIONAL: a build shipped without its dSYMs leaves every crash it
+# ever produces unsymbolicated (late upload does not retroactively fix issues). In
+# warn mode a missing-dSYM situation is a LOUD warning and the build still uploads;
+# strict mode aborts the lane.
+
+require "fastlane/action"
+require_relative "../helper/pharen_helper"
+
+module Fastlane
+  module Actions
+    module SharedValues
+      PHAREN_INSTALL_URL = :PHAREN_INSTALL_URL unless const_defined?(:PHAREN_INSTALL_URL)
+    end
+
+    class PharenReleaseAction < Action
+      def self.run(params)
+        helper = Helper::PharenHelper
+
+        # -- gather: IPA + identity (the customer passes nothing) --------------------
+        ipa = params[:ipa] || Actions.lane_context[SharedValues::IPA_OUTPUT_PATH]
+        if ipa.nil? || ipa.to_s.empty?
+          helper.fail_or_warn(params[:strict], "pharen_release: no IPA — run after build_app/gym, or pass ipa:")
+          return nil
+        end
+        ipa = File.expand_path(ipa.to_s)
+
+        begin
+          info = helper.read_ipa_info(ipa)
+        rescue Helper::PharenHelper::Failure => e
+          helper.fail_or_warn(params[:strict], "pharen_release: #{e.message}")
+          return nil
+        end
+
+        # -- step 1: register the release (idempotent server-side; commit = provenance)
+        release_args = ["releases", "new", "--platform", "ios", "--version", info[:version], "--build", info[:build]]
+        sha = helper.git_commit_sha
+        release_args += ["--commit", sha] if sha
+        release = helper.run_pharen(params[:pharen_binary], release_args)
+        unless release[:ok]
+          # Not fatal in warn mode: ingest also binds releases lazily, so a failed
+          # registration degrades provenance, not the pipeline.
+          helper.fail_or_warn(params[:strict], helper.cli_failure_message("pharen releases new", release))
+          return nil if params[:strict]
+        end
+
+        # -- step 2: symbols (every dSYM the lane produced) ---------------------------
+        dsym_inputs = params[:dsym_paths]
+        if dsym_inputs.nil? || Array(dsym_inputs).empty?
+          candidates = []
+          candidates << Actions.lane_context[SharedValues::DSYM_OUTPUT_PATH]
+          candidates.concat(Array(Actions.lane_context[SharedValues::DSYM_PATHS]))
+          dsym_inputs = candidates.compact.uniq
+        end
+        if Array(dsym_inputs).empty?
+          helper.fail_or_warn(
+            params[:strict],
+            "pharen_release: no dSYMs in the lane context — crashes from this build " \
+              "can NEVER symbolicate. Archive with DEBUG_INFORMATION_FORMAT=dwarf-with-dsym, " \
+              "or pass dsym_paths:"
+          )
+        else
+          begin
+            dsyms = helper.expand_dsym_inputs(dsym_inputs)
+            symbols = helper.run_pharen(params[:pharen_binary], ["upload-symbols", *dsyms])
+            if symbols[:ok]
+              summary = symbols[:json].is_a?(Hash) ? symbols[:json]["summary"] : nil
+              UI.success("pharen_release: symbols — #{summary || "uploaded #{dsyms.length} dSYM(s)"}")
+            else
+              helper.fail_or_warn(params[:strict], helper.cli_failure_message("pharen upload-symbols", symbols))
+            end
+          rescue Helper::PharenHelper::Failure => e
+            helper.fail_or_warn(params[:strict], "pharen_release: #{e.message}")
+          end
+        end
+
+        # -- step 3: the build itself → install link ----------------------------------
+        build_args = [
+          "upload-build",
+          "--platform", "ios",
+          "--version", info[:version],
+          "--build", info[:build],
+          "--bundle-id", info[:bundle_id],
+          ipa
+        ]
+        build = helper.run_pharen(params[:pharen_binary], build_args)
+        unless build[:ok]
+          helper.fail_or_warn(params[:strict], helper.cli_failure_message("pharen upload-build", build))
+          return nil
+        end
+
+        install_url = build[:json].is_a?(Hash) ? build[:json]["install_url"] : nil
+        Actions.lane_context[SharedValues::PHAREN_INSTALL_URL] = install_url if install_url
+        UI.success("pharen_release: #{info[:bundle_id]} #{info[:version]} (#{info[:build]}) registered + symbolicated + distributed")
+        UI.important("Install (Safari on the phone): #{install_url}") if install_url
+        install_url
+      end
+
+      #####################################################
+      # @!group Documentation
+      #####################################################
+
+      def self.description
+        "One call after build_app: register the release, upload symbols + build to Pharen, return the install link"
+      end
+
+      def self.authors
+        ["Pharen (Lucubra LLC)"]
+      end
+
+      def self.details
+        "Orchestrates the Pharen CLI's three steps (releases new → upload-symbols → " \
+          "upload-build) with everything derived: IPA + dSYMs from the lane context, " \
+          "version/build/bundle id from the IPA's Info.plist, commit sha from git, " \
+          "org/app from the committed .pharen.yml, auth from PHAREN_AUTH_TOKEN. " \
+          "Missing dSYMs warn LOUDLY (or abort under strict) — a build without " \
+          "symbols ships crashes that can never be read."
+      end
+
+      def self.available_options
+        [
+          FastlaneCore::ConfigItem.new(key: :ipa,
+                                       env_name: "PHAREN_IPA",
+                                       description: "Path to the .ipa. Defaults to what gym/build_app left in the lane context",
+                                       optional: true,
+                                       type: String),
+          FastlaneCore::ConfigItem.new(key: :dsym_paths,
+                                       env_name: "PHAREN_DSYM_PATHS",
+                                       description: "dSYM bundles/zips to upload. Defaults to gym's DSYM_OUTPUT_PATH + download_dsyms' DSYM_PATHS",
+                                       optional: true,
+                                       is_string: false),
+          FastlaneCore::ConfigItem.new(key: :pharen_binary,
+                                       env_name: "PHAREN_BINARY",
+                                       description: "Command that invokes the Pharen CLI (may include arguments, e.g. `node /path/to/cli.js`)",
+                                       optional: true,
+                                       default_value: "pharen",
+                                       type: String),
+          FastlaneCore::ConfigItem.new(key: :strict,
+                                       env_name: "PHAREN_STRICT",
+                                       description: "Fail the lane on any step's error (true) instead of warning and continuing (false)",
+                                       optional: true,
+                                       default_value: false,
+                                       is_string: false)
+        ]
+      end
+
+      def self.output
+        [
+          ["PHAREN_INSTALL_URL", "The itms-services install link answered by the Pharen control plane"]
+        ]
+      end
+
+      def self.return_value
+        "The install_url string on success; nil on skipped/failed-but-not-strict"
+      end
+
+      def self.is_supported?(platform)
+        platform == :ios
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/pharen/actions/pharen_upload_build_action.rb

@@ -0,0 +1,118 @@
+# pharen_upload_build — upload the IPA to Pharen's dl distribution and get the
+# install link back.
+#
+# Zero-arg capable: the IPA defaults from gym/build_app's SharedValues::IPA_OUTPUT_PATH,
+# and version / build number / bundle id are read out of the IPA's own Info.plist
+# (unzip + plutil — dependency-free), so the customer passes nothing. org/app come from
+# the committed .pharen.yml; auth from PHAREN_AUTH_TOKEN (env-only, never echoed).
+
+require "fastlane/action"
+require_relative "../helper/pharen_helper"
+
+module Fastlane
+  module Actions
+    module SharedValues
+      PHAREN_INSTALL_URL = :PHAREN_INSTALL_URL unless const_defined?(:PHAREN_INSTALL_URL)
+    end
+
+    class PharenUploadBuildAction < Action
+      def self.run(params)
+        helper = Helper::PharenHelper
+
+        ipa = params[:ipa] || Actions.lane_context[SharedValues::IPA_OUTPUT_PATH]
+        if ipa.nil? || ipa.to_s.empty?
+          helper.fail_or_warn(
+            params[:strict],
+            "pharen_upload_build: no IPA — run after build_app/gym, or pass ipa:"
+          )
+          return nil
+        end
+        ipa = File.expand_path(ipa.to_s)
+
+        begin
+          info = helper.read_ipa_info(ipa)
+        rescue Helper::PharenHelper::Failure => e
+          helper.fail_or_warn(params[:strict], "pharen_upload_build: #{e.message}")
+          return nil
+        end
+
+        args = [
+          "upload-build",
+          "--platform", "ios",
+          "--version", info[:version],
+          "--build", info[:build],
+          "--bundle-id", info[:bundle_id],
+          ipa
+        ]
+        result = helper.run_pharen(params[:pharen_binary], args)
+        unless result[:ok]
+          helper.fail_or_warn(params[:strict], helper.cli_failure_message("pharen upload-build", result))
+          return nil
+        end
+
+        install_url = result[:json].is_a?(Hash) ? result[:json]["install_url"] : nil
+        Actions.lane_context[SharedValues::PHAREN_INSTALL_URL] = install_url if install_url
+        UI.success("pharen_upload_build: uploaded #{info[:version]} (#{info[:build]}) #{info[:bundle_id]}")
+        UI.important("Install (Safari on the phone): #{install_url}") if install_url
+        install_url
+      end
+
+      #####################################################
+      # @!group Documentation
+      #####################################################
+
+      def self.description
+        "Upload the IPA to Pharen dl distribution and return the OTA install link (zero-arg after gym)"
+      end
+
+      def self.authors
+        ["Pharen (Lucubra LLC)"]
+      end
+
+      def self.details
+        "Thin wrapper over `pharen upload-build`: the IPA defaults from " \
+          "SharedValues::IPA_OUTPUT_PATH; version, build number and bundle id are " \
+          "extracted from the IPA's Info.plist so nothing needs passing. The server " \
+          "owns the dl layout, opaque slug and manifest.plist; the returned " \
+          "install_url is this action's return value and lands in " \
+          "lane_context[SharedValues::PHAREN_INSTALL_URL]."
+      end
+
+      def self.available_options
+        [
+          FastlaneCore::ConfigItem.new(key: :ipa,
+                                       env_name: "PHAREN_IPA",
+                                       description: "Path to the .ipa. Defaults to what gym/build_app left in the lane context",
+                                       optional: true,
+                                       type: String),
+          FastlaneCore::ConfigItem.new(key: :pharen_binary,
+                                       env_name: "PHAREN_BINARY",
+                                       description: "Command that invokes the Pharen CLI (may include arguments, e.g. `node /path/to/cli.js`)",
+                                       optional: true,
+                                       default_value: "pharen",
+                                       type: String),
+          FastlaneCore::ConfigItem.new(key: :strict,
+                                       env_name: "PHAREN_STRICT",
+                                       description: "Fail the lane on error (true) instead of warning and continuing (false)",
+                                       optional: true,
+                                       default_value: false,
+                                       is_string: false)
+        ]
+      end
+
+      def self.output
+        [
+          ["PHAREN_INSTALL_URL", "The itms-services install link answered by the Pharen control plane"]
+        ]
+      end
+
+      def self.return_value
+        "The install_url string on success; nil on skipped/failed-but-not-strict"
+      end
+
+      def self.is_supported?(platform)
+        platform == :ios
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/pharen/actions/pharen_upload_symbols_action.rb

@@ -0,0 +1,108 @@
+# pharen_upload_symbols — upload dSYMs to Pharen for crash symbolication.
+#
+# Zero-arg capable: with no options it takes the dSYMs the lane already produced —
+# gym/build_app's SharedValues::DSYM_OUTPUT_PATH and download_dsyms'
+# SharedValues::DSYM_PATHS. The CLI needs ONLY paths: debug ids are parsed from the
+# binaries, org/app come from the customer's committed .pharen.yml, auth from
+# PHAREN_AUTH_TOKEN in the environment (never echoed, never on a command line).
+
+require "fastlane/action"
+require_relative "../helper/pharen_helper"
+
+module Fastlane
+  module Actions
+    class PharenUploadSymbolsAction < Action
+      def self.run(params)
+        helper = Helper::PharenHelper
+
+        paths = params[:dsym_paths]
+        paths = default_dsym_paths if paths.nil? || Array(paths).empty?
+        if Array(paths).empty?
+          helper.fail_or_warn(
+            params[:strict],
+            "pharen_upload_symbols: no dSYMs to upload — run after build_app/gym or " \
+              "download_dsyms, or pass dsym_paths"
+          )
+          return nil
+        end
+
+        begin
+          expanded = helper.expand_dsym_inputs(paths)
+        rescue Helper::PharenHelper::Failure => e
+          helper.fail_or_warn(params[:strict], "pharen_upload_symbols: #{e.message}")
+          return nil
+        end
+
+        result = helper.run_pharen(params[:pharen_binary], ["upload-symbols"] + expanded)
+        unless result[:ok]
+          helper.fail_or_warn(params[:strict], helper.cli_failure_message("pharen upload-symbols", result))
+          return nil
+        end
+
+        summary = result[:json].is_a?(Hash) ? result[:json]["summary"] : nil
+        UI.success("pharen_upload_symbols: #{summary || 'symbols uploaded'}")
+        result[:json]
+      end
+
+      # The two places fastlane already put dSYMs, in build order: gym's zip, then any
+      # App Store Connect downloads. Duplicates collapse; the CLI dedupes by debug id
+      # anyway (re-uploads answer 'duplicate' and exit 0, so this is always re-run safe).
+      def self.default_dsym_paths
+        candidates = []
+        candidates << Actions.lane_context[SharedValues::DSYM_OUTPUT_PATH]
+        candidates.concat(Array(Actions.lane_context[SharedValues::DSYM_PATHS]))
+        candidates.compact.map(&:to_s).reject(&:empty?).uniq
+      end
+
+      #####################################################
+      # @!group Documentation
+      #####################################################
+
+      def self.description
+        "Upload dSYMs to Pharen for crash symbolication (zero-arg after gym/download_dsyms)"
+      end
+
+      def self.authors
+        ["Pharen (Lucubra LLC)"]
+      end
+
+      def self.details
+        "Thin wrapper over `pharen upload-symbols`: dSYM paths default from " \
+          "SharedValues::DSYM_OUTPUT_PATH (gym) and SharedValues::DSYM_PATHS " \
+          "(download_dsyms); .zip inputs are expanded to .dSYM bundles. Debug ids, " \
+          "org/app (.pharen.yml) and auth (PHAREN_AUTH_TOKEN) are the CLI's job. " \
+          "Server dedupes by debug id, so re-runs are safe."
+      end
+
+      def self.available_options
+        [
+          FastlaneCore::ConfigItem.new(key: :dsym_paths,
+                                       env_name: "PHAREN_DSYM_PATHS",
+                                       description: "dSYM inputs (.dSYM bundles, dSYM .zip files, or raw DWARF binaries). Defaults to what gym/download_dsyms left in the lane context",
+                                       optional: true,
+                                       type: Array),
+          FastlaneCore::ConfigItem.new(key: :pharen_binary,
+                                       env_name: "PHAREN_BINARY",
+                                       description: "Command that invokes the Pharen CLI (may include arguments, e.g. `node /path/to/cli.js`)",
+                                       optional: true,
+                                       default_value: "pharen",
+                                       type: String),
+          FastlaneCore::ConfigItem.new(key: :strict,
+                                       env_name: "PHAREN_STRICT",
+                                       description: "Fail the lane on error (true) instead of warning and continuing (false)",
+                                       optional: true,
+                                       default_value: false,
+                                       is_string: false)
+        ]
+      end
+
+      def self.return_value
+        "The CLI's parsed JSON ({ archives, summary }) on success; nil on skipped/failed-but-not-strict"
+      end
+
+      def self.is_supported?(platform)
+        platform == :ios
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/pharen/helper/pharen_helper.rb

@@ -0,0 +1,195 @@
+# PharenHelper — everything the pharen_* actions share. The plugin is a THIN wrapper:
+# all wire logic (auth, .pharen.yml, debug-id parsing, dedupe) lives in the `pharen`
+# CLI. This helper only
+#   * derives metadata the CLI needs (Info.plist out of the IPA, git commit sha),
+#   * normalizes dSYM inputs (gym/download_dsyms hand over .zip files; the CLI wants
+#     .dSYM bundles or raw DWARF binaries),
+#   * shells out to the CLI and interprets its JSON-on-stdout contract.
+#
+# Dependency-free by design: macOS system tools only (unzip, plutil, git) — every box
+# that can produce an IPA has them — so the gem adds NO runtime dependencies.
+#
+# SECURITY: PHAREN_AUTH_TOKEN is read by the CLI from the environment. This helper never
+# reads, prints, or passes the token — no command line ever contains it.
+
+require "fastlane_core/ui/ui"
+require "json"
+require "open3"
+require "shellwords"
+require "tmpdir"
+
+module Fastlane
+  UI = FastlaneCore::UI unless Fastlane.const_defined?(:UI)
+
+  module Helper
+    class PharenHelper
+      # Raised for local preparation problems (bad IPA, missing dSYM, unzip failure).
+      # Actions translate it via `fail_or_warn` — never let it escape raw.
+      class Failure < StandardError; end
+
+      # The app's own Info.plist sits exactly at Payload/<Name>.app/Info.plist.
+      # [^/]+ cannot span "/", so nested bundles (Watch apps, app extensions,
+      # frameworks) never match.
+      INFO_PLIST_ENTRY = %r{\APayload/[^/]+\.app/Info\.plist\z}
+
+      class << self
+        # -- IPA introspection ---------------------------------------------------------
+
+        # IPA -> { version:, build:, bundle_id: } (CFBundleShortVersionString,
+        # CFBundleVersion, CFBundleIdentifier), so the customer passes nothing.
+        # unzip streams the (usually binary) plist; plutil converts it to JSON on stdout.
+        def read_ipa_info(ipa_path)
+          raise Failure, "IPA not found at #{ipa_path}" unless File.exist?(ipa_path)
+
+          entry = info_plist_entry(ipa_path)
+          raw, _err, status = capture(["unzip", "-p", ipa_path, entry])
+          raise Failure, "could not read #{entry} from #{ipa_path} (unzip exit #{status})" unless status == 0
+
+          json, perr, pstatus = capture(["plutil", "-convert", "json", "-o", "-", "-"], stdin: raw)
+          raise Failure, "plutil could not parse Info.plist from #{ipa_path}: #{perr.to_s.strip}" unless pstatus == 0
+
+          plist = JSON.parse(json.force_encoding("UTF-8"))
+          info = {
+            version: plist["CFBundleShortVersionString"],
+            build: plist["CFBundleVersion"],
+            bundle_id: plist["CFBundleIdentifier"]
+          }
+          missing = info.select { |_k, v| v.nil? || v.to_s.empty? }.keys
+          unless missing.empty?
+            raise Failure, "Info.plist in #{ipa_path} is missing #{missing.join(', ')}"
+          end
+          info
+        end
+
+        # Zip entry name of the app's Info.plist (shallowest Payload/*.app only).
+        def info_plist_entry(ipa_path)
+          listing, err, status = capture(["unzip", "-Z1", ipa_path])
+          raise Failure, "could not list #{ipa_path} (unzip -Z1 exit #{status}): #{err.to_s.strip}" unless status == 0
+
+          entry = listing.split("\n").find { |line| line.match?(INFO_PLIST_ENTRY) }
+          raise Failure, "no Payload/*.app/Info.plist inside #{ipa_path} — is this an IPA?" unless entry
+          entry
+        end
+
+        # -- dSYM normalization --------------------------------------------------------
+
+        # gym's DSYM_OUTPUT_PATH and download_dsyms' DSYM_PATHS are .zip files; the CLI
+        # takes .dSYM bundles (or raw DWARF binaries). Expand zips, absolutize the rest —
+        # paths must be absolute because run_pharen may chdir for .pharen.yml resolution.
+        def expand_dsym_inputs(paths)
+          Array(paths).flat_map do |path|
+            abs = File.expand_path(path.to_s)
+            raise Failure, "dSYM path not found: #{path}" unless File.exist?(abs)
+            abs.end_with?(".zip") ? unzip_dsyms(abs) : [abs]
+          end
+        end
+
+        # Unpack a dSYM zip into a fresh temp dir and return the .dSYM bundles inside.
+        # The temp dir is left for the OS to reap — the CLI reads from it right after.
+        def unzip_dsyms(zip_path)
+          dest = Dir.mktmpdir("pharen-dsyms-")
+          _out, err, status = capture(["unzip", "-q", "-o", zip_path, "-d", dest])
+          raise Failure, "could not unzip #{zip_path}: #{err.to_s.strip}" unless status == 0
+
+          found = Dir.glob(File.join(dest, "**", "*.dSYM")).sort
+          raise Failure, "no .dSYM bundles inside #{zip_path}" if found.empty?
+          found
+        end
+
+        # -- Pharen CLI invocation -----------------------------------------------------
+
+        # Run `<binary> <args...>` and interpret the CLI's contract: JSON on stdout,
+        # exit 0 on success. `binary` is Shellwords-split so `pharen_binary` may carry a
+        # command with arguments (e.g. "node /path/to/cli.js"). Never raises on CLI
+        # failure — callers decide strict-vs-warn from the returned hash.
+        def run_pharen(binary, args, chdir: nil)
+          argv = Shellwords.split(binary.to_s) + args.map(&:to_s)
+          dir = chdir || project_dir
+          UI.command(Shellwords.join(argv)) # never contains PHAREN_AUTH_TOKEN (env-only)
+          out, err, status = capture(argv, chdir: dir)
+          json = parse_json(out)
+          { ok: status == 0, status: status, stdout: out, stderr: err, json: json }
+        rescue Errno::ENOENT => e
+          # Spawn failed: binary (or chdir target) does not exist.
+          { ok: false, status: nil, stdout: "", stderr: e.message, json: nil, not_found: true }
+        end
+
+        # One human line for a failed run_pharen result. Prefers the CLI's own
+        # { error: { code, message } } JSON; falls back to stderr, then the exit code.
+        def cli_failure_message(step, result)
+          error = result[:json].is_a?(Hash) ? result[:json]["error"] : nil
+          if error.is_a?(Hash) && error["message"]
+            "#{step} failed: #{error['message']} (#{error['code']})"
+          elsif result[:not_found]
+            "#{step} failed: #{result[:stderr]} — install the Pharen CLI and ensure `pharen` is on PATH " \
+              "(see https://pharen.ai/docs for install instructions), or set the pharen_binary option"
+          else
+            detail = result[:stderr].to_s.strip
+            detail = result[:stdout].to_s.strip if detail.empty?
+            suffix = detail.empty? ? "" : ": #{detail.split("\n").last(3).join(' / ')}"
+            "#{step} failed (exit #{result[:status]})#{suffix}"
+          end
+        end
+
+        # Where to run the CLI so it finds the customer's committed .pharen.yml.
+        # fastlane executes lanes from the fastlane/ directory (Dir.chdir in
+        # LaneManager), but .pharen.yml lives at the repo root by convention — step up
+        # one level when that is clearly the layout. Explicit --org/--app flags are the
+        # escape hatch for exotic layouts.
+        # (The CLI itself also walks up from its cwd looking for .pharen.yml, so this
+        # special-case is now a belt-and-suspenders optimization, not the only path —
+        # kept as-is since it still resolves correctly and needs no change.)
+        def project_dir
+          cwd = Dir.pwd
+          return cwd if File.exist?(File.join(cwd, ".pharen.yml"))
+          parent = File.expand_path("..", cwd)
+          if File.basename(cwd) == "fastlane" && File.exist?(File.join(parent, ".pharen.yml"))
+            parent
+          else
+            cwd
+          end
+        end
+
+        # -- misc ------------------------------------------------------------------------
+
+        # HEAD sha for `releases new --commit`; nil outside a git checkout (fine — the
+        # flag is optional provenance).
+        def git_commit_sha
+          out, _err, status = capture(%w[git rev-parse HEAD])
+          return nil unless status == 0
+          sha = out.strip
+          sha.empty? ? nil : sha
+        end
+
+        # strict: abort the lane; default: warn loudly and let the build continue —
+        # a telemetry step should never be the reason a release build fails.
+        def fail_or_warn(strict, message)
+          if strict
+            UI.user_error!(message)
+          else
+            UI.important("#{message} — continuing because strict is false")
+          end
+        end
+
+        # -- plumbing (the single shell-out seam; specs stub exactly this) ---------------
+
+        # argv -> [stdout, stderr, exitstatus]; binmode because plists are binary.
+        def capture(argv, stdin: nil, chdir: nil)
+          options = { binmode: true }
+          options[:stdin_data] = stdin unless stdin.nil?
+          options[:chdir] = chdir unless chdir.nil?
+          out, err, status = Open3.capture3(*argv, **options)
+          [out, err, status.exitstatus]
+        end
+
+        private
+
+        def parse_json(text)
+          JSON.parse(text)
+        rescue JSON::ParserError, TypeError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/pharen/version.rb

@@ -0,0 +1,5 @@
+module Fastlane
+  module Pharen
+    VERSION = "0.1.0".freeze
+  end
+end

data/lib/fastlane/plugin/pharen.rb

@@ -0,0 +1,18 @@
+# fastlane-plugin-pharen — standard fastlane plugin entry point (`fastlane add_plugin pharen`).
+# Loads every action + helper under this directory; fastlane discovers actions by class name.
+
+require "fastlane/plugin/pharen/version"
+
+module Fastlane
+  module Pharen
+    # Return all .rb files inside the "actions" and "helper" directory.
+    def self.all_classes
+      Dir[File.expand_path("**/{actions,helper}/*.rb", File.dirname(__FILE__))]
+    end
+  end
+end
+
+# By default we want to import all available actions and helpers.
+Fastlane::Pharen.all_classes.each do |current|
+  require current
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: fastlane-plugin-pharen
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Pharen (Lucubra LLC)
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fastlane
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.220.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.220.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 'Fastlane plugin for Pharen (https://pharen.ai): a thin wrapper over
+  the `pharen` CLI that adds one zero-argument action, pharen_release, after build_app
+  — it registers the release, uploads every dSYM, uploads the build, and returns the
+  OTA install link. Warn-don''t-fail by default, so a telemetry step never fails your
+  release build; `strict: true` opts a lane into hard failure where an unsymbolicated
+  release must be a stop.'
+email: hello@pharen.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/fastlane/plugin/pharen.rb
+- lib/fastlane/plugin/pharen/actions/pharen_release_action.rb
+- lib/fastlane/plugin/pharen/actions/pharen_upload_build_action.rb
+- lib/fastlane/plugin/pharen/actions/pharen_upload_symbols_action.rb
+- lib/fastlane/plugin/pharen/helper/pharen_helper.rb
+- lib/fastlane/plugin/pharen/version.rb
+homepage: https://pharen.ai
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://pharen.ai
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.11
+specification_version: 4
+summary: 'Pharen build distribution + crash symbols from your lane: pharen_release
+  / pharen_upload_build / pharen_upload_symbols'
+test_files: []