feat(doctor): add iOS diagnostics

Author: seanperez29

.changeset/ios-aware-doctor.md

@@ -0,0 +1,5 @@
+---
+"clerk": minor
+---
+
+Add native iOS project diagnostics and opt-in Xcode build and Simulator checks to `clerk doctor`.

packages/cli-core/src/commands/doctor/README.md

@@ -1,8 +1,8 @@
 # Doctor Command
 
 Runs a series of diagnostic checks on your Clerk CLI setup and reports
-the status of each check. The command is read-only and never modifies
-any state (unless `--fix` is used).
+the status of each check. The command is read-only by default. `--fix` and the
+explicit Xcode execution flags are the only modes which can change local state.
 
 ## Usage
 
@@ -12,31 +12,86 @@ clerk doctor --verbose   # Show detailed output
 clerk doctor --json      # Output results as JSON
 clerk doctor --spotlight # Only show warnings and failures
 clerk doctor --fix       # Offer to auto-fix issues
+clerk doctor --target MyApp
+clerk doctor --target MyApp --build
+clerk doctor --target MyApp --resolve-packages --build
+clerk doctor --target MyApp --simulator --device <udid>
 ```
 
 ## Options
 
-| Flag          | Description                                           |
-| ------------- | ----------------------------------------------------- |
-| `--verbose`   | Show detailed diagnostic info for each check          |
-| `--json`      | Output results as machine-readable JSON               |
-| `--spotlight` | Only show warnings and failures (hide passing checks) |
-| `--fix`       | Offer to auto-fix issues with known remedies          |
+| Flag                 | Description                                                                    |
+| -------------------- | ------------------------------------------------------------------------------ |
+| `--verbose`          | Show detailed diagnostic info for each check                                   |
+| `--json`             | Output results as machine-readable JSON                                        |
+| `--spotlight`        | Only show warnings and failures (hide passing checks)                          |
+| `--fix`              | Offer to auto-fix issues with known remedies                                   |
+| `--target`           | Select an iOS application target by name or object ID                          |
+| `--xcode-container`  | Select an inspected `.xcodeproj` or `.xcworkspace` for execution checks        |
+| `--scheme`           | Select an Xcode scheme for execution checks                                    |
+| `--resolve-packages` | Explicitly allow Xcode to resolve Swift packages and update `Package.resolved` |
+| `--build`            | Build the selected iOS app for Simulator in an isolated directory              |
+| `--simulator`        | Build, install, and launch the selected app in Simulator                       |
+| `--device`           | Simulator UDID or exact device name (requires `--simulator`)                   |
 
 ## Checks
 
 | Check                 | Category       | What it verifies                                                                                                                                                                                     |
 | --------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Authentication token  | Authentication | Credential store has a stored token                                                                                                                                                                  |
-| Token validity        | Authentication | Token is still valid (calls `/oauth/userinfo`)                                                                                                                                                       |
+| Account credentials   | Authentication | Credential store has a session or a Platform API key is configured                                                                                                                                   |
+| Token validity        | Authentication | OAuth token is still valid (calls `/oauth/userinfo`); Platform API-key access is verified by endpoint checks                                                                                         |
 | Project linkage       | Project        | Current directory is linked to a Clerk app                                                                                                                                                           |
 | Linked application    | Project        | Linked application ID is accessible via the API                                                                                                                                                      |
 | Instances             | Project        | Configured dev/prod instance IDs match the application's instances                                                                                                                                   |
-| Environment variables | Environment    | .env.local or .env has Clerk keys                                                                                                                                                                    |
+| Environment variables | Environment    | Non-iOS projects have Clerk keys in `.env.local` or `.env`                                                                                                                                           |
 | CLI configuration     | Configuration  | CLI config file exists and parses                                                                                                                                                                    |
 | Shell completion      | Configuration  | Shell autocompletion is installed for the detected shell                                                                                                                                             |
 | MCP server            | Integration    | If a Clerk MCP entry is installed, every distinct configured server answers the `initialize` handshake; warns on an unreadable client config (skipped when nothing is installed; warns, never fails) |
 
+### iOS projects
+
+When the current directory contains an Xcode project or `--target` is provided,
+doctor replaces the web `.env` check with the same semantic Xcode, Swift, and
+entitlements inspection used by `clerk init`. It reports separate results for:
+
+- application-target selection;
+- ClerkKit and ClerkKitUI product linkage;
+- `Clerk.configure` and the selected target's effective development key;
+- SwiftUI environment injection and authentication-flow evidence;
+- AuthView's enabled methods and required local Apple capability;
+- Associated Domains and the optional Sign in with Apple entitlement;
+- Native API state and the exact Bundle ID registration on the linked
+  development instance; and
+- the Clerk Apple connection when the selected target already declares the
+  native Apple entitlement.
+
+iOS diagnostics never require a secret key in the Xcode project or an env
+file. The linked development publishable key is used only to compare redacted
+Frontend API host metadata; keys, provider credentials, and raw remote config
+are not included in human or JSON output. AuthView, Native Application, and
+Apple remote checks are GET-only. Their remedies point back to `clerk init`;
+`doctor --fix` never enables an auth strategy or changes Native Application
+state.
+
+Plain `clerk doctor` remains read-only and does not invoke Xcode. The execution
+flags are deliberately opt-in because Xcode can run package manifests, plugins,
+macros, and project build scripts:
+
+- `--resolve-packages` is the only mode allowed to create or update the
+  selected container's shared `Package.resolved`.
+- `--build` requires a locked remote package graph, verifies the chosen scheme
+  belongs to the selected target, disables signing, filters Clerk credentials
+  from the child environment, and builds with temporary DerivedData and package
+  checkouts.
+- `--simulator` additionally installs and launches that isolated build. It
+  never guesses among multiple devices; agent mode requires `--device`.
+
+A successful build or launch is not a successful authentication test. Doctor
+still asks the developer to verify sign-in, sign-out, relaunch, and any redirect
+methods in the app. Projects which load their publishable key only through an
+Xcode Run-scheme environment variable are built but must be launched from Xcode,
+because `simctl launch` does not reproduce arbitrary scheme environment state.
+
 ### Keyless applications
 
 The Authentication token, Token validity, and Project linkage checks resolve
@@ -75,6 +130,10 @@ re-run to verify the results.
 interactive (`clerk auth login` opens a browser, `clerk link` shows a
 picker). It is ignored in `--json` mode and agent mode.
 
+`--fix` cannot be combined with Xcode execution flags. This prevents the
+post-fix verification pass from resolving, building, or launching a project a
+second time.
+
 Fixable issues:
 
 | Issue                              | Fix action                          |
@@ -117,8 +176,13 @@ Exit code 1 signals one or more checks failed.
 
 ## API Endpoints
 
-| Method | Endpoint                            | Description                                                     |
-| ------ | ----------------------------------- | --------------------------------------------------------------- |
-| `GET`  | `/oauth/userinfo`                   | Validates the stored auth token                                 |
-| `GET`  | `/v1/platform/applications/{appId}` | Verifies the linked app and its instances exist                 |
-| `GET`  | `/v1/instance`                      | Names the keyless application (best-effort, via its secret key) |
+| Method | Endpoint                                                                           | Description                                                                       |
+| ------ | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `GET`  | `/oauth/userinfo`                                                                  | Validates the stored auth token                                                   |
+| `GET`  | `/v1/platform/applications/{appId}`                                                | Verifies the linked app and its instances exist                                   |
+| `GET`  | `/v1/platform/applications/{appId}/instances/{instanceId}/native_settings`         | Verifies Native API state for iOS projects                                        |
+| `GET`  | `/v1/platform/applications/{appId}/instances/{instanceId}/native_applications/ios` | Verifies the exact iOS Bundle ID registration                                     |
+| `GET`  | `/v1/platform/applications/{appId}/instances/{instanceId}/config`                  | Audits the Apple connection when native Apple is relevant                         |
+| `GET`  | `/v1/platform/applications/{appId}/instances/{instanceId}/config/schema`           | Determines whether an unhealthy Apple connection can be safely reconciled by init |
+| `GET`  | `https://{fapiHost}/v1/environment`                                                | Verifies whether AuthView currently offers native Apple sign-in                   |
+| `GET`  | `/v1/instance`                                                                     | Names the keyless application (best-effort, via its secret key)                   |

packages/cli-core/src/commands/doctor/checks.ts

@@ -5,7 +5,6 @@ import { fetchUserInfo } from "../../lib/token-exchange.ts";
 import { errorMessage, isAuthError, PlapiError } from "../../lib/errors.ts";
 import { detectPublishableKeyName, detectSecretKeyName } from "../../lib/framework.ts";
 import { parseEnvFile } from "../../lib/dotenv.ts";
-import { hasAccountCredentials } from "../../lib/credential-store.ts";
 import type { KeylessTarget } from "../../lib/keyless-target.ts";
 import { CURRENT_VERSION, IS_DEV_BUILD } from "../../lib/version.ts";
 import {
@@ -102,6 +101,20 @@ export async function checkLoggedIn(ctx: DoctorContext): Promise<CheckResult> {
   const keyless = await ctx.getKeylessTarget();
   const keyError = await ctx.getKeylessKeyError();
 
+  if (ctx.hasPlatformAPIKey()) {
+    if (keyError) {
+      return check.warn(
+        `Platform API key configured, but the local secret key is unusable: ${keyError.message}`,
+        {
+          remedy:
+            "Fix or remove the malformed secret key — some commands prefer it over account credentials.",
+          fixable: false,
+        },
+      );
+    }
+    return check.pass("Authenticated with a Platform API key");
+  }
+
   if (token) {
     if (keyError) {
       return check.warn(`Logged in, but the local secret key is unusable: ${keyError.message}`, {
@@ -158,8 +171,14 @@ export async function checkHostExecution(): Promise<CheckResult> {
 
 export async function checkTokenValid(ctx: DoctorContext): Promise<CheckResult> {
   const check = defineCheck("Authentication valid", ctx.fixes.login);
+  if (ctx.hasPlatformAPIKey()) {
+    return check.pass("Platform API key configured; access is verified by API checks");
+  }
   const storedToken = await ctx.getToken();
   if (!storedToken) {
+    if (await ctx.hasAccountCredentials()) {
+      return check.pass("Platform API key configured; access is verified by API checks");
+    }
     const keyless = await ctx.getKeylessTarget();
     return keyless
       ? check.pass("No account session — not required for this keyless application")
@@ -173,6 +192,23 @@ export async function checkTokenValid(ctx: DoctorContext): Promise<CheckResult>
     return check.pass(`Authenticated as ${userInfo.email}`);
   } catch (error) {
     if (isAuthError(error)) {
+      // The OAuth userinfo surface is not available in every environment that
+      // can accept the same account credential through PLAPI. When a linked
+      // application is reachable, that authenticated request is stronger
+      // evidence for the CLI than a userinfo rejection. `getApplication()` is
+      // cached by the real context, so the later application check reuses this
+      // request. A genuinely expired hosted session still falls through: PLAPI
+      // rejects the same token (or token refresh) too.
+      try {
+        const app = await ctx.getApplication();
+        if (app) {
+          return check.pass("Account access verified through the Clerk API");
+        }
+      } catch {
+        // Preserve the existing expired-session diagnosis below. The
+        // application check reports its own endpoint-specific failure later.
+      }
+
       // Same fallback whoami uses: an expired session doesn't strand a keyless
       // project, so don't tell the user their setup is broken.
       const keyless = await ctx.getKeylessTarget();
@@ -229,7 +265,7 @@ export async function checkProjectLinked(ctx: DoctorContext): Promise<CheckResul
 
     // Someone with an account who hasn't linked this directory *could* reach
     // the full account configuration — say so, unlike the fully unclaimed case.
-    if (await hasAccountCredentials()) {
+    if (await ctx.hasAccountCredentials()) {
       return check.warn(
         `Not linked — using the keyless application ${label}, which covers fewer settings`,
         {
@@ -251,8 +287,7 @@ export async function checkProjectLinked(ctx: DoctorContext): Promise<CheckResul
 
 export async function checkLinkedAppExists(ctx: DoctorContext): Promise<CheckResult> {
   const check = defineCheck("Application reachable", ctx.fixes.link);
-  const token = await ctx.getToken();
-  if (!token) {
+  if (!(await ctx.hasAccountCredentials())) {
     // This check is account-only — the Platform API application record has no
     // keyless equivalent — so an unclaimed keyless project has nothing to skip
     // *over*, just nothing to verify.
@@ -286,8 +321,7 @@ export async function checkLinkedAppExists(ctx: DoctorContext): Promise<CheckRes
 
 export async function checkInstances(ctx: DoctorContext): Promise<CheckResult> {
   const check = defineCheck("Instance IDs", ctx.fixes.link);
-  const token = await ctx.getToken();
-  if (!token) {
+  if (!(await ctx.hasAccountCredentials())) {
     // A linked profile's dev/prod instance IDs are an account-only concept —
     // the secret key on disk already addresses its one instance directly.
     const keyless = await ctx.getKeylessTarget();

packages/cli-core/src/commands/doctor/context.test.ts

@@ -135,6 +135,7 @@ describe("createDoctorContext", () => {
     });
 
     test("returns null when no token", async () => {
+      delete process.env.CLERK_PLATFORM_API_KEY;
       mockGetToken.mockResolvedValue(null);
 
       const ctx = createDoctorContext();
@@ -144,6 +145,21 @@ describe("createDoctorContext", () => {
       expect(mockFetch).not.toHaveBeenCalled();
     });
 
+    test("fetches the public application shape with a Platform API key", async () => {
+      mockGetToken.mockResolvedValue(null);
+      mockResolveProfile.mockResolvedValue({
+        path: "github.com/org/repo",
+        profile: { workspaceId: "org_1", appId: "app_1", instances: { development: "ins_dev" } },
+        resolvedVia: "remote" as const,
+      });
+      mockAppResponse = { application_id: "app_1", name: "My App", instances: [] };
+
+      const ctx = createDoctorContext();
+      expect(await ctx.getApplication()).toEqual(mockAppResponse);
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+      expect(String(mockFetch.mock.calls[0]?.[0])).not.toContain("include_secret_keys");
+    });
+
     test("returns null when no profile", async () => {
       mockGetToken.mockResolvedValue("test_token");
       mockResolveProfile.mockResolvedValue(undefined);

packages/cli-core/src/commands/doctor/context.ts

@@ -1,4 +1,4 @@
-import { getToken, getValidToken } from "../../lib/credential-store.ts";
+import { getToken, getValidToken, hasAccountCredentials } from "../../lib/credential-store.ts";
 import { resolveProfile } from "../../lib/config.ts";
 import { fetchApplication, type Application } from "../../lib/plapi.ts";
 import { resolveKeylessTarget, type KeylessTarget } from "../../lib/keyless-target.ts";
@@ -17,6 +17,7 @@ import type { DoctorContext, KeylessInstanceInfo, ResolvedProfile } from "./type
 
 export function createDoctorContext(): DoctorContext {
   let tokenPromise: Promise<string | null> | undefined;
+  let accountCredentialsPromise: Promise<boolean> | undefined;
   let validTokenPromise: Promise<string | null> | undefined;
   let profilePromise: Promise<ResolvedProfile | undefined> | undefined;
   let appPromise: Promise<Application | null> | undefined;
@@ -26,6 +27,17 @@ export function createDoctorContext(): DoctorContext {
   let keylessKeyError: CliError | undefined;
 
   const ctx: DoctorContext = {
+    hasPlatformAPIKey() {
+      return Boolean(process.env.CLERK_PLATFORM_API_KEY);
+    },
+
+    hasAccountCredentials() {
+      if (!accountCredentialsPromise) {
+        accountCredentialsPromise = hasAccountCredentials();
+      }
+      return accountCredentialsPromise;
+    },
+
     getToken() {
       if (!tokenPromise) {
         tokenPromise = getToken();
@@ -50,11 +62,14 @@ export function createDoctorContext(): DoctorContext {
     getApplication() {
       if (!appPromise) {
         appPromise = (async () => {
-          const token = await ctx.getToken();
-          if (!token) return null;
+          if (!(await ctx.hasAccountCredentials())) return null;
           const resolved = await ctx.getProfile();
           if (!resolved) return null;
-          return fetchApplication(resolved.profile.appId);
+          // Doctor only needs application and instance identity. Keeping
+          // secret keys out of this long-lived, shared diagnostic context
+          // prevents unrelated checks from retaining credentials they never
+          // use (including the iOS checks below).
+          return fetchApplication(resolved.profile.appId, { includeSecretKeys: false });
         })();
       }
       return appPromise;