@ateriss_/aiv-cli 0.1.0

package/src/i18n/es.ts

@@ -0,0 +1,203 @@
+import { TranslationKeys } from './en';
+
+export const es: TranslationKeys = {
+  // ── General ────────────────────────────────────────────────────────────────
+  notInitialized: 'No inicializado. Ejecuta `aiv init` primero.',
+  invalidProvider: 'Proveedor inválido. Elige: claude, openai, mock',
+  invalidPrNumber: 'Número de PR inválido.',
+  repoNotDetected: 'No se pudo detectar el repositorio. Usa --owner y --repo o configúralo en .aiv/config.yml',
+
+  // ── init ───────────────────────────────────────────────────────────────────
+  initAlreadyDone: 'aiv ya está inicializado. Usa --force para reinicializar.',
+  initTitle: '  aiv — Revisor de PRs con IA\n',
+  initWritingGlobalConfig: 'Escribiendo config global (~/.aiv/config.yml)...',
+  initGlobalConfigCreated: 'Config global creada (~/.aiv/config.yml)',
+  initGlobalConfigExists: 'La config global ya existe (~/.aiv/config.yml)',
+  initWritingConfig: 'Escribiendo config del repo (.aiv/config.yml)...',
+  initConfigCreated: 'Config del repo creada (.aiv/config.yml)',
+  initRulesCreated: 'rules.yml creado',
+  initScanningTree: 'Escaneando estructura del proyecto...',
+  initTreeCreated: 'tree.json creado',
+  initTreeSkipped: 'tree.json omitido (no se pudo escanear)',
+  initBuildingContext: 'Construyendo contexto del proyecto...',
+  initContextCreated: 'context.md creado',
+  initContextSkipped: 'context.md omitido (no se pudo analizar)',
+  initGitignoreUpdated: '.gitignore actualizado',
+  initSuccessTitle: '\n  ¡Inicializado! Próximos pasos:\n',
+  initStep1: (envVar: string) => `  Configura tu API key:    export ${envVar}=tu-clave`,
+  initStep2: (envVar: string) => `  Configura GitHub token:  export ${envVar}=tu-token`,
+  initStep3: '  Listar PRs:              aiv prs',
+  initStep4: '  Revisar un PR:           aiv review <numero-pr>',
+  initEditContext: (path: string) => `  Edita ${path} para agregar contexto de negocio.`,
+  initEditRules: (path: string) => `  Edita ${path} para definir tus reglas.`,
+  initGlobalHint: '  Config global: ~/.aiv/config.yml',
+  initAddAccountHint: '  Agregar cuentas: aiv config add-account <nombre> --token-env <VAR>',
+
+  // ── selector ───────────────────────────────────────────────────────────────
+  selectorSelectPR: 'Selecciona un PR para revisar:',
+  selectorConfirmReview: 'Revisar',
+  selectorCancelled: '  Cancelado.\n',
+
+  // ── prs ────────────────────────────────────────────────────────────────────
+  prsFetching: (repo: string) => `Obteniendo PRs de ${repo}...`,
+  prsNoneFound: '\n  No se encontraron pull requests abiertos.\n',
+  prsColPR: 'PR',
+  prsColTitle: 'Título',
+  prsColAuthor: 'Autor',
+  prsColBranch: 'Rama',
+  prsColChanges: 'Cambios',
+  prsColCreated: 'Creado',
+  prsFooter: (count: number) => `  Mostrando ${count} PR(s) abierto(s). Ejecuta aiv review <numero-pr> para analizar.\n`,
+  prsMissingToken: (envVar: string) => `Variable de entorno faltante: ${envVar}. Configura tu GitHub token.`,
+  prsFailed: (msg: string) => `Error: ${msg}`,
+
+  // ── review ─────────────────────────────────────────────────────────────────
+  reviewTitle: (n: number) => `\n  aiv review — PR #${n}\n`,
+  reviewFetching: (n: number, repo: string) => `Obteniendo PR #${n} de ${repo}...`,
+  reviewLoaded: (title: string, files: number) => `PR cargado: ${title} (${files} archivos)`,
+  reviewFetchFailed: (msg: string) => `Error al obtener el PR: ${msg}`,
+  reviewLoadingContext: 'Cargando contexto del proyecto...',
+  reviewContextLoaded: 'Contexto cargado',
+  reviewRunningAgents: (agents: string) => `\n  Ejecutando agentes: ${agents}\n`,
+  reviewFailed: (msg: string) => `\n  Revisión fallida: ${msg}\n`,
+  reviewAccount: (name: string, envVar: string) => `Cuenta: ${name} (${envVar})`,
+
+  // ── context ────────────────────────────────────────────────────────────────
+  contextRefreshTitle: '\n  Actualizando contexto...\n',
+  contextScanningTree: 'Escaneando estructura del proyecto...',
+  contextTreeUpdated: 'tree.json actualizado',
+  contextTreeFailed: (msg: string) => `tree.json falló: ${msg}`,
+  contextRebuildingCtx: 'Reconstruyendo context.md...',
+  contextCtxUpdated: 'context.md actualizado',
+  contextCtxFailed: (msg: string) => `context.md falló: ${msg}`,
+  contextEditHint: (path: string) => `\n  Edita ${path} para agregar contexto personalizado.\n`,
+  contextNoFile: 'No se encontró context.md. Ejecuta `aiv context refresh`.',
+
+  // ── config ─────────────────────────────────────────────────────────────────
+  configGlobalTitle: '  ~/.aiv/config.yml  (global)',
+  configNotCreated: '  (aún no creado)',
+  configRepoConfigTitle: '  .aiv/config.yml  (repo)',
+  configRulesTitle: '  .aiv/rules.yml',
+  configProviderSet: (p: string) => `  Proveedor predeterminado: ${p}`,
+  configRepoSet: (o: string, r: string) => `  Repositorio configurado: ${o}/${r}`,
+  configNoRules: '  No se encontró rules.yml.',
+  configLangSet: (lang: string) => `  Idioma configurado: ${lang}`,
+  configInvalidLang: 'Idioma inválido. Elige: en, es',
+  configTokenEnvHint: (v: string) => `  Variable de token: ${v}`,
+  configUsernameHint: (u: string) => `  Usuario: ${u}`,
+  configRepoAccountHint: (a: string) => `  Cuenta del repo:   ${a}`,
+  configSavedToRepo: '  Guardado en .aiv/config.yml',
+
+  // ── accounts ───────────────────────────────────────────────────────────────
+  accountsTitle: '\n  Cuentas de GitHub\n',
+  accountsNone: '  Sin cuentas configuradas. Agrega una con: aiv config add-account <nombre>',
+  accountsColName: 'Nombre',
+  accountsColUser: 'Usuario',
+  accountsColEnvVar: 'Variable Token',
+  accountsColToken: 'Token',
+  accountsColDesc: 'Descripción',
+  accountsColDefault: 'Default',
+  accountsTokenFound: 'encontrado',
+  accountsTokenMissing: 'no encontrado',
+  accountsDefaultMark: '✔ default',
+  accountsAdded: (name: string) => `  Cuenta "${name}" agregada a la config global.`,
+  accountsRemoved: (name: string) => `  Cuenta "${name}" eliminada.`,
+  accountsDefaultSet: (name: string) => `  Cuenta predeterminada: ${name}`,
+  accountsRepoSet: (name: string) => `  Este repo usará la cuenta: ${name}`,
+  accountsNotFound: (name: string) => `  Cuenta "${name}" no encontrada.`,
+  accountsAlreadyExists: (name: string) => `  La cuenta "${name}" ya existe. Usa --force para sobreescribir.`,
+  accountsGlobalHint: '\n  Config global: ~/.aiv/config.yml',
+  accountsRepoHint: '  Config repo:   .aiv/config.yml\n',
+
+  // ── orchestrator ───────────────────────────────────────────────────────────
+  orchestratorRunning: (agent: string) => `  Ejecutando agente ${agent}...`,
+  orchestratorDone: (agent: string, count: number, score: number) => `  ${agent} — ${count} hallazgo(s) [puntuación: ${score}]`,
+  orchestratorAgentFailed: (agent: string, msg: string) => `  ${agent} falló: ${msg}`,
+  orchestratorFailedMsg: (msg: string) => `Agente falló: ${msg}`,
+  orchestratorFailedUnexpected: 'El agente falló inesperadamente.',
+  orchestratorOverallRisk: (label: string, score: number, total: number, agents: number) =>
+    `Riesgo general: ${label} (${score}/100). ${total} hallazgo(s) en ${agents} agente(s).`,
+  orchestratorCriticalFound: (count: number) => `${count} problema(s) de nivel alto/crítico requieren atención.`,
+  orchestratorNoCritical: 'No se detectaron problemas críticos.',
+
+  // ── renderer ───────────────────────────────────────────────────────────────
+  renderRiskScore: 'Riesgo:',
+  renderGenerated: 'Generado:',
+  renderExecutiveSummary: '  Resumen Ejecutivo',
+  renderSecurityIssues: '  Problemas de Seguridad',
+  renderBusinessRisks: '  Riesgos de Negocio',
+  renderArchitectureIssues: '  Problemas Arquitectónicos',
+  renderRegressions: '  Posibles Regresiones',
+  renderAgentSummaries: '  Resúmenes por Agente',
+  renderReviewTitle: (n: number, title: string) => `  Revisión: PR #${n} — ${title}`,
+  renderSuggestion: 'Sugerencia:',
+  severityCritical: 'CRÍTICO',
+  severityHigh: 'ALTO',
+  severityMedium: 'MEDIO',
+  severityLow: 'BAJO',
+  severityInfo: 'INFO',
+
+  // ── errors from config layer ────────────────────────────────────────────────
+  errorMissingToken: (envVar: string, account: string) => `Variable de entorno faltante: ${envVar} (cuenta: ${account})`,
+  errorAccountNotFound: (name: string) => `Cuenta "${name}" no encontrada.`,
+  errorAccountNotFoundGlobal: (name: string) =>
+    `Cuenta "${name}" no encontrada en la config global. Agrégala primero con: aiv config add-account ${name}`,
+
+  // ── custom providers ──────────────────────────────────────────────────────
+  customProviderAdded: (name: string) => `  Provider "${name}" agregado a la config global.`,
+  customProviderRemoved: (name: string) => `  Provider "${name}" eliminado.`,
+  customProviderNotFound: (name: string) => `  Provider "${name}" no encontrado en custom_providers.`,
+  customProviderAlreadyExists: (name: string) => `  Provider "${name}" ya existe. Usa --force para sobreescribir.`,
+  customProviderBaseUrlRequired: '  --base-url es requerido para providers personalizados.',
+  customProviderTitle: '\n  Providers Personalizados (compatibles con OpenAI)\n',
+  customProviderNone: '  Sin providers personalizados. Agrega uno con: aiv config add-provider <nombre> --base-url <url> --api-key-env <VAR> --model <modelo>',
+  customProviderColName: 'Nombre',
+  customProviderColUrl: 'Base URL',
+  customProviderColModel: 'Modelo',
+  customProviderColEnvVar: 'Var Token',
+  customProviderColToken: 'Token',
+  builtinProviderSet: (name: string, model: string, envVar: string) => `  ${name}: model=${model}, key_env=${envVar}`,
+
+  // ── provider routing ───────────────────────────────────────────────────────
+  providerFallback: (from: string, to: string) => `Provider "${from}" excedió su cuota/límite — cambiando a "${to}"`,
+  providerAllFailed: 'Todos los providers en la cadena de fallback fallaron. Revisa tus API keys y cuotas.',
+  configAgentProviderSet: (agent: string, spec: string) => `  El agente "${agent}" usará: ${spec}`,
+  configFallbackSet: (chain: string) => `  Cadena de fallback configurada: ${chain}`,
+  configFallbackCleared: '  Cadena de fallback eliminada.',
+  configAgentProviderShow: '\n  Providers por agente\n',
+  configAgentProviderNone: '  Sin providers por agente. Todos usan el provider predeterminado.',
+  configInvalidAgentName: (name: string) => `  Agente desconocido: "${name}". Válidos: business, architecture, security, context`,
+  configInvalidProviderSpec: (spec: string) => `  Spec inválido: "${spec}". Formato: provider o provider/modelo (ej. claude/claude-haiku-4-5)`,
+
+  // ── post-review action ─────────────────────────────────────────────────────
+  postReviewSelectAction: '¿Qué deseas hacer con este PR?',
+  postReviewSubmitting: 'Enviando revisión a GitHub...',
+  postReviewApproved: (n: number) => `  PR #${n} aprobado en GitHub.`,
+  postReviewChangesRequested: (n: number) => `  Se solicitaron cambios en el PR #${n}.`,
+  postReviewFailed: (msg: string) => `Error al enviar la revisión: ${msg}`,
+  postReviewRefreshing: 'Actualizando contexto del proyecto...',
+  postReviewRefreshed: 'Contexto actualizado.',
+
+  // ── context generate ───────────────────────────────────────────────────────
+  contextGenerateTitle: '\n  Generando contexto y reglas con IA...\n',
+  contextGenerating: 'Analizando proyecto con IA...',
+  contextGenerateDone: 'Listo. Edita los archivos si es necesario.',
+  contextGenerateFailed: (msg: string) => `Generación fallida: ${msg}`,
+  contextGenerateConfirmOverwrite: (file: string) => `${file} ya existe. ¿Sobreescribir?`,
+  contextGenerateSkipped: (file: string) => `  ${file} omitido (se conservó el existente).`,
+  contextGenerateWritten: (file: string) => `  ${file} escrito.`,
+  contextGenerateProviderError: (envVar: string) => `Clave de IA faltante: ${envVar}. Revisa tu config de proveedor.`,
+
+  // ── agents command ─────────────────────────────────────────────────────────
+  agentsTitle: '\n  aiv — Agentes Disponibles\n',
+  agentsColAgent: 'Agente',
+  agentsColDesc: 'Descripción',
+  agentsColFocus: 'Áreas de Enfoque',
+  agentsFooter: 'Ejecuta agentes específicos: aiv review <pr> --agent business security',
+  agentBusinessDesc: 'Analiza lógica de negocio, reglas de dominio y corrección funcional',
+  agentBusinessFocus: 'Lógica de negocio, invariantes de dominio, violaciones de reglas, regresiones funcionales',
+  agentArchDesc: 'Revisa patrones estructurales, acoplamiento de módulos y decisiones de diseño',
+  agentArchFocus: 'Violaciones de capas, acoplamiento, SRP, dirección de dependencias, calidad de abstracciones',
+  agentSecDesc: 'Detecta vulnerabilidades de seguridad y riesgos de exposición de datos',
+  agentSecFocus: 'Bypass de autenticación, inyección, filtración de datos, OWASP Top 10, datos sensibles',
+};

package/src/i18n/index.ts

@@ -0,0 +1,57 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { en, TranslationKeys } from './en';
+import { es } from './es';
+
+export type SupportedLang = 'en' | 'es';
+
+const translations: Record<SupportedLang, TranslationKeys> = { en, es };
+
+let _lang: SupportedLang = 'en';
+
+export function initLang(): void {
+  // 1. AIV_LANG env var — instant override
+  const envLang = process.env['AIV_LANG'];
+  if (envLang && isSupported(envLang)) {
+    _lang = envLang;
+    return;
+  }
+
+  // 2. Global config (~/.aiv/config.yml) — lang is a global setting
+  try {
+    const globalConfig = path.join(os.homedir(), '.aiv', 'config.yml');
+    if (fs.existsSync(globalConfig)) {
+      const content = fs.readFileSync(globalConfig, 'utf8');
+      const match = /^\s*lang:\s*['"]?(\w+)['"]?\s*$/m.exec(content);
+      if (match && isSupported(match[1])) {
+        _lang = match[1];
+        return;
+      }
+    }
+  } catch { /* unreadable — continue */ }
+
+  // 3. System locale fallback
+  const sysLang = process.env['LANG'] ?? process.env['LANGUAGE'] ?? '';
+  if (sysLang.startsWith('es')) {
+    _lang = 'es';
+  }
+}
+
+export function setLang(lang: SupportedLang): void {
+  _lang = lang;
+}
+
+export function getLang(): SupportedLang {
+  return _lang;
+}
+
+export function t(): TranslationKeys {
+  return translations[_lang] ?? en;
+}
+
+export function isSupported(lang: string): lang is SupportedLang {
+  return lang === 'en' || lang === 'es';
+}
+
+export const SUPPORTED_LANGS: SupportedLang[] = ['en', 'es'];

package/src/index.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { initLang } from './i18n';
+import { printBanner } from './cli/banner';
+import { initCommand } from './cli/commands/init';
+import { prsCommand } from './cli/commands/prs';
+import { reviewCommand } from './cli/commands/review';
+import { contextCommand } from './cli/commands/context';
+import { configCommand } from './cli/commands/config';
+import { agentsCommand } from './cli/commands/agents';
+
+initLang();
+printBanner();
+
+const program = new Command();
+
+program
+  .name('aiv')
+  .description('AI-powered PR reviewer — local-first, multi-agent semantic analysis')
+  .version('0.1.0');
+
+program.addCommand(initCommand());
+program.addCommand(prsCommand());
+program.addCommand(reviewCommand());
+program.addCommand(contextCommand());
+program.addCommand(configCommand());
+program.addCommand(agentsCommand());
+
+program.parse(process.argv);

package/src/orchestrator/index.ts

@@ -0,0 +1,110 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { ResolvedConfig, AivRules, PRDiff, ReviewResult, AgentFinding } from '../types';
+import { createProviderFor } from '../providers/factory';
+import { BusinessReviewer } from '../agents/business';
+import { ArchitectureReviewer } from '../agents/architecture';
+import { SecurityReviewer } from '../agents/security';
+import { BaseAgent, AgentContext } from '../agents/base';
+import { t } from '../i18n';
+
+export class Orchestrator {
+  constructor(
+    private readonly config: ResolvedConfig,
+    private readonly rules: AivRules,
+  ) {}
+
+  async run(prDiff: PRDiff, projectContext: string, agentNames: string[]): Promise<ReviewResult> {
+    const agents = buildAgents(agentNames, this.config);
+
+    const agentCtx: AgentContext = { diff: prDiff, projectContext, rules: this.rules };
+    const agentResults = await runAgents(agents, agentCtx);
+
+    const overallScore = computeOverallScore(agentResults.map(r => r.riskScore));
+    const regressions = agentResults.flatMap(r => (r as any).possibleRegressions ?? []) as string[];
+
+    return {
+      prNumber: prDiff.pr.number,
+      prTitle: prDiff.pr.title,
+      executiveSummary: buildExecutiveSummary(agentResults, overallScore),
+      riskScore: overallScore,
+      riskLabel: scoreToLabel(overallScore),
+      agents: agentResults,
+      businessRisks: agentResults.find(r => r.agentName === 'business')?.findings ?? [],
+      architectureIssues: agentResults.find(r => r.agentName === 'architecture')?.findings ?? [],
+      securityIssues: agentResults.find(r => r.agentName === 'security')?.findings ?? [],
+      possibleRegressions: regressions,
+      generatedAt: new Date().toISOString(),
+    };
+  }
+}
+
+function buildAgents(names: string[], config: ResolvedConfig): BaseAgent[] {
+  const map: Record<string, (p: ReturnType<typeof createProviderFor>) => BaseAgent> = {
+    business:     p => new BusinessReviewer(p),
+    architecture: p => new ArchitectureReviewer(p),
+    security:     p => new SecurityReviewer(p),
+  };
+  return names.filter(n => n in map).map(n => map[n](createProviderFor(config, n)));
+}
+
+async function runAgents(agents: BaseAgent[], ctx: AgentContext) {
+  const results = await Promise.allSettled(
+    agents.map(async agent => {
+      const spinner = ora(t().orchestratorRunning(chalk.cyan(agent.agentName))).start();
+      try {
+        const result = await agent.run(ctx);
+        spinner.succeed(t().orchestratorDone(chalk.cyan(agent.agentName), result.findings.length, result.riskScore));
+        return result;
+      } catch (e: any) {
+        spinner.fail(chalk.red(t().orchestratorAgentFailed(chalk.cyan(agent.agentName), e.message)));
+        return {
+          agentName: agent.agentName,
+          findings: [],
+          summary: t().orchestratorFailedMsg(e.message),
+          riskScore: 0,
+        };
+      }
+    })
+  );
+
+  return results.map(r =>
+    r.status === 'fulfilled'
+      ? r.value
+      : { agentName: 'unknown', findings: [], summary: t().orchestratorFailedUnexpected, riskScore: 0 }
+  );
+}
+
+function computeOverallScore(scores: number[]): number {
+  if (scores.length === 0) return 0;
+  const max = Math.max(...scores);
+  const avg = scores.reduce((a, b) => a + b, 0) / scores.length;
+  return Math.round(max * 0.6 + avg * 0.4);
+}
+
+function buildExecutiveSummary(
+  agents: Array<{ agentName: string; summary: string; riskScore: number; findings: AgentFinding[] }>,
+  overallScore: number,
+): string {
+  const label = scoreToLabel(overallScore);
+  const totalFindings = agents.reduce((acc, a) => acc + a.findings.length, 0);
+  const critical = agents.flatMap(a => a.findings).filter(f => f.severity === 'critical' || f.severity === 'high').length;
+
+  const criticalLine = critical > 0
+    ? t().orchestratorCriticalFound(critical)
+    : t().orchestratorNoCritical;
+
+  return [
+    t().orchestratorOverallRisk(label, overallScore, totalFindings, agents.length),
+    criticalLine,
+    '',
+    ...agents.map(a => `[${a.agentName.toUpperCase()}] ${a.summary}`),
+  ].join('\n');
+}
+
+function scoreToLabel(score: number): 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL' {
+  if (score >= 80) return 'CRITICAL';
+  if (score >= 60) return 'HIGH';
+  if (score >= 30) return 'MEDIUM';
+  return 'LOW';
+}

package/src/providers/base.ts

@@ -0,0 +1,16 @@
+export interface LLMMessage {
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+}
+
+export interface LLMResponse {
+  content: string;
+  inputTokens?: number;
+  outputTokens?: number;
+}
+
+export interface LLMProvider {
+  complete(messages: LLMMessage[], systemPrompt?: string, maxTokens?: number): Promise<LLMResponse>;
+  readonly name: string;
+  readonly model: string;
+}

package/src/providers/claude.ts

@@ -0,0 +1,36 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { LLMProvider, LLMMessage, LLMResponse } from './base';
+
+export class ClaudeProvider implements LLMProvider {
+  readonly name = 'claude';
+  readonly model: string;
+  private client: Anthropic;
+
+  constructor(apiKey: string, model: string = 'claude-sonnet-4-6') {
+    this.model = model;
+    this.client = new Anthropic({ apiKey });
+  }
+
+  async complete(messages: LLMMessage[], systemPrompt?: string, maxTokens: number = 4096): Promise<LLMResponse> {
+    const response = await this.client.messages.create({
+      model: this.model,
+      max_tokens: maxTokens,
+      system: systemPrompt,
+      messages: messages.map(m => ({
+        role: m.role === 'system' ? 'user' : m.role,
+        content: m.content,
+      })),
+    });
+
+    const content = response.content
+      .filter(b => b.type === 'text')
+      .map(b => (b as Anthropic.TextBlock).text)
+      .join('');
+
+    return {
+      content,
+      inputTokens: response.usage.input_tokens,
+      outputTokens: response.usage.output_tokens,
+    };
+  }
+}

package/src/providers/factory.ts

@@ -0,0 +1,84 @@
+import chalk from 'chalk';
+import { ResolvedConfig } from '../types';
+import { LLMProvider } from './base';
+import { ClaudeProvider } from './claude';
+import { OpenAIProvider } from './openai';
+import { GeminiProvider } from './gemini';
+import { MockProvider } from './mock';
+import { FallbackProvider } from './fallback';
+
+export function createProvider(config: ResolvedConfig): LLMProvider {
+  return createProviderFor(config, '__default__');
+}
+
+export function createProviderFor(config: ResolvedConfig, role: string): LLMProvider {
+  const spec = config.providers.agents[role];
+  const primary = spec
+    ? resolveSpec(config, spec)
+    : resolveNamed(config, config.providers.default);
+
+  const fallbackNames = config.providers.fallback;
+  if (fallbackNames.length === 0) return primary;
+
+  const chain: LLMProvider[] = [primary];
+  for (const name of fallbackNames) {
+    const candidate = tryResolveNamed(config, name);
+    if (candidate && !isSameProvider(candidate, primary)) {
+      chain.push(candidate);
+    }
+  }
+
+  if (chain.length === 1) return primary;
+
+  return new FallbackProvider(chain, (from, to) => {
+    console.log(chalk.yellow(`\n  ⚡ ${from} quota/rate limit — switching to ${to}`));
+  });
+}
+
+// Resolves "provider" or "provider/model" spec string
+function resolveSpec(config: ResolvedConfig, spec: string): LLMProvider {
+  const slash = spec.indexOf('/');
+  const providerName = slash === -1 ? spec : spec.slice(0, slash);
+  const model        = slash === -1 ? undefined : spec.slice(slash + 1);
+  return resolveNamed(config, providerName, model);
+}
+
+// Resolves a provider by name, with an optional model override
+function resolveNamed(config: ResolvedConfig, name: string, modelOverride?: string): LLMProvider {
+  if (name === 'claude') {
+    const apiKey = process.env[config.claude.api_key_env];
+    if (!apiKey) throw new Error(`Missing env var: ${config.claude.api_key_env}`);
+    return new ClaudeProvider(apiKey, modelOverride ?? config.claude.model);
+  }
+
+  if (name === 'openai') {
+    const apiKey = process.env[config.openai.api_key_env];
+    if (!apiKey) throw new Error(`Missing env var: ${config.openai.api_key_env}`);
+    return new OpenAIProvider(apiKey, modelOverride ?? config.openai.model);
+  }
+
+  if (name === 'gemini') {
+    const apiKey = process.env[config.gemini.api_key_env];
+    if (!apiKey) throw new Error(`Missing env var: ${config.gemini.api_key_env}`);
+    return new GeminiProvider(apiKey, modelOverride ?? config.gemini.model);
+  }
+
+  if (name === 'mock') return new MockProvider();
+
+  // Custom OpenAI-compatible provider
+  const custom = config.custom_providers[name];
+  if (custom) {
+    const apiKey = custom.api_key_env ? (process.env[custom.api_key_env] ?? '') : '';
+    return new OpenAIProvider(apiKey, modelOverride ?? custom.model, custom.base_url, name);
+  }
+
+  throw new Error(`Unknown provider: "${name}". Add it with: aiv config add-provider ${name} --base-url <url> --api-key-env <VAR> --model <model>`);
+}
+
+function tryResolveNamed(config: ResolvedConfig, name: string): LLMProvider | null {
+  try { return resolveNamed(config, name); } catch { return null; }
+}
+
+function isSameProvider(a: LLMProvider, b: LLMProvider): boolean {
+  return a.name === b.name && a.model === b.model;
+}

package/src/providers/fallback.ts

@@ -0,0 +1,47 @@
+import { LLMProvider, LLMMessage, LLMResponse } from './base';
+
+type FallbackCallback = (from: string, to: string) => void;
+
+export class FallbackProvider implements LLMProvider {
+  private index = 0;
+
+  constructor(
+    private readonly chain: LLMProvider[],
+    private readonly onFallback?: FallbackCallback,
+  ) {
+    if (chain.length === 0) throw new Error('FallbackProvider requires at least one provider');
+  }
+
+  get name(): string  { return this.chain[this.index].name; }
+  get model(): string { return this.chain[this.index].model; }
+
+  async complete(messages: LLMMessage[], systemPrompt?: string, maxTokens?: number): Promise<LLMResponse> {
+    for (let i = this.index; i < this.chain.length; i++) {
+      try {
+        const result = await this.chain[i].complete(messages, systemPrompt, maxTokens);
+        this.index = i;
+        return result;
+      } catch (e: unknown) {
+        if (!isRetriableError(e) || i + 1 >= this.chain.length) throw e;
+        this.onFallback?.(this.chain[i].name, this.chain[i + 1].name);
+        this.index = i + 1;
+      }
+    }
+    throw new Error('All providers in fallback chain exhausted');
+  }
+}
+
+function isRetriableError(e: unknown): boolean {
+  const status = (e as any)?.status ?? (e as any)?.statusCode ?? (e as any)?.httpStatus;
+  if (status === 429 || status === 529) return true;
+
+  const msg = e instanceof Error ? e.message.toLowerCase() : String(e).toLowerCase();
+  return (
+    msg.includes('rate_limit') ||
+    msg.includes('rate limit') ||
+    msg.includes('quota') ||
+    msg.includes('overloaded') ||
+    msg.includes('too many requests') ||
+    msg.includes('insufficient_quota')
+  );
+}

package/src/providers/gemini.ts

@@ -0,0 +1,58 @@
+import { LLMProvider, LLMMessage, LLMResponse } from './base';
+
+const GEMINI_BASE = 'https://generativelanguage.googleapis.com/v1beta/models';
+
+export class GeminiProvider implements LLMProvider {
+  readonly name = 'gemini';
+  readonly model: string;
+  private readonly apiKey: string;
+
+  constructor(apiKey: string, model: string = 'gemini-2.0-flash') {
+    this.apiKey  = apiKey;
+    this.model   = model;
+  }
+
+  async complete(messages: LLMMessage[], systemPrompt?: string, maxTokens: number = 4096): Promise<LLMResponse> {
+    const contents = messages
+      .filter(m => m.role !== 'system')
+      .map(m => ({
+        role: m.role === 'assistant' ? 'model' : 'user',
+        parts: [{ text: m.content }],
+      }));
+
+    const body: Record<string, unknown> = {
+      contents,
+      generationConfig: { maxOutputTokens: maxTokens },
+    };
+
+    if (systemPrompt) {
+      body['systemInstruction'] = { parts: [{ text: systemPrompt }] };
+    }
+
+    const url = `${GEMINI_BASE}/${this.model}:generateContent?key=${this.apiKey}`;
+    const { default: fetch } = await import('node-fetch');
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const err = await res.json() as any;
+      const status = res.status;
+      const msg = err?.error?.message ?? 'unknown error';
+      throw Object.assign(new Error(`Gemini API error (${status}): ${msg}`), { status });
+    }
+
+    const data = await res.json() as any;
+    const content = (data?.candidates?.[0]?.content?.parts ?? [])
+      .map((p: any) => p.text ?? '')
+      .join('');
+
+    return {
+      content,
+      inputTokens:  data?.usageMetadata?.promptTokenCount,
+      outputTokens: data?.usageMetadata?.candidatesTokenCount,
+    };
+  }
+}