@rankcli/agent-runtime 0.0.1

package/src/utils/http.ts

@@ -0,0 +1,302 @@
+/**
+ * Isomorphic HTTP utilities using native fetch
+ * Works in both Node.js (18+) and Deno
+ */
+
+export interface HttpRequestConfig {
+  headers?: Record<string, string>;
+  timeout?: number;
+  validateStatus?: (status: number) => boolean;
+  maxRedirects?: number;
+  auth?: { username: string; password: string };
+  params?: Record<string, string | number | boolean>;
+}
+
+export interface HttpResponse<T = unknown> {
+  data: T;
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+}
+
+const DEFAULT_TIMEOUT = 30000;
+const DEFAULT_USER_AGENT = 'RankCLI/1.0 (+https://rankcli.dev)';
+
+/**
+ * Create an AbortController with timeout
+ */
+function createTimeoutController(timeout: number): { controller: AbortController; timeoutId: ReturnType<typeof setTimeout> } {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  return { controller, timeoutId };
+}
+
+/**
+ * Convert Headers to plain object
+ */
+function headersToObject(headers: Headers): Record<string, string> {
+  const obj: Record<string, string> = {};
+  headers.forEach((value, key) => {
+    obj[key.toLowerCase()] = value;
+  });
+  return obj;
+}
+
+/**
+ * HTTP GET request
+ */
+export async function httpGet<T = string>(
+  url: string,
+  config: HttpRequestConfig = {}
+): Promise<HttpResponse<T>> {
+  const {
+    headers = {},
+    timeout = DEFAULT_TIMEOUT,
+    validateStatus = (status) => status >= 200 && status < 300,
+    maxRedirects = 5,
+    params,
+  } = config;
+
+  // Build URL with query params
+  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: T;
+
+    if (contentType.includes('application/json')) {
+      data = await response.json() as T;
+    } else {
+      data = await response.text() as unknown as T;
+    }
+
+    if (!validateStatus(response.status)) {
+      const error = new Error(`Request failed with status ${response.status}`) as Error & { response: HttpResponse<T> };
+      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;
+  }
+}
+
+/**
+ * HTTP HEAD request
+ */
+export async function httpHead(
+  url: string,
+  config: HttpRequestConfig = {}
+): Promise<HttpResponse<null>> {
+  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}`) as Error & { response: HttpResponse<null> };
+      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;
+  }
+}
+
+/**
+ * HTTP POST request
+ */
+export async function httpPost<T = unknown>(
+  url: string,
+  data?: unknown,
+  config: HttpRequestConfig = {}
+): Promise<HttpResponse<T>> {
+  const {
+    headers = {},
+    timeout = DEFAULT_TIMEOUT,
+    validateStatus = (status) => status >= 200 && status < 300,
+    auth,
+  } = config;
+
+  const { controller, timeoutId } = createTimeoutController(timeout);
+
+  const requestHeaders: Record<string, string> = {
+    'User-Agent': DEFAULT_USER_AGENT,
+    'Content-Type': 'application/json',
+    ...headers,
+  };
+
+  // Add basic auth if provided
+  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) : undefined,
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    const contentType = response.headers.get('content-type') || '';
+    let responseData: T;
+
+    if (contentType.includes('application/json')) {
+      responseData = await response.json() as T;
+    } else {
+      responseData = await response.text() as unknown as T;
+    }
+
+    if (!validateStatus(response.status)) {
+      const error = new Error(`Request failed with status ${response.status}`) as Error & { response: HttpResponse<T> };
+      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;
+  }
+}
+
+/**
+ * Follow redirects manually and return the chain
+ */
+export async function followRedirects(
+  url: string,
+  config: HttpRequestConfig = {}
+): Promise<{ chain: string[]; finalUrl: string; status: number }> {
+  const {
+    headers = {},
+    timeout = DEFAULT_TIMEOUT,
+    maxRedirects = 10,
+  } = config;
+
+  const chain: string[] = [url];
+  let currentUrl = url;
+  let redirectCount = 0;
+
+  while (redirectCount < maxRedirects) {
+    const { controller, timeoutId } = createTimeoutController(timeout);
+
+    try {
+      const response = await fetch(currentUrl, {
+        method: 'HEAD',
+        headers: {
+          'User-Agent': DEFAULT_USER_AGENT,
+          ...headers,
+        },
+        signal: controller.signal,
+        redirect: 'manual',
+      });
+
+      clearTimeout(timeoutId);
+
+      if (response.status >= 300 && response.status < 400) {
+        const location = response.headers.get('location');
+        if (location) {
+          // Resolve relative URLs
+          currentUrl = new URL(location, currentUrl).toString();
+          chain.push(currentUrl);
+          redirectCount++;
+          continue;
+        }
+      }
+
+      return { chain, finalUrl: currentUrl, status: response.status };
+    } catch (error) {
+      clearTimeout(timeoutId);
+      throw error;
+    }
+  }
+
+  return { chain, finalUrl: currentUrl, status: 0 };
+}

package/src/wasm-adapter.ts

@@ -0,0 +1,297 @@
+/**
+ * WASM Adapter
+ *
+ * This file creates the global RankCLI object that the WASM wrapper expects.
+ * It adapts the async runFullAudit to a sync-compatible interface for VM execution.
+ *
+ * When this code is embedded in WASM and executed in a Node.js VM:
+ * - The VM has limited async capabilities
+ * - We provide a sync interface that queues work for the host
+ */
+
+import * as cheerio from 'cheerio';
+import { analyzeOnPage } from './audit/checks/on-page.js';
+import { analyzeStructuredData } from './audit/checks/structured-data.js';
+import { analyzeMobile } from './audit/checks/mobile.js';
+import { analyzeSocialMeta } from './audit/checks/social-meta.js';
+import { analyzeSERPPreview } from './audit/checks/serp-preview.js';
+import { analyzeDOMStructure } from './audit/checks/dom-analysis.js';
+import { detectTechnologies } from './audit/checks/tech-detection.js';
+import { analyzeKeywords } from './audit/checks/keyword-analysis.js';
+import { analyzeDomSize } from './audit/checks/dom-size.js';
+import { analyzeImageDimensions } from './audit/checks/image-dimensions.js';
+import { analyzeUrlSafety } from './audit/checks/url-safety.js';
+import { detectSoft404 } from './audit/checks/soft-404.js';
+import { analyzePagination } from './audit/checks/pagination.js';
+// Extended checks
+import { analyzeAnchorText } from './audit/checks/anchor-text.js';
+import { analyzeLocalSEO } from './audit/checks/local-seo.js';
+import { analyzeModernImages } from './audit/checks/modern-images.js';
+import { analyzeResourceHints } from './audit/checks/resource-hints.js';
+import { analyzeTrackerBloat } from './audit/checks/tracker-bloat.js';
+import { analyzeClientRendering } from './audit/checks/client-rendering.js';
+import { analyzeResponsiveImages } from './audit/checks/responsive-images.js';
+import { analyzeColorContrast } from './audit/checks/color-contrast.js';
+import { analyzePageResources } from './audit/checks/page-resources.js';
+// Premium checks
+import { analyzeFeaturedSnippet } from './audit/checks/featured-snippet.js';
+import { analyzeInternalLinkGraph } from './audit/checks/internal-link-graph.js';
+import { analyzeEEATSignals } from './audit/checks/eeat-signals.js';
+import { analyzeContentScience } from './audit/checks/content-science.js';
+import { analyzeConversionElements } from './audit/checks/conversion-elements.js';
+import { analyzeKeywordPlacement } from './audit/checks/keyword-placement.js';
+import { analyzeNavBoostSignals } from './audit/checks/navboost-signals.js';
+import { analyzeEntitySEO } from './audit/checks/entity-seo.js';
+import { analyzeFreshnessSignals } from './audit/checks/freshness-signals.js';
+import { analyzeAIContentStructure } from './audit/checks/ai-content-structure.js';
+import { analyzeCitationQuality } from './audit/checks/citation-quality.js';
+import { analyzeAnswerConciseness } from './audit/checks/answer-conciseness.js';
+import { analyzeBrandMentionOptimization } from './audit/checks/brand-mention-optimization.js';
+import { analyzeAICitationWorthiness } from './audit/checks/ai-citation-worthiness.js';
+import { analyzeReviewEcosystem } from './audit/checks/review-ecosystem.js';
+import type { AuditIssue } from './audit/types.js';
+
+interface SyncAuditResult {
+  success: boolean;
+  score: number;
+  issues: AuditIssue[];
+  checksRun: number;
+  tier: string;
+}
+
+/**
+ * Synchronous audit function for VM execution
+ * Only runs checks that don't require network requests
+ */
+function runSyncAudit(url: string, html: string, checksLimit: number): SyncAuditResult {
+  const allIssues: AuditIssue[] = [];
+  const headers: Record<string, string> = {};
+
+  // Determine tier
+  const tier = checksLimit > 100 ? 'paid' : checksLimit > 50 ? 'registered' : 'free';
+  const runExtended = checksLimit > 50;
+  const runPremium = checksLimit > 100;
+
+  // ===== CORE CHECKS (all tiers) =====
+  try {
+    const onPage = analyzeOnPage(html, url);
+    allIssues.push(...onPage.issues);
+  } catch (e) { /* ignore */ }
+
+  try {
+    const structured = analyzeStructuredData(html, url);
+    allIssues.push(...structured.issues);
+  } catch (e) { /* ignore */ }
+
+  try {
+    const mobile = analyzeMobile(html, url);
+    allIssues.push(...mobile.issues);
+  } catch (e) { /* ignore */ }
+
+  try {
+    const social = analyzeSocialMeta(html, url);
+    allIssues.push(...social.issues);
+  } catch (e) { /* ignore */ }
+
+  try {
+    const serp = analyzeSERPPreview(html, url);
+    allIssues.push(...serp.issues);
+  } catch (e) { /* ignore */ }
+
+  try {
+    const dom = analyzeDOMStructure(html, url);
+    allIssues.push(...dom.issues);
+  } catch (e) { /* ignore */ }
+
+  try {
+    const tech = detectTechnologies(html, url, headers);
+    allIssues.push(...tech.issues);
+  } catch (e) { /* ignore */ }
+
+  try {
+    const keywords = analyzeKeywords(html, url);
+    allIssues.push(...keywords.issues);
+  } catch (e) { /* ignore */ }
+
+  try {
+    const domSize = analyzeDomSize(html, url);
+    allIssues.push(...domSize.issues);
+  } catch (e) { /* ignore */ }
+
+  try {
+    const imageDims = analyzeImageDimensions(html, url);
+    allIssues.push(...imageDims.issues);
+  } catch (e) { /* ignore */ }
+
+  try {
+    const urlSafety = analyzeUrlSafety(url);
+    allIssues.push(...urlSafety.issues);
+  } catch (e) { /* ignore */ }
+
+  try {
+    const soft404 = detectSoft404(html, url, 200);
+    allIssues.push(...soft404.issues);
+  } catch (e) { /* ignore */ }
+
+  let coreChecks = 12;
+
+  // ===== EXTENDED CHECKS (registered + paid) =====
+  if (runExtended) {
+    try {
+      const anchor = analyzeAnchorText(html, url);
+      allIssues.push(...anchor.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const local = analyzeLocalSEO(html, url);
+      allIssues.push(...local.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const modern = analyzeModernImages(html, url);
+      allIssues.push(...modern.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const hints = analyzeResourceHints(html, url);
+      allIssues.push(...hints.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const tracker = analyzeTrackerBloat(html, url);
+      allIssues.push(...tracker.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const csr = analyzeClientRendering(html, url);
+      allIssues.push(...csr.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const responsive = analyzeResponsiveImages(html, url);
+      allIssues.push(...responsive.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const contrast = analyzeColorContrast(html, url);
+      allIssues.push(...contrast.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const resources = analyzePageResources(html, url);
+      allIssues.push(...resources.issues);
+    } catch (e) { /* ignore */ }
+
+    coreChecks += 9;
+  }
+
+  // ===== PREMIUM CHECKS (paid only) =====
+  if (runPremium) {
+    try {
+      const snippet = analyzeFeaturedSnippet(html, url);
+      allIssues.push(...snippet.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const linkGraph = analyzeInternalLinkGraph(html, url);
+      allIssues.push(...linkGraph.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const eeat = analyzeEEATSignals(html, url);
+      allIssues.push(...eeat.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const content = analyzeContentScience(html, url);
+      allIssues.push(...content.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const conversion = analyzeConversionElements(html, url);
+      allIssues.push(...conversion.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const placement = analyzeKeywordPlacement(html, url);
+      allIssues.push(...placement.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const navboost = analyzeNavBoostSignals(html, url);
+      allIssues.push(...navboost.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const entity = analyzeEntitySEO(html, url);
+      allIssues.push(...entity.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const freshness = analyzeFreshnessSignals(html, url);
+      allIssues.push(...freshness.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const aiContent = analyzeAIContentStructure(html, url);
+      allIssues.push(...aiContent.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const citation = analyzeCitationQuality(html, url);
+      allIssues.push(...citation.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const answer = analyzeAnswerConciseness(html, url);
+      allIssues.push(...answer.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const brand = analyzeBrandMentionOptimization(html, url);
+      allIssues.push(...brand.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const worthiness = analyzeAICitationWorthiness(html, url);
+      allIssues.push(...worthiness.issues);
+    } catch (e) { /* ignore */ }
+
+    try {
+      const review = analyzeReviewEcosystem(html, url);
+      allIssues.push(...review.issues);
+    } catch (e) { /* ignore */ }
+
+    coreChecks += 15;
+  }
+
+  // Calculate score
+  const errors = allIssues.filter(i => i.severity === 'error').length;
+  const warnings = allIssues.filter(i => i.severity === 'warning').length;
+  const score = Math.max(0, Math.min(100, 100 - (errors * 10) - (warnings * 3)));
+
+  return {
+    success: true,
+    score,
+    issues: allIssues,
+    checksRun: coreChecks,
+    tier,
+  };
+}
+
+// Create global RankCLI object for VM execution
+declare const globalThis: {
+  RankCLI?: {
+    runAudit: typeof runSyncAudit;
+    version: string;
+  };
+};
+
+if (typeof globalThis !== 'undefined') {
+  globalThis.RankCLI = {
+    runAudit: runSyncAudit,
+    version: '0.1.0',
+  };
+}
+
+export { runSyncAudit };

package/src/wasm-entry.ts

@@ -0,0 +1,14 @@
+/**
+ * WASM Entry Point
+ *
+ * This is the entry point for the code that gets embedded in WASM.
+ * It's a minimal build that only includes sync checks (no network requests).
+ *
+ * Build with: tsup src/wasm-entry.ts --format esm --minify
+ */
+
+// Import and re-export the WASM adapter
+import './wasm-adapter.js';
+
+// Export types that might be needed
+export type { AuditIssue, AuditReport } from './audit/types.js';

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.wasm.config.ts

@@ -0,0 +1,26 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/wasm-adapter.ts'],
+  outDir: 'dist/wasm',
+  format: ['iife'],
+  minify: true,
+  bundle: true,
+  // CRITICAL: Don't externalize anything - bundle everything inline
+  noExternal: [/.*/],
+  platform: 'browser',
+  target: 'es2020',
+  globalName: '__rankcli__',
+  esbuildOptions(options) {
+    // Set global RankCLI at the end
+    options.footer = {
+      js: `
+        if (typeof globalThis !== 'undefined') {
+          globalThis.RankCLI = __rankcli__.runSyncAudit ?
+            { runAudit: __rankcli__.runSyncAudit, version: '0.1.0' } :
+            __rankcli__;
+        }
+      `,
+    };
+  },
+});

package/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      include: ['src/**/*.ts'],
+      exclude: ['src/**/*.test.ts', 'src/test/**'],
+    },
+  },
+});