@sun-asterisk/sungen 2.0.3 → 2.1.0

package/src/orchestrator/templates/readme.md

@@ -19,8 +19,6 @@ sungen generate → compiles Gherkin + selectors + data → Playwright .spec.ts
 ├── 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
@@ -28,55 +26,62 @@ sungen generate → compiles Gherkin + selectors + data → Playwright .spec.ts
 
 ## 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
+```
+Step 1                Step 2                Step 3
+┌──────────┐         ┌──────────┐         ┌──────────┐
+│ /add-    │────────▶│ /make-tc │────────▶│ /make-   │
+│ screen   │         │          │         │ test     │
+└──────────┘         └──────────┘         └──────────┘
+ Scaffold              Design TCs           Compile &
+ directories           & generate           run tests
+                       3 files
 ```
 
-### 2. Set up auth (if needed)
+Use AI commands (Claude Code or GitHub Copilot) to drive the workflow:
 
-```bash
-sungen makeauth admin
-# Opens browser → login manually → saves specs/.auth/admin.json
-```
+### Step 1: Add a screen
 
-### 3. Generate Gherkin + selectors with AI
+| Claude Code | GitHub Copilot |
+|---|---|
+| `/sungen:add-screen login /login` | `@workspace /sungen-add-screen login /login` |
 
-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`
+Scaffolds `qa/screens/<name>/` with empty feature, selectors, and test-data files, then asks if you want to create test cases.
 
-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.
+### Step 2: Create test cases
 
-### 4. Compile to Playwright tests
+| Claude Code | GitHub Copilot |
+|---|---|
+| `/sungen:make-tc login` | `@workspace /sungen-make-tc login` |
 
-```bash
-sungen generate --screen login
-# or for all screens:
-sungen generate --all
-```
+AI acts as a **Senior QA Engineer**: explores the live page (via Playwright MCP) or analyzes static designs, gathers test viewpoints (UI/UX, Validation, Logic, Security), and generates the 3 files.
 
-### 5. Run tests
+### Step 3: Compile & run tests
+
+| Claude Code | GitHub Copilot |
+|---|---|
+| `/sungen:make-test login` | `@workspace /sungen-make-test login` |
+
+AI acts as a **Senior Developer**: compiles Gherkin → Playwright `.spec.ts`, runs tests, and auto-fixes selectors/test-data on failure (up to 5 attempts).
+
+### Auth setup (if needed)
+
+If any page requires authentication, run manually before Step 2:
 
 ```bash
-npx playwright test
-npx playwright test --ui   # interactive mode
+sungen makeauth admin --url <baseURL>
+# Opens browser → login manually → saves specs/.auth/admin.json
 ```
 
-### 6. Fix failures (AI Verify loop)
-
-When tests fail, use AI to read the error → fix `selectors.yaml` → recompile → re-run.
+### Manual CLI commands
 
-| 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` |
+```bash
+sungen add --screen <name> --path <path>     # Scaffold screen
+sungen add --screen <name> --feature <name>  # Add feature to screen
+sungen generate --screen <name>              # Compile to .spec.ts
+sungen generate --all                        # Compile all screens
+npx playwright test                          # Run all tests
+npx playwright test --ui                     # Interactive mode
+```
 
 ---
 
@@ -192,6 +197,5 @@ 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)

package/dist/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
-```

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
-```