vydanne 0.4.2 → 0.6.0

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,19 +1,29 @@
 // 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 },
   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, writes: true },
 };
 
 // Commands available for `--store google` (Google Play). Same names as the Apple ones, different backend
@@ -22,9 +32,9 @@ 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/).
-export const COMMAND_NAMES = [...Object.keys(COMMANDS), "prerelease", "auth", "locales", "version"];
+export const COMMAND_NAMES = [...Object.keys(COMMANDS), "auth", "locales", "version"];

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

@@ -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,20 +133,38 @@ 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;
+  /**
+   * 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[]>;
@@ -125,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;