@sun-asterisk/sungen 1.0.0

package/src/orchestrator/project-initializer.ts

@@ -0,0 +1,315 @@
+/**
+ * Project Initializer
+ * Creates essential directory structure for Sungen pipeline
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+export class ProjectInitializer {
+  private cwd: string;
+  private createdItems: string[] = [];
+  private skippedItems: string[] = [];
+
+  constructor() {
+    this.cwd = process.cwd();
+  }
+
+  /**
+   * Initialize project with essential directories and config
+   */
+  async initialize(): Promise<void> {
+    console.log('🚀 Initializing Sungen project...\n');
+
+    // Create directories
+    this.createDirectories();
+
+    // Create playwright config if doesn't exist
+    this.createPlaywrightConfig();
+
+    // Create/update .gitignore
+    this.updateGitignore();
+
+    // Create README
+    this.createReadme();
+
+    // Display summary
+    this.displaySummary();
+  }
+
+  /**
+   * Create essential directories only
+   */
+  private createDirectories(): void {
+    const dirs = [
+      'qa',
+      'qa/screens',
+      'specs',
+      'specs/generated'
+    ];
+
+    for (const dir of dirs) {
+      const fullPath = path.join(this.cwd, dir);
+      if (!fs.existsSync(fullPath)) {
+        fs.mkdirSync(fullPath, { recursive: true });
+        this.createdItems.push(dir + '/');
+      } else {
+        this.skippedItems.push(dir + '/');
+      }
+    }
+  }
+
+  /**
+   * Create Playwright configuration
+   */
+  private createPlaywrightConfig(): void {
+    const configPath = path.join(this.cwd, 'playwright.config.ts');
+
+    if (fs.existsSync(configPath)) {
+      this.skippedItems.push('playwright.config.ts');
+      return;
+    }
+
+    const configContent = this.getPlaywrightConfigTemplate();
+    fs.writeFileSync(configPath, configContent, 'utf-8');
+    this.createdItems.push('playwright.config.ts');
+  }
+
+  /**
+   * Update .gitignore with Sungen-specific entries
+   */
+  private updateGitignore(): void {
+    const gitignorePath = path.join(this.cwd, '.gitignore');
+    const sungenEntries = [
+      '# Sungen generated files',
+      'specs/generated/',
+      'test-results/',
+      'playwright-report/'
+    ];
+
+    if (!fs.existsSync(gitignorePath)) {
+      // Create new .gitignore with Node.js patterns
+      const content = this.getGitignoreTemplate() + '\n' + sungenEntries.join('\n') + '\n';
+      fs.writeFileSync(gitignorePath, content, 'utf-8');
+      this.createdItems.push('.gitignore');
+    } else {
+      // Append Sungen entries if not already present
+      let content = fs.readFileSync(gitignorePath, 'utf-8');
+      const needsUpdate = !content.includes('specs/generated/');
+      
+      if (needsUpdate) {
+        content += '\n' + sungenEntries.join('\n') + '\n';
+        fs.writeFileSync(gitignorePath, content, 'utf-8');
+        this.createdItems.push('.gitignore (updated)');
+      } else {
+        this.skippedItems.push('.gitignore');
+      }
+    }
+  }
+
+  /**
+   * Create README documentation
+   */
+  private createReadme(): void {
+    const readmePath = path.join(this.cwd, 'README.md');
+
+    if (fs.existsSync(readmePath)) {
+      this.skippedItems.push('README.md');
+      return;
+    }
+
+    const readmeContent = this.getReadmeTemplate();
+    fs.writeFileSync(readmePath, readmeContent, 'utf-8');
+    this.createdItems.push('README.md');
+  }
+
+  /**
+   * Display initialization summary
+   */
+  private displaySummary(): void {
+    console.log('✅ Sungen initialized successfully!\n');
+
+    if (this.createdItems.length > 0) {
+      console.log('Created:');
+      this.createdItems.forEach(item => {
+        console.log(`  ✓ ${item}`);
+      });
+    }
+
+    if (this.skippedItems.length > 0) {
+      console.log('\nAlready exists:');
+      this.skippedItems.forEach(item => {
+        console.log(`  ⊳ ${item}`);
+      });
+    }
+
+    // Check for Playwright installation
+    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');
+  }
+
+  /**
+   * Check for required dependencies
+   */
+  private checkDependencies(): void {
+    try {
+      const packageJsonPath = path.join(this.cwd, 'package.json');
+      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+      const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+
+      if (!deps['@playwright/test']) {
+        console.log('\n⚠️  Playwright not detected. Install with:');
+        console.log('   npm install -D @playwright/test');
+        console.log('   npx playwright install');
+      }
+    } catch (error) {
+      // Ignore if can't read package.json
+    }
+  }
+
+  /**
+   * Get Playwright configuration template
+   */
+  private getPlaywrightConfigTemplate(): string {
+    return `import { defineConfig, devices } from '@playwright/test';
+
+/**
+ * Playwright Test Configuration
+ * See https://playwright.dev/docs/test-configuration
+ */
+export default defineConfig({
+  testDir: './specs/generated',
+  
+  fullyParallel: true,
+  
+  forbidOnly: !!process.env.CI,
+  
+  retries: process.env.CI ? 2 : 0,
+  
+  workers: process.env.CI ? 1 : undefined,
+  
+  reporter: 'html',
+  
+  use: {
+    baseURL: 'http://localhost:3000',
+    
+    trace: 'on-first-retry',
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+  ],
+
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+  },
+});
+`;
+  }
+
+  /**
+   * Get .gitignore template
+   */
+  private getGitignoreTemplate(): string {
+    return `# Dependencies
+node_modules/
+
+# Build output
+dist/
+build/
+
+# Environment variables
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+`;
+  }
+
+  /**
+   * Get README template
+   */
+  private getReadmeTemplate(): string {
+    return `# Sungen Test Automation
+
+This project uses [Sungen](https://github.com/sun-asterisk/sungen) for AI-native E2E test generation.
+
+## Directory Structure
+
+\`\`\`
+├── qa/
+│   └── screens/          # Screen definitions and selectors
+└── specs/
+    └── generated/        # Auto-generated Playwright tests
+\`\`\`
+
+## Workflow
+
+### 1. Add new Screens
+Define a new screen for your application:
+
+\`\`\`bash
+sungen add --screen login
+\`\`\`
+
+### 2. Generate mapped or full tests
+Generate mapper elements for a specific screen or all screens:
+
+\`\`\`bash
+sungen map --screen login
+# or
+sungen map --all
+\`\`\`
+
+### 4. Generate full Playwright tests
+Generate complete tests based on mapped elements:
+
+\`\`\`bash
+sungen generate --screen login
+# or for all screens
+sungen generate --all
+\`\`\`
+
+## Configuration
+
+Edit \`sungen.config.yaml\` to customize:
+- Source root directory
+- UI framework (react/vue/html)
+- AI provider settings
+- Test generation options
+
+## Documentation
+
+- [Sungen Documentation](https://github.com/sun-asterisk/sungen)
+- [Playwright Documentation](https://playwright.dev)
+
+## Learn More
+
+Visit the [Sungen GitHub repository](https://github.com/sun-asterisk/sungen) for detailed guides and examples.
+`;
+  }
+}

package/src/orchestrator/reporter.ts

@@ -0,0 +1,36 @@
+/**
+ * Reporter
+ * Generates reports for test generation results
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { RuntimeConfig } from '../config/config-schema';
+import { GeneratedTest } from '../executor/test-generator';
+
+export class Reporter {
+  private config: RuntimeConfig;
+
+  constructor(config: RuntimeConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Generate report for test generation results
+   */
+  async generate(results: GeneratedTest[]): Promise<void> {
+    if (!this.config.verbose) {
+      return;
+    }
+
+    const totalScenarios = results.reduce((sum, r) => sum + r.stats.totalScenarios, 0);
+    const totalSteps = results.reduce((sum, r) => sum + r.stats.totalSteps, 0);
+    const totalTodos = results.reduce((sum, r) => sum + r.stats.todoCount, 0);
+
+    console.log('\n📊 Generation Report:');
+    console.log(`  Features: ${results.length}`);
+    console.log(`  Scenarios: ${totalScenarios}`);
+    console.log(`  Steps: ${totalSteps}`);
+    console.log(`  TODOs: ${totalTodos}`);
+  }
+}

package/src/orchestrator/screen-manager.ts

@@ -0,0 +1,268 @@
+/**
+ * Screen Manager
+ * Manages screen definition files in qa/screens directory
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface ScreenOptions {
+  name: string;
+  path?: string;
+  description?: string;
+}
+
+export class ScreenManager {
+  private cwd: string;
+  private screensDir: string;
+
+  constructor() {
+    this.cwd = process.cwd();
+    this.screensDir = path.join(this.cwd, 'qa', 'screens');
+  }
+
+  /**
+   * 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;
+    
+    // Create directory structure
+    const featuresDir = path.join(screenDir, 'features');
+    const selectorsDir = path.join(screenDir, 'selectors');
+    const testDataDir = path.join(screenDir, 'test-data');
+
+    // File paths
+    const featurePath = path.join(featuresDir, `${filename}.feature`);
+    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
+      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');
+        process.exit(1);
+      }
+    } else {
+      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.`);
+      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);
+    }
+
+    // Generate and write selector file
+    const selectorContent = this.generateSelectorTemplate(options, filename);
+    try {
+      fs.writeFileSync(selectorPath, selectorContent, 'utf-8');
+    } catch (error) {
+      console.error(`❌ Error: Failed to create selector file at ${selectorPath}`);
+      console.error(`   ${error instanceof Error ? error.message : String(error)}`);
+      process.exit(1);
+    }
+
+    // Generate and write test data file
+    const testDataContent = this.generateTestDataTemplate(options);
+    try {
+      fs.writeFileSync(testDataPath, testDataContent, 'utf-8');
+    } catch (error) {
+      console.error(`❌ Error: Failed to create test data file at ${testDataPath}`);
+      console.error(`   ${error instanceof Error ? error.message : String(error)}`);
+      process.exit(1);
+    }
+
+    // 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);
+  }
+
+  /**
+   * Validate screen name
+   */
+  private validateScreenName(name: string): void {
+    if (!name || name.trim().length === 0) {
+      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');
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Normalize screen name to kebab-case for filename
+   */
+  private normalizeScreenName(name: string): string {
+    return name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .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
+  I want to ${description}
+  So that I can accomplish my tasks
+  Path: ${featurePath}
+
+  @high
+  Scenario: Sample scenario for ${options.name}
+    Given User open 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
+#     selector: ""           # Playwright selector
+#     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:
+#  selector: ""
+#  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
+`;
+  }
+
+  /**
+   * 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}.yaml`)}`);
+    console.log(`  📄 ${path.join(screenDir, 'test-data', `${filename}.yaml`)}\n`);
+    
+    console.log('Next steps:');
+    console.log(`  1. Edit the Gherkin feature file to define test scenarios`);
+    console.log(`  2. Run: sungen map --screen ${filename}`);
+    console.log(`     This will generate selector mappings from your feature file\n`);
+    console.log('Documentation: https://github.com/sun-asterisk/sungen');
+  }
+}