@shanyucoder/flowgrid 0.1.0

package/adapters/nextjs/codegen/templates/list/useList.ts.hbs

@@ -0,0 +1,93 @@
+'use client';
+
+import { useCallback, useMemo, useState } from 'react';
+import { create{{entityPascal}}Service } from '@/services/{{entity}}.service';
+import { use{{entityPascal}}Columns } from './use{{entityPascal}}Columns';
+import { use{{entityPascal}}Filters } from './use{{entityPascal}}Filters';
+{{#if hasExportBlock}}
+import { use{{entityPascal}}Export } from './use{{entityPascal}}Export';
+{{/if}}
+import { {{entityCamel}}MockSearch } from '@/mocks/{{entity}}.mock';
+
+/**
+ * {{title}} — list hook (portal-gen).
+ * Mock boundary: replace {{entityCamel}}MockSearch with service.search on /wire.
+ */
+export function use{{entityPascal}}List() {
+  const service = useMemo(() => create{{entityPascal}}Service(), []);
+  const { columns, searchKeys } = use{{entityPascal}}Columns();
+  const { query, setQuery, filters, resetQuery{{#if hasPerPageToolbar}}, perPage, onPerPageChange{{/if}} } = use{{entityPascal}}Filters();
+{{#if hasExportBlock}}
+  const { exportMonth, setExportMonth, exportPending, exportOpenRateReport } = use{{entityPascal}}Export(service);
+{{/if}}
+
+  const [pending, setPending] = useState(false);
+  const [errorMsg, setErrorMsg] = useState<string | null>(null);
+  const [items, setItems] = useState<Record<string, unknown>[]>([]);
+  const [total, setTotal] = useState<number | null>(null);
+
+  const load = useCallback(async () => {
+    setPending(true);
+    setErrorMsg(null);
+    try {
+      const result = await {{entityCamel}}MockSearch(query);
+      setItems(result.items);
+      setTotal(result.total ?? result.items.length);
+    } catch (error: unknown) {
+      setErrorMsg((error as Error)?.message ?? 'Cannot load {{title}}');
+      setItems([]);
+      setTotal(null);
+    } finally {
+      setPending(false);
+    }
+  }, [query]);
+
+  const onSearch = useCallback(() => load(), [load]);
+
+  const onReset = useCallback(async () => {
+    resetQuery();
+    setPending(true);
+    setErrorMsg(null);
+    try {
+      const nextQuery = { per_page: {{defaultPageSize}} };
+      const result = await {{entityCamel}}MockSearch(nextQuery);
+      setItems(result.items);
+      setTotal(result.total ?? result.items.length);
+    } catch (error: unknown) {
+      setErrorMsg((error as Error)?.message ?? 'Cannot load {{title}}');
+      setItems([]);
+      setTotal(null);
+    } finally {
+      setPending(false);
+    }
+  }, [resetQuery]);
+
+{{#if hasLoginAs}}
+  const loginAsStoreManager = useCallback(async (manager: { id: number }) => {
+    console.info('loginAsStoreManager', manager.id);
+  }, []);
+{{/if}}
+
+  return {
+    pending,
+    errorMsg,
+    items,
+    total,
+    query,
+    setQuery,
+    filters,
+    columns,
+    searchKeys,
+    load,
+    onSearch,
+    onReset,
+    service{{#if hasPerPageToolbar}},
+    perPage,
+    onPerPageChange{{/if}}{{#if hasExportBlock}},
+    exportMonth,
+    setExportMonth,
+    exportPending,
+    exportOpenRateReport{{/if}}{{#if hasLoginAs}},
+    loginAsStoreManager{{/if}}
+  };
+}

package/adapters/nextjs/codegen/templates/list/useListColumns.ts.hbs

@@ -0,0 +1,27 @@
+'use client';
+
+import { useMemo } from 'react';
+import type { DataTableColumn } from '@/components/molecules/data-table-types';
+
+/**
+ * {{title}} — column definitions (portal-gen).
+ */
+export function use{{entityPascal}}Columns() {
+  const columns = useMemo<DataTableColumn[]>(
+    () => [
+{{#each columns}}
+      {
+        key: '{{key}}',
+        title: t('{{title}}'){{#if sortable}},
+        sortable: true{{/if}}{{#if align}},
+        align: '{{align}}'{{/if}}
+      }{{#unless @last}},{{/unless}}
+{{/each}}
+    ],
+    [],
+  );
+
+  const searchKeys = useMemo(() => columns.map((column) => column.key), [columns]);
+
+  return { columns, searchKeys };
+}

package/adapters/nextjs/codegen/templates/list/useListExport.ts.hbs

@@ -0,0 +1,31 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import type { {{entityPascal}}Service } from '@/services/{{entity}}.service';
+
+/**
+ * {{title}} — export report logic (portal-gen).
+ * Only generated when spec includes export block.
+ */
+export function use{{entityPascal}}Export(service: {{entityPascal}}Service) {
+  const [exportMonth, setExportMonth] = useState(defaultExportMonth());
+  const [exportPending, setExportPending] = useState(false);
+
+  const exportOpenRateReport = useCallback(async () => {
+    setExportPending(true);
+    try {
+      await service.exportReport?.({ month: exportMonth });
+    } finally {
+      setExportPending(false);
+    }
+  }, [exportMonth, service]);
+
+  return { exportMonth, setExportMonth, exportPending, exportOpenRateReport };
+}
+
+function defaultExportMonth(): string {
+  const date = new Date();
+  date.setMonth(date.getMonth() - 1);
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  return `${date.getFullYear()}-${month}`;
+}

package/adapters/nextjs/codegen/templates/list/useListFilters.ts.hbs

@@ -0,0 +1,50 @@
+'use client';
+
+import { useCallback, useMemo, useState } from 'react';
+
+/**
+ * {{title}} — filter config + search/reset logic (portal-gen).
+ */
+export function use{{entityPascal}}Filters() {
+  const [query, setQuery] = useState<Record<string, unknown>>({ per_page: {{defaultPageSize}} });
+
+  const filters = useMemo(
+    () => [
+{{#each filters}}
+      {
+        name: '{{name}}',
+        label: t('{{label}}'),
+        type: '{{type}}'{{#if placeholder}},
+        placeholder: t('{{placeholder}}'){{/if}}
+      }{{#unless @last}},{{/unless}}
+{{/each}}
+    ],
+    [],
+  );
+
+{{#if hasPerPageToolbar}}
+  const perPage = Number(query.per_page ?? {{defaultPageSize}});
+
+  const onPerPageChange = useCallback(
+    (value: number) => {
+      setQuery((current) => ({ ...current, per_page: value, page: 1 }));
+    },
+    [],
+  );
+{{/if}}
+
+  const resetQuery = useCallback(() => {
+    const nextQuery = { per_page: {{defaultPageSize}} };
+    setQuery(nextQuery);
+    return nextQuery;
+  }, []);
+
+  return {
+    query,
+    setQuery,
+    filters,
+    resetQuery{{#if hasPerPageToolbar}},
+    perPage,
+    onPerPageChange{{/if}}
+  };
+}

package/adapters/nextjs/codegen/templates/store/store.ts.hbs

@@ -0,0 +1,28 @@
+import { create } from 'zustand';
+import type { {{entityPascal}} } from '@portal/models/{{entity}}';
+
+export interface {{entityPascal}}State {
+  selectedItem: {{entityPascal}} | null;
+  items: {{entityPascal}}[];
+  loading: boolean;
+
+  setSelectedItem: (item: {{entityPascal}} | null) => void;
+  setItems: (items: {{entityPascal}}[]) => void;
+  setLoading: (loading: boolean) => void;
+  reset: () => void;
+}
+
+/**
+ * Zustand global store for {{entityPascal}}.
+ * Triggered via #use-store tag in FlowGrid docs spec.
+ */
+export const use{{entityPascal}}Store = create<{{entityPascal}}State>()((set) => ({
+  selectedItem: null,
+  items: [],
+  loading: false,
+
+  setSelectedItem: (item) => set({ selectedItem: item }),
+  setItems: (items) => set({ items }),
+  setLoading: (loading) => set({ loading }),
+  reset: () => set({ selectedItem: null, items: [], loading: false }),
+}));

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

@@ -0,0 +1,47 @@
+# Contract codegen (`contract-gen`)
+
+Zod contract SSOT in `packages/models` — shared by Next FE and Nest.
+
+## Input
+
+IR `…/ir/design.yaml` with `entities[].fields[]` (`kind`, `scopes`, `contract`,
+`persistence`). Discovery order when `--spec` is omitted:
+
+1. `--yaml-root <path>`
+2. `FLOWGRID_DOCS_ROOT` (and `…/product`, `…/docs/features/yaml`)
+3. `$FLOWGRID_PROJECT_ROOT/docs/features/yaml`
+
+When `entities` is empty, infers scalar/relation fields from `ui.columns`
+(pilot fallback).
+
+## Commands
+
+```bash
+flowgrid contract-registry
+flowgrid contract-gen:dry -- --spec path/to/ir/design.yaml
+flowgrid contract-gen -- --spec path/to/ir/design.yaml
+flowgrid contract-gen -- --spec … --force
+```
+
+## Registry ownership
+
+| Layer | Path |
+|-------|------|
+| Toolkit default (SSOT schema) | `adapters/nextjs/registries/contract-field.registry.json` |
+| Product policy (synced on init for `--adapter=nextjs`) | `registries/contract-field.registry.json` |
+
+Validator resolves **product first**, then adapter default.
+
+## Output
+
+| Path | Purpose |
+|------|---------|
+| `packages/models/src/{entity}/*.read.schema.ts` | Response / list contract |
+| `packages/models/src/{entity}/*.write.schema.ts` | Create/update command payload |
+| `packages/models/src/{entity}/*.relationships.meta.ts` | ORM-agnostic relation meta |
+| `{function}/generated/contract.manifest.json` | Plan + written paths |
+
+`flowgrid gen` does **not** emit models — run `flowgrid contract-gen` first.
+
+Stale product-root `contractgen/` trees are reported by `flowgrid status` and
+removed by `flowgrid prune --yes` when present.

package/adapters/nextjs/contractgen/runners/generate.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import path from 'node:path'
+
+import { buildContractPlan } from './lib/plan.mjs'
+import { parseArgs, readSpecFile } from './lib/naming.mjs'
+import { writeManifest, writeOutputs } from './lib/write-files.mjs'
+import { requireDesignIrPath } from '../../../shared/read-fe-ir.mjs'
+
+const root = path.resolve(process.env.FLOWGRID_PROJECT_ROOT ?? process.cwd())
+
+/**
+ * Prefer explicit --yaml-root, then FLOWGRID_DOCS_ROOT (+ optional /product),
+ * then product-local docs/features/yaml under FLOWGRID_PROJECT_ROOT.
+ */
+function resolveIrGlobRoots(options) {
+  const roots = []
+  if (options.yamlRoot) {
+    roots.push(path.resolve(options.yamlRoot))
+  }
+  const docsRoot = process.env.FLOWGRID_DOCS_ROOT
+  if (docsRoot) {
+    const abs = path.resolve(docsRoot)
+    roots.push(path.join(abs, 'surfaces'))
+    roots.push(abs)
+  }
+  return [...new Set(roots)]
+}
+
+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()) {
+      files.push(...(await listIrDesignFiles(entryPath)))
+      continue
+    }
+    if (entry.isFile() && entry.name === 'design.yaml' && entryPath.includes(`${path.sep}ir${path.sep}`)) {
+      files.push(entryPath)
+    }
+  }
+
+  return files.sort()
+}
+
+async function resolveSpecPaths(options) {
+  if (options.spec) return [requireDesignIrPath(options.spec)]
+  for (const candidate of resolveIrGlobRoots(options)) {
+    if (!existsSync(candidate)) continue
+    const discovered = await listIrDesignFiles(candidate)
+    if (discovered.length > 0) return discovered
+  }
+  throw new Error(
+    'No ir/design.yaml found — pass --spec <ir/design.yaml>, --yaml-root, or set FLOWGRID_DOCS_ROOT',
+  )
+}
+
+async function runForSpec(specPath, options) {
+  const spec = await readSpecFile(specPath)
+  const plan = buildContractPlan(spec, specPath)
+
+  if (plan.files.length === 0) {
+    console.warn(`[contract-gen] skip (no entities/fields): ${specPath}`)
+    return { written: [], skipped: [] }
+  }
+
+  const { written, skipped } = await writeOutputs(root, plan, options)
+  const manifest = await writeManifest(root, plan, specPath, { ...options, written, skipped })
+
+  console.log(`[contract-gen] ${options.dryRun ? 'dry' : 'write'} ${specPath}`)
+  console.log(`  files: ${written.length} written, ${skipped.length} skipped`)
+
+  return manifest
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2))
+  const specs = await resolveSpecPaths(options)
+
+  if (specs.length > 1) {
+    console.log(`contract-gen: ${specs.length} ir/design.yaml file(s)`)
+  }
+
+  let failed = 0
+  for (const specPath of specs) {
+    try {
+      await runForSpec(specPath, options)
+      if (specs.length > 1) console.log('')
+    } catch (e) {
+      failed++
+      console.error(`contract-gen: FAIL ${path.relative(root, specPath)}: ${e.message ?? e}`)
+    }
+  }
+  process.exit(failed > 0 ? 1 : 0)
+}
+
+main().catch((error) => {
+  console.error(error.message ?? error)
+  process.exit(1)
+})

package/adapters/nextjs/contractgen/runners/lib/field-zod.mjs

@@ -0,0 +1,83 @@
+/**
+ * Map spec field definitions → Zod expression strings for codegen.
+ */
+
+const SCALAR_ZOD = {
+  integer: (field) => (field.key === 'id' ? 'fields.id' : 'z.number().int()'),
+  number: () => 'z.number()',
+  string: (field) => {
+    if (field.key === 'email') return 'fields.email'
+    if (field.key === 'status') return 'fields.status.optional()'
+    if (field.key?.endsWith('_at')) return 'fields.createdAt'
+    return 'fields.optionalNullableString'
+  },
+  boolean: () => 'z.boolean()',
+  datetime: () => 'fields.createdAt'
+}
+
+function embedZod(embedFields) {
+  const lines = (embedFields ?? ['id']).map((key) => {
+    if (key === 'id') return '  id: fields.id,'
+    if (key === 'full_name') return '  full_name: fields.optionalNullableString,'
+    if (key === 'name') return '  name: fields.optionalNullableString,'
+    if (key === 'email') return '  email: fields.email,'
+    return `  ${key}: fields.optionalNullableString,`
+  })
+  return `z.object({\n${lines.join('\n')}\n})`
+}
+
+function zodForArrayItem(field) {
+  if (field.kind === 'relation') return zodForRelation(field, 'read')
+  if (field.kind === 'fk') return 'fields.id.optional()'
+  return zodForScalar(field)
+}
+
+export function zodForArray(field) {
+  const itemFields = field.items ?? []
+  if (itemFields.length === 0) {
+    return 'z.array(z.unknown())'
+  }
+  const lines = itemFields.map((item) => `  ${item.key}: ${zodForArrayItem(item)},`)
+  const arrayExpr = `z.array(z.object({\n${lines.join('\n')}\n}))`
+  return field.optional ? `${arrayExpr}.optional()` : arrayExpr
+}
+
+export function zodForScalar(field) {
+  const type = field.type ?? 'string'
+  if (type === 'array') return zodForArray(field)
+  const mapper = SCALAR_ZOD[type] ?? SCALAR_ZOD.string
+  let expr = mapper(field)
+  if (field.readOnly && !expr.includes('.optional()')) {
+    expr = expr.replace(/\)$/, '.optional()') === expr ? expr : expr
+  }
+  if (field.nullable && !expr.includes('nullable')) {
+    expr = `${expr}.nullable()`
+  }
+  return expr
+}
+
+export function zodForRelation(field, mode = 'read') {
+  const embed = field.contract?.read?.embed ?? field.embed ?? ['id', 'full_name']
+  const embedSchema = embedZod(embed)
+
+  if (mode === 'write') {
+    const writeMode = field.contract?.write?.mode ?? 'syncIds'
+    if (writeMode === 'fkOnly' && field.persistence?.fkField) {
+      return 'fields.id'
+    }
+    if (field.cardinality === 'one') {
+      return embedSchema
+    }
+    return `z.array(${embedZod(['id'])})`
+  }
+
+  if (field.cardinality === 'one') {
+    return `${embedSchema}.optional()`
+  }
+  return `z.array(${embedSchema}).optional()`
+}
+
+export function fieldInScope(field, scope) {
+  const scopes = field.scopes ?? ['form', 'response', 'persistence']
+  return scopes.includes(scope)
+}

package/adapters/nextjs/contractgen/runners/lib/naming.mjs

@@ -0,0 +1,46 @@
+import fs from 'node:fs/promises'
+
+import yaml from 'yaml'
+
+export function parseArgs(argv) {
+  const options = { dryRun: false, force: false, spec: null, all: false, yamlRoot: 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 === '--yaml-root') options.yamlRoot = argv[++i]
+    else if (!arg.startsWith('-') && !options.spec) options.spec = arg
+  }
+
+  return options
+}
+
+import { requireDesignIrPath } from '../../../../shared/read-fe-ir.mjs'
+
+export async function readSpecFile(specPath) {
+  const raw = await fs.readFile(requireDesignIrPath(specPath), 'utf8')
+  return yaml.parse(raw)
+}
+
+export function resolveEntityKebab(entity, codegen = {}) {
+  const fromCodegen = codegen.entity ?? codegen.namespace
+  if (fromCodegen) {
+    return String(fromCodegen)
+      .replace(/([a-z])([A-Z])/g, '$1-$2')
+      .replace(/[\s_]+/g, '-')
+      .toLowerCase()
+  }
+  return String(entity.name ?? 'entity')
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase()
+}
+
+export function toPascalCase(value) {
+  return String(value)
+    .replace(/[-_\s]+(.)?/g, (_, c) => (c ? c.toUpperCase() : ''))
+    .replace(/^(.)/, (m) => m.toUpperCase())
+}

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

@@ -0,0 +1,147 @@
+import path from 'node:path'
+
+import { fieldInScope } from './field-zod.mjs'
+import { resolveEntityKebab, toPascalCase } from './naming.mjs'
+
+function inferFieldsFromColumns(spec) {
+  const columns = spec.ui?.columns ?? []
+  if (columns.length === 0) return []
+
+  return columns.map((column) => {
+    const key = column.key ?? column.name
+    if (!key) return null
+
+    if (key === 'managers' || column.type === 'relation') {
+      return {
+        key,
+        kind: 'relation',
+        cardinality: 'many',
+        target: column.target ?? 'User',
+        scopes: ['response'],
+        contract: {
+          read: { embed: ['id', 'full_name'], includeOn: ['list'] }
+        },
+        persistence: { type: 'hasMany', orm: 'typeorm' }
+      }
+    }
+
+    return {
+      key,
+      kind: 'scalar',
+      type: column.type === 'number' ? 'number' : 'string',
+      scopes: ['response', 'form']
+    }
+  }).filter(Boolean)
+}
+
+function normalizeEntities(spec) {
+  const entities = spec.entities ?? []
+  if (entities.length > 0) {
+    return entities.map((entity) => ({
+      ...entity,
+      fields: entity.fields ?? []
+    }))
+  }
+
+  const entityName = toPascalCase(spec.codegen?.entity ?? 'entity')
+  return [{
+    name: entityName,
+    table: spec.codegen?.module ?? `${entityName.toLowerCase()}s`,
+    fields: inferFieldsFromColumns(spec)
+  }]
+}
+
+export function deriveRelationships(entity) {
+  return (entity.fields ?? [])
+    .filter((f) => f.kind === 'relation' || f.kind === 'fk')
+    .map((field) => ({
+      entity: entity.name,
+      field: field.key,
+      kind: field.kind,
+      type: field.persistence?.type ?? (field.kind === 'fk' ? 'belongsTo' : 'hasMany'),
+      target: field.target,
+      cardinality: field.cardinality ?? 'one',
+      fkField: field.persistence?.fkField ?? null,
+      pivot: field.persistence?.pivot ?? null,
+      orm: field.persistence?.orm ?? 'typeorm',
+      writable: Boolean(field.contract?.write),
+      readEmbed: field.contract?.read?.embed ?? []
+    }))
+}
+
+export function buildContractPlan(spec, specPath) {
+  const entities = normalizeEntities(spec)
+  const files = []
+
+  for (const entity of entities) {
+    const entityKebab = resolveEntityKebab(entity, spec.codegen)
+    const entityPascal = toPascalCase(entity.name ?? entityKebab)
+
+    const readFields = (entity.fields ?? []).filter((f) => {
+      if (f.kind === 'fk') return fieldInScope(f, 'be') || fieldInScope(f, 'persistence')
+      return fieldInScope(f, 'response') || !f.scopes
+    })
+
+    const writeFields = (entity.fields ?? []).filter((f) => {
+      if (f.kind === 'relation') return f.contract?.write
+      if (f.kind === 'fk') return fieldInScope(f, 'form')
+      return fieldInScope(f, 'form') || (!f.scopes && f.kind !== 'relation')
+    })
+
+    files.push({
+      layer: 'models',
+      relativePath: `packages/models/src/${entityKebab}/${entityKebab}.read.schema.ts`,
+      template: 'read.schema.ts.hbs',
+      context: { entityKebab, entityPascal, fields: readFields, mode: 'read' }
+    })
+
+    if (writeFields.length > 0) {
+      files.push({
+        layer: 'models',
+        relativePath: `packages/models/src/${entityKebab}/${entityKebab}.write.schema.ts`,
+        template: 'write.schema.ts.hbs',
+        context: { entityKebab, entityPascal, fields: writeFields, mode: 'write' }
+      })
+    }
+
+    files.push({
+      layer: 'models',
+      relativePath: `packages/models/src/${entityKebab}/${entityKebab}.types.ts`,
+      template: 'types.ts.hbs',
+      context: { entityKebab, entityPascal, hasWrite: writeFields.length > 0 }
+    })
+
+    const relationships = deriveRelationships(entity)
+
+    files.push({
+      layer: 'models',
+      relativePath: `packages/models/src/${entityKebab}/index.ts`,
+      template: 'index.ts.hbs',
+      context: {
+        entityKebab,
+        entityPascal,
+        hasWrite: writeFields.length > 0,
+        relationships: relationships.length > 0
+      }
+    })
+    if (relationships.length > 0) {
+      files.push({
+        layer: 'meta',
+        relativePath: `packages/models/src/${entityKebab}/${entityKebab}.relationships.meta.ts`,
+        template: 'relationships.meta.ts.hbs',
+        context: { entityKebab, entityPascal, relationships }
+      })
+    }
+  }
+
+  const functionDir = specPath.includes(`${path.sep}ir${path.sep}`)
+    ? path.dirname(path.dirname(specPath))
+    : path.dirname(specPath)
+
+  return {
+    entities,
+    files,
+    manifestPath: path.join(functionDir, 'generated', 'contract.manifest.json'),
+    handoffPath: path.join(functionDir, 'generated', 'CONTRACT-HANDOFF.md')
+  }
+}