storemeta 0.1.0

package/dist/cli.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+import { Command, Option } from "commander";
+import { runAuthCheckCommand } from "./cli/auth-check.js";
+import { runConfigDoctorCommand } from "./cli/config-doctor.js";
+import { runInitCommand } from "./cli/init.js";
+import { applyCommandSummaryExitCode } from "./cli/exit-code.js";
+import { runLocalesListCommand } from "./cli/locales-list.js";
+import { runMetadataDiffCommand } from "./cli/metadata-diff.js";
+import { runMetadataPullCommand } from "./cli/metadata-pull.js";
+import { runMetadataPushCommand } from "./cli/metadata-push.js";
+import { renderCommandError, renderCommandSummary } from "./cli/render.js";
+import { runScaffoldCommand } from "./cli/scaffold.js";
+import { runScreenshotsDiffCommand } from "./cli/screenshots-diff.js";
+import { runScreenshotsPullCommand } from "./cli/screenshots-pull.js";
+import { runScreenshotsPushCommand } from "./cli/screenshots-push.js";
+import { runValidateCommand } from "./cli/validate.js";
+export function buildCliProgram() {
+    const program = new Command()
+        .name("storemeta")
+        .description("CLI for pulling, validating, and pushing App Store Connect and Google Play metadata and screenshots.")
+        .option("--config <path>", "Path to the root storemeta config file")
+        .option("--app <id>", "Configured app identifier")
+        .addOption(new Option("--platform <platform>", "Target platform")
+        .choices(["apple", "google", "all"]))
+        .option("--locale <code>", "Target locale code")
+        .option("--dry-run", "Preview changes without applying them")
+        .option("--replace", "Delete existing remote screenshots before uploading new ones")
+        .option("--verbose", "Enable verbose output");
+    const metadataCommand = program
+        .command("metadata")
+        .description("Metadata commands");
+    const screenshotsCommand = program
+        .command("screenshots")
+        .description("Screenshot commands");
+    const authCommand = program.command("auth").description("Auth commands");
+    const configCommand = program.command("config").description("Config commands");
+    const localesCommand = program.command("locales").description("Locale commands");
+    program
+        .command("init")
+        .description("Create a starter storemeta config")
+        .action(async () => {
+        const options = program.opts();
+        const configPath = await runInitCommand(options.config);
+        const summary = await runScaffoldCommand({
+            config: configPath,
+            app: options.app,
+            platform: options.platform,
+        });
+        console.log([
+            "Created starter storemeta project.",
+            "Next steps:",
+            "1. Fill app identifiers in storemeta.yml.",
+            "2. Create Apple App Store Connect API credentials and Google Play service account credentials.",
+            "3. Export the credential environment variables named in storemeta.yml.",
+            "4. Run storemeta auth check, then storemeta validate.",
+            "See docs/AUTH_SETUP.md for credential setup.",
+        ].join("\n"));
+        console.log(renderCommandSummary(summary));
+    });
+    program
+        .command("scaffold")
+        .description("Create missing metadata files and screenshot folders from config")
+        .action(async () => {
+        const options = program.opts();
+        const summary = await runScaffoldCommand({
+            config: options.config,
+            app: options.app,
+            platform: options.platform,
+        });
+        console.log(renderCommandSummary(summary));
+        applyCommandSummaryExitCode(summary);
+    });
+    program
+        .command("validate")
+        .description("Validate the storemeta project configuration")
+        .action(async () => {
+        const options = program.opts();
+        const summary = await runValidateCommand({
+            config: options.config,
+            app: options.app,
+            platform: options.platform,
+        });
+        console.log(renderCommandSummary(summary));
+        applyCommandSummaryExitCode(summary);
+    });
+    metadataCommand
+        .command("pull")
+        .description("Pull remote metadata into the local project")
+        .action(async () => {
+        const options = program.opts();
+        await runMetadataPullCommand({
+            config: options.config,
+            app: options.app,
+            locale: options.locale,
+            platform: options.platform,
+        });
+    });
+    metadataCommand
+        .command("push")
+        .description("Push local metadata to the store")
+        .action(async () => {
+        const options = program.opts();
+        const summary = await runMetadataPushCommand({
+            config: options.config,
+            app: options.app,
+            platform: options.platform,
+            locale: options.locale,
+            dryRun: options.dryRun,
+        });
+        console.log(renderCommandSummary(summary));
+        applyCommandSummaryExitCode(summary);
+    });
+    metadataCommand
+        .command("diff")
+        .description("Compare configured metadata locales with local metadata files")
+        .action(async () => {
+        const options = program.opts();
+        const summary = await runMetadataDiffCommand({
+            config: options.config,
+            app: options.app,
+            platform: options.platform,
+        });
+        console.log(renderCommandSummary(summary));
+        applyCommandSummaryExitCode(summary);
+    });
+    authCommand
+        .command("check")
+        .description("Check configured credential environment variables")
+        .action(async () => {
+        const options = program.opts();
+        const summary = await runAuthCheckCommand({
+            config: options.config,
+            app: options.app,
+            platform: options.platform,
+        });
+        console.log(renderCommandSummary(summary));
+        applyCommandSummaryExitCode(summary);
+    });
+    configCommand
+        .command("doctor")
+        .description("Inspect resolved config, app, directories, and platforms")
+        .action(async () => {
+        const options = program.opts();
+        const summary = await runConfigDoctorCommand({
+            config: options.config,
+            app: options.app,
+            platform: options.platform,
+        });
+        console.log(renderCommandSummary(summary));
+        applyCommandSummaryExitCode(summary);
+    });
+    localesCommand
+        .command("list")
+        .description("List configured default locales")
+        .action(async () => {
+        const options = program.opts();
+        const summary = await runLocalesListCommand({
+            config: options.config,
+            app: options.app,
+            platform: options.platform,
+        });
+        console.log(renderCommandSummary(summary));
+        applyCommandSummaryExitCode(summary);
+    });
+    screenshotsCommand
+        .command("pull")
+        .description("Pull remote screenshots into the local project")
+        .action(async () => {
+        const options = program.opts();
+        const summary = await runScreenshotsPullCommand({
+            config: options.config,
+            app: options.app,
+            platform: options.platform,
+            locale: options.locale,
+        });
+        console.log(renderCommandSummary(summary));
+        applyCommandSummaryExitCode(summary);
+    });
+    screenshotsCommand
+        .command("diff")
+        .description("Compare configured screenshot locales with local screenshot folders")
+        .action(async () => {
+        const options = program.opts();
+        const summary = await runScreenshotsDiffCommand({
+            config: options.config,
+            app: options.app,
+            platform: options.platform,
+        });
+        console.log(renderCommandSummary(summary));
+        applyCommandSummaryExitCode(summary);
+    });
+    screenshotsCommand
+        .command("push")
+        .description("Push local screenshots to the store")
+        .action(async () => {
+        const options = program.opts();
+        const summary = await runScreenshotsPushCommand({
+            config: options.config,
+            app: options.app,
+            platform: options.platform,
+            locale: options.locale,
+            dryRun: options.dryRun,
+            replace: options.replace,
+        });
+        console.log(renderCommandSummary(summary));
+        applyCommandSummaryExitCode(summary);
+    });
+    return program;
+}
+export async function runCli(argv = process.argv) {
+    const program = buildCliProgram();
+    await program.parseAsync(argv);
+}
+export function hasVerboseFlag(argv) {
+    return argv.includes("--verbose");
+}
+void runCli().catch((error) => {
+    console.error(renderCommandError(error, {
+        verbose: hasVerboseFlag(process.argv),
+    }));
+    process.exitCode = 1;
+});

package/dist/config/apps.js

@@ -0,0 +1,21 @@
+export function listConfiguredApps(config) {
+    return Object.entries(config.apps)
+        .sort(([leftId], [rightId]) => leftId.localeCompare(rightId))
+        .map(([id, settings]) => ({
+        id,
+        settings,
+    }));
+}
+export function getConfiguredApp(config, appId) {
+    const settings = config.apps[appId];
+    if (settings === undefined) {
+        return undefined;
+    }
+    return {
+        id: appId,
+        settings,
+    };
+}
+export function hasConfiguredApp(config, appId) {
+    return getConfiguredApp(config, appId) !== undefined;
+}

package/dist/config/load-config.js

@@ -0,0 +1,30 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import YAML from "yaml";
+import { StoremetaError } from "../cli/errors.js";
+export const DEFAULT_CONFIG_FILE = "storemeta.yml";
+export function resolveConfigPath(configPath) {
+    return resolve(configPath ?? DEFAULT_CONFIG_FILE);
+}
+export async function loadConfigFile(configPath) {
+    const resolvedPath = resolveConfigPath(configPath);
+    let raw;
+    try {
+        raw = await readFile(resolvedPath, "utf8");
+    }
+    catch (cause) {
+        throw new StoremetaError("FILESYSTEM_ERROR", `Failed to read config file at ${resolvedPath}`, { cause });
+    }
+    let parsed;
+    try {
+        parsed = YAML.parse(raw);
+    }
+    catch (cause) {
+        throw new StoremetaError("CONFIG_ERROR", `Failed to parse YAML config at ${resolvedPath}`, { cause });
+    }
+    return {
+        path: resolvedPath,
+        raw,
+        parsed,
+    };
+}

package/dist/config/schema.js

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import { StoremetaError } from "../cli/errors.js";
+const metadataFormatSchema = z.literal("yaml");
+const projectSettingsSchema = z
+    .object({
+    name: z.string().min(1),
+    defaultApp: z.string().min(1),
+})
+    .strict();
+const metadataSettingsSchema = z
+    .object({
+    baseDir: z.string().min(1),
+    format: metadataFormatSchema,
+})
+    .strict();
+const screenshotSettingsSchema = z
+    .object({
+    baseDir: z.string().min(1),
+})
+    .strict();
+const appleCredentialsSettingsSchema = z
+    .object({
+    issuerIdEnv: z.string().min(1),
+    keyIdEnv: z.string().min(1),
+    privateKeyPathEnv: z.string().min(1),
+})
+    .strict();
+const googleCredentialsSettingsSchema = z
+    .object({
+    serviceAccountPathEnv: z.string().min(1),
+})
+    .strict();
+const localeSettingsSchema = z
+    .object({
+    default: z.array(z.string().min(1)).optional(),
+    map: z.record(z.string(), z.string().min(1)).optional(),
+})
+    .strict();
+const screenshotGroupSettingsSchema = z
+    .object({
+    locales: z.array(z.string().min(1)).min(1),
+})
+    .strict();
+const googleScreenshotSettingsSchema = z
+    .object({
+    groups: z.record(z.string(), screenshotGroupSettingsSchema).optional(),
+})
+    .strict();
+const appleAppSettingsSchema = z
+    .object({
+    appId: z.string().min(1),
+    credentials: appleCredentialsSettingsSchema,
+    locales: localeSettingsSchema.optional(),
+})
+    .strict();
+const googleAppSettingsSchema = z
+    .object({
+    packageName: z.string().min(1),
+    credentials: googleCredentialsSettingsSchema,
+    locales: localeSettingsSchema.optional(),
+    screenshots: googleScreenshotSettingsSchema.optional(),
+})
+    .strict();
+const appSettingsSchema = z
+    .object({
+    metadata: metadataSettingsSchema,
+    screenshots: screenshotSettingsSchema,
+    apple: appleAppSettingsSchema.optional(),
+    google: googleAppSettingsSchema.optional(),
+})
+    .strict();
+export const storemetaConfigSchema = z
+    .object({
+    version: z.literal(1),
+    project: projectSettingsSchema,
+    apps: z
+        .record(z.string().min(1), appSettingsSchema)
+        .refine((apps) => Object.keys(apps).length > 0, {
+        message: "At least one app must be configured",
+    }),
+})
+    .strict();
+function formatSchemaIssues(error) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join(".") : "root";
+        return `${path}: ${issue.message}`;
+    })
+        .join("; ");
+}
+export function validateRootConfig(config) {
+    const result = storemetaConfigSchema.safeParse(config);
+    if (!result.success) {
+        throw new StoremetaError("CONFIG_ERROR", `Config schema validation failed: ${formatSchemaIssues(result.error)}`, { cause: result.error });
+    }
+    return result.data;
+}

package/dist/config/select-app.js

@@ -0,0 +1,10 @@
+import { StoremetaError } from "../cli/errors.js";
+import { getConfiguredApp } from "./apps.js";
+export function selectConfiguredApp(config, selectedAppId) {
+    const targetAppId = selectedAppId ?? config.project.defaultApp;
+    const app = getConfiguredApp(config, targetAppId);
+    if (app === undefined) {
+        throw new StoremetaError("CONFIG_ERROR", `Configured app "${targetAppId}" was not found`);
+    }
+    return app;
+}

package/dist/config/select-platforms.js

@@ -0,0 +1,17 @@
+import { StoremetaError } from "../cli/errors.js";
+export function resolveSelectedPlatforms(app, selectedPlatform) {
+    const configuredPlatforms = [];
+    if (app.settings.apple !== undefined) {
+        configuredPlatforms.push("apple");
+    }
+    if (app.settings.google !== undefined) {
+        configuredPlatforms.push("google");
+    }
+    if (selectedPlatform === undefined || selectedPlatform === "all") {
+        return configuredPlatforms;
+    }
+    if (!configuredPlatforms.includes(selectedPlatform)) {
+        throw new StoremetaError("CONFIG_ERROR", `Configured app "${app.id}" does not support platform "${selectedPlatform}"`);
+    }
+    return [selectedPlatform];
+}

package/dist/config/single-app.js

@@ -0,0 +1,16 @@
+import { StoremetaError } from "../cli/errors.js";
+import { listConfiguredApps } from "./apps.js";
+export function hasSingleConfiguredApp(config) {
+    return listConfiguredApps(config).length === 1;
+}
+export function getSingleConfiguredApp(config) {
+    const [app] = listConfiguredApps(config);
+    return hasSingleConfiguredApp(config) ? app : undefined;
+}
+export function requireSingleConfiguredApp(config) {
+    const app = getSingleConfiguredApp(config);
+    if (app === undefined) {
+        throw new StoremetaError("CONFIG_ERROR", "Expected exactly one configured app");
+    }
+    return app;
+}

package/dist/config/types.js

@@ -0,0 +1 @@
+export {};

package/dist/config/validate-base-dirs.js

@@ -0,0 +1,33 @@
+import { posix, win32 } from "node:path";
+import { StoremetaError } from "../cli/errors.js";
+import { listConfiguredApps } from "./apps.js";
+function isAbsolutePath(value) {
+    return posix.isAbsolute(value) || win32.isAbsolute(value);
+}
+function normalizeRelativePath(value) {
+    return posix.normalize(value.replaceAll("\\", "/"));
+}
+function isSafeRelativeDirectoryPath(value) {
+    if (value.trim().length === 0 || isAbsolutePath(value)) {
+        return false;
+    }
+    const normalized = normalizeRelativePath(value);
+    if (normalized === "." || normalized === "..") {
+        return false;
+    }
+    return !normalized.startsWith("../");
+}
+export function validateBaseDirectoryPaths(config) {
+    const issues = [];
+    for (const app of listConfiguredApps(config)) {
+        if (!isSafeRelativeDirectoryPath(app.settings.metadata.baseDir)) {
+            issues.push(`apps.${app.id}.metadata.baseDir: must be a safe relative path`);
+        }
+        if (!isSafeRelativeDirectoryPath(app.settings.screenshots.baseDir)) {
+            issues.push(`apps.${app.id}.screenshots.baseDir: must be a safe relative path`);
+        }
+    }
+    if (issues.length > 0) {
+        throw new StoremetaError("CONFIG_ERROR", `Base directory validation failed: ${issues.join("; ")}`);
+    }
+}

package/dist/config/validate-credential-env-names.js

@@ -0,0 +1,32 @@
+import { StoremetaError } from "../cli/errors.js";
+import { listConfiguredApps } from "./apps.js";
+const ENV_VAR_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function isValidEnvVarName(value) {
+    return ENV_VAR_NAME_PATTERN.test(value);
+}
+export function validateCredentialEnvVarNames(config) {
+    const issues = [];
+    for (const app of listConfiguredApps(config)) {
+        if (app.settings.apple !== undefined) {
+            const { credentials } = app.settings.apple;
+            if (!isValidEnvVarName(credentials.issuerIdEnv)) {
+                issues.push(`apps.${app.id}.apple.credentials.issuerIdEnv: invalid env var name`);
+            }
+            if (!isValidEnvVarName(credentials.keyIdEnv)) {
+                issues.push(`apps.${app.id}.apple.credentials.keyIdEnv: invalid env var name`);
+            }
+            if (!isValidEnvVarName(credentials.privateKeyPathEnv)) {
+                issues.push(`apps.${app.id}.apple.credentials.privateKeyPathEnv: invalid env var name`);
+            }
+        }
+        if (app.settings.google !== undefined) {
+            const { credentials } = app.settings.google;
+            if (!isValidEnvVarName(credentials.serviceAccountPathEnv)) {
+                issues.push(`apps.${app.id}.google.credentials.serviceAccountPathEnv: invalid env var name`);
+            }
+        }
+    }
+    if (issues.length > 0) {
+        throw new StoremetaError("CONFIG_ERROR", `Credential environment variable validation failed: ${issues.join("; ")}`);
+    }
+}

package/dist/config/validate-platform-identifiers.js

@@ -0,0 +1,24 @@
+import { StoremetaError } from "../cli/errors.js";
+import { listConfiguredApps } from "./apps.js";
+function hasText(value) {
+    return value !== undefined && value.trim().length > 0;
+}
+export function validateRequiredPlatformIdentifiers(config) {
+    const issues = [];
+    for (const app of listConfiguredApps(config)) {
+        const { apple, google } = app.settings;
+        if (apple === undefined && google === undefined) {
+            issues.push(`apps.${app.id}: at least one platform must be configured`);
+            continue;
+        }
+        if (apple !== undefined && !hasText(apple.appId)) {
+            issues.push(`apps.${app.id}.apple.appId: required`);
+        }
+        if (google !== undefined && !hasText(google.packageName)) {
+            issues.push(`apps.${app.id}.google.packageName: required`);
+        }
+    }
+    if (issues.length > 0) {
+        throw new StoremetaError("CONFIG_ERROR", `Platform identifier validation failed: ${issues.join("; ")}`);
+    }
+}

package/dist/formats/load-metadata.js

@@ -0,0 +1,38 @@
+import { readFile } from "node:fs/promises";
+import { extname, resolve } from "node:path";
+import YAML from "yaml";
+import { StoremetaError } from "../cli/errors.js";
+async function loadMetadataFileForExtension(filePath, expectedExtension) {
+    const resolvedPath = resolve(filePath);
+    if (extname(resolvedPath).toLowerCase() !== expectedExtension) {
+        throw new StoremetaError("FILESYSTEM_ERROR", `Expected a ${expectedExtension} metadata file: ${resolvedPath}`);
+    }
+    let raw;
+    try {
+        raw = await readFile(resolvedPath, "utf8");
+    }
+    catch (cause) {
+        throw new StoremetaError("FILESYSTEM_ERROR", `Failed to read metadata file at ${resolvedPath}`, { cause });
+    }
+    let parsed;
+    try {
+        parsed = YAML.parse(raw);
+    }
+    catch (cause) {
+        throw new StoremetaError("CONFIG_ERROR", `Failed to parse YAML metadata at ${resolvedPath}`, { cause });
+    }
+    return {
+        path: resolvedPath,
+        raw,
+        parsed,
+    };
+}
+export async function loadYmlMetadataFile(filePath) {
+    return loadMetadataFileForExtension(filePath, ".yml");
+}
+export async function loadYamlMetadataFile(filePath) {
+    return loadMetadataFileForExtension(filePath, ".yaml");
+}
+export async function loadMarkdownMetadataFile(filePath) {
+    return loadMetadataFileForExtension(filePath, ".md");
+}

package/dist/formats/metadata-types.js

@@ -0,0 +1 @@
+export {};

package/dist/formats/screenshot-types.js

@@ -0,0 +1 @@
+export {};

package/dist/formats/serialize-metadata.js

@@ -0,0 +1,20 @@
+import YAML from "yaml";
+function sortMetadataValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortMetadataValue);
+    }
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey))
+            .map(([key, childValue]) => [key, sortMetadataValue(childValue)]));
+    }
+    return value;
+}
+export function serializeMetadataDocument(document) {
+    const serialized = YAML.stringify(sortMetadataValue(document), {
+        indent: 2,
+        lineWidth: 0,
+        minContentWidth: 0,
+    });
+    return serialized.endsWith("\n") ? serialized : `${serialized}\n`;
+}

package/dist/locales/groups.js

@@ -0,0 +1,12 @@
+import { normalizeLocaleCodes } from "./normalize.js";
+export function listScreenshotGroups(settings) {
+    return Object.entries(settings?.groups ?? {})
+        .sort(([leftName], [rightName]) => leftName.localeCompare(rightName))
+        .map(([name, group]) => ({
+        name,
+        locales: normalizeLocaleCodes(group.locales),
+    }));
+}
+export function getScreenshotGroup(settings, groupName) {
+    return listScreenshotGroups(settings).find((group) => group.name === groupName);
+}

package/dist/locales/map.js

@@ -0,0 +1,15 @@
+import { normalizeLocaleCode } from "./normalize.js";
+function normalizeLocaleMap(localeSettings) {
+    return Object.fromEntries(Object.entries(localeSettings?.map ?? {}).map(([sourceLocale, targetLocale]) => [
+        normalizeLocaleCode(sourceLocale),
+        normalizeLocaleCode(targetLocale),
+    ]));
+}
+export function mapLocaleCode(locale, localeSettings) {
+    const normalizedLocale = normalizeLocaleCode(locale);
+    const localeMap = normalizeLocaleMap(localeSettings);
+    return localeMap[normalizedLocale] ?? normalizedLocale;
+}
+export function mapLocaleCodes(locales, localeSettings) {
+    return locales.map((locale) => mapLocaleCode(locale, localeSettings));
+}

package/dist/locales/normalize.js

@@ -0,0 +1,22 @@
+function normalizeLocaleSegment(segment, index) {
+    if (index === 0) {
+        return segment.toLowerCase();
+    }
+    if (segment.length === 4) {
+        return `${segment[0]?.toUpperCase() ?? ""}${segment.slice(1).toLowerCase()}`;
+    }
+    if (/^[A-Za-z]{2}$/.test(segment) || /^\d{3}$/.test(segment)) {
+        return segment.toUpperCase();
+    }
+    return segment.toLowerCase();
+}
+export function normalizeLocaleCode(locale) {
+    const trimmed = locale.trim().replaceAll("_", "-");
+    const segments = trimmed.split("-").filter((segment) => segment.length > 0);
+    return segments
+        .map((segment, index) => normalizeLocaleSegment(segment, index))
+        .join("-");
+}
+export function normalizeLocaleCodes(locales) {
+    return locales.map(normalizeLocaleCode);
+}

package/dist/locales/types.js

@@ -0,0 +1 @@
+export {};

package/dist/locales/validate-groups.js

@@ -0,0 +1,14 @@
+import { StoremetaError } from "../cli/errors.js";
+import { listScreenshotGroups } from "./groups.js";
+export function validateScreenshotGroups(settings) {
+    const issues = [];
+    for (const group of listScreenshotGroups(settings)) {
+        const uniqueLocales = new Set(group.locales);
+        if (uniqueLocales.size !== group.locales.length) {
+            issues.push(`screenshots.groups.${group.name}: contains duplicate locales after normalization`);
+        }
+    }
+    if (issues.length > 0) {
+        throw new StoremetaError("VALIDATION_ERROR", `Screenshot group validation failed: ${issues.join("; ")}`);
+    }
+}