@runwell/shopify-toolkit 0.17.4 → 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';
@@ -44,7 +45,10 @@ function help() {
 
 Commands:
   sync                            Apply runwell.config.json to the target theme
-  list                            List available + installed modules
+  list                            List available + installed modules.
+                                  --tenants prints a cross-tenant matrix
+                                  (tenants x baseline pin x toolkit pin x
+                                  drift) read from shopify-toolkit-deployments.json.
   add <module>                    Enable a module in runwell.config.json
   remove <module>                 Disable + clean a module's files
   doctor                          Detect drift between manifest and theme
@@ -52,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.
@@ -95,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

@@ -1,8 +1,16 @@
 import path from 'node:path';
 import fs from 'node:fs';
+import os from 'node:os';
 import { listAvailableModules, loadModuleManifest, loadConfig } from './config-loader.js';
 
 export async function list(flags) {
+  if (flags.tenants) {
+    return listTenants(flags);
+  }
+  return listModules(flags);
+}
+
+function listModules(flags) {
   const available = listAvailableModules(flags.toolkitRoot);
 
   let installed = new Set();
@@ -29,3 +37,128 @@ export async function list(flags) {
 
   console.log(`\nTotal: ${available.length} modules. Installed in current config: ${installed.size}.`);
 }
+
+function listTenants(flags) {
+  const registryPath = resolveRegistryPath(flags);
+  if (!registryPath) {
+    console.error('Could not locate shopify-toolkit-deployments.json.');
+    console.error('Pass --registry <path>, set RUNWELL_DEPLOYMENT_REGISTRY env var, or place the file at ~/Documents/Code/claude-PM/infrastructure/config/shopify-toolkit-deployments.json');
+    process.exit(1);
+  }
+
+  const registry = JSON.parse(fs.readFileSync(registryPath, 'utf-8'));
+  const deployments = registry.deployments || {};
+  const tenants = Object.entries(deployments);
+
+  if (tenants.length === 0) {
+    console.log('No tenants in registry.');
+    return;
+  }
+
+  const toolkitCurrent = readToolkitVersion(flags.toolkitRoot);
+
+  console.log(`Runwell Shopify tenants (registry: ${registryPath})\n`);
+  console.log(`Toolkit current: ${toolkitCurrent}\n`);
+  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 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}  ${configPin}  ${syncedVer}  ${moduleCount}  ${brandCss}  ${driftStr}  ${status}`);
+  }
+
+  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('  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.');
+  }
+}
+
+function resolveRegistryPath(flags) {
+  if (flags.registry) {
+    return path.resolve(flags.registry);
+  }
+  if (process.env.RUNWELL_DEPLOYMENT_REGISTRY) {
+    return path.resolve(process.env.RUNWELL_DEPLOYMENT_REGISTRY);
+  }
+  const guesses = [
+    path.join(os.homedir(), 'Documents/Code/claude-PM/infrastructure/config/shopify-toolkit-deployments.json'),
+    path.resolve(flags.toolkitRoot, '../claude-PM/infrastructure/config/shopify-toolkit-deployments.json'),
+  ];
+  return guesses.find(p => fs.existsSync(p));
+}
+
+function readToolkitVersion(toolkitRoot) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(toolkitRoot, 'package.json'), 'utf-8'));
+    return pkg.version;
+  } catch {
+    return null;
+  }
+}
+
+function readManifestToolkit(themeRepoLocal) {
+  if (!themeRepoLocal) return null;
+  const manifestPath = path.join(themeRepoLocal, 'runwell-manifest.json');
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    const m = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    return m.toolkit_version || null;
+  } catch {
+    return null;
+  }
+}
+
+function readTenantConfig(themeRepoLocal) {
+  if (!themeRepoLocal) return null;
+  const configPath = path.join(themeRepoLocal, 'runwell.config.json');
+  if (!fs.existsSync(configPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+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);
+  const curMinor = extractMinor(current);
+  if (pinMinor == null || curMinor == null) return '?';
+  if (pinMinor >= curMinor) return 'ok';
+  return 'stale';
+}
+
+function extractMinor(version) {
+  const m = String(version).match(/(\d+)\.(\d+)/);
+  if (!m) return null;
+  return parseInt(m[1], 10) * 1000 + parseInt(m[2], 10);
+}

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']