fastlane-plugin-store_screenshot_check 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 39b9ce01745b8ea131d9492c960d34c66e4aff76fb7b74fa82b2b466bc273c54
+  data.tar.gz: 8e45cba9c4706d5b90f0d1409706b25d71cc25544999375727e494ef692dec1c
+SHA512:
+  metadata.gz: 4850003b14ce13a0a91b346e9b8919f8e2a990993905d6acf126fc94608ed865967f3a3af40216158a6bc0f09e36f14920c9978963b8f28b5a0a1a762713dd10
+  data.tar.gz: c06003e8400e5604476c78183e5560a6fd00ce93090cea1d2112d542891ec53d8c9ebc0a8a389d8aa22286b49961e7f80241b84ef0dc86bae6faa3a1b2fa830b

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Grüner
+
+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,120 @@
+# Store Screenshot Check for Fastlane
+
+Check a screenshot folder before a lane uploads it to App Store Connect or Google
+Play. The `store_screenshot_check` action checks image data, dimensions,
+transparency and set counts using `@grunersoftware/store-screenshot-specs` 0.1.0.
+It returns a report and, by default, stops the lane when a file or set fails.
+
+Version 0.1.0 is available from its public GitHub release. Until the RubyGem is
+published, add the tagged repository to your project's `fastlane/Pluginfile`:
+
+```ruby
+gem 'fastlane-plugin-store_screenshot_check',
+    git: 'https://github.com/MartinGryner/fastlane-plugin-store_screenshot_check.git',
+    tag: 'v0.1.0'
+```
+
+Run `bundle install` in your project. The lane host needs Node.js 22 or newer,
+Ruby 3.1 or newer, and Fastlane 2.220 or newer (2.x). The gem includes its
+JavaScript validator and dependencies; no npm install is needed to run it.
+
+## Use before upload
+
+```ruby
+lane :check_screenshots do
+  root = File.expand_path('..', __dir__) # Fastfile is in the fastlane directory
+  report = store_screenshot_check(
+    workspace: root,
+    directory: 'screenshots/en-US/iphone',
+    target: 'apple-iphone-69'
+  )
+  UI.message("Checked #{report['files']} screenshots")
+  # Put your existing upload action after this check.
+end
+```
+
+For a Google Play phone set, use `target: 'google-phone'`. Call the action once
+for each locale/device directory; it does not recursively classify an entire
+Fastlane screenshot tree. Each directory should contain screenshot files only.
+
+| Parameter | Meaning |
+| --- | --- |
+| `directory` | Required. One screenshot directory inside `workspace`. |
+| `target` | Required. Exact target ID from the supported list below. |
+| `workspace` | Root used to resolve and constrain the screenshot path. Defaults to the process working directory. Prefer an explicit absolute path. |
+| `node` | Node.js executable name or path. Defaults to `node`. |
+| `fail_on_error` | Default `true`. Use `false` to return invalid-file/set findings without stopping the lane. |
+| `fail_on_review` | Default `false`. Use `true` to also stop for manual-review warnings. |
+
+Invalid configuration, missing Node.js, unsupported targets, empty directories,
+and directories outside the workspace always stop the lane, even when
+`fail_on_error` is false. A failed lane exits unsuccessfully unless your Fastfile
+explicitly catches the exception. No upload action is called by this plugin.
+
+The returned Hash has string keys: `target`, `specsVersion`, `files`, `failures`,
+`reviews`, `passes`, `results`, `errors` and `countCheck`. `results` contains image
+metadata and checks with `tone`, `label`, and `detail`; `errors` contains files
+that could not be inspected. `failures` counts failed files plus a failed set-count
+check. `reviews` counts files needing review plus a set-count warning. The report
+contains filenames and metadata, not image pixels.
+
+## Supported targets and limits
+
+| Target IDs | Checks |
+| --- | --- |
+| `apple-iphone-duo`, `apple-iphone-69`, `apple-iphone-65`, `apple-iphone-63`, `apple-iphone-61`, `apple-iphone-55`, `apple-iphone-47`, `apple-iphone-4`, `apple-iphone-35` | Exact supported sizes, PNG/JPEG, transparency, 1–10 screenshots. |
+| `apple-ipad-13`, `apple-ipad-129`, `apple-ipad-11`, `apple-ipad-105`, `apple-ipad-97`, `apple-mac` | Exact supported sizes, PNG/JPEG, transparency, 1–10 screenshots. |
+| `google-phone` | JPEG or 24-bit PNG without alpha, edges 320–3840px, long edge at most twice the short edge, at most 8 screenshots. |
+
+Google requires two screenshots across device types, so a phone set with only one
+image receives a review warning. Promotional dimension guidance also produces
+warnings; passing those checks does not establish promotional eligibility.
+Apple/Google file-size limits are not asserted. Only the target IDs in the table
+are supported. Google tablet/TV/watch sets and Microsoft Store are unsupported
+by this first plugin release.
+
+PNG and JPEG files are decoded; a renamed extension or a plausible header is not
+enough. PNG checks include CRCs, alpha/transparency markers, bit depth and color
+type. Hidden files and subdirectories are ignored. Other visible entries count
+toward the set; symlinks, special files, unsupported data and corrupt images fail.
+The decoder limits are 64 MiB per file, 24 megapixels per decoded image and 100
+visible non-directory entries per folder. These are validator limits, not store
+requirements.
+
+This checks one image set, not screenshot content, text overflow, required
+languages, complete device coverage, account eligibility, or store approval.
+Current store references:
+[Apple](https://developer.apple.com/help/app-store-connect/reference/app-information/screenshot-specifications/)
+and [Google Play](https://support.google.com/googleplay/android-developer/answer/9866151?hl=en).
+
+## Privacy and screenshot creation
+
+The validator processes files on the machine running the lane, makes no network
+requests, uploads no screenshots, and sends no data to an AI model. On CI, that
+machine is the CI runner; filenames and findings appear in its logs. Your other
+Fastlane actions and CI provider have their own data handling.
+
+[Screen Studio Kit](https://martingruner.com/projects/screenshot-studio) is an
+optional app for creating screenshot sets. It is not required to run this check.
+You can also use the [browser validator](https://martingruner.com/tools/store-screenshot-validator).
+
+## Build and test in this workspace
+
+The runtime bundle imports the existing validator from
+`../validate-store-screenshots/src/validate.mjs` and the shared specification
+package. There is no independently maintained rule table in this plugin.
+
+```sh
+npm --prefix ../store-screenshot-specs run build
+npm --prefix ../validate-store-screenshots ci
+node scripts/build.mjs
+node --test test/validator.test.mjs
+ruby test/action_test.rb
+gem build fastlane-plugin-store_screenshot_check.gemspec
+```
+
+The Ruby integration test requires Fastlane to be installed. Rebuild the bundle
+whenever the shared validator or specifications change. Keep `LICENSE` and
+`THIRD_PARTY_LICENSES.txt` with the bundle. The public standalone repository
+includes the shared build inputs and pinned dependency manifests needed to rebuild
+the helper. Repeat these checks before each tagged release.

data/THIRD_PARTY_LICENSES.txt

@@ -0,0 +1,49 @@
+pngjs
+pngjs original work Copyright (c) 2015 Luke Page & Original Contributors
+pngjs derived work Copyright (c) 2012 Kuba Niegowski
+
+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.
+
+
+jpeg-js
+Copyright (c) 2014, Eugene Ware
+All rights reserved.
+  
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:  
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.  
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.  
+3. Neither the name of Eugene Ware nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.  
+  
+THIS SOFTWARE IS PROVIDED BY EUGENE WARE ''AS IS'' AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL EUGENE WARE BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/lib/fastlane/plugin/store_screenshot_check/actions/store_screenshot_check_action.rb

@@ -0,0 +1,74 @@
+require 'fastlane/action'
+require 'json'
+require 'open3'
+
+module Fastlane
+  module Actions
+    class StoreScreenshotCheckAction < Action
+      def self.run(params)
+        helper = File.expand_path('../helper/validate.cjs', __dir__)
+        request = {
+          directory: params[:directory], target: params[:target],
+          workspace: File.expand_path(params[:workspace]),
+          fail_on_error: params[:fail_on_error], fail_on_review: params[:fail_on_review]
+        }
+        # Separate arguments avoid interpreting directory names or executable paths as shell code.
+        stdout, stderr, status = Open3.capture3(
+          [params[:node], params[:node]], helper, stdin_data: JSON.generate(request)
+        )
+        begin
+          report = JSON.parse(stdout)
+        rescue JSON::ParserError
+          UI.user_error!("Screenshot validator did not return JSON. #{stderr.strip}")
+        end
+        UI.user_error!(report['error'] || "Screenshot validator failed: #{stderr.strip}") unless [0, 1].include?(status.exitstatus)
+        UI.message("Screenshot check: #{report['files']} files, #{report['failures']} failures, #{report['reviews']} review warnings (#{report['target']})")
+        report.fetch('errors', []).each { |error| UI.error("#{error['name']}: #{error['message']}") }
+        report.fetch('results', []).each do |result|
+          result.fetch('checks').each do |check|
+            next if check['tone'] == 'pass'
+            message = "#{result['name']}: #{check['label']}: #{check['detail']}"
+            check['tone'] == 'fail' ? UI.error(message) : UI.important(message)
+          end
+        end
+        count = report.fetch('countCheck')
+        UI.important(count['detail']) unless count['tone'] == 'pass'
+        UI.user_error!('Screenshot validation failed. See the file and set diagnostics above.') unless status.success?
+        report
+      rescue Errno::ENOENT => error
+        UI.user_error!("Unable to start screenshot validator. Install Node.js 22 or newer and set node to its executable if needed. #{error.message}")
+      end
+
+      def self.description
+        'Validate one Apple or Google Play phone screenshot folder before upload'
+      end
+
+      def self.details
+        'Uses bundled shared store-screenshot-specs rules and PNG/JPEG decoders. Requires Node.js 22+. Runs locally on the lane host. Does not upload files or guarantee store approval.'
+      end
+
+      def self.authors
+        ['Martin Grüner']
+      end
+
+      def self.return_value
+        'Hash with target, files, failures, reviews, passes, results, errors, countCheck and specsVersion (string keys)'
+      end
+
+      def self.available_options
+        [
+          FastlaneCore::ConfigItem.new(key: :directory, env_name: 'STORE_SCREENSHOT_CHECK_DIRECTORY', description: 'One non-recursive screenshot directory inside workspace', type: String),
+          FastlaneCore::ConfigItem.new(key: :target, env_name: 'STORE_SCREENSHOT_CHECK_TARGET', description: 'Supported apple-* target ID or google-phone; see README', type: String),
+          FastlaneCore::ConfigItem.new(key: :workspace, env_name: 'STORE_SCREENSHOT_CHECK_WORKSPACE', description: 'Root that screenshot directory must be inside', type: String, optional: true, default_value: Dir.pwd),
+          FastlaneCore::ConfigItem.new(key: :node, env_name: 'STORE_SCREENSHOT_CHECK_NODE', description: 'Node.js 22+ executable name or path', type: String, optional: true, default_value: 'node'),
+          FastlaneCore::ConfigItem.new(key: :fail_on_error, env_name: 'STORE_SCREENSHOT_CHECK_FAIL_ON_ERROR', description: 'Stop the lane for invalid screenshot files or set counts', type: Boolean, optional: true, default_value: true),
+          FastlaneCore::ConfigItem.new(key: :fail_on_review, env_name: 'STORE_SCREENSHOT_CHECK_FAIL_ON_REVIEW', description: 'Also stop the lane for manual-review warnings', type: Boolean, optional: true, default_value: false)
+        ]
+      end
+
+      def self.is_supported?(platform)
+        [:ios, :mac, :android].include?(platform)
+      end
+    end
+  end
+end