vydanne 0.5.0 → 0.7.0

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vydanne
-description: Prepare an App Store Connect / Google Play submission — write AND push the localized store listing. Crafts the ASO copy (app-store name, subtitle, the 100-char keyword field, description, promo text), then fills the listing + screenshots + previews, age rating, review contact, accessibility & App Privacy labels, IAP fields, and export-compliance docs; verifies with a preflight gate and diffs local-vs-live. Native Node (ES256 JWT + fetch, no fastlane/Ruby). One vydanne.config.mjs per app. Use when writing or shipping any App Store / Play listing. Never submits — a human attaches the signed build and hits Submit.
+description: Prepare an App Store Connect / Google Play submission — write AND push the localized store listing. Crafts the ASO copy (app-store name, subtitle, the 100-char keyword field, description, promo text), then fills the listing + screenshots + previews, age rating, review contact, accessibility & App Privacy labels, IAP fields, and export-compliance docs; verifies with a preflight gate and diffs local-vs-live. Native Node (ES256 JWT + fetch, no fastlane/Ruby). One vydanne.config.mjs per app. Use when writing or shipping any App Store / Play listing. Uploads builds to testers (TestFlight internal / Play closed track) and points the prepared version at them — but never submits for review and never ships to the public.
 ---
 
 # vydanne
@@ -11,10 +11,18 @@ fastlane/Ruby/Python. Two jobs: **(A) write the listing well (ASO)**, **(B) push
 **Companion tool — [zdymak](https://www.npmjs.com/package/zdymak)** makes the *media* (screenshots, App
 Preview videos, Play feature graphic); vydanne pushes that media plus all the *text and paperwork*. If the
 user needs screenshots or a preview video produced, that's zdymak's job, not vydanne's — vydanne only
-uploads files that already exist. zdymak's default output paths are exactly the paths vydanne reads for
-Play images (below), so the two line up with no glue.
-
-**Never submits.** A human attaches the signed build and presses Submit. Don't try to work around this.
+uploads files that already exist. **The two do NOT line up on disk** (they did before zdymak 0.15):
+zdymak writes one root shaped `store-assets/<locale>/<target>/NN-name.png`, while vydanne reads several
+hardcoded roots, with Apple's locale codes and a device-prefix filename convention. **`vydanne bridge`
+is the glue** — run it after `zdymak screenshots`/`zdymak build` and before `fill`, every time.
+Skipping it is silent and dangerous: zdymak reports success, vydanne re-uploads whatever was bridged
+LAST time, and the store quietly keeps stale art.
+
+**Never submits for review; never ships to the public.** It *does* upload builds — `prerelease` sends
+the `.ipa` to TestFlight (internal groups) or the `.aab` to a Play closed track, and points the version
+being prepared at it. What stays human: pressing Submit, Play `production`, and external TestFlight
+(which needs Beta App Review). Those are refusals rather than flags, so there is no argument
+combination that reaches the public. Don't try to work around that.
 
 ## Setup
 
@@ -47,8 +55,30 @@ which user file was used, and whether the `.p8` is on disk.
 
 **Config fields:** `bundleId` · `primaryLocale` (the fallback — must be populated) · `asc` (optional
 `{profile}` — selection only, never secrets) · `platforms` (iOS and macOS are SEPARATE) · `uiLocales`
-(auto-mapped to ASC codes) · `metadataDir` · `rating` · `privacy` · `iaps` · `previews` · `export` ·
-`google` (Google Play).
+(auto-mapped to ASC codes) · `localeMap` · `metadataDir` · `screenshots` · `rating` · `ageRating` ·
+`privacy` · `iaps` · `previews` · `export` · `accessibility` · `ios` · `google` (Google Play) ·
+`bridge` · `push` · `reviewContact` · `allowCrossStoreTerms`.
+
+**Paths are defaults, not laws.** `metadataDir` (default `fastlane/metadata`), `screenshots`
+(`{IOS, MAC_OS}`, default `fastlane/screenshots` + `-macos`) and `google.images` (Play image type →
+local path) all follow fastlane's supply convention out of the box and are all overridable. Point them
+at the repo you have rather than reshaping the repo around the tool.
+
+**Four blocks the tool will NOT fill in for you.** Each publishes a CLAIM rather than a fact, so silence
+is refused instead of defaulted — that is deliberate, and re-adding a default is the bug, not the fix:
+
+- **`accessibility`** — Accessibility Nutrition Labels. Declare every feature true/false from what was
+  actually verified. No block → the command errors.
+- **`export.algorithms` + `export.statement`** — the cryptography inventory and statement in the US
+  export-compliance PDF (`compliance`). Required when `export.encryption` is `"standard"`. Never invent
+  these; ask what the app actually ships. `export.filed` stays **false** until the report has really
+  been emailed to BIS and the NSA, and while it is false the PDF does not claim it was submitted.
+- **`ageRating`** — needed for any `rating` above `"4+"`. Describe the CONTENT
+  (`{ violenceCartoonOrFantasy: "INFREQUENT_OR_MILD" }`, merged over an all-NONE base); Apple computes
+  the band. `"4+"` alone needs nothing else.
+- **`reviewContact` / demo account** — whether App Review needs a login is inferred from
+  `<metadataDir>/review_information/demo_user.txt` + `demo_password.txt` (both gitignored). An app with
+  a sign-in wall and no demo account is a guaranteed rejection.
 
 For a non-technical user asking how to set this up from scratch, walk them through
 **`GETTING_STARTED.md`** (accounts → API key → config → folders → push) rather than improvising.
@@ -90,17 +120,38 @@ before the **first underscore** selects the device slot; files upload in sorted
 | `watch_` | `APP_WATCH_ULTRA` |
 | `macos_` | `APP_DESKTOP` (in `screenshots-macos/`) |
 
-An unknown prefix is silently ignored. A set that **already has screenshots is skipped**, never
-duplicated — to replace shots, delete them in ASC first. PNGs must be **RGB with no alpha**.
+A file with an unknown prefix is not uploaded, and `fill` names it. A set that **already has
+screenshots is skipped** (and says so), never duplicated — `VYDANNE_REPLACE=1` deletes the store's set
+and uploads yours, the same flag `previews` uses. PNGs must be **RGB with no alpha**.
 
 **Play listing text** — `<google.metadataDir>/<PLAY-locale>/{title,short_description,full_description}.txt`
 (30 / 80 / 4000). Play uses its **own** codes (`de-DE`, `zh-CN`, `iw-IL`, `ar`, `be`) — *not* Apple's
 `zh-Hans`/`he`/`ar-SA`.
 
-**Play images** — hardcoded source paths (zdymak's output), each pushed only when the file exists, so a
-missing local set never deletes the live one: `brand/icons/play/icon-512.png` (512²) ·
-`marketing/out/play-feature-graphic.png` (1024×500) · `marketing/out/play-phone-plain/` ·
-`marketing/out/play-tablet7-plain/` (7″) · `marketing/out/play-tablet-plain/` (10″).
+**Play images** — DEFAULT source paths (override any of them with `google.images`), each pushed only
+when the file exists, so a missing local set never deletes the live one:
+`brand/icons/play/icon-512.png` (512², from znachok) · `marketing/out/play-feature-graphic.png`
+(1024×500) · `marketing/out/play-phone-plain/` · `marketing/out/play-tablet7-plain/` (7″) ·
+`marketing/out/play-tablet-plain/` (10″) · `marketing/out/play-wear/`. `wearScreenshots`, `tvScreenshots`
+and `tvBanner` are also understood, so a Wear OS or Android TV release is a config line, not a code
+change. An image dir that exists but is EMPTY is reported (by `fill` and `diff`) as a live set only
+Play Console can remove.
+
+Play holds graphics **per language**. The default uploads one untranslated set at
+`google.defaultLocale`; `google.imageLocales` (a list, or `"*"` for every local listing folder) opts
+into localized art, and a `<source>/<lang>/` subdirectory overrides the shared source for that language.
+`diff --store google` compares exactly the locales `fill` would write, so the two never disagree.
+
+**`bridge` populates both screenshot layouts from zdymak's output.** It maps
+`store-assets/<locale>/<dir>/NN-name.png` onto the Apple and Play paths above: locale codes via the
+same `toAsc` table `fill` uses (`de` → `de-DE`; a code with no App Store language is skipped and falls
+back to the primary listing), the device-slot prefix prepended (`iphone69_01-fresh.png`), and the Play
+sets into their configured destinations. A locale with screenshots but NO listing text is held back
+(uploading pictures alone would create the localization and break its fallback to the primary
+language), and every bridged image is checked for an alpha channel — which Apple rejects — on the
+SOURCE, before anything is copied, so a refusal leaves the destinations untouched and `--dry-run`
+catches it too. Local files only; `--dry-run` previews what would be written *and removed*. See the
+directory-vs-target note under Commands for why the source folder name is the thing that matters.
 
 ## A. Writing the listing (the ASO craft — the durable value)
 
@@ -161,8 +212,65 @@ who it's for → honest close. Keep it scannable; lead each bullet with the payo
 `fill` (metadata + screenshots, native PATCH/chunked upload — works even at READY_FOR_REVIEW) ·
 `previews` (App Preview videos) · `age-rating` · `review-contact` · `accessibility` (draft; publish once
 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) · `diff` (what differs vs live) · `preflight`
-(completeness gate) · `inspect` · `auth` (what credentials resolved, and from where) · `locales` · `version`.
+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
+resolved, and from where) · `locales` · `version`.
+
+**`bridge` maps by DIRECTORY, not by target.** zdymak writes each shot to `<dir || target>`, so a
+`dir:` override makes the folder name differ from the target name — and Play's 7" slot can *only* exist
+that way (`{ target: 'play-tablet', dir: 'play-tablet7-plain' }`; there is no `play-tablet7` target).
+Defaults prefer the `-plain` convention Google asks for on listings and fall back to the bare target
+name; `bridge.apple` / `bridge.play` override per slot. It **owns its destinations per store**: any
+Apple output means both Apple roots are rebuilt (so art dropped upstream stops being uploaded), while
+an app that bridges only Play never has its hand-managed Apple screenshots touched. It plans before it
+writes — a failure (alpha channel, empty source) leaves every destination untouched, and `--dry-run`
+reports exactly what a real run would write *and remove*.
+
+**Cross-store lint.** `preflight` and `fill` refuse listing text that names the other mobile platform
+— App Review 2.3.10 for Apple, the Store Listing and Promotion policy for Google — scanning every
+locale and field of the LOCAL metadata before upload, including localized spellings of Android/Apple.
+A store's own platform is never flagged, nor the bare word "Play". Ambiguous words warn instead of
+blocking; `allowCrossStoreTerms: [...]` in the config silences a specific one, and
+`VYDANNE_ALLOW_CROSS_STORE=1` overrides a single run. This is a rejection that surfaces days later in
+one locale out of twenty, so it is checked where it is free to fix.
+
+**The pipeline has ONE working order** — `prepare` → `fill` → `previews` → `age-rating` →
+`review-contact` → `accessibility` → `preflight` → **a human submits**. `prepare` must be first (until
+the draft version exists, nothing has anywhere to write) and `preflight` last (green must be measured
+after the writes it blesses). `push` runs exactly that sequence — each step the same `run` as the
+standalone command, on the same client, stopping at the first failure — so prefer `vydanne push` over
+re-deriving the order; the near-miss that motivated it was `fill` pointed at a live-only app out of
+order. The two flows differ only at step one and `push` absorbs it: a FIRST release already has a
+PREPARE_FOR_SUBMISSION version (creating the app record made it), so `prepare` is a find-and-reuse
+no-op; an UPDATE has only the read-only live version until `prepare` creates the next one. On a live
+app a DRY `push` stops at `fill` — the draft the later steps target doesn't exist until `prepare` is
+applied — and says so up front; `prepare --apply` (a draft, not a submission) then a dry `push`
+previews the whole plan. `prepare` creates a version for EVERY declared platform, so an iOS+macOS app
+gets both drafts. `prerelease` is deliberately not a step (macOS-only, shells out to altool); run it
+whenever the build is ready — `prepare` attaches the newest build either way.
+
+**`push --skip <step>[,<step>]`** (or `push: { skip: [...] }`) drops a step that doesn't apply — the
+usual case being an app with no audited `accessibility` block, which the command correctly refuses to
+guess. `prepare` and `preflight` cannot be skipped. Every skip is reported on its own line AND again
+after the final green, because the whole value of that last line is that green means green: never let
+a skipped run read like a complete one.
+
+`prepare` creates the version to write INTO, and is REQUIRED as the first push step on any app that
+already has a version on sale. Every other Apple command finds its target through
+`client.editVersion()`, which returns the first version Apple has not marked dead; when the only
+version is live it has no editable record to return and falls back to the live one — so `fill` aims
+its `description`/`whatsNew` PATCHes at the listing customers are reading, and `prerelease` declines
+to attach the build it just uploaded. `prepare` POSTs `/v1/appStoreVersions` with `releaseType:
+MANUAL` (so approval still doesn't release), sets `copyright` from `<metadataDir>/copyright.txt`
+(nothing else in vydanne writes that version-level field), and attaches the newest build. The version
+number is read off that build's `preReleaseVersion` — the archive's own
+`CFBundleShortVersionString`, so it cannot drift from the binary — or `VYDANNE_VERSION=<x>` when the
+version is being prepared before its build exists. It is find-or-create, so re-running is safe; a
+version Apple has locked (`IN_REVIEW`, `READY_FOR_SALE`, …) is refused rather than edited, because
+withdrawing a submission is the operator's call. It pre-checks the number against the version on sale,
+turning Apple's 409 into a sentence. **Creating a draft is not submitting** — Add to Review and Submit
+stay manual.
 
 `prerelease` uploads the BUILD. On Apple it validates and uploads the `.ipa` to **TestFlight** via
 `xcrun altool` — the one command that shells out, because the ASC REST API has never carried a binary,
@@ -179,25 +287,49 @@ edit transaction. `production` is REFUSED — not flag-gated — so no argument
 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_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:
-`<google.metadataDir>/<play-locale>/changelogs/<versionCode>.txt`, falling back to `default.txt`, capped
-at Play's 500 chars. DRY by default like `fill --store google`; `VYDANNE_COMMIT=1` publishes. The
-versionCode comes from the bundle itself, so re-uploading one fails loudly instead of silently replacing.
+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
+at Play's 500 chars. **Write the upcoming release's notes as `next.txt`** when the versionCode is not
+knowable in advance (derived from the commit count, say): after a real publish vydanne renames it to
+`<versionCode>.txt` so the next release can't inherit it, and a `default.txt` fallback is WARNED rather
+than silent. The versionCode is read out of the `.aab` locally and the changelog resolution reported
+BEFORE the upload; re-uploading a used code fails loudly instead of silently replacing. DRY by default;
+`--apply` publishes.
 
 `--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).
-`fill --store google` is **DRY by default**; `VYDANNE_COMMIT=1` commits. The AAB binary and the
-(YouTube-URL) promo video stay outside vydanne.
+The AAB binary and the (YouTube-URL) promo video stay outside vydanne.
+
+## `--apply` — writes are opt-in
+
+**Every store-mutating command is a DRY RUN without `--apply`**: `prepare` · `push` · `fill` ·
+`previews` · `age-rating` · `review-contact` · `accessibility` · `prerelease` (marked `✎` in
+the usage text, printed by `vydanne` with no arguments). They read the store, print each write they would make, and send nothing. Read-only
+commands ignore the flag.
+
+Never reach for `--apply` to "check whether it works" — the dry run IS the check, and it walks the whole
+plan rather than stopping at the first locale. Its closing count is what you compare against `diff`.
+
+Enforcement differs per store, on purpose: **Play** builds the Edit and validates it against Google for
+real, then discards it (nothing is live until commit). **Apple** has no transaction, so the gate is at the
+HTTP layer in `src/client.mjs` — no `POST`/`PATCH`/`PUT`/`DELETE` leaves the process, and each is recorded
+in `client.planned`. `prerelease` needs its own guard because the `altool` binary upload does not go
+through that client. **A new command that touches the store must be marked `writes: true` in
+`src/registry.mjs`** — that flag is the whole opt-in, not a label.
 
 **Env toggles:** `VYDANNE_CONFIG` · `VYDANNE_SKIP_METADATA` / `VYDANNE_SKIP_SCREENSHOTS` (fill) ·
-`VYDANNE_COMMIT` (Play fill) · `VYDANNE_REPLACE` (previews) · `VYDANNE_FLATTEN=<png>` (iap) ·
-`VYDANNE_A11Y_PUBLISH` (accessibility).
+`VYDANNE_REPLACE` (fill screenshots + previews: replace populated slots) · `VYDANNE_VERSION` (prepare) ·
+`VYDANNE_IPA` / `VYDANNE_AAB` / `VYDANNE_TRACK` / `VYDANNE_RELEASE_NAME` (prerelease) ·
+`VYDANNE_FLATTEN=<png>` (iap) · `VYDANNE_A11Y_PUBLISH` (accessibility) · `VYDANNE_ALLOW_CROSS_STORE`
+(one run past the cross-store lint) · `VYDANNE_COMMIT=1` (legacy alias for `--apply`; prefer the flag).
 
 ## Flow
 
-config → **write the English master listing (ASO, research-grounded)** → `preflight` (char limits) → fan
-out one copywriter agent per locale → media from zdymak → `fill` + `previews` + declarations → `diff`
-(dry-run) → `preflight` (must be green) → **a human submits**.
+config → **write the English master listing (ASO, research-grounded)** → fan out one copywriter agent
+per locale → media from zdymak → **`bridge`** (zdymak's output into vydanne's folders — every time) →
+build via `prerelease --apply` whenever it is ready → `push` (read the dry run, then re-run with
+`--apply` — it is prepare → fill → previews → age-rating → review-contact → accessibility → preflight,
+stopping at the first failure) → `diff` to confirm → **a human submits**.
 
 ## Gotchas it encodes (don't re-derive)
 

package/bin/vydanne.mjs

@@ -5,6 +5,7 @@ import path from "node:path";
 import { loadConfig } from "../src/config.mjs";
 import { Client } from "../src/client.mjs";
 import { COMMANDS, PLAY_COMMANDS } from "../src/registry.mjs";
+import { yellow } from "../src/util.mjs";
 
 const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url))).version;
 
@@ -14,6 +15,23 @@ const i = argv.indexOf("--config");
 const cfgPath = i >= 0 ? argv[i + 1] : undefined;
 const si = argv.indexOf("--store");
 const store = si >= 0 ? argv[si + 1] : "apple";
+// Validated, because the dispatch below only tests `store === "google"`: a typo (`--store goole`) or a
+// missing value (`--store --apply`) would otherwise fall through to the APPLE branch and aim the command
+// at the other store — the worst possible reading of a mistyped argument, and a silent one, since every
+// Apple command runs happily from a repo configured for both.
+if (store !== "apple" && store !== "google") {
+  console.error(`\x1b[31mvydanne: unknown --store '${store}' (expected: apple, google)\x1b[0m`);
+  process.exit(1);
+}
+
+// SAFE BY DEFAULT. Every store-mutating command is a dry run unless `--apply` is passed. The Play half
+// always worked this way (VYDANNE_COMMIT=1, enforceable because an Edit can be discarded); the Apple half
+// did not, and wrote the moment it was invoked — including from a mistyped `vydanne fill --help`, which
+// is not a hypothetical. One flag now means the same thing on both stores.
+//
+// VYDANNE_COMMIT=1 stays as an alias so the existing `play:internal` / `play:closed` scripts in the games
+// keep working unchanged; `--apply` is what the docs teach.
+const apply = argv.includes("--apply") || process.env.VYDANNE_COMMIT === "1";
 
 try {
   if (["version", "-v", "--version"].includes(cmd)) {
@@ -47,23 +65,41 @@ try {
     console.log(`supported (${Object.keys(r.supported).length}):`);
     for (const [ui, asc] of Object.entries(r.supported)) console.log(`  ${ui} -> ${asc}`);
     console.log(`unsupported (${r.unsupported.length}) [no App Store language -> fall back to primary]: ${r.unsupported.join(", ")}`);
+    // A localeMap entry pointing at a code Apple does not have is a config mistake, not a missing
+    // language — it would otherwise be indistinguishable from the line above.
+    if (r.invalid?.length) console.log(`\x1b[31minvalid localeMap (${r.invalid.length}) [not an App Store code]: ${r.invalid.join(", ")}\x1b[0m`);
   } else if (store === "google") {
     const cfg = await loadConfig(cfgPath);
     if (!cfg.google) throw new Error("vydanne: no `google` block in config — add packageName + a service-account key");
     if (!PLAY_COMMANDS[cmd]) throw new Error(`vydanne: '${cmd}' isn't available for --store google (try: ${Object.keys(PLAY_COMMANDS).join(", ")})`);
     if (!cfg.google.serviceAccountKey) throw new Error("vydanne: set PLAY_JSON_KEY_FILE (or google.serviceAccountKey) to the Play service-account JSON");
     const { PlayClient } = await import("../src/play/client.mjs");
-    const client = await PlayClient.create({ keyPath: cfg.google.serviceAccountKey, packageName: cfg.google.packageName });
-    const { run } = await import(`../src/play/commands/${PLAY_COMMANDS[cmd].mod}.mjs`);
+    const spec = PLAY_COMMANDS[cmd];
+    const dryRun = Boolean(spec.writes) && !apply;
+    // Play needs no request-level gate: every mutation happens inside an Edit, and an Edit that is never
+    // committed changes nothing. So a dry run here VALIDATES for real against Google, then discards.
+    const client = await PlayClient.create({ keyPath: cfg.google.serviceAccountKey, packageName: cfg.google.packageName, dryRun });
+    if (dryRun) console.log(yellow(`DRY RUN — '${cmd} --store google' validates against Play and discards the edit. Add --apply to commit.`));
+    const { run } = await import(`../src/play/commands/${spec.mod}.mjs`);
     const ok = await run(cfg, client);
     if (ok === false) process.exit(1);
   } else if (COMMANDS[cmd]) {
     const cfg = await loadConfig(cfgPath);
     const spec = COMMANDS[cmd];
     const { run } = await import(`../src/commands/${spec.mod}.mjs`);
-    const client = spec.client ? new Client({ keyId: cfg.keyId, issuerId: cfg.issuerId }) : null;
+    const dryRun = Boolean(spec.writes) && !apply;
+    const client = spec.client ? new Client({ keyId: cfg.keyId, issuerId: cfg.issuerId, dryRun }) : null;
+    if (dryRun) console.log(yellow(`DRY RUN — '${cmd}' will not change App Store Connect. Add --apply to write.`));
     // altool authenticates on its own rather than through our JWT, so it needs the raw ids.
     const ok = await run(cfg, client, spec.credentials ? { keyId: cfg.keyId, issuerId: cfg.issuerId } : undefined);
+    // The count is the point: "nothing happened" is not the same as "nothing would happen", and only the
+    // second one means the local state already matches the store.
+    if (dryRun && client) {
+      const n = client.planned.length;
+      console.log(yellow(n
+        ? `DRY RUN — ${n} store write(s) withheld. Re-run with --apply to perform them.`
+        : "DRY RUN — nothing to write; the store already matches local."));
+    }
     if (ok === false) process.exit(1);
   } else {
     console.error(usage());
@@ -75,26 +111,44 @@ try {
 }
 
 function usage() {
-  return `vydanne ${VERSION} — App Store Connect submission prep (companion to zdymak). Never submits.
-usage: vydanne <command> [--config vydanne.config.mjs]
-  fill            metadata + screenshots + previews (native; iOS & macOS separate)
-  age-rating      set the age rating (AppInfo declaration)
-  review-contact  App Review contact from the gitignored files
-  accessibility   Accessibility Nutrition Labels (draft; VYDANNE_A11Y_PUBLISH=1 to publish once live)
+  return `vydanne ${VERSION} — App Store Connect + Play prep (companion to zdymak). Ships builds to
+testers; never submits for review.
+usage: vydanne <command> [--apply] [--config vydanne.config.mjs]
+
+  --apply         PERFORM the writes. Without it every store-mutating command below (marked ✎) runs
+                  as a DRY RUN: it reads the store, reports exactly what it would change, and sends
+                  nothing. Read-only commands ignore the flag.
+✎ prepare         create/reuse the editable App Store version and attach the uploaded build.
+                  Run this FIRST on an app that already has a version on sale — until it has,
+                  there is no draft for \`fill\` to write into. Never submits; VYDANNE_VERSION=<x>
+                  to name the version instead of reading it off the newest build.
+✎ push            the whole pipeline, in order: prepare → fill → previews → age-rating →
+                  review-contact → accessibility → preflight. Stops at the first failure.
+                  --skip <step>[,<step>] drops steps that don't apply (prepare/preflight can't be
+                  skipped); every skip is reported again at the end, so green still means green.
+                  Ends at a green preflight — Add to Review + Submit stay yours, in the web UI.
+✎ fill            metadata + screenshots + previews (native; iOS & macOS separate)
+✎ age-rating      set the age rating (AppInfo declaration)
+✎ review-contact  App Review contact from the gitignored files
+✎ accessibility   Accessibility Nutrition Labels (draft; VYDANNE_A11Y_PUBLISH=1 to publish once live)
   privacy         write the record + print the ASC-UI answers (API can't reach iris)
-  previews        upload App Preview videos (native chunked upload)
+✎ previews        upload App Preview videos (native chunked upload)
   iap             validate IAP fields; VYDANNE_FLATTEN=<png> flattens a screenshot to RGB
   compliance      generate the US encryption self-classification PDF
+  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
   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),
+✎ prerelease      upload the build for testers — .ipa to TestFlight (internal groups only),
                   or --store google: the .aab to a closed track. Refuses production/review.
   locales         UI -> ASC locale mapping + unsupported
   auth            which credentials resolved, and from where (masked) — run this on a 401
 credentials: env > .env cascade (.env, .env.<mode>, .env.local, .env.<mode>.local) > user config
   (\$VYDANNE_CONFIG_HOME, %APPDATA%\\vydanne or \$XDG_CONFIG_HOME/vydanne, ~/.appstoreconnect).
   NEVER the committed vydanne.config.mjs — run \`vydanne auth\` to see what resolved.
-toggles: VYDANNE_SKIP_METADATA / VYDANNE_SKIP_SCREENSHOTS (fill), VYDANNE_A11Y_PUBLISH (accessibility),
-         VYDANNE_PROFILE (named profile), VYDANNE_ENV (.env mode)`;
+toggles: VYDANNE_SKIP_METADATA / VYDANNE_SKIP_SCREENSHOTS (fill), VYDANNE_REPLACE=1 (fill/previews:
+         replace populated slots), VYDANNE_VERSION (prepare), VYDANNE_A11Y_PUBLISH (accessibility),
+         VYDANNE_PROFILE (named profile), VYDANNE_ENV (.env mode),
+         VYDANNE_COMMIT=1 (legacy alias for --apply — prefer the flag)`;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vydanne",
-  "version": "0.5.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, a diff of local-vs-store, and a preflight verifier that encodes the store gotchas. iOS/macOS via the ASC REST API; Android via the Play Developer Edits API (--store google).",
+  "version": "0.7.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",
     "google-play",
@@ -51,7 +51,8 @@
   "scripts": {
     "check:docs": "node scripts/check-docs.mjs",
     "check:types": "tsc --noEmit -p tsconfig.json && node scripts/check-types.mjs",
-    "prepublishOnly": "npm run check:docs && npm run check:types",
+    "check:config": "node scripts/check-config.mjs",
+    "prepublishOnly": "npm run check:docs && npm run check:types && npm run check:config",
     "release:patch": "node scripts/release.mjs patch",
     "release:minor": "node scripts/release.mjs minor",
     "release:major": "node scripts/release.mjs major"

package/src/client.mjs

@@ -1,24 +1,36 @@
 import { makeToken } from "./jwt.mjs";
+import { yellow } from "./util.mjs";
 
 const API = "https://api.appstoreconnect.apple.com";
 const IRIS = "https://appstoreconnect.apple.com/iris";
-const DEAD_VERSION = ["READY_FOR_SALE", "REMOVED_FROM_SALE", "REPLACED_WITH_NEW_VERSION"];
+// DEVELOPER_REMOVED_FROM_SALE is the state a version reaches when the DEVELOPER pulls it, as opposed to
+// Apple; both are shipped versions that will never become editable again, so both are dead here.
+const DEAD_VERSION = ["READY_FOR_SALE", "REMOVED_FROM_SALE", "DEVELOPER_REMOVED_FROM_SALE", "REPLACED_WITH_NEW_VERSION"];
 // READY_FOR_DISTRIBUTION is Apple's newer name for the LIVE app-info (they're migrating the
 // state vocabulary; versions still report appStoreState=READY_FOR_SALE). Without it here,
 // appInfo() treats the live record as editable and every name/subtitle PATCH comes back
 // ENTITY_ERROR.ATTRIBUTE.INVALID.INVALID_STATE — which fails the whole locale in `fill`,
 // release notes included, on any app that already has a version on sale.
-const DEAD_INFO = ["READY_FOR_SALE", "READY_FOR_DISTRIBUTION", "REPLACED_WITH_NEW_VERSION", "REMOVED_FROM_SALE"];
+const DEAD_INFO = ["READY_FOR_SALE", "READY_FOR_DISTRIBUTION", "REPLACED_WITH_NEW_VERSION", "REMOVED_FROM_SALE", "DEVELOPER_REMOVED_FROM_SALE"];
+
+// Anything that is not a read. ASC has no transaction to roll back — unlike Play, where an edit can be
+// discarded — so for Apple the only safe place to stand between a command and a live listing is here.
+const MUTATING = new Set(["POST", "PATCH", "PUT", "DELETE"]);
 
 // Thin ASC REST client. Encodes the gotchas: `iris` host (App Privacy 401s the JWT), version + app-info
 // fetched from the FULL list (get_edit filters out READY_FOR_REVIEW), and individual localization reads
 // (list endpoints return sparse/empty text).
 export class Client {
-  constructor({ keyId, issuerId }) {
+  constructor({ keyId, issuerId, dryRun = false }) {
     this.token = makeToken({ keyId, issuerId });
+    /** No mutating request leaves this process. Set by bin/ for a write command without `--apply`. */
+    this.dryRun = dryRun;
+    /** What a real run WOULD have sent, in order — the dry-run report, and the count bin/ prints. */
+    this.planned = [];
   }
 
   async req(method, urlPath, { iris = false, body, rawHeaders, rawBody } = {}) {
+    if (this.dryRun && MUTATING.has(method)) return this.#plan(method, urlPath, body);
     const headers = { Authorization: `Bearer ${this.token}` };
     if (body) headers["Content-Type"] = "application/json";
     Object.assign(headers, rawHeaders || {});
@@ -31,6 +43,31 @@ export class Client {
     return { status: res.status, json, text };
   }
 
+  /**
+   * Record a mutation instead of sending it, and hand back a response shaped like the one Apple would
+   * have returned.
+   *
+   * The shape matters as much as the refusal. A dry run that returned `null` here would crash the first
+   * caller that reads `.json.data.id` — and the operator would see one locale out of twenty, which is
+   * exactly the report they cannot act on. So a synthesised `data` carries the id the caller needs to
+   * keep going, and the run walks the WHOLE plan: every locale, every screenshot set, every field.
+   *
+   * The id is deliberately `dry-run-<n>` rather than a plausible-looking one — if it ever escapes into a
+   * URL, the request 404s loudly instead of touching some real record.
+   */
+  #plan(method, urlPath, body) {
+    const attributes = body?.data?.attributes || {};
+    const fields = Object.keys(attributes);
+    this.planned.push({ method, path: urlPath, attributes });
+    console.log(yellow(`      would ${method} ${urlPath}${fields.length ? ` — ${fields.join(", ")}` : ""}`));
+    return {
+      status: method === "DELETE" ? 204 : 200,
+      json: { data: { id: body?.data?.id || `dry-run-${this.planned.length}`, type: body?.data?.type, attributes } },
+      text: "",
+      dryRun: true,
+    };
+  }
+
   get(p, opts) { return this.req("GET", p, opts); }
   post(p, body) { return this.req("POST", p, { body }); }
   patch(p, body) { return this.req("PATCH", p, { body }); }
@@ -44,16 +81,50 @@ export class Client {
     return app;
   }
 
-  async editVersion(platform) {
+  /**
+   * The version being PREPARED — or null when there isn't one.
+   *
+   * This used to fall back to `data[0]`, the LIVE version, whenever nothing editable existed. The
+   * fallback was silent and it defeated its own callers: `fill`, `preflight`, `reviewContact` and
+   * `previews` each test `if (!v)` and report "no editable version", and not one of those branches could
+   * be reached on an app that had shipped once. What happened instead was worse than an error — `fill`
+   * aimed its description/whatsNew PATCHes at the listing customers were reading, and `preflight`
+   * validated that same live listing and printed "no blockers", calling a release submittable when
+   * there was nothing to submit.
+   *
+   * So a write is never handed the live version by default. Read-only commands (`inspect`, `diff`) pass
+   * `allowLive: true`, because "how does local compare with what is on sale" is a real question and that
+   * is the only version they could ask it about. Everything else gets null and says so — and now has
+   * `prepare` to point at, which is the command that makes an editable version exist.
+   */
+  async editVersion(platform, { allowLive = false } = {}) {
     const { json } = await this.get(`/v1/apps/${this.appId}/appStoreVersions?filter[platform]=${platform}&limit=10`);
     const data = json.data || [];
-    return data.find((v) => !DEAD_VERSION.includes(v.attributes.appStoreState)) || data[0] || null;
+    const editable = data.find((v) => !DEAD_VERSION.includes(v.attributes.appStoreState));
+    if (editable) return editable;
+    return allowLive ? data[0] || null : null;
   }
 
-  async appInfo() {
+  /**
+   * The app-info being PREPARED (name/subtitle, age rating live on it) — or null when there isn't one.
+   *
+   * Same disease, same cure as editVersion() above: this fell back to `data[0]` — the LIVE app-info —
+   * whenever nothing editable existed, and the fallback aimed writes at the record customers see. It is
+   * how the DEAD_INFO bug was found in the first place (every name/subtitle PATCH against the live
+   * record comes back INVALID_STATE and fails the whole locale in `fill`), and adding
+   * READY_FOR_DISTRIBUTION to DEAD_INFO only fixed the case where an editable sibling EXISTS to be
+   * found; the moment there is none, `|| data[0]` reintroduced exactly the state that comment warns
+   * about. Now a write gets null and a clear skip instead of twenty locales of ENTITY_ERROR.
+   *
+   * `allowLive` is for reads (`diff`), where "how does local compare with what is on sale" is the
+   * question being asked.
+   */
+  async appInfo({ allowLive = false } = {}) {
     const { json } = await this.get(`/v1/apps/${this.appId}/appInfos?limit=10`);
     const data = json.data || [];
-    return data.find((i) => !DEAD_INFO.includes(i.attributes.state)) || data[0] || null;
+    const editable = data.find((i) => !DEAD_INFO.includes(i.attributes.state));
+    if (editable) return editable;
+    return allowLive ? data[0] || null : null;
   }
 
   async versionLocalizations(versionId) {

package/src/commands/accessibility.mjs

@@ -107,8 +107,14 @@ export async function run(config, client) {
   console.log(`  declaring: ${claimed.length ? claimed.join(", ") : "(nothing)"}`);
 
   let gated = false;
+  // A PATCH that Apple refuses is a claim that never reached the store. Both failure paths below used
+  // to print red and `continue`, and the command still returned true — so `push` treated a family whose
+  // declaration never saved as a completed step. The `continue`s stay (one refused family must not hide
+  // the other three); the verdict now travels out with the return.
+  const failures = [];
   for (const family of Object.keys(UNAVAILABLE)) {
     const id = decls[family];
+    // Not a failure: Apple only holds declarations for the families the app actually ships on.
     if (!id) {
       console.error(yellow(`  no ${family} declaration`));
       continue;
@@ -119,6 +125,7 @@ export async function run(config, client) {
     });
     if (r.status >= 300) {
       console.error(red(`  ${family} draft ${r.status}`));
+      failures.push(`${family}: draft not saved (${r.status})`);
       continue;
     }
     if (publish) {
@@ -132,11 +139,17 @@ export async function run(config, client) {
         console.log(yellow(`  ${family}: draft saved — publish deferred (app not live yet)`));
       } else {
         console.error(red(`  ${family} publish ${p.status}`));
+        failures.push(`${family}: publish refused (${p.status})`);
       }
     } else {
       console.log(green(`  ${family}: draft saved`));
     }
   }
+  if (failures.length) {
+    console.error(red(`accessibility: ${failures.length} declaration(s) did not save:`));
+    for (const f of failures) console.error(`  ${red("x")} ${f}`);
+    return false;
+  }
   console.log(
     gated
       ? yellow("accessibility staged (DRAFT); re-run with VYDANNE_A11Y_PUBLISH=1 once the app is live")