@aggc/or-info 0.1.0

package/lib/formatter.mjs

@@ -0,0 +1,178 @@
+import chalk from 'chalk';
+import { pricePerMillion, contextLength, maxOutput, modelTags, isFree } from './openrouter.mjs';
+
+const DIM = chalk.dim;
+const BOLD = chalk.bold;
+const GREEN = chalk.green;
+const YELLOW = chalk.yellow;
+const CYAN = chalk.cyan;
+const RED = chalk.red;
+const BLUE = chalk.blue;
+const MAGENTA = chalk.magenta;
+
+function fmtPrice(n) {
+  if (n === null) return DIM('n/a');
+  if (n === 0) return GREEN('free');
+  if (n < 0.1) return GREEN(`$${n.toFixed(4)}`);
+  if (n < 1) return YELLOW(`$${n.toFixed(4)}`);
+  return RED(`$${n.toFixed(4)}`);
+}
+
+function fmtCtx(n) {
+  if (!n) return DIM('n/a');
+  if (n >= 1_000_000) return CYAN(`${(n / 1_000_000).toFixed(1)}M`);
+  if (n >= 1_000) return CYAN(`${Math.round(n / 1_000)}k`);
+  return CYAN(String(n));
+}
+
+function fmtTags(tags) {
+  if (!tags.length) return '';
+  return tags.map((t) => DIM(`[${t}]`)).join(' ');
+}
+
+function pad(s, n, right = false) {
+  const str = String(s ?? '');
+  // Strip ANSI for length calculation
+  const visible = str.replace(/\x1b\[[0-9;]*m/g, '');
+  const diff = n - visible.length;
+  if (diff <= 0) return str;
+  return right ? ' '.repeat(diff) + str : str + ' '.repeat(diff);
+}
+
+export function modelTable(models, { showTags = false } = {}) {
+  if (!models.length) return DIM('No models found.');
+
+  const rows = models.map((m) => {
+    const price = pricePerMillion(m);
+    const ctx = contextLength(m);
+    const tags = showTags ? modelTags(m) : [];
+    return {
+      id: m.id,
+      name: m.name ?? m.id,
+      input: fmtPrice(price.input),
+      output: fmtPrice(price.output),
+      ctx: fmtCtx(ctx),
+      tags: fmtTags(tags),
+    };
+  });
+
+  const idW = Math.min(50, Math.max(20, ...rows.map((r) => r.id.length)));
+  const nameW = Math.min(30, Math.max(10, ...rows.map((r) => r.name.replace(/\x1b\[[0-9;]*m/g, '').length)));
+
+  const header =
+    BOLD(pad('ID', idW)) + '  ' +
+    BOLD(pad('In /M', 10, true)) + '  ' +
+    BOLD(pad('Out /M', 10, true)) + '  ' +
+    BOLD(pad('Context', 8, true));
+
+  const sep = DIM('─'.repeat(idW + 2 + 10 + 2 + 10 + 2 + 8));
+
+  const lines = rows.map((r) => {
+    const line =
+      pad(r.id, idW) + '  ' +
+      pad(r.input, 10, true) + '  ' +
+      pad(r.output, 10, true) + '  ' +
+      pad(r.ctx, 8, true);
+    return r.tags ? line + '  ' + r.tags : line;
+  });
+
+  return [header, sep, ...lines].join('\n');
+}
+
+export function modelDetail(model, bench = null) {
+  const price = pricePerMillion(model);
+  const ctx = contextLength(model);
+  const maxOut = maxOutput(model);
+  const tags = modelTags(model);
+
+  const lines = [
+    '',
+    BOLD(CYAN(model.name ?? model.id)),
+    DIM(model.id),
+    '',
+    BOLD('Pricing'),
+    `  Input   ${fmtPrice(price.input)} per 1M tokens`,
+    `  Output  ${fmtPrice(price.output)} per 1M tokens`,
+  ];
+
+  if (price.image !== null) lines.push(`  Image   ${fmtPrice(price.image)} per 1M tokens`);
+  if (price.cacheRead !== null) lines.push(`  Cache↓  ${fmtPrice(price.cacheRead)} per 1M tokens`);
+  if (price.cacheWrite !== null) lines.push(`  Cache↑  ${fmtPrice(price.cacheWrite)} per 1M tokens`);
+
+  lines.push('');
+  lines.push(BOLD('Capacity'));
+  lines.push(`  Context    ${fmtCtx(ctx)}`);
+  if (maxOut) lines.push(`  Max output ${fmtCtx(maxOut)}`);
+
+  if (tags.length) {
+    lines.push('');
+    lines.push(BOLD('Features'));
+    lines.push('  ' + tags.map((t) => BLUE(`[${t}]`)).join(' '));
+  }
+
+  const arch = model?.architecture;
+  if (arch?.modality) {
+    lines.push('');
+    lines.push(BOLD('Architecture'));
+    lines.push(`  ${DIM(arch.modality)}`);
+    if (arch.tokenizer) lines.push(`  Tokenizer: ${DIM(arch.tokenizer)}`);
+  }
+
+  if (bench) {
+    lines.push('');
+    lines.push(BOLD('LMArena ELO  ') + DIM('(lmarena.ai — human preference votes)'));
+    lines.push(`  ELO    ${YELLOW(String(bench.elo))}  ${DIM(`±${Math.round((bench.eloUpper - bench.eloLower) / 2)}`)}`);
+    lines.push(`  Rank   ${YELLOW('#' + bench.rank)}`);
+    lines.push(`  Votes  ${DIM(bench.votes.toLocaleString())}`);
+    if (bench.updatedAt) lines.push(`  ${DIM('Updated: ' + bench.updatedAt)}`);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+export function comparison(modelA, benchA, modelB, benchB) {
+  const render = (model, bench) => modelDetail(model, bench).split('\n');
+
+  const linesA = render(modelA, benchA);
+  const linesB = render(modelB, benchB);
+  const maxLines = Math.max(linesA.length, linesB.length);
+  const colW = 52;
+
+  const result = [BOLD('── Comparison ──'), ''];
+  for (let i = 0; i < maxLines; i++) {
+    const a = linesA[i] ?? '';
+    const b = linesB[i] ?? '';
+    const aVis = a.replace(/\x1b\[[0-9;]*m/g, '');
+    const padding = Math.max(0, colW - aVis.length);
+    result.push(a + ' '.repeat(padding) + DIM('│') + ' ' + b);
+  }
+  return result.join('\n');
+}
+
+export function topList(ranked) {
+  if (!ranked.length) return DIM('No results.');
+
+  const lines = [BOLD('── Top Models ──'), ''];
+  ranked.forEach(({ model, score, qualityScore, eloEntry }, i) => {
+    const price = pricePerMillion(model);
+    const medal = i === 0 ? YELLOW('#1') : i === 1 ? DIM('#2') : i === 2 ? DIM('#3') : DIM(`#${i + 1}`);
+    const eloStr = eloEntry ? DIM(`ELO ${eloEntry.elo}`) : DIM('no ELO');
+    lines.push(`${medal}  ${BOLD(CYAN(model.id))}`);
+    lines.push(`    Score ${YELLOW(score.toFixed(1))}  │  Out ${fmtPrice(price.output)}/M  │  ${eloStr}`);
+    lines.push('');
+  });
+  return lines.join('\n');
+}
+
+export function statusReport(items) {
+  const lines = [BOLD('── Cache Status ──'), ''];
+  for (const { key, exists, ageMs, fresh, ttlMs } of items) {
+    const indicator = !exists ? RED('✗ missing') : fresh ? GREEN('✓ fresh') : YELLOW('⚠ stale');
+    const age = ageMs ? `${Math.round(ageMs / 60_000)}m ago` : '—';
+    const ttl = `TTL ${Math.round(ttlMs / 60_000)}m`;
+    lines.push(`  ${pad(key, 12)} ${indicator}  ${DIM(age)}  ${DIM(ttl)}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}

package/lib/lmarena.mjs

@@ -0,0 +1,174 @@
+import { get, set, TTL } from './cache.mjs';
+import { BENCHMARKS_CACHE } from './paths.mjs';
+
+const HF_ROWS =
+  'https://datasets-server.huggingface.co/rows?dataset=lmarena-ai%2Fleaderboard-dataset&config=text&split=latest';
+const PAGE = 100;
+const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
+const MAX_FETCH_RETRIES = 2;
+
+function retryDelayMs(retryAfter, attempt) {
+  const seconds = Number(retryAfter);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+
+  const dateMs = Date.parse(retryAfter ?? '');
+  if (Number.isFinite(dateMs)) return Math.max(0, dateMs - Date.now());
+
+  return 500 * (attempt + 1);
+}
+
+async function sleep(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ── Fetch ──────────────────────────────────────────────────────────────────
+
+async function fetchPage(offset) {
+  const url = `${HF_ROWS}&offset=${offset}&length=${PAGE}`;
+  for (let attempt = 0; attempt <= MAX_FETCH_RETRIES; attempt++) {
+    let res;
+    try {
+      res = await fetch(url, {
+        headers: { 'User-Agent': 'or-info-cli/0.1.0' },
+        signal: AbortSignal.timeout(15_000),
+      });
+    } catch (err) {
+      if (attempt === MAX_FETCH_RETRIES) {
+        throw new Error(`LMArena request failed: ${err.message}`);
+      }
+      await sleep(retryDelayMs(null, attempt));
+      continue;
+    }
+
+    if (res.ok) return res.json();
+    if (attempt === MAX_FETCH_RETRIES || !RETRYABLE_STATUSES.has(res.status)) {
+      throw new Error(`LMArena fetch ${res.status}: ${res.statusText}`);
+    }
+
+    await sleep(retryDelayMs(res.headers.get('retry-after'), attempt));
+  }
+
+  throw new Error('LMArena request failed: exhausted retries');
+}
+
+// Fetch all rows where category === 'overall'.
+// The dataset is sorted so 'overall' rows appear first; we stop
+// as soon as we see a different category.
+async function fetchAllOverall() {
+  const entries = [];
+  let offset = 0;
+
+  while (true) {
+    const page = await fetchPage(offset);
+    const rows = page.rows ?? [];
+    if (!rows.length) break;
+
+    let sawOther = false;
+    for (const { row } of rows) {
+      if (row.category !== 'overall') { sawOther = true; break; }
+      entries.push({
+        lmarenaName: row.model_name,
+        elo: Math.round(row.rating),
+        eloLower: Math.round(row.rating_lower),
+        eloUpper: Math.round(row.rating_upper),
+        votes: Math.round(row.vote_count),
+        rank: Math.round(row.rank),
+        updatedAt: row.leaderboard_publish_date,
+      });
+    }
+    if (sawOther) break;
+    offset += PAGE;
+    if (offset >= (page.num_rows_total ?? Infinity)) break;
+  }
+  return entries;
+}
+
+// ── Name normalisation ─────────────────────────────────────────────────────
+
+// Normalise a name for fuzzy matching.
+// Rules (applied in order):
+//   1. Lowercase
+//   2. Dots → hyphens   (4.6 → 4-6)
+//   3. Remove date suffixes like -20250929 or -2025-09-29
+//   4. Collapse multiple hyphens
+function normalise(name) {
+  return name
+    .toLowerCase()
+    .replace(/\./g, '-')
+    .replace(/-20\d{2}-?\d{2}-?\d{2,}(-.+)?$/, '')
+    .replace(/-{2,}/g, '-')
+    .trim();
+}
+
+// Extract the "slug" portion of an OpenRouter model ID (after the provider /).
+// openai/gpt-4o  →  gpt-4o
+// anthropic/claude-opus-4.6  →  claude-opus-4-6  (after normalise)
+function orSlug(id) {
+  return normalise(id.includes('/') ? id.split('/').slice(1).join('/') : id);
+}
+
+// Build a lookup Map from normalised LMArena name → entry.
+// Also index by the last "segment" after the last '-' number group
+// to help with partial matches.
+function buildIndex(entries) {
+  const exact = new Map();
+  for (const e of entries) {
+    exact.set(normalise(e.lmarenaName), e);
+  }
+  return exact;
+}
+
+// Find the best matching LMArena entry for an OpenRouter model ID.
+// Returns the entry or null.
+function match(orId, index) {
+  const slug = orSlug(orId);
+
+  // 1. Exact slug match
+  if (index.has(slug)) return index.get(slug);
+
+  // 2. The OpenRouter slug contains the LMArena key as a substring
+  //    e.g. OR "deepseek-chat-v3-0324" ⊇ LMArena "v3-0324"  (too short, skip < 8 chars)
+  for (const [key, entry] of index) {
+    if (key.length >= 8 && slug.includes(key)) return entry;
+  }
+
+  // 3. The LMArena key contains the OR slug
+  for (const [key, entry] of index) {
+    if (slug.length >= 8 && key.includes(slug)) return entry;
+  }
+
+  // 4. Full OR ID normalised (keeping provider prefix stripped differently)
+  const fullNorm = normalise(orId.replace('/', '-'));
+  if (index.has(fullNorm)) return index.get(fullNorm);
+
+  return null;
+}
+
+// ── Public API ─────────────────────────────────────────────────────────────
+
+let _index = null;
+
+export async function loadLeaderboard({ force = false } = {}) {
+  if (!force) {
+    const cached = await get(BENCHMARKS_CACHE, TTL.BENCHMARKS);
+    if (cached?.entries) {
+      _index = buildIndex(cached.entries);
+      return cached.entries;
+    }
+  }
+
+  const entries = await fetchAllOverall();
+  await set(BENCHMARKS_CACHE, { entries, fetchedAt: Date.now() });
+  _index = buildIndex(entries);
+  return entries;
+}
+
+export async function getElo(orModelId, { force = false } = {}) {
+  if (!_index || force) await loadLeaderboard({ force });
+  return match(orModelId, _index);
+}
+
+export async function getAllElo({ force = false } = {}) {
+  const entries = await loadLeaderboard({ force });
+  return entries; // [{lmarenaName, elo, eloLower, eloUpper, votes, rank, updatedAt}]
+}

package/lib/openrouter.mjs

@@ -0,0 +1,125 @@
+import { get, set, TTL } from './cache.mjs';
+import { MODELS_CACHE } from './paths.mjs';
+
+const OR_BASE = 'https://openrouter.ai/api/v1';
+const USER_AGENT = 'or-info-cli/0.1.0 (https://github.com/jmtrs/or-info)';
+const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
+const MAX_FETCH_RETRIES = 2;
+
+function retryDelayMs(retryAfter, attempt) {
+  const seconds = Number(retryAfter);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+
+  const dateMs = Date.parse(retryAfter ?? '');
+  if (Number.isFinite(dateMs)) return Math.max(0, dateMs - Date.now());
+
+  return 500 * (attempt + 1);
+}
+
+async function sleep(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function fetchJson(url, apiKey) {
+  const headers = { 'User-Agent': USER_AGENT };
+  if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`;
+
+  for (let attempt = 0; attempt <= MAX_FETCH_RETRIES; attempt++) {
+    let res;
+    try {
+      res = await fetch(url, { headers });
+    } catch (err) {
+      if (attempt === MAX_FETCH_RETRIES) {
+        throw new Error(`OpenRouter request failed: ${err.message}`);
+      }
+      await sleep(retryDelayMs(null, attempt));
+      continue;
+    }
+
+    if (res.ok) return res.json();
+
+    let message = res.statusText;
+    try {
+      const body = await res.json();
+      message = body?.error?.message || body?.message || message;
+    } catch {}
+
+    if (attempt === MAX_FETCH_RETRIES || !RETRYABLE_STATUSES.has(res.status)) {
+      throw new Error(`OpenRouter ${res.status}: ${message}`);
+    }
+
+    await sleep(retryDelayMs(res.headers.get('retry-after'), attempt));
+  }
+
+  throw new Error('OpenRouter request failed: exhausted retries');
+}
+
+export async function fetchModels({ apiKey, force = false } = {}) {
+  if (!force) {
+    const cached = await get(MODELS_CACHE, TTL.MODELS);
+    if (cached?.data) return cached.data;
+  }
+  const fresh = await fetchJson(`${OR_BASE}/models`, apiKey);
+  await set(MODELS_CACHE, fresh);
+  return fresh.data ?? [];
+}
+
+export function findModel(models, id) {
+  return models.find((m) => m?.id === id) ?? null;
+}
+
+export function pricePerMillion(model) {
+  const p = model?.pricing ?? {};
+  const toM = (v) => {
+    const n = Number(v);
+    return Number.isFinite(n) && n >= 0 ? n * 1_000_000 : null;
+  };
+  return {
+    input: toM(p.prompt),
+    output: toM(p.completion),
+    image: toM(p.image),
+    cacheRead: toM(p.input_cache_read),
+    cacheWrite: toM(p.input_cache_write),
+  };
+}
+
+export function contextLength(model) {
+  const raw = model?.top_provider?.context_length ?? model?.context_length;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+export function maxOutput(model) {
+  const n = Number(model?.top_provider?.max_completion_tokens);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+export function supportsFeature(model, feature) {
+  const params = Array.isArray(model?.supported_parameters) ? model.supported_parameters : [];
+  const featureMap = {
+    reasoning: ['include_reasoning', 'reasoning'],
+    tools: ['tools', 'tool_choice'],
+    vision: () => (model?.architecture?.input_modalities ?? []).includes('image'),
+    structured: ['structured_outputs'],
+  };
+  const check = featureMap[feature];
+  if (typeof check === 'function') return check();
+  if (Array.isArray(check)) return check.some((f) => params.includes(f));
+  return params.includes(feature);
+}
+
+export function modelTags(model) {
+  const tags = [];
+  if (supportsFeature(model, 'reasoning')) tags.push('reasoning');
+  if (supportsFeature(model, 'tools')) tags.push('tools');
+  if (supportsFeature(model, 'vision')) tags.push('vision');
+  if (supportsFeature(model, 'structured')) tags.push('structured');
+  const ctx = contextLength(model);
+  if (ctx && ctx >= 128_000) tags.push('long-context');
+  return tags;
+}
+
+export function isFree(model) {
+  const p = pricePerMillion(model);
+  return p.input === 0 && p.output === 0;
+}

package/lib/paths.mjs

@@ -0,0 +1,53 @@
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+function cleanEnvPath(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+export function resolveAppPaths({
+  platform = process.platform,
+  env = process.env,
+  homeDir = homedir(),
+} = {}) {
+  const pathApi = platform === 'win32' ? path.win32 : path.posix;
+  const join = pathApi.join;
+  const resolve = pathApi.resolve;
+  const configOverride = cleanEnvPath(env.OR_INFO_CONFIG_DIR);
+  const cacheOverride = cleanEnvPath(env.OR_INFO_CACHE_DIR);
+
+  let defaultConfigRoot;
+  let defaultCacheRoot;
+
+  if (platform === 'win32') {
+    defaultConfigRoot = cleanEnvPath(env.APPDATA) ?? join(homeDir, 'AppData', 'Roaming');
+    defaultCacheRoot =
+      cleanEnvPath(env.LOCALAPPDATA) ??
+      cleanEnvPath(env.APPDATA) ??
+      join(homeDir, 'AppData', 'Local');
+  } else {
+    defaultConfigRoot = cleanEnvPath(env.XDG_CONFIG_HOME) ?? join(homeDir, '.config');
+    defaultCacheRoot = cleanEnvPath(env.XDG_CACHE_HOME) ?? join(homeDir, '.cache');
+  }
+
+  const configDir = resolve(configOverride ?? join(defaultConfigRoot, 'or-info'));
+  const cacheDir = resolve(cacheOverride ?? join(defaultCacheRoot, 'or-info'));
+  const envFile = join(configDir, '.env');
+
+  return {
+    configDir,
+    cacheDir,
+    envFile,
+    files: {
+      modelsCache: join(cacheDir, 'models.json'),
+      benchmarksCache: join(cacheDir, 'benchmarks.json'),
+    },
+  };
+}
+
+export const APP_PATHS = resolveAppPaths();
+export const CONFIG_DIR = APP_PATHS.configDir;
+export const CACHE_DIR = APP_PATHS.cacheDir;
+export const ENV_FILE = APP_PATHS.envFile;
+export const MODELS_CACHE = APP_PATHS.files.modelsCache;
+export const BENCHMARKS_CACHE = APP_PATHS.files.benchmarksCache;

package/lib/scorer.mjs

@@ -0,0 +1,81 @@
+import { pricePerMillion, supportsFeature } from './openrouter.mjs';
+
+// ELO range observed on LMArena (2026): ~1050 (weak) to ~1500 (best)
+const ELO_MIN = 1050;
+const ELO_MAX = 1500;
+
+function normaliseElo(elo) {
+  return Math.max(0, Math.min(100, ((elo - ELO_MIN) / (ELO_MAX - ELO_MIN)) * 100));
+}
+
+// Returns a penalty factor [0, 1] based on output price.
+// Free models → 1.0 (no penalty)
+// Very cheap (<$0.5/M) → near 1.0
+// Expensive (>$20/M) → significantly penalised
+function pricePenalty(outputPerM) {
+  if (outputPerM === null || outputPerM === 0) return 1.0;
+  // log-scale penalty: $1/M → 0.93, $5/M → 0.83, $20/M → 0.72
+  return Math.max(0.1, 1 - Math.log10(outputPerM + 1) * 0.15);
+}
+
+function requiresCapability(task) {
+  if (task === 'vision') return 'vision';
+  if (task === 'coding') return 'tools';
+  return null;
+}
+
+// Score a model for a task.
+// Returns { score, qualityScore } or null if not eligible.
+export function scoreForTask(model, eloEntry, task = 'general') {
+  const cap = requiresCapability(task);
+  if (cap && !supportsFeature(model, cap)) return null;
+  if (!eloEntry?.elo) return null;
+
+  const quality = normaliseElo(eloEntry.elo);
+  const price = pricePerMillion(model);
+  const penalty = task === 'cheap'
+    ? pricePenalty(price.output) * 1.4   // aggressively favour cheap
+    : pricePenalty(price.output);
+
+  return {
+    score: Math.round(quality * penalty * 10) / 10,
+    qualityScore: Math.round(quality * 10) / 10,
+  };
+}
+
+export function rankModels(models, allElo, { task = 'general', maxPricePerMOutput, limit = 5 } = {}) {
+  // Build a fast ELO lookup by OR model ID using the same normalisation
+  // as lmarena.mjs.  We re-use getElo lazily per model here.
+  const scored = [];
+
+  for (const model of models) {
+    // Find this model's ELO entry (allElo is the raw entries array)
+    const eloEntry = allElo.find
+      ? allElo.find((e) => _matchName(e.lmarenaName, model.id))
+      : null;
+
+    const result = scoreForTask(model, eloEntry, task);
+    if (!result) continue;
+
+    const price = pricePerMillion(model);
+    if (maxPricePerMOutput !== undefined && price.output !== null && price.output > maxPricePerMOutput) continue;
+
+    scored.push({ model, score: result.score, qualityScore: result.qualityScore, eloEntry });
+  }
+
+  return scored.sort((a, b) => b.score - a.score).slice(0, limit);
+}
+
+// Inline minimal name matching (mirrors lmarena.mjs logic without importing it)
+function _norm(s) {
+  return s.toLowerCase().replace(/\./g, '-').replace(/-20\d{2}-?\d{2}-?\d{2,}(-.+)?$/, '').replace(/-{2,}/g, '-');
+}
+
+function _matchName(lmarenaName, orId) {
+  const lm = _norm(lmarenaName);
+  const slug = _norm(orId.includes('/') ? orId.split('/').slice(1).join('/') : orId);
+  if (lm === slug) return true;
+  if (slug.length >= 8 && slug.includes(lm)) return true;
+  if (lm.length >= 8 && lm.includes(slug)) return true;
+  return false;
+}

package/lib/secrets.mjs

@@ -0,0 +1,41 @@
+import fs from 'node:fs/promises';
+import { ENV_FILE } from './paths.mjs';
+
+const ENV_LINE_RE = /^\s*([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
+
+function unquote(v) {
+  const t = v.trim();
+  if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+    return t.slice(1, -1);
+  }
+  return t;
+}
+
+async function parseEnvFile(file) {
+  try {
+    const text = await fs.readFile(file, 'utf8');
+    const out = {};
+    for (const raw of text.split(/\r?\n/)) {
+      const line = raw.trim();
+      if (!line || line.startsWith('#')) continue;
+      const m = line.match(ENV_LINE_RE);
+      if (m) out[m[1]] = unquote(m[2]);
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+export async function loadEnv() {
+  const fileVars = await parseEnvFile(ENV_FILE);
+  // Process env takes precedence over file so users can override with shell exports
+  return { ...fileVars, ...Object.fromEntries(
+    Object.entries(process.env).filter(([k]) => k.startsWith('OPENROUTER_'))
+  )};
+}
+
+export async function getApiKey() {
+  const env = await loadEnv();
+  return env.OPENROUTER_API_KEY || null;
+}