pagesight 0.17.0 → 0.18.0

package/src/tools/search/coverage.ts

@@ -0,0 +1,247 @@
+import { listSitemaps } from "../../providers/gsc.js";
+import { type SearchOptions } from "./schema.js";
+import { humanizeState, type InspectionSummary, inspectSingle } from "./inspection.js";
+import { fetchSitemap, sampleUrls } from "./sitemap-sampling.js";
+import { textResult } from "./result.js";
+const COVERAGE_FILTERS = [
+  "not_indexed",
+  "server_error",
+  "redirect",
+  "soft_404",
+  "blocked",
+  "duplicate",
+  "discovered",
+  "crawled_not_indexed",
+] as const;
+
+type CoverageFilter = (typeof COVERAGE_FILTERS)[number];
+
+export function matchesCoverageFilter(result: InspectionSummary, filter: CoverageFilter): boolean {
+  if (result.error) return false;
+  const cs = result.coverageState.toLowerCase();
+  const pf = result.pageFetchState.toLowerCase();
+  switch (filter) {
+    case "not_indexed":
+      return result.verdict !== "PASS";
+    case "server_error":
+      return cs.includes("server error") || pf === "server_error";
+    case "redirect":
+      return cs.includes("redirect") || pf.includes("redirect");
+    case "soft_404":
+      return cs.includes("soft 404") || pf === "soft_404";
+    case "blocked":
+      return cs.includes("blocked");
+    case "duplicate":
+      return cs.includes("duplicate");
+    case "discovered":
+      return cs.includes("discovered");
+    case "crawled_not_indexed":
+      return cs.includes("crawled - currently not indexed");
+    default:
+      return false;
+  }
+}
+
+function filterNameForState(state: string): string | null {
+  const s = state.toLowerCase();
+  if (s.includes("server error")) return "server_error";
+  if (s.includes("blocked")) return "blocked";
+  if (s.includes("redirect")) return "redirect";
+  if (s.includes("soft 404")) return "soft_404";
+  if (s.includes("duplicate")) return "duplicate";
+  if (s.includes("discovered - currently not indexed")) return "discovered";
+  if (s.includes("crawled - currently not indexed")) return "crawled_not_indexed";
+  return null;
+}
+
+export function formatSampleResults(
+  siteUrl: string,
+  sitemapUrl: string,
+  totalUrls: number,
+  results: InspectionSummary[],
+): string {
+  const lines: string[] = [
+    `=== Sample Inspection: ${siteUrl} ===`,
+    `Sitemap: ${sitemapUrl} (${totalUrls.toLocaleString()} URLs)`,
+    `Sampled: ${results.length}`,
+    "",
+  ];
+
+  // Summary
+  const verdictCounts: Record<string, number> = {};
+  const coverageCounts: Record<string, number> = {};
+  const fetchCounts: Record<string, number> = {};
+  let indexed = 0;
+  let errors = 0;
+
+  for (const r of results) {
+    if (r.error) {
+      errors++;
+      continue;
+    }
+    verdictCounts[r.verdict] = (verdictCounts[r.verdict] ?? 0) + 1;
+    coverageCounts[r.coverageState] = (coverageCounts[r.coverageState] ?? 0) + 1;
+    fetchCounts[r.pageFetchState] = (fetchCounts[r.pageFetchState] ?? 0) + 1;
+    if (r.verdict === "PASS") indexed++;
+  }
+
+  const inspected = results.length - errors;
+  lines.push("--- Inspected sample ---", "");
+  lines.push(`Indexed: ${indexed}/${inspected}`);
+
+  if (indexed < inspected) {
+    lines.push(`Not indexed: ${inspected - indexed}/${inspected}`);
+    for (const [state, count] of Object.entries(coverageCounts)) {
+      if (state !== "Submitted and indexed" && state !== "Indexing allowed") {
+        lines.push(`  ${state}: ${count}`);
+      }
+    }
+  }
+
+  // Page fetch issues
+  const fetchIssues = Object.entries(fetchCounts).filter(([s]) => s !== "SUCCESSFUL");
+  if (fetchIssues.length > 0) {
+    lines.push("");
+    lines.push("Page fetch issues:");
+    for (const [state, count] of fetchIssues) {
+      lines.push(`  ${humanizeState(state)}: ${count}`);
+    }
+  }
+
+  if (errors > 0) {
+    lines.push(`\nInspection errors: ${errors}`);
+  }
+
+  // Individual results
+  lines.push("", "--- Details ---", "");
+  for (let i = 0; i < results.length; i++) {
+    const r = results[i];
+    lines.push(`${i + 1}. ${r.url}`);
+    if (r.error) {
+      lines.push(`   Error: ${r.error}`);
+    } else {
+      lines.push(`   Verdict: ${r.verdict}`);
+      lines.push(`   Coverage: ${r.coverageState}`);
+      lines.push(`   Page fetch: ${humanizeState(r.pageFetchState)}`);
+      if (r.robotsTxtState !== "ALLOWED") lines.push(`   Robots.txt: ${humanizeState(r.robotsTxtState)}`);
+      if (r.indexingState !== "INDEXING_ALLOWED") lines.push(`   Indexing: ${humanizeState(r.indexingState)}`);
+      if (r.lastCrawlTime) lines.push(`   Last crawled: ${r.lastCrawlTime}`);
+      if (r.googleCanonical && r.googleCanonical !== r.url) {
+        lines.push(`   Google canonical: ${r.googleCanonical}`);
+      }
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+function formatCoverage(siteUrl: string, sitemapUrl: string, totalUrls: number, results: InspectionSummary[]): string {
+  const inspected = results.filter((r) => !r.error);
+  const errors = results.filter((r) => r.error);
+  const indexed = inspected.filter((r) => r.verdict === "PASS");
+  const notIndexed = inspected.filter((r) => r.verdict !== "PASS");
+
+  const lines: string[] = [
+    `=== Index Coverage: ${siteUrl} ===`,
+    `Sitemap: ${sitemapUrl} (${totalUrls.toLocaleString()} URLs)`,
+    `Inspected: ${results.length}`,
+    "",
+  ];
+
+  const total = inspected.length;
+  if (total === 0) {
+    lines.push("No URLs could be inspected.");
+    if (errors.length > 0) {
+      lines.push("");
+      for (const e of errors) lines.push(`  ${e.url}: ${e.error}`);
+    }
+    return lines.join("\n");
+  }
+
+  // Group not-indexed by coverageState
+  const issueGroups: Record<string, InspectionSummary[]> = {};
+  for (const r of notIndexed) {
+    const key = r.coverageState;
+    if (!issueGroups[key]) issueGroups[key] = [];
+    issueGroups[key].push(r);
+  }
+  const sortedIssues = Object.entries(issueGroups).sort((a, b) => b[1].length - a[1].length);
+
+  // Breakdown
+  lines.push("--- Breakdown ---", "");
+  lines.push(`Indexed: ${indexed.length}/${total} (${Math.round((indexed.length / total) * 100)}%)`);
+  lines.push(`Not indexed: ${notIndexed.length}/${total} (${Math.round((notIndexed.length / total) * 100)}%)`);
+  for (const [state, urls] of sortedIssues) {
+    lines.push(`  ${state}: ${urls.length}`);
+  }
+  if (errors.length > 0) {
+    lines.push(`Inspection errors: ${errors.length}`);
+  }
+
+  lines.push("", "These verdicts describe only the inspected sample, not site-wide coverage.");
+
+  // Example URLs per issue
+  if (sortedIssues.length > 0) {
+    lines.push("", "--- URLs by Issue ---", "");
+    for (const [state, urls] of sortedIssues) {
+      lines.push(`${state}:`);
+      for (const u of urls.slice(0, 3)) {
+        lines.push(`  ${u.url}`);
+        if (u.lastCrawlTime) lines.push(`    Last crawled: ${u.lastCrawlTime}`);
+        if (u.pageFetchState !== "SUCCESSFUL") lines.push(`    Fetch: ${humanizeState(u.pageFetchState)}`);
+      }
+      if (urls.length > 3) lines.push(`  ... and ${urls.length - 3} more in sample`);
+      lines.push("");
+    }
+  }
+
+  // Suggest drill-down
+  const filterSuggestions = sortedIssues.map(([state]) => filterNameForState(state)).filter(Boolean);
+  if (filterSuggestions.length > 0) {
+    lines.push(`Drill deeper: search(action='sample', filter='...') to investigate specific issues.`);
+    lines.push(`  Available filters: ${filterSuggestions.join(", ")}`);
+  }
+
+  return lines.join("\n");
+}
+
+export async function runCoverage(options: SearchOptions) {
+  const { site_url, sitemap_url, sample_size, sample_strategy } = options;
+  if (!site_url) return textResult("Error: site_url is required for coverage.");
+
+  const count = sample_size ?? 20;
+  const strategy = sample_strategy ?? "spread";
+
+  // Discover sitemap URL if not provided
+  let resolvedSitemapUrl = sitemap_url;
+  if (!resolvedSitemapUrl) {
+    const sitemaps = await listSitemaps(site_url);
+    if (sitemaps.length === 0) {
+      return textResult(`No sitemaps found for ${site_url} in GSC. Provide a sitemap_url directly.`);
+    }
+    const nonIndex = sitemaps.find((s) => !s.isSitemapsIndex);
+    resolvedSitemapUrl = (nonIndex ?? sitemaps[0]).path;
+  }
+
+  let parsed = await fetchSitemap(resolvedSitemapUrl);
+
+  if (parsed.isSitemapIndex && parsed.childSitemaps.length > 0) {
+    const childUrl = parsed.childSitemaps[0];
+    parsed = await fetchSitemap(childUrl);
+    resolvedSitemapUrl = `${resolvedSitemapUrl} → ${childUrl}`;
+  }
+
+  if (parsed.urls.length === 0) {
+    return textResult(`Sitemap ${resolvedSitemapUrl} contains no URLs.`);
+  }
+
+  const sampled = sampleUrls(parsed.urls, count, strategy);
+
+  const results: InspectionSummary[] = [];
+  for (const u of sampled) {
+    results.push(await inspectSingle(u, site_url));
+  }
+
+  return textResult(formatCoverage(site_url, resolvedSitemapUrl, parsed.urls.length, results));
+}

package/src/tools/search/gaps.ts

@@ -0,0 +1,129 @@
+import { querySearchAnalytics, type SearchAnalyticsFilter } from "../../providers/gsc.js";
+import { pacificDaysAgo } from "../../shared/dates.js";
+import { type SearchOptions } from "./schema.js";
+import { textResult } from "./result.js";
+function extractPageText(html: string): string {
+  // Extract text from HTML; this does not check rendered visibility.
+  let text = html;
+  text = text.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, " ");
+  text = text.replace(/<style[^>]*>[\s\S]*?<\/style>/gi, " ");
+  text = text.replace(/<[^>]+>/g, " ");
+  // Decode common HTML entities
+  text = text
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&nbsp;/g, " ");
+  // Normalize whitespace
+  text = text.replace(/\s+/g, " ").trim().toLowerCase();
+  return text;
+}
+
+function formatGapAnalysis(
+  pageUrl: string,
+  siteUrl: string,
+  queries: Array<{ query: string; clicks: number; impressions: number; ctr: number; position: number }>,
+  pageText: string,
+): string {
+  const lines: string[] = [`=== Keyword Gap Analysis: ${pageUrl} ===`, `Property: ${siteUrl}`, ""];
+
+  if (queries.length === 0) {
+    lines.push("No search queries found for this page.");
+    return lines.join("\n");
+  }
+
+  const onPage: typeof queries = [];
+  const gaps: typeof queries = [];
+
+  for (const q of queries) {
+    const words = q.query.toLowerCase().split(/\s+/);
+    const allPresent = words.every((w) => pageText.includes(w));
+    if (allPresent) {
+      onPage.push(q);
+    } else {
+      gaps.push(q);
+    }
+  }
+
+  lines.push(`Queries analyzed: ${queries.length}`);
+  lines.push(`On page: ${onPage.length}`);
+  lines.push(`Gaps (not on page): ${gaps.length}`);
+  lines.push("");
+
+  if (gaps.length > 0) {
+    lines.push("--- Keyword Gaps (queries with impressions but missing from page) ---", "");
+    gaps.sort((a, b) => b.impressions - a.impressions);
+    for (const q of gaps.slice(0, 20)) {
+      const ctr = (q.ctr * 100).toFixed(1);
+      lines.push(
+        `  "${q.query}" — ${q.impressions} imp, ${q.clicks} clicks, CTR ${ctr}%, pos ${q.position.toFixed(1)}`,
+      );
+    }
+    if (gaps.length > 20) lines.push(`  ... and ${gaps.length - 20} more`);
+    lines.push("");
+  }
+
+  if (onPage.length > 0) {
+    lines.push("--- Already Targeted (query found on page) ---", "");
+    onPage.sort((a, b) => b.impressions - a.impressions);
+    for (const q of onPage.slice(0, 10)) {
+      const ctr = (q.ctr * 100).toFixed(1);
+      lines.push(
+        `  "${q.query}" — ${q.impressions} imp, ${q.clicks} clicks, CTR ${ctr}%, pos ${q.position.toFixed(1)}`,
+      );
+    }
+    if (onPage.length > 10) lines.push(`  ... and ${onPage.length - 10} more`);
+    lines.push("");
+  }
+
+  const totalGapImpressions = gaps.reduce((sum, q) => sum + q.impressions, 0);
+  const totalImpressions = queries.reduce((sum, q) => sum + q.impressions, 0);
+  if (totalImpressions > 0) {
+    const gapPct = Math.round((totalGapImpressions / totalImpressions) * 100);
+    lines.push(`${gapPct}% of impressions come from queries not on the page — potential content opportunity.`);
+  }
+
+  return lines.join("\n");
+}
+
+export async function runGaps(options: SearchOptions) {
+  const { site_url, url, start_date, end_date, row_limit } = options;
+  if (!url) return textResult("Error: url is required for gap analysis.");
+  if (!site_url) return textResult("Error: site_url is required for gap analysis.");
+
+  // Fetch page content and GSC queries in parallel
+  const [pageRes, analyticsRes] = await Promise.all([
+    fetch(url, {
+      headers: { "User-Agent": "Mozilla/5.0 (compatible; Googlebot/2.1)", Accept: "text/html" },
+      redirect: "follow",
+    }),
+    querySearchAnalytics(site_url, {
+      startDate: start_date ?? pacificDaysAgo(28),
+      endDate: end_date ?? pacificDaysAgo(3),
+      dimensions: ["query"],
+      rowLimit: row_limit ?? 500,
+      dimensionFilterGroups: [
+        {
+          groupType: "and" as const,
+          filters: [{ dimension: "page", operator: "equals", expression: url } as SearchAnalyticsFilter],
+        },
+      ],
+    }),
+  ]);
+
+  if (!pageRes.ok) return textResult(`Error fetching ${url}: HTTP ${pageRes.status}`);
+  const html = await pageRes.text();
+  const pageText = extractPageText(html);
+
+  const queries = (analyticsRes.rows ?? []).map((row) => ({
+    query: row.keys[0],
+    clicks: row.clicks,
+    impressions: row.impressions,
+    ctr: row.ctr,
+    position: row.position,
+  }));
+
+  return textResult(formatGapAnalysis(url, site_url, queries, pageText));
+}

package/src/tools/search/inspection.ts

@@ -0,0 +1,160 @@
+import { type InspectionResult, inspectUrl } from "../../providers/gsc.js";
+import { type SearchOptions } from "./schema.js";
+import { textResult } from "./result.js";
+function formatInspection(url: string, siteUrl: string, r: InspectionResult): string {
+  const idx = r.indexStatusResult;
+  const lines: string[] = [
+    `=== URL Inspection: ${url} ===`,
+    `Property: ${siteUrl}`,
+    "",
+    "--- Index Status ---",
+    "",
+    `Verdict: ${idx.verdict}`,
+    `Coverage: ${idx.coverageState}`,
+    `Page fetch: ${idx.pageFetchState}`,
+    `Robots.txt: ${idx.robotsTxtState}`,
+    `Indexing: ${idx.indexingState}`,
+    `Crawled as: ${idx.crawledAs ?? "unknown"}`,
+  ];
+
+  if (idx.lastCrawlTime) lines.push(`Last crawled: ${idx.lastCrawlTime}`);
+  if (idx.userCanonical) lines.push(`Your canonical: ${idx.userCanonical}`);
+  if (idx.googleCanonical) lines.push(`Google's canonical: ${idx.googleCanonical}`);
+
+  if (idx.userCanonical && idx.googleCanonical && idx.userCanonical !== idx.googleCanonical) {
+    lines.push(`\n⚠ CANONICAL MISMATCH: You declared "${idx.userCanonical}" but Google chose "${idx.googleCanonical}"`);
+  }
+
+  if (idx.sitemap && idx.sitemap.length > 0) {
+    lines.push(`\nSitemaps: ${idx.sitemap.join(", ")}`);
+  }
+
+  if (idx.referringUrls && idx.referringUrls.length > 0) {
+    lines.push(`\nReferring URLs: ${idx.referringUrls.join(", ")}`);
+  }
+
+  if (idx.verdict !== "PASS") {
+    const gscUrl = `https://search.google.com/search-console/inspect?resource_id=${encodeURIComponent(siteUrl)}&id=${encodeURIComponent(url)}`;
+    lines.push("", "→ This page is not indexed. Request indexing manually in Google Search Console:", `  ${gscUrl}`);
+  }
+
+  // Rich Results
+  if (r.richResultsResult) {
+    lines.push("", "--- Rich Results ---", "");
+    lines.push(`Verdict: ${r.richResultsResult.verdict}`);
+
+    for (const item of r.richResultsResult.detectedItems ?? []) {
+      lines.push(`\nType: ${item.richResultType}`);
+      for (const instance of item.items ?? []) {
+        if (instance.name) lines.push(`  Name: ${instance.name}`);
+        const issues = instance.issues ?? [];
+        if (issues.length === 0) {
+          lines.push("  Status: PASS");
+        } else {
+          for (const issue of issues) {
+            lines.push(`  ${issue.severity}: ${issue.issueMessage}`);
+          }
+        }
+      }
+    }
+  }
+
+  // Display deprecated mobile-usability evidence when supplied.
+  if (r.mobileUsabilityResult) {
+    lines.push("", "--- Mobile Usability (deprecated) ---", "");
+    lines.push(`Verdict: ${r.mobileUsabilityResult.verdict}`);
+    if (r.mobileUsabilityResult.issues) {
+      for (const issue of r.mobileUsabilityResult.issues) {
+        lines.push(`  ${issue.issueType}${issue.message ? `: ${issue.message}` : ""}`);
+      }
+    }
+  }
+
+  // Inspection link
+  if (r.inspectionResultLink) {
+    lines.push("", `Full report: ${r.inspectionResultLink}`);
+  }
+
+  return lines.join("\n");
+}
+
+export function humanizeState(state: string): string {
+  const map: Record<string, string> = {
+    PAGE_FETCH_STATE_UNSPECIFIED: "not yet crawled",
+    ROBOTS_TXT_STATE_UNSPECIFIED: "not yet checked",
+    INDEXING_STATE_UNSPECIFIED: "not yet determined",
+  };
+  return map[state] ?? state;
+}
+
+export interface InspectionSummary {
+  url: string;
+  verdict: string;
+  coverageState: string;
+  pageFetchState: string;
+  robotsTxtState: string;
+  indexingState: string;
+  lastCrawlTime: string | null;
+  googleCanonical: string | null;
+  error: string | null;
+}
+
+export async function inspectSingle(url: string, siteUrl: string): Promise<InspectionSummary> {
+  try {
+    const r = await inspectUrl(url, siteUrl);
+    const idx = r.indexStatusResult;
+    return {
+      url,
+      verdict: idx.verdict,
+      coverageState: idx.coverageState,
+      pageFetchState: idx.pageFetchState,
+      robotsTxtState: idx.robotsTxtState,
+      indexingState: idx.indexingState,
+      lastCrawlTime: idx.lastCrawlTime ?? null,
+      googleCanonical: idx.googleCanonical ?? null,
+      error: null,
+    };
+  } catch (err) {
+    return {
+      url,
+      verdict: "ERROR",
+      coverageState: "ERROR",
+      pageFetchState: "ERROR",
+      robotsTxtState: "ERROR",
+      indexingState: "ERROR",
+      lastCrawlTime: null,
+      googleCanonical: null,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export async function runInspect(options: SearchOptions) {
+  const { site_url, url } = options;
+  if (!url) return textResult("Error: url is required for inspect.");
+  if (!site_url) return textResult("Error: site_url is required for inspect.");
+
+  try {
+    const result = await inspectUrl(url, site_url);
+    return textResult(formatInspection(url, site_url, result));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("PERMISSION_DENIED")) {
+      const domain = new URL(url).hostname;
+      return textResult(
+        [
+          `Error: Cannot inspect "${url}" — permission denied for property "${site_url}".`,
+          "",
+          "Possible causes:",
+          `  1. ${domain} is not a verified property in Google Search Console`,
+          `  2. The authenticated account does not have access to "${site_url}"`,
+          `  3. The property format is wrong — try "sc-domain:${domain}" or "https://${domain}/"`,
+          "",
+          "To verify a property: https://search.google.com/search-console",
+          "To check your auth: use the setup tool to verify credentials",
+        ].join("\n"),
+      );
+    }
+    return textResult(`Error inspecting URL: ${msg}`);
+  }
+}

package/src/tools/search/result.ts

@@ -0,0 +1,3 @@
+export function textResult(text: string) {
+  return { content: [{ type: "text" as const, text }] };
+}

package/src/tools/search/sample.ts

@@ -0,0 +1,110 @@
+import { listSitemaps } from "../../providers/gsc.js";
+import { type SearchOptions } from "./schema.js";
+import { humanizeState, type InspectionSummary, inspectSingle } from "./inspection.js";
+import { matchesCoverageFilter, formatSampleResults } from "./coverage.js";
+import { fetchSitemap, sampleUrls } from "./sitemap-sampling.js";
+import { textResult } from "./result.js";
+
+export async function runSample(options: SearchOptions) {
+  const { site_url, sitemap_url, sample_size, sample_strategy, filter } = options;
+  if (!site_url) return textResult("Error: site_url is required for sample.");
+
+  const count = sample_size ?? 5;
+  const strategy = sample_strategy ?? "random";
+
+  // Discover sitemap URL if not provided
+  let resolvedSitemapUrl = sitemap_url;
+  if (!resolvedSitemapUrl) {
+    const sitemaps = await listSitemaps(site_url);
+    if (sitemaps.length === 0) {
+      return textResult(`No sitemaps found for ${site_url} in GSC. Provide a sitemap_url directly.`);
+    }
+    const nonIndex = sitemaps.find((s) => !s.isSitemapsIndex);
+    resolvedSitemapUrl = (nonIndex ?? sitemaps[0]).path;
+  }
+
+  // Fetch and parse sitemap
+  let parsed = await fetchSitemap(resolvedSitemapUrl);
+
+  if (parsed.isSitemapIndex && parsed.childSitemaps.length > 0) {
+    const childUrl = parsed.childSitemaps[0];
+    parsed = await fetchSitemap(childUrl);
+    resolvedSitemapUrl = `${resolvedSitemapUrl} → ${childUrl}`;
+  }
+
+  if (parsed.urls.length === 0) {
+    return textResult(`Sitemap ${resolvedSitemapUrl} contains no URLs.`);
+  }
+
+  if (filter) {
+    // Filtered sample: inspect more URLs, return only matches
+    const scanLimit = Math.min(count * 5, 50, parsed.urls.length);
+    const pool = sampleUrls(parsed.urls, scanLimit, strategy);
+    const matched: InspectionSummary[] = [];
+    let scanned = 0;
+
+    for (const u of pool) {
+      const result = await inspectSingle(u, site_url);
+      scanned++;
+      if (matchesCoverageFilter(result, filter)) {
+        matched.push(result);
+        if (matched.length >= count) break;
+      }
+    }
+
+    if (matched.length === 0) {
+      return textResult(
+        [
+          `=== Filtered Sample: ${site_url} ===`,
+          `Sitemap: ${resolvedSitemapUrl} (${parsed.urls.length.toLocaleString()} URLs)`,
+          `Filter: ${filter}`,
+          `Scanned: ${scanned} | Matched: 0`,
+          "",
+          `No URLs matching "${filter}" found in ${scanned} inspected URLs.`,
+          "Try a larger sample_size or a different filter.",
+        ].join("\n"),
+      );
+    }
+
+    const lines: string[] = [
+      `=== Filtered Sample: ${site_url} ===`,
+      `Sitemap: ${resolvedSitemapUrl} (${parsed.urls.length.toLocaleString()} URLs)`,
+      `Filter: ${filter}`,
+      `Scanned: ${scanned} | Matched: ${matched.length}`,
+      "",
+      "--- Matching URLs ---",
+      "",
+    ];
+
+    for (let i = 0; i < matched.length; i++) {
+      const r = matched[i];
+      lines.push(`${i + 1}. ${r.url}`);
+      lines.push(`   Coverage: ${r.coverageState}`);
+      lines.push(`   Page fetch: ${humanizeState(r.pageFetchState)}`);
+      if (r.robotsTxtState !== "ALLOWED") lines.push(`   Robots.txt: ${humanizeState(r.robotsTxtState)}`);
+      if (r.indexingState !== "INDEXING_ALLOWED") lines.push(`   Indexing: ${humanizeState(r.indexingState)}`);
+      if (r.lastCrawlTime) lines.push(`   Last crawled: ${r.lastCrawlTime}`);
+      if (r.googleCanonical && r.googleCanonical !== r.url) {
+        lines.push(`   Google canonical: ${r.googleCanonical}`);
+      }
+      lines.push("");
+    }
+
+    if (matched.length < count && scanned >= scanLimit) {
+      lines.push(
+        `Found ${matched.length}/${count} requested — scanned ${scanned} URLs (limit ${scanLimit}). Increase sample_size for a wider scan.`,
+      );
+    }
+
+    return textResult(lines.join("\n"));
+  }
+
+  const sampled = sampleUrls(parsed.urls, count, strategy);
+
+  const results: InspectionSummary[] = [];
+  for (const u of sampled) {
+    results.push(await inspectSingle(u, site_url));
+  }
+
+  return textResult(formatSampleResults(site_url, resolvedSitemapUrl, parsed.urls.length, results));
+}