@sun-asterisk/sungen 3.1.2 → 3.2.0-beta.142

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

@@ -4,8 +4,9 @@ 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 { resolveQuery, compileQuery } from '../../harness/query-catalog';
+import { capabilityRegistry } from '../../capabilities/registry';
+import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
+import { readCapabilities } from '../../harness/capability';
 
 /**
  * Filter base scenario steps for @extend: only keep Given→When steps.
@@ -88,6 +89,40 @@ function extractPassThroughTags(scenarioTags: string[], featureTags: string[]):
   return unique.map(t => `'${t}'`).join(', ');
 }
 
+/**
+ * Derive a feature's unit from its source path: the catalog-resolution id (relative to qa/), the
+ * output subdir, and whether it is a UI flow. Recognizes the api-first project model:
+ *   qa/screens/<screen>/features/…        → id `<screen>`            (subdir `<screen>`)
+ *   qa/flows/<flow>/features/…            → id `flows/<flow>`        (subdir `flows/<flow>`, isFlow)
+ *   qa/api/<area>/features/…              → id `api/<area>`          (subdir `api/<area>`)
+ *   qa/api/flows/<flow>/features/…        → id `api/flows/<flow>`    (subdir `api/flows/<flow>`)
+ * api-first units are NOT UI flows (no cross-screen namespacing) — they resolve their own api/db catalogs.
+ */
+function deriveUnitFromFeaturePath(sourceFile: string): { unitId: string; outputSubdir: string; isFlow: boolean } {
+  const parts = path.dirname(sourceFile).split(path.sep);
+  const qa = parts.lastIndexOf('qa');
+  if (qa >= 0 && parts[qa + 1] === 'api') {
+    if (parts[qa + 2] === 'flows' && parts[qa + 3]) {
+      const id = `api/flows/${parts[qa + 3]}`;
+      return { unitId: id, outputSubdir: id, isFlow: false };
+    }
+    if (parts[qa + 2]) {
+      const id = `api/${parts[qa + 2]}`;
+      return { unitId: id, outputSubdir: id, isFlow: false };
+    }
+  }
+  const flowsIndex = parts.indexOf('flows');
+  const screensIndex = parts.indexOf('screens');
+  if (flowsIndex >= 0 && flowsIndex < parts.length - 1) {
+    const f = parts[flowsIndex + 1];
+    return { unitId: `flows/${f}`, outputSubdir: `flows/${f}`, isFlow: true };
+  }
+  if (screensIndex >= 0 && screensIndex < parts.length - 1) {
+    return { unitId: parts[screensIndex + 1], outputSubdir: parts[screensIndex + 1], isFlow: false };
+  }
+  return { unitId: '', outputSubdir: '', isFlow: false };
+}
+
 /**
  * Check for @screenshot:on-failure tag
  */
@@ -141,6 +176,19 @@ function isManual(tags: string[]): boolean {
   return tags.some(tag => tag === '@manual');
 }
 
+/**
+ * Capabilities a scenario declares via `@requires:<cap>` (TQ-11) — automation-ready work that
+ * needs an opt-in driver (e.g. `@requires:db`, `@requires:api`). When the cap is enabled the
+ * scenario compiles to a real test; when absent it compiles to a clean `test.skip` stub (no
+ * driver imports) so the run never breaks and the case is visible as "pending capability".
+ */
+function requiresCaps(tags: string[]): string[] {
+  return tags
+    .filter(t => /^@requires:/i.test(t))
+    .map(t => t.slice('@requires:'.length).trim().toLowerCase())
+    .filter(Boolean);
+}
+
 /**
  * Check for multiple auth tags and log warning
  */
@@ -210,29 +258,16 @@ export class CodeGenerator {
       fileName = this.featureNameToFileName(feature.name);
     }
     
-    // Extract screen/flow name from source file path for output subdirectory
-    // qa/screens/{screenName}/features/{featureName}.feature -> screenName
-    // qa/flows/{flowName}/features/{featureName}.feature -> flows/flowName
-    let outputSubdir = '';
-    if (feature.sourceFile) {
-      const sourceDir = path.dirname(feature.sourceFile);
-      const parts = sourceDir.split(path.sep);
-      const flowsIndex = parts.indexOf('flows');
-      const screensIndex = parts.indexOf('screens');
-      if (flowsIndex >= 0 && flowsIndex < parts.length - 2) {
-        outputSubdir = path.join('flows', parts[flowsIndex + 1]);
-      } else if (screensIndex >= 0 && screensIndex < parts.length - 2) {
-        outputSubdir = parts[screensIndex + 1];
-      }
-    }
+    // Output subdirectory from the source path (screens / flows / api-first areas+flows).
+    const outputSubdir = feature.sourceFile ? deriveUnitFromFeaturePath(feature.sourceFile).outputSubdir : '';
 
     // Build output path with subdirectory
     const filePath = outputSubdir
       ? path.join(outputDir, outputSubdir, fileName)
       : path.join(outputDir, fileName);
 
-    // Compute relative path from output file back to specs/generated/
-    const depth = outputSubdir ? outputSubdir.split(path.sep).length : 0;
+    // Compute relative path from output file back to specs/generated/ (subdir uses '/').
+    const depth = outputSubdir ? outputSubdir.split('/').length : 0;
     const basePath = depth > 0 ? Array(depth).fill('..').join('/') : '..';
 
     // Serial + @cleanup tags → need cleanupPage import from base
@@ -240,11 +275,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);
@@ -300,64 +341,52 @@ 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);
-    if (steps.some((s) => s && typeof s.text === 'string' && isDbStep(s.text))) return true;
-    // A scenario may carry only a @query:<name> post-condition tag (no DB step in its body).
-    return (feature.scenarios || []).some((sc) => (sc.tags || []).some((t) => t.startsWith('@query:')));
+    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];
   }
 
   /**
-   * Build the precondition bind steps for a scenario's `@query:<name>[(p={{v}},…)]` tags.
-   * Each runs the catalog query and binds the result array to a `{{name}}` variable.
+   * 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 buildQueryBinds(scenario: ParsedScenario): Array<{ comment?: string; code: string }> {
-    const out: Array<{ comment?: string; code: string }> = [];
-    const TAG = /^@query:([A-Za-z_][A-Za-z0-9_]*)(?:\((.*)\))?$/;
-    for (const tag of scenario.tags || []) {
-      const m = tag.match(TAG);
-      if (!m) continue;
-      const name = m[1];
-      const overrides = this.parseQueryOverrides(m[2]);
-      const entry = resolveQuery(name, this.queryScreenName); // throws (fail-fast) if missing/ambiguous
-      const { sql, paramNames } = compileQuery(entry);
-      const paramExprs = paramNames.map((p) =>
-        p in overrides ? overrides[p] : `testData.get(${JSON.stringify(p)})`,
-      );
-      const label = JSON.stringify(entry.description ? `query "${name}" — ${entry.description}` : `query "${name}"`);
-      const ds = entry.datasource ? JSON.stringify(entry.datasource) : 'undefined';
-      out.push({
-        comment: `@query:${name} → bind {{${name}}} from ${entry.datasource || 'default datasource'}`,
-        code: this.indentCode(
-          `testData.bind(${JSON.stringify(name)}, await db.fetchQuery(${label}, ${JSON.stringify(sql)}, [${paramExprs.join(', ')}], ${ds}));`,
-          4,
-        ),
-      });
-    }
-    return out;
-  }
-
-  /** Parse `@query:name(a={{x}},b="lit",c=3)` overrides → { a: "testData.get('x')", … } JS exprs. */
-  private 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;
+  private capabilityPreconditions(scenario: ParsedScenario): Array<{ comment?: string; code: string; boundVars?: string[] }> {
+    discoverAndRegisterCapabilities();
+    const tags = scenario.tags || [];
+    const out: Array<{ comment?: string; code: string; boundVars?: string[] }> = [];
+    for (const cap of capabilityRegistry.all()) {
+      if (!cap.preconditionCodegen) continue;
+      out.push(...cap.preconditionCodegen({ tags, screenName: this.queryScreenName, cwd: process.cwd() }));
+    }
+    // Order by each precondition's annotation position on the scenario (not capability-registry order),
+    // so a cross-capability sequence runs as authored — e.g. `@api:pay @concurrent:2 @query:charge_count`
+    // mutates THEN reads the DB (the idempotency cross-check). Stable: ties keep their original order.
+    const pos = (p: { boundVars?: string[] }): number => {
+      const name = p.boundVars?.[0];
+      if (!name) return tags.length;
+      const i = tags.findIndex((t) => new RegExp(`^@\\w+:${name}\\b`).test(t));
+      return i < 0 ? tags.length : i;
+    };
+    return out.map((p, i) => ({ p, i })).sort((a, b) => pos(a.p) - pos(b.p) || a.i - b.i).map((x) => x.p);
   }
 
   /**
@@ -378,11 +407,6 @@ export class CodeGenerator {
     console.log(`✓ ${exists ? 'Updated' : 'Created'}: specs/${fileName}`);
   }
 
-  /** Ensure specs/db.ts is present and current (Data Driver runtime helper). */
-  ensureDbFile(outputDir: string): void {
-    this.syncGeneratedHelper(outputDir, 'db.ts', 'specs-db.ts');
-  }
-
   ensureBaseFile(outputDir: string): void {
     this.syncGeneratedHelper(outputDir, 'base.ts', 'specs-base.ts');
     // base.ts depends on locale-fixture.ts — keep them paired.
@@ -403,27 +427,23 @@ export class CodeGenerator {
       featureName = this.featureNameToFileName(feature.name).replace('.spec.ts', '');
     }
     
-    // Derive screen/flow name from source file path when not explicitly set
-    // qa/screens/{screenName}/features/{featureName}.feature -> screenName
-    // qa/flows/{flowName}/features/{featureName}.feature -> flowName
+    // Derive the unit from the source path when not explicitly set. `unitId` is the catalog/test-data
+    // resolution id relative to qa/ (`<screen>` · `flows/<flow>` · `api/<area>` · `api/flows/<flow>`);
+    // `effectiveScreenName` is the bare name for UI screen-context (selector/data namespacing).
     let effectiveScreenName = this.screenName;
     let isFlowFeature = !!this.options.flowMode;
+    let unitId = isFlowFeature ? `flows/${effectiveScreenName || ''}` : (effectiveScreenName || '');
     if (!this.screenName && feature.sourceFile) {
-      const sourceDir = path.dirname(feature.sourceFile);
-      const parts = sourceDir.split(path.sep);
-      const flowsIndex = parts.indexOf('flows');
-      const screensIndex = parts.indexOf('screens');
-      if (flowsIndex >= 0 && flowsIndex < parts.length - 2) {
-        effectiveScreenName = parts[flowsIndex + 1];
-        isFlowFeature = true;
-      } else if (screensIndex >= 0 && screensIndex < parts.length - 2) {
-        effectiveScreenName = parts[screensIndex + 1];
-        isFlowFeature = false;
+      const u = deriveUnitFromFeaturePath(feature.sourceFile);
+      if (u.unitId) {
+        unitId = u.unitId;
+        isFlowFeature = u.isFlow;
+        effectiveScreenName = u.unitId.split('/').pop() || u.unitId; // bare name (no api/ or flows/ prefix)
+        this.stepMapper.setScreenContext(effectiveScreenName);
       }
-      this.stepMapper.setScreenContext(effectiveScreenName);
     }
-    // Catalog-resolution screen name for @query binds (flows are prefixed `flows/`).
-    this.queryScreenName = isFlowFeature ? `flows/${effectiveScreenName}` : (effectiveScreenName || '');
+    // Catalog + test-data resolution id (flows → `flows/<flow>`, api-first → `api/<area>` / `api/flows/<flow>`).
+    this.queryScreenName = unitId;
 
     // Reset flow mode per feature to prevent state leak in --all mode
     this.stepMapper.setFlowMode(isFlowFeature);
@@ -487,6 +507,10 @@ export class CodeGenerator {
     // Generate all scenarios with feature tags for inheritance
     // Skip scenarios tagged with @manual
     // Track auth role per scenario for grouping
+    // TQ-11 — enabled capabilities (qa/capabilities.yaml): a @requires:<cap> scenario whose cap is
+    // absent compiles to a skip stub instead of a real test (read once per feature).
+    const enabledCaps = new Set<string>(readCapabilities(process.cwd()).enabled.map(d => d.toLowerCase()));
+
     const renderedScenarios: Array<{ code: string; authRole?: string }> = [];
     for (const scenario of feature.scenarios) {
       if (isManual(scenario.tags)) {
@@ -501,6 +525,16 @@ export class CodeGenerator {
         continue;
       }
 
+      // TQ-11 — @requires:<cap> with the cap NOT enabled → emit a clean skip stub (no driver
+      // imports, so the spec still loads), visible as skipped-with-reason. With the cap enabled it
+      // falls through and compiles as a real test.
+      const reqAbsent = requiresCaps(scenario.tags).filter(c => !enabledCaps.has(c));
+      if (reqAbsent.length) {
+        if (this.options.verbose) console.log(`  ⏸ Pending capability (${reqAbsent.join(', ')}): ${scenario.name}`);
+        renderedScenarios.push({ code: this.generateRequiresSkipStub(scenario.name, reqAbsent), authRole: undefined });
+        continue;
+      }
+
       // Resolve auth tags for @extend scenarios (same logic as generateScenario)
       let authFeatureTags = feature.tags || [];
       if (scenario.extendsName) {
@@ -574,7 +608,7 @@ export class CodeGenerator {
       cleanupConfig,
       screenshotOnFailure,
       runtimeData: this.options.runtimeData,
-      screenName: isFlowFeature ? `flows/${effectiveScreenName}` : effectiveScreenName,
+      screenName: this.queryScreenName, // catalog/test-data id (screen · flows/<flow> · api/<area>)
       featureFileName: featureName,
       isParallel,
       flowMode: isFlowFeature,
@@ -636,6 +670,21 @@ export class CodeGenerator {
     return renderMap[hookType]();
   }
 
+  /**
+   * TQ-11 — a `@requires:<cap>` scenario whose capability is NOT enabled. Emits a real `test()`
+   * that skips itself with an actionable reason, and references NO driver runtime (so the spec
+   * loads even though the driver isn't installed). Once the cap is added + regenerated, the
+   * scenario compiles to its full automated body instead.
+   */
+  private generateRequiresSkipStub(name: string, caps: string[]): string {
+    const reason = `requires ${caps.join(' + ')} — run \`sungen capability add ${caps.join(' ')}\` to automate this`;
+    return [
+      `  test(${JSON.stringify(name)}, async () => {`,
+      `    test.skip(true, ${JSON.stringify(reason)});`,
+      `  });`,
+    ].join('\n');
+  }
+
   private async generateScenario(
     scenario: ParsedScenario,
     hasBackground: boolean,
@@ -683,18 +732,16 @@ export class CodeGenerator {
       for (const r of refs) this.stepMapper.registerCaptured(r);
     }
 
-    // @query-bound vars: `{{name.col}}` / `{{name[2].col}}` / `{{name.count}}` exist only at
-    // runtime (the bind fetches them) — register as captured so they resolve to a runtime get()
-    // instead of a compile-time YAML lookup that would fail.
-    const queryNames = (scenario.tags || [])
-      .map((t) => t.match(/^@query:([A-Za-z_][A-Za-z0-9_]*)/))
-      .filter((m): m is RegExpMatchArray => !!m)
-      .map((m) => m[1]);
-    if (queryNames.length) {
+    // 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 (queryNames.includes(head)) this.stepMapper.registerCaptured(mt[1]);
+          if (boundVars.includes(head)) this.stepMapper.registerCaptured(mt[1]);
         }
       }
     }
@@ -728,11 +775,11 @@ export class CodeGenerator {
       }
     }
 
-    // @query:<name>[(p={{v}},…)] tags → run the catalog query as a PRECONDITION and bind its
-    // result to a `{{name}}` variable (scenario asserts on it with `expect …` + path access).
-    // Prepended so the binds run before the scenario's own steps.
-    const queryBinds = this.buildQueryBinds(scenario);
-    if (queryBinds.length) steps.unshift(...queryBinds);
+    // Capability preconditions (db `@query:<name>` / api `@api:<name>` → bind {{name}}; computed
+    // above) run BEFORE the scenario's own steps — prepend them, indenting the capability 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);
@@ -752,7 +799,12 @@ export class CodeGenerator {
     // 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');
+      // AP-3: capability preconditions (`@api`/`@query`) and value assertions (`expect {{x}} is {{y}}`)
+      // emit LITERAL `testData.get/bind/set(…)` (not markers), so the marker transform above misses
+      // them. Rewrite those to the per-row `rowData` view — each row then fires its own `@api` call
+      // with that row's input and asserts that row's expected status/body (the success/failure matrix).
+      // `testData.cases()/withRow()` (the global loader, no `.get/.bind/.set`) is intentionally left alone.
+      return transformToRuntimeData(rendered, 'rowData').replace(/\btestData\.(get|bind|set)\(/g, 'rowData.$1(');
     }
     return rendered;
   }

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

@@ -1,18 +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 { expectPatterns } from './expect-patterns';
+import { capabilityRegistry } from '../../../capabilities/registry';
+import { discoverAndRegisterCapabilities } from '../../../capabilities/discover';
 
 /**
  * Pattern Registry - manages all step patterns
@@ -28,18 +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);
-    this.patterns.push(...expectPatterns);
+    // 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));
@@ -159,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/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: {

package/src/harness/annotation-overrides.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 can share it. Gherkin tags carry no whitespace,
+ * so values are single tokens — flows thread a prior response via a whole-value ref, e.g.
+ * `@api:get_profile(token={{login.body.token}})`, with the auth scheme declared in the catalog header.
+ */
+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;
+}