vydanne 0.6.0 → 0.8.0

package/src/commands/prepare.mjs

@@ -0,0 +1,266 @@
+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` +
+      // `copyright` is requested because syncCopyright compares against it. A sparse fieldset that
+      // omits it does not read as absent — it reads as EMPTY, so the comparison can never match and
+      // the field is re-PATCHed on every run, spending a request to change nothing and printing
+      // "(was empty)" over a value that was already correct. A guard that cannot see the thing it
+      // guards is not a guard.
+      `&fields[appStoreVersions]=versionString,appStoreState,copyright`,
+  );
+  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;
+}
+
+/**
+ * Copyright on a version that ALREADY EXISTED.
+ *
+ * It was only ever set at creation, on the reasoning below that nothing else in vydanne writes this
+ * version-level field — which was true and yet left the gap wide open, because `prepare` is
+ * find-or-CREATE. Every app whose draft was made before `copyright.txt` existed, or made by hand in
+ * App Store Connect, or created by an older vydanne, reused that version forever and never got a
+ * copyright. The tooling then reported "prepare done — the version is editable" and the operator
+ * discovered the truth from Apple, at the end, as `Copyright - This field is required` on the Add
+ * for Review screen. The comment three lines down even called it "a metadata rejection waiting to
+ * happen".
+ *
+ * So the create path and the reuse path now converge: after this, a version has the copyright the
+ * repo declares, however that version came to exist.
+ *
+ * PATCHes only on a real difference. Apple's rate limits are per-app and a `prepare` that rewrites
+ * an already-correct field on every `push` spends a request to change nothing — and, more to the
+ * point, prints a line claiming it did something.
+ */
+async function syncCopyright(client, config, version) {
+  const want = readCopyright(config);
+  if (!want) return;
+  const have = version.attributes?.copyright ?? "";
+  if (have === want) return;
+
+  const was = have ? ` (was "${have}")` : " (was empty)";
+  const r = await client.patch(`/v1/appStoreVersions/${version.id}`, {
+    data: { type: "appStoreVersions", id: version.id, attributes: { copyright: want } },
+  });
+  if (r.status >= 300) {
+    console.error(red(`  could not set copyright (${r.status})`));
+    for (const e of r.json?.errors || []) console.error(`    ${e.title}: ${e.detail}`);
+    return;
+  }
+  version.attributes.copyright = want;
+  console.log(client.dryRun
+    ? yellow(`  WOULD set copyright: "${want}"${was}`)
+    : green(`  copyright set: "${want}"${was}`));
+}
+
+/**
+ * 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`));
+    await syncCopyright(client, config, existing);
+    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;
 }
 

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