voltra 2.2.0 → 2.3.0

package/src/config/serverUpdate.ts

@@ -0,0 +1,160 @@
+/**
+ * Config rules for `serverUpdate`, shared by the Expo plugins and the `voltra` CLI.
+ *
+ * `serverUpdate` marks a widget as server-driven for both render engines. On a widget with
+ * `entry` the device fetches a JSON object and hands it to the bundled JS as props; without
+ * `entry` the server returns a full Voltra payload. Widgets without `entry` keep exactly the
+ * rules they had before ADR 0002, so no existing config breaks.
+ *
+ * `url` is optional. `serverUpdate: {}` means "server-driven, URL supplied at runtime" through
+ * `setWidgetServerUpdate`, which covers per-tenant backends whose URL is only known after login.
+ *
+ * These helpers report problems instead of throwing so each caller can raise its own error type.
+ *
+ * The `@use-voltra/expo-plugin` package holds the other copy of this module, shared by the
+ * Expo config plugins; keep the two in sync.
+ */
+
+/**
+ * Interval floor and default for a widget with `entry`. WorkManager cannot run periodic work
+ * more often than every 15 minutes, and WidgetKit stretches timelines requested closer together
+ * than five minutes, so a smaller number would only mislead.
+ */
+export const DYNAMIC_WIDGET_SERVER_UPDATE_INTERVAL_MINUTES = 15
+
+/** Hosts allowed over plain `http`, for talking to a dev server from a simulator or emulator. */
+const LOCAL_HTTP_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '10.0.2.2', '10.0.3.2'])
+
+/** Outcome of resolving `serverUpdate.intervalMinutes` against a platform's floor. */
+export type ServerUpdateIntervalResolution =
+  | { kind: 'ok'; intervalMinutes: number }
+  | { kind: 'clamped'; intervalMinutes: number; warning: string }
+  | { kind: 'invalid'; error: string }
+
+export interface ResolveServerUpdateIntervalOptions {
+  /** Raw `intervalMinutes` from app.json, if the widget set one. */
+  intervalMinutes: unknown
+  /** Config path used in messages, e.g. `android.widgets[portfolio].serverUpdate`. */
+  context: string
+  /** True when the widget has an `entry` and therefore renders on device. */
+  hasEntry: boolean
+  /** Interval used when the widget does not set one. Ignored for widgets with `entry`. */
+  defaultIntervalMinutes: number
+  /** Platform floor for payload widgets. Ignored for widgets with `entry`. */
+  minimumIntervalMinutes: number
+}
+
+/**
+ * Resolves the interval a widget should be scheduled on.
+ *
+ * A widget with `entry` is clamped up to {@link DYNAMIC_WIDGET_SERVER_UPDATE_INTERVAL_MINUTES}
+ * with a warning, because a shorter interval is not something either platform can honour. A
+ * payload widget keeps the platform's existing rule and is rejected below the floor.
+ */
+export function resolveServerUpdateInterval(
+  options: ResolveServerUpdateIntervalOptions
+): ServerUpdateIntervalResolution {
+  const { intervalMinutes, context, hasEntry, defaultIntervalMinutes, minimumIntervalMinutes } = options
+  const fallback = hasEntry ? DYNAMIC_WIDGET_SERVER_UPDATE_INTERVAL_MINUTES : defaultIntervalMinutes
+
+  if (intervalMinutes === undefined) {
+    return { kind: 'ok', intervalMinutes: fallback }
+  }
+
+  if (typeof intervalMinutes !== 'number' || !Number.isFinite(intervalMinutes)) {
+    return { kind: 'invalid', error: `${context}.intervalMinutes must be a number` }
+  }
+
+  if (!Number.isInteger(intervalMinutes)) {
+    return { kind: 'invalid', error: `${context}.intervalMinutes must be an integer` }
+  }
+
+  if (hasEntry) {
+    if (intervalMinutes < DYNAMIC_WIDGET_SERVER_UPDATE_INTERVAL_MINUTES) {
+      return {
+        kind: 'clamped',
+        intervalMinutes: DYNAMIC_WIDGET_SERVER_UPDATE_INTERVAL_MINUTES,
+        warning:
+          `${context}.intervalMinutes is ${intervalMinutes}, below the ` +
+          `${DYNAMIC_WIDGET_SERVER_UPDATE_INTERVAL_MINUTES} minute floor for widgets with an entry. ` +
+          `Using ${DYNAMIC_WIDGET_SERVER_UPDATE_INTERVAL_MINUTES}.`,
+      }
+    }
+
+    return { kind: 'ok', intervalMinutes }
+  }
+
+  if (intervalMinutes < minimumIntervalMinutes) {
+    return { kind: 'invalid', error: `${context}.intervalMinutes must be at least ${minimumIntervalMinutes}` }
+  }
+
+  return { kind: 'ok', intervalMinutes }
+}
+
+/** Outcome of checking `serverUpdate.url`. */
+export type ServerUpdateUrlResolution =
+  | { kind: 'ok' }
+  | { kind: 'insecure'; warning: string }
+  | { kind: 'invalid'; error: string }
+
+/**
+ * Checks `serverUpdate.url`. An absent URL is fine — the app supplies it at runtime through
+ * `setWidgetServerUpdate`.
+ *
+ * A URL that is not an absolute `http`/`https` URL is rejected: no platform HTTP stack here
+ * accepts one, so such a config could only ever have failed to fetch. Plain `http` to a
+ * non-local host is reported as insecure rather than rejected — App Transport Security and
+ * Android's cleartext policy already block it in a release build, and rejecting it outright
+ * would break configs that point at a LAN dev server.
+ */
+export function resolveServerUpdateUrl(url: unknown, context: string): ServerUpdateUrlResolution {
+  if (url === undefined) {
+    return { kind: 'ok' }
+  }
+
+  if (typeof url !== 'string' || !url.trim()) {
+    return { kind: 'invalid', error: `${context}.url must be a non-empty string` }
+  }
+
+  let parsed: URL
+
+  try {
+    parsed = new URL(url)
+  } catch {
+    return { kind: 'invalid', error: `${context}.url must be an absolute http(s) URL, received '${url}'` }
+  }
+
+  if (parsed.protocol === 'https:') {
+    return { kind: 'ok' }
+  }
+
+  if (parsed.protocol !== 'http:') {
+    return { kind: 'invalid', error: `${context}.url must be an absolute http(s) URL, received '${url}'` }
+  }
+
+  if (isLocalHttpHost(parsed.hostname)) {
+    return { kind: 'ok' }
+  }
+
+  return {
+    kind: 'insecure',
+    warning:
+      `${context}.url uses plain http ('${url}'). Release builds block cleartext traffic, so the ` +
+      'widget will not fetch outside a development build. Use https, or a local dev host ' +
+      `(${[...LOCAL_HTTP_HOSTS].join(', ')}).`,
+  }
+}
+
+/** True for the hosts Voltra allows over plain `http` — dev servers reachable from a simulator. */
+export function isLocalHttpHost(hostname: string): boolean {
+  return LOCAL_HTTP_HOSTS.has(hostname.replace(/^\[|\]$/g, ''))
+}
+
+/** Validates `serverUpdate.refresh`. Returns an error message, or `undefined` when it is fine. */
+export function validateServerUpdateRefresh(refresh: unknown, context: string): string | undefined {
+  if (refresh !== undefined && typeof refresh !== 'boolean') {
+    return `${context}.refresh must be a boolean`
+  }
+
+  return undefined
+}

package/src/config/types.ts

@@ -1,4 +1,5 @@
 import type { CLI_DEFAULTS } from './defaults'
+import type { PerConfiguration } from './perConfiguration'
 
 export type VoltraPlatform = 'android' | 'ios'
 
@@ -15,8 +16,11 @@ export type WidgetLabel = string | WidgetLocalizedValue
 export type WidgetInitialStatePath = string | WidgetLocalizedValue
 
 export interface AndroidWidgetServerUpdateConfig {
-  /** Server endpoint that returns widget state updates. */
-  url: string
+  /**
+   * Server endpoint that returns widget state updates. Optional — omit it to mark the widget
+   * server-driven and supply the URL at runtime with `setWidgetServerUpdate`.
+   */
+  url?: string
   /** Refresh interval, in minutes, for fetching server updates. */
   intervalMinutes?: number
   /** Whether fetched updates should trigger an immediate widget refresh. */
@@ -44,14 +48,32 @@ export interface AndroidWidgetConfig {
   displayName: WidgetLabel
   /** User-facing widget description shown by the launcher. */
   description: WidgetLabel
-  /** Minimum widget width in dp. */
+  /** Minimum widget width in dp. Only affects Android 11 and older. */
   minWidth?: number
-  /** Minimum widget height in dp. */
+  /** Minimum widget height in dp. Only affects Android 11 and older. */
   minHeight?: number
-  /** Minimum widget width in launcher grid cells. */
+  /**
+   * Minimum widget width in launcher grid cells.
+   *
+   * @deprecated Use `minWidth` instead. The value is approximated in dp for Android 11 and
+   * older.
+   */
   minCellWidth?: number
-  /** Minimum widget height in launcher grid cells. */
+  /**
+   * Minimum widget height in launcher grid cells.
+   *
+   * @deprecated Use `minHeight` instead. The value is approximated in dp for Android 11 and
+   * older.
+   */
   minCellHeight?: number
+  /** Minimum width, in dp, the widget can be resized down to. */
+  minResizeWidth?: number
+  /** Minimum height, in dp, the widget can be resized down to. */
+  minResizeHeight?: number
+  /** Maximum width, in dp, the widget can be resized up to. Honoured on Android 12 and newer. */
+  maxResizeWidth?: number
+  /** Maximum height, in dp, the widget can be resized up to. Honoured on Android 12 and newer. */
+  maxResizeHeight?: number
   /** Default widget width in launcher grid cells. */
   targetCellWidth: number
   /** Default widget height in launcher grid cells. */
@@ -84,8 +106,11 @@ export type IOSWidgetFamily =
   | 'accessoryInline'
 
 export interface IOSWidgetServerUpdateConfig {
-  /** Server endpoint that returns widget state updates. */
-  url: string
+  /**
+   * Server endpoint that returns widget state updates. Optional — omit it to mark the widget
+   * server-driven and supply the URL at runtime with `setWidgetServerUpdate`.
+   */
+  url?: string
   /** Refresh interval, in minutes, for fetching server updates. */
   intervalMinutes?: number
   /** Whether fetched updates should trigger an immediate widget refresh. */
@@ -109,6 +134,12 @@ export interface IOSWidgetAppIntentConfig {
 export interface IOSWidgetConfig {
   /** Stable widget identifier used in generated files and registrations. */
   id: string
+  /**
+   * WidgetKit `kind` of the generated widget. Defaults to `Voltra_Widget_<id>`.
+   * Pin it to the kind of a pre-Voltra widget so already placed instances survive the migration
+   * (WidgetKit identifies a placed widget by extension bundle id + kind).
+   */
+  kind?: string
   /** User-facing widget name shown in iOS widget configuration UI. */
   displayName: WidgetLabel
   /** User-facing widget description shown in iOS widget configuration UI. */
@@ -145,8 +176,11 @@ export interface IOSProjectOverrides {
   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 main app entitlements file, or one path per Xcode build configuration
+   * name when each environment has its own.
+   */
+  entitlementsPath?: PerConfiguration<string>
   /** Explicit path to the Podfile. */
   podfilePath?: string
 }
@@ -175,8 +209,11 @@ export interface VoltraAndroidConfig {
 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
+  /**
+   * App Group identifier used to share data between the app and widget extension, or one per Xcode
+   * build configuration name when each environment has its own.
+   */
+  groupIdentifier?: PerConfiguration<string>
   /** iOS widgets to generate and register. */
   widgets?: IOSWidgetConfig[]
   /** Minimum iOS deployment target for generated widget targets. */
@@ -187,8 +224,11 @@ export interface VoltraIOSConfig {
   fonts?: string[]
   /** Directory containing user-provided images for iOS widgets. */
   userImagesPath?: string
-  /** Keychain access group shared by the app and extension. */
-  keychainGroup?: string
+  /**
+   * Keychain access group shared by the app and extension, or one per Xcode build configuration
+   * name when each environment has its own.
+   */
+  keychainGroup?: PerConfiguration<string>
   /** Native iOS project discovery overrides. */
   project?: IOSProjectOverrides
 }
@@ -211,28 +251,27 @@ export interface LoadedVoltraConfig {
   configDir: string
 }
 
-export interface NormalizedAndroidWidgetServerUpdateConfig {
-  /** Server endpoint that returns widget state updates. */
-  url: string
+/**
+ * Build-time server-update defaults after normalization. The device treats these as the lowest
+ * settings layer; `setWidgetServerUpdate` overrides `url` and `intervalMinutes` at runtime.
+ */
+export interface NormalizedWidgetServerUpdateConfig {
+  /** Server endpoint, when app.json set one. Absent means "URL supplied at runtime". */
+  url?: string
   /** Refresh interval, in minutes, for fetching server updates. */
   intervalMinutes: number
-  /** Whether fetched updates should trigger an immediate widget refresh. */
+  /** Whether the widget draws a refresh button. Build-time only: it is generated UI structure. */
   refresh: boolean
 }
 
+export type NormalizedAndroidWidgetServerUpdateConfig = NormalizedWidgetServerUpdateConfig
+
 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 type NormalizedIOSWidgetServerUpdateConfig = NormalizedWidgetServerUpdateConfig
 
 export interface NormalizedIOSWidgetConfig extends Omit<IOSWidgetConfig, 'serverUpdate' | 'supportedFamilies'> {
   /** Supported iOS widget families after defaults have been applied. */
@@ -261,8 +300,8 @@ export interface NormalizedIOSProjectConfig {
   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 entitlements file, or one per build configuration name, if overridden. */
+  entitlementsPath?: PerConfiguration<string>
   /** Absolute path to the Podfile, if overridden. */
   podfilePath?: string
 }
@@ -284,7 +323,7 @@ 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
+  groupIdentifier?: PerConfiguration<string>
   /** iOS widgets after validation and normalization. */
   widgets: NormalizedIOSWidgetConfig[]
   /** Effective iOS deployment target for generated widget targets. */
@@ -296,11 +335,37 @@ export interface NormalizedVoltraIOSConfig {
   /** Absolute path to the iOS user images directory. */
   userImagesPath: string
   /** Keychain access group shared by the app and extension. */
-  keychainGroup?: string
+  keychainGroup?: PerConfiguration<string>
   /** Normalized iOS native project discovery overrides. */
   project: NormalizedIOSProjectConfig
 }
 
+/**
+ * iOS project overrides after per-build-configuration values have been resolved against the Xcode
+ * project.
+ */
+export type ResolvedIOSProjectConfig = Omit<NormalizedIOSProjectConfig, 'entitlementsPath'> & {
+  /** Absolute path to the entitlements file of the default build configuration, if overridden. */
+  entitlementsPath?: string
+}
+
+/**
+ * iOS config as the platform mutators consume it: every per-build-configuration value has been
+ * collapsed to a single string, either the configured value or a reference to a build setting
+ * Voltra writes per build configuration.
+ */
+export type ResolvedVoltraIOSConfig = Omit<
+  NormalizedVoltraIOSConfig,
+  'groupIdentifier' | 'keychainGroup' | 'project'
+> & {
+  /** App Group identifier used to share data between the app and extension. */
+  groupIdentifier?: string
+  /** Keychain access group shared by the app and extension. */
+  keychainGroup?: string
+  /** Resolved iOS native project discovery overrides. */
+  project: ResolvedIOSProjectConfig
+}
+
 export interface NormalizedVoltraConfig {
   /** Absolute path to the loaded config file, when the config came from a file. */
   configPath?: string
@@ -312,6 +377,8 @@ export interface NormalizedVoltraConfig {
   android?: NormalizedVoltraAndroidConfig
   /** Normalized iOS-specific Voltra configuration. */
   ios?: NormalizedVoltraIOSConfig
+  /** Non-fatal config problems, surfaced in the `voltra apply` summary. */
+  warnings?: string[]
 }
 
 export type CliDefaults = typeof CLI_DEFAULTS

package/src/config/widgetKind.node.test.ts

@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict'
+import { describe, test } from 'node:test'
+
+import { iosWidgetKind, iosWidgetKindOverrides } from './widgetKind.ts'
+
+describe('iosWidgetKind', () => {
+  test('defaults to the prefixed widget id', () => {
+    assert.equal(iosWidgetKind({ id: 'weather' }), 'Voltra_Widget_weather')
+  })
+
+  test('uses the pinned kind when the widget has one', () => {
+    assert.equal(iosWidgetKind({ id: 'streak', kind: 'StreakWidget' }), 'StreakWidget')
+  })
+})
+
+describe('iosWidgetKindOverrides', () => {
+  test('is undefined when no widget pins a kind, so the Info.plist key stays absent', () => {
+    assert.equal(iosWidgetKindOverrides([{ id: 'weather' }, { id: 'streak' }]), undefined)
+    assert.equal(iosWidgetKindOverrides([]), undefined)
+  })
+
+  test('maps only the widgets that pin a kind', () => {
+    const overrides = iosWidgetKindOverrides([{ id: 'weather' }, { id: 'streak', kind: 'StreakWidget' }])
+
+    assert.deepEqual(overrides, { streak: 'StreakWidget' })
+  })
+})

package/src/config/widgetKind.ts

@@ -0,0 +1,27 @@
+import type { IOSWidgetConfig } from './types'
+
+/** Default prefix of a widget's WidgetKit `kind`: `Voltra_Widget_<id>`. Mirrors `VoltraStorageKeys.widgetKindPrefix`. */
+export const IOS_WIDGET_KIND_PREFIX = 'Voltra_Widget_'
+
+/** WidgetKit `kind` of a widget: the `kind` option when set, else `Voltra_Widget_<id>`. */
+export function iosWidgetKind(widget: Pick<IOSWidgetConfig, 'id' | 'kind'>): string {
+  return widget.kind ?? `${IOS_WIDGET_KIND_PREFIX}${widget.id}`
+}
+
+/**
+ * `{ id: kind }` for the widgets that pin a custom `kind`, or undefined when none does.
+ * Written to both Info.plists (`Voltra_WidgetKinds`) so native code maps ids to kinds and back.
+ */
+export function iosWidgetKindOverrides(
+  widgets: Pick<IOSWidgetConfig, 'id' | 'kind'>[]
+): Record<string, string> | undefined {
+  const overrides: Record<string, string> = {}
+
+  for (const widget of widgets) {
+    if (widget.kind !== undefined) {
+      overrides[widget.id] = widget.kind
+    }
+  }
+
+  return Object.keys(overrides).length > 0 ? overrides : undefined
+}

package/src/dependencies/platformPackages.ts

@@ -36,6 +36,17 @@ export function requirePlatformPackage<TPackage>(projectRoot: string, platform:
   return createProjectRequire(projectRoot)(getPlatformPackageName(platform)) as TPackage
 }
 
+export function getPlatformClientPackageVersion(projectRoot: string, platform: VoltraPlatform): string {
+  const packageName = getPlatformClientPackageName(platform)
+  const manifest = createProjectRequire(projectRoot)(`${packageName}/package.json`) as { version?: unknown }
+
+  if (typeof manifest.version !== 'string' || manifest.version.length === 0) {
+    throw new Error(`Package ${packageName} does not declare a valid version.`)
+  }
+
+  return manifest.version
+}
+
 export function getMissingPlatformPackageMessage(
   platform: VoltraPlatform,
   packageNames = getRequiredPlatformPackageNames(platform)