voltra 2.0.0 → 2.1.0

package/src/config/types.ts

@@ -0,0 +1,317 @@
+import type { CLI_DEFAULTS } from './defaults'
+
+export type VoltraPlatform = 'android' | 'ios'
+
+/**
+ * Per-locale widget copy or build-time initial state paths.
+ * This intentionally matches the existing Expo plugin contract.
+ */
+export type WidgetLocalizedValue = Record<string, string>
+
+/** Widget display text, either as a single string or localized by locale identifier. */
+export type WidgetLabel = string | WidgetLocalizedValue
+
+/** Path to a widget initial state module, either as a single path or localized by locale identifier. */
+export type WidgetInitialStatePath = string | WidgetLocalizedValue
+
+export interface AndroidWidgetServerUpdateConfig {
+  /** Server endpoint that returns widget state updates. */
+  url: string
+  /** Refresh interval, in minutes, for fetching server updates. */
+  intervalMinutes?: number
+  /** Whether fetched updates should trigger an immediate widget refresh. */
+  refresh?: boolean
+}
+
+export interface AndroidWidgetAppIntentParameter {
+  /** Configuration key surfaced to env.configuration. */
+  name: string
+  /** Optional label for runtime configuration UIs. */
+  title?: string
+  /** Default value used before runtime configuration overrides it. */
+  default?: string
+}
+
+export interface AndroidWidgetAppIntentConfig {
+  /** Parameters surfaced to env.configuration for Dynamic Widgets. */
+  parameters: AndroidWidgetAppIntentParameter[]
+}
+
+export interface AndroidWidgetConfig {
+  /** Stable widget identifier used in generated files and registrations. */
+  id: string
+  /** User-facing widget name shown by the launcher. */
+  displayName: WidgetLabel
+  /** User-facing widget description shown by the launcher. */
+  description: WidgetLabel
+  /** Minimum widget width in dp. */
+  minWidth?: number
+  /** Minimum widget height in dp. */
+  minHeight?: number
+  /** Minimum widget width in launcher grid cells. */
+  minCellWidth?: number
+  /** Minimum widget height in launcher grid cells. */
+  minCellHeight?: number
+  /** Default widget width in launcher grid cells. */
+  targetCellWidth: number
+  /** Default widget height in launcher grid cells. */
+  targetCellHeight: number
+  /** Supported resize directions for the Android widget. */
+  resizeMode?: 'none' | 'horizontal' | 'vertical' | 'horizontal|vertical'
+  /** Launcher surfaces where the widget can be placed. */
+  widgetCategory?: 'home_screen' | 'keyguard' | 'home_screen|keyguard'
+  /** Path to the build-time initial state module for this widget. */
+  initialStatePath?: WidgetInitialStatePath
+  /** Project-relative Dynamic Widget entry module. */
+  entry?: string
+  /** Server-driven update settings for this widget. */
+  serverUpdate?: AndroidWidgetServerUpdateConfig
+  /** Path to the preview image shown in widget pickers. */
+  previewImage?: string
+  /** Path to a preview layout XML file shown in widget pickers. */
+  previewLayout?: string
+  /** Dynamic Widget configuration parameters surfaced to env.configuration. */
+  appIntent?: AndroidWidgetAppIntentConfig
+}
+
+export type IOSWidgetFamily =
+  | 'systemSmall'
+  | 'systemMedium'
+  | 'systemLarge'
+  | 'systemExtraLarge'
+  | 'accessoryCircular'
+  | 'accessoryRectangular'
+  | 'accessoryInline'
+
+export interface IOSWidgetServerUpdateConfig {
+  /** Server endpoint that returns widget state updates. */
+  url: string
+  /** Refresh interval, in minutes, for fetching server updates. */
+  intervalMinutes?: number
+  /** Whether fetched updates should trigger an immediate widget refresh. */
+  refresh?: boolean
+}
+
+export interface IOSWidgetAppIntentParameter {
+  /** Configuration key surfaced to env.configuration. */
+  name: string
+  /** Label shown in the native Edit Widget sheet. */
+  title: string
+  /** Default value used before the user configures the widget. */
+  default?: string
+}
+
+export interface IOSWidgetAppIntentConfig {
+  /** Parameters exposed through AppIntentConfiguration for Dynamic Widgets. */
+  parameters: IOSWidgetAppIntentParameter[]
+}
+
+export interface IOSWidgetConfig {
+  /** Stable widget identifier used in generated files and registrations. */
+  id: string
+  /** User-facing widget name shown in iOS widget configuration UI. */
+  displayName: WidgetLabel
+  /** User-facing widget description shown in iOS widget configuration UI. */
+  description: WidgetLabel
+  /** Supported iOS widget families for this widget. */
+  supportedFamilies?: IOSWidgetFamily[]
+  /** Path to the build-time initial state module for this widget. */
+  initialStatePath?: WidgetInitialStatePath
+  /** Project-relative Dynamic Widget entry module. */
+  entry?: string
+  /** Server-driven update settings for this widget. */
+  serverUpdate?: IOSWidgetServerUpdateConfig
+  /** Dynamic Widget AppIntent configuration. */
+  appIntent?: IOSWidgetAppIntentConfig
+}
+
+export interface AndroidProjectOverrides {
+  /** Root directory of the Android native project. Defaults to `android/` under `projectRoot`. */
+  rootDir?: string
+  /** Android app module name. Defaults to `app` when it can be inferred. */
+  appModuleName?: string
+  /** Explicit path to the AndroidManifest.xml file for the app module. */
+  manifestPath?: string
+  /** Explicit Android package name if it cannot be derived from the project files. */
+  packageName?: string
+}
+
+export interface IOSProjectOverrides {
+  /** Root directory of the iOS native project. Defaults to `ios/` under `projectRoot`. */
+  rootDir?: string
+  /** Explicit path to the `.xcodeproj` directory to use for discovery. */
+  xcodeprojPath?: string
+  /** Main application target name when the Xcode project has multiple app targets. */
+  mainTargetName?: string
+  /** Explicit path to the app target Info.plist file. */
+  infoPlistPath?: string
+  /** Explicit path to the main app entitlements file. */
+  entitlementsPath?: string
+  /** Explicit path to the Podfile. */
+  podfilePath?: string
+}
+
+/**
+ * Public CLI config for Android. This stays close to the current Expo plugin props,
+ * with explicit project discovery overrides added for native projects.
+ */
+export interface VoltraAndroidConfig {
+  /** Whether to add the Android notification permission and related setup. */
+  enableNotifications?: boolean
+  /** Android widgets to generate and register. */
+  widgets?: AndroidWidgetConfig[]
+  /** Font files that should be bundled for Android widget rendering. */
+  fonts?: string[]
+  /** Directory containing user-provided images for Android widgets. */
+  userImagesPath?: string
+  /** Native Android project discovery overrides. */
+  project?: AndroidProjectOverrides
+}
+
+/**
+ * Public CLI config for iOS. This stays close to the current Expo plugin props,
+ * with explicit project discovery overrides added for native projects.
+ */
+export interface VoltraIOSConfig {
+  /** Whether to enable push-notification-related iOS setup for widgets and Live Activities. */
+  enablePushNotifications?: boolean
+  /** App Group identifier used to share data between the app and widget extension. */
+  groupIdentifier?: string
+  /** iOS widgets to generate and register. */
+  widgets?: IOSWidgetConfig[]
+  /** Minimum iOS deployment target for generated widget targets. */
+  deploymentTarget?: string
+  /** Override for the generated widget extension target name. */
+  targetName?: string
+  /** Font files that should be bundled for iOS widget rendering. */
+  fonts?: string[]
+  /** Directory containing user-provided images for iOS widgets. */
+  userImagesPath?: string
+  /** Keychain access group shared by the app and extension. */
+  keychainGroup?: string
+  /** Native iOS project discovery overrides. */
+  project?: IOSProjectOverrides
+}
+
+export interface VoltraConfig {
+  /** Root directory used to resolve relative paths in the Voltra config. Defaults to the config file directory. */
+  projectRoot?: string
+  /** Android-specific Voltra configuration. */
+  android?: VoltraAndroidConfig
+  /** iOS-specific Voltra configuration. */
+  ios?: VoltraIOSConfig
+}
+
+export interface LoadedVoltraConfig {
+  /** Parsed Voltra config object loaded from disk. */
+  config: VoltraConfig
+  /** Absolute path to the loaded config file, when the config came from a file. */
+  configPath?: string
+  /** Directory that contained the loaded config source. */
+  configDir: string
+}
+
+export interface NormalizedAndroidWidgetServerUpdateConfig {
+  /** Server endpoint that returns widget state updates. */
+  url: string
+  /** Refresh interval, in minutes, for fetching server updates. */
+  intervalMinutes: number
+  /** Whether fetched updates should trigger an immediate widget refresh. */
+  refresh: boolean
+}
+
+export interface NormalizedAndroidWidgetConfig extends Omit<AndroidWidgetConfig, 'serverUpdate'> {
+  /** Server-driven update settings after defaults have been applied. */
+  serverUpdate?: NormalizedAndroidWidgetServerUpdateConfig
+}
+
+export interface NormalizedIOSWidgetServerUpdateConfig {
+  /** Server endpoint that returns widget state updates. */
+  url: string
+  /** Refresh interval, in minutes, for fetching server updates. */
+  intervalMinutes: number
+  /** Whether fetched updates should trigger an immediate widget refresh. */
+  refresh: boolean
+}
+
+export interface NormalizedIOSWidgetConfig extends Omit<IOSWidgetConfig, 'serverUpdate' | 'supportedFamilies'> {
+  /** Supported iOS widget families after defaults have been applied. */
+  supportedFamilies: IOSWidgetFamily[]
+  /** Server-driven update settings after defaults have been applied. */
+  serverUpdate?: NormalizedIOSWidgetServerUpdateConfig
+}
+
+export interface NormalizedAndroidProjectConfig {
+  /** Absolute Android project root directory, if overridden. */
+  rootDir?: string
+  /** Resolved Android app module name. */
+  appModuleName?: string
+  /** Absolute path to AndroidManifest.xml, if overridden. */
+  manifestPath?: string
+  /** Explicit Android package name, if overridden. */
+  packageName?: string
+}
+
+export interface NormalizedIOSProjectConfig {
+  /** Absolute iOS project root directory, if overridden. */
+  rootDir?: string
+  /** Absolute path to the `.xcodeproj` directory, if overridden. */
+  xcodeprojPath?: string
+  /** Explicit main iOS application target name, if overridden. */
+  mainTargetName?: string
+  /** Absolute path to the Info.plist file, if overridden. */
+  infoPlistPath?: string
+  /** Absolute path to the entitlements file, if overridden. */
+  entitlementsPath?: string
+  /** Absolute path to the Podfile, if overridden. */
+  podfilePath?: string
+}
+
+export interface NormalizedVoltraAndroidConfig {
+  /** Whether Android notification setup should be applied. */
+  enableNotifications: boolean
+  /** Android widgets after validation and normalization. */
+  widgets: NormalizedAndroidWidgetConfig[]
+  /** Absolute font file paths for Android widgets. */
+  fonts: string[]
+  /** Absolute path to the Android user images directory. */
+  userImagesPath: string
+  /** Normalized Android native project discovery overrides. */
+  project: NormalizedAndroidProjectConfig
+}
+
+export interface NormalizedVoltraIOSConfig {
+  /** Whether iOS push-notification-related setup should be applied. */
+  enablePushNotifications: boolean
+  /** App Group identifier used to share data between the app and extension. */
+  groupIdentifier?: string
+  /** iOS widgets after validation and normalization. */
+  widgets: NormalizedIOSWidgetConfig[]
+  /** Effective iOS deployment target for generated widget targets. */
+  deploymentTarget: string
+  /** Effective widget extension target name override, if provided. */
+  targetName?: string
+  /** Absolute font file paths for iOS widgets. */
+  fonts: string[]
+  /** Absolute path to the iOS user images directory. */
+  userImagesPath: string
+  /** Keychain access group shared by the app and extension. */
+  keychainGroup?: string
+  /** Normalized iOS native project discovery overrides. */
+  project: NormalizedIOSProjectConfig
+}
+
+export interface NormalizedVoltraConfig {
+  /** Absolute path to the loaded config file, when the config came from a file. */
+  configPath?: string
+  /** Directory that contained the loaded config source. */
+  configDir: string
+  /** Absolute root directory used for resolving all project-relative paths. */
+  projectRoot: string
+  /** Normalized Android-specific Voltra configuration. */
+  android?: NormalizedVoltraAndroidConfig
+  /** Normalized iOS-specific Voltra configuration. */
+  ios?: NormalizedVoltraIOSConfig
+}
+
+export type CliDefaults = typeof CLI_DEFAULTS

package/src/cosmiconfig.d.ts

@@ -0,0 +1,21 @@
+declare module 'cosmiconfig' {
+  export interface CosmiconfigResult {
+    config: unknown
+    filepath: string
+    isEmpty?: boolean
+  }
+
+  export interface CosmiconfigExplorer {
+    search(searchFrom?: string): Promise<CosmiconfigResult | null>
+    load(filepath: string): Promise<CosmiconfigResult | null>
+  }
+
+  export interface CosmiconfigOptions {
+    searchPlaces?: string[]
+    loaders?: Record<string, unknown>
+  }
+
+  export const defaultLoaders: Record<string, unknown>
+
+  export function cosmiconfig(moduleName: string, options?: CosmiconfigOptions): CosmiconfigExplorer
+}

package/src/dependencies/platformPackages.ts

@@ -0,0 +1,75 @@
+import path from 'node:path'
+import { createRequire } from 'node:module'
+
+import type { VoltraPlatform } from '../config/types'
+
+const PLATFORM_PACKAGE_NAMES: Record<VoltraPlatform, string> = {
+  android: '@use-voltra/android',
+  ios: '@use-voltra/ios',
+}
+
+const PLATFORM_CLIENT_PACKAGE_NAMES: Record<VoltraPlatform, string> = {
+  android: '@use-voltra/android-client',
+  ios: '@use-voltra/ios-client',
+}
+
+export function getPlatformPackageName(platform: VoltraPlatform): string {
+  return PLATFORM_PACKAGE_NAMES[platform]
+}
+
+export function getPlatformClientPackageName(platform: VoltraPlatform): string {
+  return PLATFORM_CLIENT_PACKAGE_NAMES[platform]
+}
+
+export function isPlatformPackageInstalled(projectRoot: string, platform: VoltraPlatform): boolean {
+  return getMissingPlatformPackages(projectRoot, platform).length === 0
+}
+
+export function getMissingPlatformPackages(projectRoot: string, platform: VoltraPlatform): string[] {
+  const projectRequire = createProjectRequire(projectRoot)
+  const packageNames = getRequiredPlatformPackageNames(platform)
+
+  return packageNames.filter((packageName) => !canResolvePackage(projectRequire, packageName))
+}
+
+export function requirePlatformPackage<TPackage>(projectRoot: string, platform: VoltraPlatform): TPackage {
+  return createProjectRequire(projectRoot)(getPlatformPackageName(platform)) as TPackage
+}
+
+export function getMissingPlatformPackageMessage(
+  platform: VoltraPlatform,
+  packageNames = getRequiredPlatformPackageNames(platform)
+): string {
+  const packageLabel = packageNames.length === 1 ? 'package' : 'packages'
+  const verb = packageNames.length === 1 ? 'is' : 'are'
+  const pronoun = packageNames.length === 1 ? 'it' : 'them'
+
+  return `Required ${packageLabel} ${formatPackageList(
+    packageNames
+  )} ${verb} not installed in the app project. Install ${pronoun} because voltra.config includes a ${platform} config block.`
+}
+
+function getRequiredPlatformPackageNames(platform: VoltraPlatform): string[] {
+  return [getPlatformPackageName(platform), getPlatformClientPackageName(platform)]
+}
+
+function canResolvePackage(projectRequire: NodeRequire, packageName: string): boolean {
+  try {
+    projectRequire.resolve(`${packageName}/package.json`)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function formatPackageList(packageNames: string[]): string {
+  if (packageNames.length === 1) {
+    return packageNames[0]
+  }
+
+  return `${packageNames.slice(0, -1).join(', ')} and ${packageNames[packageNames.length - 1]}`
+}
+
+function createProjectRequire(projectRoot: string): NodeRequire {
+  return createRequire(path.join(projectRoot, 'package.json'))
+}

package/src/discovery/android.ts

@@ -0,0 +1,233 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import type { Stats } from 'node:fs'
+
+import { VoltraCliError } from '../reporting/summary'
+
+import type { NormalizedAndroidProjectConfig } from '../config/types'
+
+const ANDROID_MANIFEST_FILE_NAME = 'AndroidManifest.xml'
+
+export interface AndroidProjectDiscovery {
+  androidRoot: string
+  appModuleName: string
+  appModuleRoot: string
+  manifestPath: string
+  buildGradlePath: string
+  packageName: string
+}
+
+export class AndroidProjectDiscoveryError extends VoltraCliError {
+  constructor(message: string) {
+    super(message, 'VOLTRA_ANDROID_DISCOVERY_FAILED')
+    this.name = 'AndroidProjectDiscoveryError'
+  }
+}
+
+export async function discoverAndroidProject(
+  projectRoot: string,
+  config: NormalizedAndroidProjectConfig
+): Promise<AndroidProjectDiscovery> {
+  const androidRoot = await resolveAndroidRoot(projectRoot, config)
+  const manifestPath = await resolveManifestPath(androidRoot, config)
+  const appModuleName = resolveAppModuleName(androidRoot, manifestPath, config.appModuleName)
+  const appModuleRoot = path.join(androidRoot, appModuleName)
+
+  await ensureDirectory(appModuleRoot, `Android app module directory does not exist: ${appModuleRoot}`)
+  ensureManifestBelongsToAppModule(appModuleRoot, manifestPath)
+
+  const buildGradlePath = await resolveBuildGradlePath(appModuleRoot)
+  const packageName = config.packageName ?? (await resolvePackageName(buildGradlePath, manifestPath))
+
+  return {
+    androidRoot,
+    appModuleName,
+    appModuleRoot,
+    manifestPath,
+    buildGradlePath,
+    packageName,
+  }
+}
+
+async function resolveAndroidRoot(projectRoot: string, config: NormalizedAndroidProjectConfig): Promise<string> {
+  const androidRoot = config.rootDir ?? path.join(projectRoot, 'android')
+
+  await ensureDirectory(
+    androidRoot,
+    config.rootDir
+      ? `Configured Android root directory does not exist: ${androidRoot}`
+      : `Android root directory does not exist at ${androidRoot}. Set android.project.rootDir to override the default android/ layout.`
+  )
+
+  return androidRoot
+}
+
+async function resolveManifestPath(androidRoot: string, config: NormalizedAndroidProjectConfig): Promise<string> {
+  const manifestPath =
+    config.manifestPath ??
+    path.join(androidRoot, config.appModuleName ?? 'app', 'src', 'main', ANDROID_MANIFEST_FILE_NAME)
+
+  await ensureFile(
+    manifestPath,
+    config.manifestPath
+      ? `Configured Android manifest does not exist: ${manifestPath}`
+      : `Android manifest does not exist at ${manifestPath}. Set android.project.appModuleName or android.project.manifestPath to override the default app/src/main/AndroidManifest.xml layout.`
+  )
+
+  return manifestPath
+}
+
+function resolveAppModuleName(
+  androidRoot: string,
+  manifestPath: string,
+  configuredAppModuleName: string | undefined
+): string {
+  if (configuredAppModuleName) {
+    return configuredAppModuleName
+  }
+
+  const relativeManifestPath = path.relative(androidRoot, manifestPath)
+
+  if (relativeManifestPath.startsWith('..') || path.isAbsolute(relativeManifestPath)) {
+    throw new AndroidProjectDiscoveryError(
+      `Android manifest ${manifestPath} is outside Android root ${androidRoot}. Set android.project.appModuleName to identify the app module explicitly.`
+    )
+  }
+
+  const segments = relativeManifestPath.split(path.sep)
+
+  if (
+    segments.length >= 4 &&
+    segments[1] === 'src' &&
+    segments[2] === 'main' &&
+    segments[3] === ANDROID_MANIFEST_FILE_NAME
+  ) {
+    return segments[0]
+  }
+
+  throw new AndroidProjectDiscoveryError(
+    `Could not derive Android app module from manifest path ${manifestPath}. Set android.project.appModuleName explicitly.`
+  )
+}
+
+async function resolveBuildGradlePath(appModuleRoot: string): Promise<string> {
+  const buildGradlePath = path.join(appModuleRoot, 'build.gradle')
+  const buildGradleKtsPath = path.join(appModuleRoot, 'build.gradle.kts')
+  const hasBuildGradle = await pathExists(buildGradlePath)
+  const hasBuildGradleKts = await pathExists(buildGradleKtsPath)
+
+  if (hasBuildGradle && hasBuildGradleKts) {
+    throw new AndroidProjectDiscoveryError(
+      `Android app module has both build.gradle and build.gradle.kts: ${appModuleRoot}. Remove the ambiguity before running voltra apply.`
+    )
+  }
+
+  if (hasBuildGradle) {
+    return buildGradlePath
+  }
+
+  if (hasBuildGradleKts) {
+    return buildGradleKtsPath
+  }
+
+  throw new AndroidProjectDiscoveryError(
+    `Android app module build file does not exist in ${appModuleRoot}. Expected build.gradle or build.gradle.kts.`
+  )
+}
+
+function ensureManifestBelongsToAppModule(appModuleRoot: string, manifestPath: string): void {
+  const relativeManifestPath = path.relative(appModuleRoot, manifestPath)
+
+  if (relativeManifestPath.startsWith('..') || path.isAbsolute(relativeManifestPath)) {
+    throw new AndroidProjectDiscoveryError(
+      `Android manifest ${manifestPath} is outside app module ${appModuleRoot}. Align android.project.appModuleName and android.project.manifestPath so they point at the same module.`
+    )
+  }
+}
+
+async function resolvePackageName(buildGradlePath: string, manifestPath: string): Promise<string> {
+  const buildGradle = stripGradleComments(await fs.readFile(buildGradlePath, 'utf8'))
+  const namespace = matchGradleStringLiteral(buildGradle, 'namespace')
+
+  if (namespace) {
+    return namespace
+  }
+
+  const applicationId = matchGradleStringLiteral(buildGradle, 'applicationId')
+
+  if (applicationId) {
+    return applicationId
+  }
+
+  const manifest = await fs.readFile(manifestPath, 'utf8')
+  const manifestPackage = matchManifestPackage(manifest)
+
+  if (manifestPackage) {
+    return manifestPackage
+  }
+
+  throw new AndroidProjectDiscoveryError(
+    `Could not determine Android package name from ${buildGradlePath} or ${manifestPath}. Set android.project.packageName explicitly or add namespace/applicationId to the app module build file.`
+  )
+}
+
+function matchGradleStringLiteral(content: string, propertyName: string): string | undefined {
+  const match = content.match(new RegExp(`\\b${propertyName}\\s*(?:=)?\\s*['"]([^'"]+)['"]`))
+
+  return match?.[1]
+}
+
+function stripGradleComments(content: string): string {
+  return content.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|\s)\/\/.*$/gm, '$1')
+}
+
+function matchManifestPackage(content: string): string | undefined {
+  const match = content.match(/<manifest\b[^>]*\bpackage\s*=\s*['"]([^'"]+)['"]/)
+
+  return match?.[1]
+}
+
+async function ensureDirectory(dirPath: string, message: string): Promise<void> {
+  const stat = await readPathStat(dirPath)
+
+  if (!stat) {
+    throw new AndroidProjectDiscoveryError(message)
+  }
+
+  if (!stat.isDirectory()) {
+    throw new AndroidProjectDiscoveryError(`Expected a directory but found a file: ${dirPath}`)
+  }
+}
+
+async function ensureFile(filePath: string, message: string): Promise<void> {
+  const stat = await readPathStat(filePath)
+
+  if (!stat) {
+    throw new AndroidProjectDiscoveryError(message)
+  }
+
+  if (!stat.isFile()) {
+    throw new AndroidProjectDiscoveryError(`Expected a file but found a directory: ${filePath}`)
+  }
+}
+
+async function pathExists(targetPath: string): Promise<boolean> {
+  return (await readPathStat(targetPath)) !== undefined
+}
+
+async function readPathStat(targetPath: string): Promise<Stats | undefined> {
+  try {
+    return await fs.stat(targetPath)
+  } catch (error: unknown) {
+    if (isNotFoundError(error)) {
+      return undefined
+    }
+
+    throw error
+  }
+}
+
+function isNotFoundError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && 'code' in error && error.code === 'ENOENT'
+}