voltra 2.0.0 → 2.1.1

package/src/apply/index.ts

@@ -0,0 +1,309 @@
+import path from 'node:path'
+
+import { normalizeRelativePath } from '../fs/path'
+import { loadVoltraConfig } from '../config/load'
+import { normalizeVoltraConfig } from '../config/normalize'
+import { removePathIfExists } from '../fs/readWrite'
+import { ensureGitWorktreeIsReady } from '../git/status'
+import { applyAndroidPlatform, createAndroidPreflightRunner } from '../platforms/android/apply'
+import { applyIOSPlatform, createIOSPreflightRunner } from '../platforms/ios/apply'
+import { renderApplySummary, renderIntro } from '../reporting/clack'
+import { VoltraCliError } from '../reporting/summary'
+import { diffVoltraState } from '../state/diff'
+import { loadVoltraState } from '../state/load'
+import { saveVoltraState } from '../state/save'
+
+import { runApplyPreflight } from './preflight'
+
+import type { NormalizedVoltraConfig, VoltraPlatform } from '../config/types'
+import type { ApplyPreflightResult, ApplyPreflightRunners } from './preflight'
+import type { ReportedChange } from '../reporting/summary'
+import type { VoltraState } from '../state/load'
+
+export interface ApplyOptions {
+  configPath?: string
+  platform?: VoltraPlatform
+  allowDirty?: boolean
+}
+
+export interface ApplyResult {
+  exitCode: number
+  errorMessage?: string
+}
+
+export interface PlatformApplyContext {
+  config: NormalizedVoltraConfig
+  platform: VoltraPlatform
+  preflight: unknown
+  previousState?: VoltraState
+  requestedPlatforms: VoltraPlatform[]
+}
+
+export interface PlatformApplyResult {
+  platform: VoltraPlatform
+  changes: ReportedChange[]
+  generatedFiles: string[]
+  warnings?: string[]
+}
+
+export type PlatformApplyRunner = (context: PlatformApplyContext) => Promise<PlatformApplyResult>
+
+export interface ApplyDependencies {
+  applyRunners: Partial<Record<VoltraPlatform, PlatformApplyRunner>>
+  preflightRunners: ApplyPreflightRunners
+  writeIntro(): Promise<void>
+  writeSummary(summary: { changes: ReportedChange[]; warnings?: string[] }): Promise<void>
+}
+
+const DEFAULT_DEPENDENCIES: ApplyDependencies = {
+  applyRunners: {},
+  preflightRunners: {},
+  async writeIntro() {
+    await renderIntro()
+  },
+  async writeSummary(summary) {
+    await renderApplySummary(summary)
+  },
+}
+
+export async function applyVoltra(options: ApplyOptions): Promise<ApplyResult> {
+  try {
+    await runApplyPipeline(options, DEFAULT_DEPENDENCIES)
+
+    return {
+      exitCode: 0,
+    }
+  } catch (error: unknown) {
+    return {
+      exitCode: 1,
+      errorMessage: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+export async function runApplyPipeline(options: ApplyOptions, dependencies: ApplyDependencies): Promise<void> {
+  const loadedConfig = await loadVoltraConfig({ configPath: options.configPath })
+  const normalizedConfig = normalizeVoltraConfig(loadedConfig)
+  const resolvedDependencies = resolveApplyDependencies(normalizedConfig, dependencies)
+  await resolvedDependencies.writeIntro()
+  await ensureGitWorktreeIsReady({
+    cwd: normalizedConfig.projectRoot,
+    allowDirty: options.allowDirty,
+  })
+  const preflight = await runApplyPreflight(normalizedConfig, resolvedDependencies.preflightRunners, options.platform)
+  const previousState = await loadVoltraState(normalizedConfig.projectRoot)
+  const platformResults = await runPlatformApply(
+    normalizedConfig,
+    preflight,
+    previousState,
+    resolvedDependencies.applyRunners
+  )
+  const nextGeneratedFiles = mergeGeneratedFiles(
+    normalizedConfig,
+    previousState,
+    preflight.requestedPlatforms,
+    platformResults
+  )
+  const stateDiff = diffVoltraState(previousState, nextGeneratedFiles)
+  const deletedChanges = await removeStaleGeneratedFiles(normalizedConfig.projectRoot, stateDiff.staleFiles)
+  await saveVoltraState(normalizedConfig.projectRoot, { files: stateDiff.nextFiles })
+
+  const summaryWarnings = platformResults.flatMap((result) => result.warnings ?? []).filter(isDefined)
+  const summaryChanges = [...platformResults.flatMap((result) => result.changes), ...deletedChanges]
+
+  await resolvedDependencies.writeSummary({ changes: summaryChanges, warnings: summaryWarnings })
+}
+
+function resolveApplyDependencies(config: NormalizedVoltraConfig, dependencies: ApplyDependencies): ApplyDependencies {
+  return {
+    applyRunners: {
+      android: dependencies.applyRunners.android ?? applyAndroidPlatform,
+      ios: dependencies.applyRunners.ios ?? applyIOSPlatform,
+    },
+    preflightRunners: {
+      android:
+        dependencies.preflightRunners.android ?? (config.android ? createAndroidPreflightRunner(config) : undefined),
+      ios: dependencies.preflightRunners.ios ?? (config.ios ? createIOSPreflightRunner(config) : undefined),
+    },
+    writeIntro: dependencies.writeIntro,
+    writeSummary: dependencies.writeSummary,
+  }
+}
+
+function mergeGeneratedFiles(
+  config: NormalizedVoltraConfig,
+  previousState: VoltraState | undefined,
+  requestedPlatforms: VoltraPlatform[],
+  platformResults: PlatformApplyResult[]
+): string[] {
+  const nextGeneratedFilesByPlatform = new Map(
+    platformResults.map((result) => [result.platform, result.generatedFiles] as const)
+  )
+  const mergedFiles = new Set<string>()
+  const platformRoots = getTrackedPlatformRoots(config)
+  const configuredPlatforms = getConfiguredPlatforms(config)
+  const isPartialApply = requestedPlatforms.length < configuredPlatforms.length
+
+  for (const previousFile of previousState?.files ?? []) {
+    const owningPlatform = getTrackedFilePlatform(previousFile, platformRoots)
+
+    if (!owningPlatform) {
+      if (isPartialApply) {
+        mergedFiles.add(previousFile)
+      }
+
+      continue
+    }
+
+    if (requestedPlatforms.includes(owningPlatform)) {
+      continue
+    }
+
+    mergedFiles.add(previousFile)
+  }
+
+  for (const platform of requestedPlatforms) {
+    for (const filePath of nextGeneratedFilesByPlatform.get(platform) ?? []) {
+      mergedFiles.add(filePath)
+    }
+  }
+
+  return [...mergedFiles]
+}
+
+function getTrackedPlatformRoots(config: NormalizedVoltraConfig): Partial<Record<VoltraPlatform, string>> {
+  const projectRoot = config.projectRoot
+  const androidRoot = config.android
+    ? normalizeRelativePath(
+        path.relative(projectRoot, config.android.project.rootDir ?? path.join(projectRoot, 'android'))
+      )
+    : undefined
+  const iosRoot = config.ios
+    ? normalizeRelativePath(path.relative(projectRoot, config.ios.project.rootDir ?? path.join(projectRoot, 'ios')))
+    : undefined
+
+  return {
+    ...(androidRoot ? { android: androidRoot } : {}),
+    ...(iosRoot ? { ios: iosRoot } : {}),
+  }
+}
+
+function getConfiguredPlatforms(config: NormalizedVoltraConfig): VoltraPlatform[] {
+  const platforms: VoltraPlatform[] = []
+
+  if (config.android) {
+    platforms.push('android')
+  }
+
+  if (config.ios) {
+    platforms.push('ios')
+  }
+
+  return platforms
+}
+
+function getTrackedFilePlatform(
+  filePath: string,
+  platformRoots: Partial<Record<VoltraPlatform, string>>
+): VoltraPlatform | undefined {
+  const normalizedFilePath = normalizeRelativePath(filePath)
+
+  for (const platform of ['android', 'ios'] as const) {
+    const root = platformRoots[platform]
+
+    if (!root) {
+      continue
+    }
+
+    if (normalizedFilePath === root || normalizedFilePath.startsWith(`${root}/`)) {
+      return platform
+    }
+  }
+
+  return undefined
+}
+
+async function runPlatformApply(
+  config: NormalizedVoltraConfig,
+  preflight: ApplyPreflightResult,
+  previousState: VoltraState | undefined,
+  applyRunners: Partial<Record<VoltraPlatform, PlatformApplyRunner>>
+): Promise<PlatformApplyResult[]> {
+  const missingRunners = preflight.requestedPlatforms.filter((platform) => !applyRunners[platform])
+
+  if (missingRunners.length > 0) {
+    throw new VoltraCliError(`No apply runner is registered for ${missingRunners.join(', ')}.`)
+  }
+
+  const results: PlatformApplyResult[] = []
+
+  for (const platform of preflight.requestedPlatforms) {
+    const applyRunner = applyRunners[platform]
+
+    if (!applyRunner) {
+      throw new VoltraCliError(`No apply runner is registered for ${platform}.`)
+    }
+
+    let result: PlatformApplyResult
+
+    try {
+      result = await applyRunner({
+        config,
+        platform,
+        preflight: preflight.platformResults[platform],
+        previousState,
+        requestedPlatforms: preflight.requestedPlatforms,
+      })
+    } catch (error: unknown) {
+      throw new VoltraCliError(`Apply failed for ${platform}: ${getApplyRunnerErrorMessage(error)}`)
+    }
+
+    if (result.platform !== platform) {
+      throw new VoltraCliError(
+        `Apply runner returned a mismatched platform result: expected ${platform}, received ${result.platform}.`
+      )
+    }
+
+    results.push(result)
+  }
+
+  return results
+}
+
+async function removeStaleGeneratedFiles(projectRoot: string, staleFiles: string[]): Promise<ReportedChange[]> {
+  const deletedChanges: ReportedChange[] = []
+
+  for (const staleFile of staleFiles) {
+    const staleFilePath = path.join(projectRoot, staleFile)
+    let deleted: boolean
+
+    try {
+      deleted = await removePathIfExists(staleFilePath)
+    } catch (error: unknown) {
+      throw new VoltraCliError(
+        `Failed to remove stale generated file ${staleFile}: ${getApplyRunnerErrorMessage(error)}`
+      )
+    }
+
+    if (deleted) {
+      deletedChanges.push({
+        kind: 'deleted',
+        path: staleFile,
+      })
+    }
+  }
+
+  return deletedChanges
+}
+
+function isDefined<TValue>(value: TValue | undefined): value is TValue {
+  return value !== undefined
+}
+
+function getApplyRunnerErrorMessage(error: unknown): string {
+  if (error instanceof Error && error.message) {
+    return error.message
+  }
+
+  return String(error)
+}

package/src/apply/preflight.ts

@@ -0,0 +1,172 @@
+import { PreflightError } from '../reporting/summary'
+
+import type { NormalizedVoltraConfig, VoltraPlatform } from '../config/types'
+import type { PreflightFailureReport, PreflightIssue } from '../reporting/summary'
+
+export interface PlatformPreflightSuccess<TContext> {
+  platform: VoltraPlatform
+  context: TContext
+}
+
+export interface PlatformPreflightFailure {
+  platform: VoltraPlatform
+  issues: PreflightIssue[]
+}
+
+export type PlatformPreflightResult<TContext> = PlatformPreflightSuccess<TContext> | PlatformPreflightFailure
+
+export interface ApplyPreflightContext {
+  requestedPlatforms: VoltraPlatform[]
+}
+
+export type PlatformPreflightRunner<TContext> = (
+  context: ApplyPreflightContext
+) => Promise<PlatformPreflightResult<TContext>>
+
+export interface ApplyPreflightRunners {
+  android?: PlatformPreflightRunner<unknown>
+  ios?: PlatformPreflightRunner<unknown>
+}
+
+export interface ApplyPreflightResult {
+  requestedPlatforms: VoltraPlatform[]
+  platformResults: Partial<Record<VoltraPlatform, unknown>>
+}
+
+export function getRequestedPlatforms(config: NormalizedVoltraConfig, platform?: VoltraPlatform): VoltraPlatform[] {
+  if (platform) {
+    validateConfiguredPlatform(config, platform)
+    return [platform]
+  }
+
+  const configuredPlatforms = getConfiguredPlatforms(config)
+
+  if (configuredPlatforms.length === 0) {
+    throw new PreflightError({
+      summary: 'No platforms are configured for Voltra apply.',
+      issues: [{ message: 'Add an android or ios config block before running apply.' }],
+    })
+  }
+
+  return configuredPlatforms
+}
+
+export async function runApplyPreflight(
+  config: NormalizedVoltraConfig,
+  runners: ApplyPreflightRunners,
+  platform?: VoltraPlatform
+): Promise<ApplyPreflightResult> {
+  const requestedPlatforms = getRequestedPlatforms(config, platform)
+  const preflightContext: ApplyPreflightContext = { requestedPlatforms }
+  const failures: PlatformPreflightFailure[] = []
+  const platformResults: Partial<Record<VoltraPlatform, unknown>> = {}
+
+  await Promise.all(
+    requestedPlatforms.map(async (requestedPlatform) => {
+      const runner = runners[requestedPlatform]
+
+      if (!runner) {
+        failures.push({
+          platform: requestedPlatform,
+          issues: [{ message: `No preflight runner is registered for ${requestedPlatform}.` }],
+        })
+        return
+      }
+
+      let result: PlatformPreflightResult<unknown>
+
+      try {
+        result = await runner(preflightContext)
+      } catch (error: unknown) {
+        failures.push({
+          platform: requestedPlatform,
+          issues: [{ message: getPreflightRunnerErrorMessage(error) }],
+        })
+        return
+      }
+
+      if ('issues' in result) {
+        failures.push(result)
+        return
+      }
+
+      if (result.platform !== requestedPlatform) {
+        failures.push({
+          platform: requestedPlatform,
+          issues: [{ message: `Preflight runner returned a mismatched platform result: ${result.platform}.` }],
+        })
+        return
+      }
+
+      platformResults[requestedPlatform] = result.context
+    })
+  )
+
+  if (failures.length > 0) {
+    throw new PreflightError(buildPreflightFailureReport(failures))
+  }
+
+  return {
+    requestedPlatforms,
+    platformResults,
+  }
+}
+
+function getConfiguredPlatforms(config: NormalizedVoltraConfig): VoltraPlatform[] {
+  const platforms: VoltraPlatform[] = []
+
+  if (config.android) {
+    platforms.push('android')
+  }
+
+  if (config.ios) {
+    platforms.push('ios')
+  }
+
+  return platforms
+}
+
+function validateConfiguredPlatform(config: NormalizedVoltraConfig, platform: VoltraPlatform): void {
+  if ((platform === 'android' && config.android) || (platform === 'ios' && config.ios)) {
+    return
+  }
+
+  throw new PreflightError({
+    summary: `Requested platform '${platform}' is not configured.`,
+    issues: [{ message: `Add a ${platform} config block or remove --platform ${platform}.` }],
+  })
+}
+
+function buildPreflightFailureReport(failures: PlatformPreflightFailure[]): PreflightFailureReport {
+  const orderedFailures = [...failures].sort((left, right) => comparePlatforms(left.platform, right.platform))
+
+  return {
+    summary: 'Preflight failed before any files were written.',
+    issues: orderedFailures.flatMap((failure) =>
+      failure.issues.map((issue) => ({
+        ...issue,
+        message: `${failure.platform}: ${issue.message}`,
+      }))
+    ),
+  }
+}
+
+function getPreflightRunnerErrorMessage(error: unknown): string {
+  if (error instanceof Error && error.message) {
+    return error.message
+  }
+
+  return String(error)
+}
+
+function comparePlatforms(left: VoltraPlatform, right: VoltraPlatform): number {
+  return getPlatformSortOrder(left) - getPlatformSortOrder(right)
+}
+
+function getPlatformSortOrder(platform: VoltraPlatform): number {
+  if (platform === 'android') {
+    return 0
+  }
+
+  return 1
+}

package/src/bin.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+import { runCli } from './index'
+
+void runCli(process.argv.slice(2))
+  .then((exitCode) => {
+    process.exitCode = exitCode
+  })
+  .catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error)
+
+    process.stderr.write(`${message}\n`)
+    process.exitCode = 1
+  })

package/src/commands/apply.ts

@@ -0,0 +1,114 @@
+import { Command } from 'commander'
+
+import { applyVoltra } from '../apply'
+import { normalizeClackMessage, renderError } from '../reporting/clack'
+
+import type { ApplyOptions } from '../apply'
+import type { VoltraPlatform } from '../config/types'
+
+export const CLI_EXIT_CODE_SUCCESS = 0
+export const CLI_EXIT_CODE_FAILURE = 1
+
+interface ApplyCommandCliOptions {
+  platform?: VoltraPlatform
+  config?: string
+  yes?: boolean
+}
+
+export async function runApplyCommand(argv: string[]): Promise<number> {
+  let exitCode = CLI_EXIT_CODE_SUCCESS
+  const command = createApplyCommand((nextExitCode) => {
+    exitCode = nextExitCode
+  })
+
+  try {
+    await command.parseAsync(argv, { from: 'user' })
+    return exitCode
+  } catch (error) {
+    return await handleCommanderError(error)
+  }
+}
+
+export function createApplyCommand(onComplete?: (exitCode: number) => void): Command {
+  const command = new Command('apply')
+
+  command
+    .description('Apply Voltra changes to the native project')
+    .usage('[options]')
+    .exitOverride()
+    .showHelpAfterError()
+    .showSuggestionAfterError()
+    .option('-p, --platform <platform>', 'limit apply to a single platform', parsePlatform)
+    .option('-c, --config <path>', 'load config from an explicit file path')
+    .option('-y, --yes', 'skip the dirty git worktree confirmation prompt')
+    .action(async () => {
+      const cliOptions = command.opts<ApplyCommandCliOptions>()
+      const options = toApplyOptions(cliOptions)
+      const result = await applyVoltra(options)
+
+      onComplete?.(result.exitCode)
+
+      if (result.exitCode !== CLI_EXIT_CODE_SUCCESS && result.errorMessage) {
+        await renderError(result.errorMessage, { output: process.stderr })
+      }
+    })
+
+  return command
+}
+
+function toApplyOptions(cliOptions: ApplyCommandCliOptions): ApplyOptions {
+  if (cliOptions.config !== undefined && !cliOptions.config.trim()) {
+    throw new Error('--config must be a non-empty path')
+  }
+
+  return {
+    platform: cliOptions.platform,
+    configPath: cliOptions.config,
+    allowDirty: cliOptions.yes,
+  }
+}
+
+function parsePlatform(value: string): VoltraPlatform {
+  if (value === 'android' || value === 'ios') {
+    return value
+  }
+
+  throw new Error(`Invalid platform '${value}'. Expected 'ios' or 'android'.`)
+}
+
+async function handleCommanderError(error: unknown): Promise<number> {
+  if (isCommanderError(error)) {
+    return isCommanderDisplayError(error) ? CLI_EXIT_CODE_SUCCESS : CLI_EXIT_CODE_FAILURE
+  }
+
+  await renderError(formatCommandError(error), { output: process.stderr })
+  return CLI_EXIT_CODE_FAILURE
+}
+
+function isCommanderDisplayError(error: unknown): error is { code: string } {
+  return Boolean(
+    error &&
+      typeof error === 'object' &&
+      'code' in error &&
+      (error.code === 'commander.helpDisplayed' || error.code === 'commander.version')
+  )
+}
+
+function isCommanderError(error: unknown): error is { code: string } {
+  return Boolean(
+    error &&
+      typeof error === 'object' &&
+      'code' in error &&
+      typeof error.code === 'string' &&
+      error.code.startsWith('commander.')
+  )
+}
+
+export function formatCommandError(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error)
+  return normalizeClackMessage(message)
+}
+
+export function getApplyHelpText(): string {
+  return createApplyCommand().helpInformation()
+}

package/src/config/defaults.ts

@@ -0,0 +1,34 @@
+import type { IOSWidgetFamily } from './types'
+
+export const DEFAULT_ANDROID_ENABLE_NOTIFICATIONS = false
+export const DEFAULT_ANDROID_SERVER_UPDATE_INTERVAL_MINUTES = 60
+export const DEFAULT_ANDROID_SERVER_UPDATE_REFRESH = false
+export const DEFAULT_ANDROID_USER_IMAGES_PATH = './assets/voltra-android'
+
+export const DEFAULT_IOS_ENABLE_PUSH_NOTIFICATIONS = false
+export const DEFAULT_IOS_DEPLOYMENT_TARGET = '17.0'
+export const DEFAULT_IOS_SERVER_UPDATE_INTERVAL_MINUTES = 15
+export const DEFAULT_IOS_SERVER_UPDATE_REFRESH = false
+export const DEFAULT_IOS_USER_IMAGES_PATH = './assets/voltra'
+export const DEFAULT_IOS_WIDGET_FAMILIES: IOSWidgetFamily[] = ['systemSmall', 'systemMedium', 'systemLarge']
+
+/**
+ * These defaults intentionally mirror the existing Expo plugin behavior where that behavior is already explicit.
+ * Some values, such as the default iOS widget target name, still depend on native project discovery and app naming.
+ */
+export const CLI_DEFAULTS = {
+  android: {
+    enableNotifications: DEFAULT_ANDROID_ENABLE_NOTIFICATIONS,
+    serverUpdateIntervalMinutes: DEFAULT_ANDROID_SERVER_UPDATE_INTERVAL_MINUTES,
+    serverUpdateRefresh: DEFAULT_ANDROID_SERVER_UPDATE_REFRESH,
+    userImagesPath: DEFAULT_ANDROID_USER_IMAGES_PATH,
+  },
+  ios: {
+    deploymentTarget: DEFAULT_IOS_DEPLOYMENT_TARGET,
+    enablePushNotifications: DEFAULT_IOS_ENABLE_PUSH_NOTIFICATIONS,
+    serverUpdateIntervalMinutes: DEFAULT_IOS_SERVER_UPDATE_INTERVAL_MINUTES,
+    serverUpdateRefresh: DEFAULT_IOS_SERVER_UPDATE_REFRESH,
+    userImagesPath: DEFAULT_IOS_USER_IMAGES_PATH,
+    widgetFamilies: DEFAULT_IOS_WIDGET_FAMILIES,
+  },
+} as const