@shanyucoder/flowgrid 0.1.0

package/engines/template-builder/scanner.mjs

@@ -0,0 +1,138 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * Scan a project to extract UI Framework and UI components
+ * @param {string} projectRoot
+ */
+export function scanProject(projectRoot) {
+  let pkg = {};
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    } catch {}
+  }
+
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  
+  // Detect UI library
+  let uiLibrary = 'custom';
+  if (deps['element-plus']) uiLibrary = 'element-plus';
+  else if (deps['ant-design-vue']) uiLibrary = 'ant-design-vue';
+  else if (deps['antd']) uiLibrary = 'ant-design-react';
+  else if (deps['vuetify']) uiLibrary = 'vuetify';
+  else if (deps['bootstrap-vue-next'] || deps['bootstrap-vue']) uiLibrary = 'bootstrap-vue';
+  else if (deps['@chakra-ui/react'] || deps['@chakra-ui/vue-next']) uiLibrary = 'chakra-ui';
+  else if (deps['radix-vue'] || deps['shadcn-vue']) uiLibrary = 'shadcn-vue';
+
+  return {
+    uiLibrary,
+    dependencies: Object.keys(deps),
+    packageJson: pkg
+  };
+}
+
+/**
+ * Extract DNA from a golden sample file (e.g. UserList.vue, ProductTable.tsx)
+ * @param {string} filePath
+ */
+export function extractDna(filePath) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Golden sample file not found: ${filePath}`);
+  }
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  const ext = path.extname(filePath);
+
+  // Discover shells & layouts
+  const shellMatches = content.match(/<([A-Z][a-zA-Z0-9]*(?:Layout|Container|Page|Card))/g) || [];
+  const shells = Array.from(new Set(shellMatches.map(m => m.replace('<', ''))));
+
+  // Discover table / list components
+  const tableMatches = content.match(/<([A-Z][a-zA-Z0-9]*(?:Table|List|Grid)|el-table|a-table|v-data-table)/g) || [];
+  const tables = Array.from(new Set(tableMatches.map(m => m.replace('<', ''))));
+
+  // Discover form / widget inputs
+  const widgetMatches = content.match(/<([A-Z][a-zA-Z0-9]*(?:Input|Select|DatePicker|Button|Tag|Badge)|el-[a-z-]+|a-[a-z-]+|v-[a-z-]+)/g) || [];
+  const widgets = Array.from(new Set(widgetMatches.map(m => m.replace('<', ''))));
+
+  return {
+    filePath,
+    ext,
+    shells: shells.length > 0 ? shells : ['CustomShell'],
+    tables: tables.length > 0 ? tables : ['CustomTable'],
+    widgets: widgets.slice(0, 20),
+    rawContent: content
+  };
+}
+
+/**
+ * Generate design.registry.json based on extracted DNA
+ * @param {object} params
+ */
+export function generateDesignRegistry({ uiLibrary, shells, widgets, outputDir }) {
+  const primaryShell = shells[0] || 'CustomLayout';
+  
+  const registry = {
+    $schema: 'https://flowgrid.dev/schemas/design-registry.json',
+    uiLibrary,
+    shells: {
+      [primaryShell]: {
+        tag: `#shell: ${primaryShell}`,
+        description: `Primary application layout scanned from project DNA`,
+        status: 'implemented'
+      }
+    },
+    fieldWidgets: {},
+    componentAliases: {}
+  };
+
+  for (const widget of widgets) {
+    const key = widget.replace(/^[a-z]+-/, '').replace(/^[A-Z]/, c => c.toUpperCase());
+    registry.fieldWidgets[key] = {
+      tag: `#widget: ${key}`,
+      component: widget,
+      status: 'implemented'
+    };
+  }
+
+  const registryDir = path.join(outputDir, 'registries');
+  fs.mkdirSync(registryDir, { recursive: true });
+  const registryPath = path.join(registryDir, 'design.registry.json');
+  fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2) + '\n');
+
+  // Also export local lexicon file for ArtifactGraph SQLite ingestion
+  const lexiconDir = path.join(outputDir, 'lexicon');
+  fs.mkdirSync(lexiconDir, { recursive: true });
+  const lexiconLines = [
+    `# Local project custom tags lexicon generated by FlowGrid`,
+    `#shell: ${primaryShell}`,
+    ...widgets.map(w => {
+      const key = w.replace(/^[a-z]+-/, '').replace(/^[A-Z]/, c => c.toUpperCase());
+      return `#widget: ${key} · ${w}`;
+    })
+  ];
+  fs.writeFileSync(path.join(lexiconDir, 'registry-tags.en.txt'), lexiconLines.join('\n') + '\n');
+
+  return { registryPath, registry };
+}
+
+/**
+ * Parameterize a sample into a Handlebars template
+ * @param {object} params
+ */
+export function parameterizeTemplate({ sampleContent, outputDir, templateName = 'list.vue.hbs' }) {
+  let template = sampleContent;
+
+  // Generic parameterization of titles, entity names
+  template = template.replace(/["']([A-Z][a-zA-Z0-9]+)\s+(Management|List|Index|Danh sách)["']/g, '"{{pascalCase entity}} $2"');
+  template = template.replace(/api\/v\d+\/([a-z-]+)/g, 'api/v1/{{kebabCase entity}}');
+
+  const templatesDir = path.join(outputDir, 'templates');
+  fs.mkdirSync(templatesDir, { recursive: true });
+  const templatePath = path.join(templatesDir, templateName);
+  fs.writeFileSync(templatePath, template);
+
+  return { templatePath };
+}

package/engines/testcase/_staging-from-portal/README-STAGING.md

@@ -0,0 +1,13 @@
+# Staging — product copy from portal (temporary)
+
+Copied from `~/workspace/portal/testgen` before removing the product-local
+engine. Canonical testcase engine stays in `engines/testcase/` (FlowGrid bộ test).
+
+## Check tomorrow then delete this folder
+
+- Diff this folder against its parent, excluding this file.
+- Port only missing behavior worth retaining; do not overwrite FlowGrid testcase SSOT.
+- Resolve old imports from portal's removed `codegen/runners/lib/*`.
+- After verification, delete `_staging-from-portal/`.
+
+See `TODO-TESTGEN-PORTAL.md`.

package/engines/testcase/_staging-from-portal/runners/README.md

@@ -0,0 +1,15 @@
+# testcase:gen
+
+Reads **plans** from sibling `base-tests/` → writes `tests/e2e/` on this FE repo.
+
+```bash
+pnpm testcase:gen:dry --id TC-LOGIN-VALID
+pnpm testcase:gen --id W-AD-AUTH-001
+pnpm testcase:gen --id smoke
+pnpm testcase:gen --testcase ../base-tests/cases/W-AD-AUTH-001/TC-LOGIN-VALID.yaml
+pnpm testcase:gen --feature W-AD-AUTH-001   # all TC-* under cases/{id}/
+```
+
+Author/edit plans on **base-tests** (`/testcase`), not on this code repo.
+
+Design `ir/spec.yaml` (testIds) is loaded from **base-docs** via `refs.screen` when present.

package/engines/testcase/_staging-from-portal/runners/generate.mjs

@@ -0,0 +1,123 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import Handlebars from 'handlebars'
+
+import { listFeatureTestcases, readTestcaseFile } from './lib/read-testcase.mjs'
+import { buildTestcaseContext } from './lib/plan.mjs'
+import { renderTemplate } from './lib/render.mjs'
+import { resolveSemanticPlan } from './lib/semantic-plan.mjs'
+import { writeOutputs } from './lib/write-files.mjs'
+import { resolveHubId } from '../../codegen/runners/lib/resolve-hub-id.mjs'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..')
+
+Handlebars.registerHelper('eq', (a, b) => a === b)
+Handlebars.registerHelper('and', (a, b) => a && b)
+Handlebars.registerHelper('not', (a) => !a)
+Handlebars.registerHelper('or', (a, b) => a || b)
+Handlebars.registerHelper('startsWith', (value, prefix) => String(value).startsWith(prefix))
+Handlebars.registerHelper('includes', (value, fragment) => String(value).includes(fragment))
+Handlebars.registerHelper('json', (value) => JSON.stringify(value, null, 2))
+
+function parseArgs(argv) {
+  const options = { dryRun: false, force: false, testcase: null, feature: null, id: 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 === '--testcase') options.testcase = argv[++i]
+    else if (arg === '--feature') options.feature = argv[++i]
+    else if (arg === '--id') options.id = argv[++i]
+    else if (!arg.startsWith('-') && !options.testcase && !options.feature && !options.id) {
+      options.testcase = arg
+    }
+  }
+
+  if (!options.testcase && !options.feature && !options.id) {
+    throw new Error(
+      'Usage: pnpm testcase:gen --id W-AD-AUTH-001|TC-LOGIN-VALID|smoke|CMP-01|SC-LOGIN\n' +
+        '       pnpm testcase:gen --testcase <path> | --feature W-AD-AUTH-001  (screen under base-tests/cases)',
+    )
+  }
+
+  return options
+}
+
+async function generateOne(testcasePath, options) {
+  const { testcase, spec, testcaseFile, specFile } = await readTestcaseFile(testcasePath, { repoRoot: root })
+  const ctx = buildTestcaseContext(testcase, spec, testcaseFile)
+  ctx.specFile = specFile
+
+  const semantic = await resolveSemanticPlan(root, testcase)
+  ctx.useSemanticFixture = semantic.useSemanticFixture
+  ctx.needsConsoleErrors = semantic.needsConsoleErrors
+  ctx.semanticCodegenLines = semantic.semanticCodegenLines
+  ctx.semanticReady = semantic.semanticReady ?? ctx.semanticReady
+  ctx.hasLegacyLayoutOnly = Boolean(ctx.semanticReady) && !semantic.useSemanticFixture
+  ctx.warnings.push(...semantic.warnings)
+
+  const pageContent = await renderTemplate('page.ts.hbs', ctx)
+  const specContent = await renderTemplate('spec.ts.hbs', ctx)
+
+  const outputs = [
+    { relativePath: ctx.outputs.pageObject, content: pageContent },
+    { relativePath: ctx.outputs.spec, content: specContent }
+  ]
+
+  const { written, skipped } = await writeOutputs(root, outputs, {
+    dryRun: options.dryRun,
+    force: options.force
+  })
+
+  console.log(`testcase-gen: id=${ctx.testcaseId} module=${ctx.module}`)
+  console.log(`  testcase: ${testcaseFile}`)
+  if (specFile) console.log(`  spec: ${specFile}`)
+  if (ctx.warnings.length) {
+    for (const warning of ctx.warnings) console.warn(`  warn: ${warning}`)
+  }
+  for (const item of written) {
+    console.log(`  ${options.dryRun ? 'would write' : 'write'}: ${item.relativePath}`)
+  }
+  for (const item of skipped) {
+    console.log(`  skip: ${item.relativePath} (${item.reason})`)
+  }
+
+  return { ctx, written, skipped }
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2))
+
+  if (options.id) {
+    const resolved = resolveHubId(root, options.id, 'testcase')
+    for (const n of resolved.notes) console.warn(`  note: ${n}`)
+    if (!resolved.paths.length) throw new Error(`--id ${options.id}: no testcase paths`)
+    console.log(`testcase-gen: --id ${options.id} → ${resolved.paths.length} file(s) (${resolved.kind})`)
+    for (const testcasePath of resolved.paths) {
+      await generateOne(testcasePath, options)
+    }
+    return
+  }
+
+  if (options.feature) {
+    const paths = await listFeatureTestcases(root, options.feature)
+    if (!paths.length) {
+      throw new Error(
+        `No TC-*.yaml under base-tests/cases/${options.feature}. Prefer: pnpm testcase:gen --id <W-|TC-|suite>`,
+      )
+    }
+    for (const testcasePath of paths) {
+      await generateOne(testcasePath, options)
+    }
+    return
+  }
+
+  await generateOne(options.testcase, options)
+}
+
+main().catch((error) => {
+  console.error(error.message ?? error)
+  process.exit(1)
+})

package/engines/testcase/_staging-from-portal/runners/lib/e2e-registry.mjs

@@ -0,0 +1,77 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+
+export const REGISTRY_REL = 'registries/e2e-test.registry.json'
+
+/**
+ * @param {string} root
+ */
+export async function loadE2eTestRegistry(root) {
+  const registryPath = path.join(root, REGISTRY_REL)
+  const raw = await readFile(registryPath, 'utf8')
+  const registry = JSON.parse(raw)
+  return { registry, registryPath }
+}
+
+/**
+ * @param {string} tag
+ * @param {{ tagPrefixes: { e2eBundle: string, skipAssert: string } }} registry
+ */
+export function parseE2eBundleTag(tag, registry) {
+  const prefix = registry.tagPrefixes?.e2eBundle ?? '#e2e:'
+  const trimmed = String(tag).trim()
+  if (!trimmed.startsWith(prefix)) return null
+  return trimmed.slice(prefix.length)
+}
+
+/**
+ * @param {string} tag
+ * @param {{ tagPrefixes: { skipAssert: string } }} registry
+ */
+export function parseSkipAssertTag(tag, registry) {
+  const prefix = registry.tagPrefixes?.skipAssert ?? '#skip-e2e-assert:'
+  const trimmed = String(tag).trim()
+  if (!trimmed.startsWith(prefix)) return null
+  return trimmed.slice(prefix.length)
+}
+
+/**
+ * @param {string} bundleId
+ * @param {Record<string, { extends?: string[], matchers?: string[] }>} bundles
+ * @param {Set<string>} visited
+ * @returns {string[]}
+ */
+export function resolveBundleMatchers(bundleId, bundles, visited = new Set()) {
+  if (visited.has(bundleId)) return []
+  visited.add(bundleId)
+
+  const bundle = bundles[bundleId]
+  if (!bundle) return []
+
+  const fromExtends = (bundle.extends ?? []).flatMap((id) => resolveBundleMatchers(id, bundles, visited))
+  const own = bundle.matchers ?? []
+  return [...fromExtends, ...own]
+}
+
+/**
+ * @param {string[]} tags
+ * @param {Record<string, unknown>} registry
+ */
+export function bundleIdsFromTags(tags, registry) {
+  const bundles = registry.bundles ?? {}
+  return tags
+    .map((tag) => parseE2eBundleTag(tag, registry))
+    .filter((id) => id && bundles[id])
+}
+
+/**
+ * @param {string[]} tags
+ * @param {Record<string, unknown>} registry
+ */
+export function skipMatchersFromTags(tags, registry) {
+  return new Set(
+    tags
+      .map((tag) => parseSkipAssertTag(tag, registry))
+      .filter(Boolean)
+  )
+}

package/engines/testcase/_staging-from-portal/runners/lib/plan.mjs

@@ -0,0 +1,97 @@
+/**
+ * @param {string} id e.g. chain-hotel-list
+ */
+export function toPageClassName(id) {
+  const base = id
+    .split('-')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+  return `${base}Page`
+}
+
+/**
+ * @param {Record<string, unknown>} testcase
+ * @param {Record<string, unknown> | null} spec
+ * @param {string} testcaseFile
+ */
+export function buildTestcaseContext(testcase, spec, testcaseFile) {
+  const module =
+    spec?.ui?.testIds?.module ??
+    spec?.codegen?.module ??
+    testcase.feature ??
+    'feature'
+
+  const pageClassName = toPageClassName(testcase.id)
+  const routePath = testcase.route?.path ?? '/'
+  const session = testcase.setup?.session ?? null
+  const mocks = testcase.setup?.mocks ?? []
+  const steps = testcase.steps ?? []
+  const clickSteps = steps.filter((step) => step.action === 'click')
+  const setupSteps = steps
+    .filter((step) => step.action !== 'click')
+    .map((step) => {
+      if (step.action !== 'waitFor' || !step.role) return step
+      const rawName = step.name ?? step.namePattern ?? ''
+      const nameExpr =
+        typeof rawName === 'string' && rawName.startsWith('/') && rawName.endsWith('/')
+          ? rawName
+          : rawName
+            ? `'${String(rawName).replace(/'/g, "\\'")}'`
+            : null
+      return { ...step, roleNameExpr: nameExpr }
+    })
+  const uiVisibility = (testcase.assertions?.ui ?? []).filter((item) => item.testId !== undefined)
+  const uiActions = (testcase.assertions?.ui ?? [])
+    .filter((item) => item.action)
+    .map((item) => {
+      if (item.action !== 'newTabOpened') return item
+      const pattern = testcase.testIds?.patterns?.[0]
+      const clickTemplate =
+        typeof pattern === 'string'
+          ? pattern
+          : 'chain-hotels-cell-managers-login-as-{{manager_id}}'
+      return { ...item, clickTemplate }
+    })
+  const networkAssertions = testcase.assertions?.network ?? []
+  const semanticReady = testcase.assertions?.semantic?.ready ?? null
+  const data = testcase.data ?? testcase.testData ?? {}
+  const hasNewTabAction = uiActions.some((item) => item.action === 'newTabOpened')
+
+  const specRequired = spec?.ui?.testIds?.required ?? []
+  const testcaseRequired = testcase.testIds?.required ?? []
+  const missingInSpec = testcaseRequired.filter((id) => !specRequired.includes(id))
+  const missingInTestcase = specRequired.filter((id) => !testcaseRequired.includes(id))
+
+  return {
+    testcaseId: testcase.id,
+    testcaseTitle: testcase.title ?? testcase.id,
+    coverage: testcase.coverage ?? testcase._coverage ?? [],
+    a11y: testcase.a11y ?? null,
+    module,
+    pageClassName,
+    routePath,
+    session,
+    mocks,
+    steps,
+    setupSteps,
+    clickSteps,
+    uiVisibility,
+    uiActions,
+    networkAssertions,
+    semanticReady,
+    data,
+    hasData: Object.keys(data).length > 0,
+    hasNewTabAction,
+    primaryNetwork: networkAssertions[0] ?? null,
+    testcaseFile,
+    specFile: null,
+    warnings: [
+      ...missingInSpec.map((id) => `testcase testIds.required "${id}" not in spec.ui.testIds.required`),
+      ...missingInTestcase.map((id) => `spec.ui.testIds.required "${id}" missing from testcase`)
+    ],
+    outputs: {
+      pageObject: `tests/e2e/pages/${module}/${pageClassName}.ts`,
+      spec: `tests/e2e/${module}/${testcase.id}.spec.ts`
+    }
+  }
+}

package/engines/testcase/_staging-from-portal/runners/lib/read-testcase.mjs

@@ -0,0 +1,166 @@
+import { readFile, readdir } from 'node:fs/promises'
+import path from 'node:path'
+import { parse } from 'yaml'
+import { resolveFeatureDir } from '../../../codegen/runners/lib/read-spec.mjs'
+import { resolveHubId, resolveProjectRoot } from '../../../codegen/runners/lib/resolve-hub-id.mjs'
+
+/**
+ * Normalize hub R3 cases for testcase:gen.
+ * Supports coverage[] (R3.2), testData→data, a11y / #e2e:a11y-wcag.
+ * @param {Record<string, unknown>} testcase
+ */
+export function normalizeTestcaseForGen(testcase) {
+  const out = { ...testcase }
+
+  if (Array.isArray(out.coverage) && out.coverage.length) {
+    out._coverage = [...out.coverage]
+  }
+
+  if (out.genType === 'e2e' || out.type === 'e2e') {
+    if (out.type && out.type !== 'e2e') out._taxonomyType = out.type
+    out.type = 'e2e'
+  } else if (out.type && out.type !== 'e2e') {
+    if (
+      out.genType === 'e2e' ||
+      out.refs?.screen ||
+      out.automation === 'automated' ||
+      out._coverage
+    ) {
+      out._taxonomyType = out.type
+      out.type = 'e2e'
+    }
+  }
+  if (!out.type && (out.genType === 'e2e' || out._coverage || out.refs?.screen)) {
+    out.type = 'e2e'
+  }
+  if (!out.type) out.type = 'e2e'
+
+  if (!out.feature && out.refs?.screen) {
+    out.feature = String(out.refs.screen).toLowerCase().replace(/_/g, '-')
+  }
+  if (!out.route) {
+    out.route = { path: '/login', auth: 'guest' }
+  }
+
+  if (!out.data && out.testData && typeof out.testData === 'object') {
+    out.data = out.testData
+  }
+
+  const needsA11y =
+    Boolean(out.a11y) ||
+    (Array.isArray(out.coverage) && out.coverage.includes('accessibility')) ||
+    (Array.isArray(out.tags) &&
+      out.tags.some((t) => String(t).includes('a11y-wcag') || String(t) === 'a11y'))
+
+  if (!out.tags) out.tags = ['#e2e:semantic-smoke']
+  else if (Array.isArray(out.tags) && !out.tags.some((t) => String(t).startsWith('#e2e'))) {
+    out.tags = [...out.tags, '#e2e:semantic-smoke']
+  }
+
+  if (needsA11y) {
+    const hasA11yTag = out.tags.some(
+      (t) => String(t).includes('a11y-wcag') || String(t) === '#e2e:a11y-wcag',
+    )
+    if (!hasA11yTag) out.tags = [...out.tags, '#e2e:a11y-wcag']
+
+    out.assertions = { ...(out.assertions || {}) }
+    out.assertions.semantic = { ...(out.assertions.semantic || {}) }
+    if (!Array.isArray(out.assertions.semantic.accessibility)) {
+      out.assertions.semantic.accessibility = ['toHaveNoA11yViolations']
+    }
+  }
+
+  if (typeof out.expected === 'string') {
+    out.expected = [out.expected]
+  }
+  if (!out.expected) out.expected = []
+  if (!out.assertions && out.testIds) {
+    out.assertions = {
+      semantic: {
+        ready: {
+          waitForTestIds: out.testIds.required ?? [],
+        },
+      },
+    }
+  }
+  if (!out.steps) out.steps = []
+  return out
+}
+
+/**
+ * Resolve design ir/spec.yaml from refs.screen (base-docs) for enrichment.
+ * @param {string} repoRoot
+ * @param {Record<string, unknown>} testcase
+ */
+async function loadDesignSpec(repoRoot, testcase) {
+  const screen = testcase.refs?.screen
+  if (!screen || typeof screen !== 'string') return { spec: null, specFile: null, featureDir: null }
+  try {
+    const resolved = resolveHubId(repoRoot, screen, 'codegen')
+    const abs = resolved.paths?.[0]
+    if (!abs) return { spec: null, specFile: null, featureDir: null }
+    const raw = await readFile(abs, 'utf8')
+    const spec = parse(raw) ?? {}
+    return {
+      spec,
+      specFile: path.relative(repoRoot, abs),
+      featureDir: resolveFeatureDir(abs),
+    }
+  } catch {
+    return { spec: null, specFile: null, featureDir: null }
+  }
+}
+
+/**
+ * @param {string} testcasePath
+ * @param {{ repoRoot?: string }} [opts]
+ */
+export async function readTestcaseFile(testcasePath, opts = {}) {
+  const repoRoot = opts.repoRoot ? path.resolve(opts.repoRoot) : process.cwd()
+  const absolute = path.resolve(testcasePath)
+  const raw = await readFile(absolute, 'utf8')
+  let testcase = parse(raw) ?? {}
+  testcase = normalizeTestcaseForGen(testcase)
+
+  if (!testcase.id) {
+    throw new Error(`Missing id in ${testcasePath}`)
+  }
+  // After normalize, type should be e2e for gen; taxonomy kept in _taxonomyType
+  if (testcase.type && testcase.type !== 'e2e') {
+    throw new Error(`testcase:gen only supports e2e gen — got "${testcase.type}" in ${testcasePath}`)
+  }
+
+  const design = await loadDesignSpec(repoRoot, testcase)
+  const casesDir = path.dirname(absolute)
+
+  return {
+    testcase,
+    testcaseFile: path.relative(repoRoot, absolute),
+    featureDir: path.relative(repoRoot, design.featureDir ?? casesDir),
+    specFile: design.specFile,
+    spec: design.spec,
+  }
+}
+
+/**
+ * List TC-*.yaml under base-tests/cases/{screenId}/ (prefer --id).
+ * @param {string} root FE repo root
+ * @param {string} screenId e.g. W-AD-AUTH-001
+ */
+export async function listFeatureTestcases(root, screenId) {
+  const testsRoot = resolveProjectRoot(root, 'base-tests')
+  const screenDir = path.join(testsRoot, 'cases', screenId)
+  const files = []
+  let entries = []
+  try {
+    entries = await readdir(screenDir, { withFileTypes: true })
+  } catch {
+    return files
+  }
+  for (const entry of entries) {
+    if (entry.isFile() && /^TC-.*\.ya?ml$/i.test(entry.name)) {
+      files.push(path.join(screenDir, entry.name))
+    }
+  }
+  return files.sort()
+}

package/engines/testcase/_staging-from-portal/runners/lib/render.mjs

@@ -0,0 +1,18 @@
+import Handlebars from 'handlebars'
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..')
+const templatesDir = path.join(rootDir, 'templates')
+
+/**
+ * @param {string} templateRel
+ * @param {Record<string, unknown>} context
+ */
+export async function renderTemplate(templateRel, context) {
+  const templatePath = path.join(templatesDir, templateRel)
+  const source = await readFile(templatePath, 'utf8')
+  const template = Handlebars.compile(source, { noEscape: true })
+  return `${template(context).trim()}\n`
+}