@usequark/quark-create-app 1.23.11

package/templates/base-project/skills/ecommerce-checkout/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: ecommerce-checkout
+description: Checkout flow, order lifecycle, and inventory management for Quark ecommerce. Use when building checkout, orders, payments, fulfillment, or stock management.
+---
+
+# Ecommerce Checkout Skill
+
+Build the checkout flow, order lifecycle, and inventory management for an ecommerce system on Quark.
+
+## Models
+
+```prisma
+enum OrderStatus {
+  PENDING
+  PAID
+  PROCESSING
+  FULFILLED
+  DELIVERED
+  REFUNDED
+  CANCELLED
+}
+
+model Order {
+  id              String      @id @default(cuid())
+  userId          String?
+  user            User?       @relation(fields: [userId], references: [id])
+  status          OrderStatus @default(PENDING)
+  email           String
+  shippingName    String
+  shippingAddress String    @db.Text
+  shippingCity    String
+  shippingZip     String
+  shippingCountry String
+  total           Decimal     @db.Decimal(10, 2)
+  currency        String      @default("USD")
+  stripeSessionId String?     @unique
+  paidAt          DateTime?
+  fulfilledAt     DateTime?
+  deliveredAt     DateTime?
+  createdAt       DateTime    @default(now())
+  updatedAt       DateTime    @updatedAt
+  items           OrderItem[]
+
+  @@index([userId, status])
+  @@index([status])
+  @@index([stripeSessionId])
+  @@index([createdAt])
+}
+
+model OrderItem {
+  id        String         @id @default(cuid())
+  orderId   String
+  order     Order          @relation(fields: [orderId], references: [id], onDelete: Cascade)
+  variantId String
+  variant   ProductVariant @relation(fields: [variantId], references: [id])
+  quantity  Int
+  unitPrice Decimal        @db.Decimal(10, 2)
+  createdAt DateTime       @default(now())
+  updatedAt DateTime       @updatedAt
+
+  @@index([orderId])
+}
+```
+
+## Checkout action
+
+```js
+"use server";
+import { z } from "zod";
+import { prisma } from "@__QUARK_SCOPE__/db";
+import { AppError, ValidationError } from "@techstream/quark-core/errors";
+import { createLogger } from "@techstream/quark-core";
+
+const log = createLogger("action:checkout");
+
+const checkoutSchema = z.object({
+  cartId: z.string().min(1),
+  email: z.string().email(),
+  shippingName: z.string().min(1),
+  shippingAddress: z.string().min(1),
+  shippingCity: z.string().min(1),
+  shippingZip: z.string().min(1),
+  shippingCountry: z.string().min(2).max(2),
+});
+
+export async function createOrder(formData) {
+  const parsed = checkoutSchema.safeParse(Object.fromEntries(formData));
+  if (!parsed.success) throw new ValidationError(parsed.error.flatten());
+
+  const { cartId } = parsed.data;
+
+  const order = await prisma.$transaction(async (tx) => {
+    const cart = await tx.cart.findUnique({
+      where: { id: cartId },
+      include: { items: { include: { variant: true } } },
+    });
+    if (!cart || cart.items.length === 0) {
+      throw new AppError("Cart is empty", 400, "EMPTY_CART");
+    }
+
+    for (const item of cart.items) {
+      const updated = await tx.productVariant.updateMany({
+        where: { id: item.variantId, stock: { gte: item.quantity } },
+        data: { stock: { decrement: item.quantity } },
+      });
+      if (updated.count === 0) {
+        throw new AppError(`Out of stock: ${item.variant.name}`, 409, "OUT_OF_STOCK");
+      }
+    }
+
+    const total = cart.items.reduce(
+      (sum, item) => sum + Number(item.variant.price) * item.quantity, 0
+    );
+
+    const order = await tx.order.create({
+      data: {
+        ...parsed.data,
+        total,
+        items: {
+          create: cart.items.map((item) => ({
+            variantId: item.variantId,
+            quantity: item.quantity,
+            unitPrice: item.variant.price,
+          })),
+        },
+      },
+    });
+
+    await tx.cartItem.deleteMany({ where: { cartId } });
+    log.info("order created", { orderId: order.id, total });
+    return order;
+  });
+
+  return order;
+}
+```
+
+## Order lifecycle
+
+```
+PENDING → PAID (payment webhook)
+PAID → PROCESSING (admin starts fulfillment)
+PROCESSING → FULFILLED (admin ships)
+FULFILLED → DELIVERED (carrier/admin)
+PAID/PROCESSING/FULFILLED → REFUNDED
+Any → CANCELLED (before fulfillment, admin only)
+```
+
+```js
+const ORDER_TRANSITIONS = {
+  PENDING:     ["PAID", "CANCELLED"],
+  PAID:        ["PROCESSING", "REFUNDED", "CANCELLED"],
+  PROCESSING:  ["FULFILLED", "REFUNDED"],
+  FULFILLED:   ["DELIVERED", "REFUNDED"],
+  DELIVERED:   ["REFUNDED"],
+  REFUNDED:    [],
+  CANCELLED:   [],
+};
+
+export function canTransitionOrder(from, to) {
+  return ORDER_TRANSITIONS[from]?.includes(to) ?? false;
+}
+
+export function applyOrderTransition(order, newStatus, opts = {}) {
+  if (!canTransitionOrder(order.status, newStatus)) {
+    throw new ValidationError(`Cannot transition from ${order.status} to ${newStatus}`);
+  }
+  const data = { status: newStatus };
+  if (newStatus === "PAID") data.paidAt = new Date();
+  if (newStatus === "FULFILLED") data.fulfilledAt = new Date();
+  if (newStatus === "DELIVERED") data.deliveredAt = new Date();
+  return data;
+}
+```
+
+## Inventory management
+
+Each `ProductVariant` tracks `stock` (total) and `reserved` (pending orders). **Available** = `stock - reserved`. Use atomic decrement in a transaction to prevent overselling.
+
+Optional reserve/release pattern:
+
+```js
+// Reserve on cart add
+await tx.productVariant.update({ where: { id: variantId }, data: { reserved: { increment: qty } } });
+// Release on cart abandon/cancel
+await tx.productVariant.update({ where: { id: variantId }, data: { reserved: { decrement: qty } } });
+```
+
+## Payment integration
+
+Reference the payment skill for Stripe Checkout:
+1. Create a Checkout Session with cart line items.
+2. Store `stripeSessionId` on the Order.
+3. Handle `checkout.session.completed` webhook → transition to `PAID`.
+4. Handle refunds via Stripe API → transition to `REFUNDED`.

package/templates/base-project/skills/i18n/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: i18n
+description: Add internationalization and localization to Quark apps. Use when adding multi-language support, locale routing, hreflang SEO, locale-aware sitemaps, or localized CMS content.
+---
+
+# i18n Skill
+
+Add multi-language support to a Quark app using `next-intl` with prefix-based routing (`/en/...`), locale detection, and localized CMS content queries. This skill gives you the domain context, Quark framework patterns, and end-result shape. You generate the code that fits the user's exact requirements.
+
+## Context
+
+A localized app must handle locale detection, routing, content translation, and SEO. The core concerns:
+
+- **Locale detection** — resolve the active locale from URL prefix, cookie, `Accept-Language` header, then fallback to default.
+- **Routing** — prefix-based (`/en/about`, `/es/acerca-de`) for SEO and shareable URLs.
+- **Content localization** — locale field on CMS models, queries filtered by locale, fallback chains.
+- **SEO** — `hreflang` alternates, locale-aware sitemaps, `lang` attribute on `<html>`.
+- **UI** — locale switcher component, localized formatting (dates, numbers).
+
+## Locale detection chain
+
+```
+1. URL path prefix      (/en/...)    → explicit user choice
+2. Cookie (n-lang)      ← set by LocaleSwitcher component
+3. Accept-Language      ← browser default
+4. defaultLocale        ← configured fallback ("en")
+```
+
+## Framework context (build on Quark)
+
+- **Library:** `next-intl` — purpose-built for Next.js App Router, native Server Component support, middleware-based locale negotiation, ~2 KB bundle.
+- **Routing:** prefix-based with `localePrefix: 'always'`. All public URLs include the locale prefix. Admin (`/admin`), auth (`/auth`), and API (`/api`) routes stay outside `[locale]`.
+- **Middleware:** `next-intl/middleware` handles locale detection, redirects, and 404s. Configure in `src/i18n/middleware.js`.
+- **Request config:** `getRequestConfig` from `next-intl/server` resolves the locale per request and loads message files.
+- **Models:** CMS models get a `locale String` field. Queries filter by locale with fallback chain.
+- **Validation** — Zod for all Server Actions and API routes. Use a locale enum for localized content submissions.
+- **Auth** via `getCurrentSession` from `@techstream/quark-core`.
+- **Locale utilities** from `@techstream/quark-core/locale`: `getDefaultLocale()`, `getSupportedLocales()`, `isLocaleSupported()`.
+
+## Workflow
+
+1. Read `CLAUDE.md` and `MAIN.md` for project conventions.
+2. Install `next-intl` and configure `getRequestConfig`, middleware, and routing.
+3. Create message files per locale under `messages/` (e.g., `messages/en.json`, `messages/es.json`).
+4. Wrap the app root with `NextIntlClientProvider`; set `html lang` attribute.
+5. Add a locale switcher component (client-side, updates cookie + router).
+6. Add CMS localization: locale field on models, query helpers filtered by locale.
+7. Add SEO: `hreflang` alternates, locale-aware sitemap, metadata per locale.
+
+## Example: routing config
+
+```js
+// src/i18n/routing.js
+import { defineRouting } from "next-intl/routing";
+import { getDefaultLocale, getSupportedLocales } from "@techstream/quark-core/locale";
+
+const supportedLocales = getSupportedLocales();
+
+export const routing = defineRouting({
+  locales: supportedLocales,
+  defaultLocale: getDefaultLocale(),
+  localePrefix: "always",
+});
+```
+
+## Example: request config
+
+```js
+// src/i18n/request.js
+import { getRequestConfig } from "next-intl/server";
+import { hasLocale } from "next-intl";
+import { routing } from "./routing.js";
+
+export default getRequestConfig(async ({ requestLocale }) => {
+  const requested = await requestLocale;
+  const locale = hasLocale(routing.locales, requested)
+    ? requested
+    : routing.defaultLocale;
+
+  return {
+    locale,
+    messages: (await import(`../../messages/${locale}.json`)).default,
+  };
+});
+```
+
+## Example: middleware setup
+
+```js
+// src/i18n/middleware.js
+import createMiddleware from "next-intl/middleware";
+import { routing } from "./routing.js";
+
+export default createMiddleware(routing);
+
+export const config = {
+  matcher: ["/((?!api|admin|auth|_next|.*\\..*).*)"],
+};
+```
+
+## Example: locale switcher component
+
+```jsx
+"use client";
+import { useLocale, useTranslations } from "next-intl";
+import { useRouter, usePathname } from "next/navigation";
+import { getSupportedLocales } from "@techstream/quark-core/locale";
+
+export function LocaleSwitcher() {
+  const locale = useLocale();
+  const router = useRouter();
+  const pathname = usePathname();
+  const t = useTranslations("LocaleSwitcher");
+  const locales = getSupportedLocales();
+
+  function onSelect(next) {
+    const path = pathname.replace(`/${locale}`, `/${next}`);
+    document.cookie = `n-lang=${next};path=/;max-age=31536000`;
+    router.push(path);
+  }
+
+  return (
+    <select aria-label={t("label")} value={locale} onChange={(e) => onSelect(e.target.value)}>
+      {locales.map((l) => (
+        <option key={l} value={l}>{l.toUpperCase()}</option>
+      ))}
+    </select>
+  );
+}
+```
+
+## Example: CMS model with locale
+
+```prisma
+model Page {
+  id          String        @id @default(cuid())
+  title       String
+  slug        String
+  body        String        @db.Text
+  locale      String        @default("en")
+  status      ContentStatus @default(DRAFT)
+  authorId    String
+  author      User          @relation(fields: [authorId], references: [id])
+  createdAt   DateTime      @default(now())
+  updatedAt   DateTime      @updatedAt
+
+  @@unique([slug, locale])
+  @@index([locale])
+}
+```
+
+## Example: locale-aware query
+
+```js
+import { getDefaultLocale, isLocaleSupported } from "@techstream/quark-core/locale";
+
+export async function getPageBySlug(slug, locale) {
+  const validLocale = isLocaleSupported(locale) ? locale : getDefaultLocale();
+  return prisma.page.findFirst({
+    where: { slug, locale: validLocale, status: "PUBLISHED" },
+  });
+}
+```
+
+## SEO: hreflang and sitemap
+
+```jsx
+// In your page component's generateMetadata:
+export async function generateMetadata({ params }) {
+  const { locale } = await params;
+  const baseUrl = process.env.NEXT_PUBLIC_BASE_URL;
+
+  return {
+    alternates: {
+      languages: Object.fromEntries(
+        getSupportedLocales().map((l) => [l, `${baseUrl}/${l}/${slug}`])
+      ),
+    },
+    lang: locale,
+  };
+}
+```
+
+## Example: Zod validation for localized content
+
+```js
+import { z } from "zod";
+import { isLocaleSupported } from "@techstream/quark-core/locale";
+
+export const localizedPageSchema = z.object({
+  title: z.string().min(1).max(255),
+  slug: z.string().min(1).max(255),
+  body: z.string().min(1),
+  locale: z.string().refine(isLocaleSupported, "Unsupported locale"),
+  status: z.enum(["DRAFT", "PUBLISHED"]).default("DRAFT"),
+});
+```
+
+## Workflow summary
+
+1. Install `next-intl`, configure routing + middleware + request config.
+2. Create `messages/{locale}.json` with translation keys.
+3. Wrap root layout with `NextIntlClientProvider`, set `html lang`.
+4. Build a `LocaleSwitcher` client component.
+5. Add `locale` field to CMS models, update queries with fallback.
+6. Add `hreflang` alternates and locale-aware sitemap.
+7. Test detection chain: URL → cookie → Accept-Language → default.
+
+## End result
+
+A localized Quark app where users switch languages via a prefix-based URL scheme, locale is detected from URL → cookie → header → default, CMS content is filtered by locale with fallback, SEO metadata includes `hreflang` alternates and locale-aware sitemaps, and all content submissions validate locale against the configured supported set — following Quark conventions throughout.

package/templates/base-project/skills/payment/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: payment
+description: Stripe payment integration - checkout sessions, webhooks, customer management, and fulfillment. Use when building payment flows, checkout, subscriptions, or handling Stripe webhooks.
+---
+
+# Payment Skill
+
+Build Stripe payment flows on Quark. This skill covers the full Stripe lifecycle: customer management, checkout sessions, webhook verification, and post-payment fulfillment.
+
+## Domain context
+
+Stripe integration lifecycle:
+
+```
+Customer → Checkout Session → Payment → Webhook → Fulfillment
+```
+
+Key concepts:
+- **Stripe Customer** — persistent record of a payer; store the `stripeCustomerId` on your User model.
+- **Checkout Session** — hosted payment page for one-time or subscription payments.
+- **Webhook** — Stripe sends HTTP events to your server after payment events occur.
+- **Fulfillment** — your server's response to a successful payment (update status, send email, grant access).
+- **Idempotency** — webhook handler must be safe to retry; use `eventId` deduplication.
+
+## Framework context
+
+- **Stripe client** — `createStripeClient()` from `@techstream/quark-core/stripe`. Reads `STRIPE_SECRET_KEY` from env.
+- **Webhook route** — `apps/web/src/app/api/stripe/webhook/route.js`. Use `getStripeWebhookEvent()` from `@techstream/quark-core/stripe` to verify signatures.
+- **Validation** — Zod for all incoming data. Webhook event data is already validated by Stripe's SDK.
+- **Errors** — `AppError` / `ValidationError` from `@techstream/quark-core/errors` for app errors. Never throw on webhook failures — return 200 to prevent Stripe retries for unfixable errors.
+- **Logging** — `createLogger("stripe:webhook")` from `@techstream/quark-core`.
+- **Models** — add `stripeCustomerId String?` to User, `stripeSessionId String?` / `stripeSubscriptionId String?` to relevant models. Every model needs `createdAt` / `updatedAt`.
+
+## Checkout sessions
+
+### Zod validation for checkout input
+
+```js
+import { z } from "zod";
+
+export const checkoutSchema = z.object({
+  priceId: z.string().min(1),
+  quantity: z.number().int().positive().default(1),
+  successUrl: z.string().url().optional(),
+  cancelUrl: z.string().url().optional(),
+});
+```
+
+### One-time payment
+
+```js
+import { createStripeClient } from "@techstream/quark-core/stripe";
+
+const stripe = await createStripeClient();
+const session = await stripe.checkout.sessions.create({
+  mode: "payment",
+  customer: stripeCustomerId, // or omit to create anonymous checkout
+  line_items: [{ price: priceId, quantity: 1 }],
+  success_url: `${origin}/payment/success?session_id={CHECKOUT_SESSION_ID}`,
+  cancel_url: `${origin}/payment/cancel`,
+  metadata: { orderId },
+});
+```
+
+### Subscription
+
+```js
+const session = await stripe.checkout.sessions.create({
+  mode: "subscription",
+  customer: stripeCustomerId,
+  line_items: [{ price: priceId, quantity: 1 }],
+  success_url: `${origin}/account?upgraded=true`,
+  cancel_url: `${origin}/pricing`,
+  metadata: { userId },
+});
+```
+
+## Webhooks
+
+### Webhook route handler
+
+```js
+// apps/web/src/app/api/stripe/webhook/route.js
+import { NextResponse } from "next/server";
+import { getStripeWebhookEvent } from "@techstream/quark-core/stripe";
+import { createLogger } from "@techstream/quark-core";
+import { prisma } from "@__QUARK_SCOPE__/db";
+
+const log = createLogger("stripe:webhook");
+
+export async function POST(request) {
+  const body = await request.text();
+  const signature = request.headers.get("stripe-signature");
+
+  let event;
+  try {
+    event = await getStripeWebhookEvent(body, signature);
+  } catch (err) {
+    log.error("webhook signature verification failed", { error: err.message });
+    return NextResponse.json({ error: "Invalid signature" }, { status: 400 });
+  }
+
+  log.info("webhook received", { type: event.type, id: event.id });
+
+  // Idempotency check — skip if already processed
+  const existing = await prisma.webhookEvent.findUnique({
+    where: { stripeEventId: event.id },
+  });
+  if (existing) {
+    return NextResponse.json({ received: true });
+  }
+
+  // Record event for idempotency
+  await prisma.webhookEvent.create({
+    data: {
+      stripeEventId: event.id,
+      type: event.type,
+      payload: event,
+    },
+  });
+
+  try {
+    switch (event.type) {
+      case "checkout.session.completed":
+        await handleCheckoutCompleted(event.data.object);
+        break;
+      case "invoice.paid":
+        await handleInvoicePaid(event.data.object);
+        break;
+      case "customer.subscription.deleted":
+        await handleSubscriptionDeleted(event.data.object);
+        break;
+      default:
+        log.info("unhandled event type", { type: event.type });
+    }
+  } catch (err) {
+    log.error("webhook handler error", { type: event.type, error: err.message });
+    // Return 200 to prevent Stripe retry for handler errors
+    // Log and alert instead — retrying won't fix app bugs
+  }
+
+  return NextResponse.json({ received: true });
+}
+```
+
+### Event verification
+
+`await getStripeWebhookEvent(body, signature)` calls `stripe.webhooks.constructEvent()` under the hood. It reads `STRIPE_WEBHOOK_SECRET` from env and throws if the signature is invalid.
+
+### Common events to handle
+
+| Event | Use case |
+|---|---|
+| `checkout.session.completed` | Mark order/booking as paid, grant access |
+| `invoice.paid` | Subscription renewal succeeded |
+| `invoice.payment_failed` | Subscription payment failed, notify user |
+| `customer.subscription.deleted` | Revoke access, update status |
+| `charge.refunded` | Process refund, update order status |
+
+### Idempotency
+
+Use a `WebhookEvent` model to record processed event IDs. Check before processing to prevent duplicate fulfillment:
+
+```prisma
+model WebhookEvent {
+  id             String   @id @default(cuid())
+  stripeEventId  String   @unique
+  type           String
+  payload        Json
+  createdAt      DateTime @default(now())
+  updatedAt      DateTime @updatedAt
+
+  @@index([stripeEventId])
+  @@index([type])
+}
+```
+
+## Customer management
+
+### Create or retrieve Stripe customer
+
+```js
+import { createStripeClient } from "@techstream/quark-core/stripe";
+
+export async function getOrCreateStripeCustomer(user) {
+  if (user.stripeCustomerId) return user.stripeCustomerId;
+
+  const stripe = await createStripeClient();
+  const customer = await stripe.customers.create({
+    email: user.email,
+    name: user.name,
+    metadata: { userId: user.id },
+  });
+
+  await prisma.user.update({
+    where: { id: user.id },
+    data: { stripeCustomerId: customer.id },
+  });
+
+  return customer.id;
+}
+```
+
+### User model additions
+
+Add to your User model in Prisma schema:
+
+```prisma
+model User {
+  // ... existing fields
+  stripeCustomerId String?  @unique
+}
+```
+
+## Integration patterns
+
+### Booking deposits
+
+Collect a deposit at booking time:
+
+1. Create booking in `PENDING` status with `stripeSessionId`.
+2. Redirect to Stripe Checkout.
+3. On `checkout.session.completed` webhook: update booking to `CONFIRMED`.
+4. On cancellation: refund via `stripe.refunds.create({ payment_intent })`.
+
+### Ecommerce checkout
+
+1. Create an Order model with `stripeSessionId` and status `PENDING`.
+2. Checkout Session with line items from cart.
+3. Webhook confirms payment → update Order to `PAID`, decrement inventory.
+4. Handle `payment_failed` → notify user, keep order in `PENDING`.
+
+## Testing
+
+### Stripe test mode
+
+- Use Stripe test keys (`sk_test_...`) in `.env` for development.
+- Test card: `4242 4242 4242 4242` (any future expiry, any CVC).
+- Stripe Dashboard → Developers → Webhooks → add `http://localhost:3000/api/stripe/webhook` for local testing.
+
+### Webhook CLI
+
+Install the Stripe CLI and forward webhooks to your local server:
+
+```bash
+stripe listen --forward-to localhost:3000/api/stripe/webhook
+```
+
+The CLI prints a webhook signing secret (`whsec_...`) — add it to `.env` as `STRIPE_WEBHOOK_SECRET`.
+
+### Test pattern
+
+```js
+import { test } from "node:test";
+import assert from "node:assert";
+
+test("handleCheckoutCompleted updates booking status", async () => {
+  // Create a mock Stripe session object
+  // Assert booking status changes from PENDING to CONFIRMED
+});
+```
+
+## Workflow
+
+1. Read `CLAUDE.md` and project conventions.
+2. Add `stripe` dependency to the consuming app if not already present.
+3. Set up env vars: `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`.
+4. Create Stripe Customer ID field on User model (if customer management is needed).
+5. Build checkout session creation (Server Action or API route).
+6. Implement webhook route handler with signature verification and idempotency.
+7. Add fulfillment logic (update models, send emails, grant access).
+8. Test with Stripe CLI webhook forwarding and test card numbers.
+
+## Reference
+
+Stripe docs: https://docs.stripe.com
+
+## End result
+
+A working payment system where users can complete Stripe Checkout for one-time or subscription payments, webhooks verify signatures and deduplicate events via `WebhookEvent`, Stripe customers are created lazily and stored on the User model, and post-payment fulfillment (booking confirmation, order status, access grants) runs idempotently — all following Quark conventions.