vydanne 0.6.0 → 0.7.0

package/src/commands/privacy.mjs

@@ -2,26 +2,96 @@ import fs from "node:fs";
 import path from "node:path";
 import { green, yellow } from "../util.mjs";
 
-// App Privacy is on Apple's iris host, which 401s the JWT — it CANNOT be set with the ASC API key. Write
-// the honest record + print the exact ASC-UI answers (a passkey login works there).
-const GROUP = { CRASH_DATA: "Diagnostics", PERFORMANCE_DATA: "Diagnostics", OTHER_DIAGNOSTIC_DATA: "Diagnostics" };
+/**
+ * App Privacy is on Apple's iris host, which 401s the ASC API key — it CANNOT be set through the API.
+ * So this writes the honest record and prints the exact answers to type into the ASC UI (where a
+ * passkey login works).
+ *
+ * PURPOSES ARE DECLARED, NOT ASSUMED. Every collected category used to be reported as
+ * "APP_FUNCTIONALITY", which is right for crash data in a game and wrong for almost anything else — an
+ * email address collected for marketing, or location used for analytics, would have been printed as
+ * App Functionality and typed into Apple's form that way. And the UI group was known only for the three
+ * diagnostics categories, so anything else printed a literal "?" as its section heading, which is not
+ * an answer anyone can enter. Both are now data tables covering Apple's full vocabulary, with
+ * per-category overrides in the config for the app that needs them.
+ */
+
+/** Apple's data categories -> the section they live under in the App Privacy form. */
+const GROUP = {
+  // Contact info
+  NAME: "Contact Info", EMAIL_ADDRESS: "Contact Info", PHONE_NUMBER: "Contact Info",
+  PHYSICAL_ADDRESS: "Contact Info", OTHER_USER_CONTACT_INFO: "Contact Info",
+  // Health & fitness
+  HEALTH: "Health & Fitness", FITNESS: "Health & Fitness",
+  // Financial info
+  PAYMENT_INFO: "Financial Info", CREDIT_INFO: "Financial Info", OTHER_FINANCIAL_INFO: "Financial Info",
+  // Location
+  PRECISE_LOCATION: "Location", COARSE_LOCATION: "Location",
+  // Sensitive info
+  SENSITIVE_INFO: "Sensitive Info",
+  // Contacts
+  CONTACTS: "Contacts",
+  // User content
+  EMAILS_OR_TEXT_MESSAGES: "User Content", PHOTOS_OR_VIDEOS: "User Content", AUDIO_DATA: "User Content",
+  GAMEPLAY_CONTENT: "User Content", CUSTOMER_SUPPORT: "User Content", OTHER_USER_CONTENT: "User Content",
+  // Browsing / search history
+  BROWSING_HISTORY: "Browsing History", SEARCH_HISTORY: "Search History",
+  // Identifiers
+  USER_ID: "Identifiers", DEVICE_ID: "Identifiers",
+  // Purchases
+  PURCHASE_HISTORY: "Purchases",
+  // Usage data
+  PRODUCT_INTERACTION: "Usage Data", ADVERTISING_DATA: "Usage Data", OTHER_USAGE_DATA: "Usage Data",
+  // Diagnostics
+  CRASH_DATA: "Diagnostics", PERFORMANCE_DATA: "Diagnostics", OTHER_DIAGNOSTIC_DATA: "Diagnostics",
+  // Other
+  OTHER_DATA_TYPES: "Other Data",
+};
+
+/** Apple's purpose codes -> the label the form uses. */
+const PURPOSE_LABEL = {
+  THIRD_PARTY_ADVERTISING: "Third-Party Advertising",
+  DEVELOPERS_ADVERTISING: "Developer's Advertising or Marketing",
+  ANALYTICS: "Analytics",
+  PRODUCT_PERSONALIZATION: "Product Personalization",
+  APP_FUNCTIONALITY: "App Functionality",
+  OTHER_PURPOSES: "Other Purposes",
+};
 
 export async function run(config) {
   const collected = config.privacy?.collected || ["CRASH_DATA", "PERFORMANCE_DATA"];
   const tracking = !!config.privacy?.tracking;
+  // `purposes` may be one list for everything, or a per-category map. App Functionality stays the
+  // default because it is the honest answer for the diagnostics an app collects to fix itself — but it
+  // is now a default that an app can disagree with, rather than the only thing this command can say.
+  const declared = config.privacy?.purposes;
+  const purposesFor = (cat) => {
+    const p = Array.isArray(declared) ? declared : declared?.[cat];
+    return (p && p.length ? p : ["APP_FUNCTIONALITY"]);
+  };
+
   const record = collected.map((cat) => ({
-    category: cat, purposes: ["APP_FUNCTIONALITY"],
+    category: cat,
+    purposes: purposesFor(cat),
     data_protections: [tracking ? "DATA_LINKED_TO_YOU" : "DATA_NOT_LINKED_TO_YOU", tracking ? "DATA_USED_TO_TRACK_YOU" : null].filter(Boolean),
   }));
   const out = path.join(path.dirname(config.metadataDir), "app_privacy_details.json");
   fs.writeFileSync(out, JSON.stringify(record, null, 2));
   console.log(green(`wrote ${out} (declaration record)`));
   console.log();
+
+  const unknown = collected.filter((c) => !GROUP[c]);
+  if (unknown.length) {
+    console.log(yellow(`  category not in Apple's published list, section unknown: ${unknown.join(", ")}`));
+    console.log("  Check the spelling against App Privacy in App Store Connect before entering it.");
+  }
+
   console.log(yellow("App Privacy is UI-only (passkey) — the API key 401s on Apple's iris host. Enter:"));
   if (collected.length) console.log("  Do you or your partners collect data? -> Yes");
   for (const c of collected) {
     const name = c.split("_").map((w) => w[0] + w.slice(1).toLowerCase()).join(" ");
-    console.log(`  ${GROUP[c] || "?"} -> ${name}: App Functionality · ${tracking ? "Linked" : "Not Linked"} · ${tracking ? "Tracking" : "No Tracking"}`);
+    const purposes = purposesFor(c).map((p) => PURPOSE_LABEL[p] || p).join(" + ");
+    console.log(`  ${GROUP[c] || "?"} -> ${name}: ${purposes} · ${tracking ? "Linked" : "Not Linked"} · ${tracking ? "Tracking" : "No Tracking"}`);
   }
   console.log("  Everything else -> Not Collected.");
   console.log(yellow("  'accesses' is not 'collects' — E2EE content you can't read is not collected."));

package/src/commands/push.mjs

@@ -0,0 +1,118 @@
+import { green, yellow, red } from "../util.mjs";
+import { run as prepare } from "./prepare.mjs";
+import { run as fill } from "./fill.mjs";
+import { run as previews } from "./previews.mjs";
+import { run as ageRating } from "./ageRating.mjs";
+import { run as reviewContact } from "./reviewContact.mjs";
+import { run as accessibility } from "./accessibility.mjs";
+import { run as preflight } from "./preflight.mjs";
+
+/**
+ * The whole Apple release pipeline, in the one order that works.
+ *
+ * WHY A COMMAND AND NOT A PARAGRAPH. Shipping an update takes seven commands in a specific order —
+ * `prepare` first (or nothing has a version to write into), `preflight` last (or green is measured
+ * before the writes it is meant to bless) — and that ordering lived in nobody's head. The near-miss
+ * that proved it: with the order forgotten, `fill` was pointed at an app whose only version was ON
+ * SALE, and only the editVersion() fix stood between the dry run and a rewritten live listing. A
+ * README section can teach the order; only a command can make it impossible to run out of order.
+ *
+ * WHAT IT IS. A sequencer, nothing more: each step is the same `run` its standalone command uses, on
+ * the same client, so `push` can do nothing a step couldn't. The first failure stops the run — a step
+ * that cannot proceed says why and names its fix (that is each command's own contract), and continuing
+ * past it would let a green `preflight` at the end bless a release with a known hole in it.
+ *
+ * SKIPPING IS EXPLICIT AND LOUD. `--skip <step>[,<step>]` (or `push: { skip: [...] }`) drops a step
+ * from the run. This exists because a pipeline with no way out is a pipeline that stops working the
+ * moment one step legitimately does not apply to an app: `accessibility` refuses when no block is
+ * declared — correctly, it publishes claims — so an app that has not audited its accessibility could
+ * not complete `push` at all, and neither could one with no App Review PII on disk. The skip is named
+ * on every line of the report and again at the end, because the whole value of the last step is that
+ * green means green: a run that skipped something must never read like a run that did everything.
+ *
+ * WHAT IT IS NOT. It never submits — the pipeline ends at `preflight`, and Add to Review + Submit
+ * stay in App Store Connect, human-only, exactly as every step's own refusals already guarantee.
+ * `prerelease` (the build upload) is deliberately not a step: it is macOS-only, shells out to altool,
+ * and belongs wherever the archive is produced. Run it whenever the build is ready — before or after
+ * `push`; `prepare` attaches the newest build either way.
+ *
+ * Dry-run composes: without --apply the shared client refuses every mutation, each step reports its
+ * plan, and bin/ prints the withheld-write count at the end. The one case a dry run cannot preview
+ * past is an app with no editable version — the draft the later steps target does not exist until
+ * `prepare` is APPLIED — so that is said up front rather than discovered as a refusal mid-run.
+ */
+const STEPS = [
+  ["prepare", prepare],
+  ["fill", fill],
+  ["previews", previews],
+  ["age-rating", ageRating],
+  ["review-contact", reviewContact],
+  ["accessibility", accessibility],
+  ["preflight", preflight],
+];
+
+/** Steps named by `--skip a,b` and/or `push.skip` in the config, validated against the real step list. */
+function resolveSkips(config) {
+  const flag = process.argv.find((a) => a.startsWith("--skip="))?.slice("--skip=".length)
+    ?? (process.argv.includes("--skip") ? process.argv[process.argv.indexOf("--skip") + 1] : null);
+  const named = [
+    ...(flag ? String(flag).split(",") : []),
+    ...(config.push?.skip || []),
+  ].map((s) => s.trim()).filter(Boolean);
+  const names = STEPS.map(([n]) => n);
+  const unknown = named.filter((s) => !names.includes(s));
+  return { skip: new Set(named.filter((s) => names.includes(s))), unknown };
+}
+
+export async function run(config, client) {
+  await client.findApp(config.bundleId);
+  const { skip, unknown } = resolveSkips(config);
+  if (unknown.length) {
+    console.error(red(`push: --skip named step(s) that do not exist: ${unknown.join(", ")}`));
+    console.error(`  Steps: ${STEPS.map(([n]) => n).join(", ")}`);
+    return false;
+  }
+  // Skipping the last step would make the command's own promise unverifiable, and skipping the first
+  // leaves every later step writing into a version that may not exist. Both are refusals rather than
+  // warnings: there is no reading of "push, but don't check the result" that is worth supporting.
+  for (const required of ["prepare", "preflight"]) {
+    if (skip.has(required)) {
+      console.error(red(`push: \`${required}\` cannot be skipped — run the other steps individually if that is what you want.`));
+      return false;
+    }
+  }
+
+  const platform = (config.platforms && config.platforms[0]) || "IOS";
+  if (client.dryRun && !(await client.editVersion(platform))) {
+    console.log(yellow("push: no editable App Store version exists, so this dry run will stop where the draft is needed."));
+    console.log("  `vydanne prepare --apply` creates it — a draft, not a submission — then re-run `vydanne push`");
+    console.log("  to preview the rest of the pipeline.");
+  }
+
+  const skipped = [];
+  for (const [name, step] of STEPS) {
+    if (skip.has(name)) {
+      console.log(yellow(`\n▸ push: ${name} — SKIPPED (--skip)`));
+      skipped.push(name);
+      continue;
+    }
+    console.log(green(`\n▸ push: ${name}`));
+    const ok = await step(config, client);
+    if (ok === false) {
+      console.error(red(`\npush: stopped at \`${name}\` — fix what it reported above, then re-run \`vydanne push\`.`));
+      console.error("  Every completed step is idempotent, so re-running repeats nothing destructive.");
+      if (name === "age-rating" && !config.ageRating && config.rating !== "4+") {
+        console.error(`  For a '${config.rating}' rating, declare the content descriptors in \`ageRating\` — see the message above.`);
+      }
+      console.error(`  Or drop this step for now: \`vydanne push --apply --skip ${name}\``);
+      return false;
+    }
+  }
+
+  console.log(green("\npush done — the release is staged and preflight is green."));
+  // Repeated at the end on purpose. The one thing this command sells is that its last line means the
+  // release is ready; a skipped step is precisely the case where that would otherwise overstate it.
+  if (skipped.length) console.log(yellow(`  NOT green for: ${skipped.join(", ")} — skipped, never run. Run them before you submit.`));
+  console.log(yellow("  Submitting stays yours: App Store Connect → the prepared version → Add to Review → Submit."));
+  return true;
+}

package/src/commands/reviewContact.mjs

@@ -2,27 +2,77 @@ import fs from "node:fs";
 import path from "node:path";
 import { green, yellow, red } from "../util.mjs";
 
-// App Review contact from the GITIGNORED metadata/review_information/*.txt. PATCH (or POST) the review
-// detail directly — deliver can't do this cleanly pre-first-submission.
+/**
+ * App Review contact, from the GITIGNORED `<metadataDir>/review_information/*.txt`. PATCH (or POST) the
+ * review detail directly — deliver can't do this cleanly pre-first-submission.
+ *
+ * DEMO ACCOUNT. `demoAccountRequired` used to be hardcoded false. That is true of an account-less game
+ * and false of anything with a login, and getting it wrong is not a small thing: telling Apple no demo
+ * account is needed for an app whose first screen is a sign-in wall is a guaranteed rejection, with a
+ * review cycle attached. fastlane's own convention already puts `demo_user.txt` / `demo_password.txt`
+ * in the very directory this reads from, so the fix is to read the two files that were sitting there.
+ *
+ * Every platform gets the same contact, because the contact is a property of the submitter rather than
+ * of a platform — an app shipping iOS and macOS used to set it on `platforms[0]` and leave the other
+ * version's review detail empty.
+ */
 export async function run(config, client) {
   const dir = path.join(config.metadataDir, "review_information");
   const read = (n) => { const p = path.join(dir, `${n}.txt`); return fs.existsSync(p) ? fs.readFileSync(p, "utf8").trim() : ""; };
+
+  const demoUser = read("demo_user");
+  const demoPassword = read("demo_password");
   const attributes = {
     contactFirstName: read("first_name"), contactLastName: read("last_name"),
     contactPhone: read("phone_number"), contactEmail: read("email_address"),
-    demoAccountRequired: false, notes: read("notes"),
+    // Declared by what is on disk, with an explicit config override for the app that needs one and
+    // supplies it some other way (a reviewer-specific build, a magic link in the notes).
+    demoAccountRequired: config.reviewContact?.demoAccountRequired ?? !!demoUser,
+    notes: read("notes"),
   };
+  if (demoUser) attributes.demoAccountName = demoUser;
+  if (demoPassword) attributes.demoAccountPassword = demoPassword;
+
   if (!attributes.contactEmail) { console.error(red(`review-contact: ${dir}/*.txt missing`)); return false; }
+  // A demo account that is required but has no credentials is the rejection this command exists to
+  // avoid, arriving by a different door — say it here rather than letting Apple say it in a week.
+  if (attributes.demoAccountRequired && !demoUser) {
+    console.error(red("review-contact: demoAccountRequired is true but no demo_user.txt was found."));
+    console.error(`  Add ${dir}/demo_user.txt and demo_password.txt (both gitignored), or set`);
+    console.error("  reviewContact: { demoAccountRequired: false } if the reviewer genuinely needs no account.");
+    return false;
+  }
+
   await client.findApp(config.bundleId);
-  const v = await client.editVersion(config.platforms[0]);
-  if (!v) { console.error(red("review-contact: no editable version")); return false; }
-  const { json } = await client.get(`/v1/appStoreVersions/${v.id}/appStoreReviewDetail`);
-  const existing = json.data;
-  const r = existing?.id
-    ? await client.patch(`/v1/appStoreReviewDetails/${existing.id}`, { data: { type: "appStoreReviewDetails", id: existing.id, attributes } })
-    : await client.post(`/v1/appStoreReviewDetails`, { data: { type: "appStoreReviewDetails", attributes, relationships: { appStoreVersion: { data: { type: "appStoreVersions", id: v.id } } } } });
-  if (r.status >= 300) { console.error(red(`review-contact: ${r.status}: ${JSON.stringify(r.json).slice(0, 200)}`)); return false; }
+
+  let ok = true;
+  let touched = 0;
+  for (const platform of config.platforms) {
+    const v = await client.editVersion(platform);
+    if (!v) {
+      console.error(red(`review-contact ${platform}: no editable version — nothing to attach the contact to.`));
+      console.error("  `vydanne prepare --apply` creates the version being submitted, then re-run this.");
+      ok = false;
+      continue;
+    }
+    const { json } = await client.get(`/v1/appStoreVersions/${v.id}/appStoreReviewDetail`);
+    const existing = json.data;
+    const r = existing?.id
+      ? await client.patch(`/v1/appStoreReviewDetails/${existing.id}`, { data: { type: "appStoreReviewDetails", id: existing.id, attributes } })
+      : await client.post(`/v1/appStoreReviewDetails`, { data: { type: "appStoreReviewDetails", attributes, relationships: { appStoreVersion: { data: { type: "appStoreVersions", id: v.id } } } } });
+    if (r.status >= 300) {
+      console.error(red(`review-contact ${platform}: ${r.status}: ${JSON.stringify(r.json).slice(0, 200)}`));
+      ok = false;
+      continue;
+    }
+    touched++;
+  }
+  if (!touched) return false;
+
   const who = `${attributes.contactFirstName} ${attributes.contactLastName} · ${attributes.contactPhone}`;
-  console.log(client.dryRun ? yellow(`review contact WOULD be set -> ${who}`) : green(`review contact set -> ${who}`));
-  return true;
+  const demo = attributes.demoAccountRequired ? ` · demo account ${demoUser}` : "";
+  console.log(client.dryRun
+    ? yellow(`review contact WOULD be set on ${touched} platform(s) -> ${who}${demo}`)
+    : green(`review contact set on ${touched} platform(s) -> ${who}${demo}`));
+  return ok;
 }

package/src/config.mjs

@@ -3,10 +3,12 @@ import fs from "node:fs";
 import { pathToFileURL } from "node:url";
 import { resolveLocales } from "./locales.mjs";
 import { resolveCredentials } from "./credentials.mjs";
+import { DEFAULT_SCREENSHOT_BASE } from "./screenshots.mjs";
+import { DEFAULT_PLAY_IMAGES } from "./play/images.mjs";
 
 // The public config surface — the drift guards assert each key is documented (README/SKILL) and typed
 // (types/index.d.ts). Add a config knob → document + type it, or the guards fail before publish.
-export const CONFIG_KEYS = ["bundleId", "primaryLocale", "asc", "platforms", "uiLocales", "metadataDir", "rating", "privacy", "iaps", "previews", "export", "ios", "google", "accessibility", "allowCrossStoreTerms"];
+export const CONFIG_KEYS = ["bundleId", "primaryLocale", "asc", "platforms", "uiLocales", "localeMap", "metadataDir", "screenshots", "rating", "ageRating", "privacy", "iaps", "previews", "export", "ios", "google", "accessibility", "bridge", "push", "reviewContact", "allowCrossStoreTerms"];
 
 // One `vydanne.config.mjs` per app (ESM, like zdymak.config.mjs) — nothing hard-coded. Secrets stay out:
 // credentials resolve from the environment, a gitignored .env, or ~/.appstoreconnect/config.json (see
@@ -22,23 +24,64 @@ export async function loadConfig(p) {
   };
   const creds = resolveCredentials(raw, path.dirname(file));
   for (const w of creds.warnings) console.warn(`\x1b[33mvydanne: ${w}\x1b[0m`);
+  // No `raw` passthrough, deliberately. It was assigned here and read by nothing — an attractive
+  // nuisance rather than dead weight: while `config.ios` sat unassigned (the bug check-config.mjs now
+  // guards), `config.raw.ios` WAS populated, so "fixing" a caller by reading through `raw` would have
+  // entrenched the dropped key instead of exposing it. Everything a command may read is an explicit
+  // key below, where the guard can see it.
   const c = {
-    raw,
     credentials: creds,
     bundleId: need("bundleId"),
     primaryLocale: need("primaryLocale"),
     keyId: creds.keyId,
     issuerId: creds.issuerId,
     uiLocales: raw.uiLocales || [],
+    // App code -> App Store locale, for codes Apple spells differently or does not know yet. Merged over
+    // the built-in table rather than replacing it, so an app declares only its exceptions.
+    localeMap: raw.localeMap || null,
     platforms: raw.platforms || ["IOS"],
     rating: raw.rating || "4+",
+    // Content descriptors for a rating above 4+. Null means "the 4+ shorthand", which `age-rating`
+    // expands to an all-NONE declaration; anything else must be declared, never guessed.
+    ageRating: raw.ageRating || null,
     privacy: raw.privacy || { collected: ["CRASH_DATA", "PERFORMANCE_DATA"], tracking: false },
     iaps: raw.iaps || [],
     metadataDir: raw.metadataDir || "fastlane/metadata",
+    // Where each platform's screenshots live. fastlane's supply convention by default — the same
+    // relationship `metadataDir` has always had to it, and for the same reason: a convention worth
+    // defaulting to is not a reason to be unable to point the tool at your own repo.
+    screenshots: raw.screenshots
+      ? { IOS: raw.screenshots.IOS || DEFAULT_SCREENSHOT_BASE.IOS, MAC_OS: raw.screenshots.MAC_OS || DEFAULT_SCREENSHOT_BASE.MAC_OS }
+      : null,
+    // App Review contact overrides. The PII itself still comes from the gitignored
+    // `<metadataDir>/review_information/*.txt` — this is only for what isn't a secret.
+    reviewContact: raw.reviewContact || null,
+    // `push: { skip: [...] }` — steps this app never runs. `--skip` adds to it per invocation; both are
+    // reported on every run, because a skipped step must never read as a completed one.
+    push: raw.push ? { skip: raw.push.skip || [] } : null,
+    // `bridge`: where zdymak wrote, and which of its output directories feed which store slot. Both
+    // default to zdymak's own conventions; both must be overridable, because `dir:` overrides in
+    // zdymak.config.mjs mean the directory name and the target name are not the same thing.
+    bridge: raw.bridge
+      ? { out: raw.bridge.out || null, apple: raw.bridge.apple || null, play: raw.bridge.play || null }
+      : null,
     // Terms the cross-store check must not flag for this app (see src/crossStore.mjs).
     allowCrossStoreTerms: raw.allowCrossStoreTerms || [],
     previews: raw.previews || null,
     export: raw.export || { encryption: "standard" },
+    // What the app claims to support, for the Accessibility Nutrition Labels. Passed through RAW and
+    // deliberately NOT defaulted: `accessibility` validates its own block and must be able to tell
+    // "declared nothing" from "declared everything false" — a default here would turn a missing block
+    // into a silent set of claims, which is the one thing that command exists to refuse.
+    accessibility: raw.accessibility || null,
+    // iOS build upload (`prerelease`). Normalised like `google` below so the shape is stable whether or
+    // not the block is present.
+    ios: raw.ios
+      ? {
+          ipa: raw.ios.ipa || null, // VYDANNE_IPA overrides, resolved in prerelease.resolveIpa
+          testFlightGroup: raw.ios.testFlightGroup || null, // internal groups only; external is refused
+        }
+      : null,
     // Google Play. serviceAccountKey resolves from PLAY_JSON_KEY_FILE env first (keep the secret path out
     // of the committed config). metadataDir follows fastlane supply's convention (fastlane/metadata/android).
     google: raw.google
@@ -49,10 +92,16 @@ export async function loadConfig(p) {
           defaultLocale: raw.google.defaultLocale || raw.primaryLocale,
           aab: raw.google.aab || null,
           track: raw.google.track || "internal", // testing only — `prerelease` refuses production
-
+          // Play image type -> local source path. Merged over the defaults so an app overrides only the
+          // slots whose layout differs; the default for `icon` points at znachok's output, which is a
+          // sensible default for this portfolio and a mystery to anyone else, so it is overridable.
+          images: { ...DEFAULT_PLAY_IMAGES, ...(raw.google.images || {}) },
+          // Play supports per-language graphics. Uploading only to `defaultLocale` is a choice, not a
+          // platform limit — list locales here (or "*" for every local listing folder) to localize them.
+          imageLocales: raw.google.imageLocales || null,
         }
       : null,
   };
-  c.resolvedLocales = resolveLocales(c.uiLocales);
+  c.resolvedLocales = resolveLocales(c.uiLocales, c.localeMap);
   return c;
 }

package/src/index.mjs

@@ -1,6 +1,63 @@
-// Programmatic entry (the CLI is bin/vydanne.mjs). `import { Client, loadConfig } from "vydanne"`.
+// Programmatic entry (the CLI is bin/vydanne.mjs). `import { runCommand, loadConfig } from "vydanne"`.
+//
+// This used to export a client, a config loader and the command REGISTRY — a table of `{ mod: "fill" }`
+// filenames that nothing outside the package could resolve, because `exports` maps only ".". So a
+// consumer could see that `fill` existed and had no way to run it. `runCommand` is that missing half:
+// the same dispatch bin/ performs, minus the argv parsing and the process.exit.
+import { Client } from "./client.mjs";
+import { loadConfig } from "./config.mjs";
+import { COMMANDS, PLAY_COMMANDS } from "./registry.mjs";
+
 export { Client } from "./client.mjs";
+export { PlayClient } from "./play/client.mjs";
 export { loadConfig, CONFIG_KEYS } from "./config.mjs";
-export { COMMANDS, COMMAND_NAMES } from "./registry.mjs";
-export { resolveLocales, toAsc, VALID } from "./locales.mjs";
+export { COMMANDS, PLAY_COMMANDS, COMMAND_NAMES } from "./registry.mjs";
+export { resolveLocales, toAsc, VALID, UI_TO_ASC } from "./locales.mjs";
 export { makeToken } from "./jwt.mjs";
+export { DEFAULT_SCREENSHOT_BASE, IOS_DEVICE, MAC_DEVICE, screenshotBase } from "./screenshots.mjs";
+export { DEFAULT_PLAY_IMAGES, PLAY_IMAGE_KIND, playImages } from "./play/images.mjs";
+
+/**
+ * Run one command, the way the CLI runs it.
+ *
+ * `apply` is the same safety gate the `--apply` flag drives, and it defaults to FALSE here for the same
+ * reason it does there: a caller that forgets it gets a dry run, never a write. A command that writes
+ * to the store receives a client already refusing mutations, so "dry run" is enforced in the client
+ * rather than trusted to each command.
+ *
+ * Returns `{ ok, planned }` — `planned` being the writes a dry run withheld, which is the machine-
+ * readable form of what the CLI prints as "N store write(s) withheld".
+ *
+ * @param {string} name    a key of COMMANDS (or of PLAY_COMMANDS when store is "google")
+ * @param {object} [opts]
+ * @param {object} [opts.config]     a loaded config; loaded from disk when omitted
+ * @param {string} [opts.configPath] path to vydanne.config.mjs, when loading from disk
+ * @param {"apple"|"google"} [opts.store]
+ * @param {boolean} [opts.apply]     perform store writes (default false — dry run)
+ */
+export async function runCommand(name, opts = {}) {
+  const { store = "apple", apply = false, configPath } = opts;
+  if (store !== "apple" && store !== "google") throw new Error(`vydanne: unknown store '${store}' (expected: apple, google)`);
+
+  const config = opts.config || (await loadConfig(configPath));
+  const table = store === "google" ? PLAY_COMMANDS : COMMANDS;
+  const spec = table[name];
+  if (!spec) throw new Error(`vydanne: unknown command '${name}' for store '${store}' (try: ${Object.keys(table).join(", ")})`);
+
+  const dryRun = Boolean(spec.writes) && !apply;
+
+  if (store === "google") {
+    if (!config.google) throw new Error("vydanne: no `google` block in config — add packageName + a service-account key");
+    if (!config.google.serviceAccountKey) throw new Error("vydanne: set PLAY_JSON_KEY_FILE (or google.serviceAccountKey) to the Play service-account JSON");
+    const { PlayClient } = await import("./play/client.mjs");
+    const client = await PlayClient.create({ keyPath: config.google.serviceAccountKey, packageName: config.google.packageName, dryRun });
+    const { run } = await import(`./play/commands/${spec.mod}.mjs`);
+    return { ok: (await run(config, client)) !== false, planned: [] };
+  }
+
+  const client = spec.client ? new Client({ keyId: config.keyId, issuerId: config.issuerId, dryRun }) : null;
+  const { run } = await import(`./commands/${spec.mod}.mjs`);
+  // altool authenticates on its own rather than through our JWT, so it needs the raw ids.
+  const ok = await run(config, client, spec.credentials ? { keyId: config.keyId, issuerId: config.issuerId } : undefined);
+  return { ok: ok !== false, planned: client?.planned ?? [] };
+}

package/src/locales.mjs

@@ -8,19 +8,41 @@ export const VALID = new Set([
   "te-IN", "th", "tr", "uk", "ur-PK", "vi", "zh-Hans", "zh-Hant",
 ]);
 
+// Short UI code -> App Store code. `nb` and `iw` are Android's spellings of Norwegian and Hebrew: a
+// project that names its resource folders the Android way (values-nb, values-iw) would otherwise have
+// both locales resolve to "no App Store language" and fall back to the primary listing — a silently
+// missing translation for a language Apple does support under a different code.
 export const UI_TO_ASC = {
   ar: "ar-SA", bn: "bn-BD", de: "de-DE", es: "es-ES", fr: "fr-FR", nl: "nl-NL",
   pt: "pt-BR", ur: "ur-PK", zh: "zh-Hans", en: "en-US",
+  nb: "no", iw: "he", in: "id", ji: "he",
 };
 
-export const toAsc = (code) => (VALID.has(code) ? code : UI_TO_ASC[code] || null);
+/**
+ * `code` as an App Store locale, or null when Apple has no listing language for it.
+ *
+ * `extra` is the app's own `localeMap` — the extension point this table lacked. Apple's list moves, and
+ * projects spell locales in whatever their UI framework uses; neither is a reason to need a vydanne
+ * release. An app can map its code onto a VALID one, and only onto a VALID one: an override pointing at
+ * a language Apple does not have would fail at upload instead of here.
+ */
+export const toAsc = (code, extra) => {
+  if (VALID.has(code)) return code;
+  const mapped = extra?.[code] ?? UI_TO_ASC[code] ?? null;
+  return mapped && VALID.has(mapped) ? mapped : null;
+};
 
-export function resolveLocales(uiCodes = []) {
+export function resolveLocales(uiCodes = [], extra) {
   const supported = {};
   const unsupported = [];
+  const invalid = [];
   for (const c of uiCodes) {
-    const asc = toAsc(c);
-    asc ? (supported[c] = asc) : unsupported.push(c);
+    const asc = toAsc(c, extra);
+    if (asc) supported[c] = asc;
+    // An override that names a code Apple doesn't have is a config mistake, not a missing language —
+    // kept apart so the report can say which it is instead of blaming the locale.
+    else if (extra?.[c]) invalid.push(`${c} -> ${extra[c]}`);
+    else unsupported.push(c);
   }
-  return { supported, unsupported };
+  return { supported, unsupported, invalid };
 }