@adsim/wordpress-mcp-server 3.1.0 → 4.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adsim/wordpress-mcp-server",
-  "version": "3.1.0",
+  "version": "4.5.0",
   "description": "A Model Context Protocol (MCP) server for WordPress REST API integration. Manage posts, search content, and interact with your WordPress site through any MCP-compatible client.",
   "type": "module",
   "main": "index.js",

package/src/confirmationToken.js

@@ -0,0 +1,64 @@
+import { createHash } from 'crypto';
+
+const SECRET = process.env.WP_MCP_SECRET ?? 'mcp-default-secret';
+
+/**
+ * Generate a stateless confirmation token for a destructive action.
+ * Format: mcp_{action}_{postId}_{timestamp}_{hash4}
+ */
+export function generateToken(postId, action) {
+  const timestamp = Math.floor(Date.now() / 1000);
+  const hash4 = createHash('sha256')
+    .update(`${postId}${action}${timestamp}${SECRET}`)
+    .digest('hex')
+    .substring(0, 4);
+  return `mcp_${action}_${postId}_${timestamp}_${hash4}`;
+}
+
+/**
+ * Validate a confirmation token.
+ * @returns {{ valid: boolean, reason?: string }}
+ */
+export function validateToken(token, postId, action, ttlSeconds = 60) {
+  if (typeof token !== 'string' || !token.startsWith('mcp_')) {
+    return { valid: false, reason: 'Invalid token format' };
+  }
+
+  // We know postId and action, so reconstruct expected prefix
+  const expectedPrefix = `mcp_${action}_${postId}_`;
+  if (!token.startsWith(expectedPrefix)) {
+    return { valid: false, reason: 'Token does not match post or action' };
+  }
+
+  const suffix = token.slice(expectedPrefix.length);
+  const lastUnderscore = suffix.lastIndexOf('_');
+  if (lastUnderscore === -1) {
+    return { valid: false, reason: 'Invalid token format' };
+  }
+
+  const timestampStr = suffix.substring(0, lastUnderscore);
+  const hash4 = suffix.substring(lastUnderscore + 1);
+  const timestamp = parseInt(timestampStr, 10);
+
+  if (isNaN(timestamp)) {
+    return { valid: false, reason: 'Invalid token format' };
+  }
+
+  // Check expiry
+  const now = Math.floor(Date.now() / 1000);
+  if (now - timestamp > ttlSeconds) {
+    return { valid: false, reason: 'Token expired' };
+  }
+
+  // Verify hash
+  const expectedHash = createHash('sha256')
+    .update(`${postId}${action}${timestamp}${SECRET}`)
+    .digest('hex')
+    .substring(0, 4);
+
+  if (hash4 !== expectedHash) {
+    return { valid: false, reason: 'Invalid token hash' };
+  }
+
+  return { valid: true };
+}

package/src/contentAnalyzer.js

@@ -0,0 +1,476 @@
+/**
+ * Content analysis utilities for WordPress MCP Server — Content Intelligence v4.4.
+ * Readability scoring, transition words, passive voice, content structure detection.
+ * Zero external dependencies — regex-based analysis.
+ */
+
+import { extractHeadings } from './htmlParser.js';
+
+// ── French vowels for syllable counting ──
+const VOWELS = /[aeiouyàâäéèêëïîôùûüœæ]/gi;
+
+/**
+ * Count syllables in a French word using vowel-group heuristic.
+ * @param {string} word
+ * @returns {number}
+ */
+export function countSyllablesFr(word) {
+  if (!word) return 0;
+  let w = word.toLowerCase().trim();
+  if (w.length === 0) return 0;
+
+  // Strip trailing silent 'e' (unless word <= 3 chars)
+  if (w.length > 3 && w.endsWith('e') && !w.endsWith('ée') && !w.endsWith('ie') && !w.endsWith('ue')) {
+    w = w.slice(0, -1);
+  }
+
+  // Count vowel groups
+  let count = 0;
+  let prevVowel = false;
+  for (const ch of w) {
+    const isVowel = /[aeiouyàâäéèêëïîôùûüœæ]/.test(ch);
+    if (isVowel && !prevVowel) count++;
+    prevVowel = isVowel;
+  }
+
+  return Math.max(1, count);
+}
+
+/**
+ * Strip HTML tags and return plain text.
+ * @param {string} html
+ * @returns {string}
+ */
+function stripToText(html) {
+  if (!html) return '';
+  return html
+    .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '')
+    .replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, '')
+    .replace(/<\/?(p|div|h[1-6]|li|br|tr|blockquote|pre)[^>]*>/gi, '\n')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"').replace(/&#039;/g, "'").replace(/&nbsp;/g, ' ')
+    .replace(/\n{3,}/g, '\n\n')
+    .replace(/[ \t]+/g, ' ')
+    .trim();
+}
+
+/**
+ * Split text into sentences.
+ * @param {string} text  Plain text (no HTML)
+ * @returns {string[]}
+ */
+function splitSentences(text) {
+  if (!text) return [];
+  return text
+    .split(/[.!?…]+/)
+    .map(s => s.trim())
+    .filter(s => s.length > 0);
+}
+
+/**
+ * Calculate readability score using French-adapted Flesch-Kincaid formula.
+ * @param {string} html
+ * @param {string} lang  Language code (default 'fr')
+ * @returns {{ score: number, sentences: number, words: number, syllables: number, avg_words_per_sentence: number, avg_syllables_per_word: number, level: string }}
+ */
+export function calculateReadabilityScore(html, lang = 'fr') {
+  const text = stripToText(html);
+  const sentences = splitSentences(text);
+  const sentenceCount = sentences.length || 1;
+  const words = text.split(/\s+/).filter(w => w.length > 0);
+  const wordCount = words.length || 1;
+
+  let totalSyllables = 0;
+  for (const w of words) {
+    totalSyllables += countSyllablesFr(w);
+  }
+
+  const avgWordsPerSentence = wordCount / sentenceCount;
+  const avgSyllablesPerWord = totalSyllables / wordCount;
+
+  // French-adapted Flesch-Kincaid
+  let raw = 207 - 1.015 * avgWordsPerSentence - 73.6 * avgSyllablesPerWord;
+  const score = Math.round(Math.max(0, Math.min(100, raw)) * 10) / 10;
+
+  let level;
+  if (score >= 80) level = 'très facile';
+  else if (score >= 60) level = 'facile';
+  else if (score >= 40) level = 'standard';
+  else if (score >= 20) level = 'difficile';
+  else level = 'très difficile';
+
+  return {
+    score,
+    sentences: sentenceCount,
+    words: wordCount,
+    syllables: totalSyllables,
+    avg_words_per_sentence: Math.round(avgWordsPerSentence * 10) / 10,
+    avg_syllables_per_word: Math.round(avgSyllablesPerWord * 100) / 100,
+    level
+  };
+}
+
+// ── French transition words ──
+const TRANSITION_WORDS_FR = [
+  'cependant', 'néanmoins', 'en effet', 'par conséquent', 'de plus',
+  'en outre', 'toutefois', 'ainsi', 'par ailleurs', 'en revanche',
+  "c'est pourquoi", 'autrement dit', 'en somme', "d'une part", "d'autre part",
+  'premièrement', 'deuxièmement', 'finalement', 'en conclusion', 'en résumé',
+  'par exemple', 'notamment', 'en particulier', "c'est-à-dire", 'à savoir',
+  'bien que', 'malgré', 'alors que', 'tandis que', 'puisque',
+  'car', 'donc', 'or', 'mais', 'pourtant',
+  'du coup', 'ensuite', 'puis', 'enfin', "d'abord"
+];
+
+/**
+ * Extract transition words found in text.
+ * @param {string} text  Plain text
+ * @param {string} lang  Language code (default 'fr')
+ * @returns {{ count: number, density: number, words_found: string[] }}
+ */
+export function extractTransitionWords(text, lang = 'fr') {
+  if (!text) return { count: 0, density: 0, words_found: [] };
+  const lower = text.toLowerCase();
+  const sentences = splitSentences(text);
+  const sentenceCount = sentences.length || 1;
+  const found = [];
+
+  for (const tw of TRANSITION_WORDS_FR) {
+    // Word-boundary aware search (handles multi-word transitions)
+    const escaped = tw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const regex = new RegExp(`(?:^|[\\s,;:(])${escaped}(?:[\\s,;:.!?)]|$)`, 'gi');
+    if (regex.test(lower)) {
+      found.push(tw);
+    }
+  }
+
+  return {
+    count: found.length,
+    density: Math.round((found.length / sentenceCount) * 100) / 100,
+    words_found: found
+  };
+}
+
+// ── French passive voice patterns ──
+const PASSIVE_AUX_PATTERN = /\b(?:est|sont|a\s+été|ont\s+été|sera|seront|fut|furent|était|étaient)\b/gi;
+const PAST_PARTICIPLE = /\b\w+(?:é|ée|és|ées|i|ie|is|ise|it|ite|u|ue|us|ues|t|te|ts|tes)\b/;
+
+/**
+ * Count sentences containing passive voice constructions.
+ * @param {string} text  Plain text
+ * @param {string} lang  Language code (default 'fr')
+ * @returns {{ count: number, total_sentences: number, ratio: number }}
+ */
+export function countPassiveSentences(text, lang = 'fr') {
+  if (!text) return { count: 0, total_sentences: 0, ratio: 0 };
+  const sentences = splitSentences(text);
+  let passiveCount = 0;
+
+  for (const sentence of sentences) {
+    const auxRegex = new RegExp(PASSIVE_AUX_PATTERN.source, 'gi');
+    let match;
+    while ((match = auxRegex.exec(sentence)) !== null) {
+      const after = sentence.slice(match.index + match[0].length).trim();
+      const nextWords = after.split(/\s+/).slice(0, 3).join(' ');
+      if (PAST_PARTICIPLE.test(nextWords)) {
+        passiveCount++;
+        break;
+      }
+    }
+  }
+
+  return {
+    count: passiveCount,
+    total_sentences: sentences.length,
+    ratio: sentences.length > 0 ? Math.round((passiveCount / sentences.length) * 100) / 100 : 0
+  };
+}
+
+/**
+ * Extract headings outline from HTML (H1-H6).
+ * @param {string} html
+ * @returns {{ level: number, text: string }[]}
+ */
+export function extractHeadingsOutline(html) {
+  return extractHeadings(html);
+}
+
+// ── Content section detection ──
+const CONCLUSION_KEYWORDS = ['conclusion', 'résumé', 'en résumé', 'pour conclure', 'en conclusion'];
+const FAQ_KEYWORDS = ['faq', 'questions fréquentes', 'questions courantes', 'foire aux questions'];
+
+/**
+ * Detect content structure: intro, conclusion, FAQ, lists, tables, images.
+ * @param {string} html
+ * @returns {{ has_intro: boolean, has_conclusion: boolean, has_faq: boolean, lists_count: number, tables_count: number, images_count: number, headings_count: number }}
+ */
+export function detectContentSections(html) {
+  if (!html) return { has_intro: false, has_conclusion: false, has_faq: false, lists_count: 0, tables_count: 0, images_count: 0, headings_count: 0 };
+
+  const headings = extractHeadings(html);
+  const headingsCount = headings.length;
+
+  // Intro = content before first H2
+  const firstH2Idx = html.search(/<h2\b/i);
+  const has_intro = firstH2Idx > 0 && stripToText(html.substring(0, firstH2Idx)).length > 30;
+
+  // Conclusion = last H2+ section contains conclusion keywords
+  let has_conclusion = false;
+  if (headings.length > 0) {
+    const lastHeading = headings[headings.length - 1];
+    const lastText = lastHeading.text.toLowerCase();
+    has_conclusion = CONCLUSION_KEYWORDS.some(kw => lastText.includes(kw));
+  }
+
+  // FAQ detection
+  const lowerHtml = html.toLowerCase();
+  const has_faq = FAQ_KEYWORDS.some(kw => lowerHtml.includes(kw));
+
+  // Counts
+  const lists_count = (html.match(/<(?:ul|ol)\b/gi) || []).length;
+  const tables_count = (html.match(/<table\b/gi) || []).length;
+  const images_count = (html.match(/<img\b/gi) || []).length;
+
+  return { has_intro, has_conclusion, has_faq, lists_count, tables_count, images_count, headings_count: headingsCount };
+}
+
+// ── TF-IDF and Cosine Similarity ──
+
+const STOP_WORDS_FR = new Set(['les', 'des', 'une', 'pour', 'dans', 'par', 'sur', 'avec', 'son', 'ses', 'aux', 'qui', 'que', 'est', 'sont', 'ont', 'été', 'pas', 'plus', 'tout', 'tous', 'cette', 'ces', 'mais', 'comme', 'être', 'avoir', 'faire', 'peut', 'nous', 'vous', 'ils', 'elle', 'leur', 'même', 'entre', 'après', 'sans', 'aussi', 'bien', 'quel', 'autre', 'très', 'encore', 'fait', 'dit', 'deux', 'dont', 'quand']);
+
+/**
+ * Build TF-IDF vectors for a set of documents.
+ * @param {{ id: any, text: string }[]} documents
+ * @returns {{ vectors: Map<any, Map<string, number>>, terms: Set<string> }}
+ */
+export function buildTFIDFVectors(documents) {
+  if (!documents || documents.length === 0) return { vectors: new Map(), terms: new Set() };
+
+  const tokenize = (text) => {
+    return (text || '').toLowerCase()
+      .split(/[^a-zàâäéèêëïîôùûüœæç0-9]+/i)
+      .filter(t => t.length >= 3 && !STOP_WORDS_FR.has(t));
+  };
+
+  const docTokens = new Map();
+  const docContainingTerm = new Map();
+
+  for (const doc of documents) {
+    const tokens = tokenize(doc.text);
+    const tf = new Map();
+    const total = tokens.length || 1;
+    const seen = new Set();
+
+    for (const token of tokens) {
+      tf.set(token, (tf.get(token) || 0) + 1 / total);
+      if (!seen.has(token)) {
+        seen.add(token);
+        if (!docContainingTerm.has(token)) docContainingTerm.set(token, new Set());
+        docContainingTerm.get(token).add(doc.id);
+      }
+    }
+    docTokens.set(doc.id, tf);
+  }
+
+  const totalDocs = documents.length;
+  const allTerms = new Set();
+  const vectors = new Map();
+
+  for (const doc of documents) {
+    const tf = docTokens.get(doc.id);
+    const tfidf = new Map();
+    for (const [term, tfVal] of tf) {
+      const idf = Math.log(1 + totalDocs / docContainingTerm.get(term).size);
+      tfidf.set(term, tfVal * idf);
+      allTerms.add(term);
+    }
+    vectors.set(doc.id, tfidf);
+  }
+
+  return { vectors, terms: allTerms };
+}
+
+/**
+ * Compute cosine similarity between two TF-IDF vectors.
+ * @param {Map<string, number>} vec1
+ * @param {Map<string, number>} vec2
+ * @returns {number}
+ */
+export function computeCosineSimilarity(vec1, vec2) {
+  if (!vec1 || !vec2 || vec1.size === 0 || vec2.size === 0) return 0;
+
+  let dot = 0;
+  let mag1 = 0;
+  let mag2 = 0;
+
+  for (const [term, val] of vec1) {
+    mag1 += val * val;
+    if (vec2.has(term)) dot += val * vec2.get(term);
+  }
+  for (const [, val] of vec2) {
+    mag2 += val * val;
+  }
+
+  const denom = Math.sqrt(mag1) * Math.sqrt(mag2);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+/**
+ * Find near-duplicate document pairs above a similarity threshold.
+ * @param {{ id: any, title: string, text: string }[]} documents
+ * @param {number} threshold
+ * @returns {{ doc1_id: any, doc2_id: any, similarity: number }[]}
+ */
+export function findDuplicatePairs(documents, threshold = 0.7) {
+  if (!documents || documents.length < 2) return [];
+
+  const { vectors } = buildTFIDFVectors(documents);
+  const pairs = [];
+  const ids = [...vectors.keys()];
+
+  for (let i = 0; i < ids.length; i++) {
+    for (let j = i + 1; j < ids.length; j++) {
+      const sim = computeCosineSimilarity(vectors.get(ids[i]), vectors.get(ids[j]));
+      if (sim >= threshold) {
+        pairs.push({ doc1_id: ids[i], doc2_id: ids[j], similarity: sim });
+      }
+    }
+  }
+
+  return pairs;
+}
+
+// ── Named Entity Extraction ──
+
+const ENTITY_EXCLUSIONS = new Set(['Le', 'La', 'Les', 'Un', 'Une', 'Des', 'Ce', 'Cette', 'Ces', 'Il', 'Elle', 'Ils', 'Elles', 'On', 'Nous', 'Vous', 'Mon', 'Ma', 'Mes', 'Son', 'Sa', 'Ses', 'Leur', 'Leurs', 'Notre', 'Votre', 'Tout', 'Tous', 'Toute', 'Toutes', 'Quel', 'Quelle', 'Mais', 'Donc', 'Car', 'Puis', 'Aussi', 'Bien', 'Très', 'Plus', 'Moins', 'Pour', 'Dans', 'Avec', 'Sans', 'Sur', 'Sous', 'Par', 'Entre', 'Après', 'Avant', 'Depuis', 'Pendant', 'Comme', 'Si', 'Quand', 'Où', 'Comment', 'Pourquoi', 'À', 'Au', 'Aux', 'En', 'De', 'Du']);
+
+const KNOWN_BRANDS = new Set(['Google', 'Facebook', 'Meta', 'Microsoft', 'Apple', 'Amazon', 'AWS', 'Azure', 'WordPress', 'Shopify', 'HubSpot', 'Salesforce', 'SEMrush', 'Ahrefs', 'Moz', 'Yoast', 'RankMath', 'WooCommerce', 'Elementor', 'Cloudflare', 'GitHub', 'Twitter', 'LinkedIn', 'Instagram', 'YouTube', 'TikTok', 'ChatGPT', 'OpenAI', 'Anthropic', 'Claude']);
+
+const KNOWN_LOCATIONS = new Set(['Belgique', 'France', 'Bruxelles', 'Paris', 'Liège', 'Europe', 'Wallonie', 'Flandre', 'Luxembourg', 'Suisse', 'Genève', 'Canada', 'Montréal', 'Québec', 'États-Unis', 'New York', 'Londres', 'Berlin', 'Amsterdam']);
+
+const KNOWN_FIRSTNAMES = new Set(['Jean', 'Pierre', 'Marie', 'Paul', 'Michel', 'Jacques', 'Philippe', 'François', 'Nicolas', 'Laurent', 'Julien', 'Thomas', 'David', 'Sophie', 'Julie', 'Isabelle', 'Nathalie', 'Stéphane', 'Christophe', 'Sébastien', 'Georges', 'Antoine', 'Alexandre', 'Marc', 'Olivier']);
+
+const BRAND_CONTEXT_WORDS = ['plateforme', 'outil', 'logiciel', 'solution', 'service', 'application', 'app'];
+const ORG_SUFFIXES = ['SA', 'SRL', 'SPRL', 'ASBL', 'Inc', 'Corp', 'Ltd', 'GmbH', 'SAS', 'SARL'];
+const ORG_PREFIXES = ["l'entreprise", 'la société', "l'agence", 'le groupe'];
+
+/**
+ * Extract named entities from plain text using regex heuristics.
+ * @param {string} text  Plain text (no HTML)
+ * @returns {{ name: string, type: string, count: number, contexts: string[] }[]}
+ */
+export function extractEntities(text) {
+  if (!text) return [];
+
+  const sentences = text.split(/(?<=[.!?…])\s+/).filter(s => s.length > 0);
+  const entityMap = new Map(); // name -> { type, count, contexts }
+
+  for (const sentence of sentences) {
+    const words = sentence.split(/\s+/);
+    if (words.length < 2) continue;
+
+    let i = 0;
+    while (i < words.length) {
+      const raw = words[i];
+      const clean = raw.replace(/[,;:.!?()]+$/, '');
+      if (/^[A-ZÀ-Ÿ]/.test(clean) && !ENTITY_EXCLUSIONS.has(clean)) {
+        // Group consecutive capitalized words (break on trailing punctuation like comma)
+        const parts = [clean];
+        const hasPunct = raw !== clean; // word had trailing punctuation
+        let j = i + 1;
+        if (!hasPunct) {
+          while (j < words.length) {
+            const rawJ = words[j];
+            const cleanJ = rawJ.replace(/[,;:.!?()]+$/, '');
+            if (!/^[A-ZÀ-Ÿ]/.test(cleanJ) || ENTITY_EXCLUSIONS.has(cleanJ)) break;
+            parts.push(cleanJ);
+            if (rawJ !== cleanJ) { j++; break; } // trailing punctuation breaks group
+            j++;
+          }
+        } else {
+          // Trailing punct on first word — don't group further
+        }
+        const entityName = parts.join(' ');
+        if (entityName.length < 2) { i = j; continue; }
+
+        // Classify
+        const afterWords = words.slice(j, j + 3).map(w2 => w2.toLowerCase());
+        const beforeWords = words.slice(Math.max(0, i - 3), i).map(w2 => w2.toLowerCase()).join(' ');
+        let type = 'unknown';
+
+        // Check brand
+        if (parts.some(p => KNOWN_BRANDS.has(p)) || BRAND_CONTEXT_WORDS.some(bc => afterWords.includes(bc))) {
+          type = 'brand';
+        }
+        // Check location
+        else if (KNOWN_LOCATIONS.has(entityName) || parts.some(p => KNOWN_LOCATIONS.has(p))) {
+          type = 'location';
+        }
+        // Check person (firstname + surname)
+        else if (parts.length >= 2 && KNOWN_FIRSTNAMES.has(parts[0])) {
+          type = 'person';
+        }
+        // Check organization
+        else if (ORG_SUFFIXES.some(s => afterWords[0] === s.toLowerCase() || parts[parts.length - 1] === s) ||
+                 ORG_PREFIXES.some(p => beforeWords.includes(p))) {
+          type = 'organization';
+        }
+
+        if (!entityMap.has(entityName)) {
+          entityMap.set(entityName, { type, count: 0, contexts: [] });
+        }
+        const entry = entityMap.get(entityName);
+        entry.count++;
+        if (entry.contexts.length < 2) {
+          const ctx = sentence.length > 120 ? sentence.substring(0, 120) + '…' : sentence;
+          entry.contexts.push(ctx);
+        }
+
+        i = j;
+      } else {
+        i++;
+      }
+    }
+  }
+
+  return [...entityMap.entries()].map(([name, data]) => ({
+    name, type: data.type, count: data.count, contexts: data.contexts
+  }));
+}
+
+// ── Text Diff ──
+
+/**
+ * Compute a simplified line-by-line diff between two texts.
+ * @param {string} textA  Base text
+ * @param {string} textB  Target text
+ * @returns {{ lines_added: number, lines_removed: number, lines_unchanged: number, words_added: number, words_removed: number, change_ratio: number, added_lines: string[], removed_lines: string[] }}
+ */
+export function computeTextDiff(textA, textB) {
+  const linesA = (textA || '').split('\n').filter(l => l.trim().length > 0);
+  const linesB = (textB || '').split('\n').filter(l => l.trim().length > 0);
+
+  const setA = new Set(linesA);
+  const setB = new Set(linesB);
+
+  const removed = linesA.filter(l => !setB.has(l));
+  const added = linesB.filter(l => !setA.has(l));
+  const unchanged = linesA.filter(l => setB.has(l));
+
+  const countW = (lines) => lines.reduce((sum, l) => sum + l.split(/\s+/).filter(w => w.length > 0).length, 0);
+
+  const total = added.length + removed.length + unchanged.length;
+  const changeRatio = total > 0 ? (added.length + removed.length) / total : 0;
+
+  return {
+    lines_added: added.length,
+    lines_removed: removed.length,
+    lines_unchanged: unchanged.length,
+    words_added: countW(added),
+    words_removed: countW(removed),
+    change_ratio: changeRatio,
+    added_lines: added.slice(0, 20),
+    removed_lines: removed.slice(0, 20)
+  };
+}

package/src/htmlParser.js

@@ -0,0 +1,80 @@
+/**
+ * HTML parsing utilities for WordPress MCP Server.
+ * Zero external dependencies — regex-based parsing.
+ */
+
+/**
+ * Extract <img> tags from HTML content.
+ * @param {string} html
+ * @returns {{ src: string, alt: string, title: string }[]}
+ */
+export function parseImagesFromHtml(html) {
+  if (!html) return [];
+  const images = [];
+  const regex = /<img\s[^>]*?>/gi;
+  let match;
+  while ((match = regex.exec(html)) !== null) {
+    const tag = match[0];
+    const src = (tag.match(/src=["']([^"']+)["']/i) || [])[1] || '';
+    const alt = (tag.match(/alt=["']([^"']*?)["']/i) || [])[1] || '';
+    const title = (tag.match(/title=["']([^"']*?)["']/i) || [])[1] || '';
+    if (src) images.push({ src, alt, title });
+  }
+  return images;
+}
+
+/**
+ * Extract headings (H1-H6) from HTML content.
+ * @param {string} html
+ * @returns {{ level: number, text: string }[]}
+ */
+export function extractHeadings(html) {
+  if (!html) return [];
+  const headings = [];
+  const regex = /<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1>/gi;
+  let match;
+  while ((match = regex.exec(html)) !== null) {
+    const level = parseInt(match[1], 10);
+    const text = match[2].replace(/<[^>]*>/g, '').trim();
+    headings.push({ level, text });
+  }
+  return headings;
+}
+
+/**
+ * Extract internal links from HTML (returns normalised absolute URLs).
+ * @param {string} html
+ * @param {string} siteUrl  e.g. https://example.com
+ * @returns {string[]}
+ */
+export function extractInternalLinks(html, siteUrl) {
+  if (!html || !siteUrl) return [];
+  let siteHost;
+  try { siteHost = new URL(siteUrl).host; } catch { return []; }
+  const links = [];
+  const regex = /<a\s[^>]*?href=["']([^"']+)["'][^>]*?>/gi;
+  let match;
+  while ((match = regex.exec(html)) !== null) {
+    const href = match[1];
+    try {
+      if (href.startsWith('/') && !href.startsWith('//')) {
+        links.push(`${siteUrl.replace(/\/+$/, '')}${href}`);
+      } else if (href.startsWith('http')) {
+        if (new URL(href).host === siteHost) links.push(href);
+      }
+    } catch { /* invalid URL, skip */ }
+  }
+  return links;
+}
+
+/**
+ * Count words in HTML content (strips tags first).
+ * @param {string} html
+ * @returns {number}
+ */
+export function countWords(html) {
+  if (!html) return 0;
+  const text = html.replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim();
+  if (!text) return 0;
+  return text.split(/\s+/).length;
+}