@shanyucoder/flowgrid 0.1.0

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

@@ -0,0 +1,47 @@
+import Handlebars from 'handlebars'
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..')
+const templatesDir = path.join(rootDir, 'templates')
+const partialsDir = path.join(templatesDir, 'partials')
+
+let registered = false
+
+async function registerPartials() {
+  if (registered) return
+  registered = true
+
+  Handlebars.registerHelper('eq', (a, b) => a === b)
+  Handlebars.registerHelper('json', (value) => JSON.stringify(value, null, 2))
+
+  try {
+    const { readdir } = await import('node:fs/promises')
+    const entries = await readdir(partialsDir)
+    for (const file of entries) {
+      if (!file.endsWith('.hbs')) continue
+      const name = file.replace(/\.hbs$/, '')
+      const source = await readFile(path.join(partialsDir, file), 'utf8')
+      Handlebars.registerPartial(name, Handlebars.compile(source))
+    }
+  } catch {
+    // optional partials
+  }
+}
+
+/**
+ * @param {string} templateRel e.g. list/page.tsx.hbs
+ * @param {Record<string, unknown>} context
+ */
+export async function renderTemplate(templateRel, context) {
+  await registerPartials()
+  const templatePath = path.join(templatesDir, templateRel)
+  const source = await readFile(templatePath, 'utf8')
+  const template = Handlebars.compile(source, { noEscape: true })
+  return `${template(context).trim()}\n`
+}
+
+export function getTemplatesRoot() {
+  return templatesDir
+}

package/adapters/nextjs/codegen/runners/lib/resolve-hub-id.mjs

@@ -0,0 +1,288 @@
+/**
+ * Resolve short hub IDs → filesystem paths (docs hub + tests hub).
+ * IDs: W-* | API-* | UI-* | CMP-* | CTR-* | TC-* | SC-* | suite id (smoke, …)
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import path from 'node:path'
+
+function loadJson(file) {
+  if (!existsSync(file)) return null
+  return JSON.parse(readFileSync(file, 'utf8'))
+}
+
+function deepMerge(base, over) {
+  if (!over || typeof over !== 'object') return base
+  const out = { ...base }
+  for (const [k, v] of Object.entries(over)) {
+    if (v && typeof v === 'object' && !Array.isArray(v) && base[k] && typeof base[k] === 'object') {
+      out[k] = deepMerge(base[k], v)
+    } else out[k] = v
+  }
+  return out
+}
+
+export function loadPlatformRepos(repoRoot) {
+  let doc = loadJson(path.join(repoRoot, 'platform-repos.json'))
+  if (!doc) throw new Error(`Missing platform-repos.json in ${repoRoot}`)
+  const local = loadJson(path.join(repoRoot, 'platform-repos.local.json'))
+  if (local) doc = deepMerge(doc, local)
+  return doc
+}
+
+export function resolveProjectRoot(repoRoot, projectId) {
+  const doc = loadPlatformRepos(repoRoot)
+  const proj = doc.projects?.[projectId]
+  if (!proj?.root) throw new Error(`Unknown project "${projectId}" in platform-repos.json`)
+  return path.resolve(repoRoot, proj.root)
+}
+
+export function loadDocsIndex(docsRoot) {
+  const file = path.join(docsRoot, 'registries', 'docs-index.json')
+  const idx = loadJson(file)
+  if (!idx) {
+    return buildDocsIndexFallback(docsRoot)
+  }
+  return idx
+}
+
+function buildDocsIndexFallback(docsRoot) {
+  const codeIds = {}
+  const modules = []
+  const surfacesDir = path.join(docsRoot, 'surfaces')
+
+  function scanSurfaces(dir) {
+    if (!existsSync(dir)) return
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory() && !entry.name.startsWith('.')) {
+        const fullPath = path.join(dir, entry.name)
+        if (entry.name.startsWith('CMP-')) {
+          const mod = { id: entry.name, slug: entry.name.toLowerCase(), codeIds: [] }
+          modules.push(mod)
+          const cmpChildren = readdirSync(fullPath, { withFileTypes: true })
+          for (const child of cmpChildren) {
+             if (child.isDirectory() && !child.name.startsWith('.')) {
+                const codeDir = path.join(fullPath, child.name, 'code')
+                if (existsSync(codeDir)) {
+                  for (const fnEntry of readdirSync(codeDir, { withFileTypes: true })) {
+                    if (fnEntry.isDirectory() && !fnEntry.name.startsWith('.')) {
+                      if (fnEntry.name.startsWith('W-') || fnEntry.name.startsWith('UI-') || fnEntry.name.startsWith('API-')) {
+                        mod.codeIds.push(fnEntry.name)
+                        codeIds[fnEntry.name] = path.relative(docsRoot, path.join(codeDir, fnEntry.name)).split(path.sep).join('/')
+                      }
+                    }
+                  }
+                }
+             }
+          }
+        } else if (entry.name.startsWith('W-') || entry.name.startsWith('UI-') || entry.name.startsWith('API-')) {
+          codeIds[entry.name] = path.relative(docsRoot, fullPath).split(path.sep).join('/')
+        }
+        scanSurfaces(fullPath)
+      }
+    }
+  }
+
+  scanSurfaces(surfacesDir)
+  return { version: 1, codeIds, modules }
+}
+
+export function loadTestsIndex(testsRoot) {
+  const file = path.join(testsRoot, 'registries', 'tests-index.json')
+  const idx = loadJson(file)
+  if (!idx) {
+    return buildTestsIndexFallback(testsRoot)
+  }
+  return idx
+}
+
+/** Scan cases/ + suites/ when index missing */
+function buildTestsIndexFallback(testsRoot) {
+  const codeIds = {}
+  const casesDir = path.join(testsRoot, 'cases')
+  const suites = {}
+  if (existsSync(casesDir)) {
+    for (const screen of readdirSync(casesDir, { withFileTypes: true })) {
+      if (!screen.isDirectory() || screen.name.startsWith('.')) continue
+      const screenPath = path.join(casesDir, screen.name)
+      codeIds[screen.name] = path.relative(testsRoot, screenPath).split(path.sep).join('/')
+      for (const f of readdirSync(screenPath)) {
+        if (/^TC-.*\.ya?ml$/i.test(f)) {
+          const id = f.replace(/\.ya?ml$/i, '')
+          codeIds[id] = path.relative(testsRoot, path.join(screenPath, f)).split(path.sep).join('/')
+        }
+      }
+    }
+  }
+  const suitesDir = path.join(testsRoot, 'suites')
+  if (existsSync(suitesDir)) {
+    for (const f of readdirSync(suitesDir)) {
+      if (!f.endsWith('.yaml') && !f.endsWith('.yml')) continue
+      const raw = readFileSync(path.join(suitesDir, f), 'utf8')
+      const idMatch = raw.match(/^id:\s*(\S+)/m)
+      const sid = idMatch?.[1] || f.replace(/\.ya?ml$/i, '')
+      suites[sid] = path.relative(testsRoot, path.join(suitesDir, f)).split(path.sep).join('/')
+    }
+  }
+  return { version: 1, codeIds, suites, scenarios: {} }
+}
+
+function absUnder(root, rel) {
+  if (!rel) return null
+  const abs = path.resolve(root, rel)
+  if (!existsSync(abs)) return null
+  return abs
+}
+
+/** ir/design.yaml only. Missing file = incomplete split. */
+export function preferFeDesign(codeDir) {
+  if (!codeDir || !existsSync(codeDir)) return null
+  const design = path.join(codeDir, 'ir', 'design.yaml')
+  return existsSync(design) ? design : null
+}
+
+export function preferGenSpec(codeDir) {
+  return preferFeDesign(codeDir)
+}
+
+/**
+ * @param {string} repoRoot FE/BE code repo (usually portal)
+ * @param {string} id
+ * @param {'codegen'|'testcase'} mode
+ * @returns {{ kind: string, id: string, paths: string[], notes: string[] }}
+ */
+export function resolveHubId(repoRoot, id, mode = 'testcase') {
+  if (!id || typeof id !== 'string') throw new Error('Missing --id')
+  const notes = []
+  const docsRoot = process.env.FLOWGRID_DOCS_ROOT
+    ? path.resolve(process.env.FLOWGRID_DOCS_ROOT)
+    : (() => {
+        try { return resolveProjectRoot(repoRoot, 'docs') } catch {
+          return resolveProjectRoot(repoRoot, 'base-docs')
+        }
+      })()
+  let testsRoot
+  try {
+    testsRoot = process.env.FLOWGRID_TESTS_DOC
+      ? path.resolve(process.env.FLOWGRID_TESTS_DOC)
+      : (() => {
+          try { return resolveProjectRoot(repoRoot, 'tests') } catch {
+            return resolveProjectRoot(repoRoot, 'base-tests')
+          }
+        })()
+  } catch (error) {
+    if (mode === 'codegen') {
+      testsRoot = docsRoot // unused for pure codegen W-* paths
+    } else {
+      throw error
+    }
+  }
+  const docsIdx = loadDocsIndex(docsRoot)
+  const testsIdx = loadTestsIndex(testsRoot)
+
+  // Suite
+  if (testsIdx.suites?.[id]) {
+    const suitePath = absUnder(testsRoot, testsIdx.suites[id])
+    const raw = readFileSync(suitePath, 'utf8')
+    const caseIds = [...raw.matchAll(/^\s*-\s+(TC-[\w-]+)/gm)].map((m) => m[1])
+    const paths = []
+    for (const cid of caseIds) {
+      const rel = testsIdx.codeIds?.[cid]
+      const p = absUnder(testsRoot, rel)
+      if (p) paths.push(p)
+      else notes.push(`suite ${id}: missing case ${cid}`)
+    }
+    return { kind: 'suite', id, paths, notes, suitePath }
+  }
+
+  // TC-* file
+  if (/^TC-/i.test(id)) {
+    const rel = testsIdx.codeIds?.[id]
+    const p = absUnder(testsRoot, rel)
+    if (!p) throw new Error(`Unknown testcase id ${id} — update base-tests/registries/tests-index.json`)
+    return { kind: 'testcase', id, paths: [p], notes }
+  }
+
+  // Screen / API / UI code folder on docs
+  if (/^(W|API|UI)-/i.test(id) || /^[a-z]+-[a-z]+-\d{3}(-\d{2,3})+$/i.test(id)) {
+    if (mode === 'testcase') {
+      const screenRel = testsIdx.codeIds?.[id] || `cases/${id}`
+      const screenDir = absUnder(testsRoot, screenRel)
+      if (!screenDir) throw new Error(`No cases folder for ${id} under base-tests`)
+      const paths = readdirSync(screenDir)
+        .filter((f) => /^TC-.*\.ya?ml$/i.test(f))
+        .map((f) => path.join(screenDir, f))
+        .sort()
+      if (!paths.length) throw new Error(`No TC-*.yaml under ${screenDir}`)
+      return { kind: 'screen-cases', id, paths, notes }
+    }
+    // codegen
+    const rel = docsIdx.codeIds?.[id]
+    if (!rel) throw new Error(`Unknown code id ${id} in base-docs registries/docs-index.json`)
+    const codeDir = absUnder(docsRoot, rel)
+    const spec = preferFeDesign(codeDir)
+    if (!spec) {
+      throw new Error(
+        `Missing ir/design.yaml under ${rel}. Split must emit design (tech); ir/spec.yaml is prose only.`,
+      )
+    }
+    notes.push(`codegen input: ${path.relative(repoRoot, spec)}`)
+    return { kind: 'code', id, paths: [spec], notes, codeDir }
+  }
+
+  // Cluster, Module, or Submodule (e.g. CMP-ADM, CMP-ADM-001, CMP-ADM-001-A)
+  if (/^[A-Z]+-[A-Z]+(?:-\d{3})?(?:-[A-Z0-9]+)?$/i.test(id)) {
+    const matchedModules = (docsIdx.modules || []).filter(
+      (c) => c.id === id || c.id.startsWith(`${id}-`) || c.id.startsWith(id) || (c.slug && id.toLowerCase().includes(c.slug)),
+    )
+    if (!matchedModules.length) throw new Error(`Unknown cluster/module ${id}`)
+    const paths = []
+    if (mode === 'testcase') {
+      for (const mod of matchedModules) {
+        for (const cid of mod.codeIds || []) {
+          if (!/^(W|UI)-/i.test(cid)) continue
+          const sub = resolveHubId(repoRoot, cid, 'testcase')
+          paths.push(...sub.paths)
+          notes.push(...sub.notes)
+        }
+      }
+      return { kind: 'module-cases', id, paths, notes }
+    }
+    for (const mod of matchedModules) {
+      for (const cid of mod.codeIds || []) {
+        if (/^API-/i.test(cid)) {
+          notes.push(`skip API ${cid} for portal:gen (FE codegen); design lives in docs hub`)
+          continue
+        }
+        try {
+          const sub = resolveHubId(repoRoot, cid, 'codegen')
+          paths.push(...sub.paths)
+          notes.push(...sub.notes)
+        } catch (e) {
+          notes.push(String(e.message || e))
+        }
+      }
+    }
+    if (!paths.length) {
+      throw new Error(`Cluster/Module ${id}: no ir/design.yaml after /grill-dev`)
+    }
+    return { kind: 'module-code', id, paths, notes }
+  }
+
+  // SC-* scenario → cases listed in tests index
+  if (/^SC-/i.test(id)) {
+    const sc = testsIdx.scenarios?.[id]
+    if (!sc?.cases?.length) {
+      throw new Error(`Unknown scenario ${id} — add scenarios.${id}.cases in tests-index.json`)
+    }
+    const paths = []
+    for (const cid of sc.cases) {
+      const sub = resolveHubId(repoRoot, cid, 'testcase')
+      paths.push(...sub.paths)
+    }
+    return { kind: 'scenario', id, paths, notes }
+  }
+
+  throw new Error(
+    `Unrecognized id "${id}". Use W-|API-|UI-|TC-|SC-* or hierarchical ID (e.g. cmp-adm-001-01-01), or module ID (CMP-ADM-001), or suite id (smoke, regression-auth).`,
+  )
+}

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

@@ -0,0 +1,121 @@
+/**
+ * Parse #needs-component tags and map slots → components for page templates.
+ */
+
+/**
+ * @param {string} name
+ */
+export function normalizeComponentName(name) {
+  const trimmed = String(name).trim()
+  if (!trimmed) return ''
+  return trimmed.startsWith('Mo') ? trimmed : `Mo${trimmed}`
+}
+
+/**
+ * @param {string} entry e.g. MoXxx | cell-status:MoXxx | cell-status:MoXxx:label
+ */
+export function parseNeedsComponentEntry(entry) {
+  const parts = String(entry)
+    .split(/[:/]/)
+    .map((part) => part.trim())
+    .filter(Boolean)
+
+  if (parts.length >= 2) {
+    return {
+      slot: parts[0],
+      component: normalizeComponentName(parts[1]),
+      valueProp: parts[2] ?? 'value'
+    }
+  }
+
+  return {
+    slot: null,
+    component: normalizeComponentName(parts[0] ?? entry),
+    valueProp: 'value'
+  }
+}
+
+/**
+ * @param {string[]} customSlots
+ * @param {string[]} needsComponentTags raw tag values (without prefix)
+ * @param {Array<Record<string, unknown>>} columns
+ */
+export function buildSlotBindings(customSlots, needsComponentTags, columns) {
+  const columnByKey = Object.fromEntries(columns.map((col) => [col.key, col]))
+  /** @type {Map<string, { component: string, valueProp: string }>} */
+  const componentBySlot = new Map()
+  /** @type {Array<{ component: string, valueProp: string, slot: string | null }>} */
+  const unbound = []
+
+  for (const raw of needsComponentTags) {
+    const parsed = parseNeedsComponentEntry(raw)
+    if (parsed.slot) {
+      componentBySlot.set(parsed.slot, {
+        component: parsed.component,
+        valueProp: parsed.valueProp
+      })
+    } else {
+      unbound.push(parsed)
+    }
+  }
+
+  for (const col of columns) {
+    if (!col.component) continue
+    componentBySlot.set(`cell-${col.key}`, {
+      component: normalizeComponentName(col.component),
+      valueProp: col.componentProp ?? col.componentValueProp ?? 'value'
+    })
+  }
+
+  const slots = [...new Set(customSlots)]
+
+  if (unbound.length === 1 && slots.length === 1 && !componentBySlot.has(slots[0])) {
+    componentBySlot.set(slots[0], {
+      component: unbound[0].component,
+      valueProp: unbound[0].valueProp
+    })
+    unbound.length = 0
+  }
+
+  for (const item of unbound) {
+    for (const slot of slots) {
+      if (!slot.startsWith('cell-') || componentBySlot.has(slot)) continue
+      const columnKey = slot.slice(5)
+      const col = columnByKey[columnKey]
+      if (col?.render === 'custom') {
+        componentBySlot.set(slot, {
+          component: item.component,
+          valueProp: item.valueProp
+        })
+        break
+      }
+    }
+  }
+
+  return slots.map((slot) => {
+    const columnKey = slot.startsWith('cell-') ? slot.slice(5) : null
+    const col = columnKey ? columnByKey[columnKey] : null
+    const mapped = componentBySlot.get(slot)
+    const component = mapped?.component ?? (col?.component ? normalizeComponentName(col.component) : null)
+    const valueProp = mapped?.valueProp ?? col?.componentProp ?? col?.componentValueProp ?? 'value'
+
+    return {
+      slot,
+      columnKey,
+      component,
+      valueProp,
+      wired: Boolean(component)
+    }
+  })
+}
+
+/**
+ * @param {ReturnType<typeof buildSlotBindings>} slotBindings
+ */
+export function collectUniqueComponents(slotBindings) {
+  const names = new Set()
+  for (const binding of slotBindings) {
+    if (binding.component) names.add(binding.component)
+  }
+  return [...names]
+}

package/adapters/nextjs/codegen/runners/lib/web-paths.mjs

@@ -0,0 +1,64 @@
+/**
+ * Next.js app paths under src/ (portal-gen output root).
+ */
+
+import { feLayoutForProfile } from '../../../../shared/fe-layout-profiles.mjs'
+
+export const WEB_SRC = 'src'
+
+/** @param {string} routePath e.g. /hotels */
+/** @param {string} [profile] codegen.profile */
+export function routeToAppPagePath(routePath, profile) {
+  const layout = feLayoutForProfile(profile)
+  const trimmed = String(routePath ?? '')
+    .replace(/^\//, '')
+    .replace(/\/$/, '')
+
+  if (layout === 'root') {
+    return String(profile).trim() === 'not-found'
+      ? `${WEB_SRC}/app/not-found.tsx`
+      : `${WEB_SRC}/app/error.tsx`
+  }
+
+  const group = layout === 'auth' ? '(auth)' : layout === 'public' ? '(public)' : '(dashboard)'
+  if (!trimmed) return `${WEB_SRC}/app/${group}/page.tsx`
+  return `${WEB_SRC}/app/${group}/${trimmed}/page.tsx`
+}
+
+/** @param {string} file e.g. hotel.service.ts */
+export function webServicePath(file) {
+  return `${WEB_SRC}/services/${file}`
+}
+
+/** @param {string} file e.g. hotel/useHotelList.ts */
+export function webHookPath(file) {
+  return `${WEB_SRC}/hooks/${file}`
+}
+
+/** @param {string} file e.g. hotel.mock.ts */
+export function webMockPath(file) {
+  return `${WEB_SRC}/mocks/${file}`
+}
+
+/** @param {string} file e.g. hotel/schemas.ts */
+export function webValidationPath(file) {
+  return `${WEB_SRC}/validations/${file}`
+}
+
+/** @param {string} file e.g. hotel/HotelForm.tsx */
+export function webComponentPath(file) {
+  return `${WEB_SRC}/components/${file}`
+}
+
+/** @param {string} file e.g. useHotelStore.ts */
+export function webStorePath(file) {
+  return `${WEB_SRC}/stores/${file}`
+}
+
+/** @param {string} relativePath */
+export function isNextPagePath(relativePath) {
+  const normalized = relativePath.replace(/\\/g, '/')
+  return (
+    /\/app\/\((dashboard|auth|public)\)\//.test(normalized) && normalized.endsWith('/page.tsx')
+  ) || normalized.endsWith('/app/not-found.tsx') || normalized.endsWith('/app/error.tsx')
+}

package/adapters/nextjs/codegen/runners/lib/write-files.mjs

@@ -0,0 +1,106 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+/**
+ * @param {string} root workspace root
+ * @param {{ relativePath: string, content: string }[]} outputs
+ * @param {{ dryRun?: boolean, force?: boolean }} options
+ */
+export async function writeOutputs(root, outputs, options = {}) {
+  const written = []
+  const skipped = []
+
+  for (const { relativePath, content } of outputs) {
+    const absolutePath = path.join(root, relativePath)
+    const exists = await fileExists(absolutePath)
+
+    if (exists && !options.force) {
+      skipped.push({ relativePath, reason: 'exists (use --force)' })
+      continue
+    }
+
+    if (options.dryRun) {
+      written.push({ relativePath, dryRun: true })
+      continue
+    }
+
+    await mkdir(path.dirname(absolutePath), { recursive: true })
+    await writeFile(absolutePath, content, 'utf8')
+    written.push({ relativePath })
+  }
+
+  return { written, skipped }
+}
+
+async function fileExists(filePath) {
+  try {
+    await readFile(filePath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * @param {string} featureDir
+ * @param {Record<string, unknown>} manifest
+ * @param {string} handoffMarkdown
+ */
+export async function writeGeneratedMeta(featureDir, manifest, handoffMarkdown, options = {}) {
+  const generatedDir = path.join(featureDir, 'generated')
+  const manifestPath = path.join(generatedDir, 'codegen.manifest.json')
+  const handoffPath = path.join(generatedDir, 'HANDOFF.md')
+
+  if (options.dryRun) {
+    return { manifestPath, handoffPath, dryRun: true }
+  }
+
+  await mkdir(generatedDir, { recursive: true })
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
+  await writeFile(handoffPath, handoffMarkdown, 'utf8')
+  return { manifestPath, handoffPath }
+}
+
+export function renderHandoffMarkdown(ctx, written, skipped) {
+  const lines = [
+    `# HANDOFF — ${ctx.title}`,
+    '',
+    `Generated from \`${ctx.specFile}\` (profile: **${ctx.profile}**).`,
+    '',
+    '## Files',
+    '',
+    ...(written.length
+      ? written.map((f) => `- \`${f.relativePath}\`${f.dryRun ? ' (dry-run)' : ''}`)
+      : ['- _No files written._']),
+    '',
+    ...(skipped.length
+      ? ['## Skipped (already exist)', '', ...skipped.map((s) => `- \`${s.relativePath}\` — ${s.reason}`), '']
+      : [])
+  ]
+
+  if (ctx.handoffItems.length) {
+    lines.push('## Prototype next (/prototype)', '')
+    lines.push(
+      '_portal:gen does not emit component code for `#needs-component` / `#needs-ui` — implement molecules in /prototype, then re-run gen._',
+      ''
+    )
+    for (const item of ctx.handoffItems) {
+      lines.push(`- **${item.type}**${item.name ? ` (\`${item.name}\`)` : ''}: ${item.detail}`)
+    }
+    lines.push('')
+  } else {
+    lines.push('## Prototype next (/prototype)', '', '- _No missing components — review generated code and run lint/typecheck._', '')
+  }
+
+  lines.push(
+    '## Commands',
+    '',
+    '```bash',
+    'flowgrid render / docs hub docs:render   # after spec edits',
+    'flowgrid gen --spec ... --force  # re-generate after /prototype components',
+    '```',
+    '',
+  )
+
+  return lines.join('\n')
+}