voltra 2.0.0 → 2.1.1

package/src/git/status.ts

@@ -0,0 +1,205 @@
+import { execFile } from 'node:child_process'
+import type { Readable, Writable } from 'node:stream'
+import { promisify } from 'node:util'
+
+import { renderCancelled, renderWarning } from '../reporting/clack'
+import { formatDirtyWorktreeWarning, VoltraCliError } from '../reporting/summary'
+
+import type * as ClackPrompts from '@clack/prompts'
+
+const execFileAsync = promisify(execFile)
+
+const GIT_NOT_REPOSITORY_EXIT_CODE = 128
+export interface GitWorktreeStatus {
+  isGitRepository: boolean
+  isDirty: boolean
+  repoRoot?: string
+  entries: string[]
+}
+
+export interface EnsureGitWorktreeOptions {
+  cwd: string
+  interactive?: boolean
+  allowDirty?: boolean
+  stdin?: Readable & { isTTY?: boolean }
+  stdout?: Writable & { isTTY?: boolean }
+}
+
+export interface EnsureGitWorktreeResult {
+  status: GitWorktreeStatus
+  warning?: string
+}
+
+interface ExecGitOptions {
+  cwd: string
+}
+
+class GitCommandError extends VoltraCliError {
+  readonly args: string[]
+  readonly exitCode?: number
+  readonly stderr?: string
+
+  constructor(args: string[], cause: unknown) {
+    const message = cause instanceof Error ? cause.message : String(cause)
+    super(`Failed to run git ${args.join(' ')}: ${message}`)
+    this.name = 'GitCommandError'
+    this.args = args
+    this.exitCode = getExecExitCode(cause)
+    this.stderr = getExecStderr(cause)
+  }
+}
+
+export async function getGitWorktreeStatus(cwd: string): Promise<GitWorktreeStatus> {
+  const insideWorktree = await runGitCommand(['rev-parse', '--is-inside-work-tree'], { cwd }).catch(
+    (error: unknown) => {
+      if (isNotGitRepositoryError(error)) {
+        return undefined
+      }
+
+      throw error
+    }
+  )
+
+  if (!insideWorktree || insideWorktree.trim() !== 'true') {
+    return {
+      isGitRepository: false,
+      isDirty: false,
+      entries: [],
+    }
+  }
+
+  const [repoRootOutput, statusOutput] = await Promise.all([
+    runGitCommand(['rev-parse', '--show-toplevel'], { cwd }),
+    runGitCommand(['status', '--short', '--untracked-files=normal'], { cwd }),
+  ])
+
+  const entries = splitGitStatusEntries(statusOutput)
+
+  return {
+    isGitRepository: true,
+    isDirty: entries.length > 0,
+    repoRoot: repoRootOutput.trim(),
+    entries,
+  }
+}
+
+export async function ensureGitWorktreeIsReady(options: EnsureGitWorktreeOptions): Promise<EnsureGitWorktreeResult> {
+  const status = await getGitWorktreeStatus(options.cwd)
+
+  if (!status.isGitRepository || !status.isDirty) {
+    return { status }
+  }
+
+  const warning = formatDirtyWorktreeWarning(status.entries.length)
+
+  if (options.allowDirty) {
+    return { status, warning }
+  }
+
+  if (!isInteractiveSession(options)) {
+    throw new VoltraCliError(`${warning} Re-run interactively to confirm before applying changes.`)
+  }
+
+  const confirmed = await promptForDirtyWorktreeConfirmation(options)
+
+  if (!confirmed) {
+    throw new VoltraCliError('Aborted because the git worktree has uncommitted changes.')
+  }
+
+  return { status, warning }
+}
+
+async function runGitCommand(args: string[], options: ExecGitOptions): Promise<string> {
+  try {
+    const result = await execFileAsync('git', args, {
+      cwd: options.cwd,
+      encoding: 'utf8',
+    })
+
+    return result.stdout
+  } catch (error: unknown) {
+    throw new GitCommandError(args, error)
+  }
+}
+
+function isNotGitRepositoryError(error: unknown): boolean {
+  if (!(error instanceof GitCommandError)) {
+    return false
+  }
+
+  return (
+    error.args.join(' ') === 'rev-parse --is-inside-work-tree' &&
+    error.exitCode === GIT_NOT_REPOSITORY_EXIT_CODE &&
+    typeof error.stderr === 'string' &&
+    error.stderr.toLowerCase().includes('not a git repository')
+  )
+}
+
+function getExecExitCode(error: unknown): number | undefined {
+  if (!(error instanceof Error) || !('code' in error)) {
+    return undefined
+  }
+
+  const code = error.code
+
+  return typeof code === 'number' ? code : undefined
+}
+
+function getExecStderr(error: unknown): string | undefined {
+  if (!(error instanceof Error) || !('stderr' in error)) {
+    return undefined
+  }
+
+  const stderr = error.stderr
+
+  return typeof stderr === 'string' ? stderr : undefined
+}
+
+function splitGitStatusEntries(output: string): string[] {
+  return output
+    .split(/\r?\n/)
+    .map((entry) => entry.trimEnd())
+    .filter((entry) => entry.length > 0)
+}
+
+function isInteractiveSession(options: EnsureGitWorktreeOptions): boolean {
+  if (options.interactive !== undefined) {
+    return options.interactive
+  }
+
+  const stdin = options.stdin ?? process.stdin
+  const stdout = options.stdout ?? process.stdout
+
+  return Boolean(stdin.isTTY && stdout.isTTY)
+}
+
+async function promptForDirtyWorktreeConfirmation(options: EnsureGitWorktreeOptions): Promise<boolean> {
+  const stdin = options.stdin ?? process.stdin
+  const stdout = options.stdout ?? process.stdout
+  const promptMessage = 'You have uncommitted changes. Are you sure you want to continue?'
+  const { confirm, isCancel } = await loadClackPrompts()
+
+  await renderWarning(promptMessage, { input: stdin, output: stdout })
+
+  const response = await confirm({
+    message: 'Continue?',
+    initialValue: false,
+    input: stdin,
+    output: stdout,
+  })
+
+  if (isCancel(response)) {
+    await renderCancelled({ input: stdin, output: stdout })
+    return false
+  }
+
+  return response === true
+}
+
+function loadClackPrompts() {
+  const dynamicImport = new Function('specifier', 'return import(specifier)') as (
+    specifier: string
+  ) => Promise<typeof ClackPrompts>
+
+  return dynamicImport('@clack/prompts')
+}

package/src/index.ts

@@ -0,0 +1,204 @@
+import { Command } from 'commander'
+
+import { CLI_EXIT_CODE_FAILURE, CLI_EXIT_CODE_SUCCESS, createApplyCommand, formatCommandError } from './commands/apply'
+import { renderError } from './reporting/clack'
+
+function createProgram(): Command {
+  const program = new Command()
+  let exitCode = CLI_EXIT_CODE_SUCCESS
+
+  program
+    .name('voltra')
+    .description('Apply Voltra to native React Native projects')
+    .exitOverride()
+    .showHelpAfterError()
+    .showSuggestionAfterError()
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Examples:',
+        '  voltra apply',
+        '  voltra apply --platform ios',
+        '  voltra apply --config ./voltra.config.ts --yes',
+      ].join('\n')
+    )
+
+  program.addCommand(
+    createApplyCommand((nextExitCode) => {
+      exitCode = nextExitCode
+    })
+  )
+
+  program.hook('postAction', () => {
+    program.setOptionValue('exitCode', exitCode)
+  })
+
+  return program
+}
+
+export async function runCli(argv: string[]): Promise<number> {
+  const program = createProgram()
+
+  try {
+    await program.parseAsync(['node', 'voltra', ...argv], { from: 'node' })
+    return program.getOptionValue('exitCode') ?? CLI_EXIT_CODE_SUCCESS
+  } catch (error) {
+    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 { applyVoltra, runApplyPipeline } from './apply'
+export type {
+  ApplyDependencies,
+  ApplyOptions,
+  ApplyResult,
+  PlatformApplyContext,
+  PlatformApplyResult,
+  PlatformApplyRunner,
+} from './apply'
+export { getRequestedPlatforms, runApplyPreflight } from './apply/preflight'
+export type {
+  ApplyPreflightContext,
+  ApplyPreflightResult,
+  ApplyPreflightRunners,
+  PlatformPreflightFailure,
+  PlatformPreflightResult,
+  PlatformPreflightRunner,
+  PlatformPreflightSuccess,
+} from './apply/preflight'
+export { CLI_EXIT_CODE_FAILURE, CLI_EXIT_CODE_SUCCESS, getApplyHelpText, runApplyCommand } from './commands/apply'
+
+export { CLI_DEFAULTS } from './config/defaults'
+export { VoltraConfigLoadError, loadVoltraConfig } from './config/load'
+export { VoltraConfigNormalizationError, normalizeVoltraConfig } from './config/normalize'
+export { AndroidProjectDiscoveryError, discoverAndroidProject } from './discovery/android'
+export type { AndroidProjectDiscovery } from './discovery/android'
+export { IOSProjectDiscoveryError, discoverIOSProject } from './discovery/ios'
+export type { IOSProjectDiscovery } from './discovery/ios'
+export { ensureGitWorktreeIsReady, getGitWorktreeStatus } from './git/status'
+export type { EnsureGitWorktreeOptions, EnsureGitWorktreeResult, GitWorktreeStatus } from './git/status'
+export { AndroidGeneratedFilesError, generateAndroidFiles } from './platforms/android/generated'
+export type { GenerateAndroidFilesOptions, GenerateAndroidFilesResult } from './platforms/android/generated'
+export { applyAndroidPlatform, createAndroidPreflightRunner } from './platforms/android/apply'
+export { addDynamicWidgetBundlingSnippet, ensureAndroidGradleWidgetBundling } from './platforms/android/gradle'
+export type {
+  EnsureAndroidGradleWidgetBundlingOptions,
+  EnsureAndroidGradleWidgetBundlingResult,
+} from './platforms/android/gradle'
+export { AndroidManifestMutationError, ensureAndroidManifest } from './platforms/android/manifest'
+export type { EnsureAndroidManifestOptions, EnsureAndroidManifestResult } from './platforms/android/manifest'
+export { IOSGeneratedFilesError, generateIOSFiles } from './platforms/ios/generated'
+export type { GenerateIOSFilesOptions, GenerateIOSFilesResult } from './platforms/ios/generated'
+export { resolveIOSWidgetTargetName } from './platforms/ios/targetName'
+export { IOSWidgetTargetMutationError, ensureIOSWidgetTarget } from './platforms/ios/xcodeTarget'
+export { applyIOSPlatform, createIOSPreflightRunner } from './platforms/ios/apply'
+export { IOSEntitlementsMutationError, ensureEntitlements } from './platforms/ios/entitlements'
+export type { EnsureEntitlementsOptions, EnsureEntitlementsResult } from './platforms/ios/entitlements'
+export { IOSInfoPlistMutationError, ensureInfoPlist } from './platforms/ios/plist'
+export type { EnsureInfoPlistOptions, EnsureInfoPlistResult } from './platforms/ios/plist'
+export { IOSPodfileMutationError, ensurePodfileBlock } from './platforms/ios/podfile'
+export type { EnsurePodfileBlockOptions, EnsurePodfileBlockResult } from './platforms/ios/podfile'
+export type { EnsureIOSWidgetTargetOptions, EnsureIOSWidgetTargetResult } from './platforms/ios/xcodeTarget'
+export {
+  ensureFrameworksGroup,
+  ensureMainGroupChild,
+  ensureProductsGroup,
+  getApplicationTargets,
+  getTargetBuildConfigurations,
+  getTargetBuildPhases,
+  IOSXcodeProjectError,
+  openIOSXcodeProject,
+  saveIOSXcodeProject,
+} from './platforms/ios/xcode'
+export type {
+  IOSXcodeProjectContext,
+  IOSXcodeTargetBuildConfigurations,
+  IOSXcodeTargetBuildPhases,
+  IOSXcodeTargetContext,
+} from './platforms/ios/xcode'
+export { diffVoltraState } from './state/diff'
+export { getVoltraStatePath, loadVoltraState } from './state/load'
+export { saveVoltraState } from './state/save'
+export {
+  normalizeClackMessage,
+  renderApplySummary,
+  renderCancelled,
+  renderError,
+  renderWarning,
+} from './reporting/clack'
+export type { VoltraStateDiff } from './state/diff'
+export type { SaveVoltraStateInput } from './state/save'
+export type { VoltraState } from './state/load'
+export {
+  formatAmbiguousDiscoveryWarning,
+  formatApplySummary,
+  formatDirtyWorktreeWarning,
+  formatError,
+  formatPreflightFailure,
+  formatWarning,
+  PreflightError,
+  VoltraCliError,
+} from './reporting/summary'
+export type {
+  AndroidProjectOverrides,
+  AndroidWidgetAppIntentConfig,
+  AndroidWidgetAppIntentParameter,
+  AndroidWidgetConfig,
+  AndroidWidgetServerUpdateConfig,
+  CliDefaults,
+  IOSProjectOverrides,
+  IOSWidgetAppIntentConfig,
+  IOSWidgetAppIntentParameter,
+  IOSWidgetConfig,
+  IOSWidgetFamily,
+  IOSWidgetServerUpdateConfig,
+  LoadedVoltraConfig,
+  NormalizedAndroidProjectConfig,
+  NormalizedAndroidWidgetConfig,
+  NormalizedAndroidWidgetServerUpdateConfig,
+  NormalizedIOSProjectConfig,
+  NormalizedIOSWidgetConfig,
+  NormalizedIOSWidgetServerUpdateConfig,
+  NormalizedVoltraAndroidConfig,
+  NormalizedVoltraConfig,
+  NormalizedVoltraIOSConfig,
+  VoltraAndroidConfig,
+  VoltraConfig,
+  VoltraIOSConfig,
+  VoltraPlatform,
+  WidgetInitialStatePath,
+  WidgetLabel,
+  WidgetLocalizedValue,
+} from './config/types'
+export type {
+  ApplySummary,
+  PreflightFailureReport,
+  PreflightIssue,
+  ReportedChange,
+  ReportedChangeKind,
+} from './reporting/summary'

package/src/platforms/android/apply.ts

@@ -0,0 +1,106 @@
+import { discoverAndroidProject } from '../../discovery/android'
+import { getMissingPlatformPackageMessage, getMissingPlatformPackages } from '../../dependencies/platformPackages'
+import { VoltraCliError } from '../../reporting/summary'
+
+import { ensureAndroidManifest } from './manifest'
+import { ensureAndroidGradleWidgetBundling } from './gradle'
+import { generateAndroidFiles } from './generated'
+
+import type { NormalizedVoltraConfig } from '../../config/types'
+import type { AndroidProjectDiscovery } from '../../discovery/android'
+import type { PlatformApplyContext, PlatformApplyResult } from '../../apply'
+import type { ApplyPreflightContext, PlatformPreflightResult, PlatformPreflightRunner } from '../../apply/preflight'
+
+export function createAndroidPreflightRunner(
+  config: NormalizedVoltraConfig
+): PlatformPreflightRunner<AndroidProjectDiscovery> {
+  return async (_context: ApplyPreflightContext): Promise<PlatformPreflightResult<AndroidProjectDiscovery>> => {
+    const androidConfig = config.android
+
+    if (!androidConfig) {
+      return {
+        platform: 'android',
+        issues: [{ message: 'Android config is missing.' }],
+      }
+    }
+
+    const missingPackages = getMissingPlatformPackages(config.projectRoot, 'android')
+
+    if (missingPackages.length > 0) {
+      return {
+        platform: 'android',
+        issues: [{ message: getMissingPlatformPackageMessage('android', missingPackages) }],
+      }
+    }
+
+    return {
+      platform: 'android',
+      context: await discoverAndroidProject(config.projectRoot, androidConfig.project),
+    }
+  }
+}
+
+export async function applyAndroidPlatform(context: PlatformApplyContext): Promise<PlatformApplyResult> {
+  if (context.platform !== 'android') {
+    throw new VoltraCliError(`Android apply runner received unexpected platform: ${context.platform}.`)
+  }
+
+  const androidConfig = context.config.android
+
+  if (!androidConfig) {
+    throw new VoltraCliError('Android config is missing.')
+  }
+
+  const discovery = getAndroidDiscovery(context.preflight)
+  const generatedResult = await generateAndroidFiles({
+    projectRoot: context.config.projectRoot,
+    android: androidConfig,
+    discovery,
+  })
+  const manifestResult = await ensureAndroidManifest({
+    projectRoot: context.config.projectRoot,
+    android: androidConfig,
+    discovery,
+  })
+  const gradleResult = await ensureAndroidGradleWidgetBundling({
+    projectRoot: context.config.projectRoot,
+    discovery,
+    hasDynamicWidgets: androidConfig.widgets.some((widget) => widget.entry !== undefined),
+  })
+
+  return {
+    platform: 'android',
+    changes: [manifestResult.change, gradleResult.change, ...generatedResult.changes].filter(isDefined),
+    generatedFiles: generatedResult.files,
+    warnings: [...generatedResult.warnings, ...(gradleResult.warnings ?? [])],
+  }
+}
+
+function getAndroidDiscovery(value: unknown): AndroidProjectDiscovery {
+  if (!isAndroidProjectDiscovery(value)) {
+    throw new VoltraCliError('Android preflight did not provide a valid discovery result.')
+  }
+
+  return value
+}
+
+function isAndroidProjectDiscovery(value: unknown): value is AndroidProjectDiscovery {
+  if (!value || typeof value !== 'object') {
+    return false
+  }
+
+  const candidate = value as Partial<AndroidProjectDiscovery>
+
+  return [
+    candidate.androidRoot,
+    candidate.appModuleName,
+    candidate.appModuleRoot,
+    candidate.manifestPath,
+    candidate.buildGradlePath,
+    candidate.packageName,
+  ].every((entry) => typeof entry === 'string' && entry.length > 0)
+}
+
+function isDefined<TValue>(value: TValue | undefined): value is TValue {
+  return value !== undefined
+}