@sun-asterisk/sungen 3.2.2 → 3.2.3-beta.3

package/src/orchestrator/mobile-runtime-scaffolder.ts

@@ -0,0 +1,277 @@
+/**
+ * Mobile Runtime Scaffolder
+ *
+ * Emits the Appium/WebdriverIO harness files into a project directory.
+ * Called by ProjectInitializer (init --mobile) and, in Phase 02, by `capability add mobile`.
+ * Never duplicated — always imported from here.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+import { writeCapabilities } from '../harness/capability';
+
+export interface MobileInitOptions {
+  enabled: boolean;
+  /** Mobile-only project: skip all web (Playwright) scaffolding, deps, and Chromium download. */
+  mobileOnly?: boolean;
+  appPackage?: string;
+  appActivity?: string;
+  appApk?: string;
+  androidUdid?: string;
+  iosBundleId?: string;
+  iosDevice?: string;
+  iosVersion?: string;
+}
+
+export interface ScaffoldResult {
+  created: string[];
+  skipped: string[];
+}
+
+/** Read a template from the orchestrator's bundled templates directory. */
+function readTemplate(filename: string): string {
+  const templatePath = path.join(__dirname, 'templates', filename);
+  return fs.readFileSync(templatePath, 'utf-8');
+}
+
+/**
+ * Emit the mobile runtime harness into `cwd`.
+ *
+ * Files written:
+ *   wdio.conf.ts                        — project root (seeded from mobile options)
+ *   specs/reporters/pw-shape-reporter.ts — Playwright-shaped JSON reporter for WDIO
+ *   .env.appium                          — seeded from flags (gitignored)
+ *   .env.appium.example                 — committed placeholder guide
+ *
+ * The caller is responsible for adding `test:mobile` to package.json scripts and
+ * writing qa/capabilities.yaml — helpers for both are exported below.
+ */
+export function emitMobileRuntime(cwd: string, opts: MobileInitOptions): ScaffoldResult {
+  const created: string[] = [];
+  const skipped: string[] = [];
+
+  // wdio.conf.ts (project root) — substitute init-provided app defaults into the template
+  const wdioPath = path.join(cwd, 'wdio.conf.ts');
+  if (fs.existsSync(wdioPath)) {
+    skipped.push('wdio.conf.ts');
+  } else {
+    const content = readTemplate('wdio.conf.ts')
+      .replace('__APP_PACKAGE__', opts.appPackage || 'com.example.app')
+      // appActivity is optional — leave empty when not provided so UiAutomator2
+      // auto-resolves the launcher activity from appPackage. Only pin when explicitly passed.
+      .replace('__APP_ACTIVITY__', opts.appActivity || '')
+      .replace('__ANDROID_UDID__', opts.androidUdid || 'emulator-5554')
+      .replace('__IOS_BUNDLE_ID__', opts.iosBundleId || 'com.example.app')
+      .replace('__IOS_DEVICE__', opts.iosDevice || 'iPhone 16')
+      .replace('__IOS_VERSION__', opts.iosVersion || '18.0');
+    fs.writeFileSync(wdioPath, content, 'utf-8');
+    created.push('wdio.conf.ts');
+  }
+
+  // specs/reporters/pw-shape-reporter.ts
+  const reporterPath = path.join(cwd, 'specs', 'reporters', 'pw-shape-reporter.ts');
+  if (fs.existsSync(reporterPath)) {
+    skipped.push('specs/reporters/pw-shape-reporter.ts');
+  } else {
+    fs.mkdirSync(path.dirname(reporterPath), { recursive: true });
+    fs.writeFileSync(reporterPath, readTemplate('specs-pw-shape-reporter.ts'), 'utf-8');
+    created.push('specs/reporters/pw-shape-reporter.ts');
+  }
+
+  // .env.appium — seeded from the flags that were provided; env vars that were not passed
+  // are left commented out so the file is a useful guide without imposing bogus values.
+  const envPath = path.join(cwd, '.env.appium');
+  if (fs.existsSync(envPath)) {
+    skipped.push('.env.appium');
+  } else {
+    const lines: string[] = [
+      '# .env.appium — loaded by wdio.conf.ts. Shell exports override these values.',
+      '# See .env.appium.example for the full reference.',
+      '',
+    ];
+    if (opts.appPackage) lines.push(`APP_PACKAGE=${opts.appPackage}`);
+    if (opts.appActivity) lines.push(`APP_ACTIVITY=${opts.appActivity}`);
+    if (opts.appApk) lines.push(`APP_APK=${opts.appApk}`);
+    if (opts.androidUdid) lines.push(`ANDROID_UDID=${opts.androidUdid}`);
+    if (opts.iosBundleId) lines.push(`IOS_BUNDLE_ID=${opts.iosBundleId}`);
+    if (opts.iosDevice) lines.push(`IOS_DEVICE=${opts.iosDevice}`);
+    if (opts.iosVersion) lines.push(`IOS_VERSION=${opts.iosVersion}`);
+    lines.push('');
+    fs.writeFileSync(envPath, lines.join('\n'), 'utf-8');
+    created.push('.env.appium');
+  }
+
+  // .env.appium.example — committed placeholder guide (template stored without leading dot
+  // so copy-templates' glob picks it up; the output file gets the dot).
+  const envExamplePath = path.join(cwd, '.env.appium.example');
+  if (fs.existsSync(envExamplePath)) {
+    skipped.push('.env.appium.example');
+  } else {
+    fs.writeFileSync(envExamplePath, readTemplate('env.appium.example'), 'utf-8');
+    created.push('.env.appium.example');
+  }
+
+  return { created, skipped };
+}
+
+/**
+ * Write qa/capabilities.yaml for a mobile project.
+ * Uses the canonical writeCapabilities from harness/capability so the format is always consistent.
+ */
+export function writeMobileCapabilities(cwd: string): string {
+  return writeCapabilities(cwd, { platform: 'mobile', enabled: ['mobile'] });
+}
+
+/**
+ * Resolve the install spec for `@sungen/driver-mobile`.
+ *
+ * In a monorepo checkout (dev / dogfood) the driver lives at `packages/driver-mobile` next to core and
+ * is NOT published to the registry — so we install it by `file:` path. In a published install (core in
+ * node_modules, no sibling package) we fall back to the registry pinned to the core version (lockstep).
+ *
+ * Why: a bare `@sungen/driver-mobile@<coreVersion>` hits npm E404 whenever the driver is unpublished or
+ * the consuming project lives outside the workspace (`test-mobile/`). The local `file:` path makes the
+ * dev/dogfood path work without the registry, while the registry fallback preserves lockstep for users.
+ */
+function resolveMobileDriverSpec(): string {
+  // From this file (src/orchestrator OR dist/orchestrator) the sibling driver package is ../../../driver-mobile.
+  const localDriverDir = path.resolve(__dirname, '..', '..', '..', 'driver-mobile');
+  if (fs.existsSync(path.join(localDriverDir, 'package.json'))) {
+    return `file:${localDriverDir}`;
+  }
+  let coreVersion = 'latest';
+  try {
+    coreVersion = require('../../package.json').version || 'latest';
+  } catch {
+    // noop — fall back to latest
+  }
+  return `@sungen/driver-mobile@${coreVersion}`;
+}
+
+/** Best-effort `npm install -D <specs…> [extraArgs…]` in `cwd`. Returns true on exit code 0. */
+function npmInstallDev(cwd: string, specs: string[], extraArgs: string[] = []): boolean {
+  const result = spawnSync('npm', ['install', '-D', ...specs, ...extraArgs], { cwd, stdio: 'inherit', shell: true });
+  return result.status === 0;
+}
+
+/**
+ * Locate the project's locally-installed appium CLI bin. Walks up from `cwd` so it works whether the
+ * appium dep is nested under @sungen/driver-mobile or hoisted to a parent node_modules/.bin. Returns
+ * null when appium is not installed in the project (then we skip cleanly — no `npx` auto-fetch).
+ */
+function appiumBinPath(cwd: string): string | null {
+  const binName = process.platform === 'win32' ? 'appium.cmd' : 'appium';
+  let dir = path.resolve(cwd);
+  for (let i = 0; i < 8; i++) {
+    const bin = path.join(dir, 'node_modules', '.bin', binName);
+    if (fs.existsSync(bin)) return bin;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/** Appium platform drivers already installed in ~/.appium (per-user). Empty set if it can't tell. */
+function installedAppiumDrivers(appiumBin: string, cwd: string): Set<string> {
+  const r = spawnSync(appiumBin, ['driver', 'list', '--installed', '--json'], { cwd, encoding: 'utf-8' });
+  if (r.status !== 0 || !r.stdout) return new Set();
+  try { return new Set(Object.keys(JSON.parse(r.stdout))); } catch { return new Set(); }
+}
+
+/**
+ * Auto-install the Appium PLATFORM drivers needed for ANY session — both the appium-mcp live capture
+ * (`/sungen:create-test`) and the wdio runner (`/sungen:run-test`). Provisioned by the SAME code path
+ * that installs @sungen/driver-mobile (right after its `appium` dep is installed). Best-effort + idempotent.
+ *
+ *   - `uiautomator2` (Android): cross-platform → always.
+ *   - `xcuitest` (iOS): macOS-only — it builds WebDriverAgent via Xcode at RUN time, usable only on a
+ *     Mac → installed only on darwin; elsewhere we print the command for when on a Mac.
+ *
+ * Runs the project-local appium bin directly (NOT `npx`, which would either auto-fetch a latest appium
+ * or hard-fail with `--no-install`). If appium isn't installed in the project, skip with a clear hint.
+ */
+function installAppiumPlatformDrivers(cwd: string): void {
+  const appiumBin = appiumBinPath(cwd);
+  if (!appiumBin) {
+    console.warn(
+      '⚠️  appium is not installed in the project — skipping platform-driver install.\n' +
+      '   Install the mobile runtime first (the @sungen/driver-mobile deps via `npm install`), then run:\n' +
+      `     npx appium driver install uiautomator2${process.platform === 'darwin' ? '   (+ xcuitest)' : ''}`,
+    );
+    return;
+  }
+  const installed = installedAppiumDrivers(appiumBin, cwd);
+  const want = ['uiautomator2', ...(process.platform === 'darwin' ? ['xcuitest'] : [])];
+  for (const drv of want) {
+    if (installed.has(drv)) { console.log(`✓ appium driver "${drv}" already installed.`); continue; }
+    console.log(`📦 Installing appium driver "${drv}"...`);
+    const r = spawnSync(appiumBin, ['driver', 'install', drv], { cwd, stdio: 'inherit' });
+    if (!r || r.status !== 0) {
+      console.warn(`⚠️  appium driver "${drv}" not installed (best-effort) — retry: npx appium driver install ${drv}`);
+    }
+  }
+  if (process.platform !== 'darwin') {
+    console.log('ℹ️  iOS (xcuitest) is macOS-only (needs Xcode at run time) — skipped on this OS. On a Mac: npx appium driver install xcuitest');
+  }
+}
+
+/**
+ * Best-effort provision of the mobile runtime into a project that has opted into mobile
+ * (`sungen init --mobile` / `sungen capability add mobile` — never auto-run; consent-gated).
+ *
+ * Installs everything the runner needs:
+ *   1. `@sungen/driver-mobile` + its WebdriverIO/Appium runtime (declared as that package's `dependencies`).
+ *      A local `file:` spec (dev/dogfood) uses `npm install --install-links` so npm COPIES the package and
+ *      installs its transitive deps — a plain file: install only SYMLINKS it and skips the runtime. A
+ *      published/registry spec installs deps normally.
+ *   2. the appium PLATFORM drivers (uiautomator2 / xcuitest, ~/.appium-managed) — NOT npm packages, so
+ *      installed via the appium CLI here (installAppiumPlatformDrivers), so a session can actually start.
+ *
+ * Non-fatal: logs a warning on failure so offline/air-gapped init still scaffolds correctly.
+ *
+ * @returns true if the driver install succeeded (or was already present), false on failure
+ */
+export function installMobileDriver(cwd: string): boolean {
+  const driverSpec = resolveMobileDriverSpec();
+
+  // A `file:` spec (unpublished dev/dogfood driver) MUST install with --install-links: a plain file:
+  // install only SYMLINKS the package and skips its transitive deps, so the wdio/appium runtime never
+  // lands in the project. --install-links makes npm COPY it and install those deps. Registry specs
+  // install deps normally, so the flag is omitted there.
+  const isFileSpec = driverSpec.startsWith('file:');
+
+  // Provisioned only when BOTH the driver dep AND its appium runtime are present — a driver that was
+  // symlinked earlier (no runtime) must be re-installed (with --install-links) to actually pull appium.
+  let hasDriverDep = false;
+  try {
+    const pkgJsonPath = path.join(cwd, 'package.json');
+    if (fs.existsSync(pkgJsonPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+      hasDriverDep = !!allDeps['@sungen/driver-mobile'];
+    }
+  } catch {
+    // proceed to install
+  }
+  const runtimeReady = hasDriverDep && appiumBinPath(cwd) !== null;
+
+  let driverOk = runtimeReady;
+  if (!runtimeReady) {
+    console.log(`📦 Installing mobile driver + runtime (${driverSpec})...`);
+    driverOk = npmInstallDev(cwd, [driverSpec], isFileSpec ? ['--install-links'] : []);
+    if (!driverOk) {
+      console.warn(
+        `⚠️  Could not install ${driverSpec} — scaffold is complete but the mobile driver is not installed.\n` +
+        `   Install manually later: npm install -D ${driverSpec}${isFileSpec ? ' --install-links' : ''}`,
+      );
+    }
+  }
+
+  // Appium platform driver(s) — REQUIRED for any session (appium-mcp live capture AND the wdio runner).
+  // NOT npm packages, so installed via the appium CLI here, by the same code path that installs the driver.
+  installAppiumPlatformDrivers(cwd);
+
+  return driverOk;
+}