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

package/scripts/maintenance/core-updater.mjs

@@ -2,11 +2,11 @@
  * Updates a NextSpark project to another release of the @nextsparkjs packages.
  *
  * A project takes NextSpark from npm: its package.json pins @nextsparkjs/core,
- * @nextsparkjs/cli and the other @nextsparkjs packages to one version, app/ is
- * kept in step with core's templates by `nextspark sync:app`, and contents/
- * holds the project's own themes and plugins. So an update sets those pins to
- * the new version, installs, and syncs app/. No framework source is copied into
- * the project, and of package.json only the @nextsparkjs versions change.
+ * @nextsparkjs/cli and the other @nextsparkjs packages to one version, src/app/
+ * is generated by `nextspark prepare` (dev and build run it too), and the named
+ * root directories hold project-owned source. So an update sets those pins to
+ * the new version, installs, and regenerates src/app/. No framework source is
+ * copied into the project, and of package.json only the @nextsparkjs versions change.
  *
  * What can be checked without changing anything is checked before the first
  * write, so a run that can't start says why and leaves the project as it was.
@@ -66,15 +66,17 @@ What gets updated:
                           the newest version the range allows instead of the target
   pnpm-lock.yaml, node_modules   Through pnpm install, run where pnpm-lock.yaml is (in a
                           web-mobile project, the directory above web/)
-  app/                    Synced with core's templates by nextspark sync:app, which keeps
-                          files the project customized and rebuilds the registries
-  next.config.mjs, tsconfig.json, i18n.ts, proxy.ts or middleware.ts
-                          Also synced by sync:app, which keeps them when customized
+  src/app/, .nextspark/   Generated by nextspark prepare from the new core, and ignored by
+                          git; the project's templates/ and api/ decide what replaces core's
   core.version.json       Written once everything above succeeded
 
 What update-core itself never writes:
   The rest of package.json (name, scripts, other dependencies)
-  contents/               The project's themes and plugins
+  next.config.mjs, tsconfig.json, i18n.ts, proxy.ts or middleware.ts
+                          Project files: nextspark sync:app, which used to update them, was
+                          removed in 0.1.0-beta.192
+  api/, blocks/, components/, config/, entities/, lib/, messages/, migrations/, plugins/, styles/, templates/, tests/
+                          Project-owned root-first source
   .env*                   Environment files
 Lifecycle scripts that pnpm install runs are not bound by this list.
 
@@ -82,8 +84,8 @@ The update stops before changing anything when the project isn't in a git
 repository with a commit, when it has uncommitted changes or no committed
 pnpm-lock.yaml, when a @nextsparkjs package isn't published at the target
 version, when the target is older than the installed version, when package.json
-takes a @nextsparkjs package from somewhere other than the registry, or when .env
-doesn't set NEXT_PUBLIC_ACTIVE_THEME, which the registry build needs. When every
+takes a @nextsparkjs package from somewhere other than the registry, or when
+nextspark.config.ts is absent. When every
 @nextsparkjs package is already installed and pinned exactly to the target, there
 is nothing to do and nothing is changed; a ^ or ~ range is set to the exact
 target like any other pin.
@@ -95,7 +97,7 @@ exits non-zero and prints what it got through, what git status shows and the
 command that rolls the project back to the commit it started from:
   git reset --hard <commit> && git clean -fd && rm -rf node_modules && pnpm install --frozen-lockfile
 That command is also printed before the first change, for a run that is killed
-without a chance to report (SIGKILL). The install or sync such a run was running
+without a chance to report (SIGKILL). The install or prepare such a run was running
 is then killed by a guard process, but not processes that left that step's
 process group, not while the guard is stopped (SIGSTOP), and not at all if the
 guard is killed too.
@@ -259,7 +261,7 @@ function readProject(cwd) {
     if (fs.existsSync(path.join(cwd, 'core'))) {
       return {
         problem: 'This project keeps the framework in core/, the layout from before NextSpark shipped as npm packages, and update-core only updates projects that install @nextsparkjs/core. Nothing was changed.\n' +
-          '  To move it over, create a project with create-nextspark-app and bring your contents/ across.',
+          '  To move it over, create a root-first project with create-nextspark-app and bring your project-owned source across.',
       }
     }
     return { problem: `package.json doesn't depend on ${CORE_PACKAGE}, so there is nothing for update-core to update.` }
@@ -444,19 +446,10 @@ function installedCli(cwd) {
 }
 
 /**
- * Whether the registry build sync:app runs has a theme to build: it reads
- * NEXT_PUBLIC_ACTIVE_THEME from the project's .env or the environment, and
- * without one it skips the build and still exits 0.
+ * Whether nextspark prepare can resolve the root-first project it must rebuild.
  */
-function hasActiveTheme(cwd, env) {
-  if (env.NEXT_PUBLIC_ACTIVE_THEME) return true
-  const text = readOptional(path.join(cwd, '.env'))?.toString('utf8') ?? ''
-  const lines = text.split(/\r?\n/).filter((line) => /^\s*(?:export\s+)?NEXT_PUBLIC_ACTIVE_THEME\s*=/.test(line))
-  if (lines.length === 0) return false
-  const raw = lines.at(-1).slice(lines.at(-1).indexOf('=') + 1).trim()
-  const quoted = raw.match(/^(["'`])(.*?)\1/)
-  const value = quoted ? quoted[2] : raw.replace(/\s+#.*$/, '').trim()
-  return value !== ''
+function hasProjectConfig(cwd) {
+  return fs.existsSync(path.join(cwd, 'nextspark.config.ts'))
 }
 
 function coreMigrations(cwd) {
@@ -802,7 +795,7 @@ export async function updateCore(args, { cwd = process.cwd(), env = process.env,
   }
 
   if (!packages.some(({ name }) => name === CLI_PACKAGE)) {
-    err(`   update-core syncs app/ through the nextspark CLI, and package.json doesn't depend on ${CLI_PACKAGE}. Nothing was changed.`)
+    err(`   update-core regenerates src/app/ through the nextspark CLI, and package.json doesn't depend on ${CLI_PACKAGE}. Nothing was changed.`)
     return 1
   }
 
@@ -833,8 +826,8 @@ export async function updateCore(args, { cwd = process.cwd(), env = process.env,
     return 1
   }
 
-  if (!hasActiveTheme(cwd, env)) {
-    err('   NEXT_PUBLIC_ACTIVE_THEME is not set in .env, and sync:app skips the registry build without it, so app/(templates) would stay on the old core. Set it and run update-core again. Nothing was changed.')
+  if (!hasProjectConfig(cwd)) {
+    err('   nextspark.config.ts is missing, so nextspark prepare cannot resolve the root-first project. Restore it and run update-core again. Nothing was changed.')
     return 1
   }
   out(`   Installed: ${CORE_PACKAGE} ${installed}`)
@@ -851,7 +844,7 @@ export async function updateCore(args, { cwd = process.cwd(), env = process.env,
   out(`   Target:    ${target}`)
 
   if (compareVersions(target, installed) < 0) {
-    err(`   ${target} is older than the installed ${installed}. update-core doesn't downgrade: app/ would be synced back and applied migrations can't be undone. Nothing was changed.`)
+    err(`   ${target} is older than the installed ${installed}. update-core doesn't downgrade: applied migrations can't be undone. Nothing was changed.`)
     return 1
   }
 
@@ -884,7 +877,7 @@ export async function updateCore(args, { cwd = process.cwd(), env = process.env,
   const rollback = rollbackCommand(git, { cwd, root, branch })
   out(`\n   Starting from commit ${git.head.slice(0, 12)}. If this run is killed before it can report (SIGKILL), roll back with:`)
   out(`     ${rollback}`)
-  out('   Killing this run also kills the install or sync it is running, unless its guard process is stopped or killed too, but not processes that left that step\'s process group.')
+  out('   Killing this run also kills the install or prepare it is running, unless its guard process is stopped or killed too, but not processes that left that step\'s process group.')
   out('   The rollback removes files created in the repository while the update runs, and can\'t bring back ignored files, like .env, that a lifecycle script overwrites.')
 
   // From here on the project changes, and whatever stops the run goes through stoppedReport
@@ -894,7 +887,7 @@ export async function updateCore(args, { cwd = process.cwd(), env = process.env,
     ...(branch ? [`create and switch to branch ${branch}`] : []),
     'set the @nextsparkjs versions in package.json',
     'pnpm install',
-    'nextspark sync:app --force',
+    'nextspark prepare',
     `write ${VERSION_FILE}`,
   ]
   let current = 0
@@ -959,18 +952,18 @@ export async function updateCore(args, { cwd = process.cwd(), env = process.env,
     done.push(`pnpm install: every @nextsparkjs package installed at ${target}`)
     current++
 
-    out('\n[4/5] Syncing app/ with core and rebuilding the registries...')
+    out('\n[4/5] Generating src/app/ and the registries from the new core...')
     const cli = installedCli(cwd)
     if (!cli) return stopped({ reason: `node_modules has no nextspark CLI from ${CLI_PACKAGE}` })
     fs.rmSync(path.join(cwd, '.next'), { recursive: true, force: true })
     done.push('.next removed')
     if (await signalled()) return stopped({ started: false })
-    const sync = await runStep(process.execPath, [cli, 'sync:app', '--force'], { cwd, signals })
+    const sync = await runStep(process.execPath, [cli, 'prepare'], { cwd, signals })
     if (signals.signal) return stopped({ started: sync.started, stop: sync.stop, leftRunning: sync.leftRunning })
     if (sync.status !== 0) return stopped({ reason: `${describeExit(sync)}${sync.started ? '; what it reported is above' : ''}`, started: sync.started, stop: sync.stop, leftRunning: sync.leftRunning })
     if (sync.leftRunning) return stopped({ reason: 'it exited 0, but processes it started were still running after being killed', stop: sync.stop, leftRunning: true })
-    if (sync.stop) out(`   Processes nextspark sync:app started were still running after it exited, and were ${sync.stop === 'killed' ? 'killed' : 'stopped with SIGTERM'}.`)
-    done.push('app/ synced with core and registries rebuilt by nextspark sync:app')
+    if (sync.stop) out(`   Processes nextspark prepare started were still running after it exited, and were ${sync.stop === 'killed' ? 'killed' : 'stopped with SIGTERM'}.`)
+    done.push('src/app/ generated and registries rebuilt by nextspark prepare')
     current++
 
     if (await signalled()) return stopped({ started: false })

package/scripts/maintenance/step-guard.mjs

@@ -1,5 +1,5 @@
 /**
- * Runs one step of update-core (pnpm install, nextspark sync:app) and kills it
+ * Runs one step of update-core (pnpm install, nextspark prepare) and kills it
  * if update-core goes away before it is done with the step, however
  * update-core ended.
  *

package/scripts/postinstall.mjs

@@ -2,15 +2,18 @@
 /**
  * @nextsparkjs/core postinstall hook
  *
- * Automatically syncs /app folder with core templates when the package is updated.
- * Only runs in NextSpark projects (not in the monorepo or other contexts).
+ * Writes nothing. Since 0.1.0-beta.192 `src/app` is generated by `nextspark dev`, `build` and
+ * `prepare`, and a package install never touches a project. The only thing left to do here is
+ * tell a project that still carries a committed `src/app` (or `app/`) how to move to the
+ * generated host.
  *
+ * Only runs in NextSpark projects (not in the monorepo or other contexts).
  * Debug mode: Set NEXTSPARK_DEBUG=1 to see detailed logs
  */
 
-import { execSync } from 'child_process';
 import { existsSync, readFileSync } from 'fs';
-import { join, resolve, isAbsolute } from 'path';
+import { join, resolve, isAbsolute, dirname } from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
 
 const DEBUG = process.env.NEXTSPARK_DEBUG === '1';
 
@@ -67,7 +70,7 @@ function validateProjectRoot(projectRoot) {
 
 /**
  * Detect if we're in the NextSpark development monorepo.
- * Consumer projects may also have pnpm-workspace.yaml (for themes/plugins),
+ * Consumer projects may also have pnpm-workspace.yaml (for their own packages),
  * so we check for packages/core/ which only exists in the dev monorepo.
  */
 function isDevMonorepo(projectRoot) {
@@ -110,27 +113,19 @@ function isNextSparkProject(projectRoot) {
 }
 
 /**
- * Check if the project has an /app folder (already initialized)
- */
-function hasAppFolder(projectRoot) {
-  const hasApp = existsSync(join(projectRoot, 'app'));
-  if (!hasApp) {
-    debug('Skipping: no /app folder found (project not initialized)');
-  }
-  return hasApp;
-}
-
-/**
- * Check if nextspark CLI is available
+ * Whether the project carries an app tree no generation owns: a committed `src/app` (core's
+ * `resolveHostMode` decides, validating the generation record) or a pre-root-first `app/`.
  */
-function hasNextsparkCli(projectRoot) {
-  // Check in node_modules/.bin
-  const binPath = join(projectRoot, 'node_modules', '.bin', 'nextspark');
-  const hasCli = existsSync(binPath);
-  if (!hasCli) {
-    debug('Skipping: CLI not yet available (parallel install in progress)');
+async function hasCommittedAppTree(projectRoot) {
+  if (existsSync(join(projectRoot, 'app'))) return true;
+  try {
+    const coreRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+    const { resolveHostMode } = await import(pathToFileURL(join(coreRoot, 'scripts/build/registry/host/mode.mjs')).href);
+    return resolveHostMode({ coreRoot, projectRoot }).mode === 'legacy-app';
+  } catch (error) {
+    debug(`Could not ask core who owns src/app: ${error.message}`);
+    return false;
   }
-  return hasCli;
 }
 
 // Main execution
@@ -138,33 +133,20 @@ try {
   const projectRoot = findProjectRoot();
   debug(`Project root: ${projectRoot}`);
 
-  // Validate project root path
   if (!validateProjectRoot(projectRoot)) {
     debug('Skipping: invalid project root path');
     process.exit(0);
   }
 
-  // Only run in NextSpark projects with an existing /app folder
-  if (isNextSparkProject(projectRoot) && hasAppFolder(projectRoot)) {
-    console.log('\n  📦 @nextsparkjs/core updated - syncing /app folder...\n');
-
-    // Check if CLI is available
-    if (hasNextsparkCli(projectRoot)) {
-      try {
-        execSync('npx nextspark sync:app --force', {
-          stdio: 'inherit',
-          cwd: projectRoot
-        });
-      } catch (syncError) {
-        console.warn('\n  ⚠️  Auto-sync failed. Run manually: npx nextspark sync:app\n');
-        debug(`Sync error: ${syncError.message}`);
-      }
-    }
-    // If CLI not available, skip silently - this is expected during initial setup
+  if (isNextSparkProject(projectRoot) && (await hasCommittedAppTree(projectRoot))) {
+    console.log(
+      '\n  @nextsparkjs/core: this project has a committed app tree, but src/app is now generated.\n' +
+      '  Run `pnpm nextspark migrate --dry-run` to see what changes, then `pnpm nextspark migrate`.\n' +
+      '  Nothing was changed. `nextspark sync:app` was removed in 0.1.0-beta.192.\n'
+    );
   }
 } catch (error) {
   // Postinstall hooks should not break installations
-  // The user can always run the sync manually
   if (DEBUG) {
     console.warn('\n  [DEBUG] Postinstall error:', error.message);
     if (error.stack) {

package/scripts/setup/setup-ci.mjs

@@ -166,9 +166,8 @@ if (results.copied.length > 0 || results.overwritten.length > 0) {
   console.log('\n✅ CI workflows setup complete!')
   console.log('   Review and customize workflows in .github/workflows/')
   console.log('\n📝 Recommended next steps:')
-  console.log('   1. Set repository variable: ACTIVE_THEME (if not using default)')
-  console.log('   2. Review workflow triggers and adjust as needed')
-  console.log('   3. Configure required secrets (DATABASE_URL, etc.)')
+  console.log('   1. Review workflow triggers and adjust as needed')
+  console.log('   2. Configure required secrets (DATABASE_URL, etc.)')
 }
 
 console.log('')

package/scripts/test/build-entities.mjs

@@ -6,33 +6,24 @@
  * Auto-generates entities.json for Cypress E2E tests from entity configs.
  * This ensures Cypress POMs always stay in sync with entity configurations.
  *
- * Output: contents/themes/{theme}/tests/cypress/fixtures/entities.json
+ * Output: tests/cypress/fixtures/entities.json
  *
  * Usage:
- *   node scripts/build-test-entities.mjs           # Generate for active theme
+ *   node scripts/build-test-entities.mjs           # Generate for the current project
  *   node scripts/build-test-entities.mjs --watch   # Watch mode
- *   node scripts/build-test-entities.mjs --all     # Generate for all themes
  */
 
 import { readdir, writeFile, mkdir, readFile, stat } from 'fs/promises'
-import { join, dirname, basename } from 'path'
-import { fileURLToPath } from 'url'
+import { join } from 'path'
 import { existsSync, watch } from 'fs'
-import dotenv from 'dotenv'
+import { resolveProjectPaths } from '../build/registry/project-mode.mjs'
 
-dotenv.config({ override: true })
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = dirname(__filename)
-// Path from packages/core/scripts/test/ to project root (4 levels up)
-const rootDir = join(__dirname, '../../../..')
+const { projectRoot } = resolveProjectPaths(process.cwd())
 
 // Configuration
 const CONFIG = {
-  contentsDir: join(rootDir, 'contents', 'themes'),
-  activeTheme: process.env.NEXT_PUBLIC_ACTIVE_THEME?.replace(/'/g, '') || 'team-manager',
+  projectRoot,
   watchMode: process.argv.includes('--watch'),
-  allThemes: process.argv.includes('--all'),
   verbose: process.argv.includes('--verbose') || process.argv.includes('-v'),
 }
 
@@ -158,11 +149,11 @@ async function parseEntityFields(fieldsPath) {
 /**
  * Generate entities.json for a specific theme
  */
-async function generateEntitiesJson(themePath, themeName) {
-  const entities = await discoverEntities(themePath)
+async function generateEntitiesJson(projectPath) {
+  const entities = await discoverEntities(projectPath)
 
   if (entities.length === 0) {
-    log(`No entities found in theme: ${themeName}`, 'warning')
+    log('No entities found in the project', 'warning')
     return null
   }
 
@@ -252,114 +243,43 @@ async function generateEntitiesJson(themePath, themeName) {
   return output
 }
 
-/**
- * Write entities.json to the theme's Cypress fixtures directory
- *
- * New location (theme-level testing):
- *   contents/themes/{theme}/tests/cypress/fixtures/entities.json
- *
- * Legacy location (for backwards compatibility):
- *   core/tests/cypress/fixtures/themes/{theme}/entities.json
- */
-async function writeEntitiesJson(themePath, themeName, data) {
-  // New location: theme-level Cypress fixtures
-  const themeFixturesDir = join(themePath, 'tests', 'cypress', 'fixtures')
-  // Legacy location: central Cypress fixtures (for backwards compatibility)
-  const centralFixturesDir = join(rootDir, 'core', 'tests', 'cypress', 'fixtures', 'themes', themeName)
-
-  // Ensure directories exist
-  if (!existsSync(themeFixturesDir)) {
-    await mkdir(themeFixturesDir, { recursive: true })
-  }
-  if (!existsSync(centralFixturesDir)) {
-    await mkdir(centralFixturesDir, { recursive: true })
-  }
-
-  const jsonContent = JSON.stringify(data, null, 2) + '\n'
-
-  // Primary location: theme-level
-  const outputPath = join(themeFixturesDir, 'entities.json')
-  // Secondary location: central (backwards compatibility)
-  const legacyOutputPath = join(centralFixturesDir, 'entities.json')
-
-  await writeFile(outputPath, jsonContent)
-  await writeFile(legacyOutputPath, jsonContent)
-
-  verbose(`  Primary: ${outputPath}`)
-  verbose(`  Legacy:  ${legacyOutputPath}`)
-
+/** Write entities.json to the project's Cypress fixtures directory. */
+async function writeEntitiesJson(projectPath, data) {
+  const fixturesDir = join(projectPath, 'tests', 'cypress', 'fixtures')
+  if (!existsSync(fixturesDir)) await mkdir(fixturesDir, { recursive: true })
+  const outputPath = join(fixturesDir, 'entities.json')
+  await writeFile(outputPath, JSON.stringify(data, null, 2) + '\n')
+  verbose(`  Output: ${outputPath}`)
   return outputPath
 }
 
-/**
- * Process a single theme
- */
-async function processTheme(themeName) {
-  const themePath = join(CONFIG.contentsDir, themeName)
-
-  if (!existsSync(themePath)) {
-    log(`Theme not found: ${themeName}`, 'error')
-    return false
-  }
-
-  log(`Processing theme: ${themeName}`, 'build')
-
-  const data = await generateEntitiesJson(themePath, themeName)
-
-  if (!data) {
-    return false
-  }
-
-  const outputPath = await writeEntitiesJson(themePath, themeName, data)
-  const entityCount = Object.keys(data.entities).length
-
-  log(`Generated ${outputPath} (${entityCount} entities)`, 'success')
+async function processProject() {
+  log('Processing current project', 'build')
+  const data = await generateEntitiesJson(CONFIG.projectRoot)
+  if (!data) return false
+  const outputPath = await writeEntitiesJson(CONFIG.projectRoot, data)
+  log(`Generated ${outputPath} (${Object.keys(data.entities).length} entities)`, 'success')
   return true
 }
 
-/**
- * Main execution
- */
 async function main() {
   log('Test Entities JSON Generator', 'build')
   log('============================')
-
   const startTime = Date.now()
+  await processProject()
+  log(`Completed in ${Date.now() - startTime}ms`, 'success')
 
-  if (CONFIG.allThemes) {
-    // Process all themes
-    const themes = await readdir(CONFIG.contentsDir, { withFileTypes: true })
-
-    for (const theme of themes) {
-      if (theme.isDirectory()) {
-        await processTheme(theme.name)
-      }
-    }
-  } else {
-    // Process only active theme
-    await processTheme(CONFIG.activeTheme)
-  }
-
-  const elapsed = Date.now() - startTime
-  log(`Completed in ${elapsed}ms`, 'success')
-
-  // Watch mode
   if (CONFIG.watchMode) {
     log('Watching for changes...', 'info')
-
-    const watchPath = join(CONFIG.contentsDir, CONFIG.activeTheme, 'entities')
-
+    const watchPath = join(CONFIG.projectRoot, 'entities')
     if (existsSync(watchPath)) {
       let debounceTimer = null
-
-      watch(watchPath, { recursive: true }, (eventType, filename) => {
+      watch(watchPath, { recursive: true }, (_eventType, filename) => {
         if (!filename || !filename.endsWith('.ts')) return
-
-        // Debounce rebuilds
         if (debounceTimer) clearTimeout(debounceTimer)
         debounceTimer = setTimeout(async () => {
           log(`Change detected: ${filename}`, 'info')
-          await processTheme(CONFIG.activeTheme)
+          await processProject()
         }, 500)
       })
     }