@sun-asterisk/sungen 2.4.3 → 2.4.6

package/src/cli/commands/delivery.ts

@@ -0,0 +1,348 @@
+/**
+ * `sungen delivery` CLI command.
+ * Exports Gherkin scenarios + Playwright results → CSV test case file.
+ */
+
+import { Command } from 'commander';
+import * as path from 'path';
+import * as fs from 'fs';
+import { execSync } from 'child_process';
+import { parseFeatureMetadata } from '../../exporters/feature-parser';
+import { parseSpecFile } from '../../exporters/spec-parser';
+import { loadTestData, resolveTestDataPath } from '../../exporters/test-data-resolver';
+import { loadPlaywrightReport } from '../../exporters/playwright-report-parser';
+import { mergeFeatureAndSpec } from '../../exporters/scenario-merger';
+import {
+  buildTestCaseRows,
+  buildSummary,
+  renderCsv,
+  writeCsv,
+} from '../../exporters/csv-exporter';
+import { renderXlsx, writeXlsx } from '../../exporters/xlsx-exporter';
+import { EnvironmentInfo, PreflightCheck, ScreenSummary } from '../../exporters/types';
+
+const COLOR = {
+  reset: '\x1b[0m',
+  gray: '\x1b[90m',
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  bold: '\x1b[1m',
+};
+
+function log(msg: string): void {
+  console.log(msg);
+}
+
+// ----------------------------------------------------------------------------
+// Discovery
+// ----------------------------------------------------------------------------
+
+function listAllScreens(cwd: string): string[] {
+  const screensDir = path.join(cwd, 'qa', 'screens');
+  if (!fs.existsSync(screensDir)) return [];
+  return fs
+    .readdirSync(screensDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)
+    .sort();
+}
+
+// ----------------------------------------------------------------------------
+// Pre-flight checks
+// ----------------------------------------------------------------------------
+
+/**
+ * Resolve the results file path for a screen.
+ * Prefer the per-screen co-located file, fall back to the global `test-results/results.json`.
+ */
+function resolveResultsPath(cwd: string, screen: string): string | null {
+  const perScreen = path.join(cwd, 'specs', 'generated', screen, `${screen}-test-result.json`);
+  if (fs.existsSync(perScreen)) return perScreen;
+  const global = path.join(cwd, 'test-results', 'results.json');
+  if (fs.existsSync(global)) return global;
+  return null;
+}
+
+function runPreflight(cwd: string, screen: string): PreflightCheck {
+  const featureFile = path.join(cwd, 'qa', 'screens', screen, 'features', `${screen}.feature`);
+  const testDataFile = resolveTestDataPath(cwd, screen);
+  const selectorsFile = path.join(cwd, 'qa', 'screens', screen, 'selectors', `${screen}.yaml`);
+  const specFile = path.join(cwd, 'specs', 'generated', screen, `${screen}.spec.ts`);
+  const resultsFile = resolveResultsPath(cwd, screen);
+
+  const featureOk = checkFeatureReal(featureFile);
+  const testDataOk = checkTestDataHasVars(testDataFile);
+  const selectorsOk = checkSelectorsHasEntries(selectorsFile, screen);
+  const specOk = fs.existsSync(specFile);
+  const resultsOk = resultsFile !== null;
+
+  const missing: string[] = [];
+  const suggestions: string[] = [];
+
+  if (!featureOk) {
+    missing.push(`feature file missing/empty: ${path.relative(cwd, featureFile)}`);
+    suggestions.push(`/sungen:create-test ${screen}`);
+  }
+  if (!testDataOk) {
+    missing.push(`test-data.yaml has no variables: ${path.relative(cwd, testDataFile)}`);
+    suggestions.push(`/sungen:create-test ${screen}`);
+  }
+  if (!selectorsOk) {
+    missing.push(`selectors.yaml missing entries: ${path.relative(cwd, selectorsFile)}`);
+    suggestions.push(`/sungen:run-test ${screen}`);
+  }
+  if (!specOk) {
+    missing.push(`compiled .spec.ts missing: ${path.relative(cwd, specFile)}`);
+    suggestions.push(`sungen generate --screen ${screen}`);
+  }
+  if (!resultsOk) {
+    missing.push(`test-result.json missing (optional)`);
+    suggestions.push(`PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/${screen}/${screen}-test-result.json npx playwright test specs/generated/${screen}/${screen}.spec.ts`);
+  }
+
+  return {
+    screen,
+    featureOk,
+    testDataOk,
+    selectorsOk,
+    specOk,
+    resultsOk,
+    missing,
+    suggestions: Array.from(new Set(suggestions)),
+  };
+}
+
+function checkFeatureReal(featureFile: string): boolean {
+  if (!fs.existsSync(featureFile)) return false;
+  const content = fs.readFileSync(featureFile, 'utf-8');
+  if (!/Feature:/i.test(content)) return false;
+  // Treat as empty if only the sample scaffold scenario is present
+  const sample = /Scenario:\s*Sample scenario for /.test(content);
+  const realScenarios = (content.match(/\n\s*Scenario:/g) || []).length;
+  // If sample present and only 1 scenario → it's the scaffold only
+  if (sample && realScenarios <= 1) return false;
+  return realScenarios >= 1;
+}
+
+function checkTestDataHasVars(testDataFile: string): boolean {
+  if (!fs.existsSync(testDataFile)) return false;
+  const content = fs.readFileSync(testDataFile, 'utf-8');
+  // Any non-comment line with `key: value`
+  const lines = content.split('\n').filter((l) => !l.trim().startsWith('#') && l.includes(':'));
+  return lines.length > 0;
+}
+
+function checkSelectorsHasEntries(selectorsFile: string, screen: string): boolean {
+  if (!fs.existsSync(selectorsFile)) return false;
+  const content = fs.readFileSync(selectorsFile, 'utf-8');
+  // Very small check: YAML has more than just a single `<screen>: page` entry
+  const topLevelKeys = (content.match(/^[a-zA-Z_][^\s:]*:\s*$/gm) || []).length +
+    (content.match(/^[a-zA-Z_][^\s:]*:\s/gm) || []).length;
+  return topLevelKeys > 1;
+}
+
+function hasBlockingMissing(p: PreflightCheck): boolean {
+  return !p.featureOk || !p.testDataOk || !p.selectorsOk || !p.specOk;
+}
+
+// ----------------------------------------------------------------------------
+// Environment
+// ----------------------------------------------------------------------------
+
+function getEnvironment(cwd: string): EnvironmentInfo {
+  let baseURL = '';
+  let projectName = 'chromium';
+  const configPath = path.join(cwd, 'playwright.config.ts');
+  if (fs.existsSync(configPath)) {
+    const c = fs.readFileSync(configPath, 'utf-8');
+    const baseMatch = c.match(/baseURL:\s*['"]([^'"]+)['"]/);
+    if (baseMatch) baseURL = baseMatch[1];
+    const projMatch = c.match(/name:\s*['"]([^'"]+)['"]/);
+    if (projMatch) projectName = projMatch[1];
+  }
+
+  let executor = process.env.CI_USER || process.env.USER || '';
+  try {
+    const gitUser = execSync('git config user.name', { cwd, encoding: 'utf-8' }).trim();
+    if (gitUser) executor = gitUser;
+  } catch {
+    // ignore
+  }
+
+  return { baseURL, projectName, executor };
+}
+
+// ----------------------------------------------------------------------------
+// Per-screen export
+// ----------------------------------------------------------------------------
+
+async function exportScreen(
+  cwd: string,
+  screen: string,
+  env: EnvironmentInfo
+): Promise<ScreenSummary | null> {
+  const featureFile = path.join(cwd, 'qa', 'screens', screen, 'features', `${screen}.feature`);
+  const testDataFile = resolveTestDataPath(cwd, screen);
+  const specFile = path.join(cwd, 'specs', 'generated', screen, `${screen}.spec.ts`);
+  const resultsFile = resolveResultsPath(cwd, screen);
+  const specMdFile = path.join(cwd, 'qa', 'screens', screen, 'requirements', 'spec.md');
+
+  try {
+    const feature = parseFeatureMetadata(featureFile);
+    const spec = parseSpecFile(specFile);
+    const testData = loadTestData(testDataFile);
+    const results = resultsFile ? loadPlaywrightReport(resultsFile) : null;
+
+    const merged = mergeFeatureAndSpec(feature, spec);
+    const rows = buildTestCaseRows({
+      screen,
+      featureName: feature.featureName,
+      merged,
+      testData,
+      results,
+      env,
+    });
+
+    const specLink = fs.existsSync(specMdFile) ? path.relative(cwd, specMdFile) : '';
+    const tempSummary = buildSummary(screen, rows, '');
+    const csv = renderCsv(tempSummary, rows, specLink);
+    const csvPath = writeCsv(cwd, screen, csv);
+    const wb = renderXlsx(tempSummary, rows, specLink);
+    await writeXlsx(cwd, screen, wb);
+    return buildSummary(screen, rows, path.relative(cwd, csvPath));
+  } catch (err) {
+    console.error(`${COLOR.red}Error exporting ${screen}:${COLOR.reset} ${err instanceof Error ? err.message : err}`);
+    return null;
+  }
+}
+
+// ----------------------------------------------------------------------------
+// Reporter
+// ----------------------------------------------------------------------------
+
+function printPreflightTable(checks: PreflightCheck[]): void {
+  log(`\n${COLOR.bold}Pre-flight source check${COLOR.reset}`);
+  log(`${COLOR.gray}Columns: feature | test-data | selectors | .spec.ts | test-result.json${COLOR.reset}\n`);
+
+  const ok = (b: boolean) => (b ? `${COLOR.green}✓${COLOR.reset}` : `${COLOR.red}✗${COLOR.reset}`);
+
+  for (const c of checks) {
+    log(
+      `  ${c.screen.padEnd(20)} ${ok(c.featureOk)}  ${ok(c.testDataOk)}  ${ok(c.selectorsOk)}  ${ok(c.specOk)}  ${ok(c.resultsOk)}`
+    );
+  }
+  log('');
+
+  // Show suggestions for any blocking misses
+  const blockers = checks.filter(hasBlockingMissing);
+  if (blockers.length > 0) {
+    log(`${COLOR.yellow}Blocking issues:${COLOR.reset}`);
+    for (const b of blockers) {
+      log(`  ${COLOR.bold}${b.screen}${COLOR.reset}`);
+      for (const m of b.missing) log(`    - ${COLOR.red}✗${COLOR.reset} ${m}`);
+      for (const s of b.suggestions) log(`    ${COLOR.cyan}→ ${s}${COLOR.reset}`);
+    }
+    log('');
+  }
+
+  // Warn about optional misses (results.json)
+  const warnings = checks.filter((c) => !hasBlockingMissing(c) && !c.resultsOk);
+  if (warnings.length > 0) {
+    log(`${COLOR.yellow}Warnings (optional missing):${COLOR.reset}`);
+    for (const w of warnings) {
+      log(`  ${w.screen}: test-result.json missing — execution columns will be empty`);
+    }
+    log('');
+  }
+}
+
+function printSummaryTable(summaries: ScreenSummary[]): void {
+  log(`\n${COLOR.bold}Delivery export complete${COLOR.reset}`);
+  log('');
+  log('  Screen               TCs  Passed  Failed  Pending  N/A  File');
+  log('  ' + '-'.repeat(80));
+  for (const s of summaries) {
+    log(
+      `  ${s.screen.padEnd(20)} ${String(s.total).padStart(3)}  ${String(s.passed).padStart(6)}  ${String(s.failed).padStart(6)}  ${String(s.pending).padStart(7)}  ${String(s.na).padStart(3)}  ${s.outputFile}`
+    );
+  }
+  log('');
+
+  const totalNotCompiled = summaries.reduce((a, s) => a + s.notCompiled, 0);
+  if (totalNotCompiled > 0) {
+    log(`${COLOR.yellow}Note: ${totalNotCompiled} scenario(s) flagged "Not compiled" in CSV. Re-run \`sungen generate\` to compile them.${COLOR.reset}\n`);
+  }
+}
+
+// ----------------------------------------------------------------------------
+// Command registration
+// ----------------------------------------------------------------------------
+
+export function registerDeliveryCommand(program: Command): void {
+  program
+    .command('delivery')
+    .description('Export Gherkin + Playwright results → CSV test case deliverable')
+    .argument('[screens...]', 'Specific screen names. Omit to process all screens.')
+    .option('--skip-preflight', 'Skip pre-flight checks (not recommended)')
+    .option('--continue-on-missing', 'Skip screens with blocking misses instead of aborting')
+    .action(async (screens: string[], options: { skipPreflight?: boolean; continueOnMissing?: boolean }) => {
+      try {
+        const cwd = process.cwd();
+
+        // 1. Scope detection
+        let targetScreens: string[];
+        if (screens && screens.length > 0) {
+          targetScreens = screens;
+        } else {
+          targetScreens = listAllScreens(cwd);
+          if (targetScreens.length === 0) {
+            console.error(`${COLOR.red}No screens found in qa/screens/${COLOR.reset}`);
+            process.exit(1);
+          }
+        }
+
+        log(`${COLOR.bold}sungen delivery${COLOR.reset} — exporting ${targetScreens.length} screen(s): ${targetScreens.join(', ')}\n`);
+
+        // 2. Pre-flight
+        let toExport: string[];
+        if (options.skipPreflight) {
+          toExport = targetScreens;
+        } else {
+          const checks = targetScreens.map((s) => runPreflight(cwd, s));
+          printPreflightTable(checks);
+
+          const blockers = checks.filter(hasBlockingMissing);
+          if (blockers.length > 0) {
+            if (options.continueOnMissing) {
+              toExport = checks.filter((c) => !hasBlockingMissing(c)).map((c) => c.screen);
+              log(`${COLOR.yellow}Continuing with ${toExport.length} ready screen(s).${COLOR.reset}\n`);
+            } else {
+              console.error(
+                `${COLOR.red}Aborted:${COLOR.reset} ${blockers.length} screen(s) have blocking issues.\n` +
+                `Run the suggested commands above, or use ${COLOR.cyan}--continue-on-missing${COLOR.reset} to skip them.`
+              );
+              process.exit(1);
+            }
+          } else {
+            toExport = checks.map((c) => c.screen);
+          }
+        }
+
+        // 3. Export
+        const env = getEnvironment(cwd);
+        const summaries: ScreenSummary[] = [];
+        for (const screen of toExport) {
+          const s = await exportScreen(cwd, screen, env);
+          if (s) summaries.push(s);
+        }
+
+        // 4. Summary
+        printSummaryTable(summaries);
+      } catch (err) {
+        console.error(`${COLOR.red}Fatal:${COLOR.reset} ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/update.ts

@@ -1,12 +1,52 @@
 import { Command } from 'commander';
+import { spawnSync } from 'child_process';
+
+/**
+ * `sungen update` does two jobs in sequence:
+ *
+ *  1. Reinstall `@sun-asterisk/sungen@latest` globally via npm so the bundled
+ *     AI templates are refreshed.
+ *  2. Re-execute `sungen update` with the env var `SUNGEN_UPDATE_SKIP_NPM=1`
+ *     so the AI rules / commands / skills inside the project get overwritten
+ *     from the *new* templates.
+ *
+ * We use an environment variable (not a CLI flag) for the internal hand-off
+ * because Commander throws "unknown option" if the currently-installed
+ * published version doesn't recognise the flag yet. Env vars are silently
+ * ignored by older versions — the worst case is one extra (idempotent) npm
+ * install, never a crash.
+ *
+ * The public `--skip-npm-install` flag is still available for users who
+ * already installed the binary by other means (CI pipelines, corporate
+ * mirror, manual download) and only want to refresh the project AI assets.
+ */
+
+const SKIP_NPM_ENV = 'SUNGEN_UPDATE_SKIP_NPM';
 
 export function registerUpdateCommand(program: Command): void {
   program
     .command('update')
-    .description('Update AI rules, commands, and skills to the latest version')
+    .description(
+      'Reinstall @sun-asterisk/sungen@latest + refresh AI rules, commands, and skills',
+    )
     .option('--dry-run', 'Show what would be updated without making changes')
-    .action(async (options: { dryRun?: boolean }) => {
+    .option(
+      '--skip-npm-install',
+      'Skip the `npm install -g @sun-asterisk/sungen@latest` step (refresh project AI assets only)',
+      false,
+    )
+    .action(async (options: { dryRun?: boolean; skipNpmInstall?: boolean }) => {
       try {
+        const skipNpm =
+          Boolean(options.skipNpmInstall) || process.env[SKIP_NPM_ENV] === '1';
+
+        if (!skipNpm) {
+          reinstallLatestSungen();
+          printCurrentVersion();
+          reExecUpdateForAIAssets(options.dryRun ?? false);
+          return;
+        }
+
         const { AIRulesUpdater } = require('../../orchestrator/ai-rules-updater');
         const updater = new AIRulesUpdater(process.cwd());
         await updater.update(options.dryRun ?? false);
@@ -16,3 +56,45 @@ export function registerUpdateCommand(program: Command): void {
       }
     });
 }
+
+function reinstallLatestSungen(): void {
+  console.log('📦 Installing @sun-asterisk/sungen@latest...');
+  const result = spawnSync('npm', ['install', '-g', '@sun-asterisk/sungen@latest'], {
+    stdio: 'inherit',
+    shell: true,
+  });
+  if (result.status !== 0) {
+    throw new Error(
+      'npm install -g @sun-asterisk/sungen@latest failed. Run it manually or check your npm setup.',
+    );
+  }
+}
+
+function printCurrentVersion(): void {
+  console.log('\n🔎 Installed version:');
+  spawnSync('sungen', ['--version'], { stdio: 'inherit', shell: true });
+  console.log('');
+}
+
+function reExecUpdateForAIAssets(dryRun: boolean): void {
+  const args = ['update'];
+  if (dryRun) args.push('--dry-run');
+
+  const result = spawnSync('sungen', args, {
+    stdio: 'inherit',
+    shell: true,
+    env: { ...process.env, [SKIP_NPM_ENV]: '1' },
+  });
+
+  if (result.status !== 0) {
+    console.error(
+      '\n⚠️  AI-rules refresh step returned a non-zero exit code.\n' +
+        `   If the newly installed version is older and didn't recognise this flow,\n` +
+        '   run the refresh manually:\n\n' +
+        '       sungen update --skip-npm-install' +
+        (dryRun ? ' --dry-run' : '') +
+        '\n',
+    );
+  }
+  process.exit(result.status ?? 0);
+}

package/src/cli/index.ts

@@ -10,6 +10,7 @@ import { registerAddCommand } from './commands/add';
 import { registerGenerateCommand } from './commands/generate';
 import { registerMakeauthCommand } from './commands/makeauth';
 import { registerUpdateCommand } from './commands/update';
+import { registerDeliveryCommand } from './commands/delivery';
 
 async function main() {
   const program = new Command();
@@ -17,18 +18,19 @@ async function main() {
   program
     .name('sungen')
     .description('Deterministic E2E Test Compiler — Gherkin + Selectors → Playwright')
-    .version('2.4.3');
+    .version('2.4.6');
 
   // Global options
   program
     .option('-v, --verbose', 'Enable verbose logging');
 
-  // Register commands (5 only)
+  // Register commands (6)
   registerInitCommand(program);
   registerAddCommand(program);
   registerGenerateCommand(program);
   registerMakeauthCommand(program);
   registerUpdateCommand(program);
+  registerDeliveryCommand(program);
 
   await program.parseAsync(process.argv);
 }