@rankcli/agent-runtime 0.0.1

package/dist/chunk-YNZYHEYM.mjs

@@ -0,0 +1,774 @@
+var __defProp = Object.defineProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/utils/http.ts
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_USER_AGENT = "RankCLI/1.0 (+https://rankcli.dev)";
+function createTimeoutController(timeout) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  return { controller, timeoutId };
+}
+function headersToObject(headers) {
+  const obj = {};
+  headers.forEach((value, key) => {
+    obj[key.toLowerCase()] = value;
+  });
+  return obj;
+}
+async function httpGet(url, config = {}) {
+  const {
+    headers = {},
+    timeout = DEFAULT_TIMEOUT,
+    validateStatus = (status) => status >= 200 && status < 300,
+    maxRedirects = 5,
+    params
+  } = config;
+  let finalUrl = url;
+  if (params) {
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      searchParams.append(key, String(value));
+    }
+    const separator = url.includes("?") ? "&" : "?";
+    finalUrl = `${url}${separator}${searchParams.toString()}`;
+  }
+  const { controller, timeoutId } = createTimeoutController(timeout);
+  try {
+    const response = await fetch(finalUrl, {
+      method: "GET",
+      headers: {
+        "User-Agent": DEFAULT_USER_AGENT,
+        ...headers
+      },
+      signal: controller.signal,
+      redirect: maxRedirects > 0 ? "follow" : "manual"
+    });
+    clearTimeout(timeoutId);
+    const contentType = response.headers.get("content-type") || "";
+    let data;
+    if (contentType.includes("application/json")) {
+      data = await response.json();
+    } else {
+      data = await response.text();
+    }
+    if (!validateStatus(response.status)) {
+      const error = new Error(`Request failed with status ${response.status}`);
+      error.response = {
+        data,
+        status: response.status,
+        statusText: response.statusText,
+        headers: headersToObject(response.headers)
+      };
+      throw error;
+    }
+    return {
+      data,
+      status: response.status,
+      statusText: response.statusText,
+      headers: headersToObject(response.headers)
+    };
+  } catch (error) {
+    clearTimeout(timeoutId);
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new Error(`Request timeout after ${timeout}ms`);
+    }
+    throw error;
+  }
+}
+async function httpHead(url, config = {}) {
+  const {
+    headers = {},
+    timeout = DEFAULT_TIMEOUT,
+    validateStatus = (status) => status >= 200 && status < 300,
+    maxRedirects = 5
+  } = config;
+  const { controller, timeoutId } = createTimeoutController(timeout);
+  try {
+    const response = await fetch(url, {
+      method: "HEAD",
+      headers: {
+        "User-Agent": DEFAULT_USER_AGENT,
+        ...headers
+      },
+      signal: controller.signal,
+      redirect: maxRedirects > 0 ? "follow" : "manual"
+    });
+    clearTimeout(timeoutId);
+    if (!validateStatus(response.status)) {
+      const error = new Error(`Request failed with status ${response.status}`);
+      error.response = {
+        data: null,
+        status: response.status,
+        statusText: response.statusText,
+        headers: headersToObject(response.headers)
+      };
+      throw error;
+    }
+    return {
+      data: null,
+      status: response.status,
+      statusText: response.statusText,
+      headers: headersToObject(response.headers)
+    };
+  } catch (error) {
+    clearTimeout(timeoutId);
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new Error(`Request timeout after ${timeout}ms`);
+    }
+    throw error;
+  }
+}
+async function httpPost(url, data, config = {}) {
+  const {
+    headers = {},
+    timeout = DEFAULT_TIMEOUT,
+    validateStatus = (status) => status >= 200 && status < 300,
+    auth
+  } = config;
+  const { controller, timeoutId } = createTimeoutController(timeout);
+  const requestHeaders = {
+    "User-Agent": DEFAULT_USER_AGENT,
+    "Content-Type": "application/json",
+    ...headers
+  };
+  if (auth) {
+    const credentials = btoa(`${auth.username}:${auth.password}`);
+    requestHeaders["Authorization"] = `Basic ${credentials}`;
+  }
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: requestHeaders,
+      body: data ? JSON.stringify(data) : void 0,
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    const contentType = response.headers.get("content-type") || "";
+    let responseData;
+    if (contentType.includes("application/json")) {
+      responseData = await response.json();
+    } else {
+      responseData = await response.text();
+    }
+    if (!validateStatus(response.status)) {
+      const error = new Error(`Request failed with status ${response.status}`);
+      error.response = {
+        data: responseData,
+        status: response.status,
+        statusText: response.statusText,
+        headers: headersToObject(response.headers)
+      };
+      throw error;
+    }
+    return {
+      data: responseData,
+      status: response.status,
+      statusText: response.statusText,
+      headers: headersToObject(response.headers)
+    };
+  } catch (error) {
+    clearTimeout(timeoutId);
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new Error(`Request timeout after ${timeout}ms`);
+    }
+    throw error;
+  }
+}
+
+// src/tools/crawl.ts
+import * as cheerio from "cheerio";
+async function crawlUrl(params) {
+  const { url } = params;
+  try {
+    const start = Date.now();
+    const response = await httpGet(url, {
+      timeout: 3e4,
+      validateStatus: () => true
+    });
+    const loadTime = Date.now() - start;
+    const result = {
+      url,
+      html: response.data,
+      statusCode: response.status,
+      headers: response.headers,
+      loadTime
+    };
+    return { success: true, data: result };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error crawling URL"
+    };
+  }
+}
+async function extractMeta(params) {
+  const { html, url } = params;
+  try {
+    const $ = cheerio.load(html);
+    const meta = {
+      title: $("title").text().trim() || void 0,
+      description: $('meta[name="description"]').attr("content")?.trim(),
+      canonical: $('link[rel="canonical"]').attr("href"),
+      robots: $('meta[name="robots"]').attr("content"),
+      viewport: $('meta[name="viewport"]').attr("content"),
+      charset: $("meta[charset]").attr("charset") || $('meta[http-equiv="Content-Type"]').attr("content"),
+      openGraph: {
+        title: $('meta[property="og:title"]').attr("content"),
+        description: $('meta[property="og:description"]').attr("content"),
+        image: $('meta[property="og:image"]').attr("content"),
+        url: $('meta[property="og:url"]').attr("content"),
+        type: $('meta[property="og:type"]').attr("content"),
+        siteName: $('meta[property="og:site_name"]').attr("content")
+      },
+      twitter: {
+        card: $('meta[name="twitter:card"]').attr("content"),
+        title: $('meta[name="twitter:title"]').attr("content"),
+        description: $('meta[name="twitter:description"]').attr("content"),
+        image: $('meta[name="twitter:image"]').attr("content"),
+        site: $('meta[name="twitter:site"]').attr("content")
+      },
+      other: {}
+    };
+    $("meta").each((_, el) => {
+      const name = $(el).attr("name") || $(el).attr("property");
+      const content = $(el).attr("content");
+      if (name && content && !name.startsWith("og:") && !name.startsWith("twitter:")) {
+        if (!["description", "robots", "viewport"].includes(name)) {
+          meta.other[name] = content;
+        }
+      }
+    });
+    return { success: true, data: meta };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Error extracting meta"
+    };
+  }
+}
+async function analyzeHeadings(params) {
+  const { html } = params;
+  try {
+    const $ = cheerio.load(html);
+    const headings = [];
+    $("h1, h2, h3, h4, h5, h6").each((_, el) => {
+      const tag = el.tagName.toLowerCase();
+      headings.push({
+        tag,
+        text: $(el).text().trim(),
+        level: parseInt(tag.charAt(1), 10)
+      });
+    });
+    return { success: true, data: headings };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Error analyzing headings"
+    };
+  }
+}
+async function extractImages(params) {
+  const { html } = params;
+  try {
+    const $ = cheerio.load(html);
+    const images = [];
+    $("img").each((_, el) => {
+      images.push({
+        src: $(el).attr("src") || "",
+        alt: $(el).attr("alt") || null,
+        width: $(el).attr("width"),
+        height: $(el).attr("height"),
+        loading: $(el).attr("loading")
+      });
+    });
+    return { success: true, data: images };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Error extracting images"
+    };
+  }
+}
+async function extractLinks(params) {
+  const { html, baseUrl } = params;
+  try {
+    const $ = cheerio.load(html);
+    const links = [];
+    const baseHostname = new URL(baseUrl).hostname;
+    $("a[href]").each((_, el) => {
+      const href = $(el).attr("href") || "";
+      const rel = $(el).attr("rel") || "";
+      let isInternal = false;
+      try {
+        if (href.startsWith("/") || href.startsWith("#")) {
+          isInternal = true;
+        } else {
+          const linkHostname = new URL(href).hostname;
+          isInternal = linkHostname === baseHostname;
+        }
+      } catch {
+        isInternal = true;
+      }
+      links.push({
+        href,
+        text: $(el).text().trim(),
+        isInternal,
+        isNofollow: rel.includes("nofollow")
+      });
+    });
+    return { success: true, data: links };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Error extracting links"
+    };
+  }
+}
+async function extractSchema(params) {
+  const { html } = params;
+  try {
+    const $ = cheerio.load(html);
+    const schemas = [];
+    $('script[type="application/ld+json"]').each((_, el) => {
+      try {
+        const content = $(el).html();
+        if (content) {
+          const data = JSON.parse(content);
+          schemas.push({
+            type: data["@type"] || "Unknown",
+            data
+          });
+        }
+      } catch {
+      }
+    });
+    return { success: true, data: schemas };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Error extracting schema"
+    };
+  }
+}
+async function checkRobots(params) {
+  try {
+    const baseUrl = new URL(params.url);
+    const robotsUrl = `${baseUrl.protocol}//${baseUrl.host}/robots.txt`;
+    const response = await httpGet(robotsUrl, {
+      timeout: 1e4,
+      validateStatus: () => true
+    });
+    if (response.status === 200) {
+      return {
+        success: true,
+        data: {
+          exists: true,
+          content: response.data,
+          url: robotsUrl
+        }
+      };
+    }
+    return {
+      success: true,
+      data: {
+        exists: false,
+        url: robotsUrl
+      }
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Error checking robots.txt"
+    };
+  }
+}
+async function checkSitemap(params) {
+  try {
+    const baseUrl = new URL(params.url);
+    const sitemapUrls = [
+      `${baseUrl.protocol}//${baseUrl.host}/sitemap.xml`,
+      `${baseUrl.protocol}//${baseUrl.host}/sitemap_index.xml`,
+      `${baseUrl.protocol}//${baseUrl.host}/sitemap/sitemap.xml`
+    ];
+    for (const sitemapUrl of sitemapUrls) {
+      try {
+        const response = await httpGet(sitemapUrl, {
+          timeout: 1e4
+        });
+        if (response.status === 200 && response.data.includes("<?xml")) {
+          const $ = cheerio.load(response.data, { xmlMode: true });
+          const urlCount = $("url").length || $("sitemap").length;
+          return {
+            success: true,
+            data: {
+              exists: true,
+              url: sitemapUrl,
+              urlCount,
+              content: response.data.substring(0, 2e3)
+              // First 2KB
+            }
+          };
+        }
+      } catch {
+      }
+    }
+    return {
+      success: true,
+      data: {
+        exists: false
+      }
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Error checking sitemap"
+    };
+  }
+}
+
+// src/tools/analyzer.ts
+async function analyzeUrl(params) {
+  const { url } = params;
+  const issues = [];
+  try {
+    const crawlResult = await crawlUrl({ url });
+    if (!crawlResult.success || !crawlResult.data) {
+      return { success: false, error: `Failed to crawl URL: ${crawlResult.error}` };
+    }
+    const { html, statusCode, loadTime } = crawlResult.data;
+    if (statusCode !== 200) {
+      issues.push({
+        severity: "critical",
+        category: "technical",
+        code: "HTTP_ERROR",
+        message: `Page returned HTTP ${statusCode}`,
+        impact: "Search engines cannot index pages that return error codes"
+      });
+    }
+    const metaResult = await extractMeta({ html, url });
+    if (metaResult.success && metaResult.data) {
+      const meta = metaResult.data;
+      analyzeMeta(meta, url, issues);
+    }
+    const headingsResult = await analyzeHeadings({ html });
+    if (headingsResult.success && headingsResult.data) {
+      const headings = headingsResult.data;
+      analyzeHeadingStructure(headings, issues);
+    }
+    const imagesResult = await extractImages({ html });
+    if (imagesResult.success && imagesResult.data) {
+      const images = imagesResult.data;
+      analyzeImages(images, issues);
+    }
+    const schemaResult = await extractSchema({ html });
+    if (schemaResult.success) {
+      const schemas = schemaResult.data;
+      if (!schemas || schemas.length === 0) {
+        issues.push({
+          severity: "warning",
+          category: "schema",
+          code: "MISSING_SCHEMA",
+          message: "No JSON-LD structured data found",
+          impact: "Missing rich snippets in search results. Add Schema.org markup for your content type."
+        });
+      }
+    }
+    const robotsResult = await checkRobots({ url });
+    if (robotsResult.success) {
+      const robots = robotsResult.data;
+      if (!robots.exists) {
+        issues.push({
+          severity: "warning",
+          category: "technical",
+          code: "MISSING_ROBOTS",
+          message: "No robots.txt file found",
+          impact: "Provide crawling instructions to search engines with robots.txt"
+        });
+      }
+    }
+    const sitemapResult = await checkSitemap({ url });
+    if (sitemapResult.success) {
+      const sitemap = sitemapResult.data;
+      if (!sitemap.exists) {
+        issues.push({
+          severity: "warning",
+          category: "technical",
+          code: "MISSING_SITEMAP",
+          message: "No sitemap.xml found",
+          impact: "Sitemap helps search engines discover and index all your pages"
+        });
+      }
+    }
+    if (loadTime > 3e3) {
+      issues.push({
+        severity: loadTime > 5e3 ? "critical" : "warning",
+        category: "performance",
+        code: "SLOW_LOAD_TIME",
+        message: `Page load time is ${(loadTime / 1e3).toFixed(1)}s`,
+        impact: "Slow pages hurt user experience and search rankings. Target <2.5s LCP."
+      });
+    }
+    const score = calculateScore(issues);
+    const result = {
+      url,
+      score,
+      issues,
+      recommendations: generateRecommendations(issues)
+    };
+    return { success: true, data: result };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Analysis failed"
+    };
+  }
+}
+function analyzeMeta(meta, url, issues) {
+  if (!meta.title) {
+    issues.push({
+      severity: "critical",
+      category: "meta",
+      code: "MISSING_TITLE",
+      message: "Missing title tag",
+      impact: "Title is the most important on-page SEO element. Every page needs a unique title.",
+      fix: {
+        file: "index.html",
+        before: null,
+        after: "<title>Your Page Title - Brand Name</title>"
+      }
+    });
+  } else if (meta.title.length < 30) {
+    issues.push({
+      severity: "warning",
+      category: "meta",
+      code: "TITLE_TOO_SHORT",
+      message: `Title too short (${meta.title.length} chars)`,
+      impact: "Longer titles provide more context. Aim for 50-60 characters.",
+      element: meta.title
+    });
+  } else if (meta.title.length > 60) {
+    issues.push({
+      severity: "warning",
+      category: "meta",
+      code: "TITLE_TOO_LONG",
+      message: `Title too long (${meta.title.length} chars)`,
+      impact: "Titles over 60 characters get truncated in search results.",
+      element: meta.title.substring(0, 60) + "..."
+    });
+  }
+  if (!meta.description) {
+    issues.push({
+      severity: "critical",
+      category: "meta",
+      code: "MISSING_META_DESC",
+      message: "Missing meta description",
+      impact: "Meta description appears in search results and affects click-through rate.",
+      fix: {
+        file: "index.html",
+        before: null,
+        after: '<meta name="description" content="A compelling description of your page in 150-160 characters." />'
+      }
+    });
+  } else if (meta.description.length < 120) {
+    issues.push({
+      severity: "warning",
+      category: "meta",
+      code: "META_DESC_TOO_SHORT",
+      message: `Meta description too short (${meta.description.length} chars)`,
+      impact: "Aim for 150-160 characters for optimal display in search results."
+    });
+  } else if (meta.description.length > 160) {
+    issues.push({
+      severity: "info",
+      category: "meta",
+      code: "META_DESC_TOO_LONG",
+      message: `Meta description may be truncated (${meta.description.length} chars)`,
+      impact: "Descriptions over 160 characters may be cut off in search results."
+    });
+  }
+  if (!meta.canonical) {
+    issues.push({
+      severity: "warning",
+      category: "technical",
+      code: "MISSING_CANONICAL",
+      message: "No canonical URL specified",
+      impact: "Canonical tags prevent duplicate content issues.",
+      fix: {
+        file: "index.html",
+        before: null,
+        after: `<link rel="canonical" href="${url}" />`
+      }
+    });
+  }
+  if (!meta.viewport) {
+    issues.push({
+      severity: "critical",
+      category: "technical",
+      code: "MISSING_VIEWPORT",
+      message: "Missing viewport meta tag",
+      impact: "Required for mobile-friendly pages. Google uses mobile-first indexing.",
+      fix: {
+        file: "index.html",
+        before: null,
+        after: '<meta name="viewport" content="width=device-width, initial-scale=1" />'
+      }
+    });
+  }
+  const missingOG = [];
+  if (!meta.openGraph.title) missingOG.push("og:title");
+  if (!meta.openGraph.description) missingOG.push("og:description");
+  if (!meta.openGraph.image) missingOG.push("og:image");
+  if (missingOG.length > 0) {
+    issues.push({
+      severity: "warning",
+      category: "social",
+      code: "MISSING_OG_TAGS",
+      message: `Missing Open Graph tags: ${missingOG.join(", ")}`,
+      impact: "Open Graph tags control how your page appears when shared on social media."
+    });
+  }
+  if (!meta.twitter.card) {
+    issues.push({
+      severity: "info",
+      category: "social",
+      code: "MISSING_TWITTER_CARD",
+      message: "Missing Twitter Card meta tags",
+      impact: "Twitter/X cards improve visibility when your content is shared."
+    });
+  }
+}
+function analyzeHeadingStructure(headings, issues) {
+  const h1s = headings.filter((h) => h.level === 1);
+  if (h1s.length === 0) {
+    issues.push({
+      severity: "critical",
+      category: "content",
+      code: "MISSING_H1",
+      message: "No H1 heading found",
+      impact: "Every page should have exactly one H1 that describes the main content."
+    });
+  } else if (h1s.length > 1) {
+    issues.push({
+      severity: "warning",
+      category: "content",
+      code: "MULTIPLE_H1",
+      message: `Multiple H1 headings found (${h1s.length})`,
+      impact: "Best practice is one H1 per page. Use H2-H6 for subsections.",
+      element: h1s.map((h) => h.text).join(", ")
+    });
+  }
+  let prevLevel = 0;
+  for (const h of headings) {
+    if (h.level > prevLevel + 1 && prevLevel > 0) {
+      issues.push({
+        severity: "info",
+        category: "content",
+        code: "SKIPPED_HEADING_LEVEL",
+        message: `Skipped heading level: H${prevLevel} to H${h.level}`,
+        impact: "Maintain proper heading hierarchy for accessibility and SEO."
+      });
+      break;
+    }
+    prevLevel = h.level;
+  }
+}
+function analyzeImages(images, issues) {
+  const missingAlt = images.filter((img) => !img.alt);
+  if (missingAlt.length > 0) {
+    issues.push({
+      severity: "warning",
+      category: "accessibility",
+      code: "IMAGES_MISSING_ALT",
+      message: `${missingAlt.length} image(s) missing alt text`,
+      impact: "Alt text is essential for accessibility and helps search engines understand images.",
+      element: missingAlt.slice(0, 3).map((i) => i.src).join(", ")
+    });
+  }
+  const missingDimensions = images.filter((img) => !img.width || !img.height);
+  if (missingDimensions.length > 0) {
+    issues.push({
+      severity: "info",
+      category: "performance",
+      code: "IMAGES_MISSING_DIMENSIONS",
+      message: `${missingDimensions.length} image(s) missing width/height`,
+      impact: "Specifying dimensions prevents layout shift (CLS)."
+    });
+  }
+}
+function calculateScore(issues) {
+  const weights = {
+    critical: 15,
+    warning: 5,
+    info: 1
+  };
+  let totalDeduction = 0;
+  for (const issue of issues) {
+    totalDeduction += weights[issue.severity];
+  }
+  return Math.max(0, Math.min(100, 100 - totalDeduction));
+}
+function generateRecommendations(issues) {
+  const recommendations = [];
+  const criticalCount = issues.filter((i) => i.severity === "critical").length;
+  const warningCount = issues.filter((i) => i.severity === "warning").length;
+  if (criticalCount > 0) {
+    recommendations.push({
+      priority: "high",
+      category: "immediate",
+      message: `Fix ${criticalCount} critical issue(s) first`,
+      impact: "Critical issues directly impact search visibility"
+    });
+  }
+  if (issues.some((i) => i.code === "MISSING_SCHEMA")) {
+    recommendations.push({
+      priority: "high",
+      category: "schema",
+      message: "Add JSON-LD structured data",
+      impact: "Enable rich snippets in search results"
+    });
+  }
+  if (issues.some((i) => i.code.includes("OG") || i.code.includes("TWITTER"))) {
+    recommendations.push({
+      priority: "medium",
+      category: "social",
+      message: "Complete social media meta tags",
+      impact: "Improve appearance when shared on social platforms"
+    });
+  }
+  if (warningCount > 3) {
+    recommendations.push({
+      priority: "medium",
+      category: "optimization",
+      message: `Address ${warningCount} warnings to improve score`,
+      impact: "Each fix improves overall SEO health"
+    });
+  }
+  return recommendations;
+}
+
+export {
+  __require,
+  __export,
+  httpGet,
+  httpHead,
+  httpPost,
+  crawlUrl,
+  extractMeta,
+  analyzeHeadings,
+  extractImages,
+  extractLinks,
+  extractSchema,
+  checkRobots,
+  checkSitemap,
+  analyzeUrl
+};