@thorprovider/storefront 0.4.0-mvp.0 → 0.4.0-mvp.2

package/assets/templates/views/user-panel/index.tsx

@@ -1,106 +0,0 @@
-// Thor Commerce view module: user-panel
-// 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 -> "user-panel".
-
-import { getCatalog } from '@thorprovider/runtime/commerce'
-import { pageRoot } from '../../spec/page-root'
-import type { StorefrontElement } from '../../spec/types'
-import type { ViewModule } from '../types'
-import { registry } from './registry'
-import { appShellPropsSchema, orderHistoryPropsSchema } from './schema'
-
-const elements: Record<string, StorefrontElement> = {
-  'userPanel.shell': {
-    type: 'AppShell',
-    props: {
-      brandName: '__SITE_NAME__',
-      navGroupLabel: 'Mi cuenta',
-      navItems: [
-        { label: 'Mis pedidos', href: '/cuenta', icon: 'package', active: true },
-        { label: 'Mi perfil', href: '/cuenta/perfil', icon: 'user' },
-        { label: 'Ajustes', href: '/cuenta/ajustes', icon: 'settings' },
-      ],
-      user: {
-        name: 'Cliente Demo',
-        email: 'cliente@ejemplo.com',
-        initials: 'CD',
-      },
-      breadcrumb: [
-        { label: 'Inicio', href: '/' },
-        { label: 'Mi cuenta' },
-      ],
-      pageTitle: 'Mi cuenta',
-      pageDescription: 'Consulta tus pedidos recientes y gestiona tu cuenta.',
-      action: { label: 'Seguir comprando', href: '/' },
-      stats: [
-        { label: 'Pedidos', value: '1' },
-        { label: 'Estado', value: 'Confirmado' },
-      ],
-    },
-    children: ['userPanel.orderHistory'],
-  },
-  'userPanel.orderHistory': {
-    type: 'OrderHistory',
-    props: {
-      orders: { $state: '/lastOrderLines' },
-      title: 'Historial de pedidos',
-      description: 'Tus compras recientes y su estado.',
-    },
-    on: {
-      viewOrder: { action: 'viewOrder' },
-      downloadInvoice: { action: 'downloadInvoice' },
-    },
-  },
-}
-
-const catalog = {
-  AppShell: {
-    props: appShellPropsSchema,
-    slots: ['default'],
-    description: 'Panel de cuenta con navegación lateral, cabecera y área de contenido.',
-  },
-  OrderHistory: {
-    props: orderHistoryPropsSchema,
-    description: 'Historial de pedidos del cliente.',
-  },
-}
-
-export const userPanel: ViewModule = {
-  name: 'user-panel',
-  elements,
-  catalog,
-  registry,
-  route: {
-    path: '/cuenta',
-    loaderName: 'userPanel',
-    layout: 'default',
-    metadata: {
-      title: 'Mi cuenta',
-      description: 'Consulta tu historial de pedidos y gestiona tu cuenta.',
-    },
-    entry: pageRoot('userPanel', ['userPanel.shell'], elements),
-  },
-  loader: {
-    userPanel: async () => {
-      const { products } = await getCatalog()
-      const placedAt = new Date()
-      const orderDate = placedAt.toISOString().slice(0, 10)
-      const lastOrderLines = products.slice(0, 3).map((product, index) => ({
-        name: product.title,
-        image: product.image,
-        color: 'Estándar',
-        size: 'Único',
-        quantity: index + 1,
-        price: product.price,
-        orderDate,
-      }))
-      // Only lastOrderLines is bound by this view's elements. lastOrder and
-      // orderPlaced belong to the checkout contract (StorefrontOrder shape and
-      // an ISO timestamp); writing demo values in a foreign shape here would
-      // leak into /checkout state and crash CheckoutConfirmation.
-      return { lastOrderLines }
-    },
-  },
-}

package/assets/templates/views/user-panel/registry.tsx

@@ -1,54 +0,0 @@
-'use client'
-
-// Thor Commerce view registry fragment: user-panel
-// Client boundary for the user-panel 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 {
-  AppShell1 as AppShellBlock,
-  OrderHistory1 as OrderHistoryBlock,
-} from '@thorprovider/blocks'
-import { useStateStore } from '@json-render/react'
-import { appShellPropsSchema, orderHistoryPropsSchema } from './schema'
-import type { ViewRegistry } from '../types'
-
-export const registry: ViewRegistry = {
-  AppShell: ({ props, children }) => {
-    const parsed = appShellPropsSchema.parse(props)
-    return (
-      <AppShellBlock
-        brandName={parsed.brandName}
-        navGroupLabel={parsed.navGroupLabel}
-        navItems={parsed.navItems}
-        user={parsed.user}
-        breadcrumb={parsed.breadcrumb}
-        pageTitle={parsed.pageTitle}
-        pageDescription={parsed.pageDescription}
-        action={parsed.action}
-        stats={parsed.stats}
-      >
-        {children}
-      </AppShellBlock>
-    )
-  },
-  OrderHistory: ({ props, emit }) => {
-    const parsed = orderHistoryPropsSchema.parse(props)
-    const { set } = useStateStore()
-    return (
-      <OrderHistoryBlock
-        orders={parsed.orders}
-        title={parsed.title}
-        description={parsed.description}
-        onViewDetails={() => {
-          set('/orderDetailsOpen', true)
-          emit('viewOrder')
-        }}
-        onDownloadInvoice={() => {
-          emit('downloadInvoice')
-        }}
-      />
-    )
-  },
-}

package/assets/templates/views/user-panel/schema.ts

@@ -1,79 +0,0 @@
-// Thor Commerce view schema fragment: user-panel
-// Zod mirrors of the block contracts for this view — the single source for the
-// catalog entries and the client-side registry parsing (json-render does not
-// validate props against the catalog itself, so the registry parses here).
-// Kept free of React and server imports so the Server Component module and the
-// 'use client' registry can share one contract.
-
-import { z } from 'zod'
-
-export const ctaSchema = z.object({ label: z.string(), href: z.string().optional() })
-
-// Mirrors the AppShell1NavItem block contract: `icon` is a NAME of the
-// AppShell1NavIcon set — the block resolves it to a component internally.
-export const appShellNavItemSchema = z.object({
-  label: z.string(),
-  href: z.string(),
-  icon: z.enum([
-    'layout-dashboard',
-    'package',
-    'user',
-    'settings',
-    'home',
-    'shopping-cart',
-    'bar-chart-3',
-    'users',
-    'folder-kanban',
-  ]),
-  active: z.boolean().optional(),
-})
-
-export const appShellUserSchema = z.object({
-  name: z.string(),
-  email: z.string(),
-  initials: z.string(),
-})
-
-export const breadcrumbItemSchema = z.object({
-  label: z.string(),
-  href: z.string().optional(),
-})
-
-export const statSchema = z.object({
-  label: z.string(),
-  value: z.string(),
-})
-
-// Mirrors the OrderHistory1Order block contract.
-export const orderLineSchema = z.object({
-  name: z.string(),
-  image: z.string(),
-  color: z.string(),
-  size: z.string(),
-  quantity: z.number(),
-  price: z.number(),
-  orderDate: z.string(),
-})
-
-export const appShellPropsSchema = z.object({
-  brandName: z.string().optional(),
-  navGroupLabel: z.string().optional(),
-  navItems: z.array(appShellNavItemSchema).optional(),
-  user: appShellUserSchema.optional(),
-  breadcrumb: z.array(breadcrumbItemSchema).optional(),
-  pageTitle: z.string().optional(),
-  pageDescription: z.string().optional(),
-  action: ctaSchema.optional(),
-  stats: z.array(statSchema).optional(),
-})
-
-export const orderHistoryPropsSchema = z.object({
-  orders: z.array(orderLineSchema),
-  title: z.string().optional(),
-  description: z.string().optional(),
-})
-
-export type AppShellNavItem = z.infer<typeof appShellNavItemSchema>
-export type AppShellProps = z.infer<typeof appShellPropsSchema>
-export type OrderLine = z.infer<typeof orderLineSchema>
-export type OrderHistoryProps = z.infer<typeof orderHistoryPropsSchema>

package/commands/sf-add-view.md

@@ -1,57 +0,0 @@
----
-description: "Add a view to a Thor Commerce storefront via the storefront CLI"
----
-
-Add one view to the current storefront. The CLI is the structural authority; do
-not copy templates or edit derived files.
-
-**Input**: view name, optionally a description of what it should contain.
-Examples:
-- `/sf-add-view product`
-- `/sf-add-view category specialize in power stations, use a dense grid`
-
-**Provided arguments**: $ARGUMENTS
-
-Use the `sf-view-gen` skill. The agent selects the change and delegates every
-structural write to the CLI; the user states the change in natural language and
-never types a command.
-
-**Flow:**
-1. `npx @thorprovider/storefront views --json` — confirm the view is supported
-   and read its `supportedIntents`, `registeredSlots`, `allowedSections`,
-   `maxSections`, and the top-level `sectionTypes`. Held units (`user-panel`,
-   recommendations) and the feature-owned `checkout` view are rejected; sections
-   are composable (step 4).
-2. Choose an intent per slot by meaning from the user's description.
-3. Delegate the write:
-   `npx @thorprovider/storefront view add <name> [--intent slot=intent] [--variant slot=Variant]`
-4. To compose **sections** on the new view, delegate to the CLI's section
-   operations (`section.add` / `section.remove` / `section.reorder`) in E1's
-   operations envelope `{ "formatVersion": 1, "operations": [ ... ] }`; `plan` is
-   read-only and `apply --plan` is the only writer:
-   - `section.add` (`view`, `type`, optional `id`, `variant`, `at`) adds an
-     editorial instance; `type` must be in the view's `allowedSections`, an
-     omitted `id` is auto-minted, and the add is rejected past `maxSections`.
-   - `section.remove` (`view`, `id`) removes an editorial instance; a registered
-     core slot (`slot:<slot>`) cannot be removed.
-   - `section.reorder` (`view`, `order`) requires `order` to be a permutation of
-     the view's current entry ids: every current id exactly once and every
-     registered slot present.
-
-   ```bash
-   npx @thorprovider/storefront plan --operations operations.json --out plan.json
-   npx @thorprovider/storefront apply --plan plan.json
-   ```
-
-   Only `faq` and `cta` are executable editorial types. Held types
-   (`testimonials`, `statistics`, `logoCloud`, `pricing`) are not available and
-   are refused with the bounded reason the registry reports. These three section
-   operations are implemented and supported — there is no proposed or future
-   section command.
-5. Report the result. If the CLI exits non-zero, show its message; never
-   hand-edit derived files to work around it.
-
-**Constraints:**
-- UI only `@thorprovider/blocks`; data only `@thorprovider/adapters` +
-  `@thorprovider/runtime/commerce`.
-- No manual template copy, no derived-file edits, no manual barrel edits.

package/commands/sf-feature.md

@@ -1,28 +0,0 @@
----
-description: "Add or remove a storefront feature bundle (e.g. checkout) via the storefront CLI"
----
-
-Add or remove a feature bundle in the current storefront. A feature may own
-views (plus its state/handlers/adapter wiring), an owned route, and instance
-mounts into a host view's slot; the CLI writes every derived file.
-
-**Input**: `add <name>` or `remove <name>` (e.g. `add checkout`).
-**Provided arguments**: $ARGUMENTS
-
-Use the `sf-feature` skill.
-
-**Flow:**
-1. `npx @thorprovider/storefront features --json` — confirm the feature is
-   supported. Held features are rejected before any write.
-2. Delegate the write:
-   `npx @thorprovider/storefront feature add|remove <name>`
-3. Report the result and any preserved user-owned file the CLI names. A
-   mount-based feature (e.g. `benefits` at `home.benefits`) leaves the host
-   view's customized content in place; the CLI reports its location.
-
-**Constraints:**
-- The curated MVP features are `checkout` (owns the `/checkout` route) and
-  `benefits` (mounts at `home.benefits`).
-- No derived-file edits; the CLI reconciles state/handlers/adapter wiring.
-- Purchase logic is owned by `single-tenant-commerce-mvp`; this installs
-  structural wiring only.

package/commands/sf-theme.md

@@ -1,26 +0,0 @@
----
-description: "Customize storefront theme: OKLCH colors (light/dark), typography, and identity metadata"
----
-
-Customize the theme and identity of the current storefront. The manifest
-(`storefront.config.json`) is the theme authority; the CLI applies deterministic
-changes.
-
-**Input**: optional — the wizard asks what to customize (colors, typography, identity, SEO, Open Graph).
-**Provided arguments**: $ARGUMENTS
-
-Use the `sf-theme-gen` skill.
-
-**Flow:**
-1. Run from inside the project (no directory argument).
-2. **Mode (light/dark/system)** is manifest state, not a hand edit:
-   `npx @thorprovider/storefront theme --mode light|dark|system`
-3. Colors/typography/metadata are user-owned edits in `app/globals.css` and
-   `app/layout.tsx`, following the skill's assets.
-4. `npx @thorprovider/storefront sync` and report.
-
-**Constraints (do not violate without explicit user authorization):**
-- Colors are CSS variables in OKLCH with complete background/foreground pairs
-  (light AND dark); never raw Tailwind color utilities for themed colors.
-- Never hand-edit `app/layout.tsx` for the mode — the CLI rewrites the
-  `ThemeProvider` wiring idempotently from the manifest.

package/commands/sf-view.md

@@ -1,67 +0,0 @@
----
-description: "Modify a storefront view's user-owned content/props/data, or compose its sections, via the storefront CLI"
----
-
-Modify an existing view in the current storefront.
-
-**Input**: view name followed by the change to make.
-Examples:
-- `/sf-view home add a FAQ section after the hero`
-- `/sf-view home move the CTA above the benefits`
-- `/sf-view category switch to a 4-column grid`
-
-**Provided arguments**: $ARGUMENTS
-
-Use the `sf-view-gen` skill. The agent selects the change and delegates every
-structural write to the CLI; the user describes the change in natural language
-and never types a command.
-
-**Flow:**
-1. Read the registry through the CLI
-   (`npx @thorprovider/storefront views --json`) for the view's
-   `registeredSlots`, `allowedSections`, `maxSections`, and the top-level
-   `sectionTypes`.
-2. If the change composes **sections**, delegate to the CLI's section
-   operations — do not edit derived files. They are carried in E1's operations
-   envelope `{ "formatVersion": 1, "operations": [ ... ] }`; `plan` is read-only
-   and validates the whole intended state, `apply --plan` is the only writer:
-   - `{ "op": "section.add", "view": "home", "type": "faq" }` — optional `id`,
-     `variant`, and `at` (0-based insertion index, default append). `type` must
-     be in the view's `allowedSections`; omit `id` to auto-mint one; rejected
-     when adding would exceed `maxSections`.
-   - `{ "op": "section.remove", "view": "home", "id": "home-faq-1" }` — removes
-     an editorial instance. A registered core slot (`slot:<slot>`) cannot be
-     removed.
-   - `{ "op": "section.reorder", "view": "home", "order": ["slot:hero",
-     "home-faq-1", "slot:benefits", "slot:categories"] }` — `order` must be a
-     permutation of the view's current entry ids: every current id exactly once
-     and every registered slot present.
-
-   ```bash
-   npx @thorprovider/storefront plan --operations operations.json --out plan.json
-   npx @thorprovider/storefront apply --plan plan.json
-   ```
-
-   Only `faq` and `cta` are executable editorial types. Held types
-   (`testimonials`, `statistics`, `logoCloud`, `pricing`) are not available and
-   are refused with the bounded reason the registry reports; never present a
-   held type as available. A removed instance's content is preserved in the
-   view's user-owned `content.ts`; re-adding the same `id` rebinds it, while an
-   auto-minted id never does. These three section operations are implemented and
-   supported — there is no proposed or future section command; the held section
-   types are the only not-yet-available part of this surface.
-3. If the change is a different block variant or an added/removed view, delegate
-   to the CLI: `npx @thorprovider/storefront view add|remove ...`.
-4. If the change is content/props/data, edit only the **user-owned** files:
-   `lib/<name>/views/<view>/content.ts`, `props.ts`, `data.ts`, `schema.ts`, and
-   `lib/<name>/mappers.ts`.
-5. Regenerate the derived wrappers around the edit:
-   `npx @thorprovider/storefront sync`.
-6. Report the result and the files touched.
-
-**Constraints:**
-- Preserve exported names, element ids, and the prop/event contracts the derived
-  wrapper imports.
-- Never edit derived files (`index.tsx`, `registry.tsx`, `views/index.ts`,
-  `views/registry.ts`, `catalog.ts`, `runtime.ts`, `spec/index.ts`).
-- UI only `@thorprovider/blocks`.

package/skills/building-storefronts/SKILL.md

@@ -1,178 +0,0 @@
----
-name: building-storefronts
-description: Load automatically when planning, researching, or implementing Medusa storefront features (calling custom API routes, SDK integration, React Query patterns, data fetching). REQUIRED for all storefront development in ALL modes (planning, implementation, exploration). Contains SDK usage patterns, frontend integration, and critical rules for calling Medusa APIs.
----
-
-# Medusa Storefront Development
-
-Frontend integration guide for building storefronts with Medusa. Covers SDK usage, React Query patterns, and calling custom API routes.
-
-## When to Apply
-
-**Load this skill for ANY storefront development task, including:**
-- Calling custom Medusa API routes from the storefront
-- Integrating Medusa SDK in frontend applications
-- Using React Query for data fetching
-- Implementing mutations with optimistic updates
-- Error handling and cache invalidation
-
-**Also load building-with-medusa when:** Building the backend API routes that the storefront calls
-
-## CRITICAL: Load Reference Files When Needed
-
-**The quick reference below is NOT sufficient for implementation.** You MUST load the reference file before writing storefront integration code.
-
-**Load this reference when implementing storefront features:**
-
-- **Calling API routes?** → MUST load `references/frontend-integration.md` first
-- **Using SDK?** → MUST load `references/frontend-integration.md` first
-- **Implementing React Query?** → MUST load `references/frontend-integration.md` first
-
-## Rule Categories by Priority
-
-| Priority | Category | Impact | Prefix |
-|----------|----------|--------|--------|
-| 1 | SDK Usage | CRITICAL | `sdk-` |
-| 2 | React Query Patterns | HIGH | `query-` |
-| 3 | Data Display | HIGH (includes CRITICAL price rule) | `display-` |
-| 4 | Error Handling | MEDIUM | `error-` |
-
-## Quick Reference
-
-### 1. SDK Usage (CRITICAL)
-
-- `sdk-always-use` - **ALWAYS use the Medusa JS SDK for ALL API requests** - NEVER use regular fetch()
-- `sdk-existing-methods` - For built-in endpoints, use existing SDK methods (`sdk.store.product.list()`, `sdk.admin.order.retrieve()`)
-- `sdk-client-fetch` - For custom API routes, use `sdk.client.fetch()`
-- `sdk-required-headers` - SDK automatically adds required headers (publishable API key for store, auth for admin) - regular fetch() missing these headers causes errors
-- `sdk-no-json-stringify` - **NEVER use JSON.stringify() on body** - SDK handles serialization automatically
-- `sdk-plain-objects` - Pass plain JavaScript objects to body, not strings
-- `sdk-locate-first` - Always locate where SDK is instantiated in the project before using it
-
-### 2. React Query Patterns (HIGH)
-
-- `query-use-query` - Use `useQuery` for GET requests (data fetching)
-- `query-use-mutation` - Use `useMutation` for POST/DELETE requests (mutations)
-- `query-invalidate` - Invalidate queries in `onSuccess` to refresh data after mutations
-- `query-keys-hierarchical` - Structure query keys hierarchically for effective cache management
-- `query-loading-states` - Always handle `isLoading`, `isPending`, `isError` states
-
-### 3. Data Display (HIGH)
-
-- `display-price-format` - **CRITICAL**: Prices from Medusa are stored as-is ($49.99 = 49.99, NOT in cents). Display them directly - NEVER divide by 100
-
-### 4. Error Handling (MEDIUM)
-
-- `error-on-error` - Implement `onError` callback in mutations to handle failures
-- `error-display` - Show error messages to users when mutations fail
-- `error-rollback` - Use optimistic updates with rollback on error for better UX
-
-## Critical SDK Pattern
-
-**ALWAYS pass plain objects to the SDK - NEVER use JSON.stringify():**
-
-```typescript
-// ✅ CORRECT - Plain object
-await sdk.client.fetch("/store/reviews", {
-  method: "POST",
-  body: {
-    product_id: "prod_123",
-    rating: 5,
-  }
-})
-
-// ❌ WRONG - JSON.stringify breaks the request
-await sdk.client.fetch("/store/reviews", {
-  method: "POST",
-  body: JSON.stringify({  // ❌ DON'T DO THIS!
-    product_id: "prod_123",
-    rating: 5,
-  })
-})
-```
-
-**Why this matters:**
-- The SDK handles JSON serialization automatically
-- Using JSON.stringify() will double-serialize and break the request
-- The server won't be able to parse the body
-
-## Common Mistakes Checklist
-
-Before implementing, verify you're NOT doing these:
-
-**SDK Usage:**
-- [ ] Using regular fetch() instead of the Medusa JS SDK (causes missing header errors)
-- [ ] Not using existing SDK methods for built-in endpoints (e.g., using sdk.client.fetch("/store/products") instead of sdk.store.product.list())
-- [ ] Using JSON.stringify() on the body parameter
-- [ ] Manually setting Content-Type headers (SDK adds them)
-- [ ] Hardcoding SDK import paths (locate in project first)
-- [ ] Not using sdk.client.fetch() for custom routes
-
-**React Query:**
-- [ ] Not invalidating queries after mutations
-- [ ] Using flat query keys instead of hierarchical
-- [ ] Not handling loading and error states
-- [ ] Forgetting to disable buttons during mutations (isPending)
-
-**Data Display:**
-- [ ] **CRITICAL**: Dividing prices by 100 when displaying (prices are stored as-is: $49.99 = 49.99, NOT in cents)
-
-**Error Handling:**
-- [ ] Not implementing onError callbacks
-- [ ] Not showing error messages to users
-- [ ] Not handling network failures gracefully
-
-## How to Use
-
-**For detailed patterns and examples, load reference file:**
-
-```
-references/frontend-integration.md - SDK usage, React Query patterns, API integration
-```
-
-The reference file contains:
-- Step-by-step SDK integration patterns
-- Complete React Query examples
-- Correct vs incorrect code examples
-- Query key best practices
-- Optimistic update patterns
-- Error handling strategies
-
-## When to Use MedusaDocs MCP Server
-
-**Use this skill for (PRIMARY SOURCE):**
-- How to call custom API routes from storefront
-- SDK usage patterns (sdk.client.fetch)
-- React Query integration patterns
-- Common mistakes and anti-patterns
-
-**Use MedusaDocs MCP server for (SECONDARY SOURCE):**
-- Built-in SDK methods (sdk.admin.*, sdk.store.*)
-- Official Medusa SDK API reference
-- Framework-specific configuration options
-
-**Why skills come first:**
-- Skills contain critical patterns like "don't use JSON.stringify" that MCP doesn't emphasize
-- Skills show correct vs incorrect patterns; MCP shows what's possible
-- Planning requires understanding patterns, not just API reference
-
-## Integration with Backend
-
-**⚠️ CRITICAL: ALWAYS use the Medusa JS SDK - NEVER use regular fetch()**
-
-When building features that span backend and frontend:
-
-1. **Backend (building-with-medusa skill):** Module → Workflow → API Route
-2. **Storefront (this skill):** SDK → React Query → UI Components
-3. **Connection:**
-   - Built-in endpoints: Use existing SDK methods (`sdk.store.product.list()`)
-   - Custom API routes: Use `sdk.client.fetch("/store/my-route")`
-   - **NEVER use regular fetch()** - missing publishable API key causes errors
-
-**Why the SDK is required:**
-- Store routes need `x-publishable-api-key` header
-- Admin routes need `Authorization` and session headers
-- SDK handles all required headers automatically
-- Regular fetch() without headers → authentication/authorization errors
-
-See `building-with-medusa` for backend API route patterns.