@runwell/shopify-toolkit 0.8.0 → 0.9.0

package/bin/runwell-shopify

@@ -8,6 +8,8 @@ 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 { init } from '../lib/init.js';
+import { upgradeBaseline } from '../lib/upgrade-baseline.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -49,6 +51,11 @@ Commands:
   qa                              Code-first QA pipeline (validate-config, doctor,
                                   template-integrity, orphan-assets, theme-check).
                                   Run before any visual QA or "done" declaration.
+  init <client>                   Scaffold a new tenant theme directory pinned to
+                                  the dawn-runwell baseline + toolkit. Use --baseline
+                                  to override the default pin.
+  upgrade-baseline <pkg@version>  Bump the baseline pin in runwell.config.json.
+                                  Run "runwell-shopify sync" after to apply.
   help                            Show this help
 
 Common options:
@@ -86,6 +93,12 @@ flags.toolkitRoot = TOOLKIT_ROOT;
       case 'qa':
         await qa(flags);
         break;
+      case 'init':
+        await init(flags);
+        break;
+      case 'upgrade-baseline':
+        await upgradeBaseline(flags);
+        break;
       case undefined:
       case 'help':
       case '--help':

package/lib/baseline.js

@@ -0,0 +1,203 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { interpolate } from './template.js';
+
+/* baseline.js: resolve, fetch, and apply the @runwell/dawn-runwell
+   baseline (or another baseline package) into a tenant theme dir.
+
+   Resolution order:
+   1. flags.baselinePath (CLI override)
+   2. config.baseline_path (local dev override in runwell.config.json)
+   3. config.baseline (e.g. "@runwell/dawn-runwell@^1.0.0") via the
+      cache at ~/.runwell/baseline-cache/<pkg>/<version>/
+*/
+
+const CACHE_DIR = path.join(os.homedir(), '.runwell', 'baseline-cache');
+
+export function parseBaselinePin(pin) {
+  if (!pin) return null;
+  // accept "@runwell/dawn-runwell@^1.0.0" or "@runwell/dawn-runwell@latest"
+  const m = pin.match(/^(@?[^@]+)@(.+)$/);
+  if (!m) return { name: pin, version: 'latest' };
+  return { name: m[1], version: m[2] };
+}
+
+export function resolveBaseline(flags, config) {
+  if (flags && flags.baselinePath) return flags.baselinePath;
+  if (config && config.baseline_path) return path.resolve(config.baseline_path);
+  if (!config || !config.baseline) return null;
+
+  const pin = parseBaselinePin(config.baseline);
+  if (!pin) return null;
+  const safeName = pin.name.replace('/', '__');
+  const versionDir = path.join(CACHE_DIR, safeName, pin.version);
+
+  if (fs.existsSync(path.join(versionDir, 'baseline-manifest.json'))) {
+    return versionDir;
+  }
+
+  // Cache miss: fetch via npm pack
+  console.log(`Fetching baseline: ${pin.name}@${pin.version} ...`);
+  fs.mkdirSync(versionDir, { recursive: true });
+  const packResult = spawnSync('npm', ['pack', `${pin.name}@${pin.version}`, '--pack-destination', versionDir], {
+    stdio: 'pipe',
+    encoding: 'utf8'
+  });
+  if (packResult.status !== 0) {
+    throw new Error(`npm pack failed: ${packResult.stderr || packResult.stdout}`);
+  }
+  const tarball = packResult.stdout.trim().split('\n').pop();
+  const tarPath = path.join(versionDir, tarball);
+  // npm pack delivers a tarball that extracts to ./package/
+  const tarResult = spawnSync('tar', ['-xzf', tarPath, '-C', versionDir, '--strip-components=1'], { stdio: 'inherit' });
+  if (tarResult.status !== 0) throw new Error('tar extract failed');
+  fs.unlinkSync(tarPath);
+  return versionDir;
+}
+
+export function loadBaselineManifest(baselineRoot) {
+  const p = path.join(baselineRoot, 'baseline-manifest.json');
+  if (!fs.existsSync(p)) {
+    throw new Error(`baseline-manifest.json not found at ${p}`);
+  }
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+export async function syncBaseline({ baselineRoot, targetDir, config, dryRun, written }) {
+  const manifest = loadBaselineManifest(baselineRoot);
+  console.log(`\n[baseline: ${manifest.name}@${manifest.version}]`);
+
+  const interpolationVars = {
+    config: {},
+    brand: config.brand || {},
+    client: { name: config.client, store: config.store }
+  };
+
+  // 1. Owned files (verbatim or interpolated)
+  for (const [bucket, files] of Object.entries(manifest.files || {})) {
+    if (!Array.isArray(files)) continue;
+    const targetSubdir = bucketToTargetDir(bucket, targetDir);
+    if (!targetSubdir) continue;
+    for (const rel of files) {
+      const sourcePath = path.join(baselineRoot, bucket, rel);
+      if (!fs.existsSync(sourcePath)) {
+        console.warn(`  [warn] missing baseline source: ${bucket}/${rel}`);
+        continue;
+      }
+      const filename = path.basename(rel);
+      const targetPath = path.join(targetSubdir, filename);
+      const isText = isTextFile(filename);
+      let content = fs.readFileSync(sourcePath, isText ? 'utf8' : null);
+      if (isText) content = interpolate(content, interpolationVars);
+      if (!dryRun) {
+        fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+        fs.writeFileSync(targetPath, content);
+      }
+      console.log(`  + ${path.relative(targetDir, targetPath)}`);
+      written.push({ source: 'baseline', target: targetPath, bucket, baseline_version: manifest.version });
+    }
+  }
+
+  // 2. Patches (deep-merge into existing tenant files)
+  for (const [tenantRel, patchRel] of Object.entries(manifest.patches || {})) {
+    const patchPath = path.join(baselineRoot, patchRel);
+    const tenantPath = path.join(targetDir, tenantRel);
+    if (!fs.existsSync(patchPath)) {
+      console.warn(`  [warn] missing baseline patch: ${patchRel}`);
+      continue;
+    }
+    if (!fs.existsSync(tenantPath)) {
+      console.warn(`  [warn] tenant file ${tenantRel} not present; skipping patch (run shopify theme pull first)`);
+      continue;
+    }
+    const patchData = JSON.parse(fs.readFileSync(patchPath, 'utf8'));
+    const tenantData = JSON.parse(fs.readFileSync(tenantPath, 'utf8'));
+    if (tenantRel === 'config/settings_schema.json') {
+      applySettingsPatches(tenantData, patchData);
+    } else if (tenantRel.startsWith('locales/')) {
+      deepMerge(tenantData, patchData.patches || {});
+    } else {
+      deepMerge(tenantData, patchData);
+    }
+    if (!dryRun) {
+      fs.writeFileSync(tenantPath, JSON.stringify(tenantData, null, 2) + '\n');
+    }
+    console.log(`  ~ patched ${tenantRel}`);
+    written.push({ source: 'baseline-patch', target: tenantPath, bucket: 'patch', baseline_version: manifest.version });
+  }
+}
+
+function applySettingsPatches(tenantSchema, patchDoc) {
+  // tenantSchema is an array of setting groups. patchDoc.patches is an array.
+  const patches = patchDoc.patches || [];
+  for (const patchGroup of patches) {
+    const existing = tenantSchema.find(g => g.name === patchGroup.name);
+    if (!existing) {
+      tenantSchema.push(patchGroup);
+    } else {
+      // Merge settings, skipping duplicates by id (or by content for header/paragraph)
+      const existingIds = new Set((existing.settings || []).map(s => s.id).filter(Boolean));
+      for (const s of patchGroup.settings || []) {
+        if (s.id && existingIds.has(s.id)) continue;
+        existing.settings = existing.settings || [];
+        existing.settings.push(s);
+      }
+    }
+  }
+}
+
+function deepMerge(target, source) {
+  for (const key of Object.keys(source)) {
+    if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
+      target[key] = target[key] || {};
+      deepMerge(target[key], source[key]);
+    } else {
+      target[key] = source[key];
+    }
+  }
+}
+
+function bucketToTargetDir(bucket, targetDir) {
+  switch (bucket) {
+    case 'assets':         return path.join(targetDir, 'assets');
+    case 'snippets':       return path.join(targetDir, 'snippets');
+    case 'sections':       return path.join(targetDir, 'sections');
+    case 'templates':      return path.join(targetDir, 'templates');
+    case 'layout':         return path.join(targetDir, 'layout');
+    case 'locales':        return path.join(targetDir, 'locales');
+    case 'config':         return path.join(targetDir, 'config');
+    default: return null;
+  }
+}
+
+function isTextFile(filename) {
+  const ext = path.extname(filename).toLowerCase();
+  return ['.liquid', '.js', '.css', '.json', '.html', '.svg', '.md', '.txt'].includes(ext);
+}
+
+export async function applyTenantOverrides({ targetDir, dryRun, written }) {
+  const overridesDir = path.join(targetDir, 'tenant-overrides');
+  if (!fs.existsSync(overridesDir)) return;
+  console.log(`\n[tenant-overrides]`);
+  walkAndCopy(overridesDir, targetDir, overridesDir, dryRun, written);
+}
+
+function walkAndCopy(srcRoot, dstRoot, currentDir, dryRun, written) {
+  for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+    const srcPath = path.join(currentDir, entry.name);
+    const rel = path.relative(srcRoot, srcPath);
+    const dstPath = path.join(dstRoot, rel);
+    if (entry.isDirectory()) {
+      walkAndCopy(srcRoot, dstRoot, srcPath, dryRun, written);
+    } else {
+      if (!dryRun) {
+        fs.mkdirSync(path.dirname(dstPath), { recursive: true });
+        fs.copyFileSync(srcPath, dstPath);
+      }
+      console.log(`  + ${rel}`);
+      written.push({ source: 'tenant-override', target: dstPath, bucket: 'override' });
+    }
+  }
+}

package/lib/init.js

@@ -0,0 +1,122 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/* runwell-shopify init <client> [--baseline <pin>]: scaffold a new
+   tenant theme directory with the minimum required files.
+*/
+
+export async function init(flags) {
+  const client = flags.positional && flags.positional[0];
+  if (!client) {
+    console.error('Usage: runwell-shopify init <client-name> [--baseline @runwell/dawn-runwell@^1.0.0] [--target ./<dir>]');
+    process.exit(1);
+  }
+
+  const targetDir = path.resolve(flags.target || `./${client}-shopify`);
+  if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+    console.error(`Target directory ${targetDir} is not empty. Choose another path or remove existing contents.`);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+  for (const d of ['layout', 'sections', 'snippets', 'assets', 'config', 'locales', 'templates', 'tenant-overrides']) {
+    fs.mkdirSync(path.join(targetDir, d), { recursive: true });
+  }
+
+  const baseline = flags.baseline || '@runwell/dawn-runwell@^1.0.0';
+
+  const config = {
+    client,
+    store: 'TODO.myshopify.com',
+    theme_path: '.',
+    baseline,
+    toolkit_version: '^0.9.0',
+    brand: {
+      name: client.charAt(0).toUpperCase() + client.slice(1),
+      primary: '#1A1A1A',
+      accent: '#D4AF37',
+      cream: '#F5EFE6',
+      currency: 'USD',
+      support_email: `support@${client}.com`,
+      tagline: ''
+    },
+    modules: {
+      '_shared/css-tokens': { enabled: true, config: {} }
+    }
+  };
+
+  fs.writeFileSync(path.join(targetDir, 'runwell.config.json'), JSON.stringify(config, null, 2) + '\n');
+
+  // Scaffold templates
+  fs.writeFileSync(
+    path.join(targetDir, 'templates', 'index.json'),
+    JSON.stringify({ sections: {}, order: [] }, null, 2) + '\n'
+  );
+  fs.writeFileSync(
+    path.join(targetDir, 'templates', 'product.json'),
+    JSON.stringify({
+      sections: {
+        main: {
+          type: 'main-product',
+          blocks: {
+            title: { type: 'title' },
+            price: { type: 'price' },
+            buy_buttons: { type: 'buy_buttons', settings: { show_dynamic_checkout: true } }
+          },
+          block_order: ['title', 'price', 'buy_buttons'],
+          settings: {}
+        }
+      },
+      order: ['main']
+    }, null, 2) + '\n'
+  );
+
+  // README
+  fs.writeFileSync(
+    path.join(targetDir, 'README.md'),
+    `# ${client} Shopify theme
+
+Tenant theme for ${client}, built on @runwell/dawn-runwell + @runwell/shopify-toolkit.
+
+## Lock context (always state these before any work)
+
+- Client: ${client}
+- Store: TODO.myshopify.com
+- Theme ID: TODO
+- Storefront password: TODO
+
+## Quick start
+
+\`\`\`bash
+# 1. Edit runwell.config.json with the real store handle + brand values
+# 2. Sync baseline + toolkit + tenant overrides into the theme dir
+runwell-shopify sync
+
+# 3. Code QA before any push
+runwell-shopify qa
+
+# 4. Push to a NEW unpublished theme on the store
+shopify theme push -u -s <store>.myshopify.com
+
+# 5. Once happy, push to the live theme
+shopify theme push -t <THEME_ID> -l -a -s <store>.myshopify.com
+\`\`\`
+
+## Layers
+
+1. \`@runwell/dawn-runwell\` baseline (pinned in runwell.config.json).
+2. \`@runwell/shopify-toolkit\` modules (declared in runwell.config.json modules block).
+3. This repo: \`tenant-overrides/\` directory + \`templates/*.json\` + bespoke sections + brand assets.
+
+\`runwell-manifest.json\` is regenerated on every sync and tracks file provenance.
+`
+  );
+
+  console.log(`Scaffolded ${client} tenant theme at ${targetDir}`);
+  console.log(`\nNext steps:`);
+  console.log(`  1. cd ${path.relative(process.cwd(), targetDir) || '.'}`);
+  console.log(`  2. Edit runwell.config.json: set store handle + brand values`);
+  console.log(`  3. runwell-shopify sync`);
+  console.log(`  4. runwell-shopify qa`);
+  console.log(`  5. shopify theme push -u -s <store>`);
+}

package/lib/sync.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { loadConfig, loadModuleManifest, listAvailableModules, resolveVariant } from './config-loader.js';
 import { interpolate } from './template.js';
+import { resolveBaseline, syncBaseline, applyTenantOverrides } from './baseline.js';
 
 export async function sync(flags) {
   const configPath = flags.config || './runwell.config.json';
@@ -18,6 +19,14 @@ export async function sync(flags) {
   const writtenFiles = [];
   const removedFiles = [];
 
+  // Stage 1: baseline (if configured). Owned files + patches first;
+  // toolkit module files in stage 2 will overlay on top, and tenant
+  // overrides in stage 3 win last.
+  const baselineRoot = resolveBaseline(flags, config);
+  if (baselineRoot) {
+    await syncBaseline({ baselineRoot, targetDir, config, dryRun, written: writtenFiles });
+  }
+
   const moduleNames = Object.keys(config.modules);
   for (const moduleName of moduleNames) {
     const cfgEntry = config.modules[moduleName];
@@ -77,15 +86,21 @@ export async function sync(flags) {
     }
   }
 
-  // Manifest
+  // Stage 3: tenant overrides (last; wins over baseline + toolkit).
+  await applyTenantOverrides({ targetDir, dryRun, written: writtenFiles });
+
+  // Manifest with provenance per file.
   const manifestPath = path.join(targetDir, 'runwell-manifest.json');
   const manifestData = {
     generated_at: new Date().toISOString(),
     toolkit_version: getToolkitVersion(flags.toolkitRoot),
+    baseline_version: writtenFiles.find(f => f.source === 'baseline')?.baseline_version || null,
     client: config.client,
     files: writtenFiles.map(f => ({
+      source: f.source || 'toolkit',
       module: f.module,
       bucket: f.bucket,
+      baseline_version: f.baseline_version,
       path: path.relative(targetDir, f.target)
     }))
   };

package/lib/upgrade-baseline.js

@@ -0,0 +1,25 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadConfig } from './config-loader.js';
+
+/* runwell-shopify upgrade-baseline <pin>: bump the baseline version pin
+   in runwell.config.json. Subsequent runwell-shopify sync uses the new
+   pin to fetch the new baseline. Caller is responsible for running sync
+   + qa + push afterwards.
+*/
+
+export async function upgradeBaseline(flags) {
+  const newPin = flags.positional && flags.positional[0];
+  if (!newPin) {
+    console.error('Usage: runwell-shopify upgrade-baseline <package@version>');
+    console.error('Example: runwell-shopify upgrade-baseline @runwell/dawn-runwell@1.1.0');
+    process.exit(1);
+  }
+  const configPath = path.resolve(flags.config || './runwell.config.json');
+  const { config } = loadConfig(configPath);
+  const oldPin = config.baseline || '(unset)';
+  config.baseline = newPin;
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  console.log(`baseline: ${oldPin} -> ${newPin}`);
+  console.log(`Run 'runwell-shopify sync' to apply, then 'runwell-shopify qa' before pushing.`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runwell/shopify-toolkit",
-  "version": "0.8.0",
+  "version": "0.9.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",