@runwell/shopify-toolkit 0.18.0 → 0.21.0

package/bin/runwell-shopify

@@ -8,6 +8,7 @@ import { remove } from '../lib/remove.js';
 import { doctor } from '../lib/doctor.js';
 import { validate } from '../lib/validate.js';
 import { qa } from '../lib/qa.js';
+import { qaBundles } from '../lib/qa-bundles.js';
 import { init } from '../lib/init.js';
 import { upgradeBaseline } from '../lib/upgrade-baseline.js';
 import { diffBaseline } from '../lib/diff-baseline.js';
@@ -55,6 +56,9 @@ Commands:
   qa                              Code-first QA pipeline (validate-config, doctor,
                                   template-integrity, orphan-assets, theme-check).
                                   Run before any visual QA or "done" declaration.
+                                  Add --bundles to run the bundle-system check
+                                  (admin metafields, cross-supplier disclosure,
+                                  customizer contract) instead of the full pipeline.
   init <client>                   Scaffold a new tenant theme directory pinned to
                                   the dawn-runwell baseline + toolkit. Use --baseline
                                   to override the default pin.
@@ -98,7 +102,12 @@ flags.toolkitRoot = TOOLKIT_ROOT;
         await validate(flags);
         break;
       case 'qa':
-        await qa(flags);
+        if (flags.bundles) {
+          flags.toolkitRoot = flags.toolkitRoot || TOOLKIT_ROOT;
+          await qaBundles(flags);
+        } else {
+          await qa(flags);
+        }
         break;
       case 'init':
         await init(flags);

package/lib/list.js

@@ -59,33 +59,37 @@ function listTenants(flags) {
 
   console.log(`Runwell Shopify tenants (registry: ${registryPath})\n`);
   console.log(`Toolkit current: ${toolkitCurrent}\n`);
-  console.log('  Tenant     Store                                        Baseline pin                       Config pin    Synced ver   Modules  Drift  Status');
-  console.log('  ---------  -------------------------------------------  ---------------------------------  ------------  -----------  -------  -----  ----------');
+  console.log('  Tenant     Store                                        Config pin    Synced ver   Modules  Brand CSS  Drift  Status');
+  console.log('  ---------  -------------------------------------------  ------------  -----------  -------  ---------  -----  ----------');
 
   let drifters = 0;
+  let exposed = 0;
 
   for (const [slug, t] of tenants.sort((a, b) => a[0].localeCompare(b[0]))) {
     const store = (t.store || '?').padEnd(43);
     const tenantConfig = readTenantConfig(t.theme_repo_local);
-    const basePin = (tenantConfig?.baseline || t.baseline || '?').padEnd(33);
     const configPin = (tenantConfig?.toolkit_version || '?').padEnd(12);
     const syncedVer = (readManifestToolkit(t.theme_repo_local) || '?').padEnd(11);
     const moduleCount = (t.modules_enabled || []).length.toString().padEnd(7);
+    const brandCss = hasTenantBrandCss(slug, t.theme_repo_local) ? 'present  ' : 'MISSING  ';
+    if (brandCss.trim() === 'MISSING') exposed++;
     const drift = computeDrift(tenantConfig?.toolkit_version, toolkitCurrent);
     if (drift !== 'ok') drifters++;
     const driftStr = drift.padEnd(5);
     const status = (t.status || '?');
-    console.log(`  ${slug.padEnd(9)}  ${store}  ${basePin}  ${configPin}  ${syncedVer}  ${moduleCount}  ${driftStr}  ${status}`);
+    console.log(`  ${slug.padEnd(9)}  ${store}  ${configPin}  ${syncedVer}  ${moduleCount}  ${brandCss}  ${driftStr}  ${status}`);
   }
 
-  console.log(`\nTotal: ${tenants.length} tenants. Drift: ${drifters} of ${tenants.length} pinned below toolkit current (${toolkitCurrent}).`);
+  console.log(`\nTotal: ${tenants.length} tenants.`);
+  console.log(`  Drift: ${drifters} of ${tenants.length} pinned below toolkit current (${toolkitCurrent}).`);
+  console.log(`  Exposed: ${exposed} of ${tenants.length} missing tenant brand CSS (will inherit toolkit token changes raw).`);
 
   if (flags.verbose) {
     console.log('\nLegend:');
-    console.log('  Baseline pin: from runwell.config.json baseline field (truth source).');
-    console.log('  Config pin:   from runwell.config.json toolkit_version (truth source). ^X.Y.Z accepts forward minor bumps.');
-    console.log('  Synced ver:   actual toolkit version recorded by the last `runwell-shopify sync` (from runwell-manifest.json).');
-    console.log('  Drift:        "ok" if config-pin minor >= toolkit-current minor; "stale" if behind. "stale" with synced=current means the files are current but the pin lies.');
+    console.log('  Config pin: from runwell.config.json toolkit_version (truth source). ^X.Y.Z accepts forward minor bumps.');
+    console.log('  Synced ver: actual toolkit version recorded by the last `runwell-shopify sync` (from runwell-manifest.json).');
+    console.log('  Brand CSS:  "present" if assets/<tenant>-brand.css exists, "MISSING" if not. Per docs/CUSTOMIZATION-LEVELS.md, every tenant should ship one to insulate the storefront from upstream token tuning.');
+    console.log('  Drift:      "ok" if config-pin minor >= toolkit-current minor; "stale" if behind. "stale" with synced=current means the files are current but the pin lies.');
   }
 }
 
@@ -135,6 +139,15 @@ function readTenantConfig(themeRepoLocal) {
   }
 }
 
+function hasTenantBrandCss(slug, themeRepoLocal) {
+  if (!themeRepoLocal) return false;
+  const candidates = [
+    path.join(themeRepoLocal, 'assets', `${slug}-brand.css`),
+    path.join(themeRepoLocal, 'assets', 'tenant-brand.css'),
+  ];
+  return candidates.some(p => fs.existsSync(p));
+}
+
 function computeDrift(pin, current) {
   if (!pin || !current) return '?';
   const pinMinor = extractMinor(pin);

package/lib/qa-bundles.js

@@ -0,0 +1,117 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/* qa-bundles: cross-supplier and bundle metafield consistency check.
+
+   Invoked via `runwell-shopify qa --bundles`. Two layers:
+
+   A. Local checks (this file): manifest + contract integrity.
+   B. Store checks (deferred): per-bundle Shopify Admin GraphQL reads to
+      verify bundle_cross_supplier matches actual Carro supplier count.
+      Store checks land in BS-15 (Lushi integration) once the bundle
+      module is enabled on staging and a real bundle_index exists.
+
+   Local stages:
+   1. admin-metafields-defined  the 19 product metafields are present
+                                in modules/runwell-bundle-system/admin-metafields.json
+   2. disclosure-snippet-exists the cross-supplier disclosure renders
+                                guard `bundle_cross_supplier && bundle_supplier_count > 1`
+   3. settings-contract         the cross_supplier_disclosure customizer
+                                key is wired in settings.json with the
+                                {n} placeholder
+
+   The Shopify Admin API stage (store-bundle-audit) is stubbed and reports
+   "deferred" until BS-15 wires the live check. */
+
+export async function qaBundles(flags) {
+  const toolkitRoot = path.resolve(flags.toolkitRoot || process.cwd());
+  const moduleDir = path.join(toolkitRoot, 'modules', 'runwell-bundle-system');
+
+  const findings = { errors: [], warnings: [], info: [] };
+  const log = (level, stage, msg) => {
+    findings[level].push({ stage, msg });
+    const tag = level === 'errors' ? 'FAIL' : level === 'warnings' ? 'WARN' : 'OK  ';
+    console.log(`  [${tag}] ${stage}: ${msg}`);
+  };
+
+  console.log(`runwell-shopify qa --bundles @ ${toolkitRoot}`);
+  console.log('');
+
+  // 1. admin-metafields-defined
+  console.log('1/4 admin-metafields-defined');
+  const adminPath = path.join(moduleDir, 'admin-metafields.json');
+  if (!fs.existsSync(adminPath)) {
+    log('errors', 'admin-metafields-defined', 'admin-metafields.json missing');
+  } else {
+    try {
+      const admin = JSON.parse(fs.readFileSync(adminPath, 'utf8'));
+      const defs = admin.product_metafields?.definitions || [];
+      const required = [
+        'bundle_mode', 'bundle_pricing_model', 'bundle_pricing_value',
+        'bundle_components', 'bundle_quantity_tiers', 'bundle_cross_supplier',
+        'bundle_supplier_count'
+      ];
+      const present = new Set(defs.map(d => d.key));
+      const missing = required.filter(k => !present.has(k));
+      if (missing.length > 0) {
+        log('errors', 'admin-metafields-defined', `missing required keys: ${missing.join(', ')}`);
+      } else {
+        log('info', 'admin-metafields-defined', `${defs.length} definitions present, all required keys covered`);
+      }
+    } catch (e) {
+      log('errors', 'admin-metafields-defined', `admin-metafields.json invalid JSON: ${e.message}`);
+    }
+  }
+  console.log('');
+
+  // 2. disclosure-snippet-exists
+  console.log('2/4 disclosure-snippet-exists');
+  const snippetPath = path.join(moduleDir, 'snippets', 'runwell-bundle-cross-supplier.liquid');
+  if (!fs.existsSync(snippetPath)) {
+    log('errors', 'disclosure-snippet-exists', 'runwell-bundle-cross-supplier.liquid missing');
+  } else {
+    const snippet = fs.readFileSync(snippetPath, 'utf8');
+    if (!snippet.includes('bundle_supplier_count')) {
+      log('warnings', 'disclosure-snippet-exists', 'snippet does not reference bundle_supplier_count');
+    } else {
+      log('info', 'disclosure-snippet-exists', 'snippet present and references supplier_count');
+    }
+  }
+  console.log('');
+
+  // 3. settings-contract
+  console.log('3/4 settings-contract');
+  const settingsPath = path.join(moduleDir, 'settings.json');
+  if (!fs.existsSync(settingsPath)) {
+    log('errors', 'settings-contract', 'settings.json missing');
+  } else {
+    try {
+      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      const ids = (settings.settings || []).map(s => s.id);
+      if (!ids.includes('bundle_system__cross_supplier_disclosure')) {
+        log('errors', 'settings-contract', 'bundle_system__cross_supplier_disclosure missing from settings.json');
+      } else {
+        const setting = settings.settings.find(s => s.id === 'bundle_system__cross_supplier_disclosure');
+        if (!(setting.default || '').includes('{n}')) {
+          log('warnings', 'settings-contract', 'cross_supplier_disclosure default lacks {n} placeholder');
+        } else {
+          log('info', 'settings-contract', 'cross_supplier_disclosure wired with {n} placeholder');
+        }
+      }
+    } catch (e) {
+      log('errors', 'settings-contract', `settings.json invalid JSON: ${e.message}`);
+    }
+  }
+  console.log('');
+
+  // 4. store-bundle-audit (deferred until BS-15)
+  console.log('4/4 store-bundle-audit');
+  log('info', 'store-bundle-audit',
+    'deferred until BS-15. Will read each bundle product via Shopify Admin ' +
+    'GraphQL, count distinct Carro suppliers via product.metafields, and ' +
+    'flag mismatches with bundle_cross_supplier / bundle_supplier_count.');
+  console.log('');
+
+  console.log(`summary: ${findings.errors.length} errors, ${findings.warnings.length} warnings, ${findings.info.length} info`);
+  return findings;
+}

package/lib/qa.js

@@ -10,16 +10,19 @@ import { loadConfig, loadModuleManifest, resolveVariant } from './config-loader.
    if the theme cannot be inspected at all (no manifest, no config).
 
    Stages:
-   1. validate-config    runwell.config.json shape + module references
-   2. doctor             drift between runwell-manifest and synced files
-   3. template-integrity templates/*.json sections referenced in order
-   4. orphan-assets      runwell-* files with no matching enabled module
-   5. theme-check        shopify CLI theme-check (lint), if available
+   1. validate-config       runwell.config.json shape + module references
+   2. doctor                drift between runwell-manifest and synced files
+   3. template-integrity    templates/*.json sections referenced in order
+   4. orphan-assets         runwell-* files with no matching enabled module
+   5. brand-fields          {{brand.X}} references defined in tenant config
+   6. shared-token-impact   shared-token VALUE diffs between synced + toolkit-current
+                            cross-checked against tenant brand CSS coverage
+   7. theme-check           shopify CLI theme-check (lint), if available
 
    Caller can skip stages with --skip <name,name>.
 */
 
-const STAGES = ['validate-config', 'doctor', 'template-integrity', 'orphan-assets', 'brand-fields', 'theme-check'];
+const STAGES = ['validate-config', 'doctor', 'template-integrity', 'orphan-assets', 'brand-fields', 'shared-token-impact', 'theme-check'];
 
 /* Walk the toolkit modules tree and collect every {{brand.X}} reference.
    Returns the set of unique X identifiers (e.g. 'primary', 'rain-forrest',
@@ -43,6 +46,129 @@ function collectBrandFieldReferences(modulesDir) {
   return refs;
 }
 
+/* Parse a CSS file for top-level :root --runwell-X declarations.
+   Returns Map<token-name, value-string>. Whitespace-collapsed values so
+   identical sizes match regardless of formatting.
+
+   Brace-balanced block extraction. Naive regex (`/:root\s*\{(.*?)\}/`)
+   breaks on `{{brand.X}}` Liquid placeholders inside the root block:
+   the `}}` terminates the lazy match prematurely. This walker counts
+   braces and stops at the actual matching close. */
+function parseRunwellTokens(filePath) {
+  const out = new Map();
+  if (!fs.existsSync(filePath)) return out;
+  const content = fs.readFileSync(filePath, 'utf8');
+  const rootStart = content.search(/:root\s*\{/);
+  if (rootStart < 0) return out;
+  const openIdx = content.indexOf('{', rootStart);
+  let depth = 0;
+  let blockEnd = -1;
+  for (let i = openIdx; i < content.length; i++) {
+    const c = content[i];
+    if (c === '{') depth++;
+    else if (c === '}') {
+      depth--;
+      if (depth === 0) { blockEnd = i; break; }
+    }
+  }
+  if (blockEnd < 0) return out;
+  const block = content.slice(openIdx + 1, blockEnd);
+  // Strip Liquid placeholders so they don't break the value matcher
+  // (we treat the placeholder as the literal value; comparison logic
+  // upstream skips entries whose toolkit-current value starts with '{{').
+  const decl = /(--runwell-[a-z0-9-]+)\s*:\s*([^;]+);/gi;
+  let m;
+  while ((m = decl.exec(block)) !== null) {
+    out.set(m[1], m[2].replace(/\s+/g, ' ').trim());
+  }
+  return out;
+}
+
+/* Read tenant brand CSS files (if any) and collect every --runwell-X token
+   the tenant overrides at any cascade scope. Used to determine whether a
+   shared-token value change will reach the storefront or be masked. */
+function collectTenantTokenOverrides(targetDir, clientSlug) {
+  const overrides = new Set();
+  const candidates = [
+    path.join(targetDir, 'assets', `${clientSlug}-brand.css`),
+    path.join(targetDir, 'assets', 'tenant-brand.css'),
+  ];
+  for (const file of candidates) {
+    if (!fs.existsSync(file)) continue;
+    const content = fs.readFileSync(file, 'utf8');
+    const decl = /(--runwell-[a-z0-9-]+)\s*:/gi;
+    let m;
+    while ((m = decl.exec(content)) !== null) overrides.add(m[1]);
+  }
+  return overrides;
+}
+
+function runSharedTokenImpactProbe(targetDir, toolkitRoot, log) {
+  const sharedFiles = [
+    {
+      synced: path.join(targetDir, 'assets', 'runwell-tokens.css'),
+      current: path.join(toolkitRoot, 'modules', '_shared', 'css-tokens', 'assets', 'runwell-tokens.css'),
+      label: 'tokens',
+    },
+    {
+      synced: path.join(targetDir, 'assets', 'runwell-typography.css'),
+      current: path.join(toolkitRoot, 'modules', '_shared', 'css-typography', 'assets', 'runwell-typography.css'),
+      label: 'typography',
+    },
+  ];
+
+  let clientSlug = '';
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(targetDir, 'runwell.config.json'), 'utf8'));
+    clientSlug = cfg.client || '';
+  } catch { /* no config; probe still runs against synced vs current */ }
+
+  const tenantOverrides = clientSlug ? collectTenantTokenOverrides(targetDir, clientSlug) : new Set();
+  let totalDiffs = 0;
+  let exposedDiffs = 0;
+
+  for (const { synced, current, label } of sharedFiles) {
+    if (!fs.existsSync(synced)) {
+      log('warnings', 'shared-token-impact', `${label}: ${path.basename(synced)} missing in synced theme; cannot compare`);
+      continue;
+    }
+    if (!fs.existsSync(current)) {
+      log('warnings', 'shared-token-impact', `${label}: toolkit-current source not found at ${current}; cannot compare`);
+      continue;
+    }
+    const oldTokens = parseRunwellTokens(synced);
+    const newTokens = parseRunwellTokens(current);
+    const allKeys = new Set([...oldTokens.keys(), ...newTokens.keys()]);
+    for (const key of allKeys) {
+      const a = oldTokens.get(key);
+      const b = newTokens.get(key);
+      // Skip Liquid-interpolated tokens: brand colors get resolved from
+      // runwell.config.json during sync, so the toolkit-current placeholder
+      // is not directly comparable to the synced hex value. Only flag
+      // design-system tokens that ship with literal values.
+      if (b && b.includes('{{')) continue;
+      if (a && a.includes('{{')) continue;
+      if (a === b) continue;
+      totalDiffs++;
+      const insulated = tenantOverrides.has(key);
+      const verdict = insulated ? 'insulated' : 'EXPOSED';
+      const detail = a == null
+        ? `new token (will be added: ${b})`
+        : b == null
+          ? `token removed (was: ${a})`
+          : `${a} -> ${b}`;
+      const level = insulated ? 'info' : 'warnings';
+      if (!insulated) exposedDiffs++;
+      log(level, 'shared-token-impact', `${key}: ${detail} [${verdict}${insulated ? ' by tenant brand CSS' : '; tenant brand CSS does not override this token'}]`);
+    }
+  }
+  if (totalDiffs === 0) {
+    log('info', 'shared-token-impact', 'no shared-token value drift between synced theme and toolkit-current');
+  } else {
+    log('info', 'shared-token-impact', `${totalDiffs} shared tokens differ between synced and toolkit-current; ${exposedDiffs} would surface visually on next sync (no tenant override).`);
+  }
+}
+
 export async function qa(flags) {
   const targetDir = path.resolve(flags.target || process.cwd());
   const skip = new Set((flags.skip || '').split(',').map(s => s.trim()).filter(Boolean));
@@ -59,7 +185,7 @@ export async function qa(flags) {
 
   // Stage 1: validate-config
   if (!skip.has('validate-config')) {
-    console.log('1/6 validate-config');
+    console.log('1/7 validate-config');
     try {
       const { config } = loadConfig(flags.config || './runwell.config.json');
       if (!config.client) log('errors', 'validate-config', 'missing required field "client"');
@@ -82,7 +208,7 @@ export async function qa(flags) {
 
   // Stage 2: doctor (manifest drift)
   if (!skip.has('doctor')) {
-    console.log('2/6 doctor (manifest drift)');
+    console.log('2/7 doctor (manifest drift)');
     const manifestPath = path.join(targetDir, 'runwell-manifest.json');
     if (!fs.existsSync(manifestPath)) {
       log('errors', 'doctor', 'no runwell-manifest.json (run "runwell-shopify sync" first)');
@@ -103,7 +229,7 @@ export async function qa(flags) {
 
   // Stage 3: template-integrity (every section in templates/*.json must exist)
   if (!skip.has('template-integrity')) {
-    console.log('3/6 template-integrity');
+    console.log('3/7 template-integrity');
     const tmplDir = path.join(targetDir, 'templates');
     if (fs.existsSync(tmplDir)) {
       const jsons = fs.readdirSync(tmplDir).filter(f => f.endsWith('.json'));
@@ -146,7 +272,7 @@ export async function qa(flags) {
 
   // Stage 4: orphan-assets (runwell-* files in theme that aren't synced from any enabled module)
   if (!skip.has('orphan-assets')) {
-    console.log('4/6 orphan-assets');
+    console.log('4/7 orphan-assets');
     const manifestPath = path.join(targetDir, 'runwell-manifest.json');
     if (fs.existsSync(manifestPath)) {
       const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
@@ -172,7 +298,7 @@ export async function qa(flags) {
 
   // Stage 5: brand-fields (every {{brand.X}} reference in toolkit modules must be defined in tenant config.brand)
   if (!skip.has('brand-fields')) {
-    console.log('5/6 brand-fields');
+    console.log('5/7 brand-fields');
     try {
       const { config } = loadConfig(flags.config || './runwell.config.json');
       const brand = config.brand || {};
@@ -199,9 +325,17 @@ export async function qa(flags) {
     console.log('');
   }
 
-  // Stage 6: theme-check via Shopify CLI (parse --output json for accuracy)
+  // Stage 6: shared-token-impact (compare synced shared tokens vs toolkit-current;
+  // surface any value diffs and whether the tenant brand CSS overrides them)
+  if (!skip.has('shared-token-impact')) {
+    console.log('6/7 shared-token-impact');
+    runSharedTokenImpactProbe(targetDir, flags.toolkitRoot, log);
+    console.log('');
+  }
+
+  // Stage 7: theme-check via Shopify CLI (parse --output json for accuracy)
   if (!skip.has('theme-check')) {
-    console.log('6/6 theme-check');
+    console.log('7/7 theme-check');
     await new Promise(resolve => {
       const proc = spawn('shopify', ['theme', 'check', '--path', targetDir, '--output', 'json'], {
         stdio: ['ignore', 'pipe', 'pipe']

package/modules/INDEX.md

@@ -3,12 +3,12 @@
 Auto-generated by `scripts/generate-index.mjs`. Do not edit by hand.
 Skills (shopify-storefront, shopify-cro, shopify-cli-ops, shopify-admin-browser) grep this file before writing custom Liquid.
 
-Total modules: 38.
+Total modules: 39.
 
 ## By category
 
 - **branding**: care-coaching-medvi, product-trio-medvi
-- **catalog**: bundle-builder, quantity-breaks, subscriptions
+- **catalog**: bundle-builder, quantity-breaks, runwell-bundle-system, subscriptions
 - **conversion**: cart-cross-sell, cart-freeship-progress, cart-usps, exit-intent, gift-with-purchase, post-purchase-upsell, quick-view, risk-reversal, shipping-bar, sticky-atc
 - **customer**: loyalty-tiers, wishlist
 - **pdp**: comparison-table, delivery-estimate, inventory-urgency, pdp-ingredients, pdp-journal-link, pdp-trust-checks, recently-viewed
@@ -19,7 +19,7 @@ Total modules: 38.
 
 | Name | Category | Replaces | Files | Config keys | Variants | Admin steps |
 |---|---|---|---|---|---|---|
-| `bundle-builder` | catalog | BYOB-style bundle apps | sections:1 assets:1 | heading, sale_prefix, show_rating, rating_score, rating_count, show_trust_badges, trust_1, trust_2, trust_3, fomo_mode, fomo_cycle_days, fomo_stock_count | (none) | (none) |
+| `bundle-builder` | catalog | (native build) | sections:1 assets:1 | heading, sale_prefix, show_rating, rating_score, rating_count, show_trust_badges, trust_1, trust_2, trust_3, fomo_mode, fomo_cycle_days, fomo_stock_count | (none) | (none) |
 | `care-coaching-medvi` | branding | (native build) | sections:1 snippets:1 assets:1 | section_eyebrow, headline_pre, headline_post, headline_accent_color, block_heading, circular_text, circular_text_position, footer_link_label, layout, bg_band | (none) | (none) |
 | `cart-cross-sell` | conversion | Rebuy / OneClickUpsell pre-purchase upsell | snippets:1 | eyebrow, cta_label | (none) | (none) |
 | `cart-freeship-progress` | conversion | Bold Free Shipping Manager and similar app features | snippets:1 | threshold_cents, away_text, unlocked_message | (none) | (none) |
@@ -47,6 +47,7 @@ Total modules: 38.
 | `recently-viewed` | pdp | (native build) | sections:1 assets:2 | eyebrow, heading, background_color | (none) | (none) |
 | `reviews` | social-proof | (native build) | sections:1 assets:1 | heading | (none) | (none) |
 | `risk-reversal` | conversion | (native build) | sections:1 | icon, heading, body, link_label, link_url, background_color, text_color | (none) | (none) |
+| `runwell-bundle-system` | catalog | the legacy bundle-builder module | sections:6 snippets:8 assets:2 | surface_1_collection_page_enabled, surface_2_pdp_pairs_with_enabled, surface_3_home_stacks_enabled, surface_4_cart_drawer_xsell_enabled, surface_5_pdp_banner_enabled, surface_6_collection_filter_enabled, surface_2_eyebrow, surface_2_heading, surface_3_eyebrow, surface_3_heading, surface_4_eyebrow, surface_4_cta, surface_5_copy_template, cross_supplier_disclosure, home_strip_position | (none) | install-shopify-bundles + define-bundle-metafields + create-bundle-index-metaobject + create-first-bundle-product + configure-quantity-tier-discount-function + configure-free-gift-discount + create-bundles-collection-page-template + add-home-stacks-section + add-pdp-pairs-with-section + add-pdp-banner-section + verify-cart-drawer-coordination + rebuild-bundle-index |
 | `scrolling-ticker` | social-proof | announcement-bar / scrolling-text apps | sections:1 assets:1 | (none) | (none) | (none) |
 | `shipping-bar` | conversion | (native build) | sections:1 | threshold_cents, message_below, message_qualified, message_default, background_color, text_color | (none) | (none) |
 | `social-proof-banner` | social-proof | fixed-text social-proof apps | sections:1 assets:1 | (none) | (none) | (none) |
@@ -63,8 +64,7 @@ Total modules: 38.
 ### bundle-builder
 
 - Category: catalog
-- Replaces: BYOB-style bundle apps
-- What: Build-your-own-bundle PDP section.
+- What: DEPRECATED 2026-05-10 in favor of runwell-bundle-system (Mode A).
 - Files: sections:1 assets:1
 - Config: heading, sale_prefix, show_rating, rating_score, rating_count, show_trust_badges, trust_1, trust_2, trust_3, fomo_mode, fomo_cycle_days, fomo_stock_count
 
@@ -264,6 +264,15 @@ Total modules: 38.
 - Files: sections:1
 - Config: icon, heading, body, link_label, link_url, background_color, text_color
 
+### runwell-bundle-system
+
+- Category: catalog
+- Replaces: the legacy bundle-builder module
+- What: Configurable bundles engine.
+- Files: sections:6 snippets:8 assets:2
+- Config: surface_1_collection_page_enabled, surface_2_pdp_pairs_with_enabled, surface_3_home_stacks_enabled, surface_4_cart_drawer_xsell_enabled, surface_5_pdp_banner_enabled, surface_6_collection_filter_enabled, surface_2_eyebrow, surface_2_heading, surface_3_eyebrow, surface_3_heading, surface_4_eyebrow, surface_4_cta, surface_5_copy_template, cross_supplier_disclosure, home_strip_position
+- Admin steps: install-shopify-bundles + define-bundle-metafields + create-bundle-index-metaobject + create-first-bundle-product + configure-quantity-tier-discount-function + configure-free-gift-discount + create-bundles-collection-page-template + add-home-stacks-section + add-pdp-pairs-with-section + add-pdp-banner-section + verify-cart-drawer-coordination + rebuild-bundle-index
+
 ### scrolling-ticker
 
 - Category: social-proof

package/modules/bundle-builder/README.md

@@ -1,4 +1,9 @@
-# bundle-builder
+# bundle-builder (deprecated)
+
+> **Deprecated since toolkit 0.21.0.** Use `runwell-bundle-system` (Mode A: quantity tiers) instead.
+> This module continues to function for tenants pinned to it; removal target version is 0.22.0.
+>
+> **Migration path:** set `modules.bundle-builder.enabled` to false in `runwell.config.json`, enable `runwell-bundle-system`, and set `bundle_mode: "quantity_tiers"` on the bundle product via the `runwell.bundle_mode` metafield. See `_clients/capital-v/lushi/specs/bundle-system/phase-plan.md` v1.1 for the full Lusha cutover plan.
 
 PDP section for build-your-own-bundle merchandising. Slideshow gallery + thumbnail nav + radio bundle picker (1x / 2x / 3x with savings, free-ship and free-gift badges) + sticky ATC + FOMO countdown + scarcity. Migrated from Lusha's bundle-selector.
 

package/modules/bundle-builder/module.json

@@ -2,7 +2,11 @@
   "name": "bundle-builder",
   "version": "0.1.0",
   "category": "catalog",
-  "description": "Build-your-own-bundle PDP section. Slideshow gallery + thumbnail nav + radio bundle picker (1x / 2x / 3x with savings, free-ship and free-gift badges) + sticky ATC + FOMO countdown + scarcity. Migrated from Lusha (guabrasha-store/sections/bundle-selector.liquid). Replaces BYOB-style bundle apps.",
+  "deprecated": true,
+  "deprecated_in_favor_of": "runwell-bundle-system",
+  "deprecated_since": "0.21.0",
+  "removal_target_version": "0.22.0",
+  "description": "DEPRECATED 2026-05-10 in favor of runwell-bundle-system (Mode A). Build-your-own-bundle PDP section. Slideshow gallery + thumbnail nav + radio bundle picker (1x / 2x / 3x with savings, free-ship and free-gift badges) + sticky ATC + FOMO countdown + scarcity. Lusha migration to runwell-bundle-system Mode A happens in v1.1; module removed at toolkit 0.22.0.",
   "files": {
     "sections": ["sections/runwell-bundle-builder.liquid"],
     "assets": ["assets/runwell-bundle-builder.css"]

package/modules/cart-cross-sell/snippets/runwell-cart-xsell.liquid

@@ -3,8 +3,15 @@
   already in cart. Replaces Rebuy/OneClickUpsell pre-purchase upsell
   display. Render inside cart-drawer.liquid via:
   {% render 'runwell-cart-xsell' %}
+
+  BS-6 coordination: runwell-bundle-system Surface 4 (cart drawer
+  bundle cross-sell) takes priority on partial-bundle matches. When
+  that surface dispatches the `runwell:bundle-xsell-active` event,
+  this fallback removes itself so customers do not see two competing
+  upsell cards.
 {%- endcomment -%}
 
+<div data-runwell-cart-xsell-fallback>
 {%- if cart.item_count > 0 -%}
   {%- assign cart_handles = cart.items | map: 'handle' -%}
   {%- assign suggestion = blank -%}
@@ -38,3 +45,12 @@
     </div>
   {%- endif -%}
 {%- endif -%}
+</div>
+<script>
+  (function () {
+    document.addEventListener('runwell:bundle-xsell-active', function () {
+      var fallback = document.querySelector('[data-runwell-cart-xsell-fallback]');
+      if (fallback) fallback.remove();
+    });
+  })();
+</script>

package/modules/runwell-bundle-system/README.md

@@ -0,0 +1,35 @@
+# runwell-bundle-system
+
+Configurable bundles engine for Runwell Shopify tenants.
+
+## Modes
+- Mode A: single-product quantity tiers (Lusha pattern).
+- Mode B: curated multi-product bundles (Lushi pattern).
+- Mode C: mix-and-match / build-your-own (v1.5).
+- Mode D: subscription bundles (v2).
+
+## Display surfaces
+1. Dedicated /bundles collection page.
+2. PDP "Pairs well with" widget.
+3. Home page curated stacks.
+4. Cart drawer bundle cross-sell.
+5. PDP bundle banner.
+6. Collection page bundles filter.
+
+## Architecture
+Sits on top of Shopify's free first-party Bundles app. Reads per-bundle config from product metafields (namespace: runwell). See spec.md for the data model.
+
+## Replaces
+- bundle-builder (deprecated; Lusha migrates in v1.1).
+
+## Lineage
+Net-new Runwell module. Spec: `_clients/capital-v/lushi/specs/bundle-system/spec.md`.
+
+## Files in this module
+
+- `module.json`: module manifest, config schema, admin_steps array.
+- `admin-metafields.json`: source of truth for the 19 product metafields and the `bundle_index` shop metaobject. Source for `runwell-shopify provision-metafields` and merchant manual setup.
+- `settings.json`: theme customizer settings patch. Appended to tenant `config/settings_schema.json` by `runwell-shopify sync`.
+- `sections/`: one Liquid section per display surface (placeholders until BS-2 onwards).
+- `snippets/`: shared bundle UI partials (placeholders until BS-2 onwards).
+- `assets/`: module CSS and JS (placeholders until BS-2 onwards).

package/modules/runwell-bundle-system/admin-metafields.json

@@ -0,0 +1,46 @@
+{
+  "$comment": "Source of truth for runwell.bundle_* product metafield definitions. Mirrors spec.md section 2.1. Read by runwell-shopify provision-metafields (when implemented) and by admin-guide.md for manual setup.",
+  "spec_ref": "_clients/capital-v/lushi/specs/bundle-system/spec.md#21-per-bundle-product-metafields",
+  "product_metafields": {
+    "namespace": "runwell",
+    "owner_type": "PRODUCT",
+    "definitions": [
+      { "key": "bundle_mode", "name": "Bundle mode", "type": "single_line_text_field", "validations": [{ "name": "choices", "value": "[\"quantity_tiers\",\"multi_product\",\"mix_match\",\"subscription\"]" }] },
+      { "key": "bundle_pricing_model", "name": "Bundle pricing model", "type": "single_line_text_field", "validations": [{ "name": "choices", "value": "[\"tier_quantity\",\"fixed_price\",\"percent_off_subtotal\",\"dollar_off_subtotal\"]" }] },
+      { "key": "bundle_pricing_value", "name": "Bundle pricing value (JSON)", "type": "json", "description": "Shape varies by pricing_model. See spec.md section 2.2." },
+      { "key": "bundle_components", "name": "Bundle components (JSON)", "type": "json", "description": "Required for multi_product / mix_match. Array of {product_handle, qty}." },
+      { "key": "bundle_quantity_tiers", "name": "Bundle quantity tiers (JSON)", "type": "json", "description": "Required for quantity_tiers. Array of {qty, discount_pct}. Mirrors quantity_breaks schema." },
+      { "key": "bundle_show_in_catalog", "name": "Show in main catalog", "type": "boolean", "default": true },
+      { "key": "bundle_surfaces_enabled", "name": "Surfaces enabled (JSON)", "type": "json", "description": "Per-bundle surface allowlist. Array of 1..6. Absent = all enabled at tenant level." },
+      { "key": "bundle_copy", "name": "Per-surface copy (JSON)", "type": "json", "description": "Per-surface eyebrow/heading/cta overrides." },
+      { "key": "bundle_free_gift_enabled", "name": "Free gift enabled", "type": "boolean", "default": false },
+      { "key": "bundle_free_gift_handle", "name": "Free gift product handle", "type": "single_line_text_field" },
+      { "key": "bundle_fomo_mode", "name": "FOMO mode", "type": "single_line_text_field", "validations": [{ "name": "choices", "value": "[\"none\",\"discount\",\"scarcity\",\"both\"]" }] },
+      { "key": "bundle_fomo_cycle_days", "name": "FOMO cycle (days)", "type": "number_integer" },
+      { "key": "bundle_fomo_stock_count", "name": "FOMO stock count", "type": "number_integer" },
+      { "key": "bundle_cross_supplier", "name": "Cross-supplier", "type": "boolean", "default": false },
+      { "key": "bundle_supplier_count", "name": "Supplier count", "type": "number_integer" },
+      { "key": "bundle_savings_pct", "name": "Computed savings percent", "type": "number_decimal", "description": "Precomputed for fast banner / card render. Recomputed by runwell-shopify rebuild-bundle-index." },
+      { "key": "subscription_enabled", "name": "Subscription enabled (v2)", "type": "boolean", "default": false, "v2_only": true },
+      { "key": "subscription_interval", "name": "Subscription interval (JSON, v2)", "type": "json", "v2_only": true },
+      { "key": "subscription_discount_pct", "name": "Subscription discount percent (v2)", "type": "number_decimal", "v2_only": true },
+      { "key": "subscription_badge_copy", "name": "Subscription badge copy (v2)", "type": "single_line_text_field", "v2_only": true }
+    ]
+  },
+  "shop_metaobjects": [
+    {
+      "type": "bundle_index",
+      "name": "Bundle index",
+      "description": "Forward map (bundles -> components) and reverse map (products -> bundles) used by surfaces 2/4 to avoid N+1 reads. Single instance per shop. Rebuilt by runwell-shopify rebuild-bundle-index or by Shopify Flow on bundle product create/update.",
+      "field_definitions": [
+        { "key": "entries", "name": "Entries", "type": "json", "description": "{products: {handle: [bundle_handles]}, bundles: {handle: {components: {handle: qty}}}}" }
+      ]
+    }
+  ],
+  "cross_field_validation": [
+    { "rule": "bundle_quantity_tiers required when bundle_mode == 'quantity_tiers'", "enforced_by": "runwell-shopify qa --bundles" },
+    { "rule": "bundle_components required when bundle_mode in ['multi_product','mix_match']", "enforced_by": "runwell-shopify qa --bundles" },
+    { "rule": "bundle_pricing_value shape matches bundle_pricing_model (see spec.md section 2.2)", "enforced_by": "runwell-shopify qa --bundles" },
+    { "rule": "bundle_free_gift_handle required when bundle_free_gift_enabled == true", "enforced_by": "runwell-shopify qa --bundles" }
+  ]
+}