chore: Marketplace hygiene — MFTF checkout race, zip contents, coding standard

CLAUDE.md

@@ -18,7 +18,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 # Output: pstk-paystack-magento2-module-<version>.zip
 ```
 
-`build-adobe-zip.sh` reads the version from `composer.json` and always rebuilds from scratch (removes any stale zip first). Its exclusion list is `.git*`, `.DS_Store`, `.claude/`, `dev/`, `dev-ee/`, `dev-repro/`, `marketplace/`, `vendor/`, `.env`, `auth.json`, `CLAUDE.md`, `docs/`, `graphify-out/`, `node_modules/`, `phpunit.xml`, `Test/Unit/`, the build script itself, and prior `*.zip` builds — so `CLAUDE.md`, internal QA artifacts, and tooling caches never ship to Marketplace.
+`build-adobe-zip.sh` reads the version from `composer.json` and always rebuilds from scratch (removes any stale zip first). Its exclusion list is `.git*`, `.DS_Store`, `.claude/`, `dev/`, `dev-ee/`, `dev-repro/`, `marketplace/`, `vendor/`, `.env`, `.env.sample`, `auth.json`, `CLAUDE.md`, `docs/`, `graphify-out/`, `node_modules/`, `phpunit.xml`, `Test/Unit/`, the build script itself, and prior `*.zip` builds — so `CLAUDE.md`, internal QA artifacts, and tooling caches never ship to Marketplace.
 
 > ⚠️ **Anything added to the repo root after the build script was written must be added to its exclusion list explicitly.** This has already gone wrong once: `dev-ee/` was created after the script and had to be retro-fitted before a release could ship without bundling the entire EE harness. When you add a new top-level directory that is not package content, add its `-x` line **in the same commit**.
 

Model/WebhookOrderResolver.php

@@ -74,6 +74,14 @@ class WebhookOrderResolver
     /** @var LoggerInterface */
     private $logger;
 
+    /**
+     * @param OrderRepositoryInterface $orderRepository
+     * @param SearchCriteriaBuilder $searchCriteriaBuilder
+     * @param TransactionRepositoryInterface $transactionRepository
+     * @param OrderInterface $orderInterface
+     * @param TransactionValidator $transactionValidator
+     * @param LoggerInterface $logger
+     */
     public function __construct(
         OrderRepositoryInterface $orderRepository,
         SearchCriteriaBuilder $searchCriteriaBuilder,
@@ -138,10 +146,13 @@ public function resolve(string $reference, object $transactionDetails): ?OrderIn
             if (1 === count($matches) && $this->transactionValidator->isPaystackOrder($matches[0])) {
                 return $matches[0];
             }
-            $this->logger->info('Paystack Webhook: metadata orderId did not match a Paystack order on the quote, using quote lookup', [
-                'reference' => $reference,
-                'candidates' => count($matches),
-            ]);
+            $this->logger->info(
+                'Paystack Webhook: metadata orderId did not match a Paystack order on the quote, using quote lookup',
+                [
+                    'reference' => $reference,
+                    'candidates' => count($matches),
+                ]
+            );
         } else {
             $this->logger->info('Paystack Webhook: no metadata.orderId, using quote lookup', [
                 'reference' => $reference,
@@ -195,6 +206,8 @@ function (OrderInterface $candidate): array {
     }
 
     /**
+     * The order with this entity id, or null when there is none.
+     *
      * @param mixed $orderId
      * @return OrderInterface|null
      */
@@ -204,7 +217,9 @@ private function findOrder($orderId): ?OrderInterface
     }
 
     /**
-     * @param array<string, mixed> $filters field => value, all matched with 'eq'
+     * Orders matching every filter (field => value, each compared with 'eq').
+     *
+     * @param array $filters
      * @return OrderInterface[]
      */
     private function findOrders(array $filters): array

Test/Mftf/Test/StorefrontPaystackCheckoutRendersTest.xml

@@ -57,11 +57,13 @@
         <fillField selector="input[name='postcode']" userInput="90001" stepKey="fillPostcode"/>
         <fillField selector="input[name='telephone']" userInput="08000000000" stepKey="fillPhone"/>
 
-        <!-- 4. Select the first shipping method and continue to the payment step. -->
+        <!-- 4. Select Flat Rate and continue to the payment step. Filling the address
+             re-estimates shipping behind a loading mask and re-renders the method list,
+             so a raw click races it; the core action groups wait for both. -->
         <waitForElementVisible selector=".table-checkout-shipping-method input[type='radio']" time="60" stepKey="waitForShippingMethod"/>
-        <click selector=".table-checkout-shipping-method input[type='radio']" stepKey="selectShippingMethod"/>
-        <waitForElementVisible selector="button[data-role='opc-continue']" time="30" stepKey="waitForNext"/>
-        <click selector="button[data-role='opc-continue']" stepKey="goToPayment"/>
+        <waitForLoadingMaskToDisappear stepKey="waitForShippingEstimate"/>
+        <actionGroup ref="CheckoutSelectFlatRateShippingMethodActionGroup" stepKey="selectShippingMethod"/>
+        <actionGroup ref="StorefrontCheckoutClickNextButtonActionGroup" stepKey="goToPayment"/>
 
         <!-- 5. Payment step must render and offer the Paystack method (no infinite loader). -->
         <waitForElementVisible selector=".checkout-payment-method" time="60" stepKey="assertPaymentStepRendered"/>

build-adobe-zip.sh

@@ -37,6 +37,7 @@ zip -r "$ZIP" . \
   -x "dev-repro/*" \
   -x "vendor/*" \
   -x ".env" \
+  -x ".env.sample" \
   -x "auth.json" \
   -x "CLAUDE.md" \
   -x "docs/*" \