opencandle 0.11.1 → 0.12.0

package/src/providers/exa-search.ts

@@ -1,375 +0,0 @@
-import { getConfig } from "../config.js";
-import { cache, STALE_LIMIT, TTL } from "../infra/cache.js";
-import { rateLimiter } from "../infra/rate-limiter.js";
-import type { WebSearchEnvelope, WebSearchResult } from "../types/sentiment.js";
-import { ProviderCredentialError } from "./provider-credential-error.js";
-import type { WebSearchOpts } from "./web-search.js";
-
-const EXA_MCP_URL = "https://mcp.exa.ai/mcp";
-const EXA_API_URL = "https://api.exa.ai/search";
-const TIMEOUT_MS = 5_000;
-const SNIPPET_MAX_CHARS = 300;
-const CONTEXT_MAX_CHARS = 1_000;
-
-let requestIdCounter = 0;
-
-// ---------------------------------------------------------------------------
-// Freshness helpers
-// ---------------------------------------------------------------------------
-
-function freshnessToMs(freshness: WebSearchOpts["freshness"]): number {
-  switch (freshness) {
-    case "hours":
-      return 60 * 60 * 1000;
-    case "day":
-      return 24 * 60 * 60 * 1000;
-    case "week":
-      return 7 * 24 * 60 * 60 * 1000;
-    case "month":
-      return 30 * 24 * 60 * 60 * 1000;
-  }
-}
-
-function enrichQueryForMcp(query: string, freshness: WebSearchOpts["freshness"]): string {
-  switch (freshness) {
-    case "hours":
-      return `${query} past hour`;
-    case "day":
-      return `${query} past 24 hours`;
-    case "week":
-      return `${query} past week`;
-    case "month":
-      return `${query} past month`;
-  }
-}
-
-function startPublishedDate(freshness: WebSearchOpts["freshness"]): string {
-  return new Date(Date.now() - freshnessToMs(freshness)).toISOString();
-}
-
-// ---------------------------------------------------------------------------
-// MCP response parsing
-// ---------------------------------------------------------------------------
-
-interface McpRpcResponse {
-  result?: {
-    content?: Array<{ type?: string; text?: string; _meta?: Record<string, unknown> }>;
-  };
-  error?: {
-    code?: number;
-    message?: string;
-  };
-}
-
-function extractJsonRpcPayload(body: string, contentType: string): McpRpcResponse {
-  // Path 1: plain JSON response
-  if (contentType.includes("application/json")) {
-    return JSON.parse(body) as McpRpcResponse;
-  }
-
-  // Path 2: SSE — scan all data: lines for valid JSON-RPC
-  const dataLines = body.split("\n").filter((line) => line.startsWith("data:"));
-  for (const line of dataLines) {
-    const payload = line.slice(5).trim();
-    if (!payload) continue;
-    try {
-      const candidate = JSON.parse(payload) as McpRpcResponse;
-      if (candidate?.result || candidate?.error) return candidate;
-    } catch {
-      // not valid JSON, try next line
-    }
-  }
-
-  // Path 3: fallback — try parsing entire body
-  try {
-    const candidate = JSON.parse(body) as McpRpcResponse;
-    if (candidate?.result || candidate?.error) return candidate;
-  } catch {
-    // not valid JSON
-  }
-
-  throw new Error("Exa MCP returned empty content");
-}
-
-interface ParsedResult {
-  title: string;
-  url: string;
-  published: string | null;
-  snippet: string;
-}
-
-function parseMcpResultBlocks(text: string): ParsedResult[] {
-  const blocks = text.split(/\n---\n/).filter((b) => b.trim().length > 0);
-  const results: ParsedResult[] = [];
-
-  for (const block of blocks) {
-    const title = block.match(/^Title: (.+)/m)?.[1]?.trim() ?? "";
-    const url = block.match(/^URL: (.+)/m)?.[1]?.trim() ?? "";
-    if (!url) continue;
-
-    const published = block.match(/^Published: (.+)/m)?.[1]?.trim() ?? null;
-
-    // Extract highlights/text content after the header fields
-    let content = "";
-    const hlMatch = block.match(/^Highlights:\n?/m);
-    if (hlMatch?.index != null) {
-      content = block.slice(hlMatch.index + hlMatch[0].length).trim();
-    }
-    const snippet = content.slice(0, SNIPPET_MAX_CHARS);
-
-    results.push({ title, url, published, snippet });
-  }
-
-  return results;
-}
-
-// ---------------------------------------------------------------------------
-// Direct API response mapping
-// ---------------------------------------------------------------------------
-
-interface ExaApiResult {
-  title?: string;
-  url?: string;
-  publishedDate?: string;
-  text?: string;
-  highlights?: string[];
-}
-
-interface ExaApiResponse {
-  results?: ExaApiResult[];
-}
-
-function mapApiResults(results: ExaApiResult[]): ParsedResult[] {
-  return results
-    .filter((r) => r.url)
-    .map((r) => ({
-      title: r.title ?? "",
-      url: r.url!,
-      published: r.publishedDate ?? null,
-      snippet: (r.highlights?.join(" ") || r.text || "").slice(0, SNIPPET_MAX_CHARS),
-    }));
-}
-
-// ---------------------------------------------------------------------------
-// Freshness post-filter
-// ---------------------------------------------------------------------------
-
-function filterByFreshness(
-  results: ParsedResult[],
-  freshness: WebSearchOpts["freshness"],
-): ParsedResult[] {
-  const cutoff = Date.now() - freshnessToMs(freshness);
-  return results.filter((r) => {
-    if (!r.published) return true; // benefit of the doubt
-    const pubTime = new Date(r.published).getTime();
-    return !isNaN(pubTime) && pubTime >= cutoff;
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Common helpers
-// ---------------------------------------------------------------------------
-
-function extractDomain(url: string): string {
-  try {
-    return new URL(url).hostname.replace(/^www\./, "");
-  } catch {
-    return url;
-  }
-}
-
-function toWebSearchResults(
-  parsed: ParsedResult[],
-  category: "news" | "general",
-): WebSearchResult[] {
-  return parsed.map((r) => ({
-    title: r.title,
-    url: r.url,
-    snippet: r.snippet,
-    source: extractDomain(r.url),
-    published: r.published,
-    category,
-  }));
-}
-
-function exaCacheKey(query: string, opts: WebSearchOpts): string {
-  return `web:exa:${query}:${opts.category}:${opts.freshness}:${opts.limit}`;
-}
-
-// ---------------------------------------------------------------------------
-// MCP path
-// ---------------------------------------------------------------------------
-
-async function exaMcpSearch(query: string, opts: WebSearchOpts): Promise<WebSearchEnvelope> {
-  const enrichedQuery = enrichQueryForMcp(query, opts.freshness);
-
-  const response = await fetch(EXA_MCP_URL, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Accept: "application/json, text/event-stream",
-    },
-    body: JSON.stringify({
-      jsonrpc: "2.0",
-      id: ++requestIdCounter,
-      method: "tools/call",
-      params: {
-        name: "web_search_exa",
-        arguments: {
-          query: enrichedQuery,
-          numResults: opts.limit,
-          livecrawl: "fallback",
-          type: "auto",
-          contextMaxCharacters: CONTEXT_MAX_CHARS,
-        },
-      },
-    }),
-    signal: AbortSignal.timeout(TIMEOUT_MS),
-  });
-
-  // Anti-abuse handling
-  const contentType = response.headers.get("content-type") ?? "";
-  if (!response.ok) {
-    if (response.status === 429) {
-      const retryAfter = response.headers.get("retry-after");
-      throw new Error(
-        `Exa MCP rate limited (429)${retryAfter ? ` — retry after ${retryAfter}s` : ""}`,
-      );
-    }
-    if (response.status === 403) {
-      throw new Error("Exa MCP blocked (403) — possible IP-based blocking");
-    }
-    throw new Error(`Exa MCP HTTP ${response.status} ${response.statusText}`);
-  }
-
-  if (contentType.includes("text/html")) {
-    throw new Error("Exa MCP returned HTML instead of JSON-RPC (possible challenge page)");
-  }
-
-  const body = await response.text();
-  const payload = extractJsonRpcPayload(body, contentType);
-
-  if (payload.error) {
-    throw new Error(payload.error.message ?? `Exa MCP error: code ${payload.error.code}`);
-  }
-
-  const text = payload.result?.content?.find(
-    (item) => item.type === "text" && typeof item.text === "string",
-  )?.text;
-
-  if (!text || text.trim().length === 0) {
-    // Legitimate zero results
-    return {
-      query,
-      results: [],
-      resultCount: 0,
-      fetchedAt: new Date().toISOString(),
-      provider: "exa",
-    };
-  }
-
-  const parsed = parseMcpResultBlocks(text);
-  const filtered = filterByFreshness(parsed, opts.freshness);
-  const results = toWebSearchResults(filtered, opts.category);
-
-  return {
-    query,
-    results: results.slice(0, opts.limit),
-    resultCount: Math.min(results.length, opts.limit),
-    fetchedAt: new Date().toISOString(),
-    provider: "exa",
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Direct API path
-// ---------------------------------------------------------------------------
-
-async function exaApiSearch(
-  query: string,
-  opts: WebSearchOpts,
-  apiKey: string,
-): Promise<WebSearchEnvelope> {
-  const response = await fetch(EXA_API_URL, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${apiKey}`,
-    },
-    body: JSON.stringify({
-      query,
-      type: "auto",
-      numResults: opts.limit,
-      startPublishedDate: startPublishedDate(opts.freshness),
-      contents: {
-        text: { maxCharacters: CONTEXT_MAX_CHARS },
-        highlights: true,
-      },
-    }),
-    signal: AbortSignal.timeout(TIMEOUT_MS),
-  });
-
-  if (!response.ok) {
-    if (response.status === 401 || response.status === 403) {
-      throw new ProviderCredentialError("exa", "stale", response.status);
-    }
-    const body = await response.text().catch(() => "");
-    throw new Error(`Exa API HTTP ${response.status}: ${body.slice(0, 300)}`);
-  }
-
-  const data = (await response.json()) as ExaApiResponse;
-  const parsed = mapApiResults(data.results ?? []);
-  const filtered = filterByFreshness(parsed, opts.freshness);
-  const results = toWebSearchResults(filtered, opts.category);
-
-  return {
-    query,
-    results: results.slice(0, opts.limit),
-    resultCount: Math.min(results.length, opts.limit),
-    fetchedAt: new Date().toISOString(),
-    provider: "exa",
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Public entry point
-// ---------------------------------------------------------------------------
-
-export async function exaSearch(query: string, opts: WebSearchOpts): Promise<WebSearchEnvelope> {
-  const key = exaCacheKey(query, opts);
-  const cached = cache.get<WebSearchEnvelope>(key);
-  if (cached) return cached;
-
-  try {
-    await rateLimiter.acquire("exa");
-
-    const config = getConfig();
-    const envelope = config.exaApiKey
-      ? await exaApiSearch(query, opts, config.exaApiKey)
-      : await exaMcpSearch(query, opts);
-
-    cache.set(key, envelope, TTL.WEB_SEARCH);
-    return envelope;
-  } catch (error) {
-    // Re-throw abort errors immediately
-    if (error instanceof Error && error.name === "AbortError") throw error;
-    if (error instanceof DOMException && error.name === "TimeoutError") throw error;
-    // Re-throw credential errors so the tool layer can convert them to the
-    // tagged content block. Stale cache must not mask a real auth failure.
-    if (error instanceof ProviderCredentialError) throw error;
-
-    const stale = cache.getStale<WebSearchEnvelope>(key, STALE_LIMIT.WEB_SEARCH);
-    if (stale) return stale.value;
-    throw error;
-  }
-}
-
-export type { ExaApiResponse, McpRpcResponse, ParsedResult };
-// Exported for testing
-export {
-  enrichQueryForMcp,
-  extractJsonRpcPayload,
-  filterByFreshness,
-  mapApiResults,
-  parseMcpResultBlocks,
-};

package/src/providers/external-tool-command.ts

@@ -1,164 +0,0 @@
-import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { homedir } from "node:os";
-import { delimiter, isAbsolute, join, sep } from "node:path";
-
-const DEFAULT_TIMEOUT_MS = 20_000;
-const DEFAULT_MAX_OUTPUT_CHARS = 2_000_000;
-
-export interface ExternalToolCommandResult {
-  readonly code: number | null;
-  readonly stdout: string;
-  readonly stderr: string;
-}
-
-export interface ExternalToolCommandOptions {
-  readonly timeoutMs?: number;
-  readonly maxOutputChars?: number;
-}
-
-interface CandidateOptions {
-  readonly env?: NodeJS.ProcessEnv;
-  readonly homeDir?: string;
-  readonly platform?: NodeJS.Platform;
-}
-
-export function getExternalToolCommandCandidates(
-  command: string,
-  options: CandidateOptions = {},
-): string[] {
-  if (isPathLikeCommand(command)) return [command];
-
-  const env = options.env ?? process.env;
-  const platform = options.platform ?? process.platform;
-  const home = options.homeDir ?? homedir();
-  const candidates = [command];
-  const binDirs = [
-    env.OPENCANDLE_EXTERNAL_TOOL_BIN_DIR,
-    env.UV_TOOL_BIN_DIR,
-    env.XDG_BIN_HOME,
-    home ? join(home, ".local", "bin") : undefined,
-  ];
-
-  for (const dir of binDirs) {
-    if (!dir) continue;
-    for (const executable of commandNames(command, platform)) {
-      candidates.push(join(dir, executable));
-    }
-  }
-
-  return [...new Set(candidates)];
-}
-
-export async function runExternalToolCommand(
-  command: string,
-  args: readonly string[],
-  options: ExternalToolCommandOptions = {},
-): Promise<ExternalToolCommandResult> {
-  const uvToolBinDirs = await resolveUvToolBinDirs(options);
-  const candidates = [
-    ...getExternalToolCommandCandidates(command),
-    ...uvToolBinDirs.flatMap((dir) =>
-      commandNames(command, process.platform).map((executable) => join(dir, executable)),
-    ),
-  ].filter((candidate, index, all) => all.indexOf(candidate) === index);
-  const existingCandidates = candidates.filter(
-    (candidate) => candidate === command || existsSync(candidate),
-  );
-  return runCandidate(
-    existingCandidates.length > 0 ? existingCandidates : [command],
-    args,
-    options,
-  );
-}
-
-async function resolveUvToolBinDirs(
-  options: ExternalToolCommandOptions,
-): Promise<readonly string[]> {
-  try {
-    const result = await spawnCommand("uv", ["tool", "dir", "--bin"], {
-      timeoutMs: Math.min(options.timeoutMs ?? DEFAULT_TIMEOUT_MS, 2_000),
-      maxOutputChars: 4_000,
-    });
-    if (result.code !== 0) return [];
-    const binDir = result.stdout.trim();
-    return binDir ? [binDir] : [];
-  } catch {
-    return [];
-  }
-}
-
-function runCandidate(
-  candidates: readonly string[],
-  args: readonly string[],
-  options: ExternalToolCommandOptions,
-): Promise<ExternalToolCommandResult> {
-  const [command, ...fallbacks] = candidates;
-  return spawnCommand(command, args, options).catch((err: NodeJS.ErrnoException) => {
-    if (err.code === "ENOENT" && fallbacks.length > 0) {
-      return runCandidate(fallbacks, args, options);
-    }
-    throw err;
-  });
-}
-
-function spawnCommand(
-  command: string,
-  args: readonly string[],
-  options: ExternalToolCommandOptions,
-): Promise<ExternalToolCommandResult> {
-  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const maxOutputChars = options.maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS;
-
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, [...args], { stdio: ["ignore", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    let settled = false;
-
-    const timeout = setTimeout(() => {
-      if (settled) return;
-      settled = true;
-      child.kill("SIGTERM");
-      reject(new Error(`${command} timed out after ${timeoutMs}ms`));
-    }, timeoutMs);
-
-    child.stdout.on("data", (chunk: Buffer) => {
-      stdout = (stdout + chunk.toString("utf8")).slice(0, maxOutputChars);
-    });
-    child.stderr.on("data", (chunk: Buffer) => {
-      stderr = (stderr + chunk.toString("utf8")).slice(0, maxOutputChars);
-    });
-    child.on("error", (err) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timeout);
-      reject(err);
-    });
-    child.on("close", (code) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timeout);
-      resolve({ code, stdout, stderr });
-    });
-  });
-}
-
-function isPathLikeCommand(command: string): boolean {
-  return (
-    isAbsolute(command) || command.includes("/") || command.includes("\\") || command.includes(sep)
-  );
-}
-
-function commandNames(command: string, platform: NodeJS.Platform): string[] {
-  if (platform !== "win32") return [command];
-
-  const names = [command];
-  const pathExt = process.env.PATHEXT?.split(delimiter) ?? [".EXE", ".CMD", ".BAT"];
-  for (const ext of pathExt) {
-    if (!command.toLowerCase().endsWith(ext.toLowerCase())) {
-      names.push(`${command}${ext.toLowerCase()}`);
-    }
-  }
-  return names;
-}

package/src/providers/external-tool-error.ts

@@ -1,20 +0,0 @@
-export class ExternalToolError extends Error {
-  constructor(
-    public readonly toolName: string,
-    message: string,
-    public readonly code?: string,
-  ) {
-    super(message);
-    this.name = "ExternalToolError";
-  }
-}
-
-export class ExternalToolNotInstalled extends Error {
-  constructor(
-    public readonly toolName: string,
-    public readonly installCmd: string,
-  ) {
-    super(`${toolName} is not installed. Install it with: ${installCmd}`);
-    this.name = "ExternalToolNotInstalled";
-  }
-}

package/src/providers/fear-greed.ts

@@ -1,45 +0,0 @@
-import { cache, STALE_LIMIT, TTL } from "../infra/cache.js";
-import { httpGet } from "../infra/http-client.js";
-import type { FearGreedData } from "../types/sentiment.js";
-
-// alternative.me provides a free crypto Fear & Greed index
-// CNN endpoint (production.dataviz.cnn.io) blocks automated requests (HTTP 418)
-const ENDPOINT = "https://api.alternative.me/fng/?limit=3";
-
-interface AlternativeMeFngResponse {
-  data: Array<{
-    value: string;
-    value_classification: string;
-    timestamp: string;
-  }>;
-}
-
-export async function getFearGreedIndex(): Promise<FearGreedData> {
-  const cacheKey = "feargreed:index";
-  const cached = cache.get<FearGreedData>(cacheKey);
-  if (cached) return cached;
-
-  try {
-    const data = await httpGet<AlternativeMeFngResponse>(ENDPOINT);
-
-    const entries = data.data;
-    const current = entries[0];
-    const value = parseInt(current.value, 10);
-
-    const result: FearGreedData = {
-      value,
-      label: current.value_classification,
-      timestamp: Date.now(),
-      previousClose: entries[1] ? parseInt(entries[1].value, 10) : value,
-      weekAgo: null,
-      monthAgo: null,
-    };
-
-    cache.set(cacheKey, result, TTL.SENTIMENT);
-    return result;
-  } catch (error) {
-    const stale = cache.getStale<FearGreedData>(cacheKey, STALE_LIMIT.SENTIMENT);
-    if (stale) return stale.value;
-    throw error;
-  }
-}