@mpgd/cli 0.63.0 → 0.65.0

package/dist/store-presence-play.js

@@ -0,0 +1,495 @@
+import path from 'node:path';
+import { googlePlayPresenceImageSlots, googlePlayPresenceLimits, resolveStorePresenceImageSet, } from '@mpgd/catalog';
+import { isDefinitiveHttpError } from './play-internal-submission.js';
+import { assertLocalStoreImageUnchanged, describeTextChange, formatTextChange, imageMimeType, normalizeLineBreaks, planStoreImageSet, readLocalStoreImage, sameUrlForm, storePresencePlanCommand, } from './store-presence.js';
+import { canonicalLanguageTag, mapWithConcurrency, stableSha256, StorePlanStaleError, } from './store-sync.js';
+const readConcurrency = 4;
+const uploadTimeoutMs = 5 * 60_000;
+/** Read Play through a throwaway edit and plan; never writes. */
+export async function planPlayPresence(input, port) {
+    const play = requirePlay(input.presence);
+    // Graphics are read and checked before Play is asked anything.
+    const local = readLocalGraphics(input.directory, play);
+    const editId = await port.insertEdit(input.packageName, input.signal);
+    try {
+        return await planInEdit(input, play, local, port, editId);
+    }
+    finally {
+        await discardEdit(port, input.packageName, editId);
+    }
+}
+function requirePlay(presence) {
+    if (presence.googlePlay === undefined) {
+        throw new Error('The store presence file has no googlePlay section.');
+    }
+    return presence.googlePlay;
+}
+function readLocalGraphics(directory, play) {
+    const result = new Map();
+    for (const [language, listing] of Object.entries(play.listings)) {
+        const slots = new Map();
+        for (const slot of googlePlayPresenceImageSlots) {
+            const value = listing.graphics?.[slot];
+            if (value === undefined) {
+                continue;
+            }
+            const { files, complete } = typeof value === 'string'
+                ? { files: [value], complete: true }
+                : resolveStorePresenceImageSet(value);
+            const label = `googlePlay.listings.${language}.graphics.${slot}`;
+            const images = files.map((file) => readLocalStoreImage(directory, file, { store: 'google-play', slot }, label));
+            const digests = new Set(images.map((image) => image.sha256));
+            if (digests.size !== images.length) {
+                throw new Error(`${label} lists the same image twice under different names.`);
+            }
+            slots.set(slot, { images, complete });
+        }
+        result.set(language, slots);
+    }
+    return result;
+}
+async function planInEdit(input, play, local, port, editId) {
+    const { packageName, signal } = input;
+    const [details, remoteListings] = await Promise.all([
+        port.getDetails(packageName, editId, signal),
+        port.listListings(packageName, editId, signal),
+    ]);
+    const remoteByLanguage = new Map();
+    for (const listing of remoteListings) {
+        if (typeof listing.language === 'string') {
+            remoteByLanguage.set(listing.language.toLowerCase(), listing);
+        }
+    }
+    const languages = Object.keys(play.listings);
+    // Play's images of every slot the file manages, for languages Play lists.
+    const reads = languages.flatMap((language) => {
+        const remote = remoteByLanguage.get(language.toLowerCase());
+        if (remote === undefined) {
+            return [];
+        }
+        return [...(local.get(language)?.keys() ?? [])].map((imageType) => ({
+            language,
+            remoteLanguage: String(remote.language),
+            imageType,
+        }));
+    });
+    const imageLists = await mapWithConcurrency(reads, readConcurrency, (read) => port.listImages({
+        packageName,
+        editId,
+        language: read.remoteLanguage,
+        imageType: read.imageType,
+        ...(signal === undefined ? {} : { signal }),
+    }));
+    const remoteImages = new Map();
+    reads.forEach((read, index) => {
+        remoteImages.set(`${read.language}\n${read.imageType}`, imageLists[index] ?? []);
+    });
+    const notes = [];
+    const planned = languages.map((language) => planLanguage({
+        notes,
+        language,
+        entry: play.listings[language],
+        remote: remoteByLanguage.get(language.toLowerCase()),
+        local: local.get(language) ?? new Map(),
+        remoteImages: (imageType) => remoteImages.get(`${language}\n${imageType}`) ?? [],
+    }));
+    const named = new Set(languages.map((language) => language.toLowerCase()));
+    const remoteOnlyLanguages = remoteListings
+        .map((listing) => String(listing.language))
+        .filter((language) => !named.has(language.toLowerCase()))
+        .sort();
+    const defaultLanguage = typeof details.defaultLanguage === 'string'
+        ? details.defaultLanguage
+        : undefined;
+    if (defaultLanguage !== undefined && !named.has(defaultLanguage.toLowerCase())) {
+        notes.push(`Play's default language ${defaultLanguage} is not in the file; its listing stays as Play has it.`);
+    }
+    const plannedDetails = planDetails(details, play, notes);
+    const manual = manualSteps(input.presence);
+    const imageRemovals = planned.reduce((sum, language) => sum + language.images.reduce((count, slot) => count + (slot.complete && isMultiImage(slot.imageType) ? slot.remove.length : 0), 0), 0);
+    const changed = plannedDetails !== undefined || planned.some((language) => language.action !== 'unchanged' || language.images.some((slot) => slot.action !== 'unchanged'));
+    // Images by ID and digest only: their preview URLs may differ per request.
+    const remoteSha256 = stableSha256({
+        details,
+        listings: [...remoteListings].sort((left, right) => String(left.language).localeCompare(String(right.language))),
+        images: Object.fromEntries([...remoteImages.entries()]
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, images]) => [
+            key,
+            images.map((image) => ({ id: image.id, sha256: image.sha256, sha1: image.sha1 })),
+        ])),
+    });
+    const desiredSha256 = stableSha256({ details: plannedDetails?.write, languages: planned });
+    return {
+        schemaVersion: 1,
+        store: 'google-play',
+        packageName,
+        ...(plannedDetails === undefined ? {} : { details: plannedDetails }),
+        languages: planned,
+        remoteOnlyLanguages,
+        imageRemovals,
+        changed,
+        notes,
+        manual,
+        remoteSha256,
+        desiredSha256,
+    };
+}
+function planLanguage(input) {
+    const { entry, remote } = input;
+    const language = typeof remote?.language === 'string'
+        ? remote.language
+        : canonicalLanguageTag(input.language);
+    const video = entry.video ?? (typeof remote?.video === 'string' && remote.video !== '' ? remote.video : undefined);
+    const fullDescription = normalizeLineBreaks(entry.fullDescription);
+    const text = [
+        describeTextChange('title', remote?.title, entry.title),
+        describeTextChange('shortDescription', remote?.shortDescription, entry.shortDescription),
+        describeTextChange('fullDescription', remote?.fullDescription, fullDescription),
+        entry.video === undefined ? undefined : describeTextChange('video', remote?.video, entry.video),
+    ].filter((change) => change !== undefined);
+    if (entry.video !== undefined && typeof remote?.video === 'string' && remote.video !== entry.video
+        && sameUrlForm(remote.video, entry.video)) {
+        input.notes.push(`${language} video differs from Play's only in URL form (${remote.video}); Play may normalize it.`);
+    }
+    const images = googlePlayPresenceImageSlots.flatMap((imageType) => {
+        const slot = input.local.get(imageType);
+        return slot === undefined
+            ? []
+            : [planImageSlot(imageType, slot.images, slot.complete, input.remoteImages(imageType))];
+    });
+    const action = remote === undefined
+        ? 'create'
+        : text.length > 0
+            ? 'update'
+            : 'unchanged';
+    return {
+        language,
+        action,
+        text,
+        ...(action === 'unchanged' ? {} : {
+            listing: {
+                language,
+                title: entry.title,
+                shortDescription: entry.shortDescription,
+                fullDescription,
+                ...(video === undefined ? {} : { video }),
+            },
+        }),
+        images,
+    };
+}
+function isMultiImage(imageType) {
+    return imageType !== 'icon' && imageType !== 'featureGraphic';
+}
+function planImageSlot(imageType, local, complete, remote) {
+    const plan = planStoreImageSet({
+        local: local.map((image) => ({ path: image.path, digest: image.sha256 })),
+        remote: remote.map((image) => ({
+            id: String(image.id),
+            digest: remoteImageDigest(image, local, imageType),
+        })),
+        complete,
+        single: !isMultiImage(imageType),
+        maxImages: googlePlayPresenceLimits.screenshots,
+        label: `Google Play ${imageType}`,
+        storeName: 'Play',
+    });
+    return {
+        imageType,
+        action: plan.action,
+        complete,
+        upload: plan.upload.map((image) => ({ path: image.path, sha256: image.digest })),
+        keep: plan.keep,
+        remove: plan.remove.map((image) => ({ id: image.id, sha256: image.digest })),
+        notes: plan.notes,
+    };
+}
+/**
+ * The digest a Play image is compared by: its SHA-256, else (Play reported
+ * only SHA-1) the SHA-256 of the file image with that SHA-1. An image with
+ * neither cannot be compared, so the plan stops instead of re-uploading it
+ * on every run.
+ */
+function remoteImageDigest(image, local, imageType) {
+    if (typeof image.sha256 === 'string' && image.sha256 !== '') {
+        return image.sha256.toLowerCase();
+    }
+    if (typeof image.sha1 === 'string' && image.sha1 !== '') {
+        const sha1 = image.sha1.toLowerCase();
+        return local.find((candidate) => candidate.sha1 === sha1)?.sha256 ?? `sha1:${sha1}`;
+    }
+    throw new Error(`Google Play ${imageType}: Play reports image ${String(image.id)} without a SHA-256 or SHA-1, so the sync `
+        + 'cannot compare it; replace the images of this slot in Play Console.');
+}
+function planDetails(details, play, notes) {
+    const contact = play.contact;
+    if (contact === undefined) {
+        return undefined;
+    }
+    const changes = [];
+    const write = {};
+    for (const [field, value] of Object.entries(details)) {
+        if (typeof value === 'string' && value !== '') {
+            write[field] = value;
+        }
+    }
+    const fields = [
+        ['contactEmail', contact.email],
+        ['contactWebsite', contact.website],
+        ['contactPhone', contact.phone],
+    ];
+    for (const [field, value] of fields) {
+        if (value === undefined) {
+            continue;
+        }
+        const from = details[field];
+        if (from !== value) {
+            if (field === 'contactWebsite' && typeof from === 'string' && sameUrlForm(from, value)) {
+                notes.push(`The contact website differs from Play's only in URL form (${from}); Play may normalize it.`);
+            }
+            changes.push({
+                field,
+                ...(typeof from === 'string' && from !== '' ? { from } : {}),
+                to: value,
+            });
+            write[field] = value;
+        }
+    }
+    if (changes.length === 0) {
+        return undefined;
+    }
+    // edits.details.update replaces the whole object, and Play requires a contact email.
+    if (write.contactEmail === undefined) {
+        throw new Error('Google Play has no contact email for the app and the file gives none; Play needs one to update the '
+            + 'contact details. Add googlePlay.contact.email.');
+    }
+    return { changes, write };
+}
+function manualSteps(presence) {
+    const steps = [];
+    if (presence.privacyPolicyUrl !== undefined) {
+        steps.push(`Privacy policy (Play Console > Policy and programs > App content): ${presence.privacyPolicyUrl}; `
+            + 'the Android Publisher API has no field for it.');
+    }
+    steps.push('Data safety, content rating, target audience, ads and the app category stay in Play Console '
+        + '(App content and Store settings).');
+    return steps;
+}
+export class PlayPresenceApplyError extends Error {
+    stage;
+    outcome;
+    constructor(stage, 
+    /** `discarded`: Play discarded the edit; `unknown`: the commit may or may not have landed. */
+    outcome, cause) {
+        super(`Google Play ${stage} failed (${cause instanceof Error ? cause.message : String(cause)}). ${outcome === 'discarded'
+            ? 'The edit was discarded; nothing was published.'
+            : 'The commit result is unknown.'} Run "${storePresencePlanCommand}" again: it reads Play and lists `
+            + 'what is left.', { cause });
+        this.stage = stage;
+        this.outcome = outcome;
+        this.name = 'PlayPresenceApplyError';
+    }
+}
+/**
+ * Apply a reviewed plan in one edit: re-plan inside the edit, refuse when
+ * Play or the files moved past the reviewed plan, write, then commit once.
+ * A plan whose changes already landed is a no-op, so a re-run is safe.
+ */
+export async function applyPlayPresence(input) {
+    const { saved, port } = input;
+    const { packageName, signal } = input.plan;
+    if (!input.approved) {
+        throw new Error('Writing the Google Play store listing requires --approve.');
+    }
+    if (saved.packageName !== packageName) {
+        throw new StorePlanStaleError(`The deployment profile now names ${packageName}, not ${saved.packageName}.`, storePresencePlanCommand);
+    }
+    const play = requirePlay(input.plan.presence);
+    const local = readLocalGraphics(input.plan.directory, play);
+    const editId = await port.insertEdit(packageName, signal);
+    let stage = 'read';
+    // A commit that failed without a definitive answer may have landed.
+    let commitUncertain = false;
+    try {
+        const current = await planInEdit(input.plan, play, local, port, editId);
+        if (!current.changed) {
+            await discardEdit(port, packageName, editId);
+            return { packageName, status: 'unchanged', languages: [] };
+        }
+        if (current.remoteSha256 !== saved.remoteSha256 || current.desiredSha256 !== saved.desiredSha256) {
+            throw new StorePlanStaleError('The Google Play store listing or the store presence file changed since the plan.', storePresencePlanCommand);
+        }
+        if (current.imageRemovals > 0 && input.confirmImageRemoval !== true) {
+            throw new Error(`The plan removes ${current.imageRemovals} image(s) from Google Play; confirm with --confirm-image-removal.`);
+        }
+        const optionalSignal = signal === undefined ? {} : { signal };
+        if (current.details !== undefined) {
+            stage = 'details update';
+            await port.updateDetails({
+                packageName,
+                editId,
+                details: current.details.write,
+                ...optionalSignal,
+            });
+        }
+        const languages = [];
+        for (const language of current.languages) {
+            if (language.listing !== undefined) {
+                stage = `listing ${language.language}`;
+                await port.updateListing({
+                    packageName,
+                    editId,
+                    listing: language.listing,
+                    ...optionalSignal,
+                });
+            }
+            let uploaded = 0;
+            for (const slot of language.images) {
+                if (slot.action === 'unchanged') {
+                    continue;
+                }
+                const target = {
+                    packageName,
+                    editId,
+                    language: language.language,
+                    imageType: slot.imageType,
+                    ...optionalSignal,
+                };
+                if (slot.action === 'replace') {
+                    stage = `${language.language} ${slot.imageType} delete`;
+                    await port.deleteAllImages(target);
+                }
+                for (const image of slot.upload) {
+                    stage = `${language.language} ${slot.imageType} upload of ${image.path}`;
+                    const file = path.resolve(input.plan.directory, image.path);
+                    assertLocalStoreImageUnchanged(file, image.sha256);
+                    const localFile = localImage(local, language.language, slot.imageType, image.sha256);
+                    const stored = await port.uploadImage({
+                        ...target,
+                        file,
+                        mimeType: imageMimeType(localFile.info),
+                        timeoutMs: uploadTimeoutMs,
+                    });
+                    uploaded += 1;
+                    assertStoredDigest(stored, localFile);
+                }
+            }
+            languages.push({ language: language.language, listing: language.action, images: uploaded });
+        }
+        stage = 'commit';
+        try {
+            await port.commitEdit({
+                packageName,
+                editId,
+                changesNotSentForReview: input.changesNotSentForReview === true,
+                ...optionalSignal,
+            });
+        }
+        catch (error) {
+            // A definitive 4xx (for example ERROR_IF_IN_REVIEW while a release is
+            // in review) did not commit; anything else may have.
+            commitUncertain = !isDefinitiveHttpError(error);
+            throw error;
+        }
+        return { packageName, status: 'committed', languages };
+    }
+    catch (error) {
+        // Never delete an edit that may have been committed (as deploy promote).
+        if (!commitUncertain) {
+            await discardEdit(port, packageName, editId);
+        }
+        // Nothing was written before the first write stage: the error stands as it is.
+        if (error instanceof StorePlanStaleError || stage === 'read') {
+            throw error;
+        }
+        throw new PlayPresenceApplyError(stage, commitUncertain ? 'unknown' : 'discarded', error);
+    }
+}
+/**
+ * Images are matched by digest: one Play stores under another digest (for
+ * example re-encoded) would be uploaded again by every later apply, and one
+ * without a digest could never be matched.
+ */
+function assertStoredDigest(stored, image) {
+    if (typeof stored.sha256 === 'string' && stored.sha256 !== '') {
+        if (stored.sha256.toLowerCase() !== image.sha256) {
+            throw new Error(`Play stored ${image.path} with SHA-256 ${stored.sha256}, not the file's ${image.sha256}; `
+                + 'the sync matches images by digest and cannot keep this slot in step');
+        }
+        return;
+    }
+    if (typeof stored.sha1 === 'string' && stored.sha1 !== '') {
+        if (stored.sha1.toLowerCase() !== image.sha1) {
+            throw new Error(`Play stored ${image.path} with SHA-1 ${stored.sha1}, not the file's ${image.sha1}; `
+                + 'the sync matches images by digest and cannot keep this slot in step');
+        }
+        return;
+    }
+    throw new Error(`Play answered the upload of ${image.path} without a SHA-256 or SHA-1; the sync cannot confirm it`);
+}
+function localImage(local, language, imageType, sha256) {
+    for (const [fileLanguage, slots] of local) {
+        if (fileLanguage.toLowerCase() !== language.toLowerCase()) {
+            continue;
+        }
+        const image = slots.get(imageType)?.images.find((candidate) => candidate.sha256 === sha256);
+        if (image !== undefined) {
+            return image;
+        }
+    }
+    throw new StorePlanStaleError(`${language} ${imageType} image ${sha256} is no longer in the file.`, storePresencePlanCommand);
+}
+/** Discard an edit; a failure here must not hide the error that led to it. */
+async function discardEdit(port, packageName, editId) {
+    try {
+        await port.deleteEdit(packageName, editId);
+    }
+    catch {
+        // An invalidated or committed edit cannot be deleted; Play drops it anyway.
+    }
+}
+/** The plan for the terminal: per language, the text and image changes. */
+export function formatPlayPresencePlan(plan) {
+    const lines = [
+        `Google Play ${plan.packageName} store listing${plan.changed ? '' : ': no changes'}`,
+    ];
+    for (const change of plan.details?.changes ?? []) {
+        lines.push(`  details   ${change.field}: ${JSON.stringify(change.from ?? null)} -> ${JSON.stringify(change.to)}`);
+    }
+    for (const language of plan.languages) {
+        const changedSlots = language.images.filter((slot) => slot.action !== 'unchanged');
+        lines.push(`  ${language.action.padEnd(9)} ${language.language}${changedSlots.length === 0 ? '' : ` (images: ${changedSlots.map((slot) => slot.imageType).join(', ')})`}`);
+        for (const change of language.text) {
+            lines.push(`            ${formatTextChange(change)}`);
+        }
+        for (const slot of language.images) {
+            if (slot.action === 'unchanged' && slot.notes.length === 0) {
+                continue;
+            }
+            lines.push(`            ${slot.imageType}: ${slot.action}${slot.complete && isMultiImage(slot.imageType) ? ' (complete set)' : ''}`);
+            for (const image of slot.upload) {
+                lines.push(`              + ${image.path} ${image.sha256.slice(0, 12)}`);
+            }
+            for (const image of slot.remove) {
+                lines.push(`              - ${image.id} ${image.sha256.slice(0, 12) || '(no digest)'}`);
+            }
+            for (const note of slot.notes) {
+                lines.push(`              note: ${note}`);
+            }
+        }
+    }
+    for (const language of plan.remoteOnlyLanguages) {
+        lines.push(`  remote    ${language}: only on Play; not in the file (never deleted)`);
+    }
+    if (plan.imageRemovals > 0) {
+        lines.push(`  IMAGE REMOVAL: ${plan.imageRemovals} image(s); apply needs --confirm-image-removal`);
+    }
+    for (const note of plan.notes) {
+        lines.push(`  note      ${note}`);
+    }
+    for (const step of plan.manual) {
+        lines.push(`  manual    ${step}`);
+    }
+    return lines.join('\n');
+}

package/dist/store-presence.d.ts

@@ -0,0 +1,106 @@
+import { type StoreImageInfo, type StorePresence, type StorePresenceImageSlot } from '@mpgd/catalog';
+/**
+* The game side of `mpgd store presence plan|apply`: the store presence
+* file and the graphics it names, read and checked against the store rules
+* before anything talks to a store.
+*/
+export declare const defaultStorePresenceFileName = "mpgd.store-presence.json";
+export declare const storePresencePlanCommand = "mpgd store presence plan";
+export interface StorePresenceSource {
+  readonly file: string;
+  /** Graphics paths resolve against this directory. */
+  readonly directory: string;
+  readonly presence: StorePresence;
+}
+/**
+* Read and validate the store presence file. A given path resolves against
+* the current directory, like the other mpgd file flags; the default is the
+* game's own file.
+*/
+export declare function readStorePresenceSource(input: {
+  readonly gameRoot: string;
+  readonly presenceFile?: string;
+}): StorePresenceSource;
+/** One graphic the file names, read from this checkout. */
+export interface LocalStoreImage {
+  /** Path relative to the store presence file, as the file names it. */
+  readonly path: string;
+  /** Absolute path on this checkout. */
+  readonly file: string;
+  readonly sha256: string;
+  /** For a store that reports only SHA-1. */
+  readonly sha1: string;
+  readonly md5: string;
+  readonly byteLength: number;
+  readonly info: StoreImageInfo;
+}
+/**
+* Read one graphic: it must stay inside the file's directory (symbolic links
+* included), be the PNG or JPEG its extension says, and meet the store's
+* rules for its slot.
+*/
+export declare function readLocalStoreImage(directory: string, relative: string, target: StorePresenceImageSlot, label: string): LocalStoreImage;
+/** Refuse to upload a graphic whose bytes changed after the plan was checked. */
+export declare function assertLocalStoreImageUnchanged(file: string, sha256: string): void;
+export declare function imageMimeType(info: StoreImageInfo): 'image/png' | 'image/jpeg';
+/**
+* A text field change for the plan output: lengths always, the texts
+* themselves only while both are short.
+*/
+export interface StorePresenceTextChange {
+  readonly field: string;
+  readonly fromLength: number | null;
+  readonly toLength: number;
+  readonly from?: string;
+  readonly to?: string;
+}
+/** CRLF and lone CR as LF, so a file saved on Windows and the store's text compare equal. */
+export declare function normalizeLineBreaks(value: string): string;
+/**
+* Two URLs that differ only in form (host case, a trailing slash, default
+* port): a store may normalize the URL it was given.
+*/
+export declare function sameUrlForm(left: string, right: string): boolean;
+/** Compares after normalizing line breaks; `to` is expected normalized already. */
+export declare function describeTextChange(field: string, from: string | null | undefined, to: string): StorePresenceTextChange | undefined;
+export declare function formatTextChange(change: StorePresenceTextChange): string;
+/** One image the store holds, by its ID and the digest the store reports for it. */
+export interface RemoteStoreImage {
+  readonly id: string;
+  /** Lowercase hex; empty when the store reports none. */
+  readonly digest: string;
+}
+export interface StoreImageSetPlan {
+  /** `add` uploads after the store's images; `replace` deletes the store's first. */
+  readonly action: 'unchanged' | 'add' | 'replace';
+  /** Uploads, in order. */
+  readonly upload: readonly {
+    readonly path: string;
+    readonly digest: string;
+  }[];
+  /** Digests of the store's images that stay. */
+  readonly keep: readonly string[];
+  /** The store's images the write removes and does not upload again. */
+  readonly remove: readonly RemoteStoreImage[];
+  readonly notes: readonly string[];
+}
+/**
+* Plan one image slot. A single-image slot (an icon) is replaced when it
+* differs. A list adds the images the store lacks after the ones it holds;
+* a complete set appends when the store holds a prefix of it, else replaces
+* the slot so the store holds exactly the set in order.
+*/
+export declare function planStoreImageSet(input: {
+  readonly local: readonly {
+    readonly path: string;
+    readonly digest: string;
+  }[];
+  readonly remote: readonly RemoteStoreImage[];
+  readonly complete: boolean;
+  readonly single: boolean;
+  readonly maxImages: number;
+  /** For messages: the slot, for example "Google Play phoneScreenshots". */
+  readonly label: string;
+  /** For messages: "Play" or "App Store Connect". */
+  readonly storeName: string;
+}): StoreImageSetPlan;