@sun-asterisk/sungen 3.2.24 → 3.2.25

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

@@ -58,6 +58,124 @@ function substitute(text: string, params: Record<string, any>): string {
 function substituteRaw(text: string, params: Record<string, any>): string {
   return text.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_m, p) => String(params[p] ?? ''));
 }
+
+/** The five predefined XML entities — a bound value containing a bare `&` or `<` would
+ *  otherwise re-create exactly the invalid_xml rejection this encoding exists to avoid. */
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Bind `:param` tokens into an XML string template by WHITELIST of the passed param
+ * names — a generic `:word` scan would mangle namespace prefixes (soapenv:Envelope).
+ * Longest name first + a word-boundary lookahead so `:id` can never eat the prefix
+ * of `:id_2` or the head of `:idx`. Values are XML-escaped by default; a token the
+ * template wraps as `<![CDATA[:param]]>` binds raw inside its CDATA section instead.
+ * Replacer FUNCTIONS everywhere — a value containing `$&`-style sequences must never
+ * be interpreted as a replacement pattern.
+ */
+function bindXmlParams(template: string, params: Record<string, any>): string {
+  let out = template;
+  for (const name of Object.keys(params).sort((a, b) => b.length - a.length)) {
+    const value = String(params[name] ?? '');
+    // A value containing "]]>" would terminate the CDATA section early and ship
+    // malformed XML — split it across two sections so the document stays valid.
+    const cdataSafe = value.split(']]>').join(']]]]><![CDATA[>');
+    out = out.replace(new RegExp(`<!\\[CDATA\\[:${name}\\]\\]>`, 'g'), () => `<![CDATA[${cdataSafe}]]>`);
+    out = out.replace(new RegExp(`:${name}(?![A-Za-z0-9_])`, 'g'), () => escapeXml(value));
+  }
+  return out;
+}
+
+/** Decode an XML-ish response body: Content-Type charset, else the XML declaration's
+ *  encoding (read from an ASCII-compatible prefix), else UTF-8. Unknown charsets fall
+ *  back to UTF-8 rather than failing the whole request. */
+function decodeXmlAwareText(bytes: Buffer, contentType: string): string {
+  // A UTF-16 BOM means the latin1 declaration scan below would see NUL-laden
+  // garbage that still "parses" \u2014 decode by the BOM first.
+  if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe) return new TextDecoder('utf-16le').decode(bytes);
+  if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) return new TextDecoder('utf-16be').decode(bytes);
+  const head = bytes.subarray(0, 200).toString('latin1');
+  const declared = (head.match(/^\uFEFF?\s*<\?xml[^>]*\bencoding=["']([^"']+)["']/i) || [])[1];
+  // Candidates in precedence order; an unsupported CT charset falls back to the
+  // XML declaration's encoding rather than straight to a mojibake UTF-8 decode.
+  const candidates = [(contentType.match(/charset=["']?([^;"'\s]+)/i) || [])[1], declared, 'utf-8'];
+  for (const charset of candidates) {
+    if (!charset) continue;
+    try { return new TextDecoder(charset).decode(bytes); } catch { /* next candidate */ }
+  }
+  return new TextDecoder('utf-8').decode(bytes);
+}
+
+/**
+ * Parse an XML response body to a plain object, or null on a real parse failure (the
+ * caller then keeps the raw string, matching the non-JSON behavior).
+ *
+ * Locked parser posture:
+ *  - processEntities/htmlEntities OFF — fast-xml-parser's entity processing (ON by
+ *    default, including DOCTYPE entities) is exactly the XXE-shaped surface a QA tool
+ *    must not expose to a live server's response. The five predefined entities are
+ *    decoded AFTERWARDS by our own pass.
+ *  - parseTagValue/parseAttributeValue OFF — `<error_code>01000001</error_code>` must
+ *    stay a string; numeric coercion destroys leading zeros.
+ *  - attributes kept with the `@_` prefix (`{{r.body.tag.@_id}}`).
+ *  - repeated elements: XML cannot distinguish "one item" from "a list of one" — the
+ *    catalog declares `arrayPaths:` (dot jpaths INCLUDING the root element) and those
+ *    paths are ALWAYS arrays, so `[0]` access works for 1 and N occurrences alike
+ *    (an EMPTY parent has no child key at all — no array to index).
+ */
+function parseXmlBody(text: string, label: string, arrayPaths?: string[]): any | null {
+  let XMLParser: any;
+  try {
+    // Lazy require: generated projects created before this capability existed don't
+    // have the dep; they must fail with the install command, not MODULE_NOT_FOUND.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    ({ XMLParser } = require('fast-xml-parser'));
+  } catch {
+    throw new Error(`API Driver: ${label} — the response is XML but "fast-xml-parser" is not installed in this project. Run: npm install --save-dev fast-xml-parser`);
+  }
+  const arraySet = new Set(arrayPaths || []);
+  const parser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: '@_',
+    processEntities: false,
+    htmlEntities: false,
+    parseTagValue: false,
+    parseAttributeValue: false,
+    trimValues: true,
+    isArray: (_name: string, jpath: string) => arraySet.has(jpath),
+  });
+  try {
+    return decodeXmlEntitiesDeep(parser.parse(text));
+  } catch {
+    return null;
+  }
+}
+
+/** Decode the five predefined XML entities in every string leaf (`&amp;` last, so a
+ *  literal `&amp;lt;` decodes to `&lt;` and not further). */
+function decodeXmlEntitiesDeep(value: any): any {
+  if (typeof value === 'string') {
+    return value
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&apos;/g, "'")
+      .replace(/&amp;/g, '&');
+  }
+  if (Array.isArray(value)) return value.map(decodeXmlEntitiesDeep);
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, any> = {};
+    for (const [k, v] of Object.entries(value)) out[k] = decodeXmlEntitiesDeep(v);
+    return out;
+  }
+  return value;
+}
 /** 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 fetch own the header (multipart boundary). */
@@ -94,7 +212,11 @@ function loadStorageStateCookieHeader(storageStatePath: string, url: string): st
   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}`);
+    // A cookie with NO domain must match nothing, not everything — Playwright
+    // always records a domain, so a domainless entry only comes from a hand-
+    // edited state file, and treating it as a wildcard would attach the session
+    // cookie to any origin a response-bound absolute URL points at.
+    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,
@@ -201,22 +323,72 @@ class ApiClient {
    */
   async call(
     label: string,
-    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart'; files?: Record<string, FileSpec | FileSpec[]>; bodyFile?: FileSpec; headers?: Record<string, string>; timeout?: number; datasource?: string },
+    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart' | 'xml'; files?: Record<string, FileSpec | FileSpec[]>; bodyFile?: FileSpec; headers?: Record<string, string>; timeout?: number; datasource?: string; arrayPaths?: string[] },
     params: Record<string, any> = {},
     opts: { storageState?: string } = {},
   ): Promise<{ status: number; ok: boolean; body: any; headers: Record<string, string> }> {
     const { conf } = this.cfg(req.datasource);
     const base = (conf.base_url || conf.baseUrl || '').replace(/\/$/, '');
     if (!base) throw new Error(`API Driver: ${label} — datasource has no base_url (set it in .env.qa).`);
-    const urlPath = substitute(req.path, params);   // path params (:id) bind at runtime
 
-    const headers: Record<string, string> = { ...(conf.headers || {}) };
+    // Whole-token path (`path: ":url"`): bind RAW and use an absolute http(s)
+    // value directly — an export/download link returned by a prior response
+    // (often on another origin, e.g. blob storage). substitute() would percent-
+    // encode the whole URL into `https%3A%2F%2F…` and joinApiUrl would glue it
+    // onto base_url. Raw binding also keeps presigned query escapes (%2F)
+    // untouched; new URL() is used for VALIDATION only (a response value can be
+    // anything — file:/data: schemes are refused, never fetched).
+    let fullUrl: string;
+    let absolute = false;
+    const wholeToken = req.path.match(/^:([A-Za-z_][A-Za-z0-9_]*)$/);
+    if (wholeToken) {
+      // The bound value MUST be an absolute http(s) URL. Anything else — empty
+      // string (a broken export returning {"url":""}), a relative path, or a
+      // data:/mailto:/file: form — is refused loudly: falling through to the
+      // legacy base_url join would silently GET the API root and let the
+      // scenario false-pass on exactly the failure it exists to catch. (A
+      // whole-token path was never valid before this feature, so there is no
+      // legacy behavior to preserve.)
+      const wholeVal = String(params[wholeToken[1]] ?? '');
+      let parsed: URL | null = null;
+      if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(wholeVal)) {
+        try { parsed = new URL(wholeVal); } catch { parsed = null; }
+      }
+      if (!parsed || (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')) {
+        throw new Error(`API Driver: ${label} — :${wholeToken[1]} must be an absolute http(s) URL (the value is bound from a live response); got: ${JSON.stringify(wholeVal)}`);
+      }
+      if (parsed.username || parsed.password) {
+        throw new Error(`API Driver: ${label} — :${wholeToken[1]} must not carry credentials (user:pass@host): fetch refuses such URLs.`);
+      }
+      // Raw string, not parsed.toString(): URL normalization could rewrite the
+      // presigned query escapes (%2F) the storage host signed.
+      fullUrl = wholeVal;
+      absolute = true;
+    } else if (/^https?:\/\//i.test(req.path)) {
+      // Literal absolute catalog path — its :params (if any) bind with the normal encoding.
+      fullUrl = substitute(req.path, params);
+      absolute = true;
+    } else {
+      fullUrl = joinApiUrl(base, substitute(req.path, params));   // path params (:id) bind at runtime
+    }
+
+    // Cross-origin absolute URL: the datasource's own headers must NOT travel to
+    // another origin — auth tokens, cookies and tenant keys live in conf.headers
+    // with no metadata separating them from benign defaults, so ALL of them stay
+    // home; only headers declared on the entry itself are sent. An unparseable
+    // base counts as a different origin (fail closed).
+    const sameOrigin = !absolute || (() => {
+      try { return new URL(fullUrl).origin === new URL(base).origin; } catch { return false; }
+    })();
+    const headers: Record<string, string> = sameOrigin ? { ...(conf.headers || {}) } : {};
     // catalog headers; :param tokens bind at runtime — raw (no URL-encoding, unlike the path)
     for (const [k, v] of Object.entries(req.headers || {}))
       headers[k] = substituteRaw(String(v), params);
     // Body: substitute `:param` into the body template (object values), then encode per `encoding`.
+    // An XML body is a raw STRING template and binds by param-name WHITELIST below —
+    // the generic whole-value substitution here must not touch it.
     let body: any;
-    if (req.body !== undefined && req.body !== null) {
+    if (req.body !== undefined && req.body !== null && req.encoding !== 'xml') {
       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 a fetch request body (#345): json → JSON string (application/json,
@@ -244,6 +416,17 @@ class ApiClient {
       // drop any datasource default Content-Type so it doesn't conflict with / duplicate it.
       deleteHeader(headers, 'content-type');
       fetchBody = buildMultipart(req.files, body, params, label);
+    } else if (req.encoding === 'xml' && req.body !== undefined && req.body !== null) {
+      // XML body: the catalog carries a raw string template (any shape — attributes,
+      // namespaces, CDATA, nesting). :params bind by WHITELIST of the passed param
+      // names, never by a generic `:word` scan — that scan would mangle namespace
+      // prefixes (soapenv:Envelope, xsi:type) into bound values. A BODYLESS xml
+      // entry is fine — a GET whose xml RESPONSE needs arrayPaths carries no body.
+      if (typeof req.body !== 'string') {
+        throw new Error(`API Driver: ${label} — encoding: xml requires body: to be a string template (a YAML block scalar holding the raw XML).`);
+      }
+      fetchBody = bindXmlParams(req.body, params);
+      if (!hasHeader(headers, 'content-type')) headers['content-type'] = 'application/xml';
     } else if (body !== undefined) {
       const enc = req.encoding ?? 'json';
       if (enc === 'form') {
@@ -266,9 +449,6 @@ class ApiClient {
       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.
@@ -292,9 +472,32 @@ class ApiClient {
         ...(fetchBody !== undefined ? { body: fetchBody } : {}),
         signal: controller.signal,
       });
-      const text = await res.text();
+      // Read bytes, not res.text(): the fetch spec hard-decodes text() as UTF-8, so a
+      // Shift_JIS/ISO-8859-1 XML response (common from OTA backends) would mojibake
+      // silently. XML-ish responses decode by Content-Type charset, then the XML
+      // declaration's encoding, then UTF-8; everything else keeps the UTF-8 decode
+      // res.text() always performed.
+      const bytes = Buffer.from(await res.arrayBuffer());
+      const contentType = res.headers.get('content-type') || '';
+      // XML detection: an explicit xml Content-Type (text/xml, application/xml,
+      // application/soap+xml — never text/html), else — only when the CT is absent or
+      // octet-stream — a sniff REQUIRING the `<?xml` declaration. Never sniff on a bare
+      // `<`: the parser does not validate, so an HTML 502 page would come back as a
+      // junk object instead of the raw string an author can at least read.
+      const ctIsXml = /xml/i.test(contentType) && !/html/i.test(contentType);
+      const maySniff = !contentType || /octet-stream/i.test(contentType);
+      // Non-XML branch uses TextDecoder, NOT Buffer.toString: the fetch spec's
+      // "UTF-8 decode" (what res.text() did) STRIPS a leading BOM, and a BOM'd
+      // JSON response must keep parsing as an object exactly as before.
+      const text = ctIsXml || maySniff ? decodeXmlAwareText(bytes, contentType) : new TextDecoder('utf-8').decode(bytes);
+      const isXml = (ctIsXml || (maySniff && /^\uFEFF?\s*<\?xml/.test(text))) && text.length > 0;
       let parsed: any = text;
-      try { parsed = text ? JSON.parse(text) : null; } catch { /* non-JSON → keep text */ }
+      if (isXml) {
+        const xml = parseXmlBody(text, label, req.arrayPaths);
+        parsed = xml !== null ? xml : text; // real parse failure → keep the raw string
+      } else {
+        try { parsed = text ? JSON.parse(text) : null; } catch { /* non-JSON → keep text */ }
+      }
       return { status: res.status, ok: res.ok, body: parsed, headers: Object.fromEntries(res.headers.entries()) };
     } finally {
       clearTimeout(timer);
@@ -310,7 +513,7 @@ class ApiClient {
    */
   async callN(
     label: string,
-    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart'; files?: Record<string, FileSpec | FileSpec[]>; bodyFile?: FileSpec; headers?: Record<string, string>; timeout?: number; datasource?: string },
+    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart' | 'xml'; files?: Record<string, FileSpec | FileSpec[]>; bodyFile?: FileSpec; headers?: Record<string, string>; timeout?: number; datasource?: string; arrayPaths?: string[] },
     params: Record<string, any> = {},
     n = 1,
     opts: { storageState?: string } = {},

package/dist/orchestrator/templates/specs-regex-escape.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Sungen regex-escape helper — auto-generated into specs/regex-escape.ts. DO NOT EDIT.
+ *
+ * Test-data values are LITERAL TEXT. When a generated assertion needs an anchored
+ * match (`filter({ hasText: /^…$/ })`), the runtime value is interpolated into a
+ * `new RegExp(...)` — so a value containing `( [ $ . * +` would either throw a
+ * SyntaxError or silently match the wrong element unless it is escaped HERE, at
+ * runtime, where the real value is finally known. Template-time escaping cannot do
+ * this: at generate time the value is still a placeholder marker.
+ */
+/** Escape a runtime string so RegExp treats every character literally. */
+export declare function escapeRegExp(text: string): string;
+//# sourceMappingURL=specs-regex-escape.d.ts.map

package/dist/orchestrator/templates/specs-regex-escape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"specs-regex-escape.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-regex-escape.ts"],"names":[],"mappings":"AACA;;;;;;;;;GASG;AAEH,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD"}

package/dist/orchestrator/templates/specs-regex-escape.js

@@ -0,0 +1,19 @@
+"use strict";
+/* eslint-disable */
+/**
+ * Sungen regex-escape helper — auto-generated into specs/regex-escape.ts. DO NOT EDIT.
+ *
+ * Test-data values are LITERAL TEXT. When a generated assertion needs an anchored
+ * match (`filter({ hasText: /^…$/ })`), the runtime value is interpolated into a
+ * `new RegExp(...)` — so a value containing `( [ $ . * +` would either throw a
+ * SyntaxError or silently match the wrong element unless it is escaped HERE, at
+ * runtime, where the real value is finally known. Template-time escaping cannot do
+ * this: at generate time the value is still a placeholder marker.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeRegExp = escapeRegExp;
+/** Escape a runtime string so RegExp treats every character literally. */
+function escapeRegExp(text) {
+    return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=specs-regex-escape.js.map

package/dist/orchestrator/templates/specs-regex-escape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specs-regex-escape.js","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-regex-escape.ts"],"names":[],"mappings":";AAAA,oBAAoB;AACpB;;;;;;;;;GASG;;AAGH,oCAEC;AAHD,0EAA0E;AAC1E,SAAgB,YAAY,CAAC,IAAY;IACvC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AAC7D,CAAC"}

package/dist/orchestrator/templates/specs-regex-escape.ts

@@ -0,0 +1,16 @@
+/* eslint-disable */
+/**
+ * Sungen regex-escape helper — auto-generated into specs/regex-escape.ts. DO NOT EDIT.
+ *
+ * Test-data values are LITERAL TEXT. When a generated assertion needs an anchored
+ * match (`filter({ hasText: /^…$/ })`), the runtime value is interpolated into a
+ * `new RegExp(...)` — so a value containing `( [ $ . * +` would either throw a
+ * SyntaxError or silently match the wrong element unless it is escaped HERE, at
+ * runtime, where the real value is finally known. Template-time escaping cannot do
+ * this: at generate time the value is still a placeholder marker.
+ */
+
+/** Escape a runtime string so RegExp treats every character literally. */
+export function escapeRegExp(text: string): string {
+  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/orchestrator/templates/specs-test-data.ts

@@ -50,16 +50,42 @@ export class TestDataLoader {
     if (value === undefined || value === null) {
       throw new Error(`Test data key not found: ${key}`);
     }
-    // A projected array (e.g. `{{q.rows[*].name}}`) serializes as a JSON list so the full
-    // ordered set is preserved for the assert-compare — String([...]) would flatten it to a
-    // lossy comma-join that can't be distinguished from a scalar containing commas.
-    const result = Array.isArray(value)
-      ? this.interpolate(JSON.stringify(value))
+    // A projected array (e.g. `{{q.rows[*].name}}`) and a PLAIN object (an API response
+    // body) serialize as JSON text — String([...]) flattens to a lossy comma-join and
+    // String({}) is "[object Object]", both un-assertable. Embedded `{{ref}}`s interpolate
+    // INSIDE the value before stringify, so a ref carrying quotes/backslashes can never
+    // corrupt the serialized JSON (the old order substituted raw text into JSON text).
+    // Only PLAIN objects take this path: Date/Buffer/ObjectId values bound by @query from
+    // a real driver keep their String()/toString() output — JSON.stringify would wrap a
+    // Date in quotes and flip every assertion that already compares its string form.
+    const result = isJsonContainer(value)
+      ? JSON.stringify(this.interpolateDeep(value))
       : this.interpolate(String(value));
     assertNoUnresolvedEnvRef(key, result);
     return result;
   }
 
+  /**
+   * Interpolate `{{ref}}`s in every string leaf AND key of a JSON container,
+   * recursively (matching the old whole-JSON-text pass). Non-plain nested
+   * objects are passed through untouched — JSON.stringify serializes them via
+   * toJSON. A truly cyclic object throws a RangeError; every current bind
+   * source (JSON.parse output, DB rows, YAML after load-time resolution) is
+   * acyclic. Built with Object.fromEntries, which DEFINES data properties — a
+   * body field literally named "__proto__" survives instead of silently
+   * rewiring the result's prototype to external input.
+   */
+  private interpolateDeep(value: any): any {
+    if (typeof value === 'string') return this.interpolate(value);
+    if (Array.isArray(value)) return value.map((v) => this.interpolateDeep(v));
+    if (isPlainObject(value)) {
+      return Object.fromEntries(
+        Object.entries(value).map(([k, v]) => [this.interpolate(k), this.interpolateDeep(v)])
+      );
+    }
+    return value;
+  }
+
   /**
    * Resolve a key to its RAW, uncoerced value (array/object/number kept as-is) — for binding
    * DB query / API request params, where type-strict sinks (MySQL numeric columns, MongoDB,
@@ -68,7 +94,8 @@ export class TestDataLoader {
    * as get()), so an override like `token={{login.body.token}}` or `id={{prefix}}-001` still
    * interpolates — only the final scalar/array/object type is preserved uncoerced. Arrays and
    * objects are returned as-is; refs embedded inside their elements are not interpolated (unlike
-   * get()'s JSON-text pass), since raw() callers bind structured values directly, not text.
+   * get(), which interpolates every string leaf of a plain container before serializing), since
+   * raw() callers bind structured values directly, not text.
    * Throws on missing, mirroring get()'s guard.
    */
   raw(key: string): any {
@@ -202,6 +229,26 @@ export class TestDataLoader {
   }
 }
 
+/**
+ * A value get() must serialize as JSON: an array, or a PLAIN object (literal or
+ * null-prototype). Class instances at the TOP level (Date, Buffer, ObjectId…,
+ * and driver row wrappers like mysql2's RowDataPacket) are NOT containers —
+ * they keep the String()/toString() path their existing assertions rely on;
+ * nested inside a plain container they serialize through JSON.stringify/toJSON.
+ */
+function isJsonContainer(value: any): boolean {
+  return Array.isArray(value) || isPlainObject(value);
+}
+
+// Prototype check only — a `value.constructor === Object` probe is defeated by
+// a body FIELD literally named "constructor" (JSON.parse gives it as an own
+// property), which would silently fall back to "[object Object]" again.
+function isPlainObject(value: any): boolean {
+  if (value === null || typeof value !== 'object') return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
 function loadYamlSync(filePath: string): Record<string, any> | null {
   if (!fs.existsSync(filePath)) return null;
   const content = fs.readFileSync(filePath, 'utf-8');

package/dist/orchestrator/templates/wdio.conf.ts

@@ -233,6 +233,25 @@ function restoreConnectivity(hook: string): void {
   console.log('[sungen] connectivity self-heal: no ICMP reply within ~30s — continuing (fine if this network blocks ping; otherwise the device may need a cold boot).');
 }
 
+// Evidence readability: render a dot at every injected tap so screen recordings show WHERE the
+// test touched. Android-only (iOS has no supported equivalent). The pre-run value is remembered
+// and restored on onComplete, so a developer's own device setting is not permanently mutated.
+let showTouchesBefore: string | null = null;
+function setShowTouches(hook: 'onPrepare' | 'onComplete'): void {
+  if (!RUN_ANDROID) return;
+  const adbBin = process.env.ANDROID_HOME ? path.join(process.env.ANDROID_HOME, 'platform-tools', 'adb') : 'adb';
+  const adb = `"${adbBin}" -s ${process.env.ANDROID_UDID || '__ANDROID_UDID__'} shell`;
+  const sh = (cmd: string) => execSync(`${adb} ${cmd}`, { timeout: 10000, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+  try {
+    if (hook === 'onPrepare') {
+      showTouchesBefore = sh('settings get system show_touches');
+      if (showTouchesBefore !== '1') sh('settings put system show_touches 1');
+    } else if (showTouchesBefore !== null && showTouchesBefore !== '1') {
+      sh(`settings put system show_touches ${showTouchesBefore === 'null' ? '0' : showTouchesBefore}`);
+    }
+  } catch { /* device gone / key absent — cosmetic feature, never block the run */ }
+}
+
 export const config: WebdriverIO.Config = {
   runner: 'local',
   tsConfigPath: './tsconfig.json',
@@ -265,13 +284,13 @@ export const config: WebdriverIO.Config = {
             'appium:udid': process.env.ANDROID_UDID || '__ANDROID_UDID__',
             // APP_APK installs from a file (Appium reads pkg/activity from the manifest);
             // otherwise target an already-installed app by package + activity.
-            ...(APP_APK
-              ? { 'appium:app': APP_APK }
-              : {
-                  'appium:appPackage': APP_PACKAGE,
-                  // Omit when unset → UiAutomator2 launches the package's default launcher activity.
-                  ...(HAS_REAL_APP_ACTIVITY ? { 'appium:appActivity': APP_ACTIVITY } : {}),
-                }),
+            ...(APP_APK ? { 'appium:app': APP_APK } : {}),
+            // Explicit APP_PACKAGE/APP_ACTIVITY are passed even alongside APP_APK: the driver's
+            // APK-manifest parse can flake (empty activity → bare MAIN/LAUNCHER intent, which
+            // Android rejects as "matches multiple activities"), and explicit caps override it.
+            ...(process.env.APP_PACKAGE || !APP_APK ? { 'appium:appPackage': APP_PACKAGE } : {}),
+            // Omit when unset → UiAutomator2 launches the package's default launcher activity.
+            ...(HAS_REAL_APP_ACTIVITY ? { 'appium:appActivity': APP_ACTIVITY } : {}),
             'appium:noReset': true,
             'appium:autoGrantPermissions': true,
             'appium:newCommandTimeout': 300,
@@ -385,8 +404,8 @@ export const config: WebdriverIO.Config = {
   // Connectivity self-heal (#615): onPrepare heals a device wedged by a previous KILLED run
   // (its onComplete never fired) before the session starts; onComplete restores after this run,
   // pass or fail. Both run in the launcher process, so they fire even when the worker/session died.
-  onPrepare: () => restoreConnectivity('onPrepare'),
-  onComplete: () => restoreConnectivity('onComplete'),
+  onPrepare: () => { restoreConnectivity('onPrepare'); setShowTouches('onPrepare'); },
+  onComplete: () => { restoreConnectivity('onComplete'); setShowTouches('onComplete'); },
 
   // iOS + locale: XCUITest's `noReset:false` does NOT actually clear the app's data container
   // (verified live 2026-06-11) — a Flutter app that persisted its language on a previous launch keeps

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.24",
+  "version": "3.2.25",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,6 +12,7 @@
     "copy-templates": "mkdir -p dist/generators/test-generator/adapters/playwright/templates/steps && mkdir -p dist/generators/test-generator/templates && mkdir -p dist/orchestrator/templates && mkdir -p dist/dashboard/templates && cp -r src/generators/test-generator/adapters/playwright/templates/*.hbs dist/generators/test-generator/adapters/playwright/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/playwright/templates/steps dist/generators/test-generator/adapters/playwright/templates/ && mkdir -p dist/generators/test-generator/adapters/appium/templates/steps && cp -r src/generators/test-generator/adapters/appium/templates/*.hbs dist/generators/test-generator/adapters/appium/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/appium/templates/steps dist/generators/test-generator/adapters/appium/templates/ && cp src/generators/test-generator/templates/*.hbs dist/generators/test-generator/templates/ 2>/dev/null || true && cp -r src/orchestrator/templates/* dist/orchestrator/templates/ && cp src/dashboard/templates/index.html dist/dashboard/templates/index.html && mkdir -p dist/harness/catalog && cp src/harness/catalog/*.yaml dist/harness/catalog/",
     "build:dashboard": "cd ../../dashboard && npm install --silent && npm run build && cd - && cp ../../dashboard/dist/index.html src/dashboard/templates/index.html",
     "dev": "tsx src/cli/index.ts",
+    "gen:step-matrix": "tsx tools/step-support-matrix/index.ts",
     "test": "tsx tests/run-all.ts",
     "test:update": "tsx tests/golden/run.ts --update && tsx tests/audit/run.ts --update && tsx tests/ingest/run.ts --update",
     "prepublishOnly": "npm run build:dashboard && npm run build"
@@ -39,8 +40,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.2.24",
-    "@sungen/driver-ui": "3.2.24",
+    "@sungen/driver-data-factory": "3.2.25",
+    "@sungen/driver-ui": "3.2.25",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",
@@ -66,9 +67,10 @@
     "LICENSE"
   ],
   "devDependencies": {
-    "mysql2": "^3",
-    "mongodb": "^7",
     "@aws-sdk/client-dynamodb": "^3",
-    "@aws-sdk/lib-dynamodb": "^3"
+    "@aws-sdk/lib-dynamodb": "^3",
+    "fast-xml-parser": "^5.3.3",
+    "mongodb": "^7",
+    "mysql2": "^3"
   }
 }

package/src/capabilities/context-router.ts

@@ -46,11 +46,19 @@ class ContextRouter {
    */
   capabilitiesFor(tags: string[] = [], platform?: string): string[] {
     const ids = new Set<string>();
-    const def = capabilityRegistry.defaultCapabilityId();
-    if (def) ids.add(def);
-    // A platform capability (mobile/native/…) is activated by the project's platform, not by a tag.
-    // `web` has no capability of its own → falls through to the default `ui` (byte-identical).
-    if (platform && capabilityRegistry.get(platform)) ids.add(platform);
+    // A platform capability (mobile/native/…) is activated by the project's platform, not by a tag,
+    // and it REPLACES the default rather than stacking on it. The default `ui` exists because `web`
+    // has no capability of its own; when a real platform capability is active, its gate is the one
+    // that applies. Adding both meant a mobile project ran `ui-viewpoint` AND `mobile-viewpoint` —
+    // two sensors emitting the same UNIVERSAL finding, so every mobile audit printed it twice while
+    // web printed it once (#626). Scoring already resolved this the same way
+    // (`scoringCapabilityFor` prefers the platform over the default).
+    const platformCap = platform && capabilityRegistry.get(platform) ? platform : undefined;
+    if (platformCap) ids.add(platformCap);
+    else {
+      const def = capabilityRegistry.defaultCapabilityId();
+      if (def) ids.add(def);
+    }
     for (const cap of capabilityRegistry.all()) {
       if ((cap.annotations ?? []).some((a) => tags.includes(a))) ids.add(cap.id);
     }

package/src/cli/commands/capability.ts

@@ -9,43 +9,9 @@ import {
 import { buildPlan, MANUAL_REASONS } from '../../harness/capability-plan';
 import { adapterRegistry } from '../../generators/test-generator/adapters';
 import { emitMobileRuntime, installMobileDriver } from '../../orchestrator/mobile-runtime-scaffolder';
+import { coreVersion, resolveDriverVersion } from '../../orchestrator/lockstep-version';
 import { findUnitDir, resolveUnit } from '../resolve-unit';
 
-/** The running CLI's (core) version — opt-in drivers install in lockstep with it (not `@latest`). */
-function coreVersion(): string {
-  try { return require('../../../package.json').version || 'latest'; } catch { return 'latest'; }
-}
-
-/**
- * Resolve the driver version to install for the running core `core`.
- *
- * Lockstep wants the EXACT `core` version. But the beta channel publishes `<core>-beta.N` before a
- * stable `<core>` ever exists — so a released core (e.g. 3.2.10) asking for `@3.2.10` hits ETARGET
- * out-of-the-box when npm only has `3.2.10-beta.2` (`sungen capability add` then fails for a fresh
- * user). Fall back on the SAME version line: prefer exact `core`, else the highest `core-beta.N`,
- * else the `beta` dist-tag as a last resort. Keeps the driver's pinned core-dep on the same line.
- */
-function resolveDriverVersion(pkg: string, core: string): string {
-  if (core === 'latest') return 'beta';
-  try {
-    const out = spawnSync('npm', ['view', pkg, 'versions', '--json'], { encoding: 'utf-8', shell: true });
-    if (out.status !== 0 || !out.stdout) return core; // can't query → let the exact install try/fail
-    let versions: string[] = [];
-    const parsed = JSON.parse(out.stdout);
-    versions = Array.isArray(parsed) ? parsed : [parsed];
-    if (versions.includes(core)) return core; // exact exists → lockstep
-    const prefix = `${core}-beta.`;
-    const betas = versions
-      .filter((v) => typeof v === 'string' && v.startsWith(prefix))
-      .map((v) => parseInt(v.slice(prefix.length), 10))
-      .filter((n) => Number.isInteger(n));
-    if (betas.length) return `${core}-beta.${Math.max(...betas)}`; // highest same-line prerelease
-    return 'beta'; // nothing on this line → newest beta dist-tag
-  } catch {
-    return core;
-  }
-}
-
 /**
  * Add `test:mobile` to the project's package.json scripts (if absent).
  * Idempotent — skips if the script is already set.
@@ -140,7 +106,7 @@ export function registerCapabilityCommand(program: Command): void {
         const resolved = resolveUnit(o.screen);
         if (!resolved) throw new Error(`Screen/flow not found: qa/screens/${o.screen} or qa/flows/${o.screen}`);
         // The catalog unit id carries the unit KIND, which gates which drivers can serve it.
-        const plan = buildPlan(resolved.dir, o.screen, resolved.unitId);
+        const plan = buildPlan(resolved.dir, o.screen, resolved.unitId, readCapabilities(process.cwd()).platform);
 
         const outDir = path.join(process.cwd(), '.sungen', 'reports');
         fs.mkdirSync(outDir, { recursive: true });
@@ -166,9 +132,9 @@ export function registerCapabilityCommand(program: Command): void {
           }
         }
         if (plan.unavailable.length) {
-          L('  Cannot help here (driver does not support this unit kind — do NOT install):');
+          L('  Cannot help here (driver cannot serve this unit kind or platform — do NOT install):');
           for (const r of plan.unavailable) {
-            L(`     • ${r.count} @manual:${r.reason} → \`${r.driver}\` has no ${r.unitKind} support; automate the behaviour on the owning SCREEN unit instead`);
+            L(`     • ${r.count} @manual:${r.reason} → \`${r.driver}\` ${r.why}`);
           }
         }
         if (plan.keep.length) {