@shanyucoder/flowgrid 0.1.0

package/engines/spec/lib/bundle-ir.mjs

@@ -0,0 +1,360 @@
+/**
+ * Split portal-feature-bundle → ir/{spec,legacy,design}.yaml
+ */
+
+import { readFile, writeFile, mkdir, unlink } from 'node:fs/promises'
+import path from 'node:path'
+import { parse, stringify } from 'yaml'
+import {
+  BUNDLE_META_KEYS,
+  DESIGN_LAYOUT_KEYS,
+  GEN_UI_KEYS,
+  TECH_IR_KEYS,
+  hasGenContent,
+  partitionSpecSection,
+  codegenProfileReady,
+  codegenEntityModuleReady,
+  endpointsActionReady,
+  missingGenTestTags,
+} from './bundle-schema.mjs'
+import { applyOpenQaField } from './open-qa.mjs'
+import { applyDesignApiFrom01 } from './hydrate-design-api.mjs'
+import { isPlaceholderLegacy, projectBusinessPage } from './project-business-layout.mjs'
+
+export function bundlePageId(bundle) {
+  const v = bundle?.['page-id'] ?? bundle?.pageId ?? bundle?.id
+  return typeof v === 'string' && v.trim() ? v.trim() : null
+}
+
+/**
+ * @param {Record<string, unknown>} bundle
+ */
+export function buildIrFromBundle(bundle) {
+  const meta = {}
+  for (const key of BUNDLE_META_KEYS) {
+    if (bundle[key] != null) meta[key] = bundle[key]
+  }
+  const { designSpec, gen } = partitionSpecSection(bundle.spec ?? {}, bundle.gen ?? {})
+  const spec = buildBusinessSpec(meta, designSpec, bundle)
+  const pageId = bundlePageId(bundle)
+  const legacy = { id: pageId, ...(bundle.legacy ?? {}) }
+  const design = buildDesignIr(bundle, designSpec, gen)
+
+  return { spec, legacy, design, designSpec, gen }
+}
+
+/** ir/spec.yaml — business prose + page inventory (no ids/tags/bind/components). */
+export function buildBusinessSpec(meta, designSpec = {}, bundle = {}) {
+  const spec = { ...meta }
+  delete spec.id
+  const pageId = bundlePageId(bundle)
+  if (pageId) spec['page-id'] = pageId
+  for (const [key, value] of Object.entries(designSpec)) {
+    if (TECH_IR_KEYS.includes(key)) continue
+    spec[key] = value
+  }
+  Object.assign(spec, projectBusinessPage(bundle.design ?? {}))
+  const i18nObj = bundle.i18n ?? bundle.design?.i18n
+  if (i18nObj) spec.i18n = i18nObj
+  if (!isPlaceholderLegacy(bundle.legacy)) spec.legacy = bundle.legacy
+  return spec
+}
+
+/**
+ * ir/design.yaml — tech SSOT for FE/BE/bộ test (layout + ui + api + entities + codegen).
+ */
+export function buildDesignIr(bundle, designSpec = {}, gen = {}) {
+  const pageId = bundlePageId(bundle)
+  const design = { id: pageId, ...(bundle.design ?? {}) }
+  if (bundle.title != null) design.title = bundle.title
+  if (bundle.i18n != null && design.i18n == null) design.i18n = bundle.i18n
+
+  if (gen.codegen != null) design.codegen = gen.codegen
+  if (gen.tags != null) design.tags = gen.tags
+
+  const ui = { ...(designSpec.ui ?? {}) }
+  if (gen.ui && typeof gen.ui === 'object') {
+    for (const [key, value] of Object.entries(gen.ui)) {
+      if (value != null) ui[key] = value
+    }
+  }
+  if (design.ui && typeof design.ui === 'object') {
+    Object.assign(ui, design.ui)
+  }
+  if (Object.keys(ui).length) design.ui = ui
+
+  if (designSpec.entities != null) design.entities = designSpec.entities
+  if (designSpec.relationships != null) design.relationships = designSpec.relationships
+
+  return design
+}
+
+function pickLayout(designIr) {
+  const out = {}
+  for (const key of DESIGN_LAYOUT_KEYS) {
+    if (designIr[key] != null) out[key] = designIr[key]
+  }
+  return out
+}
+
+function restoreComments(sourceYaml, generatedYaml) {
+  let result = generatedYaml
+  const lines = sourceYaml.split('\n')
+  
+  for (const line of lines) {
+    const match = line.match(/^([^#]+?)\s+#(.+)$/)
+    if (!match) continue
+    
+    const codePart = match[1].trimEnd()
+    const commentPart = match[2]
+    
+    const trimmedCode = codePart.trimStart()
+    if (!trimmedCode) continue 
+    
+    let safeCode = trimmedCode.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    
+    const kvMatch = trimmedCode.match(/^(-\s+)?([a-zA-Z0-9_-]+):\s*(.+)$/)
+    if (kvMatch) {
+      const prefix = kvMatch[1] || ''
+      const key = kvMatch[2]
+      let val = kvMatch[3].trim()
+      if ((val.startsWith("'") && val.endsWith("'")) || (val.startsWith('"') && val.endsWith('"'))) {
+        val = val.slice(1, -1)
+      }
+      const safePrefix = prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      const safeKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      const safeVal = val.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      safeCode = `${safePrefix}${safeKey}:\\s*['"]?${safeVal}['"]?`
+    }
+    
+    const replaceRegex = new RegExp(`(^|\\n)(\\s*${safeCode}\\s*)(?!\\s*#)(\\r?\\n|$)`, 'g')
+    result = result.replace(replaceRegex, `$1$2 #${commentPart.trim()}$3`)
+  }
+  
+  return result
+}
+
+/**
+ * @param {string} bundlePath
+ * @param {{ dryRun?: boolean }} [options]
+ */
+export async function splitBundleFile(bundlePath, options = {}) {
+  const absolute = path.resolve(bundlePath)
+  const dir = path.dirname(absolute)
+  const irDir = path.join(dir, 'ir')
+  const rawYaml = await readFile(absolute, 'utf8')
+  const bundle = parse(rawYaml) ?? {}
+
+  const pageId = bundlePageId(bundle)
+  if (!pageId) {
+    throw new Error(`Bundle missing page-id: ${bundlePath}`)
+  }
+
+  const { spec, legacy, design } = buildIrFromBundle(bundle)
+  applyOpenQaField(spec, absolute, pageId)
+  applyDesignApiFrom01(design, dir)
+  const yamlOpts = { lineWidth: 0 }
+
+  emitCodegenGates(bundle, design, { throwOnFail: true })
+
+  if (!options.dryRun) {
+    await mkdir(irDir, { recursive: true })
+    
+    const specYaml = restoreComments(
+      rawYaml, 
+      stringify(spec, yamlOpts)
+    )
+
+    await writeFile(
+      path.join(irDir, 'spec.yaml'),
+      `# Generated from ${path.basename(bundlePath)} — pnpm spec:split (business prose)\n${specYaml}`,
+      'utf8'
+    )
+    await writeFile(
+      path.join(irDir, 'design.yaml'),
+      `# Generated from ${path.basename(bundlePath)} — pnpm spec:split (tech: FE/BE/bộ test)\n${stringify(design, yamlOpts)}`,
+      'utf8'
+    )
+    try {
+      await unlink(path.join(irDir, 'legacy.yaml'))
+    } catch {
+      /* optional leftover */
+    }
+  }
+
+  return { bundlePath: absolute, irDir, spec, legacy, design }
+}
+
+/**
+ * @param {string} bundlePath
+ */
+export async function checkSplitBundle(bundlePath) {
+  const absolute = path.resolve(bundlePath)
+  const irDir = path.join(path.dirname(absolute), 'ir')
+  const rawYaml = await readFile(absolute, 'utf8')
+  const bundle = parse(rawYaml) ?? {}
+  const expected = buildIrFromBundle(bundle)
+  applyOpenQaField(expected.spec, absolute, bundlePageId(bundle))
+  applyDesignApiFrom01(expected.design, path.dirname(absolute))
+  const files = ['spec', 'design']
+  const mismatches = []
+
+  for (const name of files) {
+    const irPath = path.join(irDir, `${name}.yaml`)
+    let actual
+    try {
+      actual = parse(await readFile(irPath, 'utf8')) ?? {}
+    } catch {
+      mismatches.push(`${name}.yaml missing`)
+      continue
+    }
+    const expStr = name === 'spec' 
+      ? restoreComments(rawYaml, stringify(expected[name], { lineWidth: 0 })).trim()
+      : stringify(expected[name], { lineWidth: 0 }).trim()
+    
+    // We should also strip the first line `# Generated...` if we compare actual string but we parse actual so comments are gone in actual.
+    // Wait, the original check uses `stringify(actual)` which will not have comments anyway,
+    // so if we add comments to expected[spec], it will mismatch with actual because actual lost comments when parsed!
+    // But actual was parsed without comments, so `stringify(actual)` has no comments.
+    // If we want check to pass, we should compare without comments. 
+    // Let's just compare the plain stringify for check logic, it's safer.
+    
+    const plainExpStr = stringify(expected[name], { lineWidth: 0 }).trim()
+    const actStr = stringify(actual, { lineWidth: 0 }).trim()
+    if (plainExpStr !== actStr) mismatches.push(`${name}.yaml out of sync with bundle`)
+  }
+
+  const posix = absolute.split(path.sep).join('/')
+  if (posix.includes('/common/yaml/') && mismatches.includes('design.yaml missing')) {
+    mismatches.push('common yaml bundle must emit ir/design.yaml')
+  }
+
+  try {
+    emitCodegenGates(bundle, expected.design, { throwOnFail: true })
+  } catch (err) {
+    mismatches.push(err instanceof Error ? err.message : String(err))
+  }
+
+  return { ok: mismatches.length === 0, mismatches }
+}
+
+function emitCodegenGates(bundle, design, { throwOnFail }) {
+  const grillDone =
+    bundle.grillStatus?.dev === 'done' || bundle.grillStatus?.full === 'done'
+  const gen = { codegen: design.codegen, tags: design.tags }
+  const failOrWarn = (msg) => {
+    if (grillDone && throwOnFail) throw new Error(msg)
+    console.warn(`spec:split: warn: ${msg}`)
+  }
+
+  if (!codegenProfileReady(gen)) {
+    failOrWarn(
+      `bundle.gen.codegen.profile empty — flowgrid cannot gen (${bundlePageId(bundle)}). Fill in /grill-dev.`,
+    )
+  }
+  if (!codegenEntityModuleReady(gen)) {
+    failOrWarn(
+      `bundle.gen.codegen.entity/module empty for profile ${gen.codegen?.profile} (${bundlePageId(bundle)}). Fill in /grill-dev.`,
+    )
+  }
+  const actions = endpointsActionReady(design.api ?? {})
+  if (!actions.ok) {
+    failOrWarn(`api.endpoints action/path incomplete (${bundlePageId(bundle)}): ${actions.problems.join('; ')}`)
+  }
+  const missingTags = missingGenTestTags(gen)
+  if (missingTags.length) {
+    console.warn(
+      `spec:split: warn: missing tags ${missingTags.join(', ')} for profile ${gen.codegen?.profile} (${bundlePageId(bundle)})`,
+    )
+  }
+}
+
+/**
+ * @param {string} bundlePath
+ * @param {{ dryRun?: boolean }} [options]
+ */
+export async function mergeBundleFile(bundlePath, options = {}) {
+  const absolute = path.resolve(bundlePath)
+  const irDir = path.join(path.dirname(absolute), 'ir')
+  const rawYaml = await readFile(absolute, 'utf8')
+  const bundle = parse(rawYaml) ?? {}
+
+  const specIr = parse(await readFile(path.join(irDir, 'spec.yaml'), 'utf8')) ?? {}
+  const designIr = parse(await readFile(path.join(irDir, 'design.yaml'), 'utf8')) ?? {}
+  let legacyFallback = {}
+  try {
+    legacyFallback = parse(await readFile(path.join(irDir, 'legacy.yaml'), 'utf8')) ?? {}
+  } catch {
+    legacyFallback = {}
+  }
+
+  for (const key of BUNDLE_META_KEYS) {
+    if (specIr[key] != null) bundle[key] = specIr[key]
+  }
+  const mergedPageId = bundlePageId({ ...bundle, ...specIr })
+  if (mergedPageId) {
+    bundle['page-id'] = mergedPageId
+    delete bundle.id
+  }
+  delete bundle.openQuestions
+  delete bundle.qa
+  delete bundle['Q&A']
+  delete bundle.pendingTechDebt
+
+  const businessBody = { ...specIr }
+  for (const key of [
+    ...BUNDLE_META_KEYS,
+    ...DESIGN_LAYOUT_KEYS,
+    'openQuestions',
+    'legacy',
+    'qa',
+    'Q&A',
+    'pendingTechDebt',
+    'api',
+  ]) {
+    delete businessBody[key]
+  }
+
+  const ui = { ...(designIr.ui ?? {}) }
+  const gen = {}
+  if (designIr.codegen != null) gen.codegen = designIr.codegen
+  if (designIr.tags != null) gen.tags = designIr.tags
+  const genUi = {}
+  for (const key of GEN_UI_KEYS) {
+    if (ui[key] != null) {
+      genUi[key] = ui[key]
+      delete ui[key]
+    }
+  }
+  if (Object.keys(genUi).length) gen.ui = genUi
+
+  if (bundle.spec && typeof bundle.spec === 'object') delete bundle.spec.api
+
+  bundle.spec = {
+    ...businessBody,
+    ...(Object.keys(ui).length ? { ui } : {}),
+    ...(designIr.entities != null ? { entities: designIr.entities } : {}),
+    ...(designIr.relationships != null ? { relationships: designIr.relationships } : {})
+  }
+  if (bundle.spec.api) delete bundle.spec.api
+  if (hasGenContent(gen)) bundle.gen = gen
+  else delete bundle.gen
+
+  const legacySection = { ...(specIr.legacy ?? legacyFallback) }
+  delete legacySection.id
+  if (!isPlaceholderLegacy(legacySection)) bundle.legacy = legacySection
+  else delete bundle.legacy
+
+  const designSection = pickLayout(designIr)
+  bundle.design = designSection
+
+  if (!options.dryRun) {
+    const mergedYaml = restoreComments(
+      rawYaml, 
+      stringify(bundle, { lineWidth: 0 })
+    )
+    await writeFile(absolute, mergedYaml, 'utf8')
+  }
+
+  return { bundlePath: absolute, bundle }
+}

package/engines/spec/lib/bundle-schema.mjs

@@ -0,0 +1,199 @@
+/**
+ * portal-feature-bundle/v1 — design spec vs portal-gen (gen) split.
+ * bundle.spec = design v1 · bundle.gen = dev-grill / portal:gen fields · ir/spec = merged
+ */
+
+export const BUNDLE_SCHEMA = 'portal-feature-bundle/v1'
+
+export const BUNDLE_META_KEYS = [
+  'id',
+  'page-id',
+  'title',
+  'status',
+  'owner',
+  'summary',
+  'userStories',
+  'specOrigin',
+  'grillStatus'
+]
+
+/** Top-level keys in spec/gen that belong in ir/spec for portal:gen — not design v1 authoring */
+export const GEN_TOP_KEYS = ['codegen', 'tags']
+
+/** ui.* keys owned by dev-grill / portal:gen */
+export const GEN_UI_KEYS = ['filters', 'columns', 'composition', 'testIds']
+
+/** Keys that belong on ir/design.yaml (tech), not ir/spec.yaml (business prose). */
+export const TECH_IR_KEYS = ['codegen', 'tags', 'ui', 'api', 'entities', 'relationships']
+
+export const DESIGN_LAYOUT_KEYS = [
+  'inherits',
+  'shell',
+  'patterns',
+  'nav',
+  'sections',
+  'zones',
+  'behavior',
+  'actions',
+  'deviations',
+  'i18n'
+]
+
+/**
+ * @param {Record<string, unknown>} specSection
+ * @param {Record<string, unknown>} [bundleGen]
+ */
+export function partitionSpecSection(specSection = {}, bundleGen = {}) {
+  const designSpec = { ...specSection }
+  const gen = structuredClone(bundleGen ?? {})
+
+  for (const key of GEN_TOP_KEYS) {
+    if (designSpec[key] != null && gen[key] == null) gen[key] = designSpec[key]
+    delete designSpec[key]
+  }
+
+  if (designSpec.ui && typeof designSpec.ui === 'object') {
+    gen.ui = gen.ui ?? {}
+    const ui = { ...designSpec.ui }
+    for (const key of GEN_UI_KEYS) {
+      if (ui[key] != null && gen.ui[key] == null) gen.ui[key] = ui[key]
+      delete ui[key]
+    }
+    designSpec.ui = ui
+  }
+
+  return { designSpec, gen: pruneGen(gen) }
+}
+
+/**
+ * Merge design spec + gen → flat ir/spec shape (portal:gen input).
+ * @param {Record<string, unknown>} meta
+ * @param {Record<string, unknown>} designSpec
+ * @param {Record<string, unknown>} gen
+ */
+export function mergeIrSpec(meta, designSpec = {}, gen = {}) {
+  const ir = { ...meta, ...designSpec }
+
+  for (const key of GEN_TOP_KEYS) {
+    if (gen[key] != null) ir[key] = gen[key]
+  }
+
+  if (gen.ui && typeof gen.ui === 'object') {
+    ir.ui = { ...(ir.ui ?? {}) }
+    for (const key of GEN_UI_KEYS) {
+      if (gen.ui[key] != null) ir.ui[key] = gen.ui[key]
+    }
+  }
+
+  return ir
+}
+
+/**
+ * @param {Record<string, unknown>} irSpec
+ */
+export function partitionIrSpec(irSpec = {}) {
+  const meta = {}
+  for (const key of BUNDLE_META_KEYS) {
+    if (irSpec[key] != null) meta[key] = irSpec[key]
+  }
+  const specBody = { ...irSpec }
+  for (const key of [...BUNDLE_META_KEYS, ...DESIGN_LAYOUT_KEYS, 'openQuestions', 'qa', 'Q&A']) delete specBody[key]
+
+  const { designSpec, gen } = partitionSpecSection(specBody, {})
+  return { meta, designSpec, gen }
+}
+
+function pruneGen(gen) {
+  const out = { ...gen }
+  if (out.codegen === null) delete out.codegen
+  if (out.ui && !Object.keys(out.ui).length) delete out.ui
+  if (!Object.keys(out).length) return {}
+  return out
+}
+
+function nonEmptyField(value) {
+  return typeof value === 'string' && value.trim().length > 0 && value !== '#missing_info'
+}
+
+export function codegenProfileReady(gen = {}) {
+  return nonEmptyField(gen?.codegen?.profile)
+}
+
+/** Profiles that flowgrid resolves via codegen.entity + codegen.module (no silent modules[0]). */
+export const CODEGEN_ENTITY_PROFILES = new Set([
+  'list',
+  'create',
+  'edit',
+  'detail',
+  'admin-crud',
+  'crud-standard',
+  'auth',
+  'change-password',
+  'public',
+  'select-item',
+  'free',
+  'setting',
+  'export',
+  'import',
+  'dashboard-stats',
+])
+
+export function codegenEntityModuleReady(gen = {}) {
+  const profile = String(gen?.codegen?.profile ?? '').trim()
+  if (!CODEGEN_ENTITY_PROFILES.has(profile)) return true
+  return nonEmptyField(gen?.codegen?.entity) && nonEmptyField(gen?.codegen?.module)
+}
+
+export const ENDPOINT_ACTION_SUFFIXES = [
+  'list',
+  'search',
+  'create',
+  'update',
+  'duplicate',
+  'delete',
+  'detail',
+  'permissions',
+]
+
+export function endpointsActionReady(api = {}) {
+  const endpoints = api?.endpoints
+  if (!Array.isArray(endpoints) || endpoints.length === 0) {
+    return { ok: true, problems: [] }
+  }
+  const problems = []
+  for (const ep of endpoints) {
+    const id = ep?.id ?? ep?.path ?? '?'
+    const action = String(ep?.action ?? '').trim()
+    const route = String(ep?.path ?? '')
+    if (!nonEmptyField(action)) {
+      problems.push(`endpoint ${id} missing action`)
+      continue
+    }
+    const hasSuffix =
+      ENDPOINT_ACTION_SUFFIXES.some((s) => route.includes(`/${s}`)) || route.includes(`/${action}`)
+    if (!hasSuffix) problems.push(`endpoint ${id} path missing action suffix (/${action})`)
+  }
+  return { ok: problems.length === 0, problems }
+}
+
+export function expectedGenTestTags(profile) {
+  const p = String(profile ?? '').trim()
+  if (p === 'list' || p === 'admin-crud' || p === 'select-item' || p === 'export' || p === 'dashboard-stats') return ['#gen:test-schema', '#gen:test-service']
+  if (p === 'create' || p === 'edit' || p === 'auth' || p === 'change-password' || p === 'public' || p === 'setting' || p === 'import') {
+    return ['#gen:test-validation']
+  }
+  return []
+}
+
+export function missingGenTestTags(gen = {}) {
+  const expected = expectedGenTestTags(gen?.codegen?.profile)
+  const tags = new Set((gen?.tags ?? []).map((t) => String(t)))
+  return expected.filter((t) => !tags.has(t))
+}
+
+export function hasGenContent(gen = {}) {
+  if (!gen || typeof gen !== 'object') return false
+  if (GEN_TOP_KEYS.some((k) => gen[k] != null)) return true
+  if (gen.ui && GEN_UI_KEYS.some((k) => gen.ui[k] != null)) return true
+  return false
+}

package/engines/spec/lib/collect-screen-api-intents.mjs

@@ -0,0 +1,69 @@
+function tagList(node) {
+  const raw = node?.tags
+  if (!raw) return []
+  return (Array.isArray(raw) ? raw : [raw]).map((t) => String(t))
+}
+
+function isReuseTag(tag) {
+  return tag === '#reuse-api' || tag.startsWith('#reuse-api:')
+}
+
+function reusePathFromTags(tags) {
+  for (const tag of tags) {
+    if (tag.startsWith('#reuse-api:')) {
+      const path = tag.slice('#reuse-api:'.length).trim()
+      if (path) return path
+    }
+  }
+  return undefined
+}
+
+function apiRefsOf(node) {
+  if (Array.isArray(node.apiRefs) && node.apiRefs.length) return node.apiRefs
+  if (node.bind?.apiRef) return [node.bind.apiRef]
+  return []
+}
+
+function hasApiCall(node, tags) {
+  if (!node || typeof node !== 'object') return false
+  if (tags.some(isReuseTag)) return true
+  if (node.reuseFrom) return true
+  if (apiRefsOf(node).length) return true
+  return false
+}
+
+function walk(node, loc, out) {
+  if (!node || typeof node !== 'object') return
+  const tags = tagList(node)
+  if (hasApiCall(node, tags)) {
+    const reuse = tags.some(isReuseTag) || Boolean(node.reuseFrom)
+    out.push({
+      id: node.id ?? null,
+      label: node.label ?? null,
+      kind: node.kind ?? null,
+      loc,
+      reuse,
+      reuseFrom: node.reuseFrom || reusePathFromTags(tags) || null,
+      apiRefs: apiRefsOf(node),
+    })
+  }
+  for (const item of node.items || []) walk(item, loc, out)
+  for (const sec of node.sections || []) walk(sec, loc, out)
+}
+
+/**
+ * Screen API inventory from ir/design.yaml (page actions + nested items).
+ * `#reuse-api` / reuseFrom = pointer only (no new trio on this leaf).
+ * Other apiRefs = unique APIs this screen still needs a sibling api/<seq>/.
+ */
+export function collectScreenApiIntents(design = {}) {
+  const out = []
+  for (const action of design.actions || []) walk(action, 'actions', out)
+  for (const section of design.sections || []) walk(section, 'sections', out)
+  for (const zone of design.zones || []) walk(zone, 'zones', out)
+  return out
+}
+
+export function screenNeedsLocalApiTrio(design = {}) {
+  return collectScreenApiIntents(design).some((row) => !row.reuse)
+}

package/engines/spec/lib/hydrate-design-api.mjs

@@ -0,0 +1,58 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { parse } from 'yaml'
+
+function isSeqDir(name) {
+  return /^\d{2,}$/.test(name)
+}
+
+/** `…/<leaf>/api/<seq>/01-backend-spec.yaml` next to the feature bundle. */
+export function listSiblingBackend01(bundleDir) {
+  const apiRoot = path.join(path.resolve(bundleDir), 'api')
+  if (!existsSync(apiRoot)) return []
+  const out = []
+  for (const name of readdirSync(apiRoot, { withFileTypes: true })) {
+    if (!name.isDirectory() || !isSeqDir(name.name)) continue
+    const file = path.join(apiRoot, name.name, '01-backend-spec.yaml')
+    if (existsSync(file)) out.push(file)
+  }
+  out.sort()
+  return out
+}
+
+function slimEndpoint(ep = {}) {
+  const row = {}
+  if (ep.id != null) row.id = ep.id
+  if (ep.method != null) row.method = ep.method
+  if (ep.path != null) row.path = ep.path
+  if (ep.action != null) row.action = ep.action
+  return row
+}
+
+/**
+ * Authoring SSOT is 01 only. ir/design.yaml.api is a split projection of **local** sibling 01 files.
+ * Reused APIs are not projected here — they stay on design.actions/items (`#reuse-api` + reuseFrom).
+ */
+export function projectDesignApiFrom01(bundleDir) {
+  const endpoints = []
+  for (const file of listSiblingBackend01(bundleDir)) {
+    let spec = {}
+    try {
+      spec = parse(readFileSync(file, 'utf8')) ?? {}
+    } catch {
+      continue
+    }
+    for (const ep of spec.api?.endpoints ?? []) {
+      endpoints.push(slimEndpoint(ep))
+    }
+  }
+  if (!endpoints.length) return null
+  return { endpoints }
+}
+
+export function applyDesignApiFrom01(design, bundleDir) {
+  const projected = projectDesignApiFrom01(bundleDir)
+  if (projected) design.api = projected
+  else delete design.api
+  return design
+}