create-visualbuild-app 0.1.0 → 1.0.0

package/visual-app-builder/shared/npmBuildCommand.d.mts

@@ -0,0 +1,17 @@
+export interface NpmBuildCommand {
+  executable: string
+  args: string[]
+}
+
+export interface NpmBuildCommandEnvironment {
+  npm_execpath?: string
+  ComSpec?: string
+  COMSPEC?: string
+  [key: string]: string | undefined
+}
+
+export function resolveNpmBuildCommand(options?: {
+  platform?: NodeJS.Platform
+  env?: NpmBuildCommandEnvironment
+  nodeExecutable?: string
+}): NpmBuildCommand

package/visual-app-builder/shared/npmBuildCommand.mjs

@@ -0,0 +1,26 @@
+export function resolveNpmBuildCommand({
+  platform = process.platform,
+  env = process.env,
+  nodeExecutable = process.execPath,
+} = {}) {
+  const npmCliPath = String(env.npm_execpath ?? '').trim()
+
+  if (npmCliPath) {
+    return {
+      executable: nodeExecutable,
+      args: [npmCliPath, 'run', 'build'],
+    }
+  }
+
+  if (platform === 'win32') {
+    return {
+      executable: env.ComSpec || env.COMSPEC || 'cmd.exe',
+      args: ['/d', '/s', '/c', 'npm.cmd run build'],
+    }
+  }
+
+  return {
+    executable: 'npm',
+    args: ['run', 'build'],
+  }
+}

package/visual-app-builder/shared/syncCustomComponentSource.d.mts

@@ -0,0 +1,13 @@
+export interface CustomComponentRootSettings {
+  name: string
+  rootTag?: string
+  id?: unknown
+  className?: unknown
+  attributes?: unknown
+  children?: unknown[]
+}
+
+export function syncCustomComponentRoot(
+  source: string,
+  settings: CustomComponentRootSettings
+): string

package/visual-app-builder/shared/syncCustomComponentSource.mjs

@@ -0,0 +1,345 @@
+import { generate } from '@babel/generator'
+import { parse } from '@babel/parser'
+import * as t from '@babel/types'
+
+const allowedRootTags = new Set([
+  'div',
+  'section',
+  'main',
+  'article',
+  'aside',
+  'header',
+  'footer',
+  'nav',
+  'form',
+])
+
+export function syncCustomComponentRoot(source, settings) {
+  const ast = parse(source, {
+    sourceType: 'module',
+    plugins: ['jsx', 'typescript'],
+  })
+  const root = findReturnedJsxElement(ast.program)
+
+  if (!root) {
+    throw new Error(
+      `Registered component "${settings.name}" must return one JSX element`
+    )
+  }
+
+  const rootTag = allowedRootTags.has(String(settings.rootTag))
+    ? String(settings.rootTag)
+    : 'div'
+  const additionalAttributes =
+    settings.attributes &&
+    typeof settings.attributes === 'object' &&
+    !Array.isArray(settings.attributes)
+      ? settings.attributes
+      : {}
+  const serializedAttributes = Object.entries(additionalAttributes).filter(
+    ([name, value]) =>
+      isSafeJsxAttributeName(name) &&
+      !['children', 'key', 'ref', 'id', 'className'].includes(name) &&
+      isSerializableAttributeValue(value)
+  )
+  const id = settings.id ? String(settings.id) : undefined
+  const className = settings.className
+    ? String(settings.className)
+    : undefined
+
+  if (
+    !Array.isArray(settings.children) &&
+    rootMatchesSettings(
+      root,
+      rootTag,
+      id,
+      className,
+      serializedAttributes
+    )
+  ) {
+    return source
+  }
+
+  root.openingElement.name = t.jsxIdentifier(rootTag)
+
+  if (root.closingElement) {
+    root.closingElement.name = t.jsxIdentifier(rootTag)
+  }
+
+  const managedNames = new Set([
+    'id',
+    'className',
+    ...Object.keys(additionalAttributes),
+  ])
+  const preservedAttributes = root.openingElement.attributes.filter(
+    (attribute) =>
+      attribute.type === 'JSXSpreadAttribute' ||
+      !managedNames.has(attribute.name.name)
+  )
+  const nextAttributes = [
+    id ? createAttribute('id', id) : null,
+    className ? createAttribute('className', className) : null,
+    ...serializedAttributes
+      .map(([name, value]) => createAttribute(name, value)),
+  ].filter(Boolean)
+
+  root.openingElement.attributes = [
+    ...nextAttributes,
+    ...preservedAttributes,
+  ]
+
+  if (Array.isArray(settings.children)) {
+    const children = settings.children
+      .map((child) => createVisualChild(child))
+      .filter(Boolean)
+    root.children =
+      children.length > 0 ? withLineBreaks(children, 1) : []
+  }
+
+  return `${generate(ast, {
+    comments: true,
+    compact: false,
+    jsescOption: { minimal: true },
+  }).code}\n`
+}
+
+function createVisualChild(rawNode) {
+  if (!rawNode || typeof rawNode !== 'object') return null
+
+  if (rawNode.type === '__visualbuild_children_slot__') {
+    return t.jsxExpressionContainer(t.identifier('children'))
+  }
+
+  const tagName = String(rawNode.type ?? 'div')
+
+  if (!/^[A-Za-z_$][A-Za-z0-9_$.-]*$/.test(tagName)) {
+    return null
+  }
+
+  const props =
+    rawNode.props && typeof rawNode.props === 'object'
+      ? rawNode.props
+      : {}
+  const attributeEntries = Object.entries(props).filter(
+    ([name, value]) =>
+      ![
+        'text',
+        'wrapperTag',
+        'componentTree',
+        'attributes',
+      ].includes(name) &&
+      value !== undefined &&
+      value !== '' &&
+      isSafeJsxAttributeName(name) &&
+      isSerializableAttributeValue(value)
+  )
+  const additionalAttributes =
+    props.attributes &&
+    typeof props.attributes === 'object' &&
+    !Array.isArray(props.attributes)
+      ? Object.entries(props.attributes).filter(
+          ([name, value]) =>
+            isSafeJsxAttributeName(name) &&
+            isSerializableAttributeValue(value)
+        )
+      : []
+  const attributes = [...attributeEntries, ...additionalAttributes].map(
+    ([name, value]) => createAttribute(name, value)
+  )
+  const isVoid = ['br', 'hr', 'img', 'input', 'source', 'col'].includes(
+    tagName
+  )
+  const opening = t.jsxOpeningElement(
+    t.jsxIdentifier(tagName),
+    attributes,
+    isVoid
+  )
+
+  if (isVoid) {
+    return t.jsxElement(opening, null, [], true)
+  }
+
+  const nestedChildren = Array.isArray(rawNode.children)
+    ? rawNode.children.map(createVisualChild).filter(Boolean)
+    : []
+  const text = String(props.text ?? '')
+
+  if (nestedChildren.length === 0 && text) {
+    nestedChildren.push(t.jsxText(text))
+  }
+
+  return t.jsxElement(
+    opening,
+    t.jsxClosingElement(t.jsxIdentifier(tagName)),
+    nestedChildren.length > 0
+      ? withLineBreaks(nestedChildren, 2)
+      : [],
+    false
+  )
+}
+
+function withLineBreaks(children, depth) {
+  const childIndent = '  '.repeat(depth)
+  const closingIndent = '  '.repeat(Math.max(0, depth - 1))
+
+  return [
+    t.jsxText(`\n${childIndent}`),
+    ...children.flatMap((child, index) => [
+      child,
+      t.jsxText(
+        index === children.length - 1
+          ? `\n${closingIndent}`
+          : `\n${childIndent}`
+      ),
+    ]),
+  ]
+}
+
+function rootMatchesSettings(
+  root,
+  rootTag,
+  id,
+  className,
+  additionalAttributes
+) {
+  if (
+    root.openingElement.name.type !== 'JSXIdentifier' ||
+    root.openingElement.name.name !== rootTag
+  ) {
+    return false
+  }
+
+  const attributes = root.openingElement.attributes
+
+  return (
+    attributeMatches(attributes, 'id', id) &&
+    attributeMatches(attributes, 'className', className) &&
+    additionalAttributes.every(([name, value]) =>
+      attributeMatches(attributes, name, value)
+    )
+  )
+}
+
+function attributeMatches(attributes, name, expected) {
+  const attribute = attributes.find(
+    (candidate) =>
+      candidate.type === 'JSXAttribute' &&
+      candidate.name.type === 'JSXIdentifier' &&
+      candidate.name.name === name
+  )
+
+  if (expected === undefined) {
+    return attribute === undefined
+  }
+
+  if (!attribute) return false
+  return JSON.stringify(readAttributeValue(attribute)) === JSON.stringify(expected)
+}
+
+function readAttributeValue(attribute) {
+  if (!attribute.value) return true
+  if (attribute.value.type === 'StringLiteral') {
+    return attribute.value.value
+  }
+  if (attribute.value.type !== 'JSXExpressionContainer') {
+    return undefined
+  }
+
+  return readExpressionValue(attribute.value.expression)
+}
+
+function readExpressionValue(expression) {
+  if (
+    expression.type === 'StringLiteral' ||
+    expression.type === 'NumericLiteral' ||
+    expression.type === 'BooleanLiteral'
+  ) {
+    return expression.value
+  }
+  if (expression.type === 'ArrayExpression') {
+    return expression.elements.map((element) =>
+      element ? readExpressionValue(element) : null
+    )
+  }
+
+  return undefined
+}
+
+function findReturnedJsxElement(program) {
+  let result = null
+
+  const visit = (value) => {
+    if (result || !value || typeof value !== 'object') return
+
+    if (value.type === 'ReturnStatement') {
+      const argument = unwrapExpression(value.argument)
+      if (argument?.type === 'JSXElement') {
+        result = argument
+        return
+      }
+    }
+
+    if (
+      value.type === 'ArrowFunctionExpression' &&
+      unwrapExpression(value.body)?.type === 'JSXElement'
+    ) {
+      result = unwrapExpression(value.body)
+      return
+    }
+
+    for (const child of Object.values(value)) {
+      if (Array.isArray(child)) {
+        child.forEach(visit)
+      } else {
+        visit(child)
+      }
+    }
+  }
+
+  visit(program)
+  return result
+}
+
+function unwrapExpression(value) {
+  if (
+    value &&
+    [
+      'ParenthesizedExpression',
+      'TSAsExpression',
+      'TSTypeAssertion',
+      'TSSatisfiesExpression',
+    ].includes(value.type)
+  ) {
+    return unwrapExpression(value.expression)
+  }
+  return value
+}
+
+function createAttribute(name, value) {
+  return t.jsxAttribute(
+    t.jsxIdentifier(name),
+    t.jsxExpressionContainer(toExpression(value))
+  )
+}
+
+function toExpression(value) {
+  if (typeof value === 'number') return t.numericLiteral(value)
+  if (typeof value === 'boolean') return t.booleanLiteral(value)
+  if (Array.isArray(value)) {
+    return t.arrayExpression(value.map(toExpression))
+  }
+  return t.stringLiteral(String(value))
+}
+
+function isSafeJsxAttributeName(name) {
+  return /^[A-Za-z_:][A-Za-z0-9_.:-]*$/.test(name)
+}
+
+function isSerializableAttributeValue(value) {
+  return (
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean' ||
+    Array.isArray(value)
+  )
+}

package/visual-app-builder/shared/vercelDeployment.d.mts

@@ -0,0 +1,31 @@
+export interface StaticDeploymentFile {
+  file: string
+  data: Buffer
+  sha: string
+  size: number
+}
+
+export interface VercelDeploymentResult {
+  id: string
+  url: string
+  inspectorUrl?: string
+  readyState: 'READY'
+  fileCount: number
+  totalBytes: number
+}
+
+export function validateVercelProjectName(value: unknown): string
+export function validateVercelTeamId(value: unknown): string | undefined
+export function collectStaticDeploymentFiles(
+  outputRoot: string
+): Promise<StaticDeploymentFile[]>
+export function deployStaticOutputToVercel(options: {
+  outputRoot: string
+  token: string
+  projectName: string
+  teamId?: string
+  fetchImpl?: typeof fetch
+  pollIntervalMs?: number
+  maxPolls?: number
+  wait?: (milliseconds: number) => Promise<unknown>
+}): Promise<VercelDeploymentResult>

package/visual-app-builder/shared/vercelDeployment.mjs

@@ -0,0 +1,266 @@
+import { createHash } from 'node:crypto'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+const vercelApiBase = 'https://api.vercel.com'
+const forbiddenDeploymentSegments = new Set([
+  '.git',
+  '.vercel',
+  'node_modules',
+  'visual-app-builder',
+  'visual-builder',
+  'visualbuild',
+])
+const terminalDeploymentStates = new Set(['READY', 'ERROR', 'CANCELED'])
+
+export function validateVercelProjectName(value) {
+  const projectName = String(value ?? '').trim().toLowerCase()
+
+  if (
+    !projectName ||
+    projectName.length > 100 ||
+    !/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/.test(projectName) ||
+    projectName.includes('---')
+  ) {
+    throw new Error(
+      'Vercel project name must use lowercase letters, numbers, dots, underscores, or hyphens'
+    )
+  }
+
+  return projectName
+}
+
+export function validateVercelTeamId(value) {
+  const teamId = String(value ?? '').trim()
+
+  if (!teamId) return undefined
+  if (!/^team_[A-Za-z0-9]+$/.test(teamId)) {
+    throw new Error('Vercel Team ID must start with "team_"')
+  }
+
+  return teamId
+}
+
+export async function collectStaticDeploymentFiles(outputRoot) {
+  const absoluteRoot = path.resolve(outputRoot)
+  const rootStats = await fs.stat(absoluteRoot).catch(() => null)
+
+  if (!rootStats?.isDirectory()) {
+    throw new Error('The app build did not create its deployment output folder')
+  }
+
+  const files = []
+
+  async function visit(directoryPath, relativeDirectory = '') {
+    const entries = await fs.readdir(directoryPath, { withFileTypes: true })
+
+    for (const entry of entries.sort((first, second) =>
+      first.name.localeCompare(second.name)
+    )) {
+      const relativePath = relativeDirectory
+        ? `${relativeDirectory}/${entry.name}`
+        : entry.name
+      const absolutePath = path.join(directoryPath, entry.name)
+
+      assertProductionPath(relativePath)
+
+      if (entry.isSymbolicLink()) {
+        throw new Error(
+          `Deployment output cannot contain symbolic links (${relativePath})`
+        )
+      }
+
+      if (entry.isDirectory()) {
+        await visit(absolutePath, relativePath)
+        continue
+      }
+
+      if (!entry.isFile()) continue
+
+      const data = await fs.readFile(absolutePath)
+      files.push({
+        file: relativePath,
+        data,
+        sha: createHash('sha1').update(data).digest('hex'),
+        size: data.byteLength,
+      })
+    }
+  }
+
+  await visit(absoluteRoot)
+
+  if (!files.some(({ file }) => file === 'index.html')) {
+    throw new Error('Deployment output must contain an index.html file')
+  }
+
+  if (!files.some(({ file }) => file === 'vercel.json')) {
+    const data = Buffer.from(
+      `${JSON.stringify(
+        {
+          version: 2,
+          routes: [
+            { handle: 'filesystem' },
+            { src: '/.*', dest: '/index.html' },
+          ],
+        },
+        null,
+        2
+      )}\n`
+    )
+    files.push({
+      file: 'vercel.json',
+      data,
+      sha: createHash('sha1').update(data).digest('hex'),
+      size: data.byteLength,
+    })
+  }
+
+  return files.sort((first, second) => first.file.localeCompare(second.file))
+}
+
+export async function deployStaticOutputToVercel({
+  outputRoot,
+  token,
+  projectName,
+  teamId,
+  fetchImpl = fetch,
+  pollIntervalMs = 1500,
+  maxPolls = 200,
+  wait = (milliseconds) =>
+    new Promise((resolve) => setTimeout(resolve, milliseconds)),
+}) {
+  const accessToken = String(token ?? '').trim()
+
+  if (!accessToken) {
+    throw new Error(
+      'Set VERCEL_TOKEN in the visual-builder terminal, then restart the builder'
+    )
+  }
+
+  const name = validateVercelProjectName(projectName)
+  const scope = validateVercelTeamId(teamId)
+  const files = await collectStaticDeploymentFiles(outputRoot)
+  const query = scope ? `?teamId=${encodeURIComponent(scope)}` : ''
+  const authorization = `Bearer ${accessToken}`
+
+  for (const file of files) {
+    const response = await fetchImpl(`${vercelApiBase}/v2/files${query}`, {
+      method: 'POST',
+      headers: {
+        Authorization: authorization,
+        'Content-Type': 'application/octet-stream',
+        'Content-Length': String(file.size),
+        'x-vercel-digest': file.sha,
+      },
+      body: file.data,
+    })
+
+    if (!response.ok) {
+      throw await createVercelApiError(response, `upload ${file.file}`)
+    }
+  }
+
+  const deploymentResponse = await fetchImpl(
+    `${vercelApiBase}/v13/deployments${query}`,
+    {
+      method: 'POST',
+      headers: {
+        Authorization: authorization,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        name,
+        target: 'production',
+        files: files.map(({ file, sha, size }) => ({ file, sha, size })),
+        projectSettings: {
+          framework: null,
+        },
+      }),
+    }
+  )
+
+  if (!deploymentResponse.ok) {
+    throw await createVercelApiError(deploymentResponse, 'create deployment')
+  }
+
+  let deployment = await deploymentResponse.json()
+  const deploymentId = deployment.id ?? deployment.uid
+  const initialInspectorUrl = deployment.inspectorUrl
+
+  if (!deploymentId || !deployment.url) {
+    throw new Error('Vercel returned an incomplete deployment response')
+  }
+
+  for (let attempt = 0; attempt < maxPolls; attempt += 1) {
+    const state = String(
+      deployment.readyState ?? deployment.status ?? deployment.state ?? ''
+    ).toUpperCase()
+
+    if (terminalDeploymentStates.has(state)) {
+      if (state !== 'READY') {
+        throw new Error(
+          `Vercel deployment ${state.toLowerCase()}. Open the deployment inspector for build details.`
+        )
+      }
+
+      return {
+        id: deploymentId,
+        url: normalizeDeploymentUrl(deployment.url),
+        inspectorUrl: deployment.inspectorUrl ?? initialInspectorUrl,
+        readyState: state,
+        fileCount: files.length,
+        totalBytes: files.reduce((total, file) => total + file.size, 0),
+      }
+    }
+
+    await wait(pollIntervalMs)
+    const statusResponse = await fetchImpl(
+      `${vercelApiBase}/v13/deployments/${encodeURIComponent(deploymentId)}${query}`,
+      {
+        headers: { Authorization: authorization },
+      }
+    )
+
+    if (!statusResponse.ok) {
+      throw await createVercelApiError(statusResponse, 'read deployment status')
+    }
+    deployment = await statusResponse.json()
+  }
+
+  throw new Error(
+    'Vercel is still building. Open the deployment dashboard to follow its status.'
+  )
+}
+
+function assertProductionPath(relativePath) {
+  const normalized = relativePath.replace(/\\/g, '/')
+  const segments = normalized.split('/')
+
+  if (
+    normalized.startsWith('/') ||
+    segments.some(
+      (segment) =>
+        segment === '..' || forbiddenDeploymentSegments.has(segment.toLowerCase())
+    ) ||
+    /^visualbuild\.config\.[cm]?[jt]s$/i.test(path.posix.basename(normalized))
+  ) {
+    throw new Error(
+      `Builder-only path cannot enter a production deployment (${relativePath})`
+    )
+  }
+}
+
+async function createVercelApiError(response, operation) {
+  const payload = await response.json().catch(() => null)
+  const message = payload?.error?.message ?? payload?.message
+
+  return new Error(
+    message
+      ? `Vercel could not ${operation}: ${message}`
+      : `Vercel could not ${operation} (HTTP ${response.status})`
+  )
+}
+
+function normalizeDeploymentUrl(value) {
+  return /^https?:\/\//i.test(value) ? value : `https://${value}`
+}