@sun-asterisk/sungen 2.1.0 → 2.2.0

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

@@ -1,59 +1,24 @@
 ---
 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'
+description: 'Generate selectors, compile, and run Playwright tests — auto-fixes selectors on failure'
 argument-hint: [screen-name]
-allowed-tools: Read, Grep, Bash, Glob, Edit
+allowed-tools: Read, Grep, Bash, Glob, Edit, AskUserQuestion
 ---
 
 ## 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.
+You are a **Senior Developer** specialized in Playwright test debugging. You generate selectors from live pages, diagnose test failures, and fix selectors/test-data using the `sungen-selector-fix`, `sungen-selector-keys`, and `sungen-error-mapping` skills.
 
 ## Parameters
 
-Parse from `$ARGUMENTS`:
-- **screen** — screen name (e.g., `login`, `dashboard`)
-
-If missing, ask the user.
+Parse **screen** from `$ARGUMENTS`. 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.
+1. Verify `qa/screens/<screen>/` has `.feature` + `test-data.yaml`. If not → `/sungen:make-tc` first.
+2. Generate `selectors.yaml` from live page using `sungen-selector-fix` and `sungen-selector-keys` skills.
+3. Compile: `sungen generate --screen <screen>`
+4. Run: `npx playwright test specs/screens/<screen>/<screen>.spec.ts`
+5. If fail → fix selectors/test-data per `sungen-selector-fix` + `sungen-error-mapping` skills, retry (max 5).
+6. After 5 fails → ask user about direct `.spec.ts` fix.
+7. Show: pass/fail, attempt count, files changed.

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

@@ -12,7 +12,7 @@ Given a login page, here are the 3 files you generate:
 
 **qa/screens/login/features/login.feature**
 ```gherkin
-@auth:admin
+@no-auth
 Feature: Login Screen
 
   Scenario: Successful login
@@ -73,12 +73,14 @@ When exploring a page to generate test files:
 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
+1. `browser_navigate` to `baseURL`
+2. If redirected to login, ask the user to log in manually:
+   > "This page requires login. Please log in using the browser. Confirm when you're done."
+3. Once confirmed, `browser_navigate` to the target page and take `browser_snapshot`
+
+**Never use `sungen makeauth`.** Always let the user log in manually via the MCP browser.
+**NEVER use `browser_evaluate` to inject cookies or localStorage.** It causes size limit issues and server 500 errors.
+**Minimize navigations** — take one snapshot per page, do not navigate repeatedly.
 
 ## Commands
 
@@ -86,5 +88,4 @@ To browse authenticated pages via MCP:
 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/dist/orchestrator/templates/ai-instructions/claude-skill-error-mapping.md

@@ -17,6 +17,17 @@ user-invocable: false
 | not a select | set `variant: 'custom'` |
 | Frame not found | fix `frame` value |
 
+## Auth Errors → Fix
+
+| Symptom | Fix |
+|---|---|
+| Tests redirect to login page | `specs/.auth/<role>.json` missing or expired. Tell user: `sungen makeauth <role> --url <baseURL>` |
+| `storageState` file not found | Run `sungen makeauth <role> --url <baseURL>` to create auth state |
+| Most tests timeout on first step | Auth expired — re-run `sungen makeauth <role> --url <baseURL>` |
+| Page shows home/login instead of target | SPA routing + expired auth. Re-run `sungen makeauth`, add `wait for` step after navigation |
+
+**Never run `sungen makeauth` yourself.** Always tell the user to run it manually.
+
 ## Sungen Errors → Fix
 
 | Error | Fix |

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

@@ -4,13 +4,13 @@ description: 'Sungen Gherkin patterns, selector types, and YAML key rules. Auto-
 user-invocable: false
 ---
 
-## Step Patterns (58 patterns)
+## 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 on [T] page with {{v}}                   # navigate with data (e.g., detail page with ID)
 User is logged in | is not logged in              # auth state
 ```
 
@@ -22,6 +22,7 @@ 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
 ```
 
@@ -32,6 +33,9 @@ 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
@@ -86,7 +90,7 @@ User click [Act] in [Table] table row with {{f}}             # action in row
 
 ### States
 
-`hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty`
+`hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty` `loading` `selected` `sorted ascending` `sorted descending`
 
 ### Element Types
 
@@ -94,7 +98,7 @@ User click [Act] in [Table] table row with {{f}}             # action in row
 
 ## YAML Keys
 
-`[Reference]` → **lowercase, spaces→dots**: `[Search Content]` → `search.content:`
+`[Reference]` → **lowercase, keep Unicode**: `[Search Content]` → `search content:`, `[Thời gian]` → `thời gian:`
 
 ## Selectors (priority order)
 

package/dist/orchestrator/templates/ai-instructions/claude-skill-selector-fix.md

@@ -0,0 +1,206 @@
+---
+name: sungen-selector-fix
+description: 'Selector generation and fixing strategy for make-test — explores live page, generates selectors.yaml, auto-fixes on test failure. Auto-loaded by make-test command.'
+user-invocable: false
+---
+
+## Selector Generation & Fix Strategy
+
+### When to Generate Selectors
+
+Selectors are generated during `/sungen:make-test`, NOT during `/sungen:make-tc`. This ensures selectors are always validated against the live page.
+
+---
+
+### Step 1: Authenticate
+
+1. Read `baseURL` from `playwright.config.ts`
+2. `browser_navigate` to `baseURL`
+3. If redirected to login, ask the user to log in manually:
+   > "This page requires login. Please log in using the browser. Confirm when you're done."
+4. Once confirmed, `browser_navigate` to the target page and take `browser_snapshot`
+
+**Never use `sungen makeauth`.** Always let the user log in manually via the MCP browser.
+**Never use `browser_evaluate` to inject cookies or localStorage.** Use `browser_evaluate` only to read DOM info (e.g. detect `data-testid` attributes, check element properties).
+
+---
+
+### Step 2: Build an Element Catalog from the Snapshot
+
+**Never guess or infer selector names from Gherkin labels. Always copy exact values from the snapshot.**
+
+After taking the snapshot, mentally catalog ALL accessible elements:
+
+- **Buttons**: list each `button "..."` with its exact accessible name
+- **Links**: list each `link "..."` with its exact accessible name
+- **Headings**: list each `heading "..."` with level and exact name
+- **Inputs**: list each `textbox`, `searchbox`, `combobox` — note if it has an accessible name or not
+- **Regions/landmarks**: `region "..."`, `navigation "..."`, `dialog "..."`
+- **Images**: `img "..."` with accessible name (alt text)
+
+Then check for `data-testid` attributes (more stable than accessible names):
+```js
+// browser_evaluate — read-only, safe:
+Array.from(document.querySelectorAll('[data-testid]'))
+  .map(e => ({ testid: e.dataset.testid, tag: e.tagName, text: e.textContent.trim().slice(0, 60) }))
+```
+
+---
+
+### Step 3: Map Gherkin Labels → Selectors
+
+For each `[Reference]` in the `.feature` file, find the best match in the element catalog.
+
+#### Selector priority (use first applicable)
+
+| Priority | type | When to use |
+|---|---|---|
+| 1 | `testid` | `data-testid` attribute exists |
+| 2 | `role` + exact name | Interactive elements (button, link, heading) |
+| 3 | `placeholder` | Input with visible placeholder text |
+| 4 | `label` | Form field with `<label>` association |
+| 5 | `locator` (CSS / aria attr) | No accessible name (e.g. bare searchbox, icon button) |
+| 6 | `text` | Static text only — avoid for dynamic/data-driven content |
+
+#### The exact name rule
+
+Copy the accessible name **character-for-character** from the snapshot. Do not transform, translate, or infer from the Gherkin label.
+
+```yaml
+# BAD — name inferred from Gherkin label, not from snapshot
+notification bell:
+  type: 'role'
+  value: 'button'
+  name: 'Notification Bell'
+
+# GOOD — exact name from snapshot: button "Notifications"
+notification bell:
+  type: 'role'
+  value: 'button'
+  name: 'Notifications'
+```
+
+#### When there is no accessible name
+
+Use a `locator` with a CSS attribute selector or ARIA role:
+
+```yaml
+search field:
+  type: 'locator'
+  value: '[role="searchbox"]'
+
+icon button:
+  type: 'locator'
+  value: '[aria-label="Close"]'
+```
+
+---
+
+### Step 4: Handle Dynamic Content
+
+For elements whose text changes between test runs (list items, card data, user-generated content, timestamps):
+
+**Never use `type: text` with a specific value** — it breaks when data changes.
+
+```yaml
+# BAD — specific text breaks when data changes
+card title:
+  type: 'text'
+  value: 'Some specific title'
+
+# GOOD — structural: first heading inside a card container
+card title:
+  type: 'role'
+  value: 'heading'
+  nth: 1    # skip page-level headings, get first card heading
+
+# BEST — if the app has data-testid
+card title:
+  type: 'testid'
+  value: 'card-title'
+```
+
+To determine the correct `nth` offset, count how many matching elements appear before the target in the snapshot (e.g. how many headings come before the first card heading).
+
+---
+
+### Step 5: Handle SPA / Client-side Routing
+
+Many modern apps (Next.js, Nuxt, SvelteKit, etc.) return the same HTML shell for all URLs and route client-side. `domcontentloaded` fires on the shell before the target page renders.
+
+**Symptom**: Tests see a different page than expected (e.g. home page instead of `/dashboard`).
+
+**Fix in the feature file**: Add an explicit assertion after navigation to confirm the correct page has loaded before proceeding:
+
+```gherkin
+Scenario: VP-UI-001 Some test
+  Given User is on [Dashboard] page
+  Then User see [Dashboard Title] heading is visible   ← confirms page loaded
+  When User click [Some Button] button
+  ...
+```
+
+The "page loaded" check should use a **stable, always-visible element** on that specific page — typically the main page heading.
+
+---
+
+### Step 6: Handle Multiple Matches (strict mode)
+
+When an element appears more than once (e.g. desktop + mobile nav, repeated list items), add `nth`:
+
+```yaml
+nav link:
+  type: 'role'
+  value: 'link'
+  name: 'Dashboard'
+  nth: 0    # first occurrence (desktop nav)
+```
+
+Use `nth: 0` for the first match of dynamic/repeated elements.
+
+---
+
+### Auto-Infer (skip YAML entry)
+
+Many elements don't need a YAML entry — sungen auto-infers from the Gherkin label:
+
+| Gherkin | Auto-inferred locator |
+|---|---|
+| `[Submit] button` | `getByRole('button', { name: 'Submit' })` |
+| `[Home] link` | `getByRole('link', { name: 'Home' })` |
+| `[Welcome] heading` | `getByRole('heading', { name: 'Welcome' })` |
+| `[Email] field` | `getByPlaceholder('Email')` |
+| `[Success] text` | `getByText('Success')` |
+
+**Only add a YAML entry when auto-infer won't work:**
+- The accessible name differs from the Gherkin label
+- Needs `nth` to disambiguate
+- Needs `testid` or CSS locator
+- Is dynamic content (needs structural selector)
+- Is a bare input with no label or placeholder
+
+---
+
+### Fix Loop on Test Failure
+
+```
+attempt = 0
+while attempt < 5:
+    compile → run test
+    if pass → done
+    read error-context.md in test-results/ → check exact snapshot state at failure time
+    fix selectors.yaml or test-data.yaml
+    recompile → attempt++
+if still failing → ask user about direct .spec.ts fix
+```
+
+**Always read the error context snapshot first** — it shows the exact page state when the test failed, which is more reliable than re-navigating with MCP.
+
+---
+
+### Key Rules (from sungen-selector-keys)
+
+- `[Reference]` → lowercase, keep Unicode: `[Search Content]` → `search content:`, `[Thời gian]` → `thời gian:`
+- Keys use **spaces** (not dots) as word separators
+- Same label, different element types → add `--type` suffix
+- Same label, nth occurrence → add `--N` suffix

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

@@ -6,28 +6,26 @@ user-invocable: false
 
 ## Key Generation: `[Reference]` → YAML key
 
-Transform: Vietnamese/Japanese → ASCII → lowercase → remove special chars → spaces to dots.
+Copy the text from `[Reference]` as-is, then lowercase. Unicode characters (Vietnamese, Japanese, etc.) are preserved.
 
 ```
 [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
+[Search Content]      → search content
+[User's Profile]      → user's profile
+[Thời gian]           → thời gian
+[Địa điểm]            → địa điểm
+[ログイン]              → ログイン
+[パスワード]            → パスワード
+[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**
+1. Lowercase the text
+2. Trim leading/trailing whitespace
+3. Collapse multiple spaces into one
+4. **Keep all Unicode characters as-is** (Vietnamese diacritics, Japanese, etc.)
+5. **Keys use spaces** (not dots) as word separators
 
 ## Type-Suffixed Keys
 
@@ -35,12 +33,12 @@ When the same label is used for different element types, add `--type` suffix:
 
 ```yaml
 # [Add Campaign] button AND [Add Campaign] text
-add.campaign--button:
+add campaign--button:
   type: 'role'
   value: 'button'
   name: 'Add Campaign'
 
-add.campaign--text:
+add campaign--text:
   type: 'text'
   value: 'Add Campaign'
 ```
@@ -61,11 +59,11 @@ Type aliases (normalized automatically):
 When targeting a specific occurrence by index, add `--N` suffix:
 
 ```yaml
-# [Send Thank You] button 3
-hay.gui.loi.cam.on--3:
+# [Gửi lời cảm ơn] button 3
+gửi lời cảm ơn--3:
   type: 'role'
   value: 'button'
-  name: 'Send Thank You'
+  name: 'Gửi lời cảm ơn'
 ```
 
 ## Lookup Priority