vydanne 0.12.0 → 0.14.0

package/README.md

@@ -105,6 +105,7 @@ committed. A keyId or issuerId found there is refused at load, with a warning te
 | Source | Use it for |
 |---|---|
 | `ASC_KEY_ID` / `ASC_ISSUER_ID` / `PLAY_JSON_KEY_FILE` in the environment | CI secrets, one-off overrides |
+| `ASC_KEY_CONTENT` (the .p8, raw or base64) or `ASC_KEY_PATH` | CI — signs without writing the key to disk |
 | 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 |
 
@@ -491,6 +492,26 @@ allowCrossStoreTerms: ["Apple"],
 
 `VYDANNE_ALLOW_CROSS_STORE=1` overrides the whole check for one run.
 
+### When the build number is not the commit count
+
+`releases` maps a store's build number back to a commit because the build number IS
+`git rev-list --count`. A repo can be forced off that and be unable to get back: ship from a long
+branch, squash it onto the release branch, and the count lands *below* build numbers already
+uploaded. Google Play reserves every versionCode it has ever been given, so those numbers cannot
+be freed and the only way past them is a constant added to the count.
+
+```js
+buildNumberOffset: 100,   // build number = git rev-list --count <commit> + 100
+```
+
+`releases` then resolves commits again and prints the offset it applied, on both stores. Leave it
+at 0 — the default — for every app that never had the accident.
+
+It is the one input here vydanne **cannot** verify. The count check validates an index against its
+own commit, which a wrong offset passes just as cleanly as a right one, so a bad value names a
+wrong commit with full confidence. It is refused unless it is an integer, and reported wherever it
+is used, but keeping it true is yours.
+
 ### Accessibility Nutrition Labels
 
 Every other thing vydanne writes is a *fact* about your app. This one is a **claim about its

package/SKILL.md

@@ -36,7 +36,7 @@ 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
+environment (`ASC_KEY_ID` / `ASC_ISSUER_ID` / `PLAY_JSON_KEY_FILE`, plus `ASC_KEY_CONTENT` or `ASC_KEY_PATH` for the signing key in CI) → the **`.env` cascade** → the **user
 config file**.
 
 The cascade is the standard one (dotenv-parsed, later file wins): `.env` → `.env.<mode>` → `.env.local` →
@@ -57,7 +57,7 @@ which user file was used, and whether the `.p8` is on disk.
 `{profile}` — selection only, never secrets) · `platforms` (iOS and macOS are SEPARATE) · `uiLocales`
 (auto-mapped to ASC codes) · `localeMap` · `metadataDir` · `screenshots` · `rating` · `ageRating` ·
 `privacy` · `iaps` · `previews` · `export` · `accessibility` · `ios` · `google` (Google Play) ·
-`bridge` · `push` · `reviewContact` · `allowCrossStoreTerms`.
+`bridge` · `push` · `reviewContact` · `allowCrossStoreTerms` · `buildNumberOffset`.
 
 **Paths are defaults, not laws.** `metadataDir` (default `fastlane/metadata`), `screenshots`
 (`{IOS, MAC_OS}`, default `fastlane/screenshots` + `-macos`) and `google.images` (Play image type →
@@ -316,7 +316,16 @@ names and whether it carries a **tag**. Both stores in this portfolio derive the
 `git rev-list --count HEAD` (Android's `versionCode`, iOS's `CURRENT_PROJECT_VERSION` via
 `Scripts/build-number.sh`), which makes it reversible.
 
-**Every mapping is verified, never assumed.** `rev-list --reverse` is ordered, not counted, so on a
+**`buildNumberOffset` when the count no longer matches.** A repo can be forced off the plain
+convention and be unable to get back: ship from a long branch, squash it onto the release branch,
+and the count lands BELOW versionCodes already uploaded — which Play reserves permanently, so a
+constant is the only way over them. `buildNumberOffset: 100` tells `releases` that
+`build = commits + 100`, and both commands print the offset they applied. It is the one number
+here vydanne cannot verify — the count check validates an index against its own commit and cannot
+tell a right offset from one wrong by five — so it is refused unless it is an integer, and stated
+wherever it is used rather than assumed.
+
+**Every other mapping is verified, never assumed.** `rev-list --reverse` is ordered, not counted, so on a
 merged history the Nth line need not be the commit with N ancestors — the candidate's own count has
 to match. An app that does not build this way, or a build number that is not a commit count, gets a
 stated reason instead of a confident wrong answer. That check has already caught a real one: a build

package/bin/vydanne.mjs

@@ -48,11 +48,16 @@ try {
     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`);
+    // The key can now arrive three ways; say WHICH, because "missing" pointing at a path that CI was
+    // never going to have is the least useful thing this command could print on a 401.
+    if (cr.keyContent) {
+      console.log(`  \x1b[32m✓\x1b[0m ${"signing key".padEnd(20)} <inline> ${"".padEnd(17)}← ${cr.sources.ASC_KEY_CONTENT}`);
+    } else if (cr.keyId) {
+      const p = cr.keyPath || 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}`);
+        : `  \x1b[31m✗\x1b[0m ${"signing key".padEnd(20)} \x1b[31mmissing\x1b[0m — ${p}\n` +
+          `      in CI set ASC_KEY_CONTENT (the .p8, raw or base64) instead of writing this file`);
     }
     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) {
@@ -88,7 +93,7 @@ try {
     const spec = COMMANDS[cmd];
     const { run } = await import(`../src/commands/${spec.mod}.mjs`);
     const dryRun = Boolean(spec.writes) && !apply;
-    const client = spec.client ? new Client({ keyId: cfg.keyId, issuerId: cfg.issuerId, dryRun }) : null;
+    const client = spec.client ? new Client({ keyId: cfg.keyId, issuerId: cfg.issuerId, keyPath: cfg.keyPath, keyContent: cfg.keyContent, dryRun }) : null;
     if (dryRun) console.log(yellow(`DRY RUN — '${cmd}' will not change App Store Connect. Add --apply to write.`));
     // altool authenticates on its own rather than through our JWT, so it needs the raw ids.
     const ok = await run(cfg, client, spec.credentials ? { keyId: cfg.keyId, issuerId: cfg.issuerId } : undefined);
@@ -153,6 +158,8 @@ usage: vydanne <command> [--apply] [--config vydanne.config.mjs]
   locales         UI -> ASC locale mapping + unsupported
   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
+  CI: ASC_KEY_CONTENT carries the .p8 itself (raw or base64) so no key is written to the runner disk;
+  ASC_KEY_PATH points at one. Without either, the key is read from ~/.appstoreconnect/private_keys.
   (\$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_REPLACE=1 (fill/previews:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vydanne",
-  "version": "0.12.0",
+  "version": "0.14.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, build upload to TestFlight / a Play closed track, a diff of local-vs-store, and a preflight verifier that encodes the store gotchas. Never submits for review. iOS/macOS via the ASC REST API; Android via the Play Developer Edits API (--store google).",
   "keywords": [
     "app-store-connect",

package/src/buildCommit.mjs

@@ -10,7 +10,22 @@ import { execFileSync } from "node:child_process";
  * or reproducing a store binary needs the tree the archive was cut from, and a version string does
  * not identify one.
  *
- * ### Nothing here assumes the convention holds — it VERIFIES it, per build
+ * ### The offset, and what it costs
+ *
+ * `buildNumberOffset` shifts the relationship to `count + offset`, because a repo can be forced
+ * off the plain count and not be able to get back. Squash a long branch onto `master` after
+ * shipping from it and master's count lands BELOW build numbers already uploaded — and Google Play
+ * reserves every versionCode it has ever been given, so the only way over them is a constant.
+ *
+ * **The offset is a declaration this module cannot check**, and that is a real weakening worth
+ * stating rather than burying. The count check below verifies an INDEX against its own commit; it
+ * cannot tell a correct offset from one that is wrong by five, because the commit five places away
+ * verifies just as cleanly. So a wrong offset buys exactly the confident wrong answer everything
+ * else here exists to refuse. It is declared once per app, in a committed file, next to the script
+ * that stamps the number — and the commands say which offset they applied, so a reader can see the
+ * assumption instead of inheriting it.
+ *
+ * ### Nothing else here assumes the convention holds — it VERIFIES it, per build
  *
  * vydanne is pointed at apps that do not build this way, so a mapping that trusted the convention
  * would confidently name the wrong commit for them. Every answer below is checked
@@ -59,12 +74,20 @@ export function tagsAt(sha) {
  * Returns `{ sha }` when the count checks out, or `{ why }` naming what stopped it — which is the
  * useful half. "This build has no commit" is a finding about the release, not a gap in the tool.
  */
-export function commitForBuild(order, build) {
-  const n = Number(build);
+export function commitForBuild(order, build, offset = 0) {
+  const raw = Number(build);
   if (!order) return { why: "not a git checkout" };
-  if (!Number.isInteger(n) || n < 1) return { why: `build "${build}" is not a number` };
+  if (!Number.isInteger(raw)) return { why: `build "${build}" is not a number` };
+  // Every message below quotes the arithmetic when an offset is in play. A misconfigured offset
+  // surfaces here first, as a build that is impossibly far past HEAD, and "490 - 100 = 390, past
+  // HEAD (200 commits)" says which of the two numbers to go and look at.
+  const n = raw - offset;
+  const shown = offset ? `build ${raw} - offset ${offset} = ${n}` : `build ${n}`;
+  if (n < 1) {
+    return { why: `${shown} is below the first commit — the offset is larger than the build number` };
+  }
   if (n > order.length) {
-    return { why: `build ${n} is past HEAD (${order.length} commits) — built elsewhere, or on an unmerged branch` };
+    return { why: `${shown} is past HEAD (${order.length} commits) — built elsewhere, or on an unmerged branch` };
   }
   const sha = order[n - 1];
   let count;

package/src/client.mjs

@@ -21,8 +21,8 @@ const MUTATING = new Set(["POST", "PATCH", "PUT", "DELETE"]);
 // 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, dryRun = false }) {
-    this.token = makeToken({ keyId, issuerId });
+  constructor({ keyId, issuerId, keyPath, keyContent, dryRun = false }) {
+    this.token = makeToken({ keyId, issuerId, keyPath, keyContent });
     /** No mutating request leaves this process. Set by bin/ for a write command without `--apply`. */
     this.dryRun = dryRun;
     /** What a real run WOULD have sent, in order — the dry-run report, and the count bin/ prints. */

package/src/commands/releases.mjs

@@ -42,6 +42,10 @@ export async function run(config, client) {
 
   const order = commitOrder();
   if (!order) console.log(yellow("  not a git checkout — commit and tag columns unavailable"));
+  // Said once, not per row: the commit column is only as true as this number, and a reader who
+  // does not know it was applied has no way to tell a mapping from an assumption.
+  const offset = config.buildNumberOffset || 0;
+  if (order && offset) console.log(`  commit column assumes buildNumberOffset=${offset} (build = commits + ${offset})`);
 
   // Newest first: the question is almost always about the last one or two.
   versions.sort((a, b) => String(b.attributes.createdDate).localeCompare(String(a.attributes.createdDate)));
@@ -71,7 +75,7 @@ export async function run(config, client) {
     } else if (backwards) {
       note = yellow(backwards);
     } else {
-      const got = commitForBuild(order, build);
+      const got = commitForBuild(order, build, offset);
       if (got.sha) {
         commit = got.sha.slice(0, 9);
         const tags = tagsAt(got.sha);

package/src/config.mjs

@@ -8,11 +8,26 @@ import { DEFAULT_PLAY_IMAGES } from "./play/images.mjs";
 
 // The public config surface — the drift guards assert each key is documented (README/SKILL) and typed
 // (types/index.d.ts). Add a config knob → document + type it, or the guards fail before publish.
-export const CONFIG_KEYS = ["bundleId", "primaryLocale", "asc", "platforms", "uiLocales", "localeMap", "metadataDir", "screenshots", "rating", "ageRating", "categories", "contentRights", "privacy", "iaps", "previews", "export", "ios", "google", "accessibility", "bridge", "push", "reviewContact", "allowCrossStoreTerms"];
+export const CONFIG_KEYS = ["bundleId", "primaryLocale", "asc", "platforms", "uiLocales", "localeMap", "metadataDir", "screenshots", "rating", "ageRating", "categories", "contentRights", "privacy", "iaps", "previews", "export", "ios", "google", "accessibility", "bridge", "push", "reviewContact", "allowCrossStoreTerms", "buildNumberOffset"];
 
 // One `vydanne.config.mjs` per app (ESM, like zdymak.config.mjs) — nothing hard-coded. Secrets stay out:
 // credentials resolve from the environment, a gitignored .env, or ~/.appstoreconnect/config.json (see
 // credentials.mjs) and are REFUSED if found in this committed file; review-contact PII stays gitignored.
+/**
+ * An integer config value, or the default when absent — and a refusal when it is neither.
+ *
+ * `buildNumberOffset: "100"` would otherwise coerce through the arithmetic and shift every commit
+ * lookup by a string, which resolves to a real commit and reports it with no hint anything is
+ * wrong. A value this load-bearing is worth one type check.
+ */
+function integerOr(name, value, fallback) {
+  if (value == null) return fallback;
+  if (!Number.isInteger(value)) {
+    throw new Error(`vydanne: config '${name}' must be an integer, got ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
 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}`);
@@ -35,6 +50,7 @@ export async function loadConfig(p) {
     primaryLocale: need("primaryLocale"),
     keyId: creds.keyId,
     issuerId: creds.issuerId,
+    keyPath: creds.keyPath,
     uiLocales: raw.uiLocales || [],
     // App code -> App Store locale, for codes Apple spells differently or does not know yet. Merged over
     // the built-in table rather than replacing it, so an app declares only its exceptions.
@@ -71,6 +87,13 @@ export async function loadConfig(p) {
     bridge: raw.bridge
       ? { out: raw.bridge.out || null, apple: raw.bridge.apple || null, play: raw.bridge.play || null }
       : null,
+    // `build number = git rev-list --count <commit> + buildNumberOffset`, for a repo that was
+    // forced off the plain count and cannot get back — squash a long branch onto the release
+    // branch after shipping from it and the count lands below versionCodes already spent, which
+    // Play reserves forever. Unlike everything else in buildCommit.mjs this is a DECLARATION the
+    // tool cannot verify, so it is refused unless it is an integer and reported wherever it is
+    // applied. 0 means the plain convention, which is every app that never had the accident.
+    buildNumberOffset: integerOr("buildNumberOffset", raw.buildNumberOffset, 0),
     // Terms the cross-store check must not flag for this app (see src/crossStore.mjs).
     allowCrossStoreTerms: raw.allowCrossStoreTerms || [],
     previews: raw.previews || null,
@@ -115,5 +138,8 @@ export async function loadConfig(p) {
       : null,
   };
   c.resolvedLocales = resolveLocales(c.uiLocales, c.localeMap);
+  // The signing key rides along NON-ENUMERABLE, like it does on the credentials object: a config is
+  // exactly the kind of thing someone dumps while debugging, and a private key must not be in that dump.
+  Object.defineProperty(c, "keyContent", { value: creds.keyContent, enumerable: false, writable: false });
   return c;
 }

package/src/credentials.mjs

@@ -152,13 +152,25 @@ export function resolveCredentials(raw = {}, cwd = process.cwd(), env = process.
     return undefined;
   };
 
-  return {
+  // The signing key itself, for CI. A developer machine keeps the .p8 in ~/.appstoreconnect and needs
+  // neither of these; a runner has only environment variables, and without them every workflow had to
+  // write the key to disk itself just to satisfy vydanne's path convention.
+  //
+  // NON-ENUMERABLE, deliberately: a private key must not be one careless `console.log(creds)` or
+  // `JSON.stringify(config)` away from a CI log that the whole team can read. Explicit property access
+  // still works, which is the only way it is ever read; a spread or a dump cannot see it.
+  const keyContent = pick("ASC_KEY_CONTENT", "keyContent");
+
+  const out = {
     keyId: pick("ASC_KEY_ID", "keyId"),
     issuerId: pick("ASC_ISSUER_ID", "issuerId"),
+    keyPath: expandHome(pick("ASC_KEY_PATH", "keyPath"), home),
     playJsonKeyFile: expandHome(pick("PLAY_JSON_KEY_FILE", "playJsonKeyFile"), home),
     sources,
     warnings,
     userFile,
     candidates: configCandidates(env, home),
   };
+  Object.defineProperty(out, "keyContent", { value: keyContent, enumerable: false, writable: false });
+  return out;
 }

package/src/index.mjs

@@ -13,7 +13,7 @@ export { PlayClient } from "./play/client.mjs";
 export { loadConfig, CONFIG_KEYS } from "./config.mjs";
 export { COMMANDS, PLAY_COMMANDS, COMMAND_NAMES } from "./registry.mjs";
 export { resolveLocales, toAsc, VALID, UI_TO_ASC } from "./locales.mjs";
-export { makeToken } from "./jwt.mjs";
+export { makeToken, resolveKey } from "./jwt.mjs";
 export { DEFAULT_SCREENSHOT_BASE, IOS_DEVICE, MAC_DEVICE, screenshotBase } from "./screenshots.mjs";
 export { DEFAULT_PLAY_IMAGES, PLAY_IMAGE_KIND, playImages } from "./play/images.mjs";
 
@@ -55,7 +55,7 @@ export async function runCommand(name, opts = {}) {
     return { ok: (await run(config, client)) !== false, planned: [] };
   }
 
-  const client = spec.client ? new Client({ keyId: config.keyId, issuerId: config.issuerId, dryRun }) : null;
+  const client = spec.client ? new Client({ keyId: config.keyId, issuerId: config.issuerId, keyPath: config.keyPath, keyContent: config.keyContent, dryRun }) : null;
   const { run } = await import(`./commands/${spec.mod}.mjs`);
   // altool authenticates on its own rather than through our JWT, so it needs the raw ids.
   const ok = await run(config, client, spec.credentials ? { keyId: config.keyId, issuerId: config.issuerId } : undefined);

package/src/jwt.mjs

@@ -3,12 +3,51 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
+const PEM_MARKER = "-----BEGIN";
+
+/**
+ * The .p8 itself, from whichever place this machine keeps it.
+ *
+ * A FILE is the right default on a developer's Mac, where the key sits beside the credentials in
+ * `~/.appstoreconnect`. It is the wrong and only option in CI, where a secret arrives as an
+ * environment variable and there is no home directory worth writing to — every caller was left
+ * materialising the key itself:
+ *
+ *     mkdir -p "$HOME/.appstoreconnect/private_keys"
+ *     printf '%s' "$ASC_KEY_CONTENT" | base64 --decode > ".../AuthKey_${ASC_KEY_ID}.p8"
+ *
+ * That is four lines of shell, per workflow, that must agree with vydanne's private path convention —
+ * and it silently writes a signing key to disk on a shared runner. `keyContent` removes the need.
+ *
+ * Accepts the PEM as-is or base64-encoded, because CI secrets are usually stored base64 (GitHub's own
+ * docs recommend it for multi-line values, and `ASC_KEY_CONTENT` is already base64 wherever fastlane
+ * reads it with `is_key_content_base64`).
+ */
+export function resolveKey({ keyId, keyPath, keyContent }) {
+  if (keyContent) {
+    const raw = keyContent.trim();
+    if (raw.includes(PEM_MARKER)) return raw;
+    const decoded = Buffer.from(raw, "base64").toString("utf8");
+    if (decoded.includes(PEM_MARKER)) return decoded;
+    throw new Error(
+      "vydanne: ASC_KEY_CONTENT is neither a PEM nor base64 of one — expected it to contain " +
+        `"${PEM_MARKER} PRIVATE KEY". Check the secret was stored whole, newlines included.`,
+    );
+  }
+  const file = keyPath || path.join(os.homedir(), ".appstoreconnect", "private_keys", `AuthKey_${keyId}.p8`);
+  if (!fs.existsSync(file)) {
+    throw new Error(
+      `vydanne: ASC key not found at ${file}. On a developer machine put the .p8 there; in CI set ` +
+        "ASC_KEY_CONTENT (the .p8, raw or base64) or ASC_KEY_PATH instead — no file needed.",
+    );
+  }
+  return fs.readFileSync(file, "utf8");
+}
+
 // App Store Connect JWT (ES256). Node's built-in crypto signs it — `dsaEncoding: "ieee-p1363"` returns the
 // raw r||s signature JWT/JOSE needs (the default DER encoding would be rejected). No fastlane/spaceship.
-export function makeToken({ keyId, issuerId, keyPath }) {
-  keyPath ||= path.join(os.homedir(), ".appstoreconnect", "private_keys", `AuthKey_${keyId}.p8`);
-  if (!fs.existsSync(keyPath)) throw new Error(`vydanne: ASC key not found at ${keyPath}`);
-  const p8 = fs.readFileSync(keyPath, "utf8");
+export function makeToken({ keyId, issuerId, keyPath, keyContent }) {
+  const p8 = resolveKey({ keyId, keyPath, keyContent });
   const b64u = (o) => Buffer.from(typeof o === "string" ? o : JSON.stringify(o)).toString("base64url");
   const now = Math.floor(Date.now() / 1000);
   const input = `${b64u({ alg: "ES256", kid: keyId, typ: "JWT" })}.${b64u({ iss: issuerId, iat: now, exp: now + 1200, aud: "appstoreconnect-v1" })}`;

package/src/play/commands/releases.mjs

@@ -41,6 +41,10 @@ export async function run(config, client) {
 
   const order = commitOrder();
   if (!order) console.log(yellow("  not a git checkout — commit and tag columns unavailable"));
+  // Said once, not per row: the commit column is only as true as this number, and a reader who
+  // does not know it was applied has no way to tell a mapping from an assumption.
+  const offset = config.buildNumberOffset || 0;
+  if (order && offset) console.log(`  commit column assumes buildNumberOffset=${offset} (versionCode = commits + ${offset})`);
 
   const editId = await client.newEdit();
   let uploaded = [];
@@ -92,7 +96,7 @@ export async function run(config, client) {
       let commit = "-";
       let tag = "-";
       let note = "";
-      const got = commitForBuild(order, row.code);
+      const got = commitForBuild(order, row.code, offset);
       if (got.sha) {
         commit = got.sha.slice(0, 9);
         const tags = tagsAt(got.sha);

package/types/index.d.ts

@@ -343,11 +343,23 @@ export interface VydanneConfig {
    * "apple"); it is not a way to ship a store name.
    */
   allowCrossStoreTerms?: string[];
+
+  /**
+   * `build number = git rev-list --count <commit> + buildNumberOffset`. Defaults to 0, which is
+   * the plain convention.
+   *
+   * Set it only for a repo that was forced off the plain count and cannot get back: ship from a
+   * long branch, squash that branch onto the release branch, and the count lands below build
+   * numbers already uploaded — which Google Play reserves permanently, so a constant is the only
+   * way over them. It is a declaration vydanne cannot verify, so keep it true; a wrong one names
+   * a wrong commit as confidently as a right one.
+   */
+  buildNumberOffset?: number;
 }
 
 /** Thin ASC REST client (native fetch + ES256 JWT). */
 export declare class Client {
-  constructor(opts: { keyId: string; issuerId: string; dryRun?: boolean });
+  constructor(opts: { keyId: string; issuerId: string; keyPath?: string; keyContent?: string; dryRun?: boolean });
   token: string;
   appId?: string;
   app?: unknown;
@@ -408,7 +420,22 @@ export declare function runCommand(
 ): Promise<{ ok: boolean; planned: Array<{ method: string; path: string; attributes: Record<string, unknown> }> }>;
 
 export declare function loadConfig(path?: string): Promise<ResolvedConfig>;
-export declare function makeToken(opts: { keyId: string; issuerId: string; keyPath?: string }): string;
+/**
+ * App Store Connect JWT (ES256).
+ *
+ * The signing key comes from ONE of three places, in order: `keyContent` (the .p8 itself, raw PEM or
+ * base64 — what CI hands over, so no key is written to a runner's disk), `keyPath`, or the default
+ * `~/.appstoreconnect/private_keys/AuthKey_<keyId>.p8`.
+ */
+export declare function makeToken(opts: {
+  keyId: string;
+  issuerId: string;
+  keyPath?: string;
+  keyContent?: string;
+}): string;
+
+/** The .p8 text itself, from `keyContent` / `keyPath` / the default location. Throws if it is neither. */
+export declare function resolveKey(opts: { keyId?: string; keyPath?: string; keyContent?: string }): string;
 export declare function resolveLocales(uiCodes: string[], extra?: Record<string, string>): ResolvedLocales;
 export declare function toAsc(code: string, extra?: Record<string, string>): string | null;
 export declare const VALID: Set<string>;