opencandle 0.11.0 → 0.12.0

package/src/onboarding/providers.ts

@@ -1,414 +0,0 @@
-// Provider registry — single source of truth for OpenCandle's third-party
-// data providers. Every setup/status pathway iterates this registry:
-// first-run startup, the `/connect` command, the `tool_result` credential
-// interception handler, GUI provider rows, doctor checks, and gap-note
-// generation all read from here.
-//
-// Adding a new provider is a two-step change: add its id to the relevant
-// literal union below, and add its descriptor to the `PROVIDERS` array. The
-// `satisfies` and exhaustiveness checks keep the registry and id unions aligned.
-
-import { getConfig, loadFileConfig } from "../config.js";
-
-export type ApiKeyProviderId = "alpha_vantage" | "fred" | "finnhub" | "brave" | "exa";
-export type ExternalToolProviderId = "twitter" | "reddit";
-export type PublicHttpProviderId = "yahoo";
-export type ProviderId = ApiKeyProviderId | ExternalToolProviderId | PublicHttpProviderId;
-
-export type ProviderCategory =
-  | "fundamentals"
-  | "macro"
-  | "news"
-  | "web_search"
-  | "sentiment"
-  | "market";
-
-export type ProviderTier = "hard" | "soft";
-
-interface BaseProviderDescriptor {
-  readonly id: ProviderId;
-  readonly kind: "api-key" | "external-tool" | "public-http";
-  readonly displayName: string;
-  readonly category: ProviderCategory;
-  /**
-   * `hard` providers pause the workflow with a just-in-time prompt when their
-   * credential is missing; they have no meaningful fallback.
-   *
-   * `soft` providers silently use a fallback path and surface a post-answer
-   * gap note in the final output.
-   */
-  readonly tier: ProviderTier;
-  /** Lowercase friendly aliases accepted by `/connect` in addition to the id. */
-  readonly aliases: readonly string[];
-  readonly unlocks: readonly string[];
-  /**
-   * Human copy describing the degraded experience when missing, or `null`
-   * when there is no fallback (hard tier).
-   */
-  readonly fallbackDescription: string | null;
-  readonly snoozeDurationDays: number;
-  readonly instructionsHint: string;
-}
-
-export interface ApiKeyProviderDescriptor extends BaseProviderDescriptor {
-  readonly id: ApiKeyProviderId;
-  readonly kind: "api-key";
-  readonly signupUrl: string;
-  readonly freeTier: boolean;
-  readonly envVar: string;
-  /** Nested key path into `OpenCandleFileConfig` where the key is persisted. */
-  readonly configPath: readonly string[];
-}
-
-export interface ExternalToolProviderDescriptor extends BaseProviderDescriptor {
-  readonly id: ExternalToolProviderId;
-  readonly kind: "external-tool";
-  readonly binary: string;
-  readonly installCmd: string;
-  readonly sessionSource: "browser-cookies";
-  readonly supportedBrowsers?: readonly string[];
-  readonly sessionProbeArgs?: readonly string[];
-}
-
-export interface PublicHttpProviderDescriptor extends BaseProviderDescriptor {
-  readonly id: PublicHttpProviderId;
-  readonly kind: "public-http";
-  readonly probeUrl: string;
-}
-
-export type ProviderDescriptor =
-  | ApiKeyProviderDescriptor
-  | ExternalToolProviderDescriptor
-  | PublicHttpProviderDescriptor;
-
-// Declaration order matters: picker display order, per-workflow prompt priority,
-// getProvidersByCategory/getProvidersByTier iteration order.
-export const PROVIDERS = [
-  {
-    id: "alpha_vantage",
-    kind: "api-key",
-    displayName: "Alpha Vantage",
-    category: "fundamentals",
-    tier: "hard",
-    aliases: ["financials", "fundamentals", "company-financials", "alphavantage"],
-    signupUrl: "https://www.alphavantage.co/support/#api-key",
-    freeTier: true,
-    envVar: "ALPHA_VANTAGE_API_KEY",
-    configPath: ["providers", "alphaVantage", "apiKey"],
-    unlocks: [
-      "company fundamentals",
-      "income/balance/cashflow statements",
-      "DCF valuation",
-      "earnings history",
-    ],
-    fallbackDescription: null,
-    snoozeDurationDays: 7,
-    instructionsHint: "Free, about 30 seconds, signup opens in your browser",
-  },
-  {
-    id: "fred",
-    kind: "api-key",
-    displayName: "FRED",
-    category: "macro",
-    tier: "hard",
-    aliases: ["economy", "macro", "economic-data", "st-louis-fed"],
-    signupUrl: "https://fredaccount.stlouisfed.org/apikeys",
-    freeTier: true,
-    envVar: "FRED_API_KEY",
-    configPath: ["providers", "fred", "apiKey"],
-    unlocks: ["interest rates", "inflation data", "yield curve", "economic indicators"],
-    fallbackDescription: null,
-    snoozeDurationDays: 7,
-    instructionsHint: "Free, about 30 seconds, requires a St. Louis Fed account",
-  },
-  {
-    id: "finnhub",
-    kind: "api-key",
-    displayName: "Finnhub",
-    category: "news",
-    tier: "soft",
-    aliases: ["news", "company-news", "finnhub-news"],
-    signupUrl: "https://finnhub.io/register",
-    freeTier: true,
-    envVar: "FINNHUB_API_KEY",
-    configPath: ["providers", "finnhub", "apiKey"],
-    unlocks: ["ticker-tagged company news", "sentiment enrichment with a dedicated news source"],
-    // Finnhub is a soft enrichment source — sentiment-summary continues to work
-    // with Twitter/Reddit/web search when Finnhub is missing. The fallback is
-    // "the other sentiment sources still run".
-    fallbackDescription:
-      "Other sentiment sources (Reddit, Twitter, web search) continue to work without Finnhub",
-    snoozeDurationDays: 7,
-    instructionsHint: "Free, about 30 seconds, signup opens in your browser",
-  },
-  {
-    id: "brave",
-    kind: "api-key",
-    displayName: "Brave Search",
-    category: "web_search",
-    tier: "soft",
-    aliases: ["brave", "brave-search"],
-    signupUrl: "https://brave.com/search/api/",
-    freeTier: true,
-    envVar: "BRAVE_API_KEY",
-    configPath: ["providers", "brave", "apiKey"],
-    unlocks: [
-      "tier-2 web search with freshness control",
-      "independent search index outside of DuckDuckGo",
-    ],
-    fallbackDescription:
-      "Web search continues to work via DuckDuckGo (free, no key needed, lower-quality freshness)",
-    snoozeDurationDays: 7,
-    instructionsHint: "Free tier available, signup opens in your browser",
-  },
-  {
-    id: "exa",
-    kind: "api-key",
-    displayName: "Exa",
-    category: "web_search",
-    tier: "soft",
-    // Note: "search" is a multi-provider alias shared with Brave. The registry
-    // exposes it via resolveProviderFromArgument as a sub-picker case, not as a
-    // single-provider alias — so it intentionally does NOT appear in either
-    // provider's `aliases` array here. Keeping aliases unique-per-provider lets
-    // resolveProviderFromArgument cleanly distinguish the alias case from the
-    // sub-picker case.
-    aliases: ["exa", "exa-search"],
-    signupUrl: "https://dashboard.exa.ai/",
-    freeTier: false,
-    envVar: "EXA_API_KEY",
-    configPath: ["providers", "exa", "apiKey"],
-    unlocks: [
-      "tier-1 semantic web search",
-      "full article text and highlights",
-      "higher freshness accuracy than DuckDuckGo",
-    ],
-    fallbackDescription:
-      "Exa search continues to work via the keyless Exa MCP endpoint, which has lower rate limits but similar quality",
-    snoozeDurationDays: 7,
-    instructionsHint: "Paid with free tier, signup opens in your browser",
-  },
-  {
-    id: "yahoo",
-    kind: "public-http",
-    displayName: "Yahoo Finance",
-    category: "market",
-    tier: "hard",
-    aliases: ["yahoo", "yahoo-finance", "market-data", "options"],
-    probeUrl: "https://query1.finance.yahoo.com/v8/finance/chart/SPY?interval=1d&range=1d",
-    unlocks: ["quotes", "historical prices", "option chains", "market data"],
-    fallbackDescription: null,
-    snoozeDurationDays: 7,
-    instructionsHint: "No account needed; OpenCandle checks public Yahoo Finance reachability",
-  },
-  {
-    id: "twitter",
-    kind: "external-tool",
-    displayName: "X / Twitter",
-    category: "sentiment",
-    tier: "soft",
-    aliases: ["twitter", "x", "x-sentiment", "twitter-sentiment"],
-    binary: "twitter",
-    installCmd: "uv tool install twitter-cli",
-    sessionSource: "browser-cookies",
-    sessionProbeArgs: ["feed", "--max", "1", "--json"],
-    supportedBrowsers: ["Chrome", "Arc", "Edge", "Firefox", "Brave"],
-    unlocks: ["X/Twitter sentiment", "recent ticker mentions", "social engagement context"],
-    fallbackDescription:
-      "Sentiment summaries continue with Reddit, web search, and news when X is unavailable",
-    snoozeDurationDays: 7,
-    instructionsHint: "Install twitter-cli and stay logged into x.com in a supported browser",
-  },
-  {
-    id: "reddit",
-    kind: "external-tool",
-    displayName: "Reddit",
-    category: "sentiment",
-    tier: "soft",
-    aliases: ["reddit", "reddit-sentiment", "subreddit"],
-    binary: "rdt",
-    installCmd: "uv tool install rdt-cli",
-    sessionSource: "browser-cookies",
-    supportedBrowsers: ["Chrome", "Arc", "Edge", "Firefox", "Brave"],
-    sessionProbeArgs: ["status", "--json"],
-    unlocks: ["Reddit sentiment", "ticker discussion context", "retail investor discussion"],
-    fallbackDescription:
-      "Sentiment summaries continue with X/Twitter, web search, and news when Reddit is unavailable",
-    snoozeDurationDays: 7,
-    instructionsHint: "Install rdt-cli and stay logged into reddit.com in a supported browser",
-  },
-] as const satisfies readonly ProviderDescriptor[];
-
-const _providerIdExhaustivenessCheck: Record<
-  | Exclude<ProviderId, (typeof PROVIDERS)[number]["id"]>
-  | Exclude<(typeof PROVIDERS)[number]["id"], ProviderId>,
-  never
-> = {};
-void _providerIdExhaustivenessCheck;
-
-// -----------------------------------------------------------------------------
-// Lookup helpers
-// -----------------------------------------------------------------------------
-
-// Lazy-built index — populated on first helper call so module import has no
-// side effects. The test `importing the registry does not read the filesystem`
-// relies on this.
-let providersById: Map<ProviderId, ProviderDescriptor> | undefined;
-
-function byId(): Map<ProviderId, ProviderDescriptor> {
-  if (!providersById) {
-    providersById = new Map(PROVIDERS.map((p) => [p.id, p]));
-  }
-  return providersById;
-}
-
-export function listAllProviders(): readonly ProviderDescriptor[] {
-  return PROVIDERS;
-}
-
-export function isApiKeyProvider(
-  provider: ProviderDescriptor,
-): provider is ApiKeyProviderDescriptor {
-  return provider.kind === "api-key";
-}
-
-export function isExternalToolProvider(
-  provider: ProviderDescriptor,
-): provider is ExternalToolProviderDescriptor {
-  return provider.kind === "external-tool";
-}
-
-export function isPublicHttpProvider(
-  provider: ProviderDescriptor,
-): provider is PublicHttpProviderDescriptor {
-  return provider.kind === "public-http";
-}
-
-export function listApiKeyProviders(): readonly ApiKeyProviderDescriptor[] {
-  return (PROVIDERS as readonly ProviderDescriptor[]).filter(isApiKeyProvider);
-}
-
-export function getProvider(id: ProviderId): ProviderDescriptor {
-  const found = byId().get(id);
-  if (!found) {
-    throw new Error(`Unknown provider id: "${id}"`);
-  }
-  return found;
-}
-
-export function getProvidersByCategory(category: ProviderCategory): readonly ProviderDescriptor[] {
-  return PROVIDERS.filter((p) => p.category === category);
-}
-
-export function getProvidersByTier(tier: ProviderTier): readonly ProviderDescriptor[] {
-  return PROVIDERS.filter((p) => p.tier === tier);
-}
-
-// -----------------------------------------------------------------------------
-// Credential source helpers
-// -----------------------------------------------------------------------------
-
-function readConfigValueByPath(
-  obj: Record<string, unknown>,
-  path: readonly string[],
-): string | undefined {
-  let cursor: unknown = obj;
-  for (const segment of path) {
-    if (cursor && typeof cursor === "object" && segment in (cursor as object)) {
-      cursor = (cursor as Record<string, unknown>)[segment];
-    } else {
-      return undefined;
-    }
-  }
-  return typeof cursor === "string" && cursor.length > 0 ? cursor : undefined;
-}
-
-// Provider-id → `Config` field mapping. `Config` (in src/config.ts) is the
-// canonical env-or-file resolved shape that tool implementations already use.
-// `hasCredential` reads from `getConfig()` so that tests mocking `getConfig`
-// see a consistent view; `getCredentialSource` reads `process.env` +
-// `loadFileConfig` directly because it needs to distinguish env from file.
-const CONFIG_FIELD_BY_ID: Record<ApiKeyProviderId, keyof ReturnType<typeof getConfig>> = {
-  alpha_vantage: "alphaVantageApiKey",
-  fred: "fredApiKey",
-  finnhub: "finnhubApiKey",
-  brave: "braveApiKey",
-  exa: "exaApiKey",
-};
-
-export function hasCredential(id: ProviderId): boolean {
-  const descriptor = getProvider(id);
-  if (!isApiKeyProvider(descriptor)) return false;
-  const field = CONFIG_FIELD_BY_ID[descriptor.id];
-  const value = getConfig()[field];
-  return typeof value === "string" && value.length > 0;
-}
-
-export function getCredentialSource(id: ProviderId): "env" | "file" | "absent" {
-  return getCredential(id).source;
-}
-
-export function getCredential(
-  id: ProviderId,
-): { source: "env" | "file"; value: string } | { source: "absent"; value?: undefined } {
-  const descriptor = getProvider(id);
-  if (!isApiKeyProvider(descriptor)) return { source: "absent" };
-
-  const envValue = process.env[descriptor.envVar];
-  if (envValue && envValue.length > 0) return { source: "env", value: envValue };
-
-  // Lazy file-config read — only invoked when env is absent.
-  const fileConfig = loadFileConfig() as unknown as Record<string, unknown>;
-  const fileValue = readConfigValueByPath(fileConfig, descriptor.configPath);
-  if (fileValue) return { source: "file", value: fileValue };
-
-  return { source: "absent" };
-}
-
-// -----------------------------------------------------------------------------
-// /connect argument resolution
-// -----------------------------------------------------------------------------
-
-export function resolveProviderFromArgument(
-  arg: string,
-): ProviderDescriptor | readonly ProviderDescriptor[] | undefined {
-  const needle = arg.trim().toLowerCase();
-  if (!needle) return undefined;
-
-  // 1. Exact provider id match (case-insensitive).
-  for (const p of PROVIDERS) {
-    if (p.id === needle) return p;
-  }
-
-  // 2. Exact alias match.
-  for (const p of PROVIDERS) {
-    if ((p.aliases as readonly string[]).includes(needle)) return p;
-  }
-
-  // 3. Category match: if the needle matches a category name, return the
-  //    providers in that category. One match → single descriptor. Multiple
-  //    matches → array (triggers the sub-picker in the /connect handler).
-  const categories: readonly ProviderCategory[] = [
-    "fundamentals",
-    "macro",
-    "news",
-    "web_search",
-    "sentiment",
-    "market",
-  ];
-  const normalizedCategory = needle.replace("-", "_");
-  if ((categories as readonly string[]).includes(normalizedCategory)) {
-    const group = getProvidersByCategory(normalizedCategory as ProviderCategory);
-    if (group.length === 1) return group[0];
-    if (group.length > 1) return group;
-  }
-
-  // 4. Special shared alias: "search" → both web_search providers.
-  if (needle === "search" || needle === "web" || needle === "web-search") {
-    const searchProviders = getProvidersByCategory("web_search");
-    if (searchProviders.length === 1) return searchProviders[0];
-    if (searchProviders.length > 1) return searchProviders;
-  }
-
-  return undefined;
-}

package/src/onboarding/state.ts

@@ -1,216 +0,0 @@
-// Onboarding state schema and pure helpers.
-//
-// Shape: one flag for the welcome message (`welcomeShownAt`) plus a partial
-// per-provider map with a proper discriminated union for status + snooze.
-//
-// All transition helpers are PURE — they return a new state object rather
-// than mutating. The caller is responsible for persisting via saveOnboardingState.
-
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { ensureParentDir, getOnboardingPath } from "../infra/opencandle-paths.js";
-import type { ProviderId } from "./providers.js";
-
-export const ONBOARDING_VERSION = 2;
-
-export type ProviderOnboardingEntry =
-  | { status: "completed"; lastPromptAt: string }
-  | { status: "snoozed"; lastPromptAt: string; snoozeUntil: string }
-  | { status: "never_ask"; lastPromptAt: string };
-
-export interface OnboardingState {
-  version: number;
-  /** ISO 8601 timestamp the welcome message was first seeded, or undefined if never. */
-  welcomeShownAt?: string;
-  providers: Partial<Record<ProviderId, ProviderOnboardingEntry>>;
-}
-
-export function getDefaultOnboardingState(): OnboardingState {
-  return { version: ONBOARDING_VERSION, providers: {} };
-}
-
-// -----------------------------------------------------------------------------
-// Load / save
-// -----------------------------------------------------------------------------
-
-const STATUS_VALUES: ReadonlySet<string> = new Set(["completed", "snoozed", "never_ask"]);
-
-function parseEntry(raw: unknown): ProviderOnboardingEntry | undefined {
-  if (!raw || typeof raw !== "object") return undefined;
-  const obj = raw as Record<string, unknown>;
-  const status = obj.status;
-  if (typeof status !== "string" || !STATUS_VALUES.has(status)) return undefined;
-  const lastPromptAt = obj.lastPromptAt;
-  if (typeof lastPromptAt !== "string") return undefined;
-
-  if (status === "snoozed") {
-    const snoozeUntil = obj.snoozeUntil;
-    if (typeof snoozeUntil !== "string") return undefined;
-    return { status: "snoozed", lastPromptAt, snoozeUntil };
-  }
-  if (status === "completed") {
-    return { status: "completed", lastPromptAt };
-  }
-  return { status: "never_ask", lastPromptAt };
-}
-
-function parseProvidersMap(raw: unknown): Partial<Record<ProviderId, ProviderOnboardingEntry>> {
-  if (!raw || typeof raw !== "object") return {};
-  const result: Partial<Record<ProviderId, ProviderOnboardingEntry>> = {};
-  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
-    const entry = parseEntry(value);
-    if (entry) result[key as ProviderId] = entry;
-  }
-  return result;
-}
-
-export function loadOnboardingState(path = getOnboardingPath()): OnboardingState {
-  if (!existsSync(path)) {
-    return getDefaultOnboardingState();
-  }
-
-  let raw: string;
-  try {
-    raw = readFileSync(path, "utf-8");
-  } catch {
-    return getDefaultOnboardingState();
-  }
-
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return getDefaultOnboardingState();
-  }
-
-  if (!parsed || typeof parsed !== "object") {
-    return getDefaultOnboardingState();
-  }
-
-  const obj = parsed as Record<string, unknown>;
-  const version = typeof obj.version === "number" ? obj.version : ONBOARDING_VERSION;
-  const welcomeShownAt = typeof obj.welcomeShownAt === "string" ? obj.welcomeShownAt : undefined;
-  const providers = parseProvidersMap(obj.providers);
-
-  return { version, welcomeShownAt, providers };
-}
-
-export function saveOnboardingState(state: OnboardingState, path = getOnboardingPath()): void {
-  ensureParentDir(path);
-  // Strip undefined fields for cleaner on-disk output.
-  const serializable: Record<string, unknown> = {
-    version: state.version,
-    providers: state.providers,
-  };
-  if (state.welcomeShownAt !== undefined) {
-    serializable.welcomeShownAt = state.welcomeShownAt;
-  }
-  writeFileSync(path, `${JSON.stringify(serializable, null, 2)}\n`, "utf-8");
-}
-
-// -----------------------------------------------------------------------------
-// Pure transitions
-// -----------------------------------------------------------------------------
-
-function nowIso(): string {
-  return new Date().toISOString();
-}
-
-export function markProviderCompleted(state: OnboardingState, id: ProviderId): OnboardingState {
-  return {
-    ...state,
-    providers: {
-      ...state.providers,
-      [id]: { status: "completed", lastPromptAt: nowIso() },
-    },
-  };
-}
-
-export function markProviderSnoozed(
-  state: OnboardingState,
-  id: ProviderId,
-  days: number,
-): OnboardingState {
-  const now = new Date();
-  const snoozeUntil = new Date(now.getTime() + days * 24 * 3600 * 1000);
-  return {
-    ...state,
-    providers: {
-      ...state.providers,
-      [id]: {
-        status: "snoozed",
-        lastPromptAt: now.toISOString(),
-        snoozeUntil: snoozeUntil.toISOString(),
-      },
-    },
-  };
-}
-
-export function markProviderNeverAsk(state: OnboardingState, id: ProviderId): OnboardingState {
-  return {
-    ...state,
-    providers: {
-      ...state.providers,
-      [id]: { status: "never_ask", lastPromptAt: nowIso() },
-    },
-  };
-}
-
-export function clearProviderOnboardingEntry(
-  state: OnboardingState,
-  id: ProviderId,
-): OnboardingState {
-  const providers = { ...state.providers };
-  delete providers[id];
-  return { ...state, providers };
-}
-
-export function markWelcomeShown(state: OnboardingState): OnboardingState {
-  return { ...state, welcomeShownAt: nowIso() };
-}
-
-// -----------------------------------------------------------------------------
-// Pure queries
-// -----------------------------------------------------------------------------
-
-export function getProviderEntry(
-  state: OnboardingState,
-  id: ProviderId,
-): ProviderOnboardingEntry | undefined {
-  return state.providers[id];
-}
-
-export interface ShouldPromptOptions {
-  /**
-   * When true, treats a `completed` entry as eligible for re-prompt. This is
-   * how stale credentials (401 after a previously-connected key) get a fresh
-   * offer.
-   */
-  stale?: boolean;
-}
-
-export function shouldPrompt(
-  state: OnboardingState,
-  id: ProviderId,
-  now: Date,
-  options: ShouldPromptOptions = {},
-): boolean {
-  const entry = state.providers[id];
-  if (!entry) return true;
-
-  switch (entry.status) {
-    case "never_ask":
-      return false;
-    case "completed":
-      return options.stale === true;
-    case "snoozed": {
-      const until = Date.parse(entry.snoozeUntil);
-      if (Number.isNaN(until)) return true;
-      return now.getTime() >= until;
-    }
-  }
-}
-
-export function shouldShowWelcome(state: OnboardingState, hasUI: boolean): boolean {
-  if (!hasUI) return false;
-  return state.welcomeShownAt === undefined;
-}