shipscreens 0.1.0

package/cli/commands/exportFramefile.js

@@ -0,0 +1,404 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { runValidate } from './validate.js';
+import { loadShipScreensConfig } from '../loadConfig.js';
+import { formatScreenshotIndex, getScreenshotIndexWidth } from '../buildOutputs.js';
+
+function compareStrings(a, b) {
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+
+async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+async function removeFileSafe(filePath) {
+  try {
+    await fs.unlink(filePath);
+  } catch (err) {
+    if (err?.code === 'ENOENT') return;
+    throw err;
+  }
+}
+
+async function readJsonObjectFile(filePath) {
+  let content;
+  try {
+    content = await fs.readFile(filePath, 'utf8');
+  } catch (err) {
+    if (err?.code === 'ENOENT') return null;
+    throw err;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    throw new Error(`Invalid JSON: ${filePath}`);
+  }
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`Expected a JSON object: ${filePath}`);
+  }
+
+  return parsed;
+}
+
+async function removeLegacyLocaleFramefile({ localeDir, deviceTypes, useKeywords }) {
+  const legacyPath = path.join(localeDir, 'Framefile.json');
+  const parsed = await readJsonObjectFile(legacyPath).catch(() => null);
+  if (!parsed) return;
+
+  const keys = Object.keys(parsed).sort(compareStrings);
+  const isLegacy =
+    keys.length === 3 &&
+    keys[0] === 'device_types' &&
+    keys[1] === 'use_keywords' &&
+    keys[2] === 'use_title' &&
+    Array.isArray(parsed.device_types) &&
+    typeof parsed.use_keywords === 'boolean' &&
+    typeof parsed.use_title === 'boolean';
+
+  if (!isLegacy) return;
+  if (parsed.use_title !== true) return;
+  if (parsed.use_keywords !== useKeywords) return;
+  if (parsed.device_types.length !== deviceTypes.length) return;
+  for (let i = 0; i < deviceTypes.length; i++) {
+    if (parsed.device_types[i] !== deviceTypes[i]) return;
+  }
+
+  await removeFileSafe(legacyPath);
+}
+
+function resolveOutputDir({ configDir, value, fallback }) {
+  const raw = String(value || fallback || '').trim();
+  if (!raw) throw new Error('Output directory is required');
+  return path.resolve(configDir, raw);
+}
+
+function toDeviceSlug(deviceId) {
+  return String(deviceId).toLowerCase();
+}
+
+function escapeStringsValue(value) {
+  return String(value ?? '')
+    .replaceAll('\\', '\\\\')
+    .replaceAll('"', '\\"')
+    .replaceAll('\r\n', '\n')
+    .replaceAll('\r', '\n')
+    .replaceAll('\t', '\\t')
+    .replaceAll('\n', '\\n');
+}
+
+function serializeStrings(map) {
+  const keys = [...map.keys()].sort(compareStrings);
+  const lines = keys.map((key) => `"${escapeStringsValue(key)}" = "${escapeStringsValue(map.get(key))}";`);
+  return `\n${lines.join('\n')}\n`;
+}
+
+function serializeJson(obj) {
+  return `${JSON.stringify(obj, null, 2)}\n`;
+}
+
+function swapUtf16Endianness(buffer) {
+  for (let i = 0; i + 1 < buffer.length; i += 2) {
+    const a = buffer[i];
+    buffer[i] = buffer[i + 1];
+    buffer[i + 1] = a;
+  }
+}
+
+function decodeStringsFile(buffer) {
+  if (!Buffer.isBuffer(buffer)) {
+    throw new Error('Expected a Buffer');
+  }
+
+  if (buffer.length >= 2 && buffer[0] === 0xff && buffer[1] === 0xfe) {
+    return buffer.toString('utf16le');
+  }
+
+  if (buffer.length >= 2 && buffer[0] === 0xfe && buffer[1] === 0xff) {
+    const copy = Buffer.from(buffer);
+    swapUtf16Endianness(copy);
+    return copy.toString('utf16le');
+  }
+
+  if (buffer.length >= 3 && buffer[0] === 0xef && buffer[1] === 0xbb && buffer[2] === 0xbf) {
+    return buffer.toString('utf8');
+  }
+
+  return buffer.toString('utf8');
+}
+
+function stripBom(value) {
+  const str = String(value ?? '');
+  return str.startsWith('\ufeff') ? str.slice(1) : str;
+}
+
+function unescapeStringsToken(value) {
+  return String(value ?? '').replace(/\\(.)/g, (_match, ch) => {
+    if (ch === 'n') return '\n';
+    if (ch === 'r') return '\r';
+    if (ch === 't') return '\t';
+    if (ch === '"') return '"';
+    if (ch === '\\') return '\\';
+    return ch;
+  });
+}
+
+function parseStringsFileContent(content, { filePath }) {
+  const normalized = stripBom(content);
+  if (!normalized.startsWith('\n') && !normalized.startsWith('\r\n')) {
+    throw new Error(`.strings must start with a blank line: ${filePath}`);
+  }
+
+  const map = new Map();
+  const re = /"((?:\\.|[^"\\])*)"\s*=\s*"((?:\\.|[^"\\])*)";/g;
+  let match;
+  while ((match = re.exec(normalized))) {
+    const key = unescapeStringsToken(match[1]);
+    const value = unescapeStringsToken(match[2]);
+    map.set(key, value);
+  }
+
+  return map;
+}
+
+function encodeStringsFileContent(content, encoding) {
+  const normalized = String(encoding || 'utf8')
+    .trim()
+    .toLowerCase();
+
+  if (normalized === 'utf8') {
+    return { data: content, encoding: 'utf8' };
+  }
+
+  if (normalized === 'utf16le') {
+    const withBom = `\ufeff${content}`;
+    return { data: Buffer.from(withBom, 'utf16le') };
+  }
+
+  if (normalized === 'utf16be') {
+    const withBom = `\ufeff${content}`;
+    const buf = Buffer.from(withBom, 'utf16le');
+    swapUtf16Endianness(buf);
+    return { data: buf };
+  }
+
+  throw new Error(`Unsupported strings encoding: ${normalized} (expected: utf8|utf16le|utf16be)`);
+}
+
+async function writeStringsFile(filePath, content, encoding) {
+  const encoded = encodeStringsFileContent(content, encoding);
+  if (typeof encoded.data === 'string') {
+    await fs.writeFile(filePath, encoded.data, encoded.encoding || 'utf8');
+    return;
+  }
+  await fs.writeFile(filePath, encoded.data);
+}
+
+function addMapping(map, key, value) {
+  if (!key) return;
+  map.set(String(key), String(value ?? ''));
+}
+
+function collectStringsMappings({ config, localeId, iosDevices, width, field }) {
+  const map = new Map();
+  const slideCount = config.slides.length;
+
+  for (let index = 1; index <= slideCount; index++) {
+    const slide = config.slides[index - 1];
+    const text = slide?.text?.[localeId] || { header: '', sub: '' };
+    const value = String(text?.[field] ?? '');
+    const padded = formatScreenshotIndex(index, width);
+
+    // Generic index keys (some tools use numeric indices)
+    addMapping(map, String(index), value);
+    addMapping(map, padded, value);
+
+    // Filename-like keys without extensions (some tools key off basename)
+    addMapping(map, `${index}.png`, value);
+    addMapping(map, `${padded}.png`, value);
+
+    // Device-prefixed keys (ShipScreens output uses <device>_<index>.png)
+    for (const device of iosDevices) {
+      const slug = toDeviceSlug(device.id);
+      addMapping(map, `${slug}_${index}`, value);
+      addMapping(map, `${slug}_${padded}`, value);
+      addMapping(map, `${slug}_${index}.png`, value);
+      addMapping(map, `${slug}_${padded}.png`, value);
+    }
+  }
+
+  return map;
+}
+
+function collectTitleCandidateKeysForIndex({ index, padded, iosDevices }) {
+  const keys = [String(index), padded, `${index}.png`, `${padded}.png`];
+  for (const device of iosDevices || []) {
+    const slug = toDeviceSlug(device.id);
+    keys.push(`${slug}_${index}`, `${slug}_${padded}`, `${slug}_${index}.png`, `${slug}_${padded}.png`);
+  }
+  return keys;
+}
+
+async function checkFrameitInputs({ rootFramefilePath, localeDir, localeId, slideCount, width, iosDevices }) {
+  const titlePath = path.join(localeDir, 'title.strings');
+  let titleBuf;
+  try {
+    titleBuf = await fs.readFile(titlePath);
+  } catch (err) {
+    if (err?.code === 'ENOENT') {
+      throw new Error(`Missing title.strings: ${titlePath}\nRun: shipscreens export framefile`);
+    }
+    throw err;
+  }
+
+  const decoded = decodeStringsFile(titleBuf);
+  const titleMap = parseStringsFileContent(decoded, { filePath: titlePath });
+
+  const missing = [];
+  for (let index = 1; index <= slideCount; index++) {
+    const padded = formatScreenshotIndex(index, width);
+    const candidates = collectTitleCandidateKeysForIndex({ index, padded, iosDevices });
+    const ok = candidates.some((key) => {
+      const value = titleMap.get(key);
+      return typeof value === 'string' && value.trim().length > 0;
+    });
+    if (!ok) missing.push(padded);
+  }
+
+  if (missing.length) {
+    const max = 20;
+    const shown = missing.slice(0, max).join(', ');
+    const suffix = missing.length > max ? ', …' : '';
+    throw new Error(
+      `title.strings is missing titles for ${missing.length} slide(s) (${localeId}): ${shown}${suffix}\n` +
+        `Expected a non-empty title for each slide index.\n` +
+        `Run: shipscreens export framefile`
+    );
+  }
+
+  return { checked: true };
+}
+
+export async function runExportFramefile({
+  configPath,
+  iosDir,
+  stringsEncoding,
+  framefileStrategy,
+  check = false,
+} = {}) {
+  await runValidate({ configPath });
+  const { config, configDir } = await loadShipScreensConfig(configPath);
+
+  const resolvedIosDir = resolveOutputDir({
+    configDir,
+    value: iosDir || config.output?.directory,
+    fallback: 'fastlane/screenshots',
+  });
+
+  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 devices = Array.isArray(config.devices) ? config.devices : [];
+  const iosDevices = devices.filter((d) => d.platform !== 'android');
+  if (!iosDevices.length) {
+    throw new Error('No iOS devices configured. Add at least one iOS device 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 deviceTypes = iosDevices
+    .map((d) => String(d.label || d.id))
+    .filter((v) => v.trim().length > 0);
+  deviceTypes.sort(compareStrings);
+
+  const anyKeywords = config.slides.some((s) =>
+    locales.some((localeId) => String(s?.text?.[localeId]?.sub ?? '').trim().length > 0)
+  );
+
+  const normalizedStrategy = String(framefileStrategy || 'merge')
+    .trim()
+    .toLowerCase();
+  if (!['merge', 'overwrite'].includes(normalizedStrategy)) {
+    throw new Error(`Unsupported framefile strategy: ${normalizedStrategy} (expected: merge|overwrite)`);
+  }
+
+  const rootFramefilePath = path.join(resolvedIosDir, 'Framefile.json');
+
+  if (check) {
+    const existingFramefile = await readJsonObjectFile(rootFramefilePath);
+    if (!existingFramefile) {
+      throw new Error(`Framefile.json missing: ${rootFramefilePath}\nRun: shipscreens export framefile`);
+    }
+
+    const defaultSection = existingFramefile?.default;
+    const defaultBackground =
+      defaultSection && typeof defaultSection === 'object' && !Array.isArray(defaultSection)
+        ? String(defaultSection.background || '').trim()
+        : '';
+    if (!defaultBackground) {
+      throw new Error(
+        `Framefile.json default.background is not set: ${rootFramefilePath}\n` +
+          `frameit requires a background to render titles/keywords.\n` +
+          `Set default.background, or run without --check.`
+      );
+    }
+
+    for (const localeId of locales) {
+      const localeDir = path.join(resolvedIosDir, localeId);
+      await checkFrameitInputs({ rootFramefilePath, localeDir, localeId, slideCount, width, iosDevices });
+    }
+
+    return { iosDir: resolvedIosDir, locales: locales.length, checked: true };
+  }
+
+  await ensureDir(resolvedIosDir);
+  let activeFramefile = await readJsonObjectFile(rootFramefilePath);
+  if (normalizedStrategy === 'overwrite' || !activeFramefile) {
+    const framefile = { default: {}, data: [] };
+    await fs.writeFile(rootFramefilePath, serializeJson(framefile), 'utf8');
+    activeFramefile = framefile;
+  }
+  const defaultSection = activeFramefile?.default;
+  const defaultBackground =
+    defaultSection && typeof defaultSection === 'object' && !Array.isArray(defaultSection)
+      ? String(defaultSection.background || '').trim()
+      : '';
+  if (!defaultBackground) {
+    console.error(
+      `Warning: Framefile.json default.background is not set.\n` +
+        `frameit requires a background to render titles/keywords.\n` +
+        `Set it in: ${rootFramefilePath}`
+    );
+  }
+
+  for (const localeId of locales) {
+    const localeDir = path.join(resolvedIosDir, localeId);
+    await ensureDir(localeDir);
+
+    const localeHasKeywords = config.slides.some((s) => String(s?.text?.[localeId]?.sub ?? '').trim().length > 0);
+    await removeLegacyLocaleFramefile({ localeDir, deviceTypes, useKeywords: localeHasKeywords });
+
+    const titleMap = collectStringsMappings({ config, localeId, iosDevices, width, field: 'header' });
+    await writeStringsFile(path.join(localeDir, 'title.strings'), serializeStrings(titleMap), stringsEncoding);
+
+    if (anyKeywords) {
+      const keywordMap = collectStringsMappings({ config, localeId, iosDevices, width, field: 'sub' });
+      await writeStringsFile(path.join(localeDir, 'keyword.strings'), serializeStrings(keywordMap), stringsEncoding);
+    } else {
+      await removeFileSafe(path.join(localeDir, 'keyword.strings'));
+    }
+  }
+
+  return { iosDir: resolvedIosDir, locales: locales.length, checked: false };
+}