storemeta 0.1.0

package/dist/platforms/google/screenshots/pull.js

@@ -0,0 +1,129 @@
+import { writeFile } from "node:fs/promises";
+import { StoremetaError } from "../../../cli/errors.js";
+import { listScreenshotGroups } from "../../../locales/groups.js";
+import { normalizeLocaleCode } from "../../../locales/normalize.js";
+import { ensureParentDirectory } from "../../../writers/ensure-directory.js";
+import { resolveScreenshotFilePath } from "../../../writers/resolve-screenshot-path.js";
+export async function listGoogleImagesForLocaleAndType(client, packageName, editId, locale, imageType) {
+    const response = await client.requestJson(`/applications/${encodeURIComponent(packageName)}/edits/${encodeURIComponent(editId)}/listings/${encodeURIComponent(locale)}/${encodeURIComponent(imageType)}`);
+    return {
+        locale: normalizeLocaleCode(locale),
+        imageType,
+        images: response.images ?? [],
+    };
+}
+export async function listGoogleImagesForLocalesAndTypes(client, packageName, editId, locales, imageTypes) {
+    return Promise.all(locales.flatMap((locale) => imageTypes.map((imageType) => listGoogleImagesForLocaleAndType(client, packageName, editId, locale, imageType))));
+}
+export function expandGoogleScreenshotPullLocales(locales, settings) {
+    const resolvedLocales = [];
+    const seenLocales = new Set();
+    for (const locale of locales.map(normalizeLocaleCode)) {
+        if (seenLocales.has(locale)) {
+            continue;
+        }
+        resolvedLocales.push(locale);
+        seenLocales.add(locale);
+    }
+    for (const group of listScreenshotGroups(settings)) {
+        const groupMatches = group.locales.some((locale) => seenLocales.has(locale));
+        if (!groupMatches) {
+            continue;
+        }
+        for (const locale of group.locales) {
+            if (seenLocales.has(locale)) {
+                continue;
+            }
+            resolvedLocales.push(locale);
+            seenLocales.add(locale);
+        }
+    }
+    return resolvedLocales;
+}
+function normalizeGoogleImageExtension(extension) {
+    return extension.replace(/^\./u, "").toLowerCase();
+}
+function inferGoogleImageExtension(imageUrl, contentType) {
+    if (contentType !== null) {
+        if (contentType.includes("png")) {
+            return "png";
+        }
+        if (contentType.includes("jpeg") || contentType.includes("jpg")) {
+            return "jpg";
+        }
+        if (contentType.includes("webp")) {
+            return "webp";
+        }
+    }
+    try {
+        const parsedUrl = new URL(imageUrl);
+        const match = parsedUrl.pathname.match(/\.([A-Za-z0-9]+)$/u);
+        if (match?.[1] !== undefined) {
+            return normalizeGoogleImageExtension(match[1]);
+        }
+    }
+    catch {
+        // Fall back to png when the remote URL is not parseable.
+    }
+    return "png";
+}
+function createGoogleDownloadedFileName(position, extension) {
+    return `${position}.${normalizeGoogleImageExtension(extension)}`;
+}
+export async function downloadGoogleImage(image) {
+    if (image.url === undefined || image.url.trim().length === 0) {
+        throw new StoremetaError("API_ERROR", "Google Play returned an image without a download URL");
+    }
+    const response = await fetch(image.url);
+    if (!response.ok) {
+        throw new StoremetaError("API_ERROR", `Failed to download a Google Play screenshot with ${response.status} ${response.statusText}`);
+    }
+    return {
+        buffer: new Uint8Array(await response.arrayBuffer()),
+        extension: inferGoogleImageExtension(image.url, response.headers.get("content-type")),
+    };
+}
+export async function downloadGoogleScreenshotSet(screenshotsBaseDir, screenshotSet) {
+    const normalizedLocale = normalizeLocaleCode(screenshotSet.locale);
+    if (screenshotSet.images.length === 0) {
+        return {
+            platform: "google",
+            locale: normalizedLocale,
+            assetType: screenshotSet.imageType,
+            files: [],
+        };
+    }
+    const files = [];
+    for (const [index, image] of screenshotSet.images.entries()) {
+        const position = index + 1;
+        const downloadedImage = await downloadGoogleImage(image);
+        const fileName = createGoogleDownloadedFileName(position, downloadedImage.extension);
+        const filePath = resolveScreenshotFilePath(screenshotsBaseDir, {
+            platform: "google",
+            locale: screenshotSet.locale,
+            assetType: screenshotSet.imageType,
+            fileName,
+        });
+        await ensureParentDirectory(filePath);
+        try {
+            await writeFile(filePath, downloadedImage.buffer);
+        }
+        catch (cause) {
+            throw new StoremetaError("FILESYSTEM_ERROR", `Failed to write Google Play screenshot ${screenshotSet.locale}/${screenshotSet.imageType}/${fileName}`, { cause });
+        }
+        files.push({
+            platform: "google",
+            locale: normalizedLocale,
+            assetType: screenshotSet.imageType,
+            filePath,
+            fileName,
+            position,
+        });
+    }
+    return {
+        platform: "google",
+        locale: normalizedLocale,
+        assetType: screenshotSet.imageType,
+        files,
+    };
+}

package/dist/platforms/google/screenshots/push.js

@@ -0,0 +1,252 @@
+import { readFile, readdir } from "node:fs/promises";
+import { extname, join, resolve } from "node:path";
+import { StoremetaError } from "../../../cli/errors.js";
+import { listScreenshotGroups } from "../../../locales/groups.js";
+import { mapLocaleCode, mapLocaleCodes } from "../../../locales/map.js";
+import { normalizeLocaleCode } from "../../../locales/normalize.js";
+import { GOOGLE_SCREENSHOT_IMAGE_TYPES, } from "./types.js";
+const SUPPORTED_SCREENSHOT_EXTENSIONS = new Set([".png", ".jpg", ".jpeg"]);
+const GOOGLE_SCREENSHOT_IMAGE_TYPE_SET = new Set(GOOGLE_SCREENSHOT_IMAGE_TYPES);
+async function listDirectoryEntries(directoryPath) {
+    try {
+        return await readdir(directoryPath, { withFileTypes: true });
+    }
+    catch (cause) {
+        if (typeof cause === "object" &&
+            cause !== null &&
+            "code" in cause &&
+            cause.code === "ENOENT") {
+            return [];
+        }
+        throw new StoremetaError("FILESYSTEM_ERROR", `Failed to read Google screenshot directory at ${directoryPath}`, { cause });
+    }
+}
+function validateGoogleScreenshotAssetType(assetType, directoryPath) {
+    if (GOOGLE_SCREENSHOT_IMAGE_TYPE_SET.has(assetType)) {
+        return assetType;
+    }
+    throw new StoremetaError("VALIDATION_ERROR", `${directoryPath}: unsupported Google screenshot image type`);
+}
+function sortScreenshotFileNames(fileNames) {
+    return [...fileNames].sort((left, right) => left.localeCompare(right, undefined, {
+        numeric: true,
+    }));
+}
+function validateGoogleScreenshotFileNames(assetTypeDirectory, fileNames) {
+    for (const [index, fileName] of sortScreenshotFileNames(fileNames).entries()) {
+        const extension = extname(fileName).toLowerCase();
+        if (!SUPPORTED_SCREENSHOT_EXTENSIONS.has(extension)) {
+            throw new StoremetaError("VALIDATION_ERROR", `${join(assetTypeDirectory, fileName)}: unsupported screenshot file extension`);
+        }
+        const numericName = fileName.slice(0, Math.max(0, fileName.length - extension.length));
+        if (!/^\d+$/u.test(numericName)) {
+            throw new StoremetaError("VALIDATION_ERROR", `${join(assetTypeDirectory, fileName)}: expected a numeric filename`);
+        }
+        if (Number(numericName) !== index + 1) {
+            throw new StoremetaError("VALIDATION_ERROR", `${join(assetTypeDirectory, fileName)}: expected screenshot order ${index + 1}`);
+        }
+    }
+}
+function createGoogleScreenshotDescriptors(screenshotsBaseDir, localeDirectoryName, locale, imageType, fileNames) {
+    return sortScreenshotFileNames(fileNames).map((fileName, index) => ({
+        platform: "google",
+        locale,
+        assetType: imageType,
+        filePath: resolve(screenshotsBaseDir, "google", localeDirectoryName, imageType, fileName),
+        fileName,
+        position: index + 1,
+    }));
+}
+function resolveGoogleScreenshotGroupLocales(sourceLocale, localeSettings, screenshotSettings) {
+    const mappedSourceLocale = mapLocaleCode(sourceLocale, localeSettings);
+    const matchingGroups = listScreenshotGroups(screenshotSettings).filter((group) => {
+        const mappedGroupLocales = mapLocaleCodes(group.locales, localeSettings);
+        return (group.locales.includes(sourceLocale) ||
+            group.locales.includes(mappedSourceLocale) ||
+            mappedGroupLocales.includes(mappedSourceLocale));
+    });
+    if (matchingGroups.length > 1) {
+        throw new StoremetaError("VALIDATION_ERROR", `Google screenshot locale ${sourceLocale} matches multiple screenshot groups`);
+    }
+    if (matchingGroups.length === 0) {
+        return [mappedSourceLocale];
+    }
+    const mappedGroupLocales = mapLocaleCodes(matchingGroups[0].locales, localeSettings);
+    const uniqueLocales = new Set(mappedGroupLocales);
+    if (uniqueLocales.size !== mappedGroupLocales.length) {
+        throw new StoremetaError("VALIDATION_ERROR", `Google screenshot group ${matchingGroups[0].name} resolves to duplicate target locales`);
+    }
+    return mappedGroupLocales;
+}
+export async function loadGoogleScreenshotSets(screenshotsBaseDir) {
+    const googleBaseDir = resolve(screenshotsBaseDir, "google");
+    const localeEntries = await listDirectoryEntries(googleBaseDir);
+    const screenshotSets = [];
+    for (const localeEntry of localeEntries) {
+        if (!localeEntry.isDirectory()) {
+            throw new StoremetaError("VALIDATION_ERROR", `${join(googleBaseDir, localeEntry.name)}: expected a locale directory`);
+        }
+        const locale = normalizeLocaleCode(localeEntry.name);
+        const localeDirectory = join(googleBaseDir, localeEntry.name);
+        const imageTypeEntries = await listDirectoryEntries(localeDirectory);
+        for (const imageTypeEntry of imageTypeEntries) {
+            if (!imageTypeEntry.isDirectory()) {
+                throw new StoremetaError("VALIDATION_ERROR", `${join(localeDirectory, imageTypeEntry.name)}: expected an image type directory`);
+            }
+            const imageTypeDirectory = join(localeDirectory, imageTypeEntry.name);
+            const imageType = validateGoogleScreenshotAssetType(imageTypeEntry.name, imageTypeDirectory);
+            const fileEntries = await listDirectoryEntries(imageTypeDirectory);
+            const fileNames = fileEntries
+                .filter((entry) => entry.isFile())
+                .map((entry) => entry.name);
+            validateGoogleScreenshotFileNames(imageTypeDirectory, fileNames);
+            screenshotSets.push({
+                platform: "google",
+                locale,
+                assetType: imageType,
+                files: createGoogleScreenshotDescriptors(screenshotsBaseDir, localeEntry.name, locale, imageType, fileNames),
+            });
+        }
+    }
+    return screenshotSets.sort((left, right) => {
+        const localeOrder = left.locale.localeCompare(right.locale);
+        if (localeOrder !== 0) {
+            return localeOrder;
+        }
+        return left.assetType.localeCompare(right.assetType);
+    });
+}
+export function mapGoogleScreenshotSetsToTargets(screenshotSets, settings) {
+    const uploadTargets = [];
+    const seenTargets = new Map();
+    for (const screenshotSet of screenshotSets) {
+        const imageType = validateGoogleScreenshotAssetType(screenshotSet.assetType, screenshotSet.assetType);
+        const sourceLocale = normalizeLocaleCode(screenshotSet.locale);
+        const targetLocales = resolveGoogleScreenshotGroupLocales(sourceLocale, settings.locales, settings.screenshots);
+        for (const targetLocale of targetLocales) {
+            const targetKey = `${targetLocale}:${imageType}`;
+            const existingSourceLocale = seenTargets.get(targetKey);
+            if (existingSourceLocale !== undefined && existingSourceLocale !== sourceLocale) {
+                throw new StoremetaError("VALIDATION_ERROR", `Google screenshot target ${targetLocale}/${imageType} is defined by both ${existingSourceLocale} and ${sourceLocale}`);
+            }
+            seenTargets.set(targetKey, sourceLocale);
+            uploadTargets.push({
+                platform: "google",
+                locale: targetLocale,
+                targetLocale,
+                sourceLocale,
+                assetType: imageType,
+                imageType,
+                files: screenshotSet.files.map((file) => ({
+                    ...file,
+                    locale: targetLocale,
+                    assetType: imageType,
+                })),
+            });
+        }
+    }
+    return uploadTargets.sort((left, right) => {
+        const localeOrder = left.targetLocale.localeCompare(right.targetLocale);
+        if (localeOrder !== 0) {
+            return localeOrder;
+        }
+        const imageTypeOrder = left.imageType.localeCompare(right.imageType);
+        if (imageTypeOrder !== 0) {
+            return imageTypeOrder;
+        }
+        return left.sourceLocale.localeCompare(right.sourceLocale);
+    });
+}
+function getGoogleScreenshotContentType(filePath) {
+    const extension = extname(filePath).toLowerCase();
+    if (extension === ".png") {
+        return "image/png";
+    }
+    if (extension === ".jpg" || extension === ".jpeg") {
+        return "image/jpeg";
+    }
+    throw new StoremetaError("VALIDATION_ERROR", `${filePath}: unsupported screenshot file extension`);
+}
+export async function clearGoogleScreenshotTargets(client, packageName, editId, uploadTargets, options) {
+    if (options?.clearExisting !== true) {
+        return [];
+    }
+    const clearResults = [];
+    const clearedTargets = new Set();
+    for (const uploadTarget of uploadTargets) {
+        const targetKey = `${uploadTarget.targetLocale}:${uploadTarget.imageType}`;
+        if (clearedTargets.has(targetKey)) {
+            continue;
+        }
+        const response = await client.requestJson(`/applications/${encodeURIComponent(packageName)}/edits/${encodeURIComponent(editId)}/listings/${encodeURIComponent(uploadTarget.targetLocale)}/${encodeURIComponent(uploadTarget.imageType)}`, {
+            method: "DELETE",
+        });
+        clearResults.push({
+            targetLocale: uploadTarget.targetLocale,
+            imageType: uploadTarget.imageType,
+            deleted: response.deleted ?? [],
+        });
+        clearedTargets.add(targetKey);
+    }
+    return clearResults.sort((left, right) => {
+        const localeOrder = left.targetLocale.localeCompare(right.targetLocale);
+        if (localeOrder !== 0) {
+            return localeOrder;
+        }
+        return left.imageType.localeCompare(right.imageType);
+    });
+}
+export async function uploadGoogleScreenshotTarget(client, packageName, editId, uploadTarget) {
+    const uploadResults = [];
+    for (const file of uploadTarget.files) {
+        const contentType = getGoogleScreenshotContentType(file.filePath);
+        const fileContents = await readFile(file.filePath);
+        const response = await client.requestJson(`https://androidpublisher.googleapis.com/upload/androidpublisher/v3/applications/${encodeURIComponent(packageName)}/edits/${encodeURIComponent(editId)}/listings/${encodeURIComponent(uploadTarget.targetLocale)}/${encodeURIComponent(uploadTarget.imageType)}?uploadType=media`, {
+            method: "POST",
+            headers: {
+                "Content-Type": contentType,
+            },
+            body: fileContents,
+        });
+        if (response.image === undefined) {
+            throw new StoremetaError("API_ERROR", `Google Play upload did not return image data for ${uploadTarget.targetLocale}/${uploadTarget.imageType}/${file.fileName}`);
+        }
+        uploadResults.push({
+            targetLocale: uploadTarget.targetLocale,
+            imageType: uploadTarget.imageType,
+            position: file.position,
+            filePath: file.filePath,
+            image: response.image,
+        });
+    }
+    return uploadResults;
+}
+export async function uploadGoogleScreenshotTargets(client, packageName, editId, uploadTargets, options) {
+    const uploadResults = [];
+    for (const uploadTarget of uploadTargets) {
+        if (options?.onTargetStarted !== undefined) {
+            await options.onTargetStarted(uploadTarget);
+        }
+        const targetResults = await uploadGoogleScreenshotTarget(client, packageName, editId, uploadTarget);
+        for (const result of targetResults) {
+            uploadResults.push(result);
+            if (options?.onUploaded !== undefined) {
+                await options.onUploaded(result);
+            }
+        }
+        if (options?.onTargetCompleted !== undefined) {
+            await options.onTargetCompleted(uploadTarget, targetResults);
+        }
+    }
+    return uploadResults.sort((left, right) => {
+        const localeOrder = left.targetLocale.localeCompare(right.targetLocale);
+        if (localeOrder !== 0) {
+            return localeOrder;
+        }
+        const imageTypeOrder = left.imageType.localeCompare(right.imageType);
+        if (imageTypeOrder !== 0) {
+            return imageTypeOrder;
+        }
+        return left.position - right.position;
+    });
+}

package/dist/platforms/google/screenshots/types.js

@@ -0,0 +1,7 @@
+export const GOOGLE_SCREENSHOT_IMAGE_TYPES = [
+    "phoneScreenshots",
+    "sevenInchScreenshots",
+    "tenInchScreenshots",
+    "tvScreenshots",
+    "wearScreenshots",
+];

package/dist/validation/metadata/apple.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { StoremetaError } from "../../cli/errors.js";
+export const appleMetadataDocumentSchema = z
+    .object({
+    locale: z.string().min(1),
+    app_name: z.string().min(1).optional(),
+    subtitle: z.string().min(1).optional(),
+    keywords: z.string().min(1).optional(),
+    promotional_text: z.string().min(1).optional(),
+    description: z.string().min(1).optional(),
+    whats_new: z.string().min(1).optional(),
+    support_url: z.string().url().optional(),
+    marketing_url: z.string().url().optional(),
+    privacy_policy_url: z.string().url().optional(),
+})
+    .strict();
+function formatAppleMetadataIssues(error) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join(".") : "root";
+        return `${path}: ${issue.message}`;
+    })
+        .join("; ");
+}
+export function validateAppleMetadataDocument(document) {
+    const result = appleMetadataDocumentSchema.safeParse(document);
+    if (!result.success) {
+        throw new StoremetaError("VALIDATION_ERROR", `Apple metadata validation failed: ${formatAppleMetadataIssues(result.error)}`, { cause: result.error });
+    }
+    return result.data;
+}

package/dist/validation/metadata/files.js

@@ -0,0 +1,58 @@
+import { readdir } from "node:fs/promises";
+import { dirname, extname, join, resolve } from "node:path";
+import { StoremetaError } from "../../cli/errors.js";
+import { loadMarkdownMetadataFile, loadYamlMetadataFile, loadYmlMetadataFile, } from "../../formats/load-metadata.js";
+import { validateAppleMetadataDocument } from "./apple.js";
+import { validateGoogleMetadataDocument, validateGoogleMetadataLengthConstraints, } from "./google.js";
+async function listMetadataFiles(platformDir) {
+    let entries;
+    try {
+        entries = await readdir(platformDir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return [];
+        }
+        throw new StoremetaError("FILESYSTEM_ERROR", `Failed to read metadata directory at ${platformDir}`, { cause: error });
+    }
+    return entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => join(platformDir, entry.name))
+        .sort((left, right) => left.localeCompare(right));
+}
+async function loadMetadataDocument(filePath) {
+    const extension = extname(filePath).toLowerCase();
+    if (extension === ".yml") {
+        return (await loadYmlMetadataFile(filePath)).parsed;
+    }
+    if (extension === ".yaml") {
+        return (await loadYamlMetadataFile(filePath)).parsed;
+    }
+    if (extension === ".md") {
+        return (await loadMarkdownMetadataFile(filePath)).parsed;
+    }
+    return undefined;
+}
+export async function validateMetadataFiles(configPath, app, platforms) {
+    const projectRoot = dirname(resolve(configPath));
+    for (const platform of platforms) {
+        const platformDir = resolve(projectRoot, app.settings.metadata.baseDir, platform);
+        const files = await listMetadataFiles(platformDir);
+        for (const filePath of files) {
+            const parsedDocument = await loadMetadataDocument(filePath);
+            if (parsedDocument === undefined) {
+                continue;
+            }
+            if (platform === "apple") {
+                validateAppleMetadataDocument(parsedDocument);
+            }
+            if (platform === "google") {
+                const googleDocument = validateGoogleMetadataDocument(parsedDocument);
+                validateGoogleMetadataLengthConstraints(googleDocument);
+            }
+        }
+    }
+}

package/dist/validation/metadata/google.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { StoremetaError } from "../../cli/errors.js";
+export const googleMetadataDocumentSchema = z
+    .object({
+    locale: z.string().min(1),
+    title: z.string().min(1).optional(),
+    short_description: z.string().min(1).optional(),
+    full_description: z.string().min(1).optional(),
+    video: z.string().url().optional(),
+})
+    .strict();
+function formatGoogleMetadataIssues(error) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join(".") : "root";
+        return `${path}: ${issue.message}`;
+    })
+        .join("; ");
+}
+export function validateGoogleMetadataDocument(document) {
+    const result = googleMetadataDocumentSchema.safeParse(document);
+    if (!result.success) {
+        throw new StoremetaError("VALIDATION_ERROR", `Google metadata validation failed: ${formatGoogleMetadataIssues(result.error)}`, { cause: result.error });
+    }
+    return result.data;
+}
+function getCharacterCount(value) {
+    return Array.from(value).length;
+}
+export function validateGoogleMetadataLengthConstraints(document) {
+    const issues = [];
+    if (document.title !== undefined && getCharacterCount(document.title) > 30) {
+        issues.push("title: must be 30 characters or fewer");
+    }
+    if (document.short_description !== undefined &&
+        getCharacterCount(document.short_description) > 80) {
+        issues.push("short_description: must be 80 characters or fewer");
+    }
+    if (document.full_description !== undefined &&
+        getCharacterCount(document.full_description) > 4000) {
+        issues.push("full_description: must be 4000 characters or fewer");
+    }
+    if (issues.length > 0) {
+        throw new StoremetaError("VALIDATION_ERROR", `Google metadata length validation failed: ${issues.join("; ")}`);
+    }
+}

package/dist/validation/screenshots/extensions.js

@@ -0,0 +1,17 @@
+import { extname } from "node:path";
+import { StoremetaError } from "../../cli/errors.js";
+import { listScreenshotFiles } from "./files.js";
+const SUPPORTED_SCREENSHOT_EXTENSIONS = new Set([".png", ".jpg", ".jpeg"]);
+export async function validateScreenshotFileExtensions(configPath, app, platforms) {
+    const files = await listScreenshotFiles(configPath, app, platforms);
+    const issues = [];
+    for (const filePath of files) {
+        const extension = extname(filePath).toLowerCase();
+        if (!SUPPORTED_SCREENSHOT_EXTENSIONS.has(extension)) {
+            issues.push(`${filePath}: unsupported screenshot file extension`);
+        }
+    }
+    if (issues.length > 0) {
+        throw new StoremetaError("VALIDATION_ERROR", `Screenshot extension validation failed: ${issues.join("; ")}`);
+    }
+}

package/dist/validation/screenshots/files.js

@@ -0,0 +1,55 @@
+import { readdir } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { StoremetaError } from "../../cli/errors.js";
+async function listDirectoryEntries(directoryPath) {
+    try {
+        return await readdir(directoryPath, { withFileTypes: true });
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return [];
+        }
+        throw new StoremetaError("FILESYSTEM_ERROR", `Failed to read screenshot directory at ${directoryPath}`, { cause: error });
+    }
+}
+export async function listScreenshotFileGroups(configPath, app, platforms) {
+    const projectRoot = dirname(resolve(configPath));
+    const groups = [];
+    for (const platform of platforms) {
+        const platformDir = resolve(projectRoot, app.settings.screenshots.baseDir, platform);
+        const localeEntries = await listDirectoryEntries(platformDir);
+        for (const localeEntry of localeEntries) {
+            if (!localeEntry.isDirectory()) {
+                continue;
+            }
+            const localeDir = join(platformDir, localeEntry.name);
+            const assetTypeEntries = await listDirectoryEntries(localeDir);
+            for (const assetTypeEntry of assetTypeEntries) {
+                if (!assetTypeEntry.isDirectory()) {
+                    continue;
+                }
+                const assetTypeDir = join(localeDir, assetTypeEntry.name);
+                const fileEntries = await listDirectoryEntries(assetTypeDir);
+                const files = fileEntries
+                    .filter((fileEntry) => fileEntry.isFile())
+                    .map((fileEntry) => join(assetTypeDir, fileEntry.name))
+                    .sort((left, right) => left.localeCompare(right));
+                groups.push({
+                    directory: assetTypeDir,
+                    files,
+                });
+            }
+        }
+    }
+    return groups;
+}
+export async function listScreenshotFiles(configPath, app, platforms) {
+    const files = [];
+    for (const group of await listScreenshotFileGroups(configPath, app, platforms)) {
+        files.push(...group.files);
+    }
+    return files.sort((left, right) => left.localeCompare(right));
+}

package/dist/validation/screenshots/folders.js

@@ -0,0 +1,41 @@
+import { readdir } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { StoremetaError } from "../../cli/errors.js";
+async function listDirectoryEntries(directoryPath) {
+    try {
+        return await readdir(directoryPath, { withFileTypes: true });
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return [];
+        }
+        throw new StoremetaError("FILESYSTEM_ERROR", `Failed to read screenshot directory at ${directoryPath}`, { cause: error });
+    }
+}
+export async function validateScreenshotFolderStructure(configPath, app, platforms) {
+    const projectRoot = dirname(resolve(configPath));
+    const issues = [];
+    for (const platform of platforms) {
+        const platformDir = resolve(projectRoot, app.settings.screenshots.baseDir, platform);
+        const localeEntries = await listDirectoryEntries(platformDir);
+        for (const localeEntry of localeEntries) {
+            if (!localeEntry.isDirectory()) {
+                issues.push(`${join(platformDir, localeEntry.name)}: expected a locale directory`);
+                continue;
+            }
+            const localeDir = join(platformDir, localeEntry.name);
+            const assetTypeEntries = await listDirectoryEntries(localeDir);
+            for (const assetTypeEntry of assetTypeEntries) {
+                if (!assetTypeEntry.isDirectory()) {
+                    issues.push(`${join(localeDir, assetTypeEntry.name)}: expected an asset type directory`);
+                }
+            }
+        }
+    }
+    if (issues.length > 0) {
+        throw new StoremetaError("VALIDATION_ERROR", `Screenshot folder validation failed: ${issues.join("; ")}`);
+    }
+}

package/dist/validation/screenshots/order.js

@@ -0,0 +1,25 @@
+import { basename, extname } from "node:path";
+import { StoremetaError } from "../../cli/errors.js";
+import { listScreenshotFileGroups } from "./files.js";
+export async function validateScreenshotFileOrdering(configPath, app, platforms) {
+    const groups = await listScreenshotFileGroups(configPath, app, platforms);
+    const issues = [];
+    for (const group of groups) {
+        const orderedFileNames = group.files
+            .map((filePath) => basename(filePath))
+            .sort((left, right) => left.localeCompare(right, undefined, { numeric: true }));
+        for (const [index, fileName] of orderedFileNames.entries()) {
+            const numericName = basename(fileName, extname(fileName));
+            if (!/^\d+$/.test(numericName)) {
+                issues.push(`${group.directory}/${fileName}: expected a numeric filename`);
+                continue;
+            }
+            if (Number(numericName) !== index + 1) {
+                issues.push(`${group.directory}/${fileName}: expected screenshot order ${index + 1}`);
+            }
+        }
+    }
+    if (issues.length > 0) {
+        throw new StoremetaError("VALIDATION_ERROR", `Screenshot ordering validation failed: ${issues.join("; ")}`);
+    }
+}