shipscreens 0.1.0

package/cli/commands/stage.js

@@ -0,0 +1,318 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { runValidate } from './validate.js';
+import { loadShipScreensConfig } from '../loadConfig.js';
+import { resolveOutRoot, resolveOutputPath } from '../outputPaths.js';
+import { formatScreenshotIndex, getScreenshotIndexWidth } from '../buildOutputs.js';
+import { isPathInsideRoot } from '../rootPolicy.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 stage profile: ${normalized} (expected: appstore|playstore|any)`);
+  }
+  return normalized;
+}
+
+async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+async function removeDirSafe(dirPath) {
+  try {
+    await fs.rm(dirPath, { recursive: true, force: true });
+  } catch (err) {
+    if (err?.code === 'ENOENT') return;
+    throw err;
+  }
+}
+
+async function statSafe(filePath) {
+  try {
+    return await fs.stat(filePath);
+  } catch (err) {
+    if (err?.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+async function ensureParentDir(filePath) {
+  await ensureDir(path.dirname(filePath));
+}
+
+async function replaceDir({ sourceDir, destDir }) {
+  await removeDirSafe(destDir);
+  await ensureDir(path.dirname(destDir));
+  await fs.rename(sourceDir, destDir);
+}
+
+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 summarizePaths(label, paths, { max = 10 } = {}) {
+  if (!paths.length) return '';
+  const sorted = [...paths].sort(compareStrings);
+  const lines = [`${label}: ${sorted.length}`];
+  sorted.slice(0, max).forEach((p) => lines.push(`- ${p}`));
+  if (sorted.length > max) lines.push('(truncated)');
+  return lines.join('\n');
+}
+
+export async function runStage({ configPath, fromDir, outDir, profile = 'any' } = {}) {
+  const normalizedProfile = normalizeProfile(profile);
+  const stageIos = normalizedProfile !== 'playstore';
+  const stageAndroid = normalizedProfile !== 'appstore';
+
+  const rawOut = String(outDir || '').trim();
+  if (!rawOut) {
+    throw new Error('shipscreens stage requires --out <dir> (destination root)');
+  }
+
+  await runValidate({ configPath });
+  const { config, configDir } = await loadShipScreensConfig(configPath);
+
+  const sourceOutRoot = resolveOutRoot({ configDir, outDir: fromDir });
+  const destOutRoot = resolveOutRoot({ configDir, outDir });
+
+  if (path.resolve(sourceOutRoot) === path.resolve(destOutRoot)) {
+    throw new Error(
+      `Refusing to stage into the same root as the source outputs.\n` +
+        `Source: ${sourceOutRoot}\n` +
+        `Dest:   ${destOutRoot}\n` +
+        `Pass a different --out, or set --from to the build output root.`
+    );
+  }
+
+  const sourceIosDir = resolveOutputPath({
+    outRoot: sourceOutRoot,
+    value: config.output?.directory,
+    fallback: 'fastlane/screenshots',
+  });
+  const sourceAndroidDir = resolveOutputPath({
+    outRoot: sourceOutRoot,
+    value: config.output?.androidDirectory,
+    fallback: 'fastlane/metadata/android',
+  });
+
+  const destIosDir = resolveOutputPath({
+    outRoot: destOutRoot,
+    value: config.output?.directory,
+    fallback: 'fastlane/screenshots',
+  });
+  const destAndroidDir = resolveOutputPath({
+    outRoot: destOutRoot,
+    value: config.output?.androidDirectory,
+    fallback: 'fastlane/metadata/android',
+  });
+
+  const locales = (config.locales || []).map((l) => l.id).sort(compareStrings);
+  if (!locales.length) {
+    throw new Error('No locales selected. Add at least one locale in shipscreens.config.yml');
+  }
+
+  const slideCount = config.slides.length;
+  if (!slideCount) {
+    throw new Error('No slides found. Add at least one slide in shipscreens.config.yml');
+  }
+  const width = getScreenshotIndexWidth(slideCount);
+
+  const devices = Array.isArray(config.devices) ? config.devices : [];
+  const iosDevices = devices.filter((d) => d.platform !== 'android');
+  const androidDevices = devices.filter((d) => d.platform === 'android');
+  const androidBuckets = [...groupAndroidDevicesByBucket(androidDevices).entries()]
+    .sort(([a], [b]) => compareStrings(a, b))
+    .map(([bucket, device]) => ({ bucket, device }));
+
+  if (stageIos && !iosDevices.length) {
+    throw new Error(`No iOS devices configured. Add at least one iOS device, or use --profile playstore.`);
+  }
+  if (stageAndroid && !androidBuckets.length) {
+    throw new Error(`No Android devices configured. Add at least one Android device, or use --profile appstore.`);
+  }
+
+  if (stageIos && !isPathInsideRoot({ rootPath: destOutRoot, candidatePath: destIosDir })) {
+    throw new Error(
+      `Refusing to stage iOS outputs outside --out root.\n` +
+        `--out: ${destOutRoot}\n` +
+        `iOS output directory: ${destIosDir}\n` +
+        `Set output.directory to a relative path, or stage to a different --out.`
+    );
+  }
+  if (stageAndroid && !isPathInsideRoot({ rootPath: destOutRoot, candidatePath: destAndroidDir })) {
+    throw new Error(
+      `Refusing to stage Android outputs outside --out root.\n` +
+        `--out: ${destOutRoot}\n` +
+        `Android output directory: ${destAndroidDir}\n` +
+        `Set output.androidDirectory to a relative path, or stage to a different --out.`
+    );
+  }
+
+  const missing = [];
+  const copied = [];
+
+  const iosVariant = (() => {
+    if (!stageIos) return null;
+    if (normalizedProfile !== 'appstore') return 'base';
+    return 'auto';
+  })();
+
+  const iosExpected = [];
+  if (stageIos) {
+    for (const localeId of locales) {
+      for (const device of iosDevices) {
+        const deviceSlug = toDeviceSlug(device.id);
+        for (let index = 1; index <= slideCount; index++) {
+          const padded = formatScreenshotIndex(index, width);
+          iosExpected.push({ localeId, deviceSlug, padded });
+        }
+      }
+    }
+  }
+
+  let resolvedIosVariant = iosVariant;
+  if (stageIos) {
+    const baseMissing = [];
+    let anyFramed = false;
+    const framedMissing = [];
+
+    for (const item of iosExpected) {
+      const baseSrc = path.join(sourceIosDir, item.localeId, `${item.deviceSlug}_${item.padded}.png`);
+      const baseStat = await statSafe(baseSrc);
+      if (!baseStat || !baseStat.isFile()) baseMissing.push(baseSrc);
+
+      const framedSrc = path.join(sourceIosDir, item.localeId, `${item.deviceSlug}_${item.padded}_framed.png`);
+      const framedStat = await statSafe(framedSrc);
+      if (framedStat && framedStat.isFile()) {
+        anyFramed = true;
+      } else {
+        framedMissing.push(framedSrc);
+      }
+    }
+
+    if (baseMissing.length) {
+      throw new Error(
+        `${summarizePaths('Missing source file(s) for staging', baseMissing)}\n` +
+          `Run: shipscreens build (and fastlane frameit for framed outputs)`
+      );
+    }
+
+    if (resolvedIosVariant === 'auto') {
+      if (anyFramed) {
+        if (framedMissing.length) {
+          throw new Error(
+            `${summarizePaths('Partial framed iOS outputs detected (refusing to stage)', framedMissing)}\n` +
+              `Some *_framed.png files exist, but not for every locale/device/slide.\n` +
+              `Run frameit for all locales/devices, or remove the partial framed outputs before staging.`
+          );
+        }
+        resolvedIosVariant = 'framed';
+      } else {
+        resolvedIosVariant = 'base';
+      }
+    }
+  }
+
+  const ops = [];
+  if (stageIos) {
+    for (const item of iosExpected) {
+      const suffix = resolvedIosVariant === 'framed' ? '_framed' : '';
+      const fileName = `${item.deviceSlug}_${item.padded}${suffix}.png`;
+      const src = path.join(sourceIosDir, item.localeId, fileName);
+      ops.push({
+        src,
+        destRel: path.join(path.relative(destOutRoot, destIosDir), item.localeId, fileName),
+      });
+    }
+  }
+
+  if (stageAndroid) {
+    for (const localeId of locales) {
+      for (const { bucket } of androidBuckets) {
+        for (let index = 1; index <= slideCount; index++) {
+          const padded = formatScreenshotIndex(index, width);
+          const src = path.join(sourceAndroidDir, localeId, 'images', bucket, `${padded}.png`);
+          ops.push({
+            src,
+            destRel: path.join(path.relative(destOutRoot, destAndroidDir), localeId, 'images', bucket, `${padded}.png`),
+          });
+        }
+      }
+    }
+  }
+
+  for (const op of ops) {
+    const stat = await statSafe(op.src);
+    if (!stat || !stat.isFile()) missing.push(op.src);
+  }
+
+  if (missing.length) {
+    throw new Error(`${summarizePaths('Missing source file(s) for staging', missing)}\nRun: shipscreens build`);
+  }
+
+  const tempParent = path.dirname(destOutRoot);
+  await ensureDir(tempParent);
+  const tempRoot = await fs.mkdtemp(path.join(tempParent, 'shipscreens-stage-'));
+
+  try {
+    for (const op of ops) {
+      const dest = path.join(tempRoot, op.destRel);
+      await ensureParentDir(dest);
+      await fs.copyFile(op.src, dest);
+      copied.push(dest);
+    }
+
+    if (stageIos) {
+      const tempIosDir = path.join(tempRoot, path.relative(destOutRoot, destIosDir));
+      await replaceDir({ sourceDir: tempIosDir, destDir: destIosDir });
+    }
+    if (stageAndroid) {
+      const tempAndroidDir = path.join(tempRoot, path.relative(destOutRoot, destAndroidDir));
+      await replaceDir({ sourceDir: tempAndroidDir, destDir: destAndroidDir });
+    }
+  } finally {
+    await removeDirSafe(tempRoot).catch(() => {});
+  }
+
+  return {
+    profile: normalizedProfile,
+    iosVariant: stageIos ? resolvedIosVariant : null,
+    from: sourceOutRoot,
+    out: destOutRoot,
+    iosDir: destIosDir,
+    androidDir: destAndroidDir,
+    locales: locales.length,
+    slides: slideCount,
+    iosDevices: iosDevices.length,
+    androidDevices: androidDevices.length,
+    files: copied.length,
+  };
+}

package/cli/commands/validate.js

@@ -0,0 +1,89 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { collectAssetReferences } from '../assetRefs.js';
+import { loadShipScreensConfig } from '../loadConfig.js';
+import { isPathInsideRoot, resolveValidationRoot } from '../rootPolicy.js';
+
+function compareStrings(a, b) {
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+
+async function isFile(absolutePath) {
+  try {
+    const stat = await fs.stat(absolutePath);
+    return stat.isFile();
+  } catch {
+    return false;
+  }
+}
+
+export async function runValidate({ configPath }) {
+  const { config, configDir } = await loadShipScreensConfig(configPath);
+  const { rootPath, rootRealPath } = await resolveValidationRoot({ configDir });
+
+  const refs = collectAssetReferences(config);
+  const byPath = new Map();
+  refs.forEach((ref) => {
+    const key = ref.path;
+    const existing = byPath.get(key) || [];
+    existing.push(ref.pointer);
+    byPath.set(key, existing);
+  });
+
+  const missing = [];
+  const outsideRoot = [];
+  const symlinkOutsideRoot = [];
+
+  for (const [assetPath, pointers] of byPath.entries()) {
+    const absoluteAssetPath = path.resolve(configDir, assetPath);
+    if (!isPathInsideRoot({ rootPath, candidatePath: absoluteAssetPath })) {
+      outsideRoot.push({ assetPath, pointers });
+      continue;
+    }
+
+    if (!(await isFile(absoluteAssetPath))) {
+      missing.push({ assetPath, pointers });
+      continue;
+    }
+
+    try {
+      const realAssetPath = await fs.realpath(absoluteAssetPath);
+      if (!isPathInsideRoot({ rootPath: rootRealPath, candidatePath: realAssetPath })) {
+        symlinkOutsideRoot.push({ assetPath, pointers, realAssetPath });
+      }
+    } catch {
+      // ignore realpath errors; missing file is handled above
+    }
+  }
+
+  if (outsideRoot.length) {
+    outsideRoot.sort((a, b) => compareStrings(a.assetPath, b.assetPath));
+    const lines = outsideRoot.flatMap((m) => [
+      `Path escapes repo root: ${m.assetPath}`,
+      ...m.pointers.map((p) => `  - referenced by ${p}`),
+    ]);
+    throw new Error(lines.join('\n'));
+  }
+
+  if (symlinkOutsideRoot.length) {
+    symlinkOutsideRoot.sort((a, b) => compareStrings(a.assetPath, b.assetPath));
+    const lines = symlinkOutsideRoot.flatMap((m) => [
+      `Symlink escapes repo root: ${m.assetPath}`,
+      `  - resolves to ${m.realAssetPath}`,
+      ...m.pointers.map((p) => `  - referenced by ${p}`),
+    ]);
+    throw new Error(lines.join('\n'));
+  }
+
+  if (missing.length) {
+    missing.sort((a, b) => compareStrings(a.assetPath, b.assetPath));
+    const lines = missing.flatMap((m) => [
+      `Missing file: ${m.assetPath}`,
+      ...m.pointers.map((p) => `  - referenced by ${p}`),
+    ]);
+    throw new Error(lines.join('\n'));
+  }
+
+  return { assetCount: byPath.size };
+}