@mpgd/cli 0.45.0 → 0.47.0

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

@@ -2,14 +2,61 @@ interface PlannedFile {
   readonly path: string;
   readonly content: string;
 }
+/**
+* A provider id that names a kit native store plugin. `--providers` installs
+* the plugin package into the game-owned shell (where `cap add` or `cap sync`
+* registers its native code), declares it in the game (where the Vite bundle
+* imports it from the gateway file), and wires the gateway when the game still
+* has the unwired template gateway; any other id stays selection metadata.
+*/
+export interface CapacitorShellProviderPlugin {
+  readonly id: string;
+  readonly packageName: string;
+  /** The plugin's directory in a kit checkout, read when the game has not installed it yet. */
+  readonly packageDir: string;
+  /** The native platform, which is also the canonical `mpgd.targets.json` target name. */
+  readonly platform: 'android' | 'ios';
+  /** The game gateway file expected to register the plugin's service provider. */
+  readonly gatewayFile: string;
+  readonly gatewayFactory: string;
+  /**
+  * Gateway sources the initializer may replace with the template's wired
+  * gateway: the unwired gateway earlier templates generated. Any other
+  * source is game-owned and only checked.
+  */
+  readonly legacyGatewaySources: readonly string[];
+}
+export declare const capacitorShellProviderPlugins: readonly CapacitorShellProviderPlugin[];
+/**
+* Game modules the wired template gateways import. They are written next to a
+* replaced legacy gateway when missing; a game-owned copy that differs from
+* the template keeps the legacy gateway in place.
+*/
+export declare const capacitorShellProviderSupportFiles: readonly string[];
+/** A plugin the plan installs, with the exact version the shell and the game pin. */
+export interface CapacitorShellPlannedProviderPlugin extends CapacitorShellProviderPlugin {
+  readonly version: string;
+  /** `installed`: the game's copy; `kit`: the version this CLI release ships with. */
+  readonly versionSource: 'installed' | 'kit';
+}
 export interface CapacitorShellStarterInput {
   readonly gameRoot: string;
   readonly appId: string;
   readonly displayName: string;
   readonly iconSource?: string;
   readonly backendUrl?: string;
-  /** Selection metadata only; a provider SDK is not installed or enabled here. */
+  /**
+  * Requested provider ids. The ids in `capacitorShellProviderPlugins`
+  * (`play-billing`, `storekit`) install their native plugin package into the
+  * shell and the game; other ids are recorded as selection metadata only.
+  */
   readonly providerIds?: readonly string[];
+  /**
+  * The CLI's game template. With it a legacy, unwired Android or iOS gateway
+  * is replaced by the template's store-provider wiring; without it the plan
+  * only checks the gateway and warns.
+  */
+  readonly templateRoot?: string;
 }
 export interface CapacitorShellStarterPlan {
   readonly gameRoot: string;
@@ -17,6 +64,15 @@ export interface CapacitorShellStarterPlan {
   readonly changedFiles: readonly string[];
   readonly nativePlatformsToAdd: readonly ('android' | 'ios')[];
   readonly files: readonly PlannedFile[];
+  /** Native store plugins the plan installs into the shell and declares in the game. */
+  readonly providerPlugins: readonly CapacitorShellPlannedProviderPlugin[];
+  /**
+  * 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
+  * rewritten for these.
+  */
+  readonly warnings: readonly string[];
 }
 /**
 * Produce the complete game-owned shell change list before writing anything.

package/dist/capacitor-shell-starter.js

@@ -4,6 +4,7 @@ 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 { 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';
@@ -18,6 +19,50 @@ const javaKeywords = new Set(`
   synchronized this throw throws transient try void volatile while true false null record sealed
   permits var yield
 `.trim().split(/\s+/u));
+const unwiredCapacitorGateway = (target) => [
+    "import { createCapacitorPlatformGateway } from '@mpgd/adapter-capacitor';",
+    "import type { PlatformGateway } from '@mpgd/platform';",
+    '',
+    "import type { RuntimeConfig } from '../runtimeDetector';",
+    '',
+    'export async function createBuildGateway(runtime: RuntimeConfig): Promise<PlatformGateway> {',
+    '  return createCapacitorPlatformGateway({',
+    `    target: '${target}',`,
+    '    appVersion: runtime.appVersion,',
+    '    buildId: runtime.buildId,',
+    '  });',
+    '}',
+    '',
+].join('\n');
+export const capacitorShellProviderPlugins = Object.freeze([
+    {
+        id: 'play-billing',
+        packageName: '@mpgd/capacitor-play-billing',
+        packageDir: 'native-plugins/capacitor-play-billing',
+        platform: 'android',
+        gatewayFile: 'src/platform/buildGateways/capacitorAndroid.ts',
+        gatewayFactory: 'createCapacitorPlayBillingServiceProvider',
+        legacyGatewaySources: [unwiredCapacitorGateway('android')],
+    },
+    {
+        id: 'storekit',
+        packageName: '@mpgd/capacitor-storekit',
+        packageDir: 'native-plugins/capacitor-storekit',
+        platform: 'ios',
+        gatewayFile: 'src/platform/buildGateways/capacitorIos.ts',
+        gatewayFactory: 'createCapacitorStoreKitServiceProvider',
+        legacyGatewaySources: [unwiredCapacitorGateway('ios')],
+    },
+]);
+/**
+ * Game modules the wired template gateways import. They are written next to a
+ * replaced legacy gateway when missing; a game-owned copy that differs from
+ * the template keeps the legacy gateway in place.
+ */
+export const capacitorShellProviderSupportFiles = Object.freeze([
+    'src/platform/commerceProducts.ts',
+    'src/platform/commerceAccountBinding.ts',
+]);
 /**
  * Produce the complete game-owned shell change list before writing anything.
  * Existing Android/iOS projects, signing files, and custom controllers are
@@ -107,6 +152,13 @@ export function planCapacitorShellStarter(input) {
     const cliDevelopmentDependencies = requireObject(cliPackage.devDependencies, 'CLI dev dependencies');
     const typescriptVersion = requireString(cliDevelopmentDependencies.typescript, 'CLI TypeScript version');
     const targetMap = requireObject(targets.targets, 'targets');
+    for (const plugin of capacitorShellProviderPlugins) {
+        if (providerIds.includes(plugin.id) && targetMap[plugin.platform] === undefined) {
+            throw new Error(`--providers ${plugin.id} installs the ${plugin.platform} store plugin into the native `
+                + `shell, but mpgd.targets.json has no ${plugin.platform} target. Add the `
+                + `capacitor-${plugin.platform} target before requesting store providers.`);
+        }
+    }
     for (const [targetName, kind, identityKey] of [
         ['android', 'capacitor-android', 'packageId'],
         ['ios', 'capacitor-ios', 'bundleId'],
@@ -174,11 +226,41 @@ export function planCapacitorShellStarter(input) {
     }
     const requestedProviderIds = input.providerIds === undefined
         && Array.isArray(existingManifest?.requestedProviderIds)
-        ? existingManifest.requestedProviderIds : providerIds;
+        ? existingManifest.requestedProviderIds.filter((id) => typeof id === 'string')
+        : providerIds;
     const requestedBackendUrl = backendUrl ?? (typeof existingManifest?.backendUrl === 'string'
         ? existingManifest.backendUrl : undefined);
+    // Store plugins are pinned to one exact version in the shell and the game:
+    // the game's installed copy when it has one, otherwise the version this CLI
+    // release ships with, which the plan adds to the game as well. The Vite
+    // bundle imports the plugin from the gateway file, and its native code must
+    // match that JavaScript.
+    const providerPlugins = capacitorShellProviderPlugins
+        .filter((plugin) => requestedProviderIds.includes(plugin.id))
+        .map((plugin) => resolveProviderPlugin(gameRoot, gameDependencies, cliDevelopmentDependencies, plugin));
+    const warnings = [];
+    const gatewayFiles = planProviderGatewayWiring(gameRoot, input.templateRoot, providerPlugins, warnings);
+    if (packageContent !== undefined) {
+        const existingShellDependencies = requireObject(parseJsonObject(packageContent, 'existing shell package').dependencies, 'existing shell dependencies');
+        for (const plugin of capacitorShellProviderPlugins) {
+            if (existingShellDependencies[plugin.packageName] !== undefined
+                && !providerPlugins.some((planned) => planned.id === plugin.id)) {
+                warnings.push(`The shell still lists ${plugin.packageName} although ${plugin.id} is no longer `
+                    + 'requested; the initializer never removes a store plugin, so remove it from the '
+                    + 'shell package and resync if the game stopped selling there.');
+            }
+        }
+    }
+    const shellDependencies = {
+        '@capacitor/android': capacitorVersion,
+        '@capacitor/app': appVersion,
+        '@capacitor/core': capacitorVersion,
+        '@capacitor/ios': capacitorVersion,
+        '@mpgd/capacitor-game-services': pluginVersion,
+        ...Object.fromEntries(providerPlugins.map((plugin) => [plugin.packageName, plugin.version])),
+    };
     if (packageContent !== undefined) {
-        assertCompatibleExistingPackage(packageContent, capacitorVersion, appVersion, pluginVersion, typescriptVersion);
+        assertCompatibleExistingPackage(packageContent, shellDependencies, capacitorVersion, typescriptVersion);
     }
     if (configContent !== undefined) {
         const safeConfig = requireStaticCapacitorConfig(configContent);
@@ -205,28 +287,24 @@ export function planCapacitorShellStarter(input) {
         { path: 'mpgd.targets.json', content: json(targets) },
         {
             path: `${shellPath}/package.json`,
-            content: packageContent ?? json({
-                name: `${gamePackageName}-native-shell`,
-                private: true,
-                version: '0.0.0',
-                type: 'module',
-                scripts: {
-                    cap: 'cap',
-                    'sync:android': 'cap sync android',
-                    'sync:ios': 'cap sync ios',
-                },
-                dependencies: {
-                    '@capacitor/android': capacitorVersion,
-                    '@capacitor/app': appVersion,
-                    '@capacitor/core': capacitorVersion,
-                    '@capacitor/ios': capacitorVersion,
-                    '@mpgd/capacitor-game-services': pluginVersion,
-                },
-                devDependencies: {
-                    '@capacitor/cli': capacitorVersion,
-                    typescript: typescriptVersion,
-                },
-            }),
+            content: packageContent === undefined
+                ? json({
+                    name: `${gamePackageName}-native-shell`,
+                    private: true,
+                    version: '0.0.0',
+                    type: 'module',
+                    scripts: {
+                        cap: 'cap',
+                        'sync:android': 'cap sync android',
+                        'sync:ios': 'cap sync ios',
+                    },
+                    dependencies: shellDependencies,
+                    devDependencies: {
+                        '@capacitor/cli': capacitorVersion,
+                        typescript: typescriptVersion,
+                    },
+                })
+                : withPackageDependencies(packageContent, providerPlugins),
         },
         {
             path: `${shellPath}/capacitor.config.ts`,
@@ -253,6 +331,18 @@ export function planCapacitorShellStarter(input) {
                 appId: input.appId,
                 displayName: input.displayName,
                 requestedProviderIds,
+                ...(providerPlugins.length === 0
+                    ? {}
+                    : {
+                        providers: Object.fromEntries(providerPlugins.map((plugin) => [
+                            plugin.id,
+                            {
+                                package: plugin.packageName,
+                                version: plugin.version,
+                                platform: plugin.platform,
+                            },
+                        ])),
+                    }),
                 ...(requestedBackendUrl === undefined ? {} : { backendUrl: requestedBackendUrl }),
             }),
         },
@@ -269,8 +359,11 @@ export function planCapacitorShellStarter(input) {
                 'Existing native files, signing settings, and custom',
                 'ViewControllers are never replaced by mpgd target init capacitor.',
                 '',
-                'requestedProviderIds is selection metadata only: it does not install an',
-                'SDK or report a feature as available. Register provider modules explicitly.',
+                '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',
+                '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.',
                 '',
             ].join('\n'),
@@ -318,6 +411,24 @@ export function planCapacitorShellStarter(input) {
                 : current,
         });
     }
+    requestedFiles.push(...gatewayFiles);
+    // 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) {
+        safeDestination(gameRoot, 'package.json');
+        requestedFiles.push({
+            path: 'package.json',
+            content: json({
+                ...gamePackage,
+                dependencies: {
+                    ...gameDependencies,
+                    ...Object.fromEntries(missingGameDependencies.map((plugin) => [plugin.packageName, plugin.version])),
+                },
+            }),
+        });
+    }
     const nativePlatformsToAdd = ['android', 'ios'].filter((platform) => {
         const nativeDirectory = path.join(gameRoot, shellPath, platform);
         if (!existsSync(nativeDirectory)) {
@@ -342,6 +453,8 @@ export function planCapacitorShellStarter(input) {
         files,
         changedFiles: files.map((file) => file.path),
         nativePlatformsToAdd,
+        providerPlugins,
+        warnings,
     };
 }
 export function assertCapacitorAppId(appId) {
@@ -472,6 +585,15 @@ export function materializeCapacitorShellStarter(plan, runner = { run: runComman
         }
         assertNativePlatformComplete(plan.gameRoot, platform, requireString(manifest.appId, 'shell app ID'), requireString(manifest.displayName, 'shell display name'));
     }
+    // `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)
+            && !plan.nativePlatformsToAdd.includes(platform)
+            && existsSync(path.join(plan.gameRoot, shellPath, platform))) {
+            runner.run('pnpm', ['--dir', shellPath, 'cap', 'sync', platform], plan.gameRoot);
+        }
+    }
     const afterInstall = planCapacitorShellStarter(plan.input);
     if (afterInstall.changedFiles.length > 0 || afterInstall.nativePlatformsToAdd.length > 0) {
         throw new Error('Capacitor shell changed during installation; rerun the initializer.');
@@ -1915,19 +2037,24 @@ function runCommand(command, args, cwd) {
         throw new Error(`${command} ${args.join(' ')} failed. The shell files remain for a safe retry.`);
     }
 }
-function assertCompatibleExistingPackage(source, capacitorVersion, appVersion, pluginVersion, typescriptVersion) {
+function assertCompatibleExistingPackage(source, shellDependencies, capacitorVersion, typescriptVersion) {
     const value = parseJsonObject(source, 'existing shell package');
     if (value.private !== true) {
         throw new Error('Existing Capacitor shell package must stay private.');
     }
     const dependencies = requireObject(value.dependencies, 'existing shell dependencies');
-    for (const [name, version] of Object.entries({
-        '@capacitor/android': capacitorVersion,
-        '@capacitor/app': appVersion,
-        '@capacitor/core': capacitorVersion,
-        '@capacitor/ios': capacitorVersion,
-        '@mpgd/capacitor-game-services': pluginVersion,
-    })) {
+    const providerPackages = new Set(capacitorShellProviderPlugins.map((plugin) => plugin.packageName));
+    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
+        // the game's JavaScript, so it is refused like any other pinned package.
+        if (providerPackages.has(name) && dependencies[name] === undefined) {
+            continue;
+        }
+        if (providerPackages.has(name) && dependencies[name] !== version) {
+            throw new Error(`Existing shell ${name} is ${String(dependencies[name])} but the game uses ${version}; `
+                + 'align the shell package with the game before rerunning.');
+        }
         if (dependencies[name] !== version) {
             throw new Error(`Existing shell ${name} differs; refusing to rewrite dependencies.`);
         }
@@ -2209,6 +2336,156 @@ function assertNotSymlink(file) {
         }
     }
 }
+/**
+ * Adds the requested store plugins to an existing shell package, keeping every
+ * other field as the game wrote it. The content is unchanged when nothing is
+ * missing, so an untouched shell stays out of the change list.
+ */
+function withPackageDependencies(source, plugins) {
+    const value = parseJsonObject(source, 'existing shell package');
+    const dependencies = requireObject(value.dependencies, 'existing shell dependencies');
+    const missing = plugins.filter((plugin) => dependencies[plugin.packageName] === undefined);
+    if (missing.length === 0) {
+        return source;
+    }
+    return json({
+        ...value,
+        dependencies: {
+            ...dependencies,
+            ...Object.fromEntries(missing.map((plugin) => [plugin.packageName, plugin.version])),
+        },
+    });
+}
+/**
+ * Resolves one requested store plugin to the exact version the shell and the
+ * game pin: the game's installed copy, or, when the game does not declare the
+ * plugin yet, the version this CLI release ships with (its published dev
+ * dependency, or the plugin package of the kit checkout it runs from). A
+ * declared but uninstalled plugin, or one whose peers the game's installed
+ * kit packages do not satisfy, is refused before anything is written.
+ */
+function resolveProviderPlugin(gameRoot, gameDependencies, cliDevelopmentDependencies, plugin) {
+    const installedFile = path.join(gameRoot, 'node_modules', plugin.packageName, 'package.json');
+    let version;
+    let versionSource;
+    let peerDependencies;
+    if (existsSync(installedFile)) {
+        const installed = readJsonObject(installedFile);
+        version = requireString(installed.version, `installed ${plugin.packageName} version`);
+        versionSource = 'installed';
+        peerDependencies = installed.peerDependencies;
+    }
+    else if (gameDependencies[plugin.packageName] !== undefined) {
+        throw new Error(`The game declares ${plugin.packageName} but it is not installed; install game `
+            + 'dependencies before initializing the shell.');
+    }
+    else {
+        const kitPackageFile = fileURLToPath(new URL(`../../../${plugin.packageDir}/package.json`, import.meta.url));
+        const kitPackage = existsSync(kitPackageFile) ? readJsonObject(kitPackageFile) : undefined;
+        const published = cliDevelopmentDependencies[plugin.packageName];
+        const known = typeof published === 'string' && valid(published) !== null
+            ? published
+            : kitPackage?.name === plugin.packageName
+                ? kitPackage.version
+                : undefined;
+        if (typeof known !== 'string') {
+            throw new Error(`Provider ${plugin.id} needs ${plugin.packageName}, and this CLI does not know which `
+                + `version to install; add it to the game (pnpm add ${plugin.packageName}) and rerun.`);
+        }
+        version = known;
+        versionSource = 'kit';
+        peerDependencies = kitPackage?.peerDependencies;
+    }
+    if (valid(version) === null || version.includes('+')) {
+        throw new Error(`${plugin.packageName} must resolve to a concrete version, not ${version}.`);
+    }
+    if (typeof peerDependencies === 'object' && peerDependencies !== null) {
+        // Every declared peer the game has installed must satisfy the plugin's
+        // range (Capacitor core, the bridge, the adapter, and the platform alike),
+        // so an incompatible host is refused before the shell or gateway is written.
+        for (const [peer, range] of Object.entries(peerDependencies)) {
+            const peerFile = path.join(gameRoot, 'node_modules', peer, 'package.json');
+            if (typeof range !== 'string' || !existsSync(peerFile)) {
+                continue;
+            }
+            const peerVersion = readJsonObject(peerFile).version;
+            if (typeof peerVersion === 'string' && valid(peerVersion) !== null
+                && !satisfies(peerVersion, range, { includePrerelease: true })) {
+                throw new Error(`Provider ${plugin.id} (${plugin.packageName}@${version}) needs ${peer} ${range}, but `
+                    + `the game has ${peerVersion}; upgrade the game's kit packages (mpgd kit upgrade) first.`);
+            }
+        }
+    }
+    return { ...plugin, version, versionSource };
+}
+/**
+ * Plans the gateway wiring for the requested store plugins. A gateway that
+ * already imports the plugin is left alone; a gateway that is still the
+ * unwired template gateway is replaced by the template's wired gateway, with
+ * the support modules it imports written when the game has none; every other
+ * gateway is game-owned, so the plan only warns. Nothing here can enable a
+ * purchase: the wired gateway registers the store provider, and grants still
+ * come from the backend ledger through the reconciler.
+ */
+function planProviderGatewayWiring(gameRoot, templateRoot, plugins, warnings) {
+    const planned = new Map();
+    for (const plugin of plugins) {
+        const current = readExisting(safeDestination(gameRoot, plugin.gatewayFile));
+        // Wired means the gateway calls the plugin's service-provider factory; a
+        // type-only or unused import of the package does not register anything.
+        if (current !== undefined && new RegExp(`\\b${plugin.gatewayFactory}\\s*\\(`, 'u').test(current)) {
+            continue;
+        }
+        const register = `register ${plugin.gatewayFactory} from ${plugin.packageName} there so the `
+            + 'shell plugin is used';
+        if (current === undefined) {
+            warnings.push(`${plugin.gatewayFile} is missing; ${register}.`);
+            continue;
+        }
+        const legacy = plugin.legacyGatewaySources.includes(current.replace(/\r\n/gu, '\n'));
+        if (!legacy || templateRoot === undefined) {
+            warnings.push(`${plugin.gatewayFile} does not call ${plugin.gatewayFactory}; ${register}.`);
+            continue;
+        }
+        const support = new Map();
+        let kept;
+        for (const file of capacitorShellProviderSupportFiles) {
+            const existing = readExisting(safeDestination(gameRoot, file));
+            const template = readTemplateFile(templateRoot, file);
+            if (existing === undefined) {
+                support.set(file, template);
+            }
+            else if (existing !== template) {
+                kept = file;
+                break;
+            }
+        }
+        if (kept !== undefined) {
+            warnings.push(`${plugin.gatewayFile} was not rewritten because the game-owned ${kept} differs from `
+                + `the template; ${register}.`);
+            continue;
+        }
+        planned.set(plugin.gatewayFile, readTemplateFile(templateRoot, plugin.gatewayFile));
+        for (const [file, content] of support) {
+            planned.set(file, content);
+        }
+    }
+    return [...planned].map(([file, content]) => ({ path: file, content }));
+}
+/** A regular file of the CLI's game template, read without leaving the template root. */
+function readTemplateFile(templateRoot, relative) {
+    const root = realpathSync(templateRoot);
+    const file = path.resolve(root, relative);
+    const within = path.relative(root, file);
+    if (within === '' || within.startsWith('..') || path.isAbsolute(within)) {
+        throw new Error(`Game template path escapes the template root: ${relative}`);
+    }
+    if (!existsSync(file) || !lstatSync(file).isFile()
+        || path.relative(root, realpathSync(file)).startsWith('..')) {
+        throw new Error(`Game template file is missing: ${relative}`);
+    }
+    return readFileSync(file, 'utf8');
+}
 function resolveInstalledPluginVersion(gameRoot, requirement) {
     const adapterRoot = path.dirname(realpathSync(path.join(gameRoot, 'node_modules/@mpgd/adapter-capacitor/package.json')));
     const installedPackage = path.join(adapterRoot, 'node_modules/@mpgd/capacitor-game-services/package.json');

package/dist/index.js

@@ -73,6 +73,8 @@ const mpgdTemplateDependencyPackages = [
     { name: '@mpgd/adapter-verse8', packageDir: 'adapters/verse8' },
     { name: '@mpgd/analytics', packageDir: 'packages/analytics' },
     { name: '@mpgd/bridge', packageDir: 'packages/bridge' },
+    { name: '@mpgd/capacitor-play-billing', packageDir: 'native-plugins/capacitor-play-billing' },
+    { name: '@mpgd/capacitor-storekit', packageDir: 'native-plugins/capacitor-storekit' },
     { name: '@mpgd/catalog', packageDir: 'packages/catalog' },
     { name: '@mpgd/cli', packageDir: 'packages/cli' },
     { name: '@mpgd/game-services', packageDir: 'packages/game-services' },
@@ -1558,8 +1560,8 @@ const targetCommand = defineI18n({
                     ko: '프로덕션 HTTPS Game Services 기본 URL.',
                 },
                 providers: {
-                    en: 'Comma-separated requested provider IDs; this does not install SDKs.',
-                    ko: '쉼표로 구분한 요청 provider ID. SDK를 설치하지는 않습니다.',
+                    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는 기록만 합니다.',
                 },
             }),
             args: {
@@ -1607,7 +1609,7 @@ const targetCommand = defineI18n({
                 providers: {
                     type: 'string',
                     required: false,
-                    description: 'Comma-separated requested provider IDs; this does not install SDKs.',
+                    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.',
                 },
             },
             run: (ctx) => {
@@ -1631,6 +1633,7 @@ const targetCommand = defineI18n({
                         gameRoot,
                         appId,
                         displayName,
+                        templateRoot: gameTemplateDir,
                         ...(iconSource === undefined ? {} : { iconSource }),
                         ...(backendUrl === undefined ? {} : { backendUrl }),
                         ...(selectedProviders === undefined ? {} : {
@@ -1647,18 +1650,33 @@ const targetCommand = defineI18n({
                     for (const platform of plan.nativePlatformsToAdd) {
                         console.info(`${dryRun ? 'Would add' : 'Added'} native platform: ${platform}`);
                     }
-                    console.info('File count covers managed shell files only; pnpm may also update root or shell lockfiles.');
+                    for (const plugin of plan.providerPlugins) {
+                        console.info(`${dryRun ? 'Would install' : 'Installed'} ${plugin.platform} store plugin `
+                            + `${plugin.packageName}@${plugin.version} (${plugin.id}) into the shell`
+                            + `${plugin.versionSource === 'kit' ? ' and the game' : ''}`
+                            + `${dryRun ? '; cap add or cap sync registers it' : ''}.`);
+                    }
+                    for (const warning of plan.warnings) {
+                        console.warn(`Warning: ${warning}`);
+                    }
+                    console.info('File count covers managed shell and game files only; pnpm may also update root or shell lockfiles.');
                     if (!dryRun) {
                         console.info('Production native builds still require release identity and signing checks.');
                     }
                     return;
                 }
+                if (ctx.values.providers !== undefined) {
+                    throw new Error('--providers is only available for capacitor initialization: it installs the '
+                        + 'play-billing (Android) and storekit (iOS) store plugins into the game-owned '
+                        + `native shell, which ${requestedTarget} does not initialize. Run `
+                        + '"mpgd target init capacitor --providers ..." instead.');
+                }
                 const target = normalizeConfiguredBuildTarget(requestedTarget);
                 if (target !== 'microsoft-store') {
                     throw new Error(`Target initialization is only available for microsoft-store; received: ${requestedTarget}`);
                 }
                 for (const option of [
-                    'app-id', 'display-name', 'icon-source', 'backend-url', 'providers',
+                    'app-id', 'display-name', 'icon-source', 'backend-url',
                 ]) {
                     if (ctx.values[option] !== undefined) {
                         throw new Error(`--${option} is only available for capacitor initialization.`);

package/dist/native-build-info.json

@@ -1,5 +1,5 @@
 {
-  "kitGitSha": "2f70328e9199e406211c43ba22efa349d683e9f3",
+  "kitGitSha": "a54c0341749bb93a97ddd927205de960294c6511",
   "kitDirty": false,
-  "packageVersion": "0.45.0"
+  "packageVersion": "0.47.0"
 }