@sun-asterisk/sungen 3.2.4 → 3.2.5

package/src/dashboard/types.ts

@@ -39,8 +39,12 @@ export interface AggregateSummary {
 }
 
 export interface ScreenSnapshot {
-  name: string;                        // "kudos" or "flow/checkout" — the screen DIRECTORY name
+  name: string;                        // "kudos", "flow/checkout", or "api/login" — the unit label
   isFlow: boolean;
+  /** Unit kind — screen | flow | api. Drives the dashboard's suite badge so API
+   *  suites read as API rather than being mislabelled "web". Optional so history
+   *  snapshots written before this field still parse (they render as screen). */
+  kind?: 'screen' | 'flow' | 'api';
   platform?: 'web' | 'android' | 'ios' | 'mobile'; // 'mobile' = @platform:mobile screen (per-OS features below)
   featureName: string;                 // name of the primary (first) feature; kept for backwards compat
   featurePath?: string;                // entry-point path of the primary feature

package/src/exporters/api-testcase-formatter.ts

@@ -0,0 +1,325 @@
+/**
+ * Render an API test case's Steps / Expected-results cells for the delivery report.
+ *
+ * API scenarios carry no Given/When steps and assert against runtime response
+ * refs (`expect {{endpoint.status}} is 201`), so the generic row builder leaves
+ * the Steps cell empty and the Expected cell showing raw `{{…}}`. This module
+ * turns the scenario's `@api:<name>(args)` tag + the apis.yaml catalog into a
+ * human-readable request block (Method / API / Header / Body) and rewrites the
+ * assertions into "Status / Response" language.
+ *
+ * Deterministic — no AI, no network. Everything is sourced from the catalog +
+ * scenario tags + test-data, mirroring exactly what the generated request sends
+ * (see orchestrator/templates/specs-api.ts: catalog headers + a Content-Type
+ * implied by the body wire format; `:param` falls back to the same-named
+ * test-data key when the tag omits it).
+ */
+
+import { ApiCatalogEntry } from './types';
+
+/** A single `@api:<name>(k=v,…)` invocation parsed from a scenario's tags. */
+export interface ApiCall {
+  name: string;
+  /** param → value expression, kept raw: `{{new_email}}`, `"literal"`, `3`. */
+  args: Record<string, string>;
+}
+
+/** True when the scenario invokes at least one `@api:` endpoint. */
+export function hasApiCalls(tags: string[]): boolean {
+  return tags.some((t) => t.startsWith('@api:'));
+}
+
+/**
+ * Parse the ordered `@api:<name>(arg=expr,…)` invocations from a scenario's tags.
+ * Mirrors the driver's override grammar: split the top-level comma list, then the
+ * first `=` per pair. Values stay as raw expressions so the caller resolves them
+ * the same way the runtime does.
+ */
+/**
+ * Same shape the runtime accepts (`driver-api/src/index.ts`): `@api:<name>` with an
+ * optional balanced `(...)` arg list. A malformed tag (e.g. unclosed paren) is rejected
+ * here too, so the report never documents a call the runtime silently dropped.
+ */
+const API_TAG = /^@api:([A-Za-z_][A-Za-z0-9_]*)(?:\((.*)\))?$/;
+
+export function parseApiCalls(tags: string[]): ApiCall[] {
+  const calls: ApiCall[] = [];
+  for (const t of tags) {
+    const m = API_TAG.exec(t);
+    if (!m) continue;
+    const args: Record<string, string> = {};
+    for (const pair of splitTopLevel(m[2] ?? '')) {
+      const eq = pair.indexOf('=');
+      if (eq < 0) continue;
+      args[pair.slice(0, eq).trim()] = pair.slice(eq + 1).trim();
+    }
+    calls.push({ name: m[1], args });
+  }
+  return calls;
+}
+
+/**
+ * Build the "Steps" cell for an API test case: one block per invoked endpoint,
+ * showing Method / API (resolved path) / Header / Body. Endpoints absent from the
+ * catalog are skipped. Returns '' when nothing resolves (caller keeps generic Steps).
+ *
+ * `localize` resolves `{{var}}` test-data placeholders (and selector keys) to
+ * concrete values — the same resolver the row builder uses for UI steps.
+ */
+export function formatApiRequest(
+  tags: string[],
+  catalog: Record<string, ApiCatalogEntry>,
+  localize: (text: string) => string,
+): string {
+  const calls = parseApiCalls(tags).filter((c) => catalog[c.name]);
+  if (calls.length === 0) return '';
+
+  const blocks = calls.map((call) => {
+    const entry = catalog[call.name];
+    const resolve = (raw: string): string => localize(bindParams(raw, call.args));
+    // Coerce method/path — loadApiCatalog is a raw passthrough, so a malformed entry
+    // (numeric method/path) must degrade gracefully, not crash the unit's export.
+    const method = String(entry.method ?? '').toUpperCase() || '—';
+    const api = entry.path ? resolve(String(entry.path)) : '—';
+    const header = formatHeaders(entry, call.args, localize);
+    const bodyStr = formatBody(entry.body, call.args, localize);
+    return [`Method: ${method}`, `API: ${api}`, `Header: ${header}`, `Body: ${bodyStr}`].join('\n');
+  });
+
+  if (blocks.length === 1) return blocks[0];
+  // Multiple endpoints (flow) — number them so the call order is explicit.
+  return blocks
+    .map((b, i) => b.split('\n').map((l, j) => (j === 0 ? `${i + 1}. ${l}` : `   ${l}`)).join('\n'))
+    .join('\n');
+}
+
+/**
+ * Rewrite an API scenario's `Then` assertions into readable Status / Response lines.
+ * Raw assertions reference the runtime response object
+ * (`expect {{endpoint.status}} is 201`, `expect {{endpoint.body.email}} is {{x}}`);
+ * we strip the endpoint prefix (a runtime var, meaningless to a reader), keep the
+ * field path, label status vs body, and resolve `{{var}}` on the right-hand side.
+ */
+export function formatApiExpected(
+  expectedSteps: Array<{ text: string }>,
+  tags: string[],
+  localize: (text: string) => string,
+): string {
+  const endpointNames = parseApiCalls(tags).map((c) => c.name);
+  const oracleNames = parseQueryOracles(tags);
+  const lines = expectedSteps
+    .map((s) => humanizeAssertion(s.text, endpointNames, oracleNames, localize))
+    .filter((l) => l.length > 0);
+  if (lines.length === 0) return '';
+  if (lines.length === 1) return lines[0];
+  return lines.map((l, i) => `${i + 1}. ${l}`).join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+/** Split a comma list, ignoring commas nested inside {}/[]/() so `{a,b}` stays whole. */
+function splitTopLevel(s: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let cur = '';
+  for (const ch of s) {
+    if (ch === '{' || ch === '[' || ch === '(') depth++;
+    else if (ch === '}' || ch === ']' || ch === ')') depth = Math.max(0, depth - 1);
+    if (ch === ',' && depth === 0) {
+      out.push(cur);
+      cur = '';
+    } else {
+      cur += ch;
+    }
+  }
+  if (cur.trim().length > 0) out.push(cur);
+  return out;
+}
+
+/**
+ * Substitute `:param` tokens (path / body / header templates) with the invocation's
+ * arg expression, falling back to `{{param}}` when the tag omits it — matching the
+ * runtime, where an unbound param resolves from the same-named test-data key.
+ */
+function bindParams(raw: string, args: Record<string, string>): string {
+  return raw.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_m, p: string) => {
+    const expr = p in args ? args[p] : `{{${p}}}`;
+    return unquoteExpr(expr);
+  });
+}
+
+/** Strip a matching pair of surrounding quotes from a tag-arg literal (`"x"` → `x`). */
+function unquoteExpr(e: string): string {
+  const m = e.match(/^"(.*)"$/) || e.match(/^'(.*)'$/);
+  return m ? m[1] : e;
+}
+
+/**
+ * Compose the Header cell from catalog `headers:` (with `:param` bound + `{{var}}`
+ * resolved) plus the Content-Type implied by the body wire format — Playwright sets
+ * that Content-Type from the encoding option at runtime (specs-api.ts), shown only
+ * when a body is sent and the catalog didn't already declare one. Returns '—' when
+ * the request has none.
+ *
+ * Scope: this reflects the per-endpoint catalog headers only. Datasource-level headers
+ * (`conf.headers` from the datasources config, merged at runtime) are NOT read here —
+ * the exporter doesn't load `.env.qa`/datasources — so the cell is a catalog view, not
+ * a byte-for-byte copy of the wire request.
+ */
+function formatHeaders(
+  entry: ApiCatalogEntry,
+  args: Record<string, string>,
+  localize: (text: string) => string,
+): string {
+  const explicit = entry.headers && typeof entry.headers === 'object' ? entry.headers : {};
+  const hasContentType = Object.keys(explicit).some((k) => k.toLowerCase() === 'content-type');
+  // Auth headers (authorization/cookie/api-key…) carry credentials — show the scheme
+  // but mask the value. A value-based redaction pass (redactSecrets) backstops this.
+  const parts = Object.entries(explicit).map(([k, v]) =>
+    isSensitiveHeader(k) ? `${k}: ${maskHeaderValue(String(v))}` : `${k}: ${localize(bindParams(String(v), args))}`,
+  );
+  if (!hasContentType && entry.body !== undefined && entry.body !== null) {
+    parts.push(`Content-Type: ${contentTypeFor(entry.encoding)}`);
+  }
+  return parts.length > 0 ? parts.join('\n') : '—';
+}
+
+function contentTypeFor(encoding?: string): string {
+  if (encoding === 'form') return 'application/x-www-form-urlencoded';
+  if (encoding === 'multipart') return 'multipart/form-data';
+  return 'application/json';
+}
+
+/**
+ * Compose the Body cell, masking credential fields. When the body is a flat object
+ * with a sensitive key (password/token/secret/…), each value is rendered per-key so
+ * that field can be replaced with `***`; otherwise the body resolves wholesale
+ * (preserving numbers/nesting exactly as before).
+ */
+function formatBody(body: unknown, args: Record<string, string>, localize: (text: string) => string): string {
+  if (body === undefined || body === null) return '—';
+  if (isPlainObject(body)) {
+    const obj = body as Record<string, unknown>;
+    if (Object.keys(obj).some(isSensitiveField)) {
+      const out: Record<string, string> = {};
+      for (const [k, v] of Object.entries(obj)) {
+        out[k] = isSensitiveField(k) ? '***' : localize(bindParams(typeof v === 'string' ? v : JSON.stringify(v), args));
+      }
+      return JSON.stringify(out);
+    }
+  }
+  return localize(bindParams(typeof body === 'string' ? body : JSON.stringify(body), args));
+}
+
+function isPlainObject(v: unknown): boolean {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Credential name matcher (substring, not anchored) for both body-field keys and
+ * test-data keys — catches variants like confirmPassword / new_password /
+ * password_confirmation / access_token / client_secret / otp / passcode.
+ */
+const SENSITIVE_NAME = /pass(word|code)?|passwd|pwd|secret|token|otp|api[-_]?key|apikey|credential|authorization/i;
+function isSensitiveField(key: string): boolean {
+  return SENSITIVE_NAME.test(key);
+}
+
+/**
+ * Resolved values of sensitive test-data keys — used for a value-based redaction pass
+ * over the finished Steps/Expected cells, closing the paths key-based masking misses
+ * (nested request bodies, query-string credentials, and the Expected assertion cell).
+ * Values shorter than 3 chars are skipped to avoid masking trivial/coincidental text.
+ */
+export function collectSecretValues(testData: Record<string, string>): string[] {
+  const secrets: string[] = [];
+  for (const [k, v] of Object.entries(testData)) {
+    if (typeof v === 'string' && v.length >= 3 && SENSITIVE_NAME.test(k)) secrets.push(v);
+  }
+  // Longest-first so a longer secret is redacted before any shorter substring of it.
+  return [...new Set(secrets)].sort((a, b) => b.length - a.length);
+}
+
+/** Replace every occurrence of each secret value with `***` (literal, not regex). */
+export function redactSecrets(text: string, secrets: string[]): string {
+  if (secrets.length === 0 || !text) return text;
+  let out = text;
+  for (const s of secrets) out = out.split(s).join('***');
+  return out;
+}
+
+/** Header names that carry credentials — value masked, scheme kept. */
+const SENSITIVE_HEADER = /^(authorization|proxy-authorization|cookie|set-cookie|x-api-key|api-key|x-auth-token|x-access-token|x-session-token)$/i;
+function isSensitiveHeader(name: string): boolean {
+  return SENSITIVE_HEADER.test(name);
+}
+
+/** Keep an auth scheme prefix (Bearer/Basic/…) but hide the credential. */
+function maskHeaderValue(value: string): string {
+  const m = value.match(/^(Bearer|Basic|Digest|Token)\b/i);
+  return m ? `${m[1]} ***` : '***';
+}
+
+/** Ordered `@query:<oracle>` DB-oracle names (a @concurrent idempotency cross-check). */
+function parseQueryOracles(tags: string[]): string[] {
+  return tags
+    .filter((t) => t.startsWith('@query:'))
+    .map((t) => {
+      const body = t.slice('@query:'.length);
+      const parenIdx = body.indexOf('(');
+      return parenIdx >= 0 ? body.slice(0, parenIdx) : body;
+    });
+}
+
+/**
+ * Turn one raw assertion line into a readable Status/Response statement.
+ * `{{<endpoint>.<field>}}` → a labelled response reference; `{{<oracle>.<field>}}`
+ * (a @query DB oracle) → the plain dotted path; remaining `{{var}}` (genuine
+ * test-data on the right-hand side) is resolved by `localize`.
+ */
+function humanizeAssertion(
+  raw: string,
+  endpointNames: string[],
+  oracleNames: string[],
+  localize: (text: string) => string,
+): string {
+  let s = raw.trim().replace(/^expect\s+/i, '');
+  // Field path allows array-index segments so @concurrent refs like
+  // `{{login.responses[0].body.token}}` are matched, not left as raw `{{…}}`.
+  const FIELD = '(?:[\\w.]|\\[\\d+\\])+';
+  if (endpointNames.length > 0) {
+    const alt = endpointNames.map(escapeRe).join('|');
+    s = s.replace(new RegExp(`\\{\\{\\s*(?:${alt})\\.(${FIELD})\\s*\\}\\}`, 'g'), (_m, field: string) =>
+      responseFieldLabel(field),
+    );
+  }
+  if (oracleNames.length > 0) {
+    // @query oracle refs read as a DB check — strip the `{{ }}` noise, keep `oracle.field`.
+    const alt = oracleNames.map(escapeRe).join('|');
+    s = s.replace(new RegExp(`\\{\\{\\s*((?:${alt})\\.${FIELD})\\s*\\}\\}`, 'g'), (_m, ref: string) => ref);
+  }
+  s = localize(s);
+  if (s.length === 0) return s;
+  // Don't recase a line that leads with a @query oracle identifier (a code name) —
+  // `user_count.count is 1` must not become `User_count.count is 1`.
+  const leadsWithOracle = oracleNames.some((o) => s === o || s.startsWith(`${o}.`));
+  return leadsWithOracle ? s : s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/** Map a response field path (after the `<endpoint>.` prefix) to reader-friendly text. */
+function responseFieldLabel(field: string): string {
+  if (field === 'status') return 'Status';
+  if (field === 'ok') return 'Response ok';
+  if (field === 'ok_count') return 'Success count';
+  if (field === 'body') return 'Response body';
+  if (field.startsWith('body.')) return `Response body.${field.slice('body.'.length)}`;
+  if (field.startsWith('status_counts.')) return `Count of ${field.slice('status_counts.'.length)} responses`;
+  if (field.startsWith('headers.')) return `Response header "${field.slice('headers.'.length)}"`;
+  return `Response ${field}`;
+}
+
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/exporters/csv-exporter.ts

@@ -22,7 +22,8 @@ import {
   formatNote,
   statusToTestResult,
 } from './playwright-report-parser';
-import { EnvironmentInfo, PlaywrightResult, ScreenSummary, TestCaseRow } from './types';
+import { ApiCatalogEntry, EnvironmentInfo, PlaywrightResult, ScreenSummary, TestCaseRow } from './types';
+import { collectSecretValues, formatApiExpected, formatApiRequest, hasApiCalls, redactSecrets } from './api-testcase-formatter';
 import { SelectorKeyMap, substituteSelectorKeysInStep } from './selector-key-resolver';
 
 export interface BuildCsvInput {
@@ -43,6 +44,18 @@ export interface BuildCsvInput {
    * instead of the VI selector key "Click [VỀ KUDOS] link".
    */
   selectorKeyMap?: SelectorKeyMap;
+  /**
+   * Unit kind. When `'api'`, the row builder renders the request contract
+   * (Method/API/Header/Body) into the Steps cell and the response contract
+   * (Status + Response) into the Expected cell — API scenarios otherwise leave
+   * Steps empty and Expected showing raw `{{endpoint.field}}` refs.
+   */
+  kind?: 'screen' | 'flow' | 'api';
+  /**
+   * apis.yaml catalog (keyed by endpoint name) for api-kind units. Supplies the
+   * Method/path/headers/body/encoding the readable request block is built from.
+   */
+  apiCatalog?: Record<string, ApiCatalogEntry>;
 }
 
 /**
@@ -97,15 +110,35 @@ export function buildTestCaseRows(input: BuildCsvInput): TestCaseRow[] {
       localize(s.bucket === 'given' ? keepActor(s.text) : stripActor(s.text));
     const stepLines    = m.resolvedSteps.map(formatStep).filter(Boolean);
     const expectedLines = m.resolvedExpected.map(formatStep).filter(Boolean);
-    const steps =
+    let steps =
       stepLines.length === 0 ? '' :
       stepLines.length === 1 ? stepLines[0] :
       stepLines.map((l, i) => `${i + 1}. ${l}`).join('\n');
-    const expectedResults =
+    let expectedResults =
       expectedLines.length === 0 ? '' :
       expectedLines.length === 1 ? expectedLines[0] :
       expectedLines.map((l, i) => `${i + 1}. ${l}`).join('\n');
 
+    // API test cases: the scenario has no Given/When (Steps empty) and asserts
+    // against runtime response refs (`{{endpoint.status}}` — left literal since
+    // they aren't test-data keys). Render the request contract into Steps and the
+    // response contract into Expected from the @api tag + apis.yaml catalog, so
+    // QA reads Method/API/Header/Body and Status/Response instead of raw refs.
+    if (input.kind === 'api' && input.apiCatalog && hasApiCalls(m.feature.tags)) {
+      const apiRequest = formatApiRequest(m.feature.tags, input.apiCatalog, localize);
+      if (apiRequest) steps = steps ? `${steps}\n\n${apiRequest}` : apiRequest;
+      const apiExpected = formatApiExpected(m.resolvedExpected, m.feature.tags, localize);
+      if (apiExpected) expectedResults = apiExpected;
+      // Value-based redaction backstop: mask resolved credential values (from
+      // sensitively-named test-data keys) anywhere in the API cells — closes the
+      // nested-body, query-string and Expected-cell paths key-based masking misses.
+      const secrets = collectSecretValues(input.testData);
+      if (secrets.length > 0) {
+        steps = redactSecrets(steps, secrets);
+        expectedResults = redactSecrets(expectedResults, secrets);
+      }
+    }
+
     // Multi-line bullet format keeps delivery CSV/XLSX in sync with the
     // dashboard's Test data section. Multi-line CSV cells are valid (quoted
     // automatically) and render natively as multi-line in XLSX.

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/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/orchestrator/project-initializer.ts

@@ -23,6 +23,37 @@ 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;
+  const block = mobileOnly
+    ? '[mcp_servers.appium-mcp]\ncommand = "npx"\nargs = ["-y", "appium-mcp"]\n'
+    : '[mcp_servers.playwright]\ncommand = "npx"\nargs = ["@playwright/mcp@latest"]\n';
+  if (existing.trim() === '') return CODEX_MCP_HEADER + block;
+  return existing + (existing.endsWith('\n') ? '\n' : '\n\n') + block;
+}
+
 export class ProjectInitializer {
   private baseCwd: string;
   private cwd: string;
@@ -116,6 +147,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 +346,28 @@ 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) {
+      this.skippedItems.push('.codex/config.toml');
+      return;
+    }
+    fs.writeFileSync(filePath, merged, 'utf-8');
+    this.createdItems.push(existed ? '.codex/config.toml (updated)' : '.codex/config.toml');
+  }
+
   /**
    * Add MCP server entries without overwriting user config.
    * Preserves existing entries with the same key — user edits always win.