@sungen/driver-api 3.1.2-beta.99 → 3.2.0-beta.142

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-api",
-  "version": "3.1.2-beta.99",
+  "version": "3.2.0-beta.142",
   "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.99",
+    "@sun-asterisk/sungen": "3.2.0-beta.142",
     "commander": "^14.0.2",
     "yaml": "^2.8.2"
   },

package/src/api-catalog.ts

@@ -27,6 +27,8 @@ export interface ApiEntry {
   method: HttpMethod;
   path: string;
   body?: unknown;
+  encoding?: 'json' | 'form' | 'multipart'; // request-body wire format (default json); form = application/x-www-form-urlencoded
+  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;
@@ -51,7 +53,9 @@ const _cache = new Map<string, LoadedApiCatalog>();
 export function findApiCatalogFiles(screenName: string, cwd: string = process.cwd()): ApiCatalogFiles {
   const out: ApiCatalogFiles = {};
   if (!screenName) return out;
-  const screenDir = screenName.startsWith('flows/')
+  // `screenName` is a unit id relative to qa/: `<screen>` (→ qa/screens/<screen>), `flows/<flow>`,
+  // or an api-first unit `api/<area>` / `api/flows/<flow>` (→ qa/<screenName>).
+  const screenDir = screenName.startsWith('flows/') || screenName.startsWith('api/')
     ? path.join(cwd, 'qa', screenName)
     : path.join(cwd, 'qa', 'screens', screenName);
   const screenFile = path.join(screenDir, 'api', 'apis.yaml');
@@ -66,6 +70,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 +90,8 @@ function parseEntries(file: string, scope: 'screen' | 'shared'): Map<string, Api
       method: String(v.method).toUpperCase() as HttpMethod,
       path: v.path,
       body: v.body,
+      encoding: v.encoding === 'form' || v.encoding === 'multipart' ? v.encoding : undefined, // default (undefined) = json
+      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 +135,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 +146,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/api-context.ts

@@ -0,0 +1,52 @@
+/**
+ * API discovery + context-mapping (AO-3) — the `api` capability's Discover → Contextualize hooks.
+ *
+ * Discovery reads the reviewed catalog (apis.yaml) + notes the spec source; context-mapping turns
+ * the endpoints into generation units by method-profile: every endpoint → a `matrix` unit (contract
+ * + error), each mutating endpoint → also an `async` unit (idempotency), and an api flow → a `flow`
+ * unit (the ordered journey). The orchestration loop (`sungen context` → `/sungen:design`) consumes
+ * these to know WHAT to author before writing scenarios. Type-only on core.
+ */
+import type { Context, DiscoveryProvider, ContextMapper, GenerationUnit } from '@sun-asterisk/sungen';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { lintApiCatalog } from './api-catalog';
+
+interface EndpointFact { name: string; method: string; path: string; datasource?: string; expectStatus?: number | string }
+
+const MUTATING = /^(POST|PUT|PATCH|DELETE)$/;
+
+export const apiDiscovery: DiscoveryProvider = {
+  appliesTo: (t) => t.kind === 'api',
+  discover: async (target, scope) => {
+    const cwd = (scope as { cwd?: string } | undefined)?.cwd ?? process.cwd();
+    const unitId = target.id; // `api/<area>` | `api/flows/<flow>`
+    let endpoints: EndpointFact[] = [];
+    try {
+      endpoints = lintApiCatalog(unitId, null, cwd).entries.map((e) => ({
+        name: e.name, method: e.method, path: e.path, datasource: e.datasource, expectStatus: e.expect?.status,
+      }));
+    } catch { /* no catalog → the verification gate reports it */ }
+
+    const sources: Record<string, unknown> = {};
+    const specPath = path.join(cwd, 'qa', unitId, 'requirements', 'spec.md');
+    if (fs.existsSync(specPath)) sources.spec = path.relative(cwd, specPath);
+
+    return { target: { ...target, capability: 'api' }, sources, facts: { endpoints } };
+  },
+};
+
+export const apiContextMapper: ContextMapper = {
+  decompose: (ctx: Context): GenerationUnit[] => {
+    const endpoints = ((ctx.facts ?? {}) as { endpoints?: EndpointFact[] }).endpoints ?? [];
+    const units: GenerationUnit[] = [];
+    const isFlow = typeof ctx.target.id === 'string' && ctx.target.id.includes('/flows/');
+    if (isFlow) units.push({ mode: 'flow', targetSlice: ctx.target }); // the ordered journey is one unit
+    for (const e of endpoints) {
+      units.push({ mode: 'matrix', targetSlice: e });                       // contract + error matrix (70%)
+      if (MUTATING.test(e.method)) units.push({ mode: 'async', targetSlice: e }); // idempotency/concurrency (10%)
+    }
+    if (!units.length) units.push({ mode: 'matrix', targetSlice: ctx.target });
+    return units;
+  },
+};

package/src/api-harness.ts

@@ -0,0 +1,143 @@
+/**
+ * API harness — the `api` capability's score-bearing gate + viewpoint catalog (AO-2).
+ *
+ * The audit engine is capability-routed (AO-1): for an `api/<area>` unit it calls THIS capability's
+ * `viewpoints()` + `gateProvider()` instead of the UI ones, then assembles the score with the same
+ * `0.4·coverage + 0.3·businessDepth + 0.15·balance + 0.15·trace` formula. We compute API-native
+ * coverage + depth here (not the UI keyword model), so an API area is scored on what matters for an
+ * API: contract + failure coverage, and — the headline — `businessDepth`: do the business-critical
+ * (mutating) scenarios PROVE THE EFFECT (assert body / DB side-effect / concurrency invariant), or
+ * just the status?
+ *
+ * Type-only on core (like the rest of the driver) — the depth threshold + project context arrive via
+ * the gate input, so loading the driver never forces a core runtime resolve.
+ */
+import type { Catalog, GateResult, DepthResult } from '@sun-asterisk/sungen';
+import { resolveApi } from './api-catalog';
+
+/** A scenario as the audit parses it (the subset the API gate reads). */
+interface ApiScenario {
+  name: string;
+  apiRefs?: string[];
+  queryRefs?: string[];
+  casesDataset?: string;
+  stepsText?: string; // lowercase steps text
+  manual?: boolean;   // @manual — not automated, so excluded from automation businessDepth
+}
+
+interface ApiGateInput {
+  scenarios: ApiScenario[];
+  focus: string;
+  cwd: string;
+  screenName: string; // catalog-resolution id, e.g. `api/<area>`
+  threshold: number;  // required businessDepth for the focus (from core)
+  businessCriticalMethods?: string[]; // end-user override (qa/context.md) — default POST/PUT/PATCH/DELETE
+}
+
+const DEFAULT_CRITICAL = ['POST', 'PUT', 'PATCH', 'DELETE'];
+
+/**
+ * The API viewpoint catalog (display + the project-override seam). The gate computes coverage from
+ * the live `apis.yaml`, so this is intentionally light — one universal theme per viewpoint category.
+ */
+export function apiViewpoints(): Catalog {
+  const theme = (t: string, keywords: string[]) => ({ theme: t, keywords });
+  return {
+    page_types: {
+      // method-profiles (the API analog of UI page-types) — documented; the gate enforces them.
+      read: { detect_keywords: ['get', 'list', 'fetch'], must_cover: [theme('contract', ['status', 'body'])] },
+      mutating: {
+        detect_keywords: ['create', 'update', 'delete', 'post', 'put', 'patch'],
+        must_cover: [theme('contract', ['status', 'body']), theme('error', ['4', '5', 'invalid', 'cases'])],
+      },
+    },
+    universal: [theme('contract', ['status']), theme('error', ['4', '5'])],
+  };
+}
+
+/**
+ * Score-bearing API gate: coverage (must-cover viewpoints per endpoint, by method-profile) + depth
+ * (mutating scenarios that prove the effect). Returns the same `{gate, depth}` shape the audit
+ * assembles into the score.
+ */
+export function apiGateProvider(input: ApiGateInput): { gate: GateResult; depth: DepthResult } {
+  const { scenarios, focus, cwd, screenName, threshold } = input;
+  // Business-critical (depth-required) HTTP methods — end-user customizable via qa/context.md
+  // (`business_critical_methods: …`), e.g. to mark GET on a read-sensitive resource as critical.
+  const criticalMethods = (input.businessCriticalMethods?.length ? input.businessCriticalMethods : DEFAULT_CRITICAL).map((m) => m.toUpperCase());
+  const apiScenarios = scenarios.filter((s) => (s.apiRefs ?? []).length);
+
+  // Resolve each referenced endpoint's HTTP method (best-effort; unresolved → the verification
+  // sensor already fails the gate, so we just skip it here).
+  const methodOf = new Map<string, string>();
+  for (const s of apiScenarios) {
+    for (const name of s.apiRefs ?? []) {
+      if (methodOf.has(name)) continue;
+      try { methodOf.set(name, resolveApi(name, screenName, cwd).method); } catch { /* unresolved */ }
+    }
+  }
+  const isMutating = (name: string) => criticalMethods.includes((methodOf.get(name) ?? '').toUpperCase());
+
+  // ── Coverage: must-cover viewpoints per resolved endpoint ──────────────────────────────────
+  // read (GET/HEAD): {contract}; mutating: {contract, error}. (auth/idempotency/side-effect are
+  // advisory via the api-viewpoints sensor + rewarded through businessDepth, not coverage-gating.)
+  const asserts = (s: ApiScenario, endpoint: string, vp: 'contract' | 'error'): boolean => {
+    if (!(s.apiRefs ?? []).includes(endpoint)) return false;
+    const t = s.stepsText ?? '';
+    if (vp === 'contract') return new RegExp(`\\b${endpoint.toLowerCase()}\\.(status|ok|body|headers|ok_count|status_counts)\\b`).test(t);
+    return !!s.casesDataset || /\b[45]\d\d\b/.test(t); // error: a @cases matrix or an asserted 4xx/5xx
+  };
+  const gaps: GateResult['gaps'] = [];
+  let covered = 0;
+  let themesTotal = 0;
+  for (const endpoint of methodOf.keys()) {
+    const vps: ('contract' | 'error')[] = isMutating(endpoint) ? ['contract', 'error'] : ['contract'];
+    for (const vp of vps) {
+      themesTotal++;
+      if (apiScenarios.some((s) => asserts(s, endpoint, vp))) covered++;
+      else gaps.push({ theme: `${endpoint}:${vp}`, keywords: [], status: 'missing' });
+    }
+  }
+  const coverageRatio = themesTotal ? covered / themesTotal : 0;
+  const area = screenName.replace(/^api\//, '');
+  const gate: GateResult = {
+    pageType: `api:${area}`,
+    themesTotal,
+    themesCovered: covered,
+    coverageRatio,
+    gaps,
+    universalGaps: [],
+  };
+
+  // ── businessDepth: the SUCCESS path of a mutation must PROVE THE EFFECT, not just assert status ──
+  // An error scenario (a @cases matrix, or one asserting a 4xx/5xx) proves the failure CONTRACT —
+  // the status IS its correct assertion (the API analog of UI NAV), so it is not depth-required.
+  const errorLike = (s: ApiScenario) => !!s.casesDataset || /\bis\s+["']?[45]\d\d\b/.test(s.stepsText ?? '');
+  // businessDepth measures AUTOMATED proof — a @manual scenario isn't automated, so it can't count
+  // toward depth (else deferring an automatable mutation to @manual inflates the score). The
+  // api-viewpoints sensor separately flags @manual scenarios whose endpoint resolves (automatable).
+  const depthRequired = apiScenarios.filter((s) => !s.manual && (s.apiRefs ?? []).some(isMutating) && !errorLike(s));
+  const isDeep = (s: ApiScenario): boolean => {
+    const t = s.stepsText ?? '';
+    return /\b[a-z_][a-z0-9_]*\.body\b/.test(t)                 // asserts a response body field
+      || /\b[a-z_][a-z0-9_]*\.(ok_count|status_counts)\b/.test(t) // a concurrency invariant
+      || (s.queryRefs ?? []).length > 0;                          // a @query DB side-effect cross-check
+  };
+  const reqShallow = depthRequired.filter((s) => !isDeep(s));
+  const bcDepthRatio = depthRequired.length ? (depthRequired.length - reqShallow.length) / depthRequired.length : 1;
+  const verdict: DepthResult['verdict'] = bcDepthRatio < threshold ? (focus === 'smoke' ? 'warn' : 'fail') : 'pass';
+  const depth: DepthResult = {
+    total: apiScenarios.length,
+    shallowTotal: reqShallow.length,
+    shallowRatio: apiScenarios.length ? reqShallow.length / apiScenarios.length : 0,
+    businessCriticalTotal: depthRequired.length,
+    businessCriticalShallow: reqShallow.length,
+    bcDepthRatio,
+    shallowBusinessCritical: reqShallow.map((s) => ({ name: s.name, category: 'API' })),
+    focus,
+    threshold,
+    verdict,
+  };
+
+  return { gate, depth };
+}

package/src/api-repair.ts

@@ -0,0 +1,39 @@
+/**
+ * API repair catalog (#343) — the `api` capability's deterministic fix rules.
+ *
+ * `sungen repair --api <area>` matches each audit finding + runtime failure against these rules and
+ * proposes the concrete fix. Same catalog the `/sungen:run-test` API mode + `sungen-api-design`
+ * repair loop apply by hand — here it is capability-owned DATA, so it composes audit + runtime
+ * signals into one plan and a project/driver can extend it. Type-only on core.
+ */
+import type { RepairProvider } from '@sun-asterisk/sungen';
+
+export const apiRepair: RepairProvider = {
+  rules: [
+    // ── Coverage / depth (from `sungen audit --api`) ──────────────────────────────────────────
+    { id: 'api-contract', match: /VIEWPOINT-API-CONTRACT/i,
+      fix: 'The endpoint is invoked but its response is never asserted — add `expect {{name.status}} is …` plus a body check `{{name.body.<field>}}`.' },
+    { id: 'api-error', match: /VIEWPOINT-API-ERROR/i,
+      fix: 'A mutating endpoint has no failure scenario — add a `@cases` error matrix (input → expected status) or an explicit 4xx assertion (the ~70% band).' },
+    { id: 'api-idempotency', match: /VIEWPOINT-API-IDEMPOTENCY/i,
+      fix: 'A mutating endpoint has no race check — add `@concurrent:N` + assert `{{name.ok_count}} is 1`, cross-checked with a `@query` DB count (the ~10% band).' },
+    { id: 'api-depth', match: /DEPTH-?FAIL|businessDepth|SHALLOW/i,
+      fix: 'A mutating success scenario only asserts the status — make it PROVE THE EFFECT: assert a response body field, a `@query` DB side-effect, or a `@concurrent` `ok_count` invariant.' },
+    { id: 'api-verification', match: /VERIFICATION-FAIL|does not resolve|not found in/i,
+      fix: 'An `@api:<name>` does not resolve in the catalog — fix the name, or add/import the endpoint into `api/apis.yaml` (`sungen api import`).' },
+    { id: 'api-manual-automatable', match: /VIEWPOINT-API-MANUAL-AUTOMATABLE/i,
+      fix: 'A @manual scenario is automatable (its endpoint resolves) — drop @manual and use @api (+ @cases for error rows / @concurrent for idempotency). Reserve @manual for genuine judgment cases.' },
+
+    // ── Runtime failures (from the Playwright test-result) ────────────────────────────────────
+    { id: 'api-auth', match: /\b40[13]\b|unauthor|forbidden/i,
+      fix: 'Auth failure (401/403) — tag the scenario `@hybrid` + `@auth:<role>` to reuse the UI session, or wire a catalog `authorization: "Bearer :token"` header; capture a session with `sungen makeauth <role>`.' },
+    { id: 'api-datasource', match: /base_url|ECONNREFUSED|ENOTFOUND|ENETUNREACH|getaddrinfo/i,
+      fix: 'The API was unreachable — set the datasource `${X_URL}` key in `.env.qa` (from `sungen api init`) and confirm the service is up / non-prod.' },
+    { id: 'api-status-mismatch', match: /expected.*status|status.*expected|toBe.*\b[45]\d\d\b|received.*\b[45]\d\d\b/i,
+      fix: 'Asserted status ≠ actual — reconcile the expectation against `apis.yaml`/spec (the catalog is the oracle). Never hand-edit the generated spec; fix the feature/test-data and re-`generate --api`.' },
+    { id: 'api-timeout', match: /timeout|timed out|exceeded/i,
+      fix: 'Request timed out — raise the datasource `timeout_ms`, or check the endpoint/path; for flows ensure prior steps bound the values the call needs.' },
+    { id: 'api-flaky', match: /flak|intermitt|conflict|already exists|duplicate key/i,
+      fix: 'Likely state bleed — make the flow self-cleaning (delete what it created / `@cleanup`), isolate `@cases` rows, and cap `@concurrent`.' },
+  ],
+};

package/src/cli-import.ts

@@ -2,58 +2,308 @@ 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';
+import { importOpenApi, type ImportedApiEntry, type ImportResult } from './openapi-import';
+import { importCsv } from './csv-import';
 
 /**
- * `sungen api …` — API Driver authoring commands (P3, Mode A).
- * For now: `import` an OpenAPI/Swagger doc into a reviewed `api/apis.yaml` catalog.
+ * `sungen api …` — API Driver authoring (Mode A).
+ *   init    — scaffold the API project (kind: api datasource + qa/api + .env key)
+ *   add     — scaffold one area (resource/tag): qa/api/<area>/…
+ *   import  — OpenAPI/Swagger OR CSV/Google-Sheet → apis.yaml, grouped into areas by tag
  */
+
+const CATALOG_HEADER =
+  '# Named-endpoint catalog (API Driver) — generated by `sungen api import`.\n' +
+  '# Review the request shape, wire each `datasource` in datasources.yaml (kind: api),\n' +
+  '# then reference an endpoint from a scenario with `@api:<name>`.\n';
+
+const slug = (s: string) => s.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '').toLowerCase();
+const rel = (p: string) => path.relative(process.cwd(), p);
+
+function writeCatalog(file: string, entries: Record<string, ImportedApiEntry>, merge: boolean): void {
+  let out = entries;
+  if (fs.existsSync(file)) {
+    if (!merge) throw new Error(`${rel(file)} already exists — pass --merge to combine.`);
+    const existing = parseYaml(fs.readFileSync(file, 'utf8')) || {};
+    out = { ...existing, ...entries }; // imported entries win on name clash
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, CATALOG_HEADER + stringifyYaml(out));
+}
+
+/** Read a source path or http(s) URL (a published Google-Sheet CSV) → text. */
+async function readSource(source: string): Promise<string> {
+  if (/^https?:\/\//.test(source)) {
+    const res = await fetch(source);
+    if (!res.ok) throw new Error(`fetch ${source} → ${res.status}`);
+    return await res.text();
+  }
+  if (!fs.existsSync(source)) throw new Error(`source not found: ${source}`);
+  return fs.readFileSync(source, 'utf8');
+}
+
+/** Detect OpenAPI vs CSV: a parseable doc with `paths`/`openapi`/`swagger` is OpenAPI; else CSV. */
+function importAny(source: string, text: string, datasource: string): { result: ImportResult; kind: 'openapi' | 'csv' } {
+  if (/\.csv$/i.test(source)) return { result: importCsv(text, datasource), kind: 'csv' };
+  let doc: any;
+  try { doc = parseYaml(text); } catch { doc = undefined; } // yaml lib also parses JSON
+  if (doc && typeof doc === 'object' && (doc.paths || doc.openapi || doc.swagger)) {
+    return { result: importOpenApi(doc, datasource), kind: 'openapi' };
+  }
+  return { result: importCsv(text, datasource), kind: 'csv' };
+}
+
 export function registerApiCommand(program: Command): void {
-  const api = program.command('api').description('API Driver authoring (import an OpenAPI spec into an apis.yaml catalog)');
+  const api = program.command('api').description('API Driver authoring — init · add · import');
 
+  // ── init ─────────────────────────────────────────────────────────────────
   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 }) => {
+    .command('init')
+    .description('Scaffold an API project: a kind:api datasource + qa/api/ + the .env.qa URL key')
+    .requiredOption('--base-url <url>', 'API base URL (stored in .env.qa, referenced as ${<DS>_URL})')
+    .option('--datasource <name>', 'Datasource name', 'app_api')
+    .action((opts: { baseUrl: string; datasource: string }) => {
       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
+        const ds = opts.datasource;
+        const envKey = `${ds.toUpperCase()}_URL`;
+        fs.mkdirSync(path.join(process.cwd(), 'qa', 'api'), { recursive: true });
+
+        // datasources.yaml — merge (never clobber other datasources)
+        const dsFile =
+          [path.join(process.cwd(), 'qa', 'datasources.yaml'), path.join(process.cwd(), 'datasources.yaml')].find((f) => fs.existsSync(f)) ||
+          path.join(process.cwd(), 'qa', 'datasources.yaml');
+        const dsDoc: any = fs.existsSync(dsFile) ? parseYaml(fs.readFileSync(dsFile, 'utf8')) || {} : {};
+        dsDoc.datasources = dsDoc.datasources || {};
+        if (!dsDoc.datasources[ds]) {
+          dsDoc.datasources[ds] = { kind: 'api', base_url: `\${${envKey}}`, timeout_ms: 15000 };
+          fs.mkdirSync(path.dirname(dsFile), { recursive: true });
+          fs.writeFileSync(dsFile, stringifyYaml(dsDoc));
+          console.log(`✓ datasource "${ds}" (kind: api) → ${rel(dsFile)}`);
+        } else {
+          console.log(`• datasource "${ds}" already in ${rel(dsFile)} — left as is`);
         }
 
-        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));
+        // .env.qa (real value, gitignored) + .env.qa.example (key only)
+        upsertEnv(path.join(process.cwd(), '.env.qa'), envKey, opts.baseUrl);
+        upsertEnv(path.join(process.cwd(), '.env.qa.example'), envKey, '');
+        console.log(`✓ ${envKey} → .env.qa (value) + .env.qa.example (key)`);
+        console.log('\nNext: `sungen api import <openapi|csv|sheet-url>` or `sungen api add --area <name>`.\n');
+      } catch (e) { fail(e); }
+    });
+
+  // ── add ──────────────────────────────────────────────────────────────────
+  api
+    .command('add')
+    .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 {
+        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.`);
+        for (const d of ['features', 'test-data', 'requirements', 'api']) fs.mkdirSync(path.join(base, d), { recursive: true });
+        fs.writeFileSync(path.join(base, 'features', `${area}.feature`), featureStub(area));
+        fs.writeFileSync(path.join(base, 'test-data', `${area}.yaml`), `# Test data for the ${area} API area.\n`);
+        fs.writeFileSync(path.join(base, 'requirements', 'spec.md'), `# ${area} API\n\n_Describe the ${area} endpoints, rules, and expected responses here (or import an OpenAPI/CSV)._\n`);
+        fs.writeFileSync(path.join(base, 'api', 'apis.yaml'), CATALOG_HEADER);
+        console.log(`✓ area "${area}" → ${rel(base)}/`);
+        console.log(`\nNext: import or hand-author ${rel(path.join(base, 'api', 'apis.yaml'))}, then add @api scenarios in features/${area}.feature.\n`);
+      } catch (e) { fail(e); }
+    });
+
+  // ── import ───────────────────────────────────────────────────────────────
+  api
+    .command('import <source>')
+    .description('Generate apis.yaml from an OpenAPI/Swagger doc OR a CSV / published Google-Sheet URL')
+    .option('--datasource <name>', 'Default datasource for imported endpoints', 'app_api')
+    .option('--single', 'Write one shared qa/api/apis.yaml (default: one file per area)')
+    .option('--screen <name>', 'Legacy: write to qa/screens/<name>/api/apis.yaml')
+    .option('--merge', 'Merge into an existing catalog instead of refusing to overwrite')
+    .action(async (source: string, opts: { datasource: string; single?: boolean; screen?: string; merge?: boolean }) => {
+      try {
+        const text = await readSource(source);
+        const { result, kind } = importAny(source, text, opts.datasource);
+        const { entries, count, skipped } = result;
+        if (count === 0) throw new Error(`No endpoints imported (${skipped.join('; ') || 'empty source'}).`);
 
-        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}` : ''}`);
+        const written: string[] = [];
+        if (opts.screen) {
+          const f = path.join(process.cwd(), 'qa', 'screens', opts.screen, 'api', 'apis.yaml');
+          writeCatalog(f, entries, !!opts.merge);
+          written.push(rel(f));
+        } else if (opts.single) {
+          const f = path.join(process.cwd(), 'qa', 'api', 'apis.yaml');
+          writeCatalog(f, entries, !!opts.merge);
+          written.push(rel(f));
+        } else {
+          // group by area → qa/api/<area>/api/apis.yaml + a runnable contract-scenario stub.
+          const byArea: Record<string, Record<string, ImportedApiEntry>> = {};
+          for (const [name, e] of Object.entries(entries)) (byArea[e.area || 'root'] ||= {})[name] = e;
+          for (const [area, group] of Object.entries(byArea)) {
+            const f = path.join(process.cwd(), 'qa', 'api', area, 'api', 'apis.yaml');
+            writeCatalog(f, group, !!opts.merge);
+            written.push(`${rel(f)} (${Object.keys(group).length})`);
+            // Scaffold the feature so `sungen generate --api <area>` has something to compile — one
+            // happy-path contract scenario per endpoint (the 70% baseline). Don't clobber edits.
+            const featFile = path.join(process.cwd(), 'qa', 'api', area, 'features', `${area}.feature`);
+            if (!fs.existsSync(featFile)) {
+              fs.mkdirSync(path.dirname(featFile), { recursive: true });
+              fs.writeFileSync(featFile, importedFeatureStub(area, group));
+              written.push(`${rel(featFile)} (${Object.keys(group).length} contract scenario(s))`);
+            }
+          }
         }
-        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);
-      }
+
+        console.log(`\n✓ Imported ${count} endpoint(s) from ${kind} source:`);
+        for (const w of written) console.log(`   → ${w}`);
+        if (skipped.length) console.log(`\n⚠ Skipped: ${skipped.slice(0, 10).join('; ')}${skipped.length > 10 ? ` … (+${skipped.length - 10})` : ''}`);
+        console.log('\nNext: wire the `datasource` base_url + auth in datasources.yaml, refine the scenarios,');
+        console.log('then `sungen generate --api <area>` → `npx playwright test`.\n');
+      } catch (e) { fail(e); }
     });
 }
+
+function upsertEnv(file: string, key: string, value: string): void {
+  const line = `${key}=${value}`;
+  if (!fs.existsSync(file)) { fs.writeFileSync(file, line + '\n'); return; }
+  const content = fs.readFileSync(file, 'utf8');
+  if (new RegExp(`^\\s*${key}\\s*=`, 'm').test(content)) return; // already present — don't overwrite a real value
+  fs.writeFileSync(file, content.replace(/\n?$/, '\n') + line + '\n');
+}
+
+/** A runnable feature from imported endpoints: one happy-path contract scenario each (the 70% baseline). */
+function importedFeatureStub(area: string, group: Record<string, ImportedApiEntry>): string {
+  const lines = [
+    `@parallel @area:${area}`,
+    `Feature: ${area} API`,
+    '',
+    '  # Auto-scaffolded from the imported catalog — one contract check per endpoint. Refine these:',
+    '  # add error cases with @cases, flows with ordered @api tags, idempotency with @concurrent:N.',
+    '  # `sungen audit` flags missing error/idempotency coverage on mutating endpoints.',
+    '',
+  ];
+  let i = 1;
+  for (const [name, e] of Object.entries(group)) {
+    const status = e.expect?.status ?? 200;
+    const seq = String(i++).padStart(3, '0');
+    lines.push(`  @high @api:${name}`);
+    lines.push(`  Scenario: VP-API-${seq} ${e.method} ${e.path} returns ${status}`);
+    lines.push(`    Then expect {{${name}.status}} is ${status}`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+function featureStub(area: string): string {
+  return [
+    `@area:${area}`,
+    `Feature: ${area} API`,
+    '',
+    '  # Reference an endpoint from api/apis.yaml with @api:<name>; assert the bound response with',
+    '  # expect {{<name>.status}} / {{<name>.body.<path>}}. Example:',
+    '  #',
+    `  # @api:get_${area}`,
+    `  # Scenario: VP-API-001 Fetching ${area} returns 200`,
+    `  #   Then expect {{get_${area}.status}} is 200`,
+    '',
+  ].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/csv-import.ts

@@ -0,0 +1,101 @@
+/**
+ * CSV / Google-Sheet → apis.yaml importer (API Driver, AP-2).
+ *
+ * Many teams keep their endpoint list in a spreadsheet (Google Sheet → "Publish to web" CSV, or an
+ * exported .csv). This turns that flat table into the same `ImportedApiEntry` catalog shape as the
+ * OpenAPI importer. Deterministic — no AI, no network (the CLI fetches a published-CSV URL; this
+ * module only parses text).
+ *
+ * Columns (header row, case-insensitive; aliases accepted):
+ *   name | area|tag | method | path | params | body | datasource|auth | expect_status | description
+ *   - params: separated by `;` or `|` (commas live inside quoted JSON, so don't use `,` here)
+ *   - body:   a JSON object string, values may be `:param` refs, e.g. {"item_id":":item_id"}
+ *   - expect_status: a number (e.g. 201)
+ */
+import type { ImportedApiEntry, ImportResult } from './openapi-import';
+
+/** RFC-4180-ish parser: handles quoted fields, embedded commas/newlines, and "" escapes. */
+export function parseCsv(text: string): string[][] {
+  const s = text.replace(/\r\n?/g, '\n');
+  const rows: string[][] = [];
+  let field = '';
+  let row: string[] = [];
+  let inQuotes = false;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (inQuotes) {
+      if (c === '"') {
+        if (s[i + 1] === '"') { field += '"'; i++; } else inQuotes = false;
+      } else field += c;
+    } else if (c === '"') inQuotes = true;
+    else if (c === ',') { row.push(field); field = ''; }
+    else if (c === '\n') { row.push(field); rows.push(row); row = []; field = ''; }
+    else field += c;
+  }
+  if (field.length || row.length) { row.push(field); rows.push(row); }
+  return rows.filter((r) => r.some((cell) => cell.trim() !== '')); // drop blank lines
+}
+
+const ALIASES: Record<string, string> = {
+  tag: 'area', auth: 'datasource', status: 'expect_status', expectstatus: 'expect_status',
+  endpoint: 'path', url: 'path', verb: 'method', key: 'name', desc: 'description',
+};
+const norm = (h: string) => {
+  const k = h.trim().toLowerCase().replace(/[\s-]+/g, '_');
+  return ALIASES[k.replace(/_/g, '')] || ALIASES[k] || k;
+};
+const slug = (s: string) => s.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '').toLowerCase();
+
+/**
+ * Transform a CSV/Sheet table into catalog entries.
+ * @param text   raw CSV
+ * @param datasource default datasource when a row omits one (default 'app_api')
+ */
+export function importCsv(text: string, datasource = 'app_api'): ImportResult {
+  const rows = parseCsv(text);
+  const entries: Record<string, ImportedApiEntry> = {};
+  const skipped: string[] = [];
+  if (rows.length < 2) return { entries, count: 0, skipped: ['CSV has no data rows (need a header + ≥1 row)'] };
+
+  const header = rows[0].map(norm);
+  const col = (r: string[], name: string): string => {
+    const i = header.indexOf(name);
+    return i >= 0 && i < r.length ? r[i].trim() : '';
+  };
+
+  for (let n = 1; n < rows.length; n++) {
+    const r = rows[n];
+    const name = col(r, 'name');
+    const method = col(r, 'method').toUpperCase();
+    const path = col(r, 'path');
+    if (!name || !method || !path) { skipped.push(`row ${n + 1} (missing name/method/path)`); continue; }
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) { skipped.push(`row ${n + 1} ("${name}" is not a valid catalog key)`); continue; }
+    if (entries[name]) { skipped.push(`row ${n + 1} (duplicate name "${name}")`); continue; }
+
+    const area = slug(col(r, 'area')) || slug(path.replace(/^\/+/, '').split('/')[0]) || 'root';
+    const pathParams = (path.match(/:([A-Za-z_][A-Za-z0-9_]*)/g) || []).map((x) => x.slice(1));
+    const declared = col(r, 'params').split(/[;|]/).map((p) => p.trim()).filter(Boolean);
+    const params = [...new Set([...pathParams, ...declared])];
+
+    let body: Record<string, string> | undefined;
+    const bodyCell = col(r, 'body');
+    if (bodyCell) {
+      try { body = JSON.parse(bodyCell); } catch { skipped.push(`row ${n + 1} (body is not valid JSON — kept no body)`); }
+    }
+    const statusCell = col(r, 'expect_status');
+    const status = /^\d+$/.test(statusCell) ? Number(statusCell) : undefined;
+    const description = col(r, 'description') || undefined;
+
+    entries[name] = {
+      datasource: col(r, 'datasource') || datasource,
+      area,
+      ...(description ? { description } : {}),
+      method,
+      path,
+      ...(params.length ? { params } : {}),
+      ...(body ? { body } : {}),
+      ...(status != null ? { expect: { status } } : {}),
+    };
+  }
+  return { entries, count: Object.keys(entries).length, skipped };
+}

package/src/index.ts

@@ -12,13 +12,43 @@
  * 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 ONLY types from core (erased at runtime) — never a runtime value. A runtime import of
+// @sun-asterisk/sungen forces core to be resolved when this driver loads, which fails if a stale or
+// wrong-version core is on the module path (the source of repeated "Cannot find …/dist/index.js" /
+// "not resolvable" install errors). Keeping core type-only makes the driver load with no core on disk.
 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';
+import { apiViewpoints, apiGateProvider } from './api-harness';
+import { apiDiscovery, apiContextMapper } from './api-context';
+import { apiRepair } from './api-repair';
+
+/**
+ * Parse `name(a={{x}},b="lit",c=3)` annotation overrides → JS expressions. Inlined from core
+ * (was `parseQueryOverrides`) so this driver has NO runtime dependency on @sun-asterisk/sungen.
+ */
+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;
+}
 
 export { importOpenApi } from './openapi-import';
 export type { ImportedApiEntry, ImportResult } from './openapi-import';
+export { importCsv, parseCsv } from './csv-import';
 
 /**
  * API precondition codegen: `@api:<name>[(p={{v}},…)]` → run the catalog request and bind the
@@ -28,6 +58,18 @@ export type { ImportedApiEntry, ImportResult } from './openapi-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;
+  // @hybrid (AP-6): reuse the UI session — load the scenario's @auth:<role> storageState
+  // (specs/.auth/<role>.json, written by the auth global-setup before any test) so the API request
+  // carries the same authenticated cookies as the browser. No effect without an @auth role.
+  const authMatch = input.tags.map((t) => t.match(/^@auth:([A-Za-z0-9_-]+)$/)).find(Boolean);
+  const optsArg = input.tags.includes('@hybrid') && authMatch
+    ? `, { storageState: ${JSON.stringify(`specs/.auth/${authMatch[1]}.json`)} }`
+    : '';
   for (const tag of input.tags) {
     const m = tag.match(TAG);
     if (!m) continue;
@@ -39,10 +81,23 @@ 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)}` : '';
+    // request-body wire format (default json); `form` → x-www-form-urlencoded, `multipart` → form-data (#345).
+    const enc = entry.encoding ? `, encoding: ${JSON.stringify(entry.encoding)}` : '';
+    const req = `{ method: ${JSON.stringify(entry.method)}, path: ${JSON.stringify(entry.path)}${entry.body !== undefined ? `, body: ${JSON.stringify(entry.body)}` : ''}${enc}${hdr}, datasource: ${ds} }`;
+    // @concurrent:N → callN (N parallel calls, aggregate result); else a single call. @hybrid adds
+    // the storageState opts so the request reuses the UI auth session.
+    const callExpr = concurrent
+      ? `await api.callN(${label}, ${req}, { ${paramsObj} }, ${concurrent}${optsArg})`
+      : `await api.call(${label}, ${req}, { ${paramsObj} }${optsArg})`;
     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],
     });
   }
@@ -74,6 +129,68 @@ const apiVerificationSensor: Sensor<GateInput> = {
   },
 };
 
+/**
+ * API `viewpoints` gate sensor (AP-6): coverage feedback for the API surface, advisory (warn/info,
+ * never fails the gate). Classifies the feature's `@api` scenarios into the three API viewpoints and
+ * surfaces gaps — severity-weighted by method (read-only GET/HEAD surfaces don't expect error/idempotency):
+ *  - `api-contract`     — every invoked endpoint must have its response asserted ({{name.status|body}}).
+ *  - `api-error`        — a mutating endpoint without ANY failure scenario (@cases matrix or a 4xx/5xx) — the 70% band.
+ *  - `api-idempotency`  — a mutating endpoint without a @concurrent aggregate check ({{name.ok_count}}) — the 10% band.
+ * Reads the already-parsed scenarios (apiRefs + lowercase stepsText + casesDataset) — no re-parse.
+ */
+const apiViewpointSensor: Sensor<GateInput> = {
+  id: 'api-viewpoints',
+  capability: 'api',
+  kind: 'gate',
+  run: ({ screenName, scenarios, cwd }) => {
+    const findings = [] as ReturnType<Sensor['run']>;
+    const add = (severity: 'warn' | 'info', message: string) => findings.push({ sensorId: 'api-viewpoints', capability: 'api', message, severity });
+    const apiScenarios = scenarios.filter((s) => (s.apiRefs ?? []).length);
+    if (!apiScenarios.length) return findings;
+
+    const refs = new Set<string>();
+    for (const s of apiScenarios) for (const r of s.apiRefs ?? []) refs.add(r);
+
+    // api-contract — each invoked endpoint's response is asserted somewhere.
+    for (const name of refs) {
+      const re = new RegExp(`\\b${name.toLowerCase()}\\.(status|ok|body|headers|ok_count|status_counts)\\b`);
+      if (!apiScenarios.some((s) => re.test(s.stepsText ?? ''))) {
+        add('warn', `VIEWPOINT-API-CONTRACT: @api:${name} is invoked but its response is never asserted — add the contract check (expect {{${name}.status}} / {{${name}.body.…}}).`);
+      }
+    }
+
+    // api-manual-automatable — a @manual scenario whose @api endpoint RESOLVES is automatable; flag it
+    // so automatable work isn't deferred to manual (a common run-test reflex when the call failed).
+    for (const s of apiScenarios) {
+      if (!s.manual) continue;
+      const automatable = (s.apiRefs ?? []).filter((r) => { try { resolveApi(r, screenName, cwd); return true; } catch { return false; } });
+      if (automatable.length) {
+        add('warn', `VIEWPOINT-API-MANUAL-AUTOMATABLE: "${s.name}" is @manual but its endpoint(s) ${automatable.join(', ')} resolve in the catalog — automate with @api (+ @cases for error rows); don't defer an automatable API check to manual.`);
+      }
+    }
+
+    // Method-aware: error + idempotency only apply when a referenced endpoint MUTATES.
+    const mutating: string[] = [];
+    for (const name of refs) {
+      try { if (/^(POST|PUT|PATCH|DELETE)$/.test(resolveApi(name, screenName, cwd).method)) mutating.push(name); } catch { /* unresolved → the verification sensor reports it */ }
+    }
+    if (!mutating.length) return findings; // read-only surface — no error/idempotency expectation
+
+    // api-error — a failure scenario exists: a @cases matrix, or an asserted 4xx/5xx.
+    const hasError = apiScenarios.some((s) => s.casesDataset || /\b[45]\d\d\b/.test(s.stepsText ?? ''));
+    if (!hasError) {
+      add('warn', `VIEWPOINT-API-ERROR: mutating endpoint(s) ${mutating.join(', ')} have no failure scenario (4xx/auth/validation) — add a @cases error matrix or an explicit 4xx assertion (the ~70% success+failure band).`);
+    }
+
+    // api-idempotency — a @concurrent aggregate check exists.
+    const hasIdem = apiScenarios.some((s) => /\b\w+\.(ok_count|status_counts)\b/.test(s.stepsText ?? ''));
+    if (!hasIdem) {
+      add('info', `VIEWPOINT-API-IDEMPOTENCY: no @concurrent idempotency/race check on a mutating endpoint — consider @concurrent:N + a @query DB cross-check (the ~10% band).`);
+    }
+    return findings;
+  },
+};
+
 /** Register the API capability. */
 export function register(registry: CapabilityRegistry): void {
   registry.register({
@@ -81,7 +198,12 @@ export function register(registry: CapabilityRegistry): void {
     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],
+    sensors: [apiVerificationSensor, apiViewpointSensor],
+    viewpoints: apiViewpoints as () => unknown,       // AO-2: API viewpoint catalog
+    gateProvider: apiGateProvider as (i: unknown) => unknown, // AO-2: API coverage + businessDepth
+    discovery: apiDiscovery,           // AO-3: catalog/spec → Context slice
+    contextMapper: apiContextMapper,   // AO-3: endpoints → matrix/async/flow generation units
+    repair: apiRepair,                 // #343: finding/failure → concrete fix catalog
     cliCommands: [registerApiCommand as (program: unknown) => void], // `sungen api import <openapi>`
   });
 }

package/src/openapi-import.ts

@@ -8,16 +8,32 @@
  */
 export interface ImportedApiEntry {
   datasource: string;
+  area: string;            // resource/tag group (OpenAPI tag, else first path segment)
   description?: string;
   method: string;
   path: string;
   params?: string[];
   body?: Record<string, string>;
+  encoding?: 'form' | 'multipart'; // set when the requestBody is form/multipart (json omitted = default)
   expect?: { status: number };
 }
 
 const METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
 
+/** A safe lower-snake slug for area/tag names. */
+function slug(s: string): string {
+  return s.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '').toLowerCase();
+}
+
+/** Group an operation by its first OpenAPI tag (à la GitHub/Google/Swagger); fall back to the first
+ *  path segment (`/orders/{id}` → `orders`). Deterministic — no AI. */
+function areaOf(op: any, rawPath: string): string {
+  const tag = Array.isArray(op?.tags) && typeof op.tags[0] === 'string' ? slug(op.tags[0]) : '';
+  if (tag) return tag;
+  const seg = rawPath.replace(/^\/+/, '').split('/')[0] || '';
+  return slug(seg) || 'root';
+}
+
 /** 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';
@@ -37,16 +53,24 @@ function expectedStatus(responses: Record<string, unknown> | undefined): number
   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;
+/** Body property names → a `{ prop: ":prop" }` template, + the wire encoding (json | form | multipart),
+ *  best-effort from the requestBody content-type (#345). JSON is the default (encoding omitted). */
+function bodyTemplate(op: any): { body?: Record<string, string>; props: string[]; encoding?: 'form' | 'multipart' } {
+  const content = op?.requestBody?.content ?? {};
+  // Prefer JSON; else fall back to form-urlencoded / multipart (those set encoding).
+  const pick = content['application/json'] ? { ct: 'application/json' as const, encoding: undefined }
+    : content['application/x-www-form-urlencoded'] ? { ct: 'application/x-www-form-urlencoded' as const, encoding: 'form' as const }
+      : content['multipart/form-data'] ? { ct: 'multipart/form-data' as const, encoding: 'multipart' as const }
+        : undefined;
+  if (!pick) return { props: [] };
+  const schema = content[pick.ct]?.schema;
   const props = schema && typeof schema === 'object' && schema.properties && typeof schema.properties === 'object'
     ? Object.keys(schema.properties)
     : [];
-  if (!props.length) return { props: [] };
+  if (!props.length) return { props: [], encoding: pick.encoding };
   const body: Record<string, string> = {};
   for (const p of props) body[p] = `:${p}`;
-  return { body, props };
+  return { body, props, encoding: pick.encoding };
 }
 
 export interface ImportResult {
@@ -74,7 +98,7 @@ export function importOpenApi(doc: any, datasource = 'app_api'): ImportResult {
 
       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 { body, props, encoding } = bodyTemplate(op);
       const params = [...new Set([...pathParams, ...props])];
 
       let name = typeof op.operationId === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(op.operationId)
@@ -86,11 +110,13 @@ export function importOpenApi(doc: any, datasource = 'app_api'): ImportResult {
       const status = expectedStatus(op.responses);
       entries[name] = {
         datasource,
+        area: areaOf(op, rawPath),
         description: typeof op.summary === 'string' ? op.summary : undefined,
         method: method.toUpperCase(),
         path: catalogPath,
         ...(params.length ? { params } : {}),
         ...(body ? { body } : {}),
+        ...(encoding ? { encoding } : {}),
         ...(status != null ? { expect: { status } } : {}),
       };
     }