@runwell/shopify-toolkit 0.4.0 → 0.5.0

package/bin/runwell-shopify

@@ -7,6 +7,7 @@ import { add } from '../lib/add.js';
 import { remove } from '../lib/remove.js';
 import { doctor } from '../lib/doctor.js';
 import { validate } from '../lib/validate.js';
+import { qa } from '../lib/qa.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -45,6 +46,9 @@ Commands:
   remove <module>                 Disable + clean a module's files
   doctor                          Detect drift between manifest and theme
   validate                        Run @shopify/dev-mcp validators on synced files
+  qa                              Code-first QA pipeline (validate-config, doctor,
+                                  template-integrity, orphan-assets, theme-check).
+                                  Run before any visual QA or "done" declaration.
   help                            Show this help
 
 Common options:
@@ -79,6 +83,9 @@ flags.toolkitRoot = TOOLKIT_ROOT;
       case 'validate':
         await validate(flags);
         break;
+      case 'qa':
+        await qa(flags);
+        break;
       case undefined:
       case 'help':
       case '--help':

package/lib/qa.js

@@ -0,0 +1,210 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { loadConfig, loadModuleManifest, resolveVariant } from './config-loader.js';
+
+/* qa: code-first QA pipeline for a Runwell-managed Shopify theme.
+
+   Runs in fixed order; each stage is non-fatal so callers see the full
+   picture before fixing. Exits 0 with a structured summary; exits 1 only
+   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
+
+   Caller can skip stages with --skip <name,name>.
+*/
+
+const STAGES = ['validate-config', 'doctor', 'template-integrity', 'orphan-assets', 'theme-check'];
+
+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));
+
+  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 @ ${targetDir}`);
+  console.log('');
+
+  // Stage 1: validate-config
+  if (!skip.has('validate-config')) {
+    console.log('1/5 validate-config');
+    try {
+      const { config } = loadConfig(flags.config || './runwell.config.json');
+      if (!config.client) log('errors', 'validate-config', 'missing required field "client"');
+      if (!config.store) log('warnings', 'validate-config', 'missing field "store" (registry lookups will fail)');
+      const enabled = Object.entries(config.modules || {}).filter(([, v]) => v.enabled !== false);
+      log('info', 'validate-config', `${enabled.length} modules enabled`);
+      for (const [name, entry] of enabled) {
+        try {
+          const m = loadModuleManifest(flags.toolkitRoot, name);
+          if (entry.variant) resolveVariant(m, entry.variant);
+        } catch (e) {
+          log('errors', 'validate-config', `${name}: ${e.message}`);
+        }
+      }
+    } catch (e) {
+      log('errors', 'validate-config', e.message);
+    }
+    console.log('');
+  }
+
+  // Stage 2: doctor (manifest drift)
+  if (!skip.has('doctor')) {
+    console.log('2/5 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)');
+    } else {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      let missing = 0;
+      for (const tracked of manifest.files) {
+        if (!fs.existsSync(path.join(targetDir, tracked.path))) {
+          log('errors', 'doctor', `tracked file missing: ${tracked.path}`);
+          missing++;
+        }
+      }
+      if (!missing) log('info', 'doctor', `${manifest.files.length} tracked files all present`);
+      log('info', 'doctor', `manifest toolkit version: ${manifest.toolkit_version}`);
+    }
+    console.log('');
+  }
+
+  // Stage 3: template-integrity (every section in templates/*.json must exist)
+  if (!skip.has('template-integrity')) {
+    console.log('3/5 template-integrity');
+    const tmplDir = path.join(targetDir, 'templates');
+    if (fs.existsSync(tmplDir)) {
+      const jsons = fs.readdirSync(tmplDir).filter(f => f.endsWith('.json'));
+      const sectionsDir = path.join(targetDir, 'sections');
+      const knownSections = new Set();
+      if (fs.existsSync(sectionsDir)) {
+        for (const f of fs.readdirSync(sectionsDir)) {
+          if (f.endsWith('.liquid')) knownSections.add(f.replace(/\.liquid$/, ''));
+        }
+      }
+      let badRefs = 0;
+      for (const jf of jsons) {
+        const tpath = path.join(tmplDir, jf);
+        let parsed;
+        try { parsed = JSON.parse(fs.readFileSync(tpath, 'utf8')); }
+        catch (e) { log('errors', 'template-integrity', `${jf}: invalid JSON: ${e.message}`); continue; }
+        const sections = parsed.sections || {};
+        const order = parsed.order || Object.keys(sections);
+        for (const id of order) {
+          if (!sections[id]) {
+            log('errors', 'template-integrity', `${jf}: order references unknown section id "${id}"`);
+            badRefs++;
+          } else {
+            const t = sections[id].type;
+            // Type can be a built-in (Dawn-shipped, no local file) or a section file we have
+            // Only flag if it looks like our convention (no group sections) and isn't found locally and is not a Dawn default name
+            if (t && t.startsWith('runwell-') && !knownSections.has(t)) {
+              log('errors', 'template-integrity', `${jf}: section "${id}" type "${t}" has no matching sections/${t}.liquid`);
+              badRefs++;
+            }
+          }
+        }
+      }
+      if (!badRefs) log('info', 'template-integrity', `${jsons.length} template files all reference valid sections`);
+    } else {
+      log('warnings', 'template-integrity', 'no templates/ directory');
+    }
+    console.log('');
+  }
+
+  // Stage 4: orphan-assets (runwell-* files in theme that aren't synced from any enabled module)
+  if (!skip.has('orphan-assets')) {
+    console.log('4/5 orphan-assets');
+    const manifestPath = path.join(targetDir, 'runwell-manifest.json');
+    if (fs.existsSync(manifestPath)) {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      const tracked = new Set(manifest.files.map(f => f.path));
+      const buckets = ['sections', 'snippets', 'assets', 'templates'];
+      let orphans = 0;
+      for (const b of buckets) {
+        const dir = path.join(targetDir, b);
+        if (!fs.existsSync(dir)) continue;
+        for (const f of fs.readdirSync(dir)) {
+          if (!f.startsWith('runwell-')) continue;
+          const rel = `${b}/${f}`;
+          if (!tracked.has(rel)) {
+            log('warnings', 'orphan-assets', `${rel} is runwell-prefixed but not in current manifest (stale sync?)`);
+            orphans++;
+          }
+        }
+      }
+      if (!orphans) log('info', 'orphan-assets', 'no orphans');
+    }
+    console.log('');
+  }
+
+  // Stage 5: theme-check via Shopify CLI (parse --output json for accuracy)
+  if (!skip.has('theme-check')) {
+    console.log('5/5 theme-check');
+    await new Promise(resolve => {
+      const proc = spawn('shopify', ['theme', 'check', '--path', targetDir, '--output', 'json'], {
+        stdio: ['ignore', 'pipe', 'pipe']
+      });
+      let stdout = '';
+      proc.stdout.on('data', d => stdout += d.toString());
+      proc.on('error', () => {
+        log('warnings', 'theme-check', 'shopify CLI not available; skipping');
+        resolve();
+      });
+      proc.on('exit', () => {
+        let parsed;
+        try { parsed = JSON.parse(stdout); } catch { parsed = null; }
+        if (!Array.isArray(parsed)) {
+          log('warnings', 'theme-check', 'could not parse output');
+          return resolve();
+        }
+        const offenses = parsed.flatMap(f => (f.offenses || []).map(o => ({ ...o, path: f.path })));
+        const errs = offenses.filter(o => o.severity === 'error' || o.severity === 0);
+        const warns = offenses.filter(o => o.severity === 'warning' || o.severity === 1);
+        if (errs.length === 0 && warns.length === 0) {
+          log('info', 'theme-check', 'clean');
+        } else {
+          // Per-check rollup so the summary is actionable
+          const byCheck = {};
+          for (const o of errs) byCheck[o.check] = (byCheck[o.check] || 0) + 1;
+          const top = Object.entries(byCheck).sort((a, b) => b[1] - a[1]).slice(0, 5)
+            .map(([c, n]) => `${c}×${n}`).join(', ');
+          log(errs.length ? 'errors' : 'warnings', 'theme-check',
+            `${errs.length} errors, ${warns.length} warnings${top ? ' (' + top + ')' : ''}`);
+          // List the file-level offenders so users can jump straight to fixes
+          const filesWithErr = [...new Set(errs.map(e => path.relative(targetDir, e.path)))];
+          for (const f of filesWithErr.slice(0, 8)) {
+            const n = errs.filter(e => path.relative(targetDir, e.path) === f).length;
+            log('errors', 'theme-check', `  ${f}: ${n} error(s)`);
+          }
+        }
+        resolve();
+      });
+    });
+    console.log('');
+  }
+
+  // Summary
+  console.log('---');
+  console.log(`Summary: ${findings.errors.length} errors, ${findings.warnings.length} warnings, ${findings.info.length} info`);
+  if (findings.errors.length) {
+    console.log('\nErrors (fix before declaring done):');
+    findings.errors.forEach(f => console.log(`  - [${f.stage}] ${f.msg}`));
+  }
+  if (findings.warnings.length) {
+    console.log('\nWarnings (review):');
+    findings.warnings.forEach(f => console.log(`  - [${f.stage}] ${f.msg}`));
+  }
+
+  if (findings.errors.length) process.exitCode = 2;
+}

package/lib/template.js

@@ -21,7 +21,8 @@ export function interpolate(source, vars) {
   let working = source;
 
   // Second pass: substitute {{config.X}} and {{brand.Y}} and {{client.Z}}
-  working = working.replace(/\{\{\s*([a-zA-Z][a-zA-Z0-9_.]*)\s*\}\}/g, (match, key) => {
+  // Keys can include hyphens (e.g. brand.rain-forrest) and dots for nesting.
+  working = working.replace(/\{\{\s*([a-zA-Z][a-zA-Z0-9_.\-]*)\s*\}\}/g, (match, key) => {
     // If the key starts with a Liquid keyword, leave it alone (it is Shopify Liquid)
     const liquidKeywords = new Set([
       'product', 'collection', 'cart', 'customer', 'shop', 'request',

package/modules/INDEX.md

@@ -44,7 +44,7 @@ Total modules: 31.
 | `reviews` | social-proof | (native build) | sections:1 | heading | (none) | (none) |
 | `risk-reversal` | conversion | (native build) | sections:1 | icon, heading, body, link_label, link_url, background_color, text_color | (none) | (none) |
 | `shipping-bar` | conversion | (native build) | sections:1 | threshold_cents, message_below, message_qualified, message_default, background_color, text_color | (none) | (none) |
-| `sticky-atc` | conversion | (native build) | sections:1 | (none) | (none) | (none) |
+| `sticky-atc` | conversion | Sticky Add To Cart Booster Pro and similar | sections:1 assets:1 | (none) | (none) | (none) |
 | `subscriptions` | catalog | Recharge / Bold Subscriptions / Appstle for the storefront display layer; subscription management still uses Shopify's native customer account | snippets:1 | one_time_label, subscribe_label, fineprint | (none) | install-shopify-subscriptions + create-selling-plan-group + enable-customer-account-tab |
 | `testimonials` | social-proof | (native build) | sections:1 | eyebrow, heading, background_color, text_color | (none) | (none) |
 | `trust-badges` | social-proof | (native build) | sections:1 | background_color, text_color | (none) | (none) |
@@ -243,8 +243,9 @@ Total modules: 31.
 ### sticky-atc
 
 - Category: conversion
-- What: Lushi sticky ATC module migrated from Lushi.
-- Files: sections:1
+- Replaces: Sticky Add To Cart Booster Pro and similar
+- What: Sticky add-to-cart bar that slides up from the bottom on PDP after the buy area scrolls out of view.
+- Files: sections:1 assets:1
 
 ### subscriptions
 

package/modules/sticky-atc/assets/runwell-sticky-atc.css

@@ -0,0 +1,117 @@
+/* Runwell sticky add-to-cart bar.
+   Slides up from bottom on scroll past the buy area; hides when the
+   main buy button returns to view (driven by IntersectionObserver in
+   the section template).
+*/
+
+.runwell-sticky-atc {
+  position: fixed;
+  inset: auto 0 0 0;
+  z-index: 60;
+  background: #FFFFFF;
+  border-top: 1px solid rgba(0, 0, 0, 0.08);
+  box-shadow: 0 -4px 16px rgba(0, 0, 0, 0.06);
+  transform: translateY(100%);
+  transition: transform 0.25s ease, opacity 0.25s ease;
+  opacity: 0;
+  visibility: hidden;
+}
+
+.runwell-sticky-atc[aria-hidden='false'] {
+  transform: translateY(0);
+  opacity: 1;
+  visibility: visible;
+}
+
+.runwell-sticky-atc__inner {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 0.75rem 1.25rem;
+}
+
+.runwell-sticky-atc__product {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  min-width: 0;
+}
+
+.runwell-sticky-atc__thumb {
+  width: 40px;
+  height: 40px;
+  border-radius: 4px;
+  object-fit: cover;
+  flex-shrink: 0;
+}
+
+.runwell-sticky-atc__meta {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.runwell-sticky-atc__title {
+  font-family: var(--font-heading-family, serif);
+  font-style: italic;
+  font-size: 0.95rem;
+  font-weight: 400;
+  line-height: 1.2;
+  color: var(--runwell-primary, #1A1A1A);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.runwell-sticky-atc__price {
+  font-family: var(--font-body-family, sans-serif);
+  font-size: 0.85rem;
+  font-weight: 500;
+  color: var(--runwell-primary, #1A1A1A);
+  opacity: 0.8;
+}
+
+.runwell-sticky-atc__form {
+  flex-shrink: 0;
+  margin: 0;
+}
+
+.runwell-sticky-atc__cta {
+  background: var(--runwell-primary, #1A1A1A);
+  color: #FFFFFF;
+  border: none;
+  border-radius: 0;
+  padding: 0.75rem 1.5rem;
+  font-family: var(--font-body-family, sans-serif);
+  font-size: 0.9rem;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  cursor: pointer;
+  transition: opacity 0.15s ease;
+}
+
+.runwell-sticky-atc__cta:hover {
+  opacity: 0.85;
+}
+
+.runwell-sticky-atc__cta:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+@media (max-width: 749px) {
+  .runwell-sticky-atc__inner {
+    padding: 0.6rem 0.9rem;
+  }
+  .runwell-sticky-atc__title {
+    font-size: 0.85rem;
+  }
+  .runwell-sticky-atc__cta {
+    padding: 0.6rem 1.1rem;
+    font-size: 0.8rem;
+  }
+}

package/modules/sticky-atc/module.json

@@ -1,14 +1,17 @@
 {
   "name": "sticky-atc",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "category": "conversion",
-  "description": "Lushi sticky ATC module migrated from Lushi.",
+  "description": "Sticky add-to-cart bar that slides up from the bottom on PDP after the buy area scrolls out of view. Native, no app. Replaces Sticky Add To Cart Booster Pro and similar.",
   "files": {
     "sections": [
       "sections/runwell-pdp-sticky.liquid"
+    ],
+    "assets": [
+      "assets/runwell-sticky-atc.css"
     ]
   },
   "config": {
     "schema": {}
   }
-}
+}

package/modules/sticky-atc/sections/runwell-pdp-sticky.liquid

@@ -5,6 +5,7 @@
 {%- endcomment -%}
 
 {%- if template == 'product' and product != blank -%}
+{{ 'runwell-sticky-atc.css' | asset_url | stylesheet_tag }}
 <div class="runwell-sticky-atc" data-runwell-sticky aria-hidden="true">
   <div class="runwell-sticky-atc__inner">
     <div class="runwell-sticky-atc__product">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runwell/shopify-toolkit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Reusable Shopify theme modules from Runwell. Replaces typically app-driven features (reviews, wishlist, urgency, FAQ, post-purchase upsell, exit popups, free-ship progress, sticky ATC, testimonials, badges, bundles) with native Liquid + JS + CSS that ship across multiple client themes via a config-driven sync CLI.",
   "type": "module",
   "main": "lib/index.js",