create-visualbuild-app 0.1.0

package/README.md

@@ -0,0 +1,123 @@
+# VisualBuild
+
+VisualBuild is a visual development framework for building React applications
+with drag and drop while retaining normal, editable source code.
+
+The visual editor writes the project schema, the generator writes real React
+files, and supported static JSX/TSX edits can sync back into the canvas.
+
+## Public CLI
+
+The canonical npm package is `create-visualbuild-app`.
+
+After the first public release, create a named project with either command:
+
+```bash
+npm create visualbuild-app@latest my-blog
+```
+
+```bash
+npx create-visualbuild-app@latest my-blog
+```
+
+Omitting the name creates `my-app`:
+
+```bash
+npm create visualbuild-app@latest
+```
+
+The public package has not been published yet. Maintainers can exercise the
+same CLI from this repository:
+
+```powershell
+npm.cmd run create-visualbuild-app -- my-blog
+```
+
+The previous local script remains available as a compatibility alias:
+
+```powershell
+npm.cmd run create-builder-app -- my-blog
+```
+
+## Scaffold Output
+
+VisualBuild deliberately separates the deployable application from the editor:
+
+```text
+workspace/
+  my-blog/            # developer-owned React application
+  visual-builder/     # visual editor, generator, and file watcher
+  my-blog-README.md   # generated setup instructions
+```
+
+The React app does not install editor-only packages such as dnd-kit or Zustand.
+It can be built, deployed, or retained after deleting `visual-builder/`.
+
+## Run A Generated Project
+
+Install and start the React application:
+
+```powershell
+cd my-blog
+npm install
+npm.cmd run dev
+```
+
+In another terminal, install and start the visual editor:
+
+```powershell
+cd visual-builder
+npm install
+npm.cmd run visual-builder
+```
+
+Changes saved in the editor update `my-blog/visualbuild/pages.json` and the
+generated React source. Supported static source edits are watched and reflected
+back into the canvas.
+
+## Architecture
+
+```text
+Visual Editor
+    |
+    v
+visualbuild/pages.json
+    |
+    v
+Babel AST Generator
+    |
+    v
+React Project
+```
+
+`visualbuild/pages.json` remains the safe schema boundary. Reverse sync accepts
+documented static JSX/TSX structures; unsupported dynamic React code is left
+untouched and produces an editor diagnostic.
+
+## Development
+
+```powershell
+npm install
+npm.cmd run visual-builder
+```
+
+Useful checks:
+
+```powershell
+npm.cmd run lint
+npm.cmd run build
+npm.cmd run test:week3
+npm.cmd pack --dry-run
+```
+
+## Status
+
+Current version: `0.1.0`
+
+Week 3 is in progress. The stable published template, CLI identity, and
+generator diagnostics are complete. The remaining release work is publishing
+to npm and validating clean public-registry scaffolds.
+
+## License
+
+UNLICENSED

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "create-visualbuild-app",
+  "version": "0.1.0",
+  "description": "Scaffold a React app with a separate VisualBuild drag-and-drop editor.",
+  "type": "module",
+  "bin": {
+    "create-visualbuild-app": "scripts/create-builder-app.mjs"
+  },
+  "keywords": [
+    "visualbuild",
+    "react",
+    "vite",
+    "visual-editor",
+    "app-builder",
+    "scaffold"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LORD-JINXXX/builder-app.git"
+  },
+  "bugs": {
+    "url": "https://github.com/LORD-JINXXX/builder-app/issues"
+  },
+  "homepage": "https://github.com/LORD-JINXXX/builder-app#readme",
+  "license": "UNLICENSED",
+  "files": [
+    "visual-app-builder/index.html",
+    "visual-app-builder/server",
+    "visual-app-builder/shared",
+    "visual-app-builder/src",
+    "visual-app-builder/vite.config.ts",
+    "templates",
+    "scripts/create-builder-app.mjs",
+    "scripts/vb-dev.mjs",
+    "scripts/vb-generate.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "test": "npm run test:week3",
+    "test:generator": "node --test tests/generate-react-source.test.mjs",
+    "test:registry": "node --test tests/component-registry.test.mjs",
+    "test:performance": "node --test tests/generator-performance.test.mjs",
+    "test:scaffold": "node --test tests/create-builder-app.test.mjs",
+    "test:diagnostics": "node --test tests/generator-diagnostics.test.mjs",
+    "test:reverse-sync": "node --experimental-strip-types --test tests/parse-react-page.test.ts",
+    "test:week3": "node --experimental-strip-types --test tests/parse-react-page.test.ts tests/generate-react-source.test.mjs tests/component-registry.test.mjs tests/generator-performance.test.mjs tests/create-builder-app.test.mjs tests/managed-page-deletion.test.mjs tests/managed-page-move.test.mjs tests/generator-diagnostics.test.mjs",
+    "create-visualbuild-app": "node scripts/create-builder-app.mjs",
+    "create-builder-app": "npm run create-visualbuild-app --",
+    "visual-builder": "node scripts/vb-dev.mjs",
+    "vb:generate": "node scripts/vb-generate.mjs"
+  },
+  "dependencies": {
+    "@babel/generator": "^7.29.7",
+    "@babel/parser": "^7.29.7",
+    "@babel/types": "^7.29.7",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@tailwindcss/vite": "^4.3.1",
+    "chokidar": "^4.0.3",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "uuid": "^14.0.1",
+    "zustand": "^5.0.14"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.13.2",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.2",
+    "eslint": "^10.5.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.3",
+    "globals": "^17.6.0",
+    "tailwindcss": "^4.3.1",
+    "typescript": "~6.0.2",
+    "typescript-eslint": "^8.61.0",
+    "vite": "^8.1.0"
+  }
+}

package/scripts/create-builder-app.mjs

@@ -0,0 +1,501 @@
+#!/usr/bin/env node
+
+import { execFile } from 'node:child_process'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const DEFAULT_PROJECT_NAME = 'my-app'
+const BUILDER_FOLDER_NAME = 'visual-builder'
+const templateRoot = path.join(repoRoot, 'templates', 'default')
+const appTemplateDir = path.join(templateRoot, 'app')
+const builderTemplateDir = path.join(templateRoot, 'builder')
+const editorSourceDir = path.join(repoRoot, 'visual-app-builder')
+const scriptFilesToCopy = ['vb-dev.mjs', 'vb-generate.mjs']
+
+const appPackageDependencies = ['react', 'react-dom']
+const appPackageDevDependencies = [
+  '@eslint/js',
+  '@tailwindcss/vite',
+  '@types/node',
+  '@types/react',
+  '@types/react-dom',
+  '@vitejs/plugin-react',
+  'eslint',
+  'eslint-plugin-react-hooks',
+  'eslint-plugin-react-refresh',
+  'globals',
+  'tailwindcss',
+  'typescript',
+  'typescript-eslint',
+  'vite',
+]
+
+const builderPackageDependencies = [
+  '@babel/generator',
+  '@babel/parser',
+  '@babel/types',
+  '@dnd-kit/core',
+  '@dnd-kit/sortable',
+  '@dnd-kit/utilities',
+  '@tailwindcss/vite',
+  'chokidar',
+  'react',
+  'react-dom',
+  'uuid',
+  'zustand',
+]
+
+const builderPackageDevDependencies = [
+  '@eslint/js',
+  '@types/node',
+  '@types/react',
+  '@types/react-dom',
+  '@vitejs/plugin-react',
+  'eslint',
+  'eslint-plugin-react-hooks',
+  'eslint-plugin-react-refresh',
+  'globals',
+  'tailwindcss',
+  'typescript',
+  'typescript-eslint',
+  'vite',
+]
+
+function getTargetBaseDir() {
+  return path.resolve(process.env.INIT_CWD || process.cwd())
+}
+
+function toProjectSlug(input) {
+  const slug = String(input || DEFAULT_PROJECT_NAME)
+    .trim()
+    .toLowerCase()
+    .replace(/['"]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+
+  return slug || DEFAULT_PROJECT_NAME
+}
+
+function toDisplayName(slug) {
+  return slug
+    .split(/[-_]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ')
+}
+
+async function pathExists(filePath) {
+  try {
+    await fs.access(filePath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function assertTargetIsWritable(targetDir) {
+  if (!(await pathExists(targetDir))) {
+    return
+  }
+
+  const entries = await fs.readdir(targetDir)
+
+  if (entries.length > 0) {
+    throw new Error(
+      `Target folder "${targetDir}" already exists and is not empty.`
+    )
+  }
+}
+
+async function assertScaffoldTargetsAreWritable(appDir, builderDir) {
+  await assertTargetIsWritable(appDir)
+  await assertTargetIsWritable(builderDir)
+}
+
+async function assertScaffoldAssetsExist() {
+  const requiredAssets = [
+    appTemplateDir,
+    builderTemplateDir,
+    editorSourceDir,
+    ...scriptFilesToCopy.map((file) => path.join(repoRoot, 'scripts', file)),
+  ]
+
+  for (const assetPath of requiredAssets) {
+    if (!(await pathExists(assetPath))) {
+      throw new Error(
+        `Required scaffold asset is missing: ${path.relative(repoRoot, assetPath)}`
+      )
+    }
+  }
+}
+
+async function copyAppTemplate(appDir) {
+  await fs.cp(appTemplateDir, appDir, { recursive: true })
+}
+
+async function copyBuilderTemplate(builderDir) {
+  await fs.cp(builderTemplateDir, builderDir, { recursive: true })
+  await fs.cp(
+    editorSourceDir,
+    path.join(builderDir, 'visual-app-builder'),
+    { recursive: true }
+  )
+
+  await fs.mkdir(path.join(builderDir, 'scripts'), { recursive: true })
+
+  for (const file of scriptFilesToCopy) {
+    await fs.copyFile(
+      path.join(repoRoot, 'scripts', file),
+      path.join(builderDir, 'scripts', file)
+    )
+  }
+}
+
+async function rewriteJsonFile(filePath, update) {
+  const contents = await fs.readFile(filePath, 'utf8')
+  const json = JSON.parse(contents)
+  const nextJson = update(json)
+  await fs.writeFile(filePath, `${JSON.stringify(nextJson, null, 2)}\n`)
+}
+
+async function replaceInFile(filePath, replacements) {
+  if (!(await pathExists(filePath))) {
+    return
+  }
+
+  let contents = await fs.readFile(filePath, 'utf8')
+
+  for (const [from, to] of replacements) {
+    contents = contents.split(from).join(to)
+  }
+
+  await fs.writeFile(filePath, contents)
+}
+
+async function seedProject(appDir, builderDir, projectName, displayName) {
+  const appPackageJson = await readRootPackageJson()
+  const builderPackageJson = await readRootPackageJson()
+  const relativeAppDir = toPosixPath(path.relative(builderDir, appDir))
+
+  await fs.writeFile(
+    path.join(appDir, 'package.json'),
+    `${JSON.stringify(
+      createAppPackageJson(appPackageJson, projectName),
+      null,
+      2
+    )}\n`
+  )
+
+  await fs.writeFile(
+    path.join(builderDir, 'package.json'),
+    `${JSON.stringify(
+      createBuilderPackageJson(
+        builderPackageJson,
+        relativeAppDir
+      ),
+      null,
+      2
+    )}\n`
+  )
+
+  await rewriteJsonFile(
+    path.join(appDir, 'visualbuild', 'pages.json'),
+    (schema) => seedProjectSchema(schema, projectName, displayName)
+  )
+
+  const templateReplacements = [
+    ['__DISPLAY_NAME__', displayName],
+    ['__PROJECT_NAME__', projectName],
+  ]
+
+  await replaceInFile(path.join(appDir, 'index.html'), templateReplacements)
+  await replaceInFile(path.join(appDir, 'README.md'), templateReplacements)
+  await replaceInFile(path.join(builderDir, 'README.md'), templateReplacements)
+
+  const sourceReplacements = [
+    ['my-blog', projectName],
+    ['My Blog', displayName],
+    ['Welcome to My Blog', `Welcome to ${displayName}`],
+  ]
+
+  await replaceInFile(
+    path.join(builderDir, 'visual-app-builder', 'src', 'stores', 'useAppStore.ts'),
+    sourceReplacements
+  )
+  await replaceInFile(
+    path.join(
+      builderDir,
+      'visual-app-builder',
+      'src',
+      'utils',
+      'projectPersistence.ts'
+    ),
+    sourceReplacements
+  )
+  await replaceInFile(
+    path.join(
+      builderDir,
+      'visual-app-builder',
+      'src',
+      'data',
+      'componentRegistry.tsx'
+    ),
+    sourceReplacements
+  )
+}
+
+async function readRootPackageJson() {
+  return JSON.parse(await fs.readFile(path.join(repoRoot, 'package.json'), 'utf8'))
+}
+
+function createAppPackageJson(packageJson, projectName) {
+  const allDependencies = mergeDependencies(packageJson)
+
+  return {
+    name: projectName,
+    private: true,
+    version: packageJson.version,
+    type: 'module',
+    scripts: {
+      dev: 'vite',
+      build: 'tsc -b && vite build',
+      lint: 'eslint .',
+      preview: 'vite preview',
+    },
+    dependencies: pickDependencies(allDependencies, appPackageDependencies),
+    devDependencies: pickDependencies(
+      allDependencies,
+      appPackageDevDependencies
+    ),
+  }
+}
+
+function createBuilderPackageJson(packageJson, relativeAppDir) {
+  const allDependencies = mergeDependencies(packageJson)
+
+  return {
+    name: BUILDER_FOLDER_NAME,
+    private: true,
+    version: packageJson.version,
+    type: 'module',
+    scripts: {
+      'visual-builder': `node scripts/vb-dev.mjs ${JSON.stringify(relativeAppDir)}`,
+      'vb:generate': `node scripts/vb-generate.mjs ${JSON.stringify(relativeAppDir)}`,
+      build: 'vite build --config visual-app-builder/vite.config.ts',
+      lint: 'eslint .',
+    },
+    dependencies: pickDependencies(
+      allDependencies,
+      builderPackageDependencies
+    ),
+    devDependencies: pickDependencies(
+      allDependencies,
+      builderPackageDevDependencies
+    ),
+  }
+}
+
+function mergeDependencies(packageJson) {
+  return {
+    ...(packageJson.dependencies ?? {}),
+    ...(packageJson.devDependencies ?? {}),
+  }
+}
+
+function pickDependencies(source, names) {
+  return Object.fromEntries(
+    names
+      .filter((name) => source?.[name])
+      .map((name) => [name, source[name]])
+  )
+}
+
+function toPosixPath(filePath) {
+  return filePath.split(path.sep).join('/')
+}
+
+function seedProjectSchema(schema, projectName, displayName) {
+  return {
+    ...schema,
+    meta: {
+      ...schema.meta,
+      projectName,
+    },
+    appShell: {
+      header: null,
+      footer: null,
+    },
+    pages: [createStarterHomePage(displayName)],
+  }
+}
+
+function createStarterHomePage(displayName) {
+  return {
+    id: 'page-home',
+    name: 'Home',
+    route: '/',
+    sourcePath: 'src/pages/HomePage.tsx',
+    root: {
+      id: 'page-home:root',
+      type: 'main',
+      label: 'Page root',
+      props: {
+        className:
+          'min-h-screen bg-slate-950 text-white flex items-center justify-center px-6',
+      },
+      children: [],
+    },
+    components: [
+      {
+        id: 'starter-shell',
+        type: 'section',
+        label: 'Starter',
+        props: {
+          className:
+            'w-full max-w-5xl rounded-2xl border border-white/10 bg-white/10 px-8 py-12 text-center shadow-2xl backdrop-blur',
+        },
+        children: [
+          {
+            id: 'starter-eyebrow',
+            type: 'p',
+            props: {
+              text: 'VisualBuild starter',
+              className:
+                'mb-4 text-xs font-semibold uppercase tracking-[0.28em] text-blue-300',
+            },
+            children: [],
+          },
+          {
+            id: 'starter-title',
+            type: 'h1',
+            props: {
+              text: `Welcome to ${displayName}`,
+              className: 'text-4xl font-bold tracking-tight sm:text-5xl',
+            },
+            children: [],
+          },
+          {
+            id: 'starter-subtitle',
+            type: 'p',
+            props: {
+              text: 'Build your app visually with drag and drop, then keep the real React code.',
+              className: 'mx-auto mt-5 max-w-2xl text-base text-slate-300',
+            },
+            children: [],
+          },
+          {
+            id: 'starter-actions',
+            type: 'div',
+            props: {
+              className:
+                'mt-8 flex flex-wrap items-center justify-center gap-3',
+            },
+            children: [
+              {
+                id: 'starter-primary-action',
+                type: 'a',
+                props: {
+                  text: 'Open Visual Builder',
+                  href: 'http://127.0.0.1:7371',
+                  target: '_blank',
+                  className:
+                    'rounded-lg bg-blue-500 px-5 py-3 text-sm font-semibold text-white shadow-lg shadow-blue-500/25 hover:bg-blue-400',
+                },
+                children: [],
+              },
+              {
+                id: 'starter-secondary-action',
+                type: 'span',
+                props: {
+                  text: 'Edit this page from visual-builder',
+                  className: 'text-sm text-slate-400',
+                },
+                children: [],
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  }
+}
+
+async function regenerateSource(appDir) {
+  await execFileAsync(
+    process.execPath,
+    [path.join(repoRoot, 'scripts', 'vb-generate.mjs'), appDir],
+    {
+      cwd: repoRoot,
+    }
+  )
+}
+
+async function writeWorkspaceReadme(targetBaseDir, projectName, displayName) {
+  const readmePath = path.join(targetBaseDir, `${projectName}-README.md`)
+  const contents = `# ${displayName} VisualBuild Workspace
+
+This workspace contains two separate projects:
+
+- \`${projectName}\`: deployable React app source.
+- \`${BUILDER_FOLDER_NAME}\`: VisualBuild editor and generator tooling.
+
+Install and run the app:
+
+\`\`\`powershell
+cd ${projectName}
+npm.cmd install
+npm.cmd run dev
+\`\`\`
+
+Install and run the visual builder:
+
+\`\`\`powershell
+cd ..\\${BUILDER_FOLDER_NAME}
+npm.cmd install
+npm.cmd run visual-builder
+\`\`\`
+
+The builder writes to \`${projectName}/visualbuild/pages.json\` and regenerates \`${projectName}/src\`.
+The React app package does not include builder-only drag-and-drop dependencies.
+`
+
+  await fs.writeFile(readmePath, contents)
+}
+
+async function main() {
+  const projectName = toProjectSlug(process.argv[2])
+  const displayName = toDisplayName(projectName)
+  const targetBaseDir = getTargetBaseDir()
+  const appDir = path.resolve(targetBaseDir, projectName)
+  const builderDir = path.resolve(targetBaseDir, BUILDER_FOLDER_NAME)
+
+  await assertScaffoldAssetsExist()
+  await assertScaffoldTargetsAreWritable(appDir, builderDir)
+  await copyAppTemplate(appDir)
+  await copyBuilderTemplate(builderDir)
+  await seedProject(appDir, builderDir, projectName, displayName)
+  await regenerateSource(appDir)
+  await writeWorkspaceReadme(targetBaseDir, projectName, displayName)
+
+  console.log(`Created VisualBuild app "${displayName}" in ${appDir}`)
+  console.log(`Created VisualBuild editor in ${builderDir}`)
+  console.log('')
+  console.log('Next steps:')
+  console.log(`  cd ${projectName}`)
+  console.log('  npm install')
+  console.log('  npm.cmd run dev')
+  console.log('')
+  console.log('Run the visual builder:')
+  console.log(`  cd ..\\${BUILDER_FOLDER_NAME}`)
+  console.log('  npm install')
+  console.log('  npm.cmd run visual-builder')
+}
+
+main().catch((error) => {
+  console.error(error.message)
+  process.exit(1)
+})