@sun-asterisk/sungen 2.5.1 → 2.6.0

package/dist/orchestrator/templates/specs-base.ts

@@ -1,5 +1,4 @@
 import { test as base, expect } from '@playwright/test';
-import type { BrowserContext, Page } from '@playwright/test';
 
 type CleanupConfig = {
   overlay?: boolean;
@@ -8,11 +7,6 @@ type CleanupConfig = {
   storage?: boolean;
 };
 
-// Share one context per storageState — avoids creating multiple sessions
-// that trigger server rate limiting or session invalidation
-const contextCache = new Map<string, { context: BrowserContext; page: Page }>();
-const GOTO_PATCHED = Symbol('goto-patched');
-
 const test = base.extend<{
   autoCleanup: CleanupConfig;
   screenshotOnFailure: boolean;
@@ -23,69 +17,25 @@ const test = base.extend<{
   screenshotOnFailure: [false, { option: true }],
 
   page: async ({ browser, storageState }, use) => {
-    if (storageState) {
-      const cacheKey = typeof storageState === 'string' ? storageState : JSON.stringify(storageState);
-
-      let cached = contextCache.get(cacheKey);
-      if (!cached) {
-        const context = await browser.newContext({ storageState });
-        const page = await context.newPage();
-        cached = { context, page };
-        contextCache.set(cacheKey, cached);
-      }
-
-      const page = cached.page;
-
-      // Patch goto once: skip navigation if already on the target path
-      if (!(page as any)[GOTO_PATCHED]) {
-        const originalGoto = page.goto.bind(page);
-        page.goto = async function (url: string, options?: any) {
-          try {
-            const currentPath = new URL(page.url()).pathname;
-            if (currentPath === url || currentPath === url + '/') {
-              const hasOverlay = await page.evaluate(`(() => {
-                const el = document.elementFromPoint(window.innerWidth / 2, window.innerHeight / 2);
-                if (!el) return false;
-                let current = el;
-                while (current && current !== document.body) {
-                  if (getComputedStyle(current).position === 'fixed') return true;
-                  current = current.parentElement;
-                }
-                return false;
-              })()`).catch(() => true);
-
-              if (hasOverlay) {
-                return originalGoto(url, options);
-              }
-              return null as any;
-            }
-          } catch {
-            // page.url() might be about:blank on first run
-          }
-          return originalGoto(url, options);
-        };
-        (page as any)[GOTO_PATCHED] = true;
-      }
-
-      await use(page);
-    } else {
-      // No storageState: fresh context (e.g., unauthenticated tests)
-      const context = await browser.newContext();
-      const page = await context.newPage();
-      await use(page);
-      await page.close();
-      await context.close();
-    }
+    const context = storageState
+      ? await browser.newContext({ storageState })
+      : await browser.newContext();
+    const page = await context.newPage();
+    await use(page);
+    await page.close();
+    await context.close();
   },
 
   // Auto-cleanup fixture: runs teardown after each test based on @cleanup:* tags
-  _autoCleanup: [async ({ page, autoCleanup }, use) => {
+  _autoCleanup: [async ({ page, autoCleanup }, use, testInfo) => {
     await use();
 
+    // Only run cleanup when the test failed — avoids masking state for the next test
+    if (testInfo.status === testInfo.expectedStatus) return;
+
     if (autoCleanup.overlay) {
       await page.keyboard.press('Escape').catch(() => {});
       await page.locator('body').click({ position: { x: 1, y: 1 }, force: true }).catch(() => {});
-      // Dismiss persistent fixed overlays (modals, dialogs)
       const hasOverlay = await page.evaluate(`(() => {
         const el = document.elementFromPoint(window.innerWidth / 2, window.innerHeight / 2);
         if (!el) return false;

package/dist/orchestrator/templates/specs-test-data.d.ts

@@ -2,11 +2,13 @@ export declare class TestDataLoader {
     private data;
     private constructor();
     /**
-     * Load test data for a screen/feature combination.
+     * Load test data for a screen/feature or flow/feature combination.
      *
      * Priority (later wins):
      * 1. {feature}.yaml — base data
      * 2. {feature}.{SUNGEN_ENV}.yaml — environment-specific (if SUNGEN_ENV set)
+     *
+     * Paths: screenName starting with "flows/" loads from qa/flows/, otherwise qa/screens/
      */
     static load(screenName: string, featureName: string): TestDataLoader;
     get(key: string): string;

package/dist/orchestrator/templates/specs-test-data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"specs-test-data.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-test-data.ts"],"names":[],"mappings":"AAIA,qBAAa,cAAc;IACzB,OAAO,CAAC,IAAI,CAAsB;IAElC,OAAO;IAIP;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc;IAcpE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;CAczB"}
+{"version":3,"file":"specs-test-data.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-test-data.ts"],"names":[],"mappings":"AAIA,qBAAa,cAAc;IACzB,OAAO,CAAC,IAAI,CAAsB;IAElC,OAAO;IAIP;;;;;;;;OAQG;IACH,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc;IAmBpE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;CAczB"}

package/dist/orchestrator/templates/specs-test-data.js

@@ -45,14 +45,22 @@ class TestDataLoader {
         this.data = data;
     }
     /**
-     * Load test data for a screen/feature combination.
+     * Load test data for a screen/feature or flow/feature combination.
      *
      * Priority (later wins):
      * 1. {feature}.yaml — base data
      * 2. {feature}.{SUNGEN_ENV}.yaml — environment-specific (if SUNGEN_ENV set)
+     *
+     * Paths: screenName starting with "flows/" loads from qa/flows/, otherwise qa/screens/
      */
     static load(screenName, featureName) {
-        const baseDir = path.join(process.cwd(), 'qa', 'screens', screenName, 'test-data');
+        let baseDir;
+        if (screenName.startsWith('flows/')) {
+            baseDir = path.join(process.cwd(), 'qa', screenName, 'test-data');
+        }
+        else {
+            baseDir = path.join(process.cwd(), 'qa', 'screens', screenName, 'test-data');
+        }
         const env = process.env.SUNGEN_ENV;
         let data = loadYamlSync(path.join(baseDir, `${featureName}.yaml`)) || {};
         if (env) {

package/dist/orchestrator/templates/specs-test-data.js.map

@@ -1 +1 @@
-{"version":3,"file":"specs-test-data.js","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-test-data.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"specs-test-data.js","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-test-data.ts"],"names":[],"mappings":"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"}

package/dist/orchestrator/templates/specs-test-data.ts

@@ -10,14 +10,21 @@ export class TestDataLoader {
   }
 
   /**
-   * Load test data for a screen/feature combination.
+   * Load test data for a screen/feature or flow/feature combination.
    *
    * Priority (later wins):
    * 1. {feature}.yaml — base data
    * 2. {feature}.{SUNGEN_ENV}.yaml — environment-specific (if SUNGEN_ENV set)
+   *
+   * Paths: screenName starting with "flows/" loads from qa/flows/, otherwise qa/screens/
    */
   static load(screenName: string, featureName: string): TestDataLoader {
-    const baseDir = path.join(process.cwd(), 'qa', 'screens', screenName, 'test-data');
+    let baseDir: string;
+    if (screenName.startsWith('flows/')) {
+      baseDir = path.join(process.cwd(), 'qa', screenName, 'test-data');
+    } else {
+      baseDir = path.join(process.cwd(), 'qa', 'screens', screenName, 'test-data');
+    }
     const env = process.env.SUNGEN_ENV;
 
     let data = loadYamlSync(path.join(baseDir, `${featureName}.yaml`)) || {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/cli/commands/add-flow.ts

@@ -0,0 +1,25 @@
+import { Command } from 'commander';
+
+export function registerAddFlowCommand(program: Command): void {
+  program
+    .command('add-flow')
+    .description('Add a flow definition with scaffolded files for E2E cross-screen testing')
+    .requiredOption('--flow <name>', 'Flow name')
+    .option('-p, --path <path>', 'Starting page route path (e.g. /login)')
+    .option('-d, --description <text>', 'Flow description')
+    .action(async (options) => {
+      try {
+        const { FlowManager } = require('../../orchestrator/flow-manager');
+        const manager = new FlowManager();
+
+        await manager.addFlow({
+          name: options.flow,
+          path: options.path,
+          description: options.description,
+        });
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/delivery.ts

@@ -9,7 +9,7 @@ import * as fs from 'fs';
 import { execSync } from 'child_process';
 import { parseFeatureMetadata } from '../../exporters/feature-parser';
 import { parseSpecFile } from '../../exporters/spec-parser';
-import { loadTestData, resolveTestDataPath } from '../../exporters/test-data-resolver';
+import { loadTestData } from '../../exporters/test-data-resolver';
 import { loadPlaywrightReport } from '../../exporters/playwright-report-parser';
 import { mergeFeatureAndSpec } from '../../exporters/scenario-merger';
 import {
@@ -39,14 +39,46 @@ function log(msg: string): void {
 // Discovery
 // ----------------------------------------------------------------------------
 
-function listAllScreens(cwd: string): string[] {
+interface DeliveryTarget {
+  name: string;
+  isFlow: boolean;
+}
+
+function listAllTargets(cwd: string): DeliveryTarget[] {
+  const targets: DeliveryTarget[] = [];
+
   const screensDir = path.join(cwd, 'qa', 'screens');
-  if (!fs.existsSync(screensDir)) return [];
-  return fs
-    .readdirSync(screensDir, { withFileTypes: true })
-    .filter((d) => d.isDirectory())
-    .map((d) => d.name)
-    .sort();
+  if (fs.existsSync(screensDir)) {
+    for (const d of fs.readdirSync(screensDir, { withFileTypes: true })) {
+      if (d.isDirectory()) targets.push({ name: d.name, isFlow: false });
+    }
+  }
+
+  const flowsDir = path.join(cwd, 'qa', 'flows');
+  if (fs.existsSync(flowsDir)) {
+    for (const d of fs.readdirSync(flowsDir, { withFileTypes: true })) {
+      if (d.isDirectory()) targets.push({ name: d.name, isFlow: true });
+    }
+  }
+
+  return targets.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function resolveTargetType(cwd: string, name: string): DeliveryTarget {
+  if (fs.existsSync(path.join(cwd, 'qa', 'flows', name))) {
+    return { name, isFlow: true };
+  }
+  return { name, isFlow: false };
+}
+
+function qaDir(cwd: string, target: DeliveryTarget): string {
+  return path.join(cwd, 'qa', target.isFlow ? 'flows' : 'screens', target.name);
+}
+
+function generatedDir(cwd: string, target: DeliveryTarget): string {
+  return target.isFlow
+    ? path.join(cwd, 'specs', 'generated', 'flows', target.name)
+    : path.join(cwd, 'specs', 'generated', target.name);
 }
 
 // ----------------------------------------------------------------------------
@@ -54,56 +86,65 @@ function listAllScreens(cwd: string): string[] {
 // ----------------------------------------------------------------------------
 
 /**
- * Resolve the results file path for a screen.
- * Prefer the per-screen co-located file, fall back to the global `test-results/results.json`.
+ * Resolve the results file path for a target.
+ * Prefer the per-target co-located file, fall back to the global `test-results/results.json`.
  */
-function resolveResultsPath(cwd: string, screen: string): string | null {
-  const perScreen = path.join(cwd, 'specs', 'generated', screen, `${screen}-test-result.json`);
-  if (fs.existsSync(perScreen)) return perScreen;
+function resolveResultsPath(cwd: string, target: DeliveryTarget): string | null {
+  const genDir = generatedDir(cwd, target);
+  const perTarget = path.join(genDir, `${target.name}-test-result.json`);
+  if (fs.existsSync(perTarget)) return perTarget;
   const global = path.join(cwd, 'test-results', 'results.json');
   if (fs.existsSync(global)) return global;
   return null;
 }
 
-function runPreflight(cwd: string, screen: string): PreflightCheck {
-  const featureFile = path.join(cwd, 'qa', 'screens', screen, 'features', `${screen}.feature`);
-  const testDataFile = resolveTestDataPath(cwd, screen);
-  const selectorsFile = path.join(cwd, 'qa', 'screens', screen, 'selectors', `${screen}.yaml`);
-  const specFile = path.join(cwd, 'specs', 'generated', screen, `${screen}.spec.ts`);
-  const resultsFile = resolveResultsPath(cwd, screen);
+function resolveTestDataPathForTarget(cwd: string, target: DeliveryTarget): string {
+  return path.join(qaDir(cwd, target), 'test-data', `${target.name}.yaml`);
+}
+
+function runPreflight(cwd: string, target: DeliveryTarget): PreflightCheck {
+  const base = qaDir(cwd, target);
+  const genBase = generatedDir(cwd, target);
+  const featureFile = path.join(base, 'features', `${target.name}.feature`);
+  const testDataFile = resolveTestDataPathForTarget(cwd, target);
+  const selectorsFile = path.join(base, 'selectors', `${target.name}.yaml`);
+  const specFile = path.join(genBase, `${target.name}.spec.ts`);
+  const resultsFile = resolveResultsPath(cwd, target);
 
   const featureOk = checkFeatureReal(featureFile);
   const testDataOk = checkTestDataHasVars(testDataFile);
-  const selectorsOk = checkSelectorsHasEntries(selectorsFile, screen);
+  const selectorsOk = checkSelectorsHasEntries(selectorsFile, target.name);
   const specOk = fs.existsSync(specFile);
   const resultsOk = resultsFile !== null;
 
+  const label = target.isFlow ? `flow/${target.name}` : target.name;
   const missing: string[] = [];
   const suggestions: string[] = [];
 
   if (!featureOk) {
     missing.push(`feature file missing/empty: ${path.relative(cwd, featureFile)}`);
-    suggestions.push(`/sungen:create-test ${screen}`);
+    suggestions.push(`/sungen:create-test ${target.name}`);
   }
   if (!testDataOk) {
     missing.push(`test-data.yaml has no variables: ${path.relative(cwd, testDataFile)}`);
-    suggestions.push(`/sungen:create-test ${screen}`);
+    suggestions.push(`/sungen:create-test ${target.name}`);
   }
   if (!selectorsOk) {
     missing.push(`selectors.yaml missing entries: ${path.relative(cwd, selectorsFile)}`);
-    suggestions.push(`/sungen:run-test ${screen}`);
+    suggestions.push(`/sungen:run-test ${target.name}`);
   }
   if (!specOk) {
     missing.push(`compiled .spec.ts missing: ${path.relative(cwd, specFile)}`);
-    suggestions.push(`sungen generate --screen ${screen}`);
+    suggestions.push(target.isFlow ? `sungen generate --flow ${target.name}` : `sungen generate --screen ${target.name}`);
   }
   if (!resultsOk) {
     missing.push(`test-result.json missing (optional)`);
-    suggestions.push(`PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/${screen}/${screen}-test-result.json npx playwright test specs/generated/${screen}/${screen}.spec.ts`);
+    const genRel = path.relative(cwd, genBase);
+    suggestions.push(`PLAYWRIGHT_JSON_OUTPUT_NAME=${genRel}/${target.name}-test-result.json npx playwright test ${genRel}/${target.name}.spec.ts`);
   }
 
   return {
-    screen,
+    screen: label,
     featureOk,
     testDataOk,
     selectorsOk,
@@ -178,16 +219,19 @@ function getEnvironment(cwd: string): EnvironmentInfo {
 // Per-screen export
 // ----------------------------------------------------------------------------
 
-async function exportScreen(
+async function exportTarget(
   cwd: string,
-  screen: string,
+  target: DeliveryTarget,
   env: EnvironmentInfo
 ): Promise<ScreenSummary | null> {
-  const featureFile = path.join(cwd, 'qa', 'screens', screen, 'features', `${screen}.feature`);
-  const testDataFile = resolveTestDataPath(cwd, screen);
-  const specFile = path.join(cwd, 'specs', 'generated', screen, `${screen}.spec.ts`);
-  const resultsFile = resolveResultsPath(cwd, screen);
-  const specMdFile = path.join(cwd, 'qa', 'screens', screen, 'requirements', 'spec.md');
+  const base = qaDir(cwd, target);
+  const genBase = generatedDir(cwd, target);
+  const featureFile = path.join(base, 'features', `${target.name}.feature`);
+  const testDataFile = resolveTestDataPathForTarget(cwd, target);
+  const specFile = path.join(genBase, `${target.name}.spec.ts`);
+  const resultsFile = resolveResultsPath(cwd, target);
+  const specMdFile = path.join(base, 'requirements', 'spec.md');
+  const label = target.isFlow ? `flow/${target.name}` : target.name;
 
   try {
     const feature = parseFeatureMetadata(featureFile);
@@ -197,7 +241,7 @@ async function exportScreen(
 
     const merged = mergeFeatureAndSpec(feature, spec);
     const rows = buildTestCaseRows({
-      screen,
+      screen: label,
       featureName: feature.featureName,
       merged,
       testData,
@@ -206,14 +250,14 @@ async function exportScreen(
     });
 
     const specLink = fs.existsSync(specMdFile) ? path.relative(cwd, specMdFile) : '';
-    const tempSummary = buildSummary(screen, rows, '');
+    const tempSummary = buildSummary(label, rows, '');
     const csv = renderCsv(tempSummary, rows, specLink);
-    const csvPath = writeCsv(cwd, screen, csv);
+    const csvPath = writeCsv(cwd, target.name, csv);
     const wb = renderXlsx(tempSummary, rows, specLink);
-    await writeXlsx(cwd, screen, wb);
-    return buildSummary(screen, rows, path.relative(cwd, csvPath));
+    await writeXlsx(cwd, target.name, wb);
+    return buildSummary(label, rows, path.relative(cwd, csvPath));
   } catch (err) {
-    console.error(`${COLOR.red}Error exporting ${screen}:${COLOR.reset} ${err instanceof Error ? err.message : err}`);
+    console.error(`${COLOR.red}Error exporting ${label}:${COLOR.reset} ${err instanceof Error ? err.message : err}`);
     return null;
   }
 }
@@ -284,57 +328,64 @@ export function registerDeliveryCommand(program: Command): void {
   program
     .command('delivery')
     .description('Export Gherkin + Playwright results → CSV test case deliverable')
-    .argument('[screens...]', 'Specific screen names. Omit to process all screens.')
+    .argument('[names...]', 'Specific screen or flow names. Omit to process all.')
     .option('--skip-preflight', 'Skip pre-flight checks (not recommended)')
-    .option('--continue-on-missing', 'Skip screens with blocking misses instead of aborting')
-    .action(async (screens: string[], options: { skipPreflight?: boolean; continueOnMissing?: boolean }) => {
+    .option('--continue-on-missing', 'Skip targets with blocking misses instead of aborting')
+    .action(async (names: string[], options: { skipPreflight?: boolean; continueOnMissing?: boolean }) => {
       try {
         const cwd = process.cwd();
 
         // 1. Scope detection
-        let targetScreens: string[];
-        if (screens && screens.length > 0) {
-          targetScreens = screens;
+        let targets: DeliveryTarget[];
+        if (names && names.length > 0) {
+          targets = names.map((n) => resolveTargetType(cwd, n));
         } else {
-          targetScreens = listAllScreens(cwd);
-          if (targetScreens.length === 0) {
-            console.error(`${COLOR.red}No screens found in qa/screens/${COLOR.reset}`);
+          targets = listAllTargets(cwd);
+          if (targets.length === 0) {
+            console.error(`${COLOR.red}No screens or flows found in qa/screens/ or qa/flows/${COLOR.reset}`);
             process.exit(1);
           }
         }
 
-        log(`${COLOR.bold}sungen delivery${COLOR.reset} — exporting ${targetScreens.length} screen(s): ${targetScreens.join(', ')}\n`);
+        const labels = targets.map((t) => t.isFlow ? `flow/${t.name}` : t.name);
+        log(`${COLOR.bold}sungen delivery${COLOR.reset} — exporting ${targets.length} target(s): ${labels.join(', ')}\n`);
 
         // 2. Pre-flight
-        let toExport: string[];
+        let toExport: DeliveryTarget[];
         if (options.skipPreflight) {
-          toExport = targetScreens;
+          toExport = targets;
         } else {
-          const checks = targetScreens.map((s) => runPreflight(cwd, s));
+          const checks = targets.map((t) => runPreflight(cwd, t));
           printPreflightTable(checks);
 
           const blockers = checks.filter(hasBlockingMissing);
           if (blockers.length > 0) {
             if (options.continueOnMissing) {
-              toExport = checks.filter((c) => !hasBlockingMissing(c)).map((c) => c.screen);
-              log(`${COLOR.yellow}Continuing with ${toExport.length} ready screen(s).${COLOR.reset}\n`);
+              const passedScreens = new Set(
+                checks.filter((c) => !hasBlockingMissing(c)).map((c) => c.screen)
+              );
+              toExport = targets.filter((t) => {
+                const label = t.isFlow ? `flow/${t.name}` : t.name;
+                return passedScreens.has(label);
+              });
+              log(`${COLOR.yellow}Continuing with ${toExport.length} ready target(s).${COLOR.reset}\n`);
             } else {
               console.error(
-                `${COLOR.red}Aborted:${COLOR.reset} ${blockers.length} screen(s) have blocking issues.\n` +
+                `${COLOR.red}Aborted:${COLOR.reset} ${blockers.length} target(s) have blocking issues.\n` +
                 `Run the suggested commands above, or use ${COLOR.cyan}--continue-on-missing${COLOR.reset} to skip them.`
               );
               process.exit(1);
             }
           } else {
-            toExport = checks.map((c) => c.screen);
+            toExport = targets;
           }
         }
 
         // 3. Export
         const env = getEnvironment(cwd);
         const summaries: ScreenSummary[] = [];
-        for (const screen of toExport) {
-          const s = await exportScreen(cwd, screen, env);
+        for (const target of toExport) {
+          const s = await exportTarget(cwd, target, env);
           if (s) summaries.push(s);
         }
 

package/src/cli/commands/generate.ts

@@ -31,11 +31,20 @@ function findFeatureFilesForScreen(screenName: string): string[] {
 }
 
 /**
- * Find all feature files across all screens
+ * Find feature files for a specific flow
+ */
+function findFeatureFilesForFlow(flowName: string): string[] {
+  const flowFeaturesDir = path.join(process.cwd(), 'qa', 'flows', flowName, 'features');
+  return findFeatureFiles(flowFeaturesDir);
+}
+
+/**
+ * Find all feature files across all screens and flows
  */
 function findAllFeatureFiles(): string[] {
   const allFiles: string[] = [];
   const screensDir = path.join(process.cwd(), 'qa', 'screens');
+  const flowsDir = path.join(process.cwd(), 'qa', 'flows');
 
   if (fs.existsSync(screensDir)) {
     const screenDirs = fs.readdirSync(screensDir, { withFileTypes: true })
@@ -48,6 +57,17 @@ function findAllFeatureFiles(): string[] {
     }
   }
 
+  if (fs.existsSync(flowsDir)) {
+    const flowDirs = fs.readdirSync(flowsDir, { withFileTypes: true })
+      .filter(entry => entry.isDirectory())
+      .map(entry => entry.name);
+
+    for (const flowName of flowDirs) {
+      const flowFeaturesDir = path.join(flowsDir, flowName, 'features');
+      allFiles.push(...findFeatureFiles(flowFeaturesDir));
+    }
+  }
+
   return allFiles;
 }
 
@@ -56,15 +76,19 @@ export function registerGenerateCommand(program: Command): void {
     .command('generate')
     .description('Generate Playwright test code from Gherkin features')
     .option('-s, --screen <name>', 'Generate tests for a specific screen')
-    .option('--all', 'Generate tests for all screens')
+    .option('--flow <name>', 'Generate tests for a specific flow')
+    .option('--all', 'Generate tests for all screens and flows')
     .option('--framework <name>', 'Test framework (default: playwright)', 'playwright')
     .option('--inline-data', 'Hardcode test data at compile time instead of runtime loading')
     .action(async (options) => {
       try {
         const screenName = options.screen;
+        const flowName = options.flow;
 
         // Find feature files
         let featureFiles: string[];
+        let qaSourceDir: string;
+
         if (screenName) {
           featureFiles = findFeatureFilesForScreen(screenName);
           if (featureFiles.length === 0) {
@@ -73,13 +97,25 @@ export function registerGenerateCommand(program: Command): void {
               `Looked in: qa/screens/${screenName}/features/`
             );
           }
+          qaSourceDir = path.join(process.cwd(), 'qa', 'screens');
           console.log(`\nGenerating tests: ${screenName}\n`);
+        } else if (flowName) {
+          featureFiles = findFeatureFilesForFlow(flowName);
+          if (featureFiles.length === 0) {
+            throw new Error(
+              `No feature files found for flow: ${flowName}\n` +
+              `Looked in: qa/flows/${flowName}/features/`
+            );
+          }
+          qaSourceDir = path.join(process.cwd(), 'qa', 'flows');
+          console.log(`\nGenerating tests: flow/${flowName}\n`);
         } else {
           featureFiles = findAllFeatureFiles();
           if (featureFiles.length === 0) {
-            throw new Error('No feature files found in qa/screens/');
+            throw new Error('No feature files found in qa/screens/ or qa/flows/');
           }
-          console.log(`\nGenerating tests for all screens\n`);
+          qaSourceDir = path.join(process.cwd(), 'qa');
+          console.log(`\nGenerating tests for all screens and flows\n`);
         }
 
         // Output directory
@@ -88,13 +124,14 @@ export function registerGenerateCommand(program: Command): void {
         // Create generator and compile
         const generator = new CodeGenerator({
           framework: options.framework || 'playwright',
-          screenName,
+          screenName: screenName || flowName,
           verbose: program.opts().verbose,
           runtimeData: !options.inlineData,
+          flowMode: !!flowName,
         });
 
         const results = await generator.generateAllTests(
-          path.join(process.cwd(), 'qa', 'screens'),
+          qaSourceDir,
           outputDir,
           featureFiles
         );

package/src/cli/index.ts

@@ -12,6 +12,7 @@ import { registerMakeauthCommand } from './commands/makeauth';
 import { registerUpdateCommand } from './commands/update';
 import { registerDeliveryCommand } from './commands/delivery';
 import { registerFigmaCommand } from './commands/figma';
+import { registerAddFlowCommand } from './commands/add-flow';
 
 async function main() {
   const program = new Command();
@@ -19,7 +20,7 @@ async function main() {
   program
     .name('sungen')
     .description('Deterministic E2E Test Compiler — Gherkin + Selectors → Playwright')
-    .version('2.5.1');
+    .version('2.6.0');
 
   // Global options
   program
@@ -33,6 +34,7 @@ async function main() {
   registerUpdateCommand(program);
   registerDeliveryCommand(program);
   registerFigmaCommand(program);
+  registerAddFlowCommand(program);
 
   await program.parseAsync(process.argv);
 }

package/src/generators/test-generator/adapters/adapter-interface.ts

@@ -57,7 +57,7 @@ export interface TestGeneratorAdapter {
   // Template rendering methods
   renderTestFile(data: TestFileData): string;
   renderScenario(data: ScenarioData): string;
-  renderImports(options?: { runtimeData?: boolean }): string;
+  renderImports(options?: { runtimeData?: boolean; basePath?: string }): string;
   renderBeforeEach(data: { steps: Array<{ comment?: string; code: string }> }): string;
   renderBeforeAll(data: { steps: Array<{ comment?: string; code: string }> }): string;
   renderAfterEach(data: { steps: Array<{ comment?: string; code: string }> }): string;

package/src/generators/test-generator/adapters/playwright/playwright-adapter.ts

@@ -26,7 +26,7 @@ export class PlaywrightAdapter implements TestGeneratorAdapter {
     return this.templateEngine.renderScenario(data);
   }
 
-  renderImports(options?: { runtimeData?: boolean }): string {
+  renderImports(options?: { runtimeData?: boolean; basePath?: string }): string {
     return this.templateEngine.renderImports(options);
   }