npm - similarbuild - Versions diffs - 0.1.0 - Mend

similarbuild 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (76) hide show

package/templates/presets/shopify-section.yaml ADDED Viewed

@@ -0,0 +1,51 @@
+# shopify-section preset — theme reset CSS + wrapper for sb-validate-render's
+# local rendering of a Shopify section .liquid file.
+#
+# Functionally equivalent to FALLBACK_PRESETS['shopify-section'] in
+# .claude/skills/sb-validate-render/scripts/validate-render.mjs. Extracting it
+# here turns the hardcoded baseline into a declarative, customizable artifact:
+# the installer (item #16) will copy this file into <plugin>/presets/, where
+# sb-validate-render auto-resolves it; users can edit it for their specific
+# theme (Dawn, Sense, Studio, custom OS 2.0) without touching skill code.
+#
+# Resolve order in sb-validate-render:
+#   1. --preset-yaml <path> CLI override
+#   2. <plugin>/presets/shopify-section.yaml (auto-resolved)
+#   3. baked-in FALLBACK_PRESETS (this file's mirror)
+#
+# When YAML is loaded, it is shallow-merged INTO the baked-in fallback so a
+# partial override (e.g. only `reset_css`) still inherits the other keys.
+#
+# This baseline encodes what Dawn / typical OS 2.0 themes inject at the section
+# level. It is informational simulation, NOT what your build emits — your
+# build's CSS must DEFEAT this via chained-scope specificity. See
+# sb-build-shopify/references/shopify-build-rules.md.
+wrapper:
+  tag: div
+  class: page-width
+# Aggressive reset injected around the rendered Liquid fragment at validate
+# time. Mirrors Dawn's typography + spacing baseline. Note: `html { font-size:
+# 62.5% }` is Dawn's idiom (1rem = 10px), which is why every rem value below
+# matches Dawn's effective pixel size.
+reset_css: |-
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; font-size: 16px; line-height: 1.5; color: rgb(18, 18, 18); margin: 0; }
+  .page-width { max-width: 120rem; padding: 0 1.5rem; margin: 0 auto; box-sizing: border-box; }
+  h1 { font-size: 4rem; font-weight: 400; line-height: 1.1; letter-spacing: -0.05rem; margin: 0 0 1.5rem; }
+  h2 { font-size: 3rem; font-weight: 400; line-height: 1.15; letter-spacing: -0.04rem; margin: 0 0 1.25rem; }
+  h3 { font-size: 2.4rem; font-weight: 400; line-height: 1.2; letter-spacing: -0.03rem; margin: 0 0 1rem; }
+  button, .button { background: rgb(18, 18, 18); color: rgb(255, 255, 255); border: 0.1rem solid rgb(18, 18, 18); border-radius: 0; padding: 1.5rem 3rem; font-size: 1.5rem; font-weight: 500; cursor: pointer; }
+  img { max-width: 100%; height: auto; display: block; }
+  * { box-sizing: border-box; }
+  html { font-size: 62.5%; }
+# Shopify owns <head>; the theme already loads its own fonts via `font_face` or
+# theme settings. Leave empty unless customizing for a theme that needs an
+# explicit font preload at validate time (rare — usually inheritance handles it
+# and the build's typography wins via chained-scope specificity).
+head_extras: ""
+# Default selector for token probing + section bbox when --selector is not
+# passed on the CLI. `.page-width` is Dawn's section wrapper class.
+default_probe_root: .page-width

package/templates/presets/wp-elementor.yaml ADDED Viewed

@@ -0,0 +1,49 @@
+# wp-elementor preset — theme reset CSS + wrapper + Google Fonts injection
+# for sb-validate-render's local rendering of an Elementor HTML widget output.
+#
+# Functionally equivalent to FALLBACK_PRESETS['wp-elementor'] in
+# .claude/skills/sb-validate-render/scripts/validate-render.mjs. Extracting it
+# here turns the hardcoded baseline into a declarative, customizable artifact:
+# the installer (item #16) will copy this file into <plugin>/presets/, where
+# sb-validate-render auto-resolves it; users can edit it for their specific
+# theme (Astra, Hello, OceanWP, custom) without touching skill code.
+#
+# Resolve order in sb-validate-render:
+#   1. --preset-yaml <path> CLI override
+#   2. <plugin>/presets/wp-elementor.yaml (auto-resolved)
+#   3. baked-in FALLBACK_PRESETS (this file's mirror)
+#
+# When YAML is loaded, it is shallow-merged INTO the baked-in fallback so a
+# partial override (e.g. only `reset_css`) still inherits the other keys.
+#
+# This baseline encodes what Elementor + a typical paired theme (Hello, Astra)
+# inject via blanket `.elementor *` rules. It is informational simulation, NOT
+# what your build emits — your build's CSS must DEFEAT this via chained-scope
+# specificity. See sb-build-wp/references/wp-build-rules.md.
+wrapper:
+  tag: div
+  class: elementor
+# Aggressive reset injected around the fragment at validate time. Mirrors what
+# the Elementor + active-theme stack typically applies via `.elementor *` and
+# `img { height: auto !important }` blanket rules. The build under test must
+# win on specificity against every property listed here.
+reset_css: |-
+  .elementor, .elementor * { font-weight: 300 !important; font-size: 18px !important; font-family: 'Roboto', sans-serif !important; }
+  .elementor h1, .elementor h2, .elementor h3 { font-weight: 300 !important; font-size: 24px !important; }
+  .elementor img, img { max-width: 100% !important; height: auto !important; border-radius: 0 !important; }
+  .elementor button, button { background: transparent !important; border: 0 !important; padding: 0 !important; }
+# Injected BEFORE the reset so 'Roboto' is actually available when the reset
+# forces font-family. Without this, the reset names a font the rendered page
+# does not have, and the screenshot falls back to the system stack — masking
+# real font-related diff in sb-compare-visual.
+head_extras: |-
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;700&display=swap">
+# Default selector for token probing + section bbox when --selector is not
+# passed on the CLI. The wrapper class IS the boundary in Elementor fragments.
+default_probe_root: .elementor

package/templates/reports/fixtures/mock-run-1.json ADDED Viewed

@@ -0,0 +1,115 @@
+{
+  "projectSlug": "example-store",
+  "rootUrl": "https://example-store.com",
+  "target": "wp",
+  "currentRun": {
+    "timestamp": "2026-05-05T14:23:01Z",
+    "durationMs": 187340,
+    "totalIterations": 4,
+    "totals": { "ok": 3, "warn": 1, "fail": 1 },
+    "pageResults": [
+      {
+        "url": "https://example-store.com/",
+        "type": "home",
+        "slug": "home",
+        "status": "ok",
+        "diffPercent": 8.42,
+        "iterations": 1,
+        "outputPath": "clean/home/index.html",
+        "screenshotsLive": "validations/home-1/live-cropped.png",
+        "screenshotsBuild": "validations/home-1/build-cropped.png",
+        "diffMap": "validations/home-1/diff.png",
+        "violations": [],
+        "structuredDiffs": [
+          { "key": "h1.font-size", "live": "48px", "build": "44px", "severity": "med" },
+          { "key": "section.padding-top", "live": "96px", "build": "96px", "severity": "low" }
+        ],
+        "tokens": {
+          "live":  { "h1.font-size": "48px", "h1.color": "rgb(20,20,20)", "button.bg": "rgb(255,86,0)" },
+          "build": { "h1.font-size": "44px", "h1.color": "rgb(20,20,20)", "button.bg": "rgb(255,86,0)" }
+        },
+        "candidateFixes": []
+      },
+      {
+        "url": "https://example-store.com/products/foo",
+        "type": "pdp",
+        "slug": "products-foo",
+        "status": "ok",
+        "diffPercent": 4.91,
+        "iterations": 0,
+        "outputPath": "clean/pdp/products-foo.html",
+        "screenshotsLive": "validations/pdp-foo-0/live-cropped.png",
+        "screenshotsBuild": "validations/pdp-foo-0/build-cropped.png",
+        "diffMap": "validations/pdp-foo-0/diff.png",
+        "violations": [],
+        "structuredDiffs": [],
+        "tokens": null,
+        "candidateFixes": []
+      },
+      {
+        "url": "https://example-store.com/pages/contact",
+        "type": "pages",
+        "slug": "pages-contact",
+        "status": "warn",
+        "diffPercent": 14.27,
+        "iterations": 2,
+        "outputPath": "clean/pages/pages-contact.html",
+        "screenshotsLive": "validations/pages-contact-2/live-cropped.png",
+        "screenshotsBuild": "validations/pages-contact-2/build-cropped.png",
+        "diffMap": "validations/pages-contact-2/diff.png",
+        "violations": [
+          { "id": "anti-pattern-#5", "severity": "medium", "message": "Defensive specificity missing on .scope button — chain class + !important required to escape Elementor reset." }
+        ],
+        "structuredDiffs": [
+          { "key": "form.gap", "live": "16px", "build": "12px", "severity": "low" }
+        ],
+        "candidateFixes": [
+          "Add .scope.scope__contact { } around the form to chain specificity (Pattern E).",
+          "!important on button { background: …; color: … } to defeat Elementor reset."
+        ]
+      },
+      {
+        "url": "https://example-store.com/blog/article",
+        "type": "pages",
+        "slug": "blog-article",
+        "status": "ok",
+        "diffPercent": 6.12,
+        "iterations": 0,
+        "outputPath": "clean/pages/blog-article.html",
+        "screenshotsLive": null,
+        "screenshotsBuild": null,
+        "diffMap": null,
+        "violations": [],
+        "structuredDiffs": [],
+        "candidateFixes": []
+      },
+      {
+        "url": "https://example-store.com/checkout",
+        "type": "pages",
+        "slug": "checkout",
+        "status": "fail",
+        "diffPercent": 75.30,
+        "iterations": 2,
+        "outputPath": "clean/pages/checkout.html",
+        "screenshotsLive": "validations/checkout-2/live-cropped.png",
+        "screenshotsBuild": "validations/checkout-2/build-cropped.png",
+        "diffMap": "validations/checkout-2/diff.png",
+        "violations": [
+          { "id": "widget-blocked", "severity": "high", "message": "Third-party checkout widget did not render in headless browser. URL adjacency probe failed; manual paste of rendered HTML required." }
+        ],
+        "structuredDiffs": [
+          { "key": "section.height", "live": "1840px", "build": "320px", "severity": "high" }
+        ],
+        "candidateFixes": [
+          "Re-run with --user-paste-html=checkout.html (Plan B for widget-blocked pages)."
+        ]
+      }
+    ],
+    "configSnapshot": {
+      "max_parallel_pages": 3,
+      "auto_correct_max_iterations": 2,
+      "diff_threshold_pct": 10,
+      "preset": "wp-elementor"
+    }
+  }
+}

package/templates/reports/fixtures/mock-run-2.json ADDED Viewed

@@ -0,0 +1,72 @@
+{
+  "projectSlug": "example-store",
+  "rootUrl": "https://example-store.com",
+  "target": "wp",
+  "currentRun": {
+    "timestamp": "2026-05-05T18:10:55Z",
+    "durationMs": 142001,
+    "totalIterations": 1,
+    "totals": { "ok": 4, "warn": 1, "fail": 0 },
+    "pageResults": [
+      {
+        "url": "https://example-store.com/",
+        "type": "home",
+        "slug": "home",
+        "status": "ok",
+        "diffPercent": 5.20,
+        "iterations": 0,
+        "outputPath": "clean/home/index.html",
+        "violations": [],
+        "structuredDiffs": []
+      },
+      {
+        "url": "https://example-store.com/products/foo",
+        "type": "pdp",
+        "slug": "products-foo",
+        "status": "ok",
+        "diffPercent": 4.10,
+        "iterations": 0,
+        "outputPath": "clean/pdp/products-foo.html",
+        "violations": []
+      },
+      {
+        "url": "https://example-store.com/pages/contact",
+        "type": "pages",
+        "slug": "pages-contact",
+        "status": "ok",
+        "diffPercent": 7.80,
+        "iterations": 1,
+        "outputPath": "clean/pages/pages-contact.html",
+        "violations": []
+      },
+      {
+        "url": "https://example-store.com/blog/article",
+        "type": "pages",
+        "slug": "blog-article",
+        "status": "ok",
+        "diffPercent": 5.61,
+        "iterations": 0,
+        "outputPath": "clean/pages/blog-article.html",
+        "violations": []
+      },
+      {
+        "url": "https://example-store.com/checkout",
+        "type": "pages",
+        "slug": "checkout",
+        "status": "warn",
+        "diffPercent": 32.10,
+        "iterations": 0,
+        "outputPath": "clean/pages/checkout.html",
+        "violations": [
+          { "id": "widget-blocked", "severity": "medium", "message": "Widget pasted manually; visual still drifts but acceptable for review." }
+        ]
+      }
+    ],
+    "configSnapshot": {
+      "max_parallel_pages": 3,
+      "auto_correct_max_iterations": 2,
+      "diff_threshold_pct": 10,
+      "preset": "wp-elementor"
+    }
+  }
+}

package/templates/reports/report-renderer.mjs ADDED Viewed

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+// SimilarBuild aggregate report renderer.
+//
+// Reads a current-run JSON (stdin OR --input <path>), merges with prior runs
+// preserved inside an existing target HTML (Pattern #38: cumulative reports),
+// substitutes into report-template.html, writes the result.
+//
+// Usage:
+//   cat run.json | node report-renderer.mjs --output reports/index.html
+//   node report-renderer.mjs --input run.json --output reports/index.html
+//   node report-renderer.mjs --input run.json --output out.html --template path/to/template.html
+//   node report-renderer.mjs --input run.json --output out.html --max-previous-runs 10
+//
+// Stderr prefix: [report-renderer]
+import { readFile, writeFile, stat } from "node:fs/promises"
+import { fileURLToPath } from "node:url"
+import { dirname, isAbsolute, resolve } from "node:path"
+const SELF_DIR = dirname(fileURLToPath(import.meta.url))
+const DEFAULT_TEMPLATE = resolve(SELF_DIR, "report-template.html")
+const TEMPLATE_VERSION = "1"
+const STDERR_PREFIX = "[report-renderer]"
+function log(msg) { process.stderr.write(`${STDERR_PREFIX} ${msg}\n`) }
+function fail(msg, code = 1) { log(`fatal: ${msg}`); process.exit(code) }
+function parseArgs(argv) {
+  const out = { input: null, output: null, template: DEFAULT_TEMPLATE, maxPrevious: 20, projectTitle: null }
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i]
+    const next = () => argv[++i]
+    switch (a) {
+      case "--input": out.input = next(); break
+      case "--output": out.output = next(); break
+      case "--template": out.template = next(); break
+      case "--max-previous-runs": out.maxPrevious = parseInt(next(), 10) || 20; break
+      case "--project-title": out.projectTitle = next(); break
+      case "-h": case "--help":
+        process.stdout.write(usage()); process.exit(0)
+      default:
+        fail(`unknown arg: ${a}. Try --help.`)
+    }
+  }
+  if (!out.output) fail("--output is required")
+  return out
+}
+function usage() {
+  return [
+    "report-renderer — emits SimilarBuild aggregate report.html",
+    "",
+    "Required: --output <path>",
+    "Input:    stdin (default) or --input <run.json>",
+    "Optional: --template <path>  --max-previous-runs <N>  --project-title <str>",
+    "",
+  ].join("\n")
+}
+async function readStdin() {
+  return new Promise((resolveP, rejectP) => {
+    let buf = ""
+    if (process.stdin.isTTY) return resolveP("")
+    process.stdin.setEncoding("utf8")
+    process.stdin.on("data", (c) => { buf += c })
+    process.stdin.on("end", () => resolveP(buf))
+    process.stdin.on("error", rejectP)
+  })
+}
+async function loadRunData(args) {
+  let raw
+  if (args.input) {
+    log(`reading run JSON from ${args.input}`)
+    raw = await readFile(args.input, "utf8")
+  } else {
+    log(`reading run JSON from stdin`)
+    raw = await readStdin()
+  }
+  if (!raw || !raw.trim()) fail("no run data on stdin or --input")
+  let json
+  try { json = JSON.parse(raw) } catch (e) { fail(`run JSON parse error: ${e.message}`) }
+  return json
+}
+// Pattern #38: extract prior currentRun + previousRuns from an existing report.
+// We embed all run state in <script type="application/json" id="sb-report-data">…</script>,
+// so a regex pull is sufficient (no need to spin up a DOM parser).
+async function extractPreviousState(outputPath) {
+  let exists = false
+  try { exists = (await stat(outputPath)).isFile() } catch { /* not there */ }
+  if (!exists) return null
+  let html
+  try { html = await readFile(outputPath, "utf8") } catch (e) {
+    log(`warn: could not read existing ${outputPath} for merge: ${e.message}`)
+    return null
+  }
+  const m = html.match(/<script type="application\/json" id="sb-report-data">([\s\S]*?)<\/script>/)
+  if (!m) {
+    log(`warn: existing ${outputPath} has no embedded data block — overwriting without merge`)
+    return null
+  }
+  try {
+    return JSON.parse(m[1])
+  } catch (e) {
+    log(`warn: existing data block unparseable (${e.message}) — overwriting without merge`)
+    return null
+  }
+}
+function normalizeRun(run) {
+  // Defensive — accept skinny inputs but guarantee the shape the template renders against.
+  const r = run && typeof run === "object" ? run : {}
+  const pages = Array.isArray(r.pageResults) ? r.pageResults : []
+  const totals = r.totals || pages.reduce((acc, p) => {
+    const s = String(p.status || "").toLowerCase()
+    if (s === "ok" || s === "pass" || s === "passed" || s === "✅") acc.ok++
+    else if (s === "fail" || s === "failed" || s === "❌") acc.fail++
+    else acc.warn++
+    return acc
+  }, { ok: 0, warn: 0, fail: 0 })
+  return {
+    timestamp: r.timestamp || new Date().toISOString(),
+    durationMs: r.durationMs || 0,
+    totalIterations: r.totalIterations != null ? r.totalIterations : pages.reduce((s, p) => s + (p.iterations || 0), 0),
+    totals,
+    pageResults: pages,
+    configSnapshot: r.configSnapshot || null,
+  }
+}
+function buildPayload(input, prior, args) {
+  const currentRun = normalizeRun(input.currentRun || input.run || input)
+  const projectSlug = input.projectSlug || (prior && prior.projectSlug) || "(unnamed)"
+  const rootUrl = input.rootUrl || (prior && prior.rootUrl) || ""
+  const target = input.target || (prior && prior.target) || ""
+  let previousRuns = []
+  if (prior) {
+    if (prior.currentRun) previousRuns.push(prior.currentRun)
+    if (Array.isArray(prior.previousRuns)) previousRuns = previousRuns.concat(prior.previousRuns)
+  }
+  if (Array.isArray(input.previousRuns)) {
+    // explicit override (e.g., user passed full state)
+    previousRuns = input.previousRuns
+  }
+  if (args.maxPrevious > 0 && previousRuns.length > args.maxPrevious) {
+    log(`trimming previousRuns ${previousRuns.length} → ${args.maxPrevious}`)
+    previousRuns = previousRuns.slice(0, args.maxPrevious)
+  }
+  return {
+    projectSlug,
+    rootUrl,
+    target,
+    currentRun,
+    previousRuns,
+    generatedAt: new Date().toISOString(),
+    templateVersion: TEMPLATE_VERSION,
+  }
+}
+// Safe-embed: prevent JSON breaking out of the host <script> block.
+function embedSafe(jsonStr) {
+  return jsonStr
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029")
+}
+function substitute(template, payload, args) {
+  const titleSource =
+    args.projectTitle || `${payload.projectSlug}${payload.target ? " · " + payload.target : ""}`
+  const safeTitle = String(titleSource).replace(/[<>&"]/g, (c) => ({
+    "<": "&lt;", ">": "&gt;", "&": "&amp;", "\"": "&quot;",
+  }[c]))
+  const safeJson = embedSafe(JSON.stringify(payload))
+  return template
+    .replace("{{PROJECT_TITLE}}", safeTitle)
+    .replace("{{REPORT_DATA_JSON}}", safeJson)
+}
+async function main() {
+  const args = parseArgs(process.argv)
+  log(`template=${args.template}`)
+  log(`output=${args.output}`)
+  const [template, input] = await Promise.all([
+    readFile(args.template, "utf8").catch((e) => fail(`cannot read template: ${e.message}`)),
+    loadRunData(args),
+  ])
+  const outputAbs = isAbsolute(args.output) ? args.output : resolve(process.cwd(), args.output)
+  const prior = await extractPreviousState(outputAbs)
+  if (prior) log(`merged prior state (1 currentRun + ${(prior.previousRuns || []).length} previousRuns) from existing report`)
+  const payload = buildPayload(input, prior, args)
+  log(`payload: ${payload.currentRun.pageResults.length} pages this run, ${payload.previousRuns.length} previous runs preserved`)
+  const html = substitute(template, payload, args)
+  await writeFile(outputAbs, html, "utf8")
+  log(`wrote ${outputAbs} (${Buffer.byteLength(html, "utf8")} bytes)`)
+  // stdout: structured metadata for orchestrators that pipe us
+  process.stdout.write(JSON.stringify({
+    ok: true,
+    output: outputAbs,
+    bytes: Buffer.byteLength(html, "utf8"),
+    pagesThisRun: payload.currentRun.pageResults.length,
+    previousRunsPreserved: payload.previousRuns.length,
+    generatedAt: payload.generatedAt,
+  }))
+  process.stdout.write("\n")
+}
+main().catch((err) => fail(err && err.stack ? err.stack : String(err)))