@sun-asterisk/sungen 2.4.6 → 2.5.1

package/dist/tools/figma/figma-rest-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-rest-client.js","sourceRoot":"","sources":["../../../src/tools/figma/figma-rest-client.ts"],"names":[],"mappings":"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"}

package/dist/tools/figma/figma-url-parser.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Offline Figma URL parser.
+ * Converts Figma share URLs → { fileKey, nodeId } without any network call.
+ *
+ * Supported URL forms:
+ *   https://www.figma.com/design/<KEY>/<name>?node-id=1-23
+ *   https://www.figma.com/file/<KEY>/<name>?node-id=1%3A23   (legacy + percent-encoded)
+ *   https://www.figma.com/design/<KEY>/<name>                (no node selected)
+ */
+import type { FigmaNodeRef } from './figma-client-types';
+/**
+ * Parse a Figma share URL into a structured reference.
+ *
+ * @param url - Full Figma URL string.
+ * @returns `{ fileKey, nodeId? }` on success, `null` if URL is not a valid Figma URL.
+ */
+export declare function parseFigmaUrl(url: string): FigmaNodeRef | null;
+//# sourceMappingURL=figma-url-parser.d.ts.map

package/dist/tools/figma/figma-url-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-url-parser.d.ts","sourceRoot":"","sources":["../../../src/tools/figma/figma-url-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAuBzD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAe9D"}

package/dist/tools/figma/figma-url-parser.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Offline Figma URL parser.
+ * Converts Figma share URLs → { fileKey, nodeId } without any network call.
+ *
+ * Supported URL forms:
+ *   https://www.figma.com/design/<KEY>/<name>?node-id=1-23
+ *   https://www.figma.com/file/<KEY>/<name>?node-id=1%3A23   (legacy + percent-encoded)
+ *   https://www.figma.com/design/<KEY>/<name>                (no node selected)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFigmaUrl = parseFigmaUrl;
+/**
+ * Regex captures:
+ *   group 1 → path type: "design" | "file"
+ *   group 2 → fileKey (alphanumeric)
+ *   group 3 → raw node-id query param value (may be absent)
+ */
+const FIGMA_URL_RE = /^https?:\/\/(?:www\.)?figma\.com\/(design|file)\/([A-Za-z0-9]+)(?:\/[^?#]*)?(?:[?&].*?node-id=([\w%:.-]+))?/;
+/**
+ * Convert URL-form node-id to Figma API form.
+ *   "1-23"   → "1:23"
+ *   "1%3A23" → "1:23"  (percent-encoded colon)
+ *   "1:23"   → "1:23"  (already correct)
+ */
+function normalizeNodeId(raw) {
+    const decoded = decodeURIComponent(raw);
+    // Replace dash separator only between two digit groups (Figma node-id pattern)
+    return decoded.replace(/^(\d+)-(\d+)$/, '$1:$2');
+}
+/**
+ * Parse a Figma share URL into a structured reference.
+ *
+ * @param url - Full Figma URL string.
+ * @returns `{ fileKey, nodeId? }` on success, `null` if URL is not a valid Figma URL.
+ */
+function parseFigmaUrl(url) {
+    if (!url || typeof url !== 'string')
+        return null;
+    const match = FIGMA_URL_RE.exec(url.trim());
+    if (!match)
+        return null;
+    const fileKey = match[2];
+    const rawNodeId = match[3];
+    const result = { fileKey };
+    if (rawNodeId) {
+        result.nodeId = normalizeNodeId(rawNodeId);
+    }
+    return result;
+}
+//# sourceMappingURL=figma-url-parser.js.map

package/dist/tools/figma/figma-url-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-url-parser.js","sourceRoot":"","sources":["../../../src/tools/figma/figma-url-parser.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AA+BH,sCAeC;AA1CD;;;;;GAKG;AACH,MAAM,YAAY,GAChB,6GAA6G,CAAC;AAEhH;;;;;GAKG;AACH,SAAS,eAAe,CAAC,GAAW;IAClC,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACxC,+EAA+E;IAC/E,OAAO,OAAO,CAAC,OAAO,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,GAAW;IACvC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEjD,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAExB,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACzB,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAE3B,MAAM,MAAM,GAAiB,EAAE,OAAO,EAAE,CAAC;IACzC,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,CAAC,MAAM,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;IAC7C,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/utils/exec-file-no-throw.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Safe execFile wrapper — uses execFile (not exec) to prevent shell injection.
+ * Handles Windows compatibility and provides structured output.
+ */
+export interface ExecFileResult {
+    stdout: string;
+    stderr: string;
+    /** Process exit code; 0 = success. */
+    status: number;
+}
+/**
+ * Run a command safely using execFile (no shell expansion).
+ * Never throws — all errors are captured in the result.
+ *
+ * @param cmd  - Executable name or path (no shell features).
+ * @param args - Arguments as an array (each arg is passed verbatim).
+ * @param cwd  - Optional working directory.
+ */
+export declare function execFileNoThrow(cmd: string, args: string[], cwd?: string): Promise<ExecFileResult>;
+//# sourceMappingURL=exec-file-no-throw.d.ts.map

package/dist/utils/exec-file-no-throw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-file-no-throw.d.ts","sourceRoot":"","sources":["../../src/utils/exec-file-no-throw.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,cAAc,CAAC,CAezB"}

package/dist/utils/exec-file-no-throw.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Safe execFile wrapper — uses execFile (not exec) to prevent shell injection.
+ * Handles Windows compatibility and provides structured output.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.execFileNoThrow = execFileNoThrow;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+/**
+ * Run a command safely using execFile (no shell expansion).
+ * Never throws — all errors are captured in the result.
+ *
+ * @param cmd  - Executable name or path (no shell features).
+ * @param args - Arguments as an array (each arg is passed verbatim).
+ * @param cwd  - Optional working directory.
+ */
+async function execFileNoThrow(cmd, args, cwd) {
+    try {
+        const { stdout, stderr } = await execFileAsync(cmd, args, {
+            cwd,
+            // Prevent accidental shell expansion on Windows too
+            shell: false,
+        });
+        return { stdout: stdout ?? '', stderr: stderr ?? '', status: 0 };
+    }
+    catch (err) {
+        return {
+            stdout: err.stdout ?? '',
+            stderr: err.stderr ?? '',
+            status: typeof err.code === 'number' ? err.code : 1,
+        };
+    }
+}
+//# sourceMappingURL=exec-file-no-throw.js.map

package/dist/utils/exec-file-no-throw.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-file-no-throw.js","sourceRoot":"","sources":["../../src/utils/exec-file-no-throw.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAsBH,0CAmBC;AAvCD,iDAAyC;AACzC,+BAAiC;AAEjC,MAAM,aAAa,GAAG,IAAA,gBAAS,EAAC,wBAAQ,CAAC,CAAC;AAS1C;;;;;;;GAOG;AACI,KAAK,UAAU,eAAe,CACnC,GAAW,EACX,IAAc,EACd,GAAY;IAEZ,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE;YACxD,GAAG;YACH,oDAAoD;YACpD,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;QACH,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;IACnE,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,OAAO;YACL,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE;YACxB,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE;YACxB,MAAM,EAAE,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;SACpD,CAAC;IACJ,CAAC;AACH,CAAC"}

package/package.json

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

package/src/cli/commands/add.ts

@@ -1,4 +1,6 @@
 import { Command } from 'commander';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 
 export function registerAddCommand(program: Command): void {
   program
@@ -9,6 +11,10 @@ export function registerAddCommand(program: Command): void {
     .option('-c, --capture', 'Auto-capture a live-page screenshot to requirements/ui/ (requires --path)')
     .option('-f, --feature <name>', 'Add additional feature file to existing screen')
     .option('-d, --description <text>', 'Screen description')
+    .option('--figma <url>', "Figma share URL — fetch design node and generate spec_figma.md + ui/*.png. QUOTE the URL ('...'): the '&' in Figma links backgrounds the shell otherwise.")
+    .option('--refresh', 'Bypass Figma cache and re-fetch from API (use with --figma)')
+    .option('--scale <n>', 'PNG export scale factor (default: 2)', parseFloat, 2)
+    .option('--hi-res', 'Export at 4× scale (shorthand for --scale 4)')
     .action(async (options) => {
       try {
         if (options.capture && !options.path) {
@@ -16,16 +22,81 @@ export function registerAddCommand(program: Command): void {
           process.exit(1);
         }
 
-        const { ScreenManager } = require('../../orchestrator/screen-manager');
-        const manager = new ScreenManager();
+        // When --figma is set on an existing screen, skip scaffolding and
+        // just refresh Figma-derived files (spec_figma.md, ui/*.png).
+        const screenDir = path.join(process.cwd(), 'qa', 'screens', options.screen);
+        const featureFile = path.join(screenDir, 'features', `${options.screen}.feature`);
+        const screenAlreadyExists = fs.existsSync(featureFile);
 
-        await manager.addScreen({
-          name: options.screen,
-          path: options.path,
-          capture: options.capture,
-          feature: options.feature,
-          description: options.description,
-        });
+        if (!(options.figma && screenAlreadyExists)) {
+          const { ScreenManager } = require('../../orchestrator/screen-manager');
+          const manager = new ScreenManager();
+
+          await manager.addScreen({
+            name: options.screen,
+            path: options.path,
+            capture: options.capture,
+            feature: options.feature,
+            description: options.description,
+          });
+        } else {
+          console.log(`Screen "${options.screen}" already exists — refreshing Figma assets only.`);
+        }
+
+        // Figma branch: run after directory scaffolding is complete
+        if (options.figma) {
+          const { FigmaScaffolder } = require('../../orchestrator/figma/figma-scaffolder');
+          const scale: number = options.hiRes ? 4 : (options.scale ?? 2);
+
+          try {
+            const result = await FigmaScaffolder.run({
+              screenName: options.screen,
+              figmaUrl: options.figma,
+              cwd: process.cwd(),
+              refresh: options.refresh ?? false,
+              scale,
+            });
+
+            console.log('\nFigma import complete:');
+            console.log(`  ${result.specFigmaPath}`);
+            for (const img of result.imagePaths) {
+              console.log(`  qa/screens/${options.screen}/requirements/${img}`);
+            }
+            if (result.specMdCreated) {
+              console.log(`  qa/screens/${options.screen}/requirements/spec.md (stub created)`);
+            }
+
+            // Loud banner: Tell the calling agent to
+            // invoke the `sungen-figma-source` skill to synthesize the narrative sections in spec_figma.md, since
+            // the CLI cannot do this (synthesis is LLM-driven off the cached raw JSON).
+            console.log('');
+            console.log('==============================================================');
+            console.log('  NEXT STEP (REQUIRED — DO NOT SKIP)');
+            console.log('==============================================================');
+            console.log('  spec_figma.md envelope is written but narrative is EMPTY.');
+            console.log('  Invoke the `sungen-figma-source` skill NOW to synthesize');
+            console.log('  the 7 sections (Purpose / ASCII Layout / Regions / Actions /');
+            console.log('  Form Fields / Data Columns / Navigation) below the');
+            console.log('  `<!-- SYNTHESIS-BELOW -->` marker.');
+            console.log('');
+            console.log('  Read the cached raw node JSON at:');
+            console.log(`    .sungen/figma-cache/<fileKey>/<versionId>/<nodeId>-raw.json`);
+            console.log('  and append the narrative below the marker in:');
+            console.log(`    ${result.specFigmaPath}`);
+            console.log('==============================================================');
+          } catch (figmaError) {
+            const msg = figmaError instanceof Error ? figmaError.message : String(figmaError);
+            // Surface remediation hint when available
+            const remediation =
+              figmaError instanceof Error &&
+              'remediation' in figmaError &&
+              typeof (figmaError as { remediation: unknown }).remediation === 'string'
+                ? `\nHint: ${(figmaError as { remediation: string }).remediation}`
+                : '';
+            console.error(`\nFigma import failed: ${msg}${remediation}`);
+            process.exit(1);
+          }
+        }
       } catch (error) {
         console.error('Error:', error instanceof Error ? error.message : error);
         process.exit(1);

package/src/cli/commands/figma.ts

@@ -0,0 +1,162 @@
+/**
+ * `sungen figma` subcommand dispatcher.
+ *
+ * Subcommands:
+ *   sungen figma auth set   — prompt for PAT, validate via /v1/me, persist to .env
+ *   sungen figma auth check — load PAT, call /v1/me, print handle + email
+ *   sungen figma auth clear — remove FIGMA_PAT from .env
+ */
+
+import { Command } from 'commander';
+import * as readline from 'readline';
+import { loadPat, savePat, clearPat, assertSafeToUse } from '../../tools/figma/figma-auth';
+import type { FigmaMeResponse } from '../../tools/figma/figma-client-types';
+
+const FIGMA_API_BASE = 'https://api.figma.com';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Read a line from stdin without echoing characters (hidden input). */
+function readHiddenInput(prompt: string): Promise<string> {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    // Disable echoing by replacing the _writeToOutput method
+    (rl as any)._writeToOutput = (str: string) => {
+      // Only write the prompt, not the typed characters
+      if (str === prompt) (rl as any).output.write(str);
+    };
+    rl.question(prompt, (answer) => {
+      (rl as any).output.write('\n');
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+/**
+ * Call GET /v1/me with the given PAT.
+ * Returns parsed body on 2xx, throws with a scrubbed error message on failure.
+ */
+async function callFigmaMe(pat: string): Promise<FigmaMeResponse> {
+  let response: Response;
+  try {
+    response = await fetch(`${FIGMA_API_BASE}/v1/me`, {
+      headers: { 'X-Figma-Token': pat },
+    });
+  } catch (err: any) {
+    throw new Error(`Network error reaching Figma API: ${err.message ?? 'unknown'}`);
+  }
+
+  if (!response.ok) {
+    const status = response.status;
+    if (status === 403 || status === 401) {
+      throw new Error(`Figma API returned ${status}: token is invalid or lacks read scope.`);
+    }
+    throw new Error(`Figma API returned unexpected status ${status}.`);
+  }
+
+  return response.json() as Promise<FigmaMeResponse>;
+}
+
+// ---------------------------------------------------------------------------
+// Subcommand handlers
+// ---------------------------------------------------------------------------
+
+async function handleAuthSet(options: { token?: string }, cwd: string): Promise<void> {
+  let pat = options.token;
+
+  if (!pat) {
+    pat = await readHiddenInput('Enter Figma Personal Access Token: ');
+  }
+
+  if (!pat) {
+    console.error('Error: token cannot be empty.');
+    process.exit(1);
+  }
+
+  console.log('Validating token with Figma API…');
+  let me: FigmaMeResponse;
+  try {
+    me = await callFigmaMe(pat);
+  } catch (err: any) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  try {
+    await savePat(cwd, pat);
+  } catch (err: any) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  console.log(`Token validated and saved. Authenticated as: ${me.handle} <${me.email}>`);
+}
+
+async function handleAuthCheck(cwd: string): Promise<void> {
+  try {
+    await assertSafeToUse(cwd);
+  } catch (err: any) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  const pat = loadPat(cwd);
+  if (!pat) {
+    console.error('Error: No FIGMA_PAT configured. Run `sungen figma auth set` first.');
+    process.exit(1);
+  }
+
+  let me: FigmaMeResponse;
+  try {
+    me = await callFigmaMe(pat);
+  } catch (err: any) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  console.log(`Authenticated as: ${me.handle} <${me.email}>`);
+}
+
+async function handleAuthClear(cwd: string): Promise<void> {
+  clearPat(cwd);
+  console.log('FIGMA_PAT removed from .env.');
+}
+
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+
+export function registerFigmaCommand(program: Command): void {
+  const figma = program
+    .command('figma')
+    .description('Figma integration — manage authentication and (future) asset fetching');
+
+  const auth = figma
+    .command('auth')
+    .description('Manage Figma Personal Access Token');
+
+  auth
+    .command('set')
+    .description('Validate and save a Figma PAT to .env')
+    .option('--token <token>', 'PAT value (for scripting; prefer interactive prompt)')
+    .action(async (options) => {
+      await handleAuthSet(options, process.cwd());
+    });
+
+  auth
+    .command('check')
+    .description('Verify saved PAT by calling /v1/me and print account info')
+    .action(async () => {
+      await handleAuthCheck(process.cwd());
+    });
+
+  auth
+    .command('clear')
+    .description('Remove FIGMA_PAT from .env')
+    .action(async () => {
+      await handleAuthClear(process.cwd());
+    });
+}

package/src/cli/commands/generate.ts

@@ -58,6 +58,7 @@ export function registerGenerateCommand(program: Command): void {
     .option('-s, --screen <name>', 'Generate tests for a specific screen')
     .option('--all', 'Generate tests for all screens')
     .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;
@@ -89,6 +90,7 @@ export function registerGenerateCommand(program: Command): void {
           framework: options.framework || 'playwright',
           screenName,
           verbose: program.opts().verbose,
+          runtimeData: !options.inlineData,
         });
 
         const results = await generator.generateAllTests(

package/src/cli/index.ts

@@ -11,6 +11,7 @@ import { registerGenerateCommand } from './commands/generate';
 import { registerMakeauthCommand } from './commands/makeauth';
 import { registerUpdateCommand } from './commands/update';
 import { registerDeliveryCommand } from './commands/delivery';
+import { registerFigmaCommand } from './commands/figma';
 
 async function main() {
   const program = new Command();
@@ -18,19 +19,20 @@ async function main() {
   program
     .name('sungen')
     .description('Deterministic E2E Test Compiler — Gherkin + Selectors → Playwright')
-    .version('2.4.6');
+    .version('2.5.1');
 
   // Global options
   program
     .option('-v, --verbose', 'Enable verbose logging');
 
-  // Register commands (6)
+  // Register commands (7)
   registerInitCommand(program);
   registerAddCommand(program);
   registerGenerateCommand(program);
   registerMakeauthCommand(program);
   registerUpdateCommand(program);
   registerDeliveryCommand(program);
+  registerFigmaCommand(program);
 
   await program.parseAsync(process.argv);
 }

package/src/generators/gherkin-parser/index.ts

@@ -34,6 +34,7 @@ export interface ParsedScenario {
   steps: ParsedStep[];
   stepsName?: string;   // set when scenario has @steps:<name> — marks it as a reusable block
   extendsName?: string; // set when scenario has @extend:<name> — merges base steps inline
+  hookType?: 'beforeAll' | 'afterEach' | 'afterAll'; // set when scenario has @beforeAll/@afterEach/@afterAll
 }
 
 export interface ParsedFeature {
@@ -120,12 +121,15 @@ export class GherkinParser {
         const tags = scenario.tags.map((tag) => tag.name);
         const stepsName = tags.find(t => t.startsWith('@steps:'))?.replace('@steps:', '') || undefined;
         const extendsName = tags.find(t => t.startsWith('@extend:'))?.replace('@extend:', '') || undefined;
+        const hookTag = tags.find(t => /^@(beforeAll|afterEach|afterAll)$/.test(t));
+        const hookType = hookTag?.replace('@', '') as ParsedScenario['hookType'];
         return {
           name: scenario.name,
           tags,
           steps: scenario.steps.map((step) => this.parseStep(step)),
           stepsName,
           extendsName,
+          hookType,
         };
       });
   }

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

@@ -13,6 +13,14 @@ export interface TestFileData {
   featureName: string;
   featureDescription?: string;
   background?: string;
+  beforeAll?: string;
+  afterEach?: string;
+  afterAll?: string;
+  cleanupConfig?: string; // Pre-formatted autoCleanup config from @cleanup:* tags
+  screenshotOnFailure?: boolean; // @screenshot:on-failure tag
+  runtimeData?: boolean; // --runtime-data flag: testData.get() instead of hardcoded values
+  screenName?: string; // Screen name for TestDataLoader.load()
+  featureFileName?: string; // Feature file name for TestDataLoader.load()
   scenarios: string[];
   authGroups?: AuthGroup[]; // Grouped by auth role for nested describes
   singleAuthRole?: string;  // Auth role when all scenarios share the same role
@@ -49,8 +57,11 @@ export interface TestGeneratorAdapter {
   // Template rendering methods
   renderTestFile(data: TestFileData): string;
   renderScenario(data: ScenarioData): string;
-  renderImports(): string;
+  renderImports(options?: { runtimeData?: boolean }): 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;
+  renderAfterAll(data: { steps: Array<{ comment?: string; code: string }> }): string;
 
   // Step rendering
   renderStep(templateName: string, data: any): string;

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

@@ -26,14 +26,26 @@ export class PlaywrightAdapter implements TestGeneratorAdapter {
     return this.templateEngine.renderScenario(data);
   }
 
-  renderImports(): string {
-    return this.templateEngine.renderImports();
+  renderImports(options?: { runtimeData?: boolean }): string {
+    return this.templateEngine.renderImports(options);
   }
 
   renderBeforeEach(data: { steps: Array<{ comment?: string; code: string }> }): string {
     return this.templateEngine.renderBeforeEach(data);
   }
 
+  renderBeforeAll(data: { steps: Array<{ comment?: string; code: string }> }): string {
+    return this.templateEngine.renderBeforeAll(data);
+  }
+
+  renderAfterEach(data: { steps: Array<{ comment?: string; code: string }> }): string {
+    return this.templateEngine.renderAfterEach(data);
+  }
+
+  renderAfterAll(data: { steps: Array<{ comment?: string; code: string }> }): string {
+    return this.templateEngine.renderAfterAll(data);
+  }
+
   renderStep(templateName: string, data: any): string {
     return this.templateEngine.renderStep(templateName, data);
   }

package/src/generators/test-generator/adapters/playwright/templates/after-all.hbs

@@ -0,0 +1,8 @@
+  test.afterAll(async ({ request }) => {
+{{#each steps}}
+{{#if comment}}
+    // {{comment}}
+{{/if}}
+{{code}}
+{{/each}}
+  });

package/src/generators/test-generator/adapters/playwright/templates/after-each.hbs

@@ -0,0 +1,8 @@
+  test.afterEach(async ({ page }) => {
+{{#each steps}}
+{{#if comment}}
+    // {{comment}}
+{{/if}}
+{{code}}
+{{/each}}
+  });

package/src/generators/test-generator/adapters/playwright/templates/before-all.hbs

@@ -0,0 +1,8 @@
+  test.beforeAll(async ({ request }) => {
+{{#each steps}}
+{{#if comment}}
+    // {{comment}}
+{{/if}}
+{{code}}
+{{/each}}
+  });

package/src/generators/test-generator/adapters/playwright/templates/imports.hbs

@@ -1,4 +1,7 @@
 import { test, expect } from '../base';
+{{#if runtimeData}}
+import { TestDataLoader } from '../test-data';
+{{/if}}
 
 // This file is auto-generated from Gherkin feature files
 // DO NOT EDIT MANUALLY - changes will be overwritten

package/src/generators/test-generator/adapters/playwright/templates/test-file.hbs

@@ -1,4 +1,8 @@
 {{imports}}
+{{#if runtimeData}}
+
+const testData = TestDataLoader.load('{{screenName}}', '{{featureFileName}}');
+{{/if}}
 
 {{#if featureDescription}}
 /**
@@ -11,10 +15,30 @@ test.describe('{{featureName}}', () => {
 {{#if singleAuthRole}}
   test.use({ storageState: 'specs/.auth/{{singleAuthRole}}.json' });
 
+{{/if}}
+{{#if cleanupConfig}}
+  test.use({ autoCleanup: { {{cleanupConfig}} } });
+
+{{/if}}
+{{#if screenshotOnFailure}}
+  test.use({ screenshotOnFailure: true });
+
+{{/if}}
+{{#if beforeAll}}
+{{beforeAll}}
+
 {{/if}}
 {{#if background}}
 {{background}}
 
+{{/if}}
+{{#if afterEach}}
+{{afterEach}}
+
+{{/if}}
+{{#if afterAll}}
+{{afterAll}}
+
 {{/if}}
 {{#if authGroups}}
 {{#each authGroups}}