@thorprovider/storefront 0.4.0-mvp.0 → 0.4.0-mvp.2

package/examples/merchandising/category-led.json

@@ -0,0 +1,37 @@
+{
+  "name": "category-led",
+  "title": "Category-led combined presentation plus freshness selection",
+  "intent": "Lead with a category-focused combined grid-and-carousel of the newest arrivals, keep category navigation visible, and cross-sell a related category below. Selection (category handle and ordering) is independent of the presentation variant.",
+  "sections": [
+    { "id": "slot:hero", "type": "hero", "variant": "StorefrontHero1" },
+    { "id": "slot:benefits", "type": "benefits", "variant": "Feature1" },
+    { "id": "slot:categories", "type": "categories", "variant": "ProductCategory2" },
+    {
+      "id": "home-products-1",
+      "type": "products",
+      "variant": "ProductShowcase1",
+      "objective": "Showcase the newest arrivals in a category as a browsable carousel",
+      "destination": "/categories/repuestos",
+      "source": {
+        "kind": "products",
+        "query": { "categories": ["repuestos"], "sort": "newest", "pageSize": 12 }
+      },
+      "content": {
+        "heading": "Novedades en repuestos",
+        "description": "Lo último que llega a la categoría."
+      }
+    },
+    {
+      "id": "home-products-2",
+      "type": "products",
+      "variant": "ProductCard1",
+      "objective": "Cross-sell a related category below the carousel",
+      "destination": "/categories/accesorios",
+      "source": {
+        "kind": "products",
+        "query": { "categories": ["accesorios"], "sort": "featured", "pageSize": 4 }
+      },
+      "content": { "heading": "Accesorios recomendados" }
+    }
+  ]
+}

package/examples/merchandising/collection-led.json

@@ -0,0 +1,37 @@
+{
+  "name": "collection-led",
+  "title": "Collection-led grid plus campaign CTA",
+  "intent": "Lead the home with one curated collection as the primary merchandise grid, and reinforce it with a single campaign call to action. The selection is a collection handle, not a sales ranking.",
+  "sections": [
+    { "id": "slot:hero", "type": "hero", "variant": "StorefrontHero1" },
+    { "id": "slot:benefits", "type": "benefits", "variant": "Feature1" },
+    {
+      "id": "home-products-1",
+      "type": "products",
+      "variant": "ProductCard1",
+      "objective": "Move collection browsers into the featured collection",
+      "destination": "/collections/featured",
+      "source": {
+        "kind": "products",
+        "query": { "collections": ["featured"], "sort": "featured", "pageSize": 8 }
+      },
+      "content": {
+        "heading": "Destacados de la temporada",
+        "description": "Una selección curada de la colección destacada."
+      }
+    },
+    {
+      "id": "home-cta-1",
+      "type": "cta",
+      "objective": "Reinforce the campaign message with one clear action",
+      "destination": "/collections/featured",
+      "content": {
+        "badgeText": "Campaña",
+        "title": "Envío gratis esta semana",
+        "description": "En pedidos superiores al mínimo de la campaña.",
+        "primaryCta": { "label": "Ver la colección", "href": "/collections/featured" }
+      }
+    },
+    { "id": "slot:categories", "type": "categories", "variant": "ProductCategory2" }
+  ]
+}

package/package.json

@@ -1,17 +1,20 @@
 {
   "name": "@thorprovider/storefront",
-  "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)",
+  "version": "0.4.0-mvp.2",
+  "description": "Deterministic storefront scaffolder and installable OpenCode skill suite for Thor Commerce (Next.js, @thorprovider/blocks, @thorprovider/adapters, Medusa)",
   "type": "module",
-  "bin": "./bin/storefront.js",
+  "bin": {
+    "storefront": "bin/storefront.js"
+  },
   "files": [
     "assets",
     "bin",
-    "commands",
+    "examples",
     "skills",
     "recipes",
     "scripts",
-    "README.md"
+    "README.md",
+    "VENDOR.md"
   ],
   "engines": {
     "node": ">=20.9.0"
@@ -21,7 +24,7 @@
     "check-assets": "node ./scripts/sync-assets.mjs --check",
     "pretest": "node ./scripts/sync-assets.mjs --check",
     "test": "vitest run --config vitest.config.ts",
-    "test:integration": "vitest run --config vitest.config.ts tests/scaffold-integration.test.ts"
+    "test:integration": "vitest run --config vitest.config.ts tests/scaffold-integration.test.ts tests/starter-integration.test.ts"
   },
   "publishConfig": {
     "access": "public",
@@ -41,10 +44,11 @@
   ],
   "dependencies": {
     "@clack/prompts": "^1.8.1",
+    "@fission-ai/openspec": "1.11.0",
     "semver": "^7.7.4"
   },
   "devDependencies": {
     "vitest": "^3.2.4"
   },
   "license": "MIT"
-}
+}

package/recipes/archetypes.json

@@ -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": {
@@ -148,28 +157,6 @@
           "when": "A signed-in shopper's order history with per-order totals and detail on demand."
         }
       }
-    },
-    "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/catalog.json

@@ -1,7 +1,7 @@
 {
   "$schema": "./catalog.schema.json",
   "catalogVersion": 1,
-  "description": "Initial semantic executable catalog (E1 tasks 1.2-1.3), classified by source-shape inspection of the @thorprovider/blocks prop contracts and the view templates. Scope: every slot the curated MVP views (home, product, category, checkout, account) render by default, covering both the selectable archetype slots declared by recipes/archetypes.json and the nested default slots that have no archetype (category.productCard, checkout.confirmation) so no legacy default support is dropped. The account view (change: storefront-customer-auth) declares the login/register slots: LoginPage1/SignUpPage1 are executable while LoginPage2 is held for its divergent callback contract. A variant is `executable` only when the slot's canonical data shape can feed its block props without a prop bridge and without inventing data; every other non-default variant is `held` with the specific reason. The one executable non-default swap is home.benefits Feature1 -> Feature2 (identical item contract, no bridge). user-panel (non-MVP view) is outside this initial catalog scope. E2 task 6.1 declares the base listing slot category.filter CategoryFilter2 as the single controlled listing (dataShape `CatalogQuery & CatalogResults`, state controlled) with the search/filter controls contributed by the logical mounts category.search / category.filters (no second block). Source-shape compatibility is not end-to-end backend behavior proof: the render is executable, but the category.search.apply / category.filter.apply actions remain held under the capability catalog (owner: storefront-catalog-search-filters, E2) until a real runtime proof. The `capabilities` map declares those operational capabilities with their requirements and verification state; E1 declares the held category.filter.apply action, E2 adds the held category.search.apply action and the held category.price.range capability that gates the category-filters showPrice option; no capability is claimed verified.",
+  "description": "Initial semantic executable catalog (E1 tasks 1.2-1.3), classified by source-shape inspection of the @thorprovider/blocks prop contracts and the view templates. Scope: every slot the curated MVP views (home, product, category, checkout, account) render by default, covering both the selectable archetype slots declared by recipes/archetypes.json and the nested default slots that have no archetype (category.productCard, checkout.confirmation) so no legacy default support is dropped. The account view (change: storefront-customer-auth) declares the login/register slots: LoginPage1/SignUpPage1 are executable while LoginPage2 is held for its divergent callback contract. A variant is `executable` only when the slot's canonical data shape can feed its block props without a prop bridge and without inventing data; every other non-default variant is `held` with the specific reason. The one executable non-default swap is home.benefits Feature1 -> Feature2 (identical item contract, no bridge). E2 task 6.1 declares the base listing slot category.filter CategoryFilter2 as the single controlled listing (dataShape `CatalogQuery & CatalogResults`, state controlled) with the search/filter controls contributed by the logical mounts category.search / category.filters (no second block). Source-shape compatibility is not end-to-end backend behavior proof: the render is executable, but the category.search.apply / category.filter.apply actions remain held under the capability catalog (owner: storefront-catalog-search-filters, E2) until a real runtime proof. The `capabilities` map declares those operational capabilities with their requirements and verification state; E1 declares the held category.filter.apply action, E2 adds the held category.search.apply action and the held category.price.range capability that gates the category-filters showPrice option; no capability is claimed verified.",
   "slots": {
     "home.hero": {
       "default": "StorefrontHero1",
@@ -157,6 +157,32 @@
         }
       }
     },
+    "product.breadcrumb": {
+      "default": "Breadcrumb",
+      "variants": {
+        "Breadcrumb": {
+          "status": "executable",
+          "block": "Breadcrumb",
+          "dataShape": "BreadcrumbItemData[]",
+          "events": [],
+          "state": "uncontrolled",
+          "requirements": ["productBreadcrumb"]
+        }
+      }
+    },
+    "cart.view": {
+      "default": "ShoppingCart4",
+      "variants": {
+        "ShoppingCart4": {
+          "status": "executable",
+          "block": "ShoppingCart4",
+          "dataShape": "CartLineState[] & CartTotalsState",
+          "events": ["refreshCart", "updateQuantity", "removeFromCart", "checkout", "continueShopping"],
+          "state": "controlled",
+          "requirements": ["cart", "cartTotals"]
+        }
+      }
+    },
     "category.filter": {
       "default": "CategoryFilter2",
       "variants": {
@@ -339,6 +365,19 @@
           "requirements": ["accountCustomer", "accountAuthenticated"]
         }
       }
+    },
+    "category.breadcrumb": {
+      "default": "Breadcrumb",
+      "variants": {
+        "Breadcrumb": {
+          "status": "executable",
+          "block": "Breadcrumb",
+          "dataShape": "BreadcrumbItemData[]",
+          "events": [],
+          "state": "uncontrolled",
+          "requirements": ["categoryBreadcrumb"]
+        }
+      }
     }
   },
   "capabilities": {

package/recipes/features.json

@@ -30,7 +30,7 @@
       "name": "customer-auth",
       "mvp": true,
       "description": "Customer authentication: registration, login, logout, and a minimal signed-in state. Owns the account view.",
-      "route": "/cuenta",
+      "route": "/account",
       "views": ["account"],
       "state": [
         "accountCustomer",
@@ -48,7 +48,7 @@
       "name": "static-pages",
       "mvp": true,
       "description": "Content-driven static pages (contact, legal, about) served with per-page metadata. Owns the static view.",
-      "route": "/contacto",
+      "route": "/contact",
       "views": ["static"],
       "state": [],
       "handlers": [],
@@ -122,6 +122,29 @@
       "mounts": [{ "id": "category-filters", "host": "category", "slot": "filters" }],
       "surfaces": []
     },
+    {
+      "name": "navigability",
+      "mvp": true,
+      "description": "Cross-cutting navigability feature: entity-derived breadcrumbs with BreadcrumbList structured data on the product and category surfaces, plus skip-to-content, current-page indication, back-to-top, and a mobile bottom navigation in the shared shell.",
+      "views": [],
+      "state": [],
+      "handlers": [],
+      "adapter": { "needs": [] },
+      "config": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "presentation": { "type": "string", "enum": ["default"], "default": "default" },
+          "showBackToTop": { "type": "boolean", "default": true }
+        }
+      },
+      "presentations": { "default": "Breadcrumb" },
+      "mounts": [
+        { "id": "category-breadcrumb", "host": "category", "slot": "breadcrumb" },
+        { "id": "product-breadcrumb", "host": "product", "slot": "breadcrumb" }
+      ],
+      "surfaces": []
+    },
     {
       "name": "recommendations",
       "mvp": false,

package/recipes/recipe.schema.json

@@ -23,7 +23,7 @@
         "properties": {
           "name": {
             "type": "string",
-            "enum": ["home", "product", "category", "checkout", "account", "static", "user-panel"]
+            "enum": ["home", "product", "cart", "category", "checkout", "account", "static"]
           },
           "description": { "type": "string" },
           "route": { "type": "string" },

package/recipes/recipes.json

@@ -22,47 +22,69 @@
       },
       "optionalSections": ["testimonials", "faq", "statistics", "logoCloud", "pricing"],
       "registeredSlots": ["hero", "benefits", "categories"],
-      "allowedSections": ["faq", "cta"],
+      "allowedSections": ["faq", "cta", "products"],
       "maxSections": 4
     },
     {
       "name": "product",
       "mvp": true,
       "description": "Single product detail page with overview, gallery, and reviews",
-      "route": "/productos/[id]",
+      "route": "/products/[id]",
       "loader": "product",
       "requiredDataKeys": ["selectedProduct"],
       "defaultVariants": {
         "overview": "ProductOverview1",
-        "reviews": "ReviewRating1"
+        "reviews": "ReviewRating1",
+        "breadcrumb": "Breadcrumb"
       },
       "allowedVariants": {
         "overview": ["ProductOverview1", "ProductOverview2", "ProductOverview5"],
         "reviews": ["ReviewRating1", "ReviewRating2"],
+        "breadcrumb": ["Breadcrumb"],
         "productCard": ["ProductCard1", "ProductCard2", "ProductCard3", "ProductCard5"]
       },
       "optionalSections": ["testimonials", "faq", "statistics"],
-      "registeredSlots": ["overview", "reviews"],
+      "registeredSlots": ["overview", "reviews", "breadcrumb"],
       "allowedSections": [],
       "maxSections": 4
     },
+    {
+      "name": "cart",
+      "mvp": true,
+      "description": "Standalone cart review page with authoritative totals and quantity editing",
+      "route": "/cart",
+      "loader": "cart",
+      "requiredDataKeys": ["cart"],
+      "defaultVariants": {
+        "view": "ShoppingCart4"
+      },
+      "allowedVariants": {
+        "view": ["ShoppingCart4"]
+      },
+      "optionalSections": [],
+      "registeredSlots": ["view"],
+      "allowedSections": [],
+      "maxSections": 0
+    },
     {
       "name": "category",
       "mvp": true,
       "description": "Product listing filtered by category with filters and sorting",
-      "route": "/categorias/[[...slug]]",
+      "route": "/categories/[[...slug]]",
       "loader": "category",
       "requiredDataKeys": ["categoryProducts", "storeCategories"],
       "defaultVariants": {
         "filter": "CategoryFilter2",
-        "productCard": "ProductCard1"
+        "productCard": "ProductCard1",
+        "breadcrumb": "Breadcrumb"
       },
       "allowedVariants": {
         "filter": ["CategoryFilter1", "CategoryFilter2", "CategoryFilter4"],
-        "productCard": ["ProductCard1", "ProductCard2", "ProductCard3", "ProductCard5"]
+        "productCard": ["ProductCard1", "ProductCard2", "ProductCard3", "ProductCard5"],
+        "breadcrumb": ["Breadcrumb"]
       },
       "optionalSections": ["logoCloud", "testimonials"],
-      "registeredSlots": ["filter", "productCard"],
+      "registeredSlots": ["breadcrumb", "filter", "productCard"],
       "allowedSections": ["faq", "cta"],
       "maxSections": 4
     },
@@ -90,7 +112,7 @@
       "name": "account",
       "mvp": true,
       "description": "Customer account area with sign-in, registration, and a minimal signed-in state",
-      "route": "/cuenta",
+      "route": "/account",
       "loader": "account",
       "requiredDataKeys": ["accountCustomer"],
       "defaultVariants": {
@@ -111,7 +133,7 @@
       "name": "static",
       "mvp": true,
       "description": "Content-driven static pages (contact, legal, about) with per-page metadata",
-      "route": "/contacto",
+      "route": "/contact",
       "loader": "static",
       "requiredDataKeys": [],
       "defaultVariants": {},
@@ -120,26 +142,6 @@
       "registeredSlots": [],
       "allowedSections": [],
       "maxSections": 0
-    },
-    {
-      "name": "user-panel",
-      "mvp": false,
-      "description": "Customer account area with order history and account navigation",
-      "route": "/cuenta",
-      "loader": "userPanel",
-      "requiredDataKeys": ["lastOrder", "lastOrderLines", "orderPlaced"],
-      "defaultVariants": {
-        "shell": "AppShell1",
-        "orderHistory": "OrderHistory1"
-      },
-      "allowedVariants": {
-        "shell": ["AppShell1"],
-        "orderHistory": ["OrderHistory1", "OrderHistory2"]
-      },
-      "optionalSections": [],
-      "registeredSlots": ["shell", "orderHistory"],
-      "allowedSections": [],
-      "maxSections": 4
     }
   ]
 }

package/recipes/sections.json

@@ -31,6 +31,16 @@
       "propsHint": "badgeText, title, description, primaryCta/secondaryCta (label, href)",
       "status": "executable"
     },
+    {
+      "name": "products",
+      "description": "Data-bound product presentation (grid or combined grid-and-carousel) whose selection is configured independently per instance",
+      "elementType": "Products",
+      "variants": ["ProductCard1", "ProductShowcase1"],
+      "defaultVariant": "ProductCard1",
+      "dataBound": true,
+      "propsHint": "per-instance selection configured in views/<view>/data.ts sectionSources[id] (canonical category/collection/search/ordering query); heading, description, objective, ctaLabel/ctaHref are editorial content",
+      "status": "executable"
+    },
     {
       "name": "statistics",
       "description": "Key metrics or trust statistics",

package/recipes/validate.mjs

@@ -455,6 +455,27 @@ export function sectionRegistry() {
   }))
 }
 
+/**
+ * The full registry entry for a section type, or null when it is not
+ * registered. Unlike `sectionRegistry()` (the projected introspection view),
+ * this exposes every declared field — including `dataBound` and `variants` —
+ * so the CLI can tell which instances need user-owned source configuration.
+ */
+export function sectionDefinitionByName(name) {
+  const list = Array.isArray(sections.sections) ? sections.sections : []
+  return list.find((entry) => isPlainObject(entry) && entry.name === name) ?? null
+}
+
+/**
+ * Whether a section type resolves its content from a data source configured by
+ * the user (for example the `products` type) rather than from static editorial
+ * content. Unregistered types are not data-bound.
+ */
+export function sectionIsDataBound(name) {
+  const section = sectionDefinitionByName(name)
+  return section?.status === 'executable' && section.dataBound === true
+}
+
 export function getRecipe(name) {
   return recipes.views.find((v) => v.name === name) ?? null
 }
@@ -485,6 +506,39 @@ export function isCuratedFeature(name) {
   return getFeature(name)?.mvp === true
 }
 
+/**
+ * The starter composition: every curated (installable) feature plus every
+ * curated view no installed curated feature owns. A feature-owned view (for
+ * example `checkout`, owned by the `checkout` feature) is installed through its
+ * feature, not listed directly. The set is derived from the registry's
+ * `mvp: true` declaration — never a hand-maintained list — so a curated unit
+ * added or removed flows automatically and a held unit (`recommendations`, a
+ * held section) is excluded by construction.
+ *
+ * `registries` is the injection seam for tests: pass fixture `{ views }` /
+ * `{ features }` sources to exercise the derivation without mutating the loaded
+ * registry.
+ */
+export function starterComposition(registries = {}) {
+  const recipeSource = registries.recipes ?? recipes
+  const featureSource = registries.features ?? features
+  const featureNames = featureSource.features
+    .filter((f) => f.mvp === true)
+    .map((f) => f.name)
+  const ownedViews = new Set()
+  for (const name of featureNames) {
+    const feature = featureSource.features.find((f) => f.name === name)
+    for (const view of Array.isArray(feature?.views) ? feature.views : []) {
+      ownedViews.add(view)
+    }
+  }
+  const viewNames = recipeSource.views
+    .filter((v) => v.mvp === true)
+    .map((v) => v.name)
+    .filter((name) => !ownedViews.has(name))
+  return { views: viewNames, features: featureNames }
+}
+
 /**
  * The catalog entry for one slot ("<view>.<slot>"), or null when the slot is
  * outside the catalog scope (a held, non-curated view). The catalog is the

package/scripts/candidate.mjs

@@ -42,10 +42,10 @@ export const CANDIDATE_TOOLSET = Object.freeze({
     '@json-render/next': '0.21.0',
   }),
   local: Object.freeze({
-    '@thorprovider/blocks': '0.1.1',
-    '@thorprovider/adapters': '5.0.11',
-    '@thorprovider/runtime': '0.1.2',
-    '@thorprovider/types': '5.7.7',
+    '@thorprovider/blocks': '0.1.2',
+    '@thorprovider/adapters': '5.0.12',
+    '@thorprovider/runtime': '0.1.4',
+    '@thorprovider/types': '5.8.0',
   }),
 })
 

package/scripts/composers.mjs

@@ -83,16 +83,27 @@ function isPlainObject(value) {
  * derived from the manifest — never hardcoded as always-mounted.
  *
  * `features` accepts bare names or `{ name, config }` entries (the fresh
- * scaffold and a later reconcile both pass manifest entries).
+ * scaffold and a later reconcile both pass manifest entries). `views` accepts
+ * bare view names or `{ name }` entries; it drives the typed route/action
+ * availability flags below so the generated host can suppress links to routes
+ * that are not installed (e.g. the cart review page or checkout).
  */
-export function buildCompositionComposer(features) {
+export function buildCompositionComposer(features, views = []) {
   const entries = (Array.isArray(features) ? features : []).map((feature) =>
     typeof feature === 'string' ? { name: feature, config: {} } : feature,
   )
   const installed = new Set(entries.map((entry) => entry.name))
+  const viewNames = (Array.isArray(views) ? views : []).map((view) =>
+    typeof view === 'string' ? view : view.name,
+  )
+  const installedViews = new Set(viewNames)
+  const cartViewAvailable = installedViews.has('cart')
+  const checkoutAvailable = installed.has('checkout') || installedViews.has('checkout')
   const names = CATALOG_FEATURE_NAMES.filter((name) => installed.has(name))
   const list = names.map((name) => JSON.stringify(name)).join(', ')
-  const configLines = names
+  const installedNames = [...installed].sort()
+  const featureNameList = installedNames.map((name) => JSON.stringify(name)).join(', ')
+  const configLines = installedNames
     .map((name) => {
       const entry = entries.find((candidate) => candidate.name === name)
       const config = entry && isPlainObject(entry.config) ? entry.config : {}
@@ -109,9 +120,18 @@ export function buildCompositionComposer(features) {
     `// visibility/config from the installed manifest only.\n\n` +
     `import type { CatalogFeatureName } from '@thorprovider/runtime/contracts'\n\n` +
     `export const mountedFeatures: readonly CatalogFeatureName[] = [${list}]\n\n` +
-    `export const mountedFeatureConfigs: Partial<Record<CatalogFeatureName, Record<string, unknown>>> = {\n` +
+    `// Every installed feature name, unfiltered by the catalog URL boundary. The\n` +
+    `// general presence seam cross-cutting features read to gate their own\n` +
+    `// contributions (e.g. the navigability feature's shell chrome).\n` +
+    `export const mountedFeatureNames: readonly string[] = [${featureNameList}]\n\n` +
+    `export const mountedFeatureConfigs: Partial<Record<string, Record<string, unknown>>> = {\n` +
     `${configLines ? `${configLines}\n` : ''}` +
-    `}\n`
+    `}\n\n` +
+    `// Typed route/action availability derived from the installed manifest. The\n` +
+    `// generated host uses these to hide links to routes that are not installed,\n` +
+    `// so a removed view never leaves an active dead-end navigation target.\n` +
+    `export const cartViewAvailable = ${cartViewAvailable}\n\n` +
+    `export const checkoutAvailable = ${checkoutAvailable}\n`
   )
 }
 

package/scripts/env-file.mjs

@@ -0,0 +1,86 @@
+// Environment-file helpers for the scaffold.
+//
+// `create` starts a storefront in mock mode with a minimal, working `.env.local`
+// and never writes a blank `MEDUSA_*` value; `setup` later upserts the real-backend
+// keys without disturbing anything else in the file. Both behaviours are pure
+// enough to unit-test here rather than only through the network-heavy create path.
+import { existsSync, readFileSync } from 'node:fs'
+import { writeFile } from 'node:fs/promises'
+import { randomBytes } from 'node:crypto'
+import { join } from 'node:path'
+
+// The minimal mock environment `create` writes: an explicit mock data source, the
+// store identity, and the per-install session secret the guest cart and checkout
+// cookie signing requires. No backend key is written here.
+export function initialEnvLocal(name, sessionSecret) {
+  return [
+    'THOR_DATA_SOURCE=mock',
+    `THOR_STORE_ID=${name}`,
+    `THOR_SESSION_SECRET=${sessionSecret}`,
+  ].join('\n') + '\n'
+}
+
+// The committed example documenting both modes. The real-backend keys are blank
+// placeholders — `storefront setup` fills them.
+export function envExample(name) {
+  return [
+    '# Data source: "mock" for explicit demo data (no backend needed), "medusa" for a real backend.',
+    'THOR_DATA_SOURCE=mock',
+    '# Store identity (written by create; required only in real mode).',
+    `THOR_STORE_ID=${name}`,
+    '# Real backend configuration (required only when THOR_DATA_SOURCE=medusa).',
+    '# Run `storefront setup` to write these: it takes the sales channel id (from the',
+    '# Medusa admin) and derives the currency from the selected region.',
+    'MEDUSA_BASE_URL=http://localhost:9000',
+    'MEDUSA_PUBLISHABLE_KEY=',
+    'MEDUSA_REGION_ID=',
+    'MEDUSA_SALES_CHANNEL_ID=',
+    'MEDUSA_CURRENCY_CODE=',
+    '# Host-only cookie signing secret; >=16 chars, 32 recommended. Generated by create.',
+    'THOR_SESSION_SECRET=',
+  ].join('\n') + '\n'
+}
+
+// Write the initial `.env.local` only when one is absent (an existing file is
+// user-owned — a `setup` run or a hand edit — and is never clobbered), and always
+// refresh the committed `.env.example`. Returns whether `.env.local` was written.
+export async function writeInitialEnv(target, name) {
+  const envPath = join(target, '.env.local')
+  let wrote = false
+  if (!existsSync(envPath)) {
+    const sessionSecret = randomBytes(32).toString('base64url')
+    await writeFile(envPath, initialEnvLocal(name, sessionSecret), 'utf8')
+    wrote = true
+  }
+  await writeFile(join(target, '.env.example'), envExample(name), 'utf8')
+  return wrote
+}
+
+// Replace the managed keys in a dotenv-style file, appending any that are absent,
+// and leave every other line (comments, blank lines, unrelated keys) exactly as it
+// was. Idempotent: re-running with the same values produces the same file.
+export function upsertEnv(text, managed) {
+  const seen = new Set()
+  const lines = text.length ? text.split('\n') : []
+  const out = lines.map((line) => {
+    const match = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line)
+    if (match && Object.prototype.hasOwnProperty.call(managed, match[1])) {
+      seen.add(match[1])
+      return `${match[1]}=${managed[match[1]]}`
+    }
+    return line
+  })
+  const missing = Object.keys(managed).filter((key) => !seen.has(key))
+  // Drop trailing blank lines before appending so re-runs do not accumulate them.
+  while (out.length && out[out.length - 1] === '') out.pop()
+  if (missing.length) {
+    if (out.length) out.push('')
+    for (const key of missing) out.push(`${key}=${managed[key]}`)
+  }
+  return out.join('\n') + '\n'
+}
+
+// Read a dotenv file as text, or '' when it does not exist.
+export function readEnvFile(path) {
+  return existsSync(path) ? readFileSync(path, 'utf8') : ''
+}