create-visualbuild-app 0.1.0 → 1.0.1

package/scripts/create-builder-app.mjs

@@ -1,501 +1,513 @@
-#!/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)
-})
+#!/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 userGuidePath = path.join(repoRoot, 'docs', 'user-guide.md')
+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,
+    userGuidePath,
+    ...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 = [
+    ['Welcome to My App', `Welcome to ${displayName}`],
+    ['My App', displayName],
+    ['my-app', projectName],
+  ]
+
+  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 workspaceGuidePath = path.join(targetBaseDir, 'VISUALBUILD-GUIDE.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.
+
+Read [VISUALBUILD-GUIDE.md](./VISUALBUILD-GUIDE.md) for the complete workflow,
+including visual editing, page and component registration, the larger code
+workspace, source ownership, two-way sync limits, configuration, deployment,
+and error recovery.
+
+Install and run the app:
+
+\`\`\`powershell
+cd ${projectName}
+npm.cmd install
+npm.cmd run dev
+\`\`\`
+
+In another terminal opened in this workspace, install and run the visual builder:
+
+\`\`\`powershell
+cd ${BUILDER_FOLDER_NAME}
+npm.cmd install
+npm.cmd run visual-builder
+\`\`\`
+
+If that terminal starts inside \`${projectName}\`, use
+\`cd ..\\${BUILDER_FOLDER_NAME}\` instead.
+
+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.copyFile(userGuidePath, workspaceGuidePath)
+  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('In another terminal opened in the workspace, 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)
+})