@sun-asterisk/sungen 3.2.21 → 3.2.22-beta.2

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

@@ -479,7 +479,11 @@ Add cleanup tags per the `sungen-gherkin-syntax` Cleanup table. Key rules:
 
 **Files:** `qa/screens/<screen>/features/<screen>.feature` + `qa/screens/<screen>/test-data/<screen>.yaml`
 
-Use step patterns and element types from `sungen-gherkin-syntax`.
+Use step patterns and element types from `sungen-gherkin-syntax`. For a `@platform:mobile/android/ios`
+screen or flow, first check that skill's **Platform Support** section — never author a step marked
+`[web]` there (tables, browser storage, tab order, `@mock`, uploader, `Then User is on [T] page`) for
+a mobile unit, and read the divergence table before relying on `see [T] page` or `hover` to prove
+anything on mobile. Reach for `sungen-mobile-gestures` for the gesture vocabulary instead.
 **Naming**: reuse the **project's `test-viewpoint.md` IDs** when it declares them (e.g. `VP0`, `MS-HP-001`); otherwise `VP-<CATEGORY>-<NNN>`. Scenario name must use the **same element type** as the steps.
 
 **Test data** — grouped by section, loaded at runtime:
@@ -603,24 +607,67 @@ error:
 
 ## Flow Test Generation
 
+> **Terminology**: many QA teams call this level **System Test** (ISTQB: verify the fully
+> integrated system against its specified requirements, designed around business
+> processes/use cases). In sungen a *flow* is that system-test suite run through the real UI;
+> its automation then serves as the regression suite on later runs. The names are
+> interchangeable in conversation; the artifacts stay `qa/flows/<name>/`.
+
+**Representative, not exhaustive (ISTQB system-test design rule).** A flow case takes ONE
+representative input per branch — one valid value for the main flow, one error value that
+triggers the exception branch and proves the journey recovers. The full equivalence/boundary
+matrix belongs to the OWNING SCREEN (as `@cases` there), never re-run inside the flow: if the
+screen already proved "the field rejects negatives", the flow only proves "the journey survives
+one rejected input". `sungen audit` reports `FLOW-EXHAUSTIVE-INPUTS` when ≥3 same-shape flow
+scenarios differ only in data. **Mocked dependencies**: a flow scenario using `@mock` is
+delivered as *Pass (Mocked)* — verified handling logic, not the real dependency; the delivery's
+External Dependency Tracking table lists it until re-verified real.
+
+**Release selection & external legs**: when the contract declares `golden: true`, tag the
+happy-path scenario(s) that prove the outcome with **`@golden`** — that is the set
+`sungen inspect` (Final Inspection, Go/No-Go) runs before a release; `GOLDEN-MISSING` fires
+until it exists, and a @golden scenario that passes only against mocks BLOCKS the release.
+When the contract declares `external:` legs (another team/vendor's system), scenarios touching
+those namespaces are the **System INTEGRATION** group — keep their oracles about the boundary
+(contract/format/handoff), and expect `SIT-MOCK-ONLY` until they are re-verified real.
+
+
 > **Auto-detect**: if path is `qa/flows/<name>/` → use this section. Skip Steps 1–4 above.
 
+**Read `requirements/flow-contract.yaml` FIRST — it is the flow's boundary and the yardstick
+`sungen audit` scores the flow against** (`flowCoverage` axis = journey phases HP/ER/EH automated;
+`FLOW-OUTCOME-UNPROVEN`; `FLOW-SCOPE-CREEP`). No contract yet → author it with the user via the
+boundary checklist in `add-flow` (one business goal · clear trigger · ONE observable outcome
+valuable to the actor · name = "Verb + outcome"), THEN generate. **A filled contract is an INPUT —
+never rewrite it to match your output** (same rule as `test-viewpoint.md`).
+
 | Aspect | Screen | Flow |
 |---|---|---|
-| Section focus | UI patterns per section | Journey phases across screens |
+| Section focus | UI patterns per section | Journey phases toward ONE declared outcome |
 | Selector format | `[Element]` | `[Screen:Element]` (namespaced) |
 | Test data keys | `{{variable}}` | `{{phase.variable}}` |
 | Feature tag | `@auto` / `@smoke` etc. | `@flow` (required) |
-| Viewpoints | VP-UI/VAL/LOGIC/SEC per section | VP-LOGIC (transitions), VP-SEC (auth persistence), VP-VAL (cross-screen data) |
+| Scenario ids | `VP-<CATEGORY>-NNN` | `FL-<PHASE>-NNN` — phases: `HP` (happy path), `ER` (error recovery), `EH` (guards), `UI` (journey UI states, optional) |
 
-**Scenarios to generate:**
+**Scenarios to generate — every phase demanded by the contract, automated:**
 
-| Category | What to test |
-|---|---|
-| Happy path | Complete flow end-to-end with valid data |
-| Auth persistence | Auth state maintained across screen transitions |
-| Error recovery | Invalid input mid-flow → fix → continue |
-| Cross-screen data | Data entered on screen A visible on screen B |
+| Phase | What to test | Scoring |
+|---|---|---|
+| `FL-HP` happy path | The complete journey ending in the contract's `outcome.assertion` — an AUTOMATED **data** assertion on `outcome.screen` (an order number, a summed total — not just "page visible"). This scenario is WHY the flow exists: it is the regression proof after a lib/framework upgrade. | uncovered → `flowCoverage` drops + `FLOW-OUTCOME-UNPROVEN` |
+| `FL-ER` error recovery | Invalid input mid-flow → error shown → fix → the journey still completes. Validation must not trap the journey. | uncovered → `flowCoverage` drops |
+| `FL-EH` guards | Direct URL access without the precondition · browser back · refresh · expired context — each ends in a safe observable state. | uncovered → `flowCoverage` drops |
+| Cross-screen handoff | After every screen transition, assert the CARRIED state on the new screen (the added product's name in the cart, the email echoed on the sent screen). | blind tails cap `businessDepth` (`FLOW-HANDOFF-SHALLOW`) |
+| Stateful regression (when `stateful:` declared) | Count/quantity proof · teardown (remove → empty) · multi-source add. | missing dims cap `businessDepth` (`FLOW-DEPTH`) |
+
+**Boundary discipline while generating:** every scenario must serve the contract's goal. A scenario
+that never touches `outcome.screen` and is not a guard (`EH`) or error-recovery (`ER`) belongs in a
+DIFFERENT flow — propose the split instead of writing it here (`FLOW-SCOPE-CREEP` will flag it).
+Auth persistence across transitions is part of `EH` unless the project declares it its own phase.
+
+**Manual in flows**: always `@manual:Mx` with the reason code — bare `@manual` is flagged
+(`MANUAL-CODE-MISSING`) because the capability planner cannot route it. Typical flow deferrals:
+inbox/mail oracle → `M5`, network-request count → `M3`, context expiry control → `M7`. A
+cross-screen scenario inside the flow's own goal is NOT manual — automate it here.
 
 ```gherkin
 @flow @auth:user
@@ -630,19 +677,20 @@ Feature: Award Submission Flow
     Given User is on [Login] page
 
   @high
-  Scenario: User logs in successfully
+  Scenario: FL-HP-001 A signed-in user's nomination is submitted and confirmed
     When User fill [Login:Email] field with {{login.email}}
     And User fill [Login:Password] field with {{login.password}}
     And User click [Login:Submit] button
     Then User see [Dashboard] page
-
-  @high
-  Scenario: User submits nomination
     When User click [Dashboard:Awards] link
-    Then User see [Awards] page
-    When User fill [Awards:Nominee] field with {{submission.nominee}}
+    And User fill [Awards:Nominee] field with {{submission.nominee}}
     And User click [Awards:Submit] button
-    Then User see {{success_message}} message
+    Then User see [Awards:Success Message] text with {{success_message}}
+
+  @high
+  Scenario: FL-EH-001 Direct access to the award form without login redirects to login
+    When User go to [Awards] page
+    Then User see [Login] page
 ```
 
 ```yaml

package/src/orchestrator/templates/qa-context.md

@@ -45,8 +45,21 @@ Example:
 
 ## Testing Strategy
 
+Machine-readable intent — `sungen audit` reads these keys (Intent Profile). Values here are
+live even when the surrounding text changes; an invalid value silently falls back to the default.
+
+focus: functional
+<!-- focus: functional | e-commerce | security | smoke — drives the audit's depth threshold -->
+
+risk_tier: normal
+<!-- risk_tier: high | normal | low -->
+
+To silence driver suggestions in audit findings, add a line: capability_suggestions with value off.
+
 **Focus areas** — what to cover thoroughly:
-<!-- List from: functional, security, ui, accessibility, performance -->
+<!-- Prose for humans; the parseable value is the `focus:` key above.
+     Response-time budgets are NOT a focus value — declare them in qa/perf.yaml
+     (percentile + scenario_ms budgets; reported by `sungen delivery`). -->
 <!-- Example: functional, security -->
 
 **Mandatory coverage:**

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

@@ -7,12 +7,16 @@
  * `{{name.body.<path>}}`. Base URL + auth come from a `kind: api` datasource in datasources.yaml,
  * with `${VAR}` resolved from .env.qa / process.env — never inline.
  *
+ * Runs on Node's global `fetch` (Node 18+) — no `@playwright/test` import, so this driver loads in
+ * mobile (Appium/Mocha) specs, which carry no Playwright dependency. Previously built on
+ * `APIRequestContext`; ported method-by-method (see `ApiClient.call`) to keep behaviour — including
+ * the `@hybrid` storageState cookie reuse — equivalent on web.
+ *
  * Safety: a datasource flagged `env: production` is refused unless SUNGEN_ALLOW_PROD=1.
  * DO NOT EDIT — regenerated by `sungen generate`.
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { request, type APIRequestContext } from '@playwright/test';
 
 interface ApiDataSource {
   kind?: string;
@@ -56,11 +60,53 @@ function substituteRaw(text: string, params: Record<string, any>): string {
 }
 /** Delete any case-insensitive variant of a header (HTTP header names are case-insensitive, but a
  *  plain object keys on exact case — so a datasource `Content-Type` and our `content-type` would
- *  both be sent). Call before setting, or to let Playwright own the header (multipart boundary). */
+ *  both be sent). Call before setting, or to let fetch own the header (multipart boundary). */
 function deleteHeader(headers: Record<string, string>, name: string): void {
   const lower = name.toLowerCase();
   for (const k of Object.keys(headers)) if (k.toLowerCase() === lower) delete headers[k];
 }
+/** True when `headers` already carries a case-insensitive match for `name` — used to respect an
+ *  explicit catalog header instead of overriding it with our own content-type default. */
+function hasHeader(headers: Record<string, string>, name: string): boolean {
+  const lower = name.toLowerCase();
+  return Object.keys(headers).some((k) => k.toLowerCase() === lower);
+}
+
+/**
+ * Build a `Cookie:` header value from a Playwright storageState JSON file (written by
+ * `sungen makeauth` / `context.storageState()` — `{ cookies: [...], origins: [...] }`), scoped to
+ * the cookies that apply to `url` the way a browser would send them (domain + path + not expired).
+ * Powers `@hybrid`: the API call reuses the UI session's cookies without a browser/Playwright
+ * context. Returns undefined when the file has no cookie that matches `url`.
+ */
+function loadStorageStateCookieHeader(storageStatePath: string, url: string): string | undefined {
+  const abs = path.isAbsolute(storageStatePath) ? storageStatePath : path.join(process.cwd(), storageStatePath);
+  if (!fs.existsSync(abs)) {
+    throw new Error(`API Driver: storageState "${storageStatePath}" not found — run \`sungen makeauth\` first.`);
+  }
+  const state = JSON.parse(fs.readFileSync(abs, 'utf-8')) as {
+    cookies?: Array<{ name: string; value: string; domain?: string; path?: string; expires?: number; secure?: boolean }>;
+  };
+  const cookies = state.cookies || [];
+  if (!cookies.length) return undefined;
+  const target = new URL(url);
+  const nowSec = Date.now() / 1000;
+  const targetIsSecure = target.protocol === 'https:';
+  const matches = cookies.filter((c) => {
+    const domain = (c.domain || '').replace(/^\./, '');
+    const domainOk = !domain || target.hostname === domain || target.hostname.endsWith(`.${domain}`);
+    const pathOk = target.pathname.startsWith(c.path || '/');
+    const notExpired = c.expires === undefined || c.expires < 0 || c.expires > nowSec;
+    // A Secure cookie must never leave over plaintext. Playwright's own cookie jar enforces this,
+    // and this function exists to be EQUIVALENT to it — omitting the check would make a mixed
+    // @hybrid setup (https browser session, http API datasource) leak the session cookie in clear,
+    // a downgrade introduced by us rather than by anything the author wrote.
+    const secureOk = !c.secure || targetIsSecure;
+    return domainOk && pathOk && notExpired && secureOk;
+  });
+  if (!matches.length) return undefined;
+  return matches.map((c) => `${c.name}=${c.value}`).join('; ');
+}
 
 /** A multipart file field embedded by the compiler (string = shorthand for { path }). */
 type FileSpec = string | { path: string; mimeType?: string; filename?: string; name?: string };
@@ -173,11 +219,13 @@ class ApiClient {
     if (req.body !== undefined && req.body !== null) {
       body = JSON.parse(JSON.stringify(req.body).replace(/":([A-Za-z_][A-Za-z0-9_]*)"/g, (_m, p) => JSON.stringify(params[p] ?? null)));
     }
-    // Map the wire format to the right Playwright option (#345): json → data (application/json,
-    // default), form → form (application/x-www-form-urlencoded), multipart → multipart (form-data).
-    // A `files` block is a real upload: read each fixture into a { name, mimeType, buffer } part and
-    // send multipart, with any `body` values riding along as text fields.
-    const bodyOpt: Record<string, unknown> = {};
+    // Map the wire format to a fetch request body (#345): json → JSON string (application/json,
+    // default), form → URL-encoded string, multipart → FormData. A `files` block is a real upload:
+    // read each fixture into a Blob part and send multipart, with any `body` values riding along
+    // as text fields. (Typed as `any`, not fetch's DOM-only `BodyInit`: this package's tsconfig has
+    // no "dom" lib, so that alias isn't in scope even though the global runtime values are.)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- see comment above
+    let fetchBody: any;
     if (req.bodyFile) {
       // Raw-binary body: the whole request body is the fixture's bytes. Content-Type comes from the
       // spec's mimeType (default application/octet-stream) — this is what octet-stream upload
@@ -186,40 +234,70 @@ class ApiClient {
       const fpath = substituteRaw(String(spec.path), params);
       if (fpath) {
         const resolved = resolveFixture(fpath, label);
-        bodyOpt.data = fs.readFileSync(resolved);
+        fetchBody = fs.readFileSync(resolved);
         // Own the Content-Type: drop any datasource default (case-insensitive) so we don't send both.
         deleteHeader(headers, 'content-type');
         headers['content-type'] = spec.mimeType ?? 'application/octet-stream';
       }
     } else if (req.files && Object.keys(req.files).length) {
-      // Playwright generates the multipart/form-data Content-Type (with boundary); drop any datasource
-      // default Content-Type so it doesn't conflict with / duplicate the generated one.
+      // fetch derives the multipart/form-data Content-Type (with boundary) from the FormData body;
+      // drop any datasource default Content-Type so it doesn't conflict with / duplicate it.
       deleteHeader(headers, 'content-type');
-      bodyOpt.multipart = buildMultipart(req.files, body, params, label);
+      fetchBody = buildMultipart(req.files, body, params, label);
     } else if (body !== undefined) {
       const enc = req.encoding ?? 'json';
-      if (enc === 'form') bodyOpt.form = body;
-      else if (enc === 'multipart') bodyOpt.multipart = body;
-      else bodyOpt.data = body;
+      if (enc === 'form') {
+        if (!hasHeader(headers, 'content-type')) headers['content-type'] = 'application/x-www-form-urlencoded';
+        fetchBody = new URLSearchParams(body as Record<string, string>).toString();
+      } else if (enc === 'multipart') {
+        deleteHeader(headers, 'content-type');
+        fetchBody = buildMultipart({}, body, params, label); // no file fields — text fields only
+      } else {
+        if (!hasHeader(headers, 'content-type')) headers['content-type'] = 'application/json';
+        fetchBody = JSON.stringify(body);
+      }
+    }
+
+    // GET/HEAD requests may not carry a body under fetch (undici throws). Refuse LOUDLY rather than
+    // send a request quietly shorter than the catalog says it is — a dropped body reads as a server
+    // bug, not an authoring one. `validateApiEntry` catches this at generate time; this is the
+    // backstop for a catalog that reached the runtime some other way.
+    if (fetchBody !== undefined && /^(GET|HEAD)$/i.test(req.method)) {
+      throw new Error(`API Driver: ${label} — a ${req.method.toUpperCase()} request cannot carry a body. Remove body:/files:/bodyFile: from the catalog entry, or change its method to POST/PUT/PATCH.`);
+    }
+
+    // Full URL (not a baseURL-relative path) so a base path component like /api/v3 is preserved.
+    const fullUrl = joinApiUrl(base, urlPath);
+
+    // @hybrid: `storageState` is the @auth role's saved session (Playwright's `context.storageState()`
+    // JSON) — reuse its cookies (scoped to `fullUrl`'s domain/path) so the request shares the
+    // browser's authenticated session without a browser/Playwright context.
+    if (opts.storageState) {
+      const cookieHeader = loadStorageStateCookieHeader(opts.storageState, fullUrl);
+      if (cookieHeader) {
+        const existingKey = Object.keys(headers).find((k) => k.toLowerCase() === 'cookie');
+        headers[existingKey || 'cookie'] = existingKey ? `${headers[existingKey]}; ${cookieHeader}` : cookieHeader;
+      }
     }
 
-    // Playwright APIRequestContext: same runner/report/retries as UI tests. @hybrid passes
-    // `storageState` (the @auth role's saved session) so the request shares the browser's
-    // authenticated cookies. Disposed per call so no request context lingers and hangs the process.
-    const ctx: APIRequestContext = await request.newContext({
-      extraHTTPHeaders: headers,
-      timeout: req.timeout ?? conf.timeout_ms ?? 15000, // per-endpoint override → datasource → 15s
-      ...(opts.storageState ? { storageState: opts.storageState } : {}),
-    });
+    // Timeout: fetch has no built-in per-request timeout, so abort it manually — mirrors the prior
+    // per-endpoint-override → datasource → 15s default precedence.
+    const timeoutMs = req.timeout ?? conf.timeout_ms ?? 15000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
-      // Full URL (not a baseURL-relative path) so a base path component like /api/v3 is preserved.
-      const res = await ctx.fetch(joinApiUrl(base, urlPath), { method: req.method, ...bodyOpt });
+      const res = await fetch(fullUrl, {
+        method: req.method,
+        headers,
+        ...(fetchBody !== undefined ? { body: fetchBody } : {}),
+        signal: controller.signal,
+      });
       const text = await res.text();
       let parsed: any = text;
       try { parsed = text ? JSON.parse(text) : null; } catch { /* non-JSON → keep text */ }
-      return { status: res.status(), ok: res.ok(), body: parsed, headers: res.headers() };
+      return { status: res.status, ok: res.ok, body: parsed, headers: Object.fromEntries(res.headers.entries()) };
     } finally {
-      await ctx.dispose();
+      clearTimeout(timer);
     }
   }
 

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

@@ -9,9 +9,12 @@
  * Engines: PostgreSQL (`pg`), MySQL (`mysql2`), and SQLite (`better-sqlite3`), lazy-loaded on first use.
  * Config: a `datasources.yaml` at the project root (or qa/), with ${VAR} resolved from env.
  *
+ * Assertions are plain thrown Errors — no `@playwright/test` import — so this helper loads in
+ * mobile (Appium/Mocha) specs too, which carry no Playwright dependency (same reason
+ * `specs/api.ts` runs on Node's global `fetch`).
+ *
  * DO NOT EDIT — regenerated by `sungen generate`.
  */
-import { expect } from '@playwright/test';
 import * as fs from 'fs';
 import * as path from 'path';
 
@@ -647,12 +650,13 @@ class DataSource {
   async assertRow(table: string, filter: Record<string, any>, expected?: Record<string, any>, datasource?: string): Promise<void> {
     const { engine } = await this.engine(datasource);
     const rows = await engine.findRows(table, filter, 50);
-    expect(rows.length, `Expected a row in "${table}" where ${desc(filter)} — found ${rows.length}`).toBeGreaterThanOrEqual(1);
+    assert(rows.length >= 1, `Expected a row in "${table}" where ${desc(filter)} — found ${rows.length}`);
     if (expected) {
       const row = rows[0];
       for (const [col, val] of Object.entries(expected)) {
         ident(col);
-        expect(String(row[col]), `Column "${col}" of "${table}" where ${desc(filter)}`).toBe(String(val));
+        assert(String(row[col]) === String(val),
+          `Column "${col}" of "${table}" where ${desc(filter)} — expected ${JSON.stringify(String(val))}, found ${JSON.stringify(String(row[col]))}`);
       }
     }
   }
@@ -661,7 +665,7 @@ class DataSource {
   async assertNoRow(table: string, filter: Record<string, any>, datasource?: string): Promise<void> {
     const { engine } = await this.engine(datasource);
     const rows = await engine.findRows(table, filter, 50);
-    expect(rows.length, `Expected NO row in "${table}" where ${desc(filter)} — found ${rows.length}`).toBe(0);
+    assert(rows.length === 0, `Expected NO row in "${table}" where ${desc(filter)} — found ${rows.length}`);
   }
 
   /** Exactly `count` rows must match `filter`. */
@@ -669,7 +673,7 @@ class DataSource {
     const { engine } = await this.engine(datasource);
     const n = await engine.countRows(table, filter);
     const cols = Object.keys(filter);
-    expect(n, `Expected ${count} row(s) in "${table}"${cols.length ? ' where ' + desc(filter) : ''} — found ${n}`).toBe(Number(count));
+    assert(n === Number(count), `Expected ${count} row(s) in "${table}"${cols.length ? ' where ' + desc(filter) : ''} — found ${n}`);
   }
 
   /**
@@ -694,6 +698,16 @@ class DataSource {
   }
 }
 
+/**
+ * Fail a DB assertion. A thrown Error is exactly what BOTH runners report as a test failure
+ * (Playwright and Mocha/WDIO), so this replaces Playwright's `expect(...)` without importing it —
+ * the coupling that kept `specs/db.ts` out of mobile specs. Messages carry expected AND found,
+ * since there is no matcher to print them.
+ */
+function assert(cond: boolean, message: string): void {
+  if (!cond) throw new Error(`[sungen] ${message}`);
+}
+
 function desc(filter: Record<string, any>): string {
   return Object.entries(filter).map(([k, v]) => `${k}=${JSON.stringify(v)}`).join(', ');
 }