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

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

@@ -0,0 +1,362 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import { CoreRouteManifestError, loadCoreRouteManifest, loadProtectedTargets } from '../core-routes.mjs'
+import { HostPlanError, PLAN_DIAGNOSTICS, planHost, resolveHostPlan } from '../plan.mjs'
+
+const PAGE = 'export default function Page() { return null }\n'
+const ROUTE = 'export async function GET() { return Response.json({}) }\n'
+
+function project(files) {
+  const root = mkdtempSync(join(tmpdir(), 'nextspark-host-plan-'))
+  for (const [path, content] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true })
+    writeFileSync(join(root, path), content)
+  }
+  return { root, cleanup: () => rmSync(root, { recursive: true, force: true }) }
+}
+
+const core = (target, kind = 'page', extra = {}) => ({ kind, target, specifier: `@nextsparkjs/core/routes/${target.replace(/\.tsx?$/, '')}`, file: `/core/${target}`, protected: false, ...extra })
+
+const summary = routes => routes.map(route => `${route.target} <- ${route.origin}:${route.specifier}${route.overrides ? ` (overrides ${route.overrides})` : ''}`)
+
+test('core < plugin < project: a higher layer replaces a lower one at the same route file', () => {
+  const { root, cleanup } = project({
+    'templates/about/page.tsx': PAGE,
+    'templates/pricing/page.tsx': PAGE,
+    'api/notes/route.ts': ROUTE,
+    'plugins/blog/templates/about/page.tsx': PAGE,
+    'plugins/blog/templates/blog/page.tsx': PAGE,
+    'plugins/blog/api/posts/route.ts': ROUTE,
+  })
+  try {
+    const routes = resolveHostPlan({
+      coreRoutes: [core('layout.tsx', 'layout'), core('about/page.tsx'), core('blog/page.tsx'), core('page.tsx')],
+      plugins: [{ name: 'blog', root: join(root, 'plugins/blog'), importBase: '@/plugins/blog' }],
+      project: { root },
+    })
+    assert.deepEqual(summary(routes), [
+      'about/page.tsx <- project:@/templates/about/page (overrides plugins/blog/templates/about/page.tsx)',
+      'api/notes/route.ts <- project:@/api/notes/route',
+      'api/plugins/blog/posts/route.ts <- plugin:@/plugins/blog/api/posts/route',
+      'blog/page.tsx <- plugin:@/plugins/blog/templates/blog/page (overrides core route @nextsparkjs/core/routes/blog/page)',
+      'layout.tsx <- core:@nextsparkjs/core/routes/layout',
+      'page.tsx <- core:@nextsparkjs/core/routes/page',
+      'pricing/page.tsx <- project:@/templates/pricing/page',
+    ])
+    assert.equal(routes.find(route => route.target === 'about/page.tsx').file, join(root, 'templates/about/page.tsx'))
+  } 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 {
+    const routes = resolveHostPlan({ coreRoutes: [core('about/page.tsx')], project: { root } })
+    assert.deepEqual(summary(routes), ['about/page.ts <- project:@/templates/about/page (overrides core route @nextsparkjs/core/routes/about/page)'])
+  } finally {
+    cleanup()
+  }
+})
+
+test('two project files for one route are a collision naming both sources', () => {
+  const { root, cleanup } = project({ 'templates/api/notes/route.ts': ROUTE, 'api/notes/route.ts': ROUTE, 'templates/x/page.tsx': PAGE, 'templates/x/page.ts': PAGE })
+  try {
+    const { diagnostics } = planHost({ coreRoutes: [], project: { root } })
+    assert.deepEqual(diagnostics.map(d => [d.code, d.sources]), [
+      [PLAN_DIAGNOSTICS.COLLISION, ['api/notes/route.ts', 'templates/api/notes/route.ts']],
+      [PLAN_DIAGNOSTICS.COLLISION, ['templates/x/page.ts', 'templates/x/page.tsx']],
+    ])
+    assert.match(diagnostics[0].message, /src\/app\/api\/notes\/route\.ts: two project files provide this route: api\/notes\/route\.ts and templates\/api\/notes\/route\.ts/)
+    assert.throws(() => resolveHostPlan({ coreRoutes: [], project: { root } }), HostPlanError)
+  } finally {
+    cleanup()
+  }
+})
+
+test('two plugins providing one route collide, naming both plugins', () => {
+  const { root, cleanup } = project({ 'plugins/a/templates/shop/page.tsx': PAGE, 'plugins/b/templates/shop/page.tsx': PAGE })
+  try {
+    const plugins = ['b', 'a'].map(name => ({ name, root: join(root, 'plugins', name), importBase: `@/plugins/${name}` }))
+    const { diagnostics } = planHost({ coreRoutes: [core('shop/page.tsx')], plugins, project: { root: join(root, 'none') } })
+    assert.equal(diagnostics.length, 1)
+    assert.equal(diagnostics[0].code, PLAN_DIAGNOSTICS.COLLISION)
+    assert.deepEqual(diagnostics[0].sources, ['plugins/a/templates/shop/page.tsx', 'plugins/b/templates/shop/page.tsx'])
+    assert.match(diagnostics[0].message, /two plugins provide this route: plugins\/a\/templates\/shop\/page\.tsx and plugins\/b\/templates\/shop\/page\.tsx/)
+  } finally {
+    cleanup()
+  }
+})
+
+test('a plugin or project file over a protected core route is refused, naming both', () => {
+  const { root, cleanup } = project({ 'plugins/a/templates/dashboard/layout.tsx': PAGE, 'templates/dashboard/layout.tsx': PAGE })
+  try {
+    const { routes, diagnostics } = planHost({
+      coreRoutes: [core('dashboard/layout.tsx', 'layout', { protected: true })],
+      plugins: [{ name: 'a', root: join(root, 'plugins/a'), importBase: '@/plugins/a' }],
+      project: { root },
+    })
+    assert.deepEqual(diagnostics.map(d => [d.code, d.sources]), [
+      [PLAN_DIAGNOSTICS.PROTECTED, ['core route @nextsparkjs/core/routes/dashboard/layout', 'templates/dashboard/layout.tsx']],
+      [PLAN_DIAGNOSTICS.PROTECTED, ['core route @nextsparkjs/core/routes/dashboard/layout', 'plugins/a/templates/dashboard/layout.tsx']],
+    ])
+    assert.match(diagnostics[1].message, /plugins\/a\/templates\/dashboard\/layout\.tsx would replace the protected core route @nextsparkjs\/core\/routes\/dashboard\/layout/)
+    assert.equal(routes[0].origin, 'core')
+  } finally {
+    cleanup()
+  }
+})
+
+test('a page and a Route Handler left in one directory conflict', () => {
+  const { root, cleanup } = project({ 'templates/feed/route.ts': ROUTE })
+  try {
+    const { diagnostics } = planHost({ coreRoutes: [core('feed/page.tsx')], project: { root } })
+    assert.deepEqual(diagnostics.map(d => d.code), [PLAN_DIAGNOSTICS.PAGE_ROUTE_CONFLICT])
+    assert.deepEqual(diagnostics[0].sources, ['core route @nextsparkjs/core/routes/feed/page', 'templates/feed/route.ts'])
+  } finally {
+    cleanup()
+  }
+})
+
+test('only route files are planned: components, tests, dotfiles and node_modules are ignored', () => {
+  const { root, cleanup } = project({
+    'templates/blog/page.tsx': PAGE,
+    'templates/blog/components/Card.tsx': PAGE,
+    'templates/blog/page.test.tsx': PAGE,
+    'templates/blog/page.meta.ts': 'export const x = 1\n',
+    'templates/.hidden/page.tsx': PAGE,
+    'templates/node_modules/x/page.tsx': PAGE,
+    'templates/blog/opengraph-image2.tsx': PAGE,
+  })
+  try {
+    assert.deepEqual(resolveHostPlan({ coreRoutes: [], project: { root } }).map(route => `${route.kind}:${route.target}`), ['opengraph-image:blog/opengraph-image2.tsx', 'page:blog/page.tsx'])
+  } finally {
+    cleanup()
+  }
+})
+
+test('cache-mode suffixes are separate slots only for a host that declares the modes', () => {
+  const { root, cleanup } = project({ 'templates/isr/page.isr.tsx': PAGE, 'templates/cached/page.cc.tsx': PAGE })
+  try {
+    assert.deepEqual(resolveHostPlan({ coreRoutes: [], project: { root } }), [])
+    assert.deepEqual(resolveHostPlan({ coreRoutes: [], project: { root }, modes: ['isr', 'cc'] }).map(route => [route.target, route.mode]), [
+      ['cached/page.cc.tsx', 'cc'],
+      ['isr/page.isr.tsx', 'isr'],
+    ])
+  } finally {
+    cleanup()
+  }
+})
+
+test('a symlinked route source is reported, not followed', () => {
+  const { root, cleanup } = project({ 'elsewhere/page.tsx': PAGE })
+  try {
+    mkdirSync(join(root, 'templates/linked'), { recursive: true })
+    symlinkSync(join(root, 'elsewhere/page.tsx'), join(root, 'templates/linked/page.tsx'))
+    const { routes, diagnostics } = planHost({ coreRoutes: [], project: { root } })
+    assert.deepEqual(routes, [])
+    assert.deepEqual(diagnostics.map(d => d.code), [PLAN_DIAGNOSTICS.SOURCE_SYMLINK])
+  } finally {
+    cleanup()
+  }
+})
+
+test('the plan is deterministic: input order does not change it', () => {
+  const { root, cleanup } = project({ 'templates/b/page.tsx': PAGE, 'templates/a/page.tsx': PAGE, 'plugins/z/api/x/route.ts': ROUTE, 'plugins/y/api/x/route.ts': ROUTE })
+  try {
+    const plugins = ['z', 'y'].map(name => ({ name, root: join(root, 'plugins', name), importBase: `@/plugins/${name}` }))
+    const coreRoutes = [core('b/page.tsx'), core('layout.tsx', 'layout'), core('Z/page.tsx')]
+    const one = resolveHostPlan({ coreRoutes, plugins, project: { root } })
+    const two = resolveHostPlan({ coreRoutes: [...coreRoutes].reverse(), plugins: [...plugins].reverse(), project: { root } })
+    assert.deepEqual(one, two)
+    // Code-unit order (uppercase first), not locale order
+    assert.deepEqual(one.map(route => route.target), ['Z/page.tsx', 'a/page.tsx', 'api/plugins/y/x/route.ts', 'api/plugins/z/x/route.ts', 'b/page.tsx', 'layout.tsx'])
+  } finally {
+    cleanup()
+  }
+})
+
+test('loadCoreRouteManifest: null without a manifest; entries validated; files resolved; protection applied', async () => {
+  const { root, cleanup } = project({
+    'src/routes/manifest.json': JSON.stringify([
+      { kind: 'layout', target: 'layout.tsx', specifier: '@nextsparkjs/core/routes/layout' },
+      { kind: 'page', target: 'dashboard/page.tsx', specifier: '@nextsparkjs/core/routes/dashboard/page', protected: true },
+    ]),
+    'src/routes/layout.tsx': PAGE,
+    'dist/routes/dashboard/page.js': PAGE,
+    'package.json': JSON.stringify({ name: '@nextsparkjs/core', exports: { './routes/*': { types: './dist/routes/*.d.ts', import: './dist/routes/*.js' } } }),
+  })
+  try {
+    assert.equal(await loadCoreRouteManifest({ coreRoot: join(root, 'missing') }), null)
+    const manifest = await loadCoreRouteManifest({ coreRoot: root })
+    assert.match(manifest.hash, /^[0-9a-f]{64}$/)
+    assert.deepEqual(manifest.routes.map(route => [route.target, route.file.slice(root.length), route.protected]), [
+      ['layout.tsx', '/src/routes/layout.tsx', false],
+      ['dashboard/page.tsx', '/dist/routes/dashboard/page.js', true],
+    ])
+    await assert.rejects(loadCoreRouteManifest({ coreRoot: root, entries: [{ kind: 'pagee', target: '../x', specifier: '' }] }), error => {
+      assert.ok(error instanceof CoreRouteManifestError)
+      assert.equal(error.problems.length, 3)
+      return true
+    })
+    await assert.rejects(loadCoreRouteManifest({ coreRoot: root, entries: [{ kind: 'page', target: 'x/page.tsx', specifier: '@nextsparkjs/core/routes/nowhere' }] }), /no module found for @nextsparkjs\/core\/routes\/nowhere/)
+  } finally {
+    cleanup()
+  }
+})
+
+test("core's PROTECTED_PATHS are protected targets (any protection level)", async () => {
+  const coreRoot = join(import.meta.dirname, '../../../../..')
+  const isProtected = await loadProtectedTargets(coreRoot)
+  assert.equal(isProtected('dashboard/layout.tsx'), true)
+  assert.equal(isProtected('layout.tsx'), true)
+  assert.equal(isProtected('about/page.tsx'), false)
+})
+
+test('core route variants: variants.json replaces entries by target only when the host has cacheComponents on', async () => {
+  const { root, cleanup } = project({
+    'src/routes/manifest.json': JSON.stringify([
+      { kind: 'layout', target: 'layout.tsx', specifier: '@nextsparkjs/core/routes/layout' },
+      { kind: 'page', target: 'page.tsx', specifier: '@nextsparkjs/core/routes/page' },
+    ]),
+    'src/routes/variants.json': JSON.stringify({ cacheComponents: [{ kind: 'layout', target: 'layout.tsx', specifier: '@nextsparkjs/core/routes/layout.ppr' }] }),
+    'src/routes/layout.tsx': PAGE,
+    'src/routes/layout.ppr.tsx': PAGE,
+    'src/routes/page.tsx': PAGE,
+  })
+  try {
+    const specifiers = manifest => manifest.routes.map(route => `${route.target}=${route.specifier}`)
+    const off = await loadCoreRouteManifest({ coreRoot: root, cacheComponents: false })
+    const unknown = await loadCoreRouteManifest({ coreRoot: root })
+    const on = await loadCoreRouteManifest({ coreRoot: root, cacheComponents: true })
+    assert.deepEqual(specifiers(off), ['layout.tsx=@nextsparkjs/core/routes/layout', 'page.tsx=@nextsparkjs/core/routes/page'])
+    assert.deepEqual(specifiers(unknown), specifiers(off))
+    assert.deepEqual(specifiers(on), ['layout.tsx=@nextsparkjs/core/routes/layout.ppr', 'page.tsx=@nextsparkjs/core/routes/page'])
+    assert.equal(on.routes[0].file, join(root, 'src/routes/layout.ppr.tsx'))
+    assert.deepEqual(on.variantsApplied, ['layout.tsx'])
+    assert.notEqual(on.hash, off.hash, 'the setting is part of the input hash')
+
+    for (const [variants, expected] of [
+      [{ cacheComponents: [{ kind: 'page', target: 'nowhere/page.tsx', specifier: '@nextsparkjs/core/routes/x' }] }, /replaces no manifest entry/],
+      [{ cacheComponents: [{ kind: 'page', target: 'layout.tsx', specifier: '@nextsparkjs/core/routes/x' }] }, /kind page differs from the manifest's layout/],
+      [{ turbo: [] }, /unknown setting "turbo"/],
+    ]) {
+      await assert.rejects(loadCoreRouteManifest({ coreRoot: root, variants, cacheComponents: false }), expected)
+    }
+  } finally {
+    cleanup()
+  }
+})
+
+test("readCacheComponents reads only a literal next.config setting", async () => {
+  const { readCacheComponents } = await import('../prepare.mjs')
+  const cases = [
+    [{}, undefined],
+    [{ 'next.config.ts': 'export default { cacheComponents: true }\n' }, true],
+    [{ 'next.config.mjs': 'const c = {\n  // cacheComponents: true,\n  cacheComponents: false,\n}\nexport default c\n' }, false],
+    [{ 'next.config.js': 'module.exports = { cacheComponents: process.env.CC === "1" }\n' }, undefined],
+    [{ 'next.config.ts': 'export default { cacheComponents: flag }\n' }, undefined],
+    [{ 'next.config.ts': 'export default a ? { cacheComponents: true } : { cacheComponents: false }\n' }, undefined],
+  ]
+  for (const [files, expected] of cases) {
+    const { root, cleanup } = project(files)
+    try {
+      assert.equal(readCacheComponents(root), expected, JSON.stringify(files))
+    } finally {
+      cleanup()
+    }
+  }
+})
+
+// ---------------------------------------------------------------------------
+// Stage 4: composed layouts in the core manifest
+// ---------------------------------------------------------------------------
+
+test('a manifest layout may declare the wrapper its overrides are composed with; anything else about compose is a problem', async () => {
+  const { root, cleanup } = project({ 'src/routes/layout.tsx': 'export default function L() {}\n', 'src/routes/_internal/root-layout.tsx': 'export function withRootLayout() {}\n', 'src/routes/page.tsx': PAGE })
+  try {
+    const compose = { wrapper: 'withRootLayout', specifier: '@nextsparkjs/core/routes/_internal/root-layout' }
+    const manifest = await loadCoreRouteManifest({
+      coreRoot: root,
+      entries: [{ kind: 'layout', target: 'layout.tsx', specifier: '@nextsparkjs/core/routes/layout', compose }],
+      isProtected: () => false,
+    })
+    assert.deepEqual(manifest.routes[0].compose, { ...compose, file: join(root, 'src/routes/_internal/root-layout.tsx') })
+
+    const bad = entries => assert.rejects(loadCoreRouteManifest({ coreRoot: root, entries, isProtected: () => false }), CoreRouteManifestError)
+    const layout = extra => ({ kind: 'layout', target: 'layout.tsx', specifier: '@nextsparkjs/core/routes/layout', ...extra })
+    await bad([{ kind: 'page', target: 'page.tsx', specifier: '@nextsparkjs/core/routes/page', compose }])
+    await bad([layout({ compose: 'withRootLayout' })])
+    await bad([layout({ compose: { ...compose, wrapper: 'with Root' } })])
+    await bad([layout({ compose: { ...compose, specifier: '../_internal/root-layout' } })])
+    await bad([layout({ compose: { ...compose, specifier: './root-layout' } })])
+    await bad([layout({ compose: { ...compose, specifier: '@x/pkg/../../etc' } })])
+    await bad([layout({ compose: { ...compose, specifier: '@x/pkg/a b' } })])
+    await bad([layout({ compose: { ...compose, extra: 1 } })])
+    await assert.rejects(
+      loadCoreRouteManifest({ coreRoot: root, entries: [layout({ compose: { ...compose, specifier: '@nextsparkjs/core/routes/_internal/nowhere' } })], isProtected: () => false }),
+      /no module found for @nextsparkjs\/core\/routes\/_internal\/nowhere/
+    )
+  } finally {
+    cleanup()
+  }
+})
+
+test('core\'s routes carry their protection level, so a composed layout can be told from a replaceable one', async () => {
+  const coreRoot = join(import.meta.dirname, '../../../../..')
+  const isProtected = await loadProtectedTargets(coreRoot)
+  assert.equal(isProtected.level('layout.tsx'), 'protected_render')
+  assert.equal(isProtected.level('dashboard/layout.tsx'), 'protected_all')
+  assert.equal(isProtected.level('about/page.tsx'), null)
+  const manifest = await loadCoreRouteManifest({ coreRoot })
+  const level = target => manifest.routes.find(route => route.target === target)
+  assert.equal(level('layout.tsx').protectionLevel, 'protected_render')
+  assert.equal(level('dashboard/layout.tsx').protectionLevel, 'protected_all')
+  assert.equal(level('(auth)/login/page.tsx').protected, false)
+  assert.equal('protectionLevel' in level('(auth)/login/page.tsx'), false)
+  // The five wrapped layouts declare their wrapper, and every wrapper module resolves
+  assert.deepEqual(manifest.routes.filter(route => route.compose).map(route => [route.target, route.compose.wrapper]), [
+    ['(auth)/layout.tsx', 'withAuthMessages'],
+    ['(public)/layout.tsx', 'withPublicMessages'],
+    ['devtools/layout.tsx', 'withDevtoolsGuard'],
+    ['layout.tsx', 'withRootLayout'],
+    ['superadmin/layout.tsx', 'withSuperadminGuard'],
+  ])
+  const withCc = await loadCoreRouteManifest({ coreRoot, cacheComponents: true })
+  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',
+  ])
+  // 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)
+  const INTERNAL = '@nextsparkjs/core/routes/_internal/'
+  assert.deepEqual(withCc.routes.filter(route => route.compose && route.target !== 'layout.tsx').map(route => [route.target, route.compose.wrapper, route.compose.specifier]), [
+    ['(auth)/layout.tsx', 'withAuthMessages', `${INTERNAL}auth-layout.cc`],
+    ['(public)/layout.tsx', 'withPublicMessages', `${INTERNAL}public-layout.cc`],
+    ['devtools/layout.tsx', 'withDevtoolsGuard', `${INTERNAL}devtools-layout.cc`],
+    ['superadmin/layout.tsx', 'withSuperadminGuard', `${INTERNAL}superadmin-layout.cc`],
+  ])
+  assert.equal(ccLevel('dashboard/layout.tsx').specifier, '@nextsparkjs/core/routes/dashboard/layout.cc')
+  for (const target of ['layout.tsx', 'dashboard/layout.tsx']) assert.equal(ccLevel(target).protectionLevel, level(target).protectionLevel, target)
+})
+
+test('planHost without a project (or a project without a root) plans core and the plugins only, without throwing', () => {
+  const routes = [core('layout.tsx', 'layout'), core('about/page.tsx')]
+  const only = ({ routes: planned, diagnostics }) => [planned.map(route => route.target), diagnostics]
+  assert.deepEqual(only(planHost({ coreRoutes: routes })), [['about/page.tsx', 'layout.tsx'], []])
+  assert.deepEqual(only(planHost({ coreRoutes: routes, project: undefined })), [['about/page.tsx', 'layout.tsx'], []])
+  assert.deepEqual(only(planHost({ coreRoutes: routes, project: {} })), [['about/page.tsx', 'layout.tsx'], []])
+  const { root, cleanup } = project({ 'plugins/blog/api/posts/route.ts': ROUTE })
+  try {
+    const planned = planHost({ coreRoutes: routes, plugins: [{ name: 'blog', root: join(root, 'plugins/blog'), importBase: '@/plugins/blog' }] })
+    assert.deepEqual(planned.routes.map(route => route.target), ['about/page.tsx', 'api/plugins/blog/posts/route.ts', 'layout.tsx'])
+  } finally {
+    cleanup()
+  }
+})

package/scripts/build/registry/host/__tests__/host-project-composition.test.mjs

@@ -0,0 +1,269 @@
+/**
+ * Stage 4 (#203) through a real project and the installed core's route manifest: per-entity routes,
+ * composed layouts, the stylesheet, billing webhook extensions and the API namespaces, generated and
+ * published by the production pipeline.
+ *
+ * Run: node --test packages/core/scripts/build/registry/host/__tests__/host-project-composition.test.mjs
+ */
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { PrepareError, checkHost, prepareHost, projectHostConfig, renderHostFiles } from '../prepare.mjs'
+import { PAGE, ROUTE, read, write } from './host-helpers.mjs'
+
+const TASKS = `import type { EntityConfig } from '@nextsparkjs/core/lib/entities/types'
+export const taskEntityConfig: EntityConfig = {
+  slug: 'tasks',
+  enabled: true,
+  names: { singular: 'task', plural: 'Tasks' },
+  ui: { dashboard: { showInMenu: true } },
+} as EntityConfig
+`
+const POSTS = `export const postsEntityConfig = {
+  slug: 'posts',
+  enabled: true,
+  access: { public: true, basePath: '/blog' },
+  ui: { dashboard: { showInMenu: true }, public: { hasArchivePage: true } },
+  builder: { enabled: true },
+}
+`
+const LAYOUT = 'export default function Layout({ children }: { children: React.ReactNode }) { return children }\n'
+
+function project(extra = {}) {
+  const root = mkdtempSync(join(tmpdir(), 'nextspark-host-composition-'))
+  write(root, 'nextspark.config.ts', "export default { plugins: [], billing: { webhookExtensions: { stripe: './lib/billing/stripe-webhook-extensions' } } }\n")
+  write(root, 'package.json', JSON.stringify({ name: 'composition', dependencies: { next: '16.3.5' } }))
+  write(root, 'config/theme.config.ts', "export const compositionThemeConfig = { name: 'composition' }\n")
+  write(root, 'styles/globals.css', '@import "tailwindcss";\n')
+  write(root, 'lib/billing/stripe-webhook-extensions.ts', 'export const stripeWebhookExtensions = {}\n')
+  write(root, 'entities/tasks/tasks.config.ts', TASKS)
+  write(root, 'entities/posts/posts.config.ts', POSTS)
+  write(root, 'templates/layout.tsx', LAYOUT)
+  write(root, 'templates/(public)/layout.tsx', LAYOUT)
+  write(root, 'templates/(public)/blog/[slug]/page.tsx', PAGE('BlogPost'))
+  write(root, 'templates/dashboard/(main)/tasks/page.tsx', PAGE('Tasks'))
+  write(root, 'api/ai/usage/route.ts', ROUTE)
+  for (const [path, content] of Object.entries(extra)) write(root, path, content)
+  return { root, cleanup: () => rmSync(root, { recursive: true, force: true }) }
+}
+
+const at = (files, path) => files.find(file => file.path === path)?.content
+
+test('a real project: composed layouts, per-entity routes, the stylesheet, webhook extensions and /api/<path>, published and fresh', { timeout: 180_000 }, async () => {
+  const { root, cleanup } = project()
+  try {
+    const config = projectHostConfig({ projectRoot: root })
+    const generated = await prepareHost(config, { mode: 'production' })
+    const app = generated.files.filter(file => file.path.startsWith('src/app/'))
+    const routes = new Set(app.map(file => file.path.slice('src/app/'.length)))
+
+    // Composed layouts and the stylesheet
+    assert.equal(
+      read(root, 'src/app/layout.tsx'),
+      [
+        '// Generated by NextSpark from @/templates/layout. Do not edit: regenerated on every build.',
+        'import "@/styles/globals.css"',
+        'import NextSparkTemplate from "@/templates/layout"',
+        'import { withRootLayout } from "@nextsparkjs/core/routes/_internal/root-layout"',
+        'export default withRootLayout(NextSparkTemplate)',
+        'export { metadata } from "@nextsparkjs/core/routes/layout"',
+        '',
+      ].join('\n')
+    )
+    assert.match(read(root, 'src/app/(public)/layout.tsx'), /export default withPublicMessages\(NextSparkTemplate\)/)
+    // Its metadata comes from the composition module, never from core's layout (whose default layout's client
+    // components would then ship on every public route, though the override renders none of them)
+    assert.match(read(root, 'src/app/(public)/layout.tsx'), /export \{ metadata \} from "@nextsparkjs\/core\/routes\/_internal\/public-layout"/)
+    assert.doesNotMatch(read(root, 'src/app/(public)/layout.tsx'), /routes\/\(public\)\/layout/)
+    assert.equal(at(app, 'src/app/(auth)/layout.tsx').includes('withAuthMessages'), false, 'no override: core\'s own layout, as it is')
+
+    // One concrete route per entity; the project's task template is composed into the list page
+    assert.match(read(root, 'src/app/dashboard/(main)/tasks/page.tsx'), /export default createEntityListRoute\(taskEntityConfig, NextSparkTemplate\)/)
+    assert.match(read(root, 'src/app/dashboard/(main)/posts/[id]/page.tsx'), /export default createEntityDetailRoute\(postsEntityConfig, \[\]\)/)
+    assert.equal([...routes].some(route => route.startsWith('dashboard/(main)/[entity]/')), false, 'no runtime dashboard entity route (the /api/v1/[entity] API is core\'s)')
+    assert.equal(routes.has('(public)/[...slug]/page.tsx'), false, 'no runtime public catch-all')
+    // Public: the item route under the basePath takes the project template, the archive is generated
+    assert.match(read(root, 'src/app/(public)/blog/[...slug]/page.tsx'), /export default createPublicItemRoute\(postsEntityConfig, NextSparkTemplate\)/)
+    assert.equal(routes.has('(public)/blog/[slug]/page.tsx'), false, 'the template is absorbed by the item route')
+    assert.ok(routes.has('(public)/blog/page.tsx'))
+
+    // API: the project's api/ at /api/<path>, no dispatchers, webhook extensions composed
+    assert.ok(routes.has('api/ai/usage/route.ts'))
+    assert.equal([...routes].some(route => /^api\/v1\/(theme|plugin)\//.test(route)), false, 'no runtime API dispatcher')
+    assert.match(read(root, 'src/app/api/v1/billing/webhooks/stripe/route.ts'), /export const POST = createStripeWebhookRoute\(stripeWebhookExtensions\)/)
+    assert.match(read(root, 'src/app/api/v1/billing/webhooks/polar/route.ts'), /export \{ POST \} from "@nextsparkjs\/core\/routes\/api\/v1\/billing\/webhooks\/polar\/route"/, 'no polar setting: core\'s route')
+
+    // Cache Components off: no variant is used
+    assert.match(read(root, 'src/app/(auth)/login/page.tsx'), /routes\/\(auth\)\/login\/page"/)
+
+    // What was written is what --check expects, and the composed files passed the grammar gate
+    assert.deepEqual(await checkHost(config), { ok: true, problems: [] })
+    assert.ok(generated.files.filter(file => file.grammar === 'composed-facade').length >= 15, 'entity, layout, item and webhook routes')
+  } finally {
+    cleanup()
+  }
+})
+
+test('with cacheComponents on, core\'s Cache Components variants replace the routes Next.js rejects there', async () => {
+  const { root, cleanup } = project({ 'next.config.mjs': 'export default { cacheComponents: true }\n' })
+  try {
+    const { appFiles } = await renderHostFiles(projectHostConfig({ projectRoot: root }))
+    const content = path => appFiles.find(file => file.path === `src/app/${path}`).content
+    for (const route of ['(auth)/login/page.cc', '(auth)/signup/page.cc', '(public)/docs/[section]/[page]/page.cc', 'superadmin/docs/[section]/[page]/page.cc']) {
+      assert.match(content(`${route.replace(/\.cc$/, '')}.tsx`), new RegExp(`routes/${route.replace(/[[\]().]/g, '\\$&')}"`), route)
+    }
+    // The root layout is core's PPR one, composed with the PPR wrapper; public item pages carry no revalidate
+    assert.match(content('layout.tsx'), /from "@nextsparkjs\/core\/routes\/_internal\/root-layout\.ppr"/)
+    assert.match(content('(public)/layout.tsx'), /export \{ metadata \} from "@nextsparkjs\/core\/routes\/_internal\/public-layout\.cc"/)
+    assert.doesNotMatch(content('(public)/layout.tsx'), /routes\/\(public\)\/layout/)
+    assert.doesNotMatch(content('(public)/blog/[...slug]/page.tsx'), /revalidate/)
+    for (const file of appFiles) assert.doesNotMatch(file.content, /export const (dynamic|dynamicParams) =/, file.path)
+  } finally {
+    cleanup()
+  }
+})
+
+test('a project that puts a route in a namespace it does not own, or a webhook module that is not there, cannot be generated', async () => {
+  const { root, cleanup } = project({
+    'api/v1/mine/route.ts': ROUTE,
+    'api/plugins/x/route.ts': ROUTE,
+    'nextspark.config.ts': "export default { billing: { webhookExtensions: { stripe: './lib/billing/nowhere' } } }\n",
+  })
+  try {
+    await assert.rejects(renderHostFiles(projectHostConfig({ projectRoot: root })), error => {
+      assert.ok(error instanceof PrepareError)
+      assert.deepEqual(error.diagnostics.map(d => d.code).sort(), ['NS_HOST_API_NAMESPACE', 'NS_HOST_API_NAMESPACE', 'NS_HOST_WEBHOOK_EXTENSIONS_MISSING'])
+      return true
+    })
+  } finally {
+    cleanup()
+  }
+})
+
+test('an entity config the host cannot read as literals stops generation with the entity and the fix named', async () => {
+  const { root, cleanup } = project({ 'entities/posts/posts.config.ts': POSTS.replace("basePath: '/blog'", 'basePath: BLOG_PATH') })
+  try {
+    await assert.rejects(renderHostFiles(projectHostConfig({ projectRoot: root })), error => {
+      assert.ok(error instanceof PrepareError)
+      assert.match(error.message, /\[NS_HOST_ENTITY_CONFIG_NOT_STATIC\] entities\/posts \(postsEntityConfig\): `access\.basePath` is not a literal/)
+      return true
+    })
+  } finally {
+    cleanup()
+  }
+})
+
+const GROUPS = {
+  'layout.tsx': ['withRootLayout', 'root-layout'],
+  '(auth)/layout.tsx': ['withAuthMessages', 'auth-layout'],
+  '(public)/layout.tsx': ['withPublicMessages', 'public-layout'],
+  'superadmin/layout.tsx': ['withSuperadminGuard', 'superadmin-layout'],
+  'devtools/layout.tsx': ['withDevtoolsGuard', 'devtools-layout'],
+}
+
+test('every group layout override is composed with core\'s wrapper; the role-guarded groups only through the guard wrappers', async () => {
+  const { root, cleanup } = project(Object.fromEntries(Object.keys(GROUPS).map(target => [`templates/${target}`, LAYOUT])))
+  try {
+    const { appFiles } = await renderHostFiles(projectHostConfig({ projectRoot: root }))
+    for (const [target, [wrapper, module]] of Object.entries(GROUPS)) {
+      const content = at(appFiles, `src/app/${target}`)
+      assert.match(content, new RegExp(`import \\{ ${wrapper} \\} from "@nextsparkjs/core/routes/_internal/${module}"`), target)
+      assert.match(content, new RegExp(`export default ${wrapper}\\(NextSparkTemplate\\)`), target)
+      if (wrapper.endsWith('Guard')) assert.equal(content.includes('Messages(NextSparkTemplate)'), false, `${target}: a guarded group is never wrapped in messages alone`)
+    }
+    assert.equal(/withSuperadminMessages|withDevtoolsMessages/.test(appFiles.map(file => file.content).join('\n')), false)
+  } finally {
+    cleanup()
+  }
+})
+
+test('a project layout over a fully protected core layout (the dashboard\'s) is refused, and a protected route is never silently replaced', async () => {
+  const { root, cleanup } = project({ 'templates/dashboard/layout.tsx': LAYOUT })
+  try {
+    await assert.rejects(renderHostFiles(projectHostConfig({ projectRoot: root })), error => {
+      assert.ok(error instanceof PrepareError)
+      assert.deepEqual(error.diagnostics.map(d => d.code), ['NS_HOST_PROTECTED_ROUTE'])
+      assert.match(error.message, /dashboard\/layout\.tsx/)
+      return true
+    })
+  } finally {
+    cleanup()
+  }
+})
+
+// ---------------------------------------------------------------------------
+// Cache Components mode (#203 stage 4b on stage 4's guards, namespaces and per-entity routes)
+// ---------------------------------------------------------------------------
+
+const CC_CONFIG = { 'next.config.mjs': 'export default { cacheComponents: true }\n' }
+const CC_GROUPS = {
+  '(auth)/layout.tsx': ['withAuthMessages', 'auth-layout.cc'],
+  '(public)/layout.tsx': ['withPublicMessages', 'public-layout.cc'],
+  'superadmin/layout.tsx': ['withSuperadminGuard', 'superadmin-layout.cc'],
+  'devtools/layout.tsx': ['withDevtoolsGuard', 'devtools-layout.cc'],
+}
+
+async function ccFiles(extra = {}) {
+  const { root, cleanup } = project({ ...CC_CONFIG, ...extra })
+  const { appFiles } = await renderHostFiles(projectHostConfig({ projectRoot: root })).finally(cleanup)
+  return appFiles
+}
+
+test('cacheComponents: a project override of every group layout is composed with the Cache Components wrapper, the guarded groups through the guard wrappers only', async () => {
+  const appFiles = await ccFiles(Object.fromEntries(Object.keys(CC_GROUPS).map(target => [`templates/${target}`, LAYOUT])))
+  for (const [target, [wrapper, module]] of Object.entries(CC_GROUPS)) {
+    const content = at(appFiles, `src/app/${target}`)
+    assert.match(content, new RegExp(`import \\{ ${wrapper} \\} from "@nextsparkjs/core/routes/_internal/${module.replace('.', '\\.')}"`), target)
+    assert.match(content, new RegExp(`export default ${wrapper}\\(NextSparkTemplate\\)`), target)
+  }
+  // The messages-only wrappers of the guarded groups are never written, and the ISR modules are not mixed in
+  assert.equal(/withSuperadminMessages|withDevtoolsMessages/.test(appFiles.map(file => file.content).join('\n')), false)
+  assert.equal(/_internal\/(auth|public|superadmin|devtools)-layout"/.test(appFiles.map(file => file.content).join('\n')), false)
+})
+
+test('cacheComponents: core\'s own guarded layouts (no override) are the Cache Components layouts, whose default layout holds the role guard', async () => {
+  const appFiles = await ccFiles()
+  assert.match(at(appFiles, 'src/app/superadmin/layout.tsx'), /routes\/superadmin\/layout\.cc"/)
+  assert.match(at(appFiles, 'src/app/devtools/layout.tsx'), /routes\/devtools\/layout\.cc"/)
+  assert.match(at(appFiles, 'src/app/dashboard/layout.tsx'), /routes\/dashboard\/layout\.cc"/)
+})
+
+test('cacheComponents: a project layout over the dashboard\'s fully protected layout is still refused', async () => {
+  const { root, cleanup } = project({ ...CC_CONFIG, 'templates/dashboard/layout.tsx': LAYOUT })
+  try {
+    await assert.rejects(renderHostFiles(projectHostConfig({ projectRoot: root })), error => {
+      assert.ok(error instanceof PrepareError)
+      assert.deepEqual(error.diagnostics.map(d => d.code), ['NS_HOST_PROTECTED_ROUTE'])
+      return true
+    })
+  } finally {
+    cleanup()
+  }
+})
+
+test('cacheComponents: per-entity routes are generated as in ISR, the public item pages import the cached source, and the API namespaces are enforced', async () => {
+  const cc = await ccFiles()
+  const isr = await (async () => {
+    const { root, cleanup } = project()
+    return (await renderHostFiles(projectHostConfig({ projectRoot: root })).finally(cleanup)).appFiles
+  })()
+  const targets = files => files.map(file => file.path).filter(path => /\/(dashboard\/\(main\)\/(tasks|posts)|\(public\)\/blog)\//.test(path) || /\(public\)\/blog\/page\.tsx$/.test(path)).sort()
+  assert.deepEqual(targets(cc), targets(isr), 'the same entity routes in both modes')
+  assert.ok(targets(cc).length >= 12)
+  const item = at(cc, 'src/app/(public)/blog/[...slug]/page.tsx')
+  assert.match(item, /from "@nextsparkjs\/core\/routes\/_internal\/public-item-route\.cc"/)
+  assert.doesNotMatch(item, /revalidate/)
+  assert.match(at(isr, 'src/app/(public)/blog/[...slug]/page.tsx'), /_internal\/public-item-route"/)
+  // Everything below /api/ratified namespaces: the project's api/ai/usage is /api/ai/usage in both modes
+  assert.ok(at(cc, 'src/app/api/ai/usage/route.ts'))
+  const { root, cleanup } = project({ ...CC_CONFIG, 'api/v1/x/route.ts': ROUTE })
+  try {
+    await assert.rejects(renderHostFiles(projectHostConfig({ projectRoot: root })), error => error.diagnostics.some(d => d.code === 'NS_HOST_API_NAMESPACE'))
+  } finally {
+    cleanup()
+  }
+})