@sun-asterisk/sungen 2.6.1 → 2.6.2

package/src/cli/commands/dashboard.ts

@@ -0,0 +1,158 @@
+/**
+ * `sungen dashboard` CLI command.
+ *
+ * Builds qa/dashboard/index.html — a single-file, share-ready test report —
+ * from existing Gherkin features, compiled .spec.ts files, and Playwright
+ * results. Snapshots are persisted under qa/dashboard/history/ (max 20).
+ */
+
+import { Command } from 'commander';
+import * as path from 'path';
+import * as fs from 'fs';
+import { execSync } from 'child_process';
+import { EnvironmentInfo } from '../../exporters/types';
+import {
+  buildDashboardSnapshot,
+  DashboardTarget,
+  listDashboardTargets,
+  resolveTargetType,
+} from '../../dashboard/snapshot-builder';
+import {
+  writeSnapshotToHistory,
+  DEFAULT_MAX_HISTORY,
+} from '../../dashboard/history-store';
+import { buildPayload, renderDashboardHtml } from '../../dashboard/html-renderer';
+
+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); }
+
+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 };
+}
+
+interface DashboardOptions {
+  noHistory?: boolean;
+  open?: boolean;
+  maxHistory?: string;
+}
+
+export function registerDashboardCommand(program: Command): void {
+  program
+    .command('dashboard')
+    .description('Build a single-file HTML dashboard summarising all test cases & results')
+    .argument('[names...]', 'Specific screen or flow names. Omit to include all.')
+    .option('--no-history', 'Do not persist this run under qa/dashboard/history/')
+    .option('--max-history <n>', `Cap retained history files (default: ${DEFAULT_MAX_HISTORY})`)
+    .option('--open', 'Open the rendered HTML in the default browser when done')
+    .action(async (names: string[], options: DashboardOptions) => {
+      try {
+        const cwd = process.cwd();
+
+        // 1. Scope detection
+        let targets: DashboardTarget[];
+        if (names && names.length > 0) {
+          targets = names.map((n) => resolveTargetType(cwd, n));
+        } else {
+          targets = listDashboardTargets(cwd);
+          if (targets.length === 0) {
+            console.error(`${COLOR.red}No screens or flows found in qa/screens/ or qa/flows/${COLOR.reset}`);
+            process.exit(1);
+          }
+        }
+
+        const labels = targets.map((t) => t.isFlow ? `flow/${t.name}` : t.name);
+        log(`${COLOR.bold}sungen dashboard${COLOR.reset} — building report for ${targets.length} target(s): ${labels.join(', ')}`);
+
+        // 2. Build snapshot
+        const env = getEnvironment(cwd);
+        const snapshot = buildDashboardSnapshot({
+          cwd,
+          targets,
+          env,
+          continueOnError: true,
+        });
+
+        log(
+          `\n${COLOR.bold}Snapshot${COLOR.reset}  ${snapshot.runId}  ` +
+          `${COLOR.gray}(${snapshot.screens.length} screens, ${snapshot.summary.total} TCs)${COLOR.reset}`
+        );
+
+        // 3. Persist history (unless disabled)
+        if (!options.noHistory) {
+          const max = options.maxHistory ? Math.max(1, parseInt(options.maxHistory, 10) || DEFAULT_MAX_HISTORY) : DEFAULT_MAX_HISTORY;
+          const result = writeSnapshotToHistory(cwd, snapshot, max);
+          log(`  ${COLOR.green}✓${COLOR.reset} history  ${path.relative(cwd, result.written)}`);
+          if (result.pruned.length > 0) {
+            log(`  ${COLOR.gray}  pruned ${result.pruned.length} older snapshot(s)${COLOR.reset}`);
+          }
+        }
+
+        // 4. Render HTML
+        const payload = buildPayload(cwd, snapshot);
+        const rendered = renderDashboardHtml(cwd, payload);
+        log(`  ${COLOR.green}✓${COLOR.reset} html     ${path.relative(cwd, rendered.outputPath)}  ${COLOR.gray}(${(rendered.bytes / 1024 / 1024).toFixed(2)} MB)${COLOR.reset}`);
+
+        // 5. Print quick summary
+        const s = snapshot.summary;
+        log('');
+        log(`  ${COLOR.bold}Summary${COLOR.reset}`);
+        log(`    Total:        ${s.total}`);
+        log(`    ${COLOR.green}Passed${COLOR.reset}:       ${s.passed}`);
+        log(`    ${COLOR.red}Failed${COLOR.reset}:       ${s.failed}`);
+        log(`    Pending:      ${s.pending}`);
+        log(`    N/A:          ${s.na}`);
+        if (s.notCompiled > 0) {
+          log(`    ${COLOR.yellow}Not compiled${COLOR.reset}: ${s.notCompiled}`);
+        }
+        const passRatePct = (s.passRate * 100).toFixed(1);
+        log(`    Pass rate:    ${passRatePct}%  ${COLOR.gray}(of executed)${COLOR.reset}`);
+        log('');
+
+        // 6. Optionally open in browser
+        if (options.open) {
+          openInBrowser(rendered.outputPath);
+        }
+      } catch (err) {
+        console.error(`${COLOR.red}Fatal:${COLOR.reset} ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+      }
+    });
+}
+
+function openInBrowser(filePath: string): void {
+  const fileUrl = `file://${filePath}`;
+  const platform = process.platform;
+  try {
+    if (platform === 'darwin') execSync(`open "${fileUrl}"`);
+    else if (platform === 'win32') execSync(`start "" "${fileUrl}"`);
+    else execSync(`xdg-open "${fileUrl}"`);
+  } catch {
+    // ignore — user can open manually
+  }
+}

package/src/cli/index.ts

@@ -13,6 +13,7 @@ import { registerUpdateCommand } from './commands/update';
 import { registerDeliveryCommand } from './commands/delivery';
 import { registerFigmaCommand } from './commands/figma';
 import { registerAddFlowCommand } from './commands/add-flow';
+import { registerDashboardCommand } from './commands/dashboard';
 
 async function main() {
   const program = new Command();
@@ -20,13 +21,13 @@ async function main() {
   program
     .name('sungen')
     .description('Deterministic E2E Test Compiler — Gherkin + Selectors → Playwright')
-    .version('2.6.1');
+    .version('2.6.2');
 
   // Global options
   program
     .option('-v, --verbose', 'Enable verbose logging');
 
-  // Register commands (7)
+  // Register commands (9)
   registerInitCommand(program);
   registerAddCommand(program);
   registerGenerateCommand(program);
@@ -35,6 +36,7 @@ async function main() {
   registerDeliveryCommand(program);
   registerFigmaCommand(program);
   registerAddFlowCommand(program);
+  registerDashboardCommand(program);
 
   await program.parseAsync(process.argv);
 }

package/src/dashboard/history-store.ts

@@ -0,0 +1,86 @@
+/**
+ * Persist dashboard snapshots under qa/dashboard/history/ and prune to a fixed
+ * max count (oldest by mtime are deleted). Used by `sungen dashboard` to
+ * accumulate runs for Trends / Compare views.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { DashboardSnapshot } from './types';
+
+export const DEFAULT_MAX_HISTORY = 20;
+
+export interface HistoryWriteResult {
+  written: string;                     // absolute path written
+  pruned: string[];                    // absolute paths removed
+  retained: string[];                  // absolute paths still on disk (newest → oldest)
+}
+
+export function historyDir(cwd: string): string {
+  return path.join(cwd, 'qa', 'dashboard', 'history');
+}
+
+/**
+ * Write `snapshot` as <runId>.json and prune older files until at most `max`
+ * files remain. Files are sorted by mtime so manual edits (rare) still work.
+ */
+export function writeSnapshotToHistory(
+  cwd: string,
+  snapshot: DashboardSnapshot,
+  max: number = DEFAULT_MAX_HISTORY
+): HistoryWriteResult {
+  const dir = historyDir(cwd);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const filename = `${snapshot.runId}.json`;
+  const target = path.join(dir, filename);
+  fs.writeFileSync(target, JSON.stringify(snapshot, null, 2), 'utf-8');
+
+  const pruned = pruneHistory(dir, max);
+
+  const retained = listHistoryFiles(dir);
+  return { written: target, pruned, retained };
+}
+
+/**
+ * Return absolute paths of every JSON file under history/, sorted newest → oldest.
+ */
+export function listHistoryFiles(dir: string): string[] {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => path.join(dir, f))
+    .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+}
+
+/**
+ * Read every history JSON, oldest → newest. Skips files that fail to parse.
+ */
+export function readHistory(cwd: string): DashboardSnapshot[] {
+  const dir = historyDir(cwd);
+  const files = listHistoryFiles(dir).reverse(); // oldest → newest
+  const out: DashboardSnapshot[] = [];
+  for (const f of files) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(f, 'utf-8')) as DashboardSnapshot;
+      out.push(parsed);
+    } catch {
+      // ignore malformed
+    }
+  }
+  return out;
+}
+
+/**
+ * Delete oldest files in `dir` until at most `max` remain.
+ * Returns the absolute paths removed.
+ */
+function pruneHistory(dir: string, max: number): string[] {
+  const files = listHistoryFiles(dir);              // newest first
+  if (files.length <= max) return [];
+  const toRemove = files.slice(max);
+  for (const f of toRemove) {
+    try { fs.unlinkSync(f); } catch { /* ignore */ }
+  }
+  return toRemove;
+}

package/src/dashboard/html-renderer.ts

@@ -0,0 +1,90 @@
+/**
+ * Inject a DashboardPayload into the pre-built single-file HTML template,
+ * then write the result to qa/dashboard/index.html.
+ *
+ * The template lives at src/dashboard/templates/index.html (built by
+ * dashboard/, then copied during `npm run build`). It must contain
+ * the placeholder line:
+ *
+ *     <script id="__SUNGEN_DASHBOARD__" type="application/json">{}</script>
+ *
+ * The renderer replaces the JSON content with the payload — no other
+ * mutation. This keeps the template itself fully static, so opening it
+ * directly (without running the CLI) shows an empty-state dashboard.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { DashboardPayload, DashboardSnapshot } from './types';
+import { readHistory } from './history-store';
+
+const PAYLOAD_TAG_OPEN = '<script id="__SUNGEN_DASHBOARD__" type="application/json">';
+const PAYLOAD_TAG_CLOSE = '</script>';
+
+/**
+ * Locate the bundled template. Looks first in dist/ (production), then src/
+ * (when running via tsx in dev).
+ */
+export function resolveTemplatePath(): string {
+  const candidates = [
+    // Compiled package: dist/dashboard/templates/index.html (copy-templates)
+    path.join(__dirname, 'templates', 'index.html'),
+    // Dev: src/dashboard/templates/index.html
+    path.join(__dirname, '..', '..', 'src', 'dashboard', 'templates', 'index.html'),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  throw new Error(
+    'Dashboard HTML template not found. Build it via:\n' +
+    '    cd dashboard && npm install && npm run build\n' +
+    'then copy dashboard/dist/index.html → src/dashboard/templates/index.html'
+  );
+}
+
+export function buildPayload(cwd: string, current: DashboardSnapshot): DashboardPayload {
+  const all = readHistory(cwd);
+  // Exclude `current` from history if it's been written there already.
+  const history = all.filter((s) => s.runId !== current.runId);
+  return { current, history };
+}
+
+export interface RenderResult {
+  outputPath: string;
+  bytes: number;
+}
+
+/**
+ * Render `payload` into the template and write to qa/dashboard/index.html.
+ */
+export function renderDashboardHtml(cwd: string, payload: DashboardPayload): RenderResult {
+  const templatePath = resolveTemplatePath();
+  const template = fs.readFileSync(templatePath, 'utf-8');
+
+  const json = JSON.stringify(payload);
+  const replaced = injectPayload(template, json);
+
+  const outDir = path.join(cwd, 'qa', 'dashboard');
+  fs.mkdirSync(outDir, { recursive: true });
+  const outputPath = path.join(outDir, 'index.html');
+  fs.writeFileSync(outputPath, replaced, 'utf-8');
+
+  return { outputPath, bytes: Buffer.byteLength(replaced, 'utf-8') };
+}
+
+function injectPayload(template: string, json: string): string {
+  const start = template.indexOf(PAYLOAD_TAG_OPEN);
+  if (start === -1) {
+    throw new Error(
+      `Template is missing the payload placeholder ${PAYLOAD_TAG_OPEN}…${PAYLOAD_TAG_CLOSE}`
+    );
+  }
+  const contentStart = start + PAYLOAD_TAG_OPEN.length;
+  const contentEnd = template.indexOf(PAYLOAD_TAG_CLOSE, contentStart);
+  if (contentEnd === -1) {
+    throw new Error('Template payload placeholder is unterminated');
+  }
+  // Escape </script> inside JSON to prevent breaking the surrounding script tag.
+  const safe = json.replace(/<\/script>/gi, '<\\/script>');
+  return template.slice(0, contentStart) + safe + template.slice(contentEnd);
+}

package/src/dashboard/snapshot-builder.ts

@@ -0,0 +1,273 @@
+/**
+ * Orchestrate dashboard snapshot construction across all screens/flows.
+ *
+ * Inputs are read from the same on-disk sources used by `sungen delivery`:
+ *   qa/screens/<name>/...        feature, test-data, selectors, requirements
+ *   qa/flows/<name>/...
+ *   specs/generated/<...>/...    compiled .spec.ts + per-target test-result.json
+ *   test-results/results.json    global fallback
+ *
+ * Output is a DashboardSnapshot ready to be embedded in HTML or written as
+ * a history entry under qa/dashboard/history/<runId>.json.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import { parseFeatureMetadata } from '../exporters/feature-parser';
+import { parseSpecFile } from '../exporters/spec-parser';
+import { loadTestData } from '../exporters/test-data-resolver';
+import { loadPlaywrightReport } from '../exporters/playwright-report-parser';
+import { mergeFeatureAndSpec } from '../exporters/scenario-merger';
+import { buildScreenSnapshot } from '../exporters/json-exporter';
+import { getPackageVersion } from '../exporters/package-info';
+import { EnvironmentInfo } from '../exporters/types';
+import {
+  AggregateSummary,
+  DashboardSnapshot,
+  ScenarioSnapshot,
+  ScreenSnapshot,
+  SNAPSHOT_VERSION,
+} from './types';
+
+export interface DashboardTarget {
+  name: string;
+  isFlow: boolean;
+}
+
+export interface BuildSnapshotOptions {
+  cwd: string;
+  targets: DashboardTarget[];
+  env: EnvironmentInfo;
+  /** Skip targets where the .feature/.spec.ts pair fails to parse. */
+  continueOnError?: boolean;
+}
+
+export function buildDashboardSnapshot(options: BuildSnapshotOptions): DashboardSnapshot {
+  const { cwd, targets, env } = options;
+  const screens: ScreenSnapshot[] = [];
+
+  for (const target of targets) {
+    try {
+      const screen = buildOneScreen(cwd, target, env);
+      if (screen) screens.push(screen);
+    } catch (err) {
+      if (!options.continueOnError) throw err;
+      // eslint-disable-next-line no-console
+      console.warn(`[dashboard] skipping ${target.name}: ${(err as Error).message}`);
+    }
+  }
+
+  const now = new Date();
+  return {
+    version: SNAPSHOT_VERSION,
+    runId: makeRunId(now),
+    generatedAt: toLocalIso(now),
+    environment: collectEnvironment(cwd, env),
+    summary: aggregateSummary(screens),
+    screens: screens.sort((a, b) => a.name.localeCompare(b.name)),
+  };
+}
+
+// ----------------------------------------------------------------------------
+// Per-target build
+// ----------------------------------------------------------------------------
+
+function buildOneScreen(
+  cwd: string,
+  target: DashboardTarget,
+  env: EnvironmentInfo
+): ScreenSnapshot | null {
+  const base = qaDir(cwd, target);
+  const genBase = generatedDir(cwd, target);
+  const featureFile = path.join(base, 'features', `${target.name}.feature`);
+  const testDataFile = path.join(base, 'test-data', `${target.name}.yaml`);
+  const specFile = path.join(genBase, `${target.name}.spec.ts`);
+  const specMdFile = path.join(base, 'requirements', 'spec.md');
+  const resultsFile = resolveResultsPath(cwd, target);
+
+  if (!fs.existsSync(featureFile)) return null;
+
+  const feature = parseFeatureMetadata(featureFile);
+  const spec = fs.existsSync(specFile)
+    ? parseSpecFile(specFile)
+    : { tests: [] };
+  const testData = fs.existsSync(testDataFile) ? loadTestData(testDataFile) : {};
+  const results = resultsFile ? loadPlaywrightReport(resultsFile) : null;
+
+  const merged = mergeFeatureAndSpec(feature, spec);
+  const label = target.isFlow ? `flow/${target.name}` : target.name;
+  const specLink = fs.existsSync(specMdFile) ? path.relative(cwd, specMdFile) : undefined;
+
+  return buildScreenSnapshot({
+    screen: label,
+    isFlow: target.isFlow,
+    featureName: feature.featureName,
+    featurePath: feature.featurePath,
+    specLink,
+    merged,
+    testData,
+    results,
+    env,
+  });
+}
+
+// ----------------------------------------------------------------------------
+// Aggregate summary across all screens
+// ----------------------------------------------------------------------------
+
+function aggregateSummary(screens: ScreenSnapshot[]): AggregateSummary {
+  const summary: AggregateSummary = {
+    total: 0,
+    passed: 0,
+    failed: 0,
+    pending: 0,
+    na: 0,
+    notCompiled: 0,
+    passRate: 0,
+    byPriority: { Critical: 0, High: 0, Normal: 0, Low: 0 },
+    byCategory: { Accessing: 0, GUI: 0, Function: 0 },
+    byType: { Auto: 0, Manual: 0, 'Not compiled': 0 },
+  };
+
+  for (const screen of screens) {
+    summary.total += screen.summary.total;
+    summary.passed += screen.summary.passed;
+    summary.failed += screen.summary.failed;
+    summary.pending += screen.summary.pending;
+    summary.na += screen.summary.na;
+    summary.notCompiled += screen.summary.notCompiled;
+
+    for (const s of screen.scenarios) {
+      bumpKey(summary.byPriority, s.priority);
+      bumpKey(summary.byCategory, s.category2);
+      bumpKey(summary.byType, s.type);
+    }
+  }
+
+  const executed = summary.passed + summary.failed;
+  summary.passRate = executed > 0 ? summary.passed / executed : 0;
+  return summary;
+}
+
+function bumpKey(record: Record<string, number>, key: string): void {
+  record[key] = (record[key] ?? 0) + 1;
+}
+
+// ----------------------------------------------------------------------------
+// Path helpers (mirror delivery.ts to stay consistent)
+// ----------------------------------------------------------------------------
+
+function qaDir(cwd: string, target: DashboardTarget): string {
+  return path.join(cwd, 'qa', target.isFlow ? 'flows' : 'screens', target.name);
+}
+
+function generatedDir(cwd: string, target: DashboardTarget): string {
+  return target.isFlow
+    ? path.join(cwd, 'specs', 'generated', 'flows', target.name)
+    : path.join(cwd, 'specs', 'generated', target.name);
+}
+
+function resolveResultsPath(cwd: string, target: DashboardTarget): string | null {
+  const genDir = generatedDir(cwd, target);
+  const perTarget = path.join(genDir, `${target.name}-test-result.json`);
+  if (fs.existsSync(perTarget)) return perTarget;
+  const global = path.join(cwd, 'test-results', 'results.json');
+  if (fs.existsSync(global)) return global;
+  return null;
+}
+
+// ----------------------------------------------------------------------------
+// Discovery (also used by CLI)
+// ----------------------------------------------------------------------------
+
+export function listDashboardTargets(cwd: string): DashboardTarget[] {
+  const targets: DashboardTarget[] = [];
+
+  const screensDir = path.join(cwd, 'qa', 'screens');
+  if (fs.existsSync(screensDir)) {
+    for (const d of fs.readdirSync(screensDir, { withFileTypes: true })) {
+      if (d.isDirectory()) targets.push({ name: d.name, isFlow: false });
+    }
+  }
+
+  const flowsDir = path.join(cwd, 'qa', 'flows');
+  if (fs.existsSync(flowsDir)) {
+    for (const d of fs.readdirSync(flowsDir, { withFileTypes: true })) {
+      if (d.isDirectory()) targets.push({ name: d.name, isFlow: true });
+    }
+  }
+
+  return targets.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function resolveTargetType(cwd: string, name: string): DashboardTarget {
+  if (fs.existsSync(path.join(cwd, 'qa', 'flows', name))) {
+    return { name, isFlow: true };
+  }
+  return { name, isFlow: false };
+}
+
+// ----------------------------------------------------------------------------
+// Run ID + environment metadata (Vietnam Indochina Time, UTC+7, no DST)
+// ----------------------------------------------------------------------------
+
+const VN_OFFSET_MS = 7 * 60 * 60 * 1000;
+
+/**
+ * Filename-safe ISO timestamp in Vietnam time (UTC+7).
+ * Example: 2026-04-29T08-13-53+0700
+ *
+ * Colons in HH:MM:SS are replaced with `-` (filename-safe on Windows too).
+ * The `+0700` suffix makes the offset explicit so consumers don't need
+ * to assume a default timezone.
+ */
+function makeRunId(now: Date): string {
+  const vn = new Date(now.getTime() + VN_OFFSET_MS);
+  const yyyy = vn.getUTCFullYear();
+  const MM = String(vn.getUTCMonth() + 1).padStart(2, '0');
+  const dd = String(vn.getUTCDate()).padStart(2, '0');
+  const HH = String(vn.getUTCHours()).padStart(2, '0');
+  const mm = String(vn.getUTCMinutes()).padStart(2, '0');
+  const ss = String(vn.getUTCSeconds()).padStart(2, '0');
+  return `${yyyy}-${MM}-${dd}T${HH}-${mm}-${ss}+0700`;
+}
+
+/**
+ * Full ISO 8601 timestamp in Vietnam time, with milliseconds and `+07:00` offset.
+ * Example: 2026-04-29T08:13:53.495+07:00
+ */
+function toLocalIso(now: Date): string {
+  const vn = new Date(now.getTime() + VN_OFFSET_MS);
+  const yyyy = vn.getUTCFullYear();
+  const MM = String(vn.getUTCMonth() + 1).padStart(2, '0');
+  const dd = String(vn.getUTCDate()).padStart(2, '0');
+  const HH = String(vn.getUTCHours()).padStart(2, '0');
+  const mm = String(vn.getUTCMinutes()).padStart(2, '0');
+  const ss = String(vn.getUTCSeconds()).padStart(2, '0');
+  const ms = String(vn.getUTCMilliseconds()).padStart(3, '0');
+  return `${yyyy}-${MM}-${dd}T${HH}:${mm}:${ss}.${ms}+07:00`;
+}
+
+function collectEnvironment(cwd: string, env: EnvironmentInfo) {
+  let gitBranch: string | undefined;
+  let gitSha: string | undefined;
+  try {
+    gitBranch = execSync('git rev-parse --abbrev-ref HEAD', { cwd, encoding: 'utf-8' }).trim();
+  } catch { /* ignore */ }
+  try {
+    gitSha = execSync('git rev-parse --short HEAD', { cwd, encoding: 'utf-8' }).trim();
+  } catch { /* ignore */ }
+
+  return {
+    baseURL: env.baseURL,
+    projectName: env.projectName,
+    executor: env.executor,
+    sungenVersion: getPackageVersion(),
+    gitBranch,
+    gitSha,
+  };
+}
+
+// Helper for ScenarioSnapshot tree filters in UI (re-exported for callers)
+export type { ScenarioSnapshot };