@mpgd/cli 0.59.0 → 0.61.1

package/dist/play-release-options.js

@@ -0,0 +1,307 @@
+import { createHash } from 'node:crypto';
+import { createReadStream, existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+/** The kit's original destination; Play's tracks guide also lists this track as `qa`. */
+export const defaultPlayTrack = 'internal';
+/** Play Console: "up to 500 Unicode characters per language". */
+export const maximumPlayReleaseNoteCharacters = 500;
+const maximumReleaseNotesFileBytes = 256 * 1024;
+// A default name (`production`, `beta`, `alpha`, `internal`, `qa`), a custom
+// closed-testing track name, or either behind a form-factor prefix
+// (`wear:production`). Path-unsafe characters are refused before any request.
+const trackNamePattern = /^(?:[a-z][a-z0-9_]{0,31}:)?[A-Za-z0-9](?:[A-Za-z0-9 ._-]{0,98}[A-Za-z0-9._-])?$/u;
+const wellKnownTrackPattern = /^(?:[a-z][a-z0-9_]*:)?(?:internal|qa|alpha|beta|production)$/iu;
+const languageTagPattern = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*$/u;
+const sha256Pattern = /^[a-f0-9]{64}$/u;
+export const defaultPlayReleaseRequest = Object.freeze({
+    track: defaultPlayTrack,
+    status: 'completed',
+});
+/** Validate CLI release options; with none it returns the internal/completed default. */
+export async function createPlayReleaseRequest(input) {
+    const track = input.track ?? defaultPlayTrack;
+    const status = input.status ?? 'completed';
+    if (status === 'halted') {
+        throw new Error('A new Google Play release cannot start halted; use "mpgd deploy rollout --action halt" '
+            + 'on the release once it is in progress.');
+    }
+    if (status !== 'draft' && status !== 'completed' && status !== 'inProgress') {
+        throw new Error('--status must be draft, completed or inProgress.');
+    }
+    const userFraction = input.userFraction === undefined
+        ? undefined
+        : parsePlayUserFraction(input.userFraction);
+    const releaseNotes = input.releaseNotesFile === undefined
+        ? undefined
+        : readPlayReleaseNotesFile(input.releaseNotesFile);
+    let mapping;
+    if (input.mappingFile !== undefined) {
+        const mappingFile = path.resolve(input.mappingFile);
+        mapping = { mappingFile, mappingSha256: await hashMappingFile(mappingFile) };
+    }
+    const request = {
+        track,
+        status,
+        ...(userFraction === undefined ? {} : { userFraction }),
+        ...(releaseNotes === undefined ? {} : { releaseNotes }),
+        ...(mapping ?? {}),
+    };
+    assertPlayReleaseRequest(request);
+    return request;
+}
+/** Re-check a programmatic request; the CLI path builds it with createPlayReleaseRequest. */
+export function assertPlayReleaseRequest(request) {
+    assertPlayTrackName(request.track);
+    if (request.status !== 'draft' && request.status !== 'completed'
+        && request.status !== 'inProgress') {
+        throw new Error('Google Play release status must be draft, completed or inProgress.');
+    }
+    if (request.status === 'inProgress') {
+        if (request.userFraction === undefined) {
+            throw new Error('An inProgress (staged) Google Play release needs --user-fraction.');
+        }
+        assertPlayUserFraction(request.userFraction);
+    }
+    else if (request.userFraction !== undefined) {
+        throw new Error('--user-fraction applies only to an inProgress (staged) release.');
+    }
+    if (request.releaseNotes !== undefined) {
+        assertPlayReleaseNotes(request.releaseNotes);
+    }
+    if ((request.mappingFile === undefined) !== (request.mappingSha256 === undefined)
+        || (request.mappingFile !== undefined && !path.isAbsolute(request.mappingFile))
+        || (request.mappingSha256 !== undefined && !sha256Pattern.test(request.mappingSha256))) {
+        throw new Error('Google Play mapping file must be an absolute path with its SHA-256.');
+    }
+}
+export function assertPlayTrackName(track) {
+    if (!trackNamePattern.test(track)) {
+        throw new Error('Google Play track must be internal, alpha, beta, production, or a closed-testing '
+            + 'track name (letters, digits, space, ".", "_", "-"; optional form-factor prefix).');
+    }
+}
+/** `production` and form-factor production tracks such as `wear:production`. */
+export function isProductionTrack(track) {
+    // Case-insensitive, so `Production` is never treated as a testing track.
+    return /^(?:[a-z][a-z0-9_]*:)?production$/iu.test(track.trim());
+}
+/**
+ * A default track (`internal`/`qa`, `alpha`, `beta`, `production`, optionally
+ * form-factor prefixed). Other names are closed-testing tracks, which "are
+ * created manually", so a missing one is a typo rather than an empty track.
+ */
+export function isWellKnownPlayTrack(track) {
+    return wellKnownTrackPattern.test(track);
+}
+/** Production releases and every staged rollout need an explicit confirmation flag. */
+export function playReleaseNeedsConfirmation(request) {
+    return isProductionTrack(request.track) || request.status === 'inProgress';
+}
+export function assertPlayReleaseConfirmed(request, confirmed) {
+    if (playReleaseNeedsConfirmation(request) && !confirmed) {
+        throw new Error(`Google Play ${request.track} ${request.status} release needs --confirm-production: `
+            + 'production releases and staged rollouts are never made without it.');
+    }
+}
+export function isDefaultPlayReleaseRequest(request) {
+    return request.track === defaultPlayTrack && request.status === 'completed'
+        && request.userFraction === undefined && request.releaseNotes === undefined
+        && request.mappingFile === undefined;
+}
+/**
+ * Binds a submission checkpoint to the release options that started it, so a
+ * resumed edit is never committed with another track or status. The original
+ * internal/completed request has no digest, which keeps its checkpoints as before.
+ */
+export function playReleaseRequestDigest(request) {
+    if (isDefaultPlayReleaseRequest(request)) {
+        return undefined;
+    }
+    return createHash('sha256').update(JSON.stringify({
+        track: request.track,
+        status: request.status,
+        userFraction: request.userFraction ?? null,
+        releaseNotes: request.releaseNotes ?? [],
+        mappingSha256: request.mappingSha256 ?? null,
+    })).digest('hex');
+}
+export function parsePlayUserFraction(value) {
+    const fraction = typeof value === 'number'
+        ? value
+        : /^(?:0(?:\.\d+)?|\.\d+|1(?:\.0+)?)$/u.test(value.trim())
+            ? Number(value)
+            : Number.NaN;
+    assertPlayUserFraction(fraction);
+    return fraction;
+}
+/** Android Publisher v3 `Release.userFraction`: "0 < fraction < 1". */
+export function assertPlayUserFraction(fraction) {
+    if (!Number.isFinite(fraction) || fraction <= 0 || fraction >= 1) {
+        throw new Error('--user-fraction must be a number greater than 0 and less than 1 (for example 0.05); '
+            + 'use --status completed (or --action complete) for 100%.');
+    }
+}
+export function readPlayReleaseNotesFile(file) {
+    const resolved = path.resolve(file);
+    if (!existsSync(resolved) || !statSync(resolved).isFile()) {
+        throw new Error(`Release notes file is missing: ${resolved}`);
+    }
+    if (statSync(resolved).size > maximumReleaseNotesFileBytes) {
+        throw new Error('Release notes file is larger than 256 KiB.');
+    }
+    return parsePlayReleaseNotes(readFileSync(resolved, 'utf8'));
+}
+/**
+ * Accepts the Play Console's own language-tag format, one block per language:
+ *
+ *     <en-US>
+ *     Bug fixes.
+ *     </en-US>
+ *
+ * or JSON: `{ "en-US": "Bug fixes." }` or `[{ "language": "en-US", "text": "Bug fixes." }]`.
+ */
+export function parsePlayReleaseNotes(source) {
+    const content = source.replace(/^/u, '');
+    const trimmed = content.trim();
+    if (trimmed === '') {
+        throw new Error('Release notes file is empty.');
+    }
+    let notes;
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            throw new Error('Release notes JSON is malformed.');
+        }
+        notes = Array.isArray(parsed)
+            ? parsed.map((entry) => {
+                if (typeof entry !== 'object' || entry === null
+                    || typeof entry.language !== 'string'
+                    || typeof entry.text !== 'string'
+                    || Object.keys(entry).some((key) => key !== 'language' && key !== 'text')) {
+                    throw new Error('Release notes JSON array entries need only string language and text.');
+                }
+                const { language, text } = entry;
+                return { language, text: text.trim() };
+            })
+            : typeof parsed === 'object' && parsed !== null
+                ? Object.entries(parsed).map(([language, text]) => {
+                    if (typeof text !== 'string') {
+                        throw new Error(`Release notes for ${language} must be a string.`);
+                    }
+                    return { language, text: text.trim() };
+                })
+                : [];
+    }
+    else {
+        notes = [];
+        const block = /<([A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*)>([\s\S]*?)<\/\1>/gu;
+        let consumed = 0;
+        for (const match of content.matchAll(block)) {
+            if (content.slice(consumed, match.index).trim() !== '') {
+                throw new Error('Release notes text must sit between <language> and </language> tags.');
+            }
+            notes.push({ language: match[1] ?? '', text: (match[2] ?? '').trim() });
+            consumed = match.index + match[0].length;
+        }
+        if (content.slice(consumed).trim() !== '') {
+            throw new Error('Release notes text must sit between <language> and </language> tags.');
+        }
+    }
+    assertPlayReleaseNotes(notes);
+    return notes;
+}
+export function assertPlayReleaseNotes(notes) {
+    if (notes.length === 0) {
+        throw new Error('Release notes need at least one language.');
+    }
+    const seen = new Set();
+    for (const note of notes) {
+        if (!languageTagPattern.test(note.language)) {
+            throw new Error(`Release notes language is not a BCP-47 tag: ${note.language}`);
+        }
+        const key = note.language.toLowerCase();
+        if (seen.has(key)) {
+            throw new Error(`Release notes repeat the language ${note.language}.`);
+        }
+        seen.add(key);
+        if (note.text.trim() === '') {
+            throw new Error(`Release notes for ${note.language} are empty.`);
+        }
+        const length = [...note.text].length;
+        if (length > maximumPlayReleaseNoteCharacters) {
+            throw new Error(`Release notes for ${note.language} are ${length} characters; Google Play allows `
+                + `${maximumPlayReleaseNoteCharacters} per language.`);
+        }
+    }
+}
+export async function hashMappingFile(mappingFile) {
+    if (!existsSync(mappingFile) || !statSync(mappingFile).isFile()) {
+        throw new Error(`R8 mapping file is missing: ${mappingFile}`);
+    }
+    if (statSync(mappingFile).size === 0) {
+        throw new Error(`R8 mapping file is empty: ${mappingFile}`);
+    }
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(mappingFile)) {
+        hash.update(chunk);
+    }
+    return hash.digest('hex');
+}
+/** Build the Release body for a new bundle; the default matches the original body exactly. */
+export function newPlayRelease(request, name, versionCode) {
+    return {
+        name,
+        status: request.status,
+        versionCodes: [String(versionCode)],
+        ...(request.userFraction === undefined ? {} : { userFraction: request.userFraction }),
+        ...(request.releaseNotes === undefined ? {} : {
+            releaseNotes: request.releaseNotes.map((note) => ({
+                language: note.language,
+                text: note.text,
+            })),
+        }),
+    };
+}
+/**
+ * Add a new release to the releases Play returned for the track. Every other
+ * release is sent back unchanged, except the ones the new release supersedes:
+ * a completed or staged release replaces an in-progress or halted rollout, and
+ * a draft replaces an older draft. A track with only completed releases (the
+ * usual internal track) therefore gets exactly the original appended body.
+ */
+export function mergeNewPlayRelease(current, release) {
+    const superseded = [];
+    const kept = [];
+    for (const existing of current ?? []) {
+        const replaces = release.status === 'draft'
+            ? existing.status === 'draft'
+            : existing.status === 'inProgress' || existing.status === 'halted';
+        (replaces ? superseded : kept).push(existing);
+    }
+    return { releases: [...kept, release], superseded };
+}
+/**
+ * The Play Developer API answers "Only releases with status draft may be
+ * created on draft app." while an app has never been published. Google's API
+ * reference does not document it; it is reported by fastlane, the
+ * upload-google-play action and others, on edits.commit. Only a definitive 4xx
+ * with that text counts: the edit was not committed.
+ */
+export function isPlayDraftAppRejection(error) {
+    if (typeof error !== 'object' || error === null) {
+        return false;
+    }
+    const value = error;
+    const raw = value.response?.status ?? value.code;
+    const status = typeof raw === 'number' ? raw : typeof raw === 'string' ? Number(raw) : Number.NaN;
+    if (!(status >= 400 && status < 500)) {
+        return false;
+    }
+    const messages = [value.message, value.response?.data?.error?.message]
+        .filter((message) => typeof message === 'string');
+    return messages.some((message) => /only releases with status draft may be created on draft app/iu
+        .test(message));
+}

package/dist/play-release-promote.d.ts

@@ -0,0 +1,59 @@
+import type { PlayPublisher, PlayTrack, PlayTrackRelease } from './play-publisher-port.js';
+import { type PlayNewReleaseStatus, type PlayReleaseNote } from './play-release-options.js';
+/**
+* Promote a release that is already on one track to another track: the
+* target track's `edits.tracks.update` names the existing version codes, and
+* nothing is uploaded. This is the Play Console's "promote release" for the
+* build that passed testing (https://developers.google.com/android-publisher/tracks:
+* a version code uploaded once is released on a track by `Edits.tracks: update`).
+*/
+export interface PlayPromoteInput {
+  readonly packageName: string;
+  readonly fromTrack: string;
+  readonly toTrack: string;
+  /**
+  * Selects the source release that contains this version code; defaults to
+  * the source track's only completed release. The whole release (all its
+  * version codes) is promoted, never part of it.
+  */
+  readonly versionCode?: number;
+  /** Target release status; defaults to `completed`. */
+  readonly status?: PlayNewReleaseStatus;
+  /** Required for `inProgress`: 0 < fraction < 1. */
+  readonly userFraction?: number;
+  /** Defaults to the source release's notes. */
+  readonly releaseNotes?: readonly PlayReleaseNote[];
+  /** Required for production tracks and staged (inProgress) releases. */
+  readonly confirmProduction?: boolean;
+  /** `--approve`: required unless `dryRun`. */
+  readonly approved?: boolean;
+  /** Read both tracks in a throw-away edit and return the planned body without committing. */
+  readonly dryRun?: boolean;
+  readonly signal?: AbortSignal;
+}
+export interface PlayPromoteResult {
+  /** `committed`: Play accepted the edit. `unchanged`: already promoted. `dry-run`: nothing sent. */
+  readonly status: 'committed' | 'unchanged' | 'dry-run';
+  readonly packageName: string;
+  readonly fromTrack: string;
+  readonly toTrack: string;
+  readonly versionCodes: readonly string[];
+  readonly release: PlayTrackRelease;
+  /** Releases on the target track the promoted release replaces. */
+  readonly superseded: readonly PlayTrackRelease[];
+  readonly editId?: string;
+  /** The `edits.tracks.update` body (dry run only). */
+  readonly plannedTrack?: PlayTrack;
+}
+export declare class PlayPromoteUncertainError extends Error {
+  readonly stage: 'track-update' | 'validate' | 'commit';
+  readonly editId: string;
+  readonly versionCodes: readonly string[];
+  constructor(stage: 'track-update' | 'validate' | 'commit', editId: string, versionCodes: readonly string[]);
+}
+export declare function promotePlayRelease(input: PlayPromoteInput & {
+  readonly serviceAccountFile: string;
+}): Promise<PlayPromoteResult>;
+export declare function assertPlayPromoteInput(input: PlayPromoteInput): void;
+/** Credential-free injection point for the mock-transport tests. */
+export declare function promotePlayReleaseWithPublisher(input: PlayPromoteInput, publisher: PlayPublisher): Promise<PlayPromoteResult>;

package/dist/play-release-promote.js

@@ -0,0 +1,235 @@
+import { existsSync, statSync } from 'node:fs';
+import { isDefinitiveHttpError, isHttpStatus, matchesRequestedRelease, } from './play-internal-submission.js';
+import { assertPlayReleaseConfirmed, assertPlayReleaseNotes, assertPlayTrackName, assertPlayUserFraction, isWellKnownPlayTrack, mergeNewPlayRelease, } from './play-release-options.js';
+export class PlayPromoteUncertainError extends Error {
+    stage;
+    editId;
+    versionCodes;
+    constructor(stage, editId, versionCodes) {
+        super(`Google Play promote ${stage} result is uncertain for edit ${editId}. Re-run the same `
+            + `command with --version-code ${versionCodes[0] ?? ''}: it reads the target track first `
+            + 'and reports "unchanged" if the promotion landed.');
+        this.stage = stage;
+        this.editId = editId;
+        this.versionCodes = versionCodes;
+        this.name = 'PlayPromoteUncertainError';
+    }
+}
+// Only a release that is being served can be promoted: a draft was never
+// tested, and a halted one was stopped for a reason.
+const promotableStatuses = ['completed', 'inProgress'];
+export async function promotePlayRelease(input) {
+    if (!existsSync(input.serviceAccountFile) || !statSync(input.serviceAccountFile).isFile()) {
+        throw new Error('Google Play service account file is missing.');
+    }
+    assertPlayPromoteInput(input);
+    const { createServiceAccountPublisher } = await import(new URL('./play-sdk-adapter.js', import.meta.url).href);
+    return promotePlayReleaseWithPublisher(input, createServiceAccountPublisher(input.serviceAccountFile));
+}
+export function assertPlayPromoteInput(input) {
+    assertPlayTrackName(input.fromTrack);
+    assertPlayTrackName(input.toTrack);
+    if (sameTrack(input.fromTrack, input.toTrack)) {
+        throw new Error('--from and --to must name different Google Play tracks.');
+    }
+    if (input.versionCode !== undefined
+        && (!Number.isSafeInteger(input.versionCode) || input.versionCode < 1)) {
+        throw new Error('--version-code must be a positive integer.');
+    }
+    const status = input.status ?? 'completed';
+    if (status !== 'draft' && status !== 'completed' && status !== 'inProgress') {
+        throw new Error('--status must be draft, completed or inProgress.');
+    }
+    if (status === 'inProgress') {
+        if (input.userFraction === undefined) {
+            throw new Error('An inProgress (staged) Google Play release needs --user-fraction.');
+        }
+        assertPlayUserFraction(input.userFraction);
+    }
+    else if (input.userFraction !== undefined) {
+        throw new Error('--user-fraction applies only to an inProgress (staged) release.');
+    }
+    if (input.releaseNotes !== undefined) {
+        assertPlayReleaseNotes(input.releaseNotes);
+    }
+}
+/** Credential-free injection point for the mock-transport tests. */
+export async function promotePlayReleaseWithPublisher(input, publisher) {
+    assertPlayPromoteInput(input);
+    const status = input.status ?? 'completed';
+    if (input.dryRun !== true && input.approved !== true) {
+        throw new Error('Promoting a Google Play release requires --approve.');
+    }
+    if (input.dryRun !== true) {
+        assertPlayReleaseConfirmed({ track: input.toTrack, status }, input.confirmProduction === true);
+    }
+    input.signal?.throwIfAborted();
+    const { packageName, fromTrack, toTrack } = input;
+    const editId = await publisher.insertEdit(packageName, input.signal);
+    let committed = false;
+    try {
+        const source = await readTrack(publisher, packageName, editId, fromTrack, input.signal, true);
+        const sourceRelease = selectSourceRelease(source.releases ?? [], input);
+        // Always the whole source release, so a re-run with any of its version
+        // codes (as PlayPromoteUncertainError suggests) asks for the same set.
+        const versionCodes = [...(sourceRelease.versionCodes ?? [])];
+        if (versionCodes.length === 0) {
+            throw new Error(`Google Play ${fromTrack} release has no version codes to promote.`);
+        }
+        const notes = input.releaseNotes ?? copiedNotes(sourceRelease);
+        const release = {
+            ...(typeof sourceRelease.name === 'string' ? { name: sourceRelease.name } : {}),
+            status,
+            versionCodes,
+            ...(input.userFraction === undefined ? {} : { userFraction: input.userFraction }),
+            ...(notes === undefined ? {} : { releaseNotes: notes }),
+        };
+        const target = await readTrack(publisher, packageName, editId, toTrack, input.signal, !isWellKnownPlayTrack(toTrack));
+        const targetReleases = target.releases ?? [];
+        const already = targetReleases.filter((item) => versionCodes.some((code) => item.versionCodes?.includes(code)));
+        if (already.length > 0) {
+            const same = already.length === 1 && already[0] !== undefined
+                && already[0].status === status
+                && sameCodes(already[0].versionCodes, versionCodes)
+                && matchesRequestedRelease(already[0], {
+                    track: toTrack,
+                    status,
+                    ...(input.userFraction === undefined ? {} : { userFraction: input.userFraction }),
+                    ...(input.releaseNotes === undefined ? {} : { releaseNotes: input.releaseNotes }),
+                }, status);
+            if (!same) {
+                throw new Error(`Google Play ${toTrack} already has version ${versionCodes.join(',')} as ${already.map((item) => String(item.status)).join(', ')} with other options; change it with "mpgd deploy rollout" or inspect it.`);
+            }
+            return {
+                status: 'unchanged',
+                packageName,
+                fromTrack,
+                toTrack,
+                versionCodes,
+                release: already[0] ?? release,
+                superseded: [],
+            };
+        }
+        if (status === 'inProgress'
+            && !targetReleases.some((item) => item.status === 'completed')) {
+            // Play Console: "Rollout percentage options are unavailable for a first release."
+            throw new Error(`Google Play ${toTrack} has no completed release yet, so a staged rollout cannot start; `
+                + 'promote with --status completed (or draft) first.');
+        }
+        const merged = mergeNewPlayRelease(targetReleases, release);
+        const desired = { track: toTrack, releases: merged.releases };
+        if (input.dryRun === true) {
+            return {
+                status: 'dry-run',
+                packageName,
+                fromTrack,
+                toTrack,
+                versionCodes,
+                release,
+                superseded: merged.superseded,
+                plannedTrack: desired,
+            };
+        }
+        try {
+            await publisher.updateTrack(packageName, editId, desired, input.signal);
+        }
+        catch (error) {
+            if (isDefinitiveHttpError(error)) {
+                throw error;
+            }
+            throw new PlayPromoteUncertainError('track-update', editId, versionCodes);
+        }
+        try {
+            await publisher.validateEdit(packageName, editId, input.signal);
+        }
+        catch (error) {
+            if (isDefinitiveHttpError(error)) {
+                throw error;
+            }
+            throw new PlayPromoteUncertainError('validate', editId, versionCodes);
+        }
+        try {
+            await publisher.commitEdit(packageName, editId, input.signal);
+        }
+        catch (error) {
+            if (isDefinitiveHttpError(error)) {
+                throw error;
+            }
+            committed = true; // Unknown: never delete an edit that may have been committed.
+            throw new PlayPromoteUncertainError('commit', editId, versionCodes);
+        }
+        committed = true;
+        return {
+            status: 'committed',
+            packageName,
+            fromTrack,
+            toTrack,
+            versionCodes,
+            release,
+            superseded: merged.superseded,
+            editId,
+        };
+    }
+    finally {
+        if (!committed) {
+            // Discard the uncommitted edit (dry run, no-op or refusal); a failure here is harmless.
+            await publisher.deleteEdit(packageName, editId, input.signal).catch(() => undefined);
+        }
+    }
+}
+async function readTrack(publisher, packageName, editId, track, signal, mustExist) {
+    try {
+        return await publisher.getTrack(packageName, editId, track, signal);
+    }
+    catch (error) {
+        if (isHttpStatus(error, 404)) {
+            if (mustExist) {
+                throw new Error(`Google Play has no ${track} track for ${packageName}.`);
+            }
+            return { track, releases: [] };
+        }
+        throw error;
+    }
+}
+function selectSourceRelease(releases, input) {
+    const listed = releases.map((release) => `${String(release.status)} [${(release.versionCodes ?? []).join(',')}]`).join('; ') || 'none';
+    if (input.versionCode !== undefined) {
+        const matches = releases.filter((release) => release.versionCodes?.includes(String(input.versionCode)));
+        const match = matches[0];
+        if (matches.length > 1) {
+            throw new Error(`Google Play ${input.fromTrack} has several releases with version code `
+                + `${input.versionCode}; inspect the track. Releases: ${listed}.`);
+        }
+        if (match === undefined) {
+            throw new Error(`Google Play ${input.fromTrack} has no release with version code ${input.versionCode}; `
+                + `only a version already on the source track can be promoted. Releases: ${listed}.`);
+        }
+        if (!promotableStatuses.includes(String(match.status))) {
+            throw new Error(`Google Play ${input.fromTrack} version ${input.versionCode} is ${String(match.status)}; `
+                + 'only a completed or in-progress release can be promoted.');
+        }
+        return match;
+    }
+    const completed = releases.filter((release) => release.status === 'completed');
+    if (completed.length !== 1 || completed[0] === undefined) {
+        throw new Error(`Google Play ${input.fromTrack} needs exactly one completed release to promote; pass `
+            + `--version-code. Releases: ${listed}.`);
+    }
+    return completed[0];
+}
+/** Same track, ignoring case and the `internal`/`qa` alias of the internal track. */
+function sameTrack(left, right) {
+    const normal = (track) => track.trim().toLowerCase().replace(/(^|:)qa$/u, '$1internal');
+    return normal(left) === normal(right);
+}
+function copiedNotes(release) {
+    const notes = (release.releaseNotes ?? []).flatMap((note) => typeof note.language === 'string' && typeof note.text === 'string'
+        ? [{ language: note.language, text: note.text }]
+        : []);
+    return notes.length === 0 ? undefined : notes;
+}
+function sameCodes(observed, wanted) {
+    const left = [...(observed ?? [])].sort();
+    const right = [...wanted].sort();
+    return left.length === right.length && left.every((code, index) => code === right[index]);
+}

package/dist/play-release-rollout.d.ts

@@ -0,0 +1,57 @@
+import type { PlayPublisher, PlayTrack } from './play-publisher-port.js';
+/**
+* Changes to a release already on a track, without a new bundle. They follow
+* the staged-rollout steps of https://developers.google.com/android-publisher/tracks:
+* `update` changes an inProgress release's userFraction, `halt` sets it
+* `halted`, `resume` sets a halted release back to `inProgress`, and
+* `complete` sets it `completed` (100%).
+*/
+export type PlayRolloutAction = 'update' | 'halt' | 'resume' | 'complete';
+export declare const playRolloutActions: readonly PlayRolloutAction[];
+export interface PlayRolloutInput {
+  readonly packageName: string;
+  readonly track: string;
+  readonly action: PlayRolloutAction;
+  /** Selects the release; defaults to the track's only release the action applies to. */
+  readonly versionCode?: number;
+  /** Required for `update`; optional for `resume` (else the halted release's own fraction). */
+  readonly userFraction?: number;
+  /** Required for production tracks and for any change that leaves a staged rollout running. */
+  readonly confirmProduction?: boolean;
+  /** Read the track in a throw-away edit and return the planned body without committing. */
+  readonly dryRun?: boolean;
+  readonly signal?: AbortSignal;
+}
+export interface PlayRolloutReleaseState {
+  readonly status: string;
+  readonly userFraction?: number;
+}
+export interface PlayRolloutResult {
+  /** `committed`: Play accepted the edit. `unchanged`: nothing to do. `dry-run`: nothing sent. */
+  readonly status: 'committed' | 'unchanged' | 'dry-run';
+  readonly packageName: string;
+  readonly track: string;
+  readonly action: PlayRolloutAction;
+  readonly versionCodes: readonly string[];
+  readonly before: PlayRolloutReleaseState;
+  readonly after: PlayRolloutReleaseState;
+  readonly editId?: string;
+  /** The `edits.tracks.update` body (dry run only). */
+  readonly plannedTrack?: PlayTrack;
+}
+export declare class PlayRolloutUncertainError extends Error {
+  readonly stage: 'track-update' | 'validate' | 'commit';
+  readonly editId: string;
+  /** The release that was being changed; pass one of them as --version-code on the re-run. */
+  readonly versionCodes: readonly string[];
+  constructor(stage: 'track-update' | 'validate' | 'commit', editId: string, 
+  /** The release that was being changed; pass one of them as --version-code on the re-run. */
+  versionCodes?: readonly string[]);
+}
+/** Change one existing release on one named track with a service account. */
+export declare function changePlayRollout(input: PlayRolloutInput & {
+  readonly serviceAccountFile: string;
+}): Promise<PlayRolloutResult>;
+export declare function assertPlayRolloutInput(input: PlayRolloutInput): void;
+/** Credential-free injection point for the mock-transport tests. */
+export declare function changePlayRolloutWithPublisher(input: PlayRolloutInput, publisher: PlayPublisher): Promise<PlayRolloutResult>;