@unhead/cli 3.0.5

package/dist/index.mjs

@@ -0,0 +1,1356 @@
+import { defineCommand, runMain } from 'citty';
+import process from 'node:process';
+import { relative, extname, resolve } from 'pathe';
+import { readFile, writeFile } from 'node:fs/promises';
+import MagicString from 'magic-string';
+import { parseSync } from 'oxc-parser';
+import { glob } from 'tinyglobby';
+import { tagPredicates, headInputPredicates, migrationTagPredicates } from 'unhead/validate';
+import { walk } from 'oxc-walker';
+import { parseHtmlForUnheadExtraction } from 'unhead/parser';
+import { ValidatePlugin } from 'unhead/plugins';
+import { createHead, renderSSRHead } from 'unhead/server';
+
+const SEPARATORS = [" | ", " - ", " \u2013 ", " \u2014 ", " \xB7 ", " :: ", " / "];
+const TEMPLATE_PARAM_RE = /%[a-z][a-z0-9]*/i;
+function flatten(results) {
+  const titles = [];
+  const templates = [];
+  for (const r of results) {
+    for (const t of r.titles) titles.push({ ...t, filePath: r.filePath });
+    for (const t of r.titleTemplates) templates.push({ ...t, filePath: r.filePath });
+  }
+  return { titles, templates };
+}
+function detectSeparator(value) {
+  let best;
+  for (const sep of SEPARATORS) {
+    const count = value.split(sep).length - 1;
+    if (count > 0 && (!best || count > best.count))
+      best = { sep, count };
+  }
+  return best?.sep;
+}
+function suffixAfterSeparator(value, sep) {
+  const parts = value.split(sep);
+  return parts[parts.length - 1].trim();
+}
+function analyzeTitleConsistency(results) {
+  const { titles, templates } = flatten(results);
+  if (titles.length < 2)
+    return [];
+  const findings = [];
+  const sepBuckets = /* @__PURE__ */ new Map();
+  for (const t of titles) {
+    const sep = detectSeparator(t.value);
+    if (!sep)
+      continue;
+    const arr = sepBuckets.get(sep) ?? [];
+    arr.push(t);
+    sepBuckets.set(sep, arr);
+  }
+  if (sepBuckets.size > 1) {
+    const breakdown = Array.from(sepBuckets.entries()).sort((a, b) => b[1].length - a[1].length).map(([sep, occ]) => `"${sep.trim()}" (${occ.length})`).join(", ");
+    const occurrences = [];
+    for (const [, occ] of sepBuckets) {
+      for (const o of occ.slice(0, 3))
+        occurrences.push({ filePath: o.filePath, line: o.line, column: o.column, value: o.value });
+    }
+    findings.push({
+      kind: "separator",
+      message: `${sepBuckets.size} different title separators in use across pages: ${breakdown}.`,
+      hint: 'Set `templateParams: { separator: "\xB7" }` and a single `titleTemplate: "%s %separator %siteName"` in `nuxt.config.app.head` so every page renders with the same separator without repeating it.',
+      occurrences
+    });
+  }
+  const trailingCounts = /* @__PURE__ */ new Map();
+  for (const t of titles) {
+    const sep = detectSeparator(t.value);
+    if (!sep)
+      continue;
+    const tail = suffixAfterSeparator(t.value, sep);
+    if (!tail || TEMPLATE_PARAM_RE.test(tail))
+      continue;
+    const arr = trailingCounts.get(tail) ?? [];
+    arr.push(t);
+    trailingCounts.set(tail, arr);
+  }
+  let bestSuffix;
+  for (const [tail, occ] of trailingCounts) {
+    if (occ.length < 3)
+      continue;
+    if (!bestSuffix || occ.length > bestSuffix.occ.length)
+      bestSuffix = { tail, occ };
+  }
+  if (bestSuffix && bestSuffix.occ.length >= Math.max(3, Math.ceil(titles.length * 0.5))) {
+    const templateSet = templates.length > 0;
+    const suffix = bestSuffix.tail;
+    const hint = templateSet ? `\`titleTemplate\` is already set in this project \u2014 these pages duplicate "${suffix}" and will likely render it twice. Drop the suffix from each \`title:\` value.` : `Set \`titleTemplate: "%s %separator %siteName"\` and \`templateParams: { siteName: "${suffix}" }\` in \`nuxt.config.app.head\`, then drop the trailing " \u2026 ${suffix}" from every page \`title\`.`;
+    findings.push({
+      kind: templateSet ? "redundant-suffix" : "common-suffix",
+      message: `${bestSuffix.occ.length} of ${titles.length} page titles end with " \u2026 ${suffix}".`,
+      hint,
+      occurrences: bestSuffix.occ.slice(0, 5).map((o) => ({ filePath: o.filePath, line: o.line, column: o.column, value: o.value }))
+    });
+  }
+  const usingParams = titles.filter((t) => TEMPLATE_PARAM_RE.test(t.value));
+  if (usingParams.length > 0 && usingParams.length < titles.length) {
+    const literal = titles.filter((t) => !TEMPLATE_PARAM_RE.test(t.value));
+    findings.push({
+      kind: "literal-mixed-with-template",
+      message: `${usingParams.length} of ${titles.length} page titles use template params (e.g. %siteName) and ${literal.length} use literal strings.`,
+      hint: "Pick one approach: either move shared parts into `titleTemplate` + `templateParams` and have pages set just their unique segment, or drop template params everywhere. Mixing them makes the rendered output unpredictable.",
+      occurrences: literal.slice(0, 5).map((o) => ({ filePath: o.filePath, line: o.line, column: o.column, value: o.value }))
+    });
+  }
+  return findings;
+}
+
+const RED = "\x1B[31m";
+const YELLOW = "\x1B[33m";
+const GREEN = "\x1B[32m";
+const CYAN = "\x1B[36m";
+const DIM = "\x1B[90m";
+const RESET = "\x1B[0m";
+const BOLD = "\x1B[1m";
+function formatStylish(results, cwd, color) {
+  const titleFindings = analyzeTitleConsistency(results);
+  if (results.length === 0 && titleFindings.length === 0)
+    return "";
+  const c = color ? { red: RED, yellow: YELLOW, green: GREEN, cyan: CYAN, dim: DIM, reset: RESET, bold: BOLD } : { red: "", yellow: "", green: "", cyan: "", dim: "", reset: "", bold: "" };
+  const lines = [];
+  let total = 0;
+  let errors = 0;
+  let warnings = 0;
+  let infos = 0;
+  const sevColor = { error: c.red, warning: c.yellow, info: c.cyan };
+  for (const r of results) {
+    if (r.diagnostics.length === 0)
+      continue;
+    lines.push("");
+    lines.push(`${c.bold}${relative(cwd, r.filePath)}${c.reset}`);
+    const padLineCol = r.diagnostics.reduce((n, d) => Math.max(n, `${d.line}:${d.column}`.length), 0);
+    const padSeverity = r.diagnostics.reduce((n, d) => Math.max(n, d.severity.length), 0);
+    for (const d of r.diagnostics) {
+      total++;
+      if (d.severity === "error")
+        errors++;
+      else if (d.severity === "warning")
+        warnings++;
+      else
+        infos++;
+      const lc = `${d.line}:${d.column}`.padEnd(padLineCol);
+      const sev = d.severity.padEnd(padSeverity);
+      lines.push(`  ${c.dim}${lc}${c.reset}  ${sevColor[d.severity]}${sev}${c.reset}  ${d.message}  ${c.dim}${d.ruleId}${c.reset}`);
+    }
+  }
+  const covered = results.filter((r) => r.diagnostics.length === 0 && r.headCalls.length > 0);
+  if (covered.length > 0) {
+    lines.push("");
+    lines.push(`${c.dim}Scanned ${covered.length} file${covered.length === 1 ? "" : "s"} with head usage and no issues:${c.reset}`);
+    const padPath = covered.reduce((n, r) => Math.max(n, relative(cwd, r.filePath).length), 0);
+    for (const r of covered) {
+      const path = relative(cwd, r.filePath).padEnd(padPath);
+      const counts = summariseCalls(r.headCalls);
+      lines.push(`  ${c.green}\u2713${c.reset} ${path}  ${c.dim}${counts}${c.reset}`);
+    }
+  }
+  if (titleFindings.length > 0) {
+    lines.push("");
+    lines.push(`${c.bold}Title consistency${c.reset}`);
+    for (const f of titleFindings) {
+      lines.push(`  ${c.yellow}\u26A0${c.reset} ${f.message}`);
+      lines.push(`    ${c.dim}\u2192 ${f.hint}${c.reset}`);
+      for (const o of f.occurrences) {
+        const path = relative(cwd, o.filePath);
+        lines.push(`    ${c.dim}${path}:${o.line}${c.reset}  ${truncate(o.value, 80)}`);
+      }
+    }
+  }
+  if (total === 0 && covered.length === 0 && titleFindings.length === 0)
+    return "";
+  if (total > 0) {
+    lines.push("");
+    const parts = [`${errors} error${errors === 1 ? "" : "s"}`, `${warnings} warning${warnings === 1 ? "" : "s"}`];
+    if (infos > 0)
+      parts.push(`${infos} info`);
+    const summary = `${total} problem${total === 1 ? "" : "s"} (${parts.join(", ")})`;
+    const summaryColor = errors > 0 ? c.red : warnings > 0 ? c.yellow : c.cyan;
+    const glyph = errors > 0 || warnings > 0 ? "\u2716" : "\u2139";
+    lines.push(`${summaryColor}${c.bold}${glyph} ${summary}${c.reset}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function truncate(s, n) {
+  return s.length <= n ? s : `${s.slice(0, n - 1)}\u2026`;
+}
+function summariseCalls(calls) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const call of calls)
+    counts.set(call.name, (counts.get(call.name) ?? 0) + 1);
+  return Array.from(counts.entries()).sort(([a], [b]) => a.localeCompare(b)).map(([name, n]) => n === 1 ? name : `${name} \xD7${n}`).join(", ");
+}
+
+const TS_WRAPPERS$2 = /* @__PURE__ */ new Set(["TSAsExpression", "TSSatisfiesExpression", "TSNonNullExpression", "TSTypeAssertion", "TSInstantiationExpression"]);
+function unwrapTS$2(node) {
+  let cur = node;
+  while (cur && TS_WRAPPERS$2.has(cur.type))
+    cur = cur.expression;
+  return cur;
+}
+function getStringValue(node) {
+  const inner = unwrapTS$2(node);
+  if (!inner)
+    return void 0;
+  if (inner.type === "Literal" && typeof inner.value === "string")
+    return inner.value;
+  if (inner.type === "TemplateLiteral" && inner.expressions.length === 0 && inner.quasis.length === 1)
+    return inner.quasis[0].value.cooked ?? void 0;
+  return void 0;
+}
+function getKeyName$2(prop) {
+  if (prop.type !== "Property" || prop.computed)
+    return void 0;
+  const k = prop.key;
+  if (k.type === "Identifier")
+    return k.name;
+  if (k.type === "Literal" && typeof k.value === "string")
+    return k.value;
+  return void 0;
+}
+function findProperty(obj, key) {
+  for (let i = obj.properties.length - 1; i >= 0; i--) {
+    const prop = obj.properties[i];
+    if (getKeyName$2(prop) === key)
+      return prop;
+  }
+  return void 0;
+}
+function materializeTag(obj, tagType, inArray) {
+  const props = {};
+  const keys = /* @__PURE__ */ new Set();
+  const propLocs = {};
+  for (const p of obj.properties) {
+    const name = getKeyName$2(p);
+    if (!name)
+      continue;
+    keys.add(name);
+    propLocs[name] = { start: p.start, end: p.end };
+    const value = unwrapTS$2(p.value);
+    if (!value)
+      continue;
+    if (value.type === "Literal") {
+      const v = value.value;
+      if (typeof v === "string" || typeof v === "number" || typeof v === "boolean")
+        props[name] = v;
+      continue;
+    }
+    const str = getStringValue(value);
+    if (str !== void 0)
+      props[name] = str;
+  }
+  return {
+    tagType,
+    props,
+    keys,
+    loc: { start: obj.start, end: obj.end },
+    propLocs,
+    inArray
+  };
+}
+function materializeHeadInput(obj, callee) {
+  const props = {};
+  const keys = /* @__PURE__ */ new Set();
+  const propLocs = {};
+  for (const p of obj.properties) {
+    const name = getKeyName$2(p);
+    if (!name)
+      continue;
+    keys.add(name);
+    propLocs[name] = { start: p.start, end: p.end };
+    if (name === "title" || name === "titleTemplate") {
+      const str = getStringValue(p.value);
+      if (str !== void 0)
+        props[name] = str;
+    }
+  }
+  return { callee, props, keys, loc: { start: obj.start, end: obj.end }, propLocs };
+}
+
+function applyFix(magic, obj, fix, pieceOffset, pieceCode) {
+  const off = pieceOffset;
+  switch (fix.type) {
+    case "rename-prop": {
+      const prop = findProperty(obj, fix.key);
+      if (!prop)
+        return false;
+      magic.overwrite(prop.key.start + off, prop.key.end + off, fix.newKey);
+      return true;
+    }
+    case "replace-prop-value": {
+      const prop = findProperty(obj, fix.key);
+      if (!prop)
+        return false;
+      magic.overwrite(prop.value.start + off, prop.value.end + off, fix.newSource);
+      return true;
+    }
+    case "replace-prop": {
+      const prop = findProperty(obj, fix.key);
+      if (!prop)
+        return false;
+      magic.overwrite(prop.start + off, prop.end + off, fix.newSource);
+      return true;
+    }
+    case "insert-after-prop": {
+      const prop = findProperty(obj, fix.afterKey);
+      if (!prop)
+        return false;
+      magic.appendRight(prop.end + off, fix.insert);
+      return true;
+    }
+    case "remove-prop": {
+      const prop = findProperty(obj, fix.key);
+      if (!prop)
+        return false;
+      let from = prop.start;
+      let to = prop.end;
+      let f = to;
+      while (f < pieceCode.length && /\s/.test(pieceCode[f])) f++;
+      if (pieceCode[f] === ",") {
+        to = f + 1;
+      } else {
+        let b = from - 1;
+        while (b >= 0 && /\s/.test(pieceCode[b])) b--;
+        if (pieceCode[b] === ",")
+          from = b;
+      }
+      magic.remove(from + off, to + off);
+      return true;
+    }
+    case "wrap-tag": {
+      magic.appendLeft(obj.start + off, `${fix.wrapWith}(`);
+      magic.appendRight(obj.end + off, `)`);
+      return true;
+    }
+  }
+}
+
+const TS_WRAPPERS$1 = /* @__PURE__ */ new Set([
+  "TSAsExpression",
+  "TSSatisfiesExpression",
+  "TSNonNullExpression",
+  "TSTypeAssertion",
+  "TSInstantiationExpression"
+]);
+function unwrapTS$1(node) {
+  let cur = node;
+  while (cur && TS_WRAPPERS$1.has(cur.type))
+    cur = cur.expression;
+  return cur;
+}
+function getKeyName$1(prop) {
+  if (prop.type !== "Property" || prop.computed)
+    return void 0;
+  const k = prop.key;
+  if (k.type === "Identifier")
+    return k.name;
+  if (k.type === "Literal" && typeof k.value === "string")
+    return k.value;
+  return void 0;
+}
+function metaTagToFlatKey(value) {
+  const parts = value.split(/[:\-_]/).filter(Boolean);
+  if (parts.length === 0)
+    return void 0;
+  const head = parts[0].toLowerCase();
+  const tail = parts.slice(1).map((p) => p[0].toUpperCase() + p.slice(1).toLowerCase()).join("");
+  return head + tail;
+}
+const PASSTHROUGH_KEYS = /* @__PURE__ */ new Set(["title", "titleTemplate"]);
+const META_ATTR_KEYS = /* @__PURE__ */ new Set(["name", "property", "http-equiv", "httpEquiv"]);
+function analyzeUseHeadForUseSeoMeta(inputNode, pieceCode) {
+  if (inputNode.type !== "ObjectExpression")
+    return void 0;
+  const props = [];
+  const seenFlatKeys = /* @__PURE__ */ new Set();
+  let metaCount = 0;
+  for (const prop of inputNode.properties) {
+    if (prop.type !== "Property" || prop.computed || prop.shorthand)
+      return void 0;
+    const key = getKeyName$1(prop);
+    if (!key)
+      return void 0;
+    if (PASSTHROUGH_KEYS.has(key)) {
+      const valueSource = pieceCode.slice(prop.value.start, prop.value.end);
+      if (seenFlatKeys.has(key))
+        return void 0;
+      seenFlatKeys.add(key);
+      props.push({ key, valueSource });
+      continue;
+    }
+    if (key !== "meta")
+      return void 0;
+    const metaArr = unwrapTS$1(prop.value);
+    if (metaArr?.type !== "ArrayExpression")
+      return void 0;
+    for (const el of metaArr.elements) {
+      const obj = unwrapTS$1(el);
+      if (obj?.type !== "ObjectExpression")
+        return void 0;
+      let flatKey;
+      let contentSource;
+      let charsetSource;
+      for (const mp of obj.properties) {
+        if (mp.type !== "Property" || mp.computed || mp.shorthand)
+          return void 0;
+        const k = getKeyName$1(mp);
+        if (!k)
+          return void 0;
+        if (k === "charset") {
+          flatKey = "charset";
+          charsetSource = pieceCode.slice(mp.value.start, mp.value.end);
+          continue;
+        }
+        if (META_ATTR_KEYS.has(k)) {
+          const v = unwrapTS$1(mp.value);
+          if (v?.type !== "Literal" || typeof v.value !== "string")
+            return void 0;
+          const candidate = metaTagToFlatKey(v.value);
+          if (!candidate)
+            return void 0;
+          if (flatKey && flatKey !== candidate)
+            return void 0;
+          flatKey = candidate;
+          continue;
+        }
+        if (k === "content") {
+          contentSource = pieceCode.slice(mp.value.start, mp.value.end);
+          continue;
+        }
+        return void 0;
+      }
+      if (!flatKey)
+        return void 0;
+      const valueSource = charsetSource ?? contentSource;
+      if (!valueSource)
+        return void 0;
+      if (seenFlatKeys.has(flatKey))
+        return void 0;
+      seenFlatKeys.add(flatKey);
+      props.push({ key: flatKey, valueSource });
+      metaCount++;
+    }
+  }
+  if (metaCount === 0)
+    return void 0;
+  return { props };
+}
+function renderUseSeoMetaArg(conversion, originalSource) {
+  const indent = detectIndent(originalSource);
+  const lines = conversion.props.map((p) => `${indent}${p.key}: ${p.valueSource},`);
+  return `{
+${lines.join("\n")}
+}`;
+}
+function detectIndent(source) {
+  const m = source.match(/\n([ \t]+)\S/);
+  return m ? m[1] : "  ";
+}
+
+const SCRIPT_OPEN_RE = /<script\b((?:"[^"]*"|'[^']*'|[^>"'])*)>/gi;
+const SCRIPT_CLOSE_RE = /<\/script\s*>/gi;
+const LANG_ATTR_RE = /\blang\s*=\s*(?:"([^"]+)"|'([^']+)'|([^\s"'>]+))/i;
+function extractScriptBlocks(source) {
+  const out = [];
+  SCRIPT_OPEN_RE.lastIndex = 0;
+  for (let m = SCRIPT_OPEN_RE.exec(source); m; m = SCRIPT_OPEN_RE.exec(source)) {
+    const attrs = m[1];
+    const openEnd = m.index + m[0].length;
+    SCRIPT_CLOSE_RE.lastIndex = openEnd;
+    const closeMatch = SCRIPT_CLOSE_RE.exec(source);
+    if (!closeMatch)
+      continue;
+    const code = source.slice(openEnd, closeMatch.index);
+    const langMatch = attrs.match(LANG_ATTR_RE);
+    const declared = (langMatch?.[1] ?? langMatch?.[2] ?? langMatch?.[3])?.toLowerCase();
+    const lang = declared === "ts" ? "ts" : declared === "tsx" ? "tsx" : declared === "jsx" ? "jsx" : "js";
+    out.push({ code, offset: openEnd, lang });
+    SCRIPT_OPEN_RE.lastIndex = closeMatch.index + closeMatch[0].length;
+  }
+  return out;
+}
+function langForExt(ext) {
+  switch (ext) {
+    case ".ts":
+    case ".mts":
+    case ".cts":
+      return "ts";
+    case ".tsx":
+      return "tsx";
+    case ".jsx":
+      return "jsx";
+    case ".js":
+    case ".mjs":
+    case ".cjs":
+      return "js";
+    default:
+      return void 0;
+  }
+}
+
+const HEAD_INPUT_CALLEES = /* @__PURE__ */ new Set([
+  "useHead",
+  "useHeadSafe",
+  "useServerHead",
+  "useServerHeadSafe",
+  "useSeoMeta",
+  "useServerSeoMeta"
+]);
+const NUXT_CONFIG_CALLEES = /* @__PURE__ */ new Set([
+  "defineNuxtConfig"
+]);
+const TAG_HELPER_CALLEES = /* @__PURE__ */ new Set([
+  "defineLink",
+  "defineScript"
+]);
+const HEAD_INPUT_TAG_KEYS = /* @__PURE__ */ new Set([
+  "meta",
+  "link",
+  "script",
+  "noscript",
+  "style"
+]);
+const TS_WRAPPERS = /* @__PURE__ */ new Set(["TSAsExpression", "TSSatisfiesExpression", "TSNonNullExpression", "TSTypeAssertion", "TSInstantiationExpression"]);
+function unwrapTS(node) {
+  let cur = node;
+  while (cur && TS_WRAPPERS.has(cur.type))
+    cur = cur.expression;
+  return cur;
+}
+function getCalleeName(node) {
+  const callee = unwrapTS(node.callee);
+  if (!callee)
+    return void 0;
+  if (callee.type === "Identifier")
+    return callee.name;
+  if (callee.type === "MemberExpression" && callee.property.type === "Identifier")
+    return callee.property.name;
+  return void 0;
+}
+function getKeyName(prop) {
+  if (prop.type !== "Property" || prop.computed)
+    return void 0;
+  const k = prop.key;
+  if (k.type === "Identifier")
+    return k.name;
+  if (k.type === "Literal" && typeof k.value === "string")
+    return k.value;
+  return void 0;
+}
+const HELPER_NAMES = /* @__PURE__ */ new Set(["defineLink", "defineScript"]);
+const HELPER_SOURCES = /* @__PURE__ */ new Set([
+  "unhead",
+  "@unhead/vue",
+  "@unhead/react",
+  "@unhead/svelte",
+  "@unhead/solid-js",
+  "@unhead/angular"
+]);
+function isHelperSource(source) {
+  if (HELPER_SOURCES.has(source))
+    return true;
+  return source.startsWith("@unhead/");
+}
+function collectImportedHelpers(program) {
+  const out = /* @__PURE__ */ new Map();
+  for (const node of program.body) {
+    if (node.type !== "ImportDeclaration")
+      continue;
+    const source = typeof node.source?.value === "string" ? node.source.value : "";
+    if (!isHelperSource(source))
+      continue;
+    for (const spec of node.specifiers) {
+      if (spec.type === "ImportSpecifier" && spec.imported.type === "Identifier" && HELPER_NAMES.has(spec.imported.name))
+        out.set(spec.imported.name, spec.local?.name ?? spec.imported.name);
+    }
+  }
+  return out;
+}
+function collectCallees(root) {
+  const calls = /* @__PURE__ */ new Set();
+  walk(root, {
+    enter(n) {
+      if (n.type === "CallExpression") {
+        const name = getCalleeName(n);
+        if (name)
+          calls.add(name);
+      }
+    }
+  });
+  return calls;
+}
+function visitDecl(decl, fns) {
+  if (decl.type === "FunctionDeclaration" && decl.id?.name) {
+    fns.set(decl.id.name, collectCallees(decl.body));
+    return;
+  }
+  if (decl.type === "VariableDeclaration") {
+    for (const d of decl.declarations) {
+      if (d.id?.type !== "Identifier" || !d.init)
+        continue;
+      const init = unwrapTS(d.init);
+      if (init && (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression"))
+        fns.set(d.id.name, collectCallees(init.body));
+    }
+  }
+}
+function extractCallGraph(program) {
+  const functions = /* @__PURE__ */ new Map();
+  for (const stmt of program.body) {
+    if (stmt.type === "ExportNamedDeclaration" && stmt.declaration) {
+      visitDecl(stmt.declaration, functions);
+    } else if (stmt.type === "ExportDefaultDeclaration") {
+      const d = stmt.declaration;
+      if (d?.type === "FunctionDeclaration" && d.id?.name)
+        functions.set(d.id.name, collectCallees(d.body));
+    } else {
+      visitDecl(stmt, functions);
+    }
+  }
+  return { functions, allCalls: collectCallees(program) };
+}
+const TITLE_PROP_KEY = "title";
+const TITLE_TEMPLATE_PROP_KEY = "titleTemplate";
+function readStringLiteral(value) {
+  const v = unwrapTS(value);
+  if (!v)
+    return void 0;
+  if (v.type === "Literal" && typeof v.value === "string")
+    return { value: v.value, dynamic: false };
+  if (v.type === "TemplateLiteral") {
+    let out = "";
+    for (let i = 0; i < v.quasis.length; i++) {
+      out += v.quasis[i].value.cooked ?? v.quasis[i].value.raw ?? "";
+      if (i < v.expressions.length)
+        out += "{\u2026}";
+    }
+    return { value: out, dynamic: v.expressions.length > 0 };
+  }
+  return void 0;
+}
+function extractCandidateTitles(program) {
+  const titles = [];
+  const templates = [];
+  walk(program, {
+    enter(node) {
+      if (node.type !== "CallExpression")
+        return;
+      const callee = getCalleeName(node);
+      if (!callee)
+        return;
+      const arg = unwrapTS(node.arguments[0]);
+      if (arg?.type !== "ObjectExpression")
+        return;
+      for (const prop of arg.properties) {
+        const key = getKeyName(prop);
+        if (key !== TITLE_PROP_KEY && key !== TITLE_TEMPLATE_PROP_KEY)
+          continue;
+        const lit = readStringLiteral(prop.value);
+        if (!lit)
+          continue;
+        const entry = { callee, value: lit.value, dynamic: lit.dynamic, start: prop.start };
+        if (key === TITLE_PROP_KEY)
+          titles.push(entry);
+        else
+          templates.push(entry);
+      }
+    }
+  });
+  return { titles, templates };
+}
+function walkHeadCalls(program, visitor) {
+  walk(program, {
+    enter(node) {
+      if (node.type !== "CallExpression")
+        return;
+      const name = getCalleeName(node);
+      if (!name)
+        return;
+      if (TAG_HELPER_CALLEES.has(name)) {
+        visitor.onCall?.(node, name);
+        const arg2 = unwrapTS(node.arguments[0]);
+        if (arg2?.type === "ObjectExpression") {
+          const tagType = name.slice("define".length).toLowerCase();
+          visitor.onTag?.(arg2, tagType, { inArray: false });
+        }
+        return;
+      }
+      if (NUXT_CONFIG_CALLEES.has(name)) {
+        const arg2 = unwrapTS(node.arguments[0]);
+        if (arg2?.type !== "ObjectExpression")
+          return;
+        const head = findNuxtAppHead(arg2);
+        if (!head)
+          return;
+        visitor.onCall?.(node, name);
+        visitor.onHeadInput?.(head, name, node);
+        descendHeadInput(head, name, visitor);
+        return;
+      }
+      if (!HEAD_INPUT_CALLEES.has(name))
+        return;
+      visitor.onCall?.(node, name);
+      const arg = unwrapTS(node.arguments[0]);
+      if (arg?.type !== "ObjectExpression")
+        return;
+      visitor.onHeadInput?.(arg, name, node);
+      descendHeadInput(arg, name, visitor);
+    }
+  });
+}
+function descendHeadInput(arg, name, visitor) {
+  if (name === "useSeoMeta" || name === "useServerSeoMeta")
+    return;
+  for (const prop of arg.properties) {
+    const key = getKeyName(prop);
+    if (!key || !HEAD_INPUT_TAG_KEYS.has(key))
+      continue;
+    const value = unwrapTS(prop.value);
+    if (value?.type === "ArrayExpression") {
+      for (const el of value.elements) {
+        const inner = unwrapTS(el);
+        if (inner?.type === "ObjectExpression")
+          visitor.onTag?.(inner, key, { inArray: true });
+      }
+    } else if (value?.type === "ObjectExpression") {
+      visitor.onTag?.(value, key, { inArray: false });
+    }
+  }
+}
+function findNuxtAppHead(config) {
+  for (const prop of config.properties) {
+    if (getKeyName(prop) !== "app")
+      continue;
+    const app = unwrapTS(prop.value);
+    if (app?.type !== "ObjectExpression")
+      return void 0;
+    for (const inner of app.properties) {
+      if (getKeyName(inner) !== "head")
+        continue;
+      const head = unwrapTS(inner.value);
+      if (head?.type === "ObjectExpression")
+        return head;
+      return void 0;
+    }
+  }
+  return void 0;
+}
+
+const RECOMMENDED_SEVERITY = {
+  "defer-on-module-script": "warning",
+  "empty-meta-content": "warning",
+  "deprecated-prop-children": "error",
+  "deprecated-prop-hid-vmid": "error",
+  "deprecated-prop-body": "error",
+  "html-in-title": "warning",
+  "possible-typo": "warning",
+  "non-absolute-canonical": "warning",
+  "numeric-tag-priority": "warning",
+  "preload-font-crossorigin": "error",
+  "preload-missing-as": "error",
+  "robots-conflict": "error",
+  "script-src-with-content": "error",
+  "twitter-handle-missing-at": "warning",
+  "viewport-user-scalable": "warning",
+  "prefer-define-helpers": "warning",
+  "prefer-use-seo-meta": "warning",
+  "parse-error": "warning",
+  "page-missing-head": "info"
+};
+function lineCol(source, offset) {
+  let line = 1;
+  let lastNL = -1;
+  for (let i = 0; i < offset; i++) {
+    if (source.charCodeAt(i) === 10) {
+      line++;
+      lastNL = i;
+    }
+  }
+  return { line, column: offset - lastNL };
+}
+function anchorOffset(node, diag) {
+  if (!diag.at || diag.at.kind === "tag")
+    return node.start;
+  for (let i = node.properties.length - 1; i >= 0; i--) {
+    const p = node.properties[i];
+    const k = p.key;
+    const name = k?.type === "Identifier" ? k.name : k?.type === "Literal" && typeof k.value === "string" ? k.value : void 0;
+    if (name !== diag.at.key)
+      continue;
+    if (diag.at.kind === "prop")
+      return p.start;
+    if (diag.at.kind === "prop-key")
+      return p.key.start;
+    return p.value.start;
+  }
+  return node.start;
+}
+async function auditFile(filePath, source, pieces, predicateNames, shouldFix) {
+  const diagnostics = [];
+  const headCalls = [];
+  const titles = [];
+  const titleTemplates = [];
+  const candidateTitles = [];
+  const candidateTemplates = [];
+  const callGraph = { functions: /* @__PURE__ */ new Map(), allCalls: /* @__PURE__ */ new Set() };
+  const magic = shouldFix ? new MagicString(source) : void 0;
+  let edited = false;
+  for (const piece of pieces) {
+    let emit = function(diag, node) {
+      const absOffset = piece.offset + anchorOffset(node, diag);
+      const { line, column } = lineCol(source, absOffset);
+      diagnostics.push({
+        ruleId: diag.ruleId,
+        message: diag.message,
+        line,
+        column,
+        severity: RECOMMENDED_SEVERITY[diag.ruleId] ?? "warning"
+      });
+      if (shouldFix && magic && diag.fix) {
+        if (applyFix(magic, node, diag.fix, piece.offset, piece.code))
+          edited = true;
+      }
+    };
+    let parsed;
+    try {
+      parsed = parseSync(filePath, piece.code, { sourceType: "module", lang: piece.lang });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      diagnostics.push({
+        ruleId: "parse-error",
+        message: `skipped ${piece.lang} block: ${message}`,
+        line: lineCol(source, piece.offset).line,
+        column: 1,
+        severity: "warning"
+      });
+      continue;
+    }
+    if (parsed.errors.length > 0) {
+      const first = parsed.errors[0];
+      diagnostics.push({
+        ruleId: "parse-error",
+        message: `skipped ${piece.lang} block: ${first.message ?? "parse error"}`,
+        line: lineCol(source, piece.offset).line,
+        column: 1,
+        severity: "warning"
+      });
+      continue;
+    }
+    const program = parsed.program;
+    let importedHelpers;
+    const pieceGraph = extractCallGraph(program);
+    for (const c of pieceGraph.allCalls) callGraph.allCalls.add(c);
+    for (const [n, calls] of pieceGraph.functions) {
+      const existing = callGraph.functions.get(n);
+      if (existing) {
+        for (const c of calls) existing.add(c);
+      } else {
+        callGraph.functions.set(n, new Set(calls));
+      }
+    }
+    const cands = extractCandidateTitles(program);
+    for (const t of cands.titles) {
+      const { line, column } = lineCol(source, piece.offset + t.start);
+      candidateTitles.push({ value: t.value, line, column, callee: t.callee, dynamic: t.dynamic });
+    }
+    for (const t of cands.templates) {
+      const { line, column } = lineCol(source, piece.offset + t.start);
+      candidateTemplates.push({ value: t.value, line, column, callee: t.callee, dynamic: t.dynamic });
+    }
+    walkHeadCalls(program, {
+      onCall(call, callee) {
+        const { line, column } = lineCol(source, piece.offset + call.start);
+        headCalls.push({ name: callee, line, column });
+      },
+      onHeadInput(input, callee, call) {
+        if (callee === "useHead") {
+          const conversion = analyzeUseHeadForUseSeoMeta(input, piece.code);
+          if (conversion) {
+            const { line, column } = lineCol(source, piece.offset + call.start);
+            diagnostics.push({
+              ruleId: "prefer-use-seo-meta",
+              message: 'This useHead call is meta-only. Switch to useSeoMeta \u2014 meta name/property values are typed as plain strings here, so a typo (e.g. "descriptipon") compiles and silently ships broken meta. useSeoMeta keys are typed and catch typos at write time.',
+              line,
+              column,
+              severity: "warning"
+            });
+            if (shouldFix && magic) {
+              const calleeNode = call.callee;
+              const calleeStart = calleeNode?.type === "Identifier" ? calleeNode.start : call.start;
+              const calleeEnd = calleeNode?.type === "Identifier" ? calleeNode.end : call.start;
+              if (calleeNode?.type === "Identifier") {
+                magic.overwrite(piece.offset + calleeStart, piece.offset + calleeEnd, "useSeoMeta");
+              }
+              const originalSource = piece.code.slice(input.start, input.end);
+              const newArg = renderUseSeoMetaArg(conversion, originalSource);
+              magic.overwrite(piece.offset + input.start, piece.offset + input.end, newArg);
+              edited = true;
+            }
+          }
+        }
+        const view = materializeHeadInput(input, callee);
+        if (view.props.title !== void 0) {
+          const titleProp = input.properties.find((p) => {
+            const k = p.key;
+            return k?.type === "Identifier" && k.name === "title" || k?.type === "Literal" && k.value === "title";
+          });
+          if (titleProp) {
+            const { line, column } = lineCol(source, piece.offset + titleProp.start);
+            titles.push({ value: view.props.title, line, column, callee });
+          }
+        }
+        if (view.props.titleTemplate !== void 0) {
+          const tplProp = input.properties.find((p) => {
+            const k = p.key;
+            return k?.type === "Identifier" && k.name === "titleTemplate" || k?.type === "Literal" && k.value === "titleTemplate";
+          });
+          if (tplProp) {
+            const { line, column } = lineCol(source, piece.offset + tplProp.start);
+            titleTemplates.push({ value: view.props.titleTemplate, line, column, callee });
+          }
+        }
+        for (const name of predicateNames) {
+          const pred = headInputPredicates[name];
+          if (!pred)
+            continue;
+          for (const diag of pred(view))
+            emit(diag, input);
+        }
+      },
+      onTag(tag, tagType, info) {
+        const view = materializeTag(tag, tagType, info.inArray);
+        const ctx = {
+          get importedHelpers() {
+            if (!importedHelpers)
+              importedHelpers = collectImportedHelpers(program);
+            return importedHelpers;
+          }
+        };
+        for (const name of predicateNames) {
+          const pred = tagPredicates[name] ?? migrationTagPredicates[name];
+          if (!pred)
+            continue;
+          for (const diag of pred(view, ctx))
+            emit(diag, tag);
+        }
+      }
+    });
+  }
+  return {
+    diagnostics,
+    headCalls,
+    titles,
+    titleTemplates,
+    candidateTitles,
+    candidateTemplates,
+    callGraph,
+    output: edited && magic ? magic.toString() : void 0
+  };
+}
+const PAGE_PATH_RE = /[\\/]pages[\\/].+\.vue$/;
+function isPagePath(filePath) {
+  return PAGE_PATH_RE.test(filePath);
+}
+function computeHeadProvidingCallees(graphs) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const g of graphs) {
+    for (const [name, calls] of g.functions) {
+      const existing = merged.get(name);
+      if (existing) {
+        for (const c of calls) existing.add(c);
+      } else {
+        merged.set(name, new Set(calls));
+      }
+    }
+  }
+  const set = new Set(HEAD_INPUT_CALLEES);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const [name, calls] of merged) {
+      if (set.has(name))
+        continue;
+      for (const c of calls) {
+        if (set.has(c)) {
+          set.add(name);
+          changed = true;
+          break;
+        }
+      }
+    }
+  }
+  return set;
+}
+async function runAudit(opts) {
+  const files = await glob(opts.patterns, {
+    cwd: opts.cwd,
+    absolute: true,
+    ignore: opts.ignore
+  });
+  const shouldFix = opts.mode === "migrate";
+  const predicateNames = opts.mode === "migrate" ? [...Object.keys(tagPredicates), ...Object.keys(headInputPredicates), ...Object.keys(migrationTagPredicates)] : [...Object.keys(tagPredicates), ...Object.keys(headInputPredicates)];
+  const results = [];
+  const allGraphs = [];
+  const pageFiles = [];
+  const pendingCandidates = [];
+  for (const filePath of files) {
+    const source = await readFile(filePath, "utf8");
+    const ext = extname(filePath).toLowerCase();
+    const lang = langForExt(ext);
+    const pieces = lang ? [{ code: source, offset: 0, lang }] : ext === ".vue" || ext === ".svelte" ? extractScriptBlocks(source).map((b) => ({ code: b.code, offset: b.offset, lang: b.lang })) : [];
+    if (pieces.length === 0)
+      continue;
+    const result = await auditFile(filePath, source, pieces, predicateNames, shouldFix);
+    allGraphs.push(result.callGraph);
+    const isPage = isPagePath(filePath);
+    const hasInterestingResult = result.diagnostics.length > 0 || !!result.output || result.headCalls.length > 0;
+    const hasTitles = result.titles.length > 0 || result.titleTemplates.length > 0;
+    let resultIdx = -1;
+    if (hasInterestingResult || hasTitles) {
+      resultIdx = results.length;
+      results.push({
+        filePath,
+        diagnostics: result.diagnostics,
+        headCalls: result.headCalls,
+        titles: result.titles,
+        titleTemplates: result.titleTemplates,
+        output: result.output
+      });
+    }
+    if (isPage && result.headCalls.length === 0) {
+      pageFiles.push({ filePath, callGraph: result.callGraph, headCalls: result.headCalls, existingResultIdx: resultIdx });
+    }
+    if (result.candidateTitles.length > 0 || result.candidateTemplates.length > 0) {
+      pendingCandidates.push({ filePath, candidateTitles: result.candidateTitles, candidateTemplates: result.candidateTemplates, existingResultIdx: resultIdx });
+    }
+  }
+  const headProviding = computeHeadProvidingCallees(allGraphs);
+  for (const c of pendingCandidates) {
+    const extraTitles = [];
+    const extraTemplates = [];
+    for (const t of c.candidateTitles) {
+      if (HEAD_INPUT_CALLEES.has(t.callee))
+        continue;
+      if (!headProviding.has(t.callee))
+        continue;
+      extraTitles.push({ value: t.value, line: t.line, column: t.column, callee: t.callee });
+    }
+    for (const t of c.candidateTemplates) {
+      if (HEAD_INPUT_CALLEES.has(t.callee))
+        continue;
+      if (!headProviding.has(t.callee))
+        continue;
+      extraTemplates.push({ value: t.value, line: t.line, column: t.column, callee: t.callee });
+    }
+    if (extraTitles.length === 0 && extraTemplates.length === 0)
+      continue;
+    if (c.existingResultIdx >= 0) {
+      results[c.existingResultIdx].titles.push(...extraTitles);
+      results[c.existingResultIdx].titleTemplates.push(...extraTemplates);
+    } else {
+      results.push({ filePath: c.filePath, diagnostics: [], headCalls: [], titles: extraTitles, titleTemplates: extraTemplates });
+    }
+  }
+  if (pageFiles.length > 0) {
+    for (const page of pageFiles) {
+      let provides = false;
+      for (const c of page.callGraph.allCalls) {
+        if (headProviding.has(c)) {
+          provides = true;
+          break;
+        }
+      }
+      if (provides)
+        continue;
+      const diag = {
+        ruleId: "page-missing-head",
+        message: "Page does not call useHead/useSeoMeta directly or via a composable. Pages should set page-specific head metadata for SEO.",
+        line: 1,
+        column: 1,
+        severity: "info"
+      };
+      if (page.existingResultIdx >= 0) {
+        results[page.existingResultIdx].diagnostics.push(diag);
+      } else {
+        results.push({ filePath: page.filePath, diagnostics: [diag], headCalls: [], titles: [], titleTemplates: [] });
+      }
+    }
+  }
+  return results;
+}
+function summarise(results) {
+  let errorCount = 0;
+  let warningCount = 0;
+  let infoCount = 0;
+  for (const r of results) {
+    for (const d of r.diagnostics) {
+      if (d.severity === "error")
+        errorCount++;
+      else if (d.severity === "warning")
+        warningCount++;
+      else
+        infoCount++;
+    }
+  }
+  return { errorCount, warningCount, infoCount, fileCount: results.length };
+}
+
+const DEFAULT_PATTERNS$2 = ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx,vue,svelte}"];
+const DEFAULT_IGNORE$2 = ["**/node_modules/**", "**/dist/**", "**/.output/**", "**/.nuxt/**"];
+const audit = defineCommand({
+  meta: {
+    name: "audit",
+    description: "Lint your codebase for unhead misuse, type-narrowing issues, and SEO/perf foot-guns."
+  },
+  args: {
+    cwd: {
+      type: "string",
+      description: "Project root.",
+      default: "."
+    }
+  },
+  async run({ args }) {
+    const cwd = resolve(process.cwd(), args.cwd);
+    const positional = (args._ ?? []).map(String).filter(Boolean);
+    const patterns = positional.length > 0 ? positional : DEFAULT_PATTERNS$2;
+    const results = await runAudit({ patterns, mode: "audit", cwd, ignore: DEFAULT_IGNORE$2 });
+    const { errorCount, warningCount } = summarise(results);
+    const output = formatStylish(results, cwd, process.stdout.isTTY ?? false);
+    if (output)
+      process.stdout.write(output);
+    if (errorCount > 0)
+      process.exitCode = 1;
+    else if (warningCount > 0 && !output)
+      console.log(`unhead audit: ${warningCount} warning${warningCount === 1 ? "" : "s"}`);
+  }
+});
+
+const DEFAULT_PATTERNS$1 = ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx,vue,svelte}"];
+const DEFAULT_IGNORE$1 = ["**/node_modules/**", "**/dist/**", "**/.output/**", "**/.nuxt/**"];
+const migrate = defineCommand({
+  meta: {
+    name: "migrate",
+    description: "Apply autofixes for v2-to-v3 migration: rewrite deprecated props and wrap tag literals in defineX helpers."
+  },
+  args: {
+    "cwd": {
+      type: "string",
+      description: "Project root.",
+      default: "."
+    },
+    "dry-run": {
+      type: "boolean",
+      description: "Report what would change without writing files.",
+      default: false
+    }
+  },
+  async run({ args }) {
+    const cwd = resolve(process.cwd(), args.cwd);
+    const positional = (args._ ?? []).map(String).filter(Boolean);
+    const patterns = positional.length > 0 ? positional : DEFAULT_PATTERNS$1;
+    const dryRun = args["dry-run"] === true;
+    const results = await runAudit({
+      patterns,
+      mode: "migrate",
+      cwd,
+      ignore: DEFAULT_IGNORE$1
+    });
+    const output = formatStylish(results, cwd, process.stdout.isTTY ?? false);
+    if (output)
+      process.stdout.write(output);
+    if (dryRun) {
+      const fixable = results.reduce((n, r) => n + (r.output ? 1 : 0), 0);
+      console.log(`unhead migrate: ${fixable} file${fixable === 1 ? "" : "s"} would be modified (dry run)`);
+      return;
+    }
+    let written = 0;
+    for (const r of results) {
+      if (!r.output)
+        continue;
+      await writeFile(r.filePath, r.output);
+      written++;
+    }
+    console.log(`unhead migrate: applied fixes to ${written} file${written === 1 ? "" : "s"}`);
+    const { errorCount } = summarise(results);
+    if (errorCount > 0)
+      process.exitCode = 1;
+  }
+});
+
+function validateHtml(html, source) {
+  const { input } = parseHtmlForUnheadExtraction(html);
+  const captured = [];
+  const head = createHead({
+    plugins: [ValidatePlugin({ onReport: (rs) => captured.push(...rs) })]
+  });
+  head.push(input);
+  renderSSRHead(head);
+  return { source, rules: captured };
+}
+function severitySymbol(severity) {
+  return severity === "warn" ? "\u26A0" : "\u2139";
+}
+function printReport({ source, rules }) {
+  if (rules.length === 0) {
+    console.log(`${source} \u2014 no issues found`);
+    return;
+  }
+  console.log(`
+${source}`);
+  for (const rule of rules)
+    console.log(`  ${severitySymbol(rule.severity)} ${rule.id}: ${rule.message}`);
+  const warnings = rules.filter((r) => r.severity === "warn").length;
+  const info = rules.filter((r) => r.severity === "info").length;
+  console.log(`
+  ${rules.length} issue${rules.length === 1 ? "" : "s"} (${warnings} warning${warnings === 1 ? "" : "s"}, ${info} info)`);
+}
+function jsonReplacer(key, value) {
+  return key === "tag" ? void 0 : value;
+}
+
+const DEFAULT_PATTERNS = ["**/*.html"];
+const DEFAULT_IGNORE = ["**/node_modules/**"];
+const validateHtmlCommand = defineCommand({
+  meta: {
+    name: "validate-html",
+    description: "Run the runtime ValidatePlugin over prerendered HTML files (e.g. dist/, .output/, build/)."
+  },
+  args: {
+    cwd: {
+      type: "string",
+      description: "Project root.",
+      default: "."
+    },
+    json: {
+      type: "boolean",
+      description: "Emit JSON instead of human-readable output.",
+      default: false
+    }
+  },
+  async run({ args }) {
+    const cwd = resolve(process.cwd(), String(args.cwd));
+    const positional = (args._ ?? []).map(String).filter(Boolean);
+    const patterns = positional.length > 0 ? positional : DEFAULT_PATTERNS;
+    const files = await glob(patterns, {
+      cwd,
+      absolute: true,
+      ignore: DEFAULT_IGNORE
+    });
+    if (files.length === 0) {
+      console.error(`No HTML files matched ${patterns.join(", ")} in ${cwd}`);
+      process.exitCode = 1;
+      return;
+    }
+    const reports = [];
+    for (const file of files) {
+      const html = await readFile(file, "utf8");
+      reports.push(validateHtml(html, file));
+    }
+    if (args.json) {
+      process.stdout.write(`${JSON.stringify(reports, jsonReplacer, 2)}
+`);
+    } else {
+      for (const report of reports)
+        printReport(report);
+      const totalIssues = reports.reduce((n, r) => n + r.rules.length, 0);
+      const filesWithIssues = reports.filter((r) => r.rules.length > 0).length;
+      console.log(`
+${filesWithIssues}/${files.length} file${files.length === 1 ? "" : "s"} with issues, ${totalIssues} total`);
+    }
+    if (reports.some((r) => r.rules.some((rule) => rule.severity === "warn")))
+      process.exitCode = 1;
+  }
+});
+
+async function fetchHtml(url, userAgent, timeoutMs = 3e4) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      headers: {
+        "user-agent": userAgent,
+        "accept": "text/html,application/xhtml+xml"
+      },
+      redirect: "follow",
+      signal: controller.signal
+    });
+    if (!res.ok)
+      throw new Error(`HTTP ${res.status} ${res.statusText} for ${url}`);
+    const ct = res.headers.get("content-type") || "";
+    if (ct && !/text\/html|application\/xhtml\+xml/i.test(ct))
+      throw new Error(`Unexpected content-type "${ct}" for ${url} (expected HTML)`);
+    return await res.text();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+const validateUrlCommand = defineCommand({
+  meta: {
+    name: "validate-url",
+    description: "Fetch a rendered URL and run unhead's SEO/perf validation rules over its <head>."
+  },
+  args: {
+    "url": {
+      type: "positional",
+      description: "URL to fetch and validate.",
+      required: true
+    },
+    "user-agent": {
+      type: "string",
+      description: "User-Agent header to send (default: facebookexternalhit so social-crawler-aware rules engage).",
+      default: "facebookexternalhit/1.1 (+https://unhead.unjs.io)"
+    },
+    "timeout": {
+      type: "string",
+      description: "Fetch timeout in milliseconds.",
+      default: "30000"
+    },
+    "json": {
+      type: "boolean",
+      description: "Emit JSON instead of human-readable output.",
+      default: false
+    }
+  },
+  async run({ args }) {
+    const url = String(args.url);
+    const timeoutMs = Number(args.timeout) || 3e4;
+    const html = await fetchHtml(url, String(args["user-agent"]), timeoutMs);
+    const result = validateHtml(html, url);
+    if (args.json)
+      process.stdout.write(`${JSON.stringify(result, jsonReplacer, 2)}
+`);
+    else
+      printReport(result);
+    if (result.rules.some((r) => r.severity === "warn"))
+      process.exitCode = 1;
+  }
+});
+
+const main = defineCommand({
+  meta: {
+    name: "unhead",
+    description: "Audit, migrate, and validate unhead head usage."
+  },
+  subCommands: {
+    "audit": audit,
+    "migrate": migrate,
+    "validate-html": validateHtmlCommand,
+    "validate-url": validateUrlCommand
+  }
+});
+function run() {
+  return runMain(main);
+}
+
+export { audit, migrate, run, validateHtmlCommand, validateUrlCommand };