climaybe 3.3.0 → 3.4.0

package/README.md

@@ -250,6 +250,8 @@ When enabled, builds are **resilient**:
 - `init` may offer to create entrypoints; **default answer is No**.
 - Script bundling preserves comments/spacing and emits bundles only for root entry files (files imported by other top-level `_scripts/*.js` are inlined, not emitted separately).
 - Script bundles are written to `assets/*.js` (readable by default; use `climaybe build-scripts --minify` if you want minified output).
+- `assets/*.js`, `assets/style.css`, and the injected `{% schema %}` blocks are **generated outputs** — edit the source in `_scripts/`, `_styles/`, and `_schemas/` instead, since the watcher/build regenerate (and overwrite) the outputs on save and in CI.
+- **Orphan cleanup:** when `_scripts/` is in use, a full build (`climaybe build`, `climaybe build-scripts`, and the `serve` watcher) deletes any `assets/*.js` that no longer has a matching `_scripts/` source. Add new JS via a top-level `_scripts/<name>.js` entry, not by hand-editing `assets/`. Liquid-processed `*.js.liquid` assets and non-JS files are left untouched; targeted single-entry builds (`build-scripts <entry>`) skip pruning.
 - Live minified `assets/*` changes are intentionally excluded from hotfix backports to `main` (no branch-specific `.gitignore` split required).
 
 Build workflows install deps with `npm ci` and run `npx --no-install climaybe build-scripts` plus `npx --no-install climaybe build`, so CI uses lockfile-pinned versions (no `@latest` drift).

package/bin/version.txt

@@ -1 +1 @@
-3.3.0
+3.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "climaybe",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Shopify CLI by Electric Maybe for theme CI/CD workflows, branch orchestration, app setup, and dev tooling",
   "type": "module",
   "bin": {

package/src/commands/build-scripts.js

@@ -9,7 +9,7 @@ export async function buildScriptsCommand(opts = {}) {
   try {
     const minify = opts.minify === true;
     if (global.gc) global.gc();
-    const { bundles } = buildScripts({ cwd: process.cwd(), minify });
+    const { bundles, removed } = buildScripts({ cwd: process.cwd(), minify });
     if (!bundles || bundles.length === 0) {
       console.log(pc.yellow('  No _scripts/*.js entrypoints found; nothing to build.'));
       return;
@@ -20,6 +20,12 @@ export async function buildScriptsCommand(opts = {}) {
     for (const b of bundles) {
       console.log(pc.dim(`  - ${b.entryFile} → ${b.outputPath}`));
     }
+    if (removed && removed.length > 0) {
+      console.log(pc.yellow(`  Removed ${removed.length} orphan asset(s) with no _scripts source:`));
+      for (const name of removed) {
+        console.log(pc.dim(`  - assets/${name}`));
+      }
+    }
     if (global.gc) global.gc();
   } catch (err) {
     console.log(pc.red(`  Build error: ${err.message}`));

package/src/cursor/rules/00-rule-index.mdc

@@ -8,6 +8,7 @@ alwaysApply: true
 
 When you perform any of the following, **read and apply** the corresponding rule file from `.cursor/rules/`:
 
+- **Editing `assets/*.js` or `assets/style.css`, build outputs vs source, where to edit JS/CSS** → `project-overview.mdc` (Build Outputs vs Source — edit `_scripts/`/`_styles/`, never the generated `assets/` files)
 - **Git commits, commit messages** → `commit-rules.mdc`
 - **Accessibility, a11y, focus, WCAG, UI behavior** → `accessibility-rules.mdc`
 - **JavaScript, web components, _scripts/, *.js** → `javascript-standards.mdc`

package/src/cursor/rules/javascript-standards.mdc

@@ -1,7 +1,7 @@
 ---
 description: Professional JavaScript standards for Electric Maybe Shopify Theme. All JavaScript files must follow these patterns for consistency, performance, and maintainability.
 globs:
-  - "**/*.js"
+  - "_scripts/**/*.js"
   - "sections/*.liquid"
   - "snippets/*.liquid"
 alwaysApply: false
@@ -9,6 +9,8 @@ alwaysApply: false
 
 # JavaScript Development Standards
 
+> **Source vs build output:** Edit JavaScript in `_scripts/`. The CLI bundles `_scripts/*.js` into `assets/*.js` (`main.js` → `assets/index.js`) on every save and in CI, so `assets/*.js` is a **generated artifact** — never edit it directly, your changes will be overwritten. See `project-overview.mdc` (Build Outputs vs Source).
+
 ## Core Principles
 
 - **Zero external dependencies** - Use native browser APIs

package/src/cursor/rules/js-refactor-tasks.mdc

@@ -1,7 +1,7 @@
 ---
 description: JavaScript component refactor tasks and improvement tracking
 globs:
-  - "**/*.js"
+  - "_scripts/**/*.js"
 alwaysApply: false
 ---
 # JavaScript Component Refactor Tasks

package/src/cursor/rules/project-overview.mdc

@@ -55,8 +55,10 @@ Use `_scripts/electric-modal.js` as the gold standard for all web components.
 
 ## File Organization
 ```
-_scripts/        # Web components and utilities
-assets/          # Compiled CSS/JS and static assets
+_scripts/        # Source: web components and JS utilities (edit here)
+_styles/         # Source: Tailwind/CSS entrypoint (_styles/main.css)
+_schemas/        # Source: section/block schema definitions
+assets/          # GENERATED build outputs + static assets (do not hand-edit generated files)
 sections/        # Liquid section files
 snippets/        # Reusable Liquid snippets
 templates/       # Page templates
@@ -64,6 +66,22 @@ locales/         # Translation files
 config/          # Theme settings
 ```
 
+## Build Outputs vs Source
+
+`assets/` contains both static assets and **generated** build outputs. The CLI (`climaybe serve` / `climaybe build`) compiles sources into `assets/` and regenerates them on every save and in CI. Always edit the **source**, never the generated output:
+
+| Source (edit this) | Generated output (do NOT edit) |
+| --- | --- |
+| `_scripts/main.js` | `assets/index.js` |
+| `_scripts/<name>.js` (top-level entry) | `assets/<name>.js` |
+| `_styles/main.css` | `assets/style.css` |
+| `_schemas/<name>.js` / `.json` | injected `{% schema %}` block in `sections/*.liquid` & `blocks/*.liquid` |
+
+Notes:
+- JS bundling follows `import` statements: files imported by a top-level `_scripts/*.js` entry are **inlined** into that bundle, not emitted separately.
+- Any manual edit to `assets/index.js`, `assets/*.js`, or `assets/style.css` is **overwritten** on the next save (watcher) or build. Make JS changes in `_scripts/`, CSS in `_styles/`, and schema changes in `_schemas/`.
+- **Orphan cleanup:** on a full build (`climaybe build` / `climaybe build-scripts`, and the `serve` watcher), any `assets/*.js` that the current `_scripts/` build does not produce is **deleted** as a stale artifact. To add a new JS asset, create a top-level `_scripts/<name>.js` entry — do not drop a hand-written `.js` into `assets/` (it will be removed). Liquid-processed assets (`*.js.liquid`) and non-JS files are never touched.
+
 ## Code Review Requirements
 All code must pass the checklist in `javascript-standards.mdc` before merge.
 

package/src/cursor/rules/tailwindcss-rules.mdc

@@ -3,13 +3,14 @@ description: Tailwind CSS and theme token standards for Liquid and theme styles.
 globs:
   - "**/*.liquid"
   - "_styles/**/*.css"
-  - "assets/*.css"
 alwaysApply: false
 ---
 # Tailwind CSS Development Rules
 
 Apply when editing Liquid templates or theme CSS that use Tailwind classes or theme tokens. Use semantic tokens (surface, subtle, emphasis, accent, text-primary, border-secondary) from this project's `@theme`; see `_styles/02_base/02.02_colors.css`.
 
+> **Source vs build output:** Edit CSS in `_styles/` (entrypoint `_styles/main.css`). The CLI compiles it into `assets/style.css` on every save and in CI, so `assets/style.css` is a **generated artifact** — never edit it directly, your changes will be overwritten. See `project-overview.mdc` (Build Outputs vs Source).
+
 ## Core Principles
 
 ### 1. Static Class Generation

package/src/lib/build-scripts.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync, readdirSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, readdirSync, mkdirSync, unlinkSync } from 'node:fs';
 import { join, basename, dirname, normalize } from 'node:path';
 
 function extractImportRecords(content) {
@@ -161,6 +161,30 @@ function collectFilesToIsolate({ scriptsDir, entryFile }) {
   return isolateFiles;
 }
 
+function removeOrphanScriptAssets({ cwd, keepNames }) {
+  // Delete assets/*.js that this build did not produce. The Electric Maybe build
+  // model treats assets/*.js as generated output of _scripts/, so any *.js without
+  // a matching bundle output is stale and should be removed. Only plain *.js files
+  // are considered — Liquid-processed assets (e.g. *.js.liquid) are left untouched.
+  const assetsDir = join(cwd, 'assets');
+  if (!existsSync(assetsDir)) return [];
+
+  const removed = [];
+  for (const dirent of readdirSync(assetsDir, { withFileTypes: true })) {
+    if (!dirent.isFile()) continue;
+    const name = dirent.name;
+    if (!name.endsWith('.js')) continue;
+    if (keepNames.has(name)) continue;
+    try {
+      unlinkSync(join(assetsDir, name));
+      removed.push(name);
+    } catch {
+      // Best effort: a failed unlink shouldn't break the build.
+    }
+  }
+  return removed;
+}
+
 function listTopLevelEntrypoints(scriptsDir) {
   if (!existsSync(scriptsDir)) return [];
   return readdirSync(scriptsDir, { withFileTypes: true })
@@ -234,9 +258,18 @@ export function buildScripts({ cwd = process.cwd(), entry = null, minify = false
     }
   }
   if (entrypoints.length === 0) {
-    return { bundles: [] };
+    return { bundles: [], removed: [] };
   }
   const bundles = entrypoints.map((entryFile) => buildSingleEntrypoint({ cwd, entryFile, minify }));
-  return { bundles };
+
+  // Only prune orphans on a full build (no explicit entry). A targeted single-entry
+  // build must not delete the other bundles' outputs.
+  let removed = [];
+  if (!entry) {
+    const keepNames = new Set(bundles.map((b) => basename(b.outputPath)));
+    removed = removeOrphanScriptAssets({ cwd, keepNames });
+  }
+
+  return { bundles, removed };
 }
 

package/src/lib/dev-runtime.js

@@ -253,8 +253,11 @@ export function serveAssets({ cwd = process.cwd(), includeThemeCheck = false } =
   const scriptsDir = join(cwd, '_scripts');
   if (existsSync(scriptsDir)) {
     try {
-      buildScripts({ cwd });
+      const { removed } = buildScripts({ cwd });
       writeTaggedLine('scripts', pc.yellow, 'built (initial)');
+      if (removed?.length) {
+        writeTaggedLine('scripts', pc.yellow, `removed ${removed.length} orphan asset(s): ${removed.join(', ')}`);
+      }
     } catch (err) {
       writeTaggedLine('scripts', pc.yellow, `initial build failed: ${err.message}`, process.stderr);
     }
@@ -268,8 +271,11 @@ export function serveAssets({ cwd = process.cwd(), includeThemeCheck = false } =
         debounceMs: 300,
         onChange: () => {
           try {
-            buildScripts({ cwd });
+            const { removed } = buildScripts({ cwd });
             writeTaggedLine('scripts', pc.yellow, 'rebuilt');
+            if (removed?.length) {
+              writeTaggedLine('scripts', pc.yellow, `removed ${removed.length} orphan asset(s): ${removed.join(', ')}`);
+            }
           } catch (err) {
             writeTaggedLine('scripts', pc.yellow, `build failed: ${err.message}`, process.stderr);
           }
@@ -449,7 +455,10 @@ export function buildAll({ cwd = process.cwd() } = {}) {
 
   let scriptsOk = true;
   try {
-    buildScripts({ cwd });
+    const { removed } = buildScripts({ cwd });
+    if (removed?.length) {
+      writeTaggedLine('scripts', pc.yellow, `removed ${removed.length} orphan asset(s): ${removed.join(', ')}`);
+    }
   } catch (err) {
     console.log(pc.red(`\n  build-scripts failed: ${err.message}\n`));
     scriptsOk = false;