@sun-asterisk/sungen 2.0.3 → 2.1.1

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

@@ -1,189 +0,0 @@
-# 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
-```