@sun-asterisk/sungen 2.4.6 → 2.5.1

package/dist/orchestrator/templates/ai-instructions/copilot-skill-figma-source.md

@@ -0,0 +1,151 @@
+---
+name: sungen-figma-source
+description: 'Figma URL → spec_figma.md envelope + LLM-synthesized narrative from cached raw node JSON. Auto-loaded when --figma flag present or spec_figma.md exists.'
+user-invocable: false
+---
+
+## When This Skill Loads
+
+Auto-load triggers (any one is sufficient):
+
+- Any sungen AI command invoked with `--figma` flag
+- `requirements/spec_figma.md` exists in the screen directory
+- User mentions a Figma URL or says "generate from Figma"
+
+---
+
+## Prerequisites
+
+- [ ] `sungen figma auth check` succeeds — PAT is stored and valid
+- [ ] Figma file URL is available (shared file or frame link)
+- [ ] If auth missing → run `sungen figma auth set` and follow the walkthrough
+
+**Never paste the PAT into any transcript, spec file, or commit.**
+
+---
+
+## Two-Layer Architecture
+
+`spec_figma.md` has two layers separated by the `<!-- SYNTHESIS-BELOW -->` marker:
+
+| Layer | Producer | Overwrite Rule |
+|---|---|---|
+| **Envelope** (above marker) | sungen CLI | Regenerated each `sungen figma` run — deterministic |
+| **Narrative** (below marker) | This skill (LLM) | Replaced on re-synthesis — everything from marker to EOF |
+
+The envelope contains: YAML frontmatter, Frame metadata, Screenshots. The narrative is synthesized by YOU from the cached raw Figma node JSON.
+
+---
+
+## Inputs You Read
+
+The scaffolder persists a raw (unfiltered) Figma node tree to:
+
+```
+.sungen/figma-cache/<fileKey>/<versionId>/<nodeId>-raw.json
+```
+
+Read this file + the envelope frontmatter of `requirements/spec_figma.md` + any PNGs under `requirements/ui/`. You MUST NOT call the Figma REST API directly — the PAT is not available to you.
+
+---
+
+## Synthesis Task
+
+Append 7 narrative sections below `<!-- SYNTHESIS-BELOW -->`. Each section is inferred from the raw node tree (names, types, `characters`, layout bounds, auto-layout direction, componentProperties):
+
+### 1. Purpose
+One paragraph. What screen is this? Primary user goal? Infer from frame name + top-level text + dominant CTA.
+
+### 2. ASCII Layout
+Rough spatial sketch using box characters. Reflect top-bottom / left-right ordering from absoluteBoundingBox. Keep under ~20 lines. Example:
+
+```
+┌──────────────────────────────────────┐
+│ [Logo]                     [Sign In] │
+├──────────────────────────────────────┤
+│  Welcome back                        │
+│  ┌────────────────────────────────┐  │
+│  │ email@example.com              │  │
+│  └────────────────────────────────┘  │
+│  [ Continue ]                        │
+└──────────────────────────────────────┘
+```
+
+### 3. Regions
+Bulleted list of the major layout regions (header, sidebar, main, footer, modal, etc.) with a one-line purpose each. Use auto-layout frames as region hints.
+
+### 4. Actions
+Every interactive element the user can trigger. Derive from nodes whose name/type suggests a button, link, icon-button, menu-item, toggle, etc. Format:
+
+```
+- **<Action name>** — <what it does> (source: <node name>)
+```
+
+### 5. Form Fields
+Every input the user can fill. Include label, type (text/email/password/select/checkbox/radio/textarea/date), required hint if inferable, and placeholder.
+
+```
+| Label | Type | Required | Placeholder |
+|---|---|---|---|
+```
+
+Omit entirely (write `_none_`) if no inputs exist.
+
+### 6. Data Columns
+If the screen shows a table, list, or card grid — enumerate the columns/fields displayed per row. Otherwise write `_none_`.
+
+### 7. Navigation
+Outgoing links, tab bars, breadcrumbs, back buttons — anything that moves the user to another screen. Include both explicit navigation components and implicit CTAs that navigate.
+
+---
+
+## Synthesis Workflow
+
+1. Read `requirements/spec_figma.md` — note `file_key`, `node_id`, `figma_version_id` from frontmatter
+2. Read `.sungen/figma-cache/<file_key>/<figma_version_id>/<safe_node_id>-raw.json` (colons in node_id become underscores)
+3. Traverse the tree. Collect: names, types, `characters`, `componentProperties`, `absoluteBoundingBox`
+4. Produce the 7 sections above
+5. **Locate the insertion point** in `spec_figma.md`:
+   - **If `<!-- SYNTHESIS-BELOW -->` is present** → replace everything from the marker (inclusive) to EOF with: the marker line, a blank line, then the 7 sections.
+   - **If the marker is NOT present** (older `spec_figma.md` pre-envelope-refactor, or hand-edited file) → locate the last non-empty line of the envelope (usually the end of `## Screenshots`), append a blank line, then write the marker, another blank line, then the 7 sections. Do NOT delete any existing envelope content.
+   - **If the file is missing entirely** → advise the user to re-run `sungen add --screen <screen> --figma <url> --refresh` to regenerate the envelope first. Do not fabricate one.
+6. Preserve the envelope (frontmatter + Frame + Screenshots) byte-for-byte. Never touch content above the marker.
+
+---
+
+## Re-synthesis
+
+- If the envelope's `figma_version_id` changed → envelope is fresh; re-run synthesis
+- If only the narrative is stale (user wants a rewrite) → truncate from marker to EOF and regenerate
+- Never edit content ABOVE the marker — that is the scaffolder's territory
+
+---
+
+## Selector Heuristics (for downstream `run-test`)
+
+During `run-test` Phase 0, provisional selectors can be seeded from the raw JSON:
+
+| Figma Signal | Provisional YAML Entry |
+|---|---|
+| Node name ends `Button`, has text | `role: button` + `name: "<text>"` |
+| Node name ends `Input`/`Field` | `placeholder: "<placeholder text>"` |
+| Node name ends `Link`, has text | `role: link` + `name: "<text>"` |
+| componentProperties has `data-testid` | `testid: <value>` |
+| Plain text leaf (outside interactive) | `text: "<content>"` |
+| Node name ends `Icon` | `role: img` + `name: "<accessible name>"` |
+
+Every provisional entry MUST carry:
+
+```
+# @needs-live-verify source=figma node_id=<id>
+```
+
+Provisional selectors feed `selectors.yaml` as candidates. `run-test` Phase 0 verifies them against the live page and overwrites incorrect entries.
+
+---
+
+## Security
+
+- Never include the PAT in `spec_figma.md`, selectors, test data, or any committed file
+- Never log or echo the PAT in terminal output
+- Read only from `.sungen/figma-cache/` and screen directories — never from `.env`

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-figma-source.md

@@ -0,0 +1,151 @@
+---
+name: sungen-figma-source
+description: 'Figma URL → spec_figma.md envelope + LLM-synthesized narrative from cached raw node JSON. Auto-loaded when --figma flag present or spec_figma.md exists.'
+user-invocable: false
+---
+
+## When This Skill Loads
+
+Auto-load triggers (any one is sufficient):
+
+- Any sungen AI command invoked with `--figma` flag
+- `requirements/spec_figma.md` exists in the screen directory
+- User mentions a Figma URL or says "generate from Figma"
+
+---
+
+## Prerequisites
+
+- [ ] `sungen figma auth check` succeeds — PAT is stored and valid
+- [ ] Figma file URL is available (shared file or frame link)
+- [ ] If auth missing → run `sungen figma auth set` and follow the walkthrough
+
+**Never paste the PAT into any transcript, spec file, or commit.**
+
+---
+
+## Two-Layer Architecture
+
+`spec_figma.md` has two layers separated by the `<!-- SYNTHESIS-BELOW -->` marker:
+
+| Layer | Producer | Overwrite Rule |
+|---|---|---|
+| **Envelope** (above marker) | sungen CLI | Regenerated each `sungen figma` run — deterministic |
+| **Narrative** (below marker) | This skill (LLM) | Replaced on re-synthesis — everything from marker to EOF |
+
+The envelope contains: YAML frontmatter, Frame metadata, Screenshots. The narrative is synthesized by YOU from the cached raw Figma node JSON.
+
+---
+
+## Inputs You Read
+
+The scaffolder persists a raw (unfiltered) Figma node tree to:
+
+```
+.sungen/figma-cache/<fileKey>/<versionId>/<nodeId>-raw.json
+```
+
+Read this file + the envelope frontmatter of `requirements/spec_figma.md` + any PNGs under `requirements/ui/`. You MUST NOT call the Figma REST API directly — the PAT is not available to you.
+
+---
+
+## Synthesis Task
+
+Append 7 narrative sections below `<!-- SYNTHESIS-BELOW -->`. Each section is inferred from the raw node tree (names, types, `characters`, layout bounds, auto-layout direction, componentProperties):
+
+### 1. Purpose
+One paragraph. What screen is this? Primary user goal? Infer from frame name + top-level text + dominant CTA.
+
+### 2. ASCII Layout
+Rough spatial sketch using box characters. Reflect top-bottom / left-right ordering from absoluteBoundingBox. Keep under ~20 lines. Example:
+
+```
+┌──────────────────────────────────────┐
+│ [Logo]                     [Sign In] │
+├──────────────────────────────────────┤
+│  Welcome back                        │
+│  ┌────────────────────────────────┐  │
+│  │ email@example.com              │  │
+│  └────────────────────────────────┘  │
+│  [ Continue ]                        │
+└──────────────────────────────────────┘
+```
+
+### 3. Regions
+Bulleted list of the major layout regions (header, sidebar, main, footer, modal, etc.) with a one-line purpose each. Use auto-layout frames as region hints.
+
+### 4. Actions
+Every interactive element the user can trigger. Derive from nodes whose name/type suggests a button, link, icon-button, menu-item, toggle, etc. Format:
+
+```
+- **<Action name>** — <what it does> (source: <node name>)
+```
+
+### 5. Form Fields
+Every input the user can fill. Include label, type (text/email/password/select/checkbox/radio/textarea/date), required hint if inferable, and placeholder.
+
+```
+| Label | Type | Required | Placeholder |
+|---|---|---|---|
+```
+
+Omit entirely (write `_none_`) if no inputs exist.
+
+### 6. Data Columns
+If the screen shows a table, list, or card grid — enumerate the columns/fields displayed per row. Otherwise write `_none_`.
+
+### 7. Navigation
+Outgoing links, tab bars, breadcrumbs, back buttons — anything that moves the user to another screen. Include both explicit navigation components and implicit CTAs that navigate.
+
+---
+
+## Synthesis Workflow
+
+1. Read `requirements/spec_figma.md` — note `file_key`, `node_id`, `figma_version_id` from frontmatter
+2. Read `.sungen/figma-cache/<file_key>/<figma_version_id>/<safe_node_id>-raw.json` (colons in node_id become underscores)
+3. Traverse the tree. Collect: names, types, `characters`, `componentProperties`, `absoluteBoundingBox`
+4. Produce the 7 sections above
+5. **Locate the insertion point** in `spec_figma.md`:
+   - **If `<!-- SYNTHESIS-BELOW -->` is present** → replace everything from the marker (inclusive) to EOF with: the marker line, a blank line, then the 7 sections.
+   - **If the marker is NOT present** (older `spec_figma.md` pre-envelope-refactor, or hand-edited file) → locate the last non-empty line of the envelope (usually the end of `## Screenshots`), append a blank line, then write the marker, another blank line, then the 7 sections. Do NOT delete any existing envelope content.
+   - **If the file is missing entirely** → advise the user to re-run `sungen add --screen <screen> --figma <url> --refresh` to regenerate the envelope first. Do not fabricate one.
+6. Preserve the envelope (frontmatter + Frame + Screenshots) byte-for-byte. Never touch content above the marker.
+
+---
+
+## Re-synthesis
+
+- If the envelope's `figma_version_id` changed → envelope is fresh; re-run synthesis
+- If only the narrative is stale (user wants a rewrite) → truncate from marker to EOF and regenerate
+- Never edit content ABOVE the marker — that is the scaffolder's territory
+
+---
+
+## Selector Heuristics (for downstream `run-test`)
+
+During `run-test` Phase 0, provisional selectors can be seeded from the raw JSON:
+
+| Figma Signal | Provisional YAML Entry |
+|---|---|
+| Node name ends `Button`, has text | `role: button` + `name: "<text>"` |
+| Node name ends `Input`/`Field` | `placeholder: "<placeholder text>"` |
+| Node name ends `Link`, has text | `role: link` + `name: "<text>"` |
+| componentProperties has `data-testid` | `testid: <value>` |
+| Plain text leaf (outside interactive) | `text: "<content>"` |
+| Node name ends `Icon` | `role: img` + `name: "<accessible name>"` |
+
+Every provisional entry MUST carry:
+
+```
+# @needs-live-verify source=figma node_id=<id>
+```
+
+Provisional selectors feed `selectors.yaml` as candidates. `run-test` Phase 0 verifies them against the live page and overwrites incorrect entries.
+
+---
+
+## Security
+
+- Never include the PAT in `spec_figma.md`, selectors, test data, or any committed file
+- Never log or echo the PAT in terminal output
+- Read only from `.sungen/figma-cache/` and screen directories — never from `.env`

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

@@ -151,6 +151,14 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | `@no-auth` | Disable inherited auth |
 | `@steps:name` | Define reusable step block (base scenario) |
 | `@extend:name` | Prepend Given→When from @steps block (skip Then) |
+| `@cleanup:overlay` | Auto-cleanup: dismiss dialogs/overlays after each test (base.ts fixture) |
+| `@cleanup:forms` | Auto-cleanup: clear form fields after each test (base.ts fixture) |
+| `@cleanup:scroll` | Auto-cleanup: scroll to top after each test (base.ts fixture) |
+| `@cleanup:storage` | Auto-cleanup: clear sessionStorage after each test (base.ts fixture) |
+| `@screenshot:on-failure` | Auto-capture screenshot when test fails (base.ts fixture) |
+| `@beforeAll` | Hook: runs once before all tests → `test.beforeAll()` |
+| `@afterEach` | Hook: runs after each test → `test.afterEach()` (custom cleanup) |
+| `@afterAll` | Hook: runs once after all tests → `test.afterAll()` |
 
 ### @extend behavior
 
@@ -175,30 +183,28 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | Missing `is` for state | `with {{text}} hidden` | `with {{text}} is hidden` |
 | State as value | `with {{disabled}}` | `is disabled` |
 | Missing target type | `fill [email] with {{v}}` | `fill [email] field with {{v}}` |
-| Using Background | `Background: Given User is on...` | Use `@steps` + `@extend` instead |
+| Background with scope | `Background: ... And User is on [X] dialog` | Use `@steps` + `@extend` for scope-dependent flows |
 | `is on` after When | `When ... And User is on [X] dialog` | `And User see [X] dialog` or separate Given |
 
 ## Background vs @steps/@extend
 
-**Do NOT use `Background:` block.** Use `@steps` + `@extend` instead.
+Both `Background` and `@steps`/`@extend` are valid — they serve different purposes.
 
-**Why:**
-- `Background` runs before EVERY scenario but cannot set dialog/frame scope correctly
-- `Background` with `When` + `And User is on [X] dialog` creates keyword mismatch (`is on` = Given, not When)
-- `@steps` + `@extend` gives explicit control: base steps run Given→When, extending scenario starts with `Given User is on [X] dialog` (correct scope setup)
+| Pattern | Use when | Generates |
+|---|---|---|
+| `Background` | Simple shared setup (navigate to page) | `test.beforeEach()` |
+| `@steps`/`@extend` | Complex reusable flows with scope (dialog, frame) | Inline merged steps in `test()` |
 
-**Wrong:**
+**Use `Background` for simple navigation:**
 ```gherkin
 Background:
-  Given User is on [Kudos] page
-  When User click [Open] button
-  And User is on [Modal] dialog    ← keyword mismatch
+  Given User is on [Dashboard] page
 
-Scenario: VP-UI-001 Title visible
-  Then User see [Title] heading
+Scenario: View stats
+  Then User see [Revenue Chart] section
 ```
 
-**Correct:**
+**Use `@steps`/`@extend` when scope matters (dialog, frame):**
 ```gherkin
 @steps:open_modal
 Scenario: Open modal
@@ -211,3 +217,70 @@ Scenario: VP-UI-001 Title visible
   Given User is on [Modal] dialog
   Then User see [Title] heading
 ```
+
+**Avoid `Background` with scope-dependent steps** — `When` + `And User is on [X] dialog` creates keyword mismatch (`is on` = Given, not When). Use `@steps`/`@extend` instead.
+
+## Hooks & Cleanup
+
+Two layers for test lifecycle management. Prefer `@cleanup:*` tags (Layer 1) — they work with base.ts automatically. Use hook scenarios (Layer 2) only for custom logic.
+
+### Layer 1: `@cleanup:*` tags (automatic via base.ts)
+
+Feature-level tags that activate cleanup fixtures in base.ts. No Gherkin steps needed.
+
+```gherkin
+@auth:admin
+@cleanup:overlay
+@cleanup:forms
+Feature: User Management
+  Path: /users
+
+  Background:
+    Given User is on [User Management] page
+
+  Scenario: Create user shows form
+    When User click [Add User] button
+    Then User see [Create User] dialog
+    # After test: overlay auto-dismissed, forms auto-cleared by base.ts
+
+  Scenario: Search user by name
+    When User fill [Search] field with {{search_name}}
+    Then User see [User Row] row
+    # After test: search field auto-cleared by base.ts
+```
+
+| Tag | What base.ts does after each test |
+|---|---|
+| `@cleanup:overlay` | Press Escape, click body, dismiss fixed overlays |
+| `@cleanup:forms` | Clear all input/textarea fields, reset selects |
+| `@cleanup:scroll` | Scroll to top of page |
+| `@cleanup:storage` | Clear sessionStorage |
+
+### Layer 2: `@afterEach` scenario (custom cleanup)
+
+Only when `@cleanup:*` tags aren't enough — feature-specific logic.
+
+```gherkin
+@auth:admin
+@cleanup:overlay
+Feature: Dashboard
+  Path: /dashboard
+
+  Background:
+    Given User is on [Dashboard] page
+
+  @afterEach
+  Scenario: Reset dashboard filters
+    When User select [Date Filter] dropdown with {{default_period}}
+
+  Scenario: Filter by last week
+    When User select [Date Filter] dropdown with {{last_week}}
+    Then User see [Revenue Chart] section
+```
+
+### Layer 3: `@beforeAll` / `@afterAll` (optional)
+
+For one-time setup/teardown. Low priority — most e2e tests don't need these.
+
+**Rendering order in `.spec.ts`:**
+`test.describe` → `test.use(storageState)` → `test.use(autoCleanup)` → `test.beforeAll` → `test.beforeEach` → `test.afterEach` → `test.afterAll` → `test()` blocks

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

@@ -52,6 +52,67 @@ If existing selectors already cover the feature file, **skip Phase 0** and go st
 
 ---
 
+## Phase 0 (Provisional): Figma-Only Selector Generation (no live page)
+
+**Trigger**: Phase 0 decision tree (in `run-test` command) determined the live page is not reachable AND `requirements/spec_figma.md` exists.
+
+**Goal**: produce a compilable `selectors.yaml` seeded from Figma node data so that `sungen generate` succeeds and the test suite can run. Every entry is provisional — it must be verified against a real DOM when the page becomes available.
+
+### Inputs
+
+- `requirements/spec_figma.md` — specifically:
+  - `## Components` table (Name, Type, Role, Text, Variants columns)
+  - `## Text Inventory` list (node_id → label text pairs)
+
+### Steps
+
+1. **Parse references**: collect every `[Reference]` element from the `.feature` file (same as live Phase 0 step 2).
+2. **Match to Figma nodes**: for each `[Reference]`, find the best matching entry in `spec_figma.md` by comparing the reference name against component names and text labels (case-insensitive, partial match allowed).
+3. **Apply heuristic priority** (same order as live Phase 0 — use first applicable):
+
+   | Priority | Type | Figma Signal |
+   |---|---|---|
+   | 1 | `testid` | Dev annotation `data-testid=X` in component metadata |
+   | 2 | `role` + name | Component type is Button/Link + has text label |
+   | 3 | `placeholder` | Component type is Input/Field + has placeholder text |
+   | 4 | `label` | Component has associated label text (not placeholder) |
+   | 5 | `locator` (CSS) | No accessible name derivable from Figma data |
+   | 6 | `text` | Plain text node (not inside interactive component) |
+
+   See `sungen-figma-source` skill for the authoritative heuristics table mapping Figma signals to YAML entry types.
+
+4. **Write entries**: add each entry to `selectors.yaml`, prefixed with the required comment:
+   ```yaml
+   # @needs-live-verify source=figma node_id=<figma-node-id>
+   submit-button:
+     type: role
+     value: button
+     name: "Submit"
+   ```
+   - Key naming follows `sungen-selector-keys` conventions (lowercase, Unicode preserved, `--type` / `--N` suffixes).
+   - Copy text character-for-character from `## Text Inventory`. Never infer from the Gherkin label.
+   - Merge, don't overwrite — preserve the page selector and any user-authored entries.
+
+5. **Compile**: `sungen generate --screen <screen>` — must succeed before Phase 1.
+
+### Auto-fix on live page (subsequent run-test invocations)
+
+When `run-test` is called again and the live page is now reachable:
+- Phase 0 takes ONE `browser_snapshot`.
+- For each entry tagged `# @needs-live-verify` in `selectors.yaml`:
+  - Compare the provisional selector against the actual DOM element found in the snapshot.
+  - If match → remove the comment line (entry promoted to verified).
+  - If mismatch → replace the YAML value with the snapshot-derived selector, then remove the comment (entry corrected and verified).
+- Entries with no corresponding DOM element → log as unresolved, leave comment in place for manual inspection.
+
+### Pitfalls
+
+- Inferring selector names from Gherkin labels instead of Figma `## Text Inventory` → mismatch on live verification.
+- Omitting `# @needs-live-verify` comment → reviewer has no way to count unverified selectors.
+- Overwriting user-authored selectors during merge → always check for existing keys before adding.
+
+---
+
 ## Phase 0.5: Auth Persistence (MCP alternative to `sungen makeauth`)
 
 Capture an authenticated session from the MCP browser into `specs/.auth/<role>.json` — the same path `sungen makeauth` writes to, which compiled tests already reference via `test.use({ storageState })` based on `@auth:<role>` tags. No `playwright.config.ts` edits needed. Run once per auth lifetime, not on every selector fix.