vydanne 0.5.0 → 0.7.0

package/src/commands/diff.mjs

@@ -2,6 +2,8 @@ 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 = [
@@ -9,8 +11,6 @@ const VERSION_FIELDS = [
   ["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" };
 
 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 +19,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 +90,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

@@ -3,12 +3,12 @@ import path from "node:path";
 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).
 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" };
 
 /**
  * PATCH a localization, surviving attributes Apple refuses to edit RIGHT NOW.
@@ -50,25 +50,74 @@ export async function run(config, client) {
   let ok = true; // a locale Apple refused must fail the command, not just print
   const skipMeta = process.env.VYDANNE_SKIP_METADATA === "1";
   const skipShots = process.env.VYDANNE_SKIP_SCREENSHOTS === "1";
+
+  // Checked here and not only in preflight, because preflight is something you REMEMBER to run and
+  // this is the thing that actually uploads. A cross-store reference costs a review cycle, and it
+  // is free to catch one function call earlier. VYDANNE_ALLOW_CROSS_STORE=1 is the deliberate
+  // override for the rare listing that genuinely needs the word.
+  if (!skipMeta && process.env.VYDANNE_ALLOW_CROSS_STORE !== "1"
+      && !reportCrossStore("apple", config.metadataDir, config.allowCrossStoreTerms)) {
+    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) {
@@ -106,19 +155,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,4 +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.
@@ -7,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)])];
@@ -26,14 +51,48 @@ 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`);
+      }
     }
   }
 
+  // Local copy that is about to be uploaded, checked before it can earn a rejection.
+  if (!reportCrossStore("apple", config.metadataDir, config.allowCrossStoreTerms)) {
+    problems.push("listing text references another mobile platform (see above)");
+  }
+
   console.log();
   if (!problems.length) console.log(green("preflight: no blockers"));
   else { console.log(red(`preflight: ${problems.length} blocker(s)`)); problems.forEach((p) => console.log(`  ${red("x")} ${p}`)); }

package/src/commands/prepare.mjs

@@ -0,0 +1,220 @@
+import fs from "node:fs";
+import path from "node:path";
+import { green, yellow, red } from "../util.mjs";
+import { pointVersionAtBuild, LOCKED_STATES } from "./prerelease.mjs";
+
+/**
+ * Create — or reuse — the App Store version you are preparing, and point it at a build.
+ *
+ * THE GAP THIS CLOSES. Every other Apple command edits *the version being prepared*, which it finds
+ * through `client.editVersion()`. On an app whose only version is already on sale there is nothing
+ * editable to return, so that call falls back to the live record — and then `fill` aims its
+ * description/whatsNew PATCHes at the version customers are looking at, while `prerelease` declines
+ * to attach the build it just uploaded ("no editable App Store version — build uploaded, nothing to
+ * attach it to"). Neither command can recover on its own, because the thing that is missing is a
+ * *version*, and nothing in vydanne ever created one. So preparing a second release always started
+ * with a trip to the App Store Connect web UI — exactly the manual step this tool exists to delete.
+ *
+ * WHAT IT IS NOT. Creating a version is not submitting one. The record this POSTs lands in
+ * PREPARE_FOR_SUBMISSION: an editable draft, and the state `fill`, `previews` and `review-contact`
+ * all need before they can write anything. `releaseType: MANUAL` then keeps the release itself a
+ * human act even after Apple approves it. Add to Review and Submit stay exactly where they were —
+ * with you. There is no argument to this command that reaches a reviewer or the public.
+ *
+ * WHERE THE NUMBER COMES FROM. The newest build Apple holds, read off its preReleaseVersion — which
+ * is the archive's own CFBundleShortVersionString. The marketing version therefore travels with the
+ * binary, the same way `prerelease` already lets the build number travel with it: Apple assigns
+ * nothing and neither do we, so there is no second place to keep the number in step. Preparing a
+ * version *before* its build exists is the one case that needs telling, hence VYDANNE_VERSION.
+ *
+ * RE-RUNNING IS THE POINT. Find-or-create means the command is idempotent: run it before the build
+ * exists to get an empty draft, run it again after `prerelease` to attach the binary, run it a third
+ * time and it reports that everything already matches. And once the draft exists, `prerelease`
+ * attaches to it unaided — `editVersion()` starts finding a real editable version, so the "nothing
+ * to attach it to" dead end disappears for every future release too.
+ */
+
+/** How the CLI is meant to be driven, printed wherever the command can't finish the job itself. */
+const NEXT_STEPS = [
+  "  next: `vydanne fill --apply` for metadata, then Add to Review + Submit in App Store Connect.",
+];
+
+/** Every version Apple holds for this platform. Deliberately NOT `editVersion()`, which collapses the
+ *  list to a single guess — finding a specific versionString is the whole job here. */
+async function versionsFor(client, platform) {
+  const { json } = await client.get(
+    `/v1/apps/${client.appId}/appStoreVersions?filter[platform]=${platform}&limit=200` +
+      `&fields[appStoreVersions]=versionString,appStoreState`,
+  );
+  return json.data || [];
+}
+
+/** The newest build, together with the marketing version its archive declares. */
+async function newestBuildWithVersion(client) {
+  const { json } = await client.get(
+    `/v1/builds?filter[app]=${client.appId}&sort=-uploadedDate&limit=1` +
+      `&fields[builds]=version,processingState&include=preReleaseVersion` +
+      `&fields[preReleaseVersions]=version`,
+  );
+  const build = json.data?.[0] ?? null;
+  const marketing =
+    json.included?.find((r) => r.type === "preReleaseVersions")?.attributes?.version ?? null;
+  return { build, marketing };
+}
+
+/** `<metadataDir>/copyright.txt`, the same supply convention `fill` reads listing text from. */
+function readCopyright(config) {
+  if (!config.metadataDir) return null;
+  const p = path.join(config.metadataDir, "copyright.txt");
+  if (!fs.existsSync(p)) return null;
+  return fs.readFileSync(p, "utf8").trim() || null;
+}
+
+/**
+ * Is `a` a higher marketing version than `b`?
+ *
+ * Compared component-wise as NUMBERS, because Apple refuses a versionString that does not exceed the
+ * one on sale and a string compare gets the interesting case backwards: "1.10" < "1.9" as text, and
+ * 1.10 > 1.9 as a version. Worth a pre-check rather than a 409 the operator has to decode.
+ */
+export function isHigherVersion(a, b) {
+  const pa = String(a).split(".").map((n) => Number(n) || 0);
+  const pb = String(b).split(".").map((n) => Number(n) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x !== y) return x > y;
+  }
+  return false;
+}
+
+/**
+ * Find the version called `versionString`, or create it. Returns the version record, or null when it
+ * exists but Apple has locked it — a state only the operator can leave, by withdrawing in the UI.
+ */
+export async function ensureVersion(client, config, platform, versionString) {
+  const existing = (await versionsFor(client, platform)).find(
+    (v) => v.attributes.versionString === versionString,
+  );
+
+  if (existing) {
+    const state = existing.attributes.appStoreState;
+    // Reusing prerelease's LOCKED_STATES rather than enumerating the editable states here: one list
+    // to keep right, and it is already the list that decides whether a build may be re-pointed.
+    if (LOCKED_STATES.has(state)) {
+      console.error(red(`  version ${versionString} is ${state} — Apple will not let it be edited.`));
+      // Two locked cases, two different fixes — telling someone to "withdraw" a version that is ON
+      // SALE is advice they cannot take. Shipped once already means the next release needs a HIGHER
+      // number, which is the everyday case: the newest build still declares the shipped version
+      // because MARKETING_VERSION was never bumped after release.
+      if (state === "READY_FOR_SALE" || state === "REPLACED_WITH_NEW_VERSION") {
+        console.error(`  That version has shipped; the next release needs a higher number. Bump`);
+        console.error(`  MARKETING_VERSION and re-archive — or name it now: VYDANNE_VERSION=<next> vydanne prepare --apply`);
+      } else {
+        console.error("  Withdrawing that submission has reviewer-facing consequences, so it stays your");
+        console.error("  call: withdraw it in App Store Connect, then re-run this.");
+      }
+      return null;
+    }
+    console.log(green(`  version ${versionString} already exists (${state}) — reusing it`));
+    return existing;
+  }
+
+  const attributes = { platform, versionString, releaseType: "MANUAL" };
+  // Set at creation because it is a version-level field: nothing else in vydanne writes `copyright`,
+  // and a version submitted without one is a metadata rejection waiting to happen.
+  const copyright = readCopyright(config);
+  if (copyright) attributes.copyright = copyright;
+
+  const r = await client.post(`/v1/appStoreVersions`, {
+    data: {
+      type: "appStoreVersions",
+      attributes,
+      relationships: { app: { data: { type: "apps", id: client.appId } } },
+    },
+  });
+
+  if (r.status >= 300) {
+    console.error(red(`  could not create version ${versionString} (${r.status})`));
+    for (const e of r.json?.errors || []) console.error(`    ${e.title}: ${e.detail}`);
+    return null;
+  }
+
+  const how = copyright ? ", copyright set" : "";
+  // Said in the tense that happened. A dry run reported "created version 1.2" in green immediately
+  // after saying it would POST one — two lines that contradict each other, and the green one is the
+  // one people remember.
+  console.log(client.dryRun
+    ? yellow(`  WOULD create version ${versionString} — PREPARE_FOR_SUBMISSION, releaseType MANUAL${how}`)
+    : green(`  created version ${versionString} — PREPARE_FOR_SUBMISSION, releaseType MANUAL${how}`));
+  return r.json.data;
+}
+
+export async function run(config, client) {
+  await client.findApp(config.bundleId);
+  // EVERY declared platform. iOS and macOS are separate App Store versions with separate records, and
+  // preparing only `platforms[0]` left the second one with nothing editable — so `fill MAC_OS` refused
+  // ("no editable version") on an app whose iOS draft had just been created, and `push` stopped there.
+  // `fill`, `previews` and `preflight` have always looped; this is the command that creates what they
+  // loop over.
+  let ok = true;
+  for (const platform of config.platforms) {
+    if (!(await prepareOne(config, client, platform))) ok = false;
+  }
+  if (!ok) return false;
+
+  console.log("prepare done — the version is editable.");
+  for (const line of NEXT_STEPS) console.log(line);
+  console.log(yellow("  Submitting for App Store review stays manual, by design."));
+  return true;
+}
+
+async function prepareOne(config, client, platform) {
+  console.log(green(`prepare → App Store version (${platform})`));
+
+  const { build, marketing } = await newestBuildWithVersion(client);
+  const target = process.env.VYDANNE_VERSION || marketing;
+
+  if (!target) {
+    console.error(red("prepare: nothing tells me which version to prepare."));
+    console.error("  Apple holds no build to read a marketing version from. Either upload one —");
+    console.error("  `vydanne prerelease --apply` — or name the version yourself:");
+    console.error("    VYDANNE_VERSION=1.2 vydanne prepare --apply");
+    return false;
+  }
+
+  const source = process.env.VYDANNE_VERSION ? "VYDANNE_VERSION" : `build ${build?.attributes?.version}`;
+  console.log(`  preparing ${target}  (from ${source})`);
+
+  // The version on sale is the floor Apple enforces. Checking it here turns an opaque 409 into a
+  // sentence, and catches the likelier mistake: forgetting to bump MARKETING_VERSION before archiving.
+  const versions = await versionsFor(client, platform);
+  const live = versions.find((v) => v.attributes.appStoreState === "READY_FOR_SALE");
+  if (live && live.attributes.versionString !== target && !isHigherVersion(target, live.attributes.versionString)) {
+    console.error(red(`  ${target} does not exceed ${live.attributes.versionString}, which is on sale.`));
+    console.error("  Apple only accepts a higher version. Bump MARKETING_VERSION, re-archive, re-upload.");
+    return false;
+  }
+  if (live) console.log(`  on sale: ${live.attributes.versionString}`);
+
+  const version = await ensureVersion(client, config, platform, target);
+  if (!version) return false;
+
+  if (!build) {
+    console.log(yellow("  no build uploaded yet — the version is ready for one."));
+    console.log("  `vydanne prerelease --apply` will upload it and attach it to this version.");
+  } else if (marketing && marketing !== target) {
+    // The newest build belongs to a DIFFERENT marketing version — almost always because the archive for
+    // this one has not been uploaded yet, and VYDANNE_VERSION named the version ahead of its binary.
+    // Attaching it would put the previous release's binary behind the new version's number: Apple rejects
+    // that at submission, and it is a confusing thing to debug from the reviewer's message.
+    console.log(yellow(`  build ${build.attributes.version} declares ${marketing}, not ${target} — not attaching it.`));
+    console.log(`  Archive ${target} and upload it (\`vydanne prerelease --apply\`); this version is waiting.`);
+  } else if (build.attributes.processingState === "PROCESSING") {
+    console.log(yellow(`  build ${build.attributes.version} is still PROCESSING — not attaching it yet.`));
+    console.log("  Re-run once Apple finishes, or let `vydanne prerelease --apply` attach it.");
+  } else {
+    await pointVersionAtBuild(client, config, build, version);
+  }
+  return true;
+}