story-theme-mcp 1.0.0

package/src/project/export.js

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { zipSync, unzipSync, strFromU8 } from 'fflate';
+import { isInternalTemplate } from '../theme/catalog.js';
+import { parseThemeJson } from '../theme/loader.js';
+import { validateFile, fileKind, LIMITS } from '../validate/template.js';
+import { reviewProject, formatReview } from './review.js';
+import { migrateData } from '../build/migrate.js';
+import { slugify } from './store.js';
+
+const THEME_DIRS = ['assets', 'blocks', 'config', 'layout', 'locales', 'sections', 'snippets', 'templates'];
+
+function themeEntries(themeDir) {
+  const entries = new Map();
+  for (const top of THEME_DIRS) {
+    const walk = (folder, prefix) => {
+      if (!fs.existsSync(folder)) return;
+      for (const name of fs.readdirSync(folder)) {
+        if (name.startsWith('.')) continue;
+        const full = path.join(folder, name);
+        const rel = `${prefix}${name}`;
+        if (fs.statSync(full).isDirectory()) walk(full, `${rel}/`);
+        else if (!(rel.startsWith('templates/') && isInternalTemplate(rel))) entries.set(rel, full);
+      }
+    };
+    walk(path.join(themeDir, top), `${top}/`);
+  }
+  return entries;
+}
+
+// Brings every project file up to the current theme (settings it dropped, values it no longer
+// accepts), saving each changed file with a snapshot so undo can restore it.
+export function migrateProject({ catalog, store, slug }) {
+  const settings = store.read(slug, 'config/settings_data.json').data;
+  const current = typeof settings?.current === 'string' ? settings.presets?.[settings.current] : settings?.current;
+  const schemeIds = Object.keys(current?.color_schemes || {});
+  const report = {};
+  for (const rel of store.projectFiles(slug)) {
+    const { data } = store.read(slug, rel);
+    const { data: migrated, changes } = migrateData(catalog, data, { schemeIds });
+    if (!changes.length) continue;
+    store.write(slug, rel, migrated, `mise à jour vers le thème ${catalog.version} (${changes.length} réglage(s))`);
+    report[rel] = changes;
+  }
+  return report;
+}
+
+// Builds a theme zip ready for "Add theme > Upload zip file": the theme source, minus its QA
+// templates, with the project's templates, groups and settings on top. Refuses on any error.
+export function exportTheme({ catalog, store, slug }) {
+  const migrated = migrateProject({ catalog, store, slug });
+  const review = reviewProject(catalog, store, slug);
+  // Theme files count too: a project change (a removed colour scheme) can break them.
+  const blocking = review.perFile.filter((entry) => entry.validation.errors.length);
+  if (blocking.length) {
+    return {
+      ok: false,
+      migrated,
+      message: `Export refusé : ${blocking.reduce((total, entry) => total + entry.validation.errors.length, 0)} erreur(s) bloquante(s). Shopify refuserait ces fichiers.`,
+      errors: blocking.map((entry) => ({ file: entry.file, errors: entry.validation.errors.slice(0, 10) })),
+    };
+  }
+  const excluded = new Set(store.excluded(slug));
+  const files = {};
+  for (const [rel, full] of themeEntries(catalog.theme.dir)) if (!excluded.has(rel)) files[rel] = new Uint8Array(fs.readFileSync(full));
+  const overlays = store.projectFiles(slug).filter((rel) => !excluded.has(rel));
+  for (const rel of overlays) {
+    const content = fs.readFileSync(store.filePath(slug, rel));
+    const limit = rel === 'config/settings_data.json' ? LIMITS.settingsDataBytes : LIMITS.fileBytes;
+    if (content.length > limit) return { ok: false, message: `${rel} dépasse la taille maximale acceptée par Shopify (${Math.round(limit / 1024)} Ko)` };
+    files[rel] = new Uint8Array(content);
+  }
+  const meta = review.meta;
+  const stamp = new Date().toISOString().slice(0, 16).replace(/[-:T]/g, '').replace(/^(\d{8})(\d{4})$/, '$1-$2');
+  const dir = store.exportsDir(slug);
+  fs.mkdirSync(dir, { recursive: true });
+  const zipName = `${slugify(meta.name)}-story-theme-${catalog.version}-${stamp}.zip`;
+  const zip = zipSync(files, { level: 6 });
+  fs.writeFileSync(path.join(dir, zipName), zip);
+  const reportText = formatReview(review);
+  fs.writeFileSync(path.join(dir, zipName.replace(/\.zip$/, '-checklist.md')), reportText + '\n');
+  return {
+    ok: true,
+    migrated,
+    zip: path.join(dir, zipName),
+    size_mb: Math.round((zip.length / 1024 / 1024) * 10) / 10,
+    files: Object.keys(files).length,
+    overlays,
+    checklist: path.join(dir, zipName.replace(/\.zip$/, '-checklist.md')),
+    report: reportText,
+  };
+}
+
+function readSource(source) {
+  const files = new Map();
+  if (fs.statSync(source).isDirectory()) {
+    const pick = (rel) => {
+      const full = path.join(source, rel);
+      if (fs.existsSync(full)) files.set(rel, fs.readFileSync(full, 'utf8'));
+    };
+    pick('config/settings_data.json');
+    pick('config/settings_schema.json');
+    for (const folder of ['templates', 'templates/customers', 'sections']) {
+      const full = path.join(source, folder);
+      if (!fs.existsSync(full)) continue;
+      for (const name of fs.readdirSync(full)) if (name.endsWith('.json')) pick(`${folder}/${name}`);
+    }
+    return files;
+  }
+  if (!source.endsWith('.zip')) throw new Error('source attendue : un dossier de thème ou un fichier .zip exporté depuis Shopify');
+  const archive = unzipSync(new Uint8Array(fs.readFileSync(source)));
+  // Shopify exports sometimes nest everything under one top folder.
+  const names = Object.keys(archive);
+  const root = names.find((name) => name.endsWith('config/settings_schema.json'))?.replace('config/settings_schema.json', '') ?? '';
+  for (const name of names) {
+    if (!name.startsWith(root) || !name.endsWith('.json')) continue;
+    const rel = name.slice(root.length);
+    if (rel === 'config/settings_schema.json' || fileKind(rel)) files.set(rel, strFromU8(archive[name]));
+  }
+  return files;
+}
+
+// Creates a project from a theme exported from a store (folder or zip), to audit or rework it.
+export function importTheme({ catalog, store, source, name, language = 'fr' }) {
+  const resolved = path.resolve(source.replace(/^~/, process.env.HOME || ''));
+  if (!fs.existsSync(resolved)) throw new Error(`« ${source} » introuvable`);
+  const files = readSource(resolved);
+  let version = 'inconnue';
+  if (files.has('config/settings_schema.json')) {
+    try {
+      version = parseThemeJson(files.get('config/settings_schema.json')).find((group) => group.name === 'theme_info')?.theme_version || version;
+    } catch {
+      /* keep unknown */
+    }
+  }
+  files.delete('config/settings_schema.json');
+  let schemeIds;
+  try {
+    const settings = files.has('config/settings_data.json') ? parseThemeJson(files.get('config/settings_data.json')) : null;
+    const current = typeof settings?.current === 'string' ? settings.presets?.[settings.current] : settings?.current;
+    schemeIds = current?.color_schemes ? Object.keys(current.color_schemes) : undefined;
+  } catch {
+    schemeIds = undefined;
+  }
+  const meta = store.create({ name, language, brief: { imported_from: resolved, imported_version: version } });
+  const results = [];
+  for (const [rel, text] of files) {
+    if (!fileKind(rel)) continue;
+    let data;
+    try {
+      data = parseThemeJson(text);
+    } catch (error) {
+      results.push({ file: rel, imported: false, errors: [`JSON illisible : ${error.message}`] });
+      continue;
+    }
+    const validation = validateFile(catalog, rel, data, { schemeIds });
+    store.write(meta.slug, rel, data, 'import');
+    results.push({ file: rel, imported: true, errors: validation.errors.length, warnings: validation.warnings.length });
+  }
+  return { project: meta.slug, version, themeVersion: catalog.version, results };
+}

package/src/project/review.js

@@ -0,0 +1,143 @@
+import { validateFile } from '../validate/template.js';
+import { lintTemplate, lintSettings } from '../validate/design.js';
+
+function schemeIdsOf(files) {
+  const settings = files.get('config/settings_data.json')?.data;
+  const current = typeof settings?.current === 'string' ? settings.presets?.[settings.current] : settings?.current;
+  return Object.keys(current?.color_schemes || {});
+}
+
+function* blocksOf(node) {
+  for (const block of Object.values(node?.blocks || {})) {
+    yield block;
+    yield* blocksOf(block);
+  }
+}
+
+// Where colour schemes are used: every color_scheme setting of every section and block.
+export function findSchemeReferences(catalog, files, ids) {
+  const wanted = new Set(ids);
+  const found = [];
+  const visit = (file, kind, node, path) => {
+    const schema = kind === 'section' ? catalog.section(node.type)?.schema : catalog.block(node.type)?.schema;
+    for (const setting of schema?.settings || []) {
+      if (setting.type === 'color_scheme' && wanted.has(node.settings?.[setting.id] ?? setting.default)) found.push(`${file} › ${path}.${setting.id}`);
+    }
+    for (const [id, block] of Object.entries(node.blocks || {})) visit(file, 'block', block, `${path}/${id}`);
+  };
+  for (const [file, { data }] of files) {
+    const current = file === 'config/settings_data.json' ? (typeof data?.current === 'string' ? data.presets?.[data.current] : data?.current) : null;
+    const sections = current ? current.sections : data?.sections;
+    for (const [id, section] of Object.entries(sections || {})) visit(file, 'section', section, id);
+  }
+  return found;
+}
+
+// Validates and reviews every editable file of a project, and derives the launch checklist.
+export function reviewProject(catalog, store, slug) {
+  const meta = store.meta(slug);
+  const language = meta.language || 'fr';
+  const files = store.effectiveFiles(slug);
+  const schemeIds = schemeIdsOf(files);
+  const perFile = [];
+  const resources = { collections: new Set(), products: new Set(), pages: new Set(), blogs: new Set(), menus: new Set(), images: new Set(), videos: new Set() };
+  const usedBlocks = new Set();
+  const trustpilotMissing = [];
+  let errorCount = 0;
+
+  for (const [rel, { data, origin }] of files) {
+    const validation = validateFile(catalog, rel, data, { schemeIds });
+    errorCount += validation.errors.length;
+    for (const [key, list] of Object.entries(validation.resources || {})) if (resources[key]) list.forEach((item) => resources[key].add(item));
+    const design = rel === 'config/settings_data.json' ? lintSettings(catalog, data) : lintTemplate(catalog, rel, data, { language });
+    for (const section of Object.values(data?.sections || {})) {
+      for (const block of blocksOf(section)) {
+        usedBlocks.add(block.type);
+        if (block.type === 'trustpilot' && !block.settings?.business_unit_id) trustpilotMissing.push(rel);
+      }
+    }
+    perFile.push({ file: rel, origin, validation, design });
+  }
+
+  const checklist = buildChecklist({ files, resources, usedBlocks, trustpilotMissing, language });
+  const pending = perFile.filter((entry) => entry.origin === 'theme' && entry.file !== 'config/settings_data.json' && entry.design.some((finding) => finding.level === 'important'));
+  return { meta, perFile, errorCount, checklist, pendingThemeTemplates: pending.map((entry) => entry.file) };
+}
+
+function buildChecklist({ files, resources, usedBlocks, trustpilotMissing, language }) {
+  const items = [];
+  const add = (group, text) => items.push({ group, text });
+
+  add('Installer', 'Boutique en ligne > Thèmes > Ajouter un thème > Importer un fichier zip, puis « Personnaliser » pour vérifier chaque page sur ordinateur et sur mobile avant de publier.');
+  const header = files.get('sections/header-group.json')?.data;
+  const logoBlocks = header ? [...Object.values(header.sections || {})].flatMap((section) => [...blocksOf(section)]).filter((block) => block.type === '_header-logo') : [];
+  if (!logoBlocks.length || logoBlocks.every((block) => !block.settings?.logo)) add('Images', "Logo : l'ajouter dans le bloc Logo de l'en-tête (PNG ou SVG sur fond transparent, 2× la taille affichée).");
+  if (resources.images.size) add('Images', `Images citées par le thème, à déposer dans Contenu > Fichiers avec exactement ces noms : ${[...resources.images].map((value) => value.replace('shopify://shop_images/', '')).join(', ')}`);
+  if (resources.collections.size) add('Catalogue', `Collections à créer (identifiant exact) : ${[...resources.collections].join(', ')}`);
+  if (resources.products.size) add('Catalogue', `Produits cités (identifiant exact) : ${[...resources.products].join(', ')}`);
+  if (resources.menus.size) add('Navigation', `Menus utilisés : ${[...resources.menus].join(', ')} (Contenu > Menus). main-menu et footer existent déjà dans toute boutique.`);
+  if (resources.pages.size) add('Pages', `Pages citées dans les liens : ${[...resources.pages].join(', ')}`);
+
+  const pageTemplates = [...files.keys()].filter((rel) => /^templates\/page\.[^.]+\.json$/.test(rel));
+  if (pageTemplates.length) add('Pages', `Modèles de page disponibles : ${pageTemplates.map((rel) => rel.replace('templates/', '').replace('.json', '')).join(', ')}. Pour chacun, créez la page (Boutique en ligne > Pages) et choisissez le modèle dans « Modèle de thème ». Le thème doit être publié pour que ses modèles apparaissent dans la liste.`);
+  const productTemplates = [...files.keys()].filter((rel) => /^templates\/product\.[^.]+\.json$/.test(rel));
+  if (productTemplates.length) add('Pages', `Modèles de produit alternatifs : ${productTemplates.map((rel) => rel.replace('templates/', '').replace('.json', '')).join(', ')}. À attribuer produit par produit (fiche produit > Modèle de thème).`);
+
+  if (['product-offers', 'product-addons', 'bundle-builder', '_offer', '_cart-rewards'].some((type) => usedBlocks.has(type))) {
+    add('Offres', "Le thème affiche les offres mais ne fixe aucun prix : créez dans Réductions la réduction automatique (ou le code) qui correspond à chaque palier, lot ou cadeau, puis testez une commande.");
+  }
+  if (usedBlocks.has('product-subscription')) add('Offres', "Abonnements : installez une application d'abonnement (plans de vente Shopify), sinon le bloc n'affiche rien.");
+  if (usedBlocks.has('product-rating') || usedBlocks.has('_card-rating') || usedBlocks.has('review-summary')) add('Applications', "Avis produits : installez une application d'avis qui remplit les métachamps reviews.rating et reviews.rating_count (Judge.me, Yotpo, Loox…).");
+  if (trustpilotMissing.length) add('Applications', 'Trustpilot : renseignez l’identifiant d’entreprise (business_unit_id) et le modèle du widget dans le bloc Trustpilot.');
+  if (usedBlocks.has('newsletter')) add('Marketing', 'Newsletter : les inscrits arrivent dans Clients avec le consentement marketing. Branchez un outil d’e-mailing (Shopify Email, Klaviyo, Brevo).');
+
+  add('Réglages Shopify', 'Paramètres > Politiques : conditions générales de vente, politique de remboursement, confidentialité, mentions légales, expédition.');
+  if (language === 'fr') add('Réglages Shopify', 'Obligations en France : mentions légales (éditeur, hébergeur, SIRET), CGV avec droit de rétractation de 14 jours, médiateur de la consommation, bannière cookies (Paramètres > Confidentialité des clients).');
+  add('Réglages Shopify', 'Paiements, expédition (zones et tarifs), taxes, domaine, e-mails de notification à votre nom.');
+  add('Avant de publier', 'Passer une commande test de bout en bout (paiement, e-mail de confirmation, remises appliquées).');
+  add('Avant de publier', 'Vérifier chaque page sur mobile : c’est là que se font la majorité des ventes.');
+  add('Avant de publier', 'Retirer le mot de passe de la boutique (Préférences) une fois tout vérifié.');
+  return items;
+}
+
+export function formatReview(review, { maxPerFile = 12 } = {}) {
+  const lines = [];
+  const { meta, perFile, errorCount, checklist, pendingThemeTemplates } = review;
+  const own = perFile.filter((entry) => entry.origin === 'project');
+  const count = (level) => own.reduce((total, entry) => total + entry.design.filter((finding) => finding.level === level).length, 0);
+  lines.push(`# Revue du projet « ${meta.name} » (Story Thème ${meta.theme?.version}, langue ${meta.language})`);
+  lines.push(`Fichiers du projet : ${errorCount} erreur(s) bloquante(s) · ${count('important')} point(s) à corriger avant lancement · ${count('suggestion')} suggestion(s) · ${count('info')} info(s)${pendingThemeTemplates.length ? ` · ${pendingThemeTemplates.length} modèle(s) du thème encore avec leurs textes d'exemple` : ''}`);
+  lines.push(errorCount ? '→ Export impossible tant que les erreurs bloquantes restent.' : count('important') || pendingThemeTemplates.length ? '→ Shopify acceptera le thème, mais il n’est pas prêt à publier.' : '→ Prêt : aucun point bloquant ni à corriger.');
+
+  for (const entry of perFile) {
+    const important = entry.design.filter((finding) => finding.level === 'important');
+    const suggestions = entry.design.filter((finding) => finding.level === 'suggestion');
+    const infos = entry.design.filter((finding) => finding.level === 'info');
+    if (!entry.validation.errors.length && !important.length && !suggestions.length && !infos.length && !entry.validation.warnings.length) continue;
+    if (entry.origin === 'theme' && !entry.validation.errors.length) continue;
+    lines.push('');
+    lines.push(`## ${entry.file}${entry.origin === 'theme' ? ' (version du thème)' : ''}`);
+    for (const error of entry.validation.errors.slice(0, maxPerFile)) lines.push(`- ❌ ${error.path || '(racine)'} : ${error.message}`);
+    for (const warning of entry.validation.warnings.slice(0, 5)) lines.push(`- ⚠️ ${warning.path || '(racine)'} : ${warning.message}`);
+    for (const finding of important.slice(0, maxPerFile)) lines.push(`- 🔴 ${finding.path || '(page)'} : ${finding.message}`);
+    if (important.length > maxPerFile) lines.push(`- 🔴 … et ${important.length - maxPerFile} autre(s)`);
+    for (const finding of suggestions.slice(0, 8)) lines.push(`- 🟡 ${finding.path || '(page)'} : ${finding.message}`);
+    if (infos.length) lines.push(`- ℹ️ ${infos.slice(0, 6).map((finding) => `${finding.path ? finding.path + ' : ' : ''}${finding.message}`).join(' · ')}${infos.length > 6 ? ` · … (+${infos.length - 6})` : ''}`);
+  }
+  if (pendingThemeTemplates.length) {
+    lines.push('');
+    lines.push(`## Modèles encore dans leur version d'origine (textes d'exemple du thème)`);
+    lines.push(pendingThemeTemplates.map((file) => `- ${file} : à personnaliser (apply_recipe, edit_template) ou laisser si la page n'est pas utilisée`).join('\n'));
+  }
+  lines.push('');
+  lines.push('## Check-list de mise en ligne');
+  let group = null;
+  for (const item of checklist) {
+    if (item.group !== group) {
+      lines.push(`**${item.group}**`);
+      group = item.group;
+    }
+    lines.push(`- [ ] ${item.text}`);
+  }
+  return lines.join('\n');
+}

package/src/project/store.js

@@ -0,0 +1,260 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileKind } from '../validate/template.js';
+import { isInternalTemplate } from '../theme/catalog.js';
+
+const clone = (value) => JSON.parse(JSON.stringify(value));
+let sequence = 0;
+
+export function slugify(name) {
+  return String(name || '')
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .slice(0, 48)
+    .replace(/^-+|-+$/g, '');
+}
+
+// Only the files a merchant changes through the editor: templates, section groups, settings.
+export function checkRelativePath(rel) {
+  const clean = String(rel || '').replace(/\\/g, '/').replace(/^\/+/, '');
+  if (clean.includes('..') || !fileKind(clean)) {
+    throw new Error(`« ${rel} » : seuls templates/<nom>.json, templates/customers/<nom>.json, sections/<groupe>.json et config/settings_data.json sont modifiables (le code du thème ne l'est jamais)`);
+  }
+  return clean;
+}
+
+function writeAtomic(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, content);
+  fs.renameSync(temp, file);
+}
+
+export class ProjectStore {
+  constructor({ homeDir, catalog }) {
+    this.homeDir = homeDir;
+    this.catalog = catalog;
+    this.projectsDir = path.join(homeDir, 'projects');
+  }
+
+  dir(slug) {
+    const clean = slugify(slug);
+    if (!clean || clean !== slug) throw new Error(`projet « ${slug} » : identifiant invalide`);
+    return path.join(this.projectsDir, clean);
+  }
+
+  slugFor(name) {
+    return slugify(name);
+  }
+
+  // The project the merchant is working on: the last one created or changed.
+  setCurrent(slug) {
+    fs.mkdirSync(this.homeDir, { recursive: true });
+    writeAtomic(path.join(this.homeDir, 'current.json'), JSON.stringify({ slug }) + '\n');
+  }
+
+  current() {
+    try {
+      const { slug } = JSON.parse(fs.readFileSync(path.join(this.homeDir, 'current.json'), 'utf8'));
+      return this.exists(slug) ? slug : null;
+    } catch {
+      return null;
+    }
+  }
+
+  // An explicit project, else the current one.
+  resolve(slug) {
+    if (slug) return slug;
+    const current = this.current();
+    if (current) return current;
+    const projects = this.list();
+    if (projects.length === 1) return projects[0].slug;
+    throw new Error(projects.length ? `plusieurs projets existent (${projects.map((project) => project.slug).join(', ')}) : précisez lequel` : 'aucun projet : lancez build_store avec le nom de la boutique');
+  }
+
+  exists(slug) {
+    try {
+      return fs.existsSync(path.join(this.dir(slug), 'project.json'));
+    } catch {
+      return false;
+    }
+  }
+
+  list() {
+    if (!fs.existsSync(this.projectsDir)) return [];
+    return fs
+      .readdirSync(this.projectsDir)
+      .filter((slug) => fs.existsSync(path.join(this.projectsDir, slug, 'project.json')))
+      .map((slug) => this.meta(slug))
+      .sort((a, b) => String(b.updated_at).localeCompare(String(a.updated_at)));
+  }
+
+  meta(slug) {
+    const file = path.join(this.dir(slug), 'project.json');
+    if (!fs.existsSync(file)) {
+      const known = fs.existsSync(this.projectsDir) ? fs.readdirSync(this.projectsDir) : [];
+      throw new Error(`projet « ${slug} » introuvable${known.length ? ` (projets : ${known.join(', ')})` : ' (aucun projet : lancez build_store avec le nom de la boutique)'}`);
+    }
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  }
+
+  saveMeta(slug, meta) {
+    meta.updated_at = new Date().toISOString();
+    writeAtomic(path.join(this.dir(slug), 'project.json'), JSON.stringify(meta, null, 2) + '\n');
+    return meta;
+  }
+
+  create({ name, language = 'fr', brief = {} }) {
+    const slug = slugify(name);
+    if (!slug) throw new Error('nom de projet vide');
+    if (this.exists(slug)) throw new Error(`le projet « ${slug} » existe déjà : utilisez-le ou choisissez un autre nom`);
+    const now = new Date().toISOString();
+    const meta = { name, slug, language, theme: { name: this.catalog.name, version: this.catalog.version }, created_at: now, updated_at: now, brief, log: [] };
+    fs.mkdirSync(path.join(this.dir(slug), 'theme'), { recursive: true });
+    this.saveMeta(slug, meta);
+    this.setCurrent(slug);
+    // Settings start from the theme defaults so partial updates merge into a complete file.
+    writeAtomic(this.filePath(slug, 'config/settings_data.json'), JSON.stringify(clone(this.catalog.theme.settingsData), null, 2) + '\n');
+    return meta;
+  }
+
+  updateBrief(slug, patch) {
+    const meta = this.meta(slug);
+    meta.brief = { ...(meta.brief || {}), ...patch };
+    return this.saveMeta(slug, meta);
+  }
+
+  filePath(slug, rel) {
+    return path.join(this.dir(slug), 'theme', checkRelativePath(rel));
+  }
+
+  // The project's version of a file, else the theme's default.
+  read(slug, rel) {
+    const clean = checkRelativePath(rel);
+    const file = this.filePath(slug, clean);
+    if (fs.existsSync(file)) return { data: JSON.parse(fs.readFileSync(file, 'utf8')), origin: 'project' };
+    if (clean === 'config/settings_data.json') return { data: clone(this.catalog.theme.settingsData), origin: 'theme' };
+    const fromTheme = this.catalog.theme.templates.get(clean) || this.catalog.theme.groups.get(clean);
+    if (fromTheme && !fromTheme.__error) return { data: clone(fromTheme), origin: 'theme' };
+    return { data: null, origin: 'none' };
+  }
+
+  projectFiles(slug) {
+    const root = path.join(this.dir(slug), 'theme');
+    const found = [];
+    const walk = (folder, prefix) => {
+      if (!fs.existsSync(folder)) return;
+      for (const name of fs.readdirSync(folder).sort()) {
+        const full = path.join(folder, name);
+        if (fs.statSync(full).isDirectory()) walk(full, `${prefix}${name}/`);
+        else if (name.endsWith('.json')) found.push(`${prefix}${name}`);
+      }
+    };
+    walk(root, '');
+    return found;
+  }
+
+  // Every file the exported theme will hold that a merchant can edit, with where it comes from.
+  effectiveFiles(slug) {
+    const excluded = new Set(this.excluded(slug));
+    const files = new Map();
+    for (const [rel, data] of [...this.catalog.theme.templates, ...this.catalog.theme.groups]) {
+      if (isInternalTemplate(rel) || data?.__error || excluded.has(rel)) continue;
+      files.set(rel, { data, origin: 'theme' });
+    }
+    files.set('config/settings_data.json', { data: this.catalog.theme.settingsData, origin: 'theme' });
+    for (const rel of this.projectFiles(slug)) {
+      if (!excluded.has(rel)) files.set(rel, { data: JSON.parse(fs.readFileSync(this.filePath(slug, rel), 'utf8')), origin: 'project' });
+    }
+    return files;
+  }
+
+  excluded(slug) {
+    return this.meta(slug).excluded || [];
+  }
+
+  // Alternate templates the store does not use (demo offers, help page…) stay out of the export,
+  // so they never appear in the admin's template picker with sample content.
+  setExcluded(slug, rel, exclude) {
+    const clean = checkRelativePath(rel);
+    if (!/^templates\/[a-z-]+\.[a-z0-9_-]+\.json$/.test(clean)) {
+      throw new Error(`seuls les modèles alternatifs (ex. templates/product.offers-bogo.json, templates/page.help.json) peuvent être retirés : « ${clean} » est un modèle de base dont la boutique a besoin`);
+    }
+    const meta = this.meta(slug);
+    this.#snapshot(slug, clean, { kind: 'exclusion', excluded: meta.excluded || [] });
+    const set = new Set(meta.excluded || []);
+    if (exclude) set.add(clean);
+    else set.delete(clean);
+    meta.excluded = [...set].sort();
+    meta.log = [...(meta.log || []), { at: new Date().toISOString(), file: clean, summary: exclude ? "retiré de l'export" : "remis dans l'export" }].slice(-60);
+    this.saveMeta(slug, meta);
+    return meta.excluded;
+  }
+
+  #snapshot(slug, rel, extra = null) {
+    const file = this.filePath(slug, rel);
+    const historyDir = path.join(this.dir(slug), '.history');
+    fs.mkdirSync(historyDir, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const existed = fs.existsSync(file);
+    const entry = extra ? { rel, ...extra, at: new Date().toISOString() } : { rel, existed, data: existed ? JSON.parse(fs.readFileSync(file, 'utf8')) : null, at: new Date().toISOString() };
+    sequence = (sequence + 1) % 100000;
+    const name = `${stamp}-${String(sequence).padStart(5, '0')}__${rel.replace(/\//g, '~')}`;
+    writeAtomic(path.join(historyDir, name), JSON.stringify(entry));
+  }
+
+  write(slug, rel, data, summary) {
+    const clean = checkRelativePath(rel);
+    const meta = this.meta(slug);
+    this.#snapshot(slug, clean);
+    writeAtomic(this.filePath(slug, clean), JSON.stringify(data, null, 2) + '\n');
+    meta.log = [...(meta.log || []), { at: new Date().toISOString(), file: clean, summary }].slice(-60);
+    this.saveMeta(slug, meta);
+    this.setCurrent(slug);
+  }
+
+  // Drops the project's version: the theme default applies again.
+  revert(slug, rel) {
+    const clean = checkRelativePath(rel);
+    const file = this.filePath(slug, clean);
+    if (!fs.existsSync(file)) return false;
+    this.#snapshot(slug, clean);
+    fs.unlinkSync(file);
+    const meta = this.meta(slug);
+    meta.log = [...(meta.log || []), { at: new Date().toISOString(), file: clean, summary: 'retour à la version du thème' }].slice(-60);
+    this.saveMeta(slug, meta);
+    return true;
+  }
+
+  history(slug, rel = null) {
+    const historyDir = path.join(this.dir(slug), '.history');
+    if (!fs.existsSync(historyDir)) return [];
+    return fs
+      .readdirSync(historyDir)
+      .sort()
+      .filter((name) => !rel || name.endsWith(`__${checkRelativePath(rel).replace(/\//g, '~')}`))
+      .map((name) => ({ name, ...JSON.parse(fs.readFileSync(path.join(historyDir, name), 'utf8')) }));
+  }
+
+  // Restores the state before the last change (of one file, or of the project).
+  undo(slug, rel = null) {
+    const entries = this.history(slug, rel);
+    const last = entries[entries.length - 1];
+    if (!last) throw new Error(rel ? `aucune modification à annuler pour ${rel}` : 'aucune modification à annuler');
+    const file = this.filePath(slug, last.rel);
+    fs.unlinkSync(path.join(this.dir(slug), '.history', last.name));
+    const meta = this.meta(slug);
+    if (last.kind === 'exclusion') meta.excluded = last.excluded;
+    else if (last.existed) writeAtomic(file, JSON.stringify(last.data, null, 2) + '\n');
+    else if (fs.existsSync(file)) fs.unlinkSync(file);
+    meta.log = [...(meta.log || []), { at: new Date().toISOString(), file: last.rel, summary: `annulation (état du ${last.at})` }].slice(-60);
+    this.saveMeta(slug, meta);
+    return last;
+  }
+
+  exportsDir(slug) {
+    return path.join(this.dir(slug), 'exports');
+  }
+}