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

package/src/orchestrator/project-initializer.ts

@@ -6,17 +6,53 @@
 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 { buildOutputs } from './ai-skills/build';
+import { applyOutputs } from './ai-skills/writer';
+import { AdapterKey } from './ai-skills/adapters';
+import {
+  MobileInitOptions,
+  emitMobileRuntime,
+  writeMobileCapabilities,
+  installMobileDriver,
+} from './mobile-runtime-scaffolder';
+
+export { MobileInitOptions };
+
+function sungenVersion(): string {
+  try { return require(path.join(__dirname, '..', '..', 'package.json')).version || '0.0.0'; }
+  catch { return '0.0.0'; }
+}
 
 export class ProjectInitializer {
   private baseCwd: string;
   private cwd: string;
   private createdItems: string[] = [];
   private skippedItems: string[] = [];
+  private agents: AdapterKey[];
+  private force: boolean;
+  private mobile: MobileInitOptions;
 
-  constructor(private baseUrl: string) {
+  constructor(private baseUrl: string, opts: { agents?: AdapterKey[]; force?: boolean; enabled?: boolean; mobileOnly?: boolean; appPackage?: string; appActivity?: string; appApk?: string; androidUdid?: string; iosBundleId?: string; iosDevice?: string; iosVersion?: string } = {}) {
     this.baseCwd = process.cwd();
     this.cwd = this.baseCwd;
+    this.agents = opts.agents && opts.agents.length ? opts.agents : (['claude'] as AdapterKey[]);
+    this.force = opts.force ?? false;
+    this.mobile = {
+      enabled: opts.enabled ?? false,
+      mobileOnly: opts.mobileOnly ?? false,
+      appPackage: opts.appPackage,
+      appActivity: opts.appActivity,
+      appApk: opts.appApk,
+      androidUdid: opts.androidUdid,
+      iosBundleId: opts.iosBundleId,
+      iosDevice: opts.iosDevice,
+      iosVersion: opts.iosVersion,
+    };
+  }
+
+  /** Mobile-only project: no Playwright/web scaffolding. */
+  private get mobileOnly(): boolean {
+    return !!this.mobile.mobileOnly;
   }
 
   /**
@@ -30,34 +66,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 +133,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 +187,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 +243,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 +259,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 +271,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 +289,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 +382,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`);
+    }
   }
 
   /**
@@ -348,28 +401,17 @@ export class ProjectInitializer {
    * Shares `AI_RULES_FILE_MAPPING` with `sungen update` so a newly added
    * skill / command template only needs to be registered once.
    */
+  /**
+   * Create AI rules files for the selected assistants from the single source (ai-src).
+   * Shares the generator (ai-skills/build) with `sungen update` so a skill is authored once.
+   */
   private createAIRules(): void {
-    const aiTemplateDir = path.join(__dirname, 'templates', 'ai-instructions');
-
-    for (const [templateFile, outputRelPath] of AI_RULES_FILE_MAPPING) {
-      const outputPath = path.join(this.cwd, outputRelPath);
-
-      if (fs.existsSync(outputPath)) {
-        this.skippedItems.push(outputRelPath);
-        continue;
-      }
-
-      const outputDir = path.dirname(outputPath);
-      if (!fs.existsSync(outputDir)) {
-        fs.mkdirSync(outputDir, { recursive: true });
-      }
-
-      const templatePath = path.join(aiTemplateDir, templateFile);
-      const content = fs.readFileSync(templatePath, 'utf-8');
-      fs.writeFileSync(outputPath, content, 'utf-8');
-      this.createdItems.push(outputRelPath);
-    }
-
+    // Single-source generator (decision 1A). Managed skill/command files are written;
+    // config files (CLAUDE.md/AGENTS.md/copilot-instructions) are skip-if-exists unless --force.
+    const outputs = buildOutputs(this.agents);
+    const r = applyOutputs(this.cwd, outputs, { version: sungenVersion(), force: this.force });
+    this.createdItems.push(...r.created);
+    this.skippedItems.push(...r.skippedConfig);
   }
 
   /**
@@ -390,8 +432,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 +442,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 +499,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 +538,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 +554,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 +583,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)) {