termsearch 0.3.0

package/src/fetch/document.js

@@ -0,0 +1,297 @@
+// URL fetcher + HTML to readable text extraction
+// Used by AI summary to fetch page content
+
+import { assertPublicUrl } from './ssrf-guard.js';
+
+const FETCH_MAX_BYTES = 180_000;
+
+function escapeRegExp(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function stripHtml(html) {
+  return html
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, ' ')
+    .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, ' ')
+    .replace(/<noscript\b[^>]*>[\s\S]*?<\/noscript>/gi, ' ')
+    // Preserve external links as "text [url]" for AI URL extraction
+    .replace(/<a\s[^>]*\bhref="(https?:\/\/[^"#?]{4,})"[^>]*>([\s\S]*?)<\/a>/gi, (_, url, inner) => {
+      const text = inner.replace(/<[^>]+>/g, '').trim();
+      return text ? `${text} [${url}]` : `[${url}]`;
+    })
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&nbsp;/gi, ' ')
+    .replace(/&amp;/gi, '&')
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;/gi, "'")
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+export function getMetaContent(html, attr, value) {
+  const re = new RegExp(`<meta\\s+[^>]*${attr}="${escapeRegExp(value)}"[^>]*content="([^"]+)"[^>]*>`, 'i');
+  return html.match(re)?.[1]?.trim() || '';
+}
+
+export function truncateSmart(text, limit = 12000) {
+  const clean = String(text || '').trim();
+  if (clean.length <= limit) return clean;
+  const headLen = Math.max(500, Math.floor(limit * 0.62));
+  const tailLen = Math.max(400, limit - headLen - 8);
+  return `${clean.slice(0, headLen)} … ${clean.slice(-tailLen)}`.trim();
+}
+
+export function extractTitle(html, fallbackUrl) {
+  const titleMatch = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+  if (titleMatch?.[1]) return stripHtml(titleMatch[1]).slice(0, 160);
+  return fallbackUrl;
+}
+
+function extractGithubReadable(parsedUrl, html) {
+  if (parsedUrl.hostname !== 'github.com') return null;
+  const seg = parsedUrl.pathname.split('/').filter(Boolean);
+  if (seg.length === 0) return null;
+
+  const title = extractTitle(html, parsedUrl.toString());
+  const metaDesc = getMetaContent(html, 'name', 'description') || getMetaContent(html, 'property', 'og:description');
+  const lines = [`GitHub page: ${parsedUrl.toString()}`, `Title: ${title}`];
+  if (metaDesc) lines.push(`Summary: ${stripHtml(metaDesc)}`);
+
+  if (seg.length === 1) {
+    const username = seg[0];
+    const repoRe = /<a\s+href="\/([^/"?#]+\/[^/"?#]+)"[^>]*itemprop="name codeRepository"[^>]*>([\s\S]*?)<\/a>/gi;
+    const repos = [];
+    let match;
+    while ((match = repoRe.exec(html)) !== null && repos.length < 12) {
+      const ownerRepo = String(match[1] || '').trim();
+      if (!ownerRepo.toLowerCase().startsWith(`${username.toLowerCase()}/`)) continue;
+      const repoName = stripHtml(match[2] || '').trim();
+      if (!repoName) continue;
+      const chunk = html.slice(match.index, match.index + 2200);
+      const descHtml = chunk.match(/itemprop="description"[^>]*>([\s\S]*?)<\/p>/i)?.[1] || '';
+      const starsChunk = chunk.match(new RegExp(`href="/${escapeRegExp(ownerRepo)}/stargazers"[\\s\\S]{0,180}<\\/a>`, 'i'))?.[0] || '';
+      const forksChunk = chunk.match(new RegExp(`href="/${escapeRegExp(ownerRepo)}/forks"[\\s\\S]{0,180}<\\/a>`, 'i'))?.[0] || '';
+      const stars = stripHtml(starsChunk).match(/(\d[\d.,kK]*)/)?.[1] || '';
+      const forks = stripHtml(forksChunk).match(/(\d[\d.,kK]*)/)?.[1] || '';
+      const desc = stripHtml(descHtml).slice(0, 180);
+      repos.push({ repo: repoName, url: `https://github.com/${ownerRepo}`, desc, stars, forks });
+    }
+    if (repos.length > 0) {
+      lines.push(`Repositories found: ${repos.length}`);
+      for (const r of repos) {
+        const meta = [r.stars ? `stars=${r.stars}` : '', r.forks ? `forks=${r.forks}` : ''].filter(Boolean).join(', ');
+        lines.push(`- ${r.repo}${r.desc ? ` — ${r.desc}` : ''}${meta ? ` (${meta})` : ''} [${r.url}]`);
+      }
+    }
+  }
+
+  if (seg.length >= 2) {
+    const ownerRepo = `${seg[0]}/${seg[1]}`;
+    const repoDesc = getMetaContent(html, 'property', 'og:description') || getMetaContent(html, 'name', 'description');
+    lines.push(`Repository: ${ownerRepo} [https://github.com/${ownerRepo}]`);
+    if (repoDesc) lines.push(`Repository summary: ${stripHtml(repoDesc)}`);
+  }
+
+  const content = truncateSmart(lines.join('\n'), 12000);
+  return content.length >= 80 ? content : null;
+}
+
+async function fetchGithubApiSummary(username, timeoutMs) {
+  const handle = String(username || '').trim();
+  if (!handle) return '';
+  const headers = { 'User-Agent': 'TermSearch/1.0', Accept: 'application/vnd.github+json' };
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), Math.min(timeoutMs, 9000));
+  try {
+    const [userRes, reposRes] = await Promise.all([
+      fetch(`https://api.github.com/users/${encodeURIComponent(handle)}`, { headers, signal: ac.signal }),
+      fetch(`https://api.github.com/users/${encodeURIComponent(handle)}/repos?sort=updated&per_page=12`, { headers, signal: ac.signal }),
+    ]);
+    let user = null;
+    let repos = [];
+    if (userRes.ok) user = await userRes.json();
+    if (reposRes.ok) { const d = await reposRes.json(); repos = Array.isArray(d) ? d : []; }
+    if (!user && repos.length === 0) return '';
+    const lines = ['GitHub API snapshot:'];
+    if (user) {
+      lines.push(`Profile: ${user.html_url || `https://github.com/${handle}`}`);
+      if (user.name) lines.push(`Name: ${user.name}`);
+      if (user.bio) lines.push(`Bio: ${String(user.bio).slice(0, 220)}`);
+      if (Number.isFinite(user.public_repos)) lines.push(`Public repos: ${user.public_repos}`);
+    }
+    if (repos.length > 0) {
+      lines.push(`Repositories (latest ${repos.length}):`);
+      for (const repo of repos) {
+        const parts = [];
+        if (repo.language) parts.push(`lang=${repo.language}`);
+        if (Number.isFinite(repo.stargazers_count)) parts.push(`stars=${repo.stargazers_count}`);
+        lines.push(`- ${repo.name}${repo.description ? ` — ${String(repo.description).slice(0, 180)}` : ''}${parts.length ? ` (${parts.join(', ')})` : ''} [${repo.html_url}]`);
+      }
+    }
+    return lines.join('\n');
+  } catch {
+    return '';
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Fetch a URL and return readable text content
+// docCache: optional cache instance to use (injected from engine.js)
+export async function fetchReadableDocument(rawUrl, { timeoutMs = 12000, docCache } = {}) {
+  const cacheKey = String(rawUrl || '').trim();
+  if (docCache) {
+    const cached = docCache.get(cacheKey);
+    if (cached) return cached;
+  }
+
+  const parsed = await assertPublicUrl(rawUrl);
+  // Note: AbortSignal.timeout() is broken with HTTPS in Node 24 — use manual AbortController
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  let response;
+  try {
+    response = await fetch(parsed.toString(), {
+      headers: {
+        'User-Agent': 'TermSearchFetch/1.0',
+        Accept: 'text/html, text/plain;q=0.9,*/*;q=0.5',
+      },
+      signal: ac.signal,
+      redirect: 'follow',
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (!response.ok) throw new Error(`Fetch failed: ${response.status}`);
+
+  const contentType = response.headers.get('content-type') || '';
+  if (!/text\/html|text\/plain|application\/xhtml\+xml/i.test(contentType)) {
+    throw new Error(`Unsupported content-type: ${contentType || 'unknown'}`);
+  }
+
+  const buffer = await response.arrayBuffer();
+  const bytes = Buffer.from(buffer).subarray(0, FETCH_MAX_BYTES);
+  const html = bytes.toString('utf8');
+  const githubContent = extractGithubReadable(parsed, html);
+  let content = githubContent || truncateSmart(stripHtml(html), 12000);
+
+  if (parsed.hostname === 'github.com') {
+    const seg = parsed.pathname.split('/').filter(Boolean);
+    if (seg.length === 1) {
+      const apiSummary = await fetchGithubApiSummary(seg[0], timeoutMs);
+      if (apiSummary) content = truncateSmart(`${content}\n\n${apiSummary}`.trim(), 12000);
+    }
+  }
+
+  if (!content) throw new Error('No readable content extracted.');
+
+  const result = { url: parsed.toString(), title: extractTitle(html, parsed.toString()), content, status: 'ok' };
+  if (docCache) docCache.set(cacheKey, result, 45 * 60 * 1000);
+  return result;
+}
+
+// Batch fetch multiple URLs in parallel
+export async function batchFetch(urls, { timeoutMs = 12000, docCache } = {}) {
+  return Promise.all(
+    urls.map((url) =>
+      fetchReadableDocument(url, { timeoutMs, docCache })
+        .then((doc) => ({ ...doc, url }))
+        .catch((e) => ({ url, status: 'error', error: e.message, content: '', title: url }))
+    )
+  );
+}
+
+// Scan a site homepage + a few relevant internal pages by query keywords
+export async function scanSitePages(baseUrl, query, maxPages = 4, { timeoutMs = 12000, docCache } = {}) {
+  const clampedMax = Math.min(Number(maxPages) || 4, 8);
+  let base;
+  try {
+    base = await assertPublicUrl(baseUrl);
+  } catch {
+    return [];
+  }
+
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  let html = '';
+  try {
+    const response = await fetch(base.toString(), {
+      headers: {
+        'User-Agent': 'TermSearchFetch/1.0',
+        Accept: 'text/html,*/*;q=0.5',
+      },
+      signal: ac.signal,
+      redirect: 'follow',
+    });
+    if (!response.ok) return [];
+    const buffer = await response.arrayBuffer();
+    html = Buffer.from(buffer).subarray(0, FETCH_MAX_BYTES).toString('utf8');
+  } catch {
+    return [];
+  } finally {
+    clearTimeout(timer);
+  }
+
+  const homepageDoc = {
+    url: base.toString(),
+    title: extractTitle(html, base.toString()),
+    content: truncateSmart(stripHtml(html), 12000),
+    status: 'ok',
+  };
+
+  const seen = new Set([base.toString().replace(/\/+$/, '')]);
+  const candidateUrls = [];
+  const linkRe = /href="(\/[^"#?]{2,}|https?:\/\/[^"#?]+)"/gi;
+  let match;
+  while ((match = linkRe.exec(html)) !== null && candidateUrls.length < 40) {
+    try {
+      const full = new URL(match[1], base.toString());
+      if (full.hostname !== base.hostname) continue;
+      if (/(login|signin|logout|register|account|cart|checkout|\.pdf|\.zip|\.exe|\.jpg|\.jpeg|\.png|\.gif|\.css|\.js)/i.test(full.pathname)) continue;
+      const normalized = `${full.origin}${full.pathname}`.replace(/\/+$/, '');
+      if (!normalized || seen.has(normalized)) continue;
+      seen.add(normalized);
+      candidateUrls.push(normalized);
+    } catch {
+      // ignore invalid links
+    }
+  }
+
+  const queryWords = String(query || '')
+    .toLowerCase()
+    .split(/\s+/)
+    .filter((w) => w.length > 2);
+
+  const toFetch = candidateUrls
+    .map((url) => {
+      let score = 0;
+      try {
+        const parsed = new URL(url);
+        score = queryWords.filter((w) => parsed.pathname.toLowerCase().includes(w)).length;
+      } catch {
+        // ignore parse failures
+      }
+      return { url, score };
+    })
+    .sort((a, b) => b.score - a.score)
+    .slice(0, Math.max(0, clampedMax - 1))
+    .map((entry) => entry.url);
+
+  const settled = await Promise.allSettled(
+    toFetch.map(async (url) => {
+      try {
+        const doc = await fetchReadableDocument(url, { timeoutMs, docCache });
+        return doc?.status === 'ok' && String(doc.content || '').length > 100 ? doc : null;
+      } catch {
+        return null;
+      }
+    })
+  );
+
+  const docs = settled
+    .filter((result) => result.status === 'fulfilled' && result.value)
+    .map((result) => result.value);
+
+  return [homepageDoc, ...docs];
+}

package/src/fetch/ssrf-guard.js

@@ -0,0 +1,40 @@
+// SSRF protection — validates URLs before fetching, blocks private/internal IPs
+
+import dns from 'dns/promises';
+import net from 'net';
+
+const PRIVATE_V4_PREFIXES = [
+  '10.', '172.16.', '172.17.', '172.18.', '172.19.', '172.20.', '172.21.',
+  '172.22.', '172.23.', '172.24.', '172.25.', '172.26.', '172.27.',
+  '172.28.', '172.29.', '172.30.', '172.31.',
+  '192.168.', '127.', '169.254.', '0.',
+];
+
+export function isPrivateIp(ip) {
+  if (!ip) return true;
+  if (net.isIPv6(ip)) {
+    return ip === '::1' || ip.startsWith('fc') || ip.startsWith('fd') || ip.startsWith('fe80');
+  }
+  return PRIVATE_V4_PREFIXES.some((prefix) => ip.startsWith(prefix));
+}
+
+export async function assertPublicUrl(rawUrl) {
+  let parsed;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    throw new Error('Invalid URL.');
+  }
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    throw new Error('Only http/https URLs are allowed.');
+  }
+  const hostname = parsed.hostname;
+  if (!hostname || hostname === 'localhost') {
+    throw new Error('Local addresses are not allowed.');
+  }
+  const records = await dns.lookup(hostname, { all: true });
+  if (!records.length || records.some((record) => isPrivateIp(record.address))) {
+    throw new Error('Private or internal targets are not allowed.');
+  }
+  return parsed;
+}

package/src/profiler/scanner.js

@@ -0,0 +1,212 @@
+// Profile scanner — ported from MmmSearch
+// Supports: GitHub, Bluesky, Reddit, Twitter/X, Instagram, YouTube, LinkedIn, TikTok, Telegram, Facebook
+
+import { tryNitterInstances, fetchInstagramProfile, fetchYouTubeProfile, fetchFacebookPage, fetchLinkedInProfile, fetchTikTokProfile, fetchTelegramProfile } from '../social/scrapers.js';
+import { fetchBlueskyActors } from '../social/search.js';
+
+export const PROFILER_PLATFORMS = new Set([
+  'github', 'bluesky', 'reddit', 'twitter', 'instagram',
+  'linkedin', 'telegram', 'youtube', 'facebook', 'tiktok', 'auto',
+]);
+
+// ─── URL/handle detection ─────────────────────────────────────────────────────
+
+export function detectProfileTarget(raw) {
+  const q = (raw || '').trim();
+  let m;
+  if ((m = q.match(/github\.com\/([A-Za-z0-9_-]+)/i)))                               return { platform: 'github',    handle: m[1], url: `https://github.com/${m[1]}` };
+  if ((m = q.match(/bsky\.app\/profile\/([A-Za-z0-9._:-]+)/i)))                       return { platform: 'bluesky',   handle: m[1], url: `https://bsky.app/profile/${m[1]}` };
+  if ((m = q.match(/reddit\.com\/u(?:ser)?\/([A-Za-z0-9_-]+)/i)))                     return { platform: 'reddit',    handle: m[1], url: `https://reddit.com/u/${m[1]}` };
+  if ((m = q.match(/(?:t\.me|telegram\.me)\/([A-Za-z0-9_]{3,})/i)))                   return { platform: 'telegram',  handle: m[1], url: `https://t.me/${m[1]}` };
+  if ((m = q.match(/(?:twitter|x)\.com\/([A-Za-z0-9_]+)(?:\/|$)/i)))                 return { platform: 'twitter',   handle: m[1], url: `https://x.com/${m[1]}` };
+  if ((m = q.match(/youtube\.com\/@([A-Za-z0-9._-]+)(?:\/|$|\?|#)/i)))               return { platform: 'youtube',   handle: m[1], url: `https://www.youtube.com/@${m[1]}` };
+  if ((m = q.match(/youtube\.com\/(?:channel|c|user)\/([A-Za-z0-9._-]+)(?:\/|$)/i))) return { platform: 'youtube',   handle: m[1], url: `https://www.youtube.com/channel/${m[1]}` };
+  if ((m = q.match(/instagram\.com\/([A-Za-z0-9_.]+)(?:\/|$)/i)))                     return { platform: 'instagram', handle: m[1], url: `https://instagram.com/${m[1]}` };
+  if ((m = q.match(/linkedin\.com\/in\/([A-Za-z0-9_-]+)(?:\/|$)/i)))                 return { platform: 'linkedin',  handle: m[1], url: `https://linkedin.com/in/${m[1]}` };
+  if ((m = q.match(/(?:facebook|fb)\.com\/([A-Za-z0-9_.]+)(?:\/|$)/i)))              return { platform: 'facebook',  handle: m[1], url: `https://www.facebook.com/${m[1]}` };
+  if ((m = q.match(/tiktok\.com\/@([A-Za-z0-9_.]+)(?:\/|$)/i)))                       return { platform: 'tiktok',   handle: m[1], url: `https://www.tiktok.com/@${m[1]}` };
+  if ((m = q.match(/^@([A-Za-z0-9_.][A-Za-z0-9_.-]{0,58})$/)))                        return { platform: 'auto',     handle: m[1], url: null };
+  return null;
+}
+
+// ─── GitHub ───────────────────────────────────────────────────────────────────
+
+async function ghFetch(path) {
+  const ac = new AbortController();
+  const t = setTimeout(() => ac.abort(), 8000);
+  try {
+    const hdrs = { 'User-Agent': 'TermSearch/1.0', Accept: 'application/vnd.github.v3+json' };
+    const token = process.env.TERMSEARCH_GITHUB_TOKEN;
+    if (token) hdrs['Authorization'] = `token ${token}`;
+    const r = await fetch(`https://api.github.com${path}`, { headers: hdrs, signal: ac.signal });
+    if (!r.ok) return null;
+    return r.json();
+  } catch { return null; }
+  finally { clearTimeout(t); }
+}
+
+export async function fetchGitHubProfileData(handle) {
+  const [user, repos] = await Promise.all([
+    ghFetch(`/users/${encodeURIComponent(handle)}`),
+    ghFetch(`/users/${encodeURIComponent(handle)}/repos?per_page=100&sort=updated`),
+  ]);
+  if (!user || user.message) return null;
+  const sortedRepos = (Array.isArray(repos) ? repos : [])
+    .sort((a, b) => {
+      const s = Number(b.stargazers_count || 0) - Number(a.stargazers_count || 0);
+      if (s !== 0) return s;
+      const f = Number(b.forks_count || 0) - Number(a.forks_count || 0);
+      if (f !== 0) return f;
+      return new Date(b.updated_at || 0) - new Date(a.updated_at || 0);
+    })
+    .slice(0, 8);
+  return {
+    platform: 'github', handle: user.login, name: user.name || user.login,
+    bio: user.bio || null, avatar: user.avatar_url, url: user.html_url,
+    followers: user.followers, following: user.following,
+    publicRepos: user.public_repos, company: user.company || null,
+    location: user.location || null, blog: user.blog || null,
+    createdAt: user.created_at,
+    topRepos: sortedRepos.map((r) => ({
+      name: r.name, stars: r.stargazers_count, forks: r.forks_count,
+      lang: r.language || null, description: (r.description || '').slice(0, 180),
+      url: r.html_url,
+    })),
+  };
+}
+
+// ─── Bluesky ──────────────────────────────────────────────────────────────────
+
+export async function fetchBlueskyProfileData(handle) {
+  const ac = new AbortController();
+  const t = setTimeout(() => ac.abort(), 8000);
+  try {
+    const r = await fetch(`https://api.bsky.app/xrpc/app.bsky.actor.getProfile?actor=${encodeURIComponent(handle)}`, {
+      headers: { 'User-Agent': 'TermSearch/1.0' }, signal: ac.signal,
+    });
+    if (!r.ok) return null;
+    const d = await r.json();
+    if (!d.handle) return null;
+    return {
+      platform: 'bluesky', handle: d.handle, name: d.displayName || d.handle,
+      bio: d.description || null, avatar: d.avatar || null,
+      url: `https://bsky.app/profile/${d.handle}`,
+      followers: d.followersCount, following: d.followsCount, postsCount: d.postsCount,
+      createdAt: d.indexedAt || null,
+    };
+  } catch { return null; }
+  finally { clearTimeout(t); }
+}
+
+// ─── Reddit ───────────────────────────────────────────────────────────────────
+
+export async function fetchRedditProfileData(handle) {
+  const ac = new AbortController();
+  const t = setTimeout(() => ac.abort(), 8000);
+  try {
+    const r = await fetch(`https://www.reddit.com/user/${encodeURIComponent(handle)}/about.json`, {
+      headers: { 'User-Agent': 'TermSearch/1.0 (by /u/termsearch)', Accept: 'application/json' },
+      signal: ac.signal,
+    });
+    if (!r.ok) return null;
+    const d = await r.json();
+    const u = d?.data;
+    if (!u || u.is_suspended) return null;
+    return {
+      platform: 'reddit', handle: u.name, name: u.name,
+      bio: u.subreddit?.public_description || null,
+      avatar: u.icon_img ? u.icon_img.split('?')[0] : null,
+      url: `https://reddit.com/u/${u.name}`,
+      karma: u.total_karma, linkKarma: u.link_karma, commentKarma: u.comment_karma,
+      createdAt: new Date(u.created_utc * 1000).toISOString(),
+    };
+  } catch { return null; }
+  finally { clearTimeout(t); }
+}
+
+// ─── Similar profiles ─────────────────────────────────────────────────────────
+
+async function findSimilarGitHub(profile) {
+  const langs = [...new Set((profile.topRepos || []).map((r) => r.lang).filter(Boolean))].slice(0, 1);
+  const minF  = Math.max(5, Math.floor((profile.followers || 100) * 0.15));
+  const q     = langs.length > 0 ? `language:${langs[0]} followers:>${minF} repos:>2` : `followers:>${minF} repos:>3`;
+  const data  = await ghFetch(`/search/users?q=${encodeURIComponent(q)}&per_page=8&sort=followers`);
+  return (data?.items || [])
+    .filter((u) => u.login.toLowerCase() !== profile.handle.toLowerCase())
+    .slice(0, 6)
+    .map((u) => ({ platform: 'github', handle: u.login, name: u.login, avatar: u.avatar_url, url: u.html_url }));
+}
+
+async function findSimilarBluesky(profile) {
+  const terms  = (profile.bio || profile.name || '').split(/\s+/).slice(0, 4).join(' ');
+  if (!terms.trim()) return [];
+  const actors = await fetchBlueskyActors(terms, 8);
+  return actors
+    .filter((a) => a.handle !== profile.handle)
+    .slice(0, 6)
+    .map((a) => ({
+      platform: 'bluesky', handle: a.handle,
+      name: (a.title || '').replace(/ \(@.*\)$/, '') || a.handle,
+      bio: a.snippet || null, url: a.url,
+    }));
+}
+
+// ─── Main scan ────────────────────────────────────────────────────────────────
+
+export async function scanProfile(target) {
+  const { platform, handle, url } = target;
+  let profile = null;
+  let similar = [];
+
+  switch (platform) {
+    case 'github':
+      profile = await fetchGitHubProfileData(handle);
+      if (profile) similar = await findSimilarGitHub(profile).catch(() => []);
+      break;
+    case 'bluesky':
+      profile = await fetchBlueskyProfileData(handle);
+      if (profile) similar = await findSimilarBluesky(profile).catch(() => []);
+      break;
+    case 'reddit':
+      profile = await fetchRedditProfileData(handle);
+      break;
+    case 'twitter':
+      profile = await tryNitterInstances(handle);
+      break;
+    case 'instagram':
+      profile = await fetchInstagramProfile(handle);
+      break;
+    case 'youtube':
+      profile = await fetchYouTubeProfile(handle, url);
+      break;
+    case 'facebook':
+      profile = url ? await fetchFacebookPage(url, handle) : null;
+      break;
+    case 'linkedin':
+      profile = await fetchLinkedInProfile(handle);
+      break;
+    case 'tiktok':
+      profile = await fetchTikTokProfile(handle);
+      break;
+    case 'telegram':
+      profile = await fetchTelegramProfile(handle);
+      break;
+    case 'auto': {
+      // Try platforms in order for @handle
+      const attempts = [
+        () => fetchBlueskyProfileData(handle),
+        () => fetchGitHubProfileData(handle),
+        () => fetchRedditProfileData(handle),
+        () => tryNitterInstances(handle),
+        () => fetchTelegramProfile(handle),
+      ];
+      for (const attempt of attempts) {
+        profile = await attempt().catch(() => null);
+        if (profile) break;
+      }
+      break;
+    }
+  }
+
+  return { target, profile: profile || null, similar };
+}

package/src/search/cache.js

@@ -0,0 +1,119 @@
+// Tiered cache: L1 in-process RAM + L2 disk (persistent across restarts)
+// L1: hot-set in RAM, bounded, lost on restart (fast Map with LRU eviction)
+// L2: disk JSON files, larger budget, survives restarts
+// Read path: L1 hit → return; L2 hit → promote to L1 (remaining TTL) → return
+// Write path: write to both L1 and L2 (async disk write, non-blocking)
+
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+
+// L1: in-process Map with TTL + LRU eviction
+export function makeCache(maxSize) {
+  const store = new Map();
+  return {
+    get(key) {
+      const entry = store.get(key);
+      if (!entry) return undefined;
+      if (Date.now() > entry.expires) { store.delete(key); return undefined; }
+      return entry.value;
+    },
+    set(key, value, ttl) {
+      if (store.size >= maxSize) store.delete(store.keys().next().value);
+      store.set(key, { value, expires: Date.now() + ttl });
+    },
+  };
+}
+
+function _hashKey(key) {
+  return crypto.createHash('sha1').update(key).digest('hex');
+}
+
+function _diskEvict(dir, maxEntries, maxBytes) {
+  fs.readdir(dir, (err, files) => {
+    if (err) return;
+    const jsonFiles = files.filter((f) => f.endsWith('.json'));
+    if (!jsonFiles.length) return;
+    const stats = [];
+    let pending = jsonFiles.length;
+    for (const f of jsonFiles) {
+      const fp = path.join(dir, f);
+      fs.stat(fp, (statErr, st) => {
+        if (!statErr) stats.push({ fp, mtime: st.mtimeMs, size: st.size });
+        if (--pending > 0) return;
+        stats.sort((a, b) => a.mtime - b.mtime); // oldest first
+        let totalBytes = stats.reduce((s, e) => s + e.size, 0);
+        const now = Date.now();
+        const alive = [];
+        for (const s of stats) {
+          try {
+            const { expires } = JSON.parse(fs.readFileSync(s.fp, 'utf8'));
+            if (now > expires) { fs.unlink(s.fp, () => {}); totalBytes -= s.size; }
+            else alive.push(s);
+          } catch { fs.unlink(s.fp, () => {}); }
+        }
+        while (alive.length > maxEntries || totalBytes > maxBytes) {
+          const oldest = alive.shift();
+          if (!oldest) break;
+          totalBytes -= oldest.size;
+          fs.unlink(oldest.fp, () => {});
+        }
+      });
+    }
+  });
+}
+
+// L2: disk cache — sync read, async write (non-blocking fire-and-forget)
+export function makeDiskCache(dir, maxEntries, maxBytes) {
+  try { fs.mkdirSync(dir, { recursive: true }); } catch { /* ignore */ }
+  let evictTimer = null;
+  return {
+    get(key) {
+      const fp = path.join(dir, _hashKey(key) + '.json');
+      try {
+        const { value, expires } = JSON.parse(fs.readFileSync(fp, 'utf8'));
+        if (Date.now() > expires) { fs.unlink(fp, () => {}); return undefined; }
+        return { value, remainingTtl: expires - Date.now() };
+      } catch { return undefined; }
+    },
+    set(key, value, ttl) {
+      const fp = path.join(dir, _hashKey(key) + '.json');
+      fs.writeFile(fp, JSON.stringify({ value, expires: Date.now() + ttl }), (err) => {
+        if (err) console.warn('[disk-cache] write error:', err.message);
+      });
+      if (!evictTimer) {
+        evictTimer = setTimeout(() => { evictTimer = null; _diskEvict(dir, maxEntries, maxBytes); }, 15_000);
+        evictTimer.unref?.();
+      }
+    },
+  };
+}
+
+// Tiered cache: L1 (RAM) + L2 (disk). Same get/set API as makeCache.
+export function makeTieredCache(l1Max, diskDir, diskMaxEntries, diskMaxBytes) {
+  const l1 = makeCache(l1Max);
+  const l2 = makeDiskCache(diskDir, diskMaxEntries, diskMaxBytes);
+  const L1_PROMO_CAP = 15 * 60 * 1000;
+  return {
+    get(key) {
+      const v = l1.get(key);
+      if (v !== undefined) return v;
+      const d = l2.get(key);
+      if (d !== undefined) {
+        l1.set(key, d.value, Math.min(d.remainingTtl, L1_PROMO_CAP));
+        return d.value;
+      }
+      return undefined;
+    },
+    set(key, value, ttl) {
+      l1.set(key, value, ttl);
+      l2.set(key, value, ttl);
+    },
+  };
+}
+
+// Build a cache key for search queries
+export function searchCacheKey(query, lang, safe, providerList, tier, category = 'web', page = 1) {
+  const sorted = [...providerList].sort().join(',');
+  return `${tier}:${lang}:${safe}:${sorted}:${category}:p${page}:${query.toLowerCase().trim()}`;
+}