@decocms/start 5.4.2 → 6.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "5.4.2",
+  "version": "6.0.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/scripts/generate-invoke.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Integration test for scripts/generate-invoke.ts.
+ *
+ * The generator scans a `vtex/invoke.ts` file from @decocms/apps and emits a
+ * site-local `src/server/invoke.gen.ts` with top-level `createServerFn`
+ * declarations. The piece we care most about locking is the Set-Cookie
+ * bridge: every handler must call `forwardResponseCookies()` after the
+ * action awaits, so VTEX-set cookies captured by `vtexFetchWithCookies`
+ * reach the browser via TanStack Start's HTTP response. Without this,
+ * `checkout.vtex.com` never reaches the browser, the storefront's
+ * mini-cart and VTEX's server-side orderForm drift apart, and /checkout
+ * loads with an empty cart.
+ *
+ * We exercise the generator end-to-end against a minimal fixture
+ * `invoke.ts` rather than unit-test internal helpers — the failure
+ * mode we want to prevent (a missing `forwardResponseCookies()` call
+ * in the emit string) only shows up in the produced source text.
+ */
+
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+const GENERATOR = path.resolve(__dirname, "generate-invoke.ts");
+
+const FIXTURE_INVOKE_TS = `\
+import { createInvokeFn } from "@decocms/start/sdk/createInvoke";
+import { getOrCreateCart, simulateCart } from "./actions/checkout";
+import type { OrderForm } from "./types";
+
+export const invoke = {
+	vtex: {
+		actions: {
+			getOrCreateCart: createInvokeFn(
+				(data: { orderFormId?: string }) => getOrCreateCart(data),
+			) as unknown as (ctx: { data: { orderFormId?: string } }) => Promise<OrderForm>,
+
+			simulateCart: createInvokeFn(
+				(data: { postalCode: string }) => simulateCart(data),
+			),
+		},
+	},
+} as const;
+`;
+
+// Minimal stubs the generator's import-resolution doesn't *execute* but
+// ts-morph parses these to populate the importMap. We only need names to
+// resolve.
+const FIXTURE_ACTIONS_CHECKOUT_TS = `\
+export async function getOrCreateCart(_data: any): Promise<any> { return null; }
+export async function simulateCart(_data: any): Promise<any> { return null; }
+`;
+const FIXTURE_TYPES_TS = `export type OrderForm = unknown;\n`;
+
+describe("generate-invoke.ts — output shape", () => {
+  let appsDir: string;
+  let siteDir: string;
+  let outFile: string;
+
+  beforeEach(() => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "gen-invoke-"));
+    appsDir = path.join(tmp, "apps");
+    siteDir = path.join(tmp, "site");
+    fs.mkdirSync(path.join(appsDir, "vtex", "actions"), { recursive: true });
+    fs.mkdirSync(path.join(siteDir, "src", "server"), { recursive: true });
+    fs.writeFileSync(path.join(appsDir, "vtex", "invoke.ts"), FIXTURE_INVOKE_TS);
+    fs.writeFileSync(
+      path.join(appsDir, "vtex", "actions", "checkout.ts"),
+      FIXTURE_ACTIONS_CHECKOUT_TS,
+    );
+    fs.writeFileSync(path.join(appsDir, "vtex", "types.ts"), FIXTURE_TYPES_TS);
+    outFile = path.join(siteDir, "src", "server", "invoke.gen.ts");
+  });
+
+  afterEach(() => {
+    // Best-effort cleanup; tmp dirs leak otherwise.
+    try {
+      fs.rmSync(path.dirname(appsDir), { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  function runGenerator(): { stdout: string; stderr: string; status: number | null } {
+    const result = spawnSync(
+      "npx",
+      [
+        "tsx",
+        GENERATOR,
+        "--apps-dir",
+        appsDir,
+        "--out-file",
+        outFile,
+      ],
+      {
+        cwd: siteDir,
+        encoding: "utf8",
+      },
+    );
+    return {
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+      status: result.status,
+    };
+  }
+
+  it("imports the framework helpers needed for Set-Cookie propagation", () => {
+    const { status } = runGenerator();
+    expect(status).toBe(0);
+
+    const out = fs.readFileSync(outFile, "utf8");
+    // Both imports must be present — without them, forwardResponseCookies
+    // doesn't compile in the site, and the regression we're fixing
+    // resurfaces silently when someone deletes one of them.
+    expect(out).toContain('from "@tanstack/react-start/server"');
+    expect(out).toMatch(/getResponseHeaders\s*,?\s*\n?\s*setResponseHeader/);
+    expect(out).toContain('import { RequestContext } from "@decocms/start/sdk/requestContext"');
+  });
+
+  it("emits the forwardResponseCookies helper exactly once", () => {
+    runGenerator();
+    const out = fs.readFileSync(outFile, "utf8");
+    // Match the declaration, not call sites. There's only one helper.
+    const declMatches = out.match(/function forwardResponseCookies\(\)/g);
+    expect(declMatches).toHaveLength(1);
+
+    // The helper must read from RequestContext.responseHeaders and call
+    // setResponseHeader. Locking the bridge ends-to-ends.
+    expect(out).toContain("RequestContext.current");
+    expect(out).toContain("ctx.responseHeaders.getSetCookie");
+    expect(out).toContain('setResponseHeader("set-cookie"');
+  });
+
+  it("calls forwardResponseCookies() inside every generated handler", () => {
+    runGenerator();
+    const out = fs.readFileSync(outFile, "utf8");
+
+    // Each .handler(async ({ data }) ...) block produced by the
+    // generator must contain a `forwardResponseCookies()` call. We
+    // count handlers vs. call sites — excluding the declaration site
+    // (`function forwardResponseCookies()`), which also matches the
+    // bare `forwardResponseCookies()` token.
+    const handlerCount = (out.match(/\.handler\(async \(\{ data \}\)/g) ?? []).length;
+    const allOccurrences = (out.match(/\bforwardResponseCookies\(\)/g) ?? []).length;
+    const declSites = (out.match(/function\s+forwardResponseCookies\(\)/g) ?? []).length;
+    const callSites = allOccurrences - declSites;
+
+    expect(handlerCount).toBe(2);
+    expect(declSites).toBe(1);
+    expect(callSites).toBe(2);
+  });
+
+  it("calls forwardResponseCookies AFTER the action awaits (so RequestContext is populated)", () => {
+    runGenerator();
+    const out = fs.readFileSync(outFile, "utf8");
+
+    // The action must complete (await result) before we read the
+    // captured Set-Cookies — otherwise we'd forward an empty set
+    // every time. Verifying ordering via regex is brittle but the
+    // surface is small enough.
+    const pattern =
+      /const result = await \w+\(data\);\s+forwardResponseCookies\(\);\s+return (?:unwrapResult\(result\)|result);/g;
+    const orderedCalls = out.match(pattern) ?? [];
+    expect(orderedCalls.length).toBe(2);
+  });
+});

package/scripts/generate-invoke.ts

@@ -317,6 +317,17 @@ for (const [source, types] of typeImports) {
   }
 }
 
+// Imports required by the forwardResponseCookies bridge. They live next
+// to the framework's RequestContext (where vtexFetchWithCookies stashes
+// inbound Set-Cookie headers) and TanStack Start's response-header API
+// (where we copy them onto the actual HTTP response).
+out += `import {
+  getResponseHeaders,
+  setResponseHeader,
+} from "@tanstack/react-start/server";
+import { RequestContext } from "@decocms/start/sdk/requestContext";
+`;
+
 out += `
 function unwrapResult<T>(result: unknown): T {
   if (result && typeof result === "object" && "data" in result) {
@@ -325,6 +336,36 @@ function unwrapResult<T>(result: unknown): T {
   return result as T;
 }
 
+/**
+ * Forward Set-Cookie headers captured in RequestContext.responseHeaders
+ * (by vtexFetchWithCookies) into TanStack Start's HTTP response.
+ *
+ * Without this bridge, HttpOnly cookies like \`checkout.vtex.com\` and
+ * \`CheckoutOrderFormOwnership\` that VTEX returns on cart-action responses
+ * stay trapped inside the AsyncLocalStorage-backed RequestContext and
+ * never reach the browser. The storefront's mini-cart drifts away from
+ * VTEX's server-side orderForm, and the user lands on /checkout with an
+ * empty cart.
+ *
+ * Cheap no-op when no Set-Cookie was captured (e.g. read-only actions),
+ * so every handler can call it unconditionally without branching on
+ * whether the underlying action uses vtexFetchWithCookies.
+ */
+function forwardResponseCookies(): void {
+  const ctx = RequestContext.current;
+  if (!ctx) return;
+  const captured =
+    typeof ctx.responseHeaders.getSetCookie === "function"
+      ? ctx.responseHeaders.getSetCookie()
+      : [];
+  if (captured.length === 0) return;
+  const existing =
+    typeof getResponseHeaders().getSetCookie === "function"
+      ? getResponseHeaders().getSetCookie()
+      : [];
+  setResponseHeader("set-cookie", [...existing, ...captured]);
+}
+
 // ---------------------------------------------------------------------------
 // Top-level server function declarations
 // ---------------------------------------------------------------------------
@@ -337,18 +378,30 @@ for (const action of actions) {
     // All @decocms/apps action functions take a single props object.
     // Pass the validated `data` object directly — never destructure into
     // positional arguments, which breaks when function signatures change.
+    //
+    // forwardResponseCookies() runs AFTER the action awaits, so any
+    // Set-Cookie that vtexFetchWithCookies captured onto
+    // RequestContext.responseHeaders gets promoted to the actual HTTP
+    // response. Safe no-op when the action didn't touch
+    // responseHeaders (e.g. masterData reads), so it's applied
+    // unconditionally — the alternative (a static allow-list of
+    // cookie-bearing actions) silently misses any new actions that
+    // start propagating cookies.
     if (action.unwrap) {
       out += `\nconst ${varName} = createServerFn({ method: "POST" })
   .inputValidator((data: ${action.inputType}) => data)
   .handler(async ({ data }): Promise<any> => {
     const result = await ${action.importedFn}(data);
+    forwardResponseCookies();
     return unwrapResult(result);
   });\n`;
     } else {
       out += `\nconst ${varName} = createServerFn({ method: "POST" })
   .inputValidator((data: ${action.inputType}) => data)
   .handler(async ({ data }): Promise<any> => {
-    return ${action.importedFn}(data);
+    const result = await ${action.importedFn}(data);
+    forwardResponseCookies();
+    return result;
   });\n`;
     }
   } else {