similarbuild 0.1.0

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

@@ -0,0 +1,424 @@
+#!/usr/bin/env node
+// test-build-shopify.mjs — Smoke tests for build-shopify.mjs.
+// Validates: --help works, missing args fail with exit 2, validate catches the
+// canonical Liquid/schema/anti-pattern violations (exit 3), validate passes a
+// clean fragment (exit 0), write persists to the requested path. No prettier
+// or liquidjs dependency required for tests to pass.
+
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve, join } from 'node:path'
+import { mkdirSync, writeFileSync, readFileSync, rmSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { strict as assert } from 'node:assert'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const SCRIPT = resolve(here, '..', 'build-shopify.mjs')
+const TMP = join(tmpdir(), `sb-build-shopify-test-${process.pid}`)
+
+mkdirSync(TMP, { recursive: true })
+
+let passed = 0
+let failed = 0
+
+function test(name, fn) {
+  try {
+    fn()
+    process.stdout.write(`ok - ${name}\n`)
+    passed++
+  } catch (err) {
+    process.stdout.write(`not ok - ${name}\n  ${err.message}\n`)
+    failed++
+  }
+}
+
+async function testAsync(name, fn) {
+  try {
+    await fn()
+    process.stdout.write(`ok - ${name}\n`)
+    passed++
+  } catch (err) {
+    process.stdout.write(`not ok - ${name}\n  ${err.message}\n`)
+    failed++
+  }
+}
+
+function run(args, input) {
+  return spawnSync('node', [SCRIPT, ...args], {
+    encoding: 'utf8',
+    input: input ?? undefined,
+  })
+}
+
+function writeTmp(name, content) {
+  const p = join(TMP, name)
+  writeFileSync(p, content)
+  return p
+}
+
+const CLEAN_LIQUID = `
+{% style %}
+  .sb-hero, .sb-hero * { box-sizing: border-box; margin: 0; padding: 0; }
+  .sb-hero { width: 100vw; margin-left: calc(50% - 50vw); }
+  .sb-hero .sb-hero__title { font-size: 32px !important; font-weight: 700 !important; }
+  .sb-hero .sb-hero__media { aspect-ratio: 1 / 1.3; max-height: 700px; }
+  @media (min-width: 1000px) {
+    .sb-hero .sb-hero__media { aspect-ratio: 16 / 9; }
+  }
+{% endstyle %}
+
+<section class="sb-hero">
+  {% if section.settings.hero_image %}
+    <img src="{{ section.settings.hero_image | image_url: width: 1200 }}" alt="{{ section.settings.heading | escape }}" loading="eager" fetchpriority="high">
+  {% else %}
+    <img src="/assets/abc123.jpg" alt="{{ section.settings.heading | escape }}" loading="eager" width="1200" height="900">
+  {% endif %}
+  <h1 class="sb-hero__title">{{ section.settings.heading | escape }}</h1>
+  <button type="button" class="sb-hero__cta" aria-label="Shop now">{{ section.settings.cta_label | escape }}</button>
+  <img src="/assets/def456.jpg" alt="" loading="lazy">
+</section>
+
+{% schema %}
+{
+  "name": "Hero (cloned)",
+  "tag": "section",
+  "class": "sb-hero-wrapper",
+  "settings": [
+    { "type": "header", "content": "Content" },
+    { "type": "text", "id": "heading", "label": "Heading", "default": "Welcome" },
+    { "type": "image_picker", "id": "hero_image", "label": "Hero image" },
+    { "type": "text", "id": "cta_label", "label": "CTA label", "default": "Shop now" },
+    { "type": "url", "id": "cta_link", "label": "CTA link" }
+  ],
+  "presets": [
+    { "name": "Hero — clone of source", "category": "Image" }
+  ]
+}
+{% endschema %}
+`
+
+// ---- Help and arg validation ----
+
+test('--help exits 0 and prints usage', () => {
+  const r = run(['--help'])
+  assert.equal(r.status, 0, `exit code was ${r.status}`)
+  assert.match(r.stdout, /build-shopify\.mjs/)
+  assert.match(r.stdout, /validate/)
+  assert.match(r.stdout, /write/)
+})
+
+test('no args exits 0 and shows help', () => {
+  const r = run([])
+  assert.equal(r.status, 0)
+  assert.match(r.stdout, /Subcommands/)
+})
+
+test('unknown subcommand exits 2', () => {
+  const r = run(['frobnicate'])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /unknown subcommand/)
+})
+
+test('validate without --liquid-file exits 2', () => {
+  const r = run(['validate'])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /missing --liquid-file/)
+})
+
+test('write without --output-path exits 2', () => {
+  const r = run(['write'], '<div></div>')
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /missing --output-path/)
+})
+
+test('write with empty stdin exits 2', () => {
+  const r = run(['write', '--output-path', join(TMP, 'never.liquid')], '')
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /stdin was empty/)
+})
+
+// ---- Validation: clean fragment passes ----
+
+test('validate: clean fragment passes (exit 0)', () => {
+  const p = writeTmp('clean.liquid', CLEAN_LIQUID)
+  const r = run(['validate', '--liquid-file', p])
+  assert.equal(r.status, 0, `stderr: ${r.stderr}\nstdout: ${r.stdout}`)
+  const report = JSON.parse(r.stdout)
+  assert.equal(report.passed, true)
+  assert.equal(report.errorCount, 0)
+  assert.equal(report.schemaValidated, true)
+})
+
+// ---- Validation: schema rules ----
+
+test('validate: missing {% schema %} reports error', () => {
+  const liquid = CLEAN_LIQUID.replace(/\{%\s*schema\s*%\}[\s\S]*?\{%\s*endschema\s*%\}/, '')
+  const p = writeTmp('no-schema.liquid', liquid)
+  const r = run(['validate', '--liquid-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.errors.find((e) => e.rule === 'schema-missing'))
+})
+
+test('validate: invalid schema JSON reports error', () => {
+  const liquid = CLEAN_LIQUID.replace(
+    '"name": "Hero (cloned)",',
+    '"name": "Hero (cloned)" THIS IS NOT JSON,',
+  )
+  const p = writeTmp('bad-json.liquid', liquid)
+  const r = run(['validate', '--liquid-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.errors.find((e) => e.rule === 'schema-invalid-json'))
+})
+
+test('validate: schema without name reports error', () => {
+  const liquid = CLEAN_LIQUID.replace('"name": "Hero (cloned)",', '')
+  const p = writeTmp('no-name.liquid', liquid)
+  const r = run(['validate', '--liquid-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.errors.find((e) => e.rule === 'schema-missing-name'))
+})
+
+test('validate: schema without presets reports error', () => {
+  const liquid = CLEAN_LIQUID.replace(
+    /"presets":\s*\[\s*\{[^}]+\}\s*\]/,
+    '"presets": []',
+  )
+  const p = writeTmp('no-presets.liquid', liquid)
+  const r = run(['validate', '--liquid-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.errors.find((e) => e.rule === 'schema-missing-presets'))
+})
+
+test('validate: image_picker with default reports error (anti-pattern #11)', () => {
+  const liquid = CLEAN_LIQUID.replace(
+    '{ "type": "image_picker", "id": "hero_image", "label": "Hero image" }',
+    '{ "type": "image_picker", "id": "hero_image", "label": "Hero image", "default": "/foo.jpg" }',
+  )
+  const p = writeTmp('image-default.liquid', liquid)
+  const r = run(['validate', '--liquid-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.errors.find((e) => e.rule === 'schema-image-picker-default'))
+})
+
+test('validate: duplicate setting id reports error', () => {
+  const liquid = CLEAN_LIQUID.replace(
+    '{ "type": "text", "id": "cta_label", "label": "CTA label", "default": "Shop now" },',
+    '{ "type": "text", "id": "heading", "label": "Duplicate", "default": "X" },',
+  )
+  const p = writeTmp('dup-id.liquid', liquid)
+  const r = run(['validate', '--liquid-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.errors.find((e) => e.rule === 'schema-setting-duplicate-id'))
+})
+
+// ---- Validation: Liquid tag balance ----
+
+test('validate: unclosed {% if %} reports error', () => {
+  // Replace the {% endif %} that closes the hero_image conditional.
+  const liquid = CLEAN_LIQUID.replace('{% endif %}', '')
+  const p = writeTmp('unclosed-if.liquid', liquid)
+  const r = run(['validate', '--liquid-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.errors.find((e) => e.rule === 'liquid-unclosed-tag'))
+})
+
+test('validate: mismatched end tag reports error', () => {
+  const liquid = CLEAN_LIQUID.replace('{% endif %}', '{% endfor %}')
+  const p = writeTmp('mismatched.liquid', liquid)
+  const r = run(['validate', '--liquid-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(
+    report.errors.find((e) =>
+      e.rule === 'liquid-mismatched-end' || e.rule === 'liquid-unmatched-end' || e.rule === 'liquid-unclosed-tag',
+    ),
+  )
+})
+
+// ---- Validation: surface anti-patterns ----
+
+test('validate: <img> without alt reports error', () => {
+  const liquid = CLEAN_LIQUID.replace(
+    '<img src="/assets/def456.jpg" alt="" loading="lazy">',
+    '<img src="/assets/def456.jpg" loading="lazy">',
+  )
+  const p = writeTmp('no-alt.liquid', liquid)
+  const r = run(['validate', '--liquid-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.errors.find((e) => e.rule === 'img-missing-alt'))
+})
+
+test('validate: <button> without type reports error', () => {
+  const liquid = CLEAN_LIQUID.replace(
+    '<button type="button" class="sb-hero__cta" aria-label="Shop now">',
+    '<button class="sb-hero__cta" aria-label="Shop now">',
+  )
+  const p = writeTmp('no-type.liquid', liquid)
+  const r = run(['validate', '--liquid-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.errors.find((e) => e.rule === 'button-missing-type'))
+})
+
+test('validate: 100vh on height reports error (anti-pattern #1)', () => {
+  const liquid = CLEAN_LIQUID.replace('aspect-ratio: 1 / 1.3; max-height: 700px;', 'height: 100vh;')
+  const p = writeTmp('vh.liquid', liquid)
+  const r = run(['validate', '--liquid-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.errors.find((e) => e.rule === 'hero-100vh'))
+})
+
+test('validate: data:image/svg+xml in img src reports error (anti-pattern #8)', () => {
+  const liquid = CLEAN_LIQUID.replace(
+    '<img src="/assets/def456.jpg" alt="" loading="lazy">',
+    '<img src="data:image/svg+xml,%3Csvg%3E%3C/svg%3E" alt="" loading="lazy">',
+  )
+  const p = writeTmp('fake-svg.liquid', liquid)
+  const r = run(['validate', '--liquid-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.errors.find((e) => e.rule === 'fabricated-svg-data-uri'))
+})
+
+test('validate: Google Fonts <link rel="stylesheet"> reports error (anti-pattern #14)', () => {
+  const liquid = CLEAN_LIQUID.replace(
+    '<section class="sb-hero">',
+    '<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter&display=swap">\n<section class="sb-hero">',
+  )
+  const p = writeTmp('fonts-link.liquid', liquid)
+  const r = run(['validate', '--liquid-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.errors.find((e) => e.rule === 'fonts-link-in-section'))
+})
+
+test('validate: block loop without {{ block.shopify_attributes }} reports error (anti-pattern #13)', () => {
+  // Inject a minimal block loop into a fresh liquid (and add a matching schema with blocks).
+  const minimalLiquid = `
+{% style %}
+  .sb-list, .sb-list * { box-sizing: border-box; }
+  .sb-list .sb-list__item { padding: 8px; }
+{% endstyle %}
+<ul class="sb-list">
+  {% for block in section.blocks %}
+    <li class="sb-list__item">{{ block.settings.label }}</li>
+  {% endfor %}
+</ul>
+{% schema %}
+{
+  "name": "List",
+  "tag": "section",
+  "settings": [],
+  "blocks": [
+    { "type": "item", "name": "Item", "settings": [{ "type": "text", "id": "label", "label": "Label", "default": "x" }] }
+  ],
+  "presets": [{ "name": "List", "category": "Text" }]
+}
+{% endschema %}
+`
+  const p = writeTmp('no-shopify-attr.liquid', minimalLiquid)
+  const r = run(['validate', '--liquid-file', p])
+  assert.equal(r.status, 3)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.errors.find((e) => e.rule === 'block-missing-shopify-attributes'))
+})
+
+test('validate: missing reset emits warning (not error)', () => {
+  const minimal = `
+{% style %}
+  .sb-x .sb-x__y { color: red; }
+{% endstyle %}
+<section class="sb-x"><span class="sb-x__y">hi</span></section>
+{% schema %}
+{ "name": "X", "settings": [], "presets": [{ "name": "X" }] }
+{% endschema %}
+`
+  const p = writeTmp('no-reset.liquid', minimal)
+  const r = run(['validate', '--liquid-file', p])
+  assert.equal(r.status, 0, `stderr: ${r.stderr}\nstdout: ${r.stdout}`)
+  const report = JSON.parse(r.stdout)
+  assert.ok(report.warnings.find((w) => w.rule === 'no-reset-box-sizing'))
+})
+
+// ---- write subcommand ----
+
+test('write: persists stdin to output path', () => {
+  const out = join(TMP, 'nested', 'out.liquid')
+  const r = run(['write', '--output-path', out], CLEAN_LIQUID)
+  assert.equal(r.status, 0, `stderr: ${r.stderr}`)
+  const report = JSON.parse(r.stdout)
+  assert.equal(report.path, out)
+  assert.ok(report.bytes > 0)
+  assert.equal(report.validatedSchema, true)
+  assert.ok(existsSync(out))
+  const content = readFileSync(out, 'utf8')
+  assert.match(content, /\{%\s*schema\s*%\}/)
+  assert.match(content, /sb-hero/)
+})
+
+test('write: creates parent directories', () => {
+  const out = join(TMP, 'a', 'b', 'c', 'deep.liquid')
+  const r = run(['write', '--output-path', out], CLEAN_LIQUID)
+  assert.equal(r.status, 0)
+  assert.ok(existsSync(out))
+})
+
+test('write: reports validatedSchema=false on broken schema (still writes)', () => {
+  const out = join(TMP, 'broken.liquid')
+  const broken = CLEAN_LIQUID.replace('"name": "Hero (cloned)",', '')
+  const r = run(['write', '--output-path', out], broken)
+  assert.equal(r.status, 0)
+  const report = JSON.parse(r.stdout)
+  assert.equal(report.validatedSchema, false)
+  assert.ok(report.schemaErrors.length > 0)
+  assert.ok(existsSync(out))
+})
+
+// Pattern #29: prettier's HTML parser word-wraps long string literals inside
+// {% schema %} JSON, inserting \n inside JSON strings. The fix splits the
+// schema block out, formats its JSON with JSON.stringify, and re-injects after
+// prettier. Strings ≥ printWidth (100) must survive intact.
+test('write: schema with long-string default round-trips as parseable JSON', () => {
+  const longString = 'Revolutionizing Hair Care With Micro Infusion — Made for Men Who Care About Their Look And Confidence.'
+  const liquidWithLongString = CLEAN_LIQUID.replace(
+    '"default": "Welcome"',
+    `"default": "${longString}"`,
+  )
+  const out = join(TMP, 'long-string.liquid')
+  const r = run(['write', '--output-path', out], liquidWithLongString)
+  assert.equal(r.status, 0, `stderr: ${r.stderr}`)
+  const written = readFileSync(out, 'utf8')
+  const m = /\{%\s*schema\s*%\}([\s\S]*?)\{%\s*endschema\s*%\}/.exec(written)
+  assert.ok(m, 'schema block missing in written file')
+  // Must parse cleanly — no \n injected mid-string.
+  const parsed = JSON.parse(m[1].trim())
+  const heading = parsed.settings.find((s) => s.id === 'heading')
+  assert.equal(heading.default, longString, 'long-string default must survive verbatim')
+  // Re-validate the written file end-to-end — schema must pass.
+  const v = run(['validate', '--liquid-file', out])
+  assert.equal(v.status, 0, `re-validation failed:\nstderr: ${v.stderr}\nstdout: ${v.stdout}`)
+  const vReport = JSON.parse(v.stdout)
+  assert.equal(vReport.schemaValidated, true)
+})
+
+// ---- Cleanup ----
+
+try {
+  rmSync(TMP, { recursive: true, force: true })
+} catch {}
+
+if (failed > 0) {
+  process.stdout.write(`\n${failed} failed, ${passed} passed\n`)
+  process.exit(1)
+}
+process.stdout.write(`\n${passed} passed\n`)
+process.exit(0)

package/templates/skills/sb-build-wp/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: sb-build-wp
+description: Composes a standalone WordPress/Elementor HTML fragment from a live-page inspection plus extracted assets, with defensive specificity, mobile-first CSS, and a11y/perf defaults baked in. Use when the SimilarBuild orchestrator (`/build-page`, `/build-site`, `/clip-section`) requests a WP build with `--target wp`, or when the user asks to 'build wp html' from an inspection + assets bundle.
+---
+
+# sb-build-wp
+
+## Overview
+
+Produces the single `.html` fragment a user pastes into an Elementor HTML widget — a `<style>` block scoped to one root class, the matching markup, and (when the section needs interactivity) a small `<script>` block. The fragment must survive Elementor's container constraints and the active theme's `!important`-laced overrides without any post-paste tweaking. Production-grade from the first build: every image has alt + correct loading hint, hero is preloaded, fonts use `display=swap`, buttons are `type="button"`, headings don't skip levels.
+
+Unlike the upstream skills (`sb-inspect-live`, `sb-extract-assets`) where a script does ~95% of the work, **this skill is creative composition**. The LLM picks the pattern, names the classes, structures the markup, and decides where to apply defensive specificity. The `scripts/build-wp.mjs` helper handles only the deterministic plumbing around the composition: structural validation of the produced HTML and formatted persistence to disk.
+
+Act as a WordPress/Elementor specialist. You know exactly which theme overrides bite (font-family, font-size, font-weight, color via `.elementor *` blanket rules; `img { height: auto !important }`; button background reset) and you defend against all of them with chained-scope selectors and surgical `!important` on the four font properties only. You do NOT touch Liquid, Shopify schema, or any other target — that's a different skill's job.
+
+## Inputs
+
+| Argument          | Required | Notes                                                                                         |
+| ----------------- | -------- | --------------------------------------------------------------------------------------------- |
+| `inspection`      | yes      | Path to `inspection.json` from `sb-inspect-live`. Drives section type, tokens, DOM structure. |
+| `assetsMap`       | yes      | Path to `assets-map.json` from `sb-extract-assets`. Source of every `<img src>` and inline SVG. |
+| `outputPath`      | yes      | Where the final `.html` is written (parent dirs created automatically).                       |
+| `designKnowledge` | no       | Subset of `<plugin>/memory/design-knowledge.md` filtered by the orchestrator (a11y/perf rules relevant to this section). When absent, use the defaults in `references/wp-build-rules.md`. |
+| `fixHints`        | no       | JSON array from `sb-review-checks` after a failed validation cycle. When present, you are patching a previous build, not building from scratch. |
+| `previousHtmlPath` | no      | Path to the previous build (only meaningful with `fixHints`). Read it, apply the targeted patches, do not refactor untouched code. |
+
+The orchestrator passes these as concrete paths or inline values — there is no CLI for this skill, the LLM drives.
+
+## Output
+
+A single `.html` file written to `outputPath`. The file is a fragment — no `<html>`, `<head>`, or `<body>` wrappers — containing in order:
+
+1. Optional `<link rel="preconnect">` (fonts.googleapis.com, fonts.gstatic.com), `<link rel="preload" as="image">` for the hero, `<link rel="stylesheet">` for the Google Font.
+2. A `<style>` block: universal reset → scope container (full-bleed if applicable) → mobile-first element styles with chained-scope selectors → `@media (min-width: 1000px)` desktop overrides.
+3. The scoped markup (`<section class="{scope}">...</section>` or appropriate semantic root).
+4. Optional `<script>` block for vanilla JS interactivity.
+
+## On Activation
+
+1. **Read the inputs.** Parse `inspection.json` (capture `sectionType`, `tokens`, `dom`, `pseudoElements`, `imgUrls`) and `assets-map.json` (the URL → localPath / inline-SVG dictionary). If `fixHints` is given, also read `previousHtmlPath`.
+
+2. **Load the build rules.** Read `references/wp-build-rules.md` — this file contains the composition contract, defensive-specificity rule, !important policy, full-bleed escape, mobile-first breakpoint, asset-substitution rule, hero rules (no 100vh), Google Fonts inlining, accessibility/performance defaults, the canonical patterns A-H, and the anti-patterns #1-9. Treat it as your reference manual for this build.
+
+3. **Layer in user-curated knowledge if present.** When `<plugin>/memory/patterns.md`, `<plugin>/memory/anti-patterns.md`, or `<plugin>/presets/wp-elementor.yaml` exist in the host project, load them and let them OVERRIDE the matching defaults from `wp-build-rules.md` — they reflect the user's most recent learning. Skip silently when missing (the framework is early; these get populated over time).
+
+4. **Compose the HTML.** Pick the pattern that matches `inspection.sectionType` (and the markup shape — inspect `dom` and `pseudoElements`). Apply every non-negotiable from `wp-build-rules.md`: defensive specificity on every critical selector, `!important` on font-family/font-size/font-weight/color, universal reset at the top, full-bleed container if the section spans viewport-edge, mobile-first base + desktop media query, every `<img src>` resolved through `assetsMap.assets[url].localPath`, SVGs inlined from `assetsMap.assets[url].inline`, no fabricated SVG, no `100vh` for hero, Google Fonts preconnect + display=swap, hero preload link, alt on every image, type="button" on every button, heading hierarchy unbroken. The `designKnowledge` subset (when passed) extends or refines these defaults — apply it.
+
+5. **If `fixHints` are present, patch surgically.** Read the previous output, apply each fixHint to the specific selector or markup it names, and keep everything else untouched. The reviewer's diff should be the only diff. High-severity hints are mandatory; low-severity are optional unless they conflict.
+
+6. **Validate.** Write the composed HTML to a temp file and run:
+
+   ```bash
+   node {skill-root}/scripts/build-wp.mjs validate --html-file <tmp>
+   ```
+
+   The script reports structural errors (missing `<style>`, missing alt/type, `data:image/svg+xml` raster impostors, `100vh` on heights, fonts without `display=swap`) and warnings (no preload, no preconnect, no defensive-specificity selectors, no reset). Exit code 0 means errors are clean. If it exits 1, fix the flagged issues and re-validate. Warnings are advisory — fix what you can without overstepping the inputs.
+
+7. **Persist.** Pipe the validated HTML into:
+
+   ```bash
+   node {skill-root}/scripts/build-wp.mjs write --output-path <outputPath>
+   ```
+
+   The script formats with prettier when available (graceful skip when not installed) and writes to `outputPath`, creating parent directories as needed. It returns `{path, bytes, formatted}` JSON.
+
+8. **Return the result** to the orchestrator: the absolute path to the written file, the validator's report (errors + warnings), and a short note on which pattern was applied. Do not return the file's contents — the orchestrator reads the file when it needs them.
+
+## Failure modes
+
+| Symptom                                         | Likely cause                                  | What to surface                                                            |
+| ----------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------- |
+| Validator returns errors after first compose    | Missed a non-negotiable from the rules        | Fix and re-validate (up to 2 attempts). If still failing, surface the report. |
+| `assetsMap.failed[]` includes a critical asset  | Source 404 / network failure during extract   | Drop the image (decorative) or use a literal-color placeholder (hero). Never fabricate. Comment in the output: `<!-- sb-build-wp: asset failed download -->`. |
+| `inspection.widgetBlocked: true`                | Bot challenge on inspect — DOM is unreliable  | Stop. Tell the orchestrator the inspection is unusable. Do not compose from a blocked page. |
+| Pattern doesn't match any section in `inspection.dom` | Section type detected but markup is ambiguous | Pick the closest pattern from A-H, document the choice in a comment, and surface to the orchestrator. |
+| Prettier missing                                | Optional dep not installed                    | Non-fatal — `write` reports `formatted: false, formatterSkippedReason: "prettier-not-installed"`. Output is still written. |
+
+## Conventions
+
+- Bare paths (e.g. `scripts/build-wp.mjs`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory.
+- `{project-root}` resolves to the project working directory.
+- `<plugin>/memory/...` and `<plugin>/presets/...` are paths inside the SimilarBuild plugin install — read them when present, fall back to bundled defaults when absent.