@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/scripts/section-operations.mjs

@@ -0,0 +1,508 @@
+#!/usr/bin/env node
+// E3 tasks 3.1, 3.2, and 3.3 (CU-14, CU-15, CU-16): the `section.add`,
+// `section.remove`, and `section.reorder` operations and the production E3
+// operation registry.
+//
+// E3 extends E1's namespaced, extensible registry (E1 Decision 16) with the
+// `section` namespace; it never widens `E1_OPERATION_REGISTRY` or
+// `CATALOG_OPERATION_REGISTRY`. The production registry
+// `SECTION_OPERATION_REGISTRY` is E1's six operations + E2's catalog logical
+// controls + E3's `section.add`/`section.remove`/`section.reorder`, composed with
+// `extendOperationRegistry`.
+//
+// Each reducer is pure over the manifest: it reads the view's declared
+// `sections`, normalizes and validates it through `section-compat.mjs` (the
+// single normalization authority), validates the host/type allowlist, the
+// editorial `maxSections` bound, id uniqueness, the reserved `slot:` prefix, and
+// (for a reorder) that `order` is a permutation of the view's current entry ids,
+// then returns a NEW manifest (plus, for a removal, the preserved content
+// location) with the change applied. It never mutates its input and returns no
+// manifest on any failure, so a caller writes nothing (no partial writes).
+
+import { extendOperationRegistry } from './operation-registry.mjs'
+import { CATALOG_OPERATION_REGISTRY, DIAGNOSTIC_CODES, diagnostic } from './operations.mjs'
+import {
+  isEditorialSectionEntry,
+  isSlotSectionEntry,
+  normalizeViewSections,
+} from './section-compat.mjs'
+import {
+  allowedViewNames,
+  getRecipe,
+  heldSectionReason,
+  loadSections,
+} from '../recipes/validate.mjs'
+
+// The E3 section-operation diagnostics, alongside E1's shared `DIAGNOSTIC_CODES`
+// (E_INVALID_OPERATION, E_VIEW_NOT_INSTALLED). They mirror the codes
+// `section-compat.mjs` emits so a normalization failure and a direct
+// `section.add`/`section.remove` failure are named consistently.
+export const SECTION_DIAGNOSTIC_CODES = Object.freeze({
+  E_UNKNOWN_HOST: 'E_UNKNOWN_HOST',
+  E_DISALLOWED_TYPE: 'E_DISALLOWED_TYPE',
+  E_DUPLICATE_ID: 'E_DUPLICATE_ID',
+  E_RESERVED_ID: 'E_RESERVED_ID',
+  E_SECTION_LIMIT: 'E_SECTION_LIMIT',
+  E_CORE_SLOT_REMOVAL: 'E_CORE_SLOT_REMOVAL',
+  E_UNKNOWN_SECTION_REF: 'E_UNKNOWN_SECTION_REF',
+  E_UNKNOWN_ORDER_REF: 'E_UNKNOWN_ORDER_REF',
+})
+
+const RESERVED_ID_PREFIX = 'slot:'
+
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key)
+}
+
+function requireString(op, field) {
+  return typeof op[field] === 'string' && op[field].length > 0
+}
+
+function fail(code, message, extra = {}) {
+  return { ok: false, diagnostics: [diagnostic(code, message, extra)] }
+}
+
+// The preserved instance ids of the operated view: an editorial instance whose
+// content `section.remove` kept on disk. `content.ts` (classified user-owned by
+// `file-classes.mjs`) holds the content bytes and is never rewritten, but it
+// cannot itself enumerate the ids, so the id record lives in the manifest as the
+// top-level `preservedSectionIds` map (view name -> ordered ids, written by
+// `section.remove`). It is top-level, not per-view, so every E1 `view.*`/
+// `feature.*` reducer (which spreads the manifest) carries it forward and an
+// explicit re-add cannot accidentally rebind. Auto-mint consults the set so a
+// fresh id never rebinds preserved content; an explicit re-add of a preserved id
+// leaves the set (rebind). This is the concrete disk-backed notion of "preserved"
+// (E3 task 3.7, design §"Remove, content preservation, and re-add same id").
+function preservedIdsFor(manifest, viewName) {
+  const map = manifest.preservedSectionIds
+  const list =
+    map && typeof map === 'object' && !Array.isArray(map) ? map[viewName] : undefined
+  const entries = Array.isArray(list) ? list : []
+  return new Set(entries.filter((id) => typeof id === 'string' && id.length > 0))
+}
+
+// Copy `manifest` with `preservedSectionIds[viewName]` set to exactly `ids`
+// (deduplicated, insertion-ordered). An empty list drops the view's entry, and an
+// empty map drops the top-level field, so a manifest that never preserved
+// anything stays byte-identical to one that preserved and re-added. Never mutates
+// the input.
+function withPreservedIds(manifest, viewName, ids) {
+  const current = manifest.preservedSectionIds
+  const map = current && typeof current === 'object' && !Array.isArray(current) ? { ...current } : {}
+  const deduped = [...new Set(ids)]
+  if (deduped.length === 0) delete map[viewName]
+  else map[viewName] = deduped
+  const out = { ...manifest }
+  if (Object.keys(map).length === 0) delete out.preservedSectionIds
+  else out.preservedSectionIds = map
+  return out
+}
+
+function sectionDefinition(type) {
+  const sections = loadSections()?.sections
+  const list = Array.isArray(sections) ? sections : []
+  return list.find((section) => section.name === type) ?? null
+}
+
+// The smallest free `<view>-<type>-<n>` (n >= 1) not in `used ∪ preserved`, so an
+// auto-minted id never rebinds preserved content (design: `section.add` auto-mint).
+function mintSectionId(viewName, type, used, preserved) {
+  for (let n = 1; ; n += 1) {
+    const candidate = `${viewName}-${type}-${n}`
+    if (!used.has(candidate) && !preserved.has(candidate)) return candidate
+  }
+}
+
+// The user-owned file that holds a view's editorial instance content, keyed by
+// instance id (design §"Remove, content preservation, and re-add same id"). It is
+// the view's `content.ts` module, which `file-classes.mjs` classifies user-owned
+// and `reconcile` seeds once and never rewrites, so `section.remove` preserves
+// the content simply by not touching the file; the reducer reports this
+// project-relative POSIX path through the operation's `removals` so the write
+// boundary surfaces it in the result's `preserved` list. The helper is pure (it
+// derives the path from the manifest name and the view), so the reducer stays
+// filesystem-free.
+function sectionContentPath(manifest, viewName) {
+  return `lib/${manifest.name}/views/${viewName}/content.ts`
+}
+
+/**
+ * Reduce a `section.add` operation over the manifest (E3 task 3.1). Validates the
+ * host allowlist (`E_UNKNOWN_HOST` for an unknown view, `E_DISALLOWED_TYPE` for a
+ * type the view does not allow), id uniqueness against `used` (`E_DUPLICATE_ID`),
+ * the reserved `slot:` prefix (`E_RESERVED_ID`), and the editorial `maxSections`
+ * bound (`E_SECTION_LIMIT`). An omitted `id` is minted from `used ∪ preserved`,
+ * where `preserved` is the view's recorded removed ids (so a fresh id never
+ * rebinds preserved content). An explicit `id` that is still present is
+ * `E_DUPLICATE_ID`; an explicit `id` that is preserved (removed, its content
+ * still on disk) succeeds and rebinds — it leaves the preserved record. Returns
+ * `{ ok: true, manifest }` with the instance inserted at `at` (0-based, default
+ * append) or `{ ok: false, diagnostics }`. The input manifest is never mutated.
+ */
+export function reduceSectionAdd(manifest, op, options = {}) {
+  if (!requireString(op, 'view')) {
+    return fail(
+      DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+      'section.add requires a non-empty string "view".',
+    )
+  }
+  if (!requireString(op, 'type')) {
+    return fail(
+      DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+      'section.add requires a non-empty string "type".',
+    )
+  }
+  const viewName = op.view
+  const recipe = getRecipe(viewName)
+  if (!recipe) {
+    return fail(
+      SECTION_DIAGNOSTIC_CODES.E_UNKNOWN_HOST,
+      `Unknown view "${viewName}" is not a section host. Allowed views: ${allowedViewNames().join(', ')}.`,
+    )
+  }
+  const allowedSections = Array.isArray(recipe.allowedSections) ? recipe.allowedSections : []
+  if (!allowedSections.includes(op.type)) {
+    const held = heldSectionReason(op.type)
+    const heldDetail = held ? ` Section "${op.type}" is held: ${held}.` : ''
+    return fail(
+      SECTION_DIAGNOSTIC_CODES.E_DISALLOWED_TYPE,
+      `Section type "${op.type}" is not an allowed section for view "${viewName}". Allowed sections: ${allowedSections.join(', ') || '(none)'}.${heldDetail}`,
+    )
+  }
+  const installed = manifest.views.find((view) => view.name === viewName)
+  if (!installed) {
+    return fail(
+      DIAGNOSTIC_CODES.E_VIEW_NOT_INSTALLED,
+      `View "${viewName}" is not installed; add the view before adding a section to it.`,
+    )
+  }
+  const registeredSlots = Array.isArray(recipe.registeredSlots) ? recipe.registeredSlots : []
+  const maxSections = typeof recipe.maxSections === 'number' ? recipe.maxSections : null
+  const preserved = preservedIdsFor(manifest, viewName)
+
+  // Normalize/validate the current composition through the single authority so a
+  // legacy or malformed list is adapted or refused consistently, with no output
+  // on failure.
+  const normalized = normalizeViewSections(viewName, installed.sections ?? [], registeredSlots, {
+    allowedSections,
+    maxSections,
+  })
+  if (!normalized.ok) return { ok: false, diagnostics: normalized.diagnostics }
+  const current = normalized.sections
+  const used = new Set(current.map((entry) => entry.id))
+
+  let id
+  if (hasOwn(op, 'id')) {
+    if (!requireString(op, 'id')) {
+      return fail(
+        DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+        'section.add "id" must be a non-empty string when present.',
+      )
+    }
+    if (op.id.startsWith(RESERVED_ID_PREFIX)) {
+      return fail(
+        SECTION_DIAGNOSTIC_CODES.E_RESERVED_ID,
+        `section.add id "${op.id}" must not start with the reserved "${RESERVED_ID_PREFIX}" prefix.`,
+      )
+    }
+    if (used.has(op.id)) {
+      return fail(
+        SECTION_DIAGNOSTIC_CODES.E_DUPLICATE_ID,
+        `section.add id "${op.id}" is already present in view "${viewName}".`,
+      )
+    }
+    id = op.id
+  } else {
+    id = mintSectionId(viewName, op.type, used, preserved)
+  }
+
+  let variant
+  if (hasOwn(op, 'variant')) {
+    if (!requireString(op, 'variant')) {
+      return fail(
+        DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+        'section.add "variant" must be a non-empty string when present.',
+      )
+    }
+    const definition = sectionDefinition(op.type)
+    const variants = Array.isArray(definition?.variants) ? definition.variants : []
+    if (variants.length > 0 && !variants.includes(op.variant)) {
+      return fail(
+        DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+        `Variant "${op.variant}" is not a declared variant for section "${op.type}". Declared: ${variants.join(', ')}.`,
+      )
+    }
+    variant = op.variant
+  }
+
+  const editorialCount = current.filter((entry) => isEditorialSectionEntry(entry)).length
+  if (maxSections !== null && editorialCount + 1 > maxSections) {
+    return fail(
+      SECTION_DIAGNOSTIC_CODES.E_SECTION_LIMIT,
+      `Adding a "${op.type}" instance to view "${viewName}" would exceed maxSections ${maxSections} (currently ${editorialCount}).`,
+    )
+  }
+
+  let at = current.length
+  if (hasOwn(op, 'at')) {
+    if (!Number.isInteger(op.at) || op.at < 0 || op.at > current.length) {
+      return fail(
+        DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+        `section.add "at" must be an integer between 0 and ${current.length}.`,
+      )
+    }
+    at = op.at
+  }
+
+  const entry = { id, type: op.type, ...(variant === undefined ? {} : { variant }) }
+  const sections = [...current.slice(0, at), entry, ...current.slice(at)]
+  const views = manifest.views.map((view) =>
+    view.name === viewName ? { ...view, sections } : view,
+  )
+  // Re-adding an explicit preserved id rebinds its content: the id leaves the
+  // preserved record and becomes a used id. An auto-minted id is already absent
+  // from the preserved set, so this is a no-op for it.
+  const next = withPreservedIds(
+    { ...manifest, views },
+    viewName,
+    [...preserved].filter((preservedId) => preservedId !== id),
+  )
+  return { ok: true, manifest: next }
+}
+
+/**
+ * Reduce a `section.remove` operation over the manifest (E3 task 3.2,
+ * CU-15/CU-16). A reserved `slot:` id is a core registered slot and is rejected
+ * with `E_CORE_SLOT_REMOVAL` (design's stable code); an id that does not name a
+ * present editorial instance is rejected with `E_UNKNOWN_SECTION_REF`. On
+ * success it drops the editorial entry from the ordered composition, records the
+ * removed id as preserved in the view's `preservedSectionIds`, and returns the
+ * removal holder carrying the instance's user-owned content location, which the
+ * write boundary reports as preserved while `reconcile` leaves the file
+ * byte-unchanged. Never mutates its input and returns no manifest on failure, so
+ * a caller writes nothing (no partial writes).
+ */
+export function reduceSectionRemove(manifest, op, options = {}) {
+  if (!requireString(op, 'view')) {
+    return fail(
+      DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+      'section.remove requires a non-empty string "view".',
+    )
+  }
+  if (!requireString(op, 'id')) {
+    return fail(
+      DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+      'section.remove requires a non-empty string "id".',
+    )
+  }
+  const viewName = op.view
+  const recipe = getRecipe(viewName)
+  if (!recipe) {
+    return fail(
+      SECTION_DIAGNOSTIC_CODES.E_UNKNOWN_HOST,
+      `Unknown view "${viewName}" is not a section host. Allowed views: ${allowedViewNames().join(', ')}.`,
+    )
+  }
+  const installed = manifest.views.find((view) => view.name === viewName)
+  if (!installed) {
+    return fail(
+      DIAGNOSTIC_CODES.E_VIEW_NOT_INSTALLED,
+      `View "${viewName}" is not installed; add the view before removing a section from it.`,
+    )
+  }
+  // Core registered slots are non-removable (design "core transactional slots are
+  // never removed"): any reserved `slot:` id is refused before normalization with
+  // the stable `E_CORE_SLOT_REMOVAL` code.
+  if (op.id.startsWith(RESERVED_ID_PREFIX)) {
+    return fail(
+      SECTION_DIAGNOSTIC_CODES.E_CORE_SLOT_REMOVAL,
+      `section.remove id "${op.id}" is a reserved core slot of view "${viewName}"; registered slots cannot be removed.`,
+    )
+  }
+  const registeredSlots = Array.isArray(recipe.registeredSlots) ? recipe.registeredSlots : []
+  const allowedSections = Array.isArray(recipe.allowedSections) ? recipe.allowedSections : []
+  const maxSections = typeof recipe.maxSections === 'number' ? recipe.maxSections : null
+
+  // Normalize/validate the current composition through the single authority so a
+  // legacy or malformed list is adapted or refused consistently, with no output
+  // on failure.
+  const normalized = normalizeViewSections(viewName, installed.sections ?? [], registeredSlots, {
+    allowedSections,
+    maxSections,
+  })
+  if (!normalized.ok) return { ok: false, diagnostics: normalized.diagnostics }
+  const current = normalized.sections
+
+  const target = current.find(
+    (entry) => entry.id === op.id && isEditorialSectionEntry(entry),
+  )
+  if (!target) {
+    return fail(
+      SECTION_DIAGNOSTIC_CODES.E_UNKNOWN_SECTION_REF,
+      `section.remove id "${op.id}" does not name an editorial section instance in view "${viewName}".`,
+    )
+  }
+
+  const sections = current.filter((entry) => entry.id !== op.id)
+  const views = manifest.views.map((view) =>
+    view.name === viewName ? { ...view, sections } : view,
+  )
+  // Record the removed id as preserved: its user-owned content stays in the
+  // view's `content.ts` (unchanged), and the manifest holds the id so a later
+  // explicit re-add rebinds it while auto-mint avoids it.
+  const preserved = preservedIdsFor(manifest, viewName)
+  const next = withPreservedIds({ ...manifest, views }, viewName, [...preserved, op.id])
+  return {
+    ok: true,
+    manifest: next,
+    removals: [
+      { kind: 'section', view: viewName, id: op.id, contentPath: sectionContentPath(manifest, viewName) },
+    ],
+  }
+}
+
+/**
+ * Reduce a `section.reorder` operation over the manifest (E3 task 3.3,
+ * CU-15/CU-16). `order` MUST be a permutation of the view's current entry ids:
+ * every current id exactly once, no unknown id, no duplicate, and every
+ * registered core slot present. The current composition is normalized through
+ * the single `section-compat.mjs` authority first, so a legacy or malformed list
+ * is adapted or refused consistently. A successful reorder keeps every entry's
+ * id, type, variant, and content: it returns a new manifest whose view's
+ * `sections` are the same normalized entries in the requested order, never
+ * mutating its input and returning no manifest on failure (no partial writes).
+ *
+ * Stable codes (design diagnostic table): an id not present in the view ->
+ * `E_UNKNOWN_ORDER_REF`; a registered core slot that is omitted or listed twice
+ * -> `E_CORE_SLOT_REMOVAL`; a present editorial id listed twice ->
+ * `E_DUPLICATE_ID`.
+ */
+export function reduceSectionReorder(manifest, op, options = {}) {
+  if (!requireString(op, 'view')) {
+    return fail(
+      DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+      'section.reorder requires a non-empty string "view".',
+    )
+  }
+  if (!Array.isArray(op.order)) {
+    return fail(
+      DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+      'section.reorder requires an "order" array of entry ids.',
+    )
+  }
+  const viewName = op.view
+  const recipe = getRecipe(viewName)
+  if (!recipe) {
+    return fail(
+      SECTION_DIAGNOSTIC_CODES.E_UNKNOWN_HOST,
+      `Unknown view "${viewName}" is not a section host. Allowed views: ${allowedViewNames().join(', ')}.`,
+    )
+  }
+  const installed = manifest.views.find((view) => view.name === viewName)
+  if (!installed) {
+    return fail(
+      DIAGNOSTIC_CODES.E_VIEW_NOT_INSTALLED,
+      `View "${viewName}" is not installed; add the view before reordering its sections.`,
+    )
+  }
+  const registeredSlots = Array.isArray(recipe.registeredSlots) ? recipe.registeredSlots : []
+  const allowedSections = Array.isArray(recipe.allowedSections) ? recipe.allowedSections : []
+  const maxSections = typeof recipe.maxSections === 'number' ? recipe.maxSections : null
+
+  // Normalize/validate the current composition through the single authority so a
+  // legacy or malformed list is adapted or refused consistently, with no output
+  // on failure.
+  const normalized = normalizeViewSections(viewName, installed.sections ?? [], registeredSlots, {
+    allowedSections,
+    maxSections,
+  })
+  if (!normalized.ok) return { ok: false, diagnostics: normalized.diagnostics }
+  const current = normalized.sections
+  const byId = new Map(current.map((entry) => [entry.id, entry]))
+  const slotIds = new Set(current.filter((entry) => isSlotSectionEntry(entry)).map((entry) => entry.id))
+
+  const order = op.order
+  for (const id of order) {
+    if (typeof id !== 'string' || id.length === 0) {
+      return fail(
+        DIAGNOSTIC_CODES.E_INVALID_OPERATION,
+        'section.reorder "order" entries must be non-empty strings.',
+      )
+    }
+  }
+
+  const seen = new Set()
+  for (const id of order) {
+    if (!byId.has(id)) {
+      return fail(
+        SECTION_DIAGNOSTIC_CODES.E_UNKNOWN_ORDER_REF,
+        `section.reorder names id "${id}" which is not present in view "${viewName}".`,
+      )
+    }
+    if (seen.has(id)) {
+      if (slotIds.has(id)) {
+        return fail(
+          SECTION_DIAGNOSTIC_CODES.E_CORE_SLOT_REMOVAL,
+          `section.reorder lists the core slot "${id}" more than once; registered slots appear exactly once.`,
+        )
+      }
+      return fail(
+        SECTION_DIAGNOSTIC_CODES.E_DUPLICATE_ID,
+        `section.reorder lists id "${id}" more than once.`,
+      )
+    }
+    seen.add(id)
+  }
+
+  // Every current entry id must appear exactly once. An omitted registered slot is
+  // `E_CORE_SLOT_REMOVAL` (design: "order omits ... a registered slot"); an omitted
+  // editorial id is the dual of an unknown reference, refused with
+  // `E_UNKNOWN_ORDER_REF` (the design named no separate code; recorded in
+  // `design.md`).
+  for (const id of byId.keys()) {
+    if (seen.has(id)) continue
+    if (slotIds.has(id)) {
+      return fail(
+        SECTION_DIAGNOSTIC_CODES.E_CORE_SLOT_REMOVAL,
+        `section.reorder omits the core slot "${id}"; registered slots cannot be removed or omitted.`,
+      )
+    }
+    return fail(
+      SECTION_DIAGNOSTIC_CODES.E_UNKNOWN_ORDER_REF,
+      `section.reorder "order" is not a permutation of view "${viewName}" entry ids: it omits "${id}".`,
+    )
+  }
+
+  const sections = order.map((id) => byId.get(id))
+  const views = manifest.views.map((view) =>
+    view.name === viewName ? { ...view, sections } : view,
+  )
+  return { ok: true, manifest: { ...manifest, views } }
+}
+
+// E3's production registry: E1's six operations + E2's catalog logical controls +
+// E3's `section.add`/`section.remove`/`section.reorder`. `E1_OPERATION_REGISTRY`
+// and `CATALOG_OPERATION_REGISTRY` are never mutated, so E1's vocabulary and E2's
+// controls stay exactly as accepted.
+export const SECTION_OPERATION_REGISTRY = extendOperationRegistry(CATALOG_OPERATION_REGISTRY, {
+  operations: [
+    {
+      name: 'section.add',
+      required: ['view', 'type'],
+      optional: ['id', 'variant', 'at'],
+      reducer: reduceSectionAdd,
+    },
+    {
+      name: 'section.remove',
+      required: ['view', 'id'],
+      optional: [],
+      reducer: reduceSectionRemove,
+    },
+    {
+      name: 'section.reorder',
+      required: ['view', 'order'],
+      optional: [],
+      reducer: reduceSectionReorder,
+    },
+  ],
+})

package/scripts/starter.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// Initial composition for `storefront create`.
+//
+// Without `--starter`, create seeds the minimal baseline (home + cart, no
+// features). With `--starter`, it seeds the full curated set: every curated
+// feature and every curated view — including the views a feature owns, so each
+// installed feature satisfies the composition contract. The set is derived from
+// the registry (`recipes/validate.mjs`), never a hand-maintained list, so held
+// units are excluded by construction.
+
+import { curatedViewNames, starterComposition } from '../recipes/validate.mjs'
+
+export function scaffoldComposition({ starter = false } = {}) {
+  if (!starter) return { views: ['home', 'cart'], features: [] }
+  const { features } = starterComposition()
+  return { views: curatedViewNames(), features }
+}

package/scripts/sync-assets.mjs

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 // Keeps the per-skill copies of shared assets in sync with the single source.
 //
-// Source of truth: recipes/ at the package root.
-// Generated copies:
-//   skills/sf-view-gen/assets/recipes/{recipes,archetypes,sections}.json
-//   skills/sf-view-gen/scripts/validate.mjs
+// Source of truth: `recipes/` and `scripts/schema-validate.mjs` at the package root.
+// Generated copies (the installed skill must be executable from its own assets,
+// so the catalog loader, its schema, and the schema validator travel with it):
+//   skills/sf-view-gen/assets/recipes/{recipes,archetypes,sections,features}.json
+//   skills/sf-view-gen/assets/recipes/{catalog,catalog.schema}.json
+//   skills/sf-view-gen/scripts/{validate,catalog,schema-validate}.mjs
 //
-// Usage:
+// Paths are package-root-relative. Usage:
 //   node scripts/sync-assets.mjs           # write the copies from source
 //   node scripts/sync-assets.mjs --check   # report divergence, exit 1 if any
 
@@ -19,13 +21,16 @@ import { fileURLToPath } from 'node:url'
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const PKG_ROOT = resolve(__dirname, '..')
 
-const SOURCE = join(PKG_ROOT, 'recipes')
-
 const MANIFEST = [
-  ['recipes.json', join(PKG_ROOT, 'skills/sf-view-gen/assets/recipes/recipes.json')],
-  ['archetypes.json', join(PKG_ROOT, 'skills/sf-view-gen/assets/recipes/archetypes.json')],
-  ['sections.json', join(PKG_ROOT, 'skills/sf-view-gen/assets/recipes/sections.json')],
-  ['validate.mjs', join(PKG_ROOT, 'skills/sf-view-gen/scripts/validate.mjs')],
+  ['recipes/recipes.json', 'skills/sf-view-gen/assets/recipes/recipes.json'],
+  ['recipes/archetypes.json', 'skills/sf-view-gen/assets/recipes/archetypes.json'],
+  ['recipes/sections.json', 'skills/sf-view-gen/assets/recipes/sections.json'],
+  ['recipes/features.json', 'skills/sf-view-gen/assets/recipes/features.json'],
+  ['recipes/catalog.json', 'skills/sf-view-gen/assets/recipes/catalog.json'],
+  ['recipes/catalog.schema.json', 'skills/sf-view-gen/assets/recipes/catalog.schema.json'],
+  ['recipes/catalog.mjs', 'skills/sf-view-gen/scripts/catalog.mjs'],
+  ['recipes/validate.mjs', 'skills/sf-view-gen/scripts/validate.mjs'],
+  ['scripts/schema-validate.mjs', 'skills/sf-view-gen/scripts/schema-validate.mjs'],
 ]
 
 function sha256(text) {
@@ -34,8 +39,9 @@ function sha256(text) {
 
 export async function checkAssets() {
   const diverged = []
-  for (const [sourceName, destPath] of MANIFEST) {
-    const source = await readFile(join(SOURCE, sourceName), 'utf8')
+  for (const [sourceRel, destRel] of MANIFEST) {
+    const source = await readFile(join(PKG_ROOT, sourceRel), 'utf8')
+    const destPath = join(PKG_ROOT, destRel)
     if (!existsSync(destPath)) {
       diverged.push(`${destPath} (missing)`)
       continue
@@ -50,8 +56,9 @@ export async function checkAssets() {
 
 async function syncAssets() {
   let written = 0
-  for (const [sourceName, destPath] of MANIFEST) {
-    const source = await readFile(join(SOURCE, sourceName), 'utf8')
+  for (const [sourceRel, destRel] of MANIFEST) {
+    const source = await readFile(join(PKG_ROOT, sourceRel), 'utf8')
+    const destPath = join(PKG_ROOT, destRel)
     await mkdir(dirname(destPath), { recursive: true })
     await writeFile(destPath, source, 'utf8')
     written++