mysigner 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4f9aa0a3421715b8f46fdadb8325195ed5d6ef145f2ecd73df124733b7f3f9b
-  data.tar.gz: 9d53d040cbcdb39bb2387262fb989d6922f33d8ec10cb7f9709831ef07900c44
+  metadata.gz: f948f1bd3659c76f18ab35990ab196ab301f39e4de7a42598fde06b1e391a3c9
+  data.tar.gz: acb32eee7a1c8c92f353fcfdef503a5f9392aa49d61ab0a5c1e4cc8781e22855
 SHA512:
-  metadata.gz: c9dc5c8927301802a68cbd26938a1f04db2a77662529a814bfeb079236c6406271481b4856154bf81e83a4a0cad62463108636e25829a76ed5a2837b16fd8911
-  data.tar.gz: 27df131dcd35996606908032114c54b431ff651cfdeab6682a7109bcb22f9a8f6ea6074b9730918d5de1220b54b2e5e657a6f9d43de3dec3c129157002cd9b1a
+  metadata.gz: 0aa6736246d956c406051b2f3fa816c2820d0f64ed5edbde79f46e2704279661eb524e4b0e36e483a65a3114e0073228aa4a0192a3753dfdf250f98aa893dc57
+  data.tar.gz: 71ba8530c1f06736d3968ad230f62846d891a6848836a4822693dbdbb5845a39adba4b665b55ea160e96b335c1839ca8d3d0146626bdec5911f9a1a3f72fbdb4

data/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to My Signer CLI will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.2] - 2026-06-25
+
+### Fixed
+- Robustness: an undecryptable stored token no longer crashes nearly every command with a raw backtrace — it degrades to a clear "re-login" message. `config show` now works.
+- `doctor --platform android` no longer reports "All checks passed" when the JDK/Android SDK are missing (they're now reported as issues).
+- `doctor` and `validate` no longer run a tree-mutating `npx expo prebuild` from a read-only diagnostic; `validate` no longer crashes on a project with no native iOS project.
+- Android versionCode auto-increment now actually takes effect — it's injected via the Gradle init script (a bare `-PversionCode` is ignored by stock `build.gradle`), gated to the application module so library submodules don't break.
+- Expo version bumps back up `android/` and restore it on failure (no data loss).
+- `onboard --local-only` no longer crashes with `uninitialized constant StringIO`.
+- iOS-only commands (`ship testflight/appstore`, `build`, `export`, `upload`) now fail with a clear "requires macOS" message on Linux/Windows instead of a raw backtrace; `doctor` skips iOS checks on non-macOS instead of showing red Xcode issues.
+- Dropped the `-q` flag that hid Gradle output; AAB selected by newest mtime; camelCase build variants fixed; Linux/WSL JDK + Android SDK auto-detection.
+- Security: faraday 2.14.2 → 2.14.3 (CVE-2026-54297).
+
+### Changed
+- Local-only mode (no My Signer account) is now surfaced at the front door: post-install message, `onboard` (interactive mode choice), `login`, and the README Quick Start.
+- `ship` help explains Android tracks in plain words (incl. "production = PUBLIC — goes live to everyone") and what an AAB is; `--local-only` credential flags are documented.
+- `onboard` now also sets up Google Play (vault) and an Android signing keystore (local-only).
+- Connection-error guidance no longer leaks Rails/server internals to CLI users; Android build failures include a short triage block.
+
 ## [0.1.0] - 2026-01-23
 
 ### Added
@@ -97,6 +116,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.3.1] - 2026-05-29
+
+### Fixed
+- `mysigner android add PACKAGE_NAME` crashed with `NoMethodError: undefined method 'post' for nil` in local-only mode. The `android` dispatcher now gates `init` / `add` / `list` (which manage MySigner-registered records) — only `android build` is purely local. `android list`'s banner now reads "android list" instead of "apps" (it had been showing the underlying apps-command name because list is implemented as an alias).
+- `mysigner status` reported `Source: MYSIGNER_LOCAL_ONLY env var` when `MYSIGNER_LOCAL_ONLY=0` was set in the environment AND the config file had `local_only: true`. The env value "0" is falsy per the cascade's truthy parser, so the source was actually the file. Status now uses the new `Mysigner::Config.local_only_from_env?` predicate (mirroring `local_only_from_file?`) for accurate attribution.
+- README's local-only audit table classified `android init/add/build/list` as ✅ LOCAL across the board. Corrected: only `android build` is local; the other three are MySigner-only.
+
+### Added
+- `Mysigner::Config.local_only_from_env?` — public, mirrors `local_only_from_file?`. Symmetric source predicates so `mysigner status` can attribute the active source using the same truthy parser the cascade uses.
+
+---
+
 ## [0.3.0] - 2026-05-28
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mysigner (0.3.0)
+    mysigner (0.3.1)
       base64 (~> 0.2)
       faraday (~> 2.14)
       faraday-retry (~> 2.2)
@@ -32,7 +32,7 @@ GEM
       rexml
     declarative (0.0.20)
     diff-lcs (1.6.2)
-    faraday (2.14.2)
+    faraday (2.14.3)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger

data/README.md

@@ -35,9 +35,23 @@ Mobile developers spend hours dealing with:
 
 ### Prerequisites
 
+**Core (all platforms):**
 - Ruby 3.2+ (recommended: 3.4.5)
+
+**Vault mode** (default — server-orchestrated):
 - [My Signer API](https://github.com/jurgenleka/my-signer) account and API token
 
+**Local-only mode** (`--local-only` — no MySigner account or token required):
+- Your own signing credentials: Apple `.p8` key / Google Play service-account JSON / Android keystore (set up via `mysigner --local-only onboard`, flags, or env vars)
+
+**Building Android (either mode):**
+- JDK 17+ (set `JAVA_HOME`)
+- Android SDK (set `ANDROID_HOME`)
+- React Native / Expo projects: Node.js ≥ 20.19.4 and `npm install` (the native `android/` is generated by `expo prebuild`)
+
+**Building iOS (either mode):**
+- macOS with Xcode + Command Line Tools
+
 ### Install via RubyGems
 
 ```bash
@@ -57,6 +71,8 @@ bundle exec rake install
 
 ## Quick Start
 
+> **No My Signer account?** You don't need one. To sign & ship with your own Apple/Google credentials (nothing sent to a server), see the **Local-only mode** section further down and run `mysigner --local-only onboard`. The steps below are for the account-based ("vault") mode.
+
 ### 1. Get Your API Token
 
 1. Log in to your My Signer dashboard
@@ -372,9 +388,10 @@ mysigner config set local-only false    # permanent disable
 | `signing configure` | ✅ |
 | `doctor`, `status`, `validate` | ✅ (limited — no MySigner-side checks) |
 | `certificate check`, `device detect` | ✅ |
-| `android init/add/build/list` | ✅ |
+| `android build` | ✅ |
 | `config`, `config set`, `version`, `help`, `tree`, `logout` | ✅ |
 | `login`, `switch`, `orgs`, `sync` | ❌ MySigner-only |
+| `android init`, `android add`, `android list` | ❌ MySigner-only (register or list MySigner-side records) |
 | `apps`, `devices`, `certificates`, `profiles`, `bundleid`, `app-group(s)`, `merchant-id(s)`, `keystore`, `gp-credential`, `release`, `tracks`, `track`, `submit`, `device add/update`, `certificate download`, `profile download/delete` | ❌ MySigner-only |
 
 Server-only commands in local-only mode exit 2 with a one-line explanation and the override hint.

data/exe/mysigner

@@ -73,4 +73,39 @@ def rewrite_help_flag!(argv)
   ['help', first]
 end
 
-Mysigner::CLI.start(rewrite_help_flag!(hoist_leading_class_options!(ARGV)))
+# Top-level safety net for an unreadable stored credential. When
+# ~/.mysigner/config.yml holds a token that can't be decrypted (the per-machine
+# encryption key was rotated/deleted, or the config was copied from another
+# machine), Config#decrypt_token re-raises Mysigner::ConfigError. Without this
+# rescue that error — plus the underlying OpenSSL::Cipher::CipherError cause —
+# escapes as a raw Ruby backtrace on nearly every command. Convert it into one
+# actionable line and exit 1; show the trace only under DEBUG.
+begin
+  Mysigner::CLI.start(rewrite_help_flag!(hoist_leading_class_options!(ARGV)))
+rescue Mysigner::ConfigError => e
+  warn "✗ #{e.message}"
+  # Only the decrypt-failure case maps to "re-login" — other ConfigErrors
+  # (Failed to load/save/clear config) must NOT advise the user to run the very
+  # operation that just failed, so we gate the guidance on the decrypt message.
+  if e.message.include?('decrypt')
+    warn ''
+    warn 'Your saved MySigner login is unreadable (the encryption key changed, or'
+    warn '~/.mysigner was copied from another machine / is corrupt).'
+    warn "Fix: run 'mysigner logout' then 'mysigner login' to re-authenticate,"
+    warn 'or run any command with --local-only to skip MySigner entirely.'
+  end
+  if ENV['DEBUG']
+    warn ''
+    warn e.full_message(highlight: false)
+  end
+  exit 1
+rescue Errno::ENOENT => e
+  # A required external program or file wasn't found (e.g. xcodebuild on a
+  # non-Mac). Convert the raw Errno backtrace into a clear, actionable line.
+  warn "✗ A required program or file was not found: #{e.message}"
+  warn ''
+  warn 'If this was an iOS command, note that iOS builds need macOS + Xcode.'
+  warn 'On Linux or Windows you can still build Android: mysigner ship internal --platform android'
+  warn e.full_message(highlight: false) if ENV['DEBUG']
+  exit 1
+end

data/lib/mysigner/build/android_executor.rb

@@ -31,14 +31,20 @@ module Mysigner
         @key_alias = key_alias
         @key_password = key_password || keystore_password
         @version_code = version_code
+        @build_started_at = Time.now
 
         # Determine task name
-        task = "bundle#{variant.capitalize}"
+        task = "bundle#{variant_suffix(variant)}"
 
         # Build
         success = run_gradle_build(task)
 
-        raise BuildError, 'Android build failed. Check output above for errors.' unless success
+        unless success
+          raise BuildError, 'Android build failed — the details are in the Gradle output above. ' \
+                            'Common causes: signing rejected (check keystore password/alias), a ' \
+                            "missing SDK component (run 'mysigner doctor'), or a compile error in " \
+                            "your app (look for 'error:' lines). Re-run with DEBUG=1 for more."
+        end
 
         # Find output AAB
         aab_path = find_aab_output(variant)
@@ -58,14 +64,20 @@ module Mysigner
         @keystore_password = keystore_password
         @key_alias = key_alias
         @key_password = key_password || keystore_password
+        @build_started_at = Time.now
 
         # Determine task name
-        task = "assemble#{variant.capitalize}"
+        task = "assemble#{variant_suffix(variant)}"
 
         # Build
         success = run_gradle_build(task)
 
-        raise BuildError, 'Android build failed. Check output above for errors.' unless success
+        unless success
+          raise BuildError, 'Android build failed — the details are in the Gradle output above. ' \
+                            'Common causes: signing rejected (check keystore password/alias), a ' \
+                            "missing SDK component (run 'mysigner doctor'), or a compile error in " \
+                            "your app (look for 'error:' lines). Re-run with DEBUG=1 for more."
+        end
 
         # Find output APK
         apk_path = find_apk_output(variant)
@@ -93,8 +105,11 @@ module Mysigner
 
         # Phase 0: inject signing via Gradle init-script + env vars. Passwords
         # never appear in argv (no -Pandroid.injected.signing.*=PLAINTEXT).
+        # Write the Gradle init script when we need to inject EITHER signing or
+        # a versionCode override (a bare -PversionCode is ignored by stock
+        # build.gradle, so versionCode must also flow through the init script).
         injector = nil
-        if @keystore_path && File.exist?(@keystore_path)
+        if (@keystore_path && File.exist?(@keystore_path)) || @version_code
           require 'mysigner/signing/gradle_signing_injector'
           injector = Mysigner::Signing::GradleSigningInjector.new
           @signing_init_script_path = injector.write_init_script!
@@ -124,8 +139,8 @@ module Mysigner
             ENV['JAVA_HOME'] = detected
           elsif java_home && !java_home.empty?
             raise BuildError, "JAVA_HOME is set to invalid directory: #{java_home}\n" \
-                              "Run 'mysigner doctor' to fix, or set JAVA_HOME manually:\n  " \
-                              'export JAVA_HOME=$(/usr/libexec/java_home -v 17)'
+                              "Run 'mysigner doctor' to fix, or set JAVA_HOME to a valid JDK 17+ home\n  " \
+                              '(macOS: $(/usr/libexec/java_home -v 17), Linux: a dir under /usr/lib/jvm).'
           end
         end
 
@@ -147,19 +162,24 @@ module Mysigner
           ENV['ANDROID_SDK_ROOT'] = detected
         else
           raise BuildError, "Android SDK not found.\n" \
-                            "Run 'mysigner doctor' to diagnose, or set ANDROID_HOME:\n  " \
-                            'export ANDROID_HOME=~/Library/Android/sdk'
+                            "Run 'mysigner doctor' to diagnose, or set ANDROID_HOME to your SDK path\n  " \
+                            '(macOS: ~/Library/Android/sdk, Linux: ~/Android/Sdk).'
         end
       end
 
       def detect_android_home
-        # Common SDK locations
+        # Common SDK locations across macOS, Linux/WSL and Android Studio.
         candidates = [
-          File.expand_path('~/Library/Android/sdk'),
-          File.expand_path('~/Android/Sdk'),
+          ENV.fetch('ANDROID_HOME', nil),
+          ENV.fetch('ANDROID_SDK_ROOT', nil),
+          File.expand_path('~/Library/Android/sdk'),   # macOS (Android Studio)
+          File.expand_path('~/Android/Sdk'),           # Linux (Android Studio)
+          File.expand_path('~/.android/sdk'),
+          '/usr/lib/android-sdk',                      # Debian/Ubuntu package
+          '/opt/android-sdk',
           '/opt/homebrew/share/android-commandlinetools',
           '/usr/local/share/android-commandlinetools'
-        ]
+        ].compact
 
         candidates.each do |path|
           return path if Dir.exist?(path) && Dir.exist?(File.join(path, 'platform-tools'))
@@ -189,10 +209,35 @@ module Mysigner
           /usr/local/opt/openjdk/libexec/openjdk.jdk/Contents/Home
         ].each { |p| return p if Dir.exist?(p) }
 
-        # Try system Java
+        # Try system Java (macOS)
         system_paths = Dir.glob('/Library/Java/JavaVirtualMachines/*/Contents/Home')
         return system_paths.first if system_paths.any?
 
+        # Linux / WSL: resolve from the javac/java symlink, then /usr/lib/jvm.
+        detect_java_home_linux
+      end
+
+      # JAVA_HOME detection for Linux/WSL. Follows the real javac/java binary to
+      # its JDK home, then falls back to the newest /usr/lib/jvm install.
+      def detect_java_home_linux
+        %w[javac java].each do |bin|
+          path = `command -v #{bin} 2>/dev/null`.to_s.strip
+          next if path.empty?
+
+          real = begin
+            File.realpath(path)
+          rescue StandardError
+            path
+          end
+          # .../<jdk>/bin/java -> JAVA_HOME is two levels up
+          home = File.expand_path('../..', real)
+          return home if Dir.exist?(File.join(home, 'bin'))
+        end
+
+        homes = Dir.glob('/usr/lib/jvm/*/bin/java').map { |p| File.expand_path('../..', p) }
+        homes.select! { |h| Dir.exist?(h) }
+        homes.max
+      rescue StandardError
         nil
       end
 
@@ -260,6 +305,13 @@ module Mysigner
           cmd_parts << '&&' if @key_password
         end
 
+        # Export the versionCode override so the init script applies it to
+        # android.defaultConfig (a bare -PversionCode property is inert).
+        if @version_code && @signing_init_script_path
+          cmd_parts << "export MYSIGNER_VERSION_CODE=#{shell_escape(@version_code.to_s)}"
+          cmd_parts << '&&'
+        end
+
         # Change to android directory and run gradle
         cmd_parts << "cd #{shell_escape(android_dir)}"
         cmd_parts << '&&'
@@ -273,12 +325,15 @@ module Mysigner
 
         cmd_parts << task
 
-        # Add version code override if provided (no file modification needed)
+        # Belt-and-suspenders: also pass -PversionCode for any build.gradle that
+        # opts into reading it. The init-script injection above is what makes it
+        # reliable for stock projects.
         cmd_parts << "-PversionCode=#{@version_code}" if @version_code
 
-        # Standard build options
-        cmd_parts << '--no-daemon'  # Avoid daemon issues in CI
-        cmd_parts << '-q'           # Quiet mode (less noise)
+        # Standard build options. NOTE: do NOT add -q — quiet level suppresses the
+        # `> Task …` / `BUILD …` lifecycle lines that execute_with_output parses
+        # for progress, and hides the FAILURE block on errors.
+        cmd_parts << '--no-daemon' # Avoid daemon issues in CI
 
         cmd_parts.join(' ')
       end
@@ -344,12 +399,7 @@ module Mysigner
           File.join(android_dir, "build/app/outputs/bundle/#{variant}/*.aab")
         ]
 
-        patterns.each do |pattern|
-          matches = Dir.glob(pattern)
-          return matches.first if matches.any?
-        end
-
-        nil
+        newest_matching(patterns)
       end
 
       def find_apk_output(variant)
@@ -365,12 +415,34 @@ module Mysigner
           File.join(android_dir, "app/build/outputs/apk/#{variant}/app-#{variant}-unsigned.apk")
         ]
 
-        patterns.each do |pattern|
-          matches = Dir.glob(pattern)
-          return matches.first if matches.any?
-        end
+        newest_matching(patterns)
+      end
 
-        nil
+      # Pick the freshest artifact across all candidate globs. Prefer files
+      # produced by THIS build (mtime at/after build start, minus a small skew)
+      # so a leftover artifact from a previous or wrong-flavor build is never
+      # returned; fall back to the newest overall if none look fresh.
+      def newest_matching(patterns)
+        candidates = patterns.flat_map { |p| Dir.glob(p) }.uniq.select { |f| File.file?(f) }
+        return nil if candidates.empty?
+
+        fresh = if @build_started_at
+                  candidates.select { |f| File.mtime(f) >= @build_started_at - 2 }
+                else
+                  candidates
+                end
+        pool = fresh.empty? ? candidates : fresh
+        pool.max_by { |f| File.mtime(f) }
+      end
+
+      # Build the Gradle task suffix from a variant. Only the first character is
+      # upcased — String#capitalize would downcase the rest and break camelCase
+      # flavored variants (e.g. "demoRelease" -> "Demorelease").
+      def variant_suffix(variant)
+        v = variant.to_s
+        return v if v.empty?
+
+        v[0].upcase + v[1..]
       end
 
       def shell_escape(str)

data/lib/mysigner/build/android_parser.rb

@@ -63,9 +63,9 @@ module Mysigner
         # Match buildTypes block
         if @gradle_content =~ /buildTypes\s*\{(.*?)\n\s*\}/m
           block = ::Regexp.last_match(1)
-          # Find all type names (e.g., "release {" or "debug {")
+          # Find all type names (e.g., "release {" or "debug {"). Duplicates
+          # are removed by the trailing .uniq.
           block.scan(/(\w+)\s*\{/) do |match|
-            types << match[0] unless %w[debug release].include?(match[0]) && types.include?(match[0])
             types << match[0]
           end
         end

data/lib/mysigner/build/detector.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module Mysigner
   module Build
     class Detector
@@ -9,48 +11,133 @@ module Mysigner
       # Returns: { platform: :ios/:android, type: :workspace/:project/:gradle, path: String, framework: :capacitor/:react_native/:flutter/:native }
       # @param directory [String] Directory to search in
       # @param platform [Symbol, nil] Force detection for specific platform (:ios, :android, or nil for auto-detect iOS)
-      def self.detect(directory = Dir.pwd, platform: nil)
+      # @param allow_prebuild [Boolean] when false (doctor/validate and other
+      #   read-only callers), an Expo managed project with no native folder is
+      #   CLASSIFIED (framework: :expo, needs_prebuild: true) instead of having
+      #   `npx expo prebuild` run against it. Detection must never mutate the
+      #   working tree from a diagnostic path.
+      def self.detect(directory = Dir.pwd, platform: nil, allow_prebuild: true)
         # If platform is explicitly android, detect android
-        return detect_android(directory) if platform == :android
+        return detect_android(directory, allow_prebuild: allow_prebuild) if platform == :android
 
         # Default behavior: detect iOS (backwards compatible)
-        detect_ios(directory)
+        detect_ios(directory, allow_prebuild: allow_prebuild)
+      end
+
+      # ── Expo helpers ─────────────────────────────────────────────────────
+
+      # True when this looks like an Expo project: an app.json/app.config.js
+      # plus `expo` as an ACTUAL dependency in package.json. We parse the JSON
+      # rather than substring-scanning the file so an unrelated package like
+      # `eslint-config-expo`, or the word "expo" in a script, doesn't trip
+      # detection (and the destructive prebuild it gates).
+      def self.expo_managed?(directory)
+        return false unless File.exist?("#{directory}/app.json") || File.exist?("#{directory}/app.config.js")
+        return false unless File.exist?("#{directory}/package.json")
+
+        pkg = begin
+          JSON.parse(File.read("#{directory}/package.json"))
+        rescue StandardError
+          nil
+        end
+        return false unless pkg.is_a?(Hash)
+
+        deps = {}
+        deps.merge!(pkg['dependencies']) if pkg['dependencies'].is_a?(Hash)
+        deps.merge!(pkg['devDependencies']) if pkg['devDependencies'].is_a?(Hash)
+        deps.key?('expo')
+      end
+
+      # Non-mutating classification for an Expo managed project that has no
+      # native folder yet. Callers must check :needs_prebuild before trying to
+      # read gradle/xcode paths off the result.
+      def self.expo_managed_result(directory, platform)
+        {
+          platform: platform,
+          type: :expo_managed,
+          framework: :expo,
+          path: File.absolute_path(directory),
+          directory: directory,
+          needs_prebuild: true
+        }
+      end
+
+      # Materialise the native project with `npx expo prebuild`, after a
+      # precheck so the user gets an actionable message instead of expo's raw
+      # ConfigError. Raises NoProjectError on any failure. The caller's
+      # `!Dir.exist?(native/)` guard guarantees we never clobber an existing
+      # native folder.
+      def self.run_expo_prebuild!(directory, platform)
+        ensure_expo_prereqs!(directory, platform)
+
+        puts "\n📦 Expo managed workflow detected (no #{platform}/ folder)"
+        puts "🔧 Running: npx expo prebuild --platform #{platform}\n\n"
+        result = system("cd #{directory} && npx expo prebuild --platform #{platform}")
+
+        native_dir = platform == :android ? 'android' : 'ios'
+        return if result && Dir.exist?("#{directory}/#{native_dir}")
+
+        raise NoProjectError, expo_prebuild_failed_message(platform)
+      end
+
+      # Fail fast (before shelling out) for the two common prebuild blockers.
+      def self.ensure_expo_prereqs!(directory, platform)
+        unless Dir.exist?("#{directory}/node_modules/expo")
+          raise NoProjectError, expo_prebuild_failed_message(
+            platform, hint: 'The `expo` package is not installed. Run `npm install` ' \
+                            '(or yarn/pnpm install) in the project first.'
+          )
+        end
+
+        major = node_major_version
+        return unless major && major < 20
+
+        raise NoProjectError, expo_prebuild_failed_message(
+          platform, hint: "Node.js #{major}.x is too old for current Expo SDKs — " \
+                          'install Node >= 20.19.4 (e.g. via nvm, mise, or nodejs.org).'
+        )
+      end
+
+      def self.node_major_version
+        out = `node --version 2>/dev/null`.to_s.strip
+        m = out.match(/v?(\d+)\./)
+        m && m[1].to_i
+      rescue StandardError
+        nil
+      end
+
+      def self.expo_prebuild_failed_message(platform, hint: nil)
+        native = platform == :android ? 'Android' : 'iOS'
+        parts = ["Failed to generate #{native} project with expo prebuild."]
+        parts << hint if hint
+        parts << <<~ERROR.strip
+          Try running manually:
+            npx expo prebuild --platform #{platform}
+
+          Alternative: Use EAS Build (Expo's cloud service)
+          Learn more: https://docs.expo.dev/bare/overview/
+        ERROR
+        parts.join("\n\n")
       end
 
       # Detect Android project in directory
       # Returns: { platform: :android, type: :gradle, path: String, framework: :capacitor/:react_native/:flutter/:native }
-      def self.detect_android(directory = Dir.pwd)
+      def self.detect_android(directory = Dir.pwd, allow_prebuild: true)
         # 1. Check for Capacitor (most specific first)
         if File.exist?("#{directory}/capacitor.config.json") ||
            File.exist?("#{directory}/capacitor.config.ts")
           return detect_capacitor_android(directory)
         end
 
-        # 2. Check for Expo (managed workflow - no android folder)
-        if (File.exist?("#{directory}/app.json") || File.exist?("#{directory}/app.config.js")) &&
-           File.exist?("#{directory}/package.json")
-          content = File.read("#{directory}/package.json")
-          if content.include?('expo') && !Dir.exist?("#{directory}/android")
-            # Auto-run expo prebuild
-            puts "\n📦 Expo managed workflow detected (no android/ folder)"
-            puts "🔧 Running: npx expo prebuild --platform android\n\n"
-
-            result = system("cd #{directory} && npx expo prebuild --platform android")
-
-            unless result && Dir.exist?("#{directory}/android")
-              raise NoProjectError, <<~ERROR
-                Failed to generate Android project with expo prebuild.
+        # 2. Expo managed workflow (app.json/app.config.js + `expo` dependency,
+        #    no android/ yet). Read-only callers pass allow_prebuild: false and
+        #    get a non-mutating classification instead of a prebuild + possible
+        #    raise.
+        if expo_managed?(directory) && !Dir.exist?("#{directory}/android")
+          return expo_managed_result(directory, :android) unless allow_prebuild
 
-                Try running manually:
-                  npx expo prebuild --platform android
-
-                Alternative: Use EAS Build (Expo's cloud service)
-                Learn more: https://docs.expo.dev/bare/overview/
-              ERROR
-            end
-
-            puts "\n✓ Android project generated successfully\n\n"
-          end
+          run_expo_prebuild!(directory, :android)
+          puts "\n✓ Android project generated successfully\n\n"
         end
 
         # 3. Check for React Native
@@ -111,38 +198,20 @@ module Mysigner
       end
 
       # Detect iOS project in directory (original detect behavior)
-      def self.detect_ios(directory = Dir.pwd)
+      def self.detect_ios(directory = Dir.pwd, allow_prebuild: true)
         # 1. Check for Capacitor (most specific first)
         if File.exist?("#{directory}/capacitor.config.json") ||
            File.exist?("#{directory}/capacitor.config.ts")
           return detect_capacitor(directory)
         end
 
-        # 2. Check for Expo (managed workflow)
-        if (File.exist?("#{directory}/app.json") || File.exist?("#{directory}/app.config.js")) &&
-           File.exist?("#{directory}/package.json")
-          content = File.read("#{directory}/package.json")
-          if content.include?('expo') && !Dir.exist?("#{directory}/ios")
-            # Auto-run expo prebuild
-            puts "\n📦 Expo managed workflow detected (no ios/ folder)"
-            puts "🔧 Running: npx expo prebuild --platform ios\n\n"
-
-            result = system("cd #{directory} && npx expo prebuild --platform ios")
+        # 2. Expo managed workflow (see detect_android for the allow_prebuild
+        #    contract).
+        if expo_managed?(directory) && !Dir.exist?("#{directory}/ios")
+          return expo_managed_result(directory, :ios) unless allow_prebuild
 
-            unless result && Dir.exist?("#{directory}/ios")
-              raise NoProjectError, <<~ERROR
-                Failed to generate iOS project with expo prebuild.
-
-                Try running manually:
-                  npx expo prebuild --platform ios
-
-                Alternative: Use EAS Build (Expo's cloud service)
-                Learn more: https://docs.expo.dev/bare/overview/
-              ERROR
-            end
-
-            puts "\n✓ iOS project generated successfully\n\n"
-          end
+          run_expo_prebuild!(directory, :ios)
+          puts "\n✓ iOS project generated successfully\n\n"
         end
 
         # 3. Check for React Native