@shanyucoder/flowgrid 0.1.0

package/adapters/nextjs/codegen/runners/lib/page-lifecycle.mjs

@@ -0,0 +1,258 @@
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+export const REGISTRY_REL = 'registries/page-lifecycle.registry.json'
+const DOC_REL = 'docs/operational/PAGE-LIFECYCLE.md'
+const STAGE_ORDER = ['design-spec', 'prototype', 'test', 'wire']
+
+/**
+ * src/app/(dashboard)/hotels/page.tsx → /hotels
+ * src/app/(dashboard)/hotels/page.tsx → /hotels
+ * @param {string} relativePagePath
+ */
+export function routePathFromPageFile(relativePagePath) {
+  const normalized = relativePagePath.replace(/\\/g, '/')
+
+  if (normalized === 'src/app/not-found.tsx') return '/404'
+  if (normalized === 'src/app/error.tsx') return '/error'
+
+  const grouped = normalized.match(/^src\/app\/\((?:dashboard|auth|public)\)\/(?:(.+)\/)?page\.tsx$/)
+  if (grouped) return grouped[1] ? `/${grouped[1]}` : '/'
+
+  return null
+}
+
+export function normalizeRoutePath(routePath) {
+  if (!routePath) return '/'
+  const trimmed = routePath.trim()
+  if (trimmed === '/') return '/'
+  return trimmed.startsWith('/') ? trimmed.replace(/\/$/, '') || '/' : `/${trimmed}`
+}
+
+/**
+ * @param {string} requested
+ * @param {string | undefined} existingStage
+ * @param {{ allowDowngrade?: boolean }} options
+ */
+export function resolveLifecycleStage(requested, existingStage, options = {}) {
+  if (!existingStage) return requested
+  if (options.allowDowngrade) return requested
+
+  const reqIdx = STAGE_ORDER.indexOf(requested)
+  const curIdx = STAGE_ORDER.indexOf(existingStage)
+  if (reqIdx === -1) return existingStage
+  if (curIdx === -1) return requested
+  return curIdx > reqIdx ? existingStage : requested
+}
+
+async function loadRegistry(root) {
+  const registryPath = path.join(root, REGISTRY_REL)
+  try {
+    return { data: JSON.parse(await readFile(registryPath, 'utf8')), registryPath }
+  } catch {
+    return { data: { routes: {} }, registryPath }
+  }
+}
+
+async function saveRegistry(root, data) {
+  const registryPath = path.join(root, REGISTRY_REL)
+  await mkdir(path.dirname(registryPath), { recursive: true })
+  await writeFile(registryPath, `${JSON.stringify(data, null, 2)}\n`, 'utf8')
+  await renderPageLifecycleDoc(root, data)
+  return registryPath
+}
+
+/**
+ * @param {string} root
+ * @param {{ routePath: string, specFile?: string, title?: string, stage?: string, note?: string, allowDowngrade?: boolean }} entry
+ */
+export async function upsertPageLifecycle(root, entry) {
+  const { data } = await loadRegistry(root)
+  const routePath = normalizeRoutePath(entry.routePath)
+  const existing = data.routes[routePath]
+  const stage = resolveLifecycleStage(entry.stage ?? 'prototype', existing?.stage, {
+    allowDowngrade: entry.allowDowngrade
+  })
+
+  data.routes[routePath] = {
+    stage,
+    spec:
+      !entry.specFile || entry.specFile === 'manual'
+        ? (existing?.spec ?? entry.specFile)
+        : entry.specFile.replace(/\\/g, '/'),
+    title: entry.title ?? existing?.title,
+    updatedAt: new Date().toISOString(),
+    note: entry.note ?? existing?.note
+  }
+
+  await saveRegistry(root, data)
+  return { registryPath: REGISTRY_REL, routePath, stage }
+}
+
+/**
+ * Hạ stage sau portal:remove — mặc định design-spec (chưa có prototype).
+ * @param {string} root
+ * @param {string} routePath
+ * @param {{ specFile?: string, note?: string }} meta
+ */
+export async function demotePageLifecycle(root, routePath, meta = {}) {
+  return upsertPageLifecycle(root, {
+    routePath,
+    specFile: meta.specFile ?? 'manual',
+    stage: 'design-spec',
+    allowDowngrade: true,
+    note: meta.note ?? 'Prototype code removed — chạy portal:gen để tạo lại.'
+  })
+}
+
+/**
+ * Đồng bộ registry từ mọi codegen.manifest.json + kiểm tra page còn trên disk.
+ * @param {string} root
+ */
+export async function syncPageLifecycleFromManifests(root) {
+  const { data } = await loadRegistry(root)
+  const manifests = await listManifestFiles(root)
+  const touched = new Set()
+
+  for (const manifestPath of manifests) {
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+    const pageEntry = manifest.files?.find((f) => f.layer === 'page')
+    if (!pageEntry?.path) continue
+
+    const routePath = routePathFromPageFile(pageEntry.path)
+    if (!routePath) continue
+
+    touched.add(routePath)
+    const pageExists = await fileExists(path.join(root, pageEntry.path))
+    const existing = data.routes[routePath]
+    const stage = pageExists
+      ? resolveLifecycleStage('prototype', existing?.stage)
+      : resolveLifecycleStage('design-spec', existing?.stage, { allowDowngrade: true })
+
+    data.routes[routePath] = {
+      stage,
+      spec: manifest.specFile?.replace(/\\/g, '/') ?? existing?.spec ?? 'unknown',
+      title: existing?.title,
+      updatedAt: new Date().toISOString(),
+      note: pageExists ? existing?.note : 'Page file missing — sync demoted to design-spec.'
+    }
+  }
+
+  for (const [routePath, entry] of Object.entries(data.routes)) {
+    if (touched.has(routePath)) continue
+    if (entry.stage !== 'prototype') continue
+
+    const specFileAbs = entry.spec ? path.join(root, entry.spec) : null
+    const specDir = specFileAbs ? path.dirname(specFileAbs) : null
+    const featureDir = specDir ? (path.basename(specDir) === 'ir' ? path.dirname(specDir) : specDir) : null
+    const manifestPath = featureDir ? path.join(featureDir, 'generated', 'codegen.manifest.json') : null
+    const manifest = manifestPath && (await fileExists(manifestPath))
+      ? JSON.parse(await readFile(manifestPath, 'utf8'))
+      : null
+    const pagePath = manifest?.files?.find((f) => f.layer === 'page')?.path
+    const pageExists = pagePath ? await fileExists(path.join(root, pagePath)) : false
+
+    if (!pageExists) {
+      data.routes[routePath] = {
+        ...entry,
+        stage: 'design-spec',
+        updatedAt: new Date().toISOString(),
+        note: 'Prototype page removed — sync demoted to design-spec.'
+      }
+    }
+  }
+
+  await saveRegistry(root, data)
+  return { updated: Object.keys(data.routes).length, manifests: manifests.length }
+}
+
+async function listManifestFiles(root) {
+  const files = []
+  const featuresDir = path.join(root, 'surfaces')
+
+  async function walk(dir) {
+    let entries = []
+    try {
+      entries = await readdir(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+
+    for (const entry of entries) {
+      const entryPath = path.join(dir, entry.name)
+      if (entry.isDirectory()) {
+        await walk(entryPath)
+        continue
+      }
+      if (entry.name === 'codegen.manifest.json') {
+        files.push(entryPath)
+      }
+    }
+  }
+
+  await walk(featuresDir)
+  return files.sort()
+}
+
+async function fileExists(filePath) {
+  try {
+    await readFile(filePath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {{ routes: Record<string, { stage: string, spec: string, title?: string, updatedAt: string, note?: string }> }} data
+ */
+export async function renderPageLifecycleDoc(root, data) {
+  const rows = Object.entries(data.routes)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([route, entry]) => {
+      const auth = entry.stage === 'wire' ? 'required' : 'bypass'
+      const note = entry.note ? ` ${entry.note}` : ''
+      return `| ${route} | ${entry.stage} | ${auth} | \`${entry.spec}\` | ${entry.title ?? '—'} | ${entry.updatedAt.slice(0, 10)} |${note ? '' : ''}`
+    })
+
+  const markdown = `# Page lifecycle registry
+
+Nguồn máy đọc: \`registries/page-lifecycle.registry.json\`.
+
+**Tự cập nhật:** \`portal:gen\` → \`prototype\`; \`portal:remove\` → \`design-spec\`; \`pnpm portal:lifecycle sync\` quét manifest + page trên disk.
+
+## Bước chính (không ghi sub-step)
+
+| Stage | Ý nghĩa | Auth trên dev |
+|-------|---------|---------------|
+| \`design-spec\` | Spec/testcase có; chưa có prototype code | bypass |
+| \`prototype\` | UI + mock API (\`portal:gen\`) | bypass |
+| \`test\` | E2E/unit pass (vẫn mock API) | bypass |
+| \`wire\` | Ghép API thật xong | **required** |
+
+**Quy tắc:** \`stage\` = bước cao nhất đã đạt. Sửa spec / re-grill không tự hạ stage. \`portal:remove\` hoặc \`lifecycle sync\` (page mất) hạ về \`design-spec\`.
+
+\`\`\`bash
+pnpm portal:lifecycle sync
+pnpm portal:lifecycle set /hotels test
+pnpm portal:remove --spec docs/features/.../feature.spec.yaml
+\`\`\`
+
+## Routes
+
+| Path | Stage | Auth | Spec | Title | Updated |
+|------|-------|------|------|-------|---------|
+${rows.length ? rows.join('\n') : '| _—_ | — | — | — | — | — |'}
+
+## Liên quan
+
+- Auth bypass: mọi stage **trừ** \`wire\` — \`src/middleware.ts\`
+- Xóa code: \`pnpm portal:remove --spec <file>\`
+- Session handoff: \`.harness/progress.md\`
+`
+
+  const docPath = path.join(root, DOC_REL)
+  await mkdir(path.dirname(docPath), { recursive: true })
+  await writeFile(docPath, markdown, 'utf8')
+}

package/adapters/nextjs/codegen/runners/lib/plan.mjs

@@ -0,0 +1,399 @@
+import {
+  createEndpoint,
+  listEndpoint,
+  pluralize,
+  resolveCodegenNamespace,
+  buildMockRowsFromSpec,
+  routeToPagePath,
+  toCamelCase,
+  toKebabCase,
+  toPascalCase,
+  zodFieldForColumn,
+  zodFieldForFormField
+} from './naming.mjs'
+import { applyDesignRegistry, validateSpecDesign, parseDesignTags } from './design-registry.mjs'
+import { resolveComponentFiles } from './component-resolve.mjs'
+import { buildSlotBindings, collectUniqueComponents } from './slots.mjs'
+import { resolveUiInventory } from '../../../../shared/fe-ui-inventory.mjs'
+import {
+  routeToAppPagePath,
+  webComponentPath,
+  webHookPath,
+  webMockPath,
+  webServicePath,
+  webStorePath,
+  webValidationPath
+} from './web-paths.mjs'
+import {
+  assertFeProfileMatchesRoute,
+  isErrorPageProfile,
+  isFormPageProfile,
+} from '../../../../shared/fe-layout-profiles.mjs'
+
+const TAG_PREFIX = {
+  needsComponent: '#needs-component:',
+  customSlot: '#custom-slot:',
+  manualComposable: '#manual-composable:',
+  skipCodegen: '#skip-codegen:',
+  wireOnly: '#wire-only:',
+  splitHook: '#split-hook:'
+}
+
+/** @param {string[]} tags */
+export function parseTags(tags = []) {
+  const parsed = {
+    needsComponents: [],
+    customSlots: [],
+    manualComposables: [],
+    skipCodegen: [],
+    wireOnly: [],
+    patterns: [],
+    splitHooks: [],
+    reuseApi: false,
+    raw: tags
+  }
+
+  for (const tag of tags) {
+    const text = String(tag).trim()
+    if (text.startsWith(TAG_PREFIX.needsComponent)) {
+      parsed.needsComponents.push(text.slice(TAG_PREFIX.needsComponent.length).trim())
+    } else if (text.startsWith(TAG_PREFIX.customSlot)) {
+      parsed.customSlots.push(text.slice(TAG_PREFIX.customSlot.length).trim())
+    } else if (text.startsWith(TAG_PREFIX.manualComposable)) {
+      parsed.manualComposables.push(text.slice(TAG_PREFIX.manualComposable.length).trim())
+    } else if (text.startsWith(TAG_PREFIX.skipCodegen)) {
+      parsed.skipCodegen.push(text.slice(TAG_PREFIX.skipCodegen.length).trim())
+    } else if (text.startsWith(TAG_PREFIX.wireOnly)) {
+      parsed.wireOnly.push(text.slice(TAG_PREFIX.wireOnly.length).trim())
+    } else if (text.startsWith(TAG_PREFIX.splitHook)) {
+      parsed.splitHooks.push(text.slice(TAG_PREFIX.splitHook.length).trim())
+    } else if (text.startsWith('#pattern:')) {
+      parsed.patterns.push(text.slice('#pattern:'.length).trim())
+    } else if (text === '#reuse-api') {
+      parsed.reuseApi = true
+    }
+  }
+
+  return parsed
+}
+
+/** Auto-add custom slot tags from columns with render: custom */
+function mergeCustomSlots(columns, parsedTags) {
+  const slots = new Set(parsedTags.customSlots)
+  for (const col of columns) {
+    if (col.render === 'custom') {
+      slots.add(`cell-${col.key}`)
+    }
+  }
+  return [...slots]
+}
+
+/**
+ * @param {import('yaml').Document.Parsed | Record<string, unknown>} spec
+ * @param {string} specFile
+ */
+export function buildCodegenContext(spec, specFile) {
+  const codegen = spec.codegen ?? {}
+  const namespaceKebab = resolveCodegenNamespace(codegen)
+  const entity = namespaceKebab
+  const module = codegen.module ?? pluralize(entity)
+  const profile = codegen.profile ?? 'list'
+  const entityPascal = toPascalCase(namespaceKebab)
+  const entityCamel = toCamelCase(namespaceKebab)
+  const moduleKebab = toKebabCase(module)
+
+  const inventory = resolveUiInventory(spec)
+  const route = spec.ui?.routes?.[0] ?? { path: `/${moduleKebab}`, pageTestId: `${moduleKebab}-page` }
+  assertFeProfileMatchesRoute(profile, route.path)
+  const listRoutePath = String(route.path ?? `/${moduleKebab}`).replace(/\/create$/, '') || `/${moduleKebab}`
+  const testIdModule = spec.ui?.testIds?.module ?? moduleKebab
+  const columns = inventory.columns
+  const filters = inventory.filters
+  const formFields = inventory.formFields
+  const commonValidationMessages = spec.ui?.validationMessages ?? {}
+
+  const parsedTags = parseTags(inventory.tags)
+  parsedTags.customSlots = mergeCustomSlots(columns, parsedTags)
+
+  const skip = new Set([
+    ...(codegen.skip ?? []),
+    ...parsedTags.skipCodegen.map((s) => s.toLowerCase())
+  ])
+
+  const listEp = listEndpoint(spec)
+  const createEp = createEndpoint(spec)
+  const exportEp =
+    spec.api?.endpoints?.find((e) => e.action === 'export') ??
+    spec.api?.endpoints?.find((e) => /export/i.test(e.path ?? ''))
+
+  const columnSchemas = columns.map((col) => ({
+    ...col,
+    zodField: zodFieldForColumn(col)
+  }))
+
+  const formFieldSchemas = formFields.map((field) => ({
+    ...field,
+    zodField: zodFieldForFormField(field, commonValidationMessages)
+  }))
+
+  const useCustomShell =
+    spec.ui?.composition?.pattern === 'custom' || spec.ui?.composition?.overrideCommonPattern === true
+
+  const embeddedBlocks = spec.ui?.embeddedBlocks ?? []
+  const toolbar = spec.ui?.toolbar ?? {}
+  const defaultPageSize = toolbar.defaultPageSize ?? 10
+  const pageSizeOptions = toolbar.pageSizeOptions ?? []
+  const hasPerPageToolbar = pageSizeOptions.length > 0
+  const perPageConfig = toolbar.perPage ?? {}
+  const manualComposables = parsedTags.manualComposables
+  const hasExportBlock = embeddedBlocks.some((block) => block.id === 'export-open-rate') ||
+    manualComposables.includes('exportOpenRateReport')
+  const hasLoginAs = manualComposables.includes('loginAsStoreManager')
+
+  const splitHooksSet = new Set(parsedTags.splitHooks)
+  if (columns.length > 8) splitHooksSet.add('columns')
+  if (filters.length > 3) splitHooksSet.add('filters')
+  if (hasExportBlock) splitHooksSet.add('export')
+  parsedTags.splitHooks = Array.from(splitHooksSet)
+
+  const mockRowsPage1 = buildMockRowsFromSpec(spec, spec.title ?? entityPascal)
+  const mockRowsPage2 = buildMockRowsFromSpec(spec, spec.title ?? entityPascal).map((row, index) => ({
+    ...row,
+    id: Number(row.id ?? index + 1) + 100,
+    name: `${row.name ?? 'Item'} (page 2)`
+  }))
+
+  const customSlots = mergeCustomSlots(columns, parsedTags)
+  const slotBindings = buildSlotBindings(customSlots, parsedTags.needsComponents, columns)
+
+  return {
+    spec,
+    specFile,
+    profile,
+    entity,
+    namespaceKebab,
+    module,
+    entityPascal,
+    entityCamel,
+    moduleKebab,
+    testIdModule,
+    title: spec.title ?? entityPascal,
+    summary: spec.summary ?? '',
+    route,
+    listRoutePath,
+    pagePath: routeToPagePath(route.path, profile),
+    columns,
+    columnSchemas,
+    filters,
+    formFields,
+    formFieldSchemas,
+    commonValidationMessages,
+    listEndpoint: listEp,
+    createEndpoint: createEp,
+    exportEndpoint: exportEp,
+    parsedTags,
+    skip,
+    useCustomShell,
+    embeddedBlocks,
+    toolbar,
+    defaultPageSize,
+    pageSizeOptions,
+    hasPerPageToolbar,
+    perPageConfig,
+    hasExportBlock,
+    hasLoginAs,
+    mockRowsPage1,
+    mockRowsPage2,
+    manualComposables,
+    customSlots,
+    slotBindings,
+    nav: inventory.nav,
+    designSections: inventory.sections,
+    designActions: inventory.actions,
+    componentFiles: {},
+    componentStubs: [],
+    handoffItems: buildHandoffItems(spec, parsedTags, useCustomShell, slotBindings, {})
+  }
+}
+
+/**
+ * Resolve component paths and refresh handoff + stub list.
+ * @param {ReturnType<typeof buildCodegenContext>} ctx
+ * @param {string} root
+ */
+export async function enrichCodegenContext(ctx, root) {
+  const components = collectUniqueComponents(ctx.slotBindings)
+  const componentFiles = await resolveComponentFiles(root, components)
+
+  ctx.slotBindings = ctx.slotBindings.map((binding) => {
+    if (!binding.component) return binding
+    const exists = Boolean(componentFiles[binding.component]?.exists)
+    return {
+      ...binding,
+      intendedComponent: binding.component,
+      wired: exists
+    }
+  })
+
+  ctx.componentFiles = componentFiles
+  ctx.componentStubs = []
+  ctx.handoffItems = buildHandoffItems(
+    ctx.spec,
+    ctx.parsedTags,
+    ctx.useCustomShell,
+    ctx.slotBindings,
+    componentFiles
+  )
+
+  return ctx
+}
+
+function buildHandoffItems(spec, parsedTags, useCustomShell, slotBindings, componentFiles) {
+  const items = []
+  const designTags = parseDesignTags(spec.tags ?? [])
+
+  if (useCustomShell) {
+    items.push({
+      type: 'override-shell',
+      detail: 'ui.composition.overrideCommonPattern or pattern: custom — implement organism shell in /prototype.'
+    })
+  } else if (spec.tags && spec.tags.some(t => t.startsWith('#shell:'))) {
+    const shellTag = spec.tags.find(t => t.startsWith('#shell:')).split(':')[1].trim()
+    // If the shell is not custom, but it's unknown, it will be handled as a missing shell by the template.
+    // For now we just push a custom slot so developers know.
+    if (!useCustomShell) {
+      items.push({
+        type: 'custom-slot',
+        name: `shell-${shellTag}`,
+        detail: `Unknown shell ${shellTag} — please implement manually or provide a valid shell template.`
+      })
+    }
+  }
+
+  for (const binding of slotBindings) {
+    if (binding.component) {
+      const file = componentFiles[binding.component]
+      if (!file?.exists) {
+        items.push({
+          type: 'needs-component',
+          name: binding.component,
+          detail:
+            `Slot #${binding.slot} — implement \`${binding.component}\` in /prototype (spec tag already names it). ` +
+            'Re-run flowgrid gen after the file exists. Common widget → update registry per DESIGN-REGISTRY-PROMOTION.md.'
+        })
+      }
+      continue
+    }
+
+    items.push({
+      type: 'custom-slot',
+      name: binding.slot,
+      detail: `Add #needs-component: ${binding.slot}:MoYourComponent:prop in spec (/grill-with-docs), implement in /prototype, then re-run flowgrid gen.`
+    })
+  }
+
+  for (const widget of designTags.needsUi) {
+    items.push({
+      type: 'needs-ui',
+      name: widget,
+      detail:
+        `Registry widget \`${widget}\` is planned — implement molecule in /prototype, promote registry if reusable, then re-run flowgrid gen.`
+    })
+  }
+
+  for (const fn of parsedTags.manualComposables) {
+    items.push({ type: 'manual-composable', name: fn, detail: `Implement composable function: ${fn}` })
+  }
+
+  for (const topic of parsedTags.wireOnly) {
+    items.push({ type: 'wire-only', name: topic, detail: `Defer until /wire: ${topic}` })
+  }
+
+  for (const q of spec.openQuestions ?? []) {
+    const detail =
+      typeof q === 'string'
+        ? q
+        : q?.question ?? q?.id ?? JSON.stringify(q)
+    items.push({ type: 'open-question', detail: String(detail) })
+  }
+
+  items.push({
+    type: 'contract-gen',
+    detail:
+      'Run `flowgrid contract-gen --spec <ir/design.yaml>` before flowgrid gen if @portal/models entity package is missing.'
+  })
+
+  return items
+}
+
+/**
+ * @param {ReturnType<typeof buildCodegenContext>} ctx
+ */
+export function buildFilePlan(ctx) {
+  const { entity, entityPascal, profile, skip } = ctx
+  const files = []
+
+  const add = (layer, relativePath, template) => {
+    if (skip.has(layer)) return
+    if (layer === 'models') return
+    files.push({ layer, relativePath, template })
+  }
+
+  if (profile === 'list') {
+    const listTemplate =
+      ctx.listPageTemplate ??
+      (ctx.useCustomShell ? 'list/page.custom.tsx.hbs' : 'list/page.tsx.hbs')
+
+    add('service', webServicePath(`${entity}.service.ts`), 'list/service.ts.hbs')
+    add('hook', webHookPath(`${entity}/use${entityPascal}Columns.ts`), 'list/useListColumns.ts.hbs')
+    add('hook', webHookPath(`${entity}/use${entityPascal}Filters.ts`), 'list/useListFilters.ts.hbs')
+    if (ctx.hasExportBlock) {
+      add('hook', webHookPath(`${entity}/use${entityPascal}Export.ts`), 'list/useListExport.ts.hbs')
+    }
+    add('hook', webHookPath(`${entity}/use${entityPascal}List.ts`), 'list/useList.ts.hbs')
+    add('page', ctx.pagePath ?? routeToAppPagePath(ctx.route.path, ctx.profile), listTemplate)
+    add('mock', webMockPath(`${entity}.mock.ts`), 'list/mock.ts.hbs')
+  }
+
+  if (isFormPageProfile(profile) || ctx.formFields?.length > 0) {
+    add('service', webServicePath(`${entity}Form.service.ts`), 'create/service.ts.hbs')
+    add('hook', webHookPath(`${entity}/use${entityPascal}Form.ts`), 'create/useForm.ts.hbs')
+    add('validation', webValidationPath(`${entity}/schemas.ts`), 'create/validation.ts.hbs')
+    add('component', webComponentPath(`${entity}/${entityPascal}Form.tsx`), 'create/form.tsx.hbs')
+  }
+
+  if (isFormPageProfile(profile) || isErrorPageProfile(profile)) {
+    add('page', ctx.pagePath ?? routeToAppPagePath(ctx.route.path, ctx.profile), 'create/page.tsx.hbs')
+    if (isFormPageProfile(profile)) {
+      add('mock', webMockPath(`${entity}.mock.ts`), 'create/mock.ts.hbs')
+    }
+  }
+
+  const hasStoreTag = ctx.spec.tags && ctx.spec.tags.some(t => t.trim() === '#use-store')
+  if (hasStoreTag) {
+    add('store', webStorePath(`use${entityPascal}Store.ts`), 'store/store.ts.hbs')
+  }
+
+  return files
+}
+
+/**
+ * Apply portal design registry and optional validation.
+ * @param {ReturnType<typeof buildCodegenContext>} ctx
+ * @param {Record<string, unknown>} registry
+ * @param {{ validate?: boolean }} options
+ */
+export function applyRegistryToContext(ctx, registry, options = {}) {
+  applyDesignRegistry(ctx, registry)
+
+  if (options.validate) {
+    const { errors, warnings } = validateSpecDesign(ctx, registry, { strict: false })
+    ctx.designValidation = { errors, warnings }
+    if (errors.length > 0) {
+      const message = errors.map((e) => `  - ${e}`).join('\n')
+      throw new Error(`portal-gen design registry validation failed:\n${message}`)
+    }
+  }
+
+  return ctx
+}

package/adapters/nextjs/codegen/runners/lib/read-spec.mjs

@@ -0,0 +1,7 @@
+export {
+  resolveFeatureDir,
+  readSpecFile,
+  readFeIrFile,
+  resolveFeIrPath,
+  requireDesignIrPath,
+} from '../../../../shared/read-fe-ir.mjs'