@thorprovider/storefront 0.6.3 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (161) hide show
  1. package/README.md +22 -2
  2. package/assets/templates/AGENTS.md +14 -2
  3. package/assets/templates/app/app/[[...slug]]/page.tsx +9 -2
  4. package/assets/templates/app/lib/__STOREFRONT__/account-address.ts +129 -0
  5. package/assets/templates/app/lib/__STOREFRONT__/account-lifecycle.client.tsx +2 -2
  6. package/assets/templates/app/lib/__STOREFRONT__/account-private.core.ts +143 -0
  7. package/assets/templates/app/lib/__STOREFRONT__/account-profile.ts +220 -0
  8. package/assets/templates/app/lib/__STOREFRONT__/actions.ts +1234 -75
  9. package/assets/templates/app/lib/__STOREFRONT__/addresses-port.ts +107 -0
  10. package/assets/templates/app/lib/__STOREFRONT__/checkout-shipping.core.ts +37 -0
  11. package/assets/templates/app/lib/__STOREFRONT__/commerce.ts +460 -35
  12. package/assets/templates/app/lib/__STOREFRONT__/confirmation.core.ts +240 -0
  13. package/assets/templates/app/lib/__STOREFRONT__/customer-profile-port.ts +103 -0
  14. package/assets/templates/app/lib/__STOREFRONT__/order-detail-port.ts +26 -0
  15. package/assets/templates/app/lib/__STOREFRONT__/orders-port.ts +30 -0
  16. package/assets/templates/app/lib/__STOREFRONT__/ports.ts +18 -0
  17. package/assets/templates/app/lib/__STOREFRONT__/projection-ownership.client.tsx +4 -4
  18. package/assets/templates/app/lib/__STOREFRONT__/session.ts +24 -6
  19. package/assets/templates/app/lib/__STOREFRONT__/state.core.ts +28 -1
  20. package/assets/templates/app/lib/__STOREFRONT__/views/sections/address-book-advanced.client.tsx +29 -0
  21. package/assets/templates/app/lib/__STOREFRONT__/views/sections/checkout-commerce-v1.client.tsx +19 -0
  22. package/assets/templates/app/lib/__STOREFRONT__/views/sections/checkout-commerce-v1.tsx +16 -0
  23. package/assets/templates/app/lib/__STOREFRONT__/views/sections/customer-profile.client.tsx +27 -0
  24. package/assets/templates/app/lib/__STOREFRONT__/views/sections/index.ts +5 -1
  25. package/assets/templates/app/lib/__STOREFRONT__/views/sections/marketplace-product-card.client.tsx +19 -0
  26. package/assets/templates/app/lib/__STOREFRONT__/views/sections/marketplace-product-card.tsx +16 -0
  27. package/assets/templates/app/lib/__STOREFRONT__/views/sections/mega-menu-universal.client.tsx +19 -0
  28. package/assets/templates/app/lib/__STOREFRONT__/views/sections/mega-menu-universal.tsx +16 -0
  29. package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.address-book-advanced.ts +437 -0
  30. package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.checkout-commerce-v1.ts +398 -0
  31. package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.customer-profile.ts +138 -0
  32. package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.marketplace-product-card.ts +67 -0
  33. package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.mega-menu-universal.ts +76 -0
  34. package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.universal-banner.ts +217 -0
  35. package/assets/templates/app/lib/__STOREFRONT__/views/sections/universal-banner.client.tsx +24 -0
  36. package/assets/templates/app/lib/__STOREFRONT__/views/sections/universal-banner.tsx +16 -0
  37. package/assets/templates/features/checkout/handlers.ts +348 -33
  38. package/assets/templates/features/checkout/state.ts +79 -3
  39. package/assets/templates/features/customer-addresses/handlers.ts +11 -0
  40. package/assets/templates/features/customer-addresses/state.ts +33 -0
  41. package/assets/templates/features/customer-auth/state.ts +10 -0
  42. package/assets/templates/features/customer-profile/handlers.ts +11 -0
  43. package/assets/templates/features/customer-profile/state.ts +18 -0
  44. package/assets/templates/views/account/address-book-advanced.defaults.ts +534 -0
  45. package/assets/templates/views/account/assembly/assembly.json +41 -0
  46. package/assets/templates/views/account/assembly/index.skeleton.tsx +229 -0
  47. package/assets/templates/views/account/assembly/registry.skeleton.tsx +1116 -0
  48. package/assets/templates/views/account/assembly/slots/addresses/AddressBookAdvanced/binding.json +5 -0
  49. package/assets/templates/views/account/assembly/slots/addresses/AddressBookAdvanced/catalog.part +4 -0
  50. package/assets/templates/views/account/assembly/slots/addresses/AddressBookAdvanced/element.part +5 -0
  51. package/assets/templates/views/account/assembly/slots/addresses/AddressBookAdvanced/registry.part +1 -0
  52. package/assets/templates/views/account/assembly/slots/addresses/cards/catalog.part +5 -0
  53. package/assets/templates/views/account/assembly/slots/addresses/cards/element.part +10 -0
  54. package/assets/templates/views/account/assembly/slots/addresses/cards/registry.part +1 -0
  55. package/assets/templates/views/account/assembly/slots/boot/AccountBoot/catalog.part +5 -0
  56. package/assets/templates/views/account/assembly/slots/boot/AccountBoot/element.part +5 -0
  57. package/assets/templates/views/account/assembly/slots/boot/AccountBoot/registry.part +1 -0
  58. package/assets/templates/views/account/assembly/slots/login/card/catalog.part +4 -0
  59. package/assets/templates/views/account/assembly/slots/login/card/element.part +13 -0
  60. package/assets/templates/views/account/assembly/slots/login/card/registry.part +1 -0
  61. package/assets/templates/views/account/assembly/slots/orders/OrderHistory/catalog.part +5 -0
  62. package/assets/templates/views/account/assembly/slots/orders/OrderHistory/element.part +5 -0
  63. package/assets/templates/views/account/assembly/slots/orders/OrderHistory/registry.part +2 -0
  64. package/assets/templates/views/account/assembly/slots/orders/OrderHistoryAdvanced/binding.json +5 -0
  65. package/assets/templates/views/account/assembly/slots/orders/OrderHistoryAdvanced/catalog.part +5 -0
  66. package/assets/templates/views/account/assembly/slots/orders/OrderHistoryAdvanced/element.part +5 -0
  67. package/assets/templates/views/account/assembly/slots/orders/OrderHistoryAdvanced/registry.part +1 -0
  68. package/assets/templates/views/account/assembly/slots/profile/CustomerProfileAdvanced/binding.json +5 -0
  69. package/assets/templates/views/account/assembly/slots/profile/CustomerProfileAdvanced/catalog.part +4 -0
  70. package/assets/templates/views/account/assembly/slots/profile/CustomerProfileAdvanced/element.part +5 -0
  71. package/assets/templates/views/account/assembly/slots/profile/CustomerProfileAdvanced/registry.part +1 -0
  72. package/assets/templates/views/account/assembly/slots/profile/form/catalog.part +5 -0
  73. package/assets/templates/views/account/assembly/slots/profile/form/element.part +10 -0
  74. package/assets/templates/views/account/assembly/slots/profile/form/registry.part +1 -0
  75. package/assets/templates/views/account/assembly/slots/register/SignUpPage1/catalog.part +4 -0
  76. package/assets/templates/views/account/assembly/slots/register/SignUpPage1/element.part +13 -0
  77. package/assets/templates/views/account/assembly/slots/register/SignUpPage1/registry.part +1 -0
  78. package/assets/templates/views/account/assembly/slots/summary/stack/catalog.part +5 -0
  79. package/assets/templates/views/account/assembly/slots/summary/stack/element.part +5 -0
  80. package/assets/templates/views/account/assembly/slots/summary/stack/registry.part +1 -0
  81. package/assets/templates/views/account/assembly/slots/summary/tabs/catalog.part +5 -0
  82. package/assets/templates/views/account/assembly/slots/summary/tabs/element.part +5 -0
  83. package/assets/templates/views/account/assembly/slots/summary/tabs/registry.part +1 -0
  84. package/assets/templates/views/account/content.ts +326 -0
  85. package/assets/templates/views/account/customer-profile.defaults.ts +136 -0
  86. package/assets/templates/views/account/index.tsx +218 -35
  87. package/assets/templates/views/account/order-detail.client.tsx +35 -0
  88. package/assets/templates/views/account/order-detail.defaults.ts +457 -0
  89. package/assets/templates/views/account/orders-advanced.client.tsx +166 -0
  90. package/assets/templates/views/account/orders-advanced.defaults.ts +230 -0
  91. package/assets/templates/views/account/registry.tsx +944 -369
  92. package/assets/templates/views/account/schema.ts +50 -0
  93. package/assets/templates/views/account/sections-data.ts +2 -0
  94. package/assets/templates/views/cart/content.ts +1 -0
  95. package/assets/templates/views/category/assembly/index.skeleton.tsx +1 -0
  96. package/assets/templates/views/category/assembly/slots/filter/CategoryListing/element.part +1 -0
  97. package/assets/templates/views/category/content.ts +2 -0
  98. package/assets/templates/views/category/index.tsx +2 -0
  99. package/assets/templates/views/category/sections-data.ts +2 -0
  100. package/assets/templates/views/checkout/checkout-commerce-hosted.tsx +1089 -0
  101. package/assets/templates/views/checkout/content.ts +114 -2
  102. package/assets/templates/views/checkout/index.tsx +7 -1
  103. package/assets/templates/views/checkout/props.ts +70 -22
  104. package/assets/templates/views/checkout/registry.tsx +400 -71
  105. package/assets/templates/views/checkout/schema.ts +260 -9
  106. package/assets/templates/views/home/assembly/assembly.json +28 -0
  107. package/assets/templates/views/home/assembly/index.skeleton.tsx +1 -0
  108. package/assets/templates/views/home/content.ts +2 -0
  109. package/assets/templates/views/home/index.tsx +1 -0
  110. package/assets/templates/views/home/sections-data.ts +2 -0
  111. package/assets/templates/views/product/content.ts +1 -0
  112. package/assets/templates/views/static/content.ts +1 -0
  113. package/bin/storefront.js +343 -13
  114. package/package.json +2 -1
  115. package/recipes/adapter-surface.json +158 -0
  116. package/recipes/archetypes.json +38 -3
  117. package/recipes/catalog.json +138 -1
  118. package/recipes/feature.schema.json +9 -0
  119. package/recipes/features.json +72 -1
  120. package/recipes/manifest.schema.json +5 -0
  121. package/recipes/recipe.schema.json +14 -2
  122. package/recipes/recipes.json +35 -5
  123. package/recipes/section.schema.json +112 -0
  124. package/recipes/sections.json +289 -3
  125. package/recipes/validate.mjs +83 -1
  126. package/scripts/adapter-surface.mjs +41 -0
  127. package/scripts/agent-blocks.mjs +700 -0
  128. package/scripts/block-validator.mjs +45 -0
  129. package/scripts/candidate.mjs +5 -4
  130. package/scripts/composers.mjs +7 -2
  131. package/scripts/default-sections.mjs +78 -0
  132. package/scripts/file-classes.mjs +15 -0
  133. package/scripts/generate-adapter-surface.mjs +148 -0
  134. package/scripts/operations.mjs +100 -0
  135. package/scripts/reconcile.mjs +67 -39
  136. package/scripts/section-configure.mjs +316 -0
  137. package/scripts/sync-assets.mjs +1 -0
  138. package/scripts/view-assembly.mjs +101 -14
  139. package/skills/sf-feature/SKILL.md +19 -0
  140. package/skills/sf-view-gen/SKILL.md +79 -7
  141. package/skills/sf-view-gen/assets/recipes/archetypes.json +38 -3
  142. package/skills/sf-view-gen/assets/recipes/catalog.json +138 -1
  143. package/skills/sf-view-gen/assets/recipes/features.json +72 -1
  144. package/skills/sf-view-gen/assets/recipes/recipes.json +35 -5
  145. package/skills/sf-view-gen/assets/recipes/section.schema.json +112 -0
  146. package/skills/sf-view-gen/assets/recipes/sections.json +289 -3
  147. package/skills/sf-view-gen/assets/templates/views/sections/checkout-commerce-v1.client.tsx +19 -0
  148. package/skills/sf-view-gen/assets/templates/views/sections/checkout-commerce-v1.tsx +16 -0
  149. package/skills/sf-view-gen/assets/templates/views/sections/marketplace-product-card.client.tsx +19 -0
  150. package/skills/sf-view-gen/assets/templates/views/sections/marketplace-product-card.tsx +16 -0
  151. package/skills/sf-view-gen/assets/templates/views/sections/mega-menu-universal.client.tsx +19 -0
  152. package/skills/sf-view-gen/assets/templates/views/sections/mega-menu-universal.tsx +16 -0
  153. package/skills/sf-view-gen/assets/templates/views/sections/schema.checkout-commerce-v1.ts +398 -0
  154. package/skills/sf-view-gen/assets/templates/views/sections/schema.marketplace-product-card.ts +67 -0
  155. package/skills/sf-view-gen/assets/templates/views/sections/schema.mega-menu-universal.ts +76 -0
  156. package/skills/sf-view-gen/assets/templates/views/sections/schema.universal-banner.ts +217 -0
  157. package/skills/sf-view-gen/assets/templates/views/sections/universal-banner.client.tsx +24 -0
  158. package/skills/sf-view-gen/assets/templates/views/sections/universal-banner.tsx +16 -0
  159. package/skills/sf-view-gen/scripts/validate.mjs +83 -1
  160. package/skills/storefront-workflow/SKILL.md +5 -0
  161. package/skills/storefront-workflow/references/mobile-responsiveness.md +1 -1
package/bin/storefront.js CHANGED
@@ -84,6 +84,8 @@ import {
84
84
  loadArchetypes,
85
85
  loadFeatures,
86
86
  isCuratedView,
87
+ featureStatus,
88
+ getFeature,
87
89
  featureSurfaces,
88
90
  allowedVariantsForView,
89
91
  supportedVariantsForView,
@@ -91,9 +93,10 @@ import {
91
93
  viewCatalog,
92
94
  sectionRegistry,
93
95
  sectionIsDataBound,
96
+ loadSections,
94
97
  } from '../recipes/validate.mjs'
95
98
  import { CATALOG_VERSION, loadCatalog } from '../recipes/catalog.mjs'
96
- import { OPERATION_NAMES } from '../scripts/operations.mjs'
99
+ import { OPERATION_NAMES, installGateDiagnostics } from '../scripts/operations.mjs'
97
100
  import {
98
101
  applyProject,
99
102
  executeOperations,
@@ -103,8 +106,17 @@ import {
103
106
  resultEnvelope,
104
107
  } from '../scripts/plan-apply.mjs'
105
108
  import { SECTION_OPERATION_REGISTRY } from '../scripts/section-operations.mjs'
109
+ import { seedDefaultSections } from '../scripts/default-sections.mjs'
106
110
  import { auditSectionConfig, collectDataBoundInstances } from '../scripts/section-config.mjs'
107
111
  import { normalizeViewSectionsForView } from '../scripts/section-compat.mjs'
112
+ import {
113
+ checkAgentBlocksWithValidatorStatus,
114
+ listAgentBlocksWithValidatorStatus,
115
+ loadAgentBlocks,
116
+ showAgentBlockWithValidatorStatus,
117
+ auditSectionSidecars,
118
+ } from '../scripts/agent-blocks.mjs'
119
+ import { configureSection } from '../scripts/section-configure.mjs'
108
120
 
109
121
  const __dirname = dirname(fileURLToPath(import.meta.url))
110
122
  const PKG_ROOT = resolve(__dirname, '..')
@@ -155,7 +167,11 @@ Usage:
155
167
  storefront view add|remove <name> Add or remove a view (reconciles derived files)
156
168
  storefront feature add|remove <name> Add or remove a feature (installs its views)
157
169
  storefront section add|remove|move <view> ... Add, remove, or move a section instance
170
+ storefront section configure <view> <id> --data <file|-> [options] Validate and configure section content
158
171
  storefront sections [<view>] [--json] List installed views' section instances (read-only)
172
+ storefront blocks list [--json] List agent-configurable sections for installed views
173
+ storefront blocks show <type> [--json] Show an agent section contract and installed instances
174
+ storefront blocks check [--json] Validate the section agent-card registry
159
175
  storefront inspect [--json] Report the versioned catalog and composition (read-only)
160
176
  storefront plan --operations <file> [--out <file>] [--json]
161
177
  Validate a whole intended state and emit a plan
@@ -232,6 +248,9 @@ section options:
232
248
  --first | --last place at the start or end of the composition
233
249
  --at <n> place at a 0-based index (escape hatch)
234
250
  -f, --force allow the write when ownership conflicts are detected
251
+ --data <file|-> configure section data from a JSON file or stdin
252
+ --dry-run validate and describe the sidecar without writing
253
+ --json emit the shared result envelope
235
254
 
236
255
  sections options:
237
256
  --json print the installed views' section instances as JSON
@@ -264,6 +283,7 @@ function parseArgs(argv) {
264
283
  config: null,
265
284
  operations: null,
266
285
  out: null,
286
+ data: null,
267
287
  plan: null,
268
288
  id: null,
269
289
  as: null,
@@ -332,6 +352,11 @@ function parseArgs(argv) {
332
352
  out.exportPath = argv[++i]
333
353
  } else if (arg === '--dry-run') {
334
354
  out.dryRun = true
355
+ } else if (arg === '--data') {
356
+ const value = argv[i + 1]
357
+ if (value !== undefined && (!value.startsWith('-') || value === '-')) {
358
+ out.data = argv[++i]
359
+ }
335
360
  } else if (arg === '--packs') {
336
361
  out.packs = argv[++i]
337
362
  } else if (arg === '--operations') {
@@ -976,13 +1001,15 @@ async function create(args) {
976
1001
  // mkdir, external scaffold, or write so rejected input leaves no trace.
977
1002
  const starter = args.starter === true
978
1003
  const composition = scaffoldComposition({ starter })
979
- const manifest = createManifest({
980
- name,
981
- siteName,
982
- mode,
983
- views: composition.views,
984
- features: composition.features,
985
- })
1004
+ const manifest = seedDefaultSections(
1005
+ createManifest({
1006
+ name,
1007
+ siteName,
1008
+ mode,
1009
+ views: composition.views,
1010
+ features: composition.features,
1011
+ }),
1012
+ )
986
1013
  const preflight = preflightManifest(manifest)
987
1014
  if (!preflight.ok) return rejectComposition(preflight.errors)
988
1015
 
@@ -1198,6 +1225,37 @@ async function create(args) {
1198
1225
  // writes the real-mode environment. The developer supplies the publishable key, the
1199
1226
  // sales channel id (from the Medusa admin), and the region; `setup` derives only the
1200
1227
  // region's currency by reading the store API with the key.
1228
+ // Read the backend's advertised capabilities (`GET /store/thor/capabilities`)
1229
+ // and return the enabled flags as a sorted list. A failure is the caller's to
1230
+ // classify: setup records "unknown" rather than assuming support.
1231
+ async function probeCapabilities(backendUrl, publishableKey) {
1232
+ const res = await fetch(`${backendUrl}/store/thor/capabilities`, {
1233
+ headers: { 'x-publishable-api-key': publishableKey },
1234
+ })
1235
+ if (!res.ok) throw new Error(`GET ${backendUrl}/store/thor/capabilities failed (${res.status})`)
1236
+ const body = await res.json()
1237
+ if (!body || typeof body !== 'object' || Array.isArray(body)) {
1238
+ throw new Error('the capabilities endpoint returned a non-object payload')
1239
+ }
1240
+ return Object.keys(body)
1241
+ .filter((key) => body[key] === true)
1242
+ .sort()
1243
+ }
1244
+
1245
+ // Persist the probed capability list on the project manifest. Absent means
1246
+ // "unknown" (the probe failed or never ran); an empty array means "probed, and
1247
+ // the backend advertises none". A shape-invalid manifest is left untouched.
1248
+ function recordCapabilities(target, capabilities) {
1249
+ const manifest = readManifest(target)
1250
+ if (!manifest) return false
1251
+ const validated = validateManifest(manifest)
1252
+ if (!validated.ok) return false
1253
+ if (Array.isArray(capabilities)) manifest.capabilities = capabilities
1254
+ else delete manifest.capabilities
1255
+ writeManifest(target, manifest)
1256
+ return true
1257
+ }
1258
+
1201
1259
  async function setup(args) {
1202
1260
  const target = args.dir
1203
1261
  const envPath = join(target, '.env.local')
@@ -1244,6 +1302,10 @@ async function setup(args) {
1244
1302
  // No publishable key: nothing to connect. Leave the store in mock mode and exit
1245
1303
  // successfully so `setup` is safe to run in CI/bootstrap without a key.
1246
1304
  if (!publishableKey) {
1305
+ // Mock mode advertises no backend capability: an empty probed list is the
1306
+ // truthful value, so a capability-gated feature stays uninstallable rather
1307
+ // than being assumed to work.
1308
+ recordCapabilities(target, [])
1247
1309
  console.log('storefront setup: no publishable key — leaving THOR_DATA_SOURCE=mock.')
1248
1310
  return 0
1249
1311
  }
@@ -1331,11 +1393,30 @@ async function setup(args) {
1331
1393
  const next = upsertEnv(readEnvFile(envPath), managed)
1332
1394
  await writeFile(envPath, next, 'utf8')
1333
1395
 
1396
+ // Record what the backend actually advertises. A failed probe leaves the
1397
+ // capabilities unknown (absent), so a feature that needs them is refused until
1398
+ // setup runs again — never silently installed on an assumption.
1399
+ let capabilities = null
1400
+ try {
1401
+ capabilities = await probeCapabilities(backendUrl, publishableKey)
1402
+ } catch (err) {
1403
+ console.warn(
1404
+ `storefront setup: could not read backend capabilities (${err instanceof Error ? err.message : String(err)}).`,
1405
+ )
1406
+ console.warn(' Capability-gated features stay uninstallable until a successful `storefront setup`.')
1407
+ }
1408
+ recordCapabilities(target, capabilities)
1409
+
1334
1410
  console.log('storefront setup — backend connected')
1335
1411
  console.log(` backend: ${backendUrl}`)
1336
1412
  console.log(` sales channel: ${salesChannelId}`)
1337
1413
  console.log(` region: ${regionId}`)
1338
1414
  console.log(` currency: ${currencyCode}`)
1415
+ if (capabilities) {
1416
+ console.log(` capabilities: ${capabilities.length === 0 ? 'none advertised' : capabilities.join(', ')}`)
1417
+ } else {
1418
+ console.log(' capabilities: unknown (probe failed)')
1419
+ }
1339
1420
  console.log('Wrote .env.local. Restart the dev server to pick it up.')
1340
1421
  return 0
1341
1422
  }
@@ -1457,6 +1538,51 @@ async function update(args) {
1457
1538
  return 0
1458
1539
  }
1459
1540
 
1541
+ // Re-check every installed feature's declared backend capabilities against the
1542
+ // live backend (or the recorded mock list). This is the install gate applied to
1543
+ // the installed set: a feature that was installable when setup ran is reported
1544
+ // as drift once the backend stops advertising it.
1545
+ async function auditFeatureCapabilities(target, manifest) {
1546
+ const gated = (manifest.features ?? [])
1547
+ .map((feature) => getFeature(feature.name))
1548
+ .filter((spec) => spec && (spec.backendCapabilities ?? []).length > 0)
1549
+ if (gated.length === 0) return { problems: 0, lines: [], probeError: null }
1550
+
1551
+ const env = readEnvFile(join(target, '.env.local'))
1552
+ const key = env.MEDUSA_PUBLISHABLE_KEY
1553
+ const url = (env.MEDUSA_BASE_URL ?? '').replace(/\/+$/, '')
1554
+ let live = null
1555
+ let probeError = null
1556
+ if (key && url) {
1557
+ try {
1558
+ live = await probeCapabilities(url, key)
1559
+ } catch (err) {
1560
+ probeError = err instanceof Error ? err.message : String(err)
1561
+ }
1562
+ } else if (Array.isArray(manifest.capabilities)) {
1563
+ // Mock mode (or a storefront with no env): the recorded list is the only
1564
+ // evidence, and an empty list is the truthful mock value.
1565
+ live = manifest.capabilities
1566
+ }
1567
+
1568
+ const liveManifest = { ...manifest }
1569
+ if (live) liveManifest.capabilities = live
1570
+ else delete liveManifest.capabilities
1571
+
1572
+ const lines = []
1573
+ for (const spec of gated) {
1574
+ for (const diagnostic of installGateDiagnostics(liveManifest, spec)) {
1575
+ if (
1576
+ diagnostic.code === 'E_CAPABILITY_UNKNOWN' ||
1577
+ diagnostic.code === 'E_CAPABILITY_UNMET'
1578
+ ) {
1579
+ lines.push(diagnostic.message)
1580
+ }
1581
+ }
1582
+ }
1583
+ return { problems: lines.length > 0 ? 1 : 0, lines, probeError }
1584
+ }
1585
+
1460
1586
  async function doctor(args) {
1461
1587
  const target = args.dir
1462
1588
  console.log(`@thorprovider/storefront doctor — ${target}`)
@@ -1504,6 +1630,48 @@ async function doctor(args) {
1504
1630
  for (const diag of sectionConfig.diagnostics) console.log(` ${diag.message}`)
1505
1631
  console.log(' status: supply the missing source configuration, then run "storefront sync"')
1506
1632
  }
1633
+
1634
+ const sectionData = await auditSectionSidecars({ dir: target, manifest })
1635
+ if (sectionData.diagnostics.length > 0) {
1636
+ problems += sectionData.diagnostics.length
1637
+ console.log(` section data: ${sectionData.diagnostics.length} sidecar diagnostic(s):`)
1638
+ for (const diag of sectionData.diagnostics) {
1639
+ console.log(` ${diag.file} (instance ${diag.instanceId}) at ${diag.path}: ${diag.code}: ${diag.message}`)
1640
+ }
1641
+ console.log(' status: correct the section sidecar data, then run "storefront doctor" again')
1642
+ }
1643
+
1644
+ // Installed features declare the backend capabilities they need. Re-probe so
1645
+ // a backend that stopped advertising one is reported as drift, not assumed.
1646
+ const featureCapabilities = await auditFeatureCapabilities(target, manifest)
1647
+ if (featureCapabilities.probeError) {
1648
+ problems++
1649
+ console.log(` capabilities: probe failed — ${featureCapabilities.probeError}`)
1650
+ console.log(' status: run "storefront setup" to re-probe the backend')
1651
+ }
1652
+ if (featureCapabilities.lines.length > 0) {
1653
+ problems++
1654
+ console.log(` feature capabilities: ${featureCapabilities.lines.length} installed feature(s) need attention:`)
1655
+ for (const line of featureCapabilities.lines) console.log(` ${line}`)
1656
+ console.log(' status: connect a backend that provides them, or remove the feature')
1657
+ }
1658
+ }
1659
+
1660
+ const hasPackageJson = existsSync(join(target, 'package.json'))
1661
+ const hasManagedStorefrontRecord = existsSync(join(target, '.opencode', VERSION_RECORD_FILE))
1662
+ if (!hasPackageJson && !hasManagedStorefrontRecord) {
1663
+ console.log(' agent blocks: skipped — pre-scaffold project (no package.json or managed suite record)')
1664
+ } else {
1665
+ const agentBlocks = await checkAgentBlocksWithValidatorStatus({}, target)
1666
+ if (agentBlocks.errors.length > 0) {
1667
+ problems += agentBlocks.errors.length
1668
+ console.log(` agent blocks: ${agentBlocks.errors.length} conformance error(s):`)
1669
+ for (const error of agentBlocks.errors) {
1670
+ console.log(` ${error.code} ${error.section} ${error.path}: ${error.message}`)
1671
+ }
1672
+ } else {
1673
+ console.log(` agent blocks: ${agentBlocks.summary.ready} ready, ${agentBlocks.summary.pending} pending, ${agentBlocks.summary.exempt} exempt — conformance checks passed`)
1674
+ }
1507
1675
  }
1508
1676
 
1509
1677
  const opencodeDir = join(target, '.opencode')
@@ -2235,8 +2403,27 @@ async function section(args) {
2235
2403
  const target = args.dir
2236
2404
  const sub = args.positionals[1]
2237
2405
  const view = args.positionals[2]
2406
+ if (sub === 'configure') {
2407
+ const configured = await configureSection({
2408
+ target,
2409
+ view,
2410
+ id: args.positionals[3],
2411
+ dataPath: args.data,
2412
+ dryRun: args.dryRun,
2413
+ readManifestOrError,
2414
+ })
2415
+ if (args.json) printEnvelope(configured.envelope)
2416
+ else if (configured.envelope.ok) console.log(configured.message)
2417
+ else {
2418
+ for (const item of configured.envelope.diagnostics) {
2419
+ const path = item.path ? ` at ${item.path}` : ''
2420
+ console.error(`${item.code}${path}: ${item.message}`)
2421
+ }
2422
+ }
2423
+ return configured.envelope.exitCode
2424
+ }
2238
2425
  if (sub !== 'add' && sub !== 'remove' && sub !== 'move') {
2239
- console.error('Usage: storefront section <add|remove|move> <view> [...]')
2426
+ console.error('Usage: storefront section <add|remove|move|configure> <view> [...]')
2240
2427
  return 1
2241
2428
  }
2242
2429
  if (!view) {
@@ -2320,13 +2507,26 @@ async function section(args) {
2320
2507
  }
2321
2508
  return rejectDiagnostics(result.diagnostics)
2322
2509
  }
2510
+ const preserved = [...(result.preserved ?? [])]
2511
+ if (sub === 'remove') {
2512
+ const id = args.positionals[3]
2513
+ const instance = manifest.views.find((entry) => entry.name === view)?.sections
2514
+ ?.find((entry) => entry && typeof entry === 'object' && entry.id === id)
2515
+ if (instance && typeof manifest.name === 'string') {
2516
+ const sidecar = join(target, 'lib', manifest.name, 'views', view, 'sections', `${id}.json`)
2517
+ if (existsSync(sidecar)) {
2518
+ const rel = relative(target, sidecar).replaceAll('\\', '/')
2519
+ if (!preserved.includes(rel)) preserved.push(rel)
2520
+ }
2521
+ }
2522
+ }
2323
2523
  if (args.json) {
2324
2524
  printEnvelope(
2325
2525
  resultEnvelope('section', true, 0, [], {
2326
2526
  action: sub,
2327
2527
  view,
2328
2528
  changed: result.changed,
2329
- preserved: result.preserved,
2529
+ preserved,
2330
2530
  }),
2331
2531
  )
2332
2532
  return 0
@@ -2336,7 +2536,7 @@ async function section(args) {
2336
2536
  console.log(`Added a "${args.positionals[3]}" section to view "${view}".`)
2337
2537
  } else if (sub === 'remove') {
2338
2538
  console.log(`Removed section "${args.positionals[3]}" from view "${view}".`)
2339
- for (const leftover of result.preserved) {
2539
+ for (const leftover of preserved) {
2340
2540
  console.log(`Preserved user-owned file: ${leftover} (remove it manually if no longer needed).`)
2341
2541
  }
2342
2542
  } else {
@@ -2397,6 +2597,105 @@ async function sections(args) {
2397
2597
  return 0
2398
2598
  }
2399
2599
 
2600
+ // Project the section agent-card registry through the current storefront. This
2601
+ // command is read-only; conformance checks execute installed validators only on
2602
+ // the registry's declared examples.
2603
+ async function blocks(args) {
2604
+ const subcommand = args.positionals[1]
2605
+ const fail = (code, message, extra = {}) => {
2606
+ if (args.json) {
2607
+ printEnvelope(resultEnvelope('blocks', false, 1, [envelopeDiagnostic(code, message, extra)]))
2608
+ } else {
2609
+ console.error(message)
2610
+ }
2611
+ return 1
2612
+ }
2613
+
2614
+ if (!['list', 'show', 'check'].includes(subcommand)) {
2615
+ return fail('E_INVALID_BLOCK_COMMAND', 'Usage: storefront blocks list|show <type>|check [--json]')
2616
+ }
2617
+
2618
+ let manifest = null
2619
+ if (subcommand !== 'check') {
2620
+ const read = readManifestOrError(args.dir)
2621
+ if (read.error) return fail('E_INVALID_COMPOSITION', read.error, { path: 'storefront.config.json' })
2622
+ manifest = read.manifest
2623
+ }
2624
+ const registry = loadAgentBlocks({ recipes: loadRecipes(), sections: loadSections(), manifest })
2625
+
2626
+ if (subcommand === 'list') {
2627
+ const projection = await listAgentBlocksWithValidatorStatus(registry, args.dir)
2628
+ const result = { blocks: projection.blocks, unavailable: projection.unavailable }
2629
+ if (args.json) {
2630
+ printEnvelope(resultEnvelope('blocks', true, 0, [], result))
2631
+ return 0
2632
+ }
2633
+ console.log(`Storefront agent blocks (${args.dir}):`)
2634
+ for (const block of result.blocks) {
2635
+ console.log(` ${block.section.padEnd(28)} ${block.label} (hosts: ${block.hosts.join(', ')}; validator: ${block.validator} — ${block.validatorStatus})`)
2636
+ }
2637
+ if (result.blocks.length === 0) console.log(' (no ready agent-configurable sections)')
2638
+ if (result.unavailable.length > 0) {
2639
+ console.log('Unavailable:')
2640
+ for (const entry of result.unavailable) {
2641
+ console.log(` ${entry.section.padEnd(28)} ${entry.status} — ${entry.reason} (owner: ${entry.owner})`)
2642
+ }
2643
+ }
2644
+ return 0
2645
+ }
2646
+
2647
+ if (subcommand === 'show') {
2648
+ const type = args.positionals[2]
2649
+ if (!type) return fail('E_INVALID_BLOCK_COMMAND', 'Usage: storefront blocks show <type> [--json]')
2650
+ const result = await showAgentBlockWithValidatorStatus(type, { ...registry, includeUnavailable: true }, args.dir)
2651
+ if (!result) return fail('E_BLOCK_NOT_FOUND', `Unknown agent block type "${type}".`)
2652
+ if (args.json) {
2653
+ printEnvelope(resultEnvelope('blocks', true, 0, [], result))
2654
+ return 0
2655
+ }
2656
+ if (result.status !== 'ready') {
2657
+ console.log(`${result.section}: ${result.status} (not selectable)`)
2658
+ if (result.reason) console.log(` ${result.reason}`)
2659
+ if (result.owner) console.log(` owner: ${result.owner}`)
2660
+ return 0
2661
+ }
2662
+ console.log(`${result.section} — ${result.label}`)
2663
+ console.log(` ${result.purpose}`)
2664
+ console.log(` hosts: ${result.hosts.join(', ')}`)
2665
+ console.log(` variants: ${result.variants.join(', ')}`)
2666
+ console.log(` validator: ${result.validator} (${result.validatorStatus})`)
2667
+ console.log(` installed instances: ${result.instances.map((instance) => `${instance.id} (${instance.view})`).join(', ') || '(none)'}`)
2668
+ return 0
2669
+ }
2670
+
2671
+ const result = await checkAgentBlocksWithValidatorStatus(registry, args.dir)
2672
+ const diagnostics = result.errors.map((error) => envelopeDiagnostic(
2673
+ error.code,
2674
+ error.message,
2675
+ { section: error.section, path: error.path },
2676
+ ))
2677
+ const exitCode = result.ok ? 0 : 1
2678
+ if (args.json) {
2679
+ printEnvelope(resultEnvelope('blocks', result.ok, exitCode, diagnostics, result))
2680
+ } else {
2681
+ console.log(`Agent block registry (${result.summary.ready} ready, ${result.summary.pending} pending, ${result.summary.exempt} exempt).`)
2682
+ for (const exemption of result.exemptions) {
2683
+ console.log(` exemption: ${exemption.section} (${exemption.status}/${exemption.kind}) — ${exemption.reason} (owner: ${exemption.owner})`)
2684
+ }
2685
+ if (result.ok) console.log(' conformance checks passed')
2686
+ else {
2687
+ console.error('Agent block registry conformance failed:')
2688
+ for (const error of result.errors) {
2689
+ console.error(` ${error.code} ${error.section} ${error.path}: ${error.message}`)
2690
+ }
2691
+ }
2692
+ for (const validator of result.validators) {
2693
+ console.log(` ${validator.section}: ${validator.validator} — ${validator.status}`)
2694
+ }
2695
+ }
2696
+ return exitCode
2697
+ }
2698
+
2400
2699
  // Build a diagnostic for the result/error envelope. `path`, when present, is a
2401
2700
  // project-root-relative POSIX file path; operation-field diagnostics use a
2402
2701
  // semantic locator instead (e.g. `operations[0].surprise`), never a filesystem
@@ -2436,6 +2735,14 @@ function inspect(args) {
2436
2735
  catalogVersion: CATALOG_VERSION,
2437
2736
  slots: catalog.slots ?? {},
2438
2737
  capabilities: catalog.capabilities ?? {},
2738
+ features: (loadFeatures().features ?? []).map((feature) => ({
2739
+ name: feature.name,
2740
+ status: featureStatus(feature.name),
2741
+ reason: feature.reason ?? null,
2742
+ owner: feature.owner ?? null,
2743
+ requires: feature.requires ?? [],
2744
+ backendCapabilities: feature.backendCapabilities ?? [],
2745
+ })),
2439
2746
  composition: {
2440
2747
  views: manifest?.views ?? [],
2441
2748
  features: manifest?.features ?? [],
@@ -2623,7 +2930,12 @@ async function features(args) {
2623
2930
  const entries = specs.map((spec) => ({
2624
2931
  name: spec.name,
2625
2932
  description: spec.description,
2933
+ status: featureStatus(spec.name),
2934
+ reason: spec.reason ?? null,
2935
+ owner: spec.owner ?? null,
2626
2936
  mvp: spec.mvp === true,
2937
+ requires: spec.requires ?? [],
2938
+ backendCapabilities: spec.backendCapabilities ?? [],
2627
2939
  installed: installed.has(spec.name),
2628
2940
  route: spec.route ?? null,
2629
2941
  views: spec.views ?? [],
@@ -2643,9 +2955,12 @@ async function features(args) {
2643
2955
 
2644
2956
  console.log(`Storefront features (${target}):`)
2645
2957
  for (const entry of entries) {
2646
- const status = entry.installed ? 'installed' : entry.mvp ? 'available' : 'held'
2958
+ const status = entry.installed ? 'installed' : entry.status
2647
2959
  const owned = entry.views.join(', ') || '—'
2648
2960
  console.log(` ${entry.name.padEnd(16)} ${status.padEnd(10)} ${owned}`)
2961
+ if (!entry.installed && entry.status === 'held') {
2962
+ console.log(` held: ${entry.reason ?? 'no reason declared'} (owner: ${entry.owner ?? 'unassigned'})`)
2963
+ }
2649
2964
  }
2650
2965
  return 0
2651
2966
  }
@@ -2757,6 +3072,21 @@ async function main() {
2757
3072
  if (!root) return 1
2758
3073
  return sections({ ...args, dir: root })
2759
3074
  }
3075
+ if (args.action === 'blocks') {
3076
+ const root = resolveProject({ quiet: args.json })
3077
+ if (!root) {
3078
+ if (args.json) {
3079
+ printEnvelope(resultEnvelope('blocks', false, 1, [
3080
+ envelopeDiagnostic(
3081
+ 'E_NO_MANIFEST',
3082
+ 'Not inside a storefront project (no storefront.config.json found in this directory or any parent).',
3083
+ ),
3084
+ ]))
3085
+ }
3086
+ return 1
3087
+ }
3088
+ return blocks({ ...args, dir: root })
3089
+ }
2760
3090
  if (args.action === 'inspect' || args.action === 'plan' || args.action === 'apply') {
2761
3091
  const root = resolveProject({ quiet: true })
2762
3092
  if (!root) {
@@ -2825,4 +3155,4 @@ main()
2825
3155
  ]),
2826
3156
  )
2827
3157
  process.exitCode = 2
2828
- })
3158
+ })
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@thorprovider/storefront",
3
- "version": "0.6.3",
3
+ "version": "0.9.0",
4
4
  "description": "Deterministic storefront scaffolder and installable OpenCode skill suite for Thor Commerce (Next.js, @thorprovider/blocks, @thorprovider/adapters, Medusa)",
5
5
  "type": "module",
6
6
  "bin": "bin/storefront.js",
@@ -48,6 +48,7 @@
48
48
  "semver": "^7.7.4"
49
49
  },
50
50
  "devDependencies": {
51
+ "typescript": "^5.0.0",
51
52
  "vitest": "^3.2.4"
52
53
  },
53
54
  "license": "MIT"
@@ -0,0 +1,158 @@
1
+ {
2
+ "version": "1.0.0",
3
+ "commerce": [
4
+ "addShippingMethod",
5
+ "addToCart",
6
+ "applyDiscountCode",
7
+ "cancelOrder",
8
+ "checkInventoryLevels",
9
+ "completeCheckout",
10
+ "createCart",
11
+ "createFulfillment",
12
+ "createRefund",
13
+ "getAdminOrders",
14
+ "getCart",
15
+ "getCategories",
16
+ "getCategory",
17
+ "getCategoryProducts",
18
+ "getCollection",
19
+ "getCollectionProducts",
20
+ "getCollections",
21
+ "getFulfillmentOptions",
22
+ "getPaymentMethods",
23
+ "getProduct",
24
+ "getProductRecommendations",
25
+ "getProducts",
26
+ "getRegionCountries",
27
+ "getShippingMethods",
28
+ "getStockLocations",
29
+ "getStorefrontContext",
30
+ "initiatePaymentSession",
31
+ "isStorefrontRequired",
32
+ "removeDiscountCode",
33
+ "removeFromCart",
34
+ "updateCart",
35
+ "validateCartStock"
36
+ ],
37
+ "auth": [
38
+ "createAddress",
39
+ "deleteAddress",
40
+ "deleteCustomerAccount",
41
+ "getAddresses",
42
+ "getAuthToken",
43
+ "getCurrentCustomer",
44
+ "isAuthenticated",
45
+ "login",
46
+ "logout",
47
+ "register",
48
+ "requestPasswordReset",
49
+ "resetPassword",
50
+ "updateAddress",
51
+ "updateCustomer"
52
+ ],
53
+ "runtime": [
54
+ "addCartLines",
55
+ "addShippingMethod",
56
+ "addToCart",
57
+ "applyCategoryQueryChange",
58
+ "applyCheckoutShippingGroups",
59
+ "applyManualTestPayment",
60
+ "applyPaymentMethod",
61
+ "applySavedAddress",
62
+ "assertCartMatchesContext",
63
+ "assignCartToCustomer",
64
+ "buildActiveFilterChips",
65
+ "buildCategoryQueryHref",
66
+ "buildCategoryRepairHref",
67
+ "buildPagination",
68
+ "catalogHistoryMode",
69
+ "catalogResultsCacheKey",
70
+ "checkoutShippingGroupId",
71
+ "clearFilterParams",
72
+ "completeCart",
73
+ "completeCheckout",
74
+ "createCart",
75
+ "createCartForContext",
76
+ "createCustomerAddress",
77
+ "deleteCustomerAddress",
78
+ "deriveDefaultFilterSet",
79
+ "getCart",
80
+ "getCartForContext",
81
+ "getCatalogResults",
82
+ "getCatalogSortKeys",
83
+ "getCategoryProductsByHandle",
84
+ "getCategoryProductsByHandleWithSource",
85
+ "getCheckoutCountries",
86
+ "getCheckoutShippingGroups",
87
+ "getCollectionOptions",
88
+ "getCommerceClient",
89
+ "getCommerceClientWithToken",
90
+ "getCurrentCustomer",
91
+ "getCustomerAddresses",
92
+ "getCustomerOrders",
93
+ "getCustomerOrdersPage",
94
+ "getDataSource",
95
+ "getEligibleShippingMethods",
96
+ "getGeoCities",
97
+ "getGeoProvinces",
98
+ "getMerchandiseByHandle",
99
+ "getMockCommerceClient",
100
+ "getPaymentMethods",
101
+ "getPaymentMethodsByRegion",
102
+ "getProductByHandle",
103
+ "getProductDetailByHandle",
104
+ "getProductDetailById",
105
+ "getRegionCountries",
106
+ "getShippingMethods",
107
+ "initiatePaymentSession",
108
+ "isCountryEligible",
109
+ "loadCategoryListing",
110
+ "loginCustomer",
111
+ "logoutCustomer",
112
+ "makeTokenStorage",
113
+ "mapCatalogOutcomeToStatus",
114
+ "mapCatalogResultsToCategoryListing",
115
+ "normalizePriceRange",
116
+ "prefillCheckoutFromCustomer",
117
+ "reconcileCart",
118
+ "registerCustomer",
119
+ "removeActiveFilter",
120
+ "removeCartLines",
121
+ "removeFromCart",
122
+ "resolveAbsoluteQuantity",
123
+ "resolveCategoryFacetSupport",
124
+ "resolveCategoryListingSupport",
125
+ "resolveVariantPrice",
126
+ "selectApprovedManualTestProvider",
127
+ "selectFirstPurchasableVariant",
128
+ "selectShippingMethod",
129
+ "selectVariant",
130
+ "toAbsoluteLineUpdate",
131
+ "toCardProduct",
132
+ "toCartItem",
133
+ "toCartItems",
134
+ "toCatalogProductDetail",
135
+ "toCatalogVariant",
136
+ "toCategoryTree",
137
+ "toCheckoutShippingGroups",
138
+ "toCommerceError",
139
+ "toCompletionError",
140
+ "toListingProduct",
141
+ "toStoreCategory",
142
+ "updateBillingAddress",
143
+ "updateCart",
144
+ "updateCartLines",
145
+ "updateCustomer",
146
+ "updateCustomerAddress",
147
+ "updateShippingAddress",
148
+ "validateCheckoutAddress",
149
+ "validateCheckoutAddressForRegion",
150
+ "validateCustomerAddressForRegion",
151
+ "withCommerceProvider"
152
+ ],
153
+ "generatedFrom": [
154
+ "packages/types/src/commerce-provider.ts",
155
+ "packages/types/src/auth.ts",
156
+ "packages/runtime/src/commerce"
157
+ ]
158
+ }