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

package/scripts/build/registry/__tests__/write-places.test.mjs

@@ -1,6 +1,6 @@
 /**
  * Tests for the check of where the registry build writes, which the build runs
- * before writing anything and `nextspark sync:app` and `nextspark dev` run from
+ * before writing anything and `nextspark dev` and `prepare --watch` run from
  * the installed core: a symlink, something of another kind or that can't be
  * read, or a .gitignore of .nextspark/backups or .nextspark/registries that
  * would not keep what is beside it out of git, is found, and a build that finds
@@ -50,33 +50,17 @@ test('a symlink where the build or a caller writes, or something else in the way
   const outside = await directory()
   try {
     await writeIn(outside.root, 'dashboard/layout.tsx')
-    await mkdir(join(root, 'app'), { recursive: true })
     await writeIn(root, '.nextspark/backups/2026-09-16T00-00-00-000Z-q1w2e3/i18n.ts')
 
     assert.deepEqual(unsafeWritePlaces(root), [])
 
-    await symlink(outside.root, join(root, 'app/(templates)'))
-    assert.deepEqual(unsafeWritePlaces(root), [{ path: 'app/(templates)', problem: 'is a symlink' }])
-
-    await rm(join(root, 'app/(templates)'))
-    await mkdir(join(root, 'app/(templates)/(public)'), { recursive: true })
-    await symlink(join(outside.root, 'dashboard'), join(root, 'app/(templates)/(public)/dashboard'))
-    await symlink(join(outside.root, 'missing'), join(root, '.nextspark/sync-state.json'))
+    await symlink(join(outside.root, 'missing'), join(root, '.nextspark/generation.json'))
     await symlink(join(outside.root, 'dashboard'), join(root, '.nextspark/registries'))
-    await symlink(join(outside.root, 'dashboard'), join(root, 'app/dashboard'))
-    await symlink(join(outside.root, 'globals.css'), join(root, 'app/globals.css'))
-    assert.deepEqual(unsafeWritePlaces(root, ['app/dashboard/page.tsx', 'app/layout.tsx', 'i18n.ts', '.nextspark/sync-state.json']), [
-      { path: 'app/globals.css', problem: 'is a symlink' },
+    assert.deepEqual(unsafeWritePlaces(root, ['i18n.ts', '.nextspark/generation.json']), [
       { path: '.nextspark/registries', problem: 'is a symlink' },
-      { path: 'app/dashboard', problem: 'is a symlink' },
-      { path: '.nextspark/sync-state.json', problem: 'is a symlink' },
-      { path: 'app/(templates)/(public)/dashboard', problem: 'is a symlink' },
+      { path: '.nextspark/generation.json', problem: 'is a symlink' },
     ])
-    assert.deepEqual(unsafeWritePlaces(root).map(({ path }) => path), [
-      'app/globals.css',
-      '.nextspark/registries',
-      'app/(templates)/(public)/dashboard',
-    ], 'app/dashboard and the sync state count only for a caller that writes under them')
+    assert.deepEqual(unsafeWritePlaces(root).map(({ path }) => path), ['.nextspark/registries'], 'the generation record counts only for a caller that writes it')
 
     await rm(join(root, '.nextspark/registries'))
     await mkdir(join(root, '.nextspark/registries'))
@@ -85,29 +69,16 @@ test('a symlink where the build or a caller writes, or something else in the way
 
     await rm(join(root, '.nextspark/registries/index.ts'))
     await mkdir(join(root, '.nextspark/registries/index.ts'))
-    await mkdir(join(root, 'app/(templates)/(public)/page.tsx'), { recursive: true })
-    await rm(join(root, 'app/dashboard'))
-    await writeFile(join(root, 'app/dashboard'), '')
-    await rm(join(root, 'app/globals.css'))
-    await mkdir(join(root, 'app/globals.css'))
     await mkdir(join(root, 'i18n.ts'))
-    assert.deepEqual(unsafeWritePlaces(root, ['app/dashboard/page.tsx', 'app/layout.tsx', 'i18n.ts', '.nextspark/sync-state.json']), [
-      { path: 'app/globals.css', problem: 'is not a file' },
-      { path: 'app/dashboard', problem: 'is not a directory' },
+    assert.deepEqual(unsafeWritePlaces(root, ['i18n.ts', '.nextspark/generation.json']), [
       { path: 'i18n.ts', problem: 'is not a file' },
-      { path: '.nextspark/sync-state.json', problem: 'is a symlink' },
-      { path: 'app/(templates)/(public)/dashboard', problem: 'is a symlink' },
+      { path: '.nextspark/generation.json', problem: 'is a symlink' },
       { path: '.nextspark/registries/index.ts', problem: 'is not a file' },
-    ], 'a directory in app/(templates) where a file goes is left to the registry build')
+    ])
 
     await rm(join(root, '.nextspark'), { recursive: true })
     await writeFile(join(root, '.nextspark'), '')
-    await rm(join(root, 'app'), { recursive: true })
-    await symlink(outside.root, join(root, 'app'))
-    assert.deepEqual(unsafeWritePlaces(root), [
-      { path: 'app', problem: 'is a symlink' },
-      { path: '.nextspark', problem: 'is not a directory' },
-    ])
+    assert.deepEqual(unsafeWritePlaces(root), [{ path: '.nextspark', problem: 'is not a directory' }])
   } finally {
     await outside.cleanup()
     await cleanup()
@@ -117,25 +88,45 @@ test('a symlink where the build or a caller writes, or something else in the way
 test('a directory the build lists that cannot be read is found', { skip: RUNS_AS_ROOT }, async () => {
   const { root, cleanup } = await directory()
   try {
-    await mkdir(join(root, 'app/(templates)/dashboard'), { recursive: true })
     await mkdir(join(root, '.nextspark/registries'), { recursive: true })
     await mkdir(join(root, '.nextspark/backups'), { recursive: true })
-    await chmod(join(root, 'app/(templates)/dashboard'), 0)
     await chmod(join(root, '.nextspark/registries'), 0)
     await chmod(join(root, '.nextspark/backups'), 0)
     assert.deepEqual(unsafeWritePlaces(root), [
       { path: '.nextspark/backups', problem: "can't be read" },
       { path: '.nextspark/registries', problem: "can't be read" },
-      { path: 'app/(templates)/dashboard', problem: "can't be read" },
     ])
   } finally {
-    await chmod(join(root, 'app/(templates)/dashboard'), 0o755).catch(() => {})
     await chmod(join(root, '.nextspark/registries'), 0o755).catch(() => {})
     await chmod(join(root, '.nextspark/backups'), 0o755).catch(() => {})
     await cleanup()
   }
 })
 
+test('the template-scopes registries an older build left may be a directory (the host removes them), and are still guarded', async () => {
+  const { root, cleanup } = await directory()
+  const outside = await directory()
+  try {
+    await writeIn(root, '.nextspark/registries/template-scopes/server/(public)/page.ts', '/** Auto-generated route-scoped template registry; do not edit. */\n')
+    assert.deepEqual(unsafeWritePlaces(root), [])
+
+    await symlink(join(outside.root, 'scope'), join(root, '.nextspark/registries/template-scopes/server/(public)/link'))
+    assert.deepEqual(unsafeWritePlaces(root), [{ path: '.nextspark/registries/template-scopes/server/(public)/link', problem: 'is a symlink' }])
+    await rm(join(root, '.nextspark/registries/template-scopes/server/(public)/link'))
+
+    await rm(join(root, '.nextspark/registries/template-scopes'), { recursive: true })
+    await writeIn(root, '.nextspark/registries/template-scopes', '')
+    assert.deepEqual(unsafeWritePlaces(root), [{ path: '.nextspark/registries/template-scopes', problem: 'is not a directory' }])
+
+    await rm(join(root, '.nextspark/registries/template-scopes'))
+    await mkdir(join(root, '.nextspark/registries/other'), { recursive: true })
+    assert.deepEqual(unsafeWritePlaces(root), [{ path: '.nextspark/registries/other', problem: 'is not a file' }], 'no other subtree is')
+  } finally {
+    await outside.cleanup()
+    await cleanup()
+  }
+})
+
 test('a .nextspark/backups/.gitignore counts as in place only as a readable file with * as its one pattern, and anything else is found', async () => {
   const contents = [
     ['*\n', 'in place'],
@@ -230,7 +221,7 @@ test('the .gitignore kept in .nextspark/backups ignores a backup whatever its di
     await writeIn(root, '.nextspark/.gitignore', '!backups/\n!backups/**\n')
     await writeIn(root, '.nextspark/backups/2026-09-16T00-00-00-000Z-r3g1st/.gitignore', '!*\n')
     const backups = [
-      '.nextspark/backups/2026-09-16T00-00-00-000Z-Zz9Qa1/app/(templates)/(public)/page.tsx',
+      '.nextspark/backups/2026-09-16T00-00-00-000Z-Zz9Qa1/src/app/(templates)/(public)/page.tsx',
       '.nextspark/backups/2026-09-16T00-00-00-000Z-r3g1st/i18n.ts',
       '.nextspark/backups/named by hand/.env.local',
     ]
@@ -274,21 +265,19 @@ async function snapshot(root) {
   return entries
 }
 
-/** A project for core's real registry build, with a stale file in app/(templates) the build would back up and remove. */
+/** A project for core's real registry build. */
 async function buildableProject() {
   const project = await directory()
-  await writeIn(project.root, '.env', 'NEXT_PUBLIC_ACTIVE_THEME=acme\n')
-  await writeIn(project.root, 'package.json', '{}')
-  await writeIn(project.root, 'app/layout.tsx', 'export default function Layout({ children }) { return children }\n')
-  await writeIn(project.root, 'app/(templates)/stale/page.tsx', 'export default function Stale() { return null }\n')
-  await writeIn(project.root, 'contents/themes/acme/templates/pricing/page.tsx', 'export default function Pricing() { return null }\n')
+  await writeIn(project.root, 'nextspark.config.ts', 'export default {}\n')
+  await writeIn(project.root, 'package.json', '{"dependencies":{"next":"16.3.5"}}')
+  await writeIn(project.root, 'templates/pricing/page.tsx', 'export default function Pricing() { return null }\n')
   return project
 }
 
 function runBuild(root) {
-  const result = spawnSync('node', ['scripts/build/registry.mjs'], {
-    cwd: CORE_DIR,
-    env: { ...process.env, NEXTSPARK_PROJECT_ROOT: root },
+  const result = spawnSync('node', [join(CORE_DIR, 'scripts/build/registry.mjs')], {
+    cwd: root,
+    env: process.env,
     encoding: 'utf8',
   })
   return { status: result.status, output: `${result.stdout}${result.stderr}` }
@@ -305,14 +294,6 @@ test("the registry build writes nothing, in the project or through it, when a pl
       await mkdir(join(root, '.nextspark'), { recursive: true })
       await symlink(outside, join(root, '.nextspark/registries'))
     }, '.nextspark/registries is a symlink'],
-    ['app/(templates) a symlink to a directory outside', async (root, outside) => {
-      await rm(join(root, 'app/(templates)'), { recursive: true })
-      await symlink(outside, join(root, 'app/(templates)'))
-    }, 'app/(templates) is a symlink'],
-    ['app/globals.css a symlink to a file outside', async (root, outside) => {
-      await writeIn(outside, 'globals.css', '/* outside */\n')
-      await symlink(join(outside, 'globals.css'), join(root, 'app/globals.css'))
-    }, 'app/globals.css is a symlink'],
     ['a directory where a registry goes', async root => {
       await writeIn(root, '.nextspark/registries/index.ts/stale.ts')
     }, '.nextspark/registries/index.ts is not a file'],
@@ -322,29 +303,17 @@ test("the registry build writes nothing, in the project or through it, when a pl
     ['a registries .gitignore that takes the registries back', async root => {
       await writeIn(root, REGISTRIES_GITIGNORE, '*\n!*.ts\n')
     }, `${REGISTRIES_GITIGNORE} has patterns other than *`],
-    ['app/api a symlink to a directory outside holding an old generated plugin route and another file', async (root, outside) => {
-      await writeIn(outside, 'v1/plugin/legacy/route.ts', '// Auto-generated Plugin Route Proxy\n')
-      await writeIn(outside, 'v1/plugin/legacy/other.ts', 'export const other = 1\n')
-      await symlink(outside, join(root, 'app/api'))
-    }, 'app/api is a symlink'],
-    ["the active theme's fixtures directory a symlink to one outside", async (root, outside) => {
+    ["the project's fixtures directory a symlink to one outside", async (root, outside) => {
       await writeIn(outside, 'entities.json', '{"outside":true}\n')
       await writeIn(outside, 'blocks.json', '{"outside":true}\n')
-      await mkdir(join(root, 'contents/themes/acme/tests/cypress'), { recursive: true })
-      await symlink(outside, join(root, 'contents/themes/acme/tests/cypress/fixtures'))
-    }, 'contents/themes/acme/tests/cypress/fixtures is a symlink'],
-    ["the active theme's entities.json a symlink to a file outside", async (root, outside) => {
+      await mkdir(join(root, 'tests/cypress'), { recursive: true })
+      await symlink(outside, join(root, 'tests/cypress/fixtures'))
+    }, 'tests/cypress/fixtures is a symlink'],
+    ["the project's entities.json a symlink to a file outside", async (root, outside) => {
       await writeIn(outside, 'entities.json', '{"outside":true}\n')
-      await mkdir(join(root, 'contents/themes/acme/tests/cypress/fixtures'), { recursive: true })
-      await symlink(join(outside, 'entities.json'), join(root, 'contents/themes/acme/tests/cypress/fixtures/entities.json'))
-    }, 'contents/themes/acme/tests/cypress/fixtures/entities.json is a symlink'],
-    ['the active theme a symlink to a directory outside with fixtures', async (root, outside) => {
-      await writeIn(outside, 'templates/pricing/page.tsx', 'export default function Pricing() { return null }\n')
-      await writeIn(outside, 'tests/cypress/fixtures/entities.json', '{"outside":true}\n')
-      await writeIn(outside, 'tests/cypress/fixtures/blocks.json', '{"outside":true}\n')
-      await rm(join(root, 'contents/themes/acme'), { recursive: true })
-      await symlink(outside, join(root, 'contents/themes/acme'))
-    }, 'contents/themes/acme is a symlink'],
+      await mkdir(join(root, 'tests/cypress/fixtures'), { recursive: true })
+      await symlink(join(outside, 'entities.json'), join(root, 'tests/cypress/fixtures/entities.json'))
+    }, 'tests/cypress/fixtures/entities.json is a symlink'],
     ...(RUNS_AS_ROOT ? [] : [['a backups .gitignore that cannot be read', async root => {
       await writeIn(root, BACKUPS_GITIGNORE, '*\n')
       await chmod(join(root, BACKUPS_GITIGNORE), 0)
@@ -375,51 +344,15 @@ test("the registry build writes nothing, in the project or through it, when a pl
 
   const control = await buildableProject()
   try {
-    await writeIn(control.root, 'app/api/v1/plugin/legacy/route.ts', '// Auto-generated Plugin Route Proxy\n')
-    await mkdir(join(control.root, 'contents/themes/acme/tests/cypress/fixtures'), { recursive: true })
+    await mkdir(join(control.root, 'tests/cypress/fixtures'), { recursive: true })
     const { status } = runBuild(control.root)
     if (status !== 0) wrong.push(`with nothing in the way, the build exited ${status}`)
     if (!existsSync(join(control.root, '.nextspark/registries/index.ts'))) wrong.push('with nothing in the way, the build wrote no registry')
-    if (existsSync(join(control.root, 'app/(templates)/stale/page.tsx'))) wrong.push('with nothing in the way, the build left the stale file')
-    if (existsSync(join(control.root, 'app/api/v1/plugin/legacy'))) wrong.push('with nothing in the way, the build left the old generated plugin route')
-    // entities.json is written only for a theme discovery finds, which this one, with no theme.config.ts, is not
-    if (!existsSync(join(control.root, 'contents/themes/acme/tests/cypress/fixtures/blocks.json'))) wrong.push('with nothing in the way, the build wrote no blocks.json')
+    if (existsSync(join(control.root, 'src'))) wrong.push('the registry build wrote into src')
+    if (!existsSync(join(control.root, 'tests/cypress/fixtures/blocks.json'))) wrong.push('with nothing in the way, the build wrote no blocks.json')
   } finally {
     await control.cleanup()
   }
 
   assert.deepEqual(wrong, [])
 })
-
-test("the registry build keeps .nextspark/registries out of git with a .gitignore of its own, while it runs and after, whatever the project's rules take back", async () => {
-  const project = await buildableProject()
-  const root = project.root
-  try {
-    execFileSync('git', ['init', '-q'], { cwd: root })
-    await writeFile(join(root, '.gitignore'), 'node_modules/\n.env\napp/(templates)/\n!.nextspark/\n!.nextspark/registries/**\n')
-    await writeIn(root, '.nextspark/.gitignore', '!registries/\n!registries/**\n')
-    await writeFile(join(root, '.git/info/exclude'), '!*\n')
-    const visible = () => execFileSync('git', ['status', '--porcelain', '--untracked-files=all'], { cwd: root, encoding: 'utf8' })
-      .split('\n').filter(line => line.includes('.nextspark/registries'))
-
-    const build = spawn('node', ['scripts/build/registry.mjs'], { cwd: CORE_DIR, env: { ...process.env, NEXTSPARK_PROJECT_ROOT: root }, stdio: 'ignore' })
-    let exited = null
-    build.on('exit', code => { exited = code })
-    const during = new Set()
-    let polls = 0
-    while (exited === null) {
-      for (const line of visible()) during.add(line)
-      polls++
-      await new Promise(resolve => setTimeout(resolve, 5))
-    }
-
-    assert.equal(exited, 0)
-    assert.ok(polls > 1, 'git was asked while the build ran')
-    assert.deepEqual([...during], [], 'git picks up no registry while the build runs')
-    assert.deepEqual(visible(), [], 'nor after')
-    assert.equal(await readFile(join(root, REGISTRIES_GITIGNORE), 'utf8'), REGISTRIES_GITIGNORE_CONTENT)
-    assert.ok(existsSync(join(root, '.nextspark/registries/index.ts')), 'the registries are written')
-  } finally {
-    await project.cleanup()
-  }
-})

package/scripts/build/registry/config.mjs

@@ -1,192 +1,54 @@
 /**
- * Registry Build Configuration
+ * Root-first registry build configuration.
  *
- * Central configuration for the registry build process.
- * Contains paths, flags, and content type definitions.
- *
- * Supports three modes:
- * 1. Monorepo mode: themes/plugins at repo root as workspace packages
- * 2. NPM mode: @nextsparkjs/core installed in node_modules
- * 3. User project mode: themes/plugins in contents/ directory
+ * All filesystem paths come from project-mode.mjs. Discovery modules consume
+ * the resolved project root and never select or search for a theme.
  *
  * @module core/scripts/build/registry/config
  */
 
-import { join, dirname } from 'path'
-import { fileURLToPath } from 'url'
-import { existsSync } from 'fs'
-import dotenv from 'dotenv'
+import { existsSync, readFileSync } from 'fs'
+import { join, resolve } from 'path'
+import { resolveProjectPaths, resolveProjectPluginSources, detectMonorepoRoot, isInstalledAsPackage } from './project-mode.mjs'
 import { loadNextSparkConfigSync } from '../config-loader.mjs'
-import { detectMonorepoRoot, isInstalledAsPackage } from './project-mode.mjs'
-import { shownPath } from '../../utils/logging.mjs'
-
-// 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)
-
-// Root directory (5 levels up from packages/core/scripts/build/registry/)
-export const rootDir = join(__dirname, '../../../../..')
 
 export { detectMonorepoRoot, isInstalledAsPackage }
 
-/**
- * Detect project root by searching for nextspark.config.ts or apps/dev in monorepo
- * @returns {string} Project root path
- */
-export function detectProjectRoot() {
-  // Check for explicit project root from CLI
-  if (process.env.NEXTSPARK_PROJECT_ROOT) {
-    return process.env.NEXTSPARK_PROJECT_ROOT
-  }
-
-  let dir = process.cwd()
-  const maxDepth = 10
-  let depth = 0
-
-  // Search upward for nextspark.config.ts
-  while (dir !== '/' && depth < maxDepth) {
-    // Primary: nextspark.config.ts
-    if (existsSync(join(dir, 'nextspark.config.ts'))) {
-      return dir
-    }
-    // Secondary: monorepo with apps/dev (development mode)
-    if (existsSync(join(dir, 'apps/dev'))) {
-      return join(dir, 'apps/dev')
-    }
-    dir = dirname(dir)
-    depth++
-  }
-
-  // If not found, use current working directory
-  return process.cwd()
+export function detectProjectRoot(startDir = process.cwd()) {
+  return resolveProjectPaths(startDir).projectRoot
 }
 
-/**
- * Get dynamic configuration based on project root
- * @param {string|null} projectRoot - Optional project root path
- * @returns {object} Configuration object
- */
 export function getConfig(projectRoot = null) {
-  // Determine project root
-  const root = projectRoot || detectProjectRoot()
-
-  // Check if running in npm mode
-  const isNpmMode = isInstalledAsPackage(root)
-
-  // Check if running in monorepo mode
-  const monorepoRoot = detectMonorepoRoot(root)
-  const isMonorepoMode = !isNpmMode && monorepoRoot !== null
-
-  // Determine paths based on mode
-  // In monorepo mode, core is at monorepoRoot/packages/core
-  // In npm mode, core is at projectRoot/node_modules/@nextsparkjs/core
-  const coreDir = isNpmMode
-    ? join(root, 'node_modules/@nextsparkjs/core')
-    : join(isMonorepoMode ? monorepoRoot : root, 'packages/core')
-
-  // ALWAYS generate in .nextspark/registries/ of the project
-  // This unifies npm mode and monorepo mode to use the same location
-  const outputDir = join(root, '.nextspark/registries')
-
-  // Load nextspark.config.ts for features and other settings
-  const nextsparkConfig = loadNextSparkConfigSync(root)
-
-  // Determine content directories based on mode
-  // Monorepo: themes/plugins at repo root as workspace packages
-  // User project: themes/plugins in contents/ directory
-  let contentsDir, themesDir, pluginsDir
-
-  if (isMonorepoMode) {
-    // Monorepo mode: themes and plugins are at the repo root
-    contentsDir = join(monorepoRoot, 'contents') // Legacy, kept for compatibility
-    themesDir = join(monorepoRoot, 'themes')
-    pluginsDir = join(monorepoRoot, 'plugins')
-  } else {
-    // User project mode (npm or standalone)
-    contentsDir = join(root, 'contents')
-    themesDir = join(root, 'contents/themes')
-    pluginsDir = join(root, 'contents/plugins')
-  }
+  const paths = resolveProjectPaths(projectRoot || process.cwd())
+  const nextsparkConfig = loadNextSparkConfigSync(paths.projectRoot)
+  const pluginSources = resolveProjectPluginSources(paths.projectRoot, nextsparkConfig.plugins)
+  const themeConfigPath = join(paths.projectRoot, 'config', 'theme.config.ts')
+  const themeConfig = existsSync(themeConfigPath) ? readFileSync(themeConfigPath, 'utf8') : ''
+  const projectName = themeConfig.match(/\bname:\s*['"]([^'"]+)['"]/)?.[1] || 'project'
 
   return {
-    projectRoot: root,
-    monorepoRoot,
-    isNpmMode,
-    isMonorepoMode,
-    coreDir,
-    outputDir,
-    contentsDir,
-    themesDir,
-    pluginsDir,
-    watchMode: process.argv.includes('--watch') && !process.argv.includes('--build'),
+    ...paths,
+    // `nextspark prepare` for a generated host stages the registries before publishing them
+    // (host/prepare.mjs): it points the build at its staging directory inside .nextspark/.
+    ...(process.env.NEXTSPARK_REGISTRIES_OUT ? { outputDir: resolve(paths.projectRoot, process.env.NEXTSPARK_REGISTRIES_OUT) } : {}),
+    projectName,
+    pluginRequests: nextsparkConfig.plugins,
+    pluginSources,
+    pluginDirs: pluginSources.map(plugin => plugin.sourceDir),
+    plugins: pluginSources.map(plugin => plugin.name),
+    features: nextsparkConfig.features,
+    billing: nextsparkConfig.billing,
     buildMode: process.argv.includes('--build'),
     verbose: process.argv.includes('--verbose') || process.argv.includes('-v'),
-    activeTheme: process.env.NEXT_PUBLIC_ACTIVE_THEME?.replace(/'/g, ''),
-    features: nextsparkConfig?.features || {
-      billing: true,
-      teams: true,
-      superadmin: true,
-      aiChat: true
-    }
   }
 }
 
-/**
- * Validate that required environment variables are present.
- * This should be called early in the build process to fail fast
- * with clear, actionable error messages.
- *
- * @param {object} config - Configuration object from getConfig()
- * @returns {{ valid: boolean, errors: string[] }} Validation result
- */
-export function validateEnvironment(config) {
-  const errors = []
-
-  // Check if .env file exists at the project root
-  // Skip this check in CI/Vercel environments where env vars are injected directly
-  const envFilePath = join(config.projectRoot, '.env')
-  const envExamplePath = join(config.projectRoot, '.env.example')
-  const hasEnvVarsFromProcess = !!process.env.NEXT_PUBLIC_ACTIVE_THEME
-
-  if (!existsSync(envFilePath) && !hasEnvVarsFromProcess) {
-    // The error spans lines, printed one per call: the path is shown on the one line it is on
-    let fix = `Create a .env file in your project root: ${shownPath(config.projectRoot)}`
-    if (existsSync(envExamplePath)) {
-      fix = `Copy the example file:\n   cp .env.example .env\n   Then update it with your configuration.`
-    }
-    errors.push(
-      `Missing .env file.\n` +
-      `   The .env file is required to configure your NextSpark application.\n` +
-      `   Fix: ${fix}\n` +
-      `   Required variable: NEXT_PUBLIC_ACTIVE_THEME (e.g., "default")`
-    )
-  }
-
-  // Check for NEXT_PUBLIC_ACTIVE_THEME
-  if (!config.activeTheme) {
-    errors.push(
-      `Missing NEXT_PUBLIC_ACTIVE_THEME environment variable.\n` +
-      `   This variable tells NextSpark which theme to use.\n` +
-      `   Fix: Add the following line to your .env file:\n` +
-      `   NEXT_PUBLIC_ACTIVE_THEME=default`
-    )
-  }
-
-  return { valid: errors.length === 0, errors }
+export function validateEnvironment() {
+  return { valid: true, errors: [] }
 }
 
-/**
- * Build configuration (legacy - for backward compatibility)
- * Uses getConfig() with no projectRoot (auto-detect)
- */
-export const CONFIG = getConfig()
+// Legacy named export for modules that accept an explicit config; compiler entrypoints call getConfig().
+export const CONFIG = null
 
 /**
  * Convert @/core/ import paths based on NPM mode

package/scripts/build/registry/contracts/README.md

@@ -0,0 +1,120 @@
+# Portable contracts
+
+`nextspark prepare` generates a module of **API contracts** from the project's entities (#203, stage 7b): the
+TypeScript DTO types and the zod schemas of every entity, and the API response envelopes. A client that must not
+import server code - the mobile app - imports it instead of writing the same types by hand.
+
+```ts
+import { Task, CreateTaskInput, createTaskInputSchema, apiListResponseSchema, tasksApiPath } from '@project/contracts'
+```
+
+The module imports `zod` and nothing else: no Node built-ins, no server code, no registries. It is a pure function of
+the entity configs, byte for byte (no timestamps), and is covered by `nextspark prepare --check`.
+
+## What is generated
+
+```
+src/index.ts             export * of the envelope, the shared field schemas and the entities
+src/envelope.ts          ApiSuccessResponse / ApiListResponse / ApiErrorResponse and their zod schemas
+src/fields.ts            re-exports of the schemas several field types share (address, uploaded file, media reference)
+src/schema/*.ts          core's portable schema sources, copied verbatim (lib/entities/portable/)
+src/entities/index.ts    export * of every entity
+src/entities/<slug>.ts   per entity: the entity descriptor, <slug>ApiPath, <Entity> + schema, Create<Entity>Input + schema,
+                         Update<Entity>Input + schema, and one enum (schema + type) per select / multiselect field with options
+contracts.generation.json   the ownership record: sha256 of every generated file
+```
+
+## One source with the server
+
+The contracts are never a second implementation of what the API accepts or returns:
+
+- **Requests are the server's schemas.** `packages/core/src/lib/entities/portable/` holds the code that decides what an entity API
+  accepts: `schema-generator.ts` (`generateEntitySchemas` and every field validator - builder `blocks` and `settings`, the PATCH
+  preprocessing that drops system and read-only keys, nullable and numeric-string normalization, defaults, `.strict()`), plus what it
+  imports. The server re-exports it (`lib/entities/schema-generator.ts`); prepare copies those files **verbatim** into
+  `src/schema/`, and each entity module calls `generateEntitySchemas` on a literal descriptor of the entity. A client validates with the
+  bytes the server enforces with. (`createTaskInputSchema` is typed `z.ZodType<CreateTaskInput>`: the types say what a client should send,
+  the schema also accepts what the server normalizes.)
+- **Responses are what the handlers select.** `portable/response-shape.ts` describes the row: `entityResponseSystemColumns` (id, `userId`
+  always, `teamId`, timestamps, `blocks` for builder entities, `deletedAt`/`deletedBy` where soft delete is on), `taxonomyResponseFields`
+  (each an array of `taxonomyTermSchema`), and the `metas` / `children` expansions. `generic-handler.ts` builds its SELECT lists from
+  those functions and prepare evaluates the same module while rendering the DTOs.
+- **Wire types follow the driver.** The API returns raw `pg` rows, and `pg` returns NUMERIC/DECIMAL/BIGINT/MONEY as strings unless a type
+  parser is configured (none is; a test fails if one appears). The column type is read from the entity's migrations
+  (`CREATE TABLE "<slug>"`, `ALTER TABLE ... ADD/ALTER COLUMN`; `pgWireKind` maps it): NUMERIC is `string`, INT/FLOAT `number`, a column
+  no migration declares `number | string`.
+
+Tests that pin this: `packages/core/tests/jest/lib/entities/contracts-parity.test.ts` (for every payload the contract accepts exactly
+when `generateEntitySchemas` does, on the real apps/dev entities; the copies are byte-identical), and
+`packages/core/tests/jest/api/entity/contracts-response-shape.test.ts` (the real handlers, DB mocked: the SELECT columns equal the DTO's,
+the response parses through the contract without losing a key).
+
+Other rules:
+
+- the **response** is `id`, `userId`, `teamId`, timestamps, `blocks`, the fields, the taxonomy fields, then the optional `metas` and
+  `children`. A field that is `required` or has a `defaultValue` is present; every other field is `nullish`;
+- field types map to what the server accepts and stores: text-like types and dates are `string` (ISO for dates), `select`-like types
+  with options are an enum, `multiselect` an array of the enum, `tags` an array of strings, `doublerange` a pair of numbers, `address`,
+  `file`/`video`/`audio`/`image` and `media-library` use the shared schemas, `relation-multi` sends an array (the response may carry the
+  JSON string the server stores), `json` and anything unknown are `unknown`;
+- a field's custom `validation` schema is not part of the contract (the server's generator does not use it either);
+- `childEntities` ARE part of the contract: they are serialized into the entity descriptor (table and fields, through imports and
+  spreads), so the copied generator adds the same `children` to the request schemas as on the server, and the input types type each child
+  row from the child's own fields (required unless it has a default, enum options, numbers as a number or a numeric string, an optional
+  `id`). A `childEntities` that cannot be described exactly (spread in, computed, a non-literal field) fails generation with a diagnostic
+  instead of publishing a schema that contradicts the server's. The rows a `?child=` request returns stay `unknown` in the response.
+
+Entities in the contracts: the project's and its enabled plugins' top-level entities that have an external API
+(`access.api` is not `false`) and are enabled. Core's own entities (users, teams, ...) and entities that are nested children of another entity (`entity.parent`) are not entries of their own.
+
+## The wire envelope
+
+`createApiResponse` puts the pagination in `info`, next to the timestamp, and there is no `meta`:
+
+```json
+{ "success": true, "data": [ ... ], "info": { "timestamp": "...", "page": 1, "limit": 20, "total": 3, "totalPages": 1, "hasNextPage": false, "hasPrevPage": false } }
+```
+
+`ApiListResponse<T>` is exactly that. `@nextsparkjs/mobile`'s client uses the same shapes (`PaginatedResponse<T>` is `ApiListResponse<T>`,
+`SingleResponse<T>` is `ApiSuccessResponse<T>`; the old `meta` never existed on the wire), and a test in apps/mobile keeps its types and
+the generated ones mutually assignable.
+
+## Where it goes
+
+| Project | Location | In git? |
+| --- | --- | --- |
+| web-only | `<project>/.nextspark/contracts` | no (`.nextspark/` is ignored; regenerated with the host) |
+| web+mobile monorepo (`create-nextspark-app --type web-mobile`) | `packages/contracts`, beside `web/` and `mobile/` | **yes**: mobile builds from it without running the web project |
+| this repository | `packages/contracts`, fed by `apps/dev` | **yes** |
+
+A contracts package opts in to being written, and names the project that feeds it, in its `package.json`:
+
+```json
+{ "name": "@project/contracts", "nextspark": { "contractsProject": "../web" } }
+```
+
+The path is relative to the package and must lead back to the project being prepared. Prepare looks for the package at
+`<project>/../packages/contracts`, `<project>/../../packages/contracts` and `<project>/packages/contracts`, and falls back to
+`.nextspark/contracts`. The scaffold writes the `package.json`, `tsconfig.json` and README; `src/` is generated.
+
+## Ownership
+
+Like `src/app`, only files NextSpark wrote are ever replaced or deleted: a file is ours when `contracts.generation.json` lists it and
+its bytes still have the recorded hash. A file at a target path that is not ours (a hand-written `src/index.ts`, a generated file
+edited by hand) stops the run **before anything is written** (in a full prepare, before the host is published either). Files in `src/`
+the record does not list are left alone; a generated file no entity produces any more is deleted. Nothing is written through a symlink.
+
+## Commands
+
+- `nextspark prepare` - the generated host writes the contracts with `src/app` and the registries (one lock, one preflight); a project
+  whose `src/app` is a committed tree is not prepared at all (`nextspark migrate` first), contracts included;
+- `nextspark prepare --contracts-only [--check]` - only the contracts, without touching `src/app`; it refuses a committed `src/app` the same way;
+- `nextspark prepare --check` - includes the contracts when the host generates them;
+- this repository: `pnpm contracts:generate`, `pnpm contracts:check` (run in the Mobile workflow), `pnpm mobile:boundary`.
+
+## What is not readable
+
+Entity configs are parsed, never executed. `fields` may be an inline array, a `const` in the same file, an import from a relative
+module, and spreads of those. A `fields` that is computed, a field whose `name` is not a literal, an `options` list that is not
+literal: each becomes a `// Warning:` line in the entity module and a line printed by prepare, and the value is typed `string` or
+`unknown` - never left out silently.