vydanne 0.6.0 → 0.7.0

package/src/commands/fill.mjs

@@ -4,12 +4,11 @@ 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.
@@ -61,25 +60,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 +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,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`);
+      }
     }
   }
 

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;
+}

package/src/commands/prerelease.mjs

@@ -127,7 +127,7 @@ export async function run(config, client, credentials) {
     // right answer for an accident and a dead end for a re-run, so say which it is.
     if (/already exists|redundant binary|previously uploaded/i.test(text)) {
       console.error(red("  Apple already holds this build number."));
-      console.error("  Bump CFBundleVersion (Scripts/build-number.sh in the games) and re-archive.");
+      console.error("  Bump CFBundleVersion (the build number, not the marketing version) and re-archive.");
     } else {
       console.error(red("  upload failed:"));
       console.error(indent(text));
@@ -207,14 +207,21 @@ async function assignToInternalGroup(client, build, groupName) {
   else console.error(yellow(`  could not add to "${groupName}" (${r.status})`));
 }
 
-/** Versions Apple will not let us re-point without the operator withdrawing them first. */
-const LOCKED_STATES = new Set([
+/** Versions Apple will not let us re-point without the operator withdrawing them first. Exported
+ *  because `prepare` needs the same answer about the same states — two lists would drift. */
+export const LOCKED_STATES = new Set([
   "WAITING_FOR_REVIEW",
   "IN_REVIEW",
   "PENDING_DEVELOPER_RELEASE",
   "PENDING_APPLE_RELEASE",
   "READY_FOR_SALE",
   "REPLACED_WITH_NEW_VERSION",
+  // Both removed-from-sale states are shipped versions that Apple will not reopen for editing.
+  // client.mjs has always treated them as dead for `editVersion()`; leaving them out here meant
+  // `prepare` would "reuse" one and hand every later step a version whose first write Apple refuses —
+  // the refusal arriving as an opaque INVALID_STATE instead of the sentence below it.
+  "REMOVED_FROM_SALE",
+  "DEVELOPER_REMOVED_FROM_SALE",
 ]);
 
 /**
@@ -222,12 +229,17 @@ const LOCKED_STATES = new Set([
  *
  * This is what makes "upload a fix and try again" one command rather than a trip to the web UI:
  * the version → build relationship holds exactly one build, so a PATCH re-points it.
+ *
+ * [known] is the version to attach to, when the caller has already resolved it. `prepare` passes the
+ * draft it just found or created, because `editVersion()` cannot tell a fresh draft from the live
+ * record on an app that already has a version on sale — it returns whichever the list yields first.
  */
-export async function pointVersionAtBuild(client, config, build) {
+export async function pointVersionAtBuild(client, config, build, known = null) {
   const platform = (config.platforms && config.platforms[0]) || "IOS";
-  const version = await client.editVersion(platform);
+  const version = known || (await client.editVersion(platform));
   if (!version) {
     console.log(yellow("  no editable App Store version — build uploaded, nothing to attach it to."));
+    console.log("  `vydanne prepare --apply` creates the version to attach it to, then re-run this.");
     return;
   }
   const state = version.attributes.appStoreState;

package/src/commands/previews.mjs

@@ -5,16 +5,40 @@ import { uploadAsset, setPreviewPoster } from "../upload.mjs";
 
 // Upload App Preview videos natively (reserve → chunked PUT → commit → poll processing → poster frame).
 // config.previews: [{ platform, type, file, poster, locales }]. Skips locales that already have a preview.
+//
+// EVERY failure below is recorded, not just printed. This command used to `return true` unconditionally:
+// each error path printed red and `continue`d, so a rejected upload was indistinguishable from a clean
+// run to the one caller that asks — `push`, which promises to stop at the first failing step. It didn't:
+// previews could fail loudly, push would carry on through age-rating/review-contact/accessibility, and
+// preflight (which never inspects previews) would sign the whole thing off as green. The `continue`s are
+// still right — one missing video must not hide the state of the rest — but the verdict has to survive
+// them, so the loop keeps going and the RETURN carries the failure out.
 export async function run(config, client) {
   await client.findApp(config.bundleId);
   const specs = config.previews || defaultSpecs(config);
+  const failures = [];
+  // defaultSpecs filters to files that exist, so with no `previews` config and no video on disk this
+  // command used to print NOTHING and exit 0 — indistinguishable from a successful upload in a CI log.
+  // Not a failure: an app with no previews is a normal app, and `push` must not stall on one.
+  if (!specs.length) console.log(yellow("  no previews configured and none found at the default paths — nothing to upload."));
   for (const s of specs) {
     const v = await client.editVersion(s.platform);
-    if (!v) { console.error(red(`  ${s.platform}: no version`)); continue; }
+    if (!v) {
+      console.error(red(`  ${s.platform}: no editable version — nothing to upload previews to.`));
+      console.error("  `vydanne prepare --apply` creates the version being submitted, then re-run this.");
+      failures.push(`${s.platform}: no editable version`);
+      continue;
+    }
     const locs = await client.versionLocalizations(v.id);
     for (const code of s.locales || [config.primaryLocale]) {
       const loc = locs.find((l) => l.attributes.locale === code);
-      if (!loc) continue;
+      // A configured locale the version doesn't have must be said, not skipped — the spec NAMES this
+      // locale, so silence here reports success for a preview that never left the disk.
+      if (!loc) {
+        console.error(red(`  ${s.platform}/${code}: no App Store localization — preview skipped (run \`fill\` to create it)`));
+        failures.push(`${s.platform}/${code}: no App Store localization`);
+        continue;
+      }
       try {
         const { json: sets } = await client.get(`/v1/appStoreVersionLocalizations/${loc.id}/appPreviewSets?include=appPreviews&limit=50`);
         let set = (sets.data || []).find((x) => x.attributes.previewType === s.type);
@@ -36,6 +60,7 @@ export async function run(config, client) {
         // works. Name it and move on, so one missing video doesn't hide the rest of the report.
         if (!fs.existsSync(file)) {
           console.error(red(`  ${s.platform}/${code}/${s.type}: ${path.relative(process.cwd(), file)} does not exist — nothing to upload`));
+          failures.push(`${s.platform}/${code}/${s.type}: ${path.relative(process.cwd(), file)} missing`);
           continue;
         }
         console.log(`  ${s.platform}/${code}/${s.type}: ${client.dryRun ? "would upload" : "uploading"} ${path.basename(file)}...`);
@@ -44,9 +69,15 @@ export async function run(config, client) {
         if (!client.dryRun) console.log(green(`    done ${s.platform}/${code}/${s.type}`));
       } catch (e) {
         console.error(red(`    error ${s.platform}/${code}/${s.type}: ${e.message}`));
+        failures.push(`${s.platform}/${code}/${s.type}: ${e.message}`);
       }
     }
   }
+  if (failures.length) {
+    console.error(red(`previews: ${failures.length} failed — nothing above was silently skipped:`));
+    for (const f of failures) console.error(`  ${red("x")} ${f}`);
+    return false;
+  }
   return true;
 }