@thorprovider/storefront 0.3.1 → 0.4.0-mvp.0

package/skills/sf-view-gen/assets/templates/views/sections/schema.pricing.ts

@@ -0,0 +1,26 @@
+// Optional section fragment: pricing (mirrors recipes/sections.json) — shared contract.
+// Zod mirror of the PricingTier/PricingSection1Props block contracts, shared by
+// the server catalog (pricing.tsx) and the client registry (pricing.client.tsx).
+
+import { z } from 'zod'
+
+export const pricingTierSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  // Precio sin símbolo de moneda; el símbolo se pasa aparte en `currencySymbol`.
+  price: z.string(),
+  // Frecuencia de facturación, p. ej. '/mes'.
+  frequency: z.string(),
+  features: z.array(z.string()),
+  popular: z.boolean().optional(),
+})
+
+export const pricingPropsSchema = z.object({
+  sectionTitle: z.string().optional(),
+  sectionLabel: z.string().optional(),
+  currencySymbol: z.string().optional(),
+  popularBadgeLabel: z.string().optional(),
+  getStartedLabel: z.string().optional(),
+  tiers: z.array(pricingTierSchema),
+})

package/skills/sf-view-gen/assets/templates/views/sections/schema.statistics.ts

@@ -0,0 +1,25 @@
+// Optional section fragment: statistics (mirrors recipes/sections.json) — shared contract.
+// Zod mirror of the StatisticItem/Statistic1Props block contracts, shared by
+// the server catalog (statistics.tsx) and the client registry
+// (statistics.client.tsx). The block expects `icon` as a Lucide component;
+// specs ship the icon NAME, so it is a string here and the client registry
+// resolves it via resolveIcon.
+
+import { z } from 'zod'
+
+export const statisticItemSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  value: z.string(),
+  description: z.string(),
+  progress: z.number(),
+  progressLabel: z.string(),
+  icon: z.string().optional(),
+})
+
+export const statisticsPropsSchema = z.object({
+  title: z.string().optional(),
+  badge: z.string().optional(),
+  description: z.string().optional(),
+  items: z.array(statisticItemSchema),
+})

package/skills/sf-view-gen/assets/templates/views/sections/schema.testimonials.ts

@@ -0,0 +1,23 @@
+// Optional section fragment: testimonials (mirrors recipes/sections.json) — shared contract.
+// Zod mirror of the Testimonial1Item/Testimonial1Props block contracts, shared
+// by the server catalog (testimonials.tsx) and the client registry
+// (testimonials.client.tsx).
+
+import { z } from 'zod'
+
+export const testimonialItemSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  role: z.string(),
+  avatar: z.string(),
+  content: z.string(),
+  rating: z.number(),
+})
+
+export const testimonialsPropsSchema = z.object({
+  title: z.string().optional(),
+  prevLabel: z.string().optional(),
+  nextLabel: z.string().optional(),
+  slideAriaLabel: z.string().optional(),
+  items: z.array(testimonialItemSchema),
+})

package/skills/sf-view-gen/assets/templates/views/sections/statistics.client.tsx

@@ -4,15 +4,23 @@
 // The matching server-side catalog entry lives in statistics.tsx.
 
 import { Statistic1 as StatisticBlock } from '@thorprovider/blocks'
+import { statisticsPropsSchema } from './schema.statistics'
+import { resolveIcon } from '../../icon-map'
 import type { ViewRegistry } from '../types'
 
 export const registry: ViewRegistry = {
-  Statistics: ({ props }) => (
-    <StatisticBlock
-      badge={props.badge as string}
-      title={(props.title as string) ?? 'Números que nos respaldan'}
-      description={props.description as string}
-      items={props.items as never}
-    />
-  ),
+  Statistics: ({ props }) => {
+    const parsed = statisticsPropsSchema.parse(props)
+    return (
+      <StatisticBlock
+        badge={parsed.badge}
+        title={parsed.title ?? 'Números que nos respaldan'}
+        description={parsed.description}
+        items={parsed.items.map((item) => ({
+          ...item,
+          icon: resolveIcon(item.icon),
+        }))}
+      />
+    )
+  },
 }

package/skills/sf-view-gen/assets/templates/views/sections/statistics.tsx

@@ -2,18 +2,13 @@
 // Server-side part: element type + zod catalog entry. The component mappings
 // live in statistics.client.tsx ('use client').
 
-import { z } from 'zod'
+import { statisticsPropsSchema } from './schema.statistics'
 
 export const statisticsSection = {
   elementType: 'Statistics',
   catalog: {
     Statistics: {
-      props: z.object({
-        title: z.string().optional(),
-        badge: z.string().optional(),
-        description: z.string().optional(),
-        items: z.array(z.record(z.string(), z.unknown())),
-      }),
+      props: statisticsPropsSchema,
       description: 'Key metrics or trust statistics.',
     },
   },

package/skills/sf-view-gen/assets/templates/views/sections/testimonials.client.tsx

@@ -4,16 +4,20 @@
 // The matching server-side catalog entry lives in testimonials.tsx.
 
 import { Testimonial1 as TestimonialBlock } from '@thorprovider/blocks'
+import { testimonialsPropsSchema } from './schema.testimonials'
 import type { ViewRegistry } from '../types'
 
 export const registry: ViewRegistry = {
-  Testimonials: ({ props }) => (
-    <TestimonialBlock
-      title={(props.title as string) ?? 'Lo que dicen nuestros clientes'}
-      items={props.items as never}
-      prevLabel={(props.prevLabel as string) ?? 'Anterior'}
-      nextLabel={(props.nextLabel as string) ?? 'Siguiente'}
-      slideAriaLabel={(props.slideAriaLabel as string) ?? 'Testimonio'}
-    />
-  ),
+  Testimonials: ({ props }) => {
+    const parsed = testimonialsPropsSchema.parse(props)
+    return (
+      <TestimonialBlock
+        title={parsed.title ?? 'Lo que dicen nuestros clientes'}
+        items={parsed.items}
+        prevLabel={parsed.prevLabel ?? 'Anterior'}
+        nextLabel={parsed.nextLabel ?? 'Siguiente'}
+        slideAriaLabel={parsed.slideAriaLabel ?? 'Testimonio'}
+      />
+    )
+  },
 }

package/skills/sf-view-gen/assets/templates/views/sections/testimonials.tsx

@@ -2,16 +2,13 @@
 // Server-side part: element type + zod catalog entry. The component mappings
 // live in testimonials.client.tsx ('use client').
 
-import { z } from 'zod'
+import { testimonialsPropsSchema } from './schema.testimonials'
 
 export const testimonialsSection = {
   elementType: 'Testimonials',
   catalog: {
     Testimonials: {
-      props: z.object({
-        title: z.string().optional(),
-        items: z.array(z.record(z.string(), z.unknown())),
-      }),
+      props: testimonialsPropsSchema,
       description: 'Customer testimonials or social proof.',
     },
   },

package/skills/sf-view-gen/references/views.md

@@ -1,15 +1,19 @@
 # View templates
 
 Each folder here is a self-contained view module. `npx @thorprovider/storefront create`
-copies `home/` at init; `/sf-add-view` copies one folder per added view.
+generates `home/` at init; `npx @thorprovider/storefront view add <view>`
+generates one view's derived files and reconciles the barrel. The CLI — not the
+agent — writes the barrel and every derived file.
 
 ## Module shape
 
-Each view is the **two-file split** (RSC):
+Each view is the **three-file split** (RSC):
 
 - `views/<view>/index.tsx` — pure Server Component module: name, elements,
   zod catalog, route, loader. Never imports values from `@json-render/react`
   or `@thorprovider/blocks`.
+- `views/<view>/schema.ts` — pure Zod schemas mirroring the block contracts
+  the view renders (props only). No React, no `'use client'`, no Next imports.
 - `views/<view>/registry.tsx` — `'use client'`: exports
   `registry: ViewRegistry`, the component mappings
   (`Record<string, (ctx: BaseComponentProps<Record<string, unknown>>) => ReactNode>`).
@@ -39,14 +43,12 @@ view never edits them.
 
 ## Registering a view
 
-Add **one import and one entry** to `lib/<name>/views/index.ts`:
-
-```ts
-import { home } from './home'
-import { product } from './product'
-
-export const views: ViewModule[] = [home, product]
-```
+The barrel `lib/<name>/views/index.ts` (server) and `lib/<name>/views/registry.ts`
+(client) are **generated from the manifest by the CLI** on every reconcile. Do
+not hand-edit them; add or remove a view with
+`npx @thorprovider/storefront view add|remove <name>`. The CLI emits one import
+and one entry per installed view, so a view removed from the manifest cannot
+reappear through folder scanning.
 
 ## Variant substitution convention
 
@@ -67,3 +69,35 @@ import { ProductOverview5 as ProductOverviewBlock } from '@thorprovider/blocks'
 The alias is the element type's contract; the identifier is the presentation
 choice. Keeping props identical across variants is why the catalog declares the
 stable subset of each element's props.
+
+## Data contracts and icons
+
+Two rules that keep generated views from crashing at render time:
+
+1. **Mappers are applied at loaders, never in registries.** Adapter canon does
+   not match block props 1:1 (e.g. a category may carry `productCount?: number`
+   or no count at all, and `ProductCategory2.itemCount` is **optional**). The
+   view's loader maps adapter data through `lib/<name>/mappers.ts`
+   (`toFeaturedProduct`, `toCategoryCard`, `toOverviewProduct`) before it reaches
+   state. Registries receive already-mapped, block-shaped props. When a value is
+   unknown (e.g. no category count), **omit** it — never fabricate a `0` default,
+   which would render a false "0 items". A genuine `0` from a richer source is
+   preserved.
+
+2. **Icons cross registries as components, via `icon-map`.** Several blocks
+   type icon props as `LucideIcon` (a component). A string like `'truck'`
+   bound directly renders a literal `<truck>` tag in the DOM. Registries
+   resolve icon names through `lib/<name>/icon-map.ts` (`resolveIcon(name)`,
+   kebab-case → `LucideIcon`, neutral `Circle` fallback). When adding a view
+   that uses a new icon, extend `icon-map.ts` with an entry — never inline a
+   string where a component is expected.
+
+Supporting rules for the same goal:
+
+- View schemas live in `views/<view>/schema.ts` and **mirror the block's Zod
+  contracts locally** — never import schemas from `@thorprovider/blocks` (the
+  scaffold runs Zod v4 while blocks ships v3; cross-major schema assignment
+  breaks `defineCatalog`).
+- Registries **parse props through the view schema** (`schema.parse(props)`)
+  instead of casting bindings (`as never` / `as any` are forbidden in scaffold
+  code). Type errors on `parse` are the contract check.

package/skills/sf-view-gen/scripts/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/skills/sf-view-gen/scripts/schema-validate.mjs

@@ -0,0 +1,132 @@
+// Minimal, dependency-free validator for the JSON Schema subset used by the
+// published storefront schemas. It supports exactly the keywords those schemas
+// use (type, required, properties, items, additionalProperties, minLength,
+// enum) so a document is validated against the same artifact the package
+// publishes, with no duplicated hand-rolled shape contract.
+
+// Validation keywords this validator understands. Annotation-only keywords are
+// allowed through without affecting the result. Any other keyword is reported
+// as unsupported so a future schema cannot silently be treated as valid.
+const VALIDATION_KEYWORDS = new Set([
+  'type',
+  'enum',
+  'minLength',
+  'required',
+  'properties',
+  'additionalProperties',
+  'items',
+])
+// `default` is an annotation: it documents a field's default value but does not
+// affect validation. Feature config contracts use it so `normalizeConfig` can
+// apply declared defaults without a second source of truth.
+const ANNOTATION_KEYWORDS = new Set(['$schema', '$id', 'title', 'description', 'default'])
+const SUPPORTED_KEYWORDS = new Set([...VALIDATION_KEYWORDS, ...ANNOTATION_KEYWORDS])
+
+function typeOf(value) {
+  if (Array.isArray(value)) return 'array'
+  if (value === null) return 'null'
+  return typeof value
+}
+
+function isObject(value) {
+  return typeOf(value) === 'object'
+}
+
+// Own-property lookup: inherited keys (`constructor`, `__proto__`, `toString`)
+// must never be mistaken for declared schema properties or present data, or an
+// `additionalProperties` constraint could be bypassed.
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key)
+}
+
+// Walk the schema itself (independent of any value) so an unsupported keyword
+// anywhere in the tree fails clearly instead of being ignored.
+function collectUnsupportedKeywords(schema, path, errors) {
+  if (!isObject(schema)) return
+  for (const keyword of Object.keys(schema)) {
+    if (!SUPPORTED_KEYWORDS.has(keyword)) {
+      errors.push(`${path || 'manifest'} uses an unsupported schema keyword "${keyword}".`)
+    }
+  }
+  const properties = isObject(schema.properties) ? schema.properties : {}
+  for (const key of Object.keys(properties)) {
+    collectUnsupportedKeywords(properties[key], `${path || 'manifest'}.${key}`, errors)
+  }
+  if (isObject(schema.items)) {
+    collectUnsupportedKeywords(schema.items, `${path || 'manifest'}[]`, errors)
+  }
+  if (isObject(schema.additionalProperties)) {
+    collectUnsupportedKeywords(schema.additionalProperties, `${path || 'manifest'}.*`, errors)
+  }
+}
+
+export function validateSchemaSupported(schema) {
+  const errors = []
+  collectUnsupportedKeywords(schema, '', errors)
+  return errors
+}
+
+/**
+ * Validate `value` against `schema`, returning a list of human-readable errors.
+ * Each error is prefixed with the dotted path of the offending field (the root
+ * uses `manifest`), so callers can name the bad input precisely.
+ */
+export function validateAgainstSchema(value, schema, path = '') {
+  const errors = []
+  const label = path || 'manifest'
+
+  if (!isObject(schema)) {
+    errors.push(`${label} uses an invalid schema (expected an object).`)
+    return errors
+  }
+
+  // The schema tree is checked once, at the root, so unsupported keywords fail
+  // closed regardless of which fields the value happens to contain.
+  if (!path) errors.push(...validateSchemaSupported(schema))
+
+  if (schema.type) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type]
+    if (!types.includes(typeOf(value))) {
+      errors.push(`${label} must be of type ${types.join(' | ')}.`)
+      return errors
+    }
+  }
+
+  if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+    errors.push(`${label} must be one of: ${schema.enum.join(', ')}.`)
+  }
+
+  if (
+    typeof value === 'string' &&
+    typeof schema.minLength === 'number' &&
+    value.length < schema.minLength
+  ) {
+    errors.push(`${label} must be at least ${schema.minLength} character(s).`)
+  }
+
+  if (isObject(value)) {
+    for (const key of schema.required ?? []) {
+      if (!hasOwn(value, key)) errors.push(`${label} is missing required property "${key}".`)
+    }
+    const properties = isObject(schema.properties) ? schema.properties : {}
+    const additional = schema.additionalProperties
+    for (const key of Object.keys(value)) {
+      const childPath = path ? `${path}.${key}` : key
+      if (hasOwn(properties, key)) {
+        errors.push(...validateAgainstSchema(value[key], properties[key], childPath))
+      } else if (isObject(additional)) {
+        errors.push(...validateAgainstSchema(value[key], additional, childPath))
+      } else if (additional === false) {
+        errors.push(`${label} has unknown property "${key}".`)
+      }
+    }
+  }
+
+  if (Array.isArray(value) && isObject(schema.items)) {
+    value.forEach((item, index) => {
+      errors.push(...validateAgainstSchema(item, schema.items, `${path}[${index}]`))
+    })
+  }
+
+  return errors
+}