@sun-asterisk/sungen 3.2.0 → 3.2.2-beta.1

package/dist/orchestrator/templates/specs-pw-shape-reporter.ts

@@ -0,0 +1,92 @@
+/**
+ * WebdriverIO reporter that writes a **Playwright-JSON-shaped** result file per spec, so the
+ * existing sungen delivery/dashboard parser (playwright-report-parser.ts) consumes mobile runs
+ * unchanged. Output: `<genDir>/<basename>-test-result.<platform>[.<SUNGEN_ENV>].json`.
+ *
+ * The `<platform>` segment (android|ios, from the session capabilities) is REQUIRED for dual-target:
+ * with MOBILE_PLATFORM=both one @platform:mobile spec runs on BOTH capabilities — two workers, two
+ * reporter instances — and without a platform component they'd overwrite the same file (the last
+ * platform silently erasing the first). Delivery/dashboard discover per-platform variants.
+ *
+ * Wired in wdio.conf.ts: reporters: ['spec', [PwShapeReporter, {}]].
+ */
+import WDIOReporter from '@wdio/reporter';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+interface Rec { title: string; status: string; error?: string; startTime: string }
+
+export default class PwShapeReporter extends WDIOReporter {
+  private byFeature: Record<string, Rec[]> = {};
+
+  constructor(options: Record<string, unknown>) {
+    super({ ...options, stdout: false });
+  }
+
+  private add(test: { title?: string; parent?: string; error?: { message?: string } }, status: string): void {
+    const feature = test.parent || 'Tests';
+    (this.byFeature[feature] ||= []).push({
+      title: test.title || '',
+      status,
+      error: test.error?.message,
+      startTime: new Date().toISOString(),
+    });
+  }
+
+  onTestPass(test: any): void { this.add(test, 'passed'); }
+  onTestFail(test: any): void { this.add(test, 'failed'); }
+  onTestSkip(test: any): void { this.add(test, 'skipped'); }
+
+  onRunnerEnd(runner: any): void {
+    const specUrl: string | undefined = runner?.specs?.[0];
+    if (!specUrl) return;
+    const specPath = specUrl.startsWith('file:') ? fileURLToPath(specUrl) : specUrl;
+    const dir = path.dirname(specPath);
+    const base = path.basename(specPath).replace(/\.spec\.(ts|js)$/, '');
+    const env = process.env.SUNGEN_ENV;
+
+    // Build the runner label shown as "Test Environment": platform + OS version + the
+    // actual device the test ran on (e.g. "Android 16 (Appium) — emulator-5554"). The
+    // device — not the app activity — is what identifies the test environment.
+    const caps = (runner?.capabilities || {}) as Record<string, unknown>;
+    const cap = (k: string): string | undefined => {
+      const v = caps[k] ?? caps[`appium:${k}`];
+      return typeof v === 'string' && v ? v : typeof v === 'number' ? String(v) : undefined;
+    };
+    const platformName = cap('platformName') || 'Android';
+    // Per-platform filename — each capability's worker writes its OWN file so a both-OS run keeps
+    // both results: <base>-test-result.<android|ios>[.<env>].json
+    const platformSlug = platformName.toLowerCase() === 'ios' ? 'ios' : 'android';
+    const outName = env
+      ? `${base}-test-result.${platformSlug}.${env}.json`
+      : `${base}-test-result.${platformSlug}.json`;
+    const version = cap('platformVersion') || cap('deviceApiLevel');
+    const device = cap('deviceModel') || cap('deviceName') || cap('udid') || cap('deviceUDID');
+    const runnerLabel = `${platformName}${version ? ` ${version}` : ''} (Appium)`;
+    const platform = device ? `${runnerLabel} — ${device}` : runnerLabel;
+    const report = {
+      config: { projects: [{ name: platform }] },
+      suites: Object.entries(this.byFeature).map(([feature, tests]) => ({
+        title: feature,
+        specs: tests.map((t) => ({
+          title: t.title,
+          tests: [
+            {
+              projectName: platform,
+              results: [
+                {
+                  status: t.status,
+                  startTime: t.startTime,
+                  ...(t.error ? { error: { message: t.error } } : {}),
+                },
+              ],
+            },
+          ],
+        })),
+      })),
+    };
+
+    fs.writeFileSync(path.join(dir, outName), JSON.stringify(report, null, 2));
+  }
+}

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

@@ -0,0 +1,295 @@
+/**
+ * WebdriverIO runner config for sungen mobile (Appium) tests.
+ * Mobile equivalent of playwright.config.ts. Run with: npm run test:mobile
+ *
+ * Capabilities default to the app configured at `sungen init --mobile`, but every value can be
+ * overridden at runtime via env vars — no need to edit this file to target another app/device:
+ *   APP_PACKAGE=com.other.app ANDROID_UDID=emulator-5556 npm run test:mobile
+ *   (the launch activity is auto-detected from APP_PACKAGE; set APP_ACTIVITY only to pin a non-standard one)
+ *   APP_APK=/path/to/app.apk npm run test:mobile     # install + run from an .apk (Appium derives pkg/activity)
+ *
+ * iOS Simulator (opt in with MOBILE_PLATFORM=ios; needs Xcode + the xcuitest driver):
+ *   MOBILE_PLATFORM=ios IOS_BUNDLE_ID=com.example.app npm run test:mobile          # app already installed on the sim
+ *   MOBILE_PLATFORM=ios IOS_APP=/path/MyApp.app npm run test:mobile                # Appium installs a Simulator build
+ *   (+ optional IOS_DEVICE='iPhone 16' IOS_VERSION='18.0' IOS_UDID=<sim-udid>)
+ *
+ * The @wdio/appium-service auto-starts a local Appium server (auto-detecting the uiautomator2 / xcuitest driver).
+ */
+/// <reference types="node" />
+/// <reference types="@wdio/globals/types" />
+// Load .env.appium (if present) into process.env FIRST — so every override below (ANDROID_HOME / JAVA_HOME /
+// ANDROID_UDID / APP_PACKAGE / IOS_BUNDLE_ID / MOBILE_PLATFORM / SUNGEN_ENV …) can come from a dedicated
+// .env.appium file instead of shell exports. A separate file (not the generic .env) keeps Appium config from
+// clashing with other .env vars (e.g. FIGMA_PAT). dotenv is a dependency; a missing .env.appium is a no-op.
+import dotenv from 'dotenv';
+dotenv.config({ path: '.env.appium' });
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import PwShapeReporter from './specs/reporters/pw-shape-reporter';
+
+/**
+ * Auto-select MOBILE specs and classify each by its target OS (dual-target routing).
+ *
+ * sungen emits one spec per feature; the test runner differs by platform:
+ *   - mobile/appium specs import from '@wdio/globals'  ← run these with wdio
+ *   - web/playwright specs import from '@playwright/test' ← run those with `playwright test`
+ * The '@wdio/globals' import is the machine-readable "platform = mobile" marker, so we keep
+ * only those files and never feed Playwright specs into the (incompatible) mocha runner.
+ *
+ * Each mobile spec also carries a `// sungen:platform=<mobile|android|ios>` marker (emitted from the
+ * feature's @platform:* tag). It routes the spec per OS:
+ *   - mobile  → cross-platform: runs on BOTH the Android and iOS capability sets
+ *   - android → Android cap only
+ *   - ios     → iOS cap only
+ * A spec with no marker (older codegen) defaults to `mobile` (runs on both) so nothing is dropped.
+ *
+ * Override with SUNGEN_SPECS=<glob-or-path> for a single spec (still classified by its marker).
+ */
+function readPlatformMarker(file: string): 'mobile' | 'android' | 'ios' {
+  try {
+    const m = /sungen:platform=(mobile|android|ios)/.exec(fs.readFileSync(file, 'utf-8'));
+    return (m?.[1] as 'mobile' | 'android' | 'ios') || 'mobile';
+  } catch {
+    return 'mobile';
+  }
+}
+function classifyMobileSpecs(root: string): Array<{ file: string; platform: string }> {
+  if (!fs.existsSync(root)) return [];
+  return (fs.readdirSync(root, { recursive: true }) as string[])
+    .filter((rel) => rel.endsWith('.spec.ts'))
+    .map((rel) => path.join(root, rel))
+    .filter((full) => {
+      try {
+        return fs.readFileSync(full, 'utf-8').includes('@wdio/globals');
+      } catch {
+        return false;
+      }
+    })
+    .map((file) => ({ file, platform: readPlatformMarker(file) }));
+}
+
+const specEntries = process.env.SUNGEN_SPECS
+  ? [process.env.SUNGEN_SPECS].map((file) => ({ file, platform: readPlatformMarker(file) }))
+  : classifyMobileSpecs(path.join(process.cwd(), 'specs', 'generated'));
+
+// Android cap runs android + mobile (everything except ios-only); iOS cap runs ios + mobile.
+const androidSpecs = specEntries.filter((e) => e.platform !== 'ios').map((e) => e.file);
+const iosSpecs = specEntries.filter((e) => e.platform !== 'android').map((e) => e.file);
+const mobileSpecs = specEntries.map((e) => e.file); // union — top-level fallback
+
+// App under test — env overrides the init-configured defaults.
+const APP_PACKAGE = process.env.APP_PACKAGE || '__APP_PACKAGE__';
+const APP_ACTIVITY = process.env.APP_ACTIVITY || '__APP_ACTIVITY__';
+const APP_APK = process.env.APP_APK; // optional: install + launch from an .apk file
+// appActivity is OPTIONAL: UiAutomator2 auto-resolves the package's launcher activity when it's
+// omitted, and the per-scenario relaunch uses activateApp(package) (no activity). So Android needs
+// only APP_PACKAGE — set APP_ACTIVITY only to pin a non-standard launcher. iOS has no activity
+// concept at all (bundleId only). Only pass the cap when APP_ACTIVITY is a real value (not the
+// unfilled scaffold placeholder / empty), so a package-only setup launches cleanly.
+const HAS_REAL_APP_ACTIVITY = !!APP_ACTIVITY && APP_ACTIVITY !== '__APP_ACTIVITY__';
+
+// ── iOS (Simulator) — opt in with MOBILE_PLATFORM=ios; every value is env-overridable ──────────
+//   MOBILE_PLATFORM=ios IOS_BUNDLE_ID=com.example.app npm run test:mobile
+//   - IOS_APP=/path/MyApp.app  → Appium installs a SIMULATOR build (.app or zipped .app) first.
+//                                (A device .ipa won't run on a Simulator — wrong binary/platform.)
+//   - IOS_BUNDLE_ID=com.x      → attach to an app already installed on the sim (simctl install first).
+//   - IOS_DEVICE / IOS_VERSION → pick the simulator; IOS_UDID targets a specific one.
+//
+// MOBILE_PLATFORM selects which capability set(s) run:
+//   android (default) → Android cap only        (runs @platform:android + @platform:mobile specs)
+//   ios               → iOS cap only            (runs @platform:ios + @platform:mobile specs)
+//   both              → BOTH caps in one run     (a @platform:mobile spec executes on each — write once, run both)
+const MOBILE_PLATFORM = (process.env.MOBILE_PLATFORM || 'android').toLowerCase();
+const RUN_ANDROID = MOBILE_PLATFORM === 'android' || MOBILE_PLATFORM === 'both';
+const RUN_IOS = MOBILE_PLATFORM === 'ios' || MOBILE_PLATFORM === 'both';
+const IOS_APP = process.env.IOS_APP;
+const IOS_BUNDLE_ID = process.env.IOS_BUNDLE_ID || '__IOS_BUNDLE_ID__';
+const IOS_DEVICE = process.env.IOS_DEVICE || '__IOS_DEVICE__';
+const IOS_VERSION = process.env.IOS_VERSION || '__IOS_VERSION__';
+// platformVersion is OPTIONAL on a real device: with IOS_UDID set, XCUITest reads the iOS version off
+// the connected device. Only pass the cap when IOS_VERSION is a real value (not the unfilled scaffold
+// placeholder). On a Simulator set it (or IOS_DEVICE) so Appium picks a matching runtime.
+const HAS_REAL_IOS_VERSION = !!IOS_VERSION && IOS_VERSION !== '__IOS_VERSION__';
+const IOS_UDID = process.env.IOS_UDID;
+// Real iPhone (device) — WebDriverAgent must be code-signed onto it. Set IOS_TEAM_ID (your Apple
+// Team ID) to switch the iOS cap into real-device mode; the Simulator ignores these (they're only
+// emitted when IOS_TEAM_ID is present, so Simulator runs are unchanged). For a real device also set
+// IOS_UDID (the device udid, NOT a sim) and the REAL IOS_BUNDLE_ID (Android package ≠ iOS bundle id).
+const IOS_TEAM_ID = process.env.IOS_TEAM_ID;                       // → appium:xcodeOrgId
+const IOS_SIGNING_ID = process.env.IOS_SIGNING_ID || 'Apple Development'; // → appium:xcodeSigningId
+const IOS_WDA_BUNDLE_ID = process.env.IOS_WDA_BUNDLE_ID || 'com.sungen.wda'; // → appium:updatedWDABundleId; default gives WDA a unique id (required for free teams) so you needn't set it
+
+// ── i18n (device locale) ────────────────────────────────────────────────────
+// SUNGEN_ENV doubles as the locale selector (the same var that swaps the test-data overlay).
+// When its value looks like a locale code ("vi", "ja", "vi-VN"), drive the DEVICE locale via
+// appium:language/appium:locale so an app that localizes from device locale on first launch picks
+// it up, and force a data reset (noReset:false) so that first-launch path actually re-runs (clears
+// any persisted in-app language override). Non-locale envs ("staging", "production") are left
+// untouched, so existing suites are unaffected. SUNGEN_LOCALE overrides explicitly when the device
+// locale must differ from the overlay name. Country defaults are used only when the code omits a region.
+const LOCALE_COUNTRY: Record<string, string> = {
+  vi: 'VN',
+  ja: 'JP',
+  en: 'US',
+  ko: 'KR',
+  zh: 'CN',
+  th: 'TH',
+  id: 'ID',
+  fr: 'FR',
+  de: 'DE',
+  es: 'ES',
+  pt: 'BR',
+  ru: 'RU',
+};
+function resolveLocaleCaps(): Record<string, unknown> {
+  const raw = process.env.SUNGEN_LOCALE || process.env.SUNGEN_ENV;
+  if (!raw) return {};
+  const m = /^([a-z]{2})(?:[-_]([A-Za-z]{2}))?$/.exec(raw.trim());
+  if (!m) return {}; // not a locale code (e.g. "staging") → don't touch the device locale
+  const language = m[1];
+  const country = (m[2] || LOCALE_COUNTRY[language] || language).toUpperCase();
+  return {
+    'appium:language': language,
+    'appium:locale': country,
+    'appium:noReset': false,
+  };
+}
+const localeCaps = resolveLocaleCaps();
+
+export const config: WebdriverIO.Config = {
+  runner: 'local',
+  tsConfigPath: './tsconfig.json',
+
+  specs: mobileSpecs,
+  // SUNGEN_MAX_INSTANCES=2 lets a MOBILE_PLATFORM=both run execute the Android and iOS capability
+  // in PARALLEL (separate devices; uiautomator2/XCUITest do not share ports; the reporter writes
+  // per-platform files so results cannot collide). Default stays 1 — serial is the safe choice on
+  // a laptop driving an emulator + a simulator at once.
+  maxInstances: Number(process.env.SUNGEN_MAX_INSTANCES || 1),
+
+  // Global auto-wait for $/$$ matchers (toBeDisplayed, click, …). Default is 3s, too short for a
+  // heavy app's cold (re)launch — each scenario terminates+activates its app, so the first
+  // find/click must wait out the splash/first-frame. 20s keeps slow native/Flutter apps green.
+  waitforTimeout: 20000,
+
+  // Capability set(s) selected by MOBILE_PLATFORM (android | ios | both). Each cap carries its OWN
+  // `specs` (per-OS routing): the Android cap runs android + mobile specs, the iOS cap runs ios +
+  // mobile specs, so MOBILE_PLATFORM=both executes a @platform:mobile spec on each in a single run.
+  // i18n localeCaps (appium:language/locale + noReset:false) apply to both when SUNGEN_ENV is a locale.
+  capabilities: [
+    ...(RUN_ANDROID
+      ? [
+          {
+            platformName: 'Android',
+            'appium:automationName': 'UiAutomator2',
+            '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 } : {}),
+                }),
+            'appium:noReset': true,
+            'appium:autoGrantPermissions': true,
+            'appium:newCommandTimeout': 300,
+            // i18n: when SUNGEN_ENV/SUNGEN_LOCALE is a locale code, this overrides noReset→false and
+            // adds appium:language/appium:locale so the app boots in that locale. Empty otherwise.
+            ...localeCaps,
+            // Per-capability spec routing (supported by WDIO at runtime; not in the TS cap type → cast).
+            specs: androidSpecs,
+          } as any,
+        ]
+      : []),
+    ...(RUN_IOS
+      ? [
+          {
+            platformName: 'iOS',
+            'appium:automationName': 'XCUITest',
+            'appium:deviceName': IOS_DEVICE,
+            // Omit when unknown (real device, no IOS_VERSION) → XCUITest reads it from the device by udid.
+            ...(HAS_REAL_IOS_VERSION ? { 'appium:platformVersion': IOS_VERSION } : {}),
+            // target a specific simulator if given (else Appium uses the matching device/version)
+            ...(IOS_UDID ? { 'appium:udid': IOS_UDID } : {}),
+            // IOS_APP installs a Simulator build (.app/.zip); otherwise attach to an installed bundleId.
+            ...(IOS_APP
+              ? { 'appium:app': IOS_APP }
+              : IOS_BUNDLE_ID
+                ? { 'appium:bundleId': IOS_BUNDLE_ID }
+                : {}),
+            // Real-device WDA signing — emitted only when IOS_TEAM_ID is set (Simulator: omitted → unchanged).
+            ...(IOS_TEAM_ID
+              ? {
+                  'appium:xcodeOrgId': IOS_TEAM_ID,
+                  'appium:xcodeSigningId': IOS_SIGNING_ID,
+                  // Pass -allowProvisioningUpdates -allowProvisioningDeviceRegistration to xcodebuild so it
+                  // auto-creates/refreshes the WDA profile + registers the device (needed for automatic
+                  // signing on a real device; without it WDA build fails fast with "xcodebuild code 65").
+                  'appium:allowProvisioningDeviceRegistration': true,
+                  ...(IOS_WDA_BUNDLE_ID ? { 'appium:updatedWDABundleId': IOS_WDA_BUNDLE_ID } : {}),
+                }
+              : {}),
+            'appium:noReset': true,
+            'appium:newCommandTimeout': 300,
+            ...localeCaps,
+            specs: iosSpecs,
+          } as any,
+        ]
+      : []),
+  ],
+
+  logLevel: 'warn',
+  framework: 'mocha',
+  // 'spec' for console + PwShapeReporter for a Playwright-shaped JSON the delivery/dashboard reuse.
+  reporters: ['spec', [PwShapeReporter, {}]],
+
+  // Auto-start a local Appium server on :4723 (base path '/')
+  services: ['appium'],
+  port: 4723,
+  path: '/',
+
+  mochaOpts: {
+    ui: 'bdd',
+    timeout: 120000,
+  },
+
+  // 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
+  // it and ignores the new device locale, so the i18n run asserts the wrong language. Wipe the app
+  // data via simctl BEFORE the session so first-launch locale detection re-runs. Android needs no
+  // hook (its noReset:false reset works natively).
+  beforeSession: async (_config, capabilities) => {
+    if (Object.keys(localeCaps).length === 0) return; // not a locale run
+    const caps = capabilities as Record<string, unknown>;
+    if (String(caps['platformName'] || '').toLowerCase() !== 'ios') return;
+    const { execSync } = await import('node:child_process');
+    const fsm = await import('node:fs');
+    const udid = (caps['appium:udid'] as string) || 'booted';
+    // Wipe the session-default app AND every per-feature dual-id bundle the worker's specs declare
+    // (__IOS_BUNDLE__ markers) — a multi-app iOS locale run must reset each app, not just the first.
+    const bundleIds = new Set<string>();
+    if (typeof caps['appium:bundleId'] === 'string') bundleIds.add(caps['appium:bundleId'] as string);
+    for (const spec of specs || []) {
+      try {
+        const src = fsm.readFileSync(String(spec).replace('file://', ''), 'utf-8');
+        const m = /__IOS_BUNDLE__ = '([^']+)'/.exec(src);
+        if (m) bundleIds.add(m[1]);
+      } catch { /* unreadable spec — skip */ }
+    }
+    for (const bundleId of bundleIds) {
+      try { execSync(`xcrun simctl terminate ${udid} ${bundleId}`, { stdio: 'ignore' }); } catch { /* not running */ }
+      try {
+        const dataDir = execSync(`xcrun simctl get_app_container ${udid} ${bundleId} data`).toString().trim();
+        if (dataDir) execSync(`rm -rf "${dataDir}/Library" "${dataDir}/Documents"`);
+        console.log(`[sungen] iOS locale run: wiped app data for ${bundleId} (first-launch locale re-detect)`);
+      } catch { /* app not installed yet */ }
+    }
+  },
+
+  // Per-scenario app reset lives in each generated spec's `beforeEach` (terminate+activate the app
+  // from that feature's `Path:`). One run can therefore host screens from different apps — each spec
+  // launches its own — so there's no single-app reset hook here. The capabilities above only bootstrap
+  // the session (default app / device); the real app per scenario comes from the spec.
+};

package/dist/utils/selector-types.d.ts

@@ -2,6 +2,6 @@
  * Valid selector types used across scaffold generator, selector resolver, and validator.
  * Single source of truth — import this instead of hardcoding.
  */
-export declare const VALID_SELECTOR_TYPES: readonly ["placeholder", "role", "testid", "label", "text", "page", "column", "locator", "id", "upload", "frame", "table"];
+export declare const VALID_SELECTOR_TYPES: readonly ["placeholder", "role", "testid", "label", "text", "page", "column", "locator", "id", "upload", "frame", "table", "accessibility-id", "xpath", "android-uiautomator", "ios-predicate"];
 export type SelectorType = (typeof VALID_SELECTOR_TYPES)[number];
 //# sourceMappingURL=selector-types.d.ts.map

package/dist/utils/selector-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"selector-types.d.ts","sourceRoot":"","sources":["../../src/utils/selector-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,oBAAoB,4HAavB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"selector-types.d.ts","sourceRoot":"","sources":["../../src/utils/selector-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,oBAAoB,iMAkBvB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/utils/selector-types.js

@@ -18,5 +18,10 @@ exports.VALID_SELECTOR_TYPES = [
     'upload',
     'frame',
     'table',
+    // === Mobile (Appium) strategies — resolved by the appium adapter (MOB-3) ===
+    'accessibility-id', // cross-platform — Android content-desc / iOS accessibilityIdentifier
+    'xpath', // cross-platform, last resort
+    'android-uiautomator', // Android only — UiSelector expressions
+    'ios-predicate', // iOS only — NSPredicate strings
 ];
 //# sourceMappingURL=selector-types.js.map

package/dist/utils/selector-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"selector-types.js","sourceRoot":"","sources":["../../src/utils/selector-types.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACU,QAAA,oBAAoB,GAAG;IAClC,aAAa;IACb,MAAM;IACN,QAAQ;IACR,OAAO;IACP,MAAM;IACN,MAAM;IACN,QAAQ;IACR,SAAS;IACT,IAAI;IACJ,QAAQ;IACR,OAAO;IACP,OAAO;CACC,CAAC"}
+{"version":3,"file":"selector-types.js","sourceRoot":"","sources":["../../src/utils/selector-types.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACU,QAAA,oBAAoB,GAAG;IAClC,aAAa;IACb,MAAM;IACN,QAAQ;IACR,OAAO;IACP,MAAM;IACN,MAAM;IACN,QAAQ;IACR,SAAS;IACT,IAAI;IACJ,QAAQ;IACR,OAAO;IACP,OAAO;IACP,8EAA8E;IAC9E,kBAAkB,EAAK,sEAAsE;IAC7F,OAAO,EAAgB,8BAA8B;IACrD,qBAAqB,EAAE,wCAAwC;IAC/D,eAAe,EAAQ,iCAAiC;CAChD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.0",
+  "version": "3.2.2-beta.1",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -9,10 +9,10 @@
   },
   "scripts": {
     "build": "rm -rf dist && tsc && npm run copy-templates",
-    "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/ && 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/",
+    "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",
-    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts && tsx tests/capabilities/run.ts && tsx tests/openapi/run.ts && tsx tests/packaging/run.ts",
+    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts && tsx tests/exporter/feature-parser-category.run.ts && tsx tests/exporter/api-detail-sheet.run.ts && tsx tests/api-runtime/base-path-url-join.run.ts && tsx tests/capabilities/run.ts && tsx tests/openapi/run.ts && tsx tests/packaging/run.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"
   },
@@ -33,7 +33,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@sungen/driver-ui": "3.2.0",
+    "@sungen/driver-ui": "3.2.2-beta.1",
     "@anthropic-ai/sdk": "^0.71.0",
     "@babel/parser": "^7.28.5",
     "@babel/traverse": "^7.28.5",

package/src/capabilities/context-router.ts

@@ -20,6 +20,12 @@ export interface RouteTask {
   artifact: string;
   /** Capability tags present on the target (e.g. ['@query'], ['@api'], ['@cases']). */
   tags?: string[];
+  /**
+   * The project's active platform (qa/capabilities.yaml `platform:` — web | mobile | …). A platform
+   * capability (mobile/native) is activated by the project's platform, NOT by a tag, so it is keyed
+   * separately. `web` has no capability id of its own (the in-core default is `ui`) → no-op.
+   */
+  platform?: string;
 }
 
 export interface RoutePlan {
@@ -34,11 +40,17 @@ export interface RoutePlan {
 }
 
 class ContextRouter {
-  /** Which capabilities a set of tags activates: the default capability + any owning a present tag. */
-  capabilitiesFor(tags: string[] = []): string[] {
+  /**
+   * Which capabilities a task activates: the default capability + the active platform's capability
+   * (when one is registered with `id === platform`) + any capability owning a present tag.
+   */
+  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);
     for (const cap of capabilityRegistry.all()) {
       if ((cap.annotations ?? []).some((a) => tags.includes(a))) ids.add(cap.id);
     }
@@ -47,7 +59,7 @@ class ContextRouter {
 
   /** Compute the routing plan for a task (deterministic). */
   route(task: RouteTask): RoutePlan {
-    const capabilities = this.capabilitiesFor(task.tags ?? []);
+    const capabilities = this.capabilitiesFor(task.tags ?? [], task.platform);
     // Generic sensors (no capability, or the always-on `core`) run regardless of the task's tags;
     // capability-specific sensors run only when their capability is in scope.
     const inScope = (capId?: string) => capId == null || capId === 'core' || capabilities.includes(capId);

package/src/capabilities/discover.ts

@@ -23,7 +23,7 @@ import { LOCAL_DRIVERS, registerCoreCapability } from './builtins';
  * move to their packages (R5.5/R5.6) they join this list and leave `LOCAL_DRIVERS`; eventually this
  * becomes a scan of installed `@sungen/driver-*` packages (R5.7).
  */
-const EXTERNAL_DRIVERS = ['@sungen/driver-ui', '@sungen/driver-db', '@sungen/driver-api'];
+const EXTERNAL_DRIVERS = ['@sungen/driver-ui', '@sungen/driver-db', '@sungen/driver-api', '@sungen/driver-mobile'];
 
 function loadExternalDriver(name: string): void {
   // Resolve from the user's PROJECT first, then from core's own location. Opt-in drivers

package/src/cli/commands/audit.ts

@@ -117,11 +117,13 @@ export function registerAuditCommand(program: Command): void {
           console.log(`  Report: ${path.relative(process.cwd(), outPath)}`);
           console.log('');
         }
-        // Non-zero exit when the gate fails — usable in CI / repair loop.
-        process.exit(report.gateStatus === 'FAIL' ? 2 : 0);
+        // Non-zero exit when the gate fails — usable in CI / repair loop. Set exitCode (not
+        // process.exit) so a large --json report on a PIPE fully flushes before the process exits;
+        // process.exit() can truncate buffered stdout mid-write (surfaced by the H3 flowDepth field).
+        process.exitCode = report.gateStatus === 'FAIL' ? 2 : 0;
       } catch (error) {
         console.error('Error:', error instanceof Error ? error.message : error);
-        process.exit(1);
+        process.exitCode = 1;
       }
     });
 }

package/src/cli/commands/delivery.ts

@@ -20,8 +20,8 @@ import {
   renderCsv,
   writeCsv,
 } from '../../exporters/csv-exporter';
-import { renderXlsxMultiSheet, writeXlsx } from '../../exporters/xlsx-exporter';
-import { EnvironmentInfo, PreflightCheck, ScreenSummary, TestCaseRow } from '../../exporters/types';
+import { renderXlsxMultiSheet, writeXlsx, buildApiDetailRows, addApiDetailSheet } from '../../exporters/xlsx-exporter';
+import { EnvironmentInfo, PreflightCheck, ScreenSummary, TestCaseRow, ApiCatalogEntry } from '../../exporters/types';
 
 const COLOR = {
   reset: '\x1b[0m',
@@ -135,6 +135,24 @@ function qaDir(cwd: string, target: DeliveryTarget): string {
   return path.join(cwd, 'qa', qaParent(target.kind), target.screen);
 }
 
+/**
+ * Load the apis.yaml catalog for an api-kind unit.
+ * The catalog lives at qa/api/<screen>/api/apis.yaml.
+ * Returns an empty object when the file is absent (allows graceful degradation).
+ */
+function loadApiCatalog(cwd: string, target: DeliveryTarget): Record<string, ApiCatalogEntry> {
+  if (target.kind !== 'api') return {};
+  const catalogPath = path.join(cwd, 'qa', 'api', target.screen, 'api', 'apis.yaml');
+  if (!fs.existsSync(catalogPath)) return {};
+  try {
+    const parsed = parseYaml(fs.readFileSync(catalogPath, 'utf-8'));
+    if (parsed && typeof parsed === 'object') {
+      return parsed as Record<string, ApiCatalogEntry>;
+    }
+  } catch { /* malformed yaml — skip */ }
+  return {};
+}
+
 function generatedDir(cwd: string, target: DeliveryTarget): string {
   const sub = target.kind === 'flow' ? path.join('flows', target.screen) : target.kind === 'api' ? path.join('api', target.screen) : target.screen;
   return path.join(cwd, 'specs', 'generated', sub);
@@ -411,6 +429,10 @@ async function exportTarget(
     const specLink = fs.existsSync(specMdFile) ? path.relative(cwd, specMdFile) : '';
     const explicitEnv = process.env.SUNGEN_ENV;
 
+    // For api-kind units, load the endpoint catalog so we can add the API detail sheet.
+    const apiCatalog = loadApiCatalog(cwd, target);
+    const hasApiCatalog = target.kind === 'api' && Object.keys(apiCatalog).length > 0;
+
     // Decide between single-locale and aggregated multi-locale flows.
     //   • SUNGEN_ENV set → single locale (existing behaviour, no change)
     //   • SUNGEN_ENV unset → discover every *-test-result*.json variant.
@@ -439,6 +461,10 @@ async function exportTarget(
         { sheetName: 'Auto', summary: buildSummary(label, autoRows, ''), rows: autoRows, specLink },
         { sheetName: 'Manual', summary: buildSummary(label, manualRows, ''), rows: manualRows, specLink },
       ]);
+      // Append the API detail sheet when the unit has a catalog (api-kind only; no-op otherwise).
+      if (hasApiCatalog) {
+        addApiDetailSheet(wb, buildApiDetailRows(apiCatalog, feature.scenarios));
+      }
       await writeXlsx(cwd, target.featureBaseName, wb);
       return buildSummary(label, rows, path.relative(cwd, csvPath));
     }
@@ -496,6 +522,10 @@ async function exportTarget(
       { sheetName: 'Manual', summary: buildSummary(label, manualRows, ''), rows: manualRows, specLink },
     ];
     const wb = renderXlsxMultiSheet(sheets);
+    // Append the API detail sheet when the unit has a catalog (api-kind only; no-op otherwise).
+    if (hasApiCatalog) {
+      addApiDetailSheet(wb, buildApiDetailRows(apiCatalog, feature.scenarios));
+    }
     await writeXlsx(cwd, target.featureBaseName, wb);
 
     return primarySummary ?? buildSummary(label, (autoSheets[0]?.rows ?? []).concat(manualRows), primaryCsvPath);