vydanne 0.8.1 → 0.10.0

package/README.md

@@ -218,13 +218,18 @@ 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
 
 | 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. 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. |
 | `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. |
@@ -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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vydanne",
-  "version": "0.8.1",
+  "version": "0.10.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/commands/preflight.mjs

@@ -16,6 +16,27 @@ export async function run(config, client) {
   // the README listed them among the limits "checked before upload". Read-only, so `allowLive` is
   // right: on an app with nothing in preparation the live record is the only one to measure.
   const info = await client.appInfo({ allowLive: true });
+
+  // ── The fields no LOCAL file drives ─────────────────────────────────────────────────────────────
+  //
+  // Everything else here compares local metadata against the store, which is the right question for
+  // anything `fill` uploads and the wrong one for the half-dozen fields set by their own standalone
+  // command. Those are invisible to a local-vs-remote diff: there is nothing local to differ from, so
+  // a field that was NEVER SET reads exactly like one that matches.
+  //
+  // Reported from the field: a listing reached PREPARE_FOR_SUBMISSION with an empty copyright and no
+  // App Review contact at all, while this command printed "no blockers". `prepare` sets the first and
+  // `review-contact` the second; neither is part of `fill`, and neither had ever been run. Preflight
+  // was not wrong so much as asked the wrong question — so it now also asks whether the listing is
+  // SUBMITTABLE, which only the store can answer.
+  const rights = client.app?.attributes?.contentRightsDeclaration;
+  if (!rights) problems.push("content rights not declared — `vydanne appinfo --apply`");
+  if (info) {
+    if (!info.attributes.appStoreAgeRating) problems.push("age rating not declared — `vydanne age-rating --apply`");
+    const primary = (await client.get(`/v1/appInfos/${info.id}/primaryCategory`)).json?.data?.id;
+    if (!primary) problems.push("primary category not set — `vydanne appinfo --apply`");
+  }
+
   if (info) {
     const infoLocs = (await client.get(`/v1/appInfos/${info.id}/appInfoLocalizations?limit=200`)).json.data || [];
     for (const il of infoLocs) {
@@ -37,6 +58,23 @@ export async function run(config, client) {
       continue;
     }
     console.log(`  ${platform}: version ${v.attributes.versionString} (${v.attributes.appStoreState})`);
+
+    // Required, and set by `prepare` from <metadataDir>/copyright.txt — not by `fill`.
+    if (!v.attributes.copyright) {
+      problems.push(`${platform}: copyright EMPTY — set ${config.metadataDir}/copyright.txt, then \`vydanne prepare --apply\``);
+    }
+
+    // The App Review contact. Apple will not take a submission without one, and it is per-VERSION, so
+    // a contact set on a previous version does not carry forward on its own.
+    const detail = (await client.get(`/v1/appStoreVersions/${v.id}/appStoreReviewDetail`)).json?.data?.attributes;
+    const CONTACT = ["contactFirstName", "contactLastName", "contactPhone", "contactEmail"];
+    const missing = detail ? CONTACT.filter((f) => !detail[f]) : CONTACT;
+    if (missing.length) {
+      problems.push(`${platform}: App Review contact ${detail ? `missing ${missing.join(", ")}` : "not set"} — \`vydanne review-contact --apply\``);
+    } else if (detail.demoAccountRequired && !detail.demoAccountName) {
+      // The rejection `review-contact` exists to avoid, arriving by the door of nobody running it.
+      problems.push(`${platform}: demoAccountRequired is true but no demo account is set — Apple rejects this`);
+    }
     const locs = await client.versionLocalizations(v.id);
     const ascLocales = [...new Set([config.primaryLocale, ...Object.values(res.supported)])];
 

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/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 "*")