expo-release 2.0.0 → 2.2.1

package/README.md

@@ -17,15 +17,70 @@ 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
 ```
 
-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.
+The action installs its own dependencies (`hanzio`, `zod`) in `${{ github.action_path }}`, then 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.
 
@@ -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,215 @@ 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"]
 ```
 
+Run `expo-release <command> --help` for every flag. Each flag also reads `EXPO_RELEASE_<FLAG>` (for example `EXPO_RELEASE_IMPACT_PATHS`) when it is not passed; an empty value counts as unset.
+
 `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
@@ -103,6 +107,12 @@ outputs:
 runs:
   using: composite
   steps:
+    # The CLI imports hanzio and zod; the action checkout has no node_modules.
+    - name: Install expo-release dependencies
+      working-directory: ${{ github.action_path }}
+      shell: bash
+      run: bun install --production --frozen-lockfile --omit peer
+
     - name: Expo release
       id: release
       working-directory: ${{ inputs.working-directory }}
@@ -123,6 +133,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

@@ -1,3 +1,5 @@
+import type { CommandContext } from 'hanzio/cli';
+import { z } from 'zod';
 export declare const DEFAULT_IMPACT_PATHS: readonly ['apps/expo/'];
 export type ReleasePlatform = 'ios' | 'android';
 export type CommandName = 'release' | 'decide' | 'operate';
@@ -19,20 +21,58 @@ 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 function optionalString(value: string | undefined): string | undefined;
-export declare function parseImpactPaths(value: string | undefined): string[];
-export declare function parsePlatform(value: string | undefined): ReleasePlatform;
-export declare function parseBoolean(value: string | undefined, fallback: boolean): boolean;
-export declare function parseOperation(value: string | undefined): Operation;
-export declare function parseDeployType(value: string | undefined): DeployType;
-export declare function parseCommandName(value: string | undefined): CommandName;
+export declare const releaseFlags: z.ZodObject<{
+    profile: z.ZodString;
+    base: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
+    head: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
+    platform: z.ZodDefault<z.ZodEnum<{
+        android: "android";
+        ios: "ios";
+    }>>;
+    impactPaths: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string[], string>>;
+    ignoreExpoImpact: z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+        false: "false";
+        true: "true";
+    }>>, z.ZodTransform<boolean, "false" | "true">>;
+    operation: z.ZodDefault<z.ZodEnum<{
+        deploy: "deploy";
+        "force-native": "force-native";
+        republish: "republish";
+        "retry-ota": "retry-ota";
+        "rollback-embedded": "rollback-embedded";
+    }>>;
+    deployType: z.ZodDefault<z.ZodEnum<{
+        native: "native";
+        none: "none";
+        ota: "ota";
+    }>>;
+    channel: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
+    environment: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
+    autoSubmit: z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+        false: "false";
+        true: "true";
+    }>>, z.ZodTransform<boolean, "false" | "true">>;
+    preUpdate: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
+    postUpdate: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
+    updateExtraArgs: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
+    exportSourceMaps: z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+        false: "false";
+        true: "true";
+    }>>, z.ZodTransform<boolean, "false" | "true">>;
+    group: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
+    runtimeVersion: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
+    message: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
+    fingerprint: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
+    dryRun: z.ZodBoolean;
+}, z.core.$strip>;
+export type ReleaseFlags = z.output<typeof releaseFlags>;
+export declare function toReleaseOptions(command: CommandName, { context: flags, env }: CommandContext<ReleaseFlags>): ReleaseOptions;
 export declare function needsDecide(operation: Operation): boolean;
 export declare function shouldIgnoreExpoImpact(options: Pick<ReleaseOptions, 'ignoreExpoImpact' | 'operation'>): boolean;
-export declare function parseReleaseOptions(args: string[], env?: NodeJS.ProcessEnv): ReleaseOptions;