@nextsparkjs/core 0.1.0-beta.189 → 0.1.0-beta.190

package/scripts/build/registry/post-build/page-generator.mjs

@@ -7,13 +7,18 @@
  */
 
 import { createRequire } from 'node:module'
-import { existsSync } from 'fs'
-import { readFile, writeFile, mkdir } from 'fs/promises'
-import { join, dirname } from 'path'
+import { constants, existsSync } from 'fs'
+import { lstat, readdir, readFile } from 'fs/promises'
+import { join, dirname, relative, sep } from 'path'
 import { fileURLToPath } from 'url'
 
-import { log, verbose } from '../../../utils/index.mjs'
-import { cleanupOrphanedTemplates } from './route-cleanup.mjs'
+import { errorWithLines, log, verbose } from '../../../utils/index.mjs'
+import { getProtectionLevel, ProtectionLevel } from '../../../../dist/config/protected-paths.js'
+import { selectTypeScriptModule, loadTypeScriptFor } from '../shared/typescript-compiler.mjs'
+import { ensureBackupsGitignore } from './own-gitignores.mjs'
+import { projectFiles } from '../../safe-fs.mjs'
+
+export { selectTypeScriptModule }
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -79,46 +84,27 @@ const SEGMENT_CONFIG_VALIDATORS = {
   maxDuration: value => typeof value === 'number' && Number.isInteger(value) && value >= 0,
 }
 
-// Loaded lazily (and only once) since not every consumer of this module needs
-// to parse a template - npm-mode builds without a template needing this path
-// shouldn't pay for loading a TypeScript compiler up front.
-let typescriptModulePromise = null
-
-/**
- * The TypeScript compiler, resolved from core first and then from the project:
- * it is a devDependency of core, so an installed core finds it through the
- * project that builds it, which has it to compile its own `.tsx` files.
- */
-function loadTypeScript() {
-  if (!typescriptModulePromise) {
-    typescriptModulePromise = import('typescript')
-      .catch(() => createRequire(join(rootDir, 'package.json'))('typescript'))
-      .then(
-        module => module.default ?? module,
-        error => {
-          throw new Error(
-            'Parsing route-level exports out of a theme template requires the "typescript" package, but it could not be loaded ' +
-              `from @nextsparkjs/core or from the project at ${rootDir}. Add "typescript" to the project's devDependencies. (${error.message})`
-          )
-        }
-      )
-  }
-  return typescriptModulePromise
-}
-
 let nextParseModulePromise = null
 
 /**
- * Next.js's own module parser (SWC), resolved from the project and then from
- * core, or null when neither has Next.js.
+ * Next.js's own module parser and SWC binding loader, resolved from the project
+ * and then from core, or null when neither has Next.js.
  */
 function loadNextParseModule() {
   if (!nextParseModulePromise) {
-    const path = 'next/dist/build/analysis/parse-module'
+    const parseModulePath = 'next/dist/build/analysis/parse-module'
+    const swcPath = 'next/dist/build/swc'
+    const loadFrom = require => ({
+      parseModule: require(parseModulePath).parseModule,
+      loadBindings: require(swcPath).loadBindings,
+    })
     nextParseModulePromise = Promise.resolve()
-      .then(() => createRequire(join(rootDir, 'package.json'))(path))
-      .catch(() => createRequire(import.meta.url)(path))
-      .then(module => module.parseModule, () => null)
+      .then(() => loadFrom(createRequire(join(rootDir, 'package.json'))))
+      .catch(() => loadFrom(createRequire(import.meta.url)))
+      .then(async ({ parseModule, loadBindings }) => {
+        await loadBindings()
+        return parseModule
+      }, () => null)
   }
   return nextParseModulePromise
 }
@@ -201,32 +187,19 @@ function declaresDefaultExport(sourceFile, ts) {
 }
 
 /**
- * Parse a theme template's source and split its route-level exports into:
- * - `segmentConfig`: segment config keys that resolve to a literal value the
- *   generated route file can re-declare (`{ name: value }`).
- * - `moduleExports`: exported names (functions, `metadata`, etc.) the
- *   generated route file can safely forward with `export { ... } from`.
- * - `hasDefaultExport`: whether it exports a component as default, read from
- *   the syntax tree so a comment or string mentioning `export default` doesn't
- *   count and `export { Layout as default }` does.
+ * Parse a theme template's source into a TypeScript AST.
  *
- * A segment config key that IS exported but not as a literal `export const`
- * (an expression, an identifier, `let`/`var`, a re-export, or a value the
- * Next.js schema rejects) throws instead of silently dropping it - Next.js
- * would otherwise ignore the value and fall back to its default, and nothing
- * in the build would say so beyond a console warning.
+ * The parser recovers from a syntax error by skipping code, exports included. A
+ * template Next.js cannot parse either is reported rather than read in part. One
+ * it can is read from what TypeScript recovered, with a warning: Next.js compiles
+ * templates with SWC, which may know syntax the installed TypeScript does not.
  */
-export async function extractRouteExports(source, filePath) {
-  const ts = await loadTypeScript()
+async function parseTemplateSource(source, filePath) {
+  const ts = await loadTypeScriptFor(rootDir)
   // Parsed as its own kind of file: a TSX parse reads TypeScript-only syntax in a
   // .ts template (`<T>(props) => ...`, `<Props>value`) as JSX and loses what follows
   const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.getScriptKindFromFileName(filePath))
 
-  // The parser recovers from a syntax error by skipping code, exports included. A
-  // template Next.js cannot parse either is reported rather than read in part. One
-  // it can is read from what TypeScript recovered, with a warning: Next.js compiles
-  // templates with SWC, which may know syntax the installed TypeScript does not (a
-  // source phase import, for one).
   const [parseError] = sourceFile.parseDiagnostics ?? []
   if (parseError) {
     const { line } = sourceFile.getLineAndCharacterOfPosition(parseError.start ?? 0)
@@ -240,6 +213,29 @@ export async function extractRouteExports(source, filePath) {
     )
   }
 
+  return { ts, sourceFile }
+}
+
+/**
+ * Split a parsed theme template's route-level exports into:
+ * - `segmentConfig`: segment config keys that resolve to a literal value the
+ *   generated route file can re-declare (`{ name: value }`).
+ * - `moduleExports`: exported names (functions, `metadata`, etc.) the
+ *   generated route file can safely forward with `export { ... } from`.
+ * - `hasDefaultExport`: whether it exports a component as default, read from
+ *   the syntax tree so a comment or string mentioning `export default` doesn't
+ *   count and `export { Layout as default }` does.
+ *
+ * - `errors`: one per segment config key that IS exported but not as a
+ *   literal `export const` (an expression, an identifier, `let`/`var`, a
+ *   re-export, or a value the Next.js schema rejects). Next.js would ignore
+ *   such a value and fall back to its default, and nothing in the build would
+ *   say so beyond a console warning, so a route file generated from the
+ *   template must not be written with it. They are returned rather than
+ *   thrown because a template whose app route already exists gets no route
+ *   file, and nothing reads its segment config.
+ */
+function collectRouteExports(sourceFile, ts, filePath) {
   const segmentConfig = {}
   const moduleExports = []
   const seenModuleExports = new Set()
@@ -324,41 +320,55 @@ export async function extractRouteExports(source, filePath) {
     }
   }
 
+  return { segmentConfig, moduleExports, hasDefaultExport: declaresDefaultExport(sourceFile, ts), errors }
+}
+
+/**
+ * Parse a theme template's source and return its route-level exports as
+ * `collectRouteExports` splits them, throwing on segment config Next.js
+ * wouldn't read.
+ */
+export async function extractRouteExports(source, filePath) {
+  const { ts, sourceFile } = await parseTemplateSource(source, filePath)
+  const { errors, ...routeExports } = collectRouteExports(sourceFile, ts, filePath)
+
   if (errors.length > 0) {
-    throw new Error(errors.join('\n'))
+    throw errorWithLines(errors)
   }
 
-  return { segmentConfig, moduleExports, hasDefaultExport: declaresDefaultExport(sourceFile, ts) }
+  return routeExports
 }
 
 /**
  * Resolve a `@/contents/...` template import path to its file on disk,
  * trying both TSX and TS extensions.
  */
-function resolveTemplateFilePath(templatePath) {
+function resolveTemplateFilePath(templatePath, root) {
   const baseTemplatePath = templatePath
-    .replace('@/', rootDir + '/')
+    .replace('@/', root + '/')
     .replace(/\.(tsx|ts)$/, '')
   return existsSync(baseTemplatePath + '.tsx') ? baseTemplatePath + '.tsx' : baseTemplatePath + '.ts'
 }
 
 /**
- * Read a template file and extract its route-level exports. A missing file
- * is treated as having none, since a build-time override may point at a
- * template that hasn't been generated yet; a template that fails to parse
- * its segment config is not swallowed the same way, and propagates instead.
+ * Read a template file and collect its route-level exports. A missing file
+ * is treated as having none and as having a default export - a build-time
+ * override may point at a template that hasn't been generated yet, and
+ * assuming a component exists there keeps that case importing it rather than
+ * silently downgrading to metadata-only.
  */
-async function readRouteExports(templatePath) {
-  const absoluteTemplatePath = resolveTemplateFilePath(templatePath)
+async function readTemplateExports(templatePath, root) {
+  const absoluteTemplatePath = resolveTemplateFilePath(templatePath, root)
 
   let templateContent
   try {
     templateContent = await readFile(absoluteTemplatePath, 'utf8')
   } catch {
-    return { segmentConfig: {}, moduleExports: [], hasDefaultExport: false }
+    return { segmentConfig: {}, moduleExports: [], hasDefaultExport: true, errors: [] }
   }
 
-  return extractRouteExports(templateContent, absoluteTemplatePath)
+  const { ts, sourceFile } = await parseTemplateSource(templateContent, absoluteTemplatePath)
+  return collectRouteExports(sourceFile, ts, absoluteTemplatePath)
 }
 
 /**
@@ -382,12 +392,10 @@ function renderModuleExportsBlock(moduleExports, templatePathWithoutExtension) {
 /**
  * Generate content for a regular page (page.tsx, error.tsx, etc.)
  */
-async function generateRegularPageContent(appPath, templatePath) {
+function generateRegularPageContent(appPath, templatePath, { segmentConfig, moduleExports }) {
   // Remove .tsx/.ts extension from import path (TypeScript doesn't allow file extensions in imports)
   const templatePathWithoutExtension = templatePath.replace(/\.(tsx|ts)$/, '')
 
-  const { segmentConfig, moduleExports } = await readRouteExports(templatePath)
-
   const segmentConfigBlock = renderSegmentConfigBlock(segmentConfig)
   const segmentConfigSection = segmentConfigBlock
     ? `\n// Segment config re-declared as literals: Next.js only reads these when they're declared directly in the route file, not re-exported\n${segmentConfigBlock}`
@@ -413,27 +421,14 @@ ${segmentConfigSection}${moduleExportsSection}`
 /**
  * Generate content for a layout page
  */
-async function generateLayoutPageContent(appPath, componentName, templatePath) {
+function generateLayoutPageContent(appPath, componentName, templatePath, routeExports) {
   if (templatePath) {
     // Remove .tsx/.ts extension from import path (TypeScript doesn't allow file extensions in imports)
     const templatePathWithoutExtension = templatePath.replace(/\.(tsx|ts)$/, '')
-    const absoluteTemplatePath = resolveTemplateFilePath(templatePath)
 
-    // Check if template file has a default export (component), and what
+    // Whether the template has a default export (component), and what
     // route-level exports it defines alongside (or instead of) it
-    let templateContent = null
-    try {
-      templateContent = await readFile(absoluteTemplatePath, 'utf8')
-    } catch {
-      // Can't read the file - fall through to the default-export assumption below
-    }
-
-    let hasDefaultExport = true
-    let segmentConfig = {}
-    let moduleExports = []
-    if (templateContent !== null) {
-      ;({ segmentConfig, moduleExports, hasDefaultExport } = await extractRouteExports(templateContent, absoluteTemplatePath))
-    }
+    const { hasDefaultExport, segmentConfig, moduleExports } = routeExports
 
     const segmentConfigBlock = renderSegmentConfigBlock(segmentConfig)
     const moduleExportsBlock = renderModuleExportsBlock(moduleExports, templatePathWithoutExtension)
@@ -456,9 +451,17 @@ export default TemplateComponent
 ${forwardedExportsSection}`
     } else if (segmentConfigBlock || moduleExportsBlock) {
       // No component, but the template still defines segment config and/or metadata -
-      // re-export those and provide a pass-through component
+      // re-export those and provide a pass-through component. Only a PROTECTED_RENDER
+      // path is labeled as one; anywhere else the template simply has no default export.
+      const renderProtected = getProtectionLevel(appPath) === ProtectionLevel.PROTECTED_RENDER
+      const description = renderProtected
+        ? 'metadata-only (PROTECTED_RENDER)'
+        : 'route-level exports only (the theme template has no default export)'
+      const passThroughNote = renderProtected
+        ? 'actual rendering blocked by PROTECTED_RENDER'
+        : 'the theme template exports no component, so this layout renders its children'
       return `/**
- * Layout template - metadata-only (PROTECTED_RENDER)
+ * Layout template - ${description}
  * Template: ${appPath}
  * Generated by: scripts/build-registry.mjs
  */
@@ -466,7 +469,7 @@ import type { ReactNode } from 'react'
 
 // Re-export Next.js route-level exports from the theme template
 ${segmentConfigBlock}${moduleExportsBlock}
-// Pass-through component (actual rendering blocked by PROTECTED_RENDER)
+// Pass-through component (${passThroughNote})
 interface ${componentName}Props {
   children: ReactNode
 }
@@ -565,61 +568,29 @@ function addTemplateResolverToLayout(content, layoutPath) {
 }
 
 /**
- * Duplicate a layout file to (templates) directory
- * Uses BUILD-TIME resolution: checks if template override exists and generates direct import
- * NO runtime resolver needed - all decisions made at build time
- *
- * @param {string} sourcePath - Path to original layout in app/
- * @param {string} targetPath - Path to write in app/(templates)/
- * @param {string} layoutPath - Relative layout path (e.g., 'app/dashboard/layout.tsx')
- * @param {Array} templates - All discovered templates (for build-time override check)
- */
-async function duplicateLayoutDirect(sourcePath, targetPath, layoutPath, templates) {
-  // Create target directory if it doesn't exist
-  const targetDir = dirname(targetPath)
-  await mkdir(targetDir, { recursive: true })
-
-  // BUILD-TIME CHECK: Does a template override exist for this layout?
-  const layoutOverride = templates.find(t =>
-    t.appPath === layoutPath && t.templateType === 'layout'
-  )
-
-  if (layoutOverride) {
-    // Template override exists - generate direct import to it
-    const templatePathWithoutExtension = layoutOverride.templatePath.replace(/\.(tsx|ts)$/, '')
-    const componentName = `Layout${toPascalCase(layoutPath.replace(/[^\w]/g, '_'))}`
-
-    const { segmentConfig, moduleExports } = await readRouteExports(layoutOverride.templatePath)
-    const segmentConfigBlock = renderSegmentConfigBlock(segmentConfig)
-    const moduleExportsBlock = renderModuleExportsBlock(moduleExports, templatePathWithoutExtension)
-    const forwardedExportsSection = segmentConfigBlock || moduleExportsBlock
-      ? `\n// Re-export Next.js route-level exports from the theme template\n${segmentConfigBlock}${moduleExportsBlock}`
-      : ''
-
-    const content = `/**
- * Layout with template override - directly imports from theme
- * Template: ${layoutPath}
- * Override: ${layoutOverride.templatePath}
- * Generated by: scripts/build-registry.mjs (build-time resolution)
+ * The comment a copy of an app/ layout in app/(templates)/ starts with. A
+ * comment is not a statement, so a 'use client' directive right after it is
+ * still the file's directive.
  */
-import TemplateLayout from '${templatePathWithoutExtension}'
-
-export default TemplateLayout
-${forwardedExportsSection}`
-    await writeFile(targetPath, content, 'utf8')
-    verbose(`Generated layout with template override: ${layoutPath}`)
-    return
-  }
+function layoutCopyHeader(layoutPath) {
+  return `/**
+ * Generated by the NextSpark registry build: a copy of ${layoutPath}, so theme
+ * routes under app/(templates) render inside the same layout. Rewritten on every build.
+ */
+`
+}
 
-  // No override - copy original layout as-is (simple pass-through)
-  try {
-    const originalContent = await readFile(sourcePath, 'utf8')
-    await writeFile(targetPath, originalContent, 'utf8')
-    verbose(`Copied original layout: ${layoutPath}`)
-  } catch (error) {
-    // If reading fails, generate a basic pass-through wrapper
+/**
+ * The content of the copy of an app/ layout in app/(templates)/. A layout that
+ * can't be read is replaced by a pass-through, which keeps the hierarchy.
+ */
+async function layoutCopyContent(layoutPath, appFiles) {
+  const layout = await projectFileContent(layoutPath, appFiles)
+  if (layout !== null) {
+    return layoutCopyHeader(layoutPath) + layout
+  } else {
     const componentName = `PassThroughLayout${toPascalCase(layoutPath.replace(/[^\w]/g, '_'))}`
-    const basicContent = `/**
+    return `/**
  * Basic layout wrapper - maintains Next.js structure
  * Generated by: scripts/build-registry.mjs
  */
@@ -631,74 +602,206 @@ export default function ${componentName}({ children }: ${componentName}Props) {
   return <>{children}</>
 }
 `
-    await writeFile(targetPath, basicContent, 'utf8')
-    verbose(`Generated basic layout wrapper for ${layoutPath}`)
   }
 }
 
 /**
- * Generate required parent layouts for a template page
- * Duplicates layouts from app/ to app/(templates)/ to preserve Next.js hierarchy
- * Uses BUILD-TIME resolution to check for template overrides
+ * The app/ layouts above a route directory, outermost first, that exist in the
+ * project: the ones a route generated into app/(templates)/ needs copied beside
+ * it to render inside the same hierarchy.
  *
- * @param {string} appPath - App path (e.g., 'app/dashboard/(main)/posts/page.tsx')
- * @param {string} templatesDir - Output directory for (templates)
- * @param {Array} templates - All discovered templates (for build-time override check)
+ * @param {string} directory - App directory of a route (e.g. 'app/dashboard/(main)/posts')
  */
-async function generateRequiredLayouts(appPath, templatesDir, templates) {
-  let layoutsGenerated = 0
-
-  // Extract the directory path from app path (remove filename)
-  // Example: app/dashboard/(main)/plugins/page.tsx -> dashboard/(main)/plugins
-  const pathParts = appPath.replace('app/', '').replace(/\/[^\/]+$/, '').split('/')
-
-  // Generate all parent directories and check for layouts
+function requiredLayoutPaths(directory, appFiles) {
+  const layoutPaths = []
   let currentPath = ''
-  for (const part of pathParts) {
+  for (const part of directory.replace(/^app\/?/, '').split('/')) {
     if (!part) continue
-
     currentPath = currentPath ? `${currentPath}/${part}` : part
     const layoutPath = `app/${currentPath}/layout.tsx`
-    const coreLayoutPath = join(rootDir, layoutPath)
-    const templateLayoutPath = join(templatesDir, `${currentPath}/layout.tsx`)
-
-    // Check if core layout exists and template layout doesn't
-    if (existsSync(coreLayoutPath) && !existsSync(templateLayoutPath)) {
-      // Pass templates for build-time override resolution
-      await duplicateLayoutDirect(coreLayoutPath, templateLayoutPath, layoutPath, templates)
-      layoutsGenerated++
+    const exists = appFiles?.has(layoutPath) ? appFiles.get(layoutPath) !== null : existsSync(join(rootDir, layoutPath))
+    if (exists) {
+      layoutPaths.push(layoutPath)
     }
   }
+  return layoutPaths
+}
 
-  return layoutsGenerated
+/**
+ * A file's content, by path from the project root: what `appFiles` gives when
+ * it has the path - null standing for a file that is gone - and otherwise what
+ * is on disk; null when there is no such file.
+ */
+async function projectFileContent(path, appFiles) {
+  if (appFiles?.has(path)) return appFiles.get(path)
+  try {
+    return await readFile(join(rootDir, path), 'utf8')
+  } catch {
+    return null
+  }
 }
 
 /**
  * Generate a single template page with template override system
+ *
+ * What `routeFileAction` decides applies: a template over a route the app
+ * already has gets no file, and the result says so; one whose route file would
+ * break is rejected before anything is written.
+ *
+ * @param {Object} template - The template to generate a route file from
+ * @param {string} outputPath - Where to write it
+ * @param {Map} [analysis] - What `analyzeTemplates` read from the build's templates; taken for this
+ *   template when omitted
+ * @returns {Promise<{ written: boolean, reason?: string }>}
  */
-export async function generateTemplatePage(template, outputPath) {
-  const { appPath, templateType, name, templatePath } = template
+export async function generateTemplatePage(template, outputPath, analysis = null) {
+  const routeExports = analysis ? templateAnalysisFor(analysis, template) : await analyzeTemplate(template, rootDir)
 
-  // Create directory if it doesn't exist
-  const dir = dirname(outputPath)
-  await mkdir(dir, { recursive: true })
+  if (routeFileAction(template, routeExports) === 'skip') {
+    return { written: false, reason: `the app already has ${template.appPath}, so no route file is generated for this template` }
+  }
 
-  // Determine the component name and content based on template type
-  const routeSegments = name.split('/').filter(segment => !segment.startsWith('[') && !segment.endsWith(']'))
-  const routeName = routeSegments[routeSegments.length - 1] || 'page'
-  const componentName = `AutoGenerated${toPascalCase(routeName)}${toPascalCase(templateType)}`
+  const files = projectFiles(rootDir)
+  await files.mkdir(dirname(outputPath), { recursive: true })
+  await files.writeFile(outputPath, routeFileContent(template, routeExports), 'utf8')
+  verbose(`Generated: ${outputPath.replace(rootDir, '')}`)
+  return { written: true }
+}
 
-  let content
+/**
+ * Whether `generateMissingPages` will write a route file at `appPath` -
+ * importing the template's default export - rather than leaving the app's
+ * own file in place and letting the override resolve at runtime through
+ * `getTemplateOrDefault`. A layout is always written, since build-time
+ * override resolution duplicates it into `app/(templates)/` regardless of
+ * whether the app already has one; anything else is only written when the
+ * app doesn't already have that route.
+ *
+ * @param {Map<string, string | null>} [appFiles] - Files under app/, by path from the project root, to take as
+ *   having this content instead of what is on disk (null: removed)
+ */
+export function willGenerateRoute(appPath, templateType, root = rootDir, appFiles = undefined) {
+  if (templateType === 'layout') return true
+  if (appFiles?.has(appPath)) return appFiles.get(appPath) === null
+  return !existsSync(join(root, appPath))
+}
 
-  if (templateType === 'layout') {
-    content = await generateLayoutPageContent(appPath, componentName, templatePath)
-  } else {
-    content = await generateRegularPageContent(appPath, templatePath)
+/**
+ * Parse each template once and record what it contributes to the build: its
+ * route-level exports, whether it has a default export, and whether the page
+ * generator writes a route file for it (`generatesRoute`). The server template
+ * registry, the client template registry and the page generator all take
+ * these from the result instead of reading the template themselves, so a
+ * template that changes while a build runs can't look one way to one of them
+ * and another way to the next.
+ *
+ * Throws for a template the page generator writes a route file for when that
+ * file can't work: segment config Next.js wouldn't read, or a page (or any
+ * other non-layout route) with no default export to import - a plain .tsx/.ts
+ * as much as a standalone .meta.ts, which never has one. A layout with no
+ * default export gets a pass-through component instead. A template whose app
+ * route already exists gets no route file, so neither applies to it: the
+ * override resolves at runtime, metadata included.
+ *
+ * @param {Array} templates - List of template definitions
+ * @param {Object} config - Configuration object with projectRoot
+ * @param {Map<string, string | null>} [appFiles] - Files under app/, by path from the project root, to take as
+ *   having this content instead of what is on disk (null: removed), so `generatesRoute` answers for the app as
+ *   a sync about to run leaves it rather than for the app the analysis runs against
+ * @returns {Promise<Map<string, Object>>} Each template's analysis, keyed by its templatePath
+ */
+export async function analyzeTemplates(templates, config = null, appFiles = undefined) {
+  if (config?.projectRoot) {
+    rootDir = config.projectRoot
   }
 
-  // Write the file
-  await writeFile(outputPath, content, 'utf8')
-  verbose(`Generated: ${outputPath.replace(rootDir, '')}`)
+  const analysis = new Map()
+
+  for (const template of templates) {
+    if (!analysis.has(template.templatePath)) {
+      analysis.set(template.templatePath, await analyzeTemplate(template, rootDir, appFiles))
+    }
+  }
+
+  return analysis
+}
+
+/**
+ * Parse one template and collect what `analyzeTemplates` records for it,
+ * rejecting it when the route file generated from it can't work: segment
+ * config Next.js wouldn't read, or what `routeFileAction` rejects. Every
+ * generator that has no analysis to hand reads a template through here.
+ *
+ * @param {Object} template - The template to read
+ * @param {string} root - The project root its path resolves against
+ * @param {Map<string, string | null>} [appFiles] - Files under app/ to take as having this content, as for
+ *   `analyzeTemplates`
+ */
+async function analyzeTemplate(template, root, appFiles) {
+  const { appPath, templateType, templatePath } = template
+  const generatesRoute = willGenerateRoute(appPath, templateType, root, appFiles)
+  const { errors, ...routeExports } = await readTemplateExports(templatePath, root)
+
+  if (generatesRoute && errors.length > 0) {
+    throw errorWithLines(errors)
+  }
+
+  const entry = { ...routeExports, generatesRoute }
+  routeFileAction(template, entry)
+  return entry
+}
+
+/**
+ * What becomes of a template's route file, decided from its analysis in this
+ * one place for every generator that writes route files or registers template
+ * components:
+ * - 'write': a route file is generated for it in app/(templates)
+ * - 'skip': the app already has that route, which stays; the override resolves
+ *   at runtime, and nothing is written for it
+ *
+ * A page (or any other non-layout route) whose route file would import a default
+ * export it doesn't have - a plain .tsx/.ts as much as a standalone .meta.ts,
+ * which never has one - is rejected. A layout with no default export gets a
+ * pass-through component instead.
+ *
+ * @param {Object} template - The template
+ * @param {Object} entry - Its analysis, as `analyzeTemplates` records it
+ * @returns {'write' | 'skip'}
+ */
+export function routeFileAction(template, entry) {
+  const { appPath, templateType, templatePath } = template
+
+  if (!entry.generatesRoute) {
+    return 'skip'
+  }
+
+  if (templateType !== 'layout' && !entry.hasDefaultExport) {
+    throw new Error(
+      `${templatePath} has no default export, and the app has no existing route at "${appPath}" ` +
+        `for a metadata-only override to attach to - the registry build generates "${appPath}" importing this ` +
+        `template's default export, which doesn't exist. A page template needs a default export. For a ` +
+        `metadata-only override, add one to an app page that already exists at "${appPath}" (a ".meta.ts" file, ` +
+        `or a template with no default export, next to it).`
+    )
+  }
+
+  return 'write'
+}
+
+/**
+ * The analysis `analyzeTemplates` recorded for a template. Missing means the
+ * caller is generating from templates other than the ones it analyzed, and
+ * reading the template here would bring back a second, possibly different,
+ * answer - so it fails instead.
+ */
+export function templateAnalysisFor(analysis, template) {
+  const entry = analysis?.get(template.templatePath)
+  if (!entry) {
+    throw new Error(
+      `${template.templatePath} was not read by analyzeTemplates() - pass the analysis of the same templates being generated.`
+    )
+  }
+  return entry
 }
 
 /**
@@ -708,115 +811,256 @@ export async function generateTemplatePage(template, outputPath) {
  *
  * @param {Array} templates - List of template definitions
  * @param {Object} config - Configuration object with projectRoot
+ * @param {Map} [analysis] - What `analyzeTemplates` read from these templates; taken for this call when omitted
+ * @returns {Promise<{ created: number, updated: number, removed: number, backupDir: string | null, skipped: string[] }>}
+ *   What changed in app/(templates), and the app paths of the templates that got no route file
  */
-export async function generateMissingPages(templates, config = null) {
+export async function generateMissingPages(templates, config = null, analysis = null) {
   // Use config.projectRoot if provided, otherwise fall back to default rootDir
   if (config?.projectRoot) {
     rootDir = config.projectRoot
   }
   const templatesDir = join(rootDir, 'app', '(templates)')
 
-  // First, clean up orphaned files before generating new ones
-  // Note: This is also called in registry.mjs before generateMissingPages,
-  // but we keep it here for standalone usage of this function
-  await cleanupOrphanedTemplates(templates, config)
+  // Every template has to pass routeFileAction before anything is written or deleted
+  analysis = analysis ?? (await analyzeTemplates(templates, config))
+  const skipped = templates
+    .filter(template => routeFileAction(template, templateAnalysisFor(analysis, template)) === 'skip')
+    .map(({ appPath }) => appPath)
+
+  const { created, updated, removed, backupDir } = await reconcileTemplatesTree(
+    templatesDir,
+    await planTemplatesTree(templates, analysis)
+  )
 
-  if (templates.length === 0) {
-    return
+  if (created > 0 || updated > 0 || removed > 0) {
+    log(`app/(templates): ${created} new, ${updated} updated, ${removed} removed`, 'success')
+  } else {
+    verbose('app/(templates) is up to date')
+  }
+  if (backupDir) {
+    log(`app/(templates): what was replaced or removed is backed up in ${relative(rootDir, backupDir)}`, 'warning')
   }
 
-  let generated = 0
-  let layoutsDuplicated = 0
+  return { created, updated, removed, backupDir, skipped }
+}
 
-  // Track all unique directory paths that need layouts
-  const layoutPathsNeeded = new Set()
+/**
+ * What `generateMissingPages` would change in app/(templates), worked out
+ * without writing anything: the files it would create, the ones it would
+ * replace and the ones it would remove - backing up both of those first - as
+ * paths from the project root.
+ *
+ * `appFiles` reaches the analysis too: whether a template gets a route file at
+ * all turns on whether the app has one at that path, so a route the sync is
+ * about to write - or remove - decides the plan the same way it decides the run.
+ *
+ * @param {Array} templates - List of template definitions
+ * @param {Object} config - Configuration object with projectRoot
+ * @param {Map<string, string | null>} [appFiles] - Files under app/, by path from the project root, to take as
+ *   having this content instead of what is on disk (null: removed), to plan against changes not written yet
+ * @returns {Promise<{ create: string[], replace: string[], remove: string[] }>}
+ */
+export async function planMissingPages(templates, config = null, appFiles = undefined) {
+  if (config?.projectRoot) {
+    rootDir = config.projectRoot
+  }
+  const templatesDir = join(rootDir, 'app', '(templates)')
 
-  // Group templates by their directory path to identify needed layouts
-  const templatesByPath = new Map()
+  const analysis = await analyzeTemplates(templates, config, appFiles)
+  const { create, replace, remove } = await diffTemplatesTree(templatesDir, await planTemplatesTree(templates, analysis, appFiles))
 
-  for (const template of templates) {
-    const { appPath, templateType } = template
-    const templatePagePath = join(rootDir, 'app', '(templates)', appPath.replace('app/', ''))
+  const fromRoot = path => relative(rootDir, path).split(sep).join('/')
+  return { create: create.map(fromRoot), replace: replace.map(fromRoot), remove: remove.map(fromRoot) }
+}
 
-    // Track the directory path for layout generation
-    layoutPathsNeeded.add(appPath)
+/**
+ * The route file generated from a template, with its component named after the
+ * last static segment of the template's route.
+ */
+function routeFileContent(template, routeExports) {
+  const { appPath, templateType, name, templatePath } = template
+  const routeSegments = name.split('/').filter(segment => !segment.startsWith('[') && !segment.endsWith(']'))
+  const routeName = routeSegments[routeSegments.length - 1] || 'page'
+  const componentName = `AutoGenerated${toPascalCase(routeName)}${toPascalCase(templateType)}`
 
-    // Check if core page exists (skip generation if it does)
-    // IMPORTANT: Always generate layouts, even if core layout exists
-    const corePagePath = join(rootDir, appPath)
-    if (existsSync(corePagePath) && templateType !== 'layout') {
-      continue
-    }
+  return templateType === 'layout'
+    ? generateLayoutPageContent(appPath, componentName, templatePath, routeExports)
+    : generateRegularPageContent(appPath, templatePath, routeExports)
+}
+
+/** Where a file under app/ is generated inside app/(templates)/. */
+function templatesTreePath(appPath) {
+  return join(rootDir, 'app', '(templates)', appPath.replace(/^app\//, ''))
+}
 
-    // Track template for potential generation/update
-    templatesByPath.set(appPath, { template, templatePagePath })
+/**
+ * Everything the registry build puts in app/(templates), as absolute path to
+ * content: a copy of each app/ layout above a template's route, and the route
+ * file of each template that gets one. A layout template's route file takes the
+ * place of the copy of the app layout at the same path.
+ */
+async function planTemplatesTree(templates, analysis, appFiles) {
+  const files = new Map()
+
+  const directories = new Set(templates.map(({ appPath }) => appPath.replace(/\/[^\/]+$/, '')))
+  for (const directory of directories) {
+    for (const layoutPath of requiredLayoutPaths(directory, appFiles)) {
+      const copyPath = templatesTreePath(layoutPath)
+      if (!files.has(copyPath)) {
+        files.set(copyPath, await layoutCopyContent(layoutPath, appFiles))
+      }
+    }
   }
 
-  // Generate required layouts for ALL template page directories (even if layout override doesn't exist)
-  // This ensures that pages in app/(templates)/ have the necessary layout hierarchy
-  // Extract unique directories from all templates (not just layout templates)
-  const uniqueDirectories = new Set()
   for (const template of templates) {
-    const { appPath } = template
-    // Extract directory path from page path
-    const dirPath = appPath.replace(/\/[^\/]+$/, '')
-    uniqueDirectories.add(dirPath)
+    const routeExports = templateAnalysisFor(analysis, template)
+    if (routeFileAction(template, routeExports) === 'write') {
+      files.set(templatesTreePath(template.appPath), routeFileContent(template, routeExports))
+    }
   }
 
-  for (const dirPath of uniqueDirectories) {
-    // Pass templates for build-time override resolution
-    const layoutsGenerated = await generateRequiredLayouts(`${dirPath}/page.tsx`, templatesDir, templates)
-    layoutsDuplicated += layoutsGenerated
+  return files
+}
+
+/**
+ * Every file under a directory, recursively, dotfiles included; none when it
+ * doesn't exist. Finder's .DS_Store is nobody's output and nobody's edit, and
+ * is left alone.
+ */
+async function listFiles(directory) {
+  if (!existsSync(directory)) return []
+
+  const files = []
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    if (entry.name === '.DS_Store') continue
+    const path = join(directory, entry.name)
+    if (entry.isDirectory()) {
+      files.push(...(await listFiles(path)))
+    } else if (entry.isFile()) {
+      files.push(path)
+    }
   }
+  return files
+}
 
-  // Generate or update template pages (regenerate if content differs - e.g., theme changed)
-  let updated = 0
-  for (const [appPath, { template, templatePagePath }] of templatesByPath) {
-    const { templateType, name, templatePath } = template
+/**
+ * Remove a directory the tree needs a file in place of, once the files in it
+ * are backed up and removed: the directories left in it, and any .DS_Store.
+ */
+async function removeDirectoryInTheWay(directory) {
+  const files = projectFiles(rootDir)
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name)
+    if (entry.isDirectory()) {
+      await removeDirectoryInTheWay(path)
+    } else if (entry.name === '.DS_Store') {
+      await files.unlink(path)
+    }
+  }
+  await files.rmdir(directory)
+}
 
-    // Generate expected content
-    const routeSegments = name.split('/').filter(segment => !segment.startsWith('[') && !segment.endsWith(']'))
-    const routeName = routeSegments[routeSegments.length - 1] || 'page'
-    const componentName = `AutoGenerated${toPascalCase(routeName)}${toPascalCase(templateType)}`
+/** Remove the empty directories under `directory`, deepest first, keeping `directory` itself. */
+async function removeEmptyDirectories(directory) {
+  if (!existsSync(directory)) return
 
-    let expectedContent
-    if (templateType === 'layout') {
-      expectedContent = await generateLayoutPageContent(appPath, componentName, templatePath)
-    } else {
-      expectedContent = await generateRegularPageContent(appPath, templatePath)
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    const path = join(directory, entry.name)
+    await removeEmptyDirectories(path)
+    if ((await readdir(path)).length === 0) {
+      await projectFiles(rootDir).rmdir(path)
     }
+  }
+}
 
-    // Check if file exists and compare content
-    if (existsSync(templatePagePath)) {
-      try {
-        const currentContent = await readFile(templatePagePath, 'utf8')
-        if (currentContent === expectedContent) {
-          // Content matches, skip
-          continue
-        }
-        // Content differs (theme changed), update file
-        await writeFile(templatePagePath, expectedContent, 'utf8')
-        updated++
-        verbose(`Updated (theme changed): ${templatePagePath.replace(rootDir, '')}`)
-      } catch (error) {
-        // Error reading, regenerate
-        await generateTemplatePage(template, templatePagePath)
-        generated++
-      }
-    } else {
-      // File doesn't exist, generate
-      await generateTemplatePage(template, templatePagePath)
-      generated++
+/**
+ * How app/(templates) differs from `files`, as absolute paths: the files
+ * `files` has that don't exist yet - a directory where one goes counts as none,
+ * since the files in it are removed - the ones that exist with other content,
+ * and the files in the tree that `files` doesn't have.
+ */
+async function diffTemplatesTree(templatesDir, files) {
+  const create = []
+  const replace = []
+  for (const [path, content] of files) {
+    if (!existsSync(path) || (await lstat(path)).isDirectory()) {
+      create.push(path)
+    } else if ((await readFile(path, 'utf8')) !== content) {
+      replace.push(path)
     }
   }
 
-  if (generated > 0 || updated > 0 || layoutsDuplicated > 0) {
-    const parts = []
-    if (generated > 0) parts.push(`${generated} new`)
-    if (updated > 0) parts.push(`${updated} updated`)
-    if (layoutsDuplicated > 0) parts.push(`${layoutsDuplicated} layouts`)
-    log(`Template pages: ${parts.join(', ')}`, 'success')
-  } else {
-    verbose('All template pages up to date')
+  const remove = (await listFiles(templatesDir)).filter(path => !files.has(path))
+  return { create, replace, remove }
+}
+
+/**
+ * Make app/(templates) hold exactly `contents`. The registry build owns that tree,
+ * but a file about to be replaced with different content, or removed because
+ * this build didn't produce it, may hold someone's edit: it is first copied into
+ * a directory under .nextspark/backups/ that belongs to this run alone - the
+ * time, and a suffix no other run gets - and named in the output. A backup is
+ * never written over.
+ *
+ * Whatever runs the build - build, dev, registry:build or sync:app - the
+ * backups are kept out of git by .nextspark/backups/.gitignore, put in place
+ * before anything in the tree is written; when one already there can't do
+ * that, nothing in the tree is written at all.
+ */
+async function reconcileTemplatesTree(templatesDir, contents) {
+  const { create, replace, remove } = await diffTemplatesTree(templatesDir, contents)
+  if (replace.length > 0 || remove.length > 0) {
+    await ensureBackupsGitignore(rootDir)
+  }
+  let backupDir = null
+  const files = projectFiles(rootDir)
+
+  const backUp = async absolutePath => {
+    if (!backupDir) {
+      const backupsRoot = join(rootDir, '.nextspark', 'backups')
+      await files.mkdir(backupsRoot, { recursive: true })
+      backupDir = await files.mkdtemp(join(backupsRoot, `${new Date().toISOString().replace(/[:.]/g, '-')}-`))
+    }
+    const relativePath = relative(rootDir, absolutePath)
+    const backupPath = join(backupDir, relativePath)
+    await files.mkdir(dirname(backupPath), { recursive: true })
+    await files.copyFile(absolutePath, backupPath, constants.COPYFILE_EXCL)
+    log(`app/(templates): backed up ${relativePath} to ${relative(rootDir, backupPath)}`, 'warning')
   }
+
+  // What stands where a file goes - a file where the tree needs a directory,
+  // or the files of a directory where it needs a file - is backed up and
+  // removed before anything is created, and new files still come before the
+  // rest is replaced or removed
+  const inTheWay = new Set(remove.filter(path =>
+    create.some(created => created.startsWith(`${path}${sep}`) || path.startsWith(`${created}${sep}`))
+  ))
+  for (const path of inTheWay) {
+    await backUp(path)
+    await files.unlink(path)
+  }
+
+  for (const path of create) {
+    if (existsSync(path)) {
+      await removeDirectoryInTheWay(path)
+    }
+    await files.mkdir(dirname(path), { recursive: true })
+    await files.writeFile(path, contents.get(path), 'utf8')
+  }
+
+  for (const path of replace) {
+    await backUp(path)
+    await files.writeFile(path, contents.get(path), 'utf8')
+  }
+
+  for (const path of remove.filter(path => !inTheWay.has(path))) {
+    await backUp(path)
+    await files.unlink(path)
+  }
+
+  await removeEmptyDirectories(templatesDir)
+
+  return { created: create.length, updated: replace.length, removed: remove.length, backupDir }
 }