vydanne 0.6.0 → 0.7.0

package/src/play/aab.mjs

@@ -0,0 +1,133 @@
+import fs from "node:fs";
+import zlib from "node:zlib";
+
+/**
+ * Read the versionCode out of an `.aab`, locally, before anything is uploaded.
+ *
+ * WHY. Release notes resolve to `<metadataDir>/<locale>/changelogs/<versionCode>.txt`, but in repos
+ * that derive versionCode from `git rev-list --count HEAD` the number is unknowable until the build is
+ * cut — every commit moves it. So nobody can name the changelog file in advance, the fallback quietly
+ * wins, and the first time the real number appears in a log is AFTER a multi-megabyte upload. The
+ * bundle itself has known its own versionCode all along: it is an attribute on the `<manifest>`
+ * element of `base/manifest/AndroidManifest.xml`.
+ *
+ * HOW, without Java. bundletool is the official reader and is a JVM tool; shelling out to it would be
+ * the first Java dependency in a package whose whole pitch is native Node. But the format is shallow:
+ * an .aab is a ZIP, and the manifest inside is aapt2's protobuf XML. Neither needs a library —
+ * `zlib.inflateRawSync` decompresses the entry, and protobuf's wire format is walkable generically:
+ * find the submessage that looks like an XmlAttribute named "versionCode" (field 2, its `name`) and
+ * take its value (field 3 as a decimal string, or the first varint inside field 6, the compiled item).
+ * Matching by attribute NAME rather than by the exact Resources.proto field numbers for Primitive is
+ * deliberate — those internals have shifted between aapt2 versions; "an attribute called versionCode
+ * on the manifest of an Android app" has not.
+ *
+ * Returns null on anything unexpected rather than throwing: the caller has a correct-by-construction
+ * fallback (Play reports the versionCode after upload), so a parse failure must degrade to the old
+ * behaviour, never block a release.
+ */
+export function readAabVersionCode(file) {
+  try {
+    const manifest = zipEntry(fs.readFileSync(file), "base/manifest/AndroidManifest.xml");
+    return manifest ? findVersionCode(manifest) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Extract one entry from a ZIP buffer (stored or deflated), or null. */
+function zipEntry(buf, wanted) {
+  // End-of-central-directory: scan back from the end (the record allows a trailing comment).
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 65535); i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) { eocd = i; break; }
+  }
+  if (eocd < 0) return null;
+  let off = buf.readUInt32LE(eocd + 16); // central directory offset
+  const count = buf.readUInt16LE(eocd + 10);
+  for (let n = 0; n < count && off + 46 <= buf.length; n++) {
+    if (buf.readUInt32LE(off) !== 0x02014b50) return null;
+    const method = buf.readUInt16LE(off + 10);
+    const csize = buf.readUInt32LE(off + 20);
+    const nameLen = buf.readUInt16LE(off + 28);
+    const extraLen = buf.readUInt16LE(off + 30);
+    const commentLen = buf.readUInt16LE(off + 32);
+    const localOff = buf.readUInt32LE(off + 42);
+    const name = buf.toString("utf8", off + 46, off + 46 + nameLen);
+    if (name === wanted) {
+      // The local header repeats name/extra with its OWN lengths (extra often differs) — read them.
+      if (buf.readUInt32LE(localOff) !== 0x04034b50) return null;
+      const lname = buf.readUInt16LE(localOff + 26);
+      const lextra = buf.readUInt16LE(localOff + 28);
+      const data = buf.subarray(localOff + 30 + lname + lextra, localOff + 30 + lname + lextra + csize);
+      if (method === 0) return data;
+      if (method === 8) return zlib.inflateRawSync(data);
+      return null;
+    }
+    off += 46 + nameLen + extraLen + commentLen;
+  }
+  return null;
+}
+
+/** Parse one protobuf message into its fields. Throws on anything that isn't valid wire format. */
+function protoFields(buf) {
+  const out = [];
+  let i = 0;
+  const varint = () => {
+    let v = 0, shift = 0;
+    for (;;) {
+      if (i >= buf.length || shift > 49) throw new Error("varint"); // >2^49 can't be a versionCode anyway
+      const b = buf[i++];
+      v += (b & 0x7f) * 2 ** shift;
+      if (!(b & 0x80)) return v;
+      shift += 7;
+    }
+  };
+  while (i < buf.length) {
+    const key = varint();
+    const no = Math.floor(key / 8), wire = key % 8;
+    if (wire === 0) out.push({ no, wire, val: varint() });
+    else if (wire === 2) { const len = varint(); if (i + len > buf.length) throw new Error("len"); out.push({ no, wire, bytes: buf.subarray(i, i + len) }); i += len; }
+    else if (wire === 5) { i += 4; out.push({ no, wire }); }
+    else if (wire === 1) { i += 8; out.push({ no, wire }); }
+    else throw new Error("wire");
+  }
+  return out;
+}
+
+/** Depth-first hunt for an XmlAttribute whose name (field 2) is "versionCode". */
+function findVersionCode(buf) {
+  let fields;
+  try { fields = protoFields(buf); } catch { return null; } // not a message — a string that happened to be field-2
+  const name = fields.find((f) => f.no === 2 && f.wire === 2);
+  if (name && name.bytes.toString("utf8") === "versionCode") {
+    const value = fields.find((f) => f.no === 3 && f.wire === 2)?.bytes.toString("utf8");
+    if (value && /^\d+$/.test(value)) return Number(value);
+    const compiled = fields.find((f) => f.no === 6 && f.wire === 2);
+    if (compiled) {
+      const v = firstVarint(compiled.bytes);
+      if (v != null) return v;
+    }
+    return null;
+  }
+  for (const f of fields) {
+    if (f.wire !== 2) continue;
+    const found = findVersionCode(f.bytes);
+    if (found != null) return found;
+  }
+  return null;
+}
+
+/** The first varint anywhere in a message — inside Item→Primitive that is the integer value itself
+ *  (the attribute-level varints, like resource_id, live OUTSIDE the compiled item). */
+function firstVarint(buf) {
+  let fields;
+  try { fields = protoFields(buf); } catch { return null; }
+  for (const f of fields) {
+    if (f.wire === 0) return f.val;
+    if (f.wire === 2) {
+      const v = firstVarint(f.bytes);
+      if (v != null) return v;
+    }
+  }
+  return null;
+}

package/src/play/commands/diff.mjs

@@ -1,10 +1,13 @@
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { green, red, yellow } from "../../util.mjs";
+import { playImages, imageLocales } from "../images.mjs";
 
 // [Play listing attribute, local metadata filename] — supply's convention under fastlane/metadata/android.
 const FIELDS = [["title", "title"], ["shortDescription", "short_description"], ["fullDescription", "full_description"]];
 const norm = (s) => (s == null ? null : String(s).replace(/\r/g, "").replace(/\n+$/, "").trim());
+const sha1 = (buf) => crypto.createHash("sha1").update(buf).digest("hex");
 
 // Show what differs between local Play sources (fastlane/metadata/android/<locale>/*.txt) and the live Play
 // listing — a dry-run of `fill --store google`.
@@ -38,6 +41,43 @@ export async function run(config, client) {
     const localSet = new Set(localLangs);
     const extra = listings.map((l) => l.language).filter((x) => !localSet.has(x));
     if (extra.length) console.log(`  ${yellow("Play-only languages")} (no local folder): ${extra.join(", ")}`);
+
+    // Images, by CONTENT. This command compared nothing here at all, so "in sync" was a claim about the
+    // text only — a full recapture of every screenshot reported nothing to do, which is the same bug the
+    // Apple diff had with counts, one step worse. Play's images.list returns the sha1 of what it holds
+    // (the comparison supply itself uses to skip identical uploads), so local bytes can be checked
+    // against the store without downloading anything. Only types with a LOCAL asset are judged, and a
+    // remote-only type is left unflagged — mirroring fill, which never deletes by omission.
+    // Every locale `fill` would upload to, so the two commands agree on what "in sync" covers. With the
+    // default (no `google.imageLocales`) that is the one `defaultLocale` this always compared.
+    for (const lang of imageLocales(g, localLangs)) {
+      for (const [type, src, kind] of playImages(config)) {
+        const localized = path.join(src, lang);
+        const from = kind === "dir" && fs.existsSync(localized) ? localized : src;
+        if (!fs.existsSync(from)) continue;
+        const files = kind === "dir" ? fs.readdirSync(from).filter((f) => /\.(png|jpe?g)$/i.test(f)).sort().map((f) => path.join(from, f)) : [from];
+        const label = `  ${yellow("images")} ${type}`;
+        // A dir that exists but is empty means the local set was deliberately cleared — `fill` will not
+        // touch the live one (never-delete-by-omission), so if the store still holds images they are
+        // stale and only Play Console can remove them. Reported, not counted as actionable, because no
+        // vydanne command would change it.
+        if (!files.length) {
+          const held = ((await client.listImages(editId, lang, type)).json.images || []).length;
+          if (held) console.log(`${label}: local dir empty, store holds ${held} — stale; only Play Console can remove them  (@${lang})`);
+          continue;
+        }
+        const local = files.map((f) => sha1(fs.readFileSync(f)));
+        const remote = ((await client.listImages(editId, lang, type)).json.images || []).map((i) => i.sha1);
+        if (local.length !== remote.length) {
+          actionable++;
+          console.log(`${label}: local ${local.length} / remote ${remote.length}  (@${lang})`);
+        } else if (JSON.stringify([...local].sort()) !== JSON.stringify([...remote].sort())) {
+          const changed = local.filter((s) => !remote.includes(s)).length;
+          actionable++;
+          console.log(`${label}: ${changed} of ${local.length} differ in content  (@${lang})`);
+        }
+      }
+    }
   } finally {
     await client.deleteEdit(editId);
   }

package/src/play/commands/fill.mjs

@@ -2,18 +2,9 @@ import fs from "node:fs";
 import path from "node:path";
 import { green, yellow, red } from "../../util.mjs";
 import { reportCrossStore } from "../../crossStore.mjs";
+import { playImages, imageLocales } from "../images.mjs";
 
 const FIELDS = [["title", "title"], ["shortDescription", "short_description"], ["fullDescription", "full_description"]];
-// Play image type -> local source (a dir of PNGs = screenshots; a single file = graphic). From zdymak.
-// Each type is uploaded only when its local asset EXISTS, so an app that lacks (say) tablet shots or a
-// znachok icon simply skips that type — a missing local set never deletes the live one.
-const IMAGES = [
-  ["icon", "brand/icons/play/icon-512.png", "file"],
-  ["featureGraphic", "marketing/out/play-feature-graphic.png", "file"],
-  ["phoneScreenshots", "marketing/out/play-phone-plain", "dir"],
-  ["sevenInchScreenshots", "marketing/out/play-tablet7-plain", "dir"],
-  ["tenInchScreenshots", "marketing/out/play-tablet-plain", "dir"],
-];
 
 // Push the Play listing (text + images) inside one Edit, then validate and commit. iOS/Android are separate
 // stores — this is the Google half. Images only touch a type whose local asset EXISTS (so a missing local
@@ -23,12 +14,13 @@ export async function run(config, client) {
   // SAFE BY DEFAULT: validate + discard the edit unless `--apply`. A store-mutating commit must be an
   // explicit opt-in — never the default (a stale/partial local set could otherwise clobber a live one).
   const commit = !client.dryRun;
+  const IMAGES = playImages(config);
   const localLangs = fs.existsSync(g.metadataDir)
     ? fs.readdirSync(g.metadataDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)
     : [];
   const haveImages = IMAGES.some(([, src]) => fs.existsSync(src));
   if (!localLangs.length && !haveImages) {
-    console.log(yellow(`fill(play): no local listing folders under ${g.metadataDir} and no zdymak play assets — nothing to upload yet (populate them for Android Phase 2).`));
+    console.log(yellow(`fill(play): no local listing folders under ${g.metadataDir} and no local play assets — nothing to upload yet (populate them, or run \`vydanne bridge\`).`));
     return true;
   }
 
@@ -52,14 +44,23 @@ export async function run(config, client) {
       }
     }
     // Images — replace a type only when the local asset exists (delete-all then upload).
-    const lang = g.defaultLocale;
-    for (const [type, src, kind] of IMAGES) {
-      if (!fs.existsSync(src)) continue;
-      const files = kind === "dir" ? fs.readdirSync(src).filter((f) => /\.(png|jpe?g)$/i.test(f)).sort().map((f) => path.join(src, f)) : [src];
-      if (!files.length) continue;
-      await client.deleteAllImages(editId, lang, type);
-      for (const f of files) await client.uploadImage(editId, lang, type, f);
-      console.log(green(`  ${lang}/${type}: ${files.length} image(s)`));
+    for (const lang of imageLocales(g, localLangs)) {
+      for (const [type, src, kind] of IMAGES) {
+        // A per-locale override directory (`<src>/<lang>`) wins when it exists, so an app can localize
+        // some slots and leave the rest shared without listing every combination in the config.
+        const localized = path.join(src, lang);
+        const from = kind === "dir" && fs.existsSync(localized) ? localized : src;
+        if (!fs.existsSync(from)) continue;
+        const files = kind === "dir" ? fs.readdirSync(from).filter((f) => /\.(png|jpe?g)$/i.test(f)).sort().map((f) => path.join(from, f)) : [from];
+        // A dir that EXISTS but is empty is different from a missing one: someone (the store-assets
+        // bridge, when zdymak stops producing a form factor) deliberately emptied it, expecting the live
+        // set to follow. It doesn't — never-delete-by-omission holds — but that must be said, because the
+        // silent skip is how a listing keeps showing screenshots of a UI the app no longer has.
+        if (!files.length) { console.log(yellow(`  ${lang}/${type}: local dir is empty — live set left untouched (delete it in Play Console if it is stale)`)); continue; }
+        await client.deleteAllImages(editId, lang, type);
+        for (const f of files) await client.uploadImage(editId, lang, type, f);
+        console.log(green(`  ${lang}/${type}: ${files.length} image(s)`));
+      }
     }
 
     const v = await client.validate(editId);

package/src/play/commands/prerelease.mjs

@@ -1,9 +1,17 @@
 import fs from "node:fs";
 import path from "node:path";
 import { green, yellow, red } from "../../util.mjs";
+import { readAabVersionCode } from "../aab.mjs";
 
-/** Tracks this command will write. `production` is deliberately absent — see below. */
-const TESTING_TRACKS = new Set(["internal", "alpha", "beta"]);
+/**
+ * The one track this command refuses. Everything else is passed through.
+ *
+ * `internal`, `alpha` and `beta` are Play's BUILT-IN track names, not the whole vocabulary: Play
+ * Console encourages named closed tracks ("qa", "beta-partners"), and its API addresses them by that
+ * name. A closed list rejected every one of them with "unknown track" — refusing a release for a
+ * reason that was never true. The production refusal below is the one that matters, and it is exact.
+ */
+const PRODUCTION = "production";
 
 /**
  * Upload an .aab to a CLOSED TESTING track, with release notes.
@@ -26,13 +34,15 @@ export async function run(config, client) {
   const g = config.google;
   const track = process.env.VYDANNE_TRACK || g.track || "internal";
 
-  if (track === "production") {
+  if (track === PRODUCTION) {
     console.error(red("prerelease: refusing to write the production track — that release is a human's to make."));
     console.error("  Promote the tested build in Play Console when you're ready.");
     return false;
   }
-  if (!TESTING_TRACKS.has(track)) {
-    console.error(red(`prerelease: unknown track "${track}" (expected: ${[...TESTING_TRACKS].join(", ")})`));
+  // Any other name is handed to Play, which knows its own tracks: a typo comes back as a 404 naming
+  // the track, which is a better error than a list that was never authoritative.
+  if (!track) {
+    console.error(red("prerelease: no track — set `google.track` or VYDANNE_TRACK."));
     return false;
   }
 
@@ -44,6 +54,16 @@ export async function run(config, client) {
   console.log(green(`prerelease → track "${track}"`));
   console.log(`  bundle: ${path.relative(process.cwd(), aab) || aab}  (${(fs.statSync(aab).size / 1e6).toFixed(1)} MB)`);
 
+  // The bundle declares its own versionCode, so read it HERE — before the multi-megabyte upload — and
+  // resolve the changelogs against it while there is still time to fix them. In repos that derive the
+  // code from `git rev-list --count HEAD` it is unknowable in advance, so nobody can pre-name
+  // `<versionCode>.txt`; the fallback used to win silently and the first place the real number ever
+  // appeared was Play's upload response. A null here (unreadable bundle) degrades to exactly that old
+  // behaviour: Play's answer after upload stays the authority either way.
+  const declared = readAabVersionCode(aab);
+  if (declared != null) console.log(`  versionCode ${declared} (read from the bundle's manifest)`);
+  let notes = declared != null ? readNotes(g.metadataDir, declared, g.defaultLocale) : null;
+
   const editId = await client.newEdit();
   try {
     // Upload, or REUSE. Play rejects a versionCode it already holds, which is the right answer for an
@@ -63,16 +83,17 @@ export async function run(config, client) {
       console.log(yellow(`  versionCode ${versionCode} already uploaded — reusing that bundle`));
     }
 
-    const releaseNotes = readNotes(g.metadataDir, versionCode, g.defaultLocale);
-    if (releaseNotes.length) {
-      console.log(`  release notes: ${releaseNotes.length} locale(s) — ${releaseNotes.map((n) => n.language).join(", ")}`);
-    } else {
-      console.log(yellow(`  no release notes found under ${g.metadataDir}/<locale>/changelogs/{${versionCode},default}.txt`));
+    if (declared != null && declared !== versionCode) {
+      // Play's answer is derived from the same manifest, so a disagreement means OUR parser misread the
+      // bundle — say so and re-resolve the notes against the truth rather than shipping the wrong file.
+      console.log(yellow(`  bundle parse said ${declared} but Play says ${versionCode} — trusting Play (please report this)`));
+      notes = null;
     }
+    if (!notes) notes = readNotes(g.metadataDir, versionCode, g.defaultLocale);
 
     // One complete release object: Play replaces the track's releases wholesale.
     const release = { status: "completed", versionCodes: [String(versionCode)] };
-    if (releaseNotes.length) release.releaseNotes = releaseNotes;
+    if (notes.entries.length) release.releaseNotes = notes.entries;
     const name = process.env.VYDANNE_RELEASE_NAME;
     if (name) release.name = name;
 
@@ -87,6 +108,7 @@ export async function run(config, client) {
     const res = await client.commit(editId);
     if (res.status >= 300) throw new Error(`edits.commit ${res.status}: ${JSON.stringify(res.json).slice(0, 300)}`);
     console.log(green(`\n  committed — versionCode ${versionCode} is live on "${track}".`));
+    archiveNextNotes(notes, versionCode);
     console.log("  Production stays manual: promote it in Play Console when you're ready.");
     return true;
   } catch (e) {
@@ -111,27 +133,79 @@ function resolveAab(configured) {
 }
 
 /**
- * Release notes per locale, following fastlane supply's layout so an existing repo needs no migration:
- * `<metadataDir>/<play-locale>/changelogs/<versionCode>.txt`, falling back to `default.txt`.
+ * Release notes per locale — supply's layout, plus a convention that breaks the naming circularity:
+ *
+ *   <metadataDir>/<play-locale>/changelogs/<versionCode>.txt   exact — supply's own convention
+ *                                          next.txt            THIS release, named before its code exists
+ *                                          default.txt         evergreen fallback ("bug fixes")
+ *
+ * `next.txt` exists because `<versionCode>.txt` cannot be written in advance when the code is derived
+ * from the commit count: every commit moves the number, so the only file you could name ahead of time
+ * was `default.txt` — which then also serves every FUTURE release, silently. Write this release's
+ * notes as `next.txt`; after a real commit they are archived as `<versionCode>.txt` (the code is known
+ * by then), so the next release cannot inherit them by accident.
+ *
+ * Which file won is reported per source, and the default.txt fallback is a WARNING — it used to be
+ * indistinguishable from an exact match, which is how a release ships with last release's notes.
  */
 function readNotes(metadataDir, versionCode, defaultLocale) {
-  const out = [];
-  if (!metadataDir || !fs.existsSync(metadataDir)) return out;
+  const entries = [];
+  const bySource = { [`${versionCode}.txt`]: 0, "next.txt": 0, "default.txt": 0 };
+  const nextFiles = [];
+  const empty = [];
+  if (!metadataDir || !fs.existsSync(metadataDir)) return { entries, nextFiles };
   for (const language of fs.readdirSync(metadataDir)) {
     const dir = path.join(metadataDir, language, "changelogs");
     if (!fs.existsSync(dir)) continue;
-    const file = [path.join(dir, `${versionCode}.txt`), path.join(dir, "default.txt")].find((f) => fs.existsSync(f));
+    const file = [`${versionCode}.txt`, "next.txt", "default.txt"].map((f) => path.join(dir, f)).find((f) => fs.existsSync(f));
     if (!file) continue;
     const text = fs.readFileSync(file, "utf8").trim();
-    if (!text) continue;
+    // An empty file would otherwise drop the locale without a word — name it below instead.
+    if (!text) { empty.push(`${language}/${path.basename(file)}`); continue; }
+    bySource[path.basename(file)]++;
+    if (path.basename(file) === "next.txt") nextFiles.push(file);
     // Play caps release notes at 500 chars and rejects the whole edit if any locale is over.
     if (text.length > 500) {
       console.log(yellow(`  ${language}: release notes ${text.length}/500 chars — truncated`));
-      out.push({ language, text: text.slice(0, 500) });
+      entries.push({ language, text: text.slice(0, 500) });
     } else {
-      out.push({ language, text });
+      entries.push({ language, text });
     }
   }
   // Keep the default locale first purely so the log reads sensibly.
-  return out.sort((a, b) => (a.language === defaultLocale ? -1 : b.language === defaultLocale ? 1 : 0));
+  entries.sort((a, b) => (a.language === defaultLocale ? -1 : b.language === defaultLocale ? 1 : 0));
+
+  if (!entries.length) {
+    console.log(yellow(`  no release notes found under ${notesPattern(metadataDir, versionCode)}`));
+  } else {
+    const parts = Object.entries(bySource).filter(([, n]) => n).map(([f, n]) => `${n} from ${f}`);
+    console.log(`  release notes for versionCode ${versionCode}: ${entries.length} locale(s) — ${parts.join(" · ")}`);
+    if (bySource["default.txt"]) {
+      console.log(yellow(`  ${bySource["default.txt"]} locale(s) fell back to default.txt — no ${versionCode}.txt or next.txt.`));
+      console.log(yellow("  If those notes describe an older release, write this one's as changelogs/next.txt."));
+    }
+  }
+  if (empty.length) console.log(yellow(`  empty changelog file(s), locale dropped: ${empty.join(", ")}`));
+  return { entries, nextFiles };
+}
+
+const notesPattern = (dir, code) => `${dir}/<locale>/changelogs/{${code},next,default}.txt`;
+
+/**
+ * After a REAL commit, park each next.txt under the versionCode it just shipped as. Renaming (not
+ * copying) is the point: a `next.txt` that lingered would be picked up by the NEXT release too, and
+ * "this release's notes" quietly becoming "every release's notes" is the exact failure default.txt
+ * already has. The rename also lands on supply's own `<versionCode>.txt` convention, so the history
+ * of what shipped with what stays greppable.
+ */
+function archiveNextNotes(notes, versionCode) {
+  for (const file of notes.nextFiles) {
+    const to = path.join(path.dirname(file), `${versionCode}.txt`);
+    try {
+      fs.renameSync(file, to);
+      console.log(`  archived ${path.relative(process.cwd(), file)} -> ${versionCode}.txt`);
+    } catch (e) {
+      console.log(yellow(`  could not archive ${file}: ${e.message} — rename it to ${versionCode}.txt yourself, or the next release reuses it`));
+    }
+  }
 }

package/src/play/images.mjs

@@ -0,0 +1,67 @@
+/**
+ * Play listing images: the type vocabulary, and where each one is read from by default.
+ *
+ * ONE table, imported by `fill --store google` (which uploads them), `diff --store google` (which
+ * compares them) and `bridge` (which fills the folders they read). A second copy would let the three
+ * disagree about which files are even part of the listing — the same drift src/screenshots.mjs exists
+ * to prevent on the Apple side.
+ *
+ * The DEFAULTS are this portfolio's layout and are meant to be overridden: `google.images` in
+ * vydanne.config.mjs is merged over them, slot by slot. The icon default in particular points at
+ * znachok's output directory, which is an obvious path if you use znachok and a mystery otherwise.
+ *
+ * `wearScreenshots` and the TV slots have no historical default because nothing here shipped them yet;
+ * they are listed so a Wear OS or Android TV release is a config line rather than a code change. A type
+ * whose local source does not exist is skipped, so listing them costs nothing.
+ */
+
+/** Play image type -> whether its local source is a single file or a directory of images. */
+export const PLAY_IMAGE_KIND = {
+  icon: "file",
+  featureGraphic: "file",
+  tvBanner: "file",
+  phoneScreenshots: "dir",
+  sevenInchScreenshots: "dir",
+  tenInchScreenshots: "dir",
+  wearScreenshots: "dir",
+  tvScreenshots: "dir",
+};
+
+/** Play image type -> default local source path. */
+export const DEFAULT_PLAY_IMAGES = {
+  icon: "brand/icons/play/icon-512.png",
+  featureGraphic: "marketing/out/play-feature-graphic.png",
+  phoneScreenshots: "marketing/out/play-phone-plain",
+  sevenInchScreenshots: "marketing/out/play-tablet7-plain",
+  tenInchScreenshots: "marketing/out/play-tablet-plain",
+  wearScreenshots: "marketing/out/play-wear",
+};
+
+/**
+ * The resolved table for one app: [type, localSource, kind][].
+ *
+ * Shaped as tuples because that is what the callers iterate; an unknown type defaults to "dir", which
+ * is the only guess that cannot lose data — a directory source that is really a file simply won't exist.
+ */
+export function playImages(config) {
+  const table = config?.google?.images ?? DEFAULT_PLAY_IMAGES;
+  return Object.entries(table).map(([type, src]) => [type, src, PLAY_IMAGE_KIND[type] ?? "dir"]);
+}
+
+/**
+ * Which locales get graphics.
+ *
+ * Play holds images PER LANGUAGE; uploading only to `defaultLocale` was this portfolio's choice (one
+ * untranslated set for every market), not a platform limit, and the code asserted it as though it were
+ * one. `google.imageLocales` opts into localized art: a list of language codes, or "*" for every local
+ * listing folder. The default stays one set at `defaultLocale`, so nothing changes for an app that never
+ * asks. Shared by `fill` and `diff` so they cannot disagree about which locales are even being compared.
+ */
+export function imageLocales(g, localLangs = []) {
+  const want = g?.imageLocales;
+  if (!want) return [g.defaultLocale];
+  if (want === "*" || (Array.isArray(want) && want.includes("*"))) {
+    return localLangs.length ? localLangs : [g.defaultLocale];
+  }
+  return Array.isArray(want) ? want : [want];
+}

package/src/registry.mjs

@@ -10,6 +10,14 @@
 // the STORE specifically — `privacy` and `compliance` write local files (a record, a PDF) and are not
 // marked, because a dry run that refused to produce a local artefact would just be broken.
 export const COMMANDS = {
+  // Creates the editable version everything below writes INTO, so it comes first in more than
+  // listing order: on an app with a version already on sale, `fill` has nothing valid to target
+  // until this has run once.
+  prepare: { mod: "prepare", client: true, writes: true },
+  // The pipeline in its one working order — prepare → fill → previews → age-rating → review-contact →
+  // accessibility → preflight — because that order lived in nobody's head, and a release nearly got
+  // written to a live listing while everyone re-derived it. Stops at the first failure; never submits.
+  push: { mod: "push", client: true, writes: true },
   fill: { mod: "fill", client: true, writes: true },
   "age-rating": { mod: "ageRating", client: true, writes: true },
   "review-contact": { mod: "reviewContact", client: true, writes: true },
@@ -18,6 +26,9 @@ export const COMMANDS = {
   previews: { mod: "previews", client: true, writes: true },
   iap: { mod: "iap", client: false },
   compliance: { mod: "compliance", client: false },
+  // Maps zdymak's output layout onto the folders `fill` reads. Local files only (like privacy and
+  // compliance above), so it is not marked `writes` — it has its own `--dry-run` instead.
+  bridge: { mod: "bridge", client: false },
   inspect: { mod: "inspect", client: true },
   diff: { mod: "diff", client: true },
   preflight: { mod: "preflight", client: true },

package/src/screenshots.mjs

@@ -0,0 +1,112 @@
+import fs from "node:fs";
+import path from "node:path";
+import { md5 } from "./upload.mjs";
+import { VALID } from "./locales.mjs";
+
+// Screenshot filename prefix -> ASC display type, plus the base paths. ONE copy, used by three commands:
+// `fill` uploads by these, `diff` and `preflight` judge freshness by them. They used to be pasted into
+// fill.mjs and diff.mjs separately, which is one edit away from `fill` uploading a set that `diff` then
+// can't see — the same drift this module's callers exist to catch in other people.
+// Apple accepts JPEG as well as PNG for screenshots. The `.png`-only filter this replaces made a `.jpg`
+// set invisible to fill, diff AND preflight at once: nothing uploaded, nothing compared, preflight green.
+export const IMAGE_FILE = /\.(png|jpe?g)$/i;
+
+export const IOS_DEVICE = { iphone69: "APP_IPHONE_67", iphone65: "APP_IPHONE_65", ipad13: "APP_IPAD_PRO_3GEN_129", watch: "APP_WATCH_ULTRA" };
+export const MAC_DEVICE = { macos: "APP_DESKTOP" };
+export const deviceMap = (platform) => (platform === "MAC_OS" ? MAC_DEVICE : IOS_DEVICE);
+
+// fastlane's supply convention, which is what most repos already have — but a DEFAULT now, not a law.
+// These two paths were hardcoded, and the docs said so out loud ("symlink them if your layout differs"),
+// which is an honest way to describe a tool that cannot be pointed at your repo. `metadataDir` was always
+// configurable; there was never a reason for its sibling not to be.
+export const DEFAULT_SCREENSHOT_BASE = { IOS: "fastlane/screenshots", MAC_OS: "fastlane/screenshots-macos" };
+
+/** Where this platform's screenshots live: `screenshots` in the config, else the supply convention. */
+export const screenshotBase = (platform, config) =>
+  config?.screenshots?.[platform] ?? DEFAULT_SCREENSHOT_BASE[platform] ?? DEFAULT_SCREENSHOT_BASE.IOS;
+
+/**
+ * Locales with a local screenshot folder for this platform.
+ *
+ * Filtered through `VALID` for the same reason `fill` filters its upload loop through it: a folder named
+ * `de` instead of `de-DE` is not a locale Apple knows, and treating it as one would compare a real store
+ * localization against nothing. The caller reports what was dropped — see `unknownScreenshotDirs`.
+ */
+export function localScreenshotLocales(platform, config) {
+  const base = screenshotBase(platform, config);
+  if (!fs.existsSync(base)) return [];
+  return fs.readdirSync(base, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && VALID.has(d.name))
+    .map((d) => d.name)
+    .sort();
+}
+
+/** Screenshot folders that are NOT App Store locale codes — reported, never silently ignored. */
+export function unknownScreenshotDirs(platform, config) {
+  const base = screenshotBase(platform, config);
+  if (!fs.existsSync(base)) return [];
+  return fs.readdirSync(base, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !VALID.has(d.name))
+    .map((d) => d.name)
+    .sort();
+}
+
+/** The local set for one locale: displayType -> Map(fileName -> md5 of the bytes). */
+export function localScreenshots(platform, locale, config) {
+  const dir = path.join(screenshotBase(platform, config), locale);
+  const dev = deviceMap(platform);
+  const local = {};
+  if (!fs.existsSync(dir)) return local;
+  for (const f of fs.readdirSync(dir).filter((f) => IMAGE_FILE.test(f)).sort()) {
+    const dt = dev[f.split("_")[0]];
+    if (dt) (local[dt] ||= new Map()).set(f, md5(fs.readFileSync(path.join(dir, f))));
+  }
+  return local;
+}
+
+/**
+ * What the store holds for one localization: displayType -> Map(fileName -> sourceFileChecksum|null).
+ *
+ * `include=appScreenshots` returns the shots as full resources in `included`; the set's relationships
+ * carry ids only, so the attributes (fileName, sourceFileChecksum) have to be picked up from there. A
+ * null checksum means Apple reported the file but not its content — present, and unverifiable.
+ */
+export async function remoteScreenshots(client, locId) {
+  const { json: sets } = await client.get(`/v1/appStoreVersionLocalizations/${locId}/appScreenshotSets?include=appScreenshots&limit=50`);
+  const shotsById = new Map((sets.included || []).filter((r) => r.type === "appScreenshots").map((r) => [r.id, r.attributes || {}]));
+  const remote = {};
+  for (const s of sets.data || []) {
+    const m = new Map();
+    for (const ref of s.relationships?.appScreenshots?.data || []) {
+      const a = shotsById.get(ref.id);
+      if (a) m.set(a.fileName, a.sourceFileChecksum ?? null);
+      else m.set(ref.id, null); // not included — treat as present but unverifiable
+    }
+    remote[s.attributes.screenshotDisplayType] = m;
+  }
+  return remote;
+}
+
+/**
+ * One display type, local vs store — by CONTENT, not by count. Counting was actively misleading:
+ * re-rendering every screenshot leaves three-local-vs-three-remote, so a count check says "in sync"
+ * about a listing showing the old images. The checksum is there to compare against: `upload.mjs`
+ * commits md5(bytes) as `sourceFileChecksum`.
+ *
+ * Returns null on a verified match, else one finding — the kinds need different actions, so they are
+ * kept apart rather than collapsed into a boolean:
+ *   count      the sets aren't even the same size
+ *   renamed    same size, but local names the store doesn't have
+ *   stale      same names, different bytes — the store is showing old art
+ *   unverified Apple returned no checksum, so a match was never established (say so, don't claim it)
+ */
+export function compareShots(L, R) {
+  if (L.size !== R.size) return { kind: "count", local: L.size, remote: R.size };
+  const renamed = [...L.keys()].filter((name) => !R.has(name));
+  if (renamed.length) return { kind: "renamed", names: renamed };
+  const stale = [...L].filter(([name, sum]) => R.get(name) !== null && R.get(name) !== sum).map(([name]) => name);
+  if (stale.length) return { kind: "stale", names: stale, of: L.size };
+  const unverified = [...L.keys()].filter((name) => R.get(name) === null);
+  if (unverified.length) return { kind: "unverified", names: unverified };
+  return null;
+}