@sun-asterisk/sungen 3.2.4 → 3.2.6

package/src/exporters/result-variants.ts

@@ -0,0 +1,47 @@
+/**
+ * Result-variant resolution — the single seam the CSV (delivery) and JSON (dashboard) exporters
+ * share so they can never drift on @cases handling again (they did: the dashboard mislabelled
+ * every @cases row while delivery expanded them).
+ */
+import { MergedScenario } from './scenario-merger';
+import { PlaywrightResult } from './types';
+
+export interface ResultVariant {
+  /** Appended to the scenario display name: `''` for a plain scenario, ` — <label>` per executed
+   *  @cases dataset row (so each row gets a distinct category1). */
+  nameSuffix: string;
+  result?: PlaywrightResult;
+}
+
+/**
+ * Resolve the execution-result variant(s) for a merged scenario.
+ *
+ * A `@cases:<dataset>` scenario compiles to one `test()` per dataset row, whose Playwright title is
+ * `<scenario> — <label>` — expand into one variant per EXECUTED row by matching that prefix (so an
+ * already-run row carries its real pass/fail). A plain scenario resolves its single result by the
+ * spec test title. With no results — or a @cases scenario with no matching result yet — a lone
+ * variant with no result is returned, so the caller marks it Pending / N/A.
+ *
+ * NOTE: this deliberately does NOT gate on `m.spec`. For @cases the compiled test title carries a
+ * `— ${__row.__label}` suffix, so `findMatchingSpecTest` (base-name match) often leaves `m.spec`
+ * null even though the rows ran; the marker match still finds their results. Callers must let a
+ * present `result` win over the "not compiled" (`!m.spec`) heuristic.
+ */
+export function resolveResultVariants(
+  m: MergedScenario,
+  results: Map<string, PlaywrightResult> | null,
+): ResultVariant[] {
+  const isCases = m.feature.tags.some((t) => t.startsWith('@cases:'));
+  if (isCases && results) {
+    const marker = `${m.feature.name} — `;
+    const rows = [...results.entries()].filter(([t]) => t.includes(marker));
+    if (rows.length) {
+      return rows.map(([t, r]) => ({ nameSuffix: ` — ${t.slice(t.indexOf(marker) + marker.length)}`, result: r }));
+    }
+    return [{ nameSuffix: '' }];
+  }
+  if (results && m.spec) {
+    return [{ nameSuffix: '', result: results.get(m.spec.testTitle) }];
+  }
+  return [{ nameSuffix: '' }];
+}

package/src/exporters/types.ts

@@ -170,5 +170,12 @@ export interface ApiCatalogEntry {
   description?: string;
   body?: unknown;
   params?: unknown;
+  /** Per-endpoint header templates (e.g. authorization: "Bearer :token"); `:param` tokens
+   *  bind at runtime from the same args as the body/path. */
+  headers?: Record<string, string>;
+  /** Request-body wire format — decides the Content-Type the request sends.
+   *  Absent/`json` → application/json, `form` → application/x-www-form-urlencoded,
+   *  `multipart` → multipart/form-data. */
+  encoding?: 'json' | 'form' | 'multipart';
   expect?: { status?: number | string };
 }

package/src/exporters/xlsx-exporter.ts

@@ -267,11 +267,29 @@ function addOverviewSheet(wb: ExcelJS.Workbook, sheets: LocaleSheet[]): void {
     });
   };
 
+  // Each detail sheet carries a LIVE summary band (row 7): C7 Total · D7 Passed · E7 Failed ·
+  // F7 Pending · G7 N/A · H7 Remaining, all COUNTA/COUNTIF over the data area. The Overview
+  // REFERENCES those cells (`='<sheet>'!D7`) instead of freezing a number at export time — so when
+  // QA adds/edits/removes a row in the Auto or Manual sheet, the roll-up recomputes automatically.
+  const qname = (name: string): string => name.replace(/'/g, "''"); // Excel escapes ' by doubling
+  const ref = (name: string, cell: string, result: number): ExcelJS.CellFormulaValue =>
+    ({ formula: `'${qname(name)}'!${cell}`, result });
+
   let rowIdx = HEADER_ROW + 1;
+  const firstDataRow = rowIdx;
   sheets.forEach((s, i) => {
     const su = s.summary;
     const remain = Math.max(0, su.total - su.passed - su.na);
-    writeDataRow(rowIdx, [i + 1, s.sheetName, su.passed, su.failed, su.pending, su.na, remain, su.total], false);
+    writeDataRow(rowIdx, [
+      i + 1,
+      s.sheetName,
+      ref(s.sheetName, 'D7', su.passed),
+      ref(s.sheetName, 'E7', su.failed),
+      ref(s.sheetName, 'F7', su.pending),
+      ref(s.sheetName, 'G7', su.na),
+      ref(s.sheetName, 'H7', remain),
+      ref(s.sheetName, 'C7', su.total),
+    ], false);
     totals.passed += su.passed;
     totals.failed += su.failed;
     totals.pending += su.pending;
@@ -280,10 +298,23 @@ function addOverviewSheet(wb: ExcelJS.Workbook, sheets: LocaleSheet[]): void {
     totals.total += su.total;
     rowIdx += 1;
   });
+  const lastDataRow = rowIdx - 1;
 
+  // Grand total = SUM of the per-sheet Overview cells (also live — recomputes with the references
+  // above). Overview count columns are D..I (Passed·Failed·Pending·N/A·Remain·Total).
+  const sumCol = (col: string, result: number): ExcelJS.CellFormulaValue =>
+    ({ formula: `SUM(${col}${firstDataRow}:${col}${lastDataRow})`, result });
   writeDataRow(
     rowIdx,
-    ['', 'Total', totals.passed, totals.failed, totals.pending, totals.na, totals.remain, totals.total],
+    [
+      '', 'Total',
+      sumCol('D', totals.passed),
+      sumCol('E', totals.failed),
+      sumCol('F', totals.pending),
+      sumCol('G', totals.na),
+      sumCol('H', totals.remain),
+      sumCol('I', totals.total),
+    ],
     true,
   );
 }
@@ -313,7 +344,7 @@ function addTestcaseSheet(
     { width: 17 },    // E — Test Object
     { width: 25.5 },  // F — Pre-condition
     { width: 24.88 }, // G — Test Data
-    { width: 24.88 }, // H — Steps
+    { width: 50 },    // H — Steps (widened ~2× — steps are the longest cell)
     { width: 41 },    // I — Expected results
     { width: 12 },    // J — Priority
     { width: 13.5 },  // K — Testcase type
@@ -346,16 +377,18 @@ function addTestcaseSheet(
   // No explicit height → Excel auto-fits this row's content.
 
   // -- Row 7: Counts (cols C..H), live formulas referencing the data area --
-  // Data table starts at row 15 (col header at row 14, divider at row 14? actually
-  // header at row 13 + divider at 14 + first data at 15). The formulas read col L
-  // (Test Result) for status counts, col A (TC ID) for total via COUNTA.
+  // The data region begins at row 14 — the row immediately AFTER the column-header row (row 13).
+  // Start the ranges there (NOT row 15): the first category divider usually sits at row 14 with a
+  // BLANK col A (so COUNTA skips it), but a sheet whose first row after the header is real data —
+  // no leading divider — would be UNDER-counted by a range that started at 15. Row 14 covers both.
+  const COUNT_RANGE_START = 14;
   const COUNT_RANGE_END = 10000;
   const r7Values: Record<string, ExcelJS.CellValue> = {
-    C: { formula: `COUNTA(A15:A${COUNT_RANGE_END})`, result: summary.total } as ExcelJS.CellFormulaValue,
-    D: { formula: `COUNTIF(L15:L${COUNT_RANGE_END},"Passed")`, result: summary.passed } as ExcelJS.CellFormulaValue,
-    E: { formula: `COUNTIF(L15:L${COUNT_RANGE_END},"Failed")`, result: summary.failed } as ExcelJS.CellFormulaValue,
-    F: { formula: `COUNTIF(L15:L${COUNT_RANGE_END},"Pending")`, result: summary.pending } as ExcelJS.CellFormulaValue,
-    G: { formula: `COUNTIF(L15:L${COUNT_RANGE_END},"N/A")`, result: summary.na } as ExcelJS.CellFormulaValue,
+    C: { formula: `COUNTA(A${COUNT_RANGE_START}:A${COUNT_RANGE_END})`, result: summary.total } as ExcelJS.CellFormulaValue,
+    D: { formula: `COUNTIF(L${COUNT_RANGE_START}:L${COUNT_RANGE_END},"Passed")`, result: summary.passed } as ExcelJS.CellFormulaValue,
+    E: { formula: `COUNTIF(L${COUNT_RANGE_START}:L${COUNT_RANGE_END},"Failed")`, result: summary.failed } as ExcelJS.CellFormulaValue,
+    F: { formula: `COUNTIF(L${COUNT_RANGE_START}:L${COUNT_RANGE_END},"Pending")`, result: summary.pending } as ExcelJS.CellFormulaValue,
+    G: { formula: `COUNTIF(L${COUNT_RANGE_START}:L${COUNT_RANGE_END},"N/A")`, result: summary.na } as ExcelJS.CellFormulaValue,
     H: { formula: 'C7-D7-G7', result: summary.failed + summary.pending } as ExcelJS.CellFormulaValue,
   };
   for (const [col, val] of Object.entries(r7Values)) {
@@ -435,8 +468,10 @@ function addTestcaseSheet(
     applyBorder(cell);
   });
 
-  // Freeze everything above and below the header row — reveal header when scrolling.
-  ws.views = [{ state: 'frozen', ySplit: headerRow.number }];
+  // No freeze — the whole sheet scrolls freely (the masthead + summary band + header scroll away
+  // with the data). QA asked for this so the wide Steps/Expected columns aren't pinned under a frozen
+  // header on smaller screens.
+  ws.views = [{ state: 'normal' }];
 
   // -- Data rows grouped by category --
   const order = ['Accessing', 'GUI', 'Function'];

package/src/generators/test-generator/adapters/appium/templates/scenario.hbs

@@ -1,4 +1,4 @@
-  it('{{scenarioName}}', async () => {
+  it('{{escapeQuotes scenarioName}}', async () => {
 {{#each steps}}
 {{#if comment}}
     // {{comment}}

package/src/generators/test-generator/adapters/playwright/templates/scenario.hbs

@@ -1,9 +1,9 @@
 {{#if casesDataset}}
   for (const __row of testData.cases('{{casesDataset}}')) {
 {{#if tags}}
-  test(`{{scenarioName}} — ${__row.__label}`, { tag: [{{{tags}}}] }, async ({{#if isParallel}}{ page }{{/if}}) => {
+  test('{{escapeQuotes scenarioName}} — ' + __row.__label, { tag: [{{{tags}}}] }, async ({{#if isParallel}}{ page }{{/if}}) => {
 {{else}}
-  test(`{{scenarioName}} — ${__row.__label}`, async ({{#if isParallel}}{ page }{{/if}}) => {
+  test('{{escapeQuotes scenarioName}} — ' + __row.__label, async ({{#if isParallel}}{ page }{{/if}}) => {
 {{/if}}
     const rowData = testData.withRow(__row);
 {{#each steps}}
@@ -17,9 +17,9 @@
 {{else}}
 {{#if isParallel}}
 {{#if tags}}
-  test('{{scenarioName}}', { tag: [{{{tags}}}] }, async ({ page }) => {
+  test('{{escapeQuotes scenarioName}}', { tag: [{{{tags}}}] }, async ({ page }) => {
 {{else}}
-  test('{{scenarioName}}', async ({ page }) => {
+  test('{{escapeQuotes scenarioName}}', async ({ page }) => {
 {{/if}}
 {{#each steps}}
 {{#if comment}}
@@ -30,9 +30,9 @@
   });
 {{else}}
 {{#if tags}}
-  test('{{scenarioName}}', { tag: [{{{tags}}}] }, async () => {
+  test('{{escapeQuotes scenarioName}}', { tag: [{{{tags}}}] }, async () => {
 {{else}}
-  test('{{scenarioName}}', async () => {
+  test('{{escapeQuotes scenarioName}}', async () => {
 {{/if}}
 {{#each steps}}
 {{#if comment}}

package/src/generators/test-generator/adapters/playwright/templates/steps/actions/expand-action.hbs

@@ -1,11 +1,33 @@
+{ const el = {{> locator}};
+{{#if expanded.state}}
+{{!-- Toggle-only: component exposes no observable expanded state → click without asserting. --}}
+await el.click();
+{{else if expanded.class}}
+{{!-- State signalled by a class on a descendant (e.g. an accordion chevron icon). --}}
 {{#if (eq direction 'expand')}}
-if (await {{> locator}}.getAttribute('aria-expanded') !== 'true') {
-  await {{> locator}}.click();
-}
-await expect({{> locator}}).toHaveAttribute('aria-expanded', 'true');
+if (!(await el.locator('.{{expanded.class}}').count())) { await el.click(); }
+await expect(el.locator('.{{expanded.class}}')).toBeVisible();
+{{else}}
+if (await el.locator('.{{expanded.class}}').count()) { await el.click(); }
+await expect(el.locator('.{{expanded.class}}')).toHaveCount(0);
+{{/if}}
+{{else if expanded.attribute}}
+{{!-- Explicit boolean attribute ('true'/'false'), custom or aria-expanded. --}}
+{{#if (eq direction 'expand')}}
+if (await el.getAttribute('{{expanded.attribute}}') !== 'true') { await el.click(); }
+await expect(el).toHaveAttribute('{{expanded.attribute}}', 'true');
+{{else}}
+if (await el.getAttribute('{{expanded.attribute}}') !== 'false') { await el.click(); }
+await expect(el).toHaveAttribute('{{expanded.attribute}}', 'false');
+{{/if}}
+{{else}}
+{{!-- Default (zero-config): drive by aria-expanded, but assert it ONLY when the element exposes it. --}}
+{{#if (eq direction 'expand')}}
+if (await el.getAttribute('aria-expanded') !== 'true') { await el.click(); }
+if (await el.getAttribute('aria-expanded') !== null) { await expect(el).toHaveAttribute('aria-expanded', 'true'); }
 {{else}}
-if (await {{> locator}}.getAttribute('aria-expanded') !== 'false') {
-  await {{> locator}}.click();
+if (await el.getAttribute('aria-expanded') !== 'false') { await el.click(); }
+if (await el.getAttribute('aria-expanded') !== null) { await expect(el).toHaveAttribute('aria-expanded', 'false'); }
+{{/if}}
+{{/if}}
 }
-await expect({{> locator}}).toHaveAttribute('aria-expanded', 'false');
-{{/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/selected-assertion.hbs

@@ -1 +1,16 @@
-await expect({{> locator}}).toHaveAttribute('aria-selected', 'true');
+{{#if (or (eq role 'checkbox') (eq role 'radio') (eq role 'switch'))}}
+{{!-- Form control: "selected" is the checked state, never aria-selected. A native checkbox/radio
+     exposes no aria-selected attribute — its state lives in the `checked` property. --}}
+await expect({{> locator}}).toBeChecked();
+{{else}}
+{{!-- Other/unknown role (tab, option, or a text/testid/css selector): probe at runtime. An ARIA
+     single-select widget exposes aria-selected → assert it; anything without it falls back to the
+     checked state. Never hardcode aria-selected — it breaks on native form controls. --}}
+{ const el = {{> locator}};
+if ((await el.getAttribute('aria-selected')) !== null) {
+await expect(el).toHaveAttribute('aria-selected', 'true');
+} else {
+await expect(el).toBeChecked();
+}
+}
+{{/if}}

package/src/generators/test-generator/patterns/expect-patterns.ts

@@ -17,6 +17,14 @@ import { MappedStep } from '../step-mapper';
 const VALUE = String.raw`\{\{[^}]+\}\}|"[^"]*"|'[^']*'|-?\d+(?:\.\d+)?`;
 const reExpect = new RegExp(`^\\s*(?:User\\s+)?expect\\s+(${VALUE})\\s+is\\s+(not\\s+|at\\s+least\\s+|at\\s+most\\s+)?(${VALUE})\\s*$`, 'i');
 
+/** `expect {{name.body}} matches schema [Ref]` — validate a bound API response body against a named
+ *  JSON Schema (from qa/api/schemas.yaml, populated by `sungen api import`). Requires the API Driver
+ *  (the scenario carries `@api:<name>`, so the `api` runtime helper is imported).
+ *  Two regexes: the MATCHER sees ref contents masked (`{{~}}`, `[~]` — see maskRefsForMatching); the
+ *  GENERATOR gets the ORIGINAL step text, so it extracts the real `[Ref]`. */
+const reMatchesSchemaMasked = /^\s*(?:User\s+)?expect\s+\{\{~\}\}\s+matches\s+schema\s+\[~\]\s*$/i;
+const reMatchesSchema = new RegExp(`^\\s*(?:User\\s+)?expect\\s+(\\{\\{[^}]+\\}\\})\\s+matches\\s+schema\\s+\\[([A-Za-z0-9_.-]+)\\]\\s*$`, 'i');
+
 /** Render a value token (`{{var}}` | "literal" | 'literal' | number) as a JS expression. */
 function valueExpr(token: string): string {
   const t = token.trim();
@@ -29,6 +37,21 @@ function valueExpr(token: string): string {
 }
 
 export const expectPatterns: StepPattern[] = [
+  {
+    name: 'expect-matches-schema',
+    priority: 63, // above expect-data; its regex needs `matches schema`, so no overlap
+    matcher: (step: ParsedStep) => reMatchesSchemaMasked.test(step.text),
+    generator: (step: ParsedStep, _ctx: PatternContext): MappedStep => {
+      // The masked matcher is looser than this extraction regex, so a malformed step (empty var/ref,
+      // odd chars) can claim the pattern yet not re-match here — emit a clear TODO instead of crashing.
+      const m = step.text.match(reMatchesSchema);
+      if (!m) return { code: `// TODO: malformed 'matches schema' step (expected: expect {{name.body}} matches schema [Ref]): ${step.text}`, comment: 'Unrecognized matches-schema step' };
+      const value = valueExpr(m[1]);
+      const ref = m[2];
+      const code = `{ const __schema = api.assertSchema(${value}, ${JSON.stringify(ref)}); expect(__schema.ok, \`matches schema [${ref}]: \${__schema.errors}\`).toBe(true); }`;
+      return { code, comment: `Expect ${m[1]} matches schema [${ref}]` };
+    },
+  },
   {
     name: 'expect-data',
     priority: 62, // above generic see-assertions; sibling of the DB assertions

package/src/generators/test-generator/patterns/index.ts

@@ -4,6 +4,23 @@ import { StepPattern, PatternContext } from './types';
 import { capabilityRegistry } from '../../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../../capabilities/discover';
 
+/**
+ * Mask the CONTENT of selector refs `[...]` and data placeholders `{{...}}` before verb matching,
+ * keeping the delimiters. A step's verb/keywords come from the SENTENCE — never from a selector or
+ * variable NAME — but matchers scan `step.text` with substring checks (e.g. `includes('click')`),
+ * so a data ref like `{{double_click_guard_account.email}}` would spuriously satisfy the click
+ * matcher and pre-empt fill. The content is replaced with an inert placeholder (`~` — carries no
+ * verb/keyword/digit substring) rather than emptied, so structural matchers that require a NON-EMPTY
+ * ref survive too — e.g. `expect {{a}} is {{b}}` matches `\{\{[^}]+\}\}`, and `in [X] table` /
+ * `/\bto\s+\[/` keep their delimiters. The resolver/generator always receives the ORIGINAL step, so
+ * value extraction and codegen are unaffected.
+ */
+export function maskRefsForMatching(text: string): string {
+  return text
+    .replace(/\{\{[^}]*\}\}/g, '{{~}}')
+    .replace(/\[[^\]]*\]/g, '[~]');
+}
+
 /**
  * Pattern Registry - manages all step patterns
  */
@@ -40,8 +57,11 @@ export class PatternRegistry {
    * Find matching pattern for a step
    */
   findPattern(step: ParsedStep): StepPattern | null {
+    // Match against text with ref CONTENTS masked, so a verb substring inside a selector/data name
+    // (e.g. "click" in `{{double_click_guard_account.email}}`) can't hijack the verb classification.
+    const matchStep: ParsedStep = { ...step, text: maskRefsForMatching(step.text) };
     for (const pattern of this.patterns) {
-      if (this.matchesPattern(step, pattern.matcher)) {
+      if (this.matchesPattern(matchStep, pattern.matcher)) {
         return pattern;
       }
     }

package/src/generators/test-generator/utils/selector-resolver.ts

@@ -39,6 +39,17 @@ interface SelectorEntry {
   // === v2: Assertion Helpers ===
   attribute?: string;     // Attribute to check (for "has" assertions)
   pattern?: string;       // Regex for attribute value
+
+  // === Expand/collapse state signal ===
+  // How the open/closed state of an expandable element is observed. Many accordions expose no
+  // `aria-expanded` (state shows only via an icon class swap), so hardcoding it makes the assertion
+  // time out. When omitted, codegen drives by aria-expanded but asserts it ONLY if present — a safe
+  // zero-config fallback. Provide one of these to verify a non-aria component explicitly.
+  expanded?: {
+    class?: string;       // class present on a descendant when open (e.g. 'mdi-chevron-up')
+    attribute?: string;   // boolean attribute ('true'/'false') on the toggle element
+    state?: 'none';       // no observable state → toggle-click only, skip the assertion
+  };
 }
 
 // New selector file structure: flat key-value pairs
@@ -64,6 +75,12 @@ export interface ResolvedSelector {
   strategy: 'testid' | 'id' | 'placeholder' | 'label' | 'text' | 'css' | 'role' | 'locator'
     | 'accessibility-id' | 'xpath' | 'android-uiautomator' | 'ios-predicate';
   value: string;
+  // Original YAML `type:` of the matched entry (before it collapses into a `strategy`). Callers
+  // that assign meaning to the entry kind — e.g. page assertions, whose `value` is a URL ONLY when
+  // the entry is a `page` selector — must verify this instead of trusting a key match. A key can
+  // collide across types (one `読取結果一覧` entry, type `role`, reused for a page assertion), so a
+  // key-only lookup can hand back an entry whose `value` ('button') is meaningless as a URL.
+  selectorType?: SelectorType;
   // Mobile per-platform variant (`android:`/`ios:` in selectors.yaml). When set, the appium codegen
   // emits a runtime `driver.isIOS ? '<ios>' : '<android>'` so one @platform:mobile spec resolves the
   // right native selector per OS. Each side carries its own strategy+value (issue #392).
@@ -87,6 +104,7 @@ export interface ResolvedSelector {
   pagination?: Record<string, string>;
   attribute?: string;   // Attribute to check
   pattern?: string;     // Regex for attribute value
+  expanded?: { class?: string; attribute?: string; state?: 'none' };  // Expand/collapse state signal
 }
 
 /**
@@ -460,8 +478,14 @@ export class SelectorResolver {
     const type = entry.type || 'placeholder';
     // Check if value exists in entry (even if empty string), use it; otherwise use originalLabel
     const rawValue = entry.value !== undefined && entry.value !== null ? entry.value : originalLabel;
-    // Check if name exists in entry (even if empty string), use it; otherwise use originalLabel
-    const rawName = entry.name !== undefined && entry.name !== null ? entry.name : originalLabel;
+    // Name resolution has three cases:
+    //   - key absent (undefined)      → fall back to originalLabel (the [Reference] text)
+    //   - explicit null / empty string → disable the name filter entirely (rawName = '')
+    //   - a real string               → use it verbatim
+    // Explicit `name: null` in YAML is a deliberate opt-out (e.g. a role selector that must NOT
+    // filter by accessible name); it must not be conflated with "unset". The role template omits
+    // `{ name }` when this resolves to a falsy value.
+    const rawName = entry.name === undefined ? originalLabel : (entry.name ?? '');
     const value = SelectorResolver.resolveTemplateVars(rawValue);
     const name = SelectorResolver.resolveTemplateVars(rawName);
     const nth = entry.nth !== undefined && entry.nth !== null ? entry.nth : undefined;
@@ -480,10 +504,14 @@ export class SelectorResolver {
     if (entry.pagination) v2Fields.pagination = entry.pagination;
     if (entry.attribute) v2Fields.attribute = entry.attribute;
     if (entry.pattern) v2Fields.pattern = entry.pattern;
+    if (entry.expanded) v2Fields.expanded = entry.expanded;
 
     // Helper to attach v2 fields and inputMethod
     const withExtras = (resolved: ResolvedSelector): ResolvedSelector => {
       if (inputMethod) resolved.inputMethod = inputMethod;
+      // Preserve the entry's original YAML type so callers can verify the entry kind (a key match
+      // alone does not guarantee the entry means what the step expects — see ResolvedSelector.selectorType).
+      resolved.selectorType = type;
       return { ...resolved, ...v2Fields };
     };
 

package/src/orchestrator/project-initializer.ts

@@ -4,6 +4,7 @@
  */
 
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { execSync } from 'child_process';
 import { buildOutputs } from './ai-skills/build';
@@ -23,11 +24,77 @@ function sungenVersion(): string {
   catch { return '0.0.0'; }
 }
 
+/**
+ * Header written atop a NEW `.codex/config.toml`. Codex loads a PROJECT-scoped config.toml only
+ * for TRUSTED projects — without trust the MCP server silently never loads — so the note tells the
+ * user how to enable it. (Claude reads `.mcp.json` and Copilot `.vscode/mcp.json` with no such gate.)
+ */
+const CODEX_MCP_HEADER = [
+  '# Sungen — Codex MCP config (project-scoped, gives run-test the same live browser as Claude/Copilot).',
+  '# NOTE: Codex loads a project .codex/config.toml ONLY for TRUSTED projects. If the browser tools',
+  '# never appear, trust this project (open it with `codex` and approve, or set trust_level = "trusted"',
+  '# for this path in ~/.codex/config.toml). To add Figma too, see https://mcp.figma.com/mcp.',
+  '',
+  '',
+].join('\n');
+
+/**
+ * Append-if-absent merge for Codex's TOML MCP config. Mirrors `mergeMCPConfig`'s "user edits win"
+ * contract: preserves the existing file and any user-defined `[mcp_servers.*]`, and only appends the
+ * sungen server table when it is missing. Returns `null` when the target server is already present
+ * (nothing to write). TOML by hand (no toml dep) — the block is a fixed, simple table.
+ */
+export function mergeCodexMcpToml(existing: string, mobileOnly: boolean): string | null {
+  const serverKey = mobileOnly ? 'appium-mcp' : 'playwright';
+  // Already configured (by the user or a previous run) → preserve, do nothing.
+  if (new RegExp(String.raw`^\s*\[mcp_servers\.(?:"?${serverKey}"?)\]`, 'm').test(existing)) return null;
+  // startup_timeout_sec: Codex's default is 10s, which `npx <pkg>@latest` blows past on a cold
+  // cache (it downloads the package first) — the server then "fails to start" and Codex drops it.
+  // default_tools_approval_mode: Codex gates every MCP tool call behind an approval elicitation;
+  // non-interactive runs (`codex exec`, full-auto) auto-CANCEL it — "user cancelled MCP tool call"
+  // — so run-test could never drive the browser headlessly. Auto-approve is scoped to this server
+  // only and the whole file already requires project trust.
+  const serverOpts = 'startup_timeout_sec = 120\ndefault_tools_approval_mode = "approve"\n';
+  const block = mobileOnly
+    ? `[mcp_servers.appium-mcp]\ncommand = "npx"\nargs = ["-y", "appium-mcp"]\n${serverOpts}`
+    : `[mcp_servers.playwright]\ncommand = "npx"\nargs = ["@playwright/mcp@latest"]\n${serverOpts}`;
+  if (existing.trim() === '') return CODEX_MCP_HEADER + block;
+  return existing + (existing.endsWith('\n') ? '\n' : '\n\n') + block;
+}
+
+/**
+ * Whether the user's global Codex config (`~/.codex/config.toml`) marks `projectDir` trusted.
+ * Codex loads a project `.codex/config.toml` ONLY for trusted projects and skips it SILENTLY
+ * otherwise — the #1 "Codex doesn't see the Playwright MCP server" failure — so init checks and
+ * warns instead of leaving the user with a config that never loads. Pure string scan (no toml dep).
+ */
+export function codexTrustsProject(configText: string, projectDir: string): boolean {
+  let currentProject: string | null = null;
+  const trusted: string[] = [];
+  for (const line of configText.split('\n')) {
+    const header = line.match(/^\s*\[(.+)\]\s*$/);
+    if (header) {
+      const m = header[1].trim().match(/^projects\.(?:"(.+)"|'(.+)'|(.+))$/);
+      currentProject = m ? (m[1] ?? m[2] ?? m[3]) : null;
+      continue;
+    }
+    if (currentProject && /^\s*trust_level\s*=\s*"trusted"\s*$/.test(line)) trusted.push(currentProject);
+  }
+  // Codex resolves the project by walking UP from cwd (git root / trusted ancestor), so a dir
+  // nested inside a trusted project is itself trusted — verified live: `codex mcp list` inside
+  // examples/<new>/ loads its .codex/config.toml with only the repo root in the trust list.
+  return trusted.some(
+    (dir) => projectDir === dir || projectDir.startsWith(dir.endsWith(path.sep) ? dir : dir + path.sep),
+  );
+}
+
 export class ProjectInitializer {
   private baseCwd: string;
   private cwd: string;
   private createdItems: string[] = [];
   private skippedItems: string[] = [];
+  /** set by createCodexMCPConfig when the project isn't Codex-trusted (config would never load) */
+  private codexTrustWarning = false;
   private agents: AdapterKey[];
   private force: boolean;
   private mobile: MobileInitOptions;
@@ -116,6 +183,12 @@ export class ProjectInitializer {
     // Create root .mcp.json for Claude Code
     this.createClaudeMCPConfig();
 
+    // Create .codex/config.toml for Codex CLI — only when Codex is a selected assistant
+    // (`sungen init --assistant codex`), since it is Codex-specific config.
+    if (this.agents.includes('codex')) {
+      this.createCodexMCPConfig();
+    }
+
     // Display summary
     this.displaySummary(normalizedProjectName);
   }
@@ -309,6 +382,39 @@ export class ProjectInitializer {
     );
   }
 
+  /**
+   * Create `.codex/config.toml` for Codex CLI — the Codex analog of `.mcp.json` (Claude) and
+   * `.vscode/mcp.json` (Copilot), so `sungen run-test` under Codex drives the same live Playwright
+   * MCP browser instead of Codex's own (headless) fallback. Mobile-only → appium-mcp. Append-only:
+   * preserves an existing file + any user server table (via `mergeCodexMcpToml`).
+   */
+  private createCodexMCPConfig(): void {
+    const filePath = path.join(this.cwd, '.codex', 'config.toml');
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    const existed = fs.existsSync(filePath);
+    const existing = existed ? fs.readFileSync(filePath, 'utf-8') : '';
+    const merged = mergeCodexMcpToml(existing, this.mobileOnly);
+    if (merged !== null) {
+      fs.writeFileSync(filePath, merged, 'utf-8');
+      this.createdItems.push(existed ? '.codex/config.toml (updated)' : '.codex/config.toml');
+    } else {
+      this.skippedItems.push('.codex/config.toml');
+    }
+
+    // Trust gate: without a trusted entry in the GLOBAL Codex config, the project config above
+    // is silently ignored and run-test never gets the MCP browser. Warn in the summary.
+    const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+    let trusted = false;
+    try {
+      trusted = codexTrustsProject(fs.readFileSync(path.join(codexHome, 'config.toml'), 'utf-8'), this.cwd);
+    } catch {
+      // no global config yet → definitely untrusted
+    }
+    this.codexTrustWarning = !trusted;
+  }
+
   /**
    * Add MCP server entries without overwriting user config.
    * Preserves existing entries with the same key — user edits always win.
@@ -377,6 +483,16 @@ export class ProjectInitializer {
       });
     }
 
+    if (this.codexTrustWarning) {
+      console.log('\n⚠ Codex: this project is not trusted yet, so .codex/config.toml (the MCP browser');
+      console.log('  config for run-test) will be SILENTLY IGNORED by Codex. To fix, either:');
+      console.log('    • open the project with `codex` once and approve the trust prompt, or');
+      console.log('    • add to ~/.codex/config.toml:');
+      console.log(`        [projects."${this.cwd}"]`);
+      console.log('        trust_level = "trusted"');
+      console.log('  Then verify with `codex mcp list` — it should show the sungen MCP server.');
+    }
+
     console.log('\nNext steps:');
     let stepIndex = 1;
     if (projectName) {
@@ -538,10 +654,11 @@ export class ProjectInitializer {
     // Ensure standard scripts exist in package.json
     this.ensurePackageScripts(packageJsonPath);
 
-    // Mobile-only drops @playwright/test (no web runner needed).
+    // Mobile-only drops @playwright/test (no web runner needed). `ajv`/`ajv-formats` back the API
+    // Driver's `expect {{name.body}} matches schema [Ref]` (loaded lazily; harmless if unused).
     const requiredDeps = this.mobileOnly
-      ? ['@types/node', 'yaml']
-      : ['@playwright/test', '@types/node', 'yaml'];
+      ? ['@types/node', 'yaml', 'ajv', 'ajv-formats']
+      : ['@playwright/test', '@types/node', 'yaml', 'ajv', 'ajv-formats'];
 
     let missingDeps: string[] = requiredDeps;
     try {