@qobi/seocode 0.1.0

package/dist/src/cli/index.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { parseFile } from '../parsers/index.js';
+import { analyseDocument } from '../engine/rule-engine.js';
+import { parseConfig, applyConfigToRules } from '../config/seocode-config.js';
+import { discoverFiles } from './discover.js';
+import { formatTerminal } from './format-terminal.js';
+import { applyFixes } from './fix.js';
+import { stagedFiles } from './staged.js';
+import { runInit } from './init.js';
+const VERSION = '0.1.0';
+function parseArgs(argv) {
+    const a = {
+        command: 'check', paths: [], json: false,
+        color: process.stdout.isTTY && !process.env.NO_COLOR,
+        fix: false, staged: false, hook: false, help: false, version: false,
+    };
+    let sawCommand = false;
+    for (const arg of argv) {
+        if (arg === '--json')
+            a.json = true;
+        else if (arg === '--no-color')
+            a.color = false;
+        else if (arg === '--color')
+            a.color = true;
+        else if (arg === '--fix')
+            a.fix = true;
+        else if (arg === '--staged')
+            a.staged = true;
+        else if (arg === '--hook')
+            a.hook = true;
+        else if (arg === '-h' || arg === '--help')
+            a.help = true;
+        else if (arg === '-v' || arg === '--version')
+            a.version = true;
+        else if (arg.startsWith('-')) { /* unknown flag — ignore for now */ }
+        else if (!sawCommand && ['check', 'fix', 'init', 'help', 'version'].includes(arg)) {
+            a.command = arg;
+            sawCommand = true;
+        }
+        else
+            a.paths.push(arg);
+    }
+    if (a.command === 'fix')
+        a.fix = true; // `seocode fix` == `seocode check --fix`
+    if (a.command === 'help')
+        a.help = true;
+    if (a.command === 'version')
+        a.version = true;
+    return a;
+}
+const HELP = `
+seocode — technical SEO review for your codebase
+
+Usage
+  seocode check [paths...]   Scan the repo (or given paths) for SEO issues
+  seocode check --fix        Scan, then apply safe 1-click fixes to your files
+  seocode check --staged     Scan only files staged for commit (pre-commit mode)
+  seocode init               Create .seocode.json and set up a pre-commit hook
+  seocode --help             Show this help
+
+Options
+  --fix         Apply provably-safe fixes (e.g. loading="lazy", rel="noopener")
+  --staged      Review only git-staged files
+  --json        Machine-readable JSON output
+  --no-color    Disable ANSI colors (also respects NO_COLOR)
+  --hook        (with init) install .git/hooks/pre-commit
+
+Behavior
+  • Zero config — scans HTML, JS, JSX, TSX, Vue, Svelte and Astro files.
+  • Framework-aware — understands Next.js / Remix metadata, so it won't
+    false-flag dynamic titles, descriptions, or JSON-LD.
+  • Honors a .seocode.json in the repo root (exclude globs, rule overrides).
+  • Exit code 1 when deploy-blocking (critical) issues remain — drops straight
+    into a pre-commit hook or CI step.
+`;
+/** Locate the bundled ruleset by walking up from this module. */
+function findRulesFile() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 10; i++) {
+        const candidate = path.join(dir, 'rules', 'seo-rules.json');
+        if (fs.existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error('Could not locate rules/seo-rules.json (is the package intact?)');
+}
+async function analyseOne(file, rules) {
+    let content;
+    try {
+        content = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const doc = parseFile(file, content);
+    if (!doc)
+        return [];
+    return (await analyseDocument(doc, rules)).issues;
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (args.version) {
+        process.stdout.write(`seocode ${VERSION}\n`);
+        return 0;
+    }
+    const root = process.cwd();
+    if (args.command === 'init') {
+        process.stdout.write(runInit(root, { hook: args.hook }).output);
+        return 0;
+    }
+    // ── Config (.seocode.json) ──
+    let config = { exclude: [], rules: {} };
+    const cfgPath = path.join(root, '.seocode.json');
+    if (fs.existsSync(cfgPath))
+        config = parseConfig(fs.readFileSync(cfgPath, 'utf8'));
+    // ── Rules (bundled JSON, config overrides applied) ──
+    const allRules = JSON.parse(fs.readFileSync(findRulesFile(), 'utf8')).rules;
+    const rules = applyConfigToRules(allRules.filter(r => r.enabled), config);
+    // ── Discover files (repo scan, explicit paths, or staged set) ──
+    let inputs = args.paths;
+    if (args.staged) {
+        const staged = stagedFiles(root);
+        if (staged.length === 0) {
+            process.stdout.write('No staged files to review.\n');
+            return 0;
+        }
+        inputs = staged;
+    }
+    const files = discoverFiles(root, inputs, config.exclude);
+    // ── Optional: apply fixes first, then report the post-fix state ──
+    let fixedCount = 0;
+    let fixedFiles = 0;
+    if (args.fix) {
+        for (const file of files) {
+            let content;
+            try {
+                content = fs.readFileSync(file, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const doc = parseFile(file, content);
+            if (!doc)
+                continue;
+            const issues = (await analyseDocument(doc, rules)).issues;
+            const { content: fixed, applied } = applyFixes(content, issues);
+            if (applied > 0) {
+                fs.writeFileSync(file, fixed);
+                fixedCount += applied;
+                fixedFiles++;
+            }
+        }
+    }
+    // ── Analyse (post-fix if we fixed) and report ──
+    const fileReports = [];
+    let critical = 0, warning = 0, info = 0;
+    for (const file of files) {
+        const issues = await analyseOne(file, rules);
+        if (issues.length === 0)
+            continue;
+        fileReports.push({ file, issues });
+        for (const i of issues) {
+            if (i.severity === 'critical')
+                critical++;
+            else if (i.severity === 'warning')
+                warning++;
+            else
+                info++;
+        }
+    }
+    const report = { files: fileReports, scanned: files.length, critical, warning, info };
+    if (args.json) {
+        const flat = fileReports.flatMap(f => f.issues.map(i => ({
+            file: relOf(root, f.file), line: i.line, severity: i.severity,
+            ruleId: i.ruleId, ruleName: i.ruleName, description: i.description, fix: i.fix,
+        })));
+        process.stdout.write(JSON.stringify({ scanned: files.length, fixed: fixedCount, critical, warning, info, issues: flat }, null, 2) + '\n');
+    }
+    else {
+        if (fixedCount > 0) {
+            process.stdout.write(`\n  ✔ Applied ${fixedCount} fix${fixedCount === 1 ? '' : 'es'} across ${fixedFiles} file${fixedFiles === 1 ? '' : 's'}.\n`);
+        }
+        process.stdout.write(formatTerminal(report, { color: args.color, root }));
+    }
+    return critical > 0 ? 1 : 0;
+}
+function relOf(root, file) {
+    const rel = path.relative(root, file).split(path.sep).join('/');
+    return !rel || rel.startsWith('..') ? file : rel;
+}
+main().then(code => process.exit(code)).catch(err => {
+    process.stderr.write(`seocode: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(2);
+});

package/dist/src/cli/init.js

@@ -0,0 +1,48 @@
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * `seocode init` — scaffolds a `.seocode.json` (if absent) and prints how to wire
+ * a pre-commit hook. We intentionally generate a **pre-commit hook**, not a
+ * GitHub Action: the hosted GitHub App is the automated surface (no YAML, no CI
+ * runner minutes), and the CLI is the local one. `--hook` installs a native git
+ * hook; without it we just print the snippet so nothing is written unasked.
+ */
+export function runInit(root, opts) {
+    const lines = [];
+    const cfgPath = path.join(root, '.seocode.json');
+    let wroteConfig = false;
+    if (fs.existsSync(cfgPath)) {
+        lines.push('• .seocode.json already exists — left untouched.');
+    }
+    else {
+        fs.writeFileSync(cfgPath, JSON.stringify({ exclude: [], rules: {} }, null, 2) + '\n');
+        wroteConfig = true;
+        lines.push('✔ Created .seocode.json');
+    }
+    lines.push('');
+    lines.push('Config options (all optional):');
+    lines.push('  "exclude": ["emails/**", "public/legacy/**"]        skip paths (globs)');
+    lines.push('  "rules":   { "title-too-short": "off",              disable a rule');
+    lines.push('               "missing-canonical": "info" }          or change its severity');
+    lines.push('');
+    const hookBody = '#!/bin/sh\nnpx seocode check --staged\n';
+    const hookPath = path.join(root, '.git', 'hooks', 'pre-commit');
+    if (opts.hook) {
+        try {
+            fs.mkdirSync(path.dirname(hookPath), { recursive: true });
+            fs.writeFileSync(hookPath, hookBody);
+            fs.chmodSync(hookPath, 0o755);
+            lines.push('✔ Installed .git/hooks/pre-commit → runs `seocode check --staged` before every commit.');
+        }
+        catch (err) {
+            lines.push(`• Could not install the git hook (${err instanceof Error ? err.message : String(err)}).`);
+        }
+    }
+    else {
+        lines.push('Add a pre-commit hook to catch issues before you push:');
+        lines.push('  seocode init --hook          # installs .git/hooks/pre-commit for you');
+        lines.push('  # …or with husky:  echo "npx seocode check --staged" > .husky/pre-commit');
+    }
+    lines.push('');
+    return { output: lines.join('\n') + '\n', wroteConfig };
+}

package/dist/src/cli/staged.js

@@ -0,0 +1,24 @@
+import { execFileSync } from 'child_process';
+import * as path from 'path';
+/**
+ * Absolute paths of the files staged for commit (added/copied/modified). Powers
+ * `--staged` so the CLI drops into a pre-commit hook and reviews only what's
+ * about to be committed. Throws a clear message when there's no git repo.
+ */
+export function stagedFiles(root) {
+    let out;
+    try {
+        out = execFileSync('git', ['diff', '--cached', '--name-only', '--diff-filter=ACM'], {
+            cwd: root,
+            encoding: 'utf8',
+        });
+    }
+    catch {
+        throw new Error('--staged needs a git repository. Run it inside a repo with staged changes.');
+    }
+    return out
+        .split('\n')
+        .map(s => s.trim())
+        .filter(Boolean)
+        .map(f => path.resolve(root, f));
+}

package/dist/src/config/seocode-config.js

@@ -0,0 +1,97 @@
+const VALID_SEVERITIES = new Set(['critical', 'warning', 'info']);
+export const EMPTY_CONFIG = { exclude: [], rules: {} };
+/**
+ * Parses raw `.seocode.json` text into a validated config. Never throws — any
+ * malformed input falls back to EMPTY_CONFIG, and individual invalid entries are
+ * dropped rather than failing the whole file.
+ */
+export function parseConfig(raw) {
+    if (!raw)
+        return EMPTY_CONFIG;
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        return EMPTY_CONFIG;
+    }
+    if (typeof data !== 'object' || data === null)
+        return EMPTY_CONFIG;
+    const obj = data;
+    const exclude = Array.isArray(obj.exclude)
+        ? obj.exclude.filter((p) => typeof p === 'string' && p.length > 0)
+        : [];
+    const rules = {};
+    if (typeof obj.rules === 'object' && obj.rules !== null) {
+        for (const [id, val] of Object.entries(obj.rules)) {
+            if (val === false || val === 'off') {
+                rules[id] = 'off';
+            }
+            else if (typeof val === 'string' && VALID_SEVERITIES.has(val)) {
+                rules[id] = val;
+            }
+            // anything else (true, numbers, junk) is ignored
+        }
+    }
+    return { exclude, rules };
+}
+/**
+ * Applies rule overrides to the ruleset: disabled rules are dropped, severity
+ * overrides are applied. Returns a new array; input rules are not mutated.
+ */
+export function applyConfigToRules(rules, config) {
+    const out = [];
+    for (const rule of rules) {
+        const override = config.rules[rule.id];
+        if (override === 'off')
+            continue; // disabled — drop it
+        if (override && VALID_SEVERITIES.has(override)) {
+            out.push({ ...rule, severity: override });
+        }
+        else {
+            out.push(rule);
+        }
+    }
+    return out;
+}
+/**
+ * Converts a single glob to a RegExp. Supports `**` (any characters, incl. `/`),
+ * `*` (any characters except `/`), and `?` (one non-`/` char). A trailing `/`
+ * matches the directory and everything under it.
+ */
+function globToRegExp(glob) {
+    let g = glob;
+    if (g.endsWith('/'))
+        g += '**';
+    let re = '';
+    for (let i = 0; i < g.length; i++) {
+        const c = g[i];
+        if (c === '*') {
+            if (g[i + 1] === '*') {
+                re += '.*';
+                i++;
+                // consume a slash right after ** so "a/**/b" also matches "a/b"
+                if (g[i + 1] === '/')
+                    i++;
+            }
+            else {
+                re += '[^/]*';
+            }
+        }
+        else if (c === '?') {
+            re += '[^/]';
+        }
+        else if ('.+^${}()|[]\\'.includes(c)) {
+            re += '\\' + c;
+        }
+        else {
+            re += c;
+        }
+    }
+    return new RegExp('^' + re + '$');
+}
+/** True when `path` matches any of the exclude globs. */
+export function isPathExcluded(path, patterns) {
+    const normalized = path.replace(/^\.?\//, '');
+    return patterns.some(p => globToRegExp(p.replace(/^\.?\//, '')).test(normalized));
+}

package/dist/src/engine/page-detector.js

@@ -0,0 +1,82 @@
+const PAGE_CONFIDENCE_THRESHOLD = 3;
+// Filename patterns that strongly indicate a non-page file
+const NON_PAGE_FILENAME_PATTERNS = [
+    /constants?\./i,
+    /utils?\./i,
+    /helpers?\./i,
+    /types?\./i,
+    /config\./i,
+    /hooks?\./i,
+    /context\./i,
+    /store\./i,
+    /slice\./i,
+    /reducer\./i,
+    /actions?\./i,
+    /selectors?\./i,
+    /services?\./i,
+    /api\./i,
+    /mock\./i,
+    /test\./i,
+    /spec\./i,
+];
+// Framework shell mount point selectors
+const FRAMEWORK_MOUNT_PATTERNS = ['id="root"', 'id="app"', 'id="__next"', 'id="__nuxt"', '<app-root'];
+export function scorePageConfidence(doc) {
+    let score = 0;
+    const filename = doc.filePath.split('/').pop() ?? '';
+    // --- Positive signals ---
+    // Strong structural signals — present even in SEO-broken pages
+    if (doc.fileType === 'html') {
+        if (doc.rawContent.includes('<!DOCTYPE') || doc.rawContent.includes('<!doctype'))
+            score += 3;
+        if (/<body[\s>]/i.test(doc.rawContent))
+            score += 2;
+        if (/<head[\s>]/i.test(doc.rawContent))
+            score += 1;
+    }
+    else {
+        // JSX/TSX/Vue/Svelte page signals
+        if (/<html[\s>]/i.test(doc.rawContent))
+            score += 3;
+        if (/<head[\s>]/i.test(doc.rawContent))
+            score += 2;
+        if (/<body[\s>]/i.test(doc.rawContent))
+            score += 1;
+    }
+    // SEO meta signals
+    if (doc.titleTag)
+        score += 3;
+    if (doc.metaDescription)
+        score += 3;
+    if (doc.langAttribute)
+        score += 2;
+    if (doc.viewportMeta)
+        score += 1;
+    if (doc.charsetMeta)
+        score += 1;
+    if (doc.canonicalUrl)
+        score += 1;
+    if (doc.ogTitle || doc.ogDescription)
+        score += 2;
+    if (doc.headings.some((h) => h.tag === 'h1'))
+        score += 1;
+    // Has both a heading structure and some meta signal — looks like a real page
+    if (doc.headings.length > 0 && (doc.titleTag || doc.metaDescription))
+        score += 2;
+    // --- Negative signals ---
+    // Framework shell (React/Vue/Angular/Svelte app entry HTML)
+    if (FRAMEWORK_MOUNT_PATTERNS.some((p) => doc.rawContent.includes(p)))
+        score -= 5;
+    // Clearly a utility/config/type file by name
+    if (NON_PAGE_FILENAME_PATTERNS.some((pattern) => pattern.test(filename)))
+        score -= 4;
+    // No content signals at all — likely a component stub or data file
+    if (doc.headings.length === 0 && doc.images.length === 0 && doc.links.length === 0)
+        score -= 2;
+    return score;
+}
+export function isPageDocument(doc) {
+    // HTML files always count unless they are framework shells (handled by score)
+    // JSX/TSX/Vue/Svelte files need to earn enough page signals
+    return scorePageConfidence(doc) >= PAGE_CONFIDENCE_THRESHOLD;
+}

package/dist/src/engine/pr-delta.js

@@ -0,0 +1,31 @@
+export function splitByDelta(issues, addedLines, // filename -> Set(new-file line numbers this PR added)
+addedFiles, // files whose PR status is "added"
+prFiles) {
+    const introduced = [];
+    const preexisting = [];
+    for (const issue of issues) {
+        if (isIntroduced(issue, addedLines, addedFiles, prFiles))
+            introduced.push(issue);
+        else
+            preexisting.push(issue);
+    }
+    return { introduced, preexisting };
+}
+function isIntroduced(issue, addedLines, addedFiles, prFiles) {
+    // A brand-new file: everything in it is new.
+    if (addedFiles.has(issue.file))
+        return true;
+    // A file the PR never touched: pre-existing by definition.
+    if (!prFiles.has(issue.file))
+        return false;
+    // A file-level finding (no line) on a modified file can't be diff-located —
+    // don't blame the PR for something we can't attribute to its changes.
+    if (issue.line == null)
+        return false;
+    // Otherwise: introduced iff the finding sits on a line this PR added.
+    return addedLines.get(issue.file)?.has(issue.line) ?? false;
+}
+/** Convenience: how many introduced issues are criticals (drives the merge gate). */
+export function introducedCriticalCount(split) {
+    return split.introduced.filter(i => i.severity === 'critical').length;
+}

package/dist/src/engine/rule-engine.js

@@ -0,0 +1,112 @@
+import { loadRules } from './rule-loader.js';
+import { runRule } from './rules/index.js';
+import { filterRulesForPlan } from '../billing/tier.js';
+import { EMPTY_CONFIG, applyConfigToRules } from '../config/seocode-config.js';
+import { attachSuggestions } from './rules/suggest.js';
+// Only reached when preloadedRules is omitted — i.e. in tests, where loadRules
+// is mocked and never touches this stub. In production preloadedRules is always
+// supplied, so this is never invoked; the stub keeps types honest and fails loud
+// if that assumption is ever violated.
+const NO_KV = {
+    get: () => { throw new Error('loadRules called without a KV store — preloadedRules should always be provided in production'); },
+    put: async () => { },
+    delete: async () => { },
+};
+// Categories that only apply to full page documents — not utility/component files.
+const PAGE_ONLY_CATEGORIES = new Set(['meta', 'headings', 'schema', 'technical', 'performance']);
+// Framework shells (React/Vue/Svelte entry HTML) render content at runtime.
+// These rules are skipped because content is managed per-page by the framework.
+const FRAMEWORK_SHELL_SKIP_IDS = new Set([
+    'missing-h1',
+    'multiple-h1',
+    'heading-hierarchy',
+    'empty-heading',
+    'missing-json-ld',
+]);
+/**
+ * Whether a rule's declared file types cover this document. Astro templates are
+ * HTML-parsed, so a rule that targets `html` also applies to `astro` — this
+ * avoids having to add "astro" to all ~113 HTML rules in the JSON.
+ */
+function appliesToFileType(rule, fileType) {
+    if (rule.appliesTo.includes(fileType))
+        return true;
+    if (fileType === 'astro' && rule.appliesTo.includes('html'))
+        return true;
+    return false;
+}
+function isSkipped(rule, doc) {
+    // A route handler / OG-image route emits no HTML page — no rule applies.
+    if (doc.framework?.role === 'route')
+        return true;
+    if (!appliesToFileType(rule, doc.fileType))
+        return true;
+    if (!doc.isPageDocument && PAGE_ONLY_CATEGORIES.has(rule.category))
+        return true;
+    if (doc.isFrameworkShell && FRAMEWORK_SHELL_SKIP_IDS.has(rule.id))
+        return true;
+    // Framework-aware scoping (Next.js, Remix, …): a rule is skipped when the
+    // framework provides it another way (metadata API / injected default) or when
+    // its subject lives in a sibling file for this file's role (layout vs page).
+    const fw = doc.framework;
+    if (fw) {
+        if (fw.suppressedRuleIds.includes(rule.id))
+            return true;
+        if (fw.suppressedCategories.includes(rule.category))
+            return true;
+    }
+    return false;
+}
+/**
+ * Analyses a single document against a given set of rules.
+ *
+ * When `preloadedRules` is provided (always the case in production — passed
+ * from analyseDocuments after plan-filtering), rules are used directly.
+ *
+ * When `preloadedRules` is omitted (direct call in tests), rules are loaded
+ * via loadRules — the test mock intercepts this and returns the full ruleset.
+ */
+export async function analyseDocument(doc, preloadedRules) {
+    const rules = preloadedRules ?? (await loadRules(NO_KV)).rules;
+    const applicableRules = rules.filter(r => r.enabled && !isSkipped(r, doc));
+    const skippedRules = rules.filter(r => r.enabled && isSkipped(r, doc)).map(r => r.id);
+    const issues = [];
+    const passedRules = [];
+    for (const rule of applicableRules) {
+        const result = runRule(rule, doc);
+        if (result === null) {
+            passedRules.push(rule.id);
+        }
+        else {
+            issues.push(...(Array.isArray(result) ? result : [result]));
+        }
+    }
+    // Attach insertion-style 1-click fixes to declarative, file-level issues
+    // (per-element fixes are already attached by their rule handlers).
+    attachSuggestions(doc, issues);
+    return { file: doc.filePath, issues, passedRules, skippedRules };
+}
+/**
+ * Analyses multiple documents.
+ *
+ * Loads the full ruleset once, filters by plan, then runs each document
+ * against the filtered set in parallel.
+ *
+ * plan defaults to 'free' — the safest default (most restrictive).
+ * kvStore must be provided in production; in tests loadRules is mocked.
+ */
+export async function analyseDocuments(docs, plan = 'free', kvStore, config = EMPTY_CONFIG) {
+    const { rules: allRules, version, updatedAt } = await loadRules(kvStore);
+    // Rules are un-gated — every tier runs the full ruleset (filter is a pass-through).
+    const filteredRules = filterRulesForPlan(allRules, plan);
+    // Per-repo .seocode.json overrides: drop disabled rules, reclassify severities.
+    const effectiveRules = applyConfigToRules(filteredRules, config);
+    const fileResults = await Promise.all(docs.map(doc => analyseDocument(doc, effectiveRules)));
+    return {
+        fileResults,
+        version,
+        rulesDate: updatedAt,
+        // Count reflects the rules actually in force for this repo (post-config).
+        totalRuleCount: effectiveRules.filter(r => r.enabled).length,
+    };
+}

package/dist/src/engine/rule-loader.js

@@ -0,0 +1,35 @@
+let cache = null;
+const DEFAULT_TTL_MS = 3_600_000; // 1 hour
+const KV_KEY = 'rules';
+/**
+ * Loads the SEO rule set from Cloudflare KV.
+ *
+ * Rules are stored under the key "rules" in the SEO_RULES KV namespace.
+ * The value is the full seo-rules.json stringified.
+ *
+ * Results are cached in-memory for 1 hour so repeated PR events within
+ * the same isolate don't hit KV on every request.
+ *
+ * In tests, loadRules is mocked entirely.
+ */
+export async function loadRules(kvStore, ttlMs = DEFAULT_TTL_MS) {
+    const now = Date.now();
+    if (cache && now - cache.fetchedAt < ttlMs) {
+        return { rules: cache.rules, version: cache.version, updatedAt: cache.updatedAt };
+    }
+    const raw = await kvStore.get(KV_KEY);
+    if (!raw) {
+        throw new Error('SEO rules not found in KV. Run: npx wrangler kv key put --binding=SEO_RULES "rules" --path=rules/seo-rules.json');
+    }
+    const data = JSON.parse(raw);
+    cache = {
+        rules: data.rules,
+        version: data.version,
+        updatedAt: data.updatedAt,
+        fetchedAt: now,
+    };
+    return { rules: cache.rules, version: cache.version, updatedAt: cache.updatedAt };
+}
+export function invalidateCache() {
+    cache = null;
+}