vydanne 0.6.0 → 0.8.0

package/src/commands/diff.mjs

@@ -2,15 +2,20 @@ import fs from "node:fs";
 import path from "node:path";
 import { green, yellow, red } from "../util.mjs";
 import { VALID } from "../locales.mjs";
+import { md5 } from "../upload.mjs";
+import { localScreenshots, remoteScreenshots, compareShots, localScreenshotLocales } from "../screenshots.mjs";
 
 // [asc attribute, local metadata filename, isLongText]
 const VERSION_FIELDS = [
   ["description", "description", true], ["keywords", "keywords", false], ["promotionalText", "promotional_text", false],
   ["whatsNew", "release_notes", true], ["marketingUrl", "marketing_url", false], ["supportUrl", "support_url", false],
 ];
-const INFO_FIELDS = [["name", "name", false], ["subtitle", "subtitle", false]];
-const IOS_DEVICE = { iphone69: "APP_IPHONE_67", iphone65: "APP_IPHONE_65", ipad13: "APP_IPAD_PRO_3GEN_129", watch: "APP_WATCH_ULTRA" };
-const MAC_DEVICE = { macos: "APP_DESKTOP" };
+// Must list everything `fill`'s INFO_TXT writes, or `diff` reports "in sync" over a field it never
+// looked at — which is not a harmless gap: `fill` PATCHes unconditionally (patchAttrs never compares),
+// so `diff` is the ONLY thing that can say whether a value actually reached Apple. When
+// privacyPolicyUrl was added to fill and not here, one command claimed 19 pending writes while the
+// other claimed sync, and neither was evidence of anything.
+const INFO_FIELDS = [["name", "name", false], ["subtitle", "subtitle", false], ["privacyPolicyUrl", "privacy_url", false]];
 
 const norm = (s) => (s == null ? null : String(s).replace(/\r/g, "").replace(/\n+$/, "").trim());
 const short = (s, n = 24) => { s = String(s).replace(/\n/g, " "); return s.length > n ? s.slice(0, n) + "…" : s; };
@@ -19,13 +24,19 @@ const short = (s, n = 24) => { s = String(s).replace(/\n/g, " "); return s.lengt
 // Connect — i.e. what `fill` / `previews` would change. Reads each localization by id (list is sparse).
 export async function run(config, client) {
   await client.findApp(config.bundleId);
-  const info = await client.appInfo();
+  // allowLive for the same reason as editVersion below: comparing local name/subtitle against what is
+  // on sale is a legitimate read, and on an app with nothing in preparation the live record is the
+  // only one to compare against.
+  const info = await client.appInfo({ allowLive: true });
   const infoLocs = info ? (await client.get(`/v1/appInfos/${info.id}/appInfoLocalizations?limit=200`)).json.data || [] : [];
   let actionable = 0; // differences `fill`/`previews` would actually change (release_notes on a 1.0 is benign)
 
   for (const platform of config.platforms) {
-    const v = await client.editVersion(platform);
-    if (!v) { console.log(red(`${platform}: no editable version`)); continue; }
+    // allowLive: comparing local against the version ON SALE is a legitimate question and often the
+    // reason to run this before preparing a release. The state is printed below, so it is never unclear
+    // WHICH version the comparison is against — and `fill` no longer targets a live one either way.
+    const v = await client.editVersion(platform, { allowLive: true });
+    if (!v) { console.log(red(`${platform}: no version at all`)); continue; }
     console.log(`${platform}  v${v.attributes.versionString} ${v.attributes.appStoreState}`);
     const verLocs = await client.versionLocalizations(v.id);
     const localDirs = fs.existsSync(config.metadataDir)
@@ -84,24 +95,62 @@ async function mediaDiff(config, client, platform, verLocs) {
   const primary = verLocs.find((l) => l.attributes.locale === config.primaryLocale);
   if (!primary) return 0;
   let diffs = 0;
-  const dev = platform === "MAC_OS" ? MAC_DEVICE : IOS_DEVICE;
-  const base = platform === "MAC_OS" ? "fastlane/screenshots-macos" : "fastlane/screenshots";
-  const localDir = path.join(base, config.primaryLocale);
-  const local = {};
-  if (fs.existsSync(localDir)) for (const f of fs.readdirSync(localDir).filter((f) => f.endsWith(".png"))) { const dt = dev[f.split("_")[0]]; if (dt) local[dt] = (local[dt] || 0) + 1; }
-  const { json: sets } = await client.get(`/v1/appStoreVersionLocalizations/${primary.id}/appScreenshotSets?include=appScreenshots&limit=50`);
-  const remote = {};
-  for (const s of sets.data || []) remote[s.attributes.screenshotDisplayType] = (s.relationships?.appScreenshots?.data || []).length;
-  for (const dt of new Set([...Object.keys(local), ...Object.keys(remote)])) {
-    const L = local[dt] || 0, R = remote[dt] || 0;
-    if (L !== R) { diffs++; console.log(`  ${yellow("screenshots")} ${dt.replace("APP_", "")}: local ${L} / remote ${R}  (@${config.primaryLocale})`); }
+  // Compared by CONTENT, not by count — the machinery lives in src/screenshots.mjs and is shared with
+  // `preflight`, so the two commands cannot drift apart in what "in sync" means. The history is there.
+  // Every locale with a local set, for the reason preflight now does the same: `bridge` writes one
+  // folder per translated locale, and checking only the primary reported "in sync" about a listing
+  // whose other nineteen locales were showing last month's art.
+  for (const code of [...new Set([config.primaryLocale, ...localScreenshotLocales(platform, config)])]) {
+    const loc = verLocs.find((l) => l.attributes.locale === code);
+    if (!loc) continue;
+    const local = localScreenshots(platform, code, config);
+    const remote = await remoteScreenshots(client, loc.id);
+    for (const dt of new Set([...Object.keys(local), ...Object.keys(remote)])) {
+      const c = compareShots(local[dt] || new Map(), remote[dt] || new Map());
+      if (!c) continue;
+      const label = `  ${yellow("screenshots")} ${dt.replace("APP_", "")}`;
+      if (c.kind === "count") {
+        diffs++;
+        console.log(`${label}: local ${c.local} / remote ${c.remote}  (@${code})`);
+      } else if (c.kind === "renamed") {
+        diffs++;
+        console.log(`${label}: ${c.names.length} not on the store by name (${c.names.slice(0, 3).join(", ")})  (@${code})`);
+      } else if (c.kind === "stale") {
+        diffs++;
+        console.log(`${label}: ${c.names.length} of ${c.of} differ in content (${c.names.slice(0, 3).join(", ")})  (@${code})`);
+      } else {
+        // Apple did not give a checksum back. Say so rather than reporting a match we did not establish.
+        console.log(`${label}: ${c.names.length} present, checksum not reported by Apple — content unverified  (@${code})`);
+      }
+    }
   }
+  // Previews by content too — the count comparison this replaces had the screenshot bug in miniature:
+  // one-local-vs-one-remote reads "in sync" however different the videos are, so a re-rendered App
+  // Preview reported nothing to do. `uploadAsset` commits md5(bytes) as sourceFileChecksum for
+  // previews exactly as it does for screenshots, so the same comparison is available for free.
   const { json: psets } = await client.get(`/v1/appStoreVersionLocalizations/${primary.id}/appPreviewSets?include=appPreviews&limit=50`);
+  const prevById = new Map((psets.included || []).filter((r) => r.type === "appPreviews").map((r) => [r.id, r.attributes || {}]));
   const remotePrev = {};
-  for (const s of psets.data || []) remotePrev[s.attributes.previewType] = (s.relationships?.appPreviews?.data || []).length;
+  for (const s of psets.data || []) {
+    remotePrev[s.attributes.previewType] = (s.relationships?.appPreviews?.data || [])
+      .map((ref) => prevById.get(ref.id)?.sourceFileChecksum ?? null);
+  }
   for (const spec of (config.previews || []).filter((s) => s.platform === platform && (s.locales || []).includes(config.primaryLocale))) {
-    const L = fs.existsSync(path.resolve(spec.file)) ? 1 : 0, R = remotePrev[spec.type] || 0;
-    if (L !== R) { diffs++; console.log(`  ${yellow("preview")} ${spec.type}: local ${L} / remote ${R}  (@${config.primaryLocale})`); }
+    const file = path.resolve(spec.file);
+    const L = fs.existsSync(file) ? 1 : 0;
+    const R = remotePrev[spec.type] || [];
+    const label = `  ${yellow("preview")} ${spec.type}`;
+    if (L !== R.length) {
+      diffs++;
+      console.log(`${label}: local ${L} / remote ${R.length}  (@${config.primaryLocale})`);
+    } else if (L === 1) {
+      if (R.every((sum) => sum === null)) {
+        console.log(`${label}: present, checksum not reported by Apple — content unverified`);
+      } else if (!R.includes(md5(fs.readFileSync(file)))) {
+        diffs++;
+        console.log(`${label}: differs in content (${path.basename(spec.file)})  (@${config.primaryLocale})`);
+      }
+    }
   }
   return diffs;
 }

package/src/commands/fill.mjs

@@ -4,12 +4,17 @@ import { green, yellow, red } from "../util.mjs";
 import { VALID } from "../locales.mjs";
 import { uploadAsset } from "../upload.mjs";
 import { reportCrossStore } from "../crossStore.mjs";
+import { deviceMap, screenshotBase, IMAGE_FILE } from "../screenshots.mjs";
 
-// Version-localization fields (attr -> metadata filename) and AppInfo fields (name/subtitle, shared).
+// Version-localization fields (attr -> metadata filename) and AppInfo fields (shared across releases).
 const VERSION_TXT = { description: "description", keywords: "keywords", promotionalText: "promotional_text", whatsNew: "release_notes", marketingUrl: "marketing_url", supportUrl: "support_url" };
-const INFO_TXT = { name: "name", subtitle: "subtitle" };
-const IOS_DEVICE = { iphone69: "APP_IPHONE_67", iphone65: "APP_IPHONE_65", ipad13: "APP_IPAD_PRO_3GEN_129", watch: "APP_WATCH_ULTRA" };
-const MAC_DEVICE = { macos: "APP_DESKTOP" };
+// `privacyPolicyUrl` belongs here rather than on the version because it is an APP-level fact, not a
+// per-release one. Apple blocks Add for Review without it ("You must enter a Privacy Policy URL in
+// App Privacy") — a wall you hit at the very end, once everything else is green, and one nothing in
+// vydanne could clear because this map stopped at name/subtitle. It is per-LOCALE all the same, so a
+// game with a single policy page writes the same line into each locale's `privacy_url.txt`; the
+// filename follows fastlane's own convention, so an existing metadata tree needs no rearranging.
+const INFO_TXT = { name: "name", subtitle: "subtitle", privacyPolicyUrl: "privacy_url" };
 
 /**
  * PATCH a localization, surviving attributes Apple refuses to edit RIGHT NOW.
@@ -61,25 +66,64 @@ export async function run(config, client) {
     console.error(red("fill: refusing to upload — fix the listing text, or set VYDANNE_ALLOW_CROSS_STORE=1."));
     return false;
   }
+  // No allowLive: name/subtitle live on the app-info record, and the live one must never take a PATCH
+  // (Apple would refuse each with INVALID_STATE, failing the whole locale — release notes included).
   const info = await client.appInfo();
+  // Said out loud, because the `if (info)` guard below otherwise skips name/subtitle for every locale
+  // in perfect silence — twenty locales of "written" with two fields quietly missing from each.
+  if (!info) console.log(yellow("  no editable app info — name/subtitle will be skipped (the live record is not writable)"));
   const infoLocs = info ? (await client.get(`/v1/appInfos/${info.id}/appInfoLocalizations?limit=200`)).json.data || [] : [];
 
   for (const platform of config.platforms) {
+    // No allowLive, deliberately: this is the command whose PATCHes would otherwise land on the listing
+    // customers are reading. Refusing is the whole point — an unwritten release note is recoverable, a
+    // rewritten live listing is not.
     const v = await client.editVersion(platform);
-    if (!v) { console.error(red(`fill ${platform}: no editable version`)); continue; }
-    console.log(green(`fill ${platform} (metadata=${!skipMeta} screenshots=${!skipShots})...`));
+    if (!v) {
+      console.error(red(`fill ${platform}: no editable version — refusing to write to the live listing.`));
+      console.error("  `vydanne prepare --apply` creates the version to fill, then re-run this.");
+      ok = false;
+      continue;
+    }
+    console.log(green(`fill ${platform} (metadata=${!skipMeta} screenshots=${!skipShots}) -> ${v.attributes.versionString} ${v.attributes.appStoreState}`));
     const verLocs = await client.versionLocalizations(v.id);
 
     if (!skipMeta) {
       let failed = 0;
       const dropped = new Set();
-      const dirs = fs.readdirSync(config.metadataDir, { withFileTypes: true }).filter((d) => d.isDirectory() && VALID.has(d.name)).map((d) => d.name);
+      // Guarded: a metadataDir that doesn't exist used to surface as a raw ENOENT stack from readdirSync
+      // — the Play half of this command has always said it in a sentence, and there is no reason the
+      // Apple half should be the one that throws.
+      if (!fs.existsSync(config.metadataDir)) {
+        console.error(red(`fill ${platform}: no metadata directory at ${config.metadataDir}`));
+        console.error("  Create it (one folder per App Store locale), or point `metadataDir` at yours.");
+        return false;
+      }
+      const all = fs.readdirSync(config.metadataDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+      const dirs = all.filter((d) => VALID.has(d));
+      // A folder Apple has no locale for is dropped from the upload — silently, until now. `de` instead
+      // of `de-DE` is the exact mistake locales.mjs calls the #1 gotcha, and the old filter made it look
+      // like the locale had simply been forgotten. Naming it costs one line and saves a release.
+      const strays = all.filter((d) => !VALID.has(d));
+      if (strays.length) console.log(yellow(`  ${strays.length} folder(s) are not App Store locale codes, skipped: ${strays.join(", ")} (\`vydanne locales\` lists the valid ones)`));
       for (const code of dirs) {
         const folder = path.join(config.metadataDir, code);
         const read = (f) => { const p = path.join(folder, `${f}.txt`); return fs.existsSync(p) ? fs.readFileSync(p, "utf8").replace(/\n+$/, "") : null; };
         // version localization (description/keywords/promo/whatsNew/urls)
         let vl = verLocs.find((l) => l.attributes.locale === code);
-        if (!vl) { const c = await client.post(`/v1/appStoreVersionLocalizations`, { data: { type: "appStoreVersionLocalizations", attributes: { locale: code }, relationships: { appStoreVersion: { data: { type: "appStoreVersions", id: v.id } } } } }); vl = c.json.data; verLocs.push(vl); }
+        if (!vl) {
+          const c = await client.post(`/v1/appStoreVersionLocalizations`, { data: { type: "appStoreVersionLocalizations", attributes: { locale: code }, relationships: { appStoreVersion: { data: { type: "appStoreVersions", id: v.id } } } } });
+          vl = c.json.data;
+          // A refused POST leaves `vl` undefined, and the PATCH below then reads `.id` off it — a raw
+          // TypeError that kills the whole fill on one bad locale. Report the locale Apple refused and
+          // carry on with the rest, the way every other per-locale failure here behaves.
+          if (!vl) {
+            console.error(red(`    ✗ ${code}: could not create localization — ${JSON.stringify(c.json?.errors?.[0]?.detail || c.json).slice(0, 160)}`));
+            failed++;
+            continue;
+          }
+          verLocs.push(vl);
+        }
         const vattrs = {};
         for (const [k, f] of Object.entries(VERSION_TXT)) { const t = read(f); if (t != null) vattrs[k] = t; }
         if (Object.keys(vattrs).length) {
@@ -117,19 +161,42 @@ export async function run(config, client) {
 }
 
 async function uploadScreenshots(config, client, platform, verLocs) {
-  const base = platform === "MAC_OS" ? "fastlane/screenshots-macos" : "fastlane/screenshots";
-  const DEV = platform === "MAC_OS" ? MAC_DEVICE : IOS_DEVICE;
+  const base = screenshotBase(platform, config);
+  const DEV = deviceMap(platform);
   if (!fs.existsSync(base)) return;
-  for (const code of fs.readdirSync(base).filter((d) => VALID.has(d))) {
+  const dirs = fs.readdirSync(base, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  const strays = dirs.filter((d) => !VALID.has(d));
+  if (strays.length) console.log(yellow(`    ${strays.length} screenshot folder(s) are not App Store locale codes, skipped: ${strays.join(", ")}`));
+  for (const code of dirs.filter((d) => VALID.has(d))) {
     const loc = verLocs.find((l) => l.attributes.locale === code);
-    if (!loc) continue;
-    const files = fs.readdirSync(path.join(base, code)).filter((f) => f.endsWith(".png")).sort();
+    // Said, not skipped: with VYDANNE_SKIP_METADATA=1 (or a screenshots folder for a locale that has no
+    // metadata folder) no localization was created above, and a silent `continue` here reports success
+    // for a locale whose screenshots never left the disk.
+    if (!loc) { console.log(yellow(`    ${code}: no App Store localization — screenshots skipped (run fill with metadata to create it)`)); continue; }
+    const files = fs.readdirSync(path.join(base, code)).filter((f) => IMAGE_FILE.test(f)).sort();
     const byDev = {};
-    for (const f of files) { const dt = DEV[f.split("_")[0]]; if (dt) (byDev[dt] ||= []).push(f); }
+    const unknown = [];
+    for (const f of files) { const dt = DEV[f.split("_")[0]]; dt ? (byDev[dt] ||= []).push(f) : unknown.push(f); }
+    // The prefix before the first underscore selects the device slot; a file with an unknown one used to
+    // vanish without a word — the docs even said "if a screenshot doesn't appear, check the name first",
+    // which is the tool telling the user to do its job. Name the files instead.
+    if (unknown.length) console.log(yellow(`    ${code}: ${unknown.length} file(s) with no device prefix, not uploaded: ${unknown.slice(0, 3).join(", ")}${unknown.length > 3 ? ", …" : ""} (known: ${Object.keys(DEV).join(", ")})`));
     const { json: sets } = await client.get(`/v1/appStoreVersionLocalizations/${loc.id}/appScreenshotSets?include=appScreenshots&limit=50`);
     for (const [dt, list] of Object.entries(byDev)) {
       let set = (sets.data || []).find((s) => s.attributes.screenshotDisplayType === dt);
-      if (set && (set.relationships?.appScreenshots?.data || []).length) continue; // never duplicate
+      // A populated slot used to `continue` unconditionally — "never duplicate", but it also meant a
+      // re-render could NEVER reach a listing that already had images, and because the skip happened
+      // before the log below, `fill` reported success having uploaded nothing. Same shape as previews
+      // now, and the same VYDANNE_REPLACE flag rather than a second one for the other asset kind.
+      const existing = set?.relationships?.appScreenshots?.data || [];
+      if (existing.length && process.env.VYDANNE_REPLACE !== "1") {
+        console.log(yellow(`    ${code}/${dt}: already has ${existing.length}, skipping (set VYDANNE_REPLACE=1 to replace)`));
+        continue;
+      }
+      for (const s of existing) { // VYDANNE_REPLACE: drop the old shots so the new upload takes their place
+        await client.del(`/v1/appScreenshots/${s.id}`);
+        console.log(yellow(`    ${code}/${dt}: ${client.dryRun ? "would remove" : "removed"} old screenshot ${s.id}`));
+      }
       if (!set) { const c = await client.post(`/v1/appScreenshotSets`, { data: { type: "appScreenshotSets", attributes: { screenshotDisplayType: dt }, relationships: { appStoreVersionLocalization: { data: { type: "appStoreVersionLocalizations", id: loc.id } } } } }); set = c.json.data; }
       for (const f of list) await uploadAsset(client, { type: "appScreenshots", setType: "appScreenshotSet", setId: set.id, filePath: path.join(base, code, f) });
       console.log(green(`    ${code}/${dt}: ${list.length} screenshots`));

package/src/commands/inspect.mjs

@@ -3,8 +3,10 @@ export async function run(config, client) {
   await client.findApp(config.bundleId);
   console.log(`APP ${client.app.attributes.name} (${config.bundleId})  id=${client.appId}  primary=${client.app.attributes.primaryLocale}`);
   for (const platform of config.platforms) {
-    const v = await client.editVersion(platform);
-    if (!v) { console.log(`  ${platform}: no editable version`); continue; }
+    // allowLive: this command's whole job is reporting what is in the store, and on an app with nothing
+    // in preparation the live version is the answer — not something to withhold.
+    const v = await client.editVersion(platform, { allowLive: true });
+    if (!v) { console.log(`  ${platform}: no version at all`); continue; }
     const locs = await client.versionLocalizations(v.id);
     console.log(`  ${platform}: v${v.attributes.versionString}  ${v.attributes.appStoreState}  localizations=${locs.length}`);
     const primary = locs.find((l) => l.attributes.locale === config.primaryLocale) || locs[0];

package/src/commands/preflight.mjs

@@ -1,5 +1,6 @@
 import { green, red, yellow, LIMITS, VERSION_FIELDS } from "../util.mjs";
 import { reportCrossStore } from "../crossStore.mjs";
+import { localScreenshots, remoteScreenshots, compareShots, localScreenshotLocales, unknownScreenshotDirs } from "../screenshots.mjs";
 
 // Verify a listing is submission-complete the CORRECT way — each localization read by id (not the sparse
 // list), char limits, primary-locale coverage, per-platform — and warn on the gotchas before ASC does.
@@ -8,10 +9,33 @@ export async function run(config, client) {
   const problems = [], notes = [];
   const res = config.resolvedLocales;
   if (res.unsupported.length) notes.push(`UI locales with no App Store listing (fall back to ${config.primaryLocale}): ${res.unsupported.join(", ")}`);
+  if (res.invalid?.length) problems.push(`localeMap points at code(s) Apple does not have: ${res.invalid.join(", ")}`);
+
+  // name/subtitle live on the APP-INFO record, not the version, which is why they were never checked
+  // here — LIMITS has carried a 30-char limit for each since the beginning and nothing read it, while
+  // the README listed them among the limits "checked before upload". Read-only, so `allowLive` is
+  // right: on an app with nothing in preparation the live record is the only one to measure.
+  const info = await client.appInfo({ allowLive: true });
+  if (info) {
+    const infoLocs = (await client.get(`/v1/appInfos/${info.id}/appInfoLocalizations?limit=200`)).json.data || [];
+    for (const il of infoLocs) {
+      const a = await client.localization(il.id, "appInfoLocalizations");
+      for (const f of ["name", "subtitle"]) {
+        const val = (a[f] || "").toString();
+        if (!val) { if (f === "name" && il.attributes.locale === config.primaryLocale) problems.push(`${il.attributes.locale}: name EMPTY`); continue; }
+        if (val.length > LIMITS[f]) problems.push(`${il.attributes.locale}: ${f} ${val.length}>${LIMITS[f]}`);
+      }
+    }
+  }
 
   for (const platform of config.platforms) {
+    // A blocker, and now reachable: this guard existed before but editVersion() handed back the LIVE
+    // version instead of null, so preflight validated the shipped listing and called it submittable.
     const v = await client.editVersion(platform);
-    if (!v) { problems.push(`${platform}: no editable version`); continue; }
+    if (!v) {
+      problems.push(`${platform}: no editable version — run \`vydanne prepare --apply\` to create one`);
+      continue;
+    }
     console.log(`  ${platform}: version ${v.attributes.versionString} (${v.attributes.appStoreState})`);
     const locs = await client.versionLocalizations(v.id);
     const ascLocales = [...new Set([config.primaryLocale, ...Object.values(res.supported)])];
@@ -27,11 +51,40 @@ export async function run(config, client) {
       }
     }
 
-    const primary = locs.find((l) => l.attributes.locale === config.primaryLocale);
-    if (primary) {
-      const { json } = await client.get(`/v1/appStoreVersionLocalizations/${primary.id}/appScreenshotSets?include=appScreenshots&limit=50`);
-      const count = (json.data || []).reduce((n, s) => n + (s.relationships?.appScreenshots?.data || []).length, 0);
-      if (!count) problems.push(`${platform}/${config.primaryLocale}: no screenshots`);
+    // EVERY locale with a local screenshot folder, not just the primary one.
+    //
+    // By CONTENT, not by count — the same comparison `diff` runs (src/screenshots.mjs), so the two
+    // cannot disagree about what "in sync" means. The count-only check that replaced called a STALE
+    // set green: a full local recapture left three-local-vs-three-remote, preflight said "no blockers",
+    // and the submission would have shipped the old art — which is precisely the state Niva sat in with
+    // store screenshots still showing a three-tier selector the app no longer had.
+    //
+    // Restricting that to `primaryLocale` left the same hole open one locale over, and `bridge` widened
+    // it: it populates a folder per translated locale, so a de-DE set re-rendered upstream but never
+    // re-uploaded passed green while the primary one was checked in full.
+    const shotLocales = [...new Set([config.primaryLocale, ...localScreenshotLocales(platform, config)])];
+    const strays = unknownScreenshotDirs(platform, config);
+    if (strays.length) notes.push(`${platform}: screenshot folder(s) that are not App Store locale codes, never uploaded: ${strays.join(", ")}`);
+
+    for (const code of shotLocales) {
+      const loc = locs.find((l) => l.attributes.locale === code);
+      if (!loc) continue; // a missing primary localization is already a blocker above
+      const remote = await remoteScreenshots(client, loc.id);
+      const count = Object.values(remote).reduce((n, m) => n + m.size, 0);
+      // Only the primary listing MUST have screenshots — Apple falls back to it for any locale without.
+      if (!count && code === config.primaryLocale) problems.push(`${platform}/${code}: no screenshots`);
+      // Freshness is judged only where a local set exists: no local screenshots means there is nothing
+      // to compare against, not that the store's are wrong. A display type the store has and local
+      // lacks is likewise left alone — `fill` never deletes by omission, so this does not flag it.
+      for (const [dt, L] of Object.entries(localScreenshots(platform, code, config))) {
+        const c = compareShots(L, remote[dt] || new Map());
+        if (!c) continue;
+        const slot = dt.replace("APP_", "");
+        if (c.kind === "count") problems.push(`${platform}/${code}: screenshots ${slot} local ${c.local} / remote ${c.remote} — the store set is not the local one (\`fill\`, VYDANNE_REPLACE=1 to replace)`);
+        else if (c.kind === "renamed") problems.push(`${platform}/${code}: screenshots ${slot} ${c.names.length} local file(s) not on the store by name (\`fill\`, VYDANNE_REPLACE=1 to replace)`);
+        else if (c.kind === "stale") problems.push(`${platform}/${code}: screenshots ${slot} STALE — ${c.names.length} of ${c.of} differ in content; green would ship the old art (\`fill\`, VYDANNE_REPLACE=1 to replace)`);
+        else notes.push(`${platform}/${code}: screenshots ${slot} present, checksum not reported by Apple — content unverified`);
+      }
     }
   }