vydanne 0.6.0 → 0.8.0

package/src/commands/appInfo.mjs

@@ -0,0 +1,124 @@
+import { green, yellow, red } from "../util.mjs";
+
+/**
+ * The two app-level facts that block **Add for Review** and nothing else in vydanne could set.
+ *
+ *   You must select a primary category for your app.
+ *   You must set up Content Rights Information in App Information.
+ *
+ * Both are one API call each and were simply never wired, so a release that was green everywhere —
+ * metadata filled, screenshots uploaded, build attached, preflight clean — still stopped dead at the
+ * last screen with two errors nobody could act on from a terminal. That is the worst place to
+ * discover missing automation: after the work, in a web form, with no record of what the right
+ * answer was last time.
+ *
+ * Deliberately its OWN command rather than folded into `prepare`. `prepare` is about a version; these
+ * are about the app, and they outlive every version — setting them once is normal and re-running is a
+ * no-op. Keeping them separate also means a failure here names itself instead of failing a step whose
+ * name says "version".
+ */
+
+/**
+ * Apple's category vocabulary is a fixed set of ids, and `GAMES` is the only one with subcategories.
+ * Listed rather than free-typed because a wrong id returns a 409 that names neither the field nor the
+ * legal values, and the guess someone makes from that ("Puzzle", "games") is wrong twice over — the
+ * ids are upper snake case and game subcategories are prefixed.
+ */
+const CATEGORIES = new Set([
+  "BOOKS", "BUSINESS", "DEVELOPER_TOOLS", "EDUCATION", "ENTERTAINMENT", "FINANCE", "FOOD_AND_DRINK",
+  "GAMES", "GRAPHICS_AND_DESIGN", "HEALTH_AND_FITNESS", "LIFESTYLE", "MAGAZINES_AND_NEWSPAPERS",
+  "MEDICAL", "MUSIC", "NAVIGATION", "NEWS", "PHOTO_AND_VIDEO", "PRODUCTIVITY", "REFERENCE",
+  "SHOPPING", "SOCIAL_NETWORKING", "SPORTS", "TRAVEL", "UTILITIES", "WEATHER",
+]);
+
+const GAME_SUBCATEGORIES = new Set([
+  "GAMES_ACTION", "GAMES_ADVENTURE", "GAMES_BOARD", "GAMES_CARD", "GAMES_CASINO", "GAMES_CASUAL",
+  "GAMES_FAMILY", "GAMES_MUSIC", "GAMES_PUZZLE", "GAMES_RACING", "GAMES_ROLE_PLAYING",
+  "GAMES_SIMULATION", "GAMES_SPORTS", "GAMES_STRATEGY", "GAMES_TRIVIA", "GAMES_WORD",
+]);
+
+/** Apple's own two values, stated as a question so a config cannot get the polarity backwards. */
+const RIGHTS = {
+  true: "USES_THIRD_PARTY_CONTENT",
+  false: "DOES_NOT_USE_THIRD_PARTY_CONTENT",
+};
+
+function validate(config) {
+  const c = config.categories;
+  if (!c) return { problem: "appinfo: no `categories` in the config — set at least { primary: 'GAMES' }." };
+  const bad = [];
+  if (!CATEGORIES.has(c.primary)) bad.push(`primary '${c.primary}' is not an Apple category id (e.g. GAMES, PUZZLE is a SUBcategory)`);
+  if (c.secondary && !CATEGORIES.has(c.secondary)) bad.push(`secondary '${c.secondary}' is not an Apple category id`);
+  for (const k of ["primarySubcategoryOne", "primarySubcategoryTwo", "secondarySubcategoryOne", "secondarySubcategoryTwo"]) {
+    if (c[k] && !GAME_SUBCATEGORIES.has(c[k])) bad.push(`${k} '${c[k]}' is not a game subcategory id (they are GAMES_*)`);
+  }
+  // Apple allows subcategories only under GAMES; sending them otherwise is a 409 that reads as a
+  // generic relationship error.
+  if (c.primarySubcategoryOne && c.primary !== "GAMES") bad.push("subcategories are only valid when primary is GAMES");
+  if (config.contentRights !== undefined && typeof config.contentRights !== "boolean") {
+    bad.push("contentRights must be true (uses third-party content) or false (does not)");
+  }
+  return bad.length ? { problem: `appinfo: ${bad.join("; ")}` } : {};
+}
+
+const rel = (id) => (id ? { data: { type: "appCategories", id } } : { data: null });
+
+export async function run(config, client) {
+  const { problem } = validate(config);
+  if (problem) { console.error(red(problem)); return false; }
+
+  await client.findApp(config.bundleId);
+  // Same refusal as age-rating, and for the same reason: the LIVE app info's category is not ours to
+  // aim a write at, and appInfo() returning the live record instead of null once made that write look
+  // like it had worked.
+  const info = await client.appInfo();
+  if (!info) {
+    console.error(red("appinfo: 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 c = config.categories;
+  const relationships = {
+    primaryCategory: rel(c.primary),
+    primarySubcategoryOne: rel(c.primarySubcategoryOne),
+    primarySubcategoryTwo: rel(c.primarySubcategoryTwo),
+    secondaryCategory: rel(c.secondary),
+    secondarySubcategoryOne: rel(c.secondarySubcategoryOne),
+    secondarySubcategoryTwo: rel(c.secondarySubcategoryTwo),
+  };
+  const shown = [c.primary, c.primarySubcategoryOne, c.primarySubcategoryTwo, c.secondary]
+    .filter(Boolean).join(" · ");
+  console.log(`  categories: ${shown}`);
+
+  const r = await client.patch(`/v1/appInfos/${info.id}`, {
+    data: { type: "appInfos", id: info.id, relationships },
+  });
+  if (r.status >= 300) {
+    console.error(red(`appinfo: categories ${r.status}`));
+    for (const e of r.json?.errors || []) console.error(`    ${e.title}: ${e.detail}`);
+    return false;
+  }
+  console.log(client.dryRun ? yellow(`  WOULD set categories`) : green(`  categories set`));
+
+  // Content rights is on the APP, not the app info — a different resource, which is most of why it
+  // was missed. Skipped entirely when undeclared, so an app that has already answered in the UI is
+  // not overwritten by a default nobody chose.
+  if (config.contentRights === undefined) {
+    console.log(yellow("  contentRights not declared — Add for Review needs it; set `contentRights: false` if the app uses no third-party content."));
+    return true;
+  }
+  const declaration = RIGHTS[String(config.contentRights)];
+  const a = await client.patch(`/v1/apps/${client.appId}`, {
+    data: { type: "apps", id: client.appId, attributes: { contentRightsDeclaration: declaration } },
+  });
+  if (a.status >= 300) {
+    console.error(red(`appinfo: content rights ${a.status}`));
+    for (const e of a.json?.errors || []) console.error(`    ${e.title}: ${e.detail}`);
+    return false;
+  }
+  console.log(client.dryRun
+    ? yellow(`  WOULD set content rights -> ${declaration}`)
+    : green(`  content rights -> ${declaration}`));
+  return true;
+}

package/src/commands/bridge.mjs

@@ -0,0 +1,328 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { green, yellow, red } from "../util.mjs";
+import { toAsc } from "../locales.mjs";
+import { IOS_DEVICE, MAC_DEVICE, screenshotBase, IMAGE_FILE } from "../screenshots.mjs";
+import { playImages } from "../play/images.mjs";
+
+/**
+ * Map zdymak's build output onto the folders `fill` uploads from.
+ *
+ * WHY THIS EXISTS. zdymak and vydanne were documented as lining up with "no glue", and they used to:
+ * zdymak's default output paths were exactly vydanne's read paths. As of zdymak 0.15.0 they are not.
+ * zdymak writes everything under ONE root (`out:` in zdymak.config.mjs, default `./store-assets`)
+ * shaped `<locale>/<dir>/NN-name.png`, while vydanne reads several roots in a different shape. Three
+ * things differ, so no amount of retuning `out` can fix it:
+ *
+ *   1. SEVERAL roots (the screenshot bases, the Play image sources) versus one `out`.
+ *   2. Locale CODES — zdymak writes `de`, `zh`, `ur`; Apple wants `de-DE`, `zh-Hans`, `ur-PK`.
+ *   3. The slot PREFIX — `fill` picks the device slot from the token before the first underscore, so a
+ *      file must be named `iphone69_…`; zdymak names it `01-fresh.png`.
+ *
+ * The failure mode is the dangerous one: `zdymak screenshots` reports success for every locale and
+ * writes nothing vydanne can see, so `fill` re-uploads whatever was in the screenshots folder from the
+ * last time the two tools agreed — silently shipping stale store art. One app shipped exactly that, its
+ * screenshots four days older than its own store-assets. So the mapping lives HERE, in the uploader,
+ * where the locale table (`toAsc`), the slot tokens (IOS_DEVICE) and the Play read paths (playImages)
+ * are the very values `fill` uploads by — imported, not copied, so the bridge cannot drift from the
+ * thing it feeds.
+ *
+ * SOURCE DIRECTORIES ARE NOT TARGET NAMES. zdymak writes each shot to `<dir || target>`, and `dir:` is
+ * how one target serves two purposes — a styled `play-phone/` for the website and a plain
+ * `play-phone-plain/` for the Play upload, which Google requires to be the bare interface. It is also
+ * the only way to produce Play's 7" slot at all: there is no `play-tablet7` target, so that set can
+ * only exist as `{ target: 'play-tablet', dir: 'play-tablet7-plain' }`. Mapping by TARGET therefore got
+ * two things wrong at once on any config using `dir:` — it bridged the styled variant into the plain
+ * slot, and it treated the real 7" directory as a locale while wiping the destination it belonged in.
+ * So the tables below are keyed by DIRECTORY, with the `-plain` convention preferred and the bare
+ * target name as the fallback, and `bridge.apple` / `bridge.play` in vydanne.config.mjs override both.
+ *
+ * OWNERSHIP, NOT REBUILD-IF-PRESENT. The destinations are rebuilt from empty so a screenshot removed
+ * upstream disappears here too instead of lingering and being uploaded forever — but only for a store
+ * the bridge actually produced files for this run. Resetting a root the bridge did not fill would
+ * delete the screenshots of someone who uses zdymak for Play and manages Apple's by hand; resetting it
+ * only when something happened to land in it is how dropped macOS art survived a form factor being
+ * removed from zdymak.config.mjs. Per STORE is the line that satisfies both: any Apple output at all
+ * means the bridge owns both Apple roots, including the macOS one it wrote nothing into today.
+ *
+ * Local files only — nothing touches a store, which is why this command takes no `--apply`; pass
+ * `--dry-run` to see exactly what a real run would write and remove.
+ */
+
+// Filename token that selects an App Store display type -> the zdymak output directory it comes from.
+// The tokens are asserted against IOS_DEVICE/MAC_DEVICE at load: a token `fill` does not understand
+// would make every bridged file silently ignorable, which is the exact class of failure this command
+// exists to close.
+const APPLE_SLOTS = {
+  iphone69: "appstore-iphone-6.9",
+  iphone65: "appstore-iphone-6.5",
+  ipad13: "appstore-ipad-13",
+  watch: "appstore-watch",
+};
+/** macOS screenshots live under a different root entirely, so they are carried separately. */
+const MAC_SLOT = { macos: "appstore-mac" };
+
+for (const t of Object.keys(APPLE_SLOTS)) {
+  if (!(t in IOS_DEVICE)) throw new Error(`bridge: slot token '${t}' unknown to fill — update APPLE_SLOTS`);
+}
+for (const t of Object.keys(MAC_SLOT)) {
+  if (!(t in MAC_DEVICE)) throw new Error(`bridge: slot token '${t}' unknown to fill — update MAC_SLOT`);
+}
+
+// Play image type -> candidate source directories, in preference order. The `-plain` set is what Google
+// asks for on a store listing ("no additional text, graphics, or backgrounds that are not part of the
+// interface"), so it wins when both exist; the bare target name is what a config with no `dir:` override
+// produces. The Play icon is deliberately absent: it comes from znachok, not zdymak, and is already at
+// its read path.
+const PLAY_SOURCES = {
+  phoneScreenshots: ["play-phone-plain", "play-phone"],
+  sevenInchScreenshots: ["play-tablet7-plain", "play-tablet7"],
+  tenInchScreenshots: ["play-tablet-plain", "play-tablet"],
+  wearScreenshots: ["play-wear-plain", "play-wear"],
+  tvScreenshots: ["play-tv-plain", "play-tv"],
+  featureGraphic: ["play-feature-graphic.png"],
+  tvBanner: ["play-tv-banner.png"],
+};
+
+// A directory under `out` that is shaped like a locale code. Everything zdymak writes at that level is
+// either an output directory or a locale, and the old rule — "not a known target, therefore a locale" —
+// turned every `dir:` override into a phantom locale (`play-phone-plain`, `appstore-iphone-6.9-dark`)
+// that then failed to resolve and was reported as falling back to the primary listing.
+const LOCALE_SHAPED = /^[a-z]{2,3}(-[A-Za-z]{2,4}|-[0-9]{3})?$/;
+
+const dirsIn = (p) => (fs.existsSync(p) ? fs.readdirSync(p, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name) : []);
+const imagesIn = (p) => (fs.existsSync(p) ? fs.readdirSync(p).filter((f) => IMAGE_FILE.test(f)).sort() : []);
+
+/**
+ * What zdymak is configured to write: its `out`, and every directory name it produces.
+ *
+ * Read from the app's own zdymak.config.mjs so the two tools cannot disagree about the layout. Absent
+ * or unreadable is fine — the directory names are then discovered from disk instead, which is enough
+ * for the common case and only loses the ability to tell a `dir:` override apart from a locale by
+ * anything other than its shape.
+ */
+async function readZdymak(config) {
+  const out = { root: config.bridge?.out || "./store-assets", knownDirs: new Set(), fromConfig: false };
+  const file = path.resolve("zdymak.config.mjs");
+  if (!fs.existsSync(file)) return out;
+  let cfg;
+  try {
+    cfg = (await import(pathToFileURL(file).href)).default;
+  } catch (e) {
+    // A config that imports `zdymak` in a project where zdymak is not installed is the likeliest cause,
+    // and "Cannot find package 'zdymak'" on its own does not suggest a fix.
+    console.log(yellow(`bridge: could not read zdymak.config.mjs (${e.message.split("\n")[0]})`));
+    console.log("  Falling back to directory names on disk. Install zdymak, or set `bridge.out` in vydanne.config.mjs.");
+    return out;
+  }
+  if (!cfg) return out;
+  out.fromConfig = true;
+  if (!config.bridge?.out && cfg.out) out.root = cfg.out;
+  const devices = Array.isArray(cfg.devices) ? cfg.devices : Object.values(cfg.devices || {});
+  for (const d of devices) {
+    for (const s of d?.screenshots || []) {
+      if (!s?.target) continue;
+      // Icons and feature graphics are written as `<target>.png` at the root, ignoring `dir` — see
+      // zdymak/src/screenshots.mjs. Both spellings are recorded so neither can be mistaken for a locale.
+      out.knownDirs.add(s.dir || s.target);
+      out.knownDirs.add(s.target);
+    }
+  }
+  return out;
+}
+
+/** First candidate directory that exists under `from`, or null. */
+const pick = (from, candidates) => candidates.find((c) => fs.existsSync(path.join(from, c))) ?? null;
+
+/** Empty a directory, keeping the directory itself. */
+function reset(p) {
+  fs.rmSync(p, { recursive: true, force: true });
+  fs.mkdirSync(p, { recursive: true });
+}
+
+export async function run(config) {
+  const dryRun = process.argv.includes("--dry-run");
+  const zd = await readZdymak(config);
+  const SRC = path.resolve(zd.root);
+  if (!fs.existsSync(SRC)) {
+    console.error(red(`bridge: no ${path.relative(process.cwd(), SRC)} — run \`zdymak screenshots\` (or \`zdymak build\`) first.`));
+    return false;
+  }
+
+  const appleSlots = { ...APPLE_SLOTS, ...(config.bridge?.apple || {}) };
+  const macSlots = Object.fromEntries(
+    Object.entries({ ...MAC_SLOT, ...(config.bridge?.apple || {}) }).filter(([t]) => t in MAC_DEVICE),
+  );
+  const iosSlots = Object.fromEntries(Object.entries(appleSlots).filter(([t]) => t in IOS_DEVICE));
+  const playSources = { ...PLAY_SOURCES, ...(config.bridge?.play || {}) };
+
+  const APPLE = path.resolve(screenshotBase("IOS", config));
+  const APPLE_MAC = path.resolve(screenshotBase("MAC_OS", config));
+
+  // ── PLAN FIRST, WRITE SECOND ────────────────────────────────────────────────────────────────────
+  // Nothing below touches the disk. The old shape reset the destination at the top and discovered it
+  // had nothing to put there at the bottom — so an empty `store-assets` emptied the screenshots folder
+  // and *then* reported failure, and a `--dry-run` could not check the files a real run would refuse
+  // because they had not been copied yet. Planning first makes the dry run exact and the failure paths
+  // non-destructive, at the cost of one array.
+  const plan = []; // { from, to, store: 'apple' | 'play' }
+  const noListing = [];
+  const noLanguage = [];
+  const ignored = [];
+  const carried = new Set();
+  const written = new Set();
+
+  // ── Apple ───────────────────────────────────────────────────────────────────────────────────────
+  // The root of store-assets holds the untranslated (primary) set; a locale-shaped directory beside it
+  // is a translated one.
+  // Everything the bridge itself knows how to read counts as a known output, whether or not
+  // zdymak.config.mjs was readable — otherwise a project with no zdymak config has each of its own
+  // source directories reported as "neither an output nor a locale" while being bridged correctly.
+  const knownDirs = new Set([
+    ...zd.knownDirs,
+    ...Object.values(appleSlots).flat(),
+    ...Object.values(macSlots).flat(),
+    ...Object.values(playSources).flat(),
+  ]);
+  const localeDirs = dirsIn(SRC).filter((d) => {
+    if (knownDirs.has(d)) return false;
+    if (LOCALE_SHAPED.test(d)) return true;
+    ignored.push(d);
+    return false;
+  });
+
+  for (const source of [null, ...localeDirs]) {
+    const from = source ? path.join(SRC, source) : SRC;
+    const asc = source ? toAsc(source, config.localeMap) : config.primaryLocale;
+    // A code with no App Store language (Belarusian) is skipped — a locale with no folder falls back
+    // to the primary listing, which is the intent.
+    if (!asc) { noLanguage.push(source); continue; }
+
+    // Only ship screenshots for a locale that also has LISTING TEXT. Uploading them alone makes fill
+    // create the App Store localization to attach them to, and a created localization stops falling
+    // back to the primary one — the store would show a page with pictures and an empty description
+    // instead of the primary text it shows today. Silent, and worse than not translating at all. When
+    // the copy for a locale lands, this picks its screenshots up with no edit here.
+    if (!fs.existsSync(path.join(config.metadataDir, asc))) { noListing.push(asc); continue; }
+
+    for (const [root, slots] of [[APPLE, iosSlots], [APPLE_MAC, macSlots]]) {
+      for (const [slot, candidates] of Object.entries(slots)) {
+        const dir = pick(from, [candidates].flat());
+        if (!dir) continue;
+        for (const img of imagesIn(path.join(from, dir))) {
+          // fill selects the display type off the token before the first underscore, so an unprefixed
+          // copy would be a file it silently ignores, in the folder where it looks.
+          plan.push({ from: path.join(from, dir, img), to: path.join(root, asc, `${slot}_${img}`), store: "apple" });
+          carried.add(dir);
+          written.add(asc);
+        }
+      }
+    }
+  }
+
+  // ── Play ────────────────────────────────────────────────────────────────────────────────────────
+  // Only the untranslated root is carried: Play graphics default to one set at `defaultLocale`, and an
+  // app that opts into per-language art (`google.imageLocales`) points `fill` at the subdirectories it
+  // maintains itself.
+  const playDest = Object.fromEntries(playImages(config).map(([type, src, kind]) => [type, { src, kind }]));
+  const playDirs = new Set();
+  const playCarried = new Set();
+  for (const [type, candidates] of Object.entries(playSources)) {
+    const dest = playDest[type];
+    if (!dest) continue; // a type this app's images table doesn't have — nothing reads it, so skip it
+    if (dest.kind === "file") {
+      const file = [candidates].flat().map((c) => path.join(SRC, c)).find((p) => fs.existsSync(p));
+      if (!file) continue;
+      plan.push({ from: file, to: path.resolve(dest.src), store: "play" });
+      playCarried.add(path.basename(file));
+      continue;
+    }
+    const dir = pick(SRC, [candidates].flat());
+    // Owned when zdymak produces it, and ALSO when it merely still exists from a previous run — that
+    // second half is the point: a form factor dropped from zdymak.config.mjs must stop being uploaded,
+    // and "no new files" is exactly when the old ones would otherwise survive forever. A slot with
+    // neither is a slot this app does not use, and creating an empty directory for it would only
+    // invent a set for `fill` to report on.
+    if (dir || fs.existsSync(dest.src)) playDirs.add(path.resolve(dest.src));
+    if (!dir) continue;
+    for (const img of imagesIn(path.join(SRC, dir))) {
+      plan.push({ from: path.join(SRC, dir, img), to: path.resolve(dest.src, img), store: "play" });
+      playCarried.add(dir);
+    }
+  }
+
+  const appleCount = plan.filter((p) => p.store === "apple").length;
+  const playCount = plan.filter((p) => p.store === "play").length;
+
+  if (!appleCount && !playCount) {
+    console.error(red("bridge: nothing was bridged — check that zdymak actually wrote store-assets."));
+    if (ignored.length) console.error(`  neither a zdymak output nor a locale: ${ignored.join(", ")}`);
+    console.error("  Nothing was removed; every destination is untouched.");
+    return false;
+  }
+
+  // ── Apple rejects alpha, so catch it on the SOURCES, before anything is copied ──────────────────
+  // Checked here rather than after the copy for two reasons: a dry run can now report the refusal a
+  // real run would hit, and a real run no longer leaves the rejected file sitting in the folder `fill`
+  // uploads from — where the next run would send it to Apple and collect the rejection anyway.
+  const appleFiles = plan.filter((p) => p.store === "apple");
+  if (appleFiles.length) {
+    const { default: sharp } = await import("sharp");
+    const withAlpha = [];
+    for (const p of appleFiles) {
+      if ((await sharp(p.from).metadata()).hasAlpha) withAlpha.push(path.relative(process.cwd(), p.from));
+    }
+    if (withAlpha.length) {
+      console.error(red("bridge: these carry an alpha channel and Apple will reject them:"));
+      for (const p of withAlpha) console.error(`  ${p}`);
+      console.error("  Flatten at the source (zdymak), or per file: VYDANNE_FLATTEN=<png> vydanne iap");
+      console.error("  Nothing was copied; every destination is untouched.");
+      return false;
+    }
+  }
+
+  // ── Write ───────────────────────────────────────────────────────────────────────────────────────
+  // Ownership is per STORE: producing any Apple output means the bridge owns both Apple roots, so the
+  // macOS one is emptied even on a run that wrote nothing into it. An app that bridges only Play never
+  // has its hand-managed Apple screenshots touched, and vice versa.
+  const countFiles = (root) => {
+    if (!fs.existsSync(root)) return 0;
+    let n = imagesIn(root).length;
+    for (const d of dirsIn(root)) n += imagesIn(path.join(root, d)).length;
+    return n;
+  };
+  const owned = [
+    ...(appleCount ? [APPLE, APPLE_MAC] : []),
+    ...(playCount ? [...playDirs] : []),
+  ];
+  const removals = owned.map((root) => [root, countFiles(root)]).filter(([, n]) => n);
+
+  if (!dryRun) {
+    for (const root of owned) reset(root);
+    for (const p of plan) {
+      fs.mkdirSync(path.dirname(p.to), { recursive: true });
+      fs.copyFileSync(p.from, p.to);
+    }
+  }
+
+  // ── Report ──────────────────────────────────────────────────────────────────────────────────────
+  console.log(`▸ Apple → ${path.relative(process.cwd(), APPLE)}`);
+  console.log(`    ${appleCount} files · ${written.size} locale(s) · ${[...carried].join(", ") || "nothing"}`);
+  if (noLanguage.length) console.log(`    no App Store language, falls back to ${config.primaryLocale}: ${noLanguage.join(" ")}`);
+  if (noListing.length) console.log(`    held back (screenshots ready, listing text missing): ${noListing.join(" ")}`);
+
+  console.log(`▸ Play → ${[...playDirs].map((d) => path.relative(process.cwd(), d)).join(", ") || "nothing"}`);
+  console.log(`    ${playCount} files · ${[...playCarried].join(", ") || "nothing"}`);
+
+  // Said every run, because "what the bridge is about to delete" is the one thing a dry run exists to
+  // show — and because a destination emptied on purpose (its form factor dropped upstream) looks
+  // exactly like one that was never filled.
+  for (const [root, n] of removals) {
+    console.log(yellow(`    ${dryRun ? "would replace" : "replaced"} ${n} existing file(s) in ${path.relative(process.cwd(), root)}`));
+  }
+  if (ignored.length) console.log(yellow(`    ignored (neither a zdymak output nor a locale): ${ignored.join(", ")}`));
+
+  console.log(green(dryRun ? "✓ dry run — nothing written" : "✓ bridged — `vydanne fill` can now find every set"));
+  return true;
+}

package/src/commands/compliance.mjs

@@ -1,13 +1,70 @@
 import PDFDocument from "pdfkit";
 import fs from "node:fs";
-import { green, yellow } from "../util.mjs";
+import { green, yellow, red } from "../util.mjs";
+
+/**
+ * The US encryption self-classification report PDF (ECCN 5D002, License Exception ENC 740.17(b)(1)) —
+ * the document for the ASC "App Encryption Documentation" US slot. France is a separate ANSSI territory
+ * upload; the US needs no CCATS. Native pdfkit, no Python.
+ *
+ * THIS COMMAND MAKES LEGAL ASSERTIONS, SO IT DOES NOT GUESS. It used to hold a hardcoded cryptography
+ * inventory — AES-GCM, HMAC-SHA256, Ed25519, "resolves to Apple CryptoKit" — and a statement claiming
+ * the product did end-to-end encryption for cross-device sync and that "a self-classification report
+ * has been submitted to BIS and the NSA". Every app the tool was pointed at got the same page. That is
+ * wrong twice over: it describes cryptography an app may not contain, and it asserts a filing with two
+ * US government agencies that whoever ran the command may never have made. A wrong screenshot costs a
+ * review cycle; this is a document someone signs their company's name under.
+ *
+ * So the app declares its own inventory and its own statement, exactly the way `accessibility` declares
+ * its own claims, and for the same reason: silence is not consent. `export.filed` is separate and
+ * defaults to false, because "we intend to file" and "we have filed" are different sentences and only
+ * the filer knows which is true.
+ */
+
+const EXAMPLE = `  export: {
+    encryption: "standard",          // "standard" | "none" | "exempt"
+    appName: "Your App",
+    version: "1.2",
+    teamId: "ABCDE12345",
+    // What the app actually contains. Every row is [purpose, algorithm, key size].
+    algorithms: [
+      ["Transport", "TLS 1.2 / 1.3", "standard"],
+    ],
+    // One paragraph in your own words, describing what the app does with cryptography.
+    statement: "The product uses TLS for network transport only. It is a mass-market consumer " +
+      "application distributed through public app stores, uses only standard published algorithms, " +
+      "and qualifies for export under License Exception ENC, EAR 740.17(b)(1), ECCN 5D002.",
+    // Only true once the report has ACTUALLY been emailed to BIS and the NSA.
+    filed: false,
+  },`;
+
+/** Returns a human-readable problem, or null when the declaration is usable. */
+export function validate(config) {
+  const e = config.export || {};
+  if ((e.encryption || "standard") !== "standard") return null; // nothing to self-classify
+  const missing = [];
+  if (!Array.isArray(e.algorithms) || !e.algorithms.length) missing.push("algorithms");
+  if (typeof e.statement !== "string" || !e.statement.trim()) missing.push("statement");
+  if (!missing.length) return null;
+  return [
+    `compliance: export.${missing.join(" and export.")} missing.`,
+    "This command generates a US export-compliance document that makes factual claims about your",
+    "app's cryptography. It will not supply them for you — the previous default described a specific",
+    "app's crypto and asserted a BIS/NSA filing, for every app it was run against.",
+    "",
+    "Declare what your app actually contains:",
+    "",
+    EXAMPLE,
+  ].join("\n");
+}
 
-// Generate the US encryption self-classification report PDF (ECCN 5D002, License Exception ENC 740.17(b)(1))
-// for standard-crypto apps — the document for the ASC "App Encryption Documentation" US slot. France = a
-// separate ANSSI territory upload; US needs no CCATS. Native pdfkit (no python).
 export async function run(config) {
   const e = config.export || {};
-  if ((e.encryption || "standard") !== "standard") { console.log(yellow("export.encryption != standard — nothing to self-classify")); return true; }
+  if ((e.encryption || "standard") !== "standard") { console.log(yellow(`export.encryption = ${e.encryption} — nothing to self-classify`)); return true; }
+
+  const problem = validate(config);
+  if (problem) { console.error(red(problem)); return false; }
+
   const appName = e.appName || config.bundleId.split(".").pop();
   const out = `export-compliance/${config.bundleId}-US-encryption-self-classification.pdf`;
   fs.mkdirSync("export-compliance", { recursive: true });
@@ -27,19 +84,31 @@ export async function run(config) {
     h("Classification");
     kv("ECCN:", "5D002 (encryption 'software')"); kv("Authorization:", "License Exception ENC, EAR 740.17(b)(1)"); kv("Basis:", "Mass-market, self-classified (Note 3 to Cat. 5 Part 2)");
     h("Cryptography inventory");
-    p("The application uses only standard, published cryptographic algorithms (NIST / IETF). No proprietary or non-standard cryptography is implemented. On Apple platforms the primitives resolve to Apple CryptoKit.");
+    p("The application uses only standard, published cryptographic algorithms (NIST / IETF). No proprietary or non-standard cryptography is implemented.");
     doc.moveDown(0.4);
-    for (const [purpose, alg, ks] of [["Content & media confidentiality", "AES-GCM (AEAD)", "256-bit"], ["Key derivation / addressing", "HMAC-SHA256", "256-bit"], ["Token signing", "Ed25519", "255-bit curve"], ["Transport", "TLS 1.2 / 1.3", "standard"]]) {
-      doc.font("Helvetica").fontSize(10.5).fillColor("#1e1e1e").text(`•  ${purpose} — ${alg} (${ks})`);
+    for (const row of e.algorithms) {
+      const [purpose, alg, ks] = row;
+      doc.font("Helvetica").fontSize(10.5).fillColor("#1e1e1e").text(`•  ${purpose} — ${alg}${ks ? ` (${ks})` : ""}`);
     }
     h("Statement");
-    p("The product provides general data-confidentiality end-to-end encryption of the user's own data for optional cross-device sync. It is a mass-market consumer application distributed through public app stores, uses only standard published algorithms, and qualifies for export under License Exception ENC, EAR 740.17(b)(1), ECCN 5D002. A self-classification report has been submitted to BIS (crypt-supp8@bis.doc.gov) and the NSA (enc@nsa.gov).");
+    // The declared statement, and NOTHING appended to it. The filing sentence is added only when the
+    // app says the filing happened, because a PDF that claims it has been submitted is the one thing
+    // here that cannot be walked back.
+    p(e.statement.trim());
+    if (e.filed) {
+      doc.moveDown(0.4);
+      p("A self-classification report has been submitted to BIS (crypt-supp8@bis.doc.gov) and the NSA (enc@nsa.gov).");
+    }
     doc.end();
     stream.on("finish", resolve);
     stream.on("error", reject);
   });
 
   console.log(green(`wrote ${out}`));
+  if (!e.filed) {
+    console.log(yellow("  export.filed is false — the PDF does NOT claim the report was submitted."));
+    console.log("  Email it to crypt-supp8@bis.doc.gov and enc@nsa.gov, then set export.filed: true.");
+  }
   if (e.france) console.log(yellow("France: file + upload the ANSSI declaration too (territory rule). US: email BIS+NSA, no CCATS."));
   return true;
 }