@sun-asterisk/sungen 3.2.18 → 3.2.20

package/src/harness/trace.ts

@@ -13,7 +13,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { reportSlug } from './unit-paths';
+import { featureFilesFor, reportSlug } from './unit-paths';
 import { segmentRuns, latestRunEvents, LedgerEvent } from './ledger';
 import { readTextFile } from './read-text';
 
@@ -96,7 +96,7 @@ export function buildTrace(screenDir: string, screenName: string): TraceReport {
   const scRaw = readJson(path.join(process.cwd(), '.sungen', 'reports', `${reportSlug(screenName)}-script-check.json`));
   const drift = scRaw ? scRaw.drift : null;
 
-  const manual = parseManual(path.join(screenDir, 'features', `${screenName}.feature`));
+  const manual = featureFilesFor(screenDir, screenName).flatMap(parseManual);
 
   // Bottlenecks
   const bottlenecks: string[] = [];

package/src/harness/unit-paths.ts

@@ -1,14 +1,51 @@
 /**
  * Unit-path helpers (api-flow fix). A unit id may be a bare name (`orders`, `login`) or a nested
- * api-flow id (`flows/<flow>`). Two derivations the harness/CLI need:
+ * api-flow id (`flows/<flow>`). Three derivations the harness/CLI need:
  *  - featureBasename: the `.feature` filename — the LAST path segment (`flows/x` → `x`), so
  *    `<dir>/features/<basename>.feature` resolves (the bug: the full id looked for
  *    `features/flows/x.feature` → 0 scenarios).
+ *  - featureFilesFor: EVERY `.feature` file of the unit — a unit is a directory, not a file.
  *  - reportSlug: a flat key for `.sungen/reports/<slug>-*.json` + `.sungen/ledger/<slug>.jsonl`
  *    (`flows/x` → `flows-x`), so artifacts never nest under a `flows/` subdir and read/write agree.
- * Bare names (no slash) are unchanged by both → no regression for screens/flows/areas.
+ * Bare names (no slash) are unchanged by all three → no regression for screens/flows/areas.
  */
+import * as fs from 'fs';
 import * as path from 'path';
 
 export const featureBasename = (unit: string): string => path.basename(unit);
 export const reportSlug = (unit: string): string => unit.replace(/[\\/]+/g, '-');
+
+/**
+ * Every `.feature` file belonging to one unit, in a stable order.
+ *
+ * A unit is a DIRECTORY of features, not one file. `sungen add --screen x --feature y`
+ * scaffolds `x-y.feature` beside `x.feature`, and `--path` without `--feature` names the
+ * file after the URL segment — so `<unit>.feature` may be one of several, or absent
+ * entirely. `generate` and `delivery` have always enumerated the directory; the harness
+ * read the single canonical name and scored only that file, silently dropping every
+ * sub-feature from coverage/depth/traceability with no warning.
+ *
+ * Order: the canonical `<unit>.feature` first so report ordering stays put when a
+ * sub-feature is added later, then the rest alphabetically. Falls back to the canonical
+ * path when the directory is missing or empty, so callers keep the "file not found"
+ * behaviour (and error text) they already have.
+ */
+export function featureFilesFor(unitDir: string, unit: string): string[] {
+  const dir = path.join(unitDir, 'features');
+  const canonicalName = `${featureBasename(unit)}.feature`;
+  const canonical = path.join(dir, canonicalName);
+
+  let names: string[];
+  try {
+    names = fs.readdirSync(dir).filter((f) => f.endsWith('.feature'));
+  } catch {
+    return [canonical]; // no features/ dir — let the caller report the missing file
+  }
+  if (names.length === 0) return [canonical];
+
+  names.sort((a, b) => a.localeCompare(b, 'en'));
+  return [
+    ...names.filter((n) => n === canonicalName),
+    ...names.filter((n) => n !== canonicalName),
+  ].map((n) => path.join(dir, n));
+}

package/src/index.ts

@@ -20,6 +20,7 @@ export type { ResolvedAppProfile } from './generators/test-generator/app-profile
 export type { MappedStep } from './generators/test-generator/step-mapper';
 export type { ParsedStep } from './generators/gherkin-parser';
 export { getPathCode, inferPath, resolvePathVariables } from './generators/test-generator/utils/path-inference';
+export { LIST_MEMBER_ROLES } from './generators/test-generator/utils/selector-resolver';
 
 // --- Precondition-annotation override grammar (shared by the @query / @api driver codegen) ---
 export { parseQueryOverrides } from './harness/annotation-overrides';

package/src/orchestrator/screen-manager.ts

@@ -8,6 +8,7 @@ import * as path from 'path';
 import { chromium } from '@playwright/test';
 import { readCapabilities } from '../harness/capability';
 import { testDataHeader, ensureTestDataGuideFiles } from './test-data-guide';
+import { resolveWebBaseUrl } from '../exporters/env-qa';
 
 export interface ScreenOptions {
   name: string;
@@ -304,8 +305,12 @@ export class ScreenManager {
     if (!fs.existsSync(configPath)) return null;
 
     const content = fs.readFileSync(configPath, 'utf-8');
-    const match = content.match(/baseURL:\s*['"]([^'"]+)['"]/);
-    return match ? match[1] : null;
+    // Both config shapes: legacy literal and env-aware resolveBaseUrl('x') wrapper.
+    const match = content.match(/baseURL:\s*(?:resolveBaseUrl\(\s*)?['"]([^'"]+)['"]/);
+    if (!match) return null;
+    // SUNGEN_BASE_URL (shell > .env.qa.<SUNGEN_ENV> > .env.qa) overrides the static
+    // value — screenshots must capture the same host the tests will run against.
+    return resolveWebBaseUrl(this.cwd, match[1]);
   }
 
   private validateScreenName(name: string): void {

package/src/orchestrator/templates/ai-src/commands/dashboard.md

@@ -1,7 +1,7 @@
 ---
 name: dashboard
 description: "Build a single-file HTML dashboard with test cases + pass/fail results, history trends, compare runs, and CSV/XLSX export."
-argument-hint: "[screen-name...] (omit for all)"
+argument-hint: "[screen-name...] [--env <env>] (omit names for all)"
 order: 60
 claude-tools: "Bash, Read, AskUserQuestion"
 copilot-tools: "[read, execute, edit, vscode/askQuestions]"
@@ -16,6 +16,7 @@ You are a **QA Reporting Engineer**. Your job is to invoke the deterministic `su
 Parse **screens** from `$ARGUMENTS`:
 - If empty → CLI will include **all** screens and flows.
 - If provided → pass them through.
+- **`--env <env>`** — optional (accept `--locale` as an alias). Pass through as `sungen dashboard --env <env>`: the dashboard is built for that environment/locale only — it picks the `<name>-test-result.<env>.json` files, and Trends/Compare only see history snapshots of the same env (a dev run never blends into the uat trend line). Omit → the base environment.
 
 ## Steps
 

package/src/orchestrator/templates/ai-src/commands/run-test.md

@@ -61,7 +61,7 @@ Stop here for mobile — do not continue to the web path.
 
 Parse from `$ARGUMENTS`:
 - **name** — screen or flow name. If missing, ask the user.
-- **`--env <locale>`** — optional. Sets `SUNGEN_ENV=<locale>` for the test run so the runtime test-data resolver merges `<name>.<locale>.yaml` over the base, and `playwright.config.ts` writes results to `<name>-test-result.<locale>.json`. Accept `--locale <locale>` as an alias.
+- **`--env <locale>`** — optional. Sets `SUNGEN_ENV=<locale>` for the test run so the runtime test-data resolver merges `<name>.<locale>.yaml` over the base, and `playwright.config.ts` writes results to `<name>-test-result.<locale>.json`. Accept `--locale <locale>` as an alias. The value can also be a plain ENVIRONMENT name (`dev`, `uat`, `stg`): the same overlay applies to test-data AND `.env.qa.<env>` overlays `.env.qa` (secrets, API/DB datasource URLs); when `SUNGEN_BASE_URL` is declared there, the web baseURL switches too — no config edit, no recompile.
 - **`--ios`**, **`--android`**, **`--both`** (mobile only) — optional. Sets `MOBILE_PLATFORM` for the test run. Default: `android` if not specified. Parsed into `MOBILE_PLATFORM=<value>` and used in WebdriverIO test runs.
 
 If `--env` is passed but no value follows, ask the user which locale to use.

package/src/orchestrator/templates/ai-src/skills/sungen-delivery/SKILL.md

@@ -99,6 +99,12 @@ scheme (`SEC-123`, `PER-345`, `MS-HP-001`) is addressed the same way, and the ca
 exist in test-data, so Gate D does not ask for them: the capture step renders as an instruction
 (`Note the X text for later (as "v")`) and later references read `the captured v`.
 
+**Dynamic vars**: `{{$timestamp}}`, `{{$uuid}}`, `{{$random:min:max}}`, `{{$date}}`, `{{$datetime}}`
+are resolved by TestDataLoader at execution time — including when nested inside a test-data value
+(`seed: "Summary intro {{$timestamp}}"`). They have no static value to print, so the report names
+them instead: `<unique timestamp>`, `<unique id>`, `<random 1-100>`, `<today's date>`,
+`<current date-time>`. An unknown `{{$foo}}` is left raw on purpose — it is a typo and Gate D says so.
+
 **Data fidelity**: invisible test data is made visible, never normalized — `''` → `(empty)`,
 whitespace-only → `(5 spaces)`, padded → `" value "` quoted verbatim. A trim/collapse here would
 silently break the whitespace tests it describes.
@@ -172,6 +178,8 @@ The CLI reads the **per-target result file first** (co-located with `.spec.ts`),
 | Test Environment | `playwright.config.ts` baseURL + project name |
 | Note | Error message + trace path (for failed tests) |
 
+**Runtime-secret redaction (all cells, all unit kinds):** a failed test's error message carries the RESOLVED `${QA_*}` credential (runtime substituted it before asserting), and cell content can too. The exporter builds a per-unit denylist — env vars referenced as `${QA_*}` in the unit's test data whose NAME looks sensitive (`QA_ADMIN_PASSWORD` yes; `QA_BASE_URL`, `QA_ADMIN_EMAIL` no) — resolving values from shell/CI env > `.env.qa.<SUNGEN_ENV>` > `.env.qa`, and erases every occurrence (`***`) from Note, dashboard errorMessage, Steps, Expected results and Test Data. Value-based only: fake demo values (`password123`), error-message strings (`Password is required`) and element names (`[Password]`) stay readable. If a sensitive ref can't be resolved while the run has failures, delivery prints a "redaction coverage incomplete" warning — set the variable in the env before exporting. `sungen delivery` also runs the same secret scan as `generate` and warns if test-data holds a literal token-shaped value.
+
 ---
 
 ## XLSX sheets — Overview + Auto / Manual split

package/src/orchestrator/templates/ai-src/skills/sungen-error-mapping/SKILL.md

@@ -95,6 +95,10 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | `SG-W008` | `@manual` scenario incomplete in either direction: (a) HAS Gherkin steps but NO `Then` — a dangling `When` is invalid Gherkin, comments can NOT substitute; (b) documentation-style (NO steps) but its comments lack numbered action lines and/or a labeled oracle line — prose paragraphs / rationale-only comments export EMPTY Steps + Expected cells | Two valid shapes only: complete the Gherkin with a `Then`, or write the FULL procedure in the `# Tester verifies:` block as NUMBERED lines — action steps first (`1. <action>`), then labeled `Observable:`/`Oracle:`/`Expected:` lines (the number is what fills Steps, the label is what fills Expected results) |
 | `SG-W009` | test-data references `${QA_<NAME>}` (a SECRET env ref) but the name is declared in neither `.env.qa` nor `.env.qa.example` — the test throws "environment variable not set" the moment the key is used. (Only the `${QA_*}` shape is checked; any other `${...}` is literal data and never flagged.) | Add `QA_<NAME>=<value>` to `.env.qa` (gitignored) and list the NAME in `.env.qa.example` (the committed checklist). See `qa/TEST-DATA-GUIDE.md` |
 | `SG-W010` | A row step's `[Ref]` looks POSITIONAL (`First…`/`Last…`/`Top…`/`nth`) but has no selectors.yaml entry — the label is display-only, so the step checks existence ANYWHERE in the table; an ordering/sort-stability rule would pass even when the row moved | Declare the row in selectors.yaml (a `type: locator` value RELATIVE to the table, e.g. `first contact row:` → `value: 'tbody tr:first-child'`) — the step then asserts `toContainText` on that exact row. This is a selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
+| `SG-W011` | A storage assertion written as `expect … in local/session storage` — `expect` steps only read `{{response}}` refs, so this compiles to a silent no-op | Rewrite using the supported grammar: `User see [KEY] in local storage exists/…` |
+| `SG-W012` | A mock-install step written AFTER a navigation step in the same block — `page.route()` registered after `goto()` misses every request fired during page load | Move the mock-install step before the navigation, or into `Background` |
+| `SG-W013` | A page assertion (`see [X] page` / `is on [X] page`) whose `[Ref]` has no `type: page` selector entry (or collides with a non-page entry) — the step falls back to the feature's own path (or `/<ref>/`) instead of `X`'s real URL, so the anchored assertion can never pass | Declare a `type: page` entry for `[Ref]` with its real URL; if the key collides with another type, disambiguate with a `--type` suffix (`sungen-selector-keys` § Collision rule) |
+| `SG-W014` | `[X] page with {{v}}` where `{{v}}`'s base test-data value carries no query and no fragment — the step checks the PATH only, asserting less than it reads as | Informational — pass a value like `?q=…` if you meant to assert a query, or drop `with {{v}}` for a bare page |
 
 ### Runtime error → `Test data "<key>" references ${QA_*} but the environment variable is not set`
 

package/src/orchestrator/templates/ai-src/skills/sungen-gherkin-syntax/SKILL.md

@@ -62,7 +62,7 @@ User click [T] button and dismiss [Cancel] alert  # compiler registers the liste
 User click [OK | Cancel] alert                    # two-step form: must come BEFORE the trigger
 User fill [T] alert with {{v}}
 User see [message text] alert
-User press Escape key | Enter on [T] field
+User press Escape key | [Enter] key | Tab key 5 times | Enter on [T] field
 User wait for N seconds | [T] page
 User wait for [T] TYPE is visible | hidden | enabled | disabled     # ANY reference (v3.3)
 User wait for [T] TYPE with {{v}}                                    # until it shows the value
@@ -103,9 +103,43 @@ two content-filtered queries can hit different rows if the table re-renders in b
 # 5. State: User see [T] button is disabled | checkbox is checked | dialog with {{v}} is hidden
 # 6. Attribute (toHaveAttribute): User see [T] image | link with {{v}}
 # 7. Count: User see [T] row with {{count}}
-# 8. Page: User see [T] page
+# 8. Page: User see [T] page | page with {{url}}   ← `with` also asserts the query string
 ```
 
+**Pattern 8 — the page assertion judges pathname AND query together.** Both `see [T] page` and
+`is on [T] page` (Then-side) compile to ONE web-first predicate — `toHaveURL(urlMatches({…}))`,
+which retries like any other assertion — comparing the **exact** pathname (anchored, trailing slash
+normalised) plus the query:
+
+| step | asserts |
+|---|---|
+| `Then User see [Search] page` | pathname `/vi/search` **and no query at all** — `/vi/search?x=1` FAILS |
+| `… page with {{v}}`, `v` = `?q=abc` | pathname + **every declared param must match**; extra params are tolerated (a UTM/tracking param cannot turn the test red); a repeated param (`?tag=a&tag=b`) matches per value, so param ORDER never matters |
+| `… page with {{v}}`, `v` = `?q=abc#tab` | the fragment is asserted too |
+| `… page with {{v}}`, `v` = `/vi/search?q=abc` | only the query part is used — the page selector already owns the path |
+| `… page with {{v}}`, `v` = `/vi/search` (no query) | **path only**, and the compiler warns (`SG-W014`): the step asserts less than it reads as |
+| `… page with {{v}}`, `v` empty or key missing at run time | **throws, naming the key** — an unusable value is never a silent pass |
+
+So pass `with {{v}}` whenever the URL carries state worth proving, and leave it off when the page
+must be reached clean. A dynamic segment in the selector value (`/users/:id/profile`) wildcards to
+`[^/]+` on its own, still anchored — `/users/42/profile/edit` does not match. Params compare
+decoded on both sides, so a deliberately malformed query still asserts what was written.
+
+Two asymmetries worth knowing rather than discovering:
+
+1. **`Given`/`When` navigate, `Then` asserts** — so they read `{{v}}` differently. `Then` uses only
+   its query/fragment; `Given User is on [T] page with {{v}}` also honours a path the value carries
+   (`/vi/other?q=1` navigates to `/vi/other?q=1`, and a value repeating the page's own path no
+   longer doubles it). Anything that is not a path, query, or fragment is appended **verbatim** —
+   nothing is encoded or normalised, so a test can still drive a deliberately malformed query.
+2. **A repeated param matches as a subset per key**, which is the same rule as "extra params are
+   tolerated": every value you declare must be present, and the URL may carry more.
+
+The predicate itself lives in `specs/url-assert.ts` (auto-generated, `DO NOT EDIT`). If `[T]` has no
+`type: page` selector entry — or its key collides with a non-page entry, so `value` is something like
+`button` rather than a URL — the step falls back to another path and cannot match the real URL. The
+compiler warns (`SG-W013`); declare the page (or rename the colliding key) instead of chasing the red.
+
 ### Collection / all-card (P5)
 
 ```
@@ -142,6 +176,49 @@ first contact row:
 ```
 → compiles to `expect(table.locator('tbody tr:first-child')).toContainText(v)` — the exact row must hold the value — and still enters row scope for `[Col] column` checks.
 
+### Browser storage (web)
+
+```
+Then User see [KEY] in local storage exists
+Then User see [KEY] in local storage does not exist
+Then User see [KEY] in local storage is not empty
+Then User see [KEY] in local storage has length {{n}}
+Then User see key matching "PATTERN" in local storage      # regex over key names
+# same five forms with `session storage`
+```
+
+`[KEY]` is a **storage key, not a selector** — never add it to selectors.yaml. It may embed `{{vars}}`: `[{{exclusive_code}}_ACCESS_TOKEN]`. The check runs inside the browser and returns only a boolean, so a failure message never contains the stored value (safe for tokens). There is deliberately no `equals {{expected}}` form. ⚠️ `expect [KEY] in local storage …` is NOT valid (`expect` reads `{{response}}` refs only) — the compiler warns SG-W011.
+
+### Tab order (web only)
+
+```
+Then User see tab order:
+    | Ref |
+    | [Station Dropdown] |
+    | [Departure Date] |
+    | [Search Button] button |
+```
+
+Focuses row 1 (the pinned origin — there is no separate `focus [X]` step) and asserts it actually HOLDS focus (a non-focusable ref fails loudly), then presses Tab per following row and asserts it receives focus. Cell refs ARE selector references (resolved via selectors.yaml; optional element type after the ref). Requires the `| Ref |` header and ≥2 element rows — a missing header or single row is a compile error, never an empty pass. A mismatch reports the expected ref + the actual focused element (shadow-DOM-aware tag/role/name). Limitations: web only (no Appium); declare tab order OUTSIDE `use dialog`/frame scope (cell locators render page-rooted — put `scope: dialog` on the selector ENTRIES if the elements live in a dialog); focus traps / dynamic comboboxes / `tabindex=-1` reordering / WebKit differences may need `@manual` keyboard-only audits — those stay legitimate manuals.
+
+### Network mocking (optional Mock Driver — `sungen capability add mock`)
+
+```gherkin
+@mock
+Scenario: search shows the error state on server failure
+  Given [reservations-check-500] mock is active        # install a NAMED catalog entry
+  When User click [Search] button
+  Then User see [Error Toast] message
+  And User see [reservations-check-500] mock called {{n}} times   # exact count; "called 1 time" also valid
+```
+
+`[name]` is a **catalog reference, not a selector** — entries live in `qa/screens/<name>/mock/mocks.yaml` (`method`, `url` glob or `re:` regex, `status`, optional `headers`/`body`/`delay_ms`; a `"{{var}}"` body reads test-data at runtime). No inline `[GET /path]` forms. Rules:
+- **Fail-on-unmocked (default):** once a scenario has any mock, unmatched fetch/XHR requests FAIL the test (documents/assets still load). Opt out per scenario with `@mock:passthrough`.
+- **Mocks that must intercept page-load requests go in Background, BEFORE the navigation step** — installing after a navigation warns SG-W012 (load-time requests were not intercepted).
+- No `abort` entry (a network error is not a timeout) — simulate timeouts with a large `delay_ms`.
+- mocks.yaml is committed: credentials in bodies must be `${QA_*}` refs, never pasted DevTools responses (the secret scan covers `mock/*.yaml`).
+- Web only. Requires the driver: without it, `@mock` is a hard compile error pointing at `sungen capability add mock`.
+
 ### Database verification (optional Data Driver)
 
 Read-only DB-state checks. **Prefer named queries** — SQL lives in `qa/screens/<screen>/database/queries.yaml` (reviewed once, parameterized). Invoke with the `@query:<name>` annotation; it binds the result rows to `{{name}}`, then assert with `expect`:

package/src/orchestrator/templates/ai-src/skills/sungen-selector-fix/SKILL.md

@@ -55,6 +55,12 @@ When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen
 1. **Confirm with the user**: *"Generate selectors from the live page via Playwright MCP now?"* — offer **Yes, scan live page** / **Skip (use existing selectors.yaml)** / **Cancel**.
 {{/cap}}
 2. **Collect references**: parse the `.feature` file for every `[Reference]` element + its type (e.g. `[Submit] button`, `[Email] field`). Deduplicate.
+
+   ⛔ **Non-selector bracket refs — never hunt the DOM for these, never write a selectors.yaml entry:**
+   - `[KEY] in local storage …` / `[KEY] in session storage …` — a **storage key**, checked via `page.evaluate`, not an element (the key may embed `{{vars}}`, e.g. `[{{code}}_ACCESS_TOKEN]`).
+   - Bracket refs consumed by other non-DOM step families (`@mock` route refs) follow the same rule: if the step's grammar does not target a UI element, the bracket content is NOT a selector.
+   Writing a fabricated entry for these breaks the real step (the pattern parses the bracket itself) and pollutes selectors.yaml.
+   ✅ **Tab-order table cells ARE selector refs** — each `| [Ref] |` row under `Then User see tab order:` resolves through selectors.yaml like any element (verify them once; they are the same refs the scenario's other steps use — don't double-count them as new elements).
 3. **Ensure page selector**: if missing, ask user for URL path and write it first.
 4. **Navigate**:
    - Read `baseURL` from `playwright.config.ts`.
@@ -91,7 +97,7 @@ When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen
    - Loading indicator for `wait for [T] table to refresh` → `feedback.loading.indicator` (skip if the app sets `aria-busy`).
    - **Every qa/app.yaml edit MUST carry provenance** in `detection:`: who/when (`detected_by`) and the observed evidence per key (`evidence:`). A profile without evidence is a guess a human cannot review.
 8. **Merge, don't overwrite**: preserve the page selector and any user-authored entries in `selectors.yaml`. Only add missing keys.
-   - **Type-collision check** (see `sungen-selector-keys` § Collision rule): before writing a base key, check whether it already exists with a *different* `type`. If so, give **both** entries a `--type` suffix instead of clobbering or sharing the base key — a base-key entry of the wrong type gets picked up by any step referencing that label. Watch `page` especially: a `[X] page` step reads `value` as a URL, so if `X` already holds a button (`value: 'button'`) the assertion compiles to `toHaveURL(/button/)`. Write `X--page` (URL from the live page / feature `Path:`) alongside `X--button`.
+   - **Type-collision check** (see `sungen-selector-keys` § Collision rule): before writing a base key, check whether it already exists with a *different* `type`. If so, give **both** entries a `--type` suffix instead of clobbering or sharing the base key — a base-key entry of the wrong type gets picked up by any step referencing that label. Watch `page` especially: a `[X] page` step reads `value` as a URL, so if `X` already holds a button (`value: 'button'`) the compiler won't use the button's value as a URL, but it can't invent the real one either — it falls back to the feature's own path and warns `SG-W013`, asserting a page that isn't `X`'s. Write `X--page` (URL from the live page / feature `Path:`) alongside `X--button`.
 9. **Show summary + confirm**: list the keys that will be added, ask the user to approve, then write the file.
 10. **Compile**: **Screen**: `sungen generate --screen <screen>`. **Flow**: `sungen generate --flow <flow>`. Then proceed to Phase 1.
 

package/src/orchestrator/templates/ai-src/skills/sungen-selector-keys/SKILL.md

@@ -97,12 +97,15 @@ its own `--type` suffix. A key match alone does not carry type: the resolver wal
 picked up by any step referencing that label, regardless of the type the step expects.
 
 The `page` type is the sharpest trap. A page step (`Then User see [X] page`) reads the entry's
-`value` as a **URL**. If key `X` already holds a `role`/button entry, the page step resolves that
-button and emits `toHaveURL(/button/)` — a literal button label treated as a URL path.
+`value` as a **URL**. If key `X` already holds a `role`/button entry, the compiler guards the type
+— it does NOT emit `toHaveURL(/button/)` — but it can't invent the real URL either, so it falls
+back to the feature's own path (or `/<ref>/`) and warns `SG-W013`: a test that reads as asserting
+`X`'s page but never can, since the fallback path is anchored and almost certainly wrong.
 
 ```yaml
 # Gherkin: `When User click [読取結果一覧] button`  AND  `Then User see [読取結果一覧] page`
-# WRONG — one base key, page step inherits the button's value ('button') as a URL:
+# WRONG — one base key: the page step can't use the button's value, falls back to the feature path
+# instead, and the compiler warns SG-W013 rather than asserting the real page:
 読取結果一覧:
   type: 'role'
   value: 'button'
@@ -254,6 +257,12 @@ success toast:
 
 Use this for every toast/alert/spinner content assertion. Do NOT fall back to `type: locator, value: '[role="status"]'` — `name: null` keeps role semantics.
 
+**List-member roles need no opt-out.** For `option`, `listitem` and `cell` the compiler never defaults
+the name at all — those name themselves from their content, and the value being asserted is already
+carried by `.filter({ hasText })`. Omit `name:` and the locator comes out as `getByRole('option')`.
+Declare `name:` only when the DOM really does expose an accessible name worth filtering on; an
+explicit one is always honoured.
+
 ### Types requiring YAML entry (no auto-infer)
 
 These types need explicit `selectors.yaml` entries:

package/src/orchestrator/templates/playwright.config.ts

@@ -1,4 +1,33 @@
 import { defineConfig, devices } from '@playwright/test';
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Web baseURL per environment — one compiled suite runs on dev/uat/stg by
+ * switching SUNGEN_ENV, no config edit and no recompile.
+ *
+ * Precedence (first hit wins):
+ *   1. `SUNGEN_BASE_URL` from the shell/CI env
+ *   2. `SUNGEN_BASE_URL=` in `.env.qa.<SUNGEN_ENV>` (e.g. `.env.qa.uat`)
+ *   3. `SUNGEN_BASE_URL=` in `.env.qa`
+ *   4. the static fallback below (written by `sungen init --base-url`)
+ *
+ * Mirrors how the runtime resolves `${QA_*}` test-data refs and API/DB
+ * datasource URLs, so every layer of a run agrees on the environment.
+ */
+function resolveBaseUrl(fallback: string): string {
+  if (process.env.SUNGEN_BASE_URL) return process.env.SUNGEN_BASE_URL;
+  for (const name of [`.env.qa.${process.env.SUNGEN_ENV || ''}`, '.env.qa']) {
+    if (name.endsWith('.')) continue;
+    const p = path.join(process.cwd(), name);
+    if (!fs.existsSync(p)) continue;
+    for (const line of fs.readFileSync(p, 'utf8').split('\n')) {
+      const m = line.match(/^\s*SUNGEN_BASE_URL\s*=\s*(.*?)\s*$/);
+      if (m) return m[1].replace(/^["']|["']$/g, '');
+    }
+  }
+  return fallback;
+}
 
 /**
  * Resolve the JSON reporter output path.
@@ -61,8 +90,10 @@ export default defineConfig({
   ],
   /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
   use: {
-    /* Base URL to use in actions like `await page.goto('')`. */
-    baseURL: 'https://example.com',
+    /* Base URL to use in actions like `await page.goto('')`. The quoted value is the
+       static fallback (pre-filled by `sungen init --base-url`); SUNGEN_BASE_URL in the
+       shell or .env.qa[.<SUNGEN_ENV>] overrides it per environment. */
+    baseURL: resolveBaseUrl('https://example.com'),
 
     /* Per-action timeout (click, fill, etc.) */
     actionTimeout: 10_000,

package/src/orchestrator/templates/specs-mock.ts

@@ -0,0 +1,179 @@
+/* eslint-disable */
+/**
+ * Sungen Mock Driver — runtime network-mocking helper (auto-generated into specs/mock.ts).
+ *
+ * One module singleton (same import shape as db/api); ALL state lives per-page in a
+ * WeakMap<Page, MockState>, so routes and call counters follow the page's lifetime on
+ * both isolation paths: a fresh page per test destroys them for free, and the @serial
+ * shared page is reset by the compiler-emitted mock.reset(page) at the end of each
+ * @mock scenario (scoped — only routes THIS router installed are unrouted; a blanket
+ * page.unrouteAll() would also kill Background-installed mocks and third-party routes).
+ *
+ * Blocking posture (fail-on-unmocked, the project default): the first install() also
+ * registers a catch-all route. Playwright matches routes last-registered-first, so
+ * registering the catch-all FIRST makes every named mock win over it. The catch-all
+ * only judges fetch/XHR/websocket traffic — documents/scripts/styles/images pass, the
+ * app shell must still load; what is being isolated is API traffic. An unmatched API
+ * request aborts and throws (fails the test) unless the scenario opted out via
+ * @mock:passthrough (compiled to mock.setPassthrough(page)).
+ *
+ * DO NOT EDIT — regenerated by `sungen generate`.
+ */
+import type { Page, Route } from '@playwright/test';
+
+export interface MockConfig {
+  name: string;
+  method: string;               // HTTP verb or '*'
+  url: string;                  // page.route glob, or 're:<pattern>' for a regex
+  status: number;
+  headers?: Record<string, string>;
+  body?: string;                // pre-serialized by the compiler (JSON string)
+  delay_ms?: number;
+}
+
+interface InstalledRoute {
+  pattern: string | RegExp;
+  handler: (route: Route) => Promise<void>;
+}
+
+interface MockState {
+  counts: Map<string, number>;      // per-mock handled-request counters
+  installed: Set<string>;           // names installed in this scenario (callCount guard)
+  routes: InstalledRoute[];         // exactly what WE routed (scoped reset)
+  guardInstalled: boolean;
+  passthrough: boolean;
+  violations: string[];             // unmocked requests the guard aborted (fail-on-unmocked)
+  /** @serial only: routes[0..N) / names installed by Background (beforeAll) persist across
+   *  scenarios — reset() removes only what a scenario added on top. -1 = no snapshot
+   *  (the default per-test path), where reset() drops the whole state. */
+  backgroundRouteCount: number;
+  backgroundNames: Set<string>;
+}
+
+/** Resource types the fail-on-unmocked guard judges; everything else passes through.
+ *  NOTE: page.route() does NOT intercept WebSocket connections (that is
+ *  page.routeWebSocket, a separate API) — the shipped posture is fetch/XHR only. */
+const GUARDED_TYPES = new Set(['fetch', 'xhr']);
+
+class MockRouter {
+  private state = new WeakMap<Page, MockState>();
+
+  private stateFor(page: Page): MockState {
+    let st = this.state.get(page);
+    if (!st) {
+      st = { counts: new Map(), installed: new Set(), routes: [], guardInstalled: false, passthrough: false, violations: [], backgroundRouteCount: -1, backgroundNames: new Set() };
+      this.state.set(page, st);
+    }
+    return st;
+  }
+
+  /** `@mock:passthrough` — unmatched requests reach the real backend for this page/scenario.
+   *  Also forgives violations already recorded (Background installs + goto run BEFORE the
+   *  scenario body can set this flag — boot-time requests of an opted-out scenario must not
+   *  fail its assertNoUnmocked verdict). The compiler additionally arms the flag inside
+   *  beforeEach via test.info().tags, before the Background installs, so boot requests are
+   *  not even aborted on the default path. */
+  setPassthrough(page: Page): void {
+    const st = this.stateFor(page);
+    st.passthrough = true;
+    st.violations.length = 0;
+  }
+
+  /** Install one catalog entry. The first install also arms the fail-on-unmocked guard. */
+  async install(page: Page, cfg: MockConfig): Promise<void> {
+    const st = this.stateFor(page);
+    if (!st.guardInstalled) {
+      st.guardInstalled = true;
+      const guard = async (route: Route) => {
+        const req = route.request();
+        if (!GUARDED_TYPES.has(req.resourceType()) || st.passthrough) return route.fallback();
+        // Record + abort — NEVER throw here: a route handler runs outside any test
+        // stack, so a throw surfaces as an unhandled rejection (a hard process crash
+        // outside @playwright/test, flaky attribution inside it). The compiler emits
+        // `await mock.assertNoUnmocked(page)` at the end of every @mock scenario,
+        // which fails the test deterministically with the FULL violation list.
+        st.violations.push(`${req.method()} ${req.url()}`);
+        await route.abort('failed');
+      };
+      await page.route('**/*', guard); // FIRST → matched last → every named mock wins
+      st.routes.push({ pattern: '**/*', handler: guard });
+    }
+
+    const pattern = cfg.url.startsWith('re:') ? new RegExp(cfg.url.slice(3)) : cfg.url;
+    const handler = async (route: Route) => {
+      if (cfg.method !== '*' && route.request().method() !== cfg.method) return route.fallback();
+      st.counts.set(cfg.name, (st.counts.get(cfg.name) ?? 0) + 1);
+      if (cfg.delay_ms) await new Promise((r) => setTimeout(r, cfg.delay_ms));
+      // A delayed fulfill can race a page close / reset at teardown — that race must
+      // not surface as an unhandled rejection from inside a route handler.
+      try { await route.fulfill({ status: cfg.status, headers: cfg.headers, body: cfg.body }); } catch { /* page closing */ }
+    };
+    await page.route(pattern, handler);
+    st.routes.push({ pattern, handler });
+    st.installed.add(cfg.name);
+    if (!st.counts.has(cfg.name)) st.counts.set(cfg.name, 0);
+  }
+
+  /** Handled-request count for a mock installed in THIS scenario — throws for a name
+   *  that was never installed here (an exact 0 on an uninstalled mock must be a loud
+   *  error, not a passing assertion). */
+  callCount(page: Page, name: string): number {
+    const st = this.state.get(page);
+    if (!st || !st.installed.has(name)) {
+      throw new Error(`mock "${name}" was never installed in this scenario — add \`Given [${name}] mock is active\``);
+    }
+    return st.counts.get(name) ?? 0;
+  }
+
+  /** Fail-on-unmocked verdict — emitted by the compiler as the LAST statement of every
+   *  @mock scenario. Throws with the full list of aborted unmatched requests; a scenario
+   *  whose app swallowed those failed fetches must not stay green for the wrong reason. */
+  async assertNoUnmocked(page: Page): Promise<void> {
+    const st = this.state.get(page);
+    if (!st || st.violations.length === 0) return;
+    const list = st.violations.slice();
+    st.violations.length = 0;
+    throw new Error(
+      `${list.length} unmocked request(s) hit the fail-on-unmocked guard:\n  - ${list.join('\n  - ')}\n` +
+      'Add entries to mock/mocks.yaml, or opt out with @mock:passthrough.');
+  }
+
+  /** @serial only, emitted by the compiler at the END of the Background block (beforeAll):
+   *  everything installed so far — Background mocks and the guard — persists across the
+   *  feature's scenarios; reset() removes only what each scenario added on top. Without
+   *  this, scenario 1's reset would kill the Background mocks and scenarios 2+ would run
+   *  against the REAL backend with no guard — the silent-green class this driver exists
+   *  to prevent. */
+  snapshotBackground(page: Page): void {
+    const st = this.stateFor(page);
+    st.backgroundRouteCount = st.routes.length;
+    st.backgroundNames = new Set(st.installed);
+  }
+
+  /** Scoped teardown for the @serial shared page: unroute exactly what THIS scenario
+   *  installed (Background routes captured by snapshotBackground persist), zero every
+   *  counter, clear flags/violations. Emitted at the end of each @mock scenario on the
+   *  serial path; the default per-test path never needs it (page dies with the test). */
+  async reset(page: Page): Promise<void> {
+    const st = this.state.get(page);
+    if (!st) return;
+    if (st.backgroundRouteCount < 0) {
+      // No Background snapshot → drop everything (the pre-snapshot / default behavior).
+      for (const r of st.routes) {
+        try { await page.unroute(r.pattern, r.handler); } catch { /* page may be closing */ }
+      }
+      this.state.delete(page);
+      return;
+    }
+    for (const r of st.routes.slice(st.backgroundRouteCount)) {
+      try { await page.unroute(r.pattern, r.handler); } catch { /* page may be closing */ }
+    }
+    st.routes.length = st.backgroundRouteCount;
+    st.installed = new Set(st.backgroundNames);
+    st.counts = new Map();
+    st.violations.length = 0;
+    st.passthrough = false;
+  }
+}
+
+export const mock = new MockRouter();