vydanne 0.2.0

package/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: vydanne
+description: Prepare an App Store Connect / Google Play submission — write AND push the localized store listing. Crafts the ASO copy (app-store name, subtitle, the 100-char keyword field, description, promo text), then fills the listing + screenshots + previews, age rating, review contact, accessibility & App Privacy labels, IAP fields, and export-compliance docs; verifies with a preflight gate and diffs local-vs-live. Native Node (ES256 JWT + fetch, no fastlane/Ruby). One vydanne.config.mjs per app. Use when writing or shipping any App Store / Play listing. Never submits — a human attaches the signed build and hits Submit.
+---
+
+# vydanne
+
+The App Store Connect / Google Play half of a two-part release pipeline. Native Node — no
+fastlane/Ruby/Python. Two jobs: **(A) write the listing well (ASO)**, **(B) push it + the declarations**.
+
+**Companion tool — [zdymak](https://www.npmjs.com/package/zdymak)** makes the *media* (screenshots, App
+Preview videos, Play feature graphic); vydanne pushes that media plus all the *text and paperwork*. If the
+user needs screenshots or a preview video produced, that's zdymak's job, not vydanne's — vydanne only
+uploads files that already exist. zdymak's default output paths are exactly the paths vydanne reads for
+Play images (below), so the two line up with no glue.
+
+**Never submits.** A human attaches the signed build and presses Submit. Don't try to work around this.
+
+## Setup
+
+`npm i -D vydanne`, then **`npx vydanne <cmd>` from the app's repo root** — the config and every relative
+path in it resolve against the working directory. Running from a subfolder silently reads the wrong paths.
+
+One `vydanne.config.mjs` per app (schema: `vydanne.config.example.mjs`; type
+`import('vydanne').VydanneConfig`). Auth: `~/.appstoreconnect/private_keys/AuthKey_<keyId>.p8` +
+`ASC_KEY_ID` / `ASC_ISSUER_ID`; Play uses `PLAY_JSON_KEY_FILE`. Node ≥20.9. Cross-platform — the key path
+resolves via `os.homedir()`, so it works on Windows (`C:\Users\<you>\.appstoreconnect\…`). On Windows
+PowerShell the `VAR=1 cmd` form does **not** exist; set `$env:VAR = "1"` first.
+
+**Config fields:** `bundleId` · `primaryLocale` (the fallback — must be populated) · `asc` (optional
+`{keyId, issuerId}`) · `platforms` (iOS and macOS are SEPARATE) · `uiLocales` (auto-mapped to ASC codes) ·
+`metadataDir` · `rating` · `privacy` · `iaps` · `previews` · `export` · `google` (Google Play).
+
+For a non-technical user asking how to set this up from scratch, walk them through
+**`GETTING_STARTED.md`** (accounts → API key → config → folders → push) rather than improvising.
+
+## File layout — read this before writing any file
+
+vydanne reads plain `.txt` files from fixed locations. **These conventions are not configurable beyond
+`metadataDir`; do not invent paths.**
+
+**Apple listing text** — `<metadataDir>/<ASC-locale>/*.txt` (default `metadataDir`: `fastlane/metadata`):
+
+| File | Field | Limit |
+|---|---|---|
+| `name.txt` | app name (on **AppInfo**, shared across platforms) | 30 |
+| `subtitle.txt` | subtitle (on AppInfo) | 30 |
+| `description.txt` | description (on the **version**) | 4000 |
+| `keywords.txt` | keyword field (version) | 100 |
+| `promotional_text.txt` | promo text (version) | 170 |
+| `release_notes.txt` | what's new (version) | — |
+| `marketing_url.txt`, `support_url.txt` | optional URLs (version) | — |
+
+Folder names must be **Apple's exact ASC codes** (`de-DE`, `ar-SA`, `zh-Hans`, `en-GB`…). A folder whose
+name isn't in the valid set is skipped; run `vydanne locales` to get the mapping from the config's
+`uiLocales`. A language with no App Store equivalent (e.g. Belarusian `be`) must **not** get a folder — it
+falls back to `primaryLocale`.
+
+**App Review contact** — `<metadataDir>/review_information/{first_name,last_name,phone_number,email_address,notes}.txt`.
+This is PII: keep it gitignored.
+
+**Apple screenshots** — `fastlane/screenshots/<ASC-locale>/<prefix>_<anything>.png`, and
+`fastlane/screenshots-macos/<ASC-locale>/…` for Mac. **These two base paths are hardcoded.** The token
+before the **first underscore** selects the device slot; files upload in sorted order, so number them:
+
+| Prefix | Slot |
+|---|---|
+| `iphone69_` | `APP_IPHONE_67` (6.9″) |
+| `iphone65_` | `APP_IPHONE_65` |
+| `ipad13_` | `APP_IPAD_PRO_3GEN_129` |
+| `watch_` | `APP_WATCH_ULTRA` |
+| `macos_` | `APP_DESKTOP` (in `screenshots-macos/`) |
+
+An unknown prefix is silently ignored. A set that **already has screenshots is skipped**, never
+duplicated — to replace shots, delete them in ASC first. PNGs must be **RGB with no alpha**.
+
+**Play listing text** — `<google.metadataDir>/<PLAY-locale>/{title,short_description,full_description}.txt`
+(30 / 80 / 4000). Play uses its **own** codes (`de-DE`, `zh-CN`, `iw-IL`, `ar`, `be`) — *not* Apple's
+`zh-Hans`/`he`/`ar-SA`.
+
+**Play images** — hardcoded source paths (zdymak's output), each pushed only when the file exists, so a
+missing local set never deletes the live one: `brand/icons/play/icon-512.png` (512²) ·
+`marketing/out/play-feature-graphic.png` (1024×500) · `marketing/out/play-phone-plain/` ·
+`marketing/out/play-tablet7-plain/` (7″) · `marketing/out/play-tablet-plain/` (10″).
+
+## A. Writing the listing (the ASO craft — the durable value)
+
+**Write the English master first, then localize.**
+
+### The fields, what they're FOR, and the hard limits
+
+| Field | Limit | Indexed for search? | Job |
+|---|---|---|---|
+| `name` | 30 | **Yes (highest weight)** | Brand + the single strongest keyword. Must be globally UNIQUE. |
+| `subtitle` | 30 | **Yes** | A second keyword-bearing benefit line — NOT a repeat of the name. |
+| `keywords` (App Store only) | 100 | **Yes** | The biggest lever. Comma-separated, **no spaces**. |
+| `promotional_text` | 170 | No | Rotating hook (sale/seasonal); editable anytime with no review. |
+| `description` | 4000 | **App Store: NO** / **Play: YES** | Conversion copy for the human. On Play it's also indexed → bake keywords in naturally. |
+| Play `title`/`short`/`full` | 30/80/4000 | short + full **Yes** | Play has NO keyword field → keywords go in title + short + full. |
+
+### The keyword field — the rules people get wrong (App Store)
+
+- **No spaces** after commas (`a,b,c` not `a, b, c`) — every char counts toward 100. **Fill all 100.**
+- **Don't repeat** any word already in `name` or `subtitle` — Apple already indexes those; repeating wastes the field.
+- **Singular OR plural, never both** — Apple matches both stems; pick one (usually singular).
+- **Omit** "app", "game", "free", and the app's own name — Apple indexes those automatically.
+- Apple **auto-combines** keywords into phrases (kw+kw), so prefer **single words** to maximize combinations — no multi-word phrases unless the phrase is the exact search term.
+- **No competitor trademarks** (rejection risk, especially for games).
+- Prioritize by **relevance × search volume × achievable rank**: generic head terms are hard to rank; mid-tail terms convert AND rank. Order best-first (leading keywords weigh more).
+
+### Positioning — ground it in the app's real audience, not generic hype
+
+Before writing, establish what actually motivates *this* app's users (ask the user, or read whatever
+audience research/positioning docs the repo has). Then:
+
+- **Lead with the strongest shared motivation**, stated concretely — not a feature list.
+- **Name the genuine differentiator plainly.** If there's one thing competitors can't claim, say it in
+  the subtitle, not buried in paragraph four.
+- **Match the audience's temperature.** A calm, premium audience reacts badly to hype punctuation and
+  competitive framing; a competitive audience finds understatement flat. Mirror the in-app voice.
+- **Be honest in the close** — "no ads", "no account", "buy once" only if true. Claims here are checkable.
+- Don't lead with mechanics the audience doesn't care about (leaderboards, streaks) just because they exist.
+
+### Description shape (App Store & Play)
+
+Hook (1–2 lines: the promise) → **WHY \<APP\>** (3–5 benefit bullets, each benefit-first) → what it is /
+who it's for → honest close. Keep it scannable; lead each bullet with the payoff, not the feature.
+
+### Localizing the listing (transcreation, not translation)
+
+- **App name**: the brand is **never** translated; the DESCRIPTOR may be localized per store locale.
+- **Keywords**: use the target market's **actual search terms**, not a dictionary translation. Research
+  per market — the literal translation of a category name is often not what people type.
+- **Subtitle / promo / description**: **transcreate** — adapt benefit + tone naturally; never word-for-word.
+- **Fan out one agent per locale** (a Sonnet-tier translator/copywriter is the right size). Give each:
+  the master English copy, the target locale, its `<metadataDir>/<ASC-locale>/` directory, the brand name
+  (untranslated), the character limits, and the positioning above. Validate limits after the merge —
+  translations routinely blow the 30-char fields.
+
+## B. Commands (push it)
+
+`fill` (metadata + screenshots, native PATCH/chunked upload — works even at READY_FOR_REVIEW) ·
+`previews` (App Preview videos) · `age-rating` · `review-contact` · `accessibility` (draft; publish once
+live) · `privacy` (prints answers for the UI — the API can't reach Apple's iris host) · `iap` (validate +
+RGB flatten) · `compliance` (US self-classification PDF) · `diff` (what differs vs live) · `preflight`
+(completeness gate) · `inspect` · `locales` · `version`.
+
+`--store google` routes `inspect` · `diff` · `preflight` · `fill` to the Play Developer **Edits** API
+(OAuth2 service account; **scoped to the config's `packageName`** — a shared key can't touch another app).
+`fill --store google` is **DRY by default**; `VYDANNE_COMMIT=1` commits. The AAB binary and the
+(YouTube-URL) promo video stay outside vydanne.
+
+**Env toggles:** `VYDANNE_CONFIG` · `VYDANNE_SKIP_METADATA` / `VYDANNE_SKIP_SCREENSHOTS` (fill) ·
+`VYDANNE_COMMIT` (Play fill) · `VYDANNE_REPLACE` (previews) · `VYDANNE_FLATTEN=<png>` (iap) ·
+`VYDANNE_A11Y_PUBLISH` (accessibility).
+
+## Flow
+
+config → **write the English master listing (ASO, research-grounded)** → `preflight` (char limits) → fan
+out one copywriter agent per locale → media from zdymak → `fill` + `previews` + declarations → `diff`
+(dry-run) → `preflight` (must be green) → **a human submits**.
+
+## Gotchas it encodes (don't re-derive)
+
+ASC locale folder codes must be exact (`de`→`de-DE`; a bad one aborts the upload) · `name`/`subtitle` on
+AppInfo vs `description`/`keywords`/`promo` on the version · macOS is a separate platform · list endpoints
+return sparse/empty text (read each localization by id) · primary locale must be populated · App Privacy is
+on the `iris` host (JWT 401s — UI only) · accessibility can't publish until live (409) · edit-version /
+app-info / deliver all break at READY_FOR_REVIEW (fetch by id; native PATCH still works) ·
+screenshots/IAP images must be RGB no-alpha · IAP has two image slots (tall review screenshot vs 1024²
+promo) · char limits (name/subtitle 30, keywords 100, promo 170; IAP name 30 / desc 45; Play title 30 /
+short 80 / full 4000) · **Play uses its OWN locale codes** · Play images push only when the local file
+exists, so a missing set never wipes the live one · Apple requires `name` when *creating* an app-info
+localization (409 otherwise).

package/bin/vydanne.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { loadConfig } from "../src/config.mjs";
+import { Client } from "../src/client.mjs";
+import { COMMANDS, PLAY_COMMANDS } from "../src/registry.mjs";
+
+const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url))).version;
+
+const argv = process.argv.slice(2);
+const cmd = argv.shift();
+const i = argv.indexOf("--config");
+const cfgPath = i >= 0 ? argv[i + 1] : undefined;
+const si = argv.indexOf("--store");
+const store = si >= 0 ? argv[si + 1] : "apple";
+
+try {
+  if (["version", "-v", "--version"].includes(cmd)) {
+    console.log(`vydanne ${VERSION}`);
+  } else if (cmd === "locales") {
+    const r = (await loadConfig(cfgPath)).resolvedLocales;
+    console.log(`supported (${Object.keys(r.supported).length}):`);
+    for (const [ui, asc] of Object.entries(r.supported)) console.log(`  ${ui} -> ${asc}`);
+    console.log(`unsupported (${r.unsupported.length}) [no App Store language -> fall back to primary]: ${r.unsupported.join(", ")}`);
+  } else if (store === "google") {
+    const cfg = await loadConfig(cfgPath);
+    if (!cfg.google) throw new Error("vydanne: no `google` block in config — add packageName + a service-account key");
+    if (!PLAY_COMMANDS[cmd]) throw new Error(`vydanne: '${cmd}' isn't available for --store google (try: ${Object.keys(PLAY_COMMANDS).join(", ")})`);
+    if (!cfg.google.serviceAccountKey) throw new Error("vydanne: set PLAY_JSON_KEY_FILE (or google.serviceAccountKey) to the Play service-account JSON");
+    const { PlayClient } = await import("../src/play/client.mjs");
+    const client = await PlayClient.create({ keyPath: cfg.google.serviceAccountKey, packageName: cfg.google.packageName });
+    const { run } = await import(`../src/play/commands/${PLAY_COMMANDS[cmd].mod}.mjs`);
+    const ok = await run(cfg, client);
+    if (ok === false) process.exit(1);
+  } else if (COMMANDS[cmd]) {
+    const cfg = await loadConfig(cfgPath);
+    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);
+    if (ok === false) process.exit(1);
+  } else {
+    console.error(usage());
+    process.exit(1);
+  }
+} catch (e) {
+  console.error(`\x1b[31m${e.message}\x1b[0m`);
+  process.exit(1);
+}
+
+function usage() {
+  return `vydanne ${VERSION} — App Store Connect submission prep (companion to zdymak). Never submits.
+usage: vydanne <command> [--config vydanne.config.mjs]
+  fill            metadata + screenshots + previews (native; iOS & macOS separate)
+  age-rating      set the age rating (AppInfo declaration)
+  review-contact  App Review contact from the gitignored files
+  accessibility   Accessibility Nutrition Labels (draft; VYDANNE_A11Y_PUBLISH=1 to publish once live)
+  privacy         write the record + print the ASC-UI answers (API can't reach iris)
+  previews        upload App Preview videos (native chunked upload)
+  iap             validate IAP fields; VYDANNE_FLATTEN=<png> flattens a screenshot to RGB
+  compliance      generate the US encryption self-classification PDF
+  inspect         read-only ASC state
+  diff            show what differs between local (metadata/screenshots/previews) and ASC
+  preflight       verify submission-completeness (the gotcha checker)
+  locales         UI -> ASC locale mapping + unsupported
+toggles: VYDANNE_SKIP_METADATA / VYDANNE_SKIP_SCREENSHOTS (fill), VYDANNE_A11Y_PUBLISH (accessibility)`;
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "vydanne",
+  "version": "0.2.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",
+    "google-play",
+    "aso",
+    "ios",
+    "android",
+    "app-store",
+    "play-developer-api",
+    "fastlane-alternative",
+    "app-metadata",
+    "screenshots",
+    "app-preview",
+    "publishing"
+  ],
+  "type": "module",
+  "main": "src/index.mjs",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.mjs"
+    }
+  },
+  "bin": {
+    "vydanne": "bin/vydanne.mjs"
+  },
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "license": "MIT",
+  "author": "Lonli-Lokli <lonli.lokli@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lonli-Lokli/vydanne.git"
+  },
+  "homepage": "https://github.com/Lonli-Lokli/vydanne#readme",
+  "bugs": "https://github.com/Lonli-Lokli/vydanne/issues",
+  "files": [
+    "bin",
+    "src",
+    "types/index.d.ts",
+    "SKILL.md",
+    "vydanne.config.example.mjs",
+    "README.md",
+    "GETTING_STARTED.md"
+  ],
+  "scripts": {
+    "check:docs": "node scripts/check-docs.mjs",
+    "check:types": "tsc --noEmit -p tsconfig.json && node scripts/check-types.mjs",
+    "prepublishOnly": "npm run check:docs && npm run check:types",
+    "release:patch": "node scripts/release.mjs patch",
+    "release:minor": "node scripts/release.mjs minor",
+    "release:major": "node scripts/release.mjs major"
+  },
+  "dependencies": {
+    "pdfkit": "^0.15.0",
+    "sharp": "^0.35.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}

package/src/client.mjs

@@ -0,0 +1,65 @@
+import { makeToken } from "./jwt.mjs";
+
+const API = "https://api.appstoreconnect.apple.com";
+const IRIS = "https://appstoreconnect.apple.com/iris";
+const DEAD_VERSION = ["READY_FOR_SALE", "REMOVED_FROM_SALE", "REPLACED_WITH_NEW_VERSION"];
+const DEAD_INFO = ["READY_FOR_SALE", "REPLACED_WITH_NEW_VERSION", "REMOVED_FROM_SALE"];
+
+// Thin ASC REST client. Encodes the gotchas: `iris` host (App Privacy 401s the JWT), version + app-info
+// fetched from the FULL list (get_edit filters out READY_FOR_REVIEW), and individual localization reads
+// (list endpoints return sparse/empty text).
+export class Client {
+  constructor({ keyId, issuerId }) {
+    this.token = makeToken({ keyId, issuerId });
+  }
+
+  async req(method, urlPath, { iris = false, body, rawHeaders, rawBody } = {}) {
+    const headers = { Authorization: `Bearer ${this.token}` };
+    if (body) headers["Content-Type"] = "application/json";
+    Object.assign(headers, rawHeaders || {});
+    const res = await fetch(`${iris ? IRIS : API}${urlPath}`, {
+      method, headers, body: rawBody ?? (body ? JSON.stringify(body) : undefined),
+    });
+    const text = await res.text();
+    let json;
+    try { json = text ? JSON.parse(text) : {}; } catch { json = text; }
+    return { status: res.status, json, text };
+  }
+
+  get(p, opts) { return this.req("GET", p, opts); }
+  post(p, body) { return this.req("POST", p, { body }); }
+  patch(p, body) { return this.req("PATCH", p, { body }); }
+  del(p) { return this.req("DELETE", p); }
+
+  async findApp(bundleId) {
+    const { json } = await this.get(`/v1/apps?filter[bundleId]=${bundleId}&limit=1`);
+    const app = json.data?.[0];
+    if (!app) throw new Error(`vydanne: app '${bundleId}' not found for this ASC key`);
+    this.app = app; this.appId = app.id;
+    return app;
+  }
+
+  async editVersion(platform) {
+    const { json } = await this.get(`/v1/apps/${this.appId}/appStoreVersions?filter[platform]=${platform}&limit=10`);
+    const data = json.data || [];
+    return data.find((v) => !DEAD_VERSION.includes(v.attributes.appStoreState)) || data[0] || null;
+  }
+
+  async appInfo() {
+    const { json } = await this.get(`/v1/apps/${this.appId}/appInfos?limit=10`);
+    const data = json.data || [];
+    return data.find((i) => !DEAD_INFO.includes(i.attributes.state)) || data[0] || null;
+  }
+
+  async versionLocalizations(versionId) {
+    const { json } = await this.get(`/v1/appStoreVersions/${versionId}/appStoreVersionLocalizations?limit=200`);
+    return json.data || [];
+  }
+
+  // Individual fetch — the list endpoints omit the text fields (sparse), so a populated/empty check must
+  // read each localization by id.
+  async localization(id, kind = "appStoreVersionLocalizations") {
+    const { json } = await this.get(`/v1/${kind}/${id}`);
+    return json.data?.attributes || {};
+  }
+}

package/src/commands/accessibility.mjs

@@ -0,0 +1,36 @@
+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 },
+};
+
+export async function run(config, client) {
+  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;
+  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; }
+    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}`));
+    } else {
+      console.log(green(`  ${fam}: draft saved`));
+    }
+  }
+  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/ageRating.mjs

@@ -0,0 +1,33 @@
+import { green, yellow, red } from "../util.mjs";
+
+// Set the age rating via the AppInfo age-rating declaration. v1: "4+" — every content descriptor NONE.
+// (PATCH is partial; Apple recomputes 4+ from these.) app-info fetched from the full list (survives
+// READY_FOR_REVIEW).
+export async function run(config, client) {
+  if (config.rating !== "4+") { console.error(yellow(`age-rating: only '4+' (all-NONE) implemented; config=${config.rating}`)); return false; }
+  await client.findApp(config.bundleId);
+  const info = await client.appInfo();
+  if (!info) { console.error(red("age-rating: no editable app info")); return false; }
+  const { json } = await client.get(`/v1/appInfos/${info.id}/ageRatingDeclaration`);
+  const id = json.data?.id;
+  if (!id) { console.error(red("age-rating: no declaration")); return false; }
+  const N = "NONE";
+  // Apple's 2025 age-rating schema. A PATCH must include ALL required fields (a partial set 409s),
+  // and `ageRatingOverride` (deprecated) cannot be sent alongside `ageRatingOverrideV2` — so we send
+  // only V2. Content descriptors are enums (NONE); capability questions are booleans (false). All
+  // benign here → 4+.
+  const attributes = {
+    advertising: false, alcoholTobaccoOrDrugUseOrReferences: N, contests: N, gambling: false,
+    gamblingSimulated: N, gunsOrOtherWeapons: N, healthOrWellnessTopics: false, kidsAgeBand: null,
+    lootBox: false, medicalOrTreatmentInformation: N, messagingAndChat: false, parentalControls: false,
+    profanityOrCrudeHumor: N, ageAssurance: false, sexualContentGraphicAndNudity: N, sexualContentOrNudity: N,
+    socialMedia: false, socialMediaAgeRestricted: false, horrorOrFearThemes: N, matureOrSuggestiveThemes: N,
+    unrestrictedWebAccess: false, userGeneratedContent: false, violenceCartoonOrFantasy: N,
+    violenceRealisticProlongedGraphicOrSadistic: N, violenceRealistic: N, ageRatingOverrideV2: N,
+    koreaAgeRatingOverride: N,
+  };
+  const r = await client.patch(`/v1/ageRatingDeclarations/${id}`, { data: { type: "ageRatingDeclarations", id, attributes } });
+  if (r.status >= 300) { console.error(red(`age-rating: ${r.status}: ${JSON.stringify(r.json).slice(0, 200)}`)); return false; }
+  console.log(green("age rating set -> 4+"));
+  return true;
+}

package/src/commands/compliance.mjs

@@ -0,0 +1,45 @@
+import PDFDocument from "pdfkit";
+import fs from "node:fs";
+import { green, yellow } from "../util.mjs";
+
+// 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; }
+  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 });
+
+  await new Promise((resolve, reject) => {
+    const doc = new PDFDocument({ size: "A4", margin: 56 });
+    const stream = fs.createWriteStream(out);
+    doc.pipe(stream);
+    const kv = (k, v) => { doc.font("Helvetica-Bold").fontSize(10.5).fillColor("#0b0b0a").text(k, { continued: true }); doc.font("Helvetica").fillColor("#1e1e1e").text("  " + v); };
+    const h = (t) => { doc.moveDown(0.6).font("Helvetica-Bold").fontSize(13).fillColor("#0b0b0a").text(t); doc.moveDown(0.2); };
+    const p = (t) => { doc.font("Helvetica").fontSize(10.5).fillColor("#1e1e1e").text(t); };
+
+    doc.font("Helvetica-Bold").fontSize(18).fillColor("#0b0b0a").text("Encryption Export Self-Classification Report");
+    doc.moveTo(56, doc.y + 4).lineTo(539, doc.y + 4).strokeColor("#c8c8c8").stroke();
+    doc.moveDown();
+    kv("Product:", appName); kv("Bundle ID:", config.bundleId); kv("Version:", String(e.version || "1.0")); kv("Developer (Apple Team ID):", String(e.teamId || "-"));
+    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.");
+    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})`);
+    }
+    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).");
+    doc.end();
+    stream.on("finish", resolve);
+    stream.on("error", reject);
+  });
+
+  console.log(green(`wrote ${out}`));
+  if (e.france) console.log(yellow("France: file + upload the ANSSI declaration too (territory rule). US: email BIS+NSA, no CCATS."));
+  return true;
+}

package/src/commands/diff.mjs

@@ -0,0 +1,107 @@
+import fs from "node:fs";
+import path from "node:path";
+import { green, yellow, red } from "../util.mjs";
+import { VALID } from "../locales.mjs";
+
+// [asc attribute, local metadata filename, isLongText]
+const VERSION_FIELDS = [
+  ["description", "description", true], ["keywords", "keywords", false], ["promotionalText", "promotional_text", false],
+  ["whatsNew", "release_notes", true], ["marketingUrl", "marketing_url", false], ["supportUrl", "support_url", false],
+];
+const INFO_FIELDS = [["name", "name", false], ["subtitle", "subtitle", false]];
+const IOS_DEVICE = { iphone69: "APP_IPHONE_67", iphone65: "APP_IPHONE_65", ipad13: "APP_IPAD_PRO_3GEN_129", watch: "APP_WATCH_ULTRA" };
+const MAC_DEVICE = { macos: "APP_DESKTOP" };
+
+const norm = (s) => (s == null ? null : String(s).replace(/\r/g, "").replace(/\n+$/, "").trim());
+const short = (s, n = 24) => { s = String(s).replace(/\n/g, " "); return s.length > n ? s.slice(0, n) + "…" : s; };
+
+// Show what's different between the local sources (metadata folders, screenshots, previews) and App Store
+// Connect — i.e. what `fill` / `previews` would change. Reads each localization by id (list is sparse).
+export async function run(config, client) {
+  await client.findApp(config.bundleId);
+  const info = await client.appInfo();
+  const infoLocs = info ? (await client.get(`/v1/appInfos/${info.id}/appInfoLocalizations?limit=200`)).json.data || [] : [];
+  let actionable = 0; // differences `fill`/`previews` would actually change (release_notes on a 1.0 is benign)
+
+  for (const platform of config.platforms) {
+    const v = await client.editVersion(platform);
+    if (!v) { console.log(red(`${platform}: no editable version`)); continue; }
+    console.log(`${platform}  v${v.attributes.versionString} ${v.attributes.appStoreState}`);
+    const verLocs = await client.versionLocalizations(v.id);
+    const localDirs = fs.existsSync(config.metadataDir)
+      ? fs.readdirSync(config.metadataDir, { withFileTypes: true }).filter((d) => d.isDirectory() && VALID.has(d.name)).map((d) => d.name)
+      : [];
+
+    const presence = {}; // field -> { localOnly:[], remoteOnly:[] }  (systematic — aggregated, not per-locale)
+    for (const code of localDirs) {
+      const folder = path.join(config.metadataDir, code);
+      const readL = (f) => { const p = path.join(folder, `${f}.txt`); return fs.existsSync(p) ? norm(fs.readFileSync(p, "utf8")) : null; };
+      const vl = verLocs.find((l) => l.attributes.locale === code);
+      const il = infoLocs.find((l) => l.attributes.locale === code);
+      const vAttrs = vl ? await client.localization(vl.id) : {};
+      const iAttrs = il ? await client.localization(il.id, "appInfoLocalizations") : {};
+      const content = []; // per-locale value differences (the ones you usually care about)
+      const record = (file, L, R, long) => {
+        const c = cmp(L, R, long);
+        if (!c) return;
+        if (c.kind === "diff") { content.push(`${file} ${red("differs")} ${c.detail}`); actionable++; return; }
+        const arr = (presence[file] ||= { localOnly: [], remoteOnly: [] });
+        if (c.kind === "local-only") { arr.localOnly.push(code); if (file !== "release_notes") actionable++; }
+        else { arr.remoteOnly.push(code); actionable++; }
+      };
+      if (!vl) { content.unshift(yellow("[fill would create localization]")); actionable++; }
+      for (const [attr, file, long] of VERSION_FIELDS) record(file, readL(file), norm(vAttrs[attr]), long);
+      for (const [attr, file, long] of INFO_FIELDS) record(file, readL(file), norm(iAttrs[attr]), long);
+      if (content.length) console.log(`  ${code}: ${content.join(" · ")}`);
+    }
+    for (const [file, p] of Object.entries(presence)) {
+      const hint = file === "release_notes" ? "  (What's New — N/A on a first version)" : "";
+      if (p.localOnly.length) console.log(`  ${green(`${file} local-only`)} in ${p.localOnly.length} locale(s)${hint}`);
+      if (p.remoteOnly.length) console.log(`  ${yellow(`${file} remote-only`)} in ${p.remoteOnly.length} locale(s)`);
+    }
+
+    const localSet = new Set(localDirs);
+    const extra = verLocs.map((l) => l.attributes.locale).filter((c) => !localSet.has(c));
+    if (extra.length) console.log(`  ${yellow("remote-only locales")} (no local folder): ${extra.join(", ")}`);
+
+    actionable += await mediaDiff(config, client, platform, verLocs);
+  }
+
+  console.log();
+  console.log(actionable ? yellow(`${actionable} actionable difference(s) — run \`fill\` / \`previews\` to sync`) : green("in sync — local matches App Store Connect"));
+  return true;
+}
+
+function cmp(L, R, long) {
+  if (L == null && (R == null || R === "")) return null;
+  if (L == null) return { kind: "remote-only" };
+  if (R == null || R === "") return { kind: "local-only" };
+  if (L === R) return null;
+  return { kind: "diff", detail: long ? `(local ${L.length} / remote ${R.length} ch)` : `local="${short(L)}" remote="${short(R)}"` };
+}
+
+async function mediaDiff(config, client, platform, verLocs) {
+  const primary = verLocs.find((l) => l.attributes.locale === config.primaryLocale);
+  if (!primary) return 0;
+  let diffs = 0;
+  const dev = platform === "MAC_OS" ? MAC_DEVICE : IOS_DEVICE;
+  const base = platform === "MAC_OS" ? "fastlane/screenshots-macos" : "fastlane/screenshots";
+  const localDir = path.join(base, config.primaryLocale);
+  const local = {};
+  if (fs.existsSync(localDir)) for (const f of fs.readdirSync(localDir).filter((f) => f.endsWith(".png"))) { const dt = dev[f.split("_")[0]]; if (dt) local[dt] = (local[dt] || 0) + 1; }
+  const { json: sets } = await client.get(`/v1/appStoreVersionLocalizations/${primary.id}/appScreenshotSets?include=appScreenshots&limit=50`);
+  const remote = {};
+  for (const s of sets.data || []) remote[s.attributes.screenshotDisplayType] = (s.relationships?.appScreenshots?.data || []).length;
+  for (const dt of new Set([...Object.keys(local), ...Object.keys(remote)])) {
+    const L = local[dt] || 0, R = remote[dt] || 0;
+    if (L !== R) { diffs++; console.log(`  ${yellow("screenshots")} ${dt.replace("APP_", "")}: local ${L} / remote ${R}  (@${config.primaryLocale})`); }
+  }
+  const { json: psets } = await client.get(`/v1/appStoreVersionLocalizations/${primary.id}/appPreviewSets?include=appPreviews&limit=50`);
+  const remotePrev = {};
+  for (const s of psets.data || []) remotePrev[s.attributes.previewType] = (s.relationships?.appPreviews?.data || []).length;
+  for (const spec of (config.previews || []).filter((s) => s.platform === platform && (s.locales || []).includes(config.primaryLocale))) {
+    const L = fs.existsSync(path.resolve(spec.file)) ? 1 : 0, R = remotePrev[spec.type] || 0;
+    if (L !== R) { diffs++; console.log(`  ${yellow("preview")} ${spec.type}: local ${L} / remote ${R}  (@${config.primaryLocale})`); }
+  }
+  return diffs;
+}