shipscreens 0.1.6 → 0.1.7

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`;
+}