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

package/src/orchestrator/flow-manager.ts

@@ -6,11 +6,18 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import { readCapabilities } from '../harness/capability';
 
 export interface FlowOptions {
   name: string;
   path?: string;
   description?: string;
+  /**
+   * Mobile navigation recipe for the flow's starting screen. A `>`-separated list of nav steps
+   * that take the app from launch to the first screen in the flow. Scaffolded into the Background.
+   * Ignored (with a warning) for web projects.
+   */
+  reach?: string;
 }
 
 export class FlowManager {
@@ -25,6 +32,18 @@ export class FlowManager {
   async addFlow(options: FlowOptions): Promise<void> {
     this.validateFlowName(options.name);
 
+    // Detect project platform from qa/capabilities.yaml
+    const caps = readCapabilities(this.cwd);
+    const isMobile = caps.platform === 'mobile';
+
+    // --reach is mobile-only; warn and drop when the project is web
+    if (options.reach && !isMobile) {
+      console.warn(
+        `Warning: --reach is a mobile navigation recipe and is ignored for web projects. Dropping it.`
+      );
+      options = { ...options, reach: undefined };
+    }
+
     const flowName = this.normalizeFlowName(options.name);
     const flowDir = path.join(this.flowsDir, flowName);
 
@@ -59,28 +78,40 @@ export class FlowManager {
       process.exit(1);
     }
 
-    fs.writeFileSync(featurePath, this.generateFeatureTemplate(options, flowName), 'utf-8');
+    fs.writeFileSync(featurePath, this.generateFeatureTemplate(options, flowName, isMobile), 'utf-8');
 
     const startPath = options.path || '/login';
-    fs.writeFileSync(selectorPath, [
-      `# ${options.name} Flow Selectors`,
-      `# Namespace keys by screen to avoid duplicates: "login:submit", "awards:submit"`,
-      ``,
-      `# --- Login screen ---`,
-      `login:`,
-      `  type: 'page'`,
-      `  value: '${startPath}'`,
-      ``,
-      `# "login:email":`,
-      `#   type: 'testid'`,
-      `#   value: 'email-input'`,
-      ``,
-      `# "login:submit":`,
-      `#   type: 'role'`,
-      `#   value: 'button'`,
-      `#   name: 'Login'`,
-      ``,
-    ].join('\n'), 'utf-8');
+    const selectorLines = isMobile
+      ? [
+          `# ${options.name} Flow Selectors (mobile)`,
+          `# Namespace keys by screen: "home:button", "settings:save"`,
+          `# Generated at /sungen:run-test via Appium MCP — accessibility-id preferred.`,
+          ``,
+          `# "home:element":`,
+          `#   type: 'accessibility-id'`,
+          `#   value: 'element-id'`,
+          ``,
+        ]
+      : [
+          `# ${options.name} Flow Selectors`,
+          `# Namespace keys by screen to avoid duplicates: "login:submit", "awards:submit"`,
+          ``,
+          `# --- Login screen ---`,
+          `login:`,
+          `  type: 'page'`,
+          `  value: '${startPath}'`,
+          ``,
+          `# "login:email":`,
+          `#   type: 'testid'`,
+          `#   value: 'email-input'`,
+          ``,
+          `# "login:submit":`,
+          `#   type: 'role'`,
+          `#   value: 'button'`,
+          `#   name: 'Login'`,
+          ``,
+        ];
+    fs.writeFileSync(selectorPath, selectorLines.join('\n'), 'utf-8');
 
     fs.writeFileSync(testDataPath, [
       `# ${options.name} Flow Test Data`,
@@ -90,7 +121,7 @@ export class FlowManager {
     ].join('\n'), 'utf-8');
 
     const specPath = path.join(requirementsDir, 'spec.md');
-    fs.writeFileSync(specPath, this.generateSpecTemplate(options, flowName), 'utf-8');
+    fs.writeFileSync(specPath, this.generateSpecTemplate(options, flowName, isMobile), 'utf-8');
 
     const viewpointPath = path.join(requirementsDir, 'test-viewpoint.md');
     fs.writeFileSync(viewpointPath, this.generateViewpointTemplate(options), 'utf-8');
@@ -104,12 +135,21 @@ export class FlowManager {
     console.log(`  ${path.relative(this.cwd, requirementsUiDir)}/`);
     console.log('');
 
-    console.log('Next steps:');
-    console.log(`  1. Fill requirements/spec.md with flow specification (screens, transitions, business rules)`);
-    console.log(`     Optionally add UI designs to requirements/ui/`);
-    console.log(`  2. Generate test cases: /sungen:create-test ${flowName}`);
-    console.log(`  3. Compile: sungen generate --flow ${flowName}`);
-    console.log(`  4. Run: npx playwright test\n`);
+    if (isMobile) {
+      console.log('Next steps:');
+      console.log(`  1. Fill requirements/spec.md with flow specification (screens, transitions, business rules)`);
+      console.log(`     Use sungen-capture-mobile to scan each screen via Appium MCP`);
+      console.log(`  2. Generate test cases: /sungen:create-test ${flowName}`);
+      console.log(`  3. Compile: sungen generate --flow ${flowName} --framework appium`);
+      console.log(`  4. Run: npm run test:mobile\n`);
+    } else {
+      console.log('Next steps:');
+      console.log(`  1. Fill requirements/spec.md with flow specification (screens, transitions, business rules)`);
+      console.log(`     Optionally add UI designs to requirements/ui/`);
+      console.log(`  2. Generate test cases: /sungen:create-test ${flowName}`);
+      console.log(`  3. Compile: sungen generate --flow ${flowName}`);
+      console.log(`  4. Run: npx playwright test\n`);
+    }
   }
 
   private validateFlowName(name: string): void {
@@ -131,7 +171,39 @@ export class FlowManager {
       .replace(/-+/g, '-');
   }
 
-  private generateSpecTemplate(options: FlowOptions, flowName: string): string {
+  private generateSpecTemplate(options: FlowOptions, flowName: string, isMobile: boolean): string {
+    if (isMobile) {
+      return `# ${options.name} Flow Specification
+
+## Overview
+- **Platform:** mobile (Android + iOS)
+- **Auth Required:** no
+- **Starting screen reach:** ${options.reach || '<!-- nav recipe to reach the first screen, e.g. "tap [Tab] > tap [Row]" -->'}
+
+## Screens in Flow
+<!-- List all screens this flow visits, in order -->
+
+| # | Screen | Reach | Description |
+|---|--------|-------|-------------|
+| 1 | [Screen Name] | tap [element] | [What user does here] |
+
+## Flow Steps
+
+### Step 1: [Screen Name]
+- **Action:** [What the user taps]
+- **Expected:** [What should happen]
+- **Transition:** Navigates to Step 2
+
+## Business Rules
+<!-- Rules that affect the flow: permissions, conditions, limits -->
+- [Rule 1]
+
+## Notes
+<!-- Edge cases, known issues, environment-specific behavior -->
+- [Note 1]
+`;
+    }
+
     const startPath = options.path || '/login';
     return `# ${options.name} Flow Specification
 
@@ -215,9 +287,33 @@ export class FlowManager {
     ].join('\n');
   }
 
-  private generateFeatureTemplate(options: FlowOptions, flowName: string): string {
+  private generateFeatureTemplate(options: FlowOptions, flowName: string, isMobile: boolean): string {
     const description = options.description || `complete the ${options.name} flow`;
 
+    if (isMobile) {
+      const background = this.buildMobileBackground(options.reach);
+      return `@flow @platform:mobile
+Feature: ${options.name} Flow
+
+  As a user
+  I want to ${description}
+  So that I can accomplish my end-to-end goal
+
+  # Mobile (Appium) flow — selectors use colon namespace: "home:element", "settings:save".
+  # See sungen-mobile-gestures for swipe/long-press/scroll steps.
+
+${background}
+  @high
+  Scenario: Sample step for ${options.name}
+    When User tap [Home:element]
+    Then User see [Settings] screen
+
+  Scenario: Sample next step for ${options.name}
+    When User tap [Settings:element]
+    Then User see [Result:header] header with {{result_text}}
+`;
+    }
+
     return `@flow
 Feature: ${options.name} Flow
 
@@ -240,4 +336,44 @@ Feature: ${options.name} Flow
     Then User see "expected result" text
 `;
   }
+
+  /**
+   * Build the Background block for a mobile flow — same structure as screen-manager.
+   * The `--reach` steps represent how to reach the FIRST screen of the flow from app launch.
+   */
+  private buildMobileBackground(reach?: string): string {
+    const normalizeStep = (raw: string): string =>
+      raw
+        .trim()
+        .replace(/^(given|when|and|then|but)\s+/i, '')
+        .replace(/^user\s+/i, '')
+        .trim();
+
+    const steps = (reach || '')
+      .split('>')
+      .map(normalizeStep)
+      .filter(Boolean);
+
+    if (steps.length === 0) {
+      return [
+        '  Background:',
+        '    # Navigation recipe — how to reach the first screen of this flow from app launch.',
+        '    # Prefill with --reach "tap [Tab] > tap [Row]" at add-flow time.',
+        '    Given User is on [Home] screen',
+        '    # When User tap [<tab or button that leads to the first screen>]',
+        '',
+      ].join('\n');
+    }
+
+    const navLines = steps.map(
+      (body, i) => `    ${i === 0 ? 'When' : 'And'} User ${body}`,
+    );
+    return [
+      '  Background:',
+      '    # Navigation recipe — replayed by capture-mobile to land on the first screen.',
+      '    Given User is on [Home] screen',
+      ...navLines,
+      '',
+    ].join('\n');
+  }
 }

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