@mpgd/cli 0.61.0 → 0.62.0

package/dist/native-deploy-run.d.ts

@@ -24,6 +24,8 @@ export interface RunNativeDeploymentInput {
   readonly signal?: AbortSignal;
   /** Called only after a newly built target has an immutable, committed build record. */
   readonly onBuildRecorded?: (target: NativeDeployTarget) => void;
+  /** Receives the Crashlytics dSYM upload outcome; defaults to `console.warn`. */
+  readonly onCrashSymbolsReport?: (message: string) => void;
 }
 /** Reserve once, build only missing targets, then submit the recorded binaries. */
 export declare function runNativeDeployment(input: RunNativeDeploymentInput): Promise<NativeReleaseStatus>;

package/dist/native-deploy-run.js

@@ -4,10 +4,11 @@ import path from 'node:path';
 import { doctorNativeDeployment, readNativeDeployCredentialNames, readNativeDeployTargetProfile, } from './deploy-planning.js';
 import { withAndroidUploadSigningSession } from './android-signing-session.js';
 import { withIosSigningSession } from './ios-signing-session.js';
-import { assertSettledAndroidReleaseOptions, submitRecordedNativeTarget, } from './native-deploy-submission.js';
+import { assertSettledAndroidReleaseOptions, submitRecordedNativeTarget, withRecordedR8Mapping, } from './native-deploy-submission.js';
 import { isNativeSubmissionSettled, readNativeReleaseStatus, recordNativeReleaseBuild, reserveNativeRelease, } from './release-state.js';
 import { installPinnedReleaseDependencies, pinNativeDeploymentPlan, runPinnedNativeBuild, withPinnedReleaseWorkspace, } from './release-workspace.js';
 import { inspectAndroidBundleSigner } from './android-bundle-signer.js';
+import { uploadCrashSymbolsForDeployRun } from './crash-symbols-upload.js';
 import { assertPlayReleaseConfirmed, assertPlayReleaseRequest, } from './play-release-options.js';
 const gitAuthEnvironmentNames = ['GITHUB_TOKEN', 'GH_TOKEN', 'GIT_ASKPASS'];
 /** Reserve once, build only missing targets, then submit the recorded binaries. */
@@ -45,7 +46,7 @@ export async function runNativeDeployment(input) {
         }
     }
     // Refuse changed Play options for a committed release before any build work.
-    assertSettledAndroidReleaseOptions(existing?.submissions.android, input.androidRelease);
+    assertSettledAndroidReleaseOptions(existing?.submissions.android, withRecordedR8Mapping(input.androidRelease, existing?.builds.android, input.plan.gameRoot));
     const pendingSteps = existing === undefined
         ? {
             buildTargets: input.plan.targets.map((entry) => entry.target),
@@ -123,20 +124,35 @@ export async function runNativeDeployment(input) {
             ...(input.signal === undefined ? {} : { signal: input.signal }),
         });
     }
+    // A --mapping-file that differs from the mapping recorded with the Android
+    // build is refused here, before any target (iOS may come first) is submitted.
+    status = await readNativeReleaseStatus({
+        gameRoot: input.plan.gameRoot,
+        gameId: input.gameId,
+        releaseKey: input.releaseKey,
+        environment,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    });
+    withRecordedR8Mapping(input.androidRelease, status.builds.android, input.plan.gameRoot);
+    let fresh = true;
     for (const entry of input.plan.targets) {
-        status = await readNativeReleaseStatus({
-            gameRoot: input.plan.gameRoot,
-            gameId: input.gameId,
-            releaseKey: input.releaseKey,
-            environment,
-            ...(input.signal === undefined ? {} : { signal: input.signal }),
-        });
+        // The status read above serves the first target; later ones re-read it.
+        if (!fresh) {
+            status = await readNativeReleaseStatus({
+                gameRoot: input.plan.gameRoot,
+                gameId: input.gameId,
+                releaseKey: input.releaseKey,
+                environment,
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+            });
+        }
+        fresh = false;
         if (status.builds[entry.target] === undefined) {
             throw new Error(`${entry.target} has no verified build after the native build stage.`);
         }
         const submission = status.submissions[entry.target];
         if (submission !== undefined && isNativeSubmissionSettled(submission.status)) {
-            assertSettledAndroidReleaseOptions(submission, input.androidRelease);
+            assertSettledAndroidReleaseOptions(submission, withRecordedR8Mapping(input.androidRelease, status.builds.android, input.plan.gameRoot));
             continue;
         }
         await submitRecordedNativeTarget({
@@ -156,6 +172,21 @@ export async function runNativeDeployment(input) {
             ...(input.signal === undefined ? {} : { signal: input.signal }),
         });
     }
+    // Crashlytics dSYMs of the recorded iOS build, once, only after every store
+    // submission went through (a failed or cancelled run reports its own error
+    // at once; the next run or `mpgd deploy symbols` uploads them). A slow upload
+    // never delays a submission, and the step never throws: a failure is
+    // reported and retryable.
+    if (input.plan.targets.some((entry) => entry.target === 'ios')
+        && input.signal?.aborted !== true) {
+        await uploadCrashSymbolsForDeployRun({
+            gameRoot: input.plan.gameRoot,
+            gameId: input.gameId,
+            releaseKey: input.releaseKey,
+            environment,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+        }, input.onCrashSymbolsReport);
+    }
     return readNativeReleaseStatus({
         gameRoot: input.plan.gameRoot,
         gameId: input.gameId,
@@ -232,6 +263,23 @@ async function buildAndRecordTarget(input, workspace, target, reserved, environm
         const manifestLocation = `.mpgd/releases/${input.releaseKey}/${target}-manifest-${sha256(built.releaseManifest)}.json`;
         const artifactFile = persistImmutableFile(input.plan.gameRoot, artifactLocation, built.artifact);
         const manifestFile = persistImmutableFile(input.plan.gameRoot, manifestLocation, built.releaseManifest);
+        // Crash symbols travel with the artifact (and the workflow's release bundle).
+        const persistSymbol = (source, name) => {
+            const location = `.mpgd/releases/${input.releaseKey}/${target}-${name.replace('{sha}', sha256(source))}`;
+            return { file: persistImmutableFile(input.plan.gameRoot, location, source), location };
+        };
+        const r8Mapping = built.symbols?.r8Mapping === undefined
+            ? undefined
+            : persistSymbol(built.symbols.r8Mapping, 'mapping-{sha}.txt');
+        const crashlytics = built.symbols?.crashlytics;
+        const crashlyticsSymbols = crashlytics === undefined
+            ? undefined
+            : {
+                dsymArchive: persistSymbol(crashlytics.dsymArchive, 'dsyms-{sha}.zip'),
+                dsyms: crashlytics.dsyms,
+                uploadTool: persistSymbol(crashlytics.uploadTool, 'upload-symbols-{sha}'),
+                googleServiceInfo: persistSymbol(crashlytics.googleServiceInfo, 'GoogleService-Info-{sha}.plist'),
+            };
         const configDigest = createHash('sha256').update(JSON.stringify({
             gameGitSha: workspace.input.gameGitSha,
             lockfileSha256: workspace.input.lockfileSha256,
@@ -268,6 +316,8 @@ async function buildAndRecordTarget(input, workspace, target, reserved, environm
             expectedReleaseManifestSha256: sha256(manifestFile),
             inspectedAppId: planned.appId,
             ...(target === 'android' ? { inspectedSignerSha256 } : { inspectedTeamId: signerOrTeam }),
+            ...(r8Mapping === undefined ? {} : { r8Mapping }),
+            ...(crashlyticsSymbols === undefined ? {} : { crashlyticsSymbols }),
             environment,
             ...(input.signal === undefined ? {} : { signal: input.signal }),
         });

package/dist/native-deploy-submission.d.ts

@@ -50,6 +50,12 @@ export declare function isNativeDeployApproved(plan: Pick<NativeDeploymentPlan,
 * Google Play options must fail instead of being skipped as done.
 */
 export declare function assertSettledAndroidReleaseOptions(checkpoint: NativeSubmissionCheckpoint | undefined, androidRelease: PlayReleaseRequest | undefined): void;
+/**
+* The Google Play request with the R8 mapping recorded with the build: it is
+* used when no `--mapping-file` is given, and an explicit one must have the
+* same bytes. A build without a recorded mapping keeps the request as it is.
+*/
+export declare function withRecordedR8Mapping(request: PlayReleaseRequest | undefined, record: Pick<ImmutableNativeBuildRecord, 'r8Mapping'> | undefined, gameRoot: string): PlayReleaseRequest | undefined;
 /** Resume exactly one verified build; never rebuild or allocate another version here. */
 export declare function submitRecordedNativeTarget(input: SubmitRecordedNativeTargetInput): Promise<NativeSubmissionCheckpoint>;
 /** Verify one recorded Android build and print its Play edit without any store call. */
@@ -57,3 +63,5 @@ export declare function planRecordedAndroidSubmission(input: Omit<SubmitRecorded
 export declare function submitRecordedNativeTargetWithPorts(input: SubmitRecordedNativeTargetInput, ports: NativeSubmissionPorts): Promise<NativeSubmissionCheckpoint>;
 /** Validate the workflow-restored manifest against the immutable release-state hash. */
 export declare function verifyRecordedReleaseManifest(gameRoot: string, record: Pick<ImmutableNativeBuildRecord, 'artifactLocation' | 'releaseManifestSha256' | 'target'>): void;
+/** A recorded game-relative file, resolved without leaving the game directory. */
+export declare function resolveRecordedArtifact(gameRoot: string, recordedLocation: string): string;

package/dist/native-deploy-submission.js

@@ -1,5 +1,5 @@
 import { createHash, randomBytes } from 'node:crypto';
-import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { checkpointNativeSubmission, freshSubmissionLeaseExpiresAt, isNativeSubmissionSettled, readNativeReleaseStatus, reclaimNativeSubmission, releaseNativeSubmissionLease, } from './release-state.js';
 import { planVerifiedAndroidBundleSubmission, PlaySubmissionUncertainError, submitVerifiedAndroidBundle, } from './play-internal-submission.js';
@@ -33,6 +33,35 @@ export function assertSettledAndroidReleaseOptions(checkpoint, androidRelease) {
             + 'change it with "mpgd deploy rollout" or submit a new release.');
     }
 }
+/**
+ * The Google Play request with the R8 mapping recorded with the build: it is
+ * used when no `--mapping-file` is given, and an explicit one must have the
+ * same bytes. A build without a recorded mapping keeps the request as it is.
+ */
+export function withRecordedR8Mapping(request, record, gameRoot) {
+    const recorded = record?.r8Mapping;
+    if (recorded === undefined) {
+        return request;
+    }
+    if (request?.mappingSha256 !== undefined) {
+        if (request.mappingSha256 !== recorded.sha256) {
+            throw new Error(`--mapping-file differs from the R8 mapping recorded with this build (${recorded.location}, `
+                + `sha256 ${recorded.sha256}); omit it to use the recorded mapping.`);
+        }
+        return request;
+    }
+    // A missing file is reported when the submission hashes it; an existing one
+    // must not resolve outside the game through a symlink.
+    const candidate = path.resolve(gameRoot, recorded.location);
+    const mappingFile = existsSync(candidate)
+        ? resolveRecordedArtifact(gameRoot, recorded.location)
+        : candidate;
+    return {
+        ...(request ?? defaultPlayReleaseRequest),
+        mappingFile,
+        mappingSha256: recorded.sha256,
+    };
+}
 /** Resume exactly one verified build; never rebuild or allocate another version here. */
 export async function submitRecordedNativeTarget(input) {
     return submitRecordedNativeTargetWithPorts(input, productionPorts);
@@ -43,11 +72,12 @@ export async function planRecordedAndroidSubmission(input, readStatus = readNati
     if (input.environment?.MPGD_VERIFY_RELEASE_MANIFEST === '1') {
         verifyRecordedReleaseManifest(input.plan.gameRoot, recorded.record);
     }
+    const release = withRecordedR8Mapping(input.androidRelease, recorded.record, input.plan.gameRoot);
     return planVerifiedAndroidBundleSubmission({
         record: recorded.record,
         aabFile: recorded.artifactFile,
         packageName: recorded.planned.appId,
-        ...(input.androidRelease === undefined ? {} : { release: input.androidRelease }),
+        ...(release === undefined ? {} : { release }),
         ...(input.signal === undefined ? {} : { signal: input.signal }),
     });
 }
@@ -86,14 +116,13 @@ export async function submitRecordedNativeTargetWithPorts(input, ports) {
     if (planned === undefined || !input.approved) {
         throw new Error('Native store submission requires a planned target and explicit approval.');
     }
-    const androidRelease = input.androidRelease ?? defaultPlayReleaseRequest;
     if (target === 'android') {
         // Refuse an invalid or unconfirmed production/staged request before the
         // release state is read or a checkpoint is written.
-        assertPlayReleaseRequest(androidRelease);
-        assertPlayReleaseConfirmed(androidRelease, input.confirmProduction === true);
+        const requested = input.androidRelease ?? defaultPlayReleaseRequest;
+        assertPlayReleaseRequest(requested);
+        assertPlayReleaseConfirmed(requested, input.confirmProduction === true);
     }
-    const releaseDigest = target === 'android' ? playReleaseRequestDigest(androidRelease) : undefined;
     const stateInput = {
         gameRoot: input.plan.gameRoot,
         gameId: input.gameId,
@@ -101,6 +130,12 @@ export async function submitRecordedNativeTargetWithPorts(input, ports) {
         ...(input.signal === undefined ? {} : { signal: input.signal }),
     };
     const { record, artifactFile, status } = await readRecordedSubmission(input, target, ports.readStatus);
+    // The build's recorded R8 mapping goes with it, the same way --mapping-file does.
+    const effectiveAndroidRelease = target === 'android'
+        ? withRecordedR8Mapping(input.androidRelease, record, input.plan.gameRoot)
+        : undefined;
+    const androidRelease = effectiveAndroidRelease ?? defaultPlayReleaseRequest;
+    const releaseDigest = target === 'android' ? playReleaseRequestDigest(androidRelease) : undefined;
     let checkpoint = status.submissions[target];
     assertSettledAndroidReleaseOptions(checkpoint, androidRelease);
     // An attempt that never checkpointed a Play edit changed nothing remotely,
@@ -116,6 +151,12 @@ export async function submitRecordedNativeTargetWithPorts(input, ports) {
     if (checkpoint !== undefined && isNativeSubmissionSettled(checkpoint.status)) {
         return checkpoint;
     }
+    if (record.r8Mapping !== undefined && effectiveAndroidRelease?.mappingFile !== undefined
+        && !existsSync(effectiveAndroidRelease.mappingFile)) {
+        throw new Error(`The R8 mapping recorded with this build is missing: ${record.r8Mapping.location}. Restore `
+            + 'the release bundle (.mpgd/releases/<release>) next to the bundle, or pass the same file '
+            + 'with --mapping-file.');
+    }
     if (input.environment?.MPGD_VERIFY_RELEASE_MANIFEST === '1') {
         verifyRecordedReleaseManifest(input.plan.gameRoot, record);
     }
@@ -202,7 +243,7 @@ export async function submitRecordedNativeTargetWithPorts(input, ports) {
                 onEditCreated: async (editId) => {
                     await save({ status: 'edit-open', remoteEditId: editId });
                 },
-                ...(input.androidRelease === undefined ? {} : { release: input.androidRelease }),
+                ...(effectiveAndroidRelease === undefined ? {} : { release: effectiveAndroidRelease }),
                 ...(input.confirmProduction === undefined ? {} : {
                     confirmProduction: input.confirmProduction,
                 }),
@@ -316,7 +357,8 @@ export function verifyRecordedReleaseManifest(gameRoot, record) {
         throw new Error('Restored release manifest differs from the immutable build record.');
     }
 }
-function resolveRecordedArtifact(gameRoot, recordedLocation) {
+/** A recorded game-relative file, resolved without leaving the game directory. */
+export function resolveRecordedArtifact(gameRoot, recordedLocation) {
     if (path.isAbsolute(recordedLocation)) {
         throw new Error('Native artifact location must be game-relative.');
     }

package/dist/pnpm-build-approvals.d.ts

@@ -0,0 +1,59 @@
+/**
+* pnpm build-script decisions for the dependencies a notifications game adds.
+*
+* pnpm 11 replaced `onlyBuiltDependencies` with `allowBuilds` and fails an
+* install (`ERR_PNPM_IGNORED_BUILDS`) while a dependency's build script is
+* neither allowed (`true`) nor denied (`false`), because `strictDepBuilds`
+* defaults to `true` (https://pnpm.io/settings/build). The notifications
+* starter adds `firebase`, whose tree has two such scripts:
+*
+* - `@firebase/util` `postinstall.js` only matters for Firebase App Hosting:
+*   it reads `FIREBASE_WEBAPP_CONFIG`, may fetch the web app config from
+*   firebase.googleapis.com, and bakes it into `dist/postinstall.*` for
+*   `initializeApp()` without options. The published `dist` already ships the
+*   placeholder that returns `undefined`, and the kit never initializes the web
+*   SDK (it is there so the messaging plugin's web fallback resolves), so the
+*   script is denied: the install stays offline and reproducible.
+* - `protobufjs` `scripts/postinstall.js` only prints a warning when the parent
+*   package declares protobufjs with another semver operator. The game
+*   template already allows it for the Apps in Toss toolchain, so the same
+*   decision is kept here.
+*
+* `packages/cli/test/pnpm-build-approvals.test.ts` records every package with
+* an install script in the starter's Firebase tree and fails when the starter's
+* firebase version moves without that list (and a decision here) being redone.
+*/
+export declare const notificationsBuildApprovals: Readonly<Record<string, boolean>>;
+export type AllowBuildsEdit = {
+  readonly kind: 'covered';
+} | {
+  readonly kind: 'edited';
+  readonly content: string;
+  readonly added: readonly string[];
+} | {
+  readonly kind: 'unsupported';
+  readonly missing: readonly string[];
+};
+/** The package a matcher names: `name`, `name@range`, `@scope/name@range`, or `name@git-url`. */
+export declare function allowBuildsPackageName(matcher: string): string;
+/**
+* Adds an explicit decision for each package in `approvals` that the
+* `pnpm-workspace.yaml` content does not list yet, keeping every existing
+* entry (a game's own decision wins). Only the block-mapping form the game
+* template writes is edited; another form is reported as unsupported so the
+* caller can print the entries instead of rewriting YAML it cannot parse.
+*/
+export declare function addAllowBuilds(content: string, approvals: Readonly<Record<string, boolean>>): AllowBuildsEdit;
+/** The `allowBuilds` block to print when the caller cannot edit the file itself. */
+export declare function allowBuildsSnippet(approvals: Readonly<Record<string, boolean>>): string;
+/**
+* The `pnpm-workspace.yaml` edit a notifications game needs before its
+* install adds `firebase`: the new content when the file can be edited, or a
+* warning with the entries to add when it cannot (no file at the game root,
+* where a parent workspace may govern the install, or a form this edit does
+* not parse).
+*/
+export declare function planNotificationsBuildApprovals(workspace: string | undefined): {
+  readonly content?: string;
+  readonly warning?: string;
+};

package/dist/pnpm-build-approvals.js

@@ -0,0 +1,157 @@
+/**
+ * pnpm build-script decisions for the dependencies a notifications game adds.
+ *
+ * pnpm 11 replaced `onlyBuiltDependencies` with `allowBuilds` and fails an
+ * install (`ERR_PNPM_IGNORED_BUILDS`) while a dependency's build script is
+ * neither allowed (`true`) nor denied (`false`), because `strictDepBuilds`
+ * defaults to `true` (https://pnpm.io/settings/build). The notifications
+ * starter adds `firebase`, whose tree has two such scripts:
+ *
+ * - `@firebase/util` `postinstall.js` only matters for Firebase App Hosting:
+ *   it reads `FIREBASE_WEBAPP_CONFIG`, may fetch the web app config from
+ *   firebase.googleapis.com, and bakes it into `dist/postinstall.*` for
+ *   `initializeApp()` without options. The published `dist` already ships the
+ *   placeholder that returns `undefined`, and the kit never initializes the web
+ *   SDK (it is there so the messaging plugin's web fallback resolves), so the
+ *   script is denied: the install stays offline and reproducible.
+ * - `protobufjs` `scripts/postinstall.js` only prints a warning when the parent
+ *   package declares protobufjs with another semver operator. The game
+ *   template already allows it for the Apps in Toss toolchain, so the same
+ *   decision is kept here.
+ *
+ * `packages/cli/test/pnpm-build-approvals.test.ts` records every package with
+ * an install script in the starter's Firebase tree and fails when the starter's
+ * firebase version moves without that list (and a decision here) being redone.
+ */
+export const notificationsBuildApprovals = Object.freeze({
+    '@firebase/util': false,
+    protobufjs: true,
+});
+const allowBuildsLine = /^allowBuilds:[ \t]*(?:#.*)?$/mu;
+// Any top-level spelling of the key, quoted or not, so an unparsed form is
+// reported instead of getting a second, duplicate mapping appended.
+const allowBuildsKey = /^(?:allowBuilds|'allowBuilds'|"allowBuilds")[ \t]*:/mu;
+const entryKey = /^([ \t]+)(?:'((?:[^']|'')*)'|"((?:[^"\\]|\\.)*)"|([^\s#'"-][^:#]*?))[ \t]*:[ \t]*[^\s#]/u;
+/** The package a matcher names: `name`, `name@range`, `@scope/name@range`, or `name@git-url`. */
+export function allowBuildsPackageName(matcher) {
+    const trimmed = matcher.trim();
+    const versionAt = trimmed.indexOf('@', trimmed.startsWith('@') ? 1 : 0);
+    return versionAt === -1 ? trimmed : trimmed.slice(0, versionAt);
+}
+function quoteKey(name) {
+    return /^[a-z0-9][a-z0-9._-]*$/u.test(name) ? name : `'${name.replaceAll("'", "''")}'`;
+}
+/**
+ * Adds an explicit decision for each package in `approvals` that the
+ * `pnpm-workspace.yaml` content does not list yet, keeping every existing
+ * entry (a game's own decision wins). Only the block-mapping form the game
+ * template writes is edited; another form is reported as unsupported so the
+ * caller can print the entries instead of rewriting YAML it cannot parse.
+ */
+export function addAllowBuilds(content, approvals) {
+    if (/^dangerouslyAllowAllBuilds:[ \t]*true\b/mu.test(content)
+        || /^strictDepBuilds:[ \t]*false\b/mu.test(content)) {
+        return { kind: 'covered' };
+    }
+    const newline = content.includes('\r\n') ? '\r\n' : '\n';
+    const lines = content.split(/\r?\n/u);
+    const header = lines.findIndex((line) => allowBuildsLine.test(line));
+    // A bare name reviews every version; a qualified matcher (`name@1.2.3`,
+    // `name@git+…`) reviews only what it names, which may not be what the
+    // starter's firebase brings.
+    const listed = new Set();
+    const qualified = new Set();
+    let indent = '  ';
+    if (header !== -1) {
+        let indentSeen = false;
+        for (let index = header + 1; index < lines.length; index += 1) {
+            const line = lines[index] ?? '';
+            if (line.trim() === '' || /^[ \t]*#/u.test(line)) {
+                continue;
+            }
+            if (!/^[ \t]/u.test(line)) {
+                break;
+            }
+            // Only one-line `key: value` entries at one indentation are read; a
+            // sequence item, a value on the next line, or a nested key would make
+            // the scan miss an entry and the edit add a duplicate key.
+            const match = entryKey.exec(line);
+            if (match === null || (indentSeen && match[1] !== indent)) {
+                return { kind: 'unsupported', missing: Object.keys(approvals) };
+            }
+            // A merge key (`<<: *decisions`), an anchor, an alias or a tag brings
+            // entries the line scan cannot see, so an inserted entry could override
+            // an inherited decision.
+            if (/^(?:<<|[&*!])/u.test(match[4] ?? '') || /[&*!]$/u.test(match[0])) {
+                return { kind: 'unsupported', missing: Object.keys(approvals) };
+            }
+            if (!indentSeen) {
+                indent = match[1] ?? indent;
+                indentSeen = true;
+            }
+            const key = match[2]?.replaceAll("''", "'") ?? match[3] ?? match[4] ?? '';
+            const name = allowBuildsPackageName(key);
+            (name === key.trim() ? listed : qualified).add(name);
+        }
+    }
+    else if (allowBuildsKey.test(content)) {
+        return { kind: 'unsupported', missing: Object.keys(approvals) };
+    }
+    const missing = Object.keys(approvals).filter((name) => !listed.has(name)).sort();
+    if (missing.length === 0) {
+        return { kind: 'covered' };
+    }
+    if (missing.some((name) => qualified.has(name))) {
+        // A bare entry would override the game's version-specific decision.
+        return { kind: 'unsupported', missing };
+    }
+    const entries = missing.map((name) => `${indent}${quoteKey(name)}: ${String(approvals[name])}`);
+    if (header !== -1) {
+        lines.splice(header + 1, 0, ...entries);
+    }
+    else {
+        while (lines.length > 0 && lines[lines.length - 1] === '') {
+            lines.pop();
+        }
+        lines.push('allowBuilds:', ...entries, '');
+    }
+    const edited = lines.join(newline);
+    return {
+        kind: 'edited',
+        content: edited.endsWith(newline) ? edited : `${edited}${newline}`,
+        added: missing,
+    };
+}
+/** The `allowBuilds` block to print when the caller cannot edit the file itself. */
+export function allowBuildsSnippet(approvals) {
+    return [
+        'allowBuilds:',
+        ...Object.keys(approvals).sort().map((name) => `  ${quoteKey(name)}: ${String(approvals[name])}`),
+    ].join('\n');
+}
+/**
+ * The `pnpm-workspace.yaml` edit a notifications game needs before its
+ * install adds `firebase`: the new content when the file can be edited, or a
+ * warning with the entries to add when it cannot (no file at the game root,
+ * where a parent workspace may govern the install, or a form this edit does
+ * not parse).
+ */
+export function planNotificationsBuildApprovals(workspace) {
+    const instruction = 'pnpm 11 stops installing firebase until the pnpm-workspace.yaml that '
+        + `installs the game lists its build scripts:\n${allowBuildsSnippet(notificationsBuildApprovals)}`;
+    if (workspace === undefined) {
+        return { warning: `The game has no pnpm-workspace.yaml; ${instruction}` };
+    }
+    const edit = addAllowBuilds(workspace, notificationsBuildApprovals);
+    if (edit.kind === 'edited') {
+        return { content: edit.content };
+    }
+    if (edit.kind === 'unsupported') {
+        return {
+            warning: 'pnpm-workspace.yaml writes allowBuilds in a form the initializer does not edit '
+                + '(a quoted key, a flow mapping, or a version-specific entry for one of these packages); '
+                + instruction,
+        };
+    }
+    return {};
+}

package/dist/release-state.d.ts

@@ -1,4 +1,5 @@
 import { type PlatformVersionLedger, type PlatformVersionReleasePlan, type PlatformVersionTargetRequest } from '@mpgd/target-config';
+import { type NativeDsymIdentity } from './native-build-symbols.js';
 export interface NativeReleaseReservationInput {
   readonly gameRoot: string;
   readonly releaseKey: string;
@@ -40,6 +41,44 @@ export interface ImmutableNativeBuildRecord {
   readonly inspectedAppId: string;
   readonly inspectedSignerSha256?: string | undefined;
   readonly inspectedTeamId?: string | undefined;
+  /** Android: the R8 `mapping.txt` of this bundle, when the build was minified. */
+  readonly r8Mapping?: RecordedSymbolFile;
+  /** iOS with Firebase Crashlytics: the archive's dSYMs and what uploads them. */
+  readonly crashlyticsSymbols?: RecordedCrashlyticsSymbols;
+}
+/** A game-relative file kept next to the recorded artifact, with its SHA-256. */
+export interface RecordedSymbolFile {
+  readonly location: string;
+  readonly sha256: string;
+}
+export interface RecordedCrashlyticsSymbols {
+  /** Zip of the archive's `dSYMs` folder. */
+  readonly dsymArchive: RecordedSymbolFile;
+  /** Each dSYM bundle and its Mach-O UUIDs. */
+  readonly dsyms: readonly NativeDsymIdentity[];
+  /** Firebase's `upload-symbols` from the build's package checkout. */
+  readonly uploadTool: RecordedSymbolFile;
+  /** The `GoogleService-Info.plist` the archived app bundles. */
+  readonly googleServiceInfo: RecordedSymbolFile;
+}
+/** A symbol file to copy into the record: its bytes and its game-relative location. */
+export interface RecordSymbolFileInput {
+  readonly file: string;
+  readonly location: string;
+}
+/**
+* The Crashlytics dSYM upload of one recorded iOS build. It is mutable state
+* next to the immutable build record: `failed` can be retried, `uploaded` is final.
+*/
+export interface CrashSymbolUploadRecord {
+  readonly releaseKey: string;
+  readonly target: 'ios';
+  readonly buildRunId: string;
+  readonly dsymArchiveSha256: string;
+  readonly status: 'uploaded' | 'failed';
+  readonly updatedAt: string;
+  /** Short reason of the last failed attempt. */
+  readonly failure?: string;
 }
 export type NativeSubmissionStatus = 'started' | 'edit-open' | 'upload-committed' | 'uploaded' | 'processing' | 'testflight-ready' | 'action-required' | 'failed' | 'unknown' | 'committed';
 export declare function isNativeSubmissionSettled(status: NativeSubmissionStatus): boolean;
@@ -65,6 +104,8 @@ export interface NativeReleaseStatus {
   readonly plan: PlatformVersionReleasePlan;
   readonly builds: Partial<Record<'android' | 'ios', ImmutableNativeBuildRecord>>;
   readonly submissions: Partial<Record<'android' | 'ios', NativeSubmissionCheckpoint>>;
+  /** Crashlytics dSYM uploads of recorded iOS builds. */
+  readonly symbolUploads?: Partial<Record<'ios', CrashSymbolUploadRecord>>;
   readonly stateCommit: string;
 }
 export interface RecordNativeBuildInput {
@@ -87,6 +128,15 @@ export interface RecordNativeBuildInput {
   readonly inspectedAppId: string;
   readonly inspectedSignerSha256?: string | undefined;
   readonly inspectedTeamId?: string | undefined;
+  /** Android: the R8 mapping file the build wrote, already copied next to the artifact. */
+  readonly r8Mapping?: RecordSymbolFileInput;
+  /** iOS with Firebase Crashlytics, already copied next to the artifact. */
+  readonly crashlyticsSymbols?: {
+    readonly dsymArchive: RecordSymbolFileInput;
+    readonly dsyms: readonly NativeDsymIdentity[];
+    readonly uploadTool: RecordSymbolFileInput;
+    readonly googleServiceInfo: RecordSymbolFileInput;
+  };
   readonly environment?: NodeJS.ProcessEnv;
   readonly signal?: AbortSignal;
 }
@@ -142,7 +192,26 @@ export declare function releaseNativeSubmissionLease(input: {
   readonly environment?: NodeJS.ProcessEnv;
   readonly signal?: AbortSignal;
 }): Promise<NativeSubmissionCheckpoint>;
+/**
+* Record the outcome of a Crashlytics dSYM upload for one recorded iOS build.
+* A failure can be recorded again and retried; once `uploaded`, it stays so.
+*/
+export declare function recordCrashSymbolUpload(input: {
+  readonly gameRoot: string;
+  readonly gameId: string;
+  readonly releaseKey: string;
+  readonly buildRunId: string;
+  readonly dsymArchiveSha256: string;
+  readonly status: CrashSymbolUploadRecord['status'];
+  readonly failure?: string;
+  readonly environment?: NodeJS.ProcessEnv;
+  readonly signal?: AbortSignal;
+}): Promise<CrashSymbolUploadRecord>;
 /** Exported for tests: the checkpoint status moves a store submission may make. */
 export declare function allowedSubmissionTransition(from: NativeSubmissionStatus, to: NativeSubmissionStatus): boolean;
 /** Validate persisted checkpoint shape before any remote mutation or recovery. */
 export declare function assertNativeSubmissionCheckpoint(value: unknown): asserts value is NativeSubmissionCheckpoint;
+/** A game-relative location without `..` segments. */
+export declare function isRecordedLocation(location: unknown): location is string;
+/** Streamed SHA-256 of a file, hex. */
+export declare function sha256File(file: string): Promise<string>;