fix(init): improve established Apple app setup and interactive flow

[seanperez29]

Summary

Established Apple apps with custom startup configuration could be blocked from independent SDK linkage or native registration. This change allows each operation when its own prerequisites are proven, preserves custom Swift configuration and runtime-key uncertainty, and makes the interactive setup flow easier to review.

• Permit safe SDK linkage and explicit native application reconciliation with delegated configuration, including an existing AuthView. Explicit AuthView insertion still requires proven runtime wiring.
• Let Doctor check native registration when Swift source discovery is incomplete but the target identity is independently proven.
• Separate entitlement file selection and ownership from Associated Domains value validation, so unrelated domain issues do not block safe Apple sign-in or macOS networking edits. Reuse the macOS planning inspection while retaining checks before and after writes.
• Offer a target picker for ambiguous interactive selection; explicit targets and noninteractive safety rules are preserved.
• Group interactive progress under steady phase messages, show concise file previews, keep authentication/linking inside the surrounding init flow, and tailor final sign-in guidance to the existing app. Verbose output retains individual checks and detailed plans.

Safety boundaries

Each operation retains its checks for target identity, SDK compatibility, file ownership, source discovery, and approved changes. Selecting --app does not prove that a custom runtime key matches that application. Existing application UI is preserved unless the user opts into replacing a verified starter screen.

Validation

Current integrated head: 5dd8c8ca9d918910449e65496864c51c6576f9a4.

• Formatting, lint, typechecking, git diff --check, and all 4,257 unit tests passed.
• Entitlement regressions cover packaging-versus-compiler file selection, variable expansion, refused edits, and matching-path controls. macOS and JSON layers retain the same checks.
• Final integrated head 5dd8c8ca passed all 4,257 unit tests and compilation. All nine branch heads passed their local checks independently.
• On that integrated head, all 34 PBX/JSON corpus scenarios passed dry run, apply, unchanged rerun, and read-only Doctor; all 38 unsigned simulator/macOS corpus builds passed.
• Ten additional builds with local ad-hoc signing verified Xcode-generated signing entitlements: mismatched paths, matching Apple sign-in paths, domain expansion, and generated macOS networking/sandbox settings. Conflicts are blocked; matching Apple settings remain satisfied.
• Toolchains: Xcode 26.5 (17F42) for PBX and Xcode 27.2 beta (27B5019j) for JSON. Corpus APIs used local stubs; no live backend writes were performed.
• GitHub CI is left running after publication and was not monitored or awaited. Local credential-backed E2E and signed-device Apple sign-in were not rerun.
• The delayed-network presentation test initially hit its five-second timeout under concurrent build/check load; the full suite passed on retry without source changes.
• Detailed local evidence: clerk-cli-real-xcode-corpus/reports/2026-09-24-entitlement-packaging.md.

Earlier validation

UI validation recorded at 16a5158e33943af475cfdfee0c1c8e1ffbe0697c:

• Updated the native iOS E2E assertion to match the concise app-detection message; the targeted test passed against its local API stub with all 23 assertions.
• All 4,057 unit tests passed, along with formatting, lint, typechecking, changeset validation, and git diff --check. Lint retains the existing unused-parameter warning in commands/apps/shared.ts.
• Compiled the macOS ARM64 CLI with the existing environment profiles and verified the production login profile is embedded.
• Exercised the complete setup flow against a local API stub with delayed responses; verified stable progress indicators, preview/result boundaries, mutation counts, and completion messages. Real terminal checks covered grouped spinners, prompt boundaries, cancellation, and cursor restoration.
• Verified guidance for eligible starter screens, customized screens, existing authentication flows, and ClerkKit-only integrations.
• Sean manually completed authenticated clerk init on the new ClerkHelloDemo project, including prebuilt UI, native registration, and Sign in with Apple configuration. The blank project built for Simulator with Xcode 26.5 before setup.

Earlier integrated validation at 9dad4449f7ec561e32e314f94d523ff4908b2ca5 covered 24 real-Xcode-derived PBX/JSON scenarios and two incomplete-source subcases: dry run, apply, unchanged rerun, and Doctor. All 104 compared project/source files retained identical bytes and modes; dry-run and Doctor JSON matched the preceding integrated head after normalizing temporary paths. That published head also passed GitHub's credential-backed E2E suite on September 24.

The earlier f5c3ae48 head passed 28 unsigned builds with Xcode 26.5 and Xcode 27.2 beta. The full Xcode corpus and those builds were not rerun for the subsequent presentation changes. Local 1Password authorization previously timed out; no local credential-backed E2E success is claimed. Signed Apple sign-in inside a running app remains a separate validation step.

Stack

1. feat(init): add iOS project inspection foundations #431 — native Apple project inspection foundations
2. feat(init): add transactional native iOS mutation engines #453 — transactional local mutation engines
3. feat(init): compose native iOS local setup #489 — native iOS local setup orchestration
4. feat(init): reconcile native iOS backend configuration #454 — native iOS backend reconciliation
5. feat(init): integrate native iOS setup #490 — public native iOS init integration
6. feat(doctor): add native iOS diagnostics #455 — native iOS Doctor diagnostics
7. feat(native): add macOS setup and diagnostics #486 — macOS setup and diagnostics
8. feat(init): support Xcode JSON project format #488 — Xcode JSON project format
9. fix(init): improve established Apple app setup and interactive flow #493 — established app operation gates, neutral entitlement ownership, and interactive setup improvements

[changeset-bot]

🦋 Changeset detected

Latest commit: 5dd8c8c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}