@sun-asterisk/sungen 1.0.17 → 1.0.19

package/src/generators/scaffold-generator/index.ts

@@ -11,10 +11,11 @@ import { SelectorResolver } from '../test-generator/utils/selector-resolver';
 
 export interface ScaffoldElement {
   locator: string;
-  type: 'placeholder' | 'role' | 'text' | 'label' | 'page';
+  type: 'placeholder' | 'role' | 'text' | 'label' | 'page' | 'testid';
   value: string;
-  name?: string;       // For role type (accessible name)
+  name?: string;       // For role type (accessible name), or label text
   nth: number;
+  exact?: boolean;     // Whether to use exact matching (default: false)
 }
 
 export interface ScaffoldResult {
@@ -31,8 +32,8 @@ export interface MapResult {
   testDataPath: string;
   elementCount: number;
   dataRefCount: number;
-  selectorsSkipped?: boolean;  // True if selectors file already existed
-  testDataSkipped?: boolean;   // True if test-data file already existed
+  selectorsSkipped?: boolean;  // True if selectors file already existed (and force was not set)
+  testDataMerged?: boolean;    // True if test-data file existed and was smart-merged
 }
 
 interface ExtractedDataRef {
@@ -178,6 +179,9 @@ export class ScaffoldGenerator {
     if (/^(logo|image|img|icon)\b/.test(lowerText) || /^\d*\s*(logo|image|img|icon)\b/.test(lowerText)) {
       return 'img';
     }
+    if (/^(dialog|modal)\b/.test(lowerText) || /^\d*\s*(dialog|modal)\b/.test(lowerText)) {
+      return 'dialog';
+    }
     if (/^(heading|header)\b/.test(lowerText) || /^\d*\s*(heading|header)\b/.test(lowerText)) {
       return 'heading';
     }
@@ -393,7 +397,7 @@ export class ScaffoldGenerator {
       case 'see':
         // For assertions - respect targetType for role-based elements
         if (targetType === 'img' || targetType === 'button' || targetType === 'link' ||
-            targetType === 'checkbox' || targetType === 'radio' || targetType === 'heading') {
+            targetType === 'checkbox' || targetType === 'radio' || targetType === 'heading' || targetType === 'dialog') {
           const seeRoleValue = this.getRoleValue(targetType);
           return {
             locator: '',
@@ -463,6 +467,8 @@ export class ScaffoldGenerator {
         return 'img';
       case 'heading':
         return 'heading';
+      case 'dialog':
+        return 'dialog';
       default:
         return 'button'; // Default to button
     }
@@ -606,6 +612,124 @@ export class ScaffoldGenerator {
     return results;
   }
 
+  /**
+   * Enrich scaffold with live-scan data if a .live-scan.yaml file exists.
+   * Uses the Playwright locator strategy detected by live-scan:
+   *   testid      → type: testid, value: <testid>
+   *   role        → type: role, value: <aria-role>, name: <accessible-name>
+   *   label       → type: label, value: <label-text>
+   *   placeholder → type: placeholder, value: <placeholder-text>
+   *   text        → type: text, value: <visible-text>
+   */
+  private enrichWithLiveScan(scaffold: ScaffoldResult, liveScanPath: string): ScaffoldResult {
+    if (!fs.existsSync(liveScanPath)) {
+      return scaffold;
+    }
+
+    let matrixData: any;
+    try {
+      const { readMatrix, mergeMatrixElements } = require('../../core/live-scanner/matrix-reader');
+      matrixData = readMatrix(liveScanPath);
+      if (!matrixData) return scaffold;
+
+      const elements = mergeMatrixElements(matrixData);
+      if (!elements || Object.keys(elements).length === 0) return scaffold;
+
+      console.log(`   🔗 Using live-scan data from ${path.basename(liveScanPath)}`);
+
+      let enrichedCount = 0;
+      let warningCount = 0;
+
+      const enriched: ScaffoldResult = { ...scaffold };
+
+      for (const [key, scaffoldElement] of Object.entries(enriched)) {
+        // Try exact key first, then base key without --N suffix or --type suffix
+        let liveElement = elements[key];
+        if (!liveElement && key.includes('--')) {
+          const baseKey = key.replace(/--.*$/, '');
+          liveElement = elements[baseKey];
+        }
+        if (!liveElement) {
+          continue;
+        }
+
+        // If live-scan couldn't find the element, clear the identifying field so user must fill manually
+        if (liveElement.matchMethod === 'unresolved') {
+          if (scaffoldElement.name !== undefined) {
+            enriched[key] = { ...scaffoldElement, name: '' };
+          } else {
+            enriched[key] = { ...scaffoldElement, value: '' };
+          }
+          continue;
+        }
+
+        // Use the Playwright locator strategy that live-scan detected
+        const selectorType = liveElement.selectorType;
+
+        // Only set exact when true (omit from YAML when false for cleaner output)
+        const exactField = liveElement.exact ? { exact: true } : {};
+
+        if (selectorType === 'testid' && liveElement.testid) {
+          // page.getByTestId('value')
+          enriched[key] = {
+            ...scaffoldElement,
+            type: 'testid' as any,
+            value: liveElement.testid,
+          };
+        } else if (selectorType === 'role' && liveElement.role) {
+          // page.getByRole('button', { name: 'Submit' })
+          enriched[key] = {
+            ...scaffoldElement,
+            type: 'role',
+            value: liveElement.role,
+            name: liveElement.name || liveElement.gherkinRef,
+            ...exactField,
+          };
+        } else if (selectorType === 'label' && liveElement.label) {
+          // page.getByLabel('Username')
+          enriched[key] = {
+            ...scaffoldElement,
+            type: 'label',
+            value: liveElement.label,
+            ...exactField,
+          };
+        } else if (selectorType === 'placeholder' && liveElement.placeholder) {
+          // page.getByPlaceholder('Enter email')
+          enriched[key] = {
+            ...scaffoldElement,
+            type: 'placeholder',
+            value: liveElement.placeholder,
+            ...exactField,
+          };
+        } else if (selectorType === 'text') {
+          // page.getByText('Welcome')
+          enriched[key] = {
+            ...scaffoldElement,
+            type: 'text',
+            value: liveElement.name || liveElement.gherkinRef,
+            ...exactField,
+          };
+        } else {
+          continue;
+        }
+
+        enrichedCount++;
+        if (liveElement.warning) {
+          warningCount++;
+          console.log(`   ⚠️  ${key}: ${liveElement.warning}`);
+        }
+      }
+
+      const textOnlyCount = Object.keys(enriched).length - enrichedCount;
+      console.log(`   📊 Live-scan: ${enrichedCount} enriched, ${textOnlyCount} text-inferred${warningCount > 0 ? `, ${warningCount} warnings` : ''}`);
+
+      return enriched;
+    } catch (error: any) {
+      console.warn(`   ⚠️  Failed to read live-scan data: ${error.message}`);
+      return scaffold;
+    }
+  }
+
   /**
    * Helper to capitalize first letter
    */
@@ -655,6 +779,10 @@ export class ScaffoldGenerator {
       const selectorScaffold = this.buildScaffold(elements);
       const testDataScaffold = this.buildTestData(dataRefs);
 
+      // Enrich scaffold with live-scan data if available
+      const liveScanPath = path.join(selectorsDir, `${filename}.live-scan.yaml`);
+      const liveScanEnriched = this.enrichWithLiveScan(selectorScaffold, liveScanPath);
+
       // Check if files exist
       const selectorsPath = path.join(selectorsDir, `${filename}.yaml`);
       const selectorsOverridePath = path.join(selectorsDir, `${filename}.override.yaml`);
@@ -666,12 +794,19 @@ export class ScaffoldGenerator {
 
       // Write selectors YAML (BASE ONLY - never touch override files)
       if (!selectorsExists || forceOverwrite) {
-        this.writeSelectorsYaml(selectorScaffold, selectorsPath, filename);
+        this.writeSelectorsYaml(liveScanEnriched, selectorsPath, filename);
       }
       // Override file is NEVER touched by map command
 
-      // Write test-data YAML (BASE ONLY - never touch override files)
-      if (!testDataExists || forceOverwrite) {
+      // Write test-data YAML — always smart-merge regardless of --force:
+      // • existing keys keep their current value
+      // • new keys from features are added (empty string)
+      // • keys no longer referenced in features are removed
+      if (testDataExists) {
+        const existingRaw = yaml.parse(fs.readFileSync(testDataPath, 'utf-8')) as TestDataResult || {};
+        const merged = this.mergeTestData(existingRaw, testDataScaffold);
+        this.writeTestDataYaml(merged, testDataPath, filename);
+      } else {
         this.writeTestDataYaml(testDataScaffold, testDataPath, filename);
       }
       // Override file is NEVER touched by map command
@@ -680,10 +815,10 @@ export class ScaffoldGenerator {
         featureFile: filename,
         selectorsPath,
         testDataPath,
-        elementCount: Object.keys(selectorScaffold).length,
+        elementCount: Object.keys(liveScanEnriched).length,
         dataRefCount: dataRefs.length,
         selectorsSkipped: selectorsExists && !forceOverwrite,
-        testDataSkipped: testDataExists && !forceOverwrite,
+        testDataMerged: testDataExists,
       });
     }
 
@@ -786,14 +921,46 @@ export class ScaffoldGenerator {
     fs.writeFileSync(outputPath, header + yamlContent, 'utf-8');
   }
 
+  /**
+   * Smart-merge test-data objects:
+   * - Keys present in both: keep the existing value (user may have filled it in)
+   * - Keys only in fresh (new refs in features): add with empty value
+   * - Keys only in existing (removed from features): drop them
+   */
+  private mergeTestData(existing: TestDataResult, fresh: TestDataResult): TestDataResult {
+    const merged: TestDataResult = {};
+
+    for (const key of Object.keys(fresh)) {
+      if (key in existing) {
+        const existingVal = existing[key];
+        const freshVal = fresh[key];
+        if (typeof freshVal === 'object' && typeof existingVal === 'object') {
+          // Both are nested — recurse
+          merged[key] = this.mergeTestData(existingVal as TestDataResult, freshVal as TestDataResult);
+        } else {
+          // Keep the existing (user-supplied) value
+          merged[key] = existingVal;
+        }
+      } else {
+        // New key — add with the scaffold default (empty string or nested object)
+        merged[key] = fresh[key];
+      }
+      // Keys present in existing but absent from fresh are intentionally dropped (no longer referenced)
+    }
+
+    return merged;
+  }
+
   /**
    * Write test-data YAML file
    */
   private writeTestDataYaml(testData: TestDataResult, outputPath: string, screenName: string): void {
-    const header = `# ${this.capitalizeFirst(screenName)} Screen Test Data (Auto-generated)
-# ⚠️  AUTO-GENERATED - Consider editing only the override file
-# To override values, copy to ${screenName}.override.yaml
-# Manual edits to this file will be lost on regeneration
+    const header = `# ${this.capitalizeFirst(screenName)} Screen Test Data
+# Managed by: sungen map (smart-merge)
+# • New {{variable}} refs are added automatically (empty value)
+# • Removed refs are dropped on the next sungen map run
+# • Your existing values are never overwritten
+# To fix a value permanently, copy the key to ${screenName}.override.yaml
 #
 # Reference in features using {{variable}} syntax
 

package/src/generators/test-generator/adapters/playwright/templates/steps/actions/radio-select-action.hbs

@@ -1 +1 @@
-await {{pageRoot}}.getByRole('radio', { name: '{{selectValue}}'{{#if (shouldUseExact selectorRef)}}, exact: true{{/if}} }).check();
+await {{pageRoot}}.getByRole('radio', { name: '{{selectValue}}'{{#if exact}}, exact: true{{/if}} }).check();

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/disabled-with-role-variable-assertion.hbs

@@ -1,5 +1,5 @@
 {{#if name}}
-await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if (shouldUseExact selectorRef)}}, exact: true{{/if}} }).filter({ hasText: '{{escapeQuotes dataValue}}' }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeDisabled();
+await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }).filter({ hasText: '{{escapeQuotes dataValue}}' }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeDisabled();
 {{else}}
-await expect(page.getByRole('{{role}}'{{#if (shouldUseExact selectorRef)}}, { exact: true }{{/if}}).filter({ hasText: '{{escapeQuotes dataValue}}' }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeDisabled();
+await expect(page.getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}).filter({ hasText: '{{escapeQuotes dataValue}}' }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeDisabled();
 {{/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/hidden-with-role-variable-assertion.hbs

@@ -1,5 +1,5 @@
 {{#if name}}
-await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if (shouldUseExact selectorRef)}}, exact: true{{/if}} }).filter({ hasText: '{{escapeQuotes dataValue}}' }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeHidden();
+await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }).filter({ hasText: '{{escapeQuotes dataValue}}' }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeHidden();
 {{else}}
-await expect(page.getByRole('{{role}}'{{#if (shouldUseExact selectorRef)}}, { exact: true }{{/if}}).filter({ hasText: '{{escapeQuotes dataValue}}' }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeHidden();
+await expect(page.getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}).filter({ hasText: '{{escapeQuotes dataValue}}' }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeHidden();
 {{/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/visible-with-role-variable-assertion.hbs

@@ -1,5 +1,9 @@
 {{#if name}}
-await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if (shouldUseExact selectorRef)}}, exact: true{{/if}} }).filter({ hasText: '{{escapeQuotes dataValue}}' }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeVisible();
+{{#if dataValue}}
+await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }).filter({ hasText: '{{escapeQuotes dataValue}}' }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeVisible();
 {{else}}
-await expect(page.getByRole('{{role}}'{{#if (shouldUseExact selectorRef)}}, { exact: true }{{/if}}).filter({ hasText: '{{escapeQuotes dataValue}}' }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeVisible();
+await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeVisible();
+{{/if}}
+{{else}}
+await expect(page.getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}).filter({ hasText: '{{escapeQuotes dataValue}}' }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeVisible();
 {{/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/visible-with-variable-assertion.hbs

@@ -1 +1 @@
-await expect(page.getByText('{{escapeQuotes selectorRef}}').filter({ hasText: {{#if (eq selectorValue "")}}/.*{{escapeRegex dataValue}}$/{{else}}'{{escapeQuotes dataValue}}'{{/if}} }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeVisible();
+await expect(page.getByText('{{escapeQuotes selectorValue}}').filter({ hasText: /.*{{escapeRegex dataValue}}$/ }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeVisible();

package/src/generators/test-generator/adapters/playwright/templates/steps/partials/locator-strategies/label.hbs

@@ -1 +1 @@
-{{pageRoot}}.getByLabel('{{escapeQuotes value}}'{{#if (shouldUseExact selectorRef)}}, { exact: true }{{/if}})
+{{pageRoot}}.getByLabel('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}})

package/src/generators/test-generator/adapters/playwright/templates/steps/partials/locator-strategies/placeholder.hbs

@@ -1 +1 @@
-{{pageRoot}}.getByPlaceholder('{{escapeQuotes value}}'{{#if (shouldUseExact selectorRef)}}, { exact: true }{{/if}})
+{{pageRoot}}.getByPlaceholder('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}})

package/src/generators/test-generator/adapters/playwright/templates/steps/partials/locator-strategies/role.hbs

@@ -1 +1 @@
-{{#if name}}{{pageRoot}}.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if (shouldUseExact selectorRef)}}, exact: true{{/if}} }){{else}}{{pageRoot}}.getByRole('{{role}}'{{#if (shouldUseExact selectorRef)}}, { exact: true }{{/if}}){{/if}}
+{{#if name}}{{pageRoot}}.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{else}}{{pageRoot}}.getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}){{/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/partials/locator-strategies/text.hbs

@@ -1 +1 @@
-{{pageRoot}}.getByText('{{escapeQuotes value}}'{{#if (shouldUseExact selectorRef)}}, { exact: true }{{/if}})
+{{pageRoot}}.getByText('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}})

package/src/generators/test-generator/patterns/assertion-patterns.ts

@@ -223,11 +223,14 @@ export const assertionPatterns: StepPattern[] = [
 
       // Check if it's a role-based selector with data
       if (resolved.strategy === 'role' && resolved.role) {
-        // Use role-based selector with filter for role types
+        const hasName = resolved.name && resolved.name.trim();
+        // For img role: images have no text content, so put dataValue in name instead of filter
+        const isImgRole = resolved.role === 'img';
         const code = context.templateEngine.renderStep('visible-with-role-variable-assertion', {
           role: resolved.role,
-          name: resolved.name && resolved.name.trim() ? resolved.name : undefined,
-          dataValue,
+          name: isImgRole ? (hasName ? resolved.name : dataValue) : (hasName ? resolved.name : undefined),
+          dataValue: isImgRole ? undefined : dataValue,
+          exact: resolved.exact || false,
           nth: resolved.nth || 0,
         });
         return {

package/src/generators/test-generator/template-engine.ts

@@ -80,11 +80,10 @@ export class TemplateEngine {
     });
 
     // Check if selector name should use exact: true
-    // Condition: length < 6 chars AND does NOT contain space
+    // DEPRECATED: Use the `exact` field from selector YAML instead.
+    // Kept for backward compatibility with custom templates.
     Handlebars.registerHelper('shouldUseExact', function(selectorRef: string) {
-      if (!selectorRef) return false;
-      const selectorName = selectorRef.split('.')[0].trim();
-      return selectorName.length < 6 && !selectorName.includes(' ');
+      return false;
     });
 
     // Switch/case helpers for cleaner strategy routing

package/src/generators/test-generator/utils/data-resolver.ts

@@ -95,20 +95,31 @@ export class DataResolver {
       return this.dataCache.get(fileName)!;
     }
 
-    const filePath = this.findDataFilePath(fileName);
-    
-    if (!filePath) {
-      const possiblePaths = this.getPossibleDataPaths(fileName);
+    // Merge base + override: base provides defaults, override wins on conflict
+    const possiblePaths = this.getPossibleDataPaths(fileName);
+    let merged: any = {};
+    let found = false;
+
+    // Load in reverse priority order (base first, then overrides on top)
+    for (const p of [...possiblePaths].reverse()) {
+      if (fs.existsSync(p)) {
+        const content = fs.readFileSync(p, 'utf-8');
+        const data = yaml.parse(content);
+        if (data && typeof data === 'object' && Object.keys(data).length > 0) {
+          merged = { ...merged, ...data };
+          found = true;
+        }
+      }
+    }
+
+    if (!found) {
       throw new Error(
         `Data file not found. Tried:\n${possiblePaths.join('\n')}`
       );
     }
 
-    const content = fs.readFileSync(filePath, 'utf-8');
-    const data = yaml.parse(content);
-
-    this.dataCache.set(fileName, data);
-    return data;
+    this.dataCache.set(fileName, merged);
+    return merged;
   }
 
   /**

package/src/generators/test-generator/utils/selector-resolver.ts

@@ -194,6 +194,7 @@ interface SelectorEntry {
   value?: string;     // Natural language value for the locator (e.g., 'button', 'link' for role)
   name?: string;      // Accessible name for role-based selectors (e.g., 'Login', 'Submit')
   nth?: number;       // Element index (0 = no index, 1+ = append .nth())
+  exact?: boolean;    // Whether to use exact matching (default: false)
 }
 
 // New selector file structure: flat key-value pairs
@@ -219,6 +220,7 @@ export interface ResolvedSelector {
   name?: string;      // For accessible name in role selectors
   locator?: string;  // CSS locator for fallback
   nth?: number;       // Index for .nth() if multiple matches exist
+  exact?: boolean;    // Whether to use exact matching (default: false)
 }
 
 /**
@@ -512,6 +514,7 @@ export class SelectorResolver {
     // Check if name exists in entry (even if empty string), use it; otherwise use originalLabel
     const name = entry.name !== undefined && entry.name !== null ? entry.name : originalLabel;
     const nth = entry.nth || 0;
+    const exact = entry.exact === true;
 
     // If type is 'locator', use locator field (or value as fallback) as the CSS locator directly
     if (type === 'locator') {
@@ -541,6 +544,7 @@ export class SelectorResolver {
           strategy: 'placeholder',
           value,
           nth,
+          exact,
         };
 
       case 'role':
@@ -550,6 +554,7 @@ export class SelectorResolver {
           name: name,  // Use the name field for accessible name
           value,
           nth,
+          exact,
         };
 
       case 'testid':
@@ -564,6 +569,7 @@ export class SelectorResolver {
           strategy: 'label',
           value,
           nth,
+          exact,
         };
 
       case 'text':
@@ -571,6 +577,7 @@ export class SelectorResolver {
           strategy: 'text',
           value,
           nth,
+          exact,
         };
 
       default:
@@ -579,6 +586,7 @@ export class SelectorResolver {
           strategy: 'placeholder',
           value,
           nth,
+          exact,
         };
     }
   }

package/src/input/cli-adapter.ts

@@ -36,7 +36,7 @@ export class CLIAdapter implements InputAdapter {
     program
       .name('sungen')
       .description('AI-Native E2E Test Generator - Generate Playwright tests from Gherkin features')
-      .version('1.0.17');
+      .version('1.0.19');
 
     // Global options
     program
@@ -84,6 +84,9 @@ export class CLIAdapter implements InputAdapter {
       .option('--file <path>', 'Single feature file path (generates selectors next to features folder)')
       .option('-o, --output <dir>', 'Output directory for generated files')
       .option('-f, --force', 'Force overwrite existing YAML files')
+      .option('--scan-live', 'Run live-scan before mapping to detect real selectors')
+      .option('--headed', 'Launch browser in headed mode (only with --scan-live)', false)
+      .option('--auth-dir <path>', 'Auth storage state directory (only with --scan-live)', 'specs/.auth')
       .option('-v, --verbose', 'Detailed output');
   }
 
@@ -121,8 +124,8 @@ export class CLIAdapter implements InputAdapter {
    */
   addInitCommand(program: Command): Command {
     return program
-      .command('init')
-      .description('Initialize Sungen project (create essential directories and config)');
+      .command('init [projectName]')
+      .description('Initialize Sungen project (optionally create and initialize in a new project folder)');
   }
 
   /**
@@ -147,6 +150,19 @@ export class CLIAdapter implements InputAdapter {
       .option('-v, --verbose', 'Show detailed output');
   }
 
+  /**
+   * Add live-scan command
+   */
+  addLiveScanCommand(program: Command): Command {
+    return program
+      .command('live-scan')
+      .description('Scan a live site to discover real selectors for Gherkin element references')
+      .requiredOption('-s, --screen <name>', 'Screen name to scan')
+      .option('--url <baseUrl>', 'Base URL of the running site')
+      .option('--headed', 'Launch browser in headed (visible) mode')
+      .option('--auth-dir <path>', 'Directory containing auth storage state files (default: specs/.auth)');
+  }
+
   /**
    * Add add --screen command
    */

package/src/orchestrator/project-initializer.ts

@@ -7,20 +7,33 @@ import * as fs from 'fs';
 import * as path from 'path';
 
 export class ProjectInitializer {
+  private baseCwd: string;
   private cwd: string;
   private createdItems: string[] = [];
   private skippedItems: string[] = [];
 
   constructor() {
-    this.cwd = process.cwd();
+    this.baseCwd = process.cwd();
+    this.cwd = this.baseCwd;
   }
 
   /**
    * Initialize project with essential directories and config
    */
-  async initialize(): Promise<void> {
+  async initialize(projectName?: string): Promise<void> {
+    const normalizedProjectName = projectName?.trim();
+    this.cwd = normalizedProjectName
+      ? path.resolve(this.baseCwd, normalizedProjectName)
+      : this.baseCwd;
+    this.createdItems = [];
+    this.skippedItems = [];
+
     console.log('🚀 Initializing Sungen project...\n');
 
+    if (normalizedProjectName) {
+      this.createProjectRoot(normalizedProjectName);
+    }
+
     // Create directories
     this.createDirectories();
 
@@ -34,7 +47,19 @@ export class ProjectInitializer {
     this.createReadme();
 
     // Display summary
-    this.displaySummary();
+    this.displaySummary(normalizedProjectName);
+  }
+
+  /**
+   * Create project root directory when project name is provided
+   */
+  private createProjectRoot(projectName: string): void {
+    if (!fs.existsSync(this.cwd)) {
+      fs.mkdirSync(this.cwd, { recursive: true });
+      this.createdItems.push(`${projectName}/`);
+    } else {
+      this.skippedItems.push(`${projectName}/`);
+    }
   }
 
   /**
@@ -128,7 +153,7 @@ export class ProjectInitializer {
   /**
    * Display initialization summary
    */
-  private displaySummary(): void {
+  private displaySummary(projectName?: string): void {
     console.log('✅ Sungen initialized successfully!\n');
 
     if (this.createdItems.length > 0) {
@@ -149,10 +174,14 @@ export class ProjectInitializer {
     this.checkDependencies();
 
     console.log('\nNext steps:');
-    console.log('  1. Review README.md for workflow overview');
-    console.log('  2. Create your first screen with: sungen add --screen <name>');
-    console.log('  3. Generate mapped tests with: sungen map --screen <name> | sungen map --all');
-    console.log('  4. Generate tests with: sungen generate --screen <name> | sungen generate --all\n');
+    let stepIndex = 1;
+    if (projectName) {
+      console.log(`  ${stepIndex++}. cd ${projectName}`);
+    }
+    console.log(`  ${stepIndex++}. Review README.md for workflow overview`);
+    console.log(`  ${stepIndex++}. Create your first screen with: sungen add --screen <name>`);
+    console.log(`  ${stepIndex++}. Generate mapped tests with: sungen map --screen <name> | sungen map --all`);
+    console.log(`  ${stepIndex++}. Generate tests with: sungen generate --screen <name> | sungen generate --all\n`);
   }
 
   /**