@mpgd/cli 0.52.0 → 0.53.0

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

@@ -67,6 +67,15 @@ export interface CapacitorShellStarterPlan {
   /** Native store plugins the plan installs into the shell and declares in the game. */
   readonly providerPlugins: readonly CapacitorShellPlannedProviderPlugin[];
   /**
+  * The notifications plugins (`--providers notifications`) the plan installs
+  * into the shell, for Android and iOS, at the game's versions; empty when
+  * notifications are not requested.
+  */
+  readonly notificationPlugins: 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
@@ -115,4 +124,17 @@ export declare function assertAndroidReleaseLauncherIntegrity(shellApp: string):
 export declare function assertIosReleaseDisplayName(shellApp: string, expectedDisplayName: string): void;
 export declare function assertIosArchiveScheme(shellApp: string): void;
 export declare function decodeAndroidStringResource(value: string): string;
+/** The permission line that drops `SCHEDULE_EXACT_ALARM` from the merged Android manifest. */
+export declare const androidInexactAlarmPermission = "<uses-permission android:name=\"android.permission.SCHEDULE_EXACT_ALARM\" tools:node=\"remove\" />";
+/** Whether an Android manifest already drops `SCHEDULE_EXACT_ALARM` from the merge. */
+export declare function androidManifestRemovesExactAlarm(manifest: string): boolean;
+/**
+* Drops `SCHEDULE_EXACT_ALARM`, which `@capacitor/local-notifications` adds
+* to the merged manifest: reminders are inexact (notifications RFC
+* "Reminders"), Android 14 denies the permission to new installs, and Play
+* restricts it to alarm and calendar apps. The tools namespace is bound on
+* the manifest root when missing. A manifest that already drops it is
+* returned unchanged.
+*/
+export declare function applyAndroidManifestInexactAlarms(manifest: string): string;
 export {};

package/dist/capacitor-shell-starter.js

@@ -4,7 +4,8 @@ import { randomUUID } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { DOMParser } from '@xmldom/xmldom';
-import { satisfies, valid } from 'semver';
+import { satisfies, valid, validRange } from 'semver';
+import { capacitorGatewayRegistersNotifications, conflictingPushPlugin, notificationsCapacitorGatewayModules, notificationsCapacitorGateways, notificationsCapacitorSupportFiles, notificationsGameDependencies, notificationsMessagingFirebaseRange, notificationsMessagingPlugin, notificationsProviderId, notificationsShellPlugins, wireCapacitorGatewayNotifications, } from './notifications-starter.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';
@@ -239,7 +240,24 @@ export function planCapacitorShellStarter(input) {
         .filter((plugin) => requestedProviderIds.includes(plugin.id))
         .map((plugin) => resolveProviderPlugin(gameRoot, gameDependencies, cliDevelopmentDependencies, plugin));
     const warnings = [];
-    const gatewayFiles = planProviderGatewayWiring(gameRoot, input.templateRoot, providerPlugins, warnings);
+    const storeGatewayFiles = planProviderGatewayWiring(gameRoot, input.templateRoot, providerPlugins, warnings);
+    const notifications = requestedProviderIds.includes(notificationsProviderId)
+        ? planNotificationsProvider({
+            gameRoot,
+            templateRoot: input.templateRoot,
+            displayName: input.displayName,
+            gameDependencies,
+            existingShellPackage: packageContent,
+            plannedGateways: storeGatewayFiles,
+            warnings,
+        })
+        : undefined;
+    // The notifications wiring builds on the store wiring of the same gateway.
+    const gatewayFiles = [
+        ...storeGatewayFiles.filter((file) => notifications?.files.some((planned) => planned.path === file.path) !== true),
+        ...(notifications?.files ?? []),
+    ];
+    const notificationPlugins = notifications?.shellPlugins ?? [];
     if (packageContent !== undefined) {
         const existingShellDependencies = requireObject(parseJsonObject(packageContent, 'existing shell package').dependencies, 'existing shell dependencies');
         for (const plugin of capacitorShellProviderPlugins) {
@@ -250,6 +268,35 @@ export function planCapacitorShellStarter(input) {
                     + 'shell package and resync if the game stopped selling there.');
             }
         }
+        if (notifications === undefined) {
+            for (const name of notificationsShellPlugins) {
+                if (existingShellDependencies[name] !== undefined) {
+                    warnings.push(`The shell still lists ${name} although ${notificationsProviderId} is no longer `
+                        + 'requested; the initializer never removes a plugin, so remove it from the shell '
+                        + 'package and resync if the game stopped sending notifications.');
+                }
+            }
+        }
+    }
+    if (notifications !== undefined) {
+        // The starter exposes notifications on both platforms; the provider still
+        // reports its own readiness (no plugin, no Firebase files), which the
+        // target config follows. A state the game set itself is kept.
+        for (const targetName of ['android', 'ios']) {
+            const target = requireObject(targetMap[targetName], `${targetName} target`);
+            const integrations = target.integrations === undefined
+                ? {}
+                : requireObject(target.integrations, `${targetName}.integrations`);
+            if (integrations.notifications === undefined) {
+                target.integrations = { ...integrations, notifications: 'available' };
+            }
+            else if (integrations.notifications !== 'available'
+                && integrations.notifications !== 'action-required') {
+                warnings.push(`mpgd.targets.json keeps ${targetName}.integrations.notifications at `
+                    + `${String(integrations.notifications)}, which hides notifications from the game; set it `
+                    + 'to available once the shell is configured.');
+            }
+        }
     }
     const shellDependencies = {
         '@capacitor/android': capacitorVersion,
@@ -258,6 +305,7 @@ export function planCapacitorShellStarter(input) {
         '@capacitor/ios': capacitorVersion,
         '@mpgd/capacitor-game-services': pluginVersion,
         ...Object.fromEntries(providerPlugins.map((plugin) => [plugin.packageName, plugin.version])),
+        ...Object.fromEntries(notificationPlugins.map((plugin) => [plugin.packageName, plugin.version])),
     };
     if (packageContent !== undefined) {
         assertCompatibleExistingPackage(packageContent, shellDependencies, capacitorVersion, typescriptVersion);
@@ -304,7 +352,7 @@ export function planCapacitorShellStarter(input) {
                         typescript: typescriptVersion,
                     },
                 })
-                : withPackageDependencies(packageContent, providerPlugins),
+                : withPackageDependencies(packageContent, [...providerPlugins, ...notificationPlugins]),
         },
         {
             path: `${shellPath}/capacitor.config.ts`,
@@ -331,17 +379,27 @@ export function planCapacitorShellStarter(input) {
                 appId: input.appId,
                 displayName: input.displayName,
                 requestedProviderIds,
-                ...(providerPlugins.length === 0
+                ...(providerPlugins.length === 0 && notificationPlugins.length === 0
                     ? {}
                     : {
-                        providers: Object.fromEntries(providerPlugins.map((plugin) => [
-                            plugin.id,
-                            {
-                                package: plugin.packageName,
-                                version: plugin.version,
-                                platform: plugin.platform,
-                            },
-                        ])),
+                        providers: {
+                            ...Object.fromEntries(providerPlugins.map((plugin) => [
+                                plugin.id,
+                                {
+                                    package: plugin.packageName,
+                                    version: plugin.version,
+                                    platform: plugin.platform,
+                                },
+                            ])),
+                            ...(notificationPlugins.length === 0
+                                ? {}
+                                : {
+                                    [notificationsProviderId]: {
+                                        packages: Object.fromEntries(notificationPlugins.map((plugin) => [plugin.packageName, plugin.version])),
+                                        platforms: ['android', 'ios'],
+                                    },
+                                }),
+                        },
                     }),
                 ...(requestedBackendUrl === undefined ? {} : { backendUrl: requestedBackendUrl }),
             }),
@@ -361,7 +419,12 @@ export function planCapacitorShellStarter(input) {
                 '',
                 'requestedProviderIds is selection metadata, except play-billing and',
                 'storekit: those install the kit store plugin into this shell and the game',
-                'and register it with cap sync. A plugin never reports a feature as',
+                'and register it with cap sync; notifications installs',
+                '@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',
                 '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.',
@@ -415,16 +478,33 @@ export function planCapacitorShellStarter(input) {
     // The game bundle imports the plugin from its gateway file, so the game
     // declares it too, at the shell's exact version; the materializer's game
     // install picks it up.
-    const missingGameDependencies = providerPlugins.filter((plugin) => gameDependencies[plugin.packageName] === undefined);
-    if (missingGameDependencies.length > 0) {
+    const missingGameDependencies = [
+        ...providerPlugins.map((plugin) => [plugin.packageName, plugin.version]),
+        ...Object.entries(notifications?.gameDependencies ?? {}),
+    ].filter(([name]) => gameDependencies[name] === undefined);
+    const gameScripts = gamePackage.scripts === undefined
+        ? {}
+        : requireObject(gamePackage.scripts, 'game scripts');
+    const validatorPresent = notifications !== undefined
+        && (notifications.files.some((file) => file.path === 'tools/validate-notifications.ts')
+            || readExisting(safeDestination(gameRoot, 'tools/validate-notifications.ts')) !== undefined);
+    const missingScripts = !validatorPresent || gameScripts['validate:notifications'] !== undefined
+        ? {}
+        : {
+            'validate:notifications': 'ttsx --project tsconfig.tools.json tools/validate-notifications.ts',
+        };
+    if (missingGameDependencies.length > 0 || Object.keys(missingScripts).length > 0) {
         safeDestination(gameRoot, 'package.json');
         requestedFiles.push({
             path: 'package.json',
             content: json({
                 ...gamePackage,
+                ...(Object.keys(missingScripts).length === 0
+                    ? {}
+                    : { scripts: { ...gameScripts, ...missingScripts } }),
                 dependencies: {
                     ...gameDependencies,
-                    ...Object.fromEntries(missingGameDependencies.map((plugin) => [plugin.packageName, plugin.version])),
+                    ...Object.fromEntries(missingGameDependencies),
                 },
             }),
         });
@@ -454,6 +534,7 @@ export function planCapacitorShellStarter(input) {
         changedFiles: files.map((file) => file.path),
         nativePlatformsToAdd,
         providerPlugins,
+        notificationPlugins,
         warnings,
     };
 }
@@ -570,6 +651,9 @@ export function materializeCapacitorShellStarter(plan, runner = { run: runComman
         const manifest = readJsonObject(path.join(plan.gameRoot, shellPath, 'mpgd.native-shell.json'));
         if (platform === 'android' && generatedNow) {
             materializeAndroidBackupPolicy(plan.gameRoot);
+            if (plan.notificationPlugins.length > 0) {
+                materializeAndroidInexactAlarms(plan.gameRoot);
+            }
         }
         if (platform === 'ios') {
             materializeIosArchiveScheme(plan.gameRoot);
@@ -588,7 +672,8 @@ export function materializeCapacitorShellStarter(plan, runner = { run: runComman
     // `cap add` syncs a new project itself; a preserved project needs an explicit
     // 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)
+        if ((plan.providerPlugins.some((plugin) => plugin.platform === platform)
+            || plan.notificationPlugins.length > 0)
             && !plan.nativePlatformsToAdd.includes(platform)
             && existsSync(path.join(plan.gameRoot, shellPath, platform))) {
             runner.run('pnpm', ['--dir', shellPath, 'cap', 'sync', platform], plan.gameRoot);
@@ -2043,7 +2128,10 @@ function assertCompatibleExistingPackage(source, shellDependencies, capacitorVer
         throw new Error('Existing Capacitor shell package must stay private.');
     }
     const dependencies = requireObject(value.dependencies, 'existing shell dependencies');
-    const providerPackages = new Set(capacitorShellProviderPlugins.map((plugin) => plugin.packageName));
+    const providerPackages = new Set([
+        ...capacitorShellProviderPlugins.map((plugin) => plugin.packageName),
+        ...notificationsShellPlugins,
+    ]);
     for (const [name, version] of Object.entries(shellDependencies)) {
         // A store plugin the shell does not list yet is added by the plan. One it
         // lists at another version would compile native code that does not match
@@ -2472,6 +2560,287 @@ function planProviderGatewayWiring(gameRoot, templateRoot, plugins, warnings) {
     }
     return [...planned].map(([file, content]) => ({ path: file, content }));
 }
+/** The permission line that drops `SCHEDULE_EXACT_ALARM` from the merged Android manifest. */
+export const androidInexactAlarmPermission = '<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" tools:node="remove" />';
+/** Whether an Android manifest already drops `SCHEDULE_EXACT_ALARM` from the merge. */
+export function androidManifestRemovesExactAlarm(manifest) {
+    const code = withoutXmlComments(manifest);
+    return /<uses-permission\b[^>]*android:name\s*=\s*"android\.permission\.SCHEDULE_EXACT_ALARM"[^>]*tools:node\s*=\s*"remove"/u
+        .test(code)
+        || /<uses-permission\b[^>]*tools:node\s*=\s*"remove"[^>]*android:name\s*=\s*"android\.permission\.SCHEDULE_EXACT_ALARM"/u
+            .test(code);
+}
+/** The manifest with each XML comment blanked to spaces, so offsets stay the same. */
+function withoutXmlComments(manifest) {
+    return manifest.replace(/<!--[\s\S]*?-->/gu, (comment) => comment.replace(/[^\n]/gu, ' '));
+}
+/**
+ * Drops `SCHEDULE_EXACT_ALARM`, which `@capacitor/local-notifications` adds
+ * to the merged manifest: reminders are inexact (notifications RFC
+ * "Reminders"), Android 14 denies the permission to new installs, and Play
+ * restricts it to alarm and calendar apps. The tools namespace is bound on
+ * the manifest root when missing. A manifest that already drops it is
+ * returned unchanged.
+ */
+export function applyAndroidManifestInexactAlarms(manifest) {
+    if (androidManifestRemovesExactAlarm(manifest)) {
+        return manifest;
+    }
+    const code = withoutXmlComments(manifest);
+    const root = /<manifest\b[^>]*?>/u.exec(code);
+    const close = code.lastIndexOf('</manifest>');
+    if (root === null || close === -1 || root[0].endsWith('/>') || close < root.index) {
+        return manifest;
+    }
+    const newline = manifest.includes('\r\n') ? '\r\n' : '\n';
+    let rootTag = manifest.slice(root.index, root.index + root[0].length);
+    if (!/\sxmlns:tools\s*=/u.test(rootTag)) {
+        rootTag = rootTag.replace(/^<manifest\b/u, `<manifest xmlns:tools="${androidToolsNamespace}"`);
+    }
+    const head = `${manifest.slice(0, root.index)}${rootTag}${manifest.slice(root.index + root[0].length, close)}`;
+    return `${head.trimEnd()}${newline}    ${androidInexactAlarmPermission}${newline}${manifest.slice(close)}`;
+}
+function materializeAndroidInexactAlarms(gameRoot) {
+    const manifestFile = safeDestination(gameRoot, `${shellPath}/android/app/src/main/AndroidManifest.xml`);
+    if (!existsSync(manifestFile) || !lstatSync(manifestFile).isFile()) {
+        return;
+    }
+    const source = readFileSync(manifestFile, 'utf8');
+    const next = applyAndroidManifestInexactAlarms(source);
+    if (next !== source) {
+        writeFileSync(manifestFile, next);
+    }
+}
+/**
+ * Plans `--providers notifications` for the shell and the game: the two
+ * Capacitor plugins at the game's installed versions (or the starter's), the
+ * game's notifications packages, and, when a Capacitor gateway is still the
+ * template's, its notifications wiring with the starter modules it imports.
+ * A game-owned gateway is only checked. Native setup the initializer never
+ * writes (Firebase files, the iOS capability, an existing Android manifest)
+ * is reported as warnings.
+ */
+function planNotificationsProvider(input) {
+    const { gameRoot, gameDependencies, warnings } = input;
+    const shellDependencies = input.existingShellPackage === undefined
+        ? {}
+        : requireObject(parseJsonObject(input.existingShellPackage, 'existing shell package').dependencies, 'existing shell dependencies');
+    if (gameDependencies[conflictingPushPlugin] !== undefined
+        || shellDependencies[conflictingPushPlugin] !== undefined) {
+        throw new Error(`--providers notifications installs @capacitor-firebase/messaging, which cannot run next to `
+            + `${conflictingPushPlugin}: on iOS both claim Capacitor's one push handler. Remove `
+            + `${conflictingPushPlugin} from the game and the shell first.`);
+    }
+    const versionOf = (name) => {
+        const installedFile = path.join(gameRoot, 'node_modules', name, 'package.json');
+        if (existsSync(installedFile)) {
+            const installed = readJsonObject(installedFile);
+            const version = requireString(installed.version, `installed ${name} version`);
+            if (valid(version) === null) {
+                throw new Error(`${name} must resolve to a concrete version, not ${version}.`);
+            }
+            // The plugin's own peers (Capacitor core) must accept the game's
+            // installed copies, as a store plugin's must.
+            assertInstalledPeers(gameRoot, `${name}@${version}`, installed.peerDependencies);
+            return { version, installed: true };
+        }
+        if (gameDependencies[name] !== undefined) {
+            throw new Error(`The game declares ${name} but it is not installed; install game dependencies before `
+                + 'initializing the shell.');
+        }
+        const version = notificationsGameDependencies[name];
+        if (version === undefined) {
+            throw new Error(`No starter version is known for ${name}.`);
+        }
+        return { version, installed: false };
+    };
+    const shellPlugins = notificationsShellPlugins.map((name) => ({
+        packageName: name,
+        ...versionOf(name),
+    }));
+    // The wiring imports @mpgd/adapter-capacitor/notifications: the game's
+    // installed adapter must have it, and the plugins must satisfy its peers.
+    const adapter = readJsonObject(path.join(gameRoot, 'node_modules/@mpgd/adapter-capacitor/package.json'));
+    const adapterExports = adapter.exports;
+    if (typeof adapterExports !== 'object' || adapterExports === null
+        || adapterExports['./notifications'] === undefined) {
+        throw new Error(`--providers notifications needs @mpgd/adapter-capacitor/notifications, which the game's `
+            + `@mpgd/adapter-capacitor ${String(adapter.version)} does not export; upgrade the game's kit `
+            + 'packages (mpgd kit upgrade) first.');
+    }
+    // The starter's provider module also imports the settings opener, which
+    // an adapter older than this CLI's notifications starter does not have.
+    // The subpath's declared types file (dist/notifications.d.ts today), and
+    // the module it re-exports the opener from.
+    const adapterRoot = path.join(gameRoot, 'node_modules/@mpgd/adapter-capacitor');
+    const declaredTypes = adapterExports['./notifications'];
+    const typesPath = typeof declaredTypes === 'object' && declaredTypes !== null
+        && typeof declaredTypes.types === 'string'
+        ? declaredTypes.types
+        : './dist/notifications.d.ts';
+    const adapterTypes = readExisting(path.join(adapterRoot, typesPath));
+    const openerTypes = readExisting(path.join(adapterRoot, path.dirname(typesPath), 'notifications-settings.d.ts'));
+    // Refused only when the declarations show the opener is absent: an
+    // `export *` the check cannot follow passes, and the build then decides.
+    if (adapterTypes !== undefined && !/\bexport\s*\*/u.test(adapterTypes)
+        && !`${adapterTypes}\n${openerTypes ?? ''}`.includes('openCapacitorNotificationSettings')) {
+        throw new Error(`The game's @mpgd/adapter-capacitor ${String(adapter.version)} has no `
+            + 'openCapacitorNotificationSettings, which the notifications starter uses; upgrade the '
+            + "game's kit packages (mpgd kit upgrade) first.");
+    }
+    // The adapter's other peers (Capacitor core) must accept the game's
+    // installed copies too; the plugins get their own message below.
+    assertInstalledPeers(gameRoot, `@mpgd/adapter-capacitor@${String(adapter.version)}`, typeof adapter.peerDependencies === 'object' && adapter.peerDependencies !== null
+        ? Object.fromEntries(Object.entries(adapter.peerDependencies)
+            .filter(([name]) => !notificationsShellPlugins.includes(name)))
+        : undefined);
+    const adapterPeers = typeof adapter.peerDependencies === 'object' && adapter.peerDependencies !== null
+        ? adapter.peerDependencies
+        : {};
+    for (const plugin of shellPlugins) {
+        const range = adapterPeers[plugin.packageName];
+        // A range semver cannot read (`workspace:*`, a tag) is not checked.
+        if (typeof range === 'string' && validRange(range) !== null
+            && !satisfies(plugin.version, range, { includePrerelease: true })) {
+            throw new Error(plugin.installed
+                ? `@mpgd/adapter-capacitor ${String(adapter.version)} needs ${plugin.packageName} ${range}, `
+                    + `but the game has ${plugin.version}; align the game's version before rerunning.`
+                : `@mpgd/adapter-capacitor ${String(adapter.version)} needs ${plugin.packageName} ${range}, `
+                    + `but this CLI would add ${plugin.version}; add a version in that range to the game `
+                    + `(pnpm add ${plugin.packageName}) or upgrade the CLI, then rerun.`);
+        }
+    }
+    // The messaging plugin's web fallback imports `firebase`: the game's own
+    // copy must be in the plugin's peer range. For the plugin the starter
+    // adds, the kit pins the range. An installed plugin names its own, which
+    // `versionOf` already checked against an installed firebase; this covers
+    // the firebase the CLI would add.
+    const messaging = shellPlugins.find((plugin) => plugin.packageName === notificationsMessagingPlugin);
+    const firebase = versionOf('firebase');
+    if (messaging !== undefined) {
+        const installedPeers = messaging.installed
+            ? readJsonObject(path.join(gameRoot, 'node_modules', notificationsMessagingPlugin, 'package.json')).peerDependencies
+            : undefined;
+        const declared = typeof installedPeers === 'object' && installedPeers !== null
+            ? installedPeers['firebase']
+            : undefined;
+        const firebaseRange = messaging.installed ? declared : notificationsMessagingFirebaseRange;
+        if (typeof firebaseRange === 'string' && validRange(firebaseRange) !== null
+            && !satisfies(firebase.version, firebaseRange, { includePrerelease: true })) {
+            throw new Error(firebase.installed
+                ? `@capacitor-firebase/messaging ${messaging.version} needs firebase ${firebaseRange}, but the game `
+                    + `has ${firebase.version}; align the game's firebase (pnpm add firebase@"${firebaseRange}") `
+                    + 'before rerunning.'
+                : `@capacitor-firebase/messaging ${messaging.version} needs firebase ${firebaseRange}, but this `
+                    + `CLI would add ${firebase.version}; add a version in that range to the game `
+                    + `(pnpm add firebase@"${firebaseRange}") or upgrade the CLI, then rerun.`);
+        }
+    }
+    const gamePackages = Object.fromEntries(Object.keys(notificationsGameDependencies).map((name) => [name, versionOf(name).version]));
+    const register = 'register createStarterCapacitorNotifications (src/platform/capacitorNotifications.ts) '
+        + 'or createCapacitorNotificationServiceProvider from @mpgd/adapter-capacitor/notifications in its '
+        + 'providers';
+    const files = [];
+    const overlayRoot = input.templateRoot === undefined
+        ? undefined
+        : path.join(path.dirname(input.templateRoot), 'notifications-overlay', 'common');
+    const jsonTitle = JSON.stringify(input.displayName).slice(1, -1);
+    const starterFile = (root, file) => {
+        // A function replacer: `$&` or `$$` in a display name stays literal.
+        const title = file.endsWith('.json') ? jsonTitle : input.displayName;
+        return readTemplateFile(root, file).replaceAll('__GAME_TITLE__', () => title);
+    };
+    // The wired gateway imports these starter modules; a game-owned copy that
+    // differs keeps the gateway as it is, as a differing store module does.
+    const keptModule = overlayRoot === undefined
+        ? undefined
+        : notificationsCapacitorGatewayModules.find((file) => {
+            const existing = readExisting(safeDestination(gameRoot, file));
+            return existing !== undefined
+                && existing.replace(/\r\n/gu, '\n') !== starterFile(overlayRoot, file);
+        });
+    for (const gatewayFile of Object.values(notificationsCapacitorGateways)) {
+        const current = input.plannedGateways.find((file) => file.path === gatewayFile)?.content
+            ?? readExisting(safeDestination(gameRoot, gatewayFile));
+        if (current !== undefined && capacitorGatewayRegistersNotifications(current)) {
+            continue;
+        }
+        if (current === undefined) {
+            warnings.push(`${gatewayFile} is missing; ${register}.`);
+            continue;
+        }
+        const template = input.templateRoot === undefined
+            ? undefined
+            : readTemplateFile(input.templateRoot, gatewayFile);
+        if (template === undefined || current.replace(/\r\n/gu, '\n') !== template) {
+            warnings.push(`${gatewayFile} does not register notifications and is game-owned; ${register}.`);
+            continue;
+        }
+        if (keptModule !== undefined) {
+            warnings.push(`${gatewayFile} was not rewritten because the game-owned ${keptModule} differs from the `
+                + `notifications starter; ${register}.`);
+            continue;
+        }
+        files.push({
+            path: gatewayFile,
+            content: wireCapacitorGatewayNotifications(gatewayFile, template),
+        });
+    }
+    if (files.length > 0 && overlayRoot !== undefined) {
+        // The starter modules and catalog the wired gateways read; the game keeps any it has.
+        for (const file of notificationsCapacitorSupportFiles) {
+            if (readExisting(safeDestination(gameRoot, file)) === undefined) {
+                files.push({ path: file, content: starterFile(overlayRoot, file) });
+            }
+        }
+        warnings.push('The notification settings screen is not added to an existing game; render one from '
+            + 'src/platform/notificationSettings.ts (see docs/NOTIFICATIONS.md) so players can turn '
+            + 'reminders and advertising consent on and off.');
+    }
+    const androidManifest = readExisting(safeDestination(gameRoot, `${shellPath}/android/app/src/main/AndroidManifest.xml`));
+    if (androidManifest !== undefined && !androidManifestRemovesExactAlarm(androidManifest)) {
+        warnings.push(`${shellPath}/android/app/src/main/AndroidManifest.xml keeps SCHEDULE_EXACT_ALARM, which `
+            + '@capacitor/local-notifications adds; reminders are inexact, so add '
+            + `${androidInexactAlarmPermission} to the manifest.`);
+    }
+    if (readExisting(safeDestination(gameRoot, `${shellPath}/android/app/google-services.json`)) === undefined) {
+        warnings.push(`Android push needs ${shellPath}/android/app/google-services.json from the Firebase console `
+            + '(see the mpgd-kit Firebase guide); without it the push half fails closed.');
+    }
+    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).');
+    }
+    return {
+        shellPlugins: shellPlugins.map(({ packageName, version }) => ({ packageName, version })),
+        gameDependencies: gamePackages,
+        files,
+    };
+}
+/**
+ * Refuses a package whose declared peers the game's installed copies do not
+ * satisfy (Capacitor core, the kit packages), before anything is written.
+ */
+function assertInstalledPeers(gameRoot, label, peerDependencies) {
+    if (typeof peerDependencies !== 'object' || peerDependencies === null) {
+        return;
+    }
+    for (const [peer, range] of Object.entries(peerDependencies)) {
+        const peerFile = path.join(gameRoot, 'node_modules', peer, 'package.json');
+        // A range semver cannot read (`workspace:*`, a tag) is not checked.
+        if (typeof range !== 'string' || validRange(range) === null || !existsSync(peerFile)) {
+            continue;
+        }
+        const peerVersion = readJsonObject(peerFile).version;
+        if (typeof peerVersion === 'string' && valid(peerVersion) !== null
+            && !satisfies(peerVersion, range, { includePrerelease: true })) {
+            throw new Error(`${label} needs ${peer} ${range}, but the game has ${peerVersion}; align the game's `
+                + 'versions before rerunning.');
+        }
+    }
+}
 /** A regular file of the CLI's game template, read without leaving the template root. */
 function readTemplateFile(templateRoot, relative) {
     const root = realpathSync(templateRoot);

package/dist/index.js

@@ -24,6 +24,7 @@ import { cloudflarePagesDeploymentProfiles, hostedPwaDeploymentHosts, verifyHost
 import { createMicrosoftStorePackageAcceptanceRuntime, runMicrosoftStorePackageAcceptance, } from './microsoft-store-package-acceptance.js';
 import { runMicrosoftStorePackageGeneration } from './microsoft-store-package-generation.js';
 import { defaultMpgdKitPath, initializeMicrosoftStoreStarter, listMicrosoftStoreInitializerTemplateFiles, prepareBaseGameTemplateFile, resolveMicrosoftStoreAdapterDependencyVersion, } from './microsoft-store-starter.js';
+import { applyNotificationsStarter, notificationsProviderId, readGameCreateProviders, } from './notifications-starter.js';
 import { applyKitUpgrade, planKitUpgrade } from './kit-upgrade.js';
 import { applyToolingMigration, planToolingMigration } from './tooling-migration.js';
 import { runMicrosoftStoreSubmissionPreflight } from './microsoft-store-submission.js';
@@ -58,6 +59,7 @@ const packageRoot = resolvePackageRoot(sourceDir);
 const detectedKitRoot = resolveDefaultKitRoot();
 const gameTemplateDir = path.resolve(packageRoot, 'templates/phaser-game');
 const liteTemplateOverlayDir = path.resolve(packageRoot, 'templates/lite-overlay');
+const notificationsTemplateDir = path.resolve(packageRoot, 'templates/notifications-overlay');
 const supportedGameTemplates = ['phaser', 'lite'];
 /** Lite renderers implemented today. dom/svg are reserved extension points in @mpgd/lite-shell. */
 const supportedLiteRenderers = ['canvas'];
@@ -575,6 +577,10 @@ const gameCommand = defineI18n({
                     en: 'Lite template renderer. Only canvas is implemented today.',
                     ko: 'lite 템플릿 렌더러. 현재는 canvas만 지원합니다.',
                 },
+                providers: {
+                    en: 'Comma-separated game providers. notifications adds the notifications v2 starter: the topic catalog, the backend settings, the Android, iOS, Apps in Toss, and Devvit wiring, and a notification settings screen.',
+                    ko: '쉼표로 구분한 게임 provider. notifications는 알림 v2 스타터(토픽 카탈로그, 백엔드 설정, Android·iOS·앱인토스·Devvit 연결, 알림 설정 화면)를 추가합니다.',
+                },
             }),
             args: {
                 template: {
@@ -627,6 +633,11 @@ const gameCommand = defineI18n({
                     required: false,
                     description: 'Include the Microsoft Store PWA target and release workflow.',
                 },
+                providers: {
+                    type: 'string',
+                    required: false,
+                    description: 'Comma-separated game providers. notifications adds the notifications v2 starter.',
+                },
             },
             run: (ctx) => {
                 const positionals = readLocalPositionals(ctx.positionals, ['game', 'create']);
@@ -649,6 +660,7 @@ const gameCommand = defineI18n({
                     ...(kitPath === undefined ? {} : { kitPath }),
                     dryRun: ctx.values['dry-run'] === true,
                     microsoftStore: ctx.values['microsoft-store'] === true,
+                    providers: readGameCreateProviders(readOptionalString(ctx.values.providers)),
                 });
             },
         }),
@@ -1597,8 +1609,8 @@ const targetCommand = defineI18n({
                     ko: '프로덕션 HTTPS Game Services 기본 URL.',
                 },
                 providers: {
-                    en: 'Comma-separated provider IDs. play-billing (Android) and storekit (iOS) install the kit store plugin into the shell and the game, register it with cap sync, and wire an unwired template gateway; other IDs are recorded only.',
-                    ko: '쉼표로 구분한 provider ID. play-billing(Android)과 storekit(iOS)은 키트 스토어 플러그인을 셸과 게임에 설치하고 cap sync로 등록하며, 연결되지 않은 템플릿 게이트웨이를 연결합니다. 다른 ID는 기록만 합니다.',
+                    en: 'Comma-separated provider IDs. play-billing (Android) and storekit (iOS) install the kit store plugin into the shell and the game, register it with cap sync, and wire an unwired template gateway; notifications installs the Firebase messaging and local notifications plugins for Android and iOS and wires a template gateway; other IDs are recorded only.',
+                    ko: '쉼표로 구분한 provider ID. play-billing(Android)과 storekit(iOS)은 키트 스토어 플러그인을 셸과 게임에 설치하고 cap sync로 등록하며, 연결되지 않은 템플릿 게이트웨이를 연결합니다. notifications는 Android·iOS용 Firebase 메시징과 로컬 알림 플러그인을 설치하고 템플릿 게이트웨이를 연결합니다. 다른 ID는 기록만 합니다.',
                 },
             }),
             args: {
@@ -1646,7 +1658,7 @@ const targetCommand = defineI18n({
                 providers: {
                     type: 'string',
                     required: false,
-                    description: 'Comma-separated provider IDs. play-billing (Android) and storekit (iOS) install the kit store plugin into the shell and the game, register it with cap sync, and wire an unwired template gateway; other IDs are recorded only.',
+                    description: 'Comma-separated provider IDs. play-billing (Android) and storekit (iOS) install the kit store plugin into the shell and the game, register it with cap sync, and wire an unwired template gateway; notifications installs the Firebase messaging and local notifications plugins for Android and iOS and wires a template gateway; other IDs are recorded only.',
                 },
             },
             run: (ctx) => {
@@ -1693,6 +1705,11 @@ const targetCommand = defineI18n({
                             + `${plugin.versionSource === 'kit' ? ' and the game' : ''}`
                             + `${dryRun ? '; cap add or cap sync registers it' : ''}.`);
                     }
+                    if (plan.notificationPlugins.length > 0) {
+                        console.info(`${dryRun ? 'Would install' : 'Installed'} notifications plugins `
+                            + plan.notificationPlugins.map((plugin) => `${plugin.packageName}@${plugin.version}`).join(', ')
+                            + ` into the shell for android and ios${dryRun ? '; cap add or cap sync registers them' : ''}.`);
+                    }
                     for (const warning of plan.warnings) {
                         console.warn(`Warning: ${warning}`);
                     }
@@ -2943,9 +2960,17 @@ function createGameApp(input) {
         microsoftStore: input.microsoftStore,
     });
     const baseTemplateFiles = collectTemplateFiles(gameTemplateDir);
-    const selectedTemplateFiles = input.template === 'lite'
+    const templateFiles = input.template === 'lite'
         ? applyLiteTemplateOverlay(baseTemplateFiles, collectTemplateFiles(liteTemplateOverlayDir))
         : baseTemplateFiles;
+    const selectedTemplateFiles = input.providers?.includes(notificationsProviderId) === true
+        ? applyNotificationsStarter(templateFiles, {
+            template: input.template === 'lite' ? 'lite' : 'phaser',
+            common: collectTemplateFiles(path.join(notificationsTemplateDir, 'common')),
+            phaser: collectTemplateFiles(path.join(notificationsTemplateDir, 'phaser')),
+            lite: collectTemplateFiles(path.join(notificationsTemplateDir, 'lite')),
+        })
+        : templateFiles;
     const files = selectedTemplateFiles.flatMap((file) => {
         const prepared = prepareBaseGameTemplateFile({
             relativePath: file.relativePath,
@@ -3371,8 +3396,14 @@ function createGameOwnedReleaseEnv(gameRoot, baseEnv) {
         ?? readSourceGitSha(gameRoot);
     const appVersion = readOptionalString(baseEnv.APP_VERSION)
         ?? readGamePackageVersion(gameRoot);
+    const notificationTopicsFile = readConfiguredPath(baseEnv.MPGD_NOTIFICATION_TOPICS_FILE);
     return {
         ...monetizationFiles,
+        // The Apps in Toss wrapper builds in its own directory; a relative path
+        // names a file of the game, as `pnpm validate:notifications` reads it.
+        ...(notificationTopicsFile === undefined
+            ? {}
+            : { MPGD_NOTIFICATION_TOPICS_FILE: path.resolve(gameRoot, notificationTopicsFile) }),
         MPGD_SOURCE_GIT_SHA: sourceGitSha,
         ...(appVersion === undefined ? {} : { APP_VERSION: appVersion }),
     };