@thorprovider/create-storefront 0.1.1

package/README.md

@@ -0,0 +1,119 @@
+---
+title: "@thorprovider/create-storefront"
+purpose: "Installable command suite that scaffolds and customizes Thor Commerce storefronts"
+lastReviewed: "2026-09-28"
+---
+
+# @thorprovider/create-storefront
+
+Installable command suite that scaffolds and customizes Thor Commerce storefronts.
+
+It ships a set of `/sf-*` OpenCode commands, their supporting skills, static project
+templates, a recipe registry, and vendored skills — and installs them into any
+project's `.opencode/` directory. Nothing else from the Thor Commerce monorepo is
+required at generation time.
+
+## Requirements
+
+| Requirement | Supported |
+| --- | --- |
+| Node.js | >= 18.17.0 |
+| Package manager | pnpm (for generated projects) |
+| OpenCode | a version that supports project skills in `.opencode/skills/` |
+| OS | macOS, Linux, Windows (via WSL) |
+
+## Install
+
+From the root of the project where you want the commands available:
+
+```bash
+pnpm dlx @thorprovider/create-storefront
+```
+
+Or, once installed as a dependency:
+
+```bash
+create-storefront            # installs into ./.opencode
+create-storefront --dir apps/my-store
+```
+
+The installer copies `commands/` and all skills under `skills/` (own skills and
+vendored skills, flat) into `<target>/.opencode/`. It is idempotent: running it again
+overwrites with the same versioned files and leaves everything else untouched.
+
+After installing, open the project in OpenCode and run:
+
+```
+/sf-init
+```
+
+## What gets installed
+
+```
+<project>/.opencode/
+  .create-storefront-root      # absolute package root (lets skills find templates/ + recipes/)
+  commands/
+    sf-init.md
+    sf-add-view.md
+    sf-view.md
+    sf-theme.md
+  skills/
+    sf-scaffold/
+    sf-view-gen/
+    sf-theme-gen/
+    nextjs-shadcn/
+    shadcn-theming/
+    shadcn-component-discovery/
+    storefront-best-practices/
+    building-storefronts/
+```
+
+`templates/` and `recipes/` are **not** copied into the project. They are generation assets that stay in the installed package; the `.create-storefront-root` marker lets the skills resolve them at generation time. Keep the package installed (as a dependency or globally) while you use the commands.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `/sf-init` | Wizard: scaffold a new storefront with Next.js, `@thorprovider/blocks`, `@thorprovider/adapters` (Medusa), json-render, and a home view |
+| `/sf-add-view <view>` | Add one view incrementally (`product`, `category`, `checkout`, `user-panel`) |
+| `/sf-view <view> <change>` | Modify an existing view's spec, preserving structure |
+| `/sf-theme` | Customize OKLCH color tokens (light/dark), typography, and identity metadata |
+
+## First run
+
+After installing into a project, open OpenCode in that project and run:
+
+```
+/sf-init
+```
+
+The wizard asks for a storefront name, Medusa backend URL, site name, and brand
+color. It scaffolds a Next.js + json-render storefront with a home view, using
+only `@thorprovider/blocks` for UI and `@thorprovider/adapters` for data.
+
+Then grow the storefront incrementally:
+
+```
+/sf-add-view product      # add a view from its recipe
+/sf-view home add a testimonials section   # modify an existing view
+/sf-theme                 # colors, typography, identity
+```
+
+Generated projects expect a Medusa backend. Set `MEDUSA_BACKEND_URL` (and
+`MEDUSA_REGION_ID`, `MEDUSA_PUBLISHABLE_KEY` as needed) in `.env.local`. Use the
+`mock` adapter data source during local development.
+
+## Design guarantees
+
+- **Self-contained**: templates and skills travel with the package; no dependency on
+  the Thor Commerce monorepo or on machine-global skills at generation time.
+- **Stack-constrained**: UI comes only from `@thorprovider/blocks`; data only from
+  `@thorprovider/adapters` and `@thorprovider/storefronts/commerce`.
+- **Varied output**: a recipe registry lets the skills pick block variants and optional
+  sections (testimonials, FAQ, statistics, logo cloud, pricing) from your description,
+  so sites are not identical.
+
+## Maintenance
+
+See `VENDOR.md` for how vendored skills are refreshed and how to bump
+templates.

package/bin/install.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// @thorprovider/create-storefront installer
+// Copies commands/ and skills/ into <project>/.opencode/ (openspec-style).
+// Idempotent: safe to re-run. Works without the Thor Commerce monorepo.
+//
+// Templates/ and recipes/ are NOT copied: they are generation assets that live
+// inside the installed package and are resolved by the skills at generation
+// time (see skills/sf-*/SKILL.md "Resolving package assets").
+
+import { cp, mkdir, readdir, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const PKG_ROOT = resolve(__dirname, '..')
+
+// Baked into the installed skills so they can locate templates/ and recipes/
+// at generation time without walking the target filesystem.
+const ASSET_MARKER_FILE = '.create-storefront-root'
+
+function parseArgs(argv) {
+  const out = { dir: process.cwd(), force: false }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--dir' || a === '-d') out.dir = resolve(argv[++i] ?? '.')
+    else if (a === '--force' || a === '-f') out.force = true
+    else if (a === '--help' || a === '-h') out.help = true
+  }
+  return out
+}
+
+const HELP = `@thorprovider/create-storefront
+
+Usage:
+  create-storefront [--dir <path>] [--force]
+
+Installs the sf-* commands and skills into <path>/.opencode/.
+Default <path> is the current working directory.
+
+Options:
+  -d, --dir <path>   Target project root (default: cwd)
+  -f, --force        Overwrite files that already exist
+  -h, --help         Show this help
+`
+
+async function copyDir(from, to, force) {
+  if (!existsSync(from)) return 0
+  await mkdir(to, { recursive: true })
+  let count = 0
+  const entries = await readdir(from, { withFileTypes: true })
+  for (const entry of entries) {
+    const src = join(from, entry.name)
+    const dest = join(to, entry.name)
+    if (entry.isDirectory()) {
+      count += await copyDir(src, dest, force)
+    } else {
+      const exists = existsSync(dest)
+      if (exists && !force) continue
+      await cp(src, dest)
+      count++
+    }
+  }
+  return count
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+  if (args.help) {
+    console.log(HELP)
+    return
+  }
+
+  const target = args.dir
+  if (!existsSync(target)) {
+    console.error(`Target directory does not exist: ${target}`)
+    process.exitCode = 1
+    return
+  }
+  const opencodeDir = join(target, '.opencode')
+
+  console.log(`Installing @thorprovider/create-storefront into ${opencodeDir}`)
+
+  const commands = await copyDir(
+    join(PKG_ROOT, 'commands'),
+    join(opencodeDir, 'commands'),
+    args.force,
+  )
+  const ownSkills = await copyDir(
+    join(PKG_ROOT, 'skills'),
+    join(opencodeDir, 'skills'),
+    args.force,
+  )
+
+  // Record the package root so installed skills can resolve templates/ and
+  // recipes/ (generation assets) without the monorepo or a symlink.
+  const markerPath = join(opencodeDir, ASSET_MARKER_FILE)
+  if (args.force || !existsSync(markerPath)) {
+    await writeFile(markerPath, `${PKG_ROOT}\n`, 'utf8')
+  }
+
+  console.log(`  commands: ${commands} file(s)`)
+  console.log(`  skills:   ${ownSkills} file(s)`)
+  console.log(`  assets:   ${PKG_ROOT} (templates/, recipes/)`)
+  console.log('')
+  console.log('Done. Available in OpenCode:')
+  console.log('  /sf-init  /sf-add-view  /sf-view  /sf-theme')
+  if (!args.force) {
+    console.log('(Existing files were left untouched. Use --force to overwrite.)')
+  }
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exitCode = 1
+})

package/commands/sf-add-view.md

@@ -0,0 +1,21 @@
+---
+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.
+
+**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 `recipes/` (`recipes.json`, `sections.json`)
+- UI components come ONLY from `@thorprovider/blocks`
+- Data access goes ONLY through `@thorprovider/adapters` / `@thorprovider/storefronts/commerce`

package/commands/sf-init.md

@@ -0,0 +1,16 @@
+---
+description: "Initialize a new Thor Commerce storefront (json-render + @thorprovider/blocks + Medusa via @thorprovider/adapters)"
+---
+
+Initialize a new Thor Commerce storefront via an interactive wizard.
+
+**Input**: no arguments required — the wizard collects configuration.
+**Provided arguments**: $ARGUMENTS
+
+Use the `sf-scaffold` skill to perform the initialization.
+
+**Constraints (do not violate without explicit user authorization):**
+- UI components come ONLY from `@thorprovider/blocks`
+- Backend access goes ONLY through `@thorprovider/adapters` / `@thorprovider/storefronts/commerce`
+- Views and components are generated from this package's `templates/` and `recipes/`
+- Default scaffold is the `home` view only; other views are added with `/sf-add-view`

package/commands/sf-theme.md

@@ -0,0 +1,15 @@
+---
+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.
+
+**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 package `templates/`

package/commands/sf-view.md

@@ -0,0 +1,20 @@
+---
+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).
+
+**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 `recipes/`
+- UI components come ONLY from `@thorprovider/blocks`

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@thorprovider/create-storefront",
+  "version": "0.1.1",
+  "description": "Installable OpenCode command suite that scaffolds Thor Commerce json-render storefronts (Next.js, @thorprovider/blocks, @thorprovider/adapters, Medusa)",
+  "type": "module",
+  "bin": {
+    "create-storefront": "./bin/install.js"
+  },
+  "files": [
+    "bin",
+    "commands",
+    "skills",
+    "templates",
+    "recipes",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "scripts": {
+    "install:opencode": "node ./bin/install.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thorprovider/thor-commerce",
+    "directory": "packages/create-storefront"
+  },
+  "keywords": [
+    "thor-commerce",
+    "opencode",
+    "storefront",
+    "json-render",
+    "scaffolding"
+  ],
+  "license": "MIT"
+}

package/recipes/archetype.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "archetype.schema.json",
+  "title": "Storefront archetype manifest",
+  "description": "Maps slots to named intents. Each intent resolves to a block variant that must be allowed by the view recipe for that slot.",
+  "type": "object",
+  "required": ["version", "slots"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "type": "string" },
+    "description": { "type": "string" },
+    "slots": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "required": ["default", "intents"],
+        "additionalProperties": false,
+        "properties": {
+          "default": { "type": "string" },
+          "intents": {
+            "type": "object",
+            "minProperties": 1,
+            "additionalProperties": {
+              "type": "object",
+              "required": ["variant", "when"],
+              "additionalProperties": false,
+              "properties": {
+                "variant": { "type": "string" },
+                "when": { "type": "string", "minLength": 10 }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/recipes/archetypes.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "./archetype.schema.json",
+  "version": "1.0.0",
+  "description": "Archetype (intent) layer. Maps a slot to named intents so selection is by meaning, not by variant ordinal. Each intent resolves to a variant that MUST be allowed by the recipe for that slot.",
+  "slots": {
+    "home.hero": {
+      "default": "showcase",
+      "intents": {
+        "compact": {
+          "variant": "StorefrontHero1",
+          "when": "A simple, text-forward hero with a single call to action and no product showcase."
+        },
+        "showcase": {
+          "variant": "StorefrontHero2",
+          "when": "A product-led hero that displays featured products alongside the headline."
+        },
+        "editorial": {
+          "variant": "StorefrontHero5",
+          "when": "A storytelling or brand-editorial hero with strong imagery and a narrative tone."
+        },
+        "promotional": {
+          "variant": "StorefrontHero6",
+          "when": "A campaign hero built around an offer, discount, or seasonal promotion."
+        }
+      }
+    },
+    "home.benefits": {
+      "default": "compact",
+      "intents": {
+        "compact": {
+          "variant": "Feature1",
+          "when": "A short list of benefits with icons and one-line descriptions."
+        },
+        "detailed": {
+          "variant": "Feature2",
+          "when": "Benefits that need longer explanations, richer layout, or supporting media."
+        }
+      }
+    },
+    "home.categories": {
+      "default": "standard",
+      "intents": {
+        "standard": {
+          "variant": "ProductCategory2",
+          "when": "A balanced grid of category cards with image and label."
+        },
+        "iconGrid": {
+          "variant": "ProductCategory1",
+          "when": "A compact icon-based category grid for many small categories."
+        },
+        "featured": {
+          "variant": "ProductCategory4",
+          "when": "Few, large featured category tiles that act as primary navigation."
+        },
+        "editorial": {
+          "variant": "ProductCategory5",
+          "when": "Category tiles presented as editorial imagery blocks."
+        }
+      }
+    },
+    "product.overview": {
+      "default": "standard",
+      "intents": {
+        "standard": {
+          "variant": "ProductOverview1",
+          "when": "A straightforward product detail layout: gallery, title, price, add to cart."
+        },
+        "gallery": {
+          "variant": "ProductOverview2",
+          "when": "The product needs emphasis on a large image gallery with thumbnails."
+        },
+        "rich": {
+          "variant": "ProductOverview5",
+          "when": "A detailed product page with tabs, specs, and extensive structured information."
+        }
+      }
+    },
+    "product.reviews": {
+      "default": "list",
+      "intents": {
+        "list": {
+          "variant": "ReviewRating1",
+          "when": "A simple list of customer reviews with star ratings."
+        },
+        "summary": {
+          "variant": "ReviewRating2",
+          "when": "Reviews led by an aggregate rating summary and distribution."
+        }
+      }
+    },
+    "category.filter": {
+      "default": "sidebar",
+      "intents": {
+        "inline": {
+          "variant": "CategoryFilter1",
+          "when": "A compact inline filter bar above the product grid."
+        },
+        "sidebar": {
+          "variant": "CategoryFilter2",
+          "when": "A left sidebar with facets, price range, and sort controls."
+        },
+        "rich": {
+          "variant": "CategoryFilter4",
+          "when": "Advanced faceted filtering with multiple facet groups and active-filter chips."
+        }
+      }
+    },
+    "checkout.checkout": {
+      "default": "singlePage",
+      "intents": {
+        "singlePage": {
+          "variant": "CheckoutForm1",
+          "when": "A single-page checkout combining contact, shipping, and payment."
+        },
+        "multiStep": {
+          "variant": "CheckoutForm2",
+          "when": "A stepper checkout split into address, delivery, and payment steps."
+        },
+        "compact": {
+          "variant": "CheckoutForm3",
+          "when": "A minimal one-column checkout for fast, low-friction purchase."
+        }
+      }
+    },
+    "user-panel.shell": {
+      "default": "standard",
+      "intents": {
+        "standard": {
+          "variant": "AppShell1",
+          "when": "A standard account shell with side navigation and content area."
+        }
+      }
+    },
+    "user-panel.orderHistory": {
+      "default": "compact",
+      "intents": {
+        "compact": {
+          "variant": "OrderHistory1",
+          "when": "A concise list of past orders with status and totals."
+        },
+        "detailed": {
+          "variant": "OrderHistory2",
+          "when": "Order history with line-item detail, tracking, and reorder actions."
+        }
+      }
+    }
+  }
+}

package/recipes/recipe.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://thorcommerce.dev/create-storefront/recipe.schema.json",
+  "title": "Thor Commerce Storefront View Recipe",
+  "type": "object",
+  "required": ["version", "views"],
+  "properties": {
+    "version": { "type": "string" },
+    "views": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "name",
+          "description",
+          "route",
+          "loader",
+          "requiredDataKeys",
+          "defaultVariants",
+          "allowedVariants",
+          "optionalSections"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "enum": ["home", "product", "category", "checkout", "user-panel"]
+          },
+          "description": { "type": "string" },
+          "route": { "type": "string" },
+          "loader": { "type": "string" },
+          "requiredDataKeys": {
+            "type": "array",
+            "items": { "type": "string" },
+            "minItems": 1
+          },
+          "defaultVariants": {
+            "type": "object",
+            "additionalProperties": { "type": "string" }
+          },
+          "allowedVariants": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "array",
+              "items": { "type": "string" },
+              "minItems": 1
+            }
+          },
+          "optionalSections": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": ["testimonials", "faq", "statistics", "logoCloud", "pricing"]
+            }
+          }
+        }
+      }
+    }
+  }
+}