Baros

Native SwiftUI workout tracker for iPhone with a SwiftData-backed offline workout log.

Requirements

• Xcode 26+
• iOS Simulator runtime
• XcodeGen

Commands

• Generate project: xcodegen generate
• Build simulator app: xcodebuild build -project Baros.xcodeproj -scheme Baros -destination generic/platform=iOS\ Simulator -derivedDataPath /private/tmp/codex-ios-app-derived-data
• Run full XCTest suite: xcodebuild test -project Baros.xcodeproj -scheme Baros -destination platform=iOS\ Simulator,name=iPhone\ 17,OS=26.0 -derivedDataPath /private/tmp/codex-ios-app-derived-data
• Run unit tests only: xcodebuild test -project Baros.xcodeproj -scheme BarosUnitTests -destination platform=iOS\ Simulator,name=iPhone\ 17,OS=26.0 -derivedDataPath /private/tmp/codex-ios-app-derived-data
• Run UI tests only: xcodebuild test -project Baros.xcodeproj -scheme Baros -destination platform=iOS\ Simulator,name=iPhone\ 17,OS=26.0 -only-testing:BarosUITests -derivedDataPath /private/tmp/codex-ios-app-derived-data

CI

Pull requests classify changed paths before selecting the relevant GitHub Actions checks. Pushes to main use the same path boundaries. The checks are:

• ios-unit-tests: builds the BarosUnitTests scheme and runs BarosTests.
• ios-ui-smoke: runs four deterministic UI tests covering completed workout logging, workout/tab navigation, a settings-triggered sync request, and signed-out local-data reset.
• convex-checks: runs Convex Vitest coverage and Convex typecheck.
• support-site-checks: builds, checks, and tests the Astro support site, including any tracked release-asset contracts.

The two iOS jobs report as skipped on support-site-only or unrelated pull requests, which preserves their required-check results without reserving a macOS runner. Changes to convex/auth.config.ts are app-relevant because the Swift unit suite validates that file's Clerk audience and OIDC contract.

The UI smoke job intentionally selects only the four tests below instead of making the full BarosUITests target part of the required PR gate. Each selected test uses the UI suite's deterministic reset and in-memory launch helper. If either iOS job fails, first inspect the GitHub Actions log. The failed workflow run also uploads its .xcresult bundle and test log for local Xcode inspection.

Run the exact UI smoke shard locally with:

rm -rf /private/tmp/BarosUISmoke.xcresult
xcodebuild test \
  -project Baros.xcodeproj \
  -scheme Baros \
  -destination 'platform=iOS Simulator,name=iPhone 17,OS=26.5' \
  -only-testing:BarosUITests/BarosUITests/testLogWorkoutSmoke \
  -only-testing:BarosUITests/BarosUITests/testTabNavigationAndFinishSheetSmoke \
  -only-testing:BarosUITests/BarosUITests/testSettingsEditRequestsSyncInUITestMode \
  -only-testing:BarosUITests/BarosUITests/testDeleteLocalDataReturnsToSettingsAfterReset \
  -derivedDataPath /private/tmp/baros-ui-smoke-derived-data \
  -resultBundlePath /private/tmp/BarosUISmoke.xcresult

The command must execute exactly 4 tests with no failures. CI reads the result bundle and fails the smoke gate unless totalTestCount is exactly 4, so a stale selector cannot silently reduce coverage.

The canonical local UI-suite command is the Run UI tests only command above. Xcode 26.5 currently discovers 140 tests in BarosUITests; treat a run with fewer discovered or executed tests as partial coverage, not a clean full-suite result. Keep the full UI target out of the required PR gate until issue #63 establishes repeated full-suite stability.

Local equivalents:

xcodebuild test -project Baros.xcodeproj -scheme BarosUnitTests -destination platform=iOS\ Simulator,name=iPhone\ 17,OS=26.5 -derivedDataPath /private/tmp/codex-ios-app-derived-data
pnpm install --frozen-lockfile
pnpm run convex:test
pnpm run convex:typecheck

Convex Setup

Convex auth requires the Clerk JWT issuer domain to be configured on each Convex deployment. For the current development Clerk instance, set:

pnpm exec convex env set CLERK_JWT_ISSUER_DOMAIN 'https://glad-krill-22.clerk.accounts.dev'

Then push the backend functions to the development deployment:

pnpm exec convex dev --once

Do not rely on a backend fallback for this value. Staging and production deployments should set their own Clerk issuer domain before deploying Convex functions.

Production Convex reference

Release builds point at the production Convex deployment:

https://sensible-reindeer-16.convex.cloud

Use this section when preparing an App Store release candidate or troubleshooting production auth/sync. Routine app changes do not require running the full production smoke every time.

The production Clerk JWT template is configured for Convex:

• JWT issuer: https://clerk.baros.fit
• JWT audience: convex

Verify the production Convex deployment uses the matching issuer domain:

pnpm exec convex env --prod get CLERK_JWT_ISSUER_DOMAIN

Production deploys

Every push to main that touches the backend deploys to production. The deploy job in .github/workflows/convex-ci.yml runs only after convex-checks passes. It never runs on pull requests. It reads CONVEX_DEPLOY_KEY from the convex-production GitHub environment. That environment is separate from Vercel's Production environment, which belongs to the support site. Check the Actions tab to see what shipped and when.

Merging to main is deploying, so every backend change must keep working with every app build still installed. Users update the App Store build late, or never. Remove a public function, or tighten its arguments or return shape, only after no supported build calls it. Schema changes must accept the data already in production. Convex rejects a deploy whose schema doesn't match existing documents, and the run fails without shipping.

Deploy by hand only as a fallback, for example when the Action is broken or production needs a redeploy without a new commit. Deploy from an up-to-date main so production still matches it:

pnpm exec convex deploy
pnpm exec convex function-spec --prod

Production smoke

For RC validation or production auth/sync troubleshooting, run a focused production smoke:

1. Sign in with the production Clerk account flow from a Release or TestFlight build.
2. Confirm Settings shows Sync Status: Up to date.
3. Exercise the release smoke flow that needs Convex auth, such as account deletion.
4. If a direct authSmoke:me check is needed, run it from a Debug build temporarily pointed at the production Clerk and Convex values because Developer Diagnostics is Debug-only.

Record smoke-test evidence on the relevant release issue when the check is part of release validation.

Agent / MCP Workflow

This repo includes .xcodebuildmcp/config.yaml for agents that use XcodeBuildMCP.

Install XcodeBuildMCP locally and install its MCP server skill:

xcodebuildmcp init --client agents --skill mcp

Then run project setup as needed:

xcodebuildmcp setup

Keep physical device IDs and machine-specific simulator UUIDs in local session defaults. Do not commit them to the repo config.