@sun-asterisk/sungen 2.0.0 → 2.0.1

package/src/orchestrator/project-initializer.ts

@@ -236,124 +236,19 @@ export class ProjectInitializer {
     }
   }
 
+  /**
+   * Read a template file from the templates directory
+   */
+  private readTemplate(filename: string): string {
+    const templatePath = path.join(__dirname, 'templates', filename);
+    return fs.readFileSync(templatePath, 'utf-8');
+  }
+
   /**
    * Get AI rules content (shared between Copilot and Claude)
    */
   private getAIRulesContent(): string {
-    return `# Sungen AI Rules
-
-You assist with generating E2E test files for the sungen framework.
-sungen compiles Gherkin features + selector YAML + test data → Playwright tests.
-
-## File Structure
-
-Each screen lives under \`qa/screens/<name>/\`:
-\`\`\`
-qa/screens/<name>/
-├── features/          # .feature files (Gherkin)
-│   ├── <name>.feature
-│   └── <name>-<topic>.feature
-├── selectors/         # Element locator mappings
-│   └── <name>.yaml
-└── test-data/         # Test data values
-    └── <name>.yaml
-\`\`\`
-
-## Gherkin Syntax
-
-Standard pattern: \`User <action> [<Target>] <type> with {{<Value>}}\`
-
-\`[Element]\` → selector reference (mapped in selectors YAML)
-\`{{variable}}\` → test data reference (mapped in test-data YAML)
-
-### Pattern Shapes
-
-1. \`User click [Submit] button\` — simple action
-2. \`User fill [Email] field with {{email}}\` — action with data
-3. \`User see [Submit] button is disabled\` — state assertion
-4. \`User see [Panel] dialog with {{title}} is hidden\` — data + state
-5. \`User drag [Card] to [Column]\` — two targets
-6. \`User press Escape key\` — global keyboard
-7. \`User press Enter on [Search] field\` — key on target
-8. \`User wait for 3 seconds\` — timeout
-9. \`User wait for [Modal] dialog is hidden\` — wait for state
-10. \`User scroll to [Footer] section\` — scroll
-11. \`User switch to [Payment] frame\` — iframe
-12. \`User see [Avatar] image has {{url}}\` — attribute check
-13. \`User see [Table] table row 1 [Name] cell with {{name}}\` — table by index
-14. \`User see [Table] table row with {{filter}} has [Col] with {{val}}\` — table by filter
-15. \`User click [Edit] in [Table] table row with {{name}}\` — action in table
-16. \`User is on [login] page\` — navigation
-17. \`User see [Message] text contains {{partial}}\` — text assertion
-
-### States: hidden, visible, disabled, enabled, checked, unchecked, focused, empty
-
-### Tags:
-- \`@auth:role\` — Playwright storage state for auth
-- \`@steps:name\` — Define reusable step group
-- \`@extend:name\` — Inherit steps from another scenario
-- \`@manual\` — Skip scenario in generation
-
-## Selector YAML Schema
-
-\`\`\`yaml
-element.key:
-  type: 'testid'|'role'|'text'|'label'|'placeholder'|'locator'|'page'|'upload'|'frame'
-  value: 'button'              # role name, testid, CSS selector, etc.
-  name: 'Submit'               # accessible name
-  nth: 0                       # element index
-
-  # Disambiguation
-  exact: true                  # exact name match (avoid substring collisions)
-  scope: 'desktop navigation'  # parent landmark to scope within
-  match: 'exact'               # for getByText exact matching
-
-  # Complex elements
-  variant: 'native'|'custom'   # dropdown: <select> vs div-based
-  trigger: 'Upload Photo'      # button that triggers hidden file input
-  frame: '#iframe-id'          # iframe selector
-  contenteditable: true         # rich text editor
-
-  # Table columns (for table type)
-  columns:
-    name: { index: 0, header: 'Name' }
-    status: { index: 2, header: 'Status' }
-\`\`\`
-
-### Locator priority: data-testid > role+name > label > text > CSS
-
-## How to Generate from a URL
-
-1. Navigate to URL with Playwright MCP
-2. Take accessibility snapshot
-3. For each interactive element, create selector entry
-4. Prefer data-testid > role+name > text > CSS
-5. Set \`exact: true\` when name is substring of another element
-6. Set \`scope\` when element duplicated in header/footer
-7. Generate Gherkin scenarios covering the page
-8. Fill test-data with actual values from page
-
-## How to Fix Failing Tests
-
-| Error | Fix in selectors.yaml |
-|---|---|
-| strict mode: resolved to N elements | Add \`exact: true\` or \`scope\` |
-| element(s) not found | Fix \`name\`, \`type\`, or \`value\` |
-| getByText matched too many | Add \`match: 'exact'\` |
-
-## Commands
-
-\`\`\`bash
-sungen add --screen <name> --path <url-path>  # Create screen
-sungen generate --screen <name>                # Compile to .spec.ts
-sungen generate --all                          # Compile all screens
-sungen makeauth <role>                         # Capture auth state
-\`\`\`
-
-## Design Doc
-
-See \`docs/gherkin-dictionary.md\` for the complete grammar, all 17 patterns, and compiler rules.
-`;
+    return this.readTemplate('ai-rules.md');
   }
 
   /**
@@ -379,313 +274,20 @@ See \`docs/gherkin-dictionary.md\` for the complete grammar, all 17 patterns, an
    * Get Playwright configuration template
    */
   private getPlaywrightConfigTemplate(): string {
-    return `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,
-  // },
-});
-`;
+    return this.readTemplate('playwright.config.ts');
   }
 
   /**
    * Get .gitignore template
    */
   private getGitignoreTemplate(): string {
-    return `# Dependencies
-node_modules/
-
-# Build output
-dist/
-build/
-
-# Environment variables
-.env
-.env.local
-
-# IDE
-.vscode/
-.idea/
-*.swp
-*.swo
-`;
+    return this.readTemplate('gitignore');
   }
 
   /**
    * Get README template
    */
   private getReadmeTemplate(): string {
-    return `# Sungen Test Automation
-
-This project uses [Sungen v2](https://github.com/sun-asterisk/sungen) — a deterministic E2E test compiler.
-
-## How it works
-
-\`\`\`
-AI (Copilot/Claude + MCP Playwright) → visits URL → generates files
-sungen generate → compiles Gherkin + selectors + data → Playwright .spec.ts
-\`\`\`
-
-## Directory Structure
-
-\`\`\`
-├── qa/screens/<name>/
-│   ├── features/         # .feature files (Gherkin)
-│   ├── selectors/        # Element locator YAML mappings
-│   └── test-data/        # Test data YAML values
-├── specs/
-│   ├── generated/        # Auto-generated Playwright tests
-│   └── .auth/            # Auth storage states
-├── docs/
-│   └── gherkin-dictionary.md  # Full grammar & compiler rules
-├── .github/
-│   └── copilot-instructions.md  # AI rules for GitHub Copilot
-└── CLAUDE.md                    # AI rules for Claude Code
-\`\`\`
-
-## Workflow
-
-### 1. Add a screen
-
-\`\`\`bash
-sungen add --screen login --path /login
-# Add more features to an existing screen:
-sungen add --screen login --feature forgot-password
-\`\`\`
-
-### 2. Set up auth (if needed)
-
-\`\`\`bash
-sungen makeauth admin
-# Opens browser → login manually → saves specs/.auth/admin.json
-\`\`\`
-
-### 3. Generate Gherkin + selectors with AI
-
-Use your AI assistant (GitHub Copilot or Claude Code) to:
-1. Navigate to the page URL via MCP Playwright
-2. Take an accessibility snapshot
-3. Generate \`.feature\` + \`selectors.yaml\` + \`test-data.yaml\`
-
-The AI rules in \`.github/copilot-instructions.md\` and \`CLAUDE.md\` teach the AI
-how to write correct Gherkin syntax and selector YAML for sungen.
-
-### 4. Compile to Playwright tests
-
-\`\`\`bash
-sungen generate --screen login
-# or for all screens:
-sungen generate --all
-\`\`\`
-
-### 5. Run tests
-
-\`\`\`bash
-npx playwright test
-npx playwright test --ui   # interactive mode
-\`\`\`
-
-### 6. Fix failures (AI Verify loop)
-
-When tests fail, use AI to read the error → fix \`selectors.yaml\` → recompile → re-run.
-
-| Error | Fix in selectors.yaml |
-|---|---|
-| strict mode: resolved to N elements | Add \`exact: true\` or \`scope\` or \`nth\` |
-| element(s) not found | Fix \`name\`, \`type\`, or \`value\` |
-| getByText matched too many | Add \`match: 'exact'\` or \`nth\` |
-
----
-
-## Gherkin Guide
-
-### Syntax
-
-\`\`\`
-User <action> [<Target>] <type> with {{<Value>}}
-\`\`\`
-
-- \`[Target]\` → selector reference → lookup in \`selectors/*.yaml\`
-- \`{{Value}}\` → test data reference → lookup in \`test-data/*.yaml\`
-- \`<type>\` → element type: button, link, field, heading, text, etc.
-
-### Pattern Shapes (17 total)
-
-#### Actions
-
-| Pattern | Example |
-|---|---|
-| Simple click | \`User click [Submit] button\` |
-| Click with data | \`User click [Teammate] button with {{name}}\` |
-| Fill field | \`User fill [Email] field with {{email}}\` |
-| Check/Uncheck | \`User check [Remember me] checkbox\` |
-| Select dropdown | \`User select [Country] dropdown with {{country}}\` |
-| Upload file | \`User upload [Avatar] file with {{path}}\` |
-| Double click | \`User double click [Cell] element\` |
-| Hover | \`User hover [Info] icon\` |
-| Clear | \`User clear [Search] field\` |
-
-#### Keyboard
-
-| Pattern | Example |
-|---|---|
-| Global key | \`User press Escape key\` |
-| Key on element | \`User press Enter on [Search] field\` |
-
-#### Navigation
-
-| Pattern | Example |
-|---|---|
-| Open page | \`User is on [login] page\` |
-| See page (URL) | \`User see [dashboard] page\` |
-
-#### Wait
-
-| Pattern | Example |
-|---|---|
-| Wait timeout | \`User wait for 3 seconds\` |
-| Wait element | \`User wait for [Modal] dialog\` |
-| Wait hidden | \`User wait for [Loading] spinner is hidden\` |
-| Wait with data | \`User wait for [Dialog] dialog with {{title}}\` |
-
-#### Assertions
-
-| Pattern | Example |
-|---|---|
-| See element | \`User see [Welcome] heading\` |
-| See with value | \`User see [Title] heading with {{title}}\` |
-| State check | \`User see [Submit] button is disabled\` |
-| State + data | \`User see [Panel] dialog with {{title}} is hidden\` |
-| Text contains | \`User see [Message] text contains {{partial}}\` |
-
-States: \`hidden\`, \`visible\`, \`disabled\`, \`enabled\`, \`checked\`, \`unchecked\`, \`focused\`, \`empty\`
-
-#### Table
-
-| Pattern | Example |
-|---|---|
-| Row exists | \`User see [Users] table has row with {{name}}\` |
-| No row | \`User see [Users] table has no row with {{name}}\` |
-| Row count | \`User see [Users] table has {{count}} rows\` |
-| Column exists | \`User see [Users] table has [Email] column\` |
-| Cell by filter | \`User see [Users] table row with {{name}} has [Status] with {{status}}\` |
-| Cell by index | \`User see [Users] table row 1 [Name] cell with {{name}}\` |
-| Action in row | \`User click [Edit] in [Users] table row with {{name}}\` |
-| Empty table | \`User see [Users] table is empty\` |
-
-#### Scope
-
-| Pattern | Example |
-|---|---|
-| Scroll | \`User scroll to [Footer] section\` |
-| Frame enter | \`User switch to [Payment] frame\` |
-| Frame exit | \`User switch to [main] frame\` |
-
-### Tags
-
-| Tag | Purpose |
-|---|---|
-| \`@auth:role\` | Use Playwright storage state for auth |
-| \`@steps:name\` | Define reusable step group |
-| \`@extend:name\` | Inherit steps from another scenario |
-| \`@manual\` | Skip scenario in generation |
-
-### Selector YAML
-
-\`\`\`yaml
-submit.button:
-  type: 'role'              # testid, role, text, label, placeholder, locator, page
-  value: 'button'           # role name, testid value, CSS selector, etc.
-  name: 'Submit'            # accessible name
-  nth: 0                    # element index (0=first, 1=.nth(0), 2=.nth(1))
-  exact: true               # exact name match (avoid "Submit" matching "Submit Form")
-  scope: 'desktop navigation'  # scope to parent landmark
-  match: 'exact'            # exact text match for getByText
-\`\`\`
-
-Locator priority: \`data-testid\` > \`role+name\` > \`label\` > \`text\` > \`CSS\`
-
----
-
-## Documentation
-
-- [Gherkin Dictionary](docs/gherkin-dictionary.md) — full grammar, all 17 patterns, compiler rules
-- [Sungen GitHub](https://github.com/sun-asterisk/sungen)
-- [Playwright Documentation](https://playwright.dev)
-`;
+    return this.readTemplate('readme.md');
   }
 }

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