@shanyucoder/flowgrid 0.1.0

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

@@ -0,0 +1,57 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import Handlebars from 'handlebars'
+
+import { fieldInScope, zodForArray, zodForRelation, zodForScalar } from './field-zod.mjs'
+
+const templatesDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../templates')
+
+Handlebars.registerHelper('zodField', (field, mode) => {
+  if (!field) return 'z.unknown()'
+  if (field.kind === 'relation') return zodForRelation(field, mode ?? 'read')
+  if (field.kind === 'array') return zodForArray(field)
+  if (field.kind === 'fk') return 'fields.id.optional()'
+  return zodForScalar(field)
+})
+
+Handlebars.registerHelper('eq', (a, b) => a === b)
+
+export async function renderTemplate(templateName, context) {
+  const templatePath = path.join(templatesDir, templateName)
+  const source = await fs.readFile(templatePath, 'utf8')
+  const template = Handlebars.compile(source, { noEscape: true })
+  return template(context)
+}
+
+export function renderHandoffMarkdown(plan, specPath) {
+  const lines = [
+    '# Contract gen — HANDOFF',
+    '',
+    `Spec: \`${specPath}\``,
+    '',
+    '## Entities',
+    ''
+  ]
+
+  for (const entity of plan.entities) {
+    lines.push(`- **${entity.name}** — ${entity.fields?.length ?? 0} fields`)
+  }
+
+  lines.push('', '## Files', '')
+  for (const file of plan.files) {
+    lines.push(`- \`${file.relativePath}\``)
+  }
+
+  lines.push(
+    '',
+    '## Manual follow-up',
+    '',
+    '- Confirm `kind: relation` + `persistence.type` when grill infers from columns only.',
+    '- Backend scaffold: `flowgrid api-gen` / Nest `api-gen --adapter=nestjs` as needed.',
+    '',
+  )
+
+  return lines.join('\n')
+}

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

@@ -0,0 +1,54 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import { renderHandoffMarkdown, renderTemplate } from './render.mjs'
+
+export async function writeOutputs(root, plan, { dryRun, force }) {
+  const written = []
+  const skipped = []
+
+  for (const file of plan.files) {
+    const absPath = path.join(root, file.relativePath)
+    const content = await renderTemplate(file.template, {
+      ...file.context,
+      mode: file.context.mode ?? 'read'
+    })
+
+    if (!dryRun) {
+      await fs.mkdir(path.dirname(absPath), { recursive: true })
+      let exists = false
+      try {
+        await fs.access(absPath)
+        exists = true
+      } catch {
+        exists = false
+      }
+      if (exists && !force) {
+        skipped.push({ path: file.relativePath, reason: 'exists' })
+        continue
+      }
+      await fs.writeFile(absPath, content, 'utf8')
+    }
+    written.push(file.relativePath)
+  }
+
+  return { written, skipped }
+}
+
+export async function writeManifest(root, plan, specPath, { dryRun, written, skipped }) {
+  const manifest = {
+    spec: path.relative(root, specPath),
+    entities: plan.entities.map((e) => e.name),
+    written,
+    skipped,
+    generatedAt: new Date().toISOString()
+  }
+
+  if (!dryRun) {
+    await fs.mkdir(path.dirname(plan.manifestPath), { recursive: true })
+    await fs.writeFile(plan.manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
+    await fs.writeFile(plan.handoffPath, renderHandoffMarkdown(plan, specPath), 'utf8')
+  }
+
+  return manifest
+}

package/adapters/nextjs/contractgen/runners/validate-registry.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const productRoot = path.resolve(process.env.FLOWGRID_PROJECT_ROOT ?? process.cwd())
+const adapterRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..')
+
+async function resolveRegistryPath() {
+  const name = 'registries/contract-field.registry.json'
+  for (const root of [productRoot, adapterRoot]) {
+    const candidate = path.join(root, name)
+    try {
+      await fs.access(candidate)
+      return candidate
+    } catch {
+      // try next
+    }
+  }
+  throw new Error(
+    `Missing ${name} — sync via flowgrid init --adapter=nextjs or keep a product copy`,
+  )
+}
+
+async function main() {
+  const registryPath = await resolveRegistryPath()
+  const raw = await fs.readFile(registryPath, 'utf8')
+  const registry = JSON.parse(raw)
+  const errors = []
+
+  if (!registry.version) errors.push('missing version')
+  if (!Array.isArray(registry.fieldKinds) || registry.fieldKinds.length === 0) {
+    errors.push('fieldKinds must be a non-empty array')
+  }
+  if (!Array.isArray(registry.scopes) || registry.scopes.length === 0) {
+    errors.push('scopes must be a non-empty array')
+  }
+  if (!registry.scalarTypes || typeof registry.scalarTypes !== 'object') {
+    errors.push('scalarTypes must be an object')
+  }
+
+  console.log(`contract-field.registry.json OK (v${registry.version ?? '?'})`)
+  console.log(`  path: ${registryPath}`)
+  if (errors.length) {
+    for (const error of errors) console.error(`  error: ${error}`)
+    process.exit(1)
+  }
+  console.log('  validate: OK')
+}
+
+main().catch((error) => {
+  console.error(error.message ?? error)
+  process.exit(1)
+})

package/adapters/nextjs/contractgen/templates/index.ts.hbs

@@ -0,0 +1,8 @@
+export * from './{{entityKebab}}.read.schema.js'
+{{#if hasWrite}}
+export * from './{{entityKebab}}.write.schema.js'
+{{/if}}
+export * from './{{entityKebab}}.types.js'
+{{#if relationships}}
+export * from './{{entityKebab}}.relationships.meta.js'
+{{/if}}

package/adapters/nextjs/contractgen/templates/read.schema.ts.hbs

@@ -0,0 +1,22 @@
+import { z } from 'zod'
+
+import { fields } from '../common/fields.js'
+
+export const {{entityPascal}}ReadSchema = z.object({
+{{#each fields}}
+{{#if (eq kind 'relation')}}
+  {{key}}: {{{zodField this 'read'}}},
+{{else}}
+{{#unless (eq kind 'fk')}}
+  {{key}}: {{{zodField this 'read'}}},
+{{/unless}}
+{{/if}}
+{{/each}}
+})
+
+export const {{entityPascal}}ListSchema = z.array({{entityPascal}}ReadSchema)
+
+export const {{entityPascal}}ListResponseSchema = z.object({
+  items: {{entityPascal}}ListSchema,
+  total: z.number().optional()
+})

package/adapters/nextjs/contractgen/templates/relationships.meta.ts.hbs

@@ -0,0 +1,23 @@
+/**
+ * ORM-agnostic relationship metadata — consumed by nest:gen / CommandHandlers.
+ * Default ORM hint: typeorm (override per field with persistence.orm: prisma).
+ */
+export const {{entityPascal}}Relationships = {
+{{#each relationships}}
+  {{field}}: {
+    entity: '{{../entityPascal}}',
+    field: '{{field}}',
+    kind: '{{kind}}',
+    type: '{{type}}',
+    target: '{{target}}',
+    cardinality: '{{cardinality}}',
+    fkField: {{#if fkField}}'{{fkField}}'{{else}}null{{/if}},
+    pivot: {{#if pivot}}'{{pivot}}'{{else}}null{{/if}},
+    orm: '{{orm}}',
+    writable: {{writable}},
+    readEmbed: [{{#each readEmbed}}'{{this}}'{{#unless @last}}, {{/unless}}{{/each}}]
+  },
+{{/each}}
+} as const
+
+export type {{entityPascal}}RelationshipKey = keyof typeof {{entityPascal}}Relationships

package/adapters/nextjs/contractgen/templates/types.ts.hbs

@@ -0,0 +1,15 @@
+import type { z } from 'zod'
+
+import {
+  {{entityPascal}}ListResponseSchema,
+  {{entityPascal}}ReadSchema
+} from './{{entityKebab}}.read.schema.js'
+{{#if hasWrite}}
+import type { {{entityPascal}}WriteSchema } from './{{entityKebab}}.write.schema.js'
+{{/if}}
+
+export type {{entityPascal}} = z.infer<typeof {{entityPascal}}ReadSchema>
+export type {{entityPascal}}ListResponse = z.infer<typeof {{entityPascal}}ListResponseSchema>
+{{#if hasWrite}}
+export type {{entityPascal}}CreateRequest = z.infer<typeof {{entityPascal}}WriteSchema>
+{{/if}}

package/adapters/nextjs/contractgen/templates/write.schema.ts.hbs

@@ -0,0 +1,11 @@
+import { z } from 'zod'
+
+import { fields } from '../common/fields.js'
+
+export const {{entityPascal}}WriteSchema = z.object({
+{{#each fields}}
+  {{key}}: {{{zodField this 'write'}}},
+{{/each}}
+})
+
+export const {{entityPascal}}CreateRequestSchema = {{entityPascal}}WriteSchema

package/adapters/nextjs/registries/contract-field.registry.json

@@ -0,0 +1,22 @@
+{
+  "version": 1,
+  "description": "Contract field registry — kinds, scopes, and Zod mapping for contract:gen.",
+  "fieldKinds": ["scalar", "fk", "relation"],
+  "scopes": ["form", "response", "persistence", "be"],
+  "scalarTypes": {
+    "integer": { "zod": "fields.id", "note": "Use fields.id for ids; z.number() for other ints" },
+    "number": { "zod": "z.number()" },
+    "string": { "zod": "fields.optionalNullableString" },
+    "boolean": { "zod": "z.boolean()" },
+    "datetime": { "zod": "fields.createdAt" }
+  },
+  "persistenceTypes": ["belongsTo", "hasMany", "hasOne", "belongsToMany"],
+  "ormTargets": ["typeorm", "prisma"],
+  "writeModes": ["syncIds", "nestedCreate", "fkOnly"],
+  "outputs": {
+    "readSchema": "{entityPascal}ReadSchema",
+    "writeSchema": "{entityPascal}WriteSchema",
+    "embedSchema": "{namePascal}EmbedSchema",
+    "relationshipsMeta": "{entityKebab}.relationships.meta.ts"
+  }
+}

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

@@ -0,0 +1,12 @@
+# portal:unit-gen
+
+Reads hub Code `ir/design.yaml` + `generated/codegen.manifest.json` (after `flowgrid gen`) → writes `tests/unit/`.
+
+```bash
+flowgrid unit-gen:dry --id W-AD-AUTH-001
+flowgrid unit-gen --id W-AD-AUTH-001
+flowgrid unit-gen --id W-AD-AUTH-001 --force
+flowgrid unit-gen --spec /path/to/docs-hub/surfaces/.../CMP-01-auth/.../ir/design.yaml
+```
+
+Form/create pages (`profile: create|auth|change-password|public`) generate tests against `src/services/{entity}Form.service.ts` (`create{Entity}FormService`), not the list service. List-column model tests are not emitted for those profiles.

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

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { readdir, stat } from 'node:fs/promises'
+
+import { readSpecFile, requireDesignIrPath } from '../../codegen/runners/lib/read-spec.mjs'
+import { buildUnitContext, buildUnitFilePlan, collectPlannedPatternTags } from './lib/plan.mjs'
+import { readCodegenManifest } from './lib/read-codegen.mjs'
+import { renderTemplate } from './lib/render.mjs'
+import { loadUnitTestRegistry, REGISTRY_REL } from './lib/unit-registry.mjs'
+import {
+  renderUnitHandoffMarkdown,
+  writeOutputs,
+  writeUnitMeta
+} from './lib/write-files.mjs'
+import { writeSpecTags } from './lib/write-spec-tags.mjs'
+import { resolveHubId, resolveProjectRoot } from '../../codegen/runners/lib/resolve-hub-id.mjs'
+
+const root = path.resolve(process.env.FLOWGRID_PROJECT_ROOT || process.env.FLOWGRID_PROJECT_ROOT || process.cwd())
+
+function parseArgs(argv) {
+  const options = { dryRun: false, force: false, spec: null, id: null, phase: 'prototype', writeSpecTags: false }
+
+  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 === '--write-spec-tags') options.writeSpecTags = true
+    else if (arg === '--phase') options.phase = argv[++i] ?? 'prototype'
+    else if (arg === '--spec') options.spec = argv[++i]
+    else if (arg === '--id') options.id = argv[++i]
+    else if (!arg.startsWith('-') && !options.spec && !options.id) options.spec = arg
+  }
+
+  if (!options.spec && !options.id) {
+    throw new Error(
+      'Usage: flowgrid unit-gen --id W-AD-AUTH-001 [--dry-run] [--force] [--phase prototype|wire]\n' +
+        '       flowgrid unit-gen --spec <path-to-ir/design.yaml> …',
+    )
+  }
+
+  return options
+}
+
+/** @param {{ tag: string, reason: string }[]} items */
+function dedupeNeedsUnit(items) {
+  const seen = new Set()
+  return items.filter((item) => {
+    if (seen.has(item.tag)) return false
+    seen.add(item.tag)
+    return true
+  })
+}
+
+async function listIrSpecFiles(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 listIrSpecFiles(entryPath)))
+      continue
+    }
+    if (entry.isFile() && entry.name === 'design.yaml' && entryPath.includes(`${path.sep}code${path.sep}`) && entryPath.includes(`${path.sep}ir${path.sep}`)) {
+      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-unit-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 listIrSpecFiles(path.resolve(options.spec))
+      if (!discovered.length) {
+        throw new Error(`--spec ${options.spec}: directory has no ir/design.yaml files`)
+      }
+      return discovered
+    }
+    return [requireDesignIrPath(path.resolve(options.spec))]
+  }
+  return []
+}
+
+async function generateOneUnit(specPath, registry, options) {
+  const { spec, specFile, featureDir } = await readSpecFile(specPath)
+  const { manifest: codegenManifest } = await readCodegenManifest(featureDir)
+
+  const ctx = buildUnitContext(spec, specFile, codegenManifest, { phase: options.phase })
+  const { files, needsUnit, skippedPatterns } = await buildUnitFilePlan(ctx, registry, root)
+  const plannedTags = collectPlannedPatternTags(ctx, registry)
+
+  const allNeedsUnit = dedupeNeedsUnit([...needsUnit, ...plannedTags])
+
+  const outputs = []
+  for (const file of files) {
+    const templateContext = {
+      ...ctx,
+      validRowJson: JSON.stringify(ctx.validRow, null, 2),
+      validFormValuesJson: JSON.stringify(ctx.validFormValues ?? {}, null, 2)
+    }
+    const content = await renderTemplate(file.template, templateContext)
+    outputs.push({ layer: file.layer, relativePath: file.relativePath, content, patternId: file.patternId })
+  }
+
+  const { written, skipped } = await writeOutputs(root, outputs, {
+    dryRun: options.dryRun,
+    force: options.force
+  })
+
+  const unitManifest = {
+    generatedAt: new Date().toISOString(),
+    specFile,
+    phase: ctx.phase,
+    profile: ctx.profile,
+    entity: ctx.entity,
+    module: ctx.module,
+    codegenManifest: 'generated/codegen.manifest.json',
+    unitRegistry: REGISTRY_REL,
+    files: files.map((f) => ({
+      layer: f.layer,
+      path: f.relativePath,
+      pattern: f.patternId,
+      reqIds: f.reqIds
+    })),
+    written: written.map((w) => w.relativePath),
+    skipped: skipped.map((s) => ({ path: s.relativePath, reason: s.reason })),
+    skippedPatterns,
+    needsUnit: allNeedsUnit
+  }
+
+  const handoff = renderUnitHandoffMarkdown(ctx, written, skipped, allNeedsUnit)
+  const meta = await writeUnitMeta(featureDir, unitManifest, handoff, { dryRun: options.dryRun })
+
+  if (options.writeSpecTags && !options.dryRun) {
+    const specAbsolute = path.resolve(root, specFile)
+    const tagResult = await writeSpecTags(specAbsolute, allNeedsUnit)
+    if (tagResult.changed) {
+      for (const tag of tagResult.added) {
+        console.log(`  spec-tag: ${tag}`)
+      }
+    }
+  }
+
+  console.log(`portal-unit-gen: profile=${ctx.profile} entity=${ctx.entity} phase=${ctx.phase}`)
+  console.log(`  spec: ${specFile}`)
+  if (options.dryRun) console.log('  mode: dry-run')
+
+  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})`)
+  }
+  for (const item of allNeedsUnit) {
+    console.log(`  needs-unit: ${item.tag}`)
+  }
+  if (!options.dryRun && meta.manifestPath) {
+    console.log(`  manifest: ${path.relative(root, meta.manifestPath)}`)
+    console.log(`  handoff: ${path.relative(root, meta.handoffPath)}`)
+  }
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2))
+  const specPaths = await resolveSpecPaths(options)
+  const { registry } = await loadUnitTestRegistry(root)
+  let failed = 0
+  for (const specPath of specPaths) {
+    try {
+      await generateOneUnit(specPath, registry, options)
+      if (specPaths.length > 1) console.log('')
+    } catch (e) {
+      failed++
+      console.error(`portal-unit-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/unitgen/runners/lib/parse-tags.mjs

@@ -0,0 +1,67 @@
+const TAG_PREFIX = {
+  genTest: '#gen:test-',
+  needsUnit: '#needs-unit-test:',
+  skipUnit: '#skip-unit-test:',
+  testMock: '#test-mock:'
+}
+
+/** @param {string[]} tags */
+export function parseUnitTags(tags = []) {
+  const parsed = {
+    gen: new Set(),
+    skip: new Set(),
+    needs: [],
+    mocks: [],
+    raw: tags
+  }
+
+  for (const tag of tags) {
+    const text = String(tag).trim()
+    if (text.startsWith(TAG_PREFIX.genTest)) {
+      parsed.gen.add(text.slice(TAG_PREFIX.genTest.length).trim())
+    } else if (text.startsWith(TAG_PREFIX.skipUnit)) {
+      parsed.skip.add(text.slice(TAG_PREFIX.skipUnit.length).trim().toLowerCase())
+    } else if (text.startsWith(TAG_PREFIX.needsUnit)) {
+      parsed.needs.push(text)
+    } else if (text.startsWith(TAG_PREFIX.testMock)) {
+      parsed.mocks.push(text.slice(TAG_PREFIX.testMock.length).trim())
+    }
+  }
+
+  return parsed
+}
+
+const LAYER_SKIP_ALIASES = {
+  hook: ['composable', 'composable-list', 'composable-form'],
+  composable: ['hook'],
+  schema: ['models'],
+  models: ['schema']
+}
+
+/**
+ * @param {import('./parse-tags.mjs').ReturnType<typeof parseUnitTags>} unitTags
+ * @param {string} layer e.g. models, schema
+ */
+export function isLayerSkipped(unitTags, layer) {
+  const key = layer.toLowerCase()
+  if (unitTags.skip.has(key) || unitTags.skip.has('all')) return true
+  const aliases = LAYER_SKIP_ALIASES[key] ?? []
+  return aliases.some((alias) => unitTags.skip.has(alias))
+}
+
+const GEN_TAG_ALIASES = {
+  hook: ['composable', 'composable-list', 'composable-form'],
+  composable: ['hook'],
+  'composable-list': ['hook'],
+  'composable-form': ['hook']
+}
+
+/**
+ * @param {import('./parse-tags.mjs').ReturnType<typeof parseUnitTags>} unitTags
+ * @param {string} genKey e.g. schema
+ */
+export function hasExplicitGenTag(unitTags, genKey) {
+  if (unitTags.gen.has(genKey)) return true
+  const aliases = GEN_TAG_ALIASES[genKey] ?? []
+  return aliases.some((alias) => unitTags.gen.has(alias))
+}