@nextsparkjs/core 0.1.0-beta.191 → 0.1.0-beta.192

package/scripts/build/registry.mjs

@@ -7,30 +7,21 @@ import '../utils/console-guard.mjs'
  * Unified Build-Time Registry Generator
  *
  * Consolidates all content discovery into a single, efficient build script.
- * Generates static registries for ultra-fast runtime access (~17,255x performance improvement).
+ * Generates static registries for runtime access without filesystem I/O or discovery.
  *
  * Features:
  * - Unified plugin, entity, theme, and config discovery
  * - API endpoint registry generation
  * - TypeScript type generation
- * - Watch mode for development
- * - Turbo-compatible caching
  * - Dynamic project root support (NPM mode)
+ *
+ * Writes registries only, under .nextspark/registries (or NEXTSPARK_REGISTRIES_OUT). `nextspark prepare`
+ * runs it into a staging directory and publishes the result together with the generated src/app
+ * (registry/host/prepare.mjs); nothing here writes into src/app.
  */
 
 import { join, dirname, resolve } from 'path'
 import { fileURLToPath } from 'url'
-import { existsSync } from 'fs'
-import { lstat, readdir, readFile } from 'fs/promises'
-import dotenv from 'dotenv'
-
-// Load .env from the correct project root
-// Priority: NEXTSPARK_PROJECT_ROOT env var > cwd
-// This is critical for npm mode where cwd might be node_modules/@nextsparkjs/core
-const envPath = process.env.NEXTSPARK_PROJECT_ROOT
-  ? join(process.env.NEXTSPARK_PROJECT_ROOT, '.env')
-  : undefined
-dotenv.config({ path: envPath, override: true })
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -47,16 +38,16 @@ import { getBasename } from '../utils/paths.mjs'
 import { getConfig, validateEnvironment } from './registry/config.mjs'
 import { unsafeWritePlaces, unsafeWritePlacesLines } from './registry/write-places.mjs'
 import { projectFiles } from './safe-fs.mjs'
-import { ensureRegistriesGitignore, trackedFilesUnder, trackedRegistriesLines } from './registry/post-build/own-gitignores.mjs'
 
 // Import discovery modules (migrated from this file)
 import { discoverParentChildRelations } from './registry/discovery/parent-child.mjs'
 import { discoverPermissionsConfig } from './registry/discovery/permissions.mjs'
 import { discoverCoreEntities } from './registry/discovery/core-entities.mjs'
+import { mergeEntities } from './registry/discovery/all-entities.mjs'
 import { discoverPlugins } from './registry/discovery/plugins.mjs'
+import { pluginsFor } from './registry/discovery/plugin-capabilities.mjs'
 import { discoverThemes } from './registry/discovery/themes.mjs'
 import { discoverMiddlewares } from './registry/discovery/middlewares.mjs'
-import { discoverTemplates } from './registry/discovery/templates.mjs'
 import { discoverEmails } from './registry/discovery/emails.mjs'
 import { discoverBlocks } from './registry/discovery/blocks.mjs'
 import { discoverIcons } from './registry/discovery/icons.mjs'
@@ -65,17 +56,12 @@ import { discoverApiPresets } from './registry/discovery/api-presets.mjs'
 import { discoverMcpOverrides } from './registry/discovery/mcp-overrides.mjs'
 import { validateEntityConfigurations } from './registry/validation/entity-validator.mjs'
 import { generatePluginRegistry, generatePluginRegistryClient } from './registry/generators/plugin-registry.mjs'
+import { generatePluginCatalog } from './registry/generators/plugin-catalog.mjs'
 import { generateEntityRegistry, generateEntityRegistryClient } from './registry/generators/entity-registry.mjs'
 import { generateEntityTypes } from './registry/generators/entity-types.mjs'
-import { generateThemeRegistry } from './registry/generators/theme-registry.mjs'
-import {
-  generateTemplateRegistry,
-  generateTemplateRegistryClient,
-  generateTemplateScopeRegistries,
-  SCOPE_MARKER
-} from './registry/generators/template-registry.mjs'
+import { generateThemeRegistry, generateThemeRegistryClient, generateAppConfigClient, generateDashboardConfigClient, generateDevKeyringClient } from './registry/generators/theme-registry.mjs'
 import { generateEmailRegistry } from './registry/generators/email-registry.mjs'
-import { generateBlockRegistry, generateBlockRegistryClient, generateBlockRegistryLazy } from './registry/generators/block-registry.mjs'
+import { generateBlockRegistry, generateBlockRegistryClient, generateBlockRegistryLazy, generateBlockSchemas } from './registry/generators/block-registry.mjs'
 import { generateIconRegistry } from './registry/generators/icon-registry.mjs'
 import { generateMiddlewareRegistry } from './registry/generators/middleware-registry.mjs'
 import { generateRouteHandlersRegistry } from './registry/generators/route-handlers.mjs'
@@ -92,19 +78,14 @@ import { generateDocsRegistry } from './registry/generators/docs-registry.mjs'
 import { generateApiPresetsRegistry, generateApiDocsRegistry } from './registry/generators/api-presets-registry.mjs'
 import { generateMcpRegistry } from './registry/generators/mcp-registry.mjs'
 import {
-  analyzeTemplates,
-  generateMissingPages,
   displayTreeStructure,
   generateTestEntitiesJson,
-  generateTestBlocksJson,
-  cleanupOldRouteFiles
+  generateTestBlocksJson
 } from './registry/post-build/index.mjs'
-import { watchContents } from './registry/watch.mjs'
-import { syncAppGlobalsCss } from './theme.mjs'
 
 // ==================== Registry File Generation ====================
 
-async function generateRegistryFiles(CONFIG, plugins, entities, themes, templates, templateAnalysis, middlewares, blocks, permissionsConfig, coreRoutes, apiPresetsData, emails, mcpOverridesData) {
+async function generateRegistryFiles(CONFIG, plugins, entities, themes, middlewares, blocks, permissionsConfig, coreRoutes, apiPresetsData, emails, mcpOverridesData) {
   log('Generating registry files...', 'build')
 
   try {
@@ -113,51 +94,46 @@ async function generateRegistryFiles(CONFIG, plugins, entities, themes, template
     // Ensure output directory exists
     await files.mkdir(CONFIG.outputDir, { recursive: true })
 
-    // The registries git doesn't track yet are kept out of git by a .gitignore
-    // of their own, in place before the first one is written, whatever the
-    // project's rules say; the ones it tracks stay tracked, and that is said
-    if (await ensureRegistriesGitignore(CONFIG.projectRoot)) {
-      log('.gitignore', 'success')
-    }
-    const trackedRegistries = trackedFilesUnder(CONFIG.projectRoot, '.nextspark/registries')
-    if (trackedRegistries.length > 0) {
-      for (const line of trackedRegistriesLines(trackedRegistries.length)) log(line, 'warning')
-    }
-
-    // Generate client template registry (async - needs to check for server exports)
-    const templateRegistryClientContent = await generateTemplateRegistryClient(templates, CONFIG, templateAnalysis)
-
     // Collect the icon names configs can ask for by string (async - reads configs)
     const iconNames = await discoverIcons(blocks, CONFIG)
 
+    // Each registry takes only the plugins that declare its surface: the server registries the
+    // 'server' plugins, the client registry the 'web' ones (a build-only or mobile-only plugin is in neither).
+    const serverPlugins = pluginsFor(plugins, 'server')
+    const webPlugins = pluginsFor(plugins, 'web')
+
     // Generate individual registries (pass CONFIG to all generators)
     const registries = [
-      { name: 'plugin-registry.ts', content: generatePluginRegistry(plugins, CONFIG) },
-      { name: 'plugin-registry.client.ts', content: generatePluginRegistryClient(plugins, CONFIG) },
+      { name: 'plugin-registry.ts', content: generatePluginRegistry(serverPlugins, CONFIG) },
+      { name: 'plugin-registry.client.ts', content: generatePluginRegistryClient(webPlugins, CONFIG) },
+      { name: 'plugin-catalog.ts', content: generatePluginCatalog(plugins) },
       { name: 'entity-registry.ts', content: generateEntityRegistry(entities, CONFIG) },
       { name: 'entity-registry.client.ts', content: generateEntityRegistryClient(entities, CONFIG) },
       { name: 'entity-types.ts', content: generateEntityTypes(entities, CONFIG) },
       { name: 'theme-registry.ts', content: generateThemeRegistry(themes, CONFIG) },
-      { name: 'route-handlers.ts', content: generateRouteHandlersRegistry(plugins, themes, coreRoutes, entities, CONFIG) },
+      { name: 'theme-registry.client.ts', content: generateThemeRegistryClient(themes, CONFIG) },
+      { name: 'app-config.client.ts', content: generateAppConfigClient(themes, CONFIG) },
+      { name: 'dashboard-config.client.ts', content: generateDashboardConfigClient(themes, CONFIG) },
+      { name: 'dev-keyring.client.ts', content: generateDevKeyringClient(themes, CONFIG) },
+      { name: 'route-handlers.ts', content: generateRouteHandlersRegistry(serverPlugins, themes, coreRoutes, entities) },
       { name: 'translation-registry.ts', content: generateTranslationRegistry(themes, CONFIG) },
-      { name: 'template-registry.ts', content: await generateTemplateRegistry(templates, CONFIG, templateAnalysis) },
-      { name: 'template-registry.client.ts', content: templateRegistryClientContent },
       { name: 'email-registry.ts', content: generateEmailRegistry(emails, CONFIG) },
       { name: 'block-registry.ts', content: generateBlockRegistry(blocks, CONFIG) },
       { name: 'block-registry.client.ts', content: generateBlockRegistryClient(blocks, CONFIG) },
       { name: 'block-registry.lazy.ts', content: generateBlockRegistryLazy(blocks) },
+      { name: 'block-schemas.ts', content: generateBlockSchemas(blocks) },
       { name: 'icon-registry.ts', content: generateIconRegistry(iconNames, CONFIG) },
-      { name: 'billing-registry.ts', content: await generateBillingRegistry(CONFIG.activeTheme, CONFIG.contentsDir, CONFIG) },
+      { name: 'billing-registry.ts', content: await generateBillingRegistry(CONFIG) },
       { name: 'middleware-registry.ts', content: generateMiddlewareRegistry(middlewares, CONFIG) },
       { name: 'scope-registry.ts', content: generateScopeRegistry(entities, CONFIG) },
       { name: 'namespace-registry.ts', content: generateNamespaceRegistry(entities, CONFIG) },
       { name: 'permissions-registry.ts', content: await generatePermissionsRegistry(permissionsConfig, entities, CONFIG) },
       { name: 'scheduled-actions-registry.ts', content: generateScheduledActionsRegistry(themes, CONFIG) },
-      { name: 'docs-registry.ts', content: generateDocsRegistry() },
+      { name: 'docs-registry.ts', content: generateDocsRegistry(CONFIG) },
       { name: 'api-presets-registry.ts', content: generateApiPresetsRegistry(apiPresetsData, CONFIG) },
       { name: 'api-docs-registry.ts', content: generateApiDocsRegistry(apiPresetsData, CONFIG) },
       { name: 'mcp-registry.ts', content: generateMcpRegistry(mcpOverridesData, CONFIG) },
-      { name: 'index.ts', content: generateUnifiedRegistry(plugins, entities, themes, templates, middlewares, CONFIG) }
+      { name: 'index.ts', content: generateUnifiedRegistry(serverPlugins, entities, themes, middlewares, CONFIG) }
     ]
 
     for (const file of registries) {
@@ -166,52 +142,6 @@ async function generateRegistryFiles(CONFIG, plugins, entities, themes, template
       log(`${file.name}`, 'success')
     }
 
-    // Each route imports its own tiny registry rather than the global one.
-    // Build a complete replacement before cleanup so a theme change can never
-    // leave an existing route pointing at an old component import.
-    const templateScopes = await generateTemplateScopeRegistries(templates, CONFIG, templateAnalysis)
-    await files.mkdir(templateScopes.directory, { recursive: true })
-    const generated = new Set(templateScopes.files.map(file => file.path))
-
-    async function removeStaleScopedFiles(directory) {
-      let entries
-      try {
-        entries = await readdir(directory, { withFileTypes: true })
-      } catch (error) {
-        if (error?.code === 'ENOENT') return
-        throw error
-      }
-      for (const entry of entries) {
-        const path = join(directory, entry.name)
-        const stat = await lstat(path)
-        if (stat.isSymbolicLink()) continue
-        if (stat.isDirectory()) {
-          await removeStaleScopedFiles(path)
-          continue
-        }
-        if (!stat.isFile() || generated.has(path) || !path.endsWith('.ts')) continue
-        // Only files bearing our explicit marker are owned by this generator.
-        if ((await readFile(path, 'utf8')).includes(SCOPE_MARKER)) await files.rm(path, { force: true })
-      }
-      if (directory !== templateScopes.directory) {
-        try {
-          const remaining = await readdir(directory)
-          if (remaining.length === 0) {
-            await files.rmdir(directory)
-          }
-        } catch {
-          // Ignore if directory disappeared or cannot be removed
-        }
-      }
-    }
-
-    await removeStaleScopedFiles(templateScopes.directory)
-    for (const file of templateScopes.files) {
-      await files.mkdir(dirname(file.path), { recursive: true })
-      await files.writeFile(file.path, file.content, 'utf8')
-    }
-    log(`template-scopes (${templateScopes.files.length / 2})`, 'success')
-
   } catch (error) {
     logFailure('Error writing registry files', error)
     process.exit(1)
@@ -270,22 +200,15 @@ export async function buildRegistries(projectRoot = null) {
   const startTime = Date.now()
 
   try {
-    // Sync app/globals.css to import from active theme
-    // This ensures the import path matches NEXT_PUBLIC_ACTIVE_THEME
-    if (CONFIG.activeTheme) {
-      syncAppGlobalsCss(CONFIG, CONFIG.activeTheme)
-    }
-
     // Initialize parent-child discovery FIRST (needed for dynamic parseChildEntity)
     log('→ Initializing dynamic parent-child discovery...', 'info')
     await discoverParentChildRelations(CONFIG)
 
     // Discover all content types in parallel (pass CONFIG to each)
-    const [plugins, coreEntities, themes, templates, middlewares, blocks, permissionsConfig, coreRoutes, apiPresetsData, emails, mcpOverridesData] = await Promise.all([
+    const [plugins, coreEntities, themes, middlewares, blocks, permissionsConfig, coreRoutes, apiPresetsData, emails, mcpOverridesData] = await Promise.all([
       discoverPlugins(CONFIG),
       discoverCoreEntities(CONFIG),
       discoverThemes(CONFIG),
-      discoverTemplates(CONFIG),
       discoverMiddlewares(CONFIG),
       discoverBlocks(CONFIG),
       discoverPermissionsConfig(CONFIG),
@@ -295,80 +218,40 @@ export async function buildRegistries(projectRoot = null) {
       discoverMcpOverrides(CONFIG)
     ])
 
-    // Aggregate all entities with proper priority: plugin < core < theme
-    // Start with plugin entities (lowest priority)
-    const pluginEntities = []
-    plugins.forEach(plugin => {
-      if (plugin.entities && plugin.entities.length > 0) {
-        pluginEntities.push(...plugin.entities)
-      }
+    // Aggregate all entities with proper priority: plugin < core < project (a project entity can
+    // override core's with the same slug, e.g. patterns)
+    const allEntities = mergeEntities({
+      plugins,
+      coreEntities,
+      themes,
+      onOverride: (entity, replaced) => log(`  ↳ Theme override: "${entity.name}" (${entity.source || 'theme'} replaces ${replaced.source || 'core'})`, 'info'),
     })
 
-    // Add theme entities (highest priority - can override core)
-    const themeEntities = []
-    themes.forEach(theme => {
-      if (theme.entities && theme.entities.length > 0) {
-        themeEntities.push(...theme.entities)
-      }
-    })
-
-    // Merge all entities with priority: plugins < core < themes
-    // Theme entities override core entities with the same slug (e.g., patterns)
-    const mergedEntities = [
-      ...pluginEntities,      // Lowest priority
-      ...coreEntities,        // Core framework entities
-      ...themeEntities        // Highest priority (can override core)
-    ]
-
-    // Deduplicate: later entries (theme) win over earlier (core/plugin) with same name
-    const entityMap = new Map()
-    for (const entity of mergedEntities) {
-      if (entityMap.has(entity.name)) {
-        log(`  ↳ Theme override: "${entity.name}" (${entity.source || 'theme'} replaces ${entityMap.get(entity.name).source || 'core'})`, 'info')
-      }
-      entityMap.set(entity.name, entity)
-    }
-    const allEntities = Array.from(entityMap.values())
-
     // PHASE 3 VALIDATION: Ensure all entities have access.shared defined
-    await validateEntityConfigurations(allEntities)
+    await validateEntityConfigurations(allEntities, CONFIG)
 
-    const totalContents = plugins.length + allEntities.length + themes.length + templates.length + middlewares.length + blocks.length
+    const totalContents = plugins.length + allEntities.length + themes.length + middlewares.length + blocks.length
 
-    if (totalContents === 0) {
-      log('No contents found!', 'warning')
-      return
-    }
+    // A project with no contents still gets its (empty) registries: the host publishes them with src/app
+    if (totalContents === 0) log('No contents found!', 'warning')
 
     // Display beautiful tree structure
     displayTreeStructure(plugins, themes, coreEntities)
 
-    // Parse every theme template once, before anything is written. Both template
-    // registries and the page generator take what they need to know about a
-    // template from this, so a template saved while a build runs (watch mode)
-    // can't look one way to one of them and another way to the next.
-    const templateAnalysis = await analyzeTemplates(templates, CONFIG)
-
-    // Clean up old generated route files first
-    await cleanupOldRouteFiles(CONFIG)
-
     // Hoist plugin dependencies to root workspace for proper resolution
     // Generate all registry files (use aggregated entities for entity registry + blocks)
-    await generateRegistryFiles(CONFIG, plugins, allEntities, themes, templates, templateAnalysis, middlewares, blocks, permissionsConfig, coreRoutes, apiPresetsData, emails, mcpOverridesData)
-
-    // Generate missing pages for templates that don't have core app pages
-    await generateMissingPages(templates, CONFIG, templateAnalysis)
+    await generateRegistryFiles(CONFIG, plugins, allEntities, themes, middlewares, blocks, permissionsConfig, coreRoutes, apiPresetsData, emails, mcpOverridesData)
 
-    // Generate test fixtures for the active theme
+    // Generate test fixtures for the root-first project.
     await generateTestEntitiesJson(allEntities, themes, CONFIG)
     await generateTestBlocksJson(blocks, CONFIG)
 
     // Generate feature registry (features, flows, tags)
-    if (CONFIG.activeTheme) {
+    {
       log('Generating feature registry...', 'build')
       const featureResult = await generateFeatureRegistryFull(
-        CONFIG.activeTheme,
-        CONFIG.contentsDir,
+        CONFIG.projectName,
+        CONFIG.projectSourceDir,
         CONFIG.outputDir,
         CONFIG
       )
@@ -416,25 +299,12 @@ export async function buildRegistries(projectRoot = null) {
     console.log(`   Plugins: ${plugins.length}`)
     console.log(`   Entities: ${allEntities.length}`)
     console.log(`   Themes: ${themes.length}`)
-    console.log(`   Templates: ${templates.length}`)
     console.log(`   Blocks: ${blocks.length}`)
     console.log(`   Total: ${totalContents}`)
     console.log(`   Build time: ${buildTime}ms`)
     console.log()
     console.log(`🎯 All content types now accessible with zero I/O operations`)
 
-
-    if (templates.length > 0) {
-      console.log(`📄 Template overrides: ${templates.length} templates discovered`)
-      const groupedByTheme = templates.reduce((acc, t) => {
-        acc[t.themeName] = (acc[t.themeName] || 0) + 1
-        return acc
-      }, {})
-      Object.entries(groupedByTheme).forEach(([theme, count]) => {
-        console.log(`   ${theme}: ${count} templates`)
-      })
-    }
-
   } catch (error) {
     logFailure('Build failed', error, CONFIG.verbose)
     process.exit(1)
@@ -443,25 +313,14 @@ export async function buildRegistries(projectRoot = null) {
 // ==================== Direct Execution (Backward Compatibility) ====================
 
 async function main() {
-  // Get config for detecting run mode (no projectRoot = auto-detect)
-  const config = getConfig()
-
-  if (config.buildMode) {
-    log('Running in BUILD mode (watch disabled)', 'build')
-    // One-time build for production/CI
-    await buildRegistries()
-  } else if (config.watchMode) {
-    log('Running in WATCH mode (development)', 'info')
-    // Initial build
-    await buildRegistries()
-
-    // Start watching
-    await watchContents(buildRegistries)
-  } else {
-    log('Running in ONE-TIME mode', 'info')
-    // One-time build
-    await buildRegistries()
+  if (process.argv.includes('--watch')) {
+    console.error('registry.mjs no longer watches: nextspark prepare --watch (or nextspark dev) regenerates src/app and the registries on source changes.')
+    process.exit(1)
   }
+  // One build, whatever the flags: `--build` is what `nextspark prepare` passes, and regenerating
+  // on source changes is the generated host's watcher (registry/host/prepare.mjs watchHost)
+  log('Running in BUILD mode', 'build')
+  await buildRegistries()
 }
 
 // Handle graceful shutdown
@@ -477,7 +336,7 @@ process.on('SIGINT', () => {
 const isMainScript = process.argv[1] && import.meta.url.endsWith(getBasename(process.argv[1]))
 if (isMainScript) {
   main().catch(error => {
-    logFailure('Fatal error', error, getConfig().verbose)
+    logFailure('Fatal error', error, process.argv.includes('--verbose') || process.argv.includes('-v'))
     process.exit(1)
   })
 }

package/scripts/build/routes-manifest.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+/**
+ * Core route manifest (#203)
+ *
+ * Lists every route core implements under `src/routes/`, for `nextspark prepare`
+ * to emit one `src/app` facade per entry with the facade emitter
+ * (registry/host/facade-emitter.mjs):
+ *
+ * - `src/routes/manifest.json`: `[{ kind, target, specifier }]`, where `kind` is a
+ *   route kind of the emitter's export table, `target` the file's path under
+ *   `src/app`, and `specifier` the `@nextsparkjs/core/routes/...` subpath that
+ *   implements it. Sorted by target.
+ * - `src/routes/variants.json`: routes that replace a manifest entry when the host
+ *   enables a Next.js mode. Today only `cacheComponents`: the root layout
+ *   `layout.ppr.tsx`, the `layout.cc.tsx` files of the five layouts that load messages (their
+ *   `getMessages()` cannot be awaited outside Suspense while prerendering) and the `page.cc.tsx`
+ *   files of the routes whose segment config Next.js rejects under Cache Components (login,
+ *   signup, both docs pages).
+ * - A layout that wraps whatever layout the host resolves (the root layout and the four group
+ *   layouts) carries `compose: { wrapper, specifier }` (`COMPOSED_ROUTES`): a project override
+ *   of it is composed with that wrapper by the generated host instead of replacing it.
+ * - The layouts of the role-gated areas (/superadmin, /devtools) carry `access: { wrapper, specifier }`
+ *   (`ACCESS_ROUTES`): the generated host composes every other page and layout under that directory, core's,
+ *   a plugin's or the project's, with that wrapper, so each segment checks the role on the server before it
+ *   renders (a layout cannot protect its pages: Next renders every segment of a route separately).
+ *
+ * A file is a route when its name is `<kind stem>.{tsx,ts}` (`page.tsx`,
+ * `route.ts`, `icon2.tsx`, ...). Directories starting with `_` hold route
+ * helpers (`_internal/`) and are skipped, as Next.js skips private folders.
+ * A file whose name has another dot (`layout.ppr.tsx`) is a variant, never a
+ * manifest entry.
+ *
+ * Usage:
+ *   node scripts/build/routes-manifest.mjs           write both files
+ *   node scripts/build/routes-manifest.mjs --check   exit 1 when either is stale
+ *
+ * @module core/scripts/build/routes-manifest
+ */
+
+import { readdirSync, readFileSync } from 'node:fs'
+import { dirname, join, posix, relative, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { kindForFileStem } from './registry/host/facade-emitter.mjs'
+import { projectFiles } from './safe-fs.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+
+/** Where core's route modules live. */
+export const ROUTES_DIR = join(HERE, '../../src/routes')
+
+/** The package subpath every route module is exported under. */
+export const ROUTES_SUBPATH = '@nextsparkjs/core/routes'
+
+const ROUTE_EXTENSIONS = ['tsx', 'ts']
+
+/**
+ * Variant files by Next.js mode: `{ mode: { variant file: target it replaces } }`.
+ * The variant must exist and the target must be a manifest entry.
+ */
+export const VARIANT_FILES = Object.freeze({
+  cacheComponents: Object.freeze({
+    'layout.ppr.tsx': 'layout.tsx',
+    '(auth)/layout.cc.tsx': '(auth)/layout.tsx',
+    '(public)/layout.cc.tsx': '(public)/layout.tsx',
+    'superadmin/layout.cc.tsx': 'superadmin/layout.tsx',
+    'devtools/layout.cc.tsx': 'devtools/layout.tsx',
+    'dashboard/layout.cc.tsx': 'dashboard/layout.tsx',
+    '(auth)/login/page.cc.tsx': '(auth)/login/page.tsx',
+    '(auth)/signup/page.cc.tsx': '(auth)/signup/page.tsx',
+    '(public)/docs/[section]/[page]/page.cc.tsx': '(public)/docs/[section]/[page]/page.tsx',
+    'superadmin/docs/[section]/[page]/page.cc.tsx': 'superadmin/docs/[section]/[page]/page.tsx',
+  }),
+})
+
+/**
+ * Layouts that a project override is composed with (target -> wrapper): the generated host writes
+ * `export default wrapper(Template)` for a project layout at that target, so the override renders
+ * inside what core's layout provides (providers, message scopes) instead of replacing it.
+ */
+export const COMPOSED_ROUTES = Object.freeze({
+  'layout.tsx': { wrapper: 'withRootLayout', specifier: `${ROUTES_SUBPATH}/_internal/root-layout` },
+  '(auth)/layout.tsx': { wrapper: 'withAuthMessages', specifier: `${ROUTES_SUBPATH}/_internal/auth-layout` },
+  '(public)/layout.tsx': { wrapper: 'withPublicMessages', specifier: `${ROUTES_SUBPATH}/_internal/public-layout` },
+  'superadmin/layout.tsx': { wrapper: 'withSuperadminGuard', specifier: `${ROUTES_SUBPATH}/_internal/superadmin-layout` },
+  'devtools/layout.tsx': { wrapper: 'withDevtoolsGuard', specifier: `${ROUTES_SUBPATH}/_internal/devtools-layout` },
+})
+
+/**
+ * The layouts of the areas only some roles may enter (target -> the wrapper every page and layout under it is
+ * composed with, the one their `generateMetadata` is, and the one a Route Handler's methods are). The layout itself is checked by its own message wrapper
+ * (area-access).
+ */
+export const ACCESS_ROUTES = Object.freeze({
+  'superadmin/layout.tsx': { wrapper: 'withSuperadminAccess', metadata: 'withSuperadminMetadata', handler: 'withSuperadminRouteAccess', specifier: `${ROUTES_SUBPATH}/_internal/area-access` },
+  'devtools/layout.tsx': { wrapper: 'withDevtoolsAccess', metadata: 'withDevtoolsMetadata', handler: 'withDevtoolsRouteAccess', specifier: `${ROUTES_SUBPATH}/_internal/area-access` },
+})
+
+/** The composition of a variant, when it differs from its base route's. */
+export const VARIANT_COMPOSE = Object.freeze({
+  'layout.ppr.tsx': { wrapper: 'withRootLayout', specifier: `${ROUTES_SUBPATH}/_internal/root-layout.ppr` },
+  '(auth)/layout.cc.tsx': { wrapper: 'withAuthMessages', specifier: `${ROUTES_SUBPATH}/_internal/auth-layout.cc` },
+  '(public)/layout.cc.tsx': { wrapper: 'withPublicMessages', specifier: `${ROUTES_SUBPATH}/_internal/public-layout.cc` },
+  'superadmin/layout.cc.tsx': { wrapper: 'withSuperadminGuard', specifier: `${ROUTES_SUBPATH}/_internal/superadmin-layout.cc` },
+  'devtools/layout.cc.tsx': { wrapper: 'withDevtoolsGuard', specifier: `${ROUTES_SUBPATH}/_internal/devtools-layout.cc` },
+})
+
+/**
+ * Files that live next to a route without being one: the API explorer's presets, read as text by the
+ * registry build (registry/discovery/api-presets.mjs), and its docs.md.
+ */
+const ROUTE_DATA_FILES = Object.freeze(['presets.ts'])
+
+function listFiles(dir, base = dir) {
+  const files = []
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (entry.name.startsWith('_')) continue
+      files.push(...listFiles(join(dir, entry.name), base))
+    } else if (entry.isFile()) {
+      files.push(relative(base, join(dir, entry.name)).split(sep).join('/'))
+    }
+  }
+  return files
+}
+
+function splitRouteFile(file) {
+  const name = posix.basename(file)
+  const dot = name.lastIndexOf('.')
+  if (dot === -1 || !ROUTE_EXTENSIONS.includes(name.slice(dot + 1))) return null
+  return { stem: name.slice(0, dot), extension: name.slice(dot + 1) }
+}
+
+/** The core subpath of a route file (`api/v1/users/route.ts` -> `@nextsparkjs/core/routes/api/v1/users/route`). */
+export function specifierForRouteFile(file) {
+  return `${ROUTES_SUBPATH}/${file.replace(/\.(tsx|ts)$/, '')}`
+}
+
+/**
+ * Build the manifest and the variants from the files under `routesDir`.
+ *
+ * @returns {{ manifest: Array<{kind: string, target: string, specifier: string}>, variants: Record<string, Array<{kind: string, target: string, specifier: string}>> }}
+ */
+export function buildRoutesManifest(routesDir = ROUTES_DIR) {
+  const files = listFiles(routesDir)
+  const manifest = []
+  const seenTargets = new Map()
+  for (const file of files) {
+    const parts = splitRouteFile(file)
+    if (!parts) continue
+    const kind = kindForFileStem(parts.stem)
+    if (!kind) continue
+    const routeKey = file.replace(/\.(tsx|ts)$/, '')
+    if (seenTargets.has(routeKey)) {
+      throw new Error(`Two route files for one route: ${seenTargets.get(routeKey)} and ${file}; keep one extension`)
+    }
+    seenTargets.set(routeKey, file)
+    const compose = COMPOSED_ROUTES[file]
+    const access = ACCESS_ROUTES[file]
+    manifest.push({ kind, target: file, specifier: specifierForRouteFile(file), ...(compose ? { compose } : {}), ...(access ? { access } : {}) })
+  }
+  manifest.sort((a, b) => (a.target < b.target ? -1 : a.target > b.target ? 1 : 0))
+
+  const variants = {}
+  for (const [mode, byFile] of Object.entries(VARIANT_FILES)) {
+    variants[mode] = Object.entries(byFile).map(([file, target]) => {
+      if (!files.includes(file)) throw new Error(`Variant ${file} (${mode}) is missing from ${routesDir}`)
+      const replaced = manifest.find(entry => entry.target === target)
+      if (!replaced) throw new Error(`Variant ${file} (${mode}) replaces ${target}, which is not a core route`)
+      const compose = VARIANT_COMPOSE[file] ?? replaced.compose
+      return { kind: replaced.kind, target, specifier: specifierForRouteFile(file), ...(compose ? { compose } : {}), ...(replaced.access ? { access: replaced.access } : {}) }
+    })
+  }
+  return { manifest, variants }
+}
+
+/** Every file under `routesDir` that looks like a route file but is not one the manifest or variants list. */
+export function unlistedRouteLikeFiles(routesDir = ROUTES_DIR) {
+  const { manifest } = buildRoutesManifest(routesDir)
+  const listed = new Set(manifest.map(entry => entry.target))
+  for (const byFile of Object.values(VARIANT_FILES)) for (const file of Object.keys(byFile)) listed.add(file)
+  return listFiles(routesDir).filter(file => splitRouteFile(file) && !listed.has(file) && !ROUTE_DATA_FILES.includes(posix.basename(file)))
+}
+
+export function renderJson(value) {
+  return JSON.stringify(value, null, 2) + '\n'
+}
+
+function main() {
+  const check = process.argv.includes('--check')
+  const { manifest, variants } = buildRoutesManifest()
+  const outputs = [
+    [join(ROUTES_DIR, 'manifest.json'), renderJson(manifest)],
+    [join(ROUTES_DIR, 'variants.json'), renderJson(variants)],
+  ]
+  let stale = 0
+  for (const [path, content] of outputs) {
+    let current = null
+    try {
+      current = readFileSync(path, 'utf8')
+    } catch {}
+    if (current === content) continue
+    if (check) {
+      console.error(`${relative(process.cwd(), path)} is stale; run node packages/core/scripts/build/routes-manifest.mjs`)
+      stale++
+    } else {
+      projectFiles(ROUTES_DIR).writeFile(path, content, 'utf8')
+      console.log(`Wrote ${relative(process.cwd(), path)} (${path.endsWith('manifest.json') ? manifest.length : Object.values(variants).flat().length} entries)`)
+    }
+  }
+  process.exitCode = stale > 0 ? 1 : 0
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) main()

package/scripts/build/safe-fs.mjs

@@ -1,7 +1,6 @@
 /**
  * The one way the generator writes, creates directories, renames and removes:
- * the registry build and the rest of scripts/build, and `nextspark sync:app`,
- * which loads this module from the core installed in the project. No other file
+ * the registry build and the rest of scripts/build. No other file
  * of the generator calls fs to change anything; a test fails when one does.
  *
  * Each call is bound to a root, the directory it may change things under: the