fix(init): harden iOS native reconciliation

Author: seanperez29

packages/cli-core/src/commands/init/index-ios.test.ts

@@ -30,6 +30,7 @@ import type { IOSLocalSetupResult } from "./ios/apply.ts";
 import type { IOSAppleEntitlementPlan } from "./ios/apple-entitlement.ts";
 import type { IOSNativeApplePlan } from "./ios/native-apple.ts";
 import type { IOSNativeRemotePlan } from "./ios/native-remote.ts";
+import type { IOSNativeReadinessTarget } from "./ios/native-readiness.ts";
 import type { IOSPrebuiltAuthPlan } from "./ios/prebuilt-auth.ts";
 
 const VALID_DEVELOPMENT_KEY = `pk_test_${btoa("example.clerk.accounts.dev$")}`;
@@ -138,6 +139,14 @@ function iosSetupResult(overrides: Partial<IOSLocalSetupResult> = {}): IOSLocalS
   };
 }
 
+function selectedNativeTarget(
+  overrides: Partial<Extract<IOSNativeReadinessTarget, { status: "selected" }>> = {},
+): Extract<IOSNativeReadinessTarget, { status: "selected" }> {
+  const target = FAKE_IOS_NATIVE_READINESS.target;
+  if (target.status !== "selected") throw new Error("Expected a selected iOS test target");
+  return { ...target, ...overrides };
+}
+
 describe("init iOS", () => {
   const { setup, track } = useInitHarness();
 
@@ -241,6 +250,155 @@ describe("init iOS", () => {
     }
   });
 
+  test("requires a confirmed App ID Prefix before an agent creates or links a new application", async () => {
+    setup({ isAgent: true, email: "test@test.com" });
+    const iosCtx = nativeIOSContext();
+    spyOn(context, "gatherContext").mockResolvedValue(iosCtx);
+    spyOn(iosApplyMod, "applyIOSLocalSetup").mockResolvedValue(
+      iosSetupResult({
+        requiresLinkedApp: true,
+        nativeReadiness: {
+          ...FAKE_IOS_NATIVE_READINESS,
+          target: selectedNativeTarget({
+            appIdPrefix: { status: "missing", source: "literal-entitlements" },
+          }),
+        },
+        unverifiedAppIdPrefixSuggestion: {
+          source: "xcode-development-team",
+          value: "ABCDE12345",
+        },
+      }),
+    );
+
+    await expect(init({ yes: true })).rejects.toThrow(
+      "Ask the user whether to use ABCDE12345 or enter a different App ID Prefix",
+    );
+
+    expect(linkMod.link).not.toHaveBeenCalled();
+    expect(pullMod.resolveEnvironmentKeys).not.toHaveBeenCalled();
+    expect(nativeRemoteMod.prepareIOSNativeRemoteSetup).not.toHaveBeenCalled();
+    expect(iosApplyMod.applyIOSPlannedLocalSetup).not.toHaveBeenCalled();
+  });
+
+  test("names an agent-created Clerk application after the selected Xcode target", async () => {
+    setup({ isAgent: true, email: "test@test.com" });
+    const iosCtx = nativeIOSContext();
+    spyOn(context, "gatherContext").mockResolvedValue(iosCtx);
+    spyOn(config, "resolveProfile")
+      .mockResolvedValueOnce(undefined)
+      .mockResolvedValueOnce(undefined)
+      .mockResolvedValue({ profile: { appId: "app_test" } } as never);
+    spyOn(iosApplyMod, "applyIOSLocalSetup").mockResolvedValue(
+      iosSetupResult({
+        targetName: "AnotherPromptTest",
+        requiresLinkedApp: true,
+        nativeReadiness: {
+          ...FAKE_IOS_NATIVE_READINESS,
+          target: selectedNativeTarget({
+            projectPath: "ContainerProject.xcodeproj",
+            targetName: "AnotherPromptTest",
+            appIdPrefix: { status: "missing", source: "literal-entitlements" },
+          }),
+        },
+      }),
+    );
+
+    await init({ yes: true, appIdPrefix: "CONFIRMED123" });
+
+    expect(linkMod.link).toHaveBeenCalledWith({
+      skipIfLinked: true,
+      app: undefined,
+      cwd: iosCtx.cwd,
+      createIfMissing: "AnotherPromptTest",
+      skipAutolink: true,
+    });
+    expect(nativeRemoteMod.prepareIOSNativeRemoteSetup).toHaveBeenCalledWith(
+      expect.objectContaining({
+        appIdPrefix: "CONFIRMED123",
+        applicationLinkChange: "created-and-linked",
+      }),
+    );
+  });
+
+  test("lets an explicit existing app supply its registered prefix without auto-creation", async () => {
+    setup({ isAgent: true, email: "test@test.com" });
+    const iosCtx = nativeIOSContext();
+    spyOn(context, "gatherContext").mockResolvedValue(iosCtx);
+    spyOn(config, "resolveProfile")
+      .mockResolvedValueOnce(undefined)
+      .mockResolvedValueOnce(undefined)
+      .mockResolvedValue({ profile: { appId: "app_existing" } } as never);
+    spyOn(iosApplyMod, "applyIOSLocalSetup").mockResolvedValue(
+      iosSetupResult({
+        requiresLinkedApp: true,
+        nativeReadiness: {
+          ...FAKE_IOS_NATIVE_READINESS,
+          target: selectedNativeTarget({
+            appIdPrefix: { status: "missing", source: "literal-entitlements" },
+          }),
+        },
+      }),
+    );
+    spyOn(pullMod, "resolveEnvironmentKeys").mockResolvedValue({
+      appId: "app_existing",
+      instanceId: "ins_existing",
+      instanceLabel: "development",
+      publishableKey: VALID_DEVELOPMENT_KEY,
+    });
+    spyOn(nativeRemoteMod, "prepareIOSNativeRemoteSetup").mockResolvedValue(
+      iosRemotePlan({
+        applicationId: "app_existing",
+        instanceId: "ins_existing",
+        appIdPrefix: "REGISTERED123",
+        nativeApi: "satisfied",
+        registration: "satisfied",
+        status: "satisfied",
+        actions: [],
+      }),
+    );
+
+    await init({ yes: true, app: "app_existing" });
+
+    expect(linkMod.link).toHaveBeenCalledWith({
+      skipIfLinked: true,
+      app: "app_existing",
+      cwd: iosCtx.cwd,
+      createIfMissing: undefined,
+      skipAutolink: true,
+    });
+    expect(nativeRemoteMod.prepareIOSNativeRemoteSetup).toHaveBeenCalledWith(
+      expect.objectContaining({
+        appIdPrefix: undefined,
+        applicationLinkChange: "link-updated",
+      }),
+    );
+  });
+
+  test("does not auto-create a replacement when an existing iOS link disappears", async () => {
+    setup({ isAgent: true, email: "test@test.com" });
+    const iosCtx = nativeIOSContext();
+    spyOn(context, "gatherContext").mockResolvedValue(iosCtx);
+    spyOn(config, "resolveProfile")
+      .mockResolvedValueOnce({ profile: { appId: "app_existing" } } as never)
+      .mockResolvedValue(undefined);
+    spyOn(iosApplyMod, "applyIOSLocalSetup").mockResolvedValue(
+      iosSetupResult({ requiresLinkedApp: true }),
+    );
+
+    await expect(init({ yes: true })).rejects.toThrow(
+      "The Clerk application link could not be verified",
+    );
+
+    expect(linkMod.link).toHaveBeenCalledWith({
+      skipIfLinked: true,
+      app: undefined,
+      cwd: iosCtx.cwd,
+      createIfMissing: undefined,
+      skipAutolink: true,
+    });
+    expect(pullMod.resolveEnvironmentKeys).not.toHaveBeenCalled();
+  });
+
   test("rejects --allow-dirty with --dry-run before project work", async () => {
     setup();
 

packages/cli-core/src/commands/init/index.ts

@@ -83,6 +83,7 @@ import {
 } from "./ios/apply.ts";
 import {
   applyIOSNativeRemoteSetup,
+  assertIOSAppIdPrefixBeforeApplicationCreation,
   prepareIOSNativeRemoteSetup,
   validateAppIdPrefix,
 } from "./ios/native-remote.ts";
@@ -435,19 +436,35 @@ export async function init(options: InitOptions = {}) {
   assertKeylessOnlyFlags(options, strategy);
 
   let authenticatedAppId: string | undefined;
+  let iosApplicationLinkChange: "created-and-linked" | "link-updated" | undefined;
   if (strategy === "authenticate") {
     setTelemetryStage("link");
+    if (agent && iosLocalSetup?.requiresLinkedApp && !iosProfile && !options.app) {
+      assertIOSAppIdPrefixBeforeApplicationCreation({
+        target: iosLocalSetup.nativeReadiness.target,
+        appIdPrefix: options.appIdPrefix,
+        ...(iosLocalSetup.unverifiedAppIdPrefixSuggestion
+          ? { unverifiedAppIdPrefixSuggestion: iosLocalSetup.unverifiedAppIdPrefixSuggestion }
+          : {}),
+      });
+    }
     bar();
-    const createIfMissing = agent
-      ? await deriveProjectName(ctx.cwd, bootstrap?.projectName)
+    const mayCreateApplication =
+      agent && (ctx.framework.dep !== "ios" || (!iosProfile && !options.app));
+    const createIfMissing = mayCreateApplication
+      ? await deriveProjectName(ctx.cwd, bootstrap?.projectName ?? iosLocalSetup?.targetName)
       : undefined;
-    authenticatedAppId = await authenticateAndLink(
+    const authenticated = await authenticateAndLink(
       ctx.cwd,
       options.app,
       createIfMissing,
       iosLocalSetup?.requiresLinkedApp === true,
       preauthenticatedIOSLabel,
     );
+    authenticatedAppId = authenticated.applicationId;
+    if (ctx.framework.dep === "ios") {
+      iosApplicationLinkChange = authenticated.applicationLinkChange;
+    }
   }
 
   let authenticatedKeysHandled = false;
@@ -529,6 +546,7 @@ export async function init(options: InitOptions = {}) {
       ...(iosLocalSetup.unverifiedAppIdPrefixSuggestion
         ? { unverifiedAppIdPrefixSuggestion: iosLocalSetup.unverifiedAppIdPrefixSuggestion }
         : {}),
+      ...(iosApplicationLinkChange ? { applicationLinkChange: iosApplicationLinkChange } : {}),
       agent,
       yes: options.yes === true,
     });
@@ -1095,15 +1113,18 @@ async function authenticateAndLink(
   createIfMissing: string | undefined,
   requireLinkedAppId: boolean,
   preauthenticatedLabel?: string,
-): Promise<string | undefined> {
+): Promise<{
+  applicationId?: string;
+  applicationLinkChange?: "created-and-linked" | "link-updated";
+}> {
   const label = preauthenticatedLabel ?? (await resolveAuthLabel());
   const profile = await resolveProfile(cwd);
 
   const alreadyOnRequestedApp = profile && (!app || profile.profile.appId === app);
 
   if (label && alreadyOnRequestedApp) {
     log.info(dim(`${label} · Linked to ${profile.profile.appId}`));
-    return profile.profile.appId;
+    return { applicationId: profile.profile.appId };
   }
 
   if (label) {
@@ -1131,7 +1152,17 @@ async function authenticateAndLink(
       code: ERROR_CODE.NOT_LINKED,
     });
   }
-  return linked?.profile.appId;
+  const applicationId = linked?.profile.appId;
+  const applicationLinkChange =
+    applicationId && !profile && !app && createIfMissing
+      ? ("created-and-linked" as const)
+      : applicationId && profile?.profile.appId !== applicationId
+        ? ("link-updated" as const)
+        : undefined;
+  return {
+    applicationId,
+    ...(applicationLinkChange ? { applicationLinkChange } : {}),
+  };
 }
 
 // --- Keyless app setup ---

packages/cli-core/src/commands/init/ios/native-remote.test.ts

@@ -392,25 +392,100 @@ describe("Clerk Native Application remote setup", () => {
     });
   });
 
-  test("requires an explicit prefix in agent mode instead of prompting", async () => {
+  test("offers an unverified Xcode suggestion in agent mode instead of prompting", async () => {
     const { api } = scriptedAPI({
       nativeReads: [nativeSettings(false)],
       registrationReads: [[]],
     });
 
-    await expect(
-      prepareIOSNativeRemoteSetup(
-        prepareOptions({
-          target: selectedTarget({ appIdPrefix: null }),
-          unverifiedAppIdPrefixSuggestion: {
-            source: "xcode-development-team",
-            value: "ABCDE12345",
-          },
-          agent: true,
+    const error = await prepareIOSNativeRemoteSetup(
+      prepareOptions({
+        target: selectedTarget({ appIdPrefix: null }),
+        unverifiedAppIdPrefixSuggestion: {
+          source: "xcode-development-team",
+          value: "ABCDE12345",
+        },
+        agent: true,
+      }),
+      { api, prompts: prompts() },
+    ).catch((cause: unknown) => cause);
+
+    expect(error).toBeInstanceOf(Error);
+    const message = (error as Error).message;
+    expect(message).toContain("ABCDE12345");
+    expect(message).toContain("Xcode DEVELOPMENT_TEAM");
+    expect(message).toContain("unverified suggestion");
+    expect(message).toContain("Ask the user whether to use ABCDE12345 or enter a different");
+    expect(message).toContain('--app-id-prefix "<confirmed_prefix>"');
+  });
+
+  test("offers partial literal entitlement evidence in agent mode", async () => {
+    const { api } = scriptedAPI({
+      nativeReads: [nativeSettings(false)],
+      registrationReads: [[]],
+    });
+
+    const error = await prepareIOSNativeRemoteSetup(
+      prepareOptions({
+        target: selectedTarget({
+          appIdPrefix: null,
+          appIdPrefixCandidates: [LOCAL_PREFIX],
         }),
-        { api, prompts: prompts() },
-      ),
-    ).rejects.toThrow("requires --app-id-prefix");
+        agent: true,
+      }),
+      { api, prompts: prompts() },
+    ).catch((cause: unknown) => cause);
+
+    expect(error).toBeInstanceOf(Error);
+    const message = (error as Error).message;
+    expect(message).toContain(LOCAL_PREFIX);
+    expect(message).toContain("literal App ID Prefix evidence");
+    expect(message).toContain("unverified suggestion");
+    expect(message).toContain(`Ask the user whether to use ${LOCAL_PREFIX} or enter a different`);
+  });
+
+  test("directs the agent to Apple Developer when no prefix suggestion exists", async () => {
+    const { api } = scriptedAPI({
+      nativeReads: [nativeSettings(false)],
+      registrationReads: [[]],
+    });
+
+    const error = await prepareIOSNativeRemoteSetup(
+      prepareOptions({
+        target: selectedTarget({ appIdPrefix: null }),
+        agent: true,
+      }),
+      { api, prompts: prompts() },
+    ).catch((cause: unknown) => cause);
+
+    expect(error).toBeInstanceOf(Error);
+    const message = (error as Error).message;
+    expect(message).toContain("requires --app-id-prefix");
+    expect(message).toContain("copy the value labeled App ID Prefix in Apple Developer");
+    expect(message).toContain('--app-id-prefix "<confirmed_prefix>"');
+  });
+
+  test("reports an application link that changed before a missing-prefix block", async () => {
+    const { api } = scriptedAPI({
+      nativeReads: [nativeSettings(false)],
+      registrationReads: [[]],
+    });
+
+    const error = await prepareIOSNativeRemoteSetup(
+      prepareOptions({
+        target: selectedTarget({ appIdPrefix: null }),
+        applicationLinkChange: "link-updated",
+        agent: true,
+      }),
+      { api, prompts: prompts() },
+    ).catch((cause: unknown) => cause);
+
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toContain("The project's Clerk application link was updated");
+    expect((error as Error).message).toContain(
+      "no Xcode or Clerk Native Application settings changes were written",
+    );
+    expect((error as Error).message).not.toContain("No local or remote setup changes were written");
   });
 
   test("blocks an explicit prefix that conflicts with a partial local candidate", () => {