@thorprovider/storefront 0.3.1

package/scripts/render-templates.mjs

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+// Deterministic, network-free render of the scaffold templates into a target
+// project. This is the single implementation of the copy stage used by both the
+// `create` action (bin/storefront.js) and the dev harness below, so
+// determinism tests and real scaffolds exercise the same code path.
+//
+//   node scripts/render-templates.mjs <target-dir> [name]
+
+import { mkdir, readdir, readFile, writeFile, rm } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const pkgRoot = path.resolve(here, '..')
+export const templatesRoot = path.join(pkgRoot, 'assets', 'templates')
+
+export const HEADER_RE = /^\/\/ Generated by[\s\S]*?\(template: ([^)]+)\)/
+
+export function toKebab(value) {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+export function toPascal(value) {
+  return value.replace(/(^\w|[-_]\w)/g, (m) => m.replace(/[-_]/, '').toUpperCase())
+}
+
+export function replacePlaceholders(content, { name, siteName }) {
+  const camel = toPascal(name)
+  const header = content.match(HEADER_RE)?.[1]
+  let body = content
+  if (header) body = content.replace(HEADER_RE, '@@HEADER@@')
+  body = body
+    .replaceAll('__STOREFRONT_CAMEL__', camel)
+    .replaceAll('__STOREFRONT__', name)
+    .replaceAll('__SITE_NAME__', siteName)
+  if (header) {
+    body = body.replace('@@HEADER@@', `// Generated by Thor Commerce storefront (template: ${header})`)
+  }
+  return body
+}
+
+async function walk(root, dir, out) {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) await walk(root, full, out)
+    else out.push({ abs: full, rel: path.relative(root, full) })
+  }
+  return out
+}
+
+export async function renderTree(fromDir, toDir, subs) {
+  await mkdir(toDir, { recursive: true })
+  for (const { abs, rel } of await walk(fromDir, fromDir, [])) {
+    const dest = path.join(toDir, rel).replaceAll('__STOREFRONT__', subs.name)
+    await mkdir(path.dirname(dest), { recursive: true })
+    const raw = await readFile(abs, 'utf8')
+    await writeFile(dest, replacePlaceholders(raw, subs))
+  }
+}
+
+export async function writeBarrel(viewsDir) {
+  const viewNames = (await readdir(viewsDir, { withFileTypes: true }))
+    .filter((e) => e.isDirectory() && existsSync(path.join(viewsDir, e.name, 'index.tsx')))
+    .map((e) => e.name)
+    .sort()
+  const body =
+    `// Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/views/index.ts)\n` +
+    `// View registry (barrel). A freshly scaffolded store registers only \`home\`.\n` +
+    `// Adding a view appends one import and one entry here; shared files never change.\n\n` +
+    `import type { ViewModule } from './types'\n` +
+    viewNames.map((v) => `import { ${v} } from './${v}'`).join('\n') +
+    `\n\nexport const views: ViewModule[] = [${viewNames.join(', ')}]\n`
+  await writeFile(path.join(viewsDir, 'index.ts'), body)
+}
+
+// The storefront's required markers inside app/layout.tsx and app/globals.css.
+// These files belong to create-next-app + shadcn: the scaffold never deletes or
+// rewrites them wholesale — it only appends these markers when they are missing,
+// so user edits elsewhere in the files survive.
+const LAYOUT_MARKER = '@thorprovider/runtime/host-glue/providers'
+// Pre-rename marker: `create --force` over a project scaffolded with the old
+// scaffolder must still detect the injection as present (cross-version
+// idempotency) instead of duplicating the provider block.
+const LEGACY_LAYOUT_MARKER = '@thorprovider/storefronts/host-glue/providers'
+const GLOBALS_IMPORT = '@import "@thorprovider/blocks/styles.css";'
+const GLOBALS_TOKENS_MARKER = '--success:'
+
+// The block token contract the scaffold guarantees on top of whatever the shadcn
+// preset produced. Values mirror assets/templates/app/app/globals.css (success /
+// warning AA-conformant pairs in both modes); only these tokens are added, never
+// a re-statement of the preset's own tokens.
+const BLOCK_TOKEN_APPEND = `@theme inline {
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+}
+
+:root {
+  --success: oklch(0.47 0.14 155);
+  --success-foreground: oklch(0.98 0.01 155);
+  --warning: oklch(0.55 0.18 75);
+  --warning-foreground: oklch(0.98 0.02 75);
+}
+
+.dark {
+  --success: oklch(0.6 0.13 155);
+  --success-foreground: oklch(0.1 0.02 155);
+  --warning: oklch(0.7 0.15 75);
+  --warning-foreground: oklch(0.1 0.02 75);
+}
+`
+
+/**
+ * Idempotently inject the storefront provider wiring into an existing
+ * app/layout.tsx (the create-next-app default). Adds the imports and themeCss
+ * const after the last import line, then wraps {children} in the provider.
+ * Returns the content unchanged when the provider marker is already present
+ * (so a re-run never duplicates the injection and user edits survive).
+ */
+export function injectLayout(content, name) {
+  if (content.includes(LAYOUT_MARKER) || content.includes(LEGACY_LAYOUT_MARKER)) return content
+
+  const importLines = [
+    `import { StorefrontProvider } from '${LAYOUT_MARKER}'`,
+    `import { themeVarsToCss, themeTokensToVars } from '@thorprovider/runtime/render-core/theme'`,
+    `import { DEFAULT_THEME_TOKENS } from '@thorprovider/runtime/contracts'`,
+    `import { registry } from '@/lib/${name}/registry'`,
+  ]
+  const constLine = 'const themeCss = themeVarsToCss(themeTokensToVars(DEFAULT_THEME_TOKENS))'
+
+  const lines = content.split('\n')
+  let lastImport = -1
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trimStart().startsWith('import ')) lastImport = i
+  }
+  let out
+  if (lastImport >= 0) {
+    lines.splice(lastImport + 1, 0, '', ...importLines, '', constLine)
+    out = lines.join('\n')
+  } else {
+    out = [...importLines, '', constLine, '', content].join('\n')
+  }
+
+  if (!/\{children\}/.test(out)) return out
+  out = out.replace(
+    /\{children\}/,
+    '<StorefrontProvider themeCss={themeCss} registry={registry}>{children}</StorefrontProvider>',
+  )
+  return out
+}
+
+/**
+ * Idempotently append the blocks stylesheet import and the block token contract
+ * to an existing app/globals.css (produced by create-next-app + shadcn init).
+ * The @import is inserted after the last leading @import line; the success /
+ * warning tokens are appended at the end. Returns the content unchanged when
+ * the blocks import is already present and the success tokens exist.
+ */
+export function injectGlobals(content) {
+  const lines = content.split('\n')
+  let lastImport = -1
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trimStart().startsWith('@import ')) lastImport = i
+  }
+  let out
+  if (content.includes(GLOBALS_IMPORT)) {
+    out = content
+  } else if (lastImport >= 0) {
+    lines.splice(lastImport + 1, 0, GLOBALS_IMPORT)
+    out = lines.join('\n')
+  } else {
+    out = `${GLOBALS_IMPORT}\n${content}`
+  }
+
+  if (out.includes(GLOBALS_TOKENS_MARKER)) return out
+  return `${out.replace(/\s*$/, '')}\n\n${BLOCK_TOKEN_APPEND}`
+}
+
+/**
+ * Render the owned surfaces into `targetDir` — the catch-all route
+ * `app/[[...slug]]/` and `lib/<name>/` — then register the views in the barrel.
+ * `app/layout.tsx` and `app/globals.css` are NOT owned: when they exist they are
+ * only appended to (idempotently); when absent they are written from the
+ * template so a fresh project still ships the provider and block tokens.
+ * Removes the template-owned surfaces (and the create-next-app default page)
+ * first so repeated runs stay clean and no stage deletes another's output.
+ */
+export async function renderScaffold({ targetDir, name, siteName }) {
+  const viewsDir = path.join(targetDir, 'lib', name, 'views')
+  await rm(path.join(targetDir, 'lib', name), { recursive: true, force: true })
+  await rm(path.join(targetDir, 'app', '[[...slug]]'), { recursive: true, force: true })
+  await rm(path.join(targetDir, 'app', 'page.tsx'), { force: true })
+
+  await renderTree(path.join(templatesRoot, 'app', 'app', '[[...slug]]'), path.join(targetDir, 'app', '[[...slug]]'), { name, siteName })
+  await renderTree(path.join(templatesRoot, 'app', 'lib'), path.join(targetDir, 'lib'), { name, siteName })
+  await renderTree(path.join(templatesRoot, 'views'), viewsDir, { name, siteName })
+  await writeBarrel(viewsDir)
+
+  await ensureLayoutAppend(targetDir, name, siteName)
+  await ensureGlobalsAppend(targetDir, name, siteName)
+}
+
+async function ensureLayoutAppend(targetDir, name, siteName) {
+  const layoutPath = path.join(targetDir, 'app', 'layout.tsx')
+  const templatePath = path.join(templatesRoot, 'app', 'app', 'layout.tsx')
+  if (!existsSync(layoutPath)) {
+    const raw = await readFile(templatePath, 'utf8')
+    await writeFile(layoutPath, replacePlaceholders(raw, { name, siteName }))
+    return
+  }
+  const existing = await readFile(layoutPath, 'utf8')
+  const injected = injectLayout(existing, name)
+  if (injected !== existing) await writeFile(layoutPath, injected)
+}
+
+async function ensureGlobalsAppend(targetDir, name, siteName) {
+  const globalsPath = path.join(targetDir, 'app', 'globals.css')
+  const templatePath = path.join(templatesRoot, 'app', 'app', 'globals.css')
+  if (!existsSync(globalsPath)) {
+    const raw = await readFile(templatePath, 'utf8')
+    await writeFile(globalsPath, replacePlaceholders(raw, { name, siteName }))
+    return
+  }
+  const existing = await readFile(globalsPath, 'utf8')
+  const injected = injectGlobals(existing)
+  if (injected !== existing) await writeFile(globalsPath, injected)
+}
+
+const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (invokedDirectly) {
+  const targetArg = process.argv[2]
+  if (!targetArg) {
+    console.error('usage: node scripts/render-templates.mjs <target-dir> [name]')
+    process.exit(1)
+  }
+  const target = path.resolve(process.cwd(), targetArg)
+  const name = toKebab(process.argv[3] ?? path.basename(target))
+  const siteName = name
+  if (!existsSync(templatesRoot)) {
+    console.error(`templates not found: ${templatesRoot}`)
+    process.exit(1)
+  }
+  if (!existsSync(target)) {
+    console.error(`target does not exist: ${target} (create the Next.js project first)`)
+    process.exit(1)
+  }
+  await renderScaffold({ targetDir: target, name, siteName })
+  console.log(`rendered templates for "${name}" (camel: ${toPascal(name)}) into ${target}`)
+}

package/scripts/sync-assets.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// Keeps the per-skill copies of shared assets in sync with the single source.
+//
+// Source of truth: recipes/ at the package root.
+// Generated copies:
+//   skills/sf-view-gen/assets/recipes/{recipes,archetypes,sections}.json
+//   skills/sf-view-gen/scripts/validate.mjs
+//
+// Usage:
+//   node scripts/sync-assets.mjs           # write the copies from source
+//   node scripts/sync-assets.mjs --check   # report divergence, exit 1 if any
+
+import { createHash } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const PKG_ROOT = resolve(__dirname, '..')
+
+const SOURCE = join(PKG_ROOT, 'recipes')
+
+const MANIFEST = [
+  ['recipes.json', join(PKG_ROOT, 'skills/sf-view-gen/assets/recipes/recipes.json')],
+  ['archetypes.json', join(PKG_ROOT, 'skills/sf-view-gen/assets/recipes/archetypes.json')],
+  ['sections.json', join(PKG_ROOT, 'skills/sf-view-gen/assets/recipes/sections.json')],
+  ['validate.mjs', join(PKG_ROOT, 'skills/sf-view-gen/scripts/validate.mjs')],
+]
+
+function sha256(text) {
+  return createHash('sha256').update(text).digest('hex')
+}
+
+export async function checkAssets() {
+  const diverged = []
+  for (const [sourceName, destPath] of MANIFEST) {
+    const source = await readFile(join(SOURCE, sourceName), 'utf8')
+    if (!existsSync(destPath)) {
+      diverged.push(`${destPath} (missing)`)
+      continue
+    }
+    const copy = await readFile(destPath, 'utf8')
+    if (sha256(source) !== sha256(copy)) {
+      diverged.push(destPath)
+    }
+  }
+  return diverged
+}
+
+async function syncAssets() {
+  let written = 0
+  for (const [sourceName, destPath] of MANIFEST) {
+    const source = await readFile(join(SOURCE, sourceName), 'utf8')
+    await mkdir(dirname(destPath), { recursive: true })
+    await writeFile(destPath, source, 'utf8')
+    written++
+    console.log(`  synced ${destPath}`)
+  }
+  return written
+}
+
+async function main() {
+  const check = process.argv.includes('--check')
+  if (check) {
+    const diverged = await checkAssets()
+    if (diverged.length > 0) {
+      console.error('Generated assets are out of sync with recipes/:')
+      for (const file of diverged) console.error(`  ${file}`)
+      console.error('Run `node scripts/sync-assets.mjs` to regenerate.')
+      process.exitCode = 1
+      return
+    }
+    console.log('Generated assets are in sync with recipes/.')
+    return
+  }
+
+  const written = await syncAssets()
+  console.log(`Synced ${written} generated asset(s) from recipes/.`)
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
+  main().catch((err) => {
+    console.error(err)
+    process.exitCode = 1
+  })
+}

package/skills/building-storefronts/SKILL.md

@@ -0,0 +1,178 @@
+---
+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.