fastlane-plugin-appshot 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a15470692555262a4564076e0e13781454d5ac94f1e0a4127113f4ba163a2689
+  data.tar.gz: 96ee3e2203453bec0644b375c40223166232e35dc4241b7fa172a4b9d37090e3
+SHA512:
+  metadata.gz: f10805d5c8d3fb8ff640853f268251492740731cf72c9363f8e91c274b341995189d4c9953ae730b82912858e4f2f075bc09d2de2cdc29cdd52c2bc8699b97a5
+  data.tar.gz: 7e4fffaadfc59f6d3c9ebb2bf446b4ae3e62b7c68af7145b30e6e1dd5cc89e4409de5b7c9a7e143337dbe81a5f9ae205f23cb3a5f9410c51f5a0e086b70d3508

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to fastlane-plugin-appshot are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-10-08
+
+### Added
+
+- The `appshot` action. For every locale it copies fastlane snapshot's capture of each screen into an [appshot](https://github.com/jems19s/appshot-studio) studio (a capture named `<simulator>-<name>.png` goes to the slot whose screenshot is `<name>.png`), renders the framed, captioned screenshots with appshot, and copies them into `<output_directory>/<locale>/`, the folder deliver uploads.
+- Options `studio`, `app`, `raw_screenshots`, `device`, `locales`, `output_directory`, `appshot_path` and `chrome`, each also settable through an `APPSHOT_*` environment variable.
+- Safeguards: the action refuses to read raw captures from the folder deliver uploads, warns about other PNGs deliver would upload alongside the framed ones, asks for `device:` when captures from several simulators match, and explains how to install appshot when it is missing.
+- Requires Ruby 3.1 or later, like current fastlane.
+
+[0.1.0]: https://github.com/jems19s/fastlane-plugin-appshot/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Maksim Zhelezniakov <48087000+jems19s@users.noreply.github.com>
+
+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,81 @@
+# fastlane-plugin-appshot
+
+[![fastlane Plugin Badge](https://rawcdn.githack.com/fastlane/fastlane/master/fastlane/assets/plugin-badge.svg)](https://rubygems.org/gems/fastlane-plugin-appshot)
+
+A [_fastlane_](https://github.com/fastlane/fastlane) action that turns fastlane snapshot's raw captures into finished App Store screenshots with [appshot](https://github.com/jems19s/appshot-studio) — real device bezels, localized captions, generated backgrounds — and puts them where `deliver` uploads from.
+
+```ruby
+lane :screenshots do
+  capture_screenshots(output_directory: "fastlane/raw_screenshots")
+  appshot(raw_screenshots: "fastlane/raw_screenshots")
+  upload_to_app_store(skip_binary_upload: true, skip_metadata: true)
+end
+```
+
+For every locale the action:
+
+1. copies snapshot's capture of each screen into the appshot studio, so every language gets its own app screens;
+2. runs `appshot render`;
+3. copies the framed PNGs into `fastlane/screenshots/<locale>/`, the folder `deliver` uploads.
+
+## Setup
+
+```bash
+brew install jems19s/tap/appshot
+fastlane add_plugin appshot
+```
+
+Then, once, create the appshot studio next to your `fastlane` folder — the device, captions, colors and layout of your screenshots. Copy one locale's captures into a folder under plain names (`map.png`, `place.png`, …) and run:
+
+```bash
+mkdir appshot && cd appshot
+appshot init --name myapp --device "iPhone 17 Pro Max" --screenshots ../plain-captures \
+  --locale en-US --locale de-DE \
+  --caption 'The best cafés,\n*right around you*' --caption 'Know exactly\n*what to order*'
+```
+
+Translate the captions in `apps/myapp/captions/<locale>.json`, style it in `apps/myapp/config.json`, and commit the studio (add `devices/` and `output/` to its `.gitignore`). See the [appshot README](https://github.com/jems19s/appshot-studio#readme) for everything you can change, or let a coding agent do it with appshot's [skill](https://github.com/jems19s/appshot-studio#with-a-coding-agent).
+
+### How captures are matched
+
+fastlane snapshot saves `<simulator name>-<name>.png` in one folder per locale. A capture goes to the slot whose `screenshot` is `<name>.png`, so name your `snapshot("…")` calls after the studio's screenshots:
+
+```swift
+snapshot("map")    // fastlane/raw_screenshots/de-DE/iPhone 17 Pro Max-map.png → apps/myapp/assets/de-DE/map.png
+```
+
+If snapshot runs on several simulators, say which one appshot frames with `device: "iPhone 17 Pro Max"`. A locale with no captures keeps the screenshots already in the studio.
+
+### Keep raw captures out of deliver's folder
+
+snapshot writes to `fastlane/screenshots` by default — the folder `deliver` uploads. Point it somewhere else (`output_directory("./fastlane/raw_screenshots")` in the Snapfile, or the `capture_screenshots` option above), or `deliver` uploads raw and framed images side by side. The action refuses to read and write the same folder, and warns about any other PNGs it finds where it copies.
+
+## Options
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `studio` | `appshot` | appshot studio: the folder holding `apps/`, `templates/` and `devices/` |
+| `app` | the only app | app under `apps/` |
+| `raw_screenshots` | | snapshot's `output_directory`. Leave it out to render the screenshots already in the studio |
+| `device` | | simulator whose captures to use, when `raw_screenshots` holds several |
+| `locales` | all the app's locales | locales to import and render |
+| `output_directory` | `fastlane/screenshots` | framed PNGs go to `<output_directory>/<locale>/` |
+| `appshot_path` | `appshot` | the appshot command |
+| `chrome` | found automatically | Chrome or Chromium to render with |
+
+Every option can also come from an environment variable: `APPSHOT_STUDIO`, `APPSHOT_APP`, `APPSHOT_RAW_SCREENSHOTS`, `APPSHOT_DEVICE`, `APPSHOT_LOCALES`, `APPSHOT_OUTPUT_DIRECTORY`, `APPSHOT_PATH`, `APPSHOT_CHROME`.
+
+The action returns a hash of locale → paths of the copied screenshots.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake    # tests and rubocop
+```
+
+The tests use a stand-in for the `appshot` binary, so they run without appshot or Chrome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/fastlane/plugin/appshot/actions/appshot_action.rb

@@ -0,0 +1,143 @@
+require "fastlane/action"
+require_relative "../helper/appshot_helper"
+
+module Fastlane
+  module Actions
+    class AppshotAction < Action
+      def self.run(params)
+        studio = File.expand_path(params[:studio])
+        appshot_path = params[:appshot_path]
+        UI.message("appshot #{Helper::AppshotHelper.appshot_version(appshot_path)}")
+
+        app = Helper::AppshotHelper.app_name(studio, params[:app])
+        config = Helper::AppshotHelper.load_config(studio, app)
+        locales = Helper::AppshotHelper.selected_locales(config, params[:locales])
+        slots = config.fetch("slots")
+        output_directory = File.expand_path(params[:output_directory])
+
+        if params[:raw_screenshots]
+          raw_screenshots = File.expand_path(params[:raw_screenshots])
+          if raw_screenshots == output_directory
+            UI.user_error!("raw_screenshots and output_directory are both #{output_directory}: deliver would upload " \
+                           "the raw captures next to the framed ones. Have snapshot write somewhere else, e.g. " \
+                           "capture_screenshots(output_directory: \"fastlane/raw_screenshots\").")
+          end
+          imported_paths = Helper::AppshotHelper.import_captures(
+            raw_screenshots: raw_screenshots,
+            assets_folder: File.join(studio, "apps", app, "assets"),
+            locales: locales,
+            slots: slots,
+            device: params[:device]
+          )
+          UI.success("Imported #{imported_paths.count} captures into apps/#{app}/assets")
+        end
+
+        render_command = [appshot_path, "render", "--root", studio, "--app", app]
+        render_command += locales.flat_map { |locale| ["--locale", locale] }
+        render_command += ["--chrome", params[:chrome]] if params[:chrome]
+        Actions.sh(*render_command)
+
+        copied_paths_by_locale = Helper::AppshotHelper.copy_renders(
+          rendered_folder: File.join(studio, "output", app),
+          output_directory: output_directory,
+          locales: locales,
+          slots: slots
+        )
+        UI.success("Copied #{copied_paths_by_locale.values.sum(&:count)} screenshots into #{output_directory}")
+        copied_paths_by_locale
+      end
+
+      def self.description
+        "Frame fastlane snapshot captures with appshot and hand them to deliver"
+      end
+
+      def self.authors
+        ["Maksim Zhelezniakov"]
+      end
+
+      def self.return_value
+        "A hash of locale => paths of the framed screenshots copied into output_directory"
+      end
+
+      def self.details
+        [
+          "Takes fastlane snapshot's raw captures into an appshot studio, renders the framed, captioned App Store",
+          "screenshots for every locale with appshot (https://github.com/jems19s/appshot-studio), and copies them",
+          "into the folder fastlane deliver uploads from. Each capture named \"<simulator>-<name>.png\" goes to the",
+          "slot whose screenshot is \"<name>.png\"."
+        ].join(" ")
+      end
+
+      def self.available_options
+        [
+          FastlaneCore::ConfigItem.new(key: :studio,
+                                       env_name: "APPSHOT_STUDIO",
+                                       description: "appshot studio: the folder holding apps/, templates/ and devices/",
+                                       default_value: "appshot",
+                                       type: String,
+                                       verify_block: proc do |value|
+                                         UI.user_error!("No appshot studio at #{value}") unless File.directory?(value)
+                                       end),
+          FastlaneCore::ConfigItem.new(key: :app,
+                                       env_name: "APPSHOT_APP",
+                                       description: "App under apps/ (default: the only one there)",
+                                       optional: true,
+                                       type: String),
+          FastlaneCore::ConfigItem.new(key: :raw_screenshots,
+                                       env_name: "APPSHOT_RAW_SCREENSHOTS",
+                                       description: "fastlane snapshot's output_directory, one folder per locale. " \
+                                                    "Leave it out to render the screenshots already in the studio",
+                                       optional: true,
+                                       type: String),
+          FastlaneCore::ConfigItem.new(key: :device,
+                                       env_name: "APPSHOT_DEVICE",
+                                       description: "Simulator whose captures to use, e.g. \"iPhone 17 Pro Max\". " \
+                                                    "Needed only when raw_screenshots holds several devices",
+                                       optional: true,
+                                       type: String),
+          FastlaneCore::ConfigItem.new(key: :locales,
+                                       env_name: "APPSHOT_LOCALES",
+                                       description: "Locales to import and render (default: all the app's locales)",
+                                       optional: true,
+                                       type: Array),
+          FastlaneCore::ConfigItem.new(key: :output_directory,
+                                       env_name: "APPSHOT_OUTPUT_DIRECTORY",
+                                       description: "Where deliver picks up screenshots; framed PNGs go to " \
+                                                    "<output_directory>/<locale>/",
+                                       default_value: "fastlane/screenshots",
+                                       type: String),
+          FastlaneCore::ConfigItem.new(key: :appshot_path,
+                                       env_name: "APPSHOT_PATH",
+                                       description: "The appshot command",
+                                       default_value: "appshot",
+                                       type: String),
+          FastlaneCore::ConfigItem.new(key: :chrome,
+                                       env_name: "APPSHOT_CHROME",
+                                       description: "Chrome or Chromium to render with (default: found automatically)",
+                                       optional: true,
+                                       type: String)
+        ]
+      end
+
+      def self.example_code
+        [
+          <<~LANE
+            lane :screenshots do
+              capture_screenshots(output_directory: "fastlane/raw_screenshots")
+              appshot(raw_screenshots: "fastlane/raw_screenshots")
+              upload_to_app_store(skip_binary_upload: true, skip_metadata: true)
+            end
+          LANE
+        ]
+      end
+
+      def self.category
+        :screenshots
+      end
+
+      def self.is_supported?(platform)
+        %i[ios mac].include?(platform)
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/appshot/helper/appshot_helper.rb

@@ -0,0 +1,119 @@
+require "fastlane_core/ui/ui"
+require "fileutils"
+require "json"
+require "open3"
+
+module Fastlane
+  UI = FastlaneCore::UI unless Fastlane.const_defined?(:UI)
+
+  module Helper
+    class AppshotHelper
+      INSTALL_HINT = "Install it with `brew install jems19s/tap/appshot`, or point appshot_path at the binary.".freeze
+
+      def self.appshot_version(appshot_path)
+        version_output, status = Open3.capture2e(appshot_path, "--version")
+        unless status.success?
+          UI.user_error!("`#{appshot_path} --version` failed: #{version_output.strip}. #{INSTALL_HINT}")
+        end
+        version_output.strip
+      rescue Errno::ENOENT
+        UI.user_error!("appshot not found at '#{appshot_path}'. #{INSTALL_HINT}")
+      end
+
+      def self.app_name(studio, requested_app)
+        return requested_app if requested_app
+
+        apps_folder = File.join(studio, "apps")
+        app_names = Dir.exist?(apps_folder) ? Dir.children(apps_folder) : []
+        app_names = app_names.select { |entry| File.exist?(File.join(apps_folder, entry, "config.json")) }.sort
+        return app_names.first if app_names.count == 1
+
+        UI.user_error!("No appshot app in #{apps_folder} yet — create one with `appshot init`") if app_names.empty?
+        UI.user_error!("Several apps in #{apps_folder}: #{app_names.join(', ')} — pick one with app:")
+      end
+
+      def self.load_config(studio, app)
+        config_path = File.join(studio, "apps", app, "config.json")
+        unless File.exist?(config_path)
+          UI.user_error!("No appshot app at #{config_path} — create one with `appshot init`")
+        end
+        JSON.parse(File.read(config_path))
+      end
+
+      def self.selected_locales(config, requested_locales)
+        configured_locales = config.fetch("locales")
+        return configured_locales if requested_locales.nil? || requested_locales.empty?
+
+        unknown_locales = requested_locales - configured_locales
+        unless unknown_locales.empty?
+          UI.user_error!("#{unknown_locales.join(', ')} not in the app's locales (#{configured_locales.join(', ')})")
+        end
+        requested_locales
+      end
+
+      def self.import_captures(raw_screenshots:, assets_folder:, locales:, slots:, device:)
+        imported_paths = []
+        locales.each do |locale|
+          capture_folder = File.join(raw_screenshots, locale)
+          unless File.directory?(capture_folder)
+            UI.important("No #{capture_folder} — #{locale} keeps the screenshots already in the studio")
+            next
+          end
+          capture_files = Dir.children(capture_folder).select { |file| file.end_with?(".png") }
+          slots.each do |slot|
+            screenshot = slot.fetch("screenshot")
+            capture = capture_for(screenshot, capture_files, capture_folder, device)
+            next if capture.nil?
+
+            locale_assets_folder = File.join(assets_folder, locale)
+            FileUtils.mkdir_p(locale_assets_folder)
+            FileUtils.cp(File.join(capture_folder, capture), File.join(locale_assets_folder, screenshot))
+            imported_paths << File.join(locale_assets_folder, screenshot)
+          end
+        end
+        imported_paths
+      end
+
+      # fastlane snapshot saves "<simulator name>-<name>.png"; simulator names can contain hyphens themselves,
+      # so captures are matched by their "-<slot screenshot>" ending rather than split at the first hyphen.
+      def self.capture_for(screenshot, capture_files, capture_folder, device)
+        if device
+          capture = "#{device}-#{screenshot}"
+          return capture if capture_files.include?(capture)
+
+          UI.important("No #{capture} in #{capture_folder}")
+          return nil
+        end
+
+        matching_captures = capture_files.select { |file| file.end_with?("-#{screenshot}") }.sort
+        if matching_captures.count > 1
+          UI.user_error!("Several captures in #{capture_folder} end in -#{screenshot} " \
+                         "(#{matching_captures.join(', ')}) — set device: to the simulator name")
+        end
+        UI.important("No capture ending in -#{screenshot} in #{capture_folder}") if matching_captures.empty?
+        matching_captures.first
+      end
+
+      def self.copy_renders(rendered_folder:, output_directory:, locales:, slots:)
+        rendered_files = slots.map { |slot| "#{slot.fetch('name')}.png" }
+        locales.to_h do |locale|
+          destination_folder = File.join(output_directory, locale)
+          FileUtils.mkdir_p(destination_folder)
+          other_files = Dir.children(destination_folder).select { |file|
+            file.downcase.end_with?(".png")
+          } - rendered_files
+          unless other_files.empty?
+            UI.important("deliver uploads every PNG in #{destination_folder}, " \
+                         "so these go up too: #{other_files.sort.join(', ')}")
+          end
+          copied_paths = rendered_files.map do |file|
+            destination = File.join(destination_folder, file)
+            FileUtils.cp(File.join(rendered_folder, locale, file), destination)
+            destination
+          end
+          [locale, copied_paths]
+        end
+      end
+    end
+  end
+end

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

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

data/lib/fastlane/plugin/appshot.rb

@@ -0,0 +1,16 @@
+require "fastlane/plugin/appshot/version"
+
+module Fastlane
+  module Appshot
+    # 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
+# A plugin can contain any number of actions and plugins
+Fastlane::Appshot.all_classes.each do |current|
+  require current
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: fastlane-plugin-appshot
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Maksim Zhelezniakov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+email: 48087000+jems19s@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/fastlane/plugin/appshot.rb
+- lib/fastlane/plugin/appshot/actions/appshot_action.rb
+- lib/fastlane/plugin/appshot/helper/appshot_helper.rb
+- lib/fastlane/plugin/appshot/version.rb
+homepage: https://github.com/jems19s/fastlane-plugin-appshot
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/jems19s/fastlane-plugin-appshot
+  bug_tracker_uri: https://github.com/jems19s/fastlane-plugin-appshot/issues
+  changelog_uri: https://github.com/jems19s/fastlane-plugin-appshot/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.11
+specification_version: 4
+summary: Frame fastlane snapshot captures with appshot and hand them to deliver
+test_files: []