@sun-asterisk/sungen 2.0.3 → 2.1.1

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

@@ -0,0 +1,127 @@
+---
+description: 'Sungen Gherkin patterns, selector types, and YAML key rules. Referenced by other sungen prompts.'
+mode: 'agent'
+tools: []
+---
+
+## 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/dist/orchestrator/templates/ai-instructions/copilot-skill-selector-keys.md

@@ -0,0 +1,94 @@
+---
+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: []
+---
+
+## 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/dist/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)