@usequark/quark-create-app 1.23.11

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

@@ -0,0 +1,224 @@
+---
+name: ecommerce
+description: Build an ecommerce system on Quark. Use when the user wants products, catalog, cart, checkout, orders, inventory, or storefront.
+---
+
+# Ecommerce Skill
+
+Build an ecommerce system on Quark's infrastructure. This skill gives you the domain context, the Quark framework patterns, and the end-result shape. You generate the code that fits the user's exact requirements.
+
+## Context
+
+An ecommerce system manages a product catalog, shopping cart, checkout flow, orders, and inventory. The core entities and concerns:
+
+- **Product** — the sellable item with name, description, pricing, and images.
+- **ProductVariant** — a specific option of a product (size, color, material) with its own SKU, price, and stock.
+- **Category** — hierarchical grouping for browsing and filtering.
+- **Cart** — a session-linked or user-linked collection of items before purchase.
+- **Order** — a completed purchase with line items, shipping address, payment status, and fulfillment state.
+- **Inventory** — stock levels, reserved vs. available counts, atomic decrement on order.
+
+## Framework context (build on Quark)
+
+- **Models** live in `packages/db/prisma/schema.prisma`. Every model needs `id`, `createdAt DateTime @default(now())`, `updatedAt DateTime @updatedAt`. After changes: `pnpm db:generate && pnpm db:migrate`.
+- **Data access** goes through query helpers in `packages/db/src/queries.js` — never call `prisma.*` directly in pages/actions.
+- **Server Actions** (preferred for mutations) use `"use server"`, Zod validation, and `AppError`/`ValidationError` from `@techstream/quark-core/errors`.
+- **Admin views** live under `apps/web/src/app/admin/` (see the admin-dashboard skill for product/order management).
+- **Auth** via `getCurrentSession` from `@techstream/quark-core`.
+- **Payment** integration follows the payment skill for Stripe Checkout or similar processors.
+
+## Workflow
+
+1. Read `CLAUDE.md` and `MAIN.md` for project conventions.
+2. Clarify the user's requirements: product types, variants, categories, checkout flow, payment provider.
+3. Design the Prisma models (Product, Variant, Category, Cart, CartItem, Order, OrderItem) and add query helpers.
+4. Build the catalog endpoints: CRUD for products, variants, categories with admin guards.
+5. Build the cart: session-based or user-linked, add/remove/update actions, cart total calculation.
+6. Build checkout: address collection → shipping method → payment → order creation with inventory decrement.
+7. Add tests near the changed code.
+
+## Example: Prisma models
+
+```prisma
+enum OrderStatus {
+  PENDING
+  PAID
+  PROCESSING
+  FULFILLED
+  DELIVERED
+  REFUNDED
+  CANCELLED
+}
+
+model Product {
+  id          String          @id @default(cuid())
+  name        String
+  slug        String          @unique
+  description String?         @db.Text
+  basePrice   Decimal         @db.Decimal(10, 2)
+  currency    String          @default("USD")
+  images      String[]
+  active      Boolean         @default(true)
+  categoryId  String?
+  category    Category?       @relation(fields: [categoryId], references: [id])
+  variants    ProductVariant[]
+  createdAt   DateTime        @default(now())
+  updatedAt   DateTime        @updatedAt
+
+  @@index([slug])
+  @@index([categoryId])
+  @@index([active])
+}
+
+model ProductVariant {
+  id        String   @id @default(cuid())
+  productId String
+  product   Product  @relation(fields: [productId], references: [id], onDelete: Cascade)
+  sku       String   @unique
+  name      String
+  price     Decimal  @db.Decimal(10, 2)
+  stock     Int      @default(0)
+  reserved  Int      @default(0)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([productId])
+  @@index([sku])
+}
+
+model Category {
+  id          String    @id @default(cuid())
+  name        String
+  slug        String    @unique
+  description String?   @db.Text
+  parentId    String?
+  parent      Category? @relation("CategoryTree", fields: [parentId], references: [id])
+  children    Category[] @relation("CategoryTree")
+  products    Product[]
+  createdAt   DateTime  @default(now())
+  updatedAt   DateTime  @updatedAt
+
+  @@index([slug])
+  @@index([parentId])
+}
+
+model Cart {
+  id        String     @id @default(cuid())
+  userId    String?
+  user      User?      @relation(fields: [userId], references: [id])
+  sessionId String?    @unique
+  items     CartItem[]
+  createdAt DateTime   @default(now())
+  updatedAt DateTime   @updatedAt
+
+  @@index([userId])
+  @@index([sessionId])
+}
+
+model CartItem {
+  id        String         @id @default(cuid())
+  cartId    String
+  cart      Cart           @relation(fields: [cartId], references: [id], onDelete: Cascade)
+  variantId String
+  variant   ProductVariant @relation(fields: [variantId], references: [id])
+  quantity  Int            @default(1)
+  createdAt DateTime       @default(now())
+  updatedAt DateTime       @updatedAt
+
+  @@unique([cartId, variantId])
+}
+
+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])
+}
+```
+
+## Example: Zod validation
+
+```js
+import { z } from "zod";
+
+export const addToCartSchema = z.object({
+  cartId: z.string().min(1),
+  variantId: z.string().min(1),
+  quantity: z.coerce.number().int().positive().default(1),
+});
+
+export 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),
+});
+```
+
+## Sub-skills
+
+The ecommerce domain is split into focused sub-skills. Load the one that matches your current task:
+
+| Sub-skill | Path | Covers |
+|---|---|---|
+| ecommerce-catalog | `ecommerce-catalog/SKILL.md` | Product, variant, and category models + CRUD. |
+| ecommerce-cart | `ecommerce-cart/SKILL.md` | Cart model, add/remove/update, session linking, totals. |
+| ecommerce-checkout | `ecommerce-checkout/SKILL.md` | Checkout flow, order lifecycle, inventory, integration. |
+
+## Integration points
+
+### Admin dashboard
+
+Use the admin-dashboard skill to build product management screens:
+- `apps/web/src/app/admin/products/` — list, create, edit products and variants.
+- `apps/web/src/app/admin/orders/` — list orders, update status, view details.
+- `apps/web/src/app/admin/categories/` — manage category tree.
+
+### Payment
+
+Reference the payment skill for Stripe Checkout integration:
+1. Create a Checkout Session with cart line items.
+2. Store `stripeSessionId` on the Order.
+3. Handle the `checkout.session.completed` webhook to transition to `PAID`.
+4. Handle refunds via the Stripe API, transitioning to `REFUNDED`.
+
+## End result
+
+A working ecommerce system where users can browse a product catalog, add items to a cart, complete checkout with payment, and have orders tracked through a fulfillment lifecycle — with inventory management, admin screens, and Quark conventions throughout.

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

@@ -0,0 +1,193 @@
+---
+name: ecommerce-cart
+description: Shopping cart for Quark ecommerce. Use when building cart add/remove/update, session linking, or cart totals.
+---
+
+# Ecommerce Cart Skill
+
+Build the shopping cart for an ecommerce system on Quark. This sub-skill covers the cart model, item operations, session linking, and total calculation.
+
+## Context
+
+The cart is a temporary collection of items a user intends to purchase. Key concerns:
+
+- **Session-based or user-linked** — anonymous carts use a session ID; authenticated carts link to a user.
+- **Add/remove/update** — atomic operations with stock validation.
+- **Cart totals** — computed from item quantities and variant prices.
+
+## Framework context (build on Quark)
+
+- **Models** live in `packages/db/prisma/schema.prisma`. Every model needs `id`, `createdAt DateTime @default(now())`, `updatedAt DateTime @updatedAt`. After changes: `pnpm db:generate && pnpm db:migrate`.
+- **Data access** goes through query helpers in `packages/db/src/queries.js` — never call `prisma.*` directly in pages/actions.
+- **Server Actions** use `"use server"`, Zod validation, and `AppError`/`ValidationError` from `@techstream/quark-core/errors`.
+- **Auth** via `getCurrentSession` from `@techstream/quark-core`.
+
+## Models
+
+```prisma
+model Cart {
+  id        String     @id @default(cuid())
+  userId    String?
+  user      User?      @relation(fields: [userId], references: [id])
+  sessionId String?    @unique
+  items     CartItem[]
+  createdAt DateTime   @default(now())
+  updatedAt DateTime   @updatedAt
+
+  @@index([userId])
+  @@index([sessionId])
+}
+
+model CartItem {
+  id        String         @id @default(cuid())
+  cartId    String
+  cart      Cart           @relation(fields: [cartId], references: [id], onDelete: Cascade)
+  variantId String
+  variant   ProductVariant @relation(fields: [variantId], references: [id])
+  quantity  Int            @default(1)
+  createdAt DateTime       @default(now())
+  updatedAt DateTime       @updatedAt
+
+  @@unique([cartId, variantId])
+}
+```
+
+## Query helpers
+
+```js
+// packages/db/src/queries.js additions
+
+export async function getCartBySession(sessionId) {
+  return prisma.cart.findUnique({
+    where: { sessionId },
+    include: { items: { include: { variant: { include: { product: true } } } } },
+  });
+}
+
+export async function getCartByUser(userId) {
+  return prisma.cart.findFirst({
+    where: { userId },
+    include: { items: { include: { variant: { include: { product: true } } } } },
+  });
+}
+
+export async function getCartTotal(cartId) {
+  const items = await prisma.cartItem.findMany({
+    where: { cartId },
+    include: { variant: true },
+  });
+  return items.reduce((sum, item) => sum + Number(item.variant.price) * item.quantity, 0);
+}
+```
+
+## Cart operations
+
+### Adding to cart
+
+Use a Prisma transaction to prevent race conditions. Check stock availability before adding.
+
+```js
+import { prisma } from "@__QUARK_SCOPE__/db";
+import { AppError } from "@techstream/quark-core/errors";
+
+export async function addToCart(cartId, variantId, quantity = 1) {
+  return prisma.$transaction(async (tx) => {
+    const variant = await tx.productVariant.findUnique({ where: { id: variantId } });
+    if (!variant) throw new AppError("Variant not found", 404, "NOT_FOUND");
+
+    const available = variant.stock - variant.reserved;
+    if (available < quantity) {
+      throw new AppError("Insufficient stock", 409, "OUT_OF_STOCK");
+    }
+
+    const existing = await tx.cartItem.findUnique({
+      where: { cartId_variantId: { cartId, variantId } },
+    });
+
+    if (existing) {
+      return tx.cartItem.update({
+        where: { id: existing.id },
+        data: { quantity: existing.quantity + quantity },
+      });
+    }
+
+    return tx.cartItem.create({
+      data: { cartId, variantId, quantity },
+    });
+  });
+}
+```
+
+### Updating quantity
+
+```js
+export async function updateCartItemQuantity(cartItemId, quantity) {
+  if (quantity < 1) {
+    return prisma.cartItem.delete({ where: { id: cartItemId } });
+  }
+  return prisma.cartItem.update({
+    where: { id: cartItemId },
+    data: { quantity },
+  });
+}
+```
+
+### Removing from cart
+
+```js
+export async function removeFromCart(cartItemId) {
+  return prisma.cartItem.delete({ where: { id: cartItemId } });
+}
+```
+
+## Session linking
+
+For anonymous users, create a cart with a random `sessionId` cookie. On login, merge the session cart into the user's cart:
+
+```js
+export async function mergeCarts(sessionId, userId) {
+  const sessionCart = await prisma.cart.findUnique({
+    where: { sessionId },
+    include: { items: true },
+  });
+  if (!sessionCart) return;
+
+  let userCart = await prisma.cart.findFirst({ where: { userId } });
+  if (!userCart) {
+    userCart = await prisma.cart.create({ data: { userId } });
+  }
+
+  for (const item of sessionCart.items) {
+    const existing = await prisma.cartItem.findUnique({
+      where: { cartId_variantId: { cartId: userCart.id, variantId: item.variantId } },
+    });
+    if (existing) {
+      await prisma.cartItem.update({
+        where: { id: existing.id },
+        data: { quantity: existing.quantity + item.quantity },
+      });
+    } else {
+      await prisma.cartItem.create({
+        data: { cartId: userCart.id, variantId: item.variantId, quantity: item.quantity },
+      });
+    }
+  }
+
+  await prisma.cartItem.deleteMany({ where: { cartId: sessionCart.id } });
+  await prisma.cart.delete({ where: { id: sessionCart.id } });
+}
+```
+
+## Example validation schema
+
+```js
+const addToCartSchema = z.object({
+  cartId: z.string().min(1),
+  variantId: z.string().min(1),
+  quantity: z.coerce.number().int().positive().default(1),
+});
+```
+
+## End result
+
+A cart where users can add, remove, and update items — with stock validation, session merging on login, and computed totals ready for checkout.

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

@@ -0,0 +1,179 @@
+---
+name: ecommerce-catalog
+description: Product catalog models and CRUD for Quark ecommerce. Use when managing products, variants, categories, or pricing.
+---
+
+# Ecommerce Catalog Skill
+
+Manage the product catalog for an ecommerce system on Quark. This sub-skill covers product, variant, and category models plus CRUD operations.
+
+## Context
+
+The catalog is the foundation of an ecommerce system. It defines what you sell, how it's organized, and how it's priced.
+
+- **Product** — the sellable item with name, description, pricing, and images.
+- **ProductVariant** — a specific option of a product (size, color, material) with its own SKU, price, and stock.
+- **Category** — hierarchical grouping for browsing and filtering.
+
+## Framework context (build on Quark)
+
+- **Models** live in `packages/db/prisma/schema.prisma`. Every model needs `id`, `createdAt DateTime @default(now())`, `updatedAt DateTime @updatedAt`. After changes: `pnpm db:generate && pnpm db:migrate`.
+- **Data access** goes through query helpers in `packages/db/src/queries.js` — never call `prisma.*` directly in pages/actions.
+- **API routes** live in `apps/web/src/app/api/<resource>/`. Guard with `requireRole`, validate with Zod via `validateBody`, wrap mutations in `withCsrfProtection`. Follow `apps/web/src/app/api/users/route.js` as the reference shape.
+- **Server Actions** use `"use server"`, Zod validation, and `AppError`/`ValidationError` from `@techstream/quark-core/errors`.
+- **Admin views** live under `apps/web/src/app/admin/products/` and `apps/web/src/app/admin/categories/`.
+
+## Models
+
+### Category
+
+```prisma
+model Category {
+  id          String    @id @default(cuid())
+  name        String
+  slug        String    @unique
+  description String?   @db.Text
+  parentId    String?
+  parent      Category? @relation("CategoryTree", fields: [parentId], references: [id])
+  children    Category[] @relation("CategoryTree")
+  products    Product[]
+  createdAt   DateTime  @default(now())
+  updatedAt   DateTime  @updatedAt
+
+  @@index([slug])
+  @@index([parentId])
+}
+```
+
+### Product
+
+```prisma
+model Product {
+  id          String          @id @default(cuid())
+  name        String
+  slug        String          @unique
+  description String?         @db.Text
+  basePrice   Decimal         @db.Decimal(10, 2)
+  currency    String          @default("USD")
+  images      String[]
+  active      Boolean         @default(true)
+  categoryId  String?
+  category    Category?       @relation(fields: [categoryId], references: [id])
+  variants    ProductVariant[]
+  createdAt   DateTime        @default(now())
+  updatedAt   DateTime        @updatedAt
+
+  @@index([slug])
+  @@index([categoryId])
+  @@index([active])
+}
+```
+
+### ProductVariant
+
+```prisma
+model ProductVariant {
+  id        String   @id @default(cuid())
+  productId String
+  product   Product  @relation(fields: [productId], references: [id], onDelete: Cascade)
+  sku       String   @unique
+  name      String   // e.g. "Large / Blue"
+  price     Decimal  @db.Decimal(10, 2)
+  stock     Int      @default(0)
+  reserved  Int      @default(0)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([productId])
+  @@index([sku])
+}
+```
+
+## Query helpers
+
+```js
+// packages/db/src/queries.js additions
+
+export async function getProductBySlug(slug) {
+  return prisma.product.findUnique({
+    where: { slug },
+    include: { category: true, variants: true },
+  });
+}
+
+export async function listActiveProducts({ categoryId, limit = 20, offset = 0 } = {}) {
+  const where = { active: true };
+  if (categoryId) where.categoryId = categoryId;
+  return prisma.product.findMany({
+    where,
+    include: { category: true, variants: true },
+    orderBy: { createdAt: "desc" },
+    take: limit,
+    skip: offset,
+  });
+}
+
+export async function getCategoryTree() {
+  return prisma.category.findMany({
+    where: { parentId: null },
+    include: { children: true, _count: { select: { products: true } } },
+  });
+}
+```
+
+## Admin CRUD actions
+
+```js
+"use server";
+import { z } from "zod";
+import { prisma } from "@__QUARK_SCOPE__/db";
+import { ValidationError, AppError } from "@techstream/quark-core/errors";
+import { createLogger } from "@techstream/quark-core";
+
+const log = createLogger("action:product");
+
+const createProductSchema = z.object({
+  name: z.string().min(1).max(255),
+  slug: z.string().min(1).regex(/^[a-z0-9-]+$/),
+  description: z.string().optional(),
+  basePrice: z.coerce.number().positive(),
+  categoryId: z.string().optional(),
+  images: z.array(z.string().url()).optional(),
+});
+
+export async function createProduct(formData) {
+  const parsed = createProductSchema.safeParse(Object.fromEntries(formData));
+  if (!parsed.success) throw new ValidationError(parsed.error.flatten());
+
+  const existing = await prisma.product.findUnique({ where: { slug: parsed.data.slug } });
+  if (existing) throw new AppError("Slug already in use", 409, "CONFLICT");
+
+  const product = await prisma.product.create({ data: parsed.data });
+  log.info("product created", { id: product.id, slug: product.slug });
+  return product;
+}
+
+const createVariantSchema = z.object({
+  productId: z.string().min(1),
+  sku: z.string().min(1).max(100),
+  name: z.string().min(1).max(200),
+  price: z.coerce.number().positive(),
+  stock: z.coerce.number().int().nonnegative(),
+});
+
+export async function createVariant(formData) {
+  const parsed = createVariantSchema.safeParse(Object.fromEntries(formData));
+  if (!parsed.success) throw new ValidationError(parsed.error.flatten());
+
+  const existing = await prisma.productVariant.findUnique({ where: { sku: parsed.data.sku } });
+  if (existing) throw new AppError("SKU already in use", 409, "CONFLICT");
+
+  const variant = await prisma.productVariant.create({ data: parsed.data });
+  log.info("variant created", { id: variant.id, sku: variant.sku });
+  return variant;
+}
+```
+
+## End result
+
+A catalog where admins can manage products, variants, and categories — with slug-based lookups, hierarchical categories, and query helpers for the storefront.