vydanne 0.9.0 → 0.11.0

package/README.md

@@ -218,6 +218,11 @@ Two details worth knowing:
 > Upgrading from ≤ 0.5? The Apple half used to write immediately — `vydanne fill` now needs `--apply`.
 > `VYDANNE_COMMIT=1` still works as an alias so existing Play scripts keep running, but prefer the flag.
 
+`fill` takes four more overrides, all off by default: `VYDANNE_REPLACE=1` replaces a store screenshot
+set instead of leaving the live one alone (what you want after re-rendering them), and
+`VYDANNE_SKIP_METADATA=1` / `VYDANNE_SKIP_SCREENSHOTS=1` do one half of the job when the other is
+already right. `VYDANNE_FLATTEN=1` reads a flat screenshot folder rather than per-locale ones.
+
 <br>
 
 ## What each command does
@@ -230,7 +235,7 @@ Two details worth knowing:
 | `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. |
+| `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. |
 | `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. |
@@ -379,7 +384,15 @@ Notes are truncated to Play's 500-char cap with a warning. The versionCode comes
 manifest — vydanne reads it out of the `.aab` locally and reports which changelog file each locale
 resolves to *before* the upload, so a wrong file costs a re-run, not a re-release. Re-uploading a used
 code fails loudly instead of silently replacing a binary. Overrides: `VYDANNE_AAB`, `VYDANNE_TRACK`,
-`VYDANNE_RELEASE_NAME`.
+`VYDANNE_RELEASE_NAME`, `VYDANNE_STATUS`; and `VYDANNE_IPA` for the App Store half.
+
+**An app that has never been published needs `releaseStatus: "draft"`.** Play calls it a *draft app*
+and refuses a `completed` release on every track except `internal`, answering *"Only releases with
+status draft may be created on draft app."* — which names neither the track nor the fix, and is why
+the same bundle uploads to `internal` and fails on `alpha`. Set it in `google.releaseStatus` (or
+`VYDANNE_STATUS=draft` for one run); the build then waits in Play Console for a person to start the
+rollout, which is where an unpublished app's first one belongs. Remove it once the app is live.
+vydanne explains this rejection rather than printing Play's version of it.
 
 **Play is dry by default on purpose.** Nothing goes live until you add `--apply`, so a
 half-finished folder can never overwrite a good listing. Play also uses its **own** language codes

package/SKILL.md

@@ -286,6 +286,7 @@ With `--store google` it uploads an `.aab` to a **closed testing track** with re
 edit transaction. `production` is REFUSED — not flag-gated — so no argument combination ships to the
 public; promoting the tested build stays a human's job, mirroring the Apple side never submitting. Track
 comes from `google.track` / `VYDANNE_TRACK`, default `internal`; the bundle from `google.aab` /
+- `VYDANNE_STATUS` — release status for `prerelease --store google`: `draft`, `inProgress`, `halted`, `completed` (default). Use `draft` for an app that has never been published: Play refuses a completed release on any track but `internal` until it is live, and says so in a message that names neither the track nor the fix. Also settable as `google.releaseStatus`.
 `VYDANNE_AAB` (a directory takes its newest `.aab`). **For a PAID app use `internal`** — it's the only
 track where testers install without buying. Notes follow supply's layout, per locale, first match wins:
 `<google.metadataDir>/<play-locale>/changelogs/<versionCode>.txt` → `next.txt` → `default.txt`, capped
@@ -296,6 +297,11 @@ than silent. The versionCode is read out of the `.aab` locally and the changelog
 BEFORE the upload; re-uploading a used code fails loudly instead of silently replacing. DRY by default;
 `--apply` publishes.
 
+`inspect --store google` also reports **which build is on which track** — versionCode, version
+name, status, and a staged rollout's percentage — for every track that carries a release. Tracks
+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
 (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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vydanne",
-  "version": "0.9.0",
+  "version": "0.11.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/config.mjs

@@ -98,6 +98,12 @@ export async function loadConfig(p) {
           defaultLocale: raw.google.defaultLocale || raw.primaryLocale,
           aab: raw.google.aab || null,
           track: raw.google.track || "internal", // testing only — `prerelease` refuses production
+          // What state a new release is created in: draft | inProgress | halted | completed.
+          // Left null so `prerelease` keeps its own default ("completed"). The one case that needs
+          // it is an app that has never been published — Play calls that a "draft app" and refuses
+          // a completed release on any track but internal, so the first closed or open rollout has
+          // to be created as "draft" and started by a person in Console.
+          releaseStatus: raw.google.releaseStatus || null,
           // Play image type -> local source path. Merged over the defaults so an app overrides only the
           // slots whose layout differs; the default for `icon` points at znachok's output, which is a
           // sensible default for this portfolio and a mystery to anyone else, so it is overridable.

package/src/play/client.mjs

@@ -86,6 +86,35 @@ export class PlayClient {
 
   getTrack(editId, track) { return this.req("GET", `/edits/${editId}/tracks/${track}`); }
 
+  /**
+   * The track NAMES this app has, from inside an edit.
+   *
+   * Only the names are worth taking from here. The `releases` this returns are the track's DESIRED
+   * state — whatever the last edit wrote — which is not what anyone means by "what is on the track".
+   * Use [trackReleases] for that; see its note.
+   */
+  listTracks(editId) { return this.req("GET", `/edits/${editId}/tracks`); }
+
+  /**
+   * What is ACTUALLY on a track: every non-obsolete release, with its lifecycle state.
+   *
+   * Needs no edit, and it is a different answer from `edits/…/tracks`. That one reports the last
+   * write; this reports reality, and the two disagree exactly when it matters most. Measured on
+   * Niva, 2026-09-05:
+   *
+   *   edits/…/tracks   alpha → [131]                       "the upload worked"
+   *   tracks/alpha/…   alpha → 1.4 (131) IN_REVIEW
+   *                          + 1.0 (102) PUBLISHED         "…and testers still have 1.0"
+   *
+   * A newly uploaded build does not reach testers until review passes, so the previously published
+   * release keeps serving — and the edit-based view cannot see it at all. Reporting only the edit
+   * view meant `inspect` said a release was live when nobody had it yet.
+   *
+   * Shape differs from the edits API too: `releaseName`, `activeArtifacts[].versionCode` and
+   * `releaseLifecycleState`, not `name`/`versionCodes`/`status`.
+   */
+  trackReleases(track) { return this.req("GET", `/tracks/${encodeURIComponent(track)}/releases`); }
+
   /**
    * Point a track at version codes. `releases` is the FULL desired state of that track — Play replaces
    * it wholesale, so send one complete release object rather than appending to what is already there.

package/src/play/commands/inspect.mjs

@@ -1,7 +1,14 @@
 const IMAGE_TYPES = ["phoneScreenshots", "sevenInchScreenshots", "tenInchScreenshots", "wearScreenshots", "tvScreenshots", "featureGraphic", "icon", "promoGraphic"];
 
-// Read-only snapshot of the Play listing — languages, contact details, image counts. Everything reads
-// through one throwaway edit (deleted, never committed), the same as the ASC `inspect`.
+// Read-only snapshot of the Play listing — languages, contact details, image counts, and WHAT IS
+// PUBLISHED WHERE. Everything reads through one throwaway edit (deleted, never committed), the same
+// as the ASC `inspect`.
+//
+// The tracks half was missing until 2026-09-05, and its absence was the difference between "the
+// upload command said it worked" and knowing. `inspect` reported the listing beautifully and could
+// not answer the only question anyone asks after a release — which build is on which track, under
+// what version name — so that had to be worked out by hand against the raw androidpublisher API.
+// A read-only command that cannot show you the state you just changed is half a command.
 export async function run(config, client) {
   const g = config.google;
   const editId = await client.newEdit();
@@ -17,6 +24,68 @@ export async function run(config, client) {
       if (imgs.length) counts.push(`${t}=${imgs.length}`);
     }
     console.log(`  images (${lang}): ${counts.join("  ") || "(none)"}`);
+
+    // What is actually ON each track, which is NOT what the edit says is on it.
+    //
+    // The edit's own `tracks` gives the desired state — the last thing written — so straight after
+    // an upload it happily reports the new build and nothing else. The track's `releases` endpoint
+    // reports reality: the build in review AND the older one still serving testers underneath it,
+    // because a new build does not reach anyone until review passes. Reporting the edit view alone
+    // said a release was live when nobody had it (measured on Niva, 2026-09-05).
+    //
+    // So the edit is used only to enumerate track NAMES; every state below comes from the
+    // non-edit endpoint.
+    const LIFECYCLE = {
+      RELEASE_LIFECYCLE_STATE_PUBLISHED: "published",
+      RELEASE_LIFECYCLE_STATE_IN_REVIEW: "in review",
+      RELEASE_LIFECYCLE_STATE_DRAFT: "draft",
+      RELEASE_LIFECYCLE_STATE_HALTED: "halted",
+      RELEASE_LIFECYCLE_STATE_UNSPECIFIED: "unspecified",
+    };
+    const edited = (await client.listTracks(editId)).json.tracks || [];
+    const rows = [];
+    let degraded = null;
+    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;
+      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
+        // zero rows and the command printed "nothing published" about an app with three live
+        // tracks. The endpoint is quota-limited ("Listing releases quota exceeded"), so this is a
+        // state a normal day reaches, not an exotic one. Fall back to the edit's view, which is the
+        // last write rather than what is serving, and label every row so it is never mistaken for
+        // the real thing.
+        degraded = res.json?.error?.message || `HTTP ${res.status}`;
+        for (const rel of t.releases || []) {
+          const codes = (rel.versionCodes || []).join(",") || "-";
+          if (codes === "-") continue;
+          rows.push(`  ~ ${t.track.padEnd(12)} ${codes.padEnd(8)} ${(rel.name || "-").padEnd(12)} ${rel.status || "?"}`);
+        }
+        continue;
+      }
+      for (const rel of res.json.releases || []) {
+        const codes = (rel.activeArtifacts || []).map((a) => a.versionCode).join(",") || "-";
+        const state = LIFECYCLE[rel.releaseLifecycleState] || rel.releaseLifecycleState || "?";
+        const staged = rel.userFraction != null ? `  ${Math.round(rel.userFraction * 100)}% rollout` : "";
+        rows.push(`    ${t.track.padEnd(12)} ${codes.padEnd(8)} ${(rel.releaseName || "-").padEnd(12)} ${state}${staged}`);
+      }
+    }
+    if (rows.length) {
+      console.log(`  tracks (${rows.length} release(s)):`);
+      console.log(`    ${"track".padEnd(12)} ${"code".padEnd(8)} ${"name".padEnd(12)} state`);
+      for (const r of rows) console.log(r);
+    } else if (degraded) {
+      console.log("  tracks: could not be read — " + degraded);
+    } else {
+      console.log("  tracks: (nothing published — no track carries a release)");
+    }
+    if (degraded && rows.length) {
+      console.log(`  ~ rows are the EDIT's view (what was last written), not what is serving.`);
+      console.log(`    Live state unavailable: ${degraded}`);
+    }
   } finally {
     await client.deleteEdit(editId);
   }

package/src/play/commands/prerelease.mjs

@@ -92,13 +92,26 @@ export async function run(config, client) {
     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)] };
+    //
+    // The status is settable because a DRAFT APP — one that has never been published — refuses a
+    // "completed" release on any track but internal, with
+    //   "Only releases with status draft may be created on draft app."
+    // which names neither the track nor the fix. Set VYDANNE_STATUS=draft for the first closed
+    // or open rollout of an app that is not live yet; the release then waits in Play Console for
+    // a human to start it, which is where an unpublished app's first rollout belongs anyway.
+    const status = process.env.VYDANNE_STATUS || g.releaseStatus || "completed";
+    if (!RELEASE_STATUSES.includes(status)) {
+      throw new Error(
+        `release status "${status}" is not one Play accepts — use one of ${RELEASE_STATUSES.join(", ")}`,
+      );
+    }
+    const release = { status, versionCodes: [String(versionCode)] };
     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 (put.status >= 300) throw new Error(explainPlayError("tracks.update", put, track, status));
 
     if (client.dryRun) {
       await client.deleteEdit(editId);
@@ -106,8 +119,17 @@ export async function run(config, client) {
       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}".`));
+    if (res.status >= 300) throw new Error(explainPlayError("edits.commit", res, track, status));
+    // "live" is only true of a release that has actually started. A draft one is uploaded and
+    // waiting, and telling somebody it is live is how a build sits unnoticed for a week.
+    console.log(
+      status === "draft"
+        ? green(`\n  committed — versionCode ${versionCode} is on "${track}" as a DRAFT release.`)
+        : green(`\n  committed — versionCode ${versionCode} is live on "${track}".`),
+    );
+    if (status === "draft") {
+      console.log(`  Nobody has it yet: open Play Console and start the rollout when you are ready.`);
+    }
     archiveNextNotes(notes, versionCode);
     console.log("  Production stays manual: promote it in Play Console when you're ready.");
     return true;
@@ -209,3 +231,39 @@ function archiveNextNotes(notes, versionCode) {
     }
   }
 }
+
+/** The release statuses Play's Publishing API accepts. A typo here costs a round trip otherwise. */
+const RELEASE_STATUSES = ["draft", "inProgress", "halted", "completed"];
+
+/**
+ * Play's rejection, plus what to do about it.
+ *
+ * One rejection is worth translating rather than printing. An app that has never been published is
+ * a "draft app", and Play will not accept a `completed` release on any track except internal:
+ *
+ *     Only releases with status draft may be created on draft app.
+ *
+ * That sentence names neither the track it is talking about nor the setting that fixes it, and it
+ * arrives identically from the track update and from the commit — so the same upload succeeds on
+ * `internal` and fails on `alpha` with a message that suggests nothing about tracks at all. The
+ * fix is one setting, and it belongs in the error rather than in somebody's memory.
+ */
+function explainPlayError(where, res, track, status) {
+  const body = JSON.stringify(res.json).slice(0, 300);
+  const message = res.json?.error?.message || "";
+  if (/draft app/i.test(message)) {
+    return [
+      `${where} ${res.status}: ${message}`,
+      "",
+      `  This app has never been published, so Play calls it a draft app — and a draft app only`,
+      `  accepts releases whose status is "draft". You asked for "${status}" on track "${track}".`,
+      "",
+      `  Set it once in your config:      google: { releaseStatus: "draft" }`,
+      `  Or for this run only:            VYDANNE_STATUS=draft`,
+      "",
+      `  The build then waits in Play Console for a person to start the rollout, which is where an`,
+      `  unpublished app's first one belongs. Remove the setting once the app is live.`,
+    ].join("\n");
+  }
+  return `${where} ${res.status}: ${body}`;
+}

package/types/index.d.ts

@@ -139,6 +139,15 @@ export interface GoogleConfig {
    * track you created in Play Console. Only 'production' is refused — that release is a human's.
    */
   track?: string;
+  /**
+   * What state a new release is created in. Defaults to 'completed' — the rollout starts on upload.
+   *
+   * Set 'draft' for an app that has NEVER been published: Play calls that a "draft app" and refuses
+   * a completed release on any track but internal, with a message that names neither the track nor
+   * the fix. A draft release waits in Play Console for a person to start it. Remove once live.
+   * Override: VYDANNE_STATUS.
+   */
+  releaseStatus?: "draft" | "inProgress" | "halted" | "completed";
   /**
    * Play image type -> local source path. Merged over the defaults, so declare only what differs.
    * A type whose source does not exist is skipped; a missing local set never deletes the live one.

package/vydanne.config.example.mjs

@@ -100,6 +100,11 @@ export default {
     // 'internal' (default), 'alpha', 'beta', or the name of any closed track you made in Play Console.
     // Only 'production' is refused.
     // track: "internal",
+    // What state a new release is created in: "draft" | "inProgress" | "halted" | "completed".
+    // Defaults to "completed" — the rollout starts on upload. An app that has NEVER been published
+    // is a "draft app" to Play, which refuses a completed release on any track but internal; set
+    // "draft" until it is live and start the rollout yourself in Console. Override: VYDANNE_STATUS.
+    // releaseStatus: "draft",
     // Play image type -> local source. Merged over the defaults, so override only what differs.
     // images: { icon: "brand/icons/play/icon-512.png", phoneScreenshots: "marketing/out/play-phone-plain" },
     // Play holds graphics PER LANGUAGE. Default is one set at `defaultLocale`; list locales (or "*")