@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/examples/merchandising/category-led.json

@@ -0,0 +1,37 @@
+{
+  "name": "category-led",
+  "title": "Category-led combined presentation plus freshness selection",
+  "intent": "Lead with a category-focused combined grid-and-carousel of the newest arrivals, keep category navigation visible, and cross-sell a related category below. Selection (category handle and ordering) is independent of the presentation variant.",
+  "sections": [
+    { "id": "slot:hero", "type": "hero", "variant": "StorefrontHero1" },
+    { "id": "slot:benefits", "type": "benefits", "variant": "Feature1" },
+    { "id": "slot:categories", "type": "categories", "variant": "ProductCategory2" },
+    {
+      "id": "home-products-1",
+      "type": "products",
+      "variant": "ProductShowcase1",
+      "objective": "Showcase the newest arrivals in a category as a browsable carousel",
+      "destination": "/categories/repuestos",
+      "source": {
+        "kind": "products",
+        "query": { "categories": ["repuestos"], "sort": "newest", "pageSize": 12 }
+      },
+      "content": {
+        "heading": "Novedades en repuestos",
+        "description": "Lo último que llega a la categoría."
+      }
+    },
+    {
+      "id": "home-products-2",
+      "type": "products",
+      "variant": "ProductCard1",
+      "objective": "Cross-sell a related category below the carousel",
+      "destination": "/categories/accesorios",
+      "source": {
+        "kind": "products",
+        "query": { "categories": ["accesorios"], "sort": "featured", "pageSize": 4 }
+      },
+      "content": { "heading": "Accesorios recomendados" }
+    }
+  ]
+}

package/examples/merchandising/collection-led.json

@@ -0,0 +1,37 @@
+{
+  "name": "collection-led",
+  "title": "Collection-led grid plus campaign CTA",
+  "intent": "Lead the home with one curated collection as the primary merchandise grid, and reinforce it with a single campaign call to action. The selection is a collection handle, not a sales ranking.",
+  "sections": [
+    { "id": "slot:hero", "type": "hero", "variant": "StorefrontHero1" },
+    { "id": "slot:benefits", "type": "benefits", "variant": "Feature1" },
+    {
+      "id": "home-products-1",
+      "type": "products",
+      "variant": "ProductCard1",
+      "objective": "Move collection browsers into the featured collection",
+      "destination": "/collections/featured",
+      "source": {
+        "kind": "products",
+        "query": { "collections": ["featured"], "sort": "featured", "pageSize": 8 }
+      },
+      "content": {
+        "heading": "Destacados de la temporada",
+        "description": "Una selección curada de la colección destacada."
+      }
+    },
+    {
+      "id": "home-cta-1",
+      "type": "cta",
+      "objective": "Reinforce the campaign message with one clear action",
+      "destination": "/collections/featured",
+      "content": {
+        "badgeText": "Campaña",
+        "title": "Envío gratis esta semana",
+        "description": "En pedidos superiores al mínimo de la campaña.",
+        "primaryCta": { "label": "Ver la colección", "href": "/collections/featured" }
+      }
+    },
+    { "id": "slot:categories", "type": "categories", "variant": "ProductCategory2" }
+  ]
+}

package/package.json

@@ -1,26 +1,30 @@
 {
   "name": "@thorprovider/storefront",
-  "version": "0.3.1",
-  "description": "Deterministic storefront scaffolder and installable OpenCode command suite for Thor Commerce (Next.js, @thorprovider/blocks, @thorprovider/adapters, Medusa)",
+  "version": "0.4.0-mvp.2",
+  "description": "Deterministic storefront scaffolder and installable OpenCode skill suite for Thor Commerce (Next.js, @thorprovider/blocks, @thorprovider/adapters, Medusa)",
   "type": "module",
-  "bin": "./bin/storefront.js",
+  "bin": {
+    "storefront": "bin/storefront.js"
+  },
   "files": [
     "assets",
     "bin",
-    "commands",
+    "examples",
     "skills",
     "recipes",
     "scripts",
-    "README.md"
+    "README.md",
+    "VENDOR.md"
   ],
   "engines": {
-    "node": ">=18.17.0"
+    "node": ">=20.9.0"
   },
   "scripts": {
     "sync-assets": "node ./scripts/sync-assets.mjs",
     "check-assets": "node ./scripts/sync-assets.mjs --check",
     "pretest": "node ./scripts/sync-assets.mjs --check",
-    "test": "vitest run --config vitest.config.ts"
+    "test": "vitest run --config vitest.config.ts",
+    "test:integration": "vitest run --config vitest.config.ts tests/scaffold-integration.test.ts tests/starter-integration.test.ts"
   },
   "publishConfig": {
     "access": "public",
@@ -39,10 +43,12 @@
     "scaffolding"
   ],
   "dependencies": {
-    "@clack/prompts": "^1.8.1"
+    "@clack/prompts": "^1.8.1",
+    "@fission-ai/openspec": "1.11.0",
+    "semver": "^7.7.4"
   },
   "devDependencies": {
     "vitest": "^3.2.4"
   },
   "license": "MIT"
-}
+}

package/recipes/archetypes.json

@@ -4,7 +4,7 @@
   "description": "Archetype (intent) layer. Maps a slot to named intents so selection is by meaning, not by variant ordinal. Each intent resolves to a variant that MUST be allowed by the recipe for that slot.",
   "slots": {
     "home.hero": {
-      "default": "showcase",
+      "default": "compact",
       "intents": {
         "compact": {
           "variant": "StorefrontHero1",
@@ -88,6 +88,15 @@
         }
       }
     },
+    "cart.view": {
+      "default": "review",
+      "intents": {
+        "review": {
+          "variant": "ShoppingCart4",
+          "when": "A standalone cart review page: line editing plus backend-authoritative totals before checkout."
+        }
+      }
+    },
     "category.filter": {
       "default": "sidebar",
       "intents": {
@@ -122,25 +131,30 @@
         }
       }
     },
-    "user-panel.shell": {
-      "default": "standard",
+    "account.login": {
+      "default": "signIn",
       "intents": {
-        "standard": {
-          "variant": "AppShell1",
-          "when": "A standard account shell with side navigation and content area."
+        "signIn": {
+          "variant": "LoginPage1",
+          "when": "A full sign-in page with email and password and a link to create an account."
         }
       }
     },
-    "user-panel.orderHistory": {
-      "default": "compact",
+    "account.register": {
+      "default": "signUp",
       "intents": {
-        "compact": {
-          "variant": "OrderHistory1",
-          "when": "A concise list of past orders with status and totals."
-        },
-        "detailed": {
+        "signUp": {
+          "variant": "SignUpPage1",
+          "when": "A full registration page with name, email, and password and a link to sign in."
+        }
+      }
+    },
+    "account.orders": {
+      "default": "viewOrders",
+      "intents": {
+        "viewOrders": {
           "variant": "OrderHistory2",
-          "when": "Order history with line-item detail, tracking, and reorder actions."
+          "when": "A signed-in shopper's order history with per-order totals and detail on demand."
         }
       }
     }

package/recipes/catalog.json

@@ -0,0 +1,400 @@
+{
+  "$schema": "./catalog.schema.json",
+  "catalogVersion": 1,
+  "description": "Initial semantic executable catalog (E1 tasks 1.2-1.3), classified by source-shape inspection of the @thorprovider/blocks prop contracts and the view templates. Scope: every slot the curated MVP views (home, product, category, checkout, account) render by default, covering both the selectable archetype slots declared by recipes/archetypes.json and the nested default slots that have no archetype (category.productCard, checkout.confirmation) so no legacy default support is dropped. The account view (change: storefront-customer-auth) declares the login/register slots: LoginPage1/SignUpPage1 are executable while LoginPage2 is held for its divergent callback contract. A variant is `executable` only when the slot's canonical data shape can feed its block props without a prop bridge and without inventing data; every other non-default variant is `held` with the specific reason. The one executable non-default swap is home.benefits Feature1 -> Feature2 (identical item contract, no bridge). E2 task 6.1 declares the base listing slot category.filter CategoryFilter2 as the single controlled listing (dataShape `CatalogQuery & CatalogResults`, state controlled) with the search/filter controls contributed by the logical mounts category.search / category.filters (no second block). Source-shape compatibility is not end-to-end backend behavior proof: the render is executable, but the category.search.apply / category.filter.apply actions remain held under the capability catalog (owner: storefront-catalog-search-filters, E2) until a real runtime proof. The `capabilities` map declares those operational capabilities with their requirements and verification state; E1 declares the held category.filter.apply action, E2 adds the held category.search.apply action and the held category.price.range capability that gates the category-filters showPrice option; no capability is claimed verified.",
+  "slots": {
+    "home.hero": {
+      "default": "StorefrontHero1",
+      "variants": {
+        "StorefrontHero1": {
+          "status": "executable",
+          "block": "StorefrontHero",
+          "dataShape": "FeaturedProduct[]",
+          "events": ["addToCart", "buyNow", "selectColor"],
+          "state": "uncontrolled",
+          "requirements": ["heroProducts"]
+        },
+        "StorefrontHero2": {
+          "status": "held",
+          "reason": "block requires a product with reviews/trending/tag and emits a search event; the canonical FeaturedProduct shape carries rating/reviewCount but not trending/tag, and no verified prop bridge exists",
+          "block": "StorefrontHero",
+          "dataShape": "StorefrontHero2FeaturedProduct[]",
+          "events": ["search", "productClick"],
+          "state": "uncontrolled",
+          "requirements": ["heroProducts"]
+        },
+        "StorefrontHero5": {
+          "status": "held",
+          "reason": "featuredDeals[].description is absent from the canonical product shape and Department.count would require inventing counts; no truthful prop bridge can be derived from source",
+          "block": "StorefrontHero",
+          "dataShape": "FeaturedDeal[] & Department[]",
+          "events": ["departmentClick", "shopNow", "locateStores"],
+          "state": "uncontrolled",
+          "requirements": ["featuredDeals", "departments"]
+        },
+        "StorefrontHero6": {
+          "status": "held",
+          "reason": "block requires deals with discount/endTime and categories with a required count; the canonical shape supplies neither without invention and no verified prop bridge exists",
+          "block": "StorefrontHero",
+          "dataShape": "HeroDeal[] & HeroCategory[]",
+          "events": ["shopNow", "categoryClick"],
+          "state": "uncontrolled",
+          "requirements": ["deals", "categories"]
+        }
+      }
+    },
+    "home.benefits": {
+      "default": "Feature1",
+      "variants": {
+        "Feature1": {
+          "status": "executable",
+          "block": "Feature",
+          "dataShape": "BenefitsItem[]",
+          "events": ["ctaClick", "learnMore"],
+          "state": "uncontrolled",
+          "requirements": []
+        },
+        "Feature2": {
+          "status": "executable",
+          "block": "Feature",
+          "dataShape": "BenefitsItem[]",
+          "events": [],
+          "state": "uncontrolled",
+          "requirements": []
+        }
+      }
+    },
+    "home.categories": {
+      "default": "ProductCategory2",
+      "variants": {
+        "ProductCategory2": {
+          "status": "executable",
+          "block": "CategoryCards",
+          "dataShape": "CategoryCard[]",
+          "events": ["browse"],
+          "state": "uncontrolled",
+          "requirements": ["categories"]
+        },
+        "ProductCategory1": {
+          "status": "held",
+          "reason": "block requires categories with a subtitle and a named icon, which the canonical CategoryCard shape does not supply; no verified prop bridge exists",
+          "block": "CategoryCards",
+          "dataShape": "ProductCategory1Category[]",
+          "events": [],
+          "state": "uncontrolled",
+          "requirements": ["categories"]
+        },
+        "ProductCategory4": {
+          "status": "held",
+          "reason": "block requires categories with title/icon/customers/products/avatarImages, which the canonical CategoryCard shape does not supply; no verified prop bridge exists",
+          "block": "CategoryCards",
+          "dataShape": "ProductCategory4Category[]",
+          "events": ["categoryClick"],
+          "state": "uncontrolled",
+          "requirements": ["categories"]
+        },
+        "ProductCategory5": {
+          "status": "held",
+          "reason": "block requires categories with subcategories and a required itemCount plus a search control, which the canonical CategoryCard shape does not supply; no verified prop bridge exists",
+          "block": "CategoryCards",
+          "dataShape": "ProductCategory5Category[]",
+          "events": ["browse", "viewAll"],
+          "state": "uncontrolled",
+          "requirements": ["categories"]
+        }
+      }
+    },
+    "product.overview": {
+      "default": "ProductOverview1",
+      "variants": {
+        "ProductOverview1": {
+          "status": "executable",
+          "block": "ProductOverview",
+          "dataShape": "ProductDetailProduct",
+          "events": ["selectVariant", "quantityChange", "addToCart", "toggleWishlist"],
+          "state": "controlled",
+          "requirements": ["selectedProduct", "selectedVariantId"]
+        },
+        "ProductOverview2": {
+          "status": "held",
+          "reason": "block requires a product with brand/sku/sizes/colors and wishlist events, a shape the canonical ProductDetailProduct does not supply; no verified prop bridge exists",
+          "block": "ProductOverview",
+          "dataShape": "ProductOverview2Product",
+          "events": ["addToCart", "toggleWishlist"],
+          "state": "uncontrolled",
+          "requirements": ["selectedProduct"]
+        },
+        "ProductOverview5": {
+          "status": "held",
+          "reason": "block requires specifications/features/mainImages/galleryImages/userReviews, a shape the canonical ProductDetailProduct does not supply; no verified prop bridge exists",
+          "block": "ProductOverview",
+          "dataShape": "ProductOverview5Product",
+          "events": ["addToCart", "toggleWishlist"],
+          "state": "uncontrolled",
+          "requirements": ["selectedProduct"]
+        }
+      }
+    },
+    "product.reviews": {
+      "default": "ReviewRating1",
+      "variants": {
+        "ReviewRating1": {
+          "status": "executable",
+          "block": "Reviews",
+          "dataShape": "Review[]",
+          "events": ["toggleReviewLike", "submitReview"],
+          "state": "uncontrolled",
+          "requirements": ["productReviews"]
+        },
+        "ReviewRating2": {
+          "status": "held",
+          "reason": "block requires an aggregate averageRating/ratingDistribution and carousel controls the canonical Review[] shape does not supply; no verified prop bridge exists",
+          "block": "Reviews",
+          "dataShape": "Review[] & RatingSummary",
+          "events": ["like", "comment"],
+          "state": "uncontrolled",
+          "requirements": ["productReviews"]
+        }
+      }
+    },
+    "product.breadcrumb": {
+      "default": "Breadcrumb",
+      "variants": {
+        "Breadcrumb": {
+          "status": "executable",
+          "block": "Breadcrumb",
+          "dataShape": "BreadcrumbItemData[]",
+          "events": [],
+          "state": "uncontrolled",
+          "requirements": ["productBreadcrumb"]
+        }
+      }
+    },
+    "cart.view": {
+      "default": "ShoppingCart4",
+      "variants": {
+        "ShoppingCart4": {
+          "status": "executable",
+          "block": "ShoppingCart4",
+          "dataShape": "CartLineState[] & CartTotalsState",
+          "events": ["refreshCart", "updateQuantity", "removeFromCart", "checkout", "continueShopping"],
+          "state": "controlled",
+          "requirements": ["cart", "cartTotals"]
+        }
+      }
+    },
+    "category.filter": {
+      "default": "CategoryFilter2",
+      "variants": {
+        "CategoryFilter2": {
+          "status": "executable",
+          "block": "CategoryFilter",
+          "dataShape": "CatalogQuery & CatalogResults",
+          "events": [
+            "productClick",
+            "pageChange",
+            "pageSizeChange",
+            "sortChange",
+            "filterChange",
+            "searchChange",
+            "clearFilters",
+            "repair",
+            "retry",
+            "removeFilter"
+          ],
+          "state": "controlled",
+          "requirements": ["categoryProducts", "categoryQuery", "facetSupport"]
+        },
+        "CategoryFilter1": {
+          "status": "held",
+          "reason": "block requires categories/priceRanges/sortOptions with counts the canonical CardProduct[] listing does not supply; no verified prop bridge exists",
+          "block": "CategoryFilter",
+          "dataShape": "CategoryFilter1Filters",
+          "events": ["filterChange"],
+          "state": "uncontrolled",
+          "requirements": ["categoryProducts"]
+        },
+        "CategoryFilter4": {
+          "status": "held",
+          "reason": "block requires an advanced facets contract (modelTypes/rangeBands/frameSizes/colourways/features) the canonical listing does not supply; no verified prop bridge exists",
+          "block": "CategoryFilter",
+          "dataShape": "CategoryFilter4Facets",
+          "events": ["filterChange"],
+          "state": "uncontrolled",
+          "requirements": ["categoryProducts"]
+        }
+      }
+    },
+    "category.productCard": {
+      "default": "ProductCard1",
+      "variants": {
+        "ProductCard1": {
+          "status": "executable",
+          "block": "ProductCard",
+          "dataShape": "CardProduct[]",
+          "events": ["addToCart", "openProduct"],
+          "state": "uncontrolled",
+          "requirements": ["categoryProducts"]
+        },
+        "ProductCard2": {
+          "status": "held",
+          "reason": "block requires a product with a required rating, a shape the canonical CardProduct listing does not supply; no verified prop bridge exists",
+          "block": "ProductCard",
+          "dataShape": "ProductCard2Product[]",
+          "events": [],
+          "state": "uncontrolled",
+          "requirements": ["categoryProducts"]
+        },
+        "ProductCard3": {
+          "status": "held",
+          "reason": "block requires a product with subtitle/originalPrice/reviewCount/discountPercentage and a badge, a shape the canonical CardProduct listing does not supply; no verified prop bridge exists",
+          "block": "ProductCard",
+          "dataShape": "ProductCard3Product[]",
+          "events": ["toggleWishlist", "viewSimilar", "productClick"],
+          "state": "controlled",
+          "requirements": ["categoryProducts"]
+        },
+        "ProductCard5": {
+          "status": "held",
+          "reason": "block requires a product with name/category/stock/specifications/brand, a shape the canonical CardProduct listing does not supply; no verified prop bridge exists",
+          "block": "ProductCard",
+          "dataShape": "ProductCard5Product[]",
+          "events": ["toggleWishlist", "addToCart", "quickView", "compare", "export"],
+          "state": "controlled",
+          "requirements": ["categoryProducts"]
+        }
+      }
+    },
+    "checkout.checkout": {
+      "default": "CheckoutForm1",
+      "variants": {
+        "CheckoutForm1": {
+          "status": "executable",
+          "block": "Checkout",
+          "dataShape": "CheckoutForm1FormData",
+          "events": ["retryTotals", "selectShippingOption", "applyPromo", "submit"],
+          "state": "controlled",
+          "requirements": ["checkoutCountries", "checkoutPaymentMethods"]
+        },
+        "CheckoutForm2": {
+          "status": "held",
+          "reason": "unproven checkout variant: E1 keeps only the default CheckoutForm1, whose behavior is unchanged; no verified prop bridge exists",
+          "block": "Checkout",
+          "dataShape": "CheckoutForm2Data",
+          "events": ["submit"],
+          "state": "controlled",
+          "requirements": ["checkoutCountries", "checkoutPaymentMethods"]
+        },
+        "CheckoutForm3": {
+          "status": "held",
+          "reason": "unproven checkout variant: E1 keeps only the default CheckoutForm1, whose behavior is unchanged; no verified prop bridge exists",
+          "block": "Checkout",
+          "dataShape": "CheckoutForm3FormData",
+          "events": ["submit"],
+          "state": "controlled",
+          "requirements": ["checkoutCountries", "checkoutPaymentMethods"]
+        }
+      }
+    },
+    "checkout.confirmation": {
+      "default": "CheckoutConfirmation",
+      "variants": {
+        "CheckoutConfirmation": {
+          "status": "executable",
+          "block": "CheckoutConfirmation",
+          "dataShape": "Receipt",
+          "events": ["continueShopping"],
+          "state": "uncontrolled",
+          "requirements": ["lastReceipt"]
+        }
+      }
+    },
+    "account.login": {
+      "default": "LoginPage1",
+      "variants": {
+        "LoginPage1": {
+          "status": "executable",
+          "block": "LoginPage1",
+          "dataShape": "LoginPage1FormData & AccountAuthResult",
+          "events": ["submit", "createAccount"],
+          "state": "controlled",
+          "requirements": ["accountCustomer", "accountAuthenticated"]
+        },
+        "LoginPage2": {
+          "status": "held",
+          "reason": "block's onSubmit takes positional (email, password) with no remember-me field and renders a 2-column social grid; no verified prop bridge from the account element contract exists",
+          "block": "LoginPage2",
+          "dataShape": "LoginPage2Credentials & AccountAuthResult",
+          "events": ["submit", "forgotPassword", "signUp"],
+          "state": "controlled",
+          "requirements": ["accountCustomer", "accountAuthenticated"]
+        }
+      }
+    },
+    "account.register": {
+      "default": "SignUpPage1",
+      "variants": {
+        "SignUpPage1": {
+          "status": "executable",
+          "block": "SignUpPage1",
+          "dataShape": "SignUpPage1Data & AccountAuthResult",
+          "events": ["submit", "signIn"],
+          "state": "controlled",
+          "requirements": ["accountCustomer", "accountAuthenticated"]
+        }
+      }
+    },
+    "account.orders": {
+      "default": "OrderHistory2",
+      "variants": {
+        "OrderHistory2": {
+          "status": "executable",
+          "block": "OrderHistory2",
+          "dataShape": "AccountOrderView[] & OrderHistory2Labels",
+          "events": ["viewDetails"],
+          "state": "controlled",
+          "requirements": ["accountCustomer", "accountAuthenticated"]
+        },
+        "OrderHistory1": {
+          "status": "held",
+          "reason": "block models one row per order item (an item-row list), the wrong shape for an order-level history; the canonical order list cannot feed it without inventing an aggregate row",
+          "block": "OrderHistory1",
+          "dataShape": "OrderHistory1Order[]",
+          "events": [],
+          "state": "controlled",
+          "requirements": ["accountCustomer", "accountAuthenticated"]
+        }
+      }
+    },
+    "category.breadcrumb": {
+      "default": "Breadcrumb",
+      "variants": {
+        "Breadcrumb": {
+          "status": "executable",
+          "block": "Breadcrumb",
+          "dataShape": "BreadcrumbItemData[]",
+          "events": [],
+          "state": "uncontrolled",
+          "requirements": ["categoryBreadcrumb"]
+        }
+      }
+    }
+  },
+  "capabilities": {
+    "category.search.apply": {
+      "requirements": ["adapter.getCatalogProducts(query).text"],
+      "verification": "unverified",
+      "owner": "storefront-catalog-search-filters"
+    },
+    "category.filter.apply": {
+      "requirements": ["adapter.getProducts(query)"],
+      "verification": "unverified",
+      "owner": "storefront-catalog-search-filters"
+    },
+    "category.price.range": {
+      "requirements": ["adapter.getAvailableFilters(query).priceRange"],
+      "verification": "unverified",
+      "owner": "storefront-catalog-search-filters"
+    }
+  }
+}