vydanne 0.4.2 → 0.6.0

package/README.md

@@ -7,7 +7,9 @@ description, keywords, screenshots… once per language, twice per store, again
 box and the store quietly shows a blank page to half the world. Get a folder name wrong and the whole
 upload fails.
 
-vydanne does that typing for you, then **checks your work before Apple or Google does**.
+vydanne does that typing for you, then **checks your work before Apple or Google does** — and puts
+your build in front of testers on both stores. It stops at the one step that should stay a human's:
+it never submits for review, and never ships to the public.
 
 > *выданне* (Belarusian) — "publishing".
 
@@ -155,26 +157,58 @@ fastlane/metadata/en-US/keywords.txt
 ```sh
 npx vydanne preflight     # anything missing or too long?
 npx vydanne diff          # what exactly would change?
-npx vydanne fill          # do it
+npx vydanne fill          # DRY RUN — prints every write it would make
+npx vydanne fill --apply  # do it
 ```
 
 Run vydanne **from your project folder** — it finds everything relative to where you are.
 
 <br>
 
+## `--apply`, or nothing happens
+
+**Every command that can change a store is a dry run unless you pass `--apply`.** It reads the store,
+prints each write it would make, and sends nothing:
+
+```
+DRY RUN — 'fill' will not change App Store Connect. Add --apply to write.
+      would PATCH /v1/appStoreVersionLocalizations/ad2f… — description, keywords, whatsNew
+      …
+DRY RUN — 40 store write(s) withheld. Re-run with --apply to perform them.
+```
+
+The commands this applies to are marked `✎` in `vydanne help`: `fill`, `previews`, `age-rating`,
+`review-contact`, `accessibility`, `prerelease`. Everything else only reads, and ignores the flag.
+
+Two details worth knowing:
+
+- **A dry run walks the whole plan.** It does not stop at the first locale — the count at the end is the
+  number to compare against `diff`. "Nothing to write" and "nothing happened" are different sentences, and
+  only the first one means your local files already match the store.
+- **The two stores enforce it differently, deliberately.** Play builds the Edit and *validates it against
+  Google* for real, then discards it — so a dry run catches everything a commit would have caught. Apple
+  has no transaction to roll back, so there the block is at the HTTP layer: no `POST`/`PATCH`/`PUT`/
+  `DELETE` leaves the process at all. `prerelease` also refuses the `altool` upload, after validating the
+  archive.
+
+> 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.
+
+<br>
+
 ## What each command does
 
 | Command | In plain English |
 |---|---|
-| `preflight` | **Run this first.** Checks the listing is complete and nothing is over a character limit. Green means submittable. |
+| `preflight` | **Run this first.** Checks the listing is complete, nothing is over a character limit, and no locale mentions the other app store. Green means submittable. |
 | `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. |
+| `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. |
 | `locales` | Lists your languages and Apple's code for each — and warns about any language the App Store doesn't offer. |
 | `age-rating` | Sets the age rating. |
 | `review-contact` | Fills in the App Review contact details (who Apple calls if there's a problem). |
-| `accessibility` | Saves Accessibility Nutrition Labels. Stays a draft until your app is live. |
+| `accessibility` | Saves Accessibility Nutrition Labels from the `accessibility` block in your config. Stays a draft until your app is live. Refuses to run if you have not declared one — see below. |
 | `privacy` | Prints the privacy answers to paste into Apple's website (Apple's privacy section has no API). |
 | `iap` | Checks your in-app purchase text fits, and can strip transparency from an image. |
 | `compliance` | Generates the US encryption self-classification PDF that Apple asks for. |
@@ -182,6 +216,9 @@ Run vydanne **from your project folder** — it finds everything relative to whe
 
 For **Google Play**, add `--store google` to `inspect`, `diff`, `preflight`, `fill`, or `prerelease`.
 
+`fill`, `previews`, `age-rating`, `review-contact`, `accessibility` and `prerelease` change the store, so
+they need [`--apply`](#--apply-or-nothing-happens); without it they report and exit.
+
 <br>
 
 ## Google Play
@@ -191,19 +228,60 @@ Add a `google` block to your config and point `PLAY_JSON_KEY_FILE` at a service-
 
 ```sh
 npx vydanne preflight --store google
-npx vydanne fill --store google                    # dry run — shows what would change
-VYDANNE_COMMIT=1 npx vydanne fill --store google   # actually do it
-#   Windows PowerShell:  $env:VYDANNE_COMMIT = "1"; npx vydanne fill --store google
+npx vydanne fill --store google           # dry run — shows what would change
+npx vydanne fill --store google --apply   # actually do it
+```
+
+### `prerelease` — the build, to testers
+
+`fill` writes the *listing*; `prerelease` uploads the **binary** — to TestFlight on Apple, or to a
+closed testing track on Play. Neither submits anything for review.
+
+**Apple — TestFlight**
+
+```sh
+npx vydanne prerelease            # validate, upload, wait for processing
+```
+
+```js
+ios: {
+  ipa: "./dist",                  // a file, or a directory whose NEWEST .ipa is taken
+  testFlightGroup: "Internal",    // optional; INTERNAL groups only
+}
+```
+
+The App Store Connect REST API has never accepted a binary, so this is the one command that shells
+out — to `xcrun altool`, which ships with Xcode and authenticates from the same
+`~/.appstoreconnect/private_keys` key `vydanne auth` reports. That makes it **macOS-only**, which it
+checks up front. The archive is validated before it is uploaded, so the common refusals (bad
+entitlements, missing icons, a version Apple already holds) cost seconds rather than a full transfer.
+
+Build numbers come from the archive's own `CFBundleVersion` — re-uploading one Apple already holds
+fails loudly instead of quietly replacing a binary.
+
+It also **points the version you are preparing at the build it just uploaded**, which is the loop
+this command exists for:
+
+```sh
+npx vydanne prerelease      # version 1.1 -> build 66, off to testers
+# …find something, fix it, re-archive with a new build number…
+npx vydanne prerelease      # version 1.1: build 66 -> build 67
 ```
 
-### `prerelease` — the build, to a testing track
+The version→build relationship holds exactly one build, so re-running re-points it and there is
+nothing to clean up. A version that is no longer editable — `IN_REVIEW`, `READY_FOR_SALE` — is left
+alone and said so, because re-pointing it would mean withdrawing that submission, and that is a
+decision with reviewer-facing consequences.
+
+**External TestFlight groups are refused.** Distributing to them requires Beta App Review, which is a
+submission by another name; internal groups are the exact parallel of Play's `internal` track, and on
+a paid app they are the testers who install without buying it.
 
-`fill` writes the *listing*; `prerelease` uploads the **binary** to a **closed testing track** with
-release notes, all inside one edit transaction:
+**Google Play — a closed track**
 
 ```sh
-npx vydanne prerelease --store google                    # dry run
-VYDANNE_COMMIT=1 npx vydanne prerelease --store google   # publish to the track
+npx vydanne prerelease --store google           # dry run
+npx vydanne prerelease --store google --apply   # publish to the track
 ```
 
 ```js
@@ -227,7 +305,7 @@ Play's 500-char cap with a warning. The versionCode comes from the bundle's own
 numbering stays with the build and re-uploading a used code fails loudly instead of silently replacing a
 binary. Overrides: `VYDANNE_AAB`, `VYDANNE_TRACK`, `VYDANNE_RELEASE_NAME`.
 
-**Play is dry by default on purpose.** Nothing goes live until you add `VYDANNE_COMMIT=1`, so a
+**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
 (`zh-CN`, `iw-IL`) which are *not* Apple's — `vydanne locales` and the
 [layout guide](GETTING_STARTED.md#6-put-your-text-and-images-where-vydanne-looks) keep them straight.
@@ -261,6 +339,7 @@ don't have to learn them the hard way.
 | Screenshots with transparency get rejected | Converts them to RGB |
 | Once a version is *Ready for Review*, most tools can no longer edit it | Uses a method that still works |
 | Character limits (30 / 30 / 100 / 170; purchases 30 / 45) | Checked before upload, not after rejection |
+| One translation says "also on Google Play" → rejected under guideline 2.3.10 | Every locale is scanned before upload; `preflight` and `fill` both refuse |
 | Apple's privacy section can't be reached by any API key | Prints the exact answers to paste in |
 | Accessibility labels can't publish before launch | Saved as a draft automatically |
 | In-app purchases need **two** different images, easily confused | Labels both slots |
@@ -271,8 +350,12 @@ don't have to learn them the hard way.
 
 ## What vydanne will never do
 
-- **It never submits your app.** A human attaches the build and presses Submit. That's on purpose.
-- It doesn't build, sign, or upload your app binary.
+- **It never submits for review, and never ships to the public.** It *will* put a build in front of
+  your testers — TestFlight internal, or a Play closed track — and point the version you are
+  preparing at it. Pressing Submit, promoting to Play production, and distributing to external
+  TestFlight (which needs Beta App Review) all stay yours. Those are refusals, not flags: there is
+  no argument combination that reaches the public.
+- It doesn't build or sign your binary. It uploads the `.ipa` / `.aab` you already produced.
 - It doesn't create the app record — make that in App Store Connect / Play Console first.
 
 <br>
@@ -293,3 +376,56 @@ goes through the Google Play Developer **Edits** API.
 Releasing a new version: [RELEASING.md](RELEASING.md).
 
 MIT.
+
+
+### One store never mentions the other
+
+Both stores reject a listing that advertises the competing platform — Apple under App Review
+guideline **2.3.10** ("no names, icons, or imagery of other mobile platforms"), Google under its
+Store Listing and Promotion policy. It is an easy mistake to make and an expensive one to find: the
+two listings come from the same source copy, so a single translator writing "auch für Android"
+costs a review cycle, in one locale out of twenty, days later.
+
+`preflight` and `fill` both scan the local metadata before anything is uploaded, per locale, per
+field — store names, store URLs, and the other platform's device names, in Latin script and in the
+localized forms (安卓, Андроид, アンドロイド, …). A store's OWN platform is never flagged: "Android"
+belongs in a Play listing. Neither does the bare word "Play", which every game listing uses.
+
+Ambiguous words ("apple" in a game about fruit) are reported as warnings and never block. If one
+genuinely belongs in your copy:
+
+```js
+allowCrossStoreTerms: ["Apple"],
+```
+
+`VYDANNE_ALLOW_CROSS_STORE=1` overrides the whole check for one run.
+
+### Accessibility Nutrition Labels
+
+Every other thing vydanne writes is a *fact* about your app. This one is a **claim about its
+behaviour**, made to Apple — so the tool will not guess it for you.
+
+```js
+accessibility: {
+  voiceover: true,
+  voiceControl: true,
+  largerText: true,
+  sufficientContrast: true,
+  darkInterface: true,
+  differentiateWithoutColorAlone: true,
+  reducedMotion: true,
+  captions: false,
+  audioDescriptions: false,
+},
+```
+
+Every feature is stated explicitly. An omission would read as a quiet "no", which is just as
+unverified as a quiet "yes", so a partial block is rejected along with a missing one.
+
+Earlier versions applied one hardcoded matrix to every app, which meant an app inherited claims
+nobody had checked against it. At least one shipped app declared Larger Text support while its
+board glyphs scaled twice and grew off the high-contrast disc behind them. If you are upgrading,
+audit before you declare.
+
+Apple's platform caveats are still applied automatically: Larger Text does not exist on macOS and
+Voice Control does not exist on watchOS, so those are sent as false whatever you declare.

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
@@ -14,7 +14,11 @@ user needs screenshots or a preview video produced, that's zdymak's job, not vyd
 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.
+**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
 
@@ -162,32 +166,65 @@ who it's for → honest close. Keep it scannable; lead each bullet with the payo
 `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`.
-
-`prerelease` (**Play only**) uploads an `.aab` to a **closed testing track** with release notes, inside one
+(completeness gate + cross-store lint) · `inspect` · `auth` (what credentials resolved, and from where) · `locales` · `version`.
+
+**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.
+
+`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,
+which also makes it macOS-only. `.ipa` comes from `ios.ipa` / `VYDANNE_IPA` (a directory takes its
+newest), the build number from the archive's own `CFBundleVersion`, and `ios.testFlightGroup` may add
+it to an **internal** group. External groups are REFUSED — they need Beta App Review, a submission by
+another name — and App Store review is never submitted, mirroring the Play side refusing `production`.
+It then points the version being prepared AT that build, so the fix-and-re-upload loop is one command:
+re-running re-points (the relationship holds one build), while a version that is `IN_REVIEW` or
+`READY_FOR_SALE` is left alone, since re-pointing it would mean withdrawing a submission.
+
+With `--store google` it uploads an `.aab` to a **closed testing track** with release notes, inside one
 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_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.
+at Play's 500 chars. DRY by default; `--apply` publishes. The versionCode comes from the bundle itself,
+so re-uploading one fails loudly instead of silently replacing.
 
 `--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`**: `fill` · `previews` · `age-rating` ·
+`review-contact` · `accessibility` · `prerelease` (marked `✎` in `vydanne help`). 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` (previews) · `VYDANNE_FLATTEN=<png>` (iap) · `VYDANNE_A11Y_PUBLISH` (accessibility) ·
+`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**.
+out one copywriter agent per locale → media from zdymak → `fill` + `previews` + declarations (read the
+dry run, then re-run with `--apply`) → `diff` → `preflight` (must be green) → **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;
 
@@ -15,6 +16,15 @@ const cfgPath = i >= 0 ? argv[i + 1] : undefined;
 const si = argv.indexOf("--store");
 const store = si >= 0 ? argv[si + 1] : "apple";
 
+// 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)) {
     console.log(`vydanne ${VERSION}`);
@@ -53,16 +63,32 @@ try {
     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 ok = await run(cfg, client);
+    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());
@@ -74,25 +100,32 @@ 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.
+✎ 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
   inspect         read-only ASC state
   diff            show what differs between local (metadata/screenshots/previews) and ASC
   preflight       verify submission-completeness (the gotcha checker)
-  prerelease      --store google: upload the .aab to a closed testing track (refuses production)
+✎ 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)`;
+         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.4.2",
-  "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.6.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",

package/src/client.mjs

@@ -1,4 +1,5 @@
 import { makeToken } from "./jwt.mjs";
+import { yellow } from "./util.mjs";
 
 const API = "https://api.appstoreconnect.apple.com";
 const IRIS = "https://appstoreconnect.apple.com/iris";
@@ -10,15 +11,24 @@ const DEAD_VERSION = ["READY_FOR_SALE", "REMOVED_FROM_SALE", "REPLACED_WITH_NEW_
 // 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"];
 
+// 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 +41,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 }); }