shipscreens 0.1.0

package/bin/shipscreens.js

@@ -0,0 +1,664 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { resolveDefaultConfigPath } from '../cli/loadConfig.js';
+import { runValidate } from '../cli/commands/validate.js';
+import { runLock } from '../cli/commands/lock.js';
+import { runBuild } from '../cli/commands/build.js';
+import { runExportFramefile } from '../cli/commands/exportFramefile.js';
+import { runVerify } from '../cli/commands/verify.js';
+import { runStage } from '../cli/commands/stage.js';
+import { runPlan } from '../cli/commands/plan.js';
+import { runAuth } from '../cli/commands/auth.js';
+import { runInit } from '../cli/commands/init.js';
+import { runWizard } from '../cli/commands/wizard.js';
+import { runCopyImport } from '../cli/commands/copyImport.js';
+import { resolveCliAuth } from '../cli/auth.js';
+import { listTemplateIds, resolveTemplateConfig } from '../cli/templateConfig.js';
+import { loadShipScreensConfig } from '../cli/loadConfig.js';
+import { collectAssetReferences } from '../cli/assetRefs.js';
+import {
+  createSolidPng,
+  PLACEHOLDER_COLOR,
+  PLACEHOLDER_HEIGHT,
+  PLACEHOLDER_WIDTH,
+} from '../cli/commands/init.js';
+
+function printHelp() {
+  console.log(`ShipScreens CLI
+
+Usage:
+  shipscreens init [--dir <path>] [--slides <n>] [--locales <id,id>] [--devices <id,id>] [--force] [--wizard] [--style <value>] [--template <id>]
+  shipscreens wizard [--dir <path>] [--force] [--style <value>] [--template <id>] [--defaults]
+  shipscreens demo [--out <dir>] [--slides <n>] [--locales <id,id>] [--devices <id,id>] [--template <id>] [--mode <raw|rendered>] [--zip-out <path>] [--profile <appstore|playstore|any>] [--force]
+  shipscreens agent-run [--dir <path>] [--slides <n>] [--locales <id,id>] [--devices <id,id>] [--style <value>] [--template <id>] [--mode <raw|rendered>] [--out <dir>] [--zip] [--profile <appstore|playstore|any>] [--require-pro] [--force]
+  shipscreens validate [-c shipscreens.config.yml]
+  shipscreens lock [-c shipscreens.config.yml] [--out shipscreens.lock.json] [--check]
+  shipscreens build [-c shipscreens.config.yml] [--mode shipscreens|rendered|raw|frameit] [--format dir|zip] [--out <dir>] [--zip] [--zip-out <path>] [--clean]
+  shipscreens verify [-c shipscreens.config.yml] [--out <dir>] [--zip] [--zip-out <path>] [--profile appstore|playstore|any]
+  shipscreens stage [-c shipscreens.config.yml] [--from <dir>] --out <dir> [--profile appstore|playstore|any]
+  shipscreens export framefile [-c shipscreens.config.yml] [--ios-dir fastlane/screenshots] [--strings-encoding utf8|utf16le|utf16be] [--framefile-strategy merge|overwrite] [--check]
+  shipscreens plan [-c shipscreens.config.yml] [--out <dir>] [--zip-out <path>] [--profile appstore|playstore|any] [--json]
+  shipscreens copy import [-c shipscreens.config.yml] [--csv <path>] [--import-mode merge|replace]
+  shipscreens auth <login|finish|status|logout> [--domain <cognito-domain>] [--client-id <id>] [--api-base <url>] [--port <port>] [--manual] [--redirect-url <url>]
+
+Commands:
+  init       Create a starter config + placeholder PNGs + copy.csv
+  wizard     Step-by-step setup (locales/devices/template)
+  demo       Create a demo project + export (no assets required)
+  agent-run  Non-interactive end-to-end flow (init -> validate -> build -> verify)
+  validate   Validate shipscreens.config.yml (schema + asset paths)
+  lock       Generate shipscreens.lock.json with sha256 hashes
+  build      Generate Fastlane-ready outputs (headless Chromium, zero-padded filenames)
+  verify     Verify Fastlane outputs (dir and/or zip)
+  stage      Copy only upload-ready files into a new root
+  export     Export helper files for other tools
+  plan       Print a deterministic build/stage plan (JSON)
+  copy       Import locale copy from copy.csv into shipscreens.config.yml
+  auth       Manage CLI sign-in (required to remove watermarks in CLI exports)
+
+Options:
+  -c, --config <path>   Path to shipscreens.config.yml (default: ./shipscreens.config.yml)
+  --dir <path>          Output directory for init (default: .)
+  --slides <n>          Number of slides to scaffold (init, default: 5, max: 10)
+  --locales <list>      Comma-separated locales for init (default: en-US)
+  --devices <list>      Comma-separated device ids for init (default: iphone69,pixel8)
+  --force               Overwrite files when running init
+  --wizard              Run step-by-step init prompts
+  --style <value>       Style preset: default | template:<id> | <template-id>
+  --template <id>       Template preset (alias for --style template:<id>)
+  --defaults            Skip the style prompt in wizard (use default/no style)
+  --csv <path>          Path to copy.csv for copy import (default: ./copy.csv)
+  --import-mode <mode>  CSV import mode (merge|replace, default: merge)
+  --out <path>          Lock output file path (lock) or output root directory (build/verify/stage)
+  --zip-out <path>      ZIP output file path (default: <out>/fastlane_assets.zip)
+  --profile <appstore|playstore|any>  Strict verification/staging rules per store (default: any)
+  --from <dir>          Source output root for staging (default: config dir)
+  --check               Verify outputs are valid/up-to-date (no write)
+  --json                Emit machine-readable JSON (plan)
+  --mode <shipscreens|rendered|raw|frameit> Build mode (default: rendered). shipscreens=rendered alias, frameit runs raw + export framefile --check
+  --format <dir|zip>    Output format (default: dir)
+  --zip                 Also write a ZIP (same as --format zip)
+  --clean               Delete existing outputs for the current locale/device/bucket before writing
+  --require-pro         Fail the build if Pro access is not available
+  --manual              Print a login URL instead of starting a local callback server
+  --redirect-url <url>  Full redirect URL after manual login (for auth finish)
+  --code <code>         OAuth authorization code (manual finish)
+  --state <state>       OAuth state (manual finish)
+  --ios-dir <path>      iOS output directory (default: fastlane/screenshots)
+  --android-dir <path>  Android output directory (default: fastlane/metadata/android)
+  --strings-encoding <utf8|utf16le|utf16be>  Encoding for generated .strings (export framefile / build --mode frameit) (default: utf8)
+  --framefile-strategy <merge|overwrite>  How to handle fastlane/screenshots/Framefile.json (export framefile / build --mode frameit) (default: merge)
+  -h, --help            Show help
+
+Quickstart (no browser):
+  shipscreens wizard
+  shipscreens build --mode raw --zip --out out
+  shipscreens verify --out out --zip --profile appstore
+`);
+}
+
+const STYLE_DEFAULT_ALIASES = new Set(['default', 'none', 'no-style', 'nostyle', 'no_style']);
+
+const normalizeStyleValue = (value) => String(value || '').trim();
+
+function resolveStylePreset({ styleFlag, templateFlag }) {
+  const styleValue = normalizeStyleValue(styleFlag);
+  const templateValue = normalizeStyleValue(templateFlag);
+
+  if (styleValue && templateValue) {
+    throw new Error('Use either --style or --template (not both).');
+  }
+
+  if (templateValue) {
+    const resolved = resolveTemplateConfig(templateValue);
+    if (!resolved) {
+      const ids = listTemplateIds().join(', ');
+      throw new Error(`Unknown template "${templateValue}". Available: ${ids}`);
+    }
+    return { presetStyle: resolved.style, presetAssets: resolved.assets, skipStylePrompt: true };
+  }
+
+  if (!styleValue) {
+    return { presetStyle: undefined, presetAssets: undefined, skipStylePrompt: false };
+  }
+
+  const normalized = styleValue.toLowerCase();
+  if (STYLE_DEFAULT_ALIASES.has(normalized)) {
+    return { presetStyle: undefined, presetAssets: undefined, skipStylePrompt: true };
+  }
+
+  const templateKey = normalized.startsWith('template:') ? styleValue.slice('template:'.length).trim() : styleValue;
+  const resolved = resolveTemplateConfig(templateKey);
+  if (!resolved) {
+    const ids = listTemplateIds().join(', ');
+    throw new Error(`Unknown style/template "${styleValue}". Available templates: ${ids}`);
+  }
+  return { presetStyle: resolved.style, presetAssets: resolved.assets, skipStylePrompt: true };
+}
+
+function formatDemoTimestamp(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())}`
+  );
+}
+
+function formatDemoIndex(value, width) {
+  return String(value).padStart(width, '0');
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.stat(targetPath);
+    return true;
+  } catch (err) {
+    if (err?.code === 'ENOENT') return false;
+    throw err;
+  }
+}
+
+async function findPlaceholderAssets({ configPath }) {
+  const { config, configDir } = await loadShipScreensConfig(configPath);
+  const placeholder = createSolidPng({
+    width: PLACEHOLDER_WIDTH,
+    height: PLACEHOLDER_HEIGHT,
+    color: PLACEHOLDER_COLOR,
+  });
+  const refs = collectAssetReferences(config);
+  const byPath = new Map();
+  refs.forEach((ref) => {
+    const existing = byPath.get(ref.path) || [];
+    existing.push(ref.pointer);
+    byPath.set(ref.path, existing);
+  });
+
+  const matches = [];
+  for (const [assetPath, pointers] of byPath.entries()) {
+    const absolutePath = path.resolve(configDir, assetPath);
+    const buffer = await fs.readFile(absolutePath);
+    if (buffer.length !== placeholder.length) continue;
+    if (!buffer.equals(placeholder)) continue;
+    matches.push({ assetPath, pointers });
+  }
+  return matches;
+}
+
+async function main() {
+  const { positionals, values } = parseArgs({
+    args: process.argv.slice(2),
+    allowPositionals: true,
+    options: {
+      config: { type: 'string', short: 'c' },
+      out: { type: 'string' },
+      check: { type: 'boolean' },
+      mode: { type: 'string' },
+      format: { type: 'string' },
+      zip: { type: 'boolean' },
+      'zip-out': { type: 'string' },
+      clean: { type: 'boolean' },
+      'ios-dir': { type: 'string' },
+      'android-dir': { type: 'string' },
+      'strings-encoding': { type: 'string' },
+      'framefile-strategy': { type: 'string' },
+      profile: { type: 'string' },
+      from: { type: 'string' },
+      json: { type: 'boolean' },
+      'require-pro': { type: 'boolean' },
+      manual: { type: 'boolean' },
+      'redirect-url': { type: 'string' },
+      code: { type: 'string' },
+      state: { type: 'string' },
+      domain: { type: 'string' },
+      'client-id': { type: 'string' },
+      'api-base': { type: 'string' },
+      port: { type: 'string' },
+      dir: { type: 'string' },
+      slides: { type: 'string' },
+      locales: { type: 'string' },
+      devices: { type: 'string' },
+      force: { type: 'boolean' },
+      wizard: { type: 'boolean' },
+      style: { type: 'string' },
+      template: { type: 'string' },
+      defaults: { type: 'boolean' },
+      csv: { type: 'string' },
+      'import-mode': { type: 'string' },
+      help: { type: 'boolean', short: 'h' },
+    },
+  });
+
+  const command = positionals[0];
+  if (values.help || !command || command === 'help') {
+    printHelp();
+    return;
+  }
+
+  if (command === 'auth') {
+    await runAuth({ subcommand: positionals[1], values });
+    return;
+  }
+
+  if (command === 'wizard') {
+    const stylePreset = resolveStylePreset({ styleFlag: values.style, templateFlag: values.template });
+    const result = await runWizard({
+      dir: values.dir,
+      force: values.force,
+      presetStyle: stylePreset.presetStyle,
+      presetAssets: stylePreset.presetAssets,
+      skipStylePrompt: Boolean(values.defaults) || stylePreset.skipStylePrompt,
+      slides: values.slides,
+      locales: values.locales,
+      devices: values.devices,
+    });
+    console.log(
+      `OK: created starter files in ${result.dir}\n` +
+        `- ${result.configPath}\n` +
+        `- ${result.csvPath}\n` +
+        `Next: replace placeholder PNGs in assets/, then run:\n` +
+        `  shipscreens build --mode raw --zip --out out\n` +
+        `  shipscreens verify --out out --zip --profile appstore\n` +
+        `Pro unlock (remove watermark):\n` +
+        `  shipscreens auth login`
+    );
+    return;
+  }
+
+  if (command === 'demo') {
+    const stylePreset = resolveStylePreset({ styleFlag: values.style, templateFlag: values.template });
+    const rawOut = typeof values.out === 'string' ? values.out.trim() : '';
+    const demoRoot = rawOut
+      ? path.resolve(process.cwd(), rawOut)
+      : path.resolve(process.cwd(), 'out', `shipscreens-demo-${formatDemoTimestamp()}`);
+    const projectDir = path.join(demoRoot, 'project');
+    const buildOutDir = path.join(demoRoot, 'build');
+    const stageOutDir = path.join(demoRoot, 'stage');
+
+    const initResult = await runInit({
+      dir: projectDir,
+      slides: values.slides,
+      locales: values.locales,
+      devices: values.devices,
+      assets: stylePreset.presetAssets,
+      style: stylePreset.presetStyle,
+      force: Boolean(values.force),
+    });
+
+    // Overwrite placeholders with deterministic, non-placeholder demo PNGs.
+    const demoColors = [
+      [59, 130, 246, 255], // blue
+      [16, 185, 129, 255], // emerald
+      [245, 158, 11, 255], // amber
+      [236, 72, 153, 255], // pink
+      [139, 92, 246, 255], // violet
+      [20, 184, 166, 255], // teal
+    ];
+    const indexWidth = Math.max(2, String(initResult.slides).length);
+    for (let localeIndex = 0; localeIndex < initResult.locales.length; localeIndex += 1) {
+      const localeId = initResult.locales[localeIndex];
+      for (let i = 1; i <= initResult.slides; i += 1) {
+        const color = demoColors[(i - 1 + localeIndex) % demoColors.length];
+        const png = createSolidPng({
+          width: PLACEHOLDER_WIDTH,
+          height: PLACEHOLDER_HEIGHT,
+          color,
+        });
+        const index = formatDemoIndex(i, indexWidth);
+        const assetPath = path.join(projectDir, 'assets', localeId, `${index}.png`);
+        await fs.writeFile(assetPath, png);
+      }
+    }
+
+    const configPath = path.join(projectDir, 'shipscreens.config.yml');
+    await runValidate({ configPath });
+    await runLock({ configPath });
+
+    const mode = String(values.mode || 'raw')
+      .trim()
+      .toLowerCase();
+    if (!['raw', 'rendered'].includes(mode)) {
+      throw new Error(`Demo supports --mode raw|rendered (received: ${values.mode || '(missing)'})`);
+    }
+
+    const { config } = await loadShipScreensConfig(configPath);
+    const hasAndroid = (config.devices || []).some((device) => device.platform === 'android');
+    const hasIos = (config.devices || []).some((device) => device.platform !== 'android');
+    const defaultProfile = hasIos && !hasAndroid ? 'appstore' : !hasIos && hasAndroid ? 'playstore' : 'any';
+    const profile = values.profile || defaultProfile;
+
+    const rawZipOut = typeof values['zip-out'] === 'string' ? values['zip-out'].trim() : '';
+    const zipOut = rawZipOut || undefined;
+    const { token: cliAuthToken } = await resolveCliAuth({ requirePro: false });
+
+    const result = await runBuild({
+      configPath,
+      format: 'zip',
+      mode,
+      outDir: buildOutDir,
+      zipOut,
+      clean: true,
+      cliAuthToken,
+    });
+
+    const verifyResult = await runVerify({
+      configPath,
+      outDir: buildOutDir,
+      zipOut,
+      zip: true,
+      profile,
+    });
+
+    const stageResult = await runStage({
+      configPath,
+      fromDir: buildOutDir,
+      outDir: stageOutDir,
+      profile,
+    });
+
+    const summary = [
+      `OK: demo export completed`,
+      `${verifyResult.locales} locale(s)`,
+      `${verifyResult.slides} slide(s)`,
+      `${verifyResult.iosDevices} iOS device(s) -> ${verifyResult.iosDir}`,
+      `${verifyResult.androidDevices} Android device(s) -> ${verifyResult.androidDir}`,
+      `zip -> ${result.zipPath || verifyResult.zipPath || '(missing)'}`,
+      `stage -> ${stageResult.out}`,
+      `project -> ${projectDir}`,
+    ];
+    console.log(summary.join(', '));
+    return;
+  }
+
+  if (command === 'init') {
+    const stylePreset = resolveStylePreset({ styleFlag: values.style, templateFlag: values.template });
+    const result = values.wizard
+      ? await runWizard({
+          dir: values.dir,
+          force: values.force,
+          presetStyle: stylePreset.presetStyle,
+          presetAssets: stylePreset.presetAssets,
+          skipStylePrompt: Boolean(values.defaults) || stylePreset.skipStylePrompt,
+          slides: values.slides,
+          locales: values.locales,
+          devices: values.devices,
+        })
+      : await runInit({
+          dir: values.dir,
+          slides: values.slides,
+          locales: values.locales,
+          devices: values.devices,
+          assets: stylePreset.presetAssets,
+          style: stylePreset.presetStyle,
+          force: values.force,
+        });
+    console.log(
+      `OK: created starter files in ${result.dir}\n` +
+        `- ${result.configPath}\n` +
+        `- ${result.csvPath}\n` +
+        `Next: replace placeholder PNGs in assets/, then run:\n` +
+        `  shipscreens build --mode raw --zip --out out\n` +
+        `  shipscreens verify --out out --zip --profile appstore\n` +
+        `Pro unlock (remove watermark):\n` +
+        `  shipscreens auth login`
+    );
+    return;
+  }
+
+  if (command === 'agent-run') {
+    const stylePreset = resolveStylePreset({ styleFlag: values.style, templateFlag: values.template });
+    const targetDir = path.resolve(process.cwd(), values.dir || '.');
+    const configPath = path.join(targetDir, 'shipscreens.config.yml');
+    const hasConfig = await pathExists(configPath);
+
+    if (!hasConfig || values.force) {
+      await runInit({
+        dir: targetDir,
+        slides: values.slides,
+        locales: values.locales,
+        devices: values.devices,
+        assets: stylePreset.presetAssets,
+        style: stylePreset.presetStyle,
+        force: Boolean(values.force),
+      });
+    }
+
+    try {
+      await runValidate({ configPath });
+    } catch (err) {
+      const message = err?.message || String(err);
+      throw new Error(`Missing assets. Replace placeholder PNGs, then rerun.\n${message}`);
+    }
+    const placeholders = await findPlaceholderAssets({ configPath });
+    if (placeholders.length) {
+      const lines = placeholders.flatMap((item) => [
+        `Placeholder PNG detected: ${item.assetPath}`,
+        ...item.pointers.map((pointer) => `  - referenced by ${pointer}`),
+      ]);
+      throw new Error(
+        `Placeholder PNGs found. Replace them with real screenshots before building.\n` + lines.join('\n')
+      );
+    }
+
+    const rawZipOut = typeof values['zip-out'] === 'string' ? values['zip-out'].trim() : '';
+    const defaultZip = !values.format && !values.zip && !rawZipOut;
+    const format = values.format || (values.zip || rawZipOut || defaultZip ? 'zip' : 'dir');
+    const mode = values.mode || 'raw';
+    const outDir = values.out || 'out/agent';
+    const zipOut = rawZipOut || undefined;
+    const zip = format === 'zip' || Boolean(zipOut);
+    const { config } = await loadShipScreensConfig(configPath);
+    const hasAndroid = (config.devices || []).some((device) => device.platform === 'android');
+    const hasIos = (config.devices || []).some((device) => device.platform !== 'android');
+    const defaultProfile = hasIos && !hasAndroid ? 'appstore' : !hasIos && hasAndroid ? 'playstore' : 'any';
+    const profile = values.profile || defaultProfile;
+    const requirePro = Boolean(values['require-pro']);
+    const { token: cliAuthToken } = await resolveCliAuth({ requirePro });
+
+    const result = await runBuild({
+      configPath,
+      format,
+      mode,
+      outDir,
+      iosDir: values['ios-dir'],
+      androidDir: values['android-dir'],
+      zipOut,
+      stringsEncoding: values['strings-encoding'],
+      framefileStrategy: values['framefile-strategy'],
+      clean: values.clean,
+      cliAuthToken,
+    });
+
+    const verifyResult = await runVerify({
+      configPath,
+      outDir,
+      iosDir: values['ios-dir'],
+      androidDir: values['android-dir'],
+      zipOut,
+      zip,
+      profile,
+    });
+
+    const summary = [
+      `OK: agent-run completed`,
+      `${verifyResult.locales} locale(s)`,
+      `${verifyResult.slides} slide(s)`,
+      `${verifyResult.iosDevices} iOS device(s) -> ${verifyResult.iosDir}`,
+      `${verifyResult.androidDevices} Android device(s) -> ${verifyResult.androidDir}`,
+    ];
+    if (result.zipPath || verifyResult.zipPath) summary.push(`zip -> ${result.zipPath || verifyResult.zipPath}`);
+    console.log(summary.join(', '));
+    return;
+  }
+
+  const configPath = values.config ?? (await resolveDefaultConfigPath());
+  if (!configPath) {
+    throw new Error(
+      'Config not found. Expected ./shipscreens.config.yml (or pass --config).\n' +
+        'Run: shipscreens init'
+    );
+  }
+
+  if (command === 'copy') {
+    const subcommand = positionals[1];
+    if (subcommand === 'import') {
+      const result = await runCopyImport({
+        configPath,
+        csvPath: values.csv,
+        mode: values['import-mode'],
+      });
+      console.log(
+        `OK: imported copy.csv (${result.mode}) -> ${result.configPath}\n` +
+          `- locales: ${result.locales}\n` +
+          `- slides: ${result.slides}`
+      );
+      return;
+    }
+    throw new Error(`Unknown copy command: ${subcommand || '(missing)'}`);
+  }
+
+  if (command === 'validate') {
+    const result = await runValidate({ configPath });
+    console.log(`OK: validated (${result.assetCount} asset(s))`);
+    return;
+  }
+
+  if (command === 'lock') {
+    const result = await runLock({ configPath, outPath: values.out, check: values.check });
+    if (result.checked) {
+      console.log(`OK: lockfile up to date (${result.assetCount} asset(s)) -> ${result.outPath}`);
+    } else {
+      console.log(`OK: wrote lockfile (${result.assetCount} asset(s)) -> ${result.outPath}`);
+    }
+    return;
+  }
+
+  if (command === 'build') {
+    const format = values.zip ? 'zip' : values.format || 'dir';
+    const rawOut = typeof values.out === 'string' ? values.out.trim() : '';
+    const rawZipOut = typeof values['zip-out'] === 'string' ? values['zip-out'].trim() : '';
+
+    let outDir = rawOut || undefined;
+    let zipOut = rawZipOut || undefined;
+    if ((values.zip || format === 'zip') && outDir && outDir.toLowerCase().endsWith('.zip') && !zipOut) {
+      zipOut = outDir;
+      outDir = undefined;
+      console.warn(
+        `DEPRECATED: shipscreens build --out <file.zip> will change behavior in a future release.\n` +
+          `Use: shipscreens build --zip-out <file.zip>\n` +
+          `Note: --out now specifies an output directory root.`
+      );
+    }
+
+    const requirePro = Boolean(values['require-pro']);
+    const { token: cliAuthToken } = await resolveCliAuth({ requirePro });
+    const result = await runBuild({
+      configPath,
+      format,
+      mode: values.mode,
+      outDir,
+      iosDir: values['ios-dir'],
+      androidDir: values['android-dir'],
+      zipOut,
+      stringsEncoding: values['strings-encoding'],
+      framefileStrategy: values['framefile-strategy'],
+      clean: values.clean,
+      cliAuthToken,
+    });
+    const summary = [
+      `OK: built`,
+      `${result.locales} locale(s)`,
+      `${result.slides} slide(s)`,
+      `${result.iosDevices} iOS device(s) -> ${result.iosDir}`,
+      `${result.androidDevices} Android device(s) -> ${result.androidDir}`,
+    ];
+    if (result.zipPath) summary.push(`zip -> ${result.zipPath}`);
+    console.log(summary.join(', '));
+    return;
+  }
+
+  if (command === 'verify') {
+    const rawOut = typeof values.out === 'string' ? values.out.trim() : '';
+    const rawZipOut = typeof values['zip-out'] === 'string' ? values['zip-out'].trim() : '';
+    const result = await runVerify({
+      configPath,
+      outDir: rawOut || undefined,
+      iosDir: values['ios-dir'],
+      androidDir: values['android-dir'],
+      zipOut: rawZipOut || undefined,
+      zip: values.zip || Boolean(rawZipOut),
+      profile: values.profile,
+    });
+    const summary = [
+      `OK: verified`,
+      `${result.locales} locale(s)`,
+      `${result.slides} slide(s)`,
+      `${result.iosDevices} iOS device(s) -> ${result.iosDir}`,
+      `${result.androidDevices} Android device(s) -> ${result.androidDir}`,
+    ];
+    if (result.zipPath) summary.push(`zip -> ${result.zipPath}`);
+    console.log(summary.join(', '));
+    return;
+  }
+
+  if (command === 'stage') {
+    const rawFrom = typeof values.from === 'string' ? values.from.trim() : '';
+    const rawOut = typeof values.out === 'string' ? values.out.trim() : '';
+    const result = await runStage({
+      configPath,
+      fromDir: rawFrom || undefined,
+      outDir: rawOut || undefined,
+      profile: values.profile,
+    });
+    const details = result.iosVariant ? `, ios=${result.iosVariant}` : '';
+    console.log(`OK: staged (${result.profile}${details}), ${result.files} file(s) -> ${result.out}`);
+    return;
+  }
+
+  if (command === 'plan') {
+    const plan = await runPlan({
+      configPath,
+      outDir: values.out,
+      iosDir: values['ios-dir'],
+      androidDir: values['android-dir'],
+      zipOut: values['zip-out'],
+      profile: values.profile,
+    });
+    process.stdout.write(JSON.stringify(plan, null, 2) + '\n');
+    return;
+  }
+
+  if (command === 'export') {
+    const subcommand = positionals[1];
+    if (subcommand === 'framefile') {
+      const result = await runExportFramefile({
+        configPath,
+        iosDir: values['ios-dir'],
+        stringsEncoding: values['strings-encoding'],
+        framefileStrategy: values['framefile-strategy'],
+        check: values.check,
+      });
+      if (result.checked) {
+        console.log(`OK: frameit inputs look valid (${result.locales} locale(s)) -> ${result.iosDir}`);
+      } else {
+        console.log(`OK: wrote Framefile.json + .strings for ${result.locales} locale(s) -> ${result.iosDir}`);
+      }
+      return;
+    }
+
+    throw new Error(`Unknown export target: ${subcommand || '(missing)'}`);
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+main().catch((err) => {
+  console.error(err?.message || String(err));
+  process.exitCode = 1;
+});

package/cli/assetRefs.js

@@ -0,0 +1,33 @@
+export function collectAssetReferences(config) {
+  const refs = [];
+
+  const add = (assetPath, pointer) => {
+    if (!assetPath) return;
+    refs.push({ path: assetPath, pointer });
+  };
+
+  if (config?.assets?.background?.type === 'image') {
+    add(config.assets.background.path, 'assets.background.path');
+  }
+
+  if (config?.assets?.logo?.path) {
+    add(config.assets.logo.path, 'assets.logo.path');
+  }
+
+  if (Array.isArray(config?.assets?.badges)) {
+    config.assets.badges.forEach((badge, idx) => add(badge.path, `assets.badges[${idx}].path`));
+  }
+
+  if (Array.isArray(config?.slides)) {
+    config.slides.forEach((slide, idx) => {
+      add(slide?.screenshot?.path, `slides[${idx}].screenshot.path`);
+      const perLocale = slide?.screenshotsByLocale || {};
+      Object.entries(perLocale).forEach(([localeId, assetPath]) =>
+        add(assetPath, `slides[${idx}].screenshotsByLocale.${localeId}`)
+      );
+    });
+  }
+
+  return refs;
+}
+