@sun-asterisk/sungen 2.0.3 → 2.1.1

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,127 @@
+---
+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 (65 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 toggle [T] switch                           # toggle switch/checkbox
+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
+User drag [T] to [T2]                            # drag and drop
+User expand [T] row                              # expand (aria-expanded)
+User collapse [T] row                            # collapse (aria-expanded)
+```
+
+### 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` `loading` `selected` `sorted ascending` `sorted descending`
+
+### 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 |

package/src/orchestrator/templates/ai-instructions/claude-skill-selector-keys.md

@@ -0,0 +1,94 @@
+---
+name: sungen-selector-keys
+description: 'Rules for generating correct YAML selector keys from Gherkin [Reference] names. Auto-loaded when creating or fixing selectors.yaml files.'
+user-invocable: false
+---
+
+## Key Generation: `[Reference]` → YAML key
+
+Transform: Vietnamese/Japanese → ASCII → lowercase → remove special chars → spaces to dots.
+
+```
+[Submit]              → submit
+[Search Content]      → search.content
+[User's Profile]      → users.profile
+[Thời gian]           → thoi.gian
+[Địa điểm]            → dia.diem
+[ログイン]              → roguin
+[パスワード]            → pasuwaado
+[Page 2]              → page.2
+[Kudos Detail Modal]  → kudos.detail.modal
+```
+
+**Rules:**
+1. Remove Vietnamese diacritics: `ằắẳẵặ` → `a`, `đ` → `d`, etc.
+2. Convert Japanese Hiragana/Katakana to Romaji
+3. Lowercase everything
+4. `'s` → `s` (apostrophe-s becomes just s)
+5. Remove all special chars except spaces
+6. Trim, then spaces → dots
+7. **NEVER use spaces, underscores, or uppercase in YAML keys**
+
+## Type-Suffixed Keys
+
+When the same label is used for different element types, add `--type` suffix:
+
+```yaml
+# [Add Campaign] button AND [Add Campaign] text
+add.campaign--button:
+  type: 'role'
+  value: 'button'
+  name: 'Add Campaign'
+
+add.campaign--text:
+  type: 'text'
+  value: 'Add Campaign'
+```
+
+Type aliases (normalized automatically):
+| Gherkin type | Normalized suffix |
+|---|---|
+| title, label, caption, message | `text` |
+| heading, header | `heading` |
+| logo, image, icon | `img` |
+| btn | `button` |
+| input, textbox, textarea, editor | `field` |
+| column | `columnheader` |
+| list-item | `listitem` |
+
+## Nth-Suffixed Keys
+
+When targeting a specific occurrence by index, add `--N` suffix:
+
+```yaml
+# [Send Thank You] button 3
+hay.gui.loi.cam.on--3:
+  type: 'role'
+  value: 'button'
+  name: 'Send Thank You'
+```
+
+## Lookup Priority
+
+Resolver searches in this order:
+1. `key--N` (nth-suffixed)
+2. `key--type` (type-suffixed, normalized)
+3. `key` (base key)
+4. Auto-infer from element type if no YAML entry
+5. Any `key--*` (first suffixed match)
+
+## Auto-Infer (no YAML entry needed)
+
+If no YAML key exists, the resolver infers from the Gherkin element type:
+
+| Gherkin | Inferred locator |
+|---|---|
+| `[X] button` | `getByRole('button', { name: 'X' })` |
+| `[X] link` | `getByRole('link', { name: 'X' })` |
+| `[X] heading` | `getByRole('heading', { name: 'X' })` |
+| `[X] checkbox` | `getByRole('checkbox', { name: 'X' })` |
+| `[X] field` | `getByPlaceholder('X')` |
+| `[X] text` | `getByText('X')` |
+| `[X] logo/image/icon` | `getByRole('img', { name: 'X' })` |
+
+**Only add a YAML entry when** the auto-inferred locator won't work (wrong name, need testid, need nth, etc.).

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

@@ -0,0 +1,41 @@
+---
+description: 'Add a new Sungen screen — scaffolds directories and delegates to make-tc for test case creation'
+mode: 'agent'
+tools: ['terminal']
+---
+
+You are adding a new Sungen screen for test generation.
+
+## Parameters
+
+Parse from user input:
+- **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 in terminal:
+```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 the `sungen-make-tc` prompt 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/copilot-cmd-make-tc.md

@@ -0,0 +1,59 @@
+---
+description: 'Create test cases for a Sungen screen — gathers viewpoints, explores live page or static designs, generates feature/selectors/test-data files'
+mode: 'agent'
+tools: ['terminal', 'playwright']
+---
+
+## 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` prompt rules.
+
+## Parameters
+
+Parse from user input:
+- **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 <screen> --path <path>` first.
+
+### 2. Determine source mode
+
+Ask: "Do you have a **live page** or **static designs** (screenshots, Figma, images)?"
+
+**Live page →** explore via browser (see `.github/copilot-instructions.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` prompt 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/copilot-cmd-make-test.md

@@ -0,0 +1,58 @@
+---
+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'
+mode: 'agent'
+tools: ['terminal']
+---
+
+## 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` prompts for error diagnosis and key fixes.
+
+## Parameters
+
+Parse from user input:
+- **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` prompts first.
+
+### 2. Compile
+
+```bash
+sungen generate --screen <screen>
+```
+
+If fails, fix source files per `sungen-error-mapping` prompt 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` prompt
+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/copilot-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, reference the `sungen-gherkin-syntax` prompt.
+For error diagnosis, reference the `sungen-error-mapping` prompt.
+
+## 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/copilot-skill-error-mapping.md

@@ -0,0 +1,27 @@
+---
+description: 'Playwright and Sungen error to fix mapping. Referenced by other sungen prompts when running or debugging tests.'
+mode: 'agent'
+tools: []
+---
+
+## 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 |