create-visualbuild-app 0.1.0

package/scripts/vb-dev.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const targetAppDir = path.resolve(process.argv[2] ?? packageRoot)
+const viteBin = path.join(packageRoot, 'node_modules', 'vite', 'bin', 'vite.js')
+const viteConfig = path.join(packageRoot, 'visual-app-builder', 'vite.config.ts')
+
+const child = spawn(
+  process.execPath,
+  [viteBin, '--config', viteConfig, '--host', '127.0.0.1', '--port', '7371'],
+  {
+    cwd: packageRoot,
+    env: {
+      ...process.env,
+      VISUALBUILD_APP_DIR: targetAppDir,
+    },
+    stdio: 'inherit',
+  }
+)
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal)
+    return
+  }
+
+  process.exit(code ?? 0)
+})

package/scripts/vb-generate.mjs

@@ -0,0 +1,224 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import {
+  generateAppSource,
+  generateLayoutSource,
+  generatePageSource,
+  getPageSourcePath,
+  normalizeProjectPath,
+} from '../visual-app-builder/shared/generateReactSource.mjs'
+
+const root = path.resolve(process.argv[2] ?? process.cwd())
+const schemaPath = path.join(root, 'visualbuild', 'pages.json')
+const outputRoot = path.join(root, 'src')
+const manifestPath = path.join(root, 'visualbuild', 'generated-files.json')
+const diagnosticMarker = 'VISUALBUILD_DIAGNOSTIC:'
+
+class GeneratorDiagnosticError extends Error {
+  constructor(code, message, suggestion) {
+    super(message)
+    this.name = 'GeneratorDiagnosticError'
+    this.code = code
+    this.suggestion = suggestion
+  }
+}
+
+function validatePages(pages) {
+  const seenRoutes = new Set()
+  const seenSourcePaths = new Set()
+
+  for (const page of pages) {
+    if (!page.name || typeof page.name !== 'string') {
+      throw new GeneratorDiagnosticError(
+        'INVALID_PAGE_NAME',
+        'Every page needs a name.',
+        'Give each page a non-empty name in the page manager.'
+      )
+    }
+
+    if (!page.route || typeof page.route !== 'string') {
+      throw new GeneratorDiagnosticError(
+        'MISSING_PAGE_ROUTE',
+        `Page "${page.name}" needs a route.`,
+        'Add a route in the page manager before saving.'
+      )
+    }
+
+    if (!page.route.startsWith('/')) {
+      throw new GeneratorDiagnosticError(
+        'INVALID_PAGE_ROUTE',
+        `Route "${page.route}" must start with "/".`,
+        `Change the route to "/${page.route.replace(/^\/+/, '')}".`
+      )
+    }
+
+    if (seenRoutes.has(page.route)) {
+      throw new GeneratorDiagnosticError(
+        'DUPLICATE_PAGE_ROUTE',
+        `Duplicate route found: ${page.route}`,
+        'Give every registered page a unique route.'
+      )
+    }
+
+    const sourcePath = getPageSourcePath(page)
+
+    if (
+      !sourcePath.startsWith('src/') ||
+      !/\.(jsx|tsx)$/i.test(sourcePath) ||
+      sourcePath.includes('/../') ||
+      sourcePath.endsWith('/..')
+    ) {
+      throw new GeneratorDiagnosticError(
+        'INVALID_PAGE_SOURCE_PATH',
+        `Page "${page.name}" needs a .jsx or .tsx sourcePath inside src.`,
+        'Move the page source under src and use a .jsx or .tsx extension.'
+      )
+    }
+
+    if (
+      sourcePath === 'src/App.tsx' ||
+      sourcePath === 'src/layouts/AppLayout.tsx'
+    ) {
+      throw new GeneratorDiagnosticError(
+        'RESERVED_PAGE_SOURCE_PATH',
+        `Page source path is reserved: ${sourcePath}`,
+        'Choose a page file that does not replace App.tsx or AppLayout.tsx.'
+      )
+    }
+
+    if (seenSourcePaths.has(sourcePath)) {
+      throw new GeneratorDiagnosticError(
+        'DUPLICATE_PAGE_SOURCE_PATH',
+        `Duplicate page source path found: ${sourcePath}`,
+        'Give every registered page its own source file.'
+      )
+    }
+
+    seenRoutes.add(page.route)
+    seenSourcePaths.add(sourcePath)
+  }
+}
+
+async function writeFile(filePath, contents) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true })
+  await fs.writeFile(filePath, contents)
+}
+
+function getManagedFilePath(relativePath) {
+  const normalizedPath = normalizeProjectPath(relativePath)
+  const absolutePath = path.resolve(root, ...normalizedPath.split('/'))
+  const relativeToRoot = path.relative(root, absolutePath)
+
+  if (
+    !normalizedPath ||
+    relativeToRoot.startsWith('..') ||
+    path.isAbsolute(relativeToRoot)
+  ) {
+    throw new GeneratorDiagnosticError(
+      'UNSAFE_GENERATED_PATH',
+      `Generated file cannot leave the project: ${relativePath}`,
+      'Use a project-relative source path inside src.'
+    )
+  }
+
+  return absolutePath
+}
+
+async function readGeneratedManifest() {
+  try {
+    const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'))
+
+    return Array.isArray(manifest.files)
+      ? manifest.files.map(normalizeProjectPath)
+      : []
+  } catch {
+    return []
+  }
+}
+
+async function writeGeneratedManifest(files) {
+  await writeFile(
+    manifestPath,
+    `${JSON.stringify({ files: [...files].sort() }, null, 2)}\n`
+  )
+}
+
+async function main() {
+  const rawSchema = await fs.readFile(schemaPath, 'utf8')
+  const schema = JSON.parse(rawSchema)
+  const pages = schema.pages ?? []
+  const appShell = schema.appShell ?? { header: null, footer: null }
+
+  validatePages(pages)
+
+  await fs.mkdir(outputRoot, { recursive: true })
+  const previousManagedFiles = await readGeneratedManifest()
+  const nextManagedFiles = new Set([
+    'src/App.tsx',
+    ...pages.map(getPageSourcePath),
+  ])
+
+  if (appShell.header || appShell.footer) {
+    nextManagedFiles.add('src/layouts/AppLayout.tsx')
+  }
+
+  for (const staleFile of previousManagedFiles) {
+    if (!nextManagedFiles.has(staleFile)) {
+      await fs.rm(getManagedFilePath(staleFile), { force: true })
+    }
+  }
+
+  for (const page of pages) {
+    await writeFile(
+      getManagedFilePath(getPageSourcePath(page)),
+      generatePageSource(page)
+    )
+  }
+
+  if (appShell.header || appShell.footer) {
+    await writeFile(
+      path.join(outputRoot, 'layouts', 'AppLayout.tsx'),
+      generateLayoutSource(appShell)
+    )
+  }
+
+  await writeFile(
+    path.join(outputRoot, 'App.tsx'),
+    generateAppSource(pages, appShell)
+  )
+  await writeGeneratedManifest(nextManagedFiles)
+
+  console.log(`Generated ${pages.length} page(s) into src`)
+}
+
+main().catch((error) => {
+  const diagnostic = createGeneratorDiagnostic(error)
+  console.error(`${diagnosticMarker}${JSON.stringify(diagnostic)}`)
+  process.exit(1)
+})
+
+function createGeneratorDiagnostic(error) {
+  const isInvalidJson = error instanceof SyntaxError
+  const message =
+    error instanceof Error ? error.message : 'React source generation failed.'
+
+  return {
+    severity: 'error',
+    phase: 'generate',
+    code: isInvalidJson
+      ? 'INVALID_SCHEMA_JSON'
+      : error instanceof GeneratorDiagnosticError
+        ? error.code
+        : 'GENERATION_FAILED',
+    title: isInvalidJson
+      ? 'Project schema is not valid JSON'
+      : 'React source generation failed',
+    message,
+    path: 'visualbuild/pages.json',
+    suggestion: isInvalidJson
+      ? 'Fix the JSON syntax, then save again. The last generated React files were kept.'
+      : error instanceof GeneratorDiagnosticError
+        ? error.suggestion
+        : 'Review the page schema and try again. The last generated React files were kept.',
+  }
+}

package/templates/default/app/README.md

@@ -0,0 +1,21 @@
+# __DISPLAY_NAME__
+
+This is the deployable React application generated by VisualBuild. It contains
+only the source and dependencies required to run the application.
+
+## Run
+
+```powershell
+npm install
+npm.cmd run dev
+```
+
+## Build
+
+```powershell
+npm.cmd run build
+```
+
+The visual schema lives in `visualbuild/pages.json`. The optional sibling
+`visual-builder` project can edit this application visually and regenerate its
+managed React files. This application remains runnable without that editor.

package/templates/default/app/eslint.config.js

@@ -0,0 +1,25 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      globals: globals.browser,
+      parserOptions: {
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+])

package/templates/default/app/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>__DISPLAY_NAME__</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/default/app/src/index.css

@@ -0,0 +1,23 @@
+@import "tailwindcss";
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-width: 320px;
+  min-height: 100vh;
+  font-family:
+    Inter,
+    system-ui,
+    -apple-system,
+    BlinkMacSystemFont,
+    "Segoe UI",
+    sans-serif;
+  background: #f8fafc;
+  color: #111827;
+  -webkit-font-smoothing: antialiased;
+}

package/templates/default/app/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import './index.css'
+import App from './App.tsx'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

package/templates/default/app/tsconfig.app.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023", "DOM"],
+    "module": "esnext",
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}

package/templates/default/app/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}

package/templates/default/app/tsconfig.node.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023"],
+    "types": ["node"],
+    "skipLibCheck": true,
+    "module": "nodenext",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["vite.config.ts"]
+}

package/templates/default/app/visualbuild/generated-files.json

@@ -0,0 +1,3 @@
+{
+  "files": []
+}

package/templates/default/app/visualbuild/pages.json

@@ -0,0 +1,12 @@
+{
+  "meta": {
+    "projectName": "my-app",
+    "framework": "react",
+    "styling": "tailwind"
+  },
+  "appShell": {
+    "header": null,
+    "footer": null
+  },
+  "pages": []
+}

package/templates/default/app/vite.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+})

package/templates/default/builder/README.md

@@ -0,0 +1,21 @@
+# VisualBuild Editor
+
+This package contains the optional VisualBuild editor and generator for the
+sibling `__PROJECT_NAME__` React application.
+
+## Run
+
+```powershell
+npm install
+npm.cmd run visual-builder
+```
+
+## Generate Without Opening The Editor
+
+```powershell
+npm.cmd run vb:generate
+```
+
+The editor reads and writes `../__PROJECT_NAME__/visualbuild/pages.json` and
+manages generated files in `../__PROJECT_NAME__/src`. It is intentionally
+separate from the deployable application and does not need to be deployed.

package/templates/default/builder/eslint.config.js

@@ -0,0 +1,25 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      globals: globals.browser,
+      parserOptions: {
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+])

package/templates/default/builder/tsconfig.app.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023", "DOM"],
+    "module": "esnext",
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["visual-app-builder/src"]
+}

package/templates/default/builder/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}

package/templates/default/builder/tsconfig.node.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023"],
+    "types": ["node"],
+    "skipLibCheck": true,
+    "module": "nodenext",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": [
+    "visual-app-builder/vite.config.ts",
+    "visual-app-builder/server/**/*.ts"
+  ]
+}

package/visual-app-builder/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>VisualBuild</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>