climaybe 3.0.9 → 3.1.1

package/src/lib/schema-builder.js

@@ -0,0 +1,242 @@
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SCHEMA_DIR = '_schemas';
+const LIQUID_DIRS = ['sections', 'blocks'];
+
+// Matches the inline-comment marker: {% # schema 'name' %}
+const MARKER_REGEX =
+  /\{%-?\s*#\s*schema\s+['"]([^'"]+)['"]\s*-?%\}/;
+
+// Matches the marker, then an optional inline-override marker, then an
+// optional existing generated {% schema %}...{% endschema %} block, all the
+// way to end-of-file.
+const MARKER_WITH_OUTPUT_REGEX =
+  /(\{%-?\s*#\s*schema\s+['"]([^'"]+)['"]\s*-?%\})([\s\S]*?)(\{%-?\s*schema\s*-?%\}[\s\S]*?\{%-?\s*endschema\s*-?%\})?\s*$/;
+
+// Matches an inline-comment override: {% # { "name": "Custom" } %}
+const INLINE_OVERRIDE_REGEX =
+  /\{%-?\s*#\s*(\{[\s\S]*?\})\s*-?%\}/;
+
+/**
+ * Resolve a schema source file (.js or .json) from the schemas directory.
+ */
+function resolveSchemaFile(schemasDir, name) {
+  const jsPath = join(schemasDir, `${name}.js`);
+  if (existsSync(jsPath)) return jsPath;
+  const jsonPath = join(schemasDir, `${name}.json`);
+  if (existsSync(jsonPath)) return jsonPath;
+  return null;
+}
+
+/**
+ * Load a schema module. CommonJS `.js` files are loaded via `createRequire`;
+ * `.json` files are parsed directly. Cache is busted on every load so
+ * rebuilds pick up changes without restarting the process.
+ */
+function loadSchemaModule(schemasDir, absolutePath) {
+  if (absolutePath.endsWith('.json')) {
+    return JSON.parse(readFileSync(absolutePath, 'utf-8'));
+  }
+
+  const localRequire = createRequire(join(schemasDir, '_entry.js'));
+  const resolved = localRequire.resolve(absolutePath);
+  delete localRequire.cache[resolved];
+  return localRequire(resolved);
+}
+
+/**
+ * Parse optional inline JSON.
+ */
+function parseInlineContent(raw) {
+  const trimmed = (raw || '').trim();
+  if (!trimmed) return {};
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Evaluate the schema export.
+ *
+ * - **Function exports** receive `(filename, inlineContent)` and must return
+ *   the schema object.
+ * - **Object exports** are shallow-merged with any inline content (inline wins).
+ */
+function evaluateSchema(schemaExport, sectionFilename, inlineContent) {
+  const raw = schemaExport?.default ?? schemaExport;
+  if (typeof raw === 'function') {
+    return raw(sectionFilename, inlineContent);
+  }
+  const hasInline = inlineContent && typeof inlineContent === 'object' && Object.keys(inlineContent).length > 0;
+  if (hasInline) {
+    return { ...raw, ...inlineContent };
+  }
+  return raw;
+}
+
+/**
+ * Process a single directory of liquid files (sections/ or blocks/).
+ */
+function processLiquidDir({ dirPath, dirName, schemasDir, dryRun, processed, skipped, errors }) {
+  if (!existsSync(dirPath)) return;
+
+  const files = readdirSync(dirPath, { withFileTypes: true })
+    .filter((d) => d.isFile() && d.name.endsWith('.liquid'))
+    .map((d) => d.name)
+    .sort();
+
+  for (const fileName of files) {
+    const filePath = join(dirPath, fileName);
+    const displayName = `${dirName}/${fileName}`;
+    const content = readFileSync(filePath, 'utf-8');
+
+    if (!MARKER_REGEX.test(content)) {
+      skipped.push(displayName);
+      continue;
+    }
+
+    if (!existsSync(schemasDir)) {
+      errors.push({
+        section: displayName,
+        schema: '(unknown)',
+        error: '_schemas/ directory not found',
+      });
+      continue;
+    }
+
+    const fullMatch = content.match(MARKER_WITH_OUTPUT_REGEX);
+    if (!fullMatch) {
+      skipped.push(displayName);
+      continue;
+    }
+
+    const marker = fullMatch[1];
+    const schemaName = fullMatch[2];
+    const betweenContent = fullMatch[3] || '';
+
+    const schemaFile = resolveSchemaFile(schemasDir, schemaName);
+    if (!schemaFile) {
+      errors.push({
+        section: displayName,
+        schema: schemaName,
+        error: `Schema file not found: _schemas/${schemaName}.js or .json`,
+      });
+      continue;
+    }
+
+    try {
+      const schemaExport = loadSchemaModule(schemasDir, schemaFile);
+
+      let inlineContent = {};
+      const inlineMatch = betweenContent.match(INLINE_OVERRIDE_REGEX);
+      if (inlineMatch) {
+        inlineContent = parseInlineContent(inlineMatch[1]);
+      }
+
+      const schema = evaluateSchema(schemaExport, fileName, inlineContent);
+      const json = JSON.stringify(schema, null, 2);
+      const generatedBlock = `{% schema %}\n${json}\n{% endschema %}`;
+
+      const markerIndex = content.indexOf(marker);
+      const beforeMarker = content.substring(0, markerIndex);
+
+      let inlineOverrideBlock = '';
+      if (inlineMatch) {
+        inlineOverrideBlock = '\n' + inlineMatch[0];
+      }
+
+      const newContent = beforeMarker + marker + inlineOverrideBlock + '\n' + generatedBlock + '\n';
+
+      if (!dryRun) {
+        writeFileSync(filePath, newContent, 'utf-8');
+      }
+      processed.push({ section: displayName, schemaName });
+    } catch (err) {
+      errors.push({
+        section: displayName,
+        schema: schemaName,
+        error: err.message,
+      });
+    }
+  }
+}
+
+/**
+ * Build section and block schemas for a Shopify theme project.
+ *
+ * Scans `sections/*.liquid` and `blocks/*.liquid` for an inline-comment marker:
+ *
+ *   {% # schema 'hero-banner' %}
+ *
+ * When found, resolves `_schemas/hero-banner.js` (or `.json`), evaluates it,
+ * and writes (or replaces) the generated `{% schema %}...{% endschema %}`
+ * block directly below the marker. The marker is never removed, so rebuilds
+ * always work — even after Shopify theme editor edits.
+ *
+ * @param {object}  options
+ * @param {string}  [options.cwd]    Theme project root (default `process.cwd()`).
+ * @param {boolean} [options.dryRun] When true, compute schemas without writing files.
+ * @returns {{ processed: Array<{section: string, schemaName: string}>, skipped: string[], errors: Array<{section: string, schema: string, error: string}> }}
+ */
+export function buildSchemas({ cwd = process.cwd(), dryRun = false } = {}) {
+  const schemasDir = join(cwd, SCHEMA_DIR);
+
+  const processed = [];
+  const skipped = [];
+  const errors = [];
+
+  for (const dirName of LIQUID_DIRS) {
+    processLiquidDir({
+      dirPath: join(cwd, dirName),
+      dirName,
+      schemasDir,
+      dryRun,
+      processed,
+      skipped,
+      errors,
+    });
+  }
+
+  return { processed, skipped, errors };
+}
+
+/**
+ * List available schema source files in `_schemas/`.
+ */
+export function listSchemaFiles(cwd = process.cwd()) {
+  const schemasDir = join(cwd, SCHEMA_DIR);
+  if (!existsSync(schemasDir)) return [];
+  return readdirSync(schemasDir, { withFileTypes: true })
+    .filter((d) => d.isFile() && (d.name.endsWith('.js') || d.name.endsWith('.json')))
+    .map((d) => d.name)
+    .sort();
+}
+
+/**
+ * List liquid files in sections/ and blocks/ that contain the inline-comment schema marker.
+ */
+export function listSectionsWithSchemaRefs(cwd = process.cwd()) {
+  const results = [];
+
+  for (const dirName of LIQUID_DIRS) {
+    const dirPath = join(cwd, dirName);
+    if (!existsSync(dirPath)) continue;
+
+    const files = readdirSync(dirPath, { withFileTypes: true })
+      .filter((d) => d.isFile() && d.name.endsWith('.liquid'));
+
+    for (const file of files) {
+      const content = readFileSync(join(dirPath, file.name), 'utf-8');
+      const match = content.match(MARKER_REGEX);
+      if (match) {
+        results.push({ section: `${dirName}/${file.name}`, schemas: [match[1]] });
+      }
+    }
+  }
+
+  return results;
+}

package/src/lib/theme-dev-kit.js

@@ -14,11 +14,14 @@ ignore:
 `,
   '.shopifyignore': `_styles
 _scripts
+.cursor
 .cursorrules
 .config
 .backups
 .github
 .vscode
+tools
+stores
 node_modules
 .gitignore
 LICENSE

package/src/lib/update-notifier.js

@@ -45,7 +45,19 @@ function canPromptForUpdate() {
   return Boolean(input.isTTY && output.isTTY && process.env.CI !== 'true');
 }
 
-export function resolveInstallScope({ packageDir, cwd = process.cwd() } = {}) {
+function isNodeModulesInstall(packageDir, packageName) {
+  if (!packageDir || !packageName) return false;
+  const normalized = resolve(packageDir);
+  const nm = `${join('node_modules', packageName)}`;
+  return normalized.includes(`${join('node_modules', '')}`) && normalized.endsWith(nm);
+}
+
+export function resolveInstallScope({ packageName, packageDir, cwd = process.cwd() } = {}) {
+  // Prefer using the *running* CLI install path to decide how to update.
+  // This prevents "update loops" where we update a project dependency while the
+  // user is actually running a global install (or vice-versa).
+  if (isNodeModulesInstall(packageDir, packageName)) return 'local';
+
   try {
     const globalRoot = execSync('npm root -g', { encoding: 'utf-8', stdio: 'pipe' }).trim();
     if (packageDir && resolve(packageDir).startsWith(resolve(globalRoot))) return 'global';
@@ -53,7 +65,8 @@ export function resolveInstallScope({ packageDir, cwd = process.cwd() } = {}) {
     // ignore and fallback to local checks
   }
 
-  if (existsSync(join(cwd, 'package.json'))) return 'local';
+  // If we don't have an install path, fall back to "am I in a project?"
+  if (!packageDir && existsSync(join(cwd, 'package.json'))) return 'local';
   return 'global';
 }
 
@@ -73,13 +86,14 @@ export function getLocalInstallFlag({ packageName, cwd = process.cwd() } = {}) {
 }
 
 function runUpdate(packageName, { packageDir, cwd = process.cwd() } = {}) {
-  const scope = resolveInstallScope({ packageDir, cwd });
+  const scope = resolveInstallScope({ packageName, packageDir, cwd });
   if (scope === 'global') {
     execSync(`npm install -g ${packageName}@latest`, { stdio: 'inherit' });
     return 'global';
   }
-  const flag = getLocalInstallFlag({ packageName, cwd });
-  execSync(`npm install ${packageName}@latest ${flag}`, { cwd, stdio: 'inherit' });
+  const installCwd = cwd || process.cwd();
+  const flag = getLocalInstallFlag({ packageName, cwd: installCwd });
+  execSync(`npm install ${packageName}@latest ${flag}`, { cwd: installCwd, stdio: 'inherit' });
   return 'local';
 }
 

package/src/workflows/build/build-pipeline.yml

@@ -5,6 +5,17 @@ name: Build Pipeline
 on:
   push:
     branches: ['**']
+    paths-ignore:
+      - '**/*.md'
+      - 'docs/**'
+      - '.github/**'
+      - '.cursor/**'
+      - '.claude/**'
+      - '.eser/**'
+      - 'README*'
+      - 'LICENSE*'
+      - 'CHANGELOG*'
+      - 'CONTRIBUTING*'
 
 jobs:
   build:
@@ -15,11 +26,13 @@ jobs:
       !contains(github.event.head_commit.message, '[hotfix-backport]')
       && !contains(github.event.head_commit.message, '[stores-to-root]')
       && !contains(github.event.head_commit.message, '[root-to-stores]')
+      && !(github.actor == 'github-actions[bot]' && contains(github.event.head_commit.message, 'chore(assets): update compiled javascript and css'))
     uses: ./.github/workflows/reusable-build.yml
 
   lighthouse-gate:
     runs-on: ubuntu-latest
     needs: [build]
+    if: needs.build.outputs.build_ran == 'true'
     outputs:
       run_lighthouse: ${{ steps.check.outputs.run_lighthouse }}
     env:
@@ -31,8 +44,11 @@ jobs:
         id: check
         run: |
           SKIP_REASONS=()
-          if [ "${{ github.ref }}" != "refs/heads/main" ] && [ "${{ github.ref }}" != "refs/heads/staging" ]; then
-            SKIP_REASONS+=("Not on main or staging branch (current: ${{ github.ref }})")
+          BR="${{ github.ref_name }}"
+          if [[ "$BR" == "staging" ]]; then
+            :
+          else
+            SKIP_REASONS+=("Lighthouse runs only on branch staging (current branch: $BR)")
           fi
           if [ -z "$SHOPIFY_STORE_URL" ] || [ -z "$SHOP_ACCESS_TOKEN" ] || [ -z "$LHCI_GITHUB_APP_TOKEN" ]; then
             SKIP_REASONS+=("Missing required secrets: SHOPIFY_STORE_URL, SHOP_ACCESS_TOKEN, or LHCI_GITHUB_APP_TOKEN")

package/src/workflows/build/reusable-build.yml

@@ -6,6 +6,9 @@ on:
       build-success:
         description: "Whether build was successful"
         value: ${{ jobs.build.outputs.success }}
+      build_ran:
+        description: "True when npm ci and at least one build step ran (path filters matched)"
+        value: ${{ jobs.build.outputs.build_ran }}
 
 jobs:
   build:
@@ -14,22 +17,25 @@ jobs:
       contents: write
     outputs:
       success: ${{ steps.build.outputs.success }}
+      build_ran: ${{ steps.run.outputs.build_ran }}
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
+      - name: Detect changed paths
+        uses: dorny/paths-filter@v3
+        id: changes
         with:
-          node-version: "24"
-
-      - name: Install dependencies from lockfile
-        run: |
-          if [ ! -f "package-lock.json" ]; then
-            echo "package-lock.json is required for deterministic build workflow installs."
-            exit 1
-          fi
-          npm ci
+          filters: |
+            scripts:
+              - '_scripts/**/*.js'
+              - 'assets/**/*.js'
+            tailwind:
+              - '**/*.liquid'
+              - '**/*.css'
+              - '_scripts/**/*.js'
+              - 'tailwind.config.*'
+              - 'postcss.config.*'
 
       - name: Detect build entrypoints
         id: detect
@@ -51,8 +57,42 @@ jobs:
             echo "scripts_minify=false" >> $GITHUB_OUTPUT
           fi
 
+      - name: Decide which build steps to run
+        id: run
+        run: |
+          SCRIPTS="${{ steps.changes.outputs.scripts }}"
+          TW="${{ steps.changes.outputs.tailwind }}"
+          HAS_SCR="${{ steps.detect.outputs.has_scripts }}"
+          HAS_STY="${{ steps.detect.outputs.has_styles }}"
+          run_scripts=false
+          run_tailwind=false
+          if [ "$SCRIPTS" = "true" ] && [ "$HAS_SCR" = "true" ]; then run_scripts=true; fi
+          if [ "$TW" = "true" ] && [ "$HAS_STY" = "true" ]; then run_tailwind=true; fi
+          if [ "$run_scripts" = "true" ] || [ "$run_tailwind" = "true" ]; then
+            echo "build_ran=true" >> $GITHUB_OUTPUT
+          else
+            echo "build_ran=false" >> $GITHUB_OUTPUT
+          fi
+          echo "run_scripts=$run_scripts" >> $GITHUB_OUTPUT
+          echo "run_tailwind=$run_tailwind" >> $GITHUB_OUTPUT
+
+      - name: Set up Node.js
+        if: steps.run.outputs.build_ran == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+
+      - name: Install dependencies from lockfile
+        if: steps.run.outputs.build_ran == 'true'
+        run: |
+          if [ ! -f "package-lock.json" ]; then
+            echo "package-lock.json is required for deterministic build workflow installs."
+            exit 1
+          fi
+          npm ci
+
       - name: Build scripts
-        if: steps.detect.outputs.has_scripts == 'true'
+        if: steps.run.outputs.build_ran == 'true' && steps.run.outputs.run_scripts == 'true'
         run: |
           if [ "${{ steps.detect.outputs.scripts_minify }}" = "true" ]; then
             npx --no-install climaybe build-scripts --minify
@@ -61,16 +101,12 @@ jobs:
           fi
 
       - name: Run Tailwind build
-        id: build
+        if: steps.run.outputs.build_ran == 'true' && steps.run.outputs.run_tailwind == 'true'
         run: |
-          if [ "${{ steps.detect.outputs.has_styles }}" = "true" ]; then
-            NODE_ENV=production npx --no-install climaybe build
-          else
-            echo "No _styles/main.css found; skipping Tailwind build."
-          fi
-          echo "success=true" >> $GITHUB_OUTPUT
+          NODE_ENV=production npx --no-install climaybe build
 
       - name: Commit and push changes
+        if: steps.run.outputs.build_ran == 'true'
         run: |
           git config --local user.email "action@github.com"
           git config --local user.name "GitHub Action"
@@ -89,3 +125,8 @@ jobs:
             git commit -m "chore(assets): update compiled javascript and css"
             git push origin "$BRANCH_NAME"
           fi
+
+      - name: Finalize success
+        id: build
+        if: success()
+        run: echo "success=true" >> $GITHUB_OUTPUT

package/src/workflows/multi/main-to-staging-stores.yml

@@ -141,7 +141,10 @@ jobs:
             exit 0
           fi
 
-          if ! git merge origin/main --no-ff -m "Sync main → $BRANCH"; then
+          # Keep generated assets branch-local to avoid chronic merge conflicts on staging branches.
+          # This does NOT prevent main changes from landing; it only resolves conflicts in favor
+          # of the current staging-<alias> branch when the same file was modified on both sides.
+          if ! git merge -X ours origin/main --no-ff -m "Sync main → $BRANCH"; then
             echo "Merge had conflicts; aborting. Manual resolution may be needed."
             git merge --abort 2>/dev/null || true
             exit 1

package/src/workflows/preview/pr-update.yml

@@ -10,10 +10,38 @@ on:
     branches: [main, staging, develop, 'staging-*', 'live-*']
 
 jobs:
+  filter:
+    runs-on: ubuntu-latest
+    outputs:
+      theme: ${{ steps.paths.outputs.theme }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dorny/paths-filter@v3
+        id: paths
+        with:
+          filters: |
+            theme:
+              - 'assets/**'
+              - 'blocks/**'
+              - 'config/**'
+              - 'layout/**'
+              - 'locales/**'
+              - 'sections/**'
+              - 'snippets/**'
+              - 'templates/**'
+              - '_scripts/**'
+              - '_styles/**'
+              - 'shopify.theme.toml'
+              - 'stores/**'
+
   extract-pr-number:
+    needs: [filter]
+    if: needs.filter.outputs.theme == 'true'
     uses: ./.github/workflows/reusable-extract-pr-number.yml
 
   validate-environment:
+    needs: [filter]
+    if: needs.filter.outputs.theme == 'true'
     runs-on: ubuntu-latest
     outputs:
       store_alias: ${{ steps.resolve.outputs.alias }}