@zohofinance/commerce 2.1.0 → 2.2.0

package/VALIDATIONS.md

@@ -0,0 +1,122 @@
+# Theme validation
+
+`theme dev` and `theme build` run the same checks on the theme in the current directory. Each finding is an **error** or a **warning**.
+
+## How findings are reported
+
+Findings are printed in groups: missing translation keys, invalid JSON, section and block schemas, page and section-group JSON, Liquid references, theme settings, oversized assets, and missing required files. Each line names the file and the problem. Errors are marked ❌. Warnings are marked ⚠️.
+
+| | `theme dev` | `theme build` |
+| --- | --- | --- |
+| Error | Preview is replaced with a validation page. The dev server stays up and rechecks when files change. | The errors are printed, the command throws, and no zip is written. |
+| Warning | Printed. Preview continues. | Printed. The zip is still written. |
+
+A section file that is missing `available_in` or a named preset is the one check whose severity depends on the command. It is a warning during `theme dev` and an error during `theme build`.
+
+Everything else below is an error unless it is marked as a warning.
+
+## Required files
+
+These files must exist:
+
+- `layouts/theme.liquid`
+- `i18n/en.json`
+- `i18n/en.schema.json`
+- `settings/schema.json`
+- `settings/theme.json`
+
+## JSON files
+
+Every `.json` file in the theme must parse.
+
+## Translation keys
+
+Every `"t:..."` key in `.liquid`, `.json`, `.js`, `.ts`, `.css`, and `.html` files must exist in `i18n/en.schema.json`.
+
+## Assets
+
+Each file under `assets/` must be 1 MB or smaller.
+
+## Section and block schemas
+
+Checked on the `{% schema %}` block in `sections/*.liquid` and `blocks/*.liquid`.
+
+- The schema must be valid JSON.
+- A block file with no schema is a **warning**.
+- A section file with no schema is treated as missing both `available_in` and a named preset.
+- `name` is required and must be a non-empty string. `tag` and `class`, when set, must be strings.
+- `max_blocks`, when set, must be a positive integer.
+
+### `available_in` and `presets` on sections
+
+Every `sections/*.liquid` file must have:
+
+- `available_in.templates` with at least one page
+- `presets` as an array, with every preset object carrying a non-empty `name`
+
+Preset objects may also include `settings`, `blocks`, and other defaults. A missing array, an empty array, or a preset without a name fails this check. `theme dev` logs it and still previews. `theme build` logs it, throws, and does not create the zip.
+
+Allowed page values are `index`, `cart`, `product`, `page`, `blog`, `blogs`, `collection`, `category`, `checkout`, `orders`, `search`, `404`, `header-group`, and `footer-group`. A value outside that list is a **warning** in both commands. A malformed `available_in` (not an object, `templates` not an array, or a non-string entry) is also a **warning**.
+
+Block files do not require `available_in` or `presets`.
+
+### Settings
+
+`settings` must be an array of objects.
+
+Accepted types: `checkbox`, `radio`, `select`, `collection`, `blog`, `form`, `category`, `product`, `menu`, `color`, `color_scheme`, `range`, `image_picker`, `media_picker`, `url`, `text`, `image`, `richtext`, `inline_richtext`, `header`. Any other type, including `textarea`, `preview_layout`, and `date`, is rejected.
+
+- `header` needs `content` and does not use `id`.
+- Every other type needs an `id`. A repeated `id` in the same settings array is a **warning**.
+- `meta`, when set, must be `desktop` or `mobile`.
+- `select` and `radio` need a non-empty `options` array. Each option needs `value` and `label`. `default` must be `{ display_name, value }`. A `default.value` that is not one of the option values is a **warning**.
+- `range` needs numeric `min` and `max` with `min < max`. `step`, when set, must be a positive number. A numeric `default` must fall inside min and max. `unit`, when set, must be a string.
+- `url` and `menu` need `default` `{ display_name, handle }`.
+- `collection`, `category`, `product`, and `blog` need `default.handle`.
+- `image_picker` needs `default.url`. `enable_customisation`, when set, must be a boolean.
+- `media_picker` needs `default.url`. `is_video` and `enable_customisation`, when set, must be booleans.
+- A `checkbox` `default` that is not a boolean is a **warning**.
+
+### Blocks declared in the schema
+
+- A local block needs `type`. `limit`, when set, must be a positive integer.
+- Nested `blocks` stop at depth 5.
+- `@theme`, `@widget`, `@app`, `zc_theme__…`, and `zc_app__…` are opt-ins. Their settings live in their own files and are not checked inline.
+- Each declared `zc_theme__<name>` must have `blocks/<name>.liquid`.
+
+### Preset contents
+
+When `presets` is present it must be an array of objects. `settings`, when set, must be an object. `blocks`, when set, must be an object keyed by block name, together with `block_order`. Storing `blocks` as an array is a **warning**: those blocks are ignored when the preset is applied. Each preset block type must be allowed by the container schema. Every `block_order` entry must be a key of `blocks`. Nesting stops at depth 5.
+
+## Theme settings
+
+- `settings/schema.json` must be an array of groups. Each group needs `name` and a `settings` array, checked with the setting rules above.
+- In `settings/theme.json`, `selected` is a preset name or `{ preset_name }`, and that name must be a key of `presets`.
+
+## Pages and section groups
+
+Checked on `pages/*.json` and on `sections/*.json` (header and footer groups).
+
+- `layout`, when set, must have `layouts/<layout>.liquid`.
+- `order` must be an array and `sections` must be an object.
+- Each `order` entry must name a section that exists in `sections` and has `type`. Listing the same section twice is a **warning**.
+- `sections/<type>.liquid` must exist. Types starting with `custom_section_` are stored outside the theme and are not looked up as theme files.
+- A section present in `sections` but missing from `order` is a **warning**. It is never rendered.
+- `blocks` and `block_order` must be set together: `blocks` is an object and `block_order` is an array.
+- Every `block_order` entry must exist in `blocks` and must have `type`.
+- A block type must be allowed by that container's schema `blocks`: an exact type, any `zc_theme__…` when `@theme` is declared, or any `zc_app__…` when `@widget` or `@app` is declared. Nested blocks are checked the same way, up to depth 5.
+- `zc_theme__<name>` must have `blocks/<name>.liquid`.
+- `block_order` longer than `max_blocks`, or more instances of a type than its `limit`, is rejected. That section does not render.
+- A block present in `blocks` but missing from `block_order` is a **warning**. It is never rendered.
+
+## Liquid
+
+Scanned in `layouts/`, `sections/`, `blocks/`, and `snippets/`. `{% schema %}`, `{% comment %}`, and `{% raw %}` blocks are skipped.
+
+These tags are rejected: `paginate`, `form`, `stylesheet`, `include`, `layout`, `highlight`, and any tag outside the set below.
+
+Accepted tags, including their end tags: `if`, `unless`, `case`, `for`, `tablerow`, `liquid`, `assign`, `capture`, `increment`, `decrement`, `echo`, `comment`, `raw`, `break`, `continue`, `cycle`, `render`, `section`, `sections`, `render_blocks`, `render_block`, `schema`, `style`, `javascript`.
+
+- `{% render 'name' %}` must have `snippets/name.liquid`.
+- `{% section 'name' %}` must have `sections/name.liquid`.
+- `{% sections 'name' %}` must have `sections/name.json`.

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@zohofinance/commerce",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "main": "ts-dist/index.js",
   "bin": {
     "zcommerce": "ts-dist/index.js"
   },
   "scripts": {
     "prepare": "yarn run build",
-    "build": "tsc && node scripts/copy-init-templates.mjs",
+    "build": "tsc && node scripts/copy-init-templates.mjs && chmod +x ts-dist/index.js",
     "dev": "yarn run build && node ts-dist/index.js",
     "lint:js:fix": "eslint . --fix",
     "lint": "yarn eslint src/",

package/public/dev-error.liquid

@@ -267,6 +267,55 @@
         color: #e0e0e0;
       }
 
+      .error-context h3 .issue-count {
+        display: inline-block;
+        margin-left: 6px;
+        padding: 0 8px;
+        border-radius: 10px;
+        background: #5a2a2a;
+        color: #ffb4b4;
+        font-size: 0.75rem;
+        font-weight: 600;
+      }
+
+      .issue-group {
+        margin: 0 0 14px;
+        padding: 10px 12px;
+        border-left: 3px solid #e5534b;
+        background: #333;
+        border-radius: 0 6px 6px 0;
+      }
+
+      .issue-message {
+        color: #f5f5f5;
+        font-weight: 500;
+      }
+
+      .issue-files-count {
+        margin-left: 8px;
+        color: #9a9a9a;
+        font-size: 0.8rem;
+        font-weight: 400;
+      }
+
+      .error-context ul.issue-files {
+        margin: 8px 0 0;
+        padding-left: 1.2rem;
+        list-style: disc;
+      }
+
+      .error-context ul.issue-files li {
+        margin-bottom: 3px;
+        font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+        font-size: 0.85rem;
+      }
+
+      .issue-where {
+        margin-left: 8px;
+        color: #9a9a9a;
+        font-size: 0.78rem;
+      }
+
       .error-context pre {
         background: transparent;
         padding: 0;

package/ts-dist/commands/build-theme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-theme.d.ts","sourceRoot":"","sources":["../../src/commands/build-theme.ts"],"names":[],"mappings":"AAsCA,UAAU,iBAAiB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,UAAU,oBAAoB;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB;AAoXD,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAclE;AAoED,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCzE;AASD,iBAAe,UAAU,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,iBAAiB;;;;2BAUa,oBAAoB;;GAoO/F;AAED,eAAe,UAAU,CAAC"}
+{"version":3,"file":"build-theme.d.ts","sourceRoot":"","sources":["../../src/commands/build-theme.ts"],"names":[],"mappings":"AAuCA,UAAU,iBAAiB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,UAAU,oBAAoB;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB;AAoXD,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAclE;AAoED,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCzE;AASD,iBAAe,UAAU,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,iBAAiB;;;;2BAUa,oBAAoB;;GAsQ/F;AAED,eAAe,UAAU,CAAC"}

package/ts-dist/commands/build-theme.js

@@ -6,13 +6,14 @@ import zlib from 'zlib';
 import mime from 'mime-types';
 import CleanCSS from 'clean-css';
 import ignore from 'ignore';
-import { exec, spawn } from 'child_process';
+import { spawn } from 'child_process';
 import { createRequire } from 'module';
 import lighthouse from 'lighthouse';
 import puppeteer from 'puppeteer';
 import { minify as terserMinify } from 'terser';
+import AdmZip from 'adm-zip';
 import { readJSONFileContent } from '../utils/file-operations.js';
-import { assertThemeValid, validateTheme } from '../utils/theme-validation.js';
+import { assertThemeValid, validateTheme, validationErrors, validationWarnings, formatValidationIssuesForConsole } from '../utils/theme-validation.js';
 import { transformFileSync } from '@babel/core';
 const FOLDERS_TO_COPY = [
     'assets',
@@ -506,7 +507,16 @@ async function buildTheme({ env, skipAudit }) {
     }
     try {
         spinner.text = 'Validating theme...';
-        assertThemeValid(await validateTheme(process.cwd(), { mode: 'build' }));
+        const validationResult = await validateTheme(process.cwd(), { mode: 'build' });
+        const warnings = validationWarnings(validationResult.issues);
+        const errors = validationErrors(validationResult.issues);
+        if (errors.length > 0) {
+            console.error(formatValidationIssuesForConsole(errors));
+        }
+        if (warnings.length > 0) {
+            console.error(formatValidationIssuesForConsole(warnings));
+        }
+        assertThemeValid(validationResult);
         spinner.text = 'Copying theme files...';
         if (fs.existsSync(zipFolderPath))
             fs.removeSync(zipFolderPath);
@@ -556,14 +566,31 @@ async function buildTheme({ env, skipAudit }) {
         }, null, 2), 'utf-8');
         spinner.text = 'Creating theme ZIP...';
         await new Promise((resolve, reject) => {
-            exec(`echo "Theme archive" | zip -r -z "${zipFolderPath}" layouts . -x "layouts" -x "*.DS_Store" -x "__MACOSX/*" -x "*.apk"`, { cwd: distFolderPath }, (error) => {
-                if (error) {
-                    reject(new Error(`ZIP creation failed: ${error.message}`));
-                }
-                else {
-                    resolve();
-                }
-            });
+            try {
+                const zip = new AdmZip();
+                const EXCLUDED_PATTERNS = ['.DS_Store', '__MACOSX', '.apk'];
+                const shouldExclude = (filePath) => EXCLUDED_PATTERNS.some((p) => filePath.includes(p));
+                const addDirToZip = (dir, zipPrefix) => {
+                    for (const entry of fs.readdirSync(dir)) {
+                        const fullPath = path.join(dir, entry);
+                        const zipPath = zipPrefix ? path.join(zipPrefix, entry) : entry;
+                        if (shouldExclude(fullPath))
+                            continue;
+                        if (fs.statSync(fullPath).isDirectory()) {
+                            addDirToZip(fullPath, zipPath);
+                        }
+                        else {
+                            zip.addFile(zipPath.split(path.sep).join('/'), fs.readFileSync(fullPath));
+                        }
+                    }
+                };
+                addDirToZip(distFolderPath, '');
+                zip.writeZip(zipFolderPath);
+                resolve();
+            }
+            catch (error) {
+                reject(new Error(`ZIP creation failed: ${error instanceof Error ? error.message : String(error)}`));
+            }
         });
         fs.removeSync(distFolderPath);
         spinner.succeed(chalk.green('Theme packaged successfully.'));

package/ts-dist/commands/serve-theme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve-theme.d.ts","sourceRoot":"","sources":["../../src/commands/serve-theme.ts"],"names":[],"mappings":"AA4DA,iBAAe,UAAU,CACvB,UAAU,CAAC,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,OAAO,EACnB,aAAa,CAAC,EAAE,OAAO,EACvB,OAAO,UAAO,EACd,QAAQ,CAAC,EAAE,MAAM,iBA2oDlB;AAED,eAAe,UAAU,CAAC"}
+{"version":3,"file":"serve-theme.d.ts","sourceRoot":"","sources":["../../src/commands/serve-theme.ts"],"names":[],"mappings":"AA8DA,iBAAe,UAAU,CACvB,UAAU,CAAC,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,OAAO,EACnB,aAAa,CAAC,EAAE,OAAO,EACvB,OAAO,UAAO,EACd,QAAQ,CAAC,EAAE,MAAM,iBA61DlB;AAED,eAAe,UAAU,CAAC"}