@shanyucoder/flowgrid 0.1.5 → 0.1.9

package/engines/spec/lib/audit-e2e-coverage.mjs

@@ -9,6 +9,9 @@ import fs from 'fs';
 import path from 'path';
 import { parse } from 'yaml';
 import { resolveTestsDocsRoot } from '../../shared/flowgrid-tests-docs.mjs';
+import { resolveFlowgridContext } from '../../shared/resolve-flowgrid-context.mjs';
+import { playwrightScanRoots } from '../../shared/e2e-output-layout.mjs';
+import { resolveHubId } from '../../testcase/runners/lib/resolve-hub-id.mjs';
 
 const TC_ID_PATTERN = /^TC-[A-Z0-9][A-Z0-9-]*$/;
 const DESCRIBE_TC_RE = /test\.describe\s*\(\s*['"](TC-[^'"]+)['"]/g;
@@ -42,7 +45,21 @@ function walkFiles(root, onFile) {
 /**
  * @param {string} testsRoot
  */
-export function scanPlaywrightTests(testsRoot) {
+function mergeScanState(into, from) {
+  for (const rec of from.specFiles) {
+    if (!into.specFiles.includes(rec)) into.specFiles.push(rec);
+  }
+  for (const [tcId, files] of from.tcIdToFiles.entries()) {
+    const list = into.tcIdToFiles.get(tcId) ?? [];
+    for (const f of files) {
+      if (!list.includes(f)) list.push(f);
+    }
+    into.tcIdToFiles.set(tcId, list);
+  }
+  for (const id of from.referencedTcIds) into.referencedTcIds.add(id);
+}
+
+function scanPlaywrightTestsSingle(testsRoot) {
   const specFiles = [];
   const tcIdToFiles = new Map();
 
@@ -77,6 +94,10 @@ export function scanPlaywrightTests(testsRoot) {
 
   const referencedTcIds = new Set(tcIdToFiles.keys());
 
+  return buildScanResult(specFiles, tcIdToFiles, referencedTcIds);
+}
+
+function buildScanResult(specFiles, tcIdToFiles, referencedTcIds) {
   return {
     specFiles,
     specFileCount: specFiles.length,
@@ -92,6 +113,22 @@ export function scanPlaywrightTests(testsRoot) {
   };
 }
 
+/**
+ * @param {string | string[]} testsRootOrRoots
+ */
+export function scanPlaywrightTests(testsRootOrRoots) {
+  const roots = Array.isArray(testsRootOrRoots) ? testsRootOrRoots : [testsRootOrRoots];
+  const existing = roots.filter((r) => r && fs.existsSync(r));
+  if (!existing.length) {
+    return buildScanResult([], new Map(), new Set());
+  }
+  let merged = scanPlaywrightTestsSingle(existing[0]);
+  for (let i = 1; i < existing.length; i++) {
+    mergeScanState(merged, scanPlaywrightTestsSingle(existing[i]));
+  }
+  return merged;
+}
+
 /**
  * @param {string} casesRoot
  * @param {{ screen?: string }} [filter]
@@ -150,11 +187,12 @@ function addGap(gaps, code, severity, fieldPath, message, suggestedFix) {
 }
 
 /**
- * @param {{ tcDocuments: Array<{ path: string; id: string; screen: string | null; matrix: unknown[] }>; e2eRoot: string; strict?: boolean; strictMatrix?: boolean }} opts
+ * @param {{ tcDocuments: Array<{ path: string; id: string; screen: string | null; matrix: unknown[] }>; e2eRoot?: string; e2eScanRoots?: string[]; strict?: boolean; strictMatrix?: boolean }} opts
  */
 export function auditE2eCoverage(opts) {
-  const { tcDocuments, e2eRoot, strict = false, strictMatrix = false } = opts;
-  const pw = scanPlaywrightTests(e2eRoot);
+  const { tcDocuments, e2eRoot, e2eScanRoots, strict = false, strictMatrix = false } = opts;
+  const scanRoots = e2eScanRoots ?? (e2eRoot ? [e2eRoot] : []);
+  const pw = scanPlaywrightTests(scanRoots);
   const gaps = [];
   const missingInPlaywright = [];
   const matrixRowsUncovered = [];
@@ -268,21 +306,21 @@ export function auditE2eCoverage(opts) {
 }
 
 function parseCliArgs(argv) {
-  let e2eRoot = null;
-  let testsDocs = null;
+  const ctx = resolveFlowgridContext({ argv });
+  let e2eRoot = ctx.e2eRoot;
+  let testsDocs = ctx.testsDocs;
   let screen = null;
   let strict = false;
   let strictMatrix = false;
+  let hubId = null;
   const tcFiles = [];
 
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === '--e2e-root' && argv[i + 1]) {
-      e2eRoot = path.resolve(process.cwd(), argv[++i]);
-    } else if (a === '--tests-docs' && argv[i + 1]) {
-      testsDocs = path.resolve(process.cwd(), argv[++i]);
-    } else if (a === '--screen' && argv[i + 1]) {
-      screen = argv[++i];
+  for (let i = 0; i < ctx.argv.length; i++) {
+    const a = ctx.argv[i];
+    if (a === '--screen' && ctx.argv[i + 1]) {
+      screen = ctx.argv[++i];
+    } else if (a === '--id' && ctx.argv[i + 1]) {
+      hubId = ctx.argv[++i];
     } else if (a === '--strict') {
       strict = true;
       strictMatrix = true;
@@ -291,22 +329,32 @@ function parseCliArgs(argv) {
     } else if (a === '--help' || a === '-h') {
       return { help: true };
     } else if (!a.startsWith('-')) {
-      tcFiles.push(path.resolve(process.cwd(), a));
+      tcFiles.push(path.resolve(ctx.projectRoot, a));
     }
   }
 
-  return { e2eRoot, testsDocs, screen, strict, strictMatrix, tcFiles };
+  return {
+    e2eRoot,
+    testsDocs,
+    screen,
+    strict,
+    strictMatrix,
+    tcFiles,
+    hubId,
+    projectRoot: ctx.projectRoot,
+  };
 }
 
 function printUsage() {
   console.log(
     [
-      'Usage: node engines/spec/lib/audit-e2e-coverage.mjs --e2e-root <playwright-dir> [options]',
-      '       flowgrid audit e2e --e2e-root <dir> --tests-docs <tests-hub> [--screen W-*]',
-      '       flowgrid audit e2e --e2e-root <dir> <TC-*.yaml> [more…]',
+      'Usage: flowgrid audit e2e [--id TC-*|W-*|suite] [options]',
+      '       flowgrid audit e2e <TC-*.yaml> [more…]',
       '',
       'Options:',
-      '  --tests-docs   Tests hub (TC YAML); or set FLOWGRID_TESTS_DOC',
+      '  --e2e-root     Playwright scan root (default: config/MCP FLOWGRID_E2E_ROOT)',
+      '  --tests-docs   Tests hub (TC YAML); or FLOWGRID_TESTS_DOC / config',
+      '  --id           Resolve TC YAML via tests hub index (TC-*, screen W-*, suite)',
       '  --screen W-*   Filter TC docs by refs.screen',
       '  --strict       Treat missing TC spec + matrix gaps as critical',
       '  --strict-matrix  Require each testMatrix row signal in Playwright text',
@@ -327,19 +375,27 @@ if (parsed.help) {
   process.exit(0);
 }
 
-if (!parsed.e2eRoot) {
-  console.error(JSON.stringify({ error: '--e2e-root is required (Playwright specs directory)' }));
-  process.exit(1);
-}
-
-if (!fs.existsSync(parsed.e2eRoot)) {
-  console.error(JSON.stringify({ error: `e2e-root not found: ${parsed.e2eRoot}` }));
+const e2eScanRoots = playwrightScanRoots(parsed.projectRoot, parsed.e2eRoot).filter((r) =>
+  fs.existsSync(r),
+);
+if (!e2eScanRoots.length) {
+  console.error(
+    JSON.stringify({
+      error:
+        'No e2e scan directory found — set frontend/backend.e2eRoot, FLOWGRID_E2E_ROOT, or pass --e2e-root',
+    }),
+  );
   process.exit(1);
 }
 
 let tcDocuments = [];
 try {
-  if (parsed.tcFiles.length) {
+  if (parsed.hubId) {
+    const resolved = resolveHubId(parsed.projectRoot, parsed.hubId, 'testcase');
+    for (const f of resolved.paths) {
+      tcDocuments.push(loadTcDocument(f));
+    }
+  } else if (parsed.tcFiles.length) {
     for (const f of parsed.tcFiles) {
       if (!fs.existsSync(f)) {
         console.error(JSON.stringify({ error: `TC file not found: ${f}` }));
@@ -352,7 +408,7 @@ try {
     if (!testsDocs) {
       console.error(
         JSON.stringify({
-          error: 'Provide --tests-docs, FLOWGRID_TESTS_DOC, or explicit TC-*.yaml paths',
+          error: 'Provide --id, --tests-docs, FLOWGRID_TESTS_DOC, or explicit TC-*.yaml paths',
         }),
       );
       process.exit(1);
@@ -370,10 +426,12 @@ try {
 
 const report = auditE2eCoverage({
   tcDocuments,
-  e2eRoot: parsed.e2eRoot,
+  e2eScanRoots,
+  e2eRoot: e2eScanRoots[0],
   strict: parsed.strict,
   strictMatrix: parsed.strictMatrix,
 });
+report.e2eScanRoots = e2eScanRoots;
 if (parsed.testsDocs ?? resolveTestsDocsRoot()) {
   report.testsDocs = parsed.testsDocs ?? resolveTestsDocsRoot();
 }

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

@@ -12,6 +12,8 @@ export const BUNDLE_META_KEYS = [
   'status',
   'owner',
   'summary',
+  'successMetrics',
+  'nonGoals',
   'userStories',
   'specOrigin',
   'grillStatus'
@@ -36,7 +38,8 @@ export const DESIGN_LAYOUT_KEYS = [
   'behavior',
   'actions',
   'deviations',
-  'i18n'
+  'i18n',
+  'dataModel'
 ]
 
 /**

package/engines/spec/lib/open-qa.mjs

@@ -2,11 +2,20 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { parse } from 'yaml'
 
-/** Walk up from a bundle dir to the docs hub (`qa/open` or `architecture/`). */
+function qaDirHasFiles(qaDir) {
+  if (!existsSync(qaDir)) return false
+  for (const name of readdirSync(qaDir)) {
+    if (/\.ya?ml$/i.test(name)) return true
+    if (name === 'open' && existsSync(path.join(qaDir, 'open'))) return true
+  }
+  return existsSync(path.join(qaDir, 'index.md'))
+}
+
+/** Walk up from a bundle dir to the docs hub (`qa/` or `architecture/`). */
 export function findDocsHubRoot(fromDir) {
   let dir = path.resolve(fromDir)
   for (let i = 0; i < 40; i++) {
-    if (existsSync(path.join(dir, 'qa', 'open')) || existsSync(path.join(dir, 'architecture'))) {
+    if (existsSync(path.join(dir, 'architecture')) || qaDirHasFiles(path.join(dir, 'qa'))) {
       return dir
     }
     const parent = path.dirname(dir)
@@ -16,32 +25,73 @@ export function findDocsHubRoot(fromDir) {
   return null
 }
 
-export function openQaCsv(hubRoot, bundleId) {
-  return getOpenQaDetails(hubRoot, bundleId).csv
+function listQaYamlPaths(hubRoot) {
+  const qaDir = path.join(hubRoot, 'qa')
+  const paths = []
+  if (!existsSync(qaDir)) return paths
+  for (const name of readdirSync(qaDir)) {
+    if (/\.ya?ml$/i.test(name)) paths.push(path.join(qaDir, name))
+  }
+  const openDir = path.join(qaDir, 'open')
+  if (existsSync(openDir)) {
+    for (const name of readdirSync(openDir)) {
+      if (/\.ya?ml$/i.test(name)) paths.push(path.join(openDir, name))
+    }
+  }
+  return paths
+}
+
+function qaAppliesToBundle(doc, stem, bundleId, bundlePath) {
+  if (stem.startsWith(`QA-${bundleId}-`)) return true
+  if (doc?.screen && String(doc.screen) === bundleId) return true
+  const tp = doc?.target?.path
+  if (tp && bundlePath) {
+    const base = path.basename(bundlePath)
+    if (String(tp).includes(base)) return true
+  }
+  return false
+}
+
+function isOpenQa(doc) {
+  if (doc?.status === 'closed') return false
+  if (doc?.status === 'open') return true
+  if (doc?.resolution) return false
+  return true
+}
+
+function questionLine(doc) {
+  if (typeof doc?.question === 'string' && doc.question.trim()) {
+    return doc.question.trim().split('\n')[0]
+  }
+  const updates = Array.isArray(doc?.updates) ? doc.updates : []
+  const q = updates.find((u) => u?.kind === 'question')
+  if (q?.text) return String(q.text).trim().split('\n')[0]
+  const last = updates[updates.length - 1]
+  if (last?.text) return String(last.text).trim().split('\n')[0]
+  return ''
+}
+
+export function openQaCsv(hubRoot, bundleId, bundlePath = '') {
+  return getOpenQaDetails(hubRoot, bundleId, bundlePath).csv
 }
 
-export function getOpenQaDetails(hubRoot, bundleId) {
+export function getOpenQaDetails(hubRoot, bundleId, bundlePath = '') {
   if (!hubRoot || !bundleId) return { csv: '', techDebt: [] }
-  const openDir = path.join(hubRoot, 'qa', 'open')
-  if (!existsSync(openDir)) return { csv: '', techDebt: [] }
-  const prefix = `QA-${bundleId}-`
   const ids = []
   const techDebt = []
-  for (const name of readdirSync(openDir)) {
-    if (!/\.ya?ml$/i.test(name)) continue
-    const stem = name.replace(/\.ya?ml$/i, '')
-    if (!stem.startsWith(prefix)) continue
-    let id = stem
-    let kind = ''
-    let question = ''
+  for (const full of listQaYamlPaths(hubRoot)) {
+    const stem = path.basename(full).replace(/\.ya?ml$/i, '')
+    let doc = {}
     try {
-      const parsed = parse(readFileSync(path.join(openDir, name), 'utf8'))
-      if (parsed && typeof parsed.id === 'string' && parsed.id.trim()) id = parsed.id.trim()
-      if (parsed && typeof parsed.kind === 'string') kind = parsed.kind
-      if (parsed && typeof parsed.question === 'string') question = parsed.question.trim().split('\n')[0]
+      doc = parse(readFileSync(full, 'utf8')) ?? {}
     } catch {
-      /* filename */
+      continue
     }
+    if (!isOpenQa(doc)) continue
+    if (!qaAppliesToBundle(doc, stem, bundleId, bundlePath)) continue
+    const id = typeof doc.id === 'string' && doc.id.trim() ? doc.id.trim() : stem
+    const kind = typeof doc.kind === 'string' ? doc.kind : ''
+    const question = questionLine(doc)
     ids.push(id)
     if (kind === 'tech-debt') {
       techDebt.push({ id, status: 'open', summary: question })
@@ -57,7 +107,7 @@ const QA_FIELD = 'Q&A'
 /** Set or remove `Q&A` on a business spec object (comma-separated ids). */
 export function applyOpenQaField(spec, bundlePath, bundleId) {
   const hub = findDocsHubRoot(path.dirname(path.resolve(bundlePath)))
-  const qa = getOpenQaDetails(hub, bundleId)
+  const qa = getOpenQaDetails(hub, bundleId, bundlePath)
   if (qa.csv) spec[QA_FIELD] = qa.csv
   else delete spec[QA_FIELD]
   if (qa.techDebt && qa.techDebt.length > 0) spec.pendingTechDebt = qa.techDebt

package/engines/spec/split-bundle.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import fs from 'node:fs'
 import path from 'node:path'
 import { checkSplitBundle, splitBundleFile } from './lib/bundle-ir.mjs'
 import { writeBundleMarkdownFile } from '../docs/lib/render-bundle-markdown.mjs'
@@ -30,7 +31,16 @@ async function main() {
       } else {
         const { irDir } = await splitBundleFile(resolved)
         const mdOut = await writeBundleMarkdownFile(resolved)
-        const mdNote = mdOut ? ` + ${path.relative(process.cwd(), mdOut)}` : ' (no MD; missing ir/spec.yaml)'
+        const mdRel = mdOut ? path.relative(process.cwd(), mdOut) : null
+        const genDir = mdOut ? path.dirname(mdOut) : null
+        const extra = genDir
+          ? ['data-model.md', 'api.md']
+              .filter((name) => fs.existsSync(path.join(genDir, name)))
+              .map((name) => path.relative(process.cwd(), path.join(genDir, name)))
+          : []
+        const mdNote = mdRel
+          ? ` + ${mdRel}${extra.length ? ` + ${extra.join(' + ')}` : ''}`
+          : ' (no MD; missing ir/spec.yaml)'
         console.log(`spec:split: ${path.relative(process.cwd(), resolved)} → ${path.relative(process.cwd(), irDir)}/${mdNote}`)
       }
     } catch (error) {

package/engines/testcase/runners/generate-api.mjs

@@ -2,33 +2,34 @@ import path from 'node:path'
 
 import Handlebars from 'handlebars'
 
-import { listFeatureTestcases, readTestcaseFile } from './lib/read-testcase.mjs'
+import { readTestcaseFile } from './lib/read-testcase.mjs'
 import { buildApiTestcaseContext, isApiE2eTestcase } from './lib/api-plan.mjs'
 import { renderTemplate } from './lib/render.mjs'
 import { writeOutputs } from './lib/write-files.mjs'
 import { resolveHubId, resolveProjectRoot, loadTestsIndex } from './lib/resolve-hub-id.mjs'
-import { extractTestsDocsFlag, ENV_TESTS_DOC } from '../../shared/flowgrid-tests-docs.mjs'
+import { ENV_TESTS_DOC } from '../../shared/flowgrid-tests-docs.mjs'
+import {
+  bootstrapTestcaseRun,
+  applyApiOutputLayout,
+} from './lib/bootstrap-context.mjs'
 
-const root = path.resolve(process.env.FLOWGRID_PROJECT_ROOT || process.cwd())
+const boot = bootstrapTestcaseRun(process.argv.slice(2))
+const root = boot.ctx.projectRoot
+const codegenLayout = boot.layout
 
 Handlebars.registerHelper('json', (value) => JSON.stringify(value, null, 2))
 
 function parseArgs(argv) {
-  const { argv: stripped, testsDocs } = extractTestsDocsFlag(argv)
-  if (testsDocs) {
-    process.env[ENV_TESTS_DOC] = testsDocs
-  }
-
   const options = { dryRun: false, force: false, testcase: null, feature: null, id: null, all: false }
 
-  for (let i = 0; i < stripped.length; i++) {
-    const arg = stripped[i]
+  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 === '--all') options.all = true
-    else if (arg === '--testcase') options.testcase = stripped[++i]
-    else if (arg === '--feature') options.feature = stripped[++i]
-    else if (arg === '--id') options.id = stripped[++i]
+    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.all) {
       options.testcase = arg
     }
@@ -55,12 +56,14 @@ async function generateOne(testcasePath, options) {
   }
 
   const ctx = buildApiTestcaseContext(testcase, testcaseFile)
+  applyApiOutputLayout(ctx, codegenLayout)
   const specContent = await renderTemplate('api.spec.ts.hbs', ctx)
   const outputs = [{ relativePath: ctx.outputs.spec, content: specContent }]
 
   const { written, skipped } = await writeOutputs(root, outputs, {
     dryRun: options.dryRun,
     force: options.force,
+    allowedRelRoots: codegenLayout.allowedRelRoots,
   })
 
   console.log(`testcase-gen:api id=${ctx.testcaseId} module=${ctx.module}`)
@@ -76,13 +79,13 @@ async function generateOne(testcasePath, options) {
 }
 
 async function main() {
-  const options = parseArgs(process.argv.slice(2))
+  const options = parseArgs(boot.argv)
   const paths = []
 
   if (options.all) {
-    const testsRoot = process.env[ENV_TESTS_DOC]
-      ? path.resolve(process.env[ENV_TESTS_DOC])
-      : resolveProjectRoot(root, 'tests')
+    const testsRoot = boot.ctx.testsDocs
+      ?? (process.env[ENV_TESTS_DOC] ? path.resolve(process.env[ENV_TESTS_DOC]) : null)
+      ?? resolveProjectRoot(root, 'tests')
     const index = loadTestsIndex(testsRoot)
     for (const [id, rel] of Object.entries(index.codeIds || {})) {
       if (id.startsWith('TC-')) paths.push(path.resolve(testsRoot, rel))
@@ -91,12 +94,9 @@ async function main() {
     paths.push(path.resolve(root, options.testcase))
   } else if (options.feature || options.id) {
     const hubId = options.id ?? options.feature
-    const resolved = await resolveHubId(root, hubId)
-    if (resolved.kind === 'testcase') {
-      paths.push(resolved.absPath)
-    } else if (resolved.kind === 'feature' || resolved.kind === 'screen') {
-      const list = await listFeatureTestcases(resolved.absPath, { repoRoot: root })
-      paths.push(...list)
+    const resolved = resolveHubId(root, hubId, 'testcase')
+    if (resolved.paths?.length) {
+      paths.push(...resolved.paths)
     } else {
       throw new Error(`Could not resolve --id ${hubId} to testcase(s)`)
     }

package/engines/testcase/runners/generate.mjs

@@ -9,9 +9,14 @@ import { renderTemplate } from './lib/render.mjs'
 import { resolveSemanticPlan } from './lib/semantic-plan.mjs'
 import { writeOutputs } from './lib/write-files.mjs'
 import { resolveHubId, resolveProjectRoot, loadTestsIndex } from './lib/resolve-hub-id.mjs'
-import { extractTestsDocsFlag, ENV_TESTS_DOC } from '../../shared/flowgrid-tests-docs.mjs'
+import {
+  bootstrapTestcaseRun,
+  applyUiOutputLayout,
+} from './lib/bootstrap-context.mjs'
 
-const root = path.resolve(process.env.FLOWGRID_PROJECT_ROOT || process.env.FLOWGRID_PROJECT_ROOT || process.cwd())
+const boot = bootstrapTestcaseRun(process.argv.slice(2))
+const root = boot.ctx.projectRoot
+const codegenLayout = boot.layout
 
 Handlebars.registerHelper('eq', (a, b) => a === b)
 Handlebars.registerHelper('and', (a, b) => a && b)
@@ -29,21 +34,16 @@ Handlebars.registerHelper('pascalCase', (value) => {
 })
 
 function parseArgs(argv) {
-  const { argv: stripped, testsDocs } = extractTestsDocsFlag(argv)
-  if (testsDocs) {
-    process.env[ENV_TESTS_DOC] = testsDocs
-  }
-
   const options = { dryRun: false, force: false, testcase: null, feature: null, id: null, all: false }
 
-  for (let i = 0; i < stripped.length; i++) {
-    const arg = stripped[i]
+  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 === '--all') options.all = true
-    else if (arg === '--testcase') options.testcase = stripped[++i]
-    else if (arg === '--feature') options.feature = stripped[++i]
-    else if (arg === '--id') options.id = stripped[++i]
+    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.all) {
       options.testcase = arg
     }
@@ -65,6 +65,7 @@ async function generateOne(testcasePath, options) {
   const { testcase, spec, testcaseFile, specFile } = await readTestcaseFile(testcasePath, { repoRoot: root })
   const ctx = buildTestcaseContext(testcase, spec, testcaseFile)
   ctx.specFile = specFile
+  applyUiOutputLayout(ctx, codegenLayout)
 
   const semantic = await resolveSemanticPlan(root, testcase)
   ctx.useSemanticFixture = semantic.useSemanticFixture
@@ -84,7 +85,8 @@ async function generateOne(testcasePath, options) {
 
   const { written, skipped } = await writeOutputs(root, outputs, {
     dryRun: options.dryRun,
-    force: options.force
+    force: options.force,
+    allowedRelRoots: codegenLayout.allowedRelRoots,
   })
 
   console.log(`testcase-gen: id=${ctx.testcaseId} module=${ctx.module}`)
@@ -104,12 +106,12 @@ async function generateOne(testcasePath, options) {
 }
 
 async function main() {
-  const options = parseArgs(process.argv.slice(2))
+  const options = parseArgs(boot.argv)
 
   if (options.all) {
-    const testsRoot = process.env.FLOWGRID_TESTS_DOC
-      ? path.resolve(process.env.FLOWGRID_TESTS_DOC)
-      : resolveProjectRoot(root, 'tests')
+    const testsRoot = boot.ctx.testsDocs
+      ?? (process.env.FLOWGRID_TESTS_DOC ? path.resolve(process.env.FLOWGRID_TESTS_DOC) : null)
+      ?? resolveProjectRoot(root, 'tests')
     const index = loadTestsIndex(testsRoot)
     const paths = []
     for (const [id, rel] of Object.entries(index.codeIds || {})) {

package/engines/testcase/runners/lib/bootstrap-context.mjs

@@ -0,0 +1,44 @@
+import { resolveFlowgridContext, flowgridContextToEnv } from '../../../shared/resolve-flowgrid-context.mjs';
+import { codegenOutputLayout } from '../../../shared/e2e-output-layout.mjs';
+import { extractTestsDocsFlag, ENV_TESTS_DOC } from '../../../shared/flowgrid-tests-docs.mjs';
+
+/**
+ * Resolve project/tests/e2e pointers and apply FLOWGRID_* env before testcase engines run.
+ * @param {string[]} argv raw process argv slice (after command name)
+ */
+export function bootstrapTestcaseRun(argv) {
+  const { argv: afterTestsFlag, testsDocs: testsFromFlag } = extractTestsDocsFlag(argv);
+  const ctx = resolveFlowgridContext({ argv: afterTestsFlag });
+  if (testsFromFlag) {
+    ctx.testsDocs = testsFromFlag;
+  }
+  Object.assign(process.env, flowgridContextToEnv(ctx));
+  if (ctx.testsDocs) {
+    process.env[ENV_TESTS_DOC] = ctx.testsDocs;
+  }
+  const layout = codegenOutputLayout(ctx.projectRoot, ctx.e2eRoot, {
+    projectType: ctx.config?.type,
+  });
+  return { ctx, layout, argv: ctx.argv };
+}
+
+/**
+ * @param {import('../../../shared/e2e-output-layout.mjs').codegenOutputLayout} layout
+ * @param {{ outputs: { pageObject: string, spec: string }, module: string, pageClassName: string, testcaseId: string }} ctx
+ */
+export function applyUiOutputLayout(ctx, layout) {
+  ctx.outputs = {
+    pageObject: `${layout.uiPrefix}/pages/${ctx.module}/${ctx.pageClassName}.ts`,
+    spec: `${layout.uiPrefix}/${ctx.module}/${ctx.testcaseId}.spec.ts`,
+  };
+}
+
+/**
+ * @param {{ outputs: { spec: string }, module: string, testcaseId: string }} ctx
+ * @param layout
+ */
+export function applyApiOutputLayout(ctx, layout) {
+  ctx.outputs = {
+    spec: `${layout.apiPrefix}/${ctx.module}/${ctx.testcaseId}.api.spec.ts`,
+  };
+}