vydanne 0.5.0 → 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,20 +157,52 @@ 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. |
@@ -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,9 +228,8 @@ 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
@@ -244,8 +280,8 @@ a paid app they are the testers who install without buying it.
 **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
@@ -269,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.
@@ -303,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 |
@@ -313,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>
@@ -337,6 +378,28 @@ 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

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,7 +166,15 @@ 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`.
+(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,
@@ -181,23 +193,38 @@ comes from `google.track` / `VYDANNE_TRACK`, default `internal`; the bundle from
 `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,17 +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 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,20 +100,25 @@ 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      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
@@ -96,5 +126,6 @@ credentials: env > .env cascade (.env, .env.<mode>, .env.local, .env.<mode>.loca
   (\$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.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.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 }); }

package/src/commands/ageRating.mjs

@@ -28,6 +28,6 @@ export async function run(config, client) {
   };
   const r = await client.patch(`/v1/ageRatingDeclarations/${id}`, { data: { type: "ageRatingDeclarations", id, attributes } });
   if (r.status >= 300) { console.error(red(`age-rating: ${r.status}: ${JSON.stringify(r.json).slice(0, 200)}`)); return false; }
-  console.log(green("age rating set -> 4+"));
+  console.log(client.dryRun ? yellow("age rating WOULD be set -> 4+") : green("age rating set -> 4+"));
   return true;
 }

package/src/commands/fill.mjs

@@ -3,6 +3,7 @@ import path from "node:path";
 import { green, yellow, red } from "../util.mjs";
 import { VALID } from "../locales.mjs";
 import { uploadAsset } from "../upload.mjs";
+import { reportCrossStore } from "../crossStore.mjs";
 
 // Version-localization fields (attr -> metadata filename) and AppInfo fields (name/subtitle, shared).
 const VERSION_TXT = { description: "description", keywords: "keywords", promotionalText: "promotional_text", whatsNew: "release_notes", marketingUrl: "marketing_url", supportUrl: "support_url" };
@@ -50,6 +51,16 @@ export async function run(config, client) {
   let ok = true; // a locale Apple refused must fail the command, not just print
   const skipMeta = process.env.VYDANNE_SKIP_METADATA === "1";
   const skipShots = process.env.VYDANNE_SKIP_SCREENSHOTS === "1";
+
+  // Checked here and not only in preflight, because preflight is something you REMEMBER to run and
+  // this is the thing that actually uploads. A cross-store reference costs a review cycle, and it
+  // is free to catch one function call earlier. VYDANNE_ALLOW_CROSS_STORE=1 is the deliberate
+  // override for the rare listing that genuinely needs the word.
+  if (!skipMeta && process.env.VYDANNE_ALLOW_CROSS_STORE !== "1"
+      && !reportCrossStore("apple", config.metadataDir, config.allowCrossStoreTerms)) {
+    console.error(red("fill: refusing to upload — fix the listing text, or set VYDANNE_ALLOW_CROSS_STORE=1."));
+    return false;
+  }
   const info = await client.appInfo();
   const infoLocs = info ? (await client.get(`/v1/appInfos/${info.id}/appInfoLocalizations?limit=200`)).json.data || [] : [];
 

package/src/commands/preflight.mjs

@@ -1,4 +1,5 @@
 import { green, red, yellow, LIMITS, VERSION_FIELDS } from "../util.mjs";
+import { reportCrossStore } from "../crossStore.mjs";
 
 // Verify a listing is submission-complete the CORRECT way — each localization read by id (not the sparse
 // list), char limits, primary-locale coverage, per-platform — and warn on the gotchas before ASC does.
@@ -34,6 +35,11 @@ export async function run(config, client) {
     }
   }
 
+  // Local copy that is about to be uploaded, checked before it can earn a rejection.
+  if (!reportCrossStore("apple", config.metadataDir, config.allowCrossStoreTerms)) {
+    problems.push("listing text references another mobile platform (see above)");
+  }
+
   console.log();
   if (!problems.length) console.log(green("preflight: no blockers"));
   else { console.log(red(`preflight: ${problems.length} blocker(s)`)); problems.forEach((p) => console.log(`  ${red("x")} ${p}`)); }

package/src/commands/prerelease.mjs

@@ -110,6 +110,14 @@ export async function run(config, client, credentials) {
     return false;
   }
 
+  // The binary upload is the one mutation that does NOT go through the ASC client, so the client-level
+  // dry-run gate cannot see it — it has to be refused here, or a dry run would ship a build to TestFlight.
+  // Validation above has already run, which is the useful half: exactly Play's "validate, then discard".
+  if (client.dryRun) {
+    console.log(yellow("  DRY RUN — archive validated, NOT uploaded. Re-run with --apply to send it to TestFlight."));
+    return true;
+  }
+
   try {
     await altool(["--upload-app", "-f", ipa, "-t", "ios"], credentials);
     console.log(green("  uploaded"));

package/src/commands/previews.mjs

@@ -24,17 +24,24 @@ export async function run(config, client) {
         }
         for (const p of existing) { // VYDANNE_REPLACE: drop the old preview so the new upload takes its place
           await client.del(`/v1/appPreviews/${p.id}`);
-          console.log(yellow(`  ${s.platform}/${code}/${s.type}: removed old preview ${p.id}`));
+          console.log(yellow(`  ${s.platform}/${code}/${s.type}: ${client.dryRun ? "would remove" : "removed"} old preview ${p.id}`));
         }
         if (!set) {
           const c = await client.post(`/v1/appPreviewSets`, { data: { type: "appPreviewSets", attributes: { previewType: s.type }, relationships: { appStoreVersionLocalization: { data: { type: "appStoreVersionLocalizations", id: loc.id } } } } });
           set = c.json.data;
         }
         const file = path.resolve(s.file);
-        console.log(`  ${s.platform}/${code}/${s.type}: uploading ${path.basename(file)}...`);
+        // A configured preview whose file is missing is the whole reason this is checked here: the
+        // upload would throw ENOENT mid-run, and in a DRY run it would otherwise look like a plan that
+        // works. Name it and move on, so one missing video doesn't hide the rest of the report.
+        if (!fs.existsSync(file)) {
+          console.error(red(`  ${s.platform}/${code}/${s.type}: ${path.relative(process.cwd(), file)} does not exist — nothing to upload`));
+          continue;
+        }
+        console.log(`  ${s.platform}/${code}/${s.type}: ${client.dryRun ? "would upload" : "uploading"} ${path.basename(file)}...`);
         const id = await uploadAsset(client, { type: "appPreviews", setType: "appPreviewSet", setId: set.id, filePath: file });
         await setPreviewPoster(client, id, s.poster);
-        console.log(green(`    done ${s.platform}/${code}/${s.type}`));
+        if (!client.dryRun) console.log(green(`    done ${s.platform}/${code}/${s.type}`));
       } catch (e) {
         console.error(red(`    error ${s.platform}/${code}/${s.type}: ${e.message}`));
       }

package/src/commands/reviewContact.mjs

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { green, red } from "../util.mjs";
+import { green, yellow, red } from "../util.mjs";
 
 // App Review contact from the GITIGNORED metadata/review_information/*.txt. PATCH (or POST) the review
 // detail directly — deliver can't do this cleanly pre-first-submission.
@@ -22,6 +22,7 @@ export async function run(config, client) {
     ? await client.patch(`/v1/appStoreReviewDetails/${existing.id}`, { data: { type: "appStoreReviewDetails", id: existing.id, attributes } })
     : await client.post(`/v1/appStoreReviewDetails`, { data: { type: "appStoreReviewDetails", attributes, relationships: { appStoreVersion: { data: { type: "appStoreVersions", id: v.id } } } } });
   if (r.status >= 300) { console.error(red(`review-contact: ${r.status}: ${JSON.stringify(r.json).slice(0, 200)}`)); return false; }
-  console.log(green(`review contact set -> ${attributes.contactFirstName} ${attributes.contactLastName} · ${attributes.contactPhone}`));
+  const who = `${attributes.contactFirstName} ${attributes.contactLastName} · ${attributes.contactPhone}`;
+  console.log(client.dryRun ? yellow(`review contact WOULD be set -> ${who}`) : green(`review contact set -> ${who}`));
   return true;
 }

package/src/config.mjs

@@ -6,7 +6,7 @@ import { resolveCredentials } from "./credentials.mjs";
 
 // The public config surface — the drift guards assert each key is documented (README/SKILL) and typed
 // (types/index.d.ts). Add a config knob → document + type it, or the guards fail before publish.
-export const CONFIG_KEYS = ["bundleId", "primaryLocale", "asc", "platforms", "uiLocales", "metadataDir", "rating", "privacy", "iaps", "previews", "export", "ios", "google", "accessibility"];
+export const CONFIG_KEYS = ["bundleId", "primaryLocale", "asc", "platforms", "uiLocales", "metadataDir", "rating", "privacy", "iaps", "previews", "export", "ios", "google", "accessibility", "allowCrossStoreTerms"];
 
 // One `vydanne.config.mjs` per app (ESM, like zdymak.config.mjs) — nothing hard-coded. Secrets stay out:
 // credentials resolve from the environment, a gitignored .env, or ~/.appstoreconnect/config.json (see
@@ -35,6 +35,8 @@ export async function loadConfig(p) {
     privacy: raw.privacy || { collected: ["CRASH_DATA", "PERFORMANCE_DATA"], tracking: false },
     iaps: raw.iaps || [],
     metadataDir: raw.metadataDir || "fastlane/metadata",
+    // Terms the cross-store check must not flag for this app (see src/crossStore.mjs).
+    allowCrossStoreTerms: raw.allowCrossStoreTerms || [],
     previews: raw.previews || null,
     export: raw.export || { encryption: "standard" },
     // Google Play. serviceAccountKey resolves from PLAY_JSON_KEY_FILE env first (keep the secret path out

package/src/crossStore.mjs

@@ -0,0 +1,151 @@
+import fs from "node:fs";
+import path from "node:path";
+import { red, yellow, green } from "./util.mjs";
+
+/**
+ * Refuse to send one store a listing that talks about the other one.
+ *
+ * WHY THIS IS IN THE TOOL AND NOT IN A CHECKLIST. Both stores forbid it, both enforce it by
+ * REJECTING a submission, and it is the single easiest thing to do by accident — because the two
+ * listings are written from the same source copy, by the same person, often by a translator who was
+ * handed an English master that happened to say "also on Google Play". Apple's App Review guideline
+ * 2.3.10 is explicit ("does not include names, icons, or imagery of other mobile platforms"), and
+ * Google Play's Store Listing and Promotion policy is the mirror of it. Nobody discovers this while
+ * writing the copy; they discover it days later, from a rejection, in one locale out of twenty.
+ *
+ * So it is checked HERE, against the local files that are about to be uploaded, before anything is
+ * sent. That is the only place it can be caught for free.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO. It does not flag a store's own platform — "Android" belongs in
+ * a Play listing and "iPhone" belongs in an App Store one. And it does not flag the bare word
+ * "Play", which is a verb every game listing on earth uses; only the store's actual name.
+ *
+ * Findings come in two tiers, because the certainty differs:
+ *   block — unambiguous: a store name, a store URL, a competing platform's device name.
+ *   warn  — a word that is usually a reference but sometimes just a word ("apple" in a game about
+ *           fruit). Reported, never fatal, and silenceable per app.
+ *
+ * An app with a genuine exception sets `allowCrossStoreTerms: ["..."]` in its vydanne config.
+ */
+
+/** Terms that must not appear in a listing for [store]. Ordered longest-first so the report names
+ *  the most specific match rather than a fragment of it. */
+const FOREIGN = {
+  apple: [
+    { term: "play.google.com", re: /play\.google\.com/i, level: "block" },
+    { term: "Google Play", re: /google\s*play/i, level: "block" },
+    { term: "Play Store", re: /\bplay[- ]?store\b/i, level: "block" },
+    { term: "Play Market", re: /\bplay[- ]?market\b/i, level: "block" },
+    { term: "Android", re: /\bandroid\b/i, level: "block" },
+    { term: "安卓", re: /安卓/, level: "block" },
+    { term: "アンドロイド", re: /アンドロイド/, level: "block" },
+    { term: "안드로이드", re: /안드로이드/, level: "block" },
+    { term: "Андроид/Андроїд", re: /андро[иї]д/i, level: "block" },
+    { term: "أندرويد", re: /أندرويد/, level: "block" },
+    { term: "אנדרואיד", re: /אנדרואיד/, level: "block" },
+    { term: "एंड्रॉइड", re: /एंड्रॉ?इड/, level: "block" },
+    { term: "APK", re: /\bapk\b/i, level: "warn" },
+    { term: "Chromebook", re: /\bchromebook\b/i, level: "warn" },
+  ],
+  google: [
+    { term: "apps.apple.com", re: /apps\.apple\.com/i, level: "block" },
+    { term: "App Store", re: /\bapp[- ]?store\b/i, level: "block" },
+    { term: "TestFlight", re: /\btestflight\b/i, level: "block" },
+    { term: "iPhone", re: /\biphone\b/i, level: "block" },
+    { term: "iPad", re: /\bipad(os)?\b/i, level: "block" },
+    { term: "iOS", re: /\bios\b/i, level: "block" },
+    { term: "Apple Arcade", re: /\bapple\s+arcade\b/i, level: "block" },
+    { term: "苹果", re: /苹果/, level: "block" },
+    { term: "애플", re: /애플/, level: "block" },
+    { term: "アップル", re: /アップル/, level: "block" },
+    // Sometimes a fruit, so it is reported rather than fatal.
+    { term: "Apple", re: /\bapple\b/i, level: "warn" },
+  ],
+};
+
+/** Local text a store actually uploads. Keys are the file basenames each fill() reads. */
+const APPLE_FILES = [
+  "name", "subtitle", "description", "keywords", "promotional_text",
+  "release_notes", "marketing_url", "support_url",
+];
+const PLAY_FILES = ["title", "short_description", "full_description"];
+
+/** One short line of context so a finding can be found and fixed without opening the file blind. */
+function excerpt(text, match) {
+  const at = text.toLowerCase().indexOf(match.toLowerCase());
+  if (at < 0) return "";
+  const from = Math.max(0, at - 28);
+  const to = Math.min(text.length, at + match.length + 28);
+  return `${from ? "…" : ""}${text.slice(from, to).replace(/\s+/g, " ")}${to < text.length ? "…" : ""}`;
+}
+
+/**
+ * Scan the local metadata tree for [store].
+ *
+ * @returns {{findings: Array, scanned: number}} findings carry {level, locale, field, term, excerpt}
+ */
+export function scanCrossStore(store, metadataDir, allow = []) {
+  const rules = FOREIGN[store].filter((r) => !allow.some((a) => a.toLowerCase() === r.term.toLowerCase()));
+  const files = store === "apple" ? APPLE_FILES : PLAY_FILES;
+  const findings = [];
+  let scanned = 0;
+  if (!metadataDir || !fs.existsSync(metadataDir)) return { findings, scanned };
+
+  for (const entry of fs.readdirSync(metadataDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    for (const field of files) {
+      const p = path.join(metadataDir, entry.name, `${field}.txt`);
+      if (!fs.existsSync(p)) continue;
+      const text = fs.readFileSync(p, "utf8");
+      scanned++;
+      for (const rule of rules) {
+        const m = text.match(rule.re);
+        if (!m) continue;
+        findings.push({
+          level: rule.level,
+          locale: entry.name,
+          field,
+          term: rule.term,
+          excerpt: excerpt(text, m[0]),
+        });
+      }
+    }
+  }
+  return { findings, scanned };
+}
+
+/** The other store's human name, for the message. */
+const OTHER = { apple: "Google Play / Android", google: "the App Store / iOS" };
+const GUIDELINE = {
+  apple: "App Review guideline 2.3.10 — metadata must not name other mobile platforms.",
+  google: "Google Play Store Listing and Promotion policy — no references to other app stores.",
+};
+
+/**
+ * Report findings. Returns false when something BLOCKING was found, so callers can refuse to upload.
+ *
+ * Printing every locale rather than the first is the point: this fails one translation at a time,
+ * and knowing it is 3 locales and not 20 is the difference between a fix and a re-translation.
+ */
+export function reportCrossStore(store, metadataDir, allow = []) {
+  const { findings, scanned } = scanCrossStore(store, metadataDir, allow);
+  if (!scanned) return true;
+
+  const blocking = findings.filter((f) => f.level === "block");
+  const warnings = findings.filter((f) => f.level === "warn");
+
+  if (blocking.length) {
+    console.log(red(`  cross-store: ${blocking.length} reference(s) to ${OTHER[store]} in listing text`));
+    console.log(`    ${GUIDELINE[store]}`);
+    for (const f of blocking) {
+      console.log(`    ${red("x")} ${f.locale}/${f.field}: "${f.term}"  ${f.excerpt}`);
+    }
+  }
+  for (const f of warnings) {
+    console.log(`    ${yellow("!")} ${f.locale}/${f.field}: "${f.term}" — check this is not a platform reference  ${f.excerpt}`);
+  }
+  if (!blocking.length && !warnings.length) {
+    console.log(green(`  cross-store: clean (${scanned} files)`));
+  }
+  return blocking.length === 0;
+}

package/src/play/client.mjs

@@ -9,13 +9,16 @@ const UPLOAD = "https://androidpublisher.googleapis.com/upload/androidpublisher/
 // transaction — insert an edit, mutate listings/images/details against it, then commit (all-or-nothing).
 // Nothing is live until commit; a dropped edit changes nothing. Image bytes go to the /upload endpoint.
 export class PlayClient {
-  static async create({ keyPath, packageName }) {
+  static async create({ keyPath, packageName, dryRun = false }) {
     const token = await getAccessToken(keyPath);
-    return new PlayClient(token, packageName);
+    return new PlayClient(token, packageName, dryRun);
   }
-  constructor(token, packageName) {
+  constructor(token, packageName, dryRun = false) {
     this.token = token;
     this.pkg = packageName;
+    // Gates the COMMIT, not the requests: the edit is still built and validated against Google for real,
+    // which is the whole advantage of Play's transaction over Apple's fire-and-forget PATCHes.
+    this.dryRun = dryRun;
   }
 
   async req(method, subpath, { body, base = BASE } = {}) {

package/src/play/commands/fill.mjs

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { green, yellow, red } from "../../util.mjs";
+import { reportCrossStore } from "../../crossStore.mjs";
 
 const FIELDS = [["title", "title"], ["shortDescription", "short_description"], ["fullDescription", "full_description"]];
 // Play image type -> local source (a dir of PNGs = screenshots; a single file = graphic). From zdymak.
@@ -16,12 +17,12 @@ const IMAGES = [
 
 // Push the Play listing (text + images) inside one Edit, then validate and commit. iOS/Android are separate
 // stores — this is the Google half. Images only touch a type whose local asset EXISTS (so a missing local
-// set never deletes the live one). VYDANNE_DRY=1 validates and discards without committing.
+// set never deletes the live one). Without `--apply` it validates and discards without committing.
 export async function run(config, client) {
   const g = config.google;
-  // SAFE BY DEFAULT: validate + discard the edit unless VYDANNE_COMMIT=1. A store-mutating commit must be
-  // an explicit opt-in — never the default (a stale/partial local set could otherwise clobber a live one).
-  const commit = process.env.VYDANNE_COMMIT === "1";
+  // SAFE BY DEFAULT: validate + discard the edit unless `--apply`. A store-mutating commit must be an
+  // explicit opt-in — never the default (a stale/partial local set could otherwise clobber a live one).
+  const commit = !client.dryRun;
   const localLangs = fs.existsSync(g.metadataDir)
     ? fs.readdirSync(g.metadataDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)
     : [];
@@ -31,6 +32,12 @@ export async function run(config, client) {
     return true;
   }
 
+  if (process.env.VYDANNE_ALLOW_CROSS_STORE !== "1"
+      && !reportCrossStore("google", g.metadataDir, config.allowCrossStoreTerms)) {
+    console.error(red("fill(play): refusing to upload — fix the listing text, or set VYDANNE_ALLOW_CROSS_STORE=1."));
+    return false;
+  }
+
   const editId = await client.newEdit();
   try {
     // Listing text
@@ -57,7 +64,7 @@ export async function run(config, client) {
 
     const v = await client.validate(editId);
     if (v.status >= 300) throw new Error(`validate ${v.status}: ${JSON.stringify(v.json).slice(0, 200)}`);
-    if (!commit) { await client.deleteEdit(editId); console.log(yellow("fill(play): validated — DRY (nothing changed). Review the above, then set VYDANNE_COMMIT=1 to commit.")); return true; }
+    if (!commit) { await client.deleteEdit(editId); console.log(yellow("fill(play): validated — DRY (nothing changed). Review the above, then re-run with --apply to commit.")); return true; }
     const co = await client.commit(editId);
     if (co.status >= 300) throw new Error(`commit ${co.status}: ${JSON.stringify(co.json).slice(0, 200)}`);
     console.log(green("fill(play): committed."));

package/src/play/commands/preflight.mjs

@@ -1,4 +1,5 @@
 import { green, red, yellow } from "../../util.mjs";
+import { reportCrossStore } from "../../crossStore.mjs";
 
 // Play listing limits.
 const LIMITS = { title: 30, shortDescription: 80, fullDescription: 4000 };
@@ -30,6 +31,10 @@ export async function run(config, client) {
   } finally {
     await client.deleteEdit(editId);
   }
+  if (!reportCrossStore("google", g.metadataDir, config.allowCrossStoreTerms)) {
+    problems.push("listing text references another app store (see above)");
+  }
+
   console.log();
   if (!problems.length) console.log(green("preflight: no blockers"));
   else { console.log(red(`preflight: ${problems.length} blocker(s)`)); problems.forEach((p) => console.log(`  ${red("x")} ${p}`)); }

package/src/play/commands/prerelease.mjs

@@ -79,9 +79,9 @@ export async function run(config, client) {
     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 (process.env.VYDANNE_COMMIT !== "1") {
+    if (client.dryRun) {
       await client.deleteEdit(editId);
-      console.log(yellow(`\n  DRY RUN — edit discarded, nothing changed. Re-run with VYDANNE_COMMIT=1 to publish to "${track}".`));
+      console.log(yellow(`\n  DRY RUN — edit discarded, nothing changed. Re-run with --apply to publish to "${track}".`));
       return true;
     }
     const res = await client.commit(editId);

package/src/registry.mjs

@@ -1,14 +1,21 @@
 // The canonical command registry — the single source of vydanne's public commands. bin/ dispatches from
 // this, and the drift guards (scripts/check-docs.mjs, scripts/check-types.mjs) assert every command is
 // documented in README/SKILL and typed in types/index.d.ts. Add a command here → the guards force it into
-// the docs + types before publish.  name -> { mod: <file in src/commands>, client: needs an ASC client }
+// the docs + types before publish.
+//
+//   name -> { mod: <file in src/commands>, client: needs an ASC client, writes: mutates the STORE }
+//
+// `writes` is what makes a command dry-run unless `--apply` is passed, so it is a safety declaration, not
+// a label: mark a new command `writes: true` the moment it can change anything on the store side. It means
+// the STORE specifically — `privacy` and `compliance` write local files (a record, a PDF) and are not
+// marked, because a dry run that refused to produce a local artefact would just be broken.
 export const COMMANDS = {
-  fill: { mod: "fill", client: true },
-  "age-rating": { mod: "ageRating", client: true },
-  "review-contact": { mod: "reviewContact", client: true },
-  accessibility: { mod: "accessibility", client: true },
+  fill: { mod: "fill", client: true, writes: true },
+  "age-rating": { mod: "ageRating", client: true, writes: true },
+  "review-contact": { mod: "reviewContact", client: true, writes: true },
+  accessibility: { mod: "accessibility", client: true, writes: true },
   privacy: { mod: "privacy", client: false },
-  previews: { mod: "previews", client: true },
+  previews: { mod: "previews", client: true, writes: true },
   iap: { mod: "iap", client: false },
   compliance: { mod: "compliance", client: false },
   inspect: { mod: "inspect", client: true },
@@ -16,7 +23,7 @@ export const COMMANDS = {
   preflight: { mod: "preflight", client: true },
   // Uploads the .ipa to TestFlight. Needs the credentials as well as the client: the REST API
   // cannot carry a binary, so this one shells out to `xcrun altool`, which authenticates itself.
-  prerelease: { mod: "prerelease", client: true, credentials: true },
+  prerelease: { mod: "prerelease", client: true, credentials: true, writes: true },
 };
 
 // Commands available for `--store google` (Google Play). Same names as the Apple ones, different backend
@@ -25,8 +32,8 @@ export const PLAY_COMMANDS = {
   inspect: { mod: "inspect" },
   preflight: { mod: "preflight" },
   diff: { mod: "diff" },
-  fill: { mod: "fill" },
-  prerelease: { mod: "prerelease" },
+  fill: { mod: "fill", writes: true },
+  prerelease: { mod: "prerelease", writes: true },
 };
 
 // Full public command surface (the module-dispatched ones above + the three handled inline in bin/).

package/src/upload.mjs

@@ -33,6 +33,9 @@ export async function uploadAsset(client, { type, setType, setId, filePath }) {
 
 // Previews process asynchronously — poll until Apple exposes videoUrl, then set the poster frame.
 export async function setPreviewPoster(client, previewId, frameTimeCode, { tries = 30, delayMs = 15000 } = {}) {
+  // In a dry run the preview was never created, so `previewId` is a synthetic `dry-run-<n>` and this would
+  // poll a 404 for seven and a half minutes before giving up.
+  if (client.dryRun) return true;
   for (let i = 0; i < tries; i++) {
     const { json } = await client.get(`/v1/appPreviews/${previewId}`);
     if (json.data?.attributes?.videoUrl) {

package/types/index.d.ts

@@ -139,18 +139,32 @@ export interface VydanneConfig {
   ios?: IosConfig;
   /** Google Play (`--store google`): listings, screenshots, feature graphic via the Edits API. */
   google?: GoogleConfig;
+  /**
+   * Terms the cross-store check must not flag for this app.
+   *
+   * `preflight` and `fill` refuse listing text that names the OTHER mobile platform — App Review
+   * guideline 2.3.10 and Google Play's Store Listing and Promotion policy both reject it. Use this
+   * only for a word that genuinely belongs in your copy (a game about fruit really does say
+   * "apple"); it is not a way to ship a store name.
+   */
+  allowCrossStoreTerms?: string[];
 }
 
 /** Thin ASC REST client (native fetch + ES256 JWT). */
 export declare class Client {
-  constructor(opts: { keyId: string; issuerId: string });
+  constructor(opts: { keyId: string; issuerId: string; dryRun?: boolean });
   token: string;
   appId?: string;
   app?: unknown;
+  /** When true, no POST/PATCH/PUT/DELETE leaves the process — each is recorded in `planned` instead. */
+  dryRun: boolean;
+  /** The mutations a real run would have sent, in order. Populated only while `dryRun`. */
+  planned: Array<{ method: string; path: string; attributes: Record<string, unknown> }>;
   findApp(bundleId: string): Promise<unknown>;
   get(path: string, opts?: { iris?: boolean }): Promise<{ status: number; json: any }>;
   post(path: string, body: unknown): Promise<{ status: number; json: any }>;
   patch(path: string, body: unknown): Promise<{ status: number; json: any }>;
+  del(path: string): Promise<{ status: number; json: any }>;
   editVersion(platform: Platform): Promise<any>;
   appInfo(): Promise<any>;
   versionLocalizations(versionId: string): Promise<any[]>;
@@ -164,6 +178,7 @@ export declare function toAsc(code: string): string | null;
 export declare const VALID: Set<string>;
 export declare const CONFIG_KEYS: readonly string[];
 export declare const COMMAND_NAMES: readonly CommandName[];
-export declare const COMMANDS: Record<string, { mod: string; client: boolean }>;
+/** `writes` marks a command that mutates the STORE — those are dry-run unless the CLI gets `--apply`. */
+export declare const COMMANDS: Record<string, { mod: string; client: boolean; writes?: boolean }>;
 
 export default VydanneConfig;