@mpgd/cli 0.59.0 → 0.61.1

package/dist/capacitor-shell-starter.d.ts

@@ -76,6 +76,14 @@ export interface CapacitorShellStarterPlan {
     readonly version: string;
   }[];
   /**
+  * The Firebase Crashlytics plugin (`--providers crash-reporting`) the plan
+  * installs into the shell; empty when crash reporting is not requested.
+  */
+  readonly crashReportingPlugins: readonly {
+    readonly packageName: string;
+    readonly version: string;
+  }[];
+  /**
   * Store wiring the plan could not write or confirm: a missing or game-owned
   * gateway that does not register the plugin, or a store plugin the shell
   * keeps although it is no longer requested. Printed; game source is never
@@ -117,6 +125,22 @@ export declare const androidManifestBackupAttributes: readonly (readonly [string
 * the result is stable across repeated runs.
 */
 export declare function applyAndroidManifestBackupPolicy(manifest: string): string;
+/**
+* iOS push wiring of a freshly generated project (`--providers notifications`):
+* the `aps-environment` entitlement on the App target, the AppDelegate's
+* APNs registration forwarding, and the reference shell's cold-start tap
+* forwarding in SceneDelegate (#407). An existing game-owned project is never
+* rewritten; the initializer and the production build report what it lacks.
+* Whatever this cannot place in an unexpected layout is printed as the
+* manual step. Exported for the CLI's tests.
+*/
+export declare function materializeIosPushWiring(gameRoot: string): void;
+/**
+* The initializer's warnings for an existing, game-owned iOS project that
+* lacks the push wiring: each names the manual step. Empty when the shell has
+* no iOS project yet (the run generates it with the wiring) or lacks nothing.
+*/
+export declare function iosPushWiringWarnings(gameRoot: string): readonly string[];
 /** Fail closed when a Release plist hardcodes values independently of Xcode build settings. */
 export declare function assertIosReleasePlistIdentity(source: string): void;
 export declare function assertAndroidReleaseDisplayName(shellApp: string, expectedDisplayName: string): void;

package/dist/capacitor-shell-starter.js

@@ -6,7 +6,9 @@ import { fileURLToPath } from 'node:url';
 import { DOMParser } from '@xmldom/xmldom';
 import { satisfies, valid, validRange } from 'semver';
 import { capacitorGatewayRegistersNotifications, conflictingPushPlugin, notificationsCapacitorGatewayModules, notificationsCapacitorGateways, notificationsCapacitorSupportFiles, notificationsCapacitorTemplateSupportFiles, notificationsCapacitorTemplateSupportImporters, notificationsGameDependencies, notificationsMessagingFirebaseRange, notificationsMessagingPlugin, notificationsProviderId, notificationsShellPlugins, sourceReferencesRelativeModule, wireCapacitorGatewayNotifications, } from './notifications-starter.js';
-import { addIosAppResource, applyAndroidManifestAdId, applyAndroidManifestOrientation, applyIosInfoPlistOrientation, applyIosInfoPlistStorePolicy, applyIosProjectDeviceFamily, iosAppPrivacyManifestFile, iosAppPrivacyManifestXml, isRecord, readGameAdvertisingIdPolicy, readGameNativeOrientation, readIosDeviceFamily, shellUsesAdMob, } from './native-shell-store-policy.js';
+import { crashReportingPlugin, crashReportingProviderId, crashReportingRemovalWarning, materializeAndroidCrashlytics, planCrashReportingProvider, } from './crash-reporting-starter.js';
+import { addIosAppResource, applyAndroidManifestAdId, applyAndroidManifestOrientation, applyIosAppDelegatePushForwarding, applyIosInfoPlistOrientation, applyIosInfoPlistStorePolicy, applyIosProjectDeviceFamily, applyIosProjectPushEntitlements, applyIosSceneDelegateColdStartForwarding, inspectIosPushWiring, iosAppPrivacyManifestFile, iosAppPrivacyManifestXml, iosPushEntitlementsFile, iosPushEntitlementsXml, isRecord, readGameAdvertisingIdPolicy, readGameNativeOrientation, readIosDeviceFamily, shellUsesAdMob, } from './native-shell-store-policy.js';
+import { readIosPushWiringInput } from './native-shell-ios-push-files.js';
 import { isNonPublicServiceHostname } from './production-target-readiness.js';
 import { assertAndroidSettingsAppProject, assertAndroidSettingsNoAppRemap, assertIosReleaseInfoPlistExpansion, assertIosReleasePackagingSettings, assertIosReleaseProductName, assertNativeShellIdentity, hasAndroidDisplayNameResourceOverride, hasAndroidManifestSourceSetOverride, hasAndroidResourceSourceSetOverride, hasGradleIdentityMutation, hasGradleTaskAction, maskGradleStrings, readIosAppTargetId, readIosReleaseInfoPlist, stripGradleComments, } from './native-shell-identity.js';
 const shellPath = 'apps/mobile-capacitor';
@@ -262,6 +264,19 @@ export function planCapacitorShellStarter(input) {
         ...(notifications?.files ?? []),
     ];
     const notificationPlugins = notifications?.shellPlugins ?? [];
+    const existingShellDependencies = packageContent === undefined
+        ? undefined
+        : requireObject(parseJsonObject(packageContent, 'existing shell package').dependencies, 'existing shell dependencies');
+    const crashReporting = requestedProviderIds.includes(crashReportingProviderId)
+        ? planCrashReportingProvider({ gameRoot, shellPath, existingShellDependencies, warnings })
+        : undefined;
+    const crashReportingPlugins = crashReporting?.shellPlugins ?? [];
+    const crashReportingWarning = crashReporting === undefined && existingShellDependencies !== undefined
+        ? crashReportingRemovalWarning(existingShellDependencies)
+        : undefined;
+    if (crashReportingWarning !== undefined) {
+        warnings.push(crashReportingWarning);
+    }
     if (packageContent !== undefined) {
         const existingShellDependencies = requireObject(parseJsonObject(packageContent, 'existing shell package').dependencies, 'existing shell dependencies');
         for (const plugin of capacitorShellProviderPlugins) {
@@ -310,6 +325,7 @@ export function planCapacitorShellStarter(input) {
         '@mpgd/capacitor-game-services': pluginVersion,
         ...Object.fromEntries(providerPlugins.map((plugin) => [plugin.packageName, plugin.version])),
         ...Object.fromEntries(notificationPlugins.map((plugin) => [plugin.packageName, plugin.version])),
+        ...Object.fromEntries(crashReportingPlugins.map((plugin) => [plugin.packageName, plugin.version])),
     };
     if (packageContent !== undefined) {
         assertCompatibleExistingPackage(packageContent, shellDependencies, capacitorVersion, typescriptVersion);
@@ -356,7 +372,7 @@ export function planCapacitorShellStarter(input) {
                         typescript: typescriptVersion,
                     },
                 })
-                : withPackageDependencies(packageContent, [...providerPlugins, ...notificationPlugins]),
+                : withPackageDependencies(packageContent, [...providerPlugins, ...notificationPlugins, ...crashReportingPlugins]),
         },
         {
             path: `${shellPath}/capacitor.config.ts`,
@@ -384,6 +400,7 @@ export function planCapacitorShellStarter(input) {
                 displayName: input.displayName,
                 requestedProviderIds,
                 ...(providerPlugins.length === 0 && notificationPlugins.length === 0
+                    && crashReporting === undefined
                     ? {}
                     : {
                         providers: {
@@ -403,6 +420,9 @@ export function planCapacitorShellStarter(input) {
                                         platforms: ['android', 'ios'],
                                     },
                                 }),
+                            ...(crashReporting === undefined
+                                ? {}
+                                : { [crashReportingProviderId]: crashReporting.manifestEntry }),
                         },
                     }),
                 ...(requestedBackendUrl === undefined ? {} : { backendUrl: requestedBackendUrl }),
@@ -427,8 +447,9 @@ export function planCapacitorShellStarter(input) {
                 '@capacitor-firebase/messaging and @capacitor/local-notifications (never',
                 `${conflictingPushPlugin}, which claims the same iOS push handler).`,
                 'Notifications also need the Firebase files (google-services.json,',
-                'GoogleService-Info.plist) and the iOS Push Notifications capability; see',
-                'the mpgd-kit Firebase guide. A plugin never reports a feature as',
+                'GoogleService-Info.plist) and an APNs key in Firebase; an iOS project',
+                'generated with them gets the push entitlement and the AppDelegate and',
+                'SceneDelegate forwarding. See the mpgd-kit Firebase guide. A plugin never reports a feature as',
                 'available on its own; the gateway registers the store provider, and the',
                 'store answers configuration-required until the plugin and products exist.',
                 'Production builds require a real game-owned backend when grants are enabled.',
@@ -539,6 +560,7 @@ export function planCapacitorShellStarter(input) {
         nativePlatformsToAdd,
         providerPlugins,
         notificationPlugins,
+        crashReportingPlugins,
         warnings,
     };
 }
@@ -660,9 +682,15 @@ export function materializeCapacitorShellStarter(plan, runner = { run: runComman
                 materializeAndroidAdvertisingRenderer(plan.gameRoot);
             }
             materializeAndroidStorePolicy(plan.gameRoot);
+            if (plan.crashReportingPlugins.length > 0) {
+                materializeAndroidCrashlytics(path.join(plan.gameRoot, shellPath));
+            }
         }
         if (platform === 'ios' && generatedNow) {
             materializeIosStorePolicy(plan.gameRoot);
+            if (plan.notificationPlugins.length > 0) {
+                materializeIosPushWiring(plan.gameRoot);
+            }
         }
         if (platform === 'ios') {
             materializeIosArchiveScheme(plan.gameRoot);
@@ -682,7 +710,7 @@ export function materializeCapacitorShellStarter(plan, runner = { run: runComman
     // sync so the store plugin's native code joins the shell.
     for (const platform of ['android', 'ios']) {
         if ((plan.providerPlugins.some((plugin) => plugin.platform === platform)
-            || plan.notificationPlugins.length > 0)
+            || plan.notificationPlugins.length > 0 || plan.crashReportingPlugins.length > 0)
             && !plan.nativePlatformsToAdd.includes(platform)
             && existsSync(path.join(plan.gameRoot, shellPath, platform))) {
             runner.run('pnpm', ['--dir', shellPath, 'cap', 'sync', platform], plan.gameRoot);
@@ -851,6 +879,67 @@ function materializeIosStorePolicy(gameRoot) {
         writeFileSync(projectFile, next);
     }
 }
+/**
+ * iOS push wiring of a freshly generated project (`--providers notifications`):
+ * the `aps-environment` entitlement on the App target, the AppDelegate's
+ * APNs registration forwarding, and the reference shell's cold-start tap
+ * forwarding in SceneDelegate (#407). An existing game-owned project is never
+ * rewritten; the initializer and the production build report what it lacks.
+ * Whatever this cannot place in an unexpected layout is printed as the
+ * manual step. Exported for the CLI's tests.
+ */
+export function materializeIosPushWiring(gameRoot) {
+    const projectFile = safeDestination(gameRoot, `${shellPath}/ios/App/App.xcodeproj/project.pbxproj`);
+    const project = readFileSync(projectFile, 'utf8');
+    const withEntitlements = applyIosProjectPushEntitlements(project);
+    if (withEntitlements !== undefined) {
+        const entitlementsFile = safeDestination(gameRoot, `${shellPath}/ios/App/App/${iosPushEntitlementsFile}`);
+        if (!existsSync(entitlementsFile)) {
+            writeFileSync(entitlementsFile, iosPushEntitlementsXml, { flag: 'wx' });
+        }
+        if (withEntitlements !== project) {
+            writeFileSync(projectFile, withEntitlements);
+        }
+    }
+    for (const [name, apply] of [
+        ['AppDelegate.swift', applyIosAppDelegatePushForwarding],
+        ['SceneDelegate.swift', applyIosSceneDelegateColdStartForwarding],
+    ]) {
+        const file = safeDestination(gameRoot, `${shellPath}/ios/App/App/${name}`);
+        if (!existsSync(file) || !lstatSync(file).isFile()) {
+            continue;
+        }
+        const source = readFileSync(file, 'utf8');
+        let next;
+        try {
+            next = apply(source);
+        }
+        catch {
+            // Left to the game; the inspection below prints the step.
+            next = undefined;
+        }
+        if (next !== undefined && next !== source) {
+            writeFileSync(file, next);
+        }
+    }
+    for (const issue of readIosPushWiringIssues(gameRoot) ?? []) {
+        console.warn(`[mpgd] The generated iOS project has an unexpected layout: ${issue.message}`);
+    }
+}
+/**
+ * The initializer's warnings for an existing, game-owned iOS project that
+ * lacks the push wiring: each names the manual step. Empty when the shell has
+ * no iOS project yet (the run generates it with the wiring) or lacks nothing.
+ */
+export function iosPushWiringWarnings(gameRoot) {
+    return (readIosPushWiringIssues(gameRoot) ?? []).map((issue) => `${shellPath}/ios is game-owned and not rewritten: ${issue.message}`);
+}
+/** What the shell's iOS project lacks for push, or undefined when it has no project yet. */
+function readIosPushWiringIssues(gameRoot) {
+    safeDestination(gameRoot, `${shellPath}/ios/App`);
+    const input = readIosPushWiringInput(path.join(gameRoot, shellPath, 'ios/App'));
+    return input === undefined ? undefined : inspectIosPushWiring(input);
+}
 /**
  * Orientation of a freshly generated Android project's launcher activity,
  * `android:appCategory="game"`, and the advertising ID permission (declared
@@ -2223,6 +2312,7 @@ function assertCompatibleExistingPackage(source, shellDependencies, capacitorVer
     const providerPackages = new Set([
         ...capacitorShellProviderPlugins.map((plugin) => plugin.packageName),
         ...notificationsShellPlugins,
+        crashReportingPlugin,
     ]);
     for (const [name, version] of Object.entries(shellDependencies)) {
         // A store plugin the shell does not list yet is added by the plan. One it
@@ -3069,10 +3159,12 @@ function planNotificationsProvider(input) {
     }
     if (readExisting(safeDestination(gameRoot, `${shellPath}/ios/App/App/GoogleService-Info.plist`))
         === undefined) {
-        warnings.push(`iOS push needs ${shellPath}/ios/App/App/GoogleService-Info.plist, the Push Notifications `
-            + 'capability, an APNs key uploaded to Firebase, and the AppDelegate forwarding the '
-            + 'messaging plugin documents (see the mpgd-kit Firebase guide).');
+        warnings.push(`iOS push needs ${shellPath}/ios/App/App/GoogleService-Info.plist in the App target and an `
+            + 'APNs key uploaded to Firebase (see the mpgd-kit Firebase guide).');
     }
+    // A project this run generates gets the entitlement and the forwarding; an
+    // existing one is game-owned, so only the steps it still needs are printed.
+    warnings.push(...iosPushWiringWarnings(gameRoot));
     return {
         shellPlugins: shellPlugins.map(({ packageName, version }) => ({ packageName, version })),
         gameDependencies: gamePackages,

package/dist/crash-reporting-starter.d.ts

@@ -0,0 +1,99 @@
+import { type NativeShellPolicyIssue } from './native-shell-store-policy.js';
+export declare const crashReportingProviderId = "crash-reporting";
+/** The native plugin installed into the shell. */
+export declare const crashReportingPlugin = "@capacitor-firebase/crashlytics";
+/** The plugin version this CLI installs when the shell does not list one yet. */
+export declare const crashReportingPluginVersion = "8.5.2";
+/**
+* The Crashlytics Gradle plugin, which writes the build ID the Crashlytics
+* Android SDK requires at startup and uploads R8 mapping files. 3.0.8 needs
+* AGP 8.1+, Gradle 8.0+, and the Google services plugin 4.4.1+
+* (https://firebase.google.com/docs/crashlytics/android/get-started).
+*/
+export declare const crashlyticsGradlePluginVersion = "3.0.8";
+/** The manual Android steps for a shell whose Gradle files the CLI does not rewrite. */
+export declare const crashReportingAndroidSteps: readonly string[];
+/**
+* The iOS steps the CLI leaves to the game: the plugin captures crashes once
+* `GoogleService-Info.plist` is in the App target, but readable native stack
+* traces need the dSYMs uploaded (docs/CRASH_REPORTING.md#symbols).
+*/
+export declare const crashReportingIosSteps: readonly string[];
+export interface PlannedCrashReporting {
+  /** The plugin the plan installs into the shell, at the shell's version or this CLI's. */
+  readonly shellPlugins: readonly {
+    readonly packageName: string;
+    readonly version: string;
+  }[];
+  /** `mpgd.native-shell.json` `providers['crash-reporting']`. */
+  readonly manifestEntry: Readonly<Record<string, unknown>>;
+}
+/**
+* Plan the crash-reporting provider before anything is written. Refused when
+* the game's adapter has no crash reporter, when the plugin version is outside
+* the adapter's peer range, or when the shell already has an Android project
+* without the Crashlytics Gradle plugin: the Crashlytics SDK throws at startup
+* without the build ID that plugin writes, so the plugin is never installed
+* into such a project.
+*/
+export declare function planCrashReportingProvider(input: {
+  readonly gameRoot: string;
+  readonly shellPath: string;
+  readonly existingShellDependencies: Readonly<Record<string, unknown>> | undefined;
+  readonly warnings: string[];
+}): PlannedCrashReporting;
+/** Whether an Xcode project runs the Crashlytics dSYM upload script or `upload-symbols`. */
+export declare function iosProjectUploadsCrashlyticsSymbols(project: string): boolean;
+/** A warning for a shell that still lists the plugin although crash reporting is not requested. */
+export declare function crashReportingRemovalWarning(existingShellDependencies: Readonly<Record<string, unknown>>): string | undefined;
+/** Whether both Android Gradle files apply the Crashlytics Gradle plugin (comments ignored). */
+export declare function androidShellHasCrashlytics(shellRoot: string): boolean;
+export declare function androidRootGradleHasCrashlytics(source: string): boolean;
+/**
+* Whether the app module applies the Crashlytics Gradle plugin: `apply
+* plugin:`, or a plugins-block `id` that is not declared `apply false` (that
+* only puts the plugin on the classpath, as the root project does).
+*/
+export declare function androidAppGradleHasCrashlytics(source: string): boolean;
+/**
+* Add the Crashlytics Gradle plugin classpath next to the Google services
+* classpath of the Capacitor template's root `build.gradle`. Returns the
+* source unchanged when it is already there, and `undefined` for a layout the
+* template does not produce.
+*/
+export declare function applyAndroidRootGradleCrashlytics(source: string): string | undefined;
+/**
+* Apply the Crashlytics Gradle plugin right after the Google services plugin
+* in the Capacitor template's app `build.gradle`, inside its
+* `google-services.json` check: without that file Firebase does not start, so
+* the Crashlytics SDK and its build ID check stay off too. Returns the source
+* unchanged when it is already applied, and `undefined` for another layout.
+*/
+export declare function applyAndroidAppGradleCrashlytics(source: string): string | undefined;
+/**
+* Wire the Crashlytics Gradle plugin into a freshly generated Android project.
+* Both files are checked before either is written; a layout the template does
+* not produce is refused with the manual steps.
+*/
+export declare function materializeAndroidCrashlytics(shellRoot: string): void;
+/** Whether the shell's package.json installs the Crashlytics plugin (`--providers crash-reporting`). */
+export declare function shellUsesCrashlytics(shellPackage: unknown): boolean;
+/**
+* Store-policy preflight for a shell that installs the Crashlytics plugin.
+* Errors fail a production build (`reportNativeStorePolicy`); other profiles
+* print them.
+*
+* - Android: `android/app/google-services.json` must be present (without it
+*   Firebase does not start and the release reports nothing), and the app
+*   module must apply the Crashlytics Gradle plugin (without its build ID the
+*   Crashlytics SDK stops the app at startup once Firebase starts).
+* - iOS: the App target must bundle `GoogleService-Info.plist`; without it
+*   Firebase does not start and the plugin still calls Crashlytics.
+*/
+export declare function inspectCrashReportingShell(input: {
+  readonly platform: 'android' | 'ios';
+  readonly shellApp: string;
+  readonly shellPackage: unknown;
+  /** The App target's `project.pbxproj` source, for iOS. */
+  readonly iosProject?: string;
+}): readonly NativeShellPolicyIssue[];

package/dist/crash-reporting-starter.js

@@ -0,0 +1,271 @@
+import { existsSync, lstatSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { satisfies, valid, validRange } from 'semver';
+import { stripGradleComments } from './native-shell-identity.js';
+import { iosAppBundlesResource } from './native-shell-store-policy.js';
+// `mpgd target init capacitor --providers crash-reporting`: Firebase
+// Crashlytics in the game-owned Capacitor shell. The shell gets the native
+// plugin `@capacitor-firebase/crashlytics`, and a freshly generated Android
+// project gets the Crashlytics Gradle plugin. The game itself is unchanged:
+// `@mpgd/adapter-capacitor` reaches the native plugin by its registered name
+// and exposes it as `gateway.crashReporter` (docs/CRASH_REPORTING.md).
+export const crashReportingProviderId = 'crash-reporting';
+/** The native plugin installed into the shell. */
+export const crashReportingPlugin = '@capacitor-firebase/crashlytics';
+/** The plugin version this CLI installs when the shell does not list one yet. */
+export const crashReportingPluginVersion = '8.5.2';
+/**
+ * The Crashlytics Gradle plugin, which writes the build ID the Crashlytics
+ * Android SDK requires at startup and uploads R8 mapping files. 3.0.8 needs
+ * AGP 8.1+, Gradle 8.0+, and the Google services plugin 4.4.1+
+ * (https://firebase.google.com/docs/crashlytics/android/get-started).
+ */
+export const crashlyticsGradlePluginVersion = '3.0.8';
+const crashlyticsGradleClasspath = `com.google.firebase:firebase-crashlytics-gradle:${crashlyticsGradlePluginVersion}`;
+const crashlyticsGradlePluginId = 'com.google.firebase.crashlytics';
+const androidRootGradle = 'android/build.gradle';
+const androidAppGradle = 'android/app/build.gradle';
+/** The manual Android steps for a shell whose Gradle files the CLI does not rewrite. */
+export const crashReportingAndroidSteps = Object.freeze([
+    `In android/build.gradle, add classpath '${crashlyticsGradleClasspath}' to buildscript.dependencies, next to the google-services classpath (4.4.1 or later).`,
+    `In android/app/build.gradle, add apply plugin: '${crashlyticsGradlePluginId}' right after apply plugin: 'com.google.gms.google-services', inside the same google-services.json check.`,
+]);
+/**
+ * The iOS steps the CLI leaves to the game: the plugin captures crashes once
+ * `GoogleService-Info.plist` is in the App target, but readable native stack
+ * traces need the dSYMs uploaded (docs/CRASH_REPORTING.md#symbols).
+ */
+export const crashReportingIosSteps = Object.freeze([
+    'Upload dSYMs for every App Store build: add the Crashlytics run script build phase '
+        + '("${BUILD_DIR%/Build/*}/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/run") as the '
+        + 'last phase of the App target, or run upload-symbols after each archive; see '
+        + 'docs/CRASH_REPORTING.md in mpgd-kit.',
+]);
+/**
+ * Plan the crash-reporting provider before anything is written. Refused when
+ * the game's adapter has no crash reporter, when the plugin version is outside
+ * the adapter's peer range, or when the shell already has an Android project
+ * without the Crashlytics Gradle plugin: the Crashlytics SDK throws at startup
+ * without the build ID that plugin writes, so the plugin is never installed
+ * into such a project.
+ */
+export function planCrashReportingProvider(input) {
+    const adapterFile = path.join(input.gameRoot, 'node_modules/@mpgd/adapter-capacitor/package.json');
+    const adapter = JSON.parse(readFileSync(adapterFile, 'utf8'));
+    const adapterExports = adapter.exports;
+    if (typeof adapterExports !== 'object' || adapterExports === null
+        || adapterExports['./crash-reporting'] === undefined) {
+        throw new Error(`--providers ${crashReportingProviderId} needs the crash reporter of @mpgd/adapter-capacitor, `
+            + `which the game's ${String(adapter.version)} does not have; upgrade the game's kit `
+            + 'packages (mpgd kit upgrade) first.');
+    }
+    const listed = input.existingShellDependencies?.[crashReportingPlugin];
+    if (listed !== undefined && (typeof listed !== 'string' || valid(listed) === null)) {
+        throw new Error(`The shell lists ${crashReportingPlugin} as ${String(listed)}; pin an exact version before rerunning.`);
+    }
+    const version = typeof listed === 'string' ? listed : crashReportingPluginVersion;
+    const peers = typeof adapter.peerDependencies === 'object' && adapter.peerDependencies !== null
+        ? adapter.peerDependencies
+        : {};
+    const range = peers[crashReportingPlugin];
+    if (typeof range === 'string' && validRange(range) !== null
+        && !satisfies(version, range, { includePrerelease: true })) {
+        throw new Error(`@mpgd/adapter-capacitor ${String(adapter.version)} needs ${crashReportingPlugin} ${range}, `
+            + `but the shell would get ${version}; align the shell's version before rerunning.`);
+    }
+    const shellRoot = path.join(input.gameRoot, input.shellPath);
+    if (existsSync(path.join(shellRoot, 'android'))
+        && !androidShellHasCrashlytics(shellRoot)) {
+        throw new Error(`--providers ${crashReportingProviderId} installs Firebase Crashlytics, whose Android SDK `
+            + 'stops the app at startup unless the Crashlytics Gradle plugin is applied. The existing '
+            + 'Android project is game-owned and is not rewritten; first:\n'
+            + crashReportingAndroidSteps.map((step) => `- ${step}`).join('\n')
+            + '\nthen rerun.');
+    }
+    // Without the Firebase files Firebase does not start. Android then reports
+    // not-configured; the iOS plugin only logs it and still calls Crashlytics,
+    // so the plist must ship whenever the plugin does.
+    for (const [file, platform] of [
+        ['android/app/google-services.json', 'Android'],
+        ['ios/App/App/GoogleService-Info.plist', 'iOS'],
+    ]) {
+        if (!existsSync(path.join(shellRoot, file))) {
+            input.warnings.push(`${crashReportingProviderId}: ${platform} crash reports need ${input.shellPath}/${file} from the `
+                + 'Firebase console (the same file notifications use); add it before a release build.');
+        }
+    }
+    const iosProject = path.join(shellRoot, 'ios/App/App.xcodeproj/project.pbxproj');
+    if (!existsSync(iosProject) || !iosProjectUploadsCrashlyticsSymbols(readFileSync(iosProject, 'utf8'))) {
+        input.warnings.push(`${crashReportingProviderId}: on iOS, ${crashReportingIosSteps.join(' ')}`);
+    }
+    return {
+        shellPlugins: [{ packageName: crashReportingPlugin, version }],
+        manifestEntry: {
+            packages: { [crashReportingPlugin]: version },
+            platforms: ['android', 'ios'],
+        },
+    };
+}
+/** Whether an Xcode project runs the Crashlytics dSYM upload script or `upload-symbols`. */
+export function iosProjectUploadsCrashlyticsSymbols(project) {
+    return /Crashlytics\/run\b|\bupload-symbols\b/u.test(project);
+}
+/** A warning for a shell that still lists the plugin although crash reporting is not requested. */
+export function crashReportingRemovalWarning(existingShellDependencies) {
+    return existingShellDependencies[crashReportingPlugin] === undefined
+        ? undefined
+        : `The shell still lists ${crashReportingPlugin} although ${crashReportingProviderId} is no `
+            + 'longer requested; the initializer never removes a plugin, so remove it from the shell '
+            + 'package (and the Crashlytics Gradle plugin) and resync if the game stopped reporting crashes.';
+}
+/** Whether both Android Gradle files apply the Crashlytics Gradle plugin (comments ignored). */
+export function androidShellHasCrashlytics(shellRoot) {
+    const read = (relative) => {
+        const file = path.join(shellRoot, relative);
+        return existsSync(file) && lstatSync(file).isFile() ? readFileSync(file, 'utf8') : undefined;
+    };
+    const root = read(androidRootGradle);
+    const app = read(androidAppGradle);
+    return root !== undefined && app !== undefined
+        && androidRootGradleHasCrashlytics(root) && androidAppGradleHasCrashlytics(app);
+}
+export function androidRootGradleHasCrashlytics(source) {
+    return /['"]com\.google\.firebase:firebase-crashlytics-gradle:[^'"]+['"]|\bid\s*\(?\s*['"]com\.google\.firebase\.crashlytics['"]/u
+        .test(stripGradleComments(source));
+}
+/**
+ * Whether the app module applies the Crashlytics Gradle plugin: `apply
+ * plugin:`, or a plugins-block `id` that is not declared `apply false` (that
+ * only puts the plugin on the classpath, as the root project does).
+ */
+export function androidAppGradleHasCrashlytics(source) {
+    const clean = stripGradleComments(source);
+    if (/\bapply\s+plugin\s*:\s*['"]com\.google\.firebase\.crashlytics['"]/u.test(clean)) {
+        return true;
+    }
+    return clean.split('\n').some((line) => /\bid\s*\(?\s*['"]com\.google\.firebase\.crashlytics['"]/u.test(line)
+        && !/\bapply\s*\(?\s*false\b/u.test(line));
+}
+/**
+ * Add the Crashlytics Gradle plugin classpath next to the Google services
+ * classpath of the Capacitor template's root `build.gradle`. Returns the
+ * source unchanged when it is already there, and `undefined` for a layout the
+ * template does not produce.
+ */
+export function applyAndroidRootGradleCrashlytics(source) {
+    if (androidRootGradleHasCrashlytics(source)) {
+        return source;
+    }
+    const anchor = /^([ \t]*)classpath[ \t]+(['"])com\.google\.gms:google-services:[^'"\n]+\2[ \t]*$/mu.exec(source);
+    if (anchor === null) {
+        return undefined;
+    }
+    const end = anchor.index + anchor[0].length;
+    const newline = source.includes('\r\n') ? '\r\n' : '\n';
+    return `${source.slice(0, end)}${newline}${anchor[1] ?? ''}classpath '${crashlyticsGradleClasspath}'${source.slice(end)}`;
+}
+/**
+ * Apply the Crashlytics Gradle plugin right after the Google services plugin
+ * in the Capacitor template's app `build.gradle`, inside its
+ * `google-services.json` check: without that file Firebase does not start, so
+ * the Crashlytics SDK and its build ID check stay off too. Returns the source
+ * unchanged when it is already applied, and `undefined` for another layout.
+ */
+export function applyAndroidAppGradleCrashlytics(source) {
+    if (androidAppGradleHasCrashlytics(source)) {
+        return source;
+    }
+    const anchor = /^([ \t]*)apply[ \t]+plugin[ \t]*:[ \t]*(['"])com\.google\.gms\.google-services\2[ \t]*$/mu
+        .exec(source);
+    if (anchor === null) {
+        return undefined;
+    }
+    const end = anchor.index + anchor[0].length;
+    const newline = source.includes('\r\n') ? '\r\n' : '\n';
+    return `${source.slice(0, end)}${newline}${anchor[1] ?? ''}apply plugin: '${crashlyticsGradlePluginId}'${source.slice(end)}`;
+}
+/**
+ * Wire the Crashlytics Gradle plugin into a freshly generated Android project.
+ * Both files are checked before either is written; a layout the template does
+ * not produce is refused with the manual steps.
+ */
+export function materializeAndroidCrashlytics(shellRoot) {
+    const rootFile = path.join(shellRoot, androidRootGradle);
+    const appFile = path.join(shellRoot, androidAppGradle);
+    for (const file of [rootFile, appFile]) {
+        if (!existsSync(file) || !lstatSync(file).isFile()) {
+            throw new Error(`The generated Android project has no ${path.relative(shellRoot, file)}.`);
+        }
+    }
+    const rootSource = readFileSync(rootFile, 'utf8');
+    const appSource = readFileSync(appFile, 'utf8');
+    const nextRoot = applyAndroidRootGradleCrashlytics(rootSource);
+    const nextApp = applyAndroidAppGradleCrashlytics(appSource);
+    if (nextRoot === undefined || nextApp === undefined) {
+        throw new Error('The generated Android project has an unexpected Gradle layout; apply the Crashlytics '
+            + 'Gradle plugin yourself:\n'
+            + crashReportingAndroidSteps.map((step) => `- ${step}`).join('\n'));
+    }
+    if (nextRoot !== rootSource) {
+        writeFileSync(rootFile, nextRoot);
+    }
+    if (nextApp !== appSource) {
+        writeFileSync(appFile, nextApp);
+    }
+}
+/** Whether the shell's package.json installs the Crashlytics plugin (`--providers crash-reporting`). */
+export function shellUsesCrashlytics(shellPackage) {
+    if (typeof shellPackage !== 'object' || shellPackage === null) {
+        return false;
+    }
+    const { dependencies, devDependencies } = shellPackage;
+    return [dependencies, devDependencies].some((entries) => typeof entries === 'object' && entries !== null
+        && entries[crashReportingPlugin] !== undefined);
+}
+/**
+ * Store-policy preflight for a shell that installs the Crashlytics plugin.
+ * Errors fail a production build (`reportNativeStorePolicy`); other profiles
+ * print them.
+ *
+ * - Android: `android/app/google-services.json` must be present (without it
+ *   Firebase does not start and the release reports nothing), and the app
+ *   module must apply the Crashlytics Gradle plugin (without its build ID the
+ *   Crashlytics SDK stops the app at startup once Firebase starts).
+ * - iOS: the App target must bundle `GoogleService-Info.plist`; without it
+ *   Firebase does not start and the plugin still calls Crashlytics.
+ */
+export function inspectCrashReportingShell(input) {
+    if (!shellUsesCrashlytics(input.shellPackage)) {
+        return [];
+    }
+    const issues = [];
+    if (input.platform === 'android') {
+        const config = path.join(input.shellApp, 'android/app/google-services.json');
+        if (!existsSync(config) || !lstatSync(config).isFile() || readFileSync(config, 'utf8').trim() === '') {
+            issues.push({
+                level: 'error',
+                message: `The shell installs ${crashReportingPlugin}, but android/app/google-services.json is `
+                    + 'missing; Firebase does not start and the release reports no crashes. Download it from the '
+                    + 'Firebase console (the same file notifications use).',
+            });
+        }
+        if (!androidShellHasCrashlytics(input.shellApp)) {
+            issues.push({
+                level: 'error',
+                message: `The shell installs ${crashReportingPlugin}, but the Android project does not apply the `
+                    + 'Crashlytics Gradle plugin; the Crashlytics SDK stops the app at startup without the build ID '
+                    + `it writes. ${crashReportingAndroidSteps.join(' ')}`,
+            });
+        }
+        return issues;
+    }
+    if (input.iosProject !== undefined && !iosAppBundlesResource(input.iosProject, 'GoogleService-Info.plist')) {
+        issues.push({
+            level: 'error',
+            message: `The shell installs ${crashReportingPlugin}, but the iOS App target does not bundle `
+                + 'GoogleService-Info.plist; Firebase does not start and the plugin still calls Crashlytics. '
+                + 'Download it from the Firebase console and add it to the App target in Xcode.',
+        });
+    }
+    return issues;
+}

package/dist/index.d.ts

@@ -6,8 +6,11 @@ export { installPinnedReleaseDependencies, pinNativeDeploymentPlan, preparePinne
 export { withAndroidUploadSigningSession, type AndroidUploadSigningInput, } from './android-signing-session.js';
 export { checkpointNativeSubmission, readNativeReleaseStatus, reclaimNativeSubmission, releaseNativeSubmissionLease, recordNativeReleaseBuild, reserveNativeRelease, type ImmutableNativeBuildRecord, type NativeReleaseStatus, type NativeReleaseReservation, type NativeReleaseReservationInput, type NativeSubmissionCheckpoint, type NativeSubmissionStatus, type RecordNativeBuildInput, } from './release-state.js';
 export { runNativeDeployment, readStoreCredential, type RunNativeDeploymentInput, } from './native-deploy-run.js';
-export { submitRecordedNativeTarget, type NativeStoreCredential, type SubmitRecordedNativeTargetInput, } from './native-deploy-submission.js';
-export { PlaySubmissionUncertainError, submitVerifiedAndroidBundle, type PlayInternalSubmissionInput, type PlayInternalSubmissionResult, } from './play-internal-submission.js';
+export { planRecordedAndroidSubmission, submitRecordedNativeTarget, type NativeStoreCredential, type SubmitRecordedNativeTargetInput, } from './native-deploy-submission.js';
+export { PlaySubmissionUncertainError, planVerifiedAndroidBundleSubmission, submitVerifiedAndroidBundle, type PlayInternalSubmissionInput, type PlayInternalSubmissionResult, type PlaySubmissionPlan, } from './play-internal-submission.js';
+export { createPlayReleaseRequest, defaultPlayReleaseRequest, maximumPlayReleaseNoteCharacters, parsePlayReleaseNotes, type CreatePlayReleaseRequestInput, type PlayNewReleaseStatus, type PlayReleaseNote, type PlayReleaseRequest, type PlayReleaseStatus, } from './play-release-options.js';
+export { PlayPromoteUncertainError, promotePlayRelease, type PlayPromoteInput, type PlayPromoteResult, } from './play-release-promote.js';
+export { PlayRolloutUncertainError, changePlayRollout, type PlayRolloutAction, type PlayRolloutInput, type PlayRolloutResult, } from './play-release-rollout.js';
 export { IosSubmissionUncertainError, submitVerifiedIosBuild, type IosTestFlightStatus, type IosTestFlightSubmissionInput, type IosTestFlightSubmissionResult, } from './testflight-submission.js';
 export { createBrowserGameplayE2EDriver, type BrowserGameplayE2EInspectInput, type BrowserGameplayE2EPage, type BrowserGameplayE2EScreenshotOptions, type BrowserGameplayE2EViewport, type CreateBrowserGameplayE2EDriverInput, } from './browser-gameplay-e2e.js';
 export { collectGameplayE2EPathEvidence, defaultGameplayE2EReportFile, maximumGameplayE2EStates, parseGameplayE2EPlan, readGameplayE2EPlan, renderGameplayE2EMarkdown, resolveGameplayE2EReportFile, runGameplayE2E, type GameplayE2EAction, type GameplayE2EActionResult, type GameplayE2EDriver, type GameplayE2EHashLimits, type GameplayE2EInputAction, type GameplayE2EObservation, type GameplayE2EPauseResumeAction, type GameplayE2EPathEvidence, type GameplayE2EPlan, type GameplayE2EReport, type GameplayE2EResultStatus, type GameplayE2EState, type GameplayE2EStateResult, type GameplayE2EStatus, type RunGameplayE2EInput, type RunGameplayE2EResult, } from './gameplay-e2e.js';