@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/scripts/candidate.mjs

@@ -0,0 +1,236 @@
+// The pinned candidate toolset for a generated external storefront.
+//
+// Exact versions only — the scaffolder (`create`), the generated project's
+// runtime dependencies, and the local `@thorprovider/*` packages — so a fresh
+// consumer installs a reproducible, compatible set instead of floating
+// `latest`. The local `@thorprovider/*` packages are consumed from a packed
+// local candidate (a directory of `*.tgz` tarballs) via Yarn `resolutions`
+// while the declared dependency ranges stay honest semver, so M1 needs neither
+// a publish nor a fake workspace import.
+//
+// The concrete versions are real (validated against the monorepo's own install
+// and the npm registry); the actual external build is M1 evidence.
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { gunzipSync } from 'node:zlib'
+
+// The exact compatible set. `runtime` are registry packages; `local` are the
+// monorepo packages that must be packed for an external consumer.
+export const CANDIDATE_TOOLSET = Object.freeze({
+  // The package manager the generated project pins in its `packageManager`
+  // field, so Corepack resolves the canonical Yarn instead of a floating
+  // "known good" release. Must match the monorepo root (drift-tested).
+  packageManager: 'yarn@4.5.1',
+  scaffolder: Object.freeze({
+    createNextApp: '16.2.3',
+    // shadcn 4.21.1 (not 4.21.2/4.21.3) pins @shadcn/registry to the
+    // already-published 0.1.0, so a fresh scaffold installs reproducibly past
+    // Yarn's npmMinimalAgeGate (the newest releases are age-gated).
+    shadcn: '4.21.1',
+  }),
+  runtime: Object.freeze({
+    next: '16.2.3',
+    react: '19.2.5',
+    'react-dom': '19.2.5',
+    'next-themes': '0.4.6',
+    'lucide-react': '1.47.0',
+    motion: '13.4.3',
+    zod: '3.25.76',
+    '@json-render/core': '0.21.0',
+    '@json-render/react': '0.21.0',
+    '@json-render/next': '0.21.0',
+  }),
+  local: Object.freeze({
+    '@thorprovider/blocks': '0.1.2',
+    '@thorprovider/adapters': '5.0.12',
+    '@thorprovider/runtime': '0.1.4',
+    '@thorprovider/types': '5.8.0',
+  }),
+})
+
+/** The monorepo package directories the `local` toolset versions must match. */
+export const LOCAL_PACKAGE_DIRS = Object.freeze({
+  '@thorprovider/blocks': 'blocks',
+  '@thorprovider/adapters': 'adapters',
+  '@thorprovider/runtime': 'runtime',
+  '@thorprovider/types': 'types',
+})
+
+/** `@thorprovider/blocks` -> `thorprovider-blocks` (a `yarn pack` filename slug). */
+export function packSlug(name) {
+  return name.replace(/^@/, '').replace(/\//g, '-')
+}
+
+/**
+ * Find the local tarball for a package in a packs directory. Accepts the
+ * documented `yarn pack --filename <slug>-<version>.tgz` name, a plain
+ * `<slug>.tgz`, or any `.tgz` containing the slug.
+ */
+export function findPack(packsDir, name, version) {
+  if (!existsSync(packsDir)) return null
+  const slug = packSlug(name)
+  const named = [`${slug}-${version}.tgz`, `${slug}.tgz`]
+  for (const file of named) {
+    const abs = join(packsDir, file)
+    if (existsSync(abs)) return abs
+  }
+  for (const entry of readdirSync(packsDir).sort()) {
+    if (entry.endsWith('.tgz') && entry.includes(slug)) return join(packsDir, entry)
+  }
+  return null
+}
+
+/**
+ * Build the exact install plan for a generated storefront.
+ *   - `dependencies`: name -> exact version for every runtime + local package
+ *     (plus the CLI itself), all honest semver.
+ *   - `resolutions`: when `packsDir` is given, name -> `file:<abs>` mapping each
+ *     local `@thorprovider/*` package (and the CLI) to its packed tarball.
+ *   - `missingPacks`: local packages requested but absent from the packs dir.
+ */
+export function buildInstallPlan({ cliVersion, packsDir, toolset = CANDIDATE_TOOLSET } = {}) {
+  const dependencies = {
+    ...toolset.runtime,
+    ...toolset.local,
+    '@thorprovider/storefront': cliVersion,
+  }
+  const resolutions = {}
+  const missingPacks = []
+  if (packsDir) {
+    const local = { ...toolset.local, '@thorprovider/storefront': cliVersion }
+    for (const [name, version] of Object.entries(local)) {
+      const pack = findPack(packsDir, name, version)
+      if (!pack) missingPacks.push(name)
+      else resolutions[name] = `file:${pack}`
+    }
+  }
+  return { dependencies, resolutions, missingPacks, scaffolder: toolset.scaffolder, packageManager: toolset.packageManager }
+}
+
+/** Read the actual version of a sibling monorepo package (drift guard). */
+export function readLocalPackageVersion(repoPackagesDir, name) {
+  const dir = LOCAL_PACKAGE_DIRS[name]
+  if (!dir) return null
+  const pkgPath = join(repoPackagesDir, dir, 'package.json')
+  if (!existsSync(pkgPath)) return null
+  return JSON.parse(readFileSync(pkgPath, 'utf8')).version
+}
+
+/**
+ * Read the regular-file entries of a `.tgz` (gzipped tar) into a
+ * `path -> Buffer` map. A dependency-free reader (the candidate guard must run
+ * in a bare Node process, before any install). It understands the ustar header
+ * (name/size/type) and skips directories, symlinks, and pax/global headers —
+ * enough for a `yarn pack` tarball, whose paths are all short.
+ */
+export function readPackEntries(tgzPath) {
+  let raw
+  try {
+    raw = gunzipSync(readFileSync(tgzPath))
+  } catch {
+    return null
+  }
+  const entries = {}
+  let offset = 0
+  while (offset + 512 <= raw.length) {
+    const header = raw.subarray(offset, offset + 512)
+    // A zero block marks the end of the archive.
+    if (header.every((b) => b === 0)) break
+    const name = header.subarray(0, 100).toString('utf8').replace(/\0.*$/, '')
+    const sizeField = header.subarray(124, 136).toString('utf8').replace(/\0.*$/, '').trim()
+    const size = sizeField ? parseInt(sizeField, 8) : 0
+    const type = String.fromCharCode(header[156])
+    const dataStart = offset + 512
+    if (type === '0' || type === '\0' || type === '') {
+      entries[name] = raw.subarray(dataStart, dataStart + size)
+    }
+    offset = dataStart + Math.ceil(size / 512) * 512
+  }
+  return entries
+}
+
+/** Parse `package/package.json` out of a packed tarball, or null. */
+export function readPackManifest(tgzPath) {
+  const entries = readPackEntries(tgzPath)
+  const pkg = entries && entries['package/package.json']
+  if (!pkg) return null
+  try {
+    return JSON.parse(pkg.toString('utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Guard a packed local candidate before it is trusted for an install: its
+ * declared `name` and `version` MUST match the pinned toolset. A stale tarball
+ * that kept its old version (or a wrong file matched by slug) is rejected here
+ * instead of producing a half-broken generated project.
+ */
+export function verifyPackManifest({ tgzPath, name, version }) {
+  if (!tgzPath || !existsSync(tgzPath)) {
+    return { ok: false, code: 'E_PACK_MISSING', message: `no packed candidate found for ${name}@${version}` }
+  }
+  const manifest = readPackManifest(tgzPath)
+  if (!manifest) {
+    return { ok: false, code: 'E_PACK_UNREADABLE', message: `cannot read ${tgzPath} as a package tarball` }
+  }
+  if (manifest.name !== name) {
+    return { ok: false, code: 'E_PACK_NAME_MISMATCH', message: `${tgzPath} declares ${manifest.name}, expected ${name}` }
+  }
+  if (manifest.version !== version) {
+    return {
+      ok: false,
+      code: 'E_PACK_VERSION_MISMATCH',
+      message: `${tgzPath} declares ${manifest.name}@${manifest.version}, expected ${version} — repack the candidate`,
+    }
+  }
+  return { ok: true }
+}
+
+/**
+ * Guard the runtime surface a generated host actually imports: every named
+ * import the storefront template pulls from `@thorprovider/runtime/commerce`
+ * MUST exist in the packed runtime build. This catches a same-version stale
+ * tarball whose source predates a new export (the failure a version bump alone
+ * cannot see).
+ */
+export function verifyPackExports({ tgzPath, innerPath, requiredExports }) {
+  const entries = readPackEntries(tgzPath)
+  if (!entries) {
+    return { ok: false, code: 'E_PACK_UNREADABLE', message: `cannot read ${tgzPath} as a package tarball` }
+  }
+  const file = entries[innerPath]
+  if (!file) {
+    return { ok: false, code: 'E_PACK_FILE_MISSING', message: `${tgzPath} is missing ${innerPath}` }
+  }
+  const source = file.toString('utf8')
+  const missing = requiredExports.filter((sym) => !new RegExp(`\\b${sym}\\b`).test(source))
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      code: 'E_RUNTIME_SURFACE_MISMATCH',
+      message: `${tgzPath} is missing runtime export(s): ${missing.join(', ')} — repack the candidate`,
+    }
+  }
+  return { ok: true }
+}
+
+/**
+ * Extract the value-import names a template takes from
+ * `@thorprovider/runtime/commerce` (type-only imports are ignored — they
+ * compile away and need no runtime symbol).
+ */
+export function parseRuntimeCommerceImports(source) {
+  const block = source.match(/import\s*\{([\s\S]*?)\}\s*from\s*['"]@thorprovider\/runtime\/commerce['"]/)
+  if (!block) return []
+  return block[1]
+    .replace(/\/\/[^\n]*/g, '')
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .filter((entry) => !/^type\s/.test(entry))
+    .map((entry) => entry.replace(/^type\s+/, '').split(/\s+as\s+/)[0].trim())
+    .filter(Boolean)
+}

package/scripts/composers.mjs

@@ -0,0 +1,160 @@
+// Builders for the composition composers.
+//
+// `state.ts` and `handlers.ts` are not templates: they are generated from the
+// manifest's feature list so that adding or removing a feature is a manifest
+// edit plus a regenerate. Each installed feature ships a fragment under
+// `features/<name>/`; the composer imports only the installed fragments.
+
+/** `order-summary` -> `orderSummary`. */
+export function toCamel(name) {
+  return name.replace(/-([a-z0-9])/g, (_, char) => char.toUpperCase())
+}
+
+/** `order-summary` -> `OrderSummary`. */
+export function toPascal(name) {
+  return name
+    .split('-')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+}
+
+/**
+ * Build the `state.ts` composer: spread every installed feature's state slice
+ * over the core state. Re-exports the core module so views keep importing types.
+ */
+export function buildStateComposer(featureNames) {
+  const names = [...featureNames].sort()
+  const imports = names
+    .map((name) => `import { ${toCamel(name)}State } from './features/${name}/state'`)
+    .join('\n')
+  const spreads = names.map((name) => `  ...${toCamel(name)}State,`).join('\n')
+  return (
+    `// Generated by Thor Commerce storefront (composition composer: state).\n` +
+    `// Do not edit by hand — the manifest is the source of truth; run \`storefront sync\`.\n` +
+    `// Installed features contribute their state slices below.\n\n` +
+    `import { storefrontCoreState } from './state.core'\n` +
+    (imports ? `${imports}\n\n` : '\n') +
+    `export * from './state.core'\n\n` +
+    `export const storefrontInitialState = {\n` +
+    `  ...storefrontCoreState,\n` +
+    (spreads ? `${spreads}\n` : '') +
+    `}\n`
+  )
+}
+
+/**
+ * Build a feature's `adapter.ts`: a pure declaration of the commerce adapter
+ * capabilities the feature needs. The purchase implementation is owned by the
+ * commerce change; this file only records the structural dependency so the
+ * feature bundle is complete without it.
+ */
+export function buildFeatureAdapter(featureName, needs = []) {
+  const camel = toCamel(featureName)
+  const pascal = toPascal(featureName)
+  const list = needs.map((need) => `'${need}'`).join(', ')
+  return (
+    `// Generated by Thor Commerce storefront (feature: ${featureName} — adapter needs).\n` +
+    `// The commerce adapter capabilities this feature requires. The purchase\n` +
+    `// implementation is owned by the commerce change; this file only records the\n` +
+    `// structural dependency so the feature wiring is complete without it.\n\n` +
+    `export const ${camel}AdapterNeeds = [${list}] as const\n` +
+    `export type ${pascal}AdapterNeed = (typeof ${camel}AdapterNeeds)[number]\n`
+  )
+}
+
+/**
+ * The catalog capability features the URL boundary understands. The generated
+ * `mountedFeatures` is the intersection of this set with the installed manifest
+ * features — never a hardcoded always-mounted list. The boundary's
+ * `CatalogFeatureName` union is the type authority for this set.
+ */
+const CATALOG_FEATURE_NAMES = ['catalog-search', 'category-filters']
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Build the `composition.ts` composer: the installed manifest catalog features
+ * in stable order, plus their persisted config. This is the generation seam the
+ * catalog URL boundary consumes to reject parameters owned by a feature that is
+ * not installed, and the seam the single controlled `CategoryFilter2` reads to
+ * select its control visibility/config from the installed manifest only. It is
+ * derived from the manifest — never hardcoded as always-mounted.
+ *
+ * `features` accepts bare names or `{ name, config }` entries (the fresh
+ * scaffold and a later reconcile both pass manifest entries). `views` accepts
+ * bare view names or `{ name }` entries; it drives the typed route/action
+ * availability flags below so the generated host can suppress links to routes
+ * that are not installed (e.g. the cart review page or checkout).
+ */
+export function buildCompositionComposer(features, views = []) {
+  const entries = (Array.isArray(features) ? features : []).map((feature) =>
+    typeof feature === 'string' ? { name: feature, config: {} } : feature,
+  )
+  const installed = new Set(entries.map((entry) => entry.name))
+  const viewNames = (Array.isArray(views) ? views : []).map((view) =>
+    typeof view === 'string' ? view : view.name,
+  )
+  const installedViews = new Set(viewNames)
+  const cartViewAvailable = installedViews.has('cart')
+  const checkoutAvailable = installed.has('checkout') || installedViews.has('checkout')
+  const names = CATALOG_FEATURE_NAMES.filter((name) => installed.has(name))
+  const list = names.map((name) => JSON.stringify(name)).join(', ')
+  const installedNames = [...installed].sort()
+  const featureNameList = installedNames.map((name) => JSON.stringify(name)).join(', ')
+  const configLines = installedNames
+    .map((name) => {
+      const entry = entries.find((candidate) => candidate.name === name)
+      const config = entry && isPlainObject(entry.config) ? entry.config : {}
+      return `  ${JSON.stringify(name)}: ${JSON.stringify(config)},`
+    })
+    .join('\n')
+  return (
+    `// Generated by Thor Commerce storefront (composition composer: features).\n` +
+    `// Do not edit by hand — the manifest is the source of truth; run \`storefront sync\`.\n` +
+    `// Installed manifest catalog features, in stable order, with their persisted\n` +
+    `// config. This is the generation seam the catalog URL boundary consumes to\n` +
+    `// reject parameters owned by a feature that is not installed, and the seam the\n` +
+    `// single controlled CategoryFilter2 reads to select its control\n` +
+    `// visibility/config from the installed manifest only.\n\n` +
+    `import type { CatalogFeatureName } from '@thorprovider/runtime/contracts'\n\n` +
+    `export const mountedFeatures: readonly CatalogFeatureName[] = [${list}]\n\n` +
+    `// Every installed feature name, unfiltered by the catalog URL boundary. The\n` +
+    `// general presence seam cross-cutting features read to gate their own\n` +
+    `// contributions (e.g. the navigability feature's shell chrome).\n` +
+    `export const mountedFeatureNames: readonly string[] = [${featureNameList}]\n\n` +
+    `export const mountedFeatureConfigs: Partial<Record<string, Record<string, unknown>>> = {\n` +
+    `${configLines ? `${configLines}\n` : ''}` +
+    `}\n\n` +
+    `// Typed route/action availability derived from the installed manifest. The\n` +
+    `// generated host uses these to hide links to routes that are not installed,\n` +
+    `// so a removed view never leaves an active dead-end navigation target.\n` +
+    `export const cartViewAvailable = ${cartViewAvailable}\n\n` +
+    `export const checkoutAvailable = ${checkoutAvailable}\n`
+  )
+}
+
+/**
+ * Build the `handlers.ts` composer: call the core handlers hook plus every
+ * installed feature's handlers hook.
+ */
+export function buildHandlersComposer(featureNames) {
+  const names = [...featureNames].sort()
+  const imports = names
+    .map((name) => `import { use${toPascal(name)}Handlers } from './features/${name}/handlers'`)
+    .join('\n')
+  const calls = names.map((name) => `  use${toPascal(name)}Handlers()`).join('\n')
+  return (
+    `'use client'\n\n` +
+    `// Generated by Thor Commerce storefront (composition composer: handlers).\n` +
+    `// Do not edit by hand — the manifest is the source of truth; run \`storefront sync\`.\n` +
+    `// Installed features contribute their handlers below.\n\n` +
+    `import { useCoreHandlers } from './handlers.core'\n` +
+    (imports ? `${imports}\n\n` : '\n') +
+    `export function useStorefrontHandlers() {\n` +
+    `  useCoreHandlers()\n` +
+    (calls ? `${calls}\n` : '') +
+    `}\n`
+  )
+}

package/scripts/env-file.mjs

@@ -0,0 +1,86 @@
+// Environment-file helpers for the scaffold.
+//
+// `create` starts a storefront in mock mode with a minimal, working `.env.local`
+// and never writes a blank `MEDUSA_*` value; `setup` later upserts the real-backend
+// keys without disturbing anything else in the file. Both behaviours are pure
+// enough to unit-test here rather than only through the network-heavy create path.
+import { existsSync, readFileSync } from 'node:fs'
+import { writeFile } from 'node:fs/promises'
+import { randomBytes } from 'node:crypto'
+import { join } from 'node:path'
+
+// The minimal mock environment `create` writes: an explicit mock data source, the
+// store identity, and the per-install session secret the guest cart and checkout
+// cookie signing requires. No backend key is written here.
+export function initialEnvLocal(name, sessionSecret) {
+  return [
+    'THOR_DATA_SOURCE=mock',
+    `THOR_STORE_ID=${name}`,
+    `THOR_SESSION_SECRET=${sessionSecret}`,
+  ].join('\n') + '\n'
+}
+
+// The committed example documenting both modes. The real-backend keys are blank
+// placeholders — `storefront setup` fills them.
+export function envExample(name) {
+  return [
+    '# Data source: "mock" for explicit demo data (no backend needed), "medusa" for a real backend.',
+    'THOR_DATA_SOURCE=mock',
+    '# Store identity (written by create; required only in real mode).',
+    `THOR_STORE_ID=${name}`,
+    '# Real backend configuration (required only when THOR_DATA_SOURCE=medusa).',
+    '# Run `storefront setup` to write these: it takes the sales channel id (from the',
+    '# Medusa admin) and derives the currency from the selected region.',
+    'MEDUSA_BASE_URL=http://localhost:9000',
+    'MEDUSA_PUBLISHABLE_KEY=',
+    'MEDUSA_REGION_ID=',
+    'MEDUSA_SALES_CHANNEL_ID=',
+    'MEDUSA_CURRENCY_CODE=',
+    '# Host-only cookie signing secret; >=16 chars, 32 recommended. Generated by create.',
+    'THOR_SESSION_SECRET=',
+  ].join('\n') + '\n'
+}
+
+// Write the initial `.env.local` only when one is absent (an existing file is
+// user-owned — a `setup` run or a hand edit — and is never clobbered), and always
+// refresh the committed `.env.example`. Returns whether `.env.local` was written.
+export async function writeInitialEnv(target, name) {
+  const envPath = join(target, '.env.local')
+  let wrote = false
+  if (!existsSync(envPath)) {
+    const sessionSecret = randomBytes(32).toString('base64url')
+    await writeFile(envPath, initialEnvLocal(name, sessionSecret), 'utf8')
+    wrote = true
+  }
+  await writeFile(join(target, '.env.example'), envExample(name), 'utf8')
+  return wrote
+}
+
+// Replace the managed keys in a dotenv-style file, appending any that are absent,
+// and leave every other line (comments, blank lines, unrelated keys) exactly as it
+// was. Idempotent: re-running with the same values produces the same file.
+export function upsertEnv(text, managed) {
+  const seen = new Set()
+  const lines = text.length ? text.split('\n') : []
+  const out = lines.map((line) => {
+    const match = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line)
+    if (match && Object.prototype.hasOwnProperty.call(managed, match[1])) {
+      seen.add(match[1])
+      return `${match[1]}=${managed[match[1]]}`
+    }
+    return line
+  })
+  const missing = Object.keys(managed).filter((key) => !seen.has(key))
+  // Drop trailing blank lines before appending so re-runs do not accumulate them.
+  while (out.length && out[out.length - 1] === '') out.pop()
+  if (missing.length) {
+    if (out.length) out.push('')
+    for (const key of missing) out.push(`${key}=${managed[key]}`)
+  }
+  return out.join('\n') + '\n'
+}
+
+// Read a dotenv file as text, or '' when it does not exist.
+export function readEnvFile(path) {
+  return existsSync(path) ? readFileSync(path, 'utf8') : ''
+}

package/scripts/file-classes.mjs

@@ -0,0 +1,121 @@
+// File classification for reconcile.
+//
+// Every file the workflow touches is exactly one of:
+//   - external   — create-next-app / shadcn base; only idempotent marker appends
+//   - user-owned — content, props, copy, local schemas, mapper bodies; never rewritten
+//   - derived    — regenerated from the manifest on every reconcile
+//
+// Paths are relative to the template root (assets/templates), using forward slashes.
+
+import { readdirSync } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+
+export const FILE_CLASSES = {
+  derived: 'derived',
+  userOwned: 'user-owned',
+  external: 'external',
+}
+
+const RULES = [
+  {
+    class: FILE_CLASSES.external,
+    patterns: [
+      'app/app/layout.tsx',
+      'app/app/globals.css',
+      'app/app/sitemap.ts',
+      'app/app/robots.ts',
+    ],
+  },
+  {
+    class: FILE_CLASSES.userOwned,
+    patterns: [
+      'views/*/schema.ts',
+      'views/*/content.ts',
+      'views/*/props.ts',
+      'views/*/data.ts',
+      'app/lib/*/mappers.ts',
+      'app/lib/*/icon-map.ts',
+      // The shell brand/newsletter seam is user-owned so its edits survive sync.
+      'app/lib/*/shell/**',
+    ],
+  },
+  {
+    class: FILE_CLASSES.derived,
+    patterns: [
+      // The managed root guidance file is rendered from the package template,
+      // refreshed by sync, and drift-checked by doctor — never hand-edited.
+      'AGENTS.md',
+      'app/app/[[...slug]]/**',
+      'app/lib/*/handlers.ts',
+      'app/lib/*/handlers.core.ts',
+      'app/lib/*/state.ts',
+      'app/lib/*/state.core.ts',
+      'app/lib/*/composition.ts',
+      'app/lib/*/session.ts',
+      'app/lib/*/session.core.ts',
+      'app/lib/*/store-context.ts',
+      'app/lib/*/commerce.ts',
+      'app/lib/*/cart-state.ts',
+      'app/lib/*/actions.ts',
+      'app/lib/*/catalog.ts',
+      'app/lib/*/section-sources.ts',
+      'app/lib/*/section-observation.ts',
+      'app/lib/*/runtime.ts',
+      'app/lib/*/registry.tsx',
+      'app/lib/*/schema.ts',
+      'app/lib/*/spec/**',
+      'app/lib/*/views/**',
+      'features/**',
+      'views/*/index.tsx',
+      'views/*/registry.tsx',
+      // The views-root barrels are generated by reconcile (buildBarrel /
+      // buildClientRegistryBarrel), not copied from a view template. Their
+      // canonical template paths are app/lib/*/views/{index,registry}.ts, but
+      // projectIdentity maps a project's lib/<name>/views/* to the views/
+      // namespace, so the generated barrels must be classified here too or they
+      // default to user-owned in the identity domain (E1 task 4.4).
+      'views/index.ts',
+      'views/registry.ts',
+      // Per-slot/per-variant assembly sources compose the derived index/registry;
+      // they are authoring input and are never copied into a project.
+      'views/*/assembly/**',
+    ],
+  },
+].map((rule) => ({ class: rule.class, regexes: rule.patterns.map(globToRegExp) }))
+
+function globToRegExp(glob) {
+  const placeholders = glob.replace(/\*\*/g, '\u0001').replace(/\*/g, '\u0002')
+  const escaped = placeholders.replace(/[.+^${}()|[\]\\?]/g, '\\$&')
+  const source = escaped.replace(/\u0001/g, '.*').replace(/\u0002/g, '[^/]*')
+  return new RegExp(`^${source}$`)
+}
+
+function normalize(relPath) {
+  return relPath.split(sep).join('/')
+}
+
+/**
+ * Every class whose pattern matches the path. Well-formed template sets yield
+ * exactly one; more than one signals overlapping rules.
+ */
+export function classifyFileAll(relPath) {
+  const path = normalize(relPath)
+  return RULES.filter((rule) => rule.regexes.some((re) => re.test(path))).map((rule) => rule.class)
+}
+
+export function classifyFile(relPath) {
+  return classifyFileAll(relPath)[0] ?? null
+}
+
+export function listTemplateFiles(root) {
+  const files = []
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name)
+      if (entry.isDirectory()) walk(full)
+      else files.push(normalize(relative(root, full)))
+    }
+  }
+  walk(root)
+  return files.sort()
+}

package/scripts/logical-controls.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// E2 task 6.1 (CU-11): the catalog search/filter logical-control metadata.
+//
+// WHY THIS EXISTS: `scripts/operation-registry.mjs` is E1's additive seam for
+// logical-control metadata (a control slot that contributes to one already
+// rendered presentation). E1 registers none in production; E2 owns the two
+// catalog controls and registers them here. Generation consumes this registry
+// through `logicalControlFor(registry, host, slot)` so a mount registered as a
+// logical control is a contribution to the host's single presentation — not a
+// variant swap — and the presentation/variant requirement is skipped for exactly
+// those mounts (E2 design Decision 2c / the task 6.3 M2 resolution).
+//
+// This is metadata only: no new operation, no block, no element. The base
+// listing (`category.filter` rendering the one controlled `CategoryFilter2`)
+// stays the view default; these controls only toggle visibility on it.
+//
+// IMPORT-CYCLE NOTE: this module is a LEAF. It deliberately does not import
+// `operations.mjs` (which reaches `view-selection.mjs` through
+// `preflight.mjs -> render-templates.mjs`); the generation lookup only needs the
+// logical-control metadata, not E1's operation vocabulary. The full production
+// registry (E1's six operations + these controls) is built in `operations.mjs`.
+
+import {
+  LOGICAL_CONTROL_KIND,
+  createOperationRegistry,
+  logicalControlFor,
+} from './operation-registry.mjs'
+
+/** The two E2 control contributions to the single `CategoryFilter2` listing. */
+export const CATALOG_LOGICAL_CONTROLS = Object.freeze([
+  Object.freeze({
+    kind: LOGICAL_CONTROL_KIND,
+    feature: 'catalog-search',
+    host: 'category',
+    slot: 'search',
+    presentation: 'CategoryFilter2',
+    capability: 'category.search.apply',
+  }),
+  Object.freeze({
+    kind: LOGICAL_CONTROL_KIND,
+    feature: 'category-filters',
+    host: 'category',
+    slot: 'filters',
+    presentation: 'CategoryFilter2',
+    capability: 'category.filter.apply',
+  }),
+])
+
+/**
+ * A controls-only registry built from the same additive seam. Generation reads
+ * it through `logicalControlForMount`; the operation vocabulary is irrelevant to
+ * that lookup, so this registry carries no operations.
+ */
+export const CATALOG_LOGICAL_CONTROL_REGISTRY = createOperationRegistry({
+  logicalControls: CATALOG_LOGICAL_CONTROLS,
+})
+
+/** The logical control registered for a host slot, or null. */
+export function logicalControlForMount(host, slot) {
+  return logicalControlFor(CATALOG_LOGICAL_CONTROL_REGISTRY, host, slot)
+}