@teardown/cli 2.0.71 → 2.0.72

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@teardown/cli",
-	"version": "2.0.71",
+	"version": "2.0.72",
 	"private": false,
 	"type": "module",
 	"main": "./src/index.ts",
@@ -76,7 +76,7 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.3.11",
-		"@teardown/tsconfig": "2.0.71",
+		"@teardown/tsconfig": "2.0.72",
 		"@types/bun": "1.3.5",
 		"@types/ejs": "^3.1.5",
 		"typescript": "5.9.3"

package/src/cli/commands/run.ts

@@ -1,8 +1,16 @@
 /**
  * Run command - runs the app on iOS or Android devices/simulators
+ *
+ * Flow:
+ * 1. Ensure native project exists (prebuild if needed)
+ * 2. Start Metro bundler in background
+ * 3. Wait for bundler to be ready
+ * 4. Build and install the app
+ * 5. Launch app via deep link with bundler URL
+ * 6. Attach Metro to foreground
  */
 
-import { exec, spawn } from "node:child_process";
+import { type ChildProcess, exec, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { createInterface } from "node:readline";
@@ -10,6 +18,8 @@ import { promisify } from "node:util";
 import chalk from "chalk";
 import { Command } from "commander";
 import ora from "ora";
+import { attachBundlerToForeground, startBundlerBackground, waitForBundlerReady } from "../../utils/bundler";
+import { getAppScheme, launchAppWithBundler } from "../../utils/deep-link";
 
 const execAsync = promisify(exec);
 
@@ -266,33 +276,6 @@ async function ensureNativeProject(platform: "ios" | "android"): Promise<boolean
 	return true;
 }
 
-/**
- * Start Metro bundler in foreground (runs after build completes)
- */
-function startBundlerInForeground(port: string): void {
-	console.log(chalk.blue(`\nStarting Metro bundler on port ${port} with --reset-cache...\n`));
-
-	const proc = spawn("npx", ["react-native", "start", "--port", port, "--reset-cache"], {
-		stdio: "inherit",
-		shell: true,
-		cwd: process.cwd(),
-		env: {
-			...process.env,
-			LANG: "en_US.UTF-8",
-		},
-	});
-
-	proc.on("close", (code) => {
-		if (code !== 0) {
-			console.error(chalk.red(`Metro bundler exited with code ${code}`));
-		}
-	});
-
-	proc.on("error", (err) => {
-		console.error(chalk.red(`Failed to start Metro bundler: ${err.message}`));
-	});
-}
-
 interface RunOptions {
 	device?: string;
 	picker: boolean;
@@ -331,6 +314,19 @@ export function createRunCommand(): Command {
 				process.exit(1);
 			}
 
+			// Track Metro process for cleanup
+			let metroProcess: ChildProcess | null = null;
+
+			// Handle SIGINT (Ctrl+C) to clean up Metro
+			const cleanup = () => {
+				if (metroProcess) {
+					metroProcess.kill("SIGTERM");
+				}
+				process.exit(0);
+			};
+			process.on("SIGINT", cleanup);
+			process.on("SIGTERM", cleanup);
+
 			try {
 				// Ensure native project exists (auto-prebuild if needed)
 				const hasProject = await ensureNativeProject(platform);
@@ -338,17 +334,29 @@ export function createRunCommand(): Command {
 					process.exit(1);
 				}
 
+				// Start Metro bundler FIRST (unless --no-bundler or --release)
+				if (options.bundler && !options.release) {
+					metroProcess = await startMetroAndWait(options.port, platform);
+				}
+
+				// Run platform-specific build and launch
 				if (platform === "ios") {
-					await runIOS(options);
+					await runIOS(options, metroProcess);
 				} else {
-					await runAndroid(options);
+					await runAndroid(options, metroProcess);
 				}
 
-				// Start bundler after build completes (unless --no-bundler or --release)
-				if (options.bundler && !options.release) {
-					startBundlerInForeground(options.port);
+				// If Metro is running, attach to foreground
+				if (metroProcess) {
+					console.log(chalk.blue("\n─".repeat(50)));
+					console.log(chalk.blue("Metro bundler running. Press Ctrl+C to stop.\n"));
+					attachBundlerToForeground(metroProcess);
 				}
 			} catch (error) {
+				// Clean up Metro on error
+				if (metroProcess) {
+					metroProcess.kill("SIGTERM");
+				}
 				console.error(chalk.red(`Failed to run app: ${error instanceof Error ? error.message : error}`));
 				process.exit(1);
 			}
@@ -357,10 +365,43 @@ export function createRunCommand(): Command {
 	return run;
 }
 
+/**
+ * Start Metro bundler in background and wait for it to be ready
+ */
+async function startMetroAndWait(port: string, _platform: "ios" | "android"): Promise<ChildProcess> {
+	// For local development, always use localhost for the bundler check
+	const checkUrl = `http://localhost:${port}`;
+
+	console.log(chalk.blue(`\nStarting Metro bundler on port ${port}...`));
+
+	const metroProcess = startBundlerBackground({
+		port,
+		resetCache: true,
+		cwd: process.cwd(),
+	});
+
+	// Wait for bundler to be ready with progress updates
+	const spinner = ora("Waiting for Metro bundler to start...").start();
+
+	const result = await waitForBundlerReady(checkUrl, 60000, (_attempt, elapsed) => {
+		const seconds = Math.floor(elapsed / 1000);
+		spinner.text = `Waiting for Metro bundler... (${seconds}s)`;
+	});
+
+	if (!result.ready) {
+		spinner.fail("Metro bundler failed to start");
+		metroProcess.kill("SIGTERM");
+		throw new Error(result.error || "Bundler timeout");
+	}
+
+	spinner.succeed(`Metro bundler ready at ${checkUrl}`);
+	return metroProcess;
+}
+
 /**
  * Run on iOS
  */
-async function runIOS(options: RunOptions): Promise<void> {
+async function runIOS(options: RunOptions, metroProcess: ChildProcess | null): Promise<void> {
 	const spinner = ora("Detecting iOS devices...").start();
 
 	try {
@@ -406,8 +447,8 @@ async function runIOS(options: RunOptions): Promise<void> {
 			bootSpinner.succeed(`${selectedDevice.name} is now running`);
 		}
 
-		// Run the app
-		console.log(chalk.blue("\nStarting app on iOS simulator...\n"));
+		// Build the app
+		console.log(chalk.blue("\nBuilding iOS app...\n"));
 
 		const args = [
 			"react-native",
@@ -439,6 +480,24 @@ async function runIOS(options: RunOptions): Promise<void> {
 		}
 
 		await runCommand("npx", args);
+
+		// If Metro is running, launch app via deep link to connect to bundler
+		if (metroProcess && !options.release) {
+			const scheme = getAppScheme(process.cwd());
+			if (scheme) {
+				const bundlerUrl = `http://localhost:${options.port}`;
+				console.log(chalk.blue("\nLaunching app with bundler connection..."));
+				try {
+					await launchAppWithBundler("ios", scheme, bundlerUrl, selectedDevice.udid);
+					console.log(chalk.green(`✓ App launched with bundler: ${bundlerUrl}`));
+				} catch (error) {
+					// Deep link launch failed, but app should still work
+					console.log(
+						chalk.yellow(`Note: Deep link launch skipped - ${error instanceof Error ? error.message : "unknown error"}`)
+					);
+				}
+			}
+		}
 	} catch (error) {
 		spinner.fail("Failed to detect iOS devices");
 		throw error;
@@ -448,7 +507,7 @@ async function runIOS(options: RunOptions): Promise<void> {
 /**
  * Run on Android
  */
-async function runAndroid(options: RunOptions): Promise<void> {
+async function runAndroid(options: RunOptions, metroProcess: ChildProcess | null): Promise<void> {
 	const spinner = ora("Detecting Android devices...").start();
 
 	try {
@@ -478,12 +537,16 @@ async function runAndroid(options: RunOptions): Promise<void> {
 					// Re-fetch devices
 					const newDevices = await getAndroidDevices();
 					if (newDevices.length > 0) {
-						await launchAndroidApp(newDevices[0], {
-							release: options.release,
-							port: options.port,
-							variant: options.variant,
-							clean: options.clean,
-						});
+						await launchAndroidApp(
+							newDevices[0],
+							{
+								release: options.release,
+								port: options.port,
+								variant: options.variant,
+								clean: options.clean,
+							},
+							metroProcess
+						);
 						return;
 					}
 				}
@@ -514,12 +577,16 @@ async function runAndroid(options: RunOptions): Promise<void> {
 			selectedDevice = await pickAndroidDevice(devices);
 		}
 
-		await launchAndroidApp(selectedDevice, {
-			release: options.release,
-			port: options.port,
-			variant: options.variant,
-			clean: options.clean,
-		});
+		await launchAndroidApp(
+			selectedDevice,
+			{
+				release: options.release,
+				port: options.port,
+				variant: options.variant,
+				clean: options.clean,
+			},
+			metroProcess
+		);
 	} catch (error) {
 		spinner.fail("Failed to detect Android devices");
 		throw error;
@@ -531,10 +598,11 @@ async function runAndroid(options: RunOptions): Promise<void> {
  */
 async function launchAndroidApp(
 	device: AndroidDevice,
-	options: { release?: boolean; port: string; variant?: string; clean?: boolean }
+	options: { release?: boolean; port: string; variant?: string; clean?: boolean },
+	metroProcess: ChildProcess | null
 ): Promise<void> {
 	console.log(chalk.blue(`\nSelected device: ${device.name} (${device.type})`));
-	console.log(chalk.blue("\nStarting app on Android...\n"));
+	console.log(chalk.blue("\nBuilding Android app...\n"));
 
 	// Handle clean build
 	if (options.clean) {
@@ -560,6 +628,26 @@ async function launchAndroidApp(
 	}
 
 	await runCommand("npx", args);
+
+	// If Metro is running, launch app via deep link to connect to bundler
+	if (metroProcess && !options.release) {
+		const scheme = getAppScheme(process.cwd());
+		if (scheme) {
+			// Android emulator uses 10.0.2.2 to reach host machine
+			const bundlerUrl =
+				device.type === "emulator" ? `http://10.0.2.2:${options.port}` : `http://localhost:${options.port}`;
+			console.log(chalk.blue("\nLaunching app with bundler connection..."));
+			try {
+				await launchAppWithBundler("android", scheme, bundlerUrl, device.id);
+				console.log(chalk.green(`✓ App launched with bundler: ${bundlerUrl}`));
+			} catch (error) {
+				// Deep link launch failed, but app should still work
+				console.log(
+					chalk.yellow(`Note: Deep link launch skipped - ${error instanceof Error ? error.message : "unknown error"}`)
+				);
+			}
+		}
+	}
 }
 
 /**

package/src/utils/bundler.ts

@@ -0,0 +1,263 @@
+/**
+ * Metro Bundler Utilities
+ *
+ * Provides functions for starting Metro bundler in background
+ * and checking when it's ready to serve bundles.
+ */
+
+import { type ChildProcess, spawn } from "node:child_process";
+import chalk from "chalk";
+
+/**
+ * Default Metro bundler port
+ */
+export const DEFAULT_BUNDLER_PORT = 8081;
+
+/**
+ * Default timeout for waiting for bundler to be ready (60 seconds)
+ */
+export const DEFAULT_BUNDLER_TIMEOUT = 60000;
+
+/**
+ * Polling interval for checking bundler status (1 second)
+ */
+const POLL_INTERVAL = 1000;
+
+/**
+ * Result of bundler ready check
+ */
+export interface BundlerReadyResult {
+	/** Whether bundler is ready */
+	ready: boolean;
+	/** Bundler URL if ready */
+	url?: string;
+	/** Error message if not ready */
+	error?: string;
+}
+
+/**
+ * Options for starting bundler in background
+ */
+export interface StartBundlerOptions {
+	/** Port to run Metro on */
+	port?: string | number;
+	/** Whether to reset Metro cache */
+	resetCache?: boolean;
+	/** Project root directory */
+	cwd?: string;
+	/** Whether to enable verbose logging */
+	verbose?: boolean;
+}
+
+/**
+ * Start Metro bundler in background
+ *
+ * Returns the child process so it can be managed (attached to foreground, killed, etc.)
+ *
+ * @param options - Bundler options
+ * @returns Child process running Metro
+ *
+ * @example
+ * ```ts
+ * const metro = startBundlerBackground({ port: 8081 });
+ *
+ * // Wait for bundler to be ready
+ * await waitForBundlerReady('http://localhost:8081');
+ *
+ * // Later, attach to foreground
+ * metro.stdout?.pipe(process.stdout);
+ * metro.stderr?.pipe(process.stderr);
+ * ```
+ */
+export function startBundlerBackground(options: StartBundlerOptions = {}): ChildProcess {
+	const { port = DEFAULT_BUNDLER_PORT, resetCache = false, cwd = process.cwd(), verbose = false } = options;
+
+	const args = ["react-native", "start", "--port", String(port)];
+
+	if (resetCache) {
+		args.push("--reset-cache");
+	}
+
+	if (verbose) {
+		args.push("--verbose");
+	}
+
+	const proc = spawn("npx", args, {
+		cwd,
+		shell: true,
+		stdio: ["ignore", "pipe", "pipe"],
+		detached: false,
+		env: {
+			...process.env,
+			LANG: "en_US.UTF-8",
+			// Force colors in Metro output
+			FORCE_COLOR: "1",
+		},
+	});
+
+	// Handle process errors
+	proc.on("error", (err) => {
+		console.error(chalk.red(`Failed to start Metro bundler: ${err.message}`));
+	});
+
+	return proc;
+}
+
+/**
+ * Check if Metro bundler is running and ready
+ *
+ * @param url - Bundler URL (e.g., http://localhost:8081)
+ * @returns Whether bundler is ready
+ */
+export async function isBundlerReady(url: string): Promise<boolean> {
+	try {
+		const statusUrl = `${url}/status`;
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), 5000);
+
+		const response = await fetch(statusUrl, {
+			method: "GET",
+			signal: controller.signal,
+		});
+
+		clearTimeout(timeout);
+
+		if (response.ok) {
+			const text = await response.text();
+			// Metro returns "packager-status:running" when ready
+			return text.includes("packager-status:running") || response.status === 200;
+		}
+
+		return false;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Wait for Metro bundler to be ready
+ *
+ * Polls the bundler status endpoint until it responds successfully
+ * or the timeout is reached.
+ *
+ * @param url - Bundler URL (e.g., http://localhost:8081)
+ * @param timeoutMs - Maximum time to wait in milliseconds
+ * @param onProgress - Optional callback for progress updates
+ * @returns Result indicating if bundler is ready
+ *
+ * @example
+ * ```ts
+ * const result = await waitForBundlerReady('http://localhost:8081', 60000, (attempt) => {
+ *   console.log(`Attempt ${attempt}...`);
+ * });
+ *
+ * if (result.ready) {
+ *   console.log('Bundler ready at', result.url);
+ * } else {
+ *   console.error('Failed:', result.error);
+ * }
+ * ```
+ */
+export async function waitForBundlerReady(
+	url: string,
+	timeoutMs: number = DEFAULT_BUNDLER_TIMEOUT,
+	onProgress?: (attempt: number, elapsed: number) => void
+): Promise<BundlerReadyResult> {
+	const startTime = Date.now();
+	let attempt = 0;
+
+	while (Date.now() - startTime < timeoutMs) {
+		attempt++;
+		const elapsed = Date.now() - startTime;
+
+		if (onProgress) {
+			onProgress(attempt, elapsed);
+		}
+
+		const ready = await isBundlerReady(url);
+		if (ready) {
+			return {
+				ready: true,
+				url,
+			};
+		}
+
+		// Wait before next attempt
+		await sleep(POLL_INTERVAL);
+	}
+
+	return {
+		ready: false,
+		error: `Bundler did not become ready within ${timeoutMs / 1000} seconds`,
+	};
+}
+
+/**
+ * Get bundler URL for a given port and platform
+ *
+ * @param port - Metro port
+ * @param platform - Target platform
+ * @returns Bundler URL
+ */
+export function getBundlerUrl(port: string | number, platform: "ios" | "android" = "ios"): string {
+	// Android emulator needs 10.0.2.2 to reach host machine
+	const host = platform === "android" ? "10.0.2.2" : "localhost";
+	return `http://${host}:${port}`;
+}
+
+/**
+ * Kill a bundler process gracefully
+ *
+ * @param proc - Child process to kill
+ * @param timeoutMs - Time to wait before force killing
+ */
+export async function killBundler(proc: ChildProcess, timeoutMs = 5000): Promise<void> {
+	return new Promise((resolve) => {
+		if (!proc.pid) {
+			resolve();
+			return;
+		}
+
+		let killed = false;
+
+		proc.on("exit", () => {
+			killed = true;
+			resolve();
+		});
+
+		// Try graceful shutdown first
+		proc.kill("SIGTERM");
+
+		// Force kill after timeout
+		setTimeout(() => {
+			if (!killed) {
+				proc.kill("SIGKILL");
+				resolve();
+			}
+		}, timeoutMs);
+	});
+}
+
+/**
+ * Attach bundler process to foreground (pipe stdout/stderr)
+ *
+ * @param proc - Metro process
+ */
+export function attachBundlerToForeground(proc: ChildProcess): void {
+	proc.stdout?.pipe(process.stdout);
+	proc.stderr?.pipe(process.stderr);
+
+	// Handle process exit
+	proc.on("close", (code) => {
+		if (code !== 0 && code !== null) {
+			console.error(chalk.red(`Metro bundler exited with code ${code}`));
+		}
+	});
+}
+
+/**
+ * Sleep for a given duration
+ */
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/utils/deep-link.ts

@@ -0,0 +1,248 @@
+/**
+ * Deep Link Utilities
+ *
+ * Provides functions for reading app scheme from config,
+ * building deep link URLs, and launching apps via deep links.
+ */
+
+import { exec } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { promisify } from "node:util";
+import chalk from "chalk";
+
+const execAsync = promisify(exec);
+
+/**
+ * Config file names to search for (in order of priority)
+ */
+const CONFIG_FILE_NAMES = [
+	"teardown.config.ts",
+	"teardown.config.js",
+	"teardown.config.mjs",
+	"app.config.ts",
+	"app.config.js",
+];
+
+/**
+ * Deep link parameters for dev mode
+ */
+export interface DevDeepLinkParams {
+	/** Metro bundler URL */
+	bundler: string;
+}
+
+/**
+ * Read the app scheme from the Teardown/Expo config file
+ *
+ * @param projectRoot - Project root directory
+ * @returns App scheme or null if not found
+ *
+ * @example
+ * ```ts
+ * const scheme = getAppScheme('/path/to/project');
+ * console.log(scheme); // 'myapp'
+ * ```
+ */
+export function getAppScheme(projectRoot: string): string | null {
+	for (const fileName of CONFIG_FILE_NAMES) {
+		const configPath = resolve(projectRoot, fileName);
+		if (existsSync(configPath)) {
+			try {
+				const content = readFileSync(configPath, "utf-8");
+				// Extract scheme using regex - handles both single and double quotes
+				const schemeMatch = content.match(/scheme:\s*['"]([^'"]+)['"]/);
+				if (schemeMatch) {
+					return schemeMatch[1];
+				}
+			} catch {
+				// Ignore read errors and try next config file
+			}
+		}
+	}
+
+	// Try to read from slug as fallback (slug is used as default scheme)
+	for (const fileName of CONFIG_FILE_NAMES) {
+		const configPath = resolve(projectRoot, fileName);
+		if (existsSync(configPath)) {
+			try {
+				const content = readFileSync(configPath, "utf-8");
+				const slugMatch = content.match(/slug:\s*['"]([^'"]+)['"]/);
+				if (slugMatch) {
+					return slugMatch[1];
+				}
+			} catch {
+				// Ignore read errors
+			}
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Build a development deep link URL with bundler information
+ *
+ * @param scheme - App scheme (e.g., 'myapp')
+ * @param bundlerUrl - Metro bundler URL (e.g., 'http://localhost:8081')
+ * @returns Deep link URL
+ *
+ * @example
+ * ```ts
+ * const link = buildDevDeepLink('myapp', 'http://localhost:8081');
+ * // Returns: 'myapp://dev?bundler=http%3A%2F%2Flocalhost%3A8081'
+ * ```
+ */
+export function buildDevDeepLink(scheme: string, bundlerUrl: string): string {
+	const encodedUrl = encodeURIComponent(bundlerUrl);
+	return `${scheme}://dev?bundler=${encodedUrl}`;
+}
+
+/**
+ * Parse bundler URL from a deep link
+ *
+ * @param url - Deep link URL
+ * @returns Bundler URL or null if not found
+ *
+ * @example
+ * ```ts
+ * const bundlerUrl = parseBundlerFromDeepLink('myapp://dev?bundler=http%3A%2F%2Flocalhost%3A8081');
+ * // Returns: 'http://localhost:8081'
+ * ```
+ */
+export function parseBundlerFromDeepLink(url: string): string | null {
+	try {
+		// Handle custom scheme URLs by replacing scheme with http for URL parsing
+		const normalizedUrl = url.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "http://");
+		const parsed = new URL(normalizedUrl);
+		const bundler = parsed.searchParams.get("bundler");
+		return bundler ? decodeURIComponent(bundler) : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Open a deep link URL on iOS Simulator
+ *
+ * @param udid - Simulator UDID
+ * @param url - Deep link URL to open
+ *
+ * @example
+ * ```ts
+ * await openDeepLinkIOS('XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', 'myapp://dev?bundler=...');
+ * ```
+ */
+export async function openDeepLinkIOS(udid: string, url: string): Promise<void> {
+	// Escape URL for shell
+	const escapedUrl = url.replace(/"/g, '\\"');
+	const command = `xcrun simctl openurl ${udid} "${escapedUrl}"`;
+
+	try {
+		await execAsync(command);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to open deep link on iOS simulator: ${message}`);
+	}
+}
+
+/**
+ * Open a deep link URL on Android device/emulator
+ *
+ * @param deviceId - Android device ID (optional, uses default if not provided)
+ * @param url - Deep link URL to open
+ *
+ * @example
+ * ```ts
+ * await openDeepLinkAndroid('emulator-5554', 'myapp://dev?bundler=...');
+ * ```
+ */
+export async function openDeepLinkAndroid(deviceId: string | undefined, url: string): Promise<void> {
+	// Escape URL for shell
+	const escapedUrl = url.replace(/"/g, '\\"');
+
+	// Build adb command
+	let command = "adb";
+	if (deviceId) {
+		command += ` -s ${deviceId}`;
+	}
+	command += ` shell am start -a android.intent.action.VIEW -d "${escapedUrl}"`;
+
+	try {
+		await execAsync(command);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to open deep link on Android: ${message}`);
+	}
+}
+
+/**
+ * Launch app via deep link with bundler URL
+ *
+ * This is a convenience function that builds the deep link and opens it
+ * on the appropriate platform.
+ *
+ * @param platform - Target platform
+ * @param scheme - App scheme
+ * @param bundlerUrl - Metro bundler URL
+ * @param deviceId - Device identifier (UDID for iOS, device ID for Android)
+ *
+ * @example
+ * ```ts
+ * await launchAppWithBundler('ios', 'myapp', 'http://localhost:8081', 'XXXX-UDID-XXXX');
+ * ```
+ */
+export async function launchAppWithBundler(
+	platform: "ios" | "android",
+	scheme: string,
+	bundlerUrl: string,
+	deviceId: string
+): Promise<void> {
+	const deepLink = buildDevDeepLink(scheme, bundlerUrl);
+
+	console.log(chalk.gray(`  Opening: ${deepLink}`));
+
+	if (platform === "ios") {
+		await openDeepLinkIOS(deviceId, deepLink);
+	} else {
+		await openDeepLinkAndroid(deviceId, deepLink);
+	}
+}
+
+/**
+ * Check if an app with the given scheme is installed on iOS Simulator
+ *
+ * @param udid - Simulator UDID
+ * @param bundleId - App bundle identifier
+ * @returns Whether the app is installed
+ */
+export async function isAppInstalledIOS(udid: string, bundleId: string): Promise<boolean> {
+	try {
+		const { stdout } = await execAsync(`xcrun simctl get_app_container ${udid} ${bundleId}`);
+		return stdout.trim().length > 0;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Check if an app with the given package is installed on Android
+ *
+ * @param deviceId - Android device ID
+ * @param packageName - App package name
+ * @returns Whether the app is installed
+ */
+export async function isAppInstalledAndroid(deviceId: string | undefined, packageName: string): Promise<boolean> {
+	try {
+		let command = "adb";
+		if (deviceId) {
+			command += ` -s ${deviceId}`;
+		}
+		command += ` shell pm list packages ${packageName}`;
+
+		const { stdout } = await execAsync(command);
+		return stdout.includes(`package:${packageName}`);
+	} catch {
+		return false;
+	}
+}

package/src/utils/index.ts

@@ -2,6 +2,28 @@
  * Utility functions for Teardown Launchpad
  */
 
+export type { BundlerReadyResult, StartBundlerOptions } from "./bundler";
+export {
+	attachBundlerToForeground,
+	DEFAULT_BUNDLER_PORT,
+	DEFAULT_BUNDLER_TIMEOUT,
+	getBundlerUrl,
+	isBundlerReady,
+	killBundler,
+	startBundlerBackground,
+	waitForBundlerReady,
+} from "./bundler";
+export type { DevDeepLinkParams } from "./deep-link";
+export {
+	buildDevDeepLink,
+	getAppScheme,
+	isAppInstalledAndroid,
+	isAppInstalledIOS,
+	launchAppWithBundler,
+	openDeepLinkAndroid,
+	openDeepLinkIOS,
+	parseBundlerFromDeepLink,
+} from "./deep-link";
 export type { VirtualFileSystem } from "./fs";
 export {
 	copyDirectory,
@@ -19,3 +41,5 @@ export {
 	formatKeyValue,
 	formatList,
 } from "./logger";
+export type { ReporterStep, StepStatus, TerminalReporterConfig } from "./terminal-reporter";
+export { createReporter, TerminalReporter } from "./terminal-reporter";

package/src/utils/terminal-reporter.ts

@@ -0,0 +1,299 @@
+/**
+ * Terminal Reporter
+ *
+ * Unified step-by-step progress reporter for CLI commands.
+ * Provides a consistent UX for multi-step operations like build and run.
+ */
+
+import chalk from "chalk";
+import ora, { type Ora } from "ora";
+
+/**
+ * Status of a reporter step
+ */
+export type StepStatus = "pending" | "running" | "success" | "error" | "skipped";
+
+/**
+ * A step in the reporter
+ */
+export interface ReporterStep {
+	/** Unique step identifier */
+	id: string;
+	/** Display label for the step */
+	label: string;
+	/** Current status */
+	status: StepStatus;
+	/** Optional detail message */
+	detail?: string;
+	/** Error message if failed */
+	error?: string;
+	/** Start time (for duration tracking) */
+	startTime?: number;
+	/** End time */
+	endTime?: number;
+}
+
+/**
+ * Terminal reporter configuration
+ */
+export interface TerminalReporterConfig {
+	/** Whether to show elapsed time for each step */
+	showDuration?: boolean;
+	/** Whether to use colors */
+	colors?: boolean;
+	/** Whether to show step numbers */
+	showNumbers?: boolean;
+}
+
+/**
+ * Status icons for different step states
+ */
+const STATUS_ICONS: Record<StepStatus, string> = {
+	pending: chalk.gray("○"),
+	running: chalk.blue("◐"),
+	success: chalk.green("✓"),
+	error: chalk.red("✗"),
+	skipped: chalk.yellow("⊘"),
+};
+
+/**
+ * Format duration in human-readable format
+ */
+function formatDuration(ms: number): string {
+	if (ms < 1000) {
+		return `${ms}ms`;
+	}
+	if (ms < 60000) {
+		return `${(ms / 1000).toFixed(1)}s`;
+	}
+	const minutes = Math.floor(ms / 60000);
+	const seconds = Math.floor((ms % 60000) / 1000);
+	return `${minutes}m ${seconds}s`;
+}
+
+/**
+ * Terminal Reporter class
+ *
+ * Manages multi-step operations with visual feedback.
+ *
+ * @example
+ * ```ts
+ * const reporter = new TerminalReporter();
+ *
+ * reporter.addStep('prebuild', 'Ensure native project');
+ * reporter.addStep('metro', 'Start Metro bundler');
+ * reporter.addStep('build', 'Build iOS app');
+ *
+ * reporter.startStep('prebuild');
+ * await ensureNativeProject('ios');
+ * reporter.completeStep('prebuild');
+ *
+ * reporter.startStep('metro');
+ * reporter.updateStepDetail('metro', 'Starting on port 8081...');
+ * await startMetro();
+ * reporter.completeStep('metro', 'http://localhost:8081');
+ * ```
+ */
+export class TerminalReporter {
+	private steps: Map<string, ReporterStep> = new Map();
+	private stepOrder: string[] = [];
+	private spinner: Ora | null = null;
+	private config: Required<TerminalReporterConfig>;
+
+	constructor(config: TerminalReporterConfig = {}) {
+		this.config = {
+			showDuration: config.showDuration ?? true,
+			colors: config.colors ?? true,
+			showNumbers: config.showNumbers ?? true,
+		};
+	}
+
+	/**
+	 * Add a new step to the reporter
+	 */
+	addStep(id: string, label: string): void {
+		if (this.steps.has(id)) {
+			throw new Error(`Step with id "${id}" already exists`);
+		}
+
+		this.steps.set(id, {
+			id,
+			label,
+			status: "pending",
+		});
+		this.stepOrder.push(id);
+	}
+
+	/**
+	 * Start a step (mark as running)
+	 */
+	startStep(id: string): void {
+		const step = this.getStep(id);
+		step.status = "running";
+		step.startTime = Date.now();
+
+		// Stop any existing spinner
+		this.stopSpinner();
+
+		// Start new spinner
+		const stepNumber = this.config.showNumbers ? `[${this.getStepNumber(id)}/${this.stepOrder.length}] ` : "";
+		this.spinner = ora({
+			text: `${stepNumber}${step.label}`,
+			prefixText: "",
+		}).start();
+	}
+
+	/**
+	 * Complete a step successfully
+	 */
+	completeStep(id: string, detail?: string): void {
+		const step = this.getStep(id);
+		step.status = "success";
+		step.endTime = Date.now();
+		step.detail = detail;
+
+		this.stopSpinner();
+		this.printStepResult(step);
+	}
+
+	/**
+	 * Mark a step as failed
+	 */
+	failStep(id: string, error: string): void {
+		const step = this.getStep(id);
+		step.status = "error";
+		step.endTime = Date.now();
+		step.error = error;
+
+		this.stopSpinner();
+		this.printStepResult(step);
+	}
+
+	/**
+	 * Skip a step
+	 */
+	skipStep(id: string, reason?: string): void {
+		const step = this.getStep(id);
+		step.status = "skipped";
+		step.detail = reason;
+
+		this.stopSpinner();
+		this.printStepResult(step);
+	}
+
+	/**
+	 * Update the detail message for a running step
+	 */
+	updateStepDetail(id: string, detail: string): void {
+		const step = this.getStep(id);
+		step.detail = detail;
+
+		if (this.spinner && step.status === "running") {
+			const stepNumber = this.config.showNumbers ? `[${this.getStepNumber(id)}/${this.stepOrder.length}] ` : "";
+			this.spinner.text = `${stepNumber}${step.label} - ${chalk.gray(detail)}`;
+		}
+	}
+
+	/**
+	 * Get current status of a step
+	 */
+	getStepStatus(id: string): StepStatus {
+		return this.getStep(id).status;
+	}
+
+	/**
+	 * Check if all steps completed successfully
+	 */
+	allSucceeded(): boolean {
+		return Array.from(this.steps.values()).every((step) => step.status === "success" || step.status === "skipped");
+	}
+
+	/**
+	 * Print a summary of all steps
+	 */
+	printSummary(): void {
+		console.log();
+		console.log(chalk.bold("Summary:"));
+		console.log(chalk.gray("─".repeat(50)));
+
+		for (const id of this.stepOrder) {
+			const step = this.steps.get(id);
+			if (step) {
+				this.printStepResult(step, true);
+			}
+		}
+
+		console.log(chalk.gray("─".repeat(50)));
+
+		const succeeded = Array.from(this.steps.values()).filter((s) => s.status === "success").length;
+		const failed = Array.from(this.steps.values()).filter((s) => s.status === "error").length;
+		const skipped = Array.from(this.steps.values()).filter((s) => s.status === "skipped").length;
+
+		if (failed > 0) {
+			console.log(chalk.red(`✗ ${failed} failed`), chalk.gray(`| ${succeeded} succeeded | ${skipped} skipped`));
+		} else {
+			console.log(
+				chalk.green(`✓ All ${succeeded} steps completed`),
+				skipped > 0 ? chalk.gray(`(${skipped} skipped)`) : ""
+			);
+		}
+	}
+
+	/**
+	 * Clean up (stop spinner if running)
+	 */
+	cleanup(): void {
+		this.stopSpinner();
+	}
+
+	private getStep(id: string): ReporterStep {
+		const step = this.steps.get(id);
+		if (!step) {
+			throw new Error(`Step with id "${id}" not found`);
+		}
+		return step;
+	}
+
+	private getStepNumber(id: string): number {
+		return this.stepOrder.indexOf(id) + 1;
+	}
+
+	private stopSpinner(): void {
+		if (this.spinner) {
+			this.spinner.stop();
+			this.spinner = null;
+		}
+	}
+
+	private printStepResult(step: ReporterStep, isSummary = false): void {
+		const icon = STATUS_ICONS[step.status];
+		const stepNumber = this.config.showNumbers ? `[${this.getStepNumber(step.id)}/${this.stepOrder.length}] ` : "";
+
+		let line = `${icon} ${stepNumber}${step.label}`;
+
+		// Add duration if available
+		if (this.config.showDuration && step.startTime && step.endTime) {
+			const duration = step.endTime - step.startTime;
+			line += chalk.gray(` (${formatDuration(duration)})`);
+		}
+
+		// Add detail if present
+		if (step.detail) {
+			line += chalk.gray(` - ${step.detail}`);
+		}
+
+		console.log(line);
+
+		// Print error on separate line if failed and not in summary
+		if (step.status === "error" && step.error && !isSummary) {
+			console.log(chalk.red(`  └─ ${step.error}`));
+		}
+	}
+}
+
+/**
+ * Create a simple reporter for quick use
+ */
+export function createReporter(config?: TerminalReporterConfig): TerminalReporter {
+	return new TerminalReporter(config);
+}