Scripts Reference - SwiftAI Boilerplate Pro

The boilerplate ships five helper scripts in scripts/. Each is listed below with its real flags and behavior, verified against the script source.

Script	Purpose
`run-tests.sh`	Test runner with coverage measurement
`appstore-43-audit.sh`	App Store Guideline 4.3(a) Release-binary audit gate (new in v2.2)
`rebrand-design-system-prefix.sh`	Rename the `SAI` design-system prefix (new in v2.2)
`update-config.sh`	Generate `Configuration.swift` from `Secrets.xcconfig`
`validate-template-manifest.sh`	Validate `template.manifest.json` against the repo (new in v2.2)

run-tests.sh

Location: scripts/run-tests.sh Test runner with optional coverage measurement. Run from the project root. With no flags it runs the app test target via xcodebuild test against the SwiftAIBoilerplatePro scheme; with --package NAME it runs swift test inside Packages/NAME instead.

Basic Usage
Package Testing
Verbose

# Run the app test target
./scripts/run-tests.sh

# Run with coverage
./scripts/run-tests.sh --coverage

# Run and open the HTML report
./scripts/run-tests.sh --coverage --open

# Test a specific package (swift test in Packages/NAME)
./scripts/run-tests.sh --package Core
./scripts/run-tests.sh --package Networking
./scripts/run-tests.sh --package Storage

# With coverage
./scripts/run-tests.sh --package Core --coverage

# Show full xcodebuild output (skips xcpretty)
./scripts/run-tests.sh --verbose

# Print usage
./scripts/run-tests.sh --help

Flags:

--coverage — Enable code coverage and generate the report
--open — Open the HTML coverage report in the browser
--package NAME — Test a single package via swift test
--verbose — Show detailed xcodebuild output (otherwise piped through xcpretty when available)
--help — Show usage and exit

Output (with --coverage, full-app run only):

Console test results
coverage-report.txt — text summary
coverage-report.html — detailed HTML report

The script’s internal COVERAGE_THRESHOLD (85%) only prints a pass/warn line; it does not fail the run. The enforced gate lives in CI (see CI/CD Commands). The full app run uses the Boilerplate.xctestplan workspace test plan, which executes ~598 tests across the 12 package test targets plus the app unit and UI test suites in one pass.

appstore-43-audit.sh

Location: scripts/appstore-43-audit.sh New in v2.2. Builds the app in Release configuration, then runs a strings audit over the main executable and the app-owned bundle, failing the build if any un-rebranded production fingerprint survives. This is the headline App Store Guideline 4.3(a) gate: it stops you from shipping a binary that still looks like the starter template. The risky-string patterns (SwiftAI, Boilerplate, api.example.com, DesignSystem/SAI, and more) are loaded from template.manifest.json so the script, CI, and agent prompts never diverge; an inline fallback list is used only for detached copies.

# Run the full Release-binary audit from the project root
bash scripts/appstore-43-audit.sh

Beyond the binary scan, it also checks configuration readiness and fails until you:

replace the starter BrandConfig.appDisplayName ("App Name"),
set production privacyPolicyURLString, termsOfServiceURLString, and subscriptionTermsURLString in BrandConfig,
rename the starter app bundle ID by editing APP_BUNDLE_ID (com.berkin.SwiftAIBoilerplatePro) in Config/App.xcconfig — every target’s PRODUCT_BUNDLE_IDENTIFIER derives from it — and
remove bundled generic/demo legal/showcase markdown.

It exits non-zero on any blocking app-owned hit and prints PASS: when clean. Override the scheme, destination, or derived-data paths via AUDIT_SCHEME, AUDIT_DESTINATION, AUDIT_DERIVED_DATA, and AUDIT_PACKAGE_CACHE env vars.

The deeper hardening workflow (binary audit, branding/identity map, App Review Notes template, per-module removal) lives in docs/checklists/APP_STORE_4_3_HARDENING.md, with prompt packs in docs/prompts/AppStore4_3Hardening.prompts.md. The matching standalone App Generator that produces a 4.3-safe app from this template is a separate product (coming soon) — see the License & Updates page.

rebrand-design-system-prefix.sh

Location: scripts/rebrand-design-system-prefix.sh New in v2.2. Renames the SAI design-system prefix throughout Packages/DesignSystem — both textual occurrences in .swift/.md files and the SAI*-named source files themselves. Useful for clearing the DesignSystem/SAI fingerprint flagged by the 4.3 audit.

# Dry run (default): list textual matches and the files that would be renamed
bash scripts/rebrand-design-system-prefix.sh SAI YourPrefix

# Apply the rename after committing or stashing your work
bash scripts/rebrand-design-system-prefix.sh SAI YourPrefix --apply

Arguments: OLD_PREFIX (default SAI), NEW_PREFIX (required), MODE (--dry-run default, or --apply). The new prefix must be a Swift-style identifier starting with an uppercase letter.

--apply rewrites files in place. Commit or stash first, then re-run tests and scripts/appstore-43-audit.sh before submitting.

update-config.sh

Location: scripts/update-config.sh Generates SwiftAIBoilerplatePro/Generated/Configuration.swift from Config/Secrets.xcconfig. Run it manually after filling in your keys. Placeholder values containing YOUR are skipped, so a fresh clone still builds and runs with MockAuthClient and EchoLLMClient.

# Generate Configuration.swift from Config/Secrets.xcconfig
bash scripts/update-config.sh

The generated AppConfiguration enum exposes a static let for each configured key and an isConfigured(_:) helper. Recognized keys: SUPABASE_URL, SUPABASE_ANON_KEY, REVENUECAT_API_KEY, RC_ENTITLEMENT_ID, PROXY_BASE_URL, PROXY_PATH, ONESIGNAL_APP_ID. See the Configuration reference for details.

This writes real API keys into a committed-by-default path. Do NOT commit Configuration.swift after running it. Install the pre-commit hook to block accidental commits: git config core.hooksPath .githooks.

validate-template-manifest.sh

Location: scripts/validate-template-manifest.sh New in v2.2. Validates template.manifest.json (the machine-readable single source of truth for identity surface, module graph, config schema, fingerprints, and recipes) against the actual repository.

# Validate the manifest from the project root
bash scripts/validate-template-manifest.sh

It checks that:

every path referenced by the manifest exists,
each module’s manifest-declared dependencies match its Package.swift,
the manifest fingerprint list is a superset of the audit script’s fallback list, and
each brand anchor resolves to exactly one marked line.

It prints template.manifest.json OK on success or one FAIL: line per problem (exit 1). This runs as the Template Manifest job in CI.

Supabase Scripts

Deploy Edge Function

# Login
supabase login

# Link project
cd supabase
supabase link --project-ref YOUR_REF

# Set secrets
supabase secrets set OPENROUTER_API_KEY=sk-or-v1-YOUR_KEY

# Deploy
supabase functions deploy ai

# Test
curl https://YOUR_PROJECT.supabase.co/functions/v1/ai

Run Migrations

# Push all migrations
supabase db push

# Create new migration
supabase migration new your_migration_name

# Reset database (DANGER!)
supabase db reset

Local Development

# Start local Supabase
supabase start

# Run functions locally
supabase functions serve

# Stop local Supabase
supabase stop

Xcode Build Scripts

Clean Build

# In Xcode
⌘ + Shift + K

# Or terminal
xcodebuild clean \
  -scheme SwiftAIBoilerplatePro \
  -configuration Debug

Run Tests

One xcodebuild test against the scheme runs the whole Boilerplate.xctestplan (all 12 package test targets + the app suites, ~598 tests):

xcodebuild test \
  -project SwiftAIBoilerplatePro.xcodeproj \
  -scheme SwiftAIBoilerplatePro \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=26.2' \
  -enableCodeCoverage YES

Git Workflows

Pre-commit Checks

The repo ships a pre-commit hook that blocks committing a generated Configuration.swift. Install it once:

git config core.hooksPath .githooks

Run the same checks CI runs before pushing:

# Lint (strict)
swiftlint lint --strict

# Tests with coverage
./scripts/run-tests.sh --coverage

# Validate the template manifest
bash scripts/validate-template-manifest.sh

Before an App Store submission, also run the 4.3 audit gate:

bash scripts/appstore-43-audit.sh

Branch Management

# Create feature branch
git checkout -b feature/your-feature

# Commit with message
git commit -m "feat: your feature description"

# Push and create PR
git push origin feature/your-feature

Package Management

Update Dependencies

# In Xcode
File → Packages → Update to Latest Package Versions

# Or terminal
xcodebuild -resolvePackageDependencies

Reset Package Cache

# In Xcode
File → Packages → Reset Package Caches

# Or terminal
rm -rf ~/Library/Caches/org.swift.swiftpm
rm -rf ~/Library/Developer/Xcode/DerivedData

Common Commands

Development

# Open project
open SwiftAIBoilerplatePro.xcodeproj

# Run app (requires Xcode)
xcodebuild -scheme SwiftAIBoilerplatePro

# Build only
xcodebuild build -scheme SwiftAIBoilerplatePro

Configuration

# Copy config template
cp Config/Secrets.example.xcconfig Config/Secrets.xcconfig

# Edit config
nano Config/Secrets.xcconfig
# or
open -a Xcode Config/Secrets.xcconfig

Cleaning

# Clean derived data
rm -rf ~/Library/Developer/Xcode/DerivedData

# Clean build folder
xcodebuild clean

# Reset simulators
xcrun simctl erase all

CI/CD Commands

GitHub Actions

Workflows in .github/workflows/: Main CI (ci.yml) — runs on push and pull request:

- Template Manifest    validate-template-manifest.sh
- Secret Scan          Gitleaks
- Build & Test (iOS 26.2)   xcodebuild test (iPhone 17 Pro, OS=26.2) + coverage gate
- Build & Test (iOS 18.6 fallback path)   pre-iOS-26 compile/run, no coverage gate
- SwiftLint             swiftlint lint --strict

The coverage gate enforces the MINIMUM_COVERAGE env value (currently 25) and fails the build below it; it is computed over product targets only. Coverage Report (coverage-report.yml) — runs weekly (Mondays 09:00 UTC) and on manual dispatch:

- Generate detailed coverage (text + JSON)
- Build an HTML coverage report
- Open a GitHub issue if coverage is low

Trigger manually:

GitHub UI → Actions → Select workflow → Run workflow

Quick Reference

Run Tests Locally

./scripts/run-tests.sh --coverage --open

Deploy Backend

cd supabase
supabase functions deploy ai

Clean Everything

xcodebuild clean
rm -rf ~/Library/Developer/Xcode/DerivedData
rm -rf ~/Library/Caches/org.swift.swiftpm

Check Coverage

./scripts/run-tests.sh --coverage
open coverage-report.html

App Store 4.3 Pre-submission Audit

bash scripts/appstore-43-audit.sh

Testing Guide

Testing strategies

Deployment

Production deployment

Supabase Setup

Backend deployment

Configuration

Config reference

License & Updates

Pricing, lifetime updates, and the App Generator (coming soon)

​run-tests.sh

​appstore-43-audit.sh

​rebrand-design-system-prefix.sh

​update-config.sh

​validate-template-manifest.sh

​Supabase Scripts

​Deploy Edge Function

​Run Migrations

​Local Development

​Xcode Build Scripts

​Clean Build

​Archive

​Run Tests

​Git Workflows

​Pre-commit Checks

​Branch Management

​Package Management

​Update Dependencies

​Reset Package Cache

​Common Commands

​Development

​Configuration

​Cleaning

​CI/CD Commands

​GitHub Actions

​Quick Reference

​Related Resources

Testing Guide

Deployment

Supabase Setup

Configuration

License & Updates

run-tests.sh

appstore-43-audit.sh

rebrand-design-system-prefix.sh

update-config.sh

validate-template-manifest.sh

Supabase Scripts

Deploy Edge Function

Run Migrations

Local Development

Xcode Build Scripts

Clean Build

Archive

Run Tests

Git Workflows

Pre-commit Checks

Branch Management

Package Management

Update Dependencies

Reset Package Cache

Common Commands

Development

Configuration

Cleaning

CI/CD Commands

GitHub Actions

Quick Reference

Related Resources