vydanne 0.2.0 → 0.4.0

package/README.md

@@ -67,15 +67,67 @@ Download the `.p8` (once only!), then:
 ```sh
 mkdir -p ~/.appstoreconnect/private_keys
 mv ~/Downloads/AuthKey_*.p8 ~/.appstoreconnect/private_keys/
-export ASC_KEY_ID=…  ASC_ISSUER_ID=…
+
+# Write the ids ONCE — every app you ship reads them from here. Nothing to export per shell,
+# nothing secret in any repo. (The .p8 stays next to it, in private_keys/.)
+cat > ~/.appstoreconnect/config.json <<'JSON'
+{ "keyId": "ABCD123456", "issuerId": "69a6de70-…" }
+JSON
+chmod 600 ~/.appstoreconnect/config.json
+
+npx vydanne auth      # confirms what resolved, and from where
 ```
 ```powershell
 # Windows PowerShell
 New-Item -ItemType Directory -Force "$env:USERPROFILE\.appstoreconnect\private_keys"
 Move-Item "$env:USERPROFILE\Downloads\AuthKey_*.p8" "$env:USERPROFILE\.appstoreconnect\private_keys\"
-$env:ASC_KEY_ID = "…"; $env:ASC_ISSUER_ID = "…"
+'{ "keyId": "ABCD123456", "issuerId": "69a6de70-…" }' |
+  Set-Content "$env:USERPROFILE\.appstoreconnect\config.json"
+```
+
+### Where credentials come from
+
+Resolved automatically, highest priority first — and **never** from `vydanne.config.mjs`, which is
+committed. A keyId or issuerId found there is refused at load, with a warning telling you to move it:
+
+| Source | Use it for |
+|---|---|
+| `ASC_KEY_ID` / `ASC_ISSUER_ID` / `PLAY_JSON_KEY_FILE` in the environment | CI secrets, one-off overrides |
+| the `.env` cascade in the repo | one app that needs a different account from the rest |
+| **the user config file** | **the default for every app you ship** — one account, many repos |
+
+**The `.env` cascade** is the standard one (same shape Vite and Next.js use), parsed with `dotenv`, later
+file wins: `.env` → `.env.<mode>` → `.env.local` → `.env.<mode>.local`, where `mode` is `VYDANNE_ENV` (or
+`NODE_ENV`) and is optional. So `.env` and `.env.<mode>` stay **committable** for shared non-secret
+defaults, and only the `*.local` files hold secrets — those are the ones to gitignore:
+
+```gitignore
+.env.local
+.env.*.local
+```
+
+Values are *parsed*, never loaded into `process.env`, so a real environment variable always wins.
+
+**The user config file** is looked up in this order, first hit wins — there is no single cross-platform
+home for it, so all three are honoured instead of forcing one on everyone:
+
+| Path | |
+|---|---|
+| `$VYDANNE_CONFIG_HOME/config.json` | explicit escape hatch (a secrets mount, a shared drive, tests) |
+| `%APPDATA%\vydanne\config.json` (Windows)<br>`$XDG_CONFIG_HOME/vydanne/config.json` → `~/.config/vydanne/config.json` | what a Windows or Linux user expects |
+| `~/.appstoreconnect/config.json` | beside the keys — Apple's tooling and fastlane already keep the `.p8` in `~/.appstoreconnect/private_keys` on every platform |
+
+Shipping under more than one account? Use named profiles, selected with `VYDANNE_PROFILE=client-x` or
+pinned per app via `asc: { profile: "client-x" }` in its config — a label, not a secret:
+
+```json
+{ "default": "kupalinka",
+  "profiles": { "kupalinka": { "keyId": "…", "issuerId": "…", "playJsonKeyFile": "~/.config/play/sa.json" },
+                "client-x":  { "keyId": "…", "issuerId": "…" } } }
 ```
 
+`vydanne auth` prints what resolved and which source won, masked — run it first when Apple returns a 401.
+
 **2. Describe your app** in a `vydanne.config.mjs` file next to your project:
 
 ```js
@@ -128,7 +180,7 @@ Run vydanne **from your project folder** — it finds everything relative to whe
 | `compliance` | Generates the US encryption self-classification PDF that Apple asks for. |
 | `version` | Prints the version of vydanne. |
 
-For **Google Play**, add `--store google` to `inspect`, `diff`, `preflight`, or `fill`.
+For **Google Play**, add `--store google` to `inspect`, `diff`, `preflight`, `fill`, or `prerelease`.
 
 <br>
 
@@ -144,6 +196,37 @@ VYDANNE_COMMIT=1 npx vydanne fill --store google   # actually do it
 #   Windows PowerShell:  $env:VYDANNE_COMMIT = "1"; npx vydanne fill --store google
 ```
 
+### `prerelease` — the build, to a testing track
+
+`fill` writes the *listing*; `prerelease` uploads the **binary** to a **closed testing track** with
+release notes, all inside one edit transaction:
+
+```sh
+npx vydanne prerelease --store google                    # dry run
+VYDANNE_COMMIT=1 npx vydanne prerelease --store google   # publish to the track
+```
+
+```js
+google: {
+  packageName: "com.x.app",
+  aab: "./dist",        // a file, or a directory whose NEWEST .aab is taken
+  track: "internal",    // 'internal' (default) | 'alpha' | 'beta'
+}
+```
+
+**It refuses `production`** — that isn't a flag you can pass, it's a refusal. A staged rollout can be
+halted but never un-shipped, so promoting a tested build stays a human decision in Play Console. This is
+the same line the Apple side draws by never submitting.
+
+**Paid app? Use `internal`.** It is the only track where testers install without buying; closed and open
+testers pay like everyone else.
+
+Release notes follow supply's layout, so an existing repo needs no migration —
+`<metadataDir>/<play-locale>/changelogs/<versionCode>.txt`, falling back to `default.txt`, truncated to
+Play's 500-char cap with a warning. The versionCode comes from the bundle's own manifest, so build
+numbering stays with the build and re-uploading a used code fails loudly instead of silently replacing a
+binary. Overrides: `VYDANNE_AAB`, `VYDANNE_TRACK`, `VYDANNE_RELEASE_NAME`.
+
 **Play is dry by default on purpose.** Nothing goes live until you add `VYDANNE_COMMIT=1`, so a
 half-finished folder can never overwrite a good listing. Play also uses its **own** language codes
 (`zh-CN`, `iw-IL`) which are *not* Apple's — `vydanne locales` and the

package/SKILL.md

@@ -22,14 +22,33 @@ Play images (below), so the two line up with no glue.
 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.
+`import('vydanne').VydanneConfig`). Node ≥20.9. Cross-platform. On Windows PowerShell the `VAR=1 cmd`
+form does **not** exist; set `$env:VAR = "1"` first.
+
+**Auth resolves automatically — NEVER put credentials in the config.** That file is committed; vydanne
+refuses a keyId/issuerId found there and warns. The signing key stays at
+`~/.appstoreconnect/private_keys/AuthKey_<keyId>.p8`. The ids resolve highest-priority-first from: the
+environment (`ASC_KEY_ID` / `ASC_ISSUER_ID` / `PLAY_JSON_KEY_FILE`) → the **`.env` cascade** → the **user
+config file**.
+
+The cascade is the standard one (dotenv-parsed, later file wins): `.env` → `.env.<mode>` → `.env.local` →
+`.env.<mode>.local`, `mode` from `VYDANNE_ENV`/`NODE_ENV`. So `.env` and `.env.<mode>` stay COMMITTABLE
+for shared non-secret defaults and only `*.local` holds secrets — never tell a user to gitignore `.env`
+itself. Files are parsed, never merged into `process.env`, so a real env var always wins.
+
+The user config file is the answer for a portfolio: write `{"keyId","issuerId","playJsonKeyFile"}` once
+and every app picks it up with no per-repo setup. Looked up first-hit-wins —
+`$VYDANNE_CONFIG_HOME/config.json` → `%APPDATA%\vydanne\config.json` (Windows) or
+`$XDG_CONFIG_HOME/vydanne/config.json` (default `~/.config/vydanne/`) → `~/.appstoreconnect/config.json`
+(beside the keys, where Apple's tooling and fastlane already keep the `.p8`). Several accounts → named
+`profiles` + `VYDANNE_PROFILE`, or pin one per app with `asc: {profile}` (a label, not a secret).
+**Run `vydanne auth` before debugging any 401** — it prints what resolved, from which source, masked,
+which user file was used, and whether the `.p8` is on disk.
 
 **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).
+`{profile}` — selection only, never secrets) · `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.
@@ -143,9 +162,19 @@ who it's for → honest close. Keep it scannable; lead each bullet with the payo
 `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
+(completeness gate) · `inspect` · `auth` (what credentials resolved, and from where) · `locales` · `version`.
+
+`prerelease` (**Play only**) uploads an `.aab` to a **closed testing track** with release notes, inside one
+edit transaction. `production` is REFUSED — not flag-gated — so no argument combination ships to the
+public; promoting the tested build stays a human's job, mirroring the Apple side never submitting. Track
+comes from `google.track` / `VYDANNE_TRACK`, default `internal`; the bundle from `google.aab` /
+`VYDANNE_AAB` (a directory takes its newest `.aab`). **For a PAID app use `internal`** — it's the only
+track where testers install without buying. Notes follow supply's layout:
+`<google.metadataDir>/<play-locale>/changelogs/<versionCode>.txt`, falling back to `default.txt`, capped
+at Play's 500 chars. DRY by default like `fill --store google`; `VYDANNE_COMMIT=1` publishes. The
+versionCode comes from the bundle itself, so re-uploading one fails loudly instead of silently replacing.
+
+`--store google` routes `inspect` · `diff` · `preflight` · `fill` · `prerelease` 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.

package/bin/vydanne.mjs

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { loadConfig } from "../src/config.mjs";
 import { Client } from "../src/client.mjs";
 import { COMMANDS, PLAY_COMMANDS } from "../src/registry.mjs";
@@ -16,6 +18,30 @@ const store = si >= 0 ? argv[si + 1] : "apple";
 try {
   if (["version", "-v", "--version"].includes(cmd)) {
     console.log(`vydanne ${VERSION}`);
+  } else if (cmd === "auth") {
+    // "Why isn't it picking up my key?" — answered, without ever printing a secret.
+    const cr = (await loadConfig(cfgPath)).credentials;
+    const mask = (v) => (v ? `${String(v).slice(0, 4)}…${String(v).slice(-4)}` : null);
+    const row = (label, value, key, shown) =>
+      console.log(value
+        ? `  \x1b[32m✓\x1b[0m ${label.padEnd(20)} ${String(shown ?? mask(value)).padEnd(26)} ← ${cr.sources[key]}`
+        : `  \x1b[31m✗\x1b[0m ${label.padEnd(20)} \x1b[31mnot found\x1b[0m`);
+    console.log("Credentials — environment > .env cascade > user config (never the committed config):");
+    row("ASC_KEY_ID", cr.keyId, "ASC_KEY_ID", cr.keyId);
+    row("ASC_ISSUER_ID", cr.issuerId, "ASC_ISSUER_ID");
+    row("PLAY_JSON_KEY_FILE", cr.playJsonKeyFile, "PLAY_JSON_KEY_FILE", cr.playJsonKeyFile);
+    if (cr.keyId) {
+      const p = path.join(os.homedir(), ".appstoreconnect", "private_keys", `AuthKey_${cr.keyId}.p8`);
+      console.log(existsSync(p)
+        ? `  \x1b[32m✓\x1b[0m ${"signing key".padEnd(20)} ${p}`
+        : `  \x1b[31m✗\x1b[0m ${"signing key".padEnd(20)} \x1b[31mmissing\x1b[0m — ${p}`);
+    }
+    console.log(cr.userFile ? `\nuser config: ${cr.userFile}` : `\nuser config: none found. Looked in:\n${cr.candidates.map((c) => `  ${c}`).join("\n")}`);
+    if (!cr.keyId || !cr.issuerId) {
+      const target = cr.userFile || cr.candidates[cr.candidates.length - 1];
+      console.log(`\nSet once for EVERY app, no secrets in any repo:\n  ${target}\n  { "keyId": "ABCD123456", "issuerId": "69a6de70-…" }\n  chmod 600 ${target}`);
+      process.exit(1);
+    }
   } else if (cmd === "locales") {
     const r = (await loadConfig(cfgPath)).resolvedLocales;
     console.log(`supported (${Object.keys(r.supported).length}):`);
@@ -61,6 +87,12 @@ usage: vydanne <command> [--config vydanne.config.mjs]
   inspect         read-only ASC state
   diff            show what differs between local (metadata/screenshots/previews) and ASC
   preflight       verify submission-completeness (the gotcha checker)
+  prerelease      --store google: upload the .aab to a closed testing track (refuses production)
   locales         UI -> ASC locale mapping + unsupported
-toggles: VYDANNE_SKIP_METADATA / VYDANNE_SKIP_SCREENSHOTS (fill), VYDANNE_A11Y_PUBLISH (accessibility)`;
+  auth            which credentials resolved, and from where (masked) — run this on a 401
+credentials: env > .env cascade (.env, .env.<mode>, .env.local, .env.<mode>.local) > user config
+  (\$VYDANNE_CONFIG_HOME, %APPDATA%\\vydanne or \$XDG_CONFIG_HOME/vydanne, ~/.appstoreconnect).
+  NEVER the committed vydanne.config.mjs — run \`vydanne auth\` to see what resolved.
+toggles: VYDANNE_SKIP_METADATA / VYDANNE_SKIP_SCREENSHOTS (fill), VYDANNE_A11Y_PUBLISH (accessibility),
+         VYDANNE_PROFILE (named profile), VYDANNE_ENV (.env mode)`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vydanne",
-  "version": "0.2.0",
+  "version": "0.4.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",
@@ -57,6 +57,7 @@
     "release:major": "node scripts/release.mjs major"
   },
   "dependencies": {
+    "dotenv": "^17.4.2",
     "pdfkit": "^0.15.0",
     "sharp": "^0.35.3"
   },

package/src/commands/fill.mjs

@@ -10,11 +10,44 @@ const INFO_TXT = { name: "name", subtitle: "subtitle" };
 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" };
 
+/**
+ * PATCH a localization, surviving attributes Apple refuses to edit RIGHT NOW.
+ *
+ * A version-localization PATCH is all-or-nothing: one un-editable attribute rejects the WHOLE payload
+ * with 409 STATE_ERROR and nothing is written. The classic case is `whatsNew` on a first version — there
+ * is no previous release, so "What's New" cannot exist, and sending it silently costs you the
+ * description and keywords for every locale.
+ *
+ * So: send everything, and if Apple names offending attributes, drop exactly those and retry once. Any
+ * other failure is reported rather than swallowed — a fill that writes nothing must never look like a
+ * fill that worked.
+ */
+async function patchAttrs(client, url, type, id, attrs, label) {
+  const send = (a) => client.patch(url, { data: { type, id, attributes: a } });
+  let res = await send(attrs);
+  if (res.status < 300) return { ok: true, dropped: [] };
+
+  // "Attribute 'whatsNew' cannot be edited at this time" → drop the named attributes and retry.
+  const blocked = (res.json?.errors || [])
+    .flatMap((e) => [...String(e.detail || "").matchAll(/Attribute '([^']+)' cannot be edited/g)].map((m) => m[1]))
+    .filter((k) => k in attrs);
+  if (blocked.length) {
+    const rest = Object.fromEntries(Object.entries(attrs).filter(([k]) => !blocked.includes(k)));
+    if (!Object.keys(rest).length) return { ok: true, dropped: blocked };
+    res = await send(rest);
+    if (res.status < 300) return { ok: true, dropped: blocked };
+  }
+  const why = (res.json?.errors || []).map((e) => `${e.code || res.status}: ${e.detail || e.title}`).join("; ") || `HTTP ${res.status}`;
+  console.error(red(`    ✗ ${label}: ${why}`));
+  return { ok: false, dropped: [] };
+}
+
 // Push metadata (native PATCH — works at any editable state, incl. READY_FOR_REVIEW, unlike deliver) +
 // screenshots (native chunked upload; skips sets that already have shots so it never duplicates).
 // iOS and macOS are separate platforms. Toggles: VYDANNE_SKIP_METADATA / VYDANNE_SKIP_SCREENSHOTS.
 export async function run(config, client) {
   await client.findApp(config.bundleId);
+  let ok = true; // a locale Apple refused must fail the command, not just print
   const skipMeta = process.env.VYDANNE_SKIP_METADATA === "1";
   const skipShots = process.env.VYDANNE_SKIP_SCREENSHOTS === "1";
   const info = await client.appInfo();
@@ -27,6 +60,8 @@ export async function run(config, client) {
     const verLocs = await client.versionLocalizations(v.id);
 
     if (!skipMeta) {
+      let failed = 0;
+      const dropped = new Set();
       const dirs = fs.readdirSync(config.metadataDir, { withFileTypes: true }).filter((d) => d.isDirectory() && VALID.has(d.name)).map((d) => d.name);
       for (const code of dirs) {
         const folder = path.join(config.metadataDir, code);
@@ -36,7 +71,11 @@ export async function run(config, client) {
         if (!vl) { const c = await client.post(`/v1/appStoreVersionLocalizations`, { data: { type: "appStoreVersionLocalizations", attributes: { locale: code }, relationships: { appStoreVersion: { data: { type: "appStoreVersions", id: v.id } } } } }); vl = c.json.data; verLocs.push(vl); }
         const vattrs = {};
         for (const [k, f] of Object.entries(VERSION_TXT)) { const t = read(f); if (t != null) vattrs[k] = t; }
-        if (Object.keys(vattrs).length) await client.patch(`/v1/appStoreVersionLocalizations/${vl.id}`, { data: { type: "appStoreVersionLocalizations", id: vl.id, attributes: vattrs } });
+        if (Object.keys(vattrs).length) {
+          const r = await patchAttrs(client, `/v1/appStoreVersionLocalizations/${vl.id}`, "appStoreVersionLocalizations", vl.id, vattrs, `${code} version`);
+          if (!r.ok) failed++;
+          for (const d of r.dropped) dropped.add(d);
+        }
         // app-info localization (name/subtitle — shared across platforms). Apple REQUIRES `name` when
         // CREATING a localization (409 ATTRIBUTE.REQUIRED otherwise), so build the attrs first and send
         // them in the POST; only PATCH when the localization already exists.
@@ -50,16 +89,20 @@ export async function run(config, client) {
             if (il) infoLocs.push(il);
             else console.error(`  appInfo ${code}: create failed — ${JSON.stringify(c.json?.errors?.[0]?.detail || c.json)}`);
           } else if (Object.keys(iattrs).length) {
-            await client.patch(`/v1/appInfoLocalizations/${il.id}`, { data: { type: "appInfoLocalizations", id: il.id, attributes: iattrs } });
+            const r = await patchAttrs(client, `/v1/appInfoLocalizations/${il.id}`, "appInfoLocalizations", il.id, iattrs, `${code} app-info`);
+            if (!r.ok) failed++;
+            for (const d of r.dropped) dropped.add(d);
           }
         }
       }
-      console.log(green(`  metadata: ${dirs.length} locales`));
+      if (dropped.size) console.log(yellow(`  skipped un-editable attribute(s) in this version state: ${[...dropped].join(", ")}`));
+      console.log(failed ? red(`  metadata: ${dirs.length - failed}/${dirs.length} locales written, ${failed} FAILED`) : green(`  metadata: ${dirs.length} locales`));
+      if (failed) ok = false;
     }
 
     if (!skipShots) await uploadScreenshots(config, client, platform, verLocs);
   }
-  return true;
+  return ok;
 }
 
 async function uploadScreenshots(config, client, platform, verLocs) {

package/src/config.mjs

@@ -2,13 +2,15 @@ import path from "node:path";
 import fs from "node:fs";
 import { pathToFileURL } from "node:url";
 import { resolveLocales } from "./locales.mjs";
+import { resolveCredentials } from "./credentials.mjs";
 
 // The public config surface — the drift guards assert each key is documented (README/SKILL) and typed
 // (types/index.d.ts). Add a config knob → document + type it, or the guards fail before publish.
 export const CONFIG_KEYS = ["bundleId", "primaryLocale", "asc", "platforms", "uiLocales", "metadataDir", "rating", "privacy", "iaps", "previews", "export", "google"];
 
 // One `vydanne.config.mjs` per app (ESM, like zdymak.config.mjs) — nothing hard-coded. Secrets stay out:
-// ASC key via ~/.appstoreconnect + ASC_KEY_ID/ASC_ISSUER_ID env; review-contact PII in gitignored files.
+// credentials resolve from the environment, a gitignored .env, or ~/.appstoreconnect/config.json (see
+// credentials.mjs) and are REFUSED if found in this committed file; review-contact PII stays gitignored.
 export async function loadConfig(p) {
   const file = path.resolve(p || process.env.VYDANNE_CONFIG || "vydanne.config.mjs");
   if (!fs.existsSync(file)) throw new Error(`vydanne: config not found at ${file}`);
@@ -18,12 +20,15 @@ export async function loadConfig(p) {
     if (raw[k] == null) throw new Error(`vydanne: config missing '${k}'`);
     return raw[k];
   };
+  const creds = resolveCredentials(raw, path.dirname(file));
+  for (const w of creds.warnings) console.warn(`\x1b[33mvydanne: ${w}\x1b[0m`);
   const c = {
     raw,
+    credentials: creds,
     bundleId: need("bundleId"),
     primaryLocale: need("primaryLocale"),
-    keyId: process.env.ASC_KEY_ID || raw.asc?.keyId,
-    issuerId: process.env.ASC_ISSUER_ID || raw.asc?.issuerId,
+    keyId: creds.keyId,
+    issuerId: creds.issuerId,
     uiLocales: raw.uiLocales || [],
     platforms: raw.platforms || ["IOS"],
     rating: raw.rating || "4+",
@@ -37,9 +42,12 @@ export async function loadConfig(p) {
     google: raw.google
       ? {
           packageName: raw.google.packageName || raw.bundleId,
-          serviceAccountKey: process.env.PLAY_JSON_KEY_FILE || raw.google.serviceAccountKey,
+          serviceAccountKey: creds.playJsonKeyFile,
           metadataDir: raw.google.metadataDir || "fastlane/metadata/android",
           defaultLocale: raw.google.defaultLocale || raw.primaryLocale,
+          aab: raw.google.aab || null,
+          track: raw.google.track || "internal", // testing only — `prerelease` refuses production
+
         }
       : null,
   };

package/src/credentials.mjs

@@ -0,0 +1,164 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import dotenv from "dotenv";
+
+/**
+ * Credential resolution, so nobody has to paste `ASC_KEY_ID=… ASC_ISSUER_ID=…` in front of every command.
+ *
+ * CREDENTIALS NEVER COME FROM `vydanne.config.mjs`. That file is committed, and a repo may be public —
+ * so the config carries no keyId, no issuerId, no key paths. It may only name an `asc.profile`, which is
+ * a label, not a secret. If credentials ARE found there we refuse them and say so.
+ *
+ * Sources, highest priority first:
+ *   1. process.env       — CI secrets and one-off overrides. Always wins.
+ *   2. the .env cascade  — per-repo, the usual local-dev idiom (see ENV_FILES).
+ *   3. the user file     — the ACCOUNT-level default, outside every repo (see CONFIG_CANDIDATES).
+ *
+ * (3) is the answer for a portfolio: one App Store Connect account, many repos. Write it once and every
+ * consumer picks it up with zero per-repo setup and nothing secret in any repo:
+ *
+ *   { "keyId": "ABCD123456", "issuerId": "69a6de70-…", "playJsonKeyFile": "~/.config/play/sa.json" }
+ *
+ * Shipping under more than one account? Use named profiles, selected with `VYDANNE_PROFILE`, or pinned
+ * per app via `asc: { profile: "client-x" }` — a name, still not a secret:
+ *
+ *   { "default": "kupalinka",
+ *     "profiles": { "kupalinka": { "keyId": "…", "issuerId": "…" },
+ *                   "client-x":  { "keyId": "…", "issuerId": "…" } } }
+ *
+ * The .p8 is never read here — it stays at ~/.appstoreconnect/private_keys/AuthKey_<keyId>.p8 (jwt.mjs),
+ * so the private key is never pasted into a repo, a CI variable, or a shell history.
+ */
+
+/**
+ * Where the account-level file may live, best-match first. There is no single cross-platform home for
+ * this, so all three are honoured rather than forcing one on everybody:
+ *
+ *  - `$VYDANNE_CONFIG_HOME/config.json` — explicit escape hatch (shared drives, a secrets mount, tests).
+ *  - The OS config dir — `%APPDATA%\vydanne\` on Windows, `$XDG_CONFIG_HOME` (default `~/.config`)
+ *    elsewhere. This is what a Windows or Linux user expects; `~/.appstoreconnect` is neither.
+ *  - `~/.appstoreconnect/config.json` — beside the keys. Apple's own tooling (and fastlane) already put
+ *    the .p8 in `~/.appstoreconnect/private_keys` on every platform, so credentials and key sit together.
+ */
+export function configCandidates(env = process.env, home = os.homedir()) {
+  const out = [];
+  if (env.VYDANNE_CONFIG_HOME) out.push(path.join(env.VYDANNE_CONFIG_HOME, "config.json"));
+  const osConfigDir = process.platform === "win32"
+    ? env.APPDATA || path.join(home, "AppData", "Roaming")
+    : env.XDG_CONFIG_HOME || path.join(home, ".config");
+  out.push(path.join(osConfigDir, "vydanne", "config.json"));
+  out.push(path.join(home, ".appstoreconnect", "config.json"));
+  return out;
+}
+
+/** The first candidate that exists, or null. */
+export function findConfigFile(env = process.env, home = os.homedir()) {
+  return configCandidates(env, home).find((p) => fs.existsSync(p)) || null;
+}
+
+/**
+ * The standard `.env` cascade, lowest priority first — the same shape Vite/Next users already know, so
+ * `.env` stays COMMITTABLE (shared, non-secret defaults) and only `*.local` holds secrets. That is why
+ * only `*.local` belongs in .gitignore; ignoring `.env` outright fights the convention.
+ *
+ * `mode` comes from VYDANNE_ENV (or NODE_ENV) and is optional — with none set this is just
+ * `.env` then `.env.local`.
+ */
+export function envFiles(cwd, mode) {
+  const files = [".env"];
+  if (mode) files.push(`.env.${mode}`);
+  files.push(".env.local");
+  if (mode) files.push(`.env.${mode}.local`);
+  return files.map((f) => path.join(cwd, f));
+}
+
+/** Expand a leading `~` so the user file can hold portable paths. */
+export function expandHome(p, home = os.homedir()) {
+  if (!p || typeof p !== "string") return p;
+  return p.startsWith("~/") || p === "~" ? path.join(home, p.slice(1)) : p;
+}
+
+/** Read the account-level file, resolving the profile if it uses the named-profile form. */
+function readUserConfig(file, profile, env, warn) {
+  if (!file) return {};
+  let json;
+  try {
+    json = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (e) {
+    warn(`${file} is not valid JSON (${e.message}) — ignored`);
+    return {};
+  }
+  let values = json;
+  if (json.profiles) {
+    const name = profile || env.VYDANNE_PROFILE || json.default;
+    if (!name) {
+      warn(`${file} has profiles but no "default" — set one, or pass VYDANNE_PROFILE`);
+      return {};
+    }
+    values = json.profiles[name];
+    if (!values) {
+      warn(`${file} has no profile "${name}" (have: ${Object.keys(json.profiles).join(", ")})`);
+      return {};
+    }
+  }
+  // A credentials file readable by anyone on the machine is worth one line of noise. POSIX only —
+  // Windows ACLs don't map onto the mode bits, so checking there would just produce false alarms.
+  try {
+    if (process.platform !== "win32" && fs.statSync(file).mode & 0o004) {
+      warn(`${file} is world-readable — run: chmod 600 ${file}`);
+    }
+  } catch { /* a stat failure is not worth failing the run over */ }
+  return values || {};
+}
+
+/**
+ * Resolve every credential, recording WHERE each value came from so `vydanne auth` can explain itself —
+ * "it isn't picking up my key" is otherwise pure guesswork.
+ */
+export function resolveCredentials(raw = {}, cwd = process.cwd(), env = process.env, home = os.homedir()) {
+  const warnings = [];
+  const warn = (m) => warnings.push(m);
+
+  // Parsed, NOT loaded into process.env: dotenv.config() would mutate the environment and quietly
+  // destroy the precedence order below. Later files win, per the cascade.
+  const mode = env.VYDANNE_ENV || env.NODE_ENV || "";
+  const dotenvValues = {};
+  const dotenvFrom = {};
+  for (const file of envFiles(cwd, mode)) {
+    if (!fs.existsSync(file)) continue;
+    const parsed = dotenv.parse(fs.readFileSync(file));
+    for (const [k, v] of Object.entries(parsed)) {
+      dotenvValues[k] = v;
+      dotenvFrom[k] = path.relative(cwd, file) || path.basename(file);
+    }
+  }
+
+  const userFile = findConfigFile(env, home);
+  const user = readUserConfig(userFile, raw.asc?.profile, env, warn);
+
+  // Secrets in the committed config are refused, not silently honoured — otherwise the one machine that
+  // "works" is the one leaking them, and nobody notices until the repo goes public.
+  if (raw.asc?.keyId || raw.asc?.issuerId || raw.google?.serviceAccountKey) {
+    warn(`credentials found in vydanne.config.mjs (that file is committed) — IGNORED. Move them to ${userFile || configCandidates(env, home)[0]} or .env.local`);
+  }
+
+  const sources = {};
+  const pick = (envKey, userKey) => {
+    if (env[envKey]) return (sources[envKey] = "environment"), env[envKey];
+    if (dotenvValues[envKey]) return (sources[envKey] = dotenvFrom[envKey]), dotenvValues[envKey];
+    if (user[userKey]) return (sources[envKey] = userFile), user[userKey];
+    sources[envKey] = null;
+    return undefined;
+  };
+
+  return {
+    keyId: pick("ASC_KEY_ID", "keyId"),
+    issuerId: pick("ASC_ISSUER_ID", "issuerId"),
+    playJsonKeyFile: expandHome(pick("PLAY_JSON_KEY_FILE", "playJsonKeyFile"), home),
+    sources,
+    warnings,
+    userFile,
+    candidates: configCandidates(env, home),
+  };
+}

package/src/play/client.mjs

@@ -65,4 +65,29 @@ export class PlayClient {
     if (res.status >= 300) throw new Error(`image upload ${res.status}: ${JSON.stringify(j).slice(0, 200)}`);
     return j;
   }
+
+  // ── Binaries & tracks ─────────────────────────────────────────────────────────────────────────────
+
+  /** Upload an .aab. The returned versionCode comes from the BUNDLE's manifest — Play assigns it, not us. */
+  async uploadBundle(editId, filePath) {
+    const bytes = fs.readFileSync(filePath);
+    const res = await fetch(`${UPLOAD}/applications/${this.pkg}/edits/${editId}/bundles?uploadType=media`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${this.token}`, "Content-Type": "application/octet-stream" },
+      body: bytes,
+    });
+    const j = await res.json().catch(() => ({}));
+    if (res.status >= 300) throw new Error(`bundle upload ${res.status}: ${JSON.stringify(j).slice(0, 300)}`);
+    return j;
+  }
+
+  getTrack(editId, track) { return this.req("GET", `/edits/${editId}/tracks/${track}`); }
+
+  /**
+   * Point a track at version codes. `releases` is the FULL desired state of that track — Play replaces
+   * it wholesale, so send one complete release object rather than appending to what is already there.
+   */
+  putTrack(editId, track, releases) {
+    return this.req("PUT", `/edits/${editId}/tracks/${track}`, { body: { track, releases } });
+  }
 }

package/src/play/commands/prerelease.mjs

@@ -0,0 +1,125 @@
+import fs from "node:fs";
+import path from "node:path";
+import { green, yellow, red } from "../../util.mjs";
+
+/** Tracks this command will write. `production` is deliberately absent — see below. */
+const TESTING_TRACKS = new Set(["internal", "alpha", "beta"]);
+
+/**
+ * Upload an .aab to a CLOSED TESTING track, with release notes.
+ *
+ * Why testing-only: shipping to everyone is a judgement call with no undo — a staged rollout can be
+ * halted but not un-shipped, and the reviewer-facing consequences are the operator's to own. So this
+ * mirrors the Apple side, which never submits: `production` is REFUSED, not gated behind a flag, so
+ * there is no arrangement of arguments that ships to the public by accident.
+ *
+ * For a PAID app, `internal` is usually the only track you want: it is the one where testers install
+ * without buying. Closed/open testers must purchase it like anyone else.
+ *
+ * Play assigns the versionCode from the bundle's own manifest, so build numbering stays with the build,
+ * and re-uploading the same code fails loudly rather than silently replacing a binary.
+ *
+ * Everything happens inside one edit transaction: nothing is live until commit, and any throw leaves the
+ * edit uncommitted — i.e. the track untouched.
+ */
+export async function run(config, client) {
+  const g = config.google;
+  const track = process.env.VYDANNE_TRACK || g.track || "internal";
+
+  if (track === "production") {
+    console.error(red("prerelease: refusing to write the production track — that release is a human's to make."));
+    console.error("  Promote the tested build in Play Console when you're ready.");
+    return false;
+  }
+  if (!TESTING_TRACKS.has(track)) {
+    console.error(red(`prerelease: unknown track "${track}" (expected: ${[...TESTING_TRACKS].join(", ")})`));
+    return false;
+  }
+
+  const aab = resolveAab(g.aab);
+  if (!aab) {
+    console.error(red("prerelease: no .aab found — set `google.aab` in the config, or pass VYDANNE_AAB=<path>."));
+    return false;
+  }
+  console.log(green(`prerelease → track "${track}"`));
+  console.log(`  bundle: ${path.relative(process.cwd(), aab) || aab}  (${(fs.statSync(aab).size / 1e6).toFixed(1)} MB)`);
+
+  const editId = await client.newEdit();
+  try {
+    const bundle = await client.uploadBundle(editId, aab);
+    const versionCode = bundle.versionCode;
+    if (!versionCode) throw new Error(`upload returned no versionCode: ${JSON.stringify(bundle).slice(0, 200)}`);
+    console.log(green(`  uploaded versionCode ${versionCode}`));
+
+    const releaseNotes = readNotes(g.metadataDir, versionCode, g.defaultLocale);
+    if (releaseNotes.length) {
+      console.log(`  release notes: ${releaseNotes.length} locale(s) — ${releaseNotes.map((n) => n.language).join(", ")}`);
+    } else {
+      console.log(yellow(`  no release notes found under ${g.metadataDir}/<locale>/changelogs/{${versionCode},default}.txt`));
+    }
+
+    // One complete release object: Play replaces the track's releases wholesale.
+    const release = { status: "completed", versionCodes: [String(versionCode)] };
+    if (releaseNotes.length) release.releaseNotes = releaseNotes;
+    const name = process.env.VYDANNE_RELEASE_NAME;
+    if (name) release.name = name;
+
+    const put = await client.putTrack(editId, track, [release]);
+    if (put.status >= 300) throw new Error(`tracks.update ${put.status}: ${JSON.stringify(put.json).slice(0, 300)}`);
+
+    if (process.env.VYDANNE_COMMIT !== "1") {
+      await client.deleteEdit(editId);
+      console.log(yellow(`\n  DRY RUN — edit discarded, nothing changed. Re-run with VYDANNE_COMMIT=1 to publish to "${track}".`));
+      return true;
+    }
+    const res = await client.commit(editId);
+    if (res.status >= 300) throw new Error(`edits.commit ${res.status}: ${JSON.stringify(res.json).slice(0, 300)}`);
+    console.log(green(`\n  committed — versionCode ${versionCode} is live on "${track}".`));
+    console.log("  Production stays manual: promote it in Play Console when you're ready.");
+    return true;
+  } catch (e) {
+    // Abandon the edit so a failed run leaves the track exactly as it was.
+    await client.deleteEdit(editId).catch(() => {});
+    console.error(red(`prerelease: ${e.message}`));
+    return false;
+  }
+}
+
+/** `google.aab` may be a file or a directory; a directory takes its newest .aab. */
+function resolveAab(configured) {
+  const p = process.env.VYDANNE_AAB || configured;
+  if (!p) return null;
+  const abs = path.resolve(p);
+  if (!fs.existsSync(abs)) return null;
+  if (!fs.statSync(abs).isDirectory()) return abs;
+  const files = fs.readdirSync(abs).filter((f) => f.endsWith(".aab"))
+    .map((f) => path.join(abs, f))
+    .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+  return files[0] || null;
+}
+
+/**
+ * Release notes per locale, following fastlane supply's layout so an existing repo needs no migration:
+ * `<metadataDir>/<play-locale>/changelogs/<versionCode>.txt`, falling back to `default.txt`.
+ */
+function readNotes(metadataDir, versionCode, defaultLocale) {
+  const out = [];
+  if (!metadataDir || !fs.existsSync(metadataDir)) return out;
+  for (const language of fs.readdirSync(metadataDir)) {
+    const dir = path.join(metadataDir, language, "changelogs");
+    if (!fs.existsSync(dir)) continue;
+    const file = [path.join(dir, `${versionCode}.txt`), path.join(dir, "default.txt")].find((f) => fs.existsSync(f));
+    if (!file) continue;
+    const text = fs.readFileSync(file, "utf8").trim();
+    if (!text) continue;
+    // Play caps release notes at 500 chars and rejects the whole edit if any locale is over.
+    if (text.length > 500) {
+      console.log(yellow(`  ${language}: release notes ${text.length}/500 chars — truncated`));
+      out.push({ language, text: text.slice(0, 500) });
+    } else {
+      out.push({ language, text });
+    }
+  }
+  // Keep the default locale first purely so the log reads sensibly.
+  return out.sort((a, b) => (a.language === defaultLocale ? -1 : b.language === defaultLocale ? 1 : 0));
+}

package/src/registry.mjs

@@ -23,7 +23,8 @@ export const PLAY_COMMANDS = {
   preflight: { mod: "preflight" },
   diff: { mod: "diff" },
   fill: { mod: "fill" },
+  prerelease: { mod: "prerelease" },
 };
 
-// Full public command surface (the module-dispatched ones above + the two handled inline in bin/).
-export const COMMAND_NAMES = [...Object.keys(COMMANDS), "locales", "version"];
+// Full public command surface (the module-dispatched ones above + the three handled inline in bin/).
+export const COMMAND_NAMES = [...Object.keys(COMMANDS), "prerelease", "auth", "locales", "version"];

package/types/index.d.ts

@@ -16,6 +16,9 @@ export type CommandName =
   | 'inspect'
   | 'diff'
   | 'preflight'
+  /** Google Play only: upload an .aab to a closed testing track. Refuses `production`. */
+  | 'prerelease'
+  | 'auth'
   | 'locales'
   | 'version';
 
@@ -57,6 +60,10 @@ export interface GoogleConfig {
   /** Listing-text folders, supply convention. Default 'fastlane/metadata/android'. */
   metadataDir?: string;
   defaultLocale?: string;
+  /** `.aab` for `prerelease` — a file, or a directory whose NEWEST .aab is taken. Override: VYDANNE_AAB. */
+  aab?: string;
+  /** Testing track for `prerelease`: 'internal' (default) | 'alpha' | 'beta'. 'production' is refused. */
+  track?: "internal" | "alpha" | "beta";
 }
 
 export interface ExportConfig {
@@ -74,8 +81,12 @@ export interface VydanneConfig {
   bundleId: string;
   /** Fallback for every locale without its own listing — must be populated. */
   primaryLocale: string;
-  /** Prefer ASC_KEY_ID / ASC_ISSUER_ID env over putting these in the config. */
-  asc?: { keyId?: string; issuerId?: string };
+  /**
+   * Credential SELECTION only — never credentials. This file is committed, so a keyId/issuerId here is
+   * refused at load with a warning. Values resolve from the environment, a gitignored `.env`, or
+   * `~/.appstoreconnect/config.json`. `profile` picks one entry when that file uses named profiles.
+   */
+  asc?: { profile?: string };
   /** iOS and macOS are separate ASC platforms. */
   platforms?: Platform[];
   /** App UI locales; mapped to ASC codes (unsupported ones fall back to primary). */