@mpgd/cli 0.61.1 → 0.62.0

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>;

package/dist/crash-symbols-upload.js

@@ -0,0 +1,232 @@
+import { chmodSync, copyFileSync, existsSync, mkdtempSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { ReleaseProcessError, runReleaseProcess, } from './deploy-process.js';
+import { resolveRecordedArtifact } from './native-deploy-submission.js';
+import { readNativeReleaseStatus, recordCrashSymbolUpload, sha256File, } from './release-state.js';
+// Uploads the dSYMs recorded with an iOS build to Firebase Crashlytics with
+// Firebase's own `upload-symbols` (the copy recorded from the build's package
+// checkout) and the `GoogleService-Info.plist` the archived app bundles:
+//
+//     upload-symbols -gsp GoogleService-Info.plist -p ios dSYMs.zip
+//
+// Firebase documents this command for uploading dSYMs outside the Xcode run
+// script (https://firebase.google.com/docs/crashlytics/ios/get-deobfuscated-reports);
+// the tool's usage text accepts "zip archives containing dSYMs". The outcome is
+// recorded next to the immutable build record, so an upload is done once and a
+// failed one can be retried with `mpgd deploy symbols`. It never touches a store
+// submission.
+const uploadTimeoutMs = 10 * 60_000;
+const productionPorts = {
+    readStatus: readNativeReleaseStatus,
+    recordUpload: recordCrashSymbolUpload,
+    run: runReleaseProcess,
+    platform: process.platform,
+};
+/** Upload (or, with `dryRun`, plan) the Crashlytics dSYMs of one recorded iOS build. */
+export async function uploadRecordedCrashSymbols(input, ports = productionPorts) {
+    const stateInput = {
+        gameRoot: input.gameRoot,
+        gameId: input.gameId,
+        releaseKey: input.releaseKey,
+        ...(input.environment === undefined ? {} : { environment: input.environment }),
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    };
+    const status = await ports.readStatus(stateInput);
+    const build = status.builds.ios;
+    if (build === undefined) {
+        throw new Error('This release has no recorded iOS build.');
+    }
+    const symbols = build.crashlyticsSymbols;
+    if (symbols === undefined) {
+        return {
+            status: 'not-applicable',
+            reason: 'The iOS build recorded no Crashlytics dSYMs: crash reporting is off, or the build '
+                + 'was recorded before deploy run recorded dSYMs (upload those by hand, see '
+                + 'docs/CRASH_REPORTING.md).',
+        };
+    }
+    const previous = status.symbolUploads?.ios;
+    if (previous?.status === 'uploaded' && previous.buildRunId === build.buildRunId
+        && previous.dsymArchiveSha256 === symbols.dsymArchive.sha256) {
+        return { status: 'already-uploaded', upload: previous };
+    }
+    const plan = {
+        releaseKey: input.releaseKey,
+        buildRunId: build.buildRunId,
+        dsymArchiveSha256: symbols.dsymArchive.sha256,
+        dsyms: symbols.dsyms,
+        command: [
+            symbols.uploadTool.location,
+            '-gsp',
+            symbols.googleServiceInfo.location,
+            '-p',
+            'ios',
+            symbols.dsymArchive.location,
+        ],
+    };
+    // The recorded files must be the build's bytes, also for a dry run.
+    const tool = await verifiedRecordedFile(input.gameRoot, symbols.uploadTool, 'upload-symbols');
+    const plist = await verifiedRecordedFile(input.gameRoot, symbols.googleServiceInfo, 'GoogleService-Info.plist');
+    const archive = await verifiedRecordedFile(input.gameRoot, symbols.dsymArchive, 'dSYM archive');
+    if (input.dryRun === true) {
+        return { status: 'planned', plan };
+    }
+    if (ports.platform !== 'darwin') {
+        throw new Error('Firebase upload-symbols is a macOS tool; upload the dSYMs from a Mac.');
+    }
+    const record = async (outcome, failure) => ports.recordUpload({
+        ...stateInput,
+        buildRunId: build.buildRunId,
+        dsymArchiveSha256: symbols.dsymArchive.sha256,
+        status: outcome,
+        ...(failure === undefined ? {} : { failure }),
+    });
+    // Run a private executable copy: a restored workflow artifact loses its mode
+    // bits, and the recorded file itself stays untouched.
+    const workDirectory = mkdtempSync(path.join(tmpdir(), 'mpgd-crash-symbols-'));
+    let output = '';
+    try {
+        const executable = path.join(workDirectory, 'upload-symbols');
+        copyFileSync(tool, executable);
+        chmodSync(executable, 0o700);
+        if (await sha256File(executable) !== symbols.uploadTool.sha256) {
+            throw new Error('The copied upload-symbols differs from the recorded tool.');
+        }
+        try {
+            const result = await ports.run({
+                command: executable,
+                args: ['-gsp', plist, '-p', 'ios', archive],
+                cwd: workDirectory,
+                environment: uploadEnvironment(input.environment ?? process.env, workDirectory),
+                timeoutMs: uploadTimeoutMs,
+                signal: input.signal,
+            });
+            output = result.output;
+        }
+        catch (error) {
+            output = error instanceof ReleaseProcessError ? error.output : '';
+            const reason = describeFailure(error);
+            let upload;
+            try {
+                upload = await record('failed', reason);
+            }
+            catch {
+                upload = undefined;
+            }
+            return {
+                status: 'failed',
+                plan,
+                error: reason,
+                output,
+                ...(upload === undefined ? {} : { upload }),
+            };
+        }
+    }
+    finally {
+        rmSync(workDirectory, { recursive: true, force: true });
+    }
+    try {
+        return { status: 'uploaded', plan, upload: await record('uploaded'), output };
+    }
+    catch (error) {
+        // The dSYMs reached Crashlytics; only the release state is behind.
+        return {
+            status: 'uploaded',
+            plan,
+            recordError: error instanceof Error ? error.message : String(error),
+            output,
+        };
+    }
+}
+/** Only what the tool needs (and network proxy settings): no store, signing or Git credentials. */
+function uploadEnvironment(source, temporary) {
+    const environment = { TMPDIR: temporary };
+    for (const name of [
+        'PATH',
+        'HOME',
+        'USER',
+        'LANG',
+        'LC_ALL',
+        'HTTPS_PROXY',
+        'https_proxy',
+        'HTTP_PROXY',
+        'http_proxy',
+        'NO_PROXY',
+        'no_proxy',
+        'SSL_CERT_FILE',
+    ]) {
+        const value = source[name];
+        if (value !== undefined) {
+            environment[name] = value;
+        }
+    }
+    return environment;
+}
+function describeFailure(error) {
+    if (error instanceof ReleaseProcessError) {
+        if (error.reason === 'exit') {
+            return `upload-symbols exited with code ${String(error.exitCode ?? 'unknown')}`;
+        }
+        return error.reason === 'timeout'
+            ? 'upload-symbols timed out'
+            : `upload-symbols ${error.reason === 'spawn' ? 'could not start' : 'was aborted'}`;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+async function verifiedRecordedFile(gameRoot, recorded, label) {
+    const candidate = path.resolve(gameRoot, recorded.location);
+    if (!existsSync(candidate) || !statSync(candidate).isFile()) {
+        throw new Error(`The recorded ${label} is missing: ${recorded.location}. Restore the release bundle `
+            + '(.mpgd/releases/<release>) the build wrote.');
+    }
+    let file;
+    try {
+        file = resolveRecordedArtifact(gameRoot, recorded.location);
+    }
+    catch {
+        throw new Error(`The recorded ${label} resolves outside the game directory.`);
+    }
+    if (await sha256File(file) !== recorded.sha256) {
+        throw new Error(`The recorded ${label} differs from the immutable build record.`);
+    }
+    return file;
+}
+/** The command that retries a failed upload for one release, for the game directory used. */
+export function crashSymbolsRetryCommand(input) {
+    return `mpgd deploy symbols --game ${shellWord(input.gameRoot)} --game-id ${shellWord(input.gameId)} --release ${shellWord(input.releaseKey)}`;
+}
+function shellWord(value) {
+    return /^[A-Za-z0-9_./:@%+=,-]+$/u.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+/**
+ * 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 async function uploadCrashSymbolsForDeployRun(input, report = (message) => console.warn(message), upload = uploadRecordedCrashSymbols) {
+    const retry = crashSymbolsRetryCommand(input);
+    try {
+        const result = await upload(input);
+        if (result.status === 'uploaded' && result.recordError !== undefined) {
+            report(`warning: Crashlytics: uploaded the iOS dSYMs, but the release state could not record `
+                + `it (${result.recordError}); "mpgd deploy status" still shows it as not uploaded, and `
+                + `${retry} would upload them again.`);
+        }
+        else if (result.status === 'uploaded') {
+            report(`Crashlytics: uploaded the iOS dSYMs (${result.plan.dsyms
+                .map((entry) => entry.bundle).join(', ')}).`);
+        }
+        else if (result.status === 'failed') {
+            report(`warning: Crashlytics dSYM upload failed (${result.error}); the store submission `
+                + `is not affected. Retry with: ${retry}${result.output === '' ? '' : `\n${result.output}`}`);
+        }
+        return result;
+    }
+    catch (error) {
+        report(`warning: Crashlytics dSYM upload did not run (${error instanceof Error ? error.message : String(error)}); the store submission is not `
+            + `affected. Retry with: ${retry}`);
+        return undefined;
+    }
+}

package/dist/index.js

@@ -38,6 +38,7 @@ import { createPlayReleaseRequest, parsePlayUserFraction, readPlayReleaseNotesFi
 import { promotePlayRelease } from './play-release-promote.js';
 import { changePlayRollout } from './play-release-rollout.js';
 import { readNativeReleaseStatus as readNativeReleaseStatusForCli } from './release-state.js';
+import { uploadRecordedCrashSymbols } from './crash-symbols-upload.js';
 export { renderGameAcceptanceMarkdown, resolveGameAcceptanceReleaseManifestFile, runGameAcceptance, defaultGameAcceptanceCommandTimeoutMs, maximumGameplayE2EReportBytes, } from './game-acceptance.js';
 export { maximumPerformanceEvidenceBytes, preparePerformanceAcceptance, readPerformanceAcceptanceEvidence, validatePerformanceBudget, } from './performance-acceptance.js';
 export { applyCapacitorShellStarter, materializeCapacitorShellStarter, planCapacitorShellStarter, } from './capacitor-shell-starter.js';
@@ -439,6 +440,42 @@ const deployCommand = defineI18n({
                 console.info(JSON.stringify(status, null, 2));
             },
         }),
+        symbols: defineI18n({
+            name: 'symbols',
+            description: "Upload the Crashlytics dSYMs recorded with a release's iOS build.",
+            resource: commandResource({
+                en: "Upload the Crashlytics dSYMs recorded with a release's iOS build.",
+                ko: '릴리스의 iOS 빌드에 기록된 Crashlytics dSYM을 업로드합니다.',
+            }),
+            args: {
+                game: { type: 'string', required: false, description: 'Game project directory holding .mpgd/releases.' },
+                'game-id': { type: 'string', required: true, description: 'Explicit release ledger game ID.' },
+                release: { type: 'string', required: true, description: 'Explicit release ID.' },
+                'dry-run': {
+                    type: 'boolean', required: false,
+                    description: 'Verify the recorded files and print the planned upload-symbols command; run nothing.',
+                },
+            },
+            run: async (ctx) => {
+                const result = await uploadRecordedCrashSymbols({
+                    gameRoot: path.resolve(readOptionalString(ctx.values.game) ?? '.'),
+                    gameId: readRequiredCliOption(ctx.values['game-id'], '--game-id'),
+                    releaseKey: readRequiredCliOption(ctx.values.release, '--release'),
+                    dryRun: ctx.values['dry-run'] === true,
+                });
+                const { output, ...summary } = 'output' in result ? result : { ...result, output: '' };
+                if (output !== '') {
+                    console.info(output);
+                }
+                console.info(JSON.stringify(summary, null, 2));
+                if (result.status === 'failed') {
+                    throw new Error(`Crashlytics dSYM upload failed: ${result.error}`);
+                }
+                if (result.status === 'uploaded' && result.recordError !== undefined) {
+                    throw new Error(`The dSYMs were uploaded, but the release state could not record it: ${result.recordError}`);
+                }
+            },
+        }),
         submit: defineI18n({
             name: 'submit',
             description: 'Resume store submission of one already verified native build.',
@@ -1891,7 +1928,17 @@ const targetCommand = defineI18n({
                         }),
                     });
                     if (!dryRun) {
-                        materializeCapacitorShellStarter(plan);
+                        try {
+                            materializeCapacitorShellStarter(plan);
+                        }
+                        catch (error) {
+                            // A failed install may be the one the warnings explain (for example
+                            // the allowBuilds entries an unsupported pnpm-workspace.yaml needs).
+                            for (const warning of plan.warnings) {
+                                console.warn(`Warning: ${warning}`);
+                            }
+                            throw error;
+                        }
                     }
                     console.info(`${dryRun ? 'Would update' : 'Updated'} game-owned Capacitor shell: ${plan.changedFiles.length} file(s).`);
                     for (const file of plan.changedFiles) {

package/dist/native-build-info.json

@@ -1,5 +1,5 @@
 {
-  "kitGitSha": "c36007876f2cd9109fcdf519f91756c4453f18d4",
+  "kitGitSha": "ea82dfadb6cdcd6b842b753f4ce10b52ad1a1fb4",
   "kitDirty": false,
-  "packageVersion": "0.61.1"
+  "packageVersion": "0.62.0"
 }

package/dist/native-build-symbols.d.ts

@@ -0,0 +1,95 @@
+/** Game-relative paths, under the build's `release-output/native/<target>/` root. */
+export interface NativeBuildSymbols {
+  /** Android: R8 `mapping.txt` of this exact bundle. */
+  readonly r8Mapping?: string;
+  /** iOS with Firebase Crashlytics. */
+  readonly crashlytics?: NativeBuildCrashlyticsSymbols;
+}
+export interface NativeBuildCrashlyticsSymbols {
+  /** Zip of the archive's `dSYMs` folder. */
+  readonly dsymArchive: string;
+  /** Each dSYM bundle in the archive and the Mach-O UUIDs of its DWARF files. */
+  readonly dsyms: readonly NativeDsymIdentity[];
+  /** Firebase's `upload-symbols` from the shell's package checkout. */
+  readonly uploadTool: string;
+  /** The `GoogleService-Info.plist` the archived app bundles. */
+  readonly googleServiceInfo: string;
+}
+export interface NativeDsymIdentity {
+  readonly bundle: string;
+  readonly uuids: readonly string[];
+}
+/**
+* Validate a symbols record read from a build status file. `isPath` checks
+* each recorded path (game-relative, inside the build's output root).
+*/
+export declare function assertNativeBuildSymbols(value: unknown, isPath: (file: string) => boolean): asserts value is NativeBuildSymbols;
+/** A non-empty, sorted list of dSYM bundles with their UUIDs. */
+export declare function isDsymIdentityList(value: unknown): value is readonly NativeDsymIdentity[];
+/** A dSYM bundle file name: no path separator or control character, not hidden. */
+export declare function isDsymBundleName(name: string): boolean;
+/**
+* A game-relative path under the target's native build output root
+* (`release-output/native/<target>/`), without empty or `..` segments.
+*/
+export declare function isNativeOutputPath(file: string, target: string): boolean;
+/** Where AGP writes the release variant's R8 mapping file. */
+export declare const androidReleaseMappingPath = "app/build/outputs/mapping/release/mapping.txt";
+/** File names inside the build's `symbols/` directory. */
+export declare const nativeSymbolFileNames: Readonly<{
+  r8Mapping: "mapping.txt";
+  dsymArchive: "dSYMs.zip";
+  uploadTool: "upload-symbols";
+  googleServiceInfo: "GoogleService-Info.plist";
+}>;
+/**
+* Where a Crashlytics-enabled iOS archive puts its Swift Package checkouts
+* (`xcodebuild -clonedSourcePackagesDirPath`), so `upload-symbols` is found
+* without searching DerivedData.
+*/
+export declare const iosCrashlyticsSourcePackagesDirectory = ".mpgd-source-packages";
+/**
+* `upload-symbols` ships next to the Crashlytics `run` script: in the Swift
+* Package checkout (`SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/`,
+* the path Firebase's run script uses) or in CocoaPods
+* (`Pods/FirebaseCrashlytics/`, the path Firebase's manual-upload command uses).
+*/
+export declare function crashlyticsUploadToolCandidates(input: {
+  readonly sourcePackages: string;
+  readonly iosProject: string;
+}): readonly string[];
+export interface CollectIosCrashlyticsSymbolsInput {
+  /** Absolute path of the `.xcarchive` this build produced. */
+  readonly archive: string;
+  /** Absolute path of the staged shell's `ios` directory. */
+  readonly iosProject: string;
+  /** Absolute `-clonedSourcePackagesDirPath` of the archive build. */
+  readonly sourcePackages: string;
+  /** Absolute output directory (`<artifact root>/symbols`). */
+  readonly outputDirectory: string;
+  readonly copyFile: (source: string, destination: string) => void;
+  /** Zips `source` (a directory) into `destination` keeping the folder name. */
+  readonly zipDirectory: (source: string, destination: string) => void;
+}
+export interface CollectedIosCrashlyticsSymbols {
+  readonly dsymArchive: string;
+  readonly dsyms: readonly NativeDsymIdentity[];
+  readonly uploadTool: string;
+  readonly googleServiceInfo: string;
+}
+/**
+* Copy what Crashlytics needs out of a staged archive build before the stage
+* is removed. Refused when the archive has no dSYM (Firebase: "Set Debug
+* Information Format to DWARF with dSYM File"), when the checkout has no
+* `upload-symbols`, or when the app does not bundle `GoogleService-Info.plist`.
+*/
+export declare function collectIosCrashlyticsSymbols(input: CollectIosCrashlyticsSymbolsInput): CollectedIosCrashlyticsSymbols;
+/** Every `*.dSYM` bundle of an archive's `dSYMs` folder, sorted, with its UUIDs. */
+export declare function readArchiveDsyms(dsymFolder: string): NativeDsymIdentity[];
+/** dSYM UUIDs as `dwarfdump --uuid` prints them. */
+export declare function isDsymUuid(value: unknown): value is string;
+/**
+* The `LC_UUID` of each architecture in a thin or universal Mach-O file,
+* read from its headers only (DWARF files can be hundreds of megabytes).
+*/
+export declare function readMachOUuids(file: string): string[];