expo-release 2.0.0 → 2.2.1

package/src/cli.ts

@@ -1,16 +1,19 @@
 #!/usr/bin/env bun
 
+import { type CommandContext, defineCli, defineCommand } from 'hanzio/cli'
 import {
-	type ReleaseOptions,
-	USAGE,
+	type CommandName,
 	needsDecide,
-	parseReleaseOptions,
-	shouldIgnoreExpoImpact
+	type ReleaseFlags,
+	type ReleaseOptions,
+	releaseFlags,
+	shouldIgnoreExpoImpact,
+	toReleaseOptions
 } from './args'
 import {
 	type DecisionInput,
-	type ReleaseDecision,
 	decideRelease,
+	type ReleaseDecision,
 	writeDecideGitHubOutput
 } from './decide'
 import {
@@ -49,49 +52,83 @@ function toOperationInput(
 		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') {
-		process.stdout.write(`${USAGE}\n`)
-		return
-	}
+type Context = CommandContext<ReleaseFlags>
+
+async function decide(options: ReleaseOptions, ctx: Context) {
+	const decision = await decideRelease(toDecisionInput(options))
+	await writeDecideGitHubOutput(decision)
+	ctx.stdout.write(`${JSON.stringify(decision)}\n`)
+	return decision
+}
 
-	const options = parseReleaseOptions(raw)
+async function operate(
+	options: ReleaseOptions,
+	decision: ReleaseDecision | null,
+	ctx: Context
+) {
+	const result = await operateRelease(toOperationInput(options, decision))
+	await writeOperateGitHubOutput(result)
+	ctx.stdout.write(`${result}\n`)
+}
 
-	switch (options.command) {
-		case 'decide': {
-			const decision = await decideRelease(toDecisionInput(options))
-			await writeDecideGitHubOutput(decision)
-			process.stdout.write(`${JSON.stringify(decision)}\n`)
-			return
-		}
-		case 'operate': {
-			const result = await operateRelease(toOperationInput(options, null))
-			await writeOperateGitHubOutput(result)
-			process.stdout.write(`${result}\n`)
-			return
-		}
-		case 'release': {
-			let decision: ReleaseDecision | null = null
-			if (needsDecide(options.operation)) {
-				decision = await decideRelease(toDecisionInput(options))
-				await writeDecideGitHubOutput(decision)
-				process.stdout.write(`${JSON.stringify(decision)}\n`)
+const COMMANDS: CommandName[] = ['release', 'decide', 'operate']
+
+const cli = defineCli({
+	name: 'expo-release',
+	description:
+		'Fingerprint-driven Expo EAS release: OTA update or native store build',
+	// All three commands take the same flags, before or after the command name.
+	globals: releaseFlags,
+	context: (flags) => flags,
+	commands: {
+		release: defineCommand({
+			description: 'Run decide, then operate on its decision',
+			run: async (_input, ctx: Context) => {
+				const options = toReleaseOptions('release', ctx)
+				const decision = needsDecide(options.operation)
+					? await decide(options, ctx)
+					: null
+				await operate(options, decision, ctx)
+			}
+		}),
+		decide: defineCommand({
+			description:
+				'Print whether this change needs no deploy, an OTA update or a native build',
+			run: async (_input, ctx: Context) => {
+				await decide(toReleaseOptions('decide', ctx), ctx)
 			}
-			const result = await operateRelease(toOperationInput(options, decision))
-			await writeOperateGitHubOutput(result)
-			process.stdout.write(`${result}\n`)
-			return
-		}
-		default: {
-			const _exhaustive: never = options.command
-			throw new Error(`Unsupported command: ${_exhaustive}`)
-		}
+		}),
+		operate: defineCommand({
+			description: 'Run --operation for --deploy-type',
+			run: async (_input, ctx: Context) => {
+				await operate(toReleaseOptions('operate', ctx), null, ctx)
+			}
+		})
 	}
+})
+
+// GitHub Actions passes an unset input as an empty string; treat it as unset.
+const env = Object.fromEntries(
+	Object.entries(process.env).flatMap(([name, value]) =>
+		value?.trim() ? [[name, value.trim()]] : []
+	)
+)
+
+let argv = process.argv.slice(2)
+if (!argv.some((arg) => COMMANDS.includes(arg as CommandName))) {
+	// The composite action names the command in EXPO_RELEASE_COMMAND and passes no argv.
+	argv = env.EXPO_RELEASE_COMMAND
+		? [env.EXPO_RELEASE_COMMAND, ...argv]
+		: argv.length === 0
+			? ['--help']
+			: argv
 }
 
-await main()
+const code = await cli.run(argv, { env })
+// Bad arguments exit 1, as before hanzio/cli, which uses 2.
+process.exitCode = code === 2 ? 1 : code

package/src/operate.ts

@@ -7,6 +7,11 @@ import {
 	generateFingerprint,
 	runInherited
 } from './run'
+import {
+	assertSourceMaps,
+	mergeUpdateArgs,
+	sourceMapExportCommand
+} from './source-maps'
 
 export type { Operation }
 
@@ -25,8 +30,10 @@ export type OperationInput = {
 	preUpdate?: string
 	postUpdate?: string
 	updateExtraArgs?: string
+	exportSourceMaps?: boolean
 	dryRun?: boolean
 	readPackageJson?: () => Promise<unknown>
+	hasSourceMaps?: () => Promise<boolean>
 }
 
 export type OperationResult = 'skipped' | 'ota' | 'native-build' | 'recovery'
@@ -107,6 +114,12 @@ async function publishUpdate(
 	commandRunner: 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',
@@ -121,7 +134,12 @@ async function publishUpdate(
 	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)
 }

package/src/run.ts

@@ -16,18 +16,47 @@ export async function runCaptured(command: string[]): Promise<string> {
 		child.exited
 	])
 	if (exitCode !== 0) {
-		throw new Error(
-			`Command failed (${command.join(' ')}):\n${stderr || stdout}`
-		)
+		throw new Error(describeFailure(command, exitCode, { stderr, stdout }))
 	}
 	return stdout
 }
 
+const OUTPUT_TAIL_LINES = 100
+
+function tail(output: string): string {
+	const lines = output.trimEnd().split('\n')
+	if (lines.length <= OUTPUT_TAIL_LINES) return lines.join('\n')
+	const omitted = lines.length - OUTPUT_TAIL_LINES
+	return [
+		`... (${omitted} earlier lines omitted)`,
+		...lines.slice(-OUTPUT_TAIL_LINES)
+	].join('\n')
+}
+
+// Both streams are kept: EAS can print only an upgrade notice on stderr while
+// the real error lands on stdout (or the reverse). The command line holds no
+// secrets; tokens reach EAS through the environment, which is never printed.
+export function describeFailure(
+	command: string[],
+	exitCode: number,
+	output: { stderr: string; stdout: string }
+): string {
+	const sections = [
+		`Command failed with exit code ${exitCode}: ${quoteCommand(command)}`
+	]
+	if (output.stderr.trim()) sections.push(`stderr:\n${tail(output.stderr)}`)
+	if (output.stdout.trim()) sections.push(`stdout:\n${tail(output.stdout)}`)
+	if (sections.length === 1) sections.push('(no output)')
+	return sections.join('\n')
+}
+
 export async function runInherited(command: string[]): Promise<string> {
 	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 ''
 }

package/src/runtime/error-boundary.ts

@@ -0,0 +1,51 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react'
+
+export interface ErrorBoundaryFallbackProps {
+	error: Error
+	/** Clears the error and renders the children again. */
+	reset: () => void
+}
+
+export interface ErrorBoundaryProps {
+	children?: ReactNode
+	fallback: (props: ErrorBoundaryFallbackProps) => ReactNode
+	/**
+	 * Report the error here. Render errors never reach global handlers or
+	 * error-tracking autocapture, so capture them explicitly.
+	 */
+	onError?: (error: Error, info: ErrorInfo) => void
+}
+
+interface ErrorBoundaryState {
+	error: Error | null
+}
+
+const toError = (value: unknown) =>
+	value instanceof Error ? value : new Error(String(value))
+
+/** Error boundary without UI: `fallback` renders the error screen. */
+export class ErrorBoundary extends Component<
+	ErrorBoundaryProps,
+	ErrorBoundaryState
+> {
+	override state: ErrorBoundaryState = { error: null }
+
+	static getDerivedStateFromError(error: unknown): ErrorBoundaryState {
+		return { error: toError(error) }
+	}
+
+	override componentDidCatch(error: unknown, info: ErrorInfo) {
+		this.props.onError?.(toError(error), info)
+	}
+
+	reset = () => {
+		this.setState({ error: null })
+	}
+
+	override render() {
+		const { error } = this.state
+		return error
+			? this.props.fallback({ error, reset: this.reset })
+			: this.props.children
+	}
+}

package/src/runtime/index.ts

@@ -0,0 +1,19 @@
+export {
+	ErrorBoundary,
+	type ErrorBoundaryFallbackProps,
+	type ErrorBoundaryProps
+} from './error-boundary'
+export {
+	checkForOTAUpdate,
+	type ReloadApp,
+	type UseOTAUpdatesOptions,
+	useOTAUpdates
+} from './ota'
+export {
+	createPushNotifications,
+	type KeyValueStorage,
+	type NotificationListeners,
+	type PushNotifications,
+	type PushNotificationsOptions,
+	usePushNotifications
+} from './push'

package/src/runtime/ota.ts

@@ -0,0 +1,54 @@
+import * as Updates from 'expo-updates'
+import { useEffect, useRef } from 'react'
+
+declare const __DEV__: boolean | undefined
+
+/** Restarts the app on the downloaded update. */
+export type ReloadApp = () => Promise<void>
+
+/**
+ * Checks for an EAS update and downloads it. Calls `onUpdateReady` once a new
+ * update is on disk; show a "Restart" prompt there and call `reload` to apply.
+ * Returns whether a new update was downloaded.
+ */
+export async function checkForOTAUpdate(
+	onUpdateReady: (reload: ReloadApp) => void
+): Promise<boolean> {
+	const update = await Updates.checkForUpdateAsync()
+	if (!update.isAvailable) return false
+	const result = await Updates.fetchUpdateAsync()
+	if (!result.isNew) return false
+	onUpdateReady(() => Updates.reloadAsync())
+	return true
+}
+
+export interface UseOTAUpdatesOptions {
+	/** Defaults to off in development and wherever expo-updates is disabled (Expo Go). */
+	enabled?: boolean
+	/** A failed check is retried on the next launch; defaults to ignoring it. */
+	onError?: (error: unknown) => void
+}
+
+/**
+ * Checks for an update once per mount. The callbacks are read through refs, so
+ * an unstable toast function never re-runs the check or stacks prompts.
+ */
+export function useOTAUpdates(
+	onUpdateReady: (reload: ReloadApp) => void,
+	options: UseOTAUpdatesOptions = {}
+): void {
+	const {
+		enabled = Updates.isEnabled && !(typeof __DEV__ !== 'undefined' && __DEV__)
+	} = options
+	const callbacks = useRef({ onUpdateReady, onError: options.onError })
+	callbacks.current = { onUpdateReady, onError: options.onError }
+	const checked = useRef(false)
+
+	useEffect(() => {
+		if (!enabled || checked.current) return
+		checked.current = true
+		checkForOTAUpdate((reload) =>
+			callbacks.current.onUpdateReady(reload)
+		).catch((error: unknown) => callbacks.current.onError?.(error))
+	}, [enabled])
+}

package/src/runtime/push.ts

@@ -0,0 +1,243 @@
+import * as Device from 'expo-device'
+import * as Notifications from 'expo-notifications'
+import { useCallback, useEffect, useState } from 'react'
+
+/** Async key-value store. AsyncStorage and expo-secure-store adapters fit. */
+export interface KeyValueStorage {
+	getItem(key: string): Promise<string | null>
+	setItem(key: string, value: string): Promise<void>
+}
+
+export interface PushNotificationsOptions {
+	/** Remembers that the one-time prompt ran. */
+	storage: KeyValueStorage
+	/** Saves this device's Expo push token on your backend; `null` removes it. */
+	registerDevice: (token: string | null) => Promise<void>
+	/**
+	 * Explains push before the OS dialog. Resolve `true` to continue. Without
+	 * it, `prompt()` goes straight to the OS dialog.
+	 */
+	confirm?: () => Promise<boolean>
+	/** Push is off: the app runs on a simulator or the user denied permission. */
+	onUnavailable?: (reason: 'not-a-device' | 'denied') => void
+	onError?: (message: string, error: unknown) => void
+	/** Defaults to what expo-notifications reads from the app config. */
+	projectId?: string
+	/** Android channel `default`, needed for heads-up notifications. */
+	androidChannel?: Notifications.NotificationChannelInput
+	/** How notifications show while the app is in the foreground. */
+	foregroundBehavior?: Notifications.NotificationBehavior
+	storageKey?: string
+}
+
+export interface NotificationListeners {
+	onReceived?: (notification: Notifications.Notification) => void
+	/** Also called with the response that launched the app, if any. */
+	onResponse?: (response: Notifications.NotificationResponse) => void
+}
+
+export type PushNotifications = ReturnType<typeof createPushNotifications>
+
+/**
+ * expo-notifications behind one object: permission flow, Expo push token and
+ * device registration. Create it once at module level.
+ */
+export function createPushNotifications(options: PushNotificationsOptions) {
+	const {
+		storage,
+		registerDevice,
+		confirm,
+		onUnavailable,
+		onError = (message, error) => console.error(message, error),
+		projectId,
+		storageKey = '@notifications_permission_asked'
+	} = options
+
+	Notifications.setNotificationHandler({
+		handleNotification: async () =>
+			options.foregroundBehavior ?? {
+				shouldShowBanner: true,
+				shouldShowList: true,
+				shouldPlaySound: true,
+				shouldSetBadge: false
+			}
+	})
+	// Channels exist only on Android; elsewhere this resolves to null.
+	Notifications.setNotificationChannelAsync(
+		'default',
+		options.androidChannel ?? {
+			name: 'Default',
+			importance: Notifications.AndroidImportance.HIGH,
+			vibrationPattern: [0, 250, 250, 250]
+		}
+	).catch((error: unknown) =>
+		onError('Failed to create the notification channel', error)
+	)
+
+	let pendingPrompt: Promise<boolean> | null = null
+
+	const getPermissionStatus = () => Notifications.getPermissionsAsync()
+
+	async function hasPrompted() {
+		try {
+			return (await storage.getItem(storageKey)) === 'true'
+		} catch {
+			return false
+		}
+	}
+
+	/** Shows the OS dialog when it still can. Resolves whether push is allowed. */
+	async function requestPermissions() {
+		if (!Device.isDevice) {
+			onUnavailable?.('not-a-device')
+			return false
+		}
+		try {
+			const { granted } = await Notifications.requestPermissionsAsync()
+			if (!granted) onUnavailable?.('denied')
+			return granted
+		} catch (error) {
+			onError('Failed to request notification permissions', error)
+			return false
+		}
+	}
+
+	async function getPushToken() {
+		if (!Device.isDevice) return null
+		try {
+			const token = await Notifications.getExpoPushTokenAsync(
+				projectId ? { projectId } : undefined
+			)
+			return token.data
+		} catch (error) {
+			onError('Failed to get the Expo push token', error)
+			return null
+		}
+	}
+
+	/** Registers the current token. Resolves whether one was registered. */
+	async function syncToken() {
+		if (!(await getPermissionStatus()).granted) return false
+		const token = await getPushToken()
+		if (!token) return false
+		try {
+			await registerDevice(token)
+			return true
+		} catch (error) {
+			onError('Failed to register the push token', error)
+			return false
+		}
+	}
+
+	async function runPrompt() {
+		if (await hasPrompted()) return false
+		// Mark first so a crash or a second caller never shows the dialog twice.
+		try {
+			await storage.setItem(storageKey, 'true')
+		} catch (error) {
+			onError('Failed to remember the notification prompt', error)
+		}
+		if (confirm && !(await confirm())) return false
+		if (!(await requestPermissions())) return false
+		await syncToken()
+		return true
+	}
+
+	return {
+		getPermissionStatus,
+		hasPrompted,
+		requestPermissions,
+		getPushToken,
+		syncToken,
+
+		/**
+		 * Asks for push once per install (after sign-in, say), then registers the
+		 * token. Never throws; concurrent calls share one dialog.
+		 */
+		prompt(): Promise<boolean> {
+			pendingPrompt ??= runPrompt()
+				.catch((error: unknown) => {
+					onError('Failed to prompt for notifications', error)
+					return false
+				})
+				.finally(() => {
+					pendingPrompt = null
+				})
+			return pendingPrompt
+		},
+
+		/** Turns push on from settings. Resolves whether it is on. */
+		async enable() {
+			if (!(await requestPermissions())) return false
+			await syncToken()
+			return true
+		},
+
+		/** Removes this device's token from your backend. */
+		disable() {
+			return registerDevice(null)
+		},
+
+		/** Subscribes to notifications. Returns the unsubscribe function. */
+		listen({ onReceived, onResponse }: NotificationListeners) {
+			const subscriptions = [
+				onReceived && Notifications.addNotificationReceivedListener(onReceived),
+				onResponse &&
+					Notifications.addNotificationResponseReceivedListener(onResponse)
+			]
+			const launchResponse = onResponse
+				? Notifications.getLastNotificationResponse()
+				: null
+			if (launchResponse) onResponse?.(launchResponse)
+			return () => {
+				for (const subscription of subscriptions) subscription?.remove()
+			}
+		}
+	}
+}
+
+/**
+ * Push state for a settings screen. `enabled` is the user's saved preference;
+ * while it is on, the token is re-registered on mount.
+ */
+export function usePushNotifications(
+	push: PushNotifications,
+	{ enabled = false }: { enabled?: boolean } = {}
+) {
+	const [permission, setPermission] =
+		useState<Notifications.NotificationPermissionsStatus | null>(null)
+	const [isLoading, setIsLoading] = useState(false)
+
+	const refresh = useCallback(async () => {
+		setPermission(await push.getPermissionStatus())
+	}, [push])
+
+	useEffect(() => {
+		void refresh()
+		if (enabled) void push.syncToken()
+	}, [push, enabled, refresh])
+
+	const withLoading = useCallback(
+		<T>(action: () => Promise<T>) =>
+			async () => {
+				setIsLoading(true)
+				try {
+					return await action()
+				} finally {
+					await refresh()
+					setIsLoading(false)
+				}
+			},
+		[refresh]
+	)
+
+	return {
+		permission,
+		isEnabled: enabled && permission?.granted === true,
+		isLoading,
+		prompt: withLoading(push.prompt),
+		enable: withLoading(push.enable),
+		disable: withLoading(push.disable),
+		refresh
+	}
+}

package/src/source-maps.ts

@@ -0,0 +1,61 @@
+import { exists } from 'node:fs/promises'
+import type { ReleasePlatform } from './args'
+
+export const SOURCE_MAP_OUTPUT_DIR = 'dist'
+
+export function expoCommand(...args: string[]): string[] {
+	const bin = process.env.EXPO_BIN?.trim()
+	if (bin && bin.length > 0) return [bin, ...args]
+	return ['bunx', 'expo', ...args]
+}
+
+export function sourceMapExportCommand(platform: ReleasePlatform): string[] {
+	return expoCommand(
+		'export',
+		'--platform',
+		platform,
+		'--output-dir',
+		SOURCE_MAP_OUTPUT_DIR,
+		'--source-maps',
+		'external'
+	)
+}
+
+export function sourceMapUpdateArgs(): string[] {
+	return ['--input-dir', SOURCE_MAP_OUTPUT_DIR, '--skip-bundler']
+}
+
+export function mergeUpdateArgs(
+	extra: string[] | undefined,
+	exportSourceMaps: boolean
+): string[] {
+	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
+}
+
+export async function defaultHasSourceMaps(
+	directory = SOURCE_MAP_OUTPUT_DIR
+): Promise<boolean> {
+	if (!(await exists(directory))) return false
+
+	for await (const _ of new Bun.Glob('**/*.map').scan(directory)) {
+		return true
+	}
+	return false
+}
+
+export async function assertSourceMaps(
+	hasSourceMaps: () => Promise<boolean> = defaultHasSourceMaps
+) {
+	if (await hasSourceMaps()) return
+	throw new Error(
+		'Expo export did not produce Hermes source maps in dist; refusing to publish an OTA update.'
+	)
+}