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

package/src/orchestrator/ai-skills/golden-skills.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Golden regression net for the single-source generator.
+ *
+ * Compares generated output for all adapters against committed fixtures under
+ * tests/golden/ai-skills/fixtures/. The fixtures were frozen from output that was proven
+ * byte-identical to the original per-assistant templates (see git history: the prior
+ * ai-instructions-based golden). From now on the fixtures ARE the contract — any change to
+ * a source skill/command must be reflected with `--update`, making every output change a
+ * reviewable diff.
+ *
+ *   tsx .../golden-skills.test.ts            # verify
+ *   tsx .../golden-skills.test.ts --update   # re-freeze fixtures after an intentional change
+ *
+ * Also runs source lint (decision 6A): required frontmatter + unique-ish command order,
+ * and a Codex flat-namespace collision check.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { buildOutputs } from './build';
+import { parseCommandSource } from './commands';
+
+const FIX = path.resolve(__dirname, '..', '..', '..', 'tests', 'golden', 'ai-skills', 'fixtures');
+const SRC = path.resolve(__dirname, '..', 'templates', 'ai-src', 'skills');
+const SRC_CMD = path.resolve(__dirname, '..', 'templates', 'ai-src', 'commands');
+const UPDATE = process.argv.includes('--update');
+
+function lint(): string[] {
+  const errs: string[] = [];
+  const fmKeys = (t: string): Set<string> => {
+    const s = new Set<string>();
+    if (!t.startsWith('---')) return s;
+    for (const l of t.slice(3, t.indexOf('\n---', 3)).split('\n')) { const m = l.match(/^([a-zA-Z_-]+):/); if (m) s.add(m[1]); }
+    return s;
+  };
+  for (const dir of fs.existsSync(SRC) ? fs.readdirSync(SRC) : []) {
+    const dp = path.join(SRC, dir);
+    if (!fs.statSync(dp).isDirectory()) continue;
+    const f = path.join(dp, 'SKILL.md');
+    if (!fs.existsSync(f)) continue;
+    const k = fmKeys(fs.readFileSync(f, 'utf8'));
+    if (!k.has('name')) errs.push(`${dir}/SKILL.md: missing frontmatter name`);
+    if (!k.has('description')) errs.push(`${dir}/SKILL.md: missing frontmatter description`);
+  }
+  const seen = new Map<string, string>();
+  for (const f of fs.existsSync(SRC_CMD) ? fs.readdirSync(SRC_CMD) : []) {
+    const c = parseCommandSource(fs.readFileSync(path.join(SRC_CMD, f), 'utf8'), f.replace(/\.md$/, ''));
+    if (!c.description) errs.push(`commands/${f}: missing description`);
+    if (c.order != null) { const k = String(c.order); if (seen.has(k)) { /* allowed: parallel entrypoints */ } else seen.set(k, f); }
+  }
+  return errs;
+}
+
+function run() {
+  // Guardrail: the retired per-assistant folder must never come back. Skills are authored
+  // ONCE in ai-src/. If a dev recreates ai-instructions/, fail loud with a pointer.
+  const legacyDir = path.resolve(__dirname, '..', 'templates', 'ai-instructions');
+  if (fs.existsSync(legacyDir)) {
+    console.error('GOLDEN FAILED — templates/ai-instructions/ exists again.');
+    console.error('  Author skills/commands in templates/ai-src/ ONLY (see ai-src/README.md).');
+    console.error('  The per-assistant duplicates are generated from ai-src by ai-skills/build.ts.');
+    process.exit(1);
+  }
+
+  const lintErrs = lint();
+  // stripCaps throws on unknown cap tag / unclosed fence, so buildOutputs validates fences.
+  const outputs = buildOutputs(['claude', 'copilot', 'codex']);
+
+  // Codex has ONE flat .agents/skills/ namespace — every discovered SKILL.md `name:` must be
+  // unique, or `$name`/description selection is ambiguous (regression guard for the command vs
+  // backing-skill collision: dashboard/delivery/locale must be <name> vs <name>-guide).
+  const codexNames = new Map<string, string>();
+  for (const f of outputs) {
+    if (!f.outputPath.startsWith('.agents/skills/') || !f.outputPath.endsWith('/SKILL.md')) continue;
+    const m = f.content.match(/^name:\s*(\S+)/m);
+    if (!m) continue;
+    if (codexNames.has(m[1])) lintErrs.push(`codex duplicate skill name "${m[1]}" (${f.outputPath} & ${codexNames.get(m[1])})`);
+    else codexNames.set(m[1], f.outputPath);
+  }
+
+  if (UPDATE) {
+    fs.rmSync(FIX, { recursive: true, force: true });
+    for (const f of outputs) {
+      const abs = path.join(FIX, f.outputPath);
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, f.content);
+    }
+    console.log(`✓ froze ${outputs.length} fixtures -> tests/golden/ai-skills/fixtures/`);
+    if (lintErrs.length) { console.error('source lint errors:'); lintErrs.forEach((e) => console.error('  ✗ ' + e)); process.exit(1); }
+    return;
+  }
+
+  let pass = 0; const mismatches: string[] = []; const missing: string[] = [];
+  const expectedPaths = new Set(outputs.map((f) => f.outputPath));
+  for (const f of outputs) {
+    const abs = path.join(FIX, f.outputPath);
+    if (!fs.existsSync(abs)) { missing.push(f.outputPath); continue; }
+    if (fs.readFileSync(abs, 'utf8') === f.content) pass++;
+    else mismatches.push(f.outputPath);
+  }
+  // fixtures present but no longer generated => stale
+  const stale: string[] = [];
+  const walk = (d: string, base = '') => {
+    if (!fs.existsSync(d)) return;
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const rel = path.join(base, e.name);
+      if (e.isDirectory()) walk(path.join(d, e.name), rel);
+      else if (!expectedPaths.has(rel)) stale.push(rel);
+    }
+  };
+  walk(FIX);
+
+  console.log(`GOLDEN — source lint: ${lintErrs.length === 0 ? 'PASS' : lintErrs.length + ' error(s)'}`);
+  lintErrs.forEach((e) => console.log('   ✗ ' + e));
+  console.log(`GOLDEN — fixtures: ${pass}/${outputs.length} match | mismatch ${mismatches.length} | missing ${missing.length} | stale ${stale.length}`);
+  [...mismatches.map((m) => 'MISMATCH ' + m), ...missing.map((m) => 'MISSING ' + m), ...stale.map((s) => 'STALE ' + s)].forEach((x) => console.log('   ✗ ' + x));
+
+  if (lintErrs.length || mismatches.length || missing.length || stale.length) {
+    console.error('GOLDEN FAILED — run with --update if the change was intentional, then review the diff.');
+    process.exit(1);
+  }
+  console.log('✓ GOLDEN PASS — all adapter output matches frozen fixtures.');
+}
+
+run();

package/src/orchestrator/ai-skills/resolve-assistants.ts

@@ -0,0 +1,18 @@
+import { AdapterKey, ALL_ADAPTERS } from './adapters';
+
+/**
+ * Resolve `--assistant` CLI values to adapter keys.
+ * Empty -> ['claude'] (decision T5: never silently install all into a single-assistant repo).
+ * 'all' -> every adapter. Unknown values throw.
+ */
+export function resolveAssistants(input: string[] | undefined): AdapterKey[] {
+  if (!input || input.length === 0) return ['claude'];
+  const set = new Set<AdapterKey>();
+  for (const raw of input) {
+    const v = raw.toLowerCase().trim();
+    if (v === 'all') { ALL_ADAPTERS.forEach((a) => set.add(a)); continue; }
+    if (v === 'claude' || v === 'copilot' || v === 'codex') { set.add(v); continue; }
+    throw new Error(`Unknown --assistant "${raw}" (valid: claude, copilot, codex, all)`);
+  }
+  return [...set];
+}

package/src/orchestrator/ai-skills/writer.ts

@@ -0,0 +1,92 @@
+/**
+ * applyOutputs — write a BuiltFile[] to disk with the agreed semantics (decisions 2, T2).
+ *
+ *   managed (skills/commands): ALWAYS overwritten (version-managed, no rollback)
+ *   config  (CLAUDE.md/AGENTS.md/copilot-instructions): skip-if-exists unless `force`
+ *   orphans: managed files written last run but not this run are DELETED (manifest-derived,
+ *            replaces the hand-curated STALE list — decision T2)
+ *   detect-and-warn: if a managed file on disk was hand-edited since we wrote it, warn
+ *   dry-run: report adds/overwrites/skips/deletes/warnings without touching disk
+ *
+ * Manifest: <cwd>/.sungen/manifest.json = { version, managed: { <path>: <sha256> } }
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { BuiltFile } from './build';
+
+export interface ApplyOptions { force?: boolean; dryRun?: boolean; version: string }
+export interface ApplyReport {
+  created: string[]; overwritten: string[]; skippedConfig: string[];
+  deletedOrphans: string[]; handEditWarnings: string[];
+}
+
+const MANIFEST_REL = path.join('.sungen', 'manifest.json');
+const sha = (s: string) => crypto.createHash('sha256').update(s).digest('hex');
+
+interface Manifest { version: string; managed: Record<string, string> }
+
+function readManifest(cwd: string): Manifest {
+  const p = path.join(cwd, MANIFEST_REL);
+  if (!fs.existsSync(p)) return { version: '', managed: {} };
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return { version: '', managed: {} }; }
+}
+
+export function applyOutputs(cwd: string, outputs: BuiltFile[], opts: ApplyOptions): ApplyReport {
+  const r: ApplyReport = { created: [], overwritten: [], skippedConfig: [], deletedOrphans: [], handEditWarnings: [] };
+  const prev = readManifest(cwd);
+  const newManaged: Record<string, string> = {};
+
+  const write = (rel: string, content: string) => {
+    if (opts.dryRun) return;
+    const abs = path.join(cwd, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content, 'utf8');
+  };
+
+  for (const f of outputs) {
+    const abs = path.join(cwd, f.outputPath);
+    const exists = fs.existsSync(abs);
+
+    if (f.cls === 'config') {
+      if (exists && !opts.force) { r.skippedConfig.push(f.outputPath); continue; }
+      (exists ? r.overwritten : r.created).push(f.outputPath);
+      write(f.outputPath, f.content);
+      continue;
+    }
+
+    // managed: always overwrite, but warn if hand-edited since our last write
+    if (exists) {
+      const current = fs.readFileSync(abs, 'utf8');
+      const recorded = prev.managed[f.outputPath];
+      if (recorded && sha(current) !== recorded && sha(current) !== sha(f.content)) {
+        r.handEditWarnings.push(f.outputPath);
+      }
+      if (current !== f.content) r.overwritten.push(f.outputPath);
+    } else {
+      r.created.push(f.outputPath);
+    }
+    write(f.outputPath, f.content);
+    newManaged[f.outputPath] = sha(f.content);
+  }
+
+  // Orphan cleanup: managed files we wrote last time but not now.
+  for (const oldPath of Object.keys(prev.managed)) {
+    if (newManaged[oldPath]) continue;
+    r.deletedOrphans.push(oldPath);
+    if (!opts.dryRun) {
+      const abs = path.join(cwd, oldPath);
+      if (fs.existsSync(abs)) fs.rmSync(abs, { force: true });
+      // prune now-empty skill dir
+      const dir = path.dirname(abs);
+      try { if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) fs.rmdirSync(dir); } catch { /* ignore */ }
+    }
+  }
+
+  if (!opts.dryRun) {
+    const mPath = path.join(cwd, MANIFEST_REL);
+    fs.mkdirSync(path.dirname(mPath), { recursive: true });
+    fs.writeFileSync(mPath, JSON.stringify({ version: opts.version, managed: newManaged }, null, 2));
+  }
+  return r;
+}

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