@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

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

@@ -1,116 +1,169 @@
 ---
 name: sf-view-gen
-description: Add a new view or modify an existing view in a Thor Commerce storefront, selecting block variants and optional sections from this package's recipes
+description: Add or remove a Thor Commerce storefront view, compose and reorder a view's executable sections, or customize a view's user-owned files. Use when the user asks to add or remove a view (home, category, product, cart, account, static), add/remove/reorder a section (faq, cta, products), change a variant, or change a view's content, props, or data. Delegates every structural write to the `storefront` CLI.
 ---
 
 # sf-view-gen
 
-Generate or modify a single view, driven by the **recipe registry inside this skill's own directory**, so storefronts are not identical.
+Choose a view's composition **by meaning**, delegate the structural write to the
+`storefront` CLI, and edit only the user-owned files it leaves behind. The
+manifest (`storefront.config.json`) is the structural authority; the CLI is the
+only writer of derived files.
 
-## Source of truth
+## Read the curated view set through the CLI (never from memory)
 
-The workflow uses only the assets in this skill directory. There is no external project to consult and no package to locate: the recipes and templates it reads live under `assets/`, and the validator under `scripts/`. When a required choice is not determined by those files, ask the user.
+Run from the storefront project root. The CLI resolves the project from the
+current directory; do not pass a directory.
 
-## Inputs (the only target-project facts this skill reads)
-
-- 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 (view name, description of what the view should contain or emphasize)
-
-## Outputs (what this skill produces)
+```bash
+npx @thorprovider/storefront views --json      # views, routes, intents/variants, installed
+npx @thorprovider/storefront recipes --json    # whole curated registry (views + features)
+npx @thorprovider/storefront features --json   # feature bundles and what they own
+```
 
-- generated files: the view module under `lib/<name>/views/<view>/` and one barrel entry in `lib/<name>/views/index.ts`
-- declared setup commands: the typecheck command it reports
-- a summary listing every file created and every command run
+The `--json` output is the same registry the CLI validates against, so it cannot
+advertise a selection the reconciler will not honour. There is **no fixed view
+list in this skill**: `views --json` reports the authoritative curated set
+(currently `home`, `product`, `cart`, `category`, `checkout`, `account`, and
+`static`) annotated with `installed` and `supported`, so a view added to or
+removed from the registry is reflected without editing this text.
+
+`views --json` and `recipes --json` also report, per view, `registeredSlots` (the
+non-removable core slots), `allowedSections` (the section types the view may
+host), and `maxSections` (the editorial-instance bound), plus a top-level
+`sectionTypes` list marking each type `executable` or `held` with a reason. Do not
+read the JSON files directly; they are an implementation detail.
+
+## Add a view
+
+1. Read `views --json`. If the view is held (`supported: false`) or is
+   feature-owned, stop and explain the correct path (a direct `view add` of a
+   feature-owned view is rejected — route it through the owning feature's
+   `feature add`; see the `sf-feature` skill).
+2. Choose an **intent by meaning** for each slot from the view's
+   `supportedIntents` (for example a "dense grid" description → the matching
+   intent). If the description is silent, use the default. Use
+   `--variant slot=Name` only when the user names an exact supported variant.
+3. Delegate the write:
+
+   ```bash
+   npx @thorprovider/storefront view add <name> [--intent slot=intent] [--variant slot=Variant]
+   ```
 
-## Assets (inside this skill)
+   The CLI validates, updates the manifest, and reconciles the derived files. If
+   it exits non-zero, show its message and the supported options; do not hand-edit
+   derived files to work around it.
+4. Report the created view and its route.
 
-- `assets/recipes/recipes.json` — per view: `route`, `loader`, `requiredDataKeys`, `defaultVariants`, `allowedVariants`, `optionalSections`
-- `assets/recipes/sections.json` — optional sections → `elementType`, `variants`, `defaultVariant`, `propsHint`
-- `assets/recipes/archetypes.json` — the **archetype (intent) layer**: per slot (`<view>.<slot>`) a set of named **intents**, each with a `variant` and a `when` usage hint, plus the slot `default` intent
-- `assets/templates/views/<view>/` — the view modules it copies
-- `assets/templates/views/sections/` — the optional-section fragments
-- `scripts/validate.mjs` — the validator
-- `references/views.md` — the view composition contract
-- `../json-render-core/` — vendored catalog/schema/spec reference
-- `../json-render-react/` — vendored registry/action reference
+## Remove a view
 
-Paths are relative to this `SKILL.md`. Run the validator from here:
 ```bash
-node scripts/validate.mjs list
-node scripts/validate.mjs show <view>
-node scripts/validate.mjs archetypes
-node scripts/validate.mjs resolve <view> <slot> <intent>
-node scripts/validate.mjs validate '<composition-json>'
+npx @thorprovider/storefront view remove <name>
 ```
 
-## Allowed views
-`home`, `product`, `category`, `checkout`, `user-panel`
+The CLI removes the derived wrapper and wiring. If it prints a preserved
+user-owned file, relay that path to the user.
+
+## Compose sections (the agent selects, the CLI writes)
+
+A view's ordered composition mixes its **registered slots** (core presentation
+slots, mandatory and non-removable) with **editorial section instances**. The
+agent selects the options and runs the CLI; the user describes the change in
+natural language and never types a command.
+
+1. Read `views --json`. For the target view use `registeredSlots` (the core
+   slots), `allowedSections` (the host allowlist), and `maxSections`; read the
+   top-level `sectionTypes` list for which types are `executable`. Never treat the
+   `sections --json` installed-instance list as the set of available types.
+2. Only `executable` types may be composed; a `held` type is refused with the
+   `reason` the registry reports — relay that reason, never invent one. A
+   `dataBound` `products` instance is configured separately by the developer in
+   `views/<view>/data.ts` → `sectionSources[id]` (a canonical query — not a sales
+   ranking); its variant only changes presentation, and until the selection is set
+   the instance renders a truthful "needs configuration" state that `doctor`
+   reports by file and instance id.
+3. Compose through the CLI's section operations, carried in the operations
+   envelope `{ "formatVersion": 1, "operations": [ ... ] }`. Write the envelope
+   to a file, plan it, then apply the plan:
+
+   ```bash
+   npx @thorprovider/storefront plan --operations operations.json --out plan.json
+   npx @thorprovider/storefront apply --plan plan.json
+   ```
 
-Reject any other name with the full allowed list.
+   - `{ "op": "section.add", "view": "<view>", "type": "<type>" }` — optional `id`,
+     `variant`, and `at` (0-based insertion index, default append). Omit `id` to
+     auto-mint one; a `variant` must be declared by the section type.
+   - `{ "op": "section.remove", "view": "<view>", "id": "<id>" }` — removes an
+     editorial instance. A registered slot (`slot:<slot>`) cannot be removed.
+   - `{ "op": "section.reorder", "view": "<view>", "order": [ ... ] }` — `order`
+     must be a permutation of the view's current entry ids: every current id
+     exactly once, and every registered slot present.
+
+4. `plan` is read-only and validates the whole intended state; `apply --plan` is
+   the only writer. On success the CLI updates the manifest and reconciles derived
+   files. If either exits non-zero, relay its diagnostic (it names the offending
+   field) and the supported options; do not hand-edit the manifest or derived
+   files to work around it.
+5. 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
+   rebinds preserved content.
+
+## Variants
+
+A slot's variant is a presentation choice carried by the manifest. Change it
+through the CLI (`view add`/`remove` with `--variant`, or a `section.add` /
+`section.reorder` operation for editorial sections); never hand-edit a derived
+`index.tsx` or registry to swap an import identifier. Variant changes go through
+the CLI plan/apply path so the manifest and the derived files stay in sync.
+
+## Customize a view
+
+Only **user-owned** files may be edited by hand. They are consumed by thin
+derived wrappers, so `sync` regenerates the wrappers around your edits.
+
+User-owned (edit these): `lib/<name>/views/<view>/content.ts`, `props.ts`,
+`data.ts`, `schema.ts`, and `lib/<name>/mappers.ts`.
+
+Derived (never edit; the CLI regenerates them): `index.tsx`, `registry.tsx`,
+`lib/<name>/views/index.ts`, `lib/<name>/views/registry.ts`, `catalog.ts`,
+`runtime.ts`, `spec/index.ts`, `state.ts`, `handlers.ts`.
+
+1. Read the current user-owned files for the view.
+2. Apply the requested change there. Preserve exported names, element ids, and
+   the event/prop contracts the derived wrapper imports.
+3. Regenerate the wrappers: `npx @thorprovider/storefront sync`.
+4. If the change needs a different block variant or a new view, use the CLI
+   (`view add`/`remove` or the section operations); never edit a derived file to
+   swap a variant.
+
+## References
+
+Relative to this `SKILL.md`:
+
+- `references/views.md` — view module shape, registering, and data contracts.
+- `references/json-render-core.md` — catalog zod props and spec shape.
+- `references/json-render-react.md` — registry mapping, providers, and actions.
+- `references/json-render-next.md` — the Next rendering shape.
+- `references/json-render-shadcn.md` — standard component definitions.
 
-## json-render references (consult when authoring element types)
+## Stack constraints
 
-When adding a view you register new element `type`s in the view module: the zod
-catalog entry in `views/<view>/index.tsx` and the component mapping in
-`views/<view>/registry.tsx` ('use client'). Consult the vendored references
-instead of working from memory:
+- UI components only from `@thorprovider/blocks`.
+- Data only through `@thorprovider/adapters` + `@thorprovider/runtime/commerce`.
+- Never `@thorprovider/medusa-extended`.
+- No custom blocks without explicit user authorization.
+- A missing capability is a gap to report, not a reason to install another UI
+  framework or hand-edit a derived file.
 
-- `../json-render-core/` — catalog/schema/spec authoring (the shape of a catalog entry and a spec element)
-- `../json-render-react/` — registry mapping and action wiring (`defineRegistry`, `Renderer`, `useStateStore`)
+## Workflow model
 
-**Selection rule:** choose an **intent by meaning** from the user's description (never a raw variant ordinal), then resolve the intent to its variant via `assets/recipes/archetypes.json`. The resolved variant must be allowed by the recipe for that slot. Choose optional sections the same way. Never invent an intent, variant, or component. If the description is silent, use the archetype slot `default`.
+Read `../storefront-workflow/SKILL.md` for the four phases and the CLI/agent
+authority.
 
-```bash
-node scripts/validate.mjs resolve home hero showcase   # -> StorefrontHero2
-```
-
-## Stack constraints
-- UI: only `@thorprovider/blocks`
-- Data: only `@thorprovider/adapters` + `@thorprovider/runtime/commerce`
-- Never `@thorprovider/medusa-extended`
-- No custom blocks without explicit user authorization
-- **Two-file view split (RSC):** `index.tsx` is a pure Server Component module (name, elements, zod catalog, route, loader) and imports `registry` from the sibling `registry.tsx` as data. `registry.tsx` is the **`'use client'`** module and is the only place that imports values from `@json-render/react` or `@thorprovider/blocks`. Never add those imports to `index.tsx` — `@json-render/react` calls `createContext` at module scope, which breaks the RSC server graph.
-- Every element `type` used in a spec MUST be registered in the view's zod catalog (`index.tsx`) AND its client registry (`registry.tsx`); the shared `catalog.ts` / `registry.tsx` compose both through the barrel and are never hand-edited
-
-## Add-view workflow
-
-1. Parse `$ARGUMENTS` → view name (+ optional description). Validate name. Confirm `lib/<name>/` exists (else run `npx @thorprovider/storefront create` to scaffold it).
-2. `node scripts/validate.mjs show <view>` — read slots, allowed variants + sections. `node scripts/validate.mjs archetypes` — read slots with their named intents.
-3. Choose an intent per slot by meaning from the description (defaults if silent), resolve each with `node scripts/validate.mjs resolve <view> <slot> <intent>`, choose optional sections the same way, then validate the full composition with `node scripts/validate.mjs validate '<json>'` **before writing anything**. On failure → stop, show the allowed options.
-4. Copy the view template: `assets/templates/views/<view>/` → `lib/<name>/views/<view>/`. Each template is the two-file split: `index.tsx` (server spec) + `registry.tsx` ('use client' component mappings).
-5. Register it in the barrel `lib/<name>/views/index.ts` — ONE import and ONE array entry:
-   ```ts
-   import { <view> } from './<view>'
-   export const views: ViewModule[] = [home, <view>]
-   ```
-6. Substitute variants: each slot's block is imported under a stable alias (e.g. `ProductOverview1 as ProductOverviewBlock`), shipping the recipe default. Replace **only the imported identifier** with the resolved variant — never the alias, never the props:
-   ```ts
-   import { ProductOverview5 as ProductOverviewBlock } from '@thorprovider/blocks'
-   ```
-7. Include any chosen optional section — fragments live at `assets/templates/views/sections/` as a two-file split:
-   - `<section>.tsx` (server): exports the section object with `elementType`, the zod `catalog` entry, and `registryModule: './<section>.client'`.
-   - `<section>.client.tsx` ('use client'): exports `registry: ViewRegistry` with the component mapping.
-   Import the section object from `<section>` into `index.tsx` and merge its elements/catalog into the view; put the component mapping from `<section>.client` into the view's `registry.tsx` (re-exporting the fragment's registry).
-8. Verify: `yarn typecheck`. Do NOT hand-edit `catalog.ts`, `registry.tsx`, `runtime.ts`, or `spec/index.ts` — they compose whatever the barrel exports.
-
-## Modify workflow (`/sf-view`)
-
-1. Parse view name + change. Validate name.
-2. Read `lib/<name>/views/<view>/index.tsx` (server spec) and `registry.tsx` (client mappings) fully.
-3. Apply ONLY the change. Preserve ids, `type`, untouched `props`, `$state`, `on` wiring, route/loader, and the barrel entry.
-4. If new blocks are needed, choose intents from `archetypes.json`, resolve to allowed variants, and validate before writing.
-5. Re-run `yarn typecheck`.
-
-## Generation headers
-Every generated/edited file gets:
-```
-// Generated by @thorprovider/storefront (sf-view-gen) from recipes/<view>
-```
+## Completion criteria
 
-## Error handling
-- Unknown view → error + allowed list, stop.
-- Missing `lib/<name>/` → run `npx @thorprovider/storefront create`, stop.
-- Undeclared variant/section → reject via `recipes/validate.mjs`, show allowed options.
-- Type errors → fix before finishing; never leave broken specs.
+- The manifest reflects the requested composition and `sync` reports no drift.
+- Only user-owned files were hand-edited; every derived file was written by the
+  CLI.
+- The CLI command's exit status was checked and reported.

package/skills/sf-view-gen/assets/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",
@@ -88,6 +88,15 @@
         }
       }
     },
+    "cart.view": {
+      "default": "review",
+      "intents": {
+        "review": {
+          "variant": "ShoppingCart4",
+          "when": "A standalone cart review page: line editing plus backend-authoritative totals before checkout."
+        }
+      }
+    },
     "category.filter": {
       "default": "sidebar",
       "intents": {
@@ -122,25 +131,30 @@
         }
       }
     },
-    "user-panel.shell": {
-      "default": "standard",
+    "account.login": {
+      "default": "signIn",
       "intents": {
-        "standard": {
-          "variant": "AppShell1",
-          "when": "A standard account shell with side navigation and content area."
+        "signIn": {
+          "variant": "LoginPage1",
+          "when": "A full sign-in page with email and password and a link to create an account."
         }
       }
     },
-    "user-panel.orderHistory": {
-      "default": "compact",
+    "account.register": {
+      "default": "signUp",
       "intents": {
-        "compact": {
-          "variant": "OrderHistory1",
-          "when": "A concise list of past orders with status and totals."
-        },
-        "detailed": {
+        "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": "Order history with line-item detail, tracking, and reorder actions."
+          "when": "A signed-in shopper's order history with per-order totals and detail on demand."
         }
       }
     }