@use-voltra/ios-client 1.4.0 → 2.0.0-rc.1

package/expo-plugin/src/ios-widget/xcode/index.ts

@@ -0,0 +1,149 @@
+import { ConfigPlugin, withXcodeProject } from '@expo/config-plugins'
+import * as path from 'path'
+
+import { getIOSWidgetExtensionFiles } from '../../utils/fileDiscovery'
+import { addBuildPhases, ensureBuildPhases } from './buildPhases'
+import { addXCConfigurationList, ensureXCConfigurationList } from './configurationList'
+import { addPbxGroup, ensurePbxGroup } from './groups'
+import { getMainAppTargetSettings } from './mainAppSettings'
+import { addProductFile, ensureProductFile } from './productFile'
+import { configureTarget, ensureTargetAttributes, ensureTargetDependency } from './target'
+
+export interface ConfigureXcodeProjectProps {
+  targetName: string
+  bundleIdentifier: string
+  deploymentTarget: string
+}
+
+/**
+ * Plugin step that configures the Xcode project for the widget extension.
+ *
+ * This:
+ * - Adds XCConfigurationList with Debug/Release configurations
+ * - Adds the product file (.appex)
+ * - Configures the native target
+ * - Adds build phases (Sources, CopyFiles, Frameworks, Resources)
+ * - Adds PBXGroup for widget files
+ *
+ * This should run after generateWidgetExtensionFiles so the files exist.
+ */
+export const configureXcodeProject: ConfigPlugin<ConfigureXcodeProjectProps> = (config, props) => {
+  const { targetName, bundleIdentifier, deploymentTarget } = props
+
+  return withXcodeProject(config, (config) => {
+    if (config.modRequest.introspect) {
+      return config
+    }
+
+    const xcodeProject = config.modResults
+    const groupName = 'Embed Foundation Extensions'
+
+    // Check if target already exists
+    const nativeTargets = xcodeProject.pbxNativeTargetSection()
+    const existingTargetKey = xcodeProject.findTargetKey(targetName)
+    const existingTarget = existingTargetKey ? nativeTargets[existingTargetKey] : null
+
+    const { platformProjectRoot } = config.modRequest
+    const targetPath = path.join(platformProjectRoot, targetName)
+    const widgetFiles = getIOSWidgetExtensionFiles(targetPath, targetName)
+
+    // Read main app target settings to synchronize code signing
+    const mainAppSettings = getMainAppTargetSettings(xcodeProject)
+
+    // Use the deploymentTarget from plugin config (or default), ignore main app's deployment target
+    // This allows the widget extension to have its own deployment target independent of the main app
+
+    if (existingTarget && existingTargetKey) {
+      // Ensure configuration list is up to date
+      const xCConfigurationList = ensureXCConfigurationList(
+        xcodeProject,
+        {
+          targetName,
+          bundleIdentifier,
+          deploymentTarget,
+          codeSignStyle: mainAppSettings?.codeSignStyle,
+          developmentTeam: mainAppSettings?.developmentTeam,
+          provisioningProfileSpecifier: mainAppSettings?.provisioningProfileSpecifier,
+        },
+        existingTarget.buildConfigurationList
+      )
+
+      // Ensure product file exists
+      const productFile = ensureProductFile(xcodeProject, {
+        targetName,
+        groupName,
+      })
+
+      // Update target references
+      existingTarget.productReference = productFile.fileRef
+      existingTarget.buildConfigurationList = xCConfigurationList.uuid
+      existingTarget.productType = `"com.apple.product-type.app-extension"`
+      existingTarget.name = targetName
+      existingTarget.productName = targetName
+      if (!existingTarget.buildPhases) {
+        existingTarget.buildPhases = []
+      }
+
+      // Ensure build phases and groups
+      ensureBuildPhases(xcodeProject, {
+        targetUuid: existingTargetKey,
+        groupName,
+        productFile,
+        widgetFiles,
+        mainTargetUuid: xcodeProject.getFirstTarget().uuid,
+      })
+
+      ensurePbxGroup(xcodeProject, {
+        targetName,
+        widgetFiles,
+      })
+
+      ensureTargetAttributes(xcodeProject, existingTargetKey)
+      ensureTargetDependency(xcodeProject, existingTargetKey)
+
+      return config
+    }
+
+    // Add configuration list
+    const targetUuid = xcodeProject.generateUuid()
+
+    const xCConfigurationList = addXCConfigurationList(xcodeProject, {
+      targetName,
+      bundleIdentifier,
+      deploymentTarget,
+      codeSignStyle: mainAppSettings?.codeSignStyle,
+      developmentTeam: mainAppSettings?.developmentTeam,
+      provisioningProfileSpecifier: mainAppSettings?.provisioningProfileSpecifier,
+    })
+
+    // Add product file
+    const productFile = addProductFile(xcodeProject, {
+      targetName,
+      groupName,
+    })
+
+    // Configure target (native target, project section, dependency)
+    configureTarget(xcodeProject, {
+      targetName,
+      targetUuid,
+      productFile,
+      xCConfigurationList,
+    })
+
+    // Add build phases
+    addBuildPhases(xcodeProject, {
+      targetUuid,
+      groupName,
+      productFile,
+      widgetFiles,
+    })
+
+    // Add PBX group
+    addPbxGroup(xcodeProject, {
+      targetName,
+      widgetFiles,
+    })
+
+    return config
+  })
+}

package/expo-plugin/src/ios-widget/xcode/mainAppSettings.ts

@@ -0,0 +1,95 @@
+import { XcodeProject } from '@expo/config-plugins'
+
+export interface MainAppTargetSettings {
+  deploymentTarget: string
+  codeSignStyle?: string
+  developmentTeam?: string
+  provisioningProfileSpecifier?: string
+}
+
+/**
+ * Reads build settings from the main app target to synchronize code signing with the widget extension.
+ *
+ * @param xcodeProject The Xcode project instance
+ * @returns The main app target's build settings, or null if not found
+ */
+export function getMainAppTargetSettings(xcodeProject: XcodeProject): MainAppTargetSettings | null {
+  try {
+    const mainAppTarget = xcodeProject.getFirstTarget()?.firstTarget
+
+    if (!mainAppTarget) {
+      return null
+    }
+
+    // Get the build configuration list for the main app target
+    const buildConfigurationListId = mainAppTarget.buildConfigurationList
+    if (!buildConfigurationListId) {
+      return null
+    }
+
+    // Extract UUID from buildConfigurationListId (it might include a comment like "UUID /* comment */")
+    const buildConfigurationListUuid = buildConfigurationListId.split(' ')[0]
+
+    const buildConfigurationList =
+      xcodeProject.hash.project.objects['XCConfigurationList']?.[buildConfigurationListUuid]
+    if (!buildConfigurationList || !buildConfigurationList.buildConfigurations) {
+      return null
+    }
+
+    // Get the first build configuration (usually Debug) to read settings
+    const firstConfigRef = buildConfigurationList.buildConfigurations[0]
+    if (!firstConfigRef) {
+      return null
+    }
+
+    // Extract UUID from config reference (it might include a comment)
+    const firstConfigUuid =
+      typeof firstConfigRef === 'string' ? firstConfigRef.split(' ')[0] : firstConfigRef.value?.split(' ')[0]
+    if (!firstConfigUuid) {
+      return null
+    }
+
+    const buildConfiguration = xcodeProject.hash.project.objects['XCBuildConfiguration']?.[firstConfigUuid]
+    if (!buildConfiguration || !buildConfiguration.buildSettings) {
+      return null
+    }
+
+    const buildSettings = buildConfiguration.buildSettings
+
+    // Extract deployment target (remove quotes if present)
+    const deploymentTarget =
+      buildSettings.IPHONEOS_DEPLOYMENT_TARGET?.replace(/^"|"$/g, '') ||
+      buildSettings['IPHONEOS_DEPLOYMENT_TARGET']?.replace(/^"|"$/g, '') ||
+      null
+
+    // Extract code signing settings
+    const codeSignStyle =
+      buildSettings.CODE_SIGN_STYLE?.replace(/^"|"$/g, '') ||
+      buildSettings['CODE_SIGN_STYLE']?.replace(/^"|"$/g, '') ||
+      null
+
+    const developmentTeam =
+      buildSettings.DEVELOPMENT_TEAM?.replace(/^"|"$/g, '') ||
+      buildSettings['DEVELOPMENT_TEAM']?.replace(/^"|"$/g, '') ||
+      null
+
+    const provisioningProfileSpecifier =
+      buildSettings.PROVISIONING_PROFILE_SPECIFIER?.replace(/^"|"$/g, '') ||
+      buildSettings['PROVISIONING_PROFILE_SPECIFIER']?.replace(/^"|"$/g, '') ||
+      null
+
+    if (!deploymentTarget) {
+      return null
+    }
+
+    return {
+      deploymentTarget,
+      codeSignStyle: codeSignStyle || undefined,
+      developmentTeam: developmentTeam || undefined,
+      provisioningProfileSpecifier: provisioningProfileSpecifier || undefined,
+    }
+  } catch {
+    // If we can't read the settings, return null and use fallback values
+    return null
+  }
+}

package/expo-plugin/src/ios-widget/xcode/productFile.ts

@@ -0,0 +1,91 @@
+import { XcodeProject } from '@expo/config-plugins'
+
+export interface AddProductFileOptions {
+  targetName: string
+  groupName: string
+}
+
+function findProductFileReference(xcodeProject: XcodeProject, targetName: string): { fileRef: string } | null {
+  const fileReferenceSection = xcodeProject.pbxFileReferenceSection()
+  const targetProductName = `${targetName}.appex`
+
+  for (const key of Object.keys(fileReferenceSection)) {
+    if (/_comment$/.test(key)) {
+      continue
+    }
+    const entry = fileReferenceSection[key]
+    const path = typeof entry?.path === 'string' ? entry.path.replace(/^"|"$/g, '') : ''
+    const name = typeof entry?.name === 'string' ? entry.name.replace(/^"|"$/g, '') : ''
+
+    if (path === targetProductName || name === targetProductName) {
+      return { fileRef: key }
+    }
+  }
+
+  return null
+}
+
+function findBuildFileForFileRef(xcodeProject: XcodeProject, fileRef: string): { uuid: string } | null {
+  const buildFileSection = xcodeProject.pbxBuildFileSection()
+
+  for (const key of Object.keys(buildFileSection)) {
+    if (/_comment$/.test(key)) {
+      continue
+    }
+    const entry = buildFileSection[key]
+    if (entry?.fileRef === fileRef) {
+      return { uuid: key }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Adds the product file (.appex) for the widget extension.
+ */
+export function addProductFile(xcodeProject: XcodeProject, options: AddProductFileOptions) {
+  const { targetName, groupName } = options
+
+  const productFileOptions = {
+    basename: `${targetName}.appex`,
+    group: groupName,
+    explicitFileType: 'wrapper.app-extension',
+    settings: {
+      ATTRIBUTES: ['RemoveHeadersOnCopy'],
+    },
+    includeInIndex: 0,
+    path: `${targetName}.appex`,
+    sourceTree: 'BUILT_PRODUCTS_DIR',
+  }
+
+  const productFile = xcodeProject.addProductFile(targetName, productFileOptions)
+
+  return productFile
+}
+
+/**
+ * Ensures the product file (.appex) exists and returns it.
+ */
+export function ensureProductFile(xcodeProject: XcodeProject, options: AddProductFileOptions) {
+  const { targetName, groupName } = options
+  const existingFile = findProductFileReference(xcodeProject, targetName)
+
+  if (!existingFile) {
+    return addProductFile(xcodeProject, options)
+  }
+
+  const buildFile = findBuildFileForFileRef(xcodeProject, existingFile.fileRef)
+  const productFile = {
+    uuid: buildFile?.uuid ?? xcodeProject.generateUuid(),
+    fileRef: existingFile.fileRef,
+    basename: `${targetName}.appex`,
+    group: groupName,
+  }
+
+  if (!buildFile) {
+    xcodeProject.addToPbxBuildFileSection(productFile as any)
+  }
+
+  return productFile
+}

package/expo-plugin/src/ios-widget/xcode/target.ts

@@ -0,0 +1,148 @@
+import { XcodeProject } from '@expo/config-plugins'
+
+import { IOS } from '../../constants'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ConfigureTargetOptions {
+  targetName: string
+  targetUuid: string
+  productFile: { fileRef: string }
+  xCConfigurationList: { uuid: string }
+}
+
+interface AddNativeTargetOptions {
+  targetName: string
+  targetUuid: string
+  productFile: { fileRef: string }
+  xCConfigurationList: { uuid: string }
+}
+
+// ============================================================================
+// Main Function
+// ============================================================================
+
+/**
+ * Configures the widget extension target in the Xcode project.
+ *
+ * This:
+ * - Adds the target to PBXNativeTarget section
+ * - Adds the target to PBXProject section
+ * - Adds a dependency from the main app to the widget extension
+ */
+export function configureTarget(xcodeProject: XcodeProject, options: ConfigureTargetOptions) {
+  const target = addToPbxNativeTargetSection(xcodeProject, options)
+  addToPbxProjectSection(xcodeProject, target)
+  addTargetDependency(xcodeProject, target)
+
+  return target
+}
+
+/**
+ * Ensures target attributes (LastSwiftMigration) exist for the target.
+ */
+export function ensureTargetAttributes(xcodeProject: XcodeProject, targetUuid: string): void {
+  const projectSection = xcodeProject.pbxProjectSection()
+  const firstProject = xcodeProject.getFirstProject()
+
+  if (!projectSection[firstProject.uuid].attributes.TargetAttributes) {
+    projectSection[firstProject.uuid].attributes.TargetAttributes = {}
+  }
+
+  if (!projectSection[firstProject.uuid].attributes.TargetAttributes[targetUuid]) {
+    projectSection[firstProject.uuid].attributes.TargetAttributes[targetUuid] = {
+      LastSwiftMigration: IOS.LAST_SWIFT_MIGRATION,
+    }
+  }
+}
+
+/**
+ * Ensures a target dependency exists so the main app depends on the widget extension.
+ */
+export function ensureTargetDependency(xcodeProject: XcodeProject, targetUuid: string): void {
+  if (!xcodeProject.hash.project.objects['PBXTargetDependency']) {
+    xcodeProject.hash.project.objects['PBXTargetDependency'] = {}
+  }
+  if (!xcodeProject.hash.project.objects['PBXContainerItemProxy']) {
+    xcodeProject.hash.project.objects['PBXContainerItemProxy'] = {}
+  }
+
+  const mainTargetUuid = xcodeProject.getFirstTarget().uuid
+  const mainTarget = xcodeProject.pbxNativeTargetSection()[mainTargetUuid]
+  const existingDeps = mainTarget?.dependencies ?? []
+  const targetDependencySection = xcodeProject.hash.project.objects['PBXTargetDependency'] || {}
+
+  const alreadyExists = existingDeps.some((dep: any) => {
+    const dependency = targetDependencySection[dep.value]
+    return dependency?.target === targetUuid
+  })
+
+  if (!alreadyExists) {
+    xcodeProject.addTargetDependency(mainTargetUuid, [targetUuid])
+  }
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Adds the widget extension target to the PBXNativeTarget section.
+ */
+function addToPbxNativeTargetSection(xcodeProject: XcodeProject, options: AddNativeTargetOptions) {
+  const { targetName, targetUuid, productFile, xCConfigurationList } = options
+
+  const target = {
+    uuid: targetUuid,
+    pbxNativeTarget: {
+      isa: 'PBXNativeTarget',
+      name: targetName,
+      productName: targetName,
+      productReference: productFile.fileRef,
+      productType: `"com.apple.product-type.app-extension"`,
+      buildConfigurationList: xCConfigurationList.uuid,
+      buildPhases: [],
+      buildRules: [],
+      dependencies: [],
+    },
+  }
+
+  xcodeProject.addToPbxNativeTargetSection(target)
+
+  return target
+}
+
+/**
+ * Adds the target to the PBXProject section.
+ */
+function addToPbxProjectSection(xcodeProject: XcodeProject, target: { uuid: string }): void {
+  xcodeProject.addToPbxProjectSection(target)
+
+  // Add target attributes to project section
+  const projectSection = xcodeProject.pbxProjectSection()
+  const firstProject = xcodeProject.getFirstProject()
+
+  if (!projectSection[firstProject.uuid].attributes.TargetAttributes) {
+    projectSection[firstProject.uuid].attributes.TargetAttributes = {}
+  }
+
+  projectSection[firstProject.uuid].attributes.TargetAttributes[target.uuid] = {
+    LastSwiftMigration: IOS.LAST_SWIFT_MIGRATION,
+  }
+}
+
+/**
+ * Adds a target dependency so the main app depends on the widget extension.
+ */
+function addTargetDependency(xcodeProject: XcodeProject, target: { uuid: string }): void {
+  if (!xcodeProject.hash.project.objects['PBXTargetDependency']) {
+    xcodeProject.hash.project.objects['PBXTargetDependency'] = {}
+  }
+  if (!xcodeProject.hash.project.objects['PBXContainerItemProxy']) {
+    xcodeProject.hash.project.objects['PBXContainerItemProxy'] = {}
+  }
+
+  xcodeProject.addTargetDependency(xcodeProject.getFirstTarget().uuid, [target.uuid])
+}

package/expo-plugin/src/types.ts

@@ -0,0 +1,89 @@
+import type { ConfigPlugin } from '@expo/config-plugins'
+
+import type { WidgetInitialStatePath, WidgetLabel } from '@use-voltra/expo-plugin'
+
+/**
+ * Supported iOS Home Screen widget size families.
+ */
+export type IOSWidgetFamily =
+  | 'systemSmall'
+  | 'systemMedium'
+  | 'systemLarge'
+  | 'systemExtraLarge'
+  | 'accessoryCircular'
+  | 'accessoryRectangular'
+  | 'accessoryInline'
+
+/**
+ * Configuration for a single iOS home screen widget.
+ */
+export interface IOSWidgetConfig {
+  /**
+   * Unique identifier for the widget (used as the widget kind and in JS API)
+   */
+  id: string
+  displayName: WidgetLabel
+  description: WidgetLabel
+  /** @default ['systemSmall', 'systemMedium', 'systemLarge'] */
+  supportedFamilies?: IOSWidgetFamily[]
+  initialStatePath?: WidgetInitialStatePath
+  serverUpdate?: IOSWidgetServerUpdateConfig
+}
+
+/**
+ * Server-driven iOS widget updates (WidgetKit background refresh).
+ */
+export interface IOSWidgetServerUpdateConfig {
+  url: string
+  /** @default 15 */
+  intervalMinutes?: number
+  /** @default false */
+  refresh?: boolean
+}
+
+/**
+ * Files in the widget extension target (Xcode build phases / groups).
+ */
+export interface IOSWidgetExtensionFiles {
+  swiftFiles: string[]
+  entitlementFiles: string[]
+  plistFiles: string[]
+  assetDirectories: string[]
+  intentFiles: string[]
+  /** Paths relative to the widget extension root (e.g. en.lproj/VoltraWidgets.strings) */
+  localizedStringResources: string[]
+}
+
+/**
+ * Options for `@use-voltra/ios-client` Expo config plugin.
+ */
+export interface IOSConfigPluginProps {
+  enablePushNotifications?: boolean
+  groupIdentifier?: string
+  widgets?: IOSWidgetConfig[]
+  deploymentTarget?: string
+  targetName?: string
+  fonts?: string[]
+  keychainGroup?: string
+}
+
+export type VoltraIosConfigPlugin = ConfigPlugin<IOSConfigPluginProps | undefined>
+
+export interface IOSMainAppPluginProps {
+  groupIdentifier?: string
+  widgetIds?: string[]
+  widgets?: IOSWidgetConfig[]
+  keychainGroup?: string
+}
+
+export interface IOSWidgetExtensionPluginProps {
+  targetName: string
+  bundleIdentifier: string
+  deploymentTarget: string
+  widgets?: IOSWidgetConfig[]
+  groupIdentifier?: string
+  keychainGroup?: string
+  fonts?: string[]
+  version: string
+  buildNumber: string
+}

package/expo-plugin/src/utils/fileDiscovery.ts

@@ -0,0 +1,96 @@
+import * as fs from 'fs'
+import * as path from 'path'
+
+import type { IOSWidgetExtensionFiles } from '../types'
+import { logger } from '@use-voltra/expo-plugin'
+
+/** Table name matches basename without extension; co-located per locale in *.lproj */
+export const VOLTRA_WIDGET_STRINGS_BASENAME = 'VoltraWidgets.strings'
+
+/**
+ * Scans the widget extension target directory and returns categorized file lists.
+ *
+ * This function only reads the directory structure - it does NOT copy or create files.
+ * File generation should be done before this is called.
+ *
+ * @param targetPath - Path to the widget extension target directory
+ * @param targetName - Name of the target (for entitlements file)
+ * @returns Categorized lists of files for Xcode project configuration
+ */
+export function getIOSWidgetExtensionFiles(targetPath: string, targetName: string): IOSWidgetExtensionFiles {
+  const widgetFiles: IOSWidgetExtensionFiles = {
+    swiftFiles: [],
+    entitlementFiles: [],
+    plistFiles: [],
+    assetDirectories: [],
+    intentFiles: [],
+    localizedStringResources: [],
+  }
+
+  if (!fs.existsSync(targetPath)) {
+    logger.warn(`Widget target directory does not exist: ${targetPath}`)
+    // Still include required generated files even if directory doesn't exist yet
+    const initialStatesFile = 'VoltraWidgetInitialStates.swift'
+    widgetFiles.swiftFiles.push(initialStatesFile)
+    const targetEntitlements = `${targetName}.entitlements`
+    widgetFiles.entitlementFiles.push(targetEntitlements)
+    return widgetFiles
+  }
+
+  const files = fs.readdirSync(targetPath)
+
+  for (const entry of files) {
+    if (!entry.endsWith('.lproj')) {
+      continue
+    }
+    const stringsPath = path.join(targetPath, entry, VOLTRA_WIDGET_STRINGS_BASENAME)
+    if (fs.existsSync(stringsPath)) {
+      widgetFiles.localizedStringResources.push(`${entry}/${VOLTRA_WIDGET_STRINGS_BASENAME}`)
+    }
+  }
+
+  for (const file of files) {
+    const itemPath = path.join(targetPath, file)
+    const isDirectory = fs.lstatSync(itemPath).isDirectory()
+
+    // Handle directories (Assets.xcassets)
+    if (isDirectory) {
+      if (file === 'Assets.xcassets') {
+        widgetFiles.assetDirectories.push(file)
+      }
+      continue
+    }
+
+    // Categorize files by extension
+    const ext = path.extname(file).toLowerCase()
+
+    switch (ext) {
+      case '.swift':
+        widgetFiles.swiftFiles.push(file)
+        break
+      case '.entitlements':
+        widgetFiles.entitlementFiles.push(file)
+        break
+      case '.plist':
+        widgetFiles.plistFiles.push(file)
+        break
+      case '.intentdefinition':
+        widgetFiles.intentFiles.push(file)
+        break
+    }
+  }
+
+  // Always include the target entitlements file
+  const targetEntitlements = `${targetName}.entitlements`
+  if (!widgetFiles.entitlementFiles.includes(targetEntitlements)) {
+    widgetFiles.entitlementFiles.push(targetEntitlements)
+  }
+
+  // Always include VoltraWidgetInitialStates.swift (generated by config plugin)
+  const initialStatesFile = 'VoltraWidgetInitialStates.swift'
+  if (!widgetFiles.swiftFiles.includes(initialStatesFile)) {
+    widgetFiles.swiftFiles.push(initialStatesFile)
+  }
+
+  return widgetFiles
+}