@sun-asterisk/sungen 2.0.3 → 2.1.0

package/src/orchestrator/project-initializer.ts

@@ -5,6 +5,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import { execSync } from 'child_process';
 
 export class ProjectInitializer {
   private baseCwd: string;
@@ -12,7 +13,7 @@ export class ProjectInitializer {
   private createdItems: string[] = [];
   private skippedItems: string[] = [];
 
-  constructor() {
+  constructor(private baseUrl: string) {
     this.baseCwd = process.cwd();
     this.cwd = this.baseCwd;
   }
@@ -37,6 +38,9 @@ export class ProjectInitializer {
     // Create directories
     this.createDirectories();
 
+    // Ensure package.json and install Playwright
+    await this.setupDependencies();
+
     // Create playwright config if doesn't exist
     this.createPlaywrightConfig();
 
@@ -99,7 +103,8 @@ export class ProjectInitializer {
       return;
     }
 
-    const configContent = this.getPlaywrightConfigTemplate();
+    const configContent = this.getPlaywrightConfigTemplate()
+      .replace('https://example.com', this.baseUrl);
     fs.writeFileSync(configPath, configContent, 'utf-8');
     this.createdItems.push('playwright.config.ts');
   }
@@ -174,9 +179,6 @@ export class ProjectInitializer {
       });
     }
 
-    // Check for Playwright installation
-    this.checkDependencies();
-
     console.log('\nNext steps:');
     let stepIndex = 1;
     if (projectName) {
@@ -192,48 +194,54 @@ export class ProjectInitializer {
    * Create AI rules files for GitHub Copilot and Claude Code
    */
   private createAIRules(): void {
-    const rulesContent = this.getAIRulesContent();
-
-    // GitHub Copilot: .github/copilot-instructions.md
-    const githubDir = path.join(this.cwd, '.github');
-    const copilotPath = path.join(githubDir, 'copilot-instructions.md');
-    if (!fs.existsSync(copilotPath)) {
-      if (!fs.existsSync(githubDir)) {
-        fs.mkdirSync(githubDir, { recursive: true });
-      }
-      fs.writeFileSync(copilotPath, rulesContent, 'utf-8');
-      this.createdItems.push('.github/copilot-instructions.md');
-    } else {
-      this.skippedItems.push('.github/copilot-instructions.md');
-    }
+    const aiTemplateDir = path.join(__dirname, 'templates', 'ai-instructions');
+
+    // File mapping: [templateFile, outputPath]
+    const fileMapping: [string, string][] = [
+      // Config
+      ['claude-config.md', 'CLAUDE.md'],
+      ['copilot-config.md', '.github/copilot-instructions.md'],
+
+      // Commands — Claude Code
+      ['claude-cmd-add-screen.md', '.claude/commands/sungen/add-screen.md'],
+      ['claude-cmd-make-tc.md', '.claude/commands/sungen/make-tc.md'],
+      ['claude-cmd-make-test.md', '.claude/commands/sungen/make-test.md'],
+
+      // Commands — GitHub Copilot
+      ['copilot-cmd-add-screen.md', '.github/prompts/sungen-add-screen.prompt.md'],
+      ['copilot-cmd-make-tc.md', '.github/prompts/sungen-make-tc.prompt.md'],
+      ['copilot-cmd-make-test.md', '.github/prompts/sungen-make-test.prompt.md'],
+
+      // Skills — Claude Code
+      ['claude-skill-gherkin-syntax.md', '.claude/skills/sungen-gherkin-syntax/SKILL.md'],
+      ['claude-skill-selector-keys.md', '.claude/skills/sungen-selector-keys/SKILL.md'],
+      ['claude-skill-error-mapping.md', '.claude/skills/sungen-error-mapping/SKILL.md'],
+
+      // Skills — GitHub Copilot
+      ['copilot-skill-gherkin-syntax.md', '.github/prompts/sungen-gherkin-syntax.prompt.md'],
+      ['copilot-skill-selector-keys.md', '.github/prompts/sungen-selector-keys.prompt.md'],
+      ['copilot-skill-error-mapping.md', '.github/prompts/sungen-error-mapping.prompt.md'],
+    ];
 
-    // Claude Code: CLAUDE.md
-    const claudePath = path.join(this.cwd, 'CLAUDE.md');
-    if (!fs.existsSync(claudePath)) {
-      fs.writeFileSync(claudePath, rulesContent, 'utf-8');
-      this.createdItems.push('CLAUDE.md');
-    } else {
-      this.skippedItems.push('CLAUDE.md');
-    }
+    for (const [templateFile, outputRelPath] of fileMapping) {
+      const outputPath = path.join(this.cwd, outputRelPath);
 
-    // Gherkin Dictionary: docs/gherkin-dictionary.md
-    const docsDir = path.join(this.cwd, 'docs');
-    const dictPath = path.join(docsDir, 'gherkin-dictionary.md');
-    if (!fs.existsSync(dictPath)) {
-      // Copy from sungen package if available, otherwise generate stub
-      const packageDictPath = path.join(__dirname, '..', '..', 'docs', 'gherkin-dictionary.md');
-      if (!fs.existsSync(docsDir)) {
-        fs.mkdirSync(docsDir, { recursive: true });
+      if (fs.existsSync(outputPath)) {
+        this.skippedItems.push(outputRelPath);
+        continue;
       }
-      if (fs.existsSync(packageDictPath)) {
-        fs.copyFileSync(packageDictPath, dictPath);
-      } else {
-        fs.writeFileSync(dictPath, '# Sungen Gherkin Dictionary\n\nSee https://github.com/sun-asterisk/sungen for the full dictionary.\n', 'utf-8');
+
+      const outputDir = path.dirname(outputPath);
+      if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
       }
-      this.createdItems.push('docs/gherkin-dictionary.md');
-    } else {
-      this.skippedItems.push('docs/gherkin-dictionary.md');
+
+      const templatePath = path.join(aiTemplateDir, templateFile);
+      const content = fs.readFileSync(templatePath, 'utf-8');
+      fs.writeFileSync(outputPath, content, 'utf-8');
+      this.createdItems.push(outputRelPath);
     }
+
   }
 
   /**
@@ -244,30 +252,38 @@ export class ProjectInitializer {
     return fs.readFileSync(templatePath, 'utf-8');
   }
 
-  /**
-   * Get AI rules content (shared between Copilot and Claude)
-   */
-  private getAIRulesContent(): string {
-    return this.readTemplate('ai-rules.md');
-  }
-
   /**
    * Check for required dependencies
    */
-  private checkDependencies(): void {
+  private async setupDependencies(): Promise<void> {
+    const packageJsonPath = path.join(this.cwd, 'package.json');
+    const execOpts = { cwd: this.cwd, stdio: 'inherit' as const };
+
+    // Initialize package.json if it doesn't exist
+    if (!fs.existsSync(packageJsonPath)) {
+      console.log('📦 No package.json found. Initializing...\n');
+      execSync('npm init -y', execOpts);
+      this.createdItems.push('package.json');
+    }
+
+    // Check if @playwright/test is already installed
     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');
+      if (deps['@playwright/test']) {
+        console.log('✓ @playwright/test already installed\n');
+        return;
       }
-    } catch (error) {
-      // Ignore if can't read package.json
+    } catch {
+      // package.json just created, proceed with install
     }
+
+    // Install Playwright
+    console.log('📦 Installing @playwright/test...\n');
+    execSync('npm install -D @playwright/test', execOpts);
+
+    console.log('\n🎭 Installing Playwright browsers...\n');
+    execSync('npx playwright install', execOpts);
   }
 
   /**

package/src/orchestrator/templates/ai-instructions/claude-cmd-add-screen.md

@@ -0,0 +1,42 @@
+---
+name: add-screen
+description: 'Add a new Sungen screen — scaffolds directories and delegates to make-tc for test case creation'
+argument-hint: [screen-name] [url-path]
+allowed-tools: Read, Grep, Bash, Glob
+---
+
+You are adding a new Sungen screen for test generation.
+
+## Parameters
+
+Parse from `$ARGUMENTS`:
+- **screen** — screen name (e.g., `login`, `dashboard`, `settings`)
+- **path** — URL path (e.g., `/login`, `/dashboard`, `/settings`)
+
+If **screen** is missing, ask: "What is the screen name? (e.g., `login`, `dashboard`)"
+If **path** is missing, ask: "What is the URL path? (e.g., `/login`, `/dashboard`)"
+
+## Steps
+
+### 1. Scaffold the screen
+
+Run:
+```bash
+sungen add --screen <screen> --path <path>
+```
+
+### 2. Create test cases
+
+Ask the user: "Would you like to create test cases now?"
+
+If yes, delegate to `/sungen:make-tc <screen>` to handle:
+- Exploring the live page or analyzing static designs
+- Gathering test viewpoints (UI/UX, Validation, Logic, Security)
+- Generating the 3 files (feature, selectors, test-data)
+
+### 3. Confirm
+
+Tell the user what was created and next steps:
+- If the page requires authentication before exploring via browser, read `baseURL` from `playwright.config.ts` and tell the user to manually run: `sungen makeauth <role> --url <baseURL>` (e.g., `sungen makeauth admin --url http://localhost:3000`). **Do NOT execute this command yourself.**
+- Edit the generated files as needed
+- Run `sungen generate --screen <screen>` to compile to Playwright `.spec.ts`

package/src/orchestrator/templates/ai-instructions/claude-cmd-make-tc.md

@@ -0,0 +1,60 @@
+---
+name: make-tc
+description: 'Create test cases for a Sungen screen — gathers viewpoints, explores live page or static designs, generates feature/selectors/test-data files'
+argument-hint: [screen-name]
+allowed-tools: Read, Grep, Bash, Glob
+---
+
+## Role
+
+You are a **Senior QA Engineer** specialized in test case design. You structure test cases by viewpoint categories and translate UI into Gherkin test cases following the `sungen-gherkin-syntax` and `sungen-selector-keys` skills.
+
+## Parameters
+
+Parse from `$ARGUMENTS`:
+- **screen** — screen name (e.g., `login`, `dashboard`)
+
+If missing, ask the user.
+
+## Steps
+
+### 1. Verify screen exists
+
+Check `qa/screens/<screen>/` exists. If not, tell user to run `/sungen:add-screen` first.
+
+### 2. Determine source mode
+
+Ask: "Do you have a **live page** or **static designs** (screenshots, Figma, images)?"
+
+**Live page →** explore via browser (see CLAUDE.md for Playwright MCP rules). If auth needed, check `specs/.auth/<role>.json` exists — if not, read `baseURL` from `playwright.config.ts` and tell the user to manually run: `sungen makeauth <role> --url <baseURL>` (e.g., `sungen makeauth admin --url http://localhost:3000`). **Do NOT execute `sungen makeauth` yourself.** Wait for the user to confirm auth is ready before proceeding.
+
+**Static designs →** ask user to provide screenshot paths, Figma exports, or UI descriptions. Note: selectors will be best-guess until live page is available.
+
+Present discovered elements to user, then proceed.
+
+### 3. Gather test viewpoints
+
+| VP Category | Description |
+|---|---|
+| **UI/UX** | Default screen appearance, static elements, default states |
+| **Validation** | Field/form validation, error messages |
+| **Logic** | Business logic, happy paths, redirects |
+| **Security** | Auth guards, permission checks |
+
+For each viewpoint, gather: **UI Target**, **Test Viewpoint**, **Expected Result**.
+
+User can provide all at once as a table:
+```
+| VP Category | UI Target | Test Viewpoint | Expected Result |
+```
+
+### 4. Generate files
+
+Generate the 3 files following `sungen-gherkin-syntax` and `sungen-selector-keys` skill rules:
+- `qa/screens/<screen>/features/<screen>.feature` — one Scenario per viewpoint
+- `qa/screens/<screen>/selectors/<screen>.yaml`
+- `qa/screens/<screen>/test-data/<screen>.yaml`
+
+### 5. Confirm
+
+Show what was generated. Next: `sungen generate --screen <screen>`

package/src/orchestrator/templates/ai-instructions/claude-cmd-make-test.md

@@ -0,0 +1,59 @@
+---
+name: make-test
+description: 'Compile and run Playwright tests for a Sungen screen — auto-fixes selectors on failure, falls back to AI .spec.ts fix after 5 attempts'
+argument-hint: [screen-name]
+allowed-tools: Read, Grep, Bash, Glob, Edit
+---
+
+## Role
+
+You are a **Senior Developer** specialized in Playwright test debugging. You diagnose test failures, fix selectors/test-data, and patch `.spec.ts` when needed. Use the `sungen-error-mapping` and `sungen-selector-keys` skills for error diagnosis and key fixes.
+
+## Parameters
+
+Parse from `$ARGUMENTS`:
+- **screen** — screen name (e.g., `login`, `dashboard`)
+
+If missing, ask the user.
+
+## Steps
+
+### 1. Verify screen exists
+
+Check `qa/screens/<screen>/` has all 3 source files. If not, tell user to run `/sungen:add-screen` and `/sungen:make-tc` first.
+
+### 2. Compile
+
+```bash
+sungen generate --screen <screen>
+```
+
+If fails, fix source files per `sungen-error-mapping` skill and retry.
+
+### 3. Run tests
+
+```bash
+npx playwright test specs/screens/<screen>/<screen>.spec.ts
+```
+
+If pass → Step 5. If fail → Step 4.
+
+### 4. Fix and retry (max 5 attempts)
+
+Per attempt:
+1. Read Playwright error output
+2. Map error to fix using `sungen-error-mapping` skill
+3. Fix `selectors.yaml` or `test-data.yaml`
+4. Recompile: `sungen generate --screen <screen>`
+5. Retest
+
+### 5. Fallback — AI fix .spec.ts
+
+After 5 failed attempts, ask user:
+> Tests still failing. Would you like me to directly fix the `.spec.ts` file?
+
+If yes: read `.spec.ts`, fix locators/assertions, mark with `// AI-fixed: <reason>`
+
+### 6. Confirm
+
+Show: pass/fail, attempt count, files changed.

package/src/orchestrator/templates/ai-instructions/claude-config.md

@@ -0,0 +1,90 @@
+# 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`.
+
+For Gherkin syntax, selector types, and YAML rules, the `sungen-gherkin-syntax` skill is auto-loaded when needed.
+For error diagnosis, the `sungen-error-mapping` skill is auto-loaded when needed.
+
+## 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'
+```
+
+## 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. Check if `specs/.auth/<role>.json` exists
+2. If not, read `baseURL` from `playwright.config.ts` and tell the user to manually run: `sungen makeauth <role> --url <baseURL>`. **Do NOT execute `sungen makeauth` yourself.** Wait for user confirmation.
+3. Read `specs/.auth/<role>.json`
+4. `browser_navigate` to the page
+5. `browser_evaluate` to inject localStorage and cookies from the JSON
+6. `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/ai-instructions/claude-skill-error-mapping.md

@@ -0,0 +1,27 @@
+---
+name: sungen-error-mapping
+description: 'Playwright and Sungen error to fix mapping. Auto-loaded when running or debugging tests.'
+user-invocable: false
+---
+
+## Playwright Errors → Fix
+
+| Error | Fix in `selectors.yaml` |
+|---|---|
+| strict mode violation | add `nth`, `exact: true`, or specific `name` |
+| Element is not an input | change `type` or `value` |
+| Timeout waiting for selector | fix `type`/`value`/`name` to match element |
+| toBeVisible Timeout | verify accessible name or use `testid` |
+| toHaveText mismatch | fix in `test-data.yaml` |
+| Navigation failed | fix page `value` path |
+| not a select | set `variant: 'custom'` |
+| Frame not found | fix `frame` value |
+
+## Sungen Errors → Fix
+
+| Error | Fix |
+|---|---|
+| Unknown step pattern | rewrite `.feature` step to match supported pattern |
+| Missing selector | add key to `selectors.yaml` |
+| Missing variable | add key to `test-data.yaml` |
+| Invalid selector type | use: role/testid/placeholder/label/text/locator/page/upload/frame |

package/src/orchestrator/templates/ai-instructions/claude-skill-gherkin-syntax.md

@@ -0,0 +1,123 @@
+---
+name: sungen-gherkin-syntax
+description: 'Sungen Gherkin patterns, selector types, and YAML key rules. Auto-loaded when writing .feature, selectors.yaml, or test-data.yaml.'
+user-invocable: false
+---
+
+## Step Patterns (58 patterns)
+
+### Setup
+
+```
+User is on [T] page                              # navigate to page
+User navigate to [T] page with {{v}}             # navigate with data
+User is logged in | is not logged in              # auth state
+```
+
+### Form
+
+```
+User fill [T] field with {{v}}                   # text input
+User clear [T] field                             # clear input
+User check [T] checkbox                          # check
+User uncheck [T] checkbox                        # uncheck
+User select [T] dropdown with {{v}}              # select option
+User upload [T] file with {{f}}                  # file upload
+```
+
+### Interaction
+
+```
+User click [T] button                            # click
+User click [T] button with {{v}}                 # click with text match
+User double click [T] element                    # double click
+User hover [T] icon                              # hover
+```
+
+### Keyboard
+
+```
+User press Escape key                            # global key press
+User press Enter on [T] field                    # key on element
+```
+
+### Wait
+
+```
+User wait for N seconds                          # wait timeout
+User wait for [T] dialog                         # wait for element
+User wait for [T] dialog is STATE                # wait for state
+User wait for [T] dialog with {{v}}              # wait for element with text
+User wait for [T] page                           # wait for navigation
+```
+
+### Scroll & Frame
+
+```
+User scroll to [T] section                       # scroll into view
+User switch to [T] frame                         # enter/exit iframe
+```
+
+### Assertions
+
+```
+User see [T] page                                # URL assertion
+User see [T] heading                             # visibility
+User see [T] heading with {{v}}                  # visibility + text
+User see [T] text contains {{v}}                 # partial text match
+User see [T] text has text {{v}}                 # exact text match
+User see [T] button is STATE                     # state assertion
+User see [T] dialog with {{v}} is STATE          # text + state
+User see {{v}}                                   # see data text
+```
+
+### Table
+
+```
+User see [Table] table has row with {{f}}        # row exists
+User see [Table] table has no row with {{f}}     # row not exists
+User see [Table] table has {{count}} rows        # row count
+User see [Table] table has [Col] column          # column exists
+User see [Table] table is empty                  # empty table
+User see [Table] table row with {{f}} has [Col] with {{v}}  # cell by filter
+User see [Table] table row 1 [Col] cell with {{v}}          # cell by index
+User click [Act] in [Table] table row with {{f}}             # action in row
+```
+
+### States
+
+`hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty`
+
+### Element Types
+
+`page` `button` `link` `field` `textarea` `heading` `text` `checkbox` `radio` `switch` `dropdown` `dialog` `modal` `menu` `menuitem` `tab` `tabpanel` `table` `row` `cell` `list` `listitem` `icon` `image` `alert` `spinner` `progressbar` `section` `region` `nav` `frame` `uploader` `file` `columnheader` `tooltip` `slider` `treeitem`
+
+## YAML Keys
+
+`[Reference]` → **lowercase, spaces→dots**: `[Search Content]` → `search.content:`
+
+## Selectors (priority order)
+
+| type | value | name | use |
+|---|---|---|---|
+| `testid` | data-testid | — | when exists |
+| `role` | button/heading/link… | accessible name | interactive elements |
+| `placeholder` | placeholder text | — | inputs |
+| `label` | label text | — | labeled inputs |
+| `text` | — | — | static text |
+| `locator` | CSS selector | — | last resort |
+| `page` | relative URL | — | navigation |
+| `upload` | — | — | file inputs |
+| `frame` | iframe selector | — | iframes |
+
+Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `columns`
+
+## Tags
+
+| Tag | Effect |
+|---|---|
+| `@auth:role` | Use auth storage state for role |
+| `@no-auth` | Disable inherited auth |
+| `@steps:name` | Define reusable step block |
+| `@extend:name` | Prepend steps from @steps block |
+| `@manual` | Skip in generation |