shipscreens 0.1.6 → 0.1.7

package/cli/commands/inspectReleaseContext.js

@@ -0,0 +1,607 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { collectAssetReferences } from '../assetRefs.js';
+import { loadShipScreensConfig, resolveDefaultConfigPath } from '../loadConfig.js';
+import { resolveOutputPath } from '../outputPaths.js';
+import {
+  createSolidPng,
+  PLACEHOLDER_COLOR,
+  PLACEHOLDER_HEIGHT,
+  PLACEHOLDER_WIDTH,
+} from './init.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 MAX_SAMPLE_FILES = 12;
+const MAX_IMAGE_COUNT = 5000;
+
+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 || '.');
+}
+
+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);
+  }
+  return resolveDefaultConfigPath(targetDir);
+}
+
+function getAndroidBucket(device) {
+  return device.androidBucket || 'phoneScreenshots';
+}
+
+function summarizeConfig({ config, configDir, targetDir }) {
+  const devices = Array.isArray(config.devices) ? config.devices : [];
+  const iosDevices = devices.filter((device) => device.platform !== 'android');
+  const androidDevices = devices.filter((device) => device.platform === 'android');
+  const locales = (config.locales || []).map((locale) => locale.id).sort(compareStrings);
+
+  const iosDir = resolveOutputPath({
+    outRoot: configDir,
+    value: config.output?.directory,
+    fallback: 'fastlane/screenshots',
+  });
+  const androidDir = resolveOutputPath({
+    outRoot: configDir,
+    value: config.output?.androidDirectory,
+    fallback: 'fastlane/metadata/android',
+  });
+
+  return {
+    schemaVersion: config.schemaVersion || config.version || null,
+    variant: config.variant || config.experiment?.variant || config.asoExperiment?.variant || null,
+    locales,
+    localeCount: locales.length,
+    slideCount: Array.isArray(config.slides) ? config.slides.length : 0,
+    devices: devices.map((device) => ({
+      id: device.id,
+      platform: device.platform || null,
+      androidBucket: device.platform === 'android' ? getAndroidBucket(device) : null,
+      label: device.label || null,
+    })),
+    iosDevices: iosDevices.map((device) => device.id).sort(compareStrings),
+    androidDevices: androidDevices.map((device) => ({
+      id: device.id,
+      bucket: getAndroidBucket(device),
+    })),
+    output: {
+      iosDir,
+      iosDirRelative: relativeTo(targetDir, iosDir),
+      androidDir,
+      androidDirRelative: relativeTo(targetDir, androidDir),
+    },
+  };
+}
+
+async function loadConfigContext({ targetDir, configPath }) {
+  const resolvedConfigPath = await resolveConfigCandidate({ targetDir, configPath });
+  if (!resolvedConfigPath) {
+    return {
+      path: path.join(targetDir, 'shipscreens.config.yml'),
+      relativePath: 'shipscreens.config.yml',
+      exists: false,
+      valid: false,
+      error: null,
+      summary: null,
+      config: null,
+      configDir: targetDir,
+    };
+  }
+
+  const exists = Boolean(await statSafe(resolvedConfigPath));
+  if (!exists) {
+    return {
+      path: resolvedConfigPath,
+      relativePath: relativeTo(targetDir, resolvedConfigPath),
+      exists: false,
+      valid: false,
+      error: null,
+      summary: null,
+      config: null,
+      configDir: path.dirname(resolvedConfigPath),
+    };
+  }
+
+  try {
+    const loaded = await loadShipScreensConfig(resolvedConfigPath);
+    return {
+      path: loaded.configPath,
+      relativePath: relativeTo(targetDir, loaded.configPath),
+      exists: true,
+      valid: true,
+      error: null,
+      summary: summarizeConfig({
+        config: loaded.config,
+        configDir: loaded.configDir,
+        targetDir,
+      }),
+      config: loaded.config,
+      configDir: loaded.configDir,
+    };
+  } catch (err) {
+    return {
+      path: resolvedConfigPath,
+      relativePath: relativeTo(targetDir, resolvedConfigPath),
+      exists: true,
+      valid: false,
+      error: err?.message || String(err),
+      summary: null,
+      config: null,
+      configDir: path.dirname(resolvedConfigPath),
+    };
+  }
+}
+
+function addRootCandidate(candidates, seen, { kind, label, rootPath }) {
+  const resolved = path.resolve(rootPath);
+  const key = resolved.toLowerCase();
+  if (seen.has(key)) return;
+  seen.add(key);
+  candidates.push({ kind, label, path: resolved });
+}
+
+function createRootCandidates({ targetDir, configContext }) {
+  const candidates = [];
+  const seen = new Set();
+
+  if (configContext.valid && configContext.summary?.output) {
+    addRootCandidate(candidates, seen, {
+      kind: 'config_ios_output',
+      label: 'Configured iOS Fastlane output',
+      rootPath: configContext.summary.output.iosDir,
+    });
+    addRootCandidate(candidates, seen, {
+      kind: 'config_android_output',
+      label: 'Configured Android Fastlane output',
+      rootPath: configContext.summary.output.androidDir,
+    });
+  }
+
+  [
+    ['fastlane_ios', 'Conventional iOS Fastlane screenshots', path.join(targetDir, 'fastlane', 'screenshots')],
+    [
+      'fastlane_android',
+      'Conventional Android Fastlane metadata',
+      path.join(targetDir, 'fastlane', 'metadata', 'android'),
+    ],
+    ['source_screenshots', 'Source screenshots', path.join(targetDir, 'screenshots')],
+    ['captured_screenshots', 'Captured device/emulator screenshots', path.join(targetDir, 'screenshots', 'captured')],
+    ['source_screenshot', 'Source screenshot', path.join(targetDir, 'screenshot')],
+    ['assets_screenshots', 'Asset screenshots', path.join(targetDir, 'assets', 'screenshots')],
+    ['assets', 'Assets', path.join(targetDir, 'assets')],
+    ['public_screenshots', 'Public screenshots', path.join(targetDir, 'public', 'screenshots')],
+    ['app_store_screenshots', 'App Store screenshots', path.join(targetDir, 'app-store-screenshots')],
+    ['play_store_screenshots', 'Play Store screenshots', path.join(targetDir, 'play-store-screenshots')],
+  ].forEach(([kind, label, rootPath]) => addRootCandidate(candidates, seen, { kind, label, rootPath }));
+
+  return candidates;
+}
+
+async function scanImageRoot({ targetDir, candidate }) {
+  const stat = await statSafe(candidate.path);
+  const result = {
+    kind: candidate.kind,
+    label: candidate.label,
+    path: candidate.path,
+    relativePath: relativeTo(targetDir, candidate.path),
+    exists: Boolean(stat),
+    isDirectory: Boolean(stat?.isDirectory()),
+    imageFiles: 0,
+    extensions: {},
+    sample: [],
+    truncated: false,
+  };
+  if (!stat) return result;
+
+  const addImage = (filePath) => {
+    if (result.imageFiles >= MAX_IMAGE_COUNT) {
+      result.truncated = true;
+      return;
+    }
+    const ext = path.extname(filePath).toLowerCase();
+    if (!IMAGE_EXTENSIONS.has(ext)) return;
+    result.imageFiles += 1;
+    result.extensions[ext.slice(1)] = (result.extensions[ext.slice(1)] || 0) + 1;
+    if (result.sample.length < MAX_SAMPLE_FILES) {
+      result.sample.push(relativeTo(candidate.path, filePath));
+    }
+  };
+
+  if (stat.isFile()) {
+    addImage(candidate.path);
+    return result;
+  }
+  if (!stat.isDirectory()) return result;
+
+  const walk = async (dirPath, depth) => {
+    if (depth < 0 || result.imageFiles >= MAX_IMAGE_COUNT) {
+      result.truncated = true;
+      return;
+    }
+    let entries = [];
+    try {
+      entries = await fs.readdir(dirPath, { withFileTypes: true });
+    } catch (err) {
+      if (err?.code === 'ENOENT' || err?.code === 'EACCES' || err?.code === 'EPERM') return;
+      throw err;
+    }
+    entries.sort((a, b) => compareStrings(a.name, b.name));
+    for (const entry of entries) {
+      if (result.imageFiles >= MAX_IMAGE_COUNT) {
+        result.truncated = true;
+        return;
+      }
+      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()) addImage(childPath);
+    }
+  };
+
+  await walk(candidate.path, MAX_SCAN_DEPTH);
+  result.sample.sort(compareStrings);
+  result.extensions = Object.fromEntries(
+    Object.entries(result.extensions).sort(([a], [b]) => compareStrings(a, b))
+  );
+  return result;
+}
+
+async function inspectRoots({ targetDir, configContext }) {
+  const candidates = createRootCandidates({ targetDir, configContext });
+  const roots = [];
+  for (const candidate of candidates) {
+    roots.push(await scanImageRoot({ targetDir, candidate }));
+  }
+  return roots;
+}
+
+async function inspectMissingAssets({ targetDir, configContext }) {
+  if (!configContext.valid || !configContext.config) return [];
+  const refsByPath = new Map();
+  collectAssetReferences(configContext.config).forEach((ref) => {
+    const existing = refsByPath.get(ref.path) || [];
+    existing.push(ref.pointer);
+    refsByPath.set(ref.path, existing);
+  });
+
+  const missing = [];
+  for (const [assetPath, pointers] of [...refsByPath.entries()].sort(([a], [b]) => compareStrings(a, b))) {
+    const absolutePath = path.resolve(configContext.configDir, assetPath);
+    const stat = await statSafe(absolutePath);
+    if (stat?.isFile()) continue;
+    missing.push({
+      path: assetPath,
+      absolutePath,
+      relativePath: relativeTo(targetDir, absolutePath),
+      pointers,
+    });
+  }
+  return missing;
+}
+
+async function inspectPlaceholderAssets({ targetDir, configContext }) {
+  if (!configContext.valid || !configContext.config) return [];
+  const placeholder = createSolidPng({
+    width: PLACEHOLDER_WIDTH,
+    height: PLACEHOLDER_HEIGHT,
+    color: PLACEHOLDER_COLOR,
+  });
+  const refsByPath = new Map();
+  collectAssetReferences(configContext.config).forEach((ref) => {
+    const existing = refsByPath.get(ref.path) || [];
+    existing.push(ref.pointer);
+    refsByPath.set(ref.path, existing);
+  });
+
+  const placeholders = [];
+  for (const [assetPath, pointers] of [...refsByPath.entries()].sort(([a], [b]) => compareStrings(a, b))) {
+    const absolutePath = path.resolve(configContext.configDir, assetPath);
+    const stat = await statSafe(absolutePath);
+    if (!stat?.isFile()) continue;
+    const buffer = await fs.readFile(absolutePath);
+    if (buffer.length !== placeholder.length || !buffer.equals(placeholder)) continue;
+    placeholders.push({
+      path: assetPath,
+      absolutePath,
+      relativePath: relativeTo(targetDir, absolutePath),
+      pointers,
+    });
+  }
+  return placeholders;
+}
+
+async function inspectFileSignals({ targetDir, configContext }) {
+  const dedupe = new Set();
+  const makeSignal = async (kind, filePath) => {
+    const resolved = path.resolve(filePath);
+    const key = `${kind}:${resolved.toLowerCase()}`;
+    if (dedupe.has(key)) return null;
+    dedupe.add(key);
+    const stat = await statSafe(resolved);
+    return {
+      kind,
+      path: resolved,
+      relativePath: relativeTo(targetDir, resolved),
+      exists: Boolean(stat?.isFile()),
+    };
+  };
+
+  const configDir = configContext.configDir || targetDir;
+  const candidates = [
+    ['copy_csv', path.join(targetDir, 'copy.csv')],
+    ['copy_csv', path.join(configDir, 'copy.csv')],
+    ['lockfile', path.join(targetDir, 'shipscreens.lock.json')],
+    ['lockfile', path.join(configDir, 'shipscreens.lock.json')],
+    ['mcp_config', path.join(targetDir, '.mcp.json')],
+    ['mcp_config', path.join(targetDir, '.cursor', 'mcp.json')],
+    ['mcp_config', path.join(targetDir, '.vscode', 'mcp.json')],
+    ['mcp_config', path.join(targetDir, '.gemini', 'settings.json')],
+  ];
+
+  const signals = [];
+  for (const [kind, filePath] of candidates) {
+    const signal = await makeSignal(kind, filePath);
+    if (signal) signals.push(signal);
+  }
+  return signals;
+}
+
+function inferStoreTarget({ configContext, roots }) {
+  if (configContext.valid && configContext.summary) {
+    const iosCount = configContext.summary.iosDevices.length;
+    const androidCount = configContext.summary.androidDevices.length;
+    if (iosCount && androidCount) {
+      return {
+        profile: 'any',
+        confidence: 'high',
+        source: 'shipscreens.config.yml devices',
+        reasons: [`${iosCount} iOS device(s) and ${androidCount} Android device(s) configured.`],
+      };
+    }
+    if (iosCount) {
+      return {
+        profile: 'appstore',
+        confidence: 'high',
+        source: 'shipscreens.config.yml devices',
+        reasons: [`${iosCount} iOS device(s) configured and no Android devices configured.`],
+      };
+    }
+    if (androidCount) {
+      return {
+        profile: 'playstore',
+        confidence: 'high',
+        source: 'shipscreens.config.yml devices',
+        reasons: [`${androidCount} Android device(s) configured and no iOS devices configured.`],
+      };
+    }
+  }
+
+  const iosImages = roots
+    .filter((root) => ['config_ios_output', 'fastlane_ios'].includes(root.kind))
+    .reduce((sum, root) => sum + root.imageFiles, 0);
+  const androidImages = roots
+    .filter((root) => ['config_android_output', 'fastlane_android'].includes(root.kind))
+    .reduce((sum, root) => sum + root.imageFiles, 0);
+
+  if (iosImages && androidImages) {
+    return {
+      profile: 'any',
+      confidence: 'medium',
+      source: 'existing Fastlane roots',
+      reasons: [`Found ${iosImages} iOS image(s) and ${androidImages} Android image(s) in Fastlane roots.`],
+    };
+  }
+  if (iosImages) {
+    return {
+      profile: 'appstore',
+      confidence: 'medium',
+      source: 'existing Fastlane roots',
+      reasons: [`Found ${iosImages} iOS image(s) in Fastlane screenshots root.`],
+    };
+  }
+  if (androidImages) {
+    return {
+      profile: 'playstore',
+      confidence: 'medium',
+      source: 'existing Fastlane roots',
+      reasons: [`Found ${androidImages} Android image(s) in Fastlane metadata root.`],
+    };
+  }
+
+  return {
+    profile: 'unknown',
+    confidence: 'low',
+    source: 'not detected',
+    reasons: ['No valid ShipScreens config or populated Fastlane roots were detected.'],
+  };
+}
+
+function buildGuidance({ configContext, roots, missingAssets, placeholderAssets, storeTarget, fileSignals }) {
+  const warnings = [];
+  const questions = [];
+  const nextSteps = [];
+
+  if (!configContext.exists) {
+    warnings.push('No shipscreens.config.yml was detected in the inspected workspace.');
+    questions.push('Which store target should be built first: appstore, playstore, or both?');
+    questions.push('Which device and locale scope is required for this release?');
+  } else if (!configContext.valid) {
+    warnings.push(`Config exists but is invalid: ${String(configContext.error || '').split('\n')[0]}`);
+    nextSteps.push('Fix shipscreens.config.yml schema errors before build/verify/stage.');
+  }
+
+  if (missingAssets.length) {
+    warnings.push(`${missingAssets.length} referenced asset path(s) are missing.`);
+    nextSteps.push('Replace missing PNG assets or update their paths in shipscreens.config.yml.');
+  }
+
+  if (placeholderAssets.length) {
+    warnings.push(`${placeholderAssets.length} config-referenced placeholder PNG(s) still need real screenshots.`);
+    nextSteps.push('Run shipscreens import-screenshots --from <dir> --json or replace placeholder PNGs under assets/.');
+  }
+
+  const existingImageRoots = roots.filter((root) => root.exists && root.imageFiles > 0);
+  if (!existingImageRoots.length) {
+    warnings.push('No existing screenshot/image root with image files was detected.');
+    questions.push('Where are the current base screenshots or Fastlane output folders?');
+    nextSteps.push(
+      'If a real device or emulator is already showing the app, run shipscreens capture-screenshots --platform auto --out screenshots --slot 1 --json for each panel, then import-screenshots.'
+    );
+  }
+
+  if (storeTarget.profile === 'unknown') {
+    questions.push('Should the first proof target App Store, Google Play, or both?');
+  }
+
+  const hasCopyCsv = fileSignals.some((signal) => signal.kind === 'copy_csv' && signal.exists);
+  if (configContext.valid && !hasCopyCsv) {
+    questions.push('Is the panel copy already final in shipscreens.config.yml, or should the agent create/import copy.csv?');
+  }
+
+  if (!configContext.exists) {
+    nextSteps.push('Run shipscreens write-starter-config --profile <appstore|playstore|any> --json to create the starter config.');
+  } else if (configContext.valid && !missingAssets.length) {
+    const profile = storeTarget.profile === 'unknown' ? 'any' : storeTarget.profile;
+    nextSteps.push(`Run shipscreens plan --profile ${profile} --json to preview output paths.`);
+    nextSteps.push(`Run shipscreens agent-run --mode raw --zip --out out/agent --stage --profile ${profile}.`);
+  }
+
+  nextSteps.push('Return the staged root plus shipscreens.agent-report.json / shipscreens.agent-summary.md to the human reviewer.');
+
+  return {
+    warnings: [...new Set(warnings)],
+    questions: [...new Set(questions)],
+    nextSteps: [...new Set(nextSteps)],
+  };
+}
+
+function buildAgentHandoff({ storeTarget }) {
+  const profile = storeTarget.profile === 'unknown' ? '<appstore|playstore|any>' : storeTarget.profile;
+  return (
+    'Ship release-safe screenshots from this repo. First inspect release context, then use ShipScreens MCP or CLI ' +
+    `to write/update config and copy if needed, run validate/build/verify/stage with profile=${profile}, ` +
+    'and return the staged upload root plus shipscreens.agent-report.json / shipscreens.agent-summary.md. ' +
+    'Ask only if store target, device/locale scope, or panel #1 messaging is ambiguous.'
+  );
+}
+
+export async function runInspectReleaseContext({ dir, configPath } = {}) {
+  const targetDir = path.resolve(process.cwd(), dir || '.');
+  const targetStat = await statSafe(targetDir);
+  if (!targetStat?.isDirectory()) {
+    throw new Error(`Workspace directory not found: ${targetDir}`);
+  }
+
+  const configContext = await loadConfigContext({ targetDir, configPath });
+  const roots = await inspectRoots({ targetDir, configContext });
+  const missingAssets = await inspectMissingAssets({ targetDir, configContext });
+  const placeholderAssets = await inspectPlaceholderAssets({ targetDir, configContext });
+  const fileSignals = await inspectFileSignals({ targetDir, configContext });
+  const storeTarget = inferStoreTarget({ configContext, roots });
+  const guidance = buildGuidance({
+    configContext,
+    roots,
+    missingAssets,
+    placeholderAssets,
+    storeTarget,
+    fileSignals,
+  });
+
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    workspace: targetDir,
+    config: {
+      path: configContext.path,
+      relativePath: configContext.relativePath,
+      exists: configContext.exists,
+      valid: configContext.valid,
+      error: configContext.error,
+      summary: configContext.summary,
+    },
+    storeTarget,
+    screenshotRoots: roots,
+    missingAssets,
+    placeholderAssets,
+    files: fileSignals,
+    warnings: guidance.warnings,
+    questions: guidance.questions,
+    nextSteps: guidance.nextSteps,
+    agentHandoff: buildAgentHandoff({ storeTarget }),
+  };
+}
+
+export function renderInspectReleaseContextSummary(result) {
+  const existingRoots = result.screenshotRoots
+    .filter((root) => root.exists && root.imageFiles > 0)
+    .sort((a, b) => compareStrings(a.relativePath, b.relativePath));
+  const signals = result.files.filter((signal) => signal.exists).sort((a, b) => compareStrings(a.relativePath, b.relativePath));
+
+  const lines = [
+    'ShipScreens release context',
+    `- Workspace: ${result.workspace}`,
+    `- Config: ${result.config.exists ? result.config.relativePath : 'not found'} (${result.config.valid ? 'valid' : 'not ready'})`,
+    `- Store target: ${result.storeTarget.profile} (${result.storeTarget.confidence}, ${result.storeTarget.source})`,
+  ];
+
+  if (result.config.summary) {
+    lines.push(
+      `- Locales: ${result.config.summary.locales.join(', ') || 'none'}`,
+      `- Slides: ${result.config.summary.slideCount}`,
+      `- iOS devices: ${result.config.summary.iosDevices.join(', ') || 'none'}`,
+      `- Android devices: ${result.config.summary.androidDevices.map((d) => `${d.id}:${d.bucket}`).join(', ') || 'none'}`
+    );
+  }
+
+  lines.push('', 'Existing screenshot roots:');
+  if (existingRoots.length) {
+    existingRoots.slice(0, 8).forEach((root) => {
+      lines.push(`- ${root.relativePath}: ${root.imageFiles} image(s)`);
+    });
+  } else {
+    lines.push('- none detected');
+  }
+
+  lines.push('', 'File signals:');
+  if (signals.length) {
+    signals.forEach((signal) => lines.push(`- ${signal.kind}: ${signal.relativePath}`));
+  } else {
+    lines.push('- none detected');
+  }
+
+  lines.push('', 'Warnings:');
+  if (result.warnings.length) {
+    result.warnings.forEach((warning) => lines.push(`- ${warning}`));
+  } else {
+    lines.push('- none');
+  }
+
+  lines.push('', 'Next steps:');
+  result.nextSteps.forEach((step) => lines.push(`- ${step}`));
+
+  lines.push('', 'Agent handoff:', result.agentHandoff);
+  return `${lines.join('\n')}\n`;
+}