vydanne 0.5.0 → 0.7.0

package/src/crossStore.mjs

@@ -0,0 +1,151 @@
+import fs from "node:fs";
+import path from "node:path";
+import { red, yellow, green } from "./util.mjs";
+
+/**
+ * Refuse to send one store a listing that talks about the other one.
+ *
+ * WHY THIS IS IN THE TOOL AND NOT IN A CHECKLIST. Both stores forbid it, both enforce it by
+ * REJECTING a submission, and it is the single easiest thing to do by accident — because the two
+ * listings are written from the same source copy, by the same person, often by a translator who was
+ * handed an English master that happened to say "also on Google Play". Apple's App Review guideline
+ * 2.3.10 is explicit ("does not include names, icons, or imagery of other mobile platforms"), and
+ * Google Play's Store Listing and Promotion policy is the mirror of it. Nobody discovers this while
+ * writing the copy; they discover it days later, from a rejection, in one locale out of twenty.
+ *
+ * So it is checked HERE, against the local files that are about to be uploaded, before anything is
+ * sent. That is the only place it can be caught for free.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO. It does not flag a store's own platform — "Android" belongs in
+ * a Play listing and "iPhone" belongs in an App Store one. And it does not flag the bare word
+ * "Play", which is a verb every game listing on earth uses; only the store's actual name.
+ *
+ * Findings come in two tiers, because the certainty differs:
+ *   block — unambiguous: a store name, a store URL, a competing platform's device name.
+ *   warn  — a word that is usually a reference but sometimes just a word ("apple" in a game about
+ *           fruit). Reported, never fatal, and silenceable per app.
+ *
+ * An app with a genuine exception sets `allowCrossStoreTerms: ["..."]` in its vydanne config.
+ */
+
+/** Terms that must not appear in a listing for [store]. Ordered longest-first so the report names
+ *  the most specific match rather than a fragment of it. */
+const FOREIGN = {
+  apple: [
+    { term: "play.google.com", re: /play\.google\.com/i, level: "block" },
+    { term: "Google Play", re: /google\s*play/i, level: "block" },
+    { term: "Play Store", re: /\bplay[- ]?store\b/i, level: "block" },
+    { term: "Play Market", re: /\bplay[- ]?market\b/i, level: "block" },
+    { term: "Android", re: /\bandroid\b/i, level: "block" },
+    { term: "安卓", re: /安卓/, level: "block" },
+    { term: "アンドロイド", re: /アンドロイド/, level: "block" },
+    { term: "안드로이드", re: /안드로이드/, level: "block" },
+    { term: "Андроид/Андроїд", re: /андро[иї]д/i, level: "block" },
+    { term: "أندرويد", re: /أندرويد/, level: "block" },
+    { term: "אנדרואיד", re: /אנדרואיד/, level: "block" },
+    { term: "एंड्रॉइड", re: /एंड्रॉ?इड/, level: "block" },
+    { term: "APK", re: /\bapk\b/i, level: "warn" },
+    { term: "Chromebook", re: /\bchromebook\b/i, level: "warn" },
+  ],
+  google: [
+    { term: "apps.apple.com", re: /apps\.apple\.com/i, level: "block" },
+    { term: "App Store", re: /\bapp[- ]?store\b/i, level: "block" },
+    { term: "TestFlight", re: /\btestflight\b/i, level: "block" },
+    { term: "iPhone", re: /\biphone\b/i, level: "block" },
+    { term: "iPad", re: /\bipad(os)?\b/i, level: "block" },
+    { term: "iOS", re: /\bios\b/i, level: "block" },
+    { term: "Apple Arcade", re: /\bapple\s+arcade\b/i, level: "block" },
+    { term: "苹果", re: /苹果/, level: "block" },
+    { term: "애플", re: /애플/, level: "block" },
+    { term: "アップル", re: /アップル/, level: "block" },
+    // Sometimes a fruit, so it is reported rather than fatal.
+    { term: "Apple", re: /\bapple\b/i, level: "warn" },
+  ],
+};
+
+/** Local text a store actually uploads. Keys are the file basenames each fill() reads. */
+const APPLE_FILES = [
+  "name", "subtitle", "description", "keywords", "promotional_text",
+  "release_notes", "marketing_url", "support_url",
+];
+const PLAY_FILES = ["title", "short_description", "full_description"];
+
+/** One short line of context so a finding can be found and fixed without opening the file blind. */
+function excerpt(text, match) {
+  const at = text.toLowerCase().indexOf(match.toLowerCase());
+  if (at < 0) return "";
+  const from = Math.max(0, at - 28);
+  const to = Math.min(text.length, at + match.length + 28);
+  return `${from ? "…" : ""}${text.slice(from, to).replace(/\s+/g, " ")}${to < text.length ? "…" : ""}`;
+}
+
+/**
+ * Scan the local metadata tree for [store].
+ *
+ * @returns {{findings: Array, scanned: number}} findings carry {level, locale, field, term, excerpt}
+ */
+export function scanCrossStore(store, metadataDir, allow = []) {
+  const rules = FOREIGN[store].filter((r) => !allow.some((a) => a.toLowerCase() === r.term.toLowerCase()));
+  const files = store === "apple" ? APPLE_FILES : PLAY_FILES;
+  const findings = [];
+  let scanned = 0;
+  if (!metadataDir || !fs.existsSync(metadataDir)) return { findings, scanned };
+
+  for (const entry of fs.readdirSync(metadataDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    for (const field of files) {
+      const p = path.join(metadataDir, entry.name, `${field}.txt`);
+      if (!fs.existsSync(p)) continue;
+      const text = fs.readFileSync(p, "utf8");
+      scanned++;
+      for (const rule of rules) {
+        const m = text.match(rule.re);
+        if (!m) continue;
+        findings.push({
+          level: rule.level,
+          locale: entry.name,
+          field,
+          term: rule.term,
+          excerpt: excerpt(text, m[0]),
+        });
+      }
+    }
+  }
+  return { findings, scanned };
+}
+
+/** The other store's human name, for the message. */
+const OTHER = { apple: "Google Play / Android", google: "the App Store / iOS" };
+const GUIDELINE = {
+  apple: "App Review guideline 2.3.10 — metadata must not name other mobile platforms.",
+  google: "Google Play Store Listing and Promotion policy — no references to other app stores.",
+};
+
+/**
+ * Report findings. Returns false when something BLOCKING was found, so callers can refuse to upload.
+ *
+ * Printing every locale rather than the first is the point: this fails one translation at a time,
+ * and knowing it is 3 locales and not 20 is the difference between a fix and a re-translation.
+ */
+export function reportCrossStore(store, metadataDir, allow = []) {
+  const { findings, scanned } = scanCrossStore(store, metadataDir, allow);
+  if (!scanned) return true;
+
+  const blocking = findings.filter((f) => f.level === "block");
+  const warnings = findings.filter((f) => f.level === "warn");
+
+  if (blocking.length) {
+    console.log(red(`  cross-store: ${blocking.length} reference(s) to ${OTHER[store]} in listing text`));
+    console.log(`    ${GUIDELINE[store]}`);
+    for (const f of blocking) {
+      console.log(`    ${red("x")} ${f.locale}/${f.field}: "${f.term}"  ${f.excerpt}`);
+    }
+  }
+  for (const f of warnings) {
+    console.log(`    ${yellow("!")} ${f.locale}/${f.field}: "${f.term}" — check this is not a platform reference  ${f.excerpt}`);
+  }
+  if (!blocking.length && !warnings.length) {
+    console.log(green(`  cross-store: clean (${scanned} files)`));
+  }
+  return blocking.length === 0;
+}

package/src/index.mjs

@@ -1,6 +1,63 @@
-// Programmatic entry (the CLI is bin/vydanne.mjs). `import { Client, loadConfig } from "vydanne"`.
+// Programmatic entry (the CLI is bin/vydanne.mjs). `import { runCommand, loadConfig } from "vydanne"`.
+//
+// This used to export a client, a config loader and the command REGISTRY — a table of `{ mod: "fill" }`
+// filenames that nothing outside the package could resolve, because `exports` maps only ".". So a
+// consumer could see that `fill` existed and had no way to run it. `runCommand` is that missing half:
+// the same dispatch bin/ performs, minus the argv parsing and the process.exit.
+import { Client } from "./client.mjs";
+import { loadConfig } from "./config.mjs";
+import { COMMANDS, PLAY_COMMANDS } from "./registry.mjs";
+
 export { Client } from "./client.mjs";
+export { PlayClient } from "./play/client.mjs";
 export { loadConfig, CONFIG_KEYS } from "./config.mjs";
-export { COMMANDS, COMMAND_NAMES } from "./registry.mjs";
-export { resolveLocales, toAsc, VALID } from "./locales.mjs";
+export { COMMANDS, PLAY_COMMANDS, COMMAND_NAMES } from "./registry.mjs";
+export { resolveLocales, toAsc, VALID, UI_TO_ASC } from "./locales.mjs";
 export { makeToken } from "./jwt.mjs";
+export { DEFAULT_SCREENSHOT_BASE, IOS_DEVICE, MAC_DEVICE, screenshotBase } from "./screenshots.mjs";
+export { DEFAULT_PLAY_IMAGES, PLAY_IMAGE_KIND, playImages } from "./play/images.mjs";
+
+/**
+ * Run one command, the way the CLI runs it.
+ *
+ * `apply` is the same safety gate the `--apply` flag drives, and it defaults to FALSE here for the same
+ * reason it does there: a caller that forgets it gets a dry run, never a write. A command that writes
+ * to the store receives a client already refusing mutations, so "dry run" is enforced in the client
+ * rather than trusted to each command.
+ *
+ * Returns `{ ok, planned }` — `planned` being the writes a dry run withheld, which is the machine-
+ * readable form of what the CLI prints as "N store write(s) withheld".
+ *
+ * @param {string} name    a key of COMMANDS (or of PLAY_COMMANDS when store is "google")
+ * @param {object} [opts]
+ * @param {object} [opts.config]     a loaded config; loaded from disk when omitted
+ * @param {string} [opts.configPath] path to vydanne.config.mjs, when loading from disk
+ * @param {"apple"|"google"} [opts.store]
+ * @param {boolean} [opts.apply]     perform store writes (default false — dry run)
+ */
+export async function runCommand(name, opts = {}) {
+  const { store = "apple", apply = false, configPath } = opts;
+  if (store !== "apple" && store !== "google") throw new Error(`vydanne: unknown store '${store}' (expected: apple, google)`);
+
+  const config = opts.config || (await loadConfig(configPath));
+  const table = store === "google" ? PLAY_COMMANDS : COMMANDS;
+  const spec = table[name];
+  if (!spec) throw new Error(`vydanne: unknown command '${name}' for store '${store}' (try: ${Object.keys(table).join(", ")})`);
+
+  const dryRun = Boolean(spec.writes) && !apply;
+
+  if (store === "google") {
+    if (!config.google) throw new Error("vydanne: no `google` block in config — add packageName + a service-account key");
+    if (!config.google.serviceAccountKey) throw new Error("vydanne: set PLAY_JSON_KEY_FILE (or google.serviceAccountKey) to the Play service-account JSON");
+    const { PlayClient } = await import("./play/client.mjs");
+    const client = await PlayClient.create({ keyPath: config.google.serviceAccountKey, packageName: config.google.packageName, dryRun });
+    const { run } = await import(`./play/commands/${spec.mod}.mjs`);
+    return { ok: (await run(config, client)) !== false, planned: [] };
+  }
+
+  const client = spec.client ? new Client({ keyId: config.keyId, issuerId: config.issuerId, dryRun }) : null;
+  const { run } = await import(`./commands/${spec.mod}.mjs`);
+  // altool authenticates on its own rather than through our JWT, so it needs the raw ids.
+  const ok = await run(config, client, spec.credentials ? { keyId: config.keyId, issuerId: config.issuerId } : undefined);
+  return { ok: ok !== false, planned: client?.planned ?? [] };
+}

package/src/locales.mjs

@@ -8,19 +8,41 @@ export const VALID = new Set([
   "te-IN", "th", "tr", "uk", "ur-PK", "vi", "zh-Hans", "zh-Hant",
 ]);
 
+// Short UI code -> App Store code. `nb` and `iw` are Android's spellings of Norwegian and Hebrew: a
+// project that names its resource folders the Android way (values-nb, values-iw) would otherwise have
+// both locales resolve to "no App Store language" and fall back to the primary listing — a silently
+// missing translation for a language Apple does support under a different code.
 export const UI_TO_ASC = {
   ar: "ar-SA", bn: "bn-BD", de: "de-DE", es: "es-ES", fr: "fr-FR", nl: "nl-NL",
   pt: "pt-BR", ur: "ur-PK", zh: "zh-Hans", en: "en-US",
+  nb: "no", iw: "he", in: "id", ji: "he",
 };
 
-export const toAsc = (code) => (VALID.has(code) ? code : UI_TO_ASC[code] || null);
+/**
+ * `code` as an App Store locale, or null when Apple has no listing language for it.
+ *
+ * `extra` is the app's own `localeMap` — the extension point this table lacked. Apple's list moves, and
+ * projects spell locales in whatever their UI framework uses; neither is a reason to need a vydanne
+ * release. An app can map its code onto a VALID one, and only onto a VALID one: an override pointing at
+ * a language Apple does not have would fail at upload instead of here.
+ */
+export const toAsc = (code, extra) => {
+  if (VALID.has(code)) return code;
+  const mapped = extra?.[code] ?? UI_TO_ASC[code] ?? null;
+  return mapped && VALID.has(mapped) ? mapped : null;
+};
 
-export function resolveLocales(uiCodes = []) {
+export function resolveLocales(uiCodes = [], extra) {
   const supported = {};
   const unsupported = [];
+  const invalid = [];
   for (const c of uiCodes) {
-    const asc = toAsc(c);
-    asc ? (supported[c] = asc) : unsupported.push(c);
+    const asc = toAsc(c, extra);
+    if (asc) supported[c] = asc;
+    // An override that names a code Apple doesn't have is a config mistake, not a missing language —
+    // kept apart so the report can say which it is instead of blaming the locale.
+    else if (extra?.[c]) invalid.push(`${c} -> ${extra[c]}`);
+    else unsupported.push(c);
   }
-  return { supported, unsupported };
+  return { supported, unsupported, invalid };
 }

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/client.mjs

@@ -9,13 +9,16 @@ const UPLOAD = "https://androidpublisher.googleapis.com/upload/androidpublisher/
 // transaction — insert an edit, mutate listings/images/details against it, then commit (all-or-nothing).
 // Nothing is live until commit; a dropped edit changes nothing. Image bytes go to the /upload endpoint.
 export class PlayClient {
-  static async create({ keyPath, packageName }) {
+  static async create({ keyPath, packageName, dryRun = false }) {
     const token = await getAccessToken(keyPath);
-    return new PlayClient(token, packageName);
+    return new PlayClient(token, packageName, dryRun);
   }
-  constructor(token, packageName) {
+  constructor(token, packageName, dryRun = false) {
     this.token = token;
     this.pkg = packageName;
+    // Gates the COMMIT, not the requests: the edit is still built and validated against Google for real,
+    // which is the whole advantage of Play's transaction over Apple's fire-and-forget PATCHes.
+    this.dryRun = dryRun;
   }
 
   async req(method, subpath, { body, base = BASE } = {}) {

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

@@ -1,36 +1,35 @@
 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
-// set never deletes the live one). VYDANNE_DRY=1 validates and discards without committing.
+// set never deletes the live one). Without `--apply` it validates and discards without committing.
 export async function run(config, client) {
   const g = config.google;
-  // SAFE BY DEFAULT: validate + discard the edit unless VYDANNE_COMMIT=1. 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 = process.env.VYDANNE_COMMIT === "1";
+  // 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;
   }
 
+  if (process.env.VYDANNE_ALLOW_CROSS_STORE !== "1"
+      && !reportCrossStore("google", g.metadataDir, config.allowCrossStoreTerms)) {
+    console.error(red("fill(play): refusing to upload — fix the listing text, or set VYDANNE_ALLOW_CROSS_STORE=1."));
+    return false;
+  }
+
   const editId = await client.newEdit();
   try {
     // Listing text
@@ -45,19 +44,28 @@ 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);
     if (v.status >= 300) throw new Error(`validate ${v.status}: ${JSON.stringify(v.json).slice(0, 200)}`);
-    if (!commit) { await client.deleteEdit(editId); console.log(yellow("fill(play): validated — DRY (nothing changed). Review the above, then set VYDANNE_COMMIT=1 to commit.")); return true; }
+    if (!commit) { await client.deleteEdit(editId); console.log(yellow("fill(play): validated — DRY (nothing changed). Review the above, then re-run with --apply to commit.")); return true; }
     const co = await client.commit(editId);
     if (co.status >= 300) throw new Error(`commit ${co.status}: ${JSON.stringify(co.json).slice(0, 200)}`);
     console.log(green("fill(play): committed."));

package/src/play/commands/preflight.mjs

@@ -1,4 +1,5 @@
 import { green, red, yellow } from "../../util.mjs";
+import { reportCrossStore } from "../../crossStore.mjs";
 
 // Play listing limits.
 const LIMITS = { title: 30, shortDescription: 80, fullDescription: 4000 };
@@ -30,6 +31,10 @@ export async function run(config, client) {
   } finally {
     await client.deleteEdit(editId);
   }
+  if (!reportCrossStore("google", g.metadataDir, config.allowCrossStoreTerms)) {
+    problems.push("listing text references another app store (see above)");
+  }
+
   console.log();
   if (!problems.length) console.log(green("preflight: no blockers"));
   else { console.log(red(`preflight: ${problems.length} blocker(s)`)); problems.forEach((p) => console.log(`  ${red("x")} ${p}`)); }