@enricai/barnacle 1.6.2 → 1.6.4

package/dist/scripts/recon-generate.js

@@ -24,11 +24,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveStepPayloadField = resolveStepPayloadField;
 exports.inferZodSchemaFromSamples = inferZodSchemaFromSamples;
 exports.selectPayloadAction = selectPayloadAction;
+exports.selectReturnAction = selectReturnAction;
+exports.selectEffectiveResponseBody = selectEffectiveResponseBody;
 exports.extractActionSequence = extractActionSequence;
 exports.detectFormSchemaFieldNames = detectFormSchemaFieldNames;
 exports.walkSetCookiePairs = walkSetCookiePairs;
 exports.indexStateValues = indexStateValues;
 exports.compileActionSteps = compileActionSteps;
+exports.collectHeaderBindings = collectHeaderBindings;
 exports.loadQuestionPromptKeywords = loadQuestionPromptKeywords;
 exports.emitMultiStepExecuteHttp = emitMultiStepExecuteHttp;
 exports.emitContractTs = emitContractTs;
@@ -270,6 +273,31 @@ function isVoidResponse(body) {
         return body.length === 0;
     return Object.keys(body).length === 0;
 }
+/**
+ * Finds actions whose endpoint was re-hit with a varying, non-void body —
+ * the signature of a search/inventory endpoint the page queries repeatedly,
+ * as opposed to an endpoint that merely fired once or repeated an identical
+ * (retry) or void (chatter/beacon) call. Shared by `selectPayloadAction` and
+ * `selectReturnAction`, which each pick a different fallback when nothing
+ * was re-queried.
+ */
+function findRequeriedActions(steps) {
+    const bodiesByEndpoint = new Map();
+    for (const step of steps) {
+        const key = endpointKey(step.capture.url);
+        const bodies = bodiesByEndpoint.get(key) ?? new Set();
+        bodies.add(step.capture.requestPostData ?? "");
+        bodiesByEndpoint.set(key, bodies);
+    }
+    return steps.filter((step) => {
+        const bodies = bodiesByEndpoint.get(endpointKey(step.capture.url));
+        if (!bodies || bodies.size < 2)
+            return false;
+        // An endpoint re-hit with varying bodies but nothing to show for it is
+        // chatter — client-side error reporting, beacons — not the flow's subject.
+        return !isVoidResponse(step.capture.responseBody);
+    });
+}
 /**
  * Picks the action whose request body should define the payload schema.
  *
@@ -291,23 +319,40 @@ function selectPayloadAction(steps) {
     const first = steps[0];
     if (!first)
         return null;
-    const bodiesByEndpoint = new Map();
-    for (const step of steps) {
-        const key = endpointKey(step.capture.url);
-        const bodies = bodiesByEndpoint.get(key) ?? new Set();
-        bodies.add(step.capture.requestPostData ?? "");
-        bodiesByEndpoint.set(key, bodies);
-    }
-    const requeried = steps.filter((step) => {
-        const bodies = bodiesByEndpoint.get(endpointKey(step.capture.url));
-        if (!bodies || bodies.size < 2)
-            return false;
-        // An endpoint re-hit with varying bodies but nothing to show for it is
-        // chatter — client-side error reporting, beacons — not the flow's subject.
-        return !isVoidResponse(step.capture.responseBody);
-    });
+    const requeried = findRequeriedActions(steps);
     return requeried[0] ?? first;
 }
+/**
+ * Picks the action whose response body `executeHttp` should return.
+ *
+ * Defaults to the last action, which is right for a transactional/submission
+ * flow: the final call is the terminal success signal the caller wants back.
+ * It is wrong when the flow is a read/search whose last call happens to be an
+ * incidental drill-down (e.g. previewing one result) rather than the search
+ * result itself — the same re-queried-endpoint signal `selectPayloadAction`
+ * uses to find the flow's subject applies here: an endpoint hit repeatedly
+ * with varying, non-void bodies is what the flow is about, and its most
+ * recent response is the freshest instance of that answer.
+ */
+function selectReturnAction(steps) {
+    const last = steps[steps.length - 1] ?? null;
+    if (!last)
+        return null;
+    const requeried = findRequeriedActions(steps);
+    return requeried[requeried.length - 1] ?? last;
+}
+/**
+ * Picks the response body used to infer the emitted contract's response
+ * shape. MUST target the same call `selectReturnAction` returns — a
+ * submission flow's `executeHttp` and its inferred type/schema have to agree
+ * on which call they describe, or the emitted type disagrees with the value
+ * actually returned. Falls back to the replay body for single-endpoint sites.
+ */
+function selectEffectiveResponseBody(isSubmissionFlow, actionSteps, replayResponseBody) {
+    if (!isSubmissionFlow)
+        return replayResponseBody;
+    return selectReturnAction(actionSteps)?.capture.responseBody ?? replayResponseBody;
+}
 function deriveBaseUrl(captures) {
     for (const c of captures) {
         try {
@@ -1365,21 +1410,36 @@ function compileActionSteps(actions, stateIndex) {
  * step order — this is what `emitContractTs` renders as `createHttpClient`'s
  * `bind` option so the generated `executeHttp` actually forwards a value like
  * disneycruise's `Set-Cookie: __pa=<jwt>` mint to the stateful call that 401s
- * without it. Deduped by `targetHeader`: `HttpResponseBinding` (http-client.ts)
- * is one binding per target header, so if two steps somehow produced the same
- * target the earliest wins.
+ * without it. Deduped by `targetHeader.toLowerCase()` + `cookieName` (HTTP
+ * header names are case-insensitive, and compileActionSteps derives
+ * `targetHeader` verbatim from observed request-header casing, so the same
+ * logical target can show up as e.g. `Cookie` on one step and `cookie` on
+ * another): the `Cookie` request header carries many cookies by design, so
+ * every distinct cookie-origin produce targeting it must survive (the
+ * runtime accumulates them into one `Cookie` header per binding — see
+ * http-client.ts); only a produce that re-mints the SAME cookie on a later
+ * step collapses to its earliest occurrence. Non-cookie targets (e.g.
+ * `X-Conversation-Id`) still keep first-wins, since `HttpResponseBinding` is
+ * one binding per target header there and two steps producing the same
+ * non-cookie target (even under differing casing) would otherwise race with
+ * no defined winner.
+ *
+ * Exported for unit testing (as `walkSetCookiePairs` is) — lets tests exercise
+ * the produce → bind collection step directly against synthetic ActionStep
+ * sequences.
  */
 function collectHeaderBindings(actionSteps) {
-    const byTarget = new Map();
+    const byKey = new Map();
     for (const step of actionSteps) {
         for (const p of step.produces) {
             if (p.kind !== "header")
                 continue;
-            if (!byTarget.has(p.targetHeader))
-                byTarget.set(p.targetHeader, p);
+            const key = `${p.targetHeader.toLowerCase()}\0${p.cookieName ?? ""}`;
+            if (!byKey.has(key))
+                byKey.set(key, p);
         }
     }
-    return [...byTarget.values()];
+    return [...byKey.values()];
 }
 /**
  * Replaces occurrences of state values in `template` with `${varName}`
@@ -1859,7 +1919,14 @@ function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap
                 .join(", ")} },`
             : "";
         const bodyArg = bodyTemplate ? `body: \`${bodyTemplate}\`,` : "";
-        rendered.push({ url, method: cap.method, headersExpr, bodyArg });
+        // G2: each call gets its own schema, inferred from this step's captured
+        // response — the client-level schema (z.unknown() for multi-step flows,
+        // see emitContractTs) stays the plugin's caller-facing contract, not what
+        // validates any individual call. Without this override, HttpRequestInit.schema
+        // would default to the client's z.unknown() and narrowing the caller-facing
+        // contract would enforce that narrowed shape on every call in the chain.
+        const schemaExpr = inferZodSchema(cap.responseBody);
+        rendered.push({ url, method: cap.method, headersExpr, bodyArg, schemaExpr });
     }
     // Identifier scan against the rendered text — captures `${foo}`, `${foo.bar}`,
     // etc. The first segment (anchored at `${`) is the binding's name. Closed
@@ -1879,9 +1946,11 @@ function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap
             }
         }
     }
-    // The last step's var is also referenced by the closing `return { data }`.
-    if (actions.length > 0)
-        referencedNames.add(actions[actions.length - 1].varName);
+    // The relevance-selected step's var is also referenced by the closing
+    // `return { data }` — see selectReturnAction.
+    const returnAction = selectReturnAction(actions);
+    if (returnAction)
+        referencedNames.add(returnAction.varName);
     // Base64 Content overrides reference variables inside function calls
     // (e.g. buildBase64Content(payload, questionnaireId, ...)) that the
     // ${name} regex above doesn't capture. Add them explicitly.
@@ -1981,6 +2050,7 @@ function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap
             if (joined !== "") {
                 lines.push(`      ${joined}`);
             }
+            lines.push(`      schema: ${r.schemaExpr},`);
             if (needsBinding) {
                 lines.push(`    })) as Record<string, unknown>;`);
             }
@@ -2010,8 +2080,8 @@ function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap
         }
         lines.push("");
     }
-    const lastVar = actions.length > 0 ? actions[actions.length - 1].varName : "undefined";
-    lines.push(`    return { data: ${lastVar} };`);
+    const returnVar = returnAction ? returnAction.varName : "undefined";
+    lines.push(`    return { data: ${returnVar} };`);
     return lines.join("\n");
 }
 function summariseResponseShape(value) {
@@ -2049,16 +2119,25 @@ function bindOptionLiteral(headerBindings) {
  * unit tests can drive the emitter directly without spawning the CLI. */
 function emitContractTs(opts) {
     const { siteId, pascal, baseUrl, baseHeaders, minTime, safeRps, responseBody, gql, gqlQuery, endpointPath, auxFiles, multiStepBody, inputBody, hasMultipartStep = false, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, payloadFieldNames, base64ContentHelper = "", headerBindings = [], } = opts;
-    // Multi-step plugins thread responses through many different shapes that a
-    // single Zod schema can't cover — use z.unknown() so each per-step access
-    // compiles cleanly. Single-endpoint plugins keep the inferred schema.
+    // This is the CLIENT-level schema — createHttpClient's default, and the
+    // plugin's caller-facing contract (what executeHttp's return value promises
+    // its own caller). It does NOT validate any individual call in a multi-step
+    // flow: emitMultiStepExecuteHttp threads a per-call `schema:` override
+    // (inferred from that step's own capture) onto every httpClient(...)
+    // invocation, so heterogeneous per-call shapes are each checked against
+    // their own inferred schema regardless of what this client-level schema is.
     //
-    // This is deliberate, not an unfinished schema: a submission flow's terminal
-    // shape is the plugin's OWN contract with its caller (e.g. { verified: boolean }),
-    // a field that appears in zero captured responses. Inferring a schema from the
-    // captures would emit the wrong shape with false confidence. z.unknown() plus
-    // the generated `[ ] Narrow ResponseSchema` checklist item is the intended
-    // hand-off to the plugin author, who alone knows that contract.
+    // For multi-step flows this stays z.unknown(), not an unfinished schema: a
+    // submission flow's terminal shape is the plugin's OWN contract with its
+    // caller (e.g. { verified: boolean }), a field that appears in zero
+    // captured responses. Inferring a schema from the captures would emit the
+    // wrong shape with false confidence. z.unknown() plus the generated
+    // `[ ] Narrow ResponseSchema` checklist item is the intended hand-off to
+    // the plugin author, who alone knows that contract — narrowing it only
+    // changes what executeHttp promises its caller, and is now safe to do
+    // without affecting per-call validation. Single-endpoint plugins keep the
+    // inferred schema, since there both roles (client default and sole call)
+    // coincide.
     const responseSchemaExpr = multiStepBody ? `z.unknown()` : inferZodSchema(responseBody);
     // Multi-step flows that include a multipart upload need the binary asset
     // on the payload. Add Resume/ResumeContentType/ResumeFilename as required
@@ -2235,12 +2314,20 @@ const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottlenec
     const queryChecklistLine = gql
         ? `\n *   [ ] Trim UI-only fields from ${pascal.toUpperCase()}_QUERY (keep only fields you need)`
         : "";
+    // Multi-step flows validate each call against its own per-call inferred
+    // schema (emitMultiStepExecuteHttp) — narrowing ResponseSchema only changes
+    // what executeHttp promises ITS OWN caller, never a per-call validator, so
+    // the checklist item must say that explicitly. Single-endpoint plugins have
+    // exactly one call, so the client schema and that call's validator are the
+    // same schema and the shorter wording stays accurate.
+    const narrowSchemaChecklistLine = multiStepBody
+        ? `\n *   [ ] Narrow ${pascal}ResponseSchema to match what executeHttp should promise ITS CALLER — this is the plugin's own return-value contract, not a per-call validator (each call in the flow is already checked against its own inferred schema)`
+        : `\n *   [ ] Narrow ${pascal}ResponseSchema to match the real response shape`;
     const camel = siteId.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
     return `/**
  * Generated by recon-generate.ts — review before shipping.
  *
- * Checklist:${queryChecklistLine}
- *   [ ] Narrow ${pascal}ResponseSchema to match the real response shape
+ * Checklist:${queryChecklistLine}${narrowSchemaChecklistLine}
  *   [ ] Adjust ${pascal}PayloadSchema to your actual request parameters
  *   [ ] Verify BASE_HEADERS — remove any that aren't load-bearing
  *   [ ] Out-of-tree: \`pnpm add bottleneck zod\` — this file imports both
@@ -2970,12 +3057,9 @@ async function main() {
         : multiStepBody;
     const hasMultipartStep = actionSteps.some((s) => s.isMultipart);
     const headerBindings = collectHeaderBindings(actionSteps);
-    // For submission flows the final action's response body is the most useful
-    // shape inference target (it's the terminal success signal). Fall back to
-    // the replay body for single-endpoint sites.
-    const effectiveResponseBody = isSubmissionFlow
-        ? (actionSteps[actionSteps.length - 1].capture.responseBody ?? responseBody)
-        : responseBody;
+    // Shape inference targets the SAME call executeHttp returns — see
+    // selectEffectiveResponseBody — so the two surfaces can't describe different calls.
+    const effectiveResponseBody = selectEffectiveResponseBody(isSubmissionFlow, actionSteps, responseBody);
     logger.info(`generating plugin for ${siteId} (${gql ? "GraphQL" : isSubmissionFlow ? `submission flow, ${actionSteps.length} steps` : "single-endpoint REST"}, baseUrl: ${baseUrl})`);
     if (emit === "config") {
         (0, node_fs_1.mkdirSync)(outDir, { recursive: true });