vydanne 0.5.0 → 0.7.0

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,30 +83,32 @@ 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;
 
     const put = await client.putTrack(editId, track, [release]);
     if (put.status >= 300) throw new Error(`tracks.update ${put.status}: ${JSON.stringify(put.json).slice(0, 300)}`);
 
-    if (process.env.VYDANNE_COMMIT !== "1") {
+    if (client.dryRun) {
       await client.deleteEdit(editId);
-      console.log(yellow(`\n  DRY RUN — edit discarded, nothing changed. Re-run with VYDANNE_COMMIT=1 to publish to "${track}".`));
+      console.log(yellow(`\n  DRY RUN — edit discarded, nothing changed. Re-run with --apply to publish to "${track}".`));
       return true;
     }
     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

@@ -1,22 +1,40 @@
 // The canonical command registry — the single source of vydanne's public commands. bin/ dispatches from
 // this, and the drift guards (scripts/check-docs.mjs, scripts/check-types.mjs) assert every command is
 // documented in README/SKILL and typed in types/index.d.ts. Add a command here → the guards force it into
-// the docs + types before publish.  name -> { mod: <file in src/commands>, client: needs an ASC client }
+// the docs + types before publish.
+//
+//   name -> { mod: <file in src/commands>, client: needs an ASC client, writes: mutates the STORE }
+//
+// `writes` is what makes a command dry-run unless `--apply` is passed, so it is a safety declaration, not
+// a label: mark a new command `writes: true` the moment it can change anything on the store side. It means
+// 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 = {
-  fill: { mod: "fill", client: true },
-  "age-rating": { mod: "ageRating", client: true },
-  "review-contact": { mod: "reviewContact", client: true },
-  accessibility: { mod: "accessibility", client: true },
+  // 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 },
+  accessibility: { mod: "accessibility", client: true, writes: true },
   privacy: { mod: "privacy", client: false },
-  previews: { mod: "previews", client: true },
+  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 },
   // Uploads the .ipa to TestFlight. Needs the credentials as well as the client: the REST API
   // cannot carry a binary, so this one shells out to `xcrun altool`, which authenticates itself.
-  prerelease: { mod: "prerelease", client: true, credentials: true },
+  prerelease: { mod: "prerelease", client: true, credentials: true, writes: true },
 };
 
 // Commands available for `--store google` (Google Play). Same names as the Apple ones, different backend
@@ -25,8 +43,8 @@ export const PLAY_COMMANDS = {
   inspect: { mod: "inspect" },
   preflight: { mod: "preflight" },
   diff: { mod: "diff" },
-  fill: { mod: "fill" },
-  prerelease: { mod: "prerelease" },
+  fill: { mod: "fill", writes: true },
+  prerelease: { mod: "prerelease", writes: true },
 };
 
 // Full public command surface (the module-dispatched ones above + the three handled inline in bin/).

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

package/src/upload.mjs

@@ -2,7 +2,9 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 
-const md5 = (buf) => crypto.createHash("md5").update(buf).digest("hex");
+// Exported because `diff` compares against it: the checksum committed here is the only thing that lets
+// a local file be compared to what Apple actually holds, rather than to how MANY things it holds.
+export const md5 = (buf) => crypto.createHash("md5").update(buf).digest("hex");
 
 // Native ASC asset upload (what spaceship does internally): reserve the asset (returns pre-signed
 // uploadOperations) -> PUT each chunk -> commit with uploaded:true + the MD5 checksum.
@@ -33,6 +35,9 @@ export async function uploadAsset(client, { type, setType, setId, filePath }) {
 
 // Previews process asynchronously — poll until Apple exposes videoUrl, then set the poster frame.
 export async function setPreviewPoster(client, previewId, frameTimeCode, { tries = 30, delayMs = 15000 } = {}) {
+  // In a dry run the preview was never created, so `previewId` is a synthetic `dry-run-<n>` and this would
+  // poll a 404 for seven and a half minutes before giving up.
+  if (client.dryRun) return true;
   for (let i = 0; i < tries; i++) {
     const { json } = await client.get(`/v1/appPreviews/${previewId}`);
     if (json.data?.attributes?.videoUrl) {