pagesight 0.17.0 → 0.18.0

package/src/tools/page/contrast.ts

@@ -0,0 +1,128 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export function parseHex(hex: string): [number, number, number] | null {
+  const clean = hex.replace(/^#/, "");
+  if (clean.length === 3) {
+    const r = Number.parseInt(clean[0] + clean[0], 16);
+    const g = Number.parseInt(clean[1] + clean[1], 16);
+    const b = Number.parseInt(clean[2] + clean[2], 16);
+    return [r, g, b];
+  }
+  if (clean.length === 6) {
+    const r = Number.parseInt(clean.slice(0, 2), 16);
+    const g = Number.parseInt(clean.slice(2, 4), 16);
+    const b = Number.parseInt(clean.slice(4, 6), 16);
+    return [r, g, b];
+  }
+  return null;
+}
+
+export function toHex(r: number, g: number, b: number): string {
+  return `#${[r, g, b].map((c) => Math.round(c).toString(16).padStart(2, "0")).join("")}`;
+}
+
+export function relativeLuminance(r: number, g: number, b: number): number {
+  const [rs, gs, bs] = [r, g, b].map((c) => {
+    const s = c / 255;
+    return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+}
+
+export function contrastRatio(l1: number, l2: number): number {
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+export function wcagLevel(ratio: number, isLargeText: boolean): string {
+  if (isLargeText) {
+    if (ratio >= 4.5) return "AAA";
+    if (ratio >= 3) return "AA";
+    return "FAIL";
+  }
+  if (ratio >= 7) return "AAA";
+  if (ratio >= 4.5) return "AA";
+  return "FAIL";
+}
+
+export function findNearestPassing(
+  fg: [number, number, number],
+  bg: [number, number, number],
+  targetRatio: number,
+): string {
+  const bgLum = relativeLuminance(...bg);
+
+  // Try both directions: darken and lighten, pick the one closest to original
+  let bestDarken: [number, number, number] | null = null;
+  let bestLighten: [number, number, number] | null = null;
+
+  for (let step = 0; step <= 100; step++) {
+    const t = step / 100;
+    const dark: [number, number, number] = [fg[0] * (1 - t), fg[1] * (1 - t), fg[2] * (1 - t)];
+    if (!bestDarken && contrastRatio(relativeLuminance(...dark), bgLum) >= targetRatio) {
+      bestDarken = dark;
+    }
+    const light: [number, number, number] = [
+      fg[0] + (255 - fg[0]) * t,
+      fg[1] + (255 - fg[1]) * t,
+      fg[2] + (255 - fg[2]) * t,
+    ];
+    if (!bestLighten && contrastRatio(relativeLuminance(...light), bgLum) >= targetRatio) {
+      bestLighten = light;
+    }
+    if (bestDarken && bestLighten) break;
+  }
+
+  // Pick the direction that changes the color least
+  if (bestDarken && bestLighten) {
+    const darkDist =
+      Math.abs(fg[0] - bestDarken[0]) + Math.abs(fg[1] - bestDarken[1]) + Math.abs(fg[2] - bestDarken[2]);
+    const lightDist =
+      Math.abs(fg[0] - bestLighten[0]) + Math.abs(fg[1] - bestLighten[1]) + Math.abs(fg[2] - bestLighten[2]);
+    return toHex(...(darkDist <= lightDist ? bestDarken : bestLighten));
+  }
+  return toHex(...(bestDarken ?? bestLighten ?? fg));
+}
+
+export function analyzeContrast(foreground: string, background: string, large_text?: boolean): CallToolResult {
+  const fg = parseHex(foreground);
+  const bg = parseHex(background);
+
+  if (!fg) return { content: [{ type: "text", text: `Invalid foreground color: ${foreground}` }] };
+  if (!bg) return { content: [{ type: "text", text: `Invalid background color: ${background}` }] };
+
+  const fgLum = relativeLuminance(...fg);
+  const bgLum = relativeLuminance(...bg);
+  const ratio = contrastRatio(fgLum, bgLum);
+  const isLarge = large_text ?? false;
+  const level = wcagLevel(ratio, isLarge);
+
+  const aaThreshold = isLarge ? 3 : 4.5;
+  const aaaThreshold = isLarge ? 4.5 : 7;
+
+  const lines: string[] = [
+    "=== Contrast Check ===",
+    "",
+    `Foreground: ${toHex(...fg)}`,
+    `Background: ${toHex(...bg)}`,
+    `Text size: ${isLarge ? "large (≥18pt)" : "normal"}`,
+    "",
+    `Contrast ratio: ${ratio.toFixed(2)}:1`,
+    `WCAG AA (${aaThreshold}:1): ${ratio >= aaThreshold ? "PASS" : "FAIL"}`,
+    `WCAG AAA (${aaaThreshold}:1): ${ratio >= aaaThreshold ? "PASS" : "FAIL"}`,
+    `Result: ${level}`,
+  ];
+
+  if (ratio < aaThreshold) {
+    const suggested = findNearestPassing(fg, bg, aaThreshold);
+    lines.push("", `Nearest AA-passing foreground: ${suggested}`);
+
+    const sugParsed = parseHex(suggested);
+    if (sugParsed) {
+      const sugRatio = contrastRatio(relativeLuminance(...sugParsed), bgLum);
+      lines.push(`New ratio: ${sugRatio.toFixed(2)}:1`);
+    }
+  }
+
+  return { content: [{ type: "text", text: lines.join("\n") }] };
+}

package/src/tools/page/links.ts

@@ -0,0 +1,200 @@
+interface RedirectHop {
+  url: string;
+  status: number;
+}
+
+interface ImageCheck {
+  url: string;
+  tag: string;
+  status: number | null;
+  contentType: string | null;
+  contentLength: number | null;
+  error: string | null;
+}
+
+export interface LinkResult {
+  href: string;
+  status: number | null;
+  redirectChain: Array<{ url: string; status: number }>;
+  finalUrl: string | null;
+  error: string | null;
+}
+
+export async function followRedirects(
+  url: string,
+  ua: string,
+  maxHops = 10,
+): Promise<{ chain: RedirectHop[]; response: Response }> {
+  const chain: RedirectHop[] = [];
+  let current = url;
+
+  for (let i = 0; i < maxHops; i++) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 15_000);
+    const res = await fetch(current, {
+      headers: { "User-Agent": ua, Accept: "text/html" },
+      redirect: "manual",
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+
+    chain.push({ url: current, status: res.status });
+
+    if (res.status >= 300 && res.status < 400) {
+      const location = res.headers.get("location");
+      if (!location) break;
+      current = new URL(location, current).href;
+      continue;
+    }
+
+    return { chain, response: res };
+  }
+
+  // Retry with automatic redirects after the hop limit or a missing Location header.
+  const res = await fetch(current, {
+    headers: { "User-Agent": ua, Accept: "text/html" },
+    redirect: "follow",
+  });
+  return { chain, response: res };
+}
+
+export async function checkImage(imageUrl: string, tag: string): Promise<ImageCheck> {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 10_000);
+    const res = await fetch(imageUrl, { method: "HEAD", redirect: "follow", signal: controller.signal });
+    clearTimeout(timeout);
+    return {
+      url: imageUrl,
+      tag,
+      status: res.status,
+      contentType: res.headers.get("content-type"),
+      contentLength: res.headers.has("content-length") ? Number(res.headers.get("content-length")) : null,
+      error: null,
+    };
+  } catch (err) {
+    return {
+      url: imageUrl,
+      tag,
+      status: null,
+      contentType: null,
+      contentLength: null,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export async function checkLink(href: string): Promise<LinkResult> {
+  const chain: Array<{ url: string; status: number }> = [];
+  let current = href;
+
+  try {
+    for (let i = 0; i < 10; i++) {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 10_000);
+      const res = await fetch(current, {
+        method: "HEAD",
+        headers: { "User-Agent": "Mozilla/5.0 (compatible; Googlebot/2.1)", Accept: "text/html" },
+        redirect: "manual",
+        signal: controller.signal,
+      });
+      clearTimeout(timeout);
+
+      chain.push({ url: current, status: res.status });
+
+      if (res.status >= 300 && res.status < 400) {
+        const location = res.headers.get("location");
+        if (!location) break;
+        current = new URL(location, current).href;
+        continue;
+      }
+
+      return {
+        href,
+        status: res.status,
+        redirectChain: chain,
+        finalUrl: chain.length > 1 ? current : null,
+        error: null,
+      };
+    }
+
+    return {
+      href,
+      status: chain[chain.length - 1]?.status ?? null,
+      redirectChain: chain,
+      finalUrl: current,
+      error: "Too many redirects",
+    };
+  } catch (err) {
+    return {
+      href,
+      status: null,
+      redirectChain: chain,
+      finalUrl: null,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export function extractInternalLinks(html: string, origin: string): string[] {
+  const links = new Set<string>();
+
+  for (const match of html.matchAll(/<a\s[^>]*href=["']([^"'#]+)/gi)) {
+    const raw = match[1].trim();
+    if (!raw || raw.startsWith("javascript:") || raw.startsWith("mailto:") || raw.startsWith("tel:")) continue;
+
+    try {
+      const resolved = new URL(raw, origin).href;
+      if (resolved.startsWith(origin) && !resolved.includes("/cdn-cgi/")) {
+        links.add(resolved);
+      }
+    } catch {
+      // Invalid URL, skip
+    }
+  }
+
+  return [...links];
+}
+
+export function formatLinkResults(url: string, results: LinkResult[]): string {
+  const lines: string[] = [`=== Internal Links: ${url} ===`, `Found ${results.length} internal links`, ""];
+
+  const broken = results.filter((r) => r.error || (r.status && r.status >= 400));
+  const redirected = results.filter((r) => !r.error && r.redirectChain.length > 1 && r.status && r.status < 400);
+  const ok = results.filter((r) => !r.error && r.redirectChain.length === 1 && r.status && r.status < 400);
+
+  // Summary
+  lines.push("--- Summary ---", "");
+  lines.push(`OK: ${ok.length}`);
+  if (redirected.length > 0) lines.push(`Redirected: ${redirected.length}`);
+  if (broken.length > 0) lines.push(`Broken: ${broken.length}`);
+  lines.push("");
+
+  // Broken links
+  if (broken.length > 0) {
+    lines.push("--- Broken Links ---", "");
+    for (const r of broken) {
+      if (r.error) {
+        lines.push(`FAIL  ${r.href}`);
+        lines.push(`      Error: ${r.error}`);
+      } else {
+        lines.push(`FAIL  ${r.href} → ${r.status}`);
+      }
+    }
+    lines.push("");
+  }
+
+  // Redirect chains
+  if (redirected.length > 0) {
+    lines.push("--- Redirect Chains ---", "");
+    for (const r of redirected) {
+      const hops = r.redirectChain.length - 1;
+      const chainStr = r.redirectChain.map((h) => `${h.status}`).join(" → ");
+      lines.push(`REDIRECT  ${r.href}`);
+      lines.push(`          ${chainStr} → ${r.finalUrl} (${hops} hop${hops > 1 ? "s" : ""})`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/src/tools/page/metadata.ts

@@ -0,0 +1,225 @@
+import { formatJsonLd } from "./structured-data.js";
+interface MetaTag {
+  name?: string;
+  property?: string;
+  content: string;
+}
+
+interface ParsedHead {
+  title: string | null;
+  charset: string | null;
+  canonical: string | null;
+  meta: MetaTag[];
+  hreflang: Array<{ lang: string; href: string }>;
+  jsonLd: unknown[];
+}
+
+export function parseHead(html: string): ParsedHead {
+  // Extract <head> content (case-insensitive, handles attributes on <head>)
+  const headMatch = html.match(/<head[^>]*>([\s\S]*?)<\/head>/i);
+  const head = headMatch?.[1] ?? html;
+
+  // Title
+  const titleMatch = head.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+  const title = titleMatch ? titleMatch[1].trim() : null;
+
+  // Charset
+  const charsetMatch = head.match(/<meta\s+charset=["']([^"']+)["']/i) ?? head.match(/charset=["']?([^"'\s;>]+)/i);
+  const charset = charsetMatch ? charsetMatch[1] : null;
+
+  // Canonical
+  const canonicalMatch = head.match(/<link[^>]*rel=["']canonical["'][^>]*href=["']([^"']+)["']/i);
+  const canonical = canonicalMatch ? canonicalMatch[1] : null;
+
+  // Meta tags (name=... content=... and property=... content=...)
+  const meta: MetaTag[] = [];
+  for (const m of head.matchAll(/<meta\s+([^>]*?)>/gi)) {
+    const attrs = m[1];
+    const nameMatch = attrs.match(/name=["']([^"']+)["']/i);
+    const propMatch = attrs.match(/property=["']([^"']+)["']/i);
+    const contentMatch = attrs.match(/content=["']([^"']*?)["']/i);
+    if (contentMatch && (nameMatch || propMatch)) {
+      meta.push({
+        name: nameMatch?.[1],
+        property: propMatch?.[1],
+        content: contentMatch[1],
+      });
+    }
+  }
+
+  // Hreflang
+  const hreflang: Array<{ lang: string; href: string }> = [];
+  const hreflangRegex =
+    /<link[^>]*rel=["']alternate["'][^>]*hreflang=["']([^"']+)["'][^>]*href=["']([^"']+)["'][^>]*>/gi;
+  const hreflangRegex2 =
+    /<link[^>]*hreflang=["']([^"']+)["'][^>]*href=["']([^"']+)["'][^>]*rel=["']alternate["'][^>]*>/gi;
+  const hreflangRegex3 =
+    /<link[^>]*href=["']([^"']+)["'][^>]*hreflang=["']([^"']+)["'][^>]*rel=["']alternate["'][^>]*>/gi;
+  for (const rx of [hreflangRegex, hreflangRegex2]) {
+    for (const hm of head.matchAll(rx)) {
+      hreflang.push({ lang: hm[1], href: hm[2] });
+    }
+  }
+  for (const hm of head.matchAll(hreflangRegex3)) {
+    hreflang.push({ lang: hm[2], href: hm[1] });
+  }
+
+  // Dedup hreflang entries
+  const seen = new Set<string>();
+  const dedupedHreflang = hreflang.filter((h) => {
+    const key = `${h.lang}:${h.href}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  // JSON-LD
+  const jsonLd: unknown[] = [];
+  for (const ld of html.matchAll(/<script[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi)) {
+    try {
+      jsonLd.push(JSON.parse(ld[1]));
+    } catch {
+      // malformed JSON-LD, skip
+    }
+  }
+
+  return { title, charset, canonical, meta, hreflang: dedupedHreflang, jsonLd };
+}
+
+export function getMeta(meta: MetaTag[], key: string): string | null {
+  const tag = meta.find(
+    (m) => m.name?.toLowerCase() === key.toLowerCase() || m.property?.toLowerCase() === key.toLowerCase(),
+  );
+  return tag?.content ?? null;
+}
+
+function getAllMeta(meta: MetaTag[], prefix: string): Array<{ key: string; value: string }> {
+  const results: Array<{ key: string; value: string }> = [];
+  for (const tag of meta) {
+    const key = tag.property ?? tag.name ?? "";
+    if (key.toLowerCase().startsWith(prefix.toLowerCase())) {
+      results.push({ key, value: tag.content });
+    }
+  }
+  return results;
+}
+
+export function formatMetatags(url: string, parsed: ParsedHead): string {
+  const lines: string[] = [`=== Meta Tags: ${url} ===`, ""];
+
+  // Document
+  lines.push("--- Document ---", "");
+  lines.push(`Title: ${parsed.title ? `"${parsed.title}"` : "(missing)"}`);
+  lines.push(
+    `Description: ${getMeta(parsed.meta, "description") ? `"${getMeta(parsed.meta, "description")}"` : "(missing)"}`,
+  );
+  lines.push(`Charset: ${parsed.charset ?? "(missing)"}`);
+  lines.push(`Viewport: ${getMeta(parsed.meta, "viewport") ?? "(missing)"}`);
+  lines.push(`Canonical: ${parsed.canonical ?? "(not set)"}`);
+  const robots = getMeta(parsed.meta, "robots");
+  if (robots) lines.push(`Robots: ${robots}`);
+  const author = getMeta(parsed.meta, "author");
+  if (author) lines.push(`Author: ${author}`);
+
+  // Length warnings
+  if (parsed.title && parsed.title.length > 60) {
+    lines.push(`WARN: title is ${parsed.title.length} chars — may truncate in search results (recommended: ≤60)`);
+  }
+  const desc = getMeta(parsed.meta, "description");
+  if (desc && desc.length > 155) {
+    lines.push(`WARN: description is ${desc.length} chars — may truncate in search results (recommended: ≤155)`);
+  }
+
+  // HTML entity warnings
+  const entityCheck = [
+    { label: "title", value: parsed.title },
+    { label: "description", value: getMeta(parsed.meta, "description") },
+    { label: "og:title", value: getMeta(parsed.meta, "og:title") },
+    { label: "og:description", value: getMeta(parsed.meta, "og:description") },
+  ];
+  for (const { label, value } of entityCheck) {
+    if (value && /&(?:amp|lt|gt|quot|apos|#\d+|#x[\da-f]+);/i.test(value)) {
+      lines.push(`WARN: ${label} contains HTML entities — may render incorrectly in social previews`);
+    }
+  }
+
+  lines.push("");
+
+  // Open Graph
+  const ogTags = getAllMeta(parsed.meta, "og:");
+  lines.push("--- Open Graph ---", "");
+  if (ogTags.length > 0) {
+    for (const tag of ogTags) {
+      lines.push(`${tag.key}: ${tag.value}`);
+    }
+  } else {
+    lines.push("(none found)");
+  }
+  lines.push("");
+
+  // Twitter Card
+  const twitterTags = getAllMeta(parsed.meta, "twitter:");
+  lines.push("--- Twitter Card ---", "");
+  if (twitterTags.length > 0) {
+    for (const tag of twitterTags) {
+      lines.push(`${tag.key}: ${tag.value}`);
+    }
+  } else {
+    lines.push("(none found)");
+  }
+  lines.push("");
+
+  // Structured Data
+  lines.push("--- Structured Data (JSON-LD) ---", "");
+  if (parsed.jsonLd.length > 0) {
+    for (let i = 0; i < parsed.jsonLd.length; i++) {
+      if (i > 0) lines.push("");
+      lines.push(`Block ${i + 1}:`);
+      lines.push(...formatJsonLd(parsed.jsonLd[i], 1));
+    }
+  } else {
+    lines.push("(none found)");
+  }
+  lines.push("");
+
+  // Hreflang
+  if (parsed.hreflang.length > 0) {
+    lines.push("--- Alternate Languages ---", "");
+    for (const h of parsed.hreflang) {
+      lines.push(`${h.lang}: ${h.href}`);
+    }
+    lines.push("");
+  } else {
+    // Warn if URL suggests locale-specific content but no hreflang
+    const localePattern =
+      /\/(?:en|es|fr|de|ja|ko|pt|zh|ru|it|nl|sv|da|fi|nb|pl|tr|ar|hi|th|vi|id|ms|uk|cs|ro|hu|el|he|bg|hr|sk|sl|sr|lt|lv|et|ca|gl|eu|cy)(?:[-_][a-z]{2,4})?(?:\/|$)/i;
+    const checkUrl = parsed.canonical ?? url;
+    if (localePattern.test(checkUrl)) {
+      lines.push(
+        "WARN: URL appears locale-specific but no hreflang tags found — search engines may not discover alternate language versions",
+      );
+      lines.push("");
+    }
+  }
+
+  // Summary of missing tags relevant to search and social
+  const missing: string[] = [];
+  if (!parsed.title) missing.push("title");
+  if (!getMeta(parsed.meta, "description")) missing.push("meta description");
+  if (!parsed.canonical) missing.push("canonical URL");
+  if (ogTags.length === 0) missing.push("Open Graph tags");
+  else {
+    if (!getMeta(parsed.meta, "og:image")) missing.push("og:image");
+  }
+  if (twitterTags.length === 0) missing.push("Twitter Card tags");
+  if (parsed.jsonLd.length === 0) missing.push("structured data (JSON-LD)");
+
+  if (missing.length > 0) {
+    lines.push("--- Not Found ---", "");
+    for (const m of missing) {
+      lines.push(`- ${m}`);
+    }
+  }
+
+  return lines.join("\n");
+}