create-claude-cabinet 0.27.4 → 0.28.0

package/README.md

@@ -114,6 +114,19 @@ Local SQLite database for actions, projects, and status tracking. Claude
 reads and writes it directly — no external service needed. Skip this if
 you already use GitHub Issues, Linear, or something else.
 
+### Memory (included in lean)
+
+Claude Code has built-in file memory, but no guardrails around it.
+The memory module adds structure:
+
+- **`/cc-remember`** — write a new memory with automatic indexing.
+  Every memory gets its own file and an entry in `MEMORY.md` so
+  `/orient` can find it next session.
+- **`/memory`** — browse and search what Claude remembers.
+- **Validation** — `validate-memory.mjs` checks that the index stays
+  within Claude Code's session-start budget and that every file is
+  indexed. A PostToolUse hook flags unindexed writes in real time.
+
 ### Compliance Stack (full install)
 
 Scoped instructions in `.claude/rules/` that load by file path. An

package/lib/cli.js

@@ -8,6 +8,7 @@ const { mergeSettings, healUserSettings } = require('./settings-merge');
 const { create: createMetadata, read: readMetadata } = require('./metadata');
 const { setupDb } = require('./db-setup');
 const { setupVerifyRuntime } = require('./verify-setup');
+const { setupSiteAuditRuntime } = require('./site-audit-setup');
 const { reset } = require('./reset');
 
 const VERSION = require('../package.json').version;
@@ -343,6 +344,97 @@ function generateSkillIndex(projectDir) {
   return entries.length;
 }
 
+/**
+ * Generate .claude/agents/cabinet-*.md wrapper definitions from installed
+ * cabinet SKILL.md files. Each wrapper is frontmatter-only and uses the
+ * `skills:` field to preload the skill body into the agent's context — the
+ * skill stays the single source of truth, so no prose is duplicated.
+ *
+ * The wrappers give each cabinet member a registered subagent identity:
+ * the transcript shows `subagent_type: cabinet-security` (trustworthy, not
+ * spoofable) instead of `general-purpose`, and `@cabinet-security` resolves
+ * as an agent type. This runs unconditionally — the identity layer benefits
+ * plan/execute/orient cabinet consultations, not just audits.
+ *
+ * Tool grants: cabinet `tools:` frontmatter is human-readable documentation
+ * (e.g., "fetch_docs (all projects -- ...)"), NOT a machine-parseable
+ * allowlist. So we grant a safe read-only base and ADD web tools only when
+ * the skill signals it needs them — never strip a capability the skill assumes.
+ *
+ * Reconciles the directory: wrappers whose cabinet skill no longer exists are
+ * deleted, so removing a member upstream doesn't leave a zombie wrapper.
+ */
+function generateAgentWrappers(projectDir) {
+  const skillsDir = path.join(projectDir, '.claude', 'skills');
+  if (!fs.existsSync(skillsDir)) return 0;
+
+  const agentsDir = path.join(projectDir, '.claude', 'agents');
+
+  // Discover cabinet members from installed skills.
+  const wanted = new Map(); // name -> wrapper content
+  const dirs = fs.readdirSync(skillsDir, { withFileTypes: true });
+  for (const dir of dirs) {
+    if (!dir.isDirectory() || !dir.name.startsWith('cabinet-')) continue;
+    const skillFile = path.join(skillsDir, dir.name, 'SKILL.md');
+    if (!fs.existsSync(skillFile)) continue;
+
+    const content = fs.readFileSync(skillFile, 'utf8');
+    const fm = parseFrontmatter(content);
+    if (!fm || !fm.name) continue;
+
+    const description = (fm.description || '').replace(/\s+/g, ' ').trim();
+    // YAML-safe single-line double-quoted scalar.
+    const descYaml = '"' + description.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+
+    // Base read-only investigation tools every cabinet member gets.
+    const tools = ['Read', 'Grep', 'Glob', 'Bash'];
+    // Cabinet tools: frontmatter is descriptive text, not an allowlist —
+    // scan it for real web-tool signals and add them.
+    const toolSignal = (typeof fm.tools === 'string' ? fm.tools : '').toLowerCase();
+    if (/websearch/.test(toolSignal)) tools.push('WebSearch');
+    if (/webfetch|fetch_docs/.test(toolSignal)) tools.push('WebFetch');
+
+    // model: none of the cabinet skills declare one today; default to sonnet,
+    // but honor an explicit declaration if a member ever sets one.
+    const model = (typeof fm.model === 'string' && fm.model.trim()) || 'sonnet';
+
+    const wrapper =
+      `---\n` +
+      `name: ${fm.name}\n` +
+      `description: ${descYaml}\n` +
+      `tools: ${[...new Set(tools)].join(', ')}\n` +
+      `model: ${model}\n` +
+      `skills: [${fm.name}]\n` +
+      `---\n`;
+
+    wanted.set(fm.name, wrapper);
+  }
+
+  if (wanted.size === 0) {
+    // No cabinet members installed — reconcile away any stale wrappers below,
+    // but only if the agents dir exists.
+    if (!fs.existsSync(agentsDir)) return 0;
+  }
+
+  fs.mkdirSync(agentsDir, { recursive: true });
+
+  // Write current wrappers.
+  for (const [name, wrapper] of wanted) {
+    fs.writeFileSync(path.join(agentsDir, `${name}.md`), wrapper);
+  }
+
+  // Reconcile: remove cabinet-*.md wrappers with no matching skill (zombies).
+  for (const file of fs.readdirSync(agentsDir)) {
+    if (!file.startsWith('cabinet-') || !file.endsWith('.md')) continue;
+    const name = file.slice(0, -3);
+    if (!wanted.has(name)) {
+      fs.unlinkSync(path.join(agentsDir, file));
+    }
+  }
+
+  return wanted.size;
+}
+
 // MODULES is the manifest: every template path here is copied into a
 // consumer's project on install. A skill/hook/script that exists under
 // templates/ but is NOT listed in any module never ships — that is the
@@ -487,6 +579,18 @@ const MODULES = {
     ],
     postInstall: 'verify-setup',
   },
+  'site-audit': {
+    name: 'Site Audit (deployed-site quality)',
+    description: '15-check audit for deployed websites: performance, accessibility (3 engines), security, SEO, DNS, privacy, sustainability. Standalone HTML report + comparison mode.',
+    mandatory: false,
+    default: false,
+    lean: false,
+    templates: [
+      'skills/cc-site-audit',
+      'site-audit-runtime',
+    ],
+    postInstall: 'site-audit-setup',
+  },
 };
 
 /** Recursively collect all relative file paths under a directory. */
@@ -1115,21 +1219,26 @@ async function run() {
 
   // --- Run module postInstall hooks ---
   // Modules with a `postInstall` field dispatch to a matching setup
-  // function after templates are copied. Currently only 'verify-setup'
-  // (the cabinet-verify tarball builder) is wired.
+  // function. Table-driven: add new runtime installers here.
+  const POST_INSTALL_HANDLERS = {
+    'verify-setup': setupVerifyRuntime,
+    'site-audit-setup': setupSiteAuditRuntime,
+  };
   for (const moduleKey of selectedModules) {
     const mod = MODULES[moduleKey];
     if (!mod.postInstall) continue;
-    if (mod.postInstall === 'verify-setup') {
-      try {
-        console.log('');
-        const verifyResult = setupVerifyRuntime({ dryRun: !!flags.dryRun });
-        for (const r of verifyResult.results || []) console.log(`  📋 ${r}`);
-      } catch (err) {
-        console.log(`  ⚠ cabinet-verify runtime setup failed: ${err.message}`);
-        console.log('    /verify install.sh will fail until the runtime is installed.');
-        console.log('    Re-run the installer to retry.');
-      }
+    const handler = POST_INSTALL_HANDLERS[mod.postInstall];
+    if (!handler) {
+      console.log(`  ⚠ Unknown postInstall handler: ${mod.postInstall}`);
+      continue;
+    }
+    try {
+      console.log('');
+      const result = handler({ dryRun: !!flags.dryRun });
+      for (const r of result.results || []) console.log(`  📋 ${r}`);
+    } catch (err) {
+      console.log(`  ⚠ ${mod.postInstall} failed: ${err.message}`);
+      console.log('    Re-run the installer to retry.');
     }
   }
 
@@ -1290,6 +1399,17 @@ async function run() {
     }
   }
 
+  // --- Generate cabinet agent-type wrappers ---
+  // Unconditional (not audit-gated): the registered subagent identity benefits
+  // plan/execute/orient cabinet consultations, not just /audit. No-op when no
+  // cabinet members are installed.
+  if (!flags.dryRun) {
+    const wrapperCount = generateAgentWrappers(projectDir);
+    if (wrapperCount > 0) {
+      console.log(`  🪪 Generated ${wrapperCount} cabinet agent wrappers in .claude/agents/`);
+    }
+  }
+
   // --- Write metadata ---
   if (!flags.dryRun) {
     createMetadata(projectDir, {
@@ -1353,4 +1473,4 @@ async function run() {
   console.log('');
 }
 
-module.exports = { run, MODULES };
+module.exports = { run, MODULES, generateAgentWrappers };

package/lib/site-audit-setup.js

@@ -0,0 +1,84 @@
+/**
+ * site-audit-setup.js — install the @claude-cabinet/site-audit runtime
+ * to ~/.claude-cabinet/site-audit/<version>/.
+ *
+ * Mirrors verify-setup.js: npm-pack the source, install to a versioned
+ * dir, write a current/VERSION pointer. Idempotent.
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CC_HOME = path.join(os.homedir(), '.claude-cabinet');
+const SITE_AUDIT_BASE = path.join(CC_HOME, 'site-audit');
+
+function setupSiteAuditRuntime(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const runtimeSourceDir =
+    opts.runtimeSourceDir || path.resolve(__dirname, '..', 'templates', 'site-audit-runtime');
+
+  const packageJsonPath = path.join(runtimeSourceDir, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    throw new Error(`site-audit-setup: ${packageJsonPath} not found.`);
+  }
+  const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  const version = pkg.version;
+  if (typeof version !== 'string' || version.length === 0) {
+    throw new Error(`site-audit-setup: ${packageJsonPath} has no version field`);
+  }
+
+  const installDir = path.join(SITE_AUDIT_BASE, version, 'dist');
+  const tarballName = `claude-cabinet-site-audit-${version}.tgz`;
+  const tarballPath = path.join(installDir, tarballName);
+  const versionPointer = path.join(SITE_AUDIT_BASE, 'current', 'VERSION');
+  const results = [];
+
+  if (dryRun) {
+    results.push(`Would install @claude-cabinet/site-audit@${version}`);
+    results.push(`  source:  ${runtimeSourceDir}`);
+    results.push(`  target:  ${tarballPath}`);
+    results.push(`  pointer: ${versionPointer}`);
+    return { installPath: installDir, version, status: 'dry-run', results };
+  }
+
+  if (fs.existsSync(tarballPath) && fs.statSync(tarballPath).size > 1024) {
+    results.push(`@claude-cabinet/site-audit@${version} already installed (${tarballPath})`);
+    writeVersionPointer(versionPointer, version);
+    return { installPath: installDir, version, status: 'skipped', results };
+  }
+
+  if (fs.existsSync(tarballPath)) fs.unlinkSync(tarballPath);
+
+  fs.mkdirSync(installDir, { recursive: true });
+  const packStdout = execSync(`npm pack --silent --pack-destination "${installDir}"`, {
+    cwd: runtimeSourceDir,
+    encoding: 'utf8',
+  }).trim();
+
+  const lastLine = packStdout.split('\n').filter(Boolean).pop() || '';
+  const producedName = path.basename(lastLine);
+  if (producedName && producedName !== tarballName) {
+    const producedPath = path.join(installDir, producedName);
+    if (fs.existsSync(producedPath)) {
+      fs.renameSync(producedPath, tarballPath);
+    }
+  }
+
+  if (!fs.existsSync(tarballPath)) {
+    throw new Error(`site-audit-setup: tarball not found after npm pack: ${tarballPath}`);
+  }
+
+  writeVersionPointer(versionPointer, version);
+  results.push(`Installed @claude-cabinet/site-audit@${version}`);
+  results.push(`  ${tarballPath}`);
+  return { installPath: installDir, version, status: 'installed', results };
+}
+
+function writeVersionPointer(pointerPath, version) {
+  fs.mkdirSync(path.dirname(pointerPath), { recursive: true });
+  fs.writeFileSync(pointerPath, version + '\n', 'utf8');
+}
+
+module.exports = { setupSiteAuditRuntime };

package/package.json

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

package/templates/site-audit-runtime/bin/cc-site-audit

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// Thin entry — all logic lives in src/cli.mjs so it stays unit-testable.
+import { main } from '../src/cli.mjs';
+
+main(process.argv.slice(2))
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    process.stderr.write(`${err?.stack ?? err}\n`);
+    process.exit(1);
+  });

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

@@ -0,0 +1,28 @@
+{
+  "name": "@claude-cabinet/site-audit",
+  "version": "0.1.0",
+  "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": {
+    "cc-site-audit": "./bin/cc-site-audit"
+  },
+  "files": [
+    "src/",
+    "bin/"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@axe-core/cli": "^4.10.0",
+    "@mdn/mdn-http-observatory": "^1.6.0",
+    "@themarkup/blacklight-collector": "^1.0.0",
+    "lighthouse": "^12.0.0",
+    "linkinator": "^7.0.0",
+    "pa11y": "^9.0.0",
+    "unlighthouse": "^0.16.0"
+  }
+}

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

@@ -0,0 +1,41 @@
+export const checkId = 'axe-core';
+export const tool = 'axe-core (WCAG AA)';
+
+export async function detect(executor) {
+  const r = await executor.spawn('npx', ['@axe-core/cli', '--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 });
+}
+
+const IMPACT_TO_SEVERITY = { critical: 'critical', serious: 'serious', moderate: 'moderate', minor: '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 || 'axe-core 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 axe-core JSON' };
+  }
+
+  const violations = Array.isArray(data) ? data.flatMap(p => p.violations || []) : (data.violations || []);
+  const findings = violations.map(v => ({
+    severity: IMPACT_TO_SEVERITY[v.impact] || 'info',
+    message: v.description || v.id,
+    url: v.helpUrl || undefined,
+    context: v.nodes?.[0]?.html?.slice(0, 200) || undefined,
+  }));
+
+  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;
+
+  return {
+    checkId, tool, status: findings.length === 0 ? 'pass' : 'fail',
+    score: null, grade: null, severity: worstSev, findings, durationMs,
+  };
+}

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

@@ -0,0 +1,79 @@
+// 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');
+  return {
+    checkId, tool, status: hasSerious ? 'fail' : 'pass',
+    score: null, grade: null, severity: worstSev, findings, durationMs,
+  };
+}

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

@@ -0,0 +1,65 @@
+export const checkId = 'dns';
+export const tool = 'DNS & Protocol';
+
+export async function detect(executor) {
+  const r = await executor.spawn('dig', ['-v'], { timeoutMs: 5_000 });
+  return r.code === 0 || r.stderr.includes('DiG');
+}
+
+export async function run(url, executor) {
+  const hostname = new URL(url).hostname;
+  const [dnssec, spf, dmarc, http2] = await Promise.all([
+    executor.spawn('dig', ['+dnssec', '+short', hostname], { timeoutMs: 10_000 }),
+    executor.spawn('dig', ['TXT', '+short', hostname], { timeoutMs: 10_000 }),
+    executor.spawn('dig', ['TXT', '+short', `_dmarc.${hostname}`], { timeoutMs: 10_000 }),
+    executor.spawn('curl', ['-sI', '--http2', '-o', '/dev/null', '-w', '%{http_version}', url], { timeoutMs: 10_000 }),
+  ]);
+  return { hostname, dnssec, spf, dmarc, http2 };
+}
+
+export function normalize(raw, durationMs) {
+  const findings = [];
+
+  if (raw.dnssec && raw.dnssec.code === 0) {
+    const out = raw.dnssec.stdout || '';
+    if (!out.includes('RRSIG')) {
+      findings.push({ severity: 'moderate', message: 'DNSSEC not enabled' });
+    }
+  }
+
+  if (raw.spf && raw.spf.code === 0) {
+    const out = raw.spf.stdout || '';
+    if (!out.includes('v=spf1')) {
+      findings.push({ severity: 'moderate', message: 'No SPF record found' });
+    }
+  }
+
+  if (raw.dmarc && raw.dmarc.code === 0) {
+    const out = raw.dmarc.stdout || '';
+    if (!out.includes('v=DMARC1')) {
+      findings.push({ severity: 'moderate', message: 'No DMARC record found' });
+    }
+  }
+
+  let httpVersion = null;
+  if (raw.http2 && raw.http2.code === 0) {
+    httpVersion = raw.http2.stdout.trim();
+    if (!httpVersion.startsWith('2') && !httpVersion.startsWith('3')) {
+      findings.push({ severity: 'info', message: `HTTP version ${httpVersion} (HTTP/2+ recommended)` });
+    }
+  }
+
+  const total = 4;
+  const passing = total - findings.filter(f => f.severity !== 'info').length;
+  const score = Math.round((passing / total) * 100);
+
+  return {
+    checkId, tool, status: findings.some(f => f.severity !== 'info') ? 'fail' : 'pass',
+    score, grade: null,
+    severity: 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,
+    findings, durationMs,
+  };
+}

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

@@ -0,0 +1,71 @@
+export const checkId = 'lighthouse';
+export const tool = 'Lighthouse';
+export const defaultTimeoutMs = 120_000;
+
+export async function detect(executor) {
+  const r = await executor.spawn('npx', ['lighthouse', '--version'], { timeoutMs: 15_000 });
+  return r.code === 0;
+}
+
+export async function run(url, executor) {
+  const r = await executor.spawn('npx', [
+    'lighthouse', url,
+    '--output=json',
+    '--chrome-flags=--headless=new --no-sandbox',
+    '--only-categories=performance,accessibility,best-practices,seo',
+  ], { timeoutMs: 120_000 });
+  return r;
+}
+
+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 || 'lighthouse 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 lighthouse JSON' };
+  }
+
+  const cats = data.categories || {};
+  const scores = {};
+  for (const [key, cat] of Object.entries(cats)) {
+    scores[key] = Math.round((cat.score ?? 0) * 100);
+  }
+  const avg = Object.values(scores).length
+    ? Math.round(Object.values(scores).reduce((a, b) => a + b, 0) / Object.values(scores).length)
+    : null;
+
+  const findings = [];
+  const audits = data.audits || {};
+  for (const [id, audit] of Object.entries(audits)) {
+    if (audit.score !== null && audit.score < 0.5 && audit.title) {
+      findings.push({
+        severity: audit.score === 0 ? 'serious' : 'moderate',
+        message: audit.title,
+        context: audit.displayValue || undefined,
+      });
+    }
+  }
+
+  const worstSev = findings.length ? findings.reduce((w, f) => {
+    const order = { critical: 0, serious: 1, moderate: 2, info: 3 };
+    return (order[f.severity] ?? 3) < (order[w] ?? 3) ? f.severity : w;
+  }, 'info') : null;
+
+  return {
+    checkId, tool, status: avg !== null && avg >= 50 ? 'pass' : 'fail',
+    score: avg, grade: scoreToGrade(avg), severity: worstSev, findings, durationMs,
+  };
+}
+
+function scoreToGrade(s) {
+  if (s == null) return null;
+  if (s >= 95) return 'A+';
+  if (s >= 90) return 'A';
+  if (s >= 85) return 'B+';
+  if (s >= 80) return 'B';
+  if (s >= 75) return 'C+';
+  if (s >= 70) return 'C';
+  if (s >= 60) return 'D';
+  return 'F';
+}

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

@@ -0,0 +1,53 @@
+export const checkId = 'linkinator';
+export const tool = 'Linkinator (broken links)';
+
+export async function detect(executor) {
+  const r = await executor.spawn('npx', ['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 });
+}
+
+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 || 'linkinator 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 linkinator JSON' };
+  }
+
+  const links = data.links || [];
+  const findings = [];
+
+  for (const link of links) {
+    if (link.state === 'BROKEN') {
+      findings.push({
+        severity: 'serious',
+        message: `Broken link: ${link.url} (${link.status || 'no response'})`,
+        url: link.url,
+        context: link.parent || undefined,
+      });
+    } else if (link.state === 'SKIPPED') {
+      findings.push({
+        severity: 'info',
+        message: `Skipped: ${link.url}`,
+        url: link.url,
+      });
+    }
+  }
+
+  const broken = findings.filter(f => f.severity !== 'info').length;
+  const total = links.filter(l => l.state !== 'SKIPPED').length;
+
+  return {
+    checkId, tool, status: broken === 0 ? 'pass' : 'fail',
+    score: null, grade: null,
+    severity: broken > 0 ? 'serious' : null,
+    findings: findings.filter(f => f.severity !== 'info'),
+    durationMs,
+  };
+}