mcp-magento-cms 1.0.3 → 1.2.0

package/src/pageBuilderRepair.js

@@ -0,0 +1,266 @@
+/**
+ * Repair Magento Page Builder HTML so admin stage can open.
+ */
+
+import { validatePageBuilderContent, WIDTH_FOR_COUNT } from './pageBuilderValidate.js';
+
+function pbStyleId(length = 7) {
+  const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+  let out = '';
+  for (let i = 0; i < length; i++) {
+    out += alphabet[Math.floor(Math.random() * alphabet.length)];
+  }
+  return out;
+}
+
+function extractStyle(html) {
+  const m = html.match(/<style>([\s\S]*?)<\/style>/i);
+  return {
+    style: m ? m[1] : '',
+    body: html.replace(/<style>[\s\S]*?<\/style>/gi, ''),
+    hasStyle: Boolean(m),
+  };
+}
+
+function wrapWithStyle(style, body) {
+  return `<style>${style}</style>${body}`;
+}
+
+/**
+ * Remove CSS rules whose [data-pb-style=ID] is not present on any element.
+ * Orphans crash Magento stage-builder convertToInlineStyles (null setAttribute).
+ */
+function removeOrphanStyles(style, usedIds) {
+  // Split roughly on rule boundaries while keeping media queries intact enough for our use.
+  // Strategy: rewrite selectors that only reference orphan IDs out of comma-groups;
+  // drop rules that become empty.
+  return style.replace(
+    /#html-body[^{]*\{[^}]*\}/g,
+    (rule) => {
+      const head = rule.slice(0, rule.indexOf('{'));
+      const body = rule.slice(rule.indexOf('{'));
+      const selectors = head.split(',').map((s) => s.trim()).filter(Boolean);
+      const kept = selectors.filter((sel) => {
+        const id = (sel.match(/\[data-pb-style=([A-Z0-9]+)\]/i) || [])[1];
+        if (!id) return true;
+        return usedIds.has(id);
+      });
+      if (!kept.length) return '';
+      return `${kept.join(',')} ${body}`;
+    }
+  );
+}
+
+/**
+ * Ensure each column style id has a width rule; group by column-line siblings.
+ */
+function ensureColumnWidths(style, body) {
+  const injections = [];
+  // Split body by column-group and count columns per group
+  const parts = body.split(/(?=<div[^>]*data-content-type="column-group")/i);
+  const colBase =
+    'justify-content:flex-start;display:flex;flex-direction:column;' +
+    'background-position:left top;background-size:cover;background-repeat:no-repeat;' +
+    'background-attachment:scroll;align-self:stretch';
+
+  for (const part of parts.slice(1)) {
+    const cols = [
+      ...part.matchAll(
+        /data-content-type="column"[^>]*data-pb-style="([A-Z0-9]+)"/gi
+      ),
+    ].map((m) => m[1]);
+    if (!cols.length) continue;
+    const n = cols.length;
+    const width = WIDTH_FOR_COUNT[n] || `${(100 / n).toFixed(4)}%`;
+
+    const need = cols.filter((sid) => {
+      const rules = [
+        ...style.matchAll(
+          new RegExp(
+            `#html-body[^{]*\\[data-pb-style=${sid}\\][^{]*\\{([^}]*)\\}`,
+            'gi'
+          )
+        ),
+      ].map((m) => m[1]);
+      return !rules.some((r) => /width\s*:/.test(r));
+    });
+    if (!need.length) continue;
+    const selectors = need.map((sid) => `#html-body [data-pb-style=${sid}]`).join(',');
+    injections.push(`${selectors}{${colBase};width:${width}}`);
+  }
+
+  return style + injections.join('');
+}
+
+/**
+ * Convert full-bleed rows → full-width and ensure inner wrapper exists.
+ */
+function fixRowAppearances(body, styleInjections) {
+  let out = body;
+
+  // full-bleed → full-width on rows
+  out = out.replace(
+    /(data-content-type="row"[^>]*data-appearance=")full-bleed(")/gi,
+    '$1full-width$2'
+  );
+  out = out.replace(
+    /(data-appearance=")full-bleed("[^>]*data-content-type="row")/gi,
+    '$1full-width$2'
+  );
+
+  // For each full-width row missing inner, wrap children
+  const rowRe =
+    /<div\b([^>]*\bdata-content-type="row"[^>]*)>/gi;
+  const matches = [...out.matchAll(rowRe)];
+  // Process from end so indexes stay valid
+  for (let i = matches.length - 1; i >= 0; i--) {
+    const m = matches[i];
+    const attrs = m[1];
+    const appearance =
+      (attrs.match(/data-appearance="([^"]+)"/i) || [])[1] || '';
+    if (appearance !== 'full-width' && appearance !== 'contained') continue;
+
+    const openEnd = m.index + m[0].length;
+    const peek = out.slice(openEnd, openEnd + 220);
+    if (/data-element="inner"/.test(peek) || /row-full-width-inner/.test(peek)) {
+      continue;
+    }
+
+    // Find matching close for this row
+    let depth = 1;
+    let pos = openEnd;
+    let closeAt = -1;
+    while (pos < out.length && depth > 0) {
+      const nextOpen = out.indexOf('<div', pos);
+      const nextClose = out.indexOf('</div>', pos);
+      if (nextClose === -1) break;
+      if (nextOpen !== -1 && nextOpen < nextClose) {
+        depth += 1;
+        pos = nextOpen + 4;
+      } else {
+        depth -= 1;
+        if (depth === 0) {
+          closeAt = nextClose;
+          break;
+        }
+        pos = nextClose + 6;
+      }
+    }
+    if (closeAt === -1) continue;
+
+    const innerId = pbStyleId();
+    styleInjections.push(
+      `#html-body [data-pb-style=${innerId}]{background-position:left top;background-size:cover;background-repeat:no-repeat;background-attachment:scroll}`
+    );
+
+    let innerOpen;
+    if (appearance === 'full-width') {
+      innerOpen =
+        `<div class="row-full-width-inner" data-enable-parallax="0" data-parallax-speed="0.5" ` +
+        `data-background-images="{}" data-background-type="image" data-video-loop="true" ` +
+        `data-video-play-only-visible="true" data-video-lazy-load="true" data-video-fallback-src="" ` +
+        `data-element="inner" data-pb-style="${innerId}">`;
+    } else {
+      innerOpen =
+        `<div data-enable-parallax="0" data-parallax-speed="0.5" data-background-images="{}" ` +
+        `data-background-type="image" data-video-loop="true" data-video-play-only-visible="true" ` +
+        `data-video-lazy-load="true" data-video-fallback-src="" data-element="inner" ` +
+        `data-pb-style="${innerId}">`;
+    }
+
+    const inner = out.slice(openEnd, closeAt);
+    out =
+      out.slice(0, openEnd) +
+      innerOpen +
+      inner +
+      '</div>' +
+      out.slice(closeAt);
+  }
+
+  return out;
+}
+
+/**
+ * @param {string} html
+ * @param {{ stripSvg?: boolean, fixFullBleed?: boolean }} [options]
+ */
+export function repairPageBuilderContent(html, options = {}) {
+  const opts = {
+    stripSvg: options.stripSvg !== false,
+    fixFullBleed: options.fixFullBleed !== false,
+  };
+
+  let content = String(html || '');
+  const actions = [];
+  const before = validatePageBuilderContent(content);
+
+  let { style, body } = extractStyle(content);
+  const styleInjections = [];
+
+  if (opts.stripSvg) {
+    const next = body.replace(/<svg\b[^>]*>[\s\S]*?<\/svg>/gi, '');
+    if (next !== body) {
+      actions.push('Removed inline <svg> from content');
+      body = next;
+    }
+  }
+
+  // Escape bare & in title/alt attributes
+  const ampFixed = body.replace(
+    /(title|alt)="([^"]*)&(?!amp;|lt;|gt;|quot;|apos;|#)([^"]*)"/gi,
+    (_, attr, a, b) => `${attr}="${a}&amp;${b}"`
+  );
+  if (ampFixed !== body) {
+    actions.push('Escaped bare & in title/alt attributes');
+    body = ampFixed;
+  }
+
+  if (opts.fixFullBleed) {
+    const beforeBleed = body;
+    body = fixRowAppearances(body, styleInjections);
+    if (body !== beforeBleed || styleInjections.length) {
+      actions.push(
+        'Normalized rows to full-width/contained with required inner wrappers (no full-bleed)'
+      );
+    }
+  }
+
+  // Rebuild used ids after structural changes
+  const usedIds = new Set(
+    [...`${style}${body}`.matchAll(/data-pb-style="([A-Z0-9]+)"/gi)].map(
+      (m) => m[1]
+    )
+  );
+  // Also ids only in style that might still be referenced after edits — recompute from body only for orphans
+  const usedInBody = new Set(
+    [...body.matchAll(/data-pb-style="([A-Z0-9]+)"/gi)].map((m) => m[1])
+  );
+
+  const styleBeforeOrphans = style;
+  style = removeOrphanStyles(style, usedInBody);
+  if (style !== styleBeforeOrphans) {
+    actions.push('Removed orphan [data-pb-style] rules that crash admin stage');
+  }
+
+  const styleBeforeCols = style;
+  style = ensureColumnWidths(style, body);
+  if (style !== styleBeforeCols) {
+    actions.push('Added missing column width:% rules');
+  }
+
+  if (styleInjections.length) {
+    style += styleInjections.join('');
+    actions.push('Added style rules for new row inner wrappers');
+  }
+
+  content = wrapWithStyle(style, body);
+  const after = validatePageBuilderContent(content);
+
+  return {
+    content,
+    actions,
+    before,
+    after,
+    changed: content !== html,
+  };
+}

package/src/pageBuilderRules.js

@@ -0,0 +1,127 @@
+/**
+ * Magento Page Builder + CMS/theme hard rules (shared across all Adobe Commerce projects).
+ * Prefer native content types; keep HTML stage-safe for Admin Page Builder.
+ * Store-specific hex values, class prefixes, and folder catalogs belong in
+ * MAGENTO_CMS_PROJECT_RULES — not here.
+ */
+
+export const PAGEBUILDER_RULES = {
+  /**
+   * Row appearance:
+   * - Prefer "full-width" for content sections (bands, cards, heroes with gutters).
+   * - "contained" is OK for narrow text columns.
+   * - NEVER use "full-bleed" unless the user explicitly asks (edge-to-edge hero).
+   *
+   * full-width REQUIRES an inner wrapper:
+   *   <div class="row-full-width-inner" data-element="inner" ...>
+   * contained REQUIRES:
+   *   <div data-element="inner" ...>
+   * full-bleed has NO inner wrapper (children hang directly under row).
+   * Converting full-bleed → full-width without adding inner breaks Page Builder stage.
+   */
+  rowAppearance: {
+    preferred: 'full-width',
+    allowed: ['full-width', 'contained'],
+    forbiddenUnlessExplicit: ['full-bleed'],
+  },
+
+  /**
+   * Magento stage-builder.js convertToInlineStyles does:
+   *   element = document.querySelector(selector); element.setAttribute(...)
+   * If a <style> rule references [data-pb-style=ID] with no matching element,
+   * querySelector returns null → TypeError → "Page Builder Error" / stage won't open.
+   */
+  orphanStylesCrashStage: true,
+
+  /**
+   * Columns need width:% in the style block (25/33.3333/50/etc by column-line count).
+   */
+  columnsNeedWidths: true,
+};
+
+/** Stage-safe Page Builder rules (all projects). */
+export const PAGEBUILDER_RULES_SUMMARY = [
+  'CMS workflow (mandatory): use magento-cms MCP tools ONLY for creating/updating CMS pages and blocks (compose_pagebuilder, create_cms_page/block, update_cms_page/block, set_pagebuilder_html, repair_pagebuilder). Do NOT use project PHP compose/deploy scripts, bin/magento cms:*, or direct DB writes for CMS content.',
+  'Before any CMS create/update: call pagebuilder_rules, then list_section_types when composing. Prefer sections[] → compose_pagebuilder / create_cms_page; use set_pagebuilder_html only for intentional raw master HTML. Always validate (or repair_first) before save; flush/verify storefront after save.',
+  'Store views: create_cms_page/block defaults to All Store Views (store_id 0). Pass store_ids only when the user explicitly names particular store view(s).',
+  'Page layout: create_cms_page defaults to cms-full-width (Page — Full Width). Only pass page_layout when the user asks for a different layout.',
+  'When MCP is missing a capability or fails incorrectly: fix/improve the MCP package (mcp-magento-cms) — do not work around it with PHP scripts. Document the fix for the whole team.',
+  'Rows: use Full Width (or Contained). NEVER Full Bleed unless user explicitly asks.',
+  'When full-bleed IS intentional (edge-to-edge hero): pass allow_full_bleed=true and repair_first with fix_full_bleed=false (or repair_first=false).',
+  'full-width rows MUST include .row-full-width-inner[data-element=inner].',
+  'contained rows MUST include [data-element=inner].',
+  'Do not convert full-bleed→full-width without adding the inner wrapper.',
+  'Every [data-pb-style=ID] in <style> must match an element (orphans crash admin stage).',
+  'Every column needs a width:% rule in the style block.',
+  'Avoid raw <svg> inside Text elements (often crashes stage); use Image content type or theme CSS for icons.',
+  'Banner CTAs: use Banner Show Button=Always + Link URL (native .pagebuilder-banner-button) — editable in Admin Banner form.',
+  'Prefer native content types (Banner, Heading, Text, Image, Buttons, Columns, HTML) so merchants can edit without raw HTML.',
+  'Storefront links: prefer {{store url=path}} with an unquoted path; do not HTML-encode quotes as &quot; in href attributes.',
+  'Theme hooks: put project CSS on rows/banners via css_classes / data-css-classes — the theme owns class names; this MCP stays project-agnostic.',
+  'Landing composition: typically hero row (Banner) + body row(s) (Heading/Text/Columns/Image/Buttons); CMS body = page-specific content only (layout owns global chrome).',
+  'Card grids: Column → Image + Text (+ optional Buttons). Equal widths in the style block.',
+  'Compose complex pages with compose_pagebuilder({ sections }) covering all native Magento_PageBuilder types — not only Row→Text.',
+];
+
+/**
+ * Cross-project CMS media + theme conventions (all Magento stores using this MCP).
+ * Brand hex / Vendor/theme names stay in MAGENTO_CMS_PROJECT_RULES.
+ */
+export const CMS_THEME_CONVENTIONS_SUMMARY = [
+  'Media: one flat directory per CMS page under pub/media/wysiwyg/ — do NOT create cards/, icons/, products/, related/, or similar subfolders.',
+  'Media folder name MUST match the CMS page identifier (URL key), e.g. pub/media/wysiwyg/<section>/<page-url-key>/file.jpg (example: markets/market-industrial/hero.jpg).',
+  'Put all assets for that page (hero, cards, icons, products, related) directly in that single page folder.',
+  'When renaming a media folder, update all {{media url=…}} / path references in cms_page and cms_block content, then flush Magento cache.',
+  'Similar marketing/CMS pages MUST share the same CSS classes and one Magento_Cms LESS partial — do not duplicate a nearly identical LESS file per page in theme web/css/source/_sources.less.',
+  'Page-specific CMS LESS lives in the theme Magento_Cms/web/css/source/ override and is imported from Magento_Cms _module.less only (not theme _sources for page-only styles).',
+  'Define brand primary/secondary (and related tokens) once in the theme _theme.less (@theme__color__primary / @theme__color__secondary). Prefer those variables over hardcoded hex in page/module LESS.',
+  'Do not re-alias theme variables in module LESS (e.g. @local-primary: @theme__color__primary) — use the theme variable directly everywhere.',
+  'Do not redeclare font-family on page wrappers when body already uses the theme base font (@font-family-name__base / @font-family__base). Set font-family only when a different font is required.',
+  'Scope page styles with a stable hook (layout body class and/or content marker like :has(.page-hero)) so renaming the CMS URL key does not break styles when possible.',
+  'Avoid CSS !important in theme/CMS LESS. Prefer higher specificity: #html-body.<page-body-class> …, element+class (p.eyebrow, h2.page-h2), and deeper nesting under .column.main. Use !important only when a true inline style or third-party rule cannot be beaten otherwise — and leave a short comment why.',
+];
+
+/** Combined list returned by pagebuilder_rules (before optional project rules). */
+export const SHARED_RULES_SUMMARY = [
+  ...PAGEBUILDER_RULES_SUMMARY,
+  ...CMS_THEME_CONVENTIONS_SUMMARY,
+];
+
+export const SHARED_RULES_DETAIL = {
+  cms_workflow:
+    'Mandatory: magento-cms MCP only for CMS page/block content. Tools: pagebuilder_rules → compose_pagebuilder / create_* / set_pagebuilder_html / validate / repair. Forbidden: project PHP compose/deploy, CLI cms hacks, DB SQL for content. Improve the MCP when gaps appear — do not bypass it.',
+  row: 'Use Full Width or Contained. Never Full Bleed unless user explicitly asks.',
+  allow_full_bleed:
+    'When user asks for edge-to-edge hero: set_pagebuilder_html({ allow_full_bleed: true }) so repair keeps bleed and validate does not fail.',
+  full_width_inner:
+    'full-width rows MUST include <div class="row-full-width-inner" data-element="inner">…</div>',
+  contained_inner:
+    'contained rows MUST include <div data-element="inner">…</div>',
+  orphan_styles:
+    'Every [data-pb-style=ID] in <style> must exist on an element or admin stage crashes',
+  columns: 'Every column needs width:% in the style block',
+  banner_button:
+    'Hero CTAs: Banner appearance=poster, data-show-button=always, Link URL on banner, button text in .pagebuilder-banner-button — merchants edit via Banner form (Show Button / Button Text / Link).',
+  store_urls:
+    'Prefer {{store url=path}} with an unquoted path in href/Link URL. Avoid HTML-encoded quotes (&quot;) which break storefront links after cache.',
+  page_layout:
+    'create_cms_page defaults to cms-full-width (Page — Full Width). Only pass page_layout when the user asks for a different layout.',
+  theme_css:
+    'Attach project-specific styles via css_classes / data-css-classes on rows and banners. Theme LESS owns the class names; do not bake a store\'s prefixes into this MCP.',
+  composition:
+    'Typical marketing landing: hero row (Banner poster) + body row(s) with native Heading/Text/Columns/Image/Buttons. Keep global header/footer/widgets in layout XML, not duplicated in CMS HTML.',
+  cards:
+    'Product/feature cards: Column → Image + Text (+ optional Buttons). Prefer Image over SVG-in-Text for icons.',
+  media_layout:
+    'One flat folder per CMS page: pub/media/wysiwyg/<optional-section>/<cms-page-identifier>/ — folder name = page URL key; no nested cards/icons/products/related.',
+  less_location:
+    'Page-only styles → theme Magento_Cms/web/css/source/ + _module.less. Shared chrome may stay in theme web/css/source/_sources.less. Sibling pages share one LESS partial + shared classes.',
+  brand_tokens:
+    'Define @theme__color__primary / @theme__color__secondary (and related tokens) once in _theme.less. Use those variables directly in module LESS — no re-aliases, prefer vars over hex.',
+  fonts:
+    'If body already sets the theme base font, do not repeat font-family on page wrappers unless overriding to a different font.',
+  page_scope:
+    'Prefer layout body class and/or content :has() markers for page CSS scope so URL-key renames are safer.',
+  css_specificity:
+    'Avoid !important in theme/CMS LESS. Beat Magento/PB with #html-body.<page-class>, element.class, and .column.main nesting. Reserve !important for true inline/third-party cases only (comment why).',
+};

package/src/pageBuilderValidate.js

@@ -0,0 +1,164 @@
+/**
+ * Validate Magento Page Builder master-format HTML for admin stage safety.
+ */
+
+import { PAGEBUILDER_RULES, PAGEBUILDER_RULES_SUMMARY } from './pageBuilderRules.js';
+
+const WIDTH_FOR_COUNT = {
+  1: '100%',
+  2: '50%',
+  3: '33.3333%',
+  4: '25%',
+  5: '20%',
+  6: '16.6667%',
+};
+
+/**
+ * @param {string} html
+ * @param {{ allowFullBleed?: boolean }} [options]
+ * @returns {{
+ *   ok: boolean,
+ *   errors: string[],
+ *   warnings: string[],
+ *   stats: Record<string, number|string>,
+ *   orphans: string[],
+ *   missingStyles: string[],
+ *   columnsMissingWidth: string[],
+ *   rows: Array<{appearance:string, hasInner:boolean, className:string}>,
+ *   rules: string[],
+ * }}
+ */
+export function validatePageBuilderContent(html, options = {}) {
+  const errors = [];
+  const warnings = [];
+  const content = String(html || '');
+  const allowFullBleed = options.allowFullBleed === true;
+
+  if (!content.includes('data-content-type="row"')) {
+    errors.push('No Page Builder row found (data-content-type="row").');
+  }
+
+  const styleMatch = content.match(/<style>([\s\S]*?)<\/style>/i);
+  const style = styleMatch ? styleMatch[1] : '';
+  const body = content.replace(/<style>[\s\S]*?<\/style>/gi, '');
+
+  const idsDefined = new Set(
+    [...style.matchAll(/\[data-pb-style=([A-Z0-9]+)\]/gi)].map((m) => m[1])
+  );
+  const idsUsed = new Set(
+    [...content.matchAll(/data-pb-style="([A-Z0-9]+)"/gi)].map((m) => m[1])
+  );
+
+  const orphans = [...idsDefined].filter((id) => !idsUsed.has(id)).sort();
+  const missingStyles = [...idsUsed].filter((id) => !idsDefined.has(id)).sort();
+
+  if (orphans.length) {
+    errors.push(
+      `Orphan style IDs crash Page Builder stage (querySelector null): ${orphans.join(', ')}`
+    );
+  }
+  if (missingStyles.length) {
+    warnings.push(`Elements reference missing style IDs: ${missingStyles.join(', ')}`);
+  }
+
+  const fullBleed = [
+    ...body.matchAll(
+      /data-content-type="row"[^>]*data-appearance="full-bleed"|data-appearance="full-bleed"[^>]*data-content-type="row"/gi
+    ),
+  ];
+  if (fullBleed.length) {
+    const msg = `Found ${fullBleed.length} full-bleed row(s). Prefer full-width (with inner) or contained — full-bleed only when explicitly requested (edge-to-edge hero).`;
+    if (allowFullBleed) {
+      warnings.push(msg + ' (allowed via allow_full_bleed)');
+    } else {
+      errors.push(
+        msg + ' Pass allow_full_bleed=true on validate/set_pagebuilder_html when intentional.'
+      );
+    }
+  }
+
+  const rows = [];
+  const rowTagRe =
+    /<div\b([^>]*\bdata-content-type="row"[^>]*)>/gi;
+  let rm;
+  while ((rm = rowTagRe.exec(body))) {
+    const attrs = rm[1];
+    const appearance =
+      (attrs.match(/data-appearance="([^"]+)"/i) || [])[1] || 'unknown';
+    const className = (attrs.match(/\bclass="([^"]*)"/i) || [])[1] || '';
+    const peek = body.slice(rm.index + rm[0].length, rm.index + rm[0].length + 280);
+    const hasInner =
+      /data-element="inner"/.test(peek) || /row-full-width-inner/.test(peek);
+    rows.push({ appearance, hasInner, className });
+
+    if (appearance === 'full-width' && !hasInner) {
+      errors.push(
+        `full-width row missing .row-full-width-inner[data-element=inner] (class=${className || '—'}). Stage cannot open.`
+      );
+    }
+    if (appearance === 'contained' && !hasInner) {
+      errors.push(
+        `contained row missing [data-element=inner] (class=${className || '—'}).`
+      );
+    }
+  }
+
+  const columnIds = [
+    ...body.matchAll(/data-content-type="column"[^>]*data-pb-style="([A-Z0-9]+)"/gi),
+  ].map((m) => m[1]);
+
+  const columnsMissingWidth = [];
+  for (const sid of columnIds) {
+    const rules = [
+      ...style.matchAll(
+        new RegExp(
+          `#html-body[^{]*\\[data-pb-style=${sid}\\][^{]*\\{([^}]*)\\}`,
+          'gi'
+        )
+      ),
+    ].map((m) => m[1]);
+    if (!rules.some((r) => /width\s*:/.test(r))) {
+      columnsMissingWidth.push(sid);
+    }
+  }
+  if (columnsMissingWidth.length) {
+    errors.push(
+      `${columnsMissingWidth.length} column(s) missing width:% in <style> (e.g. ${columnsMissingWidth.slice(0, 5).join(', ')}).`
+    );
+  }
+
+  const svgCount = (content.match(/<svg\b/gi) || []).length;
+  if (svgCount) {
+    warnings.push(
+      `${svgCount} <svg> tag(s) in content — often crash Text content-type in admin stage.`
+    );
+  }
+
+  const ctypeCounts = {};
+  for (const m of content.matchAll(/data-content-type="([^"]+)"/g)) {
+    ctypeCounts[m[1]] = (ctypeCounts[m[1]] || 0) + 1;
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings,
+    stats: {
+      length: content.length,
+      rows: rows.length,
+      columns: columnIds.length,
+      styleIdsDefined: idsDefined.size,
+      styleIdsUsed: idsUsed.size,
+      svg: svgCount,
+      contentTypes: ctypeCounts,
+    },
+    orphans,
+    missingStyles,
+    columnsMissingWidth,
+    rows,
+    rules: PAGEBUILDER_RULES_SUMMARY,
+    ruleConfig: PAGEBUILDER_RULES.rowAppearance,
+  };
+}
+
+export { WIDTH_FOR_COUNT };

package/src/projectRules.js

@@ -0,0 +1,95 @@
+/**
+ * Optional per-store conventions for each Magento codebase.
+ * Keeps this MCP package project-agnostic.
+ *
+ * Resolution order:
+ * 1. MAGENTO_CMS_PROJECT_RULES (explicit path) — optional override
+ * 2. ${MAGENTO_ROOT}/.cursor/magento-cms-project-rules.json
+ * 3. ${MAGENTO_ROOT}/magento-cms-project-rules.json
+ *
+ * Prefer (2): commit `.cursor/magento-cms-project-rules.json` in the Magento
+ * project and set only MAGENTO_ROOT in that project's `.cursor/mcp.json`.
+ *
+ * File formats:
+ * - .json  → { "rules": string[], "detail"?: object }
+ * - .md / .txt → one rule per non-empty, non-# line
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+function candidatePaths() {
+  const out = [];
+  const configured = String(process.env.MAGENTO_CMS_PROJECT_RULES || '').trim();
+  if (configured) out.push(path.resolve(configured));
+
+  const root = String(process.env.MAGENTO_ROOT || '').trim();
+  if (root) {
+    const r = path.resolve(root);
+    out.push(path.join(r, '.cursor', 'magento-cms-project-rules.json'));
+    out.push(path.join(r, 'magento-cms-project-rules.json'));
+  }
+  return out;
+}
+
+function loadFromFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const ext = path.extname(filePath).toLowerCase();
+
+  if (ext === '.json') {
+    try {
+      const data = JSON.parse(raw);
+      const rules = Array.isArray(data.rules)
+        ? data.rules.map(String).filter(Boolean)
+        : [];
+      const detail =
+        data.detail && typeof data.detail === 'object' && !Array.isArray(data.detail)
+          ? Object.fromEntries(
+              Object.entries(data.detail).map(([k, v]) => [k, String(v)]),
+            )
+          : {};
+      return { rules, detail, source: filePath };
+    } catch (e) {
+      return {
+        rules: [`Invalid project rules JSON (${filePath}): ${e.message}`],
+        detail: {},
+        source: filePath,
+      };
+    }
+  }
+
+  const rules = raw
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('#') && !line.startsWith('//'));
+
+  return { rules, detail: {}, source: filePath };
+}
+
+/**
+ * @returns {{ rules: string[], detail: Record<string, string>, source: string|null }}
+ */
+export function loadProjectRules() {
+  const candidates = candidatePaths();
+  for (const filePath of candidates) {
+    const loaded = loadFromFile(filePath);
+    if (loaded) return loaded;
+  }
+
+  // Explicit env pointed at a missing file → warn once
+  const configured = String(process.env.MAGENTO_CMS_PROJECT_RULES || '').trim();
+  if (configured) {
+    const filePath = path.resolve(configured);
+    return {
+      rules: [`MAGENTO_CMS_PROJECT_RULES points to missing file: ${filePath}`],
+      detail: {},
+      source: filePath,
+    };
+  }
+
+  return { rules: [], detail: {}, source: null };
+}