@shanyucoder/flowgrid 0.1.0

package/adapters/nuxt4/codegen/runners/generate.mjs

@@ -0,0 +1,236 @@
+import { spawnSync } from 'node:child_process'
+import { readdir, stat } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { buildCodegenContext, buildFilePlan, enrichCodegenContext, applyRegistryToContext } from './lib/plan.mjs'
+import { loadDesignRegistry } from './lib/design-registry.mjs'
+import { upsertPageLifecycle, syncPageLifecycleFromManifests } from './lib/page-lifecycle.mjs'
+import { readFeIrFile, requireDesignIrPath } from './lib/read-spec.mjs'
+import { resolveHubId } from './lib/resolve-hub-id.mjs'
+import { renderTemplate } from './lib/render.mjs'
+import { renderHandoffMarkdown, writeGeneratedMeta, writeOutputs } from './lib/write-files.mjs'
+import { resolveProjectRoot } from './lib/resolve-hub-id.mjs'
+import { isSurfaceCommonPath } from '../../../shared/surface-common.mjs'
+import { mergeI18nFlat } from '../../../shared/i18n-merge.mjs'
+
+const root = path.resolve(process.env.FLOWGRID_PROJECT_ROOT || process.env.FLOWGRID_PROJECT_ROOT || process.cwd())
+const yamlRootFlag = process.argv.includes('--yaml-root')
+  ? process.argv[process.argv.indexOf('--yaml-root') + 1]
+  : null
+function resolveDocsSurfacesRoot() {
+  const env = process.env.FLOWGRID_DOCS_ROOT
+  if (env) return path.join(path.resolve(env), 'surfaces')
+  if (process.env.FLOWGRID_YAML_ROOT) return path.resolve(process.env.FLOWGRID_YAML_ROOT)
+  try {
+    return path.join(resolveProjectRoot(root, 'docs'), 'surfaces')
+  } catch {
+    try {
+      return path.join(resolveProjectRoot(root, 'base-docs'), 'surfaces')
+    } catch {
+      throw new Error(
+        'Set FLOWGRID_DOCS_ROOT or pass --yaml-root; no sibling docs hub is assumed',
+      )
+    }
+  }
+}
+const IR_SPEC_GLOB_ROOT = path.resolve(yamlRootFlag ?? resolveDocsSurfacesRoot())
+
+function parseArgs(argv) {
+  const options = { dryRun: false, force: false, spec: null, all: false, id: null }
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--dry-run' || arg === '--dry') options.dryRun = true
+    else if (arg === '--force') options.force = true
+    else if (arg === '--all') options.all = true
+    else if (arg === '--spec') options.spec = argv[++i]
+    else if (arg === '--id') options.id = argv[++i]
+    else if (arg === '--yaml-root') i++
+    else if (!arg.startsWith('-') && !options.spec && !options.id) options.spec = arg
+  }
+
+  return options
+}
+
+async function listIrDesignFiles(dir) {
+  const files = []
+  let entries = []
+  try {
+    entries = await readdir(dir, { withFileTypes: true })
+  } catch {
+    return files
+  }
+
+  for (const entry of entries) {
+    const entryPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (entry.name === 'common' && isSurfaceCommonPath(entryPath)) continue
+      files.push(...(await listIrDesignFiles(entryPath)))
+      continue
+    }
+    if (entry.isFile() && entry.name === 'design.yaml' && entryPath.includes(`${path.sep}ir${path.sep}`)) {
+      if (isSurfaceCommonPath(entryPath)) continue
+      files.push(entryPath)
+    }
+  }
+
+  return files.sort()
+}
+
+async function resolveSpecPaths(options) {
+  if (options.id) {
+    const resolved = resolveHubId(root, options.id, 'codegen')
+    for (const n of resolved.notes) console.warn(`  note: ${n}`)
+    if (!resolved.paths.length) {
+      throw new Error(`--id ${options.id}: no ir/design.yaml under docs hub`)
+    }
+    console.log(`portal-gen: --id ${options.id} → ${resolved.paths.length} spec(s) (${resolved.kind})`)
+    return resolved.paths
+  }
+  if (options.spec) {
+    const specStat = await stat(path.resolve(options.spec)).catch(() => null)
+    if (specStat?.isDirectory()) {
+      const discovered = await listIrDesignFiles(path.resolve(options.spec))
+      if (!discovered.length) {
+        throw new Error(`--spec ${options.spec}: directory has no ir/design.yaml`)
+      }
+      return discovered
+    }
+    return [requireDesignIrPath(path.resolve(options.spec))]
+  }
+  const discovered = await listIrDesignFiles(IR_SPEC_GLOB_ROOT)
+  if (!discovered.length) {
+    throw new Error(
+      'No ir/design.yaml. Prefer: flowgrid gen --id … or --spec <ir/design.yaml> after pnpm spec:split.',
+    )
+  }
+  return discovered
+}
+
+async function generateOne(options, registry, specPath) {
+  const { spec, specFile, featureDir } = await readFeIrFile(specPath)
+  let ctx = buildCodegenContext(spec, specFile)
+  ctx = applyRegistryToContext(ctx, registry, { validate: true })
+  ctx = await enrichCodegenContext(ctx, root)
+  const plan = buildFilePlan(ctx)
+
+  const outputs = []
+  for (const file of plan) {
+    const templateContext =
+      file.layer === 'component'
+        ? { ...ctx, moName: file.moName, componentName: file.moName }
+        : ctx
+    const content = await renderTemplate(file.template, templateContext)
+    outputs.push({ layer: file.layer, relativePath: file.relativePath, content })
+  }
+
+  const { written, skipped } = await writeOutputs(root, outputs, {
+    dryRun: options.dryRun,
+    force: options.force
+  })
+
+  const manifest = {
+    generatedAt: new Date().toISOString(),
+    specFile,
+    profile: ctx.profile,
+    entity: ctx.entity,
+    module: ctx.module,
+    shell: ctx.shell,
+    shellVariant: ctx.shellVariant,
+    commonSpecRef: ctx.commonSpecRef,
+    designRegistry: registry.registryPath,
+    slotBindings: ctx.slotBindings,
+    componentFiles: ctx.componentFiles,
+    files: plan.map((f) => ({ layer: f.layer, path: f.relativePath, template: f.template })),
+    tags: ctx.parsedTags.raw,
+    skipped: skipped.map((s) => s.relativePath)
+  }
+
+  const handoff = renderHandoffMarkdown(ctx, written, skipped)
+  const meta = await writeGeneratedMeta(featureDir, manifest, handoff, { dryRun: options.dryRun })
+
+  console.log(`portal-gen: profile=${ctx.profile} entity=${ctx.entity} shell=${ctx.shell} (${ctx.shellVariant})`)
+  console.log(`  spec: ${specFile}`)
+  if (options.dryRun) console.log('  mode: dry-run')
+
+  for (const warning of ctx.designValidation?.warnings ?? []) {
+    console.log(`  design warn: ${warning}`)
+  }
+
+  for (const binding of ctx.slotBindings) {
+    if (binding.wired) {
+      console.log(`  slot: #${binding.slot} → <${binding.component} :${binding.valueProp}>`)
+    }
+  }
+
+  for (const w of written) {
+    console.log(`  ${options.dryRun ? '[dry]' : 'write'}: ${w.relativePath}`)
+  }
+  for (const s of skipped) {
+    console.log(`  skip: ${s.relativePath} (${s.reason})`)
+  }
+
+  if (!options.dryRun) {
+    const pageWritten = written.find((w) => w.relativePath?.startsWith('pages/') && w.relativePath.endsWith('.vue'))
+    if (pageWritten) {
+      const lifecycle = await upsertPageLifecycle(root, {
+        routePath: ctx.route.path,
+        specFile: specFile,
+        title: ctx.title,
+        stage: 'prototype'
+      })
+      console.log(`  lifecycle: ${lifecycle.routePath} → stage=${lifecycle.stage} (${lifecycle.registryPath})`)
+    }
+
+    await syncPageLifecycleFromManifests(root)
+    console.log(`  handoff: ${path.relative(root, meta.handoffPath)}`)
+  }
+
+  if (spec.i18n) {
+    const localesDir = path.join(root, 'locales')
+    const i18nFiles = mergeI18nFlat(spec.i18n, localesDir, options.dryRun)
+    for (const f of i18nFiles) {
+      console.log(`  ${options.dryRun ? '[dry] ' : 'write'}: ${path.relative(root, f.path)} (+${f.keysAdded} keys)`)
+    }
+  }
+
+  return { specFile, wrotePage: !options.dryRun && written.some((w) => w.relativePath?.startsWith('pages/')) }
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2))
+  const registry = await loadDesignRegistry(root)
+  const specPaths = await resolveSpecPaths(options)
+
+  if (specPaths.length > 1) {
+    console.log(`portal-gen: ${specPaths.length} ir/design.yaml file(s)`)
+  }
+
+  let docsRenderNeeded = false
+  let failed = 0
+
+  for (const specPath of specPaths) {
+    try {
+      const result = await generateOne(options, registry, specPath)
+      if (result.wrotePage) docsRenderNeeded = true
+      if (specPaths.length > 1) console.log('')
+    } catch (error) {
+      failed++
+      console.error(`portal-gen: FAIL ${path.relative(root, specPath)}: ${error.message ?? error}`)
+    }
+  }
+
+  if (!options.dryRun && docsRenderNeeded) runDocsRender()
+  process.exit(failed > 0 ? 1 : 0)
+}
+
+/** Docs markdown render stays on the docs hub / FlowGrid docs — never assume sibling checkout. */
+function runDocsRender() {
+  console.log('  docs:render: handoff to docs hub / FlowGrid docs (not executed from FlowGrid)')
+}
+
+main().catch((error) => {
+  console.error(error.message ?? error)
+  process.exit(1)
+})

package/adapters/nuxt4/codegen/runners/lib/component-resolve.mjs

@@ -0,0 +1,66 @@
+import { readdir } from 'node:fs/promises'
+import path from 'node:path'
+
+/**
+ * Find existing molecule file for MoName → components/molecules/.../Name.vue
+ * @param {string} root
+ * @param {string} moName e.g. MoStatusChip
+ */
+export async function findMoleculeComponent(root, moName) {
+  const base = moName.replace(/^Mo/, '')
+  const moleculesDir = path.join(root, 'components/molecules')
+
+  async function walk(dir) {
+    let entries = []
+    try {
+      entries = await readdir(dir, { withFileTypes: true })
+    } catch {
+      return null
+    }
+
+    for (const entry of entries) {
+      const entryPath = path.join(dir, entry.name)
+      if (entry.isDirectory()) {
+        const found = await walk(entryPath)
+        if (found) return found
+        continue
+      }
+      if (entry.isFile() && entry.name === `${base}.vue`) {
+        return path.relative(root, entryPath)
+      }
+    }
+
+    return null
+  }
+
+  return walk(moleculesDir)
+}
+
+/**
+ * Default path for portal-gen component stub when molecule does not exist.
+ * @param {string} moName
+ */
+export function defaultComponentStubPath(moName) {
+  return `components/molecules/custom/${moName}.vue`
+}
+
+/**
+ * @param {string} root
+ * @param {string[]} componentNames
+ */
+export async function resolveComponentFiles(root, componentNames) {
+  /** @type {Record<string, { exists: boolean, path: string | null, stubPath: string }>} */
+  const map = {}
+
+  for (const name of componentNames) {
+    const existing = await findMoleculeComponent(root, name)
+    const stubPath = defaultComponentStubPath(name)
+    map[name] = {
+      exists: Boolean(existing),
+      path: existing,
+      stubPath
+    }
+  }
+
+  return map
+}

package/adapters/nuxt4/codegen/runners/lib/design-registry.mjs

@@ -0,0 +1,332 @@
+import { readFile, readdir } from 'node:fs/promises'
+import path from 'node:path'
+
+export const REGISTRY_REL = 'registries/design.registry.json'
+
+const TAG_PREFIX = {
+  shell: '#shell:',
+  ui: '#ui:',
+  widget: '#widget:',
+  render: '#render:',
+  shape: '#shape:',
+  pattern: '#pattern:',
+  style: '#style:',
+  needsUi: '#needs-ui:'
+}
+
+/** @param {string} kebab */
+export function folderToPascalCase(kebab) {
+  return String(kebab)
+    .split('-')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+}
+
+/**
+ * @param {string} root
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export async function loadDesignRegistry(root) {
+  let registryPath = path.join(root, REGISTRY_REL)
+  const customPath = path.join(root, '.flowgrid/adapters/custom/registries/design.registry.json')
+  
+  // Check if custom registry exists
+  try {
+    const rawCustom = JSON.parse(await readFile(customPath, 'utf8'))
+    const components = await discoverShadcnComponents(root, rawCustom)
+    return { ...rawCustom, components, registryPath: customPath }
+  } catch {}
+
+  const raw = JSON.parse(await readFile(registryPath, 'utf8'))
+  const components = await discoverShadcnComponents(root, raw)
+  return { ...raw, components, registryPath }
+}
+
+/**
+ * @param {string} root
+ * @param {Record<string, unknown>} raw
+ */
+async function discoverShadcnComponents(root, raw) {
+  const uiDir = path.join(root, 'components/ui')
+  const aliases = raw.componentAliases ?? {}
+  /** @type {Record<string, object>} */
+  const components = {}
+
+  let entries = []
+  try {
+    entries = await readdir(uiDir, { withFileTypes: true })
+  } catch {
+    return components
+  }
+
+  const categoryByName = buildCategoryIndex(raw.componentCategories ?? {})
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const canonical = folderToPascalCase(entry.name)
+    const extra = aliases[canonical] ?? {}
+    components[canonical] = {
+      canonical,
+      category: categoryByName[canonical] ?? 'ui',
+      tags: [`#ui: ${canonical}`],
+      aliases: extra.aliases ?? {},
+      patterns: extra.patterns ?? [],
+      disambiguate: extra.disambiguate,
+      portal: {
+        layer: 'ui',
+        path: `components/ui/${entry.name}`,
+        status: 'implemented'
+      }
+    }
+  }
+
+  return components
+}
+
+/** @param {Record<string, string[]>} categories */
+function buildCategoryIndex(categories) {
+  /** @type {Record<string, string>} */
+  const index = {}
+  for (const [category, names] of Object.entries(categories)) {
+    for (const name of names) {
+      index[name] = category
+    }
+  }
+  return index
+}
+
+/**
+ * @param {string[]} tags
+ */
+export function parseDesignTags(tags = []) {
+  const parsed = {
+    shell: [],
+    ui: [],
+    widget: [],
+    render: [],
+    shape: [],
+    pattern: [],
+    style: [],
+    needsUi: [],
+    raw: tags
+  }
+
+  for (const tag of tags) {
+    const text = String(tag).trim()
+    if (text.startsWith(TAG_PREFIX.shell)) {
+      parsed.shell.push(text.slice(TAG_PREFIX.shell.length).trim())
+    } else if (text.startsWith(TAG_PREFIX.ui)) {
+      parsed.ui.push(text.slice(TAG_PREFIX.ui.length).trim())
+    } else if (text.startsWith(TAG_PREFIX.widget)) {
+      parsed.widget.push(text.slice(TAG_PREFIX.widget.length).trim())
+    } else if (text.startsWith(TAG_PREFIX.render)) {
+      parsed.render.push(text.slice(TAG_PREFIX.render.length).trim())
+    } else if (text.startsWith(TAG_PREFIX.shape)) {
+      parsed.shape.push(text.slice(TAG_PREFIX.shape.length).trim())
+    } else if (text.startsWith(TAG_PREFIX.pattern)) {
+      parsed.pattern.push(text.slice(TAG_PREFIX.pattern.length).trim())
+    } else if (text.startsWith(TAG_PREFIX.style)) {
+      parsed.style.push(text.slice(TAG_PREFIX.style.length).trim())
+    } else if (text.startsWith(TAG_PREFIX.needsUi)) {
+      parsed.needsUi.push(text.slice(TAG_PREFIX.needsUi.length).trim())
+    }
+  }
+
+  return parsed
+}
+
+/**
+ * Normalize free text → canonical registry key via aliasIndex.
+ * @param {string} input
+ * @param {Record<string, unknown>} registry
+ */
+export function lookupAlias(input, registry) {
+  const key = String(input).trim().toLowerCase()
+  if (!key) return null
+
+  const aliasIndex = registry.aliasIndex ?? {}
+  if (aliasIndex[key]) return aliasIndex[key]
+
+  if (registry.shells?.[input]) return input
+  if (registry.components?.[input]) return input
+  if (registry.fieldWidgets?.[input]) return input
+
+  const pascal = folderToPascalCase(key.replace(/\s+/g, '-'))
+  if (registry.components?.[pascal]) return pascal
+  if (registry.shells?.[pascal]) return pascal
+
+  return null
+}
+
+/**
+ * @param {{
+ *   profile: string
+ *   composition?: { pattern?: string, overrideCommonPattern?: boolean }
+ *   designTags: ReturnType<typeof parseDesignTags>
+ *   registry: Record<string, unknown>
+ * }} options
+ */
+export function resolveShell({ profile, composition = {}, designTags, registry }) {
+  const shells = registry.shells ?? {}
+  const defaults = registry.defaults ?? {}
+  const shellByProfile = defaults.shellByProfile ?? {}
+
+  let shellName =
+    designTags.shell[0] ??
+    (composition.pattern && composition.pattern !== 'custom' ? composition.pattern : null) ??
+    shellByProfile[profile] ??
+    (profile === 'list' ? defaults.listShell : null) ??
+    null
+
+  if (shellName === 'custom') {
+    shellName = profile === 'list' ? 'DataListPage' : shellName
+  }
+
+  const shellEntry = shellName ? shells[shellName] : null
+  const overrideCommonPattern = composition.overrideCommonPattern === true
+  const patternCustom = composition.pattern === 'custom'
+  const tagCustom = designTags.shell.includes('custom')
+
+  const useCustomVariant =
+    profile === 'list' &&
+    (overrideCommonPattern || patternCustom || tagCustom)
+
+  let listPageTemplate = null
+  if (profile === 'list' && shells.DataListPage?.portalGen) {
+    const gen = shells.DataListPage.portalGen
+    listPageTemplate = useCustomVariant ? gen.templateCustom : gen.templateStandard
+  }
+
+  return {
+    shell: shellName,
+    shellEntry,
+    variant: useCustomVariant ? 'custom' : 'standard',
+    useCustomShell: useCustomVariant,
+    listPageTemplate,
+    commonSpecRef: shellEntry?.commonSpecRef ?? shells.DataListPage?.commonSpecRef ?? null
+  }
+}
+
+/**
+ * Suggest default design tags for grill when missing from spec.
+ * @param {Record<string, unknown>} spec
+ * @param {Record<string, unknown>} registry
+ */
+export function suggestDesignTags(spec, registry) {
+  const profile = spec.codegen?.profile ?? 'list'
+  const existing = new Set((spec.tags ?? []).map((t) => String(t).trim()))
+  const suggested = []
+
+  const shellResolution = resolveShell({
+    profile,
+    composition: spec.ui?.composition ?? {},
+    designTags: parseDesignTags(spec.tags ?? []),
+    registry
+  })
+
+  const shellTag = `#shell: ${shellResolution.variant === 'custom' && profile === 'list' ? 'DataListPage' : shellResolution.shell ?? 'DataListPage'}`
+  if (![...existing].some((t) => t.startsWith(TAG_PREFIX.shell))) {
+    suggested.push(shellTag)
+  }
+
+  if (profile === 'list' && !suggested.some((t) => t.includes('DataListPage')) && !existing.has(shellTag)) {
+    suggested.push('#shell: DataListPage')
+  }
+
+  if (![...existing].some((t) => t.startsWith(TAG_PREFIX.pattern))) {
+    suggested.push('#pattern: CRUD')
+  }
+
+  for (const style of registry.defaults?.style ?? []) {
+    const tag = `#style: ${style}`
+    if (![...existing].some((t) => t.startsWith(TAG_PREFIX.style) && t.includes(style))) {
+      suggested.push(tag)
+    }
+  }
+
+  return [...new Set(suggested)]
+}
+
+/**
+ * @param {ReturnType<typeof buildCodegenContext>} ctx
+ * @param {Record<string, unknown>} registry
+ */
+export function applyDesignRegistry(ctx, registry) {
+  const designTags = parseDesignTags(ctx.spec?.tags ?? [])
+  const shellResolution = resolveShell({
+    profile: ctx.profile,
+    composition: ctx.spec?.ui?.composition ?? {},
+    designTags,
+    registry
+  })
+
+  ctx.designTags = designTags
+  ctx.shell = shellResolution.shell
+  ctx.shellVariant = shellResolution.variant
+  ctx.shellEntry = shellResolution.shellEntry
+  ctx.commonSpecRef = shellResolution.commonSpecRef
+  ctx.suggestedDesignTags = suggestDesignTags(ctx.spec, registry)
+
+  if (ctx.profile === 'list') {
+    ctx.useCustomShell = shellResolution.useCustomShell
+    if (shellResolution.listPageTemplate) {
+      ctx.listPageTemplate = shellResolution.listPageTemplate
+    }
+  }
+
+  return ctx
+}
+
+/**
+ * @param {ReturnType<typeof buildCodegenContext>} ctx
+ * @param {Record<string, unknown>} registry
+ * @param {{ strict?: boolean }} options
+ */
+export function validateSpecDesign(ctx, registry, options = {}) {
+  const errors = []
+  const warnings = []
+  const { designTags } = ctx
+
+  for (const shell of designTags.shell) {
+    if (shell === 'custom') continue
+    if (!registry.shells?.[shell]) {
+      errors.push(`Unknown #shell: ${shell} — see registries/design.registry.json shells`)
+    }
+  }
+
+  for (const ui of designTags.ui) {
+    if (!registry.components?.[ui] && !registry.shells?.[ui]) {
+      errors.push(`Unknown #ui: ${ui} — not in shadcn components or shells`)
+    }
+  }
+
+  for (const widget of designTags.widget) {
+    const entry = registry.fieldWidgets?.[widget]
+    if (!entry) {
+      errors.push(`Unknown #widget: ${widget}`)
+      continue
+    }
+    if (entry.portal?.status === 'planned' && !designTags.needsUi.includes(widget)) {
+      warnings.push(
+        `#widget: ${widget} is planned — add #needs-ui: ${widget} or implement molecule first`
+      )
+    }
+  }
+
+  if (ctx.profile === 'list' && !ctx.shell && options.strict) {
+    errors.push('List profile requires shell — add #shell: DataListPage or ui.composition.pattern: DataListPage')
+  }
+
+  if (
+    ctx.useCustomShell &&
+    ctx.shell === 'DataListPage' &&
+    !ctx.spec?.notes?.length &&
+    !(ctx.spec?.openQuestions?.length)
+  ) {
+    warnings.push(
+      'DataListPage custom variant: document reason in notes (embedded blocks, toolbar overrides, etc.)'
+    )
+  }
+
+  return { errors, warnings }
+}