@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/skills/sf-setup/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: sf-setup
+description: Connect or re-point a Thor Commerce storefront to a Medusa backend — set the backend URL, publishable API key, sales channel id, and region, or preserve the current environment when no key is supplied. Use when the user asks to connect or reconnect the backend, change the region or API key, switch the data source, or "set up" the store's data. Delegates to the `storefront setup` CLI command.
+---
+
+# sf-setup
+
+Connect a storefront to a real Medusa backend, or re-point an already-connected
+store. `setup` takes the sales channel id as an explicit input (there is no store API
+that reads the channels bound to a publishable key), derives the region's currency,
+then writes them to `.env.local`. The CLI writes the file; agents never hand-edit it.
+
+## Run it
+
+Run from the storefront project root:
+
+```bash
+npx @thorprovider/storefront setup \
+  --backend-url http://localhost:9000 \
+  --publishable-key <pk_...> \
+  --sales-channel-id <sc_...> \
+  --region-id <reg_...>
+```
+
+On a terminal with no flags it runs an interactive wizard (backend URL →
+publishable key → sales channel id → region). Pass the flags to run
+non-interactively (CI, scripts).
+
+## Flags
+
+| Flag | Meaning |
+| --- | --- |
+| `--backend-url` | Medusa backend base URL. Defaults to `http://localhost:9000`. |
+| `--publishable-key` | Publishable API key (`pk_...`). Required to connect. |
+| `--sales-channel-id` | Sales channel id (`sc_...`) from the Medusa admin (Settings → Sales Channels). Required without a terminal. |
+| `--region-id` | Region id to bind. Required without a terminal; the wizard offers the available regions. |
+
+## No key — the existing environment is preserved
+
+With no publishable key, `setup` makes no network calls, **changes no files**, and
+exits 0, so it is safe to run in CI/bootstrap without a key. It does not switch
+the store to `mock`: the existing data source is left exactly as it was (`mock`
+stays `mock`, `medusa` stays `medusa`). A freshly created store is already in
+`mock` mode, so running with no key simply leaves it there.
+
+## What it writes
+
+Only the keys `setup` manages are upserted in `.env.local`; everything else (the
+session secret, the site URL, store identity, and any user additions) is
+preserved:
+
+- `THOR_DATA_SOURCE=medusa`
+- `MEDUSA_BASE_URL`
+- `MEDUSA_PUBLISHABLE_KEY`
+- `MEDUSA_REGION_ID`
+- `MEDUSA_SALES_CHANNEL_ID` (from the `--sales-channel-id` input)
+- `MEDUSA_CURRENCY_CODE` (derived from `GET /store/regions`)
+
+Restart the dev server to pick up the change.
+
+## Failure behavior
+
+If the backend is unreachable, the key is rejected, the sales channel id is
+missing, or the region is missing or has no currency, `setup` prints the reason,
+**changes no files**, preserves the existing environment (`mock` stays `mock`,
+`medusa` stays `medusa`), and exits non-zero. The store is placed in `medusa` mode
+only after the backend URL, publishable key, sales channel id, and region are all
+resolved and the region's currency resolves successfully. Relay the message to the
+user and fix the input; do not hand-edit `.env.local`.
+
+## Workflow model
+
+Read `../storefront-workflow/SKILL.md` for the four phases and the CLI/agent
+authority.
+
+## Completion criteria
+
+- `.env.local` contains the managed keys for the chosen backend and region.
+- The dev server starts and loads data from the connected backend.

package/skills/sf-theme-gen/SKILL.md

@@ -1,61 +1,131 @@
 ---
 name: sf-theme-gen
-description: Customize a Thor Commerce storefront's OKLCH color tokens (light/dark), typography, and identity/SEO metadata
+description: Customize a Thor Commerce storefront's theme — OKLCH colors, radius, fonts, shadcn presets and imported themes, plus typography and global identity/SEO metadata. Use when the user asks to change the storefront's colors, brand, theme, typography, site name, or SEO metadata.
 ---
 
 # sf-theme-gen
 
-Customize a storefront's theme and identity. This skill ships with everything it needs: it uses the vendored theming skill alongside it. When a choice is not resolved by those files, ask the user.
+Customize a storefront's theme and identity. Prefer the deterministic
+`storefront theme` controls; fall back to hand-editing the two external files only
+within their bounded surface. When a required choice is not determined by the
+references, ask the user.
 
-## Source of truth
+## Inputs
 
-The workflow uses only the assets in this skill directory and the vendored `../shadcn-theming/` skill next to it. When a required choice is not determined there, ask the user.
+- The manifest `storefront.config.json` — the theme authority for the **mode**.
+- The two external files `app/globals.css` and `app/layout.tsx` — the current
+  visual tokens, fonts, and identity.
+- The user's chosen customization area and value.
 
-## Inputs (the only target-project facts this skill reads)
+## Outputs
 
-- the existence of the target project's `package.json`
-- the existence of `lib/<name>/`
-- the existence of the project's `.opencode/`
-- the values returned by the wizard (which area to customize, and its value)
+- Edited `app/globals.css` (tokens, `@theme` bridge, font variables) and/or
+  `app/layout.tsx` (font loading, metadata/identity) — produced by
+  `storefront theme` when a control exists, or by hand within the bounds below.
+- A summary listing every file edited and every command run.
 
-## Outputs (what this skill produces)
+## Scope (bounded external surface)
 
-- generated files: `app/globals.css` and `app/layout.tsx`
-- declared setup commands: the dev server and typecheck commands it reports
-- a summary listing every file edited and every command run
+| Area | File | Allowed change |
+|---|---|---|
+| Design tokens (OKLCH, light/dark) | `app/globals.css` | token values + foreground pairs, `@theme` bridge, font variable |
+| Typography | `app/layout.tsx` + `globals.css` | load the font with `next/font`, point `--font-sans` at it |
+| Identity / metadata / Open Graph | `app/layout.tsx` | the `metadata` object |
 
-## Scope
+Everything else in these files is **CLI-managed and must be preserved**: the
+stylesheet import, the provider import and its marker, the theme-mode marker, and
+the block token contract. The CLI appends idempotently; never remove or duplicate
+a marker, and never edit the mode wiring by hand.
 
-| Area | File |
-|---|---|
-| Design tokens (shadcn) | `app/globals.css` |
-| Typography + metadata | `app/layout.tsx` |
+## CLI controls (preferred path)
 
-## Vendored skill
-Follow `../shadcn-theming/SKILL.md` for OKLCH pair rules and contrast. Paths are relative to this `SKILL.md`.
+Visual values live in `app/globals.css`; the mode lives in the manifest. All
+controls are one command and are validated before any write:
+
+```
+storefront theme --inspect [--json]        # read-only: current tokens, names, formats
+storefront theme --mode light|dark|system  # site color mode (manifest + wiring)
+storefront theme --brand orange            # named brand -> full primary family
+storefront theme --primary '#f97316'       # one color (named | #hex | oklch(...))
+storefront theme --accent 'oklch(0.6 0.15 200)'
+storefront theme --radius 0.75rem          # base radius (drives the radius scale)
+storefront theme --font-sans google:Inter  # loads the font, points --font-sans at it
+storefront theme --set light.primary=#f97316   # scope = light | dark | shared; repeatable
+storefront theme --preset <name|code|url> [--only theme|font|theme,font]
+storefront theme --import ./theme.css|./theme.json|<registry-url>
+storefront theme --export ./brand.theme.json   # portable snapshot; never overwrites
+storefront theme ... --dry-run             # describe the change, write nothing
+storefront theme ... --json                # machine-readable result envelope
+```
+
+`--brand`/`--primary` set the primary family (primary, foreground, hover, soft,
+ring, nav) in both modes. Explicit `--set` values win over shortcuts; later
+arguments win over earlier ones. A `--preset` applies **theme and fonts only** —
+it never reinstalls or restyles components.
+
+## Free theme workflow (generator → CLI)
+
+1. Design the palette in a free editor and export its CSS: the official builder
+   at `ui.shadcn.com/create` (preset code/URL) or a CSS export from tweakcn /
+   Shadcn Studio. These are authoring tools; the CLI is the writer.
+2. Apply it: `storefront theme --preset <code>` for a preset, or
+   `storefront theme --import ./exported.css` for a CSS export (only theme tokens
+   and font variables are merged; unrelated CSS is ignored).
+3. Fine-tune: `--brand`, `--primary`, `--accent`, `--radius`, `--set`, `--font-*`.
+4. `storefront theme --export ./brand.theme.json` to keep a portable snapshot;
+   replay it elsewhere with `--import ./brand.theme.json`.
 
 ## Color rules
+
 - Colors are CSS variables, never raw Tailwind color utilities.
 - OKLCH only; define complete background/foreground pairs.
-- Lightness rule: bg `L < 0.55` → fg `L >= 0.93`; bg `L >= 0.55` → fg `L <= 0.20`.
-- Named accents can use `accentColorToOklch(name)` from `@thorprovider/runtime/render-core/theme`.
+- The CLI pairs a changed color with its foreground using **measured contrast**
+  (WCAG relative luminance), not a lightness threshold; auto-selected foregrounds
+  meet >= 4.5:1. A contrast below 4.5:1 is reported as a warning but never
+  silently changes an explicit pair — use `--set light.primary-foreground=#fff`
+  to force a specific pairing.
+- Accepts `<name>` (see `storefront theme --inspect`), `#hex`, `oklch(...)`.
 
 ## Workflow
 
-1. Use the `question` tool to ask what to customize: colors, typography, identity, SEO, Open Graph.
-2. **Colors**: follow `../shadcn-theming/SKILL.md`; update BOTH `:root` (light) and `.dark` blocks in `app/globals.css`, keeping the `@theme inline` mapping intact.
-3. **Pairs**: every changed color gets its foreground pair in both modes; verify the lightness rule.
-4. **Typography**: load the font with `next/font` in `app/layout.tsx`; point `--font-sans` in `globals.css` at the new variable; keep body >= 1rem / line-height 1.5.
-5. **Identity**: update the `metadata` object in `app/layout.tsx` (title, description) and add Open Graph + Twitter Card fields. Research the current Next.js Metadata API before writing.
-6. **Verify**: run the dev server; confirm both color modes, font, and head metadata. `yarn typecheck` passes.
+1. Ask what to customize: colors/brand, radius, typography, identity, SEO, Open Graph.
+2. **Mode** is deterministic: `storefront theme --mode light|dark|system`; never
+   edit the mode wiring by hand. There is no visitor-facing toggle by design.
+3. **Colors**: prefer `storefront theme --brand/--primary/--accent` or `--set`.
+   For a full palette, import a generator export (see above). Hand-edit only a
+   value the CLI cannot express, updating BOTH `:root` and `.dark`.
+4. **Pairs**: a color change gets its foreground pair; the CLI does this and
+   warns on low contrast.
+5. **Typography**: `storefront theme --font-sans google:Inter` loads the font with
+   `next/font` and points `--font-sans` at it. Use `system:<stack>` for a CSS
+   stack. Existing local fonts are preserved unless explicitly replaced. A font
+   name alone is not proof it loads — verify rendering.
+6. **Identity**: update the `metadata` object in `app/layout.tsx` (title,
+   description) and add Open Graph + Twitter Card fields. Confirm the current
+   Next.js Metadata API before writing.
+7. **Verify**: `storefront theme --dry-run` first, then apply; run the dev server
+   and confirm both color modes, the font, and the head metadata. `yarn build` is
+   the final acceptance. A `sync` must leave the CLI-managed markers intact and
+   the theme unchanged.
+
+## Limits
+
+- A preset changes theme tokens and font wiring only; it cannot redesign
+  package-owned `@thorprovider/blocks` beyond their tokens.
+- `--export` is read-only over the project and refuses to overwrite a file.
+- Invalid input (unknown color/token/length/font, unsupported import) fails with
+  a diagnostic and writes nothing.
 
 ## Error handling
+
 - Invalid color input → re-prompt (accept `<name>`, `#hex`, `oklch(...)`).
-- No `lib/<name>/` → run `npx @thorprovider/storefront create`, stop.
-- Unknown token key → check `themeTokenKeys` in `@thorprovider/runtime/contracts` first.
+- Unknown token key → run `storefront theme --inspect` (lists supported tokens).
+- Mode change → always via `storefront theme --mode ...`; never edit by hand.
 
 ## Generation headers
+
 ```
 // Themed by @thorprovider/storefront (sf-theme-gen)
 ```
+
 Never remove existing tokens; only override values.

package/skills/sf-theme-gen/references/shadcn-theming.md

@@ -0,0 +1,87 @@
+# shadcn theming reference
+
+Reference material for the `sf-theme-gen` skill. It documents shadcn/ui design
+tokens, OKLCH color rules, dark/light mode CSS variables, and the Tailwind v4
+`@theme` bridge for the two external files `app/globals.css` and
+`app/layout.tsx`.
+
+## Overview
+
+| Feature | Description |
+|---------|-------------|
+| **CSS Variables** | `--background`, `--foreground`, `--primary`, etc. |
+| **OKLCH Colors** | Wide-gamut P3 color space, perceptually uniform |
+| **Dark Mode** | `.dark` class or `prefers-color-scheme` |
+| **Tailwind v4** | `@theme` directive integration |
+
+## Critical rules
+
+1. **ALWAYS use OKLCH** color space for all tokens.
+2. **ALWAYS define dark mode** overrides for every token.
+3. **NEVER hard-code** hex or rgb in components.
+4. **USE the `@theme`** directive for Tailwind v4 integration.
+5. **MAP semantic tokens** to primitive OKLCH values.
+
+## Lightness rule (contrast)
+
+Apply it to every custom pair (`--secondary`, `--accent`, `--destructive`, `--muted`):
+
+- Background `L < 0.55` → foreground `L >= 0.93`.
+- Background `L >= 0.55` → foreground `L <= 0.20`.
+
+## Token hierarchy
+
+```
+Component:  --card, --card-foreground, --button-*
+     ↑
+Semantic:   --primary, --secondary, --accent, --muted
+     ↑
+Primitive:  oklch(55% 0.20 260), oklch(98% 0.01 260)
+```
+
+## File scope
+
+Only these two external files are touched, and only for tokens, fonts, and
+identity. The CLI-managed imports and markers inside them must survive.
+
+```
+app/globals.css   # :root + .dark token definitions, @theme bridge
+app/layout.tsx    # font wiring (next/font) + metadata/identity
+```
+
+The theme mode (`light` / `dark` / `system`) is a CLI operation
+(`storefront theme --mode ...`); do not hand-edit the `ThemeProvider` wiring in
+`app/layout.tsx`.
+
+## Validation checklist
+
+```
+[ ] CSS variables defined in :root
+[ ] Dark mode overrides in .dark
+[ ] OKLCH color space used
+[ ] Chart variables (--chart-1 to --chart-5) if used
+[ ] Sidebar variables if applicable
+[ ] No hard-coded hex in components
+[ ] @theme bridge maps each semantic token
+```
+
+## Best practices
+
+### DO
+- Use OKLCH for all colors.
+- Define semantic tokens mapped to primitives.
+- Provide dark mode overrides for all tokens.
+- Use `@theme` for Tailwind v4 integration.
+
+### DON'T
+- Hard-code hex or rgb values.
+- Skip dark mode definitions.
+- Mix color spaces (hex + oklch).
+- Define tokens only in a Tailwind config.
+
+## Reference guide
+
+| Topic | Reference | When to consult |
+|-------|-----------|-----------------|
+| Theming guide | [theming-guide.md](theming-guide.md) | CSS variables and OKLCH setup |
+| Complete theme template | [theme-setup.md](theme-setup.md) | Light + dark token definitions and `@theme` bridge |

package/skills/{shadcn-theming/references/templates → sf-theme-gen/references}/theme-setup.md

@@ -1,11 +1,8 @@
----
-name: theme-setup
-description: Complete shadcn/ui theme with CSS variables, dark mode, and Tailwind v4 integration
-keywords: theme, setup, css, oklch, dark-mode, tailwind
----
-
 # Theme Setup
 
+Reference material for the `sf-theme-gen` skill: the complete light + dark theme
+with CSS variables, dark mode, and Tailwind v4 integration.
+
 ## Complete Light + Dark Theme
 
 ```css
@@ -92,18 +89,17 @@ keywords: theme, setup, css, oklch, dark-mode, tailwind
 }
 ```
 
-## Theme Switching (React)
+## Theme switching
 
-```tsx
-// components/theme-provider.tsx
-"use client"
-import { ThemeProvider as NextThemesProvider } from "next-themes"
+The light/dark/system mode is a CLI operation, not a hand edit. Run
+`npx @thorprovider/storefront theme --mode light|dark|system`: it rewrites the
+`ThemeProvider` wiring in `app/layout.tsx` idempotently. Do **not** add your own
+provider or toggle; the mode is a site setting and the CLI-managed import and
+marker must survive. This template covers the `:root` / `.dark` token blocks and
+the `@theme` bridge only.
 
-export function ThemeProvider({ children }: { children: React.ReactNode }) {
-  return (
-    <NextThemesProvider attribute="class" defaultTheme="system" enableSystem>
-      {children}
-    </NextThemesProvider>
-  )
-}
-```
+## Marker preservation
+
+`app/globals.css` and `app/layout.tsx` are `external` files: keep the CLI-managed
+provider/mode/style imports and block-token markers intact. Change only token
+values, font wiring, and global identity/metadata.

package/skills/{shadcn-theming → sf-theme-gen}/references/theming-guide.md

@@ -1,14 +1,9 @@
----
-name: theming-guide
-description: CSS variables, OKLCH colors, chart/sidebar tokens, and Tailwind integration
-when-to-use: When configuring theme tokens or color system
-keywords: theme, oklch, css-variables, dark-mode, tailwind, tokens, colors
-priority: high
-related: ../SKILL.md
----
-
 # Theming Guide
 
+Reference material for the `sf-theme-gen` skill: CSS variables, OKLCH colors,
+chart/sidebar tokens, and the Tailwind v4 integration used by the external
+`app/globals.css`.
+
 ## Overview
 
 shadcn/ui uses CSS custom properties with OKLCH color space for wide-gamut P3 support and perceptual uniformity. Tokens follow a 3-level hierarchy: primitive -> semantic -> component.
@@ -71,7 +66,7 @@ Use `.dark` class on `<html>` or CSS media query:
 <html className={theme === "dark" ? "dark" : ""}>
 ```
 
-For full setup with next-themes, see [theme-setup.md](templates/theme-setup.md).
+For the full token template, see [theme-setup.md](theme-setup.md).
 
 ---
 
@@ -87,4 +82,4 @@ For full setup with next-themes, see [theme-setup.md](templates/theme-setup.md).
 
 ## Related Templates
 
-- [theme-setup.md](templates/theme-setup.md) - Complete theme configuration
+- [theme-setup.md](theme-setup.md) - Complete theme configuration