expo-release 2.0.0

package/src/args.ts

@@ -0,0 +1,318 @@
+import { parseArgs } from 'node:util'
+
+export const DEFAULT_IMPACT_PATHS = ['apps/expo/'] as const
+
+export type ReleasePlatform = 'ios' | 'android'
+
+export type CommandName = 'release' | 'decide' | 'operate'
+
+export type Operation =
+	| 'deploy'
+	| 'force-native'
+	| 'retry-ota'
+	| 'republish'
+	| 'rollback-embedded'
+
+export type DeployType = 'none' | 'ota' | 'native'
+
+export type ReleaseOptions = {
+	command: CommandName
+	profile: string
+	base?: string
+	head?: string
+	platform: ReleasePlatform
+	impactPaths: string[]
+	ignoreExpoImpact: boolean
+	operation: Operation
+	deployType: DeployType
+	channel: string
+	environment?: string
+	autoSubmit: boolean
+	preUpdate?: string
+	postUpdate?: string
+	updateExtraArgs?: string
+	group?: string
+	runtimeVersion?: string
+	message?: string
+	fingerprint?: string
+	dryRun: boolean
+}
+
+export 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]'
+
+function fromEnv(env: NodeJS.ProcessEnv, name: string): string | undefined {
+	const value = env[name]?.trim()
+	return value ? value : undefined
+}
+
+function firstDefined(
+	...values: Array<string | undefined>
+): string | undefined {
+	return values.find((value) => value !== undefined && value.length > 0)
+}
+
+export function optionalString(value: string | undefined): string | undefined {
+	const trimmed = value?.trim()
+	return trimmed ? trimmed : undefined
+}
+
+export function parseImpactPaths(value: string | undefined): string[] {
+	const paths = (value ?? DEFAULT_IMPACT_PATHS.join(','))
+		.split(',')
+		.map((path) => path.trim())
+		.filter(Boolean)
+	if (paths.length === 0) {
+		throw new Error('At least one --impact-paths entry is required')
+	}
+	return paths
+}
+
+export function parsePlatform(value: string | undefined): ReleasePlatform {
+	if (value === undefined || value === 'ios') return 'ios'
+	if (value === 'android') return 'android'
+	throw new Error('Usage: --platform ios|android')
+}
+
+export function parseBoolean(value: string | undefined, fallback: boolean) {
+	if (value === undefined) return fallback
+	if (value === 'true') return true
+	if (value === 'false') return false
+	throw new Error(`Expected true or false, received: ${value}`)
+}
+
+export function parseOperation(value: string | undefined): Operation {
+	if (
+		value === undefined ||
+		value === 'deploy' ||
+		value === 'force-native' ||
+		value === 'retry-ota' ||
+		value === 'republish' ||
+		value === 'rollback-embedded'
+	) {
+		return value ?? 'deploy'
+	}
+	throw new Error(
+		'Usage: --operation deploy|force-native|retry-ota|republish|rollback-embedded'
+	)
+}
+
+export function parseDeployType(value: string | undefined): DeployType {
+	if (value === undefined || value === 'none') return 'none'
+	if (value === 'ota' || value === 'native') return value
+	throw new Error('Usage: --deploy-type none|ota|native')
+}
+
+export function parseCommandName(value: string | undefined): CommandName {
+	if (value === 'release' || value === 'decide' || value === 'operate') {
+		return value
+	}
+	throw new Error(USAGE)
+}
+
+export function needsDecide(operation: Operation): boolean {
+	switch (operation) {
+		case 'deploy':
+		case 'retry-ota':
+			return true
+		case 'force-native':
+		case 'republish':
+		case 'rollback-embedded':
+			return false
+		default: {
+			const _exhaustive: never = operation
+			throw new Error(`Unsupported operation: ${_exhaustive}`)
+		}
+	}
+}
+
+export function shouldIgnoreExpoImpact(
+	options: Pick<ReleaseOptions, 'ignoreExpoImpact' | 'operation'>
+): boolean {
+	if (options.ignoreExpoImpact) return true
+	if (options.operation === 'retry-ota') return true
+	return (
+		process.env.GITHUB_EVENT_NAME === 'workflow_dispatch' &&
+		options.operation === 'deploy'
+	)
+}
+
+export function parseReleaseOptions(
+	args: string[],
+	env: NodeJS.ProcessEnv = process.env
+): ReleaseOptions {
+	let values: {
+		profile?: string
+		base?: string
+		head?: string
+		platform?: string
+		'impact-paths'?: string
+		'ignore-expo-impact'?: string
+		operation?: string
+		'deploy-type'?: string
+		channel?: string
+		environment?: string
+		'auto-submit'?: string
+		'pre-update'?: string
+		'post-update'?: string
+		'update-extra-args'?: string
+		group?: string
+		'runtime-version'?: string
+		message?: string
+		fingerprint?: string
+		'dry-run'?: boolean
+	}
+	let positionals: string[]
+
+	try {
+		const parsed = parseArgs({
+			args,
+			allowPositionals: true,
+			strict: true,
+			options: {
+				profile: { type: 'string' },
+				base: { type: 'string' },
+				head: { type: 'string' },
+				platform: { type: 'string' },
+				'impact-paths': { type: 'string' },
+				'ignore-expo-impact': { type: 'string' },
+				operation: { type: 'string' },
+				'deploy-type': { type: 'string' },
+				channel: { type: 'string' },
+				environment: { type: 'string' },
+				'auto-submit': { type: 'string' },
+				'pre-update': { type: 'string' },
+				'post-update': { type: 'string' },
+				'update-extra-args': { type: 'string' },
+				group: { type: 'string' },
+				'runtime-version': { type: 'string' },
+				message: { type: 'string' },
+				fingerprint: { type: 'string' },
+				'dry-run': { type: 'boolean', default: false }
+			}
+		})
+		values = parsed.values
+		positionals = parsed.positionals
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error)
+		throw new Error(`${USAGE}\n${message}`)
+	}
+
+	if (positionals.length > 1) {
+		throw new Error(USAGE)
+	}
+
+	const command = parseCommandName(
+		positionals[0] ?? fromEnv(env, 'EXPO_RELEASE_COMMAND')
+	)
+	const profile = firstDefined(
+		values.profile,
+		fromEnv(env, 'EXPO_RELEASE_PROFILE')
+	)
+	if (!profile) {
+		throw new Error(USAGE)
+	}
+
+	const operation = parseOperation(
+		firstDefined(values.operation, fromEnv(env, 'EXPO_RELEASE_OPERATION'))
+	)
+	const group = optionalString(
+		firstDefined(values.group, fromEnv(env, 'EXPO_RELEASE_GROUP'))
+	)
+	if (operation === 'republish' && !group) {
+		throw new Error(
+			'Usage: --operation republish requires --group <update-group-id>'
+		)
+	}
+
+	const channel =
+		firstDefined(values.channel, fromEnv(env, 'EXPO_RELEASE_CHANNEL')) ??
+		profile
+
+	return {
+		command,
+		profile,
+		base: optionalString(
+			firstDefined(
+				values.base,
+				fromEnv(env, 'EXPO_RELEASE_BASE'),
+				fromEnv(env, 'GITHUB_EVENT_BEFORE')
+			)
+		),
+		head: optionalString(
+			firstDefined(
+				values.head,
+				fromEnv(env, 'EXPO_RELEASE_HEAD'),
+				fromEnv(env, 'GITHUB_SHA')
+			)
+		),
+		platform: parsePlatform(
+			firstDefined(values.platform, fromEnv(env, 'EXPO_RELEASE_PLATFORM'))
+		),
+		impactPaths: parseImpactPaths(
+			firstDefined(
+				values['impact-paths'],
+				fromEnv(env, 'EXPO_RELEASE_IMPACT_PATHS')
+			)
+		),
+		ignoreExpoImpact: parseBoolean(
+			firstDefined(
+				values['ignore-expo-impact'],
+				fromEnv(env, 'EXPO_RELEASE_IGNORE_EXPO_IMPACT')
+			),
+			false
+		),
+		operation,
+		deployType: parseDeployType(
+			firstDefined(
+				values['deploy-type'],
+				fromEnv(env, 'EXPO_RELEASE_DEPLOY_TYPE')
+			)
+		),
+		channel,
+		environment: optionalString(
+			firstDefined(values.environment, fromEnv(env, 'EXPO_RELEASE_ENVIRONMENT'))
+		),
+		autoSubmit: parseBoolean(
+			firstDefined(
+				values['auto-submit'],
+				fromEnv(env, 'EXPO_RELEASE_AUTO_SUBMIT')
+			),
+			true
+		),
+		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')
+			)
+		),
+		group,
+		runtimeVersion: optionalString(
+			firstDefined(
+				values['runtime-version'],
+				fromEnv(env, 'EXPO_RELEASE_RUNTIME_VERSION')
+			)
+		),
+		message: optionalString(
+			firstDefined(values.message, fromEnv(env, 'EXPO_RELEASE_MESSAGE'))
+		),
+		fingerprint: optionalString(
+			firstDefined(values.fingerprint, fromEnv(env, 'EXPO_RELEASE_FINGERPRINT'))
+		),
+		dryRun:
+			values['dry-run'] === true ||
+			parseBoolean(fromEnv(env, 'EXPO_RELEASE_DRY_RUN'), false)
+	}
+}

package/src/cli.ts

@@ -0,0 +1,97 @@
+#!/usr/bin/env bun
+
+import {
+	type ReleaseOptions,
+	USAGE,
+	needsDecide,
+	parseReleaseOptions,
+	shouldIgnoreExpoImpact
+} from './args'
+import {
+	type DecisionInput,
+	type ReleaseDecision,
+	decideRelease,
+	writeDecideGitHubOutput
+} from './decide'
+import {
+	type OperationInput,
+	operateRelease,
+	writeOperateGitHubOutput
+} from './operate'
+
+function toDecisionInput(options: ReleaseOptions): DecisionInput {
+	return {
+		base: options.base,
+		head: options.head,
+		profile: options.profile,
+		platform: options.platform,
+		impactPaths: options.impactPaths,
+		ignoreExpoImpact: shouldIgnoreExpoImpact(options)
+	}
+}
+
+function toOperationInput(
+	options: ReleaseOptions,
+	decision: ReleaseDecision | null
+): OperationInput {
+	return {
+		profile: options.profile,
+		deployType: decision?.deployType ?? options.deployType,
+		operation: options.operation,
+		channel: options.channel,
+		environment: options.environment,
+		platform: options.platform,
+		autoSubmit: options.autoSubmit,
+		fingerprint: options.fingerprint ?? decision?.fingerprint ?? undefined,
+		group: options.group,
+		runtimeVersion: options.runtimeVersion,
+		message: options.message,
+		preUpdate: options.preUpdate,
+		postUpdate: options.postUpdate,
+		updateExtraArgs: options.updateExtraArgs,
+		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
+	}
+
+	const options = parseReleaseOptions(raw)
+
+	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 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}`)
+		}
+	}
+}
+
+await main()

package/src/decide.ts

@@ -0,0 +1,293 @@
+import {
+	DEFAULT_IMPACT_PATHS,
+	type DeployType,
+	type ReleasePlatform
+} from './args'
+import { appendGitHubOutput } from './github-output'
+import {
+	type CommandRunner,
+	easCommand,
+	getRecord,
+	generateFingerprint,
+	parseJson,
+	runCaptured
+} from './run'
+
+export type EASBuildStatus =
+	| 'finished'
+	| 'in-progress'
+	| 'new'
+	| 'in-queue'
+	| 'pending-cancel'
+	| 'errored'
+	| 'canceled'
+
+export type EASBuild = {
+	id: string
+	status: EASBuildStatus
+	buildUrl?: string
+	fingerprint?: string
+	runtimeVersion?: string
+}
+
+export type ReleaseDecision = {
+	deployType: DeployType
+	nativeBuildPending: boolean
+	changedFiles: string[]
+	fingerprint: string | null
+	build: EASBuild | null
+}
+
+export type DecisionInput = {
+	base?: string
+	head?: string
+	profile: string
+	platform: ReleasePlatform
+	impactPaths: string[]
+	ignoreExpoImpact?: boolean
+}
+
+const ACTIVE_BUILD_STATUSES: readonly EASBuildStatus[] = [
+	'in-progress',
+	'new',
+	'in-queue',
+	'pending-cancel'
+]
+
+const KNOWN_BUILD_STATUSES = new Set<string>([
+	'finished',
+	'in-progress',
+	'new',
+	'in-queue',
+	'pending-cancel',
+	'errored',
+	'canceled'
+])
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function nestedString(
+	record: Record<string, unknown>,
+	...path: string[]
+): string | undefined {
+	let current: unknown = record
+	for (const key of path) {
+		if (!isRecord(current)) return undefined
+		current = current[key]
+	}
+	return typeof current === 'string' && current.length > 0 ? current : undefined
+}
+
+function normalizeBuildStatus(value: string): EASBuildStatus | null {
+	const status = value.toLowerCase().replaceAll('_', '-')
+	if (KNOWN_BUILD_STATUSES.has(status)) {
+		return status as EASBuildStatus
+	}
+	return null
+}
+
+function dashboardBuildUrl(
+	record: Record<string, unknown>
+): string | undefined {
+	const ownerName = nestedString(record, 'app', 'ownerAccount', 'name')
+	const slug = nestedString(record, 'app', 'slug')
+	if (typeof record.id !== 'string' || !ownerName || !slug) {
+		return undefined
+	}
+	return `https://expo.dev/accounts/${ownerName}/projects/${slug}/builds/${record.id}`
+}
+
+export function parseBuildList(output: string): EASBuild[] {
+	const parsed = parseJson(output)
+	if (!Array.isArray(parsed)) {
+		throw new Error('EAS build:list did not return an array')
+	}
+
+	const builds: EASBuild[] = []
+	for (const value of parsed) {
+		const record = getRecord(value, 'EAS build')
+		if (typeof record.id !== 'string' || typeof record.status !== 'string') {
+			throw new Error('EAS build must include string id and status fields')
+		}
+
+		const status = normalizeBuildStatus(record.status)
+		if (!status) {
+			process.stderr.write(
+				`Warning: ignoring EAS build ${record.id} with unsupported status ${record.status}\n`
+			)
+			continue
+		}
+
+		const buildUrl = dashboardBuildUrl(record)
+		const fingerprint = nestedString(record, 'fingerprint', 'hash')
+		const runtimeVersion = nestedString(record, 'runtime', 'version')
+
+		builds.push({
+			id: record.id,
+			status,
+			...(buildUrl ? { buildUrl } : {}),
+			...(fingerprint ? { fingerprint } : {}),
+			...(runtimeVersion ? { runtimeVersion } : {})
+		})
+	}
+
+	return builds
+}
+
+export function isExpoImpactPath(
+	path: string,
+	impactPaths: readonly string[] = DEFAULT_IMPACT_PATHS
+): boolean {
+	return impactPaths.some((impactPath) => {
+		const prefix = impactPath.endsWith('/')
+			? impactPath.slice(0, -1)
+			: impactPath
+		return (
+			path === prefix || path === impactPath || path.startsWith(`${prefix}/`)
+		)
+	})
+}
+
+export function hasExpoImpact(
+	paths: string[],
+	impactPaths: readonly string[] = DEFAULT_IMPACT_PATHS
+): boolean {
+	return paths.some((path) => isExpoImpactPath(path, impactPaths))
+}
+
+export function resolveBuildDecision(builds: EASBuild[]): {
+	deployType: Exclude<DeployType, 'none'>
+	nativeBuildPending: boolean
+	build: EASBuild | null
+} {
+	const finished = builds.find((build) => build.status === 'finished')
+	if (finished) {
+		return { deployType: 'ota', nativeBuildPending: false, build: finished }
+	}
+
+	const inProgress = builds.find((build) =>
+		ACTIVE_BUILD_STATUSES.includes(build.status)
+	)
+	if (inProgress) {
+		return {
+			deployType: 'ota',
+			nativeBuildPending: true,
+			build: inProgress
+		}
+	}
+
+	const newest = builds[0]
+	if (newest?.status === 'errored') {
+		const location = newest.buildUrl ?? newest.id
+		throw new Error(
+			`The most recent native build for this fingerprint failed (${location}). Fix the failure or use --operation force-native to queue another build.`
+		)
+	}
+
+	return { deployType: 'native', nativeBuildPending: false, build: null }
+}
+
+async function getChangedFiles(
+	input: DecisionInput,
+	commandRunner: CommandRunner
+): Promise<{ files: string[]; unreachable: boolean }> {
+	const head = input.head
+	if (!input.base || !head || /^0+$/.test(input.base)) {
+		return { files: [], unreachable: true }
+	}
+
+	try {
+		const output = await commandRunner([
+			'git',
+			'-c',
+			'diff.relative=false',
+			'diff',
+			'--name-only',
+			input.base,
+			head
+		])
+		return {
+			files: output
+				.split('\n')
+				.map((path) => path.trim())
+				.filter(Boolean),
+			unreachable: false
+		}
+	} catch {
+		return { files: [], unreachable: true }
+	}
+}
+
+async function getMatchingBuilds(
+	input: DecisionInput,
+	fingerprint: string,
+	commandRunner: CommandRunner
+): Promise<EASBuild[]> {
+	return parseBuildList(
+		await commandRunner(
+			easCommand(
+				'build:list',
+				'--platform',
+				input.platform,
+				'--build-profile',
+				input.profile,
+				'--fingerprint-hash',
+				fingerprint,
+				'--limit',
+				'20',
+				'--json',
+				'--non-interactive'
+			)
+		)
+	)
+}
+
+export async function decideRelease(
+	input: DecisionInput,
+	commandRunner: CommandRunner = runCaptured
+): Promise<ReleaseDecision> {
+	const { files: changedFiles, unreachable } = await getChangedFiles(
+		input,
+		commandRunner
+	)
+
+	if (
+		!input.ignoreExpoImpact &&
+		!unreachable &&
+		!hasExpoImpact(changedFiles, input.impactPaths)
+	) {
+		return {
+			deployType: 'none',
+			nativeBuildPending: false,
+			changedFiles,
+			fingerprint: null,
+			build: null
+		}
+	}
+
+	const fingerprint = await generateFingerprint(input, commandRunner)
+	const resolved = resolveBuildDecision(
+		await getMatchingBuilds(input, fingerprint, commandRunner)
+	)
+
+	return {
+		deployType: resolved.deployType,
+		nativeBuildPending: resolved.nativeBuildPending,
+		changedFiles,
+		fingerprint,
+		build: resolved.build
+	}
+}
+
+export async function writeDecideGitHubOutput(decision: ReleaseDecision) {
+	await appendGitHubOutput({
+		deploy_type: decision.deployType,
+		native_build_pending: String(decision.nativeBuildPending),
+		changed: String(decision.deployType !== 'none'),
+		fingerprint: decision.fingerprint ?? '',
+		build_id: decision.build?.id ?? '',
+		build_url: decision.build?.buildUrl ?? ''
+	})
+}

package/src/github-output.ts

@@ -0,0 +1,12 @@
+import { appendFile } from 'node:fs/promises'
+
+export async function appendGitHubOutput(entries: Record<string, string>) {
+	const outputPath = process.env.GITHUB_OUTPUT
+	if (!outputPath) return
+
+	const lines = Object.entries(entries).map(([key, value]) => {
+		const delimiter = `EOF_${key}_${crypto.randomUUID().replaceAll('-', '')}`
+		return `${key}<<${delimiter}\n${value}\n${delimiter}`
+	})
+	await appendFile(outputPath, `${lines.join('\n')}\n`)
+}