chore(ci): harden CI + roadmap for fearless-utils hygiene

.githooks/prepare-commit-msg

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+MSG_FILE="$1"
+# If commit is a merge or has a message already, still ensure signoff trailer exists.
+# Append Signed-off-by if missing.
+if ! grep -qi '^Signed-off-by:' "$MSG_FILE"; then
+  NAME_EMAIL="$(git config user.name) <$(git config user.email)>"
+  printf '\nSigned-off-by: %s\n' "$NAME_EMAIL" >> "$MSG_FILE"
+fi

.github/workflows/codecov.yml

@@ -10,12 +10,109 @@ jobs:
     runs-on: macOS-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v1
+        uses: actions/checkout@v4
+
+      - name: Configure GitHub auth for private pods (optional)
+        env:
+          GH_READ_TOKEN: ${{ secrets.GH_READ_TOKEN }}
+        run: |
+          if [ -n "$GH_READ_TOKEN" ]; then
+            echo "Using GH_READ_TOKEN for authenticated access to soramitsu/*"
+            git config --global url."https://${GH_READ_TOKEN}:x-oauth-basic@github.com/soramitsu/".insteadOf "https://github.com/soramitsu/"
+          else
+            echo "GH_READ_TOKEN not set; proceeding without GitHub auth"
+          fi
 
-      - name: Install Dependencies & Test
+      - name: Bootstrap Dependencies
+        run: |
+          bash scripts/ci/bootstrap.sh
+
+      - name: Build & Test (Simulator)
         run: |
-          pod install --repo-update
-          set -o pipefail && xcodebuild test -workspace fearless.xcworkspace -scheme fearless -destination 'platform=iOS Simulator,name=iPhone 14,OS=16.2' build test | xcpretty --test
+          set -o pipefail
+          # Resolve SPM into a stable workspace path and patch after resolve
+          SP_DIR="$PWD/SourcePackages"
+          mkdir -p "$SP_DIR"
+          xcodebuild -resolvePackageDependencies \
+            -workspace fearless.xcworkspace \
+            -scheme fearless \
+            -clonedSourcePackagesDirPath "$SP_DIR"
+          # Apply patches on the resolved checkout (fail fast if contracts cannot be restored)
+          SOURCE_PACKAGES_DIR="$SP_DIR" ALLOW_DERIVEDDATA_FALLBACK=0 STRICT_REQUIRED_PATCHES=1 bash scripts/spm-shared-features-fixes.sh "$(pwd)"
+          # Ensure native crypto checkout/modulemap contract is restored after resolve.
+          SOURCE_PACKAGES_DIR="$SP_DIR" STRICT_REQUIRED_PATCHES=1 bash scripts/deps/prepare-native-crypto-checkout.sh "$(pwd)" fearless.xcworkspace fearless.tests
+          echo "Preflight: checking remaining 'enum AddressFactory' in $SP_DIR checkouts (warn-only)"
+          if command -v rg >/dev/null 2>&1; then
+            rg -n "\\benum\\s+AddressFactory\\b" "$SP_DIR/checkouts/shared-features-spm/Sources" -S | sed -n '1,120p' || true
+          else
+            /usr/bin/grep -RInE "(^|[^A-Za-z0-9_])enum[[:space:]]+AddressFactory(\b|[^.])" "$SP_DIR/checkouts/shared-features-spm/Sources" | sed -n '1,120p' || true
+          fi
+          echo "Preflight: checking SSFPolkaswap addressFactory type annotations"
+          if command -v rg >/dev/null 2>&1; then
+            if rg -n "addressFactory\s*:\s*([A-Za-z_]+\.)?AddressFactory(\b|[^.])" "$SP_DIR/checkouts/shared-features-spm/Sources/SSFPolkaswap" -S >/dev/null 2>&1; then
+              echo "WARNING: addressFactory annotations still using AddressFactory (not .Type):" >&2
+              rg -n "addressFactory\s*:\s*([A-Za-z_]+\.)?AddressFactory(\b|[^.])" "$SP_DIR/checkouts/shared-features-spm/Sources/SSFPolkaswap" -S | sed -n '1,120p' >&2 || true
+            fi
+          else
+            if /usr/bin/grep -RInE "addressFactory\s*:\s*([A-Za-z_]+\.)?AddressFactory(\b|[^.])" "$SP_DIR/checkouts/shared-features-spm/Sources/SSFPolkaswap" >/dev/null 2>&1; then
+              echo "WARNING: addressFactory annotations still using AddressFactory (not .Type) [grep]:" >&2
+              /usr/bin/grep -RInE "addressFactory\s*:\s*([A-Za-z_]+\.)?AddressFactory(\b|[^.])" "$SP_DIR/checkouts/shared-features-spm/Sources/SSFPolkaswap" | sed -n '1,120p' >&2 || true
+            fi
+          fi
+          echo "Available simulators (before selection):" && xcrun simctl list devices | sed -n '1,100p'
+          UDID_RAW="$(LOG_PREFIX='[codecov]' PREFERRED_NAME='iPhone 16' ALLOW_CREATE=1 BOOT_SIMULATOR=0 bash scripts/ci/select-simulator.sh)"
+          UDID="$(printf '%s\n' "$UDID_RAW" | awk 'match($0, /[A-Fa-f0-9-]{36}/) { print substr($0, RSTART, RLENGTH); exit }')"
+          if [ -z "$UDID" ]; then
+            echo "Failed to select simulator UDID. Raw selector output: $UDID_RAW" >&2
+            exit 1
+          fi
+          if ! [[ "$UDID" =~ ^[A-Fa-f0-9-]{36}$ ]]; then
+            echo "Extracted simulator UDID has invalid format: $UDID" >&2
+            exit 1
+          fi
+          HOST_ARCH="$(uname -m)"
+          SIM_INFO="$(xcrun simctl list devices available | awk -v udid="$UDID" '
+            /^-- iOS / { os=$3; next }
+            {
+              if (index($0, udid) > 0) {
+                line = $0
+                sub(/[[:space:]]*\([A-Fa-f0-9-]{36}\).*/, "", line)
+                gsub(/^[[:space:]]+|[[:space:]]+$/, "", line)
+                print line "|" os
+                exit
+              }
+            }
+          ')"
+          if [ -n "$SIM_INFO" ]; then
+            SIM_NAME="${SIM_INFO%%|*}"
+            SIM_OS="${SIM_INFO##*|}"
+            DESTINATION="platform=iOS Simulator,OS=${SIM_OS},name=${SIM_NAME}"
+          else
+            DESTINATION="platform=iOS Simulator,id=$UDID"
+          fi
+          case "$HOST_ARCH" in
+            arm64|x86_64)
+              DESTINATION="${DESTINATION},arch=${HOST_ARCH}"
+              ;;
+          esac
+          echo "Using destination: $DESTINATION"
+          LOG_FILE="$PWD/build/codecov-xcodebuild.log"
+          mkdir -p "$PWD/build"
+          if ! xcodebuild \
+            -workspace fearless.xcworkspace \
+            -scheme fearless.tests \
+            -clonedSourcePackagesDirPath "$SP_DIR" \
+            -disableAutomaticPackageResolution \
+            -destination "$DESTINATION" \
+            build test | tee "$LOG_FILE" | xcpretty --test; then
+            echo "Build/Test failed. Key errors from $LOG_FILE:" >&2
+            if command -v rg >/dev/null 2>&1; then
+              rg -n " error: |\\*\\* (BUILD|TEST) FAILED \\*\\*" "$LOG_FILE" -S | tail -n 100 >&2 || true
+            else
+              grep -nE " error: |\\*\\* (BUILD|TEST) FAILED \\*\\*" "$LOG_FILE" | tail -n 100 >&2 || true
+            fi
+            exit 1
+          fi
 
       - name: Upload coverage to Codecov
         run: bash <(curl -s https://codecov.io/bash) -J 'fearless'

.gitignore

@@ -56,6 +56,16 @@ Tests/Mocks/CommonMocks.swift
 Tests/Mocks/ModuleMocks.swift
 #
 # Generamba
-Templates/
+/Templates/
 # Misc
 **/.DS_Store
+
+# Swift Package Manager
+SourcePackages/
+.swiftpm/
+.build/
+
+# Ignore project-level SPM resolved file; use workspace-level only
+fearless.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved
+# Private pod/env helper
+.env.private

AGENTS.md

@@ -0,0 +1,177 @@
+# Repository Guidelines
+
+<!-- wallet-context:start -->
+> About this codebase  
+> This repository contains the codebase for a cryptocurrency wallet compatible with the Polkadot ecosystem (and related networks).  
+> It uses dependencies available in the iOS ecosystem (e.g., SoraFoundation, SoraKeystore, FearlessKeys) and has an Android counterpart in soramitsu/fearless-Android.
+<!-- wallet-context:end -->
+
+## Project Structure & Modules
+- `fearless/`: App sources, split by features/modules.
+- `fearlessTests/`, `fearlessIntegrationTests/`: Unit/integration tests.
+- `fearless.xcworkspace`, `fearless.xcodeproj`: Xcode workspace/project files.
+- `Pods/`, `Podfile`, `Podfile.lock`: CocoaPods dependencies.
+- `Jenkinsfile`: CI pipeline configuration.
+- Config files: `.swiftlint.yml`, `.swiftformat`, `.periphery.yml`.
+
+## Build, Test, and Dev Commands
+- Install dependencies: `pod install`
+- Build (Debug, simulator):
+  - `xcodebuild -workspace fearless.xcworkspace -scheme fearless -configuration Debug -destination 'platform=iOS Simulator,OS=latest,name=iPhone 15' build`
+- Run unit tests (on simulator):
+  - `xcodebuild -workspace fearless.xcworkspace -scheme fearless.tests -destination 'platform=iOS Simulator,OS=latest,name=iPhone 15' test`
+- Lint/format:
+  - `swiftlint` (uses `.swiftlint.yml`)
+  - `swiftformat .` (uses `.swiftformat`)
+  - CI matrix: `bash scripts/test-matrix.sh` runs tests for Debug and Release
+
+Example destinations
+- iPhone 15: `-destination 'platform=iOS Simulator,OS=latest,name=iPhone 15'`
+- iPhone 14 Pro: `-destination 'platform=iOS Simulator,OS=latest,name=iPhone 14 Pro'`
+- iPad Pro (11-inch) 4th gen: `-destination 'platform=iOS Simulator,OS=latest,name=iPad Pro (11-inch) (4th generation)'`
+
+Tip: list available destinations with `xcodebuild -showsdks` and `xcrun simctl list devices`.
+
+CI note
+- Jenkins is configured to run tests on each build. For deterministic local parity, use `scripts/test-matrix.sh` before opening a PR.
+
+## Coding Style & Naming
+- Language: Swift; follow Swift API design guidelines.
+- Formatting: SwiftFormat; linting with SwiftLint.
+- Files: one main type per file; names in PascalCase; avoid long files.
+- Packages/Modules: keep dependencies explicit; prefer dependency injection to singletons.
+- Avoid force‑unwraps; handle errors explicitly with clear user messaging.
+
+## Testing Guidelines
+- Framework: XCTest; tests live in `fearlessTests/` and `fearlessIntegrationTests/`.
+- Naming: mirror the class under test, e.g., `AccountRepositoryTests.swift`; test methods `testX_whenY_thenZ`.
+- Coverage: maintain/raise coverage for changed code.
+- New code policy: whenever you add a function, add at least one unit test covering it.
+
+## Commit & Pull Requests
+- Commits: concise, imperative subjects; reference issues (`#123`). Conventional Commit prefixes (`feat:`, `fix:`, `refactor:`) encouraged.
+- Before PR: ensure build + tests pass locally; `swiftlint`/`swiftformat` are clean.
+- PR checklist: clear description, linked issue, screenshots/video for UI, steps to test, risk/rollback notes.
+- CI must be green (Jenkins or equivalent).
+
+## Security & Configuration
+- Never commit secrets or private keys. Use Keychain/secure storage at runtime; use CI secrets for pipelines.
+- Do not alter seed handling, signing, or cryptography without maintainer approval.
+- Runtime registries and chain/type sources must be aligned with the current Polkadot SDK release; coordinate updates with maintainers.
+- Use `*.xcconfig` and environment variables for private values; avoid hardcoding secrets in `Info.plist`.
+
+## Dependencies & Versioning
+- Prefer conservative upgrades (patch/minor). Pin major bumps to separate PRs with clear testing notes.
+- Summarize upstream changes (link release notes) and provide a rollback plan.
+- If aligning to a Polkadot SDK release, ensure iOS utils/runtime dependencies are pinned accordingly (e.g., fearless-utils‑ios or equivalent).
+
+## Preferred Tasks for Agents
+- Keep build green: fix warnings, flaky tests, and broken CI when root cause is clear.
+- Code hygiene: remove dead code; improve naming; tighten access control.
+- Tooling: enforce SwiftLint/SwiftFormat; update configs when safe.
+- Tests: add missing unit tests around changed code; stabilize integration tests.
+- Docs: keep README/ROADMAP/this guide accurate; small updates are welcome.
+
+## Out of Scope (without prior approval)
+- Feature/UI/UX changes.
+- Protocol, staking, or on‑chain logic changes.
+- Wallet/account management, seeds, encryption, or secure storage changes.
+- Adding telemetry/analytics.
+
+## Communication & Escalation
+- Use GitHub issues/PRs for decisions and traceability.
+- See `CONTRIBUTING.md` for community channels and expectations.
+- When in doubt, open an issue and wait for maintainer guidance.
+
+## Sources of Truth
+- Roadmap (Aha!): https://soramitsucoltd.aha.io/shared/97bc3006ee3c1baa0598863615cf8d14
+- Dev status board: https://soramitsucoltd.aha.io/shared/343e5db57d53398e3f26d0048158c4a2
+- Issues: https://github.com/soramitsu/fearless-iOS/issues
+- Contributing: ./CONTRIBUTING.md
+- Roadmap (repo): ./ROADMAP.md
+
+---
+
+By following these guidelines, agents help keep Fearless Wallet iOS healthy, predictable, and aligned with the published roadmap while minimizing risk to users.
+
+## Build & Archive — End‑to‑End Checklist
+
+The project mixes CocoaPods and Swift Package Manager. Follow these steps in order.
+
+1) Prerequisites (local dev)
+- Xcode 15.4+ (Xcode 18 SDK supported; CI pins 15.x when available for SPM/IrohaCrypto stability)
+- CocoaPods: `brew install cocoapods` (or `gem install cocoapods`)
+- SwiftFormat, SwiftLint (optional for local): `brew install swiftformat swiftlint`
+
+2) Install Pods (always open the workspace)
+- From repo root: `pod install`
+- Open: `open fearless.xcworkspace`
+
+3) Resolve SPM packages
+- CLI: `xcodebuild -resolvePackageDependencies -workspace fearless.xcworkspace -scheme fearless`
+- Xcode GUI: File → Packages → Reset Package Caches → Resolve Package Versions (if needed)
+
+4) Build & test on Simulator (no signing)
+- Build: `xcodebuild -workspace fearless.xcworkspace -scheme fearless -configuration Debug -destination 'platform=iOS Simulator,OS=latest,name=iPhone 15' build`
+- Tests: `bash scripts/test-matrix.sh` (runs Debug + Release simulator tests using `fearless.tests` by default)
+
+5) Archive (two options)
+- Development archive (local testing without Distribution certs):
+  - In Xcode target ‘fearless’ → Signing & Capabilities (Dev config): set Automatic + Apple Development + your team/profile.
+  - Then: `xcodebuild -workspace fearless.xcworkspace -scheme fearless -configuration Dev -destination 'generic/platform=iOS' -archivePath "$PWD/build/fearless.xcarchive" clean archive`
+- Ad‑hoc archive (CI/Release parity):
+  - Requirements on the machine: Apple Distribution certificate for team `YLWWUD25VZ` + ad‑hoc profile `fearlesswallet-dev-adhoc` installed.
+  - Project Dev config must be Manual + Apple Distribution + `jp.co.soramitsu.fearlesswallet.dev` + `PROVISIONING_PROFILE_SPECIFIER=fearlesswallet-dev-adhoc`.
+
+6) Private pods (FearlessKeys)
+- The pod `FearlessKeys` is private. To allow `pod install` on CI/local without prompting:
+  - Provide a GitHub Personal Access Token with repo read access (recommended env var: `GH_PAT_READ`).
+  - Preconfigure git on the agent: `git config --global url."https://${GH_PAT_READ}@github.com/".insteadOf "https://github.com/"` (or run `scripts/secrets/setup-private-pods.sh` which does this for you and writes `.env.private` with `INCLUDE_FEARLESS_KEYS=1`).
+  - Alternatively, write a `~/.netrc` with GitHub credentials (read-only).
+
+7) IrohaCrypto + SPM stability (Xcode 16/18)
+- The SPM package `shared-features-spm` must be pinned to a revision that works with Xcode 16/18 (`3ad0fe9…`). We now enforce this automatically via `scripts/deps/enforce-ssf-pin.sh` in CI (`bootstrap.sh`), local dev (`dev-setup.sh`), and tests (`test-matrix.sh`).
+- Dependency-contract validation is centralized in:
+  - `scripts/deps/check-dependency-contracts.sh`
+- Native crypto stability now uses dedicated contract scripts:
+  - `scripts/deps/prepare-native-crypto-checkout.sh`
+  - `scripts/deps/apply-native-crypto-package-contract.sh`
+  - `scripts/deps/apply-native-crypto-modulemap-contract.sh`
+  - `scripts/deps/verify-native-crypto-package-state.sh`
+- Additional required `shared-features-spm` compatibility fixes (BigInt dep, Web3 Data.bytes, AddressFactory type usage, scrypt guard) are applied by `scripts/spm-shared-features-fixes.sh`.
+
+8) Web3 duplication
+- The project uses `soramitsu/web3-swift@7.7.7`. Do not add another Web3 source; duplicate packages will cause resolver failure.
+
+## CI Build Requirements (Jenkins)
+
+- CocoaPods available on agents (or handled in a shared pipeline step). If Pods are installed elsewhere, our Jenkinsfile guards will skip `pod install` gracefully.
+- Environment variables:
+  - `GH_PAT_READ` (optional): GitHub PAT for private pods (`FearlessKeys`).
+  - `DEVELOPER_DIR` (optional): Jenkinsfile auto‑pins to Xcode 15.x if present for SPM stability; otherwise default Xcode is used.
+- Private keys in PRs:
+  - PR builds do NOT require private keys. The Jenkinsfile detects PR context (`CHANGE_ID`) and temporarily comments out the `pod 'FearlessKeys'` line before `pod install`, then restores the file. This prevents private repo access and allows PRs to build without secrets.
+  - Trusted branches (develop/master/release): Jenkins sets `INCLUDE_FEARLESS_KEYS=1` and, if `GH_PAT_READ` is present, rewrites GitHub URLs to use the token so `pod install` can fetch `FearlessKeys`.
+- Steps performed before archive:
+  - Clean SPM caches; resolve packages if the workspace exists.
+  - Configure GitHub token (if provided) and run `pod install --repo-update` when `pod` is available.
+  - Prepare the native crypto checkout against the repo-owned contract when required by the resolved package state.
+- Fastlane lane archives Dev as Ad‑hoc with mapping:
+  - `jp.co.soramitsu.fearlesswallet.dev` → `fearlesswallet-dev-adhoc`
+  - Ensure the Apple Distribution cert for `YLWWUD25VZ` is installed on the CI keychain.
+
+## Common Build Failures & Fixes
+
+- “No profile … matching ‘fearlesswallet-dev-adhoc’”: install the ad‑hoc profile (and Distribution certificate) on the machine, or switch PR builds to Development signing.
+- “Missing package product ‘MPQRCoreSDK’”: resolve SPM; reset SPM caches; ensure network access for binary targets.
+- “umbrella header … IrohaCrypto-umbrella.h not found”: use the pinned `shared-features-spm` revision and run the dedicated native crypto contract scripts / verifier.
+- “multiple similar targets ‘Web3’ …”: dedupe to `soramitsu/web3-swift@7.7.7` only.
+- “pod install” fails cloning FearlessKeys: supply `GH_PAT_READ` or gate that pod in CI.
+- “Ambiguous type ‘MetaAccountModel’ / ‘ChainAccountResponse’ in tests”: tests include `fearlessTests/Helper/TestTypeAliases.swift` to resolve ambiguity to app models. If you add conflicting SDK types, keep this shim or qualify uses (`fearless.MetaAccountModel`).
+- “JSONRPCEngine conformance missing in tests”: `fearlessTests/Common/Services/ChainRegistry/MockConnection.swift` provides a test engine conforming to the current `JSONRPCEngine` protocol. If the protocol changes upstream, adjust this file accordingly.
+
+## Troubleshooting Raw Archive Output
+
+- To bypass xcpretty and see the actual error:
+  - `set -o pipefail; xcodebuild -workspace fearless.xcworkspace -scheme fearless -configuration Dev -destination 'generic/platform=iOS' -archivePath "$PWD/build/fearless.xcarchive" clean archive | tee build/archive.raw.log`
+  - Then: `tail -n 300 build/archive.raw.log`