Epic: Add iOS Project Support to iloom

[acreeger]

Summary

Extend iloom's project capability system to detect and manage iOS projects — React Native, Expo, and native Xcode/SwiftUI — with support for both simulator and physical device deployment. This brings iOS projects to feature parity with iloom's existing web and CLI project support.

Context

iloom currently supports two project capabilities: 'cli' (projects with bin entries) and 'web' (projects with web framework dependencies like Next.js, Vite, Express). Each capability drives behavior across the tool — from framework detection during il init, to dev server management, to command routing in il open, il run, and il dev-server.

iOS projects need the same treatment: detect the project type, manage the development lifecycle (simulator, device, Metro bundler), and route commands appropriately.

Scope

In scope:

• Add 'ios' as a new ProjectCapability
• Detect iOS projects (React Native, Expo, native Xcode/SwiftUI)
• iOS Simulator management (boot, install, launch, track per worktree)
• Physical device deployment (xcodebuild with device destination, code signing)
• React Native Metro bundler as a dev server strategy (port-based, fits existing pattern)
• Native iOS build-and-launch utilities (does NOT fit DevServerStrategy — separate pattern)
• Command routing for iOS in il open, il run, il dev-server
• Framework detector agent update for iOS project initialization
• macOS-only platform guard (iOS development requires macOS)
• iOS-specific settings (simulator device, Xcode scheme, bundle ID, deploy target, development team for code signing)

Out of scope:

• Android support (separate future epic)
• Remote build services (e.g., EAS Build, Bitrise)
• App Store distribution
• CI/CD pipeline integration for iOS

Assumptions

1. macOS is required for iOS development — feature will gracefully skip on other platforms
2. React Native and Expo are the primary frameworks (TypeScript ecosystem), but native Xcode projects are also supported
3. Physical device deployment requires a valid Apple Developer account and provisioning profile — iloom surfaces errors from xcodebuild, it does not manage signing itself
4. For React Native, Metro bundler is the "dev server" (port-based, reuses existing DevServerStrategy pattern). For native iOS, a build-and-launch lifecycle replaces the dev server concept.

Key Architectural Decisions

1. React Native uses DevServerStrategy; native iOS does not. Metro bundler is a long-running port-bound process — it fits DevServerStrategy. Native Xcode projects use a build-and-launch cycle — they get standalone utilities, not a strategy.
2. Simulator UDID tracking per worktree. Each worktree tracks its assigned simulator to enable re-attachment and clean teardown.
3. Port 8081 override for React Native. Metro defaults to 8081; iloom overrides this with its standard basePort + issueNumber assignment to avoid conflicts across worktrees.
4. Code signing is passthrough. iloom passes developmentTeam to xcodebuild but does not manage certificates or profiles directly.

[acreeger]

Architectural Decision Record

Key Design Decisions

1. React Native uses DevServerStrategy; native iOS does not.
Metro bundler is a long-running, port-bound Node.js process — it naturally fits the existing DevServerStrategy interface (start, stop, isRunning on a port). Native Xcode projects (SwiftUI, UIKit) follow a build-and-launch lifecycle with no persistent server. Forcing native iOS into DevServerStrategy would require an awkward adapter that misuses the port concept. Instead, native iOS gets standalone build/simulator/device utilities invoked directly by commands.

2. Single wave, maximum parallelism.
All 6 implementation issues run in parallel with shared contracts. The ProjectCapability = 'ios' type and iOS settings schema are defined as contracts that all issues implement against. Compilation errors from cross-references resolve when branches merge into the epic branch. A single verification issue gates the integration.

3. Simulator UDID tracking per worktree.
Each worktree's metadata tracks its assigned simulator UDID. This prevents il run from booting a new simulator every invocation and enables clean teardown during il cleanup. The UDID is written when the simulator is first booted for a worktree and cleared on cleanup.

4. Port 8081 override for React Native.
Metro bundler defaults to port 8081, which conflicts when multiple worktrees run simultaneously. The Metro strategy overrides this with iloom's standard basePort + issueNumber scheme. The --port flag is passed to Metro, and the React Native app must be configured to connect to the overridden port (typically via RCT_METRO_PORT environment variable or .env injection).

5. Code signing is passthrough, not managed.
iloom passes developmentTeam from settings to xcodebuild's DEVELOPMENT_TEAM build setting. It does not manage certificates, provisioning profiles, or keychain access. When signing fails, xcodebuild's error output is surfaced directly to the user. This keeps iloom's scope focused and avoids security-sensitive credential management.

6. macOS platform guard.
All iOS functionality is gated behind a process.platform === 'darwin' check. On non-macOS platforms, iOS markers are ignored during detection (no 'ios' capability produced), and direct invocation of iOS utilities throws a clear error. This prevents confusing failures on Linux CI or WSL.

Trade-offs Considered

Decision	Alternative	Why chosen
Separate Metro strategy vs single iOS strategy	One iOSDevServerStrategy handling both Metro and native	Metro fits the port-based interface; native doesn't. Forcing both into one strategy creates a leaky abstraction.
Standalone utilities vs AppLifecycleStrategy interface	New AppLifecycleStrategy interface for native iOS	YAGNI — a new interface adds complexity for a single consumer (native iOS). Standalone utilities are simpler and can be promoted to an interface later if Android support needs the same pattern.
Single wave vs multi-wave DAG	Wave 1: types → Wave 2: detection + strategies → Wave 3: commands	Shared contracts enable full parallelism. The multi-wave approach would serialize unnecessarily, reducing swarm throughput by ~3x.

Recommended Execution Order

All implementation issues (#967-#972) execute in parallel. Verification (#973) runs after all complete.

[acreeger]

Child Issues Created

Issue	Title	Dependencies
#967	Add iOS capability type and settings schema	None
#968	Add iOS project detection to ProjectCapabilityDetector	None
#969	Create React Native Metro bundler dev server strategy	None
#970	Create iOS build, simulator, and device deployment utilities	None
#971	Update open, run, and dev-server commands for iOS capability	None
#972	Update framework detector agent for iOS projects	None
#973	Verify iOS support integration	#967, #968, #969, #970, #971, #972

Dependency Graph

graph TD
    967["#967 iOS capability types & settings"]
    968["#968 iOS project detection"]
    969["#969 React Native Metro strategy"]
    970["#970 iOS build/simulator/device utils"]
    971["#971 Command routing for iOS"]
    972["#972 Framework detector for iOS"]
    973["#973 Verify iOS integration"]
    967 --> 973
    968 --> 973
    969 --> 973
    970 --> 973
    971 --> 973
    972 --> 973
    click 967 "https://github.com/iloom-ai/iloom-cli/issues/967"
    click 968 "https://github.com/iloom-ai/iloom-cli/issues/968"
    click 969 "https://github.com/iloom-ai/iloom-cli/issues/969"
    click 970 "https://github.com/iloom-ai/iloom-cli/issues/970"
    click 971 "https://github.com/iloom-ai/iloom-cli/issues/971"
    click 972 "https://github.com/iloom-ai/iloom-cli/issues/972"
    click 973 "https://github.com/iloom-ai/iloom-cli/issues/973"

Loading

Wave Execution Plan

Wave 1 (all parallel): #967, #968, #969, #970, #971, #972
Verification: #973 (after all Wave 1 issues complete)

[acreeger]

Swarm Completion Status

Epic: #966

Issue	Status
#967 — Add iOS capability type and settings schema	Done
#968 — Add iOS project detection to ProjectCapabilityDetector	Done
#969 — Create React Native Metro bundler dev server strategy	Done
#970 — Create iOS build, simulator, and device deployment utilities	Done
#971 — Update open, run, and dev-server commands for iOS capability	Done
#972 — Update framework detector agent for iOS projects	Done
#973 — Verify iOS support integration	Done

Results: 7 succeeded, 0 failed out of 7 total children.

Post-swarm review: 1 critical finding fixed (capabilities dropped in getPackageConfig merge), 1 warning fixed (unified macOS assertion). 3 non-blocking warnings noted.

Full implementation report will be generated at il finish time.