@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/recipes/catalog.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// Semantic executable catalog: the single contract that states, per view slot
+// and candidate block variant, whether the variant is `executable` or `held`,
+// the block it renders, the canonical data shape it consumes, the events it
+// emits, its controlled/uncontrolled state, its requirements, and an optional
+// prop bridge from the canonical shape to the block props.
+//
+// The published shape lives in `recipes/catalog.schema.json`; this module loads
+// that same artifact and adds only the invariants the supported schema subset
+// cannot express (a held entry must carry a reason; a slot's default must be a
+// declared variant; an unverified capability must name its owning change). It
+// does not classify the initial set, derive `supported`, or wire any
+// generator/introspection — those are owned by later tasks.
+
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { validateAgainstSchema, validateSchemaSupported } from '../scripts/schema-validate.mjs'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+// Layout-agnostic catalog location: at the package root the catalog lives beside
+// this module (`recipes/`); in an installed skill it is distributed under
+// `skills/sf-view-gen/assets/recipes/` and addressed by relative path. Either
+// layout holds the same synced artifact, so there is one catalog source. The
+// `../scripts/schema-validate.mjs` import resolves to the package `scripts/` at
+// the root and to the skill's own `scripts/` once distributed (same directory).
+const catalogDir = existsSync(join(here, 'catalog.json'))
+  ? here
+  : join(here, '..', 'assets', 'recipes')
+
+export const CATALOG_VERSION = 1
+export const CATALOG_SCHEMA_ID = 'https://thorcommerce.dev/storefront/catalog.schema.json'
+
+const catalogSchema = JSON.parse(readFileSync(join(catalogDir, 'catalog.schema.json'), 'utf8'))
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key)
+}
+
+export function loadCatalogSchema() {
+  return catalogSchema
+}
+
+/**
+ * Load the published semantic catalog document (`recipes/catalog.json`) — the
+ * single source of the executable/held classification. Callers validate it with
+ * `validateCatalog`; classification is data, not logic (E1 task 1.2).
+ */
+export function loadCatalog() {
+  return JSON.parse(readFileSync(join(catalogDir, 'catalog.json'), 'utf8'))
+}
+
+/**
+ * The slot variant entry schema, read from the published catalog schema so the
+ * per-entry contract has exactly one source. Throws loudly if the schema is
+ * reshaped, rather than silently validating against nothing.
+ */
+function variantEntrySchema() {
+  const entry =
+    catalogSchema?.properties?.slots?.additionalProperties?.properties?.variants
+      ?.additionalProperties
+  if (!isPlainObject(entry)) {
+    throw new Error('catalog.schema.json does not declare a slot variant entry schema.')
+  }
+  return entry
+}
+
+/**
+ * Validate one slot variant entry against the published contract.
+ * Returns { ok, errors }.
+ */
+export function validateCatalogEntry(entry) {
+  const errors = validateAgainstSchema(entry, variantEntrySchema(), 'catalog entry')
+  return { ok: errors.length === 0, errors }
+}
+
+/**
+ * Validate a complete catalog document against the published contract plus the
+ * invariants the schema subset cannot express. Returns { ok, errors }.
+ */
+export function validateCatalog(catalog) {
+  if (!isPlainObject(catalog)) {
+    return { ok: false, errors: ['Catalog must be a JSON object.'] }
+  }
+  const errors = validateSchemaSupported(catalogSchema)
+  errors.push(...validateAgainstSchema(catalog, catalogSchema, 'catalog'))
+
+  const slots = isPlainObject(catalog.slots) ? catalog.slots : {}
+  for (const [slotId, slot] of Object.entries(slots)) {
+    if (!isPlainObject(slot)) continue
+    const variants = isPlainObject(slot.variants) ? slot.variants : {}
+    if (Object.keys(variants).length === 0) {
+      errors.push(`Slot "${slotId}" must declare at least one variant.`)
+    }
+    if (typeof slot.default === 'string' && !hasOwn(variants, slot.default)) {
+      errors.push(`Slot "${slotId}" default "${slot.default}" is not a declared variant.`)
+    }
+    for (const [variantName, entry] of Object.entries(variants)) {
+      if (!isPlainObject(entry)) continue
+      if (entry.status === 'held' && !(typeof entry.reason === 'string' && entry.reason.length > 0)) {
+        errors.push(`Held variant "${slotId}.${variantName}" must declare a non-empty reason.`)
+      }
+    }
+  }
+
+  // An unverified capability is held: it must name the change that owns its
+  // implementation, so a consumer can see that the capability is not available
+  // and who will make it available. This is the honest gate the schema subset
+  // cannot express (E1 task 4.2 / CU-04).
+  const capabilities = isPlainObject(catalog.capabilities) ? catalog.capabilities : {}
+  for (const [capabilityId, capability] of Object.entries(capabilities)) {
+    if (!isPlainObject(capability)) continue
+    if (
+      capability.verification === 'unverified' &&
+      !(typeof capability.owner === 'string' && capability.owner.length > 0)
+    ) {
+      errors.push(
+        `Unverified capability "${capabilityId}" must declare the owning change in "owner".`
+      )
+    }
+  }
+  return { ok: errors.length === 0, errors }
+}

package/recipes/catalog.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://thorcommerce.dev/storefront/catalog.schema.json",
+  "title": "Thor Commerce Storefront Semantic Catalog",
+  "description": "The semantic executable catalog: per view slot and candidate variant, its execution status (executable | held), the block it renders, its canonical data shape, emitted events, controlled/uncontrolled state, requirements, and an optional prop bridge. Held entries carry a reason. Also declares operational capabilities with their backend/data requirements and a verification state (verified | unverified); an unverified capability names its owning change in `owner`. Versioned by catalogVersion.",
+  "type": "object",
+  "required": ["catalogVersion", "slots"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "catalogVersion": { "type": "number", "enum": [1] },
+    "description": { "type": "string" },
+    "slots": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["default", "variants"],
+        "additionalProperties": false,
+        "properties": {
+          "default": { "type": "string", "minLength": 1 },
+          "variants": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "required": ["status", "block", "dataShape", "events", "state", "requirements"],
+              "additionalProperties": false,
+              "properties": {
+                "status": { "type": "string", "enum": ["executable", "held"] },
+                "reason": { "type": "string", "minLength": 1 },
+                "block": { "type": "string", "minLength": 1 },
+                "dataShape": { "type": "string", "minLength": 1 },
+                "events": { "type": "array", "items": { "type": "string" } },
+                "state": { "type": "string", "enum": ["controlled", "uncontrolled"] },
+                "requirements": { "type": "array", "items": { "type": "string" } },
+                "bridge": {
+                  "type": "object",
+                  "required": ["from", "to"],
+                  "additionalProperties": false,
+                  "properties": {
+                    "from": { "type": "string", "minLength": 1 },
+                    "to": { "type": "string", "minLength": 1 }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["requirements", "verification"],
+        "additionalProperties": false,
+        "properties": {
+          "requirements": { "type": "array", "items": { "type": "string" } },
+          "verification": { "type": "string", "enum": ["verified", "unverified"] },
+          "owner": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/recipes/feature.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://thorcommerce.dev/storefront/feature.schema.json",
+  "title": "Storefront feature registry",
+  "type": "object",
+  "required": ["version", "features"],
+  "properties": {
+    "version": { "type": "string" },
+    "features": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "views", "state", "handlers", "adapter", "surfaces", "config"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "description": { "type": "string" },
+          "mvp": { "type": "boolean" },
+          "route": { "type": "string", "minLength": 1 },
+          "views": { "type": "array", "items": { "type": "string" } },
+          "state": { "type": "array", "items": { "type": "string" } },
+          "handlers": { "type": "array", "items": { "type": "string" } },
+          "adapter": {
+            "type": "object",
+            "required": ["needs"],
+            "properties": {
+              "needs": { "type": "array", "items": { "type": "string" } },
+              "fallback": { "type": "string" }
+            }
+          },
+          "config": {
+            "type": "object",
+            "description": "Per-feature configuration contract: a JSON Schema (the dependency-free subset) that the manifest's features[].config is validated against and whose `default` annotations seed absent fields."
+          },
+          "configRejection": {
+            "type": "object",
+            "description": "Stable diagnostic for configuration the feature does not accept. With no `when`, any non-empty config key is rejected with this code/message while an empty object stays the no-op (E1 task 3.5, e.g. checkout E_UNPROVEN_CHECKOUT_OPTION). With `when: { field, equals }`, only a config where that field equals the value is rejected (E2 task 4.12); an optional `capability` makes the rejection apply only while that catalog capability is not `verified`, so an unproven option fails loudly instead of being silently coerced to its default.",
+            "required": ["code", "message"],
+            "properties": {
+              "code": { "type": "string", "minLength": 1 },
+              "message": { "type": "string", "minLength": 1 },
+              "when": {
+                "type": "object",
+                "required": ["field", "equals"],
+                "additionalProperties": false,
+                "properties": {
+                  "field": { "type": "string", "minLength": 1 },
+                  "equals": {}
+                }
+              },
+              "capability": { "type": "string", "minLength": 1 }
+            }
+          },
+          "presentations": {
+            "type": "object",
+            "description": "Generation-owned block wiring: maps a config value (e.g. config.presentation) to the block variant the feature mount renders.",
+            "additionalProperties": { "type": "string" }
+          },
+          "mounts": {
+            "type": "array",
+            "description": "Feature-instance mounts into a host view's slot. The engine owns the block wiring; a mount never carries an element.",
+            "items": {
+              "type": "object",
+              "required": ["id", "host", "slot"],
+              "additionalProperties": false,
+              "properties": {
+                "id": { "type": "string", "minLength": 1 },
+                "host": { "type": "string", "minLength": 1 },
+                "slot": { "type": "string", "minLength": 1 }
+              }
+            }
+          },
+          "surfaces": {
+            "type": "array",
+            "description": "Legacy additive alias for existing held registry entries; derived from mounts where both exist.",
+            "items": {
+              "type": "object",
+              "required": ["host", "slot", "element"],
+              "properties": {
+                "host": { "type": "string" },
+                "slot": { "type": "string" },
+                "element": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/recipes/features.json

@@ -0,0 +1,162 @@
+{
+  "version": "1.0.0",
+  "features": [
+    {
+      "name": "checkout",
+      "mvp": true,
+      "description": "Multi-step checkout: cart validation, shipping, payment, and order placement.",
+      "route": "/checkout",
+      "views": ["checkout"],
+      "state": [
+        "checkout",
+        "checkoutCountries",
+        "checkoutPaymentMethods",
+        "checkoutPending",
+        "checkoutError",
+        "lastOrder",
+        "lastOrderLines",
+        "orderPlaced"
+      ],
+      "handlers": ["placeOrder", "goToCheckout", "continueShopping"],
+      "adapter": { "needs": ["createCart", "completeCheckout"] },
+      "config": { "type": "object", "additionalProperties": false, "properties": {} },
+      "configRejection": {
+        "code": "E_UNPROVEN_CHECKOUT_OPTION",
+        "message": "checkout variants and route options are not proven; the checkout feature accepts an empty config only"
+      },
+      "surfaces": []
+    },
+    {
+      "name": "customer-auth",
+      "mvp": true,
+      "description": "Customer authentication: registration, login, logout, and a minimal signed-in state. Owns the account view.",
+      "route": "/account",
+      "views": ["account"],
+      "state": [
+        "accountCustomer",
+        "accountAuthenticated",
+        "accountMode",
+        "accountPending",
+        "accountError"
+      ],
+      "handlers": ["logout", "showRegister", "showLogin"],
+      "adapter": { "needs": [] },
+      "config": { "type": "object", "additionalProperties": false, "properties": {} },
+      "surfaces": []
+    },
+    {
+      "name": "static-pages",
+      "mvp": true,
+      "description": "Content-driven static pages (contact, legal, about) served with per-page metadata. Owns the static view.",
+      "route": "/contact",
+      "views": ["static"],
+      "state": [],
+      "handlers": [],
+      "adapter": { "needs": [] },
+      "config": { "type": "object", "additionalProperties": false, "properties": {} },
+      "surfaces": []
+    },
+    {
+      "name": "benefits",
+      "mvp": true,
+      "description": "Bounded editorial benefits feature that mounts at the home benefits slot; config selects the Feature1/Feature2 presentation while the item content stays user-owned.",
+      "views": [],
+      "state": [],
+      "handlers": [],
+      "adapter": { "needs": [] },
+      "config": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "presentation": { "type": "string", "enum": ["compact", "detailed"], "default": "compact" }
+        }
+      },
+      "presentations": { "compact": "Feature1", "detailed": "Feature2" },
+      "mounts": [{ "id": "home-benefits", "host": "home", "slot": "benefits" }],
+      "surfaces": []
+    },
+    {
+      "name": "catalog-search",
+      "mvp": true,
+      "description": "Optional category-listing search control (E2). Installation is presence, not an enabled flag; the config only supplies an optional placeholder. The search input contributes to the single controlled CategoryFilter2 at the category.search logical slot and never adds a block.",
+      "views": [],
+      "state": [],
+      "handlers": [],
+      "adapter": { "needs": [] },
+      "config": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "placeholder": { "type": "string" }
+        }
+      },
+      "mounts": [{ "id": "category-search", "host": "category", "slot": "search" }],
+      "surfaces": []
+    },
+    {
+      "name": "category-filters",
+      "mvp": true,
+      "description": "Optional category-listing filter controls (E2). Installation is presence, not an enabled flag; the config selects which demonstrated basic filters show (filterSet) and whether the price control is shown (showPrice). The controls contribute to the single controlled CategoryFilter2 at the category.filters logical slot and never add a block.",
+      "views": [],
+      "state": [],
+      "handlers": [],
+      "adapter": { "needs": [] },
+      "config": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "filterSet": {
+            "type": "array",
+            "items": { "type": "string", "enum": ["categories", "collections"] },
+            "default": ["categories", "collections"]
+          },
+          "showPrice": { "type": "boolean", "default": false }
+        }
+      },
+      "configRejection": {
+        "code": "E_UNVERIFIED_PRICE_RANGE",
+        "message": "showPrice: true requires a verified price range for the listing scope; capability \"category.price.range\" is unverified (held), so configure showPrice: false until a real range is demonstrated",
+        "when": { "field": "showPrice", "equals": true },
+        "capability": "category.price.range"
+      },
+      "mounts": [{ "id": "category-filters", "host": "category", "slot": "filters" }],
+      "surfaces": []
+    },
+    {
+      "name": "navigability",
+      "mvp": true,
+      "description": "Cross-cutting navigability feature: entity-derived breadcrumbs with BreadcrumbList structured data on the product and category surfaces, plus skip-to-content, current-page indication, back-to-top, and a mobile bottom navigation in the shared shell.",
+      "views": [],
+      "state": [],
+      "handlers": [],
+      "adapter": { "needs": [] },
+      "config": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "presentation": { "type": "string", "enum": ["default"], "default": "default" },
+          "showBackToTop": { "type": "boolean", "default": true }
+        }
+      },
+      "presentations": { "default": "Breadcrumb" },
+      "mounts": [
+        { "id": "category-breadcrumb", "host": "category", "slot": "breadcrumb" },
+        { "id": "product-breadcrumb", "host": "product", "slot": "breadcrumb" }
+      ],
+      "surfaces": []
+    },
+    {
+      "name": "recommendations",
+      "mvp": false,
+      "description": "Related-products surface injected into the product view.",
+      "views": [],
+      "state": ["recommendedProducts"],
+      "handlers": [],
+      "adapter": { "needs": ["getRelatedProducts"], "fallback": "catalog" },
+      "config": { "type": "object", "additionalProperties": false, "properties": {} },
+      "surfaces": [
+        { "host": "product", "slot": "product.related", "element": "ProductCard" }
+      ]
+    }
+  ]
+}

package/recipes/manifest.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://thorcommerce.dev/storefront/manifest.schema.json",
+  "title": "Thor Commerce Storefront Composition Manifest",
+  "type": "object",
+  "required": ["version", "name", "theme", "views", "features"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "type": "string", "minLength": 1 },
+    "name": { "type": "string", "minLength": 1 },
+    "siteName": { "type": "string" },
+    "theme": {
+      "type": "object",
+      "required": ["mode"],
+      "properties": {
+        "mode": { "type": "string", "enum": ["light", "dark", "system"] }
+      }
+    },
+    "views": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "intents": {
+            "type": "object",
+            "additionalProperties": { "type": "string" }
+          },
+          "variants": {
+            "type": "object",
+            "additionalProperties": { "type": "string" }
+          },
+          "sections": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "id": { "type": "string", "minLength": 1 },
+                "type": { "type": "string", "minLength": 1 },
+                "name": { "type": "string", "minLength": 1 },
+                "variant": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "preservedSectionIds": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": { "type": "string", "minLength": 1 }
+      }
+    },
+    "features": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "config": { "type": "object" }
+        }
+      }
+    }
+  }
+}

package/recipes/operations.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://thorcommerce.dev/storefront/operations.schema.json",
+  "title": "Thor Commerce Storefront Operations Envelope",
+  "description": "The versioned input envelope for `storefront plan --operations`. `formatVersion` must equal 1, aligned with the catalog `catalogVersion` (both 1 in E1). E1 accepts exactly six namespaced operations: view.add, view.remove, view.configure, feature.add, feature.remove, feature.configure. The per-operation field contract (which fields are required, which optional, and the exactly-one `intent` / `variant` / `reset: true` rule) is declared by OPERATION_SCHEMAS in scripts/operations.mjs, which is the runtime authority; this published schema is the closed structural contract. Unknown operation names, unknown fields, and a `force` field are not part of version 1 (`force` is an internal add/refresh control used by the legacy `view add --force` alias and by plan/apply, never a public operation field).",
+  "type": "object",
+  "required": ["formatVersion", "operations"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "formatVersion": { "type": "number", "enum": [1] },
+    "operations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["op"],
+        "additionalProperties": false,
+        "properties": {
+          "op": {
+            "type": "string",
+            "enum": [
+              "view.add",
+              "view.remove",
+              "view.configure",
+              "feature.add",
+              "feature.remove",
+              "feature.configure"
+            ]
+          },
+          "view": { "type": "string", "minLength": 1 },
+          "slot": { "type": "string", "minLength": 1 },
+          "intent": { "type": "string", "minLength": 1 },
+          "variant": { "type": "string", "minLength": 1 },
+          "reset": { "type": "boolean" },
+          "intents": { "type": "object", "additionalProperties": { "type": "string" } },
+          "variants": { "type": "object", "additionalProperties": { "type": "string" } },
+          "feature": { "type": "string", "minLength": 1 },
+          "config": { "type": "object" }
+        }
+      }
+    }
+  }
+}

package/recipes/recipe.schema.json

@@ -23,7 +23,7 @@
         "properties": {
           "name": {
             "type": "string",
-            "enum": ["home", "product", "category", "checkout", "user-panel"]
+            "enum": ["home", "product", "cart", "category", "checkout", "account", "static"]
           },
           "description": { "type": "string" },
           "route": { "type": "string" },
@@ -51,7 +51,16 @@
               "type": "string",
               "enum": ["testimonials", "faq", "statistics", "logoCloud", "pricing"]
             }
-          }
+          },
+          "registeredSlots": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "allowedSections": {
+            "type": "array",
+            "items": { "type": "string", "enum": ["faq", "cta"] }
+          },
+          "maxSections": { "type": "number" }
         }
       }
     }