@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

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
+}