vydanne 0.11.0 → 0.12.0

package/README.md

@@ -229,13 +229,15 @@ already right. `VYDANNE_FLATTEN=1` reads a flat screenshot folder rather than pe
 
 | Command | In plain English |
 |---|---|
-| `preflight` | **Run this first.** Checks the listing is complete, nothing is over a character limit, no locale mentions the other app store — and that the screenshots on the store are your *current* ones, not a stale set. It also asserts the fields no local file drives and that no diff can therefore see: copyright, the App Review contact, the age rating, the primary category and the content-rights declaration. Those are each set by their own command, so a listing that never ran one had them EMPTY while this printed green. Green means submittable. |
+| `preflight` | **Run this first.** Checks the listing is complete, nothing is over a character limit, no locale mentions the other app store — and that the screenshots on the store are your *current* ones, not a stale set. It also asserts the fields no local file drives and that no diff can therefore see: copyright, the App Review contact, the age rating, the primary category and the content-rights declaration. Those are each set by their own command, so a listing that never ran one had them EMPTY while this printed green. Green means submittable. Also refuses a **blank screenshot** — a file with almost no distinct colours in the middle of the frame, i.e. one where the app drew nothing. |
 | `prepare` | Starts the next release: creates the App Store version you're preparing and attaches your newest build to it. **Needed before `fill` on an app that already has a version on sale** — until a draft exists there is nothing for the listing text to go into. Reuses the draft if it's already there, so it's safe to re-run. It does *not* submit. |
 | `push` | **The whole release, one command**: runs `prepare` → `fill` → `previews` → `age-rating` → `review-contact` → `accessibility` → `preflight`, in that order, stopping at the first failure. Dry run without `--apply`, like everything else. Ends at a green preflight — it never submits. |
 | `diff` | Shows exactly what's different between your files and what's live. Nothing is changed — a safe preview. |
 | `fill` | Uploads your listing text and screenshots. Handles iPhone, iPad and Mac. Refuses to upload text that names the other mobile platform. |
 | `previews` | Uploads App Preview videos. |
 | `inspect` | Shows the app's current state in the store. Read-only. With `--store google` it also lists every track carrying a release — track, versionCode, version name, status, and the rollout percentage of a staged release. |
+| `releases` | Every version this app has ever had, with the build each one shipped, the commit that build number resolves to, and whether that commit is tagged. Read-only. `inspect` cannot answer this — it reports the version in preparation or the live one and nothing behind them. With `--store google` it reports what each track is serving; Play keeps no history of superseded releases, so tag as you release. |
+| `withdraw` | Takes a version back **out of** App Store review so it can be edited — the step `prepare` and `prerelease` both tell you to do by hand. Refuses a **live** version, exactly as `prerelease --store google` refuses the production track: it retrieves what is waiting and never touches what customers have. Undoes a submission; never makes one. Dry run without `--apply`. |
 | `locales` | Lists your languages and Apple's code for each — and warns about any language the App Store doesn't offer. |
 | `appinfo` | Sets the App Store **category** and the **content-rights** answer — the two app-level facts that block *Add for Review* and belong to no single release. Declared as `categories` (Apple's ids: `GAMES`, `GAMES_PUZZLE` — never display names) and `contentRights: false` for an app that shows no third-party content. Left undeclared, `contentRights` is not written at all, so an answer already given in App Store Connect is never overwritten by a default nobody chose. |
 | `age-rating` | Sets the age rating. `rating: "4+"` needs nothing else; any higher rating is described feature-by-feature in `ageRating` and Apple computes the band from it. |

package/SKILL.md

@@ -214,7 +214,7 @@ who it's for → honest close. Keep it scannable; lead each bullet with the payo
 live) · `privacy` (prints answers for the UI — the API can't reach Apple's iris host) · `iap` (validate +
 RGB flatten) · `compliance` (US self-classification PDF) · `bridge` (zdymak's output → the folders
 `fill` reads) · `diff` (what differs vs live, text AND media by checksum) · `preflight`
-(completeness gate + cross-store lint + stale-screenshot check) · `inspect` · `auth` (what credentials
+(completeness gate + cross-store lint + stale-screenshot check) · `inspect` · `releases` · `auth` (what credentials
 resolved, and from where) · `locales` · `version`.
 
 **`bridge` maps by DIRECTORY, not by target.** zdymak writes each shot to `<dir || target>`, so a
@@ -302,10 +302,92 @@ name, status, and a staged rollout's percentage — for every track that carries
 with no release are omitted. That is the question after any upload, and it could not be answered
 from this tool at all before 0.11.
 
-`--store google` routes `inspect` · `diff` · `preflight` · `fill` · `prerelease` to the Play Developer **Edits** API
+## `releases` — what shipped, and from which commit
+
+`inspect` reports the version in preparation or the one live now. It structurally cannot show the
+ones behind them, and that gap has already cost: three of Niva's release tags carry messages saying
+they could not be confirmed *"because historical build numbers are not exposed by vydanne inspect"*,
+and all three were wrong — by 9, 3 and 23 commits. They had been tagged at the commits that bumped
+`MARKETING_VERSION`, which is the intuitive place and the wrong one, because the build is archived
+days later. The data was always one query away: `appStoreVersions?include=build`.
+
+`releases` is that query plus the two columns that make it useful — the **commit** each build number
+names and whether it carries a **tag**. Both stores in this portfolio derive the build number from
+`git rev-list --count HEAD` (Android's `versionCode`, iOS's `CURRENT_PROJECT_VERSION` via
+`Scripts/build-number.sh`), which makes it reversible.
+
+**Every mapping is verified, never assumed.** `rev-list --reverse` is ordered, not counted, so on a
+merged history the Nth line need not be the commit with N ancestors — the candidate's own count has
+to match. An app that does not build this way, or a build number that is not a commit count, gets a
+stated reason instead of a confident wrong answer. That check has already caught a real one: a build
+numbered `1` sitting above a `131`, which is a `getOrDefault(1)` fallback firing when the git count
+failed at archive time. That binary cannot be traced to a commit at all.
+
+Only what is **serving users** is nagged about — `READY_FOR_SALE`, and the `production` track. A
+version in review has not shipped, and this portfolio pushes to `alpha` before every promotion, so
+tagging either would make the tag mean nothing.
+
+With `--store google` it reports what each track carries now. **Play keeps no history**: there is no
+endpoint for superseded production releases, so a game that pushed several under one version name
+has no record of the earlier ones. Uploaded bundles are listed for context and must never be tagged
+from — uploaded is not released. Tag as you release.
+
+`--store google` routes `inspect` · `releases` · `diff` · `preflight` · `fill` · `prerelease` to the Play Developer **Edits** API
 (OAuth2 service account; **scoped to the config's `packageName`** — a shared key can't touch another app).
 The AAB binary and the (YouTube-URL) promo video stay outside vydanne.
 
+## Blank screenshots — the check that had to exist
+
+Palon uploaded a device frame containing pure white and an iOS status bar to a version that reached
+App Store review, and every existing gate passed it. Presence: the file is there. Naming: it is
+named right. Freshness: it matches the store exactly. A blank file satisfies all three, and the
+chain around it is built to be faithful — zdymak photographs whatever the app draws and reports
+success, `bridge` copies what it is handed, `fill` uploads it. Nothing was looking at the pixels.
+
+`preflight` now measures distinct colours in the middle of each local screenshot, where a device
+frame's screen sits. Whole-frame colour counts do not separate — a caption band and its gradient
+contribute thousands of their own — but over the centre the failure scored **28** against
+**1500–6800** for real screens, with the quietest genuine screenshot in the portfolio at 270. The
+threshold sits 4x clear of both, so it is a fault detector rather than an opinion about how busy a
+screenshot should be.
+
+It found a second one on its first run, in a game that has not shipped yet.
+
+**It is a backstop, not a proof, and the limit is structural.** A composed screenshot's measurement
+depends on its composition: this crop works where the device is full-bleed and the middle of the
+image is the screen, which is what every app here produces, but a layout that insets the device on a
+generous background puts gradient in the crop — zdymak's own demo composition scores 204 on a frame
+whose screen is pure white. No tighter crop fixes it: at one tight enough to exclude background the
+blanks land on 8–10 and the quietest genuine screenshot lands on 9.
+
+The reliable gate is upstream. `zdymak` measures the **capture**, which has no frame, background or
+caption and separates with no crop at all — under 400 distinct colours *and* over 95% one colour.
+This check exists because vydanne is the last thing before the store and sees screenshots that never
+came from zdymak.
+
+## `withdraw` — the step that was a web form
+
+A version sits in `WAITING_FOR_REVIEW` with something wrong in it — a blank screenshot, a build
+numbered by a fallback — and every command that could fix it refuses, correctly, because Apple locks
+a submitted version. `prepare` said *"withdraw it in App Store Connect, then re-run this"*.
+`prerelease` said *"re-pointing it would mean withdrawing that submission, which is your call."*
+Three files said the same thing and none of them could do it.
+
+**It is the mirror of Play's production refusal, not a new kind of power.** `prerelease --store
+google` refuses the `production` track outright because *"that release is a human's to make"*. This
+is the same rule pointed the other way: it takes back what is **waiting** and will not touch what
+customers have — a `READY_FOR_SALE` version is refused flatly. And it stays on the safe side of the
+line vydanne draws everywhere: it UNDOES a submission and never makes one. Submitting stays manual.
+
+Withdrawing is not free, so the states are enumerated rather than filtered. `WAITING_FOR_REVIEW`
+costs a place in the queue and nothing else. `IN_REVIEW` discards a review already in progress and
+is announced as such. `PENDING_DEVELOPER_RELEASE` is refused — that version is *approved and waiting
+on you*, and throwing that away to change a screenshot is almost never what anyone means.
+
+It waits for the version to actually leave review before returning. Apple passes through
+`CANCELING` first, and a command that returned there would send you straight into a `fill` that
+fails on a still-locked version.
+
 ## `--apply` — writes are opt-in
 
 **Every store-mutating command is a DRY RUN without `--apply`**: `prepare` · `push` · `fill` ·

package/bin/vydanne.mjs

@@ -142,6 +142,10 @@ usage: vydanne <command> [--apply] [--config vydanne.config.mjs]
   bridge          map zdymak's store-assets output onto the folders \`fill\` reads (locale codes,
                   device prefixes, Play paths). Local files only; --dry-run previews.
   inspect         read-only ASC state
+  releases        every version ever shipped, with the build and the commit it came from —
+                  and whether that commit is tagged. --store google: what each track serves
+✎ withdraw        take a version back OUT of App Store review so it can be fixed. Refuses a
+                  LIVE version, the way --store google refuses the production track
   diff            show what differs between local (metadata/screenshots/previews) and ASC
   preflight       verify submission-completeness (the gotcha checker)
 ✎ prerelease      upload the build for testers — .ipa to TestFlight (internal groups only),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vydanne",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "App Store Connect + Google Play submission prep — the companion to zdymak (media). Native Node (no fastlane/Ruby/Python): localized listings, screenshot/preview/icon upload, ratings, review contact, accessibility & privacy labels, IAP, export docs, build upload to TestFlight / a Play closed track, a diff of local-vs-store, and a preflight verifier that encodes the store gotchas. Never submits for review. iOS/macOS via the ASC REST API; Android via the Play Developer Edits API (--store google).",
   "keywords": [
     "app-store-connect",

package/src/blankShot.mjs

@@ -0,0 +1,165 @@
+import fs from "node:fs";
+import zlib from "node:zlib";
+
+/**
+ * **Is this store screenshot a picture of nothing?**
+ *
+ * Palon shipped one. `store-assets/appstore-iphone-6.9/05-buildinglight.png` is a device frame
+ * containing pure white and an iOS status bar — no board, no header, no queue — and it was uploaded
+ * to a version that reached App Store review. Nothing in the chain could have noticed: zdymak
+ * photographs whatever the app draws and reports success, the asset bridge copies what it is
+ * handed, `fill` uploads it, and `preflight`'s existing checks are about presence, naming and
+ * freshness, all of which a blank file passes perfectly.
+ *
+ * The one screenshot that broke was the only one in the set shot in the LIGHT palette — the least
+ * trodden path in the capture, photographed once a release and looked at by nobody afterwards.
+ *
+ * ### It measures the CENTRE, and that is what makes the number mean something
+ *
+ * Measured across Palon's four asset sets, distinct colours over the whole frame do not separate:
+ * the caption band and its gradient contribute thousands of their own, so the blank frame scored
+ * 1821 against 7283 for a good one — a real gap, but one that depends entirely on how much
+ * decoration a game's frame happens to carry. Over the middle of the image, where the device screen
+ * sits, the same files score **28 against 3256–6811**. The quietest genuine screenshot in the
+ * portfolio (Palon's Android `fresh`, a nearly empty opening board) scores 408.
+ *
+ * Those are full-pixel counts over the crop; the implementation samples every second pixel, which
+ * scales them down but not the separation. See [BLANK_BELOW] for the figures the threshold is
+ * actually set from.
+ *
+ * ### It is a BACKSTOP, and the limit is worth stating rather than discovering
+ *
+ * A composed screenshot is a device frame on a background under a caption, so any measurement of it
+ * depends on the composition. This crop works for the frames every app in this portfolio produces,
+ * where the device is full-bleed and the middle of the image IS the screen. On a layout that insets
+ * the device on a generous background, the same crop catches gradient instead: zdymak's own demo
+ * composition scores 204 on a frame whose screen is pure white, and would pass here.
+ *
+ * There is no crop that fixes it. Measured across the portfolio, at a crop tight enough to exclude
+ * background the blanks land on 8, 9 and 10 — and the quietest genuine screenshot lands on 9.
+ *
+ * The reliable gate is upstream: `zdymak` measures the CAPTURE, which has no frame, background or
+ * caption, and separates unambiguously with no crop at all. This one exists because vydanne is the
+ * last thing before the store and sees screenshots that never came from zdymak. It catches the
+ * failure that actually shipped; it is not a proof that a listing has no blank in it.
+ *
+ * ### PNG only, and decoded here rather than by a dependency
+ *
+ * vydanne has no image dependency and should not grow one for this. PNG is enough — every
+ * screenshot in the portfolio is one — and anything else is reported as unchecked rather than
+ * guessed at, because a false "blank" on a release would be worse than the gap it closes.
+ */
+
+/** Distinct colours in the middle of a PNG, or null when the file cannot be read as one. */
+export function centreColours(file) {
+  let png;
+  try {
+    png = decodePng(fs.readFileSync(file));
+  } catch {
+    return null;
+  }
+  if (!png) return null;
+  const { width, height, pixels } = png;
+  const x0 = Math.floor(width * 0.2);
+  const x1 = Math.floor(width * 0.8);
+  const y0 = Math.floor(height * 0.25);
+  const y1 = Math.floor(height * 0.85);
+  const seen = new Set();
+  // Every 2nd pixel on both axes. Sampling matters more than it looks: at every 4th, the quietest
+  // real screenshot in the portfolio (a nearly empty opening board) fell from 408 distinct colours
+  // to 126 and would have been reported as blank, while the genuinely blank one stayed at 28
+  // whatever the step. A false "blank" on a release would be worse than the gap this closes.
+  for (let y = y0; y < y1; y += 2) {
+    for (let x = x0; x < x1; x += 2) {
+      const i = (y * width + x) * 4;
+      seen.add((pixels[i] << 16) | (pixels[i + 1] << 8) | pixels[i + 2]);
+      // Enough to pass; stop counting. The exact figure only matters below the threshold.
+      if (seen.size > BLANK_BELOW) return seen.size;
+    }
+  }
+  return seen.size;
+}
+
+/**
+ * Fewer distinct colours than this in the centre and the screen drew nothing.
+ *
+ * Measured at the sampling above: the blank screenshot scores **28**, the quietest genuine one in
+ * the portfolio **270**, and a normal one 1500–6800. This sits 4x clear of both, which is the point
+ * — near either edge it would be a taste threshold rather than a fault detector.
+ */
+export const BLANK_BELOW = 120;
+
+/**
+ * Minimal PNG reader: IHDR + IDAT, 8-bit RGB/RGBA, non-interlaced. Returns null for anything else,
+ * which the caller reports as unchecked. Enough for every screenshot any of these pipelines make.
+ */
+function decodePng(buf) {
+  if (buf.readUInt32BE(0) !== 0x89504e47) return null;
+  let pos = 8;
+  let width = 0;
+  let height = 0;
+  let colourType = -1;
+  let bitDepth = 0;
+  const idat = [];
+  while (pos < buf.length) {
+    const len = buf.readUInt32BE(pos);
+    const type = buf.toString("ascii", pos + 4, pos + 8);
+    const data = buf.subarray(pos + 8, pos + 8 + len);
+    if (type === "IHDR") {
+      width = data.readUInt32BE(0);
+      height = data.readUInt32BE(4);
+      bitDepth = data[8];
+      colourType = data[9];
+      if (data[12] !== 0) return null; // interlaced
+    } else if (type === "IDAT") {
+      idat.push(data);
+    } else if (type === "IEND") {
+      break;
+    }
+    pos += 12 + len;
+  }
+  if (bitDepth !== 8 || (colourType !== 2 && colourType !== 6)) return null;
+  const channels = colourType === 6 ? 4 : 3;
+  const raw = zlib.inflateSync(Buffer.concat(idat));
+  const stride = width * channels;
+  const out = Buffer.alloc(width * height * 4);
+  let prev = Buffer.alloc(stride);
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (stride + 1)];
+    const line = Buffer.from(raw.subarray(y * (stride + 1) + 1, y * (stride + 1) + 1 + stride));
+    unfilter(filter, line, prev, channels);
+    for (let x = 0; x < width; x++) {
+      const s = x * channels;
+      const d = (y * width + x) * 4;
+      out[d] = line[s];
+      out[d + 1] = line[s + 1];
+      out[d + 2] = line[s + 2];
+      out[d + 3] = channels === 4 ? line[s + 3] : 255;
+    }
+    prev = line;
+  }
+  return { width, height, pixels: out };
+}
+
+/** The five PNG line filters, in place. */
+function unfilter(filter, line, prev, bpp) {
+  for (let i = 0; i < line.length; i++) {
+    const a = i >= bpp ? line[i - bpp] : 0;
+    const b = prev[i];
+    const c = i >= bpp ? prev[i - bpp] : 0;
+    switch (filter) {
+      case 1: line[i] = (line[i] + a) & 0xff; break;
+      case 2: line[i] = (line[i] + b) & 0xff; break;
+      case 3: line[i] = (line[i] + ((a + b) >> 1)) & 0xff; break;
+      case 4: {
+        const p = a + b - c;
+        const pa = Math.abs(p - a);
+        const pb = Math.abs(p - b);
+        const pc = Math.abs(p - c);
+        line[i] = (line[i] + (pa <= pb && pa <= pc ? a : pb <= pc ? b : c)) & 0xff;
+        break;
+      }
+      default: break;
+    }
+  }
+}

package/src/buildCommit.mjs

@@ -0,0 +1,105 @@
+import { execFileSync } from "node:child_process";
+
+/**
+ * **Which commit a shipped build number names** — for repos whose build number is a commit count.
+ *
+ * That is the convention across the kupalinka portfolio: Android's `versionCode` comes from
+ * `git rev-list --count HEAD` in `composeApp/build.gradle.kts`, and iOS's `CURRENT_PROJECT_VERSION`
+ * from a `Scripts/build-number.sh` that runs the same command. It makes a store's build number a
+ * REVERSIBLE fact, which is the only reason a release tag is worth anything: symbolicating a crash
+ * or reproducing a store binary needs the tree the archive was cut from, and a version string does
+ * not identify one.
+ *
+ * ### Nothing here assumes the convention holds — it VERIFIES it, per build
+ *
+ * vydanne is pointed at apps that do not build this way, so a mapping that trusted the convention
+ * would confidently name the wrong commit for them. Every answer below is checked
+ * (`rev-list --count` on the candidate must equal the build number) and an unverifiable one comes
+ * back as a stated reason rather than a guess.
+ *
+ * The check is not ceremony even where the convention does hold. `rev-list --reverse` is ORDERED,
+ * not counted: on a history with merges the Nth line is not necessarily the commit with N
+ * ancestors, so indexing alone is right only by luck on a linear repo.
+ *
+ * It has already caught a real one — a build numbered `1` sitting in App Store Connect above a 131,
+ * which is a `getOrDefault(1)` fallback firing when the git count failed at archive time. That
+ * binary is not traceable to a commit by any means, and the honest output is to say so.
+ */
+
+function git(args) {
+  return execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+}
+
+/**
+ * The repo's commits oldest-first, or null when this is not a git checkout.
+ *
+ * Read once and passed around: resolving each build separately would re-walk the whole history per
+ * version, and a listing command should not cost more than the API call it is annotating.
+ */
+export function commitOrder() {
+  try {
+    return git(["rev-list", "--reverse", "HEAD"]).split("\n").filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+/** Every tag pointing at [sha], dereferenced so annotated tags are found too. */
+export function tagsAt(sha) {
+  try {
+    return git(["tag", "--points-at", sha]).split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve one build number.
+ *
+ * Returns `{ sha }` when the count checks out, or `{ why }` naming what stopped it — which is the
+ * useful half. "This build has no commit" is a finding about the release, not a gap in the tool.
+ */
+export function commitForBuild(order, build) {
+  const n = Number(build);
+  if (!order) return { why: "not a git checkout" };
+  if (!Number.isInteger(n) || n < 1) return { why: `build "${build}" is not a number` };
+  if (n > order.length) {
+    return { why: `build ${n} is past HEAD (${order.length} commits) — built elsewhere, or on an unmerged branch` };
+  }
+  const sha = order[n - 1];
+  let count;
+  try {
+    count = Number(git(["rev-list", "--count", sha]));
+  } catch {
+    return { why: "git rev-list failed" };
+  }
+  if (count !== n) {
+    return { why: `commit ${sha.slice(0, 9)} has ${count} ancestors, not ${n} — build number is not a commit count here` };
+  }
+  return { sha };
+}
+
+/**
+ * **A build number that did not grow is not a commit count**, whatever `rev-list` says about it.
+ *
+ * This exists because the count check alone is not enough, and the hole is not hypothetical: Vodar's
+ * pending 1.2 is attached to a build numbered `1`, sitting in App Store Connect above a 131. One
+ * genuinely IS the ancestor count of the repo's first commit, so [commitForBuild] verified it and
+ * cheerfully named a commit from the week the project started — a confident, wrong answer of exactly
+ * the kind this module exists to refuse.
+ *
+ * A commit count only ever grows, so a build that is not greater than one already shipped cannot be
+ * one. In practice it is a fallback firing when git was unavailable at archive time — `getOrDefault(1)`
+ * in the gradle file, or the same default in `Scripts/build-number.sh` — and the binary it names
+ * cannot be traced to a tree by any means.
+ *
+ * Flagging is the safe direction. Two releases whose builds were uploaded out of order would be
+ * reported as suspect and are worth a look anyway; a silently wrong commit is not.
+ */
+export function outOfSequence(build, priorMax) {
+  const n = Number(build);
+  if (priorMax == null || !Number.isInteger(n)) return null;
+  if (n > priorMax) return null;
+  return `build ${n} is not above ${priorMax} from an earlier release — a commit count only grows, ` +
+    "so this is a build-number fallback and the binary is not traceable to a commit";
+}

package/src/commands/preflight.mjs

@@ -1,6 +1,8 @@
 import { green, red, yellow, LIMITS, VERSION_FIELDS } from "../util.mjs";
 import { reportCrossStore } from "../crossStore.mjs";
-import { localScreenshots, remoteScreenshots, compareShots, localScreenshotLocales, unknownScreenshotDirs } from "../screenshots.mjs";
+import path from "node:path";
+import { localScreenshots, remoteScreenshots, compareShots, localScreenshotLocales, unknownScreenshotDirs, screenshotBase } from "../screenshots.mjs";
+import { centreColours, BLANK_BELOW } from "../blankShot.mjs";
 
 // Verify a listing is submission-complete the CORRECT way — each localization read by id (not the sparse
 // list), char limits, primary-locale coverage, per-platform — and warn on the gotchas before ASC does.
@@ -111,13 +113,33 @@ export async function run(config, client) {
       const count = Object.values(remote).reduce((n, m) => n + m.size, 0);
       // Only the primary listing MUST have screenshots — Apple falls back to it for any locale without.
       if (!count && code === config.primaryLocale) problems.push(`${platform}/${code}: no screenshots`);
+
       // Freshness is judged only where a local set exists: no local screenshots means there is nothing
       // to compare against, not that the store's are wrong. A display type the store has and local
       // lacks is likewise left alone — `fill` never deletes by omission, so this does not flag it.
       for (const [dt, L] of Object.entries(localScreenshots(platform, code, config))) {
+        const slot = dt.replace("APP_", "");
+
+        // IS THERE A SCREEN IN THE SCREENSHOT? Every other check here is about presence, naming and
+        // freshness, and a blank file passes all three perfectly — which is how Palon uploaded a
+        // device frame containing pure white and an iOS status bar to a version that reached App
+        // Store review. zdymak photographs whatever the app draws and reports success, the bridge
+        // copies what it is handed, `fill` uploads it. This is the only place in the chain that
+        // looks at the pixels. It runs before the comparison below on purpose: a blank file that
+        // matches the store is worse news than one that does not.
+        for (const name of L.keys()) {
+          const colours = centreColours(path.join(screenshotBase(platform, config), code, name));
+          if (colours !== null && colours < BLANK_BELOW) {
+            problems.push(
+              `${platform}/${code}: screenshot ${slot}/${name} is BLANK — ${colours} distinct ` +
+              "colours in the middle of the frame, so the app drew nothing. Re-capture it; " +
+              "uploading this ships a white rectangle to the store.",
+            );
+          }
+        }
+
         const c = compareShots(L, remote[dt] || new Map());
         if (!c) continue;
-        const slot = dt.replace("APP_", "");
         if (c.kind === "count") problems.push(`${platform}/${code}: screenshots ${slot} local ${c.local} / remote ${c.remote} — the store set is not the local one (\`fill\`, VYDANNE_REPLACE=1 to replace)`);
         else if (c.kind === "renamed") problems.push(`${platform}/${code}: screenshots ${slot} ${c.names.length} local file(s) not on the store by name (\`fill\`, VYDANNE_REPLACE=1 to replace)`);
         else if (c.kind === "stale") problems.push(`${platform}/${code}: screenshots ${slot} STALE — ${c.names.length} of ${c.of} differ in content; green would ship the old art (\`fill\`, VYDANNE_REPLACE=1 to replace)`);

package/src/commands/prerelease.mjs

@@ -68,6 +68,50 @@ async function altool(args, credentials) {
   return run_("xcrun", full, { maxBuffer: 32 * 1024 * 1024 });
 }
 
+/**
+ * **The highest build number this app has, which is not the same as the newest.**
+ *
+ * [newestBuild] sorts by upload date, and that is the wrong baseline for a gate: on 2026-09-04
+ * Vodar's newest upload WAS the broken one, a build numbered `1` sitting above a `131`, so
+ * comparing against it would have compared 1 with 1 and waved it through. The invariant is about
+ * the maximum, so read the maximum.
+ */
+async function appBuilds(client) {
+  const { json } = await client.get(
+    `/v1/builds?filter[app]=${client.appId}&sort=-uploadedDate&limit=200&fields[builds]=version,processingState`,
+  );
+  let highest = null;
+  const held = new Map();
+  for (const b of json.data || []) {
+    const raw = b.attributes?.version;
+    held.set(String(raw), b);
+    const n = Number(raw);
+    if (Number.isFinite(n) && (highest == null || n > highest)) highest = n;
+  }
+  return { highest, held };
+}
+
+/**
+ * The CFBundleVersion inside the .ipa, read before anything is uploaded.
+ *
+ * The Play side has always read the versionCode out of the bundle before the transfer; Apple's did
+ * not, so the first place a build number became visible was App Store Connect — after the upload,
+ * which is after it is too late. macOS-only tools are fine here: this command already requires
+ * `xcrun altool`.
+ */
+async function ipaBuildNumber(ipa) {
+  try {
+    const { stdout } = await run_(
+      "/bin/sh",
+      ["-c", `unzip -p ${JSON.stringify(ipa)} 'Payload/*.app/Info.plist' | plutil -convert json -o - -`],
+      { maxBuffer: 32 * 1024 * 1024 },
+    );
+    return JSON.parse(stdout).CFBundleVersion ?? null;
+  } catch {
+    return null;
+  }
+}
+
 /** The newest build Apple has for this app, if any. */
 async function newestBuild(client) {
   const { json } = await client.get(
@@ -99,9 +143,43 @@ export async function run(config, client, credentials) {
   console.log(green("prerelease → App Store Connect (TestFlight)"));
   console.log(`  archive: ${path.relative(process.cwd(), ipa) || ipa}  (${size} MB)`);
 
+  // THE BUILD NUMBER GATE. Read from the archive, checked before the transfer.
+  //
+  // Apple does not enforce this: CFBundleVersion only has to be unique within a marketing version,
+  // so a build numbered `1` uploaded above a `131` is accepted in silence. That happened on
+  // 2026-09-04 — a build-number fallback fired when git was unavailable at archive time, nothing
+  // failed anywhere, and the result is a binary that cannot be traced to a commit, tagged, or
+  // symbolicated. Google refuses the equivalent upload outright; this is the missing half.
+  //
+  // Refusing costs a re-archive. Accepting costs a permanently untraceable release.
+  const declared = await ipaBuildNumber(ipa);
+  const { highest, held } = await appBuilds(client);
+  // Already on the app? Then this is not a new upload, it is the second half of one — the archive
+  // went up earlier and the version it was meant for was locked in review at the time. That is the
+  // exact shape `withdraw` creates, and re-uploading is both impossible (Apple refuses a repeated
+  // build number) and unnecessary. Skip to attaching it.
+  const alreadyUp = declared != null && held.has(String(declared));
+  if (declared == null) {
+    console.log(yellow("  build ?  — could not read CFBundleVersion from the archive; not gated"));
+  } else {
+    console.log(`  build ${declared} (CFBundleVersion, read from the archive)`);
+    if (alreadyUp) {
+      console.log(green("  already uploaded — skipping the transfer, attaching it below"));
+    } else if (highest != null && Number(declared) <= highest) {
+      // Not above the highest, and not one Apple holds: the number went BACKWARDS. That is a
+      // build-number fallback firing, not a re-run, and the two are worth telling apart — the
+      // first version of this gate refused both and made the legitimate case impossible.
+      console.error(red(`  refusing: build ${declared} is not above ${highest}, which this app already has.`));
+      console.error("  A build number that did not grow is almost always a fallback firing — check that");
+      console.error("  the archive was made where git works, or pass BUILD_NUMBER=<n> deliberately.");
+      console.error("  Apple would accept this upload; it is not recoverable afterwards.");
+      return false;
+    }
+  }
+
   // Validate before uploading. A rejected upload has already cost the transfer; altool's validation
   // catches the common refusals (entitlements, missing icons, bad version) in seconds.
-  try {
+  if (!alreadyUp) try {
     await altool(["--validate-app", "-f", ipa, "-t", "ios"], credentials);
     console.log(green("  validated"));
   } catch (e) {
@@ -113,12 +191,16 @@ export async function run(config, client, credentials) {
   // The binary upload is the one mutation that does NOT go through the ASC client, so the client-level
   // dry-run gate cannot see it — it has to be refused here, or a dry run would ship a build to TestFlight.
   // Validation above has already run, which is the useful half: exactly Play's "validate, then discard".
-  if (client.dryRun) {
+  //
+  // Only when there IS an upload, though. With the build already on the app the rest of this command
+  // is ordinary client calls, which the client's own dry run already plans and withholds — returning
+  // here would hide the re-point that is the entire remaining point of the run.
+  if (client.dryRun && !alreadyUp) {
     console.log(yellow("  DRY RUN — archive validated, NOT uploaded. Re-run with --apply to send it to TestFlight."));
     return true;
   }
 
-  try {
+  if (!alreadyUp) try {
     await altool(["--upload-app", "-f", ipa, "-t", "ios"], credentials);
     console.log(green("  uploaded"));
   } catch (e) {
@@ -135,7 +217,7 @@ export async function run(config, client, credentials) {
     return false;
   }
 
-  const build = await waitForProcessing(client, before);
+  const build = alreadyUp ? held.get(String(declared)) : await waitForProcessing(client, before);
   if (!build) {
     console.log(yellow("  build not visible yet — Apple is still ingesting it."));
     console.log("  It will appear in TestFlight shortly; nothing further is needed here.");

package/src/commands/releases.mjs

@@ -0,0 +1,106 @@
+import { commitOrder, commitForBuild, outOfSequence, tagsAt } from "../buildCommit.mjs";
+import { green, yellow } from "../util.mjs";
+
+/**
+ * **Every version this app has ever had on the App Store, with the build each one shipped.**
+ *
+ * `inspect` cannot answer this and never could: it reports the version in preparation, or the live
+ * one, and nothing behind them. That gap has a cost on the record — three of Niva's release tags
+ * carry messages saying so in their own words, *"Not confirmed against App Store Connect:
+ * historical build numbers are not exposed by vydanne inspect"* — and all three turned out to be
+ * wrong, by 9, 3 and 23 commits. They had been tagged at the commits that bumped
+ * `MARKETING_VERSION`, which is the intuitive place and the wrong one, because the build is archived
+ * days later.
+ *
+ * The history was never actually unavailable. `inspect` just does not ask for it:
+ * `appStoreVersions?include=build` returns every version with the build attached to it. This command
+ * is that one request, plus the two columns that make it actionable.
+ *
+ * ### Read-only, and the reason it is a command rather than a note
+ *
+ * Tagging a release is the one job here that has to be right months later and cannot be checked by
+ * looking. A wrong tag is not a wrong label — it silently sends whoever is chasing a crash report to
+ * a tree that never shipped, and nothing about it looks wrong.
+ */
+export async function run(config, client) {
+  await client.findApp(config.bundleId);
+  console.log(`APP ${client.app.attributes.name} (${config.bundleId})  id=${client.appId}`);
+
+  const r = await client.get(`/v1/apps/${client.appId}/appStoreVersions?include=build&limit=200`);
+  if (r.status >= 300) {
+    console.log(yellow(`  could not read versions — HTTP ${r.status}`));
+    return false;
+  }
+  const builds = Object.fromEntries(
+    (r.json.included || []).filter((i) => i.type === "builds").map((b) => [b.id, b.attributes.version]),
+  );
+  const versions = (r.json.data || []).filter((v) => config.platforms.includes(v.attributes.platform));
+  if (!versions.length) {
+    console.log("  no versions on this app");
+    return true;
+  }
+
+  const order = commitOrder();
+  if (!order) console.log(yellow("  not a git checkout — commit and tag columns unavailable"));
+
+  // Newest first: the question is almost always about the last one or two.
+  versions.sort((a, b) => String(b.attributes.createdDate).localeCompare(String(a.attributes.createdDate)));
+
+  // The highest build seen among versions OLDER than each row, so a build that went backwards can be
+  // recognised. Computed oldest-first, then the table prints newest-first.
+  const priorMax = new Map();
+  let running = null;
+  for (const v of [...versions].reverse()) {
+    priorMax.set(v.id, running);
+    const b = Number(builds[v.relationships?.build?.data?.id]);
+    if (Number.isInteger(b)) running = running == null ? b : Math.max(running, b);
+  }
+
+  console.log(`  ${"version".padEnd(9)}${"state".padEnd(23)}${"date".padEnd(12)}${"build".padEnd(7)}${"commit".padEnd(11)}tag`);
+  const untagged = [];
+  for (const v of versions) {
+    const a = v.attributes;
+    const build = builds[v.relationships?.build?.data?.id];
+    const shipped = a.appStoreState === "READY_FOR_SALE";
+    let commit = "-";
+    let tag = "-";
+    let note = "";
+    const backwards = build == null ? null : outOfSequence(build, priorMax.get(v.id));
+    if (build == null) {
+      note = "no build attached yet";
+    } else if (backwards) {
+      note = yellow(backwards);
+    } else {
+      const got = commitForBuild(order, build);
+      if (got.sha) {
+        commit = got.sha.slice(0, 9);
+        const tags = tagsAt(got.sha);
+        tag = tags.length ? tags.join(" ") : yellow("(untagged)");
+        // Only a version actually on sale earns a nag. One in review has not shipped, and a tag
+        // saying it has is worse than no tag — tag it when it goes live.
+        if (!tags.length && shipped) untagged.push([`ios/${a.versionString}+${build}`, got.sha.slice(0, 9)]);
+      } else {
+        note = yellow(got.why);
+      }
+    }
+    // Padded on the PLAIN text, then coloured. `padEnd` counts ANSI escapes as characters, so
+    // colouring first silently shortens every highlighted cell and the columns stop lining up.
+    console.log(
+      `  ${a.versionString.padEnd(9)}${cell(a.appStoreState, 23, shipped ? green : null)}` +
+      `${String(a.createdDate).slice(0, 10).padEnd(12)}${String(build ?? "-").padEnd(7)}` +
+      `${commit.padEnd(11)}${tag}${note ? "  " + note : ""}`,
+    );
+  }
+
+  if (untagged.length) {
+    console.log(`\n  ${untagged.length} shipped version(s) carry no tag:`);
+    for (const [name, sha] of untagged) console.log(`    git tag -a ${name} ${sha} -m "…"`);
+  }
+  return true;
+}
+
+/** Pad to [width] on the plain text, then colour — see the note at the call site. */
+function cell(text, width, colour) {
+  const padded = String(text).padEnd(width);
+  return colour ? colour(String(text)) + padded.slice(String(text).length) : padded;
+}

package/src/commands/withdraw.mjs

@@ -0,0 +1,127 @@
+import { green, yellow, red } from "../util.mjs";
+
+/**
+ * **Take a version back out of App Store review.**
+ *
+ * The gap this fills was a real one, found by hitting it: a version sits in `WAITING_FOR_REVIEW`
+ * with something wrong in it — a blank screenshot, a build numbered by a fallback — and every
+ * command that could fix it refuses, correctly, because Apple locks a submitted version. `prepare`
+ * says *"withdraw it in App Store Connect, then re-run this"*. `prerelease` says *"re-pointing it
+ * would mean withdrawing that submission, which is your call."* Three files said the same thing and
+ * none of them could do it, so the one step between a known defect and its fix was a web form.
+ *
+ * ### It is the mirror of Play's production refusal, not a new kind of power
+ *
+ * `prerelease --store google` refuses the `production` track outright — not behind a flag —
+ * because *"that release is a human's to make"*. This is the same rule pointed the other way: it
+ * will take back something that is **waiting**, and it will not touch what customers already have.
+ * A version in `READY_FOR_SALE` is refused, flatly, the way `production` is.
+ *
+ * And it stays on the safe side of the line vydanne draws everywhere else: this UNDOES a
+ * submission, it never makes one. Submitting for review remains the human's click.
+ *
+ * ### Withdrawing is not free, so the states are enumerated rather than filtered
+ *
+ * `WAITING_FOR_REVIEW` costs a place in the queue and nothing else — the review has not begun.
+ * `IN_REVIEW` costs a review already in progress and starts it over, which is a different decision,
+ * so it is allowed but announced. Everything else is refused with the reason, because a state this
+ * command cannot help with is worth naming: `PENDING_DEVELOPER_RELEASE` is *approved* and waiting
+ * for you, and throwing that away to change a screenshot is almost never what anyone means.
+ */
+
+/** States where a submission exists and taking it back is what the operator meant. */
+const WITHDRAWABLE = {
+  WAITING_FOR_REVIEW: "queued but not yet picked up — withdrawing costs the place in the queue",
+  IN_REVIEW: "ALREADY BEING REVIEWED — withdrawing discards a review in progress and starts over",
+};
+
+/** States where there is nothing to withdraw, each with the reason it is not an error. */
+const NOTHING_TO_DO = {
+  PREPARE_FOR_SUBMISSION: "not submitted — it is already editable",
+  DEVELOPER_REJECTED: "already withdrawn",
+  REJECTED: "already out of review (Apple rejected it)",
+  METADATA_REJECTED: "already out of review (metadata rejected)",
+  INVALID_BINARY: "already out of review (invalid binary)",
+};
+
+export async function run(config, client) {
+  await client.findApp(config.bundleId);
+  console.log(green(`withdraw → ${client.app.attributes.name} (${config.bundleId})`));
+
+  const versions = await client.get(
+    `/v1/apps/${client.appId}/appStoreVersions?limit=10&fields[appStoreVersions]=versionString,appStoreState,platform`,
+  );
+  const mine = (versions.json.data || []).filter((v) => config.platforms.includes(v.attributes.platform));
+  if (!mine.length) {
+    console.log("  no versions on this app");
+    return true;
+  }
+  const version = mine[0];
+  const state = version.attributes.appStoreState;
+  const label = `${version.attributes.versionString} (${state})`;
+
+  // LIVE IS REFUSED, and this is the whole safety of the command. Play's side will not write the
+  // production track; this will not touch the version customers are downloading. Same rule, and
+  // neither is behind a flag.
+  if (state === "READY_FOR_SALE") {
+    console.error(red(`  refusing: ${label} is the version customers have.`));
+    console.error("  This command takes a version out of REVIEW. Removing a live version from sale");
+    console.error("  is a different act with a different blast radius, and it is not this tool's.");
+    return false;
+  }
+  if (NOTHING_TO_DO[state]) {
+    console.log(`  ${label}: ${NOTHING_TO_DO[state]} — nothing to withdraw`);
+    return true;
+  }
+  if (!WITHDRAWABLE[state]) {
+    console.error(red(`  refusing: ${label} is not a state this command can take back.`));
+    console.error("  Withdrawable states are WAITING_FOR_REVIEW and IN_REVIEW. A version that is");
+    console.error("  approved and waiting on you, or mid-processing, is a decision to make in the UI.");
+    return false;
+  }
+
+  // The submission, not the version, is what gets cancelled — a review submission can carry more
+  // than the app version (in-app purchases, for one), and Apple takes the whole thing back at once.
+  const subs = await client.get(`/v1/apps/${client.appId}/reviewSubmissions?limit=10`);
+  const open = (subs.json.data || []).find((s) => WITHDRAWABLE[s.attributes.state]);
+  if (!open) {
+    console.log(yellow(`  ${label} says it is in review, but no open submission was found.`));
+    console.log("  Nothing was changed. This is worth looking at in App Store Connect.");
+    return false;
+  }
+
+  console.log(`  version ${label}`);
+  console.log(`  submission ${open.id}  submitted ${String(open.attributes.submittedDate).slice(0, 19)}`);
+  console.log(yellow(`  ${WITHDRAWABLE[state]}`));
+
+  const r = await client.patch(`/v1/reviewSubmissions/${open.id}`, {
+    data: { type: "reviewSubmissions", id: open.id, attributes: { canceled: true } },
+  });
+  if (r.status >= 300) {
+    console.error(red(`  cancel failed — HTTP ${r.status}: ${JSON.stringify(r.json).slice(0, 300)}`));
+    return false;
+  }
+  // In a dry run the client records the PATCH instead of sending it, so the CLI's own
+  // "N store write(s) withheld" summary stays accurate — an early return here would have reported
+  // zero writes and printed "the store already matches local", which is the opposite of true.
+  if (client.dryRun) {
+    console.log(yellow("  DRY RUN — the submission is untouched. Re-run with --apply to withdraw it."));
+    return true;
+  }
+  console.log(green(`  cancelled — submission is ${r.json.data.attributes.state}`));
+
+  // Apple moves through CANCELING before the version becomes editable, and a command that returned
+  // at "CANCELING" would send the operator straight into a `fill` that fails on a locked version.
+  // Waiting the few seconds is the difference between a command that worked and one that appeared to.
+  for (let i = 0; i < 10; i++) {
+    const v = await client.get(`/v1/appStoreVersions/${version.id}?fields[appStoreVersions]=appStoreState`);
+    const now = v.json.data?.attributes?.appStoreState;
+    if (now && now !== state) {
+      console.log(green(`  version ${version.attributes.versionString} is now ${now} — editable again`));
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 3000));
+  }
+  console.log(yellow("  cancelled, but the version has not left review yet — re-check in a moment."));
+  return true;
+}

package/src/play/commands/inspect.mjs

@@ -48,8 +48,11 @@ export async function run(config, client) {
     for (const t of edited) {
       const res = await client.trackReleases(t.track);
       // 404 is information, not a failure: the app has never shipped to this track. "Does not
-      // exist" and "exists but empty" are different facts and neither earns a row.
-      if (res.status === 404) continue;
+      // exist" and "exists but empty" are different facts and neither earns a row — and 204 is the
+      // second of them, a track that exists and carries nothing, with no body to report. It was
+      // being reported as "could not be read", which put a warning on every app with an empty
+      // `beta` track. Found while writing `releases` against the same endpoint.
+      if (res.status === 404 || res.status === 204) continue;
       if (res.status !== 200) {
         // ANYTHING ELSE MUST NOT BE SWALLOWED. `req` returns a status rather than throwing, so an
         // earlier version of this that caught exceptions caught nothing at all — a 403 produced

package/src/play/commands/releases.mjs

@@ -0,0 +1,133 @@
+import { commitOrder, commitForBuild, tagsAt } from "../../buildCommit.mjs";
+import { green, yellow } from "../../util.mjs";
+
+const LIFECYCLE = {
+  RELEASE_LIFECYCLE_STATE_PUBLISHED: "published",
+  RELEASE_LIFECYCLE_STATE_IN_REVIEW: "in review",
+  RELEASE_LIFECYCLE_STATE_DRAFT: "draft",
+  RELEASE_LIFECYCLE_STATE_HALTED: "halted",
+};
+
+/**
+ * **What each track is serving, resolved to the commit it was built from.**
+ *
+ * The overlap with `inspect --store google` is deliberate and small: that command answers "what
+ * state is this listing in", this one answers "what do I tag". Same source of truth — the non-edit
+ * `tracks/<t>/releases` endpoint, because the edit's own view is the last thing WRITTEN rather than
+ * what is serving — plus the commit and tag columns.
+ *
+ * ### Play cannot give you a history, and pretending otherwise would be the bug
+ *
+ * `tracks/<t>/releases` returns what a track carries NOW. There is no endpoint for superseded
+ * production releases, so a game that pushed several of them under one version name has no record of
+ * the earlier ones — Niva did exactly that, which is why its `marketingVersion` comment exists at
+ * all. `edits.bundles` lists every versionCode ever uploaded and is shown below for that reason, but
+ * uploaded is not released and a tag must never be minted from it.
+ *
+ * So: tag as you release. This command can confirm what is out there today and cannot reconstruct
+ * what was out there last year.
+ *
+ * ### No out-of-sequence check here, and that is Google's doing rather than an omission
+ *
+ * The Apple command needs [outOfSequence] because App Store Connect accepted a build numbered `1`
+ * above a `131` — a build-number fallback firing silently. Play refuses that upload outright:
+ * a versionCode must exceed every code already used for the package, enforced at `edits.bundles`.
+ * The invariant the whole commit mapping rests on is therefore guaranteed on this store and merely
+ * hoped for on the other, which is worth knowing when a build number looks wrong.
+ */
+export async function run(config, client) {
+  const g = config.google;
+  console.log(`PLAY ${g.packageName}`);
+
+  const order = commitOrder();
+  if (!order) console.log(yellow("  not a git checkout — commit and tag columns unavailable"));
+
+  const editId = await client.newEdit();
+  let uploaded = [];
+  const rows = [];
+  // Tracks that could not be read. A command whose job is "what still needs a tag" must never let a
+  // transient failure read as "nothing else to tag" — the releases endpoint is quota-limited ("The
+  // service is currently unavailable", "Listing releases quota exceeded") and a normal day reaches
+  // it, so a missing row is a state to announce rather than one to quietly skip.
+  const unreadable = [];
+  try {
+    const edited = (await client.listTracks(editId)).json.tracks || [];
+    for (const t of edited) {
+      const res = await client.trackReleases(t.track);
+      // 404 = never shipped to this track. 204 = the track exists and carries nothing, with no body
+      // to report. Both are "no rows", not failures; reporting 204 as unreadable put a yellow
+      // warning on every app with an empty `beta` track, which is most of them.
+      if (res.status === 404 || res.status === 204) continue;
+      if (res.status !== 200) {
+        unreadable.push(`${t.track} (${res.json?.error?.message || `HTTP ${res.status}`})`);
+        continue;
+      }
+      for (const rel of res.json.releases || []) {
+        for (const art of rel.activeArtifacts || []) {
+          rows.push({
+            track: t.track,
+            code: art.versionCode,
+            name: rel.releaseName || "-",
+            state: LIFECYCLE[rel.releaseLifecycleState] || rel.releaseLifecycleState || "?",
+          });
+        }
+      }
+    }
+    uploaded = ((await client.req("GET", `/edits/${editId}/bundles`)).json.bundles || [])
+      .map((b) => b.versionCode).sort((a, b) => a - b);
+  } finally {
+    await client.deleteEdit(editId);
+  }
+
+  if (unreadable.length) {
+    console.log(yellow(`  INCOMPLETE — could not read: ${unreadable.join(", ")}`));
+    console.log(yellow("  Re-run before concluding anything is untagged; this is usually a quota blip."));
+  }
+  if (!rows.length) {
+    console.log(unreadable.length ? "  no readable track carries a release" : "  nothing published — no track carries a release");
+  } else {
+    console.log(`  ${"track".padEnd(12)}${"code".padEnd(7)}${"name".padEnd(13)}${"state".padEnd(11)}${"commit".padEnd(11)}tag`);
+    const untagged = [];
+    for (const row of rows) {
+      let commit = "-";
+      let tag = "-";
+      let note = "";
+      const got = commitForBuild(order, row.code);
+      if (got.sha) {
+        commit = got.sha.slice(0, 9);
+        const tags = tagsAt(got.sha);
+        tag = tags.length ? tags.join(" ") : yellow("(untagged)");
+        // Only `production` is a release to users. A closed track is a test, and a tag claiming
+        // otherwise is worse than no tag — this portfolio ships to `alpha` before every promotion,
+        // so nagging about those would nag on every single release.
+        if (!tags.length && row.track === "production" && row.state === "published") {
+          untagged.push([`play/${row.name}+${row.code}`, got.sha.slice(0, 9)]);
+        }
+      } else {
+        note = yellow(got.why);
+      }
+      const live = row.track === "production" && row.state === "published";
+      console.log(
+        `  ${row.track.padEnd(12)}${String(row.code).padEnd(7)}${row.name.padEnd(13)}` +
+        `${cell(row.state, 11, live ? green : null)}${commit.padEnd(11)}${tag}${note ? "  " + note : ""}`,
+      );
+    }
+    if (untagged.length) {
+      console.log(`\n  ${untagged.length} production release(s) carry no tag${unreadable.length ? " (of the tracks that could be read)" : ""}:`);
+      for (const [name, sha] of untagged) console.log(`    git tag -a ${name} ${sha} -m "…"`);
+    }
+  }
+
+  if (uploaded.length) {
+    console.log(`\n  bundles uploaded (${uploaded.length}): ${uploaded.join(", ")}`);
+    console.log("  Uploaded is NOT released — never tag from this line. Superseded production");
+    console.log("  releases are not retrievable from the Play API at all, so tag as you release.");
+  }
+  return true;
+}
+
+/** Pad to [width] on the plain text, then colour — `padEnd` counts ANSI escapes as characters. */
+function cell(text, width, colour) {
+  const padded = String(text).padEnd(width);
+  return colour ? colour(String(text)) + padded.slice(String(text).length) : padded;
+}

package/src/registry.mjs

@@ -31,6 +31,16 @@ export const COMMANDS = {
   // 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 },
+  // Version HISTORY, which `inspect` structurally cannot show — it reports the version in
+  // preparation or the live one and nothing behind them. Read-only, and the reason it exists is on
+  // the record: three of Niva's release tags say in their own messages that they could not be
+  // confirmed "because historical build numbers are not exposed by vydanne inspect", and all three
+  // were wrong. The data was always one query away.
+  releases: { mod: "releases", client: true },
+  // Takes a version back OUT of review, and it is the mirror of the Play side refusing the
+  // production track: it will retrieve something that is waiting, and it will not touch what
+  // customers already have. `writes` because it changes the store — dry run without --apply.
+  withdraw: { mod: "withdraw", client: true, writes: 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
@@ -42,6 +52,7 @@ export const COMMANDS = {
 // (src/play/commands/). Store-specific commands (Apple accessibility/iap; Play data-safety) aren't shared.
 export const PLAY_COMMANDS = {
   inspect: { mod: "inspect" },
+  releases: { mod: "releases" },
   preflight: { mod: "preflight" },
   diff: { mod: "diff" },
   fill: { mod: "fill", writes: true },

package/types/index.d.ts

@@ -38,6 +38,18 @@ export type CommandName =
    */
   | 'bridge'
   | 'inspect'
+  /**
+   * Version history with the build each release shipped, resolved to the commit that build number
+   * names (`git rev-list --count`) and whether it carries a tag. Read-only. With `--store google`,
+   * what each track is serving — Play keeps no history of superseded releases.
+   */
+  | 'releases'
+  /**
+   * Take a version back out of App Store review so it can be edited — the step `prepare` and
+   * `prerelease` both tell you to do by hand. Refuses a LIVE version, mirroring the Play side's
+   * refusal of the production track. Undoes a submission; never makes one. Dry run without `--apply`.
+   */
+  | 'withdraw'
   | 'diff'
   | 'preflight'
   /**