@sungen/driver-api 3.1.2-beta.100

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@sungen/driver-api",
+  "version": "3.1.2-beta.100",
+  "description": "Sungen API capability — the @api annotation, API catalog, OpenAPI import + `sungen api import`, and the specs/api.ts runtime template. Plugs into @sun-asterisk/sungen via the capability SPI.",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "sungen": {
+    "capability": "api"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json"
+  },
+  "author": "eqe team (engineer & quality) — Sun Asterisk",
+  "license": "MIT",
+  "dependencies": {
+    "@sun-asterisk/sungen": "3.1.2-beta.100",
+    "commander": "^14.0.2",
+    "yaml": "^2.8.2"
+  },
+  "files": [
+    "dist",
+    "src"
+  ]
+}

package/src/api-catalog.ts

@@ -0,0 +1,171 @@
+/**
+ * API Driver — named-endpoint catalog (P1, Mode B: `@api` in E2E).
+ *
+ * Mirrors the DB query catalog: endpoints live in a reviewed `api/apis.yaml`, referenced by name
+ * from the `@api:<name>` annotation. The single deterministic loader/resolver/linter, shared by the
+ * compiler (`preconditionCodegen` → embedded request) and the harness.
+ *
+ * Layout (per-capability subfolder — the §13 capability contract):
+ *   qa/screens/<screen>/api/apis.yaml   (screen-scoped)
+ *   qa/flows/<flow>/api/apis.yaml        (flow-scoped)
+ *   qa/api/apis.yaml                     (optional shared/global)
+ *
+ * Resolution: screen/flow scope first, then shared; the same name in both is an error. Request
+ * shape (method/path/body) is *structure* (like SQL/selectors) → resolved at generate time and
+ * embedded; only `{{values}}` bind at runtime. Base URL + auth live in datasources.yaml + .env.qa.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+const METHODS = new Set<string>(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']);
+
+export interface ApiEntry {
+  name: string;
+  datasource?: string;
+  method: HttpMethod;
+  path: string;
+  body?: unknown;
+  params: string[];
+  expect?: { status?: number | string };
+  description?: string;
+  scope: 'screen' | 'shared';
+  file: string;
+}
+
+export interface ApiCatalogFiles {
+  screen?: string;
+  shared?: string;
+}
+
+interface LoadedApiCatalog {
+  screen: Map<string, ApiEntry>;
+  shared: Map<string, ApiEntry>;
+  files: ApiCatalogFiles;
+}
+
+const _cache = new Map<string, LoadedApiCatalog>();
+
+/** Locate the `api/apis.yaml` files visible to a screen/flow (resolved from the project root). */
+export function findApiCatalogFiles(screenName: string, cwd: string = process.cwd()): ApiCatalogFiles {
+  const out: ApiCatalogFiles = {};
+  if (!screenName) return out;
+  const screenDir = screenName.startsWith('flows/')
+    ? path.join(cwd, 'qa', screenName)
+    : path.join(cwd, 'qa', 'screens', screenName);
+  const screenFile = path.join(screenDir, 'api', 'apis.yaml');
+  if (fs.existsSync(screenFile)) out.screen = screenFile;
+  const sharedFile = path.join(cwd, 'qa', 'api', 'apis.yaml');
+  if (fs.existsSync(sharedFile)) out.shared = sharedFile;
+  return out;
+}
+
+/** Bare `:param` references appearing in a path or stringified body. */
+function refsIn(text: string): string[] {
+  return (text.match(/:([A-Za-z_][A-Za-z0-9_]*)/g) || []).map((s) => s.slice(1));
+}
+
+function parseEntries(file: string, scope: 'screen' | 'shared'): Map<string, ApiEntry> {
+  const map = new Map<string, ApiEntry>();
+  const raw = parseYaml(fs.readFileSync(file, 'utf8')) || {};
+  const root = (raw && typeof raw === 'object' && (raw as any).apis && typeof (raw as any).apis === 'object') ? (raw as any).apis : raw;
+  for (const [name, v] of Object.entries(root as Record<string, any>)) {
+    if (!v || typeof v !== 'object' || typeof v.method !== 'string' || typeof v.path !== 'string') continue;
+    map.set(name, {
+      name,
+      datasource: typeof v.datasource === 'string' ? v.datasource : undefined,
+      method: String(v.method).toUpperCase() as HttpMethod,
+      path: v.path,
+      body: v.body,
+      params: Array.isArray(v.params) ? v.params.map((p: any) => String(p)) : [],
+      expect: v.expect && typeof v.expect === 'object' ? { status: v.expect.status } : undefined,
+      description: typeof v.description === 'string' ? v.description : undefined,
+      scope,
+      file,
+    });
+  }
+  return map;
+}
+
+function loadCatalog(screenName: string, cwd: string = process.cwd()): LoadedApiCatalog {
+  const key = `${cwd} ${screenName}`;
+  const cached = _cache.get(key);
+  if (cached) return cached;
+  const files = findApiCatalogFiles(screenName, cwd);
+  const loaded: LoadedApiCatalog = {
+    screen: files.screen ? parseEntries(files.screen, 'screen') : new Map(),
+    shared: files.shared ? parseEntries(files.shared, 'shared') : new Map(),
+    files,
+  };
+  _cache.set(key, loaded);
+  return loaded;
+}
+
+/** Resolve an `@api [name]` reference. Screen scope first, then shared; ambiguity → throw. */
+export function resolveApi(name: string, screenName: string, cwd: string = process.cwd()): ApiEntry {
+  const { screen, shared, files } = loadCatalog(screenName, cwd);
+  const inScreen = screen.get(name);
+  const inShared = shared.get(name);
+  if (inScreen && inShared) {
+    throw new Error(`API Driver: api "${name}" is defined in BOTH the screen catalog (${rel(files.screen)}) and the shared catalog (${rel(files.shared)}) — names must be unambiguous. Rename one.`);
+  }
+  const entry = inScreen || inShared;
+  if (!entry) {
+    const known = [...screen.keys(), ...shared.keys()];
+    const where = files.screen || files.shared
+      ? `Known apis: ${known.length ? known.join(', ') : '(none)'}.`
+      : `No api/apis.yaml found for screen "${screenName}" (expected qa/screens/${screenName}/api/apis.yaml or qa/api/apis.yaml).`;
+    throw new Error(`API Driver: api "${name}" not found. ${where}`);
+  }
+  return entry;
+}
+
+/** Ordered bound-param names for an entry (declared `params`, else the `:refs` in path+body). */
+export function apiParamNames(entry: ApiEntry): string[] {
+  if (entry.params.length) return entry.params;
+  const fromPath = refsIn(entry.path);
+  const fromBody = entry.body != null ? refsIn(JSON.stringify(entry.body)) : [];
+  return [...new Set([...fromPath, ...fromBody])];
+}
+
+/** Validate one entry. Returns human-readable problems (empty = clean). */
+export function validateApiEntry(entry: ApiEntry, datasourceNames: string[] | null): string[] {
+  const errs: string[] = [];
+  if (!METHODS.has(entry.method)) errs.push(`api "${entry.name}": method "${entry.method}" is not a valid HTTP method.`);
+  if (!entry.path.startsWith('/')) errs.push(`api "${entry.name}": path "${entry.path}" must start with "/".`);
+  const refs = new Set([...refsIn(entry.path), ...(entry.body != null ? refsIn(JSON.stringify(entry.body)) : [])]);
+  const declared = new Set(entry.params);
+  for (const r of refs) if (!declared.has(r)) errs.push(`api "${entry.name}": uses :${r} but it is not in params:.`);
+  for (const d of declared) if (!refs.has(d)) errs.push(`api "${entry.name}": param "${d}" is declared but never used in path/body.`);
+  if (datasourceNames && entry.datasource && !datasourceNames.includes(entry.datasource)) {
+    errs.push(`api "${entry.name}": datasource "${entry.datasource}" is not defined in datasources.yaml.`);
+  }
+  return errs;
+}
+
+export interface ApiCatalogLint {
+  files: ApiCatalogFiles;
+  errors: string[];
+  entries: ApiEntry[];
+}
+
+/** Lint every api-catalog entry visible to a screen/flow (deterministic; used by audit + CI). */
+export function lintApiCatalog(screenName: string, datasourceNames: string[] | null = null, cwd: string = process.cwd()): ApiCatalogLint {
+  const { screen, shared, files } = loadCatalog(screenName, cwd);
+  const errors: string[] = [];
+  const entries = [...screen.values(), ...shared.values()];
+  for (const e of entries) errors.push(...validateApiEntry(e, datasourceNames));
+  for (const name of screen.keys()) if (shared.has(name)) errors.push(`api "${name}": defined in both screen and shared catalogs — names must be unambiguous.`);
+  return { files, errors, entries };
+}
+
+function rel(p?: string): string {
+  if (!p) return '(unknown)';
+  return path.relative(process.cwd(), p) || p;
+}
+
+/** Clear the in-process cache (tests). */
+export function _clearApiCatalogCache(): void {
+  _cache.clear();
+}

package/src/cli-import.ts

@@ -0,0 +1,59 @@
+import { Command } from 'commander';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { importOpenApi } from './openapi-import';
+
+/**
+ * `sungen api …` — API Driver authoring commands (P3, Mode A).
+ * For now: `import` an OpenAPI/Swagger doc into a reviewed `api/apis.yaml` catalog.
+ */
+export function registerApiCommand(program: Command): void {
+  const api = program.command('api').description('API Driver authoring (import an OpenAPI spec into an apis.yaml catalog)');
+
+  api
+    .command('import <openapi>')
+    .description('Generate api/apis.yaml entries from an OpenAPI/Swagger document')
+    .option('--screen <name>', 'Write to qa/screens/<name>/api/apis.yaml (else shared qa/api/apis.yaml)')
+    .option('--datasource <name>', 'Datasource name to assign to imported endpoints', 'app_api')
+    .option('--merge', 'Merge into an existing apis.yaml instead of refusing to overwrite')
+    .action((openapi: string, opts: { screen?: string; datasource: string; merge?: boolean }) => {
+      try {
+        if (!fs.existsSync(openapi)) throw new Error(`OpenAPI file not found: ${openapi}`);
+        const text = fs.readFileSync(openapi, 'utf8');
+        const doc = parseYaml(text); // YAML parser also accepts JSON
+        const { entries, count, skipped } = importOpenApi(doc, opts.datasource);
+        if (count === 0) throw new Error(`No operations imported (${skipped.join('; ') || 'empty paths'}).`);
+
+        const outDir = opts.screen
+          ? path.join(process.cwd(), 'qa', 'screens', opts.screen, 'api')
+          : path.join(process.cwd(), 'qa', 'api');
+        const outFile = path.join(outDir, 'apis.yaml');
+
+        let merged = entries;
+        if (fs.existsSync(outFile)) {
+          if (!opts.merge) throw new Error(`${path.relative(process.cwd(), outFile)} already exists — pass --merge to combine.`);
+          const existing = parseYaml(fs.readFileSync(outFile, 'utf8')) || {};
+          merged = { ...existing, ...entries }; // imported entries win on name clash
+        }
+
+        fs.mkdirSync(outDir, { recursive: true });
+        const header = '# Named-endpoint catalog (API Driver) — generated from an OpenAPI spec by `sungen api import`.\n' +
+          '# Review the SQL-free request shape, wire each `datasource` in datasources.yaml (kind: api),\n' +
+          '# then reference an endpoint from a scenario with `@api:<name>`.\n';
+        fs.writeFileSync(outFile, header + stringifyYaml(merged));
+
+        console.log(`\n✓ Imported ${count} endpoint(s) → ${path.relative(process.cwd(), outFile)}`);
+        for (const name of Object.keys(entries).slice(0, 12)) {
+          const e = entries[name];
+          console.log(`   ${name}: ${e.method} ${e.path}${e.expect ? ` → ${e.expect.status}` : ''}`);
+        }
+        if (Object.keys(entries).length > 12) console.log(`   … and ${Object.keys(entries).length - 12} more`);
+        if (skipped.length) console.log(`\n⚠ Skipped: ${skipped.join('; ')}`);
+        console.log('\nNext: set the `datasource` base_url + auth in datasources.yaml, then `@api:<name>` in a scenario.\n');
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/index.ts

@@ -0,0 +1,89 @@
+/**
+ * @sungen/driver-api — Sungen API capability.
+ *
+ * Owns the `@api` annotation (Mode B: API in E2E) and the API-first authoring tooling (Mode A):
+ * the named-endpoint catalog (apis.yaml), the precondition codegen that binds a response to
+ * `{{name}}`, the gate sensor that verifies referenced endpoints resolve, the OpenAPI importer, and
+ * the `sungen api import` CLI command. Plugs into core via the capability SPI; core discovers and
+ * calls `register()` at runtime (core never imports this package).
+ *
+ * Relocated from core in R5.6 (was `src/harness/api-catalog.ts`, `openapi-import.ts`,
+ * `src/cli/commands/api.ts`, and the api parts of `src/capabilities/builtins.ts`). The runtime-helper
+ * template `specs-api.ts` remains in core's templates dir (emitted by the core generator via
+ * `runtimeHelpers`, resolved by filename) — consistent with the base/db templates staying in core.
+ */
+import type { CapabilityRegistry, Sensor, GateInput } from '@sun-asterisk/sungen';
+import { parseQueryOverrides } from '@sun-asterisk/sungen';
+import { resolveApi, apiParamNames, lintApiCatalog } from './api-catalog';
+import { registerApiCommand } from './cli-import';
+
+export { importOpenApi } from './openapi-import';
+export type { ImportedApiEntry, ImportResult } from './openapi-import';
+
+/**
+ * API precondition codegen: `@api:<name>[(p={{v}},…)]` → run the catalog request and bind the
+ * response { status, ok, body, headers } to `{{name}}`. Assert with `expect {{name.status}} is 201`
+ * / `{{name.body.<path>}}`.
+ */
+function apiPreconditionCodegen(input: { tags: string[]; screenName: string; cwd: string }): Array<{ comment?: string; code: string; boundVars?: string[] }> {
+  const out: Array<{ comment?: string; code: string; boundVars?: string[] }> = [];
+  const TAG = /^@api:([A-Za-z_][A-Za-z0-9_]*)(?:\((.*)\))?$/;
+  for (const tag of input.tags) {
+    const m = tag.match(TAG);
+    if (!m) continue;
+    const name = m[1];
+    const overrides = parseQueryOverrides(m[2]); // same key=value override grammar
+    const entry = resolveApi(name, input.screenName, input.cwd); // throws (fail-fast) if missing/ambiguous
+    const paramsObj = apiParamNames(entry)
+      .map((p) => `${JSON.stringify(p)}: ${p in overrides ? overrides[p] : `testData.get(${JSON.stringify(p)})`}`)
+      .join(', ');
+    const label = JSON.stringify(entry.description ? `api "${name}" — ${entry.description}` : `api "${name}"`);
+    const ds = entry.datasource ? JSON.stringify(entry.datasource) : 'undefined';
+    const req = `{ method: ${JSON.stringify(entry.method)}, path: ${JSON.stringify(entry.path)}${entry.body !== undefined ? `, body: ${JSON.stringify(entry.body)}` : ''}, datasource: ${ds} }`;
+    out.push({
+      comment: `@api:${name} → bind {{${name}}} (${entry.method} ${entry.path})`,
+      code: `testData.bind(${JSON.stringify(name)}, await api.call(${label}, ${req}, { ${paramsObj} }));`,
+      boundVars: [name],
+    });
+  }
+  return out;
+}
+
+/**
+ * API `verification` gate sensor: every referenced `@api` must resolve in its catalog, and the
+ * catalog must lint clean. An unresolved/invalid reference is a gate-level error. Runs when the `api`
+ * capability is in scope (a scenario carries `@api`). Message prefix is unchanged from the former
+ * in-core verification sensor, so audit output is byte-identical.
+ */
+const apiVerificationSensor: Sensor<GateInput> = {
+  id: 'api-verification',
+  capability: 'api',
+  kind: 'gate',
+  run: ({ screenName, scenarios, cwd }) => {
+    const findings = [] as ReturnType<Sensor['run']>;
+    const fail = (msg: string) => findings.push({ sensorId: 'api-verification', capability: 'api', message: `VERIFICATION-FAIL: ${msg}`, severity: 'error' });
+    const apiRefs = new Set<string>();
+    for (const s of scenarios) for (const r of s.apiRefs ?? []) apiRefs.add(r);
+    for (const name of apiRefs) {
+      try { resolveApi(name, screenName, cwd); } catch (e: any) { fail(e?.message || `api "${name}" does not resolve`); }
+    }
+    if (apiRefs.size) {
+      try { for (const err of lintApiCatalog(screenName, null, cwd).errors) fail(err); } catch { /* no catalog */ }
+    }
+    return findings;
+  },
+};
+
+/** Register the API capability. */
+export function register(registry: CapabilityRegistry): void {
+  registry.register({
+    id: 'api',
+    annotations: ['@api'],
+    runtimeHelpers: [{ file: 'api.ts', template: 'specs-api.ts' }], // template resolved from core's templates dir
+    preconditionCodegen: apiPreconditionCodegen, // @api:<name> → bind {{name}}
+    sensors: [apiVerificationSensor],
+    cliCommands: [registerApiCommand as (program: unknown) => void], // `sungen api import <openapi>`
+  });
+}
+
+export const sungenDriver = { capability: 'api', register } as const;

package/src/openapi-import.ts

@@ -0,0 +1,99 @@
+/**
+ * OpenAPI → apis.yaml importer (API Driver P3, Mode A keystone).
+ *
+ * Deterministically turns an OpenAPI/Swagger document into named-endpoint catalog entries, so QA
+ * doesn't hand-author the `api/apis.yaml`. Pure transform (no network): paths × methods → entries
+ * with method, `:param` path, declared params (path + JSON body props), expected status, and a
+ * placeholder datasource. The Dev/lead reviews + wires the datasource; QA references by `@api:<name>`.
+ */
+export interface ImportedApiEntry {
+  datasource: string;
+  description?: string;
+  method: string;
+  path: string;
+  params?: string[];
+  body?: Record<string, string>;
+  expect?: { status: number };
+}
+
+const METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
+
+/** A safe catalog name from an OpenAPI path + method (fallback when there's no operationId). */
+function fallbackName(method: string, path: string): string {
+  const slug = path.replace(/[{}]/g, '').replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '').toLowerCase() || 'root';
+  return `${method.toLowerCase()}_${slug}`;
+}
+
+/** Convert an OpenAPI path (`/orders/{id}`) to the catalog form (`/orders/:id`). */
+function toCatalogPath(path: string): string {
+  return path.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, ':$1');
+}
+
+/** First 2xx status declared for an operation (else the first numeric status, else 200). */
+function expectedStatus(responses: Record<string, unknown> | undefined): number | undefined {
+  if (!responses) return undefined;
+  const codes = Object.keys(responses).filter((c) => /^\d+$/.test(c)).map(Number);
+  const success = codes.find((c) => c >= 200 && c < 300);
+  return success ?? codes[0];
+}
+
+/** JSON-body property names → a `{ prop: ":prop" }` template (best-effort from requestBody schema). */
+function bodyTemplate(op: any): { body?: Record<string, string>; props: string[] } {
+  const schema = op?.requestBody?.content?.['application/json']?.schema;
+  const props = schema && typeof schema === 'object' && schema.properties && typeof schema.properties === 'object'
+    ? Object.keys(schema.properties)
+    : [];
+  if (!props.length) return { props: [] };
+  const body: Record<string, string> = {};
+  for (const p of props) body[p] = `:${p}`;
+  return { body, props };
+}
+
+export interface ImportResult {
+  entries: Record<string, ImportedApiEntry>;
+  count: number;
+  skipped: string[];
+}
+
+/**
+ * Transform an OpenAPI document into apis.yaml entries.
+ * @param doc parsed OpenAPI/Swagger object
+ * @param datasource placeholder datasource name to assign (default 'app_api')
+ */
+export function importOpenApi(doc: any, datasource = 'app_api'): ImportResult {
+  const entries: Record<string, ImportedApiEntry> = {};
+  const skipped: string[] = [];
+  const paths = doc && typeof doc === 'object' ? doc.paths : undefined;
+  if (!paths || typeof paths !== 'object') return { entries, count: 0, skipped: ['no `paths` object found'] };
+
+  for (const [rawPath, pathItem] of Object.entries(paths as Record<string, any>)) {
+    if (!pathItem || typeof pathItem !== 'object') continue;
+    for (const method of METHODS) {
+      const op = (pathItem as any)[method];
+      if (!op || typeof op !== 'object') continue;
+
+      const catalogPath = toCatalogPath(rawPath);
+      const pathParams = (catalogPath.match(/:([A-Za-z_][A-Za-z0-9_]*)/g) || []).map((s) => s.slice(1));
+      const { body, props } = bodyTemplate(op);
+      const params = [...new Set([...pathParams, ...props])];
+
+      let name = typeof op.operationId === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(op.operationId)
+        ? op.operationId
+        : fallbackName(method, rawPath);
+      if (entries[name]) name = fallbackName(method, rawPath); // operationId collision → disambiguate
+      if (entries[name]) { skipped.push(`${method.toUpperCase()} ${rawPath} (duplicate name "${name}")`); continue; }
+
+      const status = expectedStatus(op.responses);
+      entries[name] = {
+        datasource,
+        description: typeof op.summary === 'string' ? op.summary : undefined,
+        method: method.toUpperCase(),
+        path: catalogPath,
+        ...(params.length ? { params } : {}),
+        ...(body ? { body } : {}),
+        ...(status != null ? { expect: { status } } : {}),
+      };
+    }
+  }
+  return { entries, count: Object.keys(entries).length, skipped };
+}