expo-release 2.0.0 → 2.2.0

package/README.md

@@ -17,9 +17,54 @@ decide — git diff + eas fingerprint:generate + eas build:list
      └─ no matching native build → eas build --auto-submit --no-wait
 ```
 
+## Install and requirements
+
+```sh
+bun add -D expo-release
+bunx expo-release --help
+```
+
+The CLI and GitHub Action require Bun. EAS operations also need an authenticated Expo account and the EAS CLI in the calling project; Expo SDK 55+ OTA updates require an explicit EAS environment. CI verifies Bun 1.4.2. Installing the npm package does not deploy an application.
+
+## Set up with AI
+
+Copy the prompt below into Cursor, Claude Code, or another coding agent to wire up expo-release in your existing repo.
+
+```
+Integrate expo-release (https://github.com/HansKristoffer/expo-release) into this codebase for fingerprint-driven Expo EAS releases.
+
+Goal: on push to the main deploy branch, when Expo-related paths change, automatically publish an OTA update if a finished native build matches the current fingerprint, or queue a native store build (with auto-submit) when no matching build exists.
+
+Do the following in this repo:
+
+1. Inspect the repo layout: find the Expo app directory, monorepo package manager (bun/npm/pnpm), lockfile location, EAS profiles in eas.json, and any app.config.ts variant env vars (e.g. APP_VARIANT, SECRETS_ENV, APS_ENVIRONMENT).
+
+2. Ensure the Expo app is ready for fingerprint-based updates:
+   - runtimeVersion: { policy: 'fingerprint' } in app config
+   - expo-updates installed and configured
+   - channel set on each EAS build profile we deploy
+   - submit config in eas.json if we use auto-submit (iOS ascAppId, Android serviceAccountKeyPath)
+
+3. Add .github/workflows/expo-release.yml using the HansKristoffer/expo-release@v2 composite action. Adapt consumer-specific values:
+   - paths filter: Expo app dir, shared packages that affect the native bundle, and lockfile if native deps should trigger a release
+   - working-directory and impact-paths pointing at the Expo app
+   - profile, environment, and channel for each deploy target
+   - env vars required by app.config.ts on the action step (APP_VARIANT, etc.)
+   - workflow_dispatch inputs for force-native, retry-ota, republish, rollback-embedded
+   - fetch-depth: 0 on checkout, Bun/Node setup, dependency install, expo/expo-github-action with pinned eas-version and EXPO_TOKEN secret
+
+4. Document that EXPO_TOKEN must be added as a GitHub secret, and that the first run on a new fingerprint always queues a native build.
+
+5. If we have staging + production (or multiple profiles), use separate jobs or a matrix with profile-specific concurrency groups.
+
+6. Do not change unrelated CI. Keep the diff minimal and match existing workflow conventions in this repo.
+
+Reference the upstream README for full input/output docs and recovery operations. Ask me only if a required value (Expo app path, deploy branch, profile names) cannot be inferred from the repo.
+```
+
 ## Install
 
-Use the composite action. The package is not published to npm.
+### GitHub Action
 
 ```yaml
 uses: HansKristoffer/expo-release@v2
@@ -27,6 +72,16 @@ uses: HansKristoffer/expo-release@v2
 
 The action runs `bun ${{ github.action_path }}/src/cli.ts`. The caller must already have checked out the repo (`fetch-depth: 0`), installed Bun, set up EAS, and installed workspace dependencies.
 
+### npm (CLI)
+
+For local use or custom CI:
+
+```bash
+bun add -D expo-release
+```
+
+Then run `expo-release` (see [CLI](#cli)).
+
 Pin `eas-cli` with `expo/expo-github-action`. The CLI invokes `eas` from `PATH` (override with `EAS_BIN` for local tests), so that pin is the version that actually runs.
 
 ## Setup checklist
@@ -176,6 +231,7 @@ A manual `deploy` from `workflow_dispatch` ignores the impact diff. That is inte
 | `pre-update` | _(empty)_ | Shell command before `eas update` (OTA only) |
 | `post-update` | _(empty)_ | Shell command after a successful `eas update` (OTA only) |
 | `update-extra-args` | _(empty)_ | Extra tokens appended to `eas update` |
+| `export-source-maps` | `false` | OTA only: `expo export --source-maps external`, refuse if `dist` has no `.map`, then `eas update --input-dir dist --skip-bundler`. Pair with `post-update` to upload those maps for PostHog error tracking. |
 | `group` | _(empty)_ | Required when `operation` is `republish` |
 | `runtime-version` | current fingerprint | Used when `operation` is `rollback-embedded` |
 | `message` | `{profile} {sha} (fp {hash})` | Override the generated `eas update` message |
@@ -224,7 +280,9 @@ bun "${{ github.action_path }}/src/cli.ts" decide \
 
 `pre-update`, `post-update`, and `update-extra-args` run only on the OTA path (`deploy` + `ota`, and `retry-ota`). Skip, native builds, republish, and rollback ignore them. Hook commands inherit process env. A non-zero hook exit fails operate; `post-update` does not run if `eas update` fails.
 
-Production apps that export Hermes maps first set them only on the production operate step:
+`export-source-maps` is the shared Hermes export. Set it only on profiles that should publish a pre-exported `dist` (usually production). Staging stays a default `eas update`.
+
+Use it with PostHog error tracking: the same `dist` bundle that goes to `eas update` contains the Hermes `.map` files PostHog needs to symbolicate production crashes. Upload them in `post-update` after a successful OTA (`POSTHOG_CLI_API_KEY`, `POSTHOG_CLI_PROJECT_ID`, and `POSTHOG_CLI_HOST` must reach the action step):
 
 ```yaml
 - uses: HansKristoffer/expo-release@v2
@@ -232,8 +290,7 @@ Production apps that export Hermes maps first set them only on the production op
     command: release
     profile: production
     environment: production
-    pre-update: bun scripts/release/export-hermes.ts
-    update-extra-args: --input-dir dist --skip-bundler
+    export-source-maps: 'true'
     post-update: bunx posthog-cli hermes upload --directory dist
   env:
     APP_VARIANT: production
@@ -241,7 +298,7 @@ Production apps that export Hermes maps first set them only on the production op
     APS_ENVIRONMENT: production
 ```
 
-`export-hermes.ts` is app-owned (typically `expo export --source-maps external` plus a Hermes `.map` check). Staging stays a default `eas update`.
+Override the Expo binary with `EXPO_BIN` (defaults to `bunx expo`). `--dry-run` prints the export command and skips the `.map` check.
 
 ### Recovery operations
 
@@ -255,7 +312,7 @@ Production apps that export Hermes maps first set them only on the production op
 
 ### Dry run
 
-`--dry-run` still runs `git diff`, `eas fingerprint:generate`, and `eas build:list` so the decision is real. It only prints `eas update`, `eas build`, recovery commands, and OTA hooks.
+`--dry-run` still runs `git diff`, `eas fingerprint:generate`, and `eas build:list` so the decision is real. It only prints `eas update`, `eas build`, recovery commands, `expo export` (when `export-source-maps` is on), and OTA hooks.
 
 ```yaml
 - uses: HansKristoffer/expo-release@v2
@@ -362,14 +419,213 @@ expo-release operate \
   [--group <update-group-id>] \
   [--runtime-version <hash>] \
   [--message "custom message"] \
-  [--pre-update "bun scripts/release/export-hermes.ts"] \
-  [--update-extra-args "--input-dir dist --skip-bundler"] \
+  [--export-source-maps true] \
+  [--pre-update "bun scripts/release/tag-dist.ts"] \
+  [--update-extra-args "--private-key-path key"] \
   [--post-update "bunx posthog-cli hermes upload --directory dist"]
 ```
 
 `release` is decide + operate (same as the action default). `force-native`, `republish`, and `rollback-embedded` skip decide. `decide` prints JSON including `deployType` and `nativeBuildPending`. When `GITHUB_OUTPUT` is set, decide writes `deploy_type`, `native_build_pending`, `changed`, `fingerprint`, `build_id`, `build_url`. Operate writes `result`.
 
 ```bash
-# local
-bun src/cli.ts decide --base HEAD^ --head HEAD --profile production
+# local (after bun add -D expo-release)
+expo-release decide --base HEAD^ --head HEAD --profile production
+```
+
+## App runtime
+
+`expo-release/runtime` has the app side of a release: OTA prompts, push notifications and a render-error boundary. Install the package as a dependency (not `-D`) to use it. `react`, `expo-updates`, `expo-notifications` and `expo-device` are optional peers; the CLI never needs them. The helpers render no UI: pass your toast, dialog and error screen.
+
+### OTA updates
+
+Checks once per launch, downloads a new update and hands you a `reload` for your "Restart" prompt. It is off in development and wherever expo-updates is disabled (Expo Go).
+
+```tsx
+import { useOTAUpdates } from 'expo-release/runtime'
+
+function AppContent() {
+  const { toast } = useToast()
+  useOTAUpdates((reload) =>
+    toast.show({
+      id: 'ota-update-available',
+      label: 'Update ready',
+      description: 'A new version downloaded. Tap Restart to apply.',
+      actionLabel: 'Restart',
+      onActionPress: reload
+    })
+  )
+}
+```
+
+The callback is read through a ref, so an unstable toast function never repeats the check. `checkForOTAUpdate(onUpdateReady)` runs the same check outside React.
+
+### Push notifications
+
+Create the service once. It sets the foreground handler and the Android `default` channel, and owns the permission flow and the Expo push token. Your backend call is `registerDevice` (`null` unregisters).
+
+```ts
+import AsyncStorage from '@react-native-async-storage/async-storage'
+import { Alert } from 'react-native'
+import { createPushNotifications } from 'expo-release/runtime'
+
+export const push = createPushNotifications({
+  storage: AsyncStorage,
+  registerDevice: (expoPushToken) =>
+    api.user.registerDevice({ platform: Platform.OS, expoPushToken }),
+  // Optional soft-ask before the OS dialog.
+  confirm: () =>
+    new Promise((resolve) =>
+      Alert.alert('Turn on alerts?', 'Get notified about new messages.', [
+        { text: 'Not now', style: 'cancel', onPress: () => resolve(false) },
+        { text: 'Enable', onPress: () => resolve(true) }
+      ])
+    ),
+  onUnavailable: (reason) => {
+    if (reason === 'denied') Alert.alert('Notifications off', 'Turn them on in device settings.')
+  },
+  onError: (message, error) => logger.error(message, error)
+})
+```
+
+| Member | Use |
+|--------|-----|
+| `prompt()` | After sign-in. Asks once per install (soft-ask, then OS dialog), registers the token on a grant. Never throws; concurrent calls share one dialog. |
+| `enable()` / `disable()` | Settings toggle. `enable` requests permission and registers; `disable` calls `registerDevice(null)`. Save the user's preference yourself, before `enable()`: a denied dialog then leaves the preference on with `isEnabled` false, and the token registers on the next mount once permission is granted in device settings. |
+| `syncToken()` | Re-registers the current token when permission is granted. |
+| `listen({ onReceived, onResponse })` | Subscribes and returns the unsubscribe function. `onResponse` also receives the tap that launched the app. |
+| `getPermissionStatus()`, `getPushToken()`, `requestPermissions()`, `hasPrompted()` | Lower-level steps. |
+
+`usePushNotifications(push, { enabled })` gives a settings screen `permission`, `isEnabled`, `isLoading` and wrapped `prompt`/`enable`/`disable`. `enabled` is the saved preference; while it is on, the token is re-registered on mount.
+
+### Error boundary
+
+```tsx
+import { ErrorBoundary } from 'expo-release/runtime'
+
+<ErrorBoundary
+  fallback={({ error, reset }) => <ErrorScreen message={error.message} onRetry={reset} />}
+  onError={(error, info) =>
+    posthog.captureException(error, { $exception_source: 'error_boundary', component_stack: info.componentStack })
+  }
+>
+  <App />
+</ErrorBoundary>
+```
+
+Report errors in `onError`: render errors are caught before they become uncaught exceptions, so error-tracking autocapture never sees them.
+
+## Workspace and PR actions
+
+Composite actions for Bun monorepos, used as `HansKristoffer/expo-release/.github/actions/<name>@v2`. Pass secrets as inputs.
+
+| Action | Does |
+|--------|------|
+| `setup-workspace` | Bun (version from `package.json` `packageManager` by default), optional Node, restore the dependency cache keyed on `bun.lock`, always `bun install --frozen-lockfile`, save on a miss with `save-cache: 'true'`. `cache-paths` and `cache-key-files` are inputs. |
+| `playwright-browsers` | Restores browsers for the installed Playwright version; installs and saves on a miss. |
+| `pr-preview` | Railway preview environment per PR with its own PlanetScale Postgres branch and a Cloudflare-managed host. Creates on open/sync, deletes on close. |
+| `ai-changelog` | Plain-language changelog of a pushed range with Claude; outputs `message` (chat) and `markdown`, optionally POSTs the message to a webhook. |
+
+### Warm the caches on main
+
+Caches written by `pull_request` runs are scoped to that PR. Warm them on main so every new PR starts from a hit:
+
+```yaml
+name: Cache Warm
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+concurrency:
+  group: cache-warm
+  cancel-in-progress: true
+permissions:
+  contents: read
+jobs:
+  warm:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v5
+      - uses: HansKristoffer/expo-release/.github/actions/setup-workspace@v2
+        with:
+          save-cache: 'true'
+          cache-paths: |   # consumer: add generated clients
+            node_modules
+            packages/*/node_modules
+            apps/*/node_modules
+      - uses: HansKristoffer/expo-release/.github/actions/playwright-browsers@v2
+        with:
+          working-directory: apps/platform
+```
+
+Use the same `cache-paths` in every job, since they are part of the cache version.
+
+### PR preview environments
+
+The preview duplicates `railway-source-environment` (default `staging`) into `pr-<number>`, points git-connected services at the PR branch, sets `DATABASE_URL` and `DATABASE_URL_DIRECT` to a fresh PlanetScale branch, attaches `pr-<number>.<zone>` with Cloudflare DNS, then sets `BASE_URL`, which triggers the one deployment (run migrations and seeds in your pre-deploy step).
+
+```yaml
+name: PR preview
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, closed]
+concurrency:
+  group: pr-preview-${{ github.event.number }}
+  cancel-in-progress: false
+permissions:
+  contents: read
+jobs:
+  preview:
+    # Fork PRs cannot read the secrets.
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - uses: HansKristoffer/expo-release/.github/actions/pr-preview@v2
+        with:
+          planetscale-org: ${{ secrets.PLANETSCALE_ORG_NAME }}
+          planetscale-database: my-app-staging
+          planetscale-service-token-id: ${{ secrets.PLANETSCALE_SERVICE_TOKEN_ID }}
+          planetscale-service-token: ${{ secrets.PLANETSCALE_SERVICE_TOKEN }}
+          railway-token: ${{ secrets.RAILWAY_STAGING_TOKEN }}
+          railway-project-id: ${{ secrets.RAILWAY_STAGING_PROJECT_ID }}
+          railway-service: ${{ secrets.RAILWAY_STAGING_SERVICE }}
+          cloudflare-api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          cloudflare-zone-id: ${{ secrets.CLOUDFLARE_ZONE_ID }}
+          cloudflare-zone-name: previews.example.com
 ```
+
+The action needs Cloudflare DNS for the preview host; a Railway-generated domain is not supported yet. Requirements: a PlanetScale **Postgres** database with a service token scoped to it (`read_branch`, `create_branch`, `delete_branch`, `create_branch_password`); a Railway account API token; a Cloudflare token with Zone.DNS Edit and the zone's SSL/TLS mode set to Full. Extensions such as `vector` must be enabled on the source branch.
+
+### AI changelog
+
+```yaml
+name: Changelog
+on:
+  push:
+    branches: [main]
+jobs:
+  changelog:
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: HansKristoffer/expo-release/.github/actions/ai-changelog@v2
+        with:
+          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
+          webhook-url: ${{ secrets.CHANGELOG_WEBHOOK_URL }}
+          webhook-token: ${{ secrets.CHANGELOG_WEBHOOK_TOKEN }}
+          webhook-payload: '{"groupId": "${{ secrets.CHANGELOG_GROUP_ID }}"}'
+```
+
+Without `webhook-url`, read `steps.<id>.outputs.message` and `outputs.markdown` yourself. `chat-format` sets the message style (WhatsApp by default) and `instructions` adds audience or product context.
+
+## Releasing
+
+Squash PRs with conventional titles (`fix:`, `feat:`, or `feat!:`). Release Please keeps the version and changelog in a release PR; merge that PR to publish with release notes and npm provenance. See [release and recovery instructions](docs/releasing.md).

package/action.yml

@@ -63,6 +63,10 @@ inputs:
     description: Extra tokens appended to eas update (e.g. --input-dir dist --skip-bundler)
     required: false
     default: ''
+  export-source-maps:
+    description: On OTA, expo export with external source maps, then publish dist
+    required: false
+    default: 'false'
   group:
     description: Update group ID required by operation=republish
     required: false
@@ -123,6 +127,7 @@ runs:
         EXPO_RELEASE_PRE_UPDATE: ${{ inputs.pre-update }}
         EXPO_RELEASE_POST_UPDATE: ${{ inputs.post-update }}
         EXPO_RELEASE_UPDATE_EXTRA_ARGS: ${{ inputs.update-extra-args }}
+        EXPO_RELEASE_EXPORT_SOURCE_MAPS: ${{ inputs.export-source-maps }}
         EXPO_RELEASE_GROUP: ${{ inputs.group }}
         EXPO_RELEASE_RUNTIME_VERSION: ${{ inputs.runtime-version }}
         EXPO_RELEASE_MESSAGE: ${{ inputs.message }}

package/dist/args.d.ts

@@ -19,13 +19,14 @@ export type ReleaseOptions = {
     preUpdate?: string;
     postUpdate?: string;
     updateExtraArgs?: string;
+    exportSourceMaps: boolean;
     group?: string;
     runtimeVersion?: string;
     message?: string;
     fingerprint?: string;
     dryRun: boolean;
 };
-export declare const USAGE = "Usage: expo-release <release|decide|operate> --profile <profile> [--base <sha>] [--head <sha>] [--platform ios|android] [--impact-paths apps/expo/] [--operation deploy|force-native|retry-ota|republish|rollback-embedded] [--deploy-type none|ota|native] [--channel <channel>] [--environment <env>] [--group <id>] [--runtime-version <hash>] [--message <msg>] [--fingerprint <hash>] [--auto-submit true] [--pre-update <cmd>] [--post-update <cmd>] [--update-extra-args <args>] [--dry-run] [--ignore-expo-impact true]";
+export declare const USAGE = "Usage: expo-release <release|decide|operate> --profile <profile> [--base <sha>] [--head <sha>] [--platform ios|android] [--impact-paths apps/expo/] [--operation deploy|force-native|retry-ota|republish|rollback-embedded] [--deploy-type none|ota|native] [--channel <channel>] [--environment <env>] [--group <id>] [--runtime-version <hash>] [--message <msg>] [--fingerprint <hash>] [--auto-submit true] [--export-source-maps true] [--pre-update <cmd>] [--post-update <cmd>] [--update-extra-args <args>] [--dry-run] [--ignore-expo-impact true]";
 export declare function optionalString(value: string | undefined): string | undefined;
 export declare function parseImpactPaths(value: string | undefined): string[];
 export declare function parsePlatform(value: string | undefined): ReleasePlatform;

package/dist/cli.js

@@ -4,7 +4,7 @@
 // src/args.ts
 import { parseArgs } from "util";
 var DEFAULT_IMPACT_PATHS = ["apps/expo/"];
-var USAGE = "Usage: expo-release <release|decide|operate> --profile <profile> [--base <sha>] [--head <sha>] [--platform ios|android] [--impact-paths apps/expo/] [--operation deploy|force-native|retry-ota|republish|rollback-embedded] [--deploy-type none|ota|native] [--channel <channel>] [--environment <env>] [--group <id>] [--runtime-version <hash>] [--message <msg>] [--fingerprint <hash>] [--auto-submit true] [--pre-update <cmd>] [--post-update <cmd>] [--update-extra-args <args>] [--dry-run] [--ignore-expo-impact true]";
+var USAGE = "Usage: expo-release <release|decide|operate> --profile <profile> [--base <sha>] [--head <sha>] [--platform ios|android] [--impact-paths apps/expo/] [--operation deploy|force-native|retry-ota|republish|rollback-embedded] [--deploy-type none|ota|native] [--channel <channel>] [--environment <env>] [--group <id>] [--runtime-version <hash>] [--message <msg>] [--fingerprint <hash>] [--auto-submit true] [--export-source-maps true] [--pre-update <cmd>] [--post-update <cmd>] [--update-extra-args <args>] [--dry-run] [--ignore-expo-impact true]";
 function fromEnv(env, name) {
   const value = env[name]?.trim();
   return value ? value : undefined;
@@ -103,6 +103,7 @@ function parseReleaseOptions(args, env = process.env) {
         "pre-update": { type: "string" },
         "post-update": { type: "string" },
         "update-extra-args": { type: "string" },
+        "export-source-maps": { type: "string" },
         group: { type: "string" },
         "runtime-version": { type: "string" },
         message: { type: "string" },
@@ -147,6 +148,7 @@ ${message}`);
     preUpdate: optionalString(firstDefined(values["pre-update"], fromEnv(env, "EXPO_RELEASE_PRE_UPDATE"))),
     postUpdate: optionalString(firstDefined(values["post-update"], fromEnv(env, "EXPO_RELEASE_POST_UPDATE"))),
     updateExtraArgs: optionalString(firstDefined(values["update-extra-args"], fromEnv(env, "EXPO_RELEASE_UPDATE_EXTRA_ARGS"))),
+    exportSourceMaps: parseBoolean(firstDefined(values["export-source-maps"], fromEnv(env, "EXPO_RELEASE_EXPORT_SOURCE_MAPS")), false),
     group,
     runtimeVersion: optionalString(firstDefined(values["runtime-version"], fromEnv(env, "EXPO_RELEASE_RUNTIME_VERSION"))),
     message: optionalString(firstDefined(values.message, fromEnv(env, "EXPO_RELEASE_MESSAGE"))),
@@ -188,16 +190,44 @@ async function runCaptured(command) {
     child.exited
   ]);
   if (exitCode !== 0) {
-    throw new Error(`Command failed (${command.join(" ")}):
-${stderr || stdout}`);
+    throw new Error(describeFailure(command, exitCode, { stderr, stdout }));
   }
   return stdout;
 }
+var OUTPUT_TAIL_LINES = 100;
+function tail(output) {
+  const lines = output.trimEnd().split(`
+`);
+  if (lines.length <= OUTPUT_TAIL_LINES)
+    return lines.join(`
+`);
+  const omitted = lines.length - OUTPUT_TAIL_LINES;
+  return [
+    `... (${omitted} earlier lines omitted)`,
+    ...lines.slice(-OUTPUT_TAIL_LINES)
+  ].join(`
+`);
+}
+function describeFailure(command, exitCode, output) {
+  const sections = [
+    `Command failed with exit code ${exitCode}: ${quoteCommand(command)}`
+  ];
+  if (output.stderr.trim())
+    sections.push(`stderr:
+${tail(output.stderr)}`);
+  if (output.stdout.trim())
+    sections.push(`stdout:
+${tail(output.stdout)}`);
+  if (sections.length === 1)
+    sections.push("(no output)");
+  return sections.join(`
+`);
+}
 async function runInherited(command) {
   const child = Bun.spawn(command, { stdout: "inherit", stderr: "inherit" });
   const exitCode = await child.exited;
   if (exitCode !== 0) {
-    throw new Error(`Command failed (${command.join(" ")})`);
+    throw new Error(`Command failed with exit code ${exitCode}: ${quoteCommand(command)} (output above)`);
   }
   return "";
 }
@@ -394,6 +424,44 @@ async function writeDecideGitHubOutput(decision) {
   });
 }
 
+// src/source-maps.ts
+import { exists } from "fs/promises";
+var SOURCE_MAP_OUTPUT_DIR = "dist";
+function expoCommand(...args) {
+  const bin = process.env.EXPO_BIN?.trim();
+  if (bin && bin.length > 0)
+    return [bin, ...args];
+  return ["bunx", "expo", ...args];
+}
+function sourceMapExportCommand(platform) {
+  return expoCommand("export", "--platform", platform, "--output-dir", SOURCE_MAP_OUTPUT_DIR, "--source-maps", "external");
+}
+function mergeUpdateArgs(extra, exportSourceMaps) {
+  const args = extra ? [...extra] : [];
+  if (!exportSourceMaps)
+    return args;
+  if (!args.includes("--input-dir")) {
+    args.push("--input-dir", SOURCE_MAP_OUTPUT_DIR);
+  }
+  if (!args.includes("--skip-bundler")) {
+    args.push("--skip-bundler");
+  }
+  return args;
+}
+async function defaultHasSourceMaps(directory = SOURCE_MAP_OUTPUT_DIR) {
+  if (!await exists(directory))
+    return false;
+  for await (const _ of new Bun.Glob("**/*.map").scan(directory)) {
+    return true;
+  }
+  return false;
+}
+async function assertSourceMaps(hasSourceMaps = defaultHasSourceMaps) {
+  if (await hasSourceMaps())
+    return;
+  throw new Error("Expo export did not produce Hermes source maps in dist; refusing to publish an OTA update.");
+}
+
 // src/operate.ts
 function extraUpdateArgs(value) {
   return value?.split(/\s+/).filter(Boolean) ?? [];
@@ -451,12 +519,18 @@ function mutatingRunner(commandRunner, dryRun) {
 }
 async function publishUpdate(input, commandRunner) {
   await requireEnvironmentIfNeeded(input);
+  if (input.exportSourceMaps) {
+    await commandRunner(sourceMapExportCommand(input.platform));
+    if (input.dryRun !== true) {
+      await assertSourceMaps(input.hasSourceMaps);
+    }
+  }
   await runHook(input.preUpdate, commandRunner);
   const command = easCommand("update", "--channel", input.channel, "--platform", input.platform, "--message", updateMessage(input), "--non-interactive");
   if (input.environment) {
     command.push("--environment", input.environment);
   }
-  command.push(...extraUpdateArgs(input.updateExtraArgs));
+  command.push(...mergeUpdateArgs(extraUpdateArgs(input.updateExtraArgs), input.exportSourceMaps === true));
   await commandRunner(command);
   await runHook(input.postUpdate, commandRunner);
 }
@@ -550,12 +624,14 @@ function toOperationInput(options, decision) {
     preUpdate: options.preUpdate,
     postUpdate: options.postUpdate,
     updateExtraArgs: options.updateExtraArgs,
+    exportSourceMaps: options.exportSourceMaps,
     dryRun: options.dryRun
   };
 }
 async function main() {
   const raw = Bun.argv.slice(2);
-  if (raw.length === 0 || raw[0] === "--help" || raw[0] === "-h") {
+  const hasEnvCommand = Boolean(process.env.EXPO_RELEASE_COMMAND?.trim());
+  if (raw.length === 0 && !hasEnvCommand || raw[0] === "--help" || raw[0] === "-h") {
     process.stdout.write(`${USAGE}
 `);
     return;

package/dist/index.js

@@ -2,7 +2,7 @@
 // src/args.ts
 import { parseArgs } from "util";
 var DEFAULT_IMPACT_PATHS = ["apps/expo/"];
-var USAGE = "Usage: expo-release <release|decide|operate> --profile <profile> [--base <sha>] [--head <sha>] [--platform ios|android] [--impact-paths apps/expo/] [--operation deploy|force-native|retry-ota|republish|rollback-embedded] [--deploy-type none|ota|native] [--channel <channel>] [--environment <env>] [--group <id>] [--runtime-version <hash>] [--message <msg>] [--fingerprint <hash>] [--auto-submit true] [--pre-update <cmd>] [--post-update <cmd>] [--update-extra-args <args>] [--dry-run] [--ignore-expo-impact true]";
+var USAGE = "Usage: expo-release <release|decide|operate> --profile <profile> [--base <sha>] [--head <sha>] [--platform ios|android] [--impact-paths apps/expo/] [--operation deploy|force-native|retry-ota|republish|rollback-embedded] [--deploy-type none|ota|native] [--channel <channel>] [--environment <env>] [--group <id>] [--runtime-version <hash>] [--message <msg>] [--fingerprint <hash>] [--auto-submit true] [--export-source-maps true] [--pre-update <cmd>] [--post-update <cmd>] [--update-extra-args <args>] [--dry-run] [--ignore-expo-impact true]";
 function fromEnv(env, name) {
   const value = env[name]?.trim();
   return value ? value : undefined;
@@ -101,6 +101,7 @@ function parseReleaseOptions(args, env = process.env) {
         "pre-update": { type: "string" },
         "post-update": { type: "string" },
         "update-extra-args": { type: "string" },
+        "export-source-maps": { type: "string" },
         group: { type: "string" },
         "runtime-version": { type: "string" },
         message: { type: "string" },
@@ -145,6 +146,7 @@ ${message}`);
     preUpdate: optionalString(firstDefined(values["pre-update"], fromEnv(env, "EXPO_RELEASE_PRE_UPDATE"))),
     postUpdate: optionalString(firstDefined(values["post-update"], fromEnv(env, "EXPO_RELEASE_POST_UPDATE"))),
     updateExtraArgs: optionalString(firstDefined(values["update-extra-args"], fromEnv(env, "EXPO_RELEASE_UPDATE_EXTRA_ARGS"))),
+    exportSourceMaps: parseBoolean(firstDefined(values["export-source-maps"], fromEnv(env, "EXPO_RELEASE_EXPORT_SOURCE_MAPS")), false),
     group,
     runtimeVersion: optionalString(firstDefined(values["runtime-version"], fromEnv(env, "EXPO_RELEASE_RUNTIME_VERSION"))),
     message: optionalString(firstDefined(values.message, fromEnv(env, "EXPO_RELEASE_MESSAGE"))),
@@ -185,16 +187,44 @@ async function runCaptured(command) {
     child.exited
   ]);
   if (exitCode !== 0) {
-    throw new Error(`Command failed (${command.join(" ")}):
-${stderr || stdout}`);
+    throw new Error(describeFailure(command, exitCode, { stderr, stdout }));
   }
   return stdout;
 }
+var OUTPUT_TAIL_LINES = 100;
+function tail(output) {
+  const lines = output.trimEnd().split(`
+`);
+  if (lines.length <= OUTPUT_TAIL_LINES)
+    return lines.join(`
+`);
+  const omitted = lines.length - OUTPUT_TAIL_LINES;
+  return [
+    `... (${omitted} earlier lines omitted)`,
+    ...lines.slice(-OUTPUT_TAIL_LINES)
+  ].join(`
+`);
+}
+function describeFailure(command, exitCode, output) {
+  const sections = [
+    `Command failed with exit code ${exitCode}: ${quoteCommand(command)}`
+  ];
+  if (output.stderr.trim())
+    sections.push(`stderr:
+${tail(output.stderr)}`);
+  if (output.stdout.trim())
+    sections.push(`stdout:
+${tail(output.stdout)}`);
+  if (sections.length === 1)
+    sections.push("(no output)");
+  return sections.join(`
+`);
+}
 async function runInherited(command) {
   const child = Bun.spawn(command, { stdout: "inherit", stderr: "inherit" });
   const exitCode = await child.exited;
   if (exitCode !== 0) {
-    throw new Error(`Command failed (${command.join(" ")})`);
+    throw new Error(`Command failed with exit code ${exitCode}: ${quoteCommand(command)} (output above)`);
   }
   return "";
 }
@@ -390,6 +420,44 @@ async function writeDecideGitHubOutput(decision) {
     build_url: decision.build?.buildUrl ?? ""
   });
 }
+// src/source-maps.ts
+import { exists } from "fs/promises";
+var SOURCE_MAP_OUTPUT_DIR = "dist";
+function expoCommand(...args) {
+  const bin = process.env.EXPO_BIN?.trim();
+  if (bin && bin.length > 0)
+    return [bin, ...args];
+  return ["bunx", "expo", ...args];
+}
+function sourceMapExportCommand(platform) {
+  return expoCommand("export", "--platform", platform, "--output-dir", SOURCE_MAP_OUTPUT_DIR, "--source-maps", "external");
+}
+function mergeUpdateArgs(extra, exportSourceMaps) {
+  const args = extra ? [...extra] : [];
+  if (!exportSourceMaps)
+    return args;
+  if (!args.includes("--input-dir")) {
+    args.push("--input-dir", SOURCE_MAP_OUTPUT_DIR);
+  }
+  if (!args.includes("--skip-bundler")) {
+    args.push("--skip-bundler");
+  }
+  return args;
+}
+async function defaultHasSourceMaps(directory = SOURCE_MAP_OUTPUT_DIR) {
+  if (!await exists(directory))
+    return false;
+  for await (const _ of new Bun.Glob("**/*.map").scan(directory)) {
+    return true;
+  }
+  return false;
+}
+async function assertSourceMaps(hasSourceMaps = defaultHasSourceMaps) {
+  if (await hasSourceMaps())
+    return;
+  throw new Error("Expo export did not produce Hermes source maps in dist; refusing to publish an OTA update.");
+}
+
 // src/operate.ts
 function extraUpdateArgs(value) {
   return value?.split(/\s+/).filter(Boolean) ?? [];
@@ -447,12 +515,18 @@ function mutatingRunner(commandRunner, dryRun) {
 }
 async function publishUpdate(input, commandRunner) {
   await requireEnvironmentIfNeeded(input);
+  if (input.exportSourceMaps) {
+    await commandRunner(sourceMapExportCommand(input.platform));
+    if (input.dryRun !== true) {
+      await assertSourceMaps(input.hasSourceMaps);
+    }
+  }
   await runHook(input.preUpdate, commandRunner);
   const command = easCommand("update", "--channel", input.channel, "--platform", input.platform, "--message", updateMessage(input), "--non-interactive");
   if (input.environment) {
     command.push("--environment", input.environment);
   }
-  command.push(...extraUpdateArgs(input.updateExtraArgs));
+  command.push(...mergeUpdateArgs(extraUpdateArgs(input.updateExtraArgs), input.exportSourceMaps === true));
   await commandRunner(command);
   await runHook(input.postUpdate, commandRunner);
 }
@@ -519,7 +593,7 @@ async function writeOperateGitHubOutput(result) {
   await appendGitHubOutput({ result });
 }
 export {
-  operateRelease,
+  DEFAULT_IMPACT_PATHS,
   decideRelease,
-  DEFAULT_IMPACT_PATHS
+  operateRelease
 };