similarbuild 0.1.0

package/templates/skills/sb-build-shopify/scripts/build-shopify.mjs

@@ -0,0 +1,637 @@
+#!/usr/bin/env node
+// build-shopify.mjs — Plumbing for sb-build-shopify.
+//
+// The LLM composes the .liquid file (Liquid + {% schema %} JSON + scoped CSS);
+// this script handles the deterministic plumbing around that composition:
+// structural validation of the produced Liquid (schema JSON parsing, Liquid
+// tag balance, anti-pattern checks) and formatting + persistence to the output
+// path.
+//
+// Two subcommands:
+//   validate --liquid-file <path>            Check structural rules, JSON to stdout.
+//                                            Exit 0 if all errors clean, 3 if errors.
+//   write --output-path <path>               Read .liquid from stdin, optional
+//                                            prettier format, write to disk,
+//                                            JSON metadata to stdout.
+//
+// Validation rules check the *mechanical* subset of the rules in
+// references/shopify-build-rules.md — schema JSON well-formedness, Liquid tag
+// balance, the canonical anti-patterns we can detect with regex, schema field
+// requirements (presets, no `default` on image_picker, unique setting ids).
+// Semantic correctness (right pattern, defensive specificity actually applied,
+// alt text being meaningful, settings being well-named) is the LLM's job.
+//
+// prettier and liquidjs are imported lazily and are OPTIONAL. If they're not
+// installed, validate and write still succeed — formatting and full Liquid
+// parsing are skipped with a recorded reason.
+//
+// Exit codes: 0=ok, 1=script error, 2=invalid args, 3=validation failed.
+
+import { parseArgs } from 'node:util'
+import { mkdir, writeFile, readFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+
+const HELP = `
+build-shopify.mjs — Validate and persist .liquid produced by sb-build-shopify.
+
+Subcommands:
+  validate --liquid-file <path>    Run structural lint on the .liquid file.
+  write --output-path <path>       Read .liquid from stdin, format if prettier
+                                   is available, write to <output-path>.
+
+Common flags:
+  --help                           Show this message.
+  --verbose                        Extra diagnostics to stderr.
+
+Exit codes: 0=ok, 1=script error, 2=invalid args, 3=validation failed.
+`
+
+function fail(msg, code = 2) {
+  process.stderr.write(`[sb-build-shopify] ${msg}\n`)
+  process.exit(code)
+}
+
+function log(verbose, msg) {
+  if (verbose) process.stderr.write(`[sb-build-shopify] ${msg}\n`)
+}
+
+async function readStdin() {
+  const chunks = []
+  for await (const chunk of process.stdin) chunks.push(chunk)
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+// --- Helpers ------------------------------------------------------------------
+
+function findAll(re, str) {
+  const out = []
+  const flags = re.flags.includes('g') ? re.flags : `${re.flags}g`
+  const r = new RegExp(re.source, flags)
+  for (let m = r.exec(str); m !== null; m = r.exec(str)) {
+    out.push(m)
+  }
+  return out
+}
+
+// Strip {% schema %}...{% endschema %} so its JSON content (which has its own
+// {% / %} characters in string literals occasionally, and braces) doesn't
+// confuse downstream regex passes.
+function stripSchemaBlock(liquid) {
+  return liquid.replace(/\{%\s*schema\s*%\}[\s\S]*?\{%\s*endschema\s*%\}/g, '<!-- schema -->')
+}
+
+// --- Liquid tag balance -------------------------------------------------------
+
+const PAIRED_TAGS = [
+  'if', 'unless', 'for', 'case', 'capture', 'comment', 'form', 'paginate',
+  'tablerow', 'style', 'javascript', 'stylesheet', 'schema', 'raw',
+]
+
+function checkLiquidBalance(liquid) {
+  const errors = []
+  const stack = []
+  // Match every {% tag ... %}. Within each, capture the leading word.
+  const tagRe = /\{%-?\s*(\w+)[\s\S]*?-?%\}/g
+  for (let m = tagRe.exec(liquid); m !== null; m = tagRe.exec(liquid)) {
+    const tag = m[1]
+    if (PAIRED_TAGS.includes(tag)) {
+      stack.push({ tag, index: m.index })
+    } else if (tag.startsWith('end')) {
+      const expected = tag.slice(3)
+      if (PAIRED_TAGS.includes(expected)) {
+        if (stack.length === 0) {
+          errors.push({
+            rule: 'liquid-unmatched-end',
+            message: `{% ${tag} %} found with no matching opening tag.`,
+          })
+        } else {
+          const top = stack.pop()
+          if (top.tag !== expected) {
+            errors.push({
+              rule: 'liquid-mismatched-end',
+              message: `{% ${tag} %} does not match {% ${top.tag} %} (opened at index ${top.index}).`,
+            })
+          }
+        }
+      }
+    }
+  }
+  for (const open of stack) {
+    errors.push({
+      rule: 'liquid-unclosed-tag',
+      message: `{% ${open.tag} %} opened at index ${open.index} was never closed.`,
+    })
+  }
+  return errors
+}
+
+// --- Schema extraction & validation ------------------------------------------
+
+function extractSchema(liquid) {
+  const m = /\{%\s*schema\s*%\}([\s\S]*?)\{%\s*endschema\s*%\}/.exec(liquid)
+  return m ? m[1].trim() : null
+}
+
+function validateSchema(liquid) {
+  const errors = []
+  const warnings = []
+  const raw = extractSchema(liquid)
+  if (raw === null) {
+    errors.push({
+      rule: 'schema-missing',
+      message: 'No {% schema %}...{% endschema %} block found. Shopify will refuse to register the section.',
+    })
+    return { errors, warnings, schema: null }
+  }
+  let schema
+  try {
+    schema = JSON.parse(raw)
+  } catch (err) {
+    errors.push({
+      rule: 'schema-invalid-json',
+      message: `Schema is not valid JSON: ${err.message}`,
+    })
+    return { errors, warnings, schema: null }
+  }
+  if (typeof schema !== 'object' || schema === null || Array.isArray(schema)) {
+    errors.push({
+      rule: 'schema-not-object',
+      message: 'Schema root must be a JSON object.',
+    })
+    return { errors, warnings, schema: null }
+  }
+  if (typeof schema.name !== 'string' || schema.name.length === 0) {
+    errors.push({
+      rule: 'schema-missing-name',
+      message: 'Schema must have a non-empty "name" field.',
+    })
+  }
+  if (!Array.isArray(schema.presets) || schema.presets.length === 0) {
+    errors.push({
+      rule: 'schema-missing-presets',
+      message: 'Schema must have at least one preset (anti-pattern #12). Without presets, the section is uninstallable from the editor.',
+    })
+  } else {
+    schema.presets.forEach((p, i) => {
+      if (typeof p !== 'object' || p === null || typeof p.name !== 'string') {
+        errors.push({
+          rule: 'schema-preset-invalid',
+          message: `presets[${i}] must be an object with a "name" string.`,
+        })
+      }
+    })
+  }
+  const settings = Array.isArray(schema.settings) ? schema.settings : []
+  const seenIds = new Map()
+  settings.forEach((s, i) => {
+    if (typeof s !== 'object' || s === null) {
+      errors.push({
+        rule: 'schema-setting-invalid',
+        message: `settings[${i}] must be an object.`,
+      })
+      return
+    }
+    if (typeof s.type !== 'string') {
+      errors.push({
+        rule: 'schema-setting-missing-type',
+        message: `settings[${i}] missing "type" string.`,
+      })
+      return
+    }
+    if (s.type === 'header' || s.type === 'paragraph') return // these don't need an id
+    if (typeof s.id !== 'string' || s.id.length === 0) {
+      errors.push({
+        rule: 'schema-setting-missing-id',
+        message: `settings[${i}] (type=${s.type}) is missing "id".`,
+      })
+      return
+    }
+    if (seenIds.has(s.id)) {
+      errors.push({
+        rule: 'schema-setting-duplicate-id',
+        message: `settings[${i}] has duplicate id "${s.id}" (also at index ${seenIds.get(s.id)}).`,
+      })
+    } else {
+      seenIds.set(s.id, i)
+    }
+    if (s.type === 'image_picker' && Object.hasOwn(s, 'default')) {
+      errors.push({
+        rule: 'schema-image-picker-default',
+        message: `Anti-pattern #11: settings[${i}] (id="${s.id}") is image_picker with a "default". image_picker does not accept default — use a Liquid {% if %}{% else %}{% endif %} fallback.`,
+      })
+    }
+  })
+  // Block iterated → block setting type sanity.
+  if (Array.isArray(schema.blocks)) {
+    schema.blocks.forEach((b, i) => {
+      if (typeof b !== 'object' || b === null) {
+        errors.push({
+          rule: 'schema-block-invalid',
+          message: `blocks[${i}] must be an object.`,
+        })
+        return
+      }
+      if (typeof b.type !== 'string' || b.type.length === 0) {
+        errors.push({
+          rule: 'schema-block-missing-type',
+          message: `blocks[${i}] missing "type".`,
+        })
+      }
+      if (typeof b.name !== 'string' || b.name.length === 0) {
+        warnings.push({
+          rule: 'schema-block-missing-name',
+          message: `blocks[${i}] is missing "name" — editor sidebar will show the type instead.`,
+        })
+      }
+    })
+  }
+  return { errors, warnings, schema }
+}
+
+// --- HTML/Liquid surface validation (anti-patterns + a11y/perf) ---------------
+
+function validateSurface(liquid) {
+  const errors = []
+  const warnings = []
+  const info = []
+
+  // Strip schema before regexing — JSON inside has braces/percents that confuse other passes.
+  const body = stripSchemaBlock(liquid)
+
+  // 1. Every <img> must have alt attribute (decorative use alt="").
+  const imgs = findAll(/<img\b[^>]*\/?>/gi, body)
+  imgs.forEach((m, i) => {
+    if (!/\balt\s*=/i.test(m[0])) {
+      errors.push({
+        rule: 'img-missing-alt',
+        message: `<img> #${i + 1} is missing alt attribute. Decorative images use alt="".`,
+        snippet: m[0].slice(0, 120),
+      })
+    }
+  })
+
+  // 2. Every <button> must have type=.
+  const buttons = findAll(/<button\b[^>]*>/gi, body)
+  buttons.forEach((m, i) => {
+    if (!/\btype\s*=/i.test(m[0])) {
+      errors.push({
+        rule: 'button-missing-type',
+        message: `<button> #${i + 1} is missing type attribute. Use type="button" unless intentionally a submit.`,
+        snippet: m[0].slice(0, 120),
+      })
+    }
+  })
+
+  // 3. Anti-pattern #8 — fabricated raster-as-SVG via inline data URI in <img src>.
+  imgs.forEach((m) => {
+    const srcMatch = /\bsrc\s*=\s*["']([^"']+)["']/i.exec(m[0])
+    if (srcMatch && /^data:image\/svg\+xml/i.test(srcMatch[1])) {
+      errors.push({
+        rule: 'fabricated-svg-data-uri',
+        message: 'Anti-pattern #8: <img src="data:image/svg+xml,..."> indicates a fabricated SVG. Use the real asset from assetsMap.',
+        snippet: `${srcMatch[1].slice(0, 80)}...`,
+      })
+    }
+  })
+
+  // 4. Anti-pattern #1 — 100vh on a height-related property in CSS (inside {% style %} or <style>).
+  const styleBlocks = [
+    ...findAll(/\{%\s*style\s*%\}([\s\S]*?)\{%\s*endstyle\s*%\}/gi, body),
+    ...findAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi, body),
+  ]
+  const css = styleBlocks.map((m) => m[1]).join('\n')
+  const vhUses = findAll(/(min-height|height)\s*:\s*100vh\b/gi, css)
+  if (vhUses.length > 0) {
+    errors.push({
+      rule: 'hero-100vh',
+      message: `Anti-pattern #1: 100vh used on ${vhUses.length} height declaration(s). Use aspect-ratio + max-height instead.`,
+    })
+  }
+
+  // 5. Anti-pattern #14 — Google Fonts <link rel="stylesheet"> inside the section. Shopify owns <head>.
+  const fontsStylesheet = findAll(/<link\b[^>]*>/gi, body).filter((m) =>
+    /\bhref\s*=\s*["'][^"']*fonts\.googleapis\.com\/css/i.test(m[0]) &&
+    /\brel\s*=\s*["']stylesheet["']/i.test(m[0])
+  )
+  if (fontsStylesheet.length > 0) {
+    errors.push({
+      rule: 'fonts-link-in-section',
+      message: `Anti-pattern #14: Google Fonts <link rel="stylesheet"> found inside the section. Shopify owns <head>; use the {{ font_picker | font_face }} filter instead.`,
+    })
+  }
+
+  // 6. Anti-pattern #14 (companion) — preconnect to font hosts inside the section.
+  const fontPreconnect = findAll(/<link\b[^>]*>/gi, body).filter((m) =>
+    /\brel\s*=\s*["']preconnect["']/i.test(m[0]) &&
+    /\bhref\s*=\s*["'][^"']*fonts\.(googleapis|gstatic)\.com/i.test(m[0])
+  )
+  if (fontPreconnect.length > 0) {
+    warnings.push({
+      rule: 'fonts-preconnect-in-section',
+      message: `${fontPreconnect.length} <link rel="preconnect"> to fonts.* found. Sections should not preconnect — Shopify's theme handles font loading.`,
+    })
+  }
+
+  // 7. block iteration without {{ block.shopify_attributes }} — anti-pattern #13.
+  const blockLoops = findAll(/\{%\s*for\s+block\s+in\s+section\.blocks\s*%\}([\s\S]*?)\{%\s*endfor\s*%\}/gi, body)
+  blockLoops.forEach((m, i) => {
+    if (!/\{\{\s*block\.shopify_attributes\s*\}\}/.test(m[1])) {
+      errors.push({
+        rule: 'block-missing-shopify-attributes',
+        message: `Anti-pattern #13: {% for block in section.blocks %} loop #${i + 1} does not emit {{ block.shopify_attributes }}. The editor cannot link the block UI to the rendered element.`,
+      })
+    }
+  })
+
+  // 8. Hardcoded CDN URLs in markup — anti-pattern #15.
+  const cdnHardcoded = findAll(
+    /\bsrc\s*=\s*["'](https?:\/\/(?:[a-z0-9-]+\.)*(?:shopify\.com|cdn\.shopify|myshopify\.com|cloudinary|imgix|akamaized|cloudfront)[^"']*)["']/gi,
+    body,
+  )
+  if (cdnHardcoded.length > 0) {
+    warnings.push({
+      rule: 'hardcoded-cdn-url',
+      message: `Anti-pattern #15: ${cdnHardcoded.length} hardcoded CDN URL(s) in src. Use {{ image | image_url: width: N }} for setting-driven, localPath for fallback.`,
+    })
+  }
+
+  // 9. Defensive specificity heuristic.
+  if (css.length > 0) {
+    const chainedSelectors = findAll(/\.([a-z][a-z0-9_-]*)\s+\.\1__/gi, css).length
+    info.push({
+      rule: 'defensive-specificity-count',
+      message: `Found ${chainedSelectors} selector(s) using the chained-scope pattern (.scope .scope__X). More is better.`,
+    })
+    if (chainedSelectors === 0 && css.length > 200) {
+      warnings.push({
+        rule: 'no-defensive-specificity',
+        message: 'No selectors found using the chained-scope pattern (.scope .scope__X). Anti-pattern #5b: Dawn / OS 2.0 overrides will win.',
+      })
+    }
+  }
+
+  // 10. Reset rule heuristic.
+  if (css.length > 0 && !/box-sizing\s*:\s*border-box/i.test(css)) {
+    warnings.push({
+      rule: 'no-reset-box-sizing',
+      message: 'No box-sizing: border-box reset found. Add the universal reset to the top of the {% style %} block.',
+    })
+  }
+
+  // 11. {% style %} preferred over <style> for setting-driven CSS.
+  if (
+    /<style\b/i.test(body) &&
+    !/\{%\s*style\s*%\}/i.test(body) &&
+    /\{\{[\s\S]*?\}\}/.test(css)
+  ) {
+    warnings.push({
+      rule: 'style-tag-with-liquid',
+      message: '<style> block contains Liquid expressions but is not wrapped in {% style %}. Use {% style %}{% endstyle %} so Shopify processes the Liquid.',
+    })
+  }
+
+  // 12. If multiple images, most should have loading attribute.
+  if (imgs.length >= 2) {
+    const withoutLoading = imgs.filter((m) => !/\bloading\s*=/i.test(m[0])).length
+    if (withoutLoading >= imgs.length - 1) {
+      warnings.push({
+        rule: 'imgs-missing-loading',
+        message: `${withoutLoading}/${imgs.length} <img> tags lack a loading attribute. Hero/LCP can be eager; the rest should be lazy.`,
+      })
+    }
+  }
+
+  return { errors, warnings, info }
+}
+
+// --- liquidjs (lazy, optional) ------------------------------------------------
+
+// Strip Shopify-only paired tag wrappers ({% style %}, {% javascript %},
+// {% stylesheet %}, {% schema %}, {% form %}, {% paginate %}) so liquidjs
+// (which only knows core Liquid tags) doesn't choke. The wrappers' balance is
+// already verified by checkLiquidBalance — here we only care about parsing the
+// expressions inside.
+//
+// {% schema %} contents are JSON, not Liquid, so we replace the whole block
+// with a comment. The other wrappers may contain Liquid expressions, so we
+// preserve their inner content.
+function stripShopifyOnlyTags(liquid) {
+  let out = stripSchemaBlock(liquid)
+  const innerPreservingPairs = ['style', 'javascript', 'stylesheet', 'form', 'paginate']
+  for (const tag of innerPreservingPairs) {
+    const open = new RegExp(`\\{%-?\\s*${tag}\\b[^%]*%\\}`, 'gi')
+    const close = new RegExp(`\\{%-?\\s*end${tag}\\s*-?%\\}`, 'gi')
+    out = out.replace(open, '').replace(close, '')
+  }
+  return out
+}
+
+async function tryLiquidParse(liquid, verbose) {
+  let liquidjs
+  try {
+    liquidjs = await import('liquidjs')
+  } catch {
+    log(verbose, 'liquidjs not installed — relying on regex tag-balance check only')
+    return { parsed: false, reason: 'liquidjs-not-installed', errors: [] }
+  }
+  try {
+    const Liquid = liquidjs.Liquid
+    const engine = new Liquid({ strictFilters: false, strictVariables: false })
+    const stripped = stripShopifyOnlyTags(liquid)
+    engine.parse(stripped)
+    return { parsed: true, reason: null, errors: [] }
+  } catch (err) {
+    return {
+      parsed: false,
+      reason: `liquidjs-parse-error: ${err.message}`,
+      errors: [{ rule: 'liquid-parse-error', message: err.message }],
+    }
+  }
+}
+
+// --- Top-level validate -------------------------------------------------------
+
+async function validateLiquid(liquid, verbose) {
+  const allErrors = []
+  const allWarnings = []
+  const allInfo = []
+
+  // Tag balance (regex-based, always available).
+  const balanceErrors = checkLiquidBalance(liquid)
+  allErrors.push(...balanceErrors)
+
+  // Optional: full parse via liquidjs.
+  const liquidParse = await tryLiquidParse(liquid, verbose)
+  allErrors.push(...liquidParse.errors)
+
+  // Schema extraction + validation.
+  const schemaResult = validateSchema(liquid)
+  allErrors.push(...schemaResult.errors)
+  allWarnings.push(...schemaResult.warnings)
+
+  // Surface (anti-patterns, a11y, perf).
+  const surface = validateSurface(liquid)
+  allErrors.push(...surface.errors)
+  allWarnings.push(...surface.warnings)
+  allInfo.push(...surface.info)
+
+  return {
+    passed: allErrors.length === 0,
+    errorCount: allErrors.length,
+    warningCount: allWarnings.length,
+    errors: allErrors,
+    warnings: allWarnings,
+    info: allInfo,
+    schemaValidated: schemaResult.schema !== null,
+    liquidParsed: liquidParse.parsed,
+    liquidSkipReason: liquidParse.reason,
+  }
+}
+
+// --- prettier (lazy, optional) ------------------------------------------------
+
+async function tryPrettierFormat(content, verbose) {
+  let prettier
+  try {
+    prettier = await import('prettier')
+  } catch {
+    log(verbose, 'prettier not installed — writing unformatted')
+    return { content, formatted: false, reason: 'prettier-not-installed' }
+  }
+  // Prettier's HTML parser word-wraps long string literals inside `{% schema %}`
+  // (it doesn't know the block is JSON), inserting `\n` *inside* JSON strings
+  // and producing invalid JSON. We extract the schema block, format its JSON
+  // ourselves with JSON.stringify, swap a placeholder comment in for prettier,
+  // then re-inject the formatted JSON afterwards. Outside that block, prettier
+  // formats HTML + Liquid tags-as-text the same as before.
+  const SCHEMA_PLACEHOLDER = '<!--sb-shopify-schema-placeholder-->'
+  const schemaRe = /\{%-?\s*schema\s*-?%\}([\s\S]*?)\{%-?\s*endschema\s*-?%\}/
+  const schemaMatch = schemaRe.exec(content)
+  let formattedSchemaBlock = null
+  let prettierInput = content
+  if (schemaMatch) {
+    const rawJson = schemaMatch[1].trim()
+    let formattedJson = rawJson
+    try {
+      formattedJson = JSON.stringify(JSON.parse(rawJson), null, 2)
+    } catch {
+      // Schema is not valid JSON — leave it raw; validateSchema reports it.
+    }
+    formattedSchemaBlock = `{% schema %}\n${formattedJson}\n{% endschema %}`
+    prettierInput = content.replace(schemaMatch[0], SCHEMA_PLACEHOLDER)
+  }
+  try {
+    const out = await prettier.format(prettierInput, {
+      parser: 'html',
+      printWidth: 100,
+      tabWidth: 2,
+      htmlWhitespaceSensitivity: 'css',
+    })
+    if (formattedSchemaBlock) {
+      if (!out.includes(SCHEMA_PLACEHOLDER)) {
+        // Prettier dropped or mangled the placeholder — bail out unformatted
+        // rather than silently lose the schema block.
+        log(verbose, 'prettier dropped schema placeholder — writing unformatted')
+        return { content, formatted: false, reason: 'prettier-placeholder-lost' }
+      }
+      return {
+        content: out.replace(SCHEMA_PLACEHOLDER, formattedSchemaBlock),
+        formatted: true,
+        reason: null,
+      }
+    }
+    return { content: out, formatted: true, reason: null }
+  } catch (err) {
+    log(verbose, `prettier failed: ${err.message} — writing unformatted`)
+    return { content, formatted: false, reason: `prettier-error: ${err.message}` }
+  }
+}
+
+// --- entry --------------------------------------------------------------------
+
+const argv = process.argv.slice(2)
+
+if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+  process.stdout.write(HELP)
+  process.exit(0)
+}
+
+const subcommand = argv[0]
+const rest = argv.slice(1)
+
+if (subcommand !== 'validate' && subcommand !== 'write') {
+  fail(`unknown subcommand '${subcommand}' — use 'validate' or 'write'`)
+}
+
+const { values } = parseArgs({
+  args: rest,
+  options: {
+    'liquid-file': { type: 'string' },
+    'output-path': { type: 'string' },
+    verbose: { type: 'boolean', default: false },
+    help: { type: 'boolean', default: false },
+  },
+  strict: false,
+})
+
+if (values.help) {
+  process.stdout.write(HELP)
+  process.exit(0)
+}
+
+async function main() {
+  if (subcommand === 'validate') {
+    if (!values['liquid-file']) fail('validate: missing --liquid-file')
+    const path = resolve(values['liquid-file'])
+    let liquid
+    try {
+      liquid = await readFile(path, 'utf8')
+    } catch (err) {
+      fail(`validate: cannot read ${path}: ${err.message}`, 1)
+    }
+    log(values.verbose, `validating ${path} (${liquid.length} bytes)`)
+    const report = await validateLiquid(liquid, values.verbose)
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+    process.exit(report.passed ? 0 : 3)
+  }
+
+  if (subcommand === 'write') {
+    if (!values['output-path']) fail('write: missing --output-path')
+    const out = resolve(values['output-path'])
+    let liquid
+    try {
+      liquid = await readStdin()
+    } catch (err) {
+      fail(`write: failed to read stdin: ${err.message}`, 1)
+    }
+    if (!liquid.trim()) fail('write: stdin was empty', 2)
+    log(values.verbose, `read ${liquid.length} bytes from stdin`)
+    // Schema validation runs in write too — surface as part of metadata so
+    // callers know whether the persisted file has a parseable schema.
+    const schemaResult = validateSchema(liquid)
+    const validatedSchema = schemaResult.schema !== null && schemaResult.errors.length === 0
+    const fmt = await tryPrettierFormat(liquid, values.verbose)
+    try {
+      await mkdir(dirname(out), { recursive: true })
+      await writeFile(out, fmt.content, 'utf8')
+    } catch (err) {
+      fail(`write: failed to write ${out}: ${err.message}`, 1)
+    }
+    const payload = JSON.stringify(
+      {
+        path: out,
+        bytes: Buffer.byteLength(fmt.content, 'utf8'),
+        formatted: fmt.formatted,
+        formatterSkippedReason: fmt.reason,
+        validatedSchema,
+        schemaErrors: schemaResult.errors,
+      },
+      null,
+      2,
+    )
+    process.stdout.write(`${payload}\n`)
+    process.exit(0)
+  }
+}
+
+main().catch((err) => fail(`unhandled: ${err.stack || err.message}`, 1))