vydanne 0.6.0 → 0.7.0

package/bin/vydanne.mjs

@@ -15,6 +15,14 @@ const i = argv.indexOf("--config");
 const cfgPath = i >= 0 ? argv[i + 1] : undefined;
 const si = argv.indexOf("--store");
 const store = si >= 0 ? argv[si + 1] : "apple";
+// Validated, because the dispatch below only tests `store === "google"`: a typo (`--store goole`) or a
+// missing value (`--store --apply`) would otherwise fall through to the APPLE branch and aim the command
+// at the other store — the worst possible reading of a mistyped argument, and a silent one, since every
+// Apple command runs happily from a repo configured for both.
+if (store !== "apple" && store !== "google") {
+  console.error(`\x1b[31mvydanne: unknown --store '${store}' (expected: apple, google)\x1b[0m`);
+  process.exit(1);
+}
 
 // SAFE BY DEFAULT. Every store-mutating command is a dry run unless `--apply` is passed. The Play half
 // always worked this way (VYDANNE_COMMIT=1, enforceable because an Edit can be discarded); the Apple half
@@ -57,6 +65,9 @@ try {
     console.log(`supported (${Object.keys(r.supported).length}):`);
     for (const [ui, asc] of Object.entries(r.supported)) console.log(`  ${ui} -> ${asc}`);
     console.log(`unsupported (${r.unsupported.length}) [no App Store language -> fall back to primary]: ${r.unsupported.join(", ")}`);
+    // A localeMap entry pointing at a code Apple does not have is a config mistake, not a missing
+    // language — it would otherwise be indistinguishable from the line above.
+    if (r.invalid?.length) console.log(`\x1b[31minvalid localeMap (${r.invalid.length}) [not an App Store code]: ${r.invalid.join(", ")}\x1b[0m`);
   } else if (store === "google") {
     const cfg = await loadConfig(cfgPath);
     if (!cfg.google) throw new Error("vydanne: no `google` block in config — add packageName + a service-account key");
@@ -107,6 +118,15 @@ usage: vydanne <command> [--apply] [--config vydanne.config.mjs]
   --apply         PERFORM the writes. Without it every store-mutating command below (marked ✎) runs
                   as a DRY RUN: it reads the store, reports exactly what it would change, and sends
                   nothing. Read-only commands ignore the flag.
+✎ prepare         create/reuse the editable App Store version and attach the uploaded build.
+                  Run this FIRST on an app that already has a version on sale — until it has,
+                  there is no draft for \`fill\` to write into. Never submits; VYDANNE_VERSION=<x>
+                  to name the version instead of reading it off the newest build.
+✎ push            the whole pipeline, in order: prepare → fill → previews → age-rating →
+                  review-contact → accessibility → preflight. Stops at the first failure.
+                  --skip <step>[,<step>] drops steps that don't apply (prepare/preflight can't be
+                  skipped); every skip is reported again at the end, so green still means green.
+                  Ends at a green preflight — Add to Review + Submit stay yours, in the web UI.
 ✎ fill            metadata + screenshots + previews (native; iOS & macOS separate)
 ✎ age-rating      set the age rating (AppInfo declaration)
 ✎ review-contact  App Review contact from the gitignored files
@@ -115,6 +135,8 @@ usage: vydanne <command> [--apply] [--config vydanne.config.mjs]
 ✎ previews        upload App Preview videos (native chunked upload)
   iap             validate IAP fields; VYDANNE_FLATTEN=<png> flattens a screenshot to RGB
   compliance      generate the US encryption self-classification PDF
+  bridge          map zdymak's store-assets output onto the folders \`fill\` reads (locale codes,
+                  device prefixes, Play paths). Local files only; --dry-run previews.
   inspect         read-only ASC state
   diff            show what differs between local (metadata/screenshots/previews) and ASC
   preflight       verify submission-completeness (the gotcha checker)
@@ -125,7 +147,8 @@ usage: vydanne <command> [--apply] [--config vydanne.config.mjs]
 credentials: env > .env cascade (.env, .env.<mode>, .env.local, .env.<mode>.local) > user config
   (\$VYDANNE_CONFIG_HOME, %APPDATA%\\vydanne or \$XDG_CONFIG_HOME/vydanne, ~/.appstoreconnect).
   NEVER the committed vydanne.config.mjs — run \`vydanne auth\` to see what resolved.
-toggles: VYDANNE_SKIP_METADATA / VYDANNE_SKIP_SCREENSHOTS (fill), VYDANNE_A11Y_PUBLISH (accessibility),
+toggles: VYDANNE_SKIP_METADATA / VYDANNE_SKIP_SCREENSHOTS (fill), VYDANNE_REPLACE=1 (fill/previews:
+         replace populated slots), VYDANNE_VERSION (prepare), VYDANNE_A11Y_PUBLISH (accessibility),
          VYDANNE_PROFILE (named profile), VYDANNE_ENV (.env mode),
          VYDANNE_COMMIT=1 (legacy alias for --apply — prefer the flag)`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vydanne",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "App Store Connect + Google Play submission prep — the companion to zdymak (media). Native Node (no fastlane/Ruby/Python): localized listings, screenshot/preview/icon upload, ratings, review contact, accessibility & privacy labels, IAP, export docs, build upload to TestFlight / a Play closed track, a diff of local-vs-store, and a preflight verifier that encodes the store gotchas. Never submits for review. iOS/macOS via the ASC REST API; Android via the Play Developer Edits API (--store google).",
   "keywords": [
     "app-store-connect",
@@ -51,7 +51,8 @@
   "scripts": {
     "check:docs": "node scripts/check-docs.mjs",
     "check:types": "tsc --noEmit -p tsconfig.json && node scripts/check-types.mjs",
-    "prepublishOnly": "npm run check:docs && npm run check:types",
+    "check:config": "node scripts/check-config.mjs",
+    "prepublishOnly": "npm run check:docs && npm run check:types && npm run check:config",
     "release:patch": "node scripts/release.mjs patch",
     "release:minor": "node scripts/release.mjs minor",
     "release:major": "node scripts/release.mjs major"

package/src/client.mjs

@@ -3,13 +3,15 @@ import { yellow } from "./util.mjs";
 
 const API = "https://api.appstoreconnect.apple.com";
 const IRIS = "https://appstoreconnect.apple.com/iris";
-const DEAD_VERSION = ["READY_FOR_SALE", "REMOVED_FROM_SALE", "REPLACED_WITH_NEW_VERSION"];
+// DEVELOPER_REMOVED_FROM_SALE is the state a version reaches when the DEVELOPER pulls it, as opposed to
+// Apple; both are shipped versions that will never become editable again, so both are dead here.
+const DEAD_VERSION = ["READY_FOR_SALE", "REMOVED_FROM_SALE", "DEVELOPER_REMOVED_FROM_SALE", "REPLACED_WITH_NEW_VERSION"];
 // READY_FOR_DISTRIBUTION is Apple's newer name for the LIVE app-info (they're migrating the
 // state vocabulary; versions still report appStoreState=READY_FOR_SALE). Without it here,
 // appInfo() treats the live record as editable and every name/subtitle PATCH comes back
 // ENTITY_ERROR.ATTRIBUTE.INVALID.INVALID_STATE — which fails the whole locale in `fill`,
 // release notes included, on any app that already has a version on sale.
-const DEAD_INFO = ["READY_FOR_SALE", "READY_FOR_DISTRIBUTION", "REPLACED_WITH_NEW_VERSION", "REMOVED_FROM_SALE"];
+const DEAD_INFO = ["READY_FOR_SALE", "READY_FOR_DISTRIBUTION", "REPLACED_WITH_NEW_VERSION", "REMOVED_FROM_SALE", "DEVELOPER_REMOVED_FROM_SALE"];
 
 // Anything that is not a read. ASC has no transaction to roll back — unlike Play, where an edit can be
 // discarded — so for Apple the only safe place to stand between a command and a live listing is here.
@@ -79,16 +81,50 @@ export class Client {
     return app;
   }
 
-  async editVersion(platform) {
+  /**
+   * The version being PREPARED — or null when there isn't one.
+   *
+   * This used to fall back to `data[0]`, the LIVE version, whenever nothing editable existed. The
+   * fallback was silent and it defeated its own callers: `fill`, `preflight`, `reviewContact` and
+   * `previews` each test `if (!v)` and report "no editable version", and not one of those branches could
+   * be reached on an app that had shipped once. What happened instead was worse than an error — `fill`
+   * aimed its description/whatsNew PATCHes at the listing customers were reading, and `preflight`
+   * validated that same live listing and printed "no blockers", calling a release submittable when
+   * there was nothing to submit.
+   *
+   * So a write is never handed the live version by default. Read-only commands (`inspect`, `diff`) pass
+   * `allowLive: true`, because "how does local compare with what is on sale" is a real question and that
+   * is the only version they could ask it about. Everything else gets null and says so — and now has
+   * `prepare` to point at, which is the command that makes an editable version exist.
+   */
+  async editVersion(platform, { allowLive = false } = {}) {
     const { json } = await this.get(`/v1/apps/${this.appId}/appStoreVersions?filter[platform]=${platform}&limit=10`);
     const data = json.data || [];
-    return data.find((v) => !DEAD_VERSION.includes(v.attributes.appStoreState)) || data[0] || null;
+    const editable = data.find((v) => !DEAD_VERSION.includes(v.attributes.appStoreState));
+    if (editable) return editable;
+    return allowLive ? data[0] || null : null;
   }
 
-  async appInfo() {
+  /**
+   * The app-info being PREPARED (name/subtitle, age rating live on it) — or null when there isn't one.
+   *
+   * Same disease, same cure as editVersion() above: this fell back to `data[0]` — the LIVE app-info —
+   * whenever nothing editable existed, and the fallback aimed writes at the record customers see. It is
+   * how the DEAD_INFO bug was found in the first place (every name/subtitle PATCH against the live
+   * record comes back INVALID_STATE and fails the whole locale in `fill`), and adding
+   * READY_FOR_DISTRIBUTION to DEAD_INFO only fixed the case where an editable sibling EXISTS to be
+   * found; the moment there is none, `|| data[0]` reintroduced exactly the state that comment warns
+   * about. Now a write gets null and a clear skip instead of twenty locales of ENTITY_ERROR.
+   *
+   * `allowLive` is for reads (`diff`), where "how does local compare with what is on sale" is the
+   * question being asked.
+   */
+  async appInfo({ allowLive = false } = {}) {
     const { json } = await this.get(`/v1/apps/${this.appId}/appInfos?limit=10`);
     const data = json.data || [];
-    return data.find((i) => !DEAD_INFO.includes(i.attributes.state)) || data[0] || null;
+    const editable = data.find((i) => !DEAD_INFO.includes(i.attributes.state));
+    if (editable) return editable;
+    return allowLive ? data[0] || null : null;
   }
 
   async versionLocalizations(versionId) {

package/src/commands/accessibility.mjs

@@ -107,8 +107,14 @@ export async function run(config, client) {
   console.log(`  declaring: ${claimed.length ? claimed.join(", ") : "(nothing)"}`);
 
   let gated = false;
+  // A PATCH that Apple refuses is a claim that never reached the store. Both failure paths below used
+  // to print red and `continue`, and the command still returned true — so `push` treated a family whose
+  // declaration never saved as a completed step. The `continue`s stay (one refused family must not hide
+  // the other three); the verdict now travels out with the return.
+  const failures = [];
   for (const family of Object.keys(UNAVAILABLE)) {
     const id = decls[family];
+    // Not a failure: Apple only holds declarations for the families the app actually ships on.
     if (!id) {
       console.error(yellow(`  no ${family} declaration`));
       continue;
@@ -119,6 +125,7 @@ export async function run(config, client) {
     });
     if (r.status >= 300) {
       console.error(red(`  ${family} draft ${r.status}`));
+      failures.push(`${family}: draft not saved (${r.status})`);
       continue;
     }
     if (publish) {
@@ -132,11 +139,17 @@ export async function run(config, client) {
         console.log(yellow(`  ${family}: draft saved — publish deferred (app not live yet)`));
       } else {
         console.error(red(`  ${family} publish ${p.status}`));
+        failures.push(`${family}: publish refused (${p.status})`);
       }
     } else {
       console.log(green(`  ${family}: draft saved`));
     }
   }
+  if (failures.length) {
+    console.error(red(`accessibility: ${failures.length} declaration(s) did not save:`));
+    for (const f of failures) console.error(`  ${red("x")} ${f}`);
+    return false;
+  }
   console.log(
     gated
       ? yellow("accessibility staged (DRAFT); re-run with VYDANNE_A11Y_PUBLISH=1 once the app is live")

package/src/commands/ageRating.mjs

@@ -1,33 +1,106 @@
 import { green, yellow, red } from "../util.mjs";
 
-// Set the age rating via the AppInfo age-rating declaration. v1: "4+" — every content descriptor NONE.
-// (PATCH is partial; Apple recomputes 4+ from these.) app-info fetched from the full list (survives
-// READY_FOR_REVIEW).
+/**
+ * Set the age rating via the AppInfo age-rating declaration.
+ *
+ * `rating: "4+"` stays the shorthand it always was: every content descriptor NONE, every capability
+ * question false, which is what Apple recomputes 4+ from. Anything else is declared feature by feature
+ * in `ageRating`, merged over that all-NONE base — so an app with fantasy violence sets one key rather
+ * than restating twenty-seven.
+ *
+ * This used to refuse outright for any rating but 4+, which made the whole command — and `push`, which
+ * runs it as a step — unusable for any app with violence, gambling, chat or user-generated content.
+ * The base was always the general thing; only the door was missing.
+ */
+
+const N = "NONE";
+
+// Apple's 2025 age-rating schema. A PATCH must include ALL required fields (a partial set 409s), and
+// `ageRatingOverride` (deprecated) cannot be sent alongside `ageRatingOverrideV2` — so we send only V2.
+// Content descriptors are enums (NONE/INFREQUENT_OR_MILD/FREQUENT_OR_INTENSE); capability questions are
+// booleans. All benign here → 4+.
+const BASE = {
+  advertising: false, alcoholTobaccoOrDrugUseOrReferences: N, contests: N, gambling: false,
+  gamblingSimulated: N, gunsOrOtherWeapons: N, healthOrWellnessTopics: false, kidsAgeBand: null,
+  lootBox: false, medicalOrTreatmentInformation: N, messagingAndChat: false, parentalControls: false,
+  profanityOrCrudeHumor: N, ageAssurance: false, sexualContentGraphicAndNudity: N, sexualContentOrNudity: N,
+  socialMedia: false, socialMediaAgeRestricted: false, horrorOrFearThemes: N, matureOrSuggestiveThemes: N,
+  unrestrictedWebAccess: false, userGeneratedContent: false, violenceCartoonOrFantasy: N,
+  violenceRealisticProlongedGraphicOrSadistic: N, violenceRealistic: N, ageRatingOverrideV2: N,
+  koreaAgeRatingOverride: N,
+};
+
+/** Values Apple accepts for a content descriptor. `kidsAgeBand` and the overrides are checked separately. */
+const DESCRIPTOR_VALUES = new Set([N, "INFREQUENT_OR_MILD", "FREQUENT_OR_INTENSE"]);
+
+/**
+ * The attributes to send, or a human-readable problem.
+ *
+ * A declaration is validated against the schema BEFORE it reaches Apple, because the failure otherwise
+ * is a 409 naming a field the operator did not know existed. An unknown key is a typo — and a typo in
+ * this table means a descriptor silently stayed NONE, which is a rating that understates the app.
+ */
+export function resolveAttributes(config) {
+  const declared = config.ageRating;
+  if (!declared) {
+    if (config.rating === "4+") return { attributes: { ...BASE } };
+    return {
+      problem: [
+        `age-rating: rating is '${config.rating}', but nothing describes what makes it that.`,
+        "'4+' is the only rating that needs no detail (every descriptor NONE). For anything else,",
+        "declare the content Apple asks about — it computes the rating from these, you don't set it:",
+        "",
+        "  ageRating: {",
+        "    violenceCartoonOrFantasy: 'INFREQUENT_OR_MILD',",
+        "    userGeneratedContent: false,",
+        "  },",
+        "",
+        `Known keys: ${Object.keys(BASE).join(", ")}`,
+      ].join("\n"),
+    };
+  }
+  const unknown = Object.keys(declared).filter((k) => !(k in BASE));
+  if (unknown.length) {
+    return { problem: `age-rating: unknown key(s) ${unknown.join(", ")}. Known: ${Object.keys(BASE).join(", ")}` };
+  }
+  const bad = [];
+  for (const [k, v] of Object.entries(declared)) {
+    if (k === "kidsAgeBand") continue; // null | FIVE_AND_UNDER | SIX_TO_EIGHT | NINE_TO_ELEVEN
+    if (typeof BASE[k] === "boolean" && typeof v !== "boolean") bad.push(`${k} must be true or false`);
+    else if (typeof BASE[k] === "string" && !DESCRIPTOR_VALUES.has(v)) bad.push(`${k} must be one of ${[...DESCRIPTOR_VALUES].join(" / ")}`);
+  }
+  if (bad.length) return { problem: `age-rating: ${bad.join("; ")}` };
+  return { attributes: { ...BASE, ...declared } };
+}
+
 export async function run(config, client) {
-  if (config.rating !== "4+") { console.error(yellow(`age-rating: only '4+' (all-NONE) implemented; config=${config.rating}`)); return false; }
+  const { attributes, problem } = resolveAttributes(config);
+  if (problem) { console.error(red(problem)); return false; }
   await client.findApp(config.bundleId);
+  // No allowLive: this PATCHes the age-rating declaration, and the live app-info's declaration is not
+  // ours to aim a write at. The refusal below used to be unreachable — appInfo() handed back the live
+  // record instead of null, so the write was planned against it and Apple's INVALID_STATE was the
+  // first anyone heard of it.
   const info = await client.appInfo();
-  if (!info) { console.error(red("age-rating: no editable app info")); return false; }
+  if (!info) {
+    console.error(red("age-rating: no editable app info — refusing to write to the live record."));
+    console.error("  `vydanne prepare --apply` starts the next version, which makes app info editable again.");
+    return false;
+  }
   const { json } = await client.get(`/v1/appInfos/${info.id}/ageRatingDeclaration`);
   const id = json.data?.id;
   if (!id) { console.error(red("age-rating: no declaration")); return false; }
-  const N = "NONE";
-  // Apple's 2025 age-rating schema. A PATCH must include ALL required fields (a partial set 409s),
-  // and `ageRatingOverride` (deprecated) cannot be sent alongside `ageRatingOverrideV2` — so we send
-  // only V2. Content descriptors are enums (NONE); capability questions are booleans (false). All
-  // benign here → 4+.
-  const attributes = {
-    advertising: false, alcoholTobaccoOrDrugUseOrReferences: N, contests: N, gambling: false,
-    gamblingSimulated: N, gunsOrOtherWeapons: N, healthOrWellnessTopics: false, kidsAgeBand: null,
-    lootBox: false, medicalOrTreatmentInformation: N, messagingAndChat: false, parentalControls: false,
-    profanityOrCrudeHumor: N, ageAssurance: false, sexualContentGraphicAndNudity: N, sexualContentOrNudity: N,
-    socialMedia: false, socialMediaAgeRestricted: false, horrorOrFearThemes: N, matureOrSuggestiveThemes: N,
-    unrestrictedWebAccess: false, userGeneratedContent: false, violenceCartoonOrFantasy: N,
-    violenceRealisticProlongedGraphicOrSadistic: N, violenceRealistic: N, ageRatingOverrideV2: N,
-    koreaAgeRatingOverride: N,
-  };
+
+  // What is actually being asserted, printed before it is sent. Apple computes the rating from these,
+  // so the declared non-defaults ARE the rating — worth seeing in the log of the run that set them.
+  const declared = Object.entries(attributes).filter(([k, v]) => v !== BASE[k] || (v !== false && v !== N && v !== null));
+  console.log(`  declaring: ${declared.length ? declared.map(([k, v]) => `${k}=${v}`).join(", ") : "everything NONE (4+)"}`);
+
   const r = await client.patch(`/v1/ageRatingDeclarations/${id}`, { data: { type: "ageRatingDeclarations", id, attributes } });
   if (r.status >= 300) { console.error(red(`age-rating: ${r.status}: ${JSON.stringify(r.json).slice(0, 200)}`)); return false; }
-  console.log(client.dryRun ? yellow("age rating WOULD be set -> 4+") : green("age rating set -> 4+"));
+  // Apple decides the band from the descriptors; naming config.rating here reports what was ASKED for,
+  // which is the only thing this command controls.
+  const label = config.ageRating ? `${config.rating} (from the declared descriptors)` : "4+";
+  console.log(client.dryRun ? yellow(`age rating WOULD be set -> ${label}`) : green(`age rating set -> ${label}`));
   return true;
 }