Skip to content

Epic: Add iOS Project Support to iloom#974

Draft
acreeger wants to merge 9 commits intomainfrom
feat/issue-966__add-ios-project-support
Draft

Epic: Add iOS Project Support to iloom#974
acreeger wants to merge 9 commits intomainfrom
feat/issue-966__add-ios-project-support

Conversation

@acreeger
Copy link
Copy Markdown
Collaborator

Fixes #966

Epic: Add iOS Project Support to iloom

Issue details

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.

This PR was created automatically by iloom.

- Add iOS/mobile markers to Step 1 scan table (Podfile, xcodeproj, react-native, expo)
- Add *.xcworkspace and *.xcodeproj/project.pbxproj to Glob pattern
- Add iOS detection logic in Step 2 for React Native, Expo, native Xcode, and dual web+ios
- Document ios capability alongside cli and web in Step 4
- Add 5 new JSON examples: RN (ios), RN (ios+web), Expo, Xcode+CocoaPods, Xcode+SPM
- Use correct CLI commands (npx react-native run-ios, npx expo run:ios)
- Add package manager detection from lockfiles for React Native projects
- Conditional pod install only when ios/ directory is present
- Derive xcodebuild scheme from .xcodeproj directory name
- Split Native Xcode into CocoaPods and SPM-only variants
@acreeger acreeger force-pushed the feat/issue-966__add-ios-project-support branch from b5e2736 to 629476a Compare March 27, 2026 14:39
- Add 'ios' to ProjectCapability type union
- Add hasIosDependencies() utility checking react-native and expo
- Add detectIosCapability() with macOS-only platform guard
- Add hasIosFilesystemMarkers() scanning .xcodeproj/.xcworkspace in root
  and ios/ subdirectory, Podfile, ios/Podfile, app.json (Expo keys only),
  and app.config.js
- Add readdirSafe() that re-throws non-ENOENT/ENOTDIR errors
- iOS detection runs even when package.json is missing (native Xcode projects)
- Hybrid projects can have both 'web' and 'ios' capabilities
- Add 16 new tests covering all detection paths and platform guard
…ndler

- New MetroDevServerStrategy implementing DevServerStrategy for npx react-native start
- Uses --port flag to override Metro default 8081 with iloom assigned port
- startBackground: detached process, crash detection, zombie cleanup on timeout
- startForeground: inherited/stderr-redirect/piped stdio modes
- stop: process group kill (SIGTERM -pid), ESRCH guard for already-exited processes
- stopAll: cleans up all tracked Metro processes
- waitForReady: port polling with early-exit crash detection
- DevServerManager: metroMode flag wires Metro strategy into ensureServerRunning,
  isServerRunning, runServerForeground, and cleanup
- Errors thrown (not swallowed) per CLAUDE.md guidelines
- 18 unit tests for MetroDevServerStrategy + 7 new tests in DevServerManager
…ities

- Add assertIOSAvailable() platform guard for macOS + Xcode CLI check
- Add simulator management: boot, shutdown, install, launch, list
- Add xcodebuild wrapper for simulator and device builds; requires
  derivedDataPath (Xcode DerivedData hashed subdirs are unpredictable);
  surfaces stderr or stdout on failure
- Add listConnectedDevices() with regex handling nested OS version parens
- Add simulator UDID tracking per worktree in ios-simulators.json;
  only swallows ENOENT, rethrows EACCES and other I/O errors
- Add 40 unit tests covering all exports and edge cases
…ver commands

- Add iOS routing to `il open`: React Native opens ios/ in Xcode, native iOS opens project root in Xcode
- Add iOS routing to `il run`: React Native uses `npx react-native run-ios`, native iOS uses `xcodebuild`
- Add iOS routing to `il dev-server`: React Native proceeds to Metro bundler (cross-platform), native iOS throws with guidance to use `il run`
- Fix `assertMacOS()` placement in dev-server — Metro is cross-platform; macOS check only applies to native iOS
- Fix dev-server native iOS path to throw Error instead of returning CommandResult object (per project guidelines)
- Fix openIOSProject to open Xcode (not execute the app) for React Native projects
- Add `buildAndRunIOS` capabilities parameter to properly branch native vs React Native build tools
- Add `ios.command_invoked` telemetry event for all three commands
- Add `'ios'` to ProjectCapability union type and VALID_CAPABILITIES
- Add iOS behavior documentation to docs/iloom-commands.md
- Replace dynamic imports of MacOSRequiredError in tests with static imports
- Fix capabilities dropped in getPackageConfig() merge
- Unify macOS assertion to use assertMacOS() consistently
…code)

Adds iOS as a third project capability alongside CLI and web:
- iOS capability type and settings schema (simulator, device, code signing)
- Project detection for React Native, Expo, and native Xcode projects
- Metro bundler dev server strategy for React Native
- iOS build, simulator, and device deployment utilities
- Command routing for il open/run/dev-server with iOS projects
- Framework detector agent updated for iOS project recognition

Fixes #966
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

Epic: Add iOS Project Support to iloom

1 participant