create-claude-cabinet 0.29.5 → 0.29.8

package/lib/site-audit-setup.js

@@ -91,6 +91,21 @@ function extractAndInstall(versionDir, tarballPath, results) {
   execSync(`tar xf "${tarballPath}" -C "${versionDir}"`, { encoding: 'utf8' });
   execSync('npm install --omit=dev --ignore-scripts --silent', { cwd: pkgDir, encoding: 'utf8' });
 
+  // Pa11y needs Puppeteer's Chrome; axe-core needs chromedriver.
+  // Both were skipped by --ignore-scripts. Install them now.
+  try {
+    execSync('npx puppeteer browsers install chrome', { cwd: pkgDir, encoding: 'utf8', timeout: 120_000 });
+    results.push('  Installed Puppeteer Chrome for Pa11y');
+  } catch {
+    results.push('  ⚠ Puppeteer Chrome install failed — Pa11y will be unavailable');
+  }
+  try {
+    execSync('node node_modules/chromedriver/install.js', { cwd: pkgDir, encoding: 'utf8', timeout: 120_000 });
+    results.push('  Installed chromedriver for axe-core');
+  } catch {
+    results.push('  ⚠ chromedriver install failed — axe-core will be unavailable');
+  }
+
   const binDir = path.join(versionDir, 'bin');
   fs.mkdirSync(binDir, { recursive: true });
   const binSrc = path.join(pkgDir, 'bin', 'cc-site-audit');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-cabinet",
-  "version": "0.29.5",
+  "version": "0.29.8",
   "description": "Claude Cabinet — opinionated process scaffolding for Claude Code projects",
   "bin": {
     "create-claude-cabinet": "bin/create-claude-cabinet.js"

package/templates/site-audit-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-cabinet/site-audit",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "description": "Comprehensive deployed-site quality audit engine for Claude Cabinet. Runs checks across performance, accessibility, security, SEO, content, DNS, and privacy against a deployed URL; single-site and comparison modes; standalone HTML report.",
   "type": "module",
   "bin": {
@@ -22,6 +22,7 @@
     "lighthouse": "^12.0.0",
     "linkinator": "^7.0.0",
     "pa11y": "^9.0.0",
+    "ssl-checker": "^3.0.0",
     "unlighthouse": "^0.16.0"
   }
 }

package/templates/site-audit-runtime/src/checks/axe-core.mjs

@@ -1,13 +1,14 @@
 export const checkId = 'axe-core';
 export const tool = 'axe-core (WCAG AA)';
+export const whyItMatters = "Checks whether people with disabilities can use your site — screen readers, keyboard navigation, color contrast. Legal liability if not met.";
 
 export async function detect(executor) {
-  const r = await executor.spawn('npx', ['@axe-core/cli', '--version'], { timeoutMs: 15_000 });
+  const r = await executor.spawn('axe', ['--version'], { timeoutMs: 15_000 });
   return r.code === 0;
 }
 
 export async function run(url, executor) {
-  return executor.spawn('npx', ['@axe-core/cli', url, '--exit'], { timeoutMs: 60_000 });
+  return executor.spawn('axe', [url, '--exit'], { timeoutMs: 60_000 });
 }
 
 const IMPACT_TO_SEVERITY = { critical: 'critical', serious: 'serious', moderate: 'moderate', minor: 'info' };

package/templates/site-audit-runtime/src/checks/dns.mjs

@@ -1,5 +1,6 @@
 export const checkId = 'dns';
 export const tool = 'DNS & Protocol';
+export const whyItMatters = "DNS security prevents attackers from redirecting your visitors to fake versions of your site. HTTP/2 makes pages load faster.";
 
 export async function detect(executor) {
   const r = await executor.spawn('dig', ['-v'], { timeoutMs: 5_000 });

package/templates/site-audit-runtime/src/checks/lighthouse.mjs

@@ -1,15 +1,16 @@
 export const checkId = 'lighthouse';
 export const tool = 'Lighthouse';
+export const whyItMatters = "Google's own audit tool — scores four dimensions separately: Performance (page speed), Accessibility (usability for all), Best Practices (security and code quality), and SEO (search visibility). The overall score averages all four.";
 export const defaultTimeoutMs = 120_000;
 
 export async function detect(executor) {
-  const r = await executor.spawn('npx', ['lighthouse', '--version'], { timeoutMs: 15_000 });
+  const r = await executor.spawn('lighthouse', ['--version'], { timeoutMs: 15_000 });
   return r.code === 0;
 }
 
 export async function run(url, executor) {
-  const r = await executor.spawn('npx', [
-    'lighthouse', url,
+  const r = await executor.spawn('lighthouse', [
+    url,
     '--output=json',
     '--chrome-flags=--headless=new --no-sandbox',
     '--only-categories=performance,accessibility,best-practices,seo',

package/templates/site-audit-runtime/src/checks/linkinator.mjs

@@ -1,13 +1,14 @@
 export const checkId = 'linkinator';
 export const tool = 'Linkinator (broken links)';
+export const whyItMatters = "Broken links frustrate visitors and tell search engines your site isn't maintained — hurts both trust and rankings.";
 
 export async function detect(executor) {
-  const r = await executor.spawn('npx', ['linkinator', '--version'], { timeoutMs: 15_000 });
+  const r = await executor.spawn('linkinator', ['--version'], { timeoutMs: 15_000 });
   return r.code === 0;
 }
 
 export async function run(url, executor) {
-  return executor.spawn('npx', ['linkinator', url, '--format', 'json', '--timeout', '10000'], { timeoutMs: 60_000 });
+  return executor.spawn('linkinator', [url, '--format', 'json', '--timeout', '10000'], { timeoutMs: 60_000 });
 }
 
 export function normalize(raw, durationMs) {

package/templates/site-audit-runtime/src/checks/meta-og.mjs

@@ -1,5 +1,6 @@
 export const checkId = 'meta-og';
 export const tool = 'Meta & Open Graph';
+export const whyItMatters = "Controls how your site appears when shared on social media and in search results — missing tags mean ugly or blank previews.";
 
 export async function detect() { return true; }
 

package/templates/site-audit-runtime/src/checks/nuclei.mjs

@@ -6,6 +6,7 @@
 
 export const checkId = 'nuclei';
 export const tool = 'Nuclei (CVE scan)';
+export const whyItMatters = "Scans for known security vulnerabilities (CVEs) that attackers actively exploit — the kind that make the news.";
 export const defaultTimeoutMs = 300_000;
 
 export async function detect(executor) {

package/templates/site-audit-runtime/src/checks/observatory.mjs

@@ -1,14 +1,15 @@
 export const checkId = 'observatory';
 export const tool = 'MDN HTTP Observatory';
+export const whyItMatters = "Mozilla's security scorecard — grades your site's defenses against common web attacks like clickjacking and data injection.";
 
 export async function detect(executor) {
-  const r = await executor.spawn('npx', ['@mdn/mdn-http-observatory', '--version'], { timeoutMs: 15_000 });
+  const r = await executor.spawn('mdn-http-observatory-scan', ['--help'], { timeoutMs: 15_000 });
   return r.code === 0;
 }
 
 export async function run(url, executor) {
   const hostname = new URL(url).hostname;
-  return executor.spawn('npx', ['@mdn/mdn-http-observatory', hostname], { timeoutMs: 60_000 });
+  return executor.spawn('mdn-http-observatory-scan', [hostname], { timeoutMs: 60_000 });
 }
 
 const GRADE_SCORES = { 'A+': 100, 'A': 95, 'A-': 90, 'B+': 85, 'B': 80, 'B-': 75, 'C+': 70, 'C': 65, 'C-': 60, 'D+': 55, 'D': 50, 'D-': 45, 'F': 20 };

package/templates/site-audit-runtime/src/checks/pa11y.mjs

@@ -1,13 +1,14 @@
 export const checkId = 'pa11y';
 export const tool = 'Pa11y (WCAG AAA)';
+export const whyItMatters = "Stricter accessibility testing (WCAG AAA) — catches issues that basic checks miss, like low contrast text and missing form labels.";
 
 export async function detect(executor) {
-  const r = await executor.spawn('npx', ['pa11y', '--version'], { timeoutMs: 15_000 });
+  const r = await executor.spawn('pa11y', ['--version'], { timeoutMs: 15_000 });
   return r.code === 0;
 }
 
 export async function run(url, executor) {
-  return executor.spawn('npx', ['pa11y', url, '--reporter', 'json', '--standard', 'WCAG2AAA'], { timeoutMs: 60_000 });
+  return executor.spawn('pa11y', [url, '--reporter', 'json', '--standard', 'WCAG2AAA'], { timeoutMs: 60_000 });
 }
 
 const TYPE_TO_SEVERITY = { error: 'serious', warning: 'moderate', notice: 'info' };

package/templates/site-audit-runtime/src/checks/security-headers.mjs

@@ -1,13 +1,14 @@
 export const checkId = 'security-headers';
 export const tool = 'Security Headers';
+export const whyItMatters = "Missing headers let attackers inject malicious scripts, steal user data, or impersonate your site in browsers.";
 
 const CHECKS = [
-  { header: 'content-security-policy', label: 'Content-Security-Policy', weight: 2 },
-  { header: 'strict-transport-security', label: 'Strict-Transport-Security', weight: 2 },
-  { header: 'x-frame-options', label: 'X-Frame-Options', weight: 1 },
-  { header: 'x-content-type-options', label: 'X-Content-Type-Options', weight: 1 },
-  { header: 'referrer-policy', label: 'Referrer-Policy', weight: 1 },
-  { header: 'permissions-policy', label: 'Permissions-Policy', weight: 1 },
+  { header: 'content-security-policy', label: 'Content-Security-Policy', weight: 2, why: 'Controls which scripts/resources can load — primary defense against XSS attacks' },
+  { header: 'strict-transport-security', label: 'Strict-Transport-Security', weight: 2, why: 'Forces HTTPS — prevents downgrade attacks that intercept unencrypted traffic' },
+  { header: 'x-frame-options', label: 'X-Frame-Options', weight: 1, why: 'Prevents your site from being embedded in iframes — blocks clickjacking attacks' },
+  { header: 'x-content-type-options', label: 'X-Content-Type-Options', weight: 1, why: 'Stops browsers from guessing file types — prevents script injection via disguised files' },
+  { header: 'referrer-policy', label: 'Referrer-Policy', weight: 1, why: 'Controls what URL info leaks when users click links to other sites' },
+  { header: 'permissions-policy', label: 'Permissions-Policy', weight: 1, why: 'Restricts which browser features (camera, mic, geolocation) the page can use' },
 ];
 
 export async function detect() { return true; }
@@ -29,7 +30,7 @@ export function normalize(headers, durationMs) {
     if (headers[c.header]) {
       earned += c.weight;
     } else {
-      findings.push({ severity: c.weight >= 2 ? 'serious' : 'moderate', message: `Missing ${c.label} header` });
+      findings.push({ severity: c.weight >= 2 ? 'serious' : 'moderate', message: `Missing ${c.label} header`, context: c.why });
     }
   }
 

package/templates/site-audit-runtime/src/checks/ssl-cert.mjs

@@ -1,5 +1,6 @@
 export const checkId = 'ssl-cert';
 export const tool = 'SSL Certificate';
+export const whyItMatters = "An expired or misconfigured certificate shows scary browser warnings that immediately drive visitors away.";
 
 export async function detect(executor) {
   const r = await executor.spawn('openssl', ['version'], { timeoutMs: 5_000 });

package/templates/site-audit-runtime/src/checks/structured-data.mjs

@@ -1,5 +1,6 @@
 export const checkId = 'structured-data';
 export const tool = 'Structured Data (JSON-LD)';
+export const whyItMatters = "Tells Google exactly what your business does — enables rich search results like star ratings, FAQ dropdowns, and business info panels.";
 
 export async function detect() { return true; }
 
@@ -70,9 +71,12 @@ export function normalize(html, durationMs) {
     ? `${scripts.length} JSON-LD block${scripts.length !== 1 ? 's' : ''} found with ${types.length} type${types.length !== 1 ? 's' : ''}: ${types.join(', ') || 'none'}`
     : undefined;
 
+  const details = types.length ? { types, blockCount: scripts.length } : undefined;
+
   return {
     checkId, tool, status: isPass ? 'pass' : 'fail',
     score, grade: null, severity: worstSev, findings, durationMs,
     ...(passSummary && { passSummary }),
+    ...(details && { details }),
   };
 }

package/templates/site-audit-runtime/src/checks/testssl.mjs

@@ -1,70 +1,75 @@
 export const checkId = 'testssl';
-export const tool = 'testssl.sh (TLS depth)';
-export const defaultTimeoutMs = 180_000;
+export const tool = 'TLS/SSL Check';
+export const whyItMatters = "Weak encryption lets attackers intercept data between your users and your server — passwords, form submissions, everything.";
 
 export async function detect(executor) {
-  const r = await executor.spawn('testssl.sh', ['--version'], { timeoutMs: 5_000 });
-  return r.code === 0 || r.stdout.includes('testssl');
+  try {
+    await import('ssl-checker');
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 export async function run(url, executor) {
   const hostname = new URL(url).hostname;
-  return executor.spawn('testssl.sh', ['--jsonfile-pretty', '/dev/stdout', '--quiet', hostname], { timeoutMs: 180_000 });
+  const sslChecker = (await import('ssl-checker')).default;
+  const result = await sslChecker(hostname);
+  return { code: 0, stdout: JSON.stringify(result), stderr: '', timedOut: false };
 }
 
 export function normalize(raw, durationMs) {
   if (raw.code !== 0 && !raw.stdout) {
-    return { checkId, tool, status: 'error', score: null, grade: null, severity: null, findings: [], durationMs, reason: raw.stderr || 'testssl.sh failed' };
+    return { checkId, tool, status: 'error', score: null, grade: null, severity: null, findings: [], durationMs, reason: raw.stderr || 'ssl-checker failed' };
   }
 
-  let entries;
-  try { entries = JSON.parse(raw.stdout); } catch {
-    const lines = raw.stdout.split('\n').filter(l => l.trim());
-    entries = lines.map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  let data;
+  try { data = JSON.parse(raw.stdout); } catch {
+    return { checkId, tool, status: 'error', score: null, grade: null, severity: null, findings: [], durationMs, reason: 'failed to parse ssl-checker output' };
   }
-  if (!Array.isArray(entries)) entries = [entries];
 
   const findings = [];
-  for (const e of entries.flat()) {
-    if (!e || !e.severity) continue;
-    const sev = mapSeverity(e.severity);
-    if (sev && e.severity !== 'OK' && e.severity !== 'INFO') {
-      findings.push({
-        severity: sev,
-        message: e.finding || e.id || 'unknown',
-        context: e.cve || undefined,
-      });
-    }
+
+  if (!data.valid) {
+    findings.push({ severity: 'critical', message: 'Certificate is not valid' });
+  }
+
+  if (data.daysRemaining != null && data.daysRemaining < 30) {
+    findings.push({
+      severity: data.daysRemaining < 7 ? 'critical' : 'serious',
+      message: `Certificate expires in ${data.daysRemaining} days`,
+    });
+  }
+
+  const protocol = data.protocol || data.tlsVersion || '';
+  if (protocol && !protocol.includes('TLSv1.2') && !protocol.includes('TLSv1.3')) {
+    findings.push({ severity: 'serious', message: `Weak TLS protocol: ${protocol}` });
   }
 
-  const worstSev = findings.length ? findings.reduce((w, f) => {
-    const o = { critical: 0, serious: 1, moderate: 2, info: 3 };
-    return (o[f.severity] ?? 3) < (o[w] ?? 3) ? f.severity : w;
-  }, 'info') : null;
+  if (data.cipher) {
+    const weak = /RC4|DES|MD5|NULL|EXPORT|anon/i;
+    if (weak.test(data.cipher)) {
+      findings.push({ severity: 'serious', message: `Weak cipher: ${data.cipher}` });
+    }
+  }
 
   const hasCritical = findings.some(f => f.severity === 'critical');
   const hasSerious = findings.some(f => f.severity === 'serious');
-
   const isPass = !hasCritical && !hasSerious;
-  const totalChecked = entries.flat().filter(e => e && e.severity).length;
-  const passSummary = isPass
-    ? (findings.length === 0
-      ? `TLS configuration clean — ${totalChecked} check${totalChecked !== 1 ? 's' : ''} passed`
-      : `No critical/serious TLS issues (${findings.length} low-severity item${findings.length !== 1 ? 's' : ''})`)
-    : undefined;
+
+  const details = [];
+  if (data.valid) details.push('valid certificate');
+  if (data.daysRemaining != null) details.push(`${data.daysRemaining} days until expiry`);
+  if (protocol) details.push(protocol);
+  if (data.cipher) details.push(data.cipher);
+
+  const passSummary = isPass ? details.join(', ') : undefined;
 
   return {
     checkId, tool, status: isPass ? 'pass' : 'fail',
-    score: null, grade: null, severity: worstSev, findings, durationMs,
+    score: null, grade: null,
+    severity: hasCritical ? 'critical' : hasSerious ? 'serious' : findings.length ? 'moderate' : null,
+    findings, durationMs,
     ...(passSummary && { passSummary }),
   };
 }
-
-function mapSeverity(s) {
-  const l = String(s).toUpperCase();
-  if (l === 'CRITICAL' || l === 'HIGH') return 'critical';
-  if (l === 'MEDIUM' || l === 'WARN' || l === 'WARNING') return 'serious';
-  if (l === 'LOW' || l === 'NOT OK') return 'moderate';
-  if (l === 'INFO' || l === 'OK') return 'info';
-  return 'info';
-}

package/templates/site-audit-runtime/src/checks/unlighthouse.mjs

@@ -4,16 +4,17 @@
 
 export const checkId = 'unlighthouse';
 export const tool = 'Unlighthouse (full-site crawl)';
-export const defaultTimeoutMs = 300_000;
+export const whyItMatters = "Runs Lighthouse on every page of your site, not just the homepage — catches performance and accessibility problems hiding on inner pages.";
+export const defaultTimeoutMs = 600_000;
 
 export async function detect(executor) {
-  const r = await executor.spawn('npx', ['unlighthouse', '--version'], { timeoutMs: 15_000 });
+  const r = await executor.spawn('unlighthouse', ['--version'], { timeoutMs: 15_000 });
   return r.code === 0;
 }
 
 export async function run(url, executor) {
-  return executor.spawn('npx', [
-    'unlighthouse', '--site', url, '--ci', '--reporter', 'json',
+  return executor.spawn('unlighthouse', [
+    '--site', url, '--ci', '--reporter', 'json',
   ], { timeoutMs: 300_000 });
 }
 

package/templates/site-audit-runtime/src/checks/website-carbon.mjs

@@ -4,6 +4,7 @@
 
 export const checkId = 'website-carbon';
 export const tool = 'Website Carbon';
+export const whyItMatters = "Estimates your site's carbon footprint per visit — smaller pages are faster, cheaper to host, and better for the environment.";
 
 const KWH_PER_GB = 0.81;
 const CARBON_FACTOR_GRAMS_PER_KWH = 442;

package/templates/site-audit-runtime/src/orchestrator.mjs

@@ -54,8 +54,7 @@ const DEFAULT_TIMEOUTS = {
   lighthouse: 120_000,
   testssl: 180_000,
   nuclei: 300_000,
-  unlighthouse: 300_000,
-  blacklight: 120_000,
+  unlighthouse: 600_000,
 };
 const FALLBACK_TIMEOUT = 60_000;
 const MAX_CONCURRENCY = 4;
@@ -114,7 +113,6 @@ function guessCheckId(cmd, args) {
   if (allTokens.includes('nuclei')) return 'nuclei';
   if (allTokens.includes('unlighthouse')) return 'unlighthouse';
   if (allTokens.includes('observatory')) return 'observatory';
-  if (allTokens.includes('blacklight')) return 'blacklight';
   if (allTokens.includes('dig')) return 'dns';
   if (allTokens.includes('openssl')) return 'ssl-cert';
   return basename(cmd).replace(/\.\w+$/, '');
@@ -180,13 +178,16 @@ export async function auditSite(url, checks, opts = {}) {
 
     const start = Date.now();
     let available;
+    let detectError = '';
     try {
       available = await check.detect(executor);
-    } catch {
+    } catch (err) {
       available = false;
+      detectError = err instanceof Error ? err.message : String(err);
     }
 
     if (!available) {
+      const hint = detectError ? ` (${detectError})` : ' (binary not found in PATH)';
       return {
         checkId: check.checkId,
         tool: check.tool,
@@ -196,7 +197,7 @@ export async function auditSite(url, checks, opts = {}) {
         severity: null,
         findings: [],
         durationMs: Date.now() - start,
-        reason: `${check.tool} not available`,
+        reason: `${check.tool} not available${hint}`,
       };
     }
 
@@ -239,6 +240,7 @@ export async function auditSite(url, checks, opts = {}) {
           reason: `normalize produced invalid CheckResult: ${errors.join('; ')}`,
         };
       }
+      if (check.whyItMatters) result.whyItMatters = check.whyItMatters;
       return result;
     } catch (err) {
       return {

package/templates/site-audit-runtime/src/report.mjs

@@ -120,6 +120,25 @@ function renderFindings(findings, result) {
   return html;
 }
 
+function renderDetails(result) {
+  if (!result?.details) return '';
+  let html = '';
+  const cats = result.details.categories;
+  if (cats && typeof cats === 'object' && !Array.isArray(cats)) {
+    const items = Object.entries(cats).map(([k, v]) => {
+      const label = k.replace(/-/g, ' ');
+      const cls = v >= 90 ? 'score-pass' : v >= 50 ? '' : 'score-fail';
+      return `<span class="${cls}" style="display:inline-block;margin-right:1rem"><strong>${esc(label)}</strong> ${v}/100</span>`;
+    });
+    html += `<div style="margin-bottom:.75rem;font-size:.9rem">${items.join('')}</div>`;
+  }
+  const types = result.details.types;
+  if (Array.isArray(types) && types.length) {
+    html += `<div style="margin-bottom:.75rem;font-size:.85rem;color:#555">Schema types: ${types.map(t => `<strong>${esc(String(t))}</strong>`).join(', ')}</div>`;
+  }
+  return html;
+}
+
 /**
  * Generate a 2-3 sentence executive summary for a comparison report.
  * @param {import('./diff.mjs').DeltaReport} delta
@@ -137,10 +156,12 @@ export function generateSummary(delta) {
   const biggest = sorted[0];
 
   let summary = '';
+  const sA = hostnameLabel(delta.urlA);
+  const sB = hostnameLabel(delta.urlB);
   if (bWins > aWins) {
-    summary += `Site B outperforms Site A on ${bWins} of ${scored.length} scored dimension${scored.length > 1 ? 's' : ''}`;
+    summary += `${esc(sB)} outperforms ${esc(sA)} on ${bWins} of ${scored.length} scored dimension${scored.length > 1 ? 's' : ''}`;
   } else if (aWins > bWins) {
-    summary += `Site A outperforms Site B on ${aWins} of ${scored.length} scored dimension${scored.length > 1 ? 's' : ''}`;
+    summary += `${esc(sA)} outperforms ${esc(sB)} on ${aWins} of ${scored.length} scored dimension${scored.length > 1 ? 's' : ''}`;
   } else {
     summary += `Sites are evenly matched across ${scored.length} scored dimension${scored.length > 1 ? 's' : ''}`;
   }
@@ -169,6 +190,8 @@ function checkSection(result) {
     </div>
   </div>
   <div class="check-body">
+    ${result.whyItMatters ? `<p style="color:#666;font-size:.85rem;font-style:italic;margin-bottom:.5rem">${esc(result.whyItMatters)}</p>` : ''}
+    ${renderDetails(result)}
     ${renderFindings(result.findings, result)}
   </div>
 </div>`;
@@ -236,7 +259,13 @@ function classifyFindings(a, b) {
  * @param {import('./diff.mjs').DeltaReport} delta
  * @returns {string}
  */
+function hostnameLabel(url) {
+  try { return new URL(url).hostname; } catch { return url; }
+}
+
 export function renderComparison(delta) {
+  const labelA = hostnameLabel(delta.urlA);
+  const labelB = hostnameLabel(delta.urlB);
   const title = `Site Comparison — ${delta.urlA} vs ${delta.urlB}`;
 
   let html = head(title);
@@ -248,14 +277,14 @@ export function renderComparison(delta) {
   const { aOnly, bOnly } = delta.summary;
   if (aOnly > 0 || bOnly > 0) {
     html += `<div class="asymmetric-warning">Asymmetric availability: `;
-    if (aOnly > 0) html += `${aOnly} check${aOnly > 1 ? 's' : ''} ran only for Site A. `;
-    if (bOnly > 0) html += `${bOnly} check${bOnly > 1 ? 's' : ''} ran only for Site B. `;
+    if (aOnly > 0) html += `${aOnly} check${aOnly > 1 ? 's' : ''} ran only for ${esc(labelA)}. `;
+    if (bOnly > 0) html += `${bOnly} check${bOnly > 1 ? 's' : ''} ran only for ${esc(labelB)}. `;
     html += `Deltas for one-sided checks show N/A.</div>`;
   }
 
   // ── Comparison grid with drill-down links ──
   html += '<div style="background:#fff;border-radius:10px;box-shadow:0 1px 4px rgba(0,0,0,.05);overflow:hidden;margin-bottom:2rem">';
-  html += `<div class="compare-row"><span>Check</span><span>Site A</span><span>Site B</span><span>Delta</span></div>`;
+  html += `<div class="compare-row"><span>Check</span><span>${esc(labelA)}</span><span>${esc(labelB)}</span><span>Delta</span></div>`;
 
   for (const d of delta.deltas) {
     const aDisplay = d.a && d.a.status !== 'skip'
@@ -298,18 +327,20 @@ export function renderComparison(delta) {
       ? `<span class="${d.deltaScore > 0 ? 'delta-pos' : 'delta-neg'}">(${d.deltaScore > 0 ? '+' : ''}${d.deltaScore})</span>`
       : '';
 
+    const why = d.a?.whyItMatters || d.b?.whyItMatters || '';
     html += `<div class="compare-card" id="compare-${esc(d.checkId)}">
   <div class="compare-card-header">
     <span class="check-title">${STATUS_ICON[d.a?.status || d.b?.status || 'skip'] || ''} ${esc(d.tool)} ${deltaLabel}</span>
     <div class="check-meta">${aBadge} ${bBadge}</div>
   </div>
-  <div class="compare-card-body">`;
+  <div class="compare-card-body">
+  ${why ? `<p style="color:#666;font-size:.85rem;font-style:italic;margin-bottom:.75rem">${esc(why)}</p>` : ''}`;
 
     if (d.availability === 'both') {
       const { shared, aOnly: aOnlyF, bOnly: bOnlyF } = classifyFindings(d.a, d.b);
       html += '<div class="side-by-side">';
-      html += `<div class="site-column"><h4>Site A</h4>${compareCardFindings('Site A only', aOnlyF, d.a)}</div>`;
-      html += `<div class="site-column"><h4>Site B</h4>${compareCardFindings('Site B only', bOnlyF, d.b)}</div>`;
+      html += `<div class="site-column"><h4>${esc(labelA)}</h4>${renderDetails(d.a)}${compareCardFindings(esc(labelA) + ' only', aOnlyF, d.a)}</div>`;
+      html += `<div class="site-column"><h4>${esc(labelB)}</h4>${renderDetails(d.b)}${compareCardFindings(esc(labelB) + ' only', bOnlyF, d.b)}</div>`;
       html += '</div>';
       if (shared.length) {
         html += `<div class="finding-group-label" style="margin-top:1rem">Shared issues (both sites)</div>${renderFindings(shared)}`;

package/templates/site-audit-runtime/tests/checks-tier1.test.mjs

@@ -91,13 +91,14 @@ test('observatory: normalize fixture produces valid CheckResult with grade', ()
 // --- testssl ---
 import * as testssl from '../src/checks/testssl.mjs';
 
-test('testssl: normalize fixture produces valid CheckResult with TLS findings', () => {
+test('testssl: normalize ssl-checker fixture produces valid CheckResult', () => {
   const r = testssl.normalize(ok('testssl'), 30000);
   const { valid, errors } = validateCheckResult(r);
   assert.ok(valid, errors.join('; '));
   assert.equal(r.checkId, 'testssl');
-  assert.ok(r.findings.length >= 2, 'TLS 1.1 + SWEET32');
-  assert.ok(r.findings.some(f => f.context?.includes('CVE')), 'SWEET32 has a CVE');
+  assert.equal(r.status, 'pass');
+  assert.equal(r.findings.length, 0);
+  assert.ok(r.passSummary?.includes('TLSv1.3'));
 });
 
 // --- meta-og ---

package/templates/site-audit-runtime/tests/checks-tier3.test.mjs

@@ -10,28 +10,6 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const fix = (id) => readFileSync(join(__dirname, 'fixtures', `${id}.json`), 'utf8');
 const ok = (id) => ({ code: 0, stdout: fix(id), stderr: '', timedOut: false });
 
-// --- blacklight ---
-import * as blacklight from '../src/checks/blacklight.mjs';
-
-test('blacklight: normalize fixture produces valid CheckResult with tracker findings', () => {
-  const r = blacklight.normalize(ok('blacklight'), 20000);
-  const { valid, errors } = validateCheckResult(r);
-  assert.ok(valid, errors.join('; '));
-  assert.equal(r.checkId, 'blacklight');
-  assert.equal(r.score, null);
-  assert.ok(r.findings.some(f => f.message.includes('Session replay')));
-  assert.ok(r.findings.some(f => f.message.includes('Canvas fingerprinting')));
-  assert.ok(r.findings.some(f => f.message.includes('Facebook Pixel')));
-  assert.ok(r.findings.some(f => f.message.includes('third-party cookies')));
-});
-
-test('blacklight: clean site → no findings', () => {
-  const r = blacklight.normalize({ code: 0, stdout: '{}', stderr: '', timedOut: false }, 5000);
-  const { valid, errors } = validateCheckResult(r);
-  assert.ok(valid, errors.join('; '));
-  assert.equal(r.findings.length, 0);
-});
-
 // --- unlighthouse ---
 import * as unlighthouse from '../src/checks/unlighthouse.mjs';
 

package/templates/site-audit-runtime/tests/fixtures/testssl.json

@@ -1 +1 @@
-[{"id":"TLS1","severity":"OK","finding":"TLS 1.3 offered"},{"id":"TLS1_1","severity":"LOW","finding":"TLS 1.1 still offered"},{"id":"heartbleed","severity":"OK","finding":"not vulnerable"},{"id":"POODLE_SSL","severity":"OK","finding":"not vulnerable"},{"id":"SWEET32","severity":"MEDIUM","finding":"potentially vulnerable, uses 64 bit block ciphers","cve":"CVE-2016-2183"}]
+{"valid":true,"validFrom":"2026-01-01T00:00:00.000Z","validTo":"2027-01-01T00:00:00.000Z","daysRemaining":215,"protocol":"TLSv1.3","cipher":"TLS_AES_256_GCM_SHA384"}

package/templates/site-audit-runtime/src/checks/blacklight.mjs

@@ -1,86 +0,0 @@
-// Blacklight detects runtime tracker behavior: session replay scripts,
-// canvas fingerprinting, keyloggers, ad trackers, third-party cookies.
-// It loads the page in headless Chromium and observes what the page does.
-
-export const checkId = 'blacklight';
-export const tool = 'Blacklight (tracker detection)';
-export const defaultTimeoutMs = 120_000;
-
-export async function detect(executor) {
-  const r = await executor.spawn('npx', ['@themarkup/blacklight-collector', '--help'], { timeoutMs: 15_000 });
-  return r.code === 0 || r.stdout.includes('blacklight');
-}
-
-export async function run(url, executor) {
-  return executor.spawn('npx', ['@themarkup/blacklight-collector', url, '--json'], { timeoutMs: 120_000 });
-}
-
-const TRACKER_SEVERITY = {
-  session_recorders: 'moderate',
-  canvas_fingerprinters: 'moderate',
-  key_logging: 'serious',
-  fb_pixel: 'info',
-  google_analytics: 'info',
-  third_party_trackers: 'info',
-};
-
-export function normalize(raw, durationMs) {
-  if (raw.code !== 0 && !raw.stdout) {
-    return { checkId, tool, status: 'error', score: null, grade: null, severity: null, findings: [], durationMs, reason: raw.stderr || 'blacklight failed' };
-  }
-
-  let data;
-  try { data = JSON.parse(raw.stdout); } catch {
-    return { checkId, tool, status: 'error', score: null, grade: null, severity: null, findings: [], durationMs, reason: 'failed to parse blacklight JSON' };
-  }
-
-  const findings = [];
-
-  if (data.session_recorders?.length) {
-    for (const r of data.session_recorders) {
-      findings.push({ severity: 'moderate', message: `Session replay: ${r.name || r.url || 'unknown'}`, url: r.url });
-    }
-  }
-  if (data.canvas_fingerprinters?.length) {
-    for (const f of data.canvas_fingerprinters) {
-      findings.push({ severity: 'moderate', message: `Canvas fingerprinting: ${f.name || f.url || 'unknown'}`, url: f.url });
-    }
-  }
-  if (data.key_logging?.length) {
-    for (const k of data.key_logging) {
-      findings.push({ severity: 'serious', message: `Key logging detected: ${k.name || k.url || 'unknown'}`, url: k.url });
-    }
-  }
-  if (data.fb_pixel_events?.length || data.fb_pixel) {
-    findings.push({ severity: 'info', message: `Facebook Pixel active (${(data.fb_pixel_events || []).length} events)` });
-  }
-  if (data.third_party_trackers?.length) {
-    for (const t of data.third_party_trackers.slice(0, 10)) {
-      findings.push({ severity: 'info', message: `Third-party tracker: ${t.name || t.url || 'unknown'}`, url: t.url });
-    }
-    if (data.third_party_trackers.length > 10) {
-      findings.push({ severity: 'info', message: `... and ${data.third_party_trackers.length - 10} more trackers` });
-    }
-  }
-  if (data.third_party_cookies?.length) {
-    findings.push({ severity: 'info', message: `${data.third_party_cookies.length} third-party cookies set` });
-  }
-
-  const worstSev = findings.length ? findings.reduce((w, f) => {
-    const o = { critical: 0, serious: 1, moderate: 2, info: 3 };
-    return (o[f.severity] ?? 3) < (o[w] ?? 3) ? f.severity : w;
-  }, 'info') : null;
-
-  const hasSerious = findings.some(f => f.severity === 'serious' || f.severity === 'critical');
-  const passSummary = !hasSerious
-    ? (findings.length === 0
-      ? 'No trackers, fingerprinters, or session recorders detected'
-      : `No serious trackers detected (${findings.length} low-severity item${findings.length !== 1 ? 's' : ''} only)`)
-    : undefined;
-
-  return {
-    checkId, tool, status: hasSerious ? 'fail' : 'pass',
-    score: null, grade: null, severity: worstSev, findings, durationMs,
-    ...(passSummary && { passSummary }),
-  };
-}

package/templates/site-audit-runtime/tests/fixtures/blacklight.json

@@ -1 +0,0 @@
-{"session_recorders":[{"name":"Hotjar","url":"https://static.hotjar.com/c/hotjar-123.js"}],"canvas_fingerprinters":[{"name":"FingerprintJS","url":"https://cdn.fingerprint.com/v3"}],"key_logging":[],"fb_pixel_events":[{"type":"PageView"}],"third_party_trackers":[{"name":"Google Analytics","url":"https://www.google-analytics.com/analytics.js"},{"name":"Segment","url":"https://cdn.segment.com/analytics.js"}],"third_party_cookies":[{"name":"_ga","domain":".google.com"},{"name":"_fbp","domain":".facebook.com"}]}