@sungen/driver-api 3.1.2-beta.123 → 3.1.2-beta.125

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-api",
-  "version": "3.1.2-beta.123",
+  "version": "3.1.2-beta.125",
   "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.123",
+    "@sun-asterisk/sungen": "3.1.2-beta.125",
     "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;
+  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 };
@@ -89,6 +90,7 @@ 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,

package/src/api-harness.ts

@@ -22,6 +22,7 @@ interface ApiScenario {
   queryRefs?: string[];
   casesDataset?: string;
   stepsText?: string; // lowercase steps text
+  manual?: boolean;   // @manual — not automated, so excluded from automation businessDepth
 }
 
 interface ApiGateInput {
@@ -112,7 +113,10 @@ export function apiGateProvider(input: ApiGateInput): { gate: GateResult; depth:
   // 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 ?? '');
-  const depthRequired = apiScenarios.filter((s) => (s.apiRefs ?? []).some(isMutating) && !errorLike(s));
+  // 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

package/src/api-repair.ts

@@ -21,6 +21,8 @@ export const apiRepair: RepairProvider = {
       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,

package/src/index.ts

@@ -85,7 +85,9 @@ function apiPreconditionCodegen(input: { tags: string[]; screenName: string; cwd
     // 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} }`;
+    // 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
@@ -157,6 +159,16 @@ const apiViewpointSensor: Sensor<GateInput> = {
       }
     }
 
+    // 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) {

package/src/openapi-import.ts

@@ -14,6 +14,7 @@ export interface ImportedApiEntry {
   path: string;
   params?: string[];
   body?: Record<string, string>;
+  encoding?: 'form' | 'multipart'; // set when the requestBody is form/multipart (json omitted = default)
   expect?: { status: number };
 }
 
@@ -52,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 {
@@ -89,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)
@@ -107,6 +116,7 @@ export function importOpenApi(doc: any, datasource = 'app_api'): ImportResult {
         path: catalogPath,
         ...(params.length ? { params } : {}),
         ...(body ? { body } : {}),
+        ...(encoding ? { encoding } : {}),
         ...(status != null ? { expect: { status } } : {}),
       };
     }