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

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

@@ -15,7 +15,7 @@ import { dirname, join } from 'node:path'
 import { ENTITY_DIAGNOSTICS, ENTITY_MODULES, entityConfigFile, planEntityRoutes, readAllEntityFacts, readEntityFacts, routableEntities } from '../entity-routes.mjs'
 import { PLAN_DIAGNOSTICS, PLAN_NOTICES, planHost, urlConflicts } from '../plan.mjs'
 import { renderHost } from '../render.mjs'
-import { validateGeneratedModule } from '../static-imports.mjs'
+import { CORE_COMPOSITION_WRAPPERS, validateGeneratedModule } from '../static-imports.mjs'
 import { loadTypeScriptFor } from '../../shared/typescript-compiler.mjs'
 
 const CORE_ROOT = join(import.meta.dirname, '../../../../..')
@@ -29,6 +29,8 @@ const CORE_MODULES = {
   [ENTITY_MODULES.detail]: ['core/entity-detail-route.tsx', factories('createEntityDetailRoute')],
   [ENTITY_MODULES.create]: ['core/entity-create-route.tsx', factories('createEntityCreateRoute')],
   [ENTITY_MODULES.edit]: ['core/entity-edit-route.tsx', factories('createEntityEditRoute')],
+  [ENTITY_MODULES.detailCc]: ['core/entity-detail-route.cc.tsx', factories('createEntityDetailRoute')],
+  [ENTITY_MODULES.editCc]: ['core/entity-edit-route.cc.tsx', factories('createEntityEditRoute')],
   [ENTITY_MODULES.publicItem]: ['core/public-item-route.tsx', factories('createPublicItemRoute', 'createPublicItemMetadata')],
   [ENTITY_MODULES.publicItemCc]: ['core/public-item-route.cc.tsx', factories('createPublicItemRoute', 'createPublicItemMetadata')],
   [ENTITY_MODULES.publicArchive]: ['core/public-archive-route.tsx', factories('createPublicArchiveRoute', 'createPublicArchiveMetadata')],
@@ -690,6 +692,35 @@ test('a host that builds in Cache Components mode only imports the cached item s
   }
 })
 
+test('a Cache Components host writes the detail and edit pages of an entity from the modules that put them behind Suspense (they await `params`)', async () => {
+  const w = world()
+  try {
+    const args = [w, [entity('tasks', 'taskEntityConfig')], { tasks: await factsOf("slug: 'tasks', enabled: true, ui: { dashboard: { showInMenu: true } }") }]
+    const moduleOf = async (target, factory, options) => at(await render((await plan(...args, options)).routes), target).match(new RegExp(`import \\{ ${factory} \\} from "([^"]+)"`))[1]
+    assert.equal(ENTITY_MODULES.detailCc, `${ENTITY_MODULES.detail}.cc`)
+    assert.equal(ENTITY_MODULES.editCc, `${ENTITY_MODULES.edit}.cc`)
+    const detail = options => moduleOf('dashboard/(main)/tasks/[id]/page.tsx', 'createEntityDetailRoute', options)
+    const edit = options => moduleOf('dashboard/(main)/tasks/[id]/edit/page.tsx', 'createEntityEditRoute', options)
+    assert.equal(await detail({ cacheComponents: true }), ENTITY_MODULES.detailCc)
+    assert.equal(await edit({ cacheComponents: true }), ENTITY_MODULES.editCc)
+    // An ISR host keeps the routes that redirect and answer notFound() before anything is sent; so does one that builds both, or does not know
+    for (const options of [{ cacheComponents: false }, {}, { cacheComponents: true, modes: ['isr', 'cc'] }]) {
+      assert.equal(await detail(options), ENTITY_MODULES.detail)
+      assert.equal(await edit(options), ENTITY_MODULES.edit)
+    }
+  } finally {
+    w.cleanup()
+  }
+})
+
+test('every factory module the entity routes import is a known composition module, with the factories it exports (a real host fails facade validation otherwise)', () => {
+  const FACTORY_MODULES = ['layout', 'list', 'detail', 'create', 'edit', 'detailCc', 'editCc', 'publicItem', 'publicItemCc', 'publicArchive']
+  for (const name of FACTORY_MODULES) {
+    const wrappers = CORE_COMPOSITION_WRAPPERS[ENTITY_MODULES[name]]
+    assert.ok(Array.isArray(wrappers) && wrappers.length > 0, `${name}: ${ENTITY_MODULES[name]} is missing from CORE_COMPOSITION_WRAPPERS`)
+  }
+})
+
 // ---------------------------------------------------------------------------
 // "The template replaces": project templates at an entity's dashboard URL in another route group
 // ---------------------------------------------------------------------------

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

@@ -53,6 +53,16 @@ test('core < plugin < project: a higher layer replaces a lower one at the same r
   }
 })
 
+test('a project robots.ts replaces the robots route core ships (#214)', () => {
+  const { root, cleanup } = project({ 'templates/robots.ts': 'export default function robots() { return { rules: { userAgent: "*", disallow: "/" } } }\n' })
+  try {
+    const routes = resolveHostPlan({ coreRoutes: [core('robots.ts', 'robots')], plugins: [], project: { root } })
+    assert.deepEqual(summary(routes), ['robots.ts <- project:@/templates/robots (overrides core route @nextsparkjs/core/routes/robots)'])
+  } finally {
+    cleanup()
+  }
+})
+
 test('the extension does not decide the slot: templates/about/page.ts replaces core about/page.tsx', () => {
   const { root, cleanup } = project({ 'templates/about/page.ts': PAGE })
   try {
@@ -330,8 +340,8 @@ test('core\'s routes carry their protection level, so a composed layout can be t
   assert.equal(withCc.routes.find(route => route.target === 'layout.tsx').compose.specifier, '@nextsparkjs/core/routes/_internal/root-layout.ppr')
   assert.equal(withCc.routes.find(route => route.target === '(auth)/login/page.tsx').specifier, '@nextsparkjs/core/routes/(auth)/login/page.cc')
   assert.deepEqual(withCc.variantsApplied.sort(), [
-    '(auth)/layout.tsx', '(auth)/login/page.tsx', '(auth)/signup/page.tsx', '(public)/docs/[section]/[page]/page.tsx', '(public)/layout.tsx',
-    'dashboard/layout.tsx', 'devtools/layout.tsx', 'layout.tsx', 'superadmin/docs/[section]/[page]/page.tsx', 'superadmin/layout.tsx',
+    '(auth)/layout.tsx', '(auth)/login/page.tsx', '(auth)/signup/page.tsx', '(public)/docs/[section]/[page]/page.tsx', '(public)/layout.tsx', '(public)/page.tsx',
+    'dashboard/(main)/layout.tsx', 'dashboard/layout.tsx', 'devtools/layout.tsx', 'layout.tsx', 'superadmin/docs/[section]/[page]/page.tsx', 'superadmin/layout.tsx',
   ])
   // The layouts that load messages keep their wrapper (from the Cache Components module) and their protection level
   const ccLevel = target => withCc.routes.find(route => route.target === target)

package/scripts/build/registry/host/entity-routes.mjs

@@ -54,6 +54,9 @@ export const ENTITY_MODULES = Object.freeze({
   detail: `${CORE_ROUTES_SPECIFIER}_internal/entity-detail-route`,
   create: `${CORE_ROUTES_SPECIFIER}_internal/entity-create-route`,
   edit: `${CORE_ROUTES_SPECIFIER}_internal/entity-edit-route`,
+  // The detail and edit pages of a host with `cacheComponents` on: the same routes behind a Suspense boundary (they await `params`).
+  detailCc: `${CORE_ROUTES_SPECIFIER}_internal/entity-detail-route.cc`,
+  editCc: `${CORE_ROUTES_SPECIFIER}_internal/entity-edit-route.cc`,
   publicItem: `${CORE_ROUTES_SPECIFIER}_internal/public-item-route`,
   // The item pages of a host with `cacheComponents` on: same factories, `'use cache'` reads instead of `revalidate`.
   publicItemCc: `${CORE_ROUTES_SPECIFIER}_internal/public-item-route.cc`,
@@ -207,7 +210,10 @@ export function planEntityRoutes({ entities, facts, coreRoutes, resolveFile, cac
   const revalidates = cacheComponents !== true && !modes.includes('cc')
   // A host that builds in Cache Components mode only gets the cached item source; one that builds both (the
   // conformance fixture) or does not know keeps the module that works in either.
-  const publicItemModule = cacheComponents === true && modes.length === 0 && modules.publicItemCc ? modules.publicItemCc : modules.publicItem
+  const ccOnly = cacheComponents === true && modes.length === 0
+  const publicItemModule = ccOnly && modules.publicItemCc ? modules.publicItemCc : modules.publicItem
+  const detailModule = ccOnly && modules.detailCc ? modules.detailCc : modules.detail
+  const editModule = ccOnly && modules.editCc ? modules.editCc : modules.edit
 
   const coreFacade = (kind, target, specifier) => ({
     kind,
@@ -275,8 +281,8 @@ export function planEntityRoutes({ entities, facts, coreRoutes, resolveFile, cac
         coreFacade('loading', `${base}/loading.tsx`, modules.loading),
         composed('page', `${base}/page.tsx`, 'createEntityListRoute', modules.list, [config, arg.template()], { acceptsTemplate: true, reexport: [{ names: ['metadata'], specifier: modules.listMetadata }] }),
         composed('page', `${base}/create/page.tsx`, 'createEntityCreateRoute', modules.create, [config, arg.template()], { acceptsTemplate: true }),
-        composed('page', `${base}/[id]/page.tsx`, 'createEntityDetailRoute', modules.detail, [config, arg.literal(children), arg.template()], { acceptsTemplate: true, reexport: [{ names: ['metadata'], specifier: modules.detailMetadata }] }),
-        composed('page', `${base}/[id]/edit/page.tsx`, 'createEntityEditRoute', modules.edit, [config, arg.template()], { acceptsTemplate: true })
+        composed('page', `${base}/[id]/page.tsx`, 'createEntityDetailRoute', detailModule, [config, arg.literal(children), arg.template()], { acceptsTemplate: true, reexport: [{ names: ['metadata'], specifier: modules.detailMetadata }] }),
+        composed('page', `${base}/[id]/edit/page.tsx`, 'createEntityEditRoute', editModule, [config, arg.template()], { acceptsTemplate: true })
       )
     }
 

package/scripts/build/registry/host/static-imports.mjs

@@ -80,11 +80,15 @@ export const CORE_COMPOSITION_WRAPPERS = Object.freeze({
   [`${INTERNAL}devtools-layout.cc`]: ['withDevtoolsGuard'],
   // Every page and layout under /superadmin and /devtools (the manifest's `access`).
   [`${INTERNAL}area-access`]: ['withSuperadminAccess', 'withDevtoolsAccess', 'withSuperadminMetadata', 'withDevtoolsMetadata', 'withSuperadminRouteAccess', 'withDevtoolsRouteAccess'],
+  // The same, for a Cache Components host (each segment checks inside its own Suspense boundary).
+  [`${INTERNAL}area-access.cc`]: ['withSuperadminAccess', 'withDevtoolsAccess', 'withSuperadminMetadata', 'withDevtoolsMetadata', 'withSuperadminRouteAccess', 'withDevtoolsRouteAccess'],
   [`${INTERNAL}entity-layout-route`]: ['createEntityLayoutRoute'],
   [`${INTERNAL}entity-list-route`]: ['createEntityListRoute'],
   [`${INTERNAL}entity-detail-route`]: ['createEntityDetailRoute'],
   [`${INTERNAL}entity-create-route`]: ['createEntityCreateRoute'],
   [`${INTERNAL}entity-edit-route`]: ['createEntityEditRoute'],
+  [`${INTERNAL}entity-detail-route.cc`]: ['createEntityDetailRoute'],
+  [`${INTERNAL}entity-edit-route.cc`]: ['createEntityEditRoute'],
   [`${INTERNAL}public-item-route`]: ['createPublicItemRoute', 'createPublicItemMetadata'],
   [`${INTERNAL}public-item-route.cc`]: ['createPublicItemRoute', 'createPublicItemMetadata'],
   [`${INTERNAL}public-archive-route`]: ['createPublicArchiveRoute', 'createPublicArchiveMetadata'],

package/scripts/build/routes-manifest.mjs

@@ -66,6 +66,8 @@ export const VARIANT_FILES = Object.freeze({
     'superadmin/layout.cc.tsx': 'superadmin/layout.tsx',
     'devtools/layout.cc.tsx': 'devtools/layout.tsx',
     'dashboard/layout.cc.tsx': 'dashboard/layout.tsx',
+    'dashboard/(main)/layout.cc.tsx': 'dashboard/(main)/layout.tsx',
+    '(public)/page.cc.tsx': '(public)/page.tsx',
     '(auth)/login/page.cc.tsx': '(auth)/login/page.tsx',
     '(auth)/signup/page.cc.tsx': '(auth)/signup/page.tsx',
     '(public)/docs/[section]/[page]/page.cc.tsx': '(public)/docs/[section]/[page]/page.tsx',
@@ -105,6 +107,15 @@ export const VARIANT_COMPOSE = Object.freeze({
   'devtools/layout.cc.tsx': { wrapper: 'withDevtoolsGuard', specifier: `${ROUTES_SUBPATH}/_internal/devtools-layout.cc` },
 })
 
+/**
+ * The per-segment access check of a variant, when it differs from its base route's: in Cache Components mode every
+ * page and layout under an area checks the role inside its own Suspense boundary (area-access.cc).
+ */
+export const VARIANT_ACCESS = Object.freeze({
+  'superadmin/layout.cc.tsx': { ...ACCESS_ROUTES['superadmin/layout.tsx'], specifier: `${ROUTES_SUBPATH}/_internal/area-access.cc` },
+  'devtools/layout.cc.tsx': { ...ACCESS_ROUTES['devtools/layout.tsx'], specifier: `${ROUTES_SUBPATH}/_internal/area-access.cc` },
+})
+
 /**
  * Files that live next to a route without being one: the API explorer's presets, read as text by the
  * registry build (registry/discovery/api-presets.mjs), and its docs.md.
@@ -168,7 +179,8 @@ export function buildRoutesManifest(routesDir = ROUTES_DIR) {
       const replaced = manifest.find(entry => entry.target === target)
       if (!replaced) throw new Error(`Variant ${file} (${mode}) replaces ${target}, which is not a core route`)
       const compose = VARIANT_COMPOSE[file] ?? replaced.compose
-      return { kind: replaced.kind, target, specifier: specifierForRouteFile(file), ...(compose ? { compose } : {}), ...(replaced.access ? { access: replaced.access } : {}) }
+      const access = VARIANT_ACCESS[file] ?? replaced.access
+      return { kind: replaced.kind, target, specifier: specifierForRouteFile(file), ...(compose ? { compose } : {}), ...(access ? { access } : {}) }
     })
   }
   return { manifest, variants }

package/scripts/db/ssl-config.mjs

@@ -29,6 +29,17 @@ export function stripSSLParams(databaseUrl) {
   }
 }
 
+// On globalThis, like src/lib/db.ts: one warning per process however many copies of the module are loaded
+const SSL_WARNED = Symbol.for('nextspark.dbSslDisabledWarned')
+
+/** Once per process, and not for a loopback host: mirrors `warnSSLDisabledInProduction` in src/lib/db.ts. */
+function warnSSLDisabledInProduction(url) {
+  if (globalThis[SSL_WARNED]) return
+  if (['localhost', '127.0.0.1', '[::1]'].includes(url.hostname.toLowerCase())) return
+  globalThis[SSL_WARNED] = true
+  console.warn('[DB] WARNING: SSL disabled in production environment. This is insecure!')
+}
+
 /**
  * Parse the SSL policy used by database scripts.
  *
@@ -47,7 +58,7 @@ export function parseSSLConfig(databaseUrl) {
     if (sslmode) {
       switch (sslmode) {
         case 'disable':
-          if (isProduction) console.warn('[DB] WARNING: SSL disabled in production environment. This is insecure!')
+          if (isProduction) warnSSLDisabledInProduction(url)
           return false
         case 'require':
         case 'prefer':

package/templates/next.config.mjs

@@ -260,35 +260,8 @@ const nextConfig = {
         source: '/:path*',
         headers: securityHeaders
       },
-      // CORS headers for API routes
-      // NOTE: In development, CORS is handled dynamically by API routes using addCorsHeaders()
-      // to support multiple origins (web app, mobile app, etc.)
-      // In production, we set static CORS headers here
-      ...(isProduction ? [{
-        source: '/api/:path*',
-        headers: [
-          {
-            key: 'Access-Control-Allow-Origin',
-            value: process.env.NEXT_PUBLIC_APP_URL || 'http://localhost:3000'
-          },
-          {
-            key: 'Access-Control-Allow-Methods',
-            value: 'GET, POST, PUT, DELETE, OPTIONS, PATCH'
-          },
-          {
-            key: 'Access-Control-Allow-Headers',
-            value: 'Content-Type, Authorization, x-api-key, x-verify-from-ui, Cookie, Set-Cookie'
-          },
-          {
-            key: 'Access-Control-Allow-Credentials',
-            value: 'true'
-          },
-          {
-            key: 'Access-Control-Expose-Headers',
-            value: 'Set-Cookie'
-          }
-        ]
-      }] : [])
+      // No CORS headers here: core's API routes answer CORS per request (addCorsHeaders), so the
+      // origins in api.cors.allowedOrigins and CORS_ADDITIONAL_ORIGINS get their grant in production too
     ]
   },
 }

package/templates/projects/blog/api/authors/[username]/route.ts

@@ -10,6 +10,7 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { queryWithRLS } from '@nextsparkjs/core/lib/db'
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
+import { corsPreflight } from '@nextsparkjs/core/lib/api/cors-response'
 
 interface Author {
   id: string
@@ -151,3 +152,5 @@ const getHandler = async (
 }
 
 export const GET = withRateLimitTier(getHandler, 'read')
+
+export const OPTIONS = corsPreflight

package/templates/projects/blog/api/authors/route.ts

@@ -10,6 +10,7 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { queryWithRLS } from '@nextsparkjs/core/lib/db'
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
+import { corsPreflight } from '@nextsparkjs/core/lib/api/cors-response'
 
 interface AuthorWithCount {
   id: string
@@ -64,3 +65,5 @@ const getHandler = async (request: NextRequest) => {
 }
 
 export const GET = withRateLimitTier(getHandler, 'read')
+
+export const OPTIONS = corsPreflight

package/templates/projects/blog/api/posts/public/route.ts

@@ -11,6 +11,7 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { queryWithRLS } from '@nextsparkjs/core/lib/db'
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
+import { corsPreflight } from '@nextsparkjs/core/lib/api/cors-response'
 
 interface Post {
   id: string
@@ -152,3 +153,5 @@ const getHandler = async (request: NextRequest) => {
 }
 
 export const GET = withRateLimitTier(getHandler, 'read')
+
+export const OPTIONS = corsPreflight

package/templates/proxy.ts

@@ -200,8 +200,19 @@ function getSession(request: NextRequest) {
  * session. Gating the strip on protected prefixes is not enough: Next.js
  * dispatches Server Actions by the `Next-Action` header, not by the URL, so an
  * action can be POSTed to a public path with a forged `x-user-id`.
+ *
+ * The `x-api-*` names are never set here: core takes an API key's identity from
+ * validating the key, and nothing downstream may receive them from the client.
  */
-const TRUSTED_IDENTITY_HEADERS = ['x-user-id', 'x-user-email', 'x-pathname', 'x-active-team-id'] as const
+const TRUSTED_IDENTITY_HEADERS = [
+  'x-user-id',
+  'x-user-email',
+  'x-pathname',
+  'x-active-team-id',
+  'x-api-user-id',
+  'x-api-key-id',
+  'x-api-scopes',
+] as const
 
 /**
  * Build the request headers forwarded to the app: inbound copy minus every