vydanne 0.6.0 → 0.8.0

package/SKILL.md

@@ -11,8 +11,12 @@ 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.
+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
@@ -51,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.
@@ -94,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)
 
@@ -163,10 +210,22 @@ who it's for → honest close. Keep it scannable; lead each bullet with the payo
 ## B. Commands (push it)
 
 `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
+`previews` (App Preview videos) · `appinfo` (category + content rights) · `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 + cross-store lint) · `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
@@ -176,6 +235,43 @@ blocking; `allowCrossStoreTerms: [...]` in the config silences a specific one, a
 `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,
 which also makes it macOS-only. `.ipa` comes from `ios.ipa` / `VYDANNE_IPA` (a directory takes its
@@ -191,10 +287,14 @@ 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; `--apply` 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).
@@ -202,9 +302,10 @@ 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.
+**Every store-mutating command is a DRY RUN without `--apply`**: `prepare` · `push` · `fill` ·
+`previews` · `appinfo` · `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`.
@@ -217,14 +318,18 @@ through that client. **A new command that touches the store must be marked `writ
 `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_REPLACE` (previews) · `VYDANNE_FLATTEN=<png>` (iap) · `VYDANNE_A11Y_PUBLISH` (accessibility) ·
-`VYDANNE_COMMIT=1` (legacy alias for `--apply`; prefer the flag).
+`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 (read the
-dry run, then re-run with `--apply`) → `diff` → `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)
 
@@ -238,3 +343,21 @@ promo) · char limits (name/subtitle 30, keywords 100, promo 170; IAP name 30 /
 short 80 / full 4000) · **Play uses its OWN locale codes** · Play images push only when the local file
 exists, so a missing set never wipes the live one · Apple requires `name` when *creating* an app-info
 localization (409 otherwise).
+
+## The blockers that only appear on the Add for Review screen
+
+Apple checks these last, so a release can be green everywhere — metadata filled, screenshots up,
+build attached, `preflight` clean — and still stop dead with a list nobody can act on from a
+terminal. Four of the five are now vydanne's; the fifth is not reachable by any API.
+
+| blocker | who sets it |
+|---|---|
+| Privacy Policy URL | `fill` — `privacy_url.txt` per locale (an `appInfoLocalizations` field, so **every** locale needs it) |
+| Copyright | `prepare` — `<metadataDir>/copyright.txt`, on create **and** on reuse |
+| Primary category | `appinfo` — `categories` |
+| Content Rights | `appinfo` — `contentRights` |
+| **Price tier** | **App Store Connect UI.** Pricing is a separate agreement-bound surface; vydanne does not touch money. |
+
+`preflight` will NOT catch these. It verifies submission-completeness of the things it writes; a
+category it never sets is not a gap it knows to look for. Run `appinfo` once per app and the list
+shortens to the price.

package/bin/vydanne.mjs

@@ -15,6 +15,14 @@ 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
@@ -57,6 +65,9 @@ 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");
@@ -107,6 +118,15 @@ 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
@@ -115,6 +135,8 @@ usage: vydanne <command> [--apply] [--config vydanne.config.mjs]
 ✎ 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)
@@ -125,7 +147,8 @@ usage: vydanne <command> [--apply] [--config vydanne.config.mjs]
 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),
+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,6 +1,6 @@
 {
   "name": "vydanne",
-  "version": "0.6.0",
+  "version": "0.8.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",
@@ -51,7 +51,9 @@
   "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",
+    "verify": "npm run check:docs && npm run check:types && npm run check:config",
+    "prepublishOnly": "npm run verify",
     "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

@@ -3,13 +3,15 @@ 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.
@@ -79,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")

package/src/commands/ageRating.mjs

@@ -1,33 +1,106 @@
 import { green, yellow, red } from "../util.mjs";
 
-// Set the age rating via the AppInfo age-rating declaration. v1: "4+" — every content descriptor NONE.
-// (PATCH is partial; Apple recomputes 4+ from these.) app-info fetched from the full list (survives
-// READY_FOR_REVIEW).
+/**
+ * Set the age rating via the AppInfo age-rating declaration.
+ *
+ * `rating: "4+"` stays the shorthand it always was: every content descriptor NONE, every capability
+ * question false, which is what Apple recomputes 4+ from. Anything else is declared feature by feature
+ * in `ageRating`, merged over that all-NONE base — so an app with fantasy violence sets one key rather
+ * than restating twenty-seven.
+ *
+ * This used to refuse outright for any rating but 4+, which made the whole command — and `push`, which
+ * runs it as a step — unusable for any app with violence, gambling, chat or user-generated content.
+ * The base was always the general thing; only the door was missing.
+ */
+
+const N = "NONE";
+
+// Apple's 2025 age-rating schema. A PATCH must include ALL required fields (a partial set 409s), and
+// `ageRatingOverride` (deprecated) cannot be sent alongside `ageRatingOverrideV2` — so we send only V2.
+// Content descriptors are enums (NONE/INFREQUENT_OR_MILD/FREQUENT_OR_INTENSE); capability questions are
+// booleans. All benign here → 4+.
+const BASE = {
+  advertising: false, alcoholTobaccoOrDrugUseOrReferences: N, contests: N, gambling: false,
+  gamblingSimulated: N, gunsOrOtherWeapons: N, healthOrWellnessTopics: false, kidsAgeBand: null,
+  lootBox: false, medicalOrTreatmentInformation: N, messagingAndChat: false, parentalControls: false,
+  profanityOrCrudeHumor: N, ageAssurance: false, sexualContentGraphicAndNudity: N, sexualContentOrNudity: N,
+  socialMedia: false, socialMediaAgeRestricted: false, horrorOrFearThemes: N, matureOrSuggestiveThemes: N,
+  unrestrictedWebAccess: false, userGeneratedContent: false, violenceCartoonOrFantasy: N,
+  violenceRealisticProlongedGraphicOrSadistic: N, violenceRealistic: N, ageRatingOverrideV2: N,
+  koreaAgeRatingOverride: N,
+};
+
+/** Values Apple accepts for a content descriptor. `kidsAgeBand` and the overrides are checked separately. */
+const DESCRIPTOR_VALUES = new Set([N, "INFREQUENT_OR_MILD", "FREQUENT_OR_INTENSE"]);
+
+/**
+ * The attributes to send, or a human-readable problem.
+ *
+ * A declaration is validated against the schema BEFORE it reaches Apple, because the failure otherwise
+ * is a 409 naming a field the operator did not know existed. An unknown key is a typo — and a typo in
+ * this table means a descriptor silently stayed NONE, which is a rating that understates the app.
+ */
+export function resolveAttributes(config) {
+  const declared = config.ageRating;
+  if (!declared) {
+    if (config.rating === "4+") return { attributes: { ...BASE } };
+    return {
+      problem: [
+        `age-rating: rating is '${config.rating}', but nothing describes what makes it that.`,
+        "'4+' is the only rating that needs no detail (every descriptor NONE). For anything else,",
+        "declare the content Apple asks about — it computes the rating from these, you don't set it:",
+        "",
+        "  ageRating: {",
+        "    violenceCartoonOrFantasy: 'INFREQUENT_OR_MILD',",
+        "    userGeneratedContent: false,",
+        "  },",
+        "",
+        `Known keys: ${Object.keys(BASE).join(", ")}`,
+      ].join("\n"),
+    };
+  }
+  const unknown = Object.keys(declared).filter((k) => !(k in BASE));
+  if (unknown.length) {
+    return { problem: `age-rating: unknown key(s) ${unknown.join(", ")}. Known: ${Object.keys(BASE).join(", ")}` };
+  }
+  const bad = [];
+  for (const [k, v] of Object.entries(declared)) {
+    if (k === "kidsAgeBand") continue; // null | FIVE_AND_UNDER | SIX_TO_EIGHT | NINE_TO_ELEVEN
+    if (typeof BASE[k] === "boolean" && typeof v !== "boolean") bad.push(`${k} must be true or false`);
+    else if (typeof BASE[k] === "string" && !DESCRIPTOR_VALUES.has(v)) bad.push(`${k} must be one of ${[...DESCRIPTOR_VALUES].join(" / ")}`);
+  }
+  if (bad.length) return { problem: `age-rating: ${bad.join("; ")}` };
+  return { attributes: { ...BASE, ...declared } };
+}
+
 export async function run(config, client) {
-  if (config.rating !== "4+") { console.error(yellow(`age-rating: only '4+' (all-NONE) implemented; config=${config.rating}`)); return false; }
+  const { attributes, problem } = resolveAttributes(config);
+  if (problem) { console.error(red(problem)); return false; }
   await client.findApp(config.bundleId);
+  // No allowLive: this PATCHes the age-rating declaration, and the live app-info's declaration is not
+  // ours to aim a write at. The refusal below used to be unreachable — appInfo() handed back the live
+  // record instead of null, so the write was planned against it and Apple's INVALID_STATE was the
+  // first anyone heard of it.
   const info = await client.appInfo();
-  if (!info) { console.error(red("age-rating: no editable app info")); return false; }
+  if (!info) {
+    console.error(red("age-rating: no editable app info — refusing to write to the live record."));
+    console.error("  `vydanne prepare --apply` starts the next version, which makes app info editable again.");
+    return false;
+  }
   const { json } = await client.get(`/v1/appInfos/${info.id}/ageRatingDeclaration`);
   const id = json.data?.id;
   if (!id) { console.error(red("age-rating: no declaration")); return false; }
-  const N = "NONE";
-  // Apple's 2025 age-rating schema. A PATCH must include ALL required fields (a partial set 409s),
-  // and `ageRatingOverride` (deprecated) cannot be sent alongside `ageRatingOverrideV2` — so we send
-  // only V2. Content descriptors are enums (NONE); capability questions are booleans (false). All
-  // benign here → 4+.
-  const attributes = {
-    advertising: false, alcoholTobaccoOrDrugUseOrReferences: N, contests: N, gambling: false,
-    gamblingSimulated: N, gunsOrOtherWeapons: N, healthOrWellnessTopics: false, kidsAgeBand: null,
-    lootBox: false, medicalOrTreatmentInformation: N, messagingAndChat: false, parentalControls: false,
-    profanityOrCrudeHumor: N, ageAssurance: false, sexualContentGraphicAndNudity: N, sexualContentOrNudity: N,
-    socialMedia: false, socialMediaAgeRestricted: false, horrorOrFearThemes: N, matureOrSuggestiveThemes: N,
-    unrestrictedWebAccess: false, userGeneratedContent: false, violenceCartoonOrFantasy: N,
-    violenceRealisticProlongedGraphicOrSadistic: N, violenceRealistic: N, ageRatingOverrideV2: N,
-    koreaAgeRatingOverride: N,
-  };
+
+  // What is actually being asserted, printed before it is sent. Apple computes the rating from these,
+  // so the declared non-defaults ARE the rating — worth seeing in the log of the run that set them.
+  const declared = Object.entries(attributes).filter(([k, v]) => v !== BASE[k] || (v !== false && v !== N && v !== null));
+  console.log(`  declaring: ${declared.length ? declared.map(([k, v]) => `${k}=${v}`).join(", ") : "everything NONE (4+)"}`);
+
   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(client.dryRun ? yellow("age rating WOULD be set -> 4+") : green("age rating set -> 4+"));
+  // Apple decides the band from the descriptors; naming config.rating here reports what was ASKED for,
+  // which is the only thing this command controls.
+  const label = config.ageRating ? `${config.rating} (from the declared descriptors)` : "4+";
+  console.log(client.dryRun ? yellow(`age rating WOULD be set -> ${label}`) : green(`age rating set -> ${label}`));
   return true;
 }