similarbuild 0.1.0

package/templates/skills/sb-tweak/scripts/tweak.mjs

@@ -0,0 +1,656 @@
+#!/usr/bin/env node
+// tweak.mjs — sb-tweak CLI. Reads a built HTML/Liquid file, parses a natural-
+// language tweak request, locates the targeted element, applies a single
+// surgical edit, optionally invokes sb-validate-render, and emits a summarized
+// diff as JSON to stdout.
+//
+// Outputs JSON to stdout AND writes tweak.json into --output-dir.
+// Exit codes: 0=ok, 1=script error, 2=invalid args, 3=validation failed,
+//             4=disambiguation needed (low confidence OR multiple candidates).
+
+import { parseArgs } from 'node:util'
+import { mkdir, writeFile, readFile, access } from 'node:fs/promises'
+import { join, resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+
+import { parseIntent } from './lib/intent-parser.mjs'
+import {
+  locateCandidates,
+  isAmbiguous,
+  splitStyleBlocks,
+  findCssRuleAcrossBlocks,
+} from './lib/element-locator.mjs'
+import {
+  summarizeChanges,
+  computeLineFromOffset,
+  diffLines,
+} from './lib/diff-summarizer.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const SKILL_ROOT = resolve(HERE, '..')
+
+const HELP = `
+tweak.mjs — Edit a built HTML/Liquid file from a natural-language request.
+
+Required:
+  --file <path>             HTML or Liquid file to tweak (edited in place by default).
+  --request "<pedido>"      Natural-language request in PT or EN.
+  --output-dir <dir>        Directory for tweak.json (and validation artifacts).
+
+Optional:
+  --target-selector <sel>   Bypass the locator and apply the edit to this exact
+                            CSS selector. Used after a disambiguation round.
+  --output-path <path>      Write the edited file to this path instead of in-place.
+  --no-validate             Skip the post-edit sb-validate-render call.
+  --preset <name>           wp-elementor | shopify-section. Required when --validate.
+  --dry-run                 Show what would change without writing.
+  --help                    Show this message.
+
+Exit codes: 0=ok, 1=script error, 2=invalid args,
+            3=validation failed, 4=disambiguation needed.
+`
+
+function fail(msg, code = 2) {
+  process.stderr.write(`[sb-tweak] ${msg}\n`)
+  process.exit(code)
+}
+function log(msg) {
+  process.stderr.write(`[sb-tweak] ${msg}\n`)
+}
+
+const { values } = parseArgs({
+  options: {
+    file: { type: 'string' },
+    request: { type: 'string' },
+    'target-selector': { type: 'string' },
+    'output-path': { type: 'string' },
+    'output-dir': { type: 'string' },
+    validate: { type: 'boolean', default: true },
+    'no-validate': { type: 'boolean', default: false },
+    preset: { type: 'string' },
+    'dry-run': { type: 'boolean', default: false },
+    help: { type: 'boolean', default: false },
+  },
+  strict: false,
+})
+
+if (values.help) {
+  process.stdout.write(HELP)
+  process.exit(0)
+}
+
+if (!values.file) fail('missing --file')
+if (!values.request) fail('missing --request')
+if (!values['output-dir']) fail('missing --output-dir')
+
+const FILE = resolve(values.file)
+const REQUEST = String(values.request)
+const OUTPUT_DIR = resolve(values['output-dir'])
+const OUTPUT_PATH = values['output-path'] ? resolve(values['output-path']) : FILE
+const TARGET_SELECTOR = values['target-selector'] || null
+const DRY_RUN = !!values['dry-run']
+const SHOULD_VALIDATE = values['no-validate'] ? false : values.validate !== false
+const PRESET = values.preset || null
+
+if (SHOULD_VALIDATE && !PRESET) {
+  fail('--preset is required when validation is enabled (use --no-validate to skip)')
+}
+const VALID_PRESETS = new Set(['wp-elementor', 'shopify-section'])
+if (PRESET && !VALID_PRESETS.has(PRESET)) {
+  fail(`--preset must be one of: ${[...VALID_PRESETS].join(', ')} (got "${PRESET}")`)
+}
+
+async function exists(path) {
+  try {
+    await access(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+// Liquid → HTML-ish so cheerio can parse markup that contains {{ ... }} / {% ... %}.
+function liquidToHtmlish(source) {
+  return source
+    .replace(/\{\{[\s\S]*?\}\}/g, ' ')
+    .replace(/\{%[\s\S]*?%\}/g, ' ')
+}
+
+async function emitDisambiguation(payload, code = 4) {
+  const json = {
+    needsClarification: true,
+    file: FILE,
+    request: REQUEST,
+    ...payload,
+  }
+  await mkdir(OUTPUT_DIR, { recursive: true })
+  await writeFile(join(OUTPUT_DIR, 'tweak.json'), JSON.stringify(json, null, 2), 'utf8')
+  process.stdout.write(JSON.stringify(json))
+  process.stdout.write('\n')
+  process.exit(code)
+}
+
+async function emitOk(payload) {
+  const json = {
+    needsClarification: false,
+    file: FILE,
+    request: REQUEST,
+    ...payload,
+  }
+  await mkdir(OUTPUT_DIR, { recursive: true })
+  await writeFile(join(OUTPUT_DIR, 'tweak.json'), JSON.stringify(json, null, 2), 'utf8')
+  process.stdout.write(JSON.stringify(json))
+  process.stdout.write('\n')
+  process.exit(0)
+}
+
+// ─── Edit application helpers ────────────────────────────────────────────────
+
+function applyCssRuleEdit(source, css, newValue) {
+  // css = { declStart, declEnd, currentValue, ... }; offsets are absolute in
+  // `source` and bracket EXACTLY the value text (no leading space, no
+  // trailing terminator). Splice the new value in.
+  if (!css || css.declStart == null || css.declEnd == null) return null
+  const before = source.slice(0, css.declStart)
+  const after = source.slice(css.declEnd)
+  return before + String(newValue) + after
+}
+
+function readInlineStyleProperty(styleAttr, property) {
+  if (!styleAttr) return null
+  const re = new RegExp(`(?:^|;)\\s*${escapeRegex(property)}\\s*:\\s*([^;]+)`, 'i')
+  const m = re.exec(styleAttr)
+  return m ? m[1].trim() : null
+}
+
+function setInlineStyleProperty(styleAttr, property, newValue) {
+  const cur = String(styleAttr || '')
+  const re = new RegExp(`(^|;)\\s*${escapeRegex(property)}\\s*:\\s*[^;]*`, 'i')
+  if (re.test(cur)) {
+    return cur.replace(re, (_m, sep) => `${sep || ''}${sep ? ' ' : ''}${property}: ${newValue}`)
+  }
+  if (cur.trim().length === 0) return `${property}: ${newValue}`
+  return `${cur.replace(/;\s*$/, '')}; ${property}: ${newValue}`
+}
+
+function escapeRegex(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function formatCssValue(value, property) {
+  if (!value) return ''
+  if (value.kind === 'pixels') return `${value.parsed}px`
+  if (value.kind === 'length') return `${value.parsed.value}${value.parsed.unit}`
+  if (value.kind === 'color') return String(value.parsed)
+  if (value.kind === 'number') {
+    // For numeric values targeting font-weight, leave as-is. For font-size,
+    // assume pixels.
+    if (property === 'font-weight') return String(value.parsed)
+    if (property === 'font-size' || property === 'width' || property === 'height') {
+      return `${value.parsed}px`
+    }
+    return String(value.parsed)
+  }
+  if (value.kind === 'text') return String(value.parsed)
+  if (value.kind === 'url') return String(value.parsed)
+  return String(value.parsed ?? value.raw ?? '')
+}
+
+// ─── Validation invocation (sb-validate-render) ──────────────────────────────
+
+function findValidateRenderScript() {
+  // sb-tweak lives at .claude/skills/sb-tweak/. sb-validate-render lives at
+  // .claude/skills/sb-validate-render/. We resolve sibling-style.
+  const sibling = resolve(SKILL_ROOT, '..', 'sb-validate-render', 'scripts', 'validate-render.mjs')
+  return sibling
+}
+
+async function runValidateRender({ file, preset, outputDir }) {
+  const script = findValidateRenderScript()
+  if (!(await exists(script))) {
+    log(`sb-validate-render not found at ${script} — skipping validation`)
+    return null
+  }
+  const args = [
+    script,
+    '--file', file,
+    '--preset', preset,
+    '--output-dir', outputDir,
+  ]
+  log(`invoking sb-validate-render: node ${args.join(' ')}`)
+  const r = spawnSync('node', args, { encoding: 'utf8' })
+  if (r.error) {
+    log(`validate-render spawn error: ${r.error.message}`)
+    return { passed: false, error: r.error.message, exitCode: 1 }
+  }
+  let parsed = null
+  if (r.stdout) {
+    try {
+      parsed = JSON.parse(r.stdout.trim().split('\n').filter(Boolean).pop())
+    } catch {
+      // ignore — fall through to raw stdout
+    }
+  }
+  return {
+    passed: r.status === 0,
+    exitCode: r.status,
+    stderr: r.stderr,
+    report: parsed,
+    screenshot: parsed?.screenshot || join(outputDir, 'screenshot.png'),
+    warnings: parsed?.warnings || [],
+  }
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  if (!(await exists(FILE))) fail(`--file not found: ${FILE}`, 2)
+  await mkdir(OUTPUT_DIR, { recursive: true })
+
+  // 1. Parse intent
+  const intent = parseIntent(REQUEST)
+  log(`intent: action=${intent.action} target=${JSON.stringify(intent.target)} property=${intent.property} value=${intent.value?.raw} confidence=${intent.confidence} (${intent.language})`)
+
+  if (intent.language === 'unknown') {
+    return emitDisambiguation({
+      reason: 'language-unsupported',
+      hint: 'Only Portuguese (PT) and English (EN) are supported. Please rephrase.',
+      intent,
+    })
+  }
+  if (intent.confidence < 0.7) {
+    return emitDisambiguation({
+      reason: intent.reason || 'low-confidence',
+      hint: 'The request could not be parsed confidently. Specify the action verb, target, and value (e.g. "increase the hero title to 32px").',
+      intent,
+    })
+  }
+
+  // 2. Lazy-load cheerio
+  let cheerio
+  try {
+    cheerio = await import('cheerio')
+  } catch (err) {
+    process.stderr.write(
+      `[sb-tweak] missing dependency 'cheerio': ${err?.message || err}\n` +
+        `Install with: npm i cheerio\n`,
+    )
+    process.exit(1)
+  }
+
+  // 3. Read file
+  log(`reading ${FILE}`)
+  const source = await readFile(FILE, 'utf8')
+  const looksLikeLiquid = /(\{%|\{\{)/.test(source)
+  const htmlForParse = looksLikeLiquid ? liquidToHtmlish(source) : source
+  const $ = cheerio.load(htmlForParse, { decodeEntities: false })
+
+  // Pre-extract style blocks once so the locator and the edit applier share
+  // the same offsets.
+  const styleBlocks = splitStyleBlocks(source)
+
+  // 4. Locate candidates (or use --target-selector if provided)
+  let chosen = null
+  let candidates = []
+
+  if (TARGET_SELECTOR) {
+    const $el = $(TARGET_SELECTOR).first()
+    if ($el.length === 0) {
+      return emitDisambiguation({
+        reason: 'no-candidates',
+        hint: `--target-selector "${TARGET_SELECTOR}" matched no element. Re-check the selector against the file.`,
+        intent,
+      })
+    }
+    chosen = buildCandidateFromElement($, $el, source, intent, styleBlocks)
+  } else {
+    candidates = locateCandidates(intent, $, source)
+    // Inject CSS-block context for the css-rule scope (the locator does this
+    // via cssBlocks if passed; here we re-run rule discovery against the
+    // shared styleBlocks for consistency).
+    candidates = candidates.map((c) => addCssRuleHint(c, styleBlocks, intent))
+    if (candidates.length === 0) {
+      return emitDisambiguation({
+        reason: 'no-candidates',
+        hint: `No element of type "${intent.target.type}" was found in the file.`,
+        intent,
+      })
+    }
+    if (isAmbiguous(candidates)) {
+      return emitDisambiguation({
+        reason: 'multiple-candidates',
+        hint: 're-invoke with --target-selector "<chosen-selector>" using one of the candidates below',
+        intent,
+        candidates: candidates.slice(0, 5).map(slimCandidate),
+      })
+    }
+    chosen = candidates[0]
+  }
+
+  log(`chosen: ${chosen.selector} (applyTo=${chosen.applyTo})`)
+
+  // 5. Compute the edit + apply (or simulate) it.
+  const result = applyEdit({
+    source,
+    $,
+    chosen,
+    intent,
+    cheerioApi: cheerio,
+    styleBlocks,
+  })
+
+  if (!result.changed) {
+    // Idempotent path — already in requested state.
+    return emitOk({
+      intent,
+      selector: chosen.selector,
+      changes: [],
+      diff: 'no changes (already applied)',
+      validation: null,
+      outputPath: OUTPUT_PATH,
+      dryRun: DRY_RUN,
+      candidates: TARGET_SELECTOR ? undefined : candidates.slice(0, 5).map(slimCandidate),
+    })
+  }
+
+  // 6. Persist (unless dry-run).
+  if (!DRY_RUN) {
+    if (OUTPUT_PATH !== FILE) await mkdir(dirname(OUTPUT_PATH), { recursive: true })
+    await writeFile(OUTPUT_PATH, result.nextSource, 'utf8')
+    log(`wrote ${OUTPUT_PATH} (${result.nextSource.length} bytes)`)
+  } else {
+    log(`dry-run: would write ${OUTPUT_PATH} (${result.nextSource.length} bytes)`)
+  }
+
+  // 7. Optionally invoke validate-render.
+  let validation = null
+  if (SHOULD_VALIDATE && !DRY_RUN) {
+    validation = await runValidateRender({
+      file: OUTPUT_PATH,
+      preset: PRESET,
+      outputDir: OUTPUT_DIR,
+    })
+    if (validation && validation.passed === false) {
+      // Revert and escalate.
+      log(`validation failed (exit ${validation.exitCode}) — reverting ${OUTPUT_PATH}`)
+      await writeFile(OUTPUT_PATH, source, 'utf8')
+      const json = {
+        needsClarification: false,
+        file: FILE,
+        request: REQUEST,
+        intent,
+        selector: chosen.selector,
+        changes: result.changes,
+        diff: summarizeChanges(result.changes),
+        validation,
+        reverted: true,
+        outputPath: OUTPUT_PATH,
+        dryRun: false,
+      }
+      await writeFile(join(OUTPUT_DIR, 'tweak.json'), JSON.stringify(json, null, 2), 'utf8')
+      process.stdout.write(JSON.stringify(json))
+      process.stdout.write('\n')
+      process.exit(3)
+    }
+  }
+
+  return emitOk({
+    intent,
+    selector: chosen.selector,
+    changes: result.changes,
+    diff: summarizeChanges(result.changes),
+    validation,
+    outputPath: OUTPUT_PATH,
+    dryRun: DRY_RUN,
+  })
+}
+
+// ─── Edit dispatch ───────────────────────────────────────────────────────────
+
+function applyEdit({ source, $, chosen, intent, cheerioApi, styleBlocks }) {
+  const { applyTo } = chosen
+  const value = intent.value
+  const property = intent.property
+
+  if (applyTo === 'remove-element') {
+    return applyRemoveElement({ source, $, chosen, cheerioApi })
+  }
+  if (applyTo === 'attr') {
+    return applyAttrEdit({ source, $, chosen, intent })
+  }
+  if (applyTo === 'text') {
+    return applyTextEdit({ source, $, chosen, intent })
+  }
+  if (applyTo === 'css-rule') {
+    return applyCssRuleScope({ source, chosen, intent })
+  }
+  if (applyTo === 'inline-style') {
+    return applyInlineStyleEdit({ source, $, chosen, intent })
+  }
+  return { changed: false, changes: [], nextSource: source }
+}
+
+function applyRemoveElement({ source, $, chosen, cheerioApi }) {
+  // We can't precisely splice the original source for cheerio-DOM removal
+  // without round-tripping through cheerio's serialization (which would
+  // reformat the whole file). So we use cheerio's serializer — acceptable
+  // since the user explicitly asked to remove a whole element and minor
+  // formatting normalization is fine.
+  const $el = locateElementByCandidate($, chosen)
+  if (!$el || $el.length === 0) {
+    return { changed: false, changes: [], nextSource: source }
+  }
+  $el.remove()
+  const nextSource = $.html()
+  return {
+    changed: true,
+    changes: [
+      {
+        selector: chosen.selector,
+        property: 'element',
+        before: chosen.snippet,
+        after: null,
+        scope: 'remove-element',
+        line: chosen.line,
+      },
+    ],
+    nextSource,
+  }
+}
+
+function applyAttrEdit({ source, $, chosen, intent }) {
+  const $el = locateElementByCandidate($, chosen)
+  if (!$el || $el.length === 0) return { changed: false, changes: [], nextSource: source }
+  const name = chosen.attrName || intent.property
+  const before = $el.attr(name) ?? null
+  const after = String(intent.value?.parsed ?? '')
+  if (before === after) return { changed: false, changes: [], nextSource: source }
+  $el.attr(name, after)
+  return {
+    changed: true,
+    changes: [
+      {
+        selector: chosen.selector,
+        property: name,
+        before,
+        after,
+        scope: 'attr',
+        line: chosen.line,
+      },
+    ],
+    nextSource: $.html(),
+  }
+}
+
+function applyTextEdit({ source, $, chosen, intent }) {
+  const $el = locateElementByCandidate($, chosen)
+  if (!$el || $el.length === 0) return { changed: false, changes: [], nextSource: source }
+  const before = $el.text()
+  const after = String(intent.value?.parsed ?? '')
+  if (before === after) return { changed: false, changes: [], nextSource: source }
+  $el.text(after)
+  return {
+    changed: true,
+    changes: [
+      {
+        selector: chosen.selector,
+        property: 'text',
+        before,
+        after,
+        scope: 'text',
+        line: chosen.line,
+      },
+    ],
+    nextSource: $.html(),
+  }
+}
+
+function applyCssRuleScope({ source, chosen, intent }) {
+  const css = chosen.css
+  if (!css) return { changed: false, changes: [], nextSource: source }
+  const property = intent.property
+  let nextValue = formatCssValue(intent.value, property)
+
+  // Increase / decrease semantics: when the action is sizing-relative and we
+  // have a number, treat it as the new absolute value. (We don't compute
+  // relative deltas in V1 — the user states the new value explicitly.)
+  if (intent.action === 'increase' || intent.action === 'decrease') {
+    if (!nextValue && intent.value?.kind === 'number') nextValue = `${intent.value.parsed}px`
+  }
+  if (!nextValue) return { changed: false, changes: [], nextSource: source }
+
+  const currentValue = (css.currentValue || '').trim()
+  if (currentValue === nextValue.trim()) {
+    return { changed: false, changes: [], nextSource: source }
+  }
+  const nextSource = applyCssRuleEdit(source, css, nextValue)
+  if (!nextSource) return { changed: false, changes: [], nextSource: source }
+  const line = computeLineFromOffset(source, css.declStart)
+  return {
+    changed: true,
+    changes: [
+      {
+        selector: css.selector || chosen.selector,
+        property,
+        before: currentValue || null,
+        after: nextValue,
+        scope: 'css-rule',
+        line,
+      },
+    ],
+    nextSource,
+  }
+}
+
+function applyInlineStyleEdit({ source, $, chosen, intent }) {
+  const $el = locateElementByCandidate($, chosen)
+  if (!$el || $el.length === 0) return { changed: false, changes: [], nextSource: source }
+  const property = intent.property || chosen.cssProperty
+  if (!property) return { changed: false, changes: [], nextSource: source }
+  const value = formatCssValue(intent.value, property)
+  if (!value) return { changed: false, changes: [], nextSource: source }
+
+  const cur = $el.attr('style') || ''
+  const before = readInlineStyleProperty(cur, property)
+  if (before != null && before === value) {
+    return { changed: false, changes: [], nextSource: source }
+  }
+  const next = setInlineStyleProperty(cur, property, value)
+  $el.attr('style', next)
+  return {
+    changed: true,
+    changes: [
+      {
+        selector: chosen.selector,
+        property,
+        before,
+        after: value,
+        scope: 'inline-style',
+        line: chosen.line,
+      },
+    ],
+    nextSource: $.html(),
+  }
+}
+
+// ─── Utilities ───────────────────────────────────────────────────────────────
+
+function locateElementByCandidate($, chosen) {
+  // Prefer exact selector lookup when the candidate carries one. When the
+  // selector resolves to many elements, fall back to the candidate's stored
+  // index (set by collectDomCandidates).
+  if (chosen.selector) {
+    const all = $(chosen.selector)
+    if (all.length === 1) return all
+    if (chosen.idx != null && all.length > chosen.idx) return $(all[chosen.idx])
+    if (all.length > 0) return all.first()
+  }
+  return chosen.$el || $()
+}
+
+function buildCandidateFromElement($, $el, source, intent, styleBlocks) {
+  const tag = ($el[0]?.tagName || $el[0]?.name || '').toLowerCase()
+  const classes = String($el.attr('class') || '').split(/\s+/).filter(Boolean)
+  const id = $el.attr('id') || null
+  const outerHtml = $.html($el)
+  const snippet = outerHtml.length > 120 ? outerHtml.slice(0, 117) + '...' : outerHtml
+  const selector = id ? `#${id}` : (classes.length ? `${tag}.${classes[0]}` : tag)
+  const line = lineOfHtml(source, outerHtml)
+  const cand = { tag, classes, id, $el, snippet, selector, line, score: 1, idx: 0 }
+  return decideApplyTo(cand, intent, styleBlocks)
+}
+
+function lineOfHtml(source, html) {
+  const head = String(html || '').slice(0, 80)
+  const i = source.indexOf(head)
+  if (i < 0) return 0
+  let line = 1
+  for (let j = 0; j < i; j++) {
+    if (source.charCodeAt(j) === 10) line++
+  }
+  return line
+}
+
+function decideApplyTo(cand, intent, styleBlocks) {
+  const { action, property, value } = intent
+  if (action === 'remove') return { ...cand, applyTo: 'remove-element' }
+  if (property === 'alt' || property === 'src' || property === 'href' || property === 'id' || property === 'class') {
+    return { ...cand, applyTo: 'attr', attrName: property }
+  }
+  if (property === 'text') return { ...cand, applyTo: 'text' }
+  if (property) {
+    const cssMatch = findCssRuleAcrossBlocks(styleBlocks, cand.classes, cand.tag, property)
+    if (cssMatch) return { ...cand, applyTo: 'css-rule', css: cssMatch }
+    return { ...cand, applyTo: 'inline-style', cssProperty: property }
+  }
+  if (value && value.kind === 'text') return { ...cand, applyTo: 'text' }
+  return { ...cand, applyTo: 'inline-style', cssProperty: 'font-size' }
+}
+
+function addCssRuleHint(candidate, styleBlocks, intent) {
+  // For css-rule candidates from the locator, ensure the rule offsets match
+  // our shared styleBlocks (the locator's own scan also uses splitStyleBlocks
+  // but we re-confirm here so a single source of truth is used end-to-end).
+  if (candidate.applyTo !== 'css-rule') return candidate
+  if (!intent.property) return candidate
+  const match = findCssRuleAcrossBlocks(styleBlocks, candidate.classes, candidate.tag, intent.property)
+  if (match) return { ...candidate, css: match }
+  // Rule disappeared between scans (shouldn't happen) → fall back to inline style.
+  return { ...candidate, applyTo: 'inline-style', cssProperty: intent.property, css: undefined }
+}
+
+function slimCandidate(c) {
+  return {
+    selector: c.selector,
+    snippet: c.snippet,
+    score: Number((c.score ?? 0).toFixed(2)),
+    line: c.line ?? 0,
+    applyTo: c.applyTo || null,
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`[sb-tweak] fatal: ${err?.stack || err}\n`)
+  process.exit(1)
+})