@mpgd/cli 0.61.1 → 0.63.0

package/dist/app-store-iap-asc.d.ts

@@ -0,0 +1,23 @@
+import type { AscIapPort } from './app-store-iap-port.js';
+/**
+* The in-app purchase port on the pinned `asc` 5.5.0 CLI, with the same
+* binary pin, isolated environment and API key as the TestFlight
+* submission. Each method is one `asc ... --output json` command; the JSON
+* is App Store Connect's own resource document, which `asc` prints as it
+* received it (`internal/asc/types/resources.go` at the 5.5.0 tag).
+*/
+/** Runs one asc command with `--output json` appended and returns the parsed JSON. */
+export type AscCommandRunner = (args: readonly string[], timeoutMs: number) => Promise<unknown>;
+export interface AscCredential {
+  readonly ascBinary: string;
+  readonly apiKeyId: string;
+  readonly apiIssuerId: string;
+  readonly apiPrivateKeyBase64: string;
+}
+/** Copy and verify the pinned binary into a private directory; `close` removes it. */
+export declare function openAscIapSession(credential: AscCredential, signal?: AbortSignal): Promise<{
+  readonly port: AscIapPort;
+  close(): void;
+}>;
+/** The port over any runner; the tests drive it with recorded asc output. */
+export declare function createAscIapPort(run: AscCommandRunner, today?: () => string): AscIapPort;

package/dist/app-store-iap-asc.js

@@ -0,0 +1,326 @@
+import { chmodSync, copyFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { ReleaseProcessError, runReleaseProcess } from './deploy-process.js';
+import { sameDecimal } from './store-products.js';
+import { isolatedAscEnvironment, verifyPinnedAscBinary } from './testflight-submission.js';
+const lookupTimeoutMs = 60_000;
+const listTimeoutMs = 3 * 60_000;
+const uploadTimeoutMs = 10 * 60_000;
+const maxJsonBytes = 8 * 1024 * 1024;
+/** asc exit code for an App Store Connect 404 (`cmd/exit_codes.go`, 5.5.0). */
+const ascExitNotFound = 4;
+/** Copy and verify the pinned binary into a private directory; `close` removes it. */
+export async function openAscIapSession(credential, signal) {
+    if (!path.isAbsolute(credential.ascBinary)) {
+        throw new Error('asc binary must be an absolute file path.');
+    }
+    const tempRoot = mkdtempSync(path.join(tmpdir(), 'mpgd-asc-iap-'));
+    try {
+        const binary = path.join(tempRoot, 'asc');
+        copyFileSync(credential.ascBinary, binary);
+        chmodSync(binary, 0o700);
+        await verifyPinnedAscBinary(binary);
+        const environment = isolatedAscEnvironment(credential, tempRoot);
+        const run = async (args, timeoutMs) => {
+            const result = await runReleaseProcess({
+                command: binary,
+                args: [...args, '--output', 'json'],
+                cwd: tempRoot,
+                environment,
+                timeoutMs,
+                maxOutputBytes: maxJsonBytes,
+                captureMachineStdout: true,
+                secretValues: [credential.apiKeyId, credential.apiIssuerId, credential.apiPrivateKeyBase64],
+                signal,
+            });
+            if (result.truncated || result.machineStdout === undefined) {
+                throw new Error('asc JSON output was truncated or unavailable.');
+            }
+            try {
+                return JSON.parse(result.machineStdout);
+            }
+            catch {
+                throw new Error('asc returned invalid JSON.');
+            }
+        };
+        return {
+            port: createAscIapPort(run),
+            close: () => rmSync(tempRoot, { recursive: true, force: true }),
+        };
+    }
+    catch (error) {
+        rmSync(tempRoot, { recursive: true, force: true });
+        throw error;
+    }
+}
+/** The port over any runner; the tests drive it with recorded asc output. */
+export function createAscIapPort(run, today = () => new Date().toISOString().slice(0, 10)) {
+    const optional = async (args) => {
+        try {
+            return await run(args, lookupTimeoutMs);
+        }
+        catch (error) {
+            if (error instanceof ReleaseProcessError && error.exitCode === ascExitNotFound) {
+                return undefined;
+            }
+            throw error;
+        }
+    };
+    return {
+        async readAppBundleId(appId) {
+            const app = single(await run(['apps', 'view', '--id', appId], lookupTimeoutMs), 'apps view');
+            const bundleId = app.attributes.bundleId;
+            if (app.id !== appId || typeof bundleId !== 'string') {
+                throw new Error('asc apps view returned no bundle ID for the app.');
+            }
+            return bundleId;
+        },
+        async listIaps(appId) {
+            return list(await run(['iap', 'list', '--app', appId, '--paginate'], listTimeoutMs), 'iap list')
+                .map((resource) => ({
+                id: resource.id,
+                productId: requiredString(resource.attributes.productId, 'iap list productId'),
+                name: requiredString(resource.attributes.name, 'iap list name'),
+                inAppPurchaseType: requiredString(resource.attributes.inAppPurchaseType, 'iap list type'),
+                ...optionalString('state', resource.attributes.state),
+                ...optionalString('reviewNote', resource.attributes.reviewNote),
+                ...(resource.attributes.familySharable === true ? { familySharable: true } : {}),
+            }));
+        },
+        async listVersions(iapId) {
+            return list(await run(['iap', 'versions', 'list', '--iap-id', iapId, '--paginate'], listTimeoutMs), 'iap versions list').map((resource) => ({
+                id: resource.id,
+                ...(typeof resource.attributes.version === 'number' ? { version: resource.attributes.version } : {}),
+                ...optionalString('state', resource.attributes.state),
+            }));
+        },
+        async listLocalizations(versionId) {
+            return list(await run(['iap', 'versions', 'localizations', 'list', '--version-id', versionId, '--paginate'], listTimeoutMs), 'iap versions localizations list').map((resource) => ({
+                id: resource.id,
+                locale: requiredString(resource.attributes.locale, 'localization locale'),
+                name: requiredString(resource.attributes.name, 'localization name'),
+                ...optionalString('description', resource.attributes.description),
+            }));
+        },
+        async readPriceSchedule(iapId) {
+            const response = await optional(['iap', 'pricing', 'schedules', 'view', '--iap-id', iapId, '--include', 'baseTerritory']);
+            // No schedule: asc exits 4 (not found), or App Store Connect answers with no resource.
+            if (response === undefined || isEmptyResource(response)) {
+                return undefined;
+            }
+            const schedule = single(response, 'iap pricing schedules view');
+            const baseTerritory = relationshipId(schedule.relationships, 'baseTerritory');
+            const resolved = await run(['iap', 'pricing', 'schedules', 'manual-prices', '--schedule-id', schedule.id, '--resolved'], listTimeoutMs);
+            if (!isRecord(resolved) || !Array.isArray(resolved.prices)) {
+                throw new Error('asc iap pricing schedules manual-prices returned no prices.');
+            }
+            const manualPrices = resolved.prices.flatMap((row) => isRecord(row) && row.manual === true && typeof row.territory === 'string'
+                && typeof row.customerPrice === 'string'
+                ? [{ territory: row.territory, customerPrice: row.customerPrice }]
+                : []);
+            if (baseTerritory === undefined && manualPrices.length === 0) {
+                return undefined;
+            }
+            // `--resolved` lists only prices in effect; the raw list also holds future ones.
+            const all = list(await run(['iap', 'pricing', 'schedules', 'manual-prices', '--schedule-id', schedule.id, '--paginate'], listTimeoutMs), 'iap pricing schedules manual-prices');
+            const now = today();
+            // A future start or a future end (a temporary price expiring) is a
+            // transition a new open-ended schedule would remove.
+            const upcoming = (value) => typeof value === 'string' && value.slice(0, 10) > now;
+            const scheduledChanges = all.filter((price) => upcoming(price.attributes.startDate) || upcoming(price.attributes.endDate)).length;
+            return {
+                id: schedule.id,
+                ...(baseTerritory === undefined ? {} : { baseTerritory }),
+                manualPrices,
+                scheduledChanges,
+            };
+        },
+        async readAvailability(iapId) {
+            let response;
+            try {
+                response = await run(['iap', 'pricing', 'availability', 'view', '--iap-id', iapId], lookupTimeoutMs);
+            }
+            catch (error) {
+                // asc 5.5.0 reports an unset availability as an error naming it (availability.go).
+                if (error instanceof ReleaseProcessError
+                    && (error.exitCode === ascExitNotFound || error.output.includes('has no availability configured'))) {
+                    return undefined;
+                }
+                throw error;
+            }
+            if (isEmptyResource(response)) {
+                return undefined;
+            }
+            const availability = single(response, 'iap pricing availability view');
+            const territories = list(await run(['iap', 'pricing', 'availabilities', 'available-territories', '--id', availability.id, '--paginate'], listTimeoutMs), 'iap pricing availabilities available-territories').map((territory) => territory.id);
+            return {
+                id: availability.id,
+                availableInNewTerritories: availability.attributes.availableInNewTerritories === true,
+                territories,
+            };
+        },
+        async readReviewScreenshot(iapId) {
+            const response = await optional(['iap', 'review-screenshots', 'view', '--iap-id', iapId]);
+            if (!isRecord(response) || !isRecord(response.data) || typeof response.data.id !== 'string'
+                || response.data.id === '') {
+                return undefined;
+            }
+            const attributes = isRecord(response.data.attributes) ? response.data.attributes : {};
+            return {
+                id: response.data.id,
+                ...optionalString('fileName', attributes.fileName),
+                ...(typeof attributes.fileSize === 'number' ? { fileSize: attributes.fileSize } : {}),
+                ...optionalString('sourceFileChecksum', attributes.sourceFileChecksum),
+                ...optionalString('deliveryState', isRecord(attributes.assetDeliveryState) ? attributes.assetDeliveryState.state : undefined),
+            };
+        },
+        async listTerritories() {
+            const territories = list(await run(['pricing', 'territories', 'list', '--paginate'], listTimeoutMs), 'pricing territories list').map((resource) => resource.id);
+            if (territories.length === 0) {
+                throw new Error('asc pricing territories list returned no territories.');
+            }
+            return territories;
+        },
+        async createIap(input) {
+            const created = single(await run([
+                'iap', 'create',
+                '--app', input.appId,
+                '--type', input.type,
+                '--ref-name', input.referenceName,
+                '--product-id', input.productId,
+                ...(input.familySharable ? ['--family-sharable'] : []),
+            ], lookupTimeoutMs), 'iap create');
+            return created.id;
+        },
+        async updateIap(input) {
+            await run([
+                'iap', 'update',
+                '--id', input.iapId,
+                ...(input.referenceName === undefined ? [] : ['--ref-name', input.referenceName]),
+                ...(input.familySharable === true ? ['--family-sharable'] : []),
+            ], lookupTimeoutMs);
+        },
+        async createVersion(iapId) {
+            return single(await run(['iap', 'versions', 'create', '--iap-id', iapId], lookupTimeoutMs), 'iap versions create').id;
+        },
+        async createLocalization(input) {
+            await run([
+                'iap', 'versions', 'localizations', 'create',
+                '--version-id', input.versionId,
+                '--locale', input.locale,
+                '--name', input.name,
+                '--description', input.description,
+            ], lookupTimeoutMs);
+        },
+        async updateLocalization(input) {
+            await run([
+                'iap', 'versions', 'localizations', 'update',
+                '--localization-id', input.localizationId,
+                '--name', input.name,
+                '--description', input.description,
+            ], lookupTimeoutMs);
+        },
+        async findPricePoint(input) {
+            const points = list(await run([
+                'iap', 'pricing', 'price-points', 'list',
+                '--iap-id', input.iapId,
+                '--territory', input.territory,
+                '--price', input.customerPrice,
+                '--paginate',
+            ], listTimeoutMs), 'iap pricing price-points list').filter((point) => typeof point.attributes.customerPrice === 'string'
+                && sameDecimal(point.attributes.customerPrice, input.customerPrice));
+            const [point] = points;
+            if (points.length !== 1 || point === undefined) {
+                throw new Error(`App Store Connect has ${points.length} price points of ${input.customerPrice} in ${input.territory}; `
+                    + 'use a price that is an App Store price point there.');
+            }
+            return point.id;
+        },
+        async createPriceSchedule(input) {
+            await run([
+                'iap', 'pricing', 'schedules', 'create',
+                '--iap-id', input.iapId,
+                '--base-territory', input.baseTerritory,
+                '--prices', input.pricePointIds.join(','),
+            ], lookupTimeoutMs);
+        },
+        async setAvailability(input) {
+            await run([
+                'iap', 'pricing', 'availability', 'set',
+                '--iap-id', input.iapId,
+                '--territories', input.territories.join(','),
+                ...(input.availableInNewTerritories ? ['--available-in-new-territories'] : []),
+            ], lookupTimeoutMs);
+        },
+        async deleteReviewScreenshot(screenshotId) {
+            await run(['iap', 'review-screenshots', 'delete', '--screenshot-id', screenshotId, '--confirm'], lookupTimeoutMs);
+        },
+        async uploadReviewScreenshot(input) {
+            await run(['iap', 'review-screenshots', 'create', '--iap-id', input.iapId, '--file', input.file], uploadTimeoutMs);
+        },
+    };
+}
+function single(value, command) {
+    const resource = isRecord(value) ? toResource(value.data) : undefined;
+    if (resource === undefined) {
+        throw new Error(`asc ${command} returned no resource.`);
+    }
+    return resource;
+}
+function list(value, command) {
+    const resources = isRecord(value) && Array.isArray(value.data)
+        ? value.data.map(toResource)
+        : undefined;
+    if (resources === undefined || resources.some((resource) => resource === undefined)) {
+        throw new Error(`asc ${command} returned no resource list.`);
+    }
+    return resources;
+}
+function toResource(value) {
+    if (!isRecord(value) || typeof value.id !== 'string' || value.id === '') {
+        return undefined;
+    }
+    return {
+        id: value.id,
+        attributes: isRecord(value.attributes) ? value.attributes : {},
+        ...(value.relationships === undefined ? {} : { relationships: value.relationships }),
+    };
+}
+/**
+ * App Store Connect's `data: null`, or asc's rendering of it: asc 5.5.0
+ * decodes into a non-pointer resource and prints `{ "type": "", "id": "" }`.
+ */
+function isEmptyResource(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return value.data === null
+        || (isRecord(value.data) && (value.data.id === undefined || value.data.id === ''));
+}
+function relationshipId(relationships, name) {
+    if (!isRecord(relationships)) {
+        return undefined;
+    }
+    const relationship = relationships[name];
+    if (!isRecord(relationship) || !isRecord(relationship.data)) {
+        return undefined;
+    }
+    return typeof relationship.data.id === 'string' ? relationship.data.id : undefined;
+}
+function requiredString(value, label) {
+    if (typeof value !== 'string') {
+        throw new Error(`asc output has no ${label}.`);
+    }
+    return value;
+}
+function optionalString(key, value) {
+    const result = {};
+    if (typeof value === 'string' && value !== '') {
+        result[key] = value;
+    }
+    return result;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/app-store-iap-port.d.ts

@@ -0,0 +1,125 @@
+/**
+* App Store Connect in-app purchase port. The kit drives App Store Connect
+* through the pinned `asc` CLI (docs/NATIVE_DEPLOY_TOOLING_DECISION.md);
+* `app-store-iap-asc.ts` implements this port with it, and the planner and
+* tests see only these shapes.
+*
+* Resources (App Store Connect API 4.4.1):
+* - In-app purchases v2: https://developer.apple.com/documentation/appstoreconnectapi/in-app-purchases
+* - Versions and their localizations: https://developer.apple.com/documentation/appstoreconnectapi/in-app-purchase-versions
+* - Price schedules: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-inapppurchasepriceschedules
+* - Availability: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-inapppurchaseavailabilities
+* - Review screenshot: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-inapppurchaseappstorereviewscreenshots
+*/
+export type AscIapType = 'CONSUMABLE' | 'NON_CONSUMABLE';
+export interface AscIap {
+  readonly id: string;
+  readonly productId: string;
+  /** Reference name. */
+  readonly name: string;
+  readonly inAppPurchaseType: string;
+  /** `InAppPurchaseState`, for example `MISSING_METADATA` or `APPROVED`. */
+  readonly state?: string | undefined;
+  readonly familySharable?: boolean | undefined;
+  readonly reviewNote?: string | undefined;
+}
+export interface AscIapVersion {
+  readonly id: string;
+  readonly version?: number | undefined;
+  /** `PREPARE_FOR_SUBMISSION`, `READY_FOR_REVIEW`, `WAITING_FOR_REVIEW`, `APPROVED`, ... */
+  readonly state?: string | undefined;
+}
+export interface AscIapLocalization {
+  readonly id: string;
+  readonly locale: string;
+  readonly name: string;
+  readonly description?: string | undefined;
+}
+/** The current price schedule: base territory and the manual prices in effect. */
+export interface AscIapPriceSchedule {
+  readonly id: string;
+  readonly baseTerritory?: string | undefined;
+  /** Manual (not equalized) prices in effect now, per alpha-3 territory. */
+  readonly manualPrices: readonly {
+    readonly territory: string;
+    readonly customerPrice: string;
+  }[];
+  /** Manual prices that start in the future; a new schedule would drop them. */
+  readonly scheduledChanges: number;
+}
+export interface AscIapAvailability {
+  readonly id: string;
+  readonly availableInNewTerritories: boolean;
+  /** Alpha-3 territories the in-app purchase is sold in. */
+  readonly territories: readonly string[];
+}
+export interface AscIapReviewScreenshot {
+  readonly id: string;
+  readonly fileName?: string | undefined;
+  readonly fileSize?: number | undefined;
+  /** MD5 of the uploaded file, as App Store Connect records it. */
+  readonly sourceFileChecksum?: string | undefined;
+  /** `assetDeliveryState.state`: `AWAITING_UPLOAD`, `UPLOAD_COMPLETE`, `COMPLETE` or `FAILED`. */
+  readonly deliveryState?: string | undefined;
+}
+export interface AscIapPort {
+  /** The app record's bundle ID (`apps view`). */
+  readAppBundleId(appId: string): Promise<string>;
+  listIaps(appId: string): Promise<AscIap[]>;
+  listVersions(iapId: string): Promise<AscIapVersion[]>;
+  listLocalizations(versionId: string): Promise<AscIapLocalization[]>;
+  /** `undefined` when the in-app purchase has no price schedule yet. */
+  readPriceSchedule(iapId: string): Promise<AscIapPriceSchedule | undefined>;
+  /** `undefined` when no availability was set. */
+  readAvailability(iapId: string): Promise<AscIapAvailability | undefined>;
+  /** `undefined` when no review screenshot was uploaded. */
+  readReviewScreenshot(iapId: string): Promise<AscIapReviewScreenshot | undefined>;
+  /** Every App Store territory (alpha-3). */
+  listTerritories(): Promise<string[]>;
+  createIap(input: {
+    readonly appId: string;
+    readonly type: AscIapType;
+    readonly referenceName: string;
+    readonly productId: string;
+    readonly familySharable: boolean;
+  }): Promise<string>;
+  updateIap(input: {
+    readonly iapId: string;
+    readonly referenceName?: string;
+    readonly familySharable?: true;
+  }): Promise<void>;
+  createVersion(iapId: string): Promise<string>;
+  createLocalization(input: {
+    readonly versionId: string;
+    readonly locale: string;
+    readonly name: string;
+    readonly description: string;
+  }): Promise<void>;
+  updateLocalization(input: {
+    readonly localizationId: string;
+    readonly name: string;
+    readonly description: string;
+  }): Promise<void>;
+  /** The price point of `customerPrice` in `territory`; throws unless exactly one matches. */
+  findPricePoint(input: {
+    readonly iapId: string;
+    readonly territory: string;
+    readonly customerPrice: string;
+  }): Promise<string>;
+  /** A new schedule effective now: the base territory's and the manual prices. */
+  createPriceSchedule(input: {
+    readonly iapId: string;
+    readonly baseTerritory: string;
+    readonly pricePointIds: readonly string[];
+  }): Promise<void>;
+  setAvailability(input: {
+    readonly iapId: string;
+    readonly territories: readonly string[];
+    readonly availableInNewTerritories: boolean;
+  }): Promise<void>;
+  deleteReviewScreenshot(screenshotId: string): Promise<void>;
+  uploadReviewScreenshot(input: {
+    readonly iapId: string;
+    readonly file: string;
+  }): Promise<void>;
+}

package/dist/app-store-iap-port.js

@@ -0,0 +1,14 @@
+/**
+ * App Store Connect in-app purchase port. The kit drives App Store Connect
+ * through the pinned `asc` CLI (docs/NATIVE_DEPLOY_TOOLING_DECISION.md);
+ * `app-store-iap-asc.ts` implements this port with it, and the planner and
+ * tests see only these shapes.
+ *
+ * Resources (App Store Connect API 4.4.1):
+ * - In-app purchases v2: https://developer.apple.com/documentation/appstoreconnectapi/in-app-purchases
+ * - Versions and their localizations: https://developer.apple.com/documentation/appstoreconnectapi/in-app-purchase-versions
+ * - Price schedules: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-inapppurchasepriceschedules
+ * - Availability: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-inapppurchaseavailabilities
+ * - Review screenshot: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-inapppurchaseappstorereviewscreenshots
+ */
+export {};

package/dist/capacitor-shell-starter.js

@@ -11,6 +11,7 @@ import { addIosAppResource, applyAndroidManifestAdId, applyAndroidManifestOrient
 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';
+import { planNotificationsBuildApprovals } from './pnpm-build-approvals.js';
 const shellPath = 'apps/mobile-capacitor';
 const webPath = `${shellPath}/www`;
 const referenceShellPath = '${MPGD_KIT_PATH}/apps/mobile-capacitor';
@@ -500,6 +501,17 @@ export function planCapacitorShellStarter(input) {
         });
     }
     requestedFiles.push(...gatewayFiles);
+    if (notifications !== undefined) {
+        // pnpm 11 fails an install on an unreviewed dependency build script, and
+        // the firebase package notifications add brings two.
+        const approvals = planNotificationsBuildApprovals(readExisting(safeDestination(gameRoot, 'pnpm-workspace.yaml')));
+        if (approvals.content !== undefined) {
+            requestedFiles.push({ path: 'pnpm-workspace.yaml', content: approvals.content });
+        }
+        if (approvals.warning !== undefined) {
+            warnings.push(approvals.warning);
+        }
+    }
     // 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.
@@ -668,7 +680,12 @@ export function materializeCapacitorShellStarter(plan, runner = { run: runComman
     // workspace globs. Always retry its standalone install: a CLI shim alone
     // does not prove that an interrupted dependency install completed.
     runner.run('pnpm', ['install', '--no-frozen-lockfile'], plan.gameRoot);
-    runner.run('pnpm', ['--dir', shellPath, 'install', '--ignore-workspace', '--no-frozen-lockfile'], plan.gameRoot);
+    runner.run('pnpm', 
+    // --ignore-workspace also drops every pnpm-workspace.yaml setting, so no
+    // allowBuilds entry can review a dependency build script here and pnpm 11
+    // fails on any (firebase brings two when the shell resolves it). The
+    // shell's packages need none: Gradle and Xcode build the native code.
+    ['--dir', shellPath, 'install', '--ignore-workspace', '--ignore-scripts', '--no-frozen-lockfile'], plan.gameRoot);
     for (const platform of plan.nativePlatformsToAdd) {
         const generatedNow = !existsSync(path.join(plan.gameRoot, shellPath, platform));
         if (generatedNow) {

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

@@ -14,9 +14,11 @@ 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).
+* The iOS dSYM note: the plugin captures crashes once `GoogleService-Info.plist`
+* is in the App target, and readable native stack traces need the dSYMs
+* uploaded. `mpgd deploy run` records and uploads them for the archives it
+* builds; an archive made another way needs Firebase's run script or
+* `upload-symbols` (docs/CRASH_REPORTING.md#symbols).
 */
 export declare const crashReportingIosSteps: readonly string[];
 export interface PlannedCrashReporting {

package/dist/crash-reporting-starter.js

@@ -31,15 +31,18 @@ export const crashReportingAndroidSteps = Object.freeze([
     `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).
+ * The iOS dSYM note: the plugin captures crashes once `GoogleService-Info.plist`
+ * is in the App target, and readable native stack traces need the dSYMs
+ * uploaded. `mpgd deploy run` records and uploads them for the archives it
+ * builds; an archive made another way needs Firebase's run script or
+ * `upload-symbols` (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.',
+    'dSYMs: mpgd deploy run uploads them for every App Store build it makes (retry with mpgd '
+        + 'deploy symbols). For an archive made in Xcode or another pipeline, 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 the '
+        + 'archive; see docs/CRASH_REPORTING.md in mpgd-kit.',
 ]);
 /**
  * Plan the crash-reporting provider before anything is written. Refused when

package/dist/crash-symbols-upload.d.ts

@@ -0,0 +1,67 @@
+import { type ReleaseProcessInput, type ReleaseProcessResult } from './deploy-process.js';
+import type { NativeDsymIdentity } from './native-build-symbols.js';
+import { readNativeReleaseStatus, recordCrashSymbolUpload, type CrashSymbolUploadRecord } from './release-state.js';
+export interface CrashSymbolUploadPlan {
+  readonly releaseKey: string;
+  readonly buildRunId: string;
+  readonly dsymArchiveSha256: string;
+  readonly dsyms: readonly NativeDsymIdentity[];
+  /** `upload-symbols` and its arguments, with the recorded (game-relative) files. */
+  readonly command: readonly string[];
+}
+export type CrashSymbolUploadResult = {
+  readonly status: 'not-applicable';
+  readonly reason: string;
+} | {
+  readonly status: 'already-uploaded';
+  readonly upload: CrashSymbolUploadRecord;
+} | {
+  readonly status: 'planned';
+  readonly plan: CrashSymbolUploadPlan;
+} | {
+  readonly status: 'uploaded';
+  readonly plan: CrashSymbolUploadPlan;
+  /** Absent when the upload succeeded but its outcome could not be recorded. */
+  readonly upload?: CrashSymbolUploadRecord;
+  /** Why the successful upload could not be recorded; a retry uploads again. */
+  readonly recordError?: string;
+  readonly output: string;
+} | {
+  readonly status: 'failed';
+  readonly plan: CrashSymbolUploadPlan;
+  readonly error: string;
+  readonly output: string;
+  /** Absent when the failure itself could not be recorded. */
+  readonly upload?: CrashSymbolUploadRecord;
+};
+export interface UploadRecordedCrashSymbolsInput {
+  readonly gameRoot: string;
+  readonly gameId: string;
+  readonly releaseKey: string;
+  /** Print the planned upload; run nothing and record nothing. */
+  readonly dryRun?: boolean;
+  readonly environment?: NodeJS.ProcessEnv;
+  readonly signal?: AbortSignal;
+}
+/** Injection boundary for tests; production uses the release state and a child process. */
+export interface CrashSymbolUploadPorts {
+  readonly readStatus: typeof readNativeReleaseStatus;
+  readonly recordUpload: typeof recordCrashSymbolUpload;
+  readonly run: (input: ReleaseProcessInput) => Promise<ReleaseProcessResult>;
+  readonly platform: NodeJS.Platform;
+}
+/** Upload (or, with `dryRun`, plan) the Crashlytics dSYMs of one recorded iOS build. */
+export declare function uploadRecordedCrashSymbols(input: UploadRecordedCrashSymbolsInput, ports?: CrashSymbolUploadPorts): Promise<CrashSymbolUploadResult>;
+/** The command that retries a failed upload for one release, for the game directory used. */
+export declare function crashSymbolsRetryCommand(input: {
+  readonly gameRoot: string;
+  readonly gameId: string;
+  readonly releaseKey: string;
+}): string;
+/**
+* The `mpgd deploy run` step: upload the recorded dSYMs of the release's iOS
+* build once. A failure (or an error reading the files or the state) is
+* reported with the retry command and never thrown, so it cannot fail or
+* block the store submission.
+*/
+export declare function uploadCrashSymbolsForDeployRun(input: UploadRecordedCrashSymbolsInput, report?: (message: string) => void, upload?: typeof uploadRecordedCrashSymbols): Promise<CrashSymbolUploadResult | undefined>;