@thorprovider/storefront 0.7.0 → 0.10.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 (164) 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 +677 -80
  9. package/assets/templates/app/lib/__STOREFRONT__/addresses-port.ts +107 -0
  10. package/assets/templates/app/lib/__STOREFRONT__/commerce.ts +477 -38
  11. package/assets/templates/app/lib/__STOREFRONT__/confirmation.core.ts +240 -0
  12. package/assets/templates/app/lib/__STOREFRONT__/customer-profile-port.ts +103 -0
  13. package/assets/templates/app/lib/__STOREFRONT__/fulfillment-evidence-port.ts +31 -0
  14. package/assets/templates/app/lib/__STOREFRONT__/handlers.core.ts +21 -4
  15. package/assets/templates/app/lib/__STOREFRONT__/mappers.ts +6 -2
  16. package/assets/templates/app/lib/__STOREFRONT__/order-detail-mapper.ts +642 -0
  17. package/assets/templates/app/lib/__STOREFRONT__/order-detail-port.ts +25 -0
  18. package/assets/templates/app/lib/__STOREFRONT__/orders-port.ts +30 -0
  19. package/assets/templates/app/lib/__STOREFRONT__/ports.ts +28 -0
  20. package/assets/templates/app/lib/__STOREFRONT__/projection-ownership.client.tsx +4 -4
  21. package/assets/templates/app/lib/__STOREFRONT__/session.ts +24 -6
  22. package/assets/templates/app/lib/__STOREFRONT__/state.core.ts +21 -0
  23. package/assets/templates/app/lib/__STOREFRONT__/views/sections/address-book-advanced.client.tsx +29 -0
  24. package/assets/templates/app/lib/__STOREFRONT__/views/sections/checkout-commerce-v1.client.tsx +19 -0
  25. package/assets/templates/app/lib/__STOREFRONT__/views/sections/checkout-commerce-v1.tsx +16 -0
  26. package/assets/templates/app/lib/__STOREFRONT__/views/sections/customer-profile.client.tsx +27 -0
  27. package/assets/templates/app/lib/__STOREFRONT__/views/sections/index.ts +4 -1
  28. package/assets/templates/app/lib/__STOREFRONT__/views/sections/mega-menu-universal.client.tsx +19 -0
  29. package/assets/templates/app/lib/__STOREFRONT__/views/sections/mega-menu-universal.tsx +16 -0
  30. package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.address-book-advanced.ts +437 -0
  31. package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.checkout-commerce-v1.ts +398 -0
  32. package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.customer-profile.ts +138 -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 +24 -4
  38. package/assets/templates/features/customer-addresses/handlers.ts +11 -0
  39. package/assets/templates/features/customer-addresses/state.ts +33 -0
  40. package/assets/templates/features/customer-auth/state.ts +10 -0
  41. package/assets/templates/features/customer-profile/handlers.ts +11 -0
  42. package/assets/templates/features/customer-profile/state.ts +18 -0
  43. package/assets/templates/views/account/address-book-advanced.defaults.ts +534 -0
  44. package/assets/templates/views/account/assembly/assembly.json +36 -0
  45. package/assets/templates/views/account/assembly/index.skeleton.tsx +277 -0
  46. package/assets/templates/views/account/assembly/registry.skeleton.tsx +1057 -0
  47. package/assets/templates/views/account/assembly/slots/addresses/AddressBookAdvanced/binding.json +5 -0
  48. package/assets/templates/views/account/assembly/slots/addresses/AddressBookAdvanced/catalog.part +4 -0
  49. package/assets/templates/views/account/assembly/slots/addresses/AddressBookAdvanced/element.part +5 -0
  50. package/assets/templates/views/account/assembly/slots/addresses/AddressBookAdvanced/registry.part +1 -0
  51. package/assets/templates/views/account/assembly/slots/addresses/cards/catalog.part +5 -0
  52. package/assets/templates/views/account/assembly/slots/addresses/cards/element.part +10 -0
  53. package/assets/templates/views/account/assembly/slots/addresses/cards/registry.part +1 -0
  54. package/assets/templates/views/account/assembly/slots/login/card/catalog.part +4 -0
  55. package/assets/templates/views/account/assembly/slots/login/card/element.part +13 -0
  56. package/assets/templates/views/account/assembly/slots/login/card/registry.part +1 -0
  57. package/assets/templates/views/account/assembly/slots/orders/OrderHistory/catalog.part +5 -0
  58. package/assets/templates/views/account/assembly/slots/orders/OrderHistory/element.part +5 -0
  59. package/assets/templates/views/account/assembly/slots/orders/OrderHistory/registry.part +2 -0
  60. package/assets/templates/views/account/assembly/slots/orders/OrderHistoryAdvanced/binding.json +5 -0
  61. package/assets/templates/views/account/assembly/slots/orders/OrderHistoryAdvanced/catalog.part +5 -0
  62. package/assets/templates/views/account/assembly/slots/orders/OrderHistoryAdvanced/element.part +5 -0
  63. package/assets/templates/views/account/assembly/slots/orders/OrderHistoryAdvanced/registry.part +1 -0
  64. package/assets/templates/views/account/assembly/slots/profile/CustomerProfileAdvanced/binding.json +5 -0
  65. package/assets/templates/views/account/assembly/slots/profile/CustomerProfileAdvanced/catalog.part +4 -0
  66. package/assets/templates/views/account/assembly/slots/profile/CustomerProfileAdvanced/element.part +5 -0
  67. package/assets/templates/views/account/assembly/slots/profile/CustomerProfileAdvanced/registry.part +1 -0
  68. package/assets/templates/views/account/assembly/slots/profile/form/catalog.part +5 -0
  69. package/assets/templates/views/account/assembly/slots/profile/form/element.part +10 -0
  70. package/assets/templates/views/account/assembly/slots/profile/form/registry.part +1 -0
  71. package/assets/templates/views/account/assembly/slots/register/SignUpPage1/catalog.part +4 -0
  72. package/assets/templates/views/account/assembly/slots/register/SignUpPage1/element.part +13 -0
  73. package/assets/templates/views/account/assembly/slots/register/SignUpPage1/registry.part +1 -0
  74. package/assets/templates/views/account/assembly/slots/summary/stack/catalog.part +5 -0
  75. package/assets/templates/views/account/assembly/slots/summary/stack/element.part +5 -0
  76. package/assets/templates/views/account/assembly/slots/summary/stack/registry.part +1 -0
  77. package/assets/templates/views/account/assembly/slots/summary/tabs/catalog.part +5 -0
  78. package/assets/templates/views/account/assembly/slots/summary/tabs/element.part +5 -0
  79. package/assets/templates/views/account/assembly/slots/summary/tabs/registry.part +1 -0
  80. package/assets/templates/views/account/content.ts +326 -0
  81. package/assets/templates/views/account/customer-profile.defaults.ts +136 -0
  82. package/assets/templates/views/account/fulfillment-evidence.client.tsx +34 -0
  83. package/assets/templates/views/account/fulfillment-evidence.defaults.ts +145 -0
  84. package/assets/templates/views/account/fulfillment-evidence.schema.ts +15 -0
  85. package/assets/templates/views/account/index.tsx +259 -38
  86. package/assets/templates/views/account/order-detail.client.tsx +35 -0
  87. package/assets/templates/views/account/order-detail.defaults.ts +457 -0
  88. package/assets/templates/views/account/orders-advanced.client.tsx +77 -0
  89. package/assets/templates/views/account/orders-advanced.defaults.ts +230 -0
  90. package/assets/templates/views/account/registry.tsx +935 -420
  91. package/assets/templates/views/account/schema.ts +50 -0
  92. package/assets/templates/views/account/sections-data.ts +2 -0
  93. package/assets/templates/views/cart/content.ts +1 -0
  94. package/assets/templates/views/category/assembly/index.skeleton.tsx +1 -0
  95. package/assets/templates/views/category/assembly/slots/filter/CategoryListing/element.part +1 -0
  96. package/assets/templates/views/category/content.ts +2 -0
  97. package/assets/templates/views/category/index.tsx +2 -0
  98. package/assets/templates/views/category/sections-data.ts +2 -0
  99. package/assets/templates/views/checkout/checkout-commerce-hosted.tsx +1089 -0
  100. package/assets/templates/views/checkout/content.ts +51 -0
  101. package/assets/templates/views/checkout/index.tsx +1 -1
  102. package/assets/templates/views/checkout/props.ts +10 -2
  103. package/assets/templates/views/checkout/registry.tsx +104 -42
  104. package/assets/templates/views/checkout/schema.ts +76 -1
  105. package/assets/templates/views/home/assembly/assembly.json +23 -2
  106. package/assets/templates/views/home/assembly/index.skeleton.tsx +4 -1
  107. package/assets/templates/views/home/assembly/registry.skeleton.tsx +1 -0
  108. package/assets/templates/views/home/assembly/slots/hero/UniversalBanner/binding.json +5 -0
  109. package/assets/templates/views/home/assembly/slots/hero/UniversalBanner/catalog.part +4 -0
  110. package/assets/templates/views/home/assembly/slots/hero/UniversalBanner/element.part +4 -0
  111. package/assets/templates/views/home/assembly/slots/hero/UniversalBanner/registry.part +10 -0
  112. package/assets/templates/views/home/content.ts +247 -1
  113. package/assets/templates/views/home/data.ts +10 -1
  114. package/assets/templates/views/home/index.tsx +8 -6
  115. package/assets/templates/views/home/props.ts +7 -1
  116. package/assets/templates/views/home/registry.tsx +11 -28
  117. package/assets/templates/views/home/schema.ts +163 -0
  118. package/assets/templates/views/home/sections-data.ts +2 -0
  119. package/assets/templates/views/product/content.ts +1 -0
  120. package/assets/templates/views/static/content.ts +1 -0
  121. package/bin/storefront.js +356 -27
  122. package/package.json +2 -1
  123. package/recipes/adapter-surface.json +159 -0
  124. package/recipes/archetypes.json +43 -4
  125. package/recipes/catalog.json +147 -2
  126. package/recipes/feature.schema.json +9 -0
  127. package/recipes/features.json +72 -1
  128. package/recipes/manifest.schema.json +5 -0
  129. package/recipes/recipe.schema.json +13 -1
  130. package/recipes/recipes.json +37 -7
  131. package/recipes/section.schema.json +112 -0
  132. package/recipes/sections.json +281 -4
  133. package/recipes/validate.mjs +83 -1
  134. package/scripts/adapter-surface.mjs +41 -0
  135. package/scripts/agent-blocks.mjs +700 -0
  136. package/scripts/block-validator.mjs +45 -0
  137. package/scripts/candidate.mjs +56 -14
  138. package/scripts/composers.mjs +7 -2
  139. package/scripts/default-sections.mjs +78 -0
  140. package/scripts/file-classes.mjs +18 -0
  141. package/scripts/generate-adapter-surface.mjs +148 -0
  142. package/scripts/operations.mjs +100 -0
  143. package/scripts/reconcile.mjs +67 -39
  144. package/scripts/section-configure.mjs +316 -0
  145. package/scripts/sync-assets.mjs +1 -0
  146. package/scripts/view-assembly.mjs +101 -14
  147. package/skills/sf-feature/SKILL.md +19 -0
  148. package/skills/sf-view-gen/SKILL.md +73 -7
  149. package/skills/sf-view-gen/assets/recipes/archetypes.json +43 -4
  150. package/skills/sf-view-gen/assets/recipes/catalog.json +147 -2
  151. package/skills/sf-view-gen/assets/recipes/features.json +72 -1
  152. package/skills/sf-view-gen/assets/recipes/recipes.json +37 -7
  153. package/skills/sf-view-gen/assets/recipes/section.schema.json +112 -0
  154. package/skills/sf-view-gen/assets/recipes/sections.json +281 -4
  155. package/skills/sf-view-gen/assets/templates/views/sections/checkout-commerce-v1.client.tsx +19 -0
  156. package/skills/sf-view-gen/assets/templates/views/sections/checkout-commerce-v1.tsx +16 -0
  157. package/skills/sf-view-gen/assets/templates/views/sections/mega-menu-universal.client.tsx +19 -0
  158. package/skills/sf-view-gen/assets/templates/views/sections/mega-menu-universal.tsx +16 -0
  159. package/skills/sf-view-gen/assets/templates/views/sections/schema.checkout-commerce-v1.ts +398 -0
  160. package/skills/sf-view-gen/assets/templates/views/sections/schema.mega-menu-universal.ts +76 -0
  161. package/skills/sf-view-gen/assets/templates/views/sections/schema.universal-banner.ts +217 -0
  162. package/skills/sf-view-gen/assets/templates/views/sections/universal-banner.client.tsx +24 -0
  163. package/skills/sf-view-gen/assets/templates/views/sections/universal-banner.tsx +16 -0
  164. package/skills/sf-view-gen/scripts/validate.mjs +83 -1
package/bin/storefront.js CHANGED
@@ -61,7 +61,6 @@ import {
61
61
  findPack,
62
62
  parseRuntimeCommerceImports,
63
63
  verifyPackExports,
64
- verifyPackManifest,
65
64
  verifyRegistryToolset,
66
65
  } from '../scripts/candidate.mjs'
67
66
  import {
@@ -84,6 +83,8 @@ import {
84
83
  loadArchetypes,
85
84
  loadFeatures,
86
85
  isCuratedView,
86
+ featureStatus,
87
+ getFeature,
87
88
  featureSurfaces,
88
89
  allowedVariantsForView,
89
90
  supportedVariantsForView,
@@ -91,9 +92,10 @@ import {
91
92
  viewCatalog,
92
93
  sectionRegistry,
93
94
  sectionIsDataBound,
95
+ loadSections,
94
96
  } from '../recipes/validate.mjs'
95
97
  import { CATALOG_VERSION, loadCatalog } from '../recipes/catalog.mjs'
96
- import { OPERATION_NAMES } from '../scripts/operations.mjs'
98
+ import { OPERATION_NAMES, installGateDiagnostics } from '../scripts/operations.mjs'
97
99
  import {
98
100
  applyProject,
99
101
  executeOperations,
@@ -103,8 +105,17 @@ import {
103
105
  resultEnvelope,
104
106
  } from '../scripts/plan-apply.mjs'
105
107
  import { SECTION_OPERATION_REGISTRY } from '../scripts/section-operations.mjs'
108
+ import { seedDefaultSections } from '../scripts/default-sections.mjs'
106
109
  import { auditSectionConfig, collectDataBoundInstances } from '../scripts/section-config.mjs'
107
110
  import { normalizeViewSectionsForView } from '../scripts/section-compat.mjs'
111
+ import {
112
+ checkAgentBlocksWithValidatorStatus,
113
+ listAgentBlocksWithValidatorStatus,
114
+ loadAgentBlocks,
115
+ showAgentBlockWithValidatorStatus,
116
+ auditSectionSidecars,
117
+ } from '../scripts/agent-blocks.mjs'
118
+ import { configureSection } from '../scripts/section-configure.mjs'
108
119
 
109
120
  const __dirname = dirname(fileURLToPath(import.meta.url))
110
121
  const PKG_ROOT = resolve(__dirname, '..')
@@ -155,7 +166,11 @@ Usage:
155
166
  storefront view add|remove <name> Add or remove a view (reconciles derived files)
156
167
  storefront feature add|remove <name> Add or remove a feature (installs its views)
157
168
  storefront section add|remove|move <view> ... Add, remove, or move a section instance
169
+ storefront section configure <view> <id> --data <file|-> [options] Validate and configure section content
158
170
  storefront sections [<view>] [--json] List installed views' section instances (read-only)
171
+ storefront blocks list [--json] List agent-configurable sections for installed views
172
+ storefront blocks show <type> [--json] Show an agent section contract and installed instances
173
+ storefront blocks check [--json] Validate the section agent-card registry
159
174
  storefront inspect [--json] Report the versioned catalog and composition (read-only)
160
175
  storefront plan --operations <file> [--out <file>] [--json]
161
176
  Validate a whole intended state and emit a plan
@@ -232,6 +247,9 @@ section options:
232
247
  --first | --last place at the start or end of the composition
233
248
  --at <n> place at a 0-based index (escape hatch)
234
249
  -f, --force allow the write when ownership conflicts are detected
250
+ --data <file|-> configure section data from a JSON file or stdin
251
+ --dry-run validate and describe the sidecar without writing
252
+ --json emit the shared result envelope
235
253
 
236
254
  sections options:
237
255
  --json print the installed views' section instances as JSON
@@ -264,6 +282,7 @@ function parseArgs(argv) {
264
282
  config: null,
265
283
  operations: null,
266
284
  out: null,
285
+ data: null,
267
286
  plan: null,
268
287
  id: null,
269
288
  as: null,
@@ -332,6 +351,11 @@ function parseArgs(argv) {
332
351
  out.exportPath = argv[++i]
333
352
  } else if (arg === '--dry-run') {
334
353
  out.dryRun = true
354
+ } else if (arg === '--data') {
355
+ const value = argv[i + 1]
356
+ if (value !== undefined && (!value.startsWith('-') || value === '-')) {
357
+ out.data = argv[++i]
358
+ }
335
359
  } else if (arg === '--packs') {
336
360
  out.packs = argv[++i]
337
361
  } else if (arg === '--operations') {
@@ -932,32 +956,32 @@ async function create(args) {
932
956
  if (plan.missingPacks.length > 0) {
933
957
  console.error(`Refusing to create: missing packed local candidate(s) in ${resolve(args.packs)}:`)
934
958
  for (const name of plan.missingPacks) console.error(` ${name}`)
935
- console.error('Pack each @thorprovider/* package with `yarn pack --filename <slug>-<version>.tgz`.')
959
+ console.error('Pack each @thorprovider/* package with `yarn pack --filename <slug>-<version>.tgz`,')
960
+ console.error('or let `consumer:create --pack-path <dir>` build and pack the current workspaces.')
936
961
  return 1
937
962
  }
938
963
 
939
964
  // Integrity guard for the local candidate packs. A `--packs` directory can be
940
965
  // stale: a tarball packed before a public export was added still resolves for
941
966
  // the same exact version, so the generated project imports a symbol the
942
- // packed dist does not export. Verify each pack declares the expected
943
- // name+version (Tier 1) and that the packed runtime actually exports every
944
- // value the generated host imports from `@thorprovider/runtime/commerce`
945
- // (Tier 2) before the first write.
967
+ // packed dist does not export. The planner already verified each pack's
968
+ // manifest (readable, expected package name, declared version, and for the
969
+ // CLI pack the running CLI version) and adopted its versions; here the
970
+ // remaining Tier-2 check verifies that the packed runtime actually exports
971
+ // every value the generated host imports from `@thorprovider/runtime/commerce`
972
+ // before the first write.
946
973
  if (args.packs) {
947
974
  const packsDir = resolve(args.packs)
948
- const localPacks = { ...CANDIDATE_TOOLSET.local, '@thorprovider/storefront': cliVersion }
949
- for (const [name, version] of Object.entries(localPacks)) {
950
- const guard = verifyPackManifest({ tgzPath: findPack(packsDir, name, version), name, version })
951
- if (!guard.ok) {
952
- console.error(`Refusing to create: ${guard.message} (${guard.code})`)
953
- return 1
954
- }
975
+ if (plan.invalidPacks.length > 0) {
976
+ console.error(`Refusing to create: invalid packed local candidate(s) in ${packsDir}:`)
977
+ for (const pack of plan.invalidPacks) console.error(` ${pack.name}: ${pack.message} (${pack.code})`)
978
+ return 1
955
979
  }
956
980
  const commerceTemplate = join(PKG_ROOT, 'assets', 'templates', 'app', 'lib', '__STOREFRONT__', 'commerce.ts')
957
981
  const requiredExports = parseRuntimeCommerceImports(readFileSync(commerceTemplate, 'utf8'))
958
982
  const runtimeName = '@thorprovider/runtime'
959
983
  const runtimeGuard = verifyPackExports({
960
- tgzPath: findPack(packsDir, runtimeName, CANDIDATE_TOOLSET.local[runtimeName]),
984
+ tgzPath: findPack(packsDir, runtimeName, plan.dependencies[runtimeName]),
961
985
  innerPath: 'package/dist/commerce/index.mjs',
962
986
  requiredExports,
963
987
  })
@@ -976,13 +1000,15 @@ async function create(args) {
976
1000
  // mkdir, external scaffold, or write so rejected input leaves no trace.
977
1001
  const starter = args.starter === true
978
1002
  const composition = scaffoldComposition({ starter })
979
- const manifest = createManifest({
980
- name,
981
- siteName,
982
- mode,
983
- views: composition.views,
984
- features: composition.features,
985
- })
1003
+ const manifest = seedDefaultSections(
1004
+ createManifest({
1005
+ name,
1006
+ siteName,
1007
+ mode,
1008
+ views: composition.views,
1009
+ features: composition.features,
1010
+ }),
1011
+ )
986
1012
  const preflight = preflightManifest(manifest)
987
1013
  if (!preflight.ok) return rejectComposition(preflight.errors)
988
1014
 
@@ -1198,6 +1224,37 @@ async function create(args) {
1198
1224
  // writes the real-mode environment. The developer supplies the publishable key, the
1199
1225
  // sales channel id (from the Medusa admin), and the region; `setup` derives only the
1200
1226
  // region's currency by reading the store API with the key.
1227
+ // Read the backend's advertised capabilities (`GET /store/thor/capabilities`)
1228
+ // and return the enabled flags as a sorted list. A failure is the caller's to
1229
+ // classify: setup records "unknown" rather than assuming support.
1230
+ async function probeCapabilities(backendUrl, publishableKey) {
1231
+ const res = await fetch(`${backendUrl}/store/thor/capabilities`, {
1232
+ headers: { 'x-publishable-api-key': publishableKey },
1233
+ })
1234
+ if (!res.ok) throw new Error(`GET ${backendUrl}/store/thor/capabilities failed (${res.status})`)
1235
+ const body = await res.json()
1236
+ if (!body || typeof body !== 'object' || Array.isArray(body)) {
1237
+ throw new Error('the capabilities endpoint returned a non-object payload')
1238
+ }
1239
+ return Object.keys(body)
1240
+ .filter((key) => body[key] === true)
1241
+ .sort()
1242
+ }
1243
+
1244
+ // Persist the probed capability list on the project manifest. Absent means
1245
+ // "unknown" (the probe failed or never ran); an empty array means "probed, and
1246
+ // the backend advertises none". A shape-invalid manifest is left untouched.
1247
+ function recordCapabilities(target, capabilities) {
1248
+ const manifest = readManifest(target)
1249
+ if (!manifest) return false
1250
+ const validated = validateManifest(manifest)
1251
+ if (!validated.ok) return false
1252
+ if (Array.isArray(capabilities)) manifest.capabilities = capabilities
1253
+ else delete manifest.capabilities
1254
+ writeManifest(target, manifest)
1255
+ return true
1256
+ }
1257
+
1201
1258
  async function setup(args) {
1202
1259
  const target = args.dir
1203
1260
  const envPath = join(target, '.env.local')
@@ -1244,6 +1301,10 @@ async function setup(args) {
1244
1301
  // No publishable key: nothing to connect. Leave the store in mock mode and exit
1245
1302
  // successfully so `setup` is safe to run in CI/bootstrap without a key.
1246
1303
  if (!publishableKey) {
1304
+ // Mock mode advertises no backend capability: an empty probed list is the
1305
+ // truthful value, so a capability-gated feature stays uninstallable rather
1306
+ // than being assumed to work.
1307
+ recordCapabilities(target, [])
1247
1308
  console.log('storefront setup: no publishable key — leaving THOR_DATA_SOURCE=mock.')
1248
1309
  return 0
1249
1310
  }
@@ -1331,11 +1392,30 @@ async function setup(args) {
1331
1392
  const next = upsertEnv(readEnvFile(envPath), managed)
1332
1393
  await writeFile(envPath, next, 'utf8')
1333
1394
 
1395
+ // Record what the backend actually advertises. A failed probe leaves the
1396
+ // capabilities unknown (absent), so a feature that needs them is refused until
1397
+ // setup runs again — never silently installed on an assumption.
1398
+ let capabilities = null
1399
+ try {
1400
+ capabilities = await probeCapabilities(backendUrl, publishableKey)
1401
+ } catch (err) {
1402
+ console.warn(
1403
+ `storefront setup: could not read backend capabilities (${err instanceof Error ? err.message : String(err)}).`,
1404
+ )
1405
+ console.warn(' Capability-gated features stay uninstallable until a successful `storefront setup`.')
1406
+ }
1407
+ recordCapabilities(target, capabilities)
1408
+
1334
1409
  console.log('storefront setup — backend connected')
1335
1410
  console.log(` backend: ${backendUrl}`)
1336
1411
  console.log(` sales channel: ${salesChannelId}`)
1337
1412
  console.log(` region: ${regionId}`)
1338
1413
  console.log(` currency: ${currencyCode}`)
1414
+ if (capabilities) {
1415
+ console.log(` capabilities: ${capabilities.length === 0 ? 'none advertised' : capabilities.join(', ')}`)
1416
+ } else {
1417
+ console.log(' capabilities: unknown (probe failed)')
1418
+ }
1339
1419
  console.log('Wrote .env.local. Restart the dev server to pick it up.')
1340
1420
  return 0
1341
1421
  }
@@ -1457,6 +1537,51 @@ async function update(args) {
1457
1537
  return 0
1458
1538
  }
1459
1539
 
1540
+ // Re-check every installed feature's declared backend capabilities against the
1541
+ // live backend (or the recorded mock list). This is the install gate applied to
1542
+ // the installed set: a feature that was installable when setup ran is reported
1543
+ // as drift once the backend stops advertising it.
1544
+ async function auditFeatureCapabilities(target, manifest) {
1545
+ const gated = (manifest.features ?? [])
1546
+ .map((feature) => getFeature(feature.name))
1547
+ .filter((spec) => spec && (spec.backendCapabilities ?? []).length > 0)
1548
+ if (gated.length === 0) return { problems: 0, lines: [], probeError: null }
1549
+
1550
+ const env = readEnvFile(join(target, '.env.local'))
1551
+ const key = env.MEDUSA_PUBLISHABLE_KEY
1552
+ const url = (env.MEDUSA_BASE_URL ?? '').replace(/\/+$/, '')
1553
+ let live = null
1554
+ let probeError = null
1555
+ if (key && url) {
1556
+ try {
1557
+ live = await probeCapabilities(url, key)
1558
+ } catch (err) {
1559
+ probeError = err instanceof Error ? err.message : String(err)
1560
+ }
1561
+ } else if (Array.isArray(manifest.capabilities)) {
1562
+ // Mock mode (or a storefront with no env): the recorded list is the only
1563
+ // evidence, and an empty list is the truthful mock value.
1564
+ live = manifest.capabilities
1565
+ }
1566
+
1567
+ const liveManifest = { ...manifest }
1568
+ if (live) liveManifest.capabilities = live
1569
+ else delete liveManifest.capabilities
1570
+
1571
+ const lines = []
1572
+ for (const spec of gated) {
1573
+ for (const diagnostic of installGateDiagnostics(liveManifest, spec)) {
1574
+ if (
1575
+ diagnostic.code === 'E_CAPABILITY_UNKNOWN' ||
1576
+ diagnostic.code === 'E_CAPABILITY_UNMET'
1577
+ ) {
1578
+ lines.push(diagnostic.message)
1579
+ }
1580
+ }
1581
+ }
1582
+ return { problems: lines.length > 0 ? 1 : 0, lines, probeError }
1583
+ }
1584
+
1460
1585
  async function doctor(args) {
1461
1586
  const target = args.dir
1462
1587
  console.log(`@thorprovider/storefront doctor — ${target}`)
@@ -1504,6 +1629,48 @@ async function doctor(args) {
1504
1629
  for (const diag of sectionConfig.diagnostics) console.log(` ${diag.message}`)
1505
1630
  console.log(' status: supply the missing source configuration, then run "storefront sync"')
1506
1631
  }
1632
+
1633
+ const sectionData = await auditSectionSidecars({ dir: target, manifest })
1634
+ if (sectionData.diagnostics.length > 0) {
1635
+ problems += sectionData.diagnostics.length
1636
+ console.log(` section data: ${sectionData.diagnostics.length} sidecar diagnostic(s):`)
1637
+ for (const diag of sectionData.diagnostics) {
1638
+ console.log(` ${diag.file} (instance ${diag.instanceId}) at ${diag.path}: ${diag.code}: ${diag.message}`)
1639
+ }
1640
+ console.log(' status: correct the section sidecar data, then run "storefront doctor" again')
1641
+ }
1642
+
1643
+ // Installed features declare the backend capabilities they need. Re-probe so
1644
+ // a backend that stopped advertising one is reported as drift, not assumed.
1645
+ const featureCapabilities = await auditFeatureCapabilities(target, manifest)
1646
+ if (featureCapabilities.probeError) {
1647
+ problems++
1648
+ console.log(` capabilities: probe failed — ${featureCapabilities.probeError}`)
1649
+ console.log(' status: run "storefront setup" to re-probe the backend')
1650
+ }
1651
+ if (featureCapabilities.lines.length > 0) {
1652
+ problems++
1653
+ console.log(` feature capabilities: ${featureCapabilities.lines.length} installed feature(s) need attention:`)
1654
+ for (const line of featureCapabilities.lines) console.log(` ${line}`)
1655
+ console.log(' status: connect a backend that provides them, or remove the feature')
1656
+ }
1657
+ }
1658
+
1659
+ const hasPackageJson = existsSync(join(target, 'package.json'))
1660
+ const hasManagedStorefrontRecord = existsSync(join(target, '.opencode', VERSION_RECORD_FILE))
1661
+ if (!hasPackageJson && !hasManagedStorefrontRecord) {
1662
+ console.log(' agent blocks: skipped — pre-scaffold project (no package.json or managed suite record)')
1663
+ } else {
1664
+ const agentBlocks = await checkAgentBlocksWithValidatorStatus({}, target)
1665
+ if (agentBlocks.errors.length > 0) {
1666
+ problems += agentBlocks.errors.length
1667
+ console.log(` agent blocks: ${agentBlocks.errors.length} conformance error(s):`)
1668
+ for (const error of agentBlocks.errors) {
1669
+ console.log(` ${error.code} ${error.section} ${error.path}: ${error.message}`)
1670
+ }
1671
+ } else {
1672
+ console.log(` agent blocks: ${agentBlocks.summary.ready} ready, ${agentBlocks.summary.pending} pending, ${agentBlocks.summary.exempt} exempt — conformance checks passed`)
1673
+ }
1507
1674
  }
1508
1675
 
1509
1676
  const opencodeDir = join(target, '.opencode')
@@ -2235,8 +2402,27 @@ async function section(args) {
2235
2402
  const target = args.dir
2236
2403
  const sub = args.positionals[1]
2237
2404
  const view = args.positionals[2]
2405
+ if (sub === 'configure') {
2406
+ const configured = await configureSection({
2407
+ target,
2408
+ view,
2409
+ id: args.positionals[3],
2410
+ dataPath: args.data,
2411
+ dryRun: args.dryRun,
2412
+ readManifestOrError,
2413
+ })
2414
+ if (args.json) printEnvelope(configured.envelope)
2415
+ else if (configured.envelope.ok) console.log(configured.message)
2416
+ else {
2417
+ for (const item of configured.envelope.diagnostics) {
2418
+ const path = item.path ? ` at ${item.path}` : ''
2419
+ console.error(`${item.code}${path}: ${item.message}`)
2420
+ }
2421
+ }
2422
+ return configured.envelope.exitCode
2423
+ }
2238
2424
  if (sub !== 'add' && sub !== 'remove' && sub !== 'move') {
2239
- console.error('Usage: storefront section <add|remove|move> <view> [...]')
2425
+ console.error('Usage: storefront section <add|remove|move|configure> <view> [...]')
2240
2426
  return 1
2241
2427
  }
2242
2428
  if (!view) {
@@ -2320,13 +2506,26 @@ async function section(args) {
2320
2506
  }
2321
2507
  return rejectDiagnostics(result.diagnostics)
2322
2508
  }
2509
+ const preserved = [...(result.preserved ?? [])]
2510
+ if (sub === 'remove') {
2511
+ const id = args.positionals[3]
2512
+ const instance = manifest.views.find((entry) => entry.name === view)?.sections
2513
+ ?.find((entry) => entry && typeof entry === 'object' && entry.id === id)
2514
+ if (instance && typeof manifest.name === 'string') {
2515
+ const sidecar = join(target, 'lib', manifest.name, 'views', view, 'sections', `${id}.json`)
2516
+ if (existsSync(sidecar)) {
2517
+ const rel = relative(target, sidecar).replaceAll('\\', '/')
2518
+ if (!preserved.includes(rel)) preserved.push(rel)
2519
+ }
2520
+ }
2521
+ }
2323
2522
  if (args.json) {
2324
2523
  printEnvelope(
2325
2524
  resultEnvelope('section', true, 0, [], {
2326
2525
  action: sub,
2327
2526
  view,
2328
2527
  changed: result.changed,
2329
- preserved: result.preserved,
2528
+ preserved,
2330
2529
  }),
2331
2530
  )
2332
2531
  return 0
@@ -2336,7 +2535,7 @@ async function section(args) {
2336
2535
  console.log(`Added a "${args.positionals[3]}" section to view "${view}".`)
2337
2536
  } else if (sub === 'remove') {
2338
2537
  console.log(`Removed section "${args.positionals[3]}" from view "${view}".`)
2339
- for (const leftover of result.preserved) {
2538
+ for (const leftover of preserved) {
2340
2539
  console.log(`Preserved user-owned file: ${leftover} (remove it manually if no longer needed).`)
2341
2540
  }
2342
2541
  } else {
@@ -2397,6 +2596,105 @@ async function sections(args) {
2397
2596
  return 0
2398
2597
  }
2399
2598
 
2599
+ // Project the section agent-card registry through the current storefront. This
2600
+ // command is read-only; conformance checks execute installed validators only on
2601
+ // the registry's declared examples.
2602
+ async function blocks(args) {
2603
+ const subcommand = args.positionals[1]
2604
+ const fail = (code, message, extra = {}) => {
2605
+ if (args.json) {
2606
+ printEnvelope(resultEnvelope('blocks', false, 1, [envelopeDiagnostic(code, message, extra)]))
2607
+ } else {
2608
+ console.error(message)
2609
+ }
2610
+ return 1
2611
+ }
2612
+
2613
+ if (!['list', 'show', 'check'].includes(subcommand)) {
2614
+ return fail('E_INVALID_BLOCK_COMMAND', 'Usage: storefront blocks list|show <type>|check [--json]')
2615
+ }
2616
+
2617
+ let manifest = null
2618
+ if (subcommand !== 'check') {
2619
+ const read = readManifestOrError(args.dir)
2620
+ if (read.error) return fail('E_INVALID_COMPOSITION', read.error, { path: 'storefront.config.json' })
2621
+ manifest = read.manifest
2622
+ }
2623
+ const registry = loadAgentBlocks({ recipes: loadRecipes(), sections: loadSections(), manifest })
2624
+
2625
+ if (subcommand === 'list') {
2626
+ const projection = await listAgentBlocksWithValidatorStatus(registry, args.dir)
2627
+ const result = { blocks: projection.blocks, unavailable: projection.unavailable }
2628
+ if (args.json) {
2629
+ printEnvelope(resultEnvelope('blocks', true, 0, [], result))
2630
+ return 0
2631
+ }
2632
+ console.log(`Storefront agent blocks (${args.dir}):`)
2633
+ for (const block of result.blocks) {
2634
+ console.log(` ${block.section.padEnd(28)} ${block.label} (hosts: ${block.hosts.join(', ')}; validator: ${block.validator} — ${block.validatorStatus})`)
2635
+ }
2636
+ if (result.blocks.length === 0) console.log(' (no ready agent-configurable sections)')
2637
+ if (result.unavailable.length > 0) {
2638
+ console.log('Unavailable:')
2639
+ for (const entry of result.unavailable) {
2640
+ console.log(` ${entry.section.padEnd(28)} ${entry.status} — ${entry.reason} (owner: ${entry.owner})`)
2641
+ }
2642
+ }
2643
+ return 0
2644
+ }
2645
+
2646
+ if (subcommand === 'show') {
2647
+ const type = args.positionals[2]
2648
+ if (!type) return fail('E_INVALID_BLOCK_COMMAND', 'Usage: storefront blocks show <type> [--json]')
2649
+ const result = await showAgentBlockWithValidatorStatus(type, { ...registry, includeUnavailable: true }, args.dir)
2650
+ if (!result) return fail('E_BLOCK_NOT_FOUND', `Unknown agent block type "${type}".`)
2651
+ if (args.json) {
2652
+ printEnvelope(resultEnvelope('blocks', true, 0, [], result))
2653
+ return 0
2654
+ }
2655
+ if (result.status !== 'ready') {
2656
+ console.log(`${result.section}: ${result.status} (not selectable)`)
2657
+ if (result.reason) console.log(` ${result.reason}`)
2658
+ if (result.owner) console.log(` owner: ${result.owner}`)
2659
+ return 0
2660
+ }
2661
+ console.log(`${result.section} — ${result.label}`)
2662
+ console.log(` ${result.purpose}`)
2663
+ console.log(` hosts: ${result.hosts.join(', ')}`)
2664
+ console.log(` variants: ${result.variants.join(', ')}`)
2665
+ console.log(` validator: ${result.validator} (${result.validatorStatus})`)
2666
+ console.log(` installed instances: ${result.instances.map((instance) => `${instance.id} (${instance.view})`).join(', ') || '(none)'}`)
2667
+ return 0
2668
+ }
2669
+
2670
+ const result = await checkAgentBlocksWithValidatorStatus(registry, args.dir)
2671
+ const diagnostics = result.errors.map((error) => envelopeDiagnostic(
2672
+ error.code,
2673
+ error.message,
2674
+ { section: error.section, path: error.path },
2675
+ ))
2676
+ const exitCode = result.ok ? 0 : 1
2677
+ if (args.json) {
2678
+ printEnvelope(resultEnvelope('blocks', result.ok, exitCode, diagnostics, result))
2679
+ } else {
2680
+ console.log(`Agent block registry (${result.summary.ready} ready, ${result.summary.pending} pending, ${result.summary.exempt} exempt).`)
2681
+ for (const exemption of result.exemptions) {
2682
+ console.log(` exemption: ${exemption.section} (${exemption.status}/${exemption.kind}) — ${exemption.reason} (owner: ${exemption.owner})`)
2683
+ }
2684
+ if (result.ok) console.log(' conformance checks passed')
2685
+ else {
2686
+ console.error('Agent block registry conformance failed:')
2687
+ for (const error of result.errors) {
2688
+ console.error(` ${error.code} ${error.section} ${error.path}: ${error.message}`)
2689
+ }
2690
+ }
2691
+ for (const validator of result.validators) {
2692
+ console.log(` ${validator.section}: ${validator.validator} — ${validator.status}`)
2693
+ }
2694
+ }
2695
+ return exitCode
2696
+ }
2697
+
2400
2698
  // Build a diagnostic for the result/error envelope. `path`, when present, is a
2401
2699
  // project-root-relative POSIX file path; operation-field diagnostics use a
2402
2700
  // semantic locator instead (e.g. `operations[0].surprise`), never a filesystem
@@ -2436,6 +2734,14 @@ function inspect(args) {
2436
2734
  catalogVersion: CATALOG_VERSION,
2437
2735
  slots: catalog.slots ?? {},
2438
2736
  capabilities: catalog.capabilities ?? {},
2737
+ features: (loadFeatures().features ?? []).map((feature) => ({
2738
+ name: feature.name,
2739
+ status: featureStatus(feature.name),
2740
+ reason: feature.reason ?? null,
2741
+ owner: feature.owner ?? null,
2742
+ requires: feature.requires ?? [],
2743
+ backendCapabilities: feature.backendCapabilities ?? [],
2744
+ })),
2439
2745
  composition: {
2440
2746
  views: manifest?.views ?? [],
2441
2747
  features: manifest?.features ?? [],
@@ -2623,7 +2929,12 @@ async function features(args) {
2623
2929
  const entries = specs.map((spec) => ({
2624
2930
  name: spec.name,
2625
2931
  description: spec.description,
2932
+ status: featureStatus(spec.name),
2933
+ reason: spec.reason ?? null,
2934
+ owner: spec.owner ?? null,
2626
2935
  mvp: spec.mvp === true,
2936
+ requires: spec.requires ?? [],
2937
+ backendCapabilities: spec.backendCapabilities ?? [],
2627
2938
  installed: installed.has(spec.name),
2628
2939
  route: spec.route ?? null,
2629
2940
  views: spec.views ?? [],
@@ -2643,9 +2954,12 @@ async function features(args) {
2643
2954
 
2644
2955
  console.log(`Storefront features (${target}):`)
2645
2956
  for (const entry of entries) {
2646
- const status = entry.installed ? 'installed' : entry.mvp ? 'available' : 'held'
2957
+ const status = entry.installed ? 'installed' : entry.status
2647
2958
  const owned = entry.views.join(', ') || '—'
2648
2959
  console.log(` ${entry.name.padEnd(16)} ${status.padEnd(10)} ${owned}`)
2960
+ if (!entry.installed && entry.status === 'held') {
2961
+ console.log(` held: ${entry.reason ?? 'no reason declared'} (owner: ${entry.owner ?? 'unassigned'})`)
2962
+ }
2649
2963
  }
2650
2964
  return 0
2651
2965
  }
@@ -2757,6 +3071,21 @@ async function main() {
2757
3071
  if (!root) return 1
2758
3072
  return sections({ ...args, dir: root })
2759
3073
  }
3074
+ if (args.action === 'blocks') {
3075
+ const root = resolveProject({ quiet: args.json })
3076
+ if (!root) {
3077
+ if (args.json) {
3078
+ printEnvelope(resultEnvelope('blocks', false, 1, [
3079
+ envelopeDiagnostic(
3080
+ 'E_NO_MANIFEST',
3081
+ 'Not inside a storefront project (no storefront.config.json found in this directory or any parent).',
3082
+ ),
3083
+ ]))
3084
+ }
3085
+ return 1
3086
+ }
3087
+ return blocks({ ...args, dir: root })
3088
+ }
2760
3089
  if (args.action === 'inspect' || args.action === 'plan' || args.action === 'apply') {
2761
3090
  const root = resolveProject({ quiet: true })
2762
3091
  if (!root) {
@@ -2825,4 +3154,4 @@ main()
2825
3154
  ]),
2826
3155
  )
2827
3156
  process.exitCode = 2
2828
- })
3157
+ })
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@thorprovider/storefront",
3
- "version": "0.7.0",
3
+ "version": "0.10.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"