@nextsparkjs/core 0.1.0-beta.195 → 0.1.0-beta.197

package/scripts/build/registry/host/__tests__/host-proxy-areas.test.mjs

@@ -12,7 +12,7 @@ import { mkdtempSync, readFileSync, rmSync, symlinkSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
-import { PROXY_AREA_WARNING, missingProxyAreas, proxyAreaNotice, proxyAreaNotices } from '../proxy-areas.mjs'
+import { PROXY_AREA_WARNING, PROXY_SESSION_WARNING, PROXY_SESSION_CACHED_WARNING, missingProxyAreas, withoutComments, proxyAreaNotice, proxyAreaNotices, proxySessionNotice, proxySessionCachedNotice } from '../proxy-areas.mjs'
 import { predictHost } from '../prepare.mjs'
 import { PAGE, tempHost, write } from './host-helpers.mjs'
 
@@ -30,6 +30,20 @@ test('an area counts only when the proxy names its path; a look-alike prefix or
   assert.deepEqual(missingProxyAreas("const docs = '/superadmin-guide'; const tips = \"/devtools-tips\"").map(area => area.path), ['/superadmin', '/devtools'])
 })
 
+test("a proxy that re-exports core's template has the check; a re-export of anything else does not", () => {
+  assert.deepEqual(missingProxyAreas("export { proxy } from '../../../packages/core/templates/proxy'\nexport const config = { matcher: [] }"), [])
+  assert.deepEqual(missingProxyAreas("export { proxy } from '@nextsparkjs/core/templates/proxy'"), [])
+  assert.deepEqual(missingProxyAreas("export { proxy } from './my-proxy'").map(area => area.path), ['/superadmin', '/devtools'])
+  assert.deepEqual(missingProxyAreas("export { other } from '@nextsparkjs/core/templates/proxy'").map(area => area.path), ['/superadmin', '/devtools'])
+  const both = ['/superadmin', '/devtools']
+  assert.deepEqual(missingProxyAreas("export { proxy as coreProxy } from '@nextsparkjs/core/templates/proxy'\nexport function proxy() {}").map(a => a.path), both)
+  assert.deepEqual(missingProxyAreas("export { other as proxy } from '@nextsparkjs/core/templates/proxy'").map(a => a.path), both)
+  assert.deepEqual(missingProxyAreas("export { proxy } from './vendor/core/templates/proxy'").map(a => a.path), both)
+  assert.deepEqual(missingProxyAreas("// export { proxy } from '@nextsparkjs/core/templates/proxy'\nexport function proxy() {}").map(a => a.path), both)
+  assert.deepEqual(missingProxyAreas("/*\nexport { proxy } from '@nextsparkjs/core/templates/proxy'\n*/\nexport function proxy() {}").map(a => a.path), both)
+  assert.deepEqual(missingProxyAreas("export { config, proxy } from '@nextsparkjs/core/templates/proxy.ts'"), [])
+})
+
 test('the warning names the file, each missing area, its roles and where the check comes from', () => {
   const notice = proxyAreaNotice('src/proxy.ts', "const PROTECTED = ['/superadmin']")
   assert.equal(notice.code, PROXY_AREA_WARNING)
@@ -53,6 +67,63 @@ test('the proxy Next loads is the one checked; a project without one is not warn
   }
 })
 
+// S80 (D1): the session check that fetched /api/auth/get-session from the request's origin, as every proxy.ts copied
+// before 0.1.0-beta.196 does. Upgrading core never touches that copy, so prepare says what to change.
+const HTTP_SESSION_CHECK = `function getSession(request: NextRequest) {
+  return betterFetch<Session>('/api/auth/get-session', {
+    baseURL: \`\${request.nextUrl.origin}\${request.nextUrl.basePath}\`,
+    headers: { cookie: request.headers.get('cookie') || '' },
+  })
+}
+const PROTECTED = ['/superadmin', '/devtools']
+`
+
+test('a proxy that asks its own /api/auth/get-session over HTTP is warned about, with the in-process call to use', () => {
+  const notice = proxySessionNotice('src/proxy.ts', HTTP_SESSION_CHECK)
+  assert.equal(notice.code, PROXY_SESSION_WARNING)
+  assert.match(notice.message, /^src\/proxy\.ts checks the session by fetching \/api\/auth\/get-session/)
+  assert.match(notice.message, /X-Forwarded-Proto: https/)
+  assert.match(notice.message, /auth\.api\.getSession\(\{ headers: new Headers\(\{ cookie: request\.headers\.get\('cookie'\) \|\| '' \}\), query: \{ disableRefresh: true, disableCookieCache: true \} \}\)/)
+  assert.equal(proxySessionNotice('src/proxy.ts', readFileSync(join(CORE_ROOT, 'templates/proxy.ts'), 'utf8')), null)
+  assert.equal(proxySessionNotice('src/proxy.ts', "// was: betterFetch('/api/auth/get-session')\nexport function proxy() {}"), null)
+  assert.equal(proxySessionNotice('src/proxy.ts', "export { proxy } from '@nextsparkjs/core/templates/proxy'"), null)
+})
+
+// The S80 review's measured edges: an end-of-line comment, and a '/*' / '*/' pair inside two string literals.
+const COMMENT_EDGES = [
+  ['an end-of-line comment after code', "const x = 1 // was '/api/auth/get-session'\nexport function proxy() {}", false],
+  ['an end-of-line comment after code, no space', "const x = 1// was '/api/auth/get-session'", false],
+  ["a '/*' and a '*/' in two strings around the call", "const a = '/api/*'\nbetterFetch('/api/auth/get-session')\nconst b = 'x*/'", true],
+  ["a '//' inside a string before the call", "const u = 'https://example.com'; betterFetch('/api/auth/get-session')", true],
+  ['a block comment', "/* betterFetch('/api/auth/get-session') */ export function proxy() {}", false],
+  ['a quote escaped inside a string', "const q = 'it\\'s'; betterFetch('/api/auth/get-session')", true],
+]
+
+test('comments are stripped wherever they start, and never inside a string literal', () => {
+  for (const [label, source, warns] of COMMENT_EDGES) {
+    assert.equal(proxySessionNotice('src/proxy.ts', source) !== null, warns, label)
+  }
+  assert.equal(withoutComments("a // b\nc"), 'a \nc')
+  assert.equal(withoutComments("'//' /* x */ \"/*\""), "'//'   \"/*\"")
+  // The repository template, old and new, reads the same with comments gone: every regex literal in it survives.
+  const template = readFileSync(join(CORE_ROOT, 'templates/proxy.ts'), 'utf8')
+  assert.match(withoutComments(template), /\.replace\(\/\\\\\/g, '\/'\)\.replace\(\/\\\/\\\/\+\/g, '\/'\)/)
+})
+
+test("the proxy Next loads gets the session warning next to the areas one; core's template gets neither", () => {
+  const root = mkdtempSync(join(tmpdir(), 'nextspark-proxy-session-'))
+  try {
+    write(root, 'src/proxy.ts', HTTP_SESSION_CHECK)
+    assert.deepEqual(proxyAreaNotices(root).map(notice => notice.code), [PROXY_SESSION_WARNING])
+    write(root, 'src/proxy.ts', `${HTTP_SESSION_CHECK.replace("['/superadmin', '/devtools']", '[]')}`)
+    assert.deepEqual(proxyAreaNotices(root).map(notice => notice.code), [PROXY_AREA_WARNING, PROXY_SESSION_WARNING])
+    write(root, 'src/proxy.ts', readFileSync(join(CORE_ROOT, 'templates/proxy.ts'), 'utf8'))
+    assert.deepEqual(proxyAreaNotices(root), [])
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
 test("prepare's prediction carries the warning among its notices", async () => {
   const host = tempHost({ 'templates/about/page.tsx': PAGE('About') })
   const project = mkdtempSync(join(tmpdir(), 'nextspark-proxy-areas-project-'))
@@ -67,3 +138,30 @@ test("prepare's prediction carries the warning among its notices", async () => {
     rmSync(project, { recursive: true, force: true })
   }
 })
+
+// The in-process session read of the 0.1.0-beta.196 template, without disableCookieCache.
+const BETA_196_SESSION_READ = `async function getSession(request: NextRequest): Promise<Session | null> {
+  const session = await auth.api.getSession({
+    headers: new Headers({ cookie: request.headers.get('cookie') || '' }),
+    query: { disableRefresh: true },
+  })
+  return session as Session | null
+}
+`
+
+test('a proxy that reads the session in process from the cookie cache is warned about, with the option to add', () => {
+  const notice = proxySessionCachedNotice('src/proxy.ts', BETA_196_SESSION_READ)
+  assert.equal(notice.code, PROXY_SESSION_CACHED_WARNING)
+  assert.match(notice.message, /^src\/proxy\.ts reads the session with auth\.api\.getSession from Better Auth's cookie cache/)
+  assert.match(notice.message, /query: \{ disableRefresh: true, disableCookieCache: true \}/)
+  assert.equal(proxySessionCachedNotice('src/proxy.ts', readFileSync(join(CORE_ROOT, 'templates/proxy.ts'), 'utf8')), null)
+  assert.match(notice.message, /role !== 'suspended'/)
+  // the cache option alone is not enough: the proxy must also refuse a suspended account's session
+  const cacheOnly = BETA_196_SESSION_READ.replace('disableRefresh: true', 'disableRefresh: true, disableCookieCache: true')
+  assert.notEqual(proxySessionCachedNotice('src/proxy.ts', cacheOnly), null)
+  assert.equal(proxySessionCachedNotice('src/proxy.ts', cacheOnly.replace('return session as Session | null', "return session && (session.user as { role?: unknown }).role !== 'suspended' ? (session as Session) : null")), null)
+  // a comment that names the option does not count
+  assert.notEqual(proxySessionCachedNotice('src/proxy.ts', `// disableCookieCache\n${BETA_196_SESSION_READ}`), null)
+  // no in-process read (the HTTP check has its own warning), no notice
+  assert.equal(proxySessionCachedNotice('src/proxy.ts', HTTP_SESSION_CHECK), null)
+})

package/scripts/build/registry/host/__tests__/host-robustness.test.mjs

@@ -314,7 +314,7 @@ test('an npm-installed core ships only dist/: the manifest, variants and route m
 test('the project config is read again for every generation: enabling a plugin in nextspark.config.ts adds its routes', async () => {
   const root = mkdtempSync(join(tmpdir(), 'nextspark-config-reload-'))
   try {
-    write(root, 'package.json', JSON.stringify({ name: 'reload', dependencies: { next: '16.3.6' } }))
+    write(root, 'package.json', JSON.stringify({ name: 'reload', dependencies: { next: '16.3.8' } }))
     write(root, 'nextspark.config.ts', 'export default { plugins: [] }\n')
     write(root, 'plugins/search/plugin.config.ts', 'export const searchPluginConfig = {}\n')
     write(root, 'plugins/search/templates/search/page.tsx', PAGE('Search'))

package/scripts/build/registry/host/facade-emitter.mjs

@@ -284,7 +284,7 @@ export function resolveNextPackage(projectRoot = process.cwd()) {
 /**
  * Whether `version` is a Next.js the table applies to: the table's `next` is the verified
  * baseline, and core pins `next` to `~<baseline>`, so any stable patch of the same minor at or
- * above the baseline is accepted (16.3.6, 16.3.9, 16.3.6+build.1), while other minors/majors, lower
+ * above the baseline is accepted (16.3.8, 16.3.9, 16.3.8+build.1), while other minors/majors, lower
  * patches and prereleases (16.3.7-canary.0) are refused.
  */
 export function isSupportedNextVersion(version, baseline = ROUTE_EXPORT_TABLE.next) {

package/scripts/build/registry/host/next-route-exports.json

@@ -1,7 +1,7 @@
 {
   "$comment": "Route file kinds x exports x emitted facade form, for the generated host (#203). Source of truth for host/facade-emitter.mjs; README.md renders it. Verified against the installed Next.js source listed in verifiedAgainst and by the probe builds recorded in README.md. Re-verify and bump `next` when upgrading Next.js: host/__tests__/facade-emitter.test.mjs fails when the installed version differs.",
-  "next": "16.3.6",
-  "supportedNext": "~16.3.6 (same major.minor, stable patch >= the verified baseline in \"next\"; enforced by isSupportedNextVersion)",
+  "next": "16.3.8",
+  "supportedNext": "~16.3.8 (same major.minor, stable patch >= the verified baseline in \"next\"; enforced by isSupportedNextVersion)",
   "verifiedAgainst": [
     "next/dist/build/segment-config/app/app-segment-config.js (AppSegmentConfigSchemaKeys, parseAppSegmentConfig)",
     "next/dist/build/analysis/get-page-static-info.js (checkExports, getAppPageStaticInfo)",

package/scripts/build/registry/host/proxy-areas.mjs

@@ -7,6 +7,10 @@
  * before the template gained the check, or written by hand, may not have it: `nextspark prepare` (and `migrate`, in
  * the CLI) warn, naming each area the proxy never mentions.
  *
+ * Same for the session check (S80): a proxy copied before 0.1.0-beta.196 fetches its own /api/auth/get-session from
+ * the request's origin, which behind a proxy that terminates TLS is https on a plain-HTTP port, so every signed-in
+ * user is sent to /login. That copy is never updated by an upgrade, so prepare and migrate say what to change.
+ *
  * @module core/scripts/build/registry/host/proxy-areas
  */
 
@@ -24,8 +28,45 @@ export const PROTECTED_AREAS = Object.freeze([
 /** Where Next loads a project's proxy from, next to the generated src/app. */
 export const PROXY_FILES = Object.freeze(['src/proxy.ts', 'src/proxy.js', 'src/middleware.ts', 'src/middleware.js'])
 
+/**
+ * A proxy that re-exports core's template under its own name (apps/dev does) has the check without naming the areas
+ * itself. Exact name (`proxy as x` is not the proxy Next loads), a concrete specifier (the package, or the repository's
+ * packages/core), and only code: a commented-out line does not count.
+ */
+const REEXPORTS_CORE_PROXY =
+  /^\s*export\s*\{\s*(?:[\w$]+\s*,\s*)*proxy\s*(?:,[^}]*)?\}\s*from\s*['"](?:@nextsparkjs\/core|(?:\.\.\/)+packages\/core)\/templates\/proxy(?:\.ts)?['"]/m
+/**
+ * The source without its comments (`//` to the end of the line, wherever it starts, and block comments). String
+ * literals are kept whole, so a `/*` or `//` inside one is text. Not parsed: regular-expression literals (a quote in
+ * one can hide the code after it) and template-literal `${}` nesting; nor does the session detector follow a URL
+ * assembled from parts. No template that copied the HTTP session check needs either.
+ */
+export function withoutComments(source) {
+  let out = ''
+  let quote = null
+  for (let i = 0; i < source.length; i++) {
+    const c = source[i]
+    if (quote) {
+      out += c
+      if (c === '\\') out += source[++i] ?? ''
+      else if (c === quote) quote = null
+    } else if (c === '/' && source[i + 1] === '/') {
+      while (i + 1 < source.length && source[i + 1] !== '\n') i++
+    } else if (c === '/' && source[i + 1] === '*') {
+      const end = source.indexOf('*/', i + 2)
+      i = end < 0 ? source.length : end + 1
+      out += ' '
+    } else {
+      if (c === "'" || c === '"' || c === '`') quote = c
+      out += c
+    }
+  }
+  return out
+}
+
 /** The protected areas a proxy's source never names as a path (`'/superadmin'`, `"/devtools"`, `` `/devtools` ``). */
 export function missingProxyAreas(source) {
+  if (REEXPORTS_CORE_PROXY.test(withoutComments(source))) return []
   return PROTECTED_AREAS.filter(area => !new RegExp(`['"\`]${area.path}(?![\\w-])`).test(source))
 }
 
@@ -46,11 +87,60 @@ export function proxyAreaNotice(file, source) {
   }
 }
 
+export const PROXY_SESSION_WARNING = 'NS_PROXY_SESSION_OVER_HTTP'
+
+/** What to write instead of the HTTP session check; migrate in the CLI says the same. */
+export const PROXY_SESSION_FIX =
+  "import { auth } from '@nextsparkjs/core/lib/auth' and replace the betterFetch('/api/auth/get-session', ...) call with " +
+  "auth.api.getSession({ headers: new Headers({ cookie: request.headers.get('cookie') || '' }), query: { disableRefresh: true, disableCookieCache: true } }), " +
+  'which returns the session itself (or null), not { data }'
+
+/** The warning for a proxy whose code (not a comment) asks /api/auth/get-session over HTTP, or null. */
+export function proxySessionNotice(file, source) {
+  if (!withoutComments(source).includes('/api/auth/get-session')) return null
+  return {
+    code: PROXY_SESSION_WARNING,
+    target: file,
+    message:
+      `${file} checks the session by fetching /api/auth/get-session from the request's own origin. Behind a proxy that ` +
+      `terminates TLS (X-Forwarded-Proto: https) that origin is https on a port that speaks plain HTTP: the fetch fails ` +
+      `and every signed-in user is sent to /login. Read the session in process, as ` +
+      `node_modules/@nextsparkjs/core/templates/proxy.ts does: ${PROXY_SESSION_FIX}`,
+  }
+}
+
+export const PROXY_SESSION_CACHED_WARNING = 'NS_PROXY_SESSION_CACHED'
+
+/** What to add to an in-process session read (the 0.1.0-beta.196 template); migrate in the CLI says the same. */
+export const PROXY_SESSION_CACHED_FIX =
+  "add disableCookieCache: true to the query of its auth.api.getSession call: query: { disableRefresh: true, disableCookieCache: true }, " +
+  "and refuse a suspended account's session at the end of getSession: return session && (session.user as { role?: unknown }).role !== 'suspended' ? (session as Session) : null"
+
+/**
+ * The warning for a proxy whose code (not a comment) reads the session in process (auth.api.getSession, as the
+ * 0.1.0-beta.196 template) without disableCookieCache, or without refusing a suspended account, or null: Better Auth
+ * then answers from the cached session_data cookie, so a signed-out cookie pair or an old role passes the proxy for up
+ * to 5 minutes, and a suspended account's session passes it.
+ */
+export function proxySessionCachedNotice(file, source) {
+  const code = withoutComments(source)
+  if (!code.includes('auth.api.getSession(') || (code.includes('disableCookieCache') && code.includes("'suspended'"))) return null
+  return {
+    code: PROXY_SESSION_CACHED_WARNING,
+    target: file,
+    message:
+      `${file} reads the session with auth.api.getSession from Better Auth's cookie cache: after a sign-out, the copied cookie ` +
+      `pair, or a role changed since sign-in, still passes the proxy until the cached cookie expires (5 minutes by default), ` +
+      `and a suspended account's session passes it. ` +
+      `As node_modules/@nextsparkjs/core/templates/proxy.ts does, ${PROXY_SESSION_CACHED_FIX}`,
+  }
+}
+
 /** The warnings for the proxy Next would load in `projectRoot` (the first of PROXY_FILES that exists). */
 export function proxyAreaNotices(projectRoot) {
   if (!projectRoot) return []
   const file = PROXY_FILES.find(candidate => existsSync(join(projectRoot, candidate)))
   if (!file) return []
-  const notice = proxyAreaNotice(file, readFileSync(join(projectRoot, file), 'utf8'))
-  return notice ? [notice] : []
+  const source = readFileSync(join(projectRoot, file), 'utf8')
+  return [proxyAreaNotice(file, source), proxySessionNotice(file, source), proxySessionCachedNotice(file, source)].filter(Boolean)
 }

package/scripts/db/run-migrations.mjs

@@ -2,6 +2,7 @@ import fs from "fs";
 import path from "path";
 import { migrationTimeLimit, migrationClient, ignoredParametersNotice, runAndRecordMigration, migrationFailure } from './migration-time-limit.mjs';
 import { getConfig } from '../build/registry/config.mjs';
+import { isSampleDataMigration, sampleDataPolicy } from './sample-data.mjs';
 
 const projectConfig = getConfig();
 const projectRoot = projectConfig.projectRoot;
@@ -21,6 +22,8 @@ let DATABASE_URL = process.env.DATABASE_URL ?? null;
 // Falls back to DATABASE_URL when unset (pre-cutover: same owner connection).
 let MIGRATE_DATABASE_URL = process.env.MIGRATE_DATABASE_URL ?? null;
 let MIGRATION_TIMEOUT_SECONDS = process.env.MIGRATION_TIMEOUT_SECONDS;
+// What the .env says about NODE_ENV and the sample-data switch (see sample-data.mjs)
+const fileEnv = {};
 
 if (readEnvFile && fs.existsSync(envPath)) {
   const envContent = fs.readFileSync(envPath, 'utf8');
@@ -40,6 +43,11 @@ if (readEnvFile && fs.existsSync(envPath)) {
       if (key?.trim() === 'MIGRATION_TIMEOUT_SECONDS' && valueParts.length > 0) {
         MIGRATION_TIMEOUT_SECONDS = value;
       }
+      // `export NODE_ENV=...` counts too; sample-data.mjs reads the value itself (case, trailing comment)
+      const name = key?.trim().replace(/^export\s+/, '');
+      if (['NODE_ENV', 'NEXTSPARK_SEED_SAMPLE_DATA'].includes(name) && valueParts.length > 0) {
+        fileEnv[name] = value;
+      }
     }
   });
 }
@@ -65,12 +73,20 @@ try {
 const ignoredParameters = ignoredParametersNotice(MIGRATION_URL, TIME_LIMIT);
 if (ignoredParameters) console.log(`⚠️  ${ignoredParameters}\n`);
 
+const SAMPLE_DATA = sampleDataPolicy({ argv: process.argv, env: process.env, fileEnv });
+
 async function runMigrations() {
   const client = migrationClient(MIGRATION_URL, TIME_LIMIT);
   
   try {
     await client.connect();
     console.log("✅ Connected to database\n");
+
+    // 029_sample_accounts_outside_development.sql reads it: a run that applies sample data keeps the sample accounts
+    await client.query("SELECT set_config('nextspark.seed_sample_data', $1, false)", [SAMPLE_DATA.apply ? 'on' : 'off']);
+    client.on('notice', notice => {
+      if (notice.message?.startsWith('Sample accounts:')) console.log(`🔐 ${notice.message}`);
+    });
     
     // Create migrations tracking table
     await client.query(`
@@ -101,9 +117,14 @@ async function runMigrations() {
         continue;
       }
       
+      const sql = fs.readFileSync(path.join(migrationsDir, file), 'utf8');
+      if (!SAMPLE_DATA.apply && isSampleDataMigration(file, sql)) {
+        console.log(`⏭️  Skipping ${file} (sample data)`);
+        continue;
+      }
+
       // Read and execute migration
       console.log(`🔄 Running ${file}...`);
-      const sql = fs.readFileSync(path.join(migrationsDir, file), 'utf8');
       
       try {
         // Runs the file and records it in one transaction (see runAndRecordMigration)
@@ -141,11 +162,6 @@ async function getActivePlugins() {
   return projectConfig.plugins;
 }
 
-// Helper: Check if a filename is a sample_data migration
-function isSampleDataMigration(filename) {
-  return filename.toLowerCase().includes('sample_data') || filename.toLowerCase().includes('sample-data');
-}
-
 // Helper: Collect all migration files from a directory (theme/plugin level)
 function collectContentMigrations(migrationsPath, sourceType, sourceName) {
   if (!fs.existsSync(migrationsPath)) return [];
@@ -160,7 +176,7 @@ function collectContentMigrations(migrationsPath, sourceType, sourceName) {
     sourceName,
     filename: file,
     fullPath: path.join(migrationsPath, file),
-    isSampleData: isSampleDataMigration(file)
+    isSampleData: isSampleDataMigration(file, fs.readFileSync(path.join(migrationsPath, file), 'utf8'))
   }));
 }
 
@@ -193,7 +209,7 @@ function collectEntityMigrations(baseDir, sourceType, sourceName, depth = 0) {
           entityName,
           filename: file,
           fullPath: path.join(migrationsPath, file),
-          isSampleData: isSampleDataMigration(file),
+          isSampleData: isSampleDataMigration(file, fs.readFileSync(path.join(migrationsPath, file), 'utf8')),
           depth
         });
       }
@@ -415,15 +431,18 @@ async function runEntityMigrations() {
     const sortByFilename = (a, b) => a.filename.localeCompare(b.filename);
 
     const contentSchema = allContentMigrations.filter(m => !m.isSampleData).sort(sortByFilename);
-    const contentSampleData = allContentMigrations.filter(m => m.isSampleData).sort(sortByFilename);
+    const contentSampleData = allContentMigrations.filter(m => m.isSampleData && SAMPLE_DATA.apply).sort(sortByFilename);
     const entitySchema = allEntityMigrations.filter(m => !m.isSampleData).sort(sortByFilename);
-    const entitySampleData = allEntityMigrations.filter(m => m.isSampleData).sort(sortByFilename);
+    const entitySampleData = allEntityMigrations.filter(m => m.isSampleData && SAMPLE_DATA.apply).sort(sortByFilename);
 
     console.log(`📊 Migration breakdown:`);
     console.log(`   - Content schema: ${contentSchema.length}`);
     console.log(`   - Content sample_data: ${contentSampleData.length}`);
     console.log(`   - Entity schema: ${entitySchema.length}`);
     console.log(`   - Entity sample_data: ${entitySampleData.length}`);
+    for (const m of [...allContentMigrations, ...allEntityMigrations].filter(m => m.isSampleData && !SAMPLE_DATA.apply)) {
+      console.log(`⏭️  Skipping ${m.filename} (sample data, ${m.sourceName})`);
+    }
     console.log('');
 
     let totalContentMigrations = 0;
@@ -550,6 +569,7 @@ async function runEntityMigrations() {
 // Main migration runner
 async function runAllMigrations() {
   console.log("🚀 Starting migration process...\n");
+  console.log(`🌱 ${SAMPLE_DATA.notice}\n`);
   
   // First run core migrations
   console.log("📋 PHASE 1: Core migrations");

package/scripts/db/sample-data.mjs

@@ -0,0 +1,44 @@
+// Which migrations are sample data, and whether a db:migrate run applies them.
+//
+// Sample data is applied only when the run asks for it -- `--sample-data`
+// (what `nextspark db:seed` passes) or NEXTSPARK_SEED_SAMPLE_DATA=1, in the
+// environment or the project .env -- and never when NODE_ENV is production in
+// either: its accounts have a documented development password. A sample-data
+// file that is not applied is not recorded either, so a later run that asks
+// for it still applies it.
+
+export const SAMPLE_DATA_FLAG = '--sample-data';
+export const SAMPLE_DATA_VARIABLE = 'NEXTSPARK_SEED_SAMPLE_DATA';
+/** A line that marks a migration as sample data when its name does not say so. */
+export const SAMPLE_DATA_MARKER = '-- nextspark:sample-data';
+
+// A value as a .env or a shell may write it: any case, quotes, a trailing comment.
+const isProduction = value => /^\s*["']?production\b/i.test(String(value ?? ''));
+const isOn = value => /^\s*["']?(1|true)\b/i.test(String(value ?? ''));
+
+// Copies made before the name rule and the marker existed (the default theme's
+// 090_demo_users_teams.sql and 091_greek_teams_billing.sql, up to 0.1.0-beta.191)
+// are recognised by what they insert: a credential with a sample password. The
+// salts are those of migrations/029_*.sql, which has them but inserts nothing.
+const SAMPLE_PASSWORD_SALTS = ['22de14d5472248ed0bece911df908b2a:', '3db9e98e2b4d3caca97fdf2783791cbc:'];
+const insertsSamplePassword = sql => /insert\s+into\s+(?:"?public"?\s*\.\s*)?"?account\b/i.test(sql) && SAMPLE_PASSWORD_SALTS.some(salt => sql.includes(salt));
+
+export function isSampleDataMigration(filename, sql = '') {
+  const name = filename.toLowerCase();
+  return name.includes('sample_data') || name.includes('sample-data') || sql.split('\n').some(line => line.trim() === SAMPLE_DATA_MARKER) || insertsSamplePassword(sql);
+}
+
+/**
+ * `env` is the process environment, `fileEnv` what the project .env sets.
+ * Returns whether sample data is applied and the line the runner prints about it.
+ */
+export function sampleDataPolicy({ argv = [], env = {}, fileEnv = {} }) {
+  const requested = argv.includes(SAMPLE_DATA_FLAG) || [env[SAMPLE_DATA_VARIABLE], fileEnv[SAMPLE_DATA_VARIABLE]].some(isOn);
+  if ([env.NODE_ENV, fileEnv.NODE_ENV].some(isProduction)) {
+    return { apply: false, notice: `Sample data is not applied: NODE_ENV is production${requested ? ', which the sample-data switch does not override' : ''}.` };
+  }
+  if (requested) {
+    return { apply: true, notice: 'Sample data is applied (development). Its accounts share a documented password: use this only on a local database, and never use a database seeded this way in production (its sample accounts are kept, and later migrations do not disable them).' };
+  }
+  return { apply: false, notice: `Sample data is not applied. For a local development database, run \`pnpm db:seed\` (or pass ${SAMPLE_DATA_FLAG}, or set ${SAMPLE_DATA_VARIABLE}=1).` };
+}

package/scripts/db/verify-theme-migrations.mjs

@@ -28,6 +28,9 @@
 // `pnpm db:migrate` uses. Templates are first extracted into a clean temporary
 // root-first project; apps/dev already is one. No .env is read or written.
 //
+// The run applies the theme's sample data (the database is empty and
+// throwaway), so NODE_ENV is development for it whatever the shell says.
+//
 // MIGRATE_DATABASE_URL is removed from the child's environment because
 // run-migrations.mjs connects to it in preference to DATABASE_URL, which
 // would migrate a database this script never checked.
@@ -46,6 +49,7 @@ import { GLOBAL_OBJECTS, inspectCluster } from './cluster-changes.mjs';
 import { inspectTarget, inspectMaintenanceDatabase } from './inspect-server.mjs';
 import { findTheme } from './theme-location.mjs';
 import { TIME_LIMIT_VARIABLE, migrationTimeLimit } from './migration-time-limit.mjs';
+import { SAMPLE_DATA_VARIABLE } from './sample-data.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -153,7 +157,7 @@ async function main() {
     extracted = fs.mkdtempSync(path.join(os.tmpdir(), `nextspark-template-${theme}-`));
     fs.cpSync(located.sourceDir, extracted, { recursive: true });
     fs.writeFileSync(path.join(extracted, 'nextspark.config.ts'), `export default { plugins: [], template: { name: ${JSON.stringify(theme)}, version: 'test' } }\n`);
-    fs.writeFileSync(path.join(extracted, 'package.json'), JSON.stringify({ name: `nextspark-template-${theme}`, private: true, dependencies: { next: '16.3.6' } }, null, 2));
+    fs.writeFileSync(path.join(extracted, 'package.json'), JSON.stringify({ name: `nextspark-template-${theme}`, private: true, dependencies: { next: '16.3.8' } }, null, 2));
     runDir = extracted;
   }
 
@@ -164,6 +168,8 @@ async function main() {
       ...inheritedEnv,
       DATABASE_URL: databaseUrl,
       [TIME_LIMIT_VARIABLE]: timeLimitSetting,
+      [SAMPLE_DATA_VARIABLE]: '1',
+      NODE_ENV: 'development',
     },
   });
   if (extracted) fs.rmSync(extracted, { recursive: true, force: true });

package/templates/ci-workflows/github/cypress-regression.yml

@@ -66,7 +66,7 @@ jobs:
       - name: Seed test data
         env:
           DATABASE_URL: postgresql://postgres:postgres@localhost:5432/test
-        run: pnpm db:seed || echo "No seed script found, skipping..."
+        run: pnpm db:seed
 
       - name: Build application
         run: pnpm build

package/templates/ci-workflows/github/cypress-smoke.yml

@@ -59,7 +59,8 @@ jobs:
       - name: Setup database
         env:
           DATABASE_URL: postgresql://postgres:postgres@localhost:5432/test
-        run: pnpm db:migrate
+        # a throwaway test database: migrations plus the sample users the tests sign in as
+        run: pnpm db:seed
 
       - name: Build application
         run: pnpm build

package/templates/next.config.mjs

@@ -109,42 +109,21 @@ const nextConfig = {
     formats: ['image/avif', 'image/webp'],
     deviceSizes: [640, 750, 828, 1080, 1200, 1920],
     imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
+    // Hosts the server may fetch and resize through /_next/image.
+    // Keep this list to the exact hosts you use.
     remotePatterns: [
+      // Google profile pictures shown for accounts that sign in with Google.
       {
         protocol: 'https',
         hostname: 'lh3.googleusercontent.com',
         pathname: '/**',
       },
-      {
-        protocol: 'https',
-        hostname: '*.public.blob.vercel-storage.com',
-        pathname: '/**',
-      },
-      {
-        protocol: 'https',
-        hostname: 'images.unsplash.com',
-        pathname: '/**',
-      },
-      {
-        protocol: 'https',
-        hostname: 'upload.wikimedia.org',
-        pathname: '/**',
-      },
-      {
-        protocol: 'https',
-        hostname: 'i.pravatar.cc',
-        pathname: '/**',
-      },
-      {
-        protocol: 'https',
-        hostname: '*.supabase.co',
-        pathname: '/**',
-      },
-      {
-        protocol: 'https',
-        hostname: '*.cloudinary.com',
-        pathname: '/**',
-      },
+      // Examples: add the exact host of your own store, e.g. your Vercel Blob store
+      // (`<store-id>.public.blob.vercel-storage.com`) once uploads use it.
+      // { protocol: 'https', hostname: '<store-id>.public.blob.vercel-storage.com', pathname: '/**' },
+      // { protocol: 'https', hostname: '<project-ref>.supabase.co', pathname: '/**' },
+      // { protocol: 'https', hostname: 'res.cloudinary.com', pathname: '/<cloud-name>/**' },
+      // { protocol: 'https', hostname: 'images.unsplash.com', pathname: '/**' },
     ],
   },
   // Next.js sets TURBOPACK before it loads this file whenever Turbopack builds
@@ -158,7 +137,8 @@ const nextConfig = {
   async headers() {
     const isProduction = process.env.NODE_ENV === 'production';
 
-    // Allowed image domains (must match remotePatterns above)
+    // Image hosts the browser may load directly (CSP img-src). The server only fetches the hosts in
+    // images.remotePatterns above; add a host there too when next/image should serve it.
     // NOTE: Wildcard patterns (*.public.blob.vercel-storage.com, *.supabase.co, *.cloudinary.com)
     // allow images from any account on these services for development flexibility.
     // For production with stricter security, consider restricting to specific account subdomains.

package/templates/projects/blog/package.json

@@ -14,7 +14,7 @@
     "@nextsparkjs/core": ">=0.1.0-0",
     "@nextsparkjs/testing": ">=0.1.0-0",
     "lucide-react": "^0.539.0",
-    "next": "~16.3.6",
+    "next": "~16.3.8",
     "next-intl": "^4.0.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",

package/templates/projects/crm/package.json

@@ -13,7 +13,7 @@
     "@nextsparkjs/core": ">=0.1.0-0",
     "@nextsparkjs/testing": ">=0.1.0-0",
     "lucide-react": "^0.539.0",
-    "next": "~16.3.6",
+    "next": "~16.3.8",
     "next-intl": "^4.0.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",

package/templates/projects/productivity/package.json

@@ -17,7 +17,7 @@
     "@nextsparkjs/core": ">=0.1.0-0",
     "@nextsparkjs/testing": ">=0.1.0-0",
     "lucide-react": "^0.539.0",
-    "next": "~16.3.6",
+    "next": "~16.3.8",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "zod": "^4.0.0"

package/templates/projects/starter/README.md

@@ -21,6 +21,8 @@ cp .env.example .env.local
 
 # Run migrations
 pnpm db:migrate
+# Local development only: also load the sample users (DevKeyring, Cypress)
+pnpm db:seed
 
 # Start development
 pnpm dev

package/templates/projects/starter/config/app.config.ts

@@ -126,6 +126,14 @@ export const APP_CONFIG_OVERRIDES = {
     // methods: ['email-password', 'google'],
     // methods: ['email-otp', 'email-password', 'google'],
 
+    /**
+     * Password endpoints (sign-in/email, sign-up/email, reset). Left undeclared
+     * they follow `methods` in production (off under the passwordless preset) and
+     * stay on in development (dev keyring, `pnpm db:seed` users, Cypress).
+     * Uncomment to keep password logins in production (API clients, test users):
+     */
+    // emailAndPassword: { enabled: true },
+
     /**
      * Session duration / renewal in seconds (defaults: 7 days, renewed daily).
      * Long-lived sessions for an installed PWA, for example:

package/templates/projects/starter/docs/public/01-overview/01-introduction.md

@@ -17,6 +17,8 @@ Welcome to the Starter theme for NextSpark. This minimal theme provides everythi
 3. Run migrations: `pnpm db:migrate`
 4. Start development: `pnpm dev`
 
+Sample users (DevKeyring, Cypress) are for local development only: `pnpm db:seed` loads them; `pnpm db:migrate` alone does not, and neither applies them when `NODE_ENV` is `production`.
+
 ## Project Structure
 
 ```