vydanne 0.4.2 → 0.5.0

package/README.md

@@ -174,7 +174,7 @@ Run vydanne **from your project folder** — it finds everything relative to whe
 | `locales` | Lists your languages and Apple's code for each — and warns about any language the App Store doesn't offer. |
 | `age-rating` | Sets the age rating. |
 | `review-contact` | Fills in the App Review contact details (who Apple calls if there's a problem). |
-| `accessibility` | Saves Accessibility Nutrition Labels. Stays a draft until your app is live. |
+| `accessibility` | Saves Accessibility Nutrition Labels from the `accessibility` block in your config. Stays a draft until your app is live. Refuses to run if you have not declared one — see below. |
 | `privacy` | Prints the privacy answers to paste into Apple's website (Apple's privacy section has no API). |
 | `iap` | Checks your in-app purchase text fits, and can strip transparency from an image. |
 | `compliance` | Generates the US encryption self-classification PDF that Apple asks for. |
@@ -196,10 +196,52 @@ VYDANNE_COMMIT=1 npx vydanne fill --store google   # actually do it
 #   Windows PowerShell:  $env:VYDANNE_COMMIT = "1"; npx vydanne fill --store google
 ```
 
-### `prerelease` — the build, to a testing track
+### `prerelease` — the build, to testers
 
-`fill` writes the *listing*; `prerelease` uploads the **binary** to a **closed testing track** with
-release notes, all inside one edit transaction:
+`fill` writes the *listing*; `prerelease` uploads the **binary** — to TestFlight on Apple, or to a
+closed testing track on Play. Neither submits anything for review.
+
+**Apple — TestFlight**
+
+```sh
+npx vydanne prerelease            # validate, upload, wait for processing
+```
+
+```js
+ios: {
+  ipa: "./dist",                  // a file, or a directory whose NEWEST .ipa is taken
+  testFlightGroup: "Internal",    // optional; INTERNAL groups only
+}
+```
+
+The App Store Connect REST API has never accepted a binary, so this is the one command that shells
+out — to `xcrun altool`, which ships with Xcode and authenticates from the same
+`~/.appstoreconnect/private_keys` key `vydanne auth` reports. That makes it **macOS-only**, which it
+checks up front. The archive is validated before it is uploaded, so the common refusals (bad
+entitlements, missing icons, a version Apple already holds) cost seconds rather than a full transfer.
+
+Build numbers come from the archive's own `CFBundleVersion` — re-uploading one Apple already holds
+fails loudly instead of quietly replacing a binary.
+
+It also **points the version you are preparing at the build it just uploaded**, which is the loop
+this command exists for:
+
+```sh
+npx vydanne prerelease      # version 1.1 -> build 66, off to testers
+# …find something, fix it, re-archive with a new build number…
+npx vydanne prerelease      # version 1.1: build 66 -> build 67
+```
+
+The version→build relationship holds exactly one build, so re-running re-points it and there is
+nothing to clean up. A version that is no longer editable — `IN_REVIEW`, `READY_FOR_SALE` — is left
+alone and said so, because re-pointing it would mean withdrawing that submission, and that is a
+decision with reviewer-facing consequences.
+
+**External TestFlight groups are refused.** Distributing to them requires Beta App Review, which is a
+submission by another name; internal groups are the exact parallel of Play's `internal` track, and on
+a paid app they are the testers who install without buying it.
+
+**Google Play — a closed track**
 
 ```sh
 npx vydanne prerelease --store google                    # dry run
@@ -293,3 +335,34 @@ goes through the Google Play Developer **Edits** API.
 Releasing a new version: [RELEASING.md](RELEASING.md).
 
 MIT.
+
+
+### Accessibility Nutrition Labels
+
+Every other thing vydanne writes is a *fact* about your app. This one is a **claim about its
+behaviour**, made to Apple — so the tool will not guess it for you.
+
+```js
+accessibility: {
+  voiceover: true,
+  voiceControl: true,
+  largerText: true,
+  sufficientContrast: true,
+  darkInterface: true,
+  differentiateWithoutColorAlone: true,
+  reducedMotion: true,
+  captions: false,
+  audioDescriptions: false,
+},
+```
+
+Every feature is stated explicitly. An omission would read as a quiet "no", which is just as
+unverified as a quiet "yes", so a partial block is rejected along with a missing one.
+
+Earlier versions applied one hardcoded matrix to every app, which meant an app inherited claims
+nobody had checked against it. At least one shipped app declared Larger Text support while its
+board glyphs scaled twice and grew off the high-contrast disc behind them. If you are upgrading,
+audit before you declare.
+
+Apple's platform caveats are still applied automatically: Larger Text does not exist on macOS and
+Voice Control does not exist on watchOS, so those are sent as false whatever you declare.

package/SKILL.md

@@ -164,7 +164,17 @@ live) · `privacy` (prints answers for the UI — the API can't reach Apple's ir
 RGB flatten) · `compliance` (US self-classification PDF) · `diff` (what differs vs live) · `preflight`
 (completeness gate) · `inspect` · `auth` (what credentials resolved, and from where) · `locales` · `version`.
 
-`prerelease` (**Play only**) uploads an `.aab` to a **closed testing track** with release notes, inside one
+`prerelease` uploads the BUILD. On Apple it validates and uploads the `.ipa` to **TestFlight** via
+`xcrun altool` — the one command that shells out, because the ASC REST API has never carried a binary,
+which also makes it macOS-only. `.ipa` comes from `ios.ipa` / `VYDANNE_IPA` (a directory takes its
+newest), the build number from the archive's own `CFBundleVersion`, and `ios.testFlightGroup` may add
+it to an **internal** group. External groups are REFUSED — they need Beta App Review, a submission by
+another name — and App Store review is never submitted, mirroring the Play side refusing `production`.
+It then points the version being prepared AT that build, so the fix-and-re-upload loop is one command:
+re-running re-points (the relationship holds one build), while a version that is `IN_REVIEW` or
+`READY_FOR_SALE` is left alone, since re-pointing it would mean withdrawing a submission.
+
+With `--store google` it uploads an `.aab` to a **closed testing track** with release notes, inside one
 edit transaction. `production` is REFUSED — not flag-gated — so no argument combination ships to the
 public; promoting the tested build stays a human's job, mirroring the Apple side never submitting. Track
 comes from `google.track` / `VYDANNE_TRACK`, default `internal`; the bundle from `google.aab` /

package/bin/vydanne.mjs

@@ -62,7 +62,8 @@ try {
     const spec = COMMANDS[cmd];
     const { run } = await import(`../src/commands/${spec.mod}.mjs`);
     const client = spec.client ? new Client({ keyId: cfg.keyId, issuerId: cfg.issuerId }) : null;
-    const ok = await run(cfg, client);
+    // 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);
     if (ok === false) process.exit(1);
   } else {
     console.error(usage());
@@ -87,7 +88,8 @@ usage: vydanne <command> [--config vydanne.config.mjs]
   inspect         read-only ASC state
   diff            show what differs between local (metadata/screenshots/previews) and ASC
   preflight       verify submission-completeness (the gotcha checker)
-  prerelease      --store google: upload the .aab to a closed testing track (refuses production)
+  prerelease      upload the build for testers — .ipa to TestFlight (internal groups only),
+                  or --store google: the .aab to a closed track. Refuses production/review.
   locales         UI -> ASC locale mapping + unsupported
   auth            which credentials resolved, and from where (masked) — run this on a 401
 credentials: env > .env cascade (.env, .env.<mode>, .env.local, .env.<mode>.local) > user config

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vydanne",
-  "version": "0.4.2",
+  "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).",
   "keywords": [
     "app-store-connect",

package/src/commands/accessibility.mjs

@@ -1,36 +1,146 @@
 import { green, yellow, red } from "../util.mjs";
 
-const T = true, F = false;
-// Honest DoD-backed matrix; Apple caveats: Larger Text N/A on Mac, Voice Control N/A on Watch, no video →
-// no captions/AD. DRAFT-safe; VYDANNE_A11Y_PUBLISH=1 publishes, but Apple 409s publish until the app is live.
-const MATRIX = {
-  IPHONE: { supportsVoiceover: T, supportsVoiceControl: T, supportsLargerText: T, supportsSufficientContrast: T, supportsDarkInterface: T, supportsDifferentiateWithoutColorAlone: T, supportsReducedMotion: T, supportsCaptions: F, supportsAudioDescriptions: F },
-  IPAD: { supportsVoiceover: T, supportsVoiceControl: T, supportsLargerText: T, supportsSufficientContrast: T, supportsDarkInterface: T, supportsDifferentiateWithoutColorAlone: T, supportsReducedMotion: T, supportsCaptions: F, supportsAudioDescriptions: F },
-  MAC: { supportsVoiceover: T, supportsVoiceControl: T, supportsSufficientContrast: T, supportsDarkInterface: T, supportsDifferentiateWithoutColorAlone: T, supportsReducedMotion: T, supportsCaptions: F, supportsAudioDescriptions: F },
-  APPLE_WATCH: { supportsVoiceover: T, supportsLargerText: T, supportsSufficientContrast: T, supportsDarkInterface: T, supportsDifferentiateWithoutColorAlone: T, supportsReducedMotion: T, supportsCaptions: F, supportsAudioDescriptions: F },
+/**
+ * Accessibility Nutrition Labels.
+ *
+ * These used to come from a hardcoded matrix that said the same thing for every app the tool was
+ * pointed at. That is the wrong shape for this one command. Everything else vydanne writes is a
+ * FACT about an app — its name, its price, the data it collects — but this is a CLAIM about
+ * behaviour, made to Apple, and the tool had no way of knowing whether it was true. It asserted
+ * VoiceOver, Voice Control and Larger Text support for apps nobody had audited, and at least one
+ * of them did not honour Larger Text at all: its board glyphs scaled twice and grew off the
+ * high-contrast disc drawn behind them.
+ *
+ * So the app declares it, feature by feature, in `vydanne.config.mjs`. Silence is not consent — an
+ * app with no `accessibility` block gets an error, not a default, because "nobody wrote this down"
+ * must never become "supports everything".
+ *
+ * Apple's platform caveats are still applied here, because they are facts about the platforms
+ * rather than about any app: Larger Text does not exist on macOS and Voice Control does not exist
+ * on watchOS, so those are forced false regardless of what an app claims.
+ */
+
+/** Config key -> the ASC attribute it sets. */
+const FEATURES = {
+  voiceover: "supportsVoiceover",
+  voiceControl: "supportsVoiceControl",
+  largerText: "supportsLargerText",
+  sufficientContrast: "supportsSufficientContrast",
+  darkInterface: "supportsDarkInterface",
+  differentiateWithoutColorAlone: "supportsDifferentiateWithoutColorAlone",
+  reducedMotion: "supportsReducedMotion",
+  captions: "supportsCaptions",
+  audioDescriptions: "supportsAudioDescriptions",
+};
+
+/** Features Apple does not offer on a device family — never sent, whatever the app declares. */
+const UNAVAILABLE = {
+  IPHONE: [],
+  IPAD: [],
+  MAC: ["largerText"],
+  APPLE_WATCH: ["voiceControl"],
 };
 
+const EXAMPLE = `  accessibility: {
+    voiceover: true,
+    voiceControl: true,
+    largerText: true,
+    sufficientContrast: true,
+    darkInterface: true,
+    differentiateWithoutColorAlone: true,
+    reducedMotion: true,
+    captions: false,
+    audioDescriptions: false,
+  },`;
+
+/** Turn the app's declaration into the attributes for one device family. */
+function attributesFor(declared, family) {
+  const out = {};
+  for (const [key, attribute] of Object.entries(FEATURES)) {
+    out[attribute] = UNAVAILABLE[family].includes(key) ? false : declared[key] === true;
+  }
+  return out;
+}
+
+/** Returns a human-readable problem, or null when the declaration is usable. */
+export function validate(config) {
+  const declared = config.accessibility;
+  if (!declared || typeof declared !== "object") {
+    return [
+      "accessibility: missing.",
+      "This command publishes CLAIMS about your app's behaviour to Apple, so it will not guess.",
+      "Declare what you have actually verified:",
+      "",
+      EXAMPLE,
+    ].join("\n");
+  }
+  const unknown = Object.keys(declared).filter((k) => !(k in FEATURES));
+  if (unknown.length) {
+    return `accessibility: unknown feature(s) ${unknown.join(", ")}. Known: ${Object.keys(FEATURES).join(", ")}`;
+  }
+  const missing = Object.keys(FEATURES).filter((k) => typeof declared[k] !== "boolean");
+  if (missing.length) {
+    return [
+      `accessibility: ${missing.join(", ")} must be declared true or false.`,
+      "Every feature is stated explicitly — an omission would read as a quiet 'no', which is just",
+      "as unverified as a quiet 'yes'.",
+    ].join("\n");
+  }
+  return null;
+}
+
 export async function run(config, client) {
+  const problem = validate(config);
+  if (problem) {
+    console.error(red(problem));
+    return false;
+  }
+  const declared = config.accessibility;
+
   await client.findApp(config.bundleId);
   const publish = process.env.VYDANNE_A11Y_PUBLISH === "1";
   const { json } = await client.get(`/v1/apps/${client.appId}/accessibilityDeclarations?limit=50`);
   const decls = {};
   for (const d of json.data || []) decls[d.attributes.deviceFamily] = d.id;
+
+  const claimed = Object.keys(FEATURES).filter((k) => declared[k]);
+  console.log(`  declaring: ${claimed.length ? claimed.join(", ") : "(nothing)"}`);
+
   let gated = false;
-  for (const [fam, attributes] of Object.entries(MATRIX)) {
-    const id = decls[fam];
-    if (!id) { console.error(yellow(`  no ${fam} declaration`)); continue; }
-    const r = await client.patch(`/v1/accessibilityDeclarations/${id}`, { data: { type: "accessibilityDeclarations", id, attributes } });
-    if (r.status >= 300) { console.error(red(`  ${fam} draft ${r.status}`)); continue; }
+  for (const family of Object.keys(UNAVAILABLE)) {
+    const id = decls[family];
+    if (!id) {
+      console.error(yellow(`  no ${family} declaration`));
+      continue;
+    }
+    const attributes = attributesFor(declared, family);
+    const r = await client.patch(`/v1/accessibilityDeclarations/${id}`, {
+      data: { type: "accessibilityDeclarations", id, attributes },
+    });
+    if (r.status >= 300) {
+      console.error(red(`  ${family} draft ${r.status}`));
+      continue;
+    }
     if (publish) {
-      const p = await client.patch(`/v1/accessibilityDeclarations/${id}`, { data: { type: "accessibilityDeclarations", id, attributes: { publish: true } } });
-      if (p.status < 300) console.log(green(`  ${fam}: PUBLISHED`));
-      else if (JSON.stringify(p.json).includes("CANNOT_PUBLISH_APP_MUST_BE_AVAILABLE")) { gated = true; console.log(yellow(`  ${fam}: draft saved — publish deferred (app not live yet)`)); }
-      else console.error(red(`  ${fam} publish ${p.status}`));
+      const p = await client.patch(`/v1/accessibilityDeclarations/${id}`, {
+        data: { type: "accessibilityDeclarations", id, attributes: { publish: true } },
+      });
+      if (p.status < 300) {
+        console.log(green(`  ${family}: PUBLISHED`));
+      } else if (JSON.stringify(p.json).includes("CANNOT_PUBLISH_APP_MUST_BE_AVAILABLE")) {
+        gated = true;
+        console.log(yellow(`  ${family}: draft saved — publish deferred (app not live yet)`));
+      } else {
+        console.error(red(`  ${family} publish ${p.status}`));
+      }
     } else {
-      console.log(green(`  ${fam}: draft saved`));
+      console.log(green(`  ${family}: draft saved`));
     }
   }
-  console.log(gated ? yellow("accessibility staged (DRAFT); re-run with VYDANNE_A11Y_PUBLISH=1 once the app is live") : "accessibility done");
+  console.log(
+    gated
+      ? yellow("accessibility staged (DRAFT); re-run with VYDANNE_A11Y_PUBLISH=1 once the app is live")
+      : "accessibility done",
+  );
   return true;
 }

package/src/commands/prerelease.mjs

@@ -0,0 +1,259 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { green, yellow, red } from "../util.mjs";
+
+const run_ = promisify(execFile);
+
+/**
+ * Upload a build to App Store Connect, for TestFlight.
+ *
+ * The Play side has had this since the beginning; Apple did not, so the one step that actually
+ * moves a binary had to be done by hand for iOS while Android was a command. This closes that,
+ * with the same refusals.
+ *
+ * **The REST API cannot carry a binary.** Everything else vydanne does is ASC REST over a JWT it
+ * mints itself, but Apple has never exposed binary upload there — `altool` and Transporter are the
+ * only supported paths. So this shells out to `xcrun altool`, which is not a departure from "no
+ * fastlane/Ruby": altool ships with Xcode, and you already needed Xcode to produce the .ipa this
+ * command uploads. It does mean the command is macOS-only, which is checked up front rather than
+ * discovered as a confusing spawn error.
+ *
+ * WHAT IT REFUSES, mirroring `--store google`:
+ *  - it does not submit for App Store review. That release is a human's to make, and there is no
+ *    arrangement of arguments here that reaches the public.
+ *  - it does not touch EXTERNAL TestFlight groups. External testing needs Beta App Review, which
+ *    is a submission by another name. Internal groups only — the exact parallel of Play's
+ *    `internal` track, and for the same practical reason: on a PAID app, internal testers are the
+ *    ones who install without buying it.
+ *
+ * Apple assigns nothing: the build number comes from the archive's own CFBundleVersion, so build
+ * numbering stays with the build, and re-uploading one Apple already holds fails loudly instead of
+ * silently replacing a binary.
+ *
+ * WHAT IT ALSO DOES: points the version you are preparing AT the build it just uploaded. That is
+ * the loop this command exists to serve — ship a build to testers, find something, fix it, upload
+ * again — and without it the version keeps whatever build was attached first while TestFlight
+ * quietly moves on. Re-running simply re-points: the relationship is a single build, so the newest
+ * upload replaces the old one and there is nothing to clean up.
+ *
+ * It will not re-point a version that is no longer editable (in review, or already released),
+ * because Apple would need that version withdrawn first — a decision with reviewer-facing
+ * consequences, and therefore the operator's.
+ */
+
+/** How long to watch processing before handing back. Apple is usually minutes, occasionally not. */
+const PROCESS_TIMEOUT_MS = 15 * 60 * 1000;
+const POLL_MS = 20 * 1000;
+
+/** Newest `.ipa` in a directory, or the file itself. Mirrors how `google.aab` is resolved. */
+export function resolveIpa(spec) {
+  const target = process.env.VYDANNE_IPA || spec;
+  if (!target) return null;
+  if (!fs.existsSync(target)) return null;
+  if (fs.statSync(target).isFile()) return target.endsWith(".ipa") ? path.resolve(target) : null;
+  const ipas = fs
+    .readdirSync(target)
+    .filter((f) => f.endsWith(".ipa"))
+    .map((f) => path.join(target, f))
+    .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+  return ipas.length ? path.resolve(ipas[0]) : null;
+}
+
+async function altool(args, credentials) {
+  // altool finds the key itself, in the same ~/.appstoreconnect/private_keys location vydanne
+  // already resolves for its JWT — so a working `vydanne auth` is a working upload.
+  const full = ["altool", ...args, "--apiKey", credentials.keyId, "--apiIssuer", credentials.issuerId];
+  return run_("xcrun", full, { maxBuffer: 32 * 1024 * 1024 });
+}
+
+/** The newest build Apple has for this app, if any. */
+async function newestBuild(client) {
+  const { json } = await client.get(
+    `/v1/builds?filter[app]=${client.appId}&sort=-uploadedDate&limit=1` +
+      `&fields[builds]=version,processingState,uploadedDate`,
+  );
+  return json.data?.[0] ?? null;
+}
+
+export async function run(config, client, credentials) {
+  const ios = config.ios || {};
+
+  if (process.platform !== "darwin") {
+    console.error(red("prerelease: uploading to App Store Connect needs `xcrun altool`, which is macOS-only."));
+    console.error("  Apple has never exposed binary upload over the REST API — altool or Transporter only.");
+    return false;
+  }
+
+  const ipa = resolveIpa(ios.ipa);
+  if (!ipa) {
+    console.error(red("prerelease: no .ipa found — set `ios.ipa` in the config, or pass VYDANNE_IPA=<path>."));
+    console.error("  It may be a file or a directory; a directory takes its newest .ipa.");
+    return false;
+  }
+
+  await client.findApp(config.bundleId);
+  const before = await newestBuild(client);
+  const size = (fs.statSync(ipa).size / 1e6).toFixed(1);
+  console.log(green("prerelease → App Store Connect (TestFlight)"));
+  console.log(`  archive: ${path.relative(process.cwd(), ipa) || ipa}  (${size} MB)`);
+
+  // Validate before uploading. A rejected upload has already cost the transfer; altool's validation
+  // catches the common refusals (entitlements, missing icons, bad version) in seconds.
+  try {
+    await altool(["--validate-app", "-f", ipa, "-t", "ios"], credentials);
+    console.log(green("  validated"));
+  } catch (e) {
+    console.error(red("  validation failed — Apple would reject this archive:"));
+    console.error(indent(e.stdout || e.stderr || e.message));
+    return false;
+  }
+
+  try {
+    await altool(["--upload-app", "-f", ipa, "-t", "ios"], credentials);
+    console.log(green("  uploaded"));
+  } catch (e) {
+    const text = `${e.stdout || ""}${e.stderr || ""}` || e.message;
+    // The one refusal worth naming: re-uploading a build number Apple already holds. It is the
+    // right answer for an accident and a dead end for a re-run, so say which it is.
+    if (/already exists|redundant binary|previously uploaded/i.test(text)) {
+      console.error(red("  Apple already holds this build number."));
+      console.error("  Bump CFBundleVersion (Scripts/build-number.sh in the games) and re-archive.");
+    } else {
+      console.error(red("  upload failed:"));
+      console.error(indent(text));
+    }
+    return false;
+  }
+
+  const build = await waitForProcessing(client, before);
+  if (!build) {
+    console.log(yellow("  build not visible yet — Apple is still ingesting it."));
+    console.log("  It will appear in TestFlight shortly; nothing further is needed here.");
+    return true;
+  }
+  console.log(green(`  build ${build.attributes.version}: ${build.attributes.processingState}`));
+
+  if (build.attributes.processingState === "FAILED") {
+    console.error(red("  Apple failed to process this build — check the email it sent for the reason."));
+    return false;
+  }
+
+  if (ios.testFlightGroup) {
+    await assignToInternalGroup(client, build, ios.testFlightGroup);
+  }
+
+  await pointVersionAtBuild(client, config, build);
+
+  console.log("prerelease done — the build is in TestFlight.");
+  console.log(yellow("  Submitting for App Store review stays manual, by design."));
+  return true;
+}
+
+async function waitForProcessing(client, before) {
+  const deadline = Date.now() + PROCESS_TIMEOUT_MS;
+  let announced = false;
+  while (Date.now() < deadline) {
+    const build = await newestBuild(client);
+    // "New" means a different build than the one that was newest before the upload. Comparing ids
+    // rather than timestamps avoids any assumption about clock skew between here and Apple.
+    if (build && build.id !== before?.id) {
+      if (build.attributes.processingState !== "PROCESSING") return build;
+      if (!announced) {
+        console.log("  processing…");
+        announced = true;
+      }
+    }
+    await new Promise((r) => setTimeout(r, POLL_MS));
+  }
+  return null;
+}
+
+/**
+ * Add the build to an INTERNAL TestFlight group.
+ *
+ * External groups are refused: distributing to them requires Beta App Review, which is a
+ * submission, and this tool does not submit.
+ */
+async function assignToInternalGroup(client, build, groupName) {
+  const { json } = await client.get(
+    `/v1/apps/${client.appId}/betaGroups?limit=200&fields[betaGroups]=name,isInternalGroup`,
+  );
+  const groups = json.data || [];
+  const group = groups.find((g) => g.attributes.name === groupName);
+  if (!group) {
+    const names = groups.map((g) => `${g.attributes.name}${g.attributes.isInternalGroup ? "" : " (external)"}`);
+    console.error(yellow(`  no TestFlight group named "${groupName}" — have: ${names.join(", ") || "none"}`));
+    return;
+  }
+  if (!group.attributes.isInternalGroup) {
+    console.error(red(`  "${groupName}" is an EXTERNAL group — refusing.`));
+    console.error("  External testing needs Beta App Review, which is a submission by another name.");
+    return;
+  }
+  const r = await client.post(`/v1/betaGroups/${group.id}/relationships/builds`, {
+    data: [{ type: "builds", id: build.id }],
+  });
+  if (r.status < 300) console.log(green(`  added to internal group "${groupName}"`));
+  else console.error(yellow(`  could not add to "${groupName}" (${r.status})`));
+}
+
+/** Versions Apple will not let us re-point without the operator withdrawing them first. */
+const LOCKED_STATES = new Set([
+  "WAITING_FOR_REVIEW",
+  "IN_REVIEW",
+  "PENDING_DEVELOPER_RELEASE",
+  "PENDING_APPLE_RELEASE",
+  "READY_FOR_SALE",
+  "REPLACED_WITH_NEW_VERSION",
+]);
+
+/**
+ * Attach [build] to the version being prepared, replacing whatever was there.
+ *
+ * This is what makes "upload a fix and try again" one command rather than a trip to the web UI:
+ * the version → build relationship holds exactly one build, so a PATCH re-points it.
+ */
+export async function pointVersionAtBuild(client, config, build) {
+  const platform = (config.platforms && config.platforms[0]) || "IOS";
+  const version = await client.editVersion(platform);
+  if (!version) {
+    console.log(yellow("  no editable App Store version — build uploaded, nothing to attach it to."));
+    return;
+  }
+  const state = version.attributes.appStoreState;
+  const versionString = version.attributes.versionString;
+  if (LOCKED_STATES.has(state)) {
+    console.log(yellow(`  version ${versionString} is ${state} — leaving its build alone.`));
+    console.log("  Re-pointing it would mean withdrawing that submission, which is your call.");
+    return;
+  }
+
+  // What it currently points at, so a no-op re-run says so rather than looking like a change.
+  const { json: current } = await client.get(
+    `/v1/appStoreVersions/${version.id}/build?fields[builds]=version`,
+  );
+  const was = current.data?.attributes?.version ?? current.data?.id ?? null;
+  if (current.data?.id === build.id) {
+    console.log(green(`  version ${versionString} already points at build ${build.attributes.version}`));
+    return;
+  }
+
+  const r = await client.patch(`/v1/appStoreVersions/${version.id}/relationships/build`, {
+    data: { type: "builds", id: build.id },
+  });
+  if (r.status < 300) {
+    const from = was ? `build ${was} -> ` : "";
+    console.log(green(`  version ${versionString}: ${from}build ${build.attributes.version}`));
+  } else {
+    console.error(yellow(`  could not attach the build to version ${versionString} (${r.status})`));
+  }
+}
+
+const indent = (text) =>
+  String(text)
+    .trim()
+    .split("\n")
+    .map((l) => `    ${l}`)
+    .join("\n");

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", "google"];
+export const CONFIG_KEYS = ["bundleId", "primaryLocale", "asc", "platforms", "uiLocales", "metadataDir", "rating", "privacy", "iaps", "previews", "export", "ios", "google", "accessibility"];
 
 // 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

package/src/registry.mjs

@@ -14,6 +14,9 @@ export const COMMANDS = {
   inspect: { mod: "inspect", client: true },
   diff: { mod: "diff", client: true },
   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 },
 };
 
 // Commands available for `--store google` (Google Play). Same names as the Apple ones, different backend
@@ -27,4 +30,4 @@ export const PLAY_COMMANDS = {
 };
 
 // Full public command surface (the module-dispatched ones above + the three handled inline in bin/).
-export const COMMAND_NAMES = [...Object.keys(COMMANDS), "prerelease", "auth", "locales", "version"];
+export const COMMAND_NAMES = [...Object.keys(COMMANDS), "auth", "locales", "version"];

package/types/index.d.ts

@@ -16,7 +16,10 @@ export type CommandName =
   | 'inspect'
   | 'diff'
   | 'preflight'
-  /** Google Play only: upload an .aab to a closed testing track. Refuses `production`. */
+  /**
+   * Upload the build for testers: an .ipa to TestFlight (internal groups only), or with
+   * `--store google` an .aab to a closed track. Refuses App Store review and `production`.
+   */
   | 'prerelease'
   | 'auth'
   | 'locales'
@@ -52,6 +55,38 @@ export interface PrivacyConfig {
   tracking: boolean;
 }
 
+/**
+ * Accessibility Nutrition Labels — CLAIMS about your app's behaviour, published to Apple.
+ *
+ * Every feature is stated explicitly and none is optional: an omission would read as a quiet
+ * "no", which is exactly as unverified as a quiet "yes". A missing block is an error rather than
+ * a default, because "nobody wrote this down" must never become "supports everything".
+ *
+ * Apple's platform caveats are applied for you — Larger Text does not exist on macOS, Voice
+ * Control does not exist on watchOS — so those are sent as false whatever you declare.
+ */
+export interface AccessibilityConfig {
+  voiceover: boolean;
+  voiceControl: boolean;
+  largerText: boolean;
+  sufficientContrast: boolean;
+  darkInterface: boolean;
+  differentiateWithoutColorAlone: boolean;
+  reducedMotion: boolean;
+  captions: boolean;
+  audioDescriptions: boolean;
+}
+
+export interface IosConfig {
+  /** `.ipa` for `prerelease` — a file, or a directory whose NEWEST .ipa is taken. Override: VYDANNE_IPA. */
+  ipa?: string;
+  /**
+   * INTERNAL TestFlight group to add the uploaded build to. External groups are refused:
+   * distributing to them requires Beta App Review, which is a submission by another name.
+   */
+  testFlightGroup?: string;
+}
+
 export interface GoogleConfig {
   /** Play package name (usually the same as the iOS bundle id). */
   packageName: string;
@@ -98,6 +133,10 @@ export interface VydanneConfig {
   iaps?: IapConfig[];
   previews?: PreviewSpec[];
   export?: ExportConfig;
+  /** What the app actually supports, for the Accessibility Nutrition Labels. Required by that command. */
+  accessibility?: AccessibilityConfig;
+  /** iOS build upload (`prerelease`): where the .ipa is, and which internal TestFlight group. */
+  ios?: IosConfig;
   /** Google Play (`--store google`): listings, screenshots, feature graphic via the Edits API. */
   google?: GoogleConfig;
 }