@decocms/start 0.19.0

package/.cursor/skills/deco-apps-architecture/new-app-guide.md

@@ -0,0 +1,268 @@
+# Creating a New Deco App
+
+## Quick Start
+
+```bash
+deno task new
+# Select: APP or MCP
+# Enter name: my-integration (kebab-case)
+# Template is cloned, deco.ts updated, manifests generated
+```
+
+## Manual Setup
+
+1. Create the directory: `mkdir my-integration`
+2. Add to `deco.ts`:
+   ```typescript
+   app("my-integration"),
+   ```
+3. Create the minimum files:
+
+### `client.ts` — API Interface
+
+```typescript
+export interface MyClient {
+  "GET /users/:id": {
+    response: User;
+    searchParams: { fields?: string };
+  };
+  "POST /users": {
+    response: User;
+    body: CreateUserInput;
+  };
+  "GET /products": {
+    response: { items: Product[]; total: number };
+    searchParams: {
+      page?: number;
+      limit?: number;
+      q?: string;
+    };
+  };
+  "DELETE /users/:id": {
+    response: void;
+  };
+}
+```
+
+**Key rules:**
+- Key format: `"VERB /path/:param/:optional?"` 
+- `:param` = required URL param
+- `:param?` = optional URL param
+- `*` or `*name` = wildcard
+- `response` = return type of `.json()`
+- `body` = POST/PUT/PATCH body (auto-JSON-serialized)
+- `searchParams` = query string parameters
+
+### `mod.ts` — App Factory
+
+```typescript
+import { createHttpClient } from "../utils/http.ts";
+import manifest, { Manifest } from "./manifest.gen.ts";
+import type { Secret } from "../website/loaders/secret.ts";
+import type { App, AppContext as AC } from "@deco/deco";
+import { fetchSafe } from "../utils/fetch.ts";
+import { MyClient } from "./client.ts";
+
+export type AppContext = AC<ReturnType<typeof MyApp>>;
+
+export interface Props {
+  /**
+   * @description API account identifier
+   */
+  account: string;
+  /**
+   * @title API Key
+   * @format password
+   */
+  apiKey?: Secret;
+  /**
+   * @hide true
+   */
+  platform: "my-integration";
+}
+
+export default function MyApp({ account, apiKey, ...props }: Props) {
+  const headers = new Headers();
+  if (apiKey) {
+    const key = typeof apiKey === "string" ? apiKey : apiKey?.get?.() ?? "";
+    headers.set("Authorization", `Bearer ${key}`);
+  }
+
+  const api = createHttpClient<MyClient>({
+    base: `https://api.example.com/v1/${account}`,
+    headers,
+    fetcher: fetchSafe,
+  });
+
+  const state = { ...props, account, api };
+
+  const app: App<Manifest, typeof state> = {
+    state,
+    manifest,
+  };
+
+  return app;
+}
+```
+
+### Loaders
+
+```typescript
+// loaders/products.ts
+import { AppContext } from "../mod.ts";
+
+export interface Props {
+  /** @description Search query */
+  query?: string;
+  /** @description Items per page */
+  count?: number;
+}
+
+const loader = async (props: Props, _req: Request, ctx: AppContext) => {
+  const { api } = ctx;
+  const response = await api["GET /products"]({
+    q: props.query,
+    limit: props.count ?? 12,
+  });
+  return response.json();
+};
+
+export default loader;
+```
+
+### Actions
+
+```typescript
+// actions/createUser.ts
+import { AppContext } from "../mod.ts";
+
+export interface Props {
+  name: string;
+  email: string;
+}
+
+const action = async (props: Props, _req: Request, ctx: AppContext) => {
+  const { api } = ctx;
+  const response = await api["POST /users"]({}, { body: props });
+  return response.json();
+};
+
+export default action;
+```
+
+4. Run `deno task start` to generate `manifest.gen.ts`
+
+## Commerce App Template
+
+For e-commerce integrations, additional files are needed:
+
+### `utils/transform.ts`
+
+Maps platform-specific API responses to schema.org types:
+
+```typescript
+import { Product, Offer } from "../../commerce/types.ts";
+
+export const toProduct = (raw: PlatformProduct): Product => ({
+  "@type": "Product",
+  productID: String(raw.skuId),
+  sku: String(raw.skuId),
+  name: raw.name,
+  url: `/${raw.slug}/p`,
+  image: raw.images.map(img => ({
+    "@type": "ImageObject" as const,
+    url: img.url,
+    alternateName: img.alt,
+  })),
+  offers: {
+    "@type": "AggregateOffer",
+    priceCurrency: "BRL",
+    highPrice: raw.listPrice,
+    lowPrice: raw.price,
+    offerCount: 1,
+    offers: [{
+      "@type": "Offer",
+      seller: String(raw.sellerId),   // MUST be ID, not name!
+      price: raw.price,
+      availability: raw.available
+        ? "https://schema.org/InStock"
+        : "https://schema.org/OutOfStock",
+      priceSpecification: [
+        {
+          "@type": "UnitPriceSpecification",
+          priceType: "https://schema.org/ListPrice",
+          price: raw.listPrice,
+        },
+        {
+          "@type": "UnitPriceSpecification",
+          priceType: "https://schema.org/SalePrice",
+          price: raw.price,
+        },
+      ],
+    }],
+  },
+  isVariantOf: {
+    "@type": "ProductGroup",
+    productGroupID: String(raw.productId),
+    hasVariant: [],
+    name: raw.productName,
+    url: `/${raw.slug}/p`,
+  },
+});
+```
+
+### Required Commerce Loaders
+
+| Loader | Return Type | Purpose |
+|--------|-------------|---------|
+| `productDetailsPage.ts` | `ProductDetailsPage` | PDP |
+| `productListingPage.ts` | `ProductListingPage` | PLP/Category |
+| `productList.ts` | `Product[]` | Product shelf/carousel |
+| `suggestions.ts` | `Suggestion` | Search autocomplete |
+| `cart.ts` | `OrderForm` (platform-specific) | Shopping cart |
+| `user.ts` | `Person` | Current user |
+
+### Required Commerce Actions
+
+| Action | Purpose |
+|--------|---------|
+| `cart/addItems.ts` | Add to cart |
+| `cart/updateItems.ts` | Update quantities |
+| `cart/removeItems.ts` | Remove/clear cart |
+| `cart/updateCoupons.ts` | Apply coupon |
+| `authentication/signIn.ts` | User login |
+| `authentication/logout.ts` | User logout |
+
+### Required Hooks
+
+| Hook | State | Purpose |
+|------|-------|---------|
+| `context.ts` | `{ cart, user, wishlist }` | Central reactive state |
+| `useCart.ts` | Cart mutations | Cart operations |
+| `useUser.ts` | User state | User info |
+| `useWishlist.ts` | Wishlist CRUD | Wishlist operations |
+
+## MCP App Template
+
+For AI/MCP integrations:
+
+```bash
+deno task new
+# Select: MCP
+# Template: Oauth
+```
+
+MCP apps expose tools for AI assistants via the Deco MCP protocol. They use `mcp/` utilities for OAuth, bindings, and context.
+
+## Checklist
+
+- [ ] `client.ts` with typed API interface
+- [ ] `mod.ts` with Props and app factory
+- [ ] `manifest.gen.ts` generated via `deno task start`
+- [ ] Loaders for read operations
+- [ ] Actions for write operations
+- [ ] `deco.ts` updated with `app("my-app")`
+- [ ] README.md with usage instructions
+- [ ] (Commerce) `transform.ts` for schema.org mapping
+- [ ] (Commerce) All required loaders and actions
+- [ ] (Commerce) Client-side hooks

package/.cursor/skills/deco-apps-architecture/scripts-codegen.md

@@ -0,0 +1,148 @@
+# Scripts & Codegen Reference
+
+## `scripts/start.ts`
+
+Main codegen script, runs via `deno task start`. Performs three steps in sequence:
+
+### 1. OpenAPI Type Generation
+
+Walks the entire repo looking for `*.openapi.json` files, then:
+
+1. Parses the OpenAPI 3.x spec
+2. Extracts every endpoint: `VERB /path` → typed interface with `response`, `body`, `searchParams`
+3. Converts URL path params: `/{userId}` → `/:userId`
+4. Handles nullable types (OpenAPI `nullable: true` → TypeScript union with `null`)
+5. Compiles via `json-schema-to-typescript`
+6. Outputs `*.openapi.gen.ts` next to the JSON spec
+7. Formats with `deno fmt` and lints with `deno lint`
+
+**Location pattern:** `{app}/utils/openapi/{name}.openapi.json` → `{app}/utils/openapi/{name}.openapi.gen.ts`
+
+**Usage:** The generated types are consumed by `createHttpClient<GeneratedType>()`.
+
+### 2. GraphQL Type Generation
+
+Walks the repo for `*.graphql.json` files (GraphQL SDL schemas), then:
+
+1. Uses `@graphql-codegen/cli` with plugins:
+   - `typescript` — base types from schema
+   - `typescript-operations` — types from query documents (`.ts` files with `gql` tags)
+2. Outputs `*.graphql.gen.ts` in the same directory
+3. Scans all `**/*.ts` files for query/mutation documents
+
+**Location pattern:** `{app}/utils/storefront/{name}.graphql.json` → `{app}/utils/storefront/{name}.graphql.gen.ts`
+
+### 3. Deco Bundle
+
+Calls `@deco/deco/scripts/bundle` which:
+- Scans all apps listed in `deco.ts`
+- Generates `manifest.gen.ts` for each app
+- Registers actions, loaders, handlers, sections, workflows
+
+## `scripts/new.ts`
+
+Interactive project scaffolder, runs via `deno task new`:
+
+1. Prompts for type: `APP` or `MCP`
+2. Lists available templates per type
+3. Prompts for project name (validated as kebab-case)
+4. Clones the template repository:
+   - APP → `https://github.com/deco-cx/app-template`
+   - MCP → `https://github.com/deco-cx/mcp-oauth-template`
+5. Updates `deco.ts` to register the new app: `app("{name}")`
+6. Removes template `.git` directory
+7. Removes template `deno.json` (uses root config)
+8. Runs `deno task start` to generate manifests
+
+## `deno.json` Tasks
+
+```json
+{
+  "tasks": {
+    "check": "deno fmt --check && deno lint && deno check **/mod.ts",
+    "start": "deno run -A ./scripts/start.ts",
+    "bundle": "deno run -A jsr:@deco/deco/scripts/bundle",
+    "new": "deno run -A ./scripts/new.ts",
+    "release": "deno eval 'import \"deco/scripts/release.ts\"'",
+    "link": "deno eval 'import \"deco/scripts/apps/link.ts\"'",
+    "unlink": "deno eval 'import \"deco/scripts/apps/unlink.ts\"'",
+    "serve": "deno eval 'import \"deco/scripts/apps/serve.ts\"'",
+    "watcher": "deno eval 'import \"deco/scripts/apps/watcher.ts\"'",
+    "update": "deno eval 'import \"deco/scripts/update.ts\"'",
+    "reload": "deno cache -r https://deco.cx/run"
+  }
+}
+```
+
+| Task | Purpose |
+|------|---------|
+| `start` | Full codegen (OpenAPI + GraphQL + manifest) |
+| `check` | CI quality gate (format + lint + type-check) |
+| `bundle` | Only manifest generation (skip OpenAPI/GraphQL) |
+| `new` | Scaffold new app from template |
+| `release` | Publish new version |
+| `link`/`unlink` | Link local apps for development |
+| `serve` | Start local development server |
+| `watcher` | File watcher for auto-rebuild |
+| `update` | Update Deco dependencies |
+| `reload` | Cache bust |
+
+## CI/CD (`.github/workflows/`)
+
+### `ci.yaml` (Push/PR)
+1. `deno task start` — full build
+2. `deno task check` — format + lint + type-check
+3. `deno test` (continue-on-error)
+4. `deno bench` (continue-on-error)
+
+### `release.yaml` (Tag push)
+Publishes release on tag creation.
+
+### `releaser.yaml` (PR/Comments)
+- On PR: adds comment with version bump options (patch/minor/major)
+- On comment reaction: updates version in `deno.json`, creates git tag
+
+## `deco.ts` — App Registry
+
+Central configuration listing all apps:
+
+```typescript
+const app = (name: string) => ({ dir: name, name });
+
+const compatibilityApps = [
+  { dir: "./compat/$live", name: "$live" },
+  { dir: "./compat/std", name: "deco-sites/std" },
+];
+
+const config = {
+  apps: [
+    app("vtex"),
+    app("shopify"),
+    app("website"),
+    app("commerce"),
+    // ... ~90 apps total
+    ...compatibilityApps,
+  ],
+};
+
+export default config;
+```
+
+The `name` must match the directory name. Order matters for dependency resolution.
+
+## Adding OpenAPI Types to an App
+
+1. Place your OpenAPI 3.x spec at `{app}/utils/openapi/{name}.openapi.json`
+2. Run `deno task start`
+3. Import the generated types:
+   ```typescript
+   import { OpenAPI } from "./utils/openapi/{name}.openapi.gen.ts";
+   const client = createHttpClient<OpenAPI>({ base: "https://api.example.com" });
+   ```
+
+## Adding GraphQL Types to an App
+
+1. Place your GraphQL SDL at `{app}/utils/{name}.graphql.json`
+2. Write queries in `.ts` files using the `gql` tag
+3. Run `deno task start`
+4. Import generated types from `{name}.graphql.gen.ts`

package/.cursor/skills/deco-apps-architecture/shared-utils.md

@@ -0,0 +1,181 @@
+# Shared Utils — `/utils/` Reference
+
+The root `/utils/` directory provides platform-agnostic utilities used by all apps.
+
+## `http.ts` — Typed HTTP Client
+
+### `createHttpClient<T>(options)`
+
+Creates a Proxy-based HTTP client typed against an interface `T` where keys follow the pattern `"VERB /path/:param"`.
+
+```typescript
+import { createHttpClient } from "../utils/http.ts";
+
+interface MyAPI {
+  "GET /users/:id": {
+    response: User;
+    searchParams: { fields?: string };
+  };
+  "POST /users": {
+    response: User;
+    body: { name: string; email: string };
+  };
+}
+
+const client = createHttpClient<MyAPI>({
+  base: "https://api.example.com",
+  headers: new Headers({ "Authorization": "Bearer ..." }),
+  fetcher: fetchSafe,            // Optional custom fetcher
+  processHeaders: removeDirtyCookies, // Optional header processor
+});
+
+// Usage — fully typed params, body, and response
+const res = await client["GET /users/:id"]({ id: "123", fields: "name" });
+const user = await res.json(); // typed as User
+```
+
+### Interface Pattern for Typed Endpoints
+
+```typescript
+interface API {
+  "VERB /path/:required/:optional?/*wildcard": {
+    response: ResponseType;        // Return type of .json()
+    body: BodyType;                // Required for POST/PUT/PATCH
+    searchParams: {                // Query string parameters
+      required: string;
+      optional?: number;
+    };
+  };
+}
+```
+
+- URL params with `:` are extracted from the first argument
+- Remaining keys become query string params
+- `body` auto-serializes objects to JSON
+
+### `HttpError`
+
+```typescript
+class HttpError extends Error {
+  status: number;
+}
+```
+
+### `nullOnNotFound`
+
+```typescript
+const product = await client["GET /product/:id"]({ id }).catch(nullOnNotFound);
+// Returns null for 404, rethrows other errors
+```
+
+---
+
+## `graphql.ts` — GraphQL Client
+
+### `createGraphqlClient(options)`
+
+```typescript
+import { createGraphqlClient, gql } from "../utils/graphql.ts";
+
+const client = createGraphqlClient({
+  endpoint: "https://api.example.com/graphql",
+  fetcher: fetchSafe,
+});
+
+const data = await client.query<ResponseType, VariablesType>({
+  query: gql`query GetUser($id: ID!) { user(id: $id) { name } }`,
+  variables: { id: "123" },
+  operationName: "GetUser",  // optional
+  fragments: [fragmentStr],  // optional — appended to query
+});
+```
+
+### `gql` Template Tag
+
+```typescript
+const MY_QUERY = gql`
+  query GetProducts($first: Int!) {
+    products(first: $first) { id name }
+  }
+`;
+```
+
+---
+
+## `fetch.ts` — Safe Fetch with Retry
+
+### `fetchSafe(input, init?)`
+
+Wraps `fetch` with:
+- Retry on connection closed errors (1 retry, exponential backoff)
+- Throws `HttpError` on non-OK responses
+- Handles 301/302 with `redirect: "manual"`
+
+### `fetchAPI<T>(input, init?)`
+
+Convenience that sets `Accept: application/json` and returns `response.json()`.
+
+### `STALE`
+
+```typescript
+export const STALE = {
+  deco: { cache: "stale-while-revalidate" },
+} as const;
+
+// Usage: fetch(url, { ...init, ...STALE })
+```
+
+---
+
+## `cookie.ts` — Cookie Utilities
+
+### `proxySetCookie(from, to, toDomain?)`
+
+Copies Set-Cookie headers from one response to another, optionally rewriting the domain.
+
+```typescript
+proxySetCookie(vtexResponse.headers, ctx.response.headers, req.url);
+```
+
+### `getFlagsFromCookies(cookies)`
+
+Extracts Deco feature flags from the `DECO_SEGMENT` cookie.
+
+---
+
+## `normalize.ts` — String Sanitization
+
+| Function | Purpose |
+|----------|---------|
+| `removeScriptChars(str)` | Removes `+`, brackets, slashes, dots, diacritics |
+| `removeNonLatin1Chars(str)` | Strips non-ASCII and quotes |
+| `removeNonAscChars(str)` | Same as above (alias) |
+| `removeDirtyCookies(headers)` | Sanitizes the `cookie` header — removes brackets and diacritics |
+
+Used as `processHeaders` in HTTP clients to prevent malformed cookies from breaking API calls.
+
+---
+
+## Other Utils
+
+| File | Purpose |
+|------|---------|
+| `lru.ts` | LRU cache with `get`, `set`, `delete` |
+| `shortHash.ts` | `hashString` (SHA-256 async), `hashStringSync` (simple hash) |
+| `pool.ts` | Resource pool with `acquire`/`release` (uses Deferred) |
+| `worker.ts` | Web Worker abstraction (Comlink-style `postMessage` RPC) |
+| `dataURI.ts` | Converts scripts to `data:` URIs for inline `<script>` tags |
+| `capitalize.ts` | Capitalizes first letter of each word |
+| `deferred.ts` | `__DECO_FBT` and `shouldForceRender` for async rendering |
+
+---
+
+## Commerce Utils (`/commerce/utils/`)
+
+| File | Purpose |
+|------|---------|
+| `canonical.ts` | `canonicalFromBreadcrumblist(b)` — extracts URL from last breadcrumb item |
+| `constants.ts` | `DEFAULT_IMAGE` — placeholder ImageObject for products without images |
+| `filters.ts` | `parseRange("10:100")` → `{ from: 10, to: 100 }`, `formatRange(10, 100)` → `"10:100"` |
+| `productToAnalyticsItem.ts` | `mapProductToAnalyticsItem({ product, breadcrumbList, price, ... })` → `AnalyticsItem` |
+| `stateByZip.ts` | `getStateFromZip("01001000")` → `"SP"` — maps Brazilian ZIP to state |