@sun-asterisk/sungen 3.2.2-beta.11 → 3.2.2-beta.14

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;
+}

package/src/orchestrator/project-initializer.ts

@@ -7,16 +7,31 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { execSync } from 'child_process';
 import { AI_RULES_FILE_MAPPING } from './ai-rules-updater';
+import {
+  MobileInitOptions,
+  emitMobileRuntime,
+  writeMobileCapabilities,
+  installMobileDriver,
+} from './mobile-runtime-scaffolder';
+
+export { MobileInitOptions };
 
 export class ProjectInitializer {
   private baseCwd: string;
   private cwd: string;
   private createdItems: string[] = [];
   private skippedItems: string[] = [];
+  private mobile: MobileInitOptions;
 
-  constructor(private baseUrl: string) {
+  constructor(private baseUrl: string, mobile?: MobileInitOptions) {
     this.baseCwd = process.cwd();
     this.cwd = this.baseCwd;
+    this.mobile = mobile ?? { enabled: false };
+  }
+
+  /** Mobile-only project: no Playwright/web scaffolding. */
+  private get mobileOnly(): boolean {
+    return !!this.mobile.mobileOnly;
   }
 
   /**
@@ -30,34 +45,41 @@ export class ProjectInitializer {
     this.createdItems = [];
     this.skippedItems = [];
 
-    console.log('🚀 Initializing Sungen project...\n');
+    console.log(`🚀 Initializing Sungen ${this.mobileOnly ? 'mobile-only ' : ''}project...\n`);
 
     if (normalizedProjectName) {
       this.createProjectRoot(normalizedProjectName);
     }
 
-    // Create directories
+    // Create directories (mobile-only skips the web Playwright storage dir)
     this.createDirectories();
 
     // Create qa/context.md for QA lead to fill project-wide context
     this.createContext();
 
-    // Create qa/capabilities.yaml — the platform driver profile (default: web/Playwright)
+    // Create qa/capabilities.yaml — web default; mobile path uses writeMobileCapabilities
     this.createCapabilities();
 
-    // Ensure package.json and install Playwright
+    // Ensure package.json and install deps (Playwright for web; skipped for mobile-only)
     await this.setupDependencies();
 
-    // Create playwright config if doesn't exist
-    this.createPlaywrightConfig();
+    // Web-only scaffolding — skipped entirely for a mobile-only project
+    if (!this.mobileOnly) {
+      this.createPlaywrightConfig();
+      this.createSpecsBase();
+    }
 
-    // Create tsconfig.json if doesn't exist
+    // Create tsconfig.json if doesn't exist (needed by both web + mobile)
     this.createTsConfig();
 
-    // Create specs/base.ts for shared context and specs/test-data.ts for runtime data
-    this.createSpecsBase();
+    // specs/test-data.ts (runtime YAML loader) — shared by BOTH web and mobile specs
     this.createSpecsTestData();
 
+    // Mobile harness (Appium/WebdriverIO) — when `--mobile` (a mobile-only project)
+    if (this.mobile.enabled) {
+      this.emitMobileHarness();
+    }
+
     // Create/update .gitignore
     this.updateGitignore();
 
@@ -90,17 +112,14 @@ export class ProjectInitializer {
   }
 
   /**
-   * Create essential directories only
+   * Create essential directories only.
+   * Mobile-only: skips specs/storage (Playwright auth state); qa/screens + qa/flows still created
+   * (1-platform model — mobile uses the same tree as web, NOT a separate qa/mobile/ path).
    */
   private createDirectories(): void {
-    const dirs = [
-      'qa',
-      'qa/screens',
-      'qa/flows',
-      'specs',
-      'specs/generated',
-      'specs/storage',
-    ];
+    const dirs = this.mobileOnly
+      ? ['qa', 'qa/screens', 'qa/flows', 'specs', 'specs/generated']
+      : ['qa', 'qa/screens', 'qa/flows', 'specs', 'specs/generated', 'specs/storage'];
 
     for (const dir of dirs) {
       const fullPath = path.join(this.cwd, dir);
@@ -147,13 +166,17 @@ export class ProjectInitializer {
   }
 
   /**
-   * Update .gitignore with Sungen-specific entries
+   * Update .gitignore with Sungen-specific entries.
+   * Mobile projects add .env.appium (device ids + machine paths) and specs/.auth-mobile/
+   * (Appium auth contract). Web projects add Playwright auth state + report dirs.
    */
   private updateGitignore(): void {
     const gitignorePath = path.join(this.cwd, '.gitignore');
     const sungenEntries = [
       '# Sungen generated files',
       'specs/.auth/',          // session storage state = cookies/tokens (sensitive)
+      'specs/.auth-mobile/',   // mobile auth contract = credentials (sensitive)
+      '.env.appium',           // local mobile-test env = machine paths + device/team ids (.example IS committed)
       'test-results/',
       'playwright-report/',
       '.playwright-mcp/',
@@ -199,7 +222,8 @@ export class ProjectInitializer {
   }
 
   /**
-   * Create VS Code settings for Copilot auto-attach
+   * Create VS Code settings for Copilot auto-attach.
+   * Mobile-only: approves wdio + npx appium instead of npx playwright.
    */
   private createVSCodeSettings(): void {
     const settingsPath = path.join(this.cwd, '.vscode', 'settings.json');
@@ -214,7 +238,9 @@ export class ProjectInitializer {
         'github.copilot.chat.agent.runTasks': true,
         'chat.tools.terminal.autoApprove': {
           sungen: true,
-          'npx playwright': true,
+          ...(this.mobileOnly
+            ? { wdio: true, 'npx appium': true }
+            : { 'npx playwright': true }),
         },
       };
 
@@ -224,15 +250,14 @@ export class ProjectInitializer {
       this.skippedItems.push('.vscode/settings.json');
     }
 
-    // .vscode/mcp.json (Copilot format) — safe-merge Playwright + Figma entries
+    // .vscode/mcp.json (Copilot format) — appium-mcp for mobile-only, Playwright MCP otherwise
     this.mergeMCPConfig(
       path.join(this.cwd, '.vscode', 'mcp.json'),
       'servers',
       {
-        playwright: {
-          command: 'npx',
-          args: ['@playwright/mcp@latest'],
-        },
+        ...(this.mobileOnly
+          ? { 'appium-mcp': { command: 'npx', args: ['-y', 'appium-mcp'] } }
+          : { playwright: { command: 'npx', args: ['@playwright/mcp@latest'] } }),
         figma: {
           type: 'http',
           url: 'https://mcp.figma.com/mcp',
@@ -243,18 +268,17 @@ export class ProjectInitializer {
   }
 
   /**
-   * Create root .mcp.json for Claude Code — safe-merge Playwright + Figma entries
+   * Create root .mcp.json for Claude Code.
+   * Mobile-only: appium-mcp instead of Playwright MCP. Figma always included.
    */
   private createClaudeMCPConfig(): void {
     this.mergeMCPConfig(
       path.join(this.cwd, '.mcp.json'),
       'mcpServers',
       {
-        playwright: {
-          type: 'stdio',
-          command: 'npx',
-          args: ['@playwright/mcp@latest'],
-        },
+        ...(this.mobileOnly
+          ? { 'appium-mcp': { type: 'stdio', command: 'npx', args: ['-y', 'appium-mcp'] } }
+          : { playwright: { type: 'stdio', command: 'npx', args: ['@playwright/mcp@latest'] } }),
         figma: {
           type: 'http',
           url: 'https://mcp.figma.com/mcp',
@@ -337,10 +361,18 @@ export class ProjectInitializer {
     if (projectName) {
       console.log(`  ${stepIndex++}. cd ${projectName}`);
     }
-    console.log(`  ${stepIndex++}. Create your first screen: sungen add --screen <name> --path <url-path>`);
-    console.log(`  ${stepIndex++}. Use AI (Copilot/Claude) to generate Gherkin + selectors from the live page`);
-    console.log(`  ${stepIndex++}. Compile tests: sungen generate --screen <name>`);
-    console.log(`  ${stepIndex++}. Run tests: npx playwright test\n`);
+    if (this.mobileOnly) {
+      console.log(`  ${stepIndex++}. Fill in .env.appium with your device/app details (see .env.appium.example)`);
+      console.log(`  ${stepIndex++}. Create your first screen: sungen add --screen <name>`);
+      console.log(`  ${stepIndex++}. Use AI (Copilot/Claude) to generate Gherkin + selectors from the live app`);
+      console.log(`  ${stepIndex++}. Compile tests: sungen generate --screen <name>`);
+      console.log(`  ${stepIndex++}. Run tests: npm run test:mobile\n`);
+    } else {
+      console.log(`  ${stepIndex++}. Create your first screen: sungen add --screen <name> --path <url-path>`);
+      console.log(`  ${stepIndex++}. Use AI (Copilot/Claude) to generate Gherkin + selectors from the live page`);
+      console.log(`  ${stepIndex++}. Compile tests: sungen generate --screen <name>`);
+      console.log(`  ${stepIndex++}. Run tests: npx playwright test\n`);
+    }
   }
 
   /**
@@ -390,8 +422,9 @@ export class ProjectInitializer {
   }
 
   /**
-   * Create qa/capabilities.yaml — the platform driver profile (Phase 2a).
-   * Defaults to `web` (Playwright). Mobile/API projects switch via `sungen capability add`.
+   * Create qa/capabilities.yaml — the platform driver profile.
+   * Web default: platform=web, enabled=[web].
+   * Mobile: platform=mobile, enabled=[mobile] (via writeMobileCapabilities from the scaffolder).
    */
   private createCapabilities(): void {
     const p = path.join(this.cwd, 'qa', 'capabilities.yaml');
@@ -399,13 +432,18 @@ export class ProjectInitializer {
       this.skippedItems.push('qa/capabilities.yaml');
       return;
     }
-    const content =
-      '# Sungen capability profile — which runtime/drivers this project uses.\n' +
-      '# platform: the runtime adapter — web → Playwright, mobile → Appium.\n' +
-      '# enabled: drivers turned on (add more via `sungen capability add <driver>`).\n\n' +
-      'platform: web\n' +
-      'enabled:\n  - web\n';
-    fs.writeFileSync(p, content, 'utf-8');
+
+    if (this.mobile.enabled) {
+      writeMobileCapabilities(this.cwd);
+    } else {
+      const content =
+        '# Sungen capability profile — which runtime/drivers this project uses.\n' +
+        '# platform: the runtime adapter — web → Playwright, mobile → Appium.\n' +
+        '# enabled: drivers turned on (add more via `sungen capability add <driver>`).\n\n' +
+        'platform: web\n' +
+        'enabled:\n  - web\n';
+      fs.writeFileSync(p, content, 'utf-8');
+    }
     this.createdItems.push('qa/capabilities.yaml');
   }
 
@@ -451,6 +489,20 @@ export class ProjectInitializer {
     this.createdItems.push('specs/generated/test-data.ts');
   }
 
+  /**
+   * Delegate to mobile-runtime-scaffolder to emit Appium/WDIO harness files,
+   * then best-effort install @sungen/driver-mobile at lockstep version.
+   * Called only when `--mobile` is set.
+   */
+  private emitMobileHarness(): void {
+    const result = emitMobileRuntime(this.cwd, this.mobile);
+    this.createdItems.push(...result.created);
+    this.skippedItems.push(...result.skipped);
+
+    // Best-effort driver install — non-fatal so offline init still scaffolds.
+    installMobileDriver(this.cwd);
+  }
+
   /**
    * Read a template file from the templates directory
    */
@@ -476,8 +528,11 @@ export class ProjectInitializer {
     // Ensure standard scripts exist in package.json
     this.ensurePackageScripts(packageJsonPath);
 
-    // Check which dependencies are missing
-    const requiredDeps = ['@playwright/test', '@types/node', 'yaml'];
+    // Mobile-only drops @playwright/test (no web runner needed).
+    const requiredDeps = this.mobileOnly
+      ? ['@types/node', 'yaml']
+      : ['@playwright/test', '@types/node', 'yaml'];
+
     let missingDeps: string[] = requiredDeps;
     try {
       const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
@@ -489,15 +544,17 @@ export class ProjectInitializer {
 
     if (missingDeps.length === 0) {
       console.log('✓ All dependencies already installed\n');
-      return;
+    } else {
+      console.log(`📦 Installing ${missingDeps.join(', ')}...\n`);
+      execSync(`npm install -D ${missingDeps.join(' ')}`, execOpts);
     }
 
-    console.log(`📦 Installing ${missingDeps.join(', ')}...\n`);
-    execSync(`npm install -D ${missingDeps.join(' ')}`, execOpts);
-
-    console.log('\n🎭 Installing Chromium (default browser)...\n');
-    execSync('npx playwright install --with-deps chromium', execOpts);
-    console.log('\n💡 To install other browsers: npm run install:browsers -- firefox webkit\n');
+    // Chromium is only needed for the web (Playwright) runner — skip for mobile-only projects.
+    if (!this.mobileOnly) {
+      console.log('\n🎭 Installing Chromium (default browser)...\n');
+      execSync('npx playwright install --with-deps chromium', execOpts);
+      console.log('\n💡 To install other browsers: npm run install:browsers -- firefox webkit\n');
+    }
   }
 
   /**
@@ -516,15 +573,21 @@ export class ProjectInitializer {
       packageJson.scripts = {};
     }
 
-    const standardScripts: Record<string, string> = {
-      'test': 'playwright test specs/generated/',
-      'test:headed': 'playwright test specs/generated/ --headed',
-      'test:debug': 'playwright test specs/generated/ --debug',
-      'test:ui': 'playwright test specs/generated/ --ui',
-      'report': 'playwright show-report',
-      'generate': 'sungen generate --all',
-      'install:browsers': 'npx playwright install',
-    };
+    // Mobile-only projects get just the generate + mobile-run scripts (no Playwright web scripts).
+    const standardScripts: Record<string, string> = this.mobileOnly
+      ? {
+          'generate': 'sungen generate --all',
+          'test:mobile': 'wdio run wdio.conf.ts',
+        }
+      : {
+          'test': 'playwright test specs/generated/',
+          'test:headed': 'playwright test specs/generated/ --headed',
+          'test:debug': 'playwright test specs/generated/ --debug',
+          'test:ui': 'playwright test specs/generated/ --ui',
+          'report': 'playwright show-report',
+          'generate': 'sungen generate --all',
+          'install:browsers': 'npx playwright install',
+        };
 
     let added = 0;
     for (const [name, command] of Object.entries(standardScripts)) {