@mpgd/cli 0.63.0 → 0.65.0

package/dist/store-presence.js

@@ -0,0 +1,173 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { assertStorePresence, assertStorePresenceImage, readStoreImageInfo, } from '@mpgd/catalog';
+import { readJsonFile, StorePlanStaleError } from './store-sync.js';
+/**
+ * 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 const defaultStorePresenceFileName = 'mpgd.store-presence.json';
+export const storePresencePlanCommand = 'mpgd store presence plan';
+/**
+ * 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 function readStorePresenceSource(input) {
+    const file = input.presenceFile === undefined
+        ? path.join(path.resolve(input.gameRoot), defaultStorePresenceFileName)
+        : path.resolve(input.presenceFile);
+    if (!existsSync(file)) {
+        throw new Error(`Store presence sync needs ${file}.`);
+    }
+    return { file, directory: path.dirname(file), presence: assertStorePresence(readJsonFile(file)) };
+}
+/**
+ * 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 function readLocalStoreImage(directory, relative, target, label) {
+    const file = path.resolve(directory, relative);
+    if (!existsSync(file) || !statSync(file).isFile()) {
+        throw new Error(`${label}: ${relative} is missing.`);
+    }
+    const real = path.relative(realpathSync(directory), realpathSync(file));
+    if (real === '..' || real.startsWith(`..${path.sep}`) || path.isAbsolute(real)) {
+        throw new Error(`${label}: ${relative} resolves outside the store presence file's directory.`);
+    }
+    const bytes = readFileSync(file);
+    let info;
+    try {
+        info = readStoreImageInfo(bytes);
+    }
+    catch (error) {
+        throw new Error(`${label}: ${relative} is ${error.message}.`);
+    }
+    const extensionFormat = /\.png$/iu.test(relative) ? 'png' : 'jpeg';
+    if (info.format !== extensionFormat) {
+        throw new Error(`${label}: ${relative} is a ${info.format} file with a .${path.extname(relative).slice(1)} name.`);
+    }
+    assertStorePresenceImage(target, info, bytes.byteLength, `${label}: ${relative}`);
+    return {
+        path: relative,
+        file,
+        sha256: createHash('sha256').update(bytes).digest('hex'),
+        sha1: createHash('sha1').update(bytes).digest('hex'),
+        md5: createHash('md5').update(bytes).digest('hex'),
+        byteLength: bytes.byteLength,
+        info,
+    };
+}
+/** Refuse to upload a graphic whose bytes changed after the plan was checked. */
+export function assertLocalStoreImageUnchanged(file, sha256) {
+    const current = createHash('sha256').update(readFileSync(file)).digest('hex');
+    if (current !== sha256) {
+        throw new StorePlanStaleError(`${file} changed since the plan.`, storePresencePlanCommand);
+    }
+}
+export function imageMimeType(info) {
+    return info.format === 'png' ? 'image/png' : 'image/jpeg';
+}
+const shortText = 80;
+/** CRLF and lone CR as LF, so a file saved on Windows and the store's text compare equal. */
+export function normalizeLineBreaks(value) {
+    return value.replace(/\r\n?/gu, '\n');
+}
+/**
+ * Two URLs that differ only in form (host case, a trailing slash, default
+ * port): a store may normalize the URL it was given.
+ */
+export function sameUrlForm(left, right) {
+    const normal = (value) => {
+        try {
+            return new URL(value).href.replace(/\/$/u, '');
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const a = normal(left);
+    return a !== undefined && a === normal(right);
+}
+/** Compares after normalizing line breaks; `to` is expected normalized already. */
+export function describeTextChange(field, from, to) {
+    const before = typeof from === 'string' ? normalizeLineBreaks(from) : null;
+    if (before === to) {
+        return undefined;
+    }
+    const short = (value) => value === null || [...value].length <= shortText;
+    return {
+        field,
+        fromLength: before === null ? null : [...before].length,
+        toLength: [...to].length,
+        ...(short(before) && short(to) ? { ...(before === null ? {} : { from: before }), to } : {}),
+    };
+}
+export function formatTextChange(change) {
+    const lengths = `${change.fromLength === null ? 'new' : `${change.fromLength} chars`} -> ${change.toLength} chars`;
+    if (change.to === undefined) {
+        return `${change.field}: ${lengths}`;
+    }
+    return `${change.field}: ${JSON.stringify(change.from ?? null)} -> ${JSON.stringify(change.to)}`;
+}
+/**
+ * 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 function planStoreImageSet(input) {
+    const { local, remote, storeName } = input;
+    const remoteDigests = remote.map((image) => image.digest);
+    const desiredDigests = local.map((image) => image.digest);
+    const notes = [];
+    const unchanged = () => ({
+        action: 'unchanged',
+        upload: [],
+        keep: remoteDigests,
+        remove: [],
+        notes,
+    });
+    const replace = () => ({
+        action: 'replace',
+        upload: local,
+        keep: [],
+        remove: remote.filter((image) => !desiredDigests.includes(image.digest)),
+        notes,
+    });
+    const same = remoteDigests.length === desiredDigests.length
+        && remoteDigests.every((digest, index) => digest === desiredDigests[index]);
+    if (same) {
+        return unchanged();
+    }
+    if (input.single) {
+        return remote.length === 0
+            ? { action: 'add', upload: local, keep: [], remove: [], notes }
+            : replace();
+    }
+    const isPrefix = remoteDigests.length < desiredDigests.length
+        && remoteDigests.every((digest, index) => digest === desiredDigests[index]);
+    if (input.complete && !isPrefix) {
+        if (remote.some((image) => desiredDigests.includes(image.digest))) {
+            notes.push(`${storeName}'s images are deleted and the set uploaded again in the file's order.`);
+        }
+        return replace();
+    }
+    const missing = local.filter((image) => !remoteDigests.includes(image.digest));
+    if (missing.length === 0) {
+        notes.push(`${storeName} holds the file's images in another order or with others; mark the set complete to match it.`);
+        return unchanged();
+    }
+    if (remote.length + missing.length > input.maxImages) {
+        throw new Error(`${input.label}: ${storeName} holds ${remote.length} and the file adds ${missing.length}; a set takes at `
+            + `most ${input.maxImages}. Mark the set complete to replace ${storeName}'s images.`);
+    }
+    const kept = remote.length - (local.length - missing.length);
+    if (!input.complete && kept > 0) {
+        notes.push(`${storeName} keeps ${kept} image(s) the file does not list.`);
+    }
+    return { action: 'add', upload: missing, keep: remoteDigests, remove: [], notes };
+}

package/dist/store-products-command.d.ts

@@ -3,12 +3,13 @@ import { type AscCredential } from './app-store-iap-asc.js';
 import type { PlayProductCatalogPort } from './play-product-port.js';
 import { type AppStoreProductApplyResult, type AppStoreProductPlan } from './store-products-app-store.js';
 import { type PlayProductApplyResult, type PlayProductPlan } from './store-products-play.js';
+import { type StoreSyncStore } from './store-sync.js';
 /**
 * `mpgd store products plan|apply`: the game's deployment profile names the
 * app and the store credential (the same ones `deploy submit` uses), the
 * game's catalog and store listing file name the products.
 */
-export type StoreProductStore = 'google-play' | 'app-store';
+export type StoreProductStore = StoreSyncStore;
 export interface StoreProductPlanOptions {
   readonly game: string;
   readonly profile: string;

package/dist/store-products-command.js

@@ -1,11 +1,10 @@
 import { existsSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { openAscIapSession } from './app-store-iap-asc.js';
-import { planNativeDeployment } from './deploy-planning.js';
-import { readStoreCredential } from './native-deploy-run.js';
-import { readStoreProductPlanFile, readStoreProductSources, StoreProductPlanStaleError, writeStoreProductPlan, } from './store-products.js';
+import { readStoreProductSources, StoreProductPlanStaleError, } from './store-products.js';
 import { applyAppStoreProductPlan, planAppStoreProducts, } from './store-products-app-store.js';
 import { applyPlayProductPlan, planPlayProducts, } from './store-products-play.js';
+import { assertStoreSyncStore, readStorePlanFile, relocateStoreSyncFile, resolveStoreSyncApp, writeStorePlanFile, } from './store-sync.js';
 const defaultPorts = {
     googlePlay: loadPlayProductCatalog,
     appStore: openAscIapSession,
@@ -22,7 +21,7 @@ export async function planStoreProducts(options, environment = process.env, port
     }));
 }
 export function saveStoreProductPlan(file, plan) {
-    return writeStoreProductPlan(file, plan);
+    return writeStorePlanFile(file, plan);
 }
 export async function applyStoreProducts(options, environment = process.env, ports = {}) {
     if (!options.approved) {
@@ -30,16 +29,7 @@ export async function applyStoreProducts(options, environment = process.env, por
     }
     const saved = readSavedPlan(options.planFile);
     const gameRoot = options.game === undefined ? saved.gameRoot : path.resolve(options.game);
-    const relocate = (file) => {
-        if (options.game === undefined) {
-            return file;
-        }
-        const relative = path.relative(saved.gameRoot, file);
-        if (relative.startsWith('..') || path.isAbsolute(relative)) {
-            throw new Error(`The saved plan reads ${file}, outside its game directory; --game cannot move it. Plan again.`);
-        }
-        return path.resolve(gameRoot, relative);
-    };
+    const relocate = (file) => relocateStoreSyncFile(saved.gameRoot, options.game === undefined ? undefined : gameRoot, file);
     const planOptions = {
         game: gameRoot,
         profile: saved.profile,
@@ -82,42 +72,25 @@ export async function applyStoreProducts(options, environment = process.env, por
     });
 }
 async function withStoreSession(options, environment, overrides, action) {
-    if (options.store !== 'google-play' && options.store !== 'app-store') {
-        throw new Error('--store must be google-play or app-store.');
-    }
+    assertStoreSyncStore(options.store);
     const ports = { ...defaultPorts, ...overrides };
-    const gameRoot = path.resolve(options.game);
-    const target = options.store === 'google-play' ? 'android' : 'ios';
-    const deployment = planNativeDeployment({
-        game: gameRoot,
-        profile: options.profile,
-        targets: [target],
-    });
-    const planned = deployment.targets.find((entry) => entry.target === target);
-    if (planned === undefined) {
-        throw new Error(`Deployment profile ${options.profile} has no ${target} target.`);
-    }
+    // The game files first: a malformed file reports its own error without a credential.
     const sources = readStoreProductSources({
-        gameRoot,
+        gameRoot: path.resolve(options.game),
         ...(options.catalogFile === undefined ? {} : { catalogFile: options.catalogFile }),
         ...(options.listingsFile === undefined ? {} : { listingsFile: options.listingsFile }),
     });
-    const credential = readStoreCredential(deployment, target, environment);
-    if (credential.target === 'android') {
-        const port = await ports.googlePlay(credential.serviceAccountFile);
-        return action({ store: 'google-play', packageName: planned.appId, port, sources });
+    const app = resolveStoreSyncApp(options, environment);
+    if (app.store === 'google-play') {
+        const port = await ports.googlePlay(app.serviceAccountFile);
+        return action({ store: 'google-play', packageName: app.packageName, port, sources });
     }
-    const session = await ports.appStore({
-        ascBinary: credential.ascBinary,
-        apiKeyId: credential.apiKeyId,
-        apiIssuerId: credential.apiIssuerId,
-        apiPrivateKeyBase64: credential.apiPrivateKeyBase64,
-    }, options.signal);
+    const session = await ports.appStore(app.credential, options.signal);
     try {
         return await action({
             store: 'app-store',
-            appId: credential.appStoreAppId,
-            bundleId: planned.appId,
+            appId: app.appId,
+            bundleId: app.bundleId,
             port: session.port,
             sources,
         });
@@ -148,7 +121,7 @@ async function planWithSession(session, options) {
     }, session.port);
 }
 function readSavedPlan(file) {
-    const raw = readStoreProductPlanFile(file);
+    const raw = readStorePlanFile(file, 'store product plan');
     const plan = raw.plan;
     const storeFields = typeof plan === 'object' && plan !== null && ((plan.store === 'google-play' && typeof plan.packageName === 'string')
         || (plan.store === 'app-store' && typeof plan.appId === 'string' && typeof plan.bundleId === 'string'));

package/dist/store-products.d.ts

@@ -1,4 +1,6 @@
 import { type ProductCatalog, type StoreListingCatalog } from '@mpgd/catalog';
+import { StorePlanStaleError } from './store-sync.js';
+export { canonicalLanguageTag, mapWithConcurrency, stableJson, stableSha256, } from './store-sync.js';
 /**
 * Shared pieces of `mpgd store products plan|apply`: the game files the sync
 * reads, the saved plan file, and the stable digests apply uses to refuse a
@@ -24,13 +26,7 @@ export declare function readStoreProductSources(input: {
   readonly catalogFile?: string;
   readonly listingsFile?: string;
 }): StoreProductSources;
-/** JSON with object keys sorted, so equal values always hash the same. */
-export declare function stableJson(value: unknown): string;
-export declare function stableSha256(value: unknown): string;
-/** A new plan file, never overwriting one (the same rule as `deploy plan --out`). */
-export declare function writeStoreProductPlan(file: string, plan: unknown): string;
-export declare function readStoreProductPlanFile(file: string): Record<string, unknown>;
-export declare class StoreProductPlanStaleError extends Error {
+export declare class StoreProductPlanStaleError extends StorePlanStaleError {
   constructor(detail: string);
 }
 /** Decimal string (`"0.99"`) as whole units and nanos, without floating point. */
@@ -40,7 +36,3 @@ export declare function decimalToUnitsAndNanos(amount: string): {
 };
 /** Decimal strings compared by value: `0.99` equals `0.990`. */
 export declare function sameDecimal(left: string, right: string): boolean;
-/** BCP-47 casing: language lowercase, script title case, region uppercase. */
-export declare function canonicalLanguageTag(tag: string): string;
-/** `map` with at most `limit` calls in flight; results keep input order. */
-export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, map: (item: T) => Promise<R>): Promise<R[]>;

package/dist/store-products.js

@@ -1,7 +1,8 @@
-import { createHash } from 'node:crypto';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { assertProductCatalog, assertStoreListingCatalog, } from '@mpgd/catalog';
+import { readJsonFile, StorePlanStaleError } from './store-sync.js';
+export { canonicalLanguageTag, mapWithConcurrency, stableJson, stableSha256, } from './store-sync.js';
 export const defaultStoreListingFileName = 'mpgd.store-listings.json';
 export const defaultProductCatalogFileName = 'mpgd.catalog.json';
 /**
@@ -22,33 +23,13 @@ export function readStoreProductSources(input) {
             throw new Error(`Store product sync needs ${file}.`);
         }
     }
-    const catalog = assertProductCatalog(readJson(catalogFile));
-    const listings = assertStoreListingCatalog(readJson(listingsFile), catalog);
+    const catalog = assertProductCatalog(readJsonFile(catalogFile));
+    const listings = assertStoreListingCatalog(readJsonFile(listingsFile), catalog);
     return { catalogFile, listingsFile, catalog, listings };
 }
-/** JSON with object keys sorted, so equal values always hash the same. */
-export function stableJson(value) {
-    return JSON.stringify(sortKeys(value));
-}
-export function stableSha256(value) {
-    return createHash('sha256').update(stableJson(value)).digest('hex');
-}
-/** A new plan file, never overwriting one (the same rule as `deploy plan --out`). */
-export function writeStoreProductPlan(file, plan) {
-    const resolved = path.resolve(file);
-    writeFileSync(resolved, `${JSON.stringify(plan, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
-    return resolved;
-}
-export function readStoreProductPlanFile(file) {
-    const raw = readJson(path.resolve(file));
-    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
-        throw new Error('Saved store product plan is malformed.');
-    }
-    return raw;
-}
-export class StoreProductPlanStaleError extends Error {
+export class StoreProductPlanStaleError extends StorePlanStaleError {
     constructor(detail) {
-        super(`${detail} Run "mpgd store products plan" again and review the new plan.`);
+        super(detail, 'mpgd store products plan');
         this.name = 'StoreProductPlanStaleError';
     }
 }
@@ -73,52 +54,3 @@ export function sameDecimal(left, right) {
     };
     return normal(left) === normal(right);
 }
-/** BCP-47 casing: language lowercase, script title case, region uppercase. */
-export function canonicalLanguageTag(tag) {
-    return tag.split('-').map((part, index) => {
-        if (index === 0) {
-            return part.toLowerCase();
-        }
-        if (/^[A-Za-z]{4}$/u.test(part)) {
-            return `${part.slice(0, 1).toUpperCase()}${part.slice(1).toLowerCase()}`;
-        }
-        if (/^[A-Za-z]{2}$/u.test(part)) {
-            return part.toUpperCase();
-        }
-        return part.toLowerCase();
-    }).join('-');
-}
-/** `map` with at most `limit` calls in flight; results keep input order. */
-export async function mapWithConcurrency(items, limit, map) {
-    const results = new Array(items.length);
-    let next = 0;
-    const worker = async () => {
-        while (next < items.length) {
-            const index = next;
-            next += 1;
-            results[index] = await map(items[index]);
-        }
-    };
-    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
-    return results;
-}
-function readJson(file) {
-    try {
-        return JSON.parse(readFileSync(file, 'utf8'));
-    }
-    catch (error) {
-        throw new Error(`${file} is not valid JSON: ${error.message}`);
-    }
-}
-function sortKeys(value) {
-    if (Array.isArray(value)) {
-        return value.map(sortKeys);
-    }
-    if (typeof value === 'object' && value !== null) {
-        return Object.fromEntries(Object.keys(value)
-            .sort()
-            .filter((key) => value[key] !== undefined)
-            .map((key) => [key, sortKeys(value[key])]));
-    }
-    return value;
-}

package/dist/store-sync.d.ts

@@ -0,0 +1,50 @@
+import type { AscCredential } from './app-store-iap-asc.js';
+/**
+* What every `mpgd store <kind> plan|apply` shares: the app and credential
+* the deployment profile names, the saved plan file, the stable digests
+* apply compares, and moving a reviewed plan to another checkout.
+*/
+export type StoreSyncStore = 'google-play' | 'app-store';
+/** The store app the deployment profile names, with its credential. */
+export type StoreSyncApp = {
+  readonly store: 'google-play';
+  readonly packageName: string;
+  readonly serviceAccountFile: string;
+} | {
+  readonly store: 'app-store';
+  /** Numeric App Store Connect app ID. */
+  readonly appId: string;
+  readonly bundleId: string;
+  readonly credential: AscCredential;
+};
+/**
+* Resolve the app and credential of `store` from the game's deployment
+* profile, the same ones `deploy submit` uses.
+*/
+export declare function resolveStoreSyncApp(options: {
+  readonly game: string;
+  readonly profile: string;
+  readonly store: StoreSyncStore;
+}, environment: NodeJS.ProcessEnv): StoreSyncApp;
+export declare function assertStoreSyncStore(store: string): asserts store is StoreSyncStore;
+/**
+* A file a saved plan read, moved to the game directory apply runs in
+* (`apply --game`). Files outside the saved game directory cannot move.
+*/
+export declare function relocateStoreSyncFile(savedGameRoot: string, gameRoot: string | undefined, file: string): string;
+/** JSON with object keys sorted, so equal values always hash the same. */
+export declare function stableJson(value: unknown): string;
+export declare function stableSha256(value: unknown): string;
+/** A new plan file, never overwriting one (the same rule as `deploy plan --out`). */
+export declare function writeStorePlanFile(file: string, plan: unknown): string;
+/** A saved plan's top-level object; the caller checks its fields. */
+export declare function readStorePlanFile(file: string, label: string): Record<string, unknown>;
+/** The store or the game files moved past the reviewed plan. */
+export declare class StorePlanStaleError extends Error {
+  constructor(detail: string, planCommand: string);
+}
+/** BCP-47 casing: language lowercase, script title case, region uppercase. */
+export declare function canonicalLanguageTag(tag: string): string;
+/** `map` with at most `limit` calls in flight; results keep input order. */
+export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, map: (item: T) => Promise<R>): Promise<R[]>;
+export declare function readJsonFile(file: string): unknown;

package/dist/store-sync.js

@@ -0,0 +1,137 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { planNativeDeployment } from './deploy-planning.js';
+import { readStoreCredential } from './native-deploy-run.js';
+/**
+ * Resolve the app and credential of `store` from the game's deployment
+ * profile, the same ones `deploy submit` uses.
+ */
+export function resolveStoreSyncApp(options, environment) {
+    assertStoreSyncStore(options.store);
+    const target = options.store === 'google-play' ? 'android' : 'ios';
+    const deployment = planNativeDeployment({
+        game: path.resolve(options.game),
+        profile: options.profile,
+        targets: [target],
+    });
+    const planned = deployment.targets.find((entry) => entry.target === target);
+    if (planned === undefined) {
+        throw new Error(`Deployment profile ${options.profile} has no ${target} target.`);
+    }
+    const credential = readStoreCredential(deployment, target, environment);
+    if (credential.target === 'android') {
+        return {
+            store: 'google-play',
+            packageName: planned.appId,
+            serviceAccountFile: credential.serviceAccountFile,
+        };
+    }
+    return {
+        store: 'app-store',
+        appId: credential.appStoreAppId,
+        bundleId: planned.appId,
+        credential: {
+            ascBinary: credential.ascBinary,
+            apiKeyId: credential.apiKeyId,
+            apiIssuerId: credential.apiIssuerId,
+            apiPrivateKeyBase64: credential.apiPrivateKeyBase64,
+        },
+    };
+}
+export function assertStoreSyncStore(store) {
+    if (store !== 'google-play' && store !== 'app-store') {
+        throw new Error('--store must be google-play or app-store.');
+    }
+}
+/**
+ * A file a saved plan read, moved to the game directory apply runs in
+ * (`apply --game`). Files outside the saved game directory cannot move.
+ */
+export function relocateStoreSyncFile(savedGameRoot, gameRoot, file) {
+    if (gameRoot === undefined) {
+        return file;
+    }
+    const relative = path.relative(savedGameRoot, file);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error(`The saved plan reads ${file}, outside its game directory; --game cannot move it. Plan again.`);
+    }
+    return path.resolve(gameRoot, relative);
+}
+/** JSON with object keys sorted, so equal values always hash the same. */
+export function stableJson(value) {
+    return JSON.stringify(sortKeys(value));
+}
+export function stableSha256(value) {
+    return createHash('sha256').update(stableJson(value)).digest('hex');
+}
+/** A new plan file, never overwriting one (the same rule as `deploy plan --out`). */
+export function writeStorePlanFile(file, plan) {
+    const resolved = path.resolve(file);
+    writeFileSync(resolved, `${JSON.stringify(plan, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+    return resolved;
+}
+/** A saved plan's top-level object; the caller checks its fields. */
+export function readStorePlanFile(file, label) {
+    const raw = readJsonFile(path.resolve(file));
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error(`Saved ${label} is malformed.`);
+    }
+    return raw;
+}
+/** The store or the game files moved past the reviewed plan. */
+export class StorePlanStaleError extends Error {
+    constructor(detail, planCommand) {
+        super(`${detail} Run "${planCommand}" again and review the new plan.`);
+        this.name = 'StorePlanStaleError';
+    }
+}
+/** BCP-47 casing: language lowercase, script title case, region uppercase. */
+export function canonicalLanguageTag(tag) {
+    return tag.split('-').map((part, index) => {
+        if (index === 0) {
+            return part.toLowerCase();
+        }
+        if (/^[A-Za-z]{4}$/u.test(part)) {
+            return `${part.slice(0, 1).toUpperCase()}${part.slice(1).toLowerCase()}`;
+        }
+        if (/^[A-Za-z]{2}$/u.test(part)) {
+            return part.toUpperCase();
+        }
+        return part.toLowerCase();
+    }).join('-');
+}
+/** `map` with at most `limit` calls in flight; results keep input order. */
+export async function mapWithConcurrency(items, limit, map) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const index = next;
+            next += 1;
+            results[index] = await map(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return results;
+}
+export function readJsonFile(file) {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`${file} is not valid JSON: ${error.message}`);
+    }
+}
+function sortKeys(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortKeys);
+    }
+    if (typeof value === 'object' && value !== null) {
+        return Object.fromEntries(Object.keys(value)
+            .sort()
+            .filter((key) => value[key] !== undefined)
+            .map((key) => [key, sortKeys(value[key])]));
+    }
+    return value;
+}