@thorprovider/storefront 0.3.1 → 0.4.0-mvp.0

package/skills/storefront-workflow/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: storefront-workflow
+description: The Thor Commerce storefront workflow model — bootstrap, compose, customize, verify — and the CLI/manifest authority. Read when working in a generated storefront, before adding/removing views or features, changing the theme, or editing storefront files.
+---
+
+# Storefront workflow model
+
+A generated storefront is defined by a **manifest** (`storefront.config.json` at
+the project root) and produced by the `storefront` CLI. The manifest is the
+structural source of truth; the CLI is the only writer of derived files; the
+developer (or agent) edits only user-owned files.
+
+Run every command from inside the project (the CLI resolves the project from the
+current directory). The CLI is installed as a dependency of the project, so
+invoke it with `npx @thorprovider/storefront <command>` or `yarn storefront`.
+
+## The four phases
+
+**bootstrap → compose → customize → verify**
+
+### 1. Bootstrap
+
+Create the project. The CLI scaffolds Next.js, installs the pinned candidate
+toolset, writes the initial manifest, and reconciles.
+
+```bash
+npx @thorprovider/storefront create <dir> --name <name> --preset <preset>
+```
+
+Authority: **CLI only.** Do not scaffold or copy templates by hand.
+
+### 2. Compose
+
+Change the structural composition. Each command validates, updates the manifest,
+and reconciles the derived files.
+
+```bash
+npx @thorprovider/storefront view add|remove <name> [--intent slot=intent] [--variant slot=Variant]
+npx @thorprovider/storefront feature add|remove <name>
+npx @thorprovider/storefront theme --mode light|dark|system
+npx @thorprovider/storefront plan --operations <file> [--out <file>] [--json]
+npx @thorprovider/storefront apply --plan <file> [--json]
+```
+
+Section composition (`section.add` / `section.remove` / `section.reorder` for
+`faq` / `cta`) goes through the same operations envelope
+(`{ "formatVersion": 1, "operations": [ ... ] }`): `plan` is read-only and
+validates the whole intended state, `apply --plan` is the only writer.
+
+Authority: **CLI only.** Agents choose *what* to compose by reading
+`views --json` / `features --json` / `recipes --json` — including each view's
+`registeredSlots` / `allowedSections` / `maxSections` and the top-level
+`sectionTypes` list — and then delegate the write to the CLI. The user states the
+change in natural language and never types a command. Held section types
+(`testimonials`, `statistics`, `logoCloud`, `pricing`) are refused with a bounded
+reason; only the executable types (`faq`, `cta`) may be composed.
+
+### 3. Customize
+
+Edit the **user-owned** files (content, props, data, local schema, mappers).
+Reconcile never rewrites them; it regenerates the thin derived wrappers around
+them.
+
+Authority: **agent/developer.** Hand-edit only user-owned files.
+
+### 4. Verify
+
+Regenerate and check.
+
+```bash
+npx @thorprovider/storefront sync     # reconcile derived files to the manifest
+npx @thorprovider/storefront doctor   # composition drift + truthful version/BOM
+```
+
+Authority: **CLI.** A build (`yarn build`) is the final acceptance; `doctor`
+must report no drift.
+
+## File ownership
+
+| Class | Examples | Who writes it |
+|---|---|---|
+| **Derived** | `views/index.ts`, `views/registry.ts`, `index.tsx`, `registry.tsx`, `catalog.ts`, `runtime.ts`, `spec/index.ts`, `state.ts`, `handlers.ts`, `features/*/adapter.ts` | CLI (reconcile); never hand-edited |
+| **User-owned** | `views/<view>/content.ts`, `props.ts`, `data.ts`, `schema.ts`, `mappers.ts` | developer/agent |
+| **External** | `app/layout.tsx`, `app/globals.css`, other create-next-app/shadcn files | create-next-app/shadcn; the CLI only appends idempotent markers |
+
+Removing a unit removes its derived wrapper but **preserves** any customized
+user-owned file and reports its location.
+
+## Manifest authority
+
+- `storefront.config.json` declares the name, theme, installed views, installed
+  features, and per-slot intents. Every structural command edits it and then
+  reconciles.
+- `.opencode/storefront.json` is the machine-managed install record (suite
+  version, declared compatibility ranges, resolved versions, lockfile hash,
+  owned asset BOM). `doctor` validates it against the live project.
+- A **legacy** (pre-manifest) project is detected and refused with a no-write
+  diagnostic; automatic migration is held post-MVP.
+
+## Curated MVP defaults
+
+- Standalone views: `home`, `category`, `product`.
+- Feature: `checkout` (owns the `checkout` view; `view add checkout` is
+  rejected — use `feature add checkout`).
+- Held post-MVP and rejected before writes: `user-panel` and recommendations.
+- Composable sections: `faq` and `cta` are executable per view; held types
+  (`testimonials`, `statistics`, `logoCloud`, `pricing`) are refused with a
+  bounded reason.
+
+## Pinning and prerequisites
+
+- Node `>=20.9.0`, Yarn 4, `node-modules` linker. The generated project pins the
+  exact candidate toolset; `doctor` reports a linker/version mismatch non-zero.
+- The `checkout` feature ships structural wiring only; the purchase flow is
+  owned by the separate `single-tenant-commerce-mvp` change. A generated
+  storefront is not a complete commerce implementation on its own.

package/skills/sf-view-gen/assets/templates/views/category/index.tsx

@@ -1,86 +0,0 @@
-// Thor Commerce view module: category
-// Server Component module: elements + catalog entries + route + loader only.
-// The client-side component mappings live in ./registry.tsx ('use client'); this
-// module imports them as data so the RSC graph never evaluates @json-render/react
-// on the server. Registered by importing it in ../index.ts. Recipe: recipes.json -> "category".
-
-import {
-  getCatalog,
-  getCategoryProductsByHandleWithSource,
-} from '@thorprovider/runtime/commerce'
-import { z } from 'zod'
-import { pageRoot } from '../../spec/page-root'
-import type { StorefrontElement } from '../../spec/types'
-import type { ViewModule } from '../types'
-import { registry } from './registry'
-
-const elements: Record<string, StorefrontElement> = {
-  'category.filter': {
-    type: 'CategoryFilter',
-    props: {
-      products: { $state: '/categoryProducts' },
-      sortOptions: [
-        { value: 'newest', label: 'Más recientes' },
-        { value: 'price-asc', label: 'Precio: de menor a mayor' },
-        { value: 'price-desc', label: 'Precio: de mayor a menor' },
-      ],
-    },
-    on: {
-      openProduct: { action: 'openProduct' },
-      applyFilters: { action: 'applyFilters' },
-    },
-  },
-  'category.grid': {
-    type: 'ProductCard',
-    props: {
-      heading: 'Productos',
-      products: { $state: '/categoryProducts' },
-    },
-    on: {
-      addToCart: { action: 'addToCart' },
-      openProduct: { action: 'openProduct' },
-    },
-  },
-}
-
-const catalog = {
-  CategoryFilter: {
-    props: z.object({
-      products: z.array(z.record(z.string(), z.unknown())),
-      sortOptions: z
-        .array(z.object({ value: z.string(), label: z.string() }))
-        .optional(),
-      categories: z.array(z.record(z.string(), z.unknown())).optional(),
-      pagination: z.array(z.union([z.number(), z.string()])).optional(),
-    }),
-    description: 'Product listing filters, sorting, and results.',
-  },
-}
-
-export const category: ViewModule = {
-  name: 'category',
-  elements,
-  catalog,
-  registry,
-  route: {
-    path: '/categorias/[[...slug]]',
-    loaderName: 'category',
-    layout: 'default',
-    metadata: {
-      title: 'Categoría',
-      description: 'Explora los productos de esta categoría en __SITE_NAME__.',
-    },
-    entry: pageRoot('category', ['category.filter', 'category.grid'], elements),
-  },
-  loader: {
-    category: async (params) => {
-      const slug = Array.isArray(params.slug) ? params.slug[0] : params.slug
-      const { products, categories } = await getCatalog()
-      const categoryResult = slug
-        ? await getCategoryProductsByHandleWithSource(slug)
-        : null
-      const categoryProducts = categoryResult ? categoryResult.products : products
-      return { categoryProducts, storeCategories: categories }
-    },
-  },
-}

package/skills/sf-view-gen/assets/templates/views/category/registry.tsx

@@ -1,48 +0,0 @@
-'use client'
-
-// Thor Commerce view registry fragment: category
-// Client boundary for the category view. Imports value bindings from
-// @json-render/react and components from @thorprovider/blocks — both must stay
-// on the client side of the RSC graph. Kept separate from index.tsx so the view
-// spec (elements/catalog/route/loader) stays a pure Server Component module.
-
-import { CategoryFilter2 as CategoryFilterBlock } from '@thorprovider/blocks'
-import type { CardProduct, CategoryFilter2Filters, FilterProduct } from '@thorprovider/blocks'
-import { useStateStore } from '@json-render/react'
-import type { ViewRegistry } from '../types'
-
-export const registry: ViewRegistry = {
-  CategoryFilter: ({ props, emit }) => {
-    const { set } = useStateStore()
-    const products: FilterProduct[] = ((props.products ?? []) as CardProduct[]).map(
-      (p) => ({
-        id: String(p.id),
-        name: p.title,
-        price: `$${p.price.toFixed(2)}`,
-        image: p.image,
-      }),
-    )
-    return (
-      <CategoryFilterBlock
-        products={products}
-        sortOptions={props.sortOptions as never}
-        categories={props.categories as never}
-        pagination={props.pagination as never}
-        onProductClick={(product) => {
-          set('/lastClicked', product)
-          emit('openProduct')
-        }}
-        onPageChange={(page) => {
-          set('/categoryPage', page)
-        }}
-        onSortChange={(sort) => {
-          set('/categorySort', sort)
-        }}
-        onFilterChange={(filters: CategoryFilter2Filters) => {
-          set('/filters', filters)
-          emit('applyFilters')
-        }}
-      />
-    )
-  },
-}

package/skills/sf-view-gen/assets/templates/views/checkout/index.tsx

@@ -1,192 +0,0 @@
-// Thor Commerce view module: checkout
-// Server Component module: elements + catalog entries + route + loader only.
-// The client-side component mappings live in ./registry.tsx ('use client'); this
-// module imports them as data so the RSC graph never evaluates @json-render/react
-// on the server. Registered by importing it in ../index.ts. Recipe: recipes.json -> "checkout".
-
-import {
-  getPaymentMethodsByRegion,
-  getRegionCountries,
-} from '@thorprovider/runtime/commerce'
-import { z } from 'zod'
-import { pageRoot } from '../../spec/page-root'
-import type { StorefrontElement } from '../../spec/types'
-import type { ViewModule } from '../types'
-import { registry } from './registry'
-
-const elements: Record<string, StorefrontElement> = {
-  'checkout.view': {
-    type: 'Checkout',
-    visible: { $state: '/lastOrder', not: true },
-    props: {
-      title: 'Finalizar compra',
-      description: 'Completa tus datos para recibir tu pedido.',
-      orderSummary: {
-        items: { $state: '/cart' },
-        shipping: { $state: '/cartTotals/shipping' },
-        tax: { $state: '/cartTotals/tax' },
-        discount: { $state: '/cartTotals/discount' },
-        promoDiscount: { $state: '/cartTotals/promoDiscount' },
-      },
-      countries: { $state: '/checkoutCountries' },
-      paymentMethods: { $state: '/checkoutPaymentMethods' },
-      values: {
-        email: { $state: '/checkout/email' },
-        firstName: { $state: '/checkout/firstName' },
-        lastName: { $state: '/checkout/lastName' },
-        phone: { $state: '/checkout/phone' },
-        address: { $state: '/checkout/address' },
-        city: { $state: '/checkout/city' },
-        state: { $state: '/checkout/state' },
-        zipCode: { $state: '/checkout/zipCode' },
-        country: { $state: '/checkout/country' },
-        paymentMethod: { $state: '/checkout/paymentMethod' },
-        cardNumber: { $state: '/checkout/cardNumber' },
-        expiryDate: { $state: '/checkout/expiryDate' },
-        cvv: { $state: '/checkout/cvv' },
-        cardName: { $state: '/checkout/cardName' },
-        saveInfo: { $state: '/checkout/saveInfo' },
-        sameAsBilling: { $state: '/checkout/sameAsBilling' },
-        newsletter: { $state: '/checkout/newsletter' },
-        promoCode: { $state: '/checkout/promoCode' },
-      },
-      validation: {
-        email: {
-          validateOn: 'blur',
-          checks: [
-            { type: 'required', message: 'Ingresa tu correo electrónico.' },
-            { type: 'email', message: 'Ingresa un correo válido.' },
-          ],
-        },
-        firstName: {
-          checks: [{ type: 'required', message: 'Ingresa tu nombre.' }],
-        },
-        lastName: {
-          checks: [{ type: 'required', message: 'Ingresa tus apellidos.' }],
-        },
-        phone: {
-          checks: [
-            {
-              type: 'pattern',
-              args: { pattern: '^[+]?[0-9]{7,15}$' },
-              message: 'Ingresa un teléfono válido.',
-            },
-          ],
-        },
-        address: {
-          checks: [{ type: 'required', message: 'Ingresa tu dirección.' }],
-        },
-        city: {
-          checks: [{ type: 'required', message: 'Ingresa la ciudad.' }],
-        },
-        state: {
-          checks: [{ type: 'required', message: 'Ingresa la provincia.' }],
-        },
-        country: {
-          checks: [{ type: 'required', message: 'Selecciona tu país.' }],
-        },
-        zipCode: {
-          checks: [
-            { type: 'required', message: 'Ingresa el código postal.' },
-            {
-              type: 'pattern',
-              args: { pattern: '^[0-9]{4,5}$' },
-              message: 'Código postal inválido.',
-            },
-          ],
-        },
-        paymentMethod: {
-          checks: [{ type: 'required', message: 'Selecciona un método de pago.' }],
-        },
-      },
-      fieldDescriptions: {
-        email: 'Usaremos este correo para el seguimiento del pedido.',
-        phone: 'Te contactaremos para coordinar la entrega.',
-        promoCode: 'Aplica códigos promocionales válidos.',
-      },
-    },
-    on: { placeOrder: { action: 'placeOrder' } },
-  },
-  'checkout.confirmation': {
-    type: 'CheckoutConfirmation',
-    visible: { $state: '/lastOrder' },
-    props: {
-      order: { $state: '/lastOrder' },
-      orderLines: { $state: '/lastOrderLines' },
-      fulfilmentDetails: {
-        Confirmed: {
-          stage: 'Confirmed',
-          summary: 'Pago autorizado y el pedido fue enviado a preparación.',
-          location: 'Centro de distribución',
-          at: { $state: '/orderPlaced' },
-        },
-        Packed: {
-          stage: 'Packed',
-          summary: 'Los artículos fueron seleccionados y empacados.',
-          location: 'Centro de distribución',
-          at: null,
-        },
-        Shipped: {
-          stage: 'Shipped',
-          summary: 'El paquete fue entregado al transportista.',
-          location: 'En tránsito',
-          at: null,
-        },
-        Delivered: {
-          stage: 'Delivered',
-          summary: 'Entregado en tu dirección.',
-          location: 'Tu dirección',
-          at: null,
-        },
-      },
-    },
-    on: { continueShopping: { action: 'continueShopping' } },
-  },
-}
-
-const catalog = {
-  Checkout: {
-    props: z.record(z.string(), z.unknown()),
-    description: 'Checkout form with order summary, shipping and payment steps.',
-  },
-  CheckoutConfirmation: {
-    props: z.record(z.string(), z.unknown()),
-    description: 'Order confirmation with fulfilment progress.',
-  },
-}
-
-export const checkout: ViewModule = {
-  name: 'checkout',
-  elements,
-  catalog,
-  registry,
-  route: {
-    path: '/checkout',
-    loaderName: 'checkout',
-    layout: 'default',
-    metadata: {
-      title: 'Finalizar compra',
-      description: 'Completa tus datos de envío y pago para recibir tu pedido.',
-    },
-    entry: pageRoot(
-      'checkout',
-      ['checkout.view', 'checkout.confirmation'],
-      elements,
-    ),
-  },
-  loader: {
-    checkout: async () => {
-      const [countries, paymentMethods] = await Promise.all([
-        getRegionCountries(),
-        getPaymentMethodsByRegion(),
-      ])
-      return {
-        checkoutCountries: countries.map((country) => ({
-          value: country.code,
-          label: country.name,
-        })),
-        checkoutPaymentMethods: paymentMethods,
-      }
-    },
-  },
-}

package/skills/sf-view-gen/assets/templates/views/checkout/registry.tsx

@@ -1,45 +0,0 @@
-'use client'
-
-// Thor Commerce view registry fragment: checkout
-// Client boundary for the checkout view. Imports value bindings from
-// @json-render/react and components from @thorprovider/blocks — both must stay
-// on the client side of the RSC graph. Kept separate from index.tsx so the view
-// spec (elements/catalog/route/loader) stays a pure Server Component module.
-
-import {
-  CheckoutForm1 as CheckoutBlock,
-  CheckoutConfirmation as CheckoutConfirmationBlock,
-} from '@thorprovider/blocks'
-import { useStateStore } from '@json-render/react'
-import type { ViewRegistry } from '../types'
-
-export const registry: ViewRegistry = {
-  Checkout: ({ props, emit }) => {
-    const { state, set } = useStateStore()
-    return (
-      <CheckoutBlock
-        title={props.title as string}
-        description={props.description as string}
-        orderSummary={props.orderSummary as never}
-        countries={props.countries as never}
-        paymentMethods={props.paymentMethods as never}
-        values={props.values as never}
-        fieldDescriptions={props.fieldDescriptions as never}
-        onChange={(field, value) => set(`/checkout/${field}`, value)}
-        onSubmit={() => emit('placeOrder')}
-        submitting={Boolean(state.checkoutPending)}
-        submitError={(state.checkoutError as string | null) ?? undefined}
-      />
-    )
-  },
-  CheckoutConfirmation: ({ props, emit }) =>
-    props.order ? (
-      <CheckoutConfirmationBlock
-        order={props.order as never}
-        orderLines={props.orderLines as never}
-        fulfilmentDetails={props.fulfilmentDetails as never}
-        continueShoppingHref="#"
-        onContinueShopping={() => emit('continueShopping')}
-      />
-    ) : null,
-}

package/skills/sf-view-gen/assets/templates/views/product/index.tsx

@@ -1,122 +0,0 @@
-// Thor Commerce view module: product
-// Server Component module: elements + catalog entries + route + loader only.
-// The client-side component mappings live in ./registry.tsx ('use client'); this
-// module imports them as data so the RSC graph never evaluates @json-render/react
-// on the server. Registered by importing it in ../index.ts. Recipe: recipes.json -> "product".
-
-import { getProductByHandle } from '@thorprovider/runtime/commerce'
-import { z } from 'zod'
-import { pageRoot } from '../../spec/page-root'
-import type { StorefrontElement } from '../../spec/types'
-import type { ViewModule } from '../types'
-import { registry } from './registry'
-
-const elements: Record<string, StorefrontElement> = {
-  'product.overview': {
-    type: 'ProductOverview',
-    props: {
-      product: { $state: '/selectedProduct' },
-    },
-    on: { addToCart: { action: 'addToCart' } },
-  },
-  'product.reviews': {
-    type: 'Reviews',
-    props: {
-      pageTitle: 'Opiniones de clientes',
-      pageDescription: 'Lo que dicen quienes ya compraron este producto.',
-      reviews: [
-        {
-          id: 1,
-          userName: 'Carlos M.',
-          date: '2026-07-12',
-          rating: 5,
-          content: 'Excelente calidad y llegó antes de lo esperado. Muy buena compra.',
-          likes: 12,
-          comments: 2,
-        },
-        {
-          id: 2,
-          userName: 'Ana R.',
-          date: '2026-07-03',
-          rating: 4,
-          content: 'Funciona muy bien y la atención fue rápida. Lo recomiendo.',
-          likes: 7,
-          comments: 1,
-        },
-        {
-          id: 3,
-          userName: 'Luis P.',
-          date: '2026-06-28',
-          rating: 5,
-          content: 'Producto robusto, tal como aparece en la descripción.',
-          likes: 5,
-          comments: 0,
-        },
-      ],
-      form: {
-        title: 'Deja tu opinión',
-        description: 'Tu experiencia ayuda a otros clientes.',
-        nameLabel: 'Nombre',
-        emailLabel: 'Correo electrónico',
-        reviewLabel: 'Tu reseña',
-        namePlaceholder: 'Tu nombre',
-        emailPlaceholder: 'tucorreo@ejemplo.cu',
-        reviewPlaceholder: 'Cuéntanos tu experiencia...',
-        submitButtonText: 'Publicar reseña',
-        submittingButtonText: 'Publicando...',
-      },
-      reviewsPerPage: 3,
-    },
-    on: {
-      submitReview: { action: 'submitReview' },
-      toggleReviewLike: { action: 'toggleReviewLike' },
-    },
-  },
-}
-
-const catalog = {
-  ProductOverview: {
-    props: z.object({
-      product: z.record(z.string(), z.unknown()),
-      sizesLabel: z.string().optional(),
-      colorLabel: z.string().optional(),
-      reviewsLabel: z.string().optional(),
-      addToCartLabel: z.string().optional(),
-    }),
-    description: 'Detalle de producto: galería, precio, variantes y añadir al carrito.',
-  },
-  Reviews: {
-    props: z.object({
-      pageTitle: z.string().optional(),
-      pageDescription: z.string().optional(),
-      reviews: z.array(z.record(z.string(), z.unknown())),
-      form: z.record(z.string(), z.unknown()).optional(),
-      reviewsPerPage: z.number().optional(),
-    }),
-    description: 'Opiniones de clientes con resumen de valoración.',
-  },
-}
-
-export const product: ViewModule = {
-  name: 'product',
-  elements,
-  catalog,
-  registry,
-  route: {
-    path: '/productos/[id]',
-    loaderName: 'product',
-    layout: 'default',
-    metadata: {
-      title: 'Producto',
-      description: 'Detalles del producto seleccionado.',
-    },
-    entry: pageRoot('product', ['product.overview', 'product.reviews'], elements),
-  },
-  loader: {
-    product: async (params) => {
-      const id = Array.isArray(params.id) ? params.id[0] : params.id
-      const selectedProduct = await getProductByHandle(String(id))
-      return { selectedProduct }
-    },
-  },
-}

package/skills/sf-view-gen/assets/templates/views/product/registry.tsx

@@ -1,49 +0,0 @@
-'use client'
-
-// Thor Commerce view registry fragment: product
-// Client boundary for the product view. Imports value bindings from
-// @json-render/react and components from @thorprovider/blocks — both must stay
-// on the client side of the RSC graph. Kept separate from index.tsx so the view
-// spec (elements/catalog/route/loader) stays a pure Server Component module.
-
-import {
-  ProductOverview1 as ProductOverviewBlock,
-  ReviewRating1 as ReviewsBlock,
-} from '@thorprovider/blocks'
-import { useStateStore } from '@json-render/react'
-import type { ViewRegistry } from '../types'
-
-export const registry: ViewRegistry = {
-  ProductOverview: ({ props, emit }) => {
-    const { set } = useStateStore()
-    return (
-      <ProductOverviewBlock
-        product={props.product as never}
-        onAddToCart={(product) => {
-          set('/lastClicked', product)
-          emit('addToCart')
-        }}
-        onToggleWishlist={() => {}}
-      />
-    )
-  },
-  Reviews: ({ props, emit }) => {
-    const { set } = useStateStore()
-    return (
-      <ReviewsBlock
-        pageTitle={props.pageTitle as string}
-        pageDescription={props.pageDescription as string}
-        reviews={props.reviews as never}
-        form={props.form as never}
-        reviewsPerPage={props.reviewsPerPage as number}
-        onToggleReviewLike={() => {
-          emit('toggleReviewLike')
-        }}
-        onSubmitReview={(data) => {
-          set('/lastReview', data)
-          emit('submitReview')
-        }}
-      />
-    )
-  },
-}