@decocms/start 0.19.0

package/.cursor/skills/deco-server-functions-invoke/architecture.md

@@ -0,0 +1,166 @@
+# Three-Layer Invoke Architecture
+
+## Overview
+
+Server actions in Deco storefronts follow a three-layer pattern where commerce functions are pure, the framework provides the transport bridge, and the site has a generated file that wires them together.
+
+## Layer 1: Pure Functions (`@decocms/apps`)
+
+Commerce actions are regular async functions with no framework dependencies:
+
+```typescript
+// @decocms/apps/vtex/actions/checkout.ts
+export async function addItemsToCart(
+  orderFormId: string,
+  orderItems: Array<{ id: string; seller: string; quantity: number }>,
+): Promise<VtexFetchResult<OrderForm>> {
+  return vtexFetchWithCookies(
+    `/api/checkout/pub/orderForm/${orderFormId}/items?...`,
+    { method: "POST", body: JSON.stringify({ orderItems }) },
+  );
+}
+```
+
+These functions:
+- Use `vtexFetch`/`vtexFetchWithCookies` which call the VTEX API with `appKey`/`appToken`
+- Have no knowledge of how they'll be called (HTTP, RPC, direct)
+- Can be tested independently
+- Are the same for any framework (Fresh, TanStack, etc.)
+
+The `invoke.ts` in `@decocms/apps/vtex/` serves as the **declaration file** — it lists which functions should be exposed as server actions, their input/output types, and whether to unwrap `VtexFetchResult`.
+
+## Layer 2: Generator (`@decocms/start`)
+
+The `generate-invoke.ts` script bridges Layer 1 to TanStack Start:
+
+1. Parses `@decocms/apps/vtex/invoke.ts` with `ts-morph`
+2. Extracts each action: name, imports, input type, return type, call body, unwrap flag
+3. Generates `invoke.gen.ts` with top-level `createServerFn` declarations
+
+The generator lives in `@decocms/start/scripts/generate-invoke.ts` and is framework-aware — it knows about `createServerFn` and TanStack Start's compiler constraints.
+
+## Layer 3: Generated Bridge (Site)
+
+The site has `src/server/invoke.gen.ts` — auto-generated, committed or gitignored:
+
+```typescript
+// Auto-generated — do not edit
+import { createServerFn } from "@tanstack/react-start";
+import { addItemsToCart } from "@decocms/apps/vtex/actions/checkout";
+
+const $addItemsToCart = createServerFn({ method: "POST" })
+  .handler(async (ctx) => {
+    const result = await addItemsToCart(ctx.data.orderFormId, ctx.data.orderItems);
+    return unwrapResult(result);
+  });
+
+export const invoke = {
+  vtex: {
+    actions: {
+      addItemsToCart: $addItemsToCart,
+      // ...
+    },
+  },
+};
+```
+
+Components import from here:
+```typescript
+import { invoke } from "~/server/invoke.gen";
+```
+
+## Comparison: deco-cx/deco vs @decocms/start
+
+### deco-cx/deco (Fresh/Deno — Production)
+
+```
+Client
+  → invoke.vtex.actions.addItemsToCart(props)
+  → Proxy builds key: "vtex/actions/addItemsToCart"
+  → fetch("/live/invoke/vtex/actions/addItemsToCart", { body: props })
+  → Hono route /live/invoke/* → resolves handler from manifest
+  → addItemsToCart(props, ctx)
+  → vtexFetch → VTEX API
+```
+
+Key characteristics:
+- **Runtime resolution**: handler is found by key in the manifest at request time
+- **HTTP transport**: `fetch()` to `/live/invoke/{key}` — explicit HTTP call
+- **Proxy-based DX**: `proxy<Manifest>()` creates a JavaScript Proxy that builds the URL from property chain
+- **No compiler magic**: works with any bundler, no Vite plugin needed
+
+### @decocms/start (TanStack Start — New)
+
+```
+Client
+  → invoke.vtex.actions.addItemsToCart({ data: props })
+  → createClientRpc("base64id")
+  → POST /_server with serialized function ID + data
+  → TanStack Start deserializes, finds handler by ID
+  → addItemsToCart(props)
+  → vtexFetch → VTEX API
+```
+
+Key characteristics:
+- **Build-time resolution**: compiler assigns each function a unique ID at build time
+- **RPC transport**: `createClientRpc` handles serialization, TanStack Start routes to `/_server`
+- **Direct function call DX**: the generated function is directly callable, fully typed
+- **Compiler-dependent**: requires TanStack Start's Vite plugin to transform the code
+
+### Side-by-Side
+
+| Aspect | deco-cx/deco (Fresh) | @decocms/start (TanStack) |
+|--------|---------------------|--------------------------|
+| **Transport** | `fetch("/live/invoke/key")` | `createServerFn` → `/_server` RPC |
+| **Registry** | `manifest.gen.ts` (runtime) | `invoke.gen.ts` (build-time) |
+| **Client code** | `Proxy` object | Typed function stubs |
+| **Resolution** | Runtime (key → resolver) | Build-time (compiler extracts handler) |
+| **Config** | `runtime.ts` (3 lines) | `generate-invoke.ts` (build script) |
+| **Framework dep** | None (plain fetch) | TanStack Start compiler |
+| **Type safety** | Manifest types (generic) | Per-function types (specific) |
+
+### What Stayed the Same
+
+Both approaches share the core principle:
+1. **Commerce functions are pure** — same `addItemsToCart()` in both stacks
+2. **Client never calls VTEX directly** — always goes through the server
+3. **Credentials stay server-side** — `appKey`/`appToken` never reach the browser
+4. **Same invoke DX** — `invoke.vtex.actions.addItemsToCart({ data: {...} })`
+
+## Data Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                     BROWSER                              │
+│                                                          │
+│  useCart() → invoke.vtex.actions.addItemsToCart()        │
+│                    │                                     │
+│                    ▼                                     │
+│  createClientRpc("id") → POST /_server                  │
+│                    │         (same domain, no CORS)      │
+└────────────────────┼─────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│                   SERVER (Vite SSR / Worker)             │
+│                                                          │
+│  TanStack Start deserializes → finds $addItemsToCart     │
+│                    │                                     │
+│                    ▼                                     │
+│  addItemsToCart(orderFormId, orderItems)                 │
+│  (from @decocms/apps/vtex/actions/checkout.ts)          │
+│                    │                                     │
+│                    ▼                                     │
+│  vtexFetchWithCookies(                                  │
+│    "/api/checkout/pub/orderForm/{id}/items",             │
+│    { headers: { X-VTEX-API-AppKey, X-VTEX-API-AppToken }}│
+│  )                                                       │
+└────────────────────┼─────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│              VTEX API (server-to-server)                 │
+│  vtexcommercestable.com.br                              │
+│  ✓ Has credentials, ✓ No CORS, ✓ Full response          │
+└─────────────────────────────────────────────────────────┘
+```

package/.cursor/skills/deco-server-functions-invoke/generator.md

@@ -0,0 +1,122 @@
+# The generate-invoke.ts Script
+
+## Location
+
+`@decocms/start/scripts/generate-invoke.ts`
+
+## What It Does
+
+1. Finds `@decocms/apps/vtex/invoke.ts` (checks `node_modules/@decocms/apps` and `../apps-start`)
+2. Parses it with `ts-morph` to extract action definitions
+3. For each action, extracts: name, import source, imported function, input type, return type, unwrap flag, call body
+4. Generates `src/server/invoke.gen.ts` with:
+   - Top-level `createServerFn().handler()` declarations (one per action)
+   - An `invoke` object that re-exports them with proper types
+
+## Usage
+
+```bash
+# From site root
+npx tsx node_modules/@decocms/start/scripts/generate-invoke.ts
+
+# With custom output
+npx tsx node_modules/@decocms/start/scripts/generate-invoke.ts --out-file src/invoke.gen.ts
+
+# With custom apps location
+npx tsx node_modules/@decocms/start/scripts/generate-invoke.ts --apps-dir ../my-apps
+```
+
+## CLI Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--out-file` | `src/server/invoke.gen.ts` | Output file path |
+| `--apps-dir` | Auto-detected | Path to `@decocms/apps` root |
+
+## How It Parses invoke.ts
+
+The script navigates the AST:
+
+```
+invoke (VariableDeclaration)
+  └── { vtex: { actions: { ... } } } as const  (AsExpression → ObjectLiteral)
+        └── vtex (PropertyAssignment)
+              └── actions (PropertyAssignment)
+                    └── getOrCreateCart: createInvokeFn(...) as (...)
+                    └── addItemsToCart: createInvokeFn(...) as (...)
+                    └── ...
+```
+
+For each property in `actions`:
+1. Strips the `as Type` assertion to get the `createInvokeFn(...)` call
+2. Extracts the arrow function parameter type → `inputType`
+3. Extracts the arrow function body → `callBody`
+4. Checks for `{ unwrap: true }` in the second argument
+5. Resolves which imported function is called (matches against import map)
+6. Extracts the return type from the `as` assertion
+
+## Generated Output Structure
+
+```typescript
+// invoke.gen.ts
+
+import { createServerFn } from "@tanstack/react-start";
+import { addItemsToCart, ... } from "@decocms/apps/vtex/actions/checkout";
+import type { OrderForm } from "@decocms/apps/vtex/types";
+
+function unwrapResult<T>(result: unknown): T { ... }
+
+// Top-level — compiler can transform these
+const $addItemsToCart = createServerFn({ method: "POST" })
+  .handler(async (ctx: { data: { orderFormId: string; ... } }) => {
+    const result = await addItemsToCart(ctx.data.orderFormId, ctx.data.orderItems);
+    return unwrapResult(result);  // strips VtexFetchResult wrapper
+  });
+
+// Re-export with types
+export const invoke = {
+  vtex: {
+    actions: {
+      addItemsToCart: $addItemsToCart as (...) => Promise<OrderForm>,
+    },
+  },
+} as const;
+```
+
+## Adding New Actions
+
+1. Add the pure function to `@decocms/apps/vtex/actions/{module}.ts`
+2. Add it to `@decocms/apps/vtex/invoke.ts` using `createInvokeFn`
+3. Re-run `npm run generate:invoke` in the site
+4. The new action is automatically available in `invoke.vtex.actions.*`
+
+## unwrapResult
+
+VTEX checkout functions return `VtexFetchResult<T>` which wraps `{ data: T, setCookies: string[] }`. The `unwrap: true` flag causes the generated handler to extract `.data` before returning to the client:
+
+```typescript
+// Without unwrap:
+const result = await simulateCart(items, postalCode);
+return result;  // returns raw simulation response
+
+// With unwrap:
+const result = await getOrCreateCart(orderFormId);
+return unwrapResult(result);  // returns OrderForm, not { data: OrderForm, setCookies }
+```
+
+## Integration with Build Pipeline
+
+The script fits into the existing build pipeline alongside other generators:
+
+```json
+{
+  "scripts": {
+    "generate:blocks": "tsx .../generate-blocks.ts",
+    "generate:invoke": "tsx .../generate-invoke.ts",
+    "generate:schema": "tsx .../generate-schema.ts",
+    "build": "generate:blocks && generate:invoke && generate:schema && tsr generate && vite build"
+  }
+}
+```
+
+Order matters: `generate:invoke` should run before `generate:schema` (schema needs to see all imports), but after `generate:blocks` (blocks don't depend on invoke).

package/.cursor/skills/deco-server-functions-invoke/problem.md

@@ -0,0 +1,98 @@
+# The CORS Problem — Root Cause Analysis
+
+## Symptom
+
+When clicking "Add to Cart" or "Compra Rápida" in a Deco TanStack Start storefront running on `localhost:5173`, the browser makes a direct request to `https://{account}.vtexcommercestable.com.br/api/checkout/pub/orderForm/...`, which fails with a CORS error because the VTEX API doesn't allow cross-origin requests from `localhost`.
+
+## Expected Behavior
+
+The `invoke.vtex.actions.addItemsToCart()` call should go through TanStack Start's server function mechanism:
+1. Client calls the function
+2. TanStack Start serializes the call and POSTs to `/_server` (same domain)
+3. Server deserializes, runs the handler (which calls VTEX API server-to-server)
+4. Server returns the result to the client
+
+## Root Cause: Compiler Fast Path
+
+TanStack Start uses a Vite plugin (`tanstack-start-core::server-fn`) that transforms `createServerFn().handler()` calls. On the **client bundle**, it replaces the handler body with a `createClientRpc()` stub that makes an HTTP call to `/_server`.
+
+The compiler has two code paths:
+
+### Fast Path (ServerFn only)
+When a file only contains `ServerFn` kind (detected by `/\bcreateServerFn\b|\.\s*handler\s*\(/`), the compiler uses a fast path that **only scans top-level statements**:
+
+```typescript
+// compiler.ts — fast path
+function areAllKindsTopLevelOnly(kinds: Set<LookupKind>): boolean {
+  return kinds.size === 1 && kinds.has('ServerFn')
+}
+
+// Only visits top-level VariableDeclarators
+// VariableDeclarator -> VariableDeclaration -> Program
+```
+
+### Normal Path
+For files with multiple kinds (Middleware, IsomorphicFn, etc.), it does a full AST traversal.
+
+## Why createInvokeFn Fails
+
+The original `@decocms/start/sdk/createInvoke.ts`:
+
+```typescript
+import { createServerFn } from "@tanstack/react-start";
+
+export function createInvokeFn(action, opts) {
+  return createServerFn({ method: "POST" }).handler(async (ctx) => {
+    const result = await action(ctx.data);
+    // ...
+  });
+}
+```
+
+The file contains `createServerFn` → triggers `ServerFn` detection → **fast path activates** → only scans top-level → `.handler()` is inside `createInvokeFn` function body → **skipped**.
+
+Result: the client bundle receives the raw code, `createServerFn` returns a function that calls `vtexFetch` directly in the browser.
+
+## Verification
+
+You can verify the transformation by fetching the module from Vite dev server:
+
+```bash
+# BROKEN — raw code, no transformation
+curl "http://localhost:5173/@fs/.../createInvoke.ts"
+# Shows: createServerFn({ method: "POST" }).handler(async (ctx) => { ... })
+
+# FIXED — compiler transformed to RPC
+curl "http://localhost:5174/src/server/invoke.gen.ts"  
+# Shows: createServerFn({ method: "POST" }).handler(createClientRpc("eyJ..."))
+```
+
+The `createClientRpc("base64id")` is the RPC stub — it serializes the call and POSTs to `/_server`.
+
+## The Fix
+
+Each `createServerFn().handler()` must be a **top-level const declaration**:
+
+```typescript
+// WORKS — top-level const
+const $addItemsToCart = createServerFn({ method: "POST" })
+  .handler(async (ctx) => {
+    return await addItemsToCart(ctx.data.orderFormId, ctx.data.orderItems);
+  });
+
+// DOES NOT WORK — inside a function
+function createInvokeFn(action) {
+  return createServerFn({ method: "POST" })
+    .handler(async (ctx) => { ... });  // ← skipped by fast path
+}
+```
+
+## Compiler Source Reference
+
+The relevant code is in `@tanstack/start-plugin-core/src/start-compiler-plugin/`:
+
+- `compiler.ts:88-95` — `KindDetectionPatterns.ServerFn = /\bcreateServerFn\b|\.\s*handler\s*\(/`
+- `compiler.ts:226-228` — `areAllKindsTopLevelOnly` returns true for ServerFn-only files
+- `compiler.ts:660-663` — `canUseFastPath` check
+- `compiler.ts:715-717` — early exit when no top-level candidates found
+- `plugin.ts:239-247` — transform filter: `id.include = /\.[cm]?[tj]sx?($|\?)/`, `code.include` from `KindDetectionPatterns`

package/.cursor/skills/deco-server-functions-invoke/troubleshooting.md

@@ -0,0 +1,110 @@
+# Troubleshooting
+
+## CORS Error on Add to Cart / Checkout
+
+**Symptom**: Browser console shows CORS error when calling VTEX API directly.
+
+**Check**: Open browser DevTools → Network tab. If you see requests going to `vtexcommercestable.com.br` instead of `/_server`, the server functions aren't transformed.
+
+**Fix**: 
+1. Verify `invoke.gen.ts` exists in `src/server/`
+2. Verify imports point to `~/server/invoke.gen`, not `@decocms/apps/vtex/invoke`
+3. Re-run `npm run generate:invoke`
+4. Restart the dev server (Vite caches transforms)
+
+## Verify Transformation
+
+Fetch the generated file from Vite to see if the compiler transformed it:
+
+```bash
+# Replace port with your dev server port
+curl "http://localhost:5173/src/server/invoke.gen.ts" | head -20
+```
+
+**Good** — you should see `createClientRpc`:
+```js
+const $addItemsToCart = createServerFn({ method: "POST" })
+  .handler(createClientRpc("eyJmaWxlIjoi..."));
+```
+
+**Bad** — you see the raw handler code:
+```js
+const $addItemsToCart = createServerFn({ method: "POST" })
+  .handler(async (ctx) => {
+    const result = await addItemsToCart(ctx.data.orderFormId, ...);
+```
+
+If you see the raw code, the compiler didn't transform it. Possible causes:
+- The file is not in `src/` (must be inside the site's source directory)
+- The Vite plugin is not loaded (check `vite.config.ts` has `tanstackStart()`)
+- The `createServerFn` is not at top-level (check the generated code)
+
+## Server Logs Don't Show VTEX Calls
+
+**Symptom**: When clicking add to cart, no `[vtex] POST ...` lines appear in the terminal.
+
+**Cause**: The calls are going directly from the browser, not through the server.
+
+**Fix**: Same as CORS fix above — ensure `invoke.gen.ts` is being used.
+
+## "invoke.vtex.actions.X is not a function"
+
+**Cause**: The generated file doesn't include that action.
+
+**Fix**:
+1. Check `@decocms/apps/vtex/invoke.ts` — is the action declared there?
+2. Re-run `npm run generate:invoke`
+3. Check the generated `invoke.gen.ts` — is the action present?
+
+## Generator Fails: "Could not find @decocms/apps"
+
+**Cause**: The script can't locate the apps package.
+
+**Fix**: Use `--apps-dir`:
+```bash
+npx tsx .../generate-invoke.ts --apps-dir ../apps-start
+# or
+npx tsx .../generate-invoke.ts --apps-dir node_modules/@decocms/apps
+```
+
+## Generator Fails: "Could not find 'export const invoke'"
+
+**Cause**: The `invoke.ts` in `@decocms/apps` changed structure.
+
+**Fix**: The generator expects:
+```typescript
+export const invoke = {
+  vtex: {
+    actions: {
+      actionName: createInvokeFn(...) as ...,
+    },
+  },
+} as const;
+```
+
+If the structure changed, update `generate-invoke.ts` to match.
+
+## New Action Not Available After Re-generating
+
+**Checklist**:
+1. Added to `@decocms/apps/vtex/invoke.ts`? 
+2. Ran `npm run generate:invoke`?
+3. Check `src/server/invoke.gen.ts` — is the new action in the file?
+4. Restarted dev server? (HMR may not pick up `.gen.ts` changes)
+
+## TypeScript Errors in invoke.gen.ts
+
+The generated file uses `as unknown as` casts for typing. If you see TS errors:
+- They're usually harmless in the generated file
+- The consumer types (what components see) are correct
+- If a type is wrong, fix it in `@decocms/apps/vtex/invoke.ts` and re-generate
+
+## Performance: Are Server Functions Slow?
+
+Each `invoke.*` call from the client makes one HTTP request to `/_server`. In dev mode, this goes to the local Vite server. In production (Cloudflare Workers), it's handled within the same worker — effectively zero network latency since it's an in-process function call during SSR, and a single HTTP round-trip during client-side navigation.
+
+The overhead vs. direct VTEX calls: one extra hop through the worker, but this is necessary for:
+- Hiding VTEX credentials from the browser
+- Avoiding CORS
+- Allowing server-side cookie propagation
+- Enabling future features like response caching