voltra 2.0.0 → 2.1.0

package/src/platforms/shared/widgetModule.ts

@@ -0,0 +1,153 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import vm from 'node:vm'
+import { createRequire } from 'node:module'
+
+import * as babel from '@babel/core'
+
+const MODULE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '']
+
+export interface WidgetModuleBuildInfo {
+  isDev: false
+  metroUrl: null
+  appVersion: 'unknown'
+  voltraVersion: '1.4.1'
+}
+
+export const DYNAMIC_WIDGET_BUILD_INFO: WidgetModuleBuildInfo = {
+  isDev: false,
+  metroUrl: null,
+  appVersion: 'unknown',
+  voltraVersion: '1.4.1',
+}
+
+export function evaluateWidgetModuleExports(
+  projectRoot: string,
+  filePath: string,
+  createError: (message: string) => Error
+): unknown {
+  const projectRequire = createProjectRequire(projectRoot)
+  const moduleCache = new Map<string, unknown>()
+
+  const customRequire = (moduleSpecifier: string, currentDir: string): unknown => {
+    if (!isLocalModule(moduleSpecifier)) {
+      return projectRequire(moduleSpecifier)
+    }
+
+    const resolvedModulePath = resolveModulePath(moduleSpecifier, currentDir)
+
+    if (!resolvedModulePath) {
+      throw createError(`Cannot resolve module '${moduleSpecifier}' from '${currentDir}'`)
+    }
+
+    const cachedModule = moduleCache.get(resolvedModulePath)
+    if (cachedModule !== undefined) {
+      return cachedModule
+    }
+
+    const transpiledCode = transpileWidgetModule(projectRoot, resolvedModulePath, projectRequire, createError)
+    const moduleDir = path.dirname(resolvedModulePath)
+    const moduleRecord = { exports: {} as Record<string, unknown> }
+    moduleCache.set(resolvedModulePath, moduleRecord.exports)
+
+    const context = vm.createContext({
+      __dirname: moduleDir,
+      __filename: resolvedModulePath,
+      console,
+      exports: moduleRecord.exports,
+      module: moduleRecord,
+      process,
+      require: (specifier: string) => customRequire(specifier, moduleDir),
+    })
+
+    const script = new vm.Script(transpiledCode, { filename: resolvedModulePath })
+    script.runInContext(context)
+
+    moduleCache.set(resolvedModulePath, moduleRecord.exports)
+    return moduleRecord.exports
+  }
+
+  return customRequire(filePath, path.dirname(filePath))
+}
+
+function transpileWidgetModule(
+  projectRoot: string,
+  filePath: string,
+  projectRequire: NodeRequire,
+  createError: (message: string) => Error
+): string {
+  const source = fs.readFileSync(filePath, 'utf8')
+  const projectBabelConfigPath = resolveProjectBabelConfig(projectRoot)
+  const result = babel.transformSync(source, {
+    babelrc: false,
+    configFile: projectBabelConfigPath,
+    cwd: projectRoot,
+    filename: filePath,
+    presets: projectBabelConfigPath ? undefined : [resolveFallbackBabelPreset(projectRequire, createError)],
+  })
+
+  if (!result?.code) {
+    throw createError(`Babel transpilation failed for ${filePath}`)
+  }
+
+  return result.code
+}
+
+function resolveProjectBabelConfig(projectRoot: string): string | undefined {
+  const candidates = ['babel.config.js', 'babel.config.cjs', 'babel.config.mjs']
+
+  for (const candidate of candidates) {
+    const candidatePath = path.join(projectRoot, candidate)
+    if (fs.existsSync(candidatePath)) {
+      return candidatePath
+    }
+  }
+
+  return undefined
+}
+
+function resolveFallbackBabelPreset(projectRequire: NodeRequire, createError: (message: string) => Error): string {
+  try {
+    return projectRequire.resolve('@react-native/babel-preset')
+  } catch {
+    try {
+      return projectRequire.resolve('babel-preset-expo')
+    } catch {
+      throw createError(
+        'Could not resolve a Babel preset for widget evaluation. Add a project babel.config.js or install @react-native/babel-preset.'
+      )
+    }
+  }
+}
+
+function createProjectRequire(projectRoot: string): NodeRequire {
+  return createRequire(path.join(projectRoot, 'package.json'))
+}
+
+function isLocalModule(moduleSpecifier: string): boolean {
+  return moduleSpecifier.startsWith('.') || moduleSpecifier.startsWith('/')
+}
+
+function resolveModulePath(moduleSpecifier: string, fromDir: string): string | null {
+  const basePath = path.resolve(fromDir, moduleSpecifier)
+
+  for (const extension of MODULE_EXTENSIONS) {
+    const candidate = `${basePath}${extension}`
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+      return candidate
+    }
+  }
+
+  if (!fs.existsSync(basePath) || !fs.statSync(basePath).isDirectory()) {
+    return null
+  }
+
+  for (const extension of MODULE_EXTENSIONS) {
+    const indexCandidate = path.join(basePath, `index${extension}`)
+    if (fs.existsSync(indexCandidate) && fs.statSync(indexCandidate).isFile()) {
+      return indexCandidate
+    }
+  }
+
+  return null
+}

package/src/reporting/clack.ts

@@ -0,0 +1,67 @@
+import type { Readable, Writable } from 'node:stream'
+
+import type * as ClackPrompts from '@clack/prompts'
+
+import type { ApplySummary } from './summary'
+
+interface CommonClackOptions {
+  input?: Readable
+  output?: Writable
+}
+
+export async function renderApplySummary(summary: ApplySummary, options?: CommonClackOptions): Promise<void> {
+  const { outro, log } = await loadClackPrompts()
+
+  for (const kind of ['created', 'updated', 'deleted'] as const) {
+    const paths = summary.changes.filter((change) => change.kind === kind).map((change) => change.path)
+
+    for (const filePath of paths) {
+      log.step(`${capitalize(kind)} ${filePath}`, options)
+    }
+  }
+
+  for (const warning of summary.warnings ?? []) {
+    log.warn(normalizeClackMessage(warning), options)
+  }
+
+  outro('Done', options)
+}
+
+export async function renderError(message: string, options?: CommonClackOptions): Promise<void> {
+  const { log } = await loadClackPrompts()
+  log.error(normalizeClackMessage(message), options)
+}
+
+export async function renderWarning(message: string, options?: CommonClackOptions): Promise<void> {
+  const { log } = await loadClackPrompts()
+  log.warn(normalizeClackMessage(message), options)
+}
+
+export async function renderCancelled(options?: CommonClackOptions): Promise<void> {
+  const { cancel } = await loadClackPrompts()
+  cancel('Cancelled.', options)
+}
+
+export async function renderIntro(options?: CommonClackOptions): Promise<void> {
+  const { intro } = await loadClackPrompts()
+  intro('Voltra', options)
+}
+
+export function normalizeClackMessage(message: string): string {
+  return message
+    .split('\n')
+    .map((line) => line.replace(/^\[voltra\]\s*(Warning:\s*|Error:\s*|Preflight:\s*)?/, ''))
+    .join('\n')
+}
+
+function capitalize(value: string): string {
+  return value.charAt(0).toUpperCase() + value.slice(1)
+}
+
+function loadClackPrompts() {
+  const dynamicImport = new Function('specifier', 'return import(specifier)') as (
+    specifier: string
+  ) => Promise<typeof ClackPrompts>
+
+  return dynamicImport('@clack/prompts')
+}

package/src/reporting/summary.ts

@@ -0,0 +1,116 @@
+const PREFIX = '[voltra]'
+
+export type ReportedChangeKind = 'created' | 'updated' | 'deleted'
+
+export interface ReportedChange {
+  kind: ReportedChangeKind
+  path: string
+}
+
+export interface ApplySummary {
+  changes: ReportedChange[]
+  warnings?: string[]
+}
+
+export interface PreflightIssue {
+  message: string
+  path?: string
+}
+
+export interface PreflightFailureReport {
+  summary?: string
+  issues: PreflightIssue[]
+}
+
+export class VoltraCliError extends Error {
+  readonly code: string
+
+  constructor(message: string, code = 'VOLTRA_CLI_ERROR') {
+    super(message)
+    this.name = 'VoltraCliError'
+    this.code = code
+  }
+}
+
+export class PreflightError extends VoltraCliError {
+  readonly report: PreflightFailureReport
+
+  constructor(report: PreflightFailureReport) {
+    super(formatPreflightFailure(report), 'VOLTRA_PREFLIGHT_FAILED')
+    this.name = 'PreflightError'
+    this.report = report
+  }
+}
+
+export function formatApplySummary(summary: ApplySummary): string {
+  const lines = [
+    `${PREFIX} Apply summary`,
+    `${PREFIX} Created: ${countChanges(summary.changes, 'created')}`,
+    `${PREFIX} Updated: ${countChanges(summary.changes, 'updated')}`,
+    `${PREFIX} Deleted: ${countChanges(summary.changes, 'deleted')}`,
+  ]
+
+  for (const kind of ['created', 'updated', 'deleted'] as const) {
+    const paths = summary.changes.filter((change) => change.kind === kind).map((change) => change.path)
+
+    for (const filePath of paths) {
+      lines.push(`${PREFIX} ${capitalize(kind)} ${filePath}`)
+    }
+  }
+
+  for (const warning of summary.warnings ?? []) {
+    lines.push(formatWarning(warning))
+  }
+
+  return lines.join('\n')
+}
+
+export function formatDirtyWorktreeWarning(changeCount?: number): string {
+  if (!changeCount || changeCount <= 0) {
+    return `${PREFIX} Warning: git worktree has uncommitted changes.`
+  }
+
+  const noun = changeCount === 1 ? 'change' : 'changes'
+  return `${PREFIX} Warning: git worktree has ${changeCount} uncommitted ${noun}.`
+}
+
+export function formatAmbiguousDiscoveryWarning(subject: string, candidates: string[]): string {
+  if (candidates.length === 0) {
+    return `${PREFIX} Warning: ${subject} is ambiguous.`
+  }
+
+  return `${PREFIX} Warning: ${subject} is ambiguous. Candidates: ${candidates.join(', ')}`
+}
+
+export function formatWarning(message: string): string {
+  return `${PREFIX} Warning: ${message}`
+}
+
+export function formatError(message: string): string {
+  return `${PREFIX} Error: ${message}`
+}
+
+export function formatPreflightFailure(report: PreflightFailureReport): string {
+  const lines = [
+    report.summary ? formatError(report.summary) : formatError('Preflight failed.'),
+    ...report.issues.map((issue) => formatPreflightIssue(issue)),
+  ]
+
+  return lines.join('\n')
+}
+
+function formatPreflightIssue(issue: PreflightIssue): string {
+  if (!issue.path) {
+    return `${PREFIX} Preflight: ${issue.message}`
+  }
+
+  return `${PREFIX} Preflight: ${issue.path}: ${issue.message}`
+}
+
+function countChanges(changes: ReportedChange[], kind: ReportedChangeKind): number {
+  return changes.filter((change) => change.kind === kind).length
+}
+
+function capitalize(value: string): string {
+  return value.charAt(0).toUpperCase() + value.slice(1)
+}

package/src/state/diff.ts

@@ -0,0 +1,21 @@
+import { normalizeTrackedStateFiles, normalizeTrackedStateFilesForDiff } from './files'
+
+import type { VoltraState } from './load'
+
+export interface VoltraStateDiff {
+  previousFiles: string[]
+  nextFiles: string[]
+  staleFiles: string[]
+}
+
+export function diffVoltraState(previousState: VoltraState | undefined, nextFiles: string[]): VoltraStateDiff {
+  const previousFiles = normalizeTrackedStateFilesForDiff(previousState?.files)
+  const normalizedNextFiles = normalizeTrackedStateFiles(nextFiles, 'Next Voltra state files')
+  const nextFileSet = new Set(normalizedNextFiles)
+
+  return {
+    previousFiles,
+    nextFiles: normalizedNextFiles,
+    staleFiles: previousFiles.filter((filePath) => !nextFileSet.has(filePath)),
+  }
+}

package/src/state/files.ts

@@ -0,0 +1,52 @@
+import path from 'node:path'
+
+import { normalizeRelativePath } from '../fs/path'
+import { VoltraCliError } from '../reporting/summary'
+
+export function normalizeTrackedStateFiles(files: string[] | unknown[], errorContext: string): string[] {
+  if (!Array.isArray(files)) {
+    throw new VoltraCliError(`${errorContext} must be an array.`)
+  }
+
+  const seen = new Set<string>()
+  const normalizedFiles: string[] = []
+
+  for (const filePath of files) {
+    if (typeof filePath !== 'string' || !filePath.trim()) {
+      throw new VoltraCliError(`${errorContext} must contain only non-empty relative paths.`)
+    }
+
+    const normalizedFilePath = normalizeTrackedStateFilePath(filePath)
+
+    if (path.isAbsolute(normalizedFilePath)) {
+      throw new VoltraCliError(`${errorContext} must contain only project-relative paths.`)
+    }
+
+    if (seen.has(normalizedFilePath)) {
+      continue
+    }
+
+    seen.add(normalizedFilePath)
+    normalizedFiles.push(normalizedFilePath)
+  }
+
+  return normalizedFiles.sort((left, right) => left.localeCompare(right))
+}
+
+function normalizeTrackedStateFilePath(filePath: string): string {
+  const normalizedFilePath = normalizeRelativePath(path.posix.normalize(filePath))
+
+  if (normalizedFilePath === '..' || normalizedFilePath.startsWith('../')) {
+    throw new VoltraCliError('Voltra state files must contain only project-relative paths.')
+  }
+
+  return normalizedFilePath
+}
+
+export function normalizeTrackedStateFilesForDiff(files: string[] | undefined): string[] {
+  if (!files || files.length === 0) {
+    return []
+  }
+
+  return normalizeTrackedStateFiles(files, 'Voltra state files')
+}

package/src/state/load.ts

@@ -0,0 +1,66 @@
+import path from 'node:path'
+
+import { pathExists, readJsonFile } from '../fs/readWrite'
+import { VoltraCliError } from '../reporting/summary'
+
+import { normalizeTrackedStateFiles } from './files'
+
+const STATE_SCHEMA_VERSION = 1
+const STATE_DIRECTORY_NAME = '.voltra'
+const STATE_FILE_NAME = 'state.json'
+
+export interface VoltraState {
+  schemaVersion: 1
+  files: string[]
+}
+
+interface RawVoltraState {
+  schemaVersion?: unknown
+  files?: unknown
+}
+
+export async function loadVoltraState(projectRoot: string): Promise<VoltraState | undefined> {
+  const statePath = getVoltraStatePath(projectRoot)
+
+  if (!(await pathExists(statePath))) {
+    return undefined
+  }
+
+  let rawState: RawVoltraState
+
+  try {
+    rawState = await readJsonFile<RawVoltraState>(statePath)
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new VoltraCliError(`Failed to read Voltra state at ${statePath}: ${message}`)
+  }
+
+  return validateVoltraState(rawState, statePath)
+}
+
+export function getVoltraStatePath(projectRoot: string): string {
+  return path.join(projectRoot, STATE_DIRECTORY_NAME, STATE_FILE_NAME)
+}
+
+function validateVoltraState(rawState: RawVoltraState, statePath: string): VoltraState {
+  if (!rawState || typeof rawState !== 'object' || Array.isArray(rawState)) {
+    throw new VoltraCliError(`Voltra state at ${statePath} must be a JSON object.`)
+  }
+
+  if (rawState.schemaVersion !== STATE_SCHEMA_VERSION) {
+    throw new VoltraCliError(
+      `Unsupported Voltra state schema at ${statePath}: expected ${STATE_SCHEMA_VERSION}, received ${String(
+        rawState.schemaVersion
+      )}.`
+    )
+  }
+
+  if (!Array.isArray(rawState.files)) {
+    throw new VoltraCliError(`Voltra state at ${statePath} must contain a files array.`)
+  }
+
+  return {
+    schemaVersion: STATE_SCHEMA_VERSION,
+    files: normalizeTrackedStateFiles(rawState.files, `Voltra state at ${statePath} files`),
+  }
+}

package/src/state/save.ts

@@ -0,0 +1,31 @@
+import { writeJsonFile } from '../fs/readWrite'
+import { VoltraCliError } from '../reporting/summary'
+
+import { normalizeTrackedStateFiles } from './files'
+import { getVoltraStatePath } from './load'
+
+import type { VoltraState } from './load'
+
+const STATE_SCHEMA_VERSION = 1
+
+export interface SaveVoltraStateInput {
+  files: string[]
+}
+
+export async function saveVoltraState(projectRoot: string, input: SaveVoltraStateInput): Promise<VoltraState> {
+  const state: VoltraState = {
+    schemaVersion: STATE_SCHEMA_VERSION,
+    files: normalizeTrackedStateFiles(input.files, 'Voltra state files'),
+  }
+
+  const statePath = getVoltraStatePath(projectRoot)
+
+  try {
+    await writeJsonFile(statePath, state)
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new VoltraCliError(`Failed to write Voltra state at ${statePath}: ${message}`)
+  }
+
+  return state
+}

package/src/xml2js.d.ts

@@ -0,0 +1,23 @@
+declare module 'xml2js' {
+  export interface ParserOptions {
+    explicitArray?: boolean
+    explicitChildren?: boolean
+    preserveChildrenOrder?: boolean
+  }
+
+  export interface BuilderOptions {
+    headless?: boolean
+    renderOpts?: {
+      pretty?: boolean
+      indent?: string
+      newline?: string
+    }
+  }
+
+  export class Builder {
+    constructor(options?: BuilderOptions)
+    buildObject(rootObj: unknown): string
+  }
+
+  export function parseStringPromise(value: string, options?: ParserOptions): Promise<unknown>
+}