@thorprovider/storefront 0.3.1 → 0.4.0-mvp.0

package/commands/sf-add-view.md

@@ -1,26 +1,57 @@
 ---
-description: "Add a single view to an existing Thor Commerce storefront (product, category, checkout, user-panel)"
+description: "Add a view to a Thor Commerce storefront via the storefront CLI"
 ---
 
-Add one view to an existing Thor Commerce storefront, generated from a recipe.
+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 followed by a description of what the view should contain or emphasize.
+**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`
-- `/sf-add-view checkout keep it single-page`
 
 **Provided arguments**: $ARGUMENTS
 
-Use the `sf-view-gen` skill.
+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.
 
-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.
+**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.
 
-**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.
+   ```bash
+   npx @thorprovider/storefront plan --operations operations.json --out plan.json
+   npx @thorprovider/storefront apply --plan plan.json
+   ```
 
-**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`
+   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

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

@@ -2,19 +2,25 @@
 description: "Customize storefront theme: OKLCH colors (light/dark), typography, and identity metadata"
 ---
 
-Customize the theme and identity of a Thor Commerce storefront.
+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.
 
-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.
+**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 use raw Tailwind color utilities for themed colors
-- Typography and metadata follow the skill's own assets
+- 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,25 +1,67 @@
 ---
-description: "Modify an existing storefront view's spec while preserving its structure"
+description: "Modify a storefront view's user-owned content/props/data, or compose its sections, via the storefront CLI"
 ---
 
-Modify an existing view in a Thor Commerce storefront.
+Modify an existing view in the current storefront.
 
 **Input**: view name followed by the change to make.
 Examples:
-- `/sf-view home add a statistics band after the hero`
+- `/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 (modification workflow).
+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.
 
-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.
+**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.
 
-**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.
+   ```bash
+   npx @thorprovider/storefront plan --operations operations.json --out plan.json
+   npx @thorprovider/storefront apply --plan plan.json
+   ```
 
-**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`
+   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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thorprovider/storefront",
-  "version": "0.3.1",
+  "version": "0.4.0-mvp.0",
   "description": "Deterministic storefront scaffolder and installable OpenCode command suite for Thor Commerce (Next.js, @thorprovider/blocks, @thorprovider/adapters, Medusa)",
   "type": "module",
   "bin": "./bin/storefront.js",
@@ -14,13 +14,14 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=18.17.0"
+    "node": ">=20.9.0"
   },
   "scripts": {
     "sync-assets": "node ./scripts/sync-assets.mjs",
     "check-assets": "node ./scripts/sync-assets.mjs --check",
     "pretest": "node ./scripts/sync-assets.mjs --check",
-    "test": "vitest run --config vitest.config.ts"
+    "test": "vitest run --config vitest.config.ts",
+    "test:integration": "vitest run --config vitest.config.ts tests/scaffold-integration.test.ts"
   },
   "publishConfig": {
     "access": "public",
@@ -39,7 +40,8 @@
     "scaffolding"
   ],
   "dependencies": {
-    "@clack/prompts": "^1.8.1"
+    "@clack/prompts": "^1.8.1",
+    "semver": "^7.7.4"
   },
   "devDependencies": {
     "vitest": "^3.2.4"

package/recipes/archetypes.json

@@ -4,7 +4,7 @@
   "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",
+      "default": "compact",
       "intents": {
         "compact": {
           "variant": "StorefrontHero1",
@@ -122,6 +122,33 @@
         }
       }
     },
+    "account.login": {
+      "default": "signIn",
+      "intents": {
+        "signIn": {
+          "variant": "LoginPage1",
+          "when": "A full sign-in page with email and password and a link to create an account."
+        }
+      }
+    },
+    "account.register": {
+      "default": "signUp",
+      "intents": {
+        "signUp": {
+          "variant": "SignUpPage1",
+          "when": "A full registration page with name, email, and password and a link to sign in."
+        }
+      }
+    },
+    "account.orders": {
+      "default": "viewOrders",
+      "intents": {
+        "viewOrders": {
+          "variant": "OrderHistory2",
+          "when": "A signed-in shopper's order history with per-order totals and detail on demand."
+        }
+      }
+    },
     "user-panel.shell": {
       "default": "standard",
       "intents": {