shipscreens 0.1.5 → 0.1.7

package/cli/commands/copyCheck.js

@@ -0,0 +1,265 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { loadShipScreensConfig } from '../loadConfig.js';
+
+const CJK_CHAR_RE = /[\u1100-\u11ff\u2e80-\u9fff\uf900-\ufaff\u3040-\u30ff\uac00-\ud7af]/;
+const ASCII_LETTER_RE = /[A-Za-z]/;
+const LETTER_RE = /\p{L}/u;
+const UPPER_RE = /[A-Z]/;
+const DIGIT_RE = /[0-9]/;
+const TOKEN_SPLIT_RE = /[\s/|,.;:!?()[\]{}<>]+/;
+
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+
+const toFiniteNumber = (value, fallback) => {
+  const num = Number(value);
+  if (!Number.isFinite(num)) return fallback;
+  return num;
+};
+
+const round2 = (value) => Math.round(value * 100) / 100;
+
+const truncate = (value, max = 96) => {
+  const text = String(value || '');
+  if (text.length <= max) return text;
+  return `${text.slice(0, max - 3)}...`;
+};
+
+function charUnits(ch) {
+  if (!ch) return 0;
+  if (/\s/.test(ch)) return 0.45;
+  if (CJK_CHAR_RE.test(ch)) return 1.8;
+  if (UPPER_RE.test(ch)) return 1.1;
+  if (DIGIT_RE.test(ch)) return 0.95;
+  return 1.0;
+}
+
+function estimateVisualUnits(value) {
+  const text = String(value || '');
+  let total = 0;
+  for (const ch of text) total += charUnits(ch);
+  return round2(total);
+}
+
+function pseudoLocalize(value, expansion) {
+  const text = String(value || '');
+  if (!text) return '';
+
+  let letterCount = 0;
+  let converted = '';
+  for (const ch of text) {
+    if (ASCII_LETTER_RE.test(ch)) {
+      letterCount += 1;
+      // Keep placeholder-like tokens readable while still stressing width.
+      converted += UPPER_RE.test(ch) ? `${ch}${ch.toLowerCase()}` : ch;
+      continue;
+    }
+    if (LETTER_RE.test(ch)) {
+      letterCount += 1;
+      // Duplicate non-ASCII letters to stress width in CJK/Arabic/Thai etc.
+      converted += `${ch}${ch}`;
+      continue;
+    }
+    converted += ch;
+  }
+
+  const pad = '~'.repeat(Math.ceil(letterCount * expansion));
+  return `[${converted}${pad}]`;
+}
+
+function buildPseudoCsv({ locales, slides }) {
+  const header = ['Locale'];
+  for (let i = 0; i < slides.length; i += 1) {
+    const index = i + 1;
+    header.push(`Header_${index}`);
+    header.push(`Subtitle_${index}`);
+  }
+
+  const escapeCell = (value) => {
+    const text = String(value ?? '');
+    if (/[",\n]/.test(text)) return `"${text.replace(/"/g, '""')}"`;
+    return text;
+  };
+
+  const rows = [header];
+  locales.forEach((locale) => {
+    const row = [locale.id];
+    locale.slides.forEach((slide) => {
+      row.push(slide.header || '');
+      row.push(slide.sub || '');
+    });
+    rows.push(row);
+  });
+
+  return `${rows.map((row) => row.map(escapeCell).join(',')).join('\n')}\n`;
+}
+
+function formatIssue({ type, slide, localeId, field, units, limit, detail }) {
+  return {
+    type,
+    severity: 'warn',
+    slide,
+    localeId,
+    field,
+    units: round2(units),
+    limit: round2(limit),
+    detail,
+  };
+}
+
+export async function runCopyCheck({
+  configPath,
+  pseudoLocale = 'qps-ploc',
+  pseudoExpand = 0.35,
+  maxHeaderUnits = 34,
+  maxSubUnits = 54,
+  maxTokenLength = 22,
+  writePseudoCsv,
+  writeReportJson,
+} = {}) {
+  const { config, configDir } = await loadShipScreensConfig(configPath);
+  const locales = Array.isArray(config.locales) ? config.locales : [];
+  const slides = Array.isArray(config.slides) ? config.slides : [];
+
+  const normalizedPseudoExpand = clamp(toFiniteNumber(pseudoExpand, 0.35), 0, 1.5);
+  const normalizedHeaderLimit = Math.max(10, toFiniteNumber(maxHeaderUnits, 34));
+  const normalizedSubLimit = Math.max(10, toFiniteNumber(maxSubUnits, 54));
+  const normalizedTokenLimit = Math.max(6, Math.floor(toFiniteNumber(maxTokenLength, 22)));
+
+  const issues = [];
+  const pseudoLocales = [];
+
+  locales.forEach((locale, localeIndex) => {
+    const localeId = String(locale?.id || `locale-${localeIndex + 1}`);
+    const pseudoLocaleId = `${pseudoLocale}-${localeId}`.replace(/[^A-Za-z0-9-]/g, '-');
+    const pseudoSlides = [];
+
+    slides.forEach((slide, slideIndex) => {
+      const text = slide?.text?.[localeId] || {};
+      const header = String(text.header || '');
+      const sub = String(text.sub || '');
+
+      const headerUnits = estimateVisualUnits(header);
+      if (headerUnits > normalizedHeaderLimit) {
+        issues.push(
+          formatIssue({
+            type: 'long_header',
+            slide: slideIndex + 1,
+            localeId,
+            field: 'header',
+            units: headerUnits,
+            limit: normalizedHeaderLimit,
+            detail: `Header likely too long (${headerUnits} > ${normalizedHeaderLimit} units): "${truncate(header)}"`,
+          })
+        );
+      }
+
+      const subUnits = estimateVisualUnits(sub);
+      if (subUnits > normalizedSubLimit) {
+        issues.push(
+          formatIssue({
+            type: 'long_sub',
+            slide: slideIndex + 1,
+            localeId,
+            field: 'sub',
+            units: subUnits,
+            limit: normalizedSubLimit,
+            detail: `Subtitle likely too long (${subUnits} > ${normalizedSubLimit} units): "${truncate(sub)}"`,
+          })
+        );
+      }
+
+      const pseudoHeader = pseudoLocalize(header, normalizedPseudoExpand);
+      const pseudoSub = pseudoLocalize(sub, normalizedPseudoExpand);
+      const pseudoHeaderUnits = estimateVisualUnits(pseudoHeader);
+      const pseudoSubUnits = estimateVisualUnits(pseudoSub);
+
+      if (pseudoHeaderUnits > normalizedHeaderLimit) {
+        issues.push(
+          formatIssue({
+            type: 'pseudo_header_overflow',
+            slide: slideIndex + 1,
+            localeId,
+            field: 'header',
+            units: pseudoHeaderUnits,
+            limit: normalizedHeaderLimit,
+            detail: `Pseudo-locale header overflow risk (${pseudoHeaderUnits} > ${normalizedHeaderLimit} units): "${truncate(
+              pseudoHeader
+            )}"`,
+          })
+        );
+      }
+      if (pseudoSubUnits > normalizedSubLimit) {
+        issues.push(
+          formatIssue({
+            type: 'pseudo_sub_overflow',
+            slide: slideIndex + 1,
+            localeId,
+            field: 'sub',
+            units: pseudoSubUnits,
+            limit: normalizedSubLimit,
+            detail: `Pseudo-locale subtitle overflow risk (${pseudoSubUnits} > ${normalizedSubLimit} units): "${truncate(
+              pseudoSub
+            )}"`,
+          })
+        );
+      }
+
+      const tokens = `${header} ${sub}`.split(TOKEN_SPLIT_RE).filter(Boolean);
+      const longToken = tokens.find((token) => token.length > normalizedTokenLimit);
+      if (longToken) {
+        issues.push(
+          formatIssue({
+            type: 'long_unbreakable_token',
+            slide: slideIndex + 1,
+            localeId,
+            field: 'header+sub',
+            units: longToken.length,
+            limit: normalizedTokenLimit,
+            detail: `Unbreakable token too long (${longToken.length} > ${normalizedTokenLimit}): "${truncate(longToken, 60)}"`,
+          })
+        );
+      }
+
+      pseudoSlides.push({ header: pseudoHeader, sub: pseudoSub });
+    });
+
+    pseudoLocales.push({ id: pseudoLocaleId, sourceLocale: localeId, slides: pseudoSlides });
+  });
+
+  let pseudoCsvPath = null;
+  if (writePseudoCsv) {
+    pseudoCsvPath = path.resolve(configDir, writePseudoCsv);
+    await fs.mkdir(path.dirname(pseudoCsvPath), { recursive: true });
+    const pseudoCsv = buildPseudoCsv({ locales: pseudoLocales, slides });
+    await fs.writeFile(pseudoCsvPath, pseudoCsv, 'utf8');
+  }
+
+  const result = {
+    configPath,
+    locales: locales.length,
+    slides: slides.length,
+    pseudoLocale,
+    pseudoExpand: normalizedPseudoExpand,
+    limits: {
+      headerUnits: normalizedHeaderLimit,
+      subUnits: normalizedSubLimit,
+      tokenLength: normalizedTokenLimit,
+    },
+    issueCount: issues.length,
+    issues,
+    pseudoCsvPath,
+  };
+
+  let reportJsonPath = null;
+  if (writeReportJson) {
+    reportJsonPath = path.resolve(configDir, writeReportJson);
+    await fs.mkdir(path.dirname(reportJsonPath), { recursive: true });
+    await fs.writeFile(reportJsonPath, `${JSON.stringify(result, null, 2)}\n`, 'utf8');
+  }
+
+  return {
+    ...result,
+    reportJsonPath,
+  };
+}

package/cli/commands/importScreenshots.js

@@ -0,0 +1,377 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { collectAssetReferences } from '../assetRefs.js';
+import { loadShipScreensConfig, resolveDefaultConfigPath } from '../loadConfig.js';
+import {
+  createSolidPng,
+  PLACEHOLDER_COLOR,
+  PLACEHOLDER_HEIGHT,
+  PLACEHOLDER_WIDTH,
+} from './init.js';
+import { runInspectReleaseContext } from './inspectReleaseContext.js';
+
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.webp']);
+const SKIP_DIRS = new Set(['.git', '.hg', '.svn', 'node_modules', '.next', '.nuxt', 'coverage']);
+const MAX_SCAN_DEPTH = 5;
+const DEFAULT_OUT_DIR = 'out/agent';
+
+function compareStrings(a, b) {
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+
+function toPosixPath(value) {
+  return String(value || '').replaceAll('\\', '/');
+}
+
+function relativeTo(baseDir, targetPath) {
+  const rel = path.relative(baseDir, targetPath);
+  return toPosixPath(rel || '.');
+}
+
+function shellQuote(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_./:=@+-]+$/.test(text)) return text;
+  return JSON.stringify(text);
+}
+
+function commandText(args) {
+  return ['shipscreens', ...args.map(shellQuote)].join(' ');
+}
+
+function createCommand({ id, label, args, reason, required = true }) {
+  return {
+    id,
+    label,
+    command: commandText(args),
+    args,
+    reason,
+    required,
+  };
+}
+
+async function statSafe(filePath) {
+  try {
+    return await fs.stat(filePath);
+  } catch (err) {
+    if (err?.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+async function resolveConfigCandidate({ targetDir, configPath }) {
+  if (configPath) {
+    return path.isAbsolute(configPath) ? configPath : path.resolve(targetDir, configPath);
+  }
+  const defaultConfig = await resolveDefaultConfigPath(targetDir);
+  return defaultConfig || path.join(targetDir, 'shipscreens.config.yml');
+}
+
+async function collectImages(rootDir) {
+  const rootStat = await statSafe(rootDir);
+  if (!rootStat) return [];
+  if (rootStat.isFile()) {
+    return IMAGE_EXTENSIONS.has(path.extname(rootDir).toLowerCase()) ? [rootDir] : [];
+  }
+  if (!rootStat.isDirectory()) return [];
+
+  const images = [];
+  const walk = async (dirPath, depth) => {
+    if (depth < 0) return;
+    const entries = (await fs.readdir(dirPath, { withFileTypes: true })).sort((a, b) =>
+      compareStrings(a.name, b.name)
+    );
+    for (const entry of entries) {
+      const childPath = path.join(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        await walk(childPath, depth - 1);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (IMAGE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+        images.push(childPath);
+      }
+    }
+  };
+
+  await walk(rootDir, MAX_SCAN_DEPTH);
+  return images.sort(compareStrings);
+}
+
+function normalizeLocale({ locale, locales }) {
+  const raw = String(locale || '').trim();
+  if (!raw) return locales[0];
+  if (raw.toLowerCase() === 'all') return 'all';
+  if (!locales.includes(raw)) {
+    throw new Error(`Unknown --locale value: ${raw}. Config locales: ${locales.join(', ')}`);
+  }
+  return raw;
+}
+
+function getSlideTargetPath({ slide, locale, primaryLocale }) {
+  if (locale === primaryLocale) {
+    return slide.screenshot?.path || null;
+  }
+  return slide.screenshotsByLocale?.[locale] || null;
+}
+
+function collectTargets({ config, locale }) {
+  const locales = (config.locales || []).map((item) => item.id).filter(Boolean);
+  if (!locales.length) throw new Error('Config must define at least one locale.');
+  const primaryLocale = locales[0];
+  const selectedLocale = normalizeLocale({ locale, locales });
+  const selectedLocales = selectedLocale === 'all' ? locales : [selectedLocale];
+
+  const targets = [];
+  const slides = Array.isArray(config.slides) ? config.slides : [];
+  selectedLocales.forEach((localeId) => {
+    slides.forEach((slide, index) => {
+      const assetPath = getSlideTargetPath({ slide, locale: localeId, primaryLocale });
+      if (!assetPath) return;
+      targets.push({
+        locale: localeId,
+        slideId: slide.id ?? index + 1,
+        index,
+        assetPath,
+      });
+    });
+  });
+
+  return { locales, primaryLocale, selectedLocale, selectedLocales, targets };
+}
+
+function buildAssetRefSet(config) {
+  return new Set(collectAssetReferences(config).map((ref) => ref.path));
+}
+
+function createPlaceholderBuffer() {
+  return createSolidPng({
+    width: PLACEHOLDER_WIDTH,
+    height: PLACEHOLDER_HEIGHT,
+    color: PLACEHOLDER_COLOR,
+  });
+}
+
+async function isPlaceholderPng(filePath, placeholderBuffer) {
+  const buffer = await fs.readFile(filePath);
+  return buffer.length === placeholderBuffer.length && buffer.equals(placeholderBuffer);
+}
+
+async function ensureOverwriteAllowed({ targetPath, force, placeholderBuffer }) {
+  const stat = await statSafe(targetPath);
+  if (!stat?.isFile()) {
+    return { exists: false, replacedPlaceholder: false };
+  }
+  if (force) {
+    return { exists: true, replacedPlaceholder: await isPlaceholderPng(targetPath, placeholderBuffer) };
+  }
+  if (await isPlaceholderPng(targetPath, placeholderBuffer)) {
+    return { exists: true, replacedPlaceholder: true };
+  }
+  throw new Error(`Refusing to overwrite non-placeholder image: ${targetPath}. Pass --force to overwrite.`);
+}
+
+async function chooseSourceRoot({ targetDir, configPath, fromDir }) {
+  if (fromDir) {
+    return path.isAbsolute(fromDir) ? fromDir : path.resolve(targetDir, fromDir);
+  }
+
+  const inspection = await runInspectReleaseContext({ dir: targetDir, configPath });
+  const candidate = (inspection.screenshotRoots || []).find(
+    (root) =>
+      root.exists &&
+      root.imageFiles > 0 &&
+      !['assets', 'config_ios_output', 'config_android_output'].includes(root.kind)
+  );
+  if (!candidate) {
+    throw new Error('No source screenshot root was detected. Pass --from <dir> to import screenshots.');
+  }
+  return candidate.path;
+}
+
+async function imagesForLocale({ sourceRoot, locale, selectedLocale }) {
+  if (selectedLocale === 'all') {
+    const localeDir = path.join(sourceRoot, locale);
+    const localeImages = await collectImages(localeDir);
+    if (localeImages.length) return { root: localeDir, images: localeImages, usedLocaleSubdir: true };
+  }
+  return { root: sourceRoot, images: await collectImages(sourceRoot), usedLocaleSubdir: false };
+}
+
+function defaultStageOutDir(outDir) {
+  const raw = String(outDir || DEFAULT_OUT_DIR).trim() || DEFAULT_OUT_DIR;
+  const trimmed = raw.replace(/[\\/]+$/, '');
+  return `${trimmed || DEFAULT_OUT_DIR}-stage`;
+}
+
+function buildNextCommands({ dir, configPath, profile, outDir, stageOutDir }) {
+  const dirArgs = dir ? ['--dir', dir] : [];
+  const configArgs = configPath ? ['--config', configPath] : [];
+  const normalizedProfile = profile || 'any';
+  const normalizedOutDir = outDir || DEFAULT_OUT_DIR;
+  const normalizedStageOutDir = stageOutDir || defaultStageOutDir(normalizedOutDir);
+
+  return [
+    createCommand({
+      id: 'validate_config',
+      label: 'Validate imported screenshot paths',
+      args: ['validate', ...configArgs],
+      reason: 'Fail fast if copied screenshots or config paths are missing.',
+    }),
+    createCommand({
+      id: 'plan_release',
+      label: 'Re-plan release run',
+      args: ['plan-release', ...dirArgs, ...configArgs, '--profile', normalizedProfile, '--json'],
+      reason: 'Confirm readiness and remaining blockers after import.',
+    }),
+    createCommand({
+      id: 'agent_run_stage_report',
+      label: 'Build, verify, stage, and report',
+      args: [
+        'agent-run',
+        ...dirArgs,
+        '--mode',
+        'raw',
+        '--zip',
+        '--out',
+        normalizedOutDir,
+        '--stage-out',
+        normalizedStageOutDir,
+        '--profile',
+        normalizedProfile,
+        '--json',
+      ],
+      reason: 'Produce release-safe outputs plus JSON/Markdown proof report for human review.',
+    }),
+  ];
+}
+
+export async function runImportScreenshots({
+  dir,
+  configPath,
+  fromDir,
+  locale,
+  profile,
+  outDir = DEFAULT_OUT_DIR,
+  stageOutDir,
+  force = false,
+  allowPartial = false,
+} = {}) {
+  const targetDir = path.resolve(process.cwd(), dir || '.');
+  const resolvedConfigPath = await resolveConfigCandidate({ targetDir, configPath });
+  const { config, configDir } = await loadShipScreensConfig(resolvedConfigPath);
+  const sourceRoot = await chooseSourceRoot({ targetDir, configPath: resolvedConfigPath, fromDir });
+  const sourceStat = await statSafe(sourceRoot);
+  if (!sourceStat) throw new Error(`Source screenshot path not found: ${sourceRoot}`);
+  if (!sourceStat.isDirectory() && !sourceStat.isFile()) {
+    throw new Error(`Source screenshot path must be a file or directory: ${sourceRoot}`);
+  }
+
+  const { selectedLocale, selectedLocales, targets } = collectTargets({ config, locale });
+  if (!targets.length) {
+    throw new Error('No config screenshot targets were found for the selected locale scope.');
+  }
+
+  const assetRefSet = buildAssetRefSet(config);
+  const placeholderBuffer = createPlaceholderBuffer();
+  const imported = [];
+  const warnings = [];
+  let totalAvailableImages = 0;
+
+  for (const localeId of selectedLocales) {
+    const localeTargets = targets.filter((target) => target.locale === localeId);
+    const { root, images, usedLocaleSubdir } = await imagesForLocale({ sourceRoot, locale: localeId, selectedLocale });
+    totalAvailableImages += images.length;
+    if (images.length < localeTargets.length && !allowPartial) {
+      throw new Error(
+        `Not enough source screenshots for ${localeId}: found ${images.length}, need ${localeTargets.length}. ` +
+          'Pass --allow-partial to copy what is available.'
+      );
+    }
+    if (selectedLocale === 'all' && !usedLocaleSubdir) {
+      warnings.push(`No ${localeId} subfolder found under --from; reused the root image sequence for ${localeId}.`);
+    }
+
+    const copyCount = Math.min(images.length, localeTargets.length);
+    for (let index = 0; index < copyCount; index += 1) {
+      const target = localeTargets[index];
+      if (!assetRefSet.has(target.assetPath)) continue;
+      const targetPath = path.resolve(configDir, target.assetPath);
+      const overwrite = await ensureOverwriteAllowed({
+        targetPath,
+        force,
+        placeholderBuffer,
+      });
+      await fs.mkdir(path.dirname(targetPath), { recursive: true });
+      await fs.copyFile(images[index], targetPath);
+      imported.push({
+        locale: localeId,
+        slideId: target.slideId,
+        sourcePath: images[index],
+        sourceRelativePath: relativeTo(targetDir, images[index]),
+        targetPath,
+        targetRelativePath: relativeTo(targetDir, targetPath),
+        sourceRoot: root,
+        overwritten: overwrite.exists,
+        replacedPlaceholder: overwrite.replacedPlaceholder,
+      });
+    }
+  }
+
+  const skippedTargets = targets.length - imported.length;
+  if (skippedTargets > 0) {
+    warnings.push(`${skippedTargets} screenshot target(s) were not imported.`);
+  }
+
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    workspace: targetDir,
+    configPath: resolvedConfigPath,
+    sourceRoot,
+    sourceRootRelativePath: relativeTo(targetDir, sourceRoot),
+    selectedLocale,
+    selectedLocales,
+    force: Boolean(force),
+    allowPartial: Boolean(allowPartial),
+    counts: {
+      availableImages: totalAvailableImages,
+      targets: targets.length,
+      imported: imported.length,
+      skippedTargets,
+    },
+    imported,
+    warnings: [...new Set(warnings)],
+    nextCommands: buildNextCommands({
+      dir,
+      configPath: configPath || (dir ? resolvedConfigPath : relativeTo(targetDir, resolvedConfigPath)),
+      profile,
+      outDir,
+      stageOutDir,
+    }),
+  };
+}
+
+export function renderImportScreenshotsSummary(result) {
+  const lines = [
+    'ShipScreens screenshot import',
+    `- Workspace: ${result.workspace}`,
+    `- Config: ${relativeTo(result.workspace, result.configPath)}`,
+    `- Source: ${result.sourceRootRelativePath}`,
+    `- Locale scope: ${result.selectedLocale}`,
+    `- Imported: ${result.counts.imported}/${result.counts.targets}`,
+    '',
+    'Imported files:',
+    ...(result.imported.length
+      ? result.imported.map((item) => `- ${item.sourceRelativePath} -> ${item.targetRelativePath}`)
+      : ['- none']),
+    '',
+    'Warnings:',
+    ...(result.warnings.length ? result.warnings.map((item) => `- ${item}`) : ['- none']),
+    '',
+    'Next commands:',
+    ...result.nextCommands.map((cmd, idx) => `${idx + 1}. ${cmd.command}`),
+  ];
+  return `${lines.join('\n')}\n`;
+}