shipscreens 0.1.0

package/cli/commands/init.js

@@ -0,0 +1,339 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { deflateSync } from 'node:zlib';
+import { DEVICE_LIBRARY } from '../../src/constants/devices.js';
+
+const DEFAULT_LOCALES = ['en-US'];
+const DEFAULT_SLIDES = 5;
+export const DEFAULT_DEVICES = [
+  { id: 'iphone69', platform: 'ios' },
+  { id: 'pixel8', platform: 'android', androidBucket: 'phoneScreenshots' },
+];
+
+export const PLACEHOLDER_COLOR = [30, 41, 59, 255];
+export const PLACEHOLDER_WIDTH = 1080;
+export const PLACEHOLDER_HEIGHT = 1920;
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let i = 0; i < table.length; i += 1) {
+    let c = i;
+    for (let k = 0; k < 8; k += 1) {
+      c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    table[i] = c >>> 0;
+  }
+  return table;
+})();
+
+const crc32 = (buffer) => {
+  let crc = 0xffffffff;
+  for (const byte of buffer) {
+    crc = (crc >>> 8) ^ CRC_TABLE[(crc ^ byte) & 0xff];
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+};
+
+const pngChunk = (type, data) => {
+  const typeBuffer = Buffer.from(type, 'ascii');
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(data.length);
+  const crcBuffer = Buffer.alloc(4);
+  const crc = crc32(Buffer.concat([typeBuffer, data]));
+  crcBuffer.writeUInt32BE(crc);
+  return Buffer.concat([length, typeBuffer, data, crcBuffer]);
+};
+
+export const createSolidPng = ({ width, height, color }) => {
+  const row = Buffer.alloc(1 + width * 4);
+  row[0] = 0;
+  for (let i = 0; i < width; i += 1) {
+    const offset = 1 + i * 4;
+    row[offset] = color[0];
+    row[offset + 1] = color[1];
+    row[offset + 2] = color[2];
+    row[offset + 3] = color[3];
+  }
+
+  const raw = Buffer.alloc(row.length * height);
+  for (let y = 0; y < height; y += 1) {
+    row.copy(raw, y * row.length);
+  }
+
+  const compressed = deflateSync(raw);
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = 6;
+  ihdr[10] = 0;
+  ihdr[11] = 0;
+  ihdr[12] = 0;
+
+  return Buffer.concat([
+    PNG_SIGNATURE,
+    pngChunk('IHDR', ihdr),
+    pngChunk('IDAT', compressed),
+    pngChunk('IEND', Buffer.alloc(0)),
+  ]);
+};
+
+const parseList = (raw) => {
+  if (!raw) return [];
+  return String(raw)
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+};
+
+export const formatIndex = (value, width) => String(value).padStart(width, '0');
+
+const yamlQuoteIfNeeded = (value) => {
+  if (value === null || value === undefined) return '';
+  const raw = String(value);
+  // YAML treats `# ...` as a comment. Hex colors like "#0f172a" must be quoted.
+  if (raw.startsWith('#')) return `'${raw.replace(/'/g, "''")}'`;
+  return raw;
+};
+
+export const buildConfigYaml = ({ locales, slides, devices, assets, style } = {}) => {
+  const primaryLocale = locales[0];
+  const indexWidth = Math.max(2, String(slides).length);
+  const lines = ['schemaVersion: 1', '', 'locales:'];
+
+  locales.forEach((localeId) => {
+    lines.push(`  - id: ${localeId}`);
+  });
+
+  lines.push('', 'devices:');
+  (devices?.length ? devices : DEFAULT_DEVICES).forEach((device) => {
+    lines.push(`  - id: ${device.id}`);
+    if (device.platform) lines.push(`    platform: ${device.platform}`);
+    if (device.androidBucket) lines.push(`    androidBucket: ${device.androidBucket}`);
+  });
+
+  if (assets?.background || assets?.logo || (assets?.badges && assets.badges.length)) {
+    lines.push('', 'assets:');
+    if (assets.background) {
+      lines.push('  background:');
+      lines.push(`    type: ${assets.background.type}`);
+      if (assets.background.type === 'solid') {
+        lines.push(`    color: ${yamlQuoteIfNeeded(assets.background.color)}`);
+      } else if (assets.background.type === 'gradient') {
+        lines.push(`    start: ${yamlQuoteIfNeeded(assets.background.start)}`);
+        lines.push(`    end: ${yamlQuoteIfNeeded(assets.background.end)}`);
+        if (typeof assets.background.angle === 'number') lines.push(`    angle: ${assets.background.angle}`);
+      } else if (assets.background.type === 'image') {
+        lines.push(`    path: ${assets.background.path}`);
+        if (typeof assets.background.blur === 'number') lines.push(`    blur: ${assets.background.blur}`);
+        if (typeof assets.background.opacity === 'number') lines.push(`    opacity: ${assets.background.opacity}`);
+      }
+    }
+    if (assets.logo?.path) {
+      lines.push('  logo:');
+      lines.push(`    path: ${assets.logo.path}`);
+    }
+    if (assets.badges?.length) {
+      lines.push('  badges:');
+      assets.badges.forEach((badge) => {
+        lines.push(`    - id: ${badge.id}`);
+        lines.push(`      path: ${badge.path}`);
+      });
+    }
+  }
+
+  if (style && Object.keys(style).length) {
+    lines.push('', 'style:');
+    if (style.textColor) lines.push(`  textColor: ${yamlQuoteIfNeeded(style.textColor)}`);
+    if (style.layoutMode) lines.push(`  layoutMode: ${style.layoutMode}`);
+    if (typeof style.topSpacing === 'number') lines.push(`  topSpacing: ${style.topSpacing}`);
+    if (typeof style.deviceScale === 'number') lines.push(`  deviceScale: ${style.deviceScale}`);
+    if (style.frameColor) lines.push(`  frameColor: ${style.frameColor}`);
+    if (style.selectedFont) lines.push(`  selectedFont: ${style.selectedFont}`);
+    if (style.badgeType) lines.push(`  badgeType: ${style.badgeType}`);
+    if (typeof style.headerSize === 'number') lines.push(`  headerSize: ${style.headerSize}`);
+    if (typeof style.subHeaderSize === 'number') lines.push(`  subHeaderSize: ${style.subHeaderSize}`);
+    if (style.orientation) lines.push(`  orientation: ${style.orientation}`);
+  }
+
+  lines.push('', 'slides:');
+  for (let i = 1; i <= slides; i += 1) {
+    const index = formatIndex(i, indexWidth);
+    lines.push(`  - id: ${i}`);
+    lines.push('    screenshot:');
+    lines.push(`      path: assets/${primaryLocale}/${index}.png`);
+    if (locales.length > 1) {
+      lines.push('    screenshotsByLocale:');
+      locales.slice(1).forEach((localeId) => {
+        lines.push(`      ${localeId}: assets/${localeId}/${index}.png`);
+      });
+    }
+    lines.push('    text:');
+    locales.forEach((localeId) => {
+      lines.push(`      ${localeId}:`);
+      lines.push(`        header: Replace headline ${i}`);
+      lines.push(`        sub: Replace subtitle ${i}`);
+    });
+  }
+
+  return `${lines.join('\n')}\n`;
+};
+
+export const buildCopyCsv = ({ locales, slides }) => {
+  const headers = ['Locale'];
+  for (let i = 1; i <= slides; i += 1) {
+    headers.push(`Header_${i}`, `Subtitle_${i}`);
+  }
+
+  const rows = locales.map((localeId) => {
+    const cells = [localeId];
+    for (let i = 1; i <= slides; i += 1) {
+      cells.push(`Replace headline ${i}`, `Replace subtitle ${i}`);
+    }
+    return cells.join(',');
+  });
+
+  return `${headers.join(',')}\n${rows.join('\n')}\n`;
+};
+
+export const ensureDir = async (dirPath) => {
+  await fs.mkdir(dirPath, { recursive: true });
+};
+
+const pathExists = async (filePath) => {
+  try {
+    await fs.stat(filePath);
+    return true;
+  } catch (err) {
+    if (err?.code === 'ENOENT') return false;
+    throw err;
+  }
+};
+
+function normalizeDeviceConfig(rawDevices) {
+  if (!rawDevices?.length) return [];
+  return rawDevices.map((device) => ({
+    id: device.id,
+    platform: device.platform,
+    androidBucket: device.androidBucket,
+  }));
+}
+
+export function resolveDevices({ devices }) {
+  if (!devices) return DEFAULT_DEVICES;
+  const list = Array.isArray(devices) ? devices : parseList(devices);
+  if (!list.length) return DEFAULT_DEVICES;
+
+  const resolved = list.map((id) => {
+    const def = DEVICE_LIBRARY[id];
+    if (!def) {
+      throw new Error(`Unknown device id: ${id}. See src/constants/devices.js for valid ids.`);
+    }
+    const group = def.group || '';
+    const isAndroid = group.toLowerCase().includes('android');
+    const platform = isAndroid ? 'android' : 'ios';
+    const androidBucket =
+      platform === 'android'
+        ? group.toLowerCase().includes('tablet')
+          ? 'tenInchScreenshots'
+          : 'phoneScreenshots'
+        : undefined;
+    return { id, platform, androidBucket };
+  });
+
+  const androidBuckets = new Map();
+  resolved.forEach((device) => {
+    if (device.platform !== 'android') return;
+    const bucket = device.androidBucket || 'phoneScreenshots';
+    const existing = androidBuckets.get(bucket);
+    if (existing) {
+      throw new Error(
+        `Multiple Android devices map to the same Google Play bucket (${bucket}): ${existing.id}, ${device.id}\n` +
+          `Pick one Android device per bucket (phoneScreenshots/tenInchScreenshots).`
+      );
+    }
+    androidBuckets.set(bucket, device);
+  });
+
+  return normalizeDeviceConfig(resolved);
+}
+
+export async function runInit({ dir = '.', slides = DEFAULT_SLIDES, locales, devices, assets, style, force = false } = {}) {
+  const targetDir = path.resolve(process.cwd(), dir);
+  const localeList = parseList(locales);
+  const resolvedLocales = localeList.length ? localeList : DEFAULT_LOCALES;
+  const resolvedDevices = resolveDevices({ devices });
+
+  const slideCount = Number(slides || DEFAULT_SLIDES);
+  if (!Number.isInteger(slideCount) || slideCount < 1 || slideCount > 10) {
+    throw new Error('Invalid --slides value. Expected an integer between 1 and 10.');
+  }
+  if (!resolvedLocales.length) {
+    throw new Error('Invalid --locales value. Provide at least one locale id.');
+  }
+
+  const configPath = path.join(targetDir, 'shipscreens.config.yml');
+  const csvPath = path.join(targetDir, 'copy.csv');
+
+  const filesToCheck = [configPath, csvPath];
+  for (const localeId of resolvedLocales) {
+    for (let i = 1; i <= slideCount; i += 1) {
+      const index = formatIndex(i, Math.max(2, String(slideCount).length));
+      filesToCheck.push(path.join(targetDir, 'assets', localeId, `${index}.png`));
+    }
+  }
+
+  if (!force) {
+    const conflicts = [];
+    for (const filePath of filesToCheck) {
+      if (await pathExists(filePath)) conflicts.push(filePath);
+    }
+    if (conflicts.length) {
+      throw new Error(
+        `Init would overwrite existing files. Use --force to overwrite.\n` +
+          `Conflicts:\n${conflicts.map((item) => `- ${item}`).join('\n')}`
+      );
+    }
+  }
+
+  await ensureDir(targetDir);
+
+  const configYaml = buildConfigYaml({
+    locales: resolvedLocales,
+    slides: slideCount,
+    devices: resolvedDevices,
+    assets,
+    style,
+  });
+  await fs.writeFile(configPath, configYaml, 'utf8');
+
+  const csv = buildCopyCsv({ locales: resolvedLocales, slides: slideCount });
+  await fs.writeFile(csvPath, csv, 'utf8');
+
+  const placeholder = createSolidPng({
+    width: PLACEHOLDER_WIDTH,
+    height: PLACEHOLDER_HEIGHT,
+    color: PLACEHOLDER_COLOR,
+  });
+
+  const indexWidth = Math.max(2, String(slideCount).length);
+  for (const localeId of resolvedLocales) {
+    for (let i = 1; i <= slideCount; i += 1) {
+      const index = formatIndex(i, indexWidth);
+      const assetPath = path.join(targetDir, 'assets', localeId, `${index}.png`);
+      await ensureDir(path.dirname(assetPath));
+      await fs.writeFile(assetPath, placeholder);
+    }
+  }
+
+  return {
+    dir: targetDir,
+    configPath,
+    csvPath,
+    locales: resolvedLocales,
+    slides: slideCount,
+    devices: resolvedDevices,
+  };
+}

package/cli/commands/lock.js

@@ -0,0 +1,144 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { collectAssetReferences } from '../assetRefs.js';
+import { loadShipScreensConfig } from '../loadConfig.js';
+import { sha256File } from '../hash.js';
+import { SHIPSCREENS_CONFIG_SCHEMA_VERSION } from '../schema.js';
+import { isPathInsideRoot, resolveValidationRoot } from '../rootPolicy.js';
+
+async function statFile(absolutePath) {
+  const stat = await fs.stat(absolutePath);
+  if (!stat.isFile()) {
+    throw new Error(`Not a file: ${absolutePath}`);
+  }
+  return stat;
+}
+
+function serializeLock(lock) {
+  return `${JSON.stringify(lock, null, 2)}\n`;
+}
+
+function compareStrings(a, b) {
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+
+function resolveOutPath({ configDir, outPath }) {
+  if (!outPath) return path.join(configDir, 'shipscreens.lock.json');
+  if (path.isAbsolute(outPath)) return outPath;
+  return path.resolve(configDir, outPath);
+}
+
+function diffLockSummary({ expected, actual }) {
+  if (!actual || typeof actual !== 'object') {
+    return 'Existing lockfile is not a JSON object.';
+  }
+
+  const expectedAssets = Array.isArray(expected.assets) ? expected.assets : [];
+  const actualAssets = Array.isArray(actual.assets) ? actual.assets : [];
+  const expectedByPath = new Map(expectedAssets.map((a) => [a.path, a]));
+  const actualByPath = new Map(actualAssets.map((a) => [a.path, a]));
+
+  const added = [];
+  const removed = [];
+  const changed = [];
+
+  for (const [assetPath, expectedAsset] of expectedByPath.entries()) {
+    const actualAsset = actualByPath.get(assetPath);
+    if (!actualAsset) {
+      added.push(assetPath);
+      continue;
+    }
+    if (expectedAsset.sha256 !== actualAsset.sha256 || expectedAsset.bytes !== actualAsset.bytes) {
+      changed.push(assetPath);
+    }
+  }
+
+  for (const assetPath of actualByPath.keys()) {
+    if (!expectedByPath.has(assetPath)) removed.push(assetPath);
+  }
+
+  added.sort(compareStrings);
+  removed.sort(compareStrings);
+  changed.sort(compareStrings);
+
+  const lines = [`Lockfile differs: ${added.length} added, ${removed.length} removed, ${changed.length} changed`];
+
+  const maxDetails = 10;
+  added.slice(0, maxDetails).forEach((p) => lines.push(`+ ${p}`));
+  removed.slice(0, maxDetails).forEach((p) => lines.push(`- ${p}`));
+  changed.slice(0, maxDetails).forEach((p) => {
+    const e = expectedByPath.get(p);
+    const a = actualByPath.get(p);
+    lines.push(`~ ${p} (sha256 ${a.sha256} -> ${e.sha256}, bytes ${a.bytes} -> ${e.bytes})`);
+  });
+
+  if (added.length > maxDetails || removed.length > maxDetails || changed.length > maxDetails) {
+    lines.push('(diff truncated)');
+  }
+
+  return lines.join('\n');
+}
+
+export async function runLock({ configPath, outPath, check = false }) {
+  const { config, configDir } = await loadShipScreensConfig(configPath);
+  const { rootPath, rootRealPath } = await resolveValidationRoot({ configDir });
+
+  const refs = collectAssetReferences(config);
+  const uniqueAssetPaths = [...new Set(refs.map((r) => r.path))].sort(compareStrings);
+
+  const assets = [];
+  for (const assetPath of uniqueAssetPaths) {
+    const absoluteAssetPath = path.resolve(configDir, assetPath);
+    if (!isPathInsideRoot({ rootPath, candidatePath: absoluteAssetPath })) {
+      throw new Error(`Path escapes repo root: ${assetPath}`);
+    }
+    const stat = await statFile(absoluteAssetPath);
+    const realAssetPath = await fs.realpath(absoluteAssetPath);
+    if (!isPathInsideRoot({ rootPath: rootRealPath, candidatePath: realAssetPath })) {
+      throw new Error(`Symlink escapes repo root: ${assetPath} (resolves to ${realAssetPath})`);
+    }
+    const sha256 = await sha256File(absoluteAssetPath);
+    assets.push({
+      path: assetPath,
+      bytes: stat.size,
+      sha256,
+    });
+  }
+
+  const lock = {
+    version: 1,
+    configSchemaVersion: SHIPSCREENS_CONFIG_SCHEMA_VERSION,
+    assets,
+  };
+
+  const resolvedOutPath = resolveOutPath({ configDir, outPath });
+  const expected = serializeLock(lock);
+
+  if (check) {
+    let existing;
+    try {
+      existing = await fs.readFile(resolvedOutPath, 'utf8');
+    } catch (err) {
+      if (err?.code === 'ENOENT') {
+        throw new Error(`Lockfile missing: ${resolvedOutPath}\nRun: shipscreens lock --config ${configPath}`);
+      }
+      throw err;
+    }
+
+    if (existing !== expected) {
+      let parsedExisting = null;
+      try {
+        parsedExisting = JSON.parse(existing);
+      } catch {
+        // ignore parse error; summary will mention invalid JSON
+      }
+      throw new Error(`${diffLockSummary({ expected: lock, actual: parsedExisting })}\nRun: shipscreens lock`);
+    }
+
+    return { outPath: resolvedOutPath, assetCount: assets.length, checked: true };
+  }
+
+  await fs.writeFile(resolvedOutPath, expected, 'utf8');
+  return { outPath: resolvedOutPath, assetCount: assets.length, checked: false };
+}

package/cli/commands/plan.js

@@ -0,0 +1,203 @@
+import path from 'node:path';
+import { runValidate } from './validate.js';
+import { loadShipScreensConfig } from '../loadConfig.js';
+import { resolveOutRoot, resolveOutputPath, resolveZipOutPath } from '../outputPaths.js';
+import { formatScreenshotIndex, getScreenshotIndexWidth } from '../buildOutputs.js';
+
+function compareStrings(a, b) {
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+
+function normalizeProfile(profile) {
+  const normalized = String(profile || 'any')
+    .trim()
+    .toLowerCase();
+  if (!['any', 'appstore', 'playstore'].includes(normalized)) {
+    throw new Error(`Unknown plan profile: ${normalized} (expected: appstore|playstore|any)`);
+  }
+  return normalized;
+}
+
+function toPosixPath(value) {
+  return String(value).split(path.sep).join('/');
+}
+
+function toDeviceSlug(deviceId) {
+  return String(deviceId).toLowerCase();
+}
+
+function getAndroidBucket(device) {
+  return device.androidBucket || 'phoneScreenshots';
+}
+
+function groupAndroidDevicesByBucket(devices) {
+  const map = new Map();
+  devices.forEach((device) => {
+    const bucket = getAndroidBucket(device);
+    const existing = map.get(bucket);
+    if (existing) {
+      throw new Error(
+        `Multiple Android devices map to the same Google Play bucket (${bucket}): ${existing.id}, ${device.id}\n` +
+          `Each bucket represents a single screenshot set on Google Play (writing both would overwrite / conflict).\n` +
+          `Set only one Android device per bucket, or set devices[].androidBucket explicitly.`
+      );
+    }
+    map.set(bucket, device);
+  });
+  return map;
+}
+
+function resolveOutRootRel({ configDir, outRoot }) {
+  const rel = path.relative(configDir, outRoot);
+  if (!rel) return '.';
+  return toPosixPath(rel);
+}
+
+function resolvePathRel({ baseDir, absolutePath }) {
+  const rel = path.relative(baseDir, absolutePath);
+  if (!rel) return '.';
+  return toPosixPath(rel);
+}
+
+export async function runPlan({ configPath, outDir, iosDir, androidDir, zipOut, profile } = {}) {
+  const normalizedProfile = normalizeProfile(profile);
+  await runValidate({ configPath });
+
+  const { config, configDir } = await loadShipScreensConfig(configPath);
+  const outRoot = resolveOutRoot({ configDir, outDir });
+
+  const resolvedIosDir = resolveOutputPath({
+    outRoot,
+    value: iosDir || config.output?.directory,
+    fallback: 'fastlane/screenshots',
+  });
+  const resolvedAndroidDir = resolveOutputPath({
+    outRoot,
+    value: androidDir || config.output?.androidDirectory,
+    fallback: 'fastlane/metadata/android',
+  });
+  const resolvedZipPath = resolveZipOutPath({ outRoot, zipOut });
+
+  const devices = Array.isArray(config.devices) ? config.devices : [];
+  const iosDevices = devices
+    .filter((d) => d.platform !== 'android')
+    .map((d) => ({ id: d.id, slug: toDeviceSlug(d.id) }))
+    .sort((a, b) => compareStrings(a.slug, b.slug));
+
+  const androidBuckets = [...groupAndroidDevicesByBucket(devices.filter((d) => d.platform === 'android')).entries()]
+    .sort(([a], [b]) => compareStrings(a, b))
+    .map(([bucket, device]) => ({ bucket, deviceId: device.id }));
+
+  const locales = (config.locales || []).map((l) => l.id).sort(compareStrings);
+  const slideCount = config.slides.length;
+  const indexWidth = getScreenshotIndexWidth(slideCount);
+  const indices = Array.from({ length: slideCount }, (_, idx) => formatScreenshotIndex(idx + 1, indexWidth));
+
+  const includeIos = normalizedProfile !== 'playstore';
+  const includeAndroid = normalizedProfile !== 'appstore';
+
+  if (includeIos && !iosDevices.length) {
+    throw new Error(`No iOS devices configured. Add at least one iOS device, or use --profile playstore.`);
+  }
+  if (includeAndroid && !androidBuckets.length) {
+    throw new Error(`No Android devices configured. Add at least one Android device, or use --profile appstore.`);
+  }
+
+  const outRootRel = resolveOutRootRel({ configDir, outRoot });
+  const iosDirRelToOut = resolvePathRel({ baseDir: outRoot, absolutePath: resolvedIosDir });
+  const androidDirRelToOut = resolvePathRel({ baseDir: outRoot, absolutePath: resolvedAndroidDir });
+  const zipPathRelToOut = resolvePathRel({ baseDir: outRoot, absolutePath: resolvedZipPath });
+
+  const iosSets = [];
+  if (includeIos) {
+    for (const localeId of locales) {
+      for (const device of iosDevices) {
+        const files = indices.map((padded) => `${device.slug}_${padded}.png`);
+        iosSets.push({
+          locale: localeId,
+          device: device.slug,
+          dir: path.posix.join(iosDirRelToOut, localeId),
+          files,
+        });
+      }
+    }
+  }
+
+  const androidSets = [];
+  if (includeAndroid) {
+    for (const localeId of locales) {
+      for (const { bucket } of androidBuckets) {
+        const files = indices.map((padded) => `${padded}.png`);
+        androidSets.push({
+          locale: localeId,
+          bucket,
+          dir: path.posix.join(androidDirRelToOut, localeId, 'images', bucket),
+          files,
+        });
+      }
+    }
+  }
+
+  const expectedDirFiles = [
+    ...iosSets.flatMap((set) => set.files.map((file) => path.posix.join(set.dir, file))),
+    ...androidSets.flatMap((set) => set.files.map((file) => path.posix.join(set.dir, file))),
+  ].sort(compareStrings);
+
+  const expectedZipEntries = [
+    ...iosSets.flatMap((set) => set.files.map((file) => path.posix.join('fastlane', 'screenshots', set.locale, file))),
+    ...androidSets.flatMap((set) =>
+      set.files.map((file) => path.posix.join('fastlane', 'metadata', 'android', set.locale, 'images', set.bucket, file))
+    ),
+  ].sort(compareStrings);
+
+  return {
+    version: 1,
+    profile: normalizedProfile,
+    out: {
+      root: outRootRel,
+      iosDir: iosDirRelToOut,
+      androidDir: androidDirRelToOut,
+      zipPath: zipPathRelToOut,
+    },
+    config: {
+      schemaVersion: config.schemaVersion,
+      locales,
+      slides: slideCount,
+      indexWidth,
+      indices,
+      iosDevices: iosDevices.map((d) => d.slug),
+      androidBuckets: androidBuckets.map((b) => b.bucket),
+    },
+    build: {
+      writes: {
+        dirFiles: expectedDirFiles,
+        zipEntries: expectedZipEntries,
+      },
+      clean: {
+        ios: {
+          locales,
+          deviceSlugs: iosDevices.map((d) => d.slug),
+          pattern: '<device>_<index>.png (unframed only)',
+        },
+        android: {
+          locales,
+          buckets: androidBuckets.map((b) => b.bucket),
+          pattern: '<index>.png',
+        },
+      },
+    },
+    stage: {
+      profiles: {
+        appstore: { includes: ['ios'], excludes: ['android'], iosVariant: 'auto' },
+        playstore: { includes: ['android'], excludes: ['ios'] },
+        any: { includes: ['ios', 'android'], excludes: [] },
+      },
+      notes: [
+        'Use shipscreens stage --profile <appstore|playstore|any> to copy only upload-ready files into a new root.',
+        'For profile=appstore, stage will refuse partial framed outputs and choose *_framed.png only when complete.',
+      ],
+    },
+  };
+}
+