@mpgd/cli 0.59.0 → 0.61.1

package/dist/native-shell-store-policy.js

@@ -1,10 +1,4 @@
-/**
- * Store-facing settings of the game-owned Capacitor shell: the iOS
- * Info.plist keys App Store Connect reads (export compliance, device
- * capabilities). The starter writes them into a newly generated project;
- * a production build only reports what an existing shell still lacks, so
- * game-owned native files are never rewritten behind the game's back.
- */
+import { notificationsMessagingPlugin } from './notifications-starter.js';
 /**
  * Adds the iOS keys every kit shell should ship with, keeping any value the
  * game already set:
@@ -814,3 +808,555 @@ export function inspectIosInfoPlistAds(plist, usesAds) {
     }
     return issues;
 }
+// iOS push (`--providers notifications`).
+/** The entitlements file of a kit shell's App target, in the App group. */
+export const iosPushEntitlementsFile = 'App.entitlements';
+/** Its `CODE_SIGN_ENTITLEMENTS` value, relative to the Xcode project directory (`ios/App`). */
+export const iosPushEntitlementsSetting = `App/${iosPushEntitlementsFile}`;
+/**
+ * The Push Notifications entitlement the Xcode capability writes. Apple:
+ * "Xcode sets the value of the entitlement based on your app's current
+ * provisioning profile", so `development` here signs as `production` with
+ * an App Store profile
+ * (https://developer.apple.com/documentation/bundleresources/entitlements/aps-environment).
+ */
+export const iosPushEntitlementsXml = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    '<dict>',
+    '\t<key>aps-environment</key>',
+    '\t<string>development</string>',
+    '</dict>',
+    '</plist>',
+    '',
+].join('\n');
+/**
+ * The AppDelegate methods `@capacitor-firebase/messaging` documents for iOS:
+ * the plugin observes `.capacitorDidRegisterForRemoteNotifications` and hands
+ * the APNs token to Firebase, so without them it never gets an FCM token.
+ * The plugin README's third method (`didReceiveRemoteNotification`) is left
+ * out: the kit sends no silent pushes, and plugin 8.5.2 never calls the
+ * completion handler it is given.
+ */
+export const iosAppDelegatePushForwardingSwift = [
+    '    // @capacitor-firebase/messaging reads the APNs token from these Capacitor',
+    '    // notifications (added by mpgd target init capacitor --providers notifications).',
+    '    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {',
+    '        NotificationCenter.default.post(name: .capacitorDidRegisterForRemoteNotifications, object: deviceToken)',
+    '    }',
+    '',
+    '    func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {',
+    '        NotificationCenter.default.post(name: .capacitorDidFailToRegisterForRemoteNotifications, object: error)',
+    '    }',
+];
+/** The call the scene delegate makes right after Capacitor's scene proxy (reference shell, #407). */
+const iosSceneDelegateColdStartCall = [
+    '// A killed-app tap is only in connectionOptions.notificationResponse.',
+    "// Capacitor 8.5's scene proxy replays URL contexts on capacitorViewDidAppear",
+    '// and does not read this, and @capacitor/ios 8.5.2 never does either.',
+    'forwardColdStartNotification(connectionOptions.notificationResponse)',
+];
+/** The scene delegate methods that replay a cold-start tap (reference shell, #407). */
+export const iosSceneDelegateColdStartSwift = [
+    '    /// Replays a cold-start notification response once plugins have registered',
+    "    /// with Capacitor's notification router. `load()` runs before",
+    '    /// `capacitorViewDidAppear`, which is how the scene proxy replays URL contexts.',
+    '    private func forwardColdStartNotification(_ response: UNNotificationResponse?) {',
+    '        guard let response else { return }',
+    '        var token: NSObjectProtocol?',
+    '        token = NotificationCenter.default.addObserver(',
+    '            forName: .capacitorViewDidAppear,',
+    '            object: nil,',
+    '            queue: .main',
+    '        ) { _ in',
+    '            if let token {',
+    '                NotificationCenter.default.removeObserver(token)',
+    '            }',
+    '            self.deliverColdStartNotification(response)',
+    '        }',
+    '    }',
+    '',
+    '    private func deliverColdStartNotification(_ response: UNNotificationResponse) {',
+    '        let center = UNUserNotificationCenter.current()',
+    '        if let delegate = center.delegate {',
+    '            delegate.userNotificationCenter?(center, didReceive: response, withCompletionHandler: {})',
+    '            return',
+    '        }',
+    '        guard let controller = window?.rootViewController as? CAPBridgeViewController,',
+    '              let bridge = controller.bridge else {',
+    '            return',
+    '        }',
+    '        bridge.notificationRouter.userNotificationCenter(',
+    '            center,',
+    '            didReceive: response,',
+    '            withCompletionHandler: {}',
+    '        )',
+    '    }',
+];
+/** Whether the shell's package.json installs the Firebase messaging plugin (`--providers notifications`). */
+export function shellUsesFirebaseMessaging(shellPackage) {
+    if (!isRecord(shellPackage)) {
+        return false;
+    }
+    return [shellPackage.dependencies, shellPackage.devDependencies].some((dependencies) => isRecord(dependencies) && dependencies[notificationsMessagingPlugin] !== undefined);
+}
+/**
+ * Swift source with comments and string literals blanked to spaces, so
+ * offsets stay the same and only code is matched. Nested block comments,
+ * multi-line strings and raw strings (`#"..."#`) are handled; an
+ * interpolation's code inside a string is blanked with it, and a
+ * single-line string that runs into a newline ends there, so one the
+ * scanner misreads cannot blank the rest of the file.
+ */
+export function stripSwiftCommentsAndStrings(source) {
+    let output = '';
+    let commentDepth = 0;
+    let lineComment = false;
+    /** The open string's closing delimiter, and whether `\` escapes in it. */
+    let closing;
+    for (let index = 0; index < source.length; index += 1) {
+        const character = source[index] ?? '';
+        const next = source[index + 1] ?? '';
+        const blank = character === '\n' ? '\n' : ' ';
+        if (lineComment) {
+            lineComment = character !== '\n';
+            output += blank;
+        }
+        else if (commentDepth > 0) {
+            if (character === '/' && next === '*') {
+                commentDepth += 1;
+                output += '  ';
+                index += 1;
+            }
+            else if (character === '*' && next === '/') {
+                commentDepth -= 1;
+                output += '  ';
+                index += 1;
+            }
+            else {
+                output += blank;
+            }
+        }
+        else if (closing !== undefined) {
+            if (!closing.raw && character === '\\' && next !== '' && next !== '\n') {
+                output += '  ';
+                index += 1;
+            }
+            else if (source.startsWith(closing.text, index)) {
+                output += ' '.repeat(closing.text.length);
+                index += closing.text.length - 1;
+                closing = undefined;
+            }
+            else {
+                if (character === '\n' && !closing.multiline) {
+                    closing = undefined;
+                }
+                output += blank;
+            }
+        }
+        else if (character === '/' && next === '/') {
+            lineComment = true;
+            output += '  ';
+            index += 1;
+        }
+        else if (character === '/' && next === '*') {
+            commentDepth = 1;
+            output += '  ';
+            index += 1;
+        }
+        else {
+            const opener = /^(#*)("""|")/u.exec(source.slice(index, index + 64));
+            if (opener === null || (opener[1] === '' && character !== '"')) {
+                output += character;
+                continue;
+            }
+            const hashes = opener[1] ?? '';
+            const quote = opener[2] ?? '"';
+            closing = { text: `${quote}${hashes}`, multiline: quote === '"""', raw: hashes !== '' };
+            output += ' '.repeat(opener[0].length);
+            index += opener[0].length - 1;
+        }
+    }
+    return output;
+}
+/**
+ * The offset of the `}` that closes the top-level `class <name>` whose
+ * inheritance clause names `conformance`, in source whose comments and
+ * strings are blanked, or undefined.
+ */
+function findSwiftClassClose(code, name, conformance) {
+    const declaration = new RegExp(`\\bclass\\s+${name}\\b([^{};]*)\\{`, 'gu');
+    for (const match of code.matchAll(declaration)) {
+        const open = (match.index ?? 0) + match[0].length - 1;
+        const before = code.slice(0, match.index ?? 0);
+        const depthBefore = (before.match(/\{/gu)?.length ?? 0) - (before.match(/\}/gu)?.length ?? 0);
+        if (depthBefore !== 0 || !new RegExp(`\\b${conformance}\\b`, 'u').test(match[1] ?? '')) {
+            continue;
+        }
+        let depth = 0;
+        for (let index = open; index < code.length; index += 1) {
+            if (code[index] === '{') {
+                depth += 1;
+            }
+            else if (code[index] === '}') {
+                depth -= 1;
+                if (depth === 0) {
+                    return index;
+                }
+            }
+        }
+        return undefined;
+    }
+    return undefined;
+}
+/** `lines` inserted before the class's closing brace, after one blank line. */
+function insertBeforeSwiftClassClose(source, close, lines) {
+    const newline = source.includes('\r\n') ? '\r\n' : '\n';
+    const head = source.slice(0, close).replace(/\s*$/u, '');
+    return `${head}${newline}${newline}${lines.join(newline)}${newline}${source.slice(close)}`;
+}
+/** The body of each `func` whose name or labels include `label`, in blanked source. */
+function swiftFunctionBodies(code, label) {
+    const bodies = [];
+    for (const match of code.matchAll(new RegExp(`\\bfunc\\b[^{}]*\\b${label}\\b[^{}]*\\{`, 'gu'))) {
+        const open = (match.index ?? 0) + match[0].length - 1;
+        let depth = 0;
+        for (let index = open; index < code.length; index += 1) {
+            if (code[index] === '{') {
+                depth += 1;
+            }
+            else if (code[index] === '}') {
+                depth -= 1;
+                if (depth === 0) {
+                    bodies.push(code.slice(open + 1, index));
+                    break;
+                }
+            }
+        }
+    }
+    return bodies;
+}
+/**
+ * Whether a Swift source's `didRegisterForRemoteNotificationsWithDeviceToken`
+ * hands the APNs token on: it posts `.capacitorDidRegisterForRemoteNotifications`
+ * (what the messaging plugin observes) or sets Firebase's `apnsToken` itself.
+ */
+export function swiftForwardsPushToken(source) {
+    return swiftFunctionBodies(stripSwiftCommentsAndStrings(source), 'didRegisterForRemoteNotificationsWithDeviceToken').some((body) => /\bcapacitorDidRegisterForRemoteNotifications\b|\.\s*apnsToken\s*=/u.test(body));
+}
+/** Whether a Swift source declares a scene delegate class. */
+export function swiftDeclaresSceneDelegate(source) {
+    return /\bclass\s+\w+\s*:[^{]*\bUIWindowSceneDelegate\b/u.test(stripSwiftCommentsAndStrings(source));
+}
+/** Whether a Swift source forwards the scene's cold-start notification response. */
+export function swiftForwardsColdStartNotification(source) {
+    return /\.\s*notificationResponse\b/u.test(stripSwiftCommentsAndStrings(source));
+}
+/**
+ * Adds the APNs registration forwarding (`iosAppDelegatePushForwardingSwift`)
+ * to the `AppDelegate` class. An AppDelegate that already forwards the token
+ * is returned unchanged; undefined when the class is not found or already
+ * implements a registration callback without the forwarding, which is left
+ * to the game.
+ */
+export function applyIosAppDelegatePushForwarding(source) {
+    if (swiftForwardsPushToken(source)) {
+        return source;
+    }
+    const code = stripSwiftCommentsAndStrings(source);
+    if (/\bdidRegisterForRemoteNotificationsWithDeviceToken\b|\bdidFailToRegisterForRemoteNotificationsWithError\b/u
+        .test(code)) {
+        return undefined;
+    }
+    const close = findSwiftClassClose(code, 'AppDelegate', 'UIApplicationDelegate');
+    return close === undefined
+        ? undefined
+        : insertBeforeSwiftClassClose(source, close, iosAppDelegatePushForwardingSwift);
+}
+/**
+ * Adds the cold-start notification forwarding of the kit reference shell
+ * (#407) to Capacitor's `SceneDelegate`: `import UserNotifications`, the
+ * call after `SceneDelegateProxy.shared.scene(_:willConnectTo:options:)`,
+ * and `iosSceneDelegateColdStartSwift`. A scene delegate that already reads
+ * `notificationResponse` is returned unchanged; undefined when it does not
+ * have Capacitor's layout, which is left to the game.
+ */
+export function applyIosSceneDelegateColdStartForwarding(source) {
+    if (swiftForwardsColdStartNotification(source)) {
+        return source;
+    }
+    const code = stripSwiftCommentsAndStrings(source);
+    const proxyCalls = [...code.matchAll(/SceneDelegateProxy\s*\.\s*shared\s*\.\s*scene\s*\(\s*scene\s*,\s*willConnectTo\s*:\s*session\s*,\s*options\s*:\s*connectionOptions\s*\)/gu)];
+    const capacitorImport = /^import[ \t]+Capacitor[ \t]*(?=\r?$)/mu.exec(code);
+    if (proxyCalls.length !== 1 || capacitorImport === null
+        || /\bforwardColdStartNotification\b|\bdeliverColdStartNotification\b/u.test(code)) {
+        return undefined;
+    }
+    const close = findSwiftClassClose(code, 'SceneDelegate', 'UIWindowSceneDelegate');
+    const call = proxyCalls[0];
+    if (close === undefined || call?.index === undefined || call.index > close) {
+        return undefined;
+    }
+    const newline = source.includes('\r\n') ? '\r\n' : '\n';
+    const lineStart = source.lastIndexOf('\n', call.index) + 1;
+    const indentation = /^[ \t]*/u.exec(source.slice(lineStart))?.[0] ?? '';
+    const lineEnd = code.indexOf('\n', call.index);
+    if (lineEnd === -1 || lineEnd > close || code.slice(call.index + call[0].length, lineEnd).trim() !== '') {
+        return undefined;
+    }
+    const callEnd = source[lineEnd - 1] === '\r' ? lineEnd - 1 : lineEnd;
+    const withMethods = insertBeforeSwiftClassClose(source, close, iosSceneDelegateColdStartSwift);
+    const withCall = `${withMethods.slice(0, callEnd)}${iosSceneDelegateColdStartCall.map((line) => `${newline}${indentation}${line}`).join('')}${withMethods.slice(callEnd)}`;
+    if (/^import[ \t]+UserNotifications[ \t]*(?=\r?$)/mu.test(code)) {
+        return withCall;
+    }
+    const importEnd = capacitorImport.index + capacitorImport[0].length;
+    return `${withCall.slice(0, importEnd)}${newline}import UserNotifications${withCall.slice(importEnd)}`;
+}
+/** The App target's Release `CODE_SIGN_ENTITLEMENTS`, without quotes, or undefined. */
+export function readIosAppReleaseEntitlements(project) {
+    for (const id of readAppTargetConfigurationIds(project)) {
+        const settings = locatePbxBuildSettings(project, id);
+        if (settings.name === 'Release') {
+            return readPbxSetting(project.slice(settings.start, settings.end), 'CODE_SIGN_ENTITLEMENTS');
+        }
+    }
+    return undefined;
+}
+function readPbxSetting(settings, name) {
+    const value = new RegExp(`(?:^|[\\s;{])${name}\\s*=\\s*([^;]+);`, 'u').exec(settings)?.[1];
+    return value?.trim().replace(/^"(.*)"$/u, '$1');
+}
+/**
+ * The entitlements path a `CODE_SIGN_ENTITLEMENTS` value names, relative to
+ * the Xcode project directory, or undefined when it uses another build
+ * setting the kit cannot resolve.
+ */
+export function resolveIosEntitlementsSetting(value) {
+    const relative = value.replace(/^\$[({](?:SRCROOT|PROJECT_DIR)[)}]\//u, '');
+    return relative.includes('$') || relative === '' ? undefined : relative;
+}
+/**
+ * Adds `App.entitlements` to the App group of a Capacitor-generated project
+ * and sets `CODE_SIGN_ENTITLEMENTS` in every App target build configuration.
+ * The file is not bundled (no build phase). A project that already points
+ * there is returned unchanged; undefined when the project has another layout
+ * or another entitlements file, which is left to the game.
+ */
+export function applyIosProjectPushEntitlements(project) {
+    try {
+        return addIosProjectPushEntitlements(project);
+    }
+    catch {
+        // An Xcode project this cannot read is left to the game, like any other layout.
+        return undefined;
+    }
+}
+function addIosProjectPushEntitlements(project) {
+    const configurationIds = readAppTargetConfigurationIds(project);
+    if (/\bCODE_SIGN_ENTITLEMENTS\s*\[/u.test(project)) {
+        // A per-SDK entitlements setting would override the one this adds.
+        return undefined;
+    }
+    const group = findAppGroup(project);
+    if (group === undefined || !project.includes('/* End PBXFileReference section */')) {
+        return undefined;
+    }
+    for (const id of configurationIds) {
+        const settings = locatePbxBuildSettings(project, id);
+        const current = readPbxSetting(project.slice(settings.start, settings.end), 'CODE_SIGN_ENTITLEMENTS');
+        if (current !== undefined && resolveIosEntitlementsSetting(current) !== iosPushEntitlementsSetting) {
+            return undefined;
+        }
+    }
+    let next = project;
+    if (!group.text.includes(`/* ${iosPushEntitlementsFile} */`)) {
+        const fileId = uniquePbxId(project, `${iosPushEntitlementsFile}:file`);
+        const edits = [
+            {
+                at: project.indexOf('/* End PBXFileReference section */'),
+                text: `\t\t${fileId} /* ${iosPushEntitlementsFile} */ = {isa = PBXFileReference; lastKnownFileType = text.plist.entitlements; path = ${iosPushEntitlementsFile}; sourceTree = "<group>"; };\n`,
+            },
+            { at: group.childrenEnd, text: `\t${fileId} /* ${iosPushEntitlementsFile} */,\n\t\t\t` },
+        ].sort((left, right) => right.at - left.at);
+        for (const edit of edits) {
+            next = `${next.slice(0, edit.at)}${edit.text}${next.slice(edit.at)}`;
+        }
+    }
+    for (const id of configurationIds) {
+        const settings = locatePbxBuildSettings(next, id);
+        const body = next.slice(settings.start, settings.end);
+        if (readPbxSetting(body, 'CODE_SIGN_ENTITLEMENTS') === undefined) {
+            next = `${next.slice(0, settings.start)}\n\t\t\t\tCODE_SIGN_ENTITLEMENTS = ${iosPushEntitlementsSetting};${body}${next.slice(settings.end)}`;
+        }
+    }
+    return next;
+}
+export const iosPushEntitlementStep = 'add the Push Notifications capability to the App target in '
+    + `Xcode, or create ios/App/App/${iosPushEntitlementsFile} with <key>aps-environment</key>`
+    + `<string>development</string> and set CODE_SIGN_ENTITLEMENTS = ${iosPushEntitlementsSetting} `
+    + "in the App target's Debug and Release build settings (Xcode signs the value from the "
+    + 'provisioning profile, production for the App Store)';
+export const iosPushTokenForwardingStep = 'add to the AppDelegate class: func application(_ '
+    + 'application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) '
+    + '{ NotificationCenter.default.post(name: .capacitorDidRegisterForRemoteNotifications, object: '
+    + 'deviceToken) } and func application(_ application: UIApplication, '
+    + 'didFailToRegisterForRemoteNotificationsWithError error: Error) { NotificationCenter.default.post('
+    + 'name: .capacitorDidFailToRegisterForRemoteNotifications, object: error) }';
+export const iosPushColdStartStep = 'copy forwardColdStartNotification and '
+    + 'deliverColdStartNotification from the mpgd-kit reference shell '
+    + '(apps/mobile-capacitor/ios/App/App/SceneDelegate.swift) into SceneDelegate, import '
+    + 'UserNotifications, and call forwardColdStartNotification(connectionOptions.notificationResponse) '
+    + 'right after SceneDelegateProxy.shared.scene(scene, willConnectTo: session, options: connectionOptions)';
+/**
+ * What a shell with `@capacitor-firebase/messaging` still lacks on iOS: the
+ * `aps-environment` entitlement on the App target's Release configuration,
+ * the AppDelegate's APNs token forwarding, and the scene delegate's
+ * cold-start tap forwarding (for a shell with a scene delegate). Each is an
+ * error: without the first two no push reaches the app, and without the
+ * third a tap on a notification while the app is not running opens it
+ * without the notification's route. An entitlement the kit cannot follow
+ * (`inspectIosPushEntitlement`) is a warning. The forwarding checks are
+ * textual: the token must be handed on inside
+ * `didRegisterForRemoteNotificationsWithDeviceToken`, and some App source
+ * must read `.notificationResponse`.
+ */
+export function inspectIosPushWiring(input) {
+    const issues = [];
+    const guide = ' (see the mpgd-kit Firebase guide, docs/FIREBASE_NOTIFICATIONS.md#4-ios).';
+    const entitlement = inspectIosPushEntitlement(input, guide);
+    if (entitlement !== undefined) {
+        issues.push(entitlement);
+    }
+    if (!input.swiftSources.some(swiftForwardsPushToken)) {
+        issues.push({
+            level: 'error',
+            message: 'The shell installs @capacitor-firebase/messaging, but no App Swift source forwards '
+                + 'the APNs device token to Capacitor, so the plugin never gets an FCM token: '
+                + `${iosPushTokenForwardingStep}${guide}`,
+        });
+    }
+    // A shell without scenes gets a cold-start tap through the notification
+    // center delegate; only a scene delegate must forward it.
+    if (input.swiftSources.some(swiftDeclaresSceneDelegate)
+        && !input.swiftSources.some(swiftForwardsColdStartNotification)) {
+        issues.push({
+            level: 'error',
+            message: 'The shell installs @capacitor-firebase/messaging, but its iOS SceneDelegate does '
+                + 'not forward connectionOptions.notificationResponse, so a tap on a notification while '
+                + "the app is not running opens the game without the notification's route: "
+                + `${iosPushColdStartStep}${guide}`,
+        });
+    }
+    return issues;
+}
+/**
+ * The Release configuration's `aps-environment` entitlement: an error when it
+ * is provably missing, a warning when the shell sets it in a way the kit
+ * cannot follow (an xcconfig, a per-SDK setting, another build setting, a
+ * build-setting value).
+ */
+function inspectIosPushEntitlement(input, guide) {
+    const unverifiable = (reason) => ({
+        level: 'warning',
+        message: `The kit cannot verify the iOS aps-environment entitlement: ${reason}; make sure the `
+            + `App target's Release signing includes it${guide}`,
+    });
+    let release;
+    try {
+        release = readIosAppReleaseSigning(input.project);
+    }
+    catch {
+        return unverifiable('the Xcode project could not be read');
+    }
+    if (release.conditional) {
+        return unverifiable('CODE_SIGN_ENTITLEMENTS is set per SDK');
+    }
+    if (release.entitlements === undefined && release.baseConfiguration) {
+        return unverifiable('the Release configuration has a base xcconfig that may set CODE_SIGN_ENTITLEMENTS');
+    }
+    const relative = release.entitlements === undefined
+        ? undefined
+        : resolveIosEntitlementsSetting(release.entitlements);
+    if (release.entitlements !== undefined && relative === undefined) {
+        return unverifiable(`CODE_SIGN_ENTITLEMENTS is ${release.entitlements}`);
+    }
+    const entitlements = relative === undefined ? undefined : input.readProjectFile(relative);
+    let value;
+    try {
+        value = entitlements === undefined
+            ? undefined
+            : readPlistTopLevelValue(entitlements, 'aps-environment')?.xml;
+    }
+    catch {
+        value = undefined;
+    }
+    if (value !== undefined && /^<string>\s*(?:development|production)\s*<\/string>$/u.test(value)) {
+        return undefined;
+    }
+    if (value !== undefined && /^<string>[^<]*\$[({]/u.test(value)) {
+        return unverifiable(`aps-environment is ${value}`);
+    }
+    return {
+        level: 'error',
+        message: 'The shell installs @capacitor-firebase/messaging, but the iOS App target has no '
+            + 'aps-environment entitlement in its Release configuration'
+            + `${release.entitlements === undefined ? '' : ` (${release.entitlements})`}, so APNs issues no `
+            + `device token and no push reaches the app: ${iosPushEntitlementStep}${guide}`,
+    };
+}
+/** The App target's Release signing settings that decide its entitlements file. */
+/**
+ * The Release signing settings that decide the App target's entitlements
+ * file: the target's own, else what it inherits from the project-level
+ * Release configuration. `baseConfiguration` is set when an xcconfig may
+ * supply or override the value; the entitlements are then unverifiable.
+ */
+function readIosAppReleaseSigning(project) {
+    const projectObject = findPbxObject(project, (body) => /\bisa\s*=\s*PBXProject\s*;/u.test(body));
+    const projectListId = /\bbuildConfigurationList\s*=\s*([A-F0-9]+)\b/u.exec(projectObject?.text ?? '')?.[1];
+    const projectList = projectListId === undefined
+        ? undefined
+        : findPbxObjectById(project, projectListId);
+    const levels = [
+        readAppTargetConfigurationIds(project),
+        projectList === undefined
+            ? []
+            : (readPbxList(project, projectList, 'buildConfigurations')?.ids ?? []),
+    ];
+    let baseConfiguration = false;
+    for (const ids of levels) {
+        for (const id of ids) {
+            const settings = locatePbxBuildSettings(project, id);
+            if (settings.name !== 'Release') {
+                continue;
+            }
+            const body = project.slice(settings.start, settings.end);
+            const entitlements = readPbxSetting(body, 'CODE_SIGN_ENTITLEMENTS');
+            const conditional = /\bCODE_SIGN_ENTITLEMENTS\s*\[/u.test(body);
+            if (entitlements !== undefined || conditional) {
+                // A target xcconfig outranks the project-level settings: the value
+                // found there may not be the one Xcode signs with.
+                return baseConfiguration
+                    ? { entitlements: undefined, conditional: false, baseConfiguration }
+                    : { entitlements, conditional, baseConfiguration };
+            }
+            baseConfiguration ||= /\bbaseConfigurationReference\s*=/u.test(findPbxObjectById(project, id)?.text.replace(body, '') ?? '');
+        }
+    }
+    return { entitlements: undefined, conditional: false, baseConfiguration };
+}
+/** The Firebase config file the messaging plugin reads from the app bundle. */
+export const iosFirebaseConfigFile = 'GoogleService-Info.plist';
+export function inspectIosFirebaseConfig(project) {
+    if (iosAppBundlesResource(project, iosFirebaseConfigFile)) {
+        return [];
+    }
+    return [{
+            level: 'warning',
+            message: `The shell installs @capacitor-firebase/messaging, but the iOS App target does not bundle `
+                + `${iosFirebaseConfigFile}; the plugin then leaves Firebase unconfigured and push fails closed. `
+                + 'Download it from the Firebase console and add it to the App target in Xcode.',
+        }];
+}

package/dist/play-internal-submission.d.ts

@@ -1,4 +1,5 @@
-import type { PlayPublisher } from './play-publisher-port.js';
+import type { PlayPublisher, PlayTrackRelease } from './play-publisher-port.js';
+import { type PlayNewReleaseStatus, type PlayReleaseRequest } from './play-release-options.js';
 import type { ImmutableNativeBuildRecord } from './release-state.js';
 export interface PlayInternalSubmissionInput {
   readonly record: ImmutableNativeBuildRecord;
@@ -10,23 +11,58 @@ export interface PlayInternalSubmissionInput {
   readonly resumeEditId?: string;
   /** Persist this edit ID before any upload begins, for later reconciliation. */
   readonly onEditCreated?: (editId: string) => Promise<void>;
+  /** Track, status, rollout fraction, notes and mapping; defaults to internal/completed. */
+  readonly release?: PlayReleaseRequest;
+  /** Required for production tracks and staged (inProgress) rollouts. */
+  readonly confirmProduction?: boolean;
+  /** Called before the kit re-commits a release as a draft for a never-published app. */
+  readonly onDraftAppFallback?: (track: string) => void;
   readonly signal?: AbortSignal;
 }
 export interface PlayInternalSubmissionResult {
   readonly status: 'committed';
   readonly packageName: string;
   readonly editId: string;
-  readonly track: 'internal';
+  readonly track: string;
+  /** The committed release's status; `draft` after a draft-app fallback. */
+  readonly releaseStatus: PlayNewReleaseStatus;
+  /** Play refused a non-draft release because the app was never published. */
+  readonly draftAppFallback: boolean;
   readonly versionCode: number;
   readonly bundleSha256: string;
   readonly alreadyCommitted: boolean;
 }
+/** The planned edit of a `--dry-run`: verified locally, no Google Play call made. */
+export interface PlaySubmissionPlan {
+  readonly dryRun: true;
+  readonly packageName: string;
+  readonly track: string;
+  readonly versionCode: number;
+  readonly bundleSha256: string;
+  readonly release: PlayTrackRelease;
+  readonly mapping?: {
+    readonly file: string;
+    readonly sha256: string;
+  };
+  readonly requiresConfirmProduction: boolean;
+  readonly operations: readonly string[];
+}
 export declare class PlaySubmissionUncertainError extends Error {
-  readonly stage: 'checkpoint' | 'upload' | 'track-update' | 'validate' | 'commit';
+  readonly stage: 'checkpoint' | 'upload' | 'deobfuscation-upload' | 'track-update' | 'validate' | 'commit';
   readonly editId: string;
-  constructor(stage: 'checkpoint' | 'upload' | 'track-update' | 'validate' | 'commit', editId: string);
+  constructor(stage: 'checkpoint' | 'upload' | 'deobfuscation-upload' | 'track-update' | 'validate' | 'commit', editId: string);
 }
 /** Submit only a previously inspected, immutable Android build record. */
 export declare function submitVerifiedAndroidBundle(input: PlayInternalSubmissionInput): Promise<PlayInternalSubmissionResult>;
+/** Verify the record and artifact, then describe the edit without calling Google Play. */
+export declare function planVerifiedAndroidBundleSubmission(input: Omit<PlayInternalSubmissionInput, 'serviceAccountFile'>): Promise<PlaySubmissionPlan>;
 /** Internal injection point for credential-free SDK contract tests. */
 export declare function submitVerifiedAndroidBundleWithPublisher(input: PlayInternalSubmissionInput, publisher: PlayPublisher, requestRootUrl?: string): Promise<PlayInternalSubmissionResult>;
+/**
+* The release already on the track matches what this request would create:
+* the rollout fraction (a draft-app fallback has none) and, when given, the
+* release notes in any order.
+*/
+export declare function matchesRequestedRelease(observed: PlayTrackRelease, request: PlayReleaseRequest, observedStatus: PlayNewReleaseStatus): boolean;
+export declare function isHttpStatus(error: unknown, status: number): boolean;
+export declare function isDefinitiveHttpError(error: unknown): boolean;