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

package/scripts/build/registry/generators/docs-registry.mjs

@@ -7,9 +7,8 @@
  * @module core/scripts/build/registry/generators/docs-registry
  */
 
-import fs from 'fs'
+import { existsSync, readdirSync } from 'fs'
 import path from 'path'
-import { existsSync } from 'fs'
 import { CONFIG } from '../config.mjs'
 
 // Get config values - use themesDir which correctly handles monorepo mode
@@ -59,7 +58,7 @@ function scanDocsDirectory(docsPath, source) {
   }
 
   const sections = []
-  const items = fs.readdirSync(docsPath, { withFileTypes: true })
+  const items = readdirSync(docsPath, { withFileTypes: true })
 
   for (const item of items) {
     if (!item.isDirectory()) continue
@@ -70,7 +69,7 @@ function scanDocsDirectory(docsPath, source) {
     const title = slugToTitle(slug)
 
     const pages = []
-    const files = fs.readdirSync(sectionPath)
+    const files = readdirSync(sectionPath)
 
     for (const file of files) {
       if (!file.endsWith('.md')) continue

package/scripts/build/registry/generators/feature-registry.mjs

@@ -13,7 +13,7 @@
  * @module core/scripts/build/registry/generators/testing-registry
  */
 
-import { readFileSync, writeFileSync, existsSync } from 'fs'
+import { readFileSync, existsSync } from 'fs'
 import { join } from 'path'
 import { discoverTestTags, validateTags } from '../discovery/test-tags.mjs'
 

package/scripts/build/registry/generators/permissions-registry.mjs

@@ -10,7 +10,7 @@ import { readFile } from 'fs/promises'
 import { join, dirname } from 'path'
 import { fileURLToPath } from 'url'
 
-import { log, verbose } from '../../../utils/index.mjs'
+import { errorWithLines, log, verbose } from '../../../utils/index.mjs'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -187,7 +187,7 @@ export async function generatePermissionsRegistry(permissionsConfig, entities, c
       errorLines.push('     the "slug" field in the corresponding entity.config.ts')
       errorLines.push('')
 
-      throw new Error(errorLines.join('\n'))
+      throw errorWithLines(errorLines)
     }
 
     log('  ✅ All permission entity keys validated against discovered entities', 'info')

package/scripts/build/registry/generators/template-registry.mjs

@@ -15,6 +15,7 @@ import {
   canOverrideComponent
 } from '../../../../dist/config/protected-paths.js'
 import { convertCorePath } from '../config.mjs'
+import { analyzeTemplates, routeFileAction, templateAnalysisFor } from '../post-build/page-generator.mjs'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -23,13 +24,22 @@ const __dirname = dirname(__filename)
 const rootDir = join(__dirname, '../../../../../..')
 
 /**
- * Generate the template registry file
- * @param {Array} templates - Discovered templates
- * @param {object} config - Configuration object from getConfig()
- * @returns {string} Generated TypeScript content
+ * The analysis a generator works from: the one the registry build passes in,
+ * or - for a caller using the signature without it - one taken for this call,
+ * against the project root template files are resolved from here.
  */
-export function generateTemplateRegistry(templates, config) {
-  // Group templates by app path to handle multiple themes overriding the same path
+async function analysisFor(templates, config, analysis) {
+  return analysis ?? analyzeTemplates(templates, { projectRoot: config?.projectRoot || rootDir })
+}
+
+/**
+ * Group templates by app path (highest priority first), each with whether its
+ * highest-priority template has a default export. That answer comes from
+ * `analyzeTemplates`, which parsed the template once for the whole build: the
+ * server registry, the client registry and the page generator all take it
+ * from there, so none of them can see a different version of the file.
+ */
+function resolveTemplateEntries(templates, analysis) {
   const templatesByPath = {}
 
   templates.forEach(template => {
@@ -39,16 +49,36 @@ export function generateTemplateRegistry(templates, config) {
     templatesByPath[template.appPath].push(template)
   })
 
-  // Sort templates by priority (higher priority first)
   Object.keys(templatesByPath).forEach(appPath => {
     templatesByPath[appPath].sort((a, b) => b.priority - a.priority)
   })
 
+  // A template whose route file would break is rejected here too, whoever built the analysis
+  for (const template of templates) {
+    routeFileAction(template, templateAnalysisFor(analysis, template))
+  }
+
+  return Object.entries(templatesByPath).map(([appPath, pathTemplates]) => {
+    const highestPriorityTemplate = pathTemplates[0]
+    const { hasDefaultExport } = templateAnalysisFor(analysis, highestPriorityTemplate)
+    return { appPath, pathTemplates, highestPriorityTemplate, hasDefaultExport }
+  })
+}
+
+/**
+ * Generate the template registry file
+ * @param {Array} templates - Discovered templates
+ * @param {object} config - Configuration object from getConfig()
+ * @param {Map} [analysis] - What `analyzeTemplates` read from these templates; taken for this call when omitted
+ * @returns {Promise<string>} Generated TypeScript content
+ */
+export async function generateTemplateRegistry(templates, config, analysis = null) {
+  const entries = resolveTemplateEntries(templates, await analysisFor(templates, config, analysis))
+
   // Generate registry entries. Each component is a deferred import, so a route
   // pulls in the template it renders and no others.
-  const registryEntries = Object.entries(templatesByPath)
-    .map(([appPath, pathTemplates]) => {
-      const highestPriorityTemplate = pathTemplates[0]
+  const registryEntries = entries
+    .map(({ appPath, pathTemplates, highestPriorityTemplate, hasDefaultExport }) => {
       // Strip .tsx/.ts extension - Next.js resolves extensions automatically on all platforms
       let templatePath = highestPriorityTemplate.templatePath
       if (templatePath.endsWith('.tsx')) {
@@ -57,12 +87,12 @@ export function generateTemplateRegistry(templates, config) {
         templatePath = templatePath.slice(0, -3)
       }
 
-      // Metadata-only templates (PROTECTED_RENDER or standalone .meta.ts) have
-      // no component to load
+      // Metadata-only templates (PROTECTED_RENDER, standalone .meta.ts, or a
+      // template with no default export) have no component to load
       const isMetaOnly = highestPriorityTemplate.fileName?.endsWith('.meta.ts')
-      const componentRef = (!canOverrideComponent(appPath) || isMetaOnly)
-        ? 'null'
-        : `lazyTemplate('${appPath}', () => import('${templatePath}'))`
+      const componentRef = canOverrideComponent(appPath) && !isMetaOnly && hasDefaultExport
+        ? `lazyTemplate('${appPath}', () => import('${templatePath}'))`
+        : 'null'
 
       return `  '${appPath}': {
     appPath: '${appPath}',
@@ -74,7 +104,7 @@ export function generateTemplateRegistry(templates, config) {
     .join(',\n')
 
   // Generate utility functions for template resolution
-  const templatePaths = Object.keys(templatesByPath)
+  const templatePaths = entries.map(({ appPath }) => appPath)
   const templateTypeMap = {}
 
   templates.forEach(template => {
@@ -220,40 +250,27 @@ async function hasServerOnlyExports(filePath) {
  * Excludes templates with server-only exports (generateMetadata, revalidate, etc.)
  * @param {Array} templates - Discovered templates
  * @param {object} config - Configuration object from getConfig()
+ * @param {Map} [analysis] - What `analyzeTemplates` read from these templates; taken for this call when omitted
  * @returns {Promise<string>} Generated TypeScript content
  */
-export async function generateTemplateRegistryClient(templates, config) {
+export async function generateTemplateRegistryClient(templates, config, analysis = null) {
   const outputFilePath = join(config.outputDir, 'template-registry.client.ts')
-  // Group templates by app path
-  const templatesByPath = {}
-
-  templates.forEach(template => {
-    if (!templatesByPath[template.appPath]) {
-      templatesByPath[template.appPath] = []
-    }
-    templatesByPath[template.appPath].push(template)
-  })
-
-  // Sort templates by priority (higher priority first)
-  Object.keys(templatesByPath).forEach(appPath => {
-    templatesByPath[appPath].sort((a, b) => b.priority - a.priority)
-  })
-
-  // Filter for client-compatible templates (pages only, not layouts)
-  // Also exclude templates with server-only exports
-  const clientCompatibleTemplatesPromises = Object.entries(templatesByPath)
-    .filter(([appPath, pathTemplates]) => {
-      const template = pathTemplates[0]
-      // Only include page templates (not layouts) that can override components
-      return (template.templateType === 'page' || template.templateType === 'layout') && canOverrideComponent(appPath)
-    })
-    .map(async ([appPath, pathTemplates]) => {
-      const template = pathTemplates[0]
+  const projectRoot = config.projectRoot || rootDir
+  const entries = resolveTemplateEntries(templates, await analysisFor(templates, config, analysis))
+
+  // Filter for client-compatible templates: pages and layouts, not protected,
+  // with a default export according to the build's analysis - the same answer
+  // the server registry uses. Also exclude templates with server-only exports.
+  const clientCompatibleTemplatesPromises = entries
+    .filter(({ appPath, highestPriorityTemplate, hasDefaultExport }) =>
+      (highestPriorityTemplate.templateType === 'page' || highestPriorityTemplate.templateType === 'layout') &&
+      canOverrideComponent(appPath) &&
+      hasDefaultExport
+    )
+    .map(async ({ appPath, highestPriorityTemplate }) => {
       // Get actual file path from template path
       // Template paths may or may not have extension, ensure we check the .tsx file
-      // In npm mode, use config.projectRoot instead of rootDir (which is relative to script)
-      const projectRoot = config.projectRoot || rootDir
-      let actualFilePath = template.templatePath.replace('@/', projectRoot + '/')
+      let actualFilePath = highestPriorityTemplate.templatePath.replace('@/', projectRoot + '/')
       // If path doesn't end with .tsx or .ts, add .tsx
       if (!actualFilePath.endsWith('.tsx') && !actualFilePath.endsWith('.ts')) {
         actualFilePath += '.tsx'
@@ -265,7 +282,7 @@ export async function generateTemplateRegistryClient(templates, config) {
         verbose(`Excluding ${appPath} from client registry (has server-only exports)`)
         return null
       }
-      return [appPath, pathTemplates]
+      return { appPath, highestPriorityTemplate }
     })
 
   const clientCompatibleTemplatesResults = await Promise.all(clientCompatibleTemplatesPromises)
@@ -274,10 +291,9 @@ export async function generateTemplateRegistryClient(templates, config) {
   // Generate registry entries as deferred imports, so a route loads the
   // template it renders and no others
   const registryEntries = clientCompatibleTemplates
-    .map(([appPath, pathTemplates]) => {
-      const template = pathTemplates[0]
+    .map(({ appPath, highestPriorityTemplate }) => {
       // Strip .tsx/.ts extension - Next.js resolves extensions automatically on all platforms
-      let templatePath = template.templatePath
+      let templatePath = highestPriorityTemplate.templatePath
       if (templatePath.endsWith('.tsx')) {
         templatePath = templatePath.slice(0, -4)
       } else if (templatePath.endsWith('.ts')) {

package/scripts/build/registry/index.mjs

@@ -29,7 +29,6 @@ export {
 
 // Generators
 export {
-  generateAll,
   generatePluginRegistry,
   generatePluginRegistryClient,
   generateEntityRegistry,
@@ -52,7 +51,7 @@ export {
 
 // Post-build tasks
 export {
-  runPostBuild,
+  analyzeTemplates,
   generateMissingPages,
   generateTemplatePage,
   displayTreeStructure,

package/scripts/build/registry/post-build/index.mjs

@@ -6,7 +6,7 @@
  * @module core/scripts/build/registry/post-build
  */
 
-export { generateMissingPages, generateTemplatePage } from './page-generator.mjs'
+export { analyzeTemplates, generateMissingPages, generateTemplatePage } from './page-generator.mjs'
 export { displayTreeStructure } from './tree-display.mjs'
 export { generateTestEntitiesJson, generateTestBlocksJson, extractEntityTestData } from './test-fixtures.mjs'
 export {

package/scripts/build/registry/post-build/own-gitignores.mjs

@@ -0,0 +1,220 @@
+/**
+ * The .gitignore files nextspark keeps in the two directories none of whose
+ * content has a place in git: .nextspark/backups, where each backup of a file
+ * the registry build or `nextspark sync:app` replaces or removes goes into a
+ * directory named as it is created, and .nextspark/registries, which the
+ * registry build writes again on every run. A .gitignore in a directory that
+ * ignores everything in it covers all of it, named however and holding any
+ * .gitignore of its own: git takes the patterns of the deepest .gitignore over
+ * those of any other, the repository's exclude file and core.excludesFile, and
+ * doesn't look into a directory it ignores. So what goes there that git does
+ * not track yet stays out of git whatever command writes it and whatever the
+ * project's rules say. What git already tracks there - registries committed
+ * before - a .gitignore leaves tracked: each build that rewrites them leaves
+ * them modified in git, and says so, with how to stop tracking them.
+ *
+ * `nextspark sync:app` reads them, and writes the one for backups, through this
+ * module, loaded from the core installed in the project.
+ *
+ * @module core/scripts/build/registry/post-build/own-gitignores
+ */
+
+import { execFileSync } from 'child_process'
+import { lstatSync, readFileSync } from 'fs'
+import { lstat } from 'fs/promises'
+import { join, posix } from 'path'
+import { projectFiles } from '../../safe-fs.mjs'
+
+export const BACKUPS_GITIGNORE = '.nextspark/backups/.gitignore'
+
+export const REGISTRIES_GITIGNORE = '.nextspark/registries/.gitignore'
+
+export const BACKUPS_GITIGNORE_CONTENT = '# Backups nextspark keeps on this machine: none of them belongs in git\n*\n'
+
+export const REGISTRIES_GITIGNORE_CONTENT = '# Registries the nextspark registry build writes again on every run: none of them belongs in git\n*\n'
+
+const CONTENTS = {
+  [BACKUPS_GITIGNORE]: BACKUPS_GITIGNORE_CONTENT,
+  [REGISTRIES_GITIGNORE]: REGISTRIES_GITIGNORE_CONTENT,
+}
+
+/**
+ * A .gitignore line's pattern as git takes it: without a closing carriage
+ * return, or the spaces that end it unless a backslash escapes the last one.
+ */
+function patternAsGitReadsIt(line) {
+  const withoutReturn = line.replace(/\r$/, '')
+  let end = withoutReturn.length
+  let lastSpace = -1
+  for (let index = 0; index < withoutReturn.length; index++) {
+    const character = withoutReturn[index]
+    if (character === ' ') {
+      if (lastSpace === -1) lastSpace = index
+    } else {
+      if (character === '\\') index++
+      lastSpace = -1
+    }
+  }
+  if (lastSpace !== -1) end = lastSpace
+  return withoutReturn.slice(0, end)
+}
+
+/**
+ * What one of those .gitignore files is: absent; in place, when `*` is the only
+ * pattern git reads in it, whatever its comments; a symlink, which git does not
+ * read; not a file; a file that can't be read, which may hold anything; or a
+ * file with other patterns, which can take back what is beside it.
+ *
+ * @param {string} rootDir - The project root
+ * @param {string} path - BACKUPS_GITIGNORE or REGISTRIES_GITIGNORE
+ * @returns {'missing' | 'in place' | 'symlink' | 'not a file' | 'unreadable' | 'other'}
+ */
+export function ownGitignoreState(rootDir, path) {
+  const absolute = join(rootDir, path)
+  let stat
+  try {
+    stat = lstatSync(absolute)
+  } catch (error) {
+    return error.code === 'ENOENT' || error.code === 'ENOTDIR' ? 'missing' : 'unreadable'
+  }
+  if (stat.isSymbolicLink()) return 'symlink'
+  if (!stat.isFile()) return 'not a file'
+
+  let content
+  try {
+    content = readFileSync(absolute, 'utf8')
+  } catch {
+    return 'unreadable'
+  }
+  const patterns = content
+    .replace(/^\uFEFF/, '')
+    .split('\n')
+    .map(patternAsGitReadsIt)
+    .filter(line => line !== '' && !line.startsWith('#'))
+  return patterns.length === 1 && patterns[0] === '*' ? 'in place' : 'other'
+}
+
+/**
+ * What .nextspark/backups/.gitignore is, as `ownGitignoreState` reads it.
+ *
+ * @param {string} rootDir - The project root
+ */
+export function backupsGitignoreState(rootDir) {
+  return ownGitignoreState(rootDir, BACKUPS_GITIGNORE)
+}
+
+/**
+ * What is wrong with one of those .gitignore files for keeping its directory
+ * out of git, by its state, and what to do about it; a state missing here is none.
+ */
+export const OWN_GITIGNORE_PROBLEMS = {
+  symlink: 'is a symlink, which git does not read, so git would pick up what is beside it: make it a file with * as its only pattern, or remove it for nextspark to write it',
+  'not a file': 'is not a file: remove it for nextspark to write it',
+  unreadable: "can't be read, so nothing says it keeps what is beside it out of git: make it readable, with * as its only pattern",
+  other: 'has patterns other than *, which can take what is beside it back into git: leave * as its only pattern, or remove it for nextspark to write it',
+}
+
+/**
+ * Why nothing can be written beside one of those .gitignore files with git kept
+ * out of it, and what to do about it, or null when it can.
+ */
+async function ownGitignoreBlocker(rootDir, path) {
+  for (const directory of ['.nextspark', posix.dirname(path)]) {
+    let stat
+    try {
+      stat = await lstat(join(rootDir, directory))
+    } catch {
+      break
+    }
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      return stat.isSymbolicLink()
+        ? `${directory} is a symlink: what is written through it lands wherever it points, where no .gitignore of the project keeps it out of git. Make ${directory} a directory of its own.`
+        : `${directory} is not a directory. Make it one.`
+    }
+  }
+
+  const problem = OWN_GITIGNORE_PROBLEMS[ownGitignoreState(rootDir, path)]
+  return problem ? `${path} ${problem}.` : null
+}
+
+/**
+ * Give a directory the .gitignore of its own, before anything is written in it.
+ * One already there is never written over: what it holds is the project's. When
+ * it can't keep the directory out of git - a symlink, not a file, unreadable,
+ * other patterns - or .nextspark or the directory is a symlink or not a
+ * directory, this throws, starting with `refusal`, so nothing is written there.
+ */
+async function ensureOwnGitignore(rootDir, path, refusal) {
+  const blocker = await ownGitignoreBlocker(rootDir, path)
+  if (blocker) throw new Error(`${refusal}: ${blocker}`)
+  if (ownGitignoreState(rootDir, path) === 'in place') return false
+
+  const files = projectFiles(rootDir)
+  await files.mkdir(join(rootDir, posix.dirname(path)), { recursive: true })
+  try {
+    await files.writeFile(join(rootDir, path), CONTENTS[path], { flag: 'wx' })
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error
+    // Another run wrote one in the meantime, which counts only if it is one that works
+    const blockerNow = await ownGitignoreBlocker(rootDir, path)
+    if (blockerNow) throw new Error(`${refusal}: ${blockerNow}`)
+    return false
+  }
+  return true
+}
+
+/**
+ * The files git tracks under `directory` of the project, as git names them from
+ * the project root; none when the project is not in a git repository or git is
+ * not installed.
+ *
+ * @param {string} rootDir - The project root
+ * @param {string} directory - A directory from the project root
+ * @returns {string[]}
+ */
+export function trackedFilesUnder(rootDir, directory) {
+  try {
+    return execFileSync('git', ['ls-files', '-z', '--', directory], {
+      cwd: rootDir,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      maxBuffer: 64 * 1024 * 1024,
+    }).split('\0').filter(Boolean)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * What to say when git tracks registries: that the build rewrites them and
+ * their .gitignore can't keep them out, and how to stop tracking them.
+ *
+ * @param {number} count - How many files git tracks under .nextspark/registries
+ * @returns {string[]} One line each
+ */
+export function trackedRegistriesLines(count) {
+  return [
+    `.nextspark/registries is tracked by git (${count} file(s)), but every registry build rewrites it: its .gitignore keeps out only what git does not track yet, so each build leaves those files modified in git.`,
+    'To stop tracking it: git rm -r --cached .nextspark/registries',
+  ]
+}
+
+/**
+ * Give .nextspark/backups its .gitignore before the first backup is written.
+ *
+ * @param {string} rootDir - The project root
+ * @returns {Promise<boolean>} Whether it was written
+ */
+export function ensureBackupsGitignore(rootDir) {
+  return ensureOwnGitignore(rootDir, BACKUPS_GITIGNORE, 'Nothing is backed up under .nextspark/backups')
+}
+
+/**
+ * Give .nextspark/registries its .gitignore before the first registry is written.
+ *
+ * @param {string} rootDir - The project root
+ * @returns {Promise<boolean>} Whether it was written
+ */
+export function ensureRegistriesGitignore(rootDir) {
+  return ensureOwnGitignore(rootDir, REGISTRIES_GITIGNORE, 'No registry is written under .nextspark/registries')
+}