@sungen/driver-api 3.1.2-beta.110 → 3.1.2-beta.112

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-api",
-  "version": "3.1.2-beta.110",
+  "version": "3.1.2-beta.112",
   "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",
@@ -13,7 +13,7 @@
   "author": "eqe team (engineer & quality) — Sun Asterisk",
   "license": "MIT",
   "dependencies": {
-    "@sun-asterisk/sungen": "3.1.2-beta.110",
+    "@sun-asterisk/sungen": "3.1.2-beta.112",
     "commander": "^14.0.2",
     "yaml": "^2.8.2"
   },

package/src/api-catalog.ts

@@ -27,6 +27,7 @@ export interface ApiEntry {
   method: HttpMethod;
   path: string;
   body?: unknown;
+  headers?: Record<string, string>; // per-endpoint header templates; `:param` tokens bind at runtime (flow auth, e.g. authorization: "Bearer :token")
   params: string[];
   expect?: { status?: number | string };
   description?: string;
@@ -66,6 +67,14 @@ function refsIn(text: string): string[] {
   return (text.match(/:([A-Za-z_][A-Za-z0-9_]*)/g) || []).map((s) => s.slice(1));
 }
 
+/** All `:param` refs an entry binds — path + JSON body + header templates. */
+function entryRefs(entry: ApiEntry): string[] {
+  const fromPath = refsIn(entry.path);
+  const fromBody = entry.body != null ? refsIn(JSON.stringify(entry.body)) : [];
+  const fromHeaders = entry.headers ? refsIn(JSON.stringify(entry.headers)) : [];
+  return [...new Set([...fromPath, ...fromBody, ...fromHeaders])];
+}
+
 function parseEntries(file: string, scope: 'screen' | 'shared'): Map<string, ApiEntry> {
   const map = new Map<string, ApiEntry>();
   const raw = parseYaml(fs.readFileSync(file, 'utf8')) || {};
@@ -78,6 +87,7 @@ function parseEntries(file: string, scope: 'screen' | 'shared'): Map<string, Api
       method: String(v.method).toUpperCase() as HttpMethod,
       path: v.path,
       body: v.body,
+      headers: v.headers && typeof v.headers === 'object' ? Object.fromEntries(Object.entries(v.headers).map(([k, hv]) => [k, String(hv)])) : undefined,
       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,
@@ -121,12 +131,10 @@ export function resolveApi(name: string, screenName: string, cwd: string = proce
   return entry;
 }
 
-/** Ordered bound-param names for an entry (declared `params`, else the `:refs` in path+body). */
+/** Ordered bound-param names for an entry (declared `params`, else the `:refs` in path+body+headers). */
 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])];
+  return entryRefs(entry);
 }
 
 /** Validate one entry. Returns human-readable problems (empty = clean). */
@@ -134,7 +142,7 @@ export function validateApiEntry(entry: ApiEntry, datasourceNames: string[] | nu
   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 refs = new Set(entryRefs(entry));
   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.`);

package/src/cli-import.ts

@@ -94,11 +94,31 @@ export function registerApiCommand(program: Command): void {
   // ── add ──────────────────────────────────────────────────────────────────
   api
     .command('add')
-    .description('Scaffold an API area (resource/tag): qa/api/<area>/{features,test-data,requirements,api}')
-    .requiredOption('--area <name>', 'Area / resource name (e.g. orders, users, auth)')
-    .action((opts: { area: string }) => {
+    .description('Scaffold an API area (--area, one resource) or a CRUD/auth journey (--flow, ordered @api chain)')
+    .option('--area <name>', 'Area / resource name (e.g. orders, users, auth)')
+    .option('--flow <name>', 'CRUD/auth flow name — a response→request journey (e.g. user-lifecycle)')
+    .action((opts: { area?: string; flow?: string }) => {
       try {
-        const area = slug(opts.area);
+        if (!!opts.area === !!opts.flow) throw new Error('pass exactly one of --area or --flow.');
+
+        if (opts.flow) {
+          const flow = slug(opts.flow);
+          if (!flow) throw new Error(`invalid --flow "${opts.flow}"`);
+          const base = path.join(process.cwd(), 'qa', 'api', 'flows', flow);
+          if (fs.existsSync(base)) throw new Error(`${rel(base)} already exists.`);
+          for (const d of ['features', 'test-data', 'requirements', 'api']) fs.mkdirSync(path.join(base, d), { recursive: true });
+          fs.writeFileSync(path.join(base, 'features', `${flow}.feature`), flowFeatureStub(flow));
+          fs.writeFileSync(path.join(base, 'api', 'apis.yaml'), flowCatalogStub());
+          fs.writeFileSync(path.join(base, 'test-data', `${flow}.yaml`), flowTestDataStub());
+          fs.writeFileSync(path.join(base, 'requirements', 'spec.md'), `# ${flow} flow\n\n_Describe the ordered journey (auth → CRUD), the resource lifecycle, and the response fields each step threads forward._\n`);
+          console.log(`✓ flow "${flow}" → ${rel(base)}/`);
+          console.log(`\nResponse→request chaining: each @api binds {{name}}; a later call threads {{name.body.<field>}}`);
+          console.log(`via a path param or the catalog "Bearer :token" header. Review api/apis.yaml, wire the datasource,`);
+          console.log(`then assert each step's status/body. Self-clean by deleting what the flow created.\n`);
+          return;
+        }
+
+        const area = slug(opts.area!);
         if (!area) throw new Error(`invalid --area "${opts.area}"`);
         const base = path.join(process.cwd(), 'qa', 'api', area);
         if (fs.existsSync(base)) throw new Error(`${rel(base)} already exists.`);
@@ -178,6 +198,79 @@ function featureStub(area: string): string {
   ].join('\n');
 }
 
+/** CRUD/auth flow scaffold: an ordered @api chain that threads a created resource through its lifecycle. */
+function flowFeatureStub(flow: string): string {
+  return [
+    `@flow @area:${flow}`,
+    `Feature: ${flow} flow`,
+    '',
+    '  # Response→request chaining: ordered @api tags run in declaration order; each binds {{name}},',
+    '  # a later call threads a prior field forward. Tags carry no whitespace — pass single-token',
+    '  # overrides; the auth scheme ("Bearer :token") lives in the catalog header, not the feature.',
+    '  #',
+    '  # auth precondition: @api:login binds {{login}}; authed calls pass token={{login.body.token}}',
+    '  # → the catalog "Bearer :token" header. Self-clean by deleting what the flow created.',
+    '  @high @api:login(email={{email}},password={{password}}) @api:create_item(name={{item_name}},token={{login.body.token}}) @api:get_item(id={{create_item.body.id}},token={{login.body.token}}) @api:delete_item(id={{create_item.body.id}},token={{login.body.token}})',
+    `  Scenario: VP-API-FLOW-001 ${flow} — login, create, read back, then delete`,
+    '    Then expect {{login.status}} is 200',
+    '    And expect {{create_item.status}} is 201',
+    '    And expect {{get_item.status}} is 200',
+    '    And expect {{get_item.body.name}} is {{item_name}}',
+    '    And expect {{delete_item.status}} is 204',
+    '',
+  ].join('\n');
+}
+
+function flowCatalogStub(): string {
+  return CATALOG_HEADER + [
+    '',
+    'login:',
+    '  datasource: app_api',
+    '  method: POST',
+    '  path: /auth/login',
+    '  body: { email: ":email", password: ":password" }',
+    '  params: [email, password]',
+    '  expect: { status: 200 }',
+    '',
+    'create_item:',
+    '  datasource: app_api',
+    '  method: POST',
+    '  path: /items',
+    '  headers: { authorization: "Bearer :token" }   # only :token is dynamic; the scheme is the contract',
+    '  body: { name: ":name" }',
+    '  params: [name, token]',
+    '  expect: { status: 201 }',
+    '',
+    'get_item:',
+    '  datasource: app_api',
+    '  method: GET',
+    '  path: /items/:id',
+    '  headers: { authorization: "Bearer :token" }',
+    '  params: [id, token]',
+    '  expect: { status: 200 }',
+    '',
+    'delete_item:',
+    '  datasource: app_api',
+    '  method: DELETE',
+    '  path: /items/:id',
+    '  headers: { authorization: "Bearer :token" }',
+    '  params: [id, token]',
+    '  expect: { status: 204 }',
+    '',
+  ].join('\n');
+}
+
+function flowTestDataStub(): string {
+  return [
+    '# Inputs for the flow. The created id + token are threaded from responses at runtime',
+    '# ({{create_item.body.id}}, {{login.body.token}}) — only the seed inputs live here.',
+    'email: "flow-user@example.com"',
+    'password: "change-me"',
+    'item_name: "Sample item"',
+    '',
+  ].join('\n');
+}
+
 function fail(e: unknown): never {
   console.error('Error:', e instanceof Error ? e.message : e);
   process.exit(1);

package/src/index.ts

@@ -55,6 +55,11 @@ export { importCsv, parseCsv } from './csv-import';
 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_]*)(?:\((.*)\))?$/;
+  // @concurrent:N (AP-5): fire each @api call N times in parallel and bind aggregates
+  // ({{name.ok_count}}, {{name.status_counts}}) — the idempotency/race oracle. Applies to the
+  // scenario's @api call(s); pair with @query to cross-check the DB ("exactly one charge").
+  const concMatch = input.tags.map((t) => t.match(/^@concurrent:(\d+)$/)).find(Boolean);
+  const concurrent = concMatch ? Math.max(1, parseInt(concMatch[1], 10)) : 0;
   for (const tag of input.tags) {
     const m = tag.match(TAG);
     if (!m) continue;
@@ -66,10 +71,20 @@ function apiPreconditionCodegen(input: { tags: string[]; screenName: string; cwd
       .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} }`;
+    // `headers` (catalog templates, e.g. authorization: "Bearer :token") are embedded at compile time;
+    // their `:param` placeholders bind at runtime from the same params — this is the flow auth/token
+    // mechanism (the dynamic value comes via an override like `token={{login.body.token}}`).
+    const hdr = entry.headers && Object.keys(entry.headers).length ? `, headers: ${JSON.stringify(entry.headers)}` : '';
+    const req = `{ method: ${JSON.stringify(entry.method)}, path: ${JSON.stringify(entry.path)}${entry.body !== undefined ? `, body: ${JSON.stringify(entry.body)}` : ''}${hdr}, datasource: ${ds} }`;
+    // @concurrent:N → callN (N parallel calls, aggregate result); else a single call.
+    const callExpr = concurrent
+      ? `await api.callN(${label}, ${req}, { ${paramsObj} }, ${concurrent})`
+      : `await api.call(${label}, ${req}, { ${paramsObj} })`;
     out.push({
-      comment: `@api:${name} → bind {{${name}}} (${entry.method} ${entry.path})`,
-      code: `testData.bind(${JSON.stringify(name)}, await api.call(${label}, ${req}, { ${paramsObj} }));`,
+      comment: concurrent
+        ? `@api:${name} ×${concurrent} (@concurrent) → bind {{${name}}} aggregates (${entry.method} ${entry.path})`
+        : `@api:${name} → bind {{${name}}} (${entry.method} ${entry.path})`,
+      code: `testData.bind(${JSON.stringify(name)}, ${callExpr});`,
       boundVars: [name],
     });
   }