@sun-asterisk/sungen 2.1.1 → 2.2.1

package/src/orchestrator/templates/ai-instructions/copilot-cmd-make-tc.md

@@ -1,59 +1,28 @@
 ---
-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']
+name: sungen-make-tc
+description: 'Create or update test cases for a Sungen screen — generates feature + test-data files (20+ scenarios per viewpoint). Uses sungen-gherkin-syntax and sungen-tc-generation skills.'
+argument-hint: '[screen-name]'
+agent: 'agent'
+tools: ['terminal', 'playwright/*']
 ---
 
+**Input**: Screen name (e.g., `/sungen-make-tc admin-users`).
+
 ## 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.
+You are a **Senior QA Engineer**. You structure test cases by viewpoint categories and translate UI into Gherkin test cases following the `sungen-gherkin-syntax` and `sungen-tc-generation` skills. **Gherkin scenarios and test data only** — selectors are handled during `/sungen-make-test`.
 
 ## Parameters
 
-Parse from user input:
-- **screen** — screen name (e.g., `login`, `dashboard`)
-
-If missing, ask the user.
+- **screen** — ${input:screen:screen name (e.g., login, dashboard)}
 
 ## 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
+1. Verify `qa/screens/${input:screen}/` exists. If not → run `/sungen-add-screen` first.
+2. Check if `.feature` already has scenarios. If yes → summarize existing coverage and ask: **1) Add new sections**, **2) Add viewpoints to existing sections**, or **3) Replace all**. See `sungen-tc-generation` skill for update mode details.
+3. Ask the user: "How should I explore the page? **1) Live page** (via Playwright MCP) or **2) Static designs** (screenshots, Figma)?". If live page, explore via #tool:playwright (see [copilot-instructions.md](../../copilot-instructions.md) for MCP rules). If auth needed, ask user to log in manually.
+4. Identify screen sections → ask user which to focus on (per `sungen-tc-generation` skill). Present sections as a numbered list and let user pick.
+5. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills.
+6. Show summary → next: `/sungen-make-test ${input:screen}`
 
-Show what was generated. Next: `sungen generate --screen <screen>`
+**No selectors.yaml** — selectors are generated during `/sungen-make-test`.

package/src/orchestrator/templates/ai-instructions/copilot-cmd-make-test.md

@@ -1,58 +1,27 @@
 ---
-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']
+name: sungen-make-test
+description: 'Generate selectors, compile, and run Playwright tests — auto-fixes selectors on failure. Uses sungen-selector-fix, sungen-selector-keys, and sungen-error-mapping skills.'
+argument-hint: '[screen-name]'
+agent: 'agent'
+tools: ['terminal', 'playwright/*']
 ---
 
+**Input**: Screen name (e.g., `/sungen-make-test admin-users`).
+
 ## 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.
+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 user input:
-- **screen** — screen name (e.g., `login`, `dashboard`)
-
-If missing, ask the user.
+- **screen** — ${input:screen:screen name (e.g., login, dashboard)}
 
 ## 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.
+1. Verify `qa/screens/${input:screen}/` has `.feature` + `test-data.yaml`. If not → run `/sungen-make-tc` first.
+2. Explore live page via #tool:playwright to generate `selectors.yaml` (per `sungen-selector-fix` skill).
+3. Compile with #tool:terminal: `sungen generate --screen ${input:screen}`
+4. Run with #tool:terminal: `npx playwright test specs/generated/${input: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/src/orchestrator/templates/ai-instructions/copilot-config.md

@@ -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/src/orchestrator/templates/ai-instructions/github-skill-sungen-error-mapping.md

@@ -0,0 +1,56 @@
+---
+name: sungen-error-mapping
+description: 'Playwright and Sungen error to fix mapping. Use this when running Playwright tests or debugging test failures.'
+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 |
+
+## 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.
+
+## Performance Errors → Fix (specs/base.ts)
+
+All generated `.spec.ts` files import from `specs/base.ts`. This shared file handles context caching, navigation skip, and overlay cleanup.
+
+| Symptom | Fix in `specs/base.ts` |
+|---|---|
+| Server returns 429 (rate limited) | Context caching broken — check `contextCache` Map reuses sessions per `storageState` |
+| Tests slow even with `--workers=1` | Navigation skip not working — check `goto` patch compares `currentPath === url` |
+| Previous test's modal blocks next test | Overlay cleanup insufficient — improve Escape/click dismiss logic |
+| All tests fail on first navigation | `page.url()` is `about:blank` — check try/catch in goto patch |
+| Multiple session invalidation errors | Too many contexts created — ensure `contextCache.get(cacheKey)` returns existing context |
+
+**Rules:**
+- `base.ts` changes affect ALL tests — edit carefully
+- Small project-specific tweaks are OK (e.g., custom overlay dismiss, timeout tuning, extra wait logic)
+- Do NOT move individual selector/data fixes into `base.ts` — those belong in `selectors.yaml` / `test-data.yaml`
+- If unsure whether a fix belongs in `base.ts` or selectors, ask the user
+
+## 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/{dist/orchestrator/templates/ai-instructions/copilot-skill-gherkin-syntax.md → src/orchestrator/templates/ai-instructions/github-skill-sungen-gherkin-syntax.md}

@@ -1,7 +1,7 @@
 ---
-description: 'Sungen Gherkin patterns, selector types, and YAML key rules. Referenced by other sungen prompts.'
-mode: 'agent'
-tools: []
+name: sungen-gherkin-syntax
+description: 'Sungen Gherkin patterns, selector types, and YAML key rules. Use this when writing or editing .feature, selectors.yaml, or test-data.yaml files.'
+user-invocable: false
 ---
 
 ## Step Patterns (65 patterns)
@@ -10,7 +10,7 @@ tools: []
 
 ```
 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
 ```
 
@@ -98,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/src/orchestrator/templates/ai-instructions/github-skill-sungen-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. Use this when generating selectors.yaml from a live page or fixing failing selectors.'
+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/src/orchestrator/templates/ai-instructions/{copilot-skill-selector-keys.md → github-skill-sungen-selector-keys.md}

@@ -1,33 +1,31 @@
 ---
-description: 'Rules for generating correct YAML selector keys from Gherkin [Reference] names. Referenced by other sungen prompts when creating or fixing selectors.yaml files.'
-mode: 'agent'
-tools: []
+name: sungen-selector-keys
+description: 'Rules for generating correct YAML selector keys from Gherkin [Reference] names. Use this when creating or fixing selectors.yaml files with YAML key generation.'
+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