@sun-asterisk/sungen 3.1.0 → 3.1.2-beta.100

package/src/cli/index.ts

@@ -26,6 +26,8 @@ import { registerChallengeCommand } from './commands/challenge';
 import { registerBlindspotCommand } from './commands/blindspot';
 import { registerCapabilityCommand } from './commands/capability';
 import { registerFlowCheckCommand } from './commands/flow-check';
+import { capabilityRegistry } from '../capabilities/registry';
+import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 
 // Read version from package.json so `--version` never drifts from the released version.
 const { version } = require('../../package.json') as { version: string };
@@ -42,7 +44,7 @@ async function main() {
   program
     .option('-v, --verbose', 'Enable verbose logging');
 
-  // Register commands (9)
+  // Register commands
   registerInitCommand(program);
   registerAddCommand(program);
   registerGenerateCommand(program);
@@ -65,6 +67,13 @@ async function main() {
   registerIngestCommand(program);
   registerEvalCommand(program);
 
+  // Capability-contributed CLI commands (Capability SPI): drivers own their authoring commands
+  // (e.g. @sungen/driver-api → `sungen api import`). Discover, then register each.
+  discoverAndRegisterCapabilities();
+  for (const cap of capabilityRegistry.all()) {
+    for (const registerCommand of cap.cliCommands ?? []) registerCommand(program);
+  }
+
   await program.parseAsync(process.argv);
 }
 

package/src/exporters/csv-exporter.ts

@@ -53,7 +53,25 @@ export function buildTestCaseRows(input: BuildCsvInput): TestCaseRow[] {
   let fallbackIndex = 1;
 
   for (const m of input.merged) {
-    const { vpId, category1 } = splitVpAndName(m.feature.name);
+    // Data-driven (@cases): one scenario ran once per input row — emit one CSV row per
+    // executed input. The Playwright results are titled "<scenario> — <label>"; expand
+    // by matching that prefix. With no results yet, fall back to a single (Pending) row.
+    const isCases = m.feature.tags.some((t) => t.startsWith('@cases:'));
+    let variants: Array<{ nameSuffix: string; result?: PlaywrightResult }> = [{ nameSuffix: '' }];
+    if (isCases && input.results) {
+      // Result titles are "<describe> > <scenario> — <label>"; match the scenario+label marker.
+      const marker = `${m.feature.name} — `;
+      const rowResults = [...input.results.entries()].filter(([t]) => t.includes(marker));
+      if (rowResults.length) {
+        variants = rowResults.map(([t, r]) => ({ nameSuffix: ` — ${t.slice(t.indexOf(marker) + marker.length)}`, result: r }));
+      }
+    } else if (input.results && m.spec) {
+      variants = [{ nameSuffix: '', result: input.results.get(m.spec.testTitle) }];
+    }
+
+   for (const variant of variants) {
+    const displayName = `${m.feature.name}${variant.nameSuffix}`;
+    const { vpId, category1 } = splitVpAndName(displayName);
     const tcId = generateTcId(input.screen, vpId, fallbackIndex);
     if (!vpId) fallbackIndex++;
 
@@ -87,11 +105,8 @@ export function buildTestCaseRows(input: BuildCsvInput): TestCaseRow[] {
     // automatically) and render natively as multi-line in XLSX.
     const testData = formatTestData(m.feature.referencedVars, input.testData, Infinity, '\n');
 
-    // Match Playwright result by test title (from .spec.ts) OR by scenarioName
-    let result: PlaywrightResult | undefined;
-    if (input.results && m.spec) {
-      result = input.results.get(m.spec.testTitle);
-    }
+    // Status for this (possibly per-input) row — resolved into `variant` above.
+    const result: PlaywrightResult | undefined = variant.result;
 
     // Determine Test Result
     let testResult: string;
@@ -141,6 +156,7 @@ export function buildTestCaseRows(input: BuildCsvInput): TestCaseRow[] {
       testEnvironment: environment,
       note,
     });
+   }
   }
 
   return rows;

package/src/exporters/spec-parser.ts

@@ -20,7 +20,12 @@ function extractTestBlock(content: string, startIdx: number): {
   //   test('title', { tag: [...] }, async ({ page }) => {
   // Backreference \1 lets the inner title contain the opposite quote type
   // (e.g. test('Footer "X" link', ...) — common when scenarios cite UI labels).
-  const testRegex = /test\s*\(\s*(['"])((?:(?!\1).)+)\1\s*,\s*(?:\{[^}]*\}\s*,\s*)?async\s*\([^)]*\)\s*=>\s*\{/g;
+  // Quote char may be ' " or ` — the backtick form is a data-driven (@cases) title
+  // like `VP-… — ${__row.__label}`.
+  // The options object uses `\{.*?\}` (non-greedy, not `[^}]*`) so a tag value containing a
+  // `}` — e.g. `@query:q(p={{var}})` — doesn't truncate the match (issue #271). The header is
+  // single-line, so `.*?` anchored on `}, async` is safe.
+  const testRegex = /test\s*\(\s*(['"`])((?:(?!\1).)+)\1\s*,\s*(?:\{.*?\}\s*,\s*)?async\s*\([^)]*\)\s*=>\s*\{/g;
   testRegex.lastIndex = startIdx;
   const match = testRegex.exec(content);
   if (!match) return null;

package/src/generators/test-generator/adapters/adapter-interface.ts

@@ -36,6 +36,7 @@ export interface ScenarioData {
   authRole?: string; // Auth role for storage state
   isParallel?: boolean; // @parallel: use fresh page from fixture
   tags?: string; // Pass-through tags for Playwright { tag: [...] }, e.g. "'@smoke', '@high'"
+  casesDataset?: string; // @cases:<dataset> — emit one test() per row of the runtime dataset
 }
 
 export interface StepTemplateData {
@@ -63,7 +64,7 @@ export interface TestGeneratorAdapter {
   // Template rendering methods
   renderTestFile(data: TestFileData): string;
   renderScenario(data: ScenarioData): string;
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean }): string;
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean }): string;
   renderBeforeEach(data: { steps: Array<{ comment?: string; code: string }> }): string;
   renderBeforeAll(data: { steps: Array<{ comment?: string; code: string }> }): string;
   renderAfterEach(data: { steps: Array<{ comment?: string; code: string }> }): string;

package/src/generators/test-generator/adapters/playwright/playwright-adapter.ts

@@ -26,7 +26,7 @@ export class PlaywrightAdapter implements TestGeneratorAdapter {
     return this.templateEngine.renderScenario(data);
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean }): string {
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean }): string {
     return this.templateEngine.renderImports(options);
   }
 

package/src/generators/test-generator/adapters/playwright/templates/imports.hbs

@@ -6,6 +6,9 @@ import { TestDataLoader } from '{{basePath}}/test-data';
 {{#if needsDb}}
 import { db } from '{{basePath}}/db';
 {{/if}}
+{{#if needsApi}}
+import { api } from '{{basePath}}/api';
+{{/if}}
 
 // This file is auto-generated from Gherkin feature files
 // DO NOT EDIT MANUALLY - changes will be overwritten

package/src/generators/test-generator/adapters/playwright/templates/scenario.hbs

@@ -1,3 +1,20 @@
+{{#if casesDataset}}
+  for (const __row of testData.cases('{{casesDataset}}')) {
+{{#if tags}}
+  test(`{{scenarioName}} — ${__row.__label}`, { tag: [{{{tags}}}] }, async ({{#if isParallel}}{ page }{{/if}}) => {
+{{else}}
+  test(`{{scenarioName}} — ${__row.__label}`, async ({{#if isParallel}}{ page }{{/if}}) => {
+{{/if}}
+    const rowData = testData.withRow(__row);
+{{#each steps}}
+{{#if comment}}
+    // {{comment}}
+{{/if}}
+{{code}}
+{{/each}}
+  });
+  }
+{{else}}
 {{#if isParallel}}
 {{#if tags}}
   test('{{scenarioName}}', { tag: [{{{tags}}}] }, async ({ page }) => {
@@ -24,4 +41,5 @@
 {{code}}
 {{/each}}
   });
-{{/if}}
+{{/if}}
+{{/if}}

package/src/generators/test-generator/code-generator.ts

@@ -4,7 +4,8 @@ import { ParsedFeature, ParsedScenario, ParsedStep } from '../gherkin-parser';
 import { StepMapper } from './step-mapper';
 import { TestGeneratorAdapter, adapterRegistry } from './adapters';
 import { transformToRuntimeData } from './utils/runtime-data-transformer';
-import { isDbStep } from './patterns/database-patterns';
+import { capabilityRegistry } from '../../capabilities/registry';
+import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 
 /**
  * Filter base scenario steps for @extend: only keep Given→When steps.
@@ -74,7 +75,7 @@ function extractCleanupFlags(tags: string[]): { overlay?: boolean; forms?: boole
 const FUNCTIONAL_TAG_PREFIXES = [
   '@parallel', '@cleanup:', '@auth:', '@manual', '@no-auth',
   '@steps:', '@extend:', '@screenshot:', '@beforeAll', '@afterEach', '@afterAll',
-  '@flow',
+  '@flow', '@cases:',
 ];
 
 function extractPassThroughTags(scenarioTags: string[], featureTags: string[]): string | undefined {
@@ -170,6 +171,8 @@ export class CodeGenerator {
   private adapter: TestGeneratorAdapter;
   private screenName?: string;
   private options: any;
+  // Screen/flow name for the CURRENT feature, in catalog-resolution form (`flows/<x>` for flows).
+  private queryScreenName: string = '';
   // Steps registry built per feature during generateTestCode(); used by countSteps()
   private stepsRegistry = new Map<string, ParsedScenario>();
 
@@ -237,11 +240,17 @@ export class CodeGenerator {
     const hasCleanupTags = (feature.tags || []).some(t => t.startsWith('@cleanup:'));
     const needsCleanupImport = !isParallelFeature && hasCleanupTags;
 
-    // Data Driver: if any step verifies DB state, import the `db` helper + emit specs/db.ts
-    const needsDb = this.featureUsesDb(feature);
-    if (needsDb) this.ensureDbFile(outputDir);
+    // Active capabilities for this feature (registry-driven): the default UI + any whose annotation
+    // tags appear (@query) or whose detectsStep matches (declarative DB steps). Each active
+    // capability emits its declared runtime helpers (db → specs/db.ts).
+    const activeCapabilityIds = this.activeCapabilityIds(feature);
+    const needsDb = activeCapabilityIds.includes('db');
+    const needsApi = activeCapabilityIds.includes('api');
+    for (const id of activeCapabilityIds) {
+      for (const h of capabilityRegistry.get(id)?.runtimeHelpers ?? []) this.syncGeneratedHelper(outputDir, h.file, h.template);
+    }
 
-    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport, needsDb });
+    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport, needsDb, needsApi });
 
     // Generate test code (async now to support AI mapping)
     const testCode = await this.generateTestCode(feature);
@@ -297,67 +306,68 @@ export class CodeGenerator {
   /**
    * Ensure specs/base.ts exists in the output directory
    */
-  /** True when any step (background or scenario) in the feature is a DB-verification step. */
-  private featureUsesDb(feature: ParsedFeature): boolean {
+  /**
+   * Capabilities active for a feature (registry-driven): the default (UI) capability, plus any
+   * whose annotation tags appear on a scenario (e.g. `@query` → db) or whose `detectsStep`
+   * matches a step (db's declarative `User see [table] row where …`). Drives runtime-helper
+   * emission + the `db` import — replaces the hardcoded `featureUsesDb` check (R4).
+   */
+  private activeCapabilityIds(feature: ParsedFeature): string[] {
+    discoverAndRegisterCapabilities();
     const steps: ParsedStep[] = [];
     if (feature.background?.steps) steps.push(...feature.background.steps);
     for (const sc of feature.scenarios || []) if (sc.steps) steps.push(...sc.steps);
-    return steps.some((s) => s && typeof s.text === 'string' && isDbStep(s.text));
+    const scenarioTags = (feature.scenarios || []).flatMap((sc) => sc.tags || []);
+    const ids = new Set<string>();
+    const def = capabilityRegistry.defaultCapabilityId();
+    if (def) ids.add(def);
+    for (const cap of capabilityRegistry.all()) {
+      const annoMatch = (cap.annotations ?? []).some((a) => scenarioTags.some((t) => t === a || t.startsWith(a + ':')));
+      const stepMatch = cap.detectsStep ? steps.some((s) => s && typeof s.text === 'string' && cap.detectsStep!(s.text)) : false;
+      if (annoMatch || stepMatch) ids.add(cap.id);
+    }
+    return [...ids];
   }
 
-  /** Copy the Data Driver runtime helper into specs/db.ts (idempotent). */
-  ensureDbFile(outputDir: string): void {
-    const templatesRoot = path.join(__dirname, '..', '..', 'orchestrator', 'templates');
-    const dbPath = path.join(outputDir, 'db.ts');
-    if (!fs.existsSync(dbPath)) {
-      const templatePath = path.join(templatesRoot, 'specs-db.ts');
-      if (fs.existsSync(templatePath)) {
-        if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
-        fs.copyFileSync(templatePath, dbPath);
-        console.log('✓ Created: specs/db.ts');
-      }
-    }
+  /**
+   * Precondition steps a scenario's capabilities inject (e.g. db `@query:<name>` → bind {{name}}).
+   * Each capability owns its annotation codegen via the SPI (`preconditionCodegen`); the compiler
+   * just composes + indents the returned statements (R4).
+   */
+  private capabilityPreconditions(scenario: ParsedScenario): Array<{ comment?: string; code: string; boundVars?: string[] }> {
+    discoverAndRegisterCapabilities();
+    const out: Array<{ comment?: string; code: string; boundVars?: string[] }> = [];
+    for (const cap of capabilityRegistry.all()) {
+      if (!cap.preconditionCodegen) continue;
+      out.push(...cap.preconditionCodegen({ tags: scenario.tags || [], screenName: this.queryScreenName, cwd: process.cwd() }));
+    }
+    return out;
   }
 
-  ensureBaseFile(outputDir: string): void {
-    const templatesRoot = path.join(__dirname, '..', '..', 'orchestrator', 'templates');
-
-    const basePath = path.join(outputDir, 'base.ts');
-    if (!fs.existsSync(basePath)) {
-      const templatePath = path.join(templatesRoot, 'specs-base.ts');
-      if (fs.existsSync(templatePath)) {
-        const baseDir = path.dirname(basePath);
-        if (!fs.existsSync(baseDir)) {
-          fs.mkdirSync(baseDir, { recursive: true });
-        }
-        fs.copyFileSync(templatePath, basePath);
-        console.log('✓ Created: specs/base.ts');
-      }
-    }
-
-    // base.ts now depends on locale-fixture.ts — keep them paired.
-    const localeFixturePath = path.join(outputDir, 'locale-fixture.ts');
-    if (!fs.existsSync(localeFixturePath)) {
-      const templatePath = path.join(templatesRoot, 'specs-locale-fixture.ts');
-      if (fs.existsSync(templatePath)) {
-        const baseDir = path.dirname(localeFixturePath);
-        if (!fs.existsSync(baseDir)) {
-          fs.mkdirSync(baseDir, { recursive: true });
-        }
-        fs.copyFileSync(templatePath, localeFixturePath);
-        console.log('✓ Created: specs/locale-fixture.ts');
-      }
-    }
+  /**
+   * Copy an auto-generated runtime helper into specs/, **refreshing it when the template changed**.
+   * These files carry a `DO NOT EDIT — regenerated` header, so a stale copy left by an older sungen
+   * (e.g. a `specs/db.ts` from before a feature was added) is replaced instead of kept (issue #270).
+   * No-ops when the on-disk content already matches the template, so it stays quiet + idempotent.
+   */
+  private syncGeneratedHelper(outputDir: string, fileName: string, templateName: string): void {
+    const templatePath = path.join(__dirname, '..', '..', 'orchestrator', 'templates', templateName);
+    if (!fs.existsSync(templatePath)) return;
+    const targetPath = path.join(outputDir, fileName);
+    const next = fs.readFileSync(templatePath, 'utf8');
+    const exists = fs.existsSync(targetPath);
+    if (exists && fs.readFileSync(targetPath, 'utf8') === next) return; // already current
+    if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
+    fs.writeFileSync(targetPath, next);
+    console.log(`✓ ${exists ? 'Updated' : 'Created'}: specs/${fileName}`);
+  }
 
+  ensureBaseFile(outputDir: string): void {
+    this.syncGeneratedHelper(outputDir, 'base.ts', 'specs-base.ts');
+    // base.ts depends on locale-fixture.ts — keep them paired.
+    this.syncGeneratedHelper(outputDir, 'locale-fixture.ts', 'specs-locale-fixture.ts');
     if (this.options.runtimeData) {
-      const testDataPath = path.join(outputDir, 'test-data.ts');
-      if (!fs.existsSync(testDataPath)) {
-        const templatePath = path.join(templatesRoot, 'specs-test-data.ts');
-        if (fs.existsSync(templatePath)) {
-          fs.copyFileSync(templatePath, testDataPath);
-          console.log('✓ Created: specs/test-data.ts');
-        }
-      }
+      this.syncGeneratedHelper(outputDir, 'test-data.ts', 'specs-test-data.ts');
     }
   }
 
@@ -391,6 +401,8 @@ export class CodeGenerator {
       }
       this.stepMapper.setScreenContext(effectiveScreenName);
     }
+    // Catalog-resolution screen name for @query binds (flows are prefixed `flows/`).
+    this.queryScreenName = isFlowFeature ? `flows/${effectiveScreenName}` : (effectiveScreenName || '');
 
     // Reset flow mode per feature to prevent state leak in --all mode
     this.stepMapper.setFlowMode(isFlowFeature);
@@ -637,6 +649,33 @@ export class CodeGenerator {
     // Set scenario context for path variable resolution (full merged list)
     this.stepMapper.setScenarioContext(stepsToMap);
 
+    // Data-driven (@cases): the scenario's {{col}} refs are dataset *row columns* that
+    // exist only at runtime — register them as captured so they resolve to a runtime
+    // get() (→ rowData.get) instead of compile-time YAML lookup.
+    const casesTag = scenario.tags.find((t) => t.startsWith('@cases:'));
+    const casesDataset = casesTag ? casesTag.slice('@cases:'.length).trim() : undefined;
+    if (casesDataset) {
+      const refs = new Set<string>();
+      for (const st of stepsToMap) {
+        for (const m of (st.text || '').matchAll(/\{\{\s*([\w.]+)\s*\}\}/g)) refs.add(m[1]);
+      }
+      for (const r of refs) this.stepMapper.registerCaptured(r);
+    }
+
+    // Capability preconditions (db `@query:<name>` → bind {{name}}) are owned by the capability via
+    // the SPI. Their bound `{{name.*}}` vars exist only at runtime → register them as captured so
+    // they resolve to a runtime get() instead of a compile-time YAML lookup that would fail.
+    const preconditions = this.capabilityPreconditions(scenario);
+    const boundVars = preconditions.flatMap((p) => p.boundVars || []);
+    if (boundVars.length) {
+      for (const st of stepsToMap) {
+        for (const mt of (st.text || '').matchAll(/\{\{\s*([^}]+?)\s*\}\}/g)) {
+          const head = mt[1].split(/[.[]/)[0];
+          if (boundVars.includes(head)) this.stepMapper.registerCaptured(mt[1]);
+        }
+      }
+    }
+
     const steps: Array<{ comment?: string; code: string }> = [];
 
     if (scenario.extendsName && this.stepsRegistry.has(scenario.extendsName)) {
@@ -666,17 +705,33 @@ export class CodeGenerator {
       }
     }
 
+    // Capability preconditions (db `@query:<name>` → bind {{name}}; computed above) run BEFORE the
+    // scenario's own steps — prepend them, indenting the capability-supplied statements.
+    if (preconditions.length) {
+      steps.unshift(...preconditions.map((p) => ({ comment: p.comment, code: this.indentCode(p.code, 4) })));
+    }
+
     // Extract pass-through tags (feature + scenario, excluding functional tags)
     const tags = extractPassThroughTags(scenario.tags, featureTags);
 
     // Use adapter to render scenario
-    return this.adapter.renderScenario({
+    const rendered = this.adapter.renderScenario({
       scenarioName: scenario.name,
       steps,
       authRole,
       isParallel,
       tags,
+      casesDataset,
     });
+
+    // Data-driven (@cases): the per-row test() binds a row-scoped view (`rowData`).
+    // Pre-transform THIS scenario's runtime-data markers to read from `rowData`, so the
+    // global `testData` transform that runs next on the rest of the file leaves it alone.
+    // The loop header's `testData.cases()/withRow()` are literal code (no markers) → untouched.
+    if (casesDataset && this.options.runtimeData) {
+      return transformToRuntimeData(rendered, 'rowData');
+    }
+    return rendered;
   }
 
   /**

package/src/generators/test-generator/patterns/expect-patterns.ts

@@ -0,0 +1,49 @@
+import { ParsedStep } from '../../gherkin-parser';
+import { StepPattern, PatternContext } from './types';
+import { MappedStep } from '../step-mapper';
+
+/**
+ * Data-vs-data assertions — compare two runtime values directly (no UI element).
+ * The primary use is asserting on an `@query`-bound result via path access, e.g.
+ *
+ *   Then expect {{products.count}} is {{expected}}
+ *   Then expect {{products.count}} is at least {{one}}
+ *   Then expect {{active_user.status}} is "active"
+ *   Then expect {{order.total}} is not {{zero}}
+ *
+ * Both sides are `{{var|path}}` | "literal" | 'literal' | number. Generic — works for any
+ * test-data values, not only DB results.
+ */
+const VALUE = String.raw`\{\{[^}]+\}\}|"[^"]*"|'[^']*'|-?\d+(?:\.\d+)?`;
+const reExpect = new RegExp(`^\\s*(?:User\\s+)?expect\\s+(${VALUE})\\s+is\\s+(not\\s+|at\\s+least\\s+|at\\s+most\\s+)?(${VALUE})\\s*$`, 'i');
+
+/** Render a value token (`{{var}}` | "literal" | 'literal' | number) as a JS expression. */
+function valueExpr(token: string): string {
+  const t = token.trim();
+  const v = t.match(/^\{\{\s*([^}]+?)\s*\}\}$/);
+  if (v) return `testData.get(${JSON.stringify(v[1])})`;
+  const q = t.match(/^["'](.*)["']$/);
+  if (q) return JSON.stringify(q[1]);
+  if (/^-?\d+(?:\.\d+)?$/.test(t)) return t;
+  return JSON.stringify(t);
+}
+
+export const expectPatterns: StepPattern[] = [
+  {
+    name: 'expect-data',
+    priority: 62, // above generic see-assertions; sibling of the DB assertions
+    matcher: (step: ParsedStep) => reExpect.test(step.text),
+    generator: (step: ParsedStep, _ctx: PatternContext): MappedStep => {
+      const m = step.text.match(reExpect)!;
+      const a = valueExpr(m[1]);
+      const op = (m[2] || '').trim().toLowerCase();
+      const b = valueExpr(m[3]);
+      let code: string;
+      if (op === 'at least') code = `expect(Number(${a})).toBeGreaterThanOrEqual(Number(${b}));`;
+      else if (op === 'at most') code = `expect(Number(${a})).toBeLessThanOrEqual(Number(${b}));`;
+      else if (op === 'not') code = `expect(String(${a})).not.toBe(String(${b}));`;
+      else code = `expect(String(${a})).toBe(String(${b}));`;
+      return { code, comment: `Expect ${m[1]} ${op ? op + ' ' : 'is '}${m[3]}` };
+    },
+  },
+];

package/src/generators/test-generator/patterns/index.ts

@@ -1,17 +1,8 @@
 import { ParsedStep } from '../../gherkin-parser';
 import { MappedStep } from '../step-mapper';
 import { StepPattern, PatternContext } from './types';
-import { navigationPatterns } from './navigation-patterns';
-import { formPatterns } from './form-patterns';
-import { interactionPatterns } from './interaction-patterns';
-import { assertionPatterns } from './assertion-patterns';
-import { setupPatterns } from './setup-patterns';
-import { keyboardPatterns } from './keyboard-patterns';
-import { scrollPatterns } from './scroll-patterns';
-import { scopePatterns } from './scope-patterns';
-import { tablePatterns } from './table-patterns';
-import { capturePatterns } from './capture-patterns';
-import { databasePatterns } from './database-patterns';
+import { capabilityRegistry } from '../../../capabilities/registry';
+import { discoverAndRegisterCapabilities } from '../../../capabilities/discover';
 
 /**
  * Pattern Registry - manages all step patterns
@@ -27,17 +18,11 @@ export class PatternRegistry {
    * Register default patterns from all pattern modules
    */
   private registerDefaultPatterns(): void {
-    this.patterns.push(...setupPatterns);
-    this.patterns.push(...navigationPatterns);
-    this.patterns.push(...formPatterns);
-    this.patterns.push(...interactionPatterns);
-    this.patterns.push(...assertionPatterns);
-    this.patterns.push(...keyboardPatterns);
-    this.patterns.push(...scrollPatterns);
-    this.patterns.push(...scopePatterns);
-    this.patterns.push(...tablePatterns);
-    this.patterns.push(...capturePatterns);
-    this.patterns.push(...databasePatterns);
+    // Patterns are composed from the capability registry (Capability SPI, R1) instead of a
+    // hardcoded push list. Built-ins (ui · db · core) register the same set as before, so the
+    // composed list + priority sort is behaviour-identical (golden snapshots are the contract).
+    discoverAndRegisterCapabilities();
+    this.patterns.push(...capabilityRegistry.patterns());
 
     // Sort by priority (higher first)
     this.patterns.sort((a, b) => (b.priority || 0) - (a.priority || 0));
@@ -157,15 +142,6 @@ export class PatternRegistry {
   }
 }
 
-// Export pattern modules for advanced usage
-export { setupPatterns } from './setup-patterns';
-export { navigationPatterns } from './navigation-patterns';
-export { formPatterns } from './form-patterns';
-export { interactionPatterns } from './interaction-patterns';
-export { assertionPatterns } from './assertion-patterns';
-export { keyboardPatterns } from './keyboard-patterns';
-export { scrollPatterns } from './scroll-patterns';
-export { scopePatterns } from './scope-patterns';
-export { tablePatterns } from './table-patterns';
-export { databasePatterns, isDbStep } from './database-patterns';
+// The UI step patterns now live in @sungen/driver-ui (R5.4) and the DB patterns in @sungen/driver-db
+// (R5.5); both are contributed via the capability registry, not re-exported here.
 export * from './types';

package/src/generators/test-generator/step-mapper.ts

@@ -94,6 +94,15 @@ export class StepMapper {
     this.templateEngine.resetBaseContext();
   }
 
+  /**
+   * Register a runtime data variable so `{{name}}` resolves to `testData.get('name')`
+   * (skipping compile-time YAML validation). Used for @cases row columns, which exist
+   * only at runtime in the dataset rows. Scenario-scoped (cleared by setScenarioContext).
+   */
+  registerCaptured(name: string): void {
+    this.dataResolver.registerCaptured(name);
+  }
+
   /**
    * Map a Gherkin step to Playwright code
    * Uses pattern registry first, falls back to AI if enabled

package/src/generators/test-generator/template-engine.ts

@@ -229,8 +229,8 @@ export class TemplateEngine {
     this.baseContext = {};
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean }): string {
-    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport, needsDb: options?.needsDb });
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean }): string {
+    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport, needsDb: options?.needsDb, needsApi: options?.needsApi });
   }
 
   renderTestFile(data: {
@@ -284,6 +284,9 @@ export class TemplateEngine {
     scenarioName: string;
     steps: Array<{ comment?: string; code: string }>;
     authRole?: string;
+    isParallel?: boolean;
+    tags?: string;
+    casesDataset?: string;
   }): string {
     return this.render('scenario', data);
   }

package/src/generators/test-generator/utils/runtime-data-transformer.ts

@@ -4,7 +4,7 @@ const MARKER_PATTERN = /__SUNGEN_TD_([A-Za-z0-9_]+)__/;
  * Replace __SUNGEN_TD_ markers with testData.get() calls in generated code.
  * Three passes: comments, string literals, then regex literals.
  */
-export function transformToRuntimeData(code: string): string {
+export function transformToRuntimeData(code: string, accessor: string = 'testData'): string {
   // Pass 0: Comments — replace markers in // comments with decoded key name
   // Prevents Pass 2 from misinterpreting // comment markers as regex delimiters
   code = code.replace(
@@ -20,9 +20,9 @@ export function transformToRuntimeData(code: string): string {
     (_, _quote, prefix, enc, suffix) => {
       const key = decodeKey(enc);
       if (!prefix && !suffix) {
-        return `testData.get('${key}')`;
+        return `${accessor}.get('${key}')`;
       }
-      return `\`${prefix}\${testData.get('${key}')}${suffix}\``;
+      return `\`${prefix}\${${accessor}.get('${key}')}${suffix}\``;
     }
   );
 
@@ -32,7 +32,7 @@ export function transformToRuntimeData(code: string): string {
     /\/((?:[^/\\\n]|\\.)*?)__SUNGEN_TD_([A-Za-z0-9_]+)__((?:[^/\\\n]|\\.)*?)\/([gimsuy]*)/g,
     (_, prefix, enc, suffix, flags) => {
       const key = decodeKey(enc);
-      const ref = `testData.get('${key}')`;
+      const ref = `${accessor}.get('${key}')`;
       const flagStr = flags ? `, '${flags}'` : '';
       if (!prefix && !suffix) return `new RegExp(${ref}${flagStr})`;
       return `new RegExp(\`${prefix}\${${ref}}${suffix}\`${flagStr})`;
@@ -44,7 +44,7 @@ export function transformToRuntimeData(code: string): string {
   // table/list count templates). testData.get() returns a string, so coerce with Number().
   code = code.replace(
     /__SUNGEN_TD_([A-Za-z0-9_]+)__/g,
-    (_, enc) => `Number(testData.get('${decodeKey(enc)}'))`
+    (_, enc) => `Number(${accessor}.get('${decodeKey(enc)}'))`
   );
 
   return code;

package/src/harness/annotation-overrides.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared annotation-override grammar for precondition annotations (`@query`/`@api`).
+ *
+ * Parses `name(a={{x}},b="lit",c=3)` overrides into a map of JS expressions, e.g.
+ * `{ a: "testData.get('x')", b: "\"lit\"", c: "3" }`. Used by the DB and API capability drivers'
+ * precondition codegen; lives in core so both drivers (and core's `api` until R5.6) can share it.
+ */
+export function parseQueryOverrides(raw?: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!raw) return out;
+  for (const part of raw.split(',')) {
+    const eq = part.indexOf('=');
+    if (eq < 0) continue;
+    const key = part.slice(0, eq).trim();
+    const val = part.slice(eq + 1).trim();
+    if (!key) continue;
+    const v = val.match(/^\{\{\s*([^}]+?)\s*\}\}$/);
+    const q = val.match(/^["'](.*)["']$/);
+    if (v) out[key] = `testData.get(${JSON.stringify(v[1])})`;
+    else if (q) out[key] = JSON.stringify(q[1]);
+    else if (/^-?\d+(?:\.\d+)?$/.test(val)) out[key] = val;
+    else out[key] = JSON.stringify(val);
+  }
+  return out;
+}