vydanne 0.5.0 → 0.7.0

package/src/commands/prerelease.mjs

@@ -110,6 +110,14 @@ export async function run(config, client, credentials) {
     return false;
   }
 
+  // The binary upload is the one mutation that does NOT go through the ASC client, so the client-level
+  // dry-run gate cannot see it — it has to be refused here, or a dry run would ship a build to TestFlight.
+  // Validation above has already run, which is the useful half: exactly Play's "validate, then discard".
+  if (client.dryRun) {
+    console.log(yellow("  DRY RUN — archive validated, NOT uploaded. Re-run with --apply to send it to TestFlight."));
+    return true;
+  }
+
   try {
     await altool(["--upload-app", "-f", ipa, "-t", "ios"], credentials);
     console.log(green("  uploaded"));
@@ -119,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));
@@ -199,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",
 ]);
 
 /**
@@ -214,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);
@@ -24,22 +48,36 @@ export async function run(config, client) {
         }
         for (const p of existing) { // VYDANNE_REPLACE: drop the old preview so the new upload takes its place
           await client.del(`/v1/appPreviews/${p.id}`);
-          console.log(yellow(`  ${s.platform}/${code}/${s.type}: removed old preview ${p.id}`));
+          console.log(yellow(`  ${s.platform}/${code}/${s.type}: ${client.dryRun ? "would remove" : "removed"} old preview ${p.id}`));
         }
         if (!set) {
           const c = await client.post(`/v1/appPreviewSets`, { data: { type: "appPreviewSets", attributes: { previewType: s.type }, relationships: { appStoreVersionLocalization: { data: { type: "appStoreVersionLocalizations", id: loc.id } } } } });
           set = c.json.data;
         }
         const file = path.resolve(s.file);
-        console.log(`  ${s.platform}/${code}/${s.type}: uploading ${path.basename(file)}...`);
+        // A configured preview whose file is missing is the whole reason this is checked here: the
+        // upload would throw ENOENT mid-run, and in a DRY run it would otherwise look like a plan that
+        // 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)}...`);
         const id = await uploadAsset(client, { type: "appPreviews", setType: "appPreviewSet", setId: set.id, filePath: file });
         await setPreviewPoster(client, id, s.poster);
-        console.log(green(`    done ${s.platform}/${code}/${s.type}`));
+        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;
 }
 

package/src/commands/privacy.mjs

@@ -2,26 +2,96 @@ import fs from "node:fs";
 import path from "node:path";
 import { green, yellow } from "../util.mjs";
 
-// App Privacy is on Apple's iris host, which 401s the JWT — it CANNOT be set with the ASC API key. Write
-// the honest record + print the exact ASC-UI answers (a passkey login works there).
-const GROUP = { CRASH_DATA: "Diagnostics", PERFORMANCE_DATA: "Diagnostics", OTHER_DIAGNOSTIC_DATA: "Diagnostics" };
+/**
+ * App Privacy is on Apple's iris host, which 401s the ASC API key — it CANNOT be set through the API.
+ * So this writes the honest record and prints the exact answers to type into the ASC UI (where a
+ * passkey login works).
+ *
+ * PURPOSES ARE DECLARED, NOT ASSUMED. Every collected category used to be reported as
+ * "APP_FUNCTIONALITY", which is right for crash data in a game and wrong for almost anything else — an
+ * email address collected for marketing, or location used for analytics, would have been printed as
+ * App Functionality and typed into Apple's form that way. And the UI group was known only for the three
+ * diagnostics categories, so anything else printed a literal "?" as its section heading, which is not
+ * an answer anyone can enter. Both are now data tables covering Apple's full vocabulary, with
+ * per-category overrides in the config for the app that needs them.
+ */
+
+/** Apple's data categories -> the section they live under in the App Privacy form. */
+const GROUP = {
+  // Contact info
+  NAME: "Contact Info", EMAIL_ADDRESS: "Contact Info", PHONE_NUMBER: "Contact Info",
+  PHYSICAL_ADDRESS: "Contact Info", OTHER_USER_CONTACT_INFO: "Contact Info",
+  // Health & fitness
+  HEALTH: "Health & Fitness", FITNESS: "Health & Fitness",
+  // Financial info
+  PAYMENT_INFO: "Financial Info", CREDIT_INFO: "Financial Info", OTHER_FINANCIAL_INFO: "Financial Info",
+  // Location
+  PRECISE_LOCATION: "Location", COARSE_LOCATION: "Location",
+  // Sensitive info
+  SENSITIVE_INFO: "Sensitive Info",
+  // Contacts
+  CONTACTS: "Contacts",
+  // User content
+  EMAILS_OR_TEXT_MESSAGES: "User Content", PHOTOS_OR_VIDEOS: "User Content", AUDIO_DATA: "User Content",
+  GAMEPLAY_CONTENT: "User Content", CUSTOMER_SUPPORT: "User Content", OTHER_USER_CONTENT: "User Content",
+  // Browsing / search history
+  BROWSING_HISTORY: "Browsing History", SEARCH_HISTORY: "Search History",
+  // Identifiers
+  USER_ID: "Identifiers", DEVICE_ID: "Identifiers",
+  // Purchases
+  PURCHASE_HISTORY: "Purchases",
+  // Usage data
+  PRODUCT_INTERACTION: "Usage Data", ADVERTISING_DATA: "Usage Data", OTHER_USAGE_DATA: "Usage Data",
+  // Diagnostics
+  CRASH_DATA: "Diagnostics", PERFORMANCE_DATA: "Diagnostics", OTHER_DIAGNOSTIC_DATA: "Diagnostics",
+  // Other
+  OTHER_DATA_TYPES: "Other Data",
+};
+
+/** Apple's purpose codes -> the label the form uses. */
+const PURPOSE_LABEL = {
+  THIRD_PARTY_ADVERTISING: "Third-Party Advertising",
+  DEVELOPERS_ADVERTISING: "Developer's Advertising or Marketing",
+  ANALYTICS: "Analytics",
+  PRODUCT_PERSONALIZATION: "Product Personalization",
+  APP_FUNCTIONALITY: "App Functionality",
+  OTHER_PURPOSES: "Other Purposes",
+};
 
 export async function run(config) {
   const collected = config.privacy?.collected || ["CRASH_DATA", "PERFORMANCE_DATA"];
   const tracking = !!config.privacy?.tracking;
+  // `purposes` may be one list for everything, or a per-category map. App Functionality stays the
+  // default because it is the honest answer for the diagnostics an app collects to fix itself — but it
+  // is now a default that an app can disagree with, rather than the only thing this command can say.
+  const declared = config.privacy?.purposes;
+  const purposesFor = (cat) => {
+    const p = Array.isArray(declared) ? declared : declared?.[cat];
+    return (p && p.length ? p : ["APP_FUNCTIONALITY"]);
+  };
+
   const record = collected.map((cat) => ({
-    category: cat, purposes: ["APP_FUNCTIONALITY"],
+    category: cat,
+    purposes: purposesFor(cat),
     data_protections: [tracking ? "DATA_LINKED_TO_YOU" : "DATA_NOT_LINKED_TO_YOU", tracking ? "DATA_USED_TO_TRACK_YOU" : null].filter(Boolean),
   }));
   const out = path.join(path.dirname(config.metadataDir), "app_privacy_details.json");
   fs.writeFileSync(out, JSON.stringify(record, null, 2));
   console.log(green(`wrote ${out} (declaration record)`));
   console.log();
+
+  const unknown = collected.filter((c) => !GROUP[c]);
+  if (unknown.length) {
+    console.log(yellow(`  category not in Apple's published list, section unknown: ${unknown.join(", ")}`));
+    console.log("  Check the spelling against App Privacy in App Store Connect before entering it.");
+  }
+
   console.log(yellow("App Privacy is UI-only (passkey) — the API key 401s on Apple's iris host. Enter:"));
   if (collected.length) console.log("  Do you or your partners collect data? -> Yes");
   for (const c of collected) {
     const name = c.split("_").map((w) => w[0] + w.slice(1).toLowerCase()).join(" ");
-    console.log(`  ${GROUP[c] || "?"} -> ${name}: App Functionality · ${tracking ? "Linked" : "Not Linked"} · ${tracking ? "Tracking" : "No Tracking"}`);
+    const purposes = purposesFor(c).map((p) => PURPOSE_LABEL[p] || p).join(" + ");
+    console.log(`  ${GROUP[c] || "?"} -> ${name}: ${purposes} · ${tracking ? "Linked" : "Not Linked"} · ${tracking ? "Tracking" : "No Tracking"}`);
   }
   console.log("  Everything else -> Not Collected.");
   console.log(yellow("  'accesses' is not 'collects' — E2EE content you can't read is not collected."));

package/src/commands/push.mjs

@@ -0,0 +1,118 @@
+import { green, yellow, red } from "../util.mjs";
+import { run as prepare } from "./prepare.mjs";
+import { run as fill } from "./fill.mjs";
+import { run as previews } from "./previews.mjs";
+import { run as ageRating } from "./ageRating.mjs";
+import { run as reviewContact } from "./reviewContact.mjs";
+import { run as accessibility } from "./accessibility.mjs";
+import { run as preflight } from "./preflight.mjs";
+
+/**
+ * The whole Apple release pipeline, in the one order that works.
+ *
+ * WHY A COMMAND AND NOT A PARAGRAPH. Shipping an update takes seven commands in a specific order —
+ * `prepare` first (or nothing has a version to write into), `preflight` last (or green is measured
+ * before the writes it is meant to bless) — and that ordering lived in nobody's head. The near-miss
+ * that proved it: with the order forgotten, `fill` was pointed at an app whose only version was ON
+ * SALE, and only the editVersion() fix stood between the dry run and a rewritten live listing. A
+ * README section can teach the order; only a command can make it impossible to run out of order.
+ *
+ * WHAT IT IS. A sequencer, nothing more: each step is the same `run` its standalone command uses, on
+ * the same client, so `push` can do nothing a step couldn't. The first failure stops the run — a step
+ * that cannot proceed says why and names its fix (that is each command's own contract), and continuing
+ * past it would let a green `preflight` at the end bless a release with a known hole in it.
+ *
+ * SKIPPING IS EXPLICIT AND LOUD. `--skip <step>[,<step>]` (or `push: { skip: [...] }`) drops a step
+ * from the run. This exists because a pipeline with no way out is a pipeline that stops working the
+ * moment one step legitimately does not apply to an app: `accessibility` refuses when no block is
+ * declared — correctly, it publishes claims — so an app that has not audited its accessibility could
+ * not complete `push` at all, and neither could one with no App Review PII on disk. The skip is named
+ * on every line of the report and again at the end, because the whole value of the last step is that
+ * green means green: a run that skipped something must never read like a run that did everything.
+ *
+ * WHAT IT IS NOT. It never submits — the pipeline ends at `preflight`, and Add to Review + Submit
+ * stay in App Store Connect, human-only, exactly as every step's own refusals already guarantee.
+ * `prerelease` (the build upload) is deliberately not a step: it is macOS-only, shells out to altool,
+ * and belongs wherever the archive is produced. Run it whenever the build is ready — before or after
+ * `push`; `prepare` attaches the newest build either way.
+ *
+ * Dry-run composes: without --apply the shared client refuses every mutation, each step reports its
+ * plan, and bin/ prints the withheld-write count at the end. The one case a dry run cannot preview
+ * past is an app with no editable version — the draft the later steps target does not exist until
+ * `prepare` is APPLIED — so that is said up front rather than discovered as a refusal mid-run.
+ */
+const STEPS = [
+  ["prepare", prepare],
+  ["fill", fill],
+  ["previews", previews],
+  ["age-rating", ageRating],
+  ["review-contact", reviewContact],
+  ["accessibility", accessibility],
+  ["preflight", preflight],
+];
+
+/** Steps named by `--skip a,b` and/or `push.skip` in the config, validated against the real step list. */
+function resolveSkips(config) {
+  const flag = process.argv.find((a) => a.startsWith("--skip="))?.slice("--skip=".length)
+    ?? (process.argv.includes("--skip") ? process.argv[process.argv.indexOf("--skip") + 1] : null);
+  const named = [
+    ...(flag ? String(flag).split(",") : []),
+    ...(config.push?.skip || []),
+  ].map((s) => s.trim()).filter(Boolean);
+  const names = STEPS.map(([n]) => n);
+  const unknown = named.filter((s) => !names.includes(s));
+  return { skip: new Set(named.filter((s) => names.includes(s))), unknown };
+}
+
+export async function run(config, client) {
+  await client.findApp(config.bundleId);
+  const { skip, unknown } = resolveSkips(config);
+  if (unknown.length) {
+    console.error(red(`push: --skip named step(s) that do not exist: ${unknown.join(", ")}`));
+    console.error(`  Steps: ${STEPS.map(([n]) => n).join(", ")}`);
+    return false;
+  }
+  // Skipping the last step would make the command's own promise unverifiable, and skipping the first
+  // leaves every later step writing into a version that may not exist. Both are refusals rather than
+  // warnings: there is no reading of "push, but don't check the result" that is worth supporting.
+  for (const required of ["prepare", "preflight"]) {
+    if (skip.has(required)) {
+      console.error(red(`push: \`${required}\` cannot be skipped — run the other steps individually if that is what you want.`));
+      return false;
+    }
+  }
+
+  const platform = (config.platforms && config.platforms[0]) || "IOS";
+  if (client.dryRun && !(await client.editVersion(platform))) {
+    console.log(yellow("push: no editable App Store version exists, so this dry run will stop where the draft is needed."));
+    console.log("  `vydanne prepare --apply` creates it — a draft, not a submission — then re-run `vydanne push`");
+    console.log("  to preview the rest of the pipeline.");
+  }
+
+  const skipped = [];
+  for (const [name, step] of STEPS) {
+    if (skip.has(name)) {
+      console.log(yellow(`\n▸ push: ${name} — SKIPPED (--skip)`));
+      skipped.push(name);
+      continue;
+    }
+    console.log(green(`\n▸ push: ${name}`));
+    const ok = await step(config, client);
+    if (ok === false) {
+      console.error(red(`\npush: stopped at \`${name}\` — fix what it reported above, then re-run \`vydanne push\`.`));
+      console.error("  Every completed step is idempotent, so re-running repeats nothing destructive.");
+      if (name === "age-rating" && !config.ageRating && config.rating !== "4+") {
+        console.error(`  For a '${config.rating}' rating, declare the content descriptors in \`ageRating\` — see the message above.`);
+      }
+      console.error(`  Or drop this step for now: \`vydanne push --apply --skip ${name}\``);
+      return false;
+    }
+  }
+
+  console.log(green("\npush done — the release is staged and preflight is green."));
+  // Repeated at the end on purpose. The one thing this command sells is that its last line means the
+  // release is ready; a skipped step is precisely the case where that would otherwise overstate it.
+  if (skipped.length) console.log(yellow(`  NOT green for: ${skipped.join(", ")} — skipped, never run. Run them before you submit.`));
+  console.log(yellow("  Submitting stays yours: App Store Connect → the prepared version → Add to Review → Submit."));
+  return true;
+}

package/src/commands/reviewContact.mjs

@@ -1,27 +1,78 @@
 import fs from "node:fs";
 import path from "node:path";
-import { green, red } from "../util.mjs";
+import { green, yellow, red } from "../util.mjs";
 
-// App Review contact from the GITIGNORED metadata/review_information/*.txt. PATCH (or POST) the review
-// detail directly — deliver can't do this cleanly pre-first-submission.
+/**
+ * App Review contact, from the GITIGNORED `<metadataDir>/review_information/*.txt`. PATCH (or POST) the
+ * review detail directly — deliver can't do this cleanly pre-first-submission.
+ *
+ * DEMO ACCOUNT. `demoAccountRequired` used to be hardcoded false. That is true of an account-less game
+ * and false of anything with a login, and getting it wrong is not a small thing: telling Apple no demo
+ * account is needed for an app whose first screen is a sign-in wall is a guaranteed rejection, with a
+ * review cycle attached. fastlane's own convention already puts `demo_user.txt` / `demo_password.txt`
+ * in the very directory this reads from, so the fix is to read the two files that were sitting there.
+ *
+ * Every platform gets the same contact, because the contact is a property of the submitter rather than
+ * of a platform — an app shipping iOS and macOS used to set it on `platforms[0]` and leave the other
+ * version's review detail empty.
+ */
 export async function run(config, client) {
   const dir = path.join(config.metadataDir, "review_information");
   const read = (n) => { const p = path.join(dir, `${n}.txt`); return fs.existsSync(p) ? fs.readFileSync(p, "utf8").trim() : ""; };
+
+  const demoUser = read("demo_user");
+  const demoPassword = read("demo_password");
   const attributes = {
     contactFirstName: read("first_name"), contactLastName: read("last_name"),
     contactPhone: read("phone_number"), contactEmail: read("email_address"),
-    demoAccountRequired: false, notes: read("notes"),
+    // Declared by what is on disk, with an explicit config override for the app that needs one and
+    // supplies it some other way (a reviewer-specific build, a magic link in the notes).
+    demoAccountRequired: config.reviewContact?.demoAccountRequired ?? !!demoUser,
+    notes: read("notes"),
   };
+  if (demoUser) attributes.demoAccountName = demoUser;
+  if (demoPassword) attributes.demoAccountPassword = demoPassword;
+
   if (!attributes.contactEmail) { console.error(red(`review-contact: ${dir}/*.txt missing`)); return false; }
+  // A demo account that is required but has no credentials is the rejection this command exists to
+  // avoid, arriving by a different door — say it here rather than letting Apple say it in a week.
+  if (attributes.demoAccountRequired && !demoUser) {
+    console.error(red("review-contact: demoAccountRequired is true but no demo_user.txt was found."));
+    console.error(`  Add ${dir}/demo_user.txt and demo_password.txt (both gitignored), or set`);
+    console.error("  reviewContact: { demoAccountRequired: false } if the reviewer genuinely needs no account.");
+    return false;
+  }
+
   await client.findApp(config.bundleId);
-  const v = await client.editVersion(config.platforms[0]);
-  if (!v) { console.error(red("review-contact: no editable version")); return false; }
-  const { json } = await client.get(`/v1/appStoreVersions/${v.id}/appStoreReviewDetail`);
-  const existing = json.data;
-  const r = existing?.id
-    ? await client.patch(`/v1/appStoreReviewDetails/${existing.id}`, { data: { type: "appStoreReviewDetails", id: existing.id, attributes } })
-    : await client.post(`/v1/appStoreReviewDetails`, { data: { type: "appStoreReviewDetails", attributes, relationships: { appStoreVersion: { data: { type: "appStoreVersions", id: v.id } } } } });
-  if (r.status >= 300) { console.error(red(`review-contact: ${r.status}: ${JSON.stringify(r.json).slice(0, 200)}`)); return false; }
-  console.log(green(`review contact set -> ${attributes.contactFirstName} ${attributes.contactLastName} · ${attributes.contactPhone}`));
-  return true;
+
+  let ok = true;
+  let touched = 0;
+  for (const platform of config.platforms) {
+    const v = await client.editVersion(platform);
+    if (!v) {
+      console.error(red(`review-contact ${platform}: no editable version — nothing to attach the contact to.`));
+      console.error("  `vydanne prepare --apply` creates the version being submitted, then re-run this.");
+      ok = false;
+      continue;
+    }
+    const { json } = await client.get(`/v1/appStoreVersions/${v.id}/appStoreReviewDetail`);
+    const existing = json.data;
+    const r = existing?.id
+      ? await client.patch(`/v1/appStoreReviewDetails/${existing.id}`, { data: { type: "appStoreReviewDetails", id: existing.id, attributes } })
+      : await client.post(`/v1/appStoreReviewDetails`, { data: { type: "appStoreReviewDetails", attributes, relationships: { appStoreVersion: { data: { type: "appStoreVersions", id: v.id } } } } });
+    if (r.status >= 300) {
+      console.error(red(`review-contact ${platform}: ${r.status}: ${JSON.stringify(r.json).slice(0, 200)}`));
+      ok = false;
+      continue;
+    }
+    touched++;
+  }
+  if (!touched) return false;
+
+  const who = `${attributes.contactFirstName} ${attributes.contactLastName} · ${attributes.contactPhone}`;
+  const demo = attributes.demoAccountRequired ? ` · demo account ${demoUser}` : "";
+  console.log(client.dryRun
+    ? yellow(`review contact WOULD be set on ${touched} platform(s) -> ${who}${demo}`)
+    : green(`review contact set on ${touched} platform(s) -> ${who}${demo}`));
+  return ok;
 }

package/src/config.mjs

@@ -3,10 +3,12 @@ import fs from "node:fs";
 import { pathToFileURL } from "node:url";
 import { resolveLocales } from "./locales.mjs";
 import { resolveCredentials } from "./credentials.mjs";
+import { DEFAULT_SCREENSHOT_BASE } from "./screenshots.mjs";
+import { DEFAULT_PLAY_IMAGES } from "./play/images.mjs";
 
 // The public config surface — the drift guards assert each key is documented (README/SKILL) and typed
 // (types/index.d.ts). Add a config knob → document + type it, or the guards fail before publish.
-export const CONFIG_KEYS = ["bundleId", "primaryLocale", "asc", "platforms", "uiLocales", "metadataDir", "rating", "privacy", "iaps", "previews", "export", "ios", "google", "accessibility"];
+export const CONFIG_KEYS = ["bundleId", "primaryLocale", "asc", "platforms", "uiLocales", "localeMap", "metadataDir", "screenshots", "rating", "ageRating", "privacy", "iaps", "previews", "export", "ios", "google", "accessibility", "bridge", "push", "reviewContact", "allowCrossStoreTerms"];
 
 // One `vydanne.config.mjs` per app (ESM, like zdymak.config.mjs) — nothing hard-coded. Secrets stay out:
 // credentials resolve from the environment, a gitignored .env, or ~/.appstoreconnect/config.json (see
@@ -22,21 +24,64 @@ export async function loadConfig(p) {
   };
   const creds = resolveCredentials(raw, path.dirname(file));
   for (const w of creds.warnings) console.warn(`\x1b[33mvydanne: ${w}\x1b[0m`);
+  // No `raw` passthrough, deliberately. It was assigned here and read by nothing — an attractive
+  // nuisance rather than dead weight: while `config.ios` sat unassigned (the bug check-config.mjs now
+  // guards), `config.raw.ios` WAS populated, so "fixing" a caller by reading through `raw` would have
+  // entrenched the dropped key instead of exposing it. Everything a command may read is an explicit
+  // key below, where the guard can see it.
   const c = {
-    raw,
     credentials: creds,
     bundleId: need("bundleId"),
     primaryLocale: need("primaryLocale"),
     keyId: creds.keyId,
     issuerId: creds.issuerId,
     uiLocales: raw.uiLocales || [],
+    // App code -> App Store locale, for codes Apple spells differently or does not know yet. Merged over
+    // the built-in table rather than replacing it, so an app declares only its exceptions.
+    localeMap: raw.localeMap || null,
     platforms: raw.platforms || ["IOS"],
     rating: raw.rating || "4+",
+    // Content descriptors for a rating above 4+. Null means "the 4+ shorthand", which `age-rating`
+    // expands to an all-NONE declaration; anything else must be declared, never guessed.
+    ageRating: raw.ageRating || null,
     privacy: raw.privacy || { collected: ["CRASH_DATA", "PERFORMANCE_DATA"], tracking: false },
     iaps: raw.iaps || [],
     metadataDir: raw.metadataDir || "fastlane/metadata",
+    // Where each platform's screenshots live. fastlane's supply convention by default — the same
+    // relationship `metadataDir` has always had to it, and for the same reason: a convention worth
+    // defaulting to is not a reason to be unable to point the tool at your own repo.
+    screenshots: raw.screenshots
+      ? { IOS: raw.screenshots.IOS || DEFAULT_SCREENSHOT_BASE.IOS, MAC_OS: raw.screenshots.MAC_OS || DEFAULT_SCREENSHOT_BASE.MAC_OS }
+      : null,
+    // App Review contact overrides. The PII itself still comes from the gitignored
+    // `<metadataDir>/review_information/*.txt` — this is only for what isn't a secret.
+    reviewContact: raw.reviewContact || null,
+    // `push: { skip: [...] }` — steps this app never runs. `--skip` adds to it per invocation; both are
+    // reported on every run, because a skipped step must never read as a completed one.
+    push: raw.push ? { skip: raw.push.skip || [] } : null,
+    // `bridge`: where zdymak wrote, and which of its output directories feed which store slot. Both
+    // default to zdymak's own conventions; both must be overridable, because `dir:` overrides in
+    // zdymak.config.mjs mean the directory name and the target name are not the same thing.
+    bridge: raw.bridge
+      ? { out: raw.bridge.out || null, apple: raw.bridge.apple || null, play: raw.bridge.play || null }
+      : null,
+    // Terms the cross-store check must not flag for this app (see src/crossStore.mjs).
+    allowCrossStoreTerms: raw.allowCrossStoreTerms || [],
     previews: raw.previews || null,
     export: raw.export || { encryption: "standard" },
+    // What the app claims to support, for the Accessibility Nutrition Labels. Passed through RAW and
+    // deliberately NOT defaulted: `accessibility` validates its own block and must be able to tell
+    // "declared nothing" from "declared everything false" — a default here would turn a missing block
+    // into a silent set of claims, which is the one thing that command exists to refuse.
+    accessibility: raw.accessibility || null,
+    // iOS build upload (`prerelease`). Normalised like `google` below so the shape is stable whether or
+    // not the block is present.
+    ios: raw.ios
+      ? {
+          ipa: raw.ios.ipa || null, // VYDANNE_IPA overrides, resolved in prerelease.resolveIpa
+          testFlightGroup: raw.ios.testFlightGroup || null, // internal groups only; external is refused
+        }
+      : null,
     // Google Play. serviceAccountKey resolves from PLAY_JSON_KEY_FILE env first (keep the secret path out
     // of the committed config). metadataDir follows fastlane supply's convention (fastlane/metadata/android).
     google: raw.google
@@ -47,10 +92,16 @@ export async function loadConfig(p) {
           defaultLocale: raw.google.defaultLocale || raw.primaryLocale,
           aab: raw.google.aab || null,
           track: raw.google.track || "internal", // testing only — `prerelease` refuses production
-
+          // Play image type -> local source path. Merged over the defaults so an app overrides only the
+          // slots whose layout differs; the default for `icon` points at znachok's output, which is a
+          // sensible default for this portfolio and a mystery to anyone else, so it is overridable.
+          images: { ...DEFAULT_PLAY_IMAGES, ...(raw.google.images || {}) },
+          // Play supports per-language graphics. Uploading only to `defaultLocale` is a choice, not a
+          // platform limit — list locales here (or "*" for every local listing folder) to localize them.
+          imageLocales: raw.google.imageLocales || null,
         }
       : null,
   };
-  c.resolvedLocales = resolveLocales(c.uiLocales);
+  c.resolvedLocales = resolveLocales(c.uiLocales, c.localeMap);
   return c;
 }