swiftapp/README.md

# idp.global Swift App

Multiplatform SwiftUI passport companion for `idp.global` on iPhone, iPad, Mac, and Apple Watch.

## Current App Behavior

- iPhone pairing starts on a welcome screen and then opens QR scanning explicitly.
- QR pairing supports a manual paste fallback when camera scanning is unavailable.
- NFC pairing and NFC identity proof attach a signed GPS position on supported iPhones.
- The app uses the live `idp.global` backend by default for pairing, dashboard loading, approvals, and alerts.
- The Apple Watch companion and widgets live in the same Xcode project and build with the main app scheme.
- `MockIDPService` still exists for previews and test scaffolding, but normal runtime uses `LiveIDPService`.

## Repo Layout

- root `package.json`
- root `.smartconfig.json`
- Swift project at `swift/IDPGlobal.xcodeproj`

## tsswift Setup

This repo is configured for `tsswift` from the repo root and expects a named global remote builder.

Install tooling:

```bash
corepack pnpm install
```

Configure a global remote macOS builder once:

```bash
corepack pnpm exec tsswift config -g add-builder \
  --name <builder-name> \
  --host <ssh-host> \
  --root-dir <remote-project-root> \
  --platforms macos,ios,ipad
```

The global builder registry lives at:

```text
~/.git.zone/tsswift/config.json
```

Verify it with:

```bash
corepack pnpm exec tsswift config list-builders
corepack pnpm exec tsswift config show
```

## Remote Builder Behavior

This project does not keep per-repo SSH details inside `.smartconfig.json`.
Instead, it references a named builder, and `tsswift` resolves that builder from the global registry in `~/.git.zone/tsswift/config.json`.

How it works:

- `tsswift` syncs the repo to the configured remote project root via `rsync`
- `xcodebuild`, `simctl`, and simulator boot or launch commands execute on the remote macOS builder over SSH
- the local machine only orchestrates the workflow; Apple platform builds happen on the builder
- the selected simulator is opened by the requested device identifier instead of reviving a previously used simulator
- simulator builds are pinned to the builder machine's native architecture

Prerequisites:

- working SSH access to the remote builder host
- a configured global `tsswift` builder entry
- local permission to run `ssh` and `rsync`

Quick verification:

```bash
corepack pnpm exec tsswift config -g list-builders
corepack pnpm swift:doctor
```

`swift:doctor` should report the resolved remote builder and remote project root.

This repo's `.smartconfig.json` already points at that builder by name:

```json
"remoteBuilder": {
  "name": "<builder-name>"
}
```

Current project defaults:

- default scheme: `IDPGlobal`
- default configuration: `Debug`
- default run platform: `macos`
- build platforms: `macos`, `ios`, `ipad`
- test platform: `macos`
- preferred iPhone and iPad simulators are configured in `.smartconfig.json`
- derived data path: `swift/.build/xcode-derived-data`

`tsswift` pins simulator builds to the builder machine's native architecture and opens the selected simulator device directly instead of reviving a previously used iPhone.

## Common Commands

From the repo root:

```bash
corepack pnpm swift:doctor
corepack pnpm swift:emulators
corepack pnpm swift:build
corepack pnpm swift:build:macos
corepack pnpm run swift:build -- --platform ios
corepack pnpm run swift:build -- --platform ipad
corepack pnpm swift:test
corepack pnpm run swift:run -- --platform ios
corepack pnpm run swift:run -- --platform ipad
corepack pnpm swift:watch
```

Notes:

- `swift:build` builds the configured macOS, iPhone, and iPad matrix.
- `swift:test` runs the macOS test target.
- `swift:run` without extra flags follows the configured default platform, which is currently `macos`.
- `swift:run -- --platform ios` boots the configured remote iPhone simulator, installs the app, and launches it.
- `swift:run -- --platform ipad` does the same for the configured remote iPad simulator.

## Direct Xcode Use

If you are working directly on a Mac instead of through `tsswift`, open:

```text
swift/IDPGlobal.xcodeproj
```

Useful targets and schemes:

- `IDPGlobal` for the main app
- `IDPGlobalWatch` for the watch app
- `IDPGlobalWidgets` for widgets

## Pairing Notes

- Start a fresh pairing flow from the `idp.global` web session you want to trust.
- Scan the QR shown by that web flow, or paste the pairing link manually if camera access is unavailable.
- NFC flows are for supported iPhone hardware and include signed location evidence.