@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

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/migrate-english-routes.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+// Opt-in migration for the retired Spanish route literals in an existing
+// consumer's USER-OWNED content files (change: storefront-english-routes,
+// task 3.4 / AC-EN-5.4).
+//
+// WHY THIS EXISTS: `storefront sync` never rewrites a user-owned file, so a
+// consumer created before the English-route change keeps Spanish links in its
+// own `lib/<name>/shell/content.ts` (and the user-owned static-page `path`
+// declarations in `lib/<name>/views/static/content.ts`). Changing the package
+// default cannot change an existing consumer's links, so this script is the
+// documented, CLI-bounded, opt-in transition. It:
+//   * rewrites ONLY the retired route literal at the START of an `href`/`path`
+//     string property value (root-relative), preserving the backend handle and
+//     any `?query`/`#hash`,
+//   * ONLY inside the two user-owned content files on the allow-list,
+//   * ONLY when run with `--apply` (dry-run by default),
+//   * keeps a no-clobber backup of each file it rewrites, and writes
+//     transactionally (all files or none),
+//   * and preserves unrelated prose, comments, absolute URLs, and nested
+//     `/api/...` paths — it never re-parses the whole file as a grammar.
+//
+// Usage:
+//   node scripts/migrate-english-routes.mjs <project-dir>          # dry run
+//   node scripts/migrate-english-routes.mjs <project-dir> --apply  # write
+
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
+import { resolve, join, relative, dirname, isAbsolute, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { readManifest } from './manifest.mjs'
+import { assertInsideProject, atomicWrite, restoreSnapshot, takeSnapshot } from './plan-apply.mjs'
+
+// Retired route literal -> English route literal. These are matched ONLY as the
+// FIRST path segment of an `href`/`path` string property value.
+export const RETIRED = [
+  ['/categorias', '/categories'],
+  ['/productos', '/products'],
+  ['/cuenta', '/account'],
+  ['/contacto', '/contact'],
+  ['/terminos', '/terms'],
+  ['/privacidad', '/privacy'],
+  ['/sobre-nosotros', '/about'],
+]
+
+// A safe single-segment storefront name: no separators, no `..`, no leading dot.
+const SAFE_NAME = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/
+// The property keys whose string value is a route.
+const ROUTE_PROP = /(?:^|[^A-Za-z0-9_$.-])(?:href|path)\s*:\s*$/
+const QUOTES = new Set(["'", '"', '`'])
+const BACKUP_DIR = join('.opencode', 'backups', 'english-routes')
+
+/** The user-owned content files, relative to the project, that may carry a route literal. */
+export function userOwnedRouteFiles(name) {
+  return [join('lib', name, 'shell', 'content.ts'), join('lib', name, 'views', 'static', 'content.ts')]
+}
+
+/**
+ * Rewrite a route value only when it is a retired root-relative route:
+ * `/productos/<handle>?q#h` -> `/products/<handle>?q#h` (handle/query/hash kept).
+ * Returns null when the value is not a retired route (absolute URL, `/api/...`,
+ * prose, an already-English route, or a different route).
+ */
+export function migrateRouteValue(value) {
+  for (const [from, to] of RETIRED) {
+    if (
+      value === from ||
+      value.startsWith(`${from}/`) ||
+      value.startsWith(`${from}?`) ||
+      value.startsWith(`${from}#`)
+    ) {
+      return to + value.slice(from.length)
+    }
+  }
+  return null
+}
+
+// Split the source into code / string / comment tokens with a small scanner, so
+// a retired literal inside a comment or prose is never touched and only a string
+// token that directly follows an `href:`/`path:` property key is considered.
+function scan(text) {
+  const tokens = []
+  const n = text.length
+  let i = 0
+  let codeStart = 0
+  const pushCode = (end) => {
+    if (end > codeStart) tokens.push({ type: 'code', text: text.slice(codeStart, end) })
+  }
+  while (i < n) {
+    const c = text[i]
+    if (c === '/' && text[i + 1] === '/') {
+      pushCode(i)
+      let j = text.indexOf('\n', i)
+      if (j === -1) j = n
+      tokens.push({ type: 'comment', text: text.slice(i, j) })
+      i = j
+      codeStart = i
+      continue
+    }
+    if (c === '/' && text[i + 1] === '*') {
+      pushCode(i)
+      let j = text.indexOf('*/', i + 2)
+      j = j === -1 ? n : j + 2
+      tokens.push({ type: 'comment', text: text.slice(i, j) })
+      i = j
+      codeStart = i
+      continue
+    }
+    if (QUOTES.has(c)) {
+      pushCode(i)
+      let j = i + 1
+      while (j < n) {
+        if (text[j] === '\\') {
+          j += 2
+          continue
+        }
+        if (text[j] === c) {
+          j++
+          break
+        }
+        if (text[j] === '\n' && c !== '`') break
+        j++
+      }
+      tokens.push({ type: 'string', text: text.slice(i, j) })
+      i = j
+      codeStart = i
+      continue
+    }
+    i++
+  }
+  pushCode(n)
+  return tokens
+}
+
+/** Rewrite the retired route literals in an `href`/`path` value. Idempotent. */
+export function migrateText(text) {
+  const tokens = scan(text)
+  for (let k = 1; k < tokens.length; k++) {
+    const token = tokens[k]
+    if (token.type !== 'string') continue
+    const prev = tokens[k - 1]
+    if (!prev || prev.type !== 'code' || !ROUTE_PROP.test(prev.text)) continue
+    if (token.text.length < 2 || token.text[0] !== token.text[token.text.length - 1]) continue
+    const quote = token.text[0]
+    const migrated = migrateRouteValue(token.text.slice(1, -1))
+    if (migrated === null) continue
+    tokens[k] = { type: 'string', text: quote + migrated + quote }
+  }
+  return tokens.map((token) => token.text).join('')
+}
+
+// Containment: the resolved file must live under the project root, both
+// lexically and (when it exists) through any symlinked ancestor.
+function insideProject(projectDir, abs) {
+  const rel = relative(projectDir, abs)
+  if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) return false
+  if (!existsSync(abs)) return true
+  try {
+    const realRoot = realpathSync(projectDir)
+    const realAbs = realpathSync(abs)
+    return realAbs === realRoot || realAbs.startsWith(`${realRoot}${sep}`)
+  } catch {
+    return false
+  }
+}
+
+/** Plan the migration: the allow-listed files whose text would change. */
+export async function planMigration(projectDir) {
+  const manifest = await readManifest(projectDir)
+  if (!manifest) return { ok: false, error: `no storefront.config.json found in ${projectDir}` }
+  const name = manifest.name
+  if (typeof name !== 'string' || !SAFE_NAME.test(name)) {
+    return { ok: false, error: `storefront name ${JSON.stringify(name)} is not a safe path segment` }
+  }
+  const root = resolve(projectDir)
+  const changes = []
+  for (const rel of userOwnedRouteFiles(name)) {
+    const abs = join(root, rel)
+    if (!insideProject(root, abs)) {
+      return { ok: false, error: `allow-listed path escapes the project: ${rel}` }
+    }
+    if (!existsSync(abs)) continue
+    const raw = readFileSync(abs, 'utf8')
+    const next = migrateText(raw)
+    if (next === raw) continue
+    changes.push({ file: rel, abs, raw, next })
+  }
+  return { ok: true, root, name, changes }
+}
+
+// No-clobber backup: create exclusively; an existing backup is reused only when
+// it already holds this exact pre-migration content, otherwise the apply refuses.
+function ensureBackup(root, rel, raw) {
+  const abs = join(root, BACKUP_DIR, rel)
+  // A symlinked `.opencode/backups` must never redirect the backup outside the
+  // project; the same containment guard the retirement backup uses.
+  assertInsideProject(root, abs)
+  mkdirSync(dirname(abs), { recursive: true })
+  if (existsSync(abs)) {
+    if (readFileSync(abs, 'utf8') !== raw) {
+      throw new Error(`refusing to overwrite an existing backup with different content: ${abs}`)
+    }
+    return { path: abs, created: false }
+  }
+  writeFileSync(abs, raw, { flag: 'wx' })
+  return { path: abs, created: true }
+}
+
+export async function migrateProject(projectDir, { apply = false } = {}) {
+  const plan = await planMigration(projectDir)
+  if (!plan.ok) return { ok: false, error: plan.error, changed: [] }
+
+  const planned = plan.changes.map((change) => ({ file: change.file, applied: false }))
+  if (!apply || plan.changes.length === 0) {
+    return { ok: true, apply, changed: planned, files: plan.changes.map((c) => c.abs), backups: [] }
+  }
+
+  const snapshot = takeSnapshot(plan.root, plan.changes.map((c) => c.abs))
+  const backups = []
+  const createdBackups = []
+  try {
+    for (const change of plan.changes) {
+      const backup = ensureBackup(plan.root, change.file, change.raw)
+      backups.push(backup.path)
+      if (backup.created) createdBackups.push(backup.path)
+      atomicWrite(change.abs, change.next)
+    }
+  } catch (error) {
+    restoreSnapshot(snapshot)
+    for (const backup of createdBackups) rmSync(backup, { force: true })
+    return { ok: false, error: error instanceof Error ? error.message : String(error), changed: [] }
+  }
+  return {
+    ok: true,
+    apply,
+    changed: plan.changes.map((change) => ({ file: change.file, applied: true })),
+    files: plan.changes.map((c) => c.abs),
+    backups,
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2)
+  const projectDir = args.find((a) => !a.startsWith('-'))
+  const apply = args.includes('--apply')
+  if (!projectDir) {
+    console.error('Usage: node scripts/migrate-english-routes.mjs <project-dir> [--apply]')
+    return 1
+  }
+  const result = await migrateProject(resolve(projectDir), { apply })
+  if (!result.ok) {
+    console.error(result.error)
+    return 1
+  }
+  if (result.changed.length === 0) {
+    console.log('No retired Spanish route literal found in the user-owned content files — nothing to migrate.')
+    return 0
+  }
+  for (const entry of result.changed) {
+    console.log(`  ${apply ? 'migrated' : 'would migrate'} ${entry.file}`)
+  }
+  for (const backup of result.backups) console.log(`  backup ${backup}`)
+  if (!apply) {
+    console.log('Dry run — re-run with --apply to rewrite these user-owned files.')
+  }
+  return 0
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main()
+    .then((code) => {
+      process.exitCode = code
+    })
+    .catch((err) => {
+      console.error(err)
+      process.exitCode = 1
+    })
+}