react-native-paperplane 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="pp-social-dark.png" />
+    <img src="pp-social.png" alt="React Native paper plane" width="900" />
+  </picture>
+</p>
+
+<h1 align="center">React Native Paperplane</h1>
+
+Tiny CLI to bump iOS build numbers, build/export with Xcode, and upload to TestFlight.
+
+License: MIT
+
+## Features
+
+- One-command TestFlight release flow for iOS
+- Supports app.config.ts, app.config.js, and app.json (text-only parsing)
+- Dry run mode and clean git enforcement
+- Deterministic output paths for build artifacts
+
+## Requirements
+
+- Node 18+ or Bun
+- Xcode Command Line Tools
+- Transporter app installed and signed in (for iTMSTransporter)
+- Repo with ios/ and an Xcode workspace
+- One of: app.config.ts, app.config.js, app.json
+
+## Install
+
+```bash
+npm install -D react-native-paperplane
+# or
+bun add -d react-native-paperplane
+```
+
+## Quick start
+
+```bash
+npx react-native-paperplane --dry-run
+npx react-native-paperplane
+```
+
+Bun alternative:
+
+```bash
+bunx react-native-paperplane --dry-run
+bunx react-native-paperplane
+```
+
+## Local development
+
+```bash
+# run locally without publishing
+bun src/cli.js --help
+# or
+node src/cli.js --help
+```
+
+Optional global-style bin for development:
+
+```bash
+npm link
+paperplane --help
+```
+
+## Usage
+
+```bash
+paperplane [options]
+```
+
+### Options
+
+- `--build-number <n>`: Set explicit build number (default: current + 1)
+- `--message <msg>`: Override git commit message
+- `--dry-run`: Show actions without modifying files or running build/upload
+- `--allow-dirty`: Skip clean git check
+- `--skip-upload`: Build/export only; skip upload
+- `-h, --help`: Show help
+
+## Environment variables
+
+Required for upload (Apple ID auth only):
+
+- `ASC_APPLE_ID`
+- `ASC_APP_PASSWORD`
+
+Optional:
+
+- `ASC_ITC_PROVIDER`
+
+iOS overrides:
+
+- `IOS_APP_NAME`
+- `IOS_SCHEME`
+- `IOS_WORKSPACE`
+
+## Project assumptions
+
+- ios/ contains an Xcode workspace (or set IOS_WORKSPACE).
+- Info.plist is at ios/<AppName>/Info.plist.
+- Build number is read from text in app.config.ts, app.config.js, or app.json.
+
+## Output paths
+
+Artifacts are written to:
+
+```
+ios/build/testflight/<runId>/
+```
+
+## Examples
+
+```bash
+# dry run
+paperplane --dry-run
+
+# explicit build number
+paperplane --build-number 42
+
+# build only, no upload
+paperplane --skip-upload
+```
+
+## FAQ
+
+**Why Bun?**
+Bun is fast and works great for CLI workflows. This package also runs on Node 18+.
+
+**Transporter errors?**
+Install Transporter from the Mac App Store and sign in once.
+
+## Publishing checklist
+
+- Confirm the package name is available on npm: `npm view react-native-paperplane`.
+- Update `package.json` version.
+- Run a quick help check: `node src/cli.js --help`.
+- Dry pack: `npm pack` and sanity-check the tarball contents.
+- Publish: `npm publish --access public`.
+
+Notes:
+- `--access public` is only required for scoped packages, but harmless for unscoped.
+
+```text
+                                                                                    :
+                                                                   =               ..=
+                                                                                 +
+                                                               =..=                     @%@..%@@
+                                                                               +%%@.....+%@...@
+                                                                        @@@..:...-:.+%@@.-..@
+                                                  -             @%@.-........-..#++@....--@@
+                                                        %@%@...:.....-......#++%@..:...:.@     .
+                                                #%%@....+.-....=.:.+.. .#+*@%..-....:..@       =
+                                         @@@.....-................=.#++=%@..=...-:::=.@
+                                 @%%=...::...*......*....:......++==%@........:=::-.@    -    +
+                       =    @@..::.-.:::...... ...-.......-.@*++@%........::=::--.*@     .
+                       .        @@.::::.:.......+.......@+%++@#.........=#::::=..@
+                       +  +        @%.....*.:. ...-..++*+%%..........:=:::.+:-.@@
+                          +    .       @+.......#++++@%.....-...=.----.-=---..@     =
+                        +      .        @+@%.**+++%@......#..=.--:.-+-:=--+.@@
+                                        @=+@.***%......:....*:---:::%:.--.=@
+                                         @-@:+*@.%@ ......::::.=:::--:-..@@
+                                    +     ---=+@==#%#%..:.:.::-.:*::-..@@
+                                          @:-+*.===*%#*@..:....::::+..@@
+                                           @%=@+==-+==@@ @%.....*...@@
+                                           @@+.:-=-@@      @%..=...@%
+                                            @@.-@@           @@..@@
+                                            #:@           *     @%
+
+                    PPPPPP     AAA    PPPPPP   EEEEEEE  RRRRRR   PPPPPP   L          AAA    N    N   EEEEEEE
+                    P     P   A   A   P     P  E        R    R   P     P  L         A   A   NN   N   E      
+                    P     P  A     A  P     P  E        R    R   P     P  L        A     A  N N  N   E      
+                    PPPPPP   A     A  PPPPPP   EEEEEE   RRRRRR   PPPPPP   L        A     A  N  N N   EEEEEE 
+                    P        AAAAAAA  P        E        R  R     P        L        AAAAAAA  N   NN   E      
+                    P        A     A  P        E        R   R    P        L        A     A  N    N   E      
+                    P        A     A  P        EEEEEEE  R    R   P        LLLLLLL  A     A  N    N   EEEEEEE
+```

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "react-native-paperplane",
+  "version": "1.0.0",
+  "description": "Tiny CLI to bump iOS build numbers, archive/export, and upload to TestFlight.",
+  "bin": {
+    "paperplane": "src/cli.js"
+  },
+  "scripts": {
+    "dev": "node src/cli.js --help",
+    "dev:bun": "bun src/cli.js --help"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "image.png"
+  ],
+  "keywords": [
+    "testflight",
+    "testflight-upload",
+    "ios",
+    "xcode",
+    "xcodebuild",
+    "app-store",
+    "app-store-connect",
+    "react-native",
+    "expo",
+    "ios-build",
+    "ipa",
+    "cli"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cli.js

@@ -0,0 +1,698 @@
+#!/usr/bin/env node
+"use strict";
+
+const {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  writeFileSync,
+} = require("fs");
+const { basename, join, resolve } = require("path");
+const { spawn, spawnSync } = require("child_process");
+
+const options = parseArgs(process.argv.slice(2));
+
+if (options.help) {
+  printBanner();
+  printHelp();
+  process.exit(0);
+}
+
+main().catch((error) => {
+  console.error(error?.message ?? error);
+  process.exit(1);
+});
+
+async function main() {
+  const rootDir = process.cwd();
+  printBanner();
+  loadDotEnv(resolve(rootDir, ".env"));
+
+  const iosDir = resolve(rootDir, "ios");
+  ensureDir(iosDir, "ios directory");
+
+  const config = resolveConfigFile(rootDir);
+  const workspacePath = resolveWorkspacePath(iosDir, rootDir);
+  const appName = resolveAppName(workspacePath);
+  const scheme = process.env.IOS_SCHEME ?? appName;
+  const infoPlistPath = resolve(iosDir, appName, "Info.plist");
+
+  ensureFile(infoPlistPath, "Info.plist");
+
+  if (!options.allowDirty) {
+    ensureCleanGit(rootDir);
+  }
+
+  const configText = readFileSync(config.path, "utf8");
+  const buildInfo = readBuildNumber(config, configText);
+
+  if (!buildInfo) {
+    die(`Unable to detect build number in ${config.path}.`);
+  }
+
+  const nextBuildNumber =
+    options.buildNumber ??
+    (() => {
+      if (buildInfo.current === null) {
+        die(`Unable to detect current build number in ${config.path}.`);
+      }
+      return buildInfo.current + 1;
+    })();
+
+  if (!Number.isInteger(nextBuildNumber) || nextBuildNumber <= 0) {
+    die("Build number must be a positive integer.");
+  }
+
+  if (buildInfo.current !== null && nextBuildNumber === buildInfo.current) {
+    die("Build number is already set to that value.");
+  }
+
+  const updatedConfigText = updateBuildNumber(
+    config,
+    configText,
+    nextBuildNumber,
+    buildInfo.source,
+  );
+  const infoPlistText = readFileSync(infoPlistPath, "utf8");
+  const updatedInfoPlistText = updatePlistBuildNumber(
+    infoPlistText,
+    nextBuildNumber,
+  );
+
+  if (options.dryRun) {
+    const currentPlistBuild = readPlistBuildNumber(infoPlistText) ?? "unknown";
+    console.log("Dry run:");
+    console.log(`- App: ${appName}`);
+    console.log(`- Workspace: ${workspacePath}`);
+    console.log(`- Scheme: ${scheme}`);
+    console.log(
+      `- ${basename(config.path)} buildNumber: ${buildInfo.current ?? "unknown"} -> ${nextBuildNumber}`,
+    );
+    console.log(
+      `- Info.plist CFBundleVersion: ${currentPlistBuild} -> ${nextBuildNumber}`,
+    );
+    console.log(
+      "- No files were written, no commit made, no build/export/upload executed.",
+    );
+    printSuccess({ dryRun: true });
+    process.exit(0);
+  }
+
+  writeFileSync(config.path, updatedConfigText);
+  writeFileSync(infoPlistPath, updatedInfoPlistText);
+
+  const commitMessage =
+    options.message ?? `chore(release): bump iOS build to ${nextBuildNumber}`;
+  const pathsToStage = [config.path];
+  if (isTracked(rootDir, infoPlistPath)) {
+    pathsToStage.push(infoPlistPath);
+  }
+  runOrThrow(rootDir, "git", ["add", ...pathsToStage]);
+  runOrThrow(rootDir, "git", ["commit", "-m", commitMessage]);
+
+  const runId = makeRunId();
+  const buildRoot = resolve(rootDir, "ios/build/testflight", runId);
+  const archivePath = join(buildRoot, `${appName}.xcarchive`);
+  const exportPath = join(buildRoot, "export");
+  const exportOptionsPath = join(buildRoot, "exportOptions.plist");
+
+  mkdirSync(buildRoot, { recursive: true });
+  mkdirSync(exportPath, { recursive: true });
+  writeFileSync(exportOptionsPath, buildExportOptionsPlist(), "utf8");
+
+  await runOrThrowAsync(rootDir, "xcodebuild", [
+    "-workspace",
+    workspacePath,
+    "-scheme",
+    scheme,
+    "-configuration",
+    "Release",
+    "-sdk",
+    "iphoneos",
+    "-destination",
+    "generic/platform=iOS",
+    "-archivePath",
+    archivePath,
+    "-allowProvisioningUpdates",
+    "archive",
+  ]);
+
+  await runOrThrowAsync(rootDir, "xcodebuild", [
+    "-exportArchive",
+    "-archivePath",
+    archivePath,
+    "-exportOptionsPlist",
+    exportOptionsPath,
+    "-exportPath",
+    exportPath,
+    "-allowProvisioningUpdates",
+  ]);
+
+  const ipaPath = findIpa(exportPath);
+  if (options.skipUpload) {
+    console.log(`Build/export complete. IPA ready at: ${ipaPath}`);
+    printSuccess({ ipaPath });
+    process.exit(0);
+  }
+
+  ensureTransporterAvailable(rootDir);
+  const uploadArgs = buildUploadArgs(ipaPath);
+
+  await runOrThrowAsync(rootDir, "xcrun", uploadArgs);
+
+  console.log(`Upload complete. IPA: ${ipaPath}`);
+  printSuccess({ ipaPath });
+}
+
+function parseArgs(args) {
+  const options = {
+    buildNumber: undefined,
+    message: undefined,
+    dryRun: false,
+    allowDirty: false,
+    skipUpload: false,
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === "--build-number" || arg.startsWith("--build-number=")) {
+      const value = arg.includes("=") ? arg.split("=")[1] : args[i + 1];
+      if (!value) {
+        die("Missing value for --build-number.");
+      }
+      const parsed = Number(value);
+      if (!Number.isInteger(parsed)) {
+        die(`Invalid build number: ${value}`);
+      }
+      options.buildNumber = parsed;
+      if (!arg.includes("=")) {
+        i += 1;
+      }
+      continue;
+    }
+
+    if (arg === "--message" || arg.startsWith("--message=")) {
+      const value = arg.includes("=") ? arg.split("=")[1] : args[i + 1];
+      if (!value) {
+        die("Missing value for --message.");
+      }
+      options.message = value;
+      if (!arg.includes("=")) {
+        i += 1;
+      }
+      continue;
+    }
+
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+
+    if (arg === "--allow-dirty") {
+      options.allowDirty = true;
+      continue;
+    }
+
+    if (arg === "--skip-upload") {
+      options.skipUpload = true;
+      continue;
+    }
+
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+
+    die(`Unknown argument: ${arg}`);
+  }
+
+  return options;
+}
+
+function printHelp() {
+  console.log(`Usage: paperplane [options]
+
+Options:
+  --build-number <n>   Set an explicit build number (default: +1)
+  --message <msg>      Commit message override
+  --dry-run            Show actions without modifying files
+  --allow-dirty        Skip clean git check
+  --skip-upload        Build/export only; skip Transporter upload
+  --help, -h           Show help
+
+Environment:
+  IOS_APP_NAME         iOS target folder + scheme (defaults to workspace name)
+  IOS_SCHEME           Override the Xcode scheme
+  IOS_WORKSPACE        Override the workspace path (relative to repo root)
+  ASC_APPLE_ID         Apple ID (required for upload)
+  ASC_APP_PASSWORD     App-specific password (required for upload)
+  ASC_ITC_PROVIDER     iTMSTransporter provider short name (optional)
+`);
+}
+
+function printBanner() {
+  const banner = [
+    "                                                                                    :",
+    "                                                                   =               ..=",
+    "                                                                                 +",
+    "                                                               =..=                     @%@..%@@",
+    "                                                                               +%%@.....+%@...@",
+    "                                                                        @@@..:...-:.+%@@.-..@",
+    "                                                  -             @%@.-........-..#++@....--@@",
+    "                                                        %@%@...:.....-......#++%@..:...:.@     .",
+    "                                                #%%@....+.-....=.:.+.. .#+*@%..-....:..@       =",
+    "                                         @@@.....-................=.#++=%@..=...-:::=.@",
+    "                                 @%%=...::...*......*....:......++==%@........:=::-.@    -    +",
+    "                       =    @@..::.-.:::...... ...-.......-.@*++@%........::=::--.*@     .",
+    "                       .        @@.::::.:.......+.......@+%++@#.........=#::::=..@",
+    "                       +  +        @%.....*.:. ...-..++*+%%..........:=:::.+:-.@@",
+    "                          +    .       @+.......#++++@%.....-...=.----.-=---..@     =",
+    "                        +      .        @+@%.**+++%@......#..=.--:.-+-:=--+.@@",
+    "                                        @=+@.***%......:....*:---:::%:.--.=@",
+    "                                         @-@:+*@.%@ ......::::.=:::--:-..@@",
+    "                                    +     ---=+@==#%#%..:.:.::-.:*::-..@@",
+    "                                          @:-+*.===*%#*@..:....::::+..@@",
+    "                                           @%=@+==-+==@@ @%.....*...@@",
+    "                                           @@+.:-=-@@      @%..=...@%",
+    "                                            @@.-@@           @@..@@",
+    "                                            #:@           *     @%",
+    "",
+    "                    PPPPPP     AAA    PPPPPP   EEEEEEE  RRRRRR   PPPPPP   L          AAA    N    N   EEEEEEE",
+    "                    P     P   A   A   P     P  E        R    R   P     P  L         A   A   NN   N   E      ",
+    "                    P     P  A     A  P     P  E        R    R   P     P  L        A     A  N N  N   E      ",
+    "                    PPPPPP   A     A  PPPPPP   EEEEEE   RRRRRR   PPPPPP   L        A     A  N  N N   EEEEEE ",
+    "                    P        AAAAAAA  P        E        R  R     P        L        AAAAAAA  N   NN   E      ",
+    "                    P        A     A  P        E        R   R    P        L        A     A  N    N   E      ",
+    "                    P        A     A  P        EEEEEEE  R    R   P        LLLLLLL  A     A  N    N   EEEEEEE",
+  ];
+  console.log(banner.join("\n"));
+  console.log("");
+}
+
+function printSuccess({ dryRun = false, ipaPath } = {}) {
+  console.log("");
+  if (dryRun) {
+    console.log("paperplane: dry run complete.");
+    return;
+  }
+  if (ipaPath) {
+    console.log(`paperplane: done -> ${ipaPath}`);
+    return;
+  }
+  console.log("paperplane: done.");
+}
+
+function loadDotEnv(path) {
+  try {
+    const content = readFileSync(path, "utf8");
+    const lines = content.split(/\r?\n/);
+    for (const rawLine of lines) {
+      const line = rawLine.trim();
+      if (!line || line.startsWith("#")) {
+        continue;
+      }
+      const match = line.match(
+        /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/,
+      );
+      if (!match) {
+        continue;
+      }
+      const key = match[1];
+      let value = match[2].trim();
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1);
+        if (rawLine.includes('"')) {
+          value = value
+            .replace(/\\n/g, "\n")
+            .replace(/\\r/g, "\r")
+            .replace(/\\t/g, "\t")
+            .replace(/\\\\/g, "\\");
+        }
+      } else {
+        value = value.replace(/\s+#.*$/, "");
+      }
+      if (process.env[key] === undefined) {
+        process.env[key] = value;
+      }
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      die(`Failed to read .env file at ${path}`);
+    }
+  }
+}
+
+function resolveConfigFile(rootDir) {
+  const candidates = ["app.config.ts", "app.config.js", "app.json"];
+  for (const candidate of candidates) {
+    const candidatePath = resolve(rootDir, candidate);
+    if (existsSync(candidatePath)) {
+      return {
+        path: candidatePath,
+        type: candidate.endsWith(".json") ? "appJson" : "appConfig",
+      };
+    }
+  }
+  die(
+    "No app config found. Expected one of app.config.ts, app.config.js, or app.json.",
+  );
+}
+
+function resolveWorkspacePath(iosDir, rootDir) {
+  const override = process.env.IOS_WORKSPACE;
+  if (override) {
+    const resolved = override.startsWith("/")
+      ? override
+      : resolve(rootDir, override);
+    ensureDir(resolved, "workspace");
+    return resolved;
+  }
+
+  const entries = readdirSync(iosDir, { withFileTypes: true })
+    .filter((entry) => entry.name.endsWith(".xcworkspace"))
+    .map((entry) => entry.name);
+
+  if (entries.length === 0) {
+    die("No .xcworkspace found in ios/. Set IOS_WORKSPACE.");
+  }
+
+  if (entries.length > 1) {
+    console.warn(
+      `Multiple workspaces found. Using ${entries[0]}. Set IOS_WORKSPACE to override.`,
+    );
+  }
+
+  return resolve(iosDir, entries[0]);
+}
+
+function resolveAppName(workspacePath) {
+  return process.env.IOS_APP_NAME ?? basename(workspacePath, ".xcworkspace");
+}
+
+function ensureFile(path, label) {
+  try {
+    const stats = statSync(path);
+    if (!stats.isFile()) {
+      die(`Expected ${label ?? "file"} at ${path}`);
+    }
+  } catch {
+    die(`Missing required ${label ?? "file"}: ${path}`);
+  }
+}
+
+function ensureDir(path, label) {
+  try {
+    const stats = statSync(path);
+    if (!stats.isDirectory()) {
+      die(`Expected ${label ?? "directory"} at ${path}`);
+    }
+  } catch {
+    die(`Missing required ${label ?? "directory"}: ${path}`);
+  }
+}
+
+function readBuildNumber(config, text) {
+  if (config.type === "appJson") {
+    return readBuildNumberFromAppJson(text);
+  }
+  return readBuildNumberFromAppConfig(text);
+}
+
+function readBuildNumberFromAppConfig(text) {
+  const iosRegex = /ios\s*:\s*{[\s\S]*?buildNumber\s*:\s*(['"])(\d+)\1/;
+  const anyRegex = /buildNumber\s*:\s*(['"])(\d+)\1/;
+
+  const iosMatch = text.match(iosRegex);
+  if (iosMatch) {
+    return {
+      current: Number(iosMatch[2]),
+      source: "appConfig:ios",
+    };
+  }
+
+  const anyMatch = text.match(anyRegex);
+  if (anyMatch) {
+    return {
+      current: Number(anyMatch[2]),
+      source: "appConfig:any",
+    };
+  }
+
+  return null;
+}
+
+function readBuildNumberFromAppJson(text) {
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch (error) {
+    die("app.json is not valid JSON.");
+  }
+
+  const iosBuild = json?.expo?.ios?.buildNumber;
+  if (iosBuild !== undefined && iosBuild !== null) {
+    if (!isDigits(String(iosBuild))) {
+      die("expo.ios.buildNumber must be a numeric string.");
+    }
+    return { current: Number(iosBuild), source: "appJson:expo.ios" };
+  }
+
+  const expoBuild = json?.expo?.buildNumber;
+  if (expoBuild !== undefined && expoBuild !== null) {
+    if (!isDigits(String(expoBuild))) {
+      die("expo.buildNumber must be a numeric string.");
+    }
+    return { current: Number(expoBuild), source: "appJson:expo" };
+  }
+
+  return null;
+}
+
+function updateBuildNumber(config, text, nextBuildNumber, source) {
+  if (config.type === "appJson") {
+    return updateBuildNumberInAppJson(text, nextBuildNumber, source);
+  }
+  return updateBuildNumberInAppConfig(text, nextBuildNumber);
+}
+
+function updateBuildNumberInAppConfig(text, nextBuildNumber) {
+  const iosRegex = /ios\s*:\s*{[\s\S]*?buildNumber\s*:\s*(['"])(\d+)\1/;
+  const anyRegex = /buildNumber\s*:\s*(['"])(\d+)\1/;
+
+  if (iosRegex.test(text)) {
+    const updated = text.replace(iosRegex, (match, quote) =>
+      match.replace(
+        /buildNumber\s*:\s*(['"])\d+\1/,
+        `buildNumber: ${quote}${nextBuildNumber}${quote}`,
+      ),
+    );
+    if (updated === text) {
+      die("Failed to update buildNumber in app.config.");
+    }
+    return updated;
+  }
+
+  if (anyRegex.test(text)) {
+    const updated = text.replace(anyRegex, (_, quote) => {
+      return `buildNumber: ${quote}${nextBuildNumber}${quote}`;
+    });
+    if (updated === text) {
+      die("Failed to update buildNumber in app.config.");
+    }
+    return updated;
+  }
+
+  die("Failed to update buildNumber in app.config.");
+}
+
+function updateBuildNumberInAppJson(text, nextBuildNumber, source) {
+  if (source === "appJson:expo.ios") {
+    const iosRegex = /("expo"\s*:\s*{[\s\S]*?"ios"\s*:\s*{[\s\S]*?"buildNumber"\s*:\s*")(\d+)(")/;
+    if (!iosRegex.test(text)) {
+      die("Failed to update expo.ios.buildNumber in app.json.");
+    }
+    return text.replace(iosRegex, `$1${nextBuildNumber}$3`);
+  }
+
+  const expoRegex = /("expo"\s*:\s*{[\s\S]*?"buildNumber"\s*:\s*")(\d+)(")/;
+  if (!expoRegex.test(text)) {
+    die("Failed to update expo.buildNumber in app.json.");
+  }
+  return text.replace(expoRegex, `$1${nextBuildNumber}$3`);
+}
+
+function readPlistBuildNumber(plistText) {
+  const match = plistText.match(
+    /<key>CFBundleVersion<\/key>\s*<string>([^<]*)<\/string>/,
+  );
+  return match ? match[1] : null;
+}
+
+function updatePlistBuildNumber(plistText, buildNumber) {
+  const updated = plistText.replace(
+    /(<key>CFBundleVersion<\/key>\s*<string>)([^<]*)(<\/string>)/,
+    `$1${buildNumber}$3`,
+  );
+  if (updated === plistText) {
+    die("Failed to update CFBundleVersion in Info.plist.");
+  }
+  return updated;
+}
+
+function buildExportOptionsPlist() {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>method</key>
+    <string>app-store-connect</string>
+    <key>signingStyle</key>
+    <string>automatic</string>
+    <key>uploadBitcode</key>
+    <false/>
+    <key>compileBitcode</key>
+    <false/>
+  </dict>
+</plist>
+`;
+}
+
+function findIpa(exportPath) {
+  const entries = readdirSync(exportPath);
+  const direct = entries.find((entry) => entry.endsWith(".ipa"));
+  if (direct) {
+    return join(exportPath, direct);
+  }
+  for (const entry of entries) {
+    const fullPath = join(exportPath, entry);
+    const stats = statSync(fullPath);
+    if (!stats.isDirectory()) {
+      continue;
+    }
+    const nested = readdirSync(fullPath).find((file) => file.endsWith(".ipa"));
+    if (nested) {
+      return join(fullPath, nested);
+    }
+  }
+  die("No .ipa found after export.");
+}
+
+function ensureTransporterAvailable(rootDir) {
+  const result = spawnSync("xcrun", ["--find", "iTMSTransporter"], {
+    cwd: rootDir,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.status !== 0) {
+    die(
+      "iTMSTransporter not found. Install the Transporter app from the Mac App Store, then try again.",
+    );
+  }
+}
+
+function buildUploadArgs(ipaPath) {
+  const appleId = process.env.ASC_APPLE_ID;
+  const applePassword = process.env.ASC_APP_PASSWORD;
+  const provider = process.env.ASC_ITC_PROVIDER;
+
+  if (!appleId || !applePassword) {
+    die(
+      "Missing App Store Connect credentials. Set ASC_APPLE_ID and ASC_APP_PASSWORD.",
+    );
+  }
+
+  const args = [
+    "iTMSTransporter",
+    "-m",
+    "upload",
+    "-assetFile",
+    ipaPath,
+    "-u",
+    appleId,
+    "-p",
+    applePassword,
+  ];
+
+  if (provider) {
+    args.push("-itc_provider", provider);
+  }
+
+  return args;
+}
+
+function makeRunId() {
+  const iso = new Date().toISOString();
+  return iso.replace("T", "-").replace(/[:]/g, "").replace(/\..+/, "");
+}
+
+function runCapture(rootDir, cmd, args) {
+  const result = spawnSync(cmd, args, {
+    cwd: rootDir,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  return {
+    stdout: result.stdout?.toString() ?? "",
+    stderr: result.stderr?.toString() ?? "",
+    status: result.status ?? 0,
+  };
+}
+
+function ensureCleanGit(rootDir) {
+  const status = runCapture(rootDir, "git", ["status", "--porcelain"]);
+  if (status.stdout.trim().length > 0) {
+    die(
+      "Working tree is not clean. Commit or stash changes first, or pass --allow-dirty.",
+    );
+  }
+}
+
+function isTracked(rootDir, path) {
+  const result = spawnSync("git", ["ls-files", "--error-unmatch", path], {
+    cwd: rootDir,
+    stdio: ["ignore", "ignore", "ignore"],
+  });
+  return result.status === 0;
+}
+
+function runOrThrow(rootDir, cmd, args) {
+  const result = spawnSync(cmd, args, {
+    cwd: rootDir,
+    stdio: "inherit",
+  });
+  if (result.status !== 0) {
+    die(`Command failed: ${cmd} ${args.join(" ")}`);
+  }
+}
+
+function runOrThrowAsync(rootDir, cmd, args) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, {
+      cwd: rootDir,
+      stdio: "inherit",
+    });
+
+    proc.on("error", reject);
+    proc.on("close", (code) => {
+      if (code !== 0) {
+        reject(new Error(`Command failed: ${cmd} ${args.join(" ")}`));
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+function isDigits(value) {
+  return /^\d+$/.test(value);
+}
+
+function die(message) {
+  console.error(message);
+  process.exit(1);
+}