@shanyucoder/flowgrid 0.1.0

package/adapters/nestjs/nestgen/templates/orm/typeorm.entity.ts.hbs

@@ -0,0 +1,20 @@
+import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm'
+{{#if relationshipsMetaImport}}
+// Relation sync: {{relationshipsMetaImport}}
+{{/if}}
+
+@Entity('{{tableName}}')
+export class {{entityPascal}}Entity {
+{{#each ormColumns}}
+{{#if comment}}  // {{comment}}
+{{/if}}
+{{#each decorators}}
+  {{{this}}}
+{{/each}}
+  {{property}}!: {{tsType}}
+
+{{/each}}
+{{#each ormRelations}}
+  // {{type}} → {{target}} ({{field}}) — wire repository + syncRelation
+{{/each}}
+}

package/adapters/nestjs/nestgen/templates/queries/search.handler.ts.hbs

@@ -0,0 +1,36 @@
+import { IQueryHandler, QueryHandler } from '@nestjs/cqrs'
+import { InjectRepository } from '@nestjs/typeorm'
+import { Repository } from 'typeorm'
+
+import { toPaginatedEnvelope } from '../../../../common/crud/pagination.helper'
+import { {{entityPascal}}Entity } from '../{{entityKebab}}.entity'
+import { Search{{entityPascal}}Query } from './search-{{entityKebab}}.query'
+import { {{entityPascal}}Resource } from '../{{entityKebab}}.resource'
+
+@QueryHandler(Search{{entityPascal}}Query)
+export class Search{{entityPascal}}Handler implements IQueryHandler<Search{{entityPascal}}Query> {
+  constructor(
+    @InjectRepository({{entityPascal}}Entity)
+    private readonly repository: Repository<{{entityPascal}}Entity>
+  ) {}
+
+  async execute(query: Search{{entityPascal}}Query) {
+    const page = Number(query.dto.page ?? 1)
+    const perPage = Number(query.dto.per_page ?? 15)
+    const skip = (page - 1) * perPage
+
+    const [items, total] = await this.repository.findAndCount({
+      skip,
+      take: perPage,
+      order: { id: 'DESC' }
+    })
+
+    const envelope = toPaginatedEnvelope(
+      items.map((row) => {{entityPascal}}Resource.toDto(row)),
+      total,
+      { page, per_page: perPage }
+    )
+
+    return { data: envelope.items, meta: { pagination: envelope.meta } }
+  }
+}

package/adapters/nestjs/nestgen/templates/queries/search.query.ts.hbs

@@ -0,0 +1,3 @@
+export class Search{{entityPascal}}Query {
+  constructor(public readonly dto: Record<string, unknown>) {}
+}

package/adapters/nestjs/registries/nest-codegen.registry.json

@@ -0,0 +1,41 @@
+{
+  "version": 1,
+  "description": "Nest codegen tag registry — HBS templates for apps/api (CQRS).",
+  "profiles": {
+    "crud-standard": {
+      "defaultGenTags": ["#gen:module", "#gen:crud", "#gen:orm", "#gen:test-unit"]
+    },
+    "patch": {
+      "defaultGenTags": []
+    }
+  },
+  "genTags": {
+    "#gen:module": {
+      "layer": "module",
+      "template": "module.module.ts.hbs"
+    },
+    "#gen:crud": {
+      "layer": "controller",
+      "template": "entity.controller.ts.hbs"
+    },
+    "#gen:orm": {
+      "layer": "orm",
+      "template": "orm/typeorm.entity.ts.hbs"
+    },
+    "#gen:command-create": {
+      "layer": "command",
+      "template": "commands/create.handler.ts.hbs",
+      "when": "wire.create"
+    },
+    "#gen:command-update": {
+      "layer": "command",
+      "template": "commands/update.handler.ts.hbs",
+      "when": "wire.update"
+    },
+    "#gen:command-delete": {
+      "layer": "command",
+      "template": "commands/delete.handler.ts.hbs",
+      "when": "wire.delete"
+    }
+  }
+}

package/adapters/nestjs/registries/nest-unit-test.registry.json

@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "description": "Nest unit test codegen registry",
+  "patterns": {
+    "searchHandler": {
+      "when": "wire.search",
+      "template": "handlers/search.handler.spec.ts.hbs",
+      "output": "apps/api/src/modules/{moduleKebab}/{entityKebab}/queries/search-{entityKebab}.handler.spec.ts"
+    },
+    "createHandler": {
+      "when": "wire.create",
+      "template": "commands/create.handler.spec.ts.hbs",
+      "output": "apps/api/src/modules/{moduleKebab}/{entityKebab}/commands/create-{entityKebab}.handler.spec.ts"
+    },
+    "updateHandler": {
+      "when": "wire.update",
+      "template": "commands/update.handler.spec.ts.hbs",
+      "output": "apps/api/src/modules/{moduleKebab}/{entityKebab}/commands/update-{entityKebab}.handler.spec.ts"
+    },
+    "deleteHandler": {
+      "when": "wire.delete",
+      "template": "commands/delete.handler.spec.ts.hbs",
+      "output": "apps/api/src/modules/{moduleKebab}/{entityKebab}/commands/delete-{entityKebab}.handler.spec.ts"
+    },
+    "resource": {
+      "when": "always",
+      "template": "resource/entity.resource.spec.ts.hbs",
+      "output": "apps/api/src/modules/{moduleKebab}/{entityKebab}/{entityKebab}.resource.spec.ts"
+    }
+  }
+}

package/adapters/nextjs/codegen/runners/README.md

@@ -0,0 +1,68 @@
+# Portal Gen
+
+> **Doc chính:** [Portal codegen (gen + unit)](../../docs/operational/PORTAL-CODEGEN.md) — đọc trước khi quên thứ tự lệnh.
+
+Generate 4-layer scaffold from feature `ir/design.yaml` (Handlebars) into **`src/`**. API/contract uses the same `ir/design.yaml`.
+
+**Models:** `flowgrid gen` **không** sinh `models/`. Chạy `flowgrid contract-gen --spec .../ir/design.yaml` trước để có `@portal/models` (`packages/models/src/`).
+
+## Usage
+
+```bash
+flowgrid contract-gen:dry --spec docs/features/yaml/.../ir/design.yaml
+flowgrid contract-gen --spec docs/features/yaml/.../ir/design.yaml
+flowgrid registry   # validate registries/design.registry.json
+flowgrid gen --spec docs/features/yaml/admin/hotel/list/ir/design.yaml
+flowgrid gen:dry --spec docs/features/.../ir/design.yaml
+flowgrid gen --spec ... --force
+```
+
+## Design registry
+
+**Source:** `registries/design.registry.json`  
+**Docs:** `.cursor/extracts/portal-design-registry.md` · Rule: `.cursor/rules/portal-design-vocabulary.mdc`
+
+- shadcn/ui = canonical (`#ui: AlertDialog`)
+- List default shell: `#shell: DataListPage` (aliases: `DataListTable`, `common list`)
+- `flowgrid gen` resolves shell → list template (`page.tsx.hbs` vs `page.custom.tsx.hbs`)
+- Unknown `#ui:` / `#widget:` → dry-run fails
+
+## Spec requirements
+
+Copy `docs/templates/spec.yaml`. Required:
+
+- `codegen.profile` — `list` \| `create` \| `auth` \| `change-password` \| `public` \| `not-found` \| `error`
+- `codegen.entity`, `codegen.module`
+- `codegen.namespace` (optional) — when `module` differs from admin entity paths (e.g. `chain-hotels` → files under `chain-hotel/`)
+- `ui.routes`, `ui.columns` (list), `ui.filters` (optional)
+- `api.endpoints` with `action: list` or `create`
+- `tags` — see `.cursor/extracts/codegen/tags.md`
+
+**Lifecycle:** Khi ghi `src/app/(dashboard)/**/page.tsx`, flowgrid gen cập nhật registry (`prototype`) + `pnpm portal:lifecycle sync`. Xóa: `pnpm portal:remove --spec <file>`. Doc: `docs/operational/PAGE-LIFECYCLE.md`.
+
+## Output (Next.js)
+
+- `src/app/(dashboard)/{route}/page.tsx` — list/create/change-password
+- `src/app/(auth)/{route}/page.tsx` — login/forgot/reset (`profile: auth`)
+- `src/app/(public)/{route}/page.tsx` — other public pages
+- `src/app/not-found.tsx` / `src/app/error.tsx` — 404 / 503
+- `src/hooks/{entity}/use{Entity}List.ts`
+- `src/services/{entity}.service.ts`
+- `src/mocks/{entity}.mock.ts`
+- `src/validations/{entity}/schemas.ts` (create profile)
+- `docs/features/{feature}/generated/HANDOFF.md` + `codegen.manifest.json`
+
+## Templates
+
+```
+codegen/templates/
+  list/       — DataListPage; wires cell slots when Mo* exists under src
+  create/     — form scaffold (planned)
+codegen/runners/lib/
+  web-paths.mjs       — src path helpers
+  design-registry.mjs — load registry, resolve shell, validate tags
+```
+
+`#needs-component` in spec → page placeholder + HANDOFF; implement in `/prototype`, then re-gen.
+
+Stack: Node ESM + `yaml` + `handlebars`.

package/adapters/nextjs/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, 'messages')
+    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/nextjs/codegen/runners/lib/component-resolve.mjs

@@ -0,0 +1,79 @@
+import { readdir } from 'node:fs/promises'
+import path from 'node:path'
+
+import { toKebabCase } from './naming.mjs'
+
+const WEB_MOLECULES = 'src/components/molecules'
+
+/**
+ * MoDataTable → mo-data-table.tsx
+ * @param {string} moName
+ */
+function moleculeFileName(moName) {
+  const base = moName.replace(/^Mo/, '')
+  return `mo-${toKebabCase(base)}.tsx`
+}
+
+/**
+ * Find existing molecule file for MoName under src/components/molecules.
+ * @param {string} root
+ * @param {string} moName e.g. MoStatusChip
+ */
+export async function findMoleculeComponent(root, moName) {
+  const targetName = moleculeFileName(moName)
+  const moleculesDir = path.join(root, WEB_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 === targetName) {
+        return path.relative(root, entryPath).replace(/\\/g, '/')
+      }
+    }
+
+    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 `${WEB_MOLECULES}/custom/${moName}.tsx`
+}
+
+/**
+ * @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
+}