@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/scripts/preflight.mjs

@@ -0,0 +1,51 @@
+// Shared preflight for every structural write boundary.
+//
+// A composition is only accepted once it passes all layers:
+//   1. shape — the manifest validates against the published JSON Schema
+//      (`recipes/manifest.schema.json`),
+//   2. path safety — the project name is joined into filesystem paths
+//      (`lib/<name>/...`), so it must satisfy the same kebab-case contract the
+//      CLI produces (`toKebab`), and
+//   3. semantics — every unit, variant, slot, section, and feature/view
+//      dependency resolves against the registry (`recipes/validate.mjs`).
+//
+// Callers MUST reject (write nothing) when the result is not ok.
+
+import { validateManifest } from './manifest.mjs'
+import { validateCompositionManifest } from '../recipes/validate.mjs'
+import { isValidIdentifier } from './render-templates.mjs'
+import { toCamel } from './composers.mjs'
+
+// Mirrors `toKebab` output in scripts/render-templates.mjs: lowercase letters,
+// digits, and single hyphens. `manifest.name` is joined into paths by
+// `reconcile`, so a value like "../escape" must never reach a write.
+const SAFE_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+export function preflightManifest(manifest, options = {}) {
+  const shape = validateManifest(manifest)
+  if (!shape.ok) return shape
+
+  const errors = []
+  if (typeof manifest.name === 'string' && !SAFE_NAME.test(manifest.name)) {
+    errors.push(
+      `Manifest "name" must be a kebab-case identifier (lowercase letters, digits, and single hyphens): got "${manifest.name}".`
+    )
+  }
+
+  // Every installed unit becomes an exported binding in generated wiring
+  // (views barrel, feature composers). Reject any name that cannot yield a
+  // valid JS identifier before a derived file is written.
+  for (const view of manifest.views) {
+    if (!isValidIdentifier(toCamel(view.name))) {
+      errors.push(`View "${view.name}" does not yield a valid export identifier.`)
+    }
+  }
+  for (const feature of manifest.features) {
+    if (!isValidIdentifier(toCamel(feature.name))) {
+      errors.push(`Feature "${feature.name}" does not yield a valid export identifier.`)
+    }
+  }
+
+  const semantic = validateCompositionManifest(manifest, options)
+  return { ok: errors.length === 0 && semantic.ok, errors: [...errors, ...semantic.errors] }
+}

package/scripts/reconcile.mjs

@@ -0,0 +1,549 @@
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  templatesRoot,
+  replacePlaceholders,
+  buildBarrel,
+  writeBarrel,
+  buildClientRegistryBarrel,
+  writeClientRegistryBarrel,
+  injectLayout,
+  migrateLayoutInjection,
+  injectThemeMode,
+  injectGlobals,
+} from './render-templates.mjs'
+import { buildStateComposer, buildHandlersComposer, buildCompositionComposer, buildFeatureAdapter } from './composers.mjs'
+import { hasViewAssembly, isAssemblyRel, writeViewAssembly } from './view-assembly.mjs'
+import {
+  resolveFeatureMountOverrides,
+  resolveViewGenerationSelection,
+} from './view-selection.mjs'
+import { classifyFile } from './file-classes.mjs'
+import { DEFAULT_THEME_MODE } from './manifest.mjs'
+import { preflightManifest } from './preflight.mjs'
+import { allowedViewNames, getFeature } from '../recipes/validate.mjs'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const pkgRoot = path.resolve(here, '..')
+const VIEW_GEN_VIEWS = path.join(pkgRoot, 'skills', 'sf-view-gen', 'assets', 'templates', 'views')
+
+// Resolve the template directory for a view: the scaffold templates first, then
+// the view-generator skill's vendored copy (the four non-home views live there
+// until they are unified under assets/templates/views).
+export function viewTemplateDir(name) {
+  const primary = path.join(templatesRoot, 'views', name)
+  if (existsSync(primary)) return primary
+  const vendored = path.join(VIEW_GEN_VIEWS, name)
+  if (existsSync(vendored)) return vendored
+  return null
+}
+
+async function walkFiles(dir, base = dir, out = []) {
+  const entries = await readdir(dir, { withFileTypes: true })
+  for (const entry of entries) {
+    const abs = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      await walkFiles(abs, base, out)
+    } else {
+      out.push(path.relative(base, abs))
+    }
+  }
+  return out
+}
+
+// Render a template tree into the project, writing every derived file but only
+// seeding user-owned files that do not exist yet, so reconcile never clobbers a
+// hand edit. `classifyRel` maps a template-relative path to its file class.
+// With `dryRun`, no file is written; `changed` still lists the files that would
+// change, so callers (doctor) can report drift without mutating the project.
+async function renderDerivedTree(fromDir, toDir, subs, classifyRel, changed, skip, dryRun) {
+  if (!existsSync(fromDir)) return
+  const files = await walkFiles(fromDir)
+  for (const rel of files) {
+    if (skip && skip(rel)) continue
+    const dest = path.join(toDir, rel.replaceAll('__STOREFRONT__', subs.name))
+    const fileClass = classifyRel(rel)
+    if (fileClass === 'user-owned' && existsSync(dest)) continue
+    const raw = await readFile(path.join(fromDir, rel), 'utf8')
+    const next = replacePlaceholders(raw, subs)
+    const prev = existsSync(dest) ? await readFile(dest, 'utf8') : null
+    if (prev === next) continue
+    if (!dryRun) {
+      await mkdir(path.dirname(dest), { recursive: true })
+      await writeFile(dest, next)
+    }
+    changed.push(dest)
+  }
+}
+
+async function ensureLayoutAppend(targetDir, name, siteName, mode, dryRun) {
+  const layoutPath = path.join(targetDir, 'app', 'layout.tsx')
+  if (!existsSync(layoutPath)) {
+    if (dryRun) return { changed: true, conflict: null }
+    const raw = await readFile(path.join(templatesRoot, 'app', 'app', 'layout.tsx'), 'utf8')
+    const content = injectThemeMode(replacePlaceholders(raw, { name, siteName, mode }), mode)
+    await mkdir(path.dirname(layoutPath), { recursive: true })
+    await writeFile(layoutPath, content)
+    return { changed: true, conflict: null }
+  }
+  const existing = await readFile(layoutPath, 'utf8')
+  // Migrate the recognized default-palette injection (CSS owns the theme now).
+  // A custom injection is reported as a conflict and nothing is written.
+  const migration = migrateLayoutInjection(existing)
+  if (migration.conflict) return { changed: false, conflict: migration.conflict }
+  const content = injectThemeMode(injectLayout(migration.content, name), mode)
+  if (content === existing) return { changed: false, conflict: null }
+  if (!dryRun) await writeFile(layoutPath, content)
+  return { changed: true, conflict: null }
+}
+
+async function ensureGlobalsAppend(targetDir, name, siteName, dryRun) {
+  const globalsPath = path.join(targetDir, 'app', 'globals.css')
+  if (!existsSync(globalsPath)) {
+    if (dryRun) return true
+    const raw = await readFile(path.join(templatesRoot, 'app', 'app', 'globals.css'), 'utf8')
+    const content = injectGlobals(replacePlaceholders(raw, { name, siteName }))
+    await mkdir(path.dirname(globalsPath), { recursive: true })
+    await writeFile(globalsPath, content)
+    return true
+  }
+  const existing = await readFile(globalsPath, 'utf8')
+  const content = injectGlobals(existing)
+  if (content === existing) return false
+  if (!dryRun) await writeFile(globalsPath, content)
+  return true
+}
+
+// Seed a storefront-owned app-root file once, like layout.tsx/globals.css: when
+// the target is absent it is written from the template; an existing file (a
+// store's customization) is never overwritten. Returns whether it wrote.
+async function ensureSeedFile(targetDir, relFromApp, subs, dryRun) {
+  const destPath = path.join(targetDir, 'app', relFromApp)
+  if (existsSync(destPath)) return false
+  if (dryRun) return true
+  const raw = await readFile(path.join(templatesRoot, 'app', 'app', relFromApp), 'utf8')
+  await mkdir(path.dirname(destPath), { recursive: true })
+  await writeFile(destPath, replacePlaceholders(raw, subs))
+  return true
+}
+
+async function pruneEmptyDirs(dir) {
+  if (!existsSync(dir)) return
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) await pruneEmptyDirs(path.join(dir, entry.name))
+  }
+  if ((await readdir(dir)).length === 0) await rm(dir, { recursive: true, force: true })
+}
+
+// Remove a view's files when the view leaves the manifest. Nothing the user
+// could have authored is silently deleted: a user-owned file that differs from
+// the pristine template (i.e. was customized) and any file with no shipped
+// template (unknown) are preserved, and their locations are returned so the
+// caller can report them. A pristine template file is removed so a pure
+// add/remove round-trip restores the tree exactly.
+export async function removeViewFiles(
+  projectDir,
+  manifest,
+  viewName,
+  { dryRun = false, legacyDerivedFiles = null } = {},
+) {
+  const name = manifest.name
+  const viewDir = path.join(projectDir, 'lib', name, 'views', viewName)
+  if (!existsSync(viewDir)) return { removed: [], preserved: [] }
+  const subs = {
+    name,
+    siteName: manifest.siteName ?? name,
+    mode: manifest.theme?.mode ?? DEFAULT_THEME_MODE,
+  }
+  const templateDir = viewTemplateDir(viewName)
+  // A retired view's template no longer exists, so its old derived files would
+  // otherwise be treated as unknown and preserved. An explicit bounded list
+  // marks exactly those derived files as known (and therefore removable); a
+  // user-owned or unknown file is still preserved by the class check below.
+  const legacySet = new Set(Array.isArray(legacyDerivedFiles) ? legacyDerivedFiles : [])
+  const removed = []
+  const preserved = []
+  for (const rel of await walkFiles(viewDir)) {
+    const abs = path.join(viewDir, rel)
+    const posixRel = rel.split(path.sep).join('/')
+    const fileClass = classifyFile(path.posix.join('views', viewName, posixRel))
+    const templatePath = templateDir ? path.join(templateDir, rel) : null
+    const known = Boolean((templatePath && existsSync(templatePath)) || legacySet.has(posixRel))
+    const maybeAuthored = !known || fileClass === 'user-owned'
+    if (maybeAuthored) {
+      let pristine = false
+      if (known && fileClass === 'user-owned') {
+        const rendered = replacePlaceholders(await readFile(templatePath, 'utf8'), subs)
+        pristine = (await readFile(abs, 'utf8')) === rendered
+      }
+      if (!pristine) {
+        preserved.push(abs)
+        continue
+      }
+    }
+    if (!dryRun) await rm(abs, { force: true })
+    removed.push(abs)
+  }
+  if (!dryRun) await pruneEmptyDirs(viewDir)
+  const toProjectRel = (abs) => path.relative(projectDir, abs)
+  return { removed: removed.map(toProjectRel), preserved: preserved.map(toProjectRel) }
+}
+
+// Read-only: the user-owned files of a view that differ from their pristine
+// template render (i.e. were customized), as project-relative paths. A feature
+// instance mount claims a slot of its host view; removing the feature does not
+// remove the host view, so the slot's user-owned content stays on disk. This
+// lets the caller report where that content remains (E1 task 3.4 / CU-06)
+// without removing or rewriting anything.
+export async function customizedViewFiles(projectDir, manifest, viewName) {
+  const name = manifest.name
+  const viewDir = path.join(projectDir, 'lib', name, 'views', viewName)
+  if (!existsSync(viewDir)) return []
+  const subs = {
+    name,
+    siteName: manifest.siteName ?? name,
+    mode: manifest.theme?.mode ?? DEFAULT_THEME_MODE,
+  }
+  const templateDir = viewTemplateDir(viewName)
+  const customized = []
+  for (const rel of await walkFiles(viewDir)) {
+    const posixRel = rel.split(path.sep).join('/')
+    if (classifyFile(path.posix.join('views', viewName, posixRel)) !== 'user-owned') continue
+    const abs = path.join(viewDir, rel)
+    const templatePath = templateDir ? path.join(templateDir, rel) : null
+    if (!templatePath || !existsSync(templatePath)) {
+      customized.push(path.relative(projectDir, abs))
+      continue
+    }
+    const rendered = replacePlaceholders(await readFile(templatePath, 'utf8'), subs)
+    if ((await readFile(abs, 'utf8')) !== rendered) customized.push(path.relative(projectDir, abs))
+  }
+  return customized
+}
+
+// Remove a feature's files when the feature leaves the manifest. A file that
+// does not match a shipped template (customized or unknown) is preserved and
+// its location returned; pristine template files and the generated adapter are
+// removed so a pure add/remove round-trip restores the tree exactly.
+export async function removeFeatureFiles(projectDir, manifest, featureName, { dryRun = false } = {}) {
+  const name = manifest.name
+  const featureDir = path.join(projectDir, 'lib', name, 'features', featureName)
+  if (!existsSync(featureDir)) return { removed: [], preserved: [] }
+  const subs = {
+    name,
+    siteName: manifest.siteName ?? name,
+    mode: manifest.theme?.mode ?? DEFAULT_THEME_MODE,
+  }
+  const templateDir = path.join(templatesRoot, 'features', featureName)
+  const removed = []
+  const preserved = []
+  for (const rel of await walkFiles(featureDir)) {
+    const abs = path.join(featureDir, rel)
+    const posixRel = rel.split(path.sep).join('/')
+    if (posixRel === 'adapter.ts') {
+      if (!dryRun) await rm(abs, { force: true })
+      removed.push(abs)
+      continue
+    }
+    const templatePath = path.join(templateDir, rel)
+    let pristine = false
+    if (existsSync(templatePath)) {
+      const rendered = replacePlaceholders(await readFile(templatePath, 'utf8'), subs)
+      pristine = (await readFile(abs, 'utf8')) === rendered
+    }
+    if (!pristine) {
+      preserved.push(abs)
+      continue
+    }
+    if (!dryRun) await rm(abs, { force: true })
+    removed.push(abs)
+  }
+  if (!dryRun) await pruneEmptyDirs(featureDir)
+  const toProjectRel = (abs) => path.relative(projectDir, abs)
+  return { removed: removed.map(toProjectRel), preserved: preserved.map(toProjectRel) }
+}
+
+// Reconcile a storefront project to its manifest: regenerate every derived
+// structural file from the versioned templates, seed any missing user-owned
+// file, and leave existing user-owned files untouched. Idempotent by design.
+export async function reconcile(projectDir, manifest, { dryRun = false } = {}) {
+  // A manifest that is not a supported composition is never reconciled, not
+  // even in dry-run: report it and write nothing so a diagnostic cannot
+  // silently proceed as if the input were valid.
+  const preflight = preflightManifest(manifest)
+  if (!preflight.ok) {
+    return { ok: false, errors: preflight.errors, views: [], changed: [] }
+  }
+
+  const name = manifest.name
+  const siteName = manifest.siteName ?? manifest.name
+  const mode = manifest.theme?.mode ?? DEFAULT_THEME_MODE
+  const subs = { name, siteName, mode }
+  const viewsDir = path.join(projectDir, 'lib', name, 'views')
+  const changed = []
+  const preserved = []
+
+  // Resolve every assembled view's explicit slot selection from the manifest
+  // before any write, so a conflicting or non-executable selection fails the
+  // whole reconcile instead of rendering part of it. A view without an assembly
+  // has no fragments to select. Feature instance mounts claim a host slot and
+  // override its presentation from the feature's config; the view's own stored
+  // selection is preserved dormant (never written) and restored on removal.
+  const mountOverrides = resolveFeatureMountOverrides(manifest)
+  if (!mountOverrides.ok) {
+    return { ok: false, errors: mountOverrides.errors, views: [], changed: [] }
+  }
+  const viewSelections = new Map()
+  for (const view of manifest.views) {
+    const src = viewTemplateDir(view.name)
+    if (!src || !hasViewAssembly(src)) continue
+    const resolved = resolveViewGenerationSelection(view, mountOverrides.byView)
+    if (!resolved.ok) {
+      return { ok: false, errors: resolved.errors, views: [], changed: [] }
+    }
+    viewSelections.set(view.name, resolved)
+  }
+
+  await renderDerivedTree(
+    path.join(templatesRoot, 'app', 'app', '[[...slug]]'),
+    path.join(projectDir, 'app', '[[...slug]]'),
+    subs,
+    (rel) => classifyFile(path.posix.join('app/app/[[...slug]]', rel)),
+    changed,
+    undefined,
+    dryRun,
+  )
+
+  await renderDerivedTree(
+    path.join(templatesRoot, 'app', 'lib'),
+    path.join(projectDir, 'lib'),
+    subs,
+    (rel) => classifyFile(path.posix.join('app/lib', rel)),
+    changed,
+    (rel) => {
+      const normalized = rel.replaceAll('\\', '/')
+      // The barrel and the composers are generated, not copied.
+      return (
+        normalized.endsWith('views/index.ts') ||
+        normalized === '__STOREFRONT__/state.ts' ||
+        normalized === '__STOREFRONT__/handlers.ts' ||
+        normalized === '__STOREFRONT__/composition.ts'
+      )
+    },
+    dryRun,
+  )
+
+  const featuresDir = path.join(projectDir, 'lib', name, 'features')
+  const featureNames = manifest.features.map((feature) => feature.name).sort()
+  if (!dryRun) await mkdir(featuresDir, { recursive: true })
+  for (const featureName of featureNames) {
+    await renderDerivedTree(
+      path.join(templatesRoot, 'features', featureName),
+      path.join(featuresDir, featureName),
+      subs,
+      (rel) => classifyFile(path.posix.join('features', featureName, rel)),
+      changed,
+      undefined,
+      dryRun,
+    )
+    // Adapter needs are declared by the feature recipe, not templated, so the
+    // generated file always matches the registry the CLI validates against. A
+    // feature that declares no adapter needs (a pure editorial/mount feature)
+    // generates no runtime file at all — there is nothing for it to import.
+    const adapterNeeds = getFeature(featureName)?.adapter?.needs ?? []
+    if (adapterNeeds.length > 0) {
+      const adapterPath = path.join(featuresDir, featureName, 'adapter.ts')
+      const adapterContent = buildFeatureAdapter(featureName, adapterNeeds)
+      const prevAdapter = existsSync(adapterPath) ? await readFile(adapterPath, 'utf8') : null
+      if (prevAdapter !== adapterContent) {
+        if (!dryRun) {
+          await mkdir(path.dirname(adapterPath), { recursive: true })
+          await writeFile(adapterPath, adapterContent)
+        }
+        changed.push(adapterPath)
+      }
+    }
+  }
+  // Feature folders no longer in the manifest are removed, but a customized or
+  // unknown file inside one is preserved (never silently deleted) and reported
+  // back to the caller, exactly like a removed view's user-owned files.
+  if (existsSync(featuresDir)) {
+    const installed = new Set(featureNames)
+    for (const entry of await readdir(featuresDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || installed.has(entry.name)) continue
+      const removal = await removeFeatureFiles(projectDir, manifest, entry.name, { dryRun })
+      for (const rel of removal.removed) changed.push(path.join(projectDir, rel))
+      preserved.push(...removal.preserved)
+    }
+  }
+
+  if (!dryRun) await mkdir(viewsDir, { recursive: true })
+  for (const view of manifest.views) {
+    const src = viewTemplateDir(view.name)
+    if (!src) continue
+    // A view with an assembly composes its derived index.tsx/registry.tsx from
+    // the selected per-slot fragments; the assembly sources are never copied and
+    // the assembled files are written below instead of copied verbatim.
+    const assembled = hasViewAssembly(src)
+    const skip = (rel) => {
+      const normalized = rel.split(path.sep).join('/')
+      if (isAssemblyRel(rel)) return true
+      return assembled && (normalized === 'index.tsx' || normalized === 'registry.tsx')
+    }
+    await renderDerivedTree(
+      src,
+      path.join(viewsDir, view.name),
+      subs,
+      (rel) => classifyFile(path.posix.join('views', view.name, rel)),
+      changed,
+      skip,
+      dryRun,
+    )
+    if (assembled) {
+      const resolved = viewSelections.get(view.name)
+      const written = await writeViewAssembly({
+        viewDir: path.join(viewsDir, view.name),
+        templateDir: src,
+        selection: resolved?.selection ?? {},
+        sections: resolved?.sections ?? null,
+        render: (source) => replacePlaceholders(source, subs),
+        dryRun,
+      })
+      for (const abs of written) changed.push(abs)
+    }
+  }
+
+  // View directories no longer in the manifest are removed, exactly like the
+  // feature folders below. Without this, an abrupt apply kill after the derived
+  // writes but before the manifest leaves an orphan derived view on disk that a
+  // later `sync` regenerates the barrels around but never deletes, so the
+  // divergence would survive silently (E1 task 4.8). Only registered view names
+  // are considered, so a shared directory such as `views/sections` (rendered
+  // from the app/lib template tree, not a view) is never touched. A pristine
+  // template file is removed; a customized or unknown user-owned file is
+  // preserved and reported.
+  const installedViews = new Set(manifest.views.map((view) => view.name))
+  const registeredViews = new Set(allowedViewNames())
+  if (existsSync(viewsDir)) {
+    for (const entry of await readdir(viewsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || installedViews.has(entry.name)) continue
+      if (!registeredViews.has(entry.name)) continue
+      const removal = await removeViewFiles(projectDir, manifest, entry.name, { dryRun })
+      for (const rel of removal.removed) changed.push(path.join(projectDir, rel))
+      preserved.push(...removal.preserved)
+    }
+  }
+
+  // The barrel is generated from the manifest's installed views — never by
+  // scanning leftover view directories, so a view removed from the manifest
+  // cannot reappear in the wiring.
+  const viewNames = manifest.views.map((view) => view.name)
+  const barrelPath = path.join(viewsDir, 'index.ts')
+  const prevBarrel = existsSync(barrelPath) ? await readFile(barrelPath, 'utf8') : null
+  const nextBarrel = buildBarrel(viewNames)
+  if (prevBarrel !== nextBarrel) {
+    if (!dryRun) await writeBarrel(viewsDir, viewNames)
+    changed.push(barrelPath)
+  }
+
+  // The client view-registry barrel imports only each view's client mapping, so
+  // the generated shell registry never pulls the server loaders into the client
+  // graph. Generated from the manifest's views, like the server barrel.
+  const clientBarrelPath = path.join(viewsDir, 'registry.ts')
+  const prevClientBarrel = existsSync(clientBarrelPath) ? await readFile(clientBarrelPath, 'utf8') : null
+  const nextClientBarrel = buildClientRegistryBarrel(viewNames)
+  if (prevClientBarrel !== nextClientBarrel) {
+    if (!dryRun) await writeClientRegistryBarrel(viewsDir, viewNames)
+    changed.push(clientBarrelPath)
+  }
+
+  const layoutResult = await ensureLayoutAppend(projectDir, name, siteName, mode, dryRun)
+  if (layoutResult.conflict) {
+    return { ok: false, errors: [layoutResult.conflict], views: [], changed: [] }
+  }
+  if (layoutResult.changed) {
+    changed.push(path.join(projectDir, 'app', 'layout.tsx'))
+  }
+  if (await ensureGlobalsAppend(projectDir, name, siteName, dryRun)) {
+    changed.push(path.join(projectDir, 'app', 'globals.css'))
+  }
+  for (const seoFile of ['sitemap.ts', 'robots.ts']) {
+    if (await ensureSeedFile(projectDir, seoFile, subs, dryRun)) {
+      changed.push(path.join(projectDir, 'app', seoFile))
+    }
+  }
+
+  // The managed root guidance file is derived: rendered from the package
+  // template with the project placeholders, refreshed by sync, and reported as
+  // drift by doctor's dry-run. It is never seeded-and-frozen (not user-owned),
+  // so the rules a store enforces always match the installed CLI generation.
+  if (classifyFile('AGENTS.md') === 'derived') {
+    const agentsTemplate = path.join(templatesRoot, 'AGENTS.md')
+    if (existsSync(agentsTemplate)) {
+      const agentsPath = path.join(projectDir, 'AGENTS.md')
+      const nextAgents = replacePlaceholders(await readFile(agentsTemplate, 'utf8'), subs)
+      const prevAgents = existsSync(agentsPath) ? await readFile(agentsPath, 'utf8') : null
+      if (prevAgents !== nextAgents) {
+        if (!dryRun) await writeFile(agentsPath, nextAgents)
+        changed.push(agentsPath)
+      }
+    }
+  }
+
+  // Composer files are generated from the installed features, not templated.
+  // A feature contributes to a composer only when the registry declares it owns
+  // state/handlers for it; a pure editorial feature (no state, no handlers)
+  // contributes nothing and its missing fragment is never imported.
+  const stateFeatures = featureNames.filter((n) => (getFeature(n)?.state?.length ?? 0) > 0)
+  const handlerFeatures = featureNames.filter((n) => (getFeature(n)?.handlers?.length ?? 0) > 0)
+  for (const [composerPath, content] of [
+    [path.join(projectDir, 'lib', name, 'state.ts'), buildStateComposer(stateFeatures)],
+    [path.join(projectDir, 'lib', name, 'handlers.ts'), buildHandlersComposer(handlerFeatures)],
+    [path.join(projectDir, 'lib', name, 'composition.ts'), buildCompositionComposer(manifest.features, manifest.views)],
+  ]) {
+    const prev = existsSync(composerPath) ? await readFile(composerPath, 'utf8') : null
+    if (prev === content) continue
+    if (!dryRun) {
+      await mkdir(path.dirname(composerPath), { recursive: true })
+      await writeFile(composerPath, content)
+    }
+    changed.push(composerPath)
+  }
+
+  return {
+    ok: true,
+    views: manifest.views.map((view) => view.name),
+    changed: changed.map((abs) => path.relative(projectDir, abs)),
+    preserved,
+  }
+}
+
+async function main() {
+  const projectDir = process.argv[2]
+  if (!projectDir) {
+    console.error('Usage: node scripts/reconcile.mjs <project-dir>')
+    return 1
+  }
+  const { readManifest } = await import('./manifest.mjs')
+  const manifest = await readManifest(projectDir)
+  if (!manifest) {
+    console.error('No storefront.config.json found in ' + projectDir)
+    return 1
+  }
+  const result = await reconcile(projectDir, manifest)
+  if (!result.ok) {
+    console.error('Refusing to reconcile: the composition is invalid.')
+    for (const error of result.errors) console.error(`  ${error}`)
+    return 1
+  }
+  console.log('Reconciled ' + projectDir)
+  return 0
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().then((code) => {
+    process.exitCode = code
+  })
+}