dev.yml

name: checkout-kit

up:
  - packages:
      - rover
      - mint
      - xcbeautify
      - jq
      - fzf
      - swiftlint
      - swiftformat
      - sccache
      - bitrise
      - ejson
      - ejson2env
  - ruby
  - xcode:
      version: "26.2"
      runtimes:
        ios:
          - version: 23C54 # 26.2
            architecture_variant: arm64
  - node:
      version: v22.14.0
      package_manager: pnpm@10.33.1
      packages:
        - protocol
        - platforms/react-native
        - platforms/web
  - custom:
      name: Check storefront secrets
      met?: ./scripts/secrets_setup --check
      meet: "true"
  - custom:
      name: Copy root env into worktree
      met?: ./scripts/copy_worktree_env --check
      meet: ./scripts/copy_worktree_env
  - custom:
      name: Install the pinned Maestro version
      met?: ./scripts/install_maestro --check
      meet: ./scripts/install_maestro
  - custom:
      name: Run Checkout Kit workspace setup
      met?: ./scripts/setup_dev_workspace --check --skip-optional-prompts
      meet: ./scripts/setup_dev_workspace --skip-optional-prompts
  - tophat_mobile
  - custom:
      name: Configure Tophat Quick Launch items
      met?: ruby scripts/tophat/configure_quick_launch
      meet: "true"
env:
  PATH:
    prepend: ./e2e/.maestro/bin

open:
  "GitHub": "https://github.com/Shopify/checkout-kit"
  "Issues": "https://github.com/Shopify/checkout-kit/issues"
  "PRs": "https://github.com/Shopify/checkout-kit/pulls"

check:
  ejson-plaintext: ./scripts/ejson_lint
  storefront-env-tests: ./scripts/test_setup_storefront_env
  ruby-script-tests: ./scripts/test_ruby
  android-detekt: platforms/android/gradlew -p platforms/android detekt
  android-lint: |
    scripts/check_storefront_env
    platforms/android/gradlew -p platforms/android lintRelease
    platforms/android/samples/CheckoutKitAndroidDemo/gradlew -p platforms/android/samples/CheckoutKitAndroidDemo :app:lintRelease
  swift-lint: cd platforms/swift && ./Scripts/lint
  react-native-lint-swift: cd platforms/react-native && ./scripts/lint_swift
  react-native-lint-module: cd platforms/react-native && pnpm module lint
  react-native-lint-sample: cd platforms/react-native && pnpm sample lint
  web-lint: cd platforms/web && pnpm lint
  web-test: cd platforms/web && pnpm test
  protocol-check: /opt/dev/bin/dev protocol check
  e2e-bitrise-validate: bitrise validate --config=e2e/bitrise.yml

commands:
  # Repo-wide
  build:
    desc: Build all supported workspaces
    run: |
      set -e
      /opt/dev/bin/dev android build
      /opt/dev/bin/dev swift build
      /opt/dev/bin/dev react-native build
      /opt/dev/bin/dev web build
      /opt/dev/bin/dev protocol build

  codegen:
    desc: "Generate UCP models. Usage: dev codegen <kotlin|swift|typescript>"
    syntax: "<kotlin|swift|typescript>"
    run: |
      case "$1" in
        kotlin|swift|typescript|ts) ./protocol/scripts/generate_models.sh --lang "$1" ;;
        *) echo "Usage: dev codegen <kotlin|swift|typescript>"; exit 1 ;;
      esac

  copy-env:
    desc: Copy the root .env into the current worktree so `dev up` can regenerate sample config
    run: ./scripts/copy_worktree_env

  secrets:
    desc: "Edit or set up encrypted storefront config. Usage: dev secrets <edit <demo|e2e>|setup>"
    aliases: [secret]
    syntax: "<edit <demo|e2e>|setup>"
    run: |
      case "${1:-}" in
        setup) shift; ./scripts/secrets_setup "$@" ;;
        *) ./scripts/secrets_edit "$@" ;;
      esac

  tophat:
    desc: "Install a PR's build to a device via Tophat. Usage: dev tophat [<pr-number-or-url>] [<target>]"
    syntax: "[<pr-number-or-url>] [<target>]"
    run: ruby scripts/tophat/dev_tophat "$@"

  format:
    desc: Auto-format and apply safe lint autocorrections across supported workspaces
    aliases: [fix]
    run: |
      set -e
      /opt/dev/bin/dev android format
      /opt/dev/bin/dev swift format
      /opt/dev/bin/dev react-native format
      /opt/dev/bin/dev web format

  lint:
    desc: Run lint checks across supported workspaces
    aliases: [style]
    run: |
      set -e
      /opt/dev/bin/dev android lint
      /opt/dev/bin/dev swift lint
      /opt/dev/bin/dev react-native lint
      /opt/dev/bin/dev web lint
      /opt/dev/bin/dev protocol lint

  test:
    desc: Run tests across all supported workspaces
    run: |
      set -e
      /opt/dev/bin/dev android test
      /opt/dev/bin/dev swift test
      /opt/dev/bin/dev react-native test
      /opt/dev/bin/dev web test
      /opt/dev/bin/dev protocol test typescript

  apollo:
    desc: "Apollo GraphQL schema and code generation commands"
    subcommands:
      download_schema:
        desc: "Download GraphQL schema. Usage: dev apollo download_schema <android|swift> [accelerated|swift|all]"
        syntax: "<android|swift> [accelerated|swift|all]"
        run: |
          case "$1" in
            android) cd platforms/android && ./scripts/apollo_download_schema ;;
            swift) shift; cd platforms/swift && ./Scripts/apollo_download_schema "$@" ;;
            *) echo "Usage: dev apollo download_schema <android|swift> [accelerated|swift|all]"; exit 1 ;;
          esac
      codegen:
        desc: "Generate Apollo models. Usage: dev apollo codegen <android|swift> [accelerated|swift|all]"
        syntax: "<android|swift> [accelerated|swift|all]"
        run: |
          case "$1" in
            android) cd platforms/android && ./scripts/apollo_codegen ;;
            swift) shift; cd platforms/swift && ./Scripts/apollo_codegen "$@" ;;
            *) echo "Usage: dev apollo codegen <android|swift> [accelerated|swift|all]"; exit 1 ;;
          esac

  # Protocol
  protocol:
    desc: "Checkout protocol commands"
    subcommands:
      build:
        desc: Build the protocol target
        run: |
          set -e
          root=$(pwd)
          cd protocol/languages/swift
          echo "Building Swift protocol..."
          swift build
          cd $root/protocol/languages/kotlin
          echo "Building Kotlin protocol..."
          ./gradlew :embedded-checkout-protocol:build
      test:
        desc: "Run protocol package tests. Usage: dev protocol test [kotlin|swift|typescript] [-- <extra args>]"
        syntax: "[kotlin|swift|typescript]"
        run: |
          set -e
          root=$(pwd)
          run_swift() {
            cd $root/protocol/languages/swift
            echo "Running tests for Swift..."
            swift test
          }
          run_kotlin() {
            echo "Running tests for Kotlin..."
            platforms/android/gradlew -p platforms/android :embedded-checkout-protocol:test
          }
          run_typescript() {
            cd $root/protocol
            echo "Running tests for TypeScript..."
            pnpm test "$@"
          }
          target="${1:-all}"
          [ $# -gt 0 ] && shift
          case "$target" in
            swift) run_swift ;;
            kotlin) run_kotlin ;;
            typescript|ts) run_typescript "$@" ;;
            all) run_kotlin; run_swift; run_typescript ;;
            *) echo "Usage: dev protocol test [kotlin|swift|typescript] [-- <extra args>]"; exit 1 ;;
          esac

      lint:
        desc: "Lint protocol TypeScript test files"
        run: |
          set -e
          root=$(pwd)
          cd $root/protocol
          pnpm lint
      check:
        desc: Build and test the protocol package
        run: |
          set -e
          /opt/dev/bin/dev protocol build
          /opt/dev/bin/dev protocol test
      check-upstream:
        desc: Compare vendored UCP snapshot files against upstream
        run: ./protocol/scripts/check_ucp_snapshot.sh "$@"
      update-upstream:
        desc: Update vendored UCP snapshot files from upstream
        run: ./protocol/scripts/update_ucp_snapshot.sh "$@"
      check-tools:
        desc: Verify protocol codegen tools match protocol/package.json
        run: ./protocol/scripts/check_codegen_tools.sh "$@"

  # Android
  android:
    aliases: ["kotlin"]
    desc: "Android Checkout Kit commands"
    subcommands:
      build:
        desc: Build the library
        run: platforms/android/gradlew -p platforms/android :lib:build
        subcommands:
          samples:
            desc: Build all sample applications
            run: platforms/android/samples/CheckoutKitAndroidDemo/gradlew -p platforms/android/samples/CheckoutKitAndroidDemo build

      start:
        desc: Build the android sample app and install it to the booted emulator
        run: platforms/android/samples/CheckoutKitAndroidDemo/gradlew -p platforms/android/samples/CheckoutKitAndroidDemo installDebug

      e2e:
        desc: Run the Android sample Maestro tests, filtered by tag
        syntax: "[--tags TAG[,TAG...]] [--exclude-tags TAG[,TAG...]]"
        run: ./e2e/scripts/run_local_e2e kotlin-android "$@"

      test:
        desc: Run all library and demo app tests
        run: |
          set -e
          scripts/check_storefront_env
          platforms/android/gradlew -p platforms/android clean test --console=plain
          platforms/android/samples/CheckoutKitAndroidDemo/gradlew -p platforms/android/samples/CheckoutKitAndroidDemo :app:testDebugUnitTest --console=plain
        subcommands:
          specific:
            desc: Run specific test class
            syntax: <TestClassName> (e.g. CheckoutBridgeTest)
            run: platforms/android/gradlew -p platforms/android :lib:testDebugUnitTest --tests "$1"
          demo:
            desc: Run demo app unit tests
            run: |
              scripts/check_storefront_env
              platforms/android/samples/CheckoutKitAndroidDemo/gradlew -p platforms/android/samples/CheckoutKitAndroidDemo :app:testDebugUnitTest --console=plain

      lint:
        desc: Check code style and lint (detekt + Android lint, including the sample)
        aliases: [style]
        run: |
          scripts/check_storefront_env
          platforms/android/gradlew -p platforms/android detekt lintRelease
          platforms/android/samples/CheckoutKitAndroidDemo/gradlew -p platforms/android/samples/CheckoutKitAndroidDemo :app:detekt :app:lintRelease

      format:
        desc: Auto-format and apply safe lint autocorrections, including the sample
        aliases: [fix]
        run: |
          scripts/check_storefront_env
          platforms/android/gradlew -p platforms/android detekt --auto-correct
          platforms/android/samples/CheckoutKitAndroidDemo/gradlew -p platforms/android/samples/CheckoutKitAndroidDemo :app:detekt --auto-correct

      check:
        desc: Run all Android checks (detekt, Android lint)
        run: |
          set -e
          /opt/dev/bin/dev android check detekt
          /opt/dev/bin/dev android check android-lint
        subcommands:
          detekt:
            desc: Run library static analysis and sample formatting checks
            run: |
              scripts/check_storefront_env
              platforms/android/gradlew -p platforms/android detekt
              platforms/android/samples/CheckoutKitAndroidDemo/gradlew -p platforms/android/samples/CheckoutKitAndroidDemo :app:detekt
          android-lint:
            desc: Run Android lint, including the sample
            run: |
              scripts/check_storefront_env
              platforms/android/gradlew -p platforms/android lintRelease
              platforms/android/samples/CheckoutKitAndroidDemo/gradlew -p platforms/android/samples/CheckoutKitAndroidDemo :app:lintRelease

      clean:
        desc: Clean Android Gradle build outputs
        run: platforms/android/gradlew -p platforms/android clean

      open:
        desc: Open the Android library or sample app in Android Studio
        long_desc: |
          Opens an Android project in Android Studio.

            dev android open          Open the demo app (default)
            dev android open demo     Open the demo app (aliases: sample, samples)
            dev android open lib      Open the Android SDK library project (aliases: library, package, module)
        syntax:
          optional: "[lib|demo]"
        run: |
          set -e
          if [ "$#" -gt 1 ]; then
            echo "Usage: dev android open [lib|demo]" >&2
            exit 1
          fi

          case "${1:-demo}" in
            demo|sample|samples) project="platforms/android/samples/CheckoutKitAndroidDemo" ;;
            lib|library|package|module) project="platforms/android" ;;
            *)
              echo "Usage: dev android open [lib|demo]" >&2
              exit 1
              ;;
          esac

          open -a "Android Studio" "$project"

      api:
        desc: Validate or update the public Android API baselines
        run: |
          echo "Usage: dev android api {check|dump}"
          echo ""
          echo "  check  Verify public APIs match the committed baselines"
          echo "  dump   Regenerate the baselines after intentional public API changes"
          exit 1
        subcommands:
          check:
            desc: Verify public APIs match the committed baselines
            run: |
              set -e
              platforms/android/gradlew -p platforms/android :lib:apiCheck
              protocol/languages/kotlin/gradlew -p protocol/languages/kotlin :embedded-checkout-protocol:apiCheck
          dump:
            desc: Regenerate the baselines after intentional public API changes
            run: |
              set -e
              platforms/android/gradlew -p platforms/android :lib:apiDump
              protocol/languages/kotlin/gradlew -p protocol/languages/kotlin :embedded-checkout-protocol:apiDump

  # Swift
  swift:
    desc: "Swift Checkout Kit commands"
    subcommands:
      build:
        desc: Build all Swift packages and sample apps
        run: |
          set -e
          cd platforms/swift
          # ShopifyCheckoutKit-Package builds every library target in
          # Package.swift in one xcodebuild invocation. The sample apps act as
          # integration compilation checks against the built libraries.
          ./Scripts/xcode_run build ShopifyCheckoutKit-Package
          ./Scripts/build_samples
        subcommands:
          packages:
            desc: Build Swift package targets
            run: cd platforms/swift && ./Scripts/xcode_run build ShopifyCheckoutKit-Package
          samples:
            desc: Build all sample applications to verify integration
            run: cd platforms/swift && ./Scripts/build_samples

      start:
        desc: Build the swift sample app for the booted simulator (preferably)
        run: |
          set -e
          cd platforms/swift
          ./Scripts/generate_xcode_projects
          # Automatically detect if a booted simulator exists, otherwise fallback to default
          BOOTED_ID=$(xcrun simctl list devices booted | grep -E 'iPhone|iPad|Air' | sed -n -E 's/.*\(([0-9A-Fa-f-]{36})\).*/\1/p' | head -n1 || true)
          if [ -n "$BOOTED_ID" ]; then
            export CURRENT_SIMULATOR_UUID="$BOOTED_ID"
            echo "Using booted simulator: $BOOTED_ID"
          else
            echo "No booted simulator found. Falling back to default simulator."
          fi
          cd Samples
          ../Scripts/xcode_run build CheckoutKitSwiftDemo

      e2e:
        desc: Run the Swift sample Maestro tests, filtered by tag
        syntax: "[--tags TAG[,TAG...]] [--exclude-tags TAG[,TAG...]]"
        run: ./e2e/scripts/run_local_e2e swift-ios "$@"

      test:
        desc: |
          `dev swift test` - Run all tests for the ShopifyCheckoutKit-Package and the sample apps.
          `dev swift test <test_class_name>` - Run only the specified package test class.
          `dev swift test sample [test_class_name]` - Run only the sample app test targets.
        syntax: "[test_class_name]"
        run: |
          set -e
          cd platforms/swift
          if [ -n "${1:-}" ]; then
            ./Scripts/xcode_run test ShopifyCheckoutKit-Package "$1"
          else
            ./Scripts/xcode_run test ShopifyCheckoutKit-Package
            ./Scripts/test_samples
          fi
        subcommands:
          sample:
            desc: Run the sample app test targets
            syntax: "[test_class_name]"
            run: cd platforms/swift && ./Scripts/test_samples "${1:-}"
      api:
        desc: Validate or update the public Swift API baseline (platforms/swift/api/*.json)
        run: |
          echo "Usage: dev swift api {check|dump}"
          echo ""
          echo "  check  Verify public Swift API matches the committed baselines"
          echo "  dump   Regenerate the Swift API baselines after intentional public API changes"
          exit 1
        subcommands:
          check:
            desc: Verify public Swift API matches the committed baselines
            run: cd platforms/swift && ./Scripts/api check
          dump:
            desc: Regenerate the Swift API baselines after intentional public API changes
            run: cd platforms/swift && ./Scripts/api dump

      lint:
        desc: Check format and lint issues using SwiftLint and SwiftFormat
        aliases: [style]
        run: cd platforms/swift && ./Scripts/lint

      format:
        desc: Auto-format and apply safe lint autocorrections
        aliases: [fix]
        run: cd platforms/swift && ./Scripts/lint fix

      check:
        desc: Run Swift lint checks
        run: /opt/dev/bin/dev swift lint

      clean:
        desc: Clean Swift packages and sample app build artifacts
        run: |
          set -e
          cd platforms/swift
          # ShopifyCheckoutKit-Package is the SPM-wide scheme: it cleans all
          # library targets in Package.swift (ShopifyCheckoutKit,
          # ShopifyAcceleratedCheckouts, EmbeddedCheckoutProtocol) in one pass.
          ./Scripts/xcode_run clean ShopifyCheckoutKit-Package
          cd Samples
          # Sample apps have a "Run Script" build phase that runs during clean
          # and exits non-zero when there is nothing to delete. Tolerate it so
          # the second sample still gets cleaned.
          ../Scripts/xcode_run clean CheckoutKitSwiftDemo || true
          ../Scripts/xcode_run clean ShopifyAcceleratedCheckoutsApp || true

      open:
        desc: Open the Swift package or sample app in Xcode
        long_desc: |
          Opens a Swift workspace in Xcode via `xed`.

            dev swift open          Open the demo app workspace (default)
            dev swift open demo     Open the demo app workspace (aliases: sample, samples)
            dev swift open lib      Open the ShopifyCheckoutKit Swift package (aliases: library, package, module)
        syntax:
          optional: "[lib|demo]"
        run: |
          set -e
          if [ "$#" -gt 1 ]; then
            echo "Usage: dev swift open [lib|demo]" >&2
            exit 1
          fi

          case "${1:-demo}" in
            demo|sample|samples)
              platforms/swift/Scripts/generate_xcode_projects
              workspace="platforms/swift/Samples/Samples.xcworkspace"
              ;;
            lib|library|package|module) workspace="platforms/swift" ;;
            *)
              echo "Usage: dev swift open [lib|demo]" >&2
              exit 1
              ;;
          esac

          xed "$workspace"

  # React Native
  react-native:
    desc: "React Native Checkout Kit commands"
    aliases: [rn]
    subcommands:
      build:
        desc: Build the @shopify/checkout-kit-react-native module
        run: cd platforms/react-native && pnpm module build

      test:
        desc: Run React Native module tests (JS + iOS + Android)
        long_desc: |
          Runs unit tests across all three React Native targets:
            - JS:      Jest tests in `platforms/react-native/modules/@shopify/checkout-kit-react-native/tests/`
            - iOS:     Xcode/CocoaPods tests in `platforms/react-native/test/rct-integration-app/`
            - Android: Gradle JVM tests for `:shopify_checkout-kit-react-native`

          All three targets resolve the published native SDKs, matching CI. To test
          against unreleased native SDK changes, run `dev rn test android --local`.
        run: |
          set -e
          cd platforms/react-native && pnpm test
          pnpm sample test:ios
          ./scripts/publish_android_snapshot
          cd sample/android && ./gradlew :shopify_checkout-kit-react-native:test --refresh-dependencies
        subcommands:
          js:
            desc: Run JS unit tests via jest
            run: cd platforms/react-native && pnpm test
          ios:
            desc: Run native iOS unit tests via the RCT integration app
            long_desc: |
              Runs the RCT integration app unit tests on a simulator.

              --local
                Test against in-repo Swift SDK sources.
            syntax:
              optional: --local
            run: cd platforms/react-native && pnpm sample test:ios "$@"
          android:
            desc: Run native Android unit tests for the RN module against the published Android SDK
            long_desc: |
              Resolves the published `com.shopify:checkout-kit` version pinned at
              `checkoutKit.nativeSdkVersions.android` in the React Native module, matching CI.

              --local
                Resolve the in-repo Android SDK from Maven Local instead. Only for
                unreleased native API that this PR changes.
            syntax:
              optional: --local
            run: |
              set -e
              cd platforms/react-native
              for arg in "$@"; do
                if [ "$arg" = "--local" ]; then
                  export USE_LOCAL_SDK=1
                fi
              done
              ./scripts/publish_android_snapshot
              cd sample/android
              ./gradlew :shopify_checkout-kit-react-native:test --refresh-dependencies
      e2e:
        desc: Run React Native sample Maestro tests, filtered by tag
        syntax: "{ios|android} [--tags TAG[,TAG...]] [--exclude-tags TAG[,TAG...]]"
        run: |
          echo "Usage: dev rn e2e {ios|android} [--tags TAG[,TAG...]] [--exclude-tags TAG[,TAG...]]" >&2
          exit 1
        subcommands:
          ios:
            desc: Run the React Native iOS Maestro tests
            syntax: "[--tags TAG[,TAG...]] [--exclude-tags TAG[,TAG...]]"
            run: ./e2e/scripts/run_local_e2e react-native-ios "$@"
          android:
            desc: Run the React Native Android Maestro tests
            syntax: "[--tags TAG[,TAG...]] [--exclude-tags TAG[,TAG...]]"
            run: ./e2e/scripts/run_local_e2e react-native-android "$@"
      lint:
        desc: Run all React Native lint checks (Swift, module, sample)
        aliases: [style]
        run: |
          set -e
          cd platforms/react-native
          ./scripts/lint_swift
          pnpm module lint
          pnpm sample lint
        subcommands:
          swift:
            desc: Lint Swift code via SwiftLint
            run: cd platforms/react-native && ./scripts/lint_swift
          module:
            desc: Lint the @shopify/checkout-kit-react-native module
            run: cd platforms/react-native && pnpm module lint
          sample:
            desc: Lint the sample app
            run: cd platforms/react-native && pnpm sample lint

      format:
        desc: Auto-format and apply safe lint autocorrections (Swift bridge only)
        aliases: [fix]
        run: cd platforms/react-native && ./scripts/lint_swift fix

      api:
        desc: Validate or update the public React Native API baseline (api/checkout-kit-react-native.api.md)
        run: |
          echo "Usage: dev rn api {check|dump}"
          echo ""
          echo "  check  Verify public RN API matches the committed report"
          echo "  dump   Regenerate the RN API report after intentional public API changes"
          exit 1
        subcommands:
          check:
            desc: Verify public RN API matches the committed report
            run: cd platforms/react-native && pnpm module api:check
          dump:
            desc: Regenerate the RN API report after intentional public API changes
            run: cd platforms/react-native && pnpm module api:dump

      snapshot:
        desc: Manage snapshots for packaged contents
        run: |
          echo "Usage: dev rn snapshot {compare|update}"
          echo ""
          echo "  compare  Compare contents to existing snapshot"
          echo "  update   Update the snapshot"
          exit 1
        subcommands:
          compare:
            desc: Compare contents to existing snapshot
            run: |
              cd platforms/react-native
              pnpm module build
              pnpm compare-snapshot
          update:
            desc: Update the snapshot
            run: |
              cd platforms/react-native
              pnpm module build
              pnpm snapshot

      check:
        desc: Run React Native lint checks
        run: /opt/dev/bin/dev react-native lint

      clean:
        desc: Remove generated directories, clean CocoaPods cache, and stop sccache
        run: |
          cd platforms/react-native
          if (cd sample/ios && bundle exec pod --version >/dev/null 2>&1); then
            (cd sample/ios && bundle exec pod cache clean --all)
          else
            echo "Skipping CocoaPods cache clean (pod unavailable; run dev up first)"
          fi
          rm -rf test/rct-integration-app/Pods \
            test/rct-integration-app/RCTIntegrationApp.xcodeproj \
            test/rct-integration-app/RCTIntegrationApp.xcworkspace \
            test/rct-integration-app/RCTIntegrationApp/Info.plist \
            test/rct-integration-app/RCTIntegrationAppTests/Info.plist \
            test/rct-integration-app/build \
            test/rct-integration-app/.xcode.env \
            test/rct-integration-app/.xcode.env.local \
            test/rct-integration-app/PrivacyInfo.xcprivacy
          pnpm module clean
          pnpm sample clean
          pnpm clean
          if command -v sccache >/dev/null 2>&1; then
            sccache --stop-server 2>/dev/null || true
          fi
          echo "Cleaned root, module and sample workspaces"

      start:
        desc: Start Metro development server
        aliases: [s, server]
        run: cd platforms/react-native && pnpm sample start --reset-cache

      ios:
        desc: Run the iOS sample app in the simulator.
        long_desc: |
          Ensures CocoaPods are in sync, then builds and runs the iOS sample app on a simulator.

          --local
            Build against in-repo Swift SDK sources. Only for unreleased native API that
            this PR adds; CI resolves published pods, so the PR stays red until release.
        syntax:
          optional: --local
        run: cd platforms/react-native && pnpm sample ios "$@"

      android:
        desc: Run the Android sample app in the emulator.
        long_desc: |
          Builds and runs the Android sample app on an emulator.

          --local
            Build against in-repo SDK sources (publishes a local Maven snapshot first).
            Only for unreleased native API that this PR adds; CI resolves published Maven
            artifacts, so the PR stays red until release.
        syntax:
          optional: --local
        run: cd platforms/react-native && pnpm sample android "$@"

      pod-install:
        desc: Install CocoaPods for the iOS sample.
        long_desc: |
          Runs pod install for the iOS sample app.

          --local
            Wire the Podfile against in-repo Swift SDK sources. Only for unreleased native
            API that this PR adds. Never commit the Podfile.lock this produces; regenerate
            it with `env -u USE_LOCAL_SDK dev rn pod-install`.
        syntax:
          optional: --local
        run: cd platforms/react-native && pnpm run pod-install -- "$@"

      open:
        desc: Open the React Native workspace root or native sample projects
        long_desc: |
          Opens platforms/react-native in the editor set by DEV_EDITOR in
          .dev.env, otherwise `open`. The --ios and --android flags open the
          sample app's native projects.

            dev rn open                 Open platforms/react-native
            dev rn open --ios           Open the sample iOS workspace in Xcode
            dev rn open --android       Open the sample Android project in Android Studio
        syntax:
          optional: "[--ios|--android]"
        run: |
          set -e
          if [ "$#" -gt 1 ]; then
            echo "Usage: dev rn open [--ios|--android]" >&2
            exit 1
          fi

          case "${1:-}" in
            "")
              if [ -f .dev.env ]; then
                . ./.dev.env
              fi
              "${DEV_EDITOR:-open}" platforms/react-native
              ;;
            --ios)
              xed platforms/react-native/sample/ios/CheckoutKitReactNativeDemo.xcworkspace
              ;;
            --android)
              open -a "Android Studio" platforms/react-native/sample/android
              ;;
            *)
              echo "Usage: dev rn open [--ios|--android]" >&2
              exit 1
              ;;
          esac

  rn:
    desc: "Alias for React Native Checkout Kit commands"
    long_desc: |
      Alias for `dev react-native ...`. Use `dev help react-native` for the
      full subcommand list.
    syntax:
      optional: "[command] [args]"
    run: /opt/dev/bin/dev react-native "$@"

  # Web
  web:
    desc: "Web Checkout Kit commands"
    subcommands:
      build:
        desc: Build the @shopify/checkout-kit package
        run: cd platforms/web && pnpm build

      test:
        desc: Run unit tests with coverage
        run: cd platforms/web && pnpm test
        subcommands:
          watch:
            desc: Run tests in watch mode
            run: cd platforms/web && pnpm test:watch

      lint:
        desc: Run typecheck, oxlint, and format checks
        aliases: [style]
        run: cd platforms/web && pnpm lint

      format:
        desc: Auto-fix JS lint and formatting issues
        aliases: [fix]
        run: |
          set -e
          cd platforms/web
          pnpm run lint:js:fix
          pnpm run format

      check:
        desc: Run Web lint, unit tests, build, package verification, and sample build checks
        run: |
          set -e
          /opt/dev/bin/dev web lint
          /opt/dev/bin/dev web test
          /opt/dev/bin/dev web build
          /opt/dev/bin/dev web verify
          /opt/dev/bin/dev web sample build

      clean:
        desc: Remove dist and coverage directories
        run: cd platforms/web && pnpm clean

      start:
        desc: Start the sample app dev server
        aliases: [s]
        run: cd platforms/web && pnpm sample

      sample:
        desc: Start the sample app dev server
        run: cd platforms/web && pnpm sample
        subcommands:
          build:
            desc: Build the sample app
            run: cd platforms/web && pnpm sample:build
          preview:
            desc: Preview the built sample app
            run: cd platforms/web && pnpm sample:preview

      verify:
        desc: Run Web package verification
        run: cd platforms/web && pnpm verify

      snapshot:
        desc: Manage snapshots for packaged contents
        run: |
          echo "Usage: dev web snapshot {compare|update}"
          echo ""
          echo "  compare  Compare contents to existing snapshot"
          echo "  update   Update the snapshot"
          exit 1
        subcommands:
          compare:
            desc: Compare contents to existing snapshot
            run: |
              cd platforms/web
              pnpm build
              pnpm compare-snapshot
          update:
            desc: Update the snapshot
            run: |
              cd platforms/web
              pnpm build
              pnpm snapshot

      open:
        desc: Open the Web package or sample app in an editor
        long_desc: |
          Opens a Web workspace in the editor set by DEV_EDITOR in .dev.env,
          otherwise `open`.

            dev web open          Open the sample app (default)
            dev web open demo     Open the sample app (aliases: sample, samples)
            dev web open lib      Open the @shopify/checkout-kit package (aliases: library, package, module)
        syntax:
          optional: "[lib|demo]"
        run: |
          set -e
          if [ "$#" -gt 1 ]; then
            echo "Usage: dev web open [lib|demo]" >&2
            exit 1
          fi

          case "${1:-demo}" in
            demo|sample|samples) workspace="platforms/web/sample" ;;
            lib|library|package|module) workspace="platforms/web" ;;
            *)
              echo "Usage: dev web open [lib|demo]" >&2
              exit 1
              ;;
          esac

          if [ -f .dev.env ]; then
            . ./.dev.env
          fi
          "${DEV_EDITOR:-open}" "$workspace"