@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/skills/storefront-workflow/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: storefront-workflow
+description: The Thor Commerce storefront workflow model — bootstrap, compose, customize, verify — and the CLI/manifest authority. Use when working in a generated storefront, before adding/removing views or features, changing the theme, or editing storefront files.
+---
+
+# Storefront workflow model
+
+A generated storefront is defined by a **manifest** (`storefront.config.json` at
+the project root) and produced by the `storefront` CLI. The manifest is the
+structural source of truth; the CLI is the only writer of derived files; the
+developer (or agent) edits only user-owned files and the bounded surface of the
+two external files.
+
+Run every command from inside the project (the CLI resolves the project from the
+current directory). The CLI is installed as a dependency of the project, so
+invoke it with `npx @thorprovider/storefront <command>` or `yarn storefront`.
+
+## The four phases
+
+**bootstrap → compose → customize → verify**
+
+### 1. Bootstrap
+
+Create the project. The CLI scaffolds Next.js, installs the pinned candidate
+toolset, writes the initial manifest, and reconciles.
+
+```bash
+npx @thorprovider/storefront create <dir> --name <name> --preset <preset> [--starter]
+```
+
+Pass `--starter` to seed the full curated composition — every curated view and
+feature — in the same pass; omit it for the minimal baseline.
+
+Authority: **CLI only.** Do not scaffold or copy templates by hand.
+
+### 2. Compose
+
+Change the structural composition. Each command validates, updates the manifest,
+and reconciles the derived files.
+
+```bash
+npx @thorprovider/storefront view add|remove <name> [--intent slot=intent] [--variant slot=Variant]
+npx @thorprovider/storefront feature add|remove <name>
+npx @thorprovider/storefront theme --mode light|dark|system
+npx @thorprovider/storefront plan --operations <file> [--out <file>] [--json]
+npx @thorprovider/storefront apply --plan <file> [--json]
+```
+
+Section composition (`section.add` / `section.remove` / `section.reorder`) goes
+through the same operations envelope (`{ "formatVersion": 1, "operations": [ ... ] }`):
+`plan` is read-only and validates the whole intended state, `apply --plan` is the
+only writer.
+
+Authority: **CLI only.** Agents choose *what* to compose by reading the curated
+registry at runtime and then delegate the write to the CLI. The user states the
+change in natural language and never types a command.
+
+### 3. Customize
+
+Edit the **user-owned** files (content, props, data, local schema, mappers), and —
+within narrow bounds — the two **external** files described below. Reconcile never
+rewrites user-owned files; it regenerates the thin derived wrappers around them,
+and appends CLI-managed markers to the external files idempotently.
+
+Authority: **agent/developer.** Hand-edit only user-owned files and the bounded
+external surface.
+
+#### Trivial vs non-trivial — and the spec-driven loop
+
+Classify the customization before editing:
+
+- **Trivial** — the CLI can perform it deterministically and record it in the
+  manifest (`storefront theme --mode`, `view add|remove`, `feature add|remove`,
+  `setup`). Run the CLI operation; it **does not** require an OpenSpec change —
+  `storefront.config.json` is its record.
+- **Non-trivial** — the change needs judgment: content authoring, prop/data
+  mapping, composition reshaping, or a cross-file redesign whose acceptance is not
+  a CLI assertion. Drive it through the **spec-driven loop** and surface the five
+  stages to the user: **explore → plan → build → verify → inform**. Open the change
+  through the OpenSpec workflow (`openspec/config.yaml` is seeded with this model),
+  carry it to completion, and **never** ask the user to run `openspec`, name an
+  artifact, or approve one artifact at a time. Structural edits inside the loop
+  still go through the CLI; the loop adds intent and acceptance, not a second
+  writer.
+
+A non-trivial change is not done until `storefront sync` and `storefront doctor`
+pass and the change's acceptance is met.
+
+### 4. Verify
+
+Regenerate and check.
+
+```bash
+npx @thorprovider/storefront sync     # reconcile derived files to the manifest
+npx @thorprovider/storefront doctor   # composition drift + truthful version/BOM
+```
+
+Authority: **CLI.** A build (`yarn build`) is the final acceptance; `doctor`
+must report no drift.
+
+## Read the curated registry through the CLI (never a copied list)
+
+The installable set is whatever the registry reports; do not trust a list copied
+into any skill. Read it at runtime, from the project root:
+
+```bash
+npx @thorprovider/storefront views --json      # curated views, routes, intents/variants, installed
+npx @thorprovider/storefront features --json   # feature bundles, owned views/routes, mounts
+npx @thorprovider/storefront recipes --json    # whole curated registry (views + features)
+```
+
+- `views --json` and `recipes --json` include the top-level `sectionTypes` list
+  that marks each section type `executable` or `held` (with a reason). That list
+  is the authority for which section types may be composed.
+- `npx @thorprovider/storefront sections --json` reports only the currently
+  **installed** section instances; use it when the current composition matters,
+  never as the set of available types.
+- Publishing a fixed view/feature/section list in a skill is a bug: the registry
+  is the single source, so add or remove a unit there, not in this text.
+
+A unit the registry does not expose is a **gap to report**, not a reason to
+install another UI framework, hand-edit a derived file, or scaffold structure
+outside the CLI.
+
+## File ownership
+
+| Class | Examples | Who writes it |
+|---|---|---|
+| **Derived** | `views/index.ts`, `views/registry.ts`, `index.tsx`, `registry.tsx`, `catalog.ts`, `runtime.ts`, `spec/index.ts`, `state.ts`, `handlers.ts`, `features/*/adapter.ts` | CLI (reconcile); never hand-edited |
+| **User-owned** | `views/<view>/content.ts`, `props.ts`, `data.ts`, `schema.ts`, `mappers.ts`, `icon-map.ts`, `shell/**` | developer/agent |
+| **External** | `app/globals.css`, `app/layout.tsx` (plus create-next-app/shadcn support files) | developer/agent within the bounded surface below; the CLI only appends idempotent markers |
+
+Removing a unit removes its derived wrapper but **preserves** any customized
+user-owned file and reports its location.
+
+## Bounded external customization
+
+`app/globals.css` and `app/layout.tsx` are `external` files. The supported
+customization surface is deliberately narrow:
+
+- **`app/globals.css`** — theme tokens and their foreground pairs, the Tailwind
+  `@theme` bridge, font variable wiring.
+- **`app/layout.tsx`** — font loading (`next/font`) and global identity/metadata
+  (title, description, Open Graph / Twitter).
+
+Everything else in those files is CLI-managed and must survive: the stylesheet
+import, the provider import and its marker, the theme-mode marker, and the block
+token contract. The CLI appends idempotently, so a `sync` must not duplicate a
+marker or drop an edit. Use the `sf-theme-gen` skill for these files; never edit
+the mode wiring by hand. Per-entity SEO still comes from backend entities — global
+customization cannot invent a canonical.
+
+## Manifest authority
+
+- `storefront.config.json` declares the name, theme, installed views, installed
+  features, and per-slot intents. Every structural command edits it and then
+  reconciles.
+- `.opencode/storefront.json` is the machine-managed install record (suite
+  version, declared compatibility ranges, resolved versions, lockfile hash,
+  owned asset BOM). `doctor` validates it against the live project.
+- A **legacy** (pre-manifest) project is detected and refused with a no-write
+  diagnostic.
+
+## Pinning and prerequisites
+
+- Node `>=20.9.0`, Yarn 4, `node-modules` linker. The generated project pins the
+  exact candidate toolset; `doctor` reports a linker/version mismatch non-zero.
+- The `checkout` feature ships structural wiring only; the purchase flow is
+  owned by the separate `single-tenant-commerce-mvp` change. A generated
+  storefront is not a complete commerce implementation on its own.
+
+## References
+
+Relative to this `SKILL.md`:
+
+- `references/design-consistency.md` — keeping UI changes consistent with the
+  scaffold's brand and tokens.
+- `references/mobile-responsiveness.md` — mobile-first storefront patterns.
+- `references/seo.md` — ecommerce SEO and structured data.

package/skills/{storefront-best-practices/reference/design.md → storefront-workflow/references/design-consistency.md}

@@ -1,5 +1,11 @@
 # Design Guidelines
 
+Reference material for the `storefront-workflow` skill: guardrails for keeping
+UI changes consistent with an already-scaffolded storefront's brand. The CLI and
+the manifest remain the structural authority; this file only guides visual
+consistency inside the bounded surface (`app/globals.css` tokens, `app/layout.tsx`
+fonts/identity) and `@thorprovider/blocks` usage.
+
 ## Contents
 
 - [Overview](#overview)
@@ -243,36 +249,14 @@ When starting a new project WITHOUT existing theme:
 This helps me understand your aesthetic preferences."
 ```
 
-### Setup Theme Configuration
-
-After gathering preferences, configure Tailwind theme:
-
-```typescript
-// tailwind.config.ts
-export default {
-  theme: {
-    extend: {
-      colors: {
-        primary: '#3B82F6',     // User's primary color
-        secondary: '#8B5CF6',    // User's secondary
-        accent: '#F59E0B',       // Accent if needed
-        // Full scales if sophisticated design
-        brand: {
-          50: '#eff6ff',
-          500: '#3b82f6',
-          900: '#1e3a8a',
-        }
-      },
-      fontFamily: {
-        sans: ['Inter', 'system-ui', 'sans-serif'],
-        heading: ['Poppins', 'sans-serif'],
-      },
-    },
-  },
-}
-```
+### Where tokens live
 
-**Use Tailwind CSS for all new projects** - industry standard for ecommerce, highly customizable, excellent DX.
+The scaffold ships its design tokens as CSS variables in `app/globals.css`
+(`:root` + `.dark`) with a Tailwind v4 `@theme` bridge. That file is `external`
+with a bounded surface: change token values and foreground pairs, fonts, and
+global identity only, and keep the CLI-managed imports/markers intact. Use the
+`sf-theme-gen` skill for color, typography, and identity changes; do not
+introduce a separate Tailwind theme configuration.
 
 ## Decision Tree
 

package/CHANGELOG.md

@@ -1,61 +0,0 @@
-# Changelog
-
-## 0.4.0
-
-- **Renamed package**: `@thorprovider/create-storefront` → `@thorprovider/storefront`;
-  the `bin` is now `storefront` (`npx @thorprovider/storefront create`).
-- **Single scaffold command**: `storefront create <dir>` scaffolds the storefront and
-  installs the OpenCode command suite in the same run. The standalone `install` action
-  is gone; `storefront update` refreshes, prunes removed files, and migrates the
-  version record.
-- **Interactive wizard**: on a TTY, `create` prompts for name, site name, backend URL,
-  and preset (Maia preselected). Brand color is decided via `/sf-theme`, not the wizard.
-  Without a TTY, every required input must be passed as a flag or the command fails
-  fast before writing anything.
-- **Command surface**: `<dir>` is positional; `--dir` is removed; `--name` is a flag or
-  wizard prompt. Commands are `storefront create|update|doctor <dir>`.
-- **Removed `/sf-init`**: the `sf-init` command and `sf-scaffold` skill are gone.
-  Scaffolding is fully deterministic inside the binary.
-- **Decoupled templates**: the scaffold templates moved from the `sf-scaffold` skill
-  into `assets/templates/` at the package root.
-- **Version record**: `.opencode/storefront.json` (replacing `.create-storefront.json`);
-  `update` migrates existing installs.
-
-## 0.3.0
-
-- **Embedded assets**: each skill now carries the templates, recipes, and scripts it
-  uses inside its own directory (`assets/`, `scripts/`, `references/`) and addresses
-  them by relative path. No path marker is needed to locate the package.
-- **Versioned install command**: `bin` exposes `create-storefront` with `install`,
-  `update`, and `doctor`. Installation is an explicit command; there is no
-  `postinstall`. The installer records `{ version, installedAt }` in
-  `.opencode/.create-storefront.json` (replacing the `.create-storefront-root` marker).
-- **Single source, generated copies**: `recipes/` stays the single source at the
-  package root; `scripts/sync-assets.mjs` generates the per-skill copies and a
-  `--check` mode fails on drift. The check runs at build/pretest and before the
-  installer copies anything into a target project.
-- **Positive source-of-truth rule**: the skills state that the workflow uses the assets
-  inside the skill and that an undecided choice is resolved by asking the user.
-- **Named interfaces**: each skill declares the target-project inputs it reads and the
-  outputs it produces.
-- **General self-containment check**: the test fails on any absolute machine path in a
-  shipped artifact, independent of any name.
-
-## 0.2.0
-
-- Per-view templates: every recipe view (`home`, `product`, `category`, `checkout`,
-  `user-panel`) ships as a self-contained module under `templates/views/<view>/`.
-- Generated storefronts now compose views through a barrel (`lib/<name>/views/index.ts`);
-  shared files (`catalog.ts`, `registry.tsx`, `runtime.ts`, `spec/index.ts`) derive from
-  the registered views and are never edited per view.
-- `/sf-add-view` copies a view module and registers one barrel entry, substituting only
-  the imported block identifier for the resolved variant. No hand-authored wiring.
-- Optional sections (testimonials, FAQ, statistics, logo cloud, pricing) ship as
-  fragments under `views/sections/` and are validated against `recipes/sections.json`.
-- `sf-scaffold` copies `templates/app/` plus `templates/views/home/` and registers
-  `home` in the barrel.
-- Templates and skills no longer reference any repository-local application.
-
-## 0.1.3
-
-- Previous release.

package/commands/sf-add-view.md

@@ -1,26 +0,0 @@
----
-description: "Add a single view to an existing Thor Commerce storefront (product, category, checkout, user-panel)"
----
-
-Add one view to an existing Thor Commerce storefront, generated from a recipe.
-
-**Input**: view name, optionally followed by a description of what the view should contain or emphasize.
-Examples:
-- `/sf-add-view product`
-- `/sf-add-view category specialize in power stations, use a dense grid`
-- `/sf-add-view checkout keep it single-page`
-
-**Provided arguments**: $ARGUMENTS
-
-Use the `sf-view-gen` skill.
-
-The skill generates from the assets inside its own directory (`assets/recipes/`, `assets/templates/views/`); when a choice is not resolved there, it asks you.
-
-**Reads (target project):** existence of `package.json`, `lib/<name>/`, `.opencode/`, and the view name + description.
-**Writes (target project):** the view module and one barrel entry, all reported.
-
-**Constraints (do not violate without explicit user authorization):**
-- Allowed view names: `home`, `product`, `category`, `checkout`, `user-panel`
-- Block variants and optional sections MUST come from the skill's own `assets/recipes/` (`recipes.json`, `archetypes.json`, `sections.json`)
-- UI components come ONLY from `@thorprovider/blocks`
-- Data access goes ONLY through `@thorprovider/adapters` / `@thorprovider/runtime/commerce`

package/commands/sf-theme.md

@@ -1,20 +0,0 @@
----
-description: "Customize storefront theme: OKLCH colors (light/dark), typography, and identity metadata"
----
-
-Customize the theme and identity of a Thor Commerce storefront.
-
-**Input**: optional — the wizard asks what to customize (colors, typography, identity, SEO, Open Graph).
-**Provided arguments**: $ARGUMENTS
-
-Use the `sf-theme-gen` skill.
-
-The skill works from its own directory and the vendored `shadcn-theming` skill beside it; when a choice is not resolved there, it asks you.
-
-**Reads (target project):** existence of `package.json`, `lib/<name>/`, `.opencode/`, and the wizard answers.
-**Writes (target project):** `app/globals.css` and `app/layout.tsx`, all reported.
-
-**Constraints (do not violate without explicit user authorization):**
-- Colors are CSS variables in OKLCH with complete background/foreground pairs (light AND dark)
-- Never use raw Tailwind color utilities for themed colors
-- Typography and metadata follow the skill's own assets

package/commands/sf-view.md

@@ -1,25 +0,0 @@
----
-description: "Modify an existing storefront view's spec while preserving its structure"
----
-
-Modify an existing view in a Thor Commerce storefront.
-
-**Input**: view name followed by the change to make.
-Examples:
-- `/sf-view home add a statistics band after the hero`
-- `/sf-view category switch to a 4-column grid`
-
-**Provided arguments**: $ARGUMENTS
-
-Use the `sf-view-gen` skill (modification workflow).
-
-The skill works from the assets inside its own directory (`assets/recipes/`, `assets/templates/views/`); when a choice is not resolved there, it asks you.
-
-**Reads (target project):** existence of `package.json`, `lib/<name>/`, `.opencode/`, the existing view module, and the change requested.
-**Writes (target project):** the edited view module, all reported.
-
-**Constraints (do not violate without explicit user authorization):**
-- Allowed view names: `home`, `product`, `category`, `checkout`, `user-panel`
-- Preserve element ids, `type`, untouched `props`, `$state` bindings, and `on` wiring
-- Only add block variants/sections declared in the skill's own `assets/recipes/`
-- UI components come ONLY from `@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.