@shanyucoder/flowgrid 0.1.0

package/adapters/nuxt4/unitgen/runners/lib/write-files.mjs

@@ -0,0 +1,103 @@
+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 writeUnitMeta(featureDir, manifest, handoffMarkdown, options = {}) {
+  const generatedDir = path.join(featureDir, 'generated')
+  const manifestPath = path.join(generatedDir, 'unit.manifest.json')
+  const handoffPath = path.join(generatedDir, 'UNIT-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 renderUnitHandoffMarkdown(ctx, written, skipped, needsUnit) {
+  const lines = [
+    `# UNIT HANDOFF — ${ctx.title}`,
+    '',
+    `Generated from \`${ctx.specFile}\` (profile: **${ctx.profile}**, phase: **${ctx.phase}**).`,
+    '',
+    'Prerequisite: `flowgrid gen` + `generated/codegen.manifest.json`.',
+    '',
+    '## Test 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}`), '']
+      : []),
+    '## Verify',
+    '',
+    '```bash',
+    `pnpm exec vitest run ${written[0]?.relativePath ?? skipped[0]?.relativePath ?? 'tests/unit/'}`,
+    '```',
+    ''
+  ]
+
+  if (needsUnit.length) {
+    lines.push('## Unit next — #needs-unit-test', '')
+    for (const item of needsUnit) {
+      lines.push(`- \`${item.tag}\` — ${item.reason}`)
+    }
+    lines.push('')
+  }
+
+  if (!written.length && skipped.length) {
+    lines.push('## Note', '')
+    lines.push('No new files — existing tests kept. Re-run with `--force` to overwrite.', '')
+  }
+
+  return lines.join('\n')
+}

package/adapters/nuxt4/unitgen/runners/lib/write-spec-tags.mjs

@@ -0,0 +1,37 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import { parse, stringify } from 'yaml'
+
+/**
+ * Merge `#needs-unit-test:*` from unit-gen manifest into spec `tags:` (idempotent).
+ * @param {string} specFile absolute path
+ * @param {{ tag: string }[]} needsUnit
+ */
+export async function writeSpecTags(specFile, needsUnit = []) {
+  const tagsToAdd = needsUnit
+    .map((item) => item.tag)
+    .filter((tag) => typeof tag === 'string' && tag.startsWith('#needs-unit-test:'))
+
+  if (!tagsToAdd.length) {
+    return { added: [], changed: false }
+  }
+
+  const raw = await readFile(specFile, 'utf8')
+  const spec = parse(raw) ?? {}
+  const existing = new Set((spec.tags ?? []).map((tag) => String(tag).trim()))
+  const added = []
+
+  for (const tag of tagsToAdd) {
+    if (!existing.has(tag)) {
+      existing.add(tag)
+      added.push(tag)
+    }
+  }
+
+  if (!added.length) {
+    return { added: [], changed: false }
+  }
+
+  spec.tags = [...existing]
+  await writeFile(specFile, stringify(spec, { lineWidth: 0 }))
+  return { added, changed: true }
+}

package/adapters/nuxt4/unitgen/runners/validate-registry.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import path from 'node:path'
+import { access } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+
+import { loadUnitTestRegistry, REGISTRY_REL } from './lib/unit-registry.mjs'
+import { getTemplatesRoot } from './lib/render.mjs'
+
+const root = path.resolve(process.env.FLOWGRID_PROJECT_ROOT || process.env.FLOWGRID_PROJECT_ROOT || process.cwd())
+
+async function pathExists(relativePath) {
+  try {
+    await access(path.join(root, relativePath))
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function main() {
+  const { registry } = await loadUnitTestRegistry(root)
+  const errors = []
+  const warnings = []
+
+  console.log(`portal-unit-test.registry v${registry.version}`)
+  console.log(`  path: ${REGISTRY_REL}`)
+  console.log(`  patterns: ${Object.keys(registry.patterns ?? {}).join(', ')}`)
+
+  for (const [id, pattern] of Object.entries(registry.patterns ?? {})) {
+    if (!pattern.template) {
+      errors.push(`pattern ${id}: missing template`)
+      continue
+    }
+
+    const templatePath = path.join(getTemplatesRoot(), pattern.template)
+    const relTemplate = path.relative(root, templatePath)
+    const exists = await pathExists(path.relative(root, templatePath))
+
+    if (pattern.status === 'implemented' && !exists) {
+      errors.push(`pattern ${id}: missing template ${relTemplate}`)
+    }
+    if (pattern.status === 'planned' && !exists) {
+      warnings.push(`pattern ${id}: planned — template ${relTemplate} not found yet`)
+    }
+    if (!pattern.output && pattern.status === 'implemented') {
+      errors.push(`pattern ${id}: missing output path pattern`)
+    }
+  }
+
+  for (const [name, relPath] of Object.entries(registry.fixtures ?? {})) {
+    const exists = await pathExists(relPath)
+    if (!exists) {
+      errors.push(`fixture ${name}: missing ${relPath}`)
+    }
+  }
+
+  for (const warning of warnings) {
+    console.warn(`  warn: ${warning}`)
+  }
+
+  if (errors.length) {
+    for (const error of errors) {
+      console.error(`  error: ${error}`)
+    }
+    process.exit(1)
+  }
+
+  console.log('portal:unit-registry OK')
+}
+
+main().catch((error) => {
+  console.error(error.message ?? error)
+  process.exit(1)
+})

package/adapters/nuxt4/unitgen/templates/composables/use-form.test.ts.hbs

@@ -0,0 +1,56 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+
+import { mockNuxtApiFetch } from '~/tests/unit/_helpers/nuxtGlobals'
+
+const mockCreate = vi.fn()
+const mockPush = vi.fn()
+
+vi.mock('~/mocks/{{entity}}.mock', () => ({
+  {{entityCamel}}MockCreate: (...args: unknown[]) => mockCreate(...args)
+}))
+
+vi.stubGlobal('useRouter', () => ({ push: mockPush }))
+
+vi.mock('~/composables/forms/useApiForm', () => ({
+  useApiForm: <T extends Record<string, unknown>>(options: {
+    initialValues: T
+    submit: (values: T) => Promise<void>
+  }) => ({
+    onSubmit: async () => {
+      await options.submit({{{validFormValuesJson}}} as T)
+    },
+    errors: {},
+    apiError: { value: null },
+    isSubmitting: { value: false }
+  })
+}))
+
+import { use{{entityPascal}}Form } from '~/composables/{{entity}}/use{{entityPascal}}Form'
+
+describe('composables/{{entity}}/use{{entityPascal}}Form', () => {
+  const validForm = {{{validFormValuesJson}}} as const
+
+  beforeEach(() => {
+    mockCreate.mockReset()
+    mockPush.mockReset()
+    mockNuxtApiFetch.mockReset()
+    mockCreate.mockResolvedValue({ id: 1, ...validForm })
+  })
+
+  it('exposes empty initialValues for form fields', () => {
+    const { initialValues } = use{{entityPascal}}Form()
+
+{{#each formFields}}
+    expect(initialValues.{{key}}).toBe({{#if (eq type 'number')}}0{{else}}''{{/if}})
+{{/each}}
+  })
+
+  it('onSubmit calls prototype mock create and navigates to list', async () => {
+    const { onSubmit } = use{{entityPascal}}Form()
+
+    await onSubmit()
+
+    expect(mockCreate).toHaveBeenCalledWith(validForm)
+    expect(mockPush).toHaveBeenCalledWith('{{listRoutePath}}')
+  })
+})

package/adapters/nuxt4/unitgen/templates/composables/use-list.test.ts.hbs

@@ -0,0 +1,59 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+
+import { mockNuxtApiFetch } from '~/tests/unit/_helpers/nuxtGlobals'
+
+const mockSearch = vi.fn()
+
+vi.mock('~/mocks/{{entity}}.mock', () => ({
+  {{entityCamel}}MockSearch: (...args: unknown[]) => mockSearch(...args)
+}))
+
+import { use{{entityPascal}}List } from '~/composables/{{entity}}/use{{entityPascal}}List'
+
+describe('composables/{{entity}}/use{{entityPascal}}List', () => {
+  const validRow = {{{validRowJson}}} as const
+
+  beforeEach(() => {
+    mockSearch.mockReset()
+    mockNuxtApiFetch.mockReset()
+    mockSearch.mockResolvedValue({ items: [validRow], total: 1 })
+  })
+
+  it('load() fills items and total from prototype mock search', async () => {
+    const { load, items, total, pending } = use{{entityPascal}}List()
+
+    await load()
+
+    expect(mockSearch).toHaveBeenCalled()
+    expect(items.value).toHaveLength(1)
+    expect(items.value[0]).toEqual(validRow)
+    expect(total.value).toBe(1)
+    expect(pending.value).toBe(false)
+  })
+
+  it('onReset() restores default per_page and reloads', async () => {
+    const { onReset, query } = use{{entityPascal}}List()
+
+    query.value = { per_page: 20, page: 2 }
+    await onReset()
+
+    expect(query.value).toEqual({ per_page: {{defaultPageSize}} })
+    expect(mockSearch).toHaveBeenCalled()
+  })
+{{#if hasExportBlock}}
+  it('exportOpenRateReport() calls service export with month', async () => {
+    mockNuxtApiFetch.mockResolvedValue(new Blob(['csv'], { type: 'text/csv' }))
+    const { exportOpenRateReport, exportMonth, exportPending } = use{{entityPascal}}List()
+
+    exportMonth.value = '2025-05'
+    await exportOpenRateReport()
+
+    expect(mockNuxtApiFetch).toHaveBeenCalledWith('{{exportEndpoint.path}}', {
+      method: '{{exportEndpoint.method}}',
+      body: { month: '2025-05' },
+      responseType: 'blob'
+    })
+    expect(exportPending.value).toBe(false)
+  })
+{{/if}}
+})

package/adapters/nuxt4/unitgen/templates/models/schema.test.ts.hbs

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  {{entityPascal}}Schema,
+  {{entityPascal}}ListResponseSchema
+} from '~/models/{{entity}}/{{entity}}.schema'
+
+describe('models/{{entity}}/{{entity}}.schema', () => {
+  const validRow = {{{validRowJson}}} as const
+
+  it('parses a valid row', () => {
+    expect({{entityPascal}}Schema.parse(validRow)).toEqual(validRow)
+  })
+
+  it('parses list response envelope', () => {
+    const payload = { items: [validRow], total: 1 }
+    expect({{entityPascal}}ListResponseSchema.parse(payload)).toEqual(payload)
+  })
+
+  it('rejects row missing required field', () => {
+    const { {{failField}}: _removed, ...incomplete } = validRow
+    expect(() => {{entityPascal}}Schema.parse(incomplete)).toThrow()
+  })
+})

package/adapters/nuxt4/unitgen/templates/services/service.create.test.ts.hbs

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+
+import { create{{entityPascal}}FormService } from '~/services/{{entity}}Form.service'
+import { mockApiFetch } from '~/tests/unit/_helpers/mockApiFetch'
+
+describe('services/{{entity}}Form.service create', () => {
+  const validPayload = {{{validFormValuesJson}}} as const
+  const createdRow = {
+    id: 1,
+    ...validPayload,
+    created_at: '2026-01-01T00:00:00.000Z'
+  }
+
+  it('create calls create endpoint with body and parses response', async () => {
+    const apiFetch = mockApiFetch({
+      success: true,
+      data: createdRow
+    })
+
+    const result = await create{{entityPascal}}FormService(apiFetch).create(validPayload)
+
+    expect(apiFetch).toHaveBeenCalledWith('{{createEndpoint.path}}', {
+      method: '{{createEndpoint.method}}',
+      body: validPayload
+    })
+    expect(result).toEqual(createdRow)
+  })
+})

package/adapters/nuxt4/unitgen/templates/services/service.export.test.ts.hbs

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest'
+
+import { create{{entityPascal}}Service } from '~/services/{{entity}}.service'
+import { mockApiFetch } from '~/tests/unit/_helpers/mockApiFetch'
+
+describe('services/{{entity}}.service export', () => {
+  it('exportReport calls export endpoint with blob response', async () => {
+    const blob = new Blob(['report'], { type: 'text/csv' })
+    const apiFetch = mockApiFetch(blob)
+
+    const result = await create{{entityPascal}}Service(apiFetch).exportReport({ month: '2025-05' })
+
+    expect(apiFetch).toHaveBeenCalledWith('{{exportEndpoint.path}}', {
+      method: '{{exportEndpoint.method}}',
+      body: { month: '2025-05' },
+      responseType: 'blob'
+    })
+    expect(result).toBe(blob)
+  })
+})

package/adapters/nuxt4/unitgen/templates/services/service.search.test.ts.hbs

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+
+import { create{{entityPascal}}Service } from '~/services/{{entity}}.service'
+import { mockApiFetch } from '~/tests/unit/_helpers/mockApiFetch'
+
+describe('services/{{entity}}.service', () => {
+  const validRow = {{{validRowJson}}} as const
+
+  it('search calls list endpoint and parses list envelope', async () => {
+    const apiFetch = mockApiFetch({
+      success: true,
+      data: { items: [validRow], total: 1 }
+    })
+
+    const result = await create{{entityPascal}}Service(apiFetch).search({ page: 1, per_page: 100 })
+
+    expect(apiFetch).toHaveBeenCalledWith('{{listEndpoint.path}}', {
+      method: '{{listEndpoint.method}}'{{#if (eq listEndpoint.method 'GET')}},
+      query: { page: 1, per_page: 100 }{{/if}}{{#if (eq listEndpoint.method 'POST')}},
+      body: { page: 1, per_page: 100 }{{/if}}
+    })
+    expect(result.items).toHaveLength(1)
+    expect(result.items[0]).toEqual(validRow)
+  })
+})

package/adapters/nuxt4/unitgen/templates/services/service.wire.test.ts.hbs

@@ -0,0 +1,37 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { create{{entityPascal}}Service } from '~/services/{{entity}}.service'
+import { mockApiFetch } from '~/tests/unit/_helpers/mockApiFetch'
+
+describe('services/{{entity}}.service wire', () => {
+  const validRow = {{{validRowJson}}} as const
+
+  it('search rejects API error envelope', async () => {
+    const apiFetch = mockApiFetch({ success: false, message: 'List failed' })
+
+    await expect(
+      create{{entityPascal}}Service(apiFetch).search({ page: 1 })
+    ).rejects.toThrow()
+  })
+
+  it('search parses meta.total when present', async () => {
+    const apiFetch = mockApiFetch({
+      success: true,
+      data: { items: [validRow], total: 42, meta: { total: 42 } }
+    })
+
+    const result = await create{{entityPascal}}Service(apiFetch).search({ page: 1 })
+
+    expect(result.total).toBe(42)
+    expect(result.items[0]).toEqual(validRow)
+  })
+{{#if exportEndpoint}}
+  it('exportReport propagates apiFetch rejection', async () => {
+    const apiFetch = vi.fn().mockRejectedValue(new Error('export failed'))
+
+    await expect(
+      create{{entityPascal}}Service(apiFetch).exportReport({ month: '2025-05' })
+    ).rejects.toThrow('export failed')
+  })
+{{/if}}
+})

package/adapters/nuxt4/unitgen/templates/validations/schemas.test.ts.hbs

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+
+import { {{entityCamel}}CreateObjectSchema } from '~/validations/{{entity}}/schemas'
+
+describe('validations/{{entity}}/schemas', () => {
+  const validForm = {{{validFormValuesJson}}} as const
+
+  it('parses valid create payload', () => {
+    const result = {{entityCamel}}CreateObjectSchema.safeParse(validForm)
+    expect(result.success).toBe(true)
+  })
+{{#each requiredFormFields}}
+
+  it('rejects empty required field {{key}}', () => {
+    const result = {{../entityCamel}}CreateObjectSchema.safeParse({ ...validForm, {{key}}: '' })
+    expect(result.success).toBe(false)
+  })
+{{/each}}
+})