@sun-asterisk/sungen 1.0.24 → 2.0.1

package/src/orchestrator/screen-manager.ts

@@ -9,6 +9,7 @@ import * as path from 'path';
 export interface ScreenOptions {
   name: string;
   path?: string;
+  feature?: string;
   description?: string;
 }
 
@@ -25,20 +26,23 @@ export class ScreenManager {
    * Add a new screen definition
    */
   async addScreen(options: ScreenOptions): Promise<void> {
-    console.log(`📱 Adding screen: ${options.name}...\n`);
-
     // Validate screen name
     this.validateScreenName(options.name);
 
     // Normalize screen name for directory
     const screenName = this.normalizeScreenName(options.name);
     const screenDir = path.join(this.screensDir, screenName);
-    
-    // Derive filename from path or use screen name
-    const filename = options.path 
-      ? this.extractFilenameFromPath(options.path)
-      : screenName;
-    
+
+    // Derive filename: --feature flag creates "<screen>-<feature>" name
+    let filename: string;
+    if (options.feature) {
+      filename = `${screenName}-${this.normalizeScreenName(options.feature)}`;
+    } else if (options.path) {
+      filename = this.extractFilenameFromPath(options.path);
+    } else {
+      filename = screenName;
+    }
+
     // Create directory structure
     const featuresDir = path.join(screenDir, 'features');
     const selectorsDir = path.join(screenDir, 'selectors');
@@ -46,102 +50,92 @@ export class ScreenManager {
 
     // File paths
     const featurePath = path.join(featuresDir, `${filename}.feature`);
-    const selectorOverridePath = path.join(selectorsDir, `${filename}.override.yaml`);
-    const testDataOverridePath = path.join(testDataDir, `${filename}.override.yaml`);
+    const selectorPath = path.join(selectorsDir, `${filename}.yaml`);
+    const testDataPath = path.join(testDataDir, `${filename}.yaml`);
 
     // Smart behavior: Create dirs only if first file
     const isFirstFile = !fs.existsSync(screenDir);
-    
+
     if (isFirstFile) {
-      console.log(`📱 Creating screen: ${options.name}...\n`);
-      
-      // Create directories
+      console.log(`Creating screen: ${options.name}\n`);
+
       try {
         if (!fs.existsSync(this.screensDir)) {
           fs.mkdirSync(this.screensDir, { recursive: true });
-          console.log(`✓ Created directory: qa/screens/\n`);
         }
         fs.mkdirSync(featuresDir, { recursive: true });
         fs.mkdirSync(selectorsDir, { recursive: true });
         fs.mkdirSync(testDataDir, { recursive: true });
       } catch (error) {
-        console.error(`❌ Error: Failed to create directories`);
-        console.error(`   ${error instanceof Error ? error.message : String(error)}`);
-        console.error('   Check file permissions and try again.\n');
+        console.error(`Error: Failed to create directories`);
+        console.error(`  ${error instanceof Error ? error.message : String(error)}`);
         process.exit(1);
       }
     } else {
-      console.log(`📄 Adding feature to screen: ${options.name}...\n`);
+      console.log(`Adding feature to screen: ${options.name}\n`);
     }
-    
+
     // Check file existence to prevent overwrite
     if (fs.existsSync(featurePath)) {
-      console.error(`❌ Error: Feature file "${filename}.feature" already exists`);
-      console.error(`   Path: ${featurePath}`);
-      console.error(`   Use a different --path value or delete existing file.`);
+      console.error(`Error: Feature file "${filename}.feature" already exists`);
+      console.error(`  Path: ${featurePath}`);
+      console.error(`  Use a different --path or --feature value.`);
       process.exit(1);
     }
 
     // Generate and write feature file
     const featureContent = this.generateFeatureTemplate(options, filename);
-    try {
-      fs.writeFileSync(featurePath, featureContent, 'utf-8');
-    } catch (error) {
-      console.error(`❌ Error: Failed to create feature file at ${featurePath}`);
-      console.error(`   ${error instanceof Error ? error.message : String(error)}`);
-      process.exit(1);
+    fs.writeFileSync(featurePath, featureContent, 'utf-8');
+
+    // Generate empty selector YAML (with page entry)
+    if (!fs.existsSync(selectorPath)) {
+      const pagePath = options.path || `/${screenName}`;
+      fs.writeFileSync(selectorPath, [
+        `# ${options.name} Screen Selectors`,
+        `# Fill via AI or manually`,
+        ``,
+        `${screenName}:`,
+        `  type: 'page'`,
+        `  value: '${pagePath}'`,
+        `  nth: 0`,
+        ``,
+      ].join('\n'), 'utf-8');
     }
 
-    // Generate and write selector override file (NOT base file)
-    const selectorOverrideContent = this.generateSelectorOverrideTemplate(filename);
-    try {
-      fs.writeFileSync(selectorOverridePath, selectorOverrideContent, 'utf-8');
-    } catch (error) {
-      console.error(`❌ Error: Failed to create selector override file at ${selectorOverridePath}`);
-      console.error(`   ${error instanceof Error ? error.message : String(error)}`);
-      process.exit(1);
+    // Generate empty test-data YAML
+    if (!fs.existsSync(testDataPath)) {
+      fs.writeFileSync(testDataPath, [
+        `# ${options.name} Screen Test Data`,
+        `# Fill via AI or manually`,
+        `# Reference in features using {{variable}} syntax`,
+        ``,
+      ].join('\n'), 'utf-8');
     }
 
-    // Generate and write test data override file (NOT base file)
-    const testDataOverrideContent = this.generateTestDataOverrideTemplate(filename);
-    try {
-      fs.writeFileSync(testDataOverridePath, testDataOverrideContent, 'utf-8');
-    } catch (error) {
-      console.error(`❌ Error: Failed to create test data override file at ${testDataOverridePath}`);
-      console.error(`   ${error instanceof Error ? error.message : String(error)}`);
-      process.exit(1);
-    }
+    // Display success
+    console.log(`Created files:`);
+    console.log(`  ${path.relative(this.cwd, featurePath)}`);
+    console.log(`  ${path.relative(this.cwd, selectorPath)}`);
+    console.log(`  ${path.relative(this.cwd, testDataPath)}\n`);
 
-    // Display success message
-    if (isFirstFile) {
-      console.log(`✓ Created screen: ${options.name} at ${screenDir}`);
-    } else {
-      console.log(`✓ Added feature: ${filename} to ${screenName}`);
-    }
-    
-    this.displaySuccess(options.name, filename, screenDir);
+    console.log('Next steps:');
+    console.log(`  1. Use AI (Copilot/Claude) to generate Gherkin + selectors from the live page`);
+    console.log(`  2. Fill in test-data values`);
+    console.log(`  3. Compile: sungen generate --screen ${screenName}`);
+    console.log(`  4. Run: npx playwright test\n`);
   }
 
-  /**
-   * Validate screen name
-   */
   private validateScreenName(name: string): void {
     if (!name || name.trim().length === 0) {
-      console.error('❌ Error: Screen name cannot be empty');
+      console.error('Error: Screen name cannot be empty');
       process.exit(1);
     }
-
-    // Check if name contains at least one alphanumeric character
     if (!/[a-zA-Z0-9]/.test(name)) {
-      console.error('❌ Error: Screen name must contain at least one alphanumeric character');
-      console.error('   Valid examples: login, user-profile, Dashboard');
+      console.error('Error: Screen name must contain at least one alphanumeric character');
       process.exit(1);
     }
   }
 
-  /**
-   * Normalize screen name to kebab-case for filename
-   */
   private normalizeScreenName(name: string): string {
     return name
       .toLowerCase()
@@ -150,29 +144,18 @@ export class ScreenManager {
       .replace(/-+/g, '-');
   }
 
-  /**
-   * Extract filename from path value
-   */
   private extractFilenameFromPath(pathString: string): string {
-    // Remove leading and trailing slashes
     const cleanPath = pathString.replace(/^\/+/, '').replace(/\/+$/, '');
-    
-    // Split by '/' and take last segment
     const segments = cleanPath.split('/');
     const lastSegment = segments[segments.length - 1];
-    
-    // Normalize to kebab-case
     return this.normalizeScreenName(lastSegment);
   }
 
-  /**
-   * Generate feature file template
-   */
   private generateFeatureTemplate(options: ScreenOptions, filename: string): string {
     const screenName = this.normalizeScreenName(options.name);
     const featurePath = options.path || `/${screenName}`;
     const description = options.description || `interact with the ${options.name} screen`;
-    
+
     return `Feature: ${options.name} Screen
 
   As a user
@@ -182,164 +165,9 @@ export class ScreenManager {
 
   @high
   Scenario: Sample scenario for ${options.name}
-    Given User is on [${options.name}] page
+    Given User is on [${screenName}] page
     When User click [element] button
     Then User see [result] text with {{success}}
 `;
   }
-
-  /**
-   * Generate selector YAML template
-   */
-  private generateSelectorTemplate(options: ScreenOptions, filename: string): string {
-    const timestamp = new Date().toISOString().split('T')[0];
-    const screenPath = options.path || '';
-
-    return `# ${options.name} Screen Selectors
-# Created: ${timestamp}
-${screenPath ? `# Path: ${screenPath}` : '# Path: (not specified - update as needed)'}
-
-# Example element - replace with actual elements or use 'sungen map'
-# 
-# Element structure:
-#   key: element-identifier
-#     locator: ""           # Playwright locator
-#     type: text|role|placeholder|testid|xpath
-#     value: "text content"  # Element value/text/label
-#     name: "Display Name"   # Optional: readable name
-#     nth: 0                 # Optional: element index if multiple matches
-
-# element:
-#  locator: ""
-#  type: role
-#  value: "button"
-#  name: "element"
-#  nth: 0
-
-# Next steps:
-# 1. Edit the feature file: qa/screens/${filename}/features/${filename}.feature
-# 2. Run: sungen map --screen ${filename}
-#    This will populate selectors from your feature file
-# 
-# Documentation: https://github.com/sun-asterisk/sungen
-`;
-  }
-
-  /**
-   * Generate test data YAML template
-   */
-  private generateTestDataTemplate(options: ScreenOptions): string {
-    const timestamp = new Date().toISOString().split('T')[0];
-
-    return `# ${options.name} Screen Test Data
-# Created: ${timestamp}
-
-# Define test data variables here
-# Example:
-# success: "Operation completed successfully"
-# username: "testuser@example.com"
-# password: "SecurePassword123"
-
-# Next steps:
-# 1. Add test data variables referenced in your feature scenarios
-# 2. Use {{variable}} syntax in your feature files to reference these values
-`;
-  }
-
-  /**
-   * Generate selector override YAML template (empty with guidelines)
-   */
-  private generateSelectorOverrideTemplate(filename: string): string {
-    return `# ${filename}.override.yaml - User Override File
-# This file will NEVER be modified by 'sungen map' command
-# Use this to override auto-generated selectors or add custom ones
-#
-# Format:
-#   element.key:
-#     locator: "css-locator-here"  # Optional: custom CSS locator
-#     type: role|testid|placeholder|label|text
-#     value: "value-for-type"
-#     name: "Display Name"           # Optional
-#     nth: 0                          # Optional: element index
-#
-# Examples:
-#   email.field:
-#     type: testid
-#     value: "login-email"
-#   
-#   submit.button:
-#     type: role
-#     value: "button"
-#     name: "Sign In"
-#   
-#   custom.element:
-#     locator: "#my-custom-id"
-#     type: placeholder
-#     value: "Enter text"
-#
-# Leave empty if no overrides needed
-# Base selectors will be auto-generated by: sungen map --screen ${filename}
-`;
-  }
-
-  /**
-   * Generate test-data override YAML template (empty with guidelines)
-   */
-  private generateTestDataOverrideTemplate(filename: string): string {
-    return `# ${filename}.override.yaml - User Override File
-# This file will NEVER be modified by 'sungen map' command
-# Use this to override auto-generated test data or add custom data
-#
-# Format:
-#   variable_name: "value"
-#   
-#   nested:
-#     variable: "value"
-#   
-#   array_example:
-#     - "item1"
-#     - "item2"
-#
-# Examples:
-#   # Simple string override
-#   valid_email: "custom@example.com"
-#   
-#   # Nested object override
-#   api:
-#     url: "https://staging.example.com"
-#     timeout: 5000
-#   
-#   # Array override
-#   test_users:
-#     - "user1@example.com"
-#     - "user2@example.com"
-#
-# Leave empty if no overrides needed
-# Base test data will be auto-generated by: sungen map --screen ${filename}
-`;
-  }
-
-  /**
-   * Display success message with next steps
-   */
-  private displaySuccess(name: string, filename: string, screenDir: string): void {
-    console.log('✅ Screen definition created successfully!\n');
-    console.log(`Screen: ${name}`);
-    console.log(`Path:   ${screenDir}\n`);
-    
-    console.log('Created files:');
-    console.log(`  📄 ${path.join(screenDir, 'features', `${filename}.feature`)}`);
-    console.log(`  📝 ${path.join(screenDir, 'selectors', `${filename}.override.yaml`)} (user-editable)`);
-    console.log(`  📝 ${path.join(screenDir, 'test-data', `${filename}.override.yaml`)} (user-editable)\n`);
-    
-    console.log('📌 Note: Override files will NEVER be modified by automation');
-    console.log('   Edit these files to customize selectors and test data\n');
-    
-    console.log('Next steps:');
-    console.log(`  1. Edit the Gherkin feature file to define test scenarios`);
-    console.log(`  2. Run: sungen map --screen ${name}`);
-    console.log(`     This will generate BASE selector and test-data files`);
-    console.log(`     (Override files remain untouched)\n`);
-    console.log('Documentation: https://github.com/sun-asterisk/sungen');
-  }
 }

package/src/orchestrator/templates/ai-rules.md

@@ -0,0 +1,189 @@
+# Sungen AI Rules
+
+You generate 3 files for sungen — a Gherkin compiler that produces Playwright tests.
+**You do NOT write Playwright code.** You only write `.feature`, `selectors.yaml`, and `test-data.yaml`.
+
+## Complete Example
+
+Given a login page, here are the 3 files you generate:
+
+**qa/screens/login/features/login.feature**
+```gherkin
+@auth:admin
+Feature: Login Screen
+
+  Scenario: Successful login
+    Given User is on [login] page
+    When User fill [Email] field with {{email}}
+    And User fill [Password] field with {{password}}
+    And User click [Submit] button
+    Then User see [Welcome] heading with {{welcome_text}}
+    And User see [Dashboard] link is visible
+```
+
+**qa/screens/login/selectors/login.yaml**
+```yaml
+login:
+  type: 'page'
+  value: '/login'
+
+email:
+  type: 'placeholder'
+  value: 'Enter your email'
+
+password:
+  type: 'placeholder'
+  value: 'Enter your password'
+
+submit:
+  type: 'role'
+  value: 'button'
+  name: 'Submit'
+
+welcome:
+  type: 'role'
+  value: 'heading'
+  name: 'Welcome'
+
+dashboard:
+  type: 'role'
+  value: 'link'
+  name: 'Dashboard'
+```
+
+**qa/screens/login/test-data/login.yaml**
+```yaml
+email: 'admin@example.com'
+password: 'password123'
+welcome_text: 'Welcome back'
+```
+
+## Key Rules
+
+### YAML key format (CRITICAL)
+
+YAML keys = Gherkin `[Reference]` converted to: **lowercase, spaces→dots, no special chars**.
+
+| Gherkin | YAML Key |
+|---|---|
+| `[Submit]` | `submit:` |
+| `[Search Content]` | `search.content:` |
+| `[Kudos Detail Modal]` | `kudos.detail.modal:` |
+| `[Page 2]` | `page.2:` |
+
+**NEVER use spaces in YAML keys.**
+
+### Gherkin patterns (all 17)
+
+```
+User click [Target] button                              # click
+User fill [Target] field with {{value}}                  # fill
+User check [Target] checkbox                             # check/uncheck
+User select [Target] dropdown with {{value}}             # select
+User upload [Target] file with {{filename}}              # upload
+User double click [Target] element                       # double click
+User hover [Target] icon                                 # hover
+User clear [Target] field                                # clear
+User press Escape key                                    # global key
+User press Enter on [Target] field                       # key on element
+User is on [target] page                                 # navigate (Given)
+User see [target] page                                   # URL assertion (Then)
+User wait for 3 seconds                                  # wait timeout
+User wait for [Target] dialog is hidden                  # wait state
+User scroll to [Target] section                          # scroll
+User switch to [Target] frame                            # iframe
+User see [Target] heading with {{value}}                 # visible assertion
+User see [Target] button is disabled                     # state assertion
+User see [Target] text contains {{partial}}              # text contains
+User see [Table] table has row with {{filter}}           # table row
+User see [Table] table row with {{f}} has [Col] with {{v}} # table cell
+User click [Edit] in [Table] table row with {{name}}     # action in row
+```
+
+States: `hidden`, `visible`, `disabled`, `enabled`, `checked`, `unchecked`, `focused`, `empty`
+
+### Selector types
+
+| type | value | name | when to use |
+|---|---|---|---|
+| `role` | `button`, `heading`, `link`, etc. | accessible name | **preferred** for interactive elements |
+| `testid` | `data-testid` value | — | when `data-testid` exists |
+| `placeholder` | placeholder text | — | input fields |
+| `label` | label text | — | labeled inputs |
+| `text` | — | — | static text content |
+| `locator` | CSS selector | — | **last resort** |
+| `page` | relative URL path | — | navigation targets |
+| `upload` | — | — | file upload inputs |
+| `frame` | iframe selector | — | iframe targets |
+
+Priority: `testid` > `role+name` > `placeholder` > `label` > `text` > `locator`
+
+### Tags
+
+| Tag | Effect |
+|---|---|
+| `@auth:role` | Adds `test.use({ storageState: 'specs/.auth/role.json' })` |
+| `@steps:name` | Define reusable step group |
+| `@extend:name` | Inherit steps from another scenario |
+| `@manual` | Skip in generation |
+
+### Selector options
+
+```yaml
+element.key:
+  type: 'role'
+  value: 'button'
+  name: 'Submit'          # accessible name
+  nth: 0                  # element index (0=first)
+  exact: true             # exact name match (avoid substring collisions)
+  scope: 'navigation'     # parent landmark scope
+  match: 'exact'          # exact text match for getByText
+  variant: 'native'       # dropdown: 'native' (<select>) or 'custom' (div-based)
+  frame: '#iframe-id'     # iframe scope
+  contenteditable: true   # rich text editor
+  columns:                # table columns
+    name: { index: 0, header: 'Name' }
+```
+
+### Navigation and baseURL
+
+Page selectors use **relative paths only**. Playwright prepends `baseURL` from `playwright.config.ts`.
+
+```yaml
+login:
+  type: 'page'
+  value: '/login'       # NOT https://example.com/login
+```
+
+### Auth
+
+- `@auth:admin` on Feature or Scenario → compiler adds `test.use({ storageState: 'specs/.auth/admin.json' })`
+- Auth JSON created by: `sungen makeauth admin` (opens browser for manual login)
+- **Login pages**: no `@auth` tag needed
+- **Authenticated pages**: always add `@auth:role`
+
+## Using Playwright MCP to explore pages
+
+When exploring a page to generate test files:
+1. Read `playwright.config.ts` for `baseURL`
+2. Use `browser_navigate` to open `baseURL + /path`
+3. Use `browser_snapshot` to see all elements
+4. Generate the 3 files from the snapshot
+
+**NEVER use `browser_run_code`.** It fails with `require is not defined`.
+Only use: `browser_navigate`, `browser_snapshot`, `browser_click`, `browser_fill_form`, `browser_evaluate`.
+
+To browse authenticated pages via MCP:
+1. Read `specs/.auth/role.json` with your file read tool
+2. `browser_navigate` to the page
+3. `browser_evaluate` to inject localStorage and cookies from the JSON
+4. `browser_navigate` again to reload with auth
+
+## Commands
+
+```bash
+sungen add --screen <name> --path <url-path>  # Create screen
+sungen generate --screen <name>                # Compile to .spec.ts
+sungen generate --all                          # Compile all
+sungen makeauth <role>                         # Capture auth state
+```

package/src/orchestrator/templates/gitignore

@@ -0,0 +1,16 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+build/
+
+# Environment variables
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo

package/src/orchestrator/templates/playwright.config.ts

@@ -0,0 +1,80 @@
+import { defineConfig, devices } from '@playwright/test';
+
+/**
+ * Read environment variables from file.
+ * https://github.com/motdotla/dotenv
+ */
+// import dotenv from 'dotenv';
+// import path from 'path';
+// dotenv.config({ path: path.resolve(__dirname, '.env') });
+
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+export default defineConfig({
+  testDir: './specs/generated',
+  /* Run tests in files in parallel */
+  fullyParallel: true,
+  /* Fail the build on CI if you accidentally left test.only in the source code. */
+  forbidOnly: !!process.env.CI,
+  /* Retry on CI only */
+  retries: process.env.CI ? 2 : 0,
+  /* Opt out of parallel tests on CI. */
+  workers: process.env.CI ? 1 : undefined,
+  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
+  reporter: 'html',
+  /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
+  use: {
+    /* Base URL to use in actions like `await page.goto('')`. */
+    baseURL: 'https://example.com',
+
+    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
+    trace: 'on-first-retry',
+  },
+
+  /* Configure projects for major browsers */
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+
+    /*
+    // {
+    //   name: 'firefox',
+    //   use: { ...devices['Desktop Firefox'] },
+    // },
+
+    // {
+    //   name: 'webkit',
+    //   use: { ...devices['Desktop Safari'] },
+    // },
+
+    /* Test against mobile viewports.
+    // {
+    //   name: 'Mobile Chrome',
+    //   use: { ...devices['Pixel 5'] },
+    // },
+    // {
+    //   name: 'Mobile Safari',
+    //   use: { ...devices['iPhone 12'] },
+    // },
+
+    /* Test against branded browsers. */
+    // {
+    //   name: 'Microsoft Edge',
+    //   use: { ...devices['Desktop Edge'], channel: 'msedge' },
+    // },
+    // {
+    //   name: 'Google Chrome',
+    //   use: { ...devices['Desktop Chrome'], channel: 'chrome' },
+    // },
+  ],
+
+  /* Run your local dev server before starting the tests */
+  // webServer: {
+  //   command: 'npm run start',
+  //   url: 'http://localhost:3000',
+  //   reuseExistingServer: !process.env.CI,
+  // },
+});