shipscreens 0.1.6 → 0.1.7

package/cli/commands/captureScreenshots.js

@@ -0,0 +1,409 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+const DEFAULT_OUT_DIR = 'screenshots';
+const CAPTURE_PLATFORMS = new Set(['auto', 'android', 'ios-simulator', 'ios-device']);
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+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,
+  };
+}
+
+function normalizePlatform(platform) {
+  const value = String(platform || 'auto').trim().toLowerCase();
+  if (!CAPTURE_PLATFORMS.has(value)) {
+    throw new Error(`Unknown --platform value: ${value}. Expected auto|android|ios-simulator|ios-device.`);
+  }
+  return value;
+}
+
+function normalizeLocale(locale) {
+  const value = String(locale || '').trim();
+  if (!value) return null;
+  if (!/^[A-Za-z0-9_.-]+$/.test(value)) {
+    throw new Error(`Invalid --locale value: ${value}`);
+  }
+  return value;
+}
+
+function normalizeSlot(slot) {
+  if (slot === undefined || slot === null || slot === '') return null;
+  const value = Number(slot);
+  if (!Number.isInteger(value) || value < 1 || value > 99) {
+    throw new Error(`Invalid --slot value: ${slot}. Expected an integer from 1 to 99.`);
+  }
+  return value;
+}
+
+function sanitizeFileName(name) {
+  const value = String(name || '').trim();
+  if (!value) return '';
+  const cleaned = value.replace(/[^A-Za-z0-9_.-]+/g, '-').replace(/^-+|-+$/g, '');
+  if (!cleaned) throw new Error(`Invalid --name value: ${name}`);
+  return path.extname(cleaned).toLowerCase() === '.png' ? cleaned : `${cleaned}.png`;
+}
+
+function timestampName(date = new Date()) {
+  const pad = (value) => String(value).padStart(2, '0');
+  return (
+    `${date.getFullYear()}` +
+    `${pad(date.getMonth() + 1)}` +
+    `${pad(date.getDate())}` +
+    `-${pad(date.getHours())}` +
+    `${pad(date.getMinutes())}` +
+    `${pad(date.getSeconds())}.png`
+  );
+}
+
+function resolveCapturePath({ targetDir, outDir, locale, name, slot }) {
+  const root = path.resolve(targetDir, outDir || DEFAULT_OUT_DIR);
+  const outputDir = locale ? path.join(root, locale) : root;
+  const fileName = sanitizeFileName(name) || (slot ? `${String(slot).padStart(2, '0')}.png` : timestampName());
+  return {
+    root,
+    outputDir,
+    outputPath: path.join(outputDir, fileName),
+  };
+}
+
+function resolveCommandSpec(command, envKey) {
+  const raw = String(process.env[envKey] || '').trim();
+  if (!raw) return { command, prefixArgs: [] };
+  if (raw.startsWith('[')) {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+      throw new Error(`${envKey} must be a JSON array with at least one command item.`);
+    }
+    return { command: String(parsed[0]), prefixArgs: parsed.slice(1).map(String) };
+  }
+  return { command: raw, prefixArgs: [] };
+}
+
+async function commandTextOutput(command, args, envKey) {
+  const spec = resolveCommandSpec(command, envKey);
+  const { stdout } = await execFileAsync(spec.command, [...spec.prefixArgs, ...args], {
+    encoding: 'utf8',
+    windowsHide: true,
+    maxBuffer: 2 * 1024 * 1024,
+  });
+  return String(stdout || '');
+}
+
+async function commandBufferOutput(command, args, envKey) {
+  const spec = resolveCommandSpec(command, envKey);
+  const { stdout } = await execFileAsync(spec.command, [...spec.prefixArgs, ...args], {
+    encoding: 'buffer',
+    windowsHide: true,
+    maxBuffer: 25 * 1024 * 1024,
+  });
+  return Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout || '');
+}
+
+async function listAndroidDevices(warnings) {
+  try {
+    const stdout = await commandTextOutput('adb', ['devices'], 'SHIPSCREENS_ADB_COMMAND');
+    return stdout
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line && !line.toLowerCase().startsWith('list of devices'))
+      .map((line) => {
+        const [serial, status] = line.split(/\s+/);
+        return { id: serial, status: status || 'unknown', provider: 'adb' };
+      })
+      .filter((device) => device.id && device.status === 'device')
+      .sort((a, b) => compareStrings(a.id, b.id));
+  } catch (err) {
+    warnings.push(`adb not available or no Android device list could be read: ${err?.message || String(err)}`);
+    return [];
+  }
+}
+
+async function listIosSimulators(warnings) {
+  try {
+    const stdout = await commandTextOutput('xcrun', ['simctl', 'list', 'devices', 'booted'], 'SHIPSCREENS_XCRUN_COMMAND');
+    return stdout
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .map((line) => {
+        const match = line.match(/^(.+?)\s+\(([0-9A-Fa-f-]+)\)\s+\(Booted\)/);
+        if (!match) return null;
+        return { id: match[2], name: match[1].trim(), status: 'booted', provider: 'xcrun simctl' };
+      })
+      .filter(Boolean)
+      .sort((a, b) => compareStrings(a.name, b.name));
+  } catch (err) {
+    warnings.push(`xcrun simctl not available or no booted iOS simulator could be read: ${err?.message || String(err)}`);
+    return [];
+  }
+}
+
+async function listIosDevices(warnings) {
+  try {
+    const stdout = await commandTextOutput('idevice_id', ['-l'], 'SHIPSCREENS_IDEVICE_ID_COMMAND');
+    return stdout
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((id) => ({ id, status: 'connected', provider: 'libimobiledevice' }))
+      .sort((a, b) => compareStrings(a.id, b.id));
+  } catch (err) {
+    warnings.push(`idevice_id not available or no iOS device list could be read: ${err?.message || String(err)}`);
+    return [];
+  }
+}
+
+async function listCaptureDevices() {
+  const warnings = [];
+  const [android, iosSimulators, iosDevices] = await Promise.all([
+    listAndroidDevices(warnings),
+    listIosSimulators(warnings),
+    listIosDevices(warnings),
+  ]);
+  return {
+    android,
+    iosSimulators,
+    iosDevices,
+    warnings,
+  };
+}
+
+async function captureAndroid({ device, outputPath }) {
+  const args = [];
+  if (device) args.push('-s', device);
+  args.push('exec-out', 'screencap', '-p');
+  const png = await commandBufferOutput('adb', args, 'SHIPSCREENS_ADB_COMMAND');
+  if (!png.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)) {
+    throw new Error('adb screencap did not return PNG data.');
+  }
+  await fs.writeFile(outputPath, png);
+  return {
+    provider: 'adb',
+    device: device || null,
+    rawCommand: ['adb', ...args].join(' '),
+  };
+}
+
+async function captureIosSimulator({ device, outputPath }) {
+  const target = device || 'booted';
+  const args = ['simctl', 'io', target, 'screenshot', outputPath];
+  await commandTextOutput('xcrun', args, 'SHIPSCREENS_XCRUN_COMMAND');
+  return {
+    provider: 'xcrun simctl',
+    device: target,
+    rawCommand: ['xcrun', ...args].join(' '),
+  };
+}
+
+async function captureIosDevice({ device, outputPath }) {
+  const args = [];
+  if (device) args.push('-u', device);
+  args.push(outputPath);
+  await commandTextOutput('idevicescreenshot', args, 'SHIPSCREENS_IDEVICESCREENSHOT_COMMAND');
+  return {
+    provider: 'libimobiledevice',
+    device: device || null,
+    rawCommand: ['idevicescreenshot', ...args].join(' '),
+  };
+}
+
+function buildNextCommands({ dir, outRoot, locale, profile }) {
+  const dirArgs = dir ? ['--dir', dir] : [];
+  const profileValue = profile || 'any';
+  const importArgs = ['import-screenshots', ...dirArgs, '--from', outRoot, '--profile', profileValue, '--json'];
+  if (locale) importArgs.push('--locale', locale);
+
+  return [
+    createCommand({
+      id: 'import_screenshots',
+      label: 'Import captured screenshots into config asset paths',
+      args: importArgs,
+      reason: 'Use the captured device/emulator PNG sequence as ShipScreens source screenshots.',
+    }),
+    createCommand({
+      id: 'plan_release',
+      label: 'Re-plan release run',
+      args: ['plan-release', ...dirArgs, '--profile', profileValue, '--json'],
+      reason: 'Confirm remaining blockers before build/verify/stage.',
+    }),
+  ];
+}
+
+async function chooseAutoPlatform({ device, devices }) {
+  if (device) {
+    const androidMatch = devices.android.find((item) => item.id === device);
+    if (androidMatch) return { platform: 'android', device };
+    const simMatch = devices.iosSimulators.find((item) => item.id === device || item.name === device);
+    if (simMatch) return { platform: 'ios-simulator', device };
+    const iosDeviceMatch = devices.iosDevices.find((item) => item.id === device);
+    if (iosDeviceMatch) return { platform: 'ios-device', device };
+  }
+  if (devices.android.length) return { platform: 'android', device: devices.android[0].id };
+  if (devices.iosSimulators.length) return { platform: 'ios-simulator', device: devices.iosSimulators[0].id };
+  if (devices.iosDevices.length) return { platform: 'ios-device', device: devices.iosDevices[0].id };
+  throw new Error(
+    'No connected Android device/emulator, booted iOS simulator, or libimobiledevice iOS device was detected. ' +
+      'Open the app screen first, then connect adb/xcrun/idevicescreenshot or pass --from to import-screenshots.'
+  );
+}
+
+export async function runCaptureScreenshots({
+  dir,
+  platform,
+  device,
+  outDir = DEFAULT_OUT_DIR,
+  name,
+  slot,
+  locale,
+  profile,
+  list = false,
+} = {}) {
+  const targetDir = path.resolve(process.cwd(), dir || '.');
+  const normalizedPlatform = normalizePlatform(platform);
+  const normalizedLocale = normalizeLocale(locale);
+  const normalizedSlot = normalizeSlot(slot);
+
+  if (list) {
+    const devices = await listCaptureDevices();
+    return {
+      version: 1,
+      generatedAt: new Date().toISOString(),
+      workspace: targetDir,
+      platform: normalizedPlatform,
+      devices,
+      warnings: devices.warnings,
+    };
+  }
+
+  const { root, outputDir, outputPath } = resolveCapturePath({
+    targetDir,
+    outDir,
+    locale: normalizedLocale,
+    name,
+    slot: normalizedSlot,
+  });
+  await fs.mkdir(outputDir, { recursive: true });
+
+  const warnings = [];
+  let selectedPlatform = normalizedPlatform;
+  let selectedDevice = device || null;
+  if (normalizedPlatform === 'auto') {
+    const devices = await listCaptureDevices();
+    warnings.push(...devices.warnings);
+    const selected = await chooseAutoPlatform({ device: selectedDevice, devices });
+    selectedPlatform = selected.platform;
+    selectedDevice = selected.device;
+  }
+
+  let capture;
+  if (selectedPlatform === 'android') {
+    capture = await captureAndroid({ device: selectedDevice, outputPath });
+  } else if (selectedPlatform === 'ios-simulator') {
+    capture = await captureIosSimulator({ device: selectedDevice, outputPath });
+  } else if (selectedPlatform === 'ios-device') {
+    capture = await captureIosDevice({ device: selectedDevice, outputPath });
+  } else {
+    throw new Error(`Unsupported capture platform: ${selectedPlatform}`);
+  }
+
+  const stat = await fs.stat(outputPath);
+  if (!stat.isFile() || stat.size <= 0) {
+    throw new Error(`Capture did not write a non-empty PNG: ${outputPath}`);
+  }
+
+  warnings.push(
+    'Captured only the currently visible screen. Repeat with --slot 01, --slot 02, ... after navigating the app for each store panel.'
+  );
+
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    workspace: targetDir,
+    platform: selectedPlatform,
+    requestedPlatform: normalizedPlatform,
+    provider: capture.provider,
+    device: capture.device,
+    outputRoot: root,
+    outputRootRelativePath: relativeTo(targetDir, root),
+    outputPath,
+    outputRelativePath: relativeTo(targetDir, outputPath),
+    bytes: stat.size,
+    locale: normalizedLocale,
+    slot: normalizedSlot,
+    rawCommand: capture.rawCommand,
+    warnings: [...new Set(warnings)],
+    nextCommands: buildNextCommands({
+      dir,
+      outRoot: relativeTo(targetDir, root),
+      locale: normalizedLocale,
+      profile,
+    }),
+  };
+}
+
+export function renderCaptureScreenshotsSummary(result) {
+  if (result.devices) {
+    const lines = [
+      'ShipScreens capture devices',
+      `- Workspace: ${result.workspace}`,
+      `- Android devices: ${result.devices.android.map((item) => item.id).join(', ') || 'none'}`,
+      `- iOS simulators: ${result.devices.iosSimulators.map((item) => `${item.name} (${item.id})`).join(', ') || 'none'}`,
+      `- iOS devices: ${result.devices.iosDevices.map((item) => item.id).join(', ') || 'none'}`,
+      '',
+      'Warnings:',
+      ...(result.warnings.length ? result.warnings.map((item) => `- ${item}`) : ['- none']),
+    ];
+    return `${lines.join('\n')}\n`;
+  }
+
+  const lines = [
+    'ShipScreens screenshot capture',
+    `- Workspace: ${result.workspace}`,
+    `- Platform: ${result.platform}`,
+    `- Provider: ${result.provider}`,
+    `- Device: ${result.device || 'default'}`,
+    `- Output: ${result.outputRelativePath}`,
+    `- Bytes: ${result.bytes}`,
+    '',
+    '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`;
+}