create-visualbuild-app 0.1.0

package/visual-app-builder/vite.config.ts

@@ -0,0 +1,1479 @@
+import { execFile } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import fs from 'node:fs/promises'
+import type { ServerResponse } from 'node:http'
+import path from 'node:path'
+import { promisify } from 'node:util'
+import { watch as watchFiles } from 'chokidar'
+import { defineConfig } from 'vite'
+import type { Plugin } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+import {
+  parseReactPageSource,
+  reconcileImportedTree,
+  visualTreesEqual,
+  type ImportedPageTree,
+  type ImportedVisualNode,
+} from './server/parseReactPage'
+
+const execFileAsync = promisify(execFile)
+const builderPackageRoot = process.cwd()
+const projectRoot = path.resolve(
+  process.env.VISUALBUILD_APP_DIR || builderPackageRoot
+)
+const builderRoot = path.resolve(builderPackageRoot, 'visual-app-builder')
+const generatedSourceRoot = path.resolve(projectRoot, 'src')
+const visualbuildRoot = path.resolve(projectRoot, 'visualbuild')
+const maxEditableFileBytes = 2 * 1024 * 1024
+const hiddenProjectEntries = new Set(['.git', 'node_modules'])
+
+type ProjectEntryKind = 'file' | 'directory' | 'symlink'
+
+interface ProjectEntry {
+  name: string
+  path: string
+  kind: ProjectEntryKind
+}
+
+interface ManagedPage {
+  id: string
+  name: string
+  route: string
+  sourcePath?: string
+  root: ImportedVisualNode
+  components: ImportedVisualNode[]
+}
+
+interface ManagedProjectSchema {
+  pages: ManagedPage[]
+  [key: string]: unknown
+}
+
+interface ReverseSyncEvent {
+  type: 'reverse-sync-success' | 'reverse-sync-error'
+  path: string
+  pageId?: string
+  message: string
+}
+
+interface GeneratorDiagnostic {
+  severity: 'error'
+  phase: 'generate'
+  code: string
+  title: string
+  message: string
+  path: string
+  suggestion?: string
+}
+
+interface GeneratorDiagnosticEvent extends GeneratorDiagnostic {
+  type: 'generator-diagnostic'
+}
+
+interface FileSystemEvent {
+  type: 'filesystem-change'
+  path: string
+  action: 'add' | 'change' | 'unlink' | 'addDir' | 'unlinkDir'
+}
+
+interface ManagedPagesDeletedEvent {
+  type: 'managed-pages-deleted'
+  path: string
+  pageIds: string[]
+  message: string
+}
+
+interface ManagedPagePathChange {
+  pageId: string
+  previousPath: string
+  sourcePath: string
+}
+
+interface ManagedPagesMovedEvent {
+  type: 'managed-pages-moved'
+  path: string
+  targetPath: string
+  pages: ManagedPagePathChange[]
+  message: string
+}
+
+type VisualBuildEvent =
+  | ReverseSyncEvent
+  | GeneratorDiagnosticEvent
+  | FileSystemEvent
+  | ManagedPagesDeletedEvent
+  | ManagedPagesMovedEvent
+
+function isGeneratedProjectPath(watchedPath: string) {
+  const absolutePath = path.resolve(watchedPath)
+
+  return [generatedSourceRoot, visualbuildRoot].some(
+    (rootPath) =>
+      absolutePath === rootPath || absolutePath.startsWith(`${rootPath}${path.sep}`)
+  )
+}
+
+function sendJson(
+  res: { statusCode: number; setHeader: (name: string, value: string) => void; end: (body?: string) => void },
+  statusCode: number,
+  payload: unknown
+) {
+  res.statusCode = statusCode
+  res.setHeader('Content-Type', 'application/json')
+  res.end(JSON.stringify(payload))
+}
+
+function getProjectPath(relativePath = '') {
+  const normalizedInput = relativePath.replace(/\\/g, '/').trim()
+
+  if (
+    normalizedInput.startsWith('/') ||
+    /^[a-zA-Z]:/.test(normalizedInput) ||
+    normalizedInput.includes('\0')
+  ) {
+    throw new Error('Invalid project path')
+  }
+
+  const segments = normalizedInput
+    .split('/')
+    .filter((segment) => segment && segment !== '.')
+
+  if (segments.some((segment) => segment === '..')) {
+    throw new Error('Project path cannot leave the app root')
+  }
+
+  const absolutePath = path.resolve(projectRoot, ...segments)
+  const relativeToRoot = path.relative(projectRoot, absolutePath)
+
+  if (relativeToRoot.startsWith('..') || path.isAbsolute(relativeToRoot)) {
+    throw new Error('Project path cannot leave the app root')
+  }
+
+  return {
+    absolutePath,
+    relativePath: segments.join('/'),
+  }
+}
+
+async function assertRealPathInsideProject(absolutePath: string) {
+  const [realProjectRoot, realTarget] = await Promise.all([
+    fs.realpath(projectRoot),
+    fs.realpath(absolutePath),
+  ])
+  const relativeToRoot = path.relative(realProjectRoot, realTarget)
+
+  if (relativeToRoot.startsWith('..') || path.isAbsolute(relativeToRoot)) {
+    throw new Error('Project path cannot leave the app root')
+  }
+}
+
+function validateEntryName(name: unknown) {
+  if (
+    typeof name !== 'string' ||
+    !name.trim() ||
+    name === '.' ||
+    name === '..' ||
+    /[\\/:*?"<>|]/.test(name)
+  ) {
+    throw new Error('Enter a valid file or folder name')
+  }
+
+  return name.trim()
+}
+
+async function readJsonBody(req: NodeJS.ReadableStream) {
+  let body = ''
+
+  for await (const chunk of req) {
+    body += String(chunk)
+
+    if (body.length > maxEditableFileBytes * 2) {
+      throw new Error('Request is too large')
+    }
+  }
+
+  return body ? (JSON.parse(body) as Record<string, unknown>) : {}
+}
+
+async function listProjectDirectory(relativePath: string) {
+  const projectPath = getProjectPath(relativePath)
+  const stats = await fs.lstat(projectPath.absolutePath)
+
+  if (!stats.isDirectory() || stats.isSymbolicLink()) {
+    throw new Error('The selected path is not a directory')
+  }
+
+  await assertRealPathInsideProject(projectPath.absolutePath)
+  const directoryEntries = await fs.readdir(projectPath.absolutePath, {
+    withFileTypes: true,
+  })
+  const entries: ProjectEntry[] = directoryEntries
+    .filter((entry) => !hiddenProjectEntries.has(entry.name))
+    .map((entry) => {
+      const entryPath = projectPath.relativePath
+        ? `${projectPath.relativePath}/${entry.name}`
+        : entry.name
+      const kind: ProjectEntryKind = entry.isSymbolicLink()
+        ? 'symlink'
+        : entry.isDirectory()
+          ? 'directory'
+          : 'file'
+
+      return { name: entry.name, path: entryPath, kind }
+    })
+    .sort((first, second) => {
+      if (first.kind === 'directory' && second.kind !== 'directory') return -1
+      if (first.kind !== 'directory' && second.kind === 'directory') return 1
+      return first.name.localeCompare(second.name, undefined, {
+        numeric: true,
+        sensitivity: 'base',
+      })
+    })
+
+  return {
+    rootName: path.basename(projectRoot),
+    path: projectPath.relativePath,
+    entries,
+  }
+}
+
+async function readProjectFile(relativePath: string) {
+  const projectPath = getProjectPath(relativePath)
+  const stats = await fs.lstat(projectPath.absolutePath)
+
+  if (!stats.isFile() || stats.isSymbolicLink()) {
+    throw new Error('The selected path is not an editable file')
+  }
+
+  await assertRealPathInsideProject(projectPath.absolutePath)
+
+  if (stats.size > maxEditableFileBytes) {
+    return {
+      path: projectPath.relativePath,
+      content: '',
+      size: stats.size,
+      isBinary: false,
+      isTooLarge: true,
+    }
+  }
+
+  const buffer = await fs.readFile(projectPath.absolutePath)
+  const isBinary = buffer.subarray(0, 8000).includes(0)
+
+  return {
+    path: projectPath.relativePath,
+    content: isBinary ? '' : buffer.toString('utf8'),
+    size: stats.size,
+    isBinary,
+    isTooLarge: false,
+  }
+}
+
+async function importPageFromSource(
+  relativePath: string,
+  name: string,
+  route: string
+) {
+  const projectPath = getProjectPath(relativePath)
+
+  if (
+    !projectPath.relativePath.startsWith('src/') ||
+    !/\.(jsx|tsx)$/i.test(projectPath.relativePath)
+  ) {
+    throw new Error('Pages must use a .jsx or .tsx file inside src')
+  }
+
+  const stats = await fs.lstat(projectPath.absolutePath)
+
+  if (!stats.isFile() || stats.isSymbolicLink()) {
+    throw new Error('Select a valid React source file')
+  }
+
+  await assertRealPathInsideProject(projectPath.absolutePath)
+  const source = await fs.readFile(projectPath.absolutePath, 'utf8')
+  const pageId = randomUUID()
+  const converted = parseReactPageSource(source, projectPath.relativePath)
+
+  return {
+    id: pageId,
+    name,
+    route,
+    sourcePath: projectPath.relativePath,
+    root: {
+      ...converted.root,
+      id: `${pageId}:root`,
+      label: 'Page root',
+      children: [],
+    },
+    components: converted.components,
+  }
+}
+
+function getErrorStatus(error: unknown) {
+  const code =
+    typeof error === 'object' && error !== null && 'code' in error
+      ? String(error.code)
+      : ''
+
+  if (code === 'ENOENT') return 404
+  if (code === 'EEXIST' || code === 'ENOTEMPTY') return 409
+  return 400
+}
+
+const generatorDiagnosticMarker = 'VISUALBUILD_DIAGNOSTIC:'
+
+function getProcessOutput(error: unknown, key: 'stdout' | 'stderr') {
+  if (
+    typeof error !== 'object' ||
+    error === null ||
+    !(key in error)
+  ) {
+    return ''
+  }
+
+  return String(error[key] ?? '')
+}
+
+function parseGeneratorDiagnostic(
+  error: unknown,
+  reason: string
+): GeneratorDiagnostic {
+  const stderr = getProcessOutput(error, 'stderr')
+  const diagnosticLine = stderr
+    .split(/\r?\n/)
+    .find((line) => line.startsWith(generatorDiagnosticMarker))
+
+  if (diagnosticLine) {
+    try {
+      const diagnostic = JSON.parse(
+        diagnosticLine.slice(generatorDiagnosticMarker.length)
+      ) as Partial<GeneratorDiagnostic>
+
+      if (
+        diagnostic.severity === 'error' &&
+        diagnostic.phase === 'generate' &&
+        typeof diagnostic.code === 'string' &&
+        typeof diagnostic.title === 'string' &&
+        typeof diagnostic.message === 'string' &&
+        typeof diagnostic.path === 'string'
+      ) {
+        return {
+          severity: diagnostic.severity,
+          phase: diagnostic.phase,
+          code: diagnostic.code,
+          title: diagnostic.title,
+          message: diagnostic.message,
+          path: diagnostic.path,
+          suggestion:
+            typeof diagnostic.suggestion === 'string'
+              ? diagnostic.suggestion
+              : undefined,
+        }
+      }
+    } catch {
+      // Fall through to a stable diagnostic if the child process output is malformed.
+    }
+  }
+
+  return {
+    severity: 'error',
+    phase: 'generate',
+    code: 'GENERATION_FAILED',
+    title: 'React source generation failed',
+    message:
+      error instanceof Error
+        ? error.message
+        : `Failed to generate project files after ${reason}.`,
+    path: 'visualbuild/pages.json',
+    suggestion:
+      'Review the project schema and try again. The last valid files were kept.',
+  }
+}
+
+function getGeneratorDiagnostic(error: unknown) {
+  if (
+    typeof error !== 'object' ||
+    error === null ||
+    !('diagnostic' in error)
+  ) {
+    return null
+  }
+
+  return error.diagnostic as GeneratorDiagnostic
+}
+
+function visualbuildDevApi(): Plugin {
+  const pagesPath = path.resolve(projectRoot, 'visualbuild/pages.json')
+  const runtimeClassesPath = path.resolve(
+    builderRoot,
+    '.visualbuild-runtime-classes.html'
+  )
+  const generatorPath = path.resolve(
+    builderPackageRoot,
+    'scripts/vb-generate.mjs'
+  )
+
+  return {
+    name: 'visualbuild-dev-api',
+    async configResolved() {
+      await fs.writeFile(
+        runtimeClassesPath,
+        await fs.readFile(runtimeClassesPath, 'utf8').catch(() => '')
+      )
+    },
+    configureServer(server) {
+      let suppressWatchUntil = 0
+      let suppressReloadUntil = 0
+      let generateTimer: ReturnType<typeof setTimeout> | null = null
+      let managedDeletionQueue = Promise.resolve()
+      const reverseSyncTimers = new Map<
+        string,
+        ReturnType<typeof setTimeout>
+      >()
+      const suppressedUnlinkPaths = new Map<string, number>()
+      const eventClients = new Set<ServerResponse>()
+      const hotChannel = server.ws as unknown as {
+        send: (payload: unknown, data?: unknown) => void
+      }
+      const sendHotPayload = hotChannel.send.bind(hotChannel)
+
+      hotChannel.send = (payload, data) => {
+        if (
+          Date.now() < suppressReloadUntil &&
+          typeof payload === 'object' &&
+          payload !== null &&
+          'type' in payload &&
+          payload.type === 'full-reload'
+        ) {
+          return
+        }
+
+        sendHotPayload(payload, data)
+      }
+
+      async function generateProjectFiles(reason: string) {
+        try {
+          const { stdout, stderr } = await execFileAsync(
+            process.execPath,
+            [generatorPath],
+            { cwd: projectRoot }
+          )
+
+          if (stdout.trim()) {
+            server.config.logger.info(stdout.trim())
+          }
+
+          if (stderr.trim()) {
+            server.config.logger.warn(stderr.trim())
+          }
+        } catch (error) {
+          const diagnostic = parseGeneratorDiagnostic(error, reason)
+          server.config.logger.error(
+            `[VisualBuild] ${diagnostic.title}: ${diagnostic.message}`
+          )
+          broadcastVisualBuildEvent({
+            type: 'generator-diagnostic',
+            ...diagnostic,
+          })
+
+          const generationError = new Error(diagnostic.message)
+          Object.assign(generationError, { diagnostic })
+          throw generationError
+        }
+      }
+
+      const pagesWatcher = watchFiles(pagesPath, {
+        ignoreInitial: true,
+        usePolling: process.platform === 'win32',
+        interval: 100,
+        awaitWriteFinish: {
+          stabilityThreshold: 120,
+          pollInterval: 25,
+        },
+      }).on('change', () => {
+        if (Date.now() < suppressWatchUntil) {
+          return
+        }
+
+        if (generateTimer) {
+          clearTimeout(generateTimer)
+        }
+
+        generateTimer = setTimeout(() => {
+          generateTimer = null
+          void generateProjectFiles('pages.json change').catch(() => {})
+        }, 80)
+      })
+
+      function broadcastVisualBuildEvent(event: VisualBuildEvent) {
+        const payload = `event: visualbuild\ndata: ${JSON.stringify(event)}\n\n`
+
+        for (const client of eventClients) {
+          client.write(payload)
+        }
+      }
+
+      function normalizeManagedPath(value: unknown) {
+        return typeof value === 'string'
+          ? value.replace(/\\/g, '/').replace(/^\.\/+/, '')
+          : ''
+      }
+
+      function findManagedPagesForPath(
+        schema: ManagedProjectSchema,
+        relativePath: string,
+        isDirectory: boolean
+      ) {
+        const normalizedTarget = normalizeManagedPath(relativePath)
+
+        return schema.pages.filter((page) => {
+          const sourcePath = normalizeManagedPath(page.sourcePath)
+
+          return (
+            sourcePath === normalizedTarget ||
+            (isDirectory && sourcePath.startsWith(`${normalizedTarget}/`))
+          )
+        })
+      }
+
+      function replaceManagedPathPrefix(
+        sourcePath: string,
+        previousPath: string,
+        targetPath: string
+      ) {
+        return `${targetPath}${sourcePath.slice(previousPath.length)}`
+      }
+
+      function validateManagedPagePaths(schema: ManagedProjectSchema) {
+        const seenSourcePaths = new Set<string>()
+
+        for (const page of schema.pages) {
+          const sourcePath = normalizeManagedPath(page.sourcePath)
+
+          if (
+            !sourcePath.startsWith('src/') ||
+            !/\.(jsx|tsx)$/i.test(sourcePath) ||
+            sourcePath.includes('/../') ||
+            sourcePath.endsWith('/..')
+          ) {
+            throw new Error(
+              `Managed page "${page.name}" must remain a .jsx or .tsx file inside src`
+            )
+          }
+
+          if (
+            sourcePath === 'src/App.tsx' ||
+            sourcePath === 'src/layouts/AppLayout.tsx'
+          ) {
+            throw new Error(`Managed page path is reserved: ${sourcePath}`)
+          }
+
+          if (seenSourcePaths.has(sourcePath)) {
+            throw new Error(`Duplicate managed page path: ${sourcePath}`)
+          }
+
+          seenSourcePaths.add(sourcePath)
+        }
+      }
+
+      function suppressManagedUnlink(relativePath: string) {
+        suppressedUnlinkPaths.set(
+          normalizeManagedPath(relativePath),
+          Date.now() + 2500
+        )
+      }
+
+      function consumeSuppressedUnlink(relativePath: string) {
+        const normalizedPath = normalizeManagedPath(relativePath)
+        const expiresAt = suppressedUnlinkPaths.get(normalizedPath)
+
+        if (!expiresAt) return false
+
+        suppressedUnlinkPaths.delete(normalizedPath)
+        return expiresAt >= Date.now()
+      }
+
+      async function persistManagedPageDeletion(
+        relativePath: string,
+        isDirectory: boolean,
+        deleteTarget?: () => Promise<void>
+      ) {
+        const schema = JSON.parse(
+          await fs.readFile(pagesPath, 'utf8')
+        ) as ManagedProjectSchema
+        const removedPages = findManagedPagesForPath(
+          schema,
+          relativePath,
+          isDirectory
+        )
+
+        if (removedPages.length === 0) {
+          if (deleteTarget) await deleteTarget()
+          return []
+        }
+
+        if (removedPages.length === schema.pages.length) {
+          throw new Error(
+            'A VisualBuild project must keep at least one registered page'
+          )
+        }
+
+        const removedPageIds = new Set(removedPages.map((page) => page.id))
+        const nextSchema: ManagedProjectSchema = {
+          ...schema,
+          pages: schema.pages.filter((page) => !removedPageIds.has(page.id)),
+        }
+
+        for (const page of removedPages) {
+          const sourcePath = normalizeManagedPath(page.sourcePath)
+
+          if (sourcePath) {
+            suppressManagedUnlink(sourcePath)
+            const pendingTimer = reverseSyncTimers.get(
+              path.resolve(projectRoot, sourcePath)
+            )
+
+            if (pendingTimer) {
+              clearTimeout(pendingTimer)
+              reverseSyncTimers.delete(path.resolve(projectRoot, sourcePath))
+            }
+          }
+        }
+
+        suppressWatchUntil = Date.now() + 1500
+        await fs.writeFile(
+          pagesPath,
+          `${JSON.stringify(nextSchema, null, 2)}\n`,
+          'utf8'
+        )
+
+        try {
+          if (deleteTarget) await deleteTarget()
+        } catch (error) {
+          suppressWatchUntil = Date.now() + 1500
+          await fs.writeFile(
+            pagesPath,
+            `${JSON.stringify(schema, null, 2)}\n`,
+            'utf8'
+          )
+          throw error
+        }
+
+        await generateProjectFiles('managed page deletion')
+        broadcastVisualBuildEvent({
+          type: 'managed-pages-deleted',
+          path: normalizeManagedPath(relativePath),
+          pageIds: removedPages.map((page) => page.id),
+          message:
+            removedPages.length === 1
+              ? `Deleted ${removedPages[0].name}`
+              : `Deleted ${removedPages.length} pages`,
+        })
+
+        return removedPages
+      }
+
+      async function persistManagedPageMove(
+        relativePath: string,
+        targetRelativePath: string,
+        isDirectory: boolean,
+        moveTarget: () => Promise<void>,
+        rollbackTarget: () => Promise<void>
+      ) {
+        const normalizedSource = normalizeManagedPath(relativePath)
+        const normalizedTarget = normalizeManagedPath(targetRelativePath)
+        const schema = JSON.parse(
+          await fs.readFile(pagesPath, 'utf8')
+        ) as ManagedProjectSchema
+        const affectedPages = findManagedPagesForPath(
+          schema,
+          normalizedSource,
+          isDirectory
+        )
+
+        if (affectedPages.length === 0) {
+          await moveTarget()
+          return []
+        }
+
+        const affectedPageIds = new Set(affectedPages.map((page) => page.id))
+        const pathChanges: ManagedPagePathChange[] = affectedPages.map(
+          (page) => {
+            const previousPath = normalizeManagedPath(page.sourcePath)
+
+            return {
+              pageId: page.id,
+              previousPath,
+              sourcePath: isDirectory
+                ? replaceManagedPathPrefix(
+                    previousPath,
+                    normalizedSource,
+                    normalizedTarget
+                  )
+                : normalizedTarget,
+            }
+          }
+        )
+        const nextPaths = new Map(
+          pathChanges.map((change) => [change.pageId, change.sourcePath])
+        )
+        const nextSchema: ManagedProjectSchema = {
+          ...schema,
+          pages: schema.pages.map((page) =>
+            affectedPageIds.has(page.id)
+              ? { ...page, sourcePath: nextPaths.get(page.id) }
+              : page
+          ),
+        }
+
+        validateManagedPagePaths(nextSchema)
+
+        for (const change of pathChanges) {
+          suppressManagedUnlink(change.previousPath)
+          const previousAbsolutePath = path.resolve(
+            projectRoot,
+            change.previousPath
+          )
+          const pendingTimer = reverseSyncTimers.get(previousAbsolutePath)
+
+          if (pendingTimer) {
+            clearTimeout(pendingTimer)
+            reverseSyncTimers.delete(previousAbsolutePath)
+          }
+        }
+
+        let targetMoved = false
+        let schemaUpdated = false
+
+        try {
+          await moveTarget()
+          targetMoved = true
+          suppressWatchUntil = Date.now() + 1500
+          await fs.writeFile(
+            pagesPath,
+            `${JSON.stringify(nextSchema, null, 2)}\n`,
+            'utf8'
+          )
+          schemaUpdated = true
+          await generateProjectFiles('managed page move')
+        } catch (error) {
+          suppressWatchUntil = Date.now() + 1500
+
+          if (schemaUpdated) {
+            await fs.writeFile(
+              pagesPath,
+              `${JSON.stringify(schema, null, 2)}\n`,
+              'utf8'
+            )
+          }
+
+          if (targetMoved) {
+            await rollbackTarget()
+          }
+
+          if (schemaUpdated) {
+            await generateProjectFiles('managed page move rollback').catch(
+              () => {}
+            )
+          }
+
+          throw error
+        }
+
+        broadcastVisualBuildEvent({
+          type: 'managed-pages-moved',
+          path: normalizedSource,
+          targetPath: normalizedTarget,
+          pages: pathChanges,
+          message:
+            pathChanges.length === 1
+              ? `Moved ${affectedPages[0].name}`
+              : `Moved ${pathChanges.length} managed pages`,
+        })
+
+        return pathChanges
+      }
+
+      function unregisterExternallyDeletedPage(relativePath: string) {
+        managedDeletionQueue = managedDeletionQueue
+          .then(async () => {
+            const schema = JSON.parse(
+              await fs.readFile(pagesPath, 'utf8')
+            ) as ManagedProjectSchema
+            const removedPages = findManagedPagesForPath(
+              schema,
+              relativePath,
+              false
+            )
+
+            if (removedPages.length === 0) return
+
+            if (removedPages.length === schema.pages.length) {
+              await generateProjectFiles('restore required page')
+              broadcastVisualBuildEvent({
+                type: 'reverse-sync-error',
+                path: relativePath,
+                pageId: removedPages[0].id,
+                message:
+                  'The only registered page cannot be deleted. VisualBuild restored its source file.',
+              })
+              return
+            }
+
+            await persistManagedPageDeletion(relativePath, false)
+          })
+          .catch((error) => {
+            const message =
+              error instanceof Error
+                ? error.message
+                : 'Could not unregister the deleted page.'
+            broadcastVisualBuildEvent({
+              type: 'reverse-sync-error',
+              path: relativePath,
+              message,
+            })
+            server.config.logger.warn(
+              `[VisualBuild] Page deletion sync skipped ${relativePath}: ${message}`
+            )
+          })
+      }
+
+      async function reverseSyncSourceFile(absolutePath: string) {
+        const relativePath = path
+          .relative(projectRoot, absolutePath)
+          .split(path.sep)
+          .join('/')
+
+        try {
+          const schema = JSON.parse(
+            await fs.readFile(pagesPath, 'utf8')
+          ) as ManagedProjectSchema
+          const pageIndex = schema.pages.findIndex(
+            (page) =>
+              normalizeManagedPath(page.sourcePath) === relativePath
+          )
+
+          if (pageIndex < 0) return
+
+          const page = schema.pages[pageIndex]
+          const source = await fs.readFile(absolutePath, 'utf8')
+          const imported = parseReactPageSource(source, relativePath)
+          const current: ImportedPageTree = {
+            root: page.root,
+            components: page.components,
+          }
+          const reconciled = reconcileImportedTree(imported, current)
+
+          if (visualTreesEqual(reconciled, current)) return
+
+          schema.pages[pageIndex] = {
+            ...page,
+            root: reconciled.root,
+            components: reconciled.components,
+          }
+          suppressWatchUntil = Date.now() + 1200
+          await fs.writeFile(
+            pagesPath,
+            `${JSON.stringify(schema, null, 2)}\n`,
+            'utf8'
+          )
+          broadcastVisualBuildEvent({
+            type: 'reverse-sync-success',
+            path: relativePath,
+            pageId: page.id,
+            message: `Updated ${page.name} from ${relativePath}`,
+          })
+          server.config.logger.info(
+            `[VisualBuild] Reverse synced ${relativePath}`
+          )
+        } catch (error) {
+          const message =
+            error instanceof Error
+              ? error.message
+              : 'Reverse sync could not parse the managed page.'
+          broadcastVisualBuildEvent({
+            type: 'reverse-sync-error',
+            path: relativePath,
+            message,
+          })
+          server.config.logger.warn(
+            `[VisualBuild] Reverse sync skipped ${relativePath}: ${message}`
+          )
+        }
+      }
+
+      function scheduleReverseSync(absolutePath: string) {
+        if (!/\.(jsx|tsx)$/i.test(absolutePath)) return
+
+        const previousTimer = reverseSyncTimers.get(absolutePath)
+        if (previousTimer) clearTimeout(previousTimer)
+
+        reverseSyncTimers.set(
+          absolutePath,
+          setTimeout(() => {
+            reverseSyncTimers.delete(absolutePath)
+            void reverseSyncSourceFile(absolutePath)
+          }, 100)
+        )
+      }
+
+      function handleProjectFileChange(
+        action: FileSystemEvent['action'],
+        absolutePath: string
+      ) {
+        const relativePath = path
+          .relative(projectRoot, absolutePath)
+          .split(path.sep)
+          .join('/')
+
+        if (
+          !relativePath ||
+          relativePath === '..' ||
+          relativePath.startsWith('../')
+        ) {
+          return
+        }
+
+        broadcastVisualBuildEvent({
+          type: 'filesystem-change',
+          path: relativePath,
+          action,
+        })
+
+        const relativeToSource = path.relative(generatedSourceRoot, absolutePath)
+        const isInsideSource =
+          relativeToSource &&
+          relativeToSource !== '..' &&
+          !relativeToSource.startsWith(`..${path.sep}`) &&
+          !path.isAbsolute(relativeToSource)
+
+        if (isInsideSource && (action === 'add' || action === 'change')) {
+          scheduleReverseSync(absolutePath)
+        }
+
+        if (
+          isInsideSource &&
+          action === 'unlink' &&
+          !consumeSuppressedUnlink(relativePath)
+        ) {
+          unregisterExternallyDeletedPage(relativePath)
+        }
+      }
+
+      const projectWatcher = watchFiles(projectRoot, {
+        ignoreInitial: true,
+        usePolling: process.platform === 'win32',
+        interval: 100,
+        ignored: (watchedPath) => {
+          const relativePath = path.relative(projectRoot, path.resolve(watchedPath))
+          const segments = relativePath.split(path.sep)
+
+          return segments.some((segment) =>
+            ['.git', 'node_modules', 'dist', '.visualbuild-qa'].includes(segment)
+          )
+        },
+        awaitWriteFinish: {
+          stabilityThreshold: 140,
+          pollInterval: 25,
+        },
+      })
+        .on('add', (changedPath) => handleProjectFileChange('add', changedPath))
+        .on('change', (changedPath) =>
+          handleProjectFileChange('change', changedPath)
+        )
+        .on('unlink', (changedPath) =>
+          handleProjectFileChange('unlink', changedPath)
+        )
+        .on('addDir', (changedPath) =>
+          handleProjectFileChange('addDir', changedPath)
+        )
+        .on('unlinkDir', (changedPath) =>
+          handleProjectFileChange('unlinkDir', changedPath)
+        )
+        .on('ready', () => {
+          server.config.logger.info(
+            `[VisualBuild] Watching ${projectRoot} for project and managed source changes`
+          )
+        })
+        .on('error', (error) => {
+          server.config.logger.warn(
+            `[VisualBuild] Source watcher error: ${error.message}`
+          )
+        })
+
+      const keepAliveTimer = setInterval(() => {
+        for (const client of eventClients) {
+          client.write(': keep-alive\n\n')
+        }
+      }, 15000)
+
+      server.httpServer?.once('close', () => {
+        void pagesWatcher.close()
+        void projectWatcher.close()
+        clearInterval(keepAliveTimer)
+
+        for (const client of eventClients) {
+          client.end()
+        }
+
+        for (const timer of reverseSyncTimers.values()) {
+          clearTimeout(timer)
+        }
+
+        if (generateTimer) {
+          clearTimeout(generateTimer)
+        }
+      })
+
+      void generateProjectFiles('dev server start').catch(() => {})
+
+      server.middlewares.use('/__visualbuild/events', (req, res) => {
+        if (req.method !== 'GET') {
+          res.statusCode = 405
+          res.end()
+          return
+        }
+
+        res.statusCode = 200
+        res.setHeader('Content-Type', 'text/event-stream')
+        res.setHeader('Cache-Control', 'no-cache, no-transform')
+        res.setHeader('Connection', 'keep-alive')
+        res.write('retry: 1500\n\n')
+        eventClients.add(res)
+
+        req.once('close', () => {
+          eventClients.delete(res)
+        })
+      })
+
+      server.middlewares.use('/__visualbuild/files', async (req, res) => {
+        const requestUrl = new URL(req.url ?? '/', 'http://visualbuild.local')
+
+        try {
+          if (req.method === 'GET') {
+            const result = await listProjectDirectory(
+              requestUrl.searchParams.get('path') ?? ''
+            )
+            sendJson(res, 200, result)
+            return
+          }
+
+          if (req.method === 'POST') {
+            const payload = await readJsonBody(req)
+            const parentPath = getProjectPath(
+              typeof payload.parentPath === 'string' ? payload.parentPath : ''
+            )
+            const parentStats = await fs.lstat(parentPath.absolutePath)
+
+            if (!parentStats.isDirectory() || parentStats.isSymbolicLink()) {
+              throw new Error('Select a valid parent folder')
+            }
+
+            await assertRealPathInsideProject(parentPath.absolutePath)
+            const name = validateEntryName(payload.name)
+            const targetPath = getProjectPath(
+              parentPath.relativePath
+                ? `${parentPath.relativePath}/${name}`
+                : name
+            )
+
+            if (payload.kind === 'directory') {
+              await fs.mkdir(targetPath.absolutePath)
+            } else if (payload.kind === 'file') {
+              await fs.writeFile(targetPath.absolutePath, '', {
+                encoding: 'utf8',
+                flag: 'wx',
+              })
+            } else {
+              throw new Error('Entry type must be file or directory')
+            }
+
+            sendJson(res, 201, {
+              name,
+              path: targetPath.relativePath,
+              kind: payload.kind,
+            })
+            return
+          }
+
+          if (req.method === 'PATCH') {
+            const payload = await readJsonBody(req)
+            const sourcePath = getProjectPath(
+              typeof payload.path === 'string' ? payload.path : ''
+            )
+
+            if (!sourcePath.relativePath) {
+              throw new Error('The project root cannot be renamed')
+            }
+
+            const sourceStats = await fs.lstat(sourcePath.absolutePath)
+
+            if (!sourceStats.isSymbolicLink()) {
+              await assertRealPathInsideProject(sourcePath.absolutePath)
+            }
+
+            const name = validateEntryName(payload.name)
+            const currentParentPath = path.posix.dirname(
+              sourcePath.relativePath
+            )
+            const requestedParentPath =
+              typeof payload.parentPath === 'string'
+                ? getProjectPath(payload.parentPath)
+                : getProjectPath(
+                    currentParentPath === '.' ? '' : currentParentPath
+                  )
+            const parentStats = await fs.lstat(
+              requestedParentPath.absolutePath
+            )
+
+            if (
+              !parentStats.isDirectory() ||
+              parentStats.isSymbolicLink()
+            ) {
+              throw new Error('Select a valid destination folder')
+            }
+
+            await assertRealPathInsideProject(
+              requestedParentPath.absolutePath
+            )
+            const targetPath = getProjectPath(
+              requestedParentPath.relativePath
+                ? `${requestedParentPath.relativePath}/${name}`
+                : name
+            )
+
+            if (targetPath.relativePath === sourcePath.relativePath) {
+              sendJson(res, 200, {
+                name,
+                path: targetPath.relativePath,
+                kind: sourceStats.isSymbolicLink()
+                  ? 'symlink'
+                  : sourceStats.isDirectory()
+                    ? 'directory'
+                    : 'file',
+                managedPages: [],
+              })
+              return
+            }
+
+            if (
+              sourceStats.isDirectory() &&
+              targetPath.relativePath.startsWith(
+                `${sourcePath.relativePath}/`
+              )
+            ) {
+              throw new Error('A folder cannot be moved inside itself')
+            }
+
+            const targetExists = await fs
+              .lstat(targetPath.absolutePath)
+              .then(() => true)
+              .catch((error: NodeJS.ErrnoException) => {
+                if (error.code === 'ENOENT') return false
+                throw error
+              })
+
+            if (targetExists) {
+              throw new Error('A file or folder with that name already exists')
+            }
+
+            const managedPages = await persistManagedPageMove(
+              sourcePath.relativePath,
+              targetPath.relativePath,
+              sourceStats.isDirectory() && !sourceStats.isSymbolicLink(),
+              () =>
+                fs.rename(sourcePath.absolutePath, targetPath.absolutePath),
+              () =>
+                fs.rename(targetPath.absolutePath, sourcePath.absolutePath)
+            )
+            sendJson(res, 200, {
+              name,
+              path: targetPath.relativePath,
+              kind: sourceStats.isSymbolicLink()
+                ? 'symlink'
+                : sourceStats.isDirectory()
+                  ? 'directory'
+                  : 'file',
+              managedPages,
+            })
+            return
+          }
+
+          if (req.method === 'DELETE') {
+            const targetPath = getProjectPath(
+              requestUrl.searchParams.get('path') ?? ''
+            )
+
+            if (!targetPath.relativePath) {
+              throw new Error('The project root cannot be deleted')
+            }
+
+            const targetStats = await fs.lstat(targetPath.absolutePath)
+
+            if (!targetStats.isSymbolicLink()) {
+              await assertRealPathInsideProject(targetPath.absolutePath)
+            }
+
+            const deleteTarget = () =>
+              fs.rm(targetPath.absolutePath, {
+                recursive: targetStats.isDirectory(),
+              })
+            const removedPages = await persistManagedPageDeletion(
+              targetPath.relativePath,
+              targetStats.isDirectory(),
+              deleteTarget
+            )
+
+            sendJson(res, 200, {
+              path: targetPath.relativePath,
+              removedPageIds: removedPages.map((page) => page.id),
+            })
+            return
+          }
+
+          res.statusCode = 405
+          res.end()
+        } catch (error) {
+          sendJson(res, getErrorStatus(error), {
+            error:
+              error instanceof Error
+                ? error.message
+                : 'Project file operation failed',
+          })
+        }
+      })
+
+      server.middlewares.use('/__visualbuild/file', async (req, res) => {
+        const requestUrl = new URL(req.url ?? '/', 'http://visualbuild.local')
+
+        try {
+          if (req.method === 'GET') {
+            sendJson(
+              res,
+              200,
+              await readProjectFile(requestUrl.searchParams.get('path') ?? '')
+            )
+            return
+          }
+
+          if (req.method === 'PUT') {
+            const payload = await readJsonBody(req)
+            const targetPath = getProjectPath(
+              typeof payload.path === 'string' ? payload.path : ''
+            )
+            const stats = await fs.lstat(targetPath.absolutePath)
+
+            if (!stats.isFile() || stats.isSymbolicLink()) {
+              throw new Error('The selected path is not an editable file')
+            }
+
+            await assertRealPathInsideProject(targetPath.absolutePath)
+
+            if (typeof payload.content !== 'string') {
+              throw new Error('File content must be text')
+            }
+
+            if (Buffer.byteLength(payload.content, 'utf8') > maxEditableFileBytes) {
+              throw new Error('File content exceeds the 2 MB editor limit')
+            }
+
+            await fs.writeFile(targetPath.absolutePath, payload.content, 'utf8')
+            res.statusCode = 204
+            res.end()
+            return
+          }
+
+          res.statusCode = 405
+          res.end()
+        } catch (error) {
+          sendJson(res, getErrorStatus(error), {
+            error:
+              error instanceof Error
+                ? error.message
+                : 'Project file operation failed',
+          })
+        }
+      })
+
+      server.middlewares.use('/__visualbuild/import-page', async (req, res) => {
+        try {
+          if (req.method !== 'POST') {
+            res.statusCode = 405
+            res.end()
+            return
+          }
+
+          const payload = await readJsonBody(req)
+          const name =
+            typeof payload.name === 'string' ? payload.name.trim() : ''
+          const route =
+            typeof payload.route === 'string' ? payload.route.trim() : ''
+          const sourcePath =
+            typeof payload.path === 'string' ? payload.path : ''
+
+          if (!name) {
+            throw new Error('Page name is required')
+          }
+
+          if (!route.startsWith('/')) {
+            throw new Error('Page route must start with "/"')
+          }
+
+          sendJson(
+            res,
+            201,
+            await importPageFromSource(sourcePath, name, route)
+          )
+        } catch (error) {
+          sendJson(res, getErrorStatus(error), {
+            error:
+              error instanceof Error
+                ? error.message
+                : 'Failed to import page source',
+          })
+        }
+      })
+
+      server.middlewares.use('/__visualbuild/tailwind', (req, res) => {
+        if (req.method !== 'POST') {
+          res.statusCode = 405
+          res.end()
+          return
+        }
+
+        let body = ''
+
+        req.on('data', (chunk) => {
+          body += chunk
+        })
+
+        req.on('end', async () => {
+          try {
+            const current = await fs
+              .readFile(runtimeClassesPath, 'utf8')
+              .catch(() => '')
+
+            if (current !== body) {
+              suppressReloadUntil = Date.now() + 1500
+              await fs.writeFile(runtimeClassesPath, body)
+            }
+
+            res.statusCode = 204
+            res.end()
+          } catch (error) {
+            res.statusCode = 500
+            res.end(
+              error instanceof Error
+                ? error.message
+                : 'Failed to update Tailwind classes'
+            )
+          }
+        })
+      })
+
+      server.middlewares.use('/__visualbuild/pages', async (req, res) => {
+        if (req.method === 'GET') {
+          try {
+            const json = await fs.readFile(pagesPath, 'utf8')
+            res.setHeader('Content-Type', 'application/json')
+            res.setHeader(
+              'X-VisualBuild-Project-Id',
+              encodeURIComponent(projectRoot)
+            )
+            res.end(json)
+          } catch (error) {
+            res.statusCode = 500
+            res.end(
+              error instanceof Error
+                ? error.message
+                : 'Failed to read pages.json'
+            )
+          }
+          return
+        }
+
+        if (req.method === 'POST') {
+          let body = ''
+
+          req.on('data', (chunk) => {
+            body += chunk
+          })
+
+          req.on('end', async () => {
+            let previousSchema = ''
+            let wroteSchema = false
+
+            try {
+              await fs.mkdir(path.dirname(pagesPath), { recursive: true })
+              previousSchema = await fs
+                .readFile(pagesPath, 'utf8')
+                .catch(() => '')
+
+              if (previousSchema !== body) {
+                suppressWatchUntil = Date.now() + 1000
+                suppressReloadUntil = Date.now() + 5000
+                await fs.writeFile(pagesPath, body)
+                wroteSchema = true
+                await generateProjectFiles('pages.json write')
+                suppressReloadUntil = Date.now() + 1000
+              }
+
+              res.statusCode = 204
+              res.end()
+            } catch (error) {
+              if (wroteSchema) {
+                suppressWatchUntil = Date.now() + 1000
+
+                if (previousSchema) {
+                  await fs.writeFile(pagesPath, previousSchema)
+                  await generateProjectFiles('pages.json rollback').catch(
+                    (rollbackError) => {
+                      server.config.logger.error(
+                        `[VisualBuild] Failed to restore generated files: ${
+                          rollbackError instanceof Error
+                            ? rollbackError.message
+                            : String(rollbackError)
+                        }`
+                      )
+                    }
+                  )
+                } else {
+                  await fs.rm(pagesPath, { force: true })
+                }
+              }
+
+              const diagnostic = getGeneratorDiagnostic(error)
+              sendJson(res, 500, {
+                error:
+                  diagnostic?.message ??
+                  (error instanceof Error
+                    ? error.message
+                    : 'Failed to write pages.json'),
+                diagnostic,
+              })
+            }
+          })
+
+          return
+        }
+
+        res.statusCode = 405
+        res.end()
+      })
+    },
+  }
+}
+
+export default defineConfig({
+  root: builderRoot,
+  define: {
+    'process.env.BABEL_TYPES_8_BREAKING': 'false',
+  },
+  plugins: [react(), tailwindcss(), visualbuildDevApi()],
+  server: {
+    watch: {
+      ignored: ['**/node_modules/**', isGeneratedProjectPath],
+    },
+  },
+})