@thorprovider/storefront 0.3.1 → 0.4.0-mvp.0

package/scripts/manifest.mjs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+// Composition manifest for a generated storefront.
+//
+// The manifest (`storefront.config.json` at the project root) is the single
+// source of truth for what a storefront is composed of: its theme mode, the
+// installed views, the installed features, and the selected intent for each
+// block slot. Structural files are derived from it; user-owned files are not.
+
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { validateAgainstSchema } from './schema-validate.mjs'
+
+const here = dirname(fileURLToPath(import.meta.url))
+// The published schema is the single source of truth for the manifest shape;
+// registry semantics (known units, intents, variants, dependencies) are checked
+// separately by the shared preflight.
+const manifestSchema = JSON.parse(
+  readFileSync(join(here, '..', 'recipes', 'manifest.schema.json'), 'utf8')
+)
+
+export const MANIFEST_FILE = 'storefront.config.json'
+export const MANIFEST_VERSION = '1.0.0'
+export const MANIFEST_SCHEMA_ID = 'https://thorcommerce.dev/storefront/manifest.schema.json'
+export const THEME_MODES = ['light', 'dark', 'system']
+export const DEFAULT_THEME_MODE = 'system'
+
+/**
+ * Normalize a view entry to its canonical manifest shape.
+ * Accepts a bare view name or a partial object.
+ */
+export function normalizeView(view) {
+  if (typeof view === 'string') {
+    return { name: view, intents: {}, variants: {}, sections: [] }
+  }
+  return {
+    name: view.name,
+    intents: { ...(view.intents ?? {}) },
+    variants: { ...(view.variants ?? {}) },
+    sections: (view.sections ?? []).map((section) =>
+      typeof section === 'string' ? { name: section } : { ...section }
+    ),
+  }
+}
+
+/**
+ * Normalize a feature entry to its canonical manifest shape.
+ * Accepts a bare feature name or a partial object.
+ */
+export function normalizeFeature(feature) {
+  if (typeof feature === 'string') {
+    return { name: feature, config: {} }
+  }
+  return { name: feature.name, config: { ...(feature.config ?? {}) } }
+}
+
+/**
+ * Build a canonical manifest from scaffold inputs.
+ */
+export function createManifest({
+  name,
+  siteName,
+  mode = DEFAULT_THEME_MODE,
+  views = [],
+  features = [],
+} = {}) {
+  return {
+    $schema: MANIFEST_SCHEMA_ID,
+    version: MANIFEST_VERSION,
+    name,
+    siteName: siteName ?? name,
+    theme: { mode },
+    views: views.map(normalizeView),
+    features: features.map(normalizeFeature),
+  }
+}
+
+export function serializeManifest(manifest) {
+  return `${JSON.stringify(manifest, null, 2)}\n`
+}
+
+export function parseManifest(text) {
+  return JSON.parse(text)
+}
+
+/**
+ * Validate a manifest's structural shape against the published schema, plus the
+ * uniqueness invariant the schema cannot express. Registry semantics (known
+ * units, intents, variants, slots, dependencies) are checked by the shared
+ * preflight, not here, so a shape-valid manifest stays readable on its own.
+ * Returns { ok, errors }.
+ */
+export function validateManifest(manifest) {
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    return { ok: false, errors: ['Manifest must be a JSON object.'] }
+  }
+  const errors = validateAgainstSchema(manifest, manifestSchema)
+  errors.push(...duplicateNameErrors(manifest.views, 'view'))
+  errors.push(...duplicateNameErrors(manifest.features, 'feature'))
+  errors.push(...sectionEntryErrors(manifest.views))
+  return { ok: errors.length === 0, errors }
+}
+
+function duplicateNameErrors(entries, kind) {
+  const errors = []
+  if (!Array.isArray(entries)) return errors
+  const seen = new Set()
+  for (const entry of entries) {
+    if (!entry || typeof entry !== 'object') continue
+    if (typeof entry.name !== 'string' || !entry.name) continue
+    if (seen.has(entry.name)) errors.push(`Duplicate ${kind} "${entry.name}".`)
+    else seen.add(entry.name)
+  }
+  return errors
+}
+
+// The published schema can express each `sections[]` entry's shape but not the
+// cross-entry invariants: legacy-vs-new discrimination, the reserved
+// `id === "slot:" + type` form, and id uniqueness within a view. Those are
+// enforced here so an invalid or dangling entry is refused before any derived
+// file is written. Legacy `{ name, variant }` entries stay accepted until the
+// deterministic migration (E3 task 1.5) rewrites them.
+function sectionEntryErrors(views) {
+  const errors = []
+  if (!Array.isArray(views)) return errors
+  for (const view of views) {
+    if (!view || typeof view !== 'object' || Array.isArray(view)) continue
+    if (!Array.isArray(view.sections)) continue
+    const seen = new Set()
+    view.sections.forEach((section, index) => {
+      const label = `views["${view.name}"].sections[${index}]`
+      if (!section || typeof section !== 'object' || Array.isArray(section)) {
+        errors.push(`${label} must be an object.`)
+        return
+      }
+      const hasName = typeof section.name === 'string' && section.name.length > 0
+      const hasId = typeof section.id === 'string' && section.id.length > 0
+      const hasType = typeof section.type === 'string' && section.type.length > 0
+
+      if (hasId || hasType) {
+        if (!hasId || !hasType) {
+          errors.push(`${label} must declare both "id" and "type" (or a legacy "name").`)
+          return
+        }
+        if (hasName) {
+          errors.push(`${label} cannot mix the legacy "name" field with "id"/"type".`)
+          return
+        }
+        if (section.id.startsWith('slot:') && section.id !== `slot:${section.type}`) {
+          errors.push(
+            `${label} reserved slot id "${section.id}" must equal "slot:" + type ("slot:${section.type}").`
+          )
+        }
+        if (seen.has(section.id)) errors.push(`${label} duplicate section id "${section.id}".`)
+        else seen.add(section.id)
+        return
+      }
+
+      if (hasName) {
+        if (seen.has(section.name)) errors.push(`${label} duplicate section name "${section.name}".`)
+        else seen.add(section.name)
+        return
+      }
+
+      errors.push(`${label} is neither a legacy { name } entry nor an { id, type } entry.`)
+    })
+  }
+  return errors
+}
+
+export function manifestPath(projectDir) {
+  return join(projectDir, MANIFEST_FILE)
+}
+
+export function hasManifest(projectDir) {
+  return existsSync(manifestPath(projectDir))
+}
+
+/**
+ * Read the manifest at a project root, or null when it does not exist.
+ * Malformed JSON throws, so callers can surface a precise error.
+ */
+export function readManifest(projectDir) {
+  if (!hasManifest(projectDir)) return null
+  return parseManifest(readFileSync(manifestPath(projectDir), 'utf8'))
+}
+
+// The manifest is the composition source of truth, so the writer refuses to
+// persist a document that does not satisfy the published schema. This makes the
+// shape contract unbypassable from any caller: full registry/dependency
+// semantics are additionally enforced by `preflightManifest` at every CLI write
+// boundary and by `reconcile` before it renders.
+export function writeManifest(projectDir, manifest) {
+  const shape = validateManifest(manifest)
+  if (!shape.ok) {
+    throw new Error(
+      `Refusing to write an invalid manifest:\n${shape.errors.map((error) => `  ${error}`).join('\n')}`
+    )
+  }
+  writeFileSync(manifestPath(projectDir), serializeManifest(manifest))
+}
+
+/**
+ * Whether a directory looks like a storefront project even without a manifest
+ * (a `lib/<name>/` module holding a `views/` directory or a `registry.tsx`).
+ * Used so migration and reconcile can run on a pre-manifest storefront.
+ */
+export function looksLikeStorefront(projectDir) {
+  const libDir = join(projectDir, 'lib')
+  if (!existsSync(libDir)) return false
+  return readdirSync(libDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .some(
+      (entry) =>
+        existsSync(join(libDir, entry.name, 'views')) ||
+        existsSync(join(libDir, entry.name, 'registry.tsx'))
+    )
+}
+
+/**
+ * Search upward from startDir for the storefront project root (the nearest
+ * ancestor holding a manifest, or a storefront-shaped project). Returns the
+ * directory or null.
+ */
+export function findProjectRoot(startDir) {
+  let current = startDir
+  while (true) {
+    if (hasManifest(current) || looksLikeStorefront(current)) return current
+    const parent = dirname(current)
+    if (parent === current) return null
+    current = parent
+  }
+}
+
+function titleCase(value) {
+  return value
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ')
+}
+
+function detectStorefrontName(projectDir) {
+  const libDir = join(projectDir, 'lib')
+  if (!existsSync(libDir)) return null
+  const candidates = readdirSync(libDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .filter(
+      (entry) =>
+        existsSync(join(libDir, entry.name, 'views')) ||
+        existsSync(join(libDir, entry.name, 'registry.tsx'))
+    )
+    .map((entry) => entry.name)
+    .sort()
+  return candidates[0] ?? null
+}
+
+function detectViews(projectDir, name) {
+  const viewsDir = join(projectDir, 'lib', name, 'views')
+  if (!existsSync(viewsDir)) return []
+  return readdirSync(viewsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(join(viewsDir, entry.name, 'index.tsx')))
+    .map((entry) => entry.name)
+    .sort()
+}
+
+function detectThemeMode(projectDir) {
+  const layoutPath = join(projectDir, 'app', 'layout.tsx')
+  if (!existsSync(layoutPath)) return DEFAULT_THEME_MODE
+  const match = readFileSync(layoutPath, 'utf8').match(/defaultTheme=["']([^"']+)["']/)
+  return match && THEME_MODES.includes(match[1]) ? match[1] : DEFAULT_THEME_MODE
+}
+
+function detectSiteName(projectDir, name) {
+  const layoutPath = join(projectDir, 'app', 'layout.tsx')
+  if (existsSync(layoutPath)) {
+    const match = readFileSync(layoutPath, 'utf8').match(/title:\s*['"`]([^'"`]+)['"`]/)
+    if (match && match[1]) return match[1]
+  }
+  return titleCase(name)
+}
+
+/**
+ * Derive an initial manifest from an existing (pre-manifest) storefront
+ * composition so `sync` can migrate a project in place. Returns null when no
+ * storefront composition can be found.
+ */
+export function deriveManifest(projectDir) {
+  const name = detectStorefrontName(projectDir)
+  if (!name) return null
+  return createManifest({
+    name,
+    siteName: detectSiteName(projectDir, name),
+    mode: detectThemeMode(projectDir),
+    views: detectViews(projectDir, name),
+    features: [],
+  })
+}

package/scripts/operation-registry.mjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+// E1 task 4.15 (CU-17): the namespaced, extensible operation registry and its
+// logical-controls metadata seam (E1 design Decision 16).
+//
+// WHY THIS EXISTS: E1 owns exactly six public composition operations. E2 and E3
+// must consume the same envelope, fingerprint, mount, and diagnostics contracts
+// without redefining E1's engine, and E1 must not hardcode their behavior. This
+// module is that seam — a registry keyed by the namespaced `op` string plus a
+// pure, additive registration contract. Registration never mutates the registry
+// it extends; it returns a new frozen registry. Production therefore stays
+// closed: the E1 registry carries only its six operations, and any later-change
+// operation remains `E_UNKNOWN_OPERATION` until a later change explicitly builds
+// a registry that includes it. There is no environment switch and no backdoor.
+//
+// Two kinds of registration, deliberately separated:
+//
+//   * An operation is BEHAVIOR: `{ name, required, optional, reducer }`. The
+//     `reducer` is a pure `(manifest, op, ctx) -> { ok, manifest?, diagnostics?,
+//     removals? }` function, the same contract `reduceManifest` dispatches.
+//   * A logical control is METADATA: it declares that a control slot contributes
+//     to one already-rendered presentation (`kind: "logical-control"`, `host`,
+//     `slot`, `presentation`, optional `capability`). It carries no render-owned
+//     field (`block`, `element`), no behavior (`reducer`), and no operation. This
+//     is the distinction E2 relies on when it contributes search/filters to the
+//     single `CategoryFilter2` listing with no new operation (E2 design; E1
+//     Decision 16). Registering a whole view is the catalog's job, not this
+//     seam's, so a contribution that tries to carry a render field is rejected.
+
+export const OPERATION_NAMESPACE_SEPARATOR = '.'
+
+export const LOGICAL_CONTROL_KIND = 'logical-control'
+
+// The exact fields a logical-control contribution may carry. This is the
+// consumed contract E2 uses: `feature` (the contributing feature), `host`/`slot`
+// (the control slot, matching the feature's `mounts: [{ id, host, slot }]`
+// shape), `presentation` (the one rendered block it feeds), and optional
+// `capability` (the capability id it implements).
+const LOGICAL_CONTROL_FIELDS = Object.freeze([
+  'kind',
+  'feature',
+  'host',
+  'slot',
+  'presentation',
+  'capability',
+])
+
+// Render- and behavior-owned fields a logical control must NOT carry. Their
+// presence is the signal that a caller is trying to register a whole view or an
+// operation through the metadata seam; it is rejected with a clear message.
+const LOGICAL_CONTROL_FORBIDDEN_FIELDS = Object.freeze([
+  'block',
+  'element',
+  'reducer',
+  'variants',
+  'surfaces',
+  'mounts',
+  'route',
+])
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0
+}
+
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key)
+}
+
+/**
+ * The namespace of a namespaced operation name: the segment before the first
+ * `.` (`view.add` -> `view`), or the empty string when the name is not
+ * namespaced. Each registered operation name must be namespaced so later changes
+ * extend the registry without colliding with E1's names.
+ */
+export function operationNamespace(name) {
+  if (typeof name !== 'string') return ''
+  const index = name.indexOf(OPERATION_NAMESPACE_SEPARATOR)
+  return index === -1 ? '' : name.slice(0, index)
+}
+
+function assertOperationDefinition(definition) {
+  if (!isPlainObject(definition)) {
+    throw new TypeError('operation definition must be an object.')
+  }
+  if (!isNonEmptyString(definition.name) || operationNamespace(definition.name) === '') {
+    throw new TypeError(
+      `operation name must be a non-empty namespaced string such as "view.add"; got ${JSON.stringify(definition.name)}.`,
+    )
+  }
+  const required = definition.required ?? []
+  const optional = definition.optional ?? []
+  if (!Array.isArray(required) || !required.every(isNonEmptyString)) {
+    throw new TypeError(`operation "${definition.name}" required fields must be an array of strings.`)
+  }
+  if (!Array.isArray(optional) || !optional.every(isNonEmptyString)) {
+    throw new TypeError(`operation "${definition.name}" optional fields must be an array of strings.`)
+  }
+  const overlap = required.filter((field) => optional.includes(field))
+  if (overlap.length > 0) {
+    throw new TypeError(
+      `operation "${definition.name}" declares field(s) as both required and optional: ${overlap.join(', ')}.`,
+    )
+  }
+  if (typeof definition.reducer !== 'function') {
+    throw new TypeError(`operation "${definition.name}" must declare a reducer function.`)
+  }
+}
+
+function freezeOperation(definition) {
+  assertOperationDefinition(definition)
+  return Object.freeze({
+    name: definition.name,
+    namespace: operationNamespace(definition.name),
+    required: Object.freeze([...(definition.required ?? [])]),
+    optional: Object.freeze([...(definition.optional ?? [])]),
+    reducer: definition.reducer,
+  })
+}
+
+function assertLogicalControl(contribution) {
+  if (!isPlainObject(contribution)) {
+    throw new TypeError('logical control must be an object.')
+  }
+  if (contribution.kind !== LOGICAL_CONTROL_KIND) {
+    throw new TypeError(
+      `logical control must declare kind "${LOGICAL_CONTROL_KIND}"; got ${JSON.stringify(contribution.kind)}.`,
+    )
+  }
+  for (const field of ['feature', 'host', 'slot', 'presentation']) {
+    if (!isNonEmptyString(contribution[field])) {
+      throw new TypeError(`logical control must declare a non-empty string "${field}".`)
+    }
+  }
+  if (hasOwn(contribution, 'capability') && !isNonEmptyString(contribution.capability)) {
+    throw new TypeError('logical control "capability" must be a non-empty string when present.')
+  }
+  for (const field of Object.keys(contribution)) {
+    if (LOGICAL_CONTROL_FIELDS.includes(field)) continue
+    if (LOGICAL_CONTROL_FORBIDDEN_FIELDS.includes(field)) {
+      throw new TypeError(
+        `logical control is metadata and must not carry render/behavior field "${field}"; register a whole view in the catalog or a new operation instead.`,
+      )
+    }
+    throw new TypeError(
+      `logical control has unknown field "${field}". Allowed fields: ${LOGICAL_CONTROL_FIELDS.join(', ')}.`,
+    )
+  }
+}
+
+function freezeLogicalControl(contribution) {
+  assertLogicalControl(contribution)
+  const out = {}
+  for (const field of LOGICAL_CONTROL_FIELDS) {
+    if (hasOwn(contribution, field)) out[field] = contribution[field]
+  }
+  return Object.freeze(out)
+}
+
+function freezeRegistry(operations, logicalControls) {
+  return Object.freeze({
+    operations: Object.freeze({ ...operations }),
+    logicalControls: Object.freeze({ ...logicalControls }),
+  })
+}
+
+/**
+ * Build an immutable registry from an extension `{ operations?, logicalControls? }`.
+ * An empty extension yields the empty registry; E1 builds its six operations
+ * from this factory (`scripts/operations.mjs`). Malformed definitions throw a
+ * `TypeError` — this is an internal programming contract, not a user diagnostic.
+ */
+export function createOperationRegistry(extension = {}) {
+  return extendOperationRegistry(freezeRegistry({}, {}), extension)
+}
+
+/**
+ * Return a NEW registry that adds the extension's operations and logical
+ * controls on top of `registry`. The input registry is never mutated, so a
+ * caller's base (production's E1 registry) can never be widened by an
+ * extension. A duplicate operation name or a duplicate `(host, slot)` logical
+ * control throws.
+ */
+export function extendOperationRegistry(registry, extension = {}) {
+  if (
+    !isPlainObject(registry) ||
+    !isPlainObject(registry.operations) ||
+    !isPlainObject(registry.logicalControls)
+  ) {
+    throw new TypeError('extendOperationRegistry requires a registry produced by createOperationRegistry.')
+  }
+  if (!isPlainObject(extension)) {
+    throw new TypeError('operation registry extension must be an object.')
+  }
+  const operations = { ...registry.operations }
+  const logicalControls = { ...registry.logicalControls }
+  for (const definition of extension.operations ?? []) {
+    const frozen = freezeOperation(definition)
+    if (hasOwn(operations, frozen.name)) {
+      throw new TypeError(`operation "${frozen.name}" is already registered; names must be unique.`)
+    }
+    operations[frozen.name] = frozen
+  }
+  for (const contribution of extension.logicalControls ?? []) {
+    const frozen = freezeLogicalControl(contribution)
+    const key = `${frozen.host}.${frozen.slot}`
+    if (hasOwn(logicalControls, key)) {
+      throw new TypeError(
+        `logical control slot "${key}" is already registered; a host slot has one contribution.`,
+      )
+    }
+    logicalControls[key] = frozen
+  }
+  return freezeRegistry(operations, logicalControls)
+}
+
+/** The registered operation names, in registration order (E1's order is stable). */
+export function operationNames(registry) {
+  return Object.keys(registry.operations)
+}
+
+/** The distinct namespaces across the registered operations. */
+export function operationNamespaces(registry) {
+  return [...new Set(operationNames(registry).map(operationNamespace))]
+}
+
+/** The `{ required, optional }` schema of a registered operation, or null. */
+export function operationSchema(registry, name) {
+  const operation = registry.operations[name]
+  return operation
+    ? { required: [...operation.required], optional: [...operation.optional] }
+    : null
+}
+
+/** The canonical field order (required then optional) of a registered operation. */
+export function operationFieldOrder(registry, name) {
+  const operation = registry.operations[name]
+  return operation ? [...operation.required, ...operation.optional] : []
+}
+
+/** The reducer of a registered operation, or null for an unregistered name. */
+export function operationReducer(registry, name) {
+  return registry.operations[name]?.reducer ?? null
+}
+
+/** The registered logical-control contributions as an array. */
+export function logicalControls(registry) {
+  return Object.values(registry.logicalControls)
+}
+
+/** The logical control registered for a host slot, or null. */
+export function logicalControlFor(registry, host, slot) {
+  return registry.logicalControls[`${host}.${slot}`] ?? null
+}