@sungen/driver-mobile 3.2.2-beta.13

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@sungen/driver-mobile",
+  "version": "3.2.2-beta.13",
+  "description": "Sungen mobile platform driver (Appium / WebdriverIO) — gesture vocabulary, mobile selector strategies, viewpoint gate, and the WDIO runner. Plugs into @sun-asterisk/sungen via the capability SPI.",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "sungen": {
+    "capability": "mobile"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json"
+  },
+  "author": "eqe team (engineer & quality) — Sun Asterisk",
+  "license": "MIT",
+  "dependencies": {
+    "@sun-asterisk/sungen": "3.2.2-beta.13",
+    "@wdio/appium-service": "^9.0.0",
+    "@wdio/cli": "^9.0.0",
+    "@wdio/local-runner": "^9.0.0",
+    "@wdio/mocha-framework": "^9.0.0",
+    "@wdio/spec-reporter": "^9.0.0",
+    "appium": "^3.0.0",
+    "webdriverio": "^9.0.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,87 @@
+/**
+ * @sungen/driver-mobile — the MOBILE platform driver (Appium / WebdriverIO).
+ *
+ * The mobile mirror of @sungen/driver-ui (web). Core loads this at runtime via
+ * `sungenDriver.register` when a project's `qa/capabilities.yaml` has `platform: mobile`
+ * (`sungen capability add mobile`); core never imports this package statically — the
+ * mobile runtime (webdriverio/appium) lives only in the emitted project + this driver's
+ * peerDependencies, never in core.
+ *
+ * Phased build — see docs/spec/sungen_driver_mobile_spec.md:
+ *   MOB-1: capability registration + package scaffold.
+ *   MOB-2: the Appium codegen adapter (core adapterRegistry, `mobile`). The runtime files
+ *          (wdio.conf.ts, specs/reporters/pw-shape-reporter.ts, .env.appium) are emitted into
+ *          the target project by mobile-runtime-scaffolder.ts (called by `sungen init --mobile`
+ *          and `sungen capability add mobile`), NOT via the runtimeHelpers SPI. The reporter is
+ *          project-level config, emitted once — not per-generate.
+ *   MOB-3: mobile selector strategies + gesture step patterns.
+ *   MOB-4 (here): harness parity — gesture patterns + gate sensor + discovery/contextMapper.
+ *   MOB-5: mobile AI skills (gestures / capture / selector-fix).
+ *
+ * Mobile is UI-flavoured (screens, interactions, assertions), so it is scored by the SAME
+ * coverage + assertion-depth gate as web. That gate is deliberately NOT re-implemented or
+ * re-imported here. The audit engine runs its OWN in-core viewpointGate + assertionDepth over
+ * the project's catalog, passing isMobile=true for a `platform: mobile` project (so a launcher
+ * resolves to a `mobile-*` page-type, never a web one). NOT exposing `viewpoints`/`gateProvider`
+ * keeps the score-bearing gate + catalog sourced from the RUNNING core — never from a separately
+ * resolved `@sun-asterisk/sungen` copy nested under this package, which could be an older published
+ * build whose catalog predates `mobile-home` and would silently drift the score (version-skew).
+ * Only the runtime (Appium) differs, and that lives in the adapter (MOB-2), not the gate.
+ */
+import type {
+  CapabilityRegistry,
+  Sensor,
+  GateInput,
+  DiscoveryProvider,
+  ContextMapper,
+  GenerationUnit,
+} from '@sun-asterisk/sungen';
+import { gesturePatterns } from './patterns/gesture-patterns';
+
+/** Surfaces universal-viewpoint theme gaps (low-priority reminder; does not move the score). */
+const mobileViewpointGateSensor: Sensor<GateInput> = {
+  id: 'mobile-viewpoint',
+  capability: 'mobile',
+  kind: 'gate',
+  run: ({ universalGaps }) =>
+    universalGaps && universalGaps.length
+      ? [{ sensorId: 'mobile-viewpoint', capability: 'mobile', message: `UNIVERSAL: missing theme(s): ${universalGaps.join(', ')} (low priority reminder).`, severity: 'info' }]
+      : [],
+};
+
+const mobileDiscovery: DiscoveryProvider = {
+  appliesTo: (t) => t.kind === 'screen' || t.kind === 'flow',
+  discover: async (target) => ({ target: { ...target, capability: 'mobile' }, sources: {}, facts: {} }),
+};
+
+const mobileContextMapper: ContextMapper = {
+  decompose: (ctx) => {
+    const f = (ctx.facts || {}) as { screens?: unknown[]; flows?: unknown[] };
+    const units: GenerationUnit[] = [];
+    for (const s of f.screens ?? []) units.push({ mode: 'screen', targetSlice: s });
+    for (const fl of f.flows ?? []) units.push({ mode: 'flow', targetSlice: fl });
+    if (!units.length) units.push({ mode: ctx.target.kind === 'flow' ? 'flow' : 'screen', targetSlice: ctx.target });
+    return units;
+  },
+};
+
+export function register(registry: CapabilityRegistry): void {
+  registry.register({
+    id: 'mobile',
+    annotations: [],
+    patterns: [
+      ...gesturePatterns, // MOB-3: tap/double-tap + swipe/long-press/pinch/pull-to-refresh/rotate/… → appium templates
+    ],
+    discovery: mobileDiscovery,
+    contextMapper: mobileContextMapper,
+    // Intentionally NO `viewpoints`/`gateProvider`: the score-bearing gate + viewpoint catalog come
+    // from the RUNNING core (the audit engine runs its in-core viewpointGate with isMobile=true for a
+    // `platform: mobile` project). Self-loading them here would bind the gate to THIS package's own
+    // resolved @sun-asterisk/sungen copy, which npm can nest at an older published version whose
+    // catalog predates `mobile-home` → stale-catalog version-skew. See the module header.
+    sensors: [mobileViewpointGateSensor],
+  });
+}
+
+/** Discovery entry point core looks for (`mod.sungenDriver.register`). */
+export const sungenDriver = { capability: 'mobile', register } as const;

package/src/patterns/gesture-patterns.ts

@@ -0,0 +1,180 @@
+/**
+ * Mobile (Appium) step patterns — MOB-3.
+ *
+ * Maps mobile-natural Gherkin to the appium adapter's gesture/action templates
+ * (core/adapters/appium/templates/steps/{gestures,actions}). Registered by
+ * @sungen/driver-mobile; only meaningful when `platform: mobile` (the appium adapter is
+ * the only one that ships these templates). `tap`/`double-tap` are the mobile synonyms
+ * for click (driver-ui only knows `click`); `scroll to [X]` is already handled by the
+ * shared scroll pattern (both adapters ship scroll-action), so it is not repeated here.
+ */
+import { StepPattern } from '@sun-asterisk/sungen';
+
+const ANDROID_PERMISSIONS: Record<string, string> = {
+  location: 'android.permission.ACCESS_FINE_LOCATION',
+  camera: 'android.permission.CAMERA',
+  microphone: 'android.permission.RECORD_AUDIO',
+  mic: 'android.permission.RECORD_AUDIO',
+  contacts: 'android.permission.READ_CONTACTS',
+  storage: 'android.permission.READ_EXTERNAL_STORAGE',
+  notifications: 'android.permission.POST_NOTIFICATIONS',
+  calendar: 'android.permission.READ_CALENDAR',
+};
+const IOS_PERMISSIONS: Record<string, string> = {
+  location: 'location', camera: 'camera', microphone: 'microphone', mic: 'microphone',
+  contacts: 'contacts', storage: 'photos', photos: 'photos', notifications: 'notifications',
+  calendar: 'calendar', reminders: 'reminders', motion: 'motion', siri: 'siri',
+};
+
+export const gesturePatterns: StepPattern[] = [
+  // --- tap / double-tap (mobile synonyms for click; appium renders them as taps) ---
+  {
+    name: 'mobile-tap',
+    matcher: (step) =>
+      /\btap(s)?\b/i.test(step.text) &&
+      !/\bdouble[-\s]?tap\b/i.test(step.text) &&
+      !/\blong[-\s]?press\b/i.test(step.text) &&
+      !/\b(top of|at the top|at top)\b/i.test(step.text) &&
+      !!step.selectorRef,
+    resolver: (step, context) => {
+      const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, context.featureName, step.elementType, step.nth);
+      return { templateName: 'click-action', data: { ...resolved, selectorRef: step.selectorRef }, comment: `Tap ${step.selectorRef}` };
+    },
+    priority: 15,
+  },
+  {
+    name: 'mobile-double-tap',
+    matcher: (step) => /\bdouble[-\s]?tap(s)?\b/i.test(step.text) && !!step.selectorRef,
+    resolver: (step, context) => {
+      const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, context.featureName, step.elementType, step.nth);
+      return { templateName: 'double-click-action', data: { ...resolved, selectorRef: step.selectorRef }, comment: `Double-tap ${step.selectorRef}` };
+    },
+    priority: 17,
+  },
+  // --- gestures ---
+  {
+    name: 'swipe-element',
+    matcher: (step) => /\bswipe(s)?\b/i.test(step.text) && !!step.selectorRef,
+    resolver: (step, context) => {
+      const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, context.featureName, step.elementType, step.nth);
+      const direction = (step.text.match(/\b(left|right|up|down)\b/i)?.[1] || 'up').toLowerCase();
+      return { templateName: 'swipe-action', data: { ...resolved, direction, selectorRef: step.selectorRef }, comment: `Swipe ${direction} on ${step.selectorRef}` };
+    },
+    priority: 16,
+  },
+  {
+    name: 'long-press-element',
+    matcher: (step) => /\blong[-\s]?press(es)?\b/i.test(step.text) && !!step.selectorRef,
+    resolver: (step, context) => {
+      const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, context.featureName, step.elementType, step.nth);
+      const secs = step.text.match(/(\d+)\s*second/i)?.[1];
+      const durationMs = secs ? parseInt(secs, 10) * 1000 : 1000;
+      return { templateName: 'long-press-action', data: { ...resolved, durationMs, selectorRef: step.selectorRef }, comment: `Long-press ${step.selectorRef}` };
+    },
+    priority: 16,
+  },
+  {
+    name: 'pull-to-refresh',
+    matcher: (step) => /\bpull[-\s]?to[-\s]?refresh\b/i.test(step.text) && !!step.selectorRef,
+    resolver: (step, context) => {
+      const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, context.featureName, step.elementType, step.nth);
+      return { templateName: 'pull-to-refresh-action', data: { ...resolved, selectorRef: step.selectorRef }, comment: `Pull to refresh ${step.selectorRef}` };
+    },
+    priority: 16,
+  },
+  {
+    name: 'pinch-zoom',
+    matcher: (step) => /\bpinch[-\s]?zoom\b/i.test(step.text) && !!step.selectorRef,
+    resolver: (step, context) => {
+      const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, context.featureName, step.elementType, step.nth);
+      const zoomOut = /\bout\b/i.test(step.text);
+      return { templateName: 'pinch-zoom-action', data: { ...resolved, zoomOut, selectorRef: step.selectorRef }, comment: `Pinch-zoom ${zoomOut ? 'out' : 'in'} on ${step.selectorRef}` };
+    },
+    priority: 16,
+  },
+  {
+    name: 'tap-top-of-element',
+    matcher: (step) => /\btap(s)?\b/i.test(step.text) && /\b(top of|at the top|at top)\b/i.test(step.text) && !!step.selectorRef,
+    resolver: (step, context) => {
+      const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, context.featureName, step.elementType, step.nth);
+      return { templateName: 'tap-top-action', data: { ...resolved, selectorRef: step.selectorRef }, comment: `Tap top of ${step.selectorRef}` };
+    },
+    priority: 18,
+  },
+  {
+    name: 'dismiss-if-present',
+    matcher: (step) => /\bdismiss(es)?\b/i.test(step.text) && !!step.selectorRef && step.elementType !== 'alert',
+    resolver: (step, context) => {
+      const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, context.featureName, step.elementType, step.nth);
+      return { templateName: 'dismiss-action', data: { ...resolved, selectorRef: step.selectorRef }, comment: `Dismiss ${step.selectorRef} if present` };
+    },
+    priority: 14,
+  },
+  {
+    name: 'rotate-device',
+    matcher: (step) => /\brotate\b/i.test(step.text) && /\b(landscape|portrait)\b/i.test(step.text) && !step.selectorRef,
+    resolver: (step) => {
+      const orientation = /\blandscape\b/i.test(step.text) ? 'LANDSCAPE' : 'PORTRAIT';
+      return { templateName: 'rotate-action', data: { orientation }, comment: `Rotate to ${orientation.toLowerCase()}` };
+    },
+    priority: 16,
+  },
+  {
+    name: 'background-app',
+    matcher: (step) => /\bbackground\b/i.test(step.text) && /\bapp\b/i.test(step.text) && !step.selectorRef,
+    resolver: (step) => {
+      const secs = step.text.match(/(\d+)\s*second/i)?.[1];
+      const seconds = secs ? parseInt(secs, 10) : 3;
+      return { templateName: 'background-action', data: { seconds }, comment: `Send app to background for ${seconds}s` };
+    },
+    priority: 16,
+  },
+  {
+    name: 'open-notifications',
+    matcher: (step) => /\bnotification(s)?\s+(panel|shade|tray)\b/i.test(step.text) || /\bopen(s)?\s+notifications\b/i.test(step.text),
+    resolver: () => ({ templateName: 'open-notifications-action', data: {}, comment: 'Open notification panel' }),
+    priority: 16,
+  },
+  {
+    name: 'hide-keyboard',
+    matcher: (step) => /\bkeyboard\b/i.test(step.text) && /\b(hide|hides|dismiss|dismisses|close|closes)\b/i.test(step.text) && !step.selectorRef,
+    resolver: () => ({ templateName: 'hide-keyboard-action', data: {}, comment: 'Hide the soft keyboard' }),
+    priority: 16,
+  },
+  {
+    name: 'grant-permission',
+    matcher: (step) => /\bgrant(s)?\b/i.test(step.text) && /\bpermission(s)?\b/i.test(step.text),
+    resolver: (step) => {
+      const raw = step.selectorRef || step.text.match(/grant(?:s)?\s+(?:the\s+)?([\w.]+)\s+permission/i)?.[1] || '';
+      const permission = ANDROID_PERMISSIONS[raw.toLowerCase()] || raw;
+      const iosService = IOS_PERMISSIONS[raw.toLowerCase()] || raw.toLowerCase();
+      return { templateName: 'grant-permission-action', data: { permission, iosService }, comment: `Grant ${raw || 'app'} permission` };
+    },
+    priority: 16,
+  },
+  {
+    name: 'set-clipboard',
+    matcher: (step) => /\bclipboard\b/i.test(step.text) && /\b(set|sets|copy|copies|put|puts)\b/i.test(step.text) && (!!step.dataRef || step.value != null),
+    resolver: (step, context) => {
+      let value: string;
+      if (step.dataRef) {
+        try { value = context.dataResolver.resolveData(step.dataRef, context.featureName); } catch { value = `\${${step.dataRef}}`; }
+      } else { value = step.value!; }
+      return { templateName: 'set-clipboard-action', data: { clipboardValue: value, dataRef: step.dataRef }, comment: 'Set the device clipboard' };
+    },
+    priority: 16,
+  },
+  {
+    name: 'set-geolocation',
+    matcher: (step) => /\b(location|geolocation|gps|coordinates)\b/i.test(step.text) && /\b(set|sets|mock|mocks|simulate|simulates|move|moves)\b/i.test(step.text),
+    resolver: (step, context) => {
+      let raw = '';
+      if (step.dataRef) { try { raw = context.dataResolver.resolveData(step.dataRef, context.featureName); } catch { raw = ''; } }
+      const nums = (raw || step.text).match(/-?\d+\.\d+|-?\d+/g) || [];
+      const latitude = nums[0] ?? '0';
+      const longitude = nums[1] ?? '0';
+      return { templateName: 'set-geolocation-action', data: { latitude, longitude }, comment: `Set location to ${latitude}, ${longitude}` };
+    },
+    priority: 16,
+  },
+];