@zohofinance/commerce 1.0.0 → 1.1.0

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/scripts/lint-section.mjs

@@ -0,0 +1,502 @@
+#!/usr/bin/env node
+/**
+ * lint-section.mjs — write-time lint for ZCommerce Liquid section files.
+ *
+ * Enforces code-quality budgets defined in code-quality.md.
+ *
+ * Usage:
+ *   node lint-section.mjs <path/to/section.liquid>
+ *
+ * Output: JSON report on stdout. Exits 0 on PASS, 1 on FAIL.
+ *
+ * Checks:
+ *   lines_under_250          file ≤ 250 lines
+ *   max_classes_per_el       no element with > 12 utility classes
+ *   max_dom_depth            HTML nesting ≤ 6 (excluding Liquid blocks)
+ *   empty_wrappers           0 wrappers whose only child is a single element with no layout role
+ *   if_nesting_depth         {% if %} nesting ≤ 2
+ *   single_liquid_block      all top-level {% assign %} consolidated into one {% liquid %} block
+ *   inline_event_handlers    0 onclick=/onload=/etc.
+ *   hardcoded_hex            0 hardcoded #rrggbb in inline style= or in {% style %} block
+ *   hardcoded_inline_px      0 px values in inline style= for font-size, padding, margin
+ *   schema_fields_wired      every schema setting id is referenced in markup
+ *   render_not_include       0 {% include %} (must use {% render %})
+ *   escape_user_output       warning if {{ var }} from settings is used in attribute context without | escape
+ *
+ * No external dependencies — pure Node.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const BUDGET = {
+  lines: 250,
+  classesPerElement: 12,
+  domDepth: 6,
+  ifDepth: 2,
+};
+
+// Args: <file> [--i18n <path-to-en.json>] [--i18n-schema <path-to-en.schema.json>]
+// If --i18n is omitted, the linter tries to auto-locate i18n/en.json by walking up
+// from the section file path. Provide the flags explicitly for snippets that live
+// outside a theme tree.
+const argv = process.argv.slice(2);
+const file = argv[0];
+if (!file || file.startsWith('--')) {
+  console.error('Usage: node lint-section.mjs <file> [--i18n <en.json>] [--i18n-schema <en.schema.json>]');
+  process.exit(2);
+}
+
+function flagValue(name) {
+  const i = argv.indexOf(name);
+  return i >= 0 && argv[i + 1] ? argv[i + 1] : null;
+}
+
+function autoLocateI18n(sectionPath) {
+  // Walk up from the section file looking for a sibling i18n/ folder.
+  // Typical layout: templates/<theme>/sections/foo.liquid → templates/<theme>/i18n/en.json
+  let dir = path.dirname(path.resolve(sectionPath));
+  for (let i = 0; i < 6; i++) {
+    const candidate = path.join(dir, 'i18n', 'en.json');
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+const i18nPath = flagValue('--i18n') || autoLocateI18n(file);
+const i18nSchemaPath = flagValue('--i18n-schema')
+  || (i18nPath ? path.join(path.dirname(i18nPath), 'en.schema.json') : null);
+
+const src = fs.readFileSync(file, 'utf-8');
+
+const report = { file, lines: src.split('\n').length, checks: {} };
+
+report.checks.lines_under_250 = {
+  pass: report.lines <= BUDGET.lines,
+  actual: report.lines,
+  budget: BUDGET.lines,
+};
+
+// Strip {% schema %}…{% endschema %} from the linted body to scope checks
+const bodyOnly = src.replace(/\{%-?\s*schema\s*-?%\}[\s\S]*?\{%-?\s*endschema\s*-?%\}/g, '');
+const schemaBlock = (src.match(/\{%-?\s*schema\s*-?%\}([\s\S]*?)\{%-?\s*endschema\s*-?%\}/) || [, ''])[1];
+
+// ── Tailwind class count per element ─────────────────────────────────────────
+{
+  const re = /class\s*=\s*"([^"]+)"/g;
+  let m, max = 0, worstSnippet = '';
+  while ((m = re.exec(bodyOnly))) {
+    const classes = m[1].trim().split(/\s+/).filter(Boolean);
+    // Skip dynamic Liquid-only class strings ({{ ... }}) — count what's there literally
+    const staticCount = classes.filter((c) => !c.includes('{{') && !c.includes('{%')).length;
+    if (staticCount > max) { max = staticCount; worstSnippet = m[0].slice(0, 200); }
+  }
+  report.checks.max_classes_per_el = {
+    pass: max <= BUDGET.classesPerElement,
+    actual: max,
+    budget: BUDGET.classesPerElement,
+    elementHint: worstSnippet || null,
+  };
+}
+
+// ── DOM depth (rough — counts < ... > opening tags, decrements on </) ─────────
+{
+  const tokens = bodyOnly.match(/<\/?[a-zA-Z][^<>]*>/g) || [];
+  let depth = 0, max = 0;
+  for (const t of tokens) {
+    if (/^<\//.test(t)) {
+      depth = Math.max(0, depth - 1);
+    } else if (!/\/>$/.test(t) && !/^<(area|base|br|col|embed|hr|img|input|link|meta|param|source|track|wbr)\b/i.test(t)) {
+      depth += 1;
+      if (depth > max) max = depth;
+    }
+  }
+  report.checks.max_dom_depth = { pass: max <= BUDGET.domDepth, actual: max, budget: BUDGET.domDepth };
+}
+
+// ── Empty wrappers ────────────────────────────────────────────────────────────
+//
+// True empty wrapper: <div> with NO class/style/attrs containing a single element.
+// Allow:
+//   - wrapper has a class with at least one non-trivial utility (it has a layout role)
+//   - wrapper has any other attribute (data-*, role, aria-*)
+//   - inner element is an <img> / <picture> / <video> / <iframe> (media often needs a wrapper)
+//   - Liquid blocks inside (a wrapper containing {% for %} or {% if %} has a logical role)
+{
+  const re = /<div\b([^>]*)>([\s\S]*?)<\/div>/g;
+  let m, count = 0, samples = [];
+  while ((m = re.exec(bodyOnly))) {
+    const attrs = m[1].trim();
+    const inner = m[2];
+
+    // Skip if wrapper has any class with a non-empty value, OR has any non-class attr
+    const hasClass = /\bclass\s*=\s*"[^"]*\S[^"]*"/.test(attrs);
+    const hasOtherAttr = /\b(?:id|role|aria-|data-|style|hidden|tabindex)/.test(attrs);
+    if (hasClass || hasOtherAttr) continue;
+
+    // Skip if inner contains liquid logic blocks
+    if (/\{%-?\s*(?:for|if|case|unless|liquid|render)\b/.test(inner)) continue;
+
+    // Check inner for single-element child
+    const trimmed = inner.trim();
+    const childOpenTags = trimmed.match(/<[a-zA-Z]/g) || [];
+    if (childOpenTags.length !== 1) continue;
+
+    // Inner element is media → allow (legitimate wrapping)
+    if (/^<(img|picture|video|iframe|svg)\b/.test(trimmed)) continue;
+
+    count++;
+    if (samples.length < 3) samples.push(m[0].slice(0, 120));
+  }
+  report.checks.empty_wrappers = { pass: count === 0, count, samples };
+}
+
+// ── if nesting depth ──────────────────────────────────────────────────────────
+{
+  const ifOpens = [...bodyOnly.matchAll(/\{%-?\s*if\b/g)].map((m) => m.index);
+  const ifEnds  = [...bodyOnly.matchAll(/\{%-?\s*endif\b/g)].map((m) => m.index);
+  // Compute max nesting by walking the events in order
+  const events = [
+    ...ifOpens.map((i) => ({ i, t: 'open' })),
+    ...ifEnds.map((i) => ({ i, t: 'close' })),
+  ].sort((a, b) => a.i - b.i);
+  let depth = 0, max = 0;
+  for (const e of events) {
+    if (e.t === 'open') { depth++; if (depth > max) max = depth; } else { depth--; }
+  }
+  report.checks.if_nesting_depth = { pass: max <= BUDGET.ifDepth, actual: max, budget: BUDGET.ifDepth };
+}
+
+// ── single liquid block: count top-level {% assign %} outside any {% liquid %} block ──
+{
+  // Remove {% liquid %}…{% endliquid %} blocks (so assigns inside are not counted)
+  const withoutLiquidBlocks = bodyOnly.replace(/\{%-?\s*liquid\s*[\s\S]*?-?%\}/g, '');
+  const looseAssigns = (withoutLiquidBlocks.match(/\{%-?\s*assign\b/g) || []).length;
+  report.checks.single_liquid_block = {
+    pass: looseAssigns === 0,
+    loose_assigns_outside_liquid_block: looseAssigns,
+  };
+}
+
+// ── inline event handlers ─────────────────────────────────────────────────────
+{
+  const re = /\bon[a-z]+\s*=\s*"/g;
+  const count = (bodyOnly.match(re) || []).length;
+  report.checks.inline_event_handlers = { pass: count === 0, count };
+}
+
+// ── hardcoded hex colors (in inline style= or {% style %} block) ──────────────
+{
+  // In inline style attrs
+  const styleAttrs = [...bodyOnly.matchAll(/\bstyle\s*=\s*"([^"]+)"/g)].map((m) => m[1]).join(' ');
+  // In {% style %} blocks
+  const styleBlocks = [...bodyOnly.matchAll(/\{%-?\s*style\s*-?%\}([\s\S]*?)\{%-?\s*endstyle\s*-?%\}/g)].map((m) => m[1]).join(' ');
+  const haystack = styleAttrs + ' ' + styleBlocks;
+  const hexes = haystack.match(/#[0-9a-fA-F]{6}\b/g) || [];
+  report.checks.hardcoded_hex = { pass: hexes.length === 0, count: hexes.length, samples: hexes.slice(0, 5) };
+}
+
+// ── hardcoded inline px ───────────────────────────────────────────────────────
+{
+  const styleAttrs = [...bodyOnly.matchAll(/\bstyle\s*=\s*"([^"]+)"/g)].map((m) => m[1]).join(' ');
+  // Look for font-size: NNpx, padding: NNpx, margin: NNpx outside {{...}} contexts
+  const px = styleAttrs.match(/(?:font-size|padding|margin)[^;]*?\b\d+px/gi) || [];
+  report.checks.hardcoded_inline_px = { pass: px.length === 0, count: px.length, samples: px.slice(0, 5) };
+}
+
+// ── schema fields wired ───────────────────────────────────────────────────────
+{
+  // Pull section.settings ids
+  const sectionIds = [...schemaBlock.matchAll(/"id"\s*:\s*"([^"]+)"/g)].map((m) => m[1]);
+  const unique = [...new Set(sectionIds)];
+
+  // Detect alias variables: `assign foo = section.settings` or `assign foo = block.settings`.
+  // Captures the alias name (e.g. "foo") so we can match `foo.<id>` as wiring too.
+  const aliasNames = new Set();
+  const aliasRe = /\bassign\s+(\w+)\s*=\s*(?:section|block)\.settings\b/g;
+  for (const m of bodyOnly.matchAll(aliasRe)) aliasNames.add(m[1]);
+  // Also handle the `{% capture %}`-style and `{% liquid \n assign x = section.settings %}` blocks
+  const liquidBlocks = [...bodyOnly.matchAll(/\{%-?\s*liquid([\s\S]*?)-?%\}/g)].map((m) => m[1]).join('\n');
+  for (const m of liquidBlocks.matchAll(aliasRe)) aliasNames.add(m[1]);
+
+  const wireableRegexes = (id) => {
+    const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const patterns = [
+      `\\bsection\\.settings\\.${escaped}\\b`,
+      `\\bblock\\.settings\\.${escaped}\\b`,
+      `\\bsettings\\.${escaped}\\b`,
+    ];
+    for (const alias of aliasNames) {
+      patterns.push(`\\b${alias}\\.${escaped}\\b`);
+    }
+    return new RegExp(patterns.join('|'));
+  };
+
+  const haystack = bodyOnly + '\n' + liquidBlocks;
+  const unused = unique.filter((id) => !wireableRegexes(id).test(haystack));
+
+  report.checks.schema_fields_wired = {
+    pass: unused.length === 0,
+    wired: unique.length - unused.length,
+    total: unique.length,
+    aliases_detected: [...aliasNames],
+    unused,
+  };
+}
+
+// ── render not include ────────────────────────────────────────────────────────
+{
+  const count = (bodyOnly.match(/\{%-?\s*include\b/g) || []).length;
+  report.checks.render_not_include = { pass: count === 0, count_include: count };
+}
+
+// ── Liquid filter validity ────────────────────────────────────────────────────
+//
+// Source of truth: zcommerce-docs/reference/filters.md. ZCommerce supports a
+// specific set of filters; Shopify-only filters (money, money_with_currency,
+// img_url, weight_with_unit, etc.) DO NOT WORK and silently produce wrong output
+// or crash the engine. Agents have a habit of using Shopify filters from training
+// data — this catches it.
+{
+  const VALID_FILTERS = new Set([
+    // ZCommerce-specific
+    'asset_url', 'image_url', 'color_component', 't', 'translate', 'json', 'default',
+    // String
+    'append', 'capitalize', 'downcase', 'upcase',
+    'strip', 'lstrip', 'rstrip', 'strip_html', 'strip_newlines',
+    'escape', 'url_encode', 'url_decode',
+    'truncate', 'truncatewords',
+    'replace', 'replace_first',
+    'remove', 'remove_first',
+    'prepend', 'newline_to_br', 'split', 'slice',
+    // Math
+    'plus', 'minus', 'times', 'divided_by', 'modulo',
+    'round', 'ceil', 'floor', 'abs', 'at_most', 'at_least',
+    // Array
+    'map', 'where', 'sort', 'sort_natural',
+    'join', 'first', 'last', 'size', 'reverse', 'uniq', 'compact', 'concat',
+    // Date
+    'date',
+  ]);
+  // Find filter applications: `{{ x | filter_name }}` or `{{ x | filter_name: arg }}`
+  // Also catch chained: `{{ x | a | b | c }}`
+  const filterRe = /\|\s*([a-z_][a-z0-9_]*)/gi;
+  const seen = new Map();
+  for (const m of src.matchAll(filterRe)) {
+    const name = m[1];
+    seen.set(name, (seen.get(name) ?? 0) + 1);
+  }
+  const invalid = [];
+  for (const [name, count] of seen) {
+    if (!VALID_FILTERS.has(name)) invalid.push({ filter: name, count });
+  }
+  report.checks.liquid_filters_valid = {
+    pass: invalid.length === 0,
+    invalid_filters: invalid.slice(0, 10),
+    invalid_count: invalid.length,
+    hint: invalid.length > 0
+      ? `Invalid Liquid filter(s): ${invalid.map(i => i.filter).join(', ')}. Check zcommerce-docs/reference/filters.md for the supported list. Shopify-only filters (money, money_with_currency, img_url, weight_with_unit, etc.) do not work in ZCommerce.`
+      : null,
+  };
+}
+
+// ── Liquid tag validity ───────────────────────────────────────────────────────
+//
+// ZCommerce's template engine (LiquidJS) only knows: LiquidJS built-in tags
+// + the custom tags registered by the Commerce CLI (schema, style, sections).
+// (schema, style, sections).
+//
+// A common failure mode: the agent emits Shopify-only tags like `paginate`,
+// `form`, `javascript`, `stylesheet` — these throw "tag X not found" at render
+// time. The crash that shipped in real-world use was `{% paginate %}` in
+// product-carousel-section.liquid.
+{
+  // Source of truth: zcommerce-docs/reference/tags.md.
+  // Anything NOT in this list will crash the local dev server. The Shopify-only
+  // tags (paginate, form, javascript, stylesheet, etc.) are notably absent.
+  const ZCOMMERCE_DOCUMENTED = new Set([
+    // control flow
+    'if', 'elsif', 'else', 'endif',
+    'unless', 'endunless',
+    'case', 'when', 'endcase',
+    // iteration
+    'for', 'endfor', 'break', 'continue',
+    // variables
+    'liquid',
+    'assign',
+    'capture', 'endcapture',
+    'increment', 'decrement',
+    // composition
+    'render',
+    'sections',
+    'schema', 'endschema',
+    // utility
+    'comment', 'endcomment',
+    'raw', 'endraw',
+    // ZCommerce custom (registered in CLI)
+    'style', 'endstyle',
+  ]);
+  const VALID_TAGS = ZCOMMERCE_DOCUMENTED;
+
+  // Match `{% tagname` or `{%- tagname` — capture the first word after the opener
+  const tagRe = /\{%-?\s*(\w+)/g;
+  const seen = new Map();
+  for (const m of src.matchAll(tagRe)) {
+    const tag = m[1];
+    seen.set(tag, (seen.get(tag) ?? 0) + 1);
+  }
+  const invalid = [];
+  for (const [tag, count] of seen) {
+    if (!VALID_TAGS.has(tag)) invalid.push({ tag, count });
+  }
+  report.checks.liquid_tags_valid = {
+    pass: invalid.length === 0,
+    invalid_tags: invalid.slice(0, 10),
+    invalid_count: invalid.length,
+    hint: invalid.length > 0
+      ? `Invalid Liquid tag(s): ${invalid.map(i => i.tag).join(', ')}. ZCommerce only supports LiquidJS built-ins + custom: schema, style, sections. Shopify-only tags (paginate, form, javascript, stylesheet) DO NOT WORK and crash at render time.`
+      : null,
+  };
+}
+
+// ── i18n keys resolve ─────────────────────────────────────────────────────────
+//
+// Every `'a.b.c' | t` (or | translate) key referenced in the section must exist
+// in en.json (content) or en.schema.json (schema labels). This is the bug that
+// crashed category/product/blog pages in real-world use — schema declared keys
+// like `sections.foo.settings.bar.label` were referenced in markup but never
+// added to en.json.
+//
+// Resolution rules:
+//   - Keys starting with "sections.*.settings.*.label" / ".default" usually live in en.schema.json
+//   - Other keys (e.g. "category.sort_by") usually live in en.json
+//   - We check BOTH files and accept the key if it resolves in either
+//   - `{{ section.settings.X | t }}` and `{{ block.settings.X | t }}` are runtime
+//     translations of a value, not literal key references — those are skipped
+{
+  if (!i18nPath || !fs.existsSync(i18nPath)) {
+    report.checks.i18n_keys_resolve = {
+      pass: true,
+      skipped: true,
+      reason: 'No i18n/en.json found — pass --i18n explicitly to enforce',
+    };
+  } else {
+    const enJson = JSON.parse(fs.readFileSync(i18nPath, 'utf-8'));
+    const enSchema = (i18nSchemaPath && fs.existsSync(i18nSchemaPath))
+      ? JSON.parse(fs.readFileSync(i18nSchemaPath, 'utf-8'))
+      : {};
+
+    const resolve = (obj, parts) => {
+      let cur = obj;
+      for (const p of parts) {
+        if (cur == null || typeof cur !== 'object') return undefined;
+        cur = cur[p];
+      }
+      return cur;
+    };
+
+    // RUNTIME translation keys: `'a.b.c' | t` / `"a.b.c" | t` / `| translate`
+    // These are resolved at render time and MUST exist in en.json (NOT en.schema.json,
+    // which is for the admin theme editor only). This is exactly the bug that crashed
+    // toy_story_test's category page: keys were written to en.schema.json but the
+    // section used `| t` at runtime → undefined → property-access crash.
+    const litRe = /['"]([a-zA-Z][a-zA-Z0-9_.]*)['"]\s*\|\s*(?:t|translate)\b/g;
+    const literals = [...bodyOnly.matchAll(litRe)].map((m) => m[1]);
+
+    // SCHEMA-LABEL keys: `"label": "t:sections.foo.label"` inside the {% schema %} block.
+    // These are resolved by the theme editor and MUST exist in en.schema.json.
+    const schemaLabelRe = /"t:([a-zA-Z][a-zA-Z0-9_.]*)"/g;
+    const schemaLabels = [...schemaBlock.matchAll(schemaLabelRe)].map((m) => m[1]);
+
+    // Check runtime keys against en.json (strict)
+    const runtimeMisplaced = [];   // present in schema, missing from en.json — the bug
+    const runtimeMissing = [];     // missing from BOTH
+    for (const key of [...new Set(literals)]) {
+      const parts = key.split('.');
+      const inEn = resolve(enJson, parts) !== undefined;
+      if (inEn) continue;
+      const inSchema = resolve(enSchema, parts) !== undefined;
+      if (inSchema) runtimeMisplaced.push(key);
+      else runtimeMissing.push(key);
+    }
+
+    // Check schema-label keys against en.schema.json (strict)
+    const schemaLabelMissing = [];
+    for (const key of [...new Set(schemaLabels)]) {
+      const parts = key.split('.');
+      const inSchema = resolve(enSchema, parts) !== undefined;
+      if (!inSchema) schemaLabelMissing.push(key);
+    }
+
+    const runtimeTotalFail = runtimeMisplaced.length + runtimeMissing.length;
+    report.checks.i18n_keys_resolve = {
+      pass: runtimeTotalFail === 0 && schemaLabelMissing.length === 0,
+      runtime_keys_referenced: literals.length,
+      runtime_unique: new Set(literals).size,
+      runtime_misplaced_in_schema: runtimeMisplaced.slice(0, 10),
+      runtime_misplaced_count: runtimeMisplaced.length,
+      runtime_missing_entirely: runtimeMissing.slice(0, 10),
+      runtime_missing_count: runtimeMissing.length,
+      schema_label_missing: schemaLabelMissing.slice(0, 10),
+      schema_label_missing_count: schemaLabelMissing.length,
+      i18n_file: i18nPath,
+      i18n_schema_file: i18nSchemaPath || null,
+      hint: runtimeMisplaced.length > 0
+        ? "Runtime `| t` keys exist in en.schema.json but not en.json. Move them — `| t` only resolves against en.json at render time. en.schema.json is for the admin theme editor only."
+        : null,
+    };
+  }
+}
+
+// ── snippet scope sanity ──────────────────────────────────────────────────────
+//
+// `settings.X` (without `section.` or `block.` prefix) is almost always a snippet
+// scope bug. `settings` isn't a global. Real causes:
+//   (1) Author confused snippet variable scope with section scope.
+//   (2) Snippet expected a `settings` parameter via render: `{% render 'foo', settings: section.settings %}`
+//       and used `settings.X` correctly — this case is fine if the parameter is documented.
+//
+// We can't tell (1) from (2) statically, so this check is a WARNING by default,
+// promoted to a FAIL if the file path indicates a section (sections/*.liquid).
+// Snippets get a warning only.
+{
+  const isSection = /\/sections\/[^/]+\.liquid$/.test(file);
+  // Match bare `settings.X` not preceded by `section.` or `block.`
+  // Use a negative lookbehind via a manual exclusion scan.
+  const allMatches = [...bodyOnly.matchAll(/\bsettings\.([a-zA-Z_]\w*)/g)];
+  const bareSettings = [];
+  for (const m of allMatches) {
+    const before = bodyOnly.slice(Math.max(0, m.index - 8), m.index);
+    if (!/section\.$/.test(before) && !/block\.$/.test(before)) {
+      bareSettings.push({ key: m[1], context: bodyOnly.slice(m.index - 20, m.index + 30).replace(/\s+/g, ' ') });
+    }
+  }
+  report.checks.snippet_scope_sanity = {
+    pass: isSection ? bareSettings.length === 0 : true,
+    is_section: isSection,
+    bare_settings_refs: bareSettings.slice(0, 5),
+    bare_settings_count: bareSettings.length,
+    note: bareSettings.length && !isSection
+      ? 'Warning only — `settings.X` is acceptable in snippets if `settings` is passed via render parameter.'
+      : null,
+  };
+}
+
+// ── escape user output (warning only) ─────────────────────────────────────────
+{
+  // Look for {{ section.settings.X }} or {{ block.settings.X }} inside attribute context without | escape
+  const attrCtx = [...bodyOnly.matchAll(/\b\w+\s*=\s*"[^"]*\{\{([^}]+)\}\}[^"]*"/g)].map((m) => m[1].trim());
+  const warnings = attrCtx.filter((s) => !s.includes('| escape') && !s.includes('|escape') && /settings\./.test(s));
+  report.checks.escape_user_output = { pass: true, warnings: warnings.slice(0, 5), count: warnings.length };
+}
+
+// ── Final verdict ─────────────────────────────────────────────────────────────
+const failed = Object.entries(report.checks).filter(([, v]) => v.pass === false);
+report.verdict = failed.length === 0 ? 'PASS' : 'FAIL';
+report.failed_checks = failed.map(([k]) => k);
+
+console.log(JSON.stringify(report, null, 2));
+process.exit(failed.length === 0 ? 0 : 1);

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/scripts/perf.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * perf.mjs — run Lighthouse against a URL via headless Chrome.
+ *
+ * Usage:
+ *   node perf.mjs \
+ *     --url           http://localhost:3000/home \
+ *     --form-factor   mobile | desktop          (default: mobile)
+ *     --out           /path/to/lighthouse.json
+ *
+ * Output JSON shape:
+ *   {
+ *     "url": "...",
+ *     "form_factor": "mobile",
+ *     "scores": {
+ *       "performance": 92, "accessibility": 95, "best-practices": 100, "seo": 98
+ *     },
+ *     "metrics": {
+ *       "lcp_ms": 1850, "fcp_ms": 1100, "cls": 0.02, "tbt_ms": 110, "speed_index_ms": 2400
+ *     },
+ *     "opportunities": [...],   // top 5 by potential savings
+ *     "diagnostics":  [...],    // top 5 actionable
+ *     "verdict": "PASS" | "FAIL"
+ *   }
+ *
+ * Pass thresholds (mobile, throttled):
+ *   performance >= 90
+ *   lcp_ms < 2500
+ *   cls    < 0.1
+ *   tbt_ms < 200
+ *
+ * Dependencies: puppeteer, lighthouse
+ *   npm install --no-save puppeteer lighthouse
+ *   (reuse this theme's node_modules if lighthouse is already installed.)
+ */
+
+import puppeteer from 'puppeteer';
+import lighthouse from 'lighthouse';
+import fs from 'node:fs';
+import path from 'node:path';
+import { URL } from 'node:url';
+
+const args = parseArgs(process.argv.slice(2));
+const url = required(args, 'url');
+const formFactor = (args['form-factor'] || 'mobile').toLowerCase();
+const outPath = required(args, 'out');
+
+const PASS = { performance: 90, lcp_ms: 2500, cls: 0.1, tbt_ms: 200 };
+
+(async () => {
+  const browser = await puppeteer.launch({
+    headless: 'new',
+    args: ['--no-sandbox', '--disable-setuid-sandbox', '--remote-debugging-port=0'],
+  });
+  try {
+    const wsEndpoint = browser.wsEndpoint();
+    const port = new URL(wsEndpoint).port;
+
+    const config = {
+      extends: 'lighthouse:default',
+      settings: {
+        onlyCategories: ['performance'],
+        formFactor,
+        screenEmulation: formFactor === 'mobile'
+          ? { mobile: true, width: 412, height: 823, deviceScaleFactor: 1.75, disabled: false }
+          : { mobile: false, width: 1350, height: 940, deviceScaleFactor: 1, disabled: false },
+        throttlingMethod: 'simulate',
+      },
+    };
+
+    const runnerResult = await lighthouse(
+      url,
+      { port: +port, output: 'json', logLevel: 'error' },
+      config
+    );
+
+    const lhr = runnerResult.lhr;
+    const audits = lhr.audits;
+
+    const scores = {
+      performance: Math.round((lhr.categories.performance?.score ?? 0) * 100),
+    };
+    const metrics = {
+      lcp_ms:         Math.round(audits['largest-contentful-paint']?.numericValue ?? 0),
+      fcp_ms:         Math.round(audits['first-contentful-paint']?.numericValue ?? 0),
+      cls:            +(audits['cumulative-layout-shift']?.numericValue ?? 0).toFixed(3),
+      tbt_ms:         Math.round(audits['total-blocking-time']?.numericValue ?? 0),
+      speed_index_ms: Math.round(audits['speed-index']?.numericValue ?? 0),
+    };
+
+    // Top opportunities by potential ms savings
+    const opportunities = Object.values(audits)
+      .filter((a) => a.details?.type === 'opportunity' && a.numericValue > 50)
+      .sort((a, b) => (b.numericValue ?? 0) - (a.numericValue ?? 0))
+      .slice(0, 5)
+      .map((a) => ({ id: a.id, title: a.title, potential_savings_ms: Math.round(a.numericValue) }));
+
+    // Diagnostics
+    const diagnostics = Object.values(audits)
+      .filter((a) => a.details?.type === 'table' && a.score !== null && a.score < 0.9)
+      .slice(0, 5)
+      .map((a) => ({ id: a.id, title: a.title, score: a.score }));
+
+    const verdict = (
+      scores.performance >= PASS.performance &&
+      metrics.lcp_ms < PASS.lcp_ms &&
+      metrics.cls < PASS.cls &&
+      metrics.tbt_ms < PASS.tbt_ms
+    ) ? 'PASS' : 'FAIL';
+
+    const report = {
+      url, form_factor: formFactor, scores, metrics, opportunities, diagnostics, verdict,
+    };
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, JSON.stringify(report, null, 2));
+    console.log(JSON.stringify(report, null, 2));
+  } finally {
+    await browser.close();
+  }
+})().catch((e) => fail(e.message ?? String(e)));
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) {
+      const key = argv[i].slice(2);
+      const val = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : 'true';
+      out[key] = val;
+    }
+  }
+  return out;
+}
+function required(args, k) { if (!args[k]) fail(`Missing --${k}`); return args[k]; }
+function fail(msg) { console.error('perf error:', msg); process.exit(2); }