@sun-asterisk/sungen 2.4.5 → 2.4.6

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-delivery.md

@@ -0,0 +1,103 @@
+---
+name: sungen-delivery
+description: 'Export Gherkin scenarios + Playwright results → CSV test case deliverable. Auto-loaded by delivery command.'
+user-invocable: false
+---
+
+## Purpose
+
+Export test cases from Sungen screens to a standardized CSV file (format BM-2-901-13) for QA delivery.
+
+**This skill delegates all heavy work to the `sungen delivery` CLI.** The CLI is the single source of truth for parsing logic — do NOT re-parse files in AI. Your role is only to:
+
+1. Invoke the CLI
+2. Show its output verbatim
+3. Help the user react to pre-flight failures
+
+---
+
+## Architecture
+
+```
+User → /sungen:delivery [screen...]
+       │
+       ▼
+  sungen delivery CLI  (deterministic — no AI tokens)
+  ├─ Scope detection (no-arg = all screens)
+  ├─ Pre-flight source checks per screen
+  ├─ Parse .feature (metadata)
+  ├─ Parse .spec.ts (resolved Playwright code — source of truth)
+  ├─ Parse test-data.yaml (resolve {{vars}})
+  ├─ Parse test-results/results.json (match test titles)
+  ├─ Merge sources + generate CSV rows
+  └─ Write qa/deliverables/<screen>-testcases.csv
+```
+
+Source modules: `src/exporters/*.ts`
+
+---
+
+## Required sources (CLI pre-flight checks these)
+
+| # | Source | Path | Created by |
+|---|--------|------|------------|
+| 1 | Feature file | `qa/screens/<screen>/features/<screen>.feature` | `/sungen:add-screen` + `/sungen:create-test` |
+| 2 | Test data | `qa/screens/<screen>/test-data/<screen>.yaml` | `/sungen:create-test` |
+| 3 | Selectors | `qa/screens/<screen>/selectors/<screen>.yaml` | `/sungen:run-test` |
+| 4 | Compiled spec | `specs/generated/<screen>/<screen>.spec.ts` | `sungen generate` (during `/sungen:run-test`) |
+| 5 | Test results | `specs/generated/<screen>/<screen>-test-result.json` (per-screen) or `test-results/results.json` (global fallback) | `/sungen:run-test` |
+
+**Sources 1-4 are blocking** — CLI aborts if any is missing.
+**Source 5 is optional** — CSV is still generated but Test Result/Date/Executor/Env columns are empty (all tests show as Pending).
+
+The CLI reads the **per-screen result file first** (co-located with `.spec.ts`), then falls back to the global `test-results/results.json`. Per-screen is preferred because the global file gets OVERWRITTEN each time Playwright runs, losing results from earlier screens.
+
+---
+
+## Column mapping (handled by CLI)
+
+| CSV Column | Source |
+|------------|--------|
+| TC ID | Generated: `<SCREEN_UPPER>-<VP>-<NNN>` |
+| Category 1 | Scenario name with VP prefix stripped |
+| Category 2 | VP group: `VP-SEC`→Accessing, `VP-UI`→GUI, `VP-VAL`/`VP-LOGIC`→Function |
+| Category 3 | Feature name (first line of `.feature`) |
+| Category 4 | Screen name |
+| Pre-condition | Auth tag → "Logged in as X" / "Not authenticated" + Given steps (natural language) |
+| Test Data | `{{vars}}` from scenario resolved via test-data.yaml → `key: value; key2: value2` |
+| Steps | `.spec.ts` code comments for interactions (numbered) |
+| Expected results | `.spec.ts` `expect(...)` comments (numbered) |
+| Priority | Tag: `@critical`/`@high`/`@normal`/`@low` (default: Normal) |
+| Testcase type | `@manual` → Manual, else Auto. Not compiled → "Not compiled" |
+| Test Result | results.json status: passed→Passed, failed/timedOut→Failed, skipped→N/A, else Pending |
+| Executed Date | results.json startTime formatted as `dd/mm/yyyy` |
+| Test Executor | `git config user.name` |
+| Test Environment | `playwright.config.ts` baseURL + project name |
+| Note | Error message + trace path (for failed tests) |
+
+---
+
+## Excluded from CSV
+
+- `@steps:<name>` **base** scenarios — these are setup-only, inlined into `@extend:...` scenarios at compile time
+- Default scaffold `Sample scenario for <screen>` — not a real test
+
+---
+
+## CLI command reference
+
+```bash
+# Export all screens
+sungen delivery
+
+# Export specific screens
+sungen delivery kudos awards
+
+# Skip pre-flight (CI only)
+sungen delivery --skip-preflight
+
+# Skip screens with blocking misses
+sungen delivery --continue-on-missing
+```
+
+Output: `qa/deliverables/<screen>-testcases.csv` (UTF-8 with BOM)

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-gherkin-syntax.md

@@ -109,6 +109,8 @@ Row scope: `see [Ref] row in [Table] table with {{v}}` enters scope. Subsequent
 
 Most elements auto-infer from `[Label] type` → `getByRole(type, { name: 'Label' })`. Only add YAML when the accessible name differs, needs `nth`, or needs `testid`. Full auto-infer table → see `sungen-selector-keys` skill.
 
+**Types requiring YAML entry:** `date-picker`, `uploader`, `overlay`, `frame`, `step` - these have no standard ARIA role and need explicit selectors.
+
 ## YAML Keys
 
 `[Reference]` → **lowercase, keep Unicode**: `[Search Content]` → `search content:`, `[Thời gian]` → `thời gian:`

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-selector-keys.md

@@ -102,5 +102,27 @@ If no YAML key exists, the resolver infers from the Gherkin element type:
 | `[X] list` | `getByRole('list', { name: 'X' })` |
 | `[X] column` | `getByRole('columnheader', { name: 'X' })` |
 | `[X] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'X' })` |
+| `[X] dropdown` / `select` | `getByRole('combobox', { name: 'X' })` |
+| `[X] menuitem` | `getByRole('menuitem', { name: 'X' })` |
+| `[X] progressbar` | `getByRole('progressbar', { name: 'X' })` |
+| `[X] section` | `getByRole('region', { name: 'X' })` |
+| `[X] card` | `getByRole('article', { name: 'X' })` |
+| `[X] item` | `getByRole('listitem', { name: 'X' })` |
+| `[X] cell` | `getByRole('cell', { name: 'X' })` |
+| `[X] spinner` | `getByRole('status', { name: 'X' })` |
+| `[X] breadcrumb` | `getByRole('navigation', { name: 'X' })` |
+| `[X] badge` / `tooltip` / `tag` | `getByText('X')` |
 
 **Only add a YAML entry when** the auto-inferred locator won't work (wrong name, need testid, need nth, etc.).
+
+### Types requiring YAML entry (no auto-infer)
+
+These types need explicit `selectors.yaml` entries:
+
+| Type | Reason |
+|------|--------|
+| `date-picker` | Custom component, needs testid or CSS |
+| `uploader` | File input, needs upload type selector |
+| `overlay` | No standard ARIA role, needs CSS/testid |
+| `frame` | Needs iframe selector |
+| `step` | Custom stepper component, needs testid |

package/dist/orchestrator/templates/playwright.config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playwright.config.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/templates/playwright.config.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAKH;;GAEG;;AACH,wBAoEG"}
+{"version":3,"file":"playwright.config.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/templates/playwright.config.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAKH;;GAEG;;AACH,wBAyEG"}

package/dist/orchestrator/templates/playwright.config.js

@@ -24,7 +24,12 @@ exports.default = (0, test_1.defineConfig)({
     /* Global timeout per test */
     timeout: 10000,
     /* Reporter to use. See https://playwright.dev/docs/test-reporters */
-    reporter: 'html',
+    /* JSON reporter is required by `sungen delivery` to populate test result columns in the exported CSV. */
+    /* Output file path is controlled by PLAYWRIGHT_JSON_OUTPUT_NAME env var for per-screen isolation. */
+    reporter: [
+        ['html'],
+        ['json', { outputFile: process.env.PLAYWRIGHT_JSON_OUTPUT_NAME || 'test-results/results.json' }],
+    ],
     /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
     use: {
         /* Base URL to use in actions like `await page.goto('')`. */

package/dist/orchestrator/templates/playwright.config.js.map

@@ -1 +1 @@
-{"version":3,"file":"playwright.config.js","sourceRoot":"","sources":["../../../src/orchestrator/templates/playwright.config.ts"],"names":[],"mappings":";;AAAA,2CAAyD;AAEzD;;;GAGG;AACH,+BAA+B;AAC/B,2BAA2B;AAC3B,4DAA4D;AAE5D;;GAEG;AACH,kBAAe,IAAA,mBAAY,EAAC;IAC1B,OAAO,EAAE,mBAAmB;IAC5B,oCAAoC;IACpC,aAAa,EAAE,IAAI;IACnB,iFAAiF;IACjF,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;IAC5B,sBAAsB;IACtB,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,6BAA6B;IAC7B,OAAO,EAAE,KAAM;IACf,qEAAqE;IACrE,QAAQ,EAAE,MAAM;IAChB,wGAAwG;IACxG,GAAG,EAAE;QACH,4DAA4D;QAC5D,OAAO,EAAE,qBAAqB;QAE9B,+FAA+F;QAC/F,KAAK,EAAE,gBAAgB;KACxB;IAED,2CAA2C;IAC3C,QAAQ,EAAE;QACR;YACE,IAAI,EAAE,UAAU;YAChB,GAAG,EAAE,EAAE,GAAG,cAAO,CAAC,gBAAgB,CAAC,EAAE;SACtC;QAED;;;;;;;;;;;;;;;;;;;;;4CAqBoC;QACpC,IAAI;QACJ,4BAA4B;QAC5B,4DAA4D;QAC5D,KAAK;QACL,IAAI;QACJ,2BAA2B;QAC3B,8DAA8D;QAC9D,KAAK;KACN;IAED,yDAAyD;IACzD,eAAe;IACf,8BAA8B;IAC9B,kCAAkC;IAClC,0CAA0C;IAC1C,KAAK;CACN,CAAC,CAAC"}
+{"version":3,"file":"playwright.config.js","sourceRoot":"","sources":["../../../src/orchestrator/templates/playwright.config.ts"],"names":[],"mappings":";;AAAA,2CAAyD;AAEzD;;;GAGG;AACH,+BAA+B;AAC/B,2BAA2B;AAC3B,4DAA4D;AAE5D;;GAEG;AACH,kBAAe,IAAA,mBAAY,EAAC;IAC1B,OAAO,EAAE,mBAAmB;IAC5B,oCAAoC;IACpC,aAAa,EAAE,IAAI;IACnB,iFAAiF;IACjF,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;IAC5B,sBAAsB;IACtB,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,6BAA6B;IAC7B,OAAO,EAAE,KAAM;IACf,qEAAqE;IACrE,yGAAyG;IACzG,qGAAqG;IACrG,QAAQ,EAAE;QACR,CAAC,MAAM,CAAC;QACR,CAAC,MAAM,EAAE,EAAE,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,2BAA2B,IAAI,2BAA2B,EAAE,CAAC;KACjG;IACD,wGAAwG;IACxG,GAAG,EAAE;QACH,4DAA4D;QAC5D,OAAO,EAAE,qBAAqB;QAE9B,+FAA+F;QAC/F,KAAK,EAAE,gBAAgB;KACxB;IAED,2CAA2C;IAC3C,QAAQ,EAAE;QACR;YACE,IAAI,EAAE,UAAU;YAChB,GAAG,EAAE,EAAE,GAAG,cAAO,CAAC,gBAAgB,CAAC,EAAE;SACtC;QAED;;;;;;;;;;;;;;;;;;;;;4CAqBoC;QACpC,IAAI;QACJ,4BAA4B;QAC5B,4DAA4D;QAC5D,KAAK;QACL,IAAI;QACJ,2BAA2B;QAC3B,8DAA8D;QAC9D,KAAK;KACN;IAED,yDAAyD;IACzD,eAAe;IACf,8BAA8B;IAC9B,kCAAkC;IAClC,0CAA0C;IAC1C,KAAK;CACN,CAAC,CAAC"}

package/dist/orchestrator/templates/playwright.config.ts

@@ -24,7 +24,12 @@ export default defineConfig({
   /* Global timeout per test */
   timeout: 10_000,
   /* Reporter to use. See https://playwright.dev/docs/test-reporters */
-  reporter: 'html',
+  /* JSON reporter is required by `sungen delivery` to populate test result columns in the exported CSV. */
+  /* Output file path is controlled by PLAYWRIGHT_JSON_OUTPUT_NAME env var for per-screen isolation. */
+  reporter: [
+    ['html'],
+    ['json', { outputFile: process.env.PLAYWRIGHT_JSON_OUTPUT_NAME || 'test-results/results.json' }],
+  ],
   /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
   use: {
     /* Base URL to use in actions like `await page.goto('')`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "2.4.5",
+  "version": "2.4.6",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -40,6 +40,7 @@
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",
+    "exceljs": "^4.4.0",
     "fast-glob": "^3.3.3",
     "glob": "^13.0.0",
     "handlebars": "^4.7.8",

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