@shanyucoder/flowgrid 0.1.0

package/engines/openapi/gen-openapi.mjs

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+/**
+ * One OpenAPI 3.0.3 generator for the docs hub.
+ * Input: 01-backend-spec.yaml → sibling 02-openapi.yaml
+ * Bundle/UI remain: openapi:render (merge) + Redocly bundle.
+ */
+import { existsSync } from 'node:fs'
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parse, stringify } from 'yaml'
+
+const SCALAR = {
+  integer: 'integer',
+  int: 'integer',
+  number: 'number',
+  float: 'number',
+  boolean: 'boolean',
+  datetime: 'string',
+  date: 'string',
+  string: 'string',
+  text: 'string',
+}
+
+const ERROR_RESPONSE_REF = {
+  '#err:unauthorized': 'UnauthorizedError',
+  '#err:permission-denied': 'PermissionError',
+  '#err:idor-violation': 'IdorViolationError',
+  '#err:not-found': 'NotFoundError',
+  '#err:validation': 'ValidationError',
+  '#err:system': 'ServerError',
+  '#err:conflict': 'ConflictError',
+  '#err:maintenance': 'ServerError',
+}
+
+function schemaFromFields(fields = []) {
+  const properties = {}
+  const required = []
+  for (const field of fields) {
+    const name = field.name ?? field.key
+    if (!name) continue
+    properties[name] = { type: SCALAR[field.type] ?? 'string' }
+    if (field.readOnly) properties[name].readOnly = true
+    if (field.nullable) properties[name].nullable = true
+    if (field.required === true) required.push(name)
+  }
+  return {
+    type: 'object',
+    properties,
+    ...(required.length ? { required } : {}),
+  }
+}
+
+function collectEntitySchemas(spec) {
+  const schemas = {}
+  for (const mod of spec.modules ?? []) {
+    for (const entity of mod.entities ?? []) {
+      const name = entity.name
+      if (!name) continue
+      schemas[name] = schemaFromFields(entity.fields)
+    }
+  }
+  for (const [name, def] of Object.entries(spec.requests ?? {})) {
+    schemas[name] = schemaFromFields(def.fields)
+  }
+  for (const [name, def] of Object.entries(spec.responses ?? {})) {
+    if (def?.envelope) {
+      const itemRef = String(def.data ?? '').match(/of\s+(\w+)/)?.[1]
+      schemas[name] = {
+        type: 'object',
+        properties: {
+          data: itemRef
+            ? { type: 'array', items: { $ref: `#/components/schemas/${itemRef}` } }
+            : { type: 'array', items: { type: 'object' } },
+          meta: { type: 'object' },
+        },
+      }
+      continue
+    }
+    if (def?.fields) schemas[name] = schemaFromFields(def.fields)
+  }
+  return schemas
+}
+
+function ensureCollectionSchema(schemas, responseName) {
+  if (!responseName || schemas[responseName]) return
+  const entity = String(responseName).replace(/Collection$/, '')
+  if (entity && entity !== responseName && schemas[entity]) {
+    schemas[responseName] = {
+      type: 'object',
+      properties: {
+        data: { type: 'array', items: { $ref: `#/components/schemas/${entity}` } },
+      },
+    }
+  }
+}
+
+function responseSchemaRef(responseName, schemas) {
+  if (!responseName) return { type: 'object' }
+  ensureCollectionSchema(schemas, responseName)
+  if (schemas[responseName]) return { $ref: `#/components/schemas/${responseName}` }
+  return { type: 'object' }
+}
+
+function errorResponses(endpoint) {
+  const responses = {}
+  for (const row of endpoint.errorStorming ?? []) {
+    const tag = String(row.tag ?? '')
+    const name = ERROR_RESPONSE_REF[tag]
+    const code = String(row.code ?? '')
+    if (!code) continue
+    responses[code] = name
+      ? { $ref: `#/components/responses/${name}` }
+      : { description: row.reason ?? tag ?? 'Error' }
+  }
+  return responses
+}
+
+function standardComponents() {
+  return {
+    UnauthorizedError: {
+      description: 'Unauthorized (#err:unauthorized)',
+      content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
+    },
+    PermissionError: {
+      description: 'Forbidden (#err:permission-denied)',
+      content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
+    },
+    IdorViolationError: {
+      description: 'Forbidden (#err:idor-violation)',
+      content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
+    },
+    NotFoundError: {
+      description: 'Not Found (#err:not-found)',
+      content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
+    },
+    ValidationError: {
+      description: 'Validation failed (#err:validation)',
+      content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
+    },
+    ServerError: {
+      description: 'Server error (#err:system)',
+      content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
+    },
+    ConflictError: {
+      description: 'Conflict (#err:conflict)',
+      content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
+    },
+  }
+}
+
+export function buildOpenApiFromBackendSpec(spec) {
+  const schemas = collectEntitySchemas(spec)
+  schemas.ErrorResponse ??= {
+    type: 'object',
+    required: ['code', 'message'],
+    properties: { code: { type: 'string' }, message: { type: 'string' } },
+  }
+
+  const paths = {}
+  const tagNames = new Set()
+
+  for (const endpoint of spec.api?.endpoints ?? []) {
+    const pathKey = endpoint.path ?? '/'
+    const method = String(endpoint.method ?? 'GET').toLowerCase()
+    const tag = endpoint.module ?? spec.codegen?.module ?? 'API'
+    tagNames.add(tag)
+
+    const operation = {
+      operationId: endpoint.id ?? `${spec.codegen?.entity ?? 'op'}.${endpoint.action ?? 'custom'}`,
+      tags: [tag],
+      summary: endpoint.purpose ?? `${endpoint.action ?? method} ${pathKey}`,
+      responses: {
+        '200': {
+          description: 'OK',
+          content: {
+            'application/json': {
+              schema: responseSchemaRef(endpoint.response, schemas),
+            },
+          },
+        },
+        ...errorResponses(endpoint),
+      },
+    }
+
+    if (method === 'get') {
+      const filters = endpoint.query?.filters ?? []
+      const parameters = []
+      if (endpoint.query?.pagination) {
+        parameters.push(
+          { name: 'page', in: 'query', schema: { type: 'integer' } },
+          { name: 'perPage', in: 'query', schema: { type: 'integer' } },
+        )
+      }
+      for (const filter of filters) {
+        const name = typeof filter === 'string' ? filter : filter.name
+        if (name) parameters.push({ name, in: 'query', schema: { type: 'string' } })
+      }
+      if (parameters.length) operation.parameters = parameters
+    } else if (['post', 'patch', 'put'].includes(method) && endpoint.request) {
+      ensureCollectionSchema(schemas, endpoint.request)
+      operation.requestBody = {
+        required: true,
+        content: {
+          'application/json': {
+            schema: schemas[endpoint.request]
+              ? { $ref: `#/components/schemas/${endpoint.request}` }
+              : { type: 'object' },
+          },
+        },
+      }
+    }
+
+    paths[pathKey] = paths[pathKey] ?? {}
+    paths[pathKey][method] = operation
+  }
+
+  const title = spec.feature?.title ?? `${spec.codegen?.module ?? 'API'}`
+  return {
+    openapi: '3.0.3',
+    info: {
+      title,
+      version: spec.feature?.version ?? '0.1.0',
+      description: 'Generated by `flowgrid openapi:gen` from 01-backend-spec.yaml.',
+    },
+    servers: [{ url: process.env.OPENAPI_SERVER_URL || 'http://localhost', description: 'Local API' }],
+    tags: [...tagNames].map((name) => ({ name })),
+    paths,
+    components: {
+      securitySchemes: {
+        bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
+      },
+      responses: standardComponents(),
+      schemas,
+    },
+    security: [{ bearerAuth: [] }],
+    ...(spec.i18n ? { 'x-i18n': spec.i18n } : {}),
+  }
+}
+
+function parseArgs(argv) {
+  const options = { spec: null, dryRun: false, force: 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 === '--spec') options.spec = argv[++i]
+    else if (!arg.startsWith('-') && !options.spec) options.spec = arg
+  }
+  return options
+}
+
+export async function listBackendSpecs(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.startsWith('_')) continue
+      files.push(...(await listBackendSpecs(entryPath)))
+      continue
+    }
+    if (entry.isFile() && entry.name === '01-backend-spec.yaml') files.push(entryPath)
+  }
+  return files.sort()
+}
+
+async function resolveSpecFiles(options, cwd) {
+  if (options.spec) {
+    const abs = path.resolve(cwd, options.spec)
+    const st = existsSync(abs) ? await stat(abs) : null
+    if (!st) throw new Error(`Not found: ${abs}`)
+    if (st.isDirectory()) {
+      const found = await listBackendSpecs(abs)
+      if (!found.length) throw new Error(`No 01-backend-spec.yaml under ${abs}`)
+      return found
+    }
+    if (path.basename(abs) !== '01-backend-spec.yaml') {
+      throw new Error(`Expected 01-backend-spec.yaml, got ${abs}`)
+    }
+    return [abs]
+  }
+  const surfaces = path.join(cwd, 'surfaces')
+  const found = await listBackendSpecs(surfaces)
+  if (!found.length) {
+    throw new Error('No 01-backend-spec.yaml under surfaces. Pass --spec <path>.')
+  }
+  return found
+}
+
+export async function generateOpenApiFiles(options, cwd = process.cwd()) {
+  const specs = await resolveSpecFiles(options, cwd)
+  const written = []
+  for (const specPath of specs) {
+    const spec = parse(await readFile(specPath, 'utf8')) ?? {}
+    const document = buildOpenApiFromBackendSpec(spec)
+    const yamlContent = stringify(document)
+    const outputPath = path.join(path.dirname(specPath), '02-openapi.yaml')
+    if (options.dryRun) {
+      console.log(`[dry] ${path.relative(cwd, specPath)} → ${path.relative(cwd, outputPath)}`)
+      written.push(outputPath)
+      continue
+    }
+    if (existsSync(outputPath) && !options.force) {
+      const existing = await readFile(outputPath, 'utf8')
+      if (existing.trim() !== yamlContent.trim()) {
+        throw new Error(
+          `Refusing to overwrite ${path.relative(cwd, outputPath)}. Use --force after reviewing.`,
+        )
+      }
+      console.log(`skip: ${path.relative(cwd, outputPath)} (unchanged)`)
+      continue
+    }
+    await mkdir(path.dirname(outputPath), { recursive: true })
+    await writeFile(outputPath, yamlContent, 'utf8')
+    console.log(`write: ${path.relative(cwd, outputPath)}`)
+    written.push(outputPath)
+  }
+  return written
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2))
+  await generateOpenApiFiles(options, process.cwd())
+}
+
+if (path.resolve(process.argv[1] ?? '') === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(error.message ?? error)
+    process.exit(1)
+  })
+}

package/engines/openapi/render-backend-spec.mjs

@@ -0,0 +1,170 @@
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { parse } from 'yaml'
+import { MD_NONE } from './lib/markdown-table.mjs'
+import {
+  renderBackendSpecMarkdown,
+  renderCommonSpecMarkdown
+} from './lib/render-backend-spec-markdown.mjs'
+
+const projectRoot = process.cwd()
+const docsDir = path.join(projectRoot, 'docs')
+const surfacesDir = path.join(projectRoot, 'surfaces')
+const featuresDir = path.join(docsDir, 'features')
+
+export { renderFeatureBackendSpec, listBackendSpecFiles }
+
+async function main() {
+  const started = Date.now()
+  let backendSpecs = await listBackendSpecFiles(surfacesDir)
+  if (!backendSpecs.length) {
+    backendSpecs = await listBackendSpecFiles(featuresDir)
+  }
+  const commonSpecs = await listCommonSpecFiles(path.join(featuresDir, 'common'))
+
+  if (!backendSpecs.length && !commonSpecs.length) {
+    console.error('docs:render: no 01-backend-spec.yaml or features/common/*.yaml found')
+    process.exit(1)
+  }
+
+  let failed = 0
+
+  for (const specFile of backendSpecs) {
+    try {
+      await renderFeatureBackendSpec(specFile)
+    } catch (error) {
+      failed++
+      console.error(
+        `docs:render: FAIL ${path.relative(projectRoot, specFile)}: ${error.message ?? error}`
+      )
+    }
+  }
+
+  for (const specFile of commonSpecs) {
+    try {
+      await renderCommonSpec(specFile)
+    } catch (error) {
+      failed++
+      console.error(
+        `docs:render: FAIL ${path.relative(projectRoot, specFile)}: ${error.message ?? error}`
+      )
+    }
+  }
+
+  if (failed > 0) {
+    console.error(`docs:render: aborted index — ${failed} file(s) failed`)
+    process.exit(1)
+  }
+
+  await renderFeatureIndex(backendSpecs, commonSpecs)
+
+  const elapsed = ((Date.now() - started) / 1000).toFixed(1)
+  console.log(
+    `docs:render: ${backendSpecs.length} backend spec(s), ${commonSpecs.length} common spec(s) [${elapsed}s]`
+  )
+}
+
+async function renderFeatureBackendSpec(specFile) {
+  const featureDir = path.dirname(specFile)
+  const spec = await readYaml(specFile)
+  const slug = featureDir.replace(featuresDir + path.sep, '').split(path.sep).pop() ?? 'feature'
+  const generatedDir = path.join(featureDir, 'generated')
+  await mkdir(generatedDir, { recursive: true })
+
+  const markdown = renderBackendSpecMarkdown(spec, {
+    specFile: path.relative(projectRoot, specFile),
+    slug
+  })
+
+  await writeFile(path.join(generatedDir, 'backend-spec.md'), markdown, 'utf8')
+}
+
+async function renderCommonSpec(specFile) {
+  const spec = await readYaml(specFile)
+  const slug = path.basename(specFile, path.extname(specFile))
+  const generatedDir = path.join(path.dirname(specFile), 'generated')
+  await mkdir(generatedDir, { recursive: true })
+
+  const markdown = renderCommonSpecMarkdown(spec, {
+    specFile: path.relative(projectRoot, specFile),
+    slug
+  })
+
+  await writeFile(path.join(generatedDir, `${slug}.md`), markdown, 'utf8')
+}
+
+async function renderFeatureIndex(backendSpecs, commonSpecs) {
+  const rows = []
+
+  for (const specFile of commonSpecs) {
+    const spec = await readYaml(specFile)
+    const slug = path.basename(specFile, path.extname(specFile))
+    const link = vitepressLink(path.join(path.dirname(specFile), 'generated', `${slug}.md`))
+    rows.push(`- [${spec.title ?? slug}](${link})`)
+  }
+
+  for (const specFile of backendSpecs) {
+    const spec = await readYaml(specFile)
+    const title = spec.feature?.title ?? path.basename(path.dirname(specFile))
+    const link = vitepressLink(path.join(path.dirname(specFile), 'generated', 'backend-spec.md'))
+    rows.push(`- [${title}](${link})`)
+  }
+
+  const apiBaseDir = path.join(docsDir, 'api-base')
+  await mkdir(apiBaseDir, { recursive: true })
+
+  await writeFile(
+    path.join(apiBaseDir, 'generated.md'),
+    `# Generated backend contracts\n\n${rows.join('\n') || MD_NONE}\n`,
+    'utf8'
+  )
+}
+
+function vitepressLink(file) {
+  const relativePath = path.relative(docsDir, file).split(path.sep).join('/')
+  return `/${relativePath.replace(/\.md$/, '')}`
+}
+
+async function readYaml(file) {
+  return parse(await readFile(file, 'utf8')) ?? {}
+}
+
+async function listBackendSpecFiles(dir) {
+  const files = []
+  for (const entry of await listEntries(dir)) {
+    const entryPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (entry.name === 'common') continue
+      files.push(...(await listBackendSpecFiles(entryPath)))
+      continue
+    }
+    if (entry.isFile() && entry.name === '01-backend-spec.yaml') {
+      files.push(entryPath)
+    }
+  }
+  return files.sort()
+}
+
+async function listCommonSpecFiles(dir) {
+  const files = []
+  for (const entry of await listEntries(dir)) {
+    if (!entry.isFile() || !entry.name.endsWith('.yaml')) continue
+    files.push(path.join(dir, entry.name))
+  }
+  return files.sort()
+}
+
+async function listEntries(dir) {
+  try {
+    return await readdir(dir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+}
+
+if (process.argv[1] && process.argv[1].endsWith('render-backend-spec.mjs')) {
+  main().catch((error) => {
+    console.error(error)
+    process.exit(1)
+  })
+}

package/engines/openapi/render-openapi.mjs

@@ -0,0 +1,155 @@
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { parse, stringify } from 'yaml'
+import { spawnSync } from 'node:child_process'
+
+const projectRoot = process.cwd()
+const docsDir = path.join(projectRoot, 'docs')
+const surfacesDir = path.join(projectRoot, 'surfaces')
+const featuresDir = path.join(docsDir, 'features')
+const baseFile = path.join(docsDir, 'openapi', 'base.yaml')
+const outputFile = path.join(docsDir, 'openapi', 'api.yaml')
+
+async function main() {
+  const started = Date.now()
+  const base = fsExists(baseFile) ? await readYaml(baseFile) : { openapi: '3.0.3', info: { title: 'Backend API Specifications', version: '1.0.0' } }
+  const featureFiles = await listFeatureOpenApiFiles(surfacesDir)
+  if (!featureFiles.length) {
+    featureFiles.push(...(await listFeatureOpenApiFiles(featuresDir)))
+  }
+
+  const merged = structuredClone(base)
+  merged.paths ??= {}
+  merged.components ??= {}
+  merged.components.schemas ??= {}
+  merged.components.securitySchemes ??= {}
+  merged.tags ??= []
+
+  const mergedFrom = []
+
+  for (const file of featureFiles) {
+    const fragment = await readYaml(file)
+    const rel = path.relative(projectRoot, file)
+    mergeOpenApi(merged, fragment, rel)
+    mergedFrom.push(rel)
+  }
+
+  merged.info ??= {}
+  merged.info.description = [
+    base.info?.description?.trim(),
+    '',
+    'Feature fragments merged by `pnpm openapi:render`:',
+    ...mergedFrom.map((f) => `- ${f}`)
+  ]
+    .filter(Boolean)
+    .join('\n')
+
+  await writeFile(outputFile, stringify(merged), 'utf8')
+
+  const lintEnabled = process.env.OPENAPI_LINT === '1' || process.env.OPENAPI_LINT === 'true'
+  if (lintEnabled) {
+    const lintResults = [outputFile, ...featureFiles].map((file) => lintFile(file))
+    const failed = lintResults.filter((r) => r.status !== 0 && r.status != null)
+
+    if (failed.length > 0) {
+      for (const result of failed) {
+        if (result.stdout) process.stdout.write(result.stdout)
+        if (result.stderr) process.stderr.write(result.stderr)
+      }
+      process.exit(1)
+    }
+  }
+
+  const elapsed = ((Date.now() - started) / 1000).toFixed(1)
+  console.log(
+    `openapi:render: merged ${featureFiles.length} feature file(s) → docs/openapi/api.yaml [${elapsed}s]`
+  )
+}
+
+/**
+ * @param {Record<string, unknown>} target
+ * @param {Record<string, unknown>} fragment
+ * @param {string} source
+ */
+function mergeOpenApi(target, fragment, source) {
+  for (const [route, item] of Object.entries(fragment.paths ?? {})) {
+    if (target.paths[route]) {
+      throw new Error(`Duplicate path ${route} when merging ${source}. Check if this API is already defined in common or another module!`)
+    }
+    target.paths[route] = item
+  }
+
+  for (const [name, schema] of Object.entries(fragment.components?.schemas ?? {})) {
+    if (target.components.schemas[name]) {
+      throw new Error(`Duplicate schema ${name} when merging ${source}`)
+    }
+    target.components.schemas[name] = schema
+  }
+
+  for (const [name, scheme] of Object.entries(fragment.components?.securitySchemes ?? {})) {
+    if (target.components.securitySchemes[name]) {
+      throw new Error(`Duplicate securityScheme ${name} when merging ${source}`)
+    }
+    target.components.securitySchemes[name] = scheme
+  }
+
+  const existingTags = new Set((target.tags ?? []).map((t) => t.name))
+  for (const tag of fragment.tags ?? []) {
+    if (!existingTags.has(tag.name)) {
+      target.tags.push(tag)
+      existingTags.add(tag.name)
+    }
+  }
+}
+
+function lintFile(file) {
+  const rel = path.relative(projectRoot, file)
+  return spawnSync('pnpm', ['exec', 'redocly', 'lint', rel], {
+    cwd: projectRoot,
+    encoding: 'utf8',
+    env: { ...process.env, REDOCLY_TELEMETRY: 'off' },
+    timeout: 60_000,
+  })
+}
+
+function fsExists(file) {
+  try {
+    return existsSync(file)
+  } catch {
+    return false
+  }
+}
+
+async function readYaml(file) {
+  return parse(await readFile(file, 'utf8')) ?? {}
+}
+
+async function listFeatureOpenApiFiles(dir) {
+  const files = []
+  for (const entry of await listEntries(dir)) {
+    const entryPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (entry.name.startsWith('_')) continue
+      files.push(...(await listFeatureOpenApiFiles(entryPath)))
+      continue
+    }
+    if (entry.isFile() && entry.name === '02-openapi.yaml') {
+      files.push(entryPath)
+    }
+  }
+  return files.sort()
+}
+
+async function listEntries(dir) {
+  try {
+    return await readdir(dir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+}
+
+main().catch((error) => {
+  console.error(error.message ?? error)
+  process.exit(1)
+})

package/engines/shared/flowgrid-tests-docs.mjs

@@ -0,0 +1,32 @@
+import path from 'node:path';
+
+/** Tests hub (TC YAML, scenarios, suites) — not Playwright code. */
+export const ENV_TESTS_DOC = 'FLOWGRID_TESTS_DOC';
+
+/**
+ * @param {string | null | undefined} [override]
+ * @returns {string | null}
+ */
+export function resolveTestsDocsRoot(override) {
+  if (override) return path.resolve(override);
+  const fromEnv = process.env[ENV_TESTS_DOC];
+  return fromEnv ? path.resolve(fromEnv) : null;
+}
+
+/**
+ * Strip `--tests-docs <path>` from argv (for engines that should not see the flag).
+ * @param {string[]} argv
+ * @returns {{ argv: string[]; testsDocs: string | null }}
+ */
+export function extractTestsDocsFlag(argv) {
+  const out = [];
+  let testsDocs = null;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--tests-docs' && argv[i + 1]) {
+      testsDocs = path.resolve(process.cwd(), argv[++i]);
+      continue;
+    }
+    out.push(argv[i]);
+  }
+  return { argv: out, testsDocs };
+}